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

package/builtin-skills/loom/SKILL.md

@@ -53,19 +53,13 @@ loom generate page <Name> --model <model-name>
 
 ### 4. 生成 Dashboard（数据概览）
 
-Dashboard 采用**两阶段**工作流：AI 生成配置 → CLI 生成页面。
-
-**阶段 1：生成 dashboard.config.json**
-
-根据 `loom.config.ts` 中的数据模型，站在用户角度设计 Dashboard，生成 `dashboard.config.json` 到项目根目录。设计原则和配置 Schema 详见 `references/dashboard.md`。
-
-**阶段 2：执行生成命令**
+Dashboard 配置在 `loom.config.ts` 的 `dashboards` 字段中定义。设计原则和配置 Schema 详见 `references/dashboard.md`。
 
 ```bash
 loom generate dashboard <name>
 ```
 
-此命令自动生成 Dashboard 页面并接线 App.tsx。
+此命令从 `loom.config.ts` 的 `dashboards` 字段读取配置，自动生成 Dashboard 页面并接线 App.tsx。
 
 ### 5. 完善 AI Skill（必须）
 
@@ -94,7 +88,11 @@ loom dev
 
 ### 迭代：修改配置 → 重新生成
 
-编辑 `loom.config.ts`（添加/修改模型或 AI 按钮）→ 重新执行步骤 3。
+编辑 `loom.config.ts`（添加/修改模型或 AI 按钮）→ 重新执行步骤 3，加 `--force` 覆盖已有页面：
+
+```bash
+loom generate page <Name> --model <model-name> --force
+```
 
 ### 内置 Skill 使用原则
 
@@ -109,7 +107,9 @@ loom dev
 | `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 page <name> --model <model> --force` | 覆盖已有页面 |
+| `loom generate dashboard <name>` | 从 loom.config.ts dashboards 生成 Dashboard 页面（fallback dashboard.config.json） |
+| `loom generate dashboard <name> --force` | 覆盖已有 Dashboard 页面 |
 | `loom generate capabilities` | 仅重新生成应用 Skill 的 `references/models.md` |
 | `loom generate skill <name>` | 生成自定义 Skill 脚架 |
 
@@ -149,6 +149,12 @@ export default defineConfig({
     prompt: '分析{{questionContent}}，错误答案：{{wrongAnswer}}',
     placement: 'wrong_questions',  // 可选：限制按钮只出现在指定模型页面，逗号分隔多个模型名；省略则出现在所有页面
   }],
