fix(base): improve field creation and query guidance

[huarenmin13]

Summary

Improve Base agent guidance for recurring field/query failures and remove the batch-create latency regression exposed by the new array guidance.

• make the existing batch field-create capability discoverable in command help and the delivered Skill;
• select field types from explicit stored-value requirements and user semantics, using names and purposes only as confirmation clues;
• stop unsupported derived/automatic behavior instead of creating a plain storage placeholder;
• add a compact, generic quick reference for common +data-query filter values;
• keep same-table field writes sequential without sleeping one full second after every successful request;
• bound large batch response/context size through explicit --jq, skip unnecessary simple-text references/readbacks, and avoid deterministic chunking, quoting, and pagination retries;
• present typed errors before copying them into partial-failure stdout, preserve recovery extensions, and prevent extension keys from rewriting the batch ledger;
• distinguish unchanged automatic retries from resubmissions after recovery, and classify Base write conflict 1254291 as retryable.

Changes

• Document object-or-array input, ordered partial-failure semantics, and contract-preserving full batch success responses for +field-create.
• Add a general field-type selection invariant that keeps formatting, derived fields, relations, and automation distinct while treating names and business purposes only as confirmation clues.
• Add a terminal capability boundary: if documented capabilities cannot implement the requested behavior, do not probe, create a placeholder, or claim completion; report the boundary and alternatives.
• Add common select, datetime, and empty-value filter shapes to the data-query quick guide.
• Pace batch field creation with a 500ms minimum interval between request starts; request latency counts toward the interval, while serialization and partial-failure output stay unchanged.
• Keep one array per table when it fits the caller timeout, and guide generated arrays toward --json @file or argv-safe invocation instead of fixed-size chunks or double-escaped shell substitutions.
• For large successful arrays, project stdout to created / total / next-step fields while preserving the complete partial-failure envelope; next_step:done stops default field-list/get readback.
• Let one or more minimal {name,type:text} fields use command help as a fast path; other types/properties still require the field JSON SSOT, and formula/lookup keep their mandatory guides.
• Keep the compatible +field-list default of 100; large-schema verification can explicitly request --limit 200 --jq ....
• Route field-create partial failures through Runtime.PresentError before copying message, typed metadata, hints, and permission extensions into the result payload.
• Gate only unchanged automatic retries on retryable:true; non-retryable items may be resubmitted after following their authorization or input-correction hint. Register 1254291 as api/conflict/retryable:true with the canonical wait guidance.
• Lock the guidance and pacing contracts with focused tests while keeping the full query DSL in its existing SSOT; the query-guide test rejects real case artifacts rather than blacklisting an old scenario template.

Attribution and live A/B

The evaluation report's 150-field case (base_table_032) took 197.444s on baseline and 347.016s on the PR version: a 149.572s regression. This PR makes array field creation the recommended path, which activates a pre-existing fixed one-second delay before each field after the first.

Using fresh, equivalent Bases and the same 150-text-field payload:

Version	Wall time	Create result	Readback total
PR head 4d1fb9a0	269.64s	150/150	154
Patched f22e5b0d	118.80s	150/150	154
Throttle + review head 1eac5d23	103.58s	150/150	154

The first patched run removed 150.84s (-55.9%); the 1eac5d23 run was 166.06s faster than the old head (-61.6%). All runs produced identical create/readback counts. This directly closes the identified PR-attributable fixed-wait regression.

I also reran the original base_table_032 prompt through the agent with GPT-5.4, runs=1, jobs=1, separate fresh equivalent Bases, and the then-current merged main as the baseline:

Metric	Evaluated main 7363eb54	Evaluated PR bcb3ceb7	Delta
Raw token usage	452,702	425,960	-5.9%
Weighted token usage	113,720.2	116,248.4	+2.2%
Candidate duration	265.765s	214.543s	-19.3%
Peak context tokens	47,266	40,995	-13.3%
Output tokens	3,259	2,178	-33.2%
Tool calls	30	24	-20.0%
Turns	11	11	unchanged
Independent field readback	154	154	identical

The final current trace used one array call, skipped the two field reference documents on the simple-text fast path, bounded the create result to 334 characters, bounded the optional readback result to 158 characters, and completed without pagination or quoting retries. The weighted-token point estimate moved +2.2% while raw tokens, peak context, output tokens, and tool calls all fell; the two runs had different cache-hit rates (87.8% vs 84.1%), so this isolated weighted movement does not support PR causality. Earlier current-tree trials exposed and then closed two attributable token risks: a 14.6KB expanded batch result and a 27.9KB unfiltered field-list readback.

