docs: add lark-drive permission governance workflow

[jiangguozhou]

Summary

Add and refine the registered permission_governance workflow for lark-drive so AI agents can audit, report, and govern Drive / Docs / Wiki permission risks with explicit capability boundaries and write-safety gates. This update also aligns owner-transfer routing, public-permission semantic rendering, and user-facing output templates with the current CLI schema and official OpenAPI terminology.

Changes

• Register permission governance routing for owner transfer and batch owner transfer from SKILL.md through the workflow registry.
• Refine permission governance runtime rules for single-target, explicit-list, and container permission diagnostics without duplicating logic.
• Improve semantic rendering for document public access and collaboration settings, including current-schema vs official-field boundaries.
• Clarify confirmation and final-summary wording so asynchronous permission-request approval is not confused with owner transfer.
• Add command and output guidance for owner transfer, secure-label preflight, stable risk IDs, URL-backed risk lists, and actionable governance reports.

Test Plan

• node scripts/skill-format-check/index.js passed
• bash scripts/check-doc-tokens.sh skills/lark-drive passed
• bash scripts/check-skill-wire-vocab.sh passed
• git diff --check -- skills/lark-drive/SKILL.md skills/lark-drive/references/lark-drive-workflow.md skills/lark-drive/references/lark-drive-workflow-permission-governance.md skills/lark-drive/references/lark-drive-workflow-permission-governance-outputs.md skills/lark-drive/references/lark-drive-workflow-permission-governance-commands.md passed
• Manual CLI schema validation:
  • lark-cli schema drive.permission.public.get --format json
  • lark-cli schema drive.permission.members.transfer_owner --format json
• GitHub Actions tests and lint pass after push

Related Issues

• None

Summary by CodeRabbit

• New Features

  • Added a permission-governance workflow to audit and manage document permissions, sharing scope, external access, copy/download rights, owner transfers, security labels, and generate permission-risk reports with actionable remediation and confirmation steps.

• Documentation

  • Added comprehensive docs and templates: workflow protocols, step-by-step procedures, CLI command examples, output/ rendering rules, risk/report formats, dry-run/confirmation flows, bulk operation and owner-transfer guidance.

[CLAassistant]

All committers have signed the CLA.

