@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.ec88bb5 → 0.1.0-dev.f3f0e48

package/miaoda/forms-skill/SKILL.md

@@ -13,6 +13,12 @@ Shadcn Form + React Hook Form + Zod 表单开发。
 - 所有字段必须有默认值
 - 必须用 Shadcn 组件，禁止原生 input
 - 同行 FormField 必须等宽
+- 每个控件都要有能读出来的字段名（读屏和自动化验收都按它找控件）：FormField 内用 `FormLabel` + `FormControl`，id 会自动关联；FormField 外的筛选、搜索控件用 `<Label htmlFor="x">` 配控件 `id="x"`，没有可见标签时加 `aria-label`。不要只靠 placeholder 或当前选中值表达字段含义
+- 必填星号加 `aria-hidden="true"`，别让 `*` 混进字段名
+- 字段校验错误用 `<FormMessage />` 显示在字段下方；toast 只用于提交结果（成功 / 接口失败），不要用 toast 提示「请输入 xx」
+- 日期字段用 `Popover` + `Calendar`，`FormControl` 包住触发按钮，禁止 `input[type="date"]`
+- 自定义输入组件（富文本等）也放进 `FormControl`，并把 `id`、`aria-*` 透传到真正可编辑的元素上
+- 表单提交到必填 API/DTO/Request/interface 前，先读目标 shared/server 类型，在 `handleSubmit` 回调里用 `data` 逐字段构造 typed request（见 Patterns）；不要整体传 `data`、`schema.parse(data)` 或 `.required().parse(data)`，也不要用 `any`/`as` 绕过 TS2322。修完后跑 LSP 或 `typecheck`。
 
 ---
 
