dsh-data-cleaning-agent 0.3.0 → 0.5.0

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/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-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 落地时直接复用，
   不重定义契约。
 

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 | 同上 + Spike #7（`ctx.loader` 可调） |
+| 二期 | 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,6 +93,23 @@ v1 字段契约（方案 A）：
 - 消歧规则不变（`get_company_by_query` 多候选必须询问用户）。
 - 金额/比例/计数逐字引用工具返回值，禁止自算、禁止臆测。
 
+### 3.4 实施状态（0.4.0 已发布）
+
+- ✅ 第一切片：`lib/qcc-phase2.js` 已固化本地 QCC MCP 一手源码核对过的
+  16 个工商工具和 4 个历史工商工具；`enterprise-enrichment` 已扩展为按维度组调用。
+- ✅ 安全规则：多候选人工确认、付费组按需调用、数值原样保留、来源工具标记、
+  历史域无权显式降级。
+- ✅ 验收自动化：`e2e:phase2` 默认关闭，检查 20 企业 / 每企业 ≥15 维、
+  来源工具、原值一致性、主体消歧和历史账号门，拒绝合成证据替代真实 E2E。
+- ✅ DSH 冒烟：当前工作树 tarball 已在隔离 `0.1.1-rc.2` 和 `0.1.2-alpha.2` Host
+  完成加载，两者 seam 均返回 `enrichSkillRegistered:true`；测试 Host 已停止，生产端口未触碰。
+- ✅ 预检状态冒烟：无 OAuth 插件时返回 `oauth-plugin-missing`；安装插件但未授权时
+  返回 `not-connected-or-refreshing`。两种情况都不执行 QCC 工具，不产生付费调用。
+- ✅ 真实发布门主路径：隔离 rc.2 Host 完成 OAuth、20 企业、400 次调用；20/20 主体解析，
+  每企业当前最低 15 维、历史 4 维，严格验收通过。
+- ✅ 2026-09-02 发布门收口：自然过期 token 真实刷新、16+4 动态工具恢复、续期后 1 行真实 enrich；
+  401/429/配额耗尽通过 Web→Bridge→ToolRuntime 故障注入验证，无自动重试且审计脱敏。
+
 ---
 
 ## 4. 三期（0.5.0）· 风险 / 知产 / 经营 + 批量后端
@@ -174,9 +191,19 @@ v1 字段契约（方案 A）：
 ### 4.4 三期并行 · 方案 B 批量后端
 
 一期/二期/三期均为模型中介式（模型逐个调 QCC 工具）。当名单规模进入百级/千级，模型逐调成本高，
-启动方案 B（插件内 `lib/qcc.js` 直接经 `ctx.loader` 调用 mcp-client 条目）：
-- 前置：Spike #7 验证「`ctx.loader` 拿到的 mcp-client 条目可在插件后端直接调用」。
-- 若验证失败，方案 B 边界封闭，退回方案 A 的分批模型中介。
+方案 B 已启动：插件内 `lib/qcc.js` 经公共 `ctx.tools.execute()` 调用 mcp-client 动态注册的工具；
+不直接访问 `ctx.loader` 条目或 mcp-client 私有 client。
+
+- Spike #7：rc.2 / alpha.2 双基线 PASS。
+- G5-2：在 G5-1 基础上完成默认关闭 E2E Runner、脱敏、请求幂等、多候选确认续跑、
+  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 的企业夹具、域、调用上限与维护者自担测试预算；
+  客户生产账号费用不在插件承担范围内，未批准测试边界前不得执行。
 
 ---
 
@@ -226,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

