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

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

@@ -0,0 +1,294 @@
+# Process CLI Reference
+
+## Overview
+
+Process is Loom's automation engine for scheduling and event-driven AI tasks. Each process has triggers (cron, event, or manual) and executes AI prompts via the Claude Code engine.
+
+## Commands
+
+### `loom process add`
+
+Create a new process definition.
+
+```bash
+# Lightweight process (inline prompt)
+loom process add --name "daily-summary" \
+  --cron "0 9 * * 1-5" \
+  --prompt "Summarize yesterday's data and email the team" \
+  --owner admin
+
+# Full process (with PROCESS.md)
+loom process add --name "weekly-report" \
+  --cron "0 9 * * 1" \
+  --process "weekly-report" \
+  --owner admin \
+  --description "Weekly analytics report"
+
+# Event-triggered process
+loom process add --name "on-task-create" \
+  --on-event "data:create:tasks" \
+  --prompt "Analyze the new task and suggest priorities" \
+  --owner admin \
+  --event-debounce 2000
+
+# With metrics config
+loom process add --name "health-check" \
+  --cron "*/30 * * * *" \
+  --prompt "Check system health" \
+  --metrics-config ./metrics-config.json \
+  --owner bot
+```
+
+**Options:**
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--name` | Yes | Process name (^[a-zA-Z][a-zA-Z0-9_-]*$) |
+| `--prompt` | One of | Inline prompt for lightweight process |
+| `--process` | One of | Full process name (expects .loom/processes/{name}/PROCESS.md) |
+| `--cron` | No | Cron schedule expression |
+| `--cron-timezone` | No | Timezone for cron (e.g., "America/New_York") |
+| `--on-event` | No | EventBus pattern (e.g., "data:create:tasks") |
+| `--event-filter` | No | JSON filter on event payload fields |
+| `--event-debounce` | No | Debounce window in ms (default: 1000) |
+| `--description` | No | Process description |
+| `--owner` | No | Owner username (default: from processes config) |
+| `--owner-token` | No | Direct JWT token (bypasses runtime resolution) |
+| `--metrics-config` | No | Path to metrics DashboardWidget config JSON |
+| `--token` | No | Auth token (or set LOOM_TOKEN) |
+| `--server` | No | Server URL (or set LOOM_SERVER, default: http://localhost:3000) |
+
+### `loom process list`
+
+List all processes.
+
+```bash
+loom process list
+loom process list --status active
+loom process list --status paused
+```
+
+### `loom process status <name>`
+
+Show detailed process status.
+
+```bash
+loom process status daily-summary
+```
+
+### `loom process run <name>`
+
+Manually trigger a process execution.
+
+```bash
+loom process run daily-summary
+loom process run on-task-create --payload '{"model":"tasks","id":"task_123"}'
+```
+
+### `loom process pause <name>`
+
+Pause a process (stops triggers, manual run still works).
+
+```bash
+loom process pause daily-summary
+```
+
+### `loom process resume <name>`
+
+Resume a paused process.
+
+```bash
+loom process resume daily-summary
+```
+
+### `loom process update <name>`
+
+Update an existing process definition.
+
+```bash
+loom process update daily-summary --cron "0 10 * * 1-5"
+loom process update on-task-create --prompt "Updated prompt text"
+loom process update daily-summary --description "Updated description" --cron "0 8 * * 1-5"
+```
+
+**Options:**
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--cron` | No | Update cron schedule expression |
+| `--cron-timezone` | No | Update cron timezone |
+| `--on-event` | No | Update event trigger pattern |
+| `--event-filter` | No | Update event payload filter as JSON |
+| `--event-debounce` | No | Update debounce window in ms |
+| `--prompt` | No | Update inline prompt |
+| `--description` | No | Update description |
+| `--token` | No | Auth token (or set LOOM_TOKEN) |
+| `--server` | No | Server URL (or set LOOM_SERVER, default: http://localhost:3000) |
+
+### `loom process remove <name>`
+
+Remove a process definition. Logs are preserved.
+
+```bash
+loom process remove daily-summary
+```
+
+### `loom process logs <name> [runId]`
+
+View execution logs. When `runId` is provided, shows details for a single run.
+
+```bash
+# List recent logs
+loom process logs daily-summary
+loom process logs daily-summary --limit 50
+loom process logs daily-summary --offset 10
+
+# View a specific run
+loom process logs daily-summary run_abc123
+```
+
+### `loom process generate <name>`
+
+Create PROCESS.md scaffold directory (for full process mode). Called by AI, not directly by users.
+
+```bash
+loom process generate daily-report --description "Daily report generator"
+```
+
+### `loom process metrics-report <name>`
+
+Report a business metric snapshot. Used by AI agent during process execution.
+
+```bash
+# Basic report
+loom process metrics-report my-process --metric-name "成功率" --value 0.95 --unit "%"
+
+# With target and dimensions
+loom process metrics-report my-process \
+  --metric-name "错题重复率" \
+  --value 3 \
+  --unit "条" \
+  --target 0 \
+  --dimensions '{"subject":"数学"}' \
+  --run-id $LOOM_RUN_ID
+```
+
+**Options:**
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--metric-name` | Yes | Human-readable metric name |
+| `--value` | Yes | Numeric metric value |
+| `--run-id` | No | Run ID (defaults to LOOM_RUN_ID env var) |
+| `--timestamp` | No | ISO timestamp (defaults to now) |
+| `--dimensions` | No | Dimension labels as JSON |
+| `--target` | No | Target value for goal-line |
+| `--unit` | No | Unit label (e.g., "%", "条") |
+| `--token` | No | Auth token (or set LOOM_TOKEN) |
+| `--server` | No | Server URL (or set LOOM_SERVER) |
+
+### `loom process metrics-set-view-config <name>`
+
+Set or update the business metrics view configuration. This defines how process metrics are visualized in the Process Management page — each metric gets its own card and optional chart.
+
+**When to use:** After creating a full process with `## Metrics` section, design the view config and write it using this command. See the Process Builder reference for the `ProcessMetricsViewConfig` schema and chart design guidelines.
+
+```bash
+# From JSON string
+loom process metrics-set-view-config my-process --config '{"version":1,"metrics":[{"metricName":"成功率","title":"成功率","chartType":"gauge","direction":"target","target":1,"unit":"%"}],"charts":[]}'
+
+# From file (recommended for complex configs)
+loom process metrics-set-view-config my-process --config @./view-config.json
+```
+
+**ProcessMetricsViewConfig structure:**
+- `version`: Always `1`
+- `metrics[]`: Metric card definitions. Each card shows latest value, trend arrow, and target.
+  - `metricName`: Exact name used in `metrics-report` calls
+  - `title`: Display title
+  - `chartType`: `"gauge"` | `"number"` | `"line"` | `"bar"` | `"area"` — gauge/number only render as cards; line/bar/area also render as independent charts
+  - `direction`: `"increasing"` | `"decreasing"` | `"target"` — controls trend arrow color
+  - `target`: Goal value (shown on card)
+  - `unit`: Unit label (e.g., "%", "条", "次")
+- `charts[]`: G2 v5 chart specs. Each chart MUST include `metricName` for data filtering.
+  - `metricName`: Which metric's snapshots this chart displays
+  - `title`: Chart title
+  - `type`: G2 mark type (`"line"`, `"interval"`, `"area"`, etc.)
+  - `encode`: Field mapping (use `timestamp` for X axis, `value` for Y axis)
+  - Other G2 spec properties: `scale`, `axis`, `transform`, etc.
+
+**Key design rule:** Each chart shows ONE metric only. Never combine different metrics in one chart — they have different units and scales. Use `metricName` to filter data.
+
+**Options:**
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--config` | Yes | View config JSON (use `@file` to read from file) |
+| `--token` | No | Auth token (or set LOOM_TOKEN) |
+| `--server` | No | Server URL (or set LOOM_SERVER) |
+
+### `loom process export <name>`
+
+Export process definition as JSON.
+
+```bash
+loom process export daily-summary
+```
+
+## Process Modes
+
+### Lightweight Mode (`--prompt`)
+
+- Inline prompt, no PROCESS.md file
+- Best for simple, single-task automations
+- Quick to set up and modify
+
+### Full Mode (`--process`)
+
+- Has PROCESS.md at `.loom/processes/{name}/PROCESS.md`
+- Can include reference files in `.loom/processes/{name}/references/`
+- Best for complex, multi-step workflows
+- Supports Metrics and Evolution sections
+
+## Trigger Types
+
+### Cron
+Standard 5-field cron expression: `minute hour day month weekday`
+```
+*/5 * * * *     — Every 5 minutes
+0 9 * * 1-5     — Weekdays at 9 AM
+0 0 1 * *       — First of every month
+```
+
+### Event
+EventBus pattern matching: `{category}:{action}:{target}`
+```
+data:create:tasks       — When a task is created
+data:update:*           — Any data update
+user:created            — When a user is created
+process:completed:xxx   — When process xxx completes
+```
+
+### Manual
+`loom process run <name>` — immediate execution, works even when paused.
+
+## Service Token Authentication
+
+When auth is enabled, processes need a service token to operate:
+- `--owner <username>`: Runtime resolution via UserStore (recommended)
+- `--owner-token <jwt>`: Direct JWT token (less secure, stored in processes/_registry.json)
+
+## Execution Model
+
+1. Trigger fires → entry enqueued
+2. Queue slot available → process starts
+3. AI prompt built (PROCESS.md + references + event context + metrics protocol)
+4. Claude Code engine executes with timeout, env vars injected: LOOM_SERVER, LOOM_PROCESS_NAME, LOOM_RUN_ID
+5. Agent may call `loom process metrics-report` to report business metrics during execution
+6. Result logged to `.loom/processes/{name}/logs/{runId}.json`
+7. Metric snapshots stored in `.loom/processes/{name}/metrics.jsonl`
+8. Event emitted: `process:started`, `process:completed`, or `process:failed`
+
+## Concurrency
+
+Controlled by `processes.maxConcurrent` in loom.config.ts (default: 5). When max is reached, new triggers queue until a slot opens.
+
+## Debounce
+
+Event triggers have `eventDebounceMs` (default: 1000ms). Rapid events within the window are collapsed — only one execution fires with the last event's payload.

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,265 @@
+---
+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. **生成认证页面**：`loom generate system-settings user` — 自动生成用户管理页、登录页，并接入 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` 即可补全。
+
+### 重启服务前必须询问用户
+
+修改 `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\|process>` | 生成系统管理页面（模型管理、技能管理、用户管理或过程管理），首次调用创建子菜单，后续调用追加子页面；`user` 类型同时生成登录页和 AuthProvider 接线 |
+| `loom generate system-settings <model\|skill\|user\|process> --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',                 // 未显式配置的模型默认写权限
+        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"**：在项目目录下运行命令