+  dashboards: [{              // 可选：Dashboard 定义（不再使用独立的 dashboard.config.json）
+    name: 'overview',         // 必填：唯一标识，同命名规则
+    description: '数据概览',    // 可选
+    models: ['items'],        // 必填：关联的数据模型
+    layout: [{ row: [{ type: 'stat', title: '总数', model: 'items', aggregate: 'count', span: 6 }] }],
+  }],
 });
 ```
 
@@ -156,9 +162,9 @@ export default defineConfig({
 
 ## API 路由格式
 
-后端 REST API 路径为 `/api/v1/data/<model-name>`，支持：`GET`（列表）、`GET /:id`（单条）、`POST`（创建）、`PUT /:id`（更新）、`DELETE /:id`（删除）。
+后端 REST API 路径为 `/api/v1/data/<model-name>`，支持：`GET`（列表）、`GET /:id`（单条）、`POST`（创建）、`PUT /:id`（更新）、`DELETE /:id`（删除）、`GET /schema`（模型 Schema + AI 按钮）。
 AI 相关：`POST /api/v1/chat`（SSE 流式对话）、`GET /api/v1/sessions`（会话列表）。
-前端通过 `useData('<model-name>')` 自动访问，无需手动拼接。
+前端通过 `useData('<model-name>')` 自动访问，无需手动拼接。`useSchema('<model-name>')` 获取模型字段和 AI 按钮定义，`filterOptions(schema, fieldName)` 和 `selectOptions(schema, fieldName)` 将 enum 值转为 antd 组件格式。
 
 **注意：** `sqlite` 适配器在 Node.js ≥ 25 时可能因 `better-sqlite3` 原生模块未编译而报错，改用 `filesystem` 即可。
 

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

@@ -1,128 +1,185 @@
-# Loom - AI-Native Full-Stack Framework
+# 用 Loom 开发 AI 平台
 
-编织 AI 能力为应用织物
+## 30 秒理解 Loom
 
-## 快速上手
+你写一个配置文件描述你的数据模型和 AI 按钮，Loom 生成一个可运行的平台。然后你和 AI 一起迭代它。
 
-### 1. 安装 npm 包
-
-Loom 包含两个包：
+```
+你写的          Loom 生成的              你和 AI 继续做的
+loom.config.ts  →  页面 + API + AI 对话  →  改布局、加功能、调样式
+```
 
-- `@loom-framework/core` — CLI + 后端（全局安装以使用 `loom` 命令）
-- `@loom-framework/frontend-antd` — 前端组件库（项目运行时依赖，`loom init` 自动添加）
+## 开发方式
 
-```bash
-npm install -g @loom-framework/core
-```
+Loom 项目的主要交互方式是**和 AI 对话**。你告诉 AI 想要什么，AI 通过 Loom Skill 知道怎么用 Loom 实现它。
 
-### 2. 配置 Skill 到 Claude Code
+两个入口，同一个 AI：
 
-Loom Skill 随 npm 包发布，位于 `builtin-skills/loom/` 目录。复制到 Claude Code 的 skill 目录：
+- **终端 Claude Code** — 适合搭建阶段、大范围代码修改
+- **页面内对话框** — 适合日常操作数据、小范围页面调整
 
-```bash
-# 从全局安装复制
-cp -r $(npm root -g)/@loom-framework/core/builtin-skills/loom ~/.claude/skills/loom
+两个入口背后是同一个 Claude Code 引擎、同一套项目上下文。在哪边改都行。
 
-# 或从项目内复制
-cp -r node_modules/@loom-framework/core/builtin-skills/loom ~/.claude/skills/loom
-```
+## 第一个项目
 
-### 3. 打开 Claude Code
+假设你要做一个**错题管理平台**。
 
-启动 Claude Code，Skill 会被自动加载。
+### 第 1 步：告诉 AI 你的想法
 
-### 4. 开始使用
+在 Claude Code 中说：
 
-在 Claude Code 中输入以下内容触发 Loom Skill：
+> 用 loom 创建一个错题管理平台，项目名 wrong-questions，filesystem 适配器。
+> 需要两个模型：错题记录（科目、题目内容、错误答案、正确答案、错误类型、是否掌握）和复习计划（错题ID、计划日期、状态）。
+> AI 按钮要能分析错因和出类似题。
 
-### 开始开发
+AI 会读取 Loom Skill，自动执行：
 
-在 Claude Code 中输入以下内容即可触发 Loom Skill：
+1. `loom init wrong-questions --adapter filesystem` — 创建项目
+2. 编写 `loom.config.ts` — 把你的需求转成配置
+3. `loom generate page` — 生成页面
+4. `loom generate dashboard` — 生成数据概览
+5. 补充项目级 AI Skill — 让 AI 理解你的业务语义
 
-- "用 loom 开发一个 AI 平台"
-- "创建一个 loom 项目"
-- "为系统添加页面"
-- "配置 AI 按钮"
+你也可以自己跑命令，但通过 Loom Skill 让 AI 来做更省事 — 它知道每一步该做什么。
 
-示例对话：
+### 第 2 步：看看效果
 
-```
-用户: 用 loom 开发一个笔记管理系统，用 sqlite 存储，
-     需要 AI 总结和翻译功能
-Claude: [读取 SKILL.md] → 运行 loom init → 编辑 config →
-       loom generate page → loom dev
+```bash
+cd wrong-questions
+loom dev
 ```
 
-### 开发流程
+打开 http://localhost:5173 ，你的平台已经能用了：
+- 左侧导航有「错题记录」和「复习计划」页面
+- 每个页面有新增、编辑、删除、筛选
+- 错题记录每行有 AI 按钮：分析错因、出类似题
+- 右下角有 AI 对话框，可以自然语言操作数据
 
