docs: prefer local comments for drive reviews

[wittam-01]

Summary

Clarify lark-drive skill guidance for review and document-audit scenarios. The updated guidance steers agents to prefer localized comments whenever a concrete document position can be identified, instead of collecting all findings into a single full-document comment.

Changes

• Add explicit review guidance to lark-drive that defaults to local comments for review, proofreading, issue marking, and per-finding feedback.

Test Plan

• Documentation-only change; no unit tests required.
• git diff --check

Related Issues

• None

Summary by CodeRabbit

• Documentation
  • Clarified review guidance: prioritize localized, targeted comments for individual issues rather than consolidating into full-document comments.
  • Added explicit rules for review scenarios: prefer per-item local comments; use full-document comments only when requested or when stable localization isn’t possible.
  • Documented supported localization formats for text, spreadsheet cells, and slide elements and examples for pinpointing comment locations.

[coderabbitai]

📝 Walkthrough

Walkthrough

Updates Lark Drive docs to require preferring local (block/cell/slide-element) comments for review scenarios, adding a “Review 场景评论落点” guideline and expanding drive +add-comment reference to include block-id formats for sheet/slides and separate comments per issue.

Changes

Review Scenario Comment Placement Guidance

Layer / File(s)	Summary
Review comment placement rules and guidance skills/lark-drive/SKILL.md	Expands drive +add-comment local-comment positioning formats and adds a “Review 场景评论落点” guideline: prefer local comments pinned to specific elements, create separate local comments for independent issues, and only use full-document comments when explicitly requested, unsupported, or unlocatable. References drive +add-comment for locating/parameter details.
drive +add-comment reference update skills/lark-drive/references/lark-drive-add-comment.md	Adds a rule requiring review scenarios to locate specific blocks/cells/slides and create separate local comments per issue, and expands --block-id applicability to include sheet in addition to docx/slides.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• larksuite/cli#967: Complementary updates to lark-drive-add-comment.md about drive +add-comment local comment constraints and slide scenarios.
• larksuite/cli#674: Related edits around slides --block-id format and distinctions between local and full-document comments.

Suggested labels

domain/ccm

Suggested reviewers

• fangshuyu-768

Poem

🐰✍️ I hop through lines and leave a trace,
Local notes for every spot and place.
Block-ids guide my careful art,
One issue, one comment — precise from the start.
Hooray for clarity, every part!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'docs: prefer local comments for drive reviews' is clear, concise, and directly summarizes the main change—updating documentation to prioritize localized comments in review scenarios.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The pull request description follows the required template with all major sections present (Summary, Changes, Test Plan, Related Issues) and provides clear, substantive information about the documentation updates to the lark-drive skill.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/drive-comment-local-review-guidance

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

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-drive/references/lark-drive-add-comment.md`:
- Line 160: The Behavior section "Review 场景优先局部评论" mandates local
block/cell/slide comments but the `--block-id` mode description only lists
`docx` and `slides`; update the `--block-id` mode documentation to also include
`sheet` (e.g., add `sheet` to the supported modes for `--block-id`) and adjust
any examples or mode lists in the same section so they consistently reflect that
`sheet` is supported for block-local comments.

In `@skills/lark-drive/SKILL.md`:
- Around line 143-145: The SKILL.md section that currently states local comments
are supported only for `docx` (or wiki→`docx`) conflicts with the new rule
requiring local comments for `docx/sheet/slides`; update the capability
statement to explicitly include `sheet` and `slides` alongside `docx` (and
remove or revise the wiki→docx special-case) so the guidance is consistent; make
the same change in the other occurrence covering the same paragraph (the block
that lists the three bullet points about using `--block-id` and per-issue local
comments) to keep both mentions aligned.

🪄 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: d65b48b3-47a6-4e29-a2f0-f3512cac8d3a

📥 Commits

Reviewing files that changed from the base of the PR and between d793790 and 68fb0bf.

📒 Files selected for processing (2)

• skills/lark-drive/SKILL.md
• skills/lark-drive/references/lark-drive-add-comment.md

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 67.58%. Comparing base (d793790) to head (89bc5ab).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #981      +/-   ##
==========================================
+ Coverage   67.41%   67.58%   +0.17%     
==========================================
  Files         572      575       +3     
  Lines       53697    54269     +572     
==========================================
+ Hits        36200    36679     +479     
- Misses      14489    14548      +59     
- Partials     3008     3042      +34     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

npm i -g https://pkg.pr.new/larksuite/cli/@larksuite/cli@89bc5abedee9e93421863e67252bceb75353f984

🧩 Skill update

npx skills add larksuite/cli#docs/drive-comment-local-review-guidance -y -g

[coderabbitai]

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-drive/SKILL.md`:
- Around line 189-190: Update the fallback rule sentence in SKILL.md (the line
that currently allows falling back to 全文评论 when “无法稳定定位”) to require the target
supports full-document comments by adding the clause “且目标类型支持全文评论”; specifically
change the sentence that begins with
“只有在用户明确要求全文/总体评论、评论内容确实是文档级总结、目标类型不支持局部评论，或无法稳定定位到具体位置时，才退回全文评论” to include
“且目标类型支持全文评论” so the fallback is gated, and ensure the nearby reference to
`drive +add-comment` behavior remains accurate.

🪄 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: fc67c0d7-a3f4-4fd3-8198-873427448a62

📥 Commits

Reviewing files that changed from the base of the PR and between 68fb0bf and 8a254d3.

📒 Files selected for processing (2)

• skills/lark-drive/SKILL.md
• skills/lark-drive/references/lark-drive-add-comment.md

✅ Files skipped from review due to trivial changes (1)

• skills/lark-drive/references/lark-drive-add-comment.md