docs(lark-doc): document read-only block types that create/update silently skip#620
Open
herbertliu wants to merge 2 commits intomainfrom
Open
docs(lark-doc): document read-only block types that create/update silently skip#620herbertliu wants to merge 2 commits intomainfrom
herbertliu wants to merge 2 commits intomainfrom
Conversation
…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.
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 60.05% 60.05%
=======================================
Files 406 406
Lines 43089 43089
=======================================
Hits 25877 25877
Misses 15194 15194
Partials 2018 2018 ☔ 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@7449025ce2bd8477cf3cafb4cd13158e4fced9d1🧩 Skill updatenpx skills add larksuite/cli#feat/doc-readonly-block-types -y -g |
…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.
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
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.
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