dsh-data-cleaning-agent 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,8 +4,45 @@
 
 ## [Unreleased]
 
-> 目标版本：`0.4.0`。源码版本、token 到期刷新、401/429/配额故障门与 Linux/Windows 远端 CI
-> 均已通过；尚未创建 `v0.4.0` tag、GitHub Release 或 npm 发布。
+## [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 个历史工商工具）；
@@ -36,6 +73,7 @@
 - 原始证据与脱敏报告仅保存在 Git 忽略的 `.phase2-e2e/`，权限为 `0600`；未触碰生产端口。
 - 自然过期 access token 的真实 refresh、动态工具恢复与续期后最小真实调用已通过；
   401/429/配额耗尽故障注入确认无自动重试、人工重试门正确且审计不泄密。
+- 公共 npm Registry 全新安装和 ESM 导入通过，导出 `apply / inject / name`。
 
 ## [0.3.0] - 2026-09-01
 

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 source version / 当前源码版本: **0.4.0** (release candidate; npm `latest` remains 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,10 +65,14 @@ 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 Skill enrichment | `enterprise-enrichment` | 0.4.0 release candidate: company panorama, ownership, governance, and historical registration |
+| 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 release candidate: real OAuth/QCC path, natural-expiry refresh, and fault injection verified |
+| 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 (status and roadmap)
 
@@ -67,19 +82,29 @@ Besides local deterministic completion, the plugin supports Qichacha MCP enterpr
   `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, 0.4.0 release candidate)**: the Host Bridge now supports batch enrichment,
+- **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`; 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.
+  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 checklist](docs/RELEASE-0.4.0.md) for scope, blocking gates, and rollback steps.
+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.
 
@@ -98,6 +123,8 @@ npm run check
 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 source version: **0.4.0**（发布候选；npm `latest` 仍为 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,10 +58,14 @@ 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` | 引导模型按工作流调度上述工具 |
-| 企查查 Skill 补全 | `enterprise-enrichment` | 0.4.0 发布候选：工商全景、股权穿透与历史工商 |
+| 企查查 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 主路径、自然到期刷新与故障注入均已验收 |
+| 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 补全（状态与路线图）
 
@@ -63,14 +74,21 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
 - **方案 A（模型中介，优先）**：用户已用 `qcc-dsh-mcp-oauth` 连接企查查后，
   Skill 引导模型对名单中每个企业名调用 `mcp__qcc-company__get_company_by_query` /
   `mcp__qcc-company__get_company_registration_info`，把返回的最新工商信息回填到补全工具。
-  `main` 上的 0.4.0 开发切片已将 16 个工商工具和 4 个历史工商工具固化为可测契约，
+  0.4.0 已将 16 个工商工具和 4 个历史工商工具固化为可测契约，
   按 `panorama` / `ownership` / `governance` / `history` 维度组按需调用；未显式选择时不会默认打满全部付费工具。
-- **方案 B（后台程序化，0.4.0 发布候选）**：Host Bridge 已通过公共 `ctx.tools.execute()` 实现
+- **方案 B（后台程序化，0.4.0）**：Host Bridge 已通过公共 `ctx.tools.execute()` 实现
   批量补全、请求幂等、多候选人工确认续跑、retryable 失败人工重试与安全审计。
-  批量 Web 端点同时要求 `confirmPaidCalls:true` 和唯一 `idempotencyKey`；多候选绝不自动选择。
+  批量 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__*`。
@@ -80,7 +98,9 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
 
 0.4.0 真实账号验收的证据格式、安全门和命令见
 [docs/PHASE2-ACCEPTANCE.md](docs/PHASE2-ACCEPTANCE.md)。
-发布范围、阻断门和回滚步骤见 [docs/RELEASE-0.4.0.md](docs/RELEASE-0.4.0.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)。
 
 ## 本地开发
 
@@ -94,6 +114,7 @@ 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,9 +11,13 @@
 
 > 生产 GUI（`http://127.0.0.1:43120`）不用于验证，验证一律使用隔离 `DSH_HOME` + 专用端口。
 
