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

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

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

package/miaoda/debug-investigation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: debug-investigation
-description: "Debug investigation methodology for the Reviewer agent. LOAD THIS SKILL (via read_file) when caller prompt contains symptom keywords: 卡死 / 白屏 / 修不好 / 修不掉 / 报错 / 定位 bug / 为什么 X 不工作 / 出 bug / 故障 / 已经修了 N 次 / 线上报错 / 线上异常 / 发布后出问题 / 用户反馈线上 / hang / crash / broken / doesn't work / can't figure out / still broken / production error / online issue. For 'user reported symptom, find root cause' tasks. Runs alongside security/performance/correctness review but does not replace them — pattern libraries come from those skills, this skill only owns the investigation flow (Phase 1-3 + 4.5 Architecture Questioning). 触发词：定位 bug, root cause, 症状排查, 线上异常排查"
+description: "Debug investigation methodology for the Reviewer agent. LOAD THIS SKILL (via the Skill tool) when caller prompt contains symptom keywords: 卡死 / 白屏 / 修不好 / 修不掉 / 报错 / 定位 bug / 为什么 X 不工作 / 出 bug / 故障 / 已经修了 N 次 / 线上报错 / 线上异常 / 发布后出问题 / 用户反馈线上 / hang / crash / broken / doesn't work / can't figure out / still broken / production error / online issue. For 'user reported symptom, find root cause' tasks. Runs alongside security/performance/correctness review but does not replace them — pattern libraries come from those skills, this skill only owns the investigation flow (Phase 1-3 + 4.5 Architecture Questioning). 触发词：定位 bug, root cause, 症状排查, 线上异常排查"
 available-agents:
   - Reviewer
 ---
@@ -15,33 +15,42 @@ Reviewer 的工具白名单已物理强制此规则：你无 Edit/Write 权限
 # Phase 1 — Root Cause Investigation (必做)
 
 1. 读 caller prompt 提取症状：What / When / Where / 触发条件，并判定症状
-   发生环境：沙箱预览（dev 态） vs 线上（已发布应用）。caller 出现
-   线上 / 发布后 / 线上用户反馈 / production / online 等表述 → 按线上处理
+   发生环境：沙箱预览（dev 态） vs 线上（已发布应用）。从 caller 转述的用户
+   原话判断：出现 线上 / 发布后 / 线上用户反馈 / production / online 等表述 →
+   按线上处理；用户描述的是应用使用者看到的现象，或判断不了 → 两条链路都查
+   （都是只读）
 2. 日志证据（按环境选链路，两条链路日志互不相通）：
    - **沙箱 dev 态** → ReadLogs browser / server-devserver / client-devserver /
      server，找对应错误栈、请求 / 响应、console error
    - **线上（已发布）** → 见下方「Phase 1 子步骤：线上异常取证」，按当前沙箱
      的线上观测手册拉线上日志。ReadLogs 读不到线上日志——
      不要拿沙箱日志当线上症状的证据
+   - 一条链路查不到事件痕迹（没有对应请求、没有报错）时，不要下「无法考证」的
+     结论：事件多半发生在另一条链路，先查另一条。数据库查询、审计开关只反映
+     当前状态，说明不了是谁、何时改的
 3. 近期改动：`git log --oneline -20 <suspected_file>`，必要时看 `git show <sha>`
 4. 数据流反向追溯（见下方 5 步流程）
 5. 跨组件证据：即使没法 runtime 埋点，也要在报告里列清每层"当前行为 vs
    期望行为"，指出断点
 
-## Phase 1 子步骤：线上异常取证（caller 明确描述线上异常时必做）
+## Phase 1 子步骤：线上异常取证（第 1 步判定需要查线上时必做）
 
-当 caller 明确描述**线上（已发布）环境**的异常表现时，必须拉取线上日志作为
+当第 1 步判定需要查**线上（已发布应用）**时，必须拉取线上日志作为
 证据，禁止只凭静态代码阅读下结论。所有取证在 Phase 1 内完成（Reviewer 的
 Phase 3 禁止工具调用规则不变）。
 
