@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.28c4f05 → 0.1.0-dev.4e64c13

package/miaoda/lark-apps-authz/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: lark-apps-authz
+description: "Use when 在妙搭沙箱里用 `lark-cli apps +role-*` 管理【当前这个已存在的】妙搭应用的角色与角色成员、查询用户命中的角色，或用 `lark-cli apps +db-execute` 维护权限点位表（建表、预填、新增、更新、删除点位）。触发词：查询角色列表, 创建角色, 删除角色, 角色成员, 查询用户角色, 权限点位, 权限表, 新增点位, 更新点位, 删除点位, +role-, role-list, role-match-list. NOT for 编写权限控制代码——CanRole/@Can 编码用 authz-guide skill。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli apps --help; lark-cli apps +role-list --help（各 +role-* 子命令同理）"
+control-by-feature-ab: true
+unavailable-agents:
+  - AppInit
+---
+
+# lark-apps-authz — 权限管理工具
+
+Agent 在沙箱内直接执行的权限管理工具集，包含两部分能力：
+
+- **角色管理**：通过 `lark-cli apps +role-*` 管理角色（查询、创建、更新、删除、成员管理、查询用户命中角色）。完整命令细节见 [references/role.md](references/role.md)
+- **权限点位管理**：通过 `lark-cli apps +db-execute` 管理权限表和数据（建表、新增/更新/删除点位、管理映射）。SQL 执行通道与建表规范以 `lark-apps-db` skill 为准
+
+## 沙箱约定（先读）
+
+- **命令名**：一律 `lark-cli apps +role-*` / `lark-cli apps +db-execute`；命令/flag 细节以 `--help` 为准。
+- **应用已存在、app_id 走环境变量**：应用 id 在环境变量 `app_id` 里，命令需要 `--app-id` 时用 `--app-id "$app_id"`，不需要自行获取、解析或选择。
+- **鉴权自动**：apps 域请求由运行环境自动打到 innerAPI 并注入鉴权头。**不要** `auth login` / `config init` / `--as`。
+- **失败处理**：命令失败时把 `error.hint` 转述给用户，别原样甩 envelope JSON。
+
+### 高风险写操作审批（exit 10）
+
+`+role-delete`、`+role-member-remove`（含 `--all`）等删除类操作属于高风险写：不带 `--yes` 会 **exit 10** 并返回 `confirmation_required`。处理：
+
+1. 识别 exit code=10 且 `error.type=="confirmation_required"`；
+2. 把 `error.risk.action` + 关键参数给用户，明确"高风险/不可逆"，等显式同意；
+3. 同意 → 原始 argv 末尾加 `--yes` 重试；拒绝 → 终止；
+4. 想先看请求 → `--dry-run`（不触发门禁、不需 `--yes`）。
+
+**绝不**看到 exit 10 就默认补 `--yes` 静默重试。
+
+## 工具边界
+
+| 场景 | 正确做法 |
+|------|----------|
+| Agent 查询系统已有哪些角色 | `lark-cli apps +role-list --app-id "$app_id"` |
+| Agent 创建/更新角色 | `lark-cli apps +role-create --app-id "$app_id" --name "<名称>"` / `+role-update --app-id "$app_id" --role-id <role_id>` |
+| Agent 删除角色（高风险） | `lark-cli apps +role-delete --app-id "$app_id" --role-id <role_id> --yes`，执行前必须取得用户明确授权 |
+| Agent 管理角色成员 | `lark-cli apps +role-member-list/add/remove --app-id "$app_id" --role-id <role_id>`（remove 为高风险，需授权） |
+| 查询某用户命中哪些角色 | `lark-cli apps +role-match-list --app-id "$app_id" --user-id <ou_x>` |
+| 创建 authz_permissions/authz_role_permissions 表 | `lark-cli apps +db-execute` 执行 DDL |
+| 开发阶段新增/更新/删除权限点位 | `lark-cli apps +db-execute` 执行 INSERT/UPDATE/DELETE |
+| 开发阶段初始化或调整角色-点位映射 | `lark-cli apps +db-execute` 执行 INSERT/DELETE |
+| 运行态调整角色-点位映射（勾选/取消） | 由应用管理页面处理，**不属于** Agent 职责 |
+| **应用前端**需要权限控制 | 使用 `<CanRole>` 或 `<Can>` 组件（参考 `authz-guide` skill） |
+| **应用后端**需要权限控制 | 使用 `@CanRole` 或 `@Can` 装饰器（参考 `authz-guide` skill） |
+
+> **禁止**在生成的应用代码（前端/后端）中调用 `lark-cli`。CLI 命令只在 Agent 对话终端中执行。
+
+> 默认输出 JSON envelope，角色数据位于 `data.items` / `data.role` / `data.roles`。
+
+## Action 决策流程
+
+### Action 类型与触发场景
+
+| Action | 触发场景 | 对应操作 |
+| ------ | -------- |---------|
+| QUERY | 需要了解当前系统已有哪些角色 | `lark-cli apps +role-list --app-id "$app_id"` |
+| CREATE | 查询后发现所需角色不存在，需按设计方案批量创建 | `lark-cli apps +role-create --app-id "$app_id" --name "..." --description "..."` |
+| UPDATE | 需要修改已有角色的名称或描述 | `lark-cli apps +role-update --app-id "$app_id" --role-id "..." --name "..."` |
+| DELETE | 需要删除角色（高风险，不可逆） | 先 `+role-get` + `+role-member-list` 确认影响，取得授权后 `+role-delete --yes` |
+| MEMBER | 需要查询/调整角色的用户、部门、群成员 | `+role-member-list/add/remove`（remove 高风险，需授权） |
+| MATCH | 需要查询某用户命中哪些角色 | `lark-cli apps +role-match-list --app-id "$app_id" --user-id "<ou_x>"` |
+| PERM_CREATE_TABLE | 首次启用动态权限：创建 authz_permissions/authz_role_permissions 表 | `lark-cli apps +db-execute` 执行 DDL |
+| PERM_SEED | 初始化权限点位和角色-点位映射数据 | `lark-cli apps +db-execute` 执行 INSERT |
+| PERM_ADD | 新增权限点位（新功能上线时） | `lark-cli apps +db-execute` 执行 INSERT + 同步更新 `@Can`/`<Can>` 代码 |
+| PERM_UPDATE | 修改权限点位的 action/subject/description | `lark-cli apps +db-execute` 执行 UPDATE + 同步更新 `@Can`/`<Can>` 代码 |
+| PERM_DELETE | 删除权限点位（功能下线时） | `lark-cli apps +db-execute` 执行 DELETE（级联删除映射）+ 移除 `@Can`/`<Can>` 代码 |
+
+### 决策流程图
+
+```text
+权限设计方案
+    │
+    ├─ 推荐模式：静态角色鉴权
+    │   └─ 新建 ──→ 按角色清单逐个 CREATE ──→ 编写 CanRole 代码（authz-guide）
+    │
+    ├─ 推荐模式：动态权限点位鉴权
+    │   ├─ 新建 ──→ CREATE 角色 → PERM_CREATE_TABLE → PERM_SEED → 编写 @Can 代码（authz-guide）
+    │   └─ 升级（仅限历史 CanRole 代码迁移）──→ PERM_CREATE_TABLE → PERM_SEED → CanRole 升级为 Can（authz-guide）
+    │
+    ├─ "给某功能加权限控制" / "新建某个角色"
+    │   └──→ QUERY（查询角色）
+    │         ├─ 角色存在 ──→ 编写鉴权代码（authz-guide）
+    │         └─ 角色不存在 ──→ CREATE ──→ 编写鉴权代码
+    │
+    ├─ "新功能上线，需要新增权限点位" ──→ PERM_ADD + 同步 @Can/<Can> 代码
+    │
+    ├─ "功能下线，删除权限点位" ──→ PERM_DELETE + 移除 @Can/<Can> 代码
+    │
+    ├─ "修改角色信息" ──→ UPDATE
+    │
+    └─ "查某用户有哪些角色" ──→ MATCH
+```
+
+### 关键约束
+
+**角色设计由权限设计方案承载**，本 skill 负责角色 CLI 操作和权限点位管理。
+
+**日常权限开发流程**：QUERY → 判断是否 CREATE → 编写鉴权代码（参考 `authz-guide`）。
+
+**动态权限点位初始化流程**：CREATE 角色 → PERM_CREATE_TABLE → PERM_SEED → 编写鉴权代码。
+
+**权限点位变更**：PERM_ADD / PERM_UPDATE / PERM_DELETE **必须同步更新** `@Can`/`<Can>` 代码，确保数据库点位定义与代码中的鉴权声明一致。
+
+**角色标识**：角色名称不是 role_id。只有名称时先用 `+role-list --name '<exact_name>'` 精确解析；多条命中让用户消歧，唯一命中后才使用返回的真实 role_id。
+
+**mock 能力差异**：authz-cli 的 `role mock`（为用户配置模拟角色集）在 lark-cli 通道无对应命令，已移除；只读查询用户命中的角色用 MATCH（`+role-match-list`）。
+
+---
+
+## 角色管理（`lark-cli apps +role-*`）
+
+完整命令约定见 [references/role.md](references/role.md)。高频用法：
+
+### 查询角色
+
+```bash
+# 分页列出全部角色
+lark-cli apps +role-list --app-id "$app_id" --page-size 100
+
+# 按精确名称解析 role_id
+lark-cli apps +role-list --app-id "$app_id" --name '管理员'
+
+# 读取角色详情
+lark-cli apps +role-get --app-id "$app_id" --role-id <role_id>
+
+# 查询某用户命中的角色（user-id 只接受 ou_...）
+lark-cli apps +role-match-list --app-id "$app_id" --user-id <ou_x>
+```
+
+### 创建角色
+
+```bash
+lark-cli apps +role-create --app-id "$app_id" \
+  --name "管理员" \
+  --description "拥有全部管理权限" \
+  --role-id "admin"
+```
+
+**参数：**
+
+- `--name`（必需）：角色名称
+- `--description`（可选）：角色描述
+- `--role-id`（可选）：角色 ID。仅在需要稳定业务标识（如 `admin`，供权限点位表 `role_key` 引用）时传入，创建后不能修改；不传由平台分配
+
+### 按设计方案批量创建
+
+当权限设计方案已输出角色清单（含 name、roleId、description）时，按清单顺序逐个创建：
+
+```bash
+# 按角色清单顺序执行，每个角色一条命令
+lark-cli apps +role-create --app-id "$app_id" --name "读者" --role-id "reader" --description "浏览图书与分类，发起借阅"
+lark-cli apps +role-create --app-id "$app_id" --name "图书编辑" --role-id "editor" --description "负责图书内容的创建与维护"
+lark-cli apps +role-create --app-id "$app_id" --name "管理员" --role-id "admin" --description "拥有所有业务管理权限"
+```
+
+> 创建完所有角色后，按权限设计方案的功能权限映射表编写鉴权代码（参考 `authz-guide`）。
+
+### 更新角色
+
+```bash
+# 只传需要变更的字段（--name 或 --description）
+lark-cli apps +role-update --app-id "$app_id" --role-id "admin" --name "管理员（全局）"
+```
+
+### 删除角色（高风险）
+
+```bash
+# 先确认影响范围，取得用户明确授权后再带 --yes 执行
+lark-cli apps +role-get --app-id "$app_id" --role-id <role_id>
+lark-cli apps +role-member-list --app-id "$app_id" --role-id <role_id>
+lark-cli apps +role-delete --app-id "$app_id" --role-id <role_id> --yes
+```
+
+### 角色成员管理
+
+```bash
+# 查询角色的用户、部门、群成员
+lark-cli apps +role-member-list --app-id "$app_id" --role-id <role_id>
+
+# 添加成员（open ID：用户 ou_...、部门 od-...、群 oc_...）
+lark-cli apps +role-member-add --app-id "$app_id" --role-id <role_id> \
+  --users ou_x,ou_y --departments od-x --chats oc_x
+
+# 定向移除成员（高风险，需授权）
+lark-cli apps +role-member-remove --app-id "$app_id" --role-id <role_id> --users ou_x --yes
+
+# 清空成员（不删除角色；高风险，需授权）
+lark-cli apps +role-member-remove --app-id "$app_id" --role-id <role_id> --all --yes
+```
+
+> **成员参数只接受飞书 open ID**：`--users` 收 `ou_`、`--departments` 收 `od-`、`--chats` 收 `oc_`。妙搭的数字 user_id（例如数据库 `user_profile` 列用的那组测试用户）**不能用**，CLI 会直接拒绝并提示 `--users must use ou_ IDs`。
+> 沙箱内取 open ID 只有两条路：`lark-cli contact +search-user --query "<姓名或邮箱>"`（要求唯一精确命中）、`lark-cli contact +get-user`（当前登录用户自己）。**两条都拿不到就停下向用户要 open ID——禁止用数字 ID 兜底，禁止编造。**
+
+## 权限点位管理（`lark-cli apps +db-execute`）
+
+> **SQL 执行通道**：所有 DDL/DML 只用 `lark-cli apps +db-execute --app-id "$app_id" --sql "<query>" --yes` 执行，不要调用其它 SQL 工具。建表规范（审计列、RLS、默认 policy、`IF NOT EXISTS`）、DML 规则与高风险授权要求**参阅 `lark-apps-db` skill**（[../lark-apps-db/SKILL.md](../lark-apps-db/SKILL.md)）。
+
+> **职责边界**：
+> - **开发阶段（Agent）**：通过 `+db-execute` 对 `authz_permissions`（点位定义）和 `authz_role_permissions`（角色-点位映射）两张表做 CURD，含建表、预填、点位增删改、初始映射调整。
+> - **运行态（管理页面）**：只提供受限能力——角色-点位映射的勾选/取消。**禁止**管理页面提供权限点位本身的新增/删除功能（点位增删属于代码变更范畴，必须回到开发阶段走 `+db-execute` + 同步 `@Can`/`<Can>`）。
+
+> **⚠️ 双表原则**：权限点位涉及 `authz_permissions`（点位定义）和 `authz_role_permissions`（角色-点位映射）两张表，初始化和变更时**必须同时处理两张表**，禁止只操作其中一张。
+
+### PERM_CREATE_TABLE — 建表
+
+首次启用动态权限点位时执行。两张表的完整建表 DDL、RLS/policy 补齐要求、`role_key` ↔ 角色 ID 的对应关系见 [references/permission-points.md](references/permission-points.md)。
+
+### PERM_SEED — 预填初始数据
+
+按权限设计方案的「权限点位定义」和「角色-点位初始映射」表预填：
+
+```sql
+-- 按「权限点位定义」表
+INSERT INTO authz_permissions (action, subject, description) VALUES
+  ('read', 'Task', '查看任务'),
+  ('create', 'Task', '创建任务'),
+  ('update', 'Task', '编辑任务'),
+  ('delete', 'Task', '删除任务');
+
+-- 按「角色-点位初始映射」表
+INSERT INTO authz_role_permissions (role_key, permission_id) VALUES
+  ('admin', (SELECT id FROM authz_permissions WHERE action='read' AND subject='Task')),
+  ('admin', (SELECT id FROM authz_permissions WHERE action='create' AND subject='Task')),
+  ('member', (SELECT id FROM authz_permissions WHERE action='read' AND subject='Task'));
+```
+
+> 以上 SQL 仅为示例，实际数据根据权限设计方案生成。
+
+### PERM_ADD — 新增权限点位
+
+新功能上线时，新增点位 + 初始映射 + 同步鉴权代码：
+
+```sql
+-- 1. 新增点位定义（authz_permissions 表）
+INSERT INTO authz_permissions (action, subject, description) VALUES
+  ('export', 'Task', '导出任务');
+
+-- 2. 为需要该权限的角色添加映射（authz_role_permissions 表）
+INSERT INTO authz_role_permissions (role_key, permission_id) VALUES
+  ('admin', (SELECT id FROM authz_permissions WHERE action='export' AND subject='Task'));
+```
+
+> **必须同步**：
+> - 在后端对应的 Controller 方法上添加 `@Can('export', 'Task')`，前端添加 `<Can action="export" subject="Task">`
+> - **禁止**只插入 authz_permissions 而不处理 authz_role_permissions，否则新点位无任何角色拥有
+
+### PERM_UPDATE — 修改权限点位
+
+修改已有点位的 action、subject 或 description：
+
+```sql
+-- 修改 authz_permissions 表（authz_role_permissions 通过外键 permission_id 关联，无需修改）
+UPDATE authz_permissions SET description = '导出任务列表为 Excel' WHERE action = 'export' AND subject = 'Task';
+```
+
+> 如果修改了 action 或 subject，**必须同步更新**所有引用该点位的 `@Can`/`<Can>` 代码。authz_role_permissions 通过 `permission_id` 外键关联，不受 action/subject 变更影响。
+
+### PERM_DELETE — 删除权限点位
+
+功能下线时，删除点位 + 自动级联删除映射 + 移除鉴权代码：
+
+```sql
+-- 删除 authz_permissions 记录，authz_role_permissions 中关联的映射会被 ON DELETE CASCADE 自动删除
+DELETE FROM authz_permissions WHERE action = 'export' AND subject = 'Task';
+```
+
+> **必须同步**：移除后端的 `@Can('export', 'Task')` 装饰器和前端的 `<Can action="export" subject="Task">` 组件。
+> 虽然 authz_role_permissions 会自动级联删除，仍需**确认**不存在其他代码依赖被删除的点位。
+
+---
+
+## Common Mistakes
+
+| 错误 | 正确做法 |
+| ---- | -------- |
+| 在应用代码中调用 `lark-cli` | CLI 仅供 Agent 终端执行；应用代码用 CanRole 组件/装饰器（参考 `authz-guide`） |
+| 用角色名称当 role_id 直接更新/删除 | 先 `+role-list --name '<exact_name>'` 精确解析出 role_id，多条命中让用户消歧 |
+| 未授权就执行 `+role-delete --yes` / `+role-member-remove --all --yes` | 删除类操作高风险不可逆，先展示影响范围取得明确授权；exit-10 按沙箱约定处理，绝不静默补 `--yes` |
+| 只创建角色不编写鉴权代码 | 创建角色后必须编写鉴权代码（参考 `authz-guide`） |
+| 没有设计方案就大批量创建角色 | 先确认是否有权限设计方案输出的角色清单，再按清单逐个 CREATE |
+| 动态权限点位场景只创建角色不建表预填 | 需要执行 PERM_CREATE_TABLE + PERM_SEED |
+| 在管理页面提供权限点位的增删改 | 权限点位的增删改由 Agent 通过 PERM_ADD/UPDATE/DELETE 操作，管理页面只做角色-点位映射 |
+| 新增/修改/删除权限点位后不同步代码 | PERM_ADD/UPDATE/DELETE 后**必须同步**更新对应的 `@Can`/`<Can>` 代码 |
+| PERM_ADD 只插入 authz_permissions 不插入 authz_role_permissions | 新增点位后必须同时为相关角色添加映射，否则无角色拥有该权限 |

