@amaster.ai/pi-lark 0.1.4 → 0.1.6

package/skills/lark-apps/references/lark-apps-db-execute.md

@@ -0,0 +1,228 @@
+# apps +db-execute
+
+经妙搭服务端在应用数据库执行 SQL。运行时命令事实以 `lark-cli apps +db-execute --help` 为准。
+
+> **写 SQL 前先看文末「平台 SQL 规范」**：妙搭底层是 PostgreSQL + 一层平台约束，SQL 内容不符合会被服务端直接拒或建出行为不对的表。最容易踩的三条：① 建业务表必须带 4 个审计列（`_created_at`/`_updated_at`/`_created_by`/`_updated_by`）+ 启用 RLS + 4 条 policy，一次调用里写全；② 人员字段用内置复合类型 `user_profile`（写入 `ROW('<user_id>')::user_profile`，查询解引用 `(field).user_id`）；③ `CREATE/DROP DATABASE·SCHEMA·USER·ROLE`、非白名单 `CREATE EXTENSION`、平台保留表 `auth`/`users` 会被硬拒，`online` 环境禁 DDL。
+
+## 何时用
+
+用于通过妙搭服务端执行应用数据库 SQL。不要从环境变量里取连接串裸连数据库；本地调试也走这个 shortcut。写什么样的 SQL（平台约束、建表模板、`user_profile`、审计列、禁用 SQL、PG 陷阱）见文末「平台 SQL 规范」。
+
+## 命令骨架
+
+- 必填：`--app-id`，以及 `--sql` / `--file` 二选一（互斥）。
+- `--sql`：内联 SQL 文本；传 `-` 时从 stdin 读。绝对路径文件经 stdin 传入：`--sql - < <absolute-path>`（shell 解析路径，CLI 仅接收内容）。
+- `--file`：`.sql` 文件路径，需为工作目录内的相对路径（如 `--file ./migration.sql`）；绝对路径、或经 `..`/符号链接越出工作目录的路径会被拒绝。文件不在工作目录内时，改用 `--sql - < <文件路径>` 经 stdin 传入。
+- `--environment` 枚举：`dev` / `online`，**不传则由服务端按应用是否开启多环境自动选择（多环境→`dev`，未开启多环境→`online`）**；要固定环境就显式传 `--environment dev|online`。**未开启多环境的应用显式传 `--environment dev` 会报错（无 dev 分支）——这类应用不传 `--environment`（走 `online`）或显式 `--environment online`**。旧名 `--env` 已**移除**：传入会报 validation 错（提示改用 `--environment`），一律用 `--environment`。
+- risk 是 `high-risk-write`（SQL 可含 DML/DDL）：任何执行都需 `--yes`，否则返回 `confirmation_required` / exit 10。`--dry-run` 预览不需要 `--yes`。
+- **不会自动为你包事务，事务边界需自己在 SQL 里控制**：多语句默认逐条独立提交，中间某条失败时前序语句已生效、不会回滚；若需要「要么全部成功、要么全部回滚」的原子性，请在 SQL 内显式写 `BEGIN … COMMIT`（详见下「Agent 规则」）。
+
+## 示例
+
+```bash
+lark-cli apps +db-execute --app-id app_xxx --environment dev --sql "select * from orders limit 5" --yes
+lark-cli apps +db-execute --app-id app_xxx --environment dev --file ./migration.sql --dry-run
+# 绝对路径文件 / cwd 不固定：经 stdin 传入
+lark-cli apps +db-execute --app-id app_xxx --environment dev --sql - --yes < /Users/.../migrations/0001_init.sql
+```
+
+## 输出契约
+
+- 成功默认 JSON 的 `data` 按 SQL 类型自适应（不透传后端原始串）：
+  - 单 SELECT → `data` 是行数组 `[{...}]`（空 → `[]`），直接 `-q '.data[].col'` 取字段。
+  - 单 DML → `data = {command, rows_affected}`（如 `{"command":"INSERT","rows_affected":1}`）。
+  - 单 DDL → `data = {command}`（如 `{"command":"CREATE_TABLE"}`）。
+  - 多语句 → `data` 是元素数组：SELECT 为 `{command:"SELECT", rows:[...]}`，DML 为 `{command, rows_affected}`，DDL 为 `{command}`。
+- pretty 会按 SELECT/DML/DDL 自适应渲染；多语句会逐条显示 Statement 摘要。
+- 失败返回 typed `error`（`type:"api"`、`subtype:"server_error"`、`code`、`message`、`hint`）：失败位置在 `message` 的「(at statement N of M)」；前序是否落地 / 是否整批回滚写在 `hint`——事务内失败「Transaction rolled back; no changes persisted.」；非事务多语句前序已落地「Earlier statements were committed and not rolled back; fix statement N and re-run the remaining statements.」；首句即失败（无前序落地）「No statements were applied; fix the SQL and re-run.」。据此决定整段重跑还是只跑剩余语句。
+
+## Agent 规则
+
+- 该命令为 high-risk-write，执行一律需 `--yes`；无 `--yes` 会返回 `confirmation_required` / exit 10。
+  - **只读查询、以及不删除/不丢失既有数据且可撤回的语句**：已授权时可直接带 `--yes` 执行。
+  - **会删除或丢失既有数据、或难以撤回的语句**：先 `--dry-run` 预览（无需 `--yes`），向用户确认后再带 `--yes` 执行；不要在用户不知情时自动补 `--yes`。
+- 多语句失败时，失败前的语句可能已经 commit 落地。不要整批重跑；按错误 message/hint 修失败语句，并从剩余语句继续。
+- 如果需要原子性，让用户在 SQL 内显式写 `BEGIN` / `COMMIT`，不要假设 CLI 会包事务。
+- 不要把数据库连接串从 env 中取出来裸连。
+
+---
+
+# 平台 SQL 规范
+
+上面讲命令怎么调，这里讲**该写出什么样的 SQL**：妙搭底层是 PostgreSQL + 一层平台约束（RLS、审计列、`user_profile` 复合类型、禁用 SQL 白名单），不符合会被服务端直接拒或建出行为不对的表。看表 / 看结构用 [`+db-table-list`/`+db-table-get`](lark-apps-db.md)，别手写系统表查询模拟。
+
+## 平台禁用 SQL（硬拒绝）
+
+以下命中会被服务端拒，`error`（`type:"api"`）的 message/hint 会说明原因——先按 hint 修再重试，不要反复重试同一句。
+
+| 类别 | 禁止 |
+|---|---|
+| 数据库级 | `CREATE / DROP / ALTER DATABASE` |
+| Schema 级 | `CREATE / DROP SCHEMA` |
+| 用户 / 角色级 | `CREATE / DROP USER`、`CREATE / DROP / ALTER ROLE` |
+| Owner 切换 | `REASSIGN OWNED` / `DROP OWNED` |
+
+## 建表规范（CREATE TABLE）
+
+新建业务表必须：4 个审计列 + 启用 RLS + 4 条默认 policy，**放在同一次 `+db-execute` 调用里**（RLS / policy / COMMENT / INDEX 一起）。裸表名，不写 `public.` 或 schema 前缀。
+
+```sql
+CREATE TABLE IF NOT EXISTS <table> (
+  id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+  -- ... 业务列 ...
+  name varchar(100) NOT NULL,
+  _created_at TIMESTAMP(3) WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  _created_by user_profile DEFAULT (
+    CASE
+      WHEN current_setting('app.user_id', TRUE) = '' THEN NULL
+      ELSE concat('(', current_setting('app.user_id', TRUE), ')')::user_profile
+    END
+  ),
+  _updated_at TIMESTAMP(3) WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  _updated_by user_profile DEFAULT (
+    CASE
+      WHEN current_setting('app.user_id', TRUE) = '' THEN NULL
+      ELSE concat('(', current_setting('app.user_id', TRUE), ')')::user_profile
+    END
+  )
+);
+
+ALTER TABLE <table> ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY service_role_bypass_policy ON <table>
+  TO service_role USING (true);
+
+CREATE POLICY "修改全部数据" ON <table>
+  AS PERMISSIVE FOR ALL TO authenticated USING (true);
+
+CREATE POLICY "查看全部数据" ON <table>
+  AS PERMISSIVE FOR SELECT TO authenticated, anon USING (true);
+
+CREATE POLICY "修改本人数据" ON <table>
+  AS PERMISSIVE FOR ALL TO authenticated USING (
+    (current_setting('app.user_id'::text) = ANY (ARRAY[]::text[]))
+    AND (current_setting('app.user_id'::text) = ((_created_by).user_id)::text)
+  );
+```
+
+建表流程：先 `+db-table-list` / `+db-table-get` 确认表不存在或看现有结构 → 生成 DDL → 向用户展示影响并取得授权 → `+db-execute ... --yes` 执行。
+
+## 审计列
+
+- 平台自动维护的四列固定叫 `_created_at` / `_updated_at` / `_created_by` / `_updated_by`（**下划线开头**）。查询 / 排序 / 过滤一律用这些名字，别写 `created_at`。
+- `_created_at` / `_updated_at` 在 INSERT 时可省略（有默认值）；需要业务归属时显式写 `_created_by` / `_updated_by`。
+- UPDATE 业务字段时建议同步 `_updated_at = CURRENT_TIMESTAMP` 和 `_updated_by`。
+
+## `user_profile` 复合类型
+
+平台内置类型 `(user_id varchar, name varchar, email varchar, avatar text, status integer)`，无需创建。**业务 SQL 只允许访问 `(field).user_id`**，不要依赖 `name` / `email` / `avatar` / `status`（可能为空或过期）。
+
+```sql
+-- 写入 / 更新：用 ROW()::user_profile，更新时替换整个字段，不改单个属性
+INSERT INTO teacher (teacher_profile, class_id)
+VALUES (ROW('<user_id>')::user_profile, gen_random_uuid());
+
+UPDATE teacher SET teacher_profile = ROW('<user_id>')::user_profile
+WHERE (teacher_profile).user_id = '<old_user_id>';
+
+-- 查询 / 过滤：解引用取 user_id；raw SQL 返回给前端前必须解引用，别直接返回复合类型
+SELECT (teacher_profile).user_id AS teacher_profile, class_id FROM teacher;
+
+-- 索引 / 唯一性：表达式列用三重括号；表达式唯一性用 CREATE UNIQUE INDEX，
+-- 不能用 ALTER TABLE ADD CONSTRAINT UNIQUE（不支持表达式列）
+CREATE INDEX idx_teacher_user_id ON teacher (((teacher_profile).user_id));
+CREATE UNIQUE INDEX uk_teacher_user_id ON teacher (((teacher_profile).user_id));
+```
+
+## DDL 规则
+
+| 场景 | 做法 |
+|---|---|
+| 加列 | `ALTER TABLE <t> ADD COLUMN IF NOT EXISTS <col> <type>`，相关 `COMMENT ON` 同次执行 |
+| 加索引 | `CREATE INDEX IF NOT EXISTS idx_<t>_<cols> ON <t>(...)` |
+| JSONB 类型声明 | 必须 `COMMENT ON COLUMN <t>.<col> IS '@type { ... }'` 声明 TypeScript 类型，和 CREATE / ALTER 同次调用 |
+| 加 NOT NULL 列 | 必须带 `DEFAULT` 让存量行自动填：`ADD COLUMN <col> <type> NOT NULL DEFAULT <值>` |
+| 删表 / 删列 | 有业务数据默认禁止；必须用户明确授权后才执行，并说明数据丢失风险 |
+| 强约束 | `UNIQUE` / `FOREIGN KEY` / `NOT NULL` 默认谨慎，不确定不加 |
+
+**多环境库加约束前先查 online 存量**：`dev` 干净不代表 `online` 干净，约束发布到 online 会撞线上存量数据而失败。发布前一律先用 `--environment online` 查清楚，按约束类型分三种：
+
+- **加唯一约束（`UNIQUE` / 唯一索引）**：线上不能有重复值。先查重复，有则先清理再加：
+
+  ```bash
+  lark-cli apps +db-execute --app-id app_xxx --environment online --sql \
+    "SELECT <cols>, count(*) FROM t GROUP BY <cols> HAVING count(*) > 1" --yes
+  ```
+
+- **已有列改 `NOT NULL`（收紧约束）**：线上该列不能有 NULL。先查 NULL 行数，有就先回填（`UPDATE t SET <col> = <默认值> WHERE <col> IS NULL`）再加约束：
+
+  ```bash
+  lark-cli apps +db-execute --app-id app_xxx --environment online --sql \
+    "SELECT count(*) FROM t WHERE <col> IS NULL" --yes
+  ```
+
+- **新加 `NOT NULL` 字段**：必须带 `DEFAULT`，且要求线上该表**无存量数据**，否则发布报错。线上已有数据时别直接加，改走三步安全变更：先 `ADD COLUMN <col> <type>`（可空）→ 回填 `UPDATE t SET <col> = <值>` → 再 `ALTER COLUMN <col> SET NOT NULL`。先查线上行数判断走哪条：
+
+  ```bash
+  lark-cli apps +db-execute --app-id app_xxx --environment online --sql \
+    "SELECT count(*) FROM t" --yes
+  ```
+
+## SELECT 规则
+
+| 规则 | 要求                                                               |
+|---|------------------------------------------------------------------|
+| 行数 | 结果集有硬上限（平台限制 1000 行），超限**报错而非静默截断**；大表必须显式 `LIMIT`、聚合或游标分页       |
+| 分页 | 大表优先游标分页 `WHERE id > <last_id> ORDER BY id LIMIT n`，避免大 `OFFSET` |
+| user_profile | 返回给前端前解引用：`(owner).user_id AS owner`                             |
+| 统计 | 总数用 `count(*)`、分组用 `GROUP BY`，别把全量拉到 agent 侧再统计                  |
+| 慢查询 | 用 `EXPLAIN (ANALYZE, BUFFERS)`；大表 Seq Scan 考虑加索引                 |
+
+## DML 规则
+
+**INSERT**
+- UUID 主键省略，交给 `DEFAULT gen_random_uuid()`；外键 UUID 用子查询取父表 id，不手写。
+- NOT NULL 且无默认值的列必须给值；批量 INSERT 每行列数一致。
+- 需要幂等用 `ON CONFLICT ... DO NOTHING / DO UPDATE`。
+- 标量子查询必须保证单行，非唯一条件加 `ORDER BY ... LIMIT 1`。
+
+**UPDATE**
+- **必须有明确 `WHERE`，禁止无条件 UPDATE**。
+- 用户说「修改 / 更新 / 改一下」数据时用 UPDATE，**禁止 DELETE + INSERT** 模式。
+- 更新 `user_profile` / 复合类型时替换整个字段。
+- 批量更新前影响范围不明确，先 `SELECT count(*)` 给用户确认。
+
+**DELETE / TRUNCATE**（属会丢数据的高影响操作，按上面「Agent 规则」的确认流程走）
+- 已有表 / 已有数据默认禁止；先 `SELECT count(*)` 展示命中行数、取得用户明确授权，再带 `--yes` 执行。
+- `TRUNCATE` 影响整表，视同高风险删除。
+
+```sql
+UPDATE task
+SET status = 'done', _updated_at = CURRENT_TIMESTAMP, _updated_by = ROW('<user_id>')::user_profile
+WHERE id = (SELECT id FROM task WHERE title = '梳理需求' ORDER BY _created_at DESC LIMIT 1);
+```
+
+## 常见 PostgreSQL 陷阱
+
+| 陷阱 | 正确做法 |
+|---|---|
+| 表名带 schema 前缀 | 业务表一律裸表名 `FROM orders`，别写 `public.orders` |
+| 保留字作标识符 | 避免 `user` / `order` / `desc` / `offset` / `references` 等 |
+| 内联 COMMENT | 禁止 `col TEXT COMMENT 'xx'`，用独立 `COMMENT ON COLUMN` |
+| 手写系统表查结构 | 常规结构查询用 `+db-table-list` / `+db-table-get`，别手写 `information_schema` / `pg_indexes` 模拟 |
+| 空数组类型不明 | 写 `ARRAY[]::text[]` 或 `'{}'::text[]` |
+| `ROUND` 报错 | 用 `ROUND(num::numeric, n)` 或 `ROUND(num::double precision)` |
+| `DISTINCT` + 窗口函数 | 分两层查询，先 DISTINCT 再窗口函数 |
+| MySQL 方言 | 不用 `SHOW TABLES` / `DESCRIBE` / 内联 `COMMENT`；用 `+db-table-*` 和 `COMMENT ON` |
+| 多语句以为自动回滚 | `A; B; C` 不自动包事务，B 失败时 A 已提交；要原子性显式 `BEGIN; ... COMMIT;`（见上「命令骨架」「Agent 规则」） |
+
+## 数据类型与设计
+
+| 项目 | 规则 |
+|---|---|
+| 主键 | 默认 `id uuid PRIMARY KEY DEFAULT gen_random_uuid()` |
+| 命名 | 表名单数、全小写、snake_case、无冗余后缀 |
+| 枚举 / 状态 | 用 `varchar(255)`，值用小写英文 + 下划线 |
+| JSONB | 必须 `COMMENT ON COLUMN ... IS '@type { ... }'` 声明类型 |
+| 附件 / 图片 | URL 用 `TEXT`，命名 `xxx_url` |
+| 约束 | `UNIQUE` / `FOREIGN KEY` / `NOT NULL` 默认谨慎，新增 NOT NULL 列优先带 `DEFAULT` |

