@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.b2f659e → 0.1.0-dev.c8cc2b5

package/miaoda/charts-skill/SKILL.md

@@ -5,7 +5,7 @@ description: "shadcn/ui + ReactECharts 图表开发规范。Use when creating or
 
 ## L0 基础配置
 
-- **库**: `import ReactECharts from 'echarts-for-react'` (v5.6.0)
+- **库**: `import ReactECharts from 'echarts-for-react'` (echarts v6.1.x)
 - **主题**: `theme="ud"`
 - **颜色**: 🚨 只能用 hex（如 `#1890ff`），禁止 hsl/rgb
 - **高度**: ≥300px (`className='h-[300px]'`)

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

@@ -12,70 +12,67 @@ workspace-contains:
 
 1. **视觉与源稿一致**：每个页面的文案、数值、色值、条目与顺序与设计稿逐字段一致。
 2. **可见功能真实可用**：设计稿上每个可交互组件（可点、可输入、可筛选）都产生真实、闭环的结果。
+3. **数据动态可变**：会随业务数据而变的内容一律由业务事实现场算出——禁止前端写死常量、接口返回字面量、库内预置统计字段或独立统计快照。业务事实变化后，所有相关页面重新查询都得到一致的新结果；算出的值与源稿数字不一致是预期结果，只对齐单位与格式。
 
 两条核心规则：**一切视觉内容直接从源稿代码照抄，不经过任何文字转述**；**动手实现前先完成业务设计并写入 `docs/business-design.md`，后续每个阶段以该文件为执行依据**。
 
-## 流程
-
-| 步骤 | 做什么 | 谁做 |
-|------|--------|------|
-| 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">` 是创意平台预览机制，本工程不使用。
+读取 `source_package/creative/` 下全部页面源文件（index.html、pages/、components/ 等）。该目录只读，是实现期间反复对照的唯一视觉权威；工程代码不得引用它，也不要修改它。
 
 ### 第 2 步：业务设计（主 Agent 的核心职责）
 
-从源稿可见信息推断应用的业务模型。完成以下四项分析，**写入工程文件 `docs/business-design.md`**，作为第 3/4/5 步的执行依据：
+从源稿可见信息推断应用的业务模型。完成以下四项设计并通过门禁，**写入工程文件 `docs/business-design.md`**，作为第 3/4/5 步的执行依据：
 
-**2.1 业务域划分**。按「业务模块闭环拆解规则」（见下方规则章节）从源稿划分业务域，产出各域的名称、覆盖的源稿页面与功能、服务端模块归属。
+**2.1 业务域划分**。按「业务模块闭环拆解规则」（见下方规则章节）从源稿划分业务域，产出各域的名称、覆盖的源稿页面与功能、服务端模块归属。候选业务域包含多个可独立闭环的子业务，或预计单个 Worker 难以一次完整实现时，继续拆为更小的业务域；每个子域仍包含完整的前后端闭环。
 
-**2.2 数据模型**。以 2.1 划定的业务域为单位设计数据库。源稿页面上的展示数据分两类去向：与服务端逻辑相关的写入数据库、经服务端接口回到页面；不相关的以前端代码的形式展示。按以下顺序执行：
+同时单列「全局 Layout 与跨页面公共组件」清单：登记导航、侧栏、页眉、页脚等全局框架，以及被两个以上页面共同使用或重复出现的组件，并记录源稿文件和使用页面。该清单是共享视觉资产，不是业务域，不纳入任何域任务，在公共视觉层统一实现。
 
-1. **设计表结构**：为每个业务域设计该域的业务实体表，产出表名、字段（含类型）、表间关联。字段以支撑 2.3 的功能为准：筛选器的每个筛选维度要有对应字段，状态流转的状态字段枚举值从源稿可见的状态文案提取，插件结果需落库的（见拆解规则第 4 条）预留对应字段。建模范围按以下两条判据裁剪，**命中任一即入库**：
+**2.2 数据模型**。以 2.1 划定的业务域为单位，先设计合理的业务数据模型，再单独规划初始数据。表结构设计不承担视觉内容分流职责，不得为了复刻某个页面或某组展示值而增删实体和字段。
 
-  - 参与服务端逻辑：查询、筛选、排序、聚合、写入、状态变化；
-  - 属于开放集合实体的页面可见内容：实体会随业务增长（人、内容条目、业务记录等）时，该实体在页面上呈现的一切内容都入库，包含纯展示的长文本与列表——页面按实体标识渲染，写死会让所有实体呈现同一份内容。
+1. **设计表结构**：从业务对象、行为和生命周期识别实体，产出表名、业务含义、字段（含类型与语义）、主键与业务唯一键、表间关系及基数、状态与时间字段、必要约束。按以下不变量建模：
+   - 一个实体具有可解释的业务身份或生命周期；页面、卡片、图表不是实体边界，禁止按页面或展示区块机械建表；
+   - 字段保存原子业务事实，关系通过稳定标识表达；多值关系、历史记录和状态流转按其业务语义建关系表或历史表，不用展示字符串代替关联；
+   - 对业务唯一性、引用完整性、必填、合法枚举、数值范围和不允许重复的关系设置相应约束；索引服务于 2.3 的查询、筛选、排序和关联；
+   - 表结构与 2.3 相互校验：每个持久化写操作有承载实体，每个查询条件有明确事实字段，需持久化的插件结果归属到对应业务实体；平台内置服务已管理的数据不重复建表；
+   - **派生数据不作为独立真源**：会随业务事实变化的统计值、汇总值、进度、余额、排名、趋势和状态概览，不设冗余字段，不为展示单独建立统计或快照记录，由 2.3 的接口基于事实现场计算。同一业务概念跨页面复用同一事实来源和计算口径；
+   - 只有当汇总或快照本身具有独立业务身份、生命周期，并且 2.3 定义了它的真实生成、更新和消费链路时，才作为业务实体建模；“页面需要展示”不构成建表理由。
 
-  两条都不命中的留在前端代码中：
+2. **确定建表顺序**：存在引用关系的表，被引用的表先建；该顺序只服务于后续建表和初始数据写入，不改变实体边界。
 
-  - 与页面结构绑定的固定文案：区块标题、页脚文案、静态导航项；
-  - 封闭枚举实体的装饰字段：实体是页面上固定的少数几项且不随业务增长时，其图标、配色不入库；该实体因参与筛选等逻辑而入库时也不带这些字段，由前端按实体标识映射；
-  - 平台内置服务已覆盖的数据（如用户信息、文件存储）不建表，使用内置服务。
+3. **规划初始数据**：表结构确定后，再为需要种子数据的表标注源稿中的业务事实记录位置和字段映射。该部分与表结构分开书写：
+   - 只标注源稿文件、区块和字段到表字段的映射；同一实体散落在多个页面时列全位置并按稳定业务标识合并；
+   - 源稿展示格式与存储类型不同时，写明格式解析和单位、枚举、时间的转换规则；初始数据写入严格按该规则执行，不自行改变语义；
+   - 只使用源稿明确给出的业务事实，不补充源稿没有的字段值、记录或关系；源稿只有汇总数字而没有对应事实时，不将汇总数字作为初始数据，也不编造明细凑数；
+   - `docs/business-design.md` 只写来源位置和映射规则，**禁止写实际初始值、示例记录或数据摘要**；实际值由负责初始数据写入的 CodeAct 重新读取源稿后写入。
 
-2. **确定建表顺序**：存在引用关系的表，被引用的表先建；该顺序供 3.2 建表与 3.3 数据写入按序执行。
+**2.3 可见功能业务模型与 API 设计**。按 2.1 的业务域逐域进行，为每个域产出核心功能清单与接口设计。
 
-3. **标注数据来源**：为第 1 步建模的每张表标注初始数据取自哪个源稿文件、哪个区块；同一张表的数据散落在多个页面时逐条列全。只写位置指针，**设计文档中禁止出现任何初始数据内容**——不写字段值、不写示例记录、不做数据摘要；数据内容只在 3.3 执行时由 Worker 从源稿誊写，设计文档中出现的数据值一律不作为写入依据。
+对每个业务域依次完成：
 
