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

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

@@ -0,0 +1,64 @@
+---
+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/` 中的原创意设计应用为依据，在当前工程中交付真实可运行的全栈应用，而不是静态原型。源稿是只读的视觉与业务意图权威，不能作为交付应用的运行时依赖。目标是在保证以下结果的前提下尽快完成。
+
+## 工程规范与最小规划
+
+- **开发前必读 `coding-guide`**：使用当前技术栈的工程、共享类型、平台能力及规范。开发 Worker 同样必读，只按需加载专项 skill；不另发明行数/目录规则或限定文件数。在独占页面/模块目录内，首次编码即可按该规范拆私有组件与逻辑文件；必要的后置重构须基于完整源码局部移动，不能依据截断读取整体重写。
+- **先写 `docs/business-design.md` 再编码**：只写支持实现与验收的决策，不誊写源稿视觉细节、实际种子值或逐控件功能全集。正文需覆盖下表，短列表或合并表格均可；同一事实只定义一次。
+- **契约先行**：当前并行批次所需的最小 shared 类型、路由参数、ID/状态/单位口径、实际 schema 与接口落盘可引用后即可开工，不等全部业务契约或公共组件实现完成；代码契约不与文档维护两份字段定义。执行期主 Agent 与 Worker 均不得擅改契约；阻断核心链路时暂停受影响任务，统一修订设计与契约，只通知受影响消费者并调整其任务。
+- 用 TodoWrite 记录实现、验收及未完成项，每批完成或提交前按事实更新。实际阻塞在设计文档中登记，交付时如实披露。
+
+### 业务设计必须回答的问题
+
+| 内容 | 最小产出 |
+| --- | --- |
+| 核心链路 | 按用户目标识别核心链路，每条链路定义：真实可见入口与目标对象 → 输入/动作 → 必要中间态 → 真实结果 → 回读位置。链路内各步骤作用于同一目标对象，每一步写入产生的对象、状态及其关联记录须满足下一步操作与回读页所需的数据条件，任一条件不满足即视为链路未闭环。 |
+| 非核心功能 | 不属于任何核心链路的功能点逐项列出，全部保留源稿视觉；其展示数据来自数据库中的真实记录，不实现业务写入、状态流转与外部能力接入。对应控件保持外观并呈现不可用语义，不显示虚假成功，不删除页面或区块。该清单与核心链路清单共同构成本次交付范围，收尾时按同一清单如实说明。 |
+| 页面与视觉来源 | 记录全部源稿页面对应的目标路由/目录、对象参数、源文件/区块，以及用户可见的到达路径；核心结果页明确其上游操作入口。记录全局 Layout 和真正跨页组件的归属，以及素材来源与迁移/复用方案。 |
+| 最小业务模型 | 核心实体、稳定 ID/关联、关键状态及前置条件、必要唯一性与可空规则；初始事实的源稿位置与字段映射，缺失事实按空态展示。 |
+| 接口与结果口径 | 核心动作的必要用户输入、前置条件、状态变化与回读结果在接口契约中一一对应。记录方法/路径、请求/响应类型及 shared 路径、错误/空态语义；动态结果明确事实来源、计算/筛选口径与变化触发。前后端共同引用对象 ID、状态、单位/取整、时间及可空字段口径。平台/插件能力按实际需要选型并确认可用契约。 |
+| 验收与阻塞 | 按源事实定义每条核心链路的可见操作路径、目标对象/状态、可判定的结果与刷新/跨页回读；覆盖相关中间态及动态变化，合并共享链路，另列全页面视觉检查。记录影响核心交付的外部依赖、资源缺失及实际阻塞。 |
+
+设计以能开工、能判定结果为止；不扩成全产品设计、字段血缘大全或多层门禁。遇到新事实只改受影响条目，不反复读写整份文档。视觉实现者直接读取对应源稿，不凭主 Agent 转述实现。
+
+## 交付目标
+
+### 1. 页面视觉效果 100% 还原
+
+保留所有源稿页面、导航、布局、层级、尺寸、间距、字体、颜色、固定文案、素材主体与图表形态。素材优先复用/迁移；不可复用时替代图须保持原用途、主体、色调和裁切。以源稿中的实际业务页面为还原对象。
+
+动态数字来自当前业务事实，保持与源稿一致的单位、格式和排布。视觉验收关注整体呈现效果，允许动态数值和无影响的小图标差异。
+
+### 2. 核心功能完整，操作链路与数据闭环
+
+- **承诺与结果一致**：核心动作必须真实完成其业务含义，写入后可按对象 ID 重新查询，成功页刷新/重进仍能显示该结果；仅 toast、跳页、接口 200 或数据库有记录不足以证明闭环。中间态与终态区分，不能提前显示全部完成或过早清空后续页面所需状态。
+- **对象身份一致**：入口、路由参数、详情、子记录和结果内容属于同一对象。已存在的合法对象不能仅因未出现在最近/摘要列表中就不可访问。无效 ID、无关联记录返回明确空态/错误，不能默认第一条记录来掩盖问题；新对象的可空字段不得使详情崩溃，空链接不渲染可点击目标。
+- **事实与状态来源**：初始数据从源稿明确的既有事实映射、去重并建立有依据的关联，保留各对象所处的业务状态。核心操作按业务规则生成必要关联记录，状态、时间与用户输入随实际执行更新；结果页读取执行后的事实。缺失事实如实展示空态，业务完成依据实际状态判定。
+- **动态数据同一口径**：会随业务变化的展示从事实实时计算，不用预置统计字段/常数替代。写入后的计数、进度、余额与聚合联动；周期选择一致作用于标题、明细和统计；分子分母、过程/结算/历史、时钟与取整口径统一。只为本身具有独立业务生命周期的快照保留持久化，不为展示另造真源。
+- **真实能力与明确边界**：核心 AI、媒体和外部能力取得真实结果或明确失败；检索计数/字符串模板不是 AI 回答，动画计时不是播放。按需读取 `plugin-guide` 并确认运行时 schema，不把普通数据库、定位/导航/扫码或内部演示支付机械判成插件。已明确采用内部演示的能力标识模拟边界，并使用一致、可复核的状态/计算，不能伪称外部执行成功；缺少核心资源则报告阻塞。
+
+## 提效时的执行约束
+
+- 共享层只准备当前批次必要结构与接口，复用已有模板；不批量造空 API/DTO，主 Agent 不先写完所有服务和 SQL 才派发业务任务。
+- 以独占写入范围拆任务。优先按页面拆前端、按 server module 拆后端，让独立页面、后端模块与种子任务同批开始；不要把多页与整个后端塞进一个长任务。公共层一个写入者；公共组件有稳定接口即可并行消费，不等其实现完成。仅消费必要插件/素材的任务等待其结果，不让无关任务一起等待。
+- 种子数据：CodeAct 写种子数据与业务任务并行，按实际 schema 写入源稿已有对象及必要关联，写入成功即完成。统计数据基于实际数据计算，允许与源稿数值不同；运行时验证统一由主 Agent 完成。
+- 开发任务只检查自己改动的类型/契约等静态问题，达标即返回。不运行接口冒烟、启动服务联调、读运行时日志、读库验收或执行 E2E；运行时验证交由主 Agent 组织，避免开发与测试同时改同一资源。
+- 任务单引用所属核心链路、契约路径和独占写入范围，仅补充本任务特有的实现信息。前后端沿用同一结果、状态与统计口径；契约缺口由主 Agent 定点协调修订。回传改动文件、检查结果、实际阻塞和未完成项。
+
+## 验收准则
+
+**验收前必读 `testing-guide`**，使用设计阶段已确定的清单，不在验收阶段重新扩展业务或以实际弱化实现改写通过标准。
+
+1. **真实操作核心链路**：验收从应用首页或正常业务起点开始，通过用户可见的导航、按钮或业务操作到达目标页面，记录入口操作与到达结果。同一核心链路连续使用同一对象；包含创建时，将新建结果用于后续操作。一次执行核对必要输入的保存与回读、关键状态变化、真实结果及关联动态输出，并完成刷新或跨页回读。
+2. **完整视觉**：覆盖全部源稿页面，逐页确认主要布局、内容、图表、导航与图片；允许动态数值和无影响的小图标差异。
+3. **针对性修复**：先看失败步骤的请求、ID、状态及相关代码，结合源事实区分应用缺陷、测试假设错误与平台问题；只修核心功能问题或实质视觉问题，不新增身份/权限体系或源稿外业务。已有平台与 coding-guide 约束仍须满足。应用或测试修正、平台恢复后定向复测受影响链路；提交自动修复改变关键行为后也须复测。同一结果复用证据，不重复整套无关验收。不以关键词命中或同名组件一概判错，不搞全库对账。
+4. **如实交付**：清单逐项记录通过/失败/未测和证据，复测保留各核心功能的实际验收状态，披露核心阻塞。核心功能和视觉验收全部通过后宣称完成，并移除 `source_package/creative/.upgrade-manifest.json` 停止重复注入；其他源稿保留。存在失败或未测项时保留标记与证据，如实交付当前状态。

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` |
+

