@loom-framework/core 0.1.0-alpha.150 → 0.1.0-alpha.152

package/builtin-skills/app-skill/SKILL.md

@@ -1,8 +1,8 @@
 ---
-name: {{projectName}}-data
+name: {{projectName}}
 description: |
   ⚠️ TODO: 根据下方 [TODO] 标记补全触发短语。阅读 references/models.md 中的数据模型和 AI 按钮定义，
-  编写触发短语，包含：用户语言中的常见增删改查动词、各数据模型相关的操作、AI 按钮的标签。
+  编写触发短语，包含：用户语言中的常见增删改查动词、各数据模型相关的操作、AI 按钮的标签<!-- AUTH_DESC --><!-- EVENTS_DESC --><!-- PROCESS_DESC -->
   格式："This skill should be used when the user asks to '短语1', '短语2',
   or any request about <此项目管理的内容> in the {{projectName}} project."
 version: 1.0.0
@@ -10,23 +10,34 @@ version: 1.0.0
 
 # {{projectName}} — App Skill
 
-> **此文件由 `loom generate capabilities` 生成。标记为 [TODO] 的部分需要手动编辑补全。** 
+> **此文件由 `loom generate capabilities` 生成。标记为 [TODO] 的部分需要手动编辑补全。**
 > references/models.md 和 references/data-semantics.md 会每次重新生成，无需手动编辑。
 
 ## Overview
 
 [TODO: 阅读 references/models.md，用2-3句话描述项目做什么、管理哪些数据模型、用户如何通过 AI 对话与数据交互。]
+<!-- AUTH_OVERVIEW -->
+<!-- EVENTS_OVERVIEW -->
+<!-- PROCESS_OVERVIEW -->
 
 ## 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 字段筛选、跨模型关联查询）。
+<!-- AUTH_SCENARIOS_LOAD -->
+<!-- PROCESS_SCENARIOS_LOAD -->
 
-[TODO: 生成8-10个典型用户请求，每个格式：用户说的话 → 对应的 `loom data` CLI 命令。每个数据模型至少包含一个场景。]
+[TODO: 生成5-10个典型用户请求，每个格式：用户说的话 → 对应的 `loom data` CLI 命令。每个数据模型至少包含一个场景。]
+<!-- AUTH_SCENARIOS -->
+<!-- EVENTS_SCENARIOS -->
+<!-- PROCESS_SCENARIOS -->
 
 ## Technical Reference
 
+<!-- CLI_AUTH -->
 - 数据模型结构、CLI 语法和操作规范：**references/models.md**
 - 语义引导（示例数据生成、筛选选择、关系推断）：**references/data-semantics.md**
-<!-- AUTH_REF -->
+<!-- AUTH_REF -->
+<!-- EVENTS_REF -->
+<!-- PROCESS_REF -->

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

@@ -1,19 +1,5 @@
 # Auth Commands Reference
 
-## CLI Authentication
-
-CLI commands require authentication when auth is enabled. Provide token via:
-
-1. **`--token` flag**: `loom data read <model> --token <jwt>`
-2. **`LOOM_TOKEN` env**: `LOOM_TOKEN=<jwt> loom data read <model>`
-
-When auth is not enabled, CLI commands use local DataAdapter without token.
-
-### AI Chat Sessions
-
-When using AI chat (web UI), `LOOM_TOKEN` is automatically set in the AI's environment.
-AI can run `loom data read`, `loom user list`, etc. directly — the token matches the logged-in user's identity and permissions.
-
 ## Authentication Commands
 
 ### Login
@@ -65,12 +51,30 @@ loom user delete <id> --token <admin-jwt>
 loom user role <id> <role> --token <admin-jwt>
 ```
 
-## Role Info
+## 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
@@ -89,8 +93,6 @@ loom data delete <model> --id <id> --token <jwt>
 loom data schema <model> --token <jwt>
 ```
 
