docs: reorganize lark-doc skill navigation#1574
Closed
fangshuyu-768 wants to merge 1 commit into
Closed
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:
📝 WalkthroughWalkthroughThe PR revises ChangesLark docs routing and references
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 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 |
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #1574 +/- ##
==========================================
+ Coverage 74.53% 74.59% +0.06%
==========================================
Files 792 793 +1
Lines 78690 79085 +395
==========================================
+ Hits 58653 58997 +344
- Misses 15670 15702 +32
- Partials 4367 4386 +19 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
🚀 PR Preview Install Guide🧰 CLI updatenpm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@f0d5e7bd46b5167cfe20a0ada0afdd416d20865e🧩 Skill updatenpx skills add larksuite/cli#codex/lark-doc-skill-structure -y -g |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@skills/lark-doc/references/lark-doc-media.md`:
- Around line 54-60: The media-preview docs use the wrong fetch output tag
names; update the wording in lark-doc-media.md where `docs +media-preview` is
described so it refers to the actual `docs +fetch` symbols `<image token="...">`
and `<file token="...">` instead of `<img>` and `<source>`, keeping the token
extraction guidance consistent with the documented fetch output.
- Around line 37-39: The media routing guidance for URL inputs is inconsistent
with the insert flow and should not send agents to docs +update. Update the
references in lark-doc-media.md so the URL case points to the same handling as
the sibling insert guidance and operation matrix: either download the media and
use --file or route through the appropriate drive-related flow, while keeping
the --from-clipboard and local-path branches unchanged.
In `@skills/lark-doc/references/lark-doc-search.md`:
- Line 56: Scope the direct-fetch rule in the search routing guidance to
Docx/Wiki only, since spreadsheet/base flows are handled separately. Update the
wording in lark-doc-search.md so the “if user explicitly provides URL/token,
fetch directly” behavior is tied to Docx/Wiki URL/token cases, using the command
index and operation matrix as the reference for the routing distinction.
In `@skills/lark-doc/SKILL.md`:
- Around line 32-35: The prerequisite list in SKILL.md is ordered inconsistently
with the matrix-first guidance; update the “常用必读文件” entries so
lark-doc-operation-matrix.md appears before lark-doc-command-index.md, keeping
../lark-shared/SKILL.md first. Make sure the surrounding wording in the
prerequisites section stays aligned with the entrypoint guidance used elsewhere
in the document.
🪄 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: 3aa566fa-716f-4b8a-9611-b30030b238df
📒 Files selected for processing (5)
skills/lark-doc/SKILL.mdskills/lark-doc/references/lark-doc-command-index.mdskills/lark-doc/references/lark-doc-media.mdskills/lark-doc/references/lark-doc-operation-matrix.mdskills/lark-doc/references/lark-doc-search.md
Comment on lines
+37
to
+39
| - 用户说“截图、剪切板、刚复制的图” → `--from-clipboard` | ||
| - 用户给本地路径 → `--file <path>` | ||
| - 用户给 URL → 可用 `docs +update` 直接插入 `<img href="https://..."/>`，或先下载再 `--file` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Don't route URL inserts through docs +update.
This URL path conflicts with the sibling insert guidance and the operation matrix, which route media URLs to --file/download or drive-related flows instead. As written, agents will be sent down the wrong command path.
Proposed fix
- - 用户给 URL → 可用 `docs +update` 直接插入 `<img href="https://..."/>`，或先下载再 `--file`
+ - 用户给 URL → 先下载到本地再用 `--file`，或按对应的 drive/insert 流程处理📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - 用户说“截图、剪切板、刚复制的图” → `--from-clipboard` | |
| - 用户给本地路径 → `--file <path>` | |
| - 用户给 URL → 可用 `docs +update` 直接插入 `<img href="https://..."/>`，或先下载再 `--file` | |
| - 用户说“截图、剪切板、刚复制的图” → `--from-clipboard` | |
| - 用户给本地路径 → `--file <path>` | |
| - 用户给 URL → 先下载到本地再用 `--file`，或按对应的 drive/insert 流程处理 |
🤖 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-media.md` around lines 37 - 39, The media
routing guidance for URL inputs is inconsistent with the insert flow and should
not send agents to docs +update. Update the references in lark-doc-media.md so
the URL case points to the same handling as the sibling insert guidance and
operation matrix: either download the media and use --file or route through the
appropriate drive-related flow, while keeping the --from-clipboard and
local-path branches unchanged.
Comment on lines
+54
to
+60
| 用于预览正文图片或附件素材。token 从 `docs +fetch` 返回的 `<img>` / `<source>` 中提取。 | ||
|
|
||
| ```bash | ||
| lark-cli docs +media-preview --token "Z1Fjxxxxxxxx" --output ./asset | ||
| ``` | ||
|
|
||
| `--output` 不带扩展名时，CLI 会根据响应类型自动补全。 |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Fix the token tag names for fetch output.
docs +fetch is documented elsewhere as yielding <image token="..."> / <file token="...">, not <img> / <source>. If this stays unchanged, agents will look for the wrong tags and miss the media token.
Proposed fix
- 用于预览正文图片或附件素材。token 从 `docs +fetch` 返回的 `<img>` / `<source>` 中提取。
+ 用于预览正文图片或附件素材。token 从 `docs +fetch` 返回的 `<image>` / `<file>` 节点中提取。📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 用于预览正文图片或附件素材。token 从 `docs +fetch` 返回的 `<img>` / `<source>` 中提取。 | |
| ```bash | |
| lark-cli docs +media-preview --token "Z1Fjxxxxxxxx" --output ./asset | |
| ``` | |
| `--output` 不带扩展名时，CLI 会根据响应类型自动补全。 | |
| 用于预览正文图片或附件素材。token 从 `docs +fetch` 返回的 `<image>` / `<file>` 节点中提取。 | |
🤖 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-media.md` around lines 54 - 60, The
media-preview docs use the wrong fetch output tag names; update the wording in
lark-doc-media.md where `docs +media-preview` is described so it refers to the
actual `docs +fetch` symbols `<image token="...">` and `<file token="...">`
instead of `<img>` and `<source>`, keeping the token extraction guidance
consistent with the documented fetch output.
|
|
||
| - 不要把搜索摘要当正文事实来源；需要准确内容必须 fetch 目标文档。 | ||
| - 搜索是 discovery 能力，不负责正文 block 操作。 | ||
| - 如果用户明确给了 URL/token，不要先 search 再 fetch，直接 fetch。 |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Scope the direct-fetch rule to Docx/Wiki only.
“URL/token” is too broad here: spreadsheet/base cases already have separate routing, so this line should say Docx/Wiki URL/token explicitly to avoid sending non-doc search hits into the wrong flow. Based on the command index and operation matrix.
🛠️ Suggested wording
-- 如果用户明确给了 URL/token，不要先 search 再 fetch，直接 fetch。
+- 如果用户明确给了 Docx/Wiki URL/token，且目标是正文内容，不要先 search 再 fetch，直接 fetch。📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - 如果用户明确给了 URL/token，不要先 search 再 fetch，直接 fetch。 | |
| - 如果用户明确给了 Docx/Wiki URL/token，且目标是正文内容，不要先 search 再 fetch，直接 fetch。 |
🤖 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-search.md` at line 56, Scope the
direct-fetch rule in the search routing guidance to Docx/Wiki only, since
spreadsheet/base flows are handled separately. Update the wording in
lark-doc-search.md so the “if user explicitly provides URL/token, fetch
directly” behavior is tied to Docx/Wiki URL/token cases, using the command index
and operation matrix as the reference for the routing distinction.
fangshuyu-768
force-pushed
the
codex/lark-doc-skill-structure
branch
from
5e7618a to
1003542
Compare
github-actions
Bot
added
size/M
fangshuyu-768
force-pushed
the
codex/lark-doc-skill-structure
branch
2 times, most recently
from
bd3aba0 to
9a0e86e
Compare
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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/SKILL.md`:
- Around line 26-30: The prerequisite order in SKILL.md is inconsistent: the
matrix-first rule conflicts with the shared-SKILL-first rule. Update the section
to use one clear sequence and make it consistent across the text, referencing
lark-doc-operation-matrix.md and ../lark-shared/SKILL.md so readers know which
must be read first before any operation-specific reference.
- Line 37: The Markdown guidance in SKILL.md is too narrow and can cause agents
to miss the `.md` import path. Update the “创建或编辑文档内容” entry so it points to
lark-doc-md.md not only when the user explicitly asks for Markdown, but also
when the input is a Markdown file/import; keep the XML and workflow references
intact, and make the condition clear near the existing lark-doc-xml.md and
lark-doc-md.md symbols.
🪄 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: 51c653cc-b38b-47d7-807e-5ad0434b2f95
📒 Files selected for processing (3)
skills/lark-doc/SKILL.mdskills/lark-doc/references/lark-doc-command-index.mdskills/lark-doc/references/lark-doc-operation-matrix.md
🚧 Files skipped from review as they are similar to previous changes (2)
- skills/lark-doc/references/lark-doc-command-index.md
- skills/lark-doc/references/lark-doc-operation-matrix.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-operation-matrix.md`:
- Around line 11-16: The style doc links in the operation matrix are resolving
from references/ instead of the sibling style/ directory, so update the affected
markdown references in the lark-doc-operation-matrix table to use the correct
relative paths. Fix the entries that point to style/lark-doc-style.md,
style/lark-doc-create-workflow.md, and style/lark-doc-update-workflow.md so
navigation works correctly from references/.
🪄 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: e3d3bc6b-0268-4ea7-bc3b-dc5839cb046c
📒 Files selected for processing (3)
skills/lark-doc/SKILL.mdskills/lark-doc/references/lark-doc-command-index.mdskills/lark-doc/references/lark-doc-operation-matrix.md
✅ Files skipped from review due to trivial changes (1)
- skills/lark-doc/references/lark-doc-command-index.md
🚧 Files skipped from review as they are similar to previous changes (1)
- skills/lark-doc/SKILL.md
Comment on lines
+11
to
+16
| | 创建短文档 | `docs +create --api-version v2` | [`lark-doc-create.md`](lark-doc-create.md), [`lark-doc-xml.md`](lark-doc-xml.md) 或 [`lark-doc-md.md`](lark-doc-md.md) | [`style/lark-doc-style.md`](style/lark-doc-style.md) | 默认 XML；用户提供 `.md` 或明确要求 Markdown 时用 Markdown | | ||
| | 创建较长文档 | `docs +create --api-version v2` 建骨架，再 `docs +update --command block_insert_after` 分段 | [`lark-doc-create.md`](lark-doc-create.md), [`lark-doc-update.md`](lark-doc-update.md), [`style/lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md), [`lark-doc-xml.md`](lark-doc-xml.md) | [`style/lark-doc-style.md`](style/lark-doc-style.md), [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) | 先建标题骨架，再按章节 block id 分段写入；避免把超长正文一次塞进 `--content` | | ||
| | 简单旧文本到新文本替换 | `docs +update --api-version v2 --command str_replace` | [`lark-doc-update.md`](lark-doc-update.md), [`lark-doc-xml.md`](lark-doc-xml.md) 或 [`lark-doc-md.md`](lark-doc-md.md) | | XML 模式只支持行内匹配；跨段/跨 block 使用 block 级操作或 Markdown 模式 | | ||
| | 精准 block 级插入、替换、删除、移动或复制 | `docs +fetch` 定位 block id，再 `docs +update --command block_*` | [`lark-doc-fetch.md`](lark-doc-fetch.md), [`lark-doc-update.md`](lark-doc-update.md), [`lark-doc-xml.md`](lark-doc-xml.md) | [`style/lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) | 优先局部 fetch；连续写操作必须遵守 block id 生命周期，受影响 ID 不要复用 | | ||
| | 改写、润色、补充或重排已有文档 | `docs +fetch` 局部读取，再 `docs +update` 精准修改 | [`lark-doc-fetch.md`](lark-doc-fetch.md), [`lark-doc-update.md`](lark-doc-update.md), [`style/lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md), [`lark-doc-xml.md`](lark-doc-xml.md) | [`style/lark-doc-style.md`](style/lark-doc-style.md), [`lark-doc-whiteboard.md`](lark-doc-whiteboard.md) | 精准手术优于全文覆盖；保留原文中的 @人、@文档、图片、附件、画板、sheet、bitable、synced_reference 等 token 和属性 | | ||
| | 用户明确要求全文重建 | `docs +update --api-version v2 --command overwrite` | [`lark-doc-update.md`](lark-doc-update.md), [`lark-doc-xml.md`](lark-doc-xml.md) 或 [`lark-doc-md.md`](lark-doc-md.md) | [`style/lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md) | `overwrite` 会清空文档后重写，可能丢失图片、评论等；只在用户明确要改整篇时使用 | |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the relative links to the style docs.
The style/... references here are relative to references/, so they currently resolve under references/style/ instead of the sibling style/ directory. That breaks these navigation links.
🛠️ Proposed fix
- [`style/lark-doc-style.md`](style/lark-doc-style.md)
+ [`style/lark-doc-style.md`](../style/lark-doc-style.md)
- [`style/lark-doc-create-workflow.md`](style/lark-doc-create-workflow.md)
+ [`style/lark-doc-create-workflow.md`](../style/lark-doc-create-workflow.md)
- [`style/lark-doc-update-workflow.md`](style/lark-doc-update-workflow.md)
+ [`style/lark-doc-update-workflow.md`](../style/lark-doc-update-workflow.md)Also applies to: 22-23
🤖 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-operation-matrix.md` around lines 11 -
16, The style doc links in the operation matrix are resolving from references/
instead of the sibling style/ directory, so update the affected markdown
references in the lark-doc-operation-matrix table to use the correct relative
paths. Fix the entries that point to style/lark-doc-style.md,
style/lark-doc-create-workflow.md, and style/lark-doc-update-workflow.md so
navigation works correctly from references/.
ef67376 to
dab0550
Compare
fangshuyu-768
force-pushed
the
codex/lark-doc-skill-structure
branch
from
dab0550 to
f0d5e7b
Compare
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
Tests