fix(base): improve field creation and query guidance

[huarenmin13]

Summary

Improve Base agent guidance for three recurring failure modes without changing API request behavior.

• make the existing batch field-create capability discoverable in command help and the delivered Skill;
• select field types from stored values instead of purpose-specific field names;
• add a compact, generic quick reference for common +data-query filter values.

Changes

• Document object-or-array input, ordered partial-failure semantics, and single-versus-batch responses for +field-create.
• Add a general field-type selection invariant that keeps formatting, derived fields, relations, and automation distinct.
• Add common select, datetime, and empty-value filter shapes to the data-query quick guide.
• Lock all three guidance contracts with focused tests while keeping the full DSL in its existing SSOT.

Test Plan

• Targeted field-create and data-query guide contract tests
• go test ./shortcuts/base -count=1
• make unit-test
• make build
• go vet ./...
• go mod tidy leaves go.mod and go.sum unchanged
• golangci-lint run --new-from-rev=upstream/main reports 0 issues
• Current-branch binary help and embedded-Skill reads expose the new guidance
• Three benchmark runs over Base evaluation cases 096, 028, and 087 on pre-generalization head c88ec548

Benchmark result: three normalized runs completed. Case 096 exercised one-call batch creation of 10 fields in 2/3 runs; the third run found the copied target fields already present and skipped the requested new write. Case 087 returned the requested overdue count in 3/3 runs, using direct +data-query in 2/3 and a record-list fallback in 1/3. Case 028 did not produce automatic translation in any run: one unsupported type was rejected and two runs created plain-text placeholders. The whole-case grader was 4/9 in each run, with several broader newly created expectations also affected by pre-existing copied state. Case 087 guidance was subsequently reduced to generic Condition.value shapes in bfbe90db; that follow-up has not yet been benchmarked. This PR remains Draft pending follow-up on the unsupported translation intent and refreshed benchmark evidence.

Related Issues

• None

改动范围: Base field-create 帮助与 Skill 指南、data-query 快速指南，以及对应的契约测试
思考过程: 将三个已修复实验的最终有效规则合并到一个 public PR，保留通用表达并排除没有 benchmark 支撑的后续路由改动
改动原因: 统一验证批量字段创建、字段类型选择和常见查询过滤三类代理失败的修复效果
Break Change: 否

Co-authored-by: BASE Infra Harness ai@base-infra-harness.noreply.local
AI-SHA256: 513b23583ffc1911429df7bc6257eebcc023c8642a33734d3e0df61b326fb36f

Summary by CodeRabbit

• New Features
  • Expanded field creation to support creating one or more fields in a single request: --json now accepts either a single JSON object or a non-empty JSON array.
• Documentation
  • Refreshed the base data-query guide’s “Common filter values” with clearer Condition.value shapes and date/empty handling notes.
  • Updated field-create/reference docs (and quick-route entries) to cover multi-field --json usage and batch response/failure details.
• Bug Fixes
  • Improved batch create failure handling to return a structured partial-failure result (including per-item outcomes and retry guidance).
• Tests
  • Strengthened help/tips and markdown contract coverage for field-create and query guides.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

BaseFieldCreate now supports documenting and validating single or batch field creation, including structured partial-failure responses. Related references and skill rules were updated, while the data-query quick guide and its contract test now focus on common Condition.value shapes.

Changes

Field creation contract and guidance

Layer / File(s)	Summary
Field creation metadata and input contract shortcuts/base/field_create.go, shortcuts/base/base_shortcuts_test.go, shortcuts/base/references/lark-base-field-json.md	Help text, JSON usage, tips, and contract checks describe single objects or non-empty arrays and stored-value-based type selection.
Batch partial-failure handling shortcuts/base/field_ops.go, shortcuts/base/base_execute_test.go	Batch creation returns ordered created, failed, and not-attempted items with summary counts, structured error details, and retry guidance.
Batch creation and create semantics documentation skills/lark-base/SKILL.md, skills/lark-base/references/lark-base-field-create.md, shortcuts/base/base_skill_contract_test.go	References and routing documentation cover array input, sequential failure behavior, response shapes, and create-versus-reuse rules; contract tests validate consistency.