-**2.3 可见功能业务模型与 API 设计**。按 2.1 的业务域逐域进行，为每个域产出核心功能清单与接口设计。范围界定：仅涉及页面内交互、不读写业务数据的行为（Tab 切换、折叠展开、弹窗开关、表单字段校验）随页面视觉还原自然实现，不进入本节设计。
+1. **识别核心功能**。以源稿的可点控件为识别依据：每个可点控件必须归入一条核心功能，功能内容取该控件的预期结果。识别前先读 `.agent/skills/creative-to-fullstack/references/ui-to-function.md`，按其中「UI→功能映射表」与「UI→capability 常见信号示例」对照组件类型与功能信号。
 
-对每个业务域依次完成：
+   **按功能族登记，不做逐控件矩阵**：触发语义、输入、结果和状态变化相同，仅作用对象不同的重复控件合并为一条功能；不同页面复用同一能力时也只登记一次，并列出覆盖页面。不同结果、不同状态变化或不同目标页面的控件不得因文案相近而合并。源稿未展示也未暗示的功能不补造。
 
-1. **识别核心功能**。从该域覆盖的源稿页面中，按以下类型识别核心功能（组件类型与功能信号的对照见 [references/ui-to-function.md](references/ui-to-function.md)）：
-  - 业务数据的写操作：新建、编辑、删除、提交、状态变更；
-  - 影响数据展示范围与形态的读操作：搜索、筛选、排序、分页；
-  - 页面间的业务流转：列表项进详情、详情进编辑等携带真实数据的跳转；
-  - 涉及外部能力的操作：上传、AI 处理、消息通知、定时任务。
+   每条功能记录为：「功能名称 + 覆盖页面 + 触发方式与输入 + 用户可见结果 + 状态变化或目标页面」。操作结果需要跳转到另一个页面时一并写明目标页面，目标页面不在源稿里时标注为新增页面，在共享结构骨架中补齐路由与页面壳。业务设计只写功能族；逐个控件的覆盖关系在 2.5 通过源稿反查校验，只有漏项才展开记录。
 
-   每条功能记录为：「功能名称 + 所在页面 + 用户操作与预期结果」；操作结果需要跳转到另一个页面时一并写明目标页面，目标页面不在源稿里时标注为新增页面，由 3.1 规划路由与占位。
+   **源稿未画出点击后的页面不构成豁免**：该控件仍识别为核心功能，目标页面按新增页面登记。可点控件是否构成核心功能存疑时，按构成处理。
 
 2. **能力选型**。对每条核心功能按以下顺序判定实现方式：
+  - 预期结果仅为同一页面内的呈现变化，不涉及库内数据与外部能力 → 随页面视觉还原实现，不设接口，不进第 3 条；
   - 平台内置服务（用户、文件、权限、消息、自动化/定时）可满足 → 直接使用，标注「使用平台内置服务：[服务名]」，禁止自建同等能力；
   - 功能涉及 AI、智能、自动生成、大模型、文本生成、图片生成、飞书、消息通知、群组、机器人等能力 → 判定为插件能力，登记进 2.4 做插件设计；普通前后端能可靠实现的不硬凑插件；
-  - 两者都不满足 → 自建服务端 API，进入第 3 条。
+  - 以上都不满足 → 自建服务端 API，进入第 3 条。
 
-   判定插件能力时同时对照源稿代码补漏：用假逻辑模拟、但未以可交互组件呈现的此类能力（如定时提醒、自动通知），一并登记进 2.4。
+   判定时对照源稿补漏，两种都登记进 2.4：以假逻辑模拟、未以可交互组件呈现的（定时提醒、自动通知）；把智能产出画成已完成结果的（已生成的摘要、已提取的条目、带 AI 标记的内容块）。判据是这段内容真实使用中由谁产生——由模型产生就不能当初始数据誊写入库。
 
 3. **API 设计**。为自建 API 的功能设计接口：
   - 同一数据实体的操作合并设计：列表查询一个接口，入参覆盖该页全部筛选维度、搜索关键词与分页参数；新建、更新、删除、详情各一个接口；
-  - 每个接口写明：方法与路径、入参与出参、读写的表、支撑的功能。
+  - 随业务数据而变的出参必须在接口条目内就地写明「事实来源 + 计算/筛选口径 + 哪类事实写入会使它变化」；共用同一口径的多个出参可合并说明，不另建全量数据血缘矩阵；
+  - 派生出参只能从事实表或真实外部能力结果计算，禁止读取为展示而单独预置的统计/快照记录；事实写入成功后，相关查询不得依赖人工同步第二套数据；
+  - 每个接口写明：方法与路径、入参与出参、读写的表、支撑的功能；字段类型、业务语义和必要的格式转换与 2.2 保持一致，不另起一套。
 
-本节产出是第 4 步各域任务服务端子步骤的实现范围（域任务的 Service/Controller 按 API 清单逐接口实现），也是第 5 步核心验收目标的选取来源。
+本节产出是第 4 步各域任务服务端子步骤的实现范围（域任务的 Service/Controller 按 API 清单逐接口实现），也是第 5 步验收目标的选取来源。
 
 **2.4 插件设计（条件步骤，仅当 2.3 判定出插件能力时执行）**。先读取 `plugin-guide` skill 了解插件目录与调用规范，然后对 2.3 登记的插件需求逐项设计。
 
@@ -90,38 +87,40 @@ workspace-contains:
 | 插件名称 | 基础插件 | 用途 | 调用方式 | 关联页面/接口 | 输入参数 | 输出类型 |
 | --- | --- | --- | --- | --- | --- | --- |
 
+**2.5 业务设计门禁（主 Agent，进入第 3 步前执行）**。门禁只检查通用不变量，不要求输出逐控件矩阵或全量血缘表。逐条检查并在 `docs/business-design.md` 末尾记录五项结论；通过项只写一句依据，失败项列出具体漏项并修正设计，全部通过前禁止建表或派发实现：
+
+1. **交互覆盖**：从全部源稿页面反查 `button`、链接、表单、筛选、Tab、行操作和其他可点外观，每个都能归入 2.3 的某个功能族；重复实例只核对是否复用同一行为，不逐项写入设计文档。不存在因“目标页没画”“接口还没有”而取消的可见功能。
+2. **闭环成立**：每个功能族都有明确输入、用户可见结果、状态变化或目标页面；写操作包含真实写入、反馈和重新读取，失败时有可理解、可恢复的反馈。
+3. **模型合理**：每张表都能说明对应业务实体及生命周期；主键、业务唯一键、关系基数、引用完整性、状态和必要约束齐全，不按页面或展示区块机械建表，不用展示字符串代替实体关系。
+4. **数据可推导**：每个动态出参都在所属接口内写清事实来源、口径和变化触发；不存在仅为页面展示而保存的派生字段、统计表或快照记录，不存在为凑源稿数字而编造的业务事实。
+5. **单一真源**：同一业务概念跨页面、接口和状态流转使用同一事实来源与口径；不存在需要人工双写、定时补齐或前端自行修正才能一致的第二套数据。
+
 `docs/business-design.md` 写完后，用 TodoWrite 建执行清单，条目至少覆盖：每个基建项、每个业务域实现任务、**验收任务**（此刻即加入清单）。
 
 ### 第 3 步：基建
 
-**执行者划分（不可调整）**：凡产出承载源稿可见内容（文案、色值、条目、数值、素材）的，一律派 Worker 实现——Worker 的任务范围窄、开工即按标注读取源稿，写前必然读到原文；主 Agent 亲写的范围只有纯结构骨架与数据库 DDL，这两类没有任何内容取自源稿。初始数据既承载源稿内容、又需要执行 SQL，派 `CodeAct`——它兼具读文件与执行能力，读源与写库在同一上下文内完成。主 Agent 不得亲自编写页面、组件、导航、页脚、主题色板、Service、Controller，也不得凭通读记忆写入任何源稿可见内容。
+共享结构骨架完成后，主 Agent 完成建表并生成 schema，再同批并发派发三项：公共视觉层 Worker、初始数据 CodeAct、插件实例 Worker（2.4 有产出时）。三项全部完成后，派发所有无数据依赖的业务域 Worker 并发开发，验收前必须全部完成。
 
