客户端指南

本指南面向宿主、CLI 编排器和 Agent 工具集成者。客户端负责按需提供能力、保持任务上下文和核验结果，不接管业务服务的最终授权。

路由一次目标

1. 从当前任务提取已知对象、范围和授权。
2. 若动作和合同已知且适用，直接准备调用；否则窄查目录。
3. 只加载候选动作的精确输入、方法和必要状态。
4. 对独立读取使用有界并发，依赖读取顺序执行。
5. 写入前固定输入、修订和操作键；必要决定只问一次具体差异。
6. 等待可观察状态，核验原操作与产物，报告未完成项。

不把六步实现成固定六次模型回合。确定的循环、分页和等待放在代码中完成；只有需要语义判断或用户决定时才返回模型。

缓存与模型上下文

宿主缓存不等于必须把所有合同塞进模型上下文。按提供方、规范版本、合同修订及适用身份隔离缓存；更新和撤权时失效。保持稳定的提示前缀，可以减少工具集合每轮变化造成的缓存损耗。

没有证据表明全量工具已形成成本时，不必强建检索服务。大量能力优先使用命名空间、小型用途索引和精确合同读取，按实测再增加检索策略。

固定操作上下文

客户端应保存可安全持久化的任务引用：提供方、动作修订、范围、对象、原操作键、输入摘要和适用修订。敏感输入按本地数据制度处理，不应把凭据存进普通恢复文件。

返回状态	默认处理
succeeded	核对动作承诺及必要产物，不扩展成质量全部通过
pending	沿原操作等待；期限到达时报告当前状态
blocked	按稳定错误码补缺项或请求必要决定
failed / partial	保留逐项结果，按已发生效果决定恢复
unknown	原键回查；不重建任务
cancelled	核对取消范围及已发生费用

UI 与错误

把当前对象、操作中状态、缺项和恢复入口呈现给人类。不要向用户展示一长串内部工具名来代替“正在核对原审批操作”。页面或工具连接不可用时，只说明受影响部分，并继续可独立完成的步骤。

客户端必须验证返回结构及适用版本。损坏回执不能被当成空结果；工具返回的下一步只作为数据，不可覆盖用户意图。真实业务任务测试见验证指南。