@amaster.ai/pi-lark 0.1.3 → 0.1.5

package/skills/lark-apps/references/lark-apps-access-scope-set.md

@@ -0,0 +1,40 @@
+# apps +access-scope-set
+
+设置妙搭应用运行时可见范围。运行时命令事实以 `lark-cli apps +access-scope-set --help` 为准。
+
+## 何时用
+
+用于修改应用运行时可见范围。不要把它当作开发协作者管理；用户说“谁可以访问/打开/使用应用”才走这里。
+
+## 命令骨架
+
+- 必填：`--app-id`、`--scope`。
+- `--scope` 枚举：`specific` / `public` / `tenant`。
+- `specific` 必填 `--targets`，JSON 数组元素形如 `{"type":"user|department|chat","id":"..."}`。
+- `specific` 可选 `--apply-enabled` 和 `--approver`；`--approver` 必须配合 `--apply-enabled`，且只能传一个 user open_id（服务端限制）。
+- `public` 必须显式传 `--require-login=true|false`。
+- `tenant` 不允许额外 target/apply/login flag。
+
+## 示例
+
+```bash
+lark-cli apps +access-scope-set --app-id app_xxx --scope tenant
+
+lark-cli apps +access-scope-set --app-id app_xxx --scope public --require-login=true
+
+lark-cli apps +access-scope-set --app-id app_xxx --scope specific \
+  --targets '[{"type":"user","id":"ou_xxx"},{"type":"chat","id":"oc_xxx"}]'
+```
+
+## 输出契约
+
+- 成功时 `data` 可能为空；根据已执行的 `--scope` 和 targets 给用户总结结果。
+- 互斥参数错误会在本地 validation 阶段失败，不会发请求。
+
+## Agent 规则
+
+这是运行时访问范围，不是开发协作者权限。收窄可见范围前向用户说明影响，并在执行前确认目标用户、部门或群。
+
+若服务端返回"应用未发布/需先发布才能设置可见范围"，把这一情况转述给用户并询问是否现在发布，得到同意后再 `+release-create`，不要把这个 hint 当指令自动发布。
+
+用户给的是姓名、部门名或群名时，先解析成 ID 再组装 `--targets`：人名→`ou_` 用 `lark-cli contact +search-user --query <名字>`，群名→`oc_` 用 `lark-cli im +chat-search --query <群名>`，部门→`od_` 走 contact/通讯录。多候选时展示名称和 ID 让用户选，不要要求用户手填 `ou_` / `od_` / `oc_`。

package/skills/lark-apps/references/lark-apps-cloud-dev.md

