docs(base): reduce filter and update retry loops by Neseria · Pull Request #1879 · larksuite/cli

Neseria · 2026-07-14T07:41:22Z

Background

Base evaluation traces show two avoidable error → lookup → retry loops:

Record/view filters can mix up the tuple DSL with +data-query, or use an array for a scalar field value.
Some update commands require the current complete configuration. For example, field update rejects a name-only payload with 800010701 Invalid discriminator value; blindly adding only type can still lose options or style.

The second issue is not solved by making every update full-state: Base commands have different full-update and partial-update semantics. Agents need one command-aware rule instead of one request-shape patch per failure.

Changes

Sharpen the existing record/view filter guidance:
- confirm the real field type and stored values before filtering;
- keep tuple filter JSON distinct from the +data-query object DSL;
- use scalar or array values according to the real field type.
Add two concise top-level rules for Base updates:
- when a command requires complete input, read and complete the current configuration, change only what the user requested, then submit the shape required by that command;
- when a command supports partial modification, submit only the changed items;
- use the write response to confirm success, and read back only when that response is insufficient or the task explicitly requires verification.
Route Invalid discriminator value recovery through the same complete-submission rule instead of telling agents to patch only the missing type.

Why Skill-only

This is the smallest change that fixes the decision error at its source. It applies across resource types without changing CLI command semantics, adding hidden network requests, or requiring a bitable-mcp deployment. A backend field PATCH, automatic CLI retry, or field-specific type hint would solve only the current trace and could still lose nested configuration.

Validation

Real API contract probes:
- name-only field update reproduced 800010701;
- submitting the current complete field configuration with only the requested name change succeeded and preserved the remaining configuration.
15 isolated real-API runs with fresh SubAgents and Base copies, all using the candidate Skill version 1.2.3:
- _050: 5/5 final pass, zero 800010701;
- _035: 5/5 final pass, all five views created from scratch, zero filter value-shape errors;
- _032: 5/5 final pass, only the three Open/High targets changed.
Captured all 134 CLI commands with stdout, stderr, and exit code. Seven intermediate local parameter/shell errors were retained and corrected; there were no PATH exit 127 failures.
node scripts/skill-format-check/index.js
go test ./internal/qualitygate/skillscan/...
git diff --check

Summary by CodeRabbit

Documentation
- Updated the skill metadata version to 1.2.3.
- Expanded “pre-write rules” and recovery guidance, including when a full corrected re-submission is required (e.g., missing required type discriminator) and improved instructions for handling validation errors for array/object mismatches.
- Improved view filter configuration guidance: verify field type and real enum values via field/record list commands, clarify the shared tuple DSL with --filter-json, and specify that scalar fields require scalar value (not arrays).

Eval traces show the Base filter/view chain loses time to avoidable error->lookup->retry loops: - record/view --filter-json (tuple [[f,op,v]]) gets confused with +data-query's object filters ({field_name,operator,value}) -> 800010701 - scalar fields (text/number) get array-wrapped values -> 800010507 - agents guess a field is select from its name, or guess enum values in Chinese when stored values are English -> 0 hits then retry Add a top-of-doc section to the tuple-DSL SSOT (value shape by field type, check field type first, don't confuse with data-query, use real stored values), a reciprocal warning in data-query, and two recovery rows in SKILL.md. Flag-level details (--limit vs --page-size) are left to command --help per the skill's stated design.

coderabbitai · 2026-07-14T07:41:30Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e2686bc1-f9e8-4f2d-bf2d-c3077d2efed7

📥 Commits

Reviewing files that changed from the base of the PR and between 625a0fd and 0e66827.

📒 Files selected for processing (1)

skills/lark-base/SKILL.md

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

skills/lark-base/SKILL.md

📝 Walkthrough

Walkthrough

Updated Lark Base skill documentation to version 1.2.3, adding recovery guidance for missing field discriminators and clarifying filter syntax, field-type discovery, and scalar filter values.

Changes

Lark Base documentation

Layer / File(s)	Summary
Write and recovery guidance `skills/lark-base/SKILL.md`	Updates the skill version and documents configuration rereads and corrected resubmission for missing `type` discriminator errors.
Filter construction guidance `skills/lark-base/references/lark-base-view-set-filter.md`	Clarifies field inspection, shared tuple filter syntax, and scalar values for scalar fields.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

