@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.4e64c13 → 0.1.0-dev.5abff3b

package/miaoda/creative-to-fullstack/SKILL.md

@@ -6,152 +6,247 @@ workspace-contains:
   - source_package/creative/.upgrade-manifest.json
 ---
 
-# 根据创意设计稿生成全栈应用
+# 把创意设计稿实现为全栈应用
 
-`source_package/creative/` 是一份创意模式产物（UX 设计稿），它定义了应用的外观和功能，两者都要交付：视觉效果原样照抄源稿，功能实现为真实链路。架构从源稿分析得出，数据从源稿原样复制得出，都不允许自行设计或编造。
+`source_package/creative/` 是创意模式设计稿，是本次开发的唯一视觉规格。交付标准：
 
-术语约定：**初始数据**指源稿默认展示的内容写入数据库后形成的记录；**源稿定位**指源稿文件路径加行号区间。
+1. **视觉与源稿一致**：每个页面的文案、数值、色值、条目与顺序与设计稿逐字段一致。
+2. **可见功能真实可用**：设计稿上每个可交互组件（可点、可输入、可筛选）都产生真实、闭环的结果。
 
-## Quick Reference
+两条核心规则：**一切视觉内容直接从源稿代码照抄，不经过任何文字转述**；**动手实现前先完成业务设计并写入 `docs/business-design.md`，后续每个阶段以该文件为执行依据**。
 
-| 阶段 | 做什么 | 细则 |
+## 流程
+
+| 步骤 | 做什么 | 谁做 |
 |------|--------|------|
