docs(lark-doc): document read-only block types that create/update silently skip#620
docs(lark-doc): document read-only block types that create/update silently skip#620herbertliu wants to merge 6 commits intomainfrom
Conversation
github-actions
Bot
added
domain/ccm
📝 WalkthroughWalkthroughThe PR adds documentation clarifying that Lark doc MCP Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
skills/lark-doc/SKILL.md (1)
144-144: Use the exact placeholder pattern for consistency.Line 144 currently shows
<!-- Unsupported block type -->; consider matching the detailed doc’s canonical form<!-- Unsupported block type: N -->to avoid ambiguity.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/SKILL.md` at line 144, The README entry uses a generic placeholder `<!-- Unsupported block type -->`; change it to the canonical pattern `<!-- Unsupported block type: N -->` so it matches the detailed doc and avoids ambiguity—update the text in SKILL.md where the reference to `references/lark-doc-block-type-limits.md` appears (the entry that currently contains `<!-- Unsupported block type -->`) to use `<!-- Unsupported block type: N -->` instead and ensure any surrounding explanation mentions the `: N` suffix as the required format.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@skills/lark-doc/references/lark-doc-block-type-limits.md`:
- Line 5: Clarify that the behavior differs between the write-path and
fetch-path for the `create-doc` MCP tool: update the sentence referencing
`create-doc` so it explicitly states write-path = the tool silently skips
unsupported block types (API returns success but blocks are not written) and
fetch-path = the service may return a placeholder HTML comment such as `<!--
Unsupported block type: N -->` when rendering/fetching; reference the
`create-doc` MCP tool and the placeholder comment in the revised wording to
avoid implying `create-doc` itself emits HTML comments.
---
Nitpick comments:
In `@skills/lark-doc/SKILL.md`:
- Line 144: The README entry uses a generic placeholder `<!-- Unsupported block
type -->`; change it to the canonical pattern `<!-- Unsupported block type: N
-->` so it matches the detailed doc and avoids ambiguity—update the text in
SKILL.md where the reference to `references/lark-doc-block-type-limits.md`
appears (the entry that currently contains `<!-- Unsupported block type -->`) to
use `<!-- Unsupported block type: N -->` instead and ensure any surrounding
explanation mentions the `: N` suffix as the required format.
🪄 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
Run ID: 501fbc9a-e52b-4744-bded-ea7a9dc16359
📒 Files selected for processing (2)
skills/lark-doc/SKILL.mdskills/lark-doc/references/lark-doc-block-type-limits.md
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #620 +/- ##
==========================================
+ Coverage 63.20% 64.59% +1.39%
==========================================
Files 491 516 +25
Lines 42237 45782 +3545
==========================================
+ Hits 26694 29572 +2878
- Misses 13211 13625 +414
- Partials 2332 2585 +253 ☔ View full report in Codecov by Sentry. 🚀 New features to boost your workflow:
|
🚀 PR Preview Install Guide🧰 CLI updatenpm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@f0096903a6d34d7c05792f599fa5bb85318c788f🧩 Skill updatenpx skills add larksuite/cli#feat/doc-readonly-block-types -y -g |
There was a problem hiding this comment.
🧹 Nitpick comments (1)
skills/lark-doc/references/lark-doc-block-type-limits.md (1)
8-8: Consider refining "同类" for clearer reference.The phrase "同类无法稳定序列化成 markdown 的原生 block" uses "同类" (similar type/same type), which is slightly ambiguous—it's unclear what category it refers back to. Consider using "这类" (these types of) or "相应的" (corresponding) for more direct clarity.
📝 Suggested wording refinement
-- **读取路径（`docs +fetch` 导出）**：同类无法稳定序列化成 markdown 的原生 block，会以占位注释 `<!-- Unsupported block type: N -->` 呈现。 +- **读取路径（`docs +fetch` 导出）**：这类无法稳定序列化成 markdown 的原生 block，会以占位注释 `<!-- Unsupported block type: N -->` 呈现。🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@skills/lark-doc/references/lark-doc-block-type-limits.md` at line 8, Replace the ambiguous term "同类" in the sentence "同类无法稳定序列化成 markdown 的原生 block，会以占位注释 `<!-- Unsupported block type: N -->` 呈现。" with a clearer referent such as "这类" or "相应的" so it reads e.g. "这类原生 block 无法稳定序列化成 markdown，会以占位注释 `<!-- Unsupported block type: N -->` 呈现。", ensuring the sentence clearly refers to the native block types mentioned earlier.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@skills/lark-doc/references/lark-doc-block-type-limits.md`:
- Line 8: Replace the ambiguous term "同类" in the sentence "同类无法稳定序列化成 markdown
的原生 block，会以占位注释 `<!-- Unsupported block type: N -->` 呈现。" with a clearer
referent such as "这类" or "相应的" so it reads e.g. "这类原生 block 无法稳定序列化成
markdown，会以占位注释 `<!-- Unsupported block type: N -->` 呈现。", ensuring the sentence
clearly refers to the native block types mentioned earlier.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: d52a7e6e-140b-4d82-a8ce-6794435e86e6
📒 Files selected for processing (1)
skills/lark-doc/references/lark-doc-block-type-limits.md
fangshuyu-768
left a comment
fangshuyu-768
left a comment
There was a problem hiding this comment.
Reviewed the changes; a few concerns about consistency with the rest of the lark-doc skill before this lands.
1. Tag name mismatch (skills/lark-doc/references/lark-doc-block-type-limits.md, lines ~19–20). The new table uses <reference-synced> / <source-synced> (kebab-case, reversed word order), but the existing skill is consistent with <synced_reference> / <synced_source> (snake_case): see skills/lark-doc/SKILL.md:52 and skills/lark-doc/references/lark-doc-xml.md:48. Agents copying from this new doc will produce tags the create/update path doesn't recognize. Please align with the existing form.
2. Read-only inventory is incomplete (the "已知只读 block" section). skills/lark-doc/references/lark-doc-xml.md:48 already names five non-creatable block types: synced_reference, synced_source, bitable, base_ref, okr. This table only documents the first two; consider adding the other three so the doc is the single source of truth.
3. "Silently skipped" is narrower than reality. The phrasing "API returns success but the block does not appear" reads as if these blocks never exist in documents. Per lark-doc-xml.md:48, they can be moved/fetched, just not created. Worth distinguishing "block can exist via move/fetch" from "block cannot be created/updated" so agents don't mis-handle fetched output that contains them.
fangshuyu-768
left a comment
fangshuyu-768
left a comment
There was a problem hiding this comment.
Inline notes below — these expand on the earlier summary review and anchor each finding to a specific line.
|
|
||
| | 块类型 | Markdown / HTML 形式 | 现象 | 推荐做法 | | ||
| |--------|---------------------|------|---------| | ||
| | 引用同步块 | `<reference-synced source-block-id="..." source-document-id="...">...</reference-synced>` | 静默跳过；API 返回成功但文档中不会出现此块 | 通过 UI 手动绑定；或在 skill 中把"同步块占位"作为单独的手工步骤记录 | |
There was a problem hiding this comment.
Tag name is inconsistent with the rest of the lark-doc skill. skills/lark-doc/SKILL.md:52 and skills/lark-doc/references/lark-doc-xml.md:48 both use <synced_reference> / <synced_source> (snake_case). This new doc uses <reference-synced> / <source-synced> (kebab-case, reversed word order). Agents copying from here will produce tags the create/update path doesn't recognize. Please align with the existing form.
There was a problem hiding this comment.
Fixed in 245a0a5 — switched both the reference doc and the SKILL.md callout to the snake_case forms (<synced_reference> / <synced_source>), matching what lark-doc-xml.md:48 and SKILL.md:52 already use. Added a 'XML 标签 (snake_case)' column header so future contributors don't reintroduce the kebab-case form.
|
|
||
| 本文档列出已知的只读 / 受限 block 类型，供 Agent 在撰写 markdown 前自检。 | ||
|
|
||
| ## 已知只读 block（API 只支持 fetch，不支持 create / update） |
There was a problem hiding this comment.
Read-only inventory is incomplete. skills/lark-doc/references/lark-doc-xml.md:48 already names five non-creatable block types: synced_reference, synced_source, bitable, base_ref, okr. This table only documents the first two — consider adding bitable, base_ref, and okr so this doc is the single source of truth.
There was a problem hiding this comment.
Fixed in 245a0a5 — extended the inventory to all five non-creatable block types from lark-doc-xml.md:48 (synced_reference, synced_source, bitable, base_ref, okr). Each row gets its own typical XML form and migration guidance. Added a note about the block_copy_insert_after exclusion for the same set + task.
|
|
||
| `docs +create` / `docs +update` 底层的 `create-doc` MCP 工具**不支持部分 block 类型**。具体行为分为两条路径： | ||
|
|
||
| - **写入路径（create / update）**：markdown 中出现这些 block 时，写入阶段会被静默跳过，API 返回 `code=0 / success=true`，但 block 根本没进文档。 |
There was a problem hiding this comment.
Phrasing is narrower than reality. lark-doc-xml.md:48 describes these blocks as 不可创建，仅支持移动 — they can exist in documents (via fetch / move), just can't be created. Saying 静默跳过；API 返回成功但文档中不会出现此块 reads as if they never appear, which can mislead agents handling fetched output that contains them. Worth distinguishing 'block can exist via move/fetch' from 'block cannot be created/updated'.
There was a problem hiding this comment.
Fixed in 245a0a5 — rewrote the opening to explicitly separate three paths: create/update (silently skipped), fetch (serialized normally for blocks already in the doc), and block_move_after (works across documents). Replaced the misleading '不会真的出现' phrasing with '不能创建/更新，但可以 fetch / move'. The new tagline is: 'these blocks aren't fully read-only, just can't be newly created'.
…ently skip Agents hit a repeatable gotcha where docs +create / docs +update returns success but the block is silently dropped on the server side — e.g. <reference-synced> sync blocks used for weekly-report team headers, or AddOns that fetch-doc only represents as '<!-- Unsupported block type: N -->' comments. Because the API answers code=0 success=true, nothing in the tooling chain currently surfaces the drop. Add references/lark-doc-block-type-limits.md with the known read-only block inventory, the fetch-time <!-- Unsupported block type --> marker, signals for detecting a silent drop, and suggested workarounds (manual UI step vs avoiding the block in generated markdown). Link it from the docs SKILL.md so Agents see it before writing markdown.
…ype limits CodeRabbit noted the opening paragraph could be read as if create-doc itself emits the '<!-- Unsupported block type: N -->' comment, when in fact that placeholder is a fetch-doc rendering artifact for blocks it cannot serialize back to markdown. Split the sentence so the two paths are clearly separate: write-path silently drops the block; fetch-path surfaces the placeholder comment.
…ase + complete inventory) Address fangshuyu-768's three review notes on PR #620: 1. Tag naming: switch from kebab-case <reference-synced> / <source-synced> to snake_case <synced_reference> / <synced_source>, matching the canonical form already used in skills/lark-doc/SKILL.md and lark-doc-xml.md. Agents copying tags from this doc were producing forms the create/update path doesn't recognize. 2. Inventory: add <bitable>, <base_ref>, and <okr> alongside the two sync blocks. lark-doc-xml.md:48 already lists all five as 'not creatable, only movable'; this doc is now the single source of truth for the same set with deeper guidance on each. 3. Phrasing: rewrite the opening so the reader doesn't conclude these blocks 'never appear in documents'. They do — fetch-doc serializes them, block_move_after relocates them — they just can't be created or updated. The new structure splits create/update vs fetch vs move semantics explicitly. Also update SKILL.md's 'Block type 写入限制' callout to use the same snake_case names so the skill index agrees with the reference doc.
herbertliu
force-pushed
the
feat/doc-readonly-block-types
branch
from
7449025 to
245a0a5
Compare
…on refs Two review findings on PR #620: 1. The "相关 MCP 层记录" trailing section pointed at ../../lark-cli-dev/SKILL.md, which doesn't exist anywhere in the repo (no skill, no git history, no content matching the described "已知 MCP 层限制" topics like ordered-list renumbering / callout emoji mismatch / code fence nesting). Drop the section; if a real target ever shows up, link it from there rather than carry a phantom reference in the meantime. 2. Two cross-references to lark-doc-xml.md §三 / §四 were file-only links that landed at the top of the file. Convert them to GitHub anchor links (#三资源块 and #四块级复制与移动), matching the CJK anchor convention already in use in skills/lark-mail/references and skills/lark-base/references. Readers now jump straight to the referenced section.
…s v1 fetch / markdown specific The 5-block read-only inventory (synced_reference, synced_source, bitable, base_ref, okr) is rooted in Lark's data model and applies to both v1 MCP and v2 OpenAPI write paths — that part of the doc was already version-agnostic. The "<!-- Unsupported block type: N -->" placeholder, however, is a serialization fallback specific to v1 MCP `fetch-doc` rendering to markdown. v2 fetch (`POST /open-apis/docs_ai/v1/documents/<token>/fetch`) defaults to XML and represents blocks structurally, so this comment form doesn't appear there. Without that qualifier, an agent reading this doc on v2 might chase a placeholder that never materializes, or worse, treat its absence as evidence the block was successfully written. Changes: - "概念区分" bullet now scopes the placeholder note to "v1 fetch + markdown" and adds a one-line v2 fetch contrast. - "会产生 ... 占位符的块" section gets a `(v1 fetch / markdown 输出)` qualifier in the heading and an explicit blockquote note about v2 behavior at the top. - Closing sentence broadens "create-doc 不会把注释解析" to "v1 / v2 写入路径都不会" so the don't-feed-comments-back-in advice survives the v2 migration. - Signal #2 in the detection list now flags the placeholder as "v1 fetch + markdown" specific and clarifies signal #1 / #3 are v1/v2 generic.
|
Pushed three follow-up commits — flagging them here so the trail is visible alongside the resolved review threads. 1. Dead link to The trailing "相关 MCP 层记录" section pointed at a skill that doesn't exist in the repo: 2. Two cross-references to 3. The 5-block read-only inventory (synced_reference, synced_source, bitable, base_ref, okr) is rooted in Lark's data model and applies to both v1 MCP and v2 OpenAPI write paths — that part of the doc was correctly version-agnostic. The placeholder comment, however, is a serialization fallback specific to v1 MCP Edits: scoped the placeholder mention in the "概念区分" bullet, added a Net diff for all three: |
…of lark-doc skill Main branch's `lark-doc` skill is v2-exclusive: - SKILL.md description: "使用本 skill 时，docs +create、docs +fetch、docs +update **必须携带 --api-version v2**" - lark-doc-fetch.md parameter table: `--api-version` is "固定传 v2" - A repo-wide grep across `skills/lark-doc/` for v1 / MCP / fetch-doc / create-doc / update-doc returns zero hits on main This new reference doc was reintroducing v1 vocabulary into a skill that had consciously scrubbed it. The previous attempt to "qualify the placeholder section as v1-specific" pointed in the wrong direction: adding a `(v1 fetch / markdown 输出)` watermark to a section that should not exist for this audience at all. Agents told to use --api-version v2 will never trigger the v1 MCP fetch-doc + markdown placeholder fallback, so the section was teaching defenses against a failure mode that doesn't apply. Removed: - The entire `## 会产生 <!-- Unsupported block type: N --> 占位符的块` section (heading + v1 blockquote + AddOns/SubPageList/Agenda triggers + the round-trip-don't-feed-comments-back paragraph). Pure v1 fetch + markdown fallback content. - The "v1 fetch (MCP fetch-doc) + markdown 输出 ... v2 fetch ... 无此 markdown 注释占位符" sentence from the 概念区分 read-path bullet. Replaced with a tight v2 description: existing same-type blocks serialize to their XML tags, readable and usable as a block_move_after source. - Signal #2's reference to the placeholder fallback. Replaced with the direct v2 signal: fetch comes back without the tag the write attempted to add (pre-existing same-type blocks remain, unrelated to the write). Kept (unchanged, all version-agnostic / data-model rooted): - 5-block read-only inventory (synced_reference / synced_source / bitable / base_ref / okr) — non-creatable from text in any API version - block_move_after migration advice — v2 command, applies natively - block_copy_insert_after exclusion note for the same 5 types + task - "对 AI Agent 的影响" guidance (with a small consistency tweak: "在 markdown 里伪造" → "在生成的 XML / markdown 里伪造", since v2 defaults to XML) Net: -12 / +2 lines. Doc now only describes behavior that applies to the v2-only audience the skill is targeting.
|
Thanks for documenting this issue. The pitfall is real, but I do not think we should encode this limitation in the skill documentation, so I would like to reject this PR for now. Main reasons:
So I would like to reject this PR for now. The preferred direction is to improve the create/update response diagnostics, for example by returning skipped / unsupported blocks and their reasons. |
3 participants
Summary
Addresses Case 6 in the lark-cli pitfall list:
docs +create/docs +updatereturns success but silently drops blocks the underlyingcreate-docMCP tool cannot write (sync blocks, some AddOns, anything that round-trips as<!-- Unsupported block type: N -->fromfetch-doc). Agents hit this repeatedly when scaffolding weekly reports or other templates and get no signal the block is gone.Rather than adding a runtime warning (which would require MCP-side block-type inventory that CLI doesn't own), this PR documents the known read-only block set and the signals an Agent can use to detect a silent drop, so the skill consumer knows to avoid these tags in generated markdown.
Changes
skills/lark-doc/references/lark-doc-block-type-limits.md(new): read-only block inventory (<reference-synced>,<source-synced>), the<!-- Unsupported block type: N -->marker origin, detection signals, recommended workaroundsskills/lark-doc/SKILL.md: new "Block type 写入限制" section linking the new reference right after the shortcuts tableTest Plan
Summary by CodeRabbit