docs(base): restructure skill routing and analysis guidance - #2320
Open
zgz2048 wants to merge 26 commits into
Open
docs(base): restructure skill routing and analysis guidance#2320zgz2048 wants to merge 26 commits into
zgz2048 wants to merge 26 commits into
Conversation
|
Note Reviews pausedIt 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 Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe PR updates Base shortcut payloads and hints, upgrades the lark-base skill to version 1.2.6, revises field, record, filtering, and analysis references, removes obsolete guidance and contract tests, and adds NDJSON dry-run pagination coverage. ChangesBase guidance alignment
Estimated code review effort: 3 (Moderate) | ~25 minutes Mergeability Score: ⚪ Minimal · up to The change primarily restructures guidance while preserving the existing public shortcuts, and no actionable merge-blocking risk remains after normal checks and review. Possibly related PRs
Suggested labels: Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
github-actions
Bot
added
domain/base
kongenpei
previously approved these changes
Aug 12, 2026
zgz2048
marked this pull request as ready for review
August 12, 2026 12:24
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 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 `@skills/lark-base/references/lark-base-data-analysis-sop.md`:
- Around line 63-65: Update the manifest reuse guidance in the batch extraction
workflow to always compare each manifest’s rev with the current table rev
whenever freshness affects correctness, rather than relying on elapsed time or
write frequency. Re-export the table when the revisions differ; if best-effort
reuse remains permitted, explicitly state that the reused result may be stale.
In `@skills/lark-base/references/lark-base-field-json.md`:
- Around line 431-436: 更新“+field-update”说明，明确完整 PUT
仅回写更新接口支持的可写属性；使用“+field-get”读取定义后，排除仅创建时支持的 dynamic_options_source
及其他只读属性，不要将这些字段传入更新请求。
In `@skills/lark-base/references/lark-base-field-update.md`:
- Around line 120-125: Update the blacklist exception guidance in the
field-update documentation to allow exceptions only for platform-explicitly
supported scenarios, while keeping blacklist restrictions effective for empty
columns and user-accepted data loss. Explicitly exclude link-type changes and
dynamic/static option-source switches from all exceptions.
In `@skills/lark-base/references/lark-base-record-batch-create.md`:
- Around line 54-58: Update the batch-create examples associated with the
visible status field `"状态":"Open"` so status CellValues use the established
array-valued shape, matching the shortcut help and regression-test contract.
Apply the correction to both occurrences around the examples near Lines 16 and
40, without changing unrelated fields or CLI behavior.
🪄 Autofix
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: 865d670c-51fb-467d-9ef1-535318520917
📒 Files selected for processing (19)
shortcuts/base/base_execute_test.goshortcuts/base/base_resolve.goshortcuts/base/base_resolve_test.goshortcuts/base/base_shortcuts_test.goshortcuts/base/base_skill_contract_test.goshortcuts/base/data_query_guide_contract_test.goshortcuts/base/field_create.goshortcuts/base/record_batch_create.goshortcuts/base/record_upsert.goskills/lark-base/SKILL.mdskills/lark-base/references/lark-base-cell-value.mdskills/lark-base/references/lark-base-data-analysis-sop.mdskills/lark-base/references/lark-base-field-create.mdskills/lark-base/references/lark-base-field-json.mdskills/lark-base/references/lark-base-field-update.mdskills/lark-base/references/lark-base-filter-condition.mdskills/lark-base/references/lark-base-record-batch-create.mdskills/lark-base/references/lark-base-record-batch-update.mdskills/lark-base/references/lark-base-record-upsert.md
💤 Files with no reviewable changes (4)
- skills/lark-base/references/lark-base-record-upsert.md
- shortcuts/base/data_query_guide_contract_test.go
- shortcuts/base/base_skill_contract_test.go
- shortcuts/base/base_execute_test.go
Comment on lines
120
to
+125
| 只有在**整列数据丢失可接受**时，才允许对黑名单场景例外执行。 | ||
|
|
||
| - `EmptyColumn`: 该列为空 | ||
| - `FreshTableInit`: 新建空表初始化 | ||
| - `PrimaryFieldBootstrap`: 主列不能删，只能更新完成初始化 | ||
| - `ExplicitLossAccepted`: 用户明确接受整列数据丢失 | ||
| 1. 该列为空。 | ||
| 2. 正在初始化新建的空表。 | ||
| 3. 主字段不能删除，需要通过更新完成初始化。 | ||
| 4. 用户明确接受整列数据丢失。 |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- target excerpt ---'
sed -n '90,140p' skills/lark-base/references/lark-base-field-update.md
printf '%s\n' '--- related guidance and references ---'
rg -n -C 3 '黑名单|link|动态|静态|选项来源|整列数据|数据丢失|字段类型|转换|CLI' \
skills/lark-base/SKILL.md skills/lark-base/references \
2>/dev/null | head -n 300
printf '%s\n' '--- files ---'
git ls-files 'skills/lark-base/**'Repository: larksuite/cli
Length of output: 30299
🏁 Script executed:
#!/bin/bash
set -eu
python3 - <<'PY'
from pathlib import Path
field_update = Path("skills/lark-base/references/lark-base-field-update.md").read_text()
field_json = Path("skills/lark-base/references/lark-base-field-json.md").read_text()
checks = {
"field-update declares link as blacklist": "`link` 类型变更" in field_update,
"field-update declares option-source changes as blacklist": "动态 / 静态选项来源切换" in field_update,
"field-update grants broad blacklist exception": "允许对黑名单场景例外执行" in field_update,
"field-json blocks link conversion": "link` 不允许转换为其他类型，其他类型也不能转换为 `link`" in field_json,
"field-json disallows dynamic source on update": "dynamic_options_source` 仅创建支持；更新已有字段时不要传" in field_json,
}
for label, result in checks.items():
print(f"{label}: {'PASS' if result else 'FAIL'}")
print("\n--- relevant field-update lines ---")
for number, line in enumerate(field_update.splitlines(), 1):
if 105 <= number <= 130:
print(f"{number}: {line}")
print("\n--- relevant field-json lines ---")
for number, line in enumerate(field_json.splitlines(), 1):
if 230 <= number <= 242 or 359 <= number <= 364:
print(f"{number}: {line}")
PY
printf '%s\n' '--- file diff summary ---'
git diff --stat -- skills/lark-base/references/lark-base-field-update.md
printf '%s\n' '--- target file diff ---'
git diff -- skills/lark-base/references/lark-base-field-update.md | sed -n '1,180p'Repository: larksuite/cli
Length of output: 1640
保持黑名单限制有效。
空列或用户接受数据丢失不能覆盖不支持的转换。仅允许平台明确支持的场景例外，并明确排除 link 类型变更和动态/静态选项来源切换。
🤖 Prompt for 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.
In `@skills/lark-base/references/lark-base-field-update.md` around lines 120 -
125, Update the blacklist exception guidance in the field-update documentation
to allow exceptions only for platform-explicitly supported scenarios, while
keeping blacklist restrictions effective for empty columns and user-accepted
data loss. Explicitly exclude link-type changes and dynamic/static option-source
switches from all exceptions.
Comment on lines
+54
to
+58
| - 单次最多 200 条；`1254104` 表示超过单批上限，拆成多个批次。 | ||
| - `1254045` 表示字段不存在，重新 `+field-list` 后使用真实字段名或 `field_id`。 | ||
| - `1254015` 表示 CellValue 类型不匹配，按真实 Field schema 和 CellValue 规范修正。 | ||
| - 返回 `ignored_fields` / `READONLY` 时，从普通 Record 写入中移除 Formula、Lookup、系统字段和自动编号等只读字段。 | ||
| - 同一 Table 连续批量写入使用串行执行；`1254291` 表示并发写冲突，短暂等待后重试当前批次。 |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Update the batch-create examples with the new CellValue shape.
The shortcut help uses array-valued status cells, but this reference still shows "状态":"Open" at Line 16 and Line 40. These status examples can cause agents to submit the wrong CellValue shape. Change them to array values, or rename the field to make it explicitly a text example.
As per coding guidelines, “Preserve established CLI behavior, tests, lint, CI, output contracts, and public APIs unless a breaking change is explicitly requested.” The supplied shortcut help and regression tests establish the array-valued select contract.
Proposed reference example fix
- --json '{"create_records":[{"标题":"任务 A","状态":"Open"},{"标题":"任务 B","状态":"Done"}]}'
+ --json '{"create_records":[{"标题":"任务 A","状态":["Open"]},{"标题":"任务 B","状态":["Done"]}]}'
-{"create_records":[{"标题":"任务 A","状态":"Open"},{"标题":"任务 B","状态":"Done"}]}
+{"create_records":[{"标题":"任务 A","状态":["Open"]},{"标题":"任务 B","状态":["Done"]}]}🤖 Prompt for 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.
In `@skills/lark-base/references/lark-base-record-batch-create.md` around lines 54
- 58, Update the batch-create examples associated with the visible status field
`"状态":"Open"` so status CellValues use the established array-valued shape,
matching the shortcut help and regression-test contract. Apply the correction to
both occurrences around the examples near Lines 16 and 40, without changing
unrelated fields or CLI behavior.
Source: Coding guidelines
There was a problem hiding this comment.
♻️ Duplicate comments (1)
skills/lark-base/references/lark-base-field-json.md (1)
431-436: 🗄️ Data Integrity & Integration | 🟠 MajorExclude creation-only and UI-only properties from the full PUT.
The
+field-updateguidance must limit full write-back to properties supported by the update API. This page states thatdynamic_options_sourceis creation-only at Line 240 and that several properties are UI-only at Lines 241 and 339. Explicitly exclude those properties from the read-modify-write payload. Otherwise, the documented workflow can produce rejected update requests or inconsistent field definitions.🤖 Prompt for 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. In `@skills/lark-base/references/lark-base-field-json.md` around lines 431 - 436, Update the +field-update guidance to exclude creation-only dynamic_options_source and the UI-only properties identified in the field documentation from the full PUT payload. In the read-modify-write workflow, retain only properties supported by the update API while preserving the existing supported field-definition attributes and --yes requirement.
🤖 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.
Duplicate comments:
In `@skills/lark-base/references/lark-base-field-json.md`:
- Around line 431-436: Update the +field-update guidance to exclude
creation-only dynamic_options_source and the UI-only properties identified in
the field documentation from the full PUT payload. In the read-modify-write
workflow, retain only properties supported by the update API while preserving
the existing supported field-definition attributes and --yes requirement.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 660612ae-868a-4971-8160-51e84fbf22a5
📒 Files selected for processing (2)
skills/lark-base/references/lark-base-field-json.mdskills/lark-base/references/lark-base-field-update.md
🚧 Files skipped from review as they are similar to previous changes (1)
- skills/lark-base/references/lark-base-field-update.md
…ommon-fewshots # Conflicts: # skills/lark-base/references/lark-base-filter-condition.md
🚀 PR Preview Install Guide🧰 CLI updatenpm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@181bb9d081469c209bd1429fb1e6d21c899d1c1d🧩 Skill updatenpx skills add zgz2048/cli#codex/base-filter-common-fewshots -y -g |
There was a problem hiding this comment.
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/base_dryrun_ops_test.go`:
- Around line 134-145: Add self-contained CLI-level dry-run E2E cases in
TestDryRunRecordOps for both NDJSON record-list and record-search paths, rather
than invoking dryRunRecordList or dryRunRecordSearch directly. Exercise shortcut
mounting, validation, and the CLI dry-run envelope while preserving assertions
for the expected endpoint and NDJSON query parameters.
🪄 Autofix
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: 7c250195-3c89-4a1d-9b1d-2b61a2b81f55
📒 Files selected for processing (2)
shortcuts/base/base_dryrun_ops_test.goshortcuts/base/record_ops.go
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
base-block-list, typed NDJSON, predicate pushdown,revreuse, jq/Python selection, and explicit NULL semanticsrecord-upsertshortcut available through its own helpWhy
The previous entry skill was a flat command catalog with important Base concepts and routing rules spread across references. Agents frequently over-read documentation, selected legacy single-record writes, confused Base blocks with dashboard blocks, repeated artifact checks, or treated low-frequency field details as the primary workflow.
This change makes the entry skill a compact resource map, keeps module-specific contracts in their references, and preserves the Base-specific facts that a database/data-analysis model cannot infer from generic SQL or DataFrame knowledge.
User and agent impact
Validation
git diff --checkgo test ./shortcuts/base/... ./internal/skillcontent/...Experimental findings incorporated
record_idguaranteesSummary by CodeRabbit