[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: 3e0b65a9-8fbc-4a91-88a0-bcf2559dd156

📥 Commits

Reviewing files that changed from the base of the PR and between deae4f6 and b31981f.

📒 Files selected for processing (1)

• skills/lark-drive/references/lark-drive-workflow-permission-governance-commands.md

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

• skills/lark-drive/references/lark-drive-workflow-permission-governance-commands.md

---

📝 Walkthrough

Walkthrough

Adds comprehensive lark-drive documentation and SKILL routing for a new permission_governance workflow: master workflow framework, the permission_governance specification with state machine and rules, a CLI command reference, detailed user-facing output templates, and SKILL.md routing to the workflow.

Changes

Permission Governance Workflow System

Layer / File(s)	Summary
Master workflow framework and execution protocol skills/lark-drive/references/lark-drive-workflow.md	Establishes the lark-drive workflow master framework: registry-based routing, execution skeleton (route→scope→read→assess/plan→confirm→execute→verify→done), artifact and entry contracts, Risk/Structure gates (R0–R3, S1–S3), loading/split boundaries, registry example including permission_governance, and unregistered-workflow handling rules.
Permission governance workflow specification skills/lark-drive/references/lark-drive-workflow-permission-governance.md	Defines permission_governance scope/non-targets, progressive load map, runtime state extensions, full execution state machine (Parse→Discovery→Read Facts→Assess→Plan→Confirm→Execute→Verify→Done), allowed command families, container discovery and fact-read rules, risk classification/evidence labeling, write/confirmation/dry-run/rollback rules, batch/failure handling, and output constraints.
Permission governance command reference skills/lark-drive/references/lark-drive-workflow-permission-governance-commands.md	Provides lark-cli command examples organized by workflow stage: target resolution (Wiki space handling), discovery (node-list, folder file lists), fact reading (drive metas, permission.public, file.statistics, view_records), pre-write checks (manage-public auth), execution examples (permission.public patch, apply-permission, secure-label-update) and parameter placeholders.
Permission governance output templates skills/lark-drive/references/lark-drive-workflow-permission-governance-outputs.md	Specifies complete user-visible output templates and field mappings: output strategy and expansion rules, permission/link/exposure mappings, stable risk_id and URL/token fallbacks, audit and container diagnostic templates, actionable risk list schema, governance selection interaction rules, permission settings and access review templates, dry-run plan schema, batch and per-operation confirmation templates, and final recap/validation requirements.
Skill routing integration skills/lark-drive/SKILL.md	Adds a quick-decision rule routing permission-related tasks (permission risk reports, tightening permissions, requesting view/edit rights, sharing/public scope, external access, copy/download, secure labels, owner transfer) to read lark-drive-workflow.md and enter the permission_governance workflow.

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant Agent
  participant WorkflowRegistry
  participant PermissionGovernance
  participant DriveAPI
  User->>Agent: request permission governance
  Agent->>WorkflowRegistry: lookup workflow (permission_governance)
  WorkflowRegistry->>PermissionGovernance: load entry & references
  PermissionGovernance->>DriveAPI: discovery & fact read commands
  PermissionGovernance->>Agent: render diagnostics / request confirmation
  Agent->>PermissionGovernance: user confirmation
  PermissionGovernance->>DriveAPI: execute writes (permission/owner/label)
  PermissionGovernance->>DriveAPI: fresh read for verification
  PermissionGovernance->>Agent: final summary / verification results

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• larksuite/cli#1284: Changes to SKILL.md permission routing and entry points intersect with this workflow routing update.
• larksuite/cli#863: Overlaps on public permission patch guidance and scope/error handling related to permission governance.

Suggested labels

domain/ccm

Suggested reviewers

• fangshuyu-768
• wittam-01

Poem

🐰 I hopped through docs with careful paws,
I mapped the flows and listed laws.
From registry lookup to Drive's read,
I penned the commands and templates we need.
A rabbit's cheer — governance done with speed!

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the main change: adding documentation for a new lark-drive permission governance workflow.
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-permission-governance

---

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: 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/references/lark-drive-workflow-permission-governance-commands.md`:
- Around line 80-121: The doc currently shows +secure-label-update without first
listing available labels, which breaks the EXEC_CONFIRM contract; add a
secure-label enumeration example (using the command symbol +secure-label-list)
immediately before +secure-label-update in the "写前确认与执行" section so users can
discover label IDs to confirm, and ensure the example matches the flag style
used elsewhere (--token/--type/--label-id, --as user, --format json) to keep
consistency with permission.members auth and +secure-label-update entries.

🪄 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: fc2d23e3-1aaa-4e91-9927-5e9cf3e6b82f

📥 Commits

Reviewing files that changed from the base of the PR and between f3949f0 and 86bdd52.

📒 Files selected for processing (5)

• skills/lark-drive/SKILL.md
• skills/lark-drive/references/lark-drive-workflow-permission-governance-commands.md
• skills/lark-drive/references/lark-drive-workflow-permission-governance-outputs.md
• skills/lark-drive/references/lark-drive-workflow-permission-governance.md
• skills/lark-drive/references/lark-drive-workflow.md

[github-actions]

🚀 PR Preview Install Guide

🧰 CLI update

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

🧩 Skill update

npx skills add larksuite/cli#docs/lark-drive-permission-governance -y -g

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 72.83%. Comparing base (33e459a) to head (cbb6cf8).
⚠️ Report is 4 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1292   +/-   ##
=======================================
  Coverage   72.83%   72.83%           
=======================================
  Files         732      732           
  Lines       69140    69140           
=======================================
  Hits        50356    50356           
  Misses      15003    15003           
  Partials     3781     3781           

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

[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/references/lark-drive-workflow-permission-governance-commands.md`:
- Line 27: The wiki node-list command currently misdocuments/behaves for
pagination and subtree recursion: in shortcuts/wiki/wiki_node_list.go update the
pagination logic so that the --page-limit flag treats 0 as "unlimited" (i.e., no
cap), implement --page-all to iterate pages until no more results but still
respect a non-zero --page-limit as a hard cap, and ensure page-all only drains
pagination for the current space-id/parent-node-token scope (do not auto-recurse
into children); also ensure has_child remains a marker only and deeper traversal
requires explicit additional calls using --parent-node-token. Use the existing
flag variables/handlers for --page-all and --page-limit and the has_child check
in the node listing flow to locate where to change the loop/limit logic and
recursion behavior.

🪄 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: bfff7527-bee6-447b-af99-6706c751b004

📥 Commits

Reviewing files that changed from the base of the PR and between 0873d47 and deae4f6.

📒 Files selected for processing (5)

• skills/lark-drive/SKILL.md
• skills/lark-drive/references/lark-drive-workflow-permission-governance-commands.md
• skills/lark-drive/references/lark-drive-workflow-permission-governance-outputs.md
• skills/lark-drive/references/lark-drive-workflow-permission-governance.md
• skills/lark-drive/references/lark-drive-workflow.md

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

• skills/lark-drive/SKILL.md
• skills/lark-drive/references/lark-drive-workflow.md