@loom-framework/core 0.1.0-alpha.19 → 0.1.0-alpha.190

package/builtin-skills/loom/SKILL.md

@@ -0,0 +1,308 @@
+---
+name: Loom
+description: |
+  This skill should be used 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 是**配置驱动的 AI 平台开发框架**——你描述需求，AI 通过本 Skill 执行 loom 命令来构建应用。
+
+典型使用方式：
+
+1. **用自然语言描述需求** — 告诉 Claude Code（或其它支持Skill的 Agent） 你要做什么（如"用 loom 开发一个告警管理平台"），Claude Code 会先加载本Skill，理解Loom的构建方式，然后交互式地向你确认完整项目功能需求，接着创建项目、启动服务
+2. **对话迭代** — 通过Claude Code 或 创建的项目 AI 对话面板改需求、加字段、调样式，AI 理解 loom 的工作方式，知道何时改配置、何时跑命令、何时直接改代码
+3. **日常运营** — 通过 AI 对话面板或 `loom data` CLI 查看、创建、更新数据
+
+核心能力：`loom generate page` 生成 CRUD 页面，`loom generate capabilities` 生成应用 Skill（让 AI 理解项目业务），`loom generate dashboard` 生成数据概览。后端 API 由 `loom dev` 根据配置动态注册，无需手动编写。生成的页面自带 AI 助手，支持流式对话和多会话。
+
+> **运行时操作**：项目创建后，日常运营（数据 CRUD、过程管理、事件订阅、通知操作）由 **App-Skill** 提供指引。App-Skill 在 `loom generate capabilities` 后自动生成于 `.claude/skills/<projectName>/`，与本 Skill 互补。
+
+完整使用手册见 `references/README.md`。
+
+## 开发流程
+
+**重要：** 始终在项目目录下运行命令（不是 loom monorepo 根目录）。
+
+### 1. 创建项目
+
+```bash
+npx -p @loom-framework/core loom init <name> --description <desc> --adapter <filesystem|sqlite> --backend-port <backend-port> --frontend-port <frontend-port>
+```
+
+**多实例并行**：每个 Loom 实例同时占用**后端端口**（Fastify）和**前端端口**（Vite dev server）。建议后端从 :3000 起自增，前端从 :5173 起自增，相邻实例使用连续端口方便管理：
+
+| 实例 | 后端端口 | 前端端口 |
+|------|---------|---------|
+| my-app | 3000 | 5173 |
+| my-app-2 | 3001 | 5174 |
+| my-app-3 | 3002 | 5175 |
+
+`loom init` 时**必须显式指定两个端口**。如果启动时报 `EADDRINUSE`，说明端口被占用，请换端口重新 `init`。
+
+项目初始化时自动生成系统管理页面（模型管理、技能管理、用户管理、过程管理、事件管理、通知中心），并以子菜单形式接入导航。同时自动安装以下内置 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 见下方 `loom.config.ts Schema` 。高级选项见 `references/data-model.md`。
+
+> **Dashboard 配置前置要求：** 编写配置文件中 `dashboards` 字段之前，**必须**先加载并阅读 `references/dashboard.md`。Dashboard 的 layout、widget 类型、filterDimensions等有严格的 Schema 约束，未读文档直接凭直觉编写会导致生成失败。
+
+### 3. 生成页面与 Dashboard
+
+#### 3.1 生成 CRUD 页面
+
+```bash
+loom generate page <Name> --model <model-name>
+```
+
+此命令自动生成：CRUD 页面（含 AI 按钮）、App.tsx 路由接线。后端 API 由 `loom dev` 启动时动态注册。模型立即可通过 `loom data` CLI 和 AI 对话使用。
+
+#### 3.2 生成 Dashboard（可选）
+
+如果 `loom.config.ts` 中配置了 `dashboards` 字段，执行：
+
+```bash
+loom generate dashboard <name>
+```
+
+此命令从 `dashboards` 字段读取配置，自动生成 Dashboard 页面并接线 App.tsx。
+
+### 4. 生成并完善应用 Skill
+
+```bash
+loom generate capabilities
+```
+
+此命令读取 `loom.config.ts`，在 `.claude/skills/<项目名>/` 下生成以下文件：
+
+| 文件 | 说明 | 覆盖策略 |
+|------|------|---------|
+| `SKILL.md` | Skill 主文档模版 | 仅首次创建，命令重复执行不覆盖文件。若需重建：删除整个 skill 目录后重新执行 |
+| `references/*.md` | 多个指导项目SKILL如何使用的引用文件 |
+
+首次生成项目SKILL后，需要补充其 `SKILL.md` 主文档中的 TODO 内容，AI 对话时才能正确理解项目业务语义：
+
+1. **frontmatter `description`**：系统操作触发短语已自动生成，只需补全数据模型相关的 `[TODO]` 占位部分（如 `'查看告警'`, `'添加任务'`）。格式参考：
+   ```
+   This skill should be used when the user asks to "[TODO: 补全数据模型相关短语]", '用户管理', '事件订阅', ...,
+   or any request about managing data, processes, events, or notifications 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/` 下
+
+### 5. 启用认证鉴权（可选）
+
+当用户需要多用户支持、权限控制时，帮助用户在 `loom.config.ts` 中添加 `auth` 配置：
+
+1. **询问需求**：是否需要登录功能？有哪些角色？每个角色能做什么？
+2. **编辑配置**：在 `loom.config.ts` 中添加 `auth` 字段（Schema 见上方）。至少定义一个 `admin` 角色
+3. **设置密钥**：`secret` 推荐 `env:LOOM_JWT_SECRET`，不要硬编码。提醒用户设置环境变量 `export LOOM_JWT_SECRET=your-secret`
+4. **生成认证页面**：`loom generate system-settings user` — 自动接入用户管理页和登录页的 npm import，并接入 AuthProvider 路由守卫
+5. **重启后端**：auth 配置需要重启后端生效（**必须先询问用户**）
+6. **首次登录**：默认创建 admin 用户（密码 `admin123`），**提醒用户立即修改密码**
+7. **生成 app-skill**：`loom generate capabilities` 更新 Skill 中的 auth.md
+
+启用后获得：登录页 + 路由守卫 + RBAC 权限控制 + 用户管理页 + CLI `--token`/`LOOM_TOKEN` 鉴权。
+
+> 如果 `loom init` 时配置中已包含 `auth` 字段，上述页面会在初始化时自动生成。后续添加 auth 配置时，手动执行 `loom generate system-settings user` 即可补全。
+
+### 6. 启动项目
+
+```bash
+loom dev                          # 启动前后端
+loom dev --backend-only           # 只启动后端
+loom dev --frontend-only          # 只启动前端
+loom dev --frontend-port 8080     # 临时覆盖前端端口
+```
+
+- **前端端口**：由 `loom.config.ts` 的 `server.frontendPort` 决定。`loom init` 时自动根据 `--frontend-port` 写入，`loom dev` 无需再传端口
+- **后端端口**：由 `loom.config.ts` 的 `server.backendPort` 决定。后端启动时自动读取
+- `--frontend-port`：作为 Vite CLI `--port` 参数传入，**临时覆盖**配置文件中的值
+
+### 7. 功能迭代
+
+不同类型的变更，处理方式不同：
+
+| 变更类型 | 需要改页面吗 | 怎么做 |
+|---------|------------|--------|
+| 增删 AI 按钮 | 不需要 | 改配置 → `loom generate capabilities` 更新 Skill → 重启后端，按钮自动出现/消失 |
+| 修改 enum 值 | 不需要 | 改配置 → `loom generate capabilities` 更新 Skill → 重启后端，筛选和下拉自动更新 |
+| 新增数据模型 | 需要生成新页面 | 改配置 → `loom generate capabilities` + `loom generate page <Name> --model <model>` → 重启后端 |
+| 新增/删除字段 | 需要 | 改配置 → `--force` 重建（默认，最快）或 AI 增量更新代码（有定制时保留修改）→ `loom generate capabilities` 更新 Skill → 更新CLAUDE.md |
+
+**`--force` 重建（默认）**：字段变更时直接 `--force` 重建页面，是最快最干净的方式，页面与配置立即同步。`--force` 会自动将旧页面备份到 `.loom/backup/<时间戳>/` 目录。
+**恢复备份**：`--force` 覆盖的文件自动备份到项目 `.loom/backup/<时间戳>/` 目录（每次 --force 生成独立时间戳目录，同一天多次执行互不影响），如需恢复：`cp .loom/backup/<时间戳>/XXX.tsx frontend/src/components/pages/XXX.tsx`
+修改 `loom.config.ts` 后如果需要重启后端服务（如增删 AI 按钮、修改 enum 值、新增模型等场景），**必须先询问用户是否可以重启**，得到确认后再执行 `loom dev` 或停止/重启服务。不要自动重启，因为用户可能正在使用页面或调试中。
+
+**AI 增量更新（有定制时）**：如果用户说"保留我的定制"或明确表示页面有手动修改过，才让 AI 增量更新。告诉 AI 你改了什么（如"我在配置里加了一个严重等级字段"），AI 会精确添加新字段的列和表单项，保留定制代码。如果AI进行了定制化开发，务必将定制化开发内容更新到CLAUDE.md，使得后续新启动会话时Claude Code可掌握项目定制化情况。
+
+### 8. 系统管理页面定制（Eject）
+
+系统管理页面默认以 npm 组件接入，无法直接修改。需要定制时 eject 为本地文件，恢复时 uneject。详见 `references/eject.md`。
+
+### 9. 内置 Skill 使用原则
+
+- 涉及前端页面开发 → 先用 `/antd` 查询组件 API，不要凭记忆写代码
+- 需要在 Dashboard 追加图表 → 参考 `references/dashboard.md` + `/antv-g2-chart` 生成代码
+- 对话中需展示数据可视化 → 用 `/chart-visualization` 生成图片
+
+### 10. CLI 命令速查
+
+| 命令 | 说明 |
+|------|------|
+| `loom dev` | 启动开发环境（`--backend-only` `--frontend-only` `--frontend-port`） |
+| `loom build` | 生产构建 |
+| `loom generate page <name> --model <model>` | 生成 CRUD 页面（含 aiButtons 则自动集成 AI 按钮） |
+| `loom generate page <name> --model <model> --force` | 重建页面（默认方式，自动备份旧文件到 `.loom/backup/`） |
+| `loom generate capabilities` | 生成应用 Skill（`references/models.md` + `references/data-semantics.md`，`SKILL.md` 仅首次创建不覆盖） |
+| `loom generate dashboard <name>` | 从 loom.config.ts dashboards 生成 Dashboard 页面 |
+| `loom generate dashboard <name> --force` | 重建 Dashboard 页面（自动备份旧文件到 `.loom/backup/`） |
+| `loom generate system-settings <type>` | 将系统页面接入 App.tsx（npm import 接线），type: `model`/`skill`/`user`/`login`/`process`/`notification`/`event`；`user` 同时接入 AuthProvider 路由守卫，`notification` 同时接入 NotificationCenterProvider |
+| `loom generate skill <name>` | 生成自定义 Skill 脚架 |
+| `loom eject system-settings <type>` | 将系统页面从 npm 组件切换为本地文件（可自由编辑），type: `model`/`skill`/`user`/`login`/`process`/`notification`/`event`。详见 `references/eject.md` |
+| `loom uneject system-settings <type>` | 删除本地文件，恢复为 npm 组件（修改过的需 `--force`，操作前自动备份）。详见 `references/eject.md` |
+| `loom data read <model>` | 查询数据（`--filter` 筛选、`--sort <field>` 排序字段、`--sortOrder asc\|desc` 排序方向、`--limit` 限制条数、`--id` 单条查询） |
+| `loom data write <model> --data '<json>'` | 创建记录 |
+| `loom data update <model> --id <id> --data '<json>'` | 更新记录 |
+| `loom data delete <model> --id <id>` | 删除记录 |
+| `loom data schema <model>` | 查看模型字段结构 |
+| `loom auth login --username <u> --password <p>` | 登录获取 token |
+| `loom auth register --username <u> --password <p> --token <jwt>` | 注册新用户（需 admin token） |
+| `loom auth whoami --token <jwt>` | 查看当前身份 |
+| `loom user add --username <u> -p <pw> -r <role> --token <jwt>` | 添加用户 |
+| `loom user list --token <jwt>` | 列出所有用户 |
+| `loom user role <userId> <role> --token <jwt>` | 修改用户角色 |
+| `loom role list` | 列出所有角色及权限 |
+
+## loom.config.ts Schema（核心）
+以下仅展示支持平台运行的最小业务配置参数，完整业务配置及系统配置说明见 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',  // 'filesystem' | 'sqlite'
+    models: [{
+      name: 'items',          // 将作为 React 组件名生成页面，字母开头，字母/数字/下划线
+      description: { 'zh-CN': '数据项', 'en-US': 'Items' },   // 可选：支持多语言
+      fields: [
+        {
+          name: 'createdAt',  // 推荐字段：创建/录入时间，Dashboard 趋势图和日期范围筛选依赖此字段
+          type: 'date',
+          required: true,
+          description: { 'zh-CN': '创建时间', 'en-US': 'Created At' },
+        },
+        {
+          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' },
+          },
+        },
+      ],
+    }],
+  },
+  relations: [{ /* 详见 references/data-model.md > RelationConfig */ }],
+  aiButtons: [{               // 可选
+    id: 'summarize',          // 必填：唯一标识
+    label: { 'zh-CN': '总结', 'en-US': 'Summarize' },  // 必填：支持多语言
+    prompt: '请总结以下内容',    // 必填：支持 {{var}} 引用当前行字段值
+  },
+  {
+    id: 'analyze',            // 带变量的示例
+    label: { 'zh-CN': '分析', 'en-US': 'Analyze' },
+    prompt: '分析告警原因：{{description}}，当前状态：{{status}}',
+    placement: 'alerts',  // 可选：限制按钮只出现在指定模型页面，逗号分隔多个模型名；省略则出现在所有页面
+  }],
+  dashboards: [{              // 可选：数据概览，widget/图表类型/筛选配置详见 references/dashboard.md
+    name: 'overview',         // 必填：唯一标识
+    models: ['items'],        // 必填：关联的数据模型
+    defaultDateField: 'createdAt',  // 可选：日期范围筛选字段
+    filterDimensions: [],     // 可选：select 下拉筛选维度
+    layout: [],               // 必填：布局定义（行→组件）
+  }],
+  auth: {                     // 可选：认证与鉴权，启用后生成登录页、用户管理、RBAC 权限控制
+    provider: 'builtin',      // 'builtin' — 内置认证
+    secret: 'env:JWT_SECRET', // JWT 签名密钥，推荐用 env: 引用环境变量，不要硬编码
+    accessTokenTtl: 3600,     // 可选，access token 有效期（秒），默认 3600（1h）
+    refreshTokenTtl: 604800,  // 可选，refresh token 有效期（秒），默认 604800（7d）
+    roles: [                  // 角色定义，至少一个 admin 角色
+      { role: 'admin', permissions: [{ model: '*', level: 'admin' }] },
+      { role: 'viewer', permissions: [{ model: '*', level: 'read' }] },
+    ],
+    permissions: {            // 可选：默认权限和行为配置
+      defaults: {
+        read: 'read',                   // 未显式配置的模型默认读权限
+        write: 'write',                 // 未显式配置的模型默认写权限
+        writeExcludesDelete: false,     // write 权限是否排除删除操作
+      },
+    },
+  },
+  events: {                    // 可选：事件系统
+    enabled: true,             // 可选，是否启用（默认 true），设为 false 可禁用
+    subscriptions: [           // 可选：声明式事件订阅（服务启动时自动注册，修改后需重启生效）
+      { pattern: 'data:create:modelName', handler: 'process', config: { process: 'my-process', debounceMs: 1000 } },  // 触发 Process
+      { pattern: 'data:create:modelName', handler: 'log' },        // 记日志
+      { pattern: 'data:update:modelName', handler: 'webhook', config: { url: 'https://...', method?: 'POST', headers?: {} } },  // 推送外部
+      { pattern: 'data:create:modelName', handler: 'notify', config: { type: 'info', title: '标题' } },  // 创建站内通知
+    ],
+    // 声明式（config）与命令式（CLI）两种方式均可绑定事件：
+    // - 声明式：写在 subscriptions 中，重启后自动注册，适合固定不变的订阅
+    // - 命令式：`loom process add --subscribe` 或 `loom event subscribe`，即时生效，适合运行时动态管理
+    // 避免对同一 pattern + process 同时使用两种方式，否则会双重触发
+  },
+});
+```
+
+**多语言（i18n）**：所有面向用户的展示字段均支持 `LocaleString` 格式：`string | Record<string, string>`。
+
+- **简单写法**：`description: '级别'` — 所有语言显示相同文本
+- **多语言写法**：`description: { 'zh-CN': '级别', 'en-US': 'Level' }` — 切换语言时自动翻译
+- **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 路由格式
+
+用Loom创建的项目，后端 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'`
+- **端口冲突（EADDRINUSE）**：启动 `loom dev` 时如果端口已被占用，Node.js 会抛出 `EADDRINUSE` 错误。解决方式：换端口重新执行 `loom init <name> --backend-port <new-port> --frontend-port <new-frontend-port>`。
+- **`loom` 命令报错 "No loom.config.ts found"**：在项目目录下运行命令

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 创建一个告警管理平台，项目名 alert-manager，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 做的 |
+|-------|--------|
+| "帮我记一条告警，服务器CPU过载，当前状态未处理" | 用 `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 Alerts --model alerts --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 alerts --filter '{"level":"critical"}' --limit 10
+loom data write alerts --data '{"level":"critical","description":"CPU使用率超过95%","source":"monitor","status":"open"}'
+loom data update alerts --id rec_xxx --data '{"status":"resolved"}'
+loom data delete alerts --id rec_xxx
+loom data schema alerts    # 查看字段结构
+```
+
+## 后端扩展
+
+需要自定义 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` 启动后端。