在 OpenCode 上使用 taskflow

在 OpenCode 上将 taskflow 注册为 MCP 服务器，编排多阶段工作流。

OpenCode 是 taskflow 的天然宿主：它本身就以 subagent 的方式思考，而 taskflow 给这些 subagent 提供了一个声明式图来运行。在 OpenCode 上，taskflow 以零依赖 MCP 服务器的形式暴露，taskflow_* 工具出现在会话中，每个阶段的 subagent 作为隔离的 opencode run 进程运行。

本页带你走完整个流程：注册 MCP 服务器、确认它已就绪、通过工具调用运行一个 flow，并理解权限与模型解析模型。

安装

OpenCode 没有基于 git 的插件市场，所以你直接注册 MCP 服务器——用 CLI 或编辑 opencode.json。

方式 A：CLI

通过 CLI 注册 MCP 服务器

opencode mcp add taskflow -- npx -y -p opencode-taskflow opencode-taskflow-mcp

方式 B：编辑 opencode.json

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "taskflow": {
      "type": "local",
      "command": ["npx", "-y", "-p", "opencode-taskflow", "opencode-taskflow-mcp"],
      "enabled": true
    }
  },
  "skills": {
    "paths": ["./node_modules/opencode-taskflow/plugin/skills"]
  }
}

command 通过 npx 运行（一个版本锁定的 opencode-taskflow），服务器按需拉取并启动——无需全局安装其他东西，锁定绑定了确切运行的代码。

skills.paths 条目是可选的。OpenCode 会自动发现 **/SKILL.md skill（包括 Claude Code 的 .claude/skills），而 taskflow 工具是自描述的，所以路由 skill 只是帮助 OpenCode 在合适时机调用它们。一个可直接复制的 opencode.json 随包的 plugin/ 目录提供。

验证安装

在运行任何东西之前，确认 MCP 服务器干净地注册了：

验证 MCP 服务器

opencode mcp list   # 应出现 taskflow，enabled

如果缺失，说明 mcp add 步骤未完成——重新运行并检查错误。

运行你的第一个 flow

在 OpenCode 上，你不通过斜杠命令调用 taskflow——你通过 MCP 工具调用它。模型在路由 skill 的引导下决定何时调用。所以最自然的开始方式就是直接描述工作。

直接问

在 OpenCode 会话中试试这些：

用自然语言描述工作

> List my saved taskflows.
> Verify this flow, then run it: {name:"review-changes", phases:[...]}
> Run the "review-changes" taskflow with dir set to src.

skill 会把请求路由到正确的工具。如果当前项目保存了一个 flow，模型会带保存的名称调用 taskflow_run；如果你粘贴了内联定义，它则传递定义。

直接调用工具

如果你想显式调用——在脚本里或你确切知道结构时很有用——工具是 taskflow_run。它接受保存的 flow name 或内联 define：

通过 taskflow_run 运行保存的 flow

{
  "name": "review-changes",
  "args": { "dir": "src" }
}

通过 taskflow_run 运行内联 flow

{
  "define": {
    "name": "quick-review",
    "phases": [
      {
        "id": "discover",
        "type": "agent",
        "agent": "scout",
        "task": "List changed source files under src/. Output ONLY a JSON array of {path} objects.",
        "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.",
        "dependsOn": ["discover"],
        "concurrency": 4
      },
      {
        "id": "summarize",
        "type": "reduce",
        "from": ["review-each"],
        "agent": "writer",
        "task": "Combine these reviews into one prioritized summary:\n{steps.review-each.output}",
        "dependsOn": ["review-each"],
        "final": true
      }
    ]
  }
}

两种形式运行同一个 DAG。工具只返回最终输出——discover、review-each 和 summarize 的中间 transcript 留在运行时内，永远不会进入你的上下文。

只有标记了 final: true 的阶段会被返回。其余一切在设计上就是上下文隔离的。

在花费 token 之前检查 flow

在运行 DAG 之前，你可以让 OpenCode 静态校验它。这能捕获环、悬空的 dependsOn、未知的阶段引用以及格式错误的配置——全部零 token 成本：

通过 taskflow_verify 校验 flow

{
  "name": "review-changes"
}

或者把 DAG 渲染成图来目测其形状：

通过 taskflow_compile 把 flow 编译成图

{
  "name": "review-changes"
}

taskflow_compile 返回按拓扑层分组的 DAG 文本大纲，外加一个内联 SVG 图像（供能渲染图像的客户端使用）。

subagent 如何运行

