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

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

@@ -0,0 +1,259 @@
+# 生成 Dashboard（数据概览页面）
+
+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: { 'zh-CN': '数据概览', 'en-US': 'Overview' },
+    models: ['items'],
+    layout: [
+      { row: [{ type: 'stat', title: { 'zh-CN': '总数', 'en-US': 'Total' }, model: 'items', aggregate: 'count', span: 6 }] },
+    ],
+  }],
+});
+```
+
+**设计原则：**
+- 统计卡片放第一行（一眼看到关键数字）
+- 分布图表按业务重要性排列
+- 趋势图放最后一行（需要更多空间）
+- 每行不超过 4 个元素
+- 标题用业务语言，不用字段名
+
+### 配置 Schema
+
+```typescript
+{
+  name: 'overview',           // 必填：Dashboard 标识（同模型命名规则）
+  description: { 'zh-CN': '数据概览', 'en-US': 'Overview' },  // 可选：支持多语言
+  models: ['model_a'],        // 必填：关联的数据模型名列表
+  layout: [{                  // 必填：布局定义，数组每项代表一行
+    row: [{                   // 每行包含一组 widget
+      type: 'stat',           // 图表类型，见下方图表类型表
+      title: { 'zh-CN': '总数', 'en-US': 'Total' },  // 支持多语言
+      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: 'source', // 可选：第二分组字段，用于二维图表
+      interval: 'month',      // 可选：date 字段分组粒度 minute|hour|day|week|month（默认 month）
+      dateField: 'createdAt', // 可选：单组件日期筛选字段，覆盖 dashboard 级 defaultDateField
+    }]
+  }]
+}
+```
+
+### 字段说明
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `aggregate` | `count\|sum\|avg\|min\|max\|ratio` | 聚合方式。`ratio` = 符合 filter 条件的记录数/总记录数，用于 gauge/liquid/stat 百分比 |
+| `field` | string | 聚合目标字段。仅 aggregate 为 sum/avg/min/max 时需要 |
+| `filter` | object | 筛选条件，键值对。如 `{isResolved: true}` 筛选已处理的记录 |
+| `groupBy` | string | 主分组字段。string/enum 字段按值分组计数；boolean 字段自动映射为"是/否"；date 字段按 interval 分段 |
+| `crossGroupBy` | string | 第二分组维度。配合 groupBy 使用，产生交叉分组数据，用于二维图表 |
+| `interval` | `minute\|hour\|day\|week\|month` | date 字段的分组粒度，仅 groupBy 指向 date 字段时有效 |
+| `dateField` | string | 单组件日期筛选字段。覆盖 dashboard 级 `defaultDateField`，用于同一个 dashboard 中不同组件需要按不同日期字段筛选的场景 |
+
+### Dashboard 级别配置
+
+除了 `layout` 中的 widget 配置，Dashboard 还支持以下顶级配置：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `defaultDateField` | string | 默认日期字段名。启用后 Dashboard 顶部显示日期范围选择器，选择日期后筛选条件发送到后端（`__range` filter） |
+| `filterDimensions` | `DashboardFilterDimension[]` | 筛选维度定义。支持 `select`（下拉选择）类型；`dateRange` 类型已定义但暂未实现渲染，日期范围筛选请使用 `defaultDateField`。启用后 Dashboard 顶部显示对应的筛选控件，选择的值作为 filter 发送到后端 |
+
+#### DashboardFilterDimension
+
+```typescript
+{
+  field: 'subject',           // 必填：筛选字段名
+  label: { 'zh-CN': '级别' }, // 必填：显示标签，支持多语言
+  type: 'select',             // 必填：当前仅支持 'select'（'dateRange' 已定义但暂未实现）
+  options: ['语文', '数学'],   // 可选：select 类型的选项。省略则从数据中自动提取去重值
+}
+```
+
+**筛选机制：** `select` 筛选器变更后只加载符合条件的数据，清除筛选后恢复加载全量数据。日期范围筛选通过 `defaultDateField` 配置（非 filterDimensions），由 `DashboardFilterBar` 顶部日期选择器控制。
+
+**典型配置：**
+
+```typescript
+dashboards: [{
+  name: 'overview',
+  models: ['alerts'],
+  defaultDateField: 'createdAt',          // 启用日期范围筛选
+  filterDimensions: [                      // 启用 select 下拉筛选（日期范围用 defaultDateField）
+    { field: 'subject', label: { 'zh-CN': '级别', 'en-US': 'Level' }, type: 'select' },
+    { field: 'difficulty', label: { 'zh-CN': '严重度', 'en-US': 'Severity' }, type: 'select' },
+  ],
+  layout: [/* ... */],
+}]
+```
+
+### 图表类型与配置要点
+
+#### 数值类 — 展示关键指标
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `stat` | 统计卡片 | — | `{ aggregate: "count" }` 或 `{ aggregate: "avg", field: "score" }` 或 `{ aggregate: "ratio", filter: { passed: true } }` | Ant Design Statistic 数值卡片 |
+| `gauge` | 仪表盘 | `aggregate: "ratio"` + `filter` | `{ aggregate: "ratio", filter: { isResolved: true } }` | G2 仪表盘（百分比进度） |
+| `liquid` | 水波图 | `aggregate: "ratio"` + `filter` | `{ aggregate: "ratio", filter: { isResolved: true } }` | G2 水波图（百分比进度） |
+
+> **说明**：gauge 和 liquid 使用 `aggregate: "ratio"` + `filter` 来计算百分比（如处理率 = 已处理数/总数），ratio 自动算出 0-1 之间的值。
+
+#### 占比类 — 展示分布构成
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `pie` | 饼图 | `groupBy` (enum/string) | `{ groupBy: "subject" }` | G2 饼图（分布占比） |
+| `ring` | 环形图 | `groupBy` (boolean/enum) | `{ groupBy: "difficulty" }` 或 `{ groupBy: "isResolved" }` | G2 环形图（占比对比，boolean 自动映射"是/否"） |
+| `treemap` | 矩形树图 | `groupBy` + 可选 `crossGroupBy` | `{ groupBy: "subject" }` 或 `{ groupBy: "subject", crossGroupBy: "difficulty" }` | G2 矩形树图（层级占比，有 crossGroupBy 则两层） |
+
+#### 对比类 — 跨类别比较
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `bar` | 条形图 | `groupBy` | `{ groupBy: "source" }` | G2 条形图（横向分类对比） |
+| `stacked_bar` | 堆叠条形图 | `groupBy` + `crossGroupBy` | `{ groupBy: "subject", crossGroupBy: "source" }` | G2 堆叠条形图（组成+对比） |
+| `grouped_bar` | 分组条形图 | `groupBy` + `crossGroupBy` | `{ groupBy: "subject", crossGroupBy: "difficulty" }` | G2 分组条形图（并列对比） |
+| `radar` | 雷达图 | `groupBy` | `{ groupBy: "subject" }` | G2 雷达图（多维度闭合多边形） |
+| `funnel` | 漏斗图 | `groupBy` | `{ groupBy: "source" }` | G2 漏斗图（阶段转化，柱条宽度反映数值） |
+
+#### 趋势类 — 时间维度变化
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `line` | 折线图 | `groupBy` (date 字段) + `interval` | `{ groupBy: "createdAt", interval: "month" }` | G2 折线图（时间趋势） |
+| `area` | 面积图 | `groupBy` (date 字段) + `interval` | `{ groupBy: "createdAt", interval: "month" }` | G2 面积图（累计趋势） |
+
+#### 分布类 — 交叉/密度分析
+
+| type | 中文名称 | 必填字段 | 典型配置 | 生成效果 |
+|------|---------|---------|---------|---------|
+| `scatter` | 散点图 | `groupBy` | `{ groupBy: "subject" }` | G2 散点图（相关性/分布） |
+| `heatmap` | 热力图 | `groupBy` + `crossGroupBy` | `{ groupBy: "subject", crossGroupBy: "source" }` | G2 热力图（密度/交叉分析，颜色深浅表示数量） |
+
+## 执行 generate dashboard
+
+配置好 `dashboards` 字段后，运行命令生成页面：
+
+```bash
+loom generate dashboard <name>
+```
+
+此命令会：
+1. 从 `loom.config.ts` 的 `dashboards` 字段读取配置
+2. 验证引用的模型是否存在
+3. 生成 Dashboard TSX 页面（含 `useData` + `useChartData` + `DashboardChart`）
+4. 自动接线 App.tsx（添加 import、navItem、switch case）
+5. 检测 `@antv/g2` 是否已安装，未安装则自动安装
+
+**前置依赖：** Dashboard 使用 @antv/g2 渲染图表，需在 frontend 目录安装：
+
+```bash
+cd frontend && pnpm add @antv/g2
+```
+
+## 完整配置示例
+
+以告警管理平台为例，展示所有 15 种图表的配置：
+
+```typescript
+import { defineConfig } from '@loom-framework/core';
+
+export default defineConfig({
+  project: { name: 'alert-manager' },
+  data: { /* ... */ },
+  dashboards: [{
+    name: 'overview',
+    description: { 'zh-CN': '告警数据概览', 'en-US': 'Overview' },
+    models: ['alerts', 'alert_handlers'],
+    defaultDateField: 'createdAt',
+    filterDimensions: [
+      { field: 'subject', label: { 'zh-CN': '级别', 'en-US': 'Level' }, type: 'select' },
+      { field: 'difficulty', label: { 'zh-CN': '严重度', 'en-US': 'Severity' }, type: 'select' },
+    ],
+    layout: [
+      {
+        row: [
+          { type: 'stat', title: { 'zh-CN': '告警总数', 'en-US': 'Total Alerts' }, model: 'alerts', aggregate: 'count', span: 4 },
+          { type: 'stat', title: { 'zh-CN': '处理率', 'en-US': 'Resolution Rate' }, model: 'alerts', aggregate: 'ratio', filter: { isResolved: true }, span: 4 },
+          { type: 'gauge', title: { 'zh-CN': '处理率仪表盘', 'en-US': 'Resolution Gauge' }, model: 'alerts', aggregate: 'ratio', filter: { isResolved: true }, span: 6 },
+          { type: 'liquid', title: { 'zh-CN': '处理率水波图', 'en-US': 'Resolution Liquid' }, model: 'alerts', aggregate: 'ratio', filter: { isResolved: true }, span: 5 },
+          { type: 'stat', title: { 'zh-CN': '平均处理时长', 'en-US': 'Avg Resolution Time' }, model: 'alerts', aggregate: 'avg', field: 'resolutionTime', span: 5 }
+        ]
+      },
+      {
+        row: [
+          { type: 'pie', title: { 'zh-CN': '级别分布', 'en-US': 'By Level' }, model: 'alerts', groupBy: 'subject', span: 8 },
+          { type: 'ring', title: { 'zh-CN': '严重度分布', 'en-US': 'By Severity' }, model: 'alerts', groupBy: 'difficulty', span: 8 },
+          { type: 'bar', title: { 'zh-CN': '告警来源分布', 'en-US': 'By Source' }, model: 'alerts', groupBy: 'source', span: 8 }
+        ]
+      },
+      {
+        row: [
+          { type: 'line', title: { 'zh-CN': '告警趋势', 'en-US': 'Alerts Trend' }, model: 'alerts', groupBy: 'createdAt', interval: 'month', span: 12 },
+          { type: 'area', title: { 'zh-CN': '处理记录趋势', 'en-US': 'Handlers Trend' }, model: 'alert_handlers', groupBy: 'createdAt', interval: 'month', span: 12 }
+        ]
+      },
+      {
+        row: [
+          { type: 'radar', title: { 'zh-CN': '各级别概览', 'en-US': 'Level Overview' }, model: 'alerts', groupBy: 'subject', span: 8 },
+          { type: 'stacked_bar', title: { 'zh-CN': '级别×错误类型', 'en-US': 'Level × Error Type' }, model: 'alerts', groupBy: 'subject', crossGroupBy: 'source', span: 8 },
+          { type: 'grouped_bar', title: { 'zh-CN': '级别×严重度', 'en-US': 'Level × Severity' }, model: 'alerts', groupBy: 'subject', crossGroupBy: 'difficulty', span: 8 }
+        ]
+      },
+      {
+        row: [
+          { type: 'scatter', title: { 'zh-CN': '级别分布散点', 'en-US': 'Level Scatter' }, model: 'alerts', groupBy: 'subject', span: 8 },
+          { type: 'funnel', title: { 'zh-CN': '告警来源漏斗', 'en-US': 'Source Funnel' }, model: 'alerts', groupBy: 'source', span: 8 },
+          { type: 'treemap', title: { 'zh-CN': '级别×严重度树图', 'en-US': 'Level × Severity Tree' }, model: 'alerts', groupBy: 'subject', crossGroupBy: 'difficulty', span: 8 }
+        ]
+      },
+      {
+        row: [
+          { type: 'heatmap', title: { 'zh-CN': '级别×年级热力图', 'en-US': 'Level × Grade Heatmap' }, model: 'alerts', groupBy: 'subject', crossGroupBy: 'source', span: 24 }
+        ]
+      }
+    ]
+  }],
+});
+```
+
+## 追加自定义图表
+
+生成后的 Dashboard 页面是普通 TSX，可直接编辑追加图表：
+
+1. 使用 `useChartData` / `useCrossGroupChartData` / `useTreemapChartData` 准备数据
+2. 使用 `/antv-g2-chart` skill 生成 G2 v5 Spec 代码
+3. 添加 `<DashboardChart spec={...} />` 组件
+
+示例——追加一个级别×年级的堆叠柱状图：
+
+```tsx
+// 在已有的 Dashboard 页面中追加
+const levelSourceData = useCrossGroupChartData(alertsList, { groupBy: 'level', crossGroupBy: 'source' });
+
+<DashboardChart spec={{
+  type: 'interval',
+  data: subjectGradeData,
+  encode: { x: 'group', y: 'value', color: 'name' },
+  coordinate: { transform: [{ type: 'transpose' }] },
+  transform: [{ type: 'stackY' }],
+}} />
+```

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

@@ -0,0 +1,306 @@
+# Data Model Reference
+
+Advanced configuration for `loom.config.ts`. Full type definitions from `packages/core/src/types.ts`.
+
+## FieldDefinition
+
+```typescript
+{
+  name: 'status',         // ^[a-zA-Z_][a-zA-Z0-9_]*$
+  type: 'string',         // 'string' | 'number' | 'boolean' | 'date' | 'string[]' | 'number[]' | 'json'
+  required: true,         // optional, default false
+  description: { 'zh-CN': '状态', 'en-US': 'Status' },  // optional: LocaleString, shown in generated forms
+  default: 'active',      // optional: auto-filled on write if not provided
+  enum: ['active', 'inactive', 'archived'],  // optional: restrict string field to allowed values (storage values)
+  enumLabels: {            // optional: display labels per locale for each enum value
+    active: { 'zh-CN': '激活', 'en-US': 'Active' },
+    inactive: { 'zh-CN': '停用', 'en-US': 'Inactive' },
+    archived: { 'zh-CN': '归档', 'en-US': 'Archived' },
+  },
+  dateFormat: 'YYYY-MM-DD HH:mm',  // optional: dayjs format for date fields, default 'YYYY-MM-DD'
+}
+```
+
+### dateFormat (date fields only)
+
+Controls how date fields are displayed and edited in generated CRUD pages. Uses dayjs format strings:
+
+| Format | Display | DatePicker | Use case |
+|--------|---------|------------|----------|
+| `YYYY-MM-DD` (default) | `2025-11-03` | Date only | Birth dates, deadlines |
+| `YYYY-MM-DD HH:mm` | `2025-11-03 14:30` | Date + time picker | Created at, timestamps |
+| `YYYY-MM-DD HH:mm:ss` | `2025-11-03 14:30:00` | Date + time with seconds | Precise timestamps |
+
+Affects: column render, DatePicker format/showTime, save serialization, range filter format.
+
+## ModelSchema
+
+### Recommended Fields
+
+**重要：Loom 框架不会自动注入时间戳字段。** `id` 和 `createdBy`（auth 启用时）是唯一自动注入的字段。以下字段需要手动定义：
+
+- **`createdAt`**（`type: 'date'`, `required: true`）：创建/录入时间。**强烈推荐每个模型都包含此字段**，因为：
+  - Dashboard 的 `defaultDateField` 默认引用 `createdAt` 做日期范围筛选
+  - 趋势图（`line`/`area`）的 `groupBy` 依赖日期字段按时间分组
+  - 如果模型缺少此字段，Dashboard 中依赖该字段的图表和筛选将无法工作
+- **`updatedAt`**（`type: 'date'`）：更新时间。可选，如需追踪最后修改时间则添加
+
+```typescript
+// 推荐在每个模型的 fields 数组开头添加：
+{ name: 'createdAt', type: 'date', required: true, description: { 'zh-CN': '创建时间', 'en-US': 'Created At' }, dateFormat: 'YYYY-MM-DD HH:mm' },
+```
+
+### Definition
+
+```typescript
+{
+  name: 'orders',              // ^[a-zA-Z][a-zA-Z0-9_]*$, will be used as React component name
+  description: { 'zh-CN': '订单记录', 'en-US': 'Order Records' },  // optional: LocaleString, shown in page heading
+  fields: [...],
+  indexes?: [{ fields: ['userId', 'status'], unique: false }],
+  adapters?: {                  // optional: per-model adapter override
+    filesystem: { dir: 'orders', format: 'json' | 'yaml', datePattern: 'YYYY-MM' },  // datePattern: date-partitioned sub-directories using the model's first date field
+    sqlite: { table: 'orders' },
+  },
+  crud?: {                      // optional: control CRUD page features (all default to true when omitted)
+    batch: true,                // optional: enable batch selection and batch delete
+    export: true,               // optional: enable CSV export button
+    import: true,               // optional: enable CSV import button
+    deleteWithUndo: true,       // optional: delete-with-undo instead of confirm dialog; set false to use confirm dialog
+  },
+}
+```
+
+## AIButtonConfig
+
+```typescript
+aiButtons: [{
+  id: 'summarize',          // required: unique identifier
+  label: { 'zh-CN': '总结', 'en-US': 'Summarize' },  // required: LocaleString, button text
+  icon: 'FileTextOutlined', // optional: Ant Design icon component name
+  prompt: '请总结以下内容',   // required: supports {{var}} placeholders, replaced with current row field values
+  placement: 'alerts',  // optional: limit to specific model pages, comma-separated; omit for all pages
+}]
+```
+
+## AIConfig
+
+```typescript
+ai: {
+  engine: 'claude-code',       // default 'claude-code'
+  claudeCode: {
+    path: '/usr/local/bin/claude',  // optional: custom claude binary path
+    pluginRoot: '.claude',          // optional: plugin root directory
+    timeout: 120000,                // optional: command timeout in ms
+    skipPermissions: false,         // optional: skip permission prompts (default: true in headless mode — Claude Code runs without interactive terminal, so permissions are skipped unless explicitly set to false)
+    models: [                       // optional: available AI models
+      {
+        name: 'GLM-5.1',           // required: model name, passed to --model flag
+        authToken: 'sk-xxx',       // optional: ANTHROPIC_AUTH_TOKEN, passed via --settings
+        baseUrl: 'https://api.example.com',  // optional: ANTHROPIC_BASE_URL, passed via --settings
+        isDefault: true,           // optional: default model for new chats
+        tier: "max",
+          tags: [
+            "自然语言"
+          ]
+      },
+    ],
+  },
+}
+```
+
+Models can be managed via the Model Management page (System Settings → Model Management) or by editing `loom.config.ts` directly. On `loom init`, the default model is auto-detected from `~/.claude/settings.json` (ANTHROPIC_MODEL, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL).
+
+## ServerConfig
+
+```typescript
+server: {
+  backendPort: 3000,       // default 3000
+  frontendPort: 5173,      // default 5173
+  host: '127.0.0.1',       // default 127.0.0.1 (local only)
+  cors: true,              // default true
+  staticDir: './dist/frontend',
+}
+```
+
+## DataConfig
+
+```typescript
+data: {
+  defaultAdapter: 'filesystem' | 'sqlite',
+  models: [...],
+  sqlite: { filename: 'loom.db' },  // optional, default 'loom.db'
+}
+```
+
+## UIConfig
+
+```typescript
+ui: {
+  theme: {                       // optional: theme configuration
+    defaultMode: 'light',        // optional: 'light' | 'dark', default 'light'
+    token: { colorPrimary: '#1677ff' },  // optional: Ant Design token overrides
+  },
+  siderCollapsed: false,         // optional: sidebar collapsed by default on desktop
+  showHeader: true,              // optional: show header bar (breadcrumbs + theme toggle)
+  locale: 'zh-CN',              // optional: 'zh-CN' | 'en-US', default 'zh-CN'
+}
+```
+
+## AuthRuntimeConfig
+
+Runtime auth fields are auto-filled by Zod defaults. Usually no manual configuration needed.
+
+```typescript
+auth: {
+  provider: 'builtin',              // Fixed value, always 'builtin'
+  accessTokenTtl: 900,              // Optional: access token TTL in seconds (default: 900 = 15min)
+  refreshTokenTtl: 604800,          // Optional: refresh token TTL in seconds (default: 604800 = 7d)
+}
+```
+
+Note: `provider` and TTL fields are populated by Zod defaults. The `secret` field (required) should use `env:LOOM_JWT_SECRET` format.
+
+## EventsConfig
+
+```typescript
+events: {
+  enabled: true,                    // Optional: enable/disable events (default: true)
+  serverUrl: 'https://...',         // Optional: event service URL for distributed deployment
+  subscriptions: [                  // Optional: declarative event subscriptions
+    { 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: '标题' } },
+    { pattern: 'data:create:modelName', handler: 'process', config: { process: 'my-process', filter?: {} } },
+  ],
+}
+```
+
+Note: 声明式配置在服务启动时自动注册，修改后需重启生效。运行时 CLI/API 管理见 App-Skill（`references/events.md`）。避免对同一 pattern + process 同时使用声明式和命令式绑定，否则会双重触发。
+
+## ProcessesConfig
+
+```typescript
+processes: {
+  enabled: true,                    // Optional: enable/disable process engine (default: true)
+  maxConcurrent: 5,                 // Optional: max concurrent executions, 1-50 (default: 5)
+  defaultOwner: 'admin',            // Required: default owner username
+  executionTimeout: '30m',          // Optional: execution timeout (default: '30m')
+  definitions: [                    // Optional: declarative process definitions (auto-registered on start)
+    {
+      name: 'daily-report',
+      description: 'Daily summary report',
+      cron: '0 9 * * 1-5',
+      prompt: 'Summarize yesterday data and report',
+      owner: 'admin',
+    },
+    {
+      name: 'on-alert',
+      cron: '*/5 * * * *',
+      hasProcessFile: true,          // expects .loom/processes/{name}/PROCESS.md
+      owner: 'admin',
+      model: 'claude-sonnet-4-6',   // AI model for this process
+    },
+  ],
+}
+```
+
+Note: `enabled`, `maxConcurrent`, and `executionTimeout` are populated by Zod defaults. Only `defaultOwner` is typically set manually. Process definitions in `definitions[]` are auto-registered on server start. 运行时 CLI 管理（创建/运行/暂停/日志等）见 App-Skill（`references/process.md`）。
+
+## LifecycleConfig
+
+Global engine parameters for Feeder lifecycle scripts. All Feeder scripts share these parameters. Scripts are registered via `loom process add --source`, not defined in config.
+
+```typescript
+lifecycle: {
+  enabled: true,                    // Optional: enable/disable lifecycle management (default: true)
+  restart: true,                    // Optional: restart on abnormal exit (default: true)
+  maxRestarts: 5,                   // Optional: max restarts within window (default: 5)
+  restartWindowMs: 60000,           // Optional: restart counting window in ms (default: 60000)
+  backoffInitialMs: 1000,           // Optional: initial backoff delay in ms (default: 1000)
+  backoffMaxMs: 30000,              // Optional: max backoff delay in ms (default: 30000)
+  backoffMultiplier: 2.0,           // Optional: backoff multiplier (default: 2.0)
+  memoryLimitMb: 512,               // Optional: memory limit in MB (default: 512)
+  shutdownTimeoutMs: 5000,          // Optional: graceful shutdown timeout in ms (default: 5000)
+}
+```
+
+Note: The `onReady` array has been removed. Use `loom process add --source <command> --subscribe <pattern>` to register Feeder scripts, which are automatically managed by LifecycleManager using these global parameters. Feeder 脚本的事件绑定详情见 App-Skill（`references/events.md`）。
+
+## RelationConfig
+
+```typescript
+relations: [{
+  name: 'question_reviews',            // required: unique relation identifier
+  label: { 'zh-CN': '处理记录', 'en-US': 'Handler Records' },  // optional: LocaleString
+  from: 'alerts',             // required: source model name
+  to: 'alert_handlers',                  // required: target model name
+  foreignKey: 'questionId',            // required: foreign key field in target model
+  type: 'hasMany',                     // required: 'hasOne' | 'hasMany' | 'manyToMany'
+  through: 'enrollments',              // optional: pivot model for manyToMany
+}]
+```
+
+Relations are displayed in the detail drawer of generated CRUD pages. `hasMany` and `manyToMany` relations show as a nested table.
+
+## DashboardConfig
+
+```typescript
+dashboards: [{
+  name: 'overview',           // ^[a-zA-Z][a-zA-Z0-9_]*$, same naming rules as model
+  description: { 'zh-CN': '数据概览', 'en-US': 'Overview' },  // optional: LocaleString, shown in sidebar
+  models: ['items'],          // required: data models included in this dashboard
+  defaultDateField: 'createdAt',  // optional: default date field for date range filtering across all widgets
+  filterDimensions: [             // optional: filter bar dimensions for interactive filtering (select only; use defaultDateField for date range; 'dateRange' type defined but not yet implemented)
+    {
+      field: 'status',            // required: field name to filter on
+      label: { 'zh-CN': '状态', 'en-US': 'Status' },  // required: LocaleString
+      type: 'select',             // required: 'select' ('dateRange' defined but not yet implemented, use defaultDateField instead)
+      options: ['active', 'inactive'],  // optional: for 'select' type, auto-derived from data if omitted
+    },
+  ],
+  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: { 'zh-CN': '任务总数', 'en-US': 'Total Tasks' },  // required: LocaleString, 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: 'minute' | 'hour' | 'day' | 'week' | 'month' for date groupBy
+      dateField: 'createdAt', // optional: per-widget date field override (falls back to dashboard.defaultDateField)
+    }],
+  }],
+}]
+```
+
+## useSchema Runtime API
+
+Generated pages use `useSchema(model)` to fetch model schema and AI buttons at runtime. Schema is auto-resolved by current locale:
+
+```typescript
+const { schema, loading, error } = useSchema('items');
+// schema.fields — field definitions with resolved LocaleString (e.g. description is string, not LocaleString)
+// schema.fields[].enumLabels — resolved to { [enumValue]: displayLabel } for current locale
+// schema.aiButtons — AI buttons filtered by placement, label resolved to current locale
+
+// Convert schema enum to antd formats (uses resolved enumLabels):
+filterOptions(schema, 'status')  // → [{ text: '激活', value: 'active' }, ...]
+selectOptions(schema, 'status')  // → [{ label: '激活', value: 'active' }, ...]
+
+// Get display label for a single enum value:
+enumLabel(schema, 'status', 'active')  // → '激活'
+```
+
+## LocaleString
+
+All user-facing string fields support `LocaleString` format: `string | Record<string, string>`.
+
+- **Simple**: `description: '级别'` — same text for all locales
+- **Multi-locale**: `description: { 'zh-CN': '级别', 'en-US': 'Level' }` — auto-translated on locale switch
+- **Fallback**: requested locale → `'zh-CN'` → first available value
+
+Supported fields: `project.description`, `ModelSchema.description`, `FieldDefinition.description`, `AIButtonConfig.label`, `DashboardConfig.description`, `DashboardWidget.title`, `RelationConfig.label`, `DashboardFilterDimension.label`