在 Grok Build 上使用 taskflow

将 taskflow 作为 Grok Build 插件安装，通过 MCP 编排多阶段工作流。

Grok Build 是 xAI 的终端编码 agent。Taskflow 的正式发布路径是 MCP server；仓库 checkout 另带 plugin scaffold。

本页覆盖安装、验证、首次运行、权限与长时 flow。完整说明见仓库 docs/grok-mcp.md。

安装

已发布 MCP 包（推荐）

grok mcp add taskflow -- npx -y -p grok-taskflow@0.2.0 grok-taskflow-mcp

要求 Node.js ≥ 22.19.0。MCP 协议代码不依赖 MCP SDK。公共 Grok plugin marketplace/source 尚未发布；不要代入一个不存在的 source。

从 monorepo checkout 安装 plugin scaffold

包尚未上 npm 时，本地 build 并指向编译后的 bin：

本地 dogfood 安装

pnpm install
pnpm --filter taskflow-core build
pnpm --filter taskflow-mcp-core build
pnpm --filter taskflow-hosts build
pnpm --filter grok-taskflow build

grok plugin install ./packages/grok-taskflow/plugin --trust
grok plugin enable taskflow

grok mcp add taskflow -- \
  node "$(pwd)/packages/grok-taskflow/dist/mcp/bin.js"

已打开的会话请重启，或运行 grok inspect 重新发现插件与 MCP。

运行第一个 flow

在 Grok Build 上通过 MCP 工具调用（search_tool / use_tool，部分 UI 会显示为 taskflow__taskflow_*）。

直接描述

用自然语言描述工作

> 列出我保存的 taskflow。
> 先验证再运行这个 flow：{name:"review-changes", phases:[...]}
> 运行 "review-changes"，dir 设为 src。

直接调工具

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
      }
    ]
  }
}

只有标了 final: true 的阶段会返回；中间 transcript 留在运行时内。

零 token 静态检查

先用 taskflow_verify 查环、悬空依赖与坏配置：

通过 taskflow_verify 验证 flow

{
  "define": {
    "name": "quick-review",
    "phases": [{ "id": "a", "type": "agent", "agent": "executor", "task": "noop", "final": true }]
  }
}

或用 taskflow_compile 渲染 DAG（文本大纲 + 可选内联 SVG）。

子 agent 如何跑

每个 phase 是隔离的 grok -p --output-format streaming-json 进程。MCP 服务器从它的启动 cwd 发现已保存 flow 与 agent。

权限映射

Phase tools	标志	含义
只读（无 write/edit/bash）	运维方配置的自定义只读 sandbox + `--tools read_file,grep,list_dir` + 可变更工具拒绝列表 + `--deny Bash/Edit/Write/MCPTool` + `--no-subagents` + `--always-approve`	只有当 `PI_TASKFLOW_GROK_READONLY_SANDBOX_PROFILE` 指向继承 `read-only` 的自定义 profile 时才运行。Web 工具仍被禁用。
可写 / 无白名单	运维方配置的自定义 sandbox + `--always-approve`	只有当 `PI_TASKFLOW_GROK_MUTATING_SANDBOX_PROFILE` 指向自定义 profile 时才运行。Grok 内置 profile 在无法应用时可能警告后无 sandbox 继续，因此 runner 会拒绝内置 profile。

Grok 0.2.93 会把 web_search / web_fetch 报为无法映射的 allowlist 项，并可能回退到全量工具；因此只读 phase 中暂时禁用这两个 web 工具，并用独立 deny 规则做二次保护。在 ~/.grok/sandbox.toml 分别配置 [profiles.taskflow-workspace] extends = "workspace" 和 [profiles.taskflow-readonly] extends = "read-only"，启动 MCP server 前导出对应的 PI_TASKFLOW_GROK_MUTATING_SANDBOX_PROFILE 与 PI_TASKFLOW_GROK_READONLY_SANDBOX_PROFILE。max_turns_reached 会使 phase 失败。

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

Grok 0.2.93 的 streaming-json 不返回 token / cost usage，所以 Grok MCP 适配器会拒绝任何声明了 budget 的 flow，而不是静默忽略无法观察的阈值。

自定义 profile 在无法应用时会 fail-closed，但仍会保留其基础 profile 授予的访问。当文件系统变更应视为可丢弃时，请使用一次性 worktree。

工具	用途
`taskflow_run`	运行已保存或内联 flow。返回最终输出 + `runId`。
`taskflow_list` / `taskflow_show`	发现与查看已保存 flow。
`taskflow_save` / `taskflow_search`	写入库 + 搜索。
`taskflow_verify` / `taskflow_compile`	静态检查与 DAG 渲染（零 token）。
`taskflow_peek`	查看已存储运行的中间阶段输出。
`taskflow_trace`	只追加事件日志时间线（子 agent I/O + 决策）。
`taskflow_replay`	离线 what-if 阈值 / 预算重判（零 token）。
`taskflow_why_stale` / `taskflow_recompute`	过期分析（MCP 上 recompute 仅 dry-run）。

手动注册 MCP

手动注册

pnpm add -g grok-taskflow
grok mcp add taskflow -- grok-taskflow-mcp

卸载

grok plugin uninstall taskflow
grok mcp remove taskflow

下一步

Last updated on

在 Grok Build 上使用 taskflow

安装

已发布 MCP 包（推荐）

从 monorepo checkout 安装 plugin scaffold

验证安装

运行第一个 flow

直接描述

直接调工具

零 token 静态检查

子 agent 如何跑

权限映射

长时 flow

MCP 下的 approval

工具参考

手动注册 MCP

卸载

下一步

这页内容对你有帮助吗？

On this page