@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.7f786ca → 0.1.0-dev.942e73f

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

@@ -55,9 +55,9 @@ lark-cli apps +db-table-get --app-id "$app_id" --table orders --environment dev
 
 ## 环境与通用约定
 
-- **环境 `--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`。
+- **环境 `--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` 缺省会被确认关卡拦下（exit 10）；动手前先用对应的预览命令或 `--dry-run` 看清影响。
+- **高危操作必须带 `--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 修复再重试。
 
@@ -117,6 +117,116 @@ lark-cli apps +db-data-import --app-id "$app_id" --table orders --file ./orders.
 
 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`。
@@ -198,6 +308,7 @@ lark-cli apps +db-quota-get --app-id "$app_id" --environment dev
 | 多环境初始化 | `+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 确认关卡，不代替授权。
 

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

@@ -1,6 +1,6 @@
 ---
 name: lark-apps-ops
-description: "Use when 在妙搭沙箱里用 `lark-cli apps +<cmd>` 操作【当前这个已存在的】妙搭应用：本地全栈开发与部署发布上线（+release-*）、环境变量管理（+env-*）、线上日志/Trace/监控指标/PV-UV 查询（+log-*/+trace-*/+metric-list/+analytics-list）、运行时可见范围（+access-scope-*）、应用协作者与协作权限设置（+member-*）、AI 与飞书平台能力插件安装/卸载（+plugin-*）、改应用名或描述（+update）、开放 API Key 管理（+openapi-key-*）、运行时缓存调试（+cache-get/+cache-delete/+cache-clear）；本 skill 也是 apps 命令族的意图路由入口——应用数据库走 lark-apps-db、应用文件存储走 lark-apps-file、角色与权限走 lark-apps-authz。触发词：部署, 上线, 发布, 环境变量, 线上日志, 接口请求量, 错误量, 延迟, CPU, 内存, PV, UV, 访问量, 可见范围, 分享链接, 协作者, 开发权限, 谁能改这个应用, 外部协作, 插件, 改名, API Key, 缓存, cache, 清缓存, 缓存没更新, +release-, +env-, +access-scope-, +member-, +plugin-, +openapi-key-, +cache-. NOT for 新建应用/应用列表/初始化/HTML 发布/会话/自动化等未开放命令（见「能力边界」），以及非 apps 域的飞书操作（走 lark-cli skill）。"
+description: "Use when 在妙搭沙箱里用 `lark-cli apps +<cmd>` 操作【当前这个已存在的】妙搭应用：本地开发与部署发布上线（+release-*）、环境变量管理（+env-*）、线上日志/Trace/监控指标/PV-UV 查询（+log-*/+trace-*/+metric-list/+analytics-list）、运行时可见范围（+access-scope-*）、应用协作者与协作权限设置（+member-*）、AI 与飞书平台能力插件安装/卸载（+plugin-*）、改应用名或描述（+update）、开放 API Key 管理（+openapi-key-*）、运行时缓存调试（+cache-get/+cache-delete/+cache-clear）、妙搭 user_id 与飞书 open_id/union_id/user_id 互转（+user-id-convert）；本 skill 也是 apps 命令族的意图路由入口——应用数据库走 lark-apps-db、应用文件存储走 lark-apps-file、角色与权限走 lark-apps-authz。触发词：部署, 上线, 发布, 环境变量, 线上日志, 接口请求量, 错误量, 延迟, CPU, 内存, PV, UV, 访问量, 可见范围, 分享链接, 协作者, 开发权限, 谁能改这个应用, 外部协作, 插件, 改名, API Key, 缓存, cache, 清缓存, 缓存没更新, ID 转换, open_id 转 user_id, +release-, +env-, +access-scope-, +member-, +plugin-, +openapi-key-, +cache-, +user-id-convert. NOT for 新建应用/应用列表/初始化/HTML 发布/会话/自动化等未开放命令（见「能力边界」），以及非 apps 域的飞书操作（走 lark-cli skill）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -10,7 +10,7 @@ control-by-feature-ab: true
 
 # 妙搭应用 (apps) · 沙箱版
 
-在妙搭沙箱里通过 `lark-cli` 操作**当前这个已存在的**妙搭应用（全栈应用），源码已在工作区。本 skill 是 apps 命令族的意图路由入口：通用约定在本文件，各模块命令细节按下表分流到兄弟 skill 或本 skill 的 references。沙箱约定优先于 references 正文。
+在妙搭沙箱里通过 `lark-cli` 操作**当前这个已存在的**妙搭应用（full_stack 全栈或 frontend 纯前端应用），源码已在工作区。本 skill 是 apps 命令族的意图路由入口：通用约定在本文件，各模块命令细节按下表分流到兄弟 skill 或本 skill 的 references。沙箱约定优先于 references 正文。
 
 ## 沙箱约定（先读）
 
@@ -34,8 +34,8 @@ control-by-feature-ab: true
 
 | 用户意图 | 先用 | 详情 |
 |---|---|---|
-| 本地全栈开发：改代码、调试数据库、提交推送（源码已在工作区），再走发布链路上线。**执行前必读**，含部署流程和领域规则 | 原生 `git`（提交推送）+ 下方发布链路 | [local-dev](references/lark-apps-local-dev.md) |
-| **部署/上线全栈应用**（"部署""上线""推上去并部署""发布到云端"）；查发布状态/历史 | `+release-create`（部署上线动作）、`+release-get`（轮询发布结果，finished 给 online_url / failed 给 error_logs）、`+release-list` | [release-create](references/lark-apps-release-create.md)、[release-get](references/lark-apps-release-get.md)、[release-list](references/lark-apps-release-list.md) |
+| 本地开发：改代码、调试数据库（仅全栈应用有数据库）、提交推送（源码已在工作区），再走发布链路上线。**执行前必读**，含部署流程和领域规则 | 原生 `git`（提交推送）+ 下方发布链路 | [local-dev](references/lark-apps-local-dev.md) |
+| **部署/上线应用**（"部署""上线""推上去并部署""发布到云端"）；查发布状态/历史 | `+release-create`（部署上线动作）、`+release-get`（轮询发布结果，finished 给 online_url / failed 给 error_logs）、`+release-list` | [release-create](references/lark-apps-release-create.md)、[release-get](references/lark-apps-release-get.md)、[release-list](references/lark-apps-release-list.md) |
 | 管理应用环境变量（查看/设置/删除） | `+env-list`、`+env-set`、`+env-delete` | [env](references/lark-apps-env.md) |
 | 查线上日志、Trace、请求数、错误率、延迟、CPU、memory、PV/UV/访问量 | `+log-list`、`+log-get`、`+trace-list`、`+trace-get`、`+metric-list`、`+analytics-list` | [observability](references/lark-apps-observability.md) |
 | 应用数据库：看表/改表、执行 SQL、导入导出、多环境发布、审计、时间点恢复、DB 用量 | `+db-*` 命令族 | **→ [lark-apps-db](../lark-apps-db/SKILL.md)** |
@@ -44,6 +44,7 @@ control-by-feature-ab: true
 | 设置或查看运行时可见范围（谁能打开应用） | `+access-scope-set`、`+access-scope-get` | [access-scope-set](references/lark-apps-access-scope-set.md)、[access-scope-get](references/lark-apps-access-scope-get.md) |
 | 管理应用协作者（谁能开发这个应用：列出/添加/改权限/移除）或协作策略（外部分享、链接分享、评论、谁能管协作者） | `+member-list`、`+member-settings-get`、`+member-add`、`+member-update`、`+member-remove`、`+member-settings-set` | [member](references/lark-apps-member.md) ⚠️ 四条写命令高风险；`--member-type` 必须与 `--member-id` 前缀匹配，禁传内部数字 ID |
 | 外部能力（AI 模型能力和飞书平台能力）集成/插件/Plugin/Capability | `+plugin-install`、`+plugin-list`、`+plugin-uninstall` | [plugin-install](references/lark-apps-plugin-install.md)、[plugin-list](references/lark-apps-plugin-list.md)、[plugin-uninstall](references/lark-apps-plugin-uninstall.md) |
+| 把一批 ID 在妙搭 user_id ↔ 飞书 open_id / union_id / 飞书 user_id 之间互转（例如拿到 open_id 但下游要妙搭 user_id、审批要飞书 user_id） | `+user-id-convert --convert-type <方向> --ids <id1,id2,...>`（只读） | [user-id-convert](references/lark-apps-user-id-convert.md) |
 | 改应用名或描述 | `+update` | [update](references/lark-apps-update.md) |
 | 调试应用运行时缓存：查某个 key 的内容/TTL、删单个 key、清空某环境全部缓存 | `+cache-get`、`+cache-delete`、`+cache-clear` | [cache](references/lark-apps-cache.md) ⚠️ 写操作不传 `--environment` 时，无多环境的应用会直接作用到线上；`+cache-clear` 高风险 |
 | 管理开放 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 高风险 |

package/miaoda/lark-apps-ops/references/lark-apps-access-scope-get.md

@@ -27,4 +27,4 @@ lark-cli apps +access-scope-get --app-id "$app_id"
 
 向用户解释时映射为：`All` = public，`Tenant` = tenant，`Range` = specific；`Range` 按用户、部门、群分组摘要后再呈现。用户要修改时转到 [`+access-scope-set`](lark-apps-access-scope-set.md)。
 
-妙搭全栈应用发布后**默认仅创建者可见**，发布态链接发给他人对方会无权限打不开。用户要把发布态链接分享给别人时，先用本命令确认当前范围，再决定是否用 [`+access-scope-set`](lark-apps-access-scope-set.md) 放开到 `tenant` / `public` / `specific`。
+妙搭应用（full_stack / frontend）发布后**默认仅创建者可见**，发布态链接发给他人对方会无权限打不开。用户要把发布态链接分享给别人时，先用本命令确认当前范围，再决定是否用 [`+access-scope-set`](lark-apps-access-scope-set.md) 放开到 `tenant` / `public` / `specific`。

package/miaoda/lark-apps-ops/references/lark-apps-local-dev.md

@@ -1,6 +1,6 @@
-# lark-apps 本地全栈开发
+# lark-apps 本地开发
 
-适用：当前妙搭全栈应用的源码已在工作区，用本地 code agent/IDE 开发、调试数据库，再部署上线。
+适用：当前妙搭应用（full_stack 全栈或 frontend 纯前端）的源码已在工作区，用本地 code agent/IDE 开发、调试数据库（仅全栈应用有数据库），再部署上线。
 
 ## 改完代码后部署上线
 
@@ -19,6 +19,7 @@
 - `sprint/default` 是工作分支；`main` 是发布态快照，由 `+release-create` 成功后服务端 fast-forward 推进；服务端护栏禁直推 `main`、拒 force-push、要求 `sprint/default` fast-forward。
 - pull/push/diff/log 都用原生 git；云端 `sprint/default` 比本地新时，先 `git pull --rebase origin sprint/default`，解决冲突后再 push 和 publish。
 - 环境变量由脚手架在本地启动时处理。
+- frontend（纯前端，vite-react）应用的开发与部署流程和全栈一致，只是没有数据库、跳过一切 `+db-*` 步骤。后续要加数据库/后端能力时，本地链路不提供类型升级：引导用户到妙搭 web 的云端会话里用自然语言提出（如「给这个应用加登录和数据存储」）即可触发升级，无需特殊指令，也不要替用户拼站点地址。
 - DB 调试用 `+db-table-list` / `+db-table-get` / `+db-execute`（见 lark-apps-db skill）；不要裸连数据库或自行拼连接串。
 - DB 分 `dev` / `online`；日常调试优先 `--environment dev`。dev 的库结构变更要上线时，仍按应用发布链路走 `+release-create`，不要另造“数据库发布”步骤。
 - 存量单库应用需要 dev/online 多环境时，用 `+db-env-create --environment dev`。这是不可逆 high-risk 操作。

package/miaoda/lark-apps-ops/references/lark-apps-release-create.md

@@ -4,7 +4,7 @@
 
 ## 何时用
 
-用于把全栈应用的代码分支推进到发布流程。
+用于把应用的代码分支推进到发布流程（full_stack / frontend 应用统一走此入口）。
 
 ## 命令骨架
 

package/miaoda/lark-apps-ops/references/lark-apps-user-id-convert.md

@@ -0,0 +1,63 @@
+# apps +user-id-convert
+
+把一批已知 ID 在**妙搭 user_id** 与**飞书开放平台 ID**（open_id / union_id / 飞书 user_id）之间互转。运行时命令事实以 `lark-cli apps +user-id-convert --help` 为准。
+
+## 何时用
+
+沙箱里常通过 `contact` / `im` 域拿到飞书 `open_id`，但下游（妙搭插件、审批、网关）消费的是妙搭 `user_id` 或飞书 `user_id`。这个命令补上中间那一步转换。典型场景：
+
+- feishu-approval 插件要发起审批，`createApprovalInstance` 需要飞书 `user_id`，而手里只有妙搭 `user_id` → 用 `miaoda-to-feishu-user-id`。
+- 插件配置表单 / 人员选择器返回 `open_id`，但最终要落库妙搭 `user_id` → 用 `open-id-to-miaoda`。
+
+它只做一件事——转换。**没有**本地映射表、缓存、权限预判，也不猜方向。它不替代权限校验：能不能拿到目标 ID 仍由上游 scope 和文档/审批自身的可见范围决定，本命令只转换一个已知 ID 的格式。
+
+## 命令骨架
+
+- 必填 `--convert-type`：转换方向枚举，缺失或非法直接报可读的校验错误，不猜默认方向。
+- 必填 `--ids`：逗号分隔，或 `@文件` / `-`（stdin）。每次 1–100 个（服务端上限 100；CLI 额外拒绝空批以免空跑）。**不去重**，按输入顺序返回。
+- 只读命令，无写副作用，不需要 `--yes`。
+- 需要 scope `spark:directory.user.id_convert:read`。限流 50 req/s，CLI 不自动重试。
+
+### `--convert-type` 方向表
+
+| `--convert-type` | 含义 | 目标形态 |
+| --- | --- | --- |
+| `miaoda-to-open-id` | 妙搭 user_id → 飞书 Open ID | `ou_…` |
+| `miaoda-to-union-id` | 妙搭 user_id → 飞书 Union ID | `on_…` |
+| `open-id-to-miaoda` | 飞书 Open ID → 妙搭 user_id | 数字串 |
+| `union-id-to-miaoda` | 飞书 Union ID → 妙搭 user_id | 数字串 |
+| `miaoda-to-feishu-user-id` | 妙搭 user_id → 飞书 user_id | 数字（employee_id） |
+
+## 示例
+
+```bash
+# 批量把 open_id 转妙搭 user_id
+lark-cli apps +user-id-convert --convert-type open-id-to-miaoda --ids ou_abc123,ou_def456
+
+# 从 stdin 读 ID 列表
+printf 'ou_abc123,ou_def456' | lark-cli apps +user-id-convert --convert-type open-id-to-miaoda --ids -
+
+# 只看将要发送的请求体，不真正调用
+lark-cli apps +user-id-convert --convert-type miaoda-to-feishu-user-id --ids 1234567890123456 --dry-run
+```
+
+## 输出契约
+
+标准 apps stdout 信封，agent 用 `ok == true` 判成功（不是 `code == 0`）。响应字段保持服务端 `snake_case`。
+
+- `data.convert_type`：回显所传的 `--convert-type`。
+- `data.items[]`：`{index, source_id, target_id}`，`index` 是该 ID 在 `--ids` 中的 0 基位置。
+- `data.missed[]`：服务端静默丢弃的未解析 ID，CLI 用输入位置 diff 重建，`{index, source_id, reason: "not_found"}`。
+- `meta`：`{total, hit_count, missed_count}`，`total` = `--ids` 输入数（含重复，不去重），且 `hit_count + missed_count = total`。
+
+**部分命中**：批量里只要有 ID 转不出，它不是错误——服务端省略该项，CLI 把它落到 `missed`（`reason: not_found`），并保留 `index` = 输入位置，重复 ID 也能按位置回填。
+
+## Agent 规则
+
+- **方向不匹配不是错误**：比如在 `miaoda-to-open-id` 下传了 `ou_` 开头的 ID，服务端省略它 → 落到 `missed`。看到 `missed` 时先检查 ID 前缀是否与 `--convert-type` 方向一致。
+- **整批被拒**（服务端 `code != 0`）才是 `api` 错误，带透传 code 和 `log_id`，不重试；限流同理，降低调用频率。
+- 结果只在 stdout 返回一次，不落盘、不写会话上下文。
+
+## 边界
+
+只转换 ID 格式，不判断调用方是否有权拿到目标 ID。是否有权限由上游 scope 与资源自身可见范围决定，本命令不做预检。

package/miaoda/miaoda-sql/SKILL.md

@@ -98,6 +98,15 @@ CREATE POLICY "修改本人数据" ON <table>
 > pgPolicy("插入", { for: "insert", to: [authenticatedRole] }),                       // ❌ 漏 withCheck → 不生效
 > ```
 >