-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
+### 第 3 步：继续和 AI 聊
 
-## 核心理念
+平台跑起来后，你主要的工作方式是对 AI 说需求：
 
-- **Prompt as Code**: 业务逻辑写在 Skill 的 Markdown 中，而非后端代码
-- **Schema-driven**: 一个数据实体定义 → Skill + CLI 命令 + REST API（自动同步）
-- **Zero Backend Logic**: 后端是透明代理，所有智能在 Skill 中
+| 你说的 | AI 做的 |
+|-------|--------|
+| "帮我记一道数学错题，3+5=7，正确答案是8" | 用 `loom data write` 创建记录 |
+| "看看哪些错题还没掌握" | 查数据并展示 |
+| "把这个页面改成卡片布局" | 修改页面 TSX |
+| "加一个学期字段" | 改 loom.config.ts + 改页面 + 更新 Skill references |
+| "加一个科目分布的饼图" | 修改 Dashboard 页面 |
 
-## 三种交互类型
+这些操作在终端 Claude Code 和页面对话框里都能做。
 
-| 类型 | 说明 | 用户入口 | 自动化程度 |
-|------|------|---------|-----------|
-| AI Chat | 自然语言对话 | AppShell 右下角浮动按钮 | 开箱即用，无需配置 |
-| AI Buttons | 一键 AI 动作 | CRUD 页面操作列的 AI 下拉菜单 | 配置 aiButtons + generate page，自动集成 |
-| CRUD | 结构化数据管理 | 导航菜单页面 | 配置 model + generate page，自动生成 |
+## 配置变更
 
-## 组件架构
+改了 `loom.config.ts`（加了字段、改了 enum），页面不会自动更新。告诉 AI 你改了什么，AI 会同步更新页面。
 
+如果你想重来一个干净的页面：
+
+```bash
+loom generate page WrongQuestions --model wrong_questions --force
 ```
-AppShell
-  ├── Layout (Sider + Content)
-  └── AIBubble → ChatDrawer → ChatPanel
-        ├── LoomChatProvider + useXChat
-        ├── MessageContent (thinking / content / tool_call)
-        └── Sender (输入框 + 文件上传)
-
-AIActionButton → AIContext.triggerAI() → ChatDrawer 自动提交
-useData → 监听 loom:data-changed 事件自动刷新
+
+`--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: '我的应用' },
+  data: {
+    defaultAdapter: 'filesystem',
+    models: [{
+      name: 'tasks',
+      description: '任务管理',
+      fields: [
+        { name: 'title', type: 'string', required: true, description: '任务标题' },
+        { name: 'status', type: 'string', enum: ['待办', '进行中', '已完成'], default: '待办' },
+        { name: 'priority', type: 'string', enum: ['低', '中', '高'] },
+      ],
+    }],
+  },
+  aiButtons: [{
+    id: 'breakdown',
+    label: '拆解任务',
+    prompt: '请将这个任务拆解为可执行的子步骤：{{title}}',
+    placement: 'tasks',
+  }],
+  dashboards: [{
+    name: 'overview',
+    description: '数据概览',
+    models: ['tasks'],
+    layout: [
+      { row: [
+        { type: 'stat', title: '任务总数', model: 'tasks', aggregate: 'count', span: 6 },
+        { type: 'pie', title: '状态分布', model: 'tasks', groupBy: 'status', span: 8 },
+        { type: 'bar', title: '优先级分布', model: 'tasks', groupBy: 'priority', span: 8 },
+      ]}
+    ],
+  }],
+});
 ```
 
-### AI 按钮工作流
+- AI 按钮的 `prompt` 支持 `{{fieldName}}` 插值，运行时替换为当前行的字段值
+- `placement` 限制按钮只出现在指定模型页面，省略则全局显示
+- Dashboard 的 17 种图表类型和配置 Schema 见 `references/dashboard.md`
 
-1. 点击 AI 按钮 → `AIContext.triggerAI({ query, buttonId, context })`
-2. ChatDrawer 打开并自动提交 prompt
-3. AI 可能通过工具调用进行 CRUD 操作
-4. done 事件触发 `loom:data-changed` → useData 自动 refresh
+## 项目级 AI Skill
 
