Harness 工程 · 第 4 章 工具系统

Harness 工程 · 第 4 章 工具系统

章节摘要：工具系统是模型的手脚，也是 harness 与模型之间唯一的 API 边界——模型看不见你的代码，只看得见工具的 schema，所以"工具定义即文档"，schema 的质量直接决定模型用得对不对。4.1 讲注册与 Schema：把工具做成 API 契约（名称、描述、参数 JSON Schema、返回值），并给出装饰器注册器 registry.py——本书第二块积木；4.2 讲工具选择与路由：默认交给模型自选（function calling），但工具一多、模型一贵，就需要在模型前面加路由器——规则路由或判断原语路由（详见《Jev 决策编程》第 6.2 节），把几十个工具筛成小子集再让模型精挑；4.3 讲错误反馈设计：错误消息是写给模型看的接口，"把失败变成信息"的四个要素（类型、原因、线索、下一步），配结构化返回与重试纪律。章末把工具系统与主循环接驳，交棒第 5 章权限门。

学习目标

阅读完本章，你应当能够：

1. 写出工具四要素契约，并解释"schema 即文档"的含义。
2. 实现装饰器注册器，从函数签名自动生成 JSON Schema。
3. 按给工具写描述的清单自查并改进一个工具定义。
4. 说明模型自选、规则路由、判断原语路由三种方式的适用边界。
5. 设计结构化错误返回，并区分可重试与不可重试错误。

核心概念速览

（文字流程图）
S ──▶ "选择与路由·模型自选 or 路由器筛子集"
"选择与路由·模型自选 or 路由器筛子集" ──▶ "执行 + 错误反馈·结构化返回，失败也是信息"
"执行 + 错误反馈·结构化返回，失败也是信息" ──"结果 / 结构化错误"──▶ "主循环回填"
​

一句话金句：模型看不见你的代码，只看得见你的 schema——工具定义写得含糊，等于把 API 文档写成谜语。

子章节导航

4.1 注册与 Schema：工具即 API 契约

四要素契约、装饰器注册器 registry.py（约 45 行）、工具描述写作清单、工具分类学（读/写/执行/检索/委派）。

4.2 工具选择与路由

模型自选的适用区与三个退化信号（准确率、L3 税、延迟）；规则路由与判断原语路由（约 100ms 语义判断，详见《Jev 决策编程》第 6.2 节）；工程主流的两段式混合：路由器筛子集、模型在子集内精挑。

4.3 错误反馈设计：把失败变成信息

错误是写给模型的接口；结构化错误四要素（类型/原因/线索/下一步）；
四类错误（用户错/环境错/权限拒/系统错）各自的反馈与重试策略；
与 3.2 节熔断器的两级衔接——单次失败工具级重试，失败复利循环级熔断。

子章节之间的逻辑关系

4.1 注册与 Schema（工具怎么定义：契约与文档）
   │
   ▼
4.2 选择与路由（工具怎么被选中：模型自选 vs 外部路由）
   │
   ▼
4.3 错误反馈（工具失败后怎么反馈：错误也是接口）
​

前置知识与后续延伸

前置知识：第 3 章 mini_loop.py（本章产物将替换它的 TOOLS 手写清单与 TOOL_FUNCS 字典）；JSON Schema 基础。

为后续奠定基础：4.1 的工具分类学（读/写/执行）是第 5 章 allowlist 作用域设计的输入；4.3 的结构化错误是 5.3 节"被拦截也是一种错误反馈"的基础；registry.py 是第 10 章 mini-harness 的工具层。