-**派发指令的内容边界（所有派发通用）**：派发指令只写任务目标、源稿位置、验收标准。**禁止在指令里复述源稿的任何具体内容**——色值、文案、条目、名称、数值一律不写，主 Agent 通读源稿形成的记忆不得以任何形式进入指令；Worker 需要的源稿内容由它自己按位置读取。每个派发任务都要带**双权威声明**：视觉、文案、色值、数据以源稿源码为唯一权威，工程契约（路由、表结构、接口、插件实例）以落盘文件为准，指令中的文字描述仅作辅助，与两者冲突时以文件为准——**指令里出现的源稿内容不作为实现依据**。
+**3.1 共享结构骨架（主 Agent）**。先读取 coding-guide skill 了解项目规范，再依据 `docs/business-design.md` 基于现有工程一次性补齐后续任务共同依赖的最小结构：
 
-**3.1 代码架构设计与结构骨架（主 Agent）**。先读取 coding-guide skill 了解项目编码规范与目录结构。本步分先后两段：先完成全部规划，再一次性落盘所有会被多个后续任务共同引用或修改的结构文件；禁止边实现边定结构。
+- 确定页面、业务域及 2.1 共享视觉资产的代码目录归属；为每个源稿页面和 2.3 记录的新增页面补齐语义化路由，复用已有页面壳，只为缺失页面创建最小可渲染页面壳；
+- 配置默认页，以及包含页面内容容器和路由出口的 Layout 骨架；
+- 按 2.2 和 2.3 定义 shared 实体类型及 API 请求/响应契约；
+- 按 2.1 为每个业务域注册空 Module、Service 和 Controller 骨架。
 
-第一段，规划内容：
+完成后确认工程可编译，且每个页面都有路由和目录归属、每项共享视觉资产都有目标目录、每个业务域都有模块边界与 shared 契约。
 
-- 前端目录结构：pages、页面内组件、跨页面公共组件、hooks/api/types/utils 的文件归属，明确入口页文件位置；
-- 路由与导航结构：源稿每个页面一条路由，加上 2.3 记录的新增页面（路径语义化，不用查询参数冒充路由）、默认页、Layout 承载方式与菜单入口；
-- 服务端模块边界：按 2.1 的业务域确定各模块的目录与内部文件结构；
+**3.2 建表（主 Agent）**。确认 2.5 五项门禁全部通过后，按 `docs/business-design.md` 2.2 确定的建表顺序逐张建表，被引用的表先建。表结构取自 2.2 设计，不涉及源稿内容誊写。只建真实业务实体和关系表；仅服务于页面展示的派生字段、统计表、排行表、趋势表或快照表不得创建，除非 2.2 已证明它本身是具有真实生成和更新链路的业务实体。建完后跑数据库 schema 代码生成刷新 `server/database/schema.ts`，后续 CodeAct 与业务域 Worker 均以该文件中的真实列名和类型为准。
 
-第二段，落盘结构文件——**只落结构，不写任何源稿可见内容**：
+**3.3 全局 Layout 与跨页面公共组件（派发 Worker）**。按共享视觉资产清单读取对应源稿，写入共享结构骨架确定的目标目录，只实现全局视觉框架和跨页面复用的展示组件：
 
-- 全局路由配置与默认页；
-- Layout 容器：只搭出页面容器与内容插槽，**不写导航项、logo、搜索框、按钮文案与色值**（这些属于 3.4）；
-- 占位页面：为源稿每个页面与 2.3 记录的新增页面创建最小可渲染的占位页并接入路由，路由挂载不得引用不存在的页面；页面真实内容由第 4 步实现；
-- shared 契约类型：按 2.2 表结构与 2.3 接口设计，定义实体类型和各接口的请求/响应类型；
-- 服务端模块注册骨架：每个业务域一个空 Module + 空 Service/Controller 类，**类体保持为空**——不写任何方法、查询或业务逻辑，这些属于第 4 步域任务。
-
-规则：
+- 在 Layout 骨架上实现并装配导航、侧栏、页眉、页脚等全局框架，对齐源稿的结构、固定文案、色值、字体、间距和内容区域约束；导航目标只使用已注册路由；
+- 每个跨页面公共组件只实现一份。固定文案、图标和视觉结构照源稿实现；业务实体、状态和动态值改为由 props 传入，业务操作通过事件回调暴露，不在公共组件内调用业务 API、插件或维护领域状态；
+- 页面专属组件和页面内容不在本步实现，由所属业务域任务完成。
 
-- 提交时工程可编译运行，禁止引用后续任务才会创建的页面或模块；
-- 完成后对照源稿检查：每个页面都有路由与目录归属、每个业务域都有模块边界与契约类型，发现缺失在本步补齐；
+完成后确认全局 Layout 已实际挂载、所有路由页面使用同一套全局框架、公共组件可被域任务直接引用且工程可编译；只创建组件文件但未接入应用不算完成。
 
-**3.2 建表（主 Agent）**。按 `docs/business-design.md` 2.2 确定的建表顺序逐张建表，被引用的表先建。表结构取自 2.2 设计，不涉及源稿内容誊写。只建 2.2 建模的表——不参与服务端逻辑的展示数据没有对应表，保留在前端代码中。建完后跑数据库 schema 代码生成刷新 `server/database/schema.ts`：它是真实列名与类型的唯一来源，3.3 的 Worker 无法查库，只能靠这个文件。
-
-**3.3 初始数据插入（派 CodeAct）**。数据内容必须由读到源稿原文的执行者当场写入，读源与写库之间不经过任何交接。
+**3.4 初始数据插入（**必须**派 `CodeAct` 执行）**。数据内容**必须**由读到源稿原文的执行者当场写入，读源与写库之间不经过任何交接——**通读阶段读过源稿不算**，隔了若干轮之后凭记忆写出的记录必然是编造的。
 
 派发对象：`CodeAct`——它同时具备读文件与执行 SQL 的能力，读完源稿即可落库，报错时源稿仍在上下文中可直接改正。
 
@@ -131,29 +130,19 @@ workspace-contains:
 
 - 按标注打开源稿文件、定位到该区块后再写；区块落在文件后段时读到该区块为止，禁止只凭文件开头写数据；
 - 列名与类型照 `server/database/schema.ts`；`_` 前缀的系统字段与主键不写，由数据库默认值生成；
-- 字段值逐字原样来自读到的源稿原文，**这是誊写不是创作**：不改写措辞、不缩写字段值、不换算数值、不增删记录、不补充源稿没有的条目；
-- 源稿里属于该表的可见记录全部写入，一条不漏；同一实体在多个页面出现时按标识字段去重、合并各页可见字段，不重复插入；
+- 字段值来自读到的源稿业务事实，**这是映射不是创作**：除 2.2 初始数据规划明确声明的格式与类型转换外，不改写语义、不增删记录、不补充源稿没有的字段值或关系；
+- 只写具有独立业务身份、能参与查询或状态变化的源稿事实记录；KPI、汇总、趋势、占比、排名、进度、余额等派生展示值不作为初始记录写入，源稿事实不足时不得编造明细使其对上；
+- 素材字段写本应用内取得到的地址：源稿的引用指向源应用运行时存储，本应用取不到时，生成替代图后写它的地址；
+- 2.2 初始数据规划标注的业务事实记录全部写入，一条不漏；同一实体在多个页面出现时按稳定业务标识去重并合并已明确的事实字段，不重复插入；
 - 子表外键用 `SELECT` 子查询按业务键（标题、名称等）关联父行，禁止硬编码 UUID。
 
-**权限边界**：只允许对 2.2 建模的表执行 `INSERT` 与必要的 `SELECT`。出现 `DDL` / `UPDATE` / `DELETE`、或写入 2.2 未建模的表，均为越界。
-
-达标标准：每张表在源稿页面上可见的记录，首次查询即可返回且内容与源稿一致。禁止把初始数据做成运行时 mock 接口或前端写死。
-
-**3.4 共享视觉文件（派发 Worker，域任务之前串行完成）**。导航、页脚、主题色板承载源稿可见内容，且被所有页面引用，必须由单一 Worker 一次写完，禁止主 Agent 代写、禁止拆给多个域任务并行写。
-
-派发时给出源稿共享组件文件与设计 token 文件的位置，由 Worker 自行读取。任务范围：
+达标标准：2.2 初始数据规划中的每条业务事实均按映射写入，表间关系正确，首次查询可返回且业务语义与源稿一致。禁止把初始数据做成运行时 mock 接口或前端写死；页面视觉是否完整由页面实现与验收单独检查。
 