+> **公开匿名写入**：默认模板只含 `anon` SELECT。仅当业务允许未登录访客提交时，才给目标 RLS 表补匿名插入，并用未登录 HTTP POST 2xx 验证：
+>
+> ```sql
+> CREATE POLICY "允许匿名插入" ON <table>
+>   AS PERMISSIVE FOR INSERT TO anon WITH CHECK (true);
+> ```
+>
+> Drizzle 等价规则：`pgPolicy(..., { for: "insert", to: [anonRole], withCheck: sql`true` })`。反例：`FOR SELECT TO anon` 只读，`FOR INSERT TO authenticated` 只登录态写；个人数据、后台管理、公开只读页仍走登录/权限控制。
+>
 > **查询空 / 42501 排查序**：① policy 表达式是否为 `NULL`（`miaoda db schema get <table>` 看 `using`/`with_check`）→ ② 连接角色是否在 `TO` 列表（`authenticated`/`anon`）→ ③ 依赖 `app.user_id` 的策略是否 `SET LOCAL app.user_id`。
 
 建表流程：`schema list/get` 确认不存在或需变更 -> 生成 DDL -> 用户授权 -> `miaoda db sql` 执行 -> 插入 mock -> 必要时重跑 codegen 刷新 `schema.ts`。

package/miaoda/semantic-search/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: semantic-search
 description: 当妙搭应用需要为业务数据实现向量检索、语义搜索、相似内容召回或相似记录推荐时使用。适用于商品、文档、FAQ、工单、评论、案例等文本数据的语义匹配场景；方案基于妙搭 PG，通过 rds_ai.ai_embed 生成文本 embedding，并结合 vector 插件完成向量存储、HNSW 索引和相似度查询。