package/skills/lark-apps/references/lark-apps-db.md

@@ -0,0 +1,162 @@
+# apps db 域命令
+
+管理妙搭应用数据库：看表与结构、初始化与发布多环境、数据搬运、变更治理、时间点恢复、用量。逐条跑 SQL（SELECT/DML/DDL）走 [`+db-execute`](lark-apps-db-execute.md)（单独一篇）。运行时命令事实以 `lark-cli apps +<cmd> --help` 为准；认证、`--as user`、exit 码、`_notice` 等通用处理见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 与本域 [`SKILL.md`](../SKILL.md)。
+
+## 何时用
+
+用户要看应用里有哪些表 / 某张表的结构、把单库应用拆成 dev/online 多环境、把数据导进导出表、查谁在什么时候改了表结构或表数据、开关行级审计、把开发环境的库结构发布到线上、把库恢复到过去某个时间点、或看数据库用量时。逐条执行 SQL 走 [`+db-execute`](lark-apps-db-execute.md)；文件存储（上传/下载文件）走 [`lark-apps-file.md`](lark-apps-file.md)。**建表 / 改表 / 写 SQL 的平台内容规范**（审计列、RLS、`user_profile`、禁用 SQL、PG 陷阱）见 [`lark-apps-db-execute.md`](lark-apps-db-execute.md) 的「平台 SQL 规范」。
+
+## 命令一览
+
+| 命令 | 做什么 | 关键参数 |
+|---|---|---|
+| `+db-table-list` | 列出某环境的数据表 | `--environment`、`--page-size`/`--page-token` |
+| `+db-table-get` | 看单张表的结构（字段/索引/约束/DDL） | `--table`、`--environment`、`--format` |
+| `+db-env-create` | 把单库应用初始化为 dev/online 多环境（高危） | `--environment`、`--sync-data`、`--yes` |
+| `+db-data-export` | 把一张表的数据导出到本地文件 | `--table`、`--output`、`--limit`、`--environment` |
+| `+db-data-import` | 把本地 csv/json 文件导进一张表（高危） | `--file`、`--table`、`--environment`、`--yes` |
+| `+db-changelog-list` | 查表结构变更（DDL）历史 | `--table`、`--change-id`、`--since`/`--until`、`--environment` |
+| `+db-audit-status` | 看哪些表开了行级审计、保留期 | `--table`、`--environment` |
+| `+db-audit-enable` | 给某表开启行级变更审计 | `--table`、`--retention`、`--environment` |
+| `+db-audit-disable` | 关闭某表的行级审计 | `--table`、`--environment` |
+| `+db-audit-list` | 列出表的行级变更事件（增删改追溯） | `--table`（可重复）、`--since`/`--until`、`--environment` |
+| `+db-env-diff` | 预览开发环境待发布到线上的结构变更 | `--app-id` |
+| `+db-env-migrate` | 把开发环境的结构变更发布到线上（高危） | `--app-id`、`--yes` |
+| `+db-recovery-diff` | 预览把库恢复到某时间点会带来的变更 | `--target` |
+| `+db-recovery-apply` | 把库恢复到某个时间点、覆盖当前数据（高危） | `--target`、`--yes` |
+| `+db-quota-get` | 查数据库存储用量 | `--environment` |
+
+## 约定（先读）
+
+- **环境 `--environment dev|online`（可省略）**：看表、看结构、数据导入导出、变更追溯、审计、配额都按环境区分。省略 `--environment` 时 CLI 不带该参数、由服务端按应用形态自动选分支——多环境应用走 `dev`、未开多环境的走 `online`；要固定环境就显式传。唯一会报错的组合：对未开多环境的应用显式传 `--environment dev`（无 `dev` 分支）。写操作建议先在 `dev` 验（仅多环境应用有 `dev`）。旧名 `--env` 已**移除**：传入会报 validation 错（提示改用 `--environment`），一律用 `--environment`。`+db-env-diff`/`+db-env-migrate` 是「dev→online 发布」语义，**没有** `--environment`。
+- **本地文件 / `--output` 用工作目录内相对路径**：导入 `--file ./orders.csv`、导出 `--output ./out.csv`；绝对路径、或经 `..`/符号链接越出工作目录的 `--output` 会被拒（validation / exit 2）。路径在别处先 `cd` 过去或改成相对路径。
+- **高危操作必须带 `--yes`**：`+db-env-create`、`+db-data-import`、`+db-env-migrate`、`+db-recovery-apply` 缺省会被确认关卡拦下；动手前先用对应的预览命令或 `--dry-run` 看清影响。
+- **时间参数按口语自然传**（`--since`/`--until`/`--target`），格式见末尾。
+
+## 各命令
+
+### 表与结构
+
+**`+db-table-list`**：列出某环境的数据表。分页 `--page-size`（默认 20）/ `--page-token`（上一页 cursor）。每项给表名、描述、估算行数、大小、列数；要完整列定义 / 索引 / 约束用 `+db-table-get`。只知道业务对象名时，先用它定位可能的表名。
+
+```bash
+lark-cli apps +db-table-list --app-id app_xxx
+lark-cli apps +db-table-list --app-id app_xxx --environment dev --page-size 50
+```
+
+**`+db-table-get`**：看单张表的结构。默认 JSON 给结构化的字段 / 索引 / 约束 / 估算行数 / 大小；`--format pretty` 直接输出建表 DDL 文本（给用户看建表语句或做迁移参照时用）。
+
+```bash
+lark-cli apps +db-table-get --app-id app_xxx --table orders
+lark-cli apps +db-table-get --app-id app_xxx --table orders --environment dev --format pretty
+```
+
+### 多环境数据库（初始化 + 发布）
+
+**`+db-env-create`（高危）**：把存量单库应用初始化为 dev/online 两套库，不可逆，必须带 `--yes`。`--environment` 目前只支持 `dev`（默认 `dev`）；`--sync-data` 把现有 online 数据复制到新环境（不传则不复制）。注意：`+create --app-type full_stack` 新建的应用通常已自带多环境，重复初始化会返回冲突错误（应用已是多环境）——按 `error.hint` 转述状态即可，别重复初始化。
+
+```bash
+lark-cli apps +db-env-create --app-id app_xxx --environment dev --dry-run
+lark-cli apps +db-env-create --app-id app_xxx --environment dev --sync-data --yes
+```
+
+**`+db-env-diff`**：预览开发环境里待发布到线上的表结构变更，不落地。发布前先看这个。无待发布变更时明确返回「无变更」。
+
+**`+db-env-migrate`（高危）**：把开发环境的结构变更正式发布到线上，不可逆，必须带 `--yes`，返回实际发布的变更条数。发布是异步的，命令会等到完成再返回结果。
+
+> 预览与发布同一端点，故 `+db-env-diff` 也需 `spark:app:write` scope（不是纯只读权限）。
+
+```bash
+lark-cli apps +db-env-diff --app-id app_xxx
+lark-cli apps +db-env-migrate --app-id app_xxx --yes
+```
+
+### 数据导入导出
+
+**`+db-data-export`**：把一张表导出到本地文件。导出格式**只由 `--output` 的扩展名决定**——`.csv` / `.json` / `.sql`，缺省按 `<表名>.csv` 落在当前目录。注意：全局 `--format json|pretty` 只控制**命令自身输出**（成功摘要 / 错误信封）的渲染，**不影响导出文件的格式**；`--output` 后缀必须是 `.csv/.json/.sql` 之一，否则报 validation 错误（exit 2），且不支持导出到 stdout。两道体量约束：
+
+- `--limit`（1..5000，默认 5000）是**行数上限守卫**：表的行数超过它会被整体拒掉（不是「只导前 N 行」）；
+- 导出产物 >1 MB 也会被拒。
+
+超大表别硬导：先用 `+db-execute` 加 `WHERE` / `LIMIT` 缩小范围、分批导。
+
+```bash
+lark-cli apps +db-data-export --app-id app_xxx --table orders --output ./orders.csv
+lark-cli apps +db-data-export --app-id app_xxx --table orders --output ./orders.json --environment dev
+```
+
+**`+db-data-import`（高危）**：把本地 csv/json 文件的数据导进表。文件需是 `.csv`/`.json`、≤1 MB，必须带 `--yes`。目标表缺省取文件名去掉**最后一个**扩展名（如 `orders.csv`→`orders`，`orders.2026.csv`→`orders.2026`）；文件名带点号时建议显式传 `--table` 以免落到意外的表名。
+
+```bash
+lark-cli apps +db-data-import --app-id app_xxx --table orders --file ./orders.csv --environment dev --yes
+```
+
+**导入/导出限额**：体积 ≤ **1 MB**、行数 ≤ **5000**，导入导出都一样，超限会被拒。超限就分批——导入拆成 ≤1 MB / ≤5000 行的多个文件，导出用 `WHERE` / `LIMIT` 缩小范围。
+
+### 变更追溯与审计
+
+**`+db-changelog-list`**：查表结构变更（DDL）历史——谁、什么时候、改了哪张表、做了什么。可按 `--table` 过滤、按 `--change-id` 精确定位某条、用 `--since`/`--until` 圈时间区间，分页 `--page-size`/`--page-token`。
+
+```bash
+lark-cli apps +db-changelog-list --app-id app_xxx --table orders --since 7d
+```
+
+**`+db-audit-status`**：看审计开关状态。给 `--table` 看单表，不给则列出所有已配置的表（开没开、保留期）。
+
+**`+db-audit-enable` / `+db-audit-disable`**：开 / 关某张表的行级变更审计。`--retention` 设保留期，取值 `7d`/`30d`/`180d`/`360d`/`forever`（默认 `7d`）。不要对已经开启审计的表重复 enable——不确定就先用 `+db-audit-status` 查。
+
+```bash
+lark-cli apps +db-audit-enable --app-id app_xxx --table orders --retention 30d
+lark-cli apps +db-audit-disable --app-id app_xxx --table orders
+```
+
+**`+db-audit-list`**：列出表的行级变更事件（INSERT/UPDATE/DELETE 的前后值与操作人）。`--table` 必填、可重复传多张表；`--since`/`--until` 圈时间。
+- **多表查询**：会先帮用户把不存在、或没开审计的表过滤掉再查，被过滤的表及原因列在结果的 `skipped` 里——据此告诉用户哪些表没纳入及为什么。
+- **单表查询**：不预过滤，表不存在 / 未开审计会直接报错（按 `error.hint` 转述给用户，引导先 `+db-audit-enable`）。
+
+```bash
+lark-cli apps +db-audit-list --app-id app_xxx --table orders --since 24h
+lark-cli apps +db-audit-list --app-id app_xxx --table orders --table users
+```
+
+### 时间点恢复（PITR）
+
+**`+db-recovery-diff`**：预览把库恢复到 `--target` 时间点会带来哪些变更（受影响的表、行数、预计耗时），不落地。同样需 `spark:app:write` scope。
+
+**`+db-recovery-apply`（高危）**：把库恢复到某个时间点，**会覆盖当前数据**，不可逆，必须带 `--yes`。
+
+- 可恢复窗口最长 **7 天**，且不早于**最近一次 `+db-env-migrate`**；超出窗口的目标会被拒。
+- 目标时间点与当前库一致时返回 `no_changes`（空操作），不算失败。
+- 动手前务必先 `+db-recovery-diff` 给用户确认。
+
+```bash
+lark-cli apps +db-recovery-diff --app-id app_xxx --target 2h
+lark-cli apps +db-recovery-apply --app-id app_xxx --target 2026-04-15T10:00:00Z --yes
+```
+
+### 配额
+
+**`+db-quota-get`**：查数据库存储用量（已用量、表数、视图数；配额接入后还会给总配额与使用率）。
+
+```bash
+lark-cli apps +db-quota-get --app-id app_xxx --environment dev
+```
+
+## 时间格式（`--since` / `--until` / `--target`）
+
+按用户口语自然传入即可，支持：
+- 相对时间 `7d` / `2h` / `30s`（从现在往前推）
+- 日期 `2026-04-15`
+- 日期时间 `2026-04-15T10:00:00`
+- 带时区的 ISO 8601 `2026-04-15T10:00:00Z` / `2026-04-15T10:00:00+08:00`
+
+> **时区**：不带时区的 `日期` / `日期时间` 按**运行机器的本地时区**解析（再归一化到 UTC）。CI（UTC）与本地（如 UTC+8）跑同一条命令，时间边界会差几小时；要精确锁定时区时显式写 ISO 8601 带偏移（如 `...+08:00` / `...Z`）。`--target`（PITR 恢复）尤其建议带时区，避免恢复到非预期时间点。
+
+## Agent 规则
+
+- 用户说「本地 / 开发库 / 调试库」优先 `--environment dev`，线上排查用 `--environment online`；数据面写操作（导入 / 审计开关）建议先在 `dev` 验再动 `online`。**注意省略 `--environment` 时写操作会落到服务端选中的分支——单环境应用即 `online`（生产）**：不确定应用是否多环境时，写操作显式传 `--environment`；显式 `dev` 在单环境应用上会安全报错（无 dev 分支），正好当「是否多环境」的探针用。
+- 看表用 `+db-table-list`，看结构用 `+db-table-get`（要建表语句加 `--format pretty`）；`+db-env-create` 仅用于存量单库拆多环境，新建的 full_stack 应用一般不需要。
+- 四个高危命令（`+db-env-create`、`+db-data-import`、`+db-env-migrate`、`+db-recovery-apply`）动手前先看清影响再带 `--yes`：发布 / 恢复先跑对应预览 `+db-env-diff` / `+db-recovery-diff`，导入无预览命令、可先 `--dry-run` 看请求或先在 `--environment dev` 验；不要静默追加 `--yes`，遇 confirmation_required（exit 10）按 lark-shared 协议向用户确认不可逆风险后再补 `--yes` 重试。
+- 导入 / 导出的本地路径用工作目录内相对路径；超大表导出会被行数 / 体积上限拒，改用 `+db-execute` 分批。
+- `+db-audit-list` 多表查询时，把结果里 `skipped` 的表（不存在 / 未开审计）连同原因一并向用户说明，不要让用户以为这些表「没有变更」。
+- 恢复是覆盖式且不可逆：`+db-recovery-apply` 前必须先 `+db-recovery-diff`，并明确告知用户会覆盖当前数据。

