dsh-data-cleaning-agent 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,77 @@
 
 ## [Unreleased]
 
+## [0.5.0] - Release candidate (2026-09-02)
+
+> 风险 / 知产 / 经营三域批量补全、Mockup 对齐工作台与发布候选；尚未打 tag、发布 npm 或生成 GitHub Release。
+
+### Added
+- 冻结三域 91 工具契约：风险 38、知识产权 18、经营 35；兼容 canonical、OAuth 0.1.7 legacy 与短名，
+  明确 90 个 `searchKey` 工具和裁判文书详情的 `documentId` 依赖。
+- `Phase3BatchService` 与 `Phase3RunStore`：主体去重、精确/多候选/未匹配分流、调用上限、并发上限、
+  部分成功、30 分钟 Host 内存恢复、多候选续跑与只重试失败工具。
+- 同源 `/data-cleaning/api/phase3/{capabilities,estimate,enrich,resolve,retry,run}`；estimate 零调用，
+  计费端点强制 `confirmPaidCalls:true` + 唯一幂等键，结果和复核队列分别导出 CSV。
+- 默认关闭的 `e2e:phase3` Runner：仅允许回环 Host；preflight 要求 91/91 工具 ready 且验证零调用估算；
+  enrich 模式还要求显式付费确认、经批准夹具和正数 `maxCalls`，报告为 `0600` 且脱敏。
+
+### Changed
+- GitHub Actions 升级到 `actions/checkout@v7`、`actions/setup-node@v7` 与
+  `softprops/action-gh-release@v3`，移除托管 Runner 的 Node 20 action runtime 弃用警告。
+- 明确 QCC 采用客户自带连接/账号（BYO QCC）：客户自行承担其账号额度或合同费用，插件不共享 Key、
+  不代理结算、不代付；`confirmPaidCalls` 仅表示当前用户确认使用自己的 QCC 账号额度。
+- 应用内工作台升级为四步：上传与映射 → 数据体检 → 匹配核验 → 补全与导出；支持三域选择、
+  调用估算/二次确认、候选复核、失败重试、任务恢复与双 CSV。
+- 本地清洗接受显式字段映射；中文“企业名称/联系电话”等表头会按映射清洗，不再套用默认 `name/phone` 误删。
+- `enterprise-enrichment` Skill 增加风险/知产/经营域组，并保持多候选暂停、来源原值保真与权限/无数据/限流降级。
+- 同步修正 0.4.0 tarball README 的历史状态文案；已发布 0.4.0 仍为不可变快照。
+
+### Fixed
+- 修复真实 DSH React 渲染中，工作台关闭态在部分 store hooks 前返回导致首次打开报 React #310 的问题。
+
+### Verified
+- `npm run check`：125/125 测试通过；lint、双语版本、marketing 与 pack 白名单全绿。
+- DSH `0.1.1-rc.2` / `0.1.2-alpha.2` 隔离 Host 零调用冒烟共 24/24 通过；生产端口 43120 未触碰。
+- rc.2 实际渲染完成上传映射、体检和中文字段清洗闭环。
+- 2026-09-03 以维护者测试账号完成最小真实 Phase-3 E2E：1 家公开主体、1 个风险工具，
+  估算/实际调用均为 2，补全 1 行、待复核 0、错误 0；知产与经营域未做付费实调。
+
+## [0.4.0] - 2026-09-02
+
+> 工商全景与历史工商二期、QCC Host Bridge 和完整安全验收版本；已通过 npm OIDC Trusted Publishing
+> 发布并生成 GitHub Release。
+
+### 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/配额耗尽故障注入确认无自动重试、人工重试门正确且审计不泄密。
+- 公共 npm Registry 全新安装和 ESM 导入通过，导出 `apply / inject / name`。
+
 ## [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.5.0** (release candidate; npm `latest` remains 0.4.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)
@@ -24,6 +24,12 @@ The model only ever receives **aggregate summaries, never raw detail rows**. Det
 viewed and exported in the same-origin web UI, keeping customer raw data out of model context
 by construction.
 