package/miaoda/lark-apps-authz/references/permission-points.md

@@ -0,0 +1,39 @@
+# 权限点位表建表 DDL（PERM_CREATE_TABLE）
+
+首次启用动态权限点位时执行。通过 `lark-cli apps +db-execute --app-id "$app_id" --sql "<ddl>" --yes` 下发；
+SQL 执行通道、建表规范与高风险授权要求以 `lark-apps-db` skill 为准。
+
+## 两张表
+
+```sql
+CREATE TABLE IF NOT EXISTS authz_permissions (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  action VARCHAR(100) NOT NULL,
+  subject VARCHAR(100) NOT NULL,
+  description TEXT DEFAULT '',
+  creator user_profile NOT NULL,
+  _created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP NOT NULL,
+  _created_by user_profile,
+  _updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP NOT NULL,
+  _updated_by user_profile,
+  UNIQUE(action, subject)
+);
+
+CREATE TABLE IF NOT EXISTS authz_role_permissions (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  role_key VARCHAR(100) NOT NULL,
+  permission_id UUID NOT NULL REFERENCES authz_permissions(id) ON DELETE CASCADE,
+  creator user_profile NOT NULL,
+  _created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP NOT NULL,
+  _created_by user_profile,
+  _updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP NOT NULL,
+  _updated_by user_profile,
+  UNIQUE(role_key, permission_id)
+);
+```
+
+## 两条必读约束
+
+> **RLS 与默认 policy**：以上仅为业务列示意，实际建表必须按 `lark-apps-db` skill 的 CREATE TABLE Template 在**同一次 `+db-execute` 调用**中补齐 `ENABLE ROW LEVEL SECURITY` 和 4 条默认 policy（两张表都要），并在执行前取得用户授权。
+
+> **`role_key` ↔ 角色 ID**：`authz_role_permissions.role_key` 存储的值必须等于角色的 role_id（`+role-create --role-id` 传入的值，或平台分配后从 `+role-list` 读到的值）。两者是同一个标识，INSERT 映射时 `role_key` 填 `'admin'`、`'editor'` 等角色 ID，运行时鉴权也用它匹配用户拥有的角色。

