feat(mcp): bump lark-cli 1.0.69 + 参数契约层 + flag 类型修复#110
Merged
Conversation
📝 WalkthroughWalkthroughThe PR bumps the CLI version, improves generated-tool parsing and payload-schema extraction, adds runtime payload validation and error normalization, updates scope metadata, and revises extensive application, Drive, messaging, Sheets, document, and Whiteboard skill documentation. ChangesCLI catalog and runtime contracts
CLI scope and version metadata
Skill documentation contracts
Estimated code review effort: 5 (Critical) | ~120 minutes Sequence Diagram(s)sequenceDiagram
participant Client
participant Server
participant ServerLib
participant LarkCLI
Client->>Server: Call generated tool
Server->>ServerLib: Coerce and validate payload
Server->>LarkCLI: Execute validated command
LarkCLI-->>Server: Result or validation error
Server->>ServerLib: Strip notice or translate error
Server-->>Client: MCP response
Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 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 |
lark-cli >=1.0.60 的 affordance 把复合参数的 cobra type token 换成了示例
（`--sheets +table-put`、`--values [["alice",95]]`、`--range A1:Z200`、
`--border-styles { top: {...} }`、`--sort-keys [{"column":"x"}, ...]` 等），
不再是裸词 `string`。
flagTypeFromRest 原本靠白名单匹配 token：认不出就 fallback 成 boolean。于是
这些其实接收 JSON 字符串的 flag 全被标成 boolean，server.js 对 boolean 只推
开关名（`--sheets`）、把值丢掉，lark-cli 收到无值的 flag 报 unknown error。
波及 sheets / docs / mail / apps 共 39+ 个 flag，standalone lark_invoke 调用
（workbook-create 带 values/sheets、cells-set、csv-get、formula-verify 带
range 等）一律失败；batch-update 包裹子操作走的是另一条路径，所以能成——正是
用户观察到的规律。
改判定依据：cobra 用 2+ 空格把 type token 与描述对齐，boolean 名后直接是这段
2+ 空格间隙、没有 token。所以取“名后到首个 2+ 空格间隙”为 token（可含内部单
空格,覆盖多词示例）——存在即取值型（NUMBER token → number,其余 → string）,
不存在即 boolean。不再白名单化 token，从根上不受未来 affordance 措辞变化影响。
验证：42 个 parseFlags 单测全绿（新增 7 条覆盖示例 token 的各形态）；重建镜像后
39 个误判 flag 全部翻回 string，真 boolean（allow-sensitive/before/chapter/
head 等）不受影响；离线门禁 + 容器 smoke 均通过。
flagTypeFromRest 的失效模式是静默的:误判成 boolean 的取值 flag 会让 server.js 丢弃 agent 传的值,单测/smoke 全绿,只有真实调用才报 unknown error。在 runbook 校验清单和 to-pr 编排的 phase 3 各加一步:构建镜像后用 jq 扫描 generated-tools.json,凡 boolean flag 的描述携带 JSON/数组语义即 人工核对 --help;新 affordance 形态导致的误判是 hard stop,手工修 flagTypeFromRest 并补测试,不占修复预算。
测试暴露的两类 Agent 失败(参数传原生 object / 1D-vs-2D 维度错)根因都在
接口层:参数契约只以散文形式存在于 description,lark-cli 返回的结构化
validation 错误又被 isError:true 让 lenient 客户端(如 Quick)吞成
"Action failed with an unknown error.",Agent 拿不到自纠信息只能盲试。
构建期:
- extractPayloadSchemas:对声明 --print-schema 的命令逐 flag 提取上游内嵌
的 JSON Schema(维度/字段/枚举),存入 catalog payloadSchemas(1.0.69
共 25 个复合 flag);print-schema/flag-name 加入 HIDDEN_FLAGS
- translateFlagDescription:catalog description 去 CLI 化——剥 @file/stdin
提示,--flag→snake_case 参数名,lark-cli skills read→lark_get_skill,
引用等效 CLI 命令的句子删除;引号内数据字面量豁免。skills 层的"零 CLI
泄漏"invariant 由此延伸到 catalog 路径(全 catalog 复扫 leaks=0)
运行时:
- coerceFlagValue:string flag 收到 object/array 时 JSON.stringify(原
String() 会腐蚀成 "[object Object]"/逗号拼接,深入 lark-cli 才报错)
- validatePayload:spawn 前按嵌入 schema 做浅层校验(根类型 + 一层
items 维度,恰好覆盖两类实测错误),不合格返回 invalid_payload +
正确形状提示,isError:false(沿用 raw API params/data 校验先例)
- translateCliError:validation 类错误把本工具 flag 的 --kebab 引用译回
snake_case 参数名后以 isError:false 穿透;改写仅限 allowlist(本工具
真实 flag 集),回显用户数据里的 -- 序列(如 Excel 公式 --(a1:a10>5))
原样保留;auth/permission 路径不动
- stripCliNotice:剥掉 _notice.update("run: lark-cli update"),Agent 无
法执行终端命令,该提示在 pin 落后期间的每条响应里烧 token
- resolveSkillDomain:lark_get_skill 接受 docs→doc 等 service 名复数别名
(工具 namespace 是 lark_docs_*,domain 却叫 doc,Agent 按工具名推导
必猜错);unknown_domain/unknown_section/invalid_section 三个纠错响应
改 isError:false,对齐 unknown_tool 既有约定
- lark_discover:query 精确等于工具名时返回 payload_schemas(实测 Agent
自纠模式就是失败后按名重查);宽泛搜索只带 has_payload_schemas 标记
(schema 最大 ~70KB,不进 20 条结果列表)
文档:bump runbook 校验清单新增 CLI 泄漏扫描与 schema 提取计数两项,
to-pr 编排 phase 3 同步引用(均为静默失效点,离线门禁测不到)。
验证:255 单测全绿(新增 33);./scripts/test.sh + test-smoke-docker.sh
通过;重建镜像实测 25 个 payloadSchemas、cells 契约含 2D 维度、
description 零泄漏、print-schema 不再出现在 flags。
5 视角 Opus 交叉 review + 每项 2 怀疑者对抗验证,10 个发现确认 6 个,全部修复:
1. [critical] discover 精确查询 payload_schemas 永不下发:searchCatalog 按空白
切词,完整工具名是单 token,"lark" 前缀命中全部 409 个工具、打分并列,精确
目标挤不进 top-20 → exact===e 恒假(实测 0/23)。修复:findByName 命中时
强制置于结果首位。契约测试加 25 个 filler 工具复现打分稀释后锁定。
2. [critical] flagTypeFromRest 把 7 个真 boolean 误判为 string(回归):
1.0.69 的 cobra help 把 boolean 默认值渲染成 token(--skip-hidden false、
--highlight --highlight=false),新判定把它们当取值 flag,server 生成
--skip-hidden true 被 lark-cli 拒为位置参数。修复:裸 true/false token 和
--flag=true/false token 判 boolean;(default false) 无冒号守卫(实测冒号
形式 0 处、无冒号 569 处)。7 个 flag 逐一对真实 help 行验证翻回 boolean,
复合 flag 不受影响。
3. [major] stripCliNotice JSON round-trip 丢大整数精度(>2^53 的 id 被静默改
值):改为 string-aware 扫描器定位顶层 "_notice" 值区间,只重编码 lark-cli
自己的通知对象,其余字节原样透传;深层字面 "_notice"(用户数据)不受影响。
4. [minor] print-schema 改写残句("Deeply nested —;"):连接符并入删除范围。
5. [minor] 契约层接线无 server 级测试:server-runtime 新增 R9 组——真实 server
断言 1D payload 预检拦截(且不 spawn)、原生数组 stringify 后放行、validation
错误翻译+isError:false、成功响应剥 _notice。mock 新增 fail 模式与 spawn 计数。
被反驳的 4 项(payload_schema 单复数、单数 domain 别名、内部双空格 boolean、
architecture.md 措辞)按怀疑者论证不修,理由存档于 review 产物。
验证:./scripts/test.sh + test-smoke-docker.sh 全绿;重建镜像实测 7 个 flag
翻回 boolean、25 个 payloadSchemas 仍在、cells 保持 string。
ddpie
changed the title
ddpie
marked this pull request as ready for review
July 14, 2026 09:01
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 11
Note
Due to the large number of review comments, Critical, Major severity comments were prioritized as inline comments.
🟡 Minor comments (11)
docker/skills/lark-apps/references/lark-apps-get.md-16-18 (1)
16-18: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winAdd language identifiers to all fenced command examples.
docker/skills/lark-apps/references/lark-apps-get.md#L16-L18: use```bash.docker/skills/lark-drive/references/lark-drive-comment-location.md#L14-L15: use```bash.docker/skills/lark-drive/references/lark-drive-comment-location.md#L20-L21: use```bash.docker/skills/lark-drive/references/lark-drive-comments-guide.md#L21-L32: use```bash.docker/skills/lark-drive/references/lark-drive-export.md#L98-L104: use```bash.docker/skills/lark-drive/references/lark-drive-list-comments.md#L13-L15: use```bash.The markdown linter reports MD040 for these fences.
🤖 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 `@docker/skills/lark-apps/references/lark-apps-get.md` around lines 16 - 18, Annotate every affected fenced command example with the bash language identifier to satisfy MD040: update docker/skills/lark-apps/references/lark-apps-get.md lines 16-18, docker/skills/lark-drive/references/lark-drive-comment-location.md lines 14-15 and 20-21, docker/skills/lark-drive/references/lark-drive-comments-guide.md lines 21-32, docker/skills/lark-drive/references/lark-drive-export.md lines 98-104, and docker/skills/lark-drive/references/lark-drive-list-comments.md lines 13-15. No command content changes are needed.Source: Linters/SAST tools
docker/skills/lark-doc/references/lark-doc-mindnote.md-16-16 (1)
16-16: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winAdd a language identifier to the fenced code block.
Use a suitable fence such as
textorbashso Markdown tooling can validate and render the example consistently.🤖 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 `@docker/skills/lark-doc/references/lark-doc-mindnote.md` at line 16, Add a suitable language identifier, such as text or bash, to the fenced code block in the mindnote documentation while preserving its existing example content.Source: Linters/SAST tools
docker/skills/lark-apps/references/lark-apps-release-create.md-24-27 (1)
24-27: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winReconcile the synchronous deployment rule with the completion rule.
When
sync=truewaits for deployment and returnsstatus=finished, the following instruction requiringlark_apps_release_getbefore declaring deployment complete is contradictory. Clarify that polling is required only when the create response is asynchronous or not yetfinished.🤖 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 `@docker/skills/lark-apps/references/lark-apps-release-create.md` around lines 24 - 27, 调整发布状态处理说明：仅当创建响应为异步部署（sync=false 或缺失）或 status 尚未为 finished 时，才使用 lark_apps_release_get 按 20s 间隔轮询；sync=true 且直接返回 status=finished 时，应立即视为部署完成，无需再次轮询。docker/skills/lark-sheets/references/lark-sheets-changeset.md-87-87 (1)
87-87: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winSpecify a language for the fenced example.
Use
```text(or the appropriate language) instead of an untyped fence so markdownlint MD040 passes.🤖 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 `@docker/skills/lark-sheets/references/lark-sheets-changeset.md` at line 87, Update the fenced code example in the lark-sheets changeset documentation to specify an appropriate language, preferably text, so the markdownlint MD040 requirement is satisfied.Source: Linters/SAST tools
docker/skills/lark-sheets/references/lark-sheets-history.md-70-70 (1)
70-70: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winSpecify languages for all fenced examples.
Use
```text(or the appropriate language) for the three command examples so markdownlint MD040 passes.Also applies to: 83-83, 90-90
🤖 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 `@docker/skills/lark-sheets/references/lark-sheets-history.md` at line 70, Add an explicit language identifier to all three fenced command examples in the document, using text for each unless a more appropriate language applies, while preserving their command contents.Source: Linters/SAST tools
docker/skills/lark-sheets/references/lark-sheets-batch-update.md-157-157 (1)
157-157: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winFix the blank blockquote line.
Remove the standalone
>or attach the following text to the blockquote so markdownlint MD028 passes.🤖 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 `@docker/skills/lark-sheets/references/lark-sheets-batch-update.md` at line 157, Fix the blank blockquote line in the Markdown document by removing the standalone `>` or attaching the following text directly to the blockquote, ensuring the blockquote structure satisfies markdownlint MD028.Source: Linters/SAST tools
docker/skills/lark-sheets/references/lark-sheets-batch-update.md-148-149 (1)
148-149: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winUse the declared shortcut names in the example.
operations.shortcutis documented as the CLI shortcut name, but this example uses+dim-insert/+cells-set, which do not match the enum. Replace them withlark_sheets_dim_insert/lark_sheets_cells_setso copied requests validate.🤖 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 `@docker/skills/lark-sheets/references/lark-sheets-batch-update.md` around lines 148 - 149, Update the operations example to use the declared shortcut names: replace “+dim-insert” with “lark_sheets_dim_insert” and “+cells-set” with “lark_sheets_cells_set”, preserving the existing inputs and request structure.docker/skills/lark-sheets/references/lark-sheets-workbook.md-152-152 (1)
152-152: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winClarify the type semantics of
values.This description says values are “automatically identified” but also says dates/numbers become text. State explicitly that
valuesis untyped/text-oriented and that typed data must usesheets; otherwise callers may expect numeric/date preservation and silently lose types.🤖 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 `@docker/skills/lark-sheets/references/lark-sheets-workbook.md` at line 152, 更新文档中 values 字段的说明，明确其为无类型、面向文本的数据写入，日期和数字不会保留为对应类型而会写成文本；同时明确需要保留日期或数字类型时必须使用 sheets，避免继续表述为“自动识别”。docker/skills/lark-sheets/references/lark-sheets-range-operations.md-229-229 (1)
229-229: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winAdd a language identifier to the fenced example.
The code fence at Line 229 has no language tag and triggers MD040; use an appropriate identifier such as
textorpython.🤖 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 `@docker/skills/lark-sheets/references/lark-sheets-range-operations.md` at line 229, Update the fenced code example at the affected section of lark-sheets-range-operations.md to include an appropriate language identifier, such as text or python, while preserving the example content.Source: Linters/SAST tools
docker/skills/lark-sheets/references/lark-sheets-range-operations.md-202-203 (1)
202-203: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick winFix the broken blockquote formatting.
The blank line at Line 203 interrupts the blockquote and triggers MD028. Remove the blank line or prefix it with
>.🤖 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 `@docker/skills/lark-sheets/references/lark-sheets-range-operations.md` around lines 202 - 203, Fix the blockquote formatting around the warning beginning with “scope="all"” by removing the blank line that interrupts the blockquote or prefixing it with “>”, ensuring the entire warning remains a single valid blockquote and passes MD028.Source: Linters/SAST tools
docker/server.js-573-580 (1)
573-580: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
translateCliErrorallowlist omitspage-limitandformat.
executeRawApipushes--page-limit(Line 517) and--format(Line 518) as CLI flags, but the allowlist passed totranslateCliErroronly contains['params', 'data', 'page-all']. Avalidationerror from lark-cli referencing--page-limitor--formatwill pass through with raw CLI-speak instead of being rewritten to the MCP parameter name, defeating the self-correction contract for those two flags.🐛 Proposed fix
- const translated = translateCliError(message, ['params', 'data', 'page-all']); + const translated = translateCliError(message, ['params', 'data', 'page-all', 'page-limit', 'format']);🤖 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 `@docker/server.js` around lines 573 - 580, Update the translateCliError call in the executeRawApi validation-error handling to include the page-limit and format CLI flags in its allowlist alongside params, data, and page-all, so errors for all pushed flags are translated to MCP parameter names.
🧹 Nitpick comments (2)
docker/generate-tools.js (1)
117-117: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winStructured-logging guideline: use JSON, not a plain template string.
console.log(\Payload schemas extracted: ${schemaExtracted} composite flags`)doesn't follow the repo'sconsole.log(JSON.stringify({...}))` convention. Note the runbook (docs/skills/bump-lark-cli-to-pr.md lines 73-77) currently greps for this exact plain-text wording ("Payload schemas extracted: "), so switching to structured JSON here would also require updating that grep pattern.As per coding guidelines, "Use structured JSON logging via
console.log(JSON.stringify({...}))."♻️ Proposed fix
-console.log(`Payload schemas extracted: ${schemaExtracted} composite flags`); +console.log(JSON.stringify({ event: 'payload_schemas_extracted', count: schemaExtracted }));🤖 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 `@docker/generate-tools.js` at line 117, Update the schema extraction log in the generator to use the repository’s structured JSON convention via console.log(JSON.stringify(...)), preserving schemaExtracted as a clearly named field. Also update the runbook grep pattern that matches the current plain-text “Payload schemas extracted: <N>” output so it recognizes the new JSON format.Source: Coding guidelines
docker/server-lib.js (1)
294-379: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚖️ Poor tradeoffHand-rolled string/brace scanner for
_noticestripping.The custom scanner correctly preserves big integers by avoiding a full
JSON.parse/stringifyround-trip on the whole payload — traced through escape handling, depth tracking, and balanced-brace capture, and it matches all the new tests. It's inherently harder to maintain than a library-based approach (e.g.json-bigint) if lark-cli's notice shape changes again. Given the thorough test coverage already in place, this is a nice-to-have simplification rather than a blocker.🤖 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 `@docker/server-lib.js` around lines 294 - 379, Optionally simplify stripCliNotice by replacing the hand-rolled string/brace scanner with a maintained JSON library such as json-bigint, while preserving arbitrary-precision integers and restricting re-encoding to the top-level _notice value. Keep the existing behavior for removing update, retaining other notice keys, and returning the original output for unsupported or invalid shapes.
🤖 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 `@docker/skills/lark-apps/references/lark-apps-release-create.md`:
- Around line 24-27: Update the upstream skill sources for the affected Lark
documentation and release guidance, then regenerate the generated outputs rather
than editing them directly. Regenerate and commit the artifacts at
docker/skills/lark-apps/references/lark-apps-release-create.md (24-27),
docker/skills/lark-doc/SKILL.md (12),
docker/skills/lark-doc/references/lark-doc-fetch.md (22-24),
docker/skills/lark-doc/references/lark-doc-mindnote.md (12-25, 116-117, 130),
docker/skills/lark-doc/references/lark-doc-xml-extended-blocks.md (1-34),
docker/skills/lark-doc/references/lark-doc-xml.md (49-50), and
docker/skills/lark-drive/SKILL.md (22-23, 36, 78-85, 138); no direct edits are
required at these generated sites.
In `@docker/skills/lark-drive/references/lark-drive-export.md`:
- Around line 62-64: Document token as accepting only a bare token, keeping it
mutually exclusive with url. Update the token descriptions in
docker/skills/lark-drive/references/lark-drive-export.md:62-64 and
docker/skills/lark-drive/references/lark-drive-list-comments.md:51-53, while
preserving the existing requirement that doc_type is supplied for bare tokens.
In `@docker/skills/lark-im/SKILL.md`:
- Around line 37-44: Move the sender-name contract from
docker/skills/lark-im/SKILL.md lines 37-44, the reply idempotency-key constraint
from docker/skills/lark-im/references/lark-im-messages-reply.md line 183, and
the send idempotency-key constraint from
docker/skills/lark-im/references/lark-im-messages-send.md line 188 into their
generator/source-of-truth definitions. Regenerate all three skill artifacts so
the generated files contain these updates and are not manually edited.
In `@docker/skills/lark-sheets/references/lark-sheets-pivot-table.md`:
- Line 38: Update the pivot-table validation guidance around
lark_sheets_pivot_list so Loading is treated as a transient state, not a
terminal failure. Restrict delete-and-recreate instructions to terminal
error_state values such as Cover and Shrink; for Loading, poll or retry
lark_sheets_pivot_list and re-read info before deciding recovery.
In `@docker/skills/lark-sheets/references/lark-sheets-range-operations.md`:
- Around line 125-137: Align the XOR metadata and descriptions for
lark_sheets_rows_resize and lark_sheets_cols_resize so pixel mode consistently
permits height with type="pixel" and width with type="pixel", while
standard/auto types remain mutually exclusive with the pixel parameters. Ensure
the tables and the referenced guidance at line 275 state the same contract
without ambiguity.
In `@docker/skills/lark-sheets/references/lark-sheets-visual-standards.md`:
- Around line 158-159: Update the Step 3 guidance to separate
lark_sheets_cells_merge batching from lark_sheets_cells_unmerge execution: keep
merge operations grouped with lark_sheets_batch_update, while documenting
unmerge as a single direct large-range call that is not split into batches.
In `@docker/skills/lark-sheets/references/lark-sheets-workbook.md`:
- Around line 392-393: The workbook guidance incorrectly recommends
lark_sheets_sheet_copy for importing local files or datasets. Update the
documented workflow to create or copy a destination sheet only when appropriate,
then write the local data into that sheet using the relevant lark_sheets_cells_*
operations; do not present sheet_copy as the import mechanism.
In `@docker/skills/lark-sheets/references/lark-sheets-write-cells.md`:
- Around line 46-47: Update the identifier-format guidance in this document so
order numbers, identity numbers, and document IDs use only string/object types
with number_format:"@". Remove "0" as an allowed safe format for these
identifier-like fields, while retaining it only for genuinely numeric
quantities.
- Around line 94-95: Update the documented two-step content-and-style workflow
to avoid using copy_to_range as a style-only operation, since it also copies
template values and formulas. Use lark_sheets_cells_set_style or batch styling
after writing values, or perform the copy before final values are written, while
preserving numeric data types.
In `@docker/skills/lark-sheets/SKILL.md`:
- Around line 29-34: Update the “最小改动” rule in “飞书表格编辑准则” to permit deleting,
renaming, hiding, or moving existing sheets when the user explicitly requests
those operations, while retaining the prohibition as the default for all other
tasks.
In `@docker/skills/lark-whiteboard/references/lark-whiteboard-workflow.md`:
- Around line 50-57: Move the routing-table update from the generated
lark-whiteboard workflow artifact to its corresponding source input, then
regenerate the skill artifacts so the matching order and route entries are
reproduced automatically. Do not directly edit files under docker/skills/**.
---
Minor comments:
In `@docker/server.js`:
- Around line 573-580: Update the translateCliError call in the executeRawApi
validation-error handling to include the page-limit and format CLI flags in its
allowlist alongside params, data, and page-all, so errors for all pushed flags
are translated to MCP parameter names.
In `@docker/skills/lark-apps/references/lark-apps-get.md`:
- Around line 16-18: Annotate every affected fenced command example with the
bash language identifier to satisfy MD040: update
docker/skills/lark-apps/references/lark-apps-get.md lines 16-18,
docker/skills/lark-drive/references/lark-drive-comment-location.md lines 14-15
and 20-21, docker/skills/lark-drive/references/lark-drive-comments-guide.md
lines 21-32, docker/skills/lark-drive/references/lark-drive-export.md lines
98-104, and docker/skills/lark-drive/references/lark-drive-list-comments.md
lines 13-15. No command content changes are needed.
In `@docker/skills/lark-apps/references/lark-apps-release-create.md`:
- Around line 24-27: 调整发布状态处理说明：仅当创建响应为异步部署（sync=false 或缺失）或 status 尚未为 finished
时，才使用 lark_apps_release_get 按 20s 间隔轮询；sync=true 且直接返回 status=finished
时，应立即视为部署完成，无需再次轮询。
In `@docker/skills/lark-doc/references/lark-doc-mindnote.md`:
- Line 16: Add a suitable language identifier, such as text or bash, to the
fenced code block in the mindnote documentation while preserving its existing
example content.
In `@docker/skills/lark-sheets/references/lark-sheets-batch-update.md`:
- Line 157: Fix the blank blockquote line in the Markdown document by removing
the standalone `>` or attaching the following text directly to the blockquote,
ensuring the blockquote structure satisfies markdownlint MD028.
- Around line 148-149: Update the operations example to use the declared
shortcut names: replace “+dim-insert” with “lark_sheets_dim_insert” and
“+cells-set” with “lark_sheets_cells_set”, preserving the existing inputs and
request structure.
In `@docker/skills/lark-sheets/references/lark-sheets-changeset.md`:
- Line 87: Update the fenced code example in the lark-sheets changeset
documentation to specify an appropriate language, preferably text, so the
markdownlint MD040 requirement is satisfied.
In `@docker/skills/lark-sheets/references/lark-sheets-history.md`:
- Line 70: Add an explicit language identifier to all three fenced command
examples in the document, using text for each unless a more appropriate language
applies, while preserving their command contents.
In `@docker/skills/lark-sheets/references/lark-sheets-range-operations.md`:
- Line 229: Update the fenced code example at the affected section of
lark-sheets-range-operations.md to include an appropriate language identifier,
such as text or python, while preserving the example content.
- Around line 202-203: Fix the blockquote formatting around the warning
beginning with “scope="all"” by removing the blank line that interrupts the
blockquote or prefixing it with “>”, ensuring the entire warning remains a
single valid blockquote and passes MD028.
In `@docker/skills/lark-sheets/references/lark-sheets-workbook.md`:
- Line 152: 更新文档中 values
字段的说明，明确其为无类型、面向文本的数据写入，日期和数字不会保留为对应类型而会写成文本；同时明确需要保留日期或数字类型时必须使用
sheets，避免继续表述为“自动识别”。
---
Nitpick comments:
In `@docker/generate-tools.js`:
- Line 117: Update the schema extraction log in the generator to use the
repository’s structured JSON convention via console.log(JSON.stringify(...)),
preserving schemaExtracted as a clearly named field. Also update the runbook
grep pattern that matches the current plain-text “Payload schemas extracted:
<N>” output so it recognizes the new JSON format.
In `@docker/server-lib.js`:
- Around line 294-379: Optionally simplify stripCliNotice by replacing the
hand-rolled string/brace scanner with a maintained JSON library such as
json-bigint, while preserving arbitrary-precision integers and restricting
re-encoding to the top-level _notice value. Keep the existing behavior for
removing update, retaining other notice keys, and returning the original output
for unsupported or invalid shapes.
🪄 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: c965b827-dde8-4f33-b3b8-72cf45af7270
⛔ Files ignored due to path filters (1)
infra/test/__snapshots__/snapshot.test.ts.snapis excluded by!**/*.snap
📒 Files selected for processing (51)
docker/Dockerfiledocker/__tests__/generate-tools.test.jsdocker/__tests__/mcp-contract.test.jsdocker/__tests__/server-runtime.test.jsdocker/__tests__/server.test.jsdocker/generate-tools-lib.jsdocker/generate-tools.jsdocker/rawapi-scopes.jsondocker/server-lib.jsdocker/server.jsdocker/shortcut-scopes.jsondocker/skills/lark-apps/SKILL.mddocker/skills/lark-apps/references/lark-apps-get.mddocker/skills/lark-apps/references/lark-apps-html-publish.mddocker/skills/lark-apps/references/lark-apps-init.mddocker/skills/lark-apps/references/lark-apps-release-create.mddocker/skills/lark-doc/SKILL.mddocker/skills/lark-doc/references/lark-doc-fetch.mddocker/skills/lark-doc/references/lark-doc-mindnote.mddocker/skills/lark-doc/references/lark-doc-xml-extended-blocks.mddocker/skills/lark-doc/references/lark-doc-xml.mddocker/skills/lark-drive/SKILL.mddocker/skills/lark-drive/references/lark-drive-comment-location.mddocker/skills/lark-drive/references/lark-drive-comments-guide.mddocker/skills/lark-drive/references/lark-drive-export.mddocker/skills/lark-drive/references/lark-drive-list-comments.mddocker/skills/lark-im/SKILL.mddocker/skills/lark-im/references/lark-im-messages-reply.mddocker/skills/lark-im/references/lark-im-messages-send.mddocker/skills/lark-sheets/SKILL.mddocker/skills/lark-sheets/references/lark-sheets-batch-update.mddocker/skills/lark-sheets/references/lark-sheets-changeset.mddocker/skills/lark-sheets/references/lark-sheets-chart.mddocker/skills/lark-sheets/references/lark-sheets-conditional-format.mddocker/skills/lark-sheets/references/lark-sheets-core-operations.mddocker/skills/lark-sheets/references/lark-sheets-filter-view.mddocker/skills/lark-sheets/references/lark-sheets-float-image.mddocker/skills/lark-sheets/references/lark-sheets-formula-translation.mddocker/skills/lark-sheets/references/lark-sheets-formula-verify.mddocker/skills/lark-sheets/references/lark-sheets-history.mddocker/skills/lark-sheets/references/lark-sheets-pivot-table.mddocker/skills/lark-sheets/references/lark-sheets-range-operations.mddocker/skills/lark-sheets/references/lark-sheets-read-data.mddocker/skills/lark-sheets/references/lark-sheets-sheet-structure.mddocker/skills/lark-sheets/references/lark-sheets-visual-standards.mddocker/skills/lark-sheets/references/lark-sheets-workbook.mddocker/skills/lark-sheets/references/lark-sheets-write-cells.mddocker/skills/lark-whiteboard/references/lark-whiteboard-workflow.mddocs/skills/bump-lark-cli-to-pr.mddocs/skills/bump-lark-cli.mdlambda/token-refresh-shim/scope-allowlist.ts
💤 Files with no reviewable changes (1)
- docker/skills/lark-sheets/references/lark-sheets-core-operations.md
Comment on lines
+24
to
+27
| - 成功读取 `data.release_id`、`data.status` 和 `data.sync`；`release_id` 是后续 `lark_apps_release_get` 的入参。 | ||
| - `sync=true` 表示同步部署（服务端等待部署完成后才返回），`sync=false` 或缺失表示异步部署。 | ||
| - `status=publishing` 表示发布仍在进行；继续用 `lark_apps_release_get` 轮询，轮询间隔应该为 20s。应用发布平均耗时大约 2min，整体超时时间大约 5min。 | ||
| - `status=finished` 表示部署已完成（同步部署时可能直接返回此状态）。 |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'Repository files mentioning generated skill artifacts or regeneration:\n'
rg -n --hidden --glob '!**/.git/**' \
-e 'docker/skills' \
-e 'generated and must never be hand-edited' \
-e 'regenerate' \
-e 'source-of-truth' \
-e 'skill artifacts' \
-e 'lark_.*_skill' \
README.md docs docker . 2>/dev/null | sed -n '1,220p'Repository: ddpie/lark-mcp-on-agentcore
Length of output: 41315
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'Files under docker/skills and possible generators:\n'
git ls-files 'docker/skills/**' | sed -n '1,200p'
printf '\nLikely generator scripts or templates:\n'
fd -t f -a 'generate|gen|build|skill' . \
| sed -n '1,200p'Repository: ddpie/lark-mcp-on-agentcore
Length of output: 15107
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect repository guidance for generated skill artifacts.
rg -n --hidden --glob '!**/.git/**' \
'docker/skills/**|generated and must never be hand-edited|regenerate' \
. | sed -n '1,240p'Repository: ddpie/lark-mcp-on-agentcore
Length of output: 8108
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'AGENTS.md relevant lines:\n'
sed -n '52,105p' AGENTS.md
printf '\ndocs/skills/adapt-skill-for-mcp.md relevant lines:\n'
sed -n '20,40p' docs/skills/adapt-skill-for-mcp.md
sed -n '388,410p' docs/skills/adapt-skill-for-mcp.md
printf '\ndocs/skills/bump-lark-cli.md relevant lines:\n'
sed -n '392,410p' docs/skills/bump-lark-cli.mdRepository: ddpie/lark-mcp-on-agentcore
Length of output: 7383
Regenerate docker/skills/** from the source docs
These files are generated output and should not be edited directly. Update the upstream skill sources, then regenerate and commit the resulting artifacts.
📍 Affects 7 files
docker/skills/lark-apps/references/lark-apps-release-create.md#L24-L27(this comment)docker/skills/lark-doc/SKILL.md#L12-L12docker/skills/lark-doc/references/lark-doc-fetch.md#L22-L24docker/skills/lark-doc/references/lark-doc-mindnote.md#L12-L25docker/skills/lark-doc/references/lark-doc-mindnote.md#L116-L117docker/skills/lark-doc/references/lark-doc-mindnote.md#L130-L130docker/skills/lark-doc/references/lark-doc-xml-extended-blocks.md#L1-L34docker/skills/lark-doc/references/lark-doc-xml.md#L49-L50docker/skills/lark-drive/SKILL.md#L22-L23docker/skills/lark-drive/SKILL.md#L36-L36docker/skills/lark-drive/SKILL.md#L78-L85docker/skills/lark-drive/SKILL.md#L138-L138
🤖 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 `@docker/skills/lark-apps/references/lark-apps-release-create.md` around lines
24 - 27, Update the upstream skill sources for the affected Lark documentation
and release guidance, then regenerate the generated outputs rather than editing
them directly. Regenerate and commit the artifacts at
docker/skills/lark-apps/references/lark-apps-release-create.md (24-27),
docker/skills/lark-doc/SKILL.md (12),
docker/skills/lark-doc/references/lark-doc-fetch.md (22-24),
docker/skills/lark-doc/references/lark-doc-mindnote.md (12-25, 116-117, 130),
docker/skills/lark-doc/references/lark-doc-xml-extended-blocks.md (1-34),
docker/skills/lark-doc/references/lark-doc-xml.md (49-50), and
docker/skills/lark-drive/SKILL.md (22-23, 36, 78-85, 138); no direct edits are
required at these generated sites.
Source: Coding guidelines
Comment on lines
+62
to
+64
| | `url` | 与 `token` 二选一 | 源文档 URL，推荐优先使用；自动解析类型和 token，Wiki URL 会解析到底层 `obj_token/obj_type` | | ||
| | `token` | 与 `url` 二选一 | 源文档裸 token；裸 token 必须同时传 `doc_type`。裸 Wiki node token 必须传 `doc_type="wiki"`，会先解析到底层 `obj_token/obj_type` | | ||
| | `doc_type` | 条件必填 | 源文档类型：`doc` / `docx` / `sheet` / `bitable` / `slides` / `wiki`；仅当使用裸 `token` 时必填，使用 `url` 时自动推断。`wiki` 只用于裸 Wiki node token，解析后会按真实底层类型发起导出 | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Use consistent semantics for the token parameter.
docker/skills/lark-drive/references/lark-drive-export.md#L62-L64: documenttokenas a bare token only.docker/skills/lark-drive/references/lark-drive-list-comments.md#L51-L53: documenttokenas a bare token only.
Both contracts make url and token mutually exclusive, so saying token also accepts URLs can cause invalid tool invocations.
📍 Affects 2 files
docker/skills/lark-drive/references/lark-drive-export.md#L62-L64(this comment)docker/skills/lark-drive/references/lark-drive-list-comments.md#L51-L53
🤖 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 `@docker/skills/lark-drive/references/lark-drive-export.md` around lines 62 -
64, Document token as accepting only a bare token, keeping it mutually exclusive
with url. Update the token descriptions in
docker/skills/lark-drive/references/lark-drive-export.md:62-64 and
docker/skills/lark-drive/references/lark-drive-list-comments.md:51-53, while
preserving the existing requirement that doc_type is supplied for bare tokens.
Comment on lines
+37
to
+44
| ### Sender Name Resolution | ||
|
|
||
| When using bot identity to fetch messages (e.g. `lark_im_chat_messages_list`, `lark_im_threads_messages_list`, `lark_im_messages_mget`), sender names may not be resolved (shown as open_id instead of display name). This happens when the bot cannot access the user's contact info. | ||
| When fetching messages (`lark_im_chat_messages_list`, `lark_im_threads_messages_list`, `lark_im_messages_mget`, `lark_im_messages_search`), a display name is returned for both user and bot senders: | ||
|
|
||
| **Root cause**: The bot's app visibility settings do not include the message sender, so the contact API returns no name. | ||
| - **Server-provided name**: the read APIs return `sender_name` (plus the full-i18n `sender_i18n_names` map) on each message `sender`; it is surfaced as the sender's `name` for users and bots alike. No name lookup and no extra permission are needed — **no contact scope** and no `application:bot.basic_info:read`. | ||
| - **Fallback to id**: when the server does not provide a name, the sender is shown by its id and the operation still succeeds. There is no contact-directory fallback. | ||
|
|
||
| **Solution**: Check the app's visibility settings in the Lark Developer Console — ensure the app's visible range covers the users whose names need to be resolved. Alternatively, use user identity to fetch messages, which typically has broader contact access. | ||
| The raw `sender_name` is not duplicated in output (its value is in `name`); the full `sender_i18n_names` map (all locales) is preserved for consumers that need a specific language, alongside an optional `open_bot_id` (`ou_`) for bot senders aligned with the message-receive event channel. System messages (`msg_type: system`) have no sender name — that is normal, not an error. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | 🏗️ Heavy lift
Regenerate these skill artifacts from their source of truth.
All three changed files are under docker/skills/**, which the repository guidelines mark as generated and not hand-editable. Move these changes into the generator/source-of-truth workflow, then regenerate the artifacts to prevent them from being overwritten.
docker/skills/lark-im/SKILL.md#L37-L44: regenerate the sender-name contract.docker/skills/lark-im/references/lark-im-messages-reply.md#L183-L183: regenerate the reply idempotency-key constraint.docker/skills/lark-im/references/lark-im-messages-send.md#L188-L188: regenerate the send idempotency-key constraint.
📍 Affects 3 files
docker/skills/lark-im/SKILL.md#L37-L44(this comment)docker/skills/lark-im/references/lark-im-messages-reply.md#L183-L183docker/skills/lark-im/references/lark-im-messages-send.md#L188-L188
🤖 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 `@docker/skills/lark-im/SKILL.md` around lines 37 - 44, Move the sender-name
contract from docker/skills/lark-im/SKILL.md lines 37-44, the reply
idempotency-key constraint from
docker/skills/lark-im/references/lark-im-messages-reply.md line 183, and the
send idempotency-key constraint from
docker/skills/lark-im/references/lark-im-messages-send.md line 188 into their
generator/source-of-truth definitions. Regenerate all three skill artifacts so
the generated files contain these updates and are not manually edited.
Source: Coding guidelines
| - **参数长度限制**：如果透视表配置 JSON 过长（数据源范围跨越大量行列），可能导致工具调用失败。此时应先确认数据范围的精确边界，避免传入过大的 range | ||
| - **创建后必须验证**：调用 `lark_sheets_pivot_list` 确认透视表结构正确 | ||
| - **落点不能覆盖任何已有数据（不只是 `source` 范围）**：透视表创建后会向右下**展开**，展开区域哪怕只盖到一个已有单元格（即便已避开源数据），也会报「目标位置不能与数据源重叠」并产生 `#REF!`。创建前无法精确预知展开尺寸，故**强烈优先默认策略**（不传 `target_sheet_id`/`target_sheet_name` 与 `target_position`/`range`，后端自动新建空白子表），零覆盖风险；非要落到已有子表，必须挑一片足够大的纯空白区 | ||
| - **创建后必须校验（用 `info` 读取展开后的真实占用区域）**：创建后调用 `lark_sheets_pivot_list` 读 `info.error_state` 与 `info.content_range`/`page_range`——`error_state` 非 `None`（如 `Cover` 盖到其它内容 / `Shrink` 展不开）说明落点冲突，应删除后重建到空白区；`content_range`/`page_range` 是展开后**实际占用区域**，可用 `lark_sheets_csv_get` 抽查其边缘外有没有盖掉原有数据，确认结构正确 |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Do not treat Loading as a terminal pivot failure.
Lines 124 and 126 list Loading as a possible info.error_state, but Lines 38 and 126 instruct agents to treat every non-None value as an overlap/expansion failure and delete/recreate the pivot. Restrict destructive recovery to terminal states such as Cover and Shrink; for Loading, re-read after polling or retrying.
Proposed clarification
-`info.error_state` 非 `None` 即视为失败
+仅 `Cover` / `Shrink` 等终态错误视为失败；`Loading` 应等待后重新读取Also applies to: 124-126
🤖 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 `@docker/skills/lark-sheets/references/lark-sheets-pivot-table.md` at line 38,
Update the pivot-table validation guidance around lark_sheets_pivot_list so
Loading is treated as a transient state, not a terminal failure. Restrict
delete-and-recreate instructions to terminal error_state values such as Cover
and Shrink; for Loading, poll or retry lark_sheets_pivot_list and re-read info
before deciding recovery.
Comment on lines
+125
to
+137
| | `height` | int | xor | 统一行高（像素，例：30 / 40 / 60；不是磅/points），配 `range` 使用。传了 `height` 就是像素模式，可以省略 `type`；显式 `type="pixel"` 也行（等价）。多行不同高用 `heights` | | ||
| | `heights` | 复合 JSON | xor | 差异化行高 map，一次原子调用给多行设置不同高度：键为单行（`"1"`）或行闭区间（`"2:20"`），值为像素高（如 30 / 50）、`"auto"`（自适应内容）或 `"standard"`（重置默认）。⚠️ 单位是像素，不是磅/points。与 `range` / `height` / `type` 互斥 | | ||
| | `type` | string | xor | 尺寸方式 enum：`pixel`（需配 `height`）/ `standard`（重置为默认行高）/ `auto`（自动适应内容）。常规写法直接给 `height` 即可省略本参数；`type="standard"` / `type="auto"` 不能与 `height` 同时给（可选值：`pixel` / `standard` / `auto`） | | ||
| | `range` | string | xor | 要调整行高的行闭区间；1-based 行号如 `2:10` 或单行 `5`。统一尺寸形态必填（配 `height` 或 `type`）；map 形态（`heights`）不传 | | ||
|
|
||
| ### `lark_sheets_cols_resize` | ||
|
|
||
| | 参数 | Type | 必填 | 说明 | | ||
| | --- | --- | --- | --- | | ||
| | `type` | string | required | 尺寸方式 enum：`pixel`（指定 px 像素值，需配 `size`）/ `standard`（重置为默认标准列宽）（可选值：`pixel` / `standard`） | | ||
| | `size` | int | optional | 列宽（像素，例：80 / 120 / 200）；`type="pixel"` 时必填，其它 type 忽略 | | ||
| | `range` | string | required | 要调整列宽的列闭区间；列字母如 `A:E` 或单列 `C` | | ||
| | `width` | int | xor | 统一列宽（像素，例：80 / 120 / 200；不是 Excel 字符单位），配 `range` 使用。传了 `width` 就是像素模式，可以省略 `type`；显式 `type="pixel"` 也行（等价）。多列不同宽用 `widths` | | ||
| | `widths` | 复合 JSON | xor | 差异化列宽 map，一次原子调用给多列设置不同宽度：键为单列（`"A"`）或列闭区间（`"C:E"`），值为像素宽（如 80 / 120 / 200）或 `"standard"`（重置默认）。⚠️ 单位是像素，不是 Excel 字符单位（像素 ≈ 字符数×8+16）。与 `range` / `width` / `type` 互斥 | | ||
| | `type` | string | xor | 尺寸方式 enum：`pixel`（需配 `width`）/ `standard`（重置为默认列宽）。常规写法直接给 `width` 即可省略本参数；`type="standard"` 不能与 `width` 同时给（可选值：`pixel` / `standard`） | | ||
| | `range` | string | xor | 要调整列宽的列闭区间；列字母如 `A:E` 或单列 `C`。统一尺寸形态必填（配 `width` 或 `type`）；map 形态（`widths`）不传 | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Align the resize XOR contract with the documented pixel-mode behavior.
The tables mark height/width and type as mutually exclusive, but the descriptions and Line 275 explicitly allow type="pixel" alongside the pixel parameter. Change the schema metadata or the prose so callers receive one unambiguous contract.
Also applies to: 275-275
🤖 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 `@docker/skills/lark-sheets/references/lark-sheets-range-operations.md` around
lines 125 - 137, Align the XOR metadata and descriptions for
lark_sheets_rows_resize and lark_sheets_cols_resize so pixel mode consistently
permits height with type="pixel" and width with type="pixel", while
standard/auto types remain mutually exclusive with the pixel parameters. Ensure
the tables and the referenced guidance at line 275 state the same contract
without ambiguity.
Comment on lines
+392
to
+393
| > 💡 `lark_sheets_sheet_copy` 连**公式 / 合并 / 分组底色 / 列宽 / 条件格式**一起整表复制。"照一张现成子表批量造结构相同的新子表"（如参考模板给每份数据各建一张同构子表）时，先 `lark_sheets_sheet_copy` 复制模板再用 `lark_sheets_cells_*` 只改数据，比从零 `lark_sheets_sheet_create` + 重建公式 / 样式省一大截，也天然满足"公式 / 分组 / 颜色照搬"。要把本地文件 / 数据并入**已有工作簿**当子表时走它（或 `lark_sheets_sheet_create`），别用 `lark_sheets_workbook_import` / `lark_sheets_workbook_create`——那两条只会新建独立表。 | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Do not recommend sheet_copy for importing local data.
lark_sheets_sheet_copy duplicates an existing sheet; it cannot ingest a local file or dataset. Document the workflow as creating/copying a destination sheet first, then writing the local data into it.
🤖 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 `@docker/skills/lark-sheets/references/lark-sheets-workbook.md` around lines
392 - 393, The workbook guidance incorrectly recommends lark_sheets_sheet_copy
for importing local files or datasets. Update the documented workflow to create
or copy a destination sheet only when appropriate, then write the local data
into that sheet using the relevant lark_sheets_cells_* operations; do not
present sheet_copy as the import mechanism.
Comment on lines
+46
to
+47
| > **数字还是文本，按"数据本质是量值还是标识符"二选一 —— 不看当下要不要计算**：金额 / 百分比 / 比率 / 计数 / 度量这类**本质是量值**的数据，一律以**数字类型**写入（百分比存小数 `0.54` 配 `number_format:"0%"`），**不要**设 `@` 文本格式。**这与"用户当下是否要排序 / 求和"无关**——数据类型由数据本质决定、不由当下用途决定：表格数据几乎总会被后续排序 / 图表 / 二次计算复用，`"54%"` 文本与数值列混排本就破坏一致性，且数字 + `number_format` 显示效果与文本**完全相同**，没有任何理由选文本。**最常见的误判就是"这只是 leaderboard / 报表 / 看板展示，又不用算，写成 `54%` 字符串就行"——这是错的，展示用途不改变"百分比是数值"的事实。**（`lark_sheets_table_put` 用 `dtypes` 声明 `int64` / `float64`；版式 `lark_sheets_table_put` 装不下时用 `lark_sheets_cells_set` 传数字 + `number_format`；都别在本地拼成带 `$` / `%` 的字符串走 `lark_sheets_csv_put`。）反过来，编号 `001`、规格 `3-1`、身份证 / 电话 / 单据号等**本质是标识符 / 标签**、要原样保留不被飞书自动解释的内容（否则 `001`→`1`、`3-1`→日期、点分日期 `12.10`→`12.1`（尾零丢失）、长号→科学计数），才以**字符串类型**写入（`dtypes` 设 `object`）并把 `number_format` 设为 `"@"`（文本格式），字面保真。 | ||
|
|
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Remove "0" as a safe format for identifier-like long numbers.
The new rule correctly requires IDs to be strings, but the preceding table still lists "0" for order numbers, identity numbers, and document IDs. Restrict those fields to string/object plus number_format:"@"; reserve "0" for genuinely numeric quantities.
🤖 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 `@docker/skills/lark-sheets/references/lark-sheets-write-cells.md` around lines
46 - 47, Update the identifier-format guidance in this document so order
numbers, identity numbers, and document IDs use only string/object types with
number_format:"@". Remove "0" as an allowed safe format for these
identifier-like fields, while retaining it only for genuinely numeric
quantities.
Comment on lines
94
to
+95
| 💡 **内容与样式分离写入（推荐）**：当需要同时写入内容和样式时，`cells` 中每个单元格都带上 `cell_styles` / `border_styles` 会导致入参非常冗长。由于同一区域的样式通常高度重复（如整列统一背景色、统一边框），推荐拆成两步： | ||
| 1. **先写内容**：`lark_sheets_cells_set` 只传 `value` / `formula`，不带样式，`cells` 入参精简 | ||
| 1. **先写内容**：`lark_sheets_cells_set` 只传 `value` / `formula`，不带样式，`cells` 入参精简。⚠️ 这里"不带样式"指暂不带 `cell_styles`，**不是**降级用 `lark_sheets_csv_put` 铺文本——数值列（百分比 / 金额 / 计数）仍必须以数字写入（百分比传 `0.44`）：样式能后补，数据类型不能后补（见上方「数字还是文本」）。 |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Do not use copy_to_range as a style-only operation.
copy_to_range copies values/formulas and styles. In the documented two-step example, copying the A2 template across A2:A100 after writing the data overwrites the entire column with the template value. Use lark_sheets_cells_set_style/batch styling for the second step, or copy the style before writing the final values.
🤖 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 `@docker/skills/lark-sheets/references/lark-sheets-write-cells.md` around lines
94 - 95, Update the documented two-step content-and-style workflow to avoid
using copy_to_range as a style-only operation, since it also copies template
values and formulas. Use lark_sheets_cells_set_style or batch styling after
writing values, or perform the copy before final values are written, while
preserving numeric data types.
Comment on lines
+29
to
+34
| ## 飞书表格编辑准则（动手前必守，所有编辑类任务一律生效） | ||
|
|
||
| 把高频意图映射到**真实存在**的工具 / 参数。agent 常从 Excel / Google Sheets / 飞书 OpenAPI 误迁移工具名或参数，先对照本表，避免一次必然失败的试错。完整工具见各工具参考。 | ||
| 下列准则横切所有飞书表格任务，**动手前先过一遍**——即使你是被索引直接路由进某个工具参考也一律生效。每条只给一句话纲要，展开与边界见括注的 reference。 | ||
|
|
||
| | 你要做的事 | ✅ 正确写法 | ❌ 不存在 | | ||
| | --- | --- | --- | | ||
| | 读数据（纯值 / CSV） | `lark_sheets_csv_get`（范围用 `range`） | `lark_sheets_get_range`、`lark_sheets_range_get`、`lark_sheets_cells_read` | | ||
| | 读值 + 公式 / 样式 / 批注 | `lark_sheets_cells_get(include="value,formula,style,comment,data_validation")` | `lark_sheets_get_cell`、`lark_sheets_cell_get`、`with_styles`、`with_merges`、`include_merged_cells` | | ||
| | 写纯文本值（整块 CSV 平铺，列里没有需保留的数值 / 日期语义） | `lark_sheets_csv_put`（定位用 `start_cell`，单个左上角锚点格；也接受 `range` 别名，区间自动取左上角） | — | | ||
| | 写带类型的数据到**已有**表（列里有数字 / 金额 / 百分比 / 日期 / 计数，要可排序 / 求和 / 入图表 / 透视） | `lark_sheets_table_put(sheets=…)` 完整 payload `{"sheets":[{...}]}`（列名走 `columns`、二维数据走 `data`、列 pandas dtype 走 `dtypes`、列展示格式走 `formats`；来源不限 DataFrame——Counter / dict / list 同理，详见 write-cells） | 在本地把数字拼成 `"$1,234"` / `"30.5%"` 字符串再 `lark_sheets_csv_put`（会落成文本、丢失计算能力） | | ||
| | **新建**电子表格并写带类型的数据（类型保真需求同上，但目标表还不存在） | `lark_sheets_workbook_create(sheets=…)`（协议与 `lark_sheets_table_put` 同构、一步建表 + typed 写入，无需先建空表再 `lark_sheets_table_put`；date / number 不丢，详见 workbook） | 用 `values` 灌日期 / 数字（会落成文本、丢类型） | | ||
| | 写值 / 公式 / 样式 | `lark_sheets_cells_set`（定位用 `range`） | — | | ||
| | 插图：图片**绑定到某条记录**、随行走（凭证 / 证件照 / 商品图 / 头像 / 二维码 / 每行配图） | `lark_sheets_cells_set_image`（单格 `range`，嵌入单元格内） | — | | ||
| | 插图：**自由摆放、不绑数据**的装饰 / 标识（logo / 水印 / 封面大图 / banner） | `lark_sheets_float_image_create`（浮动图片，自由定位 + 尺寸 + 层级） | — | | ||
| | 查找单元格 | `lark_sheets_cells_search`（关键字用 `find`） | `lark_sheets_cells_find`、`lark_sheets_find`、`query` | | ||
| | 查找并替换 | `lark_sheets_cells_replace` | — | | ||
| | 看子表结构（合并 / 行高列宽 / 冻结 / 隐藏） | `lark_sheets_sheet_info` | `lark_sheets_sheet_get`、`lark_sheets_structure_get` | | ||
| | 看工作簿 / 子表清单 | `lark_sheets_workbook_info` | `lark_sheets_sheet_list`、`lark_sheets_workbook_get`、`lark_sheets_workbook_list` | | ||
| | 导出 xlsx / 单表 csv | `lark_sheets_workbook_export` | — | | ||
| | 导入本地 xlsx/xls/csv 文件为飞书电子表格 | `lark_sheets_workbook_import(file="./x.xlsx")`（本地表格文件 → 飞书电子表格的正解；仅要导成多维表格 bitable 时才用 lark-drive 的 `lark_drive_import(type="bitable")`） | `lark_drive_import`（导电子表格时绕了 drive 通道、还要多给 `type`，应直接用 `lark_sheets_workbook_import`）、把 .xlsx 在本地读成数据再 `lark_sheets_workbook_create` 重灌 | | ||
| | 清除内容 / 格式 | `lark_sheets_cells_clear`（范围维度用 `scope`，取值 content / formats / all） | `type` | | ||
| | 批量清除多区域 | `lark_sheets_cells_batch_clear`（`scope`） | `target` | | ||
| | 调整列宽 / 行高 | `lark_sheets_cols_resize` / `lark_sheets_rows_resize`（行、列是两个独立工具） | `dimension`（无此参数） | | ||
| | 分组汇总 / 透视 | `lark_sheets_pivot_create`（默认不传落点参数 → 自动新建子表，零覆盖） | 用 SUMIF / 本地脚本拼一张假透视表 | | ||
| 1. **最小改动**：除任务要改的单元格 / 列外，原表其它单元格、行列结构、Sheet 名、合并区、格式 1:1 保持；中间结果放原数据右侧或新建空白 Sheet，**禁止删 / 改名 / 隐藏 / 移动已存在 Sheet**；改写类任务精确圈定行列，不该转的原值 1:1 保留。 | ||
| 2. **真实写回 + 回读校验**：交付必须是对在线表格的真实写入，写完用 `lark_sheets_csv_get` / `lark_sheets_cells_get` / `lark_sheets_<对象>_list` 回读确认实际生效——**写操作返回 `ok` 只代表请求被接受、不代表结果符合预期**；写公式后查错误码、筛选 / 排序后核对前几行、删除 / 清空后确认已空。禁止只在文本里声称"已完成"。 |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Allow explicitly requested sheet operations.
The absolute prohibition on deleting, renaming, hiding, or moving existing sheets conflicts with the later workbook/structure references, which support those operations when requested. Qualify this rule with “unless explicitly requested by the user” so the safety default does not block valid tasks.
🤖 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 `@docker/skills/lark-sheets/SKILL.md` around lines 29 - 34, Update the “最小改动”
rule in “飞书表格编辑准则” to permit deleting, renaming, hiding, or moving existing
sheets when the user explicitly requests those operations, while retaining the
prohibition as the default for all other tasks.
Comment on lines
+50
to
+57
| 按上到下匹配, 命中即停: | ||
|
|
||
| | 图表类型 | 身份 | 路径 | | ||
| |---|---|---| | ||
| | 思维导图、时序图、类图、饼图、甘特图 | 任何身份 | `lark_get_skill(domain="whiteboard", section="routes/mermaid")` | | ||
| | 其他图表 | `Claude` / `Gemini` / `GPT` / `GLM` | `lark_get_skill(domain="whiteboard", section="routes/svg")` | | ||
| | 其他图表 | `Doubao` / `Seed` / `Other` | `lark_get_skill(domain="whiteboard", section="routes/dsl")` | | ||
| | 鱼骨图、金字塔图、流程图 | `Doubao` / `Seed` | `lark_get_skill(domain="whiteboard", section="routes/dsl")` | | ||
| | 其他图表 | `Claude` / `Gemini` / `GPT` / `GLM` / `Doubao` / `Seed` | `lark_get_skill(domain="whiteboard", section="routes/svg")` | | ||
| | 其他图表 | `Other` | `lark_get_skill(domain="whiteboard", section="routes/dsl")` | |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf '\n== repo files ==\n'
git ls-files 'docker/skills/lark-whiteboard/**' 'docs/**' | sed -n '1,220p'
printf '\n== outline of target file ==\n'
if command -v ast-grep >/dev/null 2>&1; then
ast-grep outline docker/skills/lark-whiteboard/references/lark-whiteboard-workflow.md --view expanded || true
fi
printf '\n== search for generation / source-of-truth references ==\n'
rg -n --hidden --no-messages \
-e 'generated' \
-e 'source-of-truth' \
-e 'regenerat' \
-e 'docker/skills/** must never be hand-edited' \
-e 'lark-whiteboard-workflow' \
docker docs .github . 2>/dev/null | sed -n '1,260p'Repository: ddpie/lark-mcp-on-agentcore
Length of output: 21432
Do not hand-edit generated skill output.
This file lives under docker/skills/**, which is generated and must not be edited directly. Move the routing-table change to the source input and regenerate the skill artifacts so the update stays reproducible.
🤖 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 `@docker/skills/lark-whiteboard/references/lark-whiteboard-workflow.md` around
lines 50 - 57, Move the routing-table update from the generated lark-whiteboard
workflow artifact to its corresponding source input, then regenerate the skill
artifacts so the matching order and route entries are reproduced automatically.
Do not directly edit files under docker/skills/**.
Source: Path instructions
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
1 participant
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.
中文
lark-cli 1.0.68 → 1.0.69,并顺带修掉一个潜伏的 flag 类型 bug、补上一层 MCP 参数契约。三块内容互相独立,但都围绕「Agent 调飞书工具能不能一次调对」。
上游变更亮点(v1.0.69)
application:app_slash_command:read/write)。修复 / Fix
--values [["alice",95]]),旧的白名单式类型推断认不出、fallback 成 boolean,server 只推开关名、把 JSON 值丢掉,调用报 unknown error。改为按 cobra 的 2+ 空格列对齐判定;boolean 默认值 token(--skip-hidden false)仍正确判为 boolean。影响 sheets/docs/mail/apps 共 39+ flag。新功能 / New — MCP 参数契约层
Agent 传错参数时,过去只能拿到被 lenient 客户端吞成的 "unknown error"。这层让契约机器可读、让可自纠的错误穿透:
--print-schema提取复合 flag 的 JSON Schema 存入 catalog(25 个);flag description 去 CLI 化(剥@file/stdin、--flag→参数名、lark-cli skills read→lark_get_skill),把 skills 层的「零 CLI 泄漏」延伸到 catalog。isError:false;lark-cli validation 错误把--flag译回参数名后穿透;剥掉_notice.update;lark_get_skill接受docs→doc别名;lark_discover精确按名查询回传完整 schema。变更清单
docker/Dockerfile— 版本 pin 1.0.68 → 1.0.69docker/shortcut-scopes.json— 重新提取(453 shortcuts,+12 命令)docker/rawapi-scopes.json、lambda/token-refresh-shim/scope-allowlist.ts— 重新生成(allowlist +2 scope)docker/generate-tools.js、docker/generate-tools-lib.js— flag 类型判定重写 + payload schema 提取 + description 去 CLI 化docker/server.js、docker/server-lib.js— 参数校验 / 错误穿透 / stringify / notice 剥离 / domain 别名 / discover schemadocker/skills/— 6 域增量 re-adapt(lark-apps、lark-doc、lark-drive、lark-im、lark-sheets、lark-whiteboard);新增lark-apps-get、lark-doc-xml-extended-blocks、lark-drive-list-comments、lark-sheets-changeset、lark-sheets-formula-verify、lark-sheets-history;删除lark-sheets-core-operations(随上游拆分)docker/__tests__/— 新增测试(parseFlags / translateFlagDescription / 契约层纯函数 + server 级接线)docs/skills/bump-lark-cli*.md— bump runbook 增加 flag 静默失效与 schema 提取的检查项infra/test/__snapshots__/— CDK snapshot 更新升级
git pull && ./scripts/deploy.sh终端用户无需额外操作。
English
Bumps lark-cli 1.0.68 → 1.0.69, plus a latent flag-type fix and a new MCP parameter-contract layer. Three independent pieces, all about whether an agent can call a Feishu tool correctly on the first try.
Upstream highlights (v1.0.69)
application:app_slash_command:read/write).Fix
--values [["alice",95]]); the old whitelist inference fell back to boolean, so server pushed a bare switch and dropped the JSON, failing as "unknown error". Now classified by cobra's 2+-space column alignment; boolean default tokens (--skip-hidden false) still resolve to boolean. Affected 39+ flags across sheets/docs/mail/apps.New — MCP parameter-contract layer
When an agent passed a bad parameter, it previously got only a generic "unknown error" swallowed by lenient clients. This layer makes the contract machine-readable and lets self-correctable errors through:
--print-schemainto the catalog (25); strip CLI-speak from flag descriptions (@file/stdin,--flag→param name,lark-cli skills read→lark_get_skill), extending the skills layer's zero-CLI-leak rule to the catalog.isError:false; translate--flagrefs in lark-cli validation errors and pass them through; strip_notice.update;lark_get_skillaccepts thedocs→docalias;lark_discoverreturns the full schema on an exact-name query.Changes
docker/Dockerfile— pin 1.0.68 → 1.0.69docker/shortcut-scopes.json— re-extracted (453 shortcuts, +12 commands)docker/rawapi-scopes.json,lambda/token-refresh-shim/scope-allowlist.ts— regenerated (allowlist +2 scopes)docker/generate-tools.js,docker/generate-tools-lib.js— flag-type rewrite + payload-schema extraction + description de-CLIdocker/server.js,docker/server-lib.js— payload validation / error pass-through / stringify / notice strip / domain alias / discover schemadocker/skills/— incremental re-adapt across 6 domains; newlark-apps-get,lark-doc-xml-extended-blocks,lark-drive-list-comments,lark-sheets-changeset,lark-sheets-formula-verify,lark-sheets-history; removedlark-sheets-core-operationsdocker/__tests__/— new tests (parseFlags / translateFlagDescription / contract-layer units + server-level wiring)docs/skills/bump-lark-cli*.md— runbook gains flag silent-failure and schema-extraction checksinfra/test/__snapshots__/— CDK snapshot updatedUpgrading
git pull && ./scripts/deploy.shNo action required from end users.
Summary by CodeRabbit
New Features
Documentation
Bug Fixes