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

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

@@ -1,10 +1,8 @@
 ---
 name: {{projectName}}
 description: |
-  ⚠️ TODO: 根据下方 [TODO] 标记补全触发短语。阅读 references/models.md 中的数据模型和 AI 按钮定义，
-  编写触发短语，包含：用户语言中的常见增删改查动词、各数据模型相关的操作、AI 按钮的标签。另外后续是一些系统操作短语，修改时需保留：<!-- AUTH_DESC --><!-- EVENTS_DESC --><!-- PROCESS_DESC --><!-- NOTIFICATION_DESC -->
-  格式："This skill should be used when the user asks to '短语1', '短语2',
-  or any request about <此项目管理的内容> in the {{projectName}} project."
+  This skill should be used when the user asks to "[TODO: 补全数据模型相关短语，如 '查看告警', '添加任务']"<!-- AUTH_DESC --><!-- EVENTS_DESC --><!-- PROCESS_DESC --><!-- NOTIFICATION_DESC -->,
+  or any request about managing data, processes, events, or notifications in the {{projectName}} project.
 version: 1.0.0
 ---
 
@@ -27,6 +25,7 @@ version: 1.0.0
 - 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 -->
+<!-- EVENTS_SCENARIOS_LOAD -->
 <!-- PROCESS_SCENARIOS_LOAD -->
 <!-- NOTIFICATION_SCENARIOS_LOAD -->
 
@@ -41,7 +40,7 @@ version: 1.0.0
 <!-- CLI_AUTH -->
 - 数据模型结构、CLI 语法和操作规范：**references/models.md**
 - 语义引导（示例数据生成、筛选选择、关系推断）：**references/data-semantics.md**
-- 鉴权与 Token 注入：**references/auth.md** — Web 对话和 Process 执行时 `LOOM_TOKEN` 将自动注入，`loom data` 命令无需添加 `--token`；本地终端执行时才需显式传 `--token`。
+- AI 模型管理（model list/add/update/remove、能力层级、Process 模型绑定）：**references/model.md**
 <!-- AUTH_REF -->
 <!-- EVENTS_REF -->
 <!-- PROCESS_REF -->

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

@@ -1,89 +1,89 @@
-# Auth Commands Reference
+# 认证命令参考
 
-## Authentication Commands
+## 认证命令
 
-### Login
+### 登录
 ```bash
 loom auth login -u <username> -p <password>
-loom auth login  # interactive prompt
+loom auth login  # 交互式提示
 ```
 
-### Register (admin token required)
+### 注册（需要 admin 令牌）
 ```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).
+注意：`role list` 不需要认证（该端点是公开的）。
 
-### 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:
+启用认证后，数据命令通过 HTTP API 路由，需要令牌：
 
 ```bash
 loom data read <model> --token <jwt>
@@ -93,33 +93,33 @@ 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:
+在 Web 聊天和 Process 执行场景中，`LOOM_TOKEN` 会自动注入到环境变量中，无需 `--token`：
 
-| 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 |
+| 场景 | 令牌来源 | 需要 --token？ |
+|------|---------|---------------|
+| Web 聊天（ChatDrawer → Claude Code） | 框架在启动 `claude -p` 时将用户 JWT 注入为 `LOOM_TOKEN` 环境变量 | 否 |
+| Process 自动化（cron/事件） | 框架将所有者的 JWT 注入为 `LOOM_TOKEN` 环境变量 | 否（在 prompt 中使用 `$LOOM_TOKEN` shell 变量引用） |
+| 本地终端 `loom` 命令 | 无自动注入 | 是 |
 
-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.
+优先级：`--token` 参数 > `LOOM_TOKEN` 环境变量。`--token` 参数作为后备/覆盖使用——始终包含是安全的，但在 Web/Process 场景中是冗余的。
 
-## Permission Model
+## 权限模型
 
-### Levels (hierarchical)
-| Level | Access |
-|-------|--------|
-| `none` | No access |
-| `read` | GET (read-only) |
-| `write` | GET, POST, PUT |
-| `admin` | GET, POST, PUT, DELETE |
+### 等级（层级关系）
+| Level | 访问权限 |
+|-------|---------|
+| `none` | 无访问权限 |
+| `read` | GET（只读） |
+| `write` | GET、POST、PUT |
+| `admin` | GET、POST、PUT、DELETE |
 