-| 第 0 步 | 确认素材：读 manifest，写 AGENTS.md 溯源 | 本文档 |
-| 第 1 步 | 判定产物类型与支持范围 | `references/artifact-signals.md` |
-| 第 2 步 | 分析源稿，产出实现方案（2.1 至 2.7 七份产物） | 本文档 |
-| 第 3 步 | 实现：共享骨架、建表与初始数据、插件、并行页面开发 | 本文档 |
-| 第 4 步 | 验收：逐字段对照、逐表计数、逐项功能核对 | 本文档 |
-
-## 禁止事项
-
-| 禁止 | 原因 |
-|------|------|
-| 修改、删除或让构建引用 `source_package/creative/` | 该目录是 UX 权威规格，只读，实现期间要反复对照 |
-| 派 Worker 实现却不带源文件、只给文字概述 | Worker 看不到源码必然按概述重画；必须带源文件并命令读源（见 3.5） |
-| 交付前端写死业务数据的页面 | 稿内示例数据应写入数据库成为初始数据，页面走真实查询 |
-| 改写可见文案、示例数据、条目数量或顺序，或用生成图片替换稿内已有素材 | 默认展示内容和素材也是 UX 规格，不只是布局与配色 |
-| 照抄创意稿里用假逻辑模拟的 AI 能力和飞书能力 | 这类能力必须用真实插件实现（见 2.6 与 plugin-guide skill） |
-| 把可交互控件做成无事件处理、空链接、占位或假成功反馈 | 可见功能必须产生真实、可验证的结果 |
-| 跳过页面清单直接写代码 | 多屏产物不拆清单必然漏页、导航断链 |
-| 对范围外产物（deck 演示稿、纯动画、报表看板）做任何生成或转换 | 产品仅支持产品设计与可交互原型，范围外一律停止并告知 |
-
-## 第 0 步：确认素材
-
-1. 读 `source_package/creative/.upgrade-manifest.json`（字段：`sourceAppId`、`archiveName`、`checkpointId`、`exportedAt`、`fileCount`）。
-2. 目录不存在或为空时，用源应用 ID 重试一次：`miaoda app export <source-app-id> --out source_package/creative --json`；仍失败则告知用户源应用没有可用的设计内容，停止，不要虚构设计稿。
-3. 追加 `AGENTS.md`（不存在则创建）溯源说明：
-
-   > 本应用根据创意设计稿 `<应用名>`（`<sourceAppId>`）生成。`source_package/creative/` 是 UX 权威规格：只读，勿改勿删，勿让构建引用。稿内 `data-miaoda-*` 属性与 `<script type="text/babel">` 是创意平台预览机制，本工程不使用。
-
-## 第 1 步：判定产物类型与支持范围
-
-读 `source_package/creative/index.html`（及 `components/`、`screens/`，若存在），按 `references/artifact-signals.md` 的信号表判定类型。产品仅支持「产品设计」（多屏设计稿、移动端 mockup 等画布类）与「可交互原型」两类；范围外类型（deck 演示稿、纯动画、报表看板）停止：告知用户不支持，不做静态转换、不虚构功能、不产出代码。
-
-## 第 2 步：分析源稿，制定实现方案
-
-方案必须包含 2.1 至 2.7 全部产物，任何一项缺失都不得进入第 3 步。
-
-- 2.1 **页面、路由与导航清单**
-  - 2.1.1 逐屏扫描源稿，为每一屏（每一个画板）规划一个路由页面，并记录该页面的源稿定位。
-  - 2.1.2 产出全局路由表并指定默认页。每条路由写明四项：路径模板、对应页面、每个路由参数的真实来源（哪个接口返回的哪个字段）、入口（用户从哪里到达该路由）。全局路由表是唯一权威：后续所有任务接入路由、编写跳转都以它为准，不得自行发明路径。
-  - 2.1.3 入口规则：每个页面至少有一个入口。带参数的路由，入口必须传入真实数据的参数值（如列表项点击传当前数据的 id）；静态导航项只能指向无参数路由，禁止用占位值（demo、default、写死的 ID）拼路径；需要从导航进入带参数页面时，规划无参数的列表页或在路由表写明取哪条真实数据。
-  - 2.1.4 导航栏、页脚等出现在多个页面上的共享组件单独列出，同样记录源稿定位。
-  - 2.1.5 清单完成后对照源稿逐屏检查：每一屏都有对应页面、每个页面都有入口、每个路由参数都有真实来源；缺任何一项即清单不完整，立即补齐。
-  - 2.1.6 页面拆分、导航项处理、设备框处理的细则见 `references/artifact-signals.md`。
-- 2.2 **主题 token**
-  - 2.2.1 把源稿中的 `:root` CSS 变量或主题常量对象整套提取为工程主题 token，色值、字体、间距保持原值。
-- 2.3 **数据模型与存放位置**
-  - 2.3.1 根据源稿中的数据结构推导数据库表、字段和关联关系，推导方法见 `references/ui-to-function.md`。
-  - 2.3.2 为每一个页面可见的值判定存放位置。存入数据库：需要参与查询、筛选、聚合的值，以及属于单条数据自身内容的视觉值（例如每门课程的封面渐变、每条路径的标识色）。写在前端代码里（组件常量或主题 token）：仅用于展示、集合由设计稿固定、不参与任何后端逻辑的纯视觉值（例如分类的字符图标、装饰 emoji、固定区块配色）。
-  - 2.3.3 统计数字和图表逐项写明展示文案、接口字段、数据库聚合口径和比较周期。文案和口径必须与源稿一致；聚合得出的数值随真实数据变化，不要求等于源稿中的数字。
-- 2.4 **初始数据清单**
-  - 2.4.1 逐页登记每一块默认展示的内容，写明五件事：源稿定位、全部可见字段（文案、字符图标、色值、数值、单位、顺序、默认选中状态）、写入哪张表、经过哪个接口、显示在哪个页面。
-  - 2.4.2 导航、页脚等共享组件的可见内容（项数、文案、顺序）同样登记，不因为不属于某一个页面而遗漏。
-  - 2.4.3 清单登记字段名和源稿定位即可，不把大段源码复制进方案。
-- 2.5 **可见功能清单**
-  - 2.5.1 逐页登记源稿中每一个可交互元素，写明四件事：用户做什么操作、应看到什么结果、经过哪条前后端链路实现、如何验收。
-  - 2.5.2 控件类型与易漏场景的枚举见 `references/ui-to-function.md`。
-- 2.6 **插件能力清单**
-  - 2.6.1 找出源稿中用假逻辑模拟的 AI 能力和飞书能力，逐项登记，实现时调用真实插件。识别信号见 `references/ui-to-function.md`，插件目录与调用规范读取 `plugin-guide` skill。
-  - 2.6.2 数据库和文件存储不是插件，使用平台内置服务。
-- 2.7 **架构边界与验收标准**
-  - 2.7.1 规划 Layout、shared 类型入口和服务端模块入口（路由与导航结构已在 2.1）。
-  - 2.7.2 为每一个后续任务写明允许修改的目录范围；多个并行任务不得修改同一个共享文件。
-  - 2.7.3 为每一个后续任务写一句可验证的完成标准，标准落在真实能力上（如「提交后写入数据库且刷新后仍可见」），不得写成「页面渲染正常」「按钮可以点击」。
-
-**方案完整性门禁**：用模拟、占位、静态展示、仅 Toast、仅记录日志代替真实功能的方案不完整，必须改为真实实现；能力不可用时写明阻塞原因。方案确认后按方案执行，用 TodoWrite 追踪进度。
-
-## 第 3 步：实现
-
-**任务依赖**：
-
-- 串行：3.1 共享骨架、3.2 数据库与初始数据、3.3 插件依次完成，然后进入 3.4。
-- 并行：3.4 的页面任务相互独立、可以并行；每个页面任务只依赖 3.1 的骨架、自己用到的表和初始数据、自己用到的插件；页面任务之间不得互相依赖。
-- 第 4 步验收在全部开发任务完成后进行。
-
-**通用要求**：动手写任何会产生页面可见内容的代码（页面、组件、初始数据、共享组件）之前，必须重新读取对应的源稿定位。探索阶段读过不算数；上下文经过压缩或大量其他实现之后必须重读。
-
-- 3.1 **共享骨架**
-  - 3.1.1 按 2.1 的全局路由表和 2.7 的规划一次性建好全局路由、Layout、shared 类型入口和服务端模块入口；后续任务不得再修改这些共享文件。
-  - 3.1.2 编写导航、页脚等共享组件之前，先读取 2.1.2 登记的源稿定位；组件的项数、文案、顺序必须与源稿一致。
-  - 3.1.3 本任务提交时工程必须可以运行：前端有最小可渲染页面，服务端可以编译启动；不得引用后续任务才会创建的文件。
-- 3.2 **数据库与初始数据**
-  - 3.2.1 按 2.3 的数据模型建表。
-  - 3.2.2 建表完成后立即写入初始数据。按 2.4 清单**一块一块地**处理，每一块都执行同一套动作序列：
-    - 第一步：读取这一块登记的源稿定位，让这段源稿内容出现在当前上下文里。
-    - 第二步：立即把这一块的默认展示内容逐字段原样复制成 INSERT 语句，用 `miaoda db sql` 执行。此时源稿内容就在眼前，照着源稿写，不凭记忆写。不改文案，不换近义词，不改数值和单位，色值保持原样，字符图标保持原字符。
-    - 第三步：用 SELECT 查回刚写入的记录，与第一步读到的源稿逐字段核对（文案、数值、单位、色值、字符图标、顺序）；发现不一致立即修正，核对通过后再处理下一块。
-  - 3.2.3 两条禁止：禁止读完全部源稿后一次性批量写入所有表；禁止不读源稿、凭方案摘要或记忆直接写 INSERT。
-  - 3.2.4 初始数据必须在本步全部写入数据库，进入页面开发之前已经在库。禁止把初始数据做成运行时接口，禁止由页面在浏览器加载时写入数据，禁止依赖第一个访问者触发写入。
-- 3.3 **插件**
-  - 3.3.1 按 2.6 清单逐个创建插件实例，自检参数与调用方式；禁止手工修改 `server/capabilities/` 目录。
-- 3.4 **页面开发**（每个源稿页面一个任务，可并行）
-  - 3.4.1 读取本页的源稿定位对应内容。本任务只读本页源稿定位与相关 shared 契约文件，缺了按需补读，不得重新推导架构。
-  - 3.4.2 实现本页的服务端 service 和 controller：做真实查询、写入和聚合，遵守 2.7 的模块边界，不写只做转发的空壳接口。
-  - 3.4.3 实现本页前端页面：写每个页面和组件之前先读对应源稿定位，按下方视觉还原规则原样还原；页面数据一律来自真实接口调用，禁止在前端写死业务数据。发现本页数据缺失或与源稿不符时，按 3.2.2 的方式补写数据库并在结果中说明，不得在前端内置数据。
-  - 3.4.4 页面内的组件可以并行开发，完成后集成到页面。
-  - 3.4.5 自查：前后端类型一致、shared 契约一致、未越出文件边界；本页每个跳转的路径与参数和 2.1 路由表一致，参数值来自真实数据；把本页源稿值与实现值逐字段并排列出对照。
-- 3.5 **派工规则**
-  - 3.5.1 派给 Worker 的每个任务必须把对应的 `source_package/creative/` 源文件放进 `include_files`。
-  - 3.5.2 任务提示词的第一条指令必须是：先读取该源文件的指定区段，以源码为视觉、文案、布局、数据的唯一权威；提示词文字仅作辅助，与源码冲突时以源码为准。
-  - 3.5.3 禁止只用文字概述替代源文件；禁止在提示词里改写源稿中的文案、数值和字段。
-  - 3.5.4 Worker 完成后回传读取过的源稿定位和验收证据；主 Agent 检查代码本身，不能只凭文字汇报下结论。
-
-### 视觉还原规则（3.1.2 与 3.4.3 遵守）
-
-- 布局用 flex 或 grid 加 gap 直接转写源稿布局，不重新设计。
-- 页面上一切可见内容（文案、条目数量与顺序、示例值与单位、字符图标、色值、选中状态、素材）与源稿逐字段一致。存入数据库的内容经由初始数据和接口到达页面；写在前端的内容直接从源稿代码复制。
-- 字符图标保持原字符，不改成图标库的图标名称。
-- 源稿中已有的图片、SVG 和 CSS 渐变必须复用或等价转写，不得用生成的图片替换。
-- 内联 SVG、文案、字体声明保留；`miaoda.feishu.cn/fonts` 字体镜像在生产环境可用。
-- 确有必要的转换（例如固定画布改响应式）必须在方案中登记转换前后的形态并验证视觉等价；响应式转换不得改变源稿参考尺寸下的构图。
-
-### 可见功能规则（3.4 遵守）
-
-- 源稿中具有交互语义的可见元素必须全部实现；只有源代码和视觉上都明确是装饰的元素可以不实现；不得添加源稿没有展示的功能。
-- 页面跳转、Tab 和弹窗必须到达正确的路由或状态；搜索、筛选、排序、分页的参数必须传入真实查询。
-- 写操作必须走完「前端事件、接口、数据库或外部能力、界面反馈」的完整链路；写入的结果在刷新后必须仍能读到。
-- 持久化的业务结果由服务端校验前提并原子写入，前端只展示重新读取到的事实；可能重复触发的操作要定义重复、并发、超时和中断时的行为。
-- 禁止用没有事件处理的控件、空链接、错误路由、只切换图标、写死的结果或假的成功提示冒充功能完成。
-
-## 第 4 步：验收与完成标准
-
-交付前逐条核验并写进交付说明，任何一条不达标都不算完成：
-
-- 4.1 **页面**：2.1 清单中的页面全部实现，且沿路由表登记的入口实际操作可以到达；导航项的数量、文案、顺序与源稿逐项一致；没有占位页，没有用空状态冒充的正式页。
-- 4.2 **视觉与数据对照**：逐页把源稿和实现并排重读，按 2.4 清单逐字段核对，并列出「源稿值、数据库值、页面渲染值」三列对照；导航、页脚等共享组件单独对照一次。数据库非空、接口 200、条数正确、结构相似都不能代替逐字段核对。
-- 4.3 **初始数据**：对 2.4 清单涉及的每张表执行 COUNT 查询，行数与清单登记的条目数一致；页面首次真实查询即可展示源稿的默认内容，不允许交付空表。
-- 4.4 **可见功能**：按 2.5 清单逐项从页面入口操作核对，用页面实际发送的参数和响应确认达到约定结果；只验证接口成功不算通过。持久化结果验证正常、重复、不满足前提的操作及刷新后重读；插件验证真实调用结果。
-- 4.5 **数据链路**：全部功能走真实查询和写入；前端没有写死的业务数据、没有用 localStorage/sessionStorage 冒充持久化；grep 确认 simulate、setTimeout 写死结果、picsum、假 toast、Math.random 零残留。
-- 4.6 **结果汇报**：报告读取过的源稿定位、逐字段对照结论、功能清单通过情况、必要转换清单、未完成项及原因（没有则写「无」）；不得只报文件列表或笼统声称完成。
-- 4.7 **摘除注入标记**：4.1–4.6 全部通过后执行 `rm -f source_package/creative/.upgrade-manifest.json`。该文件是本指引的注入门控（兼 export 幂等标记与第 0 步信息源，验收通过时后两者已完成使命：溯源已固化进 AGENTS.md，工程侧在应用初始化后也不再重复导出）——删除后本指引停止注入，后续迭代不再受建应用流程干扰；源稿其余文件保留，供以后对照参考。任何一条验收未通过时**不得删除**（下轮修复仍需本指引在场）。
-
-> 注：commit 静态检查（CheckTask）只覆盖编译、类型和 lint，不能证明视觉一致、功能可用和数据持久化，必须按上表逐项自检。
-
-## Common Mistakes
-
-| 错误 | 正确做法 |
-|------|----------|
-| 把设备框（iPhone 壳）实现进产品 UI | 只取框内内容做响应式页面 |
-| 声明用了某接口就当按钮已实现 | 按 2.5 清单逐项检查事件处理、前后端链路和可观察结果 |
-| 生成后仍保留 `source_package/creative/` 的构建引用 | 该目录只读留档，工程代码不依赖它 |
+| 1 | 通读源稿 | 主 Agent |
+| 2 | 业务设计（写入 docs/business-design.md） | 主 Agent |
+| 3 | 基建：结构骨架、建表、初始数据、共享视觉文件、插件实例 | 主 Agent + Worker |
+| 4 | 按业务域派发前后端完整实现 | Worker |
+| 5 | 验收 | 主 Agent + E2E |
+
+### 第 1 步：通读源稿
+
+读取 `source_package/creative/` 下全部页面源文件（index.html、pages/、components/ 等）。该目录只读，是实现期间反复对照的唯一视觉权威；工程代码不得引用它，也不要修改它。稿内 `data-miaoda-*` 属性与 `<script type="text/babel">` 是创意平台预览机制，本工程不使用。
+
+### 第 2 步：业务设计（主 Agent 的核心职责）
+
+从源稿可见信息推断应用的业务模型。完成以下四项分析，**写入工程文件 `docs/business-design.md`**，作为第 3/4/5 步的执行依据：
+
+**2.1 业务域划分**。按「业务模块闭环拆解规则」（见下方规则章节）从源稿划分业务域，产出各域的名称、覆盖的源稿页面与功能、服务端模块归属。
+
+**2.2 数据模型**。以 2.1 划定的业务域为单位设计数据库。源稿页面上的展示数据分两类去向：与服务端逻辑相关的写入数据库、经服务端接口回到页面；不相关的以前端代码的形式展示。按以下顺序执行：
+
+1. **设计表结构**：为每个业务域设计该域的业务实体表，产出表名、字段（含类型）、表间关联。字段以支撑 2.3 的功能为准：筛选器的每个筛选维度要有对应字段，状态流转的状态字段枚举值从源稿可见的状态文案提取，插件结果需落库的（见拆解规则第 4 条）预留对应字段。建模范围按以下两条判据裁剪，**命中任一即入库**：
+
+  - 参与服务端逻辑：查询、筛选、排序、聚合、写入、状态变化；
+  - 属于开放集合实体的页面可见内容：实体会随业务增长（人、内容条目、业务记录等）时，该实体在页面上呈现的一切内容都入库，包含纯展示的长文本与列表——页面按实体标识渲染，写死会让所有实体呈现同一份内容。
+
+  两条都不命中的留在前端代码中：
+
+  - 与页面结构绑定的固定文案：区块标题、页脚文案、静态导航项；
+  - 封闭枚举实体的装饰字段：实体是页面上固定的少数几项且不随业务增长时，其图标、配色不入库；该实体因参与筛选等逻辑而入库时也不带这些字段，由前端按实体标识映射；
+  - 平台内置服务已覆盖的数据（如用户信息、文件存储）不建表，使用内置服务。
+
+2. **确定建表顺序**：存在引用关系的表，被引用的表先建；该顺序供 3.2 建表与 3.3 数据写入按序执行。
+
+3. **标注数据来源**：为第 1 步建模的每张表标注初始数据取自哪个源稿文件、哪个区块；同一张表的数据散落在多个页面时逐条列全。只写位置指针，**设计文档中禁止出现任何初始数据内容**——不写字段值、不写示例记录、不做数据摘要；数据内容只在 3.3 执行时由 Worker 从源稿誊写，设计文档中出现的数据值一律不作为写入依据。
+
+**2.3 可见功能业务模型与 API 设计**。按 2.1 的业务域逐域进行，为每个域产出核心功能清单与接口设计。范围界定：仅涉及页面内交互、不读写业务数据的行为（Tab 切换、折叠展开、弹窗开关、表单字段校验）随页面视觉还原自然实现，不进入本节设计。
+
+对每个业务域依次完成：
+
+1. **识别核心功能**。从该域覆盖的源稿页面中，按以下类型识别核心功能（组件类型与功能信号的对照见 [references/ui-to-function.md](references/ui-to-function.md)）：
+  - 业务数据的写操作：新建、编辑、删除、提交、状态变更；
+  - 影响数据展示范围与形态的读操作：搜索、筛选、排序、分页；
+  - 页面间的业务流转：列表项进详情、详情进编辑等携带真实数据的跳转；
+  - 涉及外部能力的操作：上传、AI 处理、消息通知、定时任务。
+
+   每条功能记录为：「功能名称 + 所在页面 + 用户操作与预期结果」；操作结果需要跳转到另一个页面时一并写明目标页面，目标页面不在源稿里时标注为新增页面，由 3.1 规划路由与占位。
+
+2. **能力选型**。对每条核心功能按以下顺序判定实现方式：
+  - 平台内置服务（用户、文件、权限、消息、自动化/定时）可满足 → 直接使用，标注「使用平台内置服务：[服务名]」，禁止自建同等能力；
+  - 功能涉及 AI、智能、自动生成、大模型、文本生成、图片生成、飞书、消息通知、群组、机器人等能力 → 判定为插件能力，登记进 2.4 做插件设计；普通前后端能可靠实现的不硬凑插件；
+  - 两者都不满足 → 自建服务端 API，进入第 3 条。
+
+   判定插件能力时同时对照源稿代码补漏：用假逻辑模拟、但未以可交互组件呈现的此类能力（如定时提醒、自动通知），一并登记进 2.4。
+
+3. **API 设计**。为自建 API 的功能设计接口：
+  - 同一数据实体的操作合并设计：列表查询一个接口，入参覆盖该页全部筛选维度、搜索关键词与分页参数；新建、更新、删除、详情各一个接口；
+  - 每个接口写明：方法与路径、入参与出参、读写的表、支撑的功能。
+
+本节产出是第 4 步各域任务服务端子步骤的实现范围（域任务的 Service/Controller 按 API 清单逐接口实现），也是第 5 步核心验收目标的选取来源。
+
+**2.4 插件设计（条件步骤，仅当 2.3 判定出插件能力时执行）**。先读取 `plugin-guide` skill 了解插件目录与调用规范，然后对 2.3 登记的插件需求逐项设计。
+
+设计原则：
+
+- **原子化拆分**：一个插件实例只做一件事——不同输出类型（文本/图片/消息）建独立实例，不同业务语义（如标题与正文）建独立实例；
+- **链路完整性**：从用户输入到展示/落库，每一步都有对应插件——链式场景如文档解析→结构化提取需要两个插件；
+- **调用方式选择**：默认前端 capabilityClient 直接调用；以下情形改为服务端调用并说明原因：调用前需验证权限、需记录调用日志、结果需先落库、定时任务或 Webhook 无前端上下文、需聚合多个插件结果。
+
+输出格式，每个插件一行：
+
+| 插件名称 | 基础插件 | 用途 | 调用方式 | 关联页面/接口 | 输入参数 | 输出类型 |
+| --- | --- | --- | --- | --- | --- | --- |
+
+`docs/business-design.md` 写完后，用 TodoWrite 建执行清单，条目至少覆盖：每个基建项、每个业务域实现任务、**验收任务**（此刻即加入清单）。
+
+### 第 3 步：基建
+
+**执行者划分（不可调整）**：凡产出承载源稿可见内容（文案、色值、条目、数值、素材）的，一律派 Worker 实现——Worker 的任务范围窄、开工即按标注读取源稿，写前必然读到原文；主 Agent 亲写的范围只有纯结构骨架与数据库 DDL，这两类没有任何内容取自源稿。初始数据既承载源稿内容、又需要执行 SQL，派 `CodeAct`——它兼具读文件与执行能力，读源与写库在同一上下文内完成。主 Agent 不得亲自编写页面、组件、导航、页脚、主题色板、Service、Controller，也不得凭通读记忆写入任何源稿可见内容。
+
+**派发指令的内容边界（所有派发通用）**：派发指令只写任务目标、源稿位置、验收标准。**禁止在指令里复述源稿的任何具体内容**——色值、文案、条目、名称、数值一律不写，主 Agent 通读源稿形成的记忆不得以任何形式进入指令；Worker 需要的源稿内容由它自己按位置读取。每个派发任务都要带**双权威声明**：视觉、文案、色值、数据以源稿源码为唯一权威，工程契约（路由、表结构、接口、插件实例）以落盘文件为准，指令中的文字描述仅作辅助，与两者冲突时以文件为准——**指令里出现的源稿内容不作为实现依据**。
+
+**3.1 代码架构设计与结构骨架（主 Agent）**。先读取 coding-guide skill 了解项目编码规范与目录结构。本步分先后两段：先完成全部规划，再一次性落盘所有会被多个后续任务共同引用或修改的结构文件；禁止边实现边定结构。
+
+第一段，规划内容：
+
+- 前端目录结构：pages、页面内组件、跨页面公共组件、hooks/api/types/utils 的文件归属，明确入口页文件位置；
+- 路由与导航结构：源稿每个页面一条路由，加上 2.3 记录的新增页面（路径语义化，不用查询参数冒充路由）、默认页、Layout 承载方式与菜单入口；
+- 服务端模块边界：按 2.1 的业务域确定各模块的目录与内部文件结构；
+
+第二段，落盘结构文件——**只落结构，不写任何源稿可见内容**：
+
+- 全局路由配置与默认页；
+- Layout 容器：只搭出页面容器与内容插槽，**不写导航项、logo、搜索框、按钮文案与色值**（这些属于 3.4）；
+- 占位页面：为源稿每个页面与 2.3 记录的新增页面创建最小可渲染的占位页并接入路由，路由挂载不得引用不存在的页面；页面真实内容由第 4 步实现；
+- shared 契约类型：按 2.2 表结构与 2.3 接口设计，定义实体类型和各接口的请求/响应类型；
+- 服务端模块注册骨架：每个业务域一个空 Module + 空 Service/Controller 类，**类体保持为空**——不写任何方法、查询或业务逻辑，这些属于第 4 步域任务。
+
+规则：
+
+- 提交时工程可编译运行，禁止引用后续任务才会创建的页面或模块；
+- 完成后对照源稿检查：每个页面都有路由与目录归属、每个业务域都有模块边界与契约类型，发现缺失在本步补齐；
+
+**3.2 建表（主 Agent）**。按 `docs/business-design.md` 2.2 确定的建表顺序逐张建表，被引用的表先建。表结构取自 2.2 设计，不涉及源稿内容誊写。只建 2.2 建模的表——不参与服务端逻辑的展示数据没有对应表，保留在前端代码中。建完后跑数据库 schema 代码生成刷新 `server/database/schema.ts`：它是真实列名与类型的唯一来源，3.3 的 Worker 无法查库，只能靠这个文件。
+
+**3.3 初始数据插入（派 CodeAct）**。数据内容必须由读到源稿原文的执行者当场写入，读源与写库之间不经过任何交接。
+
+派发对象：`CodeAct`——它同时具备读文件与执行 SQL 的能力，读完源稿即可落库，报错时源稿仍在上下文中可直接改正。
+
+**派发内容**：本次负责的表清单、每张表在 2.2 的源稿位置标注、建表顺序、`server/database/schema.ts` 的路径。
+
+**任务要求**：
+
+- 按标注打开源稿文件、定位到该区块后再写；区块落在文件后段时读到该区块为止，禁止只凭文件开头写数据；
+- 列名与类型照 `server/database/schema.ts`；`_` 前缀的系统字段与主键不写，由数据库默认值生成；
+- 字段值逐字原样来自读到的源稿原文，**这是誊写不是创作**：不改写措辞、不缩写字段值、不换算数值、不增删记录、不补充源稿没有的条目；
+- 源稿里属于该表的可见记录全部写入，一条不漏；同一实体在多个页面出现时按标识字段去重、合并各页可见字段，不重复插入；
+- 子表外键用 `SELECT` 子查询按业务键（标题、名称等）关联父行，禁止硬编码 UUID。
+
+**权限边界**：只允许对 2.2 建模的表执行 `INSERT` 与必要的 `SELECT`。出现 `DDL` / `UPDATE` / `DELETE`、或写入 2.2 未建模的表，均为越界。
+
+达标标准：每张表在源稿页面上可见的记录，首次查询即可返回且内容与源稿一致。禁止把初始数据做成运行时 mock 接口或前端写死。
+
+**3.4 共享视觉文件（派发 Worker，域任务之前串行完成）**。导航、页脚、主题色板承载源稿可见内容，且被所有页面引用，必须由单一 Worker 一次写完，禁止主 Agent 代写、禁止拆给多个域任务并行写。
+
+派发时给出源稿共享组件文件与设计 token 文件的位置，由 Worker 自行读取。任务范围：
+
+- 导航：项数、文案、顺序、logo 形态、搜索框、操作区按钮全部照源稿组件转写；链接先读既定路由文件，只指向已注册路由，无承载页面的项保持不可跳转；
+- 页脚：源稿有页脚的页面共用同一个页脚组件，分栏、项数、文案照抄；
+- 主题文件：源稿设计 token 的色值、字体逐条写入，色值原样，不做近似换算或色彩空间转换。
+
+回传后主 Agent 打开源稿对应位置核对导航项数、文案、顺序与主题色值，不一致立刻退回重做；核对通过后，第 4 步各域页面直接复用这些组件与主题变量，不再逐页另行实现。
+
+**3.5 插件实例（条件步骤，2.4 有产出时执行；主 Agent）**。按 2.4 清单逐个建实例并确认契约，调用代码由第 4 步域任务实现：
+
+1. 调用 `plugin_instance` 工具创建插件实例；禁止手工修改 `server/capabilities/` 目录；
+2. 获取运行时 schema，逐字段确认 inputSchema 与 outputSchema 的字段名、类型、是否必填；
+3. 把实例名与 schema 摘要（字段名、类型、必填）写进该插件所属域的派发指令，供域任务按 schema 编写调用代码。
+
+规则：
+
+- 禁止只创建实例而不在域任务中安排调用代码——未生成调用代码的插件实例是无效的；
+- 域任务编写调用代码时，入参出参的字段名与类型以运行时 schema 为准，禁止从设计文档推测（设计可能与插件实际 schema 不一致）；入参中的动态配置值（接收人、通知模板、阈值等）禁止硬编码，从配置表或平台 API 获取；
+- 插件结果需要持久化时，优先在该域 Service 内调用插件并在同一方法内落库；保持前端调用的，成功后通过已有业务 CRUD 接口保存结果，不为此单独新建 API；
+- 后续任一阶段发现缺插件实例，主 Agent 立即用 `plugin_instance` 工具补建，禁止用 pluginKey 冒充 instanceId 调用或跳过该功能。
+
+### 第 4 步：按业务域派发实现（Worker）
+
+按「业务模块闭环拆解规则」把每个业务域派发为一个 Worker 任务。派发前重读 `docs/business-design.md`，按其中的业务域划分逐域生成任务。
+
+**核心原则**
+
+- 任务范围是该域的前后端完整实现：Service、Controller、页面、组件、接口集成都在同一个任务内；
+- 服务端代码不得摘出来由主 Agent 代写——Worker 跑不了接口测试与运行时日志是预期的，运行时验证统一在第 5 步做；
+- **派发指令不写源稿的具体内容**: 避免实现时没有按照原稿而是按照指令开发。
+
+**每个任务必须携带**：
+
+- 权威文件位置：该域相关的源稿文件、`docs/business-design.md`、该域的 shared 契约文件与既定路由文件——只给路径，禁止用文字概述替代源文件，由 Worker 自行读取；
+- 双权威声明：视觉、文案、布局、数据以源稿源码为唯一权威；表结构、API、插件调用以 `docs/business-design.md` 该域章节为准；
+- 一句话验收标准（acceptance），落在真实能力层（如「提交后经真实接口落库且刷新后可回查」），达标即完成，禁止超出标准的冗余自查。
+
+**任务内执行顺序**
+
+1. 读取 coding-guide 及与本域相关的 skill；
+2. 读源稿该域文件，读 `docs/business-design.md` 该域章节（功能清单、表结构、API 清单）；
+3. 检查 shared 契约与该域表结构、接口设计一致；按 3.1 既定的目录结构落文件，不另建与之平行的目录；
+4. Service 层：业务编排、落库、插件调用聚合、内置服务调用；服务端调用的插件逐条写明「调用 [实例名]，触发条件为 [条件]」；
+5. Controller 层：REST API，按该域 API 清单逐接口实现，避免纯透传接口；
+6. 页面接入既定路由，不改全局结构；
+7. 页面与组件实现：打开源稿对应区段对照实现，文案、色值、条目数量与顺序、示例值照源码转写；页面数据一律来自本域真实接口，禁止 mock 业务数据；组件不拆出独立任务；
+8. 前端插件集成（2.4 设计为前端调用的插件）：获取插件运行时 schema，按 schema 调用 [实例名]；结果需持久化的，调用成功后通过已有业务接口保存；
+9. 代码级自查：类型一致性、契约覆盖、shared 定义对齐；禁止运行时验证（见拆解规则第 7 条）。
+
+指令里给出的文件路径是**必读下限，不是可读上限**：实现中需要的其他工程文件（既有组件、工具函数、全局配置、路由表）一律按需自行读取。禁止的是重新推导架构：不重新规划目录与路由结构、不反复 glob 全工程、不修改允许范围外的文件。
+
+Worker 回传后，主 Agent 至少读一个关键产物文件抽查（页面是否调真实 API、功能链路是否接通）；回传中的「已完成、已验证」不作为核验依据。
+
+**自动化任务**：2.3 中选型为平台自动化内置服务的功能（定时触发、数据变更触发），作为独立任务实现，依赖其用到的表与插件：
+
+1. 读取 trigger-guide skill 了解触发器配置与代码开发规范；
+2. 创建触发器，实现任务逻辑：触发条件判断、去重、插件调用、状态更新；
+3. 完成后验证代码可编译。
+
+
+### 第 5 步：验收（清单里的任务，不是可选动作）
+
+commit 的静态检查只覆盖编译与 lint，证明不了功能可用与视觉一致。验收开始前先读取 testing-guide skill 了解 E2E 验收流程，并重读 `docs/business-design.md`，以其中的 2.3 功能与 API 清单为验收目标来源。按以下结构执行，完成前不得提交收尾：
+
+1. **架构与入口检查**：先对照 3.1 检查路由、shared 契约、模块边界是否被遵守，对照 3.4 检查导航、页脚、主题色值是否与源稿一致，发现偏离先修结构再继续。再做三项核对：
+   - **链接目标可达**：枚举代码中全部跳转目标（导航项、按钮、卡片、搜索、面包屑）与路由表比对，任一指向未注册路由即未通过；
+   - **页面均有入口**：每个已注册页面至少有一个应用内可达入口，只能手输 URL 到达的页面即未通过；
+   - 应用入口页面可正常打开，打不开（白屏 / Page not found）则停止验收，只记录阻塞问题。
+2. **核心验收目标 1~3 个**（超过 3 个属于错误输出）：从 2.3 的功能映射中选取最核心的业务链路，每个目标写成「验收对象 —— 可判定的通过标准」。通过标准必须是应用内可判定的结果：状态更新、提交后列表刷新、成功/失败提示、结果区出现内容或错误态、确认弹窗、详情数据变化；「页面渲染正常」「控件可见」「按钮可点击」不构成通过标准。派发 E2E agent 实际执行这些目标。
+3. **非核心降级范围**：AI 内容质量、真实消息送达、复杂批量数据一致性、导出文件内容正确性、低风险视觉细节可降级不阻塞；但被降级能力在应用内的触发、状态与错误反馈仍必须保留在核心验收目标中，不得完全消失。
+4. **数据核对**：对每张初始数据表做 COUNT 与文案抽查，与源稿对照；条数或文案不符即为未通过。
+5. **静态残留检查**：grep 两类问题，任一命中即未通过——
+   - 假实现：simulate、写死结果的 setTimeout、picsum、假 toast、Math.random 业务值；
+   - 无行为的可点击元素：按钮与带可点击外观的元素是否都有事件处理或路由跳转。
+6. **验收对照表**：把以上结果逐项列出后再提交。未执行的项写明原因，不得笼统声称"验收通过"。
+7. **摘除注入标记**：以上各项全部通过后执行 `rm -f source_package/creative/.upgrade-manifest.json`。该文件是本指引的 SessionStart 注入门控，删除后本指引停止注入，后续迭代不再重复进入升级流程；源稿其余文件保留供以后对照。任一项未通过时不得删除——下轮修复仍需本指引在场。
+
+## 业务模块闭环拆解规则
+
+按业务域（Module）拆分实现任务，每个任务同时覆盖该域的服务端实现（Service + Controller + DTO）与对应前端页面（路由 + 页面 + 组件 + 接口集成），命名为 `[业务模块名]模块开发（含前后端）`。**同一业务域的前后端禁止拆成独立任务**。与通用全栈开发的唯一差异：拆解依据是**创意模式的源稿代码**（页面结构与可见交互组件），而非需求文档。
+
+1. **模块边界判定**：任务拆分优先服从代码所有权边界，而非仅按页面归属或功能语义拆分。若多个页面、功能最终落在同一个 server module 中实现，必须合并为同一个模块任务，不得拆成多个并行任务。
+2. **server module 判定口径**：同一个 server module 包括但不限于同一业务目录下的 Service、Controller、DTO、Repository、模块注册文件、聚合导出文件，以及需要共同修改的 shared 契约文件。
+3. **纯展示/即时场景**：若某业务功能已规划在前端使用插件实现，且不需要数据库存储，则该模块任务中无需包含服务端 Service/Controller 子步骤，仅保留前端 + 插件集成。
+4. **需持久化场景**：若插件调用的结果需要保存到数据库，优先在该模块的 Service 中调用插件并落库；或在已有业务 CRUD 接口中扩展字段接收前端传来的插件结果。禁止为"保存插件结果"单独新建模块。
+5. **平台内置服务**：模块内需使用的平台内置服务，在该模块的 Service 部分完成配置与调用。
+6. **入口模块优先**：将承载入口页（列表页/首页）的模块任务置于全部模块任务的第一项。
+7. **并行安全**：模块任务内**禁止包含运行时验证**（接口冒烟测试、启动前后端服务联调、读取服务端/前端运行时错误日志、E2E 测试），统一推迟到第 5 步验收阶段。允许保留的验证限定为代码级静态自查（类型一致性、契约覆盖、shared 定义对齐）。
+8. **精确依赖**：每个模块任务只依赖基建（结构骨架 + 共享视觉文件 + 自身所需的表与初始数据 + 插件实例）；模块任务之间无数据依赖时全部可并行，禁止链式依赖。
+9. **粒度保底**：单个模块子步骤明显超限时，允许拆为 `[模块名]服务端开发` + `[模块名]前端开发` 两个任务，前端任务依赖同模块服务端任务，仅此一种拆法。
+
+## 视觉一致性规则（全程适用）
+
+- 布局用 flex/grid 加 gap 直接转写源稿结构，不重新设计。
+- 页面一切可见内容（文案、数值与单位、条目数量与顺序、色值、字符图标、选中状态、素材）与源稿逐字段一致：入库的经初始数据与接口到达页面，前端的直接从源稿代码复制。
+- 字符图标保持原字符；源稿已有的图片、SVG、CSS 渐变复用或等价转写，不得用生成图替换。
+- 写任何产生页面可见内容的代码之前，重新打开源稿对应位置读取。
+- 确有必要的转换（如固定画布改响应式）需说明转换前后形态，且不改变源稿参考尺寸下的构图。
+
+## 功能真实性规则（全程适用）
+
+- 写操作必须走完「前端事件 → 接口 → 数据库/插件 → 界面反馈」全链路，写入结果刷新后仍能读到。
+- 搜索、筛选、排序、分页的参数必须传入真实查询；跳转、Tab、弹窗到达正确的路由或状态。
+- **链接目标必须存在**：写任何跳转前先读既定路由文件，目标只能是已注册路由。源稿有入口但应用内无承载页面时，只有两条出路——回到 2.3 的功能记录里补上新增页面并在 3.1 注册路由后实现，或让该元素保持不可跳转；禁止指向未注册路由。
+- 持久化业务结果由服务端校验前提并写入，前端只展示重新读取的事实。
+- 有数据库时禁止用 mock 数据代替真实查询；插件返回值严禁 mock，前端用 capabilityClient 真实调用，或调用集成了插件的真实服务端接口。
+- 自建 HTTP API 不实现 SSE/WebSocket；插件链路的流式输出（outputMode=stream）不受此限。
+- **可点击外观与真实行为必须同时存在**：转写源稿的按钮与可点击元素时，能用 2.3 已设计的接口或既定路由接上的直接接上；接不上的改成非交互形态——去掉指针手型与按钮态、或呈现禁用态，并在回传中列出这些元素与接不上的原因，由主 Agent 决定是否回到 2.3 补设计。禁止保留看起来能点、点了没反应的元素。
+- 禁止：空链接、只切换图标不产生数据变化、写死的"成功"提示。

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