-control-by-feature-ab: true
 ---
 
 # 语义检索与相似召回

package/miaoda/table-skill/SKILL.md

@@ -3,6 +3,8 @@ name: table-skill
 description: '@lark-apaas/client-toolkit/antd-table 表格开发规范：列类型用 TableColumnsType，含后端分页、固定列、加载状态等最佳实践'
 available-agents:
   - Code
+  - Worker
+  - Reviewer
 ---
 
 # Table Skill

package/miaoda/testing-guide/SKILL.md

@@ -26,13 +26,15 @@ gate-tools:
 
 ```
 用户想确认应用是否正常
+  ├─ Task 工具定义的 subagent_type 选项里没有 E2E（E2E 被关闭/不可用，非"本轮没派过"）→ api_request（接口级验收）+ 读代码/读日志兜底，不要尝试派 E2E
   ├─ 明确要求验证「后端接口」「API 返回值」「请求响应」 → api_request
   └─ 其他所有情况 → Task(subagent_type="E2E")（打开浏览器，以用户视角操作应用）
                   ├─ 只看视觉（白屏/布局/样式/文案）→ agent_options.mode: "lite"
                   └─ 涉及交互/业务流程/数据 → 不传或 agent_options.mode: "standard"
 ```
 
-- **模糊需求一律派遣 E2E**：未明确提到「接口」「API」「后端」时必须派遣 E2E，不要主动选择 `api_request`
+- **E2E 不可用时改走 api_request（最高优先，先于下面所有规则判断）**：当 Task 工具定义的 subagent_type 选项里没有 E2E（用户关闭了浏览器验收 / 环境不支持；判断依据是工具定义中是否含 E2E 选项，不是"本轮有没有派过 E2E"）时，下面"模糊需求一律派遣 E2E"不再适用——改用 `api_request` 做接口级验收，配合读代码 / 读运行时日志确认核心链路，**不要尝试派 E2E、也不要空等**；此时验收范围收敛到接口与数据层可判定结果，视觉类目标顺延到非核心降级范围
+- **模糊需求一律派遣 E2E**（仅当 E2E 可用）：未明确提到「接口」「API」「后端」时必须派遣 E2E，不要主动选择 `api_request`
 - **`api_request` 仅限显式请求**：仅当明确提到接口 / API / 后端 / 请求 / 响应、且意图是验证接口逻辑而非页面功能时才使用
 - **E2E 结束后禁止追加 `api_request`**：浏览器操作的结果即为最终结果，**严禁**再自动补充验证
 