-### Configuration in loom.config.ts
+### 在 loom.config.ts 中配置
 ```typescript
 auth: {
   provider: 'builtin',
-  secret: 'env:JWT_SECRET',  // or plain string (not recommended)
+  secret: 'env:JWT_SECRET',  // 或明文字符串（不推荐）
   roles: [
     { role: 'admin', permissions: [{ model: '*', level: 'admin' }] },
     { role: 'editor', permissions: [{ model: 'items', level: 'write' }] },
@@ -129,52 +129,52 @@ auth: {
     defaults: {
       read: 'read',
       write: 'write',
-      writeExcludesDelete: false,     // writer can delete?
+      writeExcludesDelete: false,     // write 角色是否可以删除？
     },
   },
 }
 ```
 
-### Wildcard Permissions
-Use `model: '*'` to apply a permission level to all models.
-Explicit model permissions override wildcards.
+### 通配符权限
+使用 `model: '*'` 将权限等级应用到所有模型。
+显式模型权限覆盖通配符。
 
-### Default Admin User
-When auth is first enabled, a default admin user is created:
-- Username: `admin`
-- Password: `admin123`
-- **Change this immediately after first login!**
+### 默认管理员用户
+首次启用认证时，会创建默认管理员用户：
+- 用户名：`admin`
+- 密码：`admin123`
+- **首次登录后请立即修改密码！**
 
-### 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.
+### 服务令牌
+每个用户在注册时会获得一个服务令牌（长效 JWT，30 天有效期）。
+创建用户时在 API 响应中返回——管理员应安全保存。
+Process 自动化使用它来以该用户身份执行操作。
 
-## API Endpoints
+## API 端点
 
 | 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.
+| POST | /api/v1/auth/login | No | 登录 |
+| POST | /api/v1/auth/register | Admin | 注册新用户 |
+| POST | /api/v1/auth/logout | Yes | 登出 |
+| POST | /api/v1/auth/refresh | No* | 刷新令牌 |
+| GET | /api/v1/auth/whoami | Yes | 当前用户信息 |
+| GET | /api/v1/auth/roles | No | 列出角色 |
+| POST | /api/v1/auth/roles | Admin | 创建角色 |
+| PUT | /api/v1/auth/roles/:role | Admin | 更新角色 |
+| DELETE | /api/v1/auth/roles/:role | Admin | 删除角色 |
+| GET | /api/v1/auth/users | Admin | 列出用户 |
+| POST | /api/v1/auth/users | Admin | 创建用户 |
+| GET | /api/v1/auth/users/:id | Self/Admin | 获取用户信息 |
+| PUT | /api/v1/auth/users/:id | Self/Admin | 更新用户 |
+| DELETE | /api/v1/auth/users/:id | Admin | 删除用户 |
+
+*刷新令牌需要存储中有效的 refresh token
+
+## 审计字段
+
+启用认证后，写操作会自动注入：
+- `createdBy` — 创建该记录的用户名（POST）
+- `updatedBy` — 最后更新该记录的用户名（PUT）
+
+这些字段是可选的，不会影响现有数据。

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

@@ -1,5 +1,7 @@
 # 事件系统参考
 
+> **配置 Schema 参考**：事件订阅的声明式配置 (`events.subscriptions`) 见 Loom Skill (`references/data-model.md` → EventsConfig)。
+
 Loom 事件系统在数据变更和系统操作时自动触发事件，可用于通知、审计和自动化。
 
 ## 事件模式格式
@@ -69,38 +71,167 @@ Loom 事件系统在数据变更和系统操作时自动触发事件，可用于
 |----------|----------|-------------|
 | `file:uploaded` | 文件上传成功 | filename, sessionId, path, size |
 
+## 订阅可用处理器
+
+| handler | 说明 | config 字段 |
+|---------|------|------------|
+| `process` | 触发 Process 执行 | `process`（必填）, `filter`, `debounceMs` |
+| `webhook` | 发送 HTTP 请求 | `url`（必填）, `method`, `headers` |
+| `log` | 写入服务器日志 | `level`: info/debug/warn |
+| `notify` | 创建站内通知 | `title`, `description` |
+
 ## 配置声明式订阅
 
-在 `loom.config.ts` 中声明事件处理器：
+在 `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' },
-      },
+      { pattern: 'data:create:orders', handler: 'process', config: { process: 'order-processor' } },
+      { pattern: 'data:create:orders', handler: 'webhook', config: { url: 'https://example.com/webhook' } },
+      { pattern: 'user:login', handler: 'log', config: { level: 'info' } },
+      { pattern: 'alert:critical', handler: 'notify', config: { title: 'Critical Alert' } },
     ],
   },
 });
 ```
 