@@ -1,6 +1,6 @@
 ---
 name: lark-apps-db
-description: "Use when 在妙搭沙箱里用 `lark-cli apps +db-*` 管理【当前这个已存在的】妙搭应用的 PostgreSQL 数据库：建表/改表、写或排查 RLS policy、用 +db-execute 执行 SQL（SELECT/DML/DDL）、灌 mock 数据、数据导入导出、dev/online 多环境初始化与发布、DDL 变更历史（changelog）、行级审计（audit）、PITR 时间点恢复、DB 配额。触发词：应用数据库, SQL, 建表, 改表, mock 数据, 示例数据, 数据审计, 变更历史, 数据恢复, PITR, 时间点恢复, 多环境发布, RLS, policy, pgPolicy, 行级权限, 权限策略, 42501, +db-, db-table-list, db-execute."
+description: "Use when 在妙搭沙箱里用 `lark-cli apps +db-*` 管理【当前这个已存在的】妙搭应用的 PostgreSQL 数据库：建表/改表、写或排查 RLS policy、用 +db-execute 执行 SQL（SELECT/DML/DDL）、灌 mock 数据、数据导入导出、Base（多维表格）→应用数据库同步任务（+db-sync-*）、dev/online 多环境初始化与发布、DDL 变更历史（changelog）、行级审计（audit）、PITR 时间点恢复、DB 配额。触发词：应用数据库, SQL, 建表, 改表, mock 数据, 示例数据, 数据审计, 变更历史, 数据恢复, PITR, 时间点恢复, 多环境发布, RLS, policy, pgPolicy, 行级权限, 权限策略, 42501, Base 同步, +db-, db-table-list, db-execute."
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -30,12 +30,12 @@ gate-tools:
 
 ### 高风险写操作审批（exit 10）
 
