@loom-framework/core 0.1.0-alpha.5 → 0.1.0-alpha.50

package/templates/skill/references/README.md

@@ -0,0 +1,129 @@
+# 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/skill/` 目录。复制到 Claude Code 的 skill 目录：
+
+```bash
+# 从全局安装复制
+cp -r $(npm root -g)/@loom-framework/core/templates/skill ~/.claude/skills/loom
+
+# 或从项目内复制
+cp -r node_modules/@loom-framework/core/templates/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**: 一个模型定义 → MCP Tool + 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）
+    ├── mcp-server/                # MCP Server
+    └── mcp.json                   # MCP 配置
+```
+
+## 两个包
+
+| 包 | 说明 |
+|---|---|
+| `@loom-framework/core` | DataAdapter、LoomServer、CLI（loom / loom-server） |
+| `@loom-framework/frontend-antd` | 前端组件库：AppShell、ChatDrawer、AIActionButton、useData、AIContext |

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

@@ -0,0 +1,101 @@
+# Data Model Reference
+
+Advanced configuration for `loom.config.ts` data models. Load this when defining complex models.
+
+## Full Field Options
+
+```typescript
+{
+  name: 'status',         // must match ^[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 to allowed values
+}
+```
+
+## Model-Level Options
+
+```typescript
+{
+  name: 'orders',
+  description: 'Order records',  // shown in generated page heading
+  fields: [...],
+  indexes: [                     // optional: database indexes
+    { fields: ['userId', 'status'], unique: false },
+  ],
+  adapters: {                    // optional: per-model adapter override
+    filesystem: { dir: 'orders', format: 'json' | 'yaml', datePattern: 'yyyy-MM-dd' },
+    sqlite: { table: 'orders' },
+  },
+},
+```
+
+## AI Configuration
+
+```typescript
+ai: {
+  engine: 'claude-code',           // default 'claude-code'
+  claudeCode: {
+    path: '/usr/local/bin/claude', // custom claude binary path
+    pluginRoot: '.claude',         // plugin root directory
+    timeout: 120000,               // command timeout in ms
+    skipPermissions: false,        // skip permission prompts
+    defaultModel: 'claude-sonnet-4-6',
+  },
+},
+```
+
+## Server Configuration
+
+```typescript
+server: {
+  port: 3000,              // default 3000
+  host: '0.0.0.0',
+  cors: true,              // default true
+  staticDir: './dist/frontend',
+},
+```
+
+## SQLite Configuration
+
+```typescript
+data: {
+  defaultAdapter: 'sqlite',
+  sqlite: { filename: 'data.db' },  // default 'loom.db'
+}
+```
+
+## AI Buttons (Full Options)
+
+```typescript
+aiButtons: [{
+  id: 'summarize',               // required: unique identifier
+  label: '总结',                  // required: button text
+  icon: 'FileTextOutlined',      // optional: Ant Design icon name
+  prompt: '请总结以下内容',         // required: prompt text, supports {{var}} placeholders
+                                 // {{var}} is replaced with the current row's field value at runtime
+  placement: 'page-header',      // optional: UI placement hint
+},
+{
+  id: 'analyze',                 // example with template variables
+  label: '分析',
+  prompt: '分析{{questionContent}}，错误答案：{{wrongAnswer}}',
+}],
+```
+
+### AI Button Behavior
+
+When configured, AI buttons are automatically integrated into CRUD page action columns:
+
+1. Each table row shows an "AI" dropdown button with all configured buttons as menu items
+2. Clicking a button opens the ChatDrawer and sends `buttonId` + row `context` to the server
+3. Server resolves `prompt` with `{{fieldName}}` replaced by the current row's field values
+4. Context fields not referenced in the template are automatically appended to the prompt
+5. If AI performs CRUD via tool calls, the page auto-refreshes (via `loom:data-changed` event)
+
+## Data Access in Skills
+
+- **Prefer MCP Tools** for data CRUD: `read_<model>`, `write_<model>`, `update_<model>`, `delete_<model>`
+- Use `loom data read/write <model>` CLI only for debugging

package/templates/skill/references/skill-development.md

@@ -0,0 +1,46 @@
+# Skill Development Reference
+
+Guide for creating and managing Loom Skills. Load this when adding or editing `.claude/skills/`.
+
+## Skill Structure
+
+```
+.claude/skills/<skill-name>/
+├── SKILL.md          # Required: trigger conditions + workflow
+└── references/       # Optional: detailed rules and reference docs
+    └── *.md
+```
+
+## SKILL.md Format
+
+```markdown
+---
+name: <skill-name>
+description: |
+  This skill should be used when the user asks to "<trigger phrases>".
+  Include both English and Chinese trigger phrases.
+version: 1.0.0
+---
+
+# <Skill Name>
+
+<Description of what this skill does>
+
+## Workflow
+
+1. <Step 1>
+2. <Step 2>
+
+## Rules
+
+- <Rule 1>
+- <Rule 2>
+```
+
+## Best Practices
+
+- Keep SKILL.md focused on one capability domain
+- Use `references/` for detailed rules that would clutter the main SKILL.md
+- Specify which MCP Tools (`read_<model>`, `write_<model>`) the skill should use
+- Skills define behavior through prompts, not code generation
+- Run `loom skill validate [name]` to check SKILL.md structure

package/templates/skill/references/troubleshooting.md

@@ -0,0 +1,42 @@
+# Troubleshooting Guide
+
+Common issues when creating and running Loom projects.
+
+## `loom generate` Fails: Cannot find module '@loom-framework/core'
+
+Dependencies not installed. Run `npm install` from the project directory.
+
+## `npx @loom-framework/core loom init` Fails
+
+The `npx` command cannot find the executable. Use the `-p` flag to specify the package:
+```bash
+npx -p @loom-framework/core loom init <name> --description <desc> --adapter <adapter>
+```
+
+## `loom dev` Port Already in Use (EADDRINUSE)
+
+Previous process still running. Kill it: `lsof -ti:3000 | xargs kill -9`
+
+## Commands Fail: "No loom.config.ts found"
+
+Running from the wrong directory. `cd` into the project directory before running `loom` commands.
+
+## Model Name Validation Error
+
+Model names must match `^[a-z][a-z0-9_-]*$` (lowercase, hyphens/underscores allowed).
+Field names must match `^[a-zA-Z_][a-zA-Z0-9_]*$`.
+
+## `loom build` Backend TSC Fails: Cannot use JSX
+
+Root `tsconfig.json` includes `frontend/` with `.tsx` files.
+Add `"frontend"` to `exclude` in root `tsconfig.json`:
+```json
+{ "exclude": ["node_modules", "dist", "frontend"] }
+```
+Frontend has its own `frontend/tsconfig.json` with `jsx: "react-jsx"`.
+
+## Debug Tips
+
+- `loom data schema <model>` — inspect model fields
+- `loom observe logs` — view AI interaction logs
+- `loom skill validate` — check skill structure