@loom-framework/core 0.1.0-alpha.9 → 0.1.0-alpha.90

package/builtin-skills/chart-visualization/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: chart-visualization
+description: 将数据可视化为图表。当用户需要生成柱状图、折线图、饼图、散点图、雷达图、桑基图、思维导图、流程图等图表时调用此技能，通过 curl 工具调用 AntV API 生成图表图片
+---
+
+请根据用户输入的内容，将数据可视化为图表。
+
+## 步骤
+1. 分析用户数据和需求，选择最合适的图表类型
+2. 构造符合规范的 JSON 请求体
+3. 使用 curl 工具调用 API 生成图表图片
+4. 将返回的图片 URL 以 Markdown 图片格式输出
+
+## 图表选择指南
+
+根据用户的数据特征和需求，选择最合适的图表类型：
+
+- **时间序列**：用 `line`（趋势）或 `area`（累计趋势）；两个不同量纲用 `dual-axes`
+- **比较类**：用 `bar`（横向分类对比）或 `column`（纵向分类对比）；频率分布用 `histogram`
+- **占比类**：用 `pie`（比例构成）或 `treemap`（层级占比）
+- **关系与流程**：用 `scatter`（相关性）、`sankey`（流向）或 `venn`（集合重叠）
+- **层级与树形**：用 `organization-chart` 或 `mind-map`
+- **专用类型**：
+  - `radar`：多维度对比
+  - `funnel`：流程阶段转化
+  - `liquid`：百分比/进度
+  - `word-cloud`：文本词频
+  - `boxplot` / `violin`：统计分布
+  - `network-graph`：复杂节点关系
+  - `fishbone-diagram`：因果分析
+  - `flow-diagram`：流程图
+  - `spreadsheet`：结构化数据表或透视表
+
+## API 接口
+
+POST https://antv-studio.alipay.com/api/gpt-vis
+
+请求体为 JSON，必须包含 `type` 和 `source: "chart-visualization-skills"` 字段。
+
+示例：
+```bash
+curl -X POST https://antv-studio.alipay.com/api/gpt-vis \
+  -H "Content-Type: application/json" \
+  -d '{"type":"line","source":"chart-visualization-skills","data":[{"time":"2025-01","value":100}],"title":"示例图表"}'
+```
+
+返回示例：
+```json
+{"success":true,"resultObj":"https://..."}
+```
+
+将 `resultObj` 中的 URL 以 Markdown 图片格式输出：`![图表](URL)`
+
+## 支持的图表类型
+
+| 分类 | 图表类型 |
+|------|---------|
+| 比较类 | 条形图(bar)、柱状图(column)、瀑布图(waterfall)、双轴图(dual-axes) |
+| 趋势类 | 面积图(area)、折线图(line)、散点图(scatter) |
+| 分布类 | 箱线图(boxplot)、直方图(histogram)、小提琴图(violin)、漏斗图(funnel) |
+| 占比类 | 饼图(pie)、水波图(liquid)、词云(word-cloud) |
+| 层级类 | 组织架构图(organization-chart)、思维导图(mind-map)、矩形树图(treemap)、桑基图(sankey) |
+| 关系类 | 关系图(network-graph)、韦恩图(venn) |
+| 流程类 | 流程图(flow-diagram)、鱼骨图(fishbone-diagram) |
+| 多维类 | 雷达图(radar) |
+| 表格类 | 表格/透视表(spreadsheet) |
+
+## 通用可选参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| theme | string | "default" | 主题："default" / "academy" / "dark" |
+| width | number | 600 | 图表宽度 |
+| height | number | 400 | 图表高度 |
+| title | string | "" | 图表标题 |
+| style.texture | string | "default" | 纹理："default" / "rough"（手绘风格） |
+
+带坐标轴的图表还支持：axisXTitle、axisYTitle。
+
+## 各图表 data 格式
+
+- **area / line**: `{time: string, value: number, group?: string}[]`，可选 stack: boolean
+- **bar**: `{category: string, value: number, group?: string}[]`，可选 group / stack (默认 stack: true)
+- **column**: `{category: string, value: number, group?: string}[]`，可选 group (默认 true) / stack
+- **scatter**: `{x: number, y: number, group?: string}[]`
+- **pie**: `{category: string, value: number}[]`，可选 innerRadius: number (0-1)
+- **radar**: `{name: string, value: number, group?: string}[]`
+- **funnel**: `{category: string, value: number}[]`
+- **waterfall**: `{category: string, value?: number, isTotal?: boolean, isIntermediateTotal?: boolean}[]`
+- **dual-axes**: categories: string[], series: {type: "column"|"line", data: number[], axisYTitle?: string}[]
+- **histogram**: `number[]`，可选 binNumber: number
+- **boxplot / violin**: `{category: string, value: number, group?: string}[]`
+- **liquid**: percent: number (0-1)，可选 shape: "circle"|"rect"|"pin"|"triangle"
+- **word-cloud**: `{text: string, value: number}[]`
+- **sankey**: `{source: string, target: string, value: number}[]`，可选 nodeAlign
+- **treemap**: `{name: string, value: number, children?: ...}[]` (最深 3 层)
+- **venn**: `{sets: string[], value: number, label?: string}[]`
+- **network-graph / flow-diagram**: `{nodes: {name: string}[], edges: {source: string, target: string, name?: string}[]}`
+- **fishbone-diagram / mind-map**: `{name: string, children?: ...}` (最深 3 层)
+- **organization-chart**: `{name: string, description?: string, children?: ...}` (最深 3 层)，可选 orient: "horizontal"|"vertical"
+- **spreadsheet**: `Record<string, string | number>[]`，可选 rows / columns / values（透视表字段）