-### 前端组件导出
+每个项目的 `.claude/skills/<项目名>/SKILL.md` 是 AI 理解你业务的入口。`loom generate page` 会自动生成骨架，但需要你补充三个地方：
 
-| 组件/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 事件） |
+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    # 查看字段结构
 ```
-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 会话持久化
+
+## 后端扩展
+
+需要自定义 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 行。
+
+## 常见问题
+
+**loom 命令报错 "No loom.config.ts found"**
+在项目根目录下运行。
+
+**better-sqlite3 加载失败**
+`defaultAdapter` 改为 `'filesystem'`，或者 `cd node_modules/better-sqlite3 && npx node-gyp rebuild`。
+
+**改了 loom.config.ts 页面没变**
+告诉 AI 你改了什么，AI 会同步更新页面。或者用 `--force` 重建。
 
-| 包 | 说明 |
-|---|---|
-| `@loom-framework/core` | DataAdapter、LoomServer、CLI（loom / loom-server） |
-| `@loom-framework/frontend-antd` | 前端组件库：AppShell、ChatDrawer、AIActionButton、useData、AIContext |
+**对话框里的 AI 能改代码吗**
+能。和终端 Claude Code 是同一个引擎，在哪边改都行。

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

@@ -1,10 +1,27 @@
 # 生成 Dashboard（数据概览页面）
 
-Dashboard 采用**两阶段**工作流：AI 设计配置 → 代码生成页面。
-
-## 阶段 1：生成 dashboard.config.json
-
-根据项目的 `loom.config.ts` 中的数据模型，站在用户角度设计 Dashboard，生成 `dashboard.config.json` 到项目根目录。
+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: '数据概览',
+    models: ['items'],
+    layout: [
+      { row: [{ type: 'stat', title: '总数', model: 'items', aggregate: 'count', span: 6 }] },
+    ],
+  }],
+});
+```
 
 **设计原则：**
 - 统计卡片放第一行（一眼看到关键数字）
@@ -15,29 +32,25 @@ Dashboard 采用**两阶段**工作流：AI 设计配置 → 代码生成页面
 
 ### 配置 Schema
 
