docs(approval): clarify user identity scope limitations

[xu91102]

Fixes #780

背景

部分审批端点仍在元数据中列出已不能作为 user scope 授予的旧权限。反复执行登录无法恢复，且错误切换为 bot 身份会改变审批主体。

核心改动

• 在审批主 Skill 中说明旧 scope 的诊断和管理员核对路径。
• 在受影响 reference 中直接链接该恢复路径。
• 明确禁止因 scope 错误静默切换审批身份。

验证

• go test ./internal/qualitygate/rules -count=1
• git diff --check

风险与回滚

仅补充 Skill 运行指引，不改变 CLI 命令或 API 行为。回滚本提交即可恢复原文档。

Summary by CodeRabbit

• Documentation
  • Added guidance for legacy approval scope behavior when running as a user, including known mismatches for common approval endpoints.
  • Clarified which “old” user scopes apply (e.g., approval:instance:read) and that merged scopes like approval:instance are tenant-only (not usable as a user token substitute).
  • Updated instructions to avoid re-running auth login or switching to bot when the legacy-scope error appears.
  • Added steps to verify current token scopes and have an administrator confirm the correct approval permission model.

[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: 9a253622-a07d-4e27-bb7b-298a0ab56c90

📥 Commits

Reviewing files that changed from the base of the PR and between d9bd244 and 5fcfcbf.

📒 Files selected for processing (4)

• skills/lark-approval/SKILL.md
• skills/lark-approval/references/lark-approval-instances-get.md
• skills/lark-approval/references/lark-approval-instances-initiated.md
• skills/lark-approval/references/lark-approval-tasks-query.md

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

• skills/lark-approval/references/lark-approval-tasks-query.md
• skills/lark-approval/references/lark-approval-instances-get.md

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

• skills/lark-approval/references/lark-approval-instances-initiated.md

---

📝 Walkthrough

Walkthrough

Approval documentation now explains legacy OAuth scope limitations for user-identity operations, adds token-scope verification guidance, and directs users to administrator validation instead of repeated authentication attempts.

Changes

Approval scope guidance

Layer / File(s)	Summary
Document legacy-scope handling skills/lark-approval/SKILL.md, skills/lark-approval/references/*	The main skill documents legacy scope verification, administrator validation, and conditional --as bot use; instance and task references identify endpoint-specific scopes and instruct users not to repeat authentication when deprecated scopes are missing.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• larksuite/cli#1307: Restructures related approval skill scope and permission guidance.
• larksuite/cli#1598: Documents related authentication status and OAuth scope verification guidance.
• larksuite/cli#1630: Updates documentation for the same approval command references.

Suggested labels: documentation

Suggested reviewers: liangshuo-1, MaxHuang22, Paulazaaza-dev

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	#780 asks for fixing deprecated approval scopes, but this PR only documents workarounds and does not update metadata or user-identity scopes.	Update the approval metadata or scope mappings so --as user commands use grantable scopes for #780, or clearly mark this PR as docs-only and not a fix.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly matches the docs-focused change about user identity scope limitations.
Description check	✅ Passed	The description covers motivation, changes, verification, and rollback, though it does not use the template headings exactly.
Out of Scope Changes check	✅ Passed	The changes stay within approval docs and guidance updates, with no unrelated code paths or features introduced.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

🧹 Nitpick comments (1)

skills/lark-approval/SKILL.md (1)

18-22: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

Add a current scope/identity map for approval endpoints.
skills/lark-approval/SKILL.md#L16-L24 explains the legacy-scope fallback, but the reference pages still list only old scope names and never say whether each endpoint is user-grantable or bot/tenant-only. Add a small mapping in the main skill and link these notes to it:

• skills/lark-approval/references/lark-approval-instances-get.md#L6-L8
• skills/lark-approval/references/lark-approval-instances-initiated.md#L6-L8
• skills/lark-approval/references/lark-approval-tasks-query.md#L6-L8

🤖 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-approval/SKILL.md` around lines 18 - 22, 在
skills/lark-approval/SKILL.md 的审批身份说明旁新增当前 scope/identity 映射，明确相关端点分别支持 user
scope 还是仅支持 bot/tenant scope，并链接各参考页面。同步更新
skills/lark-approval/references/lark-approval-instances-get.md、lark-approval-instances-initiated.md
和 lark-approval-tasks-query.md 的 scope 说明，移除仅列旧 scope 的歧义并链接回主技能中的映射；保留缺少旧 scope
时先核验 token、不要反复 auth login 或静默切换身份的规则。

🤖 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-approval/SKILL.md`:
- Around line 18-22: 在 skills/lark-approval/SKILL.md 的审批身份说明旁新增当前 scope/identity
映射，明确相关端点分别支持 user scope 还是仅支持 bot/tenant scope，并链接各参考页面。同步更新
skills/lark-approval/references/lark-approval-instances-get.md、lark-approval-instances-initiated.md
和 lark-approval-tasks-query.md 的 scope 说明，移除仅列旧 scope 的歧义并链接回主技能中的映射；保留缺少旧 scope
时先核验 token、不要反复 auth login 或静默切换身份的规则。

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: a38a878a-463c-4cab-9ecd-b91a9ebc0702

📥 Commits

Reviewing files that changed from the base of the PR and between 4847f06 and d9bd244.

📒 Files selected for processing (4)

• skills/lark-approval/SKILL.md
• skills/lark-approval/references/lark-approval-instances-get.md
• skills/lark-approval/references/lark-approval-instances-initiated.md
• skills/lark-approval/references/lark-approval-tasks-query.md

[xu91102]

@coderabbitai 已处理：主 skill 新增 Feishu 的 scope/identity 映射，分别说明 tasks query、instances get、instances initiated 的旧 metadata scope、user 调用身份及 tenant-only 合并 scope 不能作为替代方案。三个 reference 已改为链接此映射，并明确禁止因缺失旧 scope 重试登录或静默切换 bot。已运行 go test ./internal/qualitygate/rules -count=1 与 git diff --check。

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
fd . skills/lark-approval -e md
echo "---SKILL---"
cat -n skills/lark-approval/SKILL.md
echo "---get---"
cat -n skills/lark-approval/references/lark-approval-instances-get.md
echo "---initiated---"
cat -n skills/lark-approval/references/lark-approval-instances-initiated.md
echo "---query---"
cat -n skills/lark-approval/references/lark-approval-tasks-query.md

Length of output: 21238

---

@xu91102 已核实,主 skill 中新增的“已知 scope 与身份映射（Feishu）”表格清晰列出了 tasks query、instances get、instances initiated 的旧 metadata scope、调用身份及 tenant-only 合并 scope 限制,三个 reference 文件也已正确链接到该映射,并在各自文件中明确提示不要因缺失旧 scope 重复 auth login 或静默切换到 bot 身份。改动符合 Issue #780 的诉求且未涉及任何 CLI 行为变更,看起来没有问题。