+QCC enrichment follows a **bring-your-own connection and account (BYO QCC)** model. Each customer
+connects QCC MCP in their own DSH environment and uses quota or billing attached to their own QCC
+contract. This plugin does not embed, distribute, or share a maintainer key, does not resell QCC data,
+and does not pay or subsidize customer usage. Maintainer credentials are used only in isolated tests
+and are never shipped in the package.
+
 ## Quick start
 
 ```bash
@@ -34,6 +40,11 @@ Fully restart DeepSeek Harness afterwards (stop and re-run `dsh web`). Then say
 "help me clean this batch of company list data" and the plugin loads its built-in Skill and
 drives the clean / complete / profile tools.
 
+After restart, a "Data Cleaning" entry appears at the bottom of the sidebar: click it to open the
+workbench (upload & map → profile → match & review → enrich & export, four steps). When the model calls the clean /
+complete / profile tools, matching tool cards render in the conversation, and a jobs pill in the
+workbench header shows queued / running tasks.
+
 Without the `dsh` CLI, use the install script:
 
 ```bash
@@ -54,20 +65,46 @@ Or let an agent install it for you:
 | Parse | web `/data-cleaning/api/mvp/parse` | CSV / XLSX / JSON |
 | Async jobs | web `/data-cleaning/api/mvp/jobs` | job state machine + persistent storage |
 | UI | web `/data-cleaning/` | upload → clean/complete → export |
+| In-app entry | sidebar "Data Cleaning" button | opens the Mockup-aligned workbench: upload & map → profile → match & review → enrich & export |
+| Tool cards | `tool.call.toolview` (`data_clean_rows`/`data_complete_rows`/`data_profile`) | render clean/complete/profile result cards in-conversation with running/done/failed state |
+| Task progress | workbench header jobs pill | polls `/data-cleaning/api/mvp/jobs`; shows queued / running tasks |
 | 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: 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: real OAuth/QCC path, natural-expiry refresh, and fault injection verified |
+| Three-domain enrichment | web `/data-cleaning/api/phase3/*` | 0.5.0: risk 38 + IPR 18 + operation 35, zero-call estimate, user-owned QCC quota confirmation, candidate review, recovery/retry, and two CSV exports |
 
-## 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)**: the Host Bridge 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`. The flag means the current user
+  confirms use of their own QCC account quota; it does not transfer the charge to the plugin maintainer.
+  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. Natural-expiry
+  token refresh, dynamic-tool recovery, a post-refresh real call, and 401/429/quota fault injection also passed.
+- **0.5.0 three-domain batch extension (release candidate)**: a frozen 91-tool contract covers risk (38),
+  intellectual property (18), and operation (35). The workbench supports domain selection, a zero-call upper-bound
+  estimate, separate paid-call confirmation, manual ambiguous-candidate locking, partial-failure retry, 30-minute
+  Host-memory recovery, and result/review CSV exports. rc.2 and alpha.2 passed 24/24 zero-call Host smoke checks;
+  rc.2 passed actual rendering and Chinese company-field mapping. On 2026-09-03, a minimal real Phase-3 E2E
+  using the maintainer's own test account completed one public entity with one risk tool in two actual calls,
+  with no review items or errors. IPR and operation were covered by runtime registration, contract, and zero-call gates only.
+
+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 record](docs/RELEASE-0.4.0.md) for scope, validation gates, and rollback steps.
+See [the Phase-3 acceptance record](docs/PHASE3-ACCEPTANCE.md) and
+[the 0.5.0 release-candidate record](docs/RELEASE-0.5.0.md) for current gates, upgrade, and rollback.
 
 See [docs/PLAN-OSS.md](docs/PLAN-OSS.md) for details.
 
@@ -84,6 +121,10 @@ 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.
+The Phase-3 runner is also disabled by default: `npm run e2e:phase3` only permits a loopback Host,
+and real-call mode requires an additional confirmation for use of the maintainer's own test account.
 
 ## 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.5.0**（发布候选；npm `latest` 仍为 0.4.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)
@@ -22,6 +22,10 @@
 模型（LLM）**只拿到统计摘要，从不读取原始明细行**；明细只在同源 web 界面查看与导出，
 从架构上避免把客户原始数据灌进模型上下文。
 
