@loom-framework/core 0.1.0-alpha.16 → 0.1.0-alpha.160

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

@@ -0,0 +1,285 @@
+# 用 Loom 开发 AI 平台
+
+## 30 秒理解 Loom
+
+你写一个配置文件描述你的数据模型和 AI 按钮，Loom 生成一个可运行的平台。然后你和 AI 一起迭代它。
+
+```
+你写的          Loom 生成的              你和 AI 继续做的
+loom.config.ts  →  页面 + API + AI 对话  →  改布局、加功能、调样式
+```
+
+## 开发方式
+
+Loom 项目的主要交互方式是**和 AI 对话**。你告诉 AI 想要什么，AI 通过 Loom Skill 知道怎么用 Loom 实现它。
+
+两个入口，同一个 AI：
+
+- **终端 Claude Code** — 适合搭建阶段、大范围代码修改
+- **页面右侧 AI 面板** — 适合日常操作数据、小范围页面调整
+
+两个入口背后是同一个 Claude Code 引擎、同一套项目上下文。在哪边改都行。
+
+## 第一个项目
+
+假设你要做一个**错题管理平台**。
+
+### 第 1 步：告诉 AI 你的想法
+
+在 Claude Code 中说：
+
+> 用 loom 创建一个错题管理平台，项目名 wrong-questions，filesystem 适配器。
+> 需要两个模型：错题记录（科目、题目内容、错误答案、正确答案、错误类型、是否掌握）和复习计划（错题ID、计划日期、状态）。
+> AI 按钮要能分析错因和出类似题。
+
+AI 会读取 Loom Skill，自动执行：
+
+1. `loom init wrong-questions --adapter filesystem` — 创建项目（自动生成系统管理页面）
+2. 编写 `loom.config.ts` — 把你的需求转成配置
+3. `loom generate page` — 生成页面
+4. `loom generate capabilities` — 生成应用 Skill
+5. `loom generate dashboard` — 生成数据概览
+6. 补充项目级 AI Skill — 让 AI 理解你的业务语义
+
+你也可以自己跑命令，但通过 Loom Skill 让 AI 来做更省事 — 它知道每一步该做什么。
+
+### 第 2 步：看看效果
+
+```bash
+cd wrong-questions
+loom dev
+```
+
+打开 http://localhost:5173 ，你的平台已经能用了：
+- 顶部导航有「错题记录」和「复习计划」页面
+- 每个页面有新增、编辑、删除、筛选
+- 错题记录每行有 AI 按钮：分析错因、出类似题
+- 右侧 AI 面板可以自然语言操作数据
+
+### 第 3 步：继续和 AI 聊
+
+平台跑起来后，你主要的工作方式是对 AI 说需求：
+
+| 你说的 | AI 做的 |
+|-------|--------|
+| "帮我记一道数学错题，3+5=7，正确答案是8" | 用 `loom data write` 创建记录 |
+| "看看哪些错题还没掌握" | 查数据并展示 |
+| "把这个页面改成卡片布局" | 修改页面 TSX |
+| "加一个学期字段" | 改 loom.config.ts + 改页面 + 更新 Skill references |
+| "加一个科目分布的饼图" | 修改 Dashboard 页面 |
+
+这些操作在终端 Claude Code 和页面对话框里都能做。
+
+## 配置变更与迭代
+
+改了 `loom.config.ts` 后，不同类型的变更需要不同的处理方式：
+
+| 变更类型 | 页面需要改吗 | 怎么做 |
+|---------|------------|--------|
+| 增删 AI 按钮 | 不需要 | 改配置 → `loom generate capabilities` 更新 Skill → 重启后端，按钮自动出现在页面 |
+| 修改 enum 值 | 不需要 | 改配置 → `loom generate capabilities` 更新 Skill → 重启后端，筛选和下拉自动更新 |
+| 新增数据模型 | 需要生成新页面 | 改配置 → `loom generate capabilities` + `loom generate page <Name> --model <model>` → 重启后端 |
+| 新增/删除字段 | 需要 | 改配置 → AI 更新页面（推荐）或 `--force` 重建 → `loom generate capabilities` 更新 Skill |
+
+**推荐：AI 辅助迭代**。告诉 AI 你改了什么（比如"我在配置里加了一个学期字段"），AI 会在页面中精确添加新字段的列和表单项，**保留你之前做的视觉定制代码**。
+
+**谨慎使用 `--force`**。它会用最新配置全量覆盖页面，之前对页面做的任何定制修改都会丢失。
+
+```bash
+# 只改了 AI 按钮或 enum → 重启后端即可，不用碰页面
+# 加了新字段 → 让 AI 更新页面
+# 想重来一个干净页面 → --force
+loom generate page WrongQuestions --model wrong_questions --force
+```
+
+页面不存在时直接 `loom generate page` 即可，不需要 `--force`。
+
+## 配置写法
+
+`loom.config.ts` 是唯一配置源，包含数据模型、AI 按钮和 Dashboard 定义。完整的字段类型和高级选项见 `references/data-model.md`。
+
+```typescript
+import { defineConfig } from '@loom-framework/core';
+
+export default defineConfig({
+  project: { name: 'my-app', description: { 'zh-CN': '我的应用', 'en-US': 'My App' } },
+  data: {
+    defaultAdapter: 'filesystem',
+    models: [{
+      name: 'tasks',
+      description: { 'zh-CN': '任务管理', 'en-US': 'Tasks' },
+      fields: [
+        { name: 'title', type: 'string', required: true, description: { 'zh-CN': '任务标题', 'en-US': 'Title' } },
+        { name: 'status', type: 'string', enum: ['待办', '进行中', '已完成'], enumLabels: {
+          '待办': { 'zh-CN': '待办', 'en-US': 'Todo' },
+          '进行中': { 'zh-CN': '进行中', 'en-US': 'In Progress' },
+          '已完成': { 'zh-CN': '已完成', 'en-US': 'Done' },
+        }, default: '待办' },
+        { name: 'priority', type: 'string', enum: ['低', '中', '高'] },
+      ],
+    }],
+  },
+  aiButtons: [{
+    id: 'breakdown',
+    label: { 'zh-CN': '拆解任务', 'en-US': 'Break Down Task' },
+    prompt: '请将这个任务拆解为可执行的子步骤：{{title}}',
+    placement: 'tasks',
+  }],
+  dashboards: [{
+    name: 'overview',
+    description: { 'zh-CN': '数据概览', 'en-US': 'Overview' },
+    models: ['tasks'],
+    layout: [
+      { row: [
+        { type: 'stat', title: { 'zh-CN': '任务总数', 'en-US': 'Total Tasks' }, model: 'tasks', aggregate: 'count', span: 6 },
+        { type: 'pie', title: { 'zh-CN': '状态分布', 'en-US': 'Status Distribution' }, model: 'tasks', groupBy: 'status', span: 8 },
+        { type: 'bar', title: { 'zh-CN': '优先级分布', 'en-US': 'Priority Distribution' }, model: 'tasks', groupBy: 'priority', span: 8 },
+      ]}
+    ],
+  }],
+});
+```
+
+- 所有展示文本（description、label、title）支持多语言：纯字符串 `'任务管理'` 或 `{ 'zh-CN': '任务管理', 'en-US': 'Tasks' }`
+- `enum` 是存储值（所有语言一致），`enumLabels` 为每个值提供多语言显示文本
+- AI 按钮的 `prompt` 支持 `{{fieldName}}` 插值，运行时替换为当前行的字段值
+- `placement` 限制按钮只出现在指定模型页面，省略则全局显示
+- Dashboard 的 15 种图表类型和配置 Schema 见 `references/dashboard.md`
+
+## 项目级 AI Skill
+
+每个项目的 `.claude/skills/<项目名>/SKILL.md` 是 AI 理解你业务的入口。`loom generate capabilities` 生成骨架（`references/` 下的内容自动维护），但 SKILL.md 主文档需要你补充三个地方：
+
+1. **description**：写用户会说的话，如 `"记录错题", "查看错题", "分析错因"`
+2. **Overview**：2-3 句话描述平台做什么
+3. **Usage Scenarios**：5-10 个典型用户请求及对应的 `loom data` 命令
+
+补充后，AI 在终端和对话框里都能理解"帮我查数学错题"这类业务请求。
+
+## 数据操作
+
+不打开页面也能操作数据。你可以自己跑命令，也可以让 AI 跑：
+
+```bash
+loom data read wrong_questions --filter '{"subject":"数学"}' --limit 10
+loom data write wrong_questions --data '{"subject":"数学","questionContent":"3+5=?","wrongAnswer":"7","correctAnswer":"8"}'
+loom data update wrong_questions --id rec_xxx --data '{"isMastered":true}'
+loom data delete wrong_questions --id rec_xxx
+loom data schema wrong_questions    # 查看字段结构
+```
+
+## 后端扩展
+
+需要自定义 API 路由时，编辑 `backend/src/index.ts`：
+
+```typescript
+import { LoomServer } from '@loom-framework/core';
+
+const server = new LoomServer({
+  projectRoot,
+  hooks: {
+    afterInit({ app, adapter }) {
+      app.get('/api/v1/stats/trend', async (req, reply) => { ... });
+    },
+  },
+});
+await server.initialize();
+await server.start();
+```
+
+不需要时就是原来的 3 行。
+
+## AI 模型配置
+
+在**系统配置 > 模型管理**页面中配置 AI 模型。也可以直接编辑 `loom.config.ts`：
+
+```typescript
+export default defineConfig({
+  ai: {
+    claudeCode: {
+      models: [
+        { name: 'claude-sonnet-4-20250514', isDefault: true },
+        { name: 'GLM-5.1', authToken: 'your-token', baseUrl: 'https://api.example.com' },
+      ],
+    },
+  },
+});
+```
+
+- `isDefault`：对话时默认使用的模型
+- `authToken`：API 认证令牌，页面中显示脱敏，编辑时留空保持不变
+- `baseUrl`：自定义 API 地址（适用于第三方模型）
+- 页面和配置文件双向同步：在页面修改模型后会自动写入 `loom.config.ts`
+
+在 AI 面板顶部的模型选择器中切换当前对话使用的模型。
+
+## 文件上传
+
+AI 对话支持上传文件，两种方式：
+
+- **附件按钮** — 点击输入框左侧的回形针图标选择文件
+- **粘贴上传** — 直接粘贴截图或复制的文件
+
+上传的文件会随对话发送给 AI 分析。图片在气泡中显示缩略图，其他文件显示为可下载的标签。文件大小上限约 30MB。
+
+## 页面功能控制
+
+通过 `crud` 配置字段控制生成页面的功能：
+
+```typescript
+models: [{
+  name: 'tasks',
+  fields: [...],
+  crud: {
+    export: false,        // 隐藏导出按钮
+    import: false,        // 隐藏导入按钮
+    deleteWithUndo: false, // 删除改为确认对话框（而非撤销模式）
+  },
+}],
+```
+
+省略 `crud` 字段时默认全部启用。
+
+## 日期分区
+
+数据可按日期字段自动分区存储，适合日志类数据：
+
+```typescript
+models: [{
+  name: 'logs',
+  fields: [
+    { name: 'content', type: 'string' },
+    { name: 'createdAt', type: 'string' },
+  ],
+  datePattern: {
+    dateField: 'createdAt',
+    pattern: 'yyyy/MM',  // 按月分区：data/logs/2026/04/*.json
+  },
+}],
+```
+
+## 常见问题
+
+**loom 命令报错 "No loom.config.ts found"**
+在项目根目录下运行。
+
+**better-sqlite3 加载失败**
+`defaultAdapter` 改为 `'filesystem'`，或者 `cd node_modules/better-sqlite3 && npx node-gyp rebuild`。
+
+**改了 loom.config.ts 页面没变**
+取决于改了什么：AI 按钮和 enum 值变更是自动生效的（重启后端即可）；字段增删需要让 AI 更新页面或 `--force` 重建。详见上方「配置变更与迭代」。
+
+**改了配置后 AI 按钮没出现**
+需要重启后端（`loom dev` 会自动重载，如果没生效就停掉重新 `loom dev`）。
+
+**删除了配置中的字段，旧数据怎么办**
+数据文件中的旧字段值不会删除，只是页面不再展示。如果之后加回同名字段，旧数据会自动恢复显示。
+
+**--force 会丢掉我的页面定制吗**
+会。`--force` 全量覆盖页面文件。如果你对页面做过视觉或交互定制，建议让 AI 辅助迭代而不是用 `--force`。
+
+**AI 面板里的 AI 能改代码吗**
+能。和终端 Claude Code 是同一个引擎，在哪边改都行。
+
+**如何部署到生产环境**
+`loom build` 构建前端和后端，然后 `node dist/backend/src/index.js` 启动后端。

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

