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, 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 in-file comment rules and added a dedicated comments reference covering modes, queries/paging/stats, replies/reactions, examples, and positioning notes.
  • Added a permissions guide with error-handling, bot-authorization workflow, and removed the embedded permission table.
  • Added wiki-token routing reference and inspect/unpack guidance; consolidated shortcuts and noted quota detail requirements.

[coderabbitai]

Note

Reviews paused

It 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 reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 2d95875d-436f-4eb4-ad64-ad4ddfa920c9

📥 Commits

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

📒 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

💤 Files with no reviewable changes (5)

• 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
• skills/lark-drive/references/lark-drive-comments-guide.md
• 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 directly summarizes the main change: optimizing lark-drive skill routing as reflected in the raw summary and description.
Description check	✅ Passed	The description covers required sections (Summary, Changes, Test Plan, Related Issues) with sufficient detail and includes verification steps demonstrating the changes were tested appropriately.
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 71.90%. Comparing base (7fdf558) to head (dba9ac6).

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1284   +/-   ##
=======================================
  Coverage   71.90%   71.90%           
=======================================
  Files         691      691           
  Lines       65629    65629           
=======================================
+ Hits        47191    47193    +2     
+ Misses      14791    14790    -1     
+ Partials     3647     3646    -1     

☔ 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@dba9ac6887ee435975a508b11d53c7e3e0333cd8

🧩 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