@loom-framework/core 0.1.0-alpha.14 → 0.1.0-alpha.140

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,213 @@
+---
+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>
+```
+
+项目初始化时自动创建 `CLAUDE.md`（项目根目录），Claude Code 会自动加载此文件作为 system prompt 上下文，提升 AI 对话效果。同时自动安装以下内置 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 配置在 `loom.config.ts` 的 `dashboards` 字段中定义。设计原则和配置 Schema 详见 `references/dashboard.md`。
+
+```bash
+loom generate dashboard <name>
+```
+
+此命令从 `loom.config.ts` 的 `dashboards` 字段读取配置，自动生成 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/` 下
+
+### 重启服务前必须询问用户
+
+修改 `loom.config.ts` 后如果需要重启后端服务（如增删 AI 按钮、修改 enum 值、新增模型等场景），**必须先询问用户是否可以重启**，得到确认后再执行 `loom dev` 或停止/重启服务。不要自动重启，因为用户可能正在使用页面或调试中。
+
+### 6. 启动开发
+
+```bash
+loom dev
+```
+
+- 前端：http://localhost:5173
+- 后端：http://localhost:3000
+
+### 迭代：修改配置后的处理
+
+不同类型的配置变更，处理方式不同：
+
+| 变更类型 | 需要改页面吗 | 怎么做 |
+|---------|------------|--------|
+| 增删 AI 按钮 | 不需要 | 改配置 → 重启后端，按钮自动出现/消失 |
+| 修改 enum 值 | 不需要 | 改配置 → 重启后端，筛选和下拉自动更新 |
+| 新增数据模型 | 需要生成新页面 | 改配置 → `loom generate page <Name> --model <model>` → 重启后端 |
+| 新增/删除字段 | 需要 | 改配置 → `--force` 重建（默认，最快）或 AI 增量更新（有定制时保留修改）→ 更新CLAUDE.md |
+
+**`--force` 重建（默认）**：字段变更时直接 `--force` 重建页面，是最快最干净的方式，页面与配置立即同步。`--force` 会自动将旧页面备份到 `.loom/backup/<时间戳>/` 目录，如需恢复直接复制回来即可。
+
+**AI 增量更新（有定制时）**：如果用户说"保留我的定制"或明确表示页面有手动修改过，才让 AI 增量更新。告诉 AI 你改了什么（如"我在配置里加了一个学期字段"），AI 会精确添加新字段的列和表单项，保留定制代码。如果AI进行了定制化开发，务必将定制化开发内容更新到CLAUDE.md，使得后续新启动会话时Claude Code可掌握项目定制化情况。
+
+```bash
+# 只改了 AI 按钮或 enum → 重启后端即可
+# 加了新字段 → --force 重建（默认）
+# 加了新字段，要保留页面定制 → 让 AI 增量更新
+loom generate page <Name> --model <model-name> --force
+```
+
+**恢复备份**：`--force` 覆盖的文件自动备份到项目 `.loom/backup/<时间戳>/` 目录（每次 --force 生成独立时间戳目录，同一天多次执行互不影响），如需恢复：`cp .loom/backup/<时间戳>/XXX.tsx frontend/src/components/pages/XXX.tsx`
+
+### 内置 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 page <name> --model <model> --force` | 重建页面（默认方式，自动备份旧文件到 `.loom/backup/`） |
+| `loom generate dashboard <name>` | 从 loom.config.ts dashboards 生成 Dashboard 页面 |
+| `loom generate dashboard <name> --force` | 重建 Dashboard 页面（自动备份旧文件到 `.loom/backup/`） |
+| `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: { 'zh-CN': '我的应用', 'en-US': 'My App' },  // 可选，支持多语言
+  },
+  data: {
+    defaultAdapter: 'filesystem',  // 'filesystem' | 'sqlite'
+    models: [{
+      name: 'items',          // 将作为 React 组件名生成页面，字母开头，字母/数字/下划线
+      description: { 'zh-CN': '数据项', 'en-US': 'Items' },   // 可选：支持多语言
+      fields: [{
+        name: 'status',       // 字母/下划线开头，字母数字下划线
+        type: 'string',       // 'string' | 'number' | 'boolean' | 'date' | 'string[]' | 'number[]' | 'json'
+        required: true,       // 可选，默认 false
+        description: { 'zh-CN': '状态', 'en-US': 'Status' },  // 可选：支持多语言
+        default: 'active',    // 可选：写入时自动填充
+        enum: ['active', 'inactive'],  // 可选：限制可选值（存储值，不随语言变化）
+        enumLabels: {                   // 可选：enum 值的多语言显示标签
+          active: { 'zh-CN': '激活', 'en-US': 'Active' },
+          inactive: { 'zh-CN': '停用', 'en-US': 'Inactive' },
+        },
+      }],
+    }],
+  },
+  aiButtons: [{               // 可选
+    id: 'summarize',          // 必填：唯一标识
+    label: { 'zh-CN': '总结', 'en-US': 'Summarize' },  // 必填：支持多语言
+    prompt: '请总结以下内容',    // 必填：支持 {{var}} 引用当前行字段值
+  },
+  {
+    id: 'analyze',            // 带变量的示例
+    label: { 'zh-CN': '分析', 'en-US': 'Analyze' },
+    prompt: '分析{{questionContent}}，错误答案：{{wrongAnswer}}',
+    placement: 'wrong_questions',  // 可选：限制按钮只出现在指定模型页面，逗号分隔多个模型名；省略则出现在所有页面
+  }],
+  dashboards: [{              // 可选：Dashboard 定义，完整配置见 references/dashboard.md
+    name: 'overview',         // 必填：唯一标识，同命名规则
+    description: { 'zh-CN': '数据概览', 'en-US': 'Overview' },  // 可选
+    models: ['items'],        // 必填：关联的数据模型
+    defaultDateField: 'createdAt',  // 可选：启用日期范围筛选
+    filterDimensions: [],     // 可选：启用下拉筛选，见 references/dashboard.md
+    layout: [{ row: [{ type: 'stat', title: { 'zh-CN': '总数', 'en-US': 'Total' }, model: 'items', aggregate: 'count', span: 6 }] }],
+  }],
+});
+```
+
+### 多语言（i18n）
+
+所有面向用户的展示字段均支持 `LocaleString` 格式：`string | Record<string, string>`。
+
+- **简单写法**：`description: '科目'` — 所有语言显示相同文本
+- **多语言写法**：`description: { 'zh-CN': '科目', 'en-US': 'Subject' }` — 切换语言时自动翻译
+- **enum 值**：`enum` 始终是存储值（不分语言），显示文本通过 `enumLabels` 翻译
+- **回退规则**：请求的 locale → `'zh-CN'` → 第一个可用值
+
+支持的 LocaleString 字段：`project.description`、`ModelSchema.description`、`FieldDefinition.description`、`AIButtonConfig.label`、`DashboardConfig.description`、`DashboardWidget.title`、`RelationConfig.label`
+
+生成页面会自动通过 `registerMessages()` 注册 i18n key，并使用 `t()` 调用引用，无需手动处理。
+
+高级配置（`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`（删除）、`GET /schema`（模型 Schema + AI 按钮）。
+AI 相关：`POST /api/v1/chat`（SSE 流式对话）、`GET /api/v1/sessions`（会话列表）。
+前端通过 `useData('<model-name>')` 自动访问，无需手动拼接。`useSchema('<model-name>')` 获取模型字段和 AI 按钮定义，自动根据当前 locale 请求服务端 resolved 数据。`filterOptions(schema, fieldName)` 和 `selectOptions(schema, fieldName)` 将 enum 值转为 antd 组件格式（使用 resolved 的 enumLabels）。`enumLabel(schema, fieldName, value)` 获取单个 enum 值的显示标签。
+
+## 常见问题
+
+- **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,211 @@
+# 用 Loom 开发 AI 平台
+
+## 30 秒理解 Loom
+
+你写一个配置文件描述你的数据模型和 AI 按钮，Loom 生成一个可运行的平台。然后你和 AI 一起迭代它。
+
+```
+你写的          Loom 生成的              你和 AI 继续做的
+loom.config.ts  →  页面 + API + AI 对话  →  改布局、加功能、调样式
+```
+
+## 开发方式
+
+Loom 项目的主要交互方式是**和 AI 对话**。你告诉 AI 想要什么，AI 通过 Loom Skill 知道怎么用 Loom 实现它。
+
+两个入口，同一个 AI：
+
+- **终端 Claude Code** — 适合搭建阶段、大范围代码修改
+- **页面内对话框** — 适合日常操作数据、小范围页面调整
+
+两个入口背后是同一个 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 dashboard` — 生成数据概览
+5. 补充项目级 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 按钮 | 不需要 | 改配置 → 重启后端，按钮自动出现在页面 |
+| 修改 enum 值 | 不需要 | 改配置 → 重启后端，筛选和下拉自动更新 |
+| 新增数据模型 | 需要生成新页面 | 改配置 → `loom generate page <Name> --model <model>` → 重启后端 |
+| 新增/删除字段 | 需要 | 改配置 → `--force` 重建（默认，最快）或 AI 增量更新（有定制时保留修改） |
+
+**`--force` 重建（默认）**：字段变更时直接 `--force` 重建页面，是最快最干净的方式，页面与配置立即同步。`--force` 会自动将旧页面备份到 `.loom/backup/<时间戳>/` 目录（每次 --force 生成独立时间戳目录，同一天多次执行互不影响），如需恢复直接复制回来即可。
+
+**AI 增量更新（有定制时）**：如果用户说"保留我的定制"或明确表示页面有手动修改过，才让 AI 增量更新。告诉 AI 你改了什么（比如"我在配置里加了一个学期字段"），AI 会在页面中精确添加新字段的列和表单项，**保留你之前做的视觉定制代码**。
+
+```bash
+# 只改了 AI 按钮或 enum → 重启后端即可，不用碰页面
+# 加了新字段 → --force 重建（默认）
+# 加了新字段，要保留页面定制 → 让 AI 增量更新
+loom generate page WrongQuestions --model wrong_questions --force
+```
+
+**恢复备份**：`--force` 覆盖的文件自动备份到 `.loom/backup/<时间戳>/` 目录，如需恢复：`cp .loom/backup/<时间戳>/XXX.tsx frontend/src/components/pages/XXX.tsx`
+
+页面不存在时直接 `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 按钮的 `prompt` 支持 `{{fieldName}}` 插值，运行时替换为当前行的字段值
+- `placement` 限制按钮只出现在指定模型页面，省略则全局显示
+- Dashboard 的 15 种图表类型和配置 Schema 见 `references/dashboard.md`
+
+## 项目级 AI Skill
+
+每个项目的 `.claude/skills/<项目名>/SKILL.md` 是 AI 理解你业务的入口。`loom generate page` 会自动生成骨架，但需要你补充三个地方：
+
+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 行。
+
+## 常见问题
+
+**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` 全量覆盖页面文件，但会自动将旧文件备份到 `.loom/backup/<时间戳>/` 目录。如果页面有定制且需要保留，用 AI 增量更新；如果页面没有定制，直接 `--force` 即可，是最快的方式。
+
+**对话框里的 AI 能改代码吗**
+能。和终端 Claude Code 是同一个引擎，在哪边改都行。
+
+**如何部署到生产环境**
+`loom build` 构建前端和后端，然后 `node dist/backend/src/index.js` 启动后端。