+企查查补全采用 **客户自带连接与账号（BYO QCC）**：每位客户在自己的 DSH 中开通企查查 MCP，
+调用消耗其自有账号的套餐额度或按其与企查查的合同计费。本插件不内置、不分发、不共享开发者 Key，
+不代理结算，也不为客户代付或补贴企查查费用。维护者自己的 Key 仅用于隔离开发测试，不进入发布包。
+
 ## 30 秒开始
 
 ```bash
@@ -31,6 +35,9 @@ dsh plugin --profile web add dsh-data-cleaning-agent
 安装后**完全重启** DeepSeek Harness（停止后重新运行 `dsh web`）。
 之后在对话中说「帮我清洗这批企业名单数据」，插件会自动加载内嵌 Skill 并调度清洗/补全/画像工具。
 
+重启后侧边栏底部会出现「数据清洗」入口：点击打开工作台（上传与映射 → 数据体检 → 匹配核验 → 补全与导出四步），
+模型调用清洗/补全/画像工具时对话内会渲染对应工具卡片，工作台头部用任务 pill 展示排队/进行中的任务。
+
 没有 `dsh` CLI 时，也可以用安装脚本：
 
 ```bash
@@ -51,21 +58,50 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
 | 解析 | web `/data-cleaning/api/mvp/parse` | CSV / XLSX / JSON |
 | 异步任务 | web `/data-cleaning/api/mvp/jobs` | 任务状态机 + 持久化存储 |
 | UI | web `/data-cleaning/` | 上传 → 清洗/补全 → 导出 |
+| 应用内入口 | 侧边栏「数据清洗」按钮 | 打开 Mockup 对齐工作台：上传与映射 → 数据体检 → 匹配核验 → 补全与导出 |
+| 工具卡片 | `tool.call.toolview`（`data_clean_rows`/`data_complete_rows`/`data_profile`） | 对话内渲染清洗/补全/画像结果卡，含运行/已完成/失败状态 |
+| 任务进度 | 工作台头部任务 pill | 轮询 `/data-cleaning/api/mvp/jobs`，展示排队/运行中任务 |
 | 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 主路径、自然到期刷新与故障注入均已验收 |
+| 三域补全 | web `/data-cleaning/api/phase3/*` | 0.5.0：风险 38 + 知产 18 + 经营 35；零调用估算、显式付费确认、候选复核、恢复/重试与双 CSV 导出 |
 
-## 企查查 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 工具，
-  批量补全，模型只见最终摘要。
+  0.4.0 已将 16 个工商工具和 4 个历史工商工具固化为可测契约，
+  按 `panorama` / `ownership` / `governance` / `history` 维度组按需调用；未显式选择时不会默认打满全部付费工具。
+- **方案 B（后台程序化，0.4.0）**：Host Bridge 已通过公共 `ctx.tools.execute()` 实现
+  批量补全、请求幂等、多候选人工确认续跑、retryable 失败人工重试与安全审计。
+  批量 Web 端点同时要求 `confirmPaidCalls:true` 和唯一 `idempotencyKey`；该字段表示当前用户确认
+  使用自己的 QCC 账号额度，不代表插件开发者代客户付款；多候选绝不自动选择。
+  默认关闭的本机 E2E Runner 已就绪；2026-09-01 已在隔离 rc.2 Host 完成真实 OAuth、跨重启恢复和
+  20 家公开企业的 400 次 QCC 调用；自然过期 token 的真实刷新、动态工具恢复及 1 行续期后调用也已通过。
+  401 / 429 / 配额耗尽使用 Web→Bridge→ToolRuntime 故障注入验证，不额外消耗真实付费批次。
+- **0.5.0 三域批量扩展（发布候选）**：风险 38、知识产权 18、经营 35 个工具已冻结为 91 工具契约；
+  工作台支持域组勾选、零调用上界估算、独立付费确认、多候选人工锁定、部分失败人工重试、
+  30 分钟 Host 内存恢复、结果 CSV 与复核 CSV。rc.2 / alpha.2 零调用 Host 冒烟 24/24 通过，
+  rc.2 实际渲染与中文企业字段映射闭环通过。2026-09-03 又以维护者自己的测试账号完成最小真实
+  Phase-3 E2E：1 家公开主体、1 个风险工具、实际 2 次调用，1 行补全、0 待复核、0 错误；
+  知产与经营域本次只覆盖运行时注册、契约与零调用门。
+
+`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)。
+0.5.0 三域验收状态见 [docs/PHASE3-ACCEPTANCE.md](docs/PHASE3-ACCEPTANCE.md)，
+发布候选、升级与回滚见 [docs/RELEASE-0.5.0.md](docs/RELEASE-0.5.0.md)。
+
 ## 本地开发
 
 要求 Node.js 20 或更高。DSH 运行期服务（`ctx.tools` / `ctx.skills` / `ctx.jobs` /
@@ -77,6 +113,8 @@ npm run check
 ```
 
 `npm run check` 会依次执行 lint、文档版本一致性、发布包白名单校验与单元测试。