-Optional: `--server <url>` (default: http://localhost:3000)
-
 ## Permission Model
 
 ### Levels (hierarchical)
@@ -115,7 +117,6 @@ auth: {
     defaults: {
       read: 'read',
       write: 'write',
-      readIncludesAiButtons: false,  // viewer sees AI buttons?
       writeExcludesDelete: false,     // writer can delete?
     },
   },
@@ -146,7 +147,10 @@ Used by Process automation to execute as the 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 | Yes | List roles |
+| 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 |

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/process-builder.md

@@ -0,0 +1,140 @@
+# Process Builder Guide
+
+## Purpose
+
+This guide helps AI assistants create Processes for users. When a user says "I want to automate X" or "run Y every day", use this guide to build a process definition.
+
+## Lightweight vs Full Decision
+
+### Use Lightweight (`--prompt`) when:
+- Single, simple task
+- No reference files needed
+- Prompt fits in a few sentences
+- No metrics dashboard needed
+
+### Use Full (`--process`) when:
+- Multi-step workflow with decision points
+- Reference documentation needed (API docs, data schemas, style guides)
+- Metrics dashboard desired
+- Process may evolve over time (Evolution section)
+
+## Step-by-Step Creation
+
+### 1. Analyze the Request
+
+Identify:
+- **What** the process should do
+- **When** it should run (schedule or event trigger)
+- **Who** owns it (username for service token)
+- **Complexity** (lightweight vs full)
+
+### 2. Choose Trigger
+
+| Need | Use | Example |
+|------|-----|---------|
+| Periodic schedule | `--cron` | `0 9 * * 1-5` (weekdays 9am) |
+| On data change | `--on-event` | `data:create:tasks` |
+| On user action | `--on-event` | `user:created` |
+| Manual only | Neither | Just `loom process run` |
+
+### 3. Create the Process
+
+For lightweight:
+```bash
+loom process add --name "task-summary" \
+  --cron "0 9 * * *" \
+  --prompt "Read all tasks created yesterday, summarize key themes, and post a digest" \
+  --owner admin
+```
+
+For full:
+```bash
+# Step 1: Generate scaffold
+loom process generate weekly-report --description "Weekly analytics report"
+
+# Step 2: Edit PROCESS.md with detailed flow
+# (AI should write the PROCESS.md content)
+
+# Step 3: Add reference files if needed
+# (Copy to .claude/processes/weekly-report/references/)
+
+# Step 4: Register the process
+loom process add --name "weekly-report" \
+  --cron "0 9 * * 1" \
+  --process "weekly-report" \
+  --owner admin
+```
+
+### 4. Verify
+
+```bash
+loom process status <name>
+loom process run <name>  # manual test
+loom process logs <name>  # check result
+```
+
+## PROCESS.md Best Practices
+
+### Structure
+
+```markdown
+# Process: <name>
+
+## Description
+What this process does and why.
+
+## Trigger
+When it runs and what triggers it.
+
+## Flow
+Step-by-step instructions:
+1. Read data from <model>
+2. Analyze <something>
+3. Write results to <model>
+4. Notify <channel>
+
+## Decision Points
+Key decisions the AI should make:
+- If X, do Y
+- If Z, skip to step N
+
+## Metrics
+How success is measured:
+- Execution time < N seconds
+- Error rate < X%
+- Output quality: <criteria>
+
+## Evolution
+How this process should improve:
+- After N runs, review and optimize prompt
+- Track common errors and add handling
+```
+
+### Tips
+- Be specific in Flow steps — AI follows them literally
+- Include data model names and field names
+- Reference CLI commands: `loom data list <model>`, `loom data create <model>`
+- Use `loom data` commands for data operations, not direct file I/O
+- Include error handling in Decision Points
+
+## Common Cron Patterns
+
+| Pattern | Schedule |
+|---------|----------|
+| `*/5 * * * *` | Every 5 minutes |
+| `*/15 * * * *` | Every 15 minutes |
+| `0 * * * *` | Every hour |
+| `0 9 * * *` | Daily at 9 AM |
+| `0 9 * * 1-5` | Weekdays at 9 AM |
+| `0 9 * * 1` | Every Monday at 9 AM |
+| `0 0 1 * *` | First of every month |
+
+## Common Event Patterns
+
+| Pattern | When |
+|---------|------|
+| `data:create:<model>` | New record created |
+| `data:update:<model>` | Record updated |
+| `data:delete:<model>` | Record deleted |
+| `user:created` | New user registered |
+| `process:completed:<name>` | Another process finished |

package/builtin-skills/app-skill/references/process-metrics.md

@@ -0,0 +1,93 @@
+# Process Metrics Reference
+
+## Overview
+
+Process metrics allow you to define dashboard widgets for monitoring process execution. Metrics are served via the `/api/v1/processes/:name/metrics` endpoint and configured per-process.
+
+## Metrics Config
+
+Define metrics using DashboardWidget schema in `--metrics-config <path>` JSON file or via the API.
+
+### Example: metrics-config.json
+
+```json
+[
+  {
+    "type": "stat",
+    "title": "成功率",
+    "model": "__process_metrics",
+    "aggregate": "sum",
+    "field": "completedRuns",
+    "color": "#52c41a"
+  },
+  {
+    "type": "stat",
+    "title": "失败次数",
+    "model": "__process_metrics",
+    "aggregate": "sum",
+    "field": "failedRuns",
+    "color": "#ff4d4f"
+  },
+  {
+    "type": "line",
+    "title": "执行趋势",
+    "model": "__process_metrics",
+    "aggregate": "sum",
+    "field": "totalRuns",
+    "groupBy": "date",
+    "dateInterval": "day"
+  }
+]
+```
+
+### Available Widget Types
+
+| Type | Description | Required Fields |
+|------|-------------|-----------------|
+| `stat` | Single number display | `title`, `model`, `aggregate`, `field` |
+| `line` | Line chart | `title`, `model`, `aggregate`, `field`, `groupBy`, `dateInterval` |
+| `bar` | Bar chart | `title`, `model`, `aggregate`, `field`, `groupBy` |
+| `pie` | Pie chart | `title`, `model`, `field`, `groupBy` |
+| `gauge` | Gauge display | `title`, `model`, `field`, `min`, `max` |
+| `table` | Table view | `title`, `model`, `columns` |
+
+### Available Metrics Fields
+
+From `ProcessMetricsAggregate`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `date` | string | Date (YYYY-MM-DD) |
+| `totalRuns` | number | Total executions |
+| `completedRuns` | number | Successful executions |
+| `failedRuns` | number | Failed executions |
+| `timeoutRuns` | number | Timed out executions |
+| `avgDurationMs` | number | Average duration in ms |
+| `lastRunAt` | string\|null | Last execution timestamp |
+| `lastStatus` | string\|null | Last execution status |
+
+### Setting Metrics Config
+
+```bash
+# During process creation
+loom process add --name "health-check" \
+  --cron "*/30 * * * *" \
+  --prompt "Check system health" \
+  --metrics-config ./health-metrics.json \
+  --owner admin
+
+# Or create the JSON file first
+echo '[
+  {"type":"stat","title":"Success Rate","model":"__process_metrics","aggregate":"sum","field":"completedRuns"},
+  {"type":"stat","title":"Avg Duration","model":"__process_metrics","aggregate":"avg","field":"avgDurationMs"}
+]' > health-metrics.json
+```
+
+### API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/v1/processes/:name/metrics` | GET | Get aggregated metrics data |
+| `/api/v1/processes/:name/metrics-config` | GET | Get widget configuration |
+
+The frontend ProcessManagementPage Metrics tab fetches both endpoints and renders the configured widgets dynamically.