@loom-framework/core 0.1.0-alpha.101 → 0.1.0-alpha.102

package/builtin-skills/loom/SKILL.md

@@ -143,50 +143,67 @@ import { defineConfig } from '@loom-framework/core';
 export default defineConfig({
   project: {
     name: 'my-app',           // 必填
-    description: '...',',     // 可选
+    description: { 'zh-CN': '我的应用', 'en-US': 'My App' },  // 可选，支持多语言
   },
   data: {
     defaultAdapter: 'filesystem',  // 'filesystem' | 'sqlite'
     models: [{
       name: 'items',          // 将作为 React 组件名生成页面，字母开头，字母/数字/下划线
-      description: '...',',   // 可选：显示在生成页面中
+      description: { 'zh-CN': '数据项', 'en-US': 'Items' },   // 可选：支持多语言
       fields: [{
         name: 'status',       // 字母/下划线开头，字母数字下划线
         type: 'string',       // 'string' | 'number' | 'boolean' | 'date' | 'string[]' | 'number[]' | 'json'
         required: true,       // 可选，默认 false
-        description: '...,',  // 可选：显示在表单中
+        description: { 'zh-CN': '状态', 'en-US': 'Status' },  // 可选：支持多语言
         default: 'active',    // 可选：写入时自动填充
-        enum: ['active', 'inactive'],  // 可选：限制可选值
+        enum: ['active', 'inactive'],  // 可选：限制可选值（存储值，不随语言变化）
+        enumLabels: {                   // 可选：enum 值的多语言显示标签
+          active: { 'zh-CN': '激活', 'en-US': 'Active' },
+          inactive: { 'zh-CN': '停用', 'en-US': 'Inactive' },
+        },
       }],
     }],
   },
   aiButtons: [{               // 可选
     id: 'summarize',          // 必填：唯一标识
-    label: '总结',             // 必填：按钮文本
+    label: { 'zh-CN': '总结', 'en-US': 'Summarize' },  // 必填：支持多语言
     prompt: '请总结以下内容',    // 必填：支持 {{var}} 引用当前行字段值
   },
   {
     id: 'analyze',            // 带变量的示例
-    label: '分析',
+    label: { 'zh-CN': '分析', 'en-US': 'Analyze' },
     prompt: '分析{{questionContent}}，错误答案：{{wrongAnswer}}',
     placement: 'wrong_questions',  // 可选：限制按钮只出现在指定模型页面，逗号分隔多个模型名；省略则出现在所有页面
   }],
   dashboards: [{              // 可选：Dashboard 定义
     name: 'overview',         // 必填：唯一标识，同命名规则
-    description: '数据概览',    // 可选
+    description: { 'zh-CN': '数据概览', 'en-US': 'Overview' },  // 可选
     models: ['items'],        // 必填：关联的数据模型
-    layout: [{ row: [{ type: 'stat', title: '总数', model: 'items', aggregate: 'count', span: 6 }] }],
+    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 按钮定义，`filterOptions(schema, fieldName)` 和 `selectOptions(schema, fieldName)` 将 enum 值转为 antd 组件格式。
+前端通过 `useData('<model-name>')` 自动访问，无需手动拼接。`useSchema('<model-name>')` 获取模型字段和 AI 按钮定义，自动根据当前 locale 请求服务端 resolved 数据。`filterOptions(schema, fieldName)` 和 `selectOptions(schema, fieldName)` 将 enum 值转为 antd 组件格式（使用 resolved 的 enumLabels）。`enumLabel(schema, fieldName, value)` 获取单个 enum 值的显示标签。
 
 ## 常见问题
 

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

@@ -14,10 +14,10 @@ export default defineConfig({
   data: { /* ... */ },
   dashboards: [{
     name: 'overview',
-    description: '数据概览',
+    description: { 'zh-CN': '数据概览', 'en-US': 'Overview' },
     models: ['items'],
     layout: [
-      { row: [{ type: 'stat', title: '总数', model: 'items', aggregate: 'count', span: 6 }] },
+      { row: [{ type: 'stat', title: { 'zh-CN': '总数', 'en-US': 'Total' }, model: 'items', aggregate: 'count', span: 6 }] },
     ],
   }],
 });
@@ -35,12 +35,12 @@ export default defineConfig({
 ```typescript
 {
   name: 'overview',           // 必填：Dashboard 标识（同模型命名规则）
-  description: '数据概览',     // 可选：侧边栏展示名
+  description: { 'zh-CN': '数据概览', 'en-US': 'Overview' },  // 可选：支持多语言
   models: ['model_a'],        // 必填：关联的数据模型名列表
   layout: [{                  // 必填：布局定义，数组每项代表一行
     row: [{                   // 每行包含一组 widget
       type: 'stat',           // 图表类型，见下方图表类型表
-      title: '总数',          // 业务语言标题
+      title: { 'zh-CN': '总数', 'en-US': 'Total' },  // 支持多语言
       model: 'model_a',      // 数据模型名
       span: 6,               // 可选：Col 宽度（1-24），省略则自动均分
       aggregate: 'count',    // 可选：count|sum|avg|min|max|ratio（默认 count）
@@ -142,48 +142,48 @@ export default defineConfig({
   data: { /* ... */ },
   dashboards: [{
     name: 'overview',
-    description: '错题数据概览',
+    description: { 'zh-CN': '错题数据概览', 'en-US': 'Overview' },
     models: ['wrong_questions', 'review_plans'],
     layout: [
       {
         row: [
-          { type: 'stat', title: '错题总数', model: 'wrong_questions', aggregate: 'count', span: 4 },
-          { type: 'stat', title: '掌握率', model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 4 },
-          { type: 'gauge', title: '掌握率仪表盘', model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 6 },
-          { type: 'liquid', title: '掌握率水波图', model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 5 },
-          { type: 'stat', title: '平均复习次数', model: 'wrong_questions', aggregate: 'avg', field: 'reviewCount', span: 5 }
+          { type: 'stat', title: { 'zh-CN': '错题总数', 'en-US': 'Total Questions' }, model: 'wrong_questions', aggregate: 'count', span: 4 },
+          { type: 'stat', title: { 'zh-CN': '掌握率', 'en-US': 'Mastery Rate' }, model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 4 },
+          { type: 'gauge', title: { 'zh-CN': '掌握率仪表盘', 'en-US': 'Mastery Gauge' }, model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 6 },
+          { type: 'liquid', title: { 'zh-CN': '掌握率水波图', 'en-US': 'Mastery Liquid' }, model: 'wrong_questions', aggregate: 'ratio', filter: { isMastered: true }, span: 5 },
+          { type: 'stat', title: { 'zh-CN': '平均复习次数', 'en-US': 'Avg Reviews' }, model: 'wrong_questions', aggregate: 'avg', field: 'reviewCount', span: 5 }
         ]
       },
       {
         row: [
-          { type: 'pie', title: '科目分布', model: 'wrong_questions', groupBy: 'subject', span: 8 },
-          { type: 'ring', title: '难度分布', model: 'wrong_questions', groupBy: 'difficulty', span: 8 },
-          { type: 'bar', title: '错误类型分布', model: 'wrong_questions', groupBy: 'errorType', span: 8 }
+          { type: 'pie', title: { 'zh-CN': '科目分布', 'en-US': 'By Subject' }, model: 'wrong_questions', groupBy: 'subject', span: 8 },
+          { type: 'ring', title: { 'zh-CN': '难度分布', 'en-US': 'By Difficulty' }, model: 'wrong_questions', groupBy: 'difficulty', span: 8 },
+          { type: 'bar', title: { 'zh-CN': '错误类型分布', 'en-US': 'By Error Type' }, model: 'wrong_questions', groupBy: 'errorType', span: 8 }
         ]
       },
       {
         row: [
-          { type: 'line', title: '错题录入趋势', model: 'wrong_questions', groupBy: 'createdAt', interval: 'month', span: 12 },
-          { type: 'area', title: '复习计划趋势', model: 'review_plans', groupBy: 'createdAt', interval: 'month', span: 12 }
+          { type: 'line', title: { 'zh-CN': '错题录入趋势', 'en-US': 'Questions Trend' }, model: 'wrong_questions', groupBy: 'createdAt', interval: 'month', span: 12 },
+          { type: 'area', title: { 'zh-CN': '复习计划趋势', 'en-US': 'Review Plans Trend' }, model: 'review_plans', groupBy: 'createdAt', interval: 'month', span: 12 }
         ]
       },
       {
         row: [
-          { type: 'radar', title: '各科目概览', model: 'wrong_questions', groupBy: 'subject', span: 8 },
-          { type: 'stacked_bar', title: '科目×错误类型', model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'errorType', span: 8 },
-          { type: 'grouped_bar', title: '科目×难度', model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'difficulty', span: 8 }
+          { type: 'radar', title: { 'zh-CN': '各科目概览', 'en-US': 'Subject Overview' }, model: 'wrong_questions', groupBy: 'subject', span: 8 },
+          { type: 'stacked_bar', title: { 'zh-CN': '科目×错误类型', 'en-US': 'Subject × Error Type' }, model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'errorType', span: 8 },
+          { type: 'grouped_bar', title: { 'zh-CN': '科目×难度', 'en-US': 'Subject × Difficulty' }, model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'difficulty', span: 8 }
         ]
       },
       {
         row: [
-          { type: 'scatter', title: '科目分布散点', model: 'wrong_questions', groupBy: 'subject', span: 8 },
-          { type: 'funnel', title: '错误类型漏斗', model: 'wrong_questions', groupBy: 'errorType', span: 8 },
-          { type: 'treemap', title: '科目×难度树图', model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'difficulty', span: 8 }
+          { type: 'scatter', title: { 'zh-CN': '科目分布散点', 'en-US': 'Subject Scatter' }, model: 'wrong_questions', groupBy: 'subject', span: 8 },
+          { type: 'funnel', title: { 'zh-CN': '错误类型漏斗', 'en-US': 'Error Type Funnel' }, model: 'wrong_questions', groupBy: 'errorType', span: 8 },
+          { type: 'treemap', title: { 'zh-CN': '科目×难度树图', 'en-US': 'Subject × Difficulty Tree' }, model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'difficulty', span: 8 }
         ]
       },
       {
         row: [
-          { type: 'heatmap', title: '科目×年级热力图', model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'grade', span: 24 }
+          { type: 'heatmap', title: { 'zh-CN': '科目×年级热力图', 'en-US': 'Subject × Grade Heatmap' }, model: 'wrong_questions', groupBy: 'subject', crossGroupBy: 'grade', span: 24 }
         ]
       }
     ]

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

@@ -9,9 +9,14 @@ Advanced configuration for `loom.config.ts`. Full type definitions from `package
   name: 'status',         // ^[a-zA-Z_][a-zA-Z0-9_]*$
   type: 'string',         // 'string' | 'number' | 'boolean' | 'date' | 'string[]' | 'number[]' | 'json'
   required: true,         // optional, default false
-  description: '...',     // optional: shown in generated forms
+  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
+  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' },
+  },
 }
 ```
 
@@ -20,7 +25,7 @@ Advanced configuration for `loom.config.ts`. Full type definitions from `package
 ```typescript
 {
   name: 'orders',              // ^[a-zA-Z][a-zA-Z0-9_]*$, will be used as React component name
-  description: 'Order records', // optional: shown in generated page heading
+  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
@@ -35,7 +40,7 @@ Advanced configuration for `loom.config.ts`. Full type definitions from `package
 ```typescript
 aiButtons: [{
   id: 'summarize',          // required: unique identifier
-  label: '总结',             // required: button text
+  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: 'wrong_questions',  // optional: limit to specific model pages, comma-separated; omit for all pages
@@ -82,12 +87,12 @@ data: {
 ```typescript
 dashboards: [{
   name: 'overview',           // ^[a-zA-Z][a-zA-Z0-9_]*$, same naming rules as model
-  description: '数据概览',     // optional: shown in sidebar navigation
+  description: { 'zh-CN': '数据概览', 'en-US': 'Overview' },  // optional: LocaleString, shown in sidebar
   models: ['items'],          // required: data models included in this dashboard
   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: '任务总数',       // required: display title
+      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
@@ -103,14 +108,28 @@ dashboards: [{
 
 ## useSchema Runtime API
 
-Generated pages use `useSchema(model)` to fetch model schema and AI buttons at runtime:
+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 enum values
-// schema.aiButtons — AI buttons filtered by placement
+// 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': 'Subject' }` — auto-translated on locale switch
+- **Fallback**: requested locale → `'zh-CN'` → first available value
 
-// Convert schema enum to antd formats:
-filterOptions(schema, 'status')  // → [{ text: 'active', value: 'active' }, ...]
-selectOptions(schema, 'status')  // → [{ label: 'active', value: 'active' }, ...]
-```
+Supported fields: `project.description`, `ModelSchema.description`, `FieldDefinition.description`, `AIButtonConfig.label`, `DashboardConfig.description`, `DashboardWidget.title`, `RelationConfig.label`

package/dist/cli/templates/frontend-entry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"frontend-entry.d.ts","sourceRoot":"","sources":["../../../src/cli/templates/frontend-entry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,aAAa,IAAI,MAAM,CAWtC;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CAyD1E;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CAc7E"}
+{"version":3,"file":"frontend-entry.d.ts","sourceRoot":"","sources":["../../../src/cli/templates/frontend-entry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,4BAA4B;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,aAAa,IAAI,MAAM,CAWtC;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CAiE1E;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,4BAA4B,GAAG,MAAM,CAc7E"}

package/dist/cli/templates/frontend-entry.js

@@ -15,7 +15,7 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
 }
 export function createAppTsx(options) {
     return `import React, { useState } from 'react';
-import { AppShell, useLoomTheme, useLocale, registerMessages } from '@loom-framework/frontend-antd';
+import { AppShell, useLocale, registerMessages, LoomConfigProvider } from '@loom-framework/frontend-antd';
 import type { BreadcrumbItem } from '@loom-framework/frontend-antd';
 
 // Register i18n keys for nav items and breadcrumbs
@@ -28,7 +28,7 @@ registerMessages('en-US', {
   'nav.skill-management': 'Skill Management',
 });
 
-export default function App() {
+function AppContent() {
   const [selectedKey, setSelectedKey] = useState('');
   const { t } = useLocale();
 
@@ -48,7 +48,7 @@ export default function App() {
       default:
         return (
           <div style={{ padding: 24 }}>
-            <h2>${options.name}</h2>
+            <h2>{t('nav.home')}</h2>
             <p>${options.description || 'A Loom application.'}</p>
             <p>运行 <code>loom generate page &lt;Name&gt; --model &lt;model&gt;</code> 生成页面。</p>
           </div>
@@ -69,6 +69,14 @@ export default function App() {
     </AppShell>
   );
 }
+
+export default function App() {
+  return (
+    <LoomConfigProvider>
+      <AppContent />
+    </LoomConfigProvider>
+  );
+}
 `;
 }
 export function createIndexHtml(options) {

package/dist/cli/templates/frontend-entry.js.map

@@ -1 +1 @@
-{"version":3,"file":"frontend-entry.js","sourceRoot":"","sources":["../../../src/cli/templates/frontend-entry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,MAAM,UAAU,aAAa;IAC3B,OAAO;;;;;;;;;CASR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAqC;IAChE,OAAO;;;;;;iBAMQ,OAAO,CAAC,IAAI;;;;iBAIZ,OAAO,CAAC,IAAI;;;;;;;;;;;;;;;;;;;;;;;;kBAwBX,OAAO,CAAC,IAAI;iBACb,OAAO,CAAC,WAAW,IAAI,qBAAqB;;;;;;;;;eAS9C,OAAO,CAAC,IAAI;;;;;;;;;;;CAW1B,CAAC;AACF,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAqC;IACnE,OAAO;;;;;aAKI,OAAO,CAAC,IAAI;;;;;;;CAOxB,CAAC;AACF,CAAC"}
+{"version":3,"file":"frontend-entry.js","sourceRoot":"","sources":["../../../src/cli/templates/frontend-entry.ts"],"names":[],"mappings":"AAAA;;GAEG;AAOH,MAAM,UAAU,aAAa;IAC3B,OAAO;;;;;;;;;CASR,CAAC;AACF,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAqC;IAChE,OAAO;;;;;;iBAMQ,OAAO,CAAC,IAAI;;;;iBAIZ,OAAO,CAAC,IAAI;;;;;;;;;;;;;;;;;;;;;;;;;iBAyBZ,OAAO,CAAC,WAAW,IAAI,qBAAqB;;;;;;;;;eAS9C,OAAO,CAAC,IAAI;;;;;;;;;;;;;;;;;;;CAmB1B,CAAC;AACF,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAAqC;IACnE,OAAO;;;;;aAKI,OAAO,CAAC,IAAI;;;;;;;CAOxB,CAAC;AACF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@loom-framework/core",
-  "version": "0.1.0-alpha.101",
+  "version": "0.1.0-alpha.102",
   "description": "Loom framework - DataAdapter, Capability Generator, config system, backend server, CLI",
   "type": "module",
   "main": "./dist/index.js",