-- 导航：项数、文案、顺序、logo 形态、搜索框、操作区按钮全部照源稿组件转写；链接先读既定路由文件，只指向已注册路由，无承载页面的项保持不可跳转；
-- 页脚：源稿有页脚的页面共用同一个页脚组件，分栏、项数、文案照抄；
-- 主题文件：源稿设计 token 的色值、字体逐条写入，色值原样，不做近似换算或色彩空间转换。
+**3.5 插件实例（条件步骤，2.4 有产出时执行；派发 Worker）**。整份 2.4 清单交给一个 Worker 建实例并确认契约，调用代码由所属业务域任务实现：
 
-回传后主 Agent 打开源稿对应位置核对导航项数、文案、顺序与主题色值，不一致立刻退回重做；核对通过后，第 4 步各域页面直接复用这些组件与主题变量，不再逐页另行实现。
-
-**3.5 插件实例（条件步骤，2.4 有产出时执行；主 Agent）**。按 2.4 清单逐个建实例并确认契约，调用代码由第 4 步域任务实现：
-
-1. 调用 `plugin_instance` 工具创建插件实例；禁止手工修改 `server/capabilities/` 目录；
+1. 调用 `plugin_instance` 工具创建插件实例，彼此无依赖的实例在同一批次并发创建，只有输出需作为下一实例入参的链式实例才顺序建；禁止手工修改 `server/capabilities/` 目录；
 2. 获取运行时 schema，逐字段确认 inputSchema 与 outputSchema 的字段名、类型、是否必填；
-3. 把实例名与 schema 摘要（字段名、类型、必填）写进该插件所属域的派发指令，供域任务按 schema 编写调用代码。
+3. 回传每个实例的实例名与 schema 摘要（字段名、类型、必填）。主 Agent 把摘要写进该插件所属域的派发指令，供域任务按 schema 编写调用代码。
 
 规则：
 
@@ -164,36 +153,42 @@ workspace-contains:
 
 ### 第 4 步：按业务域派发实现（Worker）
 
-按「业务模块闭环拆解规则」把每个业务域派发为一个 Worker 任务。派发前重读 `docs/business-design.md`，按其中的业务域划分逐域生成任务。
+确认全局 Layout、跨页面公共组件、初始数据和所需插件实例全部完成后，按「业务模块闭环拆解规则」把每个业务域派发为一个 Worker 任务。派发前重读 `docs/business-design.md`，按其中的业务域划分逐域生成任务。
 
 **核心原则**
 
-- 任务范围是该域的前后端完整实现：Service、Controller、页面、组件、接口集成都在同一个任务内；
+- 任务范围是该域的前后端完整实现：Service、Controller、页面内容、页面专属组件与接口集成都在同一个任务内；共享结构骨架、全局 Layout 与跨页面公共组件不在域任务中重复实现；
 - 服务端代码不得摘出来由主 Agent 代写——Worker 跑不了接口测试与运行时日志是预期的，运行时验证统一在第 5 步做；
 - **派发指令不写源稿的具体内容**: 避免实现时没有按照原稿而是按照指令开发。
 
 **每个任务必须携带**：
 
 - 权威文件位置：该域相关的源稿文件、`docs/business-design.md`、该域的 shared 契约文件与既定路由文件——只给路径，禁止用文字概述替代源文件，由 Worker 自行读取；
-- 双权威声明：视觉、文案、布局、数据以源稿源码为唯一权威；表结构、API、插件调用以 `docs/business-design.md` 该域章节为准；
-- 一句话验收标准（acceptance），落在真实能力层（如「提交后经真实接口落库且刷新后可回查」），达标即完成，禁止超出标准的冗余自查。
+- 双权威声明：视觉结构、固定文案、布局与呈现格式以源稿源码为唯一权威；业务数据以真实接口返回为准；表结构、API、插件调用以 `docs/business-design.md` 该域章节为准；
+- 全局 Layout 与公共组件位置：全局框架已统一接入，域任务只填充页面内容；公共组件直接 import，**禁止在页面内重新实现同名组件**；清单之外且只属于本域的组件才在页面内实现；
+- 一句话验收标准（acceptance），落在真实能力层（如「提交后经真实接口落库且刷新后可回查」），达标即完成，禁止超出标准的冗余自查；
+- 只写任务目标、源稿位置、验收标准，源稿的具体内容由 Worker 按位置自己读；
+- 让 Worker 在开工前感知到「任务内执行顺序」以及「视觉一致性」「功能真实性」两节规则。
 
 **任务内执行顺序**
 
 1. 读取 coding-guide 及与本域相关的 skill；
 2. 读源稿该域文件，读 `docs/business-design.md` 该域章节（功能清单、表结构、API 清单）；
-3. 检查 shared 契约与该域表结构、接口设计一致；按 3.1 既定的目录结构落文件，不另建与之平行的目录；
+3. 检查 shared 契约与该域表结构、接口设计一致；按既定目录结构落文件，不另建与之平行的目录；
 4. Service 层：业务编排、落库、插件调用聚合、内置服务调用；服务端调用的插件逐条写明「调用 [实例名]，触发条件为 [条件]」；
 5. Controller 层：REST API，按该域 API 清单逐接口实现，避免纯透传接口；
-6. 页面接入既定路由，不改全局结构；
-7. 页面与组件实现：打开源稿对应区段对照实现，文案、色值、条目数量与顺序、示例值照源码转写；页面数据一律来自本域真实接口，禁止 mock 业务数据；组件不拆出独立任务；
-8. 前端插件集成（2.4 设计为前端调用的插件）：获取插件运行时 schema，按 schema 调用 [实例名]；结果需持久化的，调用成功后通过已有业务接口保存；
-9. 代码级自查：类型一致性、契约覆盖、shared 定义对齐；禁止运行时验证（见拆解规则第 7 条）。
+6. 在已注册路由与页面壳内实现页面，不重新配置全局路由或 Layout；
+7. 页面与组件实现：打开源稿对应区段对照实现，固定文案、色值、条目结构与顺序照源码转写；业务实体、状态和动态值来自本域真实接口，禁止 mock 业务数据；复用公共组件，只在本域实现页面专属组件，组件不拆出独立任务；
+8. 可点元素处置：落在 2.3 功能清单里的全部接上行为。发现清单外的可点元素说明 2.5 门禁漏项，**不得自行去掉交互、补造接口或把它静默留空**；写入 `docs/design-gaps/[域名].md`（文案、页面、预期行为、需要补齐的设计项）并回报主 Agent。主 Agent 更新 2.2/2.3、路由与契约后重新派发；只有源稿本身明确为纯装饰、且不存在可点语义的元素才可保持非交互。该文件是本任务交付物，无则写「无」；
+9. 前端插件集成（2.4 设计为前端调用的插件）：获取插件运行时 schema，按 schema 调用 [实例名]，字段名与类型以运行时 schema 为准、不从设计文档推测；结果需持久化的，调用成功后通过已有业务接口保存；
+10. 代码级自查：类型一致性、契约覆盖、shared 定义对齐。禁止运行时验证——接口冒烟、起服务联调、读运行时日志、E2E 一概不做，统一在第 5 步由主 Agent 执行。
 
-指令里给出的文件路径是**必读下限，不是可读上限**：实现中需要的其他工程文件（既有组件、工具函数、全局配置、路由表）一律按需自行读取。禁止的是重新推导架构：不重新规划目录与路由结构、不反复 glob 全工程、不修改允许范围外的文件。
+指令里给出的文件路径是**必读下限，不是可读上限**：实现中需要的其他工程文件（既有组件、工具函数、全局配置、路由表）一律按需自行读取。禁止的是重新推导架构：不重新规划目录与路由结构，不反复 glob 全工程。
 
 Worker 回传后，主 Agent 至少读一个关键产物文件抽查（页面是否调真实 API、功能链路是否接通）；回传中的「已完成、已验证」不作为核验依据。
 
