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

package/miaoda/lark-apps-db/references/full-reference.md

@@ -0,0 +1,424 @@
+# lark-apps-db Reference
+
+本 reference 只承接 [`../SKILL.md`](../SKILL.md) 未展开的细节：`lark-cli apps +db-*` 各命令完整 flags、输出契约、错误处理、环境约定、时间格式、少见 PostgreSQL 限制、import/export 边界。DDL / SELECT / DML 的常用规则与沙箱约定（`$app_id`、鉴权、exit-10 审批）以 [`../SKILL.md`](../SKILL.md) 为准。运行时命令事实以 `lark-cli apps +<cmd> --help` 为准。
+
+## `+db-execute`（SQL 唯一执行通道）
+
+经妙搭服务端在应用数据库执行 SQL。不要从环境变量里取连接串裸连数据库；本地调试也走这个命令。
+
+### 命令骨架
+
+- 必填：`--app-id`（沙箱里用 `"$app_id"`），以及 `--sql` / `--file` 二选一（互斥）。
+- `--sql`：内联 SQL 文本；传 `-` 时从 stdin 读。绝对路径文件经 stdin 传入：`--sql - < <absolute-path>`（shell 解析路径，CLI 仅接收内容）。
+- `--file`：`.sql` 文件路径，需为工作目录内的相对路径（如 `--file ./migration.sql`）；绝对路径、或经 `..`/符号链接越出工作目录的路径会被拒绝。文件不在工作目录内时，改用 `--sql - < <文件路径>` 经 stdin 传入。
+- risk 是 `high-risk-write`（SQL 可含 DML/DDL）：任何执行都需 `--yes`，否则返回 `confirmation_required` / exit 10。`--dry-run` 预览不需要 `--yes`。
+- **不会自动包事务，事务边界需自己在 SQL 里控制**：多语句默认逐条独立提交，中间某条失败时前序语句已生效、不会回滚；若需要「要么全部成功、要么全部回滚」的原子性，在 SQL 内显式写 `BEGIN … COMMIT`。
+
+```bash
+lark-cli apps +db-execute --app-id "$app_id" --environment dev --sql "select * from orders limit 5" --yes
+lark-cli apps +db-execute --app-id "$app_id" --environment dev --file ./migration.sql --dry-run
+# 绝对路径文件 / cwd 不固定：经 stdin 传入
+lark-cli apps +db-execute --app-id "$app_id" --environment dev --sql - --yes < /path/to/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.」。据此决定整段重跑还是只跑剩余语句。
+
+### 执行规则
+
+- 该命令为 high-risk-write，执行一律需 `--yes`；无 `--yes` 会返回 `confirmation_required` / exit 10。
+  - **只读查询、以及不删除/不丢失既有数据且可撤回的语句**：已授权时可直接带 `--yes` 执行。
+  - **会删除或丢失既有数据、或难以撤回的语句**：先 `--dry-run` 预览（无需 `--yes`），向用户确认后再带 `--yes` 执行；不要在用户不知情时自动补 `--yes`。
+- 多语句失败时，失败前的语句可能已经 commit 落地。不要整批重跑；按错误 message/hint 修失败语句，并从剩余语句继续。
+- `+db-execute` 完全透传 SQL：平台不会自动补审计列、RLS、policy、COMMENT 或 trigger。
+
+## 表与结构
+
+**`+db-table-list`**：列出某环境的数据表。分页 `--page-size`（默认 20）/ `--page-token`（上一页 cursor）。每项给表名、描述、估算行数、大小、列数；要完整列定义 / 索引 / 约束用 `+db-table-get`。只知道业务对象名时，先用它定位可能的表名。
+
+**`+db-table-get`**：看单张表的结构，`--table` 必填。默认 JSON 给结构化的字段 / 索引 / 约束 / 估算行数 / 大小；`--format pretty` 直接输出建表 DDL 文本（给用户看建表语句或做迁移参照时用）。
+
+常规结构查询禁止用 `information_schema.columns` / `pg_indexes` 手写模拟。
+
+```bash
+lark-cli apps +db-table-list --app-id "$app_id" --environment dev --page-size 50
+lark-cli apps +db-table-get --app-id "$app_id" --table orders
+lark-cli apps +db-table-get --app-id "$app_id" --table orders --environment dev --format pretty
+```
+
+## 环境与通用约定
+
+- **环境 `--environment dev|online`（可省略）**：看表、看结构、数据导入导出、变更追溯、审计、配额都按环境区分。省略 `--environment` 时 CLI 不带该参数、由服务端按应用形态自动选分支——多环境应用走 `dev`、未开多环境的走 `online`；要固定环境才显式传。**唯一会报错的组合：对未开多环境的应用显式传 `--environment dev`（无 `dev` 分支）**。写操作建议先在 `dev` 验（仅多环境应用有 `dev`）。旧名 `--env` 已**移除**：传入会报 validation 错（提示改用 `--environment`），一律用 `--environment`。`+db-env-diff`/`+db-env-migrate` 是「dev→online 发布」语义、`+db-recovery-*` 作用于当前库，二者**没有** `--environment`。`+db-sync-*` 家族**不走自动选分支**：省略 `--environment` 默认落 online（详见下方「Base 数据同步」）。
+- **本地文件 / `--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`、`+db-execute`、`+db-sync-create`、`+db-sync-update`、`+db-sync-delete` 缺省会被确认关卡拦下（exit 10）；动手前先用对应的预览命令或 `--dry-run` 看清影响。`+db-sync-create --preview` 只解析/校验配置、不落库，免确认、不需 `--yes`；真正建任务（不带 `--preview`）才需要 `--yes`。
+- 全局 `--format json|pretty` 只控制**命令自身输出**（成功摘要 / 错误信封）的渲染，**不影响导出文件的格式**。
+- 服务端 SQL 错误码（如语法错误、表 / 列不存在、结果集超限、超时、命中禁用 SQL 等）经 typed `error` 的 `code` / `message` / `hint` 返回；`hint` 优先级高，先按 hint 修复再重试。
+
+## SQL 限制与服务端错误码
+
+| 约束 | 说明 |
+|---|---|
+| SELECT 1000 行硬上限 | 超过报错，无隐式截断；用 LIMIT、聚合或游标分页 |
+| 单语句 5000 行 / 1 MB 上限 | 超过需用 LIMIT、聚合或分批 |
+| 多语句不自动包事务 | 需要原子性显式 `BEGIN/COMMIT`；失败定位与前序落地情况见上方 `+db-execute` 输出契约 |
+| NULL 表达 | JSON 输出为原生 `null`；pretty / 管道输出为字面字符串 `NULL` |
+
+服务端错误码经 typed `error` 的 `code` 返回，`hint` 优先级高、先按 hint 修复再重试：
+
+| 错误码 | 触发场景 |
+|---|---|
+| `SYNTAX_ERROR` | SQL 语法错误 |
+| `TABLE_NOT_FOUND` | 表不存在 |
+| `COLUMN_NOT_FOUND` | 列不存在 |
+| `RESULT_SET_TOO_LARGE` | SELECT 超过 1000 行 |
+| `STATEMENT_TIMEOUT` | 服务端超时强制中断 |
+| `SQL_OPERATION_FORBIDDEN` | 命中平台禁用 SQL（见下文 Platform Forbidden SQL） |
+| `EXTENSION_NOT_WHITELISTED` | `CREATE EXTENSION` 不在白名单 |
+| `FILE_ALREADY_EXISTS` | 导出目标文件已存在；换一个不存在的 `--output` 路径重试（lark-cli 侧无 `--force` 覆盖选项） |
+| `IMPORT_TABLE_NOT_FOUND` | 导入目标表不存在 |
+| `IMPORT_COLUMN_MISMATCH` | CSV 表头 / JSON key 与表字段不匹配 |
+| `IMPORT_PK_CONFLICT` | 导入主键冲突，已回滚 |
+| `IMPORT_TYPE_MISMATCH` | 导入类型不匹配，已回滚 |
+| `IMPORT_FORMAT_UNSUPPORTED` | 文件扩展名非 `.csv` / `.json` |
+| `IMPORT_FILE_NOT_FOUND` | 本地导入文件不存在 |
+| `AUDIT_ALREADY_ENABLED` | 重复启用同一表 audit |
+| `AUDIT_NOT_ENABLED` | 未启用 audit 却 disable / list |
+| `INVALID_TIMESTAMP` | recovery 时间格式不合法 |
+
+## 数据导入导出
+
+**`+db-data-export`**：把一张表导出到本地文件。导出格式**只由 `--output` 的扩展名决定**——`.csv` / `.json` / `.sql`，缺省按 `<表名>.csv` 落在当前目录。`--output` 后缀必须是 `.csv/.json/.sql` 之一，否则报 validation 错误（exit 2），且不支持导出到 stdout。两道体量约束：
+
+- `--limit`（1..5000，默认 5000）是**行数上限守卫**：表的行数超过它会被整体拒掉（不是「只导前 N 行」）；
+- 导出产物 >1 MB 也会被拒。
+
+超大表别硬导：先用 `+db-execute` 加 `WHERE` / `LIMIT` 缩小范围、分批导。
+
+若命中「导出成功但文件静默 0 行」且表名 / 列名含非纯 ASCII 字符（中文表名、中文列名等）：workaround 是先把表 / 列 rename 成 ASCII，或改用 `+db-execute` 跑 `SELECT col AS ascii_alias ...` 取数后自行落盘。（该行为未实测，命中时再按此处理。）
+
+**`+db-data-import`（高危，需 `--yes`）**：把本地 csv/json 文件的数据导进表。文件需是 `.csv`/`.json`、≤1 MB。目标表缺省取文件名去掉**最后一个**扩展名（如 `orders.csv`→`orders`，`orders.2026.csv`→`orders.2026`）；文件名带点号时建议显式传 `--table` 以免落到意外的表名。
+
+**导入/导出限额**：体积 ≤ **1 MB**、行数 ≤ **5000**，导入导出都一样，超限会被拒。超限就分批——导入拆成 ≤1 MB / ≤5000 行的多个文件，导出用 `WHERE` / `LIMIT` 缩小范围。
+
+导入前置与值类型：目标表已存在；CSV 表头 / JSON 顶层 key 与表字段名完全一致；JSON 空值用 `null`、CSV 空值留空单元格；`INTEGER` / `BIGINT` 在 JSON 中建议写字符串或改 CSV，避免裸数字 / 科学计数被当浮点拒收；CSV 每行列数必须与表头一致，含逗号 / 换行 / 引号的字段用双引号包裹；主键 / 唯一键冲突会整批回滚，先导前 SELECT 查重或改用 SQL `ON CONFLICT`。来源是 Excel 或其它格式时，先转 CSV 再导。
+
+```bash
+lark-cli apps +db-data-export --app-id "$app_id" --table orders --output ./orders.csv
+lark-cli apps +db-data-export --app-id "$app_id" --table orders --output ./orders.json --environment dev
+lark-cli apps +db-data-import --app-id "$app_id" --table orders --file ./orders.csv --environment dev --yes
+```
+
+SQL 格式回放：导出的 `.sql` 产物用 `+db-execute --file ./file.sql --yes`（或 `--sql - < file.sql`），不要走 `+db-data-import`。
+
+## Base 数据同步（`+db-sync-*`）
+
+Base（多维表格）数据同步走 `+db-sync-*`，和本地文件导入不同：`+db-data-import` 只处理本地 `.csv/.json` 文件；Base 链接、Base 表、字段映射、持续同步任务都走 `+db-sync-create` / `+db-sync-update`。
+
+| 命令 | 用途 | 关键 flag |
+|---|---|---|
+| `+db-sync-create` | 预览或创建 Base 到应用数据库的同步任务（高危） | `--config`、`--preview`、`--output`、`--environment`、`--yes` |
+| `+db-sync-list` | 列出 Base 同步任务 | `--mode`、`--status`、`--table`、`--page-size`/`--page-token`、`--environment` |
+| `+db-sync-get` | 查看同步任务配置、状态、统计和 warnings | `--task-id` |
+| `+db-sync-enable` | 启用 streaming 同步任务 | `--task-id` |
+| `+db-sync-disable` | 停用 streaming 同步任务 | `--task-id` |
+| `+db-sync-update` | 修改 streaming 同步任务映射配置（高危） | `--task-id`、`--config`、`--environment`、`--yes` |
+| `+db-sync-delete` | 删除 streaming 同步任务，保留目标数据（高危） | `--task-id`、`--yes` |
+
+**任务类型**：
+
+- `mode=batch`：一次性任务。`schema_only=true` 只建目标表；`schema_only=false` 建表或写入已有表并导入当前 Base 数据。完成后不能 enable/disable/update/delete。
+- `mode=streaming`：持续同步任务。首次同步后持续处理 Base 变化，可 enable/disable/update/delete。
+
+**环境（重要）**：`+db-sync-*` 命令省略 `--environment` 时默认落 **online**（不同于 `+db-table-*`/`+db-audit-*` 等「多环境自动选 dev、单环境选 online」的规则——db-sync 家族不走自动选分支）。**多环境应用建表**（`target.table.action=create`）**必须显式 `--environment dev`**：不填或填 `online` 会被 online 分支的 DDL 禁令拒（`k_dl_4000001：forbid ddl/dcl operation in online env`），因为 online 分支产品上不允许直接建表，建表要落到 dev 分支。共享库 / 单环境应用只有 online、在 online 建表正常成功（不会报 `k_dl_4000001`），省略 `--environment` 或填 `online` 均可。
+
+**配置格式**：只通过 `--config` 传完整 JSON，支持内联 JSON、`@file`、`-` stdin。配置 key 使用复数：`field_maps`、`option_mappings`、`syncable_source_fields`。不要写单数 `field_map` / `option_mapping`，CLI 会直接报 validation 错。正式 create 时 `field_maps` **可省略或传空数组**：服务端会使用与 preview 相同的逻辑自动匹配字段并直接创建任务；若显式传了映射，则至少要有一项未写成 `"enabled": false`，写了却全部关闭会被 CLI 拒绝。`+db-sync-update` 仍要求至少一个启用的 `field_maps`，因为 update 的语义是修改既有映射。`target.table.action` 只能是 `create` 或 `use_existing`：建表时 `pg_field` 需要完整字段定义；写已有表时通常只需目标列名。`source.base_url`（源 Base 表完整 URL）在 `+db-sync-create` 必填、由服务端强制；`+db-sync-update` 可选——省略时服务端复用原任务的源 URL，仅在换源 / 替换成另一张 Base 表时才需要传新的 `base_url`。`source.table.name` 是要同步的 Base 表名。`base_url` 形如 `https://.../base/<token>?table=<tableId>`：`token` 定位 Base，`table=` 参数（tableId）定位表。填了 `source.table.name` 就以 name 为准——服务端用 `token + name` 反查 tableId（覆盖 url 里的 `table=` 参数）；不填才用 url 的 `table=` 参数定位。所以用户自然语言里说「同步 xxx 表」「把 xxx 表同步过去」时，一定要把「xxx」填进 `source.table.name`，不要只给 `base_url`——尤其当 `base_url` 不带 `table=` 参数（指向不带具体表的 Base）时，漏了 name 服务端无从定位表。
+
+**不知道要同步哪张表**：若 `base_url` 只有域名+token、不带 `?table=` 参数，又不确定表名，别硬猜。先用 `lark-cli base +table-list --base-token <token>` 列出该 Base 的所有表（`<token>` 就是 `base_url` 里 `/base/` 后面那段），把表名给用户选定，再填进 `source.table.name`（或改用带 `?table=<table_id>` 的完整 URL）。`+db-sync-create` 会在本地就拦下「`base_url` 无 `?table=` 且 `source.table.name` 空」的配置（提交前即报 validation 错，不送到服务端）。
+
+**单数 key 恢复**：如果用户说配置里 `field_map` 是单数、`option_mapping` 是单数、或字段映射可能不生效，不要把原配置直接提交。先找到用户这份同步配置，做这三步：
+
+1. 只把已知 key 改成复数：`field_map` -> `field_maps`，`option_mapping` -> `option_mappings`；不要发明 `fieldMappings` / `mapping` 之类字段名。
+2. 检查 `field_maps` 是数组，且至少有一项 `enabled` 缺省或为 `true`。如果全是 `"enabled": false`，先让用户确认要启用哪几项，再继续。
+3. 修好后先重新 preview，或复用最近一次 preview `--output` 产出的 `data.config`，再继续 create / update。
+
+```bash
+lark-cli apps +db-sync-create --app-id "$app_id" --environment dev --config @sync.json --preview --output ./resolved-sync.json
+lark-cli apps +db-sync-create --app-id "$app_id" --environment dev --config @resolved-sync.json --yes
+```
+
+如果本地找不到配置文件，不要只停在“请提供文件”。先说明恢复来源：让用户贴失败时传入的 JSON，或查找最近 preview 的 `--output` 文件；如果是已有任务的修改，先用 `+db-sync-get` 取回当前任务配置，再基于它修正后 update。
+
+**推荐流程（最佳实践，不是强制）**：优先先 preview，再让用户确认映射，最后用 preview 输出的完整 config 正式创建；这样最稳，也避免手写复杂 `field_maps`。若用户明确要求直接执行、不需要 preview，也可以在 create config 中省略 `field_maps`（或传空数组），由服务端自动匹配并直接创建任务；不要为了拿 mapping 强制用户先 preview。
+
+```bash
+lark-cli apps +db-sync-create \
+  --app-id "$app_id" \
+  --environment dev \
+  --config - \
+  --preview \
+  --output ./resolved-sync.json <<'JSON'
+{
+  "mode": "streaming",
+  "source": {
+    "type": "base",
+    "base_url": "https://example.feishu.cn/base/xxx",
+    "table": {"name": "客户"}
+  },
+  "target": {
+    "type": "postgresql",
+    "table": {"name": "customers", "action": "use_existing"}
+  }
+}
+JSON
+```
+
+preview 返回 `data.config`、`syncable_source_fields` 和 `summary`。`--output` 只把 `data.config` 写入文件，文件可直接作为正式输入：
+
+```bash
+lark-cli apps +db-sync-create --app-id "$app_id" --environment dev --config @resolved-sync.json --yes
+lark-cli apps +db-sync-get --app-id "$app_id" --task-id streaming_123
+```
+
+**多表 Base**：本命令一次只处理一张表。用户要同步整个 Base 时，先把计划说清楚：不是一个“整库同步任务”，而是按表拆成 N 个单表任务。每张表各有一份配置文件、一次 `+db-sync-create --preview`、一次用户确认后的 `+db-sync-create --yes`，并记录各自 `task_id`。配置也必须是单表粒度：每份 JSON 只有一个 `source.table` 和一个 `target.table`，字段名保持 `field_maps`、`option_mappings`、`syncable_source_fields` 这些复数 key。
+
+**修改 streaming 映射**：先用 get 导出当前配置，编辑 `field_maps` 后 update。update 是高危操作，必须经用户确认再加 `--yes`。
+
+`+db-sync-get` 返回的 `source` **不含 `base_url`**（只有 token / tableId，服务端没有 domain 拼不出完整 URL），这是正常的。原表 update 直接省略 `base_url` 即可；只有要换成另一张 Base 表时，才在 config 里显式补一个新的 `base_url`。不要为了"补全" `base_url` 而编造 domain 或拼接 URL——拿不到就省略，让服务端复用原任务的源 URL。
+
+`+db-sync-update` 也遵循 db-sync 家族「省略 `--environment` 落 online」的规则，所以改 dev 上的任务必须显式带该任务所在环境的 `--environment`（多环境应用的 streaming 任务通常在 `dev`），否则会错落 online、找不到任务或改错分支。
+
+```bash
+lark-cli apps +db-sync-get --app-id "$app_id" --task-id streaming_123 -q '.data | {mode, source, target, field_maps}' > sync.json
+lark-cli apps +db-sync-update --app-id "$app_id" --task-id streaming_123 --environment dev --config @sync.json --yes
+```
+
+**列表与生命周期**：
+
+```bash
+lark-cli apps +db-sync-list --app-id "$app_id" --mode streaming --table customers
+lark-cli apps +db-sync-disable --app-id "$app_id" --task-id streaming_123
+lark-cli apps +db-sync-enable --app-id "$app_id" --task-id streaming_123
+lark-cli apps +db-sync-delete --app-id "$app_id" --task-id streaming_123 --yes
+```
+
+`+db-sync-enable`、`+db-sync-disable`、`+db-sync-update`、`+db-sync-delete` 只适用于 `streaming_...` task。对 `batch_...` 执行这些操作会返回 failed-precondition。
+
+**batch 任务 operation-not-allowed 恢复**：用户说“批量任务重新启用”“导入历史订单表的任务重新 enable”“系统说操作不允许”时，先给生命周期结论：batch / import 类任务是一次性任务，完成或失败后不能重新启用，也不要反复调用 `+db-sync-enable`。下一步改为查状态和结果：
+
+```bash
+lark-cli apps +db-sync-get --app-id "$app_id" --task-id batch_123
+```
+
+把 `status`、`result`、`warnings` 和目标表写入情况告诉用户。若用户要的是后续持续同步，不是“重启这个 batch”，应新建 `mode=streaming` 任务：先 `+db-sync-create --preview` 给用户确认映射和影响，再带 `--yes` 创建；不要强行 enable 已完成的 batch 任务。
+
+**失败恢复**：看到 `warnings` 不要直接说同步成功。按 warning 或 error 的 `hint` 继续排查，恢复路径按任务 mode 分支：
+
+- **streaming 任务**：常见路径是 `+log-list --keyword <target_table>` / `+log-get` 查日志（见 lark-apps-ops skill 的 observability），然后用 `+db-execute` 修目标表结构，或用 `+db-sync-update`（带该任务所在环境的 `--environment`）修字段映射，最后对同一 `task_id` 再 `+db-sync-get` 复查。
+- **batch 任务**：batch 是一次性任务、**不能 update**（见上文生命周期）。修完目标表结构（`+db-execute`）后不要 update 原 batch，而是重新 `+db-sync-create --preview` 建新任务；只想看这个 batch 的结果就直接 `+db-sync-get`。
+
+**online 禁 DDL（`k_dl_4000001`）恢复**：`+db-sync-create` 建表报 `k_dl_4000001：forbid ddl/dcl operation in online env` 时，这必然是多环境应用（共享库在 online 建表不会报此码）。online 分支**本就不允许**直接建表，这是多环境应用的产品设计、不是可绕过的限制。改用 `--environment dev` 重跑 `+db-sync-create`，把表建到 dev 分支；不要试图「在 online 想办法重试建表」，没有这个选项。
+
+**缺 Base 表记录 ID 映射列（`400002477`）恢复**：streaming 自动同步要求目标表有一个映射给「Base 表记录 ID」的 **text + 单值 + unique** 列。用 `action=use_existing` 写已有表时，若该表没有这样的列，会报 `400002477`（Field mapping must include 'Base 表记录 ID'）。先用 `+db-execute` 给表加一个，如 `ALTER TABLE <表> ADD COLUMN base_record_id varchar UNIQUE`，再把它映射给「Base 表记录 ID」、重跑 `+db-sync-create --preview`。注意这是**加列**、不是建表，不需要审计列 / RLS 那套建表规范。
+
+## 变更追溯与审计
+
+**`+db-changelog-list`**：查表结构变更（DDL）历史——谁、什么时候、改了哪张表、做了什么（CREATE / ALTER / DROP TABLE、CREATE / DROP INDEX 等）。全应用默认开启，无需启用。可按 `--table` 过滤、按 `--change-id` 精确定位某条、用 `--since`/`--until` 圈时间区间，分页 `--page-size`/`--page-token`。禁止直接查询或模拟 `pg_audit`。
+
+**`+db-audit-status`**：看审计开关状态。给 `--table` 看单表，不给则列出所有已配置的表（开没开、保留期）。
+
+**`+db-audit-enable` / `+db-audit-disable`**：开 / 关某张表的行级变更审计。`--retention` 设保留期，取值 `7d`/`30d`/`180d`/`360d`/`forever`（默认 `7d`）。不要对已经开启审计的表重复 enable——不确定就先用 `+db-audit-status` 查。
+
+**`+db-audit-list`**：列出表的行级变更事件（INSERT/UPDATE/DELETE 的前后值与操作人）。`--table` 必填、可重复传多张表；`--since`/`--until` 圈时间。
+- **多表查询**：会先帮用户把不存在、或没开审计的表过滤掉再查，被过滤的表及原因列在结果的 `skipped` 里——据此告诉用户哪些表没纳入及为什么。
+- **单表查询**：不预过滤，表不存在 / 未开审计会直接报错（按 `error.hint` 转述给用户，引导先 `+db-audit-enable`）。
+
+```bash
+lark-cli apps +db-changelog-list --app-id "$app_id" --table orders --since 7d
+lark-cli apps +db-audit-enable --app-id "$app_id" --table orders --retention 30d
+lark-cli apps +db-audit-disable --app-id "$app_id" --table orders
+lark-cli apps +db-audit-list --app-id "$app_id" --table orders --since 24h
+lark-cli apps +db-audit-list --app-id "$app_id" --table orders --table users
+```
+
+## 多环境数据库（初始化 + 发布）
+
+**`+db-env-create`（高危，需 `--yes`）**：把存量单库应用初始化为 dev/online 两套库，不可逆。`--environment` 目前只支持 `dev`（默认 `dev`）；`--sync-data` 把现有 online 数据复制到新环境（不传则不复制）。新建的 full_stack 应用通常已自带多环境，重复初始化会返回冲突错误（应用已是多环境）——按 `error.hint` 转述状态即可，别重复初始化。
+
+**`+db-env-diff`**：预览开发环境里待发布到线上的表结构变更，不落地。发布前先看这个。无待发布变更时明确返回「无变更」。
+
+**`+db-env-migrate`（高危，需 `--yes`）**：把开发环境的结构变更正式发布到线上，不可逆，返回实际发布的变更条数。发布是异步的，命令会等到完成再返回结果。只发布 DDL；数据变更需自行同步。
+
+> 预览与发布同一端点，故 `+db-env-diff` 也需写 scope（不是纯只读权限）。
+
+**发布审批拦截**：若应用的发布配置了审批，`+db-env-migrate` 会被服务端拒绝（`feature_not_available`，exit 1）。这**不是**参数问题：换 flag、重试都不会成功，也不要去跑 `+db-env-create`。改走应用发布（见 lark-apps-ops 的发布链路）：先向用户确认发布理由，再执行 `lark-cli apps +release-create --app-id "$app_id" --apply-reason "<已向用户确认的发布理由>"`；也可以让用户在页面上发布。只有真发布被拦，`+db-env-diff` 预览照常可用。
+
+```bash
+lark-cli apps +db-env-create --app-id "$app_id" --environment dev --dry-run
+lark-cli apps +db-env-create --app-id "$app_id" --environment dev --sync-data --yes
+lark-cli apps +db-env-diff --app-id "$app_id"
+lark-cli apps +db-env-migrate --app-id "$app_id" --yes
+```
+
+## 时间点恢复（PITR）
+
+**`+db-recovery-diff`**：预览把库恢复到 `--target` 时间点会带来哪些变更（受影响的表、行数、预计耗时），不落地。同样需写 scope。
+
+**`+db-recovery-apply`（高危，需 `--yes`）**：把库恢复到某个时间点，**会覆盖当前数据**，不可逆。
+
+- 可恢复窗口最长 **7 天**，且不早于**最近一次 `+db-env-migrate`**；超出窗口的目标会被拒。
+- 目标时间点与当前库一致时返回 `no_changes`（空操作），不算失败。
+- 动手前务必先 `+db-recovery-diff` 给用户确认。
+
+```bash
+lark-cli apps +db-recovery-diff --app-id "$app_id" --target 2h
+lark-cli apps +db-recovery-apply --app-id "$app_id" --target 2026-04-15T10:00:00Z --yes
+```
+
+## 配额
+
+**`+db-quota-get`**：查数据库存储用量（已用量、表数、视图数；配额接入后还会给总配额与使用率）。
+
+```bash
+lark-cli apps +db-quota-get --app-id "$app_id" --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 恢复）尤其建议带时区，避免恢复到非预期时间点。
+
+## 授权细节
+
+以下操作前必须向用户展示影响范围并取得明确授权（exit-10 审批流程见 [`../SKILL.md`](../SKILL.md) 沙箱约定）：
+
+| 场景 | 触发条件 | 展示内容 |
+|---|---|---|
+| 表结构变更 | CREATE / ALTER / DROP TABLE / INDEX / COLUMN | 目标对象、变更内容；DROP 说明数据风险 |
+| 数据删除 | DELETE / TRUNCATE | 目标表、WHERE 条件、`SELECT count(*)` 命中行数 |
+| 多环境初始化 | `+db-env-create` | 不可逆、会创建 dev 分支，可选 `--sync-data` 复制数据 |
+| dev -> online 发布 | `+db-env-migrate` | 先展示 `+db-env-diff` 输出，说明影响 online |
+| PITR 恢复 | `+db-recovery-apply` | 先展示 `+db-recovery-diff`，说明恢复点之后变更会被覆盖丢失 |
+| Base 同步任务创建 / 改映射 / 删除 | `+db-sync-create` / `+db-sync-update` / `+db-sync-delete` | 先 `+db-sync-create --preview`（或 `+db-sync-get` 取当前配置）展示源表、目标表与字段映射；delete 说明任务会删、目标表数据保留 |
+
+`--yes` 只跳过 CLI 确认关卡，不代替授权。
+
+## Platform Forbidden SQL
+
+命中会被服务端拒绝并经 typed `error` 返回。
+
+| 类别 | 禁止 SQL |
+|---|---|
+| 数据库级 | `CREATE / DROP / ALTER DATABASE` |
+| Schema 级 | `CREATE / DROP SCHEMA` |
+| 用户级 | `CREATE / DROP USER` |
+| 角色级 | `CREATE / DROP / ALTER ROLE` |
+| Owner 切换 | `REASSIGN OWNED` / `DROP OWNED` |
+| Extension | 仅白名单内允许，如 `pg_trgm`、`pgcrypto` |
+
+业务红线：禁止操作平台保留表如 `auth`、`users`；禁止 DROP 平台审计列；业务创建人 / 负责人字段命名为 `creator` / `owner` / `author`，避免混淆审计列。
+
+## PostgreSQL Edge Cases
+
+| 场景 | 规则 |
+|---|---|
+| 系统表白名单 | 只允许 `information_schema.tables/columns/table_constraints/key_column_usage/views/sequences/schemata`、`pg_indexes`、`pg_description` |
+| 系统表禁用 | 禁止 `pg_tables`、`pg_policies`、`pg_type`、`pg_class`、`pg_attribute`、`pg_catalog.*` |
+| DISTINCT + window functions | 分两层查询，先 DISTINCT 再窗口函数 |
+| 日期相减 | 两个 DATE 相减直接返回天数整数 |
+| 内联 COMMENT | 禁止 `column TEXT COMMENT 'xx'`，使用独立 `COMMENT ON` |
+| CREATE TYPE | 不支持 `IF NOT EXISTS` |
+| CREATE POLICY | 不支持 `IF NOT EXISTS` |
+| ALTER TABLE ADD CONSTRAINT | 不支持 `IF NOT EXISTS` |
+
+### JSONB comments
+
+JSONB 字段必须用 `COMMENT ON COLUMN ... IS '@type { ... }'` 声明 TypeScript 类型；CREATE TABLE 和 COMMENT 应放在同一次 DDL 调用中。
+
+```sql
+COMMENT ON COLUMN orders.items IS '@type { items: Array<{ sku: string }> }';
+COMMENT ON COLUMN orders.metadata IS '@type { source: string } @description 订单来源';
+COMMENT ON COLUMN product.payload IS '@type { key: string }';
+```
+
+当 `@type` 里含图片语义字段（`image` / `cover_url` / `avatar` / `gallery` / `images` / `photos`）时，mock 写入规则同普通图片列：先找语义匹配图片，再调用 `generate_image`，不能直接写 Picsum。
+
+### `user_profile` compound type
+
+平台内置：`(user_id varchar, name varchar, email varchar, avatar text, status integer)`，无需创建。仅允许业务 SQL 访问 `(field).user_id`；不要依赖 name / email / avatar / status。
+
+```sql
+INSERT INTO teacher (teacher_profile, class_id)
+VALUES (ROW('1847292986161210')::user_profile, gen_random_uuid());
+
+SELECT (teacher_profile).user_id AS teacher_profile, class_id
+FROM teacher;
+
+UPDATE teacher
+SET teacher_profile = ROW('1847292357012580')::user_profile
+WHERE (teacher_profile).user_id = '1847292986161210';
+
+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));
+```
+
+表达式唯一性必须用 `CREATE UNIQUE INDEX`；`ALTER TABLE ... ADD CONSTRAINT ... UNIQUE` 不支持 `(field).user_id` 这类表达式列。
+
+### pg function constraints
+
+创建函数时：函数体内禁止 DDL；`RETURNS trigger` 必须 `LANGUAGE plpgsql`。
+
+```sql
+CREATE OR REPLACE FUNCTION fn_set_updated_at()
+RETURNS trigger
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  NEW.title := trim(NEW.title);
+  RETURN NEW;
+END;
+$$;
+```
+
+## Mock Data Details
+
+| 中文用户 user_id | name | 英文用户 user_id | name |
+|---|---|---|---|
+| 1847292357012580 | 张伟 | 1846114399229988 | John Smith |
+| 1847292986161210 | 李明 | 1847298549409911 | Emma Johnson |
+| 1838411738368010 | 刘洋 | 1847291727560708 | Michael Brown |
+| 1847292458018820 | 赵丽 | 1848568929333380 | Robert Wilson |
+| 1847286122258458 | 孙强 | 1847751107397639 | Maria Garcia |
+
+图片 URL 决策：优先用户上传的语义匹配图片；其次历史消息中语义匹配图片；否则调用 `generate_image`。prompt 必须与数据语义匹配；禁止使用品牌名、角色名、真实人物等版权内容。只有生成失败才用 Picsum，且必须带 seed：`https://picsum.photos/seed/${seed}/400/300`；不能先写 Picsum 再声称已经生成图片。
+
+JSONB 图片字段同样适用：只要 `@type` 中包含 `image` / `cover_url` / `avatar` / `gallery` / `images` / `photos` 等图片地址语义，就不能跳过 `generate_image`。
+
+## `schema.ts` 生成与刷新（`npm run gen:db-schema`）
+
+`server/database/schema.ts` 是 DB 元数据生成产物，只能只读辅助确认结构，禁止手改。唯一的刷新方式是在应用工程根目录执行工程自带的 npm script：
+
+```bash
+npm run gen:db-schema
+```
+
+该 script 反查 DB 元数据重写 `schema.ts`（当前模板背后是 `@lark-apaas/db-schema-sync`，早期应用是 `fullstack-cli gen-db-schema`）。**认这个 script 名，不要自己去调背后的包或猜别的命令。**
+
+`lark-cli apps +db-execute` **只执行 SQL，不碰工程文件**：DDL 成功后不会自动刷新 `schema.ts`。每次 DDL（含分批执行的每一批）成功后都要立即手动跑一次，再写引用新表 / 新列的 TS 代码，否则类型检查会报找不到表 / 列。
+
+| 现象 | 处理 |
+|---|---|
+| DB 结构、默认值、类型或约束不对 | 改 DDL 后重跑 `npm run gen:db-schema`，让 `schema.ts` 跟随真源刷新 |
+| `schema.ts` 缺新建的表 / 列 | DDL 后漏跑了 `npm run gen:db-schema`，补跑一次 |
+| DB 正确但 `schema.ts` 展示错误 | 视为 schema 生成器渲染 bug；不要手改产物，说明平台侧需修复 |

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