package/miaoda-design/lark-apps-comment/SKILL.md

@@ -4,69 +4,64 @@ description: 当需要查看当前妙搭应用收到的评论、或把某条评
 metadata:
   requires:
     bins: ["lark-cli"]
-  cliHelp: "lark-cli drive file.comments list --help; lark-cli drive file.comments patch --help"
+  cliHelp: "lark-cli drive +list-comments --help; lark-cli drive +list-replies --help; lark-cli drive +resolve-comment --help"
 control-by-feature-ab: true
 ---
 
 # lark-apps-comment
 
-查看 / 处理**当前应用**的评论。评论上下文来自应用 ID（环境变量 `$app_id`），先经 `lark-cli apps +get` 换取 `meta_token`，再按 `file_type=apps` + `file_token=<meta_token>` 调 `drive file.comments`。
+查看 / 处理**当前应用**的评论。评论上下文来自应用 ID（环境变量 `$app_id`），先经 `lark-cli apps +get` 换取 `meta_token`，再用 drive 域评论快捷命令（`--token <meta_token> --type apps`）操作。
 
 ```bash
 # 取 meta_token（先执行一次，后续命令复用）
 lark-cli apps +get --app-id "$app_id" -q '.data.app.meta_token'
 
-# 仅未解决评论（默认口径）
-lark-cli drive file.comments list \
-  --params '{"file_token":"<meta_token>","file_type":"apps","is_solved":false}' \
-  --format json
+# 未解决评论（--solved-status 默认 false，正是本 skill 的默认口径）
+lark-cli drive +list-comments --token "<meta_token>" --type apps --format json
 
 # 标记已解决
-lark-cli drive file.comments patch \
-  --params '{"file_token":"<meta_token>","file_type":"apps","comment_id":"<commentID>","is_solved":true}' \
-  --format json
+lark-cli drive +resolve-comment --token "<meta_token>" --type apps \
+  --comment-id "<commentID>" --format json
 ```
 