package/builtin-skills/loom/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: Loom
+description: |
+  Use this skill when the user asks to "create a new loom project", "用loom开发一个系统",
+  "开发一个AI平台应用", "为系统添加页面", "为项目配置 AI 按钮功能", or any Loom framework task.
+  Loom is an AI-Native full-stack framework.
+version: 0.1.0
+---
+
+# Loom - AI 原生全栈框架技能
+
+## 框架工作方式
+
+Loom 是**配置驱动、自动生成**的框架。工作流程为：
+
+1. **写配置** — 编辑 `loom.config.ts`，定义数据模型和 AI 按钮
+2. **跑命令** — CLI 读取配置，自动生成页面、API 和路由接线
+
+`loom generate page` 会自动生成：CRUD 页面（含 AI 按钮）、App.tsx 路由接线、后端 API + 应用 Skill。
+生成的页面自带 AI 助手浮动按钮，支持流式对话、多会话和数据自动刷新。
+
+技术架构细节见 `references/README.md`。
+
+## 开发流程
+
+**重要：** 始终在项目目录下运行命令（不是 loom monorepo 根目录）。
+
+### 1. 创建项目
+
+```bash
+npx -p @loom-framework/core loom init <name> --description <desc> --adapter <filesystem|sqlite>
+```
+
+项目初始化时自动安装以下内置 Skill：
+
+| Skill | 触发场景 | 说明 |
+|-------|---------|------|
+| **antd** | 开发前端页面、丰富 UI 功能 | 通过 `@ant-design/cli` 查询组件 API、语义化样式、示例；编写前端代码前先用此 Skill 确认用法 |
+| **antv-g2-chart** | 添加自定义可视化图表 | 生成 G2 v5 Spec 代码；配合 `useChartData` / `DashboardChart`，详见 `references/dashboard.md` |
+| **chart-visualization** | 对话中快速生成图表 | 通过 API 生成图表图片返回 Markdown 链接，适合快速展示数据分析结果 |
+
+### 2. 编辑配置
+
+编辑 `loom.config.ts`，定义数据模型（`data.models`）和 AI 按钮（`aiButtons`），Schema 见下方。高级选项见 `references/data-model.md`。
+
+### 3. 生成页面
+
+```bash
+loom generate page <Name> --model <model-name>
+```
+
+此命令自动生成：CRUD 页面（含 AI 按钮）、App.tsx 路由接线、后端 API、应用 Skill。模型立即可通过 `loom data` CLI 和 AI 对话使用。
+
+### 4. 生成 Dashboard（数据概览）
+
+Dashboard 采用**两阶段**工作流：AI 生成配置 → CLI 生成页面。
+
+**阶段 1：生成 dashboard.config.json**
+
+根据 `loom.config.ts` 中的数据模型，站在用户角度设计 Dashboard，生成 `dashboard.config.json` 到项目根目录。设计原则和配置 Schema 详见 `references/dashboard.md`。
+
+**阶段 2：执行生成命令**
+
+```bash
+loom generate dashboard <name>
+```
+
+此命令自动生成 Dashboard 页面并接线 App.tsx。
+
+### 5. 完善 AI Skill（必须）
+
+步骤 3 会自动生成应用 Skill（`.claude/skills/<项目名>/SKILL.md`），但需要补充以下 TODO，AI 对话才能正确理解项目业务语义：
+
+1. **frontmatter `description`**：写入用户在 AI 对话中会说的触发短语。格式参考：
+   ```
+   This skill should be used when the user asks to "创建XXX", "查看XXX", "删除XXX",
+   or any request about managing XXX in the <项目名> project.
+   ```
+2. **Overview 部分**：用 2-3 句话描述项目做什么、有哪些数据、用户如何与数据交互
+3. **Usage Scenarios 部分**：列出 5-10 个典型用户请求，格式为 `- "用户说的话" → 对应的 CLI 命令`
+
+如需添加自定义 Skill：
+- `loom generate skill <name>` — 创建脚手架，然后编辑 `.claude/skills/<name>/SKILL.md`
+- 或直接复制一个已有的 Skill 目录到 `.claude/skills/` 下
+
+### 6. 启动开发
+
+```bash
+loom dev
+```
+
+- 前端：http://localhost:5173
+- 后端：http://localhost:3000
+
+### 迭代：修改配置 → 重新生成
+
+编辑 `loom.config.ts`（添加/修改模型或 AI 按钮）→ 重新执行步骤 3。
+
+### 内置 Skill 使用原则
+
+- 涉及前端页面开发 → 先用 `/antd` 查询组件 API，不要凭记忆写代码
+- 需要在 Dashboard 追加图表 → 参考 `references/dashboard.md` + `/antv-g2-chart` 生成代码
+- 对话中需展示数据可视化 → 用 `/chart-visualization` 生成图片
+
+### CLI 命令速查
+
+| 命令 | 说明 |
+|------|------|
+| `loom dev` | 启动开发环境（`--skip-generate` `--backend-only` `--frontend-only`） |
+| `loom build` | 生产构建 |
+| `loom generate page <name> --model <model>` | 生成 CRUD 页面 + 应用 Skill（含 aiButtons 则自动集成） |
+| `loom generate dashboard <name>` | 从 dashboard.config.json 生成 Dashboard 数据概览页面 |
+| `loom generate capabilities` | 仅重新生成应用 Skill 的 `references/models.md` |
+| `loom generate skill <name>` | 生成自定义 Skill 脚架 |
+
+## loom.config.ts Schema（核心）
+
+```typescript
+import { defineConfig } from '@loom-framework/core';
+
+export default defineConfig({
+  project: {
+    name: 'my-app',           // 必填
+    description: '...',',     // 可选
+  },
+  data: {
+    defaultAdapter: 'filesystem',  // 'filesystem' | 'sqlite'
+    models: [{
+      name: 'items',          // 将作为 React 组件名生成页面，字母开头，字母/数字/下划线
+      description: '...',',   // 可选：显示在生成页面中
+      fields: [{
+        name: 'status',       // 字母/下划线开头，字母数字下划线
+        type: 'string',       // 'string' | 'number' | 'boolean' | 'date' | 'string[]' | 'number[]' | 'json'
+        required: true,       // 可选，默认 false
+        description: '...,',  // 可选：显示在表单中
+        default: 'active',    // 可选：写入时自动填充
+        enum: ['active', 'inactive'],  // 可选：限制可选值
+      }],
+    }],
+  },
+  aiButtons: [{               // 可选
+    id: 'summarize',          // 必填：唯一标识
+    label: '总结',             // 必填：按钮文本
+    prompt: '请总结以下内容',    // 必填：支持 {{var}} 引用当前行字段值
+  },
+  {
+    id: 'analyze',            // 带变量的示例
+    label: '分析',
+    prompt: '分析{{questionContent}}，错误答案：{{wrongAnswer}}',
+    placement: 'wrong_questions',  // 可选：限制按钮只出现在指定模型页面，逗号分隔多个模型名；省略则出现在所有页面
+  }],
+});
+```
+
+高级配置（`ai.claudeCode`、`server`、按模型 `adapters`、`indexes`）见 `references/data-model.md`。
+
+## API 路由格式
+
+后端 REST API 路径为 `/api/v1/data/<model-name>`，支持：`GET`（列表）、`GET /:id`（单条）、`POST`（创建）、`PUT /:id`（更新）、`DELETE /:id`（删除）。
+AI 相关：`POST /api/v1/chat`（SSE 流式对话）、`GET /api/v1/sessions`（会话列表）。
+前端通过 `useData('<model-name>')` 自动访问，无需手动拼接。
+
+**注意：** `sqlite` 适配器在 Node.js ≥ 25 时可能因 `better-sqlite3` 原生模块未编译而报错，改用 `filesystem` 即可。
+
+## 常见问题
+
+- **better-sqlite3 加载失败**：Node.js 版本缺少预编译包。修复：(1) `cd node_modules/better-sqlite3 && npx node-gyp rebuild`，或 (2) 将 `defaultAdapter` 改为 `'filesystem'`
+- **`loom` 命令报错 "No loom.config.ts found"**：在项目目录下运行命令