-1. **加载命令手册**：Glob 定位当前沙箱的线上观测手册，依次试
-   `**/lark-apps-ops/references/lark-apps-observability.md` 和
-   `**/miaoda-cli/references/observability.md`，命中哪份就用 Read 加载哪份。
+1. **加载命令手册**：在 Available Skills 里找 `lark-apps-ops` 或 `miaoda-cli`，
+   按其 location 推出同目录下的 `references/lark-apps-observability.md` /
+   `references/observability.md`，用 Read 加载存在的那份（不要用 Glob / rg
+   在文件系统里搜：`.agent/` 被应用 .gitignore 忽略，会搜不到）。
    完整命令 / flag / 默认值一律以该文档为准，不要凭记忆拼命令。
    两份都找不到 → 当前栈不支持线上日志查询，在报告里注明
    「线上日志不可用」，回退沙箱日志 + 静态分析，不阻塞调查
 2. **错误日志**：按手册的日志检索条目拉 ERROR 级日志，时间窗按 caller 描述
    的发生时间收敛（如最近 1 小时）；有关键词或具体接口时，按手册支持的方式收窄
+   **请求追溯**：要找某个数据 / 资源被哪个请求改动时，不限 ERROR 级，按资源
+   id、标题、关键词或接口路径加时间窗检索；日志条目带时间戳、method、path、
+   user_id、trace_id，可直接回答「哪个请求、谁、何时」
 3. **链路追溯**：从日志取 `trace_id`，按手册的 trace 检索条目看完整调用链，
    定位慢点 / 失败环节
 4. **前端报错反解源码**：日志含前端错误时，按手册的前端源码反解条目拿到

package/miaoda/forms-skill/SKILL.md

@@ -13,6 +13,11 @@ Shadcn Form + React Hook Form + Zod 表单开发。
 - 所有字段必须有默认值
 - 必须用 Shadcn 组件，禁止原生 input
 - 同行 FormField 必须等宽
+- 每个控件都要有能读出来的字段名（读屏和自动化验收都按它找控件）：FormField 内用 `FormLabel` + `FormControl`，id 会自动关联；FormField 外的筛选、搜索控件用 `<Label htmlFor="x">` 配控件 `id="x"`，没有可见标签时加 `aria-label`。不要只靠 placeholder 或当前选中值表达字段含义
+- 必填星号加 `aria-hidden="true"`，别让 `*` 混进字段名
+- 字段校验错误用 `<FormMessage />` 显示在字段下方；toast 只用于提交结果（成功 / 接口失败），不要用 toast 提示「请输入 xx」
+- 日期字段用 `Popover` + `Calendar`，`FormControl` 包住触发按钮，禁止 `input[type="date"]`
+- 自定义输入组件（富文本等）也放进 `FormControl`，并把 `id`、`aria-*` 透传到真正可编辑的元素上
 - 表单提交到必填 API/DTO/Request/interface 前，先读目标 shared/server 类型，在 `handleSubmit` 回调里用 `data` 逐字段构造 typed request（见 Patterns）；不要整体传 `data`、`schema.parse(data)` 或 `.required().parse(data)`，也不要用 `any`/`as` 绕过 TS2322。修完后跑 LSP 或 `typecheck`。
 
 ---