-> 参数结构以 `lark-cli schema drive.file.comments.list` / `lark-cli schema drive.file.comments.patch` 为准。
-
 ## 何时使用
 
 ✅ 用户说"看看有哪些评论 / 反馈没处理"
 ✅ 想按用户反馈列一个待办清单再逐条改
 ✅ 某条反馈已经改完，把它标记为已解决
 
-❌ 想给评论**回复文字**（沙箱内回复写 API 不可用，只支持看列表和 resolve）
+❌ 想给评论**回复文字**（回复/更新回复不在本 skill 范围，评论处理只做查看与 resolve）
 ❌ 修改代码 / 页面本身（用代码编辑工具）
 
 ## 子命令
 
-### `drive file.comments list` —— 查看评论列表
+### `drive +list-comments` —— 查看评论列表
 
 ```bash
-# 仅未解决评论（默认口径，对齐原 miaoda comment list --only-unresolved）
-lark-cli drive file.comments list \
-  --params '{"file_token":"<meta_token>","file_type":"apps","is_solved":false}' \
-  --format json
-
-# 全部评论（用户明确要求"全部"时省略 is_solved）
-lark-cli drive file.comments list \
-  --params '{"file_token":"<meta_token>","file_type":"apps"}' \
-  --format json
+# 未解决评论（默认口径，对齐原 miaoda comment list --only-unresolved）
+lark-cli drive +list-comments --token "<meta_token>" --type apps --format json
+
+# 全部评论（仅当用户明确要求"包含已解决"时才传 --solved-status all）
+lark-cli drive +list-comments --token "<meta_token>" --type apps --solved-status all --format json
 ```
 
