492f33a129
- DEFAULT_CHAIN_ADMISSION.md: reviewed and approved, real artifact refs added - DEFAULT_DATA_IDEMPOTENT_RELEASE_GATE.md: reviewed and approved - scripts/setup_default_data.sh: idempotent init with --dry-run/--apply/artifact - scripts/test/test_default_data.sh: 4 test cases all pass - scripts/acceptance/verify_user_key_self_service.sh: Phase 0 skeleton - .gitignore: add generated artifact directories
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 实现范围的一部分，但当前只完成设计契约。审核通过后开始实现剩余改进。
|