docs: optimize lark-drive skill routing

[wittam-01]

Summary

Optimize the lark-drive skill routing and main skill size while preserving core Drive capabilities and detailed guidance through references.

Changes

• Shorten the lark-drive description and add explicit NOT routing to related Lark skills.
• Front-load shortcut guidance, keep core Drive resource coverage discoverable, and restore key +sync behavior details in SKILL.md.
• Move comment and permission details into focused references, add shared Wiki token routing, and update reaction prerequisites.

Test Plan

• Unit tests pass (not run; skill documentation-only change)
• Manual local verification confirms the lark-cli <domain> <command> flow works as expected via skill/doc checks below
• git diff --check
• node scripts/skill-format-check/index.js
• bash scripts/check-doc-tokens.sh skills/lark-drive
• bash scripts/check-doc-tokens.sh skills/lark-shared
• Local Markdown link check for changed skill references

Related Issues

• None

Summary by CodeRabbit

• Documentation
  • Reorganized Drive docs: clarified scope, terminology, and cloud URL/token routing by resource-type + path + token (no domain fallback); added import-first rule for certain file types and a quick-decision routing note.
  • Condensed detailed in-file comment rules and added a dedicated comments reference covering modes, queries/paging/stats, replies/reactions and examples.
  • Added a permissions guide with error-handling and bot-authorization workflow; removed the in-file permission table.
  • Added wiki-token routing reference and inspect/unpack guidance.

[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: d00d8ba7-5b6a-4330-a68b-f26591a55a1e

📥 Commits

Reviewing files that changed from the base of the PR and between 0545e0d and 1ee1b5e.

📒 Files selected for processing (2)

• skills/lark-drive/SKILL.md
• skills/lark-drive/references/lark-drive-permission-guide.md

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

• skills/lark-drive/references/lark-drive-permission-guide.md

🚧 Files skipped from review as they are similar to previous changes (1)

• skills/lark-drive/SKILL.md

---

📝 Walkthrough

Walkthrough

Condenses skills/lark-drive/SKILL.md into focused entry points, delegates comment, permission, reactions, and wiki-token routing details into new reference guides, updates shortcuts and doubao.com routing rules, and removes the in-file permission table.

Changes

Drive Skill Documentation Restructuring

Layer / File(s)	Summary
SKILL.md core restructuring and entry points skills/lark-drive/SKILL.md	Updated skill description with scope boundaries and doubao.com routing rules; added terminology and import-splitting rule; reworked core concepts to focus on URL/token handling and /wiki/ unpacking via drive +inspect; condensed comment entry, added permission entry, consolidated shortcuts, removed in-file permission table.
Drive comments capability reference guide skills/lark-drive/references/lark-drive-comments-guide.md	New guide covering comment modes, supported file types, --content/reply_elements format and escaping, default unresolved-only queries, comment card/statistics and pagination rules, sorting, reply limits, batch_query vs list, and native V2 API usage with schema/anchor examples.
Drive permission and authorization reference guide skills/lark-drive/references/lark-drive-permission-guide.md	New guide documenting when to handle Drive permissions, public permission error codes (91009–91012) with user-facing resolution steps and URL-return rules for 91011/91012, and a two-step flow to authorize the current app (bot) using bot.open_id and drive permission.members create.
Wiki routing and reactions guide alignment skills/lark-shared/references/lark-wiki-token-routing.md, skills/lark-drive/references/lark-drive-reactions.md	Added wiki-token routing reference explaining /wiki/<token> unpacking to obj_type/obj_token (recommended drive +inspect, manual wiki spaces get_node fallback) and updated reactions guide prerequisite to reference SKILL.md comment entry.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• larksuite/cli#1082: Overlaps on doubao.com URL/token routing refinements for lark-drive.
• larksuite/cli#947: Related wiki-link handling and drive +inspect recommendations.
• larksuite/cli#863: Related permission error-code guidance for drive permission flows.

Suggested labels

domain/ccm

Suggested reviewers

• fangshuyu-768
• kongenpei

Poem

🐰 I hopped through Drive docs, tidy and spry,
Shortcuts aligned, wiki tokens unwrapped by and by,
Comments moved to guides with paging rules neat,
Permissions and reactions now live in their seat,
A rabbit's rewrite—compact, clear, and spry!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the main objective of optimizing lark-drive skill routing and is concise and clear.
Description check	✅ Passed	The PR description follows the template structure with Summary, Changes, Test Plan, and Related Issues sections, all clearly filled with relevant details.
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/lark-drive-skill-routing

---

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 (2f4e2c3) to head (1ee1b5e).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1284      +/-   ##
==========================================
+ Coverage   70.17%   70.33%   +0.15%     
==========================================
  Files         671      672       +1     
  Lines       65329    65322       -7     
==========================================
+ Hits        45847    45941      +94     
+ Misses      15794    15728      -66     
+ Partials     3688     3653      -35     

☔ 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@1ee1b5ec425ea96c66a6827bc194ab33c0e43ed9

🧩 Skill update

npx skills add larksuite/cli#docs/lark-drive-skill-routing -y -g

[coderabbitai]

🧹 Nitpick comments (1)

skills/lark-drive/references/lark-drive-permission-guide.md (1)

16-16: 💤 Low value

Consider clarifying the URL recovery process.

The guidance to "recover URL from context, search results, or metadata" when only a token is available could benefit from a concrete example or reference to the drive +inspect capability mentioned in the main SKILL.md. This would help implementers understand the recommended recovery workflow.

🤖 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-drive/references/lark-drive-permission-guide.md` at line 16, The
guidance is vague about recovering a document URL from a token (when error codes
91011/91012 occur); update the text to include a concrete recovery workflow:
when only a token is available, first call the drive +inspect capability with
the token to retrieve metadata (title, fileId, path), then attempt to
reconstruct the document URL from returned fileId/path; if +inspect fails, fall
back to a search by title or SHA using available context and search results, and
finally present the reconstructed URL as a clickable link; mention the specific
use of "drive +inspect" and the token error codes (91011/91012) so implementers
know the exact steps to follow.

🤖 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-drive/references/lark-drive-permission-guide.md`:
- Line 16: The guidance is vague about recovering a document URL from a token
(when error codes 91011/91012 occur); update the text to include a concrete
recovery workflow: when only a token is available, first call the drive +inspect
capability with the token to retrieve metadata (title, fileId, path), then
attempt to reconstruct the document URL from returned fileId/path; if +inspect
fails, fall back to a search by title or SHA using available context and search
results, and finally present the reconstructed URL as a clickable link; mention
the specific use of "drive +inspect" and the token error codes (91011/91012) so
implementers know the exact steps to follow.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b4784842-b8f6-414d-a1d9-252ebff6d213

📥 Commits

Reviewing files that changed from the base of the PR and between 2f4e2c3 and eea9ba9.

📒 Files selected for processing (5)

• skills/lark-drive/SKILL.md
• skills/lark-drive/references/lark-drive-comments-guide.md
• skills/lark-drive/references/lark-drive-permission-guide.md
• skills/lark-drive/references/lark-drive-reactions.md
• skills/lark-shared/references/lark-wiki-token-routing.md