+`docs/design-gaps/[域名].md` 非空说明 2.3 或 2.5 漏了元素，主 Agent 逐条补齐功能、接口、页面、表或插件设计后重新派发；禁止把源稿可见功能以“无法实现”或“无目标页”为由降级掉。
+
 **自动化任务**：2.3 中选型为平台自动化内置服务的功能（定时触发、数据变更触发），作为独立任务实现，依赖其用到的表与插件：
 
 1. 读取 trigger-guide skill 了解触发器配置与代码开发规范；
@@ -205,18 +200,21 @@ Worker 回传后，主 Agent 至少读一个关键产物文件抽查（页面是
 
 commit 的静态检查只覆盖编译与 lint，证明不了功能可用与视觉一致。验收开始前先读取 testing-guide skill 了解 E2E 验收流程，并重读 `docs/business-design.md`，以其中的 2.3 功能与 API 清单为验收目标来源。按以下结构执行，完成前不得提交收尾：
 
-1. **架构与入口检查**：先对照 3.1 检查路由、shared 契约、模块边界是否被遵守，对照 3.4 检查导航、页脚、主题色值是否与源稿一致，发现偏离先修结构再继续。再做三项核对：
+1. **架构与入口检查**：检查路由、页面归属、shared 契约和模块边界，再对照源稿检查全局 Layout 是否挂载以及导航项数、文案、顺序、主题色值和内容区域约束，发现偏离先修对应层再继续。再做三项核对：
    - **链接目标可达**：枚举代码中全部跳转目标（导航项、按钮、卡片、搜索、面包屑）与路由表比对，任一指向未注册路由即未通过；
    - **页面均有入口**：每个已注册页面至少有一个应用内可达入口，只能手输 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 注入门控，删除后本指引停止注入，后续迭代不再重复进入升级流程；源稿其余文件保留供以后对照。任一项未通过时不得删除——下轮修复仍需本指引在场。
+2. **功能族覆盖验收**：从 2.3 生成验收目标，不设全应用固定数量上限。每个会写数据或改变业务状态的功能族至少实操一次；纯查询类按不同查询机制（搜索、筛选、排序、分页、切换、跳转）各选一个代表实操，行为相同的重复控件不重复测。每个目标写成「验收对象 —— 应用内点击路径 —— 可判定的通过标准」，必须从应用可见入口开始逐步点击，禁止手输内部 URL 代替可达性验证。通过标准必须包含状态更新、刷新回读、列表/详情变化、真实结果或可恢复错误之一；「页面渲染正常」「控件可见」「按钮可点击」不构成通过标准。派发 E2E agent 实际执行。
+3. **业务闭环验收**：每个独立业务域至少选一条包含起点、过程和业务结果的主链路；若多个域共享同一条跨域链路可合并执行。链路中不得从预置中间态开始来替代创建或触发步骤，源稿未画出的新增页面也必须通过应用内入口到达。
+4. **可降级范围**：AI 内容质量、真实消息送达、复杂批量数据一致性、导出文件内容正确性、低风险视觉细节可降级不阻塞；但被降级能力在应用内的触发、状态与错误反馈仍必须纳入对应功能族验收，不得完全消失。
+5. **初始事实核对**：只对 2.2 建模的业务事实表做 COUNT 与文案抽查，与源稿实体记录对照；条数或文案不符即为未通过。逐个打开源稿画了实体数据的列表与区块，看应用里是否真的渲染出行：**库里有行而页面为空即未通过**。KPI、图表、排行、趋势等派生值不与源稿数字做入库对账。
+6. **动态联动核验**：按 2.3 中不同的「事实来源 + 计算口径 + 变化触发」组合各选一个代表，不按页面或组件重复测试。先记录动态输出，通过应用内真实功能写入或变更一条可唯一识别的事实，刷新并重新查询，确认相关输出按口径变化、跨页面结果一致，且无关输出不被错误改动；再核对数据库只新增或修改事实记录，没有人工同步的统计/快照记录。没有任何可执行写入口能触发变化，说明功能或数据模型未闭环，按未通过处理。
+7. **假实现与派生快照 grep**：命中即未通过——simulate、写死结果的 setTimeout、picsum、假 toast、Math.random 业务值。再 grep 成组出现的业务数值字面量和疑似派生/统计持久化字段或表；不能证明其具有独立业务身份及真实生成更新链路的，改为基于事实的实时计算。
+8. **跨应用素材引用 grep**：在工程代码与初始数据里搜 `/spark/app/`，出现的 appid 不是本应用的即未通过——换成本应用内的地址后重跑。再逐页确认图片真的加载出来（`naturalWidth > 0`），加载失败的按未通过处理。
+9. **公共组件边界与唯一性**：grep 组件定义（`function X(`、`const X = (`、`const X: React.FC`），同名组件在两处及以上定义即未通过——合并到公共组件目录、页面改为 import 后重跑。再检查公共组件不得包含业务数据常量、业务 API 或插件调用、领域状态；命中时把业务逻辑移回所属域，公共组件只保留 props 与事件回调。
+10. **假可点对账（门禁，grep 判不了）**：逐页在浏览器里枚举「有可点外观（`button`、`a`、`role=button`、`role=tab`、`cursor:pointer`）但取不到事件绑定或 `href`」的元素，并反查 2.3 功能族与各域 `docs/design-gaps/*.md`。**存在未归属或未接通的元素即未通过**：先补业务设计，再补接口、页面、插件或行为并重跑；禁止仅为通过验收而撤掉源稿已有的交互外观。功能族数量、浏览器发现的交互实例数、未归属数写进对照表，无需输出逐控件矩阵。
+11. **验收对照表**：列出功能族覆盖、业务主链路、动态推导组合及其通过/失败结果，再列出其余门禁结论。未执行的项写明原因，不得笼统声称“验收通过”；任一必要功能族、主链路或动态推导组合未覆盖，均不得判定完整通过。
+12. **摘除注入标记**：以上各项全部通过后执行 `rm -f source_package/creative/.upgrade-manifest.json`。该文件是本指引的 SessionStart 注入门控，删除后本指引停止注入，后续迭代不再重复进入升级流程；源稿其余文件保留供以后对照。任一项未通过时不得删除——下轮修复仍需本指引在场。
 
 ## 业务模块闭环拆解规则
 
@@ -229,24 +227,31 @@ commit 的静态检查只覆盖编译与 lint，证明不了功能可用与视
 5. **平台内置服务**：模块内需使用的平台内置服务，在该模块的 Service 部分完成配置与调用。
 6. **入口模块优先**：将承载入口页（列表页/首页）的模块任务置于全部模块任务的第一项。
 7. **并行安全**：模块任务内**禁止包含运行时验证**（接口冒烟测试、启动前后端服务联调、读取服务端/前端运行时错误日志、E2E 测试），统一推迟到第 5 步验收阶段。允许保留的验证限定为代码级静态自查（类型一致性、契约覆盖、shared 定义对齐）。
-8. **精确依赖**：每个模块任务只依赖基建（结构骨架 + 共享视觉文件 + 自身所需的表与初始数据 + 插件实例）；模块任务之间无数据依赖时全部可并行，禁止链式依赖。
-9. **粒度保底**：单个模块子步骤明显超限时，允许拆为 `[模块名]服务端开发` + `[模块名]前端开发` 两个任务，前端任务依赖同模块服务端任务，仅此一种拆法。
+8. **启动条件**：结构骨架、schema、公共组件、初始数据和所需插件实例全部就绪后才派发模块任务；模块任务之间无数据依赖时全部可并行，禁止链式依赖。
+9. **公共组件不进域任务**：共享视觉资产清单中的全局 Layout 和跨页面公共组件统一实现，域任务只 import 和传入业务数据、事件，不重写视觉结构；发现清单漏项时先补充清单并完成公共组件实现，不在多个域中各写一份。
+10. **超大域拆分**：命中业务域划分中拆分条件的业务域不得作为单一任务，按子域分别派发；无数据依赖的子域按规则 8 并发执行。
 
-## 视觉一致性规则（全程适用）
+## 视觉一致性原则
 
 - 布局用 flex/grid 加 gap 直接转写源稿结构，不重新设计。
