# 订单状态助手架构记录

## 决策

使用一套有边界的 Claude 辅助工作流：包含一个进程内只读工具、确定性策略、严格的输出验证和明确的升级处理。

## 背景

用户需要根据精确的公开订单 ID 获取已验证的订单状态。路径已知，而编造操作的代价很高。目前由一个应用拥有此能力。

## 组件

1. 输入校验器提取公开 ID 格式。
2. 信任边界将用户和检索到的内容标记为不可信。
3. Claude 可通过类型化工具契约提议 `lookup_order`。
4. 策略门禁只允许带一个参数的只读调用。
5. 可信集成代码绑定经认证的用户和租户身份。
6. 订单服务返回经过最小化处理的已验证状态。
7. Claude 生成结构化最终响应。
8. 应用验证 schema、证据、路由状态和追踪。

## 决策与权衡

### 工作流优于自主 agent

顺序已知。通用 agent 会增加工具选择和循环风险，却不会改善核心用户结果。

### 直接工具优于 MCP

一个宿主使用一项能力。直接的类型化处理器具有更少的运维边界。当两个或更多获批准的宿主需要共享发现和治理时，再迁移到 MCP。

### 自动化能力保持只读

在通过 schema 和策略检查后可以自动查询。退款、取消、地址变更和外部消息需要独立工具、外部批准、幂等性和新的评估。

### 结构化输出加本地验证

provider 约束的生成可减少语法错误。本地 schema、语义和授权检查仍然是必需的。

### 默认不使用扩展思考

该工作流是直接查询。新增推理预算必须先证明能带来可测量的质量提升。

## 被否决的备选方案

- 自由形式 shell 或数据库工具：权限过大且难以验证。
- 宽泛的 `manage_order` 工具：混合读取和修改权限。
- 以对话文本作为批准：未经认证且容易被注入攻击。
- 无限重试：造成成本和副作用不确定性。
- 第一版就使用 MCP：互操作收益尚不足以证明服务器运维合理。

## 安全边界

- 凭证保留在可信集成代码中。
- 模型参数绝不建立身份或租户。
- 不可信内容不能授予能力。
- 未知工具和参数字段默认拒绝。
- 工具结果在进入模型上下文前最小化。
- 追踪包含类型化摘要、版本和指纹，而不是机密。

## 验证

- 单元测试覆盖校验、策略、工具行为、契约形态和升级处理。
- 行为评估覆盖已知、未知、缺失输入和注入案例。
- 生产部署必须增加 live API 序列化测试、经认证的归属检查、速率限制处理和金丝雀评估。

## 产品细节说明

实施和升级期间，必须根据当前官方文档核对模型 ID、SDK 方法、结构化输出字段、停止原因和配置入口。