+真实 G5 验收必须按 [E2E 手册](docs/G5-E2E-RUNBOOK.md) 显式开启；默认执行 `npm run e2e:g5` 会安全拒绝。
+0.5.0 三域 Runner 同样默认关闭；`npm run e2e:phase3` 仅允许回环 Host，付费模式还需单独设置确认门。
 
 ## 配置
 

package/docs/COMPATIBILITY.md

@@ -11,12 +11,19 @@
 
 > 生产 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`；测试进程已停止。
+
+2026-09-02 的 0.5.0 发布候选在 rc.2（43136）与 alpha.2（43137）完成 24/24 零调用 Host 冒烟：
+MVP 路由、Phase-3 capabilities、estimate 与未确认 enrich 阻断均通过。rc.2 另完成实际工作台渲染、
+中文企业名称映射和本地清洗闭环；alpha.2 仍只定位为兼容探针。
+
 ## 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 +36,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 +52,53 @@
   `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 中同时报告两者。
+- 0.5.0 三域 Bridge 同时兼容 `mcp__qcc-{risk,ipr,operation}__*`、OAuth 0.1.7 实测 legacy
+  `mcp__{risk,ipr,operation}__*` 与内部短名；输出始终记录规范 `sourceTool` 和实际 `runtimeTool`。
+
+### 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 可用。
+
+### 4.2 应用内入口（M1–M3）双基线实测
+
+侧边栏「数据清洗」入口、全屏工作台、三张工具卡片（`data_clean_rows` /
+`data_complete_rows` / `data_profile`）与任务 pill 在双基线均已通过隔离 `DSH_HOME` 冒烟验证：
+
+- **rc.2**：根 HTML 直接引用 `/plugins/dsh-data-cleaning-agent/client.js?rev=…`，client bundle
+  HTTP 200 且含全部入口标记；后端 seam/parse/clean/complete/profile/jobs/ui 均 200/202。
+- **alpha.2**：web 半区默认要求鉴权，需先带 `?token=…` 访问拿 `dsh-auth-*` Cookie（303 → 200），
+  client bundle 改经合并端点 `/plugins/??dsh-data-cleaning-agent/client.js&rev=…` 交付，同样
+  200 且含全部入口标记；后端端点一致通过。
+
+两条基线均返回 `[dc-agent] host apply() ran`，且未发起任何真实 QCC 调用。
+
+### 4.3 0.5.0 三域兼容面
+
+| 能力 | rc.2 | alpha.2 | 备注 |
+| --- | --- | --- | --- |
+| 91 工具契约加载 | ✅ | ✅ | canonical / legacy / short-name 单测全覆盖 |
+| Phase-3 capabilities / estimate | ✅ | ✅ | 零 QCC 调用 |
+| 未确认 enrich 阻断 | ✅ | ✅ | HTTP 409，ToolRuntime 前阻断 |
+| 工作台实际交互 | ✅ | 探针 | rc.2 完成上传映射、体检、中文字段清洗 |
+| 维护者测试账号最小真实 Phase-3 E2E | ✅ 2/2 调用 | 不作为发布门 | rc.2：1 家公开主体 + 1 个风险工具；知产/经营仅过注册、契约与零调用门 |
 
 ## 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 均已发布 `v0.4.0`。
+- `/data-cleaning/api/phase3/*` 为 0.5.0 发布候选；单批最多 100 行、并发最多 4、默认/硬调用上限
+  500/2000。run 只保留在 Host 内存 30 分钟，Host 重启不恢复。
+- alpha.2 的实际 UI 只作兼容探针；0.5.0 的稳定发布与回滚判断以 rc.2 为准。

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/配额故障注入已验收**
+- 发布状态：✅ 已随 `v0.4.0` 发布到 npm 与 GitHub Release
+- 决策依据：`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，没有新增真实计费故障调用。