---
description: 运行 YAML 工作流（DAG 执行器）。位置参数按 inputs 声明顺序映射，或用 --input k=v 显式传参
argument-hint: <name> [val ...] [--input key=value ...]
---

# /workflow

本命令由 workflow-runner 插件接管（plugin.ts.runCommand），不会把 prompt 喂给 LLM。
直接调用插件内置的 YAML DAG 执行器，按 steps 顺序运行 tool / llm / skill / agent / assert / branch / loop 等节点。

用法示例：

  /workflow hello-workflow alice                            位置参数：直接传 inputs 声明里第一个 input
  /workflow hello-workflow alice zh                         多个位置参数：按 inputs 顺序填
  /workflow hello-workflow.yaml alice                       .yaml 后缀可省（带也认）
  /workflow hello-workflow --input name=alice --input lang=zh   显式 KV
  /workflow hello-workflow alice --input lang=zh            混用：位置填 name，--input 填 lang

规则：
- 位置参数按 yaml 文件 `inputs:` 数组的**声明顺序**映射（不是字段名顺序）。多 input workflow 推荐 `--input key=value` 显式 KV，不易出错
- `--input k=v` 显式 KV 优先级高于位置参数；位置参数对应的 input 已被 KV 占位时，位置参数被丢弃并 stderr 打 warning
- 多余的位置参数（超过 inputs 声明数量）被丢弃并 stderr 打 warning，不影响 workflow 执行
- 值含空格时用引号：`/workflow xxx "AI 教程 进阶"`

## agent 节点：把一步交给会随机应变的子 agent

大多数 step 是确定性的（`tool` 调一个原子工具、`llm` 单轮生成）。但有些步骤本质是开放式的——
「把 ./data 下最新的 csv 整理成 summary.md」这种，怎么做得看现场。这时用 `agent:` 节点：inline 写一句
任务描述，工作流就地起一个**有界 TAOR 子 agent**（思考 → 用工具 → 观察 → 反思 → 再来），让它随机应变
把这一步要的结果做出来，产出经验证后 `capture` 给下游。这就是「受工作流指导的 TAOR」——happy path 仍是
确定性骨架，只在你显式声明的节点上注入完整 agency。

```yaml
steps:
  - id: summarize
    agent: "把 ./data 下最新的 csv 读出来，整理成一份 markdown 摘要写到 summary.md"
    capture: { content: summary }     # agent 的最终产出存进变量 summary
  - id: gate
    type: assert
    condition: "fileExists('summary.md')"
```

`agent:` 的配套字段（全部复用现有字段，都可选）：

- `allowed_tools: [Read, Write]` —— 收窄它能用的工具；**缺省给全量工具**（要真 agency）。
- `output_schema: {...}` —— 要求结构化产出（provider-native JSON Schema），按字段 `capture`。
- `context_files: [{ path, hint }]` —— 列出可读文件让它按需 Read（不 inline 内容）。
- `maxTurns: <n>` —— 子循环最大轮数，默认 12。
- `capture` / `when` / `onError` —— 与其它动作 step 一致（agent 节点也能 `onError: recover` 被再救一次）。

`agent` vs `skill`：`agent` 是 **inline、一次性**的有界子循环（miniReAct，轻、收敛快、产出受验证闸门把关）；
`skill` 是跑一个**外部 SKILL.md 定义、可复用**的完整 agent（runQuery）。需要复用同一套能力用 `skill`，
临时让某步「自己想办法」用 `agent`。

**信任边界 / 不伪造**：agent 节点与 `onError: recover` 共用同一套系统提示词纪律——内置安全护栏（最小动作、
优先可逆、不碰工作目录外、不删无关数据）、收尾前自我验证、**严禁伪造产出**；做不成就诚实放弃（抛错走 `onError`）。
默认握全量工具，信任边界同 `skill:`——「运行一条 workflow 即信任它」。

## 节点失败怎么办：onError（指导 ↔ 自主 旋钮）

传统工作流的痛点：某个节点一失败、或撞上预料之外的情况，整条流程就崩、停摆。
每个**动作 step**（tool / llm / skill / agent / assert）可声明 `onError`，决定失败时的行为，
让一条工作流在「刚性确定」和「随机应变」之间按节点滑动：

- `halt`（**默认**）：节点失败 → 整条工作流停、报错。最刚性、最可审计。
- `continue`：跳过该节点、继续往下。⚠️ 下游若用 `capture` 依赖它会拿到空值，慎用。
- `recover`（**自适应恢复**）：失败时**不立刻停**，而是临时起一个**有界 agent**，带着
  「工作流目标 + 这个节点本来要做什么 + 错在哪 + 当前已知变量 + 下游 capture 契约」去**随机应变**——
  它会先诊断根因，再换路径 / 换命令 / 先读后写 / 补齐前置条件，**并在收尾前自我验证**产出确实满足意图，
  想办法把这一步要的**结果**做出来。
  **救回** → 用同一个 `capture` 绑定结果、继续走正常流程；**救不回** → 它会**诚实放弃**（绝不伪造假结果），
  工作流带原因报错停止（错误信息形如「自适应恢复未成功：<原因>」）。这是「确定性工作流 × 会随机应变的 agent」的结合点。

`recover` 的配套字段（都可选）：

- `recover_hint: "<提示>"` —— 给恢复 agent 的提示（支持 `${var}` 插值），如 `"端口被占就换 3001 重试"`。
- `allowed_tools: [Read, Bash]` —— 收窄恢复 agent 能用的工具；**缺省给全量工具**。
- `maxTurns: <n>` —— 恢复子循环最大轮数，默认 12（够「诊断 + 探查 + 动手 + 验证」一圈）。

示例：

```yaml
steps:
  - id: start_server
    tool: Bash
    args: { command: "node server.js" }
    onError: recover
    recover_hint: "端口被占就换一个端口重试"
    capture: { content: server_log }
```

注意事项：

- `onError` **只作用于动作 step**。控制流节点（branch / loop / vote / parallel 的条件或结构错误、
  以及 `when` 表达式错误）**始终 halt** —— 那类是「作者写错了」，不是「运行期意外」，不走恢复。
- `continue` vs `recover`：前者「放弃这步、盲目往下」，后者「想办法把这步做成、保住下游」。
  要扛住「预料之外」的情况，用 `recover`。
- **信任边界**：恢复 agent 默认握有全量工具，与 `skill:` 节点一致——「运行一条 workflow 即信任它」。
  不信任来源的 yaml 本就不该跑。
- **不伪造 / 诚实失败**：恢复 agent 的系统提示词内置安全护栏（只做最小必要动作、优先可逆、不碰工作目录外、
  不删无关数据）并**严禁编造假结果**——它要么交付经自我验证的真产出，要么显式放弃让工作流诚实 halt。
  框架侧另有验证闸门：空产出 / 显式放弃一律**不绑 `capture`、不放行下游**，杜绝把脏值喂给后续步骤。
- `recover` 是 opt-in 的：确定性 / 可审计正是工作流的价值，不默认抹掉；由作者按节点决定授予多少「自主权」。

输入 /workflows 查看可用工作流列表。