package/skills/lark-apps/references/lark-apps-env-pull.md

@@ -0,0 +1,37 @@
+# apps +env-pull
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)（认证 / 全局参数 / 安全）。
+
+把妙搭应用 dev 启动期环境变量拉取到本地项目根的 `.env.local`。身份固定 `--as user`；scope `spark:app:read`。`--app-id` 必填，目标项目根默认当前工作目录（`--project-path` 可指定）。
+
+这个命令是 dev-only 的本地恢复工具：内部固定 `POST env_vars`，body 为 `env=dev`。它没有 `--env` flag，也不管理线上环境变量。
+
+## 何时别用（核心反模式）
+
+**通常不需要手动跑**——脚手架的 `npm run dev` 在起本地开发时会自动后台拉取（非阻塞）。手动再跑会重复做同样的事，并用服务端返回值覆盖 `.env.local` 里的同名 key；本地无关行和注释会保留。
+
+只在这些兜底场景用：
+
+- 不通过 `npm run dev` 启动（直接跑 `node` / IDE debug）。
+- `.env.local` 被改坏 / 删除，想重新同步。
+
+## 行为
+
+- **合并、不清空**：写入 `.env.local` 时保留你手写的内容与注释——命中的 key 替换值，新 key 追加，不整体覆盖。
+- **安全护栏**：返回的 envelope **不会回显任何 env key / value**（防止 token / 数据库凭据泄漏到日志或 CI 输出）。要看实际值请直接读 `.env.local`。
+
+## 示例
+
+```bash
+lark-cli apps +env-pull --app-id <app_id>
+```
+
+## 失败处理
+
+`missing_scope`（没拿到 `spark:app:read`）时，按 lark-shared 引导 `lark-cli auth login --domain apps`。其余失败优先转述 `error.hint` / `error.message`。
+
+## 参考
+
+- [lark-apps](../SKILL.md) — 妙搭应用全部命令 + 心智模型
+- [lark-apps-local-dev](lark-apps-local-dev.md) — 本地全栈开发端到端流程
+- [lark-shared](../../lark-shared/SKILL.md) — 认证和全局参数