The agent A/B above evaluated bcb3ceb7. Current head 6680508e restores the existing full-success response contract and field-list default of 100, preserves presented typed-error extensions behind collision-safe batch-ledger aliases, makes same-name handling command-specific, and documents caller-timeout reconciliation. The evaluated success trace explicitly projected both field-create and field-list output with --jq and never entered partial failure, so these compatibility fixes do not change that trajectory; this preserves the measured mechanism without claiming that the new head itself has been rerun at agent level.

The branch merge-base remains upstream main 875d20a2. A clean merge-tree against latest main 426f80fd passes Base normal and race tests, and the current branch passes the exact CI unit-package race command. Latest main itself currently reproduces an unrelated +messages-search affordance-example failure, so this description does not claim a green latest-main full-repository suite.

The current run's control-plane prepareBase/status callbacks warned, but local result.json, trace completion, and independent Base readback were all present.

This is targeted causal evidence for the changed field-create path, not a replacement for a refreshed 124-case aggregate evaluation.

Review follow-up

• Batch-create full success now returns the original server fields again; only partial-failure created items keep compact id / name / type identity.
• +field-list now defaults to 100 again while retaining the 1-200 range, --page-size alias, and explicit --limit 200 support.
• Field-create partial failures now present typed errors before copying them into stdout: visible recovery includes base:field:create, concealed distributions retain the scope without exposing auth login, and typed recovery extensions such as challenge_url survive. Colliding extension keys cannot overwrite index, status, field, or error in the batch ledger.
• Partial-failure retry guidance now allows authorization/input recovery before resubmission while reserving unchanged automatic retry for retryable:true; Base error 1254291 now carries api/conflict/retryable:true and canonical wait guidance. Caller-timeout recovery reads back before resubmission and marks same-name hits as ambiguous when no pre-write snapshot exists.
• Global same-name guidance now defers to each command or guide; the simple-text help fast path is an explicit exception to the field-JSON read rule, and field type selection no longer rejects business semantics as a confirmation clue.
• base_table_028: current guidance now has an explicit unsupported terminal state and forbids plain storage placeholders or false completion. The replacement tip remains 36 English words, equal to the prior tip, and contains no translation-specific wording. This current-head behavior still needs an agent benchmark before claiming the original task is fixed.
• base_table_087: removed the contract test's blacklist of the old date-plus-status template and placeholder names. The remaining contract checks atomic Condition.value rules, the DSL SSOT link, guide size, and absence of real case IDs/Base URLs.

Test Plan

• Targeted throttle contract tests
• Targeted full-success/partial-failure output and field-list default contract tests
• Targeted visible/concealed partial-failure error presentation tests
• Targeted security-challenge extension and custom typed-error ledger-collision tests
• Targeted authorization-recovery resubmission contract test
• Targeted 1254291 retryable write-conflict partial-failure test
• go test ./shortcuts/base -count=1
• go test -race ./shortcuts/base -count=1
• Latest-main merged-tree Base normal/race tests; unrelated latest-main IM affordance failure independently reproduced
• Array field-create CLI E2E
• make unit-test
• make build
• go vet ./...
• go mod tidy leaves go.mod and go.sum unchanged
• CI-equivalent golangci-lint reports 0 issues
• Source-contract lint and lint module tests
• Current-branch binary help and embedded-Skill reads expose the new guidance
• Live old-head, patched, and current-head A/B over 150 serial field creates
• Original case032 prompt, model, and fresh-fixture evaluated-main/PR agent A/B with local traces and independent 154-field readback

Earlier benchmark context

Three normalized runs were completed over Base evaluation cases 096, 028, and 087 on pre-generalization head c88ec548. Case 096 exercised one-call batch creation of 10 fields in 2/3 runs; the third run found copied target fields already present and skipped the requested 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. The generalized 028 terminal boundary and 087 atomic guide at current head have not yet received the corresponding agent-level benchmark.

Related Issues

• None

改动范围: Base field-create 指南、批量节流、显式 jq 有界输出、field-list 兼容默认、部分失败错误呈现、恢复重提语义、1254291 冲突分类及对应契约测试
思考过程: 保留通用字段和查询规则及 case032 已验证收益路径，恢复既有输出和分页契约；把 retryable 限定为原样自动重试，并允许按 hint 修复后重提
改动原因: PR 必须至少优化 token、正确率或耗时之一且不引入可归因回退；本轮消除权限恢复与顶层提示冲突，并让既有写冲突等待规则获得结构化错误支持
Break Change: 否

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

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
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.
Title check	✅ Passed	The title clearly identifies the Base field-creation and query-guidance improvements covered by the pull request.
Description check	✅ Passed	The description includes all required sections and provides detailed scope, test results, benchmarks, follow-up items, and related-issue status.

✨ 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@6680508e9481b9b07d0a3727de278b14f69abe65

🧩 Skill update

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