@loom-framework/core 0.1.0-alpha.19 → 0.1.0-alpha.191

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

@@ -0,0 +1,184 @@
+# Feeder 开发规范
+
+Feeder 是随 Process 生命周期管理的外部数据源脚本，负责从钉钉、Git Webhook 等渠道采集数据并推送到 EventBus。
+
+注册方式见 **`process.md` → Source (Feeder)**，创建流程见 **`process-builder.md` → 事件触发 + Feeder 数据源**。本文档聚焦**如何编写 Feeder 脚本本身**。
+
+## 脚本契约
+
+1. **环境变量**：使用 `$LOOM_SERVER_URL`（LifecycleManager 自动注入）、`$LOOM_SCRIPT_NAME`、业务环境变量（如 `$DINGTALK_*_CID`），禁止硬编码 URL 或 CID
+2. **单实例**：同一 name 的脚本只运行一个实例
+3. **整条消息一次推送**：以 `recv_new_messages` 为消息边界，攒完一整条再 flush；用 `jq -Rs` 构造 JSON，不要逐行发送
+4. **FIFO 路径**：使用 `$SCRIPT_DIR`（脚本所在目录），不要使用 `/tmp/`
+5. **始终 exit 1**：确保 LifecycleManager 能区分异常退出与主动停止（见下方"退出码与保活"）
+
+## 保活结构
+
+LifecycleManager 管理 Feeder 的生命周期：实例就绪时启动，实例关闭时停止。脚本必须遵循以下结构，否则进程死亡后无法被检测和重启。
+
+### 核心模式：FIFO + 后台进程
+
+```bash
+RUNNING=true
+trap 'RUNNING=false' SIGTERM SIGINT
+
+# 业务配置
+TARGET="${LOOM_SERVER_URL:-http://localhost:3000}/api/v1/events/emit"
+
+# 消息缓冲
+buffer=""
+started=false
+
+flush() {
+  if [[ -n "$buffer" ]]; then
+    if printf '%s' "$buffer" | jq -Rs '{pattern:"<event-pattern>",payload:{msgContent:.},source:"feeder"}' \
+      | curl -sf -X POST "$TARGET" -H 'Content-Type: application/json' -d @- > /dev/null; then
+      buffer=""
+    else
+      echo "[feeder] flush failed, retrying on next cycle" >&2
+    fi
+  fi
+}
+
+# FIFO + 后台进程
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+FIFO=$(mktemp -u "${SCRIPT_DIR}/feeder_${LOOM_SCRIPT_NAME:-default}_XXXXXX")
+mkfifo "$FIFO"
+<消息源命令> > "$FIFO" &
+WATCHER_PID=$!
+
+# EXIT trap 清理
+trap 'kill "$WATCHER_PID" 2>/dev/null; rm -f "$FIFO"' EXIT
+
+# 将 FIFO 绑定到 fd 3
+exec 3< "$FIFO"
+
+# 主循环
+while [ "$RUNNING" = "true" ]; do
+  if ! kill -0 "$WATCHER_PID" 2>/dev/null; then
+    break
+  fi
+
+  if IFS= read -r -t 2 line <&3; then
+    if [[ "$line" == recv_new_messages ]]; then
+      flush
+      started=true
+    elif [[ "$started" == "false" ]]; then
+      continue
+    else
+      buffer="${buffer:+$buffer$'\n'}$line"
+    fi
+  else
+    if ! kill -0 "$WATCHER_PID" 2>/dev/null; then
+      break
+    fi
+    flush
+  fi
+done
+
+# 排空残余数据
+while IFS= read -r -t 1 line <&3; do
+  if [[ "$line" == recv_new_messages ]]; then
+    flush
+    started=true
+  elif [[ "$started" == "true" ]]; then
+    buffer="${buffer:+$buffer$'\n'}$line"
+  fi
+done
+flush
+
+exec 3<&-
+exit 1
+```
+
+### 关键要点
+
+**必须使用 FIFO + 后台进程**，而非进程替换 `done < <(...)`：
+- 进程替换中子进程死亡时主 shell 不会退出，导致空转且 LifecycleManager 无法检测
+
+**EXIT trap 清理**：
+- 脚本退出时必须 kill 后台进程、删除 FIFO，避免孤儿进程
+
+**EOF 检测**：
+- `read` 返回 false 时检查后台进程是否存活，避免 FIFO 关闭后空转
+
+**信号处理**：
+- 捕获 SIGTERM/SIGINT 设置 `RUNNING=false`，主循环优雅退出
+- 静默超时（2 秒无新行）触发 flush，避免等下一条消息才发送当前消息
+
+### 退出码
+
+始终 `exit 1`：
+- **LifecycleManager 主动停止**：先设 `proc.status='stopping'` 再发 SIGTERM → exit handler 检测到 stopping 状态，不触发重启
+- **其他原因退出**（子进程崩溃、外部 kill 等）：status 非 stopping → exit handler 走 handleCrash → 保活重启
+- `exit 0` 会被当作"正常完成"而不重启
+
+## 事件格式
+
+Feeder 通过 POST `/api/v1/events/emit` 推送事件：
+
+```json
+{
+  "pattern": "dingtalk:mention",
+  "payload": { "msgContent": "<消息内容>" },
+  "source": "feeder"
+}
+```
+
+- `pattern`：事件模式，格式 `{category}:{action}` 或 `{category}:{action}:{target}`
+- `payload`：事件载荷，Process 订阅此模式后可读取
+- `source`：固定为 `"feeder"`
+
+## 钉钉 Feeder
+
+钉钉消息感知依赖 **antding-frida-hook Skill**，核心命令为 `antding watch`。
+
+### antding watch 输出格式
+
+`antding watch` 的输出以 `recv_new_messages` 标记每条新消息的开端：
+
+```
+recv_new_messages
+<消息内容行1>
+<消息内容行2>
+recv_new_messages
+<下一条消息内容>
+```
+
+脚本以 `recv_new_messages` 为消息边界：遇到时 flush 上一条缓冲，开始缓冲新消息。2 秒静默超时也触发 flush。
+
+### 常用 watch 参数
+
+| 参数 | 说明 |
+|------|------|
+| `--cid <cid>` | 监听指定群会话 |
+| `--keyword <text>` | 过滤包含关键词的消息 |
+| `--group-only` | 只监听群消息 |
+| `--exclude-sender <uid>` | 排除指定发送者（如排除自身） |
+
+### 环境变量
+
+| 变量 | 用途 |
+|------|------|
+| `$DINGTALK_TEST_CID` | 通用测试群的 CID |
+| `$DINGTALK_MENTION_CID` | @我消息所在群的 CID |
+| `$DINGTALK_URGENT_CID` | 紧急关键词群的 CID |
+
+## Git Webhook Feeder
+
+Git Webhook 不需要 antding，使用标准 HTTP 服务接收事件：
+
+- 由外部 Git 平台（GitHub/GitLab）主动 POST 到 Feeder 暴露的 HTTP 端点
+- Feeder 解析 payload 后按统一格式推送到 EventBus
+- 适合 PR/Commit 事件场景
+
+## 生命周期事件
+
+LifecycleManager 在 Feeder 运行期间发出以下事件，可供其他 Process 订阅：
+
+| 模式 | 触发时机 |
+|------|----------|
+| `lifecycle:started:{name}` | Feeder 脚本启动时 |
+| `lifecycle:failed:{name}` | Feeder 脚本异常退出时 |
+| `lifecycle:circuit_open:{name}` | Feeder 达到最大重启次数时 |
+| `lifecycle:restart:{name}` | Feeder 带退避策略重启时 |

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