每个阶段的 subagent 作为隔离的 opencode run 进程运行——一个真正的 OpenCode 会话，不是 pi 进程。服务器从其启动 cwd 发现已保存的 flow 和 agent，所以你在哪个项目启动它决定了哪些 flow 可见。

权限映射

OpenCode 没有按运行的 tool-whitelist 标志，但它支持通过 OPENCODE_CONFIG_CONTENT 环境变量注入的按进程配置。运行时把每个阶段的工具白名单映射到一个权限策略：

阶段工具	权限策略	含义
只读（无 `write`/`edit`/`bash`）	注入一个拒绝 bash/write/edit 的策略	被拒绝的工具调用会被真正拒绝（而非仅未批准）。这是真正的强制，更接近只读 OS 沙箱而非咨询式白名单。
变更（或无白名单）	`opencode run --auto`	自动批准每个权限——workspace-write 的类比。只运行你信任的 flow，最好在一次性 worktree（`cwd: "worktree"`）中。

变更阶段以 --auto 运行，自动批准每个权限。对涉及文件系统的 flow，优先使用一次性 worktree（cwd: "worktree"），并只运行你信任的 flow。

模型解析

OpenCode 模型 id 是 provider/model（如 anthropic/claude-sonnet-4-5）。因为合法的 OpenCode id 包含斜杠，运行时不会复用 codex/claude 的"包含 / ⇒ 丢弃"规则。它只丢弃明显不是 OpenCode 模型的 id：

未解析的 role 占位符（{{fast}}）
pi 的 thinking 后缀（…:xhigh）
多段 openrouter 路径（openrouter/vendor/model，≥ 2 个斜杠）

被丢弃的 id 会回退到 OpenCode 配置的默认模型。

长时运行的 flow

关于在 OpenCode 上运行 taskflow，你需要知道一件事：taskflow_run 是同步的。 工具调用在整个 DAG 完成之前不会返回——每个阶段、每个 subagent。对三阶段审查这没问题；对五十个文件的扇出加末尾的 tournament，可能要花一阵子。

如果一个 flow 确实很大，考虑把它拆成几个较小的 taskflow_run 调用，让每个都能及时返回，或者从普通 shell 在后台运行：

在后台运行 flow

opencode run "run the nightly-audit taskflow" &

然后用 taskflow_peek 事后检查运行：

通过 taskflow_peek 查看某阶段的存储输出

{
  "runId": "run_2026-07-04_abc123",
  "phaseId": "summarize"
}

省略 phaseId 可列出每个阶段及其状态和输出大小。输出会被硬截断（默认 4000 字符），所以 peek 永远不会淹没你的上下文。

taskflow_peek 是 taskflow 上下文隔离的唯一有意例外。它把中间输出拉进你的对话——只用于调试，不要作为正常流程的一部分。

MCP 模式下的审批

MCP 驱动的运行是非交互的，所以 approval 阶段会自动拒绝（fail-open）。在你通过 taskflow_* 工具运行的 flow 中，优先使用 gate（agent 审查）；approval 只用在人工交互运行的 flow 中。

工具参考

以下是服务器暴露的完整 MCP 接口：

工具	用途
`taskflow_run`	运行保存的 flow（按 `name`）或内联定义（按 `define`）。返回最终输出 + 一个 `runId`。
`taskflow_list`	列出从 cwd 可发现的保存 flow，附带库元数据（如有）。
`taskflow_show`	显示保存 flow 的定义及其库 sidecar 元数据。
`taskflow_save`	把 flow 保存到库，可选 `purpose`、`tags`、`notes`。
`taskflow_search`	在编写前搜索库。返回排序后的可复用 flow。
`taskflow_verify`	静态校验 flow（环、引用、配置），零成本。
`taskflow_compile`	把 DAG 渲染为文本大纲 + 内联 SVG。
`taskflow_peek`	查看某次运行中某阶段的存储输出，用于事后调试。

你很少需要记住这些。内置 skill 会告诉 OpenCode 哪个工具适合请求——"verify this flow"、"show me the diagram"、"run it" 都能自动正确路由。

备选：从仓库检出运行

如果你不想安装包，从本仓库检出构建，并让 OpenCode 指向构建好的 bin：

从检出注册

pnpm run build
opencode mcp add taskflow -- node /abs/path/to/taskflow/packages/opencode-taskflow/dist/mcp/bin.js

服务器的行为与 npx 版本完全相同。

卸载

如果你需要从某台机器移除 taskflow：

移除 taskflow MCP 服务器

opencode mcp remove taskflow    # 或删除 opencode.json 中的 mcp.taskflow 条目

磁盘上任何已保存的 flow 定义都不受影响。