@loom-framework/core 0.1.0-alpha.17 → 0.1.0-alpha.171

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

@@ -0,0 +1,408 @@
+# Process Builder Guide
+
+## Purpose
+
+This guide helps AI assistants create Processes for users. When a user says "I want to automate X" or "run Y every day", use this guide to build a process definition.
+
+## Lightweight vs Full Decision
+
+### Use Lightweight (`--prompt`) when:
+- Single, simple task
+- No reference files needed
+- Prompt fits in a few sentences
+- No metrics dashboard needed
+
+### Use Full (`--process`) when:
+- Multi-step workflow with decision points
+- Reference documentation needed (API docs, data schemas, style guides)
+- Metrics dashboard desired
+- Process may evolve over time (Evolution section)
+
+## Step-by-Step Creation
+
+### 1. Analyze the Request
+
+Identify:
+- **What** the process should do
+- **When** it should run (schedule or event trigger)
+- **Who** owns it (username for service token)
+- **Complexity** (lightweight vs full)
+
+### 2. Choose Trigger
+
+| Need | Use | Example |
+|------|-----|---------|
+| Periodic schedule | `--cron` | `0 9 * * 1-5` (weekdays 9am) |
+| On data change | `--on-event` | `data:create:tasks` |
+| On user action | `--on-event` | `user:created` |
+| Manual only | Neither | Just `loom process run` |
+
+### 3. Create the Process
+
+For lightweight:
+```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
+```
+
+For full:
+```bash
+# Step 1: Generate scaffold
+loom process generate weekly-report --description "Weekly analytics report"
+
+# Step 2: Edit PROCESS.md with detailed flow
+# (AI should write the PROCESS.md content)
+
+# Step 3: Add reference files if needed
+# If this process requires additional context, create the references directory
+# and add files that the AI agent will need during execution:
+mkdir -p .loom/processes/weekly-report/references
+# Then add reference files such as:
+#   - Skill references (CLI command usage, API docs)
+#   - Domain knowledge (data schemas, business rules)
+#   - Scripts or tools (data transforms, query templates)
+# Only create the directory when reference files are actually needed.
+# Skip this step if no additional context is required.
+
+# Step 4: Register the process
+loom process add --name "weekly-report" \
+  --cron "0 9 * * 1" \
+  --process "weekly-report" \
+  --owner admin
+
+# Step 5: Initialize metrics view config (if PROCESS.md has ## Metrics section)
+# Design the view config based on ## Metrics section (see "Initializing Metrics Visualization" below)
+# Then write it using metrics-set-view-config:
+loom process metrics-set-view-config weekly-report --config @./view-config.json
+```
+
+### 4. Verify
+
+```bash
+loom process status <name>
+loom process run <name>  # manual test
+loom process logs <name>  # check result
+```
+
+## PROCESS.md Best Practices
+
+### Structure
+
+```markdown
+# Process: <name>
+
+## Description
+What this process does and why.
+
+## Trigger
+When it runs and what triggers it.
+
+## Flow
+Step-by-step instructions:
+1. Read data from <model>
+2. Analyze <something>
+3. Write results to <model>
+4. Send notification with execution result via `loom notification send`
+
+## Decision Points
+Key decisions the AI should make:
+- If X, do Y
+- If Z, skip to step N
+
+## Metrics
+How success is measured:
+- Execution time < N seconds
+- Error rate < X%
+- Output quality: <criteria>
+
+## Evolution
+How this process should improve:
+- After N runs, review and optimize prompt
+- Track common errors and add handling
+
+## References
+_List files in the `references/` directory that support this process:_
+- _Skill references (e.g., CLI command usage, API docs)_
+- _Domain knowledge (e.g., data schemas, business rules)_
+- _Scripts or tools (e.g., data transforms, query templates)_
+_Only create the `references/` directory and add files when needed._
+```
+
+### Tips
+- Be specific in Flow steps — AI follows them literally
+- Include data model names and field names
+- Reference CLI commands: `loom data list <model>`, `loom data create <model>`
+- Use `loom data` commands for data operations, not direct file I/O
+- Include error handling in Decision Points
+- Add a notification step at the end of Flow to send execution results to yourself: `loom notification send --userId <owner> --type success --title "Process completed" --description "Summary of results" --token $LOOM_TOKEN`
+
+## Metrics Definition
+
+When defining `## Metrics` in PROCESS.md, follow these guidelines so the system can properly track and visualize them:
+
+### Format
+
+Each metric should include:
+- **Name**: A clear, concise identifier (e.g., "错题 review 率")
+- **Meaning**: What this metric measures and why it matters
+- **Direction**: Whether the metric should increase, decrease, or approach a target
+  - `increasing` = higher is better (e.g., success rate)
+  - `decreasing` = lower is better (e.g., error count)
+  - `target` = should approach a specific value (e.g., 100% coverage)
+- **Target** (optional): The goal value
+- **Unit** (optional): Measurement unit (e.g., "%", "条", "次")
+- **Chart** (optional): Suggested chart type for visualization
+
+### Example
+
+```markdown
+## Metrics
+
+- **错题 review 率**: 每次触发后，是否成功将错题写入 review_plans。方向：趋近目标值。目标：100%。单位：%。图表：gauge。
+- **错题重复出现率**: 统计相同错误模式的错题数量趋势。方向：越低越好。单位：条。图表：line。
+```
+
+### Initializing Metrics Visualization
+
+After registering a full process with `--process`, you MUST initialize the metrics view configuration so the Process Management page can render charts for each metric. This is a two-step process:
+
+#### Step 1: Design the view config based on ## Metrics
+
+Analyze each metric in the `## Metrics` section and generate a `ProcessMetricsViewConfig` JSON. The config has two parts:
+
+- **`metrics[]`**: Metric card definitions (shown as number + trend + target)
+- **`charts[]`**: G2 v5 chart specs (one independent chart per metric, filtered by `metricName`)
+
+**ProcessMetricsViewConfig Schema:**
+
+```typescript
+{
+  version: 1,
+  metrics: ProcessMetricView[],        // Metric card definitions
+  charts: ProcessMetricChartSpec[]     // Chart specs with metric binding
+}
+
+// ProcessMetricView:
+{
+  metricName: string;                   // Must match the exact name used in metrics-report
+  title: LocaleString;                  // Display title for the card (i18n)
+  description?: LocaleString;           // Optional tooltip description (i18n)
+  chartType: string;                    // 'line' | 'bar' | 'area' | 'gauge' | 'number'
+  direction?: 'increasing' | 'decreasing' | 'target';
+  target?: number;                      // Goal value (shown on card)
+  unit?: string;                        // Unit label (e.g., "%", "条", "次")
+}
+
+// ProcessMetricChartSpec:
+{
+  metricName?: string;                  // Filter snapshots for this metric
+  title?: LocaleString;                 // Chart title (i18n)
+  type: string;                         // G2 chart type: 'line' | 'interval' | 'area' | 'cell'
+  encode?: Record<string, unknown>;     // G2 encode config
+  scale?: Record<string, unknown>;      // G2 scale config
+  coordinate?: Record<string, unknown>; // G2 coordinate config
+  transform?: Record<string, unknown>[];// G2 transform config
+  style?: Record<string, unknown>;      // G2 style config
+  legend?: Record<string, unknown> | boolean;
+  labels?: Record<string, unknown>[];
+  interval?: 'minute' | 'hour' | 'day' | 'week' | 'month'; // Date truncation for timestamp field
+  aggregate?: 'count' | 'sum' | 'avg'; // Aggregate function when interval is set (default: 'avg')
+}
+
+// LocaleString is either a plain string or { "zh-CN": "...", "en-US": "..." }
+type LocaleString = string | { "zh-CN": string; "en-US": string };
+```
+
+**Chart type selection guide:**
+
+| Metric direction + unit | chartType | Has chart? | Reasoning |
+|------------------------|-----------|-----------|-----------|
+| `target` + `%` unit | `gauge` | No (card only) | Percentage target → card shows current vs target |
+| `target` + non-`%` unit | `number` | No (card only) | Numeric target → card is sufficient |
+| `increasing` / `decreasing` + `%` | `line` | Yes | Track trend over time |
+| `increasing` / `decreasing` + count unit | `bar` | Yes | Compare across runs |
+
+**Chart spec design rules:**
+
+1. **Each metric gets its own independent chart** — never mix different metrics in one chart. Different metrics have different units and scales, combining them makes the chart unreadable.
+2. **Every chart MUST include `metricName`** — the frontend uses this field to filter `metricSnapshots` for that specific metric. Without it, all data would be mixed.
+3. **Chart data fields** reference `ProcessMetricSnapshot` properties: `timestamp`, `value`, `metricName`, `dimensions`, `target`, `unit`. The frontend injects filtered snapshots as `data`.
+4. **Title each chart** — add a `title` field (use LocaleString format for i18n support).
+
+**Chart spec templates by type:**
+
+```jsonc
+// line chart — time series trend (with date aggregation)
+{
+  "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 } }
+}
+
+// bar chart — per-run comparison
+{
+  "metricName": "新增错题数",
+  "title": { "zh-CN": "每次执行新增错题数", "en-US": "New Errors Per Run" },
+  "type": "interval",
+  "encode": { "x": "runId", "y": "value" },
+  "scale": { "y": { "nice": true } }
+}
+
+// area chart — cumulative trend (with date aggregation)
+{
+  "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 and number types do NOT need a chart entry** — they only appear as metric cards (showing latest value, trend arrow, and target).
+6. **When `interval` is set**, the frontend automatically aggregates snapshots by truncated date (minute/hour/day/week/month). Use `encode: { "x": "name", "y": "value" }` for interval-mode charts. When `interval` is omitted, raw snapshots are passed through to G2 directly (use `encode: { "x": "timestamp", "y": "value" }` for time series without aggregation).
+
+#### Step 2: Write the view config
+
+Use `loom process metrics-set-view-config` to write the configuration:
+
+```bash
+# From JSON string
+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 } }
+    }
+  ]
+}'
+
+# Or from a file
+loom process metrics-set-view-config <name> --config @./view-config.json
+```
+
+Note: The server must be running when using this command (it calls the API).
+
+### Complete example — error-pattern-analysis process
+
+PROCESS.md `## Metrics` section:
+
+```markdown
+## Metrics
+
+- **错题 review 率**: 每次触发后，是否成功将错题写入 review_plans。方向：趋近目标值。目标：100%。单位：%。图表：gauge。
+- **错题重复出现率**: 统计相同错误模式的错题数量趋势。方向：越低越好。单位：条。图表：line。
+```
+
+Corresponding view config:
+
+```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 } }
+    }
+  ]
+}
+```
+
+Note: "错题 review 率" has `chartType: "gauge"` which only renders as a metric card (latest value + target + trend). It does NOT need a chart entry in `charts[]`.
+
+### Reporting metrics during execution
+
+When a process's PROCESS.md has a `## Metrics` section, the system automatically injects a Metrics Protocol into the AI prompt. The agent MUST call `loom process metrics-report` for each metric after computing its value:
+
+```bash
+loom process metrics-report <process-name> \
+  --metric-name "错题 review 率" \
+  --value 0.95 \
+  --target 1 \
+  --unit "%" \
+  --run-id $LOOM_RUN_ID
+```
+
+Key points:
+- `--metric-name` MUST exactly match the name used in the view config (including `metrics[]` entries)
+- `--run-id` is automatically available via the `$LOOM_RUN_ID` environment variable
+- `--dimensions` is optional for dimensional breakdown (e.g., `--dimensions '{"subject":"数学"}'`)
+- Report each metric as soon as it's computed, don't batch at the end
+
+## Common Cron Patterns
+
+| Pattern | Schedule |
+|---------|----------|
+| `*/5 * * * *` | Every 5 minutes |
+| `*/15 * * * *` | Every 15 minutes |
+| `0 * * * *` | Every hour |
+| `0 9 * * *` | Daily at 9 AM |
+| `0 9 * * 1-5` | Weekdays at 9 AM |
+| `0 9 * * 1` | Every Monday at 9 AM |
+| `0 0 1 * *` | First of every month |
+
+## Common Event Patterns
+
+| Pattern | When |
+|---------|------|
+| `data:create:<model>` | New record created |
+| `data:update:<model>` | Record updated |
+| `data:delete:<model>` | Record deleted |
+| `user:created` | New user registered |
+| `process:completed:<name>` | Another process finished |

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

