命令
Pi 斜杠命令与 MCP 工具（Codex、Claude、OpenCode、Grok、Hermes）。
taskflow 以两种方式暴露相同的操作。在 Pi 上，你输入像 /tf run 和 /tf:review-changes 这样的斜杠命令。在 Codex（以及 Claude Code、OpenCode、Grok、Hermes）上，相同的操作是模型调用的 MCP 工具——taskflow_run、taskflow_list 等等。
本页是两者的分组参考。每个命令有一行用途说明，并在有用处时给出具体示例。如果你只想略读，跳到末尾的示例会话。
已保存的 flow 在 Pi 上变成 CLI 快捷方式（/tf:<name>）。在 MCP 宿主上，你通过 taskflow_run 按名称运行已保存的 flow。
Pi /tf 命令
/tf 命令是 Pi 上面向用户的界面。它的子命令分为四组。
运行
| 命令 | 说明 |
|---|---|
/tf run <name> [args] | 运行已保存的 flow，可选地以 key=value 对或 JSON 传入参数。 |
/tf:<name> [args] | 快捷方式——等价于 /tf run <name> [args]。为每个已保存的 flow 注册。 |
/tf resume <runId> | 从停止处续跑一个暂停或失败的运行。 |
查看
| 命令 | 说明 |
|---|---|
/tf list | 列出本项目所有已保存的 flow。 |
/tf show <name> | 打印一个已保存 flow 的完整 JSON 定义。 |
/tf runs | 浏览最近的运行历史（最近 50 条），并选一个来查看或续跑。 |
/tf peek <runId> [phaseId] | 查看一个已存储运行的中间阶段输出（事后调试）。支持 --json、--item <n>、--limit <chars>。 |
验证与分析
| 命令 | 说明 |
|---|---|
/tf plan <name> [args-json] | 零 token preflight——绑定 args、投影 phase 序与动态绑定、worst-case agent 调用上界。建议在 run 之前使用。 |
/tf verify <name> | 静态验证一个 flow——循环、缺失依赖、死胡同——零 token 成本。 |
/tf compile <name> [lr|td] | 把 DAG 渲染为 Mermaid 图（lr = 从左到右，td = 从上到下）。 |
/tf analytics <name> [--last N] | 聚合最近 N 次运行：状态直方图、耗时、per-phase 失败/缓存命中率（只读）。 |
/tf ir <name> | 编译为 FlowIR + 内容哈希（增量重算的中间产物）。 |
/tf provenance <runId> | 显示一个运行观察到的读集合来源。 |
/tf why-stale <runId> [phaseId] | 解释为什么一个缓存的运行已过期——哪个 fingerprint 输入变了。 |
/tf recompute <runId> <phaseId> [--apply] | 最小化地重算一个过期阶段。默认是安全的 dry-run（含省钱一行）；--apply 花 token。 |
/tf trace <runId> [--json] | 显示追加写事件日志（subagent I/O + 运行时决策）。 |
/tf replay <runId> [--threshold phase=n] [--budget-usd n] [--json] | 基于已录制轨迹的离线阈值/预算 what-if（零 token）。 |
生命周期
| 命令 | 说明 |
|---|---|
/tf save | 把最近的内联 flow 定义保存到一个名称下（让 /tf:<name> 立即可用）。 |
/tf search | 按 purpose/tags 搜索可复用 flow 库。 |
/tf init | 配置模型角色——把内置 agent 角色映射到你的模型。 |
peek / provenance / why-stale / recompute 回答「会重跑什么」；trace + replay 回答「当时如何裁决」与反事实旋钮——见确定性重放。
taskflow 工具（Pi）
在 Pi 上，模型也可以直接调用一个 taskflow 工具。它接受一个 action 加参数。这些 action 与 /tf 子命令对应，并加上几个模型内部使用的：
| Action | 说明 |
|---|---|
run | 运行内联或已保存的 flow。 |
plan | 零 token preflight（参数绑定 + phase 计划 + 预算上界）。 |
save | 持久化一个 flow 定义。 |
search | 按 purpose/tags 搜索可复用 flow 库。 |
resume | 按 runId 续跑。 |
list | 列出已保存的 flow。 |
agents | 列出内置 agent。 |
verify | 静态检查。 |
compile | Mermaid 图 + 验证报告。 |
analytics | 按 flow 名聚合最近 N 次运行（只读）。 |
ir / provenance / why-stale / recompute | 增量重算工具包。 |
trace / replay | 事件日志查看 + 离线决策 what-if（零 token）。 |
cache-clear | 清除跨运行记忆化缓存。 |
init | 配置模型角色。 |
Codex / Claude / OpenCode / Grok / Hermes MCP 工具
在 MCP 宿主上，taskflow 暴露这些工具（模型调用它们；你通常不输入它们）：
| 工具 | 说明 |
|---|---|
taskflow_run | 运行内联或已保存的 flow；返回最终输出和一个 runId。 |
taskflow_runs | 列出后台运行，或按 runId 执行 status / 有界 wait / cancel。 |
taskflow_resume | 把失败或暂停运行 fork 为新的不可变子运行，可覆盖一个阶段。 |
taskflow_version | 报告包版本、构建 commit、schema 版本、构建时间与 host。 |
taskflow_list | 列出在此目录下可发现的已保存 flow。 |
taskflow_show | 打印一个已保存 flow 的定义。 |
taskflow_plan | 零 token preflight：绑定 args、phase 计划、预算上界（不执行）。 |
taskflow_analytics | 聚合某 flow 最近 N 次运行（状态、耗时、失败/缓存率）。 |
taskflow_verify | 静态验证一个 flow（不执行）。 |
taskflow_compile | 把 DAG 渲染为 SVG、独立文本大纲与验证状态；超大图回退为纯文本。 |
taskflow_peek | 查看一个已存储运行的某个阶段的中间输出（事后调试）。 |
taskflow_trace | 运行追加写事件日志的只读时间线。 |
taskflow_replay | 基于已录制轨迹的离线阈值/预算 what-if（零 token）。 |
taskflow_why_stale | 解释观测/声明依赖的陈旧性。 |
taskflow_recompute | 报告陈旧前沿（MCP 上仅 dry-run）。 |
taskflow_reconcile_workspace | 检查或修复 dirty-unknown 的 resolve-only 工作区后显式接受当前状态；需要 Host 授权和精确确认文本。 |
taskflow_save | 将 flow 连同 purpose/tags 保存到库。 |
taskflow_search | 搜索可复用 flow 库。 |
在 MCP 宿主上没有 /tf 斜杠命令——你用自然语言描述工作，模型调用 taskflow_run。事后排查与离线 what-if 使用 taskflow_peek / taskflow_trace / taskflow_replay 配合 runId。
示例会话
一个在 Pi 上从首次运行到调试的现实会话：
/tf verify review-changesVerify 在任何 token 花费之前捕获一个循环和一个缺失的 dependsOn。修正 JSON，然后运行它：
/tf run review-changes dir=src运行完成并返回最终摘要。你喜欢它，所以保存它：
/tf save review-changes从现在起，快捷方式可用：
/tf:review-changes dir=src几天后摘要看起来过期了。在不重跑的情况下检查原因：
/tf runs
/tf why-stale <runId> summarywhy-stale 报告自缓存运行以来 git:HEAD 变了。只重算那个阶段：
/tf recompute <runId> summary --apply只有 summary 重跑；flow 的其余部分从缓存复用。
下一步
Last updated on