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

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

@@ -1,44 +1,45 @@
-# Process CLI Reference
+# Process CLI 参考
 
-## Overview
+> **配置 Schema 参考**：过程定义的声明式配置 (`processes.definitions`) 见 Loom Skill (`references/data-model.md` → ProcessesConfig)。
 
-Process is Loom's automation engine for scheduling and event-driven AI tasks. Each process has triggers (cron, event, or manual) and executes AI prompts via the Claude Code engine.
+## 概述
 
-## Commands
+Process 是 Loom 的自动化引擎，用于调度和事件驱动的 AI 任务。每个 Process 拥有触发器（cron、event 或手动），并通过 Claude Code 引擎执行 AI 提示词。
+
+## 命令
 
 ### `loom process add`
 
-Create a new process definition.
+创建新的 Process 定义。
 
 ```bash
-# Lightweight process (inline prompt)
+# 轻量模式（内联提示词）
 loom process add --name "daily-summary" \
   --cron "0 9 * * 1-5" \
   --prompt "Summarize yesterday's data and email the team" \
   --owner admin
 
-# Full process (with PROCESS.md)
+# 完整模式（使用 PROCESS.md）
 loom process add --name "weekly-report" \
   --cron "0 9 * * 1" \
   --process "weekly-report" \
   --owner admin \
   --description "Weekly analytics report"
 
-# Event-triggered process
+# 事件触发模式（带订阅）
 loom process add --name "on-task-create" \
-  --on-event "data:create:tasks" \
+  --subscribe "data:create:tasks" \
   --prompt "Analyze the new task and suggest priorities" \
-  --owner admin \
-  --event-debounce 2000
+  --owner admin
 
-# With metrics config
+# 带指标配置
 loom process add --name "health-check" \
   --cron "*/30 * * * *" \
   --prompt "Check system health" \
   --metrics-config ./metrics-config.json \
   --owner bot
 
-# With a specific model
+# 指定模型
 loom process add --name "complex-analysis" \
   --cron "0 2 * * *" \
   --prompt "Analyze daily data and generate insights" \
@@ -46,29 +47,29 @@ loom process add --name "complex-analysis" \
   --model "claude-opus-4-7"
 ```
 