-- 分页返回；`has_more=true` 时把返回的 `page_token` 填入 `--params` 的 `"page_token"` 续拉。
-- 评论正文在 `items[].reply_list.replies[].content.elements[]` 里；`is_solved` 标记是否已解决；另有 `quote`（划词引用）等字段。
+- `--solved-status` 默认 `false`（只查未解决）。即使用户说"所有评论"，只要没明确提到包含已解决评论，仍按默认口径查；明确要已解决的传 `true`，全部传 `all`。
+- 分页：**外层** `has_more=true` 时把返回的 `page_token` 传给 `--page-token` 续拉（还有下一页评论卡片），不自动翻页。
+- 返回的 `items` 是评论卡片：第一条 reply（根回复）就是这条评论本身，正文在 `items[].reply_list.replies[].content.elements[]`；`is_solved` 标记是否已解决；另有 `quote`（划词引用）等字段。
 
 JSON（`--format json`，节选）：
 
 ```json
 {
+  "file_token": "<meta_token>",
+  "file_type": "apps",
   "items": [
     {
       "comment_id": "6916106822734512356",
       "is_solved": false,
       "is_whole": true,
       "quote": "划词评论引用内容",
+      "has_more": false,
       "reply_list": {
         "replies": [
           {
@@ -80,31 +75,45 @@ JSON（`--format json`，节选）：
       }
     }
   ],
-  "has_more": false
+  "has_more": false,
+  "page_token": "",
+  "count": 1
 }
 ```
 
-### `drive file.comments patch` —— 标记已解决
+### `drive +list-replies` —— 拉全某条评论的回复
+
+**卡片级** `items[].has_more=true` 是与外层分页不同的字段：表示该条评论下还有回复没返回全，漏了会看不到用户的后续补充说明。用本命令按 `comment_id` 拉全：
+
+```bash
+lark-cli drive +list-replies --token "<meta_token>" --type apps \
+  --comment-id "<commentID>" --format json
+# items 是该评论的完整回复数组；输出自身 has_more=true 时用返回的 page_token 续拉
+```
+
+### `drive +resolve-comment` —— 标记已解决
 
-把一条评论标记为已解决，`commentID` 从 list 的 `comment_id` 字段拿：
+把一条评论标记为已解决，`commentID` 从 `+list-comments` 的 `items[].comment_id` 拿：
 
 ```bash
-lark-cli drive file.comments patch \
-  --params '{"file_token":"<meta_token>","file_type":"apps","comment_id":"1703677660120110076","is_solved":true}' \
-  --format json
+lark-cli drive +resolve-comment --token "<meta_token>" --type apps \
+  --comment-id "1703677660120110076" --format json
 ```
 
-写操作，可能触发 exit-10 高风险审批（见 lark-cli skill 的沙箱约定）：按提示显式确认后重试。
+- 写操作；成功回执含 `"action": "resolve", "is_solved": true, "updated": true`。
+- 误关了要重新打开时用反向命令 `drive +restore-comment`（参数同上）。
+- 对同一条评论连续翻转解决状态可能触发服务端限流（HTTP 429），连续调用之间留间隔。
 
 ## 典型流程
 
 1. `lark-cli apps +get --app-id "$app_id" -q '.data.app.meta_token'` 取 meta_token
-2. `drive file.comments list`（`is_solved:false`）拿到待处理评论
-3. 按评论正文逐条改代码（正文在 `items[].reply_list.replies[].content.elements[].text_run.text`）
-4. 改完对应项后用 `drive file.comments patch` 逐条 `resolve` 关掉
+2. `drive +list-comments --token "<meta_token>" --type apps` 拿到待处理评论（默认即未解决）
+3. 任一条 `items[].has_more=true` → 先用 `drive +list-replies --comment-id <id>` 把该评论的回复拉全，别漏掉用户的补充说明
+4. 按评论正文逐条改代码（正文在 `items[].reply_list.replies[].content.elements[].text_run.text`）
+5. 改完对应项后用 `drive +resolve-comment` 逐条关掉
 
 ## 失败处理
 
 - 命令失败时把 `error.hint` 转述给用户，不要原样甩 envelope JSON。
 - `permission denied`：当前身份对该应用 page 没有评论读写权限，转述后停止，不要自行补登录或改身份。
-- `invalid file_type`：确认 `file_type=apps`，且 `file_token` 是 `+get` 返回的 `meta_token`（不是 app_id 本身）。
+- validation error 提示类型不符：确认 `--type apps`，且 `--token` 是 `+get` 返回的 `meta_token`（不是 app_id 本身）。

