docs(approval): clarify user identity scope limitations

skills/lark-approval/SKILL.md

@@ -13,6 +13,26 @@ metadata:
 
 所有命令默认 `--as user`（审批是人的动作）。调用前先按需读取 references 下对应的文件，查参数结构，不要猜字段；**references 是第一信息源**，只有在 reference 未覆盖的原生 / 高级场景下，才额外用 `lark-cli ... --help`、`lark-cli schema` 等方式补充确认字段。
 
+### 用户身份的旧 scope 限制
+
+部分审批端点的元数据仍可能要求旧 scope（例如 `approval:task:read`、`approval:task:write`、`approval:instance:read`、`approval:instance:write`）。若 `--as user` 返回这些 scope 缺失，不要反复执行 `auth login`：这些旧 scope 可能已无法作为 user scope 在开发者后台授权。
+
+#### 已知 scope 与身份映射（Feishu）
+
+| 端点 | CLI 元数据要求 | 调用身份 | 当前限制与恢复路径 |
+| --- | --- | --- | --- |
+| `approval tasks query` | `approval:task:read`（旧） | 仅 `user` | `approval:task` 是 tenant-only，不能替代 user token。当前官方文档列出 `approval:approval:readonly` 或 `approval:task:list_by_user`，但 CLI 元数据尚未映射；保留错误并请管理员或维护者核对平台配置。 |
+| `approval instances get` | `approval:instance:read`（旧） | `user` | 合并后的 `approval:instance` 是 tenant-only，不能修复 user 调用；不要改为 bot。 |
+| `approval instances initiated` | `approval:instance:read`（旧） | `user` | 合并后的 `approval:instance` 是 tenant-only，不能修复 user 调用；不要改为 bot。 |
+
+这张表描述的是当前 CLI 元数据与平台授权模型不一致时的处理边界，不代表 tenant/bot scope 可以读取或代办用户的审批任务。
+
+1. 先运行 `lark-cli auth status --verify --format json`，确认当前 user token 和已授予 scope。
+2. 让应用管理员在开发者后台核对当前可申请的审批 scope；不要把旧 scope 名称当作用户可自行补齐的权限。
+3. 只有用户明确要求以应用身份运行、且该端点支持 tenant/bot scope 时，才改用 `--as bot`。审批动作默认是人的动作，禁止因一次 scope 报错静默切换身份。
+
+这类限制不是网络故障；保留原始错误和 scope 名称，向用户说明需要管理员确认平台权限模型。
+
 ## 路由优先级（先判断是不是审批，再选命令）
 
 审批待办不是飞书任务。**只要用户的核心对象是审批单据 / 审批待办 / 审批实例，就优先使用 `lark-approval`，不要让渡给 `lark-task`。**

skills/lark-approval/references/lark-approval-instances-get.md

@@ -3,7 +3,9 @@
 
 获取单个审批实例详情（用户级只读操作）。适合在执行 approve / reject / transfer / rollback / cancel / cc / remind 之前，先查看审批表单、当前节点、任务列表、审批动态和整体状态。
 
-需要的 scopes: ["approval:instance:read"]
+CLI 元数据 scopes: ["approval:instance:read"]（旧）。此命令面向 `--as user`；合并后的 `approval:instance` 是 tenant-only，不能替代 user token。请阅读主 skill 的“已知 scope 与身份映射（Feishu）”。
+
+> 如果 `--as user` 提示缺少这个旧 scope，不要重复 `auth login` 或改用 bot。请先阅读主 skill 的“用户身份的旧 scope 限制”和“已知 scope 与身份映射（Feishu）”。
 
 ## 命令
 

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

@@ -3,7 +3,9 @@
 
 查询当前用户已发起的审批实例列表（用户级只读操作）。适合在需要查看“我发起了哪些审批”、筛选某类审批定义、获取 `instance_code` 供后续 `instances get` / `instances cancel` / `instances cc` 等命令使用时调用。
 
-需要的 scopes: ["approval:instance:read"]
+CLI 元数据 scopes: ["approval:instance:read"]（旧）。此命令面向 `--as user`；合并后的 `approval:instance` 是 tenant-only，不能替代 user token。请阅读主 skill 的“已知 scope 与身份映射（Feishu）”。
+
+> 如果 `--as user` 提示缺少这个旧 scope，不要重复 `auth login` 或改用 bot。请先阅读主 skill 的“用户身份的旧 scope 限制”和“已知 scope 与身份映射（Feishu）”。
 
 ## 命令
 

skills/lark-approval/references/lark-approval-tasks-query.md

@@ -3,7 +3,9 @@
 
 查询当前用户的审批任务列表，可用于查看待办、已办、知会等分组。只读操作，不会修改审批状态。
 
-需要的 scopes: ["approval:task:read"]
+CLI 元数据 scopes: ["approval:task:read"]（旧）。此端点只接受 `--as user`；`approval:task` 是 tenant-only，不能替代 user token。请阅读主 skill 的“已知 scope 与身份映射（Feishu）”。
+
+> 如果 `--as user` 提示缺少这个旧 scope，不要重复 `auth login` 或改用 bot。请先阅读主 skill 的“用户身份的旧 scope 限制”和“已知 scope 与身份映射（Feishu）”。
 
 ## 命令