@lark-apaas/coding-miaoda-sandbox-skills 0.1.0-dev.ec88bb5 → 0.1.0-dev.f6e7ce8
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/miaoda/animation-skill/SKILL.md +348 -0
- package/miaoda/authz-cli/SKILL.md +1 -0
- package/miaoda/charts-skill/SKILL.md +264 -0
- package/miaoda/creative-to-fullstack/SKILL.md +252 -0
- package/miaoda/creative-to-fullstack/references/artifact-signals.md +46 -0
- package/miaoda/creative-to-fullstack/references/ui-to-function.md +134 -0
- package/miaoda/data-analysis/SKILL.md +151 -0
- package/miaoda/data-analysis/references/json-output-specification.md +277 -0
- package/miaoda/data-analysis/references/post-analysis-guide.md +77 -0
- package/miaoda/data-analysis/references/python-analysis-reference.md +272 -0
- package/miaoda/data-analysis/references/tmp-file-management-guide.md +100 -0
- package/miaoda/debug-investigation/SKILL.md +21 -18
- package/miaoda/extract-json-schema/SKILL.md +147 -0
- package/miaoda/lark-apps/SKILL.md +37 -0
- package/miaoda/lark-apps/references/openapi-key.md +80 -0
- package/miaoda/lark-apps-authz/SKILL.md +292 -0
- package/miaoda/lark-apps-authz/references/permission-points.md +39 -0
- package/miaoda/lark-apps-authz/references/role.md +122 -0
- package/miaoda/lark-apps-db/SKILL.md +219 -0
- package/miaoda/lark-apps-db/references/full-reference.md +413 -0
- package/miaoda/lark-apps-file/SKILL.md +216 -0
- package/miaoda/lark-apps-ops/SKILL.md +63 -0
- package/miaoda/lark-apps-ops/references/lark-apps-access-scope-get.md +30 -0
- package/miaoda/lark-apps-ops/references/lark-apps-access-scope-set.md +40 -0
- package/miaoda/lark-apps-ops/references/lark-apps-cache.md +62 -0
- package/miaoda/lark-apps-ops/references/lark-apps-env.md +46 -0
- package/miaoda/lark-apps-ops/references/lark-apps-local-dev.md +26 -0
- package/miaoda/lark-apps-ops/references/lark-apps-member.md +93 -0
- package/miaoda/lark-apps-ops/references/lark-apps-observability.md +46 -0
- package/miaoda/lark-apps-ops/references/lark-apps-plugin-install.md +36 -0
- package/miaoda/lark-apps-ops/references/lark-apps-plugin-list.md +23 -0
- package/miaoda/lark-apps-ops/references/lark-apps-plugin-uninstall.md +25 -0
- package/miaoda/lark-apps-ops/references/lark-apps-release-create.md +30 -0
- package/miaoda/lark-apps-ops/references/lark-apps-release-get.md +28 -0
- package/miaoda/lark-apps-ops/references/lark-apps-release-list.md +31 -0
- package/miaoda/lark-apps-ops/references/lark-apps-update.md +30 -0
- package/miaoda/lark-apps-ops/references/lark-apps-user-id-convert.md +63 -0
- package/miaoda/lark-apps-ops/references/openapi-key.md +80 -0
- package/miaoda/miaoda-file/SKILL.md +1 -0
- package/miaoda/miaoda-sql/SKILL.md +15 -2
- package/miaoda/performance-review/SKILL.md +144 -0
- package/miaoda/performance-review/references/business-analyzer.md +139 -0
- package/miaoda/performance-review/references/examples.md +107 -0
- package/miaoda/reviewer-usage/SKILL.md +111 -0
- package/miaoda/semantic-search/SKILL.md +0 -1
- package/miaoda/table-skill/SKILL.md +2 -0
- package/miaoda/testing-guide/SKILL.md +220 -0
- package/miaoda-design/lark-apps-comment/SKILL.md +119 -0
- package/miaoda-design/lark-apps-ops/SKILL.md +45 -0
- package/miaoda-design/lark-apps-ops/references/lark-apps-release-create.md +51 -0
- package/miaoda-design/lark-apps-ops/references/lark-apps-release-get.md +28 -0
- package/miaoda-design/lark-apps-ops/references/lark-apps-release-list.md +31 -0
- package/miaoda-design/lark-apps-ops/references/lark-apps-update.md +33 -0
- package/{shared → miaoda-modern}/lark-apps/SKILL.md +5 -5
- package/miaoda-modern/lark-apps/references/openapi-key.md +80 -0
- package/miaoda-modern/lark-apps-ops/SKILL.md +63 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-access-scope-get.md +30 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-access-scope-set.md +40 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-cache.md +62 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-env.md +46 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-local-dev.md +26 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-member.md +93 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-observability.md +46 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-plugin-install.md +36 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-plugin-list.md +23 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-plugin-uninstall.md +25 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-release-create.md +30 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-release-get.md +28 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-release-list.md +31 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-update.md +30 -0
- package/miaoda-modern/lark-apps-ops/references/lark-apps-user-id-convert.md +63 -0
- package/{shared/lark-apps → miaoda-modern/lark-apps-ops}/references/openapi-key.md +3 -3
- package/miaoda-modern/memory/SKILL.md +86 -0
- package/package.json +1 -1
- package/shared/lark-cli/SKILL.md +221 -0
- package/shared/lark-cli/lark-base/README.md +56 -0
- package/shared/lark-cli/lark-base/references/lark-base-commands.md +108 -0
- package/shared/lark-cli/lark-calendar/README.md +158 -0
- package/shared/lark-cli/lark-calendar/references/lark-calendar-meeting.md +30 -0
- package/shared/lark-cli/lark-calendar/references/lark-calendar-room-find.md +108 -0
- package/shared/lark-cli/lark-calendar/references/lark-calendar-suggestion.md +120 -0
- package/shared/lark-cli/lark-contact/README.md +35 -0
- package/shared/lark-cli/lark-contact/references/lark-contact-get-user.md +13 -0
- package/shared/lark-cli/lark-contact/references/lark-contact-search-user.md +121 -0
- package/shared/lark-cli/lark-doc/README.md +67 -0
- package/shared/lark-cli/lark-doc/references/lark-doc-fetch.md +138 -0
- package/shared/lark-cli/lark-doc/references/lark-doc-history.md +61 -0
- package/shared/lark-cli/lark-drive/README.md +158 -0
- package/shared/lark-cli/lark-drive/references/lark-drive-batch-query-comments.md +44 -0
- package/shared/lark-cli/lark-drive/references/lark-drive-files-list.md +183 -0
- package/shared/lark-cli/lark-drive/references/lark-drive-list-replies.md +49 -0
- package/shared/lark-cli/lark-im/README.md +70 -0
- package/shared/lark-cli/lark-im/references/lark-im-chat-list.md +140 -0
- package/shared/lark-cli/lark-im/references/lark-im-chat-members-list.md +84 -0
- package/shared/lark-cli/lark-im/references/lark-im-chat-search.md +135 -0
- package/shared/lark-cli/lark-im/references/lark-im-reactions.md +232 -0
- package/shared/lark-cli/lark-minutes/README.md +51 -0
- package/shared/lark-cli/lark-minutes/references/lark-minutes-download.md +130 -0
- package/shared/lark-cli/lark-sheets/README.md +174 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-changeset.md +105 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-chart.md +45 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-conditional-format.md +42 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-filter-view.md +49 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-filter.md +42 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-float-image.md +43 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-formula-verify.md +64 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-history.md +70 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-pivot-table.md +44 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-read-data.md +286 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-search-replace.md +67 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-sheet-structure.md +52 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-sparkline.md +47 -0
- package/shared/lark-cli/lark-sheets/references/lark-sheets-workbook.md +69 -0
- package/shared/lark-cli/lark-sheets/scripts/lark_detect_subtables.py +593 -0
- package/shared/lark-cli/lark-sheets/scripts/lark_inspect_workbook.py +188 -0
- package/shared/lark-cli/lark-sheets/scripts/lark_profile_table.py +614 -0
- package/shared/lark-cli/lark-sheets/scripts/lark_sheet_range.py +176 -0
- package/shared/lark-cli/lark-sheets/scripts/lark_sheet_read_cli.py +184 -0
- package/shared/lark-cli/lark-sheets/scripts/sheets_df.py +50 -0
- package/shared/lark-cli/lark-slides/README.md +87 -0
- package/shared/lark-cli/lark-slides/references/lark-slides-history.md +117 -0
- package/shared/lark-cli/lark-slides/references/lark-slides-xml-presentation-slide-get.md +108 -0
- package/shared/lark-cli/lark-slides/references/lark-slides-xml-presentations-get.md +77 -0
- package/shared/lark-cli/lark-task/README.md +93 -0
- package/shared/lark-cli/lark-task/references/lark-task-get-my-tasks.md +57 -0
- package/shared/lark-cli/lark-task/references/lark-task-get-related-tasks.md +49 -0
- package/shared/lark-cli/lark-task/references/lark-task-search.md +36 -0
- package/shared/lark-cli/lark-task/references/lark-task-tasklist-search.md +35 -0
- package/shared/lark-cli/lark-vc/README.md +40 -0
- package/shared/lark-cli/lark-vc/references/lark-vc-recording.md +31 -0
- package/shared/lark-cli/lark-whiteboard/README.md +34 -0
- package/shared/lark-cli/lark-whiteboard/references/lark-whiteboard-export.md +59 -0
- package/shared/lark-cli/lark-wiki/README.md +50 -0
- package/shared/lark-cli/lark-wiki/references/lark-wiki-node-get.md +70 -0
- package/shared/lark-cli/lark-wiki/references/lark-wiki-node-list.md +95 -0
- package/shared/lark-cli/lark-wiki/references/lark-wiki-space-list.md +68 -0
- package/miaoda-design/attachment/SKILL.md +0 -58
- package/shared/dev-channel-probe/SKILL.md +0 -40
- /package/{shared → miaoda}/memory/SKILL.md +0 -0
- /package/{shared → miaoda-modern}/animation-skill/SKILL.md +0 -0
- /package/{shared → miaoda-modern}/charts-skill/SKILL.md +0 -0
- /package/{shared → miaoda-modern}/data-analysis/SKILL.md +0 -0
- /package/{shared → miaoda-modern}/data-analysis/references/json-output-specification.md +0 -0
- /package/{shared → miaoda-modern}/data-analysis/references/post-analysis-guide.md +0 -0
- /package/{shared → miaoda-modern}/data-analysis/references/python-analysis-reference.md +0 -0
- /package/{shared → miaoda-modern}/data-analysis/references/tmp-file-management-guide.md +0 -0
- /package/{shared → miaoda-modern}/extract-json-schema/SKILL.md +0 -0
- /package/{shared → miaoda-modern}/performance-review/SKILL.md +0 -0
- /package/{shared → miaoda-modern}/performance-review/references/business-analyzer.md +0 -0
- /package/{shared → miaoda-modern}/performance-review/references/examples.md +0 -0
- /package/{shared → miaoda-modern}/reviewer-usage/SKILL.md +0 -0
- /package/{shared → miaoda-modern}/testing-guide/SKILL.md +0 -0
|
@@ -0,0 +1,252 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: creative-to-fullstack
|
|
3
|
+
description: Use when the task is to build a complete full-stack application from a creative-mode design draft. 触发词:创意设计稿, 将创意设计稿实现为一个完整的全栈应用, 按设计稿开发应用, 基于当前设计生成应用, design to fullstack
|
|
4
|
+
hook: SessionStart
|
|
5
|
+
workspace-contains:
|
|
6
|
+
- source_package/creative/.upgrade-manifest.json
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
# 把创意设计稿实现为全栈应用
|
|
10
|
+
|
|
11
|
+
`source_package/creative/` 是创意模式设计稿,是本次开发的唯一视觉规格。交付标准:
|
|
12
|
+
|
|
13
|
+
1. **视觉与源稿一致**:每个页面的文案、数值、色值、条目与顺序与设计稿逐字段一致。
|
|
14
|
+
2. **可见功能真实可用**:设计稿上每个可交互组件(可点、可输入、可筛选)都产生真实、闭环的结果。
|
|
15
|
+
|
|
16
|
+
两条核心规则:**一切视觉内容直接从源稿代码照抄,不经过任何文字转述**;**动手实现前先完成业务设计并写入 `docs/business-design.md`,后续每个阶段以该文件为执行依据**。
|
|
17
|
+
|
|
18
|
+
## 流程
|
|
19
|
+
|
|
20
|
+
| 步骤 | 做什么 | 谁做 |
|
|
21
|
+
|------|--------|------|
|
|
22
|
+
| 1 | 通读源稿 | 主 Agent |
|
|
23
|
+
| 2 | 业务设计(写入 docs/business-design.md) | 主 Agent |
|
|
24
|
+
| 3 | 基建:结构骨架、建表、初始数据、共享视觉文件、插件实例 | 主 Agent + Worker |
|
|
25
|
+
| 4 | 按业务域派发前后端完整实现 | Worker |
|
|
26
|
+
| 5 | 验收 | 主 Agent + E2E |
|
|
27
|
+
|
|
28
|
+
### 第 1 步:通读源稿
|
|
29
|
+
|
|
30
|
+
读取 `source_package/creative/` 下全部页面源文件(index.html、pages/、components/ 等)。该目录只读,是实现期间反复对照的唯一视觉权威;工程代码不得引用它,也不要修改它。稿内 `data-miaoda-*` 属性与 `<script type="text/babel">` 是创意平台预览机制,本工程不使用。
|
|
31
|
+
|
|
32
|
+
### 第 2 步:业务设计(主 Agent 的核心职责)
|
|
33
|
+
|
|
34
|
+
从源稿可见信息推断应用的业务模型。完成以下四项分析,**写入工程文件 `docs/business-design.md`**,作为第 3/4/5 步的执行依据:
|
|
35
|
+
|
|
36
|
+
**2.1 业务域划分**。按「业务模块闭环拆解规则」(见下方规则章节)从源稿划分业务域,产出各域的名称、覆盖的源稿页面与功能、服务端模块归属。
|
|
37
|
+
|
|
38
|
+
**2.2 数据模型**。以 2.1 划定的业务域为单位设计数据库。源稿页面上的展示数据分两类去向:与服务端逻辑相关的写入数据库、经服务端接口回到页面;不相关的以前端代码的形式展示。按以下顺序执行:
|
|
39
|
+
|
|
40
|
+
1. **设计表结构**:为每个业务域设计该域的业务实体表,产出表名、字段(含类型)、表间关联。字段以支撑 2.3 的功能为准:筛选器的每个筛选维度要有对应字段,状态流转的状态字段枚举值从源稿可见的状态文案提取,插件结果需落库的(见拆解规则第 4 条)预留对应字段。建模范围按以下两条判据裁剪,**命中任一即入库**:
|
|
41
|
+
|
|
42
|
+
- 参与服务端逻辑:查询、筛选、排序、聚合、写入、状态变化;
|
|
43
|
+
- 属于开放集合实体的页面可见内容:实体会随业务增长(人、内容条目、业务记录等)时,该实体在页面上呈现的一切内容都入库,包含纯展示的长文本与列表——页面按实体标识渲染,写死会让所有实体呈现同一份内容。
|
|
44
|
+
|
|
45
|
+
两条都不命中的留在前端代码中:
|
|
46
|
+
|
|
47
|
+
- 与页面结构绑定的固定文案:区块标题、页脚文案、静态导航项;
|
|
48
|
+
- 封闭枚举实体的装饰字段:实体是页面上固定的少数几项且不随业务增长时,其图标、配色不入库;该实体因参与筛选等逻辑而入库时也不带这些字段,由前端按实体标识映射;
|
|
49
|
+
- 平台内置服务已覆盖的数据(如用户信息、文件存储)不建表,使用内置服务。
|
|
50
|
+
|
|
51
|
+
2. **确定建表顺序**:存在引用关系的表,被引用的表先建;该顺序供 3.2 建表与 3.3 数据写入按序执行。
|
|
52
|
+
|
|
53
|
+
3. **标注数据来源**:为第 1 步建模的每张表标注初始数据取自哪个源稿文件、哪个区块;同一张表的数据散落在多个页面时逐条列全。只写位置指针,**设计文档中禁止出现任何初始数据内容**——不写字段值、不写示例记录、不做数据摘要;数据内容只在 3.3 执行时由 Worker 从源稿誊写,设计文档中出现的数据值一律不作为写入依据。
|
|
54
|
+
|
|
55
|
+
**2.3 可见功能业务模型与 API 设计**。按 2.1 的业务域逐域进行,为每个域产出核心功能清单与接口设计。范围界定:仅涉及页面内交互、不读写业务数据的行为(Tab 切换、折叠展开、弹窗开关、表单字段校验)随页面视觉还原自然实现,不进入本节设计。
|
|
56
|
+
|
|
57
|
+
对每个业务域依次完成:
|
|
58
|
+
|
|
59
|
+
1. **识别核心功能**。从该域覆盖的源稿页面中,按以下类型识别核心功能(组件类型与功能信号的对照见 [references/ui-to-function.md](references/ui-to-function.md)):
|
|
60
|
+
- 业务数据的写操作:新建、编辑、删除、提交、状态变更;
|
|
61
|
+
- 影响数据展示范围与形态的读操作:搜索、筛选、排序、分页;
|
|
62
|
+
- 页面间的业务流转:列表项进详情、详情进编辑等携带真实数据的跳转;
|
|
63
|
+
- 涉及外部能力的操作:上传、AI 处理、消息通知、定时任务。
|
|
64
|
+
|
|
65
|
+
每条功能记录为:「功能名称 + 所在页面 + 用户操作与预期结果」;操作结果需要跳转到另一个页面时一并写明目标页面,目标页面不在源稿里时标注为新增页面,由 3.1 规划路由与占位。
|
|
66
|
+
|
|
67
|
+
2. **能力选型**。对每条核心功能按以下顺序判定实现方式:
|
|
68
|
+
- 平台内置服务(用户、文件、权限、消息、自动化/定时)可满足 → 直接使用,标注「使用平台内置服务:[服务名]」,禁止自建同等能力;
|
|
69
|
+
- 功能涉及 AI、智能、自动生成、大模型、文本生成、图片生成、飞书、消息通知、群组、机器人等能力 → 判定为插件能力,登记进 2.4 做插件设计;普通前后端能可靠实现的不硬凑插件;
|
|
70
|
+
- 两者都不满足 → 自建服务端 API,进入第 3 条。
|
|
71
|
+
|
|
72
|
+
判定插件能力时同时对照源稿代码补漏:用假逻辑模拟、但未以可交互组件呈现的此类能力(如定时提醒、自动通知),一并登记进 2.4。
|
|
73
|
+
|
|
74
|
+
3. **API 设计**。为自建 API 的功能设计接口:
|
|
75
|
+
- 同一数据实体的操作合并设计:列表查询一个接口,入参覆盖该页全部筛选维度、搜索关键词与分页参数;新建、更新、删除、详情各一个接口;
|
|
76
|
+
- 每个接口写明:方法与路径、入参与出参、读写的表、支撑的功能。
|
|
77
|
+
|
|
78
|
+
本节产出是第 4 步各域任务服务端子步骤的实现范围(域任务的 Service/Controller 按 API 清单逐接口实现),也是第 5 步核心验收目标的选取来源。
|
|
79
|
+
|
|
80
|
+
**2.4 插件设计(条件步骤,仅当 2.3 判定出插件能力时执行)**。先读取 `plugin-guide` skill 了解插件目录与调用规范,然后对 2.3 登记的插件需求逐项设计。
|
|
81
|
+
|
|
82
|
+
设计原则:
|
|
83
|
+
|
|
84
|
+
- **原子化拆分**:一个插件实例只做一件事——不同输出类型(文本/图片/消息)建独立实例,不同业务语义(如标题与正文)建独立实例;
|
|
85
|
+
- **链路完整性**:从用户输入到展示/落库,每一步都有对应插件——链式场景如文档解析→结构化提取需要两个插件;
|
|
86
|
+
- **调用方式选择**:默认前端 capabilityClient 直接调用;以下情形改为服务端调用并说明原因:调用前需验证权限、需记录调用日志、结果需先落库、定时任务或 Webhook 无前端上下文、需聚合多个插件结果。
|
|
87
|
+
|
|
88
|
+
输出格式,每个插件一行:
|
|
89
|
+
|
|
90
|
+
| 插件名称 | 基础插件 | 用途 | 调用方式 | 关联页面/接口 | 输入参数 | 输出类型 |
|
|
91
|
+
| --- | --- | --- | --- | --- | --- | --- |
|
|
92
|
+
|
|
93
|
+
`docs/business-design.md` 写完后,用 TodoWrite 建执行清单,条目至少覆盖:每个基建项、每个业务域实现任务、**验收任务**(此刻即加入清单)。
|
|
94
|
+
|
|
95
|
+
### 第 3 步:基建
|
|
96
|
+
|
|
97
|
+
**执行者划分(不可调整)**:凡产出承载源稿可见内容(文案、色值、条目、数值、素材)的,一律派 Worker 实现——Worker 的任务范围窄、开工即按标注读取源稿,写前必然读到原文;主 Agent 亲写的范围只有纯结构骨架与数据库 DDL,这两类没有任何内容取自源稿。初始数据既承载源稿内容、又需要执行 SQL,派 `CodeAct`——它兼具读文件与执行能力,读源与写库在同一上下文内完成。主 Agent 不得亲自编写页面、组件、导航、页脚、主题色板、Service、Controller,也不得凭通读记忆写入任何源稿可见内容。
|
|
98
|
+
|
|
99
|
+
**派发指令的内容边界(所有派发通用)**:派发指令只写任务目标、源稿位置、验收标准。**禁止在指令里复述源稿的任何具体内容**——色值、文案、条目、名称、数值一律不写,主 Agent 通读源稿形成的记忆不得以任何形式进入指令;Worker 需要的源稿内容由它自己按位置读取。每个派发任务都要带**双权威声明**:视觉、文案、色值、数据以源稿源码为唯一权威,工程契约(路由、表结构、接口、插件实例)以落盘文件为准,指令中的文字描述仅作辅助,与两者冲突时以文件为准——**指令里出现的源稿内容不作为实现依据**。
|
|
100
|
+
|
|
101
|
+
**3.1 代码架构设计与结构骨架(主 Agent)**。先读取 coding-guide skill 了解项目编码规范与目录结构。本步分先后两段:先完成全部规划,再一次性落盘所有会被多个后续任务共同引用或修改的结构文件;禁止边实现边定结构。
|
|
102
|
+
|
|
103
|
+
第一段,规划内容:
|
|
104
|
+
|
|
105
|
+
- 前端目录结构:pages、页面内组件、跨页面公共组件、hooks/api/types/utils 的文件归属,明确入口页文件位置;
|
|
106
|
+
- 路由与导航结构:源稿每个页面一条路由,加上 2.3 记录的新增页面(路径语义化,不用查询参数冒充路由)、默认页、Layout 承载方式与菜单入口;
|
|
107
|
+
- 服务端模块边界:按 2.1 的业务域确定各模块的目录与内部文件结构;
|
|
108
|
+
|
|
109
|
+
第二段,落盘结构文件——**只落结构,不写任何源稿可见内容**:
|
|
110
|
+
|
|
111
|
+
- 全局路由配置与默认页;
|
|
112
|
+
- Layout 容器:只搭出页面容器与内容插槽,**不写导航项、logo、搜索框、按钮文案与色值**(这些属于 3.4);
|
|
113
|
+
- 占位页面:为源稿每个页面与 2.3 记录的新增页面创建最小可渲染的占位页并接入路由,路由挂载不得引用不存在的页面;页面真实内容由第 4 步实现;
|
|
114
|
+
- shared 契约类型:按 2.2 表结构与 2.3 接口设计,定义实体类型和各接口的请求/响应类型;
|
|
115
|
+
- 服务端模块注册骨架:每个业务域一个空 Module + 空 Service/Controller 类,**类体保持为空**——不写任何方法、查询或业务逻辑,这些属于第 4 步域任务。
|
|
116
|
+
|
|
117
|
+
规则:
|
|
118
|
+
|
|
119
|
+
- 提交时工程可编译运行,禁止引用后续任务才会创建的页面或模块;
|
|
120
|
+
- 完成后对照源稿检查:每个页面都有路由与目录归属、每个业务域都有模块边界与契约类型,发现缺失在本步补齐;
|
|
121
|
+
|
|
122
|
+
**3.2 建表(主 Agent)**。按 `docs/business-design.md` 2.2 确定的建表顺序逐张建表,被引用的表先建。表结构取自 2.2 设计,不涉及源稿内容誊写。只建 2.2 建模的表——不参与服务端逻辑的展示数据没有对应表,保留在前端代码中。建完后跑数据库 schema 代码生成刷新 `server/database/schema.ts`:它是真实列名与类型的唯一来源,3.3 的 Worker 无法查库,只能靠这个文件。
|
|
123
|
+
|
|
124
|
+
**3.3 初始数据插入(派 CodeAct)**。数据内容必须由读到源稿原文的执行者当场写入,读源与写库之间不经过任何交接。
|
|
125
|
+
|
|
126
|
+
派发对象:`CodeAct`——它同时具备读文件与执行 SQL 的能力,读完源稿即可落库,报错时源稿仍在上下文中可直接改正。
|
|
127
|
+
|
|
128
|
+
**派发内容**:本次负责的表清单、每张表在 2.2 的源稿位置标注、建表顺序、`server/database/schema.ts` 的路径。
|
|
129
|
+
|
|
130
|
+
**任务要求**:
|
|
131
|
+
|
|
132
|
+
- 按标注打开源稿文件、定位到该区块后再写;区块落在文件后段时读到该区块为止,禁止只凭文件开头写数据;
|
|
133
|
+
- 列名与类型照 `server/database/schema.ts`;`_` 前缀的系统字段与主键不写,由数据库默认值生成;
|
|
134
|
+
- 字段值逐字原样来自读到的源稿原文,**这是誊写不是创作**:不改写措辞、不缩写字段值、不换算数值、不增删记录、不补充源稿没有的条目;
|
|
135
|
+
- 源稿里属于该表的可见记录全部写入,一条不漏;同一实体在多个页面出现时按标识字段去重、合并各页可见字段,不重复插入;
|
|
136
|
+
- 子表外键用 `SELECT` 子查询按业务键(标题、名称等)关联父行,禁止硬编码 UUID。
|
|
137
|
+
|
|
138
|
+
**权限边界**:只允许对 2.2 建模的表执行 `INSERT` 与必要的 `SELECT`。出现 `DDL` / `UPDATE` / `DELETE`、或写入 2.2 未建模的表,均为越界。
|
|
139
|
+
|
|
140
|
+
达标标准:每张表在源稿页面上可见的记录,首次查询即可返回且内容与源稿一致。禁止把初始数据做成运行时 mock 接口或前端写死。
|
|
141
|
+
|
|
142
|
+
**3.4 共享视觉文件(派发 Worker,域任务之前串行完成)**。导航、页脚、主题色板承载源稿可见内容,且被所有页面引用,必须由单一 Worker 一次写完,禁止主 Agent 代写、禁止拆给多个域任务并行写。
|
|
143
|
+
|
|
144
|
+
派发时给出源稿共享组件文件与设计 token 文件的位置,由 Worker 自行读取。任务范围:
|
|
145
|
+
|
|
146
|
+
- 导航:项数、文案、顺序、logo 形态、搜索框、操作区按钮全部照源稿组件转写;链接先读既定路由文件,只指向已注册路由,无承载页面的项保持不可跳转;
|
|
147
|
+
- 页脚:源稿有页脚的页面共用同一个页脚组件,分栏、项数、文案照抄;
|
|
148
|
+
- 主题文件:源稿设计 token 的色值、字体逐条写入,色值原样,不做近似换算或色彩空间转换。
|
|
149
|
+
|
|
150
|
+
回传后主 Agent 打开源稿对应位置核对导航项数、文案、顺序与主题色值,不一致立刻退回重做;核对通过后,第 4 步各域页面直接复用这些组件与主题变量,不再逐页另行实现。
|
|
151
|
+
|
|
152
|
+
**3.5 插件实例(条件步骤,2.4 有产出时执行;主 Agent)**。按 2.4 清单逐个建实例并确认契约,调用代码由第 4 步域任务实现:
|
|
153
|
+
|
|
154
|
+
1. 调用 `plugin_instance` 工具创建插件实例;禁止手工修改 `server/capabilities/` 目录;
|
|
155
|
+
2. 获取运行时 schema,逐字段确认 inputSchema 与 outputSchema 的字段名、类型、是否必填;
|
|
156
|
+
3. 把实例名与 schema 摘要(字段名、类型、必填)写进该插件所属域的派发指令,供域任务按 schema 编写调用代码。
|
|
157
|
+
|
|
158
|
+
规则:
|
|
159
|
+
|
|
160
|
+
- 禁止只创建实例而不在域任务中安排调用代码——未生成调用代码的插件实例是无效的;
|
|
161
|
+
- 域任务编写调用代码时,入参出参的字段名与类型以运行时 schema 为准,禁止从设计文档推测(设计可能与插件实际 schema 不一致);入参中的动态配置值(接收人、通知模板、阈值等)禁止硬编码,从配置表或平台 API 获取;
|
|
162
|
+
- 插件结果需要持久化时,优先在该域 Service 内调用插件并在同一方法内落库;保持前端调用的,成功后通过已有业务 CRUD 接口保存结果,不为此单独新建 API;
|
|
163
|
+
- 后续任一阶段发现缺插件实例,主 Agent 立即用 `plugin_instance` 工具补建,禁止用 pluginKey 冒充 instanceId 调用或跳过该功能。
|
|
164
|
+
|
|
165
|
+
### 第 4 步:按业务域派发实现(Worker)
|
|
166
|
+
|
|
167
|
+
按「业务模块闭环拆解规则」把每个业务域派发为一个 Worker 任务。派发前重读 `docs/business-design.md`,按其中的业务域划分逐域生成任务。
|
|
168
|
+
|
|
169
|
+
**核心原则**
|
|
170
|
+
|
|
171
|
+
- 任务范围是该域的前后端完整实现:Service、Controller、页面、组件、接口集成都在同一个任务内;
|
|
172
|
+
- 服务端代码不得摘出来由主 Agent 代写——Worker 跑不了接口测试与运行时日志是预期的,运行时验证统一在第 5 步做;
|
|
173
|
+
- **派发指令不写源稿的具体内容**: 避免实现时没有按照原稿而是按照指令开发。
|
|
174
|
+
|
|
175
|
+
**每个任务必须携带**:
|
|
176
|
+
|
|
177
|
+
- 权威文件位置:该域相关的源稿文件、`docs/business-design.md`、该域的 shared 契约文件与既定路由文件——只给路径,禁止用文字概述替代源文件,由 Worker 自行读取;
|
|
178
|
+
- 双权威声明:视觉、文案、布局、数据以源稿源码为唯一权威;表结构、API、插件调用以 `docs/business-design.md` 该域章节为准;
|
|
179
|
+
- 一句话验收标准(acceptance),落在真实能力层(如「提交后经真实接口落库且刷新后可回查」),达标即完成,禁止超出标准的冗余自查。
|
|
180
|
+
|
|
181
|
+
**任务内执行顺序**
|
|
182
|
+
|
|
183
|
+
1. 读取 coding-guide 及与本域相关的 skill;
|
|
184
|
+
2. 读源稿该域文件,读 `docs/business-design.md` 该域章节(功能清单、表结构、API 清单);
|
|
185
|
+
3. 检查 shared 契约与该域表结构、接口设计一致;按 3.1 既定的目录结构落文件,不另建与之平行的目录;
|
|
186
|
+
4. Service 层:业务编排、落库、插件调用聚合、内置服务调用;服务端调用的插件逐条写明「调用 [实例名],触发条件为 [条件]」;
|
|
187
|
+
5. Controller 层:REST API,按该域 API 清单逐接口实现,避免纯透传接口;
|
|
188
|
+
6. 页面接入既定路由,不改全局结构;
|
|
189
|
+
7. 页面与组件实现:打开源稿对应区段对照实现,文案、色值、条目数量与顺序、示例值照源码转写;页面数据一律来自本域真实接口,禁止 mock 业务数据;组件不拆出独立任务;
|
|
190
|
+
8. 前端插件集成(2.4 设计为前端调用的插件):获取插件运行时 schema,按 schema 调用 [实例名];结果需持久化的,调用成功后通过已有业务接口保存;
|
|
191
|
+
9. 代码级自查:类型一致性、契约覆盖、shared 定义对齐;禁止运行时验证(见拆解规则第 7 条)。
|
|
192
|
+
|
|
193
|
+
指令里给出的文件路径是**必读下限,不是可读上限**:实现中需要的其他工程文件(既有组件、工具函数、全局配置、路由表)一律按需自行读取。禁止的是重新推导架构:不重新规划目录与路由结构、不反复 glob 全工程、不修改允许范围外的文件。
|
|
194
|
+
|
|
195
|
+
Worker 回传后,主 Agent 至少读一个关键产物文件抽查(页面是否调真实 API、功能链路是否接通);回传中的「已完成、已验证」不作为核验依据。
|
|
196
|
+
|
|
197
|
+
**自动化任务**:2.3 中选型为平台自动化内置服务的功能(定时触发、数据变更触发),作为独立任务实现,依赖其用到的表与插件:
|
|
198
|
+
|
|
199
|
+
1. 读取 trigger-guide skill 了解触发器配置与代码开发规范;
|
|
200
|
+
2. 创建触发器,实现任务逻辑:触发条件判断、去重、插件调用、状态更新;
|
|
201
|
+
3. 完成后验证代码可编译。
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
### 第 5 步:验收(清单里的任务,不是可选动作)
|
|
205
|
+
|
|
206
|
+
commit 的静态检查只覆盖编译与 lint,证明不了功能可用与视觉一致。验收开始前先读取 testing-guide skill 了解 E2E 验收流程,并重读 `docs/business-design.md`,以其中的 2.3 功能与 API 清单为验收目标来源。按以下结构执行,完成前不得提交收尾:
|
|
207
|
+
|
|
208
|
+
1. **架构与入口检查**:先对照 3.1 检查路由、shared 契约、模块边界是否被遵守,对照 3.4 检查导航、页脚、主题色值是否与源稿一致,发现偏离先修结构再继续。再做三项核对:
|
|
209
|
+
- **链接目标可达**:枚举代码中全部跳转目标(导航项、按钮、卡片、搜索、面包屑)与路由表比对,任一指向未注册路由即未通过;
|
|
210
|
+
- **页面均有入口**:每个已注册页面至少有一个应用内可达入口,只能手输 URL 到达的页面即未通过;
|
|
211
|
+
- 应用入口页面可正常打开,打不开(白屏 / Page not found)则停止验收,只记录阻塞问题。
|
|
212
|
+
2. **核心验收目标 1~3 个**(超过 3 个属于错误输出):从 2.3 的功能映射中选取最核心的业务链路,每个目标写成「验收对象 —— 可判定的通过标准」。通过标准必须是应用内可判定的结果:状态更新、提交后列表刷新、成功/失败提示、结果区出现内容或错误态、确认弹窗、详情数据变化;「页面渲染正常」「控件可见」「按钮可点击」不构成通过标准。派发 E2E agent 实际执行这些目标。
|
|
213
|
+
3. **非核心降级范围**:AI 内容质量、真实消息送达、复杂批量数据一致性、导出文件内容正确性、低风险视觉细节可降级不阻塞;但被降级能力在应用内的触发、状态与错误反馈仍必须保留在核心验收目标中,不得完全消失。
|
|
214
|
+
4. **数据核对**:对每张初始数据表做 COUNT 与文案抽查,与源稿对照;条数或文案不符即为未通过。
|
|
215
|
+
5. **静态残留检查**:grep 两类问题,任一命中即未通过——
|
|
216
|
+
- 假实现:simulate、写死结果的 setTimeout、picsum、假 toast、Math.random 业务值;
|
|
217
|
+
- 无行为的可点击元素:按钮与带可点击外观的元素是否都有事件处理或路由跳转。
|
|
218
|
+
6. **验收对照表**:把以上结果逐项列出后再提交。未执行的项写明原因,不得笼统声称"验收通过"。
|
|
219
|
+
7. **摘除注入标记**:以上各项全部通过后执行 `rm -f source_package/creative/.upgrade-manifest.json`。该文件是本指引的 SessionStart 注入门控,删除后本指引停止注入,后续迭代不再重复进入升级流程;源稿其余文件保留供以后对照。任一项未通过时不得删除——下轮修复仍需本指引在场。
|
|
220
|
+
|
|
221
|
+
## 业务模块闭环拆解规则
|
|
222
|
+
|
|
223
|
+
按业务域(Module)拆分实现任务,每个任务同时覆盖该域的服务端实现(Service + Controller + DTO)与对应前端页面(路由 + 页面 + 组件 + 接口集成),命名为 `[业务模块名]模块开发(含前后端)`。**同一业务域的前后端禁止拆成独立任务**。与通用全栈开发的唯一差异:拆解依据是**创意模式的源稿代码**(页面结构与可见交互组件),而非需求文档。
|
|
224
|
+
|
|
225
|
+
1. **模块边界判定**:任务拆分优先服从代码所有权边界,而非仅按页面归属或功能语义拆分。若多个页面、功能最终落在同一个 server module 中实现,必须合并为同一个模块任务,不得拆成多个并行任务。
|
|
226
|
+
2. **server module 判定口径**:同一个 server module 包括但不限于同一业务目录下的 Service、Controller、DTO、Repository、模块注册文件、聚合导出文件,以及需要共同修改的 shared 契约文件。
|
|
227
|
+
3. **纯展示/即时场景**:若某业务功能已规划在前端使用插件实现,且不需要数据库存储,则该模块任务中无需包含服务端 Service/Controller 子步骤,仅保留前端 + 插件集成。
|
|
228
|
+
4. **需持久化场景**:若插件调用的结果需要保存到数据库,优先在该模块的 Service 中调用插件并落库;或在已有业务 CRUD 接口中扩展字段接收前端传来的插件结果。禁止为"保存插件结果"单独新建模块。
|
|
229
|
+
5. **平台内置服务**:模块内需使用的平台内置服务,在该模块的 Service 部分完成配置与调用。
|
|
230
|
+
6. **入口模块优先**:将承载入口页(列表页/首页)的模块任务置于全部模块任务的第一项。
|
|
231
|
+
7. **并行安全**:模块任务内**禁止包含运行时验证**(接口冒烟测试、启动前后端服务联调、读取服务端/前端运行时错误日志、E2E 测试),统一推迟到第 5 步验收阶段。允许保留的验证限定为代码级静态自查(类型一致性、契约覆盖、shared 定义对齐)。
|
|
232
|
+
8. **精确依赖**:每个模块任务只依赖基建(结构骨架 + 共享视觉文件 + 自身所需的表与初始数据 + 插件实例);模块任务之间无数据依赖时全部可并行,禁止链式依赖。
|
|
233
|
+
9. **粒度保底**:单个模块子步骤明显超限时,允许拆为 `[模块名]服务端开发` + `[模块名]前端开发` 两个任务,前端任务依赖同模块服务端任务,仅此一种拆法。
|
|
234
|
+
|
|
235
|
+
## 视觉一致性规则(全程适用)
|
|
236
|
+
|
|
237
|
+
- 布局用 flex/grid 加 gap 直接转写源稿结构,不重新设计。
|
|
238
|
+
- 页面一切可见内容(文案、数值与单位、条目数量与顺序、色值、字符图标、选中状态、素材)与源稿逐字段一致:入库的经初始数据与接口到达页面,前端的直接从源稿代码复制。
|
|
239
|
+
- 字符图标保持原字符;源稿已有的图片、SVG、CSS 渐变复用或等价转写,不得用生成图替换。
|
|
240
|
+
- 写任何产生页面可见内容的代码之前,重新打开源稿对应位置读取。
|
|
241
|
+
- 确有必要的转换(如固定画布改响应式)需说明转换前后形态,且不改变源稿参考尺寸下的构图。
|
|
242
|
+
|
|
243
|
+
## 功能真实性规则(全程适用)
|
|
244
|
+
|
|
245
|
+
- 写操作必须走完「前端事件 → 接口 → 数据库/插件 → 界面反馈」全链路,写入结果刷新后仍能读到。
|
|
246
|
+
- 搜索、筛选、排序、分页的参数必须传入真实查询;跳转、Tab、弹窗到达正确的路由或状态。
|
|
247
|
+
- **链接目标必须存在**:写任何跳转前先读既定路由文件,目标只能是已注册路由。源稿有入口但应用内无承载页面时,只有两条出路——回到 2.3 的功能记录里补上新增页面并在 3.1 注册路由后实现,或让该元素保持不可跳转;禁止指向未注册路由。
|
|
248
|
+
- 持久化业务结果由服务端校验前提并写入,前端只展示重新读取的事实。
|
|
249
|
+
- 有数据库时禁止用 mock 数据代替真实查询;插件返回值严禁 mock,前端用 capabilityClient 真实调用,或调用集成了插件的真实服务端接口。
|
|
250
|
+
- 自建 HTTP API 不实现 SSE/WebSocket;插件链路的流式输出(outputMode=stream)不受此限。
|
|
251
|
+
- **可点击外观与真实行为必须同时存在**:转写源稿的按钮与可点击元素时,能用 2.3 已设计的接口或既定路由接上的直接接上;接不上的改成非交互形态——去掉指针手型与按钮态、或呈现禁用态,并在回传中列出这些元素与接不上的原因,由主 Agent 决定是否回到 2.3 补设计。禁止保留看起来能点、点了没反应的元素。
|
|
252
|
+
- 禁止:空链接、只切换图标不产生数据变化、写死的"成功"提示。
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# 创意产物类型信号表与分类型拆分细则
|
|
2
|
+
|
|
3
|
+
创意模式产物是 design-html 技术栈的静态工程:`index.html` 为入口,可能带 `components/` 或 `screens/` 目录(`.jsx` 经 `<script type="text/babel">` 在浏览器内编译)。先读 `index.html` 全文 + 目录清单,再按下表判类型。**支持生成的只有前三行**(产品设计=多屏设计稿/移动端 mockup、可交互原型);报表/deck/动画为产品范围外,判中即停止并告知用户(入口层正常会拦截,此为防御兜底)。若会话上下文提供了「当前选中的设计稿文件」路径,判型与拆分优先以该文件为主入口。
|
|
4
|
+
|
|
5
|
+
## 类型判定信号表
|
|
6
|
+
|
|
7
|
+
| 类型 | 判定信号(任一命中) | 实现形态 |
|
|
8
|
+
|------|---------------------|----------|
|
|
9
|
+
| 演示稿(deck) | `<deck-stage>` / 翻页控件 / 每屏是「第 N 页」式幻灯结构 | **范围外,停止并告知** |
|
|
10
|
+
| 多屏设计稿(artboard) | `<DCArtboard>` / `design-canvas` 缩放壳 / 多画板平铺 + 画板 label | 每画板 → 路由页 |
|
|
11
|
+
| 移动端 mockup | 设备框组件(iOS/Android 壳:`width:390` + 圆角 + 状态栏/灵动岛) + `screens/` 或 `screen-*.jsx` 多屏 | 每屏 → 路由页;框内 tab → 应用导航 |
|
|
12
|
+
| 交互原型 | `useState` / 事件处理驱动页面切换,无画布壳,本身像单页应用 | 按其内部「视图状态」拆路由页 |
|
|
13
|
+
| 报表看板 | echarts / 图表库 + 指标卡片布局 | **范围外,停止并告知** |
|
|
14
|
+
| 纯动画/视觉演示 | 大量 keyframes/canvas 动画、无业务 UI | **范围外,停止并告知** |
|
|
15
|
+
|
|
16
|
+
混合信号时以「业务 UI 占比」为准:有表单/列表/详情等业务界面 → 按设计稿/原型类正常生成(防止 deck 里嵌了真实业务界面设计被误杀);纯展示 → 判为范围外。
|
|
17
|
+
|
|
18
|
+
## 分类型拆分细则
|
|
19
|
+
|
|
20
|
+
### 多屏设计稿 / 移动端 mockup
|
|
21
|
+
|
|
22
|
+
1. 枚举所有屏:`data-screen-label` 属性、画板 label、`screen-*.jsx` 文件名,三者取有值的作为页面名与路由名来源。
|
|
23
|
+
2. 稿内导航(底部 tab / 侧边栏 / 顶部菜单)转为工程导航结构;未出现在导航里的屏(如详情页、由弹层提级的独立页)按从属关系挂到父页面路由下。
|
|
24
|
+
3. 导航项逐项承接源稿:数量、文案、顺序与源稿一致。源稿导航中没有对应画板的项不得删除,也不得添加源稿没有的导航项;这类项的点击去向在方案中写明(例如指向相关页面的对应区块,或在方案的未决事项中说明),不得静默决定。
|
|
25
|
+
4. 设备框(手机壳、浏览器壳、`IOSFrame` 这类组件)是预览容器:取 `children` 内容做响应式页面;状态栏、灵动岛、Home 指示条随壳丢弃。
|
|
26
|
+
5. 稿内固定尺寸(390×844、1920×1080 加 scale 缩放)改为真响应式:内容宽度用容器约束(如 `max-width` + 居中),移动优先或桌面优先取决于原稿形态。
|
|
27
|
+
|
|
28
|
+
### 交互原型
|
|
29
|
+
|
|
30
|
+
1. 找出所有「视图状态」:`useState` 切换的 tab/step/modal 中承载独立业务界面的 → 路由页;纯交互细节(折叠、hover)→ 保留为组件内交互。
|
|
31
|
+
2. 原型里已经写了的交互逻辑(校验提示、乐观更新、步骤流转)是功能需求的最强信号,逐条纳入第 2 步的可见功能清单。
|
|
32
|
+
|
|
33
|
+
### 报表看板
|
|
34
|
+
|
|
35
|
+
范围外类型,不做生成。若混合产物中局部包含图表且整体被判为设计稿/原型类,图表部分按 `ui-to-function.md` 的"统计卡片/图表"映射行处理。
|
|
36
|
+
|
|
37
|
+
## 稿内机制识别速查
|
|
38
|
+
|
|
39
|
+
| 稿内出现 | 含义 | 处置 |
|
|
40
|
+
|----------|------|------|
|
|
41
|
+
| `<script type="text/babel">` + `@babel/standalone` | 浏览器内编译 JSX 的预览机制 | 内容重写为工程组件,机制丢弃 |
|
|
42
|
+
| `unpkg-sdk/react@*/umd/*.js`(miaoda.feishu.cn 镜像) | CDN React 运行时 | 丢弃,用工程自带 React |
|
|
43
|
+
| `Object.assign(window, { Xxx })` | 组件挂全局供跨 `<script>` 引用 | 转译为模块 import/export |
|
|
44
|
+
| `data-miaoda-*` / `data-screen-label` | 创意平台标注属性 | 属性丢弃;label 值用作路由/导航命名后即弃 |
|
|
45
|
+
| `miaoda.feishu.cn/fonts/css2?family=...` | 字体镜像 | 保留,生产可用 |
|
|
46
|
+
| tweaks / EDITMODE 面板 | 设计期调参 | 当前参数值固化进主题 token,面板删除 |
|
|
@@ -0,0 +1,134 @@
|
|
|
1
|
+
# UI→功能推导映射表
|
|
2
|
+
|
|
3
|
+
设计稿里的每个 UI 元素都是功能需求的证据。本表把「稿子上画了什么」翻译成「工程要实现什么」:数据模型、接口、页面行为三层缺一不可。
|
|
4
|
+
|
|
5
|
+
## UI→功能映射表
|
|
6
|
+
|
|
7
|
+
| 稿内 UI 元素 | 数据模型 | 接口 | 页面行为 |
|
|
8
|
+
|--------------|----------|------|----------|
|
|
9
|
+
| 表单(输入框/选择器/提交按钮) | 表单字段 → 实体字段(含类型与必填) | 创建/更新写入接口 + 校验 | 提交、校验提示、成功/失败反馈 |
|
|
10
|
+
| 列表/卡片流 | 列表项字段 → 实体查询投影 | 查询接口:排序、过滤、分页 | 空态、加载态、分页/滚动加载 |
|
|
11
|
+
| 详情页 | 单实体全字段 | 按 ID 查询 | 不存在时的 404 处理 |
|
|
12
|
+
| 统计卡片/图表 | 无新实体,基于既有实体聚合 | 聚合接口(count/sum/avg + group by 维度) | 时间/维度筛选联动 |
|
|
13
|
+
| 头像/昵称/个人页/「我的」tab | 用户实体 + 业务数据挂 userId | 当前用户接口;业务查询按用户隔离 | 登录态展示 |
|
|
14
|
+
| 状态标签(待办/进行中/已完成等) | 实体 status 字段 + 合法流转 | 状态变更接口(校验流转合法性) | 状态筛选、变更操作入口 |
|
|
15
|
+
| 搜索框 | — | 查询接口加关键字参数 | 防抖、无结果态 |
|
|
16
|
+
| 删除/归档按钮 | 软删或归档字段 | 删除/归档接口 | 确认交互 |
|
|
17
|
+
| 日期/日历视图 | 实体时间字段 | 按时间范围查询 | 日/周/月切换 |
|
|
18
|
+
| 稿内示例数据(列表里的假条目、图表假数值) | — | — | 写入数据库成为初始数据;页面必须走真实查询,不许写死 |
|
|
19
|
+
|
|
20
|
+
推导原则:**稿内看得见的每条数据都要能回答「它从哪张表的哪个字段来」**;回答不了的,就补齐真实数据模型和数据链路,不得用硬编码或假逻辑代替。
|
|
21
|
+
|
|
22
|
+
**多维组件必须逐维度登记字段绑定**:一个组件同时承载多个可见维度时(如状态标签的「显示文案」与「视觉状态/颜色」是两个维度),每个维度显式写明绑定哪个字段(如文案 ← `docType`、颜色 ← `status`),不得用同一个状态字段既当文案又当颜色,导致所有行渲染成同一个值。
|
|
23
|
+
|
|
24
|
+
## 源稿可见内容与默认数据状态
|
|
25
|
+
|
|
26
|
+
高保真不只包含布局和样式。源稿在默认(未交互)状态下可见的内容、数据和素材同样是 UX 规格;把静态示例改成 DB/API 驱动时,只改变数据来源,不改变默认展示结果。这条约束覆盖应用的每一个页面、每一处可见内容。
|
|
27
|
+
|
|
28
|
+
| 源稿证据 | 实现要求 |
|
|
29
|
+
|----------|----------|
|
|
30
|
+
| 区块标题、说明、标签、按钮文案 | 原样保留,不擅自缩写、润色或改写语义 |
|
|
31
|
+
| 分类、卡片、列表等重复条目 | 保留源稿的数量、名称、顺序、分组和对应关系 |
|
|
32
|
+
| 价格、时长、进度、统计等示例值 | 作为初始数据写入数据库,统一单位后由真实 API 返回;页面展示值与源稿一致 |
|
|
33
|
+
| 图片、SVG、图标、CSS 渐变、背景 | 复用或等价转译并保持与条目的映射;不得用生成图片替换已有素材 |
|
|
34
|
+
| 默认选中、筛选、分页、空态和业务状态 | 首次进入时由真实数据与页面状态复现,不用硬编码结果覆盖 API |
|
|
35
|
+
|
|
36
|
+
**页面可见字段不得静默改写**:凡直接显示或决定页面默认外观的字段,包括文案、字符/图标、图片、颜色、渐变、数值、单位、顺序和默认状态,均须从源稿逐字段传递到其存放位置并到达页面。存放位置按性质划分:业务数据,以及属于单条数据自身内容的视觉值(每条数据自有的封面图、封面渐变、标识色),写入数据库成为初始数据、经接口到达页面;不参与查询和聚合、由设计稿为固定集合指定的纯视觉值(字符图标、装饰 emoji、固定区块配色),作为前端组件常量或主题 token,直接从源稿代码复制。字符图标不得静默改成图标库名称,素材不得改成语义占位符。确有必要转译时,在方案中登记源表示、目标表示、转换实现和验收方式,并验证视觉等价。
|
|
37
|
+
|
|
38
|
+
规划时对每组默认展示数据登记五项内容:目标页面或区块、源文件与行号区间、全部默认展示字段、数据库与接口与页面链路、原值保留或必要转换策略。字段集合必须完整,但不要把大段源码或全部字段值复制进 plan;重复条目应覆盖所有直接渲染或决定外观的字段(如 `name/icon/count/order`),不得只概括成“若干分类/卡片”。写入初始数据、实现 API 投影或素材映射的 Agent 必须在动手前就近读取对应源文件;不能因为 UI Agent 已读源稿,就依据其摘要重新编造数据。
|
|
39
|
+
|
|
40
|
+
验收时逐页沿真实链路核对:
|
|
41
|
+
|
|
42
|
+
源稿可见内容、数据库初始数据与素材、API 返回、页面渲染,四层逐字段一致
|
|
43
|
+
|
|
44
|
+
数据库非空、接口成功、返回条数正确或页面结构相似都不算通过;必须按方案登记的默认展示字段逐字段核对文案、字符/图标、条目数量与顺序、示例值与单位、素材对应关系和默认状态。
|
|
45
|
+
|
|
46
|
+
## 前后端接口与数据口径一致
|
|
47
|
+
|
|
48
|
+
同一业务数据经过前端、API、服务端、数据库或插件时,字段名、类型、单位、取值范围、枚举、是否必填和默认值必须一致。优先在共享接口类型中定义请求与响应结构,前后端不得各自发明不同口径。
|
|
49
|
+
|
|
50
|
+
只为容易产生歧义的数据建立口径清单,不要罗列所有普通字段。必须登记:金额、比例、时长、距离、时间等带单位字段,状态和类型枚举,单值/多值,可空/选填/默认值,插件结构化输出,以及展示值与存储值不同的字段。
|
|
51
|
+
|
|
52
|
+
| 业务数据 | 请求/响应字段 | 类型与取值 | 单位/范围 | 服务端与 DB | 页面展示 |
|
|
53
|
+
|----------|---------------|------------|-----------|-------------|----------|
|
|
54
|
+
| 示例:商品价格 | `minPrice` / `maxPrice` | `number` | 分,非负整数 | DB 存分,仅在明确边界转换 | 展示时除以 100 |
|
|
55
|
+
| 示例:搜索类型 | `types` | `SearchType[]` | 约定枚举,可多选 | 按数组执行 `IN` 查询 | 多选筛选器 |
|
|
56
|
+
| 示例:置信度 | `confidence` | `integer` | 0–100 | DB 与插件归一化后均存 0–100 | 直接追加 `%` |
|
|
57
|
+
|
|
58
|
+
## 持久化业务结果与异常恢复
|
|
59
|
+
|
|
60
|
+
如果一次用户操作的结果需要在刷新、重新进入或异常重试后继续存在,或者会约束后续允许执行的操作,就把它视为持久化业务结果。业务结果不限于状态枚举,也包括实体创建、关系变化、数量或进度变化、生命周期阶段和异步产物。Tab、弹窗、展开收起等纯页面状态不要求落库,除非源稿明确表达跨会话保留。
|
|
61
|
+
|
|
62
|
+
| 业务对象 | 操作/事件 | 操作前提 | 成功后的业务结果 | 持久化内容 | 重复/并发处理 | 刷新与异常恢复 |
|
|
63
|
+
|----------|-----------|----------|--------------------|------------|---------------|----------------|
|
|
64
|
+
| `<实体或关系>` | `<用户操作或系统事件>` | `<允许执行的业务条件>` | `<可观察、可继续使用的事实>` | `<表、字段或外部结果引用>` | `<幂等、拒绝或并发控制>` | `<重新读取、重试或对账>` |
|
|
65
|
+
|
|
66
|
+
- 以服务端和持久化存储中的业务事实为准;前端只在重新读取后确认结果,不得仅凭本地状态或 HTTP 2xx 宣布完成。
|
|
67
|
+
- 在服务端校验操作前提并原子持久化业务结果;不满足前提的操作返回明确错误,不得静默成功。
|
|
68
|
+
- 对可能重复产生副作用的操作定义幂等或并发控制;请求超时或中断时,先重新读取真实结果,再决定是否重试。
|
|
69
|
+
- 对异步处理持久化任务状态、结果引用和失败信息,使页面重新进入后能够继续查询或恢复。
|
|
70
|
+
|
|
71
|
+
## 可见功能闭环清单
|
|
72
|
+
|
|
73
|
+
逐项登记所有具有交互语义的可见元素:按钮、链接、可点击卡片、表单控件、搜索/筛选/排序/分页、Tab/导航/弹窗、上传/下载/导出、播放器、开关和步骤流转。纯文案、分割线、背景等明确非交互装饰不登记;不要据此补造源稿未展示或暗示的产品功能。
|
|
74
|
+
|
|
75
|
+
同一组件模板中行为和链路完全相同的重复控件可以合并登记,但每个可见交互都必须能对应到清单中的一项;行为、参数或结果不同的控件分别登记。
|
|
76
|
+
|
|
77
|
+
| 页面 / 可见元素 | 用户操作 | 可见结果 | 实现链路 | 验收方式 |
|
|
78
|
+
|-----------------|----------|----------|----------|----------|
|
|
79
|
+
| 示例:课程详情 /「立即购买」 | 点击 | 报名成功,按钮变为已加入 | `onClick → POST /enrollments → enrollment 表 → 刷新详情` | 从按钮触发;刷新后仍为已加入 |
|
|
80
|
+
| 示例:播放器 / 播放按钮 | 点击 | 开始播放,时间与进度变化 | 播放器状态 → 进度写接口 → progress 表 | 播放后读取进度并刷新确认 |
|
|
81
|
+
|
|
82
|
+
实现链路按交互类型填写:
|
|
83
|
+
|
|
84
|
+
- **导航/本地状态**:控件 → 正确路由、Tab、弹窗或组件状态;不得用空 `href`、错误路由或只切换无关图标代替。
|
|
85
|
+
- **查询**:控件 → 查询参数 → API DTO → DB 查询 → 列表/统计结果;前后端复用同一数据口径,并用页面实际发送的参数验收查询结果。
|
|
86
|
+
- **写入**:控件 handler → 写 API → DB/文件/平台能力 → 成功/失败反馈 → 重新读取;请求与响应遵循共享接口类型,不得只改前端内存、只改初始数据或返回固定成功。
|
|
87
|
+
- **插件/外部能力**:控件 → 真实 capability/服务 → 可验证结果;先明确插件输入输出的字段、类型、范围与空值处理,不可用时报告阻塞,不得用延时、随机数、正则校验或假 toast 冒充。
|
|
88
|
+
|
|
89
|
+
方案提交前扫描可见功能清单、风险和实现说明。若用「模拟、占位、静态展示、Toast 反馈、仅格式校验、仅记录、不对接」代替源稿表达的功能,必须改为真实链路;能力确实不可用时标记阻塞和未完成,不得把降级方案列为已实现范围。
|
|
90
|
+
|
|
91
|
+
## UI→capability 常见信号示例(非完整插件目录)
|
|
92
|
+
|
|
93
|
+
创意稿里被 mock 的 AI/飞书类能力,生成时用**真实插件**实现。下表只帮助从 UI 语义识别插件候选并触发 `plugin-guide`,不是平台能力清单;表外疑似插件能力也要召回 `plugin-guide`。实际可用能力以其动态提供的 `available_plugin_instances`、`available_plugins` 及候选实例的 `get_plugin_ai_json` 为准。
|
|
94
|
+
|
|
95
|
+
| 稿内 UI 语义 | 候选 capability(以动态目录为准) |
|
|
96
|
+
|--------------|-------------------|
|
|
97
|
+
| "AI 生成/智能生成/一键生成文案"、聊天对话框、智能问答 | `ai-text-generate` |
|
|
98
|
+
| "AI 生图/配图/封面生成/头像生成" | `ai-text-to-image` |
|
|
99
|
+
| 上传图片"识别/提取字段"(发票/名片/证件/表单) | `ai-image-to-json` |
|
|
100
|
+
| 上传文档"解析/总结/提炼" | `ai-doc-parser` → `ai-text-to-json` / `ai-text-summary` |
|
|
101
|
+
| "翻译" | `ai-translate` |
|
|
102
|
+
| "语音转写/录音转文字" | `ai-speech-to-text` |
|
|
103
|
+
| 图片"抠图/去背景" | `ai-image-matting` |
|
|
104
|
+
| "发送到飞书/通知群/推送消息" | `send-feishu-message` |
|
|
105
|
+
| "同步到多维表格/写入 Base/存表格" | `feishu-bitable` |
|
|
106
|
+
| "建群/拉群" | `feishu-group-create` |
|
|
107
|
+
|
|
108
|
+
识别出候选后**召回 `plugin-guide` skill**,由它完成实例复用或创建、运行时合同读取和真实调用。本 skill 不复述插件目录与调用规范。
|
|
109
|
+
|
|
110
|
+
**边界**:数据库读写、文件上传/存储**不是插件**(内置服务 DataLoom / file-service,走对应 skill);语义检索走 `semantic-search` skill。别把这三类误建成 capability。
|
|
111
|
+
|
|
112
|
+
## mock 信号识别表(grep 创意产物定位待替换点)
|
|
113
|
+
|
|
114
|
+
创意稿无「插件规划」时,AI/飞书能力都是 mock 的。规划阶段 grep 这些信号,逐个登记进方案的 capability 清单:
|
|
115
|
+
|
|
116
|
+
| mock 反模式 | 典型形态 | 应替换为 |
|
|
117
|
+
|-------------|----------|----------|
|
|
118
|
+
| 假异步 AI | `setTimeout(() => setState(硬编码对象))`、`simulate*`/`mock*`/`fake*` 函数名 | 对应 AI capability |
|
|
119
|
+
| 预置结果数组 | `MOCK_*` / `PRESET_*` 常量假装 AI 生成结果 | 对应 AI capability |
|
|
120
|
+
| 外链占位图 | `picsum.photos` / `placeholder.com` / `unsplash` 替代 AI 生图 | `ai-text-to-image` |
|
|
121
|
+
| 假飞书反馈 | `toast('已发送到飞书')` 无真实调用 | `send-feishu-message` |
|
|
122
|
+
| 随机数假逻辑 | `Math.random()` 替代 AI 分类/评分 | 对应 AI capability |
|
|
123
|
+
|
|
124
|
+
("展示用示例数据"是允许的 mock——写入数据库成为初始数据即可,与上面的"插件能力 mock"区分:前者是数据,后者是能力。)
|
|
125
|
+
|
|
126
|
+
## 方案(plan)必须包含
|
|
127
|
+
|
|
128
|
+
- **页面清单**:路由 / 页面名 / 来源屏(画板 label 或文件名)
|
|
129
|
+
- **源稿实现定位与默认展示字段归属**:目标页面或区块 / 源文件或区段 / 全部默认展示字段 / DB、API 与页面链路 / 原值保留或必要转译策略 / UI、初始数据、API 与素材负责人;字段集合必须完整,但不复制大段源码或全部字段值
|
|
130
|
+
- **实体与关系**:表、字段、关联、状态机
|
|
131
|
+
- **页面-接口映射**:每页消费/调用哪些接口
|
|
132
|
+
- **可见功能清单**:页面与控件 / 用户操作 / 可见结果 / 实现链路 / 验收方式
|
|
133
|
+
- **数据口径清单(存在易歧义数据时)**:业务数据 / 请求与响应字段 / 类型与取值 / 单位与范围 / 服务端与 DB / 页面展示
|
|
134
|
+
- **持久化业务结果清单(存在需跨刷新/重新进入/异常重试保留或约束后续操作的结果时)**:业务对象 / 操作或事件 / 操作前提 / 成功后的业务结果 / 持久化内容 / 重复与并发处理 / 刷新与异常恢复
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: data-analysis
|
|
3
|
+
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"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Data Analysis
|
|
7
|
+
|
|
8
|
+
Systematic data analysis workflow that produces structured JSON output for downstream code consumption.
|
|
9
|
+
|
|
10
|
+
## Execution Flow
|
|
11
|
+
|
|
12
|
+
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.
|
|
13
|
+
|
|
14
|
+
1. **Setup tmp directory**: Initialize `tmp/` directory structure in project root. **MUST read `references/tmp-file-management-guide.md` before proceeding.**
|
|
15
|
+
2. **Confirm data source**: Confirm the file path to analyze with user
|
|
16
|
+
3. **Execute Phase 1-3**: Business Understanding → Data Understanding → Quality Assessment (see "Analysis Methodology")
|
|
17
|
+
4. **Report initial findings**: Inform user about data overview and quality issues
|
|
18
|
+
5. **Execute Phase 4-5**: Descriptive Analysis → Insight Extraction (see "Analysis Methodology")
|
|
19
|
+
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.**
|
|
20
|
+
7. **Generate visualizations** (optional): Save charts to `tmp/output/visualizations/`
|
|
21
|
+
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.
|
|
22
|
+
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.
|
|
23
|
+
10. **Report output locations**: Inform user where artifacts are saved. **MUST read "Output Summary Template" in `references/post-analysis-guide.md`.**
|
|
24
|
+
|
|
25
|
+
### Quality Checklist
|
|
26
|
+
|
|
27
|
+
After completing all steps above, verify the following before considering the task done:
|
|
28
|
+
|
|
29
|
+
- [ ] **tmp/ directory initialized**: All subdirectories created
|
|
30
|
+
- [ ] **Data quality assessed**: `data_quality` section fully populated
|
|
31
|
+
- [ ] **Statistics complete**: All numeric/categorical columns have corresponding summary
|
|
32
|
+
- [ ] **Insights have evidence**: Every insight has an `evidence` field
|
|
33
|
+
- [ ] **Insights answer business question**: Corresponds to `metadata.business_question`
|
|
34
|
+
- [ ] **JSON conforms to spec**: Field names, types, required fields all correct
|
|
35
|
+
- [ ] **Visualization config is valid**: Field names in `config` exist in the data
|
|
36
|
+
- [ ] **At least 1 recommendation**: `recommendations` is not empty
|
|
37
|
+
- [ ] **No hardcoded paths**: File paths come from user input
|
|
38
|
+
- [ ] **Outputs saved to tmp/**: JSON result and visualizations written to correct locations
|
|
39
|
+
- [ ] **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)
|
|
40
|
+
- [ ] **tmp/ in .gitignore**: Ensure tmp/ is excluded from version control
|
|
41
|
+
- [ ] **types.ts updated**: TS type definitions extracted and appended to `shared/static/types.ts` (created if not exists)
|
|
42
|
+
- [ ] **AGENTS.md updated**: Analysis record appended with type definition location and consumption example
|
|
43
|
+
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## Analysis Methodology (6 Phases)
|
|
47
|
+
|
|
48
|
+
Follow a simplified CRISP-DM methodology. **MUST read `references/python-analysis-reference.md` for Python code templates before writing analysis code.**
|
|
49
|
+
|
|
50
|
+
### Phase 1: Business Understanding
|
|
51
|
+
|
|
52
|
+
**Goal**: Clarify the analysis purpose and avoid blind exploration.
|
|
53
|
+
|
|
54
|
+
1. Confirm analysis type (see "Analysis Type Quick Reference")
|
|
55
|
+
2. Extract the user's core question or hypothesis
|
|
56
|
+
3. Define success criteria: What does the user expect from the analysis?
|
|
57
|
+
|
|
58
|
+
**Output**: Record in `metadata.analysis_type` and `metadata.business_question` in JSON.
|
|
59
|
+
|
|
60
|
+
### Phase 2: Data Understanding
|
|
61
|
+
|
|
62
|
+
**Goal**: Fully understand the structure and content of the data.
|
|
63
|
+
|
|
64
|
+
1. Load data and get basic information (row/column count, field names, dtypes, sample rows)
|
|
65
|
+
2. Identify field semantics:
|
|
66
|
+
|
|
67
|
+
| Type | Examples |
|
|
68
|
+
| ---- | -------- |
|
|
69
|
+
| Numeric (continuous) | price, age, amount |
|
|
70
|
+
| Numeric (discrete) | count, quantity |
|
|
71
|
+
| Categorical (ordinal) | rating, education level |
|
|
72
|
+
| Categorical (nominal) | color, city, product name |
|
|
73
|
+
| DateTime | order_date, created_at |
|
|
74
|
+
| Text | description, comments |
|
|
75
|
+
|
|
76
|
+
3. Initial statistical overview
|
|
77
|
+
|
|
78
|
+
### Phase 3: Data Quality Assessment
|
|
79
|
+
|
|
80
|
+
**Goal**: Identify data issues for credibility reference.
|
|
81
|
+
|
|
82
|
+
| Check | Method |
|
|
83
|
+
| ----- | ------ |
|
|
84
|
+
| Missing values | Per-column missing ratio, random vs systematic pattern |
|
|
85
|
+
| Duplicates | Full-row and key-field duplicates |
|
|
86
|
+
| Outliers | Numeric: IQR or Z-score; Categorical: rare categories |
|
|
87
|
+
| Consistency | Date formats, category value spelling |
|
|
88
|
+
|
|
89
|
+
**Output**: Populate the `data_quality` section of JSON.
|
|
90
|
+
|
|
91
|
+
### Phase 4: Descriptive Analysis
|
|
92
|
+
|
|
93
|
+
**Goal**: Extract statistical characteristics and distribution patterns.
|
|
94
|
+
|
|
95
|
+
| Sub-phase | Focus | Key Metrics |
|
|
96
|
+
| --------- | ----- | ----------- |
|
|
97
|
+
| 4.1 Numeric | Central tendency & dispersion | mean, median, std, skew, kurtosis, quartiles |
|
|
98
|
+
| 4.2 Categorical | Frequency distribution | unique count, top N values, mode |
|
|
99
|
+
| 4.3 Correlation | Variable relationships | Pearson (linear), Spearman (monotonic), \|r\| > 0.7 = strong |
|
|
100
|
+
| 4.4 Group Aggregation | Group comparisons | group-by mean/std/count |
|
|
101
|
+
|
|
102
|
+
**Output**: Populate the `statistics` section of JSON.
|
|
103
|
+
|
|
104
|
+
### Phase 5: Insight Extraction
|
|
105
|
+
|
|
106
|
+
**Goal**: Extract business-valuable findings from statistical results.
|
|
107
|
+
|
|
108
|
+
| Type | Identification Criteria | Example |
|
|
109
|
+
| ---- | ----------------------- | ------- |
|
|
110
|
+
| `correlation` | \|r\| > 0.7 or p < 0.05 | "Price and sales show strong negative correlation" |
|
|
111
|
+
| `trend` | Directional change in time series | "Monthly revenue shows continuous growth" |
|
|
112
|
+
| `anomaly` | Beyond 3σ or IQR boundary | "5 anomalous high-value orders detected" |
|
|
113
|
+
| `distribution` | Obvious skewness or multimodal | "Income shows right-skewed distribution" |
|
|
114
|
+
| `comparison` | Significant group differences | "Group A conversion rate significantly higher than Group B" |
|
|
115
|
+
|
|
116
|
+
Each insight must include: **evidence** (specific supporting data), **significance** (high/medium/low), **affected_columns**.
|
|
117
|
+
|
|
118
|
+
### Phase 6: JSON Output
|
|
119
|
+
|
|
120
|
+
Generate structured analysis result. **MUST read `references/json-output-specification.md` and strictly conform to its schema.**
|
|
121
|
+
|
|
122
|
+
---
|
|
123
|
+
|
|
124
|
+
## Analysis Type Quick Reference
|
|
125
|
+
|
|
126
|
+
Select the appropriate analysis focus based on user intent. Phase numbers refer to "Analysis Methodology" above.
|
|
127
|
+
|
|
128
|
+
| User Expression | Analysis Type | Focus Phase | Key Output |
|
|
129
|
+
| --------------- | ------------- | ----------- | ---------- |
|
|
130
|
+
| "explore data", "overview", "understand data" | `exploratory` | Phase 2-4 | Basic stats, quality report, distribution |
|
|
131
|
+
| "find patterns", "correlations", "relationships" | `exploratory` | Phase 4.3 | Correlation matrix, significant pairs |
|
|
132
|
+
| "compare", "A vs B", "differences" | `diagnostic` | Phase 4.4 | Group statistics, group differences |
|
|
133
|
+
| "validate hypothesis", "significance test" | `confirmatory` | Phase 4-5 | Statistical tests, p-values |
|
|
134
|
+
| "statistics", "summary", "report" | `descriptive` | Phase 4 | Aggregation results, frequency stats |
|
|
135
|
+
| "trend", "changes", "time series" | `exploratory` | Phase 4 | Time series trends, periodicity |
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Common Mistakes
|
|
140
|
+
|
|
141
|
+
| Mistake | Correct Approach |
|
|
142
|
+
| ------- | ---------------- |
|
|
143
|
+
| Analyze directly without checking data quality | Execute Phase 3 first, assess missing values and outliers |
|
|
144
|
+
| Ignore missing values when calculating mean | Clarify missing value handling strategy, or use `dropna()` |
|
|
145
|
+
| Interpret correlation as causation | Explicitly label "correlation" not "causes" in insights |
|
|
146
|
+
| Ignore data types and analyze directly | Confirm dtype first, numeric vs categorical need different handling |
|
|
147
|
+
| Output non-standardized JSON | Strictly follow the Schema in `references/json-output-specification.md` |
|
|
148
|
+
| Insights without supporting evidence | Every insight must have an `evidence` field |
|
|
149
|
+
| Visualization config doesn't match data | Ensure field names in `config` exist in the data |
|
|
150
|
+
| JSON contains NaN/Infinity (TS1328) | MUST sanitize: replace NaN/Infinity with `None` before `json.dump()`, use `allow_nan=False` |
|
|
151
|
+
|