larksuite/cli#374: Related updates to error-recovery guidance in the same documentation file.

Suggested reviewers: kongenpei

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main doc change: reducing filter mistakes and retry loops in Base skills.
Description check	✅ Passed	The description is detailed and covers motivation, changes, rationale, and validation, though it does not follow the template headings exactly.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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

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

…rfit examples Address review feedback on the first pass: - remove the added top-level '## 0 …先读' section — it duplicated §3 (per-type value rules) and §7 (易错点), and its examples (状态=="Open", 工时>=3.5) overfit the eval case and even clashed with §3's own 状态-as-select example. - instead sharpen what already exists: §7 names the shared commands and the data-query object shape to avoid; §6 gets one process rule (confirm field type / real values first); all example-free and principle-based. - revert the data-query.md note (wrong direction; the confusion is fixed at the record/view tuple-DSL SSOT). - slim the SKILL.md recovery rows to terse, message-keyed, reference-pointing entries matching the table's style.

CLAassistant · 2026-07-14T09:40:43Z

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

github-actions · 2026-07-17T03:14:06Z

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@0e66827fd60783750f33f36adc76802a6044f7d9

🧩 Skill update

npx skills add Neseria/cli#worktree-lark-base-filter-guidance -y -g

* docs(base): clarify complete and partial updates Consolidate the update rule introduced in #1879 and make the command-contract boundary explicit. Full-update commands must use trusted current configuration for the first actual request, while delta commands should send the smallest legal payload. * docs(base): clarify full-update state preservation Address review feedback by requiring unchanged writable configuration to remain intact, except when the requested update makes a setting inapplicable. * docs(base): strengthen update contract guidance

github-actions Bot added domain/base PR touches the base domain size/M Single-domain feat or fix with limited business impact labels Jul 14, 2026

github-actions Bot added size/L Large or sensitive change across domains or core paths and removed size/M Single-domain feat or fix with limited business impact labels Jul 15, 2026

Neseria changed the title ~~docs(base): disambiguate filter DSL & value shape to cut Base retry loops~~ docs(base): reduce filter and update retry loops Jul 15, 2026

Neseria force-pushed the worktree-lark-base-filter-guidance branch from e79473e to 1350662 Compare July 15, 2026 08:36

github-actions Bot added size/M Single-domain feat or fix with limited business impact and removed size/L Large or sensitive change across domains or core paths labels Jul 15, 2026

docs(base): clarify full and partial update guidance

625a0fd

Neseria force-pushed the worktree-lark-base-filter-guidance branch from 1350662 to 625a0fd Compare July 16, 2026 03:50

Neseria marked this pull request as ready for review July 17, 2026 03:05

docs(base): clarify partial update payload guidance

0e66827

Neseria force-pushed the worktree-lark-base-filter-guidance branch from 291b508 to 0e66827 Compare July 17, 2026 03:26

coderabbitai Bot mentioned this pull request Jul 17, 2026

docs(base): enforce complete field update #1937

Open

3 tasks

zhouyue-bytedance approved these changes Jul 20, 2026

View reviewed changes

zhouyue-bytedance merged commit 7b98994 into larksuite:main Jul 20, 2026
36 of 37 checks passed

liangshuo-1 mentioned this pull request Jul 20, 2026

chore: release v1.0.73 #1971

Merged

3 tasks

huarenmin13 mentioned this pull request Jul 21, 2026

docs(base): clarify complete and partial updates #1993

Merged

8 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(base): reduce filter and update retry loops#1879

docs(base): reduce filter and update retry loops#1879
zhouyue-bytedance merged 4 commits into
larksuite:mainfrom
Neseria:worktree-lark-base-filter-guidance

Neseria commented Jul 14, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

CLAassistant commented Jul 14, 2026

Uh oh!

github-actions Bot commented Jul 17, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Uh oh!

Conversation

Neseria commented Jul 14, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Background

Changes

Why Skill-only

Validation

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

CLAassistant commented Jul 14, 2026

Uh oh!

github-actions Bot commented Jul 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🚀 PR Preview Install Guide

🧰 CLI update

🧩 Skill update

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Neseria commented Jul 14, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 14, 2026 •

edited

Loading

github-actions Bot commented Jul 17, 2026 •

edited

Loading