-2026-09-01 的 0.4.0 发布候选已分别在 rc.2（43153）和 alpha.2（43154）
+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`。
@@ -52,6 +56,8 @@
   调用动态注册的 `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 实测结论
 
@@ -62,11 +68,37 @@
 - 真实 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，
+- `/data-cleaning/api/g5/enrich` 为 0.4.0 已发布能力，单批上限 100 行、并发上限 4，
   且必须显式 `confirmPaidCalls:true` 和唯一 `idempotencyKey`；token 到期刷新与 401/429/配额故障门已通过，
-  正式可用版本仍以 npm/GitHub Release 为准。
+  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-HOST-BRIDGE.md

@@ -2,7 +2,7 @@
 
 - 日期：2026-09-02
 - 状态：**G5-2.1～G5-2.5、真实 OAuth/QCC 主路径、token 自然到期刷新与 401/429/配额故障注入已验收**
-- 发布状态：0.4.0 发布候选，尚未创建 tag 或发布 npm 新版本
+- 发布状态：✅ 已随 `v0.4.0` 发布到 npm 与 GitHub Release
 - 决策依据：`docs/adr/0002-programmatic-mcp-tool-execution.md`
 
 ## 本阶段交付

package/docs/PHASE3-ACCEPTANCE.md

@@ -0,0 +1,129 @@
+# 0.5.0 三域补全验收记录
+
+> 状态：**本地 / Mock / 双基线零调用门及维护者测试账号的最小真实 Phase-3 E2E 均已通过。**
+>
+> 记录日期：2026-09-03
+
+## 1. 验收范围
+
+0.5.0 覆盖企查查风险、知识产权、经营三域：
+
+| 域 | 工具数 | 规范前缀 |
+| --- | ---: | --- |
+| 风险 | 38 | `mcp__qcc-risk__*` |
+| 知识产权 | 18 | `mcp__qcc-ipr__*` |
+| 经营 | 35 | `mcp__qcc-operation__*` |
+| 合计 | 91 | — |
+
+验收同时覆盖批量 Host Bridge、同源 Web API、四步工作台、安全门、任务恢复、导出与发布包。
+
+## 2. 已通过门
+
+### 2.1 自动化
+
+- `npm run check`：125/125 测试通过。
+- 三域工具规范名、OAuth 0.1.7 legacy 名和短名共 91 个逐一归一化测试通过。
+- 未确认付费、幂等冲突、调用上限、工具缺失、多候选、部分失败、人工重试、TTL 失效均有回归。
+- `e2e:phase3` 默认关闭、只允许回环 Host、preflight 失败关闭、`0600` 脱敏报告均有测试。
+
+### 2.2 DSH 双基线零调用 Host 冒烟
+
+使用当前 tarball 装入隔离 profile，未触碰生产端口 `43120`：
+
+| 基线 | 端口 | 结果 |
+| --- | ---: | --- |
+| DSH `0.1.1-rc.2` | 43136 | 12/12 PASS |
+| DSH `0.1.2-alpha.2` | 43137 | 12/12 PASS |
+
+每条基线覆盖 Host 启动、MVP seam/parse/clean/complete/profile/jobs/UI、Phase-3 capabilities、
+零调用 estimate，以及未确认 enrich 在 ToolRuntime 前返回 409。合计 24/24 PASS。
+
+### 2.3 rc.2 实际渲染与交互
+
+- DSH 侧边栏「数据清洗」入口可发现。
+- 四步工作台实际渲染：上传与映射 → 数据体检 → 匹配核验 → 补全与导出。
+- 修复真实 React Host 才暴露的 #310 hooks 顺序问题；修复后工作台打开无崩溃。
+- 中文 CSV 的“企业名称”自动映射；解析后留在映射页供确认。
+- 两行中文企业数据进入本地清洗后保留 2、误删 0；未发起任何真实 QCC 调用。
+
+### 2.4 0.5.0 最终候选安装物
+
+- `npm run check` 通过，pack 白名单共 35 个文件。
+- 0.5.0 最终 tarball 已安装到全新 DSH `0.1.1-rc.2` 隔离 profile，并在端口 `43164` 启动。
+- `mvp-seam` 返回 Host/Web/三工具/两个 Skill 注册成功，`enrichSkillRegistered: true`。
+- Phase-3 capabilities 和 estimate 可达；一行企业、三域全选的调用上界估算为 92 次。
+- 未确认付费 enrich 在 ToolRuntime 前返回 409；全新 profile 未安装 OAuth 插件时明确返回
+  `oauth-plugin-missing`，未误报三域工具可用。
+- 未触碰生产端口 `43120`，未产生任何真实 QCC 调用。
+
+### 2.5 最小真实 Phase-3 E2E（维护者测试账号）
+
+- 2026-09-03 在隔离 DSH `0.1.1-rc.2` Profile、端口 `43166` 执行；生产端口 `43120` 未触碰。
+- 夹具为 1 家官网公开主体，仅批准 `get_company_risk_scan`，`maxCalls: 2`、`concurrency: 1`，不自动重试。
+- preflight 确认风险 38 + 知产 18 + 经营 35，共 91/91 个工具 ready；零业务调用。
+- 真实 enrich 返回 `completed`：估算 2 次、实际 2 次、补全 1 行、部分成功 0、待复核 0、错误 0。
+- 本次付费实调只覆盖主体解析 + 1 个风险工具；知识产权与经营域通过运行时注册、契约和零调用门验证，
+  未宣称已逐域进行付费实调。
+- 调用使用维护者自己的 QCC 测试账号并由维护者承担测试额度；未使用客户账号。
+- 夹具与报告均为 `0600`，报告只记录脱敏摘要；隔离 Host 停止后，复制出的 OAuth grant、夹具、
+  报告及临时安装目录均已删除，未进入 Git 或 npm 包。
+
+## 3. 开发者测试账号的真实计费 E2E 门
+
+本节只约束发布前由维护者使用**自己的测试 Key / QCC 账号**执行的真实 Phase-3 E2E；测试产生的额度
+或费用由维护者自己承担。客户在生产使用时必须连接客户自己的 QCC MCP 账号，额度或费用由客户
+依据其自身企查查合同承担；插件开发者不代付、不垫付，也不向客户提供开发者 Key。
+
+真实 Phase-3 测试会消耗维护者测试账号的 QCC 调用额度，因此不从本地门自动继承授权。后续若扩大
+本次已批准的最小范围，执行前仍必须明确批准：
+
+1. 企业夹具（建议先 1–3 家公开企业）；
+2. 精确域或工具清单；
+3. `maxCalls` 上限与维护者测试账号预算；
+4. 隔离 DSH Home、端口和报告目录；
+5. 是否允许候选确认后的续跑与失败工具人工重试。
+
+未同时获得上述批准时，不得设置 `PHASE3_E2E_CONFIRM_PAID_CALLS=YES`。
+
+## 4. Runner 用法
+
+零调用 preflight 仍要求 Host 已注册 91/91 三域工具：
+
+```bash
+PHASE3_E2E=1 \
+PHASE3_E2E_MODE=preflight \
+PHASE3_BASE_URL=http://127.0.0.1:43162 \
+npm run e2e:phase3
+```
+
+真实 enrich 仅在批准后执行。夹具应放在 Git 忽略目录，并设为 `0600`：
+
+```json
+{
+  "headers": ["name"],
+  "nameField": "name",
+  "rows": [{ "name": "APPROVED_PUBLIC_COMPANY" }],
+  "domains": ["risk"],
+  "tools": [],
+  "maxCalls": 39,
+  "concurrency": 1
+}
+```
+
+```bash
+PHASE3_E2E=1 \
+PHASE3_E2E_MODE=enrich \
+PHASE3_E2E_CONFIRM_PAID_CALLS=YES \
+PHASE3_BASE_URL=http://127.0.0.1:43162 \
+PHASE3_FIXTURE_PATH=.phase3-e2e/approved.json \
+PHASE3_E2E_REPORT=.phase3-e2e/report.json \
+npm run e2e:phase3
+```
+
+## 5. 发布判断
+
+- 本地代码、Mock、Web、UI 和双基线零调用门：**GO**。
+- npm pack / 全新隔离安装物料：**GO**。
+- 维护者测试账号最小真实 Phase-3 E2E：**GO（1 家公开主体、1 个风险工具、实际 2 次调用）**。
+- 知产与经营域逐域付费实调：**非本次发布阻断项；如执行须重新批准范围和维护者测试预算**。
+- tag、npm publish、GitHub Release：**HOLD，必须单独批准**。