@@ -48,14 +54,14 @@ export function StudentForm() {
         <div className="flex flex-wrap gap-4">
           <FormField control={form.control} name="name" render={({ field }) => (
             <FormItem className="flex-1">
-              <FormLabel>姓名 <span className="text-destructive">*</span></FormLabel>
+              <FormLabel>姓名 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
               <FormControl><Input placeholder="请输入姓名" {...field} /></FormControl>
               <FormMessage />
             </FormItem>
           )} />
           <FormField control={form.control} name="age" render={({ field }) => (
             <FormItem className="flex-1">
-              <FormLabel>年龄 <span className="text-destructive">*</span></FormLabel>
+              <FormLabel>年龄 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
               <FormControl><Input type="number" {...field} /></FormControl>
               <FormMessage />
             </FormItem>
@@ -63,7 +69,7 @@ export function StudentForm() {
         </div>
         <FormField control={form.control} name="grade" render={({ field }) => (
           <FormItem>
-            <FormLabel>年级 <span className="text-destructive">*</span></FormLabel>
+            <FormLabel>年级 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
             <Select onValueChange={field.onChange} defaultValue={field.value}>
               <FormControl><SelectTrigger><SelectValue placeholder="请选择" /></SelectTrigger></FormControl>
               <SelectContent>
@@ -98,7 +104,43 @@ const form = useForm<FormData>({ resolver: zodResolver(schema), defaultValues: {
 </div>
 
 // 必填标记
-<FormLabel>字段 <span className="text-destructive">*</span></FormLabel>
+<FormLabel>字段 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
+
+// 表单外的筛选 / 搜索控件：可见标签用 htmlFor + id 关联；没有可见标签必须加 aria-label
+<Label htmlFor="status-filter">状态</Label>
+<Select value={status} onValueChange={setStatus}>
+  <SelectTrigger id="status-filter"><SelectValue placeholder="全部状态" /></SelectTrigger>
+  <SelectContent>{/* SelectItem ... */}</SelectContent>
+</Select>
+<Input aria-label="搜索姓名或职位" placeholder="搜索姓名或职位" value={keyword} onChange={(e) => setKeyword(e.target.value)} />
+
+// 日期：Popover + Calendar，FormControl 包住触发按钮，label 才能关联到它
+<FormField control={form.control} name="dueDate" render={({ field }) => (
+  <FormItem>
+    <FormLabel>截止日期</FormLabel>
+    <Popover>
+      <PopoverTrigger asChild>
+        <FormControl>
+          <Button variant="outline" className="w-full justify-start font-normal">
+            {field.value ? dayjs(field.value).format("YYYY-MM-DD") : "请选择日期"}
+          </Button>
+        </FormControl>
+      </PopoverTrigger>
+      <PopoverContent className="w-auto p-0" align="start">
+        <Calendar mode="single" selected={field.value} onSelect={field.onChange} />
+      </PopoverContent>
+    </Popover>
+    <FormMessage />
+  </FormItem>
+)} />
+
+// 必填 Request/DTO 桥接：zodResolver 负责运行时校验，DTO 边界负责静态类型匹配。
+// 用 handleSubmit 回调的 data，不要用 getValues（拿到的是 coerce 前的原始值）。
+import type { SaveRequest } from "@/shared/api";
+form.handleSubmit(async (data) => {
+  const request: SaveRequest = { field: data.field };
+  await api.save(request);
+});
 
 // 调试
 logger.info("errors:", form.formState.errors);

package/miaoda/lark-apps/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: lark-apps
+description: "在妙搭沙箱里用 lark-cli 操作【当前这个已存在的】妙搭应用：开放 API Key。当用户要在沙箱里对当前应用做这些操作时使用（可用能力以本次打包的模块为准）。"
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli apps --help; lark-cli apps +<cmd> --help"
+control-by-feature-ab: true
+---
+
+# 妙搭应用 (apps) · 沙箱版
+
+在妙搭沙箱里通过 `lark-cli` 操作**当前这个已存在的**妙搭应用。
+
+## 沙箱约定（先读）
+
+- **命令名**：一律 `lark-cli apps +<cmd>`；命令/flag 细节以 `--help` 为准。
+- **应用已存在、app_id 走环境变量**：应用 id 在环境变量 `app_id` 里，命令需要 `--app-id` 时用 `--app-id "$app_id"`。
+- **鉴权自动**：apps 域请求由运行环境自动打到 innerAPI 并注入鉴权头。**不要** `auth login` / `config init` / `--as`。
+
+## 意图路由
+
+| 用户意图 | 命令 | 详情 |
+|---|---|---|
+| 管理开放 API Key（列/查/建/改/启停/删/轮换） | `+openapi-key-list` / `+openapi-key-get` / `+openapi-key-create` / `+openapi-key-update` / `+openapi-key-enable` / `+openapi-key-disable` / `+openapi-key-delete` / `+openapi-key-reset` | [openapi-key](references/openapi-key.md) ⚠️ create/reset 密钥一次性可见；delete/reset 高风险 |
+
+
+## 失败处理
+命令失败时把 `error.hint` 转述给用户，别原样甩 envelope JSON。
+
+## 高风险写操作审批（exit 10）
+`risk: high-risk-write` 的命令不带 `--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` 静默重试。

package/miaoda/lark-apps/references/openapi-key.md

@@ -0,0 +1,80 @@
+# apps openapi-key 命令族（开放 API Key）
+
+管理妙搭应用对外暴露的 HTTP API Key（`/openapi/**` 鉴权凭证）。命令事实以 `lark-cli apps +openapi-key-list --help`（各子命令同理）为准；本文件只记录 Agent 不看就会做错的领域规则。鉴权由沙箱运行环境自动注入（见 SKILL.md「鉴权自动」），命令无需也不要传身份参数。
+
+## 命令路由
+
+| 命令 | 用途 |
+|---|---|
+| `+openapi-key-list` | 列出应用所有 API Key（脱敏） |
+| `+openapi-key-get` | 查看单个 Key 详情（脱敏） |
+| `+openapi-key-create` | 创建新 Key，**原始密钥一次性可见** |
+| `+openapi-key-update` | 改名或改 config（不改 status） |
+| `+openapi-key-enable` | 启用 Key（status→1） |
+| `+openapi-key-disable` | 停用 Key（status→0），**泄露/疑似泄露优先用这个而非 delete** |
+| `+openapi-key-delete` | 永久删除 Key（不可逆，高风险） |
+| `+openapi-key-reset` | 轮换密钥（刷新原始 Key），**一次性可见**（高风险） |
+
+命令均带 `--app-id "$app_id"`（当前沙箱应用），如：
+
+```bash
+lark-cli apps +openapi-key-list --app-id "$app_id"
+```
+
+## 密钥红线（安全关键，务必遵守）
+
+- `create` / `reset` 返回的**原始密钥仅一次性可见**：只在 `data.api_key`（顶层）随本次响应返回一次，同时 stderr 打印一次性提示（大意：此密钥仅显示一次、不被 lark-cli 保存，请立即复制到你自己的密钥管理器）。
+- **绝不**把原始密钥写入 cache / config / recent / debug log / 错误信息，也不要在后续对话里回显完整密钥；只向用户转述一次并提示自行妥善保管。
+- **密钥丢失不能找回**：`list` / `get` 不回显原始密钥。唯一恢复方式是 `+openapi-key-reset` 重新生成新密钥（旧密钥同时失效）。
+
+## 脱敏口径
+
+- `list` / `get` / `update` / `enable` / `disable`：返回结构里 **无** `api_key` 字段，只有 `key_preview`（格式：`****` + 原始密钥末 4 位，如 `****5f4a`）。
+- `create` / `reset`：**仅** 在 `data.api_key`（顶层）返回原始密钥一次（见上「密钥红线」）。
+
+## scope 结构与 CLI 表达
+
+后端 `config.request_scope` 的真实结构（**snake_case**——Lark 开放网关 `/open-apis/` 对外契约约定；`api_key.thrift` 的 camelCase go.tag 是内部表示，OGW 已转成 snake_case）：
+
+```json
+{
+  "allow_all": true,
+  "http_infos": [
+    { "http_method": "GET", "http_path": "/openapi/some-path" }
+  ]
+}
+```
+
+- `allow_all=true`：放开该应用所有 `/openapi/**` 路由；`http_infos` 此时忽略。
+- `allow_all=false`：按 `http_infos` 逐条授权，每条需 `http_method`（大写）+ `http_path`（`/openapi/` 开头）。
+
+CLI 提供三种互斥的 scope 表达方式：
+
+| flag | 用途 | 备注 |
+|---|---|---|
+| `--scope-all` | `allow_all=true`，放开所有路由 | bool flag，显式传 `--scope-all=false` 也算"已设置" |
+| `--scope-api 'METHOD /openapi/path'` | 逐条授权一个路由，可重复 | 路由从应用 `docs/openapi.json` 取 |
+| `--scope '<raw request_scope JSON>'` | 高级逃生口，直传 request_scope JSON（snake_case） | CLI 只校验合法 JSON；`--scope` 与 `--scope-all`/`--scope-api` 互斥 |
+
+### scope 值来源
+
+妙搭应用的 `/openapi/**` 路由定义在应用仓库，并同步维护在 `docs/openapi.json`（`paths` 下每个 `"/openapi/..."` 条目 + HTTP 方法）。要授权哪些路由，读目标应用自己的 `docs/openapi.json`，取 `(method, path)` 对。CLI 本身不提供 API 路由发现功能（P1 规划中）。
+
+## 高风险操作（delete / reset）
+
+`delete` 和 `reset` 是高风险写操作（`high-risk-write`）：缺 `--yes` 会 **exit 10**（`confirmation_required`），须按 SKILL.md 的 exit-10 审批协议先征得用户显式同意再补 `--yes`——**不要**自动补 `--yes`；不确定先 `--dry-run` 查看将执行的 HTTP 请求（不含密钥）。
+
+- **泄露场景**：应优先 `+openapi-key-disable` 立即停用，而非 `+openapi-key-delete`——停用可随时 `+openapi-key-enable` 恢复，delete 不可逆。
+
+## 典型决策场景
+
+| 用户意图 | 正确操作 |
+|---|---|
+| "key 泄露了，先停掉" | `+openapi-key-disable`（不是 delete） |
+| "key 丢了/忘了，再给我一个" | `+openapi-key-reset`（不是 create 新 key；reset 轮换密钥、保留原 key 配置） |
+| "我的 key 密钥是什么" | 解释：list/get 不回显原始密钥，只能用 `+openapi-key-reset` 轮换 |
+| "给应用创建一个有权限限制的 key" | `+openapi-key-create --name ... --scope-api 'GET /openapi/...'`（路由取自应用 `docs/openapi.json`） |
+
+## 不在本 skill 范围
+
+- OpenAPI spec 全量导出、实时日志 tail、Webhook 消费、多鉴权方式：本期不支持。

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，运行时鉴权也用它匹配用户拥有的角色。