sub2api-cn-relay-manager/docs/2026-06-04-HOST_PROTOCOL_MATRIX_SCRIPT_CONTRACT.md

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 实现范围的一部分，但当前只完成设计契约。审核通过后开始实现剩余改进。