模型工具 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、TaskStop 和 GenerateImage。未覆盖的工具保留其结果类型名和显式的 null schema；这样可以避免把推断出的或不完整的形状当作稳定契约。只有当具体 Rust 结果类型派生 schemars::JsonSchema 时，覆盖范围才能扩展。

TaskOutput 已从模型工具接口移除，而非仅标记为弃用。改用 TaskStatus、运行时确认的命令输出文件的有界读取，以及 Agent 级 tail 观测；完成等待和重新进入使用 WaitFor(task_result)。底层 HTTP task-output 路由与内部 result/capture 服务仍保留。边界详见任务契约。

能力家族

每个内置工具都属于一个能力家族。运行时在 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