-- 页面一切可见内容（文案、数值与单位、条目数量与顺序、色值、字符图标、选中状态、素材）与源稿逐字段一致：入库的经初始数据与接口到达页面，前端的直接从源稿代码复制。
-- 字符图标保持原字符；源稿已有的图片、SVG、CSS 渐变复用或等价转写，不得用生成图替换。
+- **数据模型与视觉承载分开处理**：不得为了复刻页面而反向增删业务实体和字段。固定文案、导航、区块标题、装饰、图标和样式直接按源稿实现；业务实体字段、状态和动态值经真实接口呈现。
+- 页面固定内容、初始业务事实的呈现、条目结构与顺序、色值、字符图标和选中状态与源稿逐项一致；动态值只对齐单位、格式和排布。
+- 动态获取的内容只对齐源稿的呈现形式（单位、格式、排布），值由真实数据决定。
+- 字符图标保持原字符；源稿已有的 SVG、CSS 渐变复用或等价转写。
+- 源稿素材在本应用内取不到时（如图片指向源应用的运行时存储），不照抄原引用——自行生成替代图并使用，同一位置的图只生成一次；生成不了的报回主 Agent，不留坏链。
+- **公共组件只有一份**：共享视觉资产清单中的全局 Layout 和跨页面公共组件只实现一份；域页面直接 import 并传入业务数据和事件，不在页面内复制视觉结构。只属于单个业务域的页面专属组件才就地实现。
 - 写任何产生页面可见内容的代码之前，重新打开源稿对应位置读取。
 - 确有必要的转换（如固定画布改响应式）需说明转换前后形态，且不改变源稿参考尺寸下的构图。
 
-## 功能真实性规则（全程适用）
+## 功能真实性原则
 
 - 写操作必须走完「前端事件 → 接口 → 数据库/插件 → 界面反馈」全链路，写入结果刷新后仍能读到。
 - 搜索、筛选、排序、分页的参数必须传入真实查询；跳转、Tab、弹窗到达正确的路由或状态。
-- **链接目标必须存在**：写任何跳转前先读既定路由文件，目标只能是已注册路由。源稿有入口但应用内无承载页面时，只有两条出路——回到 2.3 的功能记录里补上新增页面并在 3.1 注册路由后实现，或让该元素保持不可跳转；禁止指向未注册路由。
+- **链接目标必须存在**：写任何跳转前先读既定路由文件，目标只能是已注册路由；源稿有可见入口但没有承载页面时，必须先按功能设计补齐新增页面与路由，禁止以缺少目标页为由取消功能或指向未注册路由。
 - 持久化业务结果由服务端校验前提并写入，前端只展示重新读取的事实。
 - 有数据库时禁止用 mock 数据代替真实查询；插件返回值严禁 mock，前端用 capabilityClient 真实调用，或调用集成了插件的真实服务端接口。
 - 自建 HTTP API 不实现 SSE/WebSocket；插件链路的流式输出（outputMode=stream）不受此限。
-- **可点击外观与真实行为必须同时存在**：转写源稿的按钮与可点击元素时，能用 2.3 已设计的接口或既定路由接上的直接接上；接不上的改成非交互形态——去掉指针手型与按钮态、或呈现禁用态，并在回传中列出这些元素与接不上的原因，由主 Agent 决定是否回到 2.3 补设计。禁止保留看起来能点、点了没反应的元素。
+- **有可点外观就必须有行为**：行为的目标照 2.3 的功能清单与既定路由文件接；只有源稿明确为纯装饰且不存在交互语义的元素才去掉手型与悬停态，禁止因为实现成本或缺少目标页撤掉源稿已有功能。
+- **随业务数据而变的值一律算出**：在 service 内从业务事实聚合，不落成前端常量、`return` 的字面量、冗余派生字段或独立统计快照；事实变化后相关页面重新查询使用同一口径。算出的值与源稿数字不一致是预期结果，源稿事实不足时不得编造明细凑数。
+- **媒体控件绑真实媒体**：播放、进度、倍速挂在真实媒体元素上，时间由它驱动；无媒体资源时整组去掉可点外观。
 - 禁止：空链接、只切换图标不产生数据变化、写死的"成功"提示。

package/miaoda/creative-to-fullstack/references/artifact-signals.md

@@ -1,12 +1,13 @@
 # 创意产物类型信号表与分类型拆分细则
 
-创意模式产物是 design-html 技术栈的静态工程：`index.html` 为入口，可能带 `components/` 或 `screens/` 目录（`.jsx` 经 `<script type="text/babel">` 在浏览器内编译）。先读 `index.html` 全文 + 目录清单，再按下表判类型。**支持生成的只有前三行**（产品设计=多屏设计稿/移动端 mockup、可交互原型）；报表/deck/动画为产品范围外，判中即停止并告知用户（入口层正常会拦截，此为防御兜底）。若会话上下文提供了「当前选中的设计稿文件」路径，判型与拆分优先以该文件为主入口。
+创意模式产物是 design-html 技术栈的静态工程：`index.html` 为入口，可能带 `components/` 或 `screens/` 目录（`.jsx` 经 `<script type="text/babel">` 在浏览器内编译）。先读 `index.html` 全文 + 目录清单，再按下表判类型。**支持生成的只有三类**：多屏设计稿（artboard）、移动端 mockup、可交互原型；报表 / deck / 图文卡片 / 动画为产品范围外，判中即停止并告知用户（入口层正常会拦截，此为防御兜底）。若会话上下文提供了「当前选中的设计稿文件」路径，判型与拆分优先以该文件为主入口。
 
 ## 类型判定信号表
 
 | 类型 | 判定信号（任一命中） | 实现形态 |
 |------|---------------------|----------|
 | 演示稿（deck） | `<deck-stage>` / 翻页控件 / 每屏是「第 N 页」式幻灯结构 | **范围外，停止并告知** |
+| 图文卡片（social card） | `<card-stage>` / 一组固定竖版 `<section>` 卡片（1080×1440 这类上传规格）+ 每卡独立成图 | **范围外，停止并告知** |
 | 多屏设计稿（artboard） | `<DCArtboard>` / `design-canvas` 缩放壳 / 多画板平铺 + 画板 label | 每画板 → 路由页 |
 | 移动端 mockup | 设备框组件（iOS/Android 壳：`width:390` + 圆角 + 状态栏/灵动岛） + `screens/` 或 `screen-*.jsx` 多屏 | 每屏 → 路由页；框内 tab → 应用导航 |
 | 交互原型 | `useState` / 事件处理驱动页面切换，无画布壳，本身像单页应用 | 按其内部「视图状态」拆路由页 |

package/miaoda/creative-to-fullstack/references/ui-to-function.md

@@ -1,6 +1,6 @@
 # UI→功能推导映射表
 
-设计稿里的每个 UI 元素都是功能需求的证据。本表把「稿子上画了什么」翻译成「工程要实现什么」：数据模型、接口、页面行为三层缺一不可。
+设计稿里的每个 UI 元素都是功能需求的证据。本文件只提供对照表，供 SKILL.md 第 2 步业务设计时查表使用。产物结构、登记格式与流程口径一律以 SKILL.md 为准，本文件不重复、不改写、不另立模板。
 
 ## UI→功能映射表
 
@@ -15,34 +15,13 @@
 | 搜索框 | — | 查询接口加关键字参数 | 防抖、无结果态 |
 | 删除/归档按钮 | 软删或归档字段 | 删除/归档接口 | 确认交互 |
 | 日期/日历视图 | 实体时间字段 | 按时间范围查询 | 日/周/月切换 |
-| 稿内示例数据（列表里的假条目、图表假数值） | — | — | 写入数据库成为初始数据；页面必须走真实查询，不许写死 |
+| 稿内示例实体记录（列表/详情中的业务条目） | 对应业务实体与关系 | 真实查询接口 | 作为可追溯初始事实写入数据库，页面走真实查询 |
+| 稿内 KPI/图表/排行/趋势数值 | 不建展示快照实体 | 基于业务事实现场聚合 | 只对齐组件、单位和格式；事实不足时显示真实空值/零值，不誊写数值、不编造明细 |
 