+## CLI 管理
+
+### `loom event list`
+
+列出所有事件订阅（显示稳定 ID）。
+
+```bash
+loom event list
+```
+
+输出示例：
+```
+Event Subscriptions:
+  sub_1747301234_ab data:create:tasks → process (on-task-create) ●
+  sub_1747301235_cd user:login → log (info)
+  sub_1747301236_ef alert:critical → webhook → https://example.com/hook
+```
+
+`●` 表示订阅活跃（process 类型需目标进程已注册事件监听；webhook/log/notify 类型在 EventBus 运行时始终活跃），`○` 表示未激活。
+
+### `loom event subscribe <pattern>`
+
+添加事件订阅，返回稳定 ID。
+
+```bash
+# 触发 Process 执行
+loom event subscribe "data:create:tasks" \
+  --handler process \
+  --process "on-task-create"
+
+# 带过滤和防抖
+loom event subscribe "data:update:*" \
+  --handler process \
+  --process "on-data-update" \
+  --filter '{"model":"tasks"}' \
+  --debounce 2000
+
+# Webhook
+loom event subscribe "alert:critical" \
+  --handler webhook \
+  --url "https://example.com/hook"
+
+# 日志
+loom event subscribe "data:*" \
+  --handler log \
+  --level debug
+
+# 通知
+loom event subscribe "incident:created" \
+  --handler notify \
+  --title "New Incident"
+```
+
+**Options:**
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--handler` | Yes | Handler type: `process` \| `webhook` \| `log` \| `notify` |
+| `--process` | process | 目标 Process 名称（handler=process 时必填） |
+| `--url` | webhook | Webhook URL（handler=webhook 时必填） |
+| `--method` | No | HTTP 方法，默认 POST（handler=webhook） |
+| `--headers` | No | Webhook 请求头 JSON |
+| `--level` | No | 日志级别 info/debug/warn（handler=log） |
+| `--title` | No | 通知标题模板（handler=notify） |
+| `--description` | No | 通知描述模板（handler=notify） |
+| `--filter` | No | 事件载荷过滤 JSON（handler=process） |
+| `--debounce` | No | 防抖窗口 ms，默认 1000（handler=process） |
+| `--token` | No | Auth token（或设置 LOOM_TOKEN） |
+| `--server` | No | Server URL（或设置 LOOM_SERVER） |
+
+### `loom event update <id>`
+
+按 ID 部分更新事件订阅（只需指定要修改的字段）。
+
+```bash
+# 修改防抖值
+loom event update sub_1747301234_ab --debounce 2000
+
+# 修改 pattern
+loom event update sub_1747301234_ab --pattern "data:update:tasks"
+
+# 修改 process 配置
+loom event update sub_1747301234_ab --process "new-processor" --filter '{"status":"critical"}'
+
+# 修改 webhook URL
+loom event update sub_1747301235_cd --url "https://new-hook.example.com"
+```
+
+**Options:**
+| Flag | Required | Description |
+|------|----------|-------------|
+| `--pattern` | No | 新的事件模式 |
+| `--handler` | No | 新的处理器类型 |
+| `--process` | No | Process 名称（handler=process） |
+| `--filter` | No | 事件载荷过滤 JSON（handler=process） |
+| `--debounce` | No | 防抖窗口 ms（handler=process） |
+| `--url` | No | Webhook URL（handler=webhook） |
+| `--method` | No | HTTP 方法（handler=webhook） |
+| `--headers` | No | Webhook 请求头 JSON（handler=webhook） |
+| `--level` | No | 日志级别（handler=log） |
+| `--title` | No | 通知标题（handler=notify） |
+| `--description` | No | 通知描述（handler=notify） |
+| `--token` | No | Auth token |
+| `--server` | No | Server URL |
+
+### `loom event unsubscribe <id>`
+
+按 ID 删除事件订阅。
+
+```bash
+loom event unsubscribe sub_1747301234_ab
+```
+
+### `loom event test <pattern>`
+
+发送测试事件（调试用）。
+
+```bash
+loom event test "data:create:tasks"
+loom event test "data:update:items" --payload '{"id":"test_123"}'
+```
+
 ## 事件 API
 
 | 端点 | 方法 | 说明 |
 |------|------|------|
-| `/api/v1/events/notify` | POST | 外部事件注入（CLI 使用） |
+| `/api/v1/events/emit` | POST | 外部事件注入（CLI 使用） |
 | `/api/v1/events/patterns` | GET | 查看已注册的事件模式 |
+| `/api/v1/events/subscriptions` | GET | 列出所有事件订阅 |
+| `/api/v1/events/subscriptions` | POST | 添加事件订阅 |
+| `/api/v1/events/subscriptions/:id` | PUT | 部分更新事件订阅 |
+| `/api/v1/events/subscriptions/:id` | DELETE | 删除事件订阅 |
+| `/api/v1/events/test` | POST | 发送测试事件 |
 
-### POST /api/v1/events/notify
+### POST /api/v1/events/emit
 
 ```json
 {
@@ -110,10 +241,97 @@ export default defineConfig({
 }
 ```
 
-## 订阅可用处理器
+### POST /api/v1/events/subscriptions
 
-| handler | 说明 | config 字段 |
-|---------|------|------------|
-| `log` | 写入服务器日志 | `level`: info/debug/warn |
-| `webhook` | 发送 HTTP 请求 | `url`, `method`, `headers` |
-| `process` | 启动进程（未来） | `process`, `filter` |
+返回值包含自动生成的稳定 `id`：
+
+```json
+{
+  "pattern": "data:create:orders",
+  "handler": "process",
+  "config": { "process": "order-processor", "debounceMs": 1000 }
+}
+```
+
+响应：
+```json
+{ "ok": true, "id": "sub_1747301234_ab", "subscription": { "id": "sub_1747301234_ab", "pattern": "...", "handler": "...", "config": {...} } }
+```
+
+### PUT /api/v1/events/subscriptions/:id
+
+部分更新（只发送要修改的字段）：
+
+```json
+{ "config": { "debounceMs": 2000 } }
+```
+
+## Process 事件绑定
+
+Process 通过事件订阅响应事件。三种绑定方式：
+
+1. **创建 Process 时绑定**（原子操作）：`loom process add --subscribe "pattern"` — 同时创建 process 和 subscription，保证 process 存在时订阅立即生效
+2. **给已有 Process 添加订阅**：`loom process update <name> --subscribe-add "pattern"` 或 `loom event subscribe "pattern" --handler process --process <name>`
+3. **移除订阅**：`loom process update <name> --subscribe-remove <id>` 或 `loom event unsubscribe <id>`
+
+注意：避免对同一 pattern + process 重复声明（声明式配置 + CLI/API），否则会双重触发。
+
+### `loom process add --subscribe`
+
+创建 Process 时同时绑定事件订阅（原子操作）：
+
+```bash
+loom process add --name "on-task-create" \
+  --prompt "自动处理新任务" \
+  --subscribe "data:create:tasks" \
+  --event-filter '{"priority":"high"}' \
+  --event-debounce 2000 \
+  --owner admin
+```
+
+**Options:**
+| Flag | Description |
+|------|-------------|
+| `--subscribe <pattern>` | 事件模式（如 `data:create:tasks`）|
+| `--event-filter <json>` | 事件载荷过滤（可选）|
+| `--event-debounce <ms>` | 防抖窗口，默认 1000ms（可选）|
+| `--source <command>` | Feeder 命令，必须同时指定 `--subscribe`（可选）|
+
+### `loom process update --subscribe-add / --subscribe-remove`
+
+给已有 Process 动态添加或移除事件订阅：
+
+```bash
+# 添加订阅
+loom process update my-process \
+  --subscribe-add "data:update:orders" \
+  --subscribe-filter '{"status":"urgent"}' \
+  --subscribe-debounce 1500
+
+# 移除订阅
+loom process update my-process --subscribe-remove sub_1747301234_ab
+```
+
+## 声明式配置
+
+事件订阅也可以在 `loom.config.ts` 的 `events.subscriptions` 中声明式定义（完整 Schema 见 Loom Skill `references/data-model.md` → EventsConfig）。服务启动时自动注册，修改后需重启生效。适合固定不变的订阅（如 webhook 推送、日志记录）。
+
+CLI/API 与声明式配置不要对同一 pattern + handler 重复声明，否则会双重触发。
+
+## 事件管理页面
+
+系统管理 → 事件管理 页面提供可视化操作：
+
+- **查看所有订阅**：表格展示 pattern、handler、config 详情、活跃状态
+- **添加/编辑/删除订阅**：按 handler 类型动态渲染配置表单
+- **测试事件**：输入 pattern + payload 发送测试事件调试
+
+通过 `loom generate system-settings event` 接入 App.tsx，或 `loom eject system-settings event` 定制。
+
+## 校验行为
+
+| 操作 | 校验规则 |
+|------|---------|
+| `handler: 'process'` | 目标 process 必须存在，否则返回 `Process "xxx" not found` |
+| `handler: 'webhook'` | `config.url` 必填，否则返回 `webhook handler requires config.url` |
+| `handler: 'process'` + 无 `--process` | 返回 `--process is required when handler=process` |