-`risk: high-risk-write` 的命令（`+db-env-create` / `+db-data-import` / `+db-env-migrate` / `+db-recovery-apply` / `+db-execute`）不带 `--yes` 会 **exit 10** 并返回 `confirmation_required`。处理：
+`risk: high-risk-write` 的命令（`+db-env-create` / `+db-data-import` / `+db-env-migrate` / `+db-recovery-apply` / `+db-execute` / `+db-sync-create/update/delete`）不带 `--yes` 会 **exit 10** 并返回 `confirmation_required`。处理：
 
 1. 识别 exit code=10 且 `error.type=="confirmation_required"`；
 2. 把 `error.risk.action` + 关键参数给用户，明确"高风险/不可逆"，等显式同意；
 3. 同意 → 原始 argv 末尾加 `--yes` 重试；拒绝 → 终止；
-4. 想先看请求 → `--dry-run`（不触发门禁、不需 `--yes`）；发布/恢复先跑对应预览命令（`+db-env-diff` / `+db-recovery-diff`）。
+4. 想先看请求 → `--dry-run`（不触发门禁、不需 `--yes`）；发布/恢复/Base 同步先跑对应预览（`+db-env-diff` / `+db-recovery-diff` / `+db-sync-create --preview`，均免确认）。
 
 **绝不**看到 exit 10 就默认补 `--yes` 静默重试。
 