package/skills/lark-apps/references/lark-apps-env.md

@@ -0,0 +1,48 @@
+# apps env
+
+> **前置条件：** 先阅读 [`../lark-shared/SKILL.md`](../../lark-shared/SKILL.md)（认证 / 全局参数 / 安全）。
+
+管理妙搭应用环境变量。查看用 `+env-list`，设置用 `+env-set`，删除用 `+env-delete`。没有单变量 get 命令；要确认某个 key 是否存在，使用 list 后用 `--jq` 过滤。
+
+环境 flag 使用 `--environment`；不要使用旧的 `--env`，也不要使用短选项。
+
+## 查看
+
+`+env-list` 默认查 dev，且默认不返回 value。只有显式传 `--include-values` 后，响应中才可能出现变量值；不要在公开日志里展示带值输出。
+
+接口契约：list 使用 `POST env_vars`，body 固定包含 `env` 和 CLI 场景 `scene=2`；set 使用 `POST create_or_update_env_var`；delete 使用 `POST delete_env_vars`。`--include-values` 只控制 CLI 输出是否展示 value，不作为服务端查询参数发送。
+
+```bash
+lark-cli apps +env-list --app-id <app_id>
+lark-cli apps +env-list --app-id <app_id> --environment online
+lark-cli apps +env-list --app-id <app_id> --include-values --jq '.data.items[] | select(.key == "FOO")'
+```
+
+## 设置
+
+dev 环境设置不需要 `--yes`。设置 online 环境需要人类确认并显式传 `--yes`；如果用户在同一轮已经明确说“确认/直接执行”，视为已确认，直接带 `--yes`，不要再次追问。`--dry-run` 可用于预览请求且不需要 `--yes`。变量值支持直接传 `<value>`，也支持 `@file` 或 stdin 输入。
+
+回复中只说明 app/env/key 和执行结果；不要回显真实 value。需要举例时使用 `<value>`、`@file` 或 stdin。
+
+```bash
+lark-cli apps +env-set --app-id <app_id> --key FOO --value <value>
+lark-cli apps +env-set --app-id <app_id> --key FOO --value @./secret.txt
+lark-cli apps +env-set --app-id <app_id> --environment online --key FOO --value <value> --dry-run
+lark-cli apps +env-set --app-id <app_id> --environment online --key FOO --value <value> --yes
+```
+
+## 删除
+
+`+env-delete` 是 high-risk-write。尊重 exit 10 confirmation protocol：先让用户确认 app/env/key 和删除后果，再传 `--yes`。不要自动补 `--yes`。如果只是认证失败后让用户重登，重登完成不等于删除确认；继续删除前仍需确认。
+
+```bash
+lark-cli apps +env-delete --app-id <app_id> --key FOO --dry-run
+lark-cli apps +env-delete --app-id <app_id> --key FOO --yes
+lark-cli apps +env-delete --app-id <app_id> --environment online --key FOO --yes
+```
+
+## 反模式
+
+- 不要把 `+env-pull` 当成环境变量管理命令；它只是刷新本地 `.env.local` 的兜底工具。
+- 不要为了看一个变量臆造名为 env-get 的 apps shortcut；用 `+env-list --include-values` 加 `--jq`。
+- 不要把真实 secret 写进示例或对话输出；需要示例时使用 `<value>`、`@file` 或 stdin。

