docs(lark-doc): refine rich block, path, and block ID guidance#1508
docs(lark-doc): refine rich block, path, and block ID guidance#1508fangshuyu-768 wants to merge 6 commits into
Conversation
github-actions
Bot
added
domain/ccm
|
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:
📝 WalkthroughWalkthroughFive Lark doc reference and skill files are updated across two functional themes. Element usage guidance in style and workflow files is made conditional rather than prescriptive: tables, grids, callouts, and whiteboards should be used only when they solve specific problems (row/column data, comparison, visual emphasis, or diagram comprehension), with paragraph restructuring preferred otherwise. The skill and update-reference files add comprehensive block ID lifecycle documentation explaining which write operations invalidate IDs and when to re-fetch, plus tighter prerequisites for document creation vs. editing workflows. ChangesLark Doc Reference and Skill Documentation Updates
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
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 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 |
🚀 PR Preview Install Guide🧰 CLI updatenpm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@3d611ef635fb2bc3456395cb7a3a46004e650d57🧩 Skill updatenpx skills add larksuite/cli#docs/soften-lark-doc-rich-block-guidance -y -g |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (1)
skills/lark-doc/references/lark-doc-update.md (1)
58-58: ⚡ Quick winMinor wording improvement needed for consistency with adjacent table entries.
Line 58 uses "复制出的 block 是新 ID" which is grammatically valid but inconsistent with the verb patterns in nearby rows. Lines 56 and 57 use the more natural and active phrasing "会生成新 block ID" (will generate new ID). For clarity and consistency, recommend rephrasing line 58 to match:
- Old: "复制出的 block 是新 ID"
- New: "复制出的新 block 会生成新 ID" or "复制出的 block 会生成新 ID"
📝 Proposed rewording for consistency
- | `block_copy_insert_after` | 源 block 和锚点 block ID 保留；复制出的 block 是新 ID | 如果要继续操作复制出的内容，先重新 fetch 获取新 ID | + | `block_copy_insert_after` | 源 block 和锚点 block ID 保留；复制出的新 block 会生成新 ID | 如果要继续操作复制出的内容，先重新 fetch 获取新 ID |🤖 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-doc/references/lark-doc-update.md` at line 58, In the table entry for block_copy_insert_after on line 58, update the phrase "复制出的 block 是新 ID" to use the more consistent and active verb pattern "会生成新 ID" that is used in the adjacent rows (lines 56-57). Change the text to either "复制出的新 block 会生成新 ID" or "复制出的 block 会生成新 ID" to maintain grammatical consistency and clarity with the surrounding table entries.
🤖 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.
Nitpick comments:
In `@skills/lark-doc/references/lark-doc-update.md`:
- Line 58: In the table entry for block_copy_insert_after on line 58, update the
phrase "复制出的 block 是新 ID" to use the more consistent and active verb pattern
"会生成新 ID" that is used in the adjacent rows (lines 56-57). Change the text to
either "复制出的新 block 会生成新 ID" or "复制出的 block 会生成新 ID" to maintain grammatical
consistency and clarity with the surrounding table entries.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: e4b0c1bc-ba3e-432e-92ca-980e86283ef3
📒 Files selected for processing (2)
skills/lark-doc/SKILL.mdskills/lark-doc/references/lark-doc-update.md
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1508 +/- ##
==========================================
+ Coverage 73.52% 73.72% +0.19%
==========================================
Files 783 781 -2
Lines 74630 74217 -413
==========================================
- Hits 54874 54717 -157
+ Misses 15662 15437 -225
+ Partials 4094 4063 -31 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
fangshuyu-768
changed the title
fangshuyu-768
changed the title
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
skills/lark-doc/references/style/lark-doc-update-workflow.md (1)
40-41: ⚡ Quick winStrengthen explicit alignment with style.md rich-block usage constraints.
Lines 40–41 correctly prioritize simpler formatting and state that rich blocks are optional, but the guidance could be more explicit about when each rich block is appropriate. The referenced lark-doc-style.md table (Context snippet 1) defines specific scenarios:
<callout>only for short visual reminders (risks, limitations, alerts)<grid>for simple 2-column comparisons<table>for row/column lookups or multi-dimension comparisonsCurrently, line 41 mentions rich blocks are optional but doesn't cross-reference these usage constraints. Consider rephrasing to explicitly exclude callout/table/grid from readability improvements unless those specific scenarios apply.
For example, align more closely with the lark-doc-create-workflow.md pattern (Context snippet 2):
"优先拆段、改列表、增加小标题或调整顺序；只有确实存在行列数据、并列对比或强提醒信息时，才考虑
<table>/<grid>/<callout>"Suggested alignment
- 优先通过重写段落、调整标题、拆分列表或补充小标题提升可读性 - - 富 block 是可选表达手段，不因固定比例而添加；画板类需求只走第 5 步 + - 富 block 是可选表达手段：只有确实存在行列数据、并列对比或强提醒信息时，才分别考虑 `<table>` / `<grid>` / `<callout>`；不因固定比例而添加。画板类需求只走第 5 步。🤖 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-doc/references/style/lark-doc-update-workflow.md` around lines 40 - 41, The guidance on lines 40-41 states that rich blocks are optional but lacks explicit constraints on when each rich block type should be used. Revise line 41 to be more specific by replacing the vague statement about rich blocks being optional with explicit conditions that align with lark-doc-style.md constraints: specifically mention that callout, grid, and table should only be considered when their specific scenarios apply (callout for alerts/risks, grid for 2-column comparisons, table for row/column data lookups). Reword to follow the lark-doc-create-workflow.md pattern that explicitly states these rich blocks should only be used when those specific conditions genuinely exist, not merely as decoration, making the when-and-why of each rich block type clear to writers.
🤖 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-doc/references/style/lark-doc-update-workflow.md`:
- Around line 22-28: In the lark-doc-update-workflow.md file on line 25, the
instruction uses incomplete shorthand notation "section --start-block-id <标题id>"
which is ambiguous. Replace this shorthand with the full and explicit command
syntax "docs +fetch --api-version v2 --scope section --start-block-id <标题id>" to
maintain consistency with the authoritative syntax documented in
lark-doc-fetch.md and avoid confusion. Ensure that all command examples in this
section follow the complete syntax pattern with the --scope parameter always
explicitly stated rather than implied.
---
Nitpick comments:
In `@skills/lark-doc/references/style/lark-doc-update-workflow.md`:
- Around line 40-41: The guidance on lines 40-41 states that rich blocks are
optional but lacks explicit constraints on when each rich block type should be
used. Revise line 41 to be more specific by replacing the vague statement about
rich blocks being optional with explicit conditions that align with
lark-doc-style.md constraints: specifically mention that callout, grid, and
table should only be considered when their specific scenarios apply (callout for
alerts/risks, grid for 2-column comparisons, table for row/column data lookups).
Reword to follow the lark-doc-create-workflow.md pattern that explicitly states
these rich blocks should only be used when those specific conditions genuinely
exist, not merely as decoration, making the when-and-why of each rich block type
clear to writers.
🪄 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: d813306a-e61e-4dd0-93f9-f3790366af79
📒 Files selected for processing (2)
skills/lark-doc/SKILL.mdskills/lark-doc/references/style/lark-doc-update-workflow.md
✅ Files skipped from review due to trivial changes (1)
- skills/lark-doc/SKILL.md
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 `@skills/lark-doc/references/lark-doc-update.md`:
- Line 52: In the documentation line describing block operations, replace the
phrase "新内容是新 ID" with an action verb to clarify the relationship. Change "是"
(is) to "产生" (generate) or "获得" (acquire) to make the causality explicit. Use
either "新内容产生新的 ID" or "新内容获得新的 ID" to improve clarity and grammar in the
sentence about how new content relates to new IDs in the block_insert_after,
append, and block_copy_insert_after operations.
🪄 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: 20c4c0ed-2537-4bf9-b7c7-45201e8ba32e
📒 Files selected for processing (3)
skills/lark-doc/SKILL.mdskills/lark-doc/references/lark-doc-update.mdskills/lark-doc/references/style/lark-doc-update-workflow.md
✅ Files skipped from review due to trivial changes (1)
- skills/lark-doc/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (1)
- skills/lark-doc/references/style/lark-doc-update-workflow.md
PR Quality SummaryThe semantic review system could not produce a fully trusted result. This is not reported as a code defect. System status
|
1 participant
Background
PR #1463 softened the lark-doc style guidance by making rich blocks optional instead of mandatory. Follow-up evaluation still showed three gaps:
<callout>and<table>because the component guide presents them as the default recommendation for conclusions, summaries, and structured content.docs +updateoperations because the lifecycle of block IDs after write commands is not explicit enough.This PR keeps rich blocks, full-fidelity editing, and block-level operations available, but makes the routing guidance more selective and concise.
Changes
1. Soften rich block and whiteboard guidance
<callout>usage to short visual reminders such as risks, limitations, pending confirmations, or key alerts.<table>usage to content that benefits from row/column lookup or comparison.2. Clarify Docs task path selection
lark-drive.--detail fullas the intended path for full-fidelity content edits.old text -> new textreplacements.str_replace, localwith-ids, or scopedfullreads based on actual edit intent.3. Clarify and deduplicate block ID lifecycle guidance
lark-doc-update.mdwhen editing existing documents, alongside the update workflow.str_replaceusually preserves IDs, while large replacements may require refetching4. Trim repeated entry-point guidance
Expected Behavior
<callout>,<table>,<grid>,<whiteboard>, and other rich blocks when they fit the content.fetch with-ids/full -> block operationfor simple read-only, search, import/export, and direct text replacement tasks.--detail fullfor full-fidelity edits that need existing content, style, references, media, or resource metadata.Testing
git diff --checknode scripts/skill-format-check/index.jsgo test ./shortcuts/doc