@@ -44,19 +44,20 @@ gate-tools:
 | 场景 | 首选命令 | 关键规则 |
 |---|---|---|
 | 列表 / 查表结构 | `lark-cli apps +db-table-list --app-id "$app_id"` / `+db-table-get --app-id "$app_id" --table <table>` | 禁止用 `information_schema` / `pg_indexes` 模拟常规结构查询 |
-| 执行 DDL / DML / SELECT | `lark-cli apps +db-execute --app-id "$app_id" --sql "<query>" --yes` | 不自动包事务，原子性自己写 `BEGIN…COMMIT` |
-| 批量导入 CSV / JSON | `lark-cli apps +db-data-import --app-id "$app_id" --file ./<file> --table <table> --yes` | 目标表已存在；表头 / key 与列名完全一致；≤1 MB / ≤5000 行；无 upsert |
-| 批量导出 | `lark-cli apps +db-data-export --app-id "$app_id" --table <table> --output ./<file>` | 格式由 `--output` 扩展名决定（.csv/.json/.sql）；5000 行守卫 + 1 MB 上限 |
-| 表结构变更历史 | `lark-cli apps +db-changelog-list --app-id "$app_id"` | DDL 维度：CREATE / ALTER / DROP / INDEX |
-| 表数据变更历史 | `lark-cli apps +db-audit-status --app-id "$app_id"`；enable / disable / list 另需 `--table <table>` | DML 维度：INSERT / UPDATE / DELETE；需按表启用。两者都禁止直查 `pg_audit` 模拟 |
-| 单库拆 dev/online 多环境（高危） | `lark-cli apps +db-env-create --app-id "$app_id" [--sync-data] --yes` | 不可逆；新建 full_stack 应用一般已自带多环境；执行后必须回读 `+db-table-list --environment dev` 确认结构已同步 |
-| dev→online 结构发布（高危） | `lark-cli apps +db-env-diff --app-id "$app_id"` → `+db-env-migrate --app-id "$app_id" --yes` | 只发布 DDL |
-| PITR 恢复（高危） | `lark-cli apps +db-recovery-diff --app-id "$app_id" --target <时间点>` → `+db-recovery-apply --app-id "$app_id" --target <时间点> --yes` | `--target` 必填；覆盖式不可逆；窗口最长 7 天 |
-| DB 用量 | `lark-cli apps +db-quota-get --app-id "$app_id"` | 查容量、表数、视图数 |
+| 执行 DDL / DML / SELECT | `+db-execute --app-id "$app_id" --sql "<query>" --yes` | 不自动包事务，原子性自己写 `BEGIN…COMMIT` |
+| 批量导入 CSV / JSON | `+db-data-import --app-id "$app_id" --file ./<file> --table <table> --yes` | 目标表已存在；表头 / key 与列名完全一致；≤1 MB / ≤5000 行；无 upsert |
+| 批量导出 | `+db-data-export --app-id "$app_id" --table <table> --output ./<file>` | 格式由 `--output` 扩展名决定（.csv/.json/.sql）；5000 行守卫 + 1 MB 上限 |
+| Base（多维表格）→ 应用数据库同步（高危；本地 csv/json 才走 `+db-data-import`） | `+db-sync-create --app-id "$app_id" --config @sync.json --preview` → 确认后去 `--preview` 加 `--yes`；任务管理 `+db-sync-list/get/enable/disable/update/delete` | 一次只同步**一张 Base 表**；`batch_...` 任务一次性、**不能重新 enable**；enable/disable/update/delete 仅 `streaming_...` |
+| 表结构变更历史 | `+db-changelog-list --app-id "$app_id"` | DDL 维度：CREATE / ALTER / DROP / INDEX |
+| 表数据变更历史 | `+db-audit-status --app-id "$app_id"`；enable / disable / list 另需 `--table <table>` | DML 维度：INSERT / UPDATE / DELETE；需按表启用。两者都禁止直查 `pg_audit` 模拟 |
+| 单库拆 dev/online 多环境（高危） | `+db-env-create --app-id "$app_id" [--sync-data] --yes` | 不可逆；新建 full_stack 应用一般已自带多环境；执行后必须回读 `+db-table-list --environment dev` 确认结构已同步 |
+| dev→online 结构发布（高危） | `+db-env-diff --app-id "$app_id"` → `+db-env-migrate --app-id "$app_id" --yes` | 只发布 DDL |
+| PITR 恢复（高危） | `+db-recovery-diff --app-id "$app_id" --target <时间点>` → `+db-recovery-apply --app-id "$app_id" --target <时间点> --yes` | `--target` 必填；覆盖式不可逆；窗口最长 7 天 |
+| DB 用量 | `+db-quota-get --app-id "$app_id"` | 查容量、表数、视图数 |
 