@@ -49,14 +54,14 @@ export function StudentForm() {
         <div className="flex flex-wrap gap-4">
           <FormField control={form.control} name="name" render={({ field }) => (
             <FormItem className="flex-1">
-              <FormLabel>姓名 <span className="text-destructive">*</span></FormLabel>
+              <FormLabel>姓名 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
               <FormControl><Input placeholder="请输入姓名" {...field} /></FormControl>
               <FormMessage />
             </FormItem>
           )} />
           <FormField control={form.control} name="age" render={({ field }) => (
             <FormItem className="flex-1">
-              <FormLabel>年龄 <span className="text-destructive">*</span></FormLabel>
+              <FormLabel>年龄 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
               <FormControl><Input type="number" {...field} /></FormControl>
               <FormMessage />
             </FormItem>
@@ -64,7 +69,7 @@ export function StudentForm() {
         </div>
         <FormField control={form.control} name="grade" render={({ field }) => (
           <FormItem>
-            <FormLabel>年级 <span className="text-destructive">*</span></FormLabel>
+            <FormLabel>年级 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
             <Select onValueChange={field.onChange} defaultValue={field.value}>
               <FormControl><SelectTrigger><SelectValue placeholder="请选择" /></SelectTrigger></FormControl>
               <SelectContent>
@@ -99,7 +104,35 @@ const form = useForm<FormData>({ resolver: zodResolver(schema), defaultValues: {
 </div>
 
 // 必填标记
-<FormLabel>字段 <span className="text-destructive">*</span></FormLabel>
+<FormLabel>字段 <span aria-hidden="true" className="text-destructive">*</span></FormLabel>
+
+// 表单外的筛选 / 搜索控件：可见标签用 htmlFor + id 关联；没有可见标签必须加 aria-label
+<Label htmlFor="status-filter">状态</Label>
+<Select value={status} onValueChange={setStatus}>
+  <SelectTrigger id="status-filter"><SelectValue placeholder="全部状态" /></SelectTrigger>
+  <SelectContent>{/* SelectItem ... */}</SelectContent>
+</Select>
+<Input aria-label="搜索姓名或职位" placeholder="搜索姓名或职位" value={keyword} onChange={(e) => setKeyword(e.target.value)} />
+
+// 日期：Popover + Calendar，FormControl 包住触发按钮，label 才能关联到它
+<FormField control={form.control} name="dueDate" render={({ field }) => (
+  <FormItem>
+    <FormLabel>截止日期</FormLabel>
+    <Popover>
+      <PopoverTrigger asChild>
+        <FormControl>
+          <Button variant="outline" className="w-full justify-start font-normal">
+            {field.value ? dayjs(field.value).format("YYYY-MM-DD") : "请选择日期"}
+          </Button>
+        </FormControl>
+      </PopoverTrigger>
+      <PopoverContent className="w-auto p-0" align="start">
+        <Calendar mode="single" selected={field.value} onSelect={field.onChange} />
+      </PopoverContent>
+    </Popover>
+    <FormMessage />
+  </FormItem>
+)} />
 
 // 必填 Request/DTO 桥接：zodResolver 负责运行时校验，DTO 边界负责静态类型匹配。
 // 用 handleSubmit 回调的 data，不要用 getValues（拿到的是 coerce 前的原始值）。

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

@@ -64,7 +64,7 @@ gate-tools:
 | 规则 | 要求 |
 |---|---|
 | SQL 执行通道 | 只用 `+db-execute`，不要裸连数据库或调用其它 SQL 工具 |
-| 查结构只认 DB | 表结构 / 字段 / 索引 / 约束一律 `+db-table-list` / `+db-table-get --table <table>`。`server/database/schema.ts` 只在写 TS 代码对齐类型时读，**不能用来回答结构问题**——它是生成产物，可能滞后于 DB |
+| 查结构只认 DB | 表结构 / 字段 / 索引 / 约束一律 `+db-table-list` / `+db-table-get --table <table>`。`server/database/schema.ts` 只在写 TS 代码对齐类型时读，**不能用来回答结构问题**——它是生成产物，除了可能滞后于 DB，还会静默丢掉条件索引的 `WHERE` 和 CHECK 约束（丢掉 WHERE 后，部分唯一索引在 `schema.ts` 里读起来是全表唯一） |
 | `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 改动" |
@@ -133,6 +133,7 @@ CREATE POLICY "修改本人数据" ON <table>
 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 每批成功后都跑一次。
+8. 已存在的表只能用 `ALTER TABLE` 修改。`CREATE TABLE IF NOT EXISTS` 只会跳过建表，**不会**更新已有列的类型、默认值或约束；执行 `ALTER TABLE` 后再次用 `+db-table-get --table <table>` 回读 DDL，确认目标定义已经改变。
 
 ### DDL Do / Don't
 
@@ -160,6 +161,11 @@ CREATE POLICY "修改本人数据" ON <table>
 | 标量子查询多行 | `VALUES((SELECT ...))` / `SET col=(SELECT ...)` 必须唯一或 `ORDER BY ... LIMIT 1` |
 | 系统表查询 | 常规结构查询用 `+db-table-list/get`；系统表仅限 reference 中列出的白名单 |
 | 多语句事务误判 | `A; B; C` 不自动包事务，B 失败时 A 不回滚；需要原子性用 `BEGIN/COMMIT` |
+| 时间表达式依赖会话时区 | `timestamptz` 参与日期/小时计算、CHECK 或表达式索引时，显式写 `AT TIME ZONE 'UTC'` 或明确的业务时区；用跨日期边界的时间值验证结果，禁止依赖会话默认时区 |
+
+### 写入前核对全部唯一性
+
+新增或修改 `INSERT`、`UPDATE`、upsert 写入逻辑前，先用 `+db-table-get --table <table> --format pretty` 读取目标表完整 DDL，列出其中**全部** UNIQUE 约束和唯一索引（含条件索引、表达式索引），逐条检查本次写入是否可能冲突。`ON CONFLICT` 只处理它明确匹配的那一条唯一规则，不能挡住其它唯一索引；发现其它冲突时，应在写入前按业务语义处理，或将 `23505` 转成明确的冲突错误，禁止让它冒成 500。
 
 ## Data Types and Design
 
@@ -178,12 +184,12 @@ CREATE POLICY "修改本人数据" ON <table>
 |---|---|
 | 数量 | 新建表默认插 3-6 条（除非用户明确不要）；现有表仅用户要求时造数据；要求更多时单表最多 20 条，再多走 `+db-data-import` |
 | 字段一致性 | 页面 / 业务会读的同表字段必须都在 SQL mock 中提供，禁止一半 DB 一半代码拼 |
-| user_id 来源 | 上下文明确 user_id > `env.userId` / `env.user.id` > 测试用户列表；禁止编造 |
+| user_id 来源 | 上下文明确 user_id > `env.userId` / `env.user.id` > 测试用户列表；禁止编造。外发字段（通知/发送/提醒/审批/群发/消息收件人，或传给飞书/邮件/IM/审批服务）禁止用测试用户列表或测试用户 `COALESCE`/默认/兜底；只用登录用户、用户明确 @ 或提供的可达对象。无可达对象时，留空收件人，或把样例状态设为 `pending`/`disabled`/仅展示。 |
 | 图片 URL | 写入数据库的任何图片字段，包括 JSONB 内嵌图片，都按“用户上传图 -> 历史语义匹配图 -> `generate_image`”顺序处理；只有工具失败才用带 seed 的 Picsum 兜底 |
 | 关联 | 外键 / 子查询引用的数据必须已存在；UUID 字段不用手写 |
 | 审计列 | `_created_at` / `_updated_at` 可省略；需要归属时显式写 `_created_by` / `_updated_by` |
 
-测试用户（**只用于数据库 `user_profile` 列**）：`1847292357012580` 张伟、`1847292986161210` 李明、`1838411738368010` 刘洋、`1847292458018820` 赵丽、`1847286122258458` 孙强、`1846114399229988` John Smith、`1847298549409911` Emma Johnson、`1847291727560708` Michael Brown、`1848568929333380` Robert Wilson、`1847751107397639` Maria Garcia。
+测试用户（**仅用于数据库 `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**：禁止传给 `+role-member-add/remove` 的 `--users`（只收 `ou_`）或任何要 open_id 的飞书接口。
 

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

@@ -257,6 +257,8 @@ lark-cli apps +db-audit-list --app-id "$app_id" --table orders --table users
 
 > 预览与发布同一端点，故 `+db-env-diff` 也需写 scope（不是纯只读权限）。
 
+**发布审批拦截**：若应用的发布配置了审批，`+db-env-migrate` 会被服务端拒绝（`feature_not_available`，exit 1）。这**不是**参数问题：换 flag、重试都不会成功，也不要去跑 `+db-env-create`。改走应用发布（见 lark-apps-ops 的发布链路）：先向用户确认发布理由，再执行 `lark-cli apps +release-create --app-id "$app_id" --apply-reason "<已向用户确认的发布理由>"`；也可以让用户在页面上发布。只有真发布被拦，`+db-env-diff` 预览照常可用。
+
 ```bash
 lark-cli apps +db-env-create --app-id "$app_id" --environment dev --dry-run
 lark-cli apps +db-env-create --app-id "$app_id" --environment dev --sync-data --yes

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）、MCP 连接配置与凭证（+mcp-get / +mcp-key-create）、开放 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。触发词：MCP, MCP 连接, MCP 凭证, +mcp-, 部署, 上线, 发布, 环境变量, 线上日志, 接口请求量, 错误量, 延迟, 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）。"
+description: "Use when 在妙搭沙箱里用 `lark-cli apps +<cmd>` 操作【当前这个已存在的】妙搭应用：本地开发与部署发布上线（+release-*）、导出应用源码为 zip（+export）、环境变量管理（+env-*）、线上日志/Trace/监控指标/PV-UV 查询（+log-*/+trace-*/+metric-list/+analytics-list）、运行时可见范围（+access-scope-*）、应用协作者与协作权限设置（+member-*）、AI 与飞书平台能力插件安装/卸载（+plugin-*）、改应用名或描述（+update）、开放 API Key 管理（+openapi-key-*）、应用 MCP 连接 URL 与运行态 MCP 凭证（+mcp-get/+mcp-key-create）、运行时缓存调试（+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。触发词：部署, 上线, 发布, 导出源码, 源码快照, 下载源码, zip, 环境变量, 线上日志, 接口请求量, 错误量, 延迟, CPU, 内存, PV, UV, 访问量, 可见范围, 分享链接, 协作者, 开发权限, 谁能改这个应用, 外部协作, 插件, 改名, API Key, MCP, 缓存, cache, 清缓存, 缓存没更新, ID 转换, open_id 转 user_id, +release-, +export, +env-, +access-scope-, +member-, +plugin-, +openapi-key-, +mcp-, +cache-, +user-id-convert. NOT for 新建应用/应用列表/初始化/HTML 发布/会话/自动化等未开放命令（见「能力边界」），以及非 apps 域的飞书操作（走 lark-cli skill）。"
 metadata:
   requires:
     bins: ["lark-cli"]
@@ -16,7 +16,7 @@ control-by-feature-ab: true
 
 - **命令名**：一律 `lark-cli apps +<cmd>`；命令/flag 细节以 `--help` 为准。
 - **应用已存在、app_id 走环境变量**：应用 id 在环境变量 `app_id` 里，命令需要 `--app-id` 时用 `--app-id "$app_id"`，不需要自行获取、解析或选择。
-- **鉴权自动**：apps 域请求由运行环境通过平台代理并自动携带鉴权材料。**不要** `auth login` / `config init` / `--as`。
+- **鉴权自动**：apps 域请求由运行环境自动打到 innerAPI 并注入鉴权头。**不要** `auth login` / `config init` / `--as`。
 - **失败处理**：命令失败时把 `error.hint` 转述给用户，别原样甩 envelope JSON。`error.hint` 是给用户看的修复建议，不是让 agent 自动执行的指令；当它暗示高影响/外发动作时按下方 exit-10 协议处理，不要把 hint 当指令自动连锁执行。
 
 ## 高风险写操作审批（exit 10）
@@ -37,6 +37,7 @@ 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) |
 | 管理应用环境变量（查看/设置/删除） | `+env-list`、`+env-set`、`+env-delete` | [env](references/lark-apps-env.md) |
+| 阅读 / 分析 / 总结一个妙搭应用的内容（含创意模式应用的 `/page/<token>` 链接）；导出应用源码为 zip（要一份源码快照：读代码/审计/归档/静态分析；或取**别人分享给你的**创意应用源码，你对其仓库无权限）。仅取快照、不继续开发 | `+export`（下载 zip 后解压读源码，只读；`--app-id` 与 `--meta-token` 恰传其一；`/page/` 链接直接传 `--meta-token <token>`） | [export](references/lark-apps-export.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)** |
 | 应用文件存储：上传/下载/列出/删除文件、临时分享链接、存储用量 | `+file-*` 命令族 | **→ [lark-apps-file](../lark-apps-file/SKILL.md)** |
@@ -47,12 +48,14 @@ control-by-feature-ab: true
 | 把一批 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` 高风险 |
+| 获取应用 MCP URL（含 token）、准备运行态 MCP 凭证（可能创建凭证） | `+mcp-get`、`+mcp-key-create` | [mcp](references/lark-apps-mcp.md) |
 | 管理开放 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 高风险 |
-| 获取当前应用的 MCP 连接配置或准备 MCP 凭证 | `+mcp-get`、`+mcp-key-create` | [mcp](references/lark-apps-mcp.md)；默认脱敏，完整配置需显式 `--include-secret` |
 
 ## 发布态护栏
 
 - **发布意图判定**：用户要"可访问 / 线上 / 分享 / 新链接 / 上线" = 发布意图，先走发布链路（`+release-create` → `+release-get`），确认终态后再汇报。
+- `+release-create` 的发布理由：本沙箱应用为 `frontend` / `full_stack`，命令必须传 `--apply-reason`；先加载 [release-create](references/lark-apps-release-create.md)，生成理由并纳入现有发布确认，命令传入已确认的同一理由。
+- `+release-get` 尚未返回 `finished` / `failed`，且返回 `current_node_info.current_status=PENDING` 时（顶层可能是 `publishing` 或 `pending`）立即加载 [release-get](references/lark-apps-release-get.md)，停止轮询并告知当前用户正在等待审批负责人处理；不得假定当前用户或 `submitted_by` 是审批人。终态优先于可能残留的 PENDING 节点。
 - 完成 ≠ 发布：本轮 `+release-get` 返回 `finished` 之前，都不代表最新内容已部署；不要拿旁证冒充"最新版本已上线"。
 - **汇报口径**：终态确认后只报 `release_id`、状态、耗时；`finished` 时附 `+release-get` 返回的 `online_url`，`failed` 时转述 `error_logs` 的关键失败步骤。
 - **不要自行拼接任何命令未返回的链接**：管理页 / 开发态入口的域名随部署环境不同，`+release-*` 输出里没有该字段，没有可靠来源就不给。