工具

本页定义 Holon 面向模型的工具接口的当前契约：工具家族、权限分类、 schema/分发对齐，以及结果信封约定。

内置面向模型工具的机器可读清单是 model-tool-schema-inventory.json； 它的版本策略和刷新流程记录在 模型工具 schema 清册参考。

Last verified: 2026-05-27 against src/types.rs ToolCapabilityFamily, src/tool/tools/mod.rs builtin_tool_definitions(), src/tool/spec.rs, src/tool/dispatch.rs.

源 RFC

• 工具接口分层
• 工具契约一致性
• 工具结果信封
• 任务接口收窄
• 命令工具家族
• Apply Patch 统一 Diff 契约
• Exec Command Batch

工具家族（ToolCapabilityFamily）

工具按能力家族分组，用于权限门控：

操作者通知记录、投递回调和 UI 渲染仍是运行时拥有的能力。它们不属于面向模型的 工具清单；NotifyOperator 有意不出现在内置工具注册表和机器可读 schema 清单中。 ExternalTrigger 工具目前遵循同样的模式：它们在注册表中可分发，但不在面向模型的 接口中。

完整工具列表

工作项平面

任务控制平面

Agent 平面

定时器平面

模型平面

图像平面

工作区平面

记忆平面

Web 平面

工具定义契约

每个工具由一个 BuiltinToolDefinition 定义：

BuiltinToolDefinition {
    family: ToolCapabilityFamily,
    spec: ToolSpec { name, description, input_schema, freeform_grammar },
}

关键契约：

• 工具 schema 必须与用于解析参数的运行时类型一致。
• 工具参数结构体强制启用 serde(deny_unknown_fields)。
• ToolSpec 中的 description 字段是模型可见的指引文本。
• 提示层级的工具指引（在 AGENTS.md 或系统提示中）不得与工具自身的描述冲突。

输入与结果分离

Holon 严格区分工具的启动输入与结果元数据：

• 启动输入：cmd、workdir、shell、login、tty、duplicate_policy、 accepts_input、yield_time_ms、max_output_tokens。
• 结果元数据（在启动输入中无效）：status、task_handle、disposition、 exit_status、output_preview。

关键契约：

• 把结果字段当作启动输入传入是错误。
• 模型不得混淆两个接口。提示指引通过有效/无效启动示例明确记录这一区别。

结果信封

工具执行返回一个 ToolResult，可序列化为 JSON，或渲染为人类可读回执：

• 规范结果： 结构化 JSON，包含 content（text/tool_use 块数组）和可选的 artifacts。
• 人类可读回执： 展示给模型的渲染文本；可以省略内部字段，但必须保留语义上 重要的内容。

ExecCommand 结果带有额外字段：disposition、exit_status、 initial_output_preview，以及 task_handle（在提升为 command_task 时）。

WaitFor 交付模式与等待所有权

WaitFor 记录显式等待状态并让出当前轮次。每次调用必须显式指定交付模式：

• delivery=final：当前轮次在进入等待前必须发布非空的面向操作者最终简报。运行时提交等待条件并等待模型生成最终文本，模型在该轮只能回复最终文本，不能再调用工具。
• delivery=silent：无需操作者可见简报；运行时直接结算等待状态，不再启动额外的模型轮次。

核心契约：

• 必填参数：reason（非空说明）、wake（task_result、operator_input、external、timer 或 system）以及 delivery（final 或 silent）。
• 原子结算：运行时将交付模式、等待注册、工具证据、轮次终态与队列终态合并在同一个原子事务中提交。陈旧的任务、执行绑定、WorkItem 版本、唤醒或插话无法发布过期的等待报告。
• 任务结果等待所有权：对于 wake=task_result，等待的所有权严格解析自任务创建时捕获的所有者。切换 WorkItem 焦点（通过 PickWorkItem 或 CreateWorkItem）绝不会迁移后台任务或绕过其捕获的所有权边界。

已知缺口

• 工具描述文本在 Rust 源码中手工维护；没有自动化校验时，描述与实际行为可能漂移。
• ExecCommandBatch 和单次 ExecCommand 调用共享字段，但有效字段子集不同； 类型层面没有结构化的 schema 阻止把仅属于批次的字段传给单次 ExecCommand。