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

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

@@ -0,0 +1,458 @@
+# Process CLI 参考
+
+> **配置 Schema 参考**：过程定义的声明式配置 (`processes.definitions`) 见 Loom Skill (`references/data-model.md` → ProcessesConfig)。
+
+## 概述
+
+Process 是 Loom 的自动化引擎，用于调度和事件驱动的 AI 任务。每个 Process 拥有触发器（cron、event 或手动），并通过 Claude Code 引擎执行 AI 提示词。
+
+## 命令
+
+### `loom process add`
+
+创建新的 Process 定义。
+
+```bash
+# 轻量模式（内联提示词）
+loom process add --name "daily-summary" \
+  --cron "0 9 * * 1-5" \
+  --prompt "Summarize yesterday's data and email the team" \
+  --owner admin
+
+# 完整模式（使用 PROCESS.md）
+loom process add --name "weekly-report" \
+  --cron "0 9 * * 1" \
+  --process "weekly-report" \
+  --owner admin \
+  --description "Weekly analytics report"
+
+# 事件触发模式（带订阅）
+loom process add --name "on-task-create" \
+  --subscribe "data:create:tasks" \
+  --prompt "Analyze the new task and suggest priorities" \
+  --owner admin
+
+# 带指标配置
+loom process add --name "health-check" \
+  --cron "*/30 * * * *" \
+  --prompt "Check system health" \
+  --metrics-config ./metrics-config.json \
+  --owner bot
+
+# 指定模型
+loom process add --name "complex-analysis" \
+  --cron "0 2 * * *" \
+  --prompt "Analyze daily data and generate insights" \
+  --owner admin \
+  --model "claude-opus-4-7"
+```
+
+**选项：**
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--name` | 是 | Process 名称（^[a-zA-Z][a-zA-Z0-9_-]*$） |
+| `--prompt` | 二选一 | 轻量模式的内联提示词 |
+| `--process` | 二选一 | 完整模式名称（需存在 .loom/processes/{name}/PROCESS.md） |
+| `--cron` | 否 | Cron 调度表达式 |
+| `--cron-timezone` | 否 | Cron 时区（如 "America/New_York"） |
+| `--subscribe` | 否 | 订阅的 EventBus 模式（如 "data:create:tasks"） |
+| `--event-filter` | 否 | 事件载荷字段的 JSON 过滤条件（仅与 --subscribe 配合使用） |
+| `--event-debounce` | 否 | 防抖窗口，单位毫秒（默认：0，即无防抖，仅与 --subscribe 配合使用） |
+| `--description` | 否 | Process 描述 |
+| `--owner` | 否 | 所有者用户名（默认：取自 processes 配置） |
+| `--owner-token` | 否 | 直接传入 JWT 令牌（绕过运行时解析） |
+| `--metrics-config` | 否 | DashboardWidget 指标配置 JSON 文件路径 |
+| `--source` | 否 | Feeder 脚本命令，可重复指定（如 --source "bash examples/feeders/ingest.sh" --source "bash feeders/notify.sh"）。多个时自动编号 1、2、3...，对应生命周期名 {process}-feeder-1。必须同时指定 --subscribe |
+| `--model` | 否 | 此 Process 使用的 AI 模型名称（须在模型管理中存在；使用 `loom model list` 查看可用模型） |
+| `--token` | 否 | 认证令牌（或设置 LOOM_TOKEN） |
+| `--server` | 否 | 服务器 URL（或设置 LOOM_SERVER，默认：http://localhost:3000） |
+
+### `loom process list`
+
+列出所有 Process。
+
+```bash
+loom process list
+loom process list --status active
+loom process list --status paused
+```
+
+### `loom process status <name>`
+
+显示 Process 详细状态。
+
+```bash
+loom process status daily-summary
+```
+
+### `loom process run <name>`
+
+手动触发一次 Process 执行。
+
+```bash
+loom process run daily-summary
+loom process run on-task-create --payload '{"model":"tasks","id":"task_123"}'
+```
+
+### `loom process pause <name>`
+
+暂停 Process（停止触发器，手动执行仍可用）。
+
+```bash
+loom process pause daily-summary
+```
+
+### `loom process resume <name>`
+
+恢复已暂停的 Process。
+
+```bash
+loom process resume daily-summary
+```
+
+### `loom process update <name>`
+
+更新已有的 Process 定义。
+
+```bash
+loom process update daily-summary --cron "0 10 * * 1-5"
+loom process update on-task-create --prompt "Updated prompt text"
+loom process update daily-summary --description "Updated description" --cron "0 8 * * 1-5"
+
+# 添加事件订阅
+loom process update on-task-create --subscribe-add "data:update:tasks"
+loom process update on-task-create --subscribe-add "data:update:tasks" --subscribe-filter '{"status":"critical"}' --subscribe-debounce 2000
+
+# 按 ID 移除事件订阅
+loom process update on-task-create --subscribe-remove sub_1747301234_ab
+```
+
+**选项：**
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--cron` | 否 | 更新 Cron 调度表达式 |
+| `--cron-timezone` | 否 | 更新 Cron 时区 |
+| `--prompt` | 否 | 更新内联提示词 |
+| `--description` | 否 | 更新描述 |
+| `--model` | 否 | 更新 AI 模型名称（传入空字符串移除模型绑定） |
+| `--subscribe-add` | 否 | 要订阅的事件模式（创建 `handler: process` 订阅） |
+| `--subscribe-filter` | 否 | 事件载荷的 JSON 过滤条件（仅与 --subscribe-add 配合使用） |
+| `--subscribe-debounce` | 否 | 防抖窗口，单位毫秒（默认：0，即无防抖，仅与 --subscribe-add 配合使用） |
+| `--subscribe-remove` | 否 | 要移除的订阅 ID（使用 `loom event list` 查找 ID） |
+| `--token` | 否 | 认证令牌（或设置 LOOM_TOKEN） |
+| `--server` | 否 | 服务器 URL（或设置 LOOM_SERVER，默认：http://localhost:3000） |
+
+### `loom process remove <name>`
+
+移除 Process 定义。执行日志会保留。
+
+```bash
+loom process remove daily-summary
+```
+
+### `loom process logs <name> [runId]`
+
+查看执行日志。提供 `runId` 时显示单次运行的详情。
+
+```bash
+# 列出最近的日志
+loom process logs daily-summary
+loom process logs daily-summary --limit 50
+loom process logs daily-summary --offset 10
+
+# 查看特定运行
+loom process logs daily-summary run_abc123
+```
+
+### `loom process generate <name>`
+
+创建 PROCESS.md 脚手架目录（用于完整模式）。由 AI 调用，用户一般不直接使用。
+
+```bash
+loom process generate daily-report --description "Daily report generator"
+```
+
+### `loom process metrics-report <name>`
+
+上报业务指标快照。由 AI Agent 在 Process 执行期间调用。
+
+```bash
+# 基础上报
+loom process metrics-report my-process --metric-name "成功率" --value 0.95 --unit "%"
+
+# 带目标和维度
+loom process metrics-report my-process \
+  --metric-name "错题重复率" \
+  --value 3 \
+  --unit "条" \
+  --target 0 \
+  --dimensions '{"subject":"数学"}' \
+  --run-id $LOOM_RUN_ID
+```
+
+**选项：**
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--metric-name` | 是 | 指标的可读名称 |
+| `--value` | 是 | 数值型指标值 |
+| `--run-id` | 否 | 运行 ID（默认取 LOOM_RUN_ID 环境变量） |
+| `--timestamp` | 否 | ISO 时间戳（默认为当前时间） |
+| `--dimensions` | 否 | 维度标签，JSON 格式 |
+| `--target` | 否 | 目标值，用于显示目标线 |
+| `--unit` | 否 | 单位标签（如 "%"、"条"） |
+| `--token` | 否 | 认证令牌（或设置 LOOM_TOKEN） |
+| `--server` | 否 | 服务器 URL（或设置 LOOM_SERVER） |
+
+### `loom process metrics-set-view-config <name>`
+
+设置或更新业务指标视图配置。定义 Process 指标在 Process 管理页面的可视化方式——每个指标拥有独立卡片和可选图表。
+
+**何时使用：** 创建含 `## Metrics` 章节的完整 Process 后，设计视图配置并通过此命令写入。
+
+```bash
+# 从 JSON 字符串
+loom process metrics-set-view-config my-process --config '{"version":1,"metrics":[{"metricName":"成功率","title":"成功率","chartType":"gauge","direction":"target","target":1,"unit":"%"}],"charts":[]}'
+
+# 从文件（推荐用于复杂配置）
+loom process metrics-set-view-config my-process --config @./view-config.json
+```
+
+**ProcessMetricsViewConfig** 完整 Schema、chart 设计规则和示例见 **`process-builder.md` → Initializing Metrics Visualization**。
+
+**选项：**
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--config` | 是 | 视图配置 JSON（使用 `@file` 从文件读取） |
+| `--token` | 否 | 认证令牌（或设置 LOOM_TOKEN） |
+| `--server` | 否 | 服务器 URL（或设置 LOOM_SERVER） |
+
+### `loom process export <name>`
+
+导出 Process 定义为 JSON。
+
+```bash
+loom process export daily-summary
+```
+
+## Process 模式
+
+### 轻量模式（`--prompt`）
+
+- 内联提示词，无需 PROCESS.md 文件
+- 适合简单的单步自动化
+- 快速创建和修改
+
+### 完整模式（`--process`）
+
+- 在 `.loom/processes/{name}/PROCESS.md` 拥有 PROCESS.md
+- 可在 `.loom/processes/{name}/references/` 中添加参考文件
+- 适合复杂的多步骤工作流
+- 支持 Metrics 和 Evolution 章节
+
+## 触发器类型
+
+### Cron
+标准 5 字段 Cron 表达式：`分钟 小时 日 月 星期`
+
+| 模式 | 调度 |
+|------|------|
+| `*/5 * * * *` | 每 5 分钟 |
+| `*/15 * * * *` | 每 15 分钟 |
+| `0 * * * *` | 每小时 |
+| `0 9 * * *` | 每天 9 点 |
+| `0 9 * * 1-5` | 工作日 9 点 |
+| `0 9 * * 1` | 每周一 9 点 |
+| `0 0 1 * *` | 每月 1 号 |
+
+### Event
+EventBus 模式匹配：`{category}:{action}:{target}`
+
+| 模式 | 触发时机 |
+|------|----------|
+| `data:create:<model>` | 新记录创建时 |
+| `data:update:<model>` | 记录更新时 |
+| `data:delete:<model>` | 记录删除时 |
+| `user:created` | 新用户注册时 |
+| `process:completed:<name>` | 另一个 Process 完成时 |
+
+完整的事件模式文档见 **`events.md`**。
+
+### Source（Feeder）
+当 Process 需要持久化的外部数据源时，使用 `--source` 声明 Feeder 脚本。脚本在 Loom 实例就绪时启动，实例关闭时停止。`--source` 可重复指定以声明多个 Feeder。
+
+```bash
+# 单个 Feeder
+loom process add --name ingest \
+  --subscribe "dingtalk:mention" \
+  --source "bash examples/feeders/dingtalk-mention.sh" \
+  --process "ingest" \
+  --owner admin
+
+# 多个 Feeder（自动编号 1、2，生命周期名 ingest-feeder-1、ingest-feeder-2）
+loom process add --name monitor \
+  --subscribe "data:update:tasks" \
+  --source "bash feeders/dingtalk-mention.sh" \
+  --source "bash feeders/webhook-forward.sh" \
+  --prompt "Process incoming events" \
+  --owner admin
+```
+
+此命令一步完成：
+1. 注册带 `sources` 字段的 Process 定义
+2. 通过 LifecycleManager 自动启动 Feeder
+3. 若事件订阅尚不存在则自动注册
+
+使用 `loom process remove` 移除 Process 时，如果没有其他 Process 订阅同一事件模式，Feeder 会被自动清理。
+
+**Feeder 脚本约定：**
+- 捕获 SIGTERM/SIGINT 并以退出码 0 退出，实现优雅关闭
+- 使用 `$LOOM_SERVER_URL` 而非硬编码 URL
+- 退出码 0 = 正常退出（不重启）；非零 = 崩溃（自动重启，带退避策略）
+- 每个名称仅允许一个脚本实例
+
+**生命周期事件模式：**
+| 模式 | 触发时机 |
+|------|----------|
+| `lifecycle:started:{name}` | Feeder 脚本启动时 |
+| `lifecycle:failed:{name}` | Feeder 脚本异常退出时 |
+| `lifecycle:circuit_open:{name}` | Feeder 达到最大重启次数时 |
+| `lifecycle:restart:{name}` | Feeder 带退避策略重启时 |
+
+### 手动触发
+`loom process run <name>` —— 立即执行，即使 Process 已暂停也有效。
+
+## 服务令牌认证
+
+启用认证后，Process 需要服务令牌才能运行：
+- `--owner <username>`：通过 UserStore 运行时解析（推荐）
+- `--owner-token <jwt>`：直接传入 JWT 令牌（安全性较低，存储在 loom.config.ts 中）
+
+## 执行模型
+
+1. 触发器触发 → 任务入队
+2. 队列有空闲槽位 → Process 开始执行
+3. 构建 AI 提示词（PROCESS.md + 参考文件 + 事件上下文 + 指标协议）
+4. Claude Code 引擎带超时执行，注入环境变量：LOOM_SERVER、LOOM_PROCESS_NAME、LOOM_RUN_ID
+5. Agent 可在执行期间调用 `loom process metrics-report` 上报业务指标
+6. 执行结果记录到 `.loom/processes/{name}/logs/{runId}.json`
+7. 指标快照存储到 `.loom/processes/{name}/metrics.jsonl`
+8. 发出事件：`process:started`、`process:completed` 或 `process:failed`
+
+## 并发控制
+
+由 loom.config.ts 中的 `processes.maxConcurrent` 控制（默认：5）。达到上限时，新触发器排队等待空闲槽位。
+
+## 防抖
+
+事件触发器带有 `eventDebounceMs`（默认：0ms，即无防抖）。设置防抖后，防抖窗口内的快速事件会被合并——仅触发一次执行，使用最后一条事件的载荷。
+
+## 事件订阅
+
+Process 通过事件订阅响应事件。两种绑定方式：
+
+1. **创建时绑定**：`loom process add --subscribe "pattern"` — 自动创建 `handler: 'process'` 订阅，适合一步到位
+2. **独立管理**：`loom event subscribe/unsubscribe/update/test` — 灵活管理 M:N 关系，支持所有 handler 类型
+
+```bash
+# 创建 Process 时同时绑定事件
+loom process add --name "on-task-create" \
+  --subscribe "data:create:tasks" \
+  --prompt "Analyze the new task" \
+  --owner admin
+
+# 给已有 Process 追加/移除订阅
+loom process update on-task-create --subscribe-add "data:update:tasks"
+loom process update on-task-create --subscribe-remove sub_1747301234_ab
+```
+
+完整的事件订阅命令、API 端点、handler 类型（process/webhook/log/notify）及声明式配置，见 **`events.md`**。
+
+> **重要**：订阅的 `pattern` 必须与 Feeder 脚本实际发出的事件名完全匹配。Feeder 通过 `POST /api/v1/events/emit` 发送事件时指定的 `pattern` 值，必须与 `--subscribe` 声明的模式一致，否则订阅不会触发。例如，`--subscribe "dingtalk:mention"` 要求 Feeder 脚本 emit 的事件 pattern 也是 `"dingtalk:mention"`。
+
+## 系统指标配置
+
+Process 内置执行统计指标（totalRuns、completedRuns、avgDurationMs 等），可通过 `--metrics-config` 配置 Dashboard 展示。这与 `metrics-report` 上报的**业务指标**是两套独立系统：
+
+| 系统 | 数据来源 | 配置方式 | 用途 |
+|------|----------|----------|------|
+| **系统指标**（本节） | 自动采集执行统计 | `--metrics-config` + DashboardWidget | 监控执行健康度 |
+| **业务指标** | AI 调用 `metrics-report` 上报 | `## Metrics` + `metrics-set-view-config` | 跟踪业务 KPI |
+
+业务指标的完整设计指南见 **`process-builder.md`**。
+
+### 指标配置
+
+创建 Process 时通过 `--metrics-config <path>` 指定 JSON 配置文件：
+
+```bash
+loom process add --name "health-check" \
+  --cron "*/30 * * * *" \
+  --prompt "Check system health" \
+  --metrics-config ./health-metrics.json \
+  --owner admin
+```
+
+### 示例：metrics-config.json
+
+```json
+[
+  {
+    "type": "stat",
+    "title": { "zh-CN": "成功率", "en-US": "Success Rate" },
+    "model": "__process_metrics",
+    "aggregate": "sum",
+    "field": "completedRuns",
+    "color": "#52c41a"
+  },
+  {
+    "type": "stat",
+    "title": { "zh-CN": "失败次数", "en-US": "Failures" },
+    "model": "__process_metrics",
+    "aggregate": "sum",
+    "field": "failedRuns",
+    "color": "#ff4d4f"
+  },
+  {
+    "type": "line",
+    "title": { "zh-CN": "执行趋势", "en-US": "Execution Trend" },
+    "model": "__process_metrics",
+    "aggregate": "sum",
+    "field": "totalRuns",
+    "groupBy": "date",
+    "dateInterval": "day"
+  }
+]
+```
+
+### 可用组件类型
+
+| Type | 说明 | 必填字段 |
+|------|------|----------|
+| `stat` | 单数值展示 | `title`、`model`、`aggregate`、`field` |
+| `line` | 折线图 | `title`、`model`、`aggregate`、`field`、`groupBy`、`dateInterval` |
+| `bar` | 柱状图 | `title`、`model`、`aggregate`、`field`、`groupBy` |
+| `pie` | 饼图 | `title`、`model`、`field`、`groupBy` |
+| `gauge` | 仪表盘 | `title`、`model`、`field`、`min`、`max` |
+| `table` | 表格视图 | `title`、`model`、`columns` |
+
+### 可用指标字段
+
+来自 `ProcessMetricsAggregate`：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `date` | string | 日期（YYYY-MM-DD） |
+| `totalRuns` | number | 总执行次数 |
+| `completedRuns` | number | 成功执行次数 |
+| `failedRuns` | number | 失败执行次数 |
+| `timeoutRuns` | number | 超时执行次数 |
+| `avgDurationMs` | number | 平均执行时长（毫秒） |
+| `lastRunAt` | string\|null | 最近执行时间戳 |
+| `lastStatus` | string\|null | 最近执行状态 |
+
+### API 端点
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/api/v1/processes/:name/metrics` | GET | 获取聚合指标数据 |
+| `/api/v1/processes/:name/metrics-config` | GET | 获取组件配置 |

package/builtin-skills/chart-visualization/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: chart-visualization
+description: 将数据可视化为图表。当用户需要生成柱状图、折线图、饼图、散点图、雷达图、桑基图、思维导图、流程图等图表时调用此技能，通过 curl 工具调用 AntV API 生成图表图片
+---
+
+请根据用户输入的内容，将数据可视化为图表。
+
+## 步骤
+1. 分析用户数据和需求，选择最合适的图表类型
+2. 构造符合规范的 JSON 请求体
+3. 使用 curl 工具调用 API 生成图表图片
+4. 将返回的图片 URL 以 Markdown 图片格式输出
+
+## 图表选择指南
+
+根据用户的数据特征和需求，选择最合适的图表类型：
+
+- **时间序列**：用 `line`（趋势）或 `area`（累计趋势）；两个不同量纲用 `dual-axes`
+- **比较类**：用 `bar`（横向分类对比）或 `column`（纵向分类对比）；频率分布用 `histogram`
+- **占比类**：用 `pie`（比例构成）或 `treemap`（层级占比）
+- **关系与流程**：用 `scatter`（相关性）、`sankey`（流向）或 `venn`（集合重叠）
+- **层级与树形**：用 `organization-chart` 或 `mind-map`
+- **专用类型**：
+  - `radar`：多维度对比
+  - `funnel`：流程阶段转化
+  - `liquid`：百分比/进度
+  - `word-cloud`：文本词频
+  - `boxplot` / `violin`：统计分布
+  - `network-graph`：复杂节点关系
+  - `fishbone-diagram`：因果分析
+  - `flow-diagram`：流程图
+  - `spreadsheet`：结构化数据表或透视表
+
+## API 接口
+
+POST https://antv-studio.alipay.com/api/gpt-vis
+
+请求体为 JSON，必须包含 `type` 和 `source: "chart-visualization-skills"` 字段。
+
+示例：
+```bash
+curl -X POST https://antv-studio.alipay.com/api/gpt-vis \
+  -H "Content-Type: application/json" \
+  -d '{"type":"line","source":"chart-visualization-skills","data":[{"time":"2025-01","value":100}],"title":"示例图表"}'
+```
+
+返回示例：
+```json
+{"success":true,"resultObj":"https://..."}
+```
+
+将 `resultObj` 中的 URL 以 Markdown 图片格式输出：`![图表](URL)`
+
+## 支持的图表类型
+
+| 分类 | 图表类型 |
+|------|---------|
+| 比较类 | 条形图(bar)、柱状图(column)、瀑布图(waterfall)、双轴图(dual-axes) |
+| 趋势类 | 面积图(area)、折线图(line)、散点图(scatter) |
+| 分布类 | 箱线图(boxplot)、直方图(histogram)、小提琴图(violin)、漏斗图(funnel) |
+| 占比类 | 饼图(pie)、水波图(liquid)、词云(word-cloud) |
+| 层级类 | 组织架构图(organization-chart)、思维导图(mind-map)、矩形树图(treemap)、桑基图(sankey) |
+| 关系类 | 关系图(network-graph)、韦恩图(venn) |
+| 流程类 | 流程图(flow-diagram)、鱼骨图(fishbone-diagram) |
+| 多维类 | 雷达图(radar) |
+| 表格类 | 表格/透视表(spreadsheet) |
+
+## 通用可选参数
+
+| 参数 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| theme | string | "default" | 主题："default" / "academy" / "dark" |
+| width | number | 600 | 图表宽度 |
+| height | number | 400 | 图表高度 |
+| title | string | "" | 图表标题 |
+| style.texture | string | "default" | 纹理："default" / "rough"（手绘风格） |
+
+带坐标轴的图表还支持：axisXTitle、axisYTitle。
+
+## 各图表 data 格式
+
+- **area / line**: `{time: string, value: number, group?: string}[]`，可选 stack: boolean
+- **bar**: `{category: string, value: number, group?: string}[]`，可选 group / stack (默认 stack: true)
+- **column**: `{category: string, value: number, group?: string}[]`，可选 group (默认 true) / stack
+- **scatter**: `{x: number, y: number, group?: string}[]`
+- **pie**: `{category: string, value: number}[]`，可选 innerRadius: number (0-1)
+- **radar**: `{name: string, value: number, group?: string}[]`
+- **funnel**: `{category: string, value: number}[]`
+- **waterfall**: `{category: string, value?: number, isTotal?: boolean, isIntermediateTotal?: boolean}[]`
+- **dual-axes**: categories: string[], series: {type: "column"|"line", data: number[], axisYTitle?: string}[]
+- **histogram**: `number[]`，可选 binNumber: number
+- **boxplot / violin**: `{category: string, value: number, group?: string}[]`
+- **liquid**: percent: number (0-1)，可选 shape: "circle"|"rect"|"pin"|"triangle"
+- **word-cloud**: `{text: string, value: number}[]`
+- **sankey**: `{source: string, target: string, value: number}[]`，可选 nodeAlign
+- **treemap**: `{name: string, value: number, children?: ...}[]` (最深 3 层)
+- **venn**: `{sets: string[], value: number, label?: string}[]`
+- **network-graph / flow-diagram**: `{nodes: {name: string}[], edges: {source: string, target: string, name?: string}[]}`
+- **fishbone-diagram / mind-map**: `{name: string, children?: ...}` (最深 3 层)
+- **organization-chart**: `{name: string, description?: string, children?: ...}` (最深 3 层)，可选 orient: "horizontal"|"vertical"
+- **spreadsheet**: `Record<string, string | number>[]`，可选 rows / columns / values（透视表字段）