@loom-framework/core 0.1.0-alpha.8 → 0.1.0-alpha.80

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@loom-framework/core",
-  "version": "0.1.0-alpha.8",
-  "description": "Loom framework core - DataAdapter, Capability Generator, config system",
+  "version": "0.1.0-alpha.80",
+  "description": "Loom framework - DataAdapter, Capability Generator, config system, backend server, CLI",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -11,24 +11,39 @@
       "types": "./dist/index.d.ts"
     }
   },
+  "bin": {
+    "loom": "dist/bin.js",
+    "core": "dist/bin.js",
+    "loom-server": "dist/server-bin.js"
+  },
   "files": [
-    "dist"
+    "dist",
+    "templates"
   ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "clean": "rm -rf dist",
+    "lint": "tsc --noEmit"
+  },
   "dependencies": {
+    "@fastify/cors": "^10.0.0",
+    "@fastify/static": "^8.0.0",
+    "adm-zip": "^0.5.17",
+    "chalk": "^5.3.0",
+    "commander": "^12.1.0",
+    "fastify": "^5.2.0",
+    "glob": "^11.0.0",
     "jiti": "^2.6.1",
+    "ora": "^8.0.0",
     "zod": "^3.23.0"
   },
   "optionalDependencies": {
     "better-sqlite3": "^12.8.0"
   },
   "devDependencies": {
+    "@types/adm-zip": "^0.5.8",
     "@types/better-sqlite3": "^7.6.13",
     "typescript": "^5.6.0"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "tsc --watch",
-    "clean": "rm -rf dist",
-    "lint": "tsc --noEmit"
   }
-}
+}

