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

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

@@ -1,90 +1,90 @@
-# Process Evolution Guide
+# Process 演化指南
 
-## 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.
+Process 演化是基于执行结果持续改进自动化流程的实践。Loom 提供工具（日志、指标）供 AI 随时间分析和优化流程。
 
-## 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
+1. **监控**：查看执行日志和指标
+2. **分析**：识别模式、失败原因和优化机会
+3. **决策**：确定需要变更的内容（prompt、trigger、references）
+4. **执行**：更新流程定义或 PROCESS.md
+5. **验证**：监控后续运行以确认改进效果
 
-## Reading Metrics
+## 读取指标
 
 ```bash
-# Check recent logs
+# 查看最近日志
 loom process logs <name> --limit 20
 
-# View process status
+# 查看 process 状态
 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 |
+| 指标 | 良好 | 需要改进 |
+|------|------|----------|
+| 成功率 | > 95% | < 80% |
+| 平均耗时 | 稳定或下降 | 上升趋势 |
+| 超时率 | 0% | > 5% |
+| 错误模式 | 错误各不相同 | 同一错误反复出现 |
 
-## Evolution Strategies
+## 演化策略
 
-### Prompt Optimization
+### Prompt 优化
 
-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
+1. 读取当前 prompt：`loom process export <name>`
+2. 分析日志中的失败模式
+3. 让 prompt 更具体：
+   - 添加约束（"输出必须为 JSON"）
+   - 添加示例（"好的输出示例：..."）
+   - 添加错误处理指令
+4. 更新：`loom process export <name>` → 编辑 → API 更新
 
-### Trigger Adjustment
+### Trigger 调整
 
-If a process runs too often or too rarely:
+如果流程运行过于频繁或过少：
 
-- Adjust cron frequency
-- Add `--event-debounce` for bursty events
-- Add `--event-filter` for selective triggering
+- 调整 cron 频率
+- 通过 `loom event subscribe/unsubscribe` 管理事件订阅
+- 通过 `loom event subscribe --debounce --filter` 添加防抖或过滤
 
 ```bash
-# Increase debounce for bursty events
-loom process update <name> --event-debounce 5000
+# 对突发事件添加防抖订阅
+loom event subscribe "data:update:*" --handler process --process <name> --debounce 5000
 
-# Add filter to only trigger on specific conditions
-loom process update <name> --event-filter '{"status":"urgent"}'
+# 添加过滤条件，仅在特定条件下触发
+loom event subscribe "data:update:tasks" --handler process --process <name> --filter '{"status":"urgent"}'
 ```
 
-### Reference Updates
+### Reference 更新
 
-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
+对于完整流程，更新引用文件：
+- 过时的 API 文档 → 替换为最新版本
+- 缺少上下文 → 添加新的 reference 文件
+- 不必要的引用 → 移除以减少 prompt 大小
 
-## 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
+演化仅限于以下安全操作：
+- **通知**：通过事件发送告警
+- **数据写入**：通过 `loom data` CLI 创建/更新记录
+- **Process 更新**：通过 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
+演化严禁：
+- 未经用户明确批准删除数据
+- 未经用户同意修改其他流程
+- 更改认证或授权设置
+- 在沙箱外执行 shell 命令
 
-## 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
+应用演化变更后：
+1. 手动运行：`loom process run <name>`
+2. 检查结果：`loom process logs <name> --limit 1`
+3. 验证后续 5-10 次定时运行的指标是否改善
+4. 情况恶化时回滚：恢复之前的定义

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

@@ -1,24 +1,24 @@
-# Model CLI Reference
+# Model CLI 参考
 
-## Overview
+## 概述
 
-Model management commands configure AI models used by the Loom platform — for chat, Process execution, and AI-assisted features.
+模型管理命令用于配置 Loom 平台使用的 AI 模型——包括聊天、Process 执行和 AI 辅助功能。
 
-## Commands
+## 命令
 
 ### `loom model list`
 
-List all configured AI models with their capability tier, tags, and default status.
+列出所有已配置的 AI 模型及其能力层级、标签和默认状态。
 
 ```bash
 loom model list
 ```
 
-Output shows each model's name, capability tier (`[fast]`, `[standard]`, `[max]`), default marker, base URL, auth status, and tags.
+输出显示每个模型的名称、能力层级（`[fast]`、`[standard]`、`[max]`）、默认标记、基础 URL、认证状态和标签。
 
 ### `loom model add <name>`
 
-Add a new AI model configuration.
+添加新的 AI 模型配置。
 
 ```bash
 loom model add "claude-sonnet-4-6" \
@@ -29,82 +29,82 @@ loom model add "claude-sonnet-4-6" \
   --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) |
+**选项：**
+| 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>`
 
-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) |
+**选项：**
+| 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>`
 
-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 |
+| `fast` | 轻量级，响应快速 | 简单数据聚合、格式化 |
+| `standard` | 性能均衡 | 通用任务 |
+| `max` | 最强推理能力 | 复杂分析、多步推理 |
 
-Capability tiers appear as colored tags in the AI Sidecar and ChatDrawer model selectors, and in Process overview when a model is bound.
+能力层级在 AI Sidecar 和 ChatDrawer 的模型选择器中以彩色标签显示，绑定模型的 Process 概览页也会显示。
 
-## Process Model Binding
+## Process 模型绑定
 
-When creating a Process, you can specify which model it uses:
+创建 Process 时，可以指定其使用的模型：
 
 ```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" \
@@ -112,12 +112,12 @@ loom process add --name "quick-summary" \
   --model "claude-sonnet-4-6"
 ```
 
