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

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

@@ -0,0 +1,336 @@
+# Process CLI Reference
+
+## Overview
+
+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
+
+### `loom process add`
+
+Create a new process definition.
+
+```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)
+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" \
+  --prompt "Analyze the new task and suggest priorities" \
+  --owner admin \
+  --event-debounce 2000
+
+# 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" \
+  --owner admin \
+  --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) |
+
+### `loom process list`
+
+List all processes.
+
+```bash
+loom process list
+loom process list --status active
+loom process list --status paused
+```
+
+### `loom process status <name>`
+
+Show detailed process status.
+
+```bash
+loom process status daily-summary
+```
+
+### `loom process run <name>`
+
+Manually trigger a process execution.
+
+```bash
+loom process run daily-summary
+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).
+
+```bash
+loom process pause daily-summary
+```
+
+### `loom process resume <name>`
+
+Resume a paused process.
+
+```bash
+loom process resume daily-summary
+```
+
+### `loom process update <name>`
+
+Update an existing process definition.
+
+```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"
+```
+
+**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) |
+
+### `loom process remove <name>`
+
+Remove a process definition. Logs are preserved.
+
+```bash
+loom process remove daily-summary
+```
+
+### `loom process logs <name> [runId]`
+
+View execution logs. When `runId` is provided, shows details for a single run.
+
+```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.
+
+```bash
+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.
+
+```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 \
+  --unit "条" \
+  --target 0 \
+  --dimensions '{"subject":"数学"}' \
+  --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) |
+
+### `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.
+
+**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.
+
+```bash
+# From JSON string
+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) |
+
+### `loom process export <name>`
+
+Export process definition as JSON.
+
+```bash
+loom process export daily-summary
+```
+
+## Process Modes
+
+### Lightweight Mode (`--prompt`)
+
+- Inline prompt, no PROCESS.md file
+- Best for simple, single-task automations
+- Quick to set up and modify
+
+### Full Mode (`--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
+
+## 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
+```
+
+### 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
+```
+
+### 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.
+
+```bash
+loom process add --name ingest \
+  --on-event "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
+
+Removing the process with `loom process remove` automatically cleans up the Feeder if no other process subscribes to the same event pattern.
+
+**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 |
+
+### Manual
+`loom process run <name>` — immediate execution, works even when paused.
+
+## Service Token Authentication
+
+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
+
+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`
+
+## Concurrency
+
+Controlled by `processes.maxConcurrent` in loom.config.ts (default: 5). When max is reached, new triggers queue until a slot opens.
+
+## Debounce
+
+Event triggers have `eventDebounceMs` (default: 1000ms). Rapid events within the window are collapsed — only one execution fires with the last event's payload.

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（透视表字段）