package/builtin-skills/loom/references/README.md

@@ -0,0 +1,128 @@
+# Loom - AI-Native Full-Stack Framework
+
+编织 AI 能力为应用织物
+
+## 快速上手
+
+### 1. 安装 npm 包
+
+Loom 包含两个包：
+
+- `@loom-framework/core` — CLI + 后端（全局安装以使用 `loom` 命令）
+- `@loom-framework/frontend-antd` — 前端组件库（项目运行时依赖，`loom init` 自动添加）
+
+```bash
+npm install -g @loom-framework/core
+```
+
+### 2. 配置 Skill 到 Claude Code
+
+Loom Skill 随 npm 包发布，位于 `builtin-skills/loom/` 目录。复制到 Claude Code 的 skill 目录：
+
+```bash
+# 从全局安装复制
+cp -r $(npm root -g)/@loom-framework/core/builtin-skills/loom ~/.claude/skills/loom
+
+# 或从项目内复制
+cp -r node_modules/@loom-framework/core/builtin-skills/loom ~/.claude/skills/loom
+```
+
+### 3. 打开 Claude Code
+
+启动 Claude Code，Skill 会被自动加载。
+
+### 4. 开始使用
+
+在 Claude Code 中输入以下内容触发 Loom Skill：
+
+### 开始开发
+
+在 Claude Code 中输入以下内容即可触发 Loom Skill：
+
+- "用 loom 开发一个 AI 平台"
+- "创建一个 loom 项目"
+- "为系统添加页面"
+- "配置 AI 按钮"
+
+示例对话：
+
+```
+用户: 用 loom 开发一个笔记管理系统，用 sqlite 存储，
+     需要 AI 总结和翻译功能
+Claude: [读取 SKILL.md] → 运行 loom init → 编辑 config →
+       loom generate page → loom dev
+```
+
+### 开发流程
+
+1. **创建项目**：`npx -p @loom-framework/core loom init <name> --description <desc> --adapter <adapter>`
+2. **编辑配置**：在 `loom.config.ts` 中定义数据模型和 AI 按钮
+3. **生成页面**：`loom generate page <Name> --model <model>`
+4. **启动开发**：`loom dev` → http://localhost:5173
+
+## 核心理念
+
+- **Prompt as Code**: 业务逻辑写在 Skill 的 Markdown 中，而非后端代码
+- **Schema-driven**: 一个数据实体定义 → Skill + CLI 命令 + REST API（自动同步）
+- **Zero Backend Logic**: 后端是透明代理，所有智能在 Skill 中
+
+## 三种交互类型
+
+| 类型 | 说明 | 用户入口 | 自动化程度 |
+|------|------|---------|-----------|
+| AI Chat | 自然语言对话 | AppShell 右下角浮动按钮 | 开箱即用，无需配置 |
+| AI Buttons | 一键 AI 动作 | CRUD 页面操作列的 AI 下拉菜单 | 配置 aiButtons + generate page，自动集成 |
+| CRUD | 结构化数据管理 | 导航菜单页面 | 配置 model + generate page，自动生成 |
+
+## 组件架构
+
+```
+AppShell
+  ├── Layout (Sider + Content)
+  └── AIBubble → ChatDrawer → ChatPanel
+        ├── LoomChatProvider + useXChat
+        ├── MessageContent (thinking / content / tool_call)
+        └── Sender (输入框 + 文件上传)
+
+AIActionButton → AIContext.triggerAI() → ChatDrawer 自动提交
+useData → 监听 loom:data-changed 事件自动刷新
+```
+
+### AI 按钮工作流
+
+1. 点击 AI 按钮 → `AIContext.triggerAI({ query, buttonId, context })`
+2. ChatDrawer 打开并自动提交 prompt
+3. AI 可能通过工具调用进行 CRUD 操作
+4. done 事件触发 `loom:data-changed` → useData 自动 refresh
+
+### 前端组件导出
+
+| 组件/Hook | 说明 |
+|-----------|------|
+| `AppShell` | 应用布局框架，内含 AIBubble |
+| `ChatDrawer` | AI 对话抽屉（多会话、流式、thinking/tool_call） |
+| `AIBubble` | AI 浮动按钮（imperativeHandle: openWithQuery） |
+| `AIActionButton` | AI 动作按钮（通过 AIContext 触发 ChatDrawer） |
+| `AIContext` | AI 上下文（AppShell 提供 triggerAI） |
+| `useData` | 数据 CRUD hook（自动响应 loom:data-changed 事件） |
+
+## 项目结构
+
+```
+my-loom-app/
+├── loom.config.ts                 # 配置源
+├── frontend/src/components/pages/ # 业务页面
+├── backend/src/                   # Fastify + AI 通信
+├── .claude/skills/                # Skills
+├── cli/src/commands/              # CLI 命令扩展
+├── data/                          # 数据存储
+└── .loom/                         # 自动生成（gitignore）
+    └── sessions/                  # AI 会话持久化
+```
+
+## 两个包
+
+| 包 | 说明 |
+|---|---|
+| `@loom-framework/core` | DataAdapter、LoomServer、CLI（loom / loom-server） |
+| `@loom-framework/frontend-antd` | 前端组件库：AppShell、ChatDrawer、AIActionButton、useData、AIContext |