package/docs/QCC-PHASES-ROADMAP.md

@@ -29,8 +29,8 @@
 | 阶段 | 版本 | 交付形态 | 覆盖维度 | 依赖 |
 | --- | --- | --- | --- | --- |
 | 一期 | 0.3.0 ✅ | 方案 A：模型中介式 Skill `enterprise-enrichment` | 核心工商 7 字段 + 风险标签 | `qcc-dsh-mcp-oauth` 已连接 |
-| 二期 | 0.4.0 | 方案 A 扩展 Skill：工商全景 + 股权穿透 | 工商域 16 工具 + 历史工商 | 同上 |
-| 三期 | 0.5.0 | 方案 A 扩展 Skill：风险/知产/经营 + 方案 B 批量后端 | 风险 38 + 知产 18 + 经营 35 | 同上；S7 PASS，G5-2 安全闭环已落地 |
+| 二期 | 0.4.0 ✅ | 方案 A 扩展 Skill：工商全景 + 股权穿透 | 工商域 16 工具 + 历史工商 | 同上 |
+| 三期 | 0.5.0 RC | 方案 A 扩展 Skill：风险/知产/经营 + 方案 B 批量后端 | 风险 38 + 知产 18 + 经营 35 | 本地/双基线零调用门与最小真实 Phase-3 E2E 已过；待发布授权 |
 | 四期（可选） | 0.6.0 | 历史轨迹 + 董监高 + 招投标 | 历史 34 + 人员 44 + 招投标 6 | 企业认证账号（历史域） |
 
 每期之间不互相阻塞：二期工商全景、三期风险知产都可独立评审与合入。
