docs(lark-shared): restructure into prioritized rules + on-demand references

[liangshuo-1]

Summary

lark-shared is force-loaded by nearly every lark-* skill, so its body is paid on almost every task. This rewrites the 168-line monolith into a slim always-loaded core plus on-demand references/.

The core is a positioning line + 7 mental-model rules (通用准则) ordered by agent attention priority: rules that fail silently or have no trigger (read-usage-first, identity, auth split-flow) come first; rules with loud self-announcing triggers or low frequency (exit-10 gate, relative-path, no-secrets) come last. Each rule states the why / boundary (the mental model); the how (mechanics, steps, field paths) lives in references loaded only when relevant.

Changes

• Progressive disclosure: the body carries only the resident safe-defaults; mechanics move to references/, named with the lark-shared- prefix to match the per-domain convention.
  • lark-shared-auth-split-flow.md — split-flow steps (marked must-read before initiating user auth)
  • lark-shared-high-risk-approval.md — exit-10 envelope forms, predict-before-running, --dry-run preview
  • lark-shared-identity-and-permissions.md — identity model, grant layers, scope-recovery flows
  • lark-shared-config-init.md — first-run config (blocking; no split-flow)
  • lark-shared-update-notice.md — _notice handling (update / skills / deprecated_command)
• Fix doc-vs-implementation drift (verified against the code):
  • exit-10 keys on exit code 10, not the type string; covers both the flat (type=confirmation_required) and typed (type=confirmation + subtype) envelopes; reads the confirm flag from hint (--yes / --force, varies by command).
  • distinguish permission_violations (raw API block) vs missing_scopes (CLI structured error).
  • complete _notice keys (update / skills / deprecated_command).
  • identity failure is silent-or-loud per command, not always an empty result.
• Misc: description switched to Chinese; version bumped 1.0.0 → 1.1.0.

Test plan

• lark-cli skills read lark-shared and each references/lark-shared-*.md resolve; no broken links (every references/…md target exists).
• Field paths / behaviors verified against the implementation: internal/cmdutil/confirm.go (flat envelope), errs/ (typed envelope), cmd/root.go (_notice keys), internal/vfs/localfileio/path.go (relative-path error + hint), internal/schema/assembler.go (yes field injection).
• Behavioral spot-checks on a live, authenticated lark-cli: the slim rules steer correct handling of exit-10 (stop + confirm, no silent --yes), bot/user identity selection, auth split-flow (QR + hand back control), and relative-path recovery.

Related

Alternative restructure of the same file as #1433.

Summary by CodeRabbit

• Documentation
  • Reorganized Lark CLI guidance into a condensed rule set with dedicated reference documents
  • Added documentation for authentication split-flow pattern
  • Added documentation for high-risk command approval gates
  • Added documentation for permission management and command identity
  • Added documentation for upgrade notifications in command output

[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: 3754450e-70ca-43a1-947a-7266ef734b06

📥 Commits

Reviewing files that changed from the base of the PR and between 0fbfe68 and 09d5c5d.

📒 Files selected for processing (6)

• skills/lark-shared/SKILL.md
• skills/lark-shared/references/lark-shared-auth-split-flow.md
• skills/lark-shared/references/lark-shared-config-init.md
• skills/lark-shared/references/lark-shared-high-risk-approval.md
• skills/lark-shared/references/lark-shared-identity-and-permissions.md
• skills/lark-shared/references/lark-shared-update-notice.md

---

📝 Walkthrough

Walkthrough

This PR refactors the Lark shared CLI skills documentation from a monolithic guide into a modular reference architecture. The main SKILL.md is condensed to a short checklist, with detailed workflows for authentication, identity, approval gating, and lifecycle notifications moved to five dedicated reference documents.

Changes

Shared Skills Documentation Restructuring

Layer / File(s)	Summary
Main SKILL.md condensed checklist and reference architecture skills/lark-shared/SKILL.md	SKILL.md version bumped to 1.1.0; replaced comprehensive prior guidance with short "通用准则" rules checklist (identity via --as, non-blocking auth split-flow, QR/verification URLs, exit-code 10 approval gate, cwd-relative paths, no plaintext secrets) and "其他场景" section pointing to separate reference docs for config init, wiki tokens, and update notices.
Auth split-flow and config init references skills/lark-shared/references/lark-shared-auth-split-flow.md, skills/lark-shared/references/lark-shared-config-init.md	Two-stage auth login split-flow: first call with --no-wait --json obtains verification_url/device_code without polling; second call with --device-code completes polling after user confirmation. Rules prohibit caching tokens and require explicit scopes. Config init flow is blocking (config init --new), run in background to extract auth URL without split-flow pattern.
Identity semantics and high-risk approval gating skills/lark-shared/references/lark-shared-identity-and-permissions.md, skills/lark-shared/references/lark-shared-high-risk-approval.md	Identity (--as user vs --as bot) determines auth source, resource access, and failure behavior; identity-based recovery paths for permission violations and missing scopes. High-risk commands identified by exit code 10 envelope; field extraction from error JSON; approval flow with optional --dry-run preview; distinction between risk-marked commands and actual gate triggering.
Update notice lifecycle handling skills/lark-shared/references/lark-shared-update-notice.md	_notice field in JSON output signals three categories (update, skills, deprecated_command); none should be silently ignored. Users complete current request, then proactively run lark-cli update (with optional --check); after updating, restart agent to load latest skills.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• larksuite/cli#1201: Both PRs align on the same Lark auth split-flow guidance; main PR reshapes shared Skills docs to reference the split-flow while retrieved PR updates cmd/auth/login.go's --no-wait --json hint to match the non-blocking, two-step --device-code flow.
• larksuite/cli#505: Main PR consolidates "身份与权限处理" (identity and permissions) guidance in shared docs, which is routed by retrieved PR's lark-base skill as a downstream workflow for handling permission/scope errors.
• larksuite/cli#1319: Both PRs update skills/lark-shared/SKILL.md to document and enforce cwd-relative path restrictions (rejecting absolute paths).

Suggested labels

documentation, domain/ccm, size/M

Suggested reviewers

• fangshuyu-768
• zhouyue-bytedance

Poem

🐰 A checklist trimmed, five guides now bloom,
Auth flows split, approval's doom,
Identity clear, permissions bright,
Updates whisper, skills take flight! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately describes the main change: restructuring lark-shared from a monolithic document into a slim core with prioritized rules plus on-demand references.
Description check	✅ Passed	The description provides comprehensive context including summary, detailed changes with file references, thorough test plan with specific implementation files and behaviors, and related issue reference; all required template sections are present and well-filled.
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-shared-restructure

---

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 72.88%. Comparing base (e1af7e3) to head (09d5c5d).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1450   +/-   ##
=======================================
  Coverage   72.88%   72.88%           
=======================================
  Files         738      738           
  Lines       69553    69553           
=======================================
  Hits        50695    50695           
  Misses      15043    15043           
  Partials     3815     3815           

☔ 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@09d5c5d99b3b6562faeda9c60f678d8dcf5a38b0

🧩 Skill update

npx skills add larksuite/cli#docs/lark-shared-restructure -y -g