package/miaoda/data-analysis/references/json-output-specification.md

@@ -0,0 +1,277 @@
+# JSON Output Specification
+
+## Complete Schema
+
+```json
+{
+  "analysis_id": "string (UUID v4)",
+  "timestamp": "string (ISO 8601 format)",
+  "metadata": {
+    "data_source": "string (file path or data description)",
+    "row_count": "integer",
+    "column_count": "integer",
+    "analysis_type": "exploratory | confirmatory | diagnostic | descriptive",
+    "business_question": "string (user's core question, optional)"
+  },
+  "data_quality": {
+    "completeness": "number (0-1, non-missing ratio)",
+    "missing_values": {
+      "column_name": "integer (missing count)"
+    },
+    "duplicates": "integer (duplicate row count)",
+    "outliers": {
+      "column_name": "integer (outlier count)"
+    },
+    "issues": ["string (issue description)"]
+  },
+  "statistics": {
+    "numeric_summary": {
+      "column_name": {
+        "count": "integer",
+        "mean": "number",
+        "std": "number",
+        "min": "number",
+        "max": "number",
+        "quartiles": ["number (Q1)", "number (Q2/median)", "number (Q3)"],
+        "skew": "number (optional)",
+        "kurtosis": "number (optional)"
+      }
+    },
+    "categorical_summary": {
+      "column_name": {
+        "unique_count": "integer",
+        "top_values": [
+          {"value": "string", "count": "integer", "percentage": "number"}
+        ],
+        "mode": "string"
+      }
+    },
+    "correlations": [
+      {
+        "column1": "string",
+        "column2": "string",
+        "coefficient": "number",
+        "method": "pearson | spearman"
+      }
+    ]
+  },
+  "insights": [
+    {
+      "id": "string (insight_1, insight_2, ...)",
+      "type": "correlation | trend | anomaly | distribution | comparison",
+      "title": "string (short title, within 10 characters)",
+      "description": "string (detailed description)",
+      "evidence": {
+        "metric": "string (metric name)",
+        "value": "number | string",
+        "p_value": "number (optional, for statistical tests)"
+      },
+      "significance": "high | medium | low",
+      "affected_columns": ["string"]
+    }
+  ],
+  "recommendations": [
+    {
+      "id": "string (rec_1, rec_2, ...)",
+      "type": "visualization | further_analysis | data_collection | action",
+      "title": "string (recommendation title)",
+      "description": "string (detailed recommendation)",
+      "priority": "high | medium | low"
+    }
+  ],
+  "visualizations": [
+    {
+      "id": "string (viz_1, viz_2, ...)",
+      "type": "histogram | scatter | line | bar | heatmap | box | pie",
+      "title": "string (chart title)",
+      "config": {
+        "x": "string (X-axis field name)",
+        "y": "string (Y-axis field name, optional)",
+        "group_by": "string (grouping field, optional)",
+        "aggregation": "string (aggregation method: sum/mean/count, optional)"
+      },
+      "insight_refs": ["string (associated insight id)"]
+    }
+  ]
+}
+```
+
+## CRITICAL: JSON Validity Rules
+
+Python `json.dumps()` defaults to `allow_nan=True`, which outputs `NaN` and `Infinity` as bare tokens — **these are NOT valid JSON** and will cause TypeScript build failures (TS1328).
+
+| Python value | json.dumps output | Valid JSON? | Fix |
+|-------------|-------------------|-------------|-----|
+| `float('nan')` | `NaN` | **NO** | Replace with `null` |
+| `float('inf')` | `Infinity` | **NO** | Replace with `null` or max value |
+| `float('-inf')` | `-Infinity` | **NO** | Replace with `null` or min value |
+| `None` | `null` | Yes | OK |
+
+**MUST** do one of:
+1. Call `json.dump(..., allow_nan=False)` (raises error if NaN exists, forcing explicit handling)
+2. Sanitize all float values before dumping: replace `NaN`/`Infinity` with `None`
+
+Common sources of NaN in pandas: `df.mean()` on empty column, `df.std()` on single value, `df.skew()` on constant data, division by zero.
+
+## Field Description
+
+| Field Path | Required | Description |
+| ---------- | -------- | ----------- |
+| `analysis_id` | Yes | Unique identifier for analysis task, use UUID v4 |
+| `timestamp` | Yes | Analysis completion time, ISO 8601 format |
+| `metadata.*` | Yes | Data source metadata |
+| `data_quality.*` | Yes | Data quality assessment results |
+| `statistics.numeric_summary` | Conditional | Required when numeric columns exist |
+| `statistics.categorical_summary` | Conditional | Required when categorical columns exist |
+| `statistics.correlations` | No | Only populate when significant correlations found |
+| `insights` | Yes | At least 1 insight required |
+| `recommendations` | Yes | At least 1 recommendation required |
+| `visualizations` | Yes | At least 1 visualization config required |
+
+## Example Output
+
+```json
+{
+  "analysis_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "timestamp": "2024-01-15T10:30:00Z",
+  "metadata": {
+    "data_source": "/data/sales_2023.csv",
+    "row_count": 10000,
+    "column_count": 12,
+    "analysis_type": "exploratory",
+    "business_question": "了解2023年销售数据的整体情况"
+  },
+  "data_quality": {
+    "completeness": 0.95,
+    "missing_values": {
+      "customer_age": 320,
+      "region": 180
+    },
+    "duplicates": 45,
+    "outliers": {
+      "order_amount": 23
+    },
+    "issues": [
+      "customer_age 列有 3.2% 缺失值",
+      "order_amount 存在 23 个异常高值（超出 IQR 上界）"
+    ]
+  },
+  "statistics": {
+    "numeric_summary": {
+      "order_amount": {
+        "count": 10000,
+        "mean": 156.78,
+        "std": 89.34,
+        "min": 5.00,
+        "max": 2500.00,
+        "quartiles": [85.00, 135.00, 210.00],
+        "skew": 2.34,
+        "kurtosis": 8.91
+      },
+      "customer_age": {
+        "count": 9680,
+        "mean": 35.6,
+        "std": 12.3,
+        "min": 18,
+        "max": 75,
+        "quartiles": [26, 34, 44]
+      }
+    },
+    "categorical_summary": {
+      "product_category": {
+        "unique_count": 5,
+        "top_values": [
+          {"value": "Electronics", "count": 3500, "percentage": 35.0},
+          {"value": "Clothing", "count": 2800, "percentage": 28.0},
+          {"value": "Home", "count": 2000, "percentage": 20.0}
+        ],
+        "mode": "Electronics"
+      }
+    },
+    "correlations": [
+      {
+        "column1": "order_amount",
+        "column2": "customer_age",
+        "coefficient": 0.72,
+        "method": "pearson"
+      }
+    ]
+  },
+  "insights": [
+    {
+      "id": "insight_1",
+      "type": "correlation",
+      "title": "年龄与消费正相关",
+      "description": "客户年龄与订单金额呈较强正相关（r=0.72），年长客户倾向于更高消费。",
+      "evidence": {
+        "metric": "pearson_correlation",
+        "value": 0.72,
+        "p_value": 0.001
+      },
+      "significance": "high",
+      "affected_columns": ["customer_age", "order_amount"]
+    },
+    {
+      "id": "insight_2",
+      "type": "distribution",
+      "title": "订单金额右偏分布",
+      "description": "订单金额呈明显右偏（skew=2.34），大部分订单集中在低价区间，少量高价订单拉高均值。",
+      "evidence": {
+        "metric": "skewness",
+        "value": 2.34
+      },
+      "significance": "medium",
+      "affected_columns": ["order_amount"]
+    }
+  ],
+  "recommendations": [
+    {
+      "id": "rec_1",
+      "type": "further_analysis",
+      "title": "深入分析高价值客户",
+      "description": "建议对年龄>40且订单金额>500的客户群体进行细分分析，挖掘其消费特征。",
+      "priority": "high"
+    },
+    {
+      "id": "rec_2",
+      "type": "visualization",
+      "title": "绘制年龄-消费散点图",
+      "description": "使用散点图可视化年龄与订单金额的关系，并按产品类别着色。",
+      "priority": "medium"
+    }
+  ],
+  "visualizations": [
+    {
+      "id": "viz_1",
+      "type": "scatter",
+      "title": "客户年龄 vs 订单金额",
+      "config": {
+        "x": "customer_age",
+        "y": "order_amount",
+        "group_by": "product_category"
+      },
+      "insight_refs": ["insight_1"]
+    },
+    {
+      "id": "viz_2",
+      "type": "histogram",
+      "title": "订单金额分布",
+      "config": {
+        "x": "order_amount"
+      },
+      "insight_refs": ["insight_2"]
+    },
+    {
+      "id": "viz_3",
+      "type": "bar",
+      "title": "各产品类别销售额",
+      "config": {
+        "x": "product_category",
+        "y": "order_amount",
+        "aggregation": "sum"
+      },
+      "insight_refs": []
+    }
+  ]
+}
+```