package/skills/lark-apps/references/lark-apps-file.md

@@ -0,0 +1,96 @@
+# apps file 域命令（应用存储）
+
+管理妙搭应用的文件存储：上传 / 下载本地文件、列出与查看已存文件、生成临时分享链接、批量删除、查看用量。运行时命令事实以 `lark-cli apps +<cmd> --help` 为准；认证、`--as user`、exit 码、`_notice` 等通用处理见 [`../lark-shared/SKILL.md`](../lark-shared/SKILL.md) 与本域 [`SKILL.md`](../SKILL.md)。
+
+## 何时用
+
+用户要在某个妙搭应用里上传 / 下载 / 列出 / 删除文件、拿文件的临时分享链接、或看存储用量时。普通飞书云盘走 [`lark-drive`](../../lark-drive/SKILL.md)；数据库里的表数据走 `+db-*`。
+
+## 命令一览
+
+| 命令 | 做什么 | 关键参数 |
+|---|---|---|
+| `+file-list` | 列出文件，可按名/路径/类型/大小/上传时间过滤 | `--app-id`、过滤器、`--page-size`/`--page-token` |
+| `+file-get` | 查单个文件的元数据 | `--app-id`、`--path` |
+| `+file-sign` | 生成有时效的下载链接（用于分享 / 直接下载） | `--app-id`、`--path`、`--expires-in` |
+| `+file-download` | 把远端文件保存到本地 | `--app-id`、`--path`、`--output` |
+| `+file-upload` | 上传本地文件到应用存储 | `--app-id`、`--file` |
+| `+file-delete` | 按路径批量删除文件 | `--app-id`、`--path`（可重复）、`--yes` |
+| `+file-quota-get` | 查应用的文件存储用量 | `--app-id` |
+
+## 寻址与约定（先读）
+
+- **远端文件统一用 `--path` 精确寻址**（远端路径，带前导 `/`）。只知道文件名时，先用 `+file-list --name <名>` 定位拿到 `path`，再做后续操作。
+- **本地文件 / 输出路径用工作目录内的相对路径**（如 `--file ./report.pdf`、`--output ./out.png`）；路径在别处时先 `cd` 过去或改成相对路径。
+- 上传只接收本地 `--file`：文件名沿用本地文件名，远端路径由平台分配、全局唯一（无需也无法手填）。
+- file 域不区分环境，没有 `--env`。
+
+## 各命令
+
+### +file-list
+列出应用文件，支持精确过滤：`--name`（文件名）、`--path`（远端路径）、`--type`（MIME 类型）、`--size-gt`/`--size-lt`（字节）、`--uploaded-since`/`--uploaded-until`（上传时间区间，时间格式见末尾）。分页 `--page-size`（默认 20）/ `--page-token`。列表每项给名称、路径、大小、类型、上传时间（pretty 表格即这 5 列）；上传者、下载地址（如有）仅在 JSON 输出里，单文件详情用 `+file-get`。
+
+```bash
+lark-cli apps +file-list --app-id app_xxx
+lark-cli apps +file-list --app-id app_xxx --type image/png --uploaded-since 7d
+```
+
+### +file-get
+按 `--path` 查单个文件的元数据。路径不存在时返回明确的「文件不存在」错误。
+
+```bash
+lark-cli apps +file-get --app-id app_xxx --path /1858537546760216.png
+```
+
+### +file-sign
+为指定文件生成一个**有时效的下载链接**——适合发给用户分享、或直接下载。`--expires-in` 设有效期秒数（默认 1 天，最长 30 天）。`pretty` 模式只输出链接本身，便于复制 / 管道；要把到期时间一并告诉用户时用默认 JSON 输出（含到期时间）。
+
+```bash
+lark-cli apps +file-sign --app-id app_xxx --path /1858537546760216.png --expires-in 3600
+```
+
+### +file-download
+把远端文件保存到本地。`--output` 指定保存路径，缺省时按远端文件名保存到当前目录。
+
+```bash
+lark-cli apps +file-download --app-id app_xxx --path /1858537546760216.png --output ./logo.png
+```
+
+### +file-upload
+上传一个本地文件。文件名沿用本地文件名（特殊字符做 URL 编码透传；以 `.` 开头的隐藏文件名会加 `_` 前缀，避免下载回本地时覆盖隐藏文件），远端路径由平台分配。单文件上限 100 MB。
+
+```bash
+lark-cli apps +file-upload --app-id app_xxx --file ./report.pdf
+```
+
+### +file-delete（高危）
+按路径批量删除，`--path` 可重复传多个。删除是高危操作，必须带 `--yes`；缺省会被确认关卡拦下。**逐项返回结果**：部分文件删除失败（如某个路径不存在）不影响其余文件，整体仍算成功，失败项在结果里单独标出原因。
+
+```bash
+lark-cli apps +file-delete --app-id app_xxx --path /1858537546760216.png --yes
+lark-cli apps +file-delete --app-id app_xxx --path /a.png --path /b.png --yes
+```
+
+### +file-quota-get
+查应用的文件存储用量（已用量、文件数；配额接入后还会给总配额与使用率）。
+
+```bash
+lark-cli apps +file-quota-get --app-id app_xxx
+```
+
+## 时间格式（`--uploaded-since` / `--uploaded-until`）
+
+按用户口语自然传入即可，支持：
+- 相对时间 `7d` / `2h` / `30s`（从现在往前推）
+- 日期 `2026-04-15`
+- 日期时间 `2026-04-15T10:00:00`
+- 带时区的 ISO 8601 `2026-04-15T10:00:00Z` / `2026-04-15T10:00:00+08:00`
+
+> **时区**：不带时区的 `日期` / `日期时间` 按**运行机器的本地时区**解析（再归一化到 UTC 发给服务端）。CI（UTC）与本地（如 UTC+8）跑同一条命令，过滤边界会差几小时；要精确到某时区时显式写 ISO 8601 带偏移（如 `...+08:00` / `...Z`）。
+
+## Agent 规则
+
+- 寻址一律用 `--path`；用户只给文件名时先 `+file-list --name <名>` 定位，多个同名再让用户确认。
+- 上传 / 下载的本地路径用工作目录内相对路径；不在当前目录就 `cd` 过去或改相对路径。
+- 用户要「分享链接 / 临时下载地址」时用 `+file-sign`，把返回的链接转述给用户。
+- 删除前判断意图：已明确要删且授权时可直接带 `--yes`；不确定删哪些时先 `+file-list` 给用户确认。批量删除部分失败不报错，按逐项结果向用户说明哪些成功、哪些没删掉及原因。