-**Options:**
-| Flag | Required | Description |
-|------|----------|-------------|
-| `--name` | Yes | Process name (^[a-zA-Z][a-zA-Z0-9_-]*$) |
-| `--prompt` | One of | Inline prompt for lightweight process |
-| `--process` | One of | Full process name (expects .loom/processes/{name}/PROCESS.md) |
-| `--cron` | No | Cron schedule expression |
-| `--cron-timezone` | No | Timezone for cron (e.g., "America/New_York") |
-| `--on-event` | No | EventBus pattern (e.g., "data:create:tasks") |
-| `--event-filter` | No | JSON filter on event payload fields |
-| `--event-debounce` | No | Debounce window in ms (default: 1000) |
-| `--description` | No | Process description |
-| `--owner` | No | Owner username (default: from processes config) |
-| `--owner-token` | No | Direct JWT token (bypasses runtime resolution) |
-| `--metrics-config` | No | Path to metrics DashboardWidget config JSON |
-| `--source` | No | Feeder script command (auto-registers lifecycle script + event subscription) |
-| `--model` | No | AI model name for this process (must exist in model management; use `loom model list` to see available models) |
-| `--token` | No | Auth token (or set LOOM_TOKEN) |
-| `--server` | No | Server URL (or set LOOM_SERVER, default: http://localhost:3000) |
+**选项：**
+| 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` | 否 | 防抖窗口，单位毫秒（默认：1000，仅与 --subscribe 配合使用） |
+| `--description` | 否 | Process 描述 |
+| `--owner` | 否 | 所有者用户名（默认：取自 processes 配置） |
+| `--owner-token` | 否 | 直接传入 JWT 令牌（绕过运行时解析） |
+| `--metrics-config` | 否 | DashboardWidget 指标配置 JSON 文件路径 |
+| `--source` | 否 | Feeder 脚本命令（自动注册生命周期脚本 + 事件订阅） |
+| `--model` | 否 | 此 Process 使用的 AI 模型名称（须在模型管理中存在；使用 `loom model list` 查看可用模型） |
+| `--token` | 否 | 认证令牌（或设置 LOOM_TOKEN） |
+| `--server` | 否 | 服务器 URL（或设置 LOOM_SERVER，默认：http://localhost:3000） |
 
 ### `loom process list`
 
-List all processes.
+列出所有 Process。
 
 ```bash
 loom process list
@@ -78,7 +79,7 @@ loom process list --status paused
 
 ### `loom process status <name>`
 
-Show detailed process status.
+显示 Process 详细状态。
 
 ```bash
 loom process status daily-summary
@@ -86,7 +87,7 @@ loom process status daily-summary
 
 ### `loom process run <name>`
 
-Manually trigger a process execution.
+手动触发一次 Process 执行。
 
 ```bash
 loom process run daily-summary
@@ -95,7 +96,7 @@ loom process run on-task-create --payload '{"model":"tasks","id":"task_123"}'
 
 ### `loom process pause <name>`
 
-Pause a process (stops triggers, manual run still works).
+暂停 Process（停止触发器，手动执行仍可用）。
 
 ```bash
 loom process pause daily-summary
@@ -103,7 +104,7 @@ loom process pause daily-summary
 
 ### `loom process resume <name>`
 
-Resume a paused process.
+恢复已暂停的 Process。
 
 ```bash
 loom process resume daily-summary
@@ -111,31 +112,39 @@ loom process resume daily-summary
 
 ### `loom process update <name>`
 
-Update an existing process definition.
+更新已有的 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
 ```
 
-**Options:**
-| Flag | Required | Description |
-|------|----------|-------------|
-| `--cron` | No | Update cron schedule expression |
-| `--cron-timezone` | No | Update cron timezone |
-| `--on-event` | No | Update event trigger pattern |
-| `--event-filter` | No | Update event payload filter as JSON |
-| `--event-debounce` | No | Update debounce window in ms |
-| `--prompt` | No | Update inline prompt |
-| `--description` | No | Update description |
-| `--model` | No | Update AI model name (pass empty string to remove model binding) |
-| `--token` | No | Auth token (or set LOOM_TOKEN) |
-| `--server` | No | Server URL (or set LOOM_SERVER, default: http://localhost:3000) |
+**选项：**
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--cron` | 否 | 更新 Cron 调度表达式 |
+| `--cron-timezone` | 否 | 更新 Cron 时区 |
+| `--prompt` | 否 | 更新内联提示词 |
+| `--description` | 否 | 更新描述 |
+| `--model` | 否 | 更新 AI 模型名称（传入空字符串移除模型绑定） |
+| `--subscribe-add` | 否 | 要订阅的事件模式（创建 `handler: process` 订阅） |
+| `--subscribe-filter` | 否 | 事件载荷的 JSON 过滤条件（仅与 --subscribe-add 配合使用） |
+| `--subscribe-debounce` | 否 | 防抖窗口，单位毫秒（默认：1000，仅与 --subscribe-add 配合使用） |
+| `--subscribe-remove` | 否 | 要移除的订阅 ID（使用 `loom event list` 查找 ID） |
+| `--token` | 否 | 认证令牌（或设置 LOOM_TOKEN） |
+| `--server` | 否 | 服务器 URL（或设置 LOOM_SERVER，默认：http://localhost:3000） |
 
 ### `loom process remove <name>`
 
-Remove a process definition. Logs are preserved.
+移除 Process 定义。执行日志会保留。
 
 ```bash
 loom process remove daily-summary
@@ -143,21 +152,21 @@ loom process remove daily-summary
 
 ### `loom process logs <name> [runId]`
 
-View execution logs. When `runId` is provided, shows details for a single run.
+查看执行日志。提供 `runId` 时显示单次运行的详情。
 
 ```bash
-# List recent logs
+# 列出最近的日志
 loom process logs daily-summary
 loom process logs daily-summary --limit 50
 loom process logs daily-summary --offset 10
 
-# View a specific run
+# 查看特定运行
 loom process logs daily-summary run_abc123
 ```
 
 ### `loom process generate <name>`
 
-Create PROCESS.md scaffold directory (for full process mode). Called by AI, not directly by users.
+创建 PROCESS.md 脚手架目录（用于完整模式）。由 AI 调用，用户一般不直接使用。
 
 ```bash
 loom process generate daily-report --description "Daily report generator"
@@ -165,13 +174,13 @@ loom process generate daily-report --description "Daily report generator"
 
 ### `loom process metrics-report <name>`
 
-Report a business metric snapshot. Used by AI agent during process execution.
+上报业务指标快照。由 AI Agent 在 Process 执行期间调用。
 
 ```bash
-# Basic report
+# 基础上报
 loom process metrics-report my-process --metric-name "成功率" --value 0.95 --unit "%"
 
-# With target and dimensions
+# 带目标和维度
 loom process metrics-report my-process \
   --metric-name "错题重复率" \
   --value 3 \
@@ -181,156 +190,258 @@ loom process metrics-report my-process \
   --run-id $LOOM_RUN_ID
 ```
 
-**Options:**
-| Flag | Required | Description |
-|------|----------|-------------|
-| `--metric-name` | Yes | Human-readable metric name |
-| `--value` | Yes | Numeric metric value |
-| `--run-id` | No | Run ID (defaults to LOOM_RUN_ID env var) |
-| `--timestamp` | No | ISO timestamp (defaults to now) |
-| `--dimensions` | No | Dimension labels as JSON |
-| `--target` | No | Target value for goal-line |
-| `--unit` | No | Unit label (e.g., "%", "条") |
-| `--token` | No | Auth token (or set LOOM_TOKEN) |
-| `--server` | No | Server URL (or set LOOM_SERVER) |
+**选项：**
+| 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>`
 
-Set or update the business metrics view configuration. This defines how process metrics are visualized in the Process Management page — each metric gets its own card and optional chart.
+设置或更新业务指标视图配置。定义 Process 指标在 Process 管理页面的可视化方式——每个指标拥有独立卡片和可选图表。
 
-**When to use:** After creating a full process with `## Metrics` section, design the view config and write it using this command. See the Process Builder reference for the `ProcessMetricsViewConfig` schema and chart design guidelines.
+**何时使用：** 创建含 `## Metrics` 章节的完整 Process 后，设计视图配置并通过此命令写入。
 
 ```bash
-# From JSON string
+# 从 JSON 字符串
 loom process metrics-set-view-config my-process --config '{"version":1,"metrics":[{"metricName":"成功率","title":"成功率","chartType":"gauge","direction":"target","target":1,"unit":"%"}],"charts":[]}'
 
-# From file (recommended for complex configs)
+# 从文件（推荐用于复杂配置）
 loom process metrics-set-view-config my-process --config @./view-config.json
 ```
 
-**ProcessMetricsViewConfig structure:**
-- `version`: Always `1`
-- `metrics[]`: Metric card definitions. Each card shows latest value, trend arrow, and target.
-  - `metricName`: Exact name used in `metrics-report` calls
-  - `title`: Display title
-  - `chartType`: `"gauge"` | `"number"` | `"line"` | `"bar"` | `"area"` — gauge/number only render as cards; line/bar/area also render as independent charts
-  - `direction`: `"increasing"` | `"decreasing"` | `"target"` — controls trend arrow color
-  - `target`: Goal value (shown on card)
-  - `unit`: Unit label (e.g., "%", "条", "次")
-- `charts[]`: G2 v5 chart specs. Each chart MUST include `metricName` for data filtering.
-  - `metricName`: Which metric's snapshots this chart displays
-  - `title`: Chart title
-  - `type`: G2 mark type (`"line"`, `"interval"`, `"area"`, etc.)
-  - `encode`: Field mapping (use `timestamp` for X axis, `value` for Y axis)
-  - Other G2 spec properties: `scale`, `axis`, `transform`, etc.
-
-**Key design rule:** Each chart shows ONE metric only. Never combine different metrics in one chart — they have different units and scales. Use `metricName` to filter data.
-
-**Options:**
-| Flag | Required | Description |
-|------|----------|-------------|
-| `--config` | Yes | View config JSON (use `@file` to read from file) |
-| `--token` | No | Auth token (or set LOOM_TOKEN) |
-| `--server` | No | Server URL (or set LOOM_SERVER) |
+**ProcessMetricsViewConfig** 完整 Schema、chart 设计规则和示例见 **`process-builder.md` → Initializing Metrics Visualization**。
+
+**选项：**
+| Flag | 必填 | 说明 |
+|------|------|------|
+| `--config` | 是 | 视图配置 JSON（使用 `@file` 从文件读取） |
+| `--token` | 否 | 认证令牌（或设置 LOOM_TOKEN） |
+| `--server` | 否 | 服务器 URL（或设置 LOOM_SERVER） |
 
 ### `loom process export <name>`
 
-Export process definition as JSON.
+导出 Process 定义为 JSON。
 
 ```bash
 loom process export daily-summary
 ```
 
-## Process Modes
+## Process 模式
 
-### Lightweight Mode (`--prompt`)
+### 轻量模式（`--prompt`）
 
-- Inline prompt, no PROCESS.md file
-- Best for simple, single-task automations
-- Quick to set up and modify
+- 内联提示词，无需 PROCESS.md 文件
+- 适合简单的单步自动化
+- 快速创建和修改
 
-### Full Mode (`--process`)
+### 完整模式（`--process`）
 
-- Has PROCESS.md at `.loom/processes/{name}/PROCESS.md`
-- Can include reference files in `.loom/processes/{name}/references/`
-- Best for complex, multi-step workflows
-- Supports Metrics and Evolution sections
+- 在 `.loom/processes/{name}/PROCESS.md` 拥有 PROCESS.md
+- 可在 `.loom/processes/{name}/references/` 中添加参考文件
+- 适合复杂的多步骤工作流
+- 支持 Metrics 和 Evolution 章节
 
-## Trigger Types
+## 触发器类型
 
 ### Cron
-Standard 5-field cron expression: `minute hour day month weekday`
-```
-*/5 * * * *     — Every 5 minutes
-0 9 * * 1-5     — Weekdays at 9 AM
-0 0 1 * *       — First of every month
-```
+标准 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 pattern matching: `{category}:{action}:{target}`
-```
-data:create:tasks       — When a task is created
-data:update:*           — Any data update
-user:created            — When a user is created
-process:completed:xxx   — When process xxx completes
-```
+EventBus 模式匹配：`{category}:{action}:{target}`
 
-### Source (Feeder)
-When a process needs a persistent external data source, use `--source` to declare a Feeder script. The script starts when the Loom instance becomes ready and stops when the instance shuts down.
+| 模式 | 触发时机 |
+|------|----------|
+| `data:create:<model>` | 新记录创建时 |
+| `data:update:<model>` | 记录更新时 |
+| `data:delete:<model>` | 记录删除时 |
+| `user:created` | 新用户注册时 |
+| `process:completed:<name>` | 另一个 Process 完成时 |
+
+完整的事件模式文档见 **`events.md`**。
+
+### Source（Feeder）
+当 Process 需要持久化的外部数据源时，使用 `--source` 声明 Feeder 脚本。脚本在 Loom 实例就绪时启动，实例关闭时停止。
 
 ```bash
 loom process add --name ingest \
-  --on-event "dingtalk:mention" \
+  --subscribe "dingtalk:mention" \
   --source "bash examples/feeders/dingtalk-mention.sh" \
   --process "ingest" \
   --owner admin
 ```
 
-This single command:
-1. Registers the Process definition with a `source` field
-2. Auto-starts the Feeder via LifecycleManager
-3. Auto-registers the event subscription if not already present
+此命令一步完成：
+1. 注册带 `source` 字段的 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 中）
+
+## 执行模型
 
-Removing the process with `loom process remove` automatically cleans up the Feeder if no other process subscribes to the same event pattern.
+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`
 
-**Feeder script contract:**
-- Trap SIGTERM/SIGINT and exit with code 0 for graceful shutdown
-- Use `$LOOM_SERVER_URL` instead of hardcoded URLs
-- Exit code 0 = normal (no restart); non-zero = crash (auto-restart with backoff)
-- One script instance per name
+## 并发控制
 
-**Lifecycle event patterns:**
-| Pattern | When |
-|---------|------|
-| `lifecycle:started:{name}` | Feeder script started |
-| `lifecycle:failed:{name}` | Feeder script exited abnormally |
-| `lifecycle:circuit_open:{name}` | Feeder reached max restarts |
-| `lifecycle:restart:{name}` | Feeder restarting with backoff |
+由 loom.config.ts 中的 `processes.maxConcurrent` 控制（默认：5）。达到上限时，新触发器排队等待空闲槽位。
 
-### Manual
-`loom process run <name>` — immediate execution, works even when paused.
+## 防抖
 
-## Service Token Authentication
+事件触发器带有 `eventDebounceMs`（默认：1000ms）。防抖窗口内的快速事件会被合并——仅触发一次执行，使用最后一条事件的载荷。
 
-When auth is enabled, processes need a service token to operate:
-- `--owner <username>`: Runtime resolution via UserStore (recommended)
-- `--owner-token <jwt>`: Direct JWT token (less secure, stored in processes/_registry.json)
+## 事件订阅
 
-## Execution Model
+Process 通过事件订阅响应事件。两种绑定方式：
 
-1. Trigger fires → entry enqueued
-2. Queue slot available → process starts
-3. AI prompt built (PROCESS.md + references + event context + metrics protocol)
-4. Claude Code engine executes with timeout, env vars injected: LOOM_SERVER, LOOM_PROCESS_NAME, LOOM_RUN_ID
-5. Agent may call `loom process metrics-report` to report business metrics during execution
-6. Result logged to `.loom/processes/{name}/logs/{runId}.json`
-7. Metric snapshots stored in `.loom/processes/{name}/metrics.jsonl`
-8. Event emitted: `process:started`, `process:completed`, or `process:failed`
+1. **创建时绑定**：`loom process add --subscribe "pattern"` — 自动创建 `handler: 'process'` 订阅，适合一步到位
+2. **独立管理**：`loom event subscribe/unsubscribe/update/test` — 灵活管理 M:N 关系，支持所有 handler 类型
 
-## Concurrency
+```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`**。
+
+## 系统指标配置
+
+Process 内置执行统计指标（totalRuns、completedRuns、avgDurationMs 等），可通过 `--metrics-config` 配置 Dashboard 展示。这与 `metrics-report` 上报的**业务指标**是两套独立系统：
+
+| 系统 | 数据来源 | 配置方式 | 用途 |
+|------|----------|----------|------|
+| **系统指标**（本节） | 自动采集执行统计 | `--metrics-config` + DashboardWidget | 监控执行健康度 |
+| **业务指标** | AI 调用 `metrics-report` 上报 | `## Metrics` + `metrics-set-view-config` | 跟踪业务 KPI |
+
+业务指标的完整设计指南见 **`process-builder.md`**。
 
-Controlled by `processes.maxConcurrent` in loom.config.ts (default: 5). When max is reached, new triggers queue until a slot opens.
+### 指标配置
 
-## Debounce
+创建 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"
+  }
+]
+```
 
-Event triggers have `eventDebounceMs` (default: 1000ms). Rapid events within the window are collapsed — only one execution fires with the last event's payload.
+### 可用组件类型
+
+| 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 | 获取组件配置 |