@@ -0,0 +1,124 @@
+# Model CLI 参考
+
+## 概述
+
+模型管理命令用于配置 Loom 平台使用的 AI 模型——包括聊天、Process 执行和 AI 辅助功能。
+
+## 命令
+
+### `loom model list`
+
+列出所有已配置的 AI 模型及其能力层级、标签和默认状态。
+
+```bash
+loom model list
+```
+
+输出显示每个模型的名称、能力层级（`[fast]`、`[standard]`、`[max]`）、默认标记、基础 URL、认证状态和标签。
+
+### `loom model add <name>`
+
+添加新的 AI 模型配置。
+
+```bash
+loom model add "claude-sonnet-4-6" \
+  --base-url "https://api.anthropic.com" \
+  --auth-token "sk-ant-..." \
+  --default \
+  --tier standard \
+  --tags "创作模型,多模态"
+```
+
+**选项：**
+| Flag | 必填 | Description |
+|------|------|-------------|
+| `--base-url` | 是 | API 基础 URL |
+| `--auth-token` | 否 | 认证令牌 |
+| `--default` | 否 | 设为默认模型（第一个添加的模型自动成为默认） |
+| `--tier` | 否 | 能力层级：`fast`、`standard` 或 `max` |
+| `--tags` | 否 | 逗号分隔的分类标签 |
+| `--token` | 否 | 认证令牌（或设置 LOOM_TOKEN） |
+| `--server` | 否 | 服务器 URL（或设置 LOOM_SERVER，默认：http://localhost:3000） |
+
+### `loom model update <name>`
+
+更新已有的模型配置。
+
+```bash
+# 更改能力层级
+loom model update "claude-sonnet-4-6" --tier fast
+
+# 设为默认模型
+loom model update "claude-opus-4-7" --default
+
+# 更新标签
+loom model update "claude-sonnet-4-6" --tags "创作模型,多模态,代码"
+
+# 清除能力层级
+loom model update "claude-sonnet-4-6" --tier none
+
+# 清除标签
+loom model update "claude-sonnet-4-6" --tags ""
+```
+
+**选项：**
+| Flag | 必填 | Description |
+|------|------|-------------|
+| `--base-url` | 否 | 更新 API 基础 URL |
+| `--auth-token` | 否 | 更新认证令牌 |
+| `--default` | 否 | 设为默认模型 |
+| `--tier` | 否 | 更新能力层级（`fast`/`standard`/`max`，或 `none` 清除） |
+| `--tags` | 否 | 更新标签（逗号分隔，或 `""` 清除） |
+| `--token` | 否 | 认证令牌（或设置 LOOM_TOKEN） |
+| `--server` | 否 | 服务器 URL（或设置 LOOM_SERVER，默认：http://localhost:3000） |
+
+### `loom model remove <name>`
+
+移除模型配置。如果移除的模型是默认模型，剩余模型中的第一个将成为新的默认模型。
+
+```bash
+loom model remove "old-model"
+```
+
+## 能力层级
+
+能力层级是模型能力的信息标签：
+
+| Tier | Meaning | Use Case |
+|------|---------|----------|
+| `fast` | 轻量级，响应快速 | 简单数据聚合、格式化 |
+| `standard` | 性能均衡 | 通用任务 |
+| `max` | 最强推理能力 | 复杂分析、多步推理 |
+
+能力层级在 AI Sidecar 和 ChatDrawer 的模型选择器中以彩色标签显示，绑定模型的 Process 概览页也会显示。
+
+## Process 模型绑定
+
+创建 Process 时，可以指定其使用的模型：
+
+```bash
+# 使用指定模型进行复杂推理
+loom process add --name "daily-analysis" \
+  --cron "0 2 * * *" \
+  --prompt "Analyze daily data and generate insights" \
+  --owner admin \
+  --model "claude-opus-4-7"
+
+# 使用快速模型进行简单聚合
+loom process add --name "quick-summary" \
+  --cron "*/30 * * * *" \
+  --prompt "Summarize key metrics" \
+  --owner admin \
+  --model "claude-sonnet-4-6"
+```
+
+如果省略 `--model`，Process 将使用全局默认模型。
+
+## HTTP API 对应关系
+
+| CLI 命令 | HTTP 端点 |
+|----------|-----------|
+| `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,59 @@
+# 数据模型与 CLI 参考
+
+> 本文件由 `loom generate capabilities` 自动生成。请勿手动编辑 — 重新生成时将被覆盖。
+
+## 数据模型
+
+<!-- DATA_MODELS -->
+
+## CLI 命令
+
+所有数据操作使用 `loom data` CLI 命令，需在项目根目录下执行。
+
+| 命令 | 说明 |
+|------|------|
+| `loom data read <model> [--id <id>] [--filter <json>] [--sort <field>] [--sortOrder <asc\|desc>] [--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`。
+
+## sort / sortOrder 排序
+
+`loom data read --sort` 支持按字段排序：
+
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `--sort <field>` | 排序字段名 | `--sort createdAt` |
+| `--sortOrder <order>` | 排序方向：`asc`（默认）或 `desc` | `--sortOrder desc` |
+
+```bash
+# 按创建时间降序
+loom data read tasks --sort createdAt --sortOrder desc --limit 10
+```
+
+## 操作规范
+
+1. 所有数据操作必须使用 `loom data` CLI 命令，不要直接访问文件或数据库。
+2. 命令在项目根目录下执行。
+3. 执行删除等不可逆操作前，需与用户确认。
+4. 创建/更新时确保必填字段齐全。不确定时用 `loom data schema <model>` 查看。
+5. `update` 只需传入要修改的字段，未指定的字段保持不变。
+6. CLI 输出格式为 JSON — 解析输出以理解数据结构。
+7. 数据变更后，告知用户页面会自动刷新。

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

@@ -0,0 +1,123 @@
+# 通知命令参考
+
+## 概述
+
+Loom 提供内置通知系统，用于持久化的服务端通知。通知按用户作用域隔离，支持通过 HTTP API 和 CLI 进行 CRUD 操作。
+
+## CLI 命令
+
+### 列出通知
+```bash
+loom notification list [--unread] [--limit 20] [--offset 0] --token <TOKEN>
+```
+
+### 标记为已读
+```bash
+loom notification read <id> --token <TOKEN>
+```
+
+### 全部标记为已读
+```bash
+loom notification read-all --token <TOKEN>
+```
+
+### 删除通知
+```bash
+loom notification delete <id> --token <TOKEN>
+```
+
+### 清空所有通知
+```bash
+loom notification clear --token <TOKEN>
+```
+
+### 发送通知（仅管理员）
+```bash
+loom notification send --userId <userId> --type <type> --title <title> [--description DESC] --token <TOKEN>
+```
+
+## HTTP API
+
+| Method | Path | Auth | Permission | Description |
+|--------|------|------|------------|-------------|
+| GET | `/api/v1/notifications` | Required | Own only | 分页查询通知列表 |
+| GET | `/api/v1/notifications/unread-count` | Required | Own only | 获取未读数量 |
+| PUT | `/api/v1/notifications/:id/read` | Required | Own only | 标记为已读 |
+| PUT | `/api/v1/notifications/read-all` | Required | Own only | 全部标记为已读 |
+| DELETE | `/api/v1/notifications/:id` | Required | Own only | 删除单条通知 |
+| DELETE | `/api/v1/notifications` | Required | Own only | 清空所有通知 |
+| POST | `/api/v1/notifications` | Required | Admin | 创建通知 |
+
+## 通知类型
+
+- `success` — 绿色，操作成功完成
+- `error` — 红色，操作失败
+- `warning` — 橙色，需要关注
+- `info` — 蓝色，信息提示
+
+## 来源类型
+
+- `system` — 由 Loom 框架生成
+- `event` — 由 EventBus 订阅生成
+- `cli` — 通过 CLI 命令创建
+
+## EventBus notify 处理器
+
+在 `loom.config.ts` 中配置事件自动生成通知：
+
+```typescript
+export default defineConfig({
+  events: {
+    subscriptions: [
+      {
+        pattern: 'data:create:orders',
+        handler: 'notify',
+        config: {
+          type: 'success',
+          title: 'New Order Created',
+          description: 'Order {{id}} created in orders model',
+        },
+      },
+      {
+        pattern: 'user:login',
+        handler: 'notify',
+        config: {
+          type: 'info',
+          title: 'User Logged In',
+          broadcastAll: true,
+        },
+      },
+    ],
+  },
+});
+```
+
+### 配置选项
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `type` | `'success' \| 'error' \| 'warning' \| 'info'` | Yes | 通知严重级别 |
+| `title` | `string` | Yes | 通知标题（支持 `{{var}}` 插值） |
+| `description` | `string` | No | 通知正文（支持 `{{var}}` 插值） |
+| `broadcastAll` | `boolean` | No | 当事件无 userId 时广播给所有用户（默认：false） |
+
+### 插值
+
+标题和描述支持从事件载荷中提取 `{{var}}` 插值：
+- `{{id}}` — 记录 ID
+- `{{model}}` — 模型名称
+- 事件载荷中的任意字段
+
+缺失的变量将被替换为空字符串。
+
+### 行为规则
+
+- 若事件包含 `userId`：仅发送给该用户
+- 若事件无 `userId` 且 `broadcastAll: true`：发送给所有用户（上限 100）
+- 若事件无 `userId` 且 `broadcastAll: false`（默认）：跳过该通知
+
+## 权限
+
+- 用户只能读取/修改自己的通知
+- 仅管理员可通过 POST API 或 `loom notification send` 为其他用户创建通知
+- 通知在 30 天后或超过 500 条时自动清理