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