-If `--model` is omitted, the Process uses the global default model.
+如果省略 `--model`，Process 将使用全局默认模型。
 
-## HTTP API Equivalents
+## HTTP API 对应关系
 
-| CLI Command | HTTP Endpoint |
-|------------|---------------|
+| 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` |

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

@@ -1,37 +1,37 @@
-# Notification Commands Reference
+# 通知命令参考
 
-## Overview
+## 概述
 
-Loom provides a built-in notification system for persistent server-side notifications. Notifications are user-scoped and support CRUD operations via both HTTP API and CLI.
+Loom 提供内置通知系统，用于持久化的服务端通知。通知按用户作用域隔离，支持通过 HTTP API 和 CLI 进行 CRUD 操作。
 
-## CLI Commands
+## CLI 命令
 
-### List notifications
+### 列出通知
 ```bash
 loom notification list [--unread] [--limit 20] [--offset 0] --token <TOKEN>
 ```
 
-### Mark as read
+### 标记为已读
 ```bash
 loom notification read <id> --token <TOKEN>
 ```
 
-### Mark all as read
+### 全部标记为已读
 ```bash
 loom notification read-all --token <TOKEN>
 ```
 
-### Delete notification
+### 删除通知
 ```bash
 loom notification delete <id> --token <TOKEN>
 ```
 
-### Clear all notifications
+### 清空所有通知
 ```bash
 loom notification clear --token <TOKEN>
 ```
 
-### Send notification (admin only)
+### 发送通知（仅管理员）
 ```bash
 loom notification send --userId <userId> --type <type> --title <title> [--description DESC] --token <TOKEN>
 ```
@@ -40,30 +40,30 @@ loom notification send --userId <userId> --type <type> --title <title> [--descri
 
 | Method | Path | Auth | Permission | Description |
 |--------|------|------|------------|-------------|
-| GET | `/api/v1/notifications` | Required | Own only | List (paginated) |
-| GET | `/api/v1/notifications/unread-count` | Required | Own only | Unread count |
-| PUT | `/api/v1/notifications/:id/read` | Required | Own only | Mark read |
-| PUT | `/api/v1/notifications/read-all` | Required | Own only | Mark all read |
-| DELETE | `/api/v1/notifications/:id` | Required | Own only | Delete single |
-| DELETE | `/api/v1/notifications` | Required | Own only | Clear all |
-| POST | `/api/v1/notifications` | Required | Admin | Create notification |
+| 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 | 创建通知 |
 
-## Notification Types
+## 通知类型
 
-- `success` — Green, operation completed successfully
-- `error` — Red, operation failed
-- `warning` — Orange, attention needed
-- `info` — Blue, informational
+- `success` — 绿色，操作成功完成
+- `error` — 红色，操作失败
+- `warning` — 橙色，需要关注
+- `info` — 蓝色，信息提示
 
-## Source Types
+## 来源类型
 
-- `system` — Generated by Loom framework
-- `event` — Generated by EventBus subscription
-- `cli` — Created via CLI command
+- `system` — 由 Loom 框架生成
+- `event` — 由 EventBus 订阅生成
+- `cli` — 通过 CLI 命令创建
 
-## EventBus notify Handler
+## EventBus notify 处理器
 
-Configure automatic notification generation from events in `loom.config.ts`:
+在 `loom.config.ts` 中配置事件自动生成通知：
 
 ```typescript
 export default defineConfig({
@@ -92,32 +92,32 @@ export default defineConfig({
 });
 ```
 
-### Config Options
+### 配置选项
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `type` | `'success' \| 'error' \| 'warning' \| 'info'` | Yes | Notification severity |
-| `title` | `string` | Yes | Notification title (supports `{{var}}` interpolation) |
-| `description` | `string` | No | Notification body (supports `{{var}}` interpolation) |
-| `broadcastAll` | `boolean` | No | Broadcast to all users when event has no userId (default: false) |
+| `type` | `'success' \| 'error' \| 'warning' \| 'info'` | Yes | 通知严重级别 |
+| `title` | `string` | Yes | 通知标题（支持 `{{var}}` 插值） |
+| `description` | `string` | No | 通知正文（支持 `{{var}}` 插值） |
+| `broadcastAll` | `boolean` | No | 当事件无 userId 时广播给所有用户（默认：false） |
 
-### Interpolation
+### 插值
 
-Title and description support `{{var}}` interpolation from event payload:
-- `{{id}}` — Record ID
-- `{{model}}` — Model name
-- Any field from the event payload
+标题和描述支持从事件载荷中提取 `{{var}}` 插值：
+- `{{id}}` — 记录 ID
+- `{{model}}` — 模型名称
+- 事件载荷中的任意字段
 
-Missing variables are replaced with empty string.
+缺失的变量将被替换为空字符串。
 
-### Behavior
+### 行为规则
 
-- If event has `userId`: notification sent to that user only
-- If event has no `userId` and `broadcastAll: true`: sent to all users (capped at 100)
-- If event has no `userId` and `broadcastAll: false` (default): notification is skipped
+- 若事件包含 `userId`：仅发送给该用户
+- 若事件无 `userId` 且 `broadcastAll: true`：发送给所有用户（上限 100）
+- 若事件无 `userId` 且 `broadcastAll: false`（默认）：跳过该通知
 
-## Permissions
+## 权限
 
-- Users can only read/modify their own notifications
-- Only admin users can create notifications for other users via POST API or `loom notification send`
-- Notifications are auto-pruned after 30 days or when exceeding 500 items
+- 用户只能读取/修改自己的通知
+- 仅管理员可通过 POST API 或 `loom notification send` 为其他用户创建通知
+- 通知在 30 天后或超过 500 条时自动清理