dsh-data-cleaning-agent 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@
 
 ## [Unreleased]
 
+> 目标版本：`0.4.0`。源码版本、token 到期刷新、401/429/配额故障门与 Linux/Windows 远端 CI
+> 均已通过；尚未创建 `v0.4.0` tag、GitHub Release 或 npm 发布。
+
+### Added
+- 0.4.0 二期第一切片：新增可测的 QCC 工商全景契约（16 个工商工具 + 4 个历史工商工具）；
+  `enterprise-enrichment` 按 `panorama` / `ownership` / `governance` / `history` 组按需调用，
+  强制来源标记、历史权限降级与付费批次约束。
+- 0.4.0 验收评估器与默认关闭的 `e2e:phase2` Runner：强制 20 企业 / 每企业 ≥15 维、
+  源工具匹配、字段原值一致、历史账号门，并显式拒绝合成证据充当真实 E2E。
+- 只读 `/data-cleaning/api/phase2/capabilities` 预检：报告 16+4 工具注册状态，
+  不调用 QCC，并将历史工具可用性与账号权限验证明确分开。
+- G5-1 QCC Host Bridge（`lib/qcc.js`）：通过公共 `ctx.tools.execute()` 程序化调用动态 MCP 工具，
+  支持允许列表、超时/取消、OAuth 重注册窗口、企业去重批处理、多候选暂停与部分失败隔离。
+- 同源 Web 端点 `/data-cleaning/api/g5/capabilities` 与 `/data-cleaning/api/g5/enrich`；
+  计费调用前强制 `confirmPaidCalls:true`，单批最多 100 行。
+- G5 Mock/Contract 测试已覆盖主路径；真实 OAuth/QCC 主路径、token 自然到期刷新与故障注入均已验收。
+- G5-2 安全闭环：默认关闭且仅允许回环 Host 的 E2E Runner、日志/报告脱敏、请求幂等、
+  Host 内存 run 状态、多候选人工确认续跑、retryable 失败人工重试和安全调用审计。
+- 上游错误细分为授权、权限、限流、配额、超时、工具刷新、服务不可用和契约拒绝；
+  错误响应不再复述可能包含敏感内容的上游原始 message。
+
+### Changed
+- QCC Host Bridge 兼容 `qcc-dsh-mcp-oauth@0.1.7` 实测注册的
+  `mcp__company__*` / `mcp__history__*` legacy serverName，同时保留
+  `mcp__qcc-company__*` / `mcp__qcc-history__*` 作为规范名称；capabilities 同时报告规范名与实际运行时名。
+
+### Verified
+- 在隔离 DSH `0.1.1-rc.2` Host 完成真实 OAuth、授权跨重启恢复与 20 家公开企业的 400 次 QCC 调用；
+  严格历史域验收通过：20/20 主体已解析、每企业当前工商最低 15 维、历史工商 4 维。
+- 原始证据与脱敏报告仅保存在 Git 忽略的 `.phase2-e2e/`，权限为 `0600`；未触碰生产端口。
+- 自然过期 access token 的真实 refresh、动态工具恢复与续期后最小真实调用已通过；
+  401/429/配额耗尽故障注入确认无自动重试、人工重试门正确且审计不泄密。
+
 ## [0.3.0] - 2026-09-01
 
 > 企查查 MCP 接入 · 方案 A（模型中介式企业名单补全）首个版本。

package/README.en.md

@@ -2,7 +2,7 @@
 
 > A data cleaning & completion agent plugin for DeepSeek Harness: local CSV/XLSX/JSON engine plus optional Qichacha (QCC) MCP enterprise-data enrichment. Initiated and maintained by the Qichacha (QCC) team.
 >