package/miaoda/lark-apps-authz/references/role.md

@@ -0,0 +1,122 @@
+# apps role 域命令（应用角色）
+
+管理妙搭应用内的平台角色、角色成员，以及查询某个用户命中的角色。运行时命令事实以 `lark-cli apps +<cmd> --help` 为准；沙箱约定（`$app_id`、鉴权自动、exit-10 高风险确认）遵循本 skill [`SKILL.md`](../SKILL.md) 的沙箱约定段。
+
+## 何时用
+
+用户要列出、查看、创建、更新或删除某个妙搭应用内的平台角色，管理角色的用户、部门或群成员，或查询某个用户在应用中命中的角色时使用。多维表格 / Base 的角色与权限不走本命令域；设置谁能访问应用走 `+access-scope-*`，不要路由到本命令域。
+
+## 命令一览
+
+| 命令 | 做什么 | 关键参数 |
+|---|---|---|
+| `+role-list` | 分页列出角色，或按名称筛选角色 | `--app-id`、`--name`、`--page-size`/`--page-token` |
+| `+role-get` | 根据真实 `role_id` 读取角色详情 | `--app-id`、`--role-id` |
+| `+role-match-list` | 查询指定用户命中的角色 | `--app-id`、`--user-id` |
+| `+role-create` | 创建角色 | `--app-id`、`--name`、`--description`、`--role-id` |
+| `+role-update` | 更新角色名称或描述 | `--app-id`、`--role-id`、`--name`/`--description` |
+| `+role-delete` | 永久删除角色 | `--app-id`、`--role-id`、`--yes` |
+| `+role-member-list` | 查询角色的用户、部门和群成员 | `--app-id`、`--role-id`、`--member-type` |
+| `+role-member-add` | 向角色添加用户、部门或群成员 | `--app-id`、`--role-id`、`--users`/`--departments`/`--chats` |
+| `+role-member-remove` | 定向移除或清空角色成员 | `--app-id`、`--role-id`、成员参数或 `--all`、`--yes` |
+
+## 约定（先读）
+
+- 应用 id 在环境变量 `app_id` 里，所有命令用 `--app-id "$app_id"`；其角色和成员只使用 `apps +role-*` / `apps +role-member-*`，不要改走 Base 角色命令或裸 bitable API。
+- 角色名称不是 `role_id`。只有名称时优先用 `+role-list --name` 精确解析；若已取得完整分页列表，也可从中证明精确名称唯一命中。0 条如实报告，多条让用户消歧，唯一命中后才使用返回的真实 ID。
+- `+role-list` 返回 `has_more=true` 时，用本页 `page_token` 继续查询，直到 `has_more=false`；不要根据 `total` 补造条目。
+- `+role-list`、`+role-get`、`+role-match-list` 的角色数据分别位于 `data.items`、`data.role`、`data.roles`，不要混用。
+- 同一角色的写入及依赖该写入结果的操作必须串行。不同角色的独立操作只有在每次写入可单独追溯、失败不影响其它目标且分别验收时才可并行；否则保持串行。互不依赖的名称解析或只读查询可并行。
+
+## 各命令
+
+### 查询角色
+
+```bash
+lark-cli apps +role-list --app-id "$app_id" --page-size 100
+lark-cli apps +role-list --app-id "$app_id" --name '<exact_name>'
+lark-cli apps +role-get --app-id "$app_id" --role-id <role_id>
+lark-cli apps +role-match-list --app-id "$app_id" --user-id <ou_x>
+```
+
+整理角色列表时保留 `role_id`、`name` 和 `description`。不要猜测未知 `role_id`，也不要从同名候选中静默选择。
+`items=[]` 时直接报告当前没有角色；不要为表格补造“无”或 `N/A` 占位行。
+`+role-match-list --user-id` 只接受 `ou_...`；用户给的是姓名、邮箱或手机号时，先解析唯一 open ID（见「成员 ID 解析」），再查询命中角色。
+
+### 创建与更新
+
+```bash
+lark-cli apps +role-create --app-id "$app_id" --name '<name>' \
+  --description '<description>'
+
+# 只修改名称
+lark-cli apps +role-update --app-id "$app_id" --role-id <role_id> \
+  --name '<new_name>' --format json
+
+# 只修改描述
+lark-cli apps +role-update --app-id "$app_id" --role-id <role_id> \
+  --description '<new_description>' --format json
+```
+
+- `--description` 和创建时的 `--role-id` 可选；仅在确实需要稳定 ID 时传 `--role-id`，创建后不能修改。
+- 更新时只传用户明确要求变更的字段。
+- 成功响应中的角色位于 `data.role`。只有用户要求独立验证，或结果将用于后续高风险操作时，才额外执行 `+role-get`。
+
+### 删除角色
+
+普通“删除某角色”请求只说明目标，**不等于不可逆确认**。如果用户尚未明确确认删除后果，本轮只能定位角色、读取完整成员并说明影响，最后请求确认；不得在同一轮自动追加 `--yes`。用户已明确确认不可逆删除时才继续。
+
+只有名称时仍按上述规则唯一解析，优先使用 `+role-list --name`。目标写前已不存在时立即停止，如实说明本次是 no-op、没有执行删除，不能把“当前不存在”表述为“删除成功”。
+
+删除前读取准确角色和完整成员范围，向用户说明 app、role、`users` / `departments` / `chats` 影响；得到不可逆删除确认后才使用 `--yes`：
+
+```bash
+lark-cli apps +role-get --app-id "$app_id" --role-id <role_id>
+lark-cli apps +role-member-list --app-id "$app_id" --role-id <role_id>
+lark-cli apps +role-delete --app-id "$app_id" --role-id <role_id> --yes
+```
+
+成功响应包含匹配的 `data.role_id` 和 `data.deleted=true`。只有用户明确要求独立验证删除结果时，才再用 `+role-list --name` 检查目标 ID 已不存在。
+
+### 成员 ID 解析
+
+成员 flags 只接受 open ID：用户 `ou_...`、部门 `od-...`、群 `oc_...`。用户已提供对应类型的合法 open ID 时直接使用；只有名称或邮箱时才解析。
+对象类型以用户语义为准，不能互换解析器：用户走通讯录用户搜索，群走群搜索；沙箱内没有可用的部门搜索命令，部门让用户直接提供 `od-...`。
+
+```bash
+# 用户：每个姓名或邮箱单独查询。
+lark-cli contact +search-user --query '<姓名或邮箱>' \
+  --exclude-external-users --page-size 30
+
+# 群：拉完分页，只接受名称精确匹配的唯一 chat_id。
+lark-cli im +chat-search --query '<群名称>' --page-size 50
+```
+
+- 只接受与输入姓名、邮箱或群名精确匹配的唯一结果。0 条、多条或分页未完成时停止写入并让用户补充或消歧。
+- 多个对象逐个解析。全部解析成功且总数不超过 100 后，按类型放入一次成员写入；任一对象失败时不要部分写入，也不要自动拆批。
+- `lark-cli api` 不在沙箱命令白名单内，会被策略直接拒绝，**不要**用它解析部门或兜底其它对象；解析失败时让用户直接提供 open ID，不要改用猜测或模糊匹配。
+
+### 成员操作
+
+```bash
+# 省略 --member-type，返回完整 users / departments / chats。
+lark-cli apps +role-member-list --app-id "$app_id" --role-id <role_id>
+
+lark-cli apps +role-member-add --app-id "$app_id" --role-id <role_id> \
+  --users ou_x,ou_y --departments od-x --chats oc_x
+
+lark-cli apps +role-member-remove --app-id "$app_id" --role-id <role_id> \
+  --users ou_x --yes
+
+# 清空成员，不删除角色。
+lark-cli apps +role-member-remove --app-id "$app_id" --role-id <role_id> \
+  --all --yes
+```
+
+- `+role-member-list` 不分页；`--member-type` 只返回选中类型的字段，未返回的成员字段表示“未查询”而不是空。影响确认或完整比较时必须省略它。
+- 汇总 `--member-type` 结果时明确这是过滤投影，不得据此断言角色没有其它类型成员。
+- 用户要求 CLI 原生 table 时，直接执行 `+role-member-list --format table`；可原样转发或做事实摘要，不要先取 JSON 再手工重建一张替代表格。
+- 写入和依赖其结果的回读不得放进同一个并发批次；必须等待写入完整返回成功后，再单独发起回读。误并发时只能以写入完成后的新回读作为结果证据。
+- 添加前仅在用户要求独立证明或确认其他成员类型未变化时读取完整基线，并在写后完整回读；否则成功响应即可作为结果。
+- 定向移除前确认准确成员及影响。若需要证明结果，写后完整回读；不要把过滤结果当作完整成员集合。
+- `--all` 前读取完整成员范围并确认；成功后执行一次无过滤 `+role-member-list`，确认三个成员数组均为空。