package/builtin-skills/loom/references/dashboard.md

@@ -0,0 +1,196 @@
+# 生成 Dashboard（数据概览页面）
+
+Dashboard 采用**两阶段**工作流：AI 设计配置 → 代码生成页面。
+
+## 阶段 1：生成 dashboard.config.json
+
+根据项目的 `loom.config.ts` 中的数据模型，站在用户角度设计 Dashboard，生成 `dashboard.config.json` 到项目根目录。
+
+**设计原则：**
+- 统计卡片放第一行（一眼看到关键数字）
+- 分布图表按业务重要性排列
+- 趋势图放最后一行（需要更多空间）
+- 每行不超过 4 个元素
+- 标题用业务语言，不用字段名
+
+### 配置 Schema
+
+```jsonc
+{
+  "name": "overview",           // 必填：Dashboard 标识（同模型命名规则）
+  "description": "数据概览",     // 可选：侧边栏展示名
+  "models": ["model_a", "model_b"],  // 必填：关联的数据模型名列表
+  "layout": [                    // 必填：布局定义，数组每项代表一行
+    {
+      "row": [                   // 每行包含一组 widget
+        {
+          "type": "stat",        // 图表类型，见下方图表类型表
+          "title": "总数",       // 业务语言标题
+          "model": "model_a",   // 数据模型名
+          "span": 6,            // 可选：Col 宽度（1-24），省略则自动均分
+          "aggregate": "count", // 可选：count|sum|avg|min|max|ratio（默认 count）
+          "field": "score",     // aggregate 为 sum/avg/min/max 时必填：数值字段名
+          "filter": { "status": "active" },  // 可选：聚合前筛选条件
+          "groupBy": "category", // 可选：分组字段（string/enum/date/boolean）
+          "crossGroupBy": "grade", // 可选：第二分组字段，用于二维图表
+          "interval": "month"   // 可选：date 字段分组粒度 day|week|month（默认 month）
+        }
+      ]
+    }
+  ]
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `aggregate` | `count\|sum\|avg\|min\|max\|ratio` | 聚合方式。`ratio` = 符合 filter 条件的记录数/总记录数，用于 gauge/liquid/stat 百分比 |
+| `field` | string | 聚合目标字段。仅 aggregate 为 sum/avg/min/max 时需要 |
+| `filter` | object | 筛选条件，键值对。如 `{"isMastered": true}` 筛选已掌握的记录 |
+| `groupBy` | string | 主分组字段。string/enum 字段按值分组计数；boolean 字段自动映射为"是/否"；date 字段按 interval 分段 |
+| `crossGroupBy` | string | 第二分组维度。配合 groupBy 使用，产生交叉分组数据，用于二维图表 |
+| `interval` | `day\|week\|month` | date 字段的分组粒度，仅 groupBy 指向 date 字段时有效 |
+
+### 图表类型与配置要点
+
+#### 数值类 — 展示关键指标
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `stat` | 统计卡片 | — | `{ aggregate: "count" }` 或 `{ aggregate: "avg", field: "score" }` 或 `{ aggregate: "ratio", filter: { passed: true } }` | Ant Design Statistic 数值卡片 |
+| `gauge` | 仪表盘 | `aggregate: "ratio"` + `filter` | `{ aggregate: "ratio", filter: { isMastered: true } }` | G2 仪表盘（百分比进度） |
+| `liquid` | 水波图 | `aggregate: "ratio"` + `filter` | `{ aggregate: "ratio", filter: { isMastered: true } }` | G2 水波图（百分比进度） |
+
+> **说明**：gauge 和 liquid 使用 `aggregate: "ratio"` + `filter` 来计算百分比（如掌握率 = 已掌握数/总数），ratio 自动算出 0-1 之间的值。
+
+#### 占比类 — 展示分布构成
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `pie` | 饼图 | `groupBy` (enum/string) | `{ groupBy: "subject" }` | G2 饼图（分布占比） |
+| `ring` | 环形图 | `groupBy` (boolean/enum) | `{ groupBy: "difficulty" }` 或 `{ groupBy: "isMastered" }` | G2 环形图（占比对比，boolean 自动映射"是/否"） |
+| `treemap` | 矩形树图 | `groupBy` + 可选 `crossGroupBy` | `{ groupBy: "subject" }` 或 `{ groupBy: "subject", crossGroupBy: "difficulty" }` | G2 矩形树图（层级占比，有 crossGroupBy 则两层） |
+
+#### 对比类 — 跨类别比较
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `bar` | 条形图 | `groupBy` | `{ groupBy: "errorType" }` | G2 条形图（横向分类对比） |
+| `stacked_bar` | 堆叠条形图 | `groupBy` + `crossGroupBy` | `{ groupBy: "subject", crossGroupBy: "errorType" }` | G2 堆叠条形图（组成+对比） |
+| `grouped_bar` | 分组条形图 | `groupBy` + `crossGroupBy` | `{ groupBy: "subject", crossGroupBy: "difficulty" }` | G2 分组条形图（并列对比） |
+| `radar` | 雷达图 | `groupBy` | `{ groupBy: "subject" }` | G2 雷达图（多维度闭合多边形） |
+| `funnel` | 漏斗图 | `groupBy` | `{ groupBy: "errorType" }` | G2 漏斗图（阶段转化，柱条宽度反映数值） |
+
+#### 趋势类 — 时间维度变化
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `line` | 折线图 | `groupBy` (date 字段) + `interval` | `{ groupBy: "createdAt", interval: "month" }` | G2 折线图（时间趋势） |
+| `area` | 面积图 | `groupBy` (date 字段) + `interval` | `{ groupBy: "createdAt", interval: "month" }` | G2 面积图（累计趋势） |
+
+#### 分布类 — 交叉/密度分析
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `scatter` | 散点图 | `groupBy` | `{ groupBy: "subject" }` | G2 散点图（相关性/分布） |
+| `heatmap` | 热力图 | `groupBy` + `crossGroupBy` | `{ groupBy: "subject", crossGroupBy: "grade" }` | G2 热力图（密度/交叉分析，颜色深浅表示数量） |
+
+## 阶段 2：执行 generate dashboard
+
+用户审查 `dashboard.config.json` 后，运行命令生成页面：
+
+```bash
+loom generate dashboard <name>
+```
+
+此命令会：
+1. 读取并校验 `dashboard.config.json`
+2. 验证引用的模型是否存在于 `loom.config.ts`
+3. 生成 Dashboard TSX 页面（含 `useData` + `useChartData` + `DashboardChart`）
+4. 自动接线 App.tsx（添加 import、navItem、switch case）
+5. 检测 `@antv/g2` 是否已安装，未安装则提示
+
+**前置依赖：** Dashboard 使用 @antv/g2 渲染图表，需在 frontend 目录安装：
+
+```bash
+cd frontend && pnpm add @antv/g2
+```
+
+## 完整配置示例
+
+以小学生错题管理平台为例，展示所有 15 种图表的配置：
+
+```json
+{
+  "name": "overview",
+  "description": "错题数据概览",
+  "models": ["wrong_questions", "review_plans"],
+  "layout": [
+    {
+      "row": [
+        { "type": "stat", "title": "错题总数", "model": "wrong_questions", "aggregate": "count", "span": 4 },
+        { "type": "stat", "title": "掌握率", "model": "wrong_questions", "aggregate": "ratio", "filter": { "isMastered": true }, "span": 4 },
+        { "type": "gauge", "title": "掌握率仪表盘", "model": "wrong_questions", "aggregate": "ratio", "filter": { "isMastered": true }, "span": 6 },
+        { "type": "liquid", "title": "掌握率水波图", "model": "wrong_questions", "aggregate": "ratio", "filter": { "isMastered": true }, "span": 5 },
+        { "type": "stat", "title": "平均复习次数", "model": "wrong_questions", "aggregate": "avg", "field": "reviewCount", "span": 5 }
+      ]
+    },
+    {
+      "row": [
+        { "type": "pie", "title": "科目分布", "model": "wrong_questions", "groupBy": "subject", "span": 8 },
+        { "type": "ring", "title": "难度分布", "model": "wrong_questions", "groupBy": "difficulty", "span": 8 },
+        { "type": "bar", "title": "错误类型分布", "model": "wrong_questions", "groupBy": "errorType", "span": 8 }
+      ]
+    },
+    {
+      "row": [
+        { "type": "line", "title": "错题录入趋势", "model": "wrong_questions", "groupBy": "createdAt", "interval": "month", "span": 12 },
+        { "type": "area", "title": "复习计划趋势", "model": "review_plans", "groupBy": "createdAt", "interval": "month", "span": 12 }
+      ]
+    },
+    {
+      "row": [
+        { "type": "radar", "title": "各科目概览", "model": "wrong_questions", "groupBy": "subject", "span": 8 },
+        { "type": "stacked_bar", "title": "科目×错误类型", "model": "wrong_questions", "groupBy": "subject", "crossGroupBy": "errorType", "span": 8 },
+        { "type": "grouped_bar", "title": "科目×难度", "model": "wrong_questions", "groupBy": "subject", "crossGroupBy": "difficulty", "span": 8 }
+      ]
+    },
+    {
+      "row": [
+        { "type": "scatter", "title": "科目分布散点", "model": "wrong_questions", "groupBy": "subject", "span": 8 },
+        { "type": "funnel", "title": "错误类型漏斗", "model": "wrong_questions", "groupBy": "errorType", "span": 8 },
+        { "type": "treemap", "title": "科目×难度树图", "model": "wrong_questions", "groupBy": "subject", "crossGroupBy": "difficulty", "span": 8 }
+      ]
+    },
+    {
+      "row": [
+        { "type": "heatmap", "title": "科目×年级热力图", "model": "wrong_questions", "groupBy": "subject", "crossGroupBy": "grade", "span": 24 }
+      ]
+    }
+  ]
+}
+```
+
+## 追加自定义图表
+
+生成后的 Dashboard 页面是普通 TSX，可直接编辑追加图表：
+
+1. 使用 `useChartData` / `useCrossGroupChartData` / `useTreemapChartData` 准备数据
+2. 使用 `/antv-g2-chart` skill 生成 G2 v5 Spec 代码
+3. 添加 `<DashboardChart spec={...} />` 组件
+
+示例——追加一个科目×年级的堆叠柱状图：
+
+```tsx
+// 在已有的 Dashboard 页面中追加
+const subjectGradeData = useCrossGroupChartData(wrongQuestionsList, { groupBy: 'subject', crossGroupBy: 'grade' });
+
+<DashboardChart spec={{
+  type: 'interval',
+  data: subjectGradeData,
+  encode: { x: 'group', y: 'value', color: 'name' },
+  coordinate: { transform: [{ type: 'transpose' }] },
+  transform: [{ type: 'stackY' }],
+}} />
+```

package/builtin-skills/loom/references/data-model.md

@@ -0,0 +1,78 @@
+# Data Model Reference
+
+Advanced configuration for `loom.config.ts`. Full type definitions from `packages/core/src/types.ts`.
+
+## FieldDefinition
+
+```typescript
+{
+  name: 'status',         // ^[a-zA-Z_][a-zA-Z0-9_]*$
+  type: 'string',         // 'string' | 'number' | 'boolean' | 'date' | 'string[]' | 'number[]' | 'json'
+  required: true,         // optional, default false
+  description: '...',     // optional: shown in generated forms
+  default: 'active',      // optional: auto-filled on write if not provided
+  enum: ['active', 'inactive', 'archived'],  // optional: restrict string field to allowed values
+}
+```
+
+## ModelSchema
+
+```typescript
+{
+  name: 'orders',              // ^[a-zA-Z][a-zA-Z0-9_]*$, will be used as React component name
+  description: 'Order records', // optional: shown in generated page heading
+  fields: [...],
+  indexes?: [{ fields: ['userId', 'status'], unique: false }],
+  adapters?: {                  // optional: per-model adapter override
+    filesystem: { dir: 'orders', format: 'json' | 'yaml', datePattern: 'YYYY-MM' },
+    sqlite: { table: 'orders' },
+  },
+}
+```
+
+## AIButtonConfig
+
+```typescript
+aiButtons: [{
+  id: 'summarize',          // required: unique identifier
+  label: '总结',             // required: button text
+  icon: 'FileTextOutlined', // optional: Ant Design icon component name
+  prompt: '请总结以下内容',   // required: supports {{var}} placeholders, replaced with current row field values
+  placement: 'wrong_questions',  // optional: limit to specific model pages, comma-separated; omit for all pages
+}]
+```
+
+## AIConfig
+
+```typescript
+ai: {
+  engine: 'claude-code',       // default 'claude-code'
+  claudeCode: {
+    path: '/usr/local/bin/claude',  // optional: custom claude binary path
+    pluginRoot: '.claude',          // optional: plugin root directory
+    timeout: 120000,                // optional: command timeout in ms
+    skipPermissions: false,         // optional: skip permission prompts
+  },
+}
+```
+
+## ServerConfig
+
+```typescript
+server: {
+  port: 3000,              // default 3000
+  host: '0.0.0.0',
+  cors: true,              // default true
+  staticDir: './dist/frontend',
+}
+```
+
+## DataConfig
+
+```typescript
+data: {
+  defaultAdapter: 'filesystem' | 'sqlite',
+  models: [...],
+  sqlite: { filename: 'loom.db' },  // optional, default 'loom.db'
+}
+```