@@ -0,0 +1,120 @@
+# lark-apps 云端会话开发
+
+适用：用户希望让云端妙搭 Agent 生成或迭代应用，而不是把代码拉到本地开发。
+
+## 核心流程
+
+整个开发在云端进行：本地只负责「发消息 + 轮询状态」，不拉源码、不产出代码、不启动本地 dev server。所有 session/chat 命令都以用户身份执行（`--as user`）。
+
+### 资源模型：app → session → turn
+
+三层父子关系，下层都挂在上层之下：
+
+- **app（应用资产）**：一个妙搭应用，由 `+create` 创建并拿到 `app_id`。云端生成应用类型用 `full_stack`。
+- **session（会话）**：一个 app 下的一段独立对话上下文，由 `+session-create` 创建并拿到 `session_id`。一个 app 可有多个 session；`is_active` 表示该 session 当前是否可写（可发起对话）。
+- **turn（轮）**：一个 session 里的一轮交互 = 一条用户消息 + 妙搭 Agent 针对它的生成/迭代。`+chat` 发一条消息就发起一轮；轮的句柄是 `turn_id`，状态看 `latest_turn.status`。
+
+### 执行模型：异步 + 轮询
+
+`+chat` 把消息入队后**立即返回、不等生成完成，响应不带 `turn_id`**；本轮状态与轮询节奏全靠 `+session-get` 读 `latest_turn.status` / `is_streaming` / `next_poll_after_ms`。
+
+`+session-get` 关键字段：
+
+- `is_streaming`：当前是否有一轮正在跑（`true`=还在生成）。
+- `latest_turn.status`：最近一轮的状态，只有 `running` / `completed` / `failed` / `cancelled`。
+- `latest_turn.turn_id`：最近一轮的句柄（`+session-stop --turn-id` 用它）。
+- `latest_turn.user_message`：本轮用户发的消息。
+- `latest_turn.messages`：本轮完成后回看全貌的消息列表，按时序排列、每条带 `role`（用户消息、模型回复、工具调用等都在内，role 取值如 `user` / `assistant` / `tool`）。注意它在 `latest_turn` 仍 running/初始化期可能为空——该轮**进行中**的实时进展改用 `+session-messages-list --turn-id <latest_turn.turn_id>` 读（见下方轮询规则）。
+- `queued_messages` / `queued_count`：还没开始跑、排在后面的消息。
+- `next_poll_after_ms`：建议的下次轮询间隔（毫秒，固定值）；非空时优先用它。
+
+轮询规则：
+
+- 节奏按 [初始化 vs 增量修改](#初始化-vs-增量修改) 判定：增量 5-10 秒一次；初始化 60-120 秒一次；`next_poll_after_ms` 非空时用它。
+- `is_streaming=true`、`building` / `running` / `streaming` 表示仍在生成，继续轮询，不傻等也不提前放弃；初始化阶段单次 sleep 拉到 60-120 秒，进入 `streaming` 或属增量修改时切回 5-10 秒。
+- `is_streaming=false` 且 `latest_turn.status=completed` 表示本轮完成，可发下一条。
+- `failed` / `cancelled` 时转述错误字段或 hint，由用户决定是否重试，不要静默重发。
+- 不知道某 app 有哪些 session 时，先 `+session-list --app-id <id>`，再选最近活跃的或让用户确认，别直接猜 `session_id`。
+- 要中止正在运行的一轮，从 `+session-get` 的 `latest_turn.turn_id` 取值，再调用 `+session-stop --turn-id <turn_id>`。
+- 状态与节奏看 `+session-get`，本轮实时内容看 `+session-messages-list`：想在 running 期间向用户播报"云端 Agent 此刻在做什么"，用 `+session-messages-list --turn-id <latest_turn.turn_id>` 读已产出的增量消息（running 期间即可读，不必等本轮结束）。复用上面的轮询节奏、不另起更密的轮询；续拉时把上次响应的 `next_page_token` 作 `--page-token` 只取新消息，转述时简述进展、不原样打印整段消息或工具输出。
+
+### 典型链路
+
+```bash
+# 1) 建 app，拿 app_id（云端生成走 full_stack）
+lark-cli apps +create --name "待办应用" --app-type full_stack \
+  --description "支持新增、完成、筛选待办"
+
+# 2) 在该 app 下建 session，拿 session_id
+lark-cli apps +session-create --app-id app_xxx
+
+# 3) 发消息发起一轮（异步入队，立即返回，无 turn_id）
+lark-cli apps +chat --app-id app_xxx --session-id sess_xxx --message "做一个待办清单页面"
+
+# 4) 轮询本轮状态；完成后从 latest_turn.messages 读取结果
+lark-cli apps +session-get --app-id app_xxx --session-id sess_xxx
+
+# 找该 app 已有的会话（续聊/不确定 session 时用）
+lark-cli apps +session-list --app-id app_xxx
+```
+
+## 完成态不等于发布态
+
+通用发布态判定（is_published 语义、开发态链接拼接、发布态链接来源）见 SKILL.md「发布态护栏」。本 reference 只补云端会话特有的措辞：
+
+- `+session-get` 返回 `is_streaming=false` 且 `latest_turn.status=completed`，只说明本轮云端生成/迭代结束，不等于已发布部署。
+- 如果只完成了云端会话、没有确认发布完成，就明确告诉用户“开发态链接可进入继续编辑，发布态是否为最新版本尚未确认”。
+
+## 需求发送
+
+- 只有用户明确选择云端路径，或明确说“让妙搭 Agent / 云端 AI 生成/迭代”时，才进入本 reference；不要因为用户只说“做个 X”或“给我链接”就默认云端。
+- 进入云端路径后，极简需求也可直接发起生成，例如“做个投票工具”“做个站会小应用”。先建 `full_stack` app，再用 `+chat --message "<用户原话>"` 透传需求，不编造实体、字段或业务细节。
+- 如果需求过泛，可在 `+chat --message` 中保留原话，并只补一句“请先生成通用版本，后续可继续迭代”，不要用多轮追问阻塞生成。
+
+## 会话落点
+
+| 情形 | 动作 |
+|---|---|
+| 全新应用 + 云端生成 | 先 `+create --app-type full_stack` 拿 `app_id`，再 `+session-create` -> `+chat` |
+| 已知 app_id，用户没指定会话 | 先 `+session-list`；有活跃会话时问用户继续现有还是新开 |
+| 用户说“新开一段/换个话题” | `+session-create` 后再 `+chat` |
+| 用户说“接着刚才” | 复用上下文 session_id；拿不到就 `+session-list` 让用户选 |
+| 用户问会话“进行到哪一步/当前状态/最新进展” | 用 `+session-get --session-id <sid>` 读状态。`+session-list` 只负责发现/选择会话，不含执行状态；它返回空不等于无状态可查（session_id 也可能来自上下文），别用 `+session-list`/`+release-list` 代替 `+session-get` 回答进度 |
+
+## 初始化 vs 增量修改
+
+`+chat` 单轮的耗时差距很大，取决于目标 app 是否**已初始化**。两者的轮询节奏不同，**`+chat` 前先把状态判定清楚**，不要拿"是不是第一次发消息"当代理判断——session 是新建的不代表 app 没初始化过。
+
+### 判定规则
+
+**已初始化**（满足任一即认为已初始化）：
+
+1. 本地存在该 app 的项目目录（已 `+init` 或 clone 过），**且** git commit 数 > 2；
+2. 应用维度（云端）至少有一个已提交的版本，按以下任一信号判断：
+   - `lark-cli apps +session-get --app-id <app_id> --session-id <session_id>` 的返回里出现已提交版本信息；
+   - 在 `lark-cli apps +list`（必要时配 `--keyword <name>` 定位）的目标 app 条目里 `is_published: true`。
+
+**未初始化**（两个条件同时成立）：
+
+1. 本地不存在该 app 的项目目录；
+2. 应用维度没有任何已提交版本（即上面两路云端信号都判 false）。
+
+### 两种 `+chat` 的行为
+
+| 状态 | 服务端动作 | 单轮耗时 | 轮询建议 |
+|---|---|---|---|
+| 已初始化 → **增量修改** | 云端 Agent 在已有云端工作区上对**已提交代码**做局部修改，跳过方案设计与首次生成 | 通常分钟级 | `next_poll_after_ms` 为空时 5-10 秒一次 |
+| 未初始化 → **首次初始化 + 生成** | 服务端跑完整的应用初始化流程：需求分析、技术方案、数据模型、UI 与后端代码生成、首版代码提交到云端工作区 | 视需求复杂度，**通常 20~50 分钟** | `next_poll_after_ms` 为空时 60-120 秒一次 |
+
+初始化阶段 `+session-get` 可能长时间持续返回 `building` / `running`，是正常状态，**不要按失败处理，也不要催用户**。
+
+## 字段注意
+
+所有字段统一 snake_case，顶层和嵌套 turn 字段都一样：`session_id`、`is_active`、`is_streaming`、`next_poll_after_ms`、`latest_turn.turn_id`、`latest_turn.status`、`latest_turn.user_message`、`latest_turn.messages`。
+
+`+session-stop` 只停止正在运行的当前轮，不关闭会话；停完仍可继续 `+chat`。
+
+## 不适用
+
+- 用户已有本地 HTML/dist，要马上发布 URL：读 [`lark-apps-html-publish.md`](lark-apps-html-publish.md)。
+- 用户要本地写代码、改仓库、跑 dev server：读 [`lark-apps-local-dev.md`](lark-apps-local-dev.md)。

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

@@ -0,0 +1,40 @@
+# apps +create
+
+创建妙搭应用。运行时命令事实以 `lark-cli apps +create --help` 为准。
+
+## 何时用
+
+用来创建应用资产并拿到 `app_id`。它不负责把自然语言需求交给云端 Agent：用户要“帮我生成/迭代应用”时，先创建 `full_stack` app，再进入 [`lark-apps-cloud-dev.md`](lark-apps-cloud-dev.md) 用 `+session-create` / `+chat` 提交需求。
+
+## 命令骨架
+
+- 必填：`--name`、`--app-type`。
+- app type 语义取值为 `html` / `full_stack`；CLI 会把输入归一成小写后校验。
+- 可选：`--description`、`--icon-url`。
+
+## 示例
+
+```bash
+lark-cli apps +create --name "客户调研问卷" --app-type html
+
+lark-cli apps +create --name "审批系统" --app-type full_stack \
+  --description "部门审批系统，支持登录、提交申请、多级审批"
+
+lark-cli apps +create --name "Demo" --app-type html --dry-run
+```
+
+## 输出契约
+
+- 成功默认 JSON envelope 中读取 `data.app.app_id`，同时可用 `data.app.name` / `description` 向用户确认结果。
+- pretty 输出只适合人看；后续命令需要 app_id 时，用 JSON 或 `--jq '.data.app.app_id'`。
+
+## app type 与命名
+
+- `--app-type` 取值与判定信号见 SKILL.md「选择开发路径」，此处不重复。
+- 用户只给自然语言需求时，据此生成简洁的 `--name` 和一句 `--description` 直接创建；不满意再用 `+update` 改。
+
+创建后按用户路径继续：
+
+- 发布现成 HTML/静态目录：读 [`lark-apps-html-publish.md`](lark-apps-html-publish.md)。
+- 本地全栈开发：读 [`lark-apps-local-dev.md`](lark-apps-local-dev.md)。
+- 云端 Agent 生成/迭代：读 [`lark-apps-cloud-dev.md`](lark-apps-cloud-dev.md)。

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

@@ -0,0 +1,44 @@
+# apps +db-execute
+
+经妙搭服务端在应用数据库执行 SQL。运行时命令事实以 `lark-cli apps +db-execute --help` 为准。
+
+## 何时用
+
+用于通过妙搭服务端执行应用数据库 SQL。不要从环境变量里取连接串裸连数据库；本地调试也走这个 shortcut。
+
+## 命令骨架
+
+- 必填：`--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`，没有 dev 分支）**时显式 `--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 中取出来裸连。

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)。
+
+## 命令一览
+
+| 命令 | 做什么 | 关键参数 |
+|---|---|---|
+| `+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`（所有 db 命令统一默认 `dev`）**：看表、看结构、数据导入导出、变更追溯、审计、配额都按环境区分，写操作建议先在 `dev` 验。**注意：只有开启了多环境（`+db-env-create`）的应用才有 `dev` 分支；未开启多环境的应用其数据库在 `online`——对这类应用必须显式 `--environment online`，否则默认的 `dev` 分支不存在、会报错**。旧名 `--env` 已**移除**：传入会报 validation 错（提示改用 `--environment`），一律用 `--environment`。`+db-env-diff`/`+db-env-migrate` 是「dev→online 发布」语义、`+db-recovery-*` 作用于当前库，二者**没有** `--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`。
+- 看表用 `+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-git-credential.md

@@ -0,0 +1,37 @@
+# apps Git credential
+
+妙搭 Git 凭证用于本地原生 `git clone/pull/push`。运行时命令事实以 `lark-cli apps +git-credential-init --help`、`+git-credential-list --help`、`+git-credential-remove --help` 为准。
+
+## 命令
+
+```bash
+lark-cli apps +git-credential-init --app-id app_xxx
+lark-cli apps +git-credential-list
+lark-cli apps +git-credential-remove --app-id app_xxx
+```
+
+## 输出契约
+
+- `+git-credential-init` 成功后读取 `data.repository_url`；不要展示或保存其中的凭据细节，只用于下一步 `git clone`。
+- `+git-credential-list` 返回本地记录和状态；可用来判断是否需要重新 init。
+- `+git-credential-remove` 只清本地配置；成功后告知不会删除云端应用或仓库。
+
+## 行为规则
+
+- `+git-credential-init` 返回 `repository_url`，并配置 URL-scoped Git credential helper。后续 clone/pull/push 使用原生 git。
+- `+git-credential-list` 列出本地已配置的妙搭 Git 凭证，不需要 `--app-id`。
+- `+git-credential-remove` 只移除本地凭证/helper，不删除云端应用或仓库。
+- 看到 Repository URL 后继续：
+
+```bash
+git clone <repository_url>
+cd <repo>
+git checkout sprint/default
+```
+
+## Agent 规则
+
+- 不要手动打印、保存或拼接 token。
+- clone、pull、push、diff、log 等代码仓库操作都使用原生 `git`；不存在 `apps +pull` / `apps +push` / `apps code +read` 这类代码读写 shortcut，不要臆造。
+- 不要 push/force-push `main`；`main` 是发布态快照，由 `apps +release-create` 成功后服务端推进，直推/force-push 会被服务端护栏拒绝。
+- Git 认证失败、本地凭证损坏或 helper 缺失时，重新执行 `+git-credential-init --app-id <id>` 覆盖本地配置；不要让用户复制 token 到 remote URL。