@@ -93,7 +93,7 @@ v1 字段契约（方案 A）：
 - 消歧规则不变（`get_company_by_query` 多候选必须询问用户）。
 - 金额/比例/计数逐字引用工具返回值，禁止自算、禁止臆测。
 
-### 3.4 实施状态（0.4.0 发布候选）
+### 3.4 实施状态（0.4.0 已发布）
 
 - ✅ 第一切片：`lib/qcc-phase2.js` 已固化本地 QCC MCP 一手源码核对过的
   16 个工商工具和 4 个历史工商工具；`enterprise-enrichment` 已扩展为按维度组调用。
@@ -199,6 +199,11 @@ v1 字段契约（方案 A）：
   retryable 失败人工重试、细分错误分类与安全审计，均已通过 Mock/Contract 测试。
 - 已通过：真实 OAuth 首连、授权跨重启恢复、真实 QCC 主调用路径、token 自然到期刷新与续期后调用。
 - 已通过：401/429/配额耗尽故障注入；仅 retryable 错误允许用户显式重试，非 retryable 配额错误在派发前阻断。
+- 已完成：91 工具冻结契约、三域批量服务、`/phase3/*` API、四步工作台、零调用估算、
+  付费确认、候选续跑、失败工具重试、双 CSV 和默认关闭的 `e2e:phase3` Runner。
+- 已验证：125/125 自动化、rc.2 / alpha.2 Host 零调用冒烟 24/24、rc.2 实际 UI 与中文字段映射闭环。
+- 待批准：维护者测试账号真实三域 E2E 的企业夹具、域、调用上限与维护者自担测试预算；
+  客户生产账号费用不在插件承担范围内，未批准测试边界前不得执行。
 
 ---
 
@@ -248,7 +253,7 @@ v1 字段契约（方案 A）：
 
 ## 7. 分期评审与合入规则
 