-**环境**：`--environment dev|online` **默认不传**——省略时由服务端按应用形态自动选分支（多环境应用走 `dev`，未开多环境的走 `online`）；要固定环境才显式传。**唯一会报错的组合是对未开多环境的应用显式传 `--environment dev`**（无 `dev` 分支，报 `Invalid DB Branch`）。旧名 `--env` 已移除，一律用 `--environment`。`+db-env-diff` / `+db-env-migrate`（dev→online 语义）与 `+db-recovery-*`（作用于当前库）没有 `--environment`。
+**环境**：`--environment dev|online` **默认不传**——省略时服务端按应用形态自动选分支（多环境应用走 `dev`，未开多环境走 `online`）；要固定环境才显式传。**唯一会报错的组合是对未开多环境的应用显式传 `dev`**（无 `dev` 分支，报 `Invalid DB Branch`）。旧名 `--env` 已移除。`+db-env-diff` / `+db-env-migrate`（dev→online 语义）与 `+db-recovery-*` 没有 `--environment`。**例外：`+db-sync-*` 不走自动选分支**——省略默认落 **online**；多环境应用建表（`action=create`）必须显式 `--environment dev`，否则撞 online 禁 DDL（`k_dl_4000001`）。
 
-**何时打开 reference**：各命令完整 flags / 分页 / 输出契约、`+db-execute` 多语句与事务语义、导入导出边界与限额、audit/changelog/env/recovery/quota 参数、时间格式、系统表白名单、user_profile 唯一表达式、pg function、JSONB 复杂注释等长尾限制 → 见 [full-reference.md](references/full-reference.md)。
+**何时打开 reference**：各命令完整 flags / 分页 / 输出契约、`+db-execute` 多语句与事务语义、导入导出边界与限额、Base 同步的配置格式与生命周期 / 错误恢复、audit/changelog/env/recovery/quota 参数、时间格式、系统表白名单、user_profile 唯一表达式、pg function、JSONB 复杂注释等长尾限制 → 见 [full-reference.md](references/full-reference.md)。
 
 ## Hard Rules
 
