TaskOutputTool：读取任务输出
2026/8/2 16:24:29 · 来源
深入理解 TaskOutputTool 如何将 shell、本地 agent 和远程 agent 的任务输出统一为一致结构，并掌握其设计理念与演进方向。
它把后台任务输出统一成同一种可读结果
TaskOutputTool 用来读取后台任务的输出。
它最重要的价值是统一：
- shell 任务输出
- 本地 agent 输出
- 远程 agent 输出
所以主线程不需要关心底层任务类型差异，只要关心统一返回结构。
关键源码
输入定义：
const inputSchema = z.strictObject({
task_id: z.string(),
block: z.boolean().default(true),
timeout: z.number().min(0).max(600000).default(30000),
})
统一输出对象：
type TaskOutput = {
task_id: string;
task_type: TaskType;
status: string;
description: string;
output: string;
}
它还有一个很有意思的现状
源码 prompt 明写了：
DEPRECATED: Prefer using the Read tool on the task's output file path instead.
也就是说，它仍然存在，但 Anthropic 已经在把“读任务输出”引导到更通用的 Read 工具。
这对学习源码很有价值，因为你能看到 Claude Code 运行时能力如何逐步收敛。
调用链
主线程想看后台结果 > TaskOutputTool > 读取 task 状态 > 必要时等待完成 > 统一抽取输出 > 回给主线程
小结
TaskOutputTool 是后台任务链路里的“统一读口”，即使它未来可能被更通用的 Read 替代。
学习地图
📚 TaskOutputTool 学习路线图
阶段一：理解底层机制
- 认识三种任务类型（shell / 本地 agent / 远程 agent）的差异
- 理解统一输出接口
TaskOutput的结构及其各字段含义 - 掌握
inputSchema参数的作用：task_id、block、timeout
阶段二：掌握调用链
- 追踪主线程发起请求 → TaskOutputTool → 任务状态读取 → 等待完成 → 输出返回的完整链路
- 理解 block 模式（同步等待）和 non-blocking 模式的区别
- 分析 timeout 参数的失效边界与重试策略
阶段三：架构演进洞察
- 对比 TaskOutputTool 与通用 Read 工具的职责差异
- 理解为何 Anthropic 将功能收敛到更通用的 Read 工具
- 体会从专用工具到统一接口的设计收敛趋势
动手实践——分步指南
- 在 Claude Code 源码中定位 TaskOutputTool 的实现文件，阅读其 inputSchema 定义
- 对照三种任务类型（backend tasks），分别构造一个 shell 任务、本地 agent 任务和远程 agent 任务，观察输出差异
- 调用 TaskOutputTool 的读取接口，验证返回结构是否为统一的 TaskOutput（含 task_id、task_type、status、description、output 字段）
- 通过修改 block=true/false，分别测试同步等待和异步轮询两种模式的行为差异
- 将 timeout 设置为短于任务实际耗时（如 100ms），观察超时被触发时的状态反馈
- 阅读 TaskOutputTool 源码中对 Read 工具的替代说明，对比两者的能力边界
三大推荐资源
- 1Claude Code GitHub 仓库
Anthropic Claude Code 的官方开源实现，可从中直接查阅 TaskOutputTool 的源码与设计文档。
https://github.com/anthropics/claude-code
- 2Anthropic 官方博客文章
Anthropic 工程团队发布的官方文章，包含 Claude Code 架构演进与工具设计理念的说明。
https://www.anthropic.com/engineering
- 3Agent 模式化输出设计（Pattern: Unified Output Channel）
关于 Agent 中统一输出通道的通用设计模式的教程与最佳实践。
https://www.aipatterns.io/tool-design/unified-output-channels
链接由 AI 推荐——使用前建议快速核实。