-```jsonc
+```typescript
 {
-  "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）
-        }
-      ]
-    }
-  ]
+  name: 'overview',           // 必填：Dashboard 标识（同模型命名规则）
+  description: '数据概览',     // 可选：侧边栏展示名
+  models: ['model_a'],        // 必填：关联的数据模型名列表
+  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）
+    }]
+  }]
 }
 ```
 
@@ -47,7 +60,7 @@ Dashboard 采用**两阶段**工作流：AI 设计配置 → 代码生成页面
 |------|------|------|
 | `aggregate` | `count\|sum\|avg\|min\|max\|ratio` | 聚合方式。`ratio` = 符合 filter 条件的记录数/总记录数，用于 gauge/liquid/stat 百分比 |
 | `field` | string | 聚合目标字段。仅 aggregate 为 sum/avg/min/max 时需要 |
-| `filter` | object | 筛选条件，键值对。如 `{"isMastered": true}` 筛选已掌握的记录 |
+| `filter` | object | 筛选条件，键值对。如 `{isMastered: true}` 筛选已掌握的记录 |
 | `groupBy` | string | 主分组字段。string/enum 字段按值分组计数；boolean 字段自动映射为"是/否"；date 字段按 interval 分段 |
 | `crossGroupBy` | string | 第二分组维度。配合 groupBy 使用，产生交叉分组数据，用于二维图表 |
 | `interval` | `day\|week\|month` | date 字段的分组粒度，仅 groupBy 指向 date 字段时有效 |
@@ -96,20 +109,20 @@ Dashboard 采用**两阶段**工作流：AI 设计配置 → 代码生成页面
 | `scatter` | 散点图 | `groupBy` | `{ groupBy: "subject" }` | G2 散点图（相关性/分布） |
 | `heatmap` | 热力图 | `groupBy` + `crossGroupBy` | `{ groupBy: "subject", crossGroupBy: "grade" }` | G2 热力图（密度/交叉分析，颜色深浅表示数量） |
 
-## 阶段 2：执行 generate dashboard
+## 执行 generate dashboard
 
-用户审查 `dashboard.config.json` 后，运行命令生成页面：
+配置好 `dashboards` 字段后，运行命令生成页面：
 
 ```bash
 loom generate dashboard <name>
 ```
 
 此命令会：
-1. 读取并校验 `dashboard.config.json`
-2. 验证引用的模型是否存在于 `loom.config.ts`
+1. 从 `loom.config.ts` 的 `dashboards` 字段读取配置
+2. 验证引用的模型是否存在
 3. 生成 Dashboard TSX 页面（含 `useData` + `useChartData` + `DashboardChart`）
 4. 自动接线 App.tsx（添加 import、navItem、switch case）
-5. 检测 `@antv/g2` 是否已安装，未安装则提示
+5. 检测 `@antv/g2` 是否已安装，未安装则自动安装
 
 **前置依赖：** Dashboard 使用 @antv/g2 渲染图表，需在 frontend 目录安装：
 
@@ -121,55 +134,61 @@ 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 }
-      ]
-    }
-  ]
-}
+```typescript
+import { defineConfig } from '@loom-framework/core';
+
+export default defineConfig({
+  project: { name: 'wrong-questions' },
+  data: { /* ... */ },
+  dashboards: [{
+    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 }
+        ]
+      }
+    ]
+  }],
+});
 ```
 
 ## 追加自定义图表

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

@@ -75,4 +75,42 @@ data: {
   models: [...],
   sqlite: { filename: 'loom.db' },  // optional, default 'loom.db'
 }
+```
+
+## DashboardConfig
+
+```typescript
+dashboards: [{
+  name: 'overview',           // ^[a-zA-Z][a-zA-Z0-9_]*$, same naming rules as model
+  description: '数据概览',     // optional: shown in sidebar navigation
+  models: ['items'],          // required: data models included in this dashboard
+  layout: [{                  // required: at least one row
+    row: [{                   // at least one widget per row
+      type: 'stat' | 'pie' | 'ring' | 'bar' | 'line' | 'area' | 'scatter' | 'radar' | 'funnel' | 'treemap' | 'gauge' | 'liquid' | 'heatmap' | 'stacked_bar' | 'grouped_bar',
+      title: '任务总数',       // required: display title
+      model: 'items',         // required: data model name
+      span: 6,                // optional: Ant Design Grid Col span (1-24), auto-equal-split if omitted
+      groupBy: 'status',      // optional: group by field for aggregation
+      crossGroupBy: 'priority', // optional: second group-by for 2D charts (heatmap, stacked_bar, grouped_bar)
+      aggregate: 'count',     // optional: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'ratio', default count
+      field: 'score',         // optional: numeric field for sum/avg/min/max
+      filter: { status: 'active' }, // optional: pre-aggregation filter
+      interval: 'month',      // optional: 'day' | 'week' | 'month' for date groupBy
+    }],
+  }],
+}]
+```
+
+## useSchema Runtime API
+
+Generated pages use `useSchema(model)` to fetch model schema and AI buttons at runtime:
+
+```typescript
+const { schema, loading, error } = useSchema('items');
+// schema.fields — field definitions with enum values
+// schema.aiButtons — AI buttons filtered by placement
+
+// Convert schema enum to antd formats:
+filterOptions(schema, 'status')  // → [{ text: 'active', value: 'active' }, ...]
+selectOptions(schema, 'status')  // → [{ label: 'active', value: 'active' }, ...]
 ```

package/dist/backend/index.js

@@ -86,7 +86,7 @@ export class LoomServer {
         }
         // Register routes
         registerHealthRoute(this.fastify, this.adapter);
-        registerDataRoutes(this.fastify, this.adapter);
+        registerDataRoutes(this.fastify, this.adapter, this.config);
         registerUploadRoutes(this.fastify, { projectRoot: this.projectRoot });
         registerChatRoutes(this.fastify, {
             engine: this.engine,