@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.28c4f05 → 0.1.0-dev.4e64c13

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

@@ -0,0 +1,157 @@
+---
+name: creative-to-fullstack
+description: Use when the task is to build a complete full-stack application from a creative-mode design draft. 触发词：创意设计稿, 将创意设计稿实现为一个完整的全栈应用, 按设计稿开发应用, 基于当前设计生成应用, design to fullstack
+hook: SessionStart
+workspace-contains:
+  - source_package/creative/.upgrade-manifest.json
+---
+
+# 根据创意设计稿生成全栈应用
+
+`source_package/creative/` 是一份创意模式产物（UX 设计稿），它定义了应用的外观和功能，两者都要交付：视觉效果原样照抄源稿，功能实现为真实链路。架构从源稿分析得出，数据从源稿原样复制得出，都不允许自行设计或编造。
+
+术语约定：**初始数据**指源稿默认展示的内容写入数据库后形成的记录；**源稿定位**指源稿文件路径加行号区间。
+
+## Quick Reference
+
+| 阶段 | 做什么 | 细则 |
+|------|--------|------|
+| 第 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/` 的构建引用 | 该目录只读留档，工程代码不依赖它 |

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

@@ -0,0 +1,46 @@
+# 创意产物类型信号表与分类型拆分细则
+
+创意模式产物是 design-html 技术栈的静态工程：`index.html` 为入口，可能带 `components/` 或 `screens/` 目录（`.jsx` 经 `<script type="text/babel">` 在浏览器内编译）。先读 `index.html` 全文 + 目录清单，再按下表判类型。**支持生成的只有前三行**（产品设计=多屏设计稿/移动端 mockup、可交互原型）；报表/deck/动画为产品范围外，判中即停止并告知用户（入口层正常会拦截，此为防御兜底）。若会话上下文提供了「当前选中的设计稿文件」路径，判型与拆分优先以该文件为主入口。
+
+## 类型判定信号表
+
+| 类型 | 判定信号（任一命中） | 实现形态 |
+|------|---------------------|----------|
+| 演示稿（deck） | `<deck-stage>` / 翻页控件 / 每屏是「第 N 页」式幻灯结构 | **范围外，停止并告知** |
+| 多屏设计稿（artboard） | `<DCArtboard>` / `design-canvas` 缩放壳 / 多画板平铺 + 画板 label | 每画板 → 路由页 |
+| 移动端 mockup | 设备框组件（iOS/Android 壳：`width:390` + 圆角 + 状态栏/灵动岛） + `screens/` 或 `screen-*.jsx` 多屏 | 每屏 → 路由页；框内 tab → 应用导航 |
+| 交互原型 | `useState` / 事件处理驱动页面切换，无画布壳，本身像单页应用 | 按其内部「视图状态」拆路由页 |
+| 报表看板 | echarts / 图表库 + 指标卡片布局 | **范围外，停止并告知** |
+| 纯动画/视觉演示 | 大量 keyframes/canvas 动画、无业务 UI | **范围外，停止并告知** |
+
+混合信号时以「业务 UI 占比」为准：有表单/列表/详情等业务界面 → 按设计稿/原型类正常生成（防止 deck 里嵌了真实业务界面设计被误杀）；纯展示 → 判为范围外。
+
+## 分类型拆分细则
+
+### 多屏设计稿 / 移动端 mockup
+
+1. 枚举所有屏：`data-screen-label` 属性、画板 label、`screen-*.jsx` 文件名，三者取有值的作为页面名与路由名来源。
+2. 稿内导航（底部 tab / 侧边栏 / 顶部菜单）转为工程导航结构；未出现在导航里的屏（如详情页、由弹层提级的独立页）按从属关系挂到父页面路由下。
+3. 导航项逐项承接源稿：数量、文案、顺序与源稿一致。源稿导航中没有对应画板的项不得删除，也不得添加源稿没有的导航项；这类项的点击去向在方案中写明（例如指向相关页面的对应区块，或在方案的未决事项中说明），不得静默决定。
+4. 设备框（手机壳、浏览器壳、`IOSFrame` 这类组件）是预览容器：取 `children` 内容做响应式页面；状态栏、灵动岛、Home 指示条随壳丢弃。
+5. 稿内固定尺寸（390×844、1920×1080 加 scale 缩放）改为真响应式：内容宽度用容器约束（如 `max-width` + 居中），移动优先或桌面优先取决于原稿形态。
+
+### 交互原型
+
+1. 找出所有「视图状态」：`useState` 切换的 tab/step/modal 中承载独立业务界面的 → 路由页；纯交互细节（折叠、hover）→ 保留为组件内交互。
+2. 原型里已经写了的交互逻辑（校验提示、乐观更新、步骤流转）是功能需求的最强信号，逐条纳入第 2 步的可见功能清单。
+
+### 报表看板
+
+范围外类型，不做生成。若混合产物中局部包含图表且整体被判为设计稿/原型类，图表部分按 `ui-to-function.md` 的"统计卡片/图表"映射行处理。
+
+## 稿内机制识别速查
+
+| 稿内出现 | 含义 | 处置 |
+|----------|------|------|
+| `<script type="text/babel">` + `@babel/standalone` | 浏览器内编译 JSX 的预览机制 | 内容重写为工程组件，机制丢弃 |
+| `unpkg-sdk/react@*/umd/*.js`（miaoda.feishu.cn 镜像） | CDN React 运行时 | 丢弃，用工程自带 React |
+| `Object.assign(window, { Xxx })` | 组件挂全局供跨 `<script>` 引用 | 转译为模块 import/export |
+| `data-miaoda-*` / `data-screen-label` | 创意平台标注属性 | 属性丢弃；label 值用作路由/导航命名后即弃 |
+| `miaoda.feishu.cn/fonts/css2?family=...` | 字体镜像 | 保留，生产可用 |
+| tweaks / EDITMODE 面板 | 设计期调参 | 当前参数值固化进主题 token，面板删除 |

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

@@ -0,0 +1,134 @@
+# UI→功能推导映射表
+
+设计稿里的每个 UI 元素都是功能需求的证据。本表把「稿子上画了什么」翻译成「工程要实现什么」：数据模型、接口、页面行为三层缺一不可。
+
+## UI→功能映射表
+
+| 稿内 UI 元素 | 数据模型 | 接口 | 页面行为 |
+|--------------|----------|------|----------|
+| 表单（输入框/选择器/提交按钮） | 表单字段 → 实体字段（含类型与必填） | 创建/更新写入接口 + 校验 | 提交、校验提示、成功/失败反馈 |
+| 列表/卡片流 | 列表项字段 → 实体查询投影 | 查询接口：排序、过滤、分页 | 空态、加载态、分页/滚动加载 |
+| 详情页 | 单实体全字段 | 按 ID 查询 | 不存在时的 404 处理 |
+| 统计卡片/图表 | 无新实体，基于既有实体聚合 | 聚合接口（count/sum/avg + group by 维度） | 时间/维度筛选联动 |
+| 头像/昵称/个人页/「我的」tab | 用户实体 + 业务数据挂 userId | 当前用户接口；业务查询按用户隔离 | 登录态展示 |
+| 状态标签（待办/进行中/已完成等） | 实体 status 字段 + 合法流转 | 状态变更接口（校验流转合法性） | 状态筛选、变更操作入口 |
+| 搜索框 | — | 查询接口加关键字参数 | 防抖、无结果态 |
+| 删除/归档按钮 | 软删或归档字段 | 删除/归档接口 | 确认交互 |
+| 日期/日历视图 | 实体时间字段 | 按时间范围查询 | 日/周/月切换 |
+| 稿内示例数据（列表里的假条目、图表假数值） | — | — | 写入数据库成为初始数据；页面必须走真实查询，不许写死 |
+
+推导原则：**稿内看得见的每条数据都要能回答「它从哪张表的哪个字段来」**；回答不了的，就补齐真实数据模型和数据链路，不得用硬编码或假逻辑代替。
+
+**多维组件必须逐维度登记字段绑定**：一个组件同时承载多个可见维度时（如状态标签的「显示文案」与「视觉状态/颜色」是两个维度），每个维度显式写明绑定哪个字段（如文案 ← `docType`、颜色 ← `status`），不得用同一个状态字段既当文案又当颜色，导致所有行渲染成同一个值。
+
+## 源稿可见内容与默认数据状态
+
+高保真不只包含布局和样式。源稿在默认（未交互）状态下可见的内容、数据和素材同样是 UX 规格；把静态示例改成 DB/API 驱动时，只改变数据来源，不改变默认展示结果。这条约束覆盖应用的每一个页面、每一处可见内容。
+
+| 源稿证据 | 实现要求 |
+|----------|----------|
+| 区块标题、说明、标签、按钮文案 | 原样保留，不擅自缩写、润色或改写语义 |
+| 分类、卡片、列表等重复条目 | 保留源稿的数量、名称、顺序、分组和对应关系 |
+| 价格、时长、进度、统计等示例值 | 作为初始数据写入数据库，统一单位后由真实 API 返回；页面展示值与源稿一致 |
+| 图片、SVG、图标、CSS 渐变、背景 | 复用或等价转译并保持与条目的映射；不得用生成图片替换已有素材 |
+| 默认选中、筛选、分页、空态和业务状态 | 首次进入时由真实数据与页面状态复现，不用硬编码结果覆盖 API |
+
+**页面可见字段不得静默改写**：凡直接显示或决定页面默认外观的字段，包括文案、字符/图标、图片、颜色、渐变、数值、单位、顺序和默认状态，均须从源稿逐字段传递到其存放位置并到达页面。存放位置按性质划分：业务数据，以及属于单条数据自身内容的视觉值（每条数据自有的封面图、封面渐变、标识色），写入数据库成为初始数据、经接口到达页面；不参与查询和聚合、由设计稿为固定集合指定的纯视觉值（字符图标、装饰 emoji、固定区块配色），作为前端组件常量或主题 token，直接从源稿代码复制。字符图标不得静默改成图标库名称，素材不得改成语义占位符。确有必要转译时，在方案中登记源表示、目标表示、转换实现和验收方式，并验证视觉等价。
+
+规划时对每组默认展示数据登记五项内容：目标页面或区块、源文件与行号区间、全部默认展示字段、数据库与接口与页面链路、原值保留或必要转换策略。字段集合必须完整，但不要把大段源码或全部字段值复制进 plan；重复条目应覆盖所有直接渲染或决定外观的字段（如 `name/icon/count/order`），不得只概括成“若干分类/卡片”。写入初始数据、实现 API 投影或素材映射的 Agent 必须在动手前就近读取对应源文件；不能因为 UI Agent 已读源稿，就依据其摘要重新编造数据。
+
+验收时逐页沿真实链路核对：
+
+源稿可见内容、数据库初始数据与素材、API 返回、页面渲染，四层逐字段一致
+
+数据库非空、接口成功、返回条数正确或页面结构相似都不算通过；必须按方案登记的默认展示字段逐字段核对文案、字符/图标、条目数量与顺序、示例值与单位、素材对应关系和默认状态。
+
+## 前后端接口与数据口径一致
+
+同一业务数据经过前端、API、服务端、数据库或插件时，字段名、类型、单位、取值范围、枚举、是否必填和默认值必须一致。优先在共享接口类型中定义请求与响应结构，前后端不得各自发明不同口径。
+
+只为容易产生歧义的数据建立口径清单，不要罗列所有普通字段。必须登记：金额、比例、时长、距离、时间等带单位字段，状态和类型枚举，单值/多值，可空/选填/默认值，插件结构化输出，以及展示值与存储值不同的字段。
+
+| 业务数据 | 请求/响应字段 | 类型与取值 | 单位/范围 | 服务端与 DB | 页面展示 |
+|----------|---------------|------------|-----------|-------------|----------|
+| 示例：商品价格 | `minPrice` / `maxPrice` | `number` | 分，非负整数 | DB 存分，仅在明确边界转换 | 展示时除以 100 |
+| 示例：搜索类型 | `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` 为准。
+
+| 稿内 UI 语义 | 候选 capability（以动态目录为准） |
+|--------------|-------------------|
+| "AI 生成/智能生成/一键生成文案"、聊天对话框、智能问答 | `ai-text-generate` |
+| "AI 生图/配图/封面生成/头像生成" | `ai-text-to-image` |
+| 上传图片"识别/提取字段"（发票/名片/证件/表单） | `ai-image-to-json` |
+| 上传文档"解析/总结/提炼" | `ai-doc-parser` → `ai-text-to-json` / `ai-text-summary` |
+| "翻译" | `ai-translate` |
+| "语音转写/录音转文字" | `ai-speech-to-text` |
+| 图片"抠图/去背景" | `ai-image-matting` |
+| "发送到飞书/通知群/推送消息" | `send-feishu-message` |
+| "同步到多维表格/写入 Base/存表格" | `feishu-bitable` |
+| "建群/拉群" | `feishu-group-create` |
+
+识别出候选后**召回 `plugin-guide` skill**，由它完成实例复用或创建、运行时合同读取和真实调用。本 skill 不复述插件目录与调用规范。
+
+**边界**：数据库读写、文件上传/存储**不是插件**（内置服务 DataLoom / file-service，走对应 skill）；语义检索走 `semantic-search` skill。别把这三类误建成 capability。
+
+## mock 信号识别表（grep 创意产物定位待替换点）
+
+创意稿无「插件规划」时，AI/飞书能力都是 mock 的。规划阶段 grep 这些信号，逐个登记进方案的 capability 清单：
+
+| mock 反模式 | 典型形态 | 应替换为 |
+|-------------|----------|----------|
+| 假异步 AI | `setTimeout(() => setState(硬编码对象))`、`simulate*`/`mock*`/`fake*` 函数名 | 对应 AI capability |
+| 预置结果数组 | `MOCK_*` / `PRESET_*` 常量假装 AI 生成结果 | 对应 AI capability |
+| 外链占位图 | `picsum.photos` / `placeholder.com` / `unsplash` 替代 AI 生图 | `ai-text-to-image` |
+| 假飞书反馈 | `toast('已发送到飞书')` 无真实调用 | `send-feishu-message` |
+| 随机数假逻辑 | `Math.random()` 替代 AI 分类/评分 | 对应 AI capability |
+
+（"展示用示例数据"是允许的 mock——写入数据库成为初始数据即可，与上面的"插件能力 mock"区分：前者是数据，后者是能力。）
+
+## 方案（plan）必须包含
+
+- **页面清单**：路由 / 页面名 / 来源屏（画板 label 或文件名）
+- **源稿实现定位与默认展示字段归属**：目标页面或区块 / 源文件或区段 / 全部默认展示字段 / DB、API 与页面链路 / 原值保留或必要转译策略 / UI、初始数据、API 与素材负责人；字段集合必须完整，但不复制大段源码或全部字段值
+- **实体与关系**：表、字段、关联、状态机
+- **页面-接口映射**：每页消费/调用哪些接口
+- **可见功能清单**：页面与控件 / 用户操作 / 可见结果 / 实现链路 / 验收方式
+- **数据口径清单（存在易歧义数据时）**：业务数据 / 请求与响应字段 / 类型与取值 / 单位与范围 / 服务端与 DB / 页面展示
+- **持久化业务结果清单（存在需跨刷新/重新进入/异常重试保留或约束后续操作的结果时）**：业务对象 / 操作或事件 / 操作前提 / 成功后的业务结果 / 持久化内容 / 重复与并发处理 / 刷新与异常恢复

package/miaoda/data-analysis/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: data-analysis
+description: "Data analysis and insight extraction skill. Outputs structured JSON for downstream code consumption. MUST be used FIRST when user's message contains or references data file attachments (CSV/Excel/JSON/Markdown), even if the final goal is building a webpage or dashboard. Use when: (1) exploring/comparing datasets, finding patterns/trends/correlations, (2) preparing data for visualization, dashboard, or analysis webpage, (3) assessing data quality or generating statistical reports. Keywords: 分析数据, 数据分析, 统计, 对比, 趋势, 评估, 数据看板, 数据大屏, 分析页面, 分析网页, 数据探索, 数据展示, 找规律, 画图, 报表, 报告, 可视化, 图表, visualize, dashboard, chart, plot, trend, pattern, insight, comparison, overview, correlation"
+---
+
+# Data Analysis
+
+Systematic data analysis workflow that produces structured JSON output for downstream code consumption.
+
+## Execution Flow
+
+When this skill is triggered, execute **ALL** steps below in order. **Do NOT skip any step** — every step is mandatory unless explicitly marked as optional.
+
+1. **Setup tmp directory**: Initialize `tmp/` directory structure in project root. **MUST read `references/tmp-file-management-guide.md` before proceeding.**
+2. **Confirm data source**: Confirm the file path to analyze with user
+3. **Execute Phase 1-3**: Business Understanding → Data Understanding → Quality Assessment (see "Analysis Methodology")
+4. **Report initial findings**: Inform user about data overview and quality issues
+5. **Execute Phase 4-5**: Descriptive Analysis → Insight Extraction (see "Analysis Methodology")
+6. **Generate JSON output**: Save structured result to `tmp/output/`, then copy the JSON files the app will consume to `shared/static/data/` (create the directory if missing) — `tmp/` is gitignored and not deployed, so anything the frontend imports at runtime must live in `shared/static/data/`. **MUST read `references/json-output-specification.md` before generating — do NOT guess the schema.**
+7. **Generate visualizations** (optional): Save charts to `tmp/output/visualizations/`
+8. **[CRITICAL] Update type definitions**: Extract TS type definitions from analysis JSON and append/update to `shared/static/types.ts` (check if file exists first; if not, create it with directory). Naming convention: remove file extension, convert snake_case to PascalCase (e.g. `sales_2023_exploratory.json` → `Sales2023Exploratory`). Do NOT skip.
+9. **[CRITICAL] Update AGENTS.md**: Record analysis summary in AGENTS.md with type definition location and consumption example. **MUST read `references/post-analysis-guide.md` before updating.** Do NOT skip.
+10. **Report output locations**: Inform user where artifacts are saved. **MUST read "Output Summary Template" in `references/post-analysis-guide.md`.**
+
+### Quality Checklist
+
+After completing all steps above, verify the following before considering the task done:
+
+- [ ] **tmp/ directory initialized**: All subdirectories created
+- [ ] **Data quality assessed**: `data_quality` section fully populated
+- [ ] **Statistics complete**: All numeric/categorical columns have corresponding summary
+- [ ] **Insights have evidence**: Every insight has an `evidence` field
+- [ ] **Insights answer business question**: Corresponds to `metadata.business_question`
+- [ ] **JSON conforms to spec**: Field names, types, required fields all correct
+- [ ] **Visualization config is valid**: Field names in `config` exist in the data
+- [ ] **At least 1 recommendation**: `recommendations` is not empty
+- [ ] **No hardcoded paths**: File paths come from user input
+- [ ] **Outputs saved to tmp/**: JSON result and visualizations written to correct locations
+- [ ] **Consumable JSON copied to shared/static/data/**: any JSON the app reads at runtime is copied out of tmp/ (tmp/ is gitignored and not deployed)
+- [ ] **tmp/ in .gitignore**: Ensure tmp/ is excluded from version control
+- [ ] **types.ts updated**: TS type definitions extracted and appended to `shared/static/types.ts` (created if not exists)
+- [ ] **AGENTS.md updated**: Analysis record appended with type definition location and consumption example
+
+---
+
+## Analysis Methodology (6 Phases)
+
+Follow a simplified CRISP-DM methodology. **MUST read `references/python-analysis-reference.md` for Python code templates before writing analysis code.**
+
+### Phase 1: Business Understanding
+
+**Goal**: Clarify the analysis purpose and avoid blind exploration.
+
+1. Confirm analysis type (see "Analysis Type Quick Reference")
+2. Extract the user's core question or hypothesis
+3. Define success criteria: What does the user expect from the analysis?
+
+**Output**: Record in `metadata.analysis_type` and `metadata.business_question` in JSON.
+
+### Phase 2: Data Understanding
+
+**Goal**: Fully understand the structure and content of the data.
+
+1. Load data and get basic information (row/column count, field names, dtypes, sample rows)
+2. Identify field semantics:
+
+| Type | Examples |
+| ---- | -------- |
+| Numeric (continuous) | price, age, amount |
+| Numeric (discrete) | count, quantity |
+| Categorical (ordinal) | rating, education level |
+| Categorical (nominal) | color, city, product name |
+| DateTime | order_date, created_at |
+| Text | description, comments |
+
+3. Initial statistical overview
+
+### Phase 3: Data Quality Assessment
+
+**Goal**: Identify data issues for credibility reference.
+
+| Check | Method |
+| ----- | ------ |
+| Missing values | Per-column missing ratio, random vs systematic pattern |
+| Duplicates | Full-row and key-field duplicates |
+| Outliers | Numeric: IQR or Z-score; Categorical: rare categories |
+| Consistency | Date formats, category value spelling |
+
+**Output**: Populate the `data_quality` section of JSON.
+
+### Phase 4: Descriptive Analysis
+
+**Goal**: Extract statistical characteristics and distribution patterns.
+
+| Sub-phase | Focus | Key Metrics |
+| --------- | ----- | ----------- |
+| 4.1 Numeric | Central tendency & dispersion | mean, median, std, skew, kurtosis, quartiles |
+| 4.2 Categorical | Frequency distribution | unique count, top N values, mode |
+| 4.3 Correlation | Variable relationships | Pearson (linear), Spearman (monotonic), \|r\| > 0.7 = strong |
+| 4.4 Group Aggregation | Group comparisons | group-by mean/std/count |
+
+**Output**: Populate the `statistics` section of JSON.
+
+### Phase 5: Insight Extraction
+
+**Goal**: Extract business-valuable findings from statistical results.
+
+| Type | Identification Criteria | Example |
+| ---- | ----------------------- | ------- |
+| `correlation` | \|r\| > 0.7 or p < 0.05 | "Price and sales show strong negative correlation" |
+| `trend` | Directional change in time series | "Monthly revenue shows continuous growth" |
+| `anomaly` | Beyond 3σ or IQR boundary | "5 anomalous high-value orders detected" |
+| `distribution` | Obvious skewness or multimodal | "Income shows right-skewed distribution" |
+| `comparison` | Significant group differences | "Group A conversion rate significantly higher than Group B" |
+
+Each insight must include: **evidence** (specific supporting data), **significance** (high/medium/low), **affected_columns**.
+
+### Phase 6: JSON Output
+
+Generate structured analysis result. **MUST read `references/json-output-specification.md` and strictly conform to its schema.**
+
+---
+
+## Analysis Type Quick Reference
+
+Select the appropriate analysis focus based on user intent. Phase numbers refer to "Analysis Methodology" above.
+
+| User Expression | Analysis Type | Focus Phase | Key Output |
+| --------------- | ------------- | ----------- | ---------- |
+| "explore data", "overview", "understand data" | `exploratory` | Phase 2-4 | Basic stats, quality report, distribution |
+| "find patterns", "correlations", "relationships" | `exploratory` | Phase 4.3 | Correlation matrix, significant pairs |
+| "compare", "A vs B", "differences" | `diagnostic` | Phase 4.4 | Group statistics, group differences |
+| "validate hypothesis", "significance test" | `confirmatory` | Phase 4-5 | Statistical tests, p-values |
+| "statistics", "summary", "report" | `descriptive` | Phase 4 | Aggregation results, frequency stats |
+| "trend", "changes", "time series" | `exploratory` | Phase 4 | Time series trends, periodicity |
+
+---
+
+## Common Mistakes
+
+| Mistake | Correct Approach |
+| ------- | ---------------- |
+| Analyze directly without checking data quality | Execute Phase 3 first, assess missing values and outliers |
+| Ignore missing values when calculating mean | Clarify missing value handling strategy, or use `dropna()` |
+| Interpret correlation as causation | Explicitly label "correlation" not "causes" in insights |
+| Ignore data types and analyze directly | Confirm dtype first, numeric vs categorical need different handling |
+| Output non-standardized JSON | Strictly follow the Schema in `references/json-output-specification.md` |
+| Insights without supporting evidence | Every insight must have an `evidence` field |
+| Visualization config doesn't match data | Ensure field names in `config` exist in the data |
+| JSON contains NaN/Infinity (TS1328) | MUST sanitize: replace NaN/Infinity with `None` before `json.dump()`, use `allow_nan=False` |
+