@loom-framework/core 0.1.0-alpha.18 → 0.1.0-alpha.180

package/builtin-skills/app-skill/references/auth.md

@@ -0,0 +1,180 @@
+# Auth Commands Reference
+
+## Authentication Commands
+
+### Login
+```bash
+loom auth login -u <username> -p <password>
+loom auth login  # interactive prompt
+```
+
+### Register (admin token required)
+```bash
+loom auth register -u <username> -p <password> [--role <role>] --token <admin-jwt>
+```
+
+### Logout
+```bash
+loom auth logout --refresh-token <token> --token <jwt>
+```
+
+### Whoami
+```bash
+loom auth whoami --token <jwt>
+```
+
+## User Management (Admin Only)
+
+### Add User
+```bash
+loom user add <username> -p <password> -r <role> --token <admin-jwt>
+```
+
+### List Users
+```bash
+loom user list --token <jwt>
+```
+
+### Update User
+```bash
+loom user update <id> -r <role> --token <jwt>
+loom user update <id> -p <newpassword> --token <jwt>
+```
+
+### Delete User
+```bash
+loom user delete <id> --token <admin-jwt>
+```
+
+### Change Role
+```bash
+loom user role <id> <role> --token <admin-jwt>
+```
+
+## Role Management
+
+### List Roles
+```bash
+loom role list [--token <jwt>]
+```
+Note: `role list` does not require authentication (the endpoint is public).
+
+### Create Role (admin required)
+```bash
+loom role create <name> -p '[{"model":"*","level":"read"}]' --token <admin-jwt>
+```
+
+### Update Role (admin required)
+```bash
+loom role update <name> -n <new-name> --token <admin-jwt>
+loom role update <name> -p '[{"model":"items","level":"write"}]' --token <admin-jwt>
+```
+
+### Delete Role (admin required)
+```bash
+loom role delete <name> --token <admin-jwt>
+```
+Cannot delete a role that still has assigned users.
+
+### Permission Levels
+```bash
+loom role permissions
+```
+
+## Data Commands with Auth
+
+When auth is enabled, data commands route through HTTP API and require token:
+
+```bash
+loom data read <model> --token <jwt>
+loom data write <model> --data '<json>' --token <jwt>
+loom data update <model> --id <id> --data '<json>' --token <jwt>
+loom data delete <model> --id <id> --token <jwt>
+loom data schema <model> --token <jwt>
+```
+
+## Automatic Token Injection
+
+In Web chat and Process execution scenarios, `LOOM_TOKEN` is automatically injected into the environment — `--token` is not needed:
+
+| Scenario | Token Source | Need --token? |
+|----------|-------------|---------------|
+| Web chat (ChatDrawer → Claude Code) | Framework injects user's JWT as `LOOM_TOKEN` env var when spawning `claude -p` | No |
+| Process automation (cron/event) | Framework injects owner's JWT as `LOOM_TOKEN` env var | No (use `$LOOM_TOKEN` shell variable reference in prompts) |
+| Local terminal `loom` commands | No automatic injection | Yes |
+
+Priority: `--token` flag > `LOOM_TOKEN` env var. The `--token` flag acts as a fallback/override — safe to always include, but redundant in Web/Process contexts.
+
+## Permission Model
+
+### Levels (hierarchical)
+| Level | Access |
+|-------|--------|
+| `none` | No access |
+| `read` | GET (read-only) |
+| `write` | GET, POST, PUT |
+| `admin` | GET, POST, PUT, DELETE |
+
+### Configuration in loom.config.ts
+```typescript
+auth: {
+  provider: 'builtin',
+  secret: 'env:JWT_SECRET',  // or plain string (not recommended)
+  roles: [
+    { role: 'admin', permissions: [{ model: '*', level: 'admin' }] },
+    { role: 'editor', permissions: [{ model: 'items', level: 'write' }] },
+    { role: 'viewer', permissions: [{ model: '*', level: 'read' }] },
+  ],
+  permissions: {
+    defaults: {
+      read: 'read',
+      write: 'write',
+      writeExcludesDelete: false,     // writer can delete?
+    },
+  },
+}
+```
+
+### Wildcard Permissions
+Use `model: '*'` to apply a permission level to all models.
+Explicit model permissions override wildcards.
+
+### Default Admin User
+When auth is first enabled, a default admin user is created:
+- Username: `admin`
+- Password: `admin123`
+- **Change this immediately after first login!**
+
+### Service Token
+Each user gets a service token at registration time (long-lived JWT, 30-day TTL).
+Returned in the API response when creating a user — the admin should save it securely.
+Used by Process automation to execute as the user.
+
+## API Endpoints
+
+| Method | Path | Auth | Description |
+|--------|------|------|-------------|
+| POST | /api/v1/auth/login | No | Login |
+| POST | /api/v1/auth/register | Admin | Register new user |
+| POST | /api/v1/auth/logout | Yes | Logout |
+| POST | /api/v1/auth/refresh | No* | Refresh token |
+| GET | /api/v1/auth/whoami | Yes | Current user |
+| GET | /api/v1/auth/roles | No | List roles |
+| POST | /api/v1/auth/roles | Admin | Create role |
+| PUT | /api/v1/auth/roles/:role | Admin | Update role |
+| DELETE | /api/v1/auth/roles/:role | Admin | Delete role |
+| GET | /api/v1/auth/users | Admin | List users |
+| POST | /api/v1/auth/users | Admin | Create user |
+| GET | /api/v1/auth/users/:id | Self/Admin | Get user |
+| PUT | /api/v1/auth/users/:id | Self/Admin | Update user |
+| DELETE | /api/v1/auth/users/:id | Admin | Delete user |
+
+*Refresh requires valid refresh token in store
+
+## Audit Fields
+
+When auth is enabled, write operations automatically inject:
+- `createdBy` — username of the user who created the record (POST)
+- `updatedBy` — username of the user who last updated the record (PUT)
+
+These fields are optional and don't affect existing data.

