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

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,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. 数据变更后，告知用户页面会自动刷新。

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 条时自动清理