订单状态助手架构记录
决策
使用一套有边界的 Claude 辅助工作流：包含一个进程内只读工具、确定性策略、严格的输出验证和明确的升级处理。
背景
用户需要根据精确的公开订单 ID 获取已验证的订单状态。路径已知，而编造操作的代价很高。目前由一个应用拥有此能力。
组件
- 输入校验器提取公开 ID 格式。
- 信任边界将用户和检索到的内容标记为不可信。
- Claude 可通过类型化工具契约提议
lookup_order。 - 策略门禁只允许带一个参数的只读调用。
- 可信集成代码绑定经认证的用户和租户身份。
- 订单服务返回经过最小化处理的已验证状态。
- Claude 生成结构化最终响应。
- 应用验证 schema、证据、路由状态和追踪。
决策与权衡
工作流优于自主 agent
顺序已知。通用 agent 会增加工具选择和循环风险，却不会改善核心用户结果。
直接工具优于 MCP
一个宿主使用一项能力。直接的类型化处理器具有更少的运维边界。当两个或更多获批准的宿主需要共享发现和治理时，再迁移到 MCP。
自动化能力保持只读
在通过 schema 和策略检查后可以自动查询。退款、取消、地址变更和外部消息需要独立工具、外部批准、幂等性和新的评估。
结构化输出加本地验证
provider 约束的生成可减少语法错误。本地 schema、语义和授权检查仍然是必需的。
默认不使用扩展思考
该工作流是直接查询。新增推理预算必须先证明能带来可测量的质量提升。
被否决的备选方案
- 自由形式 shell 或数据库工具：权限过大且难以验证。
- 宽泛的
manage_order工具：混合读取和修改权限。 - 以对话文本作为批准：未经认证且容易被注入攻击。
- 无限重试：造成成本和副作用不确定性。
- 第一版就使用 MCP：互操作收益尚不足以证明服务器运维合理。
安全边界
- 凭证保留在可信集成代码中。
- 模型参数绝不建立身份或租户。
- 不可信内容不能授予能力。
- 未知工具和参数字段默认拒绝。
- 工具结果在进入模型上下文前最小化。
- 追踪包含类型化摘要、版本和指纹，而不是机密。
验证
- 单元测试覆盖校验、策略、工具行为、契约形态和升级处理。
- 行为评估覆盖已知、未知、缺失输入和注入案例。
- 生产部署必须增加 live API 序列化测试、经认证的归属检查、速率限制处理和金丝雀评估。
产品细节说明
实施和升级期间，必须根据当前官方文档核对模型 ID、SDK 方法、结构化输出字段、停止原因和配置入口。