@loom-framework/core 0.1.0-alpha.15 → 0.1.0-alpha.150

package/builtin-skills/app-skill/references/data-semantics.md

@@ -0,0 +1,44 @@
+# 数据语义引导
+
+> 本文件由 `loom generate capabilities` 自动生成。请勿手动编辑 — 重新生成时将被覆盖。
+
+生成 `loom data` CLI 命令时，阅读 `loom.config.ts` 获取数据模型定义，并遵循以下规则生成贴合业务的输出。
+
+注：本文中的"数据模型"指 loom.config.ts 中定义的数据结构（如 wrong_questions、review_plans），而非大语言模型。
+
+## 示例数据生成
+
+构造 write 命令的 `--data` JSON 时：
+
+- 根据字段名、类型、描述和枚举值生成**贴合业务的真实值**。
+  例如名为 `questionContent`、描述为"题目内容"的字段，应填真实题目如 `"3+5=?"`，而非 `"value"`。
+- 遵守 **FieldType**：`number` → 不加引号的数字（`1`），`boolean` → 不加引号的布尔值（`false`），
+  `date` → ISO 日期字符串（`"2026-01-15"`），`string[]` → JSON 数组（`["标签1"]`），`json` → JSON 对象（`{}`）。
+- 有 **enum** 时必须使用枚举值 — 这是该字段唯一切合法的取值。
+- write 命令只需包含**必填字段**，可选字段可省略。
+- update 命令只需传入**要变更的字段**。
+
+## 筛选条件选择
+
+构造 read 命令的 `--filter` JSON 时：
+
+- **优先使用 enum 和 boolean 字段**做筛选 — 它们能产生最有意义的分区
+  （如 `{"subject": "数学"}`、`{"mastered": false}`）。
+- 选择**业务含义最丰富的筛选条件**，而非按字母序取第一个字段。
+- 可组合多个筛选：`{"subject": "数学", "mastered": false}`。
+- 数据量大时使用 `--limit` 避免输出过多。
+
+## 跨数据模型关联
+
+当字段名以 `Id` 结尾（如 `wrongQuestionId`）时，通常引用的是另一个数据模型的记录。
+
+- 查询关联记录：`loom data read <目标数据模型> --id <值>`。
+- 查询指向某条记录的所有关联：`loom data read <数据模型> --filter '{"<外键字段>": "<id>"}'`。
+- 常见命名模式：`parentId` → 自引用，`<数据模型名>Id` → 引用该数据模型。
+
+<!-- MODEL_NAMES -->
+
+## AI 按钮校验
+
+执行 AI 按钮操作前，验证 prompt 中所有 `{{var}}` 占位符是否对应目标数据模型上的实际字段。
+如果变量引用了不存在的字段，告知用户并建议添加该字段或更新 prompt。

package/builtin-skills/app-skill/references/models.md

