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

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

@@ -0,0 +1,420 @@
+# Process 构建指南
+
+## 目的
+
+本指南帮助 AI 助手为用户创建 Process。当用户说"我想自动化 X"或"每天运行 Y"时，使用本指南构建流程定义。
+
+## 轻量模式 vs 完整模式选择
+
+### 使用轻量模式（`--prompt`）的场景：
+- 单一、简单的任务
+- 不需要引用文件
+- 提示词几句话就能描述清楚
+- 不需要指标仪表盘
+
+### 使用完整模式（`--process`）的场景：
+- 多步骤工作流，包含判断节点
+- 需要参考文档（API 文档、数据模型、样式指南）
+- 需要指标仪表盘
+- 流程可能随时间演进（Evolution 章节）
+
+## 逐步创建
+
+### 1. 分析需求
+
+明确：
+- **做什么** — 流程应该执行什么操作
+- **何时运行** — 定时调度还是事件触发
+- **谁负责** — 服务令牌对应的用户名（owner）
+- **用哪个模型** — 使用 `loom model list` 查看可用模型；简单任务用快速模型，复杂推理用最大模型；省略则使用全局默认
+- **复杂度** — 轻量还是完整
+
+### 2. 选择触发方式
+
+| 需求 | 使用 | 示例 |
+|------|-----|------|
+| 定时调度 | `--cron` | `0 9 * * 1-5`（工作日每天9点） |
+| 数据变更时 | `--subscribe` | `data:create:tasks` |
+| 用户操作时 | `--subscribe` | `user:created` |
+| 外部数据源 | `--source` | `--source "bash feeders/my-feeder.sh"` |
+| 仅手动触发 | 都不用 | 直接 `loom process run` |
+
+### 3. 创建流程
+
+轻量模式：
+```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 \
+  --model "claude-sonnet-4-6"
+```
+
+完整模式：
+```bash
+# 步骤 1：生成脚手架
+loom process generate weekly-report --description "Weekly analytics report"
+
+# 步骤 2：编辑 PROCESS.md，填写详细流程
+# （AI 应编写 PROCESS.md 内容）
+
+# 步骤 3：按需添加引用文件
+# 如果流程需要额外上下文，创建 references 目录
+# 并添加 AI 代理执行时需要的文件：
+mkdir -p .loom/processes/weekly-report/references
+# 然后添加引用文件，例如：
+#   - Skill 引用（CLI 命令用法、API 文档）
+#   - 领域知识（数据模型、业务规则）
+#   - 脚本或工具（数据转换、查询模板）
+# 仅在确实需要引用文件时才创建该目录。
+# 无需额外上下文时跳过此步骤。
+
+# 步骤 4：注册流程
+loom process add --name "weekly-report" \
+  --cron "0 9 * * 1" \
+  --process "weekly-report" \
+  --owner admin
+
+# 步骤 5：初始化指标视图配置（如果 PROCESS.md 中有 ## Metrics 章节才需要）
+# 根据 ## Metrics 章节设计视图配置（见下方"初始化指标可视化"）
+# 然后使用 metrics-set-view-config 写入：
+loom process metrics-set-view-config weekly-report --config @./view-config.json
+```
+
+### 事件触发 + Feeder 数据源
+
+当流程需要持久数据源（如钉钉消息、Webhook）时，使用 `--source` 声明 Feeder 脚本：
+
+```bash
+# 步骤 1：生成脚手架（如果是完整模式）
+loom process generate ingest --description "AI semantic router for incoming messages"
+
+# 步骤 2：编辑 PROCESS.md，编写路由逻辑
+# ...
+
+# 步骤 3：注册时指定 Feeder 数据源
+loom process add --name "ingest" \
+  --subscribe "dingtalk:mention" \
+  --source "bash examples/feeders/dingtalk-mention.sh" \
+  --process "ingest" \
+  --owner admin
+```
+
+**何时使用 `--source`：**
+- 流程需要持久的外部数据源（钉钉、Git Webhook、扫描器等）
+- Feeder 应随 Loom 实例的运行持续运行
+- 需要 Feeder 的自动重启和退避机制
+
+Feeder 运行时行为（`--source` 标志、生命周期管理、自动重启）详见 **`process.md` → Source (Feeder)**。Feeder 脚本开发规范（保活结构、退出码、事件格式、钉钉集成）详见 **`feeder.md`**。
+
+### 4. 验证
+
+```bash
+loom process status <name>
+loom process run <name>  # 手动测试
+loom process logs <name>  # 查看结果
+```
+
+## PROCESS.md 最佳实践
+
+### 结构
+
+```markdown
+# Process: <name>
+
+## Description
+此流程的功能及目的。
+
+## Trigger
+运行时机和触发条件。
+
+## Flow
+逐步指令：
+1. 从 <model> 读取数据
+2. 分析 <something>
+3. 将结果写入 <model>
+4. 通过 `loom notification send` 发送执行结果通知
+
+## Decision Points
+AI 应做出的关键判断：
+- 如果 X，执行 Y
+- 如果 Z，跳到步骤 N
+
+## Metrics
+如何衡量成功：
+- 执行时间 < N 秒
+- 错误率 < X%
+- 输出质量：<标准>
+
+## Evolution
+此流程应如何改进：
+- 运行 N 次后，回顾并优化提示词
+- 追踪常见错误并添加处理逻辑
+
+## References
+_列出 `references/` 目录中支持此流程的文件：_
+- _Skill 引用（如 CLI 命令用法、API 文档）_
+- _领域知识（如数据模型、业务规则）_
+- _脚本或工具（如数据转换、查询模板）_
+_仅在需要时才创建 `references/` 目录并添加文件。_
+```
+
+### 技巧
+- Flow 步骤要具体 — AI 会严格按字面执行
+- 包含数据模型名称和字段名称
+- 引用 CLI 命令：`loom data list <model>`、`loom data create <model>`
+- 数据操作使用 `loom data` 命令，而非直接文件 I/O
+- 在 Decision Points 中包含错误处理
+- 在 Flow 末尾添加通知步骤，将执行结果发送给自己：`loom notification send --userId <owner> --type success --title "Process completed" --description "Summary of results" --token $LOOM_TOKEN`
+- 如果流程需要强推理能力，创建时通过 `--model` 指定最大级别模型。简单数据聚合任务使用快速模型即可。
+
+## 指标定义
+
+在 PROCESS.md 中定义 `## Metrics` 时，遵循以下指南以便系统正确追踪和可视化：
+
+### 格式
+
+每个指标应包含：
+- **名称**：清晰简洁的标识符（如"错题 review 率"）
+- **含义**：该指标衡量什么以及为什么重要
+- **方向**：指标应增大、减小还是趋近目标值
+  - `increasing` = 越高越好（如成功率）
+  - `decreasing` = 越低越好（如错误数）
+  - `target` = 应趋近特定值（如 100% 覆盖率）
+- **目标值**（可选）：目标数值
+- **单位**（可选）：度量单位（如"%"、"条"、"次"）
+- **图表**（可选）：建议的可视化图表类型
+
+### 示例
+
+```markdown
+## Metrics
+
+- **错题 review 率**: 每次触发后，是否成功将错题写入 review_plans。方向：趋近目标值。目标：100%。单位：%。图表：gauge。
+- **错题重复出现率**: 统计相同错误模式的错题数量趋势。方向：越低越好。单位：条。图表：line。
+```
+
+### 初始化指标可视化
+
+使用 `--process` 注册完整流程后，必须初始化指标视图配置，以便流程管理页面能为每个指标渲染图表。这是一个两步过程：
+
+#### 步骤 1：根据 ## Metrics 设计视图配置
+
+分析 `## Metrics` 章节中的每个指标，生成 `ProcessMetricsViewConfig` JSON。配置包含两部分：
+
+- **`metrics[]`**：指标卡片定义（显示数值 + 趋势 + 目标）
+- **`charts[]`**：G2 v5 图表规格（每个指标一个独立图表，通过 `metricName` 过滤）
+
+**ProcessMetricsViewConfig Schema：**
+
+```typescript
+{
+  version: 1,
+  metrics: ProcessMetricView[],        // 指标卡片定义
+  charts: ProcessMetricChartSpec[]     // 带指标绑定的图表规格
+}
+
+// ProcessMetricView:
+{
+  metricName: string;                   // 必须与 metrics-report 中使用的名称完全一致
+  title: LocaleString;                  // 卡片显示标题（i18n）
+  description?: LocaleString;           // 可选的工具提示描述（i18n）
+  chartType: string;                    // 'line' | 'bar' | 'area' | 'gauge' | 'number'
+  direction?: 'increasing' | 'decreasing' | 'target';
+  target?: number;                      // 目标值（显示在卡片上）
+  unit?: string;                        // 单位标签（如 "%"、"条"、"次"）
+}
+
+// ProcessMetricChartSpec:
+{
+  metricName?: string;                  // 按此指标名称过滤快照数据
+  title?: LocaleString;                 // 图表标题（i18n）
+  type: string;                         // G2 图表类型: 'line' | 'interval' | 'area' | 'cell'
+  encode?: Record<string, unknown>;     // G2 encode 配置
+  scale?: Record<string, unknown>;      // G2 scale 配置
+  coordinate?: Record<string, unknown>; // G2 coordinate 配置
+  transform?: Record<string, unknown>[];// G2 transform 配置
+  style?: Record<string, unknown>;      // G2 style 配置
+  legend?: Record<string, unknown> | boolean;
+  labels?: Record<string, unknown>[];
+  interval?: 'minute' | 'hour' | 'day' | 'week' | 'month'; // 时间戳字段的日期截断
+  aggregate?: 'count' | 'sum' | 'avg'; // 设置 interval 时的聚合函数（默认: 'avg'）
+}
+
+// LocaleString 可以是纯字符串或 { "zh-CN": "...", "en-US": "..." }
+type LocaleString = string | { "zh-CN": string; "en-US": string };
+```
+
+**图表类型选择指南：**
+
+| 指标方向 + 单位 | chartType | 是否有图表？ | 原因 |
+|----------------|-----------|------------|------|
+| `target` + `%` 单位 | `gauge` | 无（仅卡片） | 百分比目标 → 卡片显示当前值与目标值 |
+| `target` + 非 `%` 单位 | `number` | 无（仅卡片） | 数值目标 → 卡片已足够 |
+| `increasing` / `decreasing` + `%` | `line` | 有 | 追踪时间趋势 |
+| `increasing` / `decreasing` + 计数单位 | `bar` | 有 | 跨运行对比 |
+
+**图表规格设计规则：**
+
+1. **每个指标独立一个图表** — 绝不在一个图表中混合不同指标。不同指标有不同单位和量级，合并会导致图表不可读。
+2. **每个图表必须包含 `metricName`** — 前端使用此字段为该特定指标过滤 `metricSnapshots`。缺少此字段会导致所有数据混合。
+3. **图表数据字段**引用 `ProcessMetricSnapshot` 属性：`timestamp`、`value`、`metricName`、`dimensions`、`target`、`unit`。前端将过滤后的快照作为 `data` 注入。
+4. **为每个图表添加标题** — 添加 `title` 字段（使用 LocaleString 格式支持 i18n）。
+
+**按图表类型的规格模板：**
+
+```jsonc
+// 折线图 — 时间序列趋势（带日期聚合）
+{
+  "metricName": "错题重复出现率",
+  "title": { "zh-CN": "错题重复出现率趋势", "en-US": "Repeat Error Rate Trend" },
+  "type": "line",
+  "interval": "month",
+  "aggregate": "avg",
+  "encode": { "x": "name", "y": "value" },
+  "scale": { "y": { "nice": true } }
+}
+
+// 柱状图 — 每次运行对比
+{
+  "metricName": "新增错题数",
+  "title": { "zh-CN": "每次执行新增错题数", "en-US": "New Errors Per Run" },
+  "type": "interval",
+  "encode": { "x": "runId", "y": "value" },
+  "scale": { "y": { "nice": true } }
+}
+
+// 面积图 — 累计趋势（带日期聚合）
+{
+  "metricName": "review 完成数",
+  "title": { "zh-CN": "Review 完成趋势", "en-US": "Review Completion Trend" },
+  "type": "area",
+  "interval": "month",
+  "aggregate": "avg",
+  "encode": { "x": "name", "y": "value" },
+  "scale": { "y": { "nice": true } }
+}
+```
+
+5. **gauge 和 number 类型不需要图表条目** — 它们仅作为指标卡片显示（展示最新值、趋势箭头和目标值）。
+6. **设置 `interval` 时**，前端自动按截断日期（分钟/小时/天/周/月）聚合快照。interval 模式图表使用 `encode: { "x": "name", "y": "value" }`。省略 `interval` 时，原始快照直接传递给 G2（无聚合的时间序列使用 `encode: { "x": "timestamp", "y": "value" }`）。
+
+#### 步骤 2：写入视图配置
+
+使用 `loom process metrics-set-view-config` 写入配置：
+
+```bash
+# 从 JSON 字符串写入
+loom process metrics-set-view-config <name> --config '{
+  "version": 1,
+  "metrics": [
+    {
+      "metricName": "错题 review 率",
+      "title": { "zh-CN": "错题 Review 率", "en-US": "Review Rate" },
+      "description": { "zh-CN": "每次触发后成功写入 review_plans 的比率", "en-US": "Ratio of successful review plan creation after trigger" },
+      "chartType": "gauge",
+      "direction": "target",
+      "target": 1,
+      "unit": "%"
+    },
+    {
+      "metricName": "错题重复出现率",
+      "title": { "zh-CN": "错题重复出现率", "en-US": "Repeat Error Rate" },
+      "description": { "zh-CN": "相同错误模式的错题数量趋势", "en-US": "Trend of repeated error patterns" },
+      "chartType": "line",
+      "direction": "decreasing",
+      "unit": "条"
+    }
+  ],
+  "charts": [
+    {
+      "metricName": "错题重复出现率",
+      "title": { "zh-CN": "错题重复出现率趋势", "en-US": "Repeat Error Rate Trend" },
+      "type": "line",
+      "interval": "month",
+      "aggregate": "avg",
+      "encode": { "x": "name", "y": "value" },
+      "scale": { "y": { "nice": true } }
+    }
+  ]
+}'
+
+# 或从文件读取
+loom process metrics-set-view-config <name> --config @./view-config.json
+```
+
+注意：使用此命令时服务器必须正在运行（它会调用 API）。
+
+### 完整示例 — error-pattern-analysis 流程
+
+PROCESS.md `## Metrics` 章节：
+
+```markdown
+## Metrics
+
+- **错题 review 率**: 每次触发后，是否成功将错题写入 review_plans。方向：趋近目标值。目标：100%。单位：%。图表：gauge。
+- **错题重复出现率**: 统计相同错误模式的错题数量趋势。方向：越低越好。单位：条。图表：line。
+```
+
+对应的视图配置：
+
+```json
+{
+  "version": 1,
+  "metrics": [
+    {
+      "metricName": "错题 review 率",
+      "title": { "zh-CN": "错题 Review 率", "en-US": "Review Rate" },
+      "description": { "zh-CN": "每次触发后成功写入 review_plans 的比率", "en-US": "Ratio of successful review plan creation after trigger" },
+      "chartType": "gauge",
+      "direction": "target",
+      "target": 1,
+      "unit": "%"
+    },
+    {
+      "metricName": "错题重复出现率",
+      "title": { "zh-CN": "错题重复出现率", "en-US": "Repeat Error Rate" },
+      "description": { "zh-CN": "相同错误模式的错题数量趋势", "en-US": "Trend of repeated error patterns" },
+      "chartType": "line",
+      "direction": "decreasing",
+      "unit": "条"
+    }
+  ],
+  "charts": [
+    {
+      "metricName": "错题重复出现率",
+      "title": { "zh-CN": "错题重复出现率趋势", "en-US": "Repeat Error Rate Trend" },
+      "type": "line",
+      "interval": "month",
+      "aggregate": "avg",
+      "encode": { "x": "name", "y": "value" },
+      "scale": { "y": { "nice": true } }
+    }
+  ]
+}
+```
+
+注意："错题 review 率"的 `chartType: "gauge"` 仅渲染为指标卡片（最新值 + 目标值 + 趋势）。它在 `charts[]` 中不需要图表条目。
+
+### 执行期间上报指标
+
+当流程的 PROCESS.md 包含 `## Metrics` 章节时，系统会自动在 AI 提示词中注入指标协议（Metrics Protocol）。代理在计算每个指标的值后，必须调用 `loom process metrics-report`：
+
+```bash
+loom process metrics-report <process-name> \
+  --metric-name "错题 review 率" \
+  --value 0.95 \
+  --target 1 \
+  --unit "%" \
+  --run-id $LOOM_RUN_ID
+```
+
+关键要点：
+- `--metric-name` 必须与视图配置中使用的名称完全一致（包括 `metrics[]` 条目中的名称）
+- `--run-id` 通过 `$LOOM_RUN_ID` 环境变量自动获取
+- `--dimensions` 可选，用于维度拆分（如 `--dimensions '{"subject":"数学"}'`）
+- 每个指标计算完成后立即上报，不要在最后批量上报
+
+## 快速参考
+
+常用 Cron 和 Event 模式表见 **`process.md` → Trigger Types**。