package/templates/app-skill/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: {{projectName}}-data
+description: |
+  [阅读 references/models.md 中的数据模型和 AI 按钮定义，编写触发短语。
+  包含：用户语言中的常见增删改查动词、各数据模型相关的操作、AI 按钮的标签。
+  格式："This skill should be used when the user asks to '短语1', '短语2',
+  or any request about <此项目管理的内容> in the {{projectName}} project."]
+version: 1.0.0
+---
+
+# {{projectName}} — App Skill
+
+## Overview
+
+[阅读 references/models.md，用2-3句话描述：项目做什么、管理哪些数据模型、用户如何通过 AI 对话与数据交互。]
+
+## Usage Scenarios
+
+[**必须加载 references/models.md 和 references/data-semantics.md**，这两个文件包含从 loom.config.ts 动态注入的项目特定信息，不加载则无法生成正确内容。
+- models.md — 当前项目的数据模型字段表（字段名、类型、enum 取值、默认值）、AI 按钮定义（id、label、prompt、placement）、CLI 命令语法（read/write/update/delete，不要使用 create/list 等不存在的命令）。
+- data-semantics.md — 当前项目的数据模型名称列表、write 的 --data JSON 构造规则（字段类型格式、enum 取值约束、贴合业务的真实示例值）、read 的 --filter JSON 构造规则（优先用 enum/boolean 字段筛选、跨模型关联查询）。
+再生成8-10个典型用户请求，每个格式：用户说的话 → 对应的 `loom data` CLI 命令。每个数据模型至少包含一个场景。]
+
+## Technical Reference
+
+- 数据模型结构、CLI 语法和操作规范：**references/models.md**
+- 语义引导（示例数据生成、筛选选择、关系推断）：**references/data-semantics.md**

package/templates/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/templates/app-skill/references/models.md

@@ -0,0 +1,31 @@
+# 数据模型与 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 -->
+
+## 操作规范
+
+1. 所有数据操作必须使用 `loom data` CLI 命令，不要直接访问文件或数据库。
+2. 命令在项目根目录下执行。
+3. 执行删除等不可逆操作前，需与用户确认。
+4. 创建/更新时确保必填字段齐全。不确定时用 `loom data schema <model>` 查看。
+5. `update` 只需传入要修改的字段，未指定的字段保持不变。
+6. CLI 输出格式为 JSON — 解析输出以理解数据结构。
+7. 数据变更后，告知用户页面会自动刷新。

package/templates/loom-skill/SKILL.md

@@ -0,0 +1,140 @@
+---
+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 是**配置驱动、自动生成**的框架。工作流程为：
+
+1. **写配置** — 编辑 `loom.config.ts`，定义数据模型和 AI 按钮
+2. **跑命令** — CLI 读取配置，自动生成页面、API 和路由接线
+
+`loom generate page` 会自动生成：CRUD 页面（含 AI 按钮）、App.tsx 路由接线、后端 API + 应用 Skill。
+生成的页面自带 AI 助手浮动按钮，支持流式对话、多会话和数据自动刷新。
+
+技术架构细节见 `references/README.md`。
+
+## 开发流程
+
+**重要：** 始终在项目目录下运行命令（不是 loom monorepo 根目录）。
+
+### 1. 创建项目
+
+```bash
+npx -p @loom-framework/core loom init <name> --description <desc> --adapter <filesystem|sqlite>
+```
+
+### 2. 编辑配置
+
+编辑 `loom.config.ts`，定义数据模型（`data.models`）和 AI 按钮（`aiButtons`），Schema 见下方。高级选项见 `references/data-model.md`。
+
+### 3. 生成页面 + 应用 Skill
+
+```bash
+loom generate page <Name> --model <model-name>
+```
+
+此命令自动生成：CRUD 页面（含 AI 按钮）、App.tsx 路由接线、后端 API、应用 Skill。数据实体立即可通过 `loom data` CLI 和 AI 对话使用。
+
+### 4. 补充应用 Skill 描述（必须）
+
+首次生成后，必须补充 `.claude/skills/<项目名>/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 命令`
+
+### 5. 启动开发
+
+```bash
+loom dev
+```
+
+- 前端：http://localhost:5173
+- 后端：http://localhost:3000
+
+### 迭代：修改配置 → 重新生成
+
+编辑 `loom.config.ts`（添加/修改数据实体或 AI 按钮）→ 重新执行步骤 3。
+
+### 可选：添加更多 Skill
+
+`.claude/skills/` 下的所有 Skill 都会被 AI 自动发现。除了自动生成的应用 Skill，还可以添加新的：
+
+- `loom generate skill <name>` — 创建脚手架，然后编辑 `.claude/skills/<name>/SKILL.md`
+- 或直接复制一个已有的 Skill 目录到 `.claude/skills/` 下
+
+### CLI 命令速查
+
+| 命令 | 说明 |
+|------|------|
+| `loom dev` | 启动开发环境（`--skip-generate` `--backend-only` `--frontend-only`） |
+| `loom build` | 生产构建 |
+| `loom generate page <name> --model <model>` | 生成 CRUD 页面 + 应用 Skill（含 aiButtons 则自动集成） |
+| `loom generate capabilities` | 仅重新生成应用 Skill 的 `references/models.md` |
+| `loom generate skill <name>` | 生成自定义 Skill 脚手架 |
+
+## loom.config.ts Schema（核心）
+
+```typescript
+import { defineConfig } from '@loom-framework/core';
+
+export default defineConfig({
+  project: {
+    name: 'my-app',           // 必填
+    description: '...',',     // 可选
+  },
+  data: {
+    defaultAdapter: 'filesystem',  // 'filesystem' | 'sqlite'
+    models: [{
+      name: 'items',          // 将作为 React 组件名生成页面，字母开头，字母/数字/下划线
+      description: '...',',   // 可选：显示在生成页面中
+      fields: [{
+        name: 'status',       // 字母/下划线开头，字母数字下划线
+        type: 'string',       // 'string' | 'number' | 'boolean' | 'date' | 'string[]' | 'number[]' | 'json'
+        required: true,       // 可选，默认 false
+        description: '...,',  // 可选：显示在表单中
+        default: 'active',    // 可选：写入时自动填充
+        enum: ['active', 'inactive'],  // 可选：限制可选值
+      }],
+    }],
+  },
+  aiButtons: [{               // 可选
+    id: 'summarize',          // 必填：唯一标识
+    label: '总结',             // 必填：按钮文本
+    prompt: '请总结以下内容',    // 必填：支持 {{var}} 引用当前行字段值
+  },
+  {
+    id: 'analyze',            // 带变量的示例
+    label: '分析',
+    prompt: '分析{{questionContent}}，错误答案：{{wrongAnswer}}',
+    placement: 'wrong_questions',  // 可选：限制按钮只出现在指定数据实体的页面，逗号分隔多个实体名；省略则出现在所有页面
+  }],
+});
+```
+
+高级配置（`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`（删除）。
+AI 相关：`POST /api/v1/chat`（SSE 流式对话）、`GET /api/v1/sessions`（会话列表）。
+前端通过 `useData('<model-name>')` 自动访问，无需手动拼接。
+
+**注意：** `sqlite` 适配器在 Node.js ≥ 25 时可能因 `better-sqlite3` 原生模块未编译而报错，改用 `filesystem` 即可。
+
+## 常见问题
+
+- **better-sqlite3 加载失败**：Node.js 版本缺少预编译包。修复：(1) `cd node_modules/better-sqlite3 && npx node-gyp rebuild`，或 (2) 将 `defaultAdapter` 改为 `'filesystem'`
+- **`loom` 命令报错 "No loom.config.ts found"**：在项目目录下运行命令

package/templates/loom-skill/references/README.md

@@ -0,0 +1,128 @@
+# Loom - AI-Native Full-Stack Framework
+
+编织 AI 能力为应用织物
+
+## 快速上手
+
+### 1. 安装 npm 包
+
+Loom 包含两个包：
+
+- `@loom-framework/core` — CLI + 后端（全局安装以使用 `loom` 命令）
+- `@loom-framework/frontend-antd` — 前端组件库（项目运行时依赖，`loom init` 自动添加）
+
+```bash
+npm install -g @loom-framework/core
+```
+
+### 2. 配置 Skill 到 Claude Code
+
+Loom Skill 随 npm 包发布，位于 `templates/loom-skill/` 目录。复制到 Claude Code 的 skill 目录：
+
+```bash
+# 从全局安装复制
+cp -r $(npm root -g)/@loom-framework/core/templates/loom-skill ~/.claude/skills/loom
+
+# 或从项目内复制
+cp -r node_modules/@loom-framework/core/templates/loom-skill ~/.claude/skills/loom
+```
+
+### 3. 打开 Claude Code
+
+启动 Claude Code，Skill 会被自动加载。
+
+### 4. 开始使用
+
+在 Claude Code 中输入以下内容触发 Loom Skill：
+
+### 开始开发
+
+在 Claude Code 中输入以下内容即可触发 Loom Skill：
+
+- "用 loom 开发一个 AI 平台"
+- "创建一个 loom 项目"
+- "为系统添加页面"
+- "配置 AI 按钮"
+
+示例对话：
+
+```
+用户: 用 loom 开发一个笔记管理系统，用 sqlite 存储，
+     需要 AI 总结和翻译功能
+Claude: [读取 SKILL.md] → 运行 loom init → 编辑 config →
+       loom generate page → loom dev
+```
+
+### 开发流程
+
+1. **创建项目**：`npx -p @loom-framework/core loom init <name> --description <desc> --adapter <adapter>`
+2. **编辑配置**：在 `loom.config.ts` 中定义数据模型和 AI 按钮
+3. **生成页面**：`loom generate page <Name> --model <model>`
+4. **启动开发**：`loom dev` → http://localhost:5173
+
+## 核心理念
+
+- **Prompt as Code**: 业务逻辑写在 Skill 的 Markdown 中，而非后端代码
+- **Schema-driven**: 一个数据实体定义 → Skill + CLI 命令 + REST API（自动同步）
+- **Zero Backend Logic**: 后端是透明代理，所有智能在 Skill 中
+
+## 三种交互类型
+
+| 类型 | 说明 | 用户入口 | 自动化程度 |
+|------|------|---------|-----------|
+| AI Chat | 自然语言对话 | AppShell 右下角浮动按钮 | 开箱即用，无需配置 |
+| AI Buttons | 一键 AI 动作 | CRUD 页面操作列的 AI 下拉菜单 | 配置 aiButtons + generate page，自动集成 |
+| CRUD | 结构化数据管理 | 导航菜单页面 | 配置 model + generate page，自动生成 |
+
+## 组件架构
+
+```
+AppShell
+  ├── Layout (Sider + Content)
+  └── AIBubble → ChatDrawer → ChatPanel
+        ├── LoomChatProvider + useXChat
+        ├── MessageContent (thinking / content / tool_call)
+        └── Sender (输入框 + 文件上传)
+
+AIActionButton → AIContext.triggerAI() → ChatDrawer 自动提交
+useData → 监听 loom:data-changed 事件自动刷新
+```
+
+### AI 按钮工作流
+
+1. 点击 AI 按钮 → `AIContext.triggerAI({ query, buttonId, context })`
+2. ChatDrawer 打开并自动提交 prompt
+3. AI 可能通过工具调用进行 CRUD 操作
+4. done 事件触发 `loom:data-changed` → useData 自动 refresh
+
+### 前端组件导出
+
+| 组件/Hook | 说明 |
+|-----------|------|
+| `AppShell` | 应用布局框架，内含 AIBubble |
+| `ChatDrawer` | AI 对话抽屉（多会话、流式、thinking/tool_call） |
+| `AIBubble` | AI 浮动按钮（imperativeHandle: openWithQuery） |
+| `AIActionButton` | AI 动作按钮（通过 AIContext 触发 ChatDrawer） |
+| `AIContext` | AI 上下文（AppShell 提供 triggerAI） |
+| `useData` | 数据 CRUD hook（自动响应 loom:data-changed 事件） |
+
+## 项目结构
+
+```
+my-loom-app/
+├── loom.config.ts                 # 配置源
+├── frontend/src/components/pages/ # 业务页面
+├── backend/src/                   # Fastify + AI 通信
+├── .claude/skills/                # Skills
+├── cli/src/commands/              # CLI 命令扩展
+├── data/                          # 数据存储
+└── .loom/                         # 自动生成（gitignore）
+    └── sessions/                  # AI 会话持久化
+```
+
+## 两个包
+
+| 包 | 说明 |
+|---|---|
+| `@loom-framework/core` | DataAdapter、LoomServer、CLI（loom / loom-server） |
+| `@loom-framework/frontend-antd` | 前端组件库：AppShell、ChatDrawer、AIActionButton、useData、AIContext |

package/templates/loom-skill/references/data-model.md

@@ -0,0 +1,78 @@
+# 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: '...',     // optional: 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
+}
+```
+
+## ModelSchema
+
+```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
+  fields: [...],
+  indexes?: [{ fields: ['userId', 'status'], unique: false }],
+  adapters?: {                  // optional: per-model adapter override
+    filesystem: { dir: 'orders', format: 'json' | 'yaml', datePattern: 'YYYY-MM' },
+    sqlite: { table: 'orders' },
+  },
+}
+```
+
+## AIButtonConfig
+
+```typescript
+aiButtons: [{
+  id: 'summarize',          // required: unique identifier
+  label: '总结',             // required: 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
+}]
+```
+
+## 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
+  },
+}
+```
+
+## ServerConfig
+
+```typescript
+server: {
+  port: 3000,              // default 3000
+  host: '0.0.0.0',
+  cors: true,              // default true
+  staticDir: './dist/frontend',
+}
+```
+
+## DataConfig
+
+```typescript
+data: {
+  defaultAdapter: 'filesystem' | 'sqlite',
+  models: [...],
+  sqlite: { filename: 'data.db' },  // optional, default 'loom.db'
+}
+```