package/miaoda-modern/lark-apps-ops/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: lark-apps-ops
-description: "Use when 在妙搭沙箱里用 `lark-cli apps +<cmd>` 操作【当前这个已存在的】妙搭应用：本地全栈开发与部署发布上线（+release-*）、环境变量管理（+env-*）、线上日志/Trace/监控指标/PV-UV 查询（+log-*/+trace-*/+metric-list/+analytics-list）、运行时可见范围（+access-scope-*）、应用协作者与协作权限设置（+member-*）、AI 与飞书平台能力插件安装/卸载（+plugin-*）、改应用名或描述（+update）、开放 API Key 管理（+openapi-key-*）、运行时缓存调试（+cache-get/+cache-delete/+cache-clear）；本 skill 也是 apps 命令族的意图路由入口——应用数据库走 lark-apps-db、应用文件存储走 lark-apps-file、角色与权限走 lark-apps-authz。触发词：部署, 上线, 发布, 环境变量, 线上日志, 接口请求量, 错误量, 延迟, CPU, 内存, PV, UV, 访问量, 可见范围, 分享链接, 协作者, 开发权限, 谁能改这个应用, 外部协作, 插件, 改名, API Key, 缓存, cache, 清缓存, 缓存没更新, +release-, +env-, +access-scope-, +member-, +plugin-, +openapi-key-, +cache-. NOT for 新建应用/应用列表/初始化/HTML 发布/会话/自动化等未开放命令（见「能力边界」），以及非 apps 域的飞书操作（走 lark-cli skill）。"
+description: "Use when 在妙搭沙箱里用 `lark-cli apps +<cmd>` 操作【当前这个已存在的】妙搭应用：本地开发与部署发布上线（+release-*）、环境变量管理（+env-*）、线上日志/Trace/监控指标/PV-UV 查询（+log-*/+trace-*/+metric-list/+analytics-list）、运行时可见范围（+access-scope-*）、应用协作者与协作权限设置（+member-*）、AI 与飞书平台能力插件安装/卸载（+plugin-*）、改应用名或描述（+update）、开放 API Key 管理（+openapi-key-*）、运行时缓存调试（+cache-get/+cache-delete/+cache-clear）、妙搭 user_id 与飞书 open_id/union_id/user_id 互转（+user-id-convert）；本 skill 也是 apps 命令族的意图路由入口——应用数据库走 lark-apps-db、应用文件存储走 lark-apps-file、角色与权限走 lark-apps-authz。触发词：部署, 上线, 发布, 环境变量, 线上日志, 接口请求量, 错误量, 延迟, CPU, 内存, PV, UV, 访问量, 可见范围, 分享链接, 协作者, 开发权限, 谁能改这个应用, 外部协作, 插件, 改名, API Key, 缓存, cache, 清缓存, 缓存没更新, ID 转换, open_id 转 user_id, +release-, +env-, +access-scope-, +member-, +plugin-, +openapi-key-, +cache-, +user-id-convert. NOT for 新建应用/应用列表/初始化/HTML 发布/会话/自动化等未开放命令（见「能力边界」），以及非 apps 域的飞书操作（走 lark-cli skill）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -10,7 +10,7 @@ control-by-feature-ab: true
 
 # 妙搭应用 (apps) · 沙箱版
 
-在妙搭沙箱里通过 `lark-cli` 操作**当前这个已存在的**妙搭应用（全栈应用），源码已在工作区。本 skill 是 apps 命令族的意图路由入口：通用约定在本文件，各模块命令细节按下表分流到兄弟 skill 或本 skill 的 references。沙箱约定优先于 references 正文。
+在妙搭沙箱里通过 `lark-cli` 操作**当前这个已存在的**妙搭应用（full_stack 全栈或 frontend 纯前端应用），源码已在工作区。本 skill 是 apps 命令族的意图路由入口：通用约定在本文件，各模块命令细节按下表分流到兄弟 skill 或本 skill 的 references。沙箱约定优先于 references 正文。
 
 ## 沙箱约定（先读）
 
@@ -34,8 +34,8 @@ control-by-feature-ab: true
 
 | 用户意图 | 先用 | 详情 |
 |---|---|---|
-| 本地全栈开发：改代码、调试数据库、提交推送（源码已在工作区），再走发布链路上线。**执行前必读**，含部署流程和领域规则 | 原生 `git`（提交推送）+ 下方发布链路 | [local-dev](references/lark-apps-local-dev.md) |
-| **部署/上线全栈应用**（"部署""上线""推上去并部署""发布到云端"）；查发布状态/历史 | `+release-create`（部署上线动作）、`+release-get`（轮询发布结果，finished 给 online_url / failed 给 error_logs）、`+release-list` | [release-create](references/lark-apps-release-create.md)、[release-get](references/lark-apps-release-get.md)、[release-list](references/lark-apps-release-list.md) |
+| 本地开发：改代码、调试数据库（仅全栈应用有数据库）、提交推送（源码已在工作区），再走发布链路上线。**执行前必读**，含部署流程和领域规则 | 原生 `git`（提交推送）+ 下方发布链路 | [local-dev](references/lark-apps-local-dev.md) |
+| **部署/上线应用**（"部署""上线""推上去并部署""发布到云端"）；查发布状态/历史 | `+release-create`（部署上线动作）、`+release-get`（轮询发布结果，finished 给 online_url / failed 给 error_logs）、`+release-list` | [release-create](references/lark-apps-release-create.md)、[release-get](references/lark-apps-release-get.md)、[release-list](references/lark-apps-release-list.md) |
 | 管理应用环境变量（查看/设置/删除） | `+env-list`、`+env-set`、`+env-delete` | [env](references/lark-apps-env.md) |
 | 查线上日志、Trace、请求数、错误率、延迟、CPU、memory、PV/UV/访问量 | `+log-list`、`+log-get`、`+trace-list`、`+trace-get`、`+metric-list`、`+analytics-list` | [observability](references/lark-apps-observability.md) |
 | 应用数据库：看表/改表、执行 SQL、导入导出、多环境发布、审计、时间点恢复、DB 用量 | `+db-*` 命令族 | **→ [lark-apps-db](../lark-apps-db/SKILL.md)** |
