在 OpenCode 上使用 taskflow

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

OpenCode 通过协议层不依赖 MCP SDK 的 MCP server 暴露 taskflow；每个阶段作为隔离的 opencode run 进程运行。

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

安装

要求 Node.js ≥ 22.19.0。

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

方式 A：CLI

通过 CLI 注册 MCP 服务器

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

方式 B：编辑 opencode.json

opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "taskflow": {
      "type": "local",
      "command": ["npx", "-y", "-p", "opencode-taskflow@beta", "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`）	`--pure` + 注入默认拒绝策略	禁用外部插件；仅允许已知的读取/列举/搜索内置工具，因此继承的自定义与 MCP 工具也会被拒绝。
变更（或无白名单）	默认拒绝	仅对可信 flow 设置 `PI_TASKFLOW_OPENCODE_UNSAFE_AUTO=1` 才启用无 sandbox 的 `--auto`；`--pure` 始终保留。

OpenCode 没有 OS sandbox 兜底。unsafe auto 需要运维方显式 opt-in；优先使用一次性 worktree，且只运行可信 flow。

子进程只继承平台、代理/CA、OpenCode 配置与受支持 provider 变量；无关的父进程 secret 会被移除。确需额外任务变量时，通过逗号分隔的 PI_TASKFLOW_CHILD_ENV_ALLOW 显式列出变量名。

模型解析

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

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

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

长时运行的 flow

taskflow_run 默认同步。长 flow 可设置 mode: "background"；MCP 调用会立即返回持久化 runId。使用 taskflow_runs 列出、查看、等待或取消该 worker。

然后用 taskflow_peek 事后检查运行：

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

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

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

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

MCP 模式下的审批

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

工具参考

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

工具	用途
`taskflow_run`	运行保存的 flow（按 `name`）或内联定义（按 `define`）。返回最终输出 + 一个 `runId`。
`taskflow_runs`	列出后台运行，或按 `runId` 执行 `status` / `wait` / `cancel`。
`taskflow_resume`	把失败或暂停运行 fork 为新的不可变子运行，可覆盖一个阶段。
`taskflow_version`	报告包版本、构建 commit、schema 版本、构建时间与 host。
`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`	查看某次运行中某阶段的存储输出，用于事后调试。
`taskflow_trace`	读取运行的 append-only 事件时间线。
`taskflow_replay`	离线重放已记录决策，不调用模型。
`taskflow_why_stale`	零 token 解释依赖为何 stale。
`taskflow_recompute`	报告 stale frontier（MCP 仅 dry-run）。
`taskflow_reconcile_workspace`	检查/修复 dirty-unknown 的 resolve-only 工作区后显式接受当前状态。

你很少需要记住这些。内置 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 定义都不受影响。