-- 每期交付前须通过 `npm run check`（lint + docs:check + marketing:check + verify-pack + 13 例测试）。
+- 每期交付前须通过 `npm run check`（lint + docs:check + marketing:check + verify-pack + 全量测试）。
 - 每期新增 Skill 内容须遵守安全不变量：不编造字段、多候选必询问、金额比例计数逐字引用。
 - 历史域（`qcc-history`）与四期人员历史工具需企业认证账号，未授权时 Skill 须显式降级并说明，不得假装补全。
 - 版本号按 SemVer：二期 0.4.0、三期 0.5.0、四期 0.6.0，均需 CHANGELOG + README 版本同步后走 OIDC 发布。

package/docs/RELEASE-0.4.0.md

@@ -1,8 +1,10 @@
-# 0.4.0 发布候选检查单
+# 0.4.0 发布记录与检查单
 
 - 源码版本：`0.4.0`
-- 状态：发布候选，尚未创建 `v0.4.0` tag、GitHub Release 或 npm 发布
+- 状态：✅ 已发布；npm `latest`、Git tag 与 GitHub Release 均为 `0.4.0`
 - 基线日期：2026-09-02
+- 发布提交：`4cc7b03`
+- Release workflow：`33575803070`（tag/版本检查、`npm run check`、OIDC publish、GitHub Release 全部成功）
 
 ## 已纳入范围
 
@@ -34,10 +36,9 @@
 1. ✅ access token 自然到期后的真实 refresh、持久 grant 更新、动态工具恢复与续期后最小真实调用。
 2. ✅ 401、429、配额不足的本地故障注入、稳定错误码、人工重试门及审计脱敏。
 
-代码审查、本机 `npm run check`、干净工作树和远端 CI 已完成；剩余只是创建/推送 tag 所触发的正式发布操作，
-不再有 0.4.0 功能实现缺口。
+代码审查、本机 `npm run check`、干净工作树、远端 CI 与正式发布均已完成；不再有 0.4.0 功能或发布缺口。
 
-## 发布命令（阻断门全部通过后）
+## 已执行的发布流程
 
 ```bash
 npm run check
@@ -46,8 +47,16 @@ git tag -a v0.4.0 -m "Release v0.4.0"
 git push origin v0.4.0
 ```
 
-`v0.4.0` tag 会触发 `.github/workflows/release.yml`：校验 tag/包版本、执行完整检查、
-通过 npm OIDC Trusted Publishing 发布并生成 GitHub Release。不要手工写入生产密钥。
+`v0.4.0` tag 已触发 `.github/workflows/release.yml`：校验 tag/包版本、执行完整检查、
+通过 npm OIDC Trusted Publishing 发布并生成 GitHub Release；全程没有手工写入生产密钥。
+
+发布后验证：npm Registry 返回 `latest=0.4.0`，公共 tarball 全新隔离安装成功，ESM 导入可见
+`apply / inject / name`；公共 Registry 包安装到全新 DSH profile 后在隔离端口 43160 成功启动，
+三工具、两个 Skill、Web 与 QCC Bridge seam 均注册；GitHub Release 为非 draft、非 prerelease。
+
+已知文档差异：npm 的 0.4.0 tarball/包页面 README 是 tag 时的不可变快照，仍含“发布候选 / latest 0.3.0”
+字样；GitHub `main` 已修正。该差异不影响代码、版本或安装，且不得覆盖已发布版本；如需同步 npm 包内文案，
+应发布新的补丁版本 `0.4.1`。
 
 ## 回滚
 

package/docs/RELEASE-0.5.0.md

