@loom-framework/core 0.1.0-alpha.45 → 0.1.0-alpha.46

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/dist/cli/commands/init.js +2 -2
  2. package/package.json +1 -1
  3. package/templates/skill/SKILL.md +56 -45
  4. package/templates/skill/references/README.md +91 -82
package/dist/cli/commands/init.js CHANGED
@@ -167,8 +167,8 @@ async function createPackageJson(targetDir, options) {
167
167
  generate: 'loom generate capabilities',
168
168
  },
169
169
  dependencies: {
170
- '@loom-framework/core': '^0.1.0-alpha.45',
171
- '@loom-framework/frontend-antd': '^0.1.0-alpha.45',
170
+ '@loom-framework/core': '^0.1.0-alpha.46',
171
+ '@loom-framework/frontend-antd': '^0.1.0-alpha.46',
172
172
  'fastify': '^5.2.0',
173
173
  '@ant-design/x': '^2.5.0',
174
174
  '@ant-design/x-sdk': '^2.5.0',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@loom-framework/core",
3
- "version": "0.1.0-alpha.45",
3
+ "version": "0.1.0-alpha.46",
4
4
  "description": "Loom framework - DataAdapter, Capability Generator, config system, backend server, CLI",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
package/templates/skill/SKILL.md CHANGED
@@ -7,85 +7,96 @@ description: |
7
7
  version: 0.1.0
8
8
  ---
9
9
 
10
- # Loom - AI-Native Framework Skill
10
+ # Loom - AI 原生全栈框架技能
11
11
 
12
- ## Quick Start
12
+ ## 框架工作方式
13
13
 
14
- 1. Confirm project scope: name, description, data models, AI buttons
15
- 2. Create project:
14
+ Loom 是**配置驱动、自动生成**的框架。工作流程为：
15
+
16
+ 1. **写配置** — 编辑 `loom.config.ts`，定义数据模型和 AI 按钮
17
+ 2. **跑命令** — CLI 读取配置，自动生成页面、API 和路由接线
18
+
19
+ `loom generate page` 会自动生成：CRUD 页面（含 AI 按钮）、App.tsx 路由接线、后端 API + MCP Tool。
20
+ 生成的页面自带 AI 助手浮动按钮，支持流式对话、多会话和数据自动刷新。
21
+
22
+ 技术架构细节见 `references/README.md`。
23
+
24
+ ## 快速开始
25
+
26
+ 1. 创建项目：
16
27
  `npx -p @loom-framework/core loom init <name> --description <desc> --adapter <filesystem|sqlite>`
17
- 3. Define data models and AI buttons in `loom.config.ts` (see Schema below)
18
- 4. Generate pages: `loom generate page <Name> --model <model>`
19
- 5. Start dev: `loom dev` → http://localhost:5173 (frontend), http://localhost:3000 (backend)
28
+ 2. 编辑 `loom.config.ts` — 定义数据模型和 AI 按钮（见下方 Schema）
29
+ 3. 生成页面：`loom generate page <Name> --model <model>`
30
+ 4. 启动开发：`loom dev` → http://localhost:5173 (前端), http://localhost:3000 (后端)
20
31
 
21
- **Important:** Always run commands from the project directory (not the loom monorepo root).
32
+ **重要：** 始终在项目目录下运行命令（不是 loom monorepo 根目录）。
22
33
 
23
- ## Core CLI Commands
34
+ ## 核心 CLI 命令
24
35
 
25
- - `loom dev` - Start dev environment (hot-reload)
36
+ - `loom dev` - 启动开发环境（热更新）
26
37
  - `--skip-generate`, `--backend-only`, `--frontend-only`
27
- - `loom build` - Build for production
28
- - `loom generate capabilities` - Generate MCP Server + CLI from config
29
- - `loom generate page <name> --model <model>` - Generate CRUD page (includes AI buttons if configured)
30
- - `loom generate skill <name>` - Generate skill scaffold
38
+ - `loom build` - 生产构建
39
+ - `loom generate capabilities` - 根据 config 生成 MCP Server + CLI
40
+ - `loom generate page <name> --model <model>` - 生成 CRUD 页面（若配置了 aiButtons 则自动集成）
41
+ - `loom generate skill <name>` - 生成 Skill 脚手架
31
42
 
32
- ## Detailed Workflows
43
+ ## 详细工作流
33
44
 
34
- ### Adding a New Data Model
45
+ ### 添加数据模型
35
46
 
36
- 1. Edit `loom.config.ts` → add model definition (see Schema below; for advanced options see `references/data-model.md`)
37
- 2. Run `loom generate page <Name> --model <model-name>`
38
- 3. Model is immediately available via MCP Tools and `loom data` CLI
47
+ 1. 编辑 `loom.config.ts` → 添加模型定义（见下方 Schema；高级选项见 `references/data-model.md`）
48
+ 2. 运行 `loom generate page <Name> --model <model-name>`
49
+ 3. 模型立即可通过 MCP Tool 和 `loom data` CLI 使用
39
50
 
40
- ### Adding an AI Button
51
+ ### 添加 AI 按钮
41
52
 
42
- 1. Edit `loom.config.ts` → add entry to `aiButtons` array (top-level, not inside `ai`)
43
- 2. Run `loom generate page <Name> --model <model-name>` — AI buttons are automatically integrated into the page
53
+ 1. 编辑 `loom.config.ts` → 在 `aiButtons` 数组中添加条目（顶层，不在 `ai` 内部）
54
+ 2. 运行 `loom generate page <Name> --model <model-name>` — AI 按钮自动集成到页面
44
55
 
45
- ### Adding a New Skill
56
+ ### 添加 Skill
46
57
 
47
- 1. Create scaffold: `loom generate skill <name>`
48
- 2. Edit `.claude/skills/<name>/SKILL.md` (see `references/skill-development.md` for format)
49
- 3. Add reference prompts in `.claude/skills/<name>/references/`
58
+ 1. 创建脚手架：`loom generate skill <name>`
59
+ 2. 编辑 `.claude/skills/<name>/SKILL.md`（格式见 `references/skill-development.md`）
60
+ 3. 在 `.claude/skills/<name>/references/` 中添加参考 prompt
50
61
 
51
- ## loom.config.ts Schema (Core)
62
+ ## loom.config.ts Schema（核心）
52
63
 
53
64
  ```typescript
54
65
  import { defineConfig } from '@loom-framework/core';
55
66
 
56
67
  export default defineConfig({
57
68
  project: {
58
- name: 'my-app', // required
59
- description: '...',', // optional
69
+ name: 'my-app', // 必填
70
+ description: '...',', // 可选
60
71
  },
61
72
  data: {
62
73
  defaultAdapter: 'filesystem', // 'filesystem' | 'sqlite'
63
74
  models: [{
64
- name: 'items', // lowercase, hyphens/underscores allowed
65
- description: '...',', // optional: shown in generated pages
75
+ name: 'items', // 小写，允许连字符/下划线
76
+ description: '...',', // 可选：显示在生成页面中
66
77
  fields: [{
67
- name: 'status', // alphanumeric + underscore, start with letter/underscore
78
+ name: 'status', // 字母/下划线开头，字母数字下划线
68
79
  type: 'string', // 'string' | 'number' | 'boolean' | 'date' | 'string[]' | 'number[]' | 'json'
69
- required: true, // optional, default false
70
- description: '...,', // optional: shown in forms
71
- default: 'active', // optional: auto-filled on write
72
- enum: ['active', 'inactive'], // optional: restrict values
80
+ required: true, // 可选，默认 false
81
+ description: '...,', // 可选：显示在表单中
82
+ default: 'active', // 可选：写入时自动填充
83
+ enum: ['active', 'inactive'], // 可选：限制可选值
73
84
  }],
74
85
  }],
75
86
  },
76
- aiButtons: [{ // optional
77
- id: 'summarize', // required: unique identifier
78
- label: '总结', // required: button text
79
- prompt: '请总结以下内容', // required (or promptTemplate)
87
+ aiButtons: [{ // 可选
88
+ id: 'summarize', // 必填：唯一标识
89
+ label: '总结', // 必填：按钮文本
90
+ prompt: '请总结以下内容', // 必填（或用 promptTemplate）
80
91
  }],
81
92
  });
82
93
  ```
83
94
 
84
- For advanced config (`ai.claudeCode`, `server`, per-model `adapters`, `indexes`, `aiButtons.promptTemplate/contextVars`), see `references/data-model.md`.
95
+ 高级配置（`ai.claudeCode`、`server`、按模型 `adapters`、`indexes`、`aiButtons.promptTemplate/contextVars`）见 `references/data-model.md`。
85
96
 
86
- ## Troubleshooting
97
+ ## 常见问题
87
98
 
88
- - **`loom` commands fail "No loom.config.ts found"**: Run commands from the project directory, not the loom monorepo root
89
- - **loom init fails**: Use `npx -p @loom-framework/core loom init <name> --description <desc> --adapter <filesystem|sqlite>`
99
+ - **`loom` 命令报错 "No loom.config.ts found"**：在项目目录下运行命令，不是 loom monorepo 根目录
100
+ - **loom init 失败**：使用 `npx -p @loom-framework/core loom init <name> --description <desc> --adapter <filesystem|sqlite>`
90
101
 
91
- See `references/troubleshooting.md` for more issues.
102
+ 更多问题见 `references/troubleshooting.md`。
package/templates/skill/references/README.md CHANGED
@@ -2,6 +2,64 @@
2
2
 
3
3
  编织 AI 能力为应用织物
4
4
 
5
+ ## 快速上手
6
+
7
+ ### 1. 安装 npm 包
8
+
9
+ Loom 包含两个包：
10
+
11
+ - `@loom-framework/core` — CLI + 后端（全局安装以使用 `loom` 命令）
12
+ - `@loom-framework/frontend-antd` — 前端组件库（项目运行时依赖，`loom init` 自动添加）
13
+
14
+ ```bash
15
+ npm install -g @loom-framework/core
16
+ ```
17
+
18
+ ### 2. 配置 Skill 到 Claude Code
19
+
20
+ Loom Skill 随 npm 包发布，位于 `templates/skill/` 目录。复制到 Claude Code 的 skill 目录：
21
+
22
+ ```bash
23
+ # 从全局安装复制
24
+ cp -r $(npm root -g)/@loom-framework/core/templates/skill ~/.claude/skills/loom
25
+
26
+ # 或从项目内复制
27
+ cp -r node_modules/@loom-framework/core/templates/skill ~/.claude/skills/loom
28
+ ```
29
+
30
+ ### 3. 打开 Claude Code
31
+
32
+ 启动 Claude Code，Skill 会被自动加载。
33
+
34
+ ### 4. 开始使用
35
+
36
+ 在 Claude Code 中输入以下内容触发 Loom Skill：
37
+
38
+ ### 开始开发
39
+
40
+ 在 Claude Code 中输入以下内容即可触发 Loom Skill：
41
+
42
+ - "用 loom 开发一个 AI 平台"
43
+ - "创建一个 loom 项目"
44
+ - "为系统添加页面"
45
+ - "配置 AI 按钮"
46
+
47
+ 示例对话：
48
+
49
+ ```
50
+ 用户: 用 loom 开发一个笔记管理系统，用 sqlite 存储，
51
+ 需要 AI 总结和翻译功能
52
+ Claude: [读取 SKILL.md] → 运行 loom init → 编辑 config →
53
+ loom generate page → loom dev
54
+ ```
55
+
56
+ ### 开发流程
57
+
58
+ 1. **创建项目**：`npx -p @loom-framework/core loom init <name> --description <desc> --adapter <adapter>`
59
+ 2. **编辑配置**：在 `loom.config.ts` 中定义数据模型和 AI 按钮
60
+ 3. **生成页面**：`loom generate page <Name> --model <model>`
61
+ 4. **启动开发**：`loom dev` → http://localhost:5173
62
+
5
63
  ## 核心理念
6
64
 
7
65
  - **Prompt as Code**: 业务逻辑写在 Skill 的 Markdown 中，而非后端代码
@@ -10,111 +68,62 @@
10
68
 
11
69
  ## 三种交互类型
12
70
 
13
- | 类型 | 说明 | 实现方式 |
14
- |------|------|---------|
15
- | AI Chat | 自然语言对话 | HTTP SSE 流式，Claude Code 引擎 |
16
- | AI Buttons | 一键 AI 动作 | 预定义 Prompt，`aiButtons` 配置；点击后打开 ChatDrawer 自动提交 |
17
- | CRUD | 结构化数据管理 | REST API，Schema 驱动自动生成 |
71
+ | 类型 | 说明 | 用户入口 | 自动化程度 |
72
+ |------|------|---------|-----------|
73
+ | AI Chat | 自然语言对话 | AppShell 右下角浮动按钮 | 开箱即用，无需配置 |
74
+ | AI Buttons | 一键 AI 动作 | CRUD 页面操作列的 AI 下拉菜单 | 配置 aiButtons + generate page，自动集成 |
75
+ | CRUD | 结构化数据管理 | 导航菜单页面 | 配置 model + generate page，自动生成 |
18
76
 
19
77
  ## 组件架构
20
78
 
21
79
  ```
22
- AppShell（应用布局，自动包含 AI 入口）
80
+ AppShell
23
81
  ├── Layout (Sider + Content)
24
- └── AIBubble（浮动 AI 助手按钮）
25
- └── ChatDrawer（AI 对话抽屉）
26
- └── ChatPanel（聊天面板，SSE 流式通信）
27
- ├── LoomChatProvider + useXChat
28
- ├── MessageContent（thinking/content/tool_call 渲染）
29
- └── Sender（输入框 + 文件上传）
30
-
31
- AIActionButton（触发 AI 动作）
32
- → 通过 AIContext.triggerAI() 打开 ChatDrawer 并自动提交 prompt
33
-
34
- useData（数据 CRUD hook）
35
- → 监听 loom:data-changed 事件，AI 通过工具修改数据后自动刷新
82
+ └── AIBubble → ChatDrawer → ChatPanel
83
+ ├── LoomChatProvider + useXChat
84
+ ├── MessageContent (thinking / content / tool_call)
85
+ └── Sender (输入框 + 文件上传)
86
+
87
+ AIActionButton → AIContext.triggerAI() → ChatDrawer 自动提交
88
+ useData → 监听 loom:data-changed 事件自动刷新
36
89
  ```
37
90
 
38
91
  ### AI 按钮工作流
39
92
 
40
- 1. 用户点击 AI 按钮（表格操作列的 Dropdown 菜单项）
41
- 2. AIActionButton 调用 `AIContext.triggerAI({ query, buttonId, context })`
42
- 3. AIBubble 收到请求 → 打开 ChatDrawer → 设置 pendingRequest
43
- 4. ChatPanel 收到 pendingQuery → 自动提交给后端
44
- 5. 后端 AI 处理，可能通过工具调用进行 CRUD 操作
45
- 6. ChatPanel done 事件 → 触发 `loom:data-changed` 自定义事件
46
- 7. useData hook 监听事件 → 自动 refresh 刷新页面数据
93
+ 1. 点击 AI 按钮 → `AIContext.triggerAI({ query, buttonId, context })`
94
+ 2. ChatDrawer 打开并自动提交 prompt
95
+ 3. AI 可能通过工具调用进行 CRUD 操作
96
+ 4. done 事件触发 `loom:data-changed` → useData 自动 refresh
47
97
 
48
98
  ### 前端组件导出
49
99
 
50
100
  | 组件/Hook | 说明 |
51
101
  |-----------|------|
52
- | `AppShell` | 应用布局框架（含 AI 浮动入口） |
53
- | `ChatDrawer` | AI 对话抽屉 |
54
- | `AIBubble` | AI 浮动按钮（AppShell 已内置，无需单独使用） |
102
+ | `AppShell` | 应用布局框架，内含 AIBubble |
103
+ | `ChatDrawer` | AI 对话抽屉（多会话、流式、thinking/tool_call） |
104
+ | `AIBubble` | AI 浮动按钮（imperativeHandle: openWithQuery） |
55
105
  | `AIActionButton` | AI 动作按钮（通过 AIContext 触发 ChatDrawer） |
56
- | `AIContext` | AI 上下文（AppShell 提供，子组件可调用 triggerAI） |
57
- | `useData` | 数据 CRUD hook（自动响应 AI 数据变更） |
106
+ | `AIContext` | AI 上下文（AppShell 提供 triggerAI） |
107
+ | `useData` | 数据 CRUD hook（自动响应 loom:data-changed 事件） |
58
108
 
59
109
  ## 项目结构
60
110
 
61
111
  ```
62
112
  my-loom-app/
63
- ├── loom.config.ts # 唯一配置源（模型、AI 按钮、服务器配置）
64
- ├── frontend/ # React + TypeScript + Vite
65
- │ └── src/components/pages/ # 业务页面（CRUD + AI 按钮）
66
- ├── backend/src/ # Fastify + AI 通信（LoomServer）
67
- ├── .claude/skills/ # Skills（Prompt as Code）
68
- ├── cli/src/commands/ # CLI 业务命令扩展
69
- ├── data/ # 数据存储（DataAdapter 管理）
70
- └── .loom/ # 自动生成（gitignore）
71
- ├── mcp-server/ # MCP Server（自动生成）
72
- └── mcp.json # MCP 配置
113
+ ├── loom.config.ts # 配置源
114
+ ├── frontend/src/components/pages/ # 业务页面
115
+ ├── backend/src/ # Fastify + AI 通信
116
+ ├── .claude/skills/ # Skills
117
+ ├── cli/src/commands/ # CLI 命令扩展
118
+ ├── data/ # 数据存储
119
+ └── .loom/ # 自动生成（gitignore）
120
+ ├── mcp-server/ # MCP Server
121
+ └── mcp.json # MCP 配置
73
122
  ```
74
123
 
75
124
  ## 两个包
76
125
 
77
126
  | 包 | 说明 |
78
127
  |---|---|
79
- | `@loom-framework/core` | 运行时 + 开发时：DataAdapter、LoomServer、CLI（loom / loom-server） |
80
- | `@loom-framework/frontend-antd` | 前端组件库：AppShell、ChatDrawer、AIActionButton、useData、AIContext |
81
-
82
- ## CLI 命令速查
83
-
84
- ### 项目初始化
85
-
86
- | 命令 | 说明 |
87
- |------|------|
88
- | `npx -p @loom-framework/core loom init <name> -d <desc> -a <adapter>` | 创建新项目 |
89
-
90
- ### 开发
91
-
92
- | 命令 | 说明 |
93
- |------|------|
94
- | `loom dev` | 启动开发环境（前端 + 后端，热更新） |
95
- | `loom build` | 生产构建 |
96
-
97
- ### 生成
98
-
99
- | 命令 | 说明 |
100
- |------|------|
101
- | `loom generate page <Name> --model <model>` | 生成 CRUD 页面（含 AI 按钮，若配置了 aiButtons） |
102
- | `loom generate skill <name>` | 生成 Skill 脚手架 |
103
- | `loom generate capabilities` | 重新生成 MCP Server + CLI |
104
-
105
- ### 数据
106
-
107
- | 命令 | 说明 |
108
- |------|------|
109
- | `loom data read <model>` | 读取记录 |
110
- | `loom data write <model> --data '<json>'` | 写入记录 |
111
- | `loom data schema [model]` | 查看模型定义 |
112
-
113
- ### 其他
114
-
115
- | 命令 | 说明 |
116
- |------|------|
117
- | `loom skill list` | 列出所有 Skill |
118
- | `loom skill validate [name]` | 校验 Skill 结构 |
119
- | `loom observe logs` | 查看 AI 交互日志 |
120
- | `loom observe metrics` | 查看聚合指标 |
128
+ | `@loom-framework/core` | DataAdapter、LoomServer、CLI（loom / loom-server） |
129
+ | `@loom-framework/frontend-antd` | 前端组件库：AppShell、ChatDrawer、AIActionButton、useData、AIContext |