@@ -0,0 +1,216 @@
+---
+name: lark-apps-file
+description: "Use when 在妙搭沙箱里用 `lark-cli apps +file-*` 管理【当前这个已存在的】妙搭应用的文件存储：一次性上传、下载、列出、删除、清理或查看文件，获取文件下载链接、临时分享链接，或查存储用量。触发词：文件上传, 文件下载, 文件列表, 文件删除, 文件清理, 文件查看, 文件元数据, 下载链接, 临时分享链接, 应用文件存储, 文件存储用量, +file-, file-upload, file-download, file-sign."
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli apps --help; lark-cli apps +file-list --help（各 +file-* 子命令同理）"
+control-by-feature-ab: true
+# AppInit 只做需求理解与概要设计，不上传/下载应用文件；且「文件下载」这类触发词
+# 会和「读取飞书云文档 / 云空间资源」的意图混淆。
+unavailable-agents:
+  - AppInit
+---
+
+# lark-apps-file
+
+使用 `lark-cli apps +file-*` 处理应用存储里的文件型一次性操作，如上传、下载、查看元数据或生成临时分享链接。
+
+## 沙箱约定（先读）
+
+- **命令名**：一律 `lark-cli apps +file-*`；命令/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）
+
+`+file-delete` 是 `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` 静默重试。
+
+## 何时使用
+
+### 匹配场景
+
+- 用户要对应用存储里的文件做一次性操作：列出、查找、上传、下载、删除、查看元数据
+- 用户要拿文件链接：应用内可用的下载地址，或对外分享、可过期的临时下载链接
+- 用户要在 CI、脚本、一次性运维里处理测试文件、初始化测试数据或清理文件
+- 用户要查应用的文件存储用量
+
+### 不匹配场景
+
+- 目标是实现前端页面里的文件上传/删除/取链接能力：用 `client-builtins-file-storage-service`
+- 目标是实现 NestJS controller / service 里的文件处理能力：用 `server-builtins-file-storage-service`
+- 输入来自当前会话附件，且还没确认真实本地路径：先用 `attachment`
+- 目标是浏览器里的在线预览体验：用 `file-preview`
+- 用户要操作工作区或代码仓库里的本地文件（如源代码、构建产物、`.env`），不是应用存储里的文件
+- 数据库里的表数据：用 `lark-apps-db` 的 `+db-*`
+
+## 按目标选择工具
+
+| 目标 | 用什么 | 原因 |
+|---|---|---|
+| 当前会话附件继续上传到应用存储 | 先用 `attachment` 找真实本地路径，再 `+file-upload` | `+file-upload` 只接收本地路径，不直接处理附件引用 |
+| 实现前端页面里的上传/删除/取链接能力 | `client-builtins-file-storage-service` | 这是前端页面功能开发，产出物是 `.tsx` / 页面逻辑，不是一次性 CLI 操作 |
+| 实现服务端 controller / service 里的文件处理能力 | `server-builtins-file-storage-service` | 这是 NestJS 代码开发，不是一次性 CLI 调试 |
+| 做 PDF / Word / Excel / PPT 在线预览 | `file-preview` | 目标是预览体验，不是文件运维 |
+
+## 关键概念
+
+### 文档中的路径写法
+
+- 本文把应用存储里的对象统一写成以 `/` 开头的远端路径，例如 `/1858537546760216.png`
+- 本地文件统一写成 `./logo.png` 这类**工作目录内的相对路径**；路径在别处时先 `cd` 过去或改成相对路径
+- 如果命令行为与本文示例不一致，以 `lark-cli apps +file-list --help` 或对应子命令的 `--help` 为准
+
+### 远端寻址：`--path` 精确匹配
+
+远端文件统一用 `--path` 精确寻址（带前导 `/`）。规则：
+
+- 只知道文件名时，先 `+file-list --name <名>` 定位拿到 `path`，再做后续操作；多个同名文件让用户确认
+- `+file-list --path` 是精确匹配，不是目录前缀匹配
+- 后续要稳定引用具体文件时，优先保留 `path`
+
+### 上传的路径与文件名规则
+
+- 上传只接收本地 `--file`：文件名沿用本地文件名，远端路径由平台分配、全局唯一（无需也无法手填）
+- 特殊字符做 URL 编码透传；以 `.` 开头的隐藏文件名会加 `_` 前缀，避免下载回本地时覆盖隐藏文件
+
+### 应用内下载地址 vs 临时分享链接 `signed_url`
+
+| 类型 | 公网可直接访问 | 有效期 | 适用场景 | 推荐获取方式 |
+|---|---|---|---|---|
+| 下载地址 | 否 | 不过期 | 应用内使用文件、写入业务字段、前端或后端后续消费 | 上传响应的 JSON 输出；文件已在应用存储里就用 `+file-get` 的 JSON 输出（如有） |
+| `signed_url` | 是 | 会过期，`--expires-in` 秒数，默认 1 天，最长 30 天 | 对外分享、浏览器直接打开、需要过期时间 | `+file-sign` |
+
+规则：
+
+- 不要依赖 `+file-list` 的 pretty 表格获取下载地址；上传者、下载地址（如有）仅在 JSON 输出里，单文件详情用 `+file-get`
+- 只是应用内使用文件时，不要无故生成 `signed_url`
+- `+file-sign` 的 pretty 模式只输出链接本身，便于复制 / 管道；要把到期时间一并告诉用户时用默认 JSON 输出
+
+### file 域无环境概念
+
+file 域不区分环境，没有 `--environment` / `--env`。
+
+## 命令速查
+
+这里只列高频、默认安全路径；完整参数以 `--help` 为准。
+
+| 场景 | 命令 |
+|---|---|
+| 先看总帮助 | `lark-cli apps --help` |
+| 某个子命令用法不确定 | `lark-cli apps +file-list --help`（各子命令同理） |
+| 列出文件 | `lark-cli apps +file-list --app-id "$app_id"` |
+| 按文件名精确查找 | `lark-cli apps +file-list --app-id "$app_id" --name logo.png` |
+| 按 path / 文件名 / MIME / 大小 / 上传时间过滤 | `lark-cli apps +file-list --app-id "$app_id" --path/--name/--type/--size-gt/--uploaded-since ...` |
+| 查看单文件元数据 | `lark-cli apps +file-get --app-id "$app_id" --path /1858537546760216.png` |
+| 上传本地文件到应用存储 | `lark-cli apps +file-upload --app-id "$app_id" --file ./local.png` |
+| 下载远程文件到本地 | `lark-cli apps +file-download --app-id "$app_id" --path /1858537546760216.png --output ./logo.png` |
+| 删除前确认单文件范围 | `lark-cli apps +file-get --app-id "$app_id" --path <path>` |
+| 删除前确认批量范围 | `lark-cli apps +file-list --app-id "$app_id" <过滤器>` |
+| 执行删除（已确认影响范围后） | `lark-cli apps +file-delete --app-id "$app_id" --path <path1> --path <path2> --yes` |
+| 生成临时分享链接 | `lark-cli apps +file-sign --app-id "$app_id" --path <path> --expires-in 604800` |
+| 查文件存储用量 | `lark-cli apps +file-quota-get --app-id "$app_id"` |
+
+`+file-list` 分页：`--page-size`（默认 20）/ `--page-token`；pretty 表格每项给名称、路径、大小、类型、上传时间 5 列。
+
+## 多步工作流
+
+### 1. 当前会话附件上传到应用存储
+
+- 先用 `attachment` 确认当前会话附件的真实本地路径
+- 再把该本地路径作为 `--file` 上传到应用存储
+
+```bash
+lark-cli apps +file-upload --app-id "$app_id" --file ./logo.png
+```
+
+### 2. 上传后立即拿下载地址
+
+```bash
+lark-cli apps +file-upload --app-id "$app_id" --file ./logo.png
+```
+
+- 从返回结果里读取平台分配的远端 `path` 和应用内下载地址
+- 需要把文件链接写入业务字段、后续代码或测试数据时，优先直接用这次上传响应，不要再额外跑一次 `+file-list`
+
+### 3. 已知文件名，先查 `path` 再下载
+
+```bash
+# 先查 path
+lark-cli apps +file-list --app-id "$app_id" --name logo.png
+# 再下载
+lark-cli apps +file-download --app-id "$app_id" --path /1858537546760216.png --output ./logo.png
+```
+
+### 4. 批量清理文件
+
+```bash
+# 先用过滤器看命中（分页翻完）
+lark-cli apps +file-list --app-id "$app_id" --uploaded-until 2026-03-01 --page-size 100
+```
+
+可替换的范围过滤器：
+
+- `--type image/png`
+- `--size-gt <字节>` / `--size-lt <字节>`
+- `--uploaded-since 2026-04-01`
+- `--uploaded-until 2026-03-01`
+
+- 先把命中总数、样本文件、过滤条件展示给用户，并明确说明这是不可逆删除
+- 在拿到明确授权前，不要继续执行 `+file-delete`
+
+获得明确授权后，再分批删除（`--path` 可重复传多个）：
+
+```bash
+lark-cli apps +file-delete --app-id "$app_id" --path /a.png --path /b.png --yes
+```
+
+用法不确定或命令报错时，先看 `lark-cli apps --help` 或对应子命令的 `--help`。
+
+## 时间格式（`--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`）。
+
+## 安全规则
+
+### 删除前必须确认影响范围
+
+`+file-delete` 是不可逆操作。对来源不明或可能是生产数据的文件，先展示影响范围，再删除。
+
+建议流程：
+
+1. 先用 `+file-list` 或 `+file-get` 拿到待删清单、总数、总大小
+2. 向用户展示影响范围，并暂停等待明确授权；没有授权前不要继续执行 `+file-delete`
+3. 如果当前 agent 提供 `ask_user_question` 一类确认工具，优先用工具；没有时直接在对话中确认
+4. 授权后再带 `--yes` 执行删除
+
+### 批量删除要先报数
+
+`--type`、`--size-gt`、`--uploaded-since` 一类范围过滤器容易扩大命中范围。删除前至少先跑一次 `+file-list` 确认命中数量；命中为 `0` 时不要继续执行删除。
+
+### `+file-delete` 是逐项 best-effort
+
+- 逐项返回结果：部分文件删除失败（如某个路径不存在）不影响其余文件，整体仍算成功
+- 失败项在结果里单独标出原因，按逐项结果向用户说明哪些成功、哪些没删掉及原因
+
+## 关键限制
+
+- 单文件上传上限：`100 MB`
+- `+file-sign --expires-in` 上限：30 天（默认 1 天）
+- `+file-delete` 不带 `--yes` 会被确认关卡拦下（exit 10）
+- 本地文件 / 输出路径限工作目录内相对路径