企业官网建设流程全解析

DeepSeek Agent Harness 2026终极指南 - 第9章第44节 工具返回值设计：结构化与token经济学

第40-43节我们做了文件、bash、检索、联网四件套，Agent已经能读改写代码、跑命令、找代码、查文档。但工具返回值的设计还有很多讲究——返回太多占上下文，返回太少模型看不懂。这节讲工具返回值设计：结构化格式、token经济学、返回值如何影响模型决策。这是工具开发的"最后一公里"。

本文导航

• 为什么返回值设计很重要
• 结构化返回值：成功/失败统一格式
• 超大输出截断策略
• 返回值如何影响模型决策
• 实证对比：好返回值 vs 坏返回值
• 小结

为什么返回值设计很重要

工具返回值是模型理解工具执行结果的唯一途径。设计不好，模型会：

1. 误解结果：返回"成功"，模型不知道成功了什么
2. 浪费token：返回1万字，模型看不完，上下文爆炸
3. 决策错误：返回信息不全，模型做出错误判断

好的返回值设计：

• 结构化：成功/失败统一格式，模型容易解析
• 精简：只返回必要信息，节省token
• 明确：告诉模型发生了什么、下一步该做什么

结构化返回值：成功/失败统一格式

很多工具返回的是纯字符串，如"成功"、“失败”。模型很难判断是成功还是失败。

解决方案：统一结构化格式。

@tooldefsome_tool(param:str)->str:"""工具描述"""try:# 执行逻辑result=do_something(param)# 成功：返回结构化信息returnf"""成功： - 操作：{param}- 结果：{result}- 下一步：可以继续执行其他操作"""exceptExceptionase:# 失败：返回错误信息和建议returnf"""失败： - 操作：{param}- 错误：{str(e)}- 建议：检查参数是否正确，或尝试其他方法"""

关键点：

1. 明确标识成功/失败：开头写"成功：“或"失败：”
2. 包含关键信息：操作、结果/错误、下一步建议
3. 格式化输出：用换行、列表，方便模型解析

超大输出截断策略

有些工具返回大量数据：

• read_file读大文件
• grep搜索大量匹配
• web_fetch抓取长网页

如果不截断，会占满上下文窗口。

截断策略：

MAX_OUTPUT=4000# 最大输出字符数deftruncate_output(output:str,max_length:int=MAX_OUTPUT)->str:"""截断超长输出"""iflen(output)<=max_length:returnoutput# 截断并提示truncated=output[:max_length]returnf"{truncated}\n\n[输出已截断，共{len(output)}字符，已显示前{max_length}字符]"

关键点：

1. 默认4000字符：约1000-2000 token，对模型够用
2. 提示总长度：让模型知道还有多少内容没看到
3. 可选参数：允许调用方指定max_length

返回值如何影响模型决策

返回值不仅告诉模型"发生了什么"，还影响模型"下一步做什么"。

案例1：文件读取

坏返回值：

def add(a, b): return a + b

模型不知道这是哪个文件、第几行。

好返回值：

文件：test_math.py 行号：1-3 内容： 1: def add(a, b): 2: return a + b 3: 下一步：可以用edit_file修改这个函数

模型知道：

• 这是test_math.py的1-3行
• 可以用edit_file修改

案例2：命令执行

坏返回值：

1 passed in 0.01s

模型不知道命令是否成功。

好返回值：

命令：pytest test_math.py -v 状态：成功（返回码 0） 输出： 1 passed in 0.01s 下一步：测试通过，可以继续开发其他功能

模型知道：

• 命令成功（返回码0）
• 测试通过
• 可以继续开发

实证对比：好返回值 vs 坏返回值

我们做一个实验：让Agent修改一个有bug的函数。

实验设置：

• test_math.py里有个bug：add(0, 0)应该返回0，但测试失败
• 让Agent修复bug

坏返回值版本：

工具返回：

test_math.py::test_add FAILED AssertionError: assert 1 == 0

Agent反应：

• 看到"FAILED"，知道测试失败
• 看到"assert 1 == 0"，不知道是哪行代码错了
• 可能盲目修改代码

好返回值版本：

工具返回：

命令：pytest test_math.py -v 状态：失败（返回码 1） 输出： test_math.py::test_add FAILED 失败详情： 文件：test_math.py 函数：test_add 行号：8 错误：AssertionError: assert add(0, 0) == 0 实际值：1 期望值：0 建议：检查add函数在a=0, b=0时的返回值

Agent反应：

• 知道是test_math.py第8行
• 知道是add(0, 0)返回了1而不是0
• 精准定位bug，快速修复

结论：好返回值让Agent决策更准确、更高效。

小结

1. 返回值设计是工具开发的"最后一公里"：设计不好，模型误解、浪费token、决策错误。
2. 结构化返回值：成功/失败统一格式，包含操作、结果/错误、下一步建议。
3. 超大输出截断：默认4000字符，提示总长度，允许调用方指定max_length。
4. 返回值影响模型决策：好返回值让模型精准定位问题，坏返回值让模型盲目猜测。
5. 实证对比：好返回值包含文件、行号、错误详情、建议；坏返回值只有简单错误信息。
6. 设计原则：明确、精简、结构化、可操作。
7. DeepPilot v0.4工具返回值设计完成——工具开发从"能用"升级到"好用"。

下节预告

工具返回值设计好了，但还有一个问题——模型怎么知道该用哪个工具？你让Agent"查一下天气"，它怎么知道要用get_weather而不是web_search？下一节讲工具描述工程：怎么写工具描述让模型用对工具。这是工具开发的"提示词工程"。

如果觉得本文对你有帮助，欢迎点赞、收藏、关注三连！
本系列持续更新中，关注不迷路~