@@ -0,0 +1,33 @@
+# 数据模型与 CLI 参考
+
+> 本文件由 `loom generate capabilities` 自动生成。请勿手动编辑 — 重新生成时将被覆盖。
+
+## 数据模型
+
+<!-- DATA_MODELS -->
+
+## CLI 命令
+
+所有数据操作使用 `loom data` CLI 命令，需在项目根目录下执行。
+
+| 命令 | 说明 |
+|------|------|
+| `loom data read <model> [--id <id>] [--filter <json>] [--limit <n>]` | 读取记录 |
+| `loom data write <model> --data '<json>'` | 创建记录 |
+| `loom data update <model> --id <id> --data '<json>'` | 更新记录 |
+| `loom data delete <model> --id <id>` | 删除记录 |
+| `loom data schema [model]` | 查看数据模型结构 |
+
+<!-- AI_BUTTONS -->
+
+<!-- AUTH_ROLES -->
+
+## 操作规范
+
+1. 所有数据操作必须使用 `loom data` CLI 命令，不要直接访问文件或数据库。
+2. 命令在项目根目录下执行。
+3. 执行删除等不可逆操作前，需与用户确认。
+4. 创建/更新时确保必填字段齐全。不确定时用 `loom data schema <model>` 查看。
+5. `update` 只需传入要修改的字段，未指定的字段保持不变。
+6. CLI 输出格式为 JSON — 解析输出以理解数据结构。
+7. 数据变更后，告知用户页面会自动刷新。

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,263 @@
+---
+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 是**配置驱动的 AI 平台开发框架**——你描述需求，AI 通过本 Skill 执行 loom 命令来构建应用。
+
+典型使用方式：
+
+1. **用自然语言描述需求** — 告诉 Claude Code（或其它支持Skill的 Agent） 你要做什么（如"用 loom 开发一个错题管理平台"），Claude Code 会调用本 Skill 读取配置、生成页面、启动服务
+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 助手，支持流式对话和多会话。
+
+完整使用手册见 `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 由 `loom dev` 启动时动态注册。模型立即可通过 `loom data` CLI 和 AI 对话使用。
+
+### 4. 生成并完善应用 Skill
+
+```bash
+loom generate capabilities
+```
+
+此命令读取 `loom.config.ts`，在 `.claude/skills/<项目名>/` 下生成以下文件：
+
+| 文件 | 说明 | 覆盖策略 |
+|------|------|---------|
+| `SKILL.md` | Skill 主文档（含 TODO 模板） | 仅首次创建，不覆盖。若需重建：删除整个 skill 目录后重新执行 |
+| `references/models.md` | 数据模型字段表 + AI 按钮定义 + CLI 语法 | 每次重新生成 |
+| `references/data-semantics.md` | 语义引导（示例数据、筛选规则、跨模型关联） | 每次重新生成 |
+| `references/auth.md` | 认证鉴权命令参考（`--token`/`LOOM_TOKEN` 用法、权限模型） | Auth 启用时每次重新生成 |
+
+每次修改数据模型或 AI 按钮后，重新运行此命令即可更新 `references/` 下的自动生成内容，`SKILL.md` 中手动补充的内容不会被覆盖。
+
+首次生成后，需要补充 `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/` 下
+
+### 5. 生成 Dashboard（数据概览）
+
+Dashboard 配置在 `loom.config.ts` 的 `dashboards` 字段中定义。设计原则和配置 Schema 详见 `references/dashboard.md`。
+
+```bash
+loom generate dashboard <name>
+```
+
+此命令从 `loom.config.ts` 的 `dashboards` 字段读取配置，自动生成 Dashboard 页面并接线 App.tsx。
+
+### 5.5 启用认证鉴权（可选）
+
+当用户需要多用户支持、权限控制时，帮助用户在 `loom.config.ts` 中添加 `auth` 配置：
+
+1. **询问需求**：是否需要登录功能？有哪些角色？每个角色能做什么？
+2. **编辑配置**：在 `loom.config.ts` 中添加 `auth` 字段（Schema 见上方）。至少定义一个 `admin` 角色
+3. **设置密钥**：`secret` 推荐 `env:JWT_SECRET`，不要硬编码。提醒用户设置环境变量 `export JWT_SECRET=your-secret`
+4. **重启后端**：auth 配置需要重启后端生效（**必须先询问用户**）
+5. **首次登录**：默认创建 admin 用户（密码 `admin123`），**提醒用户立即修改密码**
+6. **生成 app-skill**：`loom generate capabilities` 更新 Skill 中的 auth.md
+
+启用后自动获得：登录页 + 路由守卫 + RBAC 权限控制 + 用户管理页 + CLI `--token`/`LOOM_TOKEN` 鉴权。
+
+### 重启服务前必须询问用户
+
+修改 `loom.config.ts` 后如果需要重启后端服务（如增删 AI 按钮、修改 enum 值、新增模型等场景），**必须先询问用户是否可以重启**，得到确认后再执行 `loom dev` 或停止/重启服务。不要自动重启，因为用户可能正在使用页面或调试中。
+
+### 6. 启动开发
+
+```bash
+loom dev
+```
+
+- 前端：http://localhost:5173
+- 后端：http://localhost:3000
+
+### 迭代：修改配置后的处理
+
+不同类型的配置变更，处理方式不同：
+
+| 变更类型 | 需要改页面吗 | 怎么做 |
+|---------|------------|--------|
+| 增删 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/<时间戳>/` 目录，如需恢复直接复制回来即可。
+
+**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` | 启动开发环境（`--backend-only` `--frontend-only`） |
+| `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 <model\|skill\|user>` | 生成系统管理页面（模型管理、技能管理或用户管理），首次调用创建子菜单，后续调用追加子页面 |
+| `loom generate system-settings <model\|skill\|user> --force` | 重建系统管理页面（自动备份旧文件到 `.loom/backup/`） |
+| `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 }] }],
+  }],
+  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',                 // 未显式配置的模型默认写权限
+        readIncludesAiButtons: false,   // read 权限是否可见 AI 按钮
+        writeExcludesDelete: false,     // write 权限是否排除删除操作
+      },
+    },
+  },
+});
+```
+
+### 多语言（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"**：在项目目录下运行命令