package/skills/lark-apps/references/lark-apps-get.md

@@ -0,0 +1,43 @@
+# apps +get
+
+按 app_id 查询单个应用详情。运行时命令事实以 `lark-cli apps +get --help` 为准。
+
+## 何时用
+
+需要查看一个应用的类型、名称、描述、发布状态等详情时使用。如果只是按应用名模糊搜索定位 app_id，用 `+list --keyword`。
+
+## 命令骨架
+
+- 必填：`--app-id`。
+- 返回应用的完整信息：`app_id`、`app_type`、`name`、`description`、`icon_url`、`created_at`、`updated_at`、`is_published`。
+
+## 示例
+
+```bash
+lark-cli apps +get --app-id app_xxx
+lark-cli apps +get --app-id app_xxx --dry-run
+lark-cli apps +get --app-id app_xxx -q '.data.app.app_type'
+```
+
+## 输出契约
+
+- 成功读取 `data.app` 对象，包含以下字段：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `app_id` | string | 应用唯一标识 |
+| `app_type` | string | 应用类型（如 HTML、FULL_STACK、MODERN_HTML） |
+| `name` | string | 应用显示名称 |
+| `description` | string | 应用功能说明 |
+| `icon_url` | string | 应用图标 URL |
+| `created_at` | string | 创建时间（ISO 8601 UTC） |
+| `updated_at` | string | 最后更新时间（ISO 8601 UTC） |
+| `is_published` | boolean | 是否已发布 |
+
+- pretty 输出展示核心字段：`app_id`、`app_type`、`name`、`is_published`、`updated_at`。
+- `is_published=true` 只代表应用历史上有发布版本，不代表最新代码已部署。
+
+## Agent 规则
+
+- 用户已有 `app_id` 想查看详情时用 `+get`；只有应用名时用 `+list --keyword`。
+- 不要把 `cli_` 开头的飞书应用 ID 传给 `+get`，只接受 `app_` 开头的应用 ID。