-推导原则：**稿内看得见的每条数据都要能回答「它从哪张表的哪个字段来」**；回答不了的，就补齐真实数据模型和数据链路，不得用硬编码或假逻辑代替。
+推导原则：稿内实体字段要能回答「它来自哪个业务事实字段」；动态值要能回答「它由哪些事实按什么口径计算、哪类写入会使它变化」。回答不了时先补真实业务模型；源稿没有事实依据时返回真实空值或零值，不得用硬编码、统计快照或编造明细代替。
 
 **多维组件必须逐维度登记字段绑定**：一个组件同时承载多个可见维度时（如状态标签的「显示文案」与「视觉状态/颜色」是两个维度），每个维度显式写明绑定哪个字段（如文案 ← `docType`、颜色 ← `status`），不得用同一个状态字段既当文案又当颜色，导致所有行渲染成同一个值。
 
-## 源稿可见内容与默认数据状态
-
-高保真不只包含布局和样式。源稿在默认（未交互）状态下可见的内容、数据和素材同样是 UX 规格；把静态示例改成 DB/API 驱动时，只改变数据来源，不改变默认展示结果。这条约束覆盖应用的每一个页面、每一处可见内容。
-
-| 源稿证据 | 实现要求 |
-|----------|----------|
-| 区块标题、说明、标签、按钮文案 | 原样保留，不擅自缩写、润色或改写语义 |
-| 分类、卡片、列表等重复条目 | 保留源稿的数量、名称、顺序、分组和对应关系 |
-| 价格、时长、进度、统计等示例值 | 作为初始数据写入数据库，统一单位后由真实 API 返回；页面展示值与源稿一致 |
-| 图片、SVG、图标、CSS 渐变、背景 | 复用或等价转译并保持与条目的映射；不得用生成图片替换已有素材 |
-| 默认选中、筛选、分页、空态和业务状态 | 首次进入时由真实数据与页面状态复现，不用硬编码结果覆盖 API |
-
-**页面可见字段不得静默改写**：凡直接显示或决定页面默认外观的字段，包括文案、字符/图标、图片、颜色、渐变、数值、单位、顺序和默认状态，均须从源稿逐字段传递到其存放位置并到达页面。存放位置按性质划分：业务数据，以及属于单条数据自身内容的视觉值（每条数据自有的封面图、封面渐变、标识色），写入数据库成为初始数据、经接口到达页面；不参与查询和聚合、由设计稿为固定集合指定的纯视觉值（字符图标、装饰 emoji、固定区块配色），作为前端组件常量或主题 token，直接从源稿代码复制。字符图标不得静默改成图标库名称，素材不得改成语义占位符。确有必要转译时，在方案中登记源表示、目标表示、转换实现和验收方式，并验证视觉等价。
-
-规划时对每组默认展示数据登记五项内容：目标页面或区块、源文件与行号区间、全部默认展示字段、数据库与接口与页面链路、原值保留或必要转换策略。字段集合必须完整，但不要把大段源码或全部字段值复制进 plan；重复条目应覆盖所有直接渲染或决定外观的字段（如 `name/icon/count/order`），不得只概括成“若干分类/卡片”。写入初始数据、实现 API 投影或素材映射的 Agent 必须在动手前就近读取对应源文件；不能因为 UI Agent 已读源稿，就依据其摘要重新编造数据。
-
-验收时逐页沿真实链路核对：
-
-源稿可见内容、数据库初始数据与素材、API 返回、页面渲染，四层逐字段一致
-
-数据库非空、接口成功、返回条数正确或页面结构相似都不算通过；必须按方案登记的默认展示字段逐字段核对文案、字符/图标、条目数量与顺序、示例值与单位、素材对应关系和默认状态。
-
 ## 前后端接口与数据口径一致
 
 同一业务数据经过前端、API、服务端、数据库或插件时，字段名、类型、单位、取值范围、枚举、是否必填和默认值必须一致。优先在共享接口类型中定义请求与响应结构，前后端不得各自发明不同口径。
@@ -55,39 +34,6 @@
 | 示例：搜索类型 | `types` | `SearchType[]` | 约定枚举，可多选 | 按数组执行 `IN` 查询 | 多选筛选器 |
 | 示例：置信度 | `confidence` | `integer` | 0–100 | DB 与插件归一化后均存 0–100 | 直接追加 `%` |
 
-## 持久化业务结果与异常恢复
-
-如果一次用户操作的结果需要在刷新、重新进入或异常重试后继续存在，或者会约束后续允许执行的操作，就把它视为持久化业务结果。业务结果不限于状态枚举，也包括实体创建、关系变化、数量或进度变化、生命周期阶段和异步产物。Tab、弹窗、展开收起等纯页面状态不要求落库，除非源稿明确表达跨会话保留。
-
-| 业务对象 | 操作/事件 | 操作前提 | 成功后的业务结果 | 持久化内容 | 重复/并发处理 | 刷新与异常恢复 |
-|----------|-----------|----------|--------------------|------------|---------------|----------------|
-| `<实体或关系>` | `<用户操作或系统事件>` | `<允许执行的业务条件>` | `<可观察、可继续使用的事实>` | `<表、字段或外部结果引用>` | `<幂等、拒绝或并发控制>` | `<重新读取、重试或对账>` |
-
-- 以服务端和持久化存储中的业务事实为准；前端只在重新读取后确认结果，不得仅凭本地状态或 HTTP 2xx 宣布完成。
-- 在服务端校验操作前提并原子持久化业务结果；不满足前提的操作返回明确错误，不得静默成功。
-- 对可能重复产生副作用的操作定义幂等或并发控制；请求超时或中断时，先重新读取真实结果，再决定是否重试。
-- 对异步处理持久化任务状态、结果引用和失败信息，使页面重新进入后能够继续查询或恢复。
-
-## 可见功能闭环清单
-
-逐项登记所有具有交互语义的可见元素：按钮、链接、可点击卡片、表单控件、搜索/筛选/排序/分页、Tab/导航/弹窗、上传/下载/导出、播放器、开关和步骤流转。纯文案、分割线、背景等明确非交互装饰不登记；不要据此补造源稿未展示或暗示的产品功能。
-
-同一组件模板中行为和链路完全相同的重复控件可以合并登记，但每个可见交互都必须能对应到清单中的一项；行为、参数或结果不同的控件分别登记。
-
-| 页面 / 可见元素 | 用户操作 | 可见结果 | 实现链路 | 验收方式 |
-|-----------------|----------|----------|----------|----------|
-| 示例：课程详情 /「立即购买」 | 点击 | 报名成功，按钮变为已加入 | `onClick → POST /enrollments → enrollment 表 → 刷新详情` | 从按钮触发；刷新后仍为已加入 |
-| 示例：播放器 / 播放按钮 | 点击 | 开始播放，时间与进度变化 | 播放器状态 → 进度写接口 → progress 表 | 播放后读取进度并刷新确认 |
-
-实现链路按交互类型填写：
-
-- **导航/本地状态**：控件 → 正确路由、Tab、弹窗或组件状态；不得用空 `href`、错误路由或只切换无关图标代替。
-- **查询**：控件 → 查询参数 → API DTO → DB 查询 → 列表/统计结果；前后端复用同一数据口径，并用页面实际发送的参数验收查询结果。
-- **写入**：控件 handler → 写 API → DB/文件/平台能力 → 成功/失败反馈 → 重新读取；请求与响应遵循共享接口类型，不得只改前端内存、只改初始数据或返回固定成功。
-- **插件/外部能力**：控件 → 真实 capability/服务 → 可验证结果；先明确插件输入输出的字段、类型、范围与空值处理，不可用时报告阻塞，不得用延时、随机数、正则校验或假 toast 冒充。
-
-方案提交前扫描可见功能清单、风险和实现说明。若用「模拟、占位、静态展示、Toast 反馈、仅格式校验、仅记录、不对接」代替源稿表达的功能，必须改为真实链路；能力确实不可用时标记阻塞和未完成，不得把降级方案列为已实现范围。
-
 ## UI→capability 常见信号示例（非完整插件目录）
 
 创意稿里被 mock 的 AI/飞书类能力，生成时用**真实插件**实现。下表只帮助从 UI 语义识别插件候选并触发 `plugin-guide`，不是平台能力清单；表外疑似插件能力也要召回 `plugin-guide`。实际可用能力以其动态提供的 `available_plugin_instances`、`available_plugins` 及候选实例的 `get_plugin_ai_json` 为准。