@@ -72,7 +73,7 @@ gate-tools:
 | `--yes` 边界 | 只跳过 CLI 确认关卡，不能代替用户授权 |
 | 线上发布 / 恢复 | `+db-env-migrate` / `+db-recovery-apply` 前先跑 `+db-env-diff` / `+db-recovery-diff` 预览并给用户确认 |
 | 已有数据安全 | 已有表 / 已有数据禁止直接 DROP / DELETE；优先 ALTER / UPDATE；不确定先问用户 |
-| 环境选择 | **默认不传 `--environment`**，由服务端自动选分支；只有已确认应用开了多环境时才显式传 `dev` 验写操作——对未开多环境的应用传 `dev` 必报错 |
+| 环境选择 | 默认不传 `--environment`（服务端自动选分支）；确认应用开了多环境才显式传 `dev` 验写操作 |
 | 平台保留对象 | 禁止创建或修改 `auth`、`users` 等平台保留表；禁止 DROP 平台审计列 |
 | 业务人员字段 | 业务需要“创建人 / 负责人”字段时命名为 `creator` / `owner` / `author`，避免与审计列混淆 |
 | 本地文件路径 | `--file` / `--output` 用工作目录内相对路径；绝对路径或经 `..`/符号链接越出工作目录会被拒 |