-> Current version / 当前版本: **0.3.0**
+> Current source version / 当前源码版本: **0.4.0** (release candidate; npm `latest` remains 0.3.0)
 
 [![CI](https://github.com/duhu2000/dsh-data-cleaning-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/duhu2000/dsh-data-cleaning-agent/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/dsh-data-cleaning-agent)](https://www.npmjs.com/package/dsh-data-cleaning-agent)
@@ -55,19 +55,31 @@ Or let an agent install it for you:
 | Async jobs | web `/data-cleaning/api/mvp/jobs` | job state machine + persistent storage |
 | UI | web `/data-cleaning/` | upload → clean/complete → export |
 | Skill | `data-cleaning` | guides the model through the workflow |
-| QCC enrichment | (planned, see below) | backfill list with Qichacha MCP enterprise data |
+| QCC Skill enrichment | `enterprise-enrichment` | 0.4.0 release candidate: company panorama, ownership, governance, and historical registration |
+| 0.4.0 preflight | web `/data-cleaning/api/phase2/capabilities` | Read-only 16+4 dynamic-tool check; makes no QCC or paid calls |
+| QCC Host Bridge | web `/data-cleaning/api/g5/*` | 0.4.0 release candidate: real OAuth/QCC path, natural-expiry refresh, and fault injection verified |
 
-## Qichacha MCP enrichment (roadmap)
+## Qichacha MCP enrichment (status and roadmap)
 
-Besides local deterministic completion, the plugin will (in later releases) enrich lists with
-Qichacha MCP enterprise data:
+Besides local deterministic completion, the plugin supports Qichacha MCP enterprise-data enrichment:
 
 - **Plan A (model-mediated, first)**: after the user connects Qichacha with
   `qcc-dsh-mcp-oauth`, the Skill guides the model to call
   `mcp__qcc-company__get_company_by_query` / `mcp__qcc-company__get_company_registration_info`
   per company name and feed the fresh registration data back into the completion tool.
-- **Plan B (programmatic, later)**: `lib/qcc.js` calls Qichacha MCP tools directly in the host
-  half and batch-completes; the model sees only the final summary.
+- **Plan B (programmatic, 0.4.0 release candidate)**: the Host Bridge now supports batch enrichment,
+  idempotency, explicit candidate-resolution resume, manual retry of retryable failures, and
+  metadata-only auditing through the public `ctx.tools.execute()` runtime. Paid endpoints require
+  both `confirmPaidCalls:true` and a unique `idempotencyKey`; ambiguous candidates are never
+  auto-selected. A loopback-only, fail-closed E2E runner is ready. On 2026-09-01 an isolated rc.2
+  Host passed real OAuth, restart recovery, and 400 QCC calls across 20 public companies; expiry-time
+  token refresh and rate-limit/quota fault injection remain release-blocking gates.
+
+The Bridge accepts both the documented `mcp__qcc-company__*` names and the legacy
+`mcp__company__*` names observed from `qcc-dsh-mcp-oauth@0.1.7`. A fresh rc.2 profile must also
+install the matching `@deepseek-ai/dsh-mcp-client` explicitly; see the compatibility guide.
+
+See [the 0.4.0 release checklist](docs/RELEASE-0.4.0.md) for scope, blocking gates, and rollback steps.
 
 See [docs/PLAN-OSS.md](docs/PLAN-OSS.md) for details.
 
@@ -84,6 +96,8 @@ npm run check
 
 `npm run check` runs lint, documentation version consistency, pack whitelist verification and
 unit tests.
+Real G5 validation must be enabled explicitly according to
+[the E2E runbook](docs/G5-E2E-RUNBOOK.md); `npm run e2e:g5` refuses to run by default.
 
 ## Configuration
 

package/README.md

@@ -2,7 +2,7 @@
 
 > 在 DeepSeek Harness 中清洗、补全、画像企业名单数据的智能体插件：本地 CSV/XLSX/JSON 引擎 + 可选企查查（Qichacha/QCC）MCP 企业数据补全，由企查查（Qichacha/QCC）团队发起并维护。
 >
-> 当前版本 / Current version: **0.3.0**
+> 当前源码版本 / Current source version: **0.4.0**（发布候选；npm `latest` 仍为 0.3.0）
 
 [![CI](https://github.com/duhu2000/dsh-data-cleaning-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/duhu2000/dsh-data-cleaning-agent/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/dsh-data-cleaning-agent)](https://www.npmjs.com/package/dsh-data-cleaning-agent)
@@ -52,20 +52,36 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
 | 异步任务 | web `/data-cleaning/api/mvp/jobs` | 任务状态机 + 持久化存储 |
 | UI | web `/data-cleaning/` | 上传 → 清洗/补全 → 导出 |
 | Skill | `data-cleaning` | 引导模型按工作流调度上述工具 |
-| 企查查补全 | （规划中，见下文） | 用企查查 MCP 企业数据回填名单 |
+| 企查查 Skill 补全 | `enterprise-enrichment` | 0.4.0 发布候选：工商全景、股权穿透与历史工商 |
+| 0.4.0 工具预检 | web `/data-cleaning/api/phase2/capabilities` | 只读检查 16+4 动态工具，不发起 QCC/付费调用 |
+| QCC Host Bridge | web `/data-cleaning/api/g5/*` | 0.4.0 发布候选：后台批量基础层；真实 OAuth/QCC 主路径、自然到期刷新与故障注入均已验收 |
 
-## 企查查 MCP 补全（路线图）
+## 企查查 MCP 补全（状态与路线图）
 
-插件同时提供本地确定性补全，以及（后续版本）接入企查查 MCP 企业数据的能力：
+插件同时提供本地确定性补全和企查查 MCP 企业数据补全：
 
 - **方案 A（模型中介，优先）**：用户已用 `qcc-dsh-mcp-oauth` 连接企查查后，
   Skill 引导模型对名单中每个企业名调用 `mcp__qcc-company__get_company_by_query` /
   `mcp__qcc-company__get_company_registration_info`，把返回的最新工商信息回填到补全工具。
-- **方案 B（后台程序化，后续）**：`lib/qcc.js` 在 host 半区直接调用企查查 MCP 工具，
-  批量补全，模型只见最终摘要。
+  `main` 上的 0.4.0 开发切片已将 16 个工商工具和 4 个历史工商工具固化为可测契约，
+  按 `panorama` / `ownership` / `governance` / `history` 维度组按需调用；未显式选择时不会默认打满全部付费工具。
+- **方案 B（后台程序化，0.4.0 发布候选）**：Host Bridge 已通过公共 `ctx.tools.execute()` 实现
+  批量补全、请求幂等、多候选人工确认续跑、retryable 失败人工重试与安全审计。
+  批量 Web 端点同时要求 `confirmPaidCalls:true` 和唯一 `idempotencyKey`；多候选绝不自动选择。
+  默认关闭的本机 E2E Runner 已就绪；2026-09-01 已在隔离 rc.2 Host 完成真实 OAuth、跨重启恢复和
+  20 家公开企业的 400 次 QCC 调用；自然过期 token 的真实刷新、动态工具恢复及 1 行续期后调用也已通过。
+  401 / 429 / 配额耗尽使用 Web→Bridge→ToolRuntime 故障注入验证，不额外消耗真实付费批次。
+
+`qcc-dsh-mcp-oauth@0.1.7` 在 rc.2 实测注册为 `mcp__company__*` / `mcp__history__*`；
+本插件的兼容 Bridge 会自动映射到文档规范名 `mcp__qcc-company__*` / `mcp__qcc-history__*`。
+隔离 Profile 还需显式安装与 Host 同版本的 `@deepseek-ai/dsh-mcp-client`，详见兼容性文档。
 
 详见 [docs/PLAN-OSS.md](docs/PLAN-OSS.md)。
 
+0.4.0 真实账号验收的证据格式、安全门和命令见
+[docs/PHASE2-ACCEPTANCE.md](docs/PHASE2-ACCEPTANCE.md)。
+发布范围、阻断门和回滚步骤见 [docs/RELEASE-0.4.0.md](docs/RELEASE-0.4.0.md)。
+
 ## 本地开发
 
 要求 Node.js 20 或更高。DSH 运行期服务（`ctx.tools` / `ctx.skills` / `ctx.jobs` /
@@ -77,6 +93,7 @@ npm run check
 ```
 
 `npm run check` 会依次执行 lint、文档版本一致性、发布包白名单校验与单元测试。
+真实 G5 验收必须按 [E2E 手册](docs/G5-E2E-RUNBOOK.md) 显式开启；默认执行 `npm run e2e:g5` 会安全拒绝。
 
 ## 配置
 

package/docs/COMPATIBILITY.md

@@ -11,12 +11,15 @@
 
 > 生产 GUI（`http://127.0.0.1:43120`）不用于验证，验证一律使用隔离 `DSH_HOME` + 专用端口。
 
+2026-09-01 的 0.4.0 发布候选已分别在 rc.2（43153）和 alpha.2（43154）
+隔离 Host 完成 tarball 加载冒烟，两者均返回 `enrichSkillRegistered:true`；测试进程已停止。
+
 ## 2. Node 运行时
 
 - 本包 `engines.node` 声明 `>=20`。
 - CI 矩阵按 ADR-0001 收敛为 **Node 22 / 24**（本机 Desktop `engines` 为 `^22.19.0 || >=24.0.0`）。
 
-## 3. 契约面（Spike #1–#6 已实测）
+## 3. 契约面（Spike #1–#7 已实测）
 
 | 契约 | 用法 | 备注 |
 | --- | --- | --- |
@@ -29,12 +32,13 @@
 | 存储 | `ctx.storageDomain` | `open({name,version,tables})` → `table('jobs')` |
 | web 路由 | `webServer.register({kind:'prefix', path, handler})` | 最长前缀匹配；前缀需以 `/` 结尾且匹配 `pathname.startsWith(prefix + '/')` |
 | 同源守卫 | `isTrusted(req)` | `sec-fetch-site !== 'cross-site'` 且 origin 为 127.0.0.1/localhost |
+| 程序化工具调用 | `ctx.tools.get()` + `ctx.tools.execute()` | S7 双基线验证；每次调用重新解析，不缓存动态 MCP 工具 |
 
 ## 4. 与企查查 MCP OAuth 插件的共存
 
 | | `qcc-dsh-mcp-oauth` | 本插件 |
 | --- | --- | --- |
-| 工具名前缀 | `qcc_oauth_*` + `mcp__qcc-*` | `data_clean_rows` / `data_complete_rows` / `data_profile` |
+| 工具名前缀 | `qcc_oauth_*` + 规范 `mcp__qcc-*`；0.1.7 实测为 legacy `mcp__company__*` 等 | `data_clean_rows` / `data_complete_rows` / `data_profile` |
 | Skill | — | `data-cleaning`、`enterprise-enrichment` |
 | 存储域 | 自有 grant store | `dc_tasks_v1` |
 | 能否共存 | ✅ | ✅（工具名 / Skill 名 / 存储域 / 条目 id 全独立） |
@@ -44,9 +48,25 @@
   `mcp__qcc-company__*` / `mcp__qcc-risk__*`（授权成功后由 mcp-client 动态提供）。
 - 若 qcc-dsh-mcp-oauth 未安装或未授权，`enterprise-enrichment` Skill 的第一步
   `qcc_oauth_status` 即会中断并引导用户先连接，不会假装补全。
+- G5 Host Bridge 不读取 grant/token，也不访问 mcp-client 私有 client；只经共享 `ctx.tools`
+  调用动态注册的 `mcp__qcc-*` 工具。G5-2 增加幂等、候选续跑、人工重试与安全审计；
+  run 明细仅驻留 Host 内存。Bridge 会把 OAuth 0.1.7 的 legacy `mcp__company__*` / `mcp__history__*`
+  映射到规范名称，并在 capabilities 中同时报告两者。
+
+### 4.1 2026-09-01 rc.2 实测结论
+
+- fresh Profile 必须显式安装与 Host 同版本的 `@deepseek-ai/dsh-mcp-client@0.1.1-rc.2`；
+  仅依赖 DSH CLI 全局副本时，OAuth grant 可恢复但动态工具不会进入 Profile 的可调用工具面。
+- `qcc-dsh-mcp-oauth@0.1.7` 的 `serverName` 实际为 `company/history/...`，注册名因此不带 `qcc-`。
+  当前 Bridge 已兼容；上游修复后无需迁移证据或 Skill 规范名。
+- 真实 OAuth、跨重启恢复、16+4 工具预检、20 企业/400 调用及自然到期 refresh 已通过；
+  refresh 后 16+4 工具恢复，并以 1 行真实 enrich 验证新 token 可用。
 
 ## 5. 已知限制
 
 - alpha.2 的 `@Remote` 契约仍可能变动，本包不对其作稳定 API 承诺。
 - web 半区仅 web 组合可用；headless 组合自动跳过（工具与 Skill 仍注册）。
 - XLSX 解析依赖 `xlsx`（懒加载），缺失时返回 `XLSX_UNAVAILABLE` 而非崩溃。
+- `/data-cleaning/api/g5/enrich` 当前为 0.4.0 发布候选能力，单批上限 100 行、并发上限 4，
+  且必须显式 `confirmPaidCalls:true` 和唯一 `idempotencyKey`；token 到期刷新与 401/429/配额故障门已通过，
+  正式可用版本仍以 npm/GitHub Release 为准。

package/docs/G5-E2E-RUNBOOK.md

@@ -0,0 +1,110 @@
+# G5 真实 E2E 验收手册
+
+- 日期：2026-09-02
+- 当前状态：**真实 OAuth、跨重启恢复、token 自然到期刷新、QCC 主调用路径与 401/429/配额故障注入均已执行**
+- 适用脚本：`npm run e2e:g5`
+- 示例夹具：`test/fixtures/g5-e2e.example.json`（仅虚构数据）
+
+## 安全前提
+
+Runner 默认关闭，并同时执行以下硬门：
+
+1. 必须显式设置 `G5_E2E=1`。
+2. `G5_BASE_URL` 只允许 `http://127.0.0.1:*` 或 `http://localhost:*`，拒绝远端地址。
+3. `G5_E2E_MODE=enrich` 还必须显式设置 `G5_E2E_CONFIRM_PAID_CALLS=YES`。
+4. enrich 模式要求 capabilities 已为 `ready:true`；Runner 不代替用户发起 OAuth 连接。
+5. 报告仅保留状态、计数、错误码和安全审计数量，不写原始行、候选详情或 QCC 原始响应。
+6. 报告文件以 `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 工具：
+
+```bash
+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. 准备本机夹具
+
+把示例复制到仓库外或已忽略目录，再替换为经过批准的脱敏名单：
+
+```bash
+cp test/fixtures/g5-e2e.example.json /private/tmp/g5-e2e-input.json
+chmod 600 /private/tmp/g5-e2e-input.json
+```
+
+夹具结构：
+
+```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，再确认测试调用额度，最后运行：
+
+```bash
+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. 必验场景
+
+1. 未授权：capabilities 非 ready，Runner 在 enrich 前关闭。
+2. 首次授权：用户完成 OAuth 后，capabilities 变为 ready。
+3. 唯一匹配：完成工商补全。
+4. 多候选：初次只进入 `awaiting-review`；未确认前不调用工商详情。
+5. 候选确认：只调用工商详情及可选风险，不重复实体检索。
+6. 未匹配：保持 unresolved。
+7. token 刷新：工具短暂消失后恢复；仅 `UNKNOWN_TOOL` 竞态允许一次内部安全重解析。✅ 自然到期刷新已验
+8. 401、403、429、配额不足、超时和 5xx：映射为稳定错误码，且只能由用户显式重试。✅ 401/429/配额故障注入已验，其余有契约测试
+9. 混合批次：单企业失败不影响其他企业。
+10. 报告、日志和审计中无 Token、企业原名、信用代码、邮箱、手机号或原始工具响应。
+
+## 5. 当前限制
+
+- G5 run 与幂等记录只保存在 Host 内存，默认 TTL 30 分钟、最多 50 个 run；Host 重启或过期后必须新建 run。
+- 当前不持久化原始/补全行，这是刻意的隐私边界；后续如需跨重启恢复，应先完成加密存储与保留期设计评审。
+- Runner 不自动调用 `qcc_oauth_connect`，真实 OAuth 始终由用户在隔离环境显式完成。

package/docs/G5-HOST-BRIDGE.md

@@ -0,0 +1,136 @@
+# G5 Host Bridge：方案 B 批量补全基础层
+
+- 日期：2026-09-02
+- 状态：**G5-2.1～G5-2.5、真实 OAuth/QCC 主路径、token 自然到期刷新与 401/429/配额故障注入已验收**
+- 发布状态：0.4.0 发布候选，尚未创建 tag 或发布 npm 新版本
+- 决策依据：`docs/adr/0002-programmatic-mcp-tool-execution.md`
+
+## 本阶段交付
+
+`lib/qcc.js` 基于 DSH 公共 `ctx.tools.get()` / `ctx.tools.execute()` 实现 Host Bridge：
+
+1. 仅允许 `qcc_oauth_*`、规范 `mcp__qcc-*__*` 与 OAuth 0.1.7 已验证 legacy serverName，拒绝任意工具代理。
+2. 每次调用重新解析工具，兼容 OAuth 刷新造成的注销/重注册窗口；只对 `UNKNOWN_TOOL` 做一次安全重试，其他失败不自动重试，避免重复计费。
+3. 统一 call ID、AbortSignal、超时和 ToolRuntime `isError`，错误响应不携带工具原始业务数据。
+4. 解析 MCP `structuredContent` 或 QCC 文本 JSON，复用一期字段契约。
+5. 批量输入按企业名去重调用；唯一精确主体才继续工商/风险补全，多候选进入 `reviewQueue`，未匹配保留为 `unresolved`。
+6. 单企业失败隔离，不中断其他企业；原始/补全明细只在 Host/Web 同源边界内流转。
+
+## 数据流
+
+```text
+同源 Web 请求（显式确认计费）
+  → QccHostBridge.enrichRows
+    → 企业名去重 + 受控并发（1–4）
+      → ctx.tools.get（每次重新解析）
+      → ctx.tools.execute(mcp__qcc-company__get_company_by_query)
+        ├─ 唯一精确 → 锁定信用代码 → 工商详情 → 可选风险扫描
+        ├─ 多候选   → reviewQueue，停止该主体下游调用
+        └─ 未匹配   → unresolved
+  → 摘要 + 同源明细 + CSV 下载
+```
+
+## Web 契约
+
+### 被动能力探测
+
+`GET /data-cleaning/api/g5/capabilities`
+
+只检查工具是否注册，不调用 OAuth 或任何计费 QCC 工具。返回 Bridge marker、连接态推断和批量限制。
+同时声明 `idempotencyRequired / candidateResume / manualRetry`，run 状态仅为 `host-memory`。
+
+### 批量补全
+
+`POST /data-cleaning/api/g5/enrich`
+
+```json
+{
+  "idempotencyKey": "client-generated-unique-key",
+  "confirmPaidCalls": true,
+  "rows": [{ "name": "示例企业" }],
+  "headers": ["name"],
+  "nameField": "name",
+  "includeRisk": false,
+  "concurrency": 2
+}
+```
+
+约束：
+
+- `confirmPaidCalls` 必须严格为 `true`，否则在任何工具调用前返回 `QCC_CONFIRM_REQUIRED`。
+- `idempotencyKey` 必填；相同键与相同请求复用首个结果，不重复调用工具；同键不同请求返回冲突。
+- 单批最多 100 行，并发范围 1–4；重复企业只检索一次。
+- 响应包含 `summary / reviewQueue / errors / rows / csv`；完整明细不得转发给模型。
+- 多候选不会自动取第一项；响应提供 `runId`，状态为 `awaiting-review`。
+
+### 候选确认、人工重试与 run 查询
+
+- `POST /data-cleaning/api/g5/resolve`：传入 `runId / companyName / selectedCreditNo / idempotencyKey / confirmPaidCalls:true`。信用代码必须存在于该公司的待复核候选列表；成功后直接调用工商详情和可选风险，不重复实体检索。
+- `POST /data-cleaning/api/g5/retry`：传入 `runId / companyNames / idempotencyKey / confirmPaidCalls:true`。只允许重试错误队列中 `retryable:true` 的企业，且不会自动触发。
+- `GET /data-cleaning/api/g5/run/<runId>`：读取当前同源 run 状态，不调用 QCC 工具。
+
+run 状态为 `awaiting-review / needs-retry / completed-with-errors / completed`。明细、候选和幂等结果仅保存在 Host 内存，默认 TTL 30 分钟、最多 50 个 run；Host 重启后失效。
+
+## 错误分类与安全审计
+
+Host Bridge 把上游错误归一为稳定错误码：
+
+- 401/Token 失效 → `QCC_AUTH_REQUIRED`
+- 403/资源域未授权 → `QCC_PERMISSION_DENIED`
+- 429 → `QCC_RATE_LIMITED`
+- 配额不足 → `QCC_QUOTA_EXHAUSTED`
+- 超时 → `QCC_TIMEOUT`
+- 工具刷新消失 → `QCC_TOOL_UNAVAILABLE`
+- 5xx/连接故障 → `QCC_UPSTREAM_UNAVAILABLE`
+- 参数契约拒绝 → `QCC_UPSTREAM_REJECTED`
+
+错误响应不复述上游原始 message。每次物理工具调用只记录 toolName、callId、attempt、结果、稳定错误码和耗时；不记录参数、企业名或工具响应。
+
+## E2E Runner
+
+`scripts/g5-e2e.mjs` 默认关闭、仅允许回环 DSH Host；真实 enrich 还要求独立的付费确认变量。报告只包含脱敏摘要，详见 `docs/G5-E2E-RUNBOOK.md`。
+
+## 已通过的 Mock/Contract 门
+
+- Bridge 单元测试覆盖允许列表、每次解析、唯一 call ID、动态工具恢复、取消、超时、细分错误归一化、安全审计、响应解码、消歧、字段映射、锁定候选、去重批量、部分失败、未连接和批量上限。
+- Run/Web 测试覆盖并发幂等、同键冲突、候选合法性、续跑、人工重试、状态过期、capabilities、确认门和 CSV。
+- Runner/脱敏测试覆盖默认关闭、回环限制、付费确认、摘要报告及凭据/企业标识清洗。
+- Web 路由级故障注入覆盖 401、429、配额耗尽：确认不自动重试、人工重试门与安全审计语义。
+- 测试夹具只使用虚构企业与虚构信用代码，不含真实 token 或业务数据。
+
+## DSH rc.2 隔离 Host 冒烟
+
+2026-09-01 将当前工作树打包后安装到临时 `DSH_HOME`，在隔离端口 `43140` 启动 DSH `0.1.1-rc.2`；为规避本机文件监听器的 `EMFILE`，仅在该测试进程设置 `CHOKIDAR_USEPOLLING=1`。结果：
+
+- Host 成功执行插件 `apply()`；MVP seam 返回 `qccBridgeMounted:true`、`enrichSkillRegistered:true`，原有三工具与两个 Skill 均保持注册。
+- `GET /data-cleaning/api/g5/capabilities` 返回 `200`、marker `g5-host-bridge`、`ready:false`、`state:oauth-plugin-missing`，未调用 OAuth 或 QCC 工具。
+- 未传 `confirmPaidCalls:true` 的补全请求返回 `409 QCC_CONFIRM_REQUIRED`，证明计费确认门在工具调用前生效。
+- 显式确认后，因隔离 Host 未安装 QCC 动态工具而返回 `503 QCC_NOT_CONNECTED`，没有真实 OAuth、token 刷新或 QCC 请求。
+- 测试 Host 已停止；生产 GUI 端口 `43120` 未触碰。
+
+G5-2 在同日将更新后的 27 文件 tarball 安装到隔离 Profile，并在端口 `43141` 追加验证：
+
+- capabilities 返回 `idempotencyRequired:true / candidateResume:true / manualRetry:true / runPersistence:host-memory`。
+- 已确认计费但缺少幂等键时返回 `400 QCC_IDEMPOTENCY_REQUIRED`，零 QCC 工具调用。
+- 带合法幂等键时，由于隔离 Host 未安装 OAuth/QCC 工具，安全返回 `503 QCC_NOT_CONNECTED`。
+- `G5_E2E_MODE=preflight` Runner 成功生成权限 `0600` 的脱敏报告，只含 capabilities 摘要。
+- 测试 Host 已停止；没有安装 QCC OAuth、没有真实 QCC 调用，生产端口 `43120` 未触碰。
+
+## 真实 E2E 验收门
+
+2026-09-01 已通过：OAuth PKCE 首连、授权跨重启恢复、真实 company/history 工具调用、
+20 家公开企业/400 次调用、每企业当前最低 15 维与历史 4 维、证据脱敏边界。
+
+发布前验收状态：
+
+1. 未授权 host：返回 `QCC_NOT_CONNECTED` 并正确引导 `qcc_oauth_connect`。
+2. 已授权 host：用脱敏名单跑真实 `get_company_by_query` 与 `get_company_registration_info`。✅
+3. 多候选真实响应：不发生下游工商/风险调用。
+4. token 临期刷新：刷新期间工具短暂消失后恢复，且无重复计费调用。✅ 自然到期真实 refresh + 续期后 1 行调用
+5. 401/限流/配额不足/超时：错误分类、部分失败和人工重试符合契约。✅ 401/429/配额故障注入 + 其余契约测试
+6. includeRisk：风险因子计数逐字引用，不自行加总或推断。
+7. 审计：日志、响应错误、测试证据均不泄露 token 或未脱敏原始名单。✅ 主路径与故障注入均已验证
+
+2026-09-02 的刷新验收使用隔离 DSH `0.1.1-rc.2`、端口 `43159`：启动前 access token 已自然过期；
+启动后持久 grant 更新时间与到期时间均前移，16+4 工具恢复为 ready，随后 1 行真实 enrich 1/1 成功。
+测试 Host 已停止，生产 `43120` 未触碰。错误注入只走本地 Mock ToolRuntime，没有新增真实计费故障调用。

package/docs/PHASE2-ACCEPTANCE.md

@@ -0,0 +1,133 @@
+# 0.4.0 工商全景验收手册
+
+## 1. 目的与边界
+
+`scripts/phase2-acceptance.mjs` 是 0.4.0 源码仓库的本地验收 Runner（不进 npm 运行时包）。
+它只读取从真实 DSH/QCC
+工具轨迹整理出的 JSON 证据，不主动联网、不发起付费调用、不读取 OAuth token。
+
+Runner 验证：
+
+- 不少于 20 条企业记录；
+- 每条的主体消歧已完成，不允许多候选或未解析；
+- `resolveEntity` 和 `registration` 必须是含非空原值对照的 `resolved`，不能以 `no_data` 充数；
+- 每条不少于 15 个当前工商维度已交付；
+- 维度使用的 `sourceTool` 必须与 `lib/qcc-phase2.js` 中的已验证契约一致；
+- `resolved` 字段的 `value` 与 `sourceValue` 必须深度全等，防止金额、比例、计数或股权链被二次计算；
+- 启用历史域门时，必须标记企业认证账号，且每条 4 个历史工商维度都已交付。
+
+Runner 是「证据结构和结果契约」的自动检查，不是 QCC 调用器。真实性还需与同次
+DSH session/tool transcript 的时间和调用记录对应；Mock 或人工编造的数据不能作为发布证据。
+
+`sourceTool` 同时接受规范名 `mcp__qcc-company__*` / `mcp__qcc-history__*` 与
+`qcc-dsh-mcp-oauth@0.1.7` 实测 legacy 名 `mcp__company__*` / `mcp__history__*`；
+除此之外的别名仍会以 `SOURCE_TOOL_MISMATCH` 拒绝。
+
+### 1.1 真实调用前的只读预检
+
+在隔离 DSH Host 完成 OAuth 后，先请求：
+
+```bash
+curl -fsS -H 'sec-fetch-site: same-origin' \
+  http://127.0.0.1:<隔离端口>/data-cleaning/api/phase2/capabilities
+```
+
+该端点只读取 ToolRuntime 注册表，不调用 QCC，返回 `paidCalls:false` 和
+`executesTools:false`。进入当前工商 E2E 前应有 `companyRegistered:16` / `companyReady:true`；
+历史域应有 `historyRegistered:4` / `historyToolsReady:true`。
+
+`historyAuthorizationVerified:false` 在预检中始终为 false：工具已注册不等于企业认证账号已获权，
+账号权限只能在用户明确同意后通过真实历史工具调用验证。
+
+## 2. 证据文件契约
+
+真实证据不进 Git，建议放在已忽略的 `.phase2-e2e/`。企业名及信用代码不写入
+`reference`，只使用 `row-001` 这类不透明行号。
+
+```json
+{
+  "schemaVersion": 1,
+  "evidenceKind": "qcc-phase2-real-tool-transcript",
+  "synthetic": false,
+  "historyAccess": "enterprise-certified",
+  "records": [
+    {
+      "reference": "row-001",
+      "entityStatus": "resolved",
+      "dimensions": [
+        {
+          "domain": "company",
+          "id": "registration",
+          "status": "resolved",
+          "sourceTool": "mcp__qcc-company__get_company_registration_info",
+          "fields": [
+            {
+              "key": "reg_capital",
+              "value": "<实际输出值>",
+              "sourceValue": "<同次工具返回原值>"
+            }
+          ]
+        },
+        {
+          "domain": "company",
+          "id": "listing",
+          "status": "no_data",
+          "sourceTool": "mcp__qcc-company__get_listing_info",
+          "fields": []
+        }
+      ]
+    }
+  ]
+}
+```
+
+维度状态：
+
+- `resolved`：工具成功返回数据；必须至少有一个非空 `fields` 条目，且输出值与源值完全一致。
+- `no_data`：工具调用成功但该主体无此数据；`fields` 必须为空。该维度计入覆盖。
+- `permission_required` / `not_available` / `error`：显式降级，不计入覆盖数。
+
+公司域 `id` 和历史域 `id` 必须使用 [qcc-phase2.js](../lib/qcc-phase2.js) 的对象键。
+
+## 3. 执行命令
+
+只验收当前工商全景：
+
+```bash
+QCC_PHASE2_ACCEPTANCE=1 \
+QCC_PHASE2_EVIDENCE="$PWD/.phase2-e2e/evidence.json" \
+QCC_PHASE2_REPORT="$PWD/.phase2-e2e/report.json" \
+npm run e2e:phase2
+```
+
+同时强制验收企业认证历史域：
+
+```bash
+QCC_PHASE2_ACCEPTANCE=1 \
+QCC_PHASE2_REQUIRE_HISTORY=YES \
+QCC_PHASE2_EVIDENCE="$PWD/.phase2-e2e/evidence.json" \
+QCC_PHASE2_REPORT="$PWD/.phase2-e2e/report-history.json" \
+npm run e2e:phase2
+```
+
+退出码：
+
+- `0`：全部验收门通过；
+- `1`：证据可读，但记录数、维度、消歧、来源或原值一致性未达标；
+- `2`：Runner 未显式启用、文件缺失或 JSON 无法读取。
+
+## 4. 安全要求
+
+- 报告文件以 `0600` 权限写入，只包含计数、失败代码和 `row-xxx` 引用。
+- 不将 evidence、session transcript、OAuth 参数、token、企业名单或信用代码提交到 Git。
+- `synthetic:true` 的证据会被 Runner 显式拒绝，不能用单元测试夹具代替真实 E2E。
+- 若需付费调用，必须先在隔离 DSH Profile 内由用户明确确认额度和企业名单。
+
+## 5. 2026-09-01 真实验收记录
+
+- 环境：隔离 DSH `0.1.1-rc.2`，未触碰生产 `43120`。
+- 授权：OAuth PKCE 成功，6 个 Server 挂载，授权跨多次 Host 重启恢复成功。
+- 样本：20 家公开知名企业；顺序执行 400 次工具调用。
+- 结果：20/20 主体解析；每企业当前工商最低 15 维、历史工商 4 维；严格历史门通过。
+- `verifyIdentity` 因输入只含企业名而统一不交付，符合 Skill 的按需调用规则，15 维门不受影响。
+- 原始证据与报告位于 Git 忽略的 `.phase2-e2e/` 且为 `0600`；不进入 npm 包、Git、Issue 或日志。

package/docs/QCC-ENRICHMENT-DESIGN.md

@@ -208,8 +208,11 @@ content:
 ## 9. 与方案 B 的边界与预留
 
 - 方案 A 不改 `lib/`（最多可选加 `data_rows_to_csv` 工具）。
-- 方案 B 新增 `lib/qcc.js`（host 半区程序化调用 mcp-client），依赖 Spike #7 验证
-  `ctx.loader` 条目能否被插件代码直接 `tools/call`。
+- 方案 B 已新增 `lib/qcc.js`：Spike #7 双基线证明公共 `ctx.tools.execute()` 可程序化调度动态
+  MCP 工具；G5-2 幂等、候选续跑、人工重试与安全 Runner 的 Mock/Contract 已通过。
+  禁止访问 mcp-client 私有 client；真实 OAuth/QCC 主路径已验收，token 到期刷新与
+  2026-09-02 已完成自然过期 token refresh 与 401/429/配额故障注入验收；
+  故障注入使用本地 ToolRuntime，不重复真实付费批次。
 - 两者**共享**：§5 字段契约、§6 消歧策略、§7 未连接引导。方案 B 落地时直接复用，
   不重定义契约。