@@ -121,14 +67,4 @@
 | 假飞书反馈 | `toast('已发送到飞书')` 无真实调用 | `send-feishu-message` |
 | 随机数假逻辑 | `Math.random()` 替代 AI 分类/评分 | 对应 AI capability |
 
-（"展示用示例数据"是允许的 mock——写入数据库成为初始数据即可，与上面的"插件能力 mock"区分：前者是数据，后者是能力。）
-
-## 方案（plan）必须包含
-
-- **页面清单**：路由 / 页面名 / 来源屏（画板 label 或文件名）
-- **源稿实现定位与默认展示字段归属**：目标页面或区块 / 源文件或区段 / 全部默认展示字段 / DB、API 与页面链路 / 原值保留或必要转译策略 / UI、初始数据、API 与素材负责人；字段集合必须完整，但不复制大段源码或全部字段值
-- **实体与关系**：表、字段、关联、状态机
-- **页面-接口映射**：每页消费/调用哪些接口
-- **可见功能清单**：页面与控件 / 用户操作 / 可见结果 / 实现链路 / 验收方式
-- **数据口径清单（存在易歧义数据时）**：业务数据 / 请求与响应字段 / 类型与取值 / 单位与范围 / 服务端与 DB / 页面展示
-- **持久化业务结果清单（存在需跨刷新/重新进入/异常重试保留或约束后续操作的结果时）**：业务对象 / 操作或事件 / 操作前提 / 成功后的业务结果 / 持久化内容 / 重复与并发处理 / 刷新与异常恢复
+（源稿中的示例业务实体记录可作为初始事实写入数据库；KPI、图表、排行、趋势等派生展示值不属于可誊写的初始事实。二者都与需要真实插件替换的“能力 mock”区分。）

package/miaoda/feishu/SKILL.md

@@ -143,14 +143,14 @@ npm install @larksuiteoapi/node-sdk
 
 ### FeishuService 单例
 
-> ⚠️ **凭证写入源码**：全栈框架不支持自定义环境变量，因此 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 必须直接写在源码常量中，**不要改为 `process.env`**。
+> ⚠️ **凭证直接写入源码常量**：妙搭全栈当前不提供这类飞书自建应用凭证的运行时环境变量注入。用户提供真实的 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET` 后，直接写入 `FeishuService` 源码常量；不要把它们称为环境变量，也不要改成 `process.env`。在用户提供凭证前，不生成真实值或占位值。
 
 ```typescript
 import { Injectable } from '@nestjs/common';
 import * as lark from '@larksuiteoapi/node-sdk';
 
-const FEISHU_APP_ID = 'cli_xxxx';      // ← 用户提供的真实值
-const FEISHU_APP_SECRET = 'xxxx';      // ← 用户提供的真实值
+const FEISHU_APP_ID = '用户提供的真实 App ID';
+const FEISHU_APP_SECRET = '用户提供的真实 App Secret';
 
 @Injectable()
 export class FeishuService {
@@ -258,7 +258,7 @@ for await (const items of await client.contact.user.listWithIterator({
 
 | 错误 | 正确做法 |
 |------|----------|
-| 将凭证改为 process.env 读取 | 全栈框架不支持自定义环境变量，凭证必须写入源码常量 |
+| 把凭证称为环境变量或改用 `process.env` | 按当前全栈平台契约，在用户提供真实凭证后写入 `FeishuService` 源码常量；未提供前不要生成代码中的凭证值 |
 | `content` 传对象而非 JSON 字符串 | `content: JSON.stringify({ text: 'hello' })` |
 | 每次请求都新建 `lark.Client` | NestJS `@Injectable()` 单例模式复用 |
 | `receive_id_type` 与 ID 前缀不匹配 | `oc_` → `chat_id`, `ou_` → `open_id`, `on_` → `union_id` |

package/miaoda/forms-skill/SKILL.md

@@ -13,6 +13,7 @@ Shadcn Form + React Hook Form + Zod 表单开发。
 - 所有字段必须有默认值
 - 必须用 Shadcn 组件，禁止原生 input
 - 同行 FormField 必须等宽
+- 表单提交到必填 API/DTO/Request/interface 前，先读目标 shared/server 类型，在 `handleSubmit` 回调里用 `data` 逐字段构造 typed request（见 Patterns）；不要整体传 `data`、`schema.parse(data)` 或 `.required().parse(data)`，也不要用 `any`/`as` 绕过 TS2322。修完后跑 LSP 或 `typecheck`。
 
 ---
 
@@ -100,6 +101,14 @@ const form = useForm<FormData>({ resolver: zodResolver(schema), defaultValues: {
 // 必填标记
 <FormLabel>字段 <span className="text-destructive">*</span></FormLabel>
 
+// 必填 Request/DTO 桥接：zodResolver 负责运行时校验，DTO 边界负责静态类型匹配。
+// 用 handleSubmit 回调的 data，不要用 getValues（拿到的是 coerce 前的原始值）。
+import type { SaveRequest } from "@/shared/api";
+form.handleSubmit(async (data) => {
+  const request: SaveRequest = { field: data.field };
+  await api.save(request);
+});
+
 // 调试
 logger.info("errors:", form.formState.errors);
 ```

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

@@ -65,7 +65,8 @@ gate-tools:
 |---|---|
 | SQL 执行通道 | 只用 `+db-execute`，不要裸连数据库或调用其它 SQL 工具 |
 | 查结构只认 DB | 表结构 / 字段 / 索引 / 约束一律 `+db-table-list` / `+db-table-get --table <table>`。`server/database/schema.ts` 只在写 TS 代码对齐类型时读，**不能用来回答结构问题**——它是生成产物，可能滞后于 DB |
-| `schema.ts` 禁止手改 | DB 结构不对就改 DDL 后重跑 codegen；DB 正确但 `schema.ts` 渲染错误时同样不手改，向用户说明是 codegen bug |
+| `schema.ts` 禁止手改 | `schema.ts` 是 `npm run gen:db-schema` 的生成产物。DB 结构不对就改 DDL 后重跑 `npm run gen:db-schema`；DB 正确但 `schema.ts` 渲染错误时同样不手改，向用户说明是 schema 生成器 bug |
+| DDL 后刷新 `schema.ts` | `+db-execute` **不会**自动刷新 `schema.ts`。每次 DDL 成功后立即在应用工程根目录执行 `npm run gen:db-schema`，再写引用新表 / 新列的 TS 代码 |
 | 变更历史只认 DB | 结构变更历史用 `+db-changelog-list`。`git log -- server/database/schema.ts` 只是代码侧痕迹，**不等价**，不能用来回答"做过哪些 DDL 改动" |
 | 要数据就查库 | 用户要的是查询结果本身（计数 / 明细 / 统计）时，直接 `+db-execute` 查完把结果给用户；**不要为一次性查询去新增接口或 service 代码** |
 | DDL 原子性 | CREATE TABLE + RLS + policy + COMMENT + INDEX 放在一次 `--sql` 调用；需要全回滚时显式 `BEGIN; ... COMMIT;` |
@@ -131,6 +132,7 @@ CREATE POLICY "修改本人数据" ON <table>
 4. CREATE TABLE / CREATE INDEX / ALTER TABLE ADD COLUMN 必须带 `IF NOT EXISTS`，避免重复执行失败。
 5. 执行前向用户展示目标对象和变更内容；DROP / DROP COLUMN 还要说明数据丢失风险并取得明确授权。
 6. 执行：`lark-cli apps +db-execute --app-id "$app_id" --sql "<ddl>" --yes`。多条 DDL 是一个逻辑单元时放在一次调用；需要全回滚则显式包事务。
+7. DDL 成功后**立即**在应用工程根目录执行 `npm run gen:db-schema` 刷新 `server/database/schema.ts`——`+db-execute` 不会自动刷新。多批 DDL 每批成功后都跑一次。
 
 ### DDL Do / Don't