Data-query quick guide

Layer / File(s)	Summary
Condition value guide and contract validation skills/lark-base/references/lark-base-data-query-guide.md, shortcuts/base/data_query_guide_contract_test.go	The guide documents select, datetime, and empty-array Condition.value shapes; tests validate normalized content, size limits, and forbidden identifiers.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant FieldCreate
  participant FieldAPI
  CLI->>FieldCreate: Submit field object array
  FieldCreate->>FieldAPI: Create fields sequentially
  FieldAPI-->>FieldCreate: Success or API error
  FieldCreate-->>CLI: Return created, failed, and not-attempted results

Loading

Possibly related PRs

• larksuite/cli#1661: Directly relates to the JSON-array batch field creation and sequential execution paths updated here.

Suggested reviewers: liangshuo-1

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main changes: Base field creation and data-query guidance improvements.
Description check	✅ Passed	The description matches the required template with Summary, Changes, Test Plan, and Related Issues sections.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@shortcuts/base/data_query_guide_contract_test.go`:
- Around line 18-31: Expand the assertion list in the contract test around the
guide fixture to cover every newly added filter example: isLess,
isEmpty/isNotEmpty, value as an empty array, type 1, conditions, and the exact
["<status_value>"] shape. Keep the existing substring-based validation and add
one assertion for each required contract fragment so removal of any example
causes the test to fail.

In `@skills/lark-base/references/lark-base-field-create.md`:
- Line 46: Insert one blank line immediately after the arguments table in
lark-base-field-create.md and before the following heading, leaving the table
content unchanged so markdownlint MD058 is resolved.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4562f56b-1db3-4620-80f7-15c88607d2ce

📥 Commits

Reviewing files that changed from the base of the PR and between a575a8b and 9ba8ffa.

📒 Files selected for processing (6)

• shortcuts/base/base_shortcuts_test.go
• shortcuts/base/data_query_guide_contract_test.go
• shortcuts/base/field_create.go
• skills/lark-base/SKILL.md
• skills/lark-base/references/lark-base-data-query-guide.md
• skills/lark-base/references/lark-base-field-create.md

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@shortcuts/base/data_query_guide_contract_test.go`:
- Around line 42-51: Update the forbidden-content loop in the contract test to
search normalizedGuide instead of the raw guide, matching the positive checks
and ensuring forbidden phrases split by whitespace or Markdown line breaks are
detected.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8b8e8e8b-59bc-4c3c-ab2a-58a3fdf140a8

📥 Commits

Reviewing files that changed from the base of the PR and between c88ec54 and bfbe90d.

📒 Files selected for processing (2)

• shortcuts/base/data_query_guide_contract_test.go
• skills/lark-base/references/lark-base-data-query-guide.md

🚧 Files skipped from review as they are similar to previous changes (1)

• skills/lark-base/references/lark-base-data-query-guide.md

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@shortcuts/base/field_ops.go`:
- Around line 223-233: Preserve the underlying err when constructing the partial
failure in field_ops.go, passing it as the OutPartialFailure cause while
retaining the existing structured payload. In base_execute_test.go, replace the
display-string-only assertion with checks that errs.ProblemOf metadata includes
category, a non-empty subtype, code, log ID, and the original cause.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 7695c4d8-a2af-4837-a4b3-afe0a71f91e1

📥 Commits

Reviewing files that changed from the base of the PR and between db0506b and a1f350e.

📒 Files selected for processing (7)

• shortcuts/base/base_execute_test.go
• shortcuts/base/base_skill_contract_test.go
• shortcuts/base/data_query_guide_contract_test.go
• shortcuts/base/field_ops.go
• skills/lark-base/SKILL.md
• skills/lark-base/references/lark-base-field-create.md
• skills/lark-base/references/lark-base-field-json.md

🚧 Files skipped from review as they are similar to previous changes (2)

• skills/lark-base/references/lark-base-field-create.md
• skills/lark-base/SKILL.md

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@4d1fb9a0065b8d7c4c95aa2ab4b8c2efe40d85a8

🧩 Skill update

npx skills add huarenmin13/cli#codex/base-field-query-guidance -y -g