@@ -120,13 +121,11 @@ CREATE POLICY "修改本人数据" ON <table>
   );
 ```
 
-建表流程：`+db-table-list/get` 确认不存在或需变更 -> 生成 DDL -> 用户授权 -> `+db-execute --sql "<ddl>" --yes` 执行 -> 插入 mock -> 必要时重跑 codegen 刷新 `schema.ts`。
-
 ## DDL Rules
 
 ### DDL Workflow
 
-1. 先 `lark-cli apps +db-table-list --app-id "$app_id"` 判断表是否存在；已有表再 `+db-table-get --app-id "$app_id" --table <table>` 看 DDL / columns / indexes / comments（`--format pretty` 直接给建表 DDL）。
+1. 先 `+db-table-list` 判断表是否存在；已有表再 `+db-table-get --table <table>` 看 DDL / columns / indexes / comments（`--format pretty` 直接给建表 DDL）。
 2. 生成 DDL 时只写裸表名，不写 `public.` 或 workspace schema。
 3. CREATE TABLE 必须带审计列、RLS、4 条默认 policy；JSONB 字段必须在同一次调用里写 `COMMENT ON COLUMN ... IS '@type { ... }'`。
 4. CREATE TABLE / CREATE INDEX / ALTER TABLE ADD COLUMN 必须带 `IF NOT EXISTS`，避免重复执行失败。
@@ -184,13 +183,13 @@ CREATE POLICY "修改本人数据" ON <table>
 
 测试用户（**只用于数据库 `user_profile` 列**）：`1847292357012580` 张伟、`1847292986161210` 李明、`1838411738368010` 刘洋、`1847292458018820` 赵丽、`1847286122258458` 孙强、`1846114399229988` John Smith、`1847298549409911` Emma Johnson、`1847291727560708` Michael Brown、`1848568929333380` Robert Wilson、`1847751107397639` Maria Garcia。
 
-> ⚠️ 这些是妙搭数字 user_id，**不是飞书 open_id**。禁止传给 `lark-cli apps +role-member-add` / `+role-member-remove` 的 `--users`（只收 `ou_` 开头的 open ID），也禁止传给任何需要 open_id 的飞书接口——传了会被直接拒绝。
+> ⚠️ 这些是妙搭数字 user_id，**不是飞书 open_id**：禁止传给 `+role-member-add/remove` 的 `--users`（只收 `ou_`）或任何要 open_id 的飞书接口。
 
 ### `user_id` / `user_profile`
 
 - `user_id` 是高频写入规则，不是长尾 reference：只能来自上下文明确给定、`env.userId` / `env.user.id`，或上方测试用户列表，禁止编造。
 - 写入 `user_profile` 字段用 `ROW('<user_id>')::user_profile`；更新复合类型时替换整个字段。
-- 查询、过滤、索引 `user_profile` 时只使用 `(field).user_id`；不要依赖 `name` / `email` / `avatar` / `status`。
+- 查询 / 过滤 / 索引只用 `(field).user_id`，不依赖 `name` / `email` 等其它子字段。
 
 ## SELECT Rules
 
@@ -213,13 +212,7 @@ CREATE POLICY "修改本人数据" ON <table>
 | UPDATE | 必须有明确 WHERE，禁止无条件 UPDATE；用户说"修改 / 更新 / 改一下"数据时用 UPDATE，禁止 DELETE + INSERT；修改业务字段时同步 `_updated_at = CURRENT_TIMESTAMP` 和 `_updated_by`；影响范围不明先 `SELECT count(*)` 给用户确认 |
 | DELETE / TRUNCATE | 当前会话中 Agent 自己插入的 mock 可删；已有表 / 已有数据默认禁止，必须先 `SELECT count(*)` 展示命中行数并取得用户明确授权；`TRUNCATE` 影响整表，视同高风险删除 |
 
-```sql
-INSERT INTO task (title, status, assignee, _created_by, _updated_by)
-VALUES
-  ('梳理需求', 'open', ROW('1847292357012580')::user_profile, ROW('1847292357012580')::user_profile, ROW('1847292357012580')::user_profile),
-  ('完成设计', 'doing', ROW('1847292986161210')::user_profile, ROW('1847292357012580')::user_profile, ROW('1847292357012580')::user_profile)
-ON CONFLICT (title) DO NOTHING;
-```
+`user_profile` 列的 INSERT / UPDATE 写法示例见 [full-reference.md](references/full-reference.md) 的 `user_profile` compound type 一节。
 
 ## Import / Export