# Host Protocol Matrix Script Contract

日期：2026-06-04
状态：待审核
适用版本：vNext.1

## 目的

定义 `scripts/acceptance/verify_host_protocol_matrix.sh` 的契约、强制约束与后续生产化路径，确保协议矩阵脚本的输出可被重复信任，不会因为参数模式、超时、错误分类或脱敏不足而误判。

## 当前状态

`verify_host_protocol_matrix.sh` 已支持的功能：

- 通过 `PROTOCOL_MATRIX_TARGETS_JSON` 传入探测目标
- 探测 `/v1/models`、`/v1/chat/completions`、`/v1/responses` 三个端点
- 支持 `DRY_RUN` 模式，跳过真实网络调用
- 生成 `artifacts/host-capability/<timestamp>/protocol-matrix-summary.json`
- 每 target 输出独立子目录，保留 headers 和 body
- support level 分类：supported-direct / supported-with-plugin-adapter / unsupported-by-host / upstream-unhealthy
- `--help` 参数

当前缺口（来自审核报告 P0-5）：

这些已在审核报告中明确，但尚未进入脚本实现：

1. curl 没有 `--connect-timeout`、`--max-time`、重试策略和网络错误分类
2. 没有标准化 body error code
3. 没有区分 upstream / host / user-key 三层探测
4. artifact 没有统一脱敏、保留周期和敏感字段规则
5. 失败时脚本整体退出，不保留已完成的 provider 结果

## 三层探测结构

### 1. upstream probe

直接请求供应商上游。

参数：

- `base_url` 为供应商官方地址
- `api_key` 为普通 upstream key

输出：

- 上游是否可直连
- 上游协议层兼容性
- 参考 latency

### 2. host probe

经 sub2api 宿主入口探测。

参数：

- `base_url` 为宿主地址
- `api_key` 为宿主可识别的上游 key / channel key

输出：

- 宿主协议转换层状态
- host 是否通过了 chat / responses
- 与 upstream 的差异

### 3. user-key probe

使用最终用户 key 测试完整链路。

参数：

- `base_url` 为宿主对外公开地址
- `api_key` 为最终用户 key

输出：

- 用户能否成功走完 `chat/completions`
- 给出 200 或明确失败分类

规则：

- 三层探测使用同一个 `PROTOCOL_MATRIX_TARGETS_JSON` 结构
- 目标定义中加入 `probe_layer: "upstream" | "host" | "user-key"`
- 默认模式：upstream；需要额外参数允许 host / user-key 运行

## 强制参数

### 超时与重试

- 每个请求必须设置 `--connect-timeout 10`
- 每个请求必须设置 `--max-time 30`
- 重试策略：失败时重试 1 次，间隔 2 秒
- 两次重试仍失败 → 归类为 `network_timeout`，不视为成功

### 错误分类 enum

body error code 至少识别：

| 分类                    | 匹配规则                                | 说明                           |
| ----------------------- | --------------------------------------- | ------------------------------ |
| chat_ok                 | HTTP 200, body 有效                     | 正常成功                       |
| models_only             | only models 200, chat/responses not 200 | 仅 models 可达                 |
| responses_unsupported   | chat 200, responses not 200             | Host/upstream 不支持 Responses |
| rate_limited            | HTTP 429                                | 上游/宿主限流                  |
| region_blocked          | HTTP 403, body region                   | 区域限制                       |
| cloudflare_blocked      | body: "1010" 或 "cloudflare"            | Cloudflare CDN 拦截            |
| auth_failed             | HTTP 401, 403, body: "auth" / "invalid" | 认证失败                       |
| network_timeout         | curl exit code 28                       | 连接/超时                      |
| host_protocol_mismatch  | chat body 格式与预期不一致              | 宿主协议转换错误               |
| user_key_binding_failed | user-key 路径 body 显示分组/绑定错误    | 权限/groups 问题               |

### 部分失败输出

- 脚本不得在第一个失败的 target 整体退出
- 已完成的 target 仍然保留 artifact
- failure target 在 summary 中标记 `status: failed`，并记录错误分类
- 最终 exit code = 0（即使部分 target 失败），除非有脚本内部错误

### Artifact 保留要求

- 所有 probe 包含 `request_headers.txt`、`response_headers.txt`、`response_body.json`
- secrets 必须在输出前脱敏：`Authorization: Bearer ***`
- artifact 保留周期：至少 7 天
- artifact 目录结构：

```
artifacts/host-capability/<timestamp>/
  protocol-matrix-summary.json
  targets/
    01-<provider_id>/
      01-models.{headers.txt,body.json}
      02-chat.{headers.txt,body.json}
      03-responses.{headers.txt,body.json}
    ...
```

## 验收条件

脚本必须通过以下测试：

1. `DRY_RUN=1 bash ./scripts/acceptance/verify_host_protocol_matrix.sh` 成功
2. 部分失败不回滚之前 target
3. 含 `--connect-timeout` 和 `--max-time`
4. artifact 目录不含明文 secret
5. summary 使用标准化 error enum
6. 无 `exit 1` 因单个 target 失败导致

## 未来生产化方向

- p95 latency 记录
- 增量探测（仅测上次失败/新增的 target）
- 与 SLO pipeline 集成
- 失败分类告警

## 与本轮范围关系

脚本生产化属于 vNext.1 实现范围的一部分，但当前只完成设计契约。审核通过后开始实现剩余改进。