@@ -0,0 +1,66 @@
+# 0.4.0 发布记录与检查单
+
+- 源码版本：`0.4.0`
+- 状态：✅ 已发布；npm `latest`、Git tag 与 GitHub Release 均为 `0.4.0`
+- 基线日期：2026-09-02
+- 发布提交：`4cc7b03`
+- Release workflow：`33575803070`（tag/版本检查、`npm run check`、OIDC publish、GitHub Release 全部成功）
+
+## 已纳入范围
+
+- `enterprise-enrichment` 扩展为工商全景、股权、治理和历史工商维度组按需调用。
+- 固化 16 个当前工商工具与 4 个历史工商工具契约，并兼容
+  `qcc-dsh-mcp-oauth@0.1.7` 实测 legacy serverName。
+- 新增只读 `/data-cleaning/api/phase2/capabilities` 预检、真实证据验收器与默认关闭的本地 Runner。
+- G5 Host Bridge 提供批量幂等、多候选人工续跑、retryable 失败人工重试、取消/超时、错误分类和脱敏审计。
+- 发布 workflow 在发布前执行完整 `npm run check`，并强制 Git tag 与 `package.json` 版本一致。
+
+## 已通过门
+
+- 单元、契约、Web 路由、Skill、脱敏和 Runner 自动测试。
+- npm 打包白名单与 README/包版本一致性检查。
+- DSH `0.1.1-rc.2` / `0.1.2-alpha.2` 隔离 Host 加载冒烟。
+- rc.2 隔离 Host 真实 OAuth、授权跨重启恢复、20 家公开企业、400 次 QCC 调用：
+  20/20 主体解析，每企业当前工商最低 15 维、历史工商 4 维。
+- rc.2 隔离 Host 的旧 access token 已自然过期；重新启动后持久 grant 自动刷新、到期时间前移，
+  16 个 company + 4 个 history 动态工具恢复，并以 1 行真实 enrich（1/1 成功、2 条安全审计）确认新 token 可用。
+- Web→Bridge→Mock ToolRuntime 故障注入覆盖 401、429 与配额耗尽：除 `UNKNOWN_TOOL` 刷新竞态外
+  均不自动重试；401/429 只能显式人工重试，配额耗尽在重新派发前阻断；审计不含参数、原始响应或秘密。
+- `main` 提交 `0c8cb75` 的远端 CI `33569931224` 已通过 Linux Node 22、Linux Node 24 与 Windows Node 24 全矩阵。
+- 真实证据与报告仅保存在 Git 忽略的本机目录，不进入仓库或 npm 包。
+
+## 发布阻断门（已通过）
+
+2026-09-02 已完成此前两个剩余门：
+
+1. ✅ access token 自然到期后的真实 refresh、持久 grant 更新、动态工具恢复与续期后最小真实调用。
+2. ✅ 401、429、配额不足的本地故障注入、稳定错误码、人工重试门及审计脱敏。
+
+代码审查、本机 `npm run check`、干净工作树、远端 CI 与正式发布均已完成；不再有 0.4.0 功能或发布缺口。
+
+## 已执行的发布流程
+
+```bash
+npm run check
+git status --short
+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；全程没有手工写入生产密钥。
+
+发布后验证：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`。
+
+## 回滚
+
+- tag 尚未推送：删除本地 tag，修复后重新检查。
+- tag 已推送但 workflow 未发布 npm：停止 workflow，修复后使用新的补丁版本；不要复用已公开 tag。
+- npm 已发布：npm 版本不可覆盖。立即在 GitHub/npm 标记受影响版本，必要时执行 `npm deprecate`，
+  修复后发布 `0.4.1`；代码回滚使用普通 revert commit，不改写 `main` 历史。

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`。

package/docs/USER-GUIDE.md

@@ -24,7 +24,20 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
 
 插件会加载内嵌 Skill `data-cleaning`，自动按 `data_profile → data_clean_rows → data_complete_rows` 工作流调度。
 
-### 2.2 web 界面
+### 2.2 应用内入口（侧边栏「数据清洗」）
+
+重启后，DeepSeek Harness 侧边栏底部会出现「数据清洗」按钮。点击打开全屏工作台，按四步操作：
+
+1. **上传与映射**：粘贴或上传 CSV / XLSX / JSON，确认企业名称字段；
+2. **数据体检**：查看列概览、缺失和金额分布；
+3. **匹配核验**：先做本地清洗，再选择风险/知产/经营域；多候选由人工确认；
+4. **补全与导出**：恢复任务、重试可重试失败，下载结果 CSV 和复核 CSV。
+
+模型在对话中调用 `data_clean_rows` / `data_complete_rows` / `data_profile` 时，
+对话内会渲染对应的工具结果卡片（含运行中 / 已完成 / 失败状态）；工作台头部用任务 pill
+实时展示排队 / 运行中的后台任务（轮询 `/data-cleaning/api/mvp/jobs`）。
+
+### 2.3 web 界面
 
 打开 DeepSeek Harness 后访问插件的同源界面（`/data-cleaning/`），可上传 CSV/XLSX/JSON，
 执行解析、清洗、补全、导出 CSV。web 界面的后端路由前缀为 `/data-cleaning/api/mvp/*`。
@@ -41,19 +54,80 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
 
 ### 3.2 企查查企业名单补全（Skill `enterprise-enrichment`）
 
+#### 账号与费用边界
+
+- 客户必须在自己的 DSH 环境中开通并连接自己的企查查 MCP 账号。
+- QCC 调用消耗客户自有账号的套餐额度，或按客户与企查查之间的合同计费。
+- 本插件及其开发者不提供共享 Key，不代客户购买、结算、垫付或补贴 QCC 调用费用。
+- 开发者 Key 只用于隔离测试环境，不写入代码、日志、夹具或 npm 发布包。
+- API 字段 `confirmPaidCalls` 为兼容性保留；它表示“当前用户确认使用自己的 QCC 账号额度”，
+  不表示插件开发者或维护者承担费用。
+
 先用企查查 MCP 连接插件（`qcc-dsh-mcp-oauth`）完成授权，然后对对话说：
 
-> 帮我补全这份企业名单：统一社会信用代码、法人、注册资本、成立日期、登记状态、风险标签。
+> 帮我补全这份企业名单：工商全景 + 股权穿透，不要历史工商。
 
 模型会按 `enterprise-enrichment` Skill 逐个企业调 `mcp__qcc-company__get_company_by_query`
-（消歧，多候选时停下询问）→ `get_company_registration_info`（工商详情）→
-`get_company_risk_scan`（风险标签），最后输出摘要 + Markdown 补全表。
+（消歧，多候选时停下询问）→ `get_company_registration_info`（工商详情），
+然后只调用请求的维度组：
+
+- `panorama`：企业画像、联系方式、开票、上市、财务；
+- `ownership`：实控人、受益所有人、股东和对外投资；
+- `governance`：分支机构、主要人员、变更记录和年报；
+- `history`：历史股东、法人、高管和登记信息（需企业认证账号）。
+
+如果请求没有明确维度，Skill 会先让用户选择，不默认调用全部付费工具。
+历史域无权时只标记 `permission_required`，当前工商组仍继续。对话默认返回统计摘要和小量预览；
+完整明细只在 Host 确实提供同源下载/产物能力时交付。
+开发者可在真实调用前 GET `/data-cleaning/api/phase2/capabilities`，只读检查 16+4 工具面；
+该预检不发起 QCC 或付费调用，也不会把「工具已注册」误报为「历史账号已授权」。
 
 **前置条件**：先连接企查查 MCP（未连接时 Skill 会引导执行 `qcc_oauth_connect`）。
 
 **本阶段边界**（方案 A，模型中介式）：
 - 不重造 OAuth；工具面来自 `qcc-dsh-mcp-oauth`。
-- 逐企业调用，适合中小名单（几十条以内）；百级以上大名单的批量补全见路线图（方案 B）。
+- 逐企业调用，适合中小名单（几十条以内）。
+- 金额、比例、计数保留 QCC 原值，不自算股权链、不将缺失值写成「无」或 0。
+- 0.4.0 已发布；20 企业、每企业至少 15 个当前维度并含 4 个历史维度的真实账号验收已通过。
+  access token 自然到期后的真实刷新、动态工具恢复以及限流/配额故障注入已在隔离环境验收。
+
+### 3.3 QCC 后台批量 Host Bridge（0.4.0 / G5-2）
+
+源码 `main` 已提供 `/data-cleaning/api/g5/capabilities`（只读能力探测）和
+`/data-cleaning/api/g5/enrich`（同源批量补全）基础层。它按企业名去重调用、只对唯一精确主体继续补全，
+多候选进入人工确认队列，模型不接触完整明细。
+
+这是 0.4.0 已发布能力：真实 OAuth、授权跨重启恢复、QCC 主调用路径、token 自然到期刷新
+与 401 / 429 / 配额故障注入均已完成隔离验收。
+调用批量端点必须由 UI 在用户确认后同时发送 `confirmPaidCalls:true` 和唯一 `idempotencyKey`；
+未确认或缺少幂等键时不会产生任何 QCC 调用。
+
+初次请求返回 `runId`：多候选进入 `awaiting-review`，只能通过 `/g5/resolve` 选择返回候选中的
+信用代码后续跑；retryable 失败只能由用户通过 `/g5/retry` 显式重试。run 仅在 Host 内存保留
+30 分钟，Host 重启后失效，不把原始企业行持久化落盘。
+
+### 3.4 三域批量补全（0.5.0 发布候选）
+
+0.5.0 在工作台中增加三个可选域：
+
+- **风险信息 · 38**：司法、执行、处罚、经营异常、税务、违约等；
+- **知识产权 · 18**：专利、商标、软著、数字资产、备案等；
+- **经营信息 · 35**：资质、招投标、融资、舆情、监管、进出口等。
+
+推荐流程：
+
+1. 上传数据并确认“企业名称字段”；
+2. 生成数据体检，执行本地清洗；
+3. 点击“检测企查查连接”，按需要勾选域；
+4. 点击“估算调用量”。估算为上界且不执行 QCC 工具；
+5. 只有在核对企业数、工具数、估算调用量和 `maxCalls` 后，才勾选“确认使用当前用户的企查查账号额度”；
+6. 多候选逐项人工选择；失败项只在明确点击重试时重放；
+7. 下载补全结果 CSV，必要时下载候选复核 CSV。
+
+同源 API 为 `/data-cleaning/api/phase3/*`。单批最多 100 行，并发上限 4，硬调用上限 2000；
+默认调用上限 500。`enrich` / `resolve` / `retry` 均要求 `confirmPaidCalls:true` 和唯一幂等键。
+当前维护者测试账号的真实三域计费 E2E 仍是发布门；与客户生产费用无关，详见
+[PHASE3-ACCEPTANCE.md](PHASE3-ACCEPTANCE.md)。
 
 ## 4. 数据边界
 
@@ -72,6 +146,11 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
 - **Q：安装后工具不出现？** A：确认已完全重启 DSH；确认 `dsh plugin list`（或 profile 的
   `package.json` → `dsh.profile.bundles`）含 `dsh-data-cleaning-agent`。
 - **Q：XLSX 解析报 `XLSX_UNAVAILABLE`？** A：当前 DSH 组合未安装 `xlsx`；web 组合默认可用。
-- **Q：能接企查查补全企业信息吗？** A：可以。先安装并连接 `qcc-dsh-mcp-oauth`，再说"帮我补全这份企业名单"，会自动走
+- **Q：能接企查查补全企业信息吗？** A：可以。先安装并连接 `qcc-dsh-mcp-oauth`；rc.2 隔离 Profile
+  需同时显式安装同版本 `@deepseek-ai/dsh-mcp-client`。再说"帮我补全这份企业名单"，会自动走
   `enterprise-enrichment` Skill（方案 A 模型中介式）。字段契约与二期规划见
   [QCC-ENRICHMENT-DESIGN.md](QCC-ENRICHMENT-DESIGN.md)。
+- **Q：可以在后台批量补全吗？** A：可以。0.4.0 G5 工商批量已发布并完成真实 OAuth/token 验收；
+  0.5.0 风险/知产/经营三域为发布候选，先用 estimate 核对调用上限，再显式确认付费调用。
+- **Q：刷新页面或重启后还能恢复吗？** A：同一 Host 进程内可用 `runId` 恢复，默认保留 30 分钟；
+  Host 重启后内存 run 失效，但已下载 CSV 和本地源文件不受影响。