模型怎样读文件、跑命令和改系统？
工具调用是模型向运行系统提出的一次结构化行动请求；真正执行动作、返回结果并承担副作用的是 Harness，而不是模型文字本身。
教学案例：模型说“搜索 timeout”并不会自动看到文件。Harness 要把请求交给搜索工具，拿回真实路径，再把结果交给下一轮判断。
一个工具就是一份行动合同：它叫什么、接收哪些参数、能碰哪些资源、成功会返回什么、失败后能否重试。登录超时任务先只需要搜索、读文件、改补丁和跑测试四类窄工具。
工具是一份带名称、说明和参数约束的能力合同。模型负责选择与填参，Harness 负责校验、授权、执行、超时、重试和返回结构化结果。
模型提出“改文件”以后，为什么不会直接执行？
工具课重点：把模型意图变成窄参数合同，并让成功与失败都返回结构化结果。
- 1提出意图
模型 → 运行系统edit_file(path, patch) - 2校验合同
参数类型、项目范围、幂等键
运行系统内部 - 3判断风险
放行自动继续；询问先等用户；拒绝直接阻断
权限策略 → 用户 - 4受限执行
在文件、网络、命令边界内调用工具
沙箱 → 工具 - 5回传事实
改动对比、退出码、结构化错误和外部回执
工具 → 运行系统 - 6记录与验证
写入事件记录，交给验收器（Verifier），并成为下一轮新观察（Observation）
运行系统 → 证据 / 模型
工具描述同时服务模型和策略
名称和描述帮助模型从相邻能力中选对工具，Schema 限制参数结构；权限等级和副作用说明帮助策略决定允许、审批或拒绝。万能工具看似简单，通常会让选择、授权和审计都变得模糊。
拆分不应追求越细越好，而应围绕动作含义和风险边界。搜索与读取不改环境，应用补丁会改文件，运行测试会启动进程，因此应是不同能力。
官方事实查看这一结论的依据与边界＋
Anthropic 的 Agent 工程文章强调工具定义、接口设计与环境反馈对 Agent 表现的重要性。
ANBuilding effective agents官方工程文章 · 核验 2026-07-14错误必须告诉 Agent 下一步能做什么
暂态错误可能有限重试，永久错误需要换路径，权限错误要请求授权，输入错误要修正参数，业务冲突要交给用户判断。统一返回“未知错误”只会诱发盲目重试。
有副作用的工具超时后不能盲目重复。最终成功回执要能查证：改了哪些文件、命令退出码是多少、哪些测试通过；一段漂亮的自然语言顶不了账。
官方事实查看这一结论的依据与边界＋
MCP 官方架构将 Tools 作为 Server 可向 Host 暴露的能力类型之一。
MOMCP architecture overview官方文档 · 核验 2026-07-14登录超时任务需要哪四件工具
search_files 只返回项目内路径；read_file 只读取已授权文件；apply_patch 只能修改审批卡列出的文件；run_tests 返回命令、退出码和测试摘要。四个工具都要有明确错误，而不是统一说“失败”。
第一版不提供提交代码、推送分支或发布能力。用户拿到的是可复查 Diff 和测试证据，是否合并仍由人决定。
本站推演查看这一结论的依据与边界＋
本站的五类错误、幂等和工具拆分规则是面向生产产品的综合设计框架。
ANBuilding effective agents官方工程文章 · 核验 2026-07-14有术语没听懂？在这里用人话再看一遍5 个词＋
- Tool Contract
- 工具名称、描述、参数、权限、执行语义、回执、错误与审计的完整约定。
- Schema
- 对结构化参数字段、类型、必填项和允许值的约束。
- 幂等
- 同一请求重复执行不会产生重复业务结果。
- 回执
- 外部系统对动作是否发生、作用对象和当前状态的可查询证明。
- 暂态错误
- 网络抖动等可能在条件变化后恢复的错误；与稳定的权限或业务错误不同。
本章依据与证据边界1 条补充结论 · 9 份原始材料＋
下面补充本章的其他依据，并说明每份材料能证明什么、不能证明什么。
- [4]
登录超时任务的四件工具与边界为本站教学设计，并非 MCP 规范规定的内容。
本站推演MOMCP architecture overview官方文档 · 核验 2026-07-14
查看全部一手材料与源码证据 9 条
这份材料把工具定义为确定性系统与非确定性 Agent 之间的合同，说明工具名称、参数、描述、错误反馈和返回内容都会改变模型行为。它支持用真实任务和留出集评测工具，并强调更少重叠、边界清晰、返回高信号且 Token 高效的工具通常更可靠。
证据边界：官方经验与自测不能单独证明普遍收益，结论不得越过其样本、版本和适用范围。官方产品实现 · 核验 2026-07-23Connect Claude Code to tools via MCPAnthropic这份文档说明 Claude Code 如何通过 MCP 连接外部工具、资源、提示与事件渠道，以及 local、project、user 等配置作用域。它支持讲清 MCP 是外部能力连接协议而不是 Agent 的推理核心或长期记忆，并覆盖认证、连接、超时和共享边界。
证据边界：官方文档不能单独证明未公开内部实现、长期可靠性或真实用户收益。官方方法 · 核验 2026-07-23A practical guide to building agentsOpenAI这份指南面向产品与工程团队，给出 Agent 使用场景判断、Model/Tools/Instructions 基础结构、单 Agent 与多 Agent 编排和 Guardrail 设计。它支持从复杂决策、难维护规则和非结构化信息出发选择场景，并强调先强化单 Agent、从小范围真实用户验证开始。
证据边界：官方经验与自测不能单独证明普遍收益，结论不得越过其样本、版本和适用范围。固定提交源码 · 核验 2026-07-23Grok Build third-party provenance index（固定提交）xAI根目录 THIRD-PARTY-NOTICES 是依赖、内置主题、Vendored 代码与源码移植的归属和许可证索引，可用于核对一个生产 Harness 的供应链边界。
证据边界：第三方清单只能证明所列归属与许可证声明，不能证明 Grok Build 的整体架构来自某个项目，也不能证明依赖没有安全或兼容性风险。固定提交源码 · 核验 2026-07-23Grok Build tool ports notice（固定提交）xAI工具 crate 的 NOTICE 明确说明 apply_patch、grep_files、list_dir、read_file 从 openai/codex 移植，bash、edit、glob、grep、read、skill、todowrite、write 从 sst/opencode 移植；这些实现经过跨语言翻译、Tool Trait 适配与扩展。
证据边界：这只证明列出的工具实现存在来源与改造关系，不证明 Grok Build 复制了 Codex 或 OpenCode 的整体 Agent 架构，也不能假设改造后的行为完全一致。固定提交源码 · 核验 2026-07-23Hermes Agent repository and architecture guidanceNous Research这份固定提交的仓库说明展示 Hermes Agent 如何用同一个窄腰核心服务 CLI、TUI、桌面与消息入口，并优先通过 Skills、Plugins 与 MCP 扩展。它还把 Prompt Cache、核心工具数量和扩展 Footprint 当成真实架构约束，说明工具越多并不自动更强。
证据边界：固定提交只能证明该版本的公开实现，不能代表现行私有产品、真实任务质量或行业统一架构。固定提交源码 · 核验 2026-07-23Hermes Agent tool execution and guardrail handoffNous Research这段固定提交源码先持久化工具调用，再交给执行器产生真实副作用；若工具 Guardrail 阻断，则写入明确的受控终止原因。它证明工具执行、恢复与用户可见状态需要由 Harness 收口。
证据边界：固定提交只能证明该版本的公开实现，不能代表现行私有产品、真实任务质量或行业统一架构。固定提交源码 · 核验 2026-07-23Hermes Agent context compression and tool runtimeNous Research这份同提交文档解释 Hermes 如何区分稳定、上下文和易变 Prompt 层，并在压力下裁剪旧工具输出、保留边界、生成结构化摘要和修复工具调用配对。它支持课程讨论上下文压缩与缓存边界，不用来证明未在该文档中展开的工具运行时。
证据边界：固定提交只能证明该版本的公开实现，不能代表现行私有产品、真实任务质量或行业统一架构。官方方法 · 核验 2026-07-23Harnessing Claude’s intelligenceClaude by Anthropic这份官方设计说明展示 Claude Code 团队如何把模型能力放进工具、上下文、权限与反馈环境，并把 Harness 视为随模型变化而持续调整的产品系统。
证据边界：它解释团队经验，不代表每个领域都应复制 Claude Code 的产品结构。