package/miaoda/data-analysis/references/post-analysis-guide.md

@@ -0,0 +1,77 @@
+# Post-Analysis Guide
+
+Steps to complete after analysis is done: update AGENTS.md and report output locations to user.
+
+## 1. Update AGENTS.md
+
+**CRITICAL**: After completing analysis, you **MUST** update AGENTS.md. This is NOT optional.
+
+### Steps
+
+1. Check if `AGENTS.md` exists in the project root; if not, create it
+2. Append the analysis record to `AGENTS.md` following the format below exactly
+
+> **NOTE**: Before writing code that consumes analysis data, always read the corresponding type definition in `shared/static/types.ts` first to ensure correct field access.
+
+### AGENTS.md Format (MUST follow exactly)
+
+> ### [Date] Analysis of [filename]
+> - **Source file**: `path/to/source/data.csv`
+> - **Analysis type**: exploratory | confirmatory | diagnostic | descriptive
+> - **Key findings**: Brief summary of main insights (1-2 sentences)
+> - **Output location**: `tmp/output/filename_analysis.json`
+> - **Copied to**: `shared/static/filename_analysis.json` (if applicable)
+> - **Type definition**: `shared/static/types.ts` → `FilenameAnalysis`
+>
+> #### Consumption
+>
+> ```typescript
+> import type { FilenameAnalysis } from '@shared/static/types';
+> import rawData from '@shared/static/filename_analysis.json';
+>
+> const data = rawData as FilenameAnalysis;
+> // access fields: data.insights, data.statistics, data.visualizations, etc.
+> ```
+
+### Example Entry
+
+> ### 2024-01-15 Analysis of sales_2023.csv
+> - **Source file**: `data/sales_2023.csv`
+> - **Analysis type**: exploratory
+> - **Key findings**: Strong correlation between customer age and order amount (r=0.72). Order amounts show right-skewed distribution.
+> - **Output location**: `tmp/output/sales_2023_exploratory.json`
+> - **Copied to**: `shared/static/sales_2023_exploratory.json`
+> - **Type definition**: `shared/static/types.ts` → `Sales2023Exploratory`
+>
+> #### Consumption
+>
+> ```typescript
+> import type { Sales2023Exploratory } from '@shared/static/types';
+> import rawData from '@shared/static/sales_2023_exploratory.json';
+>
+> const data = rawData as Sales2023Exploratory;
+> const highInsights = data.insights.filter(i => i.significance === 'high');
+> ```
+
+## 2. Report Output Locations
+
+After completing analysis, report to user:
+
+```text
+Analysis complete! Artifacts saved to:
+
+📁 tmp/
+├── output/
+│   ├── sales_2023_exploratory.json      # Structured analysis result
+│   └── visualizations/
+│       ├── sales_2023_age_vs_amount.png # Scatter plot
+│       └── sales_2023_amount_dist.png   # Histogram
+└── intermediate/
+    └── sales_2023_cleaned.csv           # Cleaned data (if applicable)
+
+To use in your code, copy the JSON to shared/static/:
+  mkdir -p shared/static/ && cp tmp/output/sales_2023_exploratory.json shared/static/
+
+Then import directly in your code:
+  import analysisData from '@shared/static/sales_2023_exploratory.json'
+```