package/builtin-skills/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/builtin-skills/app-skill/references/events.md

@@ -0,0 +1,119 @@
+# 事件系统参考
+
+Loom 事件系统在数据变更和系统操作时自动触发事件，可用于通知、审计和自动化。
+
+## 事件模式格式
+
+事件使用 `category:action:target` 三段式模式：
+
+| 段 | 说明 | 示例 |
+|----|------|------|
+| category | 事件类别 | `data`, `user`, `skill`, `ai`, `session`, `file` |
+| action | 操作类型 | `create`, `update`, `delete`, `login`, `logout` |
+| target | 操作对象 | 模型名、`models`、技能名等 |
+
+## 通配符订阅
+
+| 通配符 | 匹配规则 | 示例 |
+|--------|----------|------|
+| `*` | 单段匹配 | `data:*:tasks` 匹配 `data:create:tasks`、`data:update:tasks` |
+| `**` | 任意深度匹配 | `data:**` 匹配所有 data 类事件 |
+
+## 数据事件（EventEmittingAdapter 自动触发）
+
+这些事件由 DataAdapter 操作自动触发，无需手动代码：
+
+| 事件模式 | 触发时机 | Payload 字段 |
+|----------|----------|-------------|
+| `data:create:<model>` | 创建记录 | model, id, data |
+| `data:update:<model>` | 更新记录 | model, id, data, previousData, changedFields |
+| `data:delete:<model>` | 删除记录 | model, id, previousData |
+| `data:import:<model>` | CSV 导入完成 | model, imported, errors |
+| `data:batch_delete:<model>` | 批量删除完成 | model, count, errors |
+
+## 认证事件
+
+| 事件模式 | 触发时机 | Payload 字段 |
+|----------|----------|-------------|
+| `user:login` | 用户登录 | userId, username, role |
+| `user:logout` | 用户登出 | userId |
+| `user:created` | 创建用户 | userId, username, role |
+| `user:updated` | 更新用户 | userId, username, role |
+| `user:deleted` | 删除用户 | userId |
+
+## 技能管理事件
+
+| 事件模式 | 触发时机 | Payload 字段 |
+|----------|----------|-------------|
+| `skill:created` | 创建技能 | skillName |
+| `skill:deleted` | 删除技能 | skillName |
+| `skill:file_updated` | 更新技能文件 | skillName, filename, path |
+
+## AI 配置事件
+
+| 事件模式 | 触发时机 | Payload 字段 |
+|----------|----------|-------------|
+| `ai:models_updated` | 模型列表更新 | count |
+
+## 会话事件
+
+| 事件模式 | 触发时机 | Payload 字段 |
+|----------|----------|-------------|
+| `session:created` | 创建会话 | sessionId |
+| `session:deleted` | 删除会话 | sessionId |
+| `session:truncated` | 截断会话消息 | sessionId, fromIndex |
+
+## 文件上传事件
+
+| 事件模式 | 触发时机 | Payload 字段 |
+|----------|----------|-------------|
+| `file:uploaded` | 文件上传成功 | filename, sessionId, path, size |
+
+## 配置声明式订阅
+
+在 `loom.config.ts` 中声明事件处理器：
+
+```typescript
+export default defineConfig({
+  // ...
+  events: {
+    subscriptions: [
+      {
+        pattern: 'data:create:orders',
+        handler: 'webhook',
+        config: { url: 'https://example.com/webhook' },
+      },
+      {
+        pattern: 'user:login',
+        handler: 'log',
+        config: { level: 'info' },
+      },
+    ],
+  },
+});
+```
+
+## 事件 API
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/api/v1/events/notify` | POST | 外部事件注入（CLI 使用） |
+| `/api/v1/events/patterns` | GET | 查看已注册的事件模式 |
+
+### POST /api/v1/events/notify
+
+```json
+{
+  "pattern": "data:create:tasks",
+  "payload": { "model": "tasks", "id": "rec_123" },
+  "source": "cli"
+}
+```
+
+## 订阅可用处理器
+
+| handler | 说明 | config 字段 |
+|---------|------|------------|
+| `log` | 写入服务器日志 | `level`: info/debug/warn |
+| `webhook` | 发送 HTTP 请求 | `url`, `method`, `headers` |
+| `process` | 启动进程（未来） | `process`, `filter` |

package/builtin-skills/app-skill/references/evolution.md

@@ -0,0 +1,90 @@
+# Process Evolution Guide
+
+## Overview
+
+Process Evolution is the practice of iteratively improving automated processes based on execution results. Loom provides the tooling (logs, metrics) for AI to analyze and optimize processes over time.
+
+## How Evolution Works
+
+1. **Monitor**: Review execution logs and metrics
+2. **Analyze**: Identify patterns, failures, and optimization opportunities
+3. **Decide**: Determine what to change (prompt, trigger, references)
+4. **Apply**: Update the process definition or PROCESS.md
+5. **Verify**: Monitor subsequent runs for improvement
+
+## Reading Metrics
+
+```bash
+# Check recent logs
+loom process logs <name> --limit 20
+
+# View process status
+loom process status <name>
+```
+
+### Key Indicators
+
+| Metric | Good | Needs Improvement |
+|--------|------|-------------------|
+| Success rate | > 95% | < 80% |
+| Avg duration | Stable or decreasing | Increasing trend |
+| Timeout rate | 0% | > 5% |
+| Error patterns | Unique errors | Repeated same error |
+
+## Evolution Strategies
+
+### Prompt Optimization
+
+If a process frequently fails or produces low-quality results:
+
+1. Read the current prompt: `loom process export <name>`
+2. Analyze failure patterns in logs
+3. Make the prompt more specific:
+   - Add constraints ("Output must be JSON")
+   - Add examples ("Here's a good output: ...")
+   - Add error handling instructions
+4. Update: `loom process export <name>` → edit → API update
+
+### Trigger Adjustment
+
+If a process runs too often or too rarely:
+
+- Adjust cron frequency
+- Add `--event-debounce` for bursty events
+- Add `--event-filter` for selective triggering
+
+```bash
+# Increase debounce for bursty events
+loom process update <name> --event-debounce 5000
+
+# Add filter to only trigger on specific conditions
+loom process update <name> --event-filter '{"status":"urgent"}'
+```
+
+### Reference Updates
+
+For full processes, update reference files:
+- Outdated API docs → replace with current
+- Missing context → add new reference files
+- Unnecessary references → remove to reduce prompt size
+
+## Safety Constraints
+
+Evolution is limited to these safe operations:
+- **Notify**: Send alerts via events
+- **Data write**: Create/update records via `loom data` CLI
+- **Process update**: Modify process definitions via CLI
+
+Evolution MUST NOT:
+- Delete data without explicit user approval
+- Modify other processes without user consent
+- Change authentication or authorization settings
+- Execute shell commands outside the sandbox
+
+## Monitoring Checklist
+
+After applying evolution changes:
+1. Run manually: `loom process run <name>`
+2. Check result: `loom process logs <name> --limit 1`
+3. Verify metrics improve over next 5-10 scheduled runs
+4. Revert if worse: restore previous definition

package/builtin-skills/app-skill/references/model.md

@@ -0,0 +1,124 @@
+# Model CLI Reference
+
+## Overview
+
+Model management commands configure AI models used by the Loom platform — for chat, Process execution, and AI-assisted features.
+
+## Commands
+
+### `loom model list`
+
+List all configured AI models with their capability tier, tags, and default status.
+
+```bash
+loom model list
+```
+
+Output shows each model's name, capability tier (`[fast]`, `[standard]`, `[max]`), default marker, base URL, auth status, and tags.
+
+### `loom model add <name>`
+
+Add a new AI model configuration.
+
+```bash
+loom model add "claude-sonnet-4-6" \
+  --base-url "https://api.anthropic.com" \
+  --auth-token "sk-ant-..." \
+  --default \
+  --tier standard \
+  --tags "创作模型,多模态"
+```
+
+**Options:**
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--base-url` | Yes | API base URL |
+| `--auth-token` | No | Authentication token |
+| `--default` | No | Set as default model (first model is auto-default) |
+| `--tier` | No | Capability tier: `fast`, `standard`, or `max` |
+| `--tags` | No | Comma-separated classification tags |
+| `--token` | No | Auth token (or set LOOM_TOKEN) |
+| `--server` | No | Server URL (or set LOOM_SERVER, default: http://localhost:3000) |
+
+### `loom model update <name>`
+
+Update an existing model configuration.
+
+```bash
+# Change capability tier
+loom model update "claude-sonnet-4-6" --tier fast
+
+# Set as default
+loom model update "claude-opus-4-7" --default
+
+# Update tags
+loom model update "claude-sonnet-4-6" --tags "创作模型,多模态,代码"
+
+# Clear capability tier
+loom model update "claude-sonnet-4-6" --tier none
+
+# Clear tags
+loom model update "claude-sonnet-4-6" --tags ""
+```
+
+**Options:**
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--base-url` | No | Update API base URL |
+| `--auth-token` | No | Update authentication token |
+| `--default` | No | Set as default model |
+| `--tier` | No | Update capability tier (`fast`/`standard`/`max`, or `none` to clear) |
+| `--tags` | No | Update tags (comma-separated, or `""` to clear) |
+| `--token` | No | Auth token (or set LOOM_TOKEN) |
+| `--server` | No | Server URL (or set LOOM_SERVER, default: http://localhost:3000) |
+
+### `loom model remove <name>`
+
+Remove a model configuration. If the removed model was the default, the first remaining model becomes the new default.
+
+```bash
+loom model remove "old-model"
+```
+
+## Capability Tiers
+
+Capability tiers are informational labels for model capability:
+
+| Tier | Meaning | Use Case |
+|------|---------|----------|
+| `fast` | Lightweight, quick responses | Simple data aggregation, formatting |
+| `standard` | Balanced performance | General-purpose tasks |
+| `max` | Strongest reasoning | Complex analysis, multi-step reasoning |
+
+Capability tiers appear as colored tags in the AI Sidecar and ChatDrawer model selectors, and in Process overview when a model is bound.
+
+## Process Model Binding
+
+When creating a Process, you can specify which model it uses:
+
+```bash
+# Use a specific model for complex reasoning
+loom process add --name "daily-analysis" \
+  --cron "0 2 * * *" \
+  --prompt "Analyze daily data and generate insights" \
+  --owner admin \
+  --model "claude-opus-4-7"
+
+# Use a fast model for simple aggregation
+loom process add --name "quick-summary" \
+  --cron "*/30 * * * *" \
+  --prompt "Summarize key metrics" \
+  --owner admin \
+  --model "claude-sonnet-4-6"
+```
+
+If `--model` is omitted, the Process uses the global default model.
+
+## HTTP API Equivalents
+
+| CLI Command | HTTP Endpoint |
+|------------|---------------|
+| `loom model list` | `GET /api/v1/ai/models` |
+| `loom model add` | `POST /api/v1/ai/models` |
+| `loom model update` | `PUT /api/v1/ai/models/:name` |
+| `loom model remove` | `DELETE /api/v1/ai/models/:name` |

package/builtin-skills/app-skill/references/models.md

@@ -0,0 +1,45 @@
+# 数据模型与 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 -->
+
+<!-- AUTH_ROLES -->
+
+## filter 查询语法
+
+`loom data read --filter` 支持以下查询方式：
+
+| 语法 | 示例 | 说明 |
+|------|------|------|
+| 等值匹配 | `{"subject":"数学"}` | 字段等于指定值 |
+| 多条件 AND | `{"subject":"数学","difficulty":"困难"}` | 多字段同时匹配 |
+| 范围查询 | `{"createdAt":{"__range":["2026-03-01","2026-03-31"]}}` | 闭区间，包含两端点 |
+
+**注意**：不支持 `$gte`、`$gt`、`$lte`、`$lt`、`>=`、`<` 等比较操作符，使用不支持的语法不会报错但返回空结果。范围查询必须使用 `__range`。
+
+## 操作规范
+
+1. 所有数据操作必须使用 `loom data` CLI 命令，不要直接访问文件或数据库。
+2. 命令在项目根目录下执行。
+3. 执行删除等不可逆操作前，需与用户确认。
+4. 创建/更新时确保必填字段齐全。不确定时用 `loom data schema <model>` 查看。
+5. `update` 只需传入要修改的字段，未指定的字段保持不变。
+6. CLI 输出格式为 JSON — 解析输出以理解数据结构。
+7. 数据变更后，告知用户页面会自动刷新。