在 Pi 上使用 taskflow

如果你已经在用 Pi 把工作委托给子代理，taskflow 把这些一次性的委托变成有名字、可续跑、多步骤的工作流。你把工作描述成一个图——fan-out、gate、loop，你需要什么就写什么——只有最终结果回到你的上下文里。

本页走完整个弧线：安装、运行你的第一个 flow、保存它、按名字运行它，以及接好模型角色。读完时你会有一个一行就能干一件实事的可复用命令。

安装

taskflow 是一个 Pi 扩展。装一次就行：

pi install npm:pi-taskflow

就这样。这个扩展注册了一个模型可以自动调用的 taskflow 工具，外加一个给你的 /tf 命令。启动不需要任何模型侧的配置。

运行你的第一个 flow

咱们从一件实事开始：审查一个项目里改过的文件，返回一份单一的风险摘要。把这个存成 review-changes.json，放在你运行 Pi 的地方旁边：

{
  "name": "review-changes",
  "description": "Review changed files and return a single risk summary.",
  "args": {
    "dir": { "default": "." }
  },
  "concurrency": 4,
  "phases": [
    {
      "id": "discover",
      "type": "agent",
      "agent": "scout",
      "task": "List the source files under {args.dir} that have been changed recently. Output ONLY a JSON array of objects with a 'path' field. No prose.",
      "output": "json"
    },
    {
      "id": "review-each",
      "type": "map",
      "over": "{steps.discover.json}",
      "as": "file",
      "agent": "security-reviewer",
      "task": "Review {file.path} for security risks. Return one paragraph of findings or 'No issues found.'.",
      "dependsOn": ["discover"],
      "concurrency": 4
    },
    {
      "id": "summarize",
      "type": "reduce",
      "from": ["review-each"],
      "agent": "writer",
      "task": "Combine the following per-file reviews into a single prioritized risk summary:\n{steps.review-each.output}",
      "dependsOn": ["review-each"],
      "final": true
    }
  ]
}

这里有三个阶段，连成一个小 DAG。discover 列出文件。review-each fan out——每个文件一个 security reviewer，最多同时四个。summarize 把各文件的审查折成一份报告，而因为它标了 final: true，那份报告是唯一回到你对话里的东西。

现在运行它。你有两种问法。

直接描述工作

你不需要记住一个命令。在 Pi 会话里，用自然语言描述你想要的：

模型识别出意图，加载 taskflow 工具，执行 DAG。来自 discover、review-each 和 summarize 的中间 transcript 留在运行时内部——你的上下文窗口只收到最终摘要。

直接用命令

如果你想明确一点，/tf 命令随时可用：

/tf run review-changes dir=src

两条路径运行的是同一个 flow。当你确切知道自己想要什么、不想花一个模型回合去谈判时，命令形式很方便。

把 flow 存下来以后用

从 JSON 文件运行适合试验，但真正的回报是把一个你喜欢的 flow 变成一个单词命令。

一次运行之后，直接告诉 Pi 把它存下来：

或者直接用命令从一个文件存：

/tf save review-changes

taskflow 把定义写进你项目的 flow store。从那时起，这个 flow 就有了一个快捷方式：

/tf:review-changes dir=src

这个 /tf:<name> 形式是调用一个你已经塑好形的 flow 的最快方式。它和 /tf run <name> 一样——只是更短。

当一次运行暂停或失败时

真实的工作流并不总是第一次就跑完。一个 approval 阶段可能为人工暂停，一个子代理可能撞上瞬时错误，或者你可能中止一个长运行之后再回来。

每次运行都有一个 runId，运行时持久化它的状态。要继续一个暂停或失败的运行：

/tf resume <runId>

要浏览你运行过的东西，包括进行中和暂停的运行：

/tf runs

而如果你需要在事后检查某个阶段的中间输出——比如调试一个 gate 为什么 block 了——peek 不用重新运行任何东西就能显示它：

/tf peek <runId> summarize

模型角色

taskflow 自带十八个内置 agent（scout、security-reviewer、writer 等等），每一个都打了一个映射到模型的角色标签。开箱即用时，这些角色可能解析到一个默认模型——但你会想把它们指向你自己的模型。

运行交互式设置：

/tf init

你会得到一个选择器，带你走过每个角色并推荐合理的默认值。角色如下：

配置写到你的 Pi settings.json 里的 modelRoles 下。你可以随时重新运行 /tf init 来改单个角色，或接受推荐的默认值。

命令参考

这是完整的 /tf 表面，供你确切知道自己需要什么时用：

下一步

Last updated on