G5 真实 E2E 验收手册

September 1, 2026 · View on GitHub

日期：2026-09-02
当前状态：真实 OAuth、跨重启恢复、token 自然到期刷新、QCC 主调用路径与 401/429/配额故障注入均已执行
适用脚本：npm run e2e:g5
示例夹具：test/fixtures/g5-e2e.example.json（仅虚构数据）

安全前提

Runner 默认关闭，并同时执行以下硬门：

必须显式设置 G5_E2E=1。
G5_BASE_URL 只允许 http://127.0.0.1:* 或 http://localhost:*，拒绝远端地址。
G5_E2E_MODE=enrich 还必须显式设置 G5_E2E_CONFIRM_PAID_CALLS=YES。
enrich 模式要求 capabilities 已为 ready:true；Runner 不代替用户发起 OAuth 连接。
报告仅保留状态、计数、错误码和安全审计数量，不写原始行、候选详情或 QCC 原始响应。
报告文件以 0600 权限创建；默认写入系统临时目录。

不要把真实 Token、企业名单或真实 E2E 报告提交到 Git。仓库已忽略 .env.g5-e2e 与 .g5-e2e/。

2026-09-01 补充：在隔离 rc.2 Profile 中，qcc-dsh-mcp-oauth@0.1.7 还需要显式安装 @deepseek-ai/dsh-mcp-client@0.1.1-rc.2；其实际工具名不带 qcc- 前缀，当前 Bridge 已兼容。 20 家公开企业的 400 次当前/历史工商调用已通过 e2e:phase2 严格验收。

2026-09-02 补充：复用同一隔离 Profile 的自然过期 grant，在端口 43159 启动 0.4.0 候选后， OAuth 插件自动刷新 access token，16+4 动态工具恢复；随后以 1 行批准夹具执行真实 enrich， 1/1 成功、0 失败、2 条安全审计。输入与报告均为 Git 忽略的 0600 文件，测试 Host 已停止，生产端口 43120 未触碰。

401、429 与配额耗尽采用 Web→Bridge→Mock ToolRuntime 故障注入，避免伪造真实账号故障或重复付费批次。三类错误均只派发一次失败调用；401/429 仅在显式 /retry 后重新派发，配额耗尽拒绝重试；审计仅含工具名、callId、attempt、稳定错误码与耗时。

1. 被动 preflight

此步骤只读取 capabilities，不调用 OAuth 或计费 QCC 工具：

G5_E2E=1 \
G5_E2E_MODE=preflight \
G5_BASE_URL=http://127.0.0.1:43150 \
npm run e2e:g5

预期：生成临时脱敏报告；Host 未连接时显示 not-connected-or-refreshing 或 oauth-plugin-missing。

2. 准备本机夹具

把示例复制到仓库外或已忽略目录，再替换为经过批准的脱敏名单：

cp test/fixtures/g5-e2e.example.json /private/tmp/g5-e2e-input.json
chmod 600 /private/tmp/g5-e2e-input.json

夹具结构：

{
  "headers": ["name"],
  "nameField": "name",
  "includeRisk": false,
  "concurrency": 1,
  "rows": [{ "name": "批准用于测试的企业" }],
  "selections": [
    {
      "companyName": "需要人工消歧的输入名",
      "selectedCreditNo": "人工确认的候选信用代码"
    }
  ],
  "retryCompanyNames": []
}

selections 只能填写 enrich 返回的候选；Host 会再次校验信用代码是否属于待复核列表。retryCompanyNames 只能填写错误队列中 retryable:true 的企业。

3. 真实 enrich Gate

先由用户在隔离 DSH Profile 内完成 QCC OAuth，再确认测试调用额度，最后运行：

G5_E2E=1 \
G5_E2E_MODE=enrich \
G5_E2E_CONFIRM_PAID_CALLS=YES \
G5_BASE_URL=http://127.0.0.1:43150 \
G5_FIXTURE_PATH=/private/tmp/g5-e2e-input.json \
G5_E2E_REPORT=/private/tmp/g5-e2e-report.json \
npm run e2e:g5

Runner 为 enrich、每次候选确认和人工重试生成稳定幂等键。同一 Host 内重复执行相同输入时应得到 idempotencyReplayed:true，不得再次调用计费工具。

4. 必验场景

未授权：capabilities 非 ready，Runner 在 enrich 前关闭。
首次授权：用户完成 OAuth 后，capabilities 变为 ready。
唯一匹配：完成工商补全。
多候选：初次只进入 awaiting-review；未确认前不调用工商详情。
候选确认：只调用工商详情及可选风险，不重复实体检索。
未匹配：保持 unresolved。
token 刷新：工具短暂消失后恢复；仅 UNKNOWN_TOOL 竞态允许一次内部安全重解析。✅ 自然到期刷新已验
401、403、429、配额不足、超时和 5xx：映射为稳定错误码，且只能由用户显式重试。✅ 401/429/配额故障注入已验，其余有契约测试
混合批次：单企业失败不影响其他企业。
报告、日志和审计中无 Token、企业原名、信用代码、邮箱、手机号或原始工具响应。

5. 当前限制

G5 run 与幂等记录只保存在 Host 内存，默认 TTL 30 分钟、最多 50 个 run；Host 重启或过期后必须新建 run。
当前不持久化原始/补全行，这是刻意的隐私边界；后续如需跨重启恢复，应先完成加密存储与保留期设计评审。
Runner 不自动调用 qcc_oauth_connect，真实 OAuth 始终由用户在隔离环境显式完成。