@@ -0,0 +1,84 @@
+# 0.5.0 发布候选记录
+
+> 状态：**Release candidate；未打 tag、未发布 npm、未创建 GitHub Release。**
+>
+> npm `latest` 仍为 `0.4.0`。
+
+## 1. 范围
+
+0.5.0 在 0.4.0 工商/历史工商 Host Bridge 上新增：
+
+- 风险 38 + 知产 18 + 经营 35 的 91 工具冻结契约；
+- 三域批量服务与 30 分钟 Host 内存 run；
+- capabilities / estimate / enrich / resolve / retry / run 同源 API；
+- 四步 Mockup 对齐工作台、域组选择、调用估算、付费二次确认；
+- 多候选人工续跑、部分失败人工重试、结果/复核双 CSV；
+- 默认关闭、回环限定、失败关闭的 Phase-3 E2E Runner。
+
+0.5.0 不新增 OAuth 存储或私有 MCP client。所有调用继续走公共 `ctx.tools.get/execute`，
+OAuth/token 生命周期由 `qcc-dsh-mcp-oauth` 和 `dsh-mcp-client` 负责。
+
+## 2. 兼容矩阵
+
+| 组合 | 级别 | 当前结论 |
+| --- | --- | --- |
+| DSH `0.1.1-rc.2` | 稳定发布基线 | Host/API 12/12；实际工作台渲染与字段映射闭环通过 |
+| DSH `0.1.2-alpha.2` | 兼容探针 | Host/API 12/12；不承诺 alpha 私有/实验 API 稳定性 |
+| Node 22 / 24 | CI 基线 | `npm run check` 目标矩阵 |
+| `qcc-dsh-mcp-oauth@0.1.7` | 已验证 OAuth 线 | Bridge 兼容 canonical 与 legacy serverName |
+
+## 3. 升级
+
+从 0.4.0 升级：
+
+```bash
+dsh plugin --profile web add dsh-data-cleaning-agent@0.5.0
+```
+
+然后完全停止并重启 `dsh web`。升级是加法变更：
+
+- 现有 `data_clean_rows` / `data_complete_rows` / `data_profile` 不变；
+- `data-cleaning` 与 `enterprise-enrichment` Skill 名不变；
+- `/data-cleaning/api/mvp/*` 与 `/data-cleaning/api/g5/*` 保留；
+- 新增 `/data-cleaning/api/phase3/*`；
+- `dc_tasks_v1` 存储域不迁移；Phase-3 run 只在 Host 内存保存，重启后按设计失效。
+
+升级后先运行零调用 capabilities / estimate，再批准任何付费批次。
+
+## 4. 回滚
+
+回滚到已发布 0.4.0：
+
+```bash
+dsh plugin --profile web add dsh-data-cleaning-agent@0.4.0
+```
+
+完全重启 Host。回滚影响：
+
+- Phase-3 路由和三域工作台能力消失；
+- 正在运行或等待复核的 Phase-3 内存 run 丢失，需从原输入新建任务；
+- 本地 CSV 文件、已下载结果和 `dc_tasks_v1` 不删除；
+- 0.4.0 的 G5 工商批量能力继续可用。
+
+不得通过覆盖已发布 npm 版本实现回滚；只安装明确版本。
+
+## 5. 已完成发布门
+
+- [x] `npm run check` 125/125；lint/docs/marketing/pack 全绿。
+- [x] rc.2 / alpha.2 隔离 Host 零调用冒烟 24/24。
+- [x] rc.2 实际 UI 渲染、上传映射、体检、中文字段清洗闭环。
+- [x] 计费确认、幂等、上限、多候选、重试、脱敏回归。
+- [x] README 中英文、CHANGELOG、兼容矩阵、用户指南、验收记录、升级/回滚。
+- [x] 0.5.0 包白名单与 release-candidate 文档。
+- [x] 最终候选执行 `npm run check` 与 pack 内容复核，tarball 为 35 个白名单文件。
+- [x] 最终候选 tarball 安装到全新 DSH `0.1.1-rc.2` 隔离 profile 并启动成功。
+- [x] 隔离 Host 验证 seam、Phase-3 capabilities / estimate 与未确认付费失败关闭；未触碰生产端口 `43120`。
+- [x] 维护者测试账号最小真实 Phase-3 E2E：1 家公开主体、1 个风险工具、`maxCalls: 2`，
+  实际 2 次调用，1 行补全、0 待复核、0 错误；隔离端口 `43166`，临时凭据副本已清理。
+
+## 6. 发布前外部门
+
+- [ ] 用户明确批准创建并推送 `v0.5.0` tag。
+- [ ] 等待 OIDC workflow 完成 npm provenance 与 GitHub Release；再核验公共 Registry 全新安装。
+
+发布前任何一项失败都不得移动 `latest`。