@@ -44,6 +44,7 @@ control-by-feature-ab: true
 | 设置或查看运行时可见范围（谁能打开应用） | `+access-scope-set`、`+access-scope-get` | [access-scope-set](references/lark-apps-access-scope-set.md)、[access-scope-get](references/lark-apps-access-scope-get.md) |
 | 管理应用协作者（谁能开发这个应用：列出/添加/改权限/移除）或协作策略（外部分享、链接分享、评论、谁能管协作者） | `+member-list`、`+member-settings-get`、`+member-add`、`+member-update`、`+member-remove`、`+member-settings-set` | [member](references/lark-apps-member.md) ⚠️ 四条写命令高风险；`--member-type` 必须与 `--member-id` 前缀匹配，禁传内部数字 ID |
 | 外部能力（AI 模型能力和飞书平台能力）集成/插件/Plugin/Capability | `+plugin-install`、`+plugin-list`、`+plugin-uninstall` | [plugin-install](references/lark-apps-plugin-install.md)、[plugin-list](references/lark-apps-plugin-list.md)、[plugin-uninstall](references/lark-apps-plugin-uninstall.md) |
+| 把一批 ID 在妙搭 user_id ↔ 飞书 open_id / union_id / 飞书 user_id 之间互转（例如拿到 open_id 但下游要妙搭 user_id、审批要飞书 user_id） | `+user-id-convert --convert-type <方向> --ids <id1,id2,...>`（只读） | [user-id-convert](references/lark-apps-user-id-convert.md) |
 | 改应用名或描述 | `+update` | [update](references/lark-apps-update.md) |
 | 调试应用运行时缓存：查某个 key 的内容/TTL、删单个 key、清空某环境全部缓存 | `+cache-get`、`+cache-delete`、`+cache-clear` | [cache](references/lark-apps-cache.md) ⚠️ 写操作不传 `--environment` 时，无多环境的应用会直接作用到线上；`+cache-clear` 高风险 |
 | 管理开放 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 高风险 |

package/miaoda-modern/lark-apps-ops/references/lark-apps-access-scope-get.md

@@ -27,4 +27,4 @@ lark-cli apps +access-scope-get --app-id "$app_id"
 
 向用户解释时映射为：`All` = public，`Tenant` = tenant，`Range` = specific；`Range` 按用户、部门、群分组摘要后再呈现。用户要修改时转到 [`+access-scope-set`](lark-apps-access-scope-set.md)。
 
-妙搭全栈应用发布后**默认仅创建者可见**，发布态链接发给他人对方会无权限打不开。用户要把发布态链接分享给别人时，先用本命令确认当前范围，再决定是否用 [`+access-scope-set`](lark-apps-access-scope-set.md) 放开到 `tenant` / `public` / `specific`。
+妙搭应用（full_stack / frontend）发布后**默认仅创建者可见**，发布态链接发给他人对方会无权限打不开。用户要把发布态链接分享给别人时，先用本命令确认当前范围，再决定是否用 [`+access-scope-set`](lark-apps-access-scope-set.md) 放开到 `tenant` / `public` / `specific`。

package/miaoda-modern/lark-apps-ops/references/lark-apps-local-dev.md

@@ -1,6 +1,6 @@
-# lark-apps 本地全栈开发
+# lark-apps 本地开发
 
-适用：当前妙搭全栈应用的源码已在工作区，用本地 code agent/IDE 开发、调试数据库，再部署上线。
+适用：当前妙搭应用（full_stack 全栈或 frontend 纯前端）的源码已在工作区，用本地 code agent/IDE 开发、调试数据库（仅全栈应用有数据库），再部署上线。
 
 ## 改完代码后部署上线
 
@@ -19,6 +19,7 @@
 - `sprint/default` 是工作分支；`main` 是发布态快照，由 `+release-create` 成功后服务端 fast-forward 推进；服务端护栏禁直推 `main`、拒 force-push、要求 `sprint/default` fast-forward。
 - pull/push/diff/log 都用原生 git；云端 `sprint/default` 比本地新时，先 `git pull --rebase origin sprint/default`，解决冲突后再 push 和 publish。
 - 环境变量由脚手架在本地启动时处理。
+- frontend（纯前端，vite-react）应用的开发与部署流程和全栈一致，只是没有数据库、跳过一切 `+db-*` 步骤。后续要加数据库/后端能力时，本地链路不提供类型升级：引导用户到妙搭 web 的云端会话里用自然语言提出（如「给这个应用加登录和数据存储」）即可触发升级，无需特殊指令，也不要替用户拼站点地址。
 - DB 调试用 `+db-table-list` / `+db-table-get` / `+db-execute`（见 lark-apps-db skill）；不要裸连数据库或自行拼连接串。
 - DB 分 `dev` / `online`；日常调试优先 `--environment dev`。dev 的库结构变更要上线时，仍按应用发布链路走 `+release-create`，不要另造“数据库发布”步骤。
 - 存量单库应用需要 dev/online 多环境时，用 `+db-env-create --environment dev`。这是不可逆 high-risk 操作。

package/miaoda-modern/lark-apps-ops/references/lark-apps-release-create.md

@@ -4,7 +4,7 @@
 
 ## 何时用
 
-用于把全栈应用的代码分支推进到发布流程。
+用于把应用的代码分支推进到发布流程（full_stack / frontend 应用统一走此入口）。
 
 ## 命令骨架