@@ -0,0 +1,93 @@
+# Process Metrics Reference
+
+## Overview
+
+Process metrics allow you to define dashboard widgets for monitoring process execution. Metrics are served via the `/api/v1/processes/:name/metrics` endpoint and configured per-process.
+
+## Metrics Config
+
+Define metrics using DashboardWidget schema in `--metrics-config <path>` JSON file or via the API.
+
+### Example: 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"
+  }
+]
+```
+
+### Available Widget Types
+
+| Type | Description | Required Fields |
+|------|-------------|-----------------|
+| `stat` | Single number display | `title`, `model`, `aggregate`, `field` |
+| `line` | Line chart | `title`, `model`, `aggregate`, `field`, `groupBy`, `dateInterval` |
+| `bar` | Bar chart | `title`, `model`, `aggregate`, `field`, `groupBy` |
+| `pie` | Pie chart | `title`, `model`, `field`, `groupBy` |
+| `gauge` | Gauge display | `title`, `model`, `field`, `min`, `max` |
+| `table` | Table view | `title`, `model`, `columns` |
+
+### Available Metrics Fields
+
+From `ProcessMetricsAggregate`:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `date` | string | Date (YYYY-MM-DD) |
+| `totalRuns` | number | Total executions |
+| `completedRuns` | number | Successful executions |
+| `failedRuns` | number | Failed executions |
+| `timeoutRuns` | number | Timed out executions |
+| `avgDurationMs` | number | Average duration in ms |
+| `lastRunAt` | string\|null | Last execution timestamp |
+| `lastStatus` | string\|null | Last execution status |
+
+### Setting Metrics Config
+
+```bash
+# During process creation
+loom process add --name "health-check" \
+  --cron "*/30 * * * *" \
+  --prompt "Check system health" \
+  --metrics-config ./health-metrics.json \
+  --owner admin
+
+# Or create the JSON file first
+echo '[
+  {"type":"stat","title":{"zh-CN":"成功率","en-US":"Success Rate"},"model":"__process_metrics","aggregate":"sum","field":"completedRuns"},
+  {"type":"stat","title":{"zh-CN":"平均耗时","en-US":"Avg Duration"},"model":"__process_metrics","aggregate":"avg","field":"avgDurationMs"}
+]' > health-metrics.json
+```
+
+### API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/api/v1/processes/:name/metrics` | GET | Get aggregated metrics data |
+| `/api/v1/processes/:name/metrics-config` | GET | Get widget configuration |
+
+The frontend ProcessManagementPage Metrics tab fetches both endpoints and renders the configured widgets dynamically.