模型工具 schema 清单
本页定义 Holon 面向模型的内置工具接口的版本策略。机器可读清单检入为
model-tool-schema-inventory.json。
- 权威来源：
src/tool/tools/mod.rs的builtin_tool_definitions()，以及 派生schemars::JsonSchema的带类型 Rust 参数结构体。 - 生成的清单：
holon::tool::model_tool_schema_inventory()。 - 漂移检查：
make snapshots-check。 - 当前状态： 1.0 之前的基线。把 stable 标签视为当前轨道打算保持的兼容边界， 而不是最终的 1.0 承诺。
清单内容
每个内置工具条目记录：
- 工具名称
- 能力家族
- 稳定性级别
- 面向模型的输入 schema
- 工具接受非 JSON 输入时的自由格式语法
- 结果信封家族和模型渲染契约
- 当该稳定结果接口属于当前覆盖范围时，带类型的成功结果 JSON Schema
- 当命令是对工具或运行时 API 的封装时，相关的 HTTP 或 CLI 接口
- 模型可见的工具描述
版本 2 清单当前覆盖以下工具的结果 schema：CreateTimer、ListTimers、
GetTimer、CancelTimer、Enqueue、CreateAgent、
SendAgentMessage、InvokeAgent、ListTasks、TaskStatus、
TaskInput、TaskOutput、TaskStop 和 GenerateImage。未覆盖的工具保留其
结果类型名和显式的 null schema；这样可以避免把推断出的或不完整的形状当作
稳定契约。只有当具体 Rust 结果类型派生 schemars::JsonSchema 时，覆盖范围
才能扩展。
能力家族
每个内置工具都属于一个能力家族。运行时在 src/types.rs
（ToolCapabilityFamily）中定义六个家族：
| 家族 | 说明 | 示例工具 |
|---|---|---|
CoreAgent | 核心 agent 操作（状态、消息、记忆、工作项、调度、CLI/配置内省） | SendAgentMessage, MemorySearch, WaitFor, ListWorkItems, AdvisoryDecision |
LocalEnvironment | 工作区本地操作 | ExecCommand, ApplyPatch, ViewImage, GetWorkspaceState, SwitchWorkspace, CreateWorktree |
Web | 公共 Web 访问 | WebFetch, WebSearch |
AgentCreation | agent 创建与受监督调用 | CreateAgent, InvokeAgent |
AuthorityExpanding | 改变工作区权威或销毁已注册产物的工具 | AttachWorkspace, DetachWorkspace, RemoveWorktree |
ExternalTrigger | 外部事件入口 | CreateExternalTrigger, CancelExternalTrigger |
稳定性级别
| 级别 | 含义 |
|---|---|
stable | 名称、输入 schema、结果信封家族和已记录的模型渲染都保持兼容。 |
experimental | 接口可用，但运行时契约尚未定型，仍可能变化。 |
deprecated | 接口为兼容而保留，但不应引入新工作流。 |
命名策略
Holon 原生内置工具名使用 PascalCase，并以动作开头。集合读取用 List*，
单资源或快照读取用 Get*，控制或变更用明确动词，比如 Send*、Stop*、
Create*、Update*。迁移窗口期内调度器可能仍接受旧别名，但检入的清单对外
公布的是规范的、面向模型的名称。
版本策略
顶层 version 字段为清单格式定版本，而不是为每个工具 schema 单独定版本。
- 当清单文件形状的变化需要读取方区别处理时，递增
version。 - 普通的工具增删、输入 schema 变更、描述变更或稳定性标签变更都不递增
version；这些是同一清单格式内的契约变更，通过快照 diff 审阅。 - 保留 Rust 定义作为权威来源。有意的变更应先更新 Rust，再刷新检入的清单。
刷新流程
make snapshots-refresh
make snapshots-check