@@ -0,0 +1,257 @@
+# 生成 Dashboard（数据概览页面）
+
+Dashboard 在 `loom.config.ts` 的 `dashboards` 字段中定义，然后通过 CLI 生成页面。
+
+## 配置 Dashboard
+
+在 `loom.config.ts` 中添加 `dashboards` 字段：
+
+```typescript
+import { defineConfig } from '@loom-framework/core';
+
+export default defineConfig({
+  project: { name: 'my-app' },
+  data: { /* ... */ },
+  dashboards: [{
+    name: 'overview',
+    description: { 'zh-CN': '数据概览', 'en-US': 'Overview' },
+    models: ['items'],
+    layout: [
+      { row: [{ type: 'stat', title: { 'zh-CN': '总数', 'en-US': 'Total' }, model: 'items', aggregate: 'count', span: 6 }] },
+    ],
+  }],
+});
+```
+
+**设计原则：**
+- 统计卡片放第一行（一眼看到关键数字）
+- 分布图表按业务重要性排列
+- 趋势图放最后一行（需要更多空间）
+- 每行不超过 4 个元素
+- 标题用业务语言，不用字段名
+
+### 配置 Schema
+
+```typescript
+{
+  name: 'overview',           // 必填：Dashboard 标识（同模型命名规则）
+  description: { 'zh-CN': '数据概览', 'en-US': 'Overview' },  // 可选：支持多语言
+  models: ['model_a'],        // 必填：关联的数据模型名列表
+  layout: [{                  // 必填：布局定义，数组每项代表一行
+    row: [{                   // 每行包含一组 widget
+      type: 'stat',           // 图表类型，见下方图表类型表
+      title: { 'zh-CN': '总数', 'en-US': 'Total' },  // 支持多语言
+      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 字段时有效 |
+
+### Dashboard 级别配置
+
+除了 `layout` 中的 widget 配置，Dashboard 还支持以下顶级配置：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `defaultDateField` | string | 默认日期字段名。启用后 Dashboard 顶部显示日期范围选择器，选择日期后筛选条件发送到后端（`__range` filter） |
+| `filterDimensions` | `DashboardFilterDimension[]` | 筛选维度定义。启用后 Dashboard 顶部显示对应的筛选控件，选择的值作为 filter 发送到后端 |
+
+#### DashboardFilterDimension
+
+```typescript
+{
+  field: 'subject',           // 必填：筛选字段名
+  label: { 'zh-CN': '科目' }, // 必填：显示标签，支持多语言
+  type: 'select',             // 必填：'select'（下拉选择）| 'dateRange'（日期范围）
+  options: ['语文', '数学'],   // 可选：select 类型的选项。省略则从数据中自动提取去重值
+}
+```
+
+**筛选机制：** 日期范围和 select 筛选器变更后只加载符合条件的数据，清除筛选后恢复加载全量数据。
+
+**典型配置：**
+
+```typescript
+dashboards: [{
+  name: 'overview',
+  models: ['wrong_questions'],
+  defaultDateField: 'createdAt',          // 启用日期范围筛选
+  filterDimensions: [                      // 启用下拉筛选
+    { field: 'subject', label: { 'zh-CN': '科目', 'en-US': 'Subject' }, type: 'select' },
+    { field: 'difficulty', label: { 'zh-CN': '难度', 'en-US': 'Difficulty' }, type: 'select' },
+  ],
+  layout: [/* ... */],
+}]
+```
+
+### 图表类型与配置要点
+
+#### 数值类 — 展示关键指标
+
+| 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 热力图（密度/交叉分析，颜色深浅表示数量） |
+
+## 执行 generate dashboard
+
+配置好 `dashboards` 字段后，运行命令生成页面：
+
+```bash
+loom generate dashboard <name>
+```
+
+此命令会：
+1. 从 `loom.config.ts` 的 `dashboards` 字段读取配置
+2. 验证引用的模型是否存在
+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 种图表的配置：
+
+```typescript
+import { defineConfig } from '@loom-framework/core';
+
+export default defineConfig({
+  project: { name: 'wrong-questions' },
+  data: { /* ... */ },
+  dashboards: [{
+    name: 'overview',
+    description: { 'zh-CN': '错题数据概览', 'en-US': 'Overview' },
+    models: ['wrong_questions', 'review_plans'],
+    defaultDateField: 'createdAt',
+    filterDimensions: [
+      { field: 'subject', label: { 'zh-CN': '科目', 'en-US': 'Subject' }, type: 'select' },
+      { field: 'difficulty', label: { 'zh-CN': '难度', 'en-US': 'Difficulty' }, type: 'select' },
+    ],
+    layout: [
+      {
+        row: [
+          { type: 'stat', title: { 'zh-CN': '错题总数', 'en-US': 'Total Questions' }, model: 'wrong_questions', aggregate: 'count', span: 4 },
+          { type: 'stat', title: { 'zh-CN': '掌握率', 'en-US': 'Mastery Rate' }, model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 4 },
+          { type: 'gauge', title: { 'zh-CN': '掌握率仪表盘', 'en-US': 'Mastery Gauge' }, model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 6 },
+          { type: 'liquid', title: { 'zh-CN': '掌握率水波图', 'en-US': 'Mastery Liquid' }, model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 5 },
+          { type: 'stat', title: { 'zh-CN': '平均复习次数', 'en-US': 'Avg Reviews' }, model: 'wrong_questions', aggregate: 'avg', field: 'reviewCount', span: 5 }
+        ]
+      },
+      {
+        row: [
+          { type: 'pie', title: { 'zh-CN': '科目分布', 'en-US': 'By Subject' }, model: 'wrong_questions', groupBy: 'subject', span: 8 },
+          { type: 'ring', title: { 'zh-CN': '难度分布', 'en-US': 'By Difficulty' }, model: 'wrong_questions', groupBy: 'difficulty', span: 8 },
+          { type: 'bar', title: { 'zh-CN': '错误类型分布', 'en-US': 'By Error Type' }, model: 'wrong_questions', groupBy: 'errorType', span: 8 }
+        ]
+      },
+      {
+        row: [
+          { type: 'line', title: { 'zh-CN': '错题录入趋势', 'en-US': 'Questions Trend' }, model: 'wrong_questions', groupBy: 'createdAt', interval: 'month', span: 12 },
+          { type: 'area', title: { 'zh-CN': '复习计划趋势', 'en-US': 'Review Plans Trend' }, model: 'review_plans', groupBy: 'createdAt', interval: 'month', span: 12 }
+        ]
+      },
+      {
+        row: [
+          { type: 'radar', title: { 'zh-CN': '各科目概览', 'en-US': 'Subject Overview' }, model: 'wrong_questions', groupBy: 'subject', span: 8 },
+          { type: 'stacked_bar', title: { 'zh-CN': '科目×错误类型', 'en-US': 'Subject × Error Type' }, model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'errorType', span: 8 },
+          { type: 'grouped_bar', title: { 'zh-CN': '科目×难度', 'en-US': 'Subject × Difficulty' }, model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'difficulty', span: 8 }
+        ]
+      },
+      {
+        row: [
+          { type: 'scatter', title: { 'zh-CN': '科目分布散点', 'en-US': 'Subject Scatter' }, model: 'wrong_questions', groupBy: 'subject', span: 8 },
+          { type: 'funnel', title: { 'zh-CN': '错误类型漏斗', 'en-US': 'Error Type Funnel' }, model: 'wrong_questions', groupBy: 'errorType', span: 8 },
+          { type: 'treemap', title: { 'zh-CN': '科目×难度树图', 'en-US': 'Subject × Difficulty Tree' }, model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'difficulty', span: 8 }
+        ]
+      },
+      {
+        row: [
+          { type: 'heatmap', title: { 'zh-CN': '科目×年级热力图', 'en-US': 'Subject × Grade Heatmap' }, 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' }],
+}} />
+```