docs: add drive comment location guidance

[wittam-01]

Summary

Adds guidance for locating document comments using need_relation=true, relation block IDs, and embedded resource parent metadata.

Changes

• Link the lark-drive skill to a new comment location reference for review/comment mapping workflows.
• Document relation parsing, positionInfo.blockID matching, parent_type / parent_token handling, and accuracy levels.
• Add follow-up guidance for Sheet, Base/Bitable, and Whiteboard internal comments.

Test Plan

• git diff --check HEAD~1..HEAD
• Unit tests pass — not run; documentation-only Skill change.
• Manual local verification confirms the lark-cli <domain> <command> flow works as expected — not run; guidance-only Skill change.

Related Issues

• None

Summary by CodeRabbit

• Documentation
  • Added guidance requiring use of the new "快速决策" rule and enabling need_relation=true when locating comments to document content.
  • New section describing how comment relation data maps to document positions, including using relation to resolve block IDs.
  • Documented workflows for locating comments inside embedded content (parent_type/parent_token) and fallback strategies.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 3e4fff9f-93a6-4d0c-85be-ae40667f1d6c

📥 Commits

Reviewing files that changed from the base of the PR and between ef3e9c0 and dbe35be.

📒 Files selected for processing (2)

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

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

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

---

📝 Walkthrough

Walkthrough

SKILL.md adds routing rules requiring need_relation=true for comment-to-body positioning and points to a new reference. The reference defines field semantics (relation, parent_type, parent_token), shows how to parse relation.relation to extract block IDs via docs +fetch --detail with-ids, and prescribes a priority flow for embedded resources and quote fallbacks.

Changes

Lark Drive comment-location positioning

Layer / File(s)	Summary
SKILL.md routing to comment-location reference skills/lark-drive/SKILL.md	Quick-decision rule and comment-positioning-fields guidance direct users to the comment-location reference and require need_relation=true in comment queries.
Comment-location reference: objectives, usage, and field semantics skills/lark-drive/references/lark-drive-comment-location.md	Documents applicability (docx support), how to set need_relation for paged/batched queries, how to fetch docs with --detail with-ids, and defines relation/parent_type/parent_token with a three-tier accuracy classification.
Comment-location reference: positioning examples and end-to-end flow skills/lark-drive/references/lark-drive-comment-location.md	Examples show parsing relation.relation JSON to extract positionInfo.blockID, matching blocks in fetched docs, and the ordered workflow: relation → parent-embedding → quote fallback.
Comment-location reference: embedded resources guidance and usage principles skills/lark-drive/references/lark-drive-comment-location.md	Per-embed guidance: Sheets (cell coord + lark-sheets verification), Bitable/Base (parent_token parsing + lark-base drill-down, pagination handling), Whiteboard (raw-node reads + text-match confirmation). Emphasizes preferring block-id over quote.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• larksuite/cli#981: Both PRs update skills/lark-drive comment/positioning guidance—this PR adds need_relation=true and field-priority mapping; the related PR updates comment placement and local comment guidance.

Suggested labels

domain/ccm

Suggested reviewers

• fangshuyu-768
• SunPeiYang996

Poem

🐰 A rabbit hops through comment trails,
Parsing relations and parent tales,
From docx blocks to sheets and boards,
need_relation=true opens location doors,
I nibble paths and leave bright trails ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately and concisely summarizes the main change—adding documentation guidance for locating drive comments—which aligns with the changeset contents.
Description check	✅ Passed	The description covers all required template sections: Summary, Changes, Test Plan, and Related Issues. It provides clear context about the guidance additions and testing approach.
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.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/drive-comment-location-skill

---

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.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 70.33%. Comparing base (b216363) to head (dbe35be).
⚠️ Report is 32 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1258      +/-   ##
==========================================
+ Coverage   69.19%   70.33%   +1.13%     
==========================================
  Files         634      672      +38     
  Lines       59482    65322    +5840     
==========================================
+ Hits        41161    45941    +4780     
- Misses      15007    15728     +721     
- Partials     3314     3653     +339     

☔ View full report in Codecov by Harness.
📢 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@dbe35be23206bc3ad8f741f74d76c6a3a3e49ace

🧩 Skill update

npx skills add larksuite/cli#docs/drive-comment-location-skill -y -g