Make Codex and Claude Code subscriptions go further: a local model router that gives routine agent work to economical models and keeps your strongest model for the hard parts.
HiRoute black-box E2E
这个目录保存环境无关的产品路径合同。它位于 unit、component 和 gateway-core lifecycle 测试之上,从真实 TCP 边界验证用户最终看到的行为。
E2E HTTP client
-> external HiRoute SUT
-> stock CPA Claude (one source)
-> Anthropic-native mock
-> stock CPA Codex (one source)
-> Responses-native mock
hiroute-e2e 不依赖 hiroute-poc 或 gateway-core Rust crate。将来 POC binary 被正式 daemon / Desktop backend 替换时,只要维持外部 CLI 与 HTTP 产品合同,scenario 不需要重写。
当前覆盖
scenarios/core-routing.json 包含十七个顺序步骤:
| 下游协议 | 任务 | 真实 native mock | 预期来源 |
|---|---|---|---|
| Responses | simple | Anthropic /v1/messages |
Claude-compatible |
| Responses | complex | Codex /responses |
Codex subscription |
| Messages | simple | Anthropic /v1/messages |
Claude-compatible |
| Messages | complex | Codex /responses |
Codex subscription |
| Responses / Messages | large Agent envelope + simple user | Anthropic /v1/messages |
Claude-compatible |
| Responses / Messages | tool continuation | Codex /responses |
原 Turn affinity hit |
| Responses | simple + Claude 500 | Claude /v1/messages 后 Codex /responses |
precommit fallback 到 Codex |
| Responses | fallback 后 function output | Codex /responses,无 Claude Attempt |
回写后的 Turn affinity hit |
| Responses | complex 后追加 simple 完整历史 | Codex /responses |
同 Session 前缀保持 Codex |
| Responses | 保留前两条 user、替换后续摘要 | Anthropic /v1/messages |
完整历史重建后重新选择 Claude |
| Messages | simple 后追加 complex 完整历史 | Anthropic /v1/messages |
同 Session 前缀保持 Claude |
| Messages | 编辑 system、历史正文不变 | Codex /responses |
指令变化后重新选择 Codex |
| Responses | 非空 previous_response_id |
无 native Attempt | Planner 前返回明确 400 错误码 |
每一步同时断言:
- 下游状态、SSE content type 与协议终止事件;
x-hiroute-source;- native mock 实际收到的有序 Attempt、native path、native model、response-head status,以及 CPA 使用了该 source 独有的上游鉴权;
- 是否确实发生 Messages / Responses 协议转换;
- 每次 Attempt 对应的 routing receipt,其 protocol、source、class、affinity、disposition 与 status;
- fallback 后接受来源会回写 Turn affinity,function output 续轮直接命中 Codex,不再探测 Claude;
- 同一稳定 Session 的完整可见历史 append 跨 simple/complex 分支保持实际成功来源,历史重建或指令编辑则重新选路;
- 不支持的 Responses 服务端续链在 Planner 和 native 上游前拒绝,ledger 与 receipt 均不增加。
上述当前实现只证明基础路径、来源与有限终止事件,不能证明协议语义已经保真。当前
protocol_conversion=true 仅表示客户端协议与 native mock 协议名称不同;native ledger 只检查
messages/input 顶层形状,尚未逐项比较 Vision、Tool schema/choice/call/result/ID、
reasoning 原生字段、usage/finish reason、Provider state 和完整 SSE 事件序列。因此不能把当前 17-step suite
表述成正式协议转换 conformance 已通过。
正式 P0 目标由
Agent 接入与模型协议转换合同定义,并拆成:
E2E-P028:从 exact Codex/Claude Code 安装版本和有效配置解析 AgentIntegrationProfile,分别选择 Responses/Messages 唯一入口,执行配置 diff/apply/rollback 与真实跨协议 Turn;E2E-D011:Responses/Messages 入站到 Responses/Chat Completions/Messages 上游的六路径语义保真;E2E-D012:入站 effort 隔离、AgentPlan exact reasoning configuration 的逐目标协议原生渲染与 fallback 重渲染;E2E-D013:Tool ID/续轮、Provider state 亲和、统一流式事件、流中错误和 postcommit 零接力。
这四项必须先以有限 schema、canonical Model IR corpus、request/SSE golden 和 native semantic ledger 建成红灯 测试,再实现正式 Adapter。只看 HTTP 200、最终文本、目标 path 或协议名称不同均不构成通过证据。
来源判定以 native mock ledger 为主证据,不信任 response model 或 Gateway 自报 header;后两者只是相互独立的旁证。Native mock 只断言鉴权是否完全匹配,不把任何 credential 写入 ledger 或结果 artifact。
环境合同
Scenario 只描述产品行为,禁止 executable path、shell command、端口、延时、任意响应体和凭据。v2 的成功步骤只允许 1–2 次 source-native Attempt,以及有限的 response-head status:200/429/500/502/503/504/529;最终 Attempt 必须是 200 Accept。入口预校验步骤只允许固定 400 + error code + 0 Attempt,用于断言请求没有进入 Planner/native 上游。请求头只允许有界的 session-id/thread-id,不能注入认证或环境编排。#[serde(deny_unknown_fields)]、语义校验与 JSON Schema 共同防止环境编排逐渐渗入用例。
profiles/local-process.json 只允许两个固定引用:
HIROUTE_E2E_CPA_BIN -> stock CLIProxyAPI executable
HIROUTE_E2E_SUT_BIN -> external HiRoute executable
Runner 每次使用动态端口与 0700 TempDir,生成随机 capability,启动两个 single-source CPA、两个 native mock 与一个 SUT;所有 secret-bearing 文件和进程日志为 0600。每个子进程都有独立、启动时为空的 0700 work directory,并同时作为 current_dir、HOME、XDG 与 TMPDIR,因此 stock CPA 不会向上搜索并读取仓库 .env。子进程从 env_clear() 的最小环境启动,不继承开发者 shell 中的真实 Provider token;外部 HTTP proxy 被指向 loopback blackhole,native source 只允许 loopback。进程 readiness 使用连接探测,不依赖固定 sleep;退出有界并由 drop 做二次 kill 保证。
结果 artifact 只保留产品证据,不包含:
- 请求或模型响应正文;
- capability / CPA / native API key;
- 端口、临时路径或 executable path;
- command argv 或原始进程日志。
使用
验证合同(不要求已有二进制):
cargo run -p hiroute-e2e -- validate \
--scenario e2e/scenarios/core-routing.json \
--profile e2e/profiles/local-process.json
运行完整黑盒链路:
HIROUTE_E2E_CPA_BIN=/absolute/path/to/CLIProxyAPI \
HIROUTE_E2E_SUT_BIN=/absolute/path/to/hiroute-poc \
cargo run -p hiroute-e2e -- run \
--scenario e2e/scenarios/core-routing.json \
--profile e2e/profiles/local-process.json \
--result /tmp/hiroute-e2e-result.json
Runner 每次分配动态端口和私有临时目录,启动两个 native mock、两个隔离 stock CPA 和一个外部 HiRoute SUT。它用真实 TCP 验证四个协议/来源象限、两种 Agent envelope 反例、Responses/Messages 工具续轮的 affinity hit、context hold/重建失效、Responses 服务端续链早拒绝,以及 Claude 500 -> Codex Accept -> function output 直接命中 Codex 的完整链路。
建议的质量门禁:
cargo fmt --package hiroute-e2e -- --check
cargo check -p hiroute-e2e
cargo clippy -p hiroute-e2e --all-targets -- -D warnings
cargo test -p hiroute-e2e
用 E2E 驱动后续功能
新增能力时遵循“产品合同先红、实现后绿”:
- 用现有字段可表达时,先添加一个
ScenarioStep,运行确认因未实现行为而失败。 - response-head fallback 直接使用 v2 的有限
attempts;新能力需要首包断连、语义 SSE failure、更多 step 类型或新的证据时,再升级 Rust contract 与schema_version,同步更新e2e/schema/。 - 不在 scenario 中加入 shell、路径、sleep、固定端口或 secret;编排能力属于 runner/profile。
- 对路由能力优先增加 native ledger 断言;对协议能力同时增加原生事件序列和统一语义断言。
- 实现产品代码,直到本地与 CI 的同一 scenario 通过。
- 结果 artifact 通过敏感信息扫描后再作为评审证据保留。
推荐下一批 scenario:
- 两个 Turn 交错,affinity 不串线;
- 429/502/503/504/529 response-head 矩阵、首包断连与首个语义 SSE error 的 precommit fallback;
- commit 后禁止重放和总 Attempt 数上限;
- SSE 任意字节切片、长流、客户端取消与内存上界;
- multimodal、
count_tokens、compact和 usage/cost evidence; - Codex CLI / Claude Code 的 real-local smoke profile。
当前 v2 native mock 对成功响应返回固定文本 SSE,并支持有限 response-head failure;ScenarioStep 只支持 HTTP Turn。不要用任意 shell 字段绕过这个边界;需要上述能力时,应把 stream failure 或 AgentTurn 建成新的有限枚举并升级 schema。
CI 分层
当前公共 CI 在 Linux、macOS、Windows 上编译 harness、运行其 mock/unit tests,并通过 CLI 静态校验 checked-in scenario 与 profile;这条门禁不需要外部二进制、真实账号或凭据。
完整 10-step 进程链路当前仍需要单独提供 stock CPA 与 HiRoute SUT,按上面的 run 命令显式执行。
它不会被静态 validate 冒充已经在公共 CI 跑通。正式 SUT 可由代码仓库直接构建后,再分层扩展:
e2e-core-routing:构建 stock CPA + SUT,执行当前 10-step hermetic suite;e2e-product:按 Proposal 增加 fallback、tool、cancel、memory 等套件;e2e-real-local:显式人工/nightly 触发,使用真实本地 Agent 和授权,不进入公共 CI,也不替代 hermetic suite。
P0 Gateway exact Oracle
最终 gateway-isolated 合同由 schema/p0-production-manifest.json 封口。Manifest 锁定一个真实
Responses → Responses production smoke、profile、scenario 和 launcher/readiness/collector/result schema;
artifact SHA-256 对 canonical JSON 计算,任何未重新封口的语义漂移都会在启动前失败。旧
p0-gateway-manifest.json、corpus/golden 和 fixture adversary 仍可作为历史负向输入,但不再被最终 profile
加载,也不能证明发布完成。
Runner 只用正常的 hirouted --role gateway --listen ... --publication ... --credentials ... 路径;最终合同中
不存在 --fixture、--expect-status、expected_red 或 skip。每次运行生成私有 publication/credential
输入、随机 client/provider capability、不可预测 freshness challenge、动态 loopback listener 和 native
Provider mock。Profile 固定 Gateway 产品源码 revision;runner 在 binary 所属 checkout 内检查源码树和构建输入相对该
revision 无 tracked/untracked 漂移,再用当前 target/toolchain 执行带随机 build nonce 的 cargo rustc --locked --all-features 可信重建。Launcher evidence 固定这次重建的 revision/source tree/build-input digest、target、toolchain、
build command、artifact path 和实际 executable SHA-256,因此不同 checkout/平台的合法构建无需共享本地 debug hash,
而 wrapper、非 Cargo artifact 和伪造构建输入不能被当作 SUT。
/_hiroute/ready 除精确回报 publication revision/digest 与 executable digest 外,runner 还会在 probe 前后
通过 OS socket-owner proof 要求动态 listener 都由同一存活 child PID 持有。调用方还可用
HIROUTE_E2E_SUT_REVISION 增加外部 revision 断言。
Provider 证据保存完整原生 JSON payload 和精确连接计数。Collector 分别读取 Lifecycle、ExecutionFact、
ConversationContent 和 content-free OTel JSONL,要求四套独立 producer/epoch/stream identity、从 1 开始的
连续 sequence、每条 record 的 exact channel schema digest 与拒绝未知字段的强类型 product envelope、唯一
event ID、同一 request correlation、零 gap/loss 和各自 terminal。Lifecycle 的 request_finished 必须
最后出现;ExecutionFact 的 request_finished 后只允许独立的 usage_and_cache;ConversationContent 必须
只含 request/response 两个方向并分别形成 begin … finish,绝不把 request_finished 解释成正文 barrier。结果中的十项
exact evidence 唯一地投影为四个有序 checkpoint;缺失、孤立、损坏、hard-coded、wrong-ready、wrong payload
或 incomplete terminal 均 fail closed。
结果 schema 只允许 scenario green|red,并把 process_exit.test_process_code 与 scenario_state 分开记录。
CLI 只在真实 production evidence 推出 green 时返回 0;证据不匹配会写出 red 结果并返回非零,启动、
provenance、readiness 或 collector 合同失败也返回非零且不能形成发布证明。完整结果含 synthetic challenge
和 canonical Content evidence,因此以 0600 写入指定路径;stdout 只输出无正文摘要。
验证、重新封口并运行真实 production smoke:
cargo build -p hiroute-gateway --bin hirouted --all-features
cargo run -p hiroute-e2e -- validate \
--schema e2e/schema --scenario e2e/scenarios/p0-gateway.json
# 只在有意修改任一已锁定 artifact 后运行;连续运行两次,第二次必须零 diff。
cargo run -p hiroute-e2e -- seal-production --e2e-root e2e
HIROUTE_E2E_SUT_BIN="$PWD/target/debug/hirouted" \
cargo run -p hiroute-e2e -- run \
--profile e2e/profiles/gateway-isolated.json \
--scenario e2e/scenarios/p0-gateway.json \
--result target/e2e/p0-gateway-result.json
本 PROCESS 只冻结这一个 production smoke 和稳定扩展点。九条协议路径、fault/resource/privacy 全矩阵继续由 PROCESS-22009 在其独立 ownership 中补齐;不得把这里的一例绿色外推成完整矩阵完成。
matrix/p0-gateway-coverage.json 是 PROCESS-22009 的独立 exact coverage index,但不是完成状态的
自报输入。冻结 typed registry 定义完整 required row 集;每个 row 只引用 registry receipt,而 receipt
固定真实 hirouted + native Provider 执行模式、测试 target、精确 symbol、完整 source SHA-256 和
assertion identity。seal-coverage 只把该 registry 投影为 JSON:
cargo run -p hiroute-e2e -- seal-coverage --e2e-root e2e
p0_gateway_matrix_coverage 同时校验 schema、完整 registry projection、source digest、symbol/test
绑定与 assertion identity;缺失 row 或伪造 execution 均失败。index 不包含 skip、expected_red 或人工
passed 状态。个人版 P0 listener 的 transport 行仅是 loopback H1;release H2 benchmark 与 Enterprise
TLS listener 不属于此 matrix。