dsh-data-cleaning-agent 0.3.0 → 0.4.0

package/docs/QCC-PHASES-ROADMAP.md

@@ -30,7 +30,7 @@
 | --- | --- | --- | --- | --- |
 | 一期 | 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.5.0 | 方案 A 扩展 Skill：风险/知产/经营 + 方案 B 批量后端 | 风险 38 + 知产 18 + 经营 35 | 同上；S7 PASS，G5-2 安全闭环已落地 |
 | 四期（可选） | 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,14 @@ 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 配额错误在派发前阻断。
 
 ---
 

package/docs/RELEASE-0.4.0.md

@@ -0,0 +1,57 @@
+# 0.4.0 发布候选检查单
+
+- 源码版本：`0.4.0`
+- 状态：发布候选，尚未创建 `v0.4.0` tag、GitHub Release 或 npm 发布
+- 基线日期：2026-09-02
+
+## 已纳入范围
+
+- `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 已完成；剩余只是创建/推送 tag 所触发的正式发布操作，
+不再有 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。不要手工写入生产密钥。
+
+## 回滚
+
+- tag 尚未推送：删除本地 tag，修复后重新检查。
+- tag 已推送但 workflow 未发布 npm：停止 workflow，修复后使用新的补丁版本；不要复用已公开 tag。
+- npm 已发布：npm 版本不可覆盖。立即在 GitHub/npm 标记受影响版本，必要时执行 `npm deprecate`，
+  修复后发布 `0.4.1`；代码回滚使用普通 revert commit，不改写 `main` 历史。

package/docs/USER-GUIDE.md

@@ -43,17 +43,46 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
 
 先用企查查 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 / 配额故障注入均已完成隔离验收；正式可用版本仍以 npm/GitHub Release 为准。
+调用批量端点必须由 UI 在用户确认后同时发送 `confirmPaidCalls:true` 和唯一 `idempotencyKey`；
+未确认或缺少幂等键时不会产生任何 QCC 调用。
+
+初次请求返回 `runId`：多候选进入 `awaiting-review`，只能通过 `/g5/resolve` 选择返回候选中的
+信用代码后续跑；retryable 失败只能由用户通过 `/g5/retry` 显式重试。run 仅在 Host 内存保留
+30 分钟，Host 重启后失效，不把原始企业行持久化落盘。
 
 ## 4. 数据边界
 
@@ -72,6 +101,9 @@ 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：`main` 已有 G5-2 Host Bridge 安全闭环，真实 OAuth/QCC 主路径已验收但尚未发布；
+  生产使用前仍需通过 `docs/G5-HOST-BRIDGE.md` 的 token 到期刷新与计费错误门。

package/lib/index.js

@@ -6,6 +6,7 @@
  *  2. ctx.skills —— 注册内嵌 Skill `data-cleaning`（正文指引模型调上述工具）
  *  3. webServer/webRuntime —— 挂载上传/解析/同步清洗补全/异步任务/UI 路由
  *  4. ctx.jobs + ctx.storageDomain —— 异步任务状态机（web 组合内可用）
+ *  5. ctx.tools.execute —— G5 QCC Host Bridge（程序化批量补全，web 组合内可用）
  *
  * headless 组合无 webServer/webRuntime：用 ctx.get() 存在性守卫跳过 web 半区，
  * 工具与 Skill 照常注册（端到端真实模型路径依赖它们）。
@@ -26,6 +27,7 @@ export function apply(ctx, config) {
     skillRegistered: false,
     webMounted: false,
     webSkipped: false,
+    qccBridgeMounted: false,
   };
   const disposers = [];
 

package/lib/qcc-phase2-acceptance.js

@@ -0,0 +1,191 @@
+import { isDeepStrictEqual } from 'node:util';
+import {
+  QCC_PHASE2_COMPANY_TOOLS,
+  QCC_PHASE2_HISTORY_TOOLS,
+  qccToolRuntimeCandidates,
+} from './qcc-phase2.js';
+
+export const QCC_PHASE2_ACCEPTANCE_SCHEMA_VERSION = 1;
+export const QCC_PHASE2_EVIDENCE_KIND = 'qcc-phase2-real-tool-transcript';
+export const QCC_PHASE2_ACCEPTANCE_FLOORS = Object.freeze({
+  minimumRecords: 20,
+  minimumCurrentDimensions: 15,
+  requiredHistoryDimensions: Object.keys(QCC_PHASE2_HISTORY_TOOLS).length,
+});
+
+const CURRENT_TOOLS = new Map(Object.entries(QCC_PHASE2_COMPANY_TOOLS));
+const HISTORY_TOOLS = new Map(Object.entries(QCC_PHASE2_HISTORY_TOOLS));
+const DELIVERED_STATUSES = new Set(['resolved', 'no_data']);
+const ALLOWED_STATUSES = new Set([
+  ...DELIVERED_STATUSES,
+  'permission_required',
+  'not_available',
+  'error',
+]);
+const OPAQUE_REFERENCE = /^row-[0-9]{3,6}$/;
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function hasMeaningfulValue(value) {
+  if (value === null || value === undefined) return false;
+  if (typeof value === 'string') return value.trim().length > 0;
+  if (Array.isArray(value)) return value.length > 0;
+  if (typeof value === 'object') return Object.keys(value).length > 0;
+  return true;
+}
+
+function evaluateField(field) {
+  if (!field || typeof field !== 'object' || Array.isArray(field)) return false;
+  if (typeof field.key !== 'string' || field.key.length === 0) return false;
+  if (!hasOwn(field, 'value') || !hasOwn(field, 'sourceValue')) return false;
+  if (!hasMeaningfulValue(field.value) || !hasMeaningfulValue(field.sourceValue)) return false;
+  return isDeepStrictEqual(field.value, field.sourceValue);
+}
+
+function evaluateDimension(dimension, knownTools) {
+  const failures = [];
+  if (!dimension || typeof dimension !== 'object' || Array.isArray(dimension)) {
+    return { id: null, delivered: false, failures: ['DIMENSION_INVALID'] };
+  }
+  const id = typeof dimension.id === 'string' ? dimension.id : null;
+  const expectedTool = id ? knownTools.get(id) : null;
+  if (!expectedTool) failures.push('DIMENSION_UNKNOWN');
+  if (!qccToolRuntimeCandidates(expectedTool ?? '').includes(dimension.sourceTool)) {
+    failures.push('SOURCE_TOOL_MISMATCH');
+  }
+  if (!ALLOWED_STATUSES.has(dimension.status)) failures.push('DIMENSION_STATUS_INVALID');
+
+  const fieldsAreArray = Array.isArray(dimension.fields);
+  const fields = fieldsAreArray ? dimension.fields : [];
+  if (!fieldsAreArray) failures.push('FIELDS_ARRAY_REQUIRED');
+  if (dimension.status === 'resolved') {
+    if (fields.length === 0) failures.push('RESOLVED_FIELDS_REQUIRED');
+    if (!fields.every(evaluateField)) failures.push('VALUE_NOT_VERBATIM');
+  }
+  if (dimension.status === 'no_data' && fields.length > 0) {
+    failures.push('NO_DATA_MUST_NOT_CARRY_VALUES');
+  }
+
+  return {
+    id,
+    delivered: failures.length === 0 && DELIVERED_STATUSES.has(dimension.status),
+    failures,
+  };
+}
+
+function evaluateRecord(record, index, { requireHistory }) {
+  const safeReference = OPAQUE_REFERENCE.test(record?.reference ?? '')
+    ? record.reference
+    : `row-${String(index + 1).padStart(3, '0')}`;
+  const failures = [];
+  if (!OPAQUE_REFERENCE.test(record?.reference ?? '')) failures.push('REFERENCE_NOT_OPAQUE');
+  if (record?.entityStatus !== 'resolved') failures.push('ENTITY_NOT_RESOLVED');
+
+  const dimensions = Array.isArray(record?.dimensions) ? record.dimensions : [];
+  if (!Array.isArray(record?.dimensions)) failures.push('DIMENSIONS_REQUIRED');
+
+  const seen = new Set();
+  const deliveredStatuses = new Map();
+  let currentDelivered = 0;
+  let historyDelivered = 0;
+  for (const dimension of dimensions) {
+    const domain = dimension?.domain;
+    const tools = domain === 'history' ? HISTORY_TOOLS : domain === 'company' ? CURRENT_TOOLS : null;
+    if (!tools) {
+      failures.push('DIMENSION_DOMAIN_INVALID');
+      continue;
+    }
+    const uniqueKey = `${domain}:${dimension?.id ?? ''}`;
+    if (seen.has(uniqueKey)) {
+      failures.push('DIMENSION_DUPLICATE');
+      continue;
+    }
+    seen.add(uniqueKey);
+    const result = evaluateDimension(dimension, tools);
+    failures.push(...result.failures);
+    if (result.delivered) deliveredStatuses.set(uniqueKey, dimension.status);
+    if (result.delivered && domain === 'company') currentDelivered += 1;
+    if (result.delivered && domain === 'history') historyDelivered += 1;
+  }
+
+  if (
+    deliveredStatuses.get('company:resolveEntity') !== 'resolved'
+    || deliveredStatuses.get('company:registration') !== 'resolved'
+  ) {
+    failures.push('IDENTITY_EVIDENCE_REQUIRED');
+  }
+  if (currentDelivered < QCC_PHASE2_ACCEPTANCE_FLOORS.minimumCurrentDimensions) {
+    failures.push('CURRENT_DIMENSION_FLOOR_NOT_MET');
+  }
+  if (requireHistory && historyDelivered < QCC_PHASE2_ACCEPTANCE_FLOORS.requiredHistoryDimensions) {
+    failures.push('HISTORY_DIMENSION_FLOOR_NOT_MET');
+  }
+
+  return {
+    reference: safeReference,
+    passed: failures.length === 0,
+    currentDelivered,
+    historyDelivered,
+    failures: [...new Set(failures)].sort(),
+    entityStatus: ['resolved', 'ambiguous', 'unresolved'].includes(record?.entityStatus)
+      ? record.entityStatus
+      : 'invalid',
+  };
+}
+
+/**
+ * 评估 0.4.0 真实 E2E 证据。返回值严格不携带企业名、信用代码或字段值。
+ */
+export function evaluateQccPhase2Evidence(evidence, { requireHistory = false } = {}) {
+  const globalFailures = [];
+  if (!evidence || typeof evidence !== 'object' || Array.isArray(evidence)) {
+    globalFailures.push('EVIDENCE_INVALID');
+  }
+  if (evidence?.schemaVersion !== QCC_PHASE2_ACCEPTANCE_SCHEMA_VERSION) {
+    globalFailures.push('SCHEMA_VERSION_UNSUPPORTED');
+  }
+  if (evidence?.evidenceKind !== QCC_PHASE2_EVIDENCE_KIND) {
+    globalFailures.push('EVIDENCE_KIND_UNVERIFIED');
+  }
+  // 真实 E2E 证据必须显式声明 synthetic:false；缺省值也按未验证处理，保持 fail-closed。
+  if (evidence?.synthetic !== false) globalFailures.push('SYNTHETIC_EVIDENCE_REJECTED');
+  if (!Array.isArray(evidence?.records)) globalFailures.push('RECORDS_REQUIRED');
+  const records = Array.isArray(evidence?.records) ? evidence.records : [];
+  if (records.length < QCC_PHASE2_ACCEPTANCE_FLOORS.minimumRecords) {
+    globalFailures.push('RECORD_FLOOR_NOT_MET');
+  }
+  if (requireHistory && evidence?.historyAccess !== 'enterprise-certified') {
+    globalFailures.push('ENTERPRISE_HISTORY_ACCESS_NOT_VERIFIED');
+  }
+
+  const recordReports = records.map((record, index) => evaluateRecord(record, index, { requireHistory }));
+  const references = recordReports.map((record) => record.reference);
+  if (new Set(references).size !== references.length) globalFailures.push('REFERENCE_DUPLICATE');
+
+  const failedRecords = recordReports.filter((record) => !record.passed);
+  const summary = {
+    recordCount: recordReports.length,
+    passedRecords: recordReports.length - failedRecords.length,
+    failedRecords: failedRecords.length,
+    ambiguousRecords: recordReports.filter((record) => record.entityStatus === 'ambiguous').length,
+    unresolvedRecords: recordReports.filter((record) => record.entityStatus === 'unresolved').length,
+    minimumCurrentDimensions: recordReports.length === 0
+      ? 0
+      : Math.min(...recordReports.map((record) => record.currentDelivered)),
+    minimumHistoryDimensions: recordReports.length === 0
+      ? 0
+      : Math.min(...recordReports.map((record) => record.historyDelivered)),
+  };
+
+  return {
+    schemaVersion: QCC_PHASE2_ACCEPTANCE_SCHEMA_VERSION,
+    passed: globalFailures.length === 0 && failedRecords.length === 0,
+    requireHistory,
+    floors: QCC_PHASE2_ACCEPTANCE_FLOORS,
+    summary,
+    globalFailures: [...new Set(globalFailures)].sort(),
+    failures: failedRecords.map(({ reference, failures }) => ({ reference, codes: failures })),
+  };
+}

package/lib/qcc-phase2.js

@@ -0,0 +1,99 @@
+/**
+ * QCC 0.4.0 二期工具契约。
+ *
+ * 这里只固化已经在本地 QCC MCP 一手源码注册表中核对过的工具名。
+ * 不固化上游响应字段：方案 A 由模型中介解读工具返回，并必须保留原值。
+ */
+
+const companyTool = (name) => `mcp__qcc-company__${name}`;
+const historyTool = (name) => `mcp__qcc-history__${name}`;
+
+/**
+ * qcc-dsh-mcp-oauth 0.1.7 把 serverKey 直接作为 serverName，因而注册为
+ * `mcp__company__*` / `mcp__history__*`；修复版与手工配置使用文档约定的
+ * `mcp__qcc-company__*` / `mcp__qcc-history__*`。Bridge 同时兼容两者，
+ * 但始终把带 qcc- 前缀的名称作为规范契约。
+ */
+export function qccToolRuntimeCandidates(canonicalName) {
+  const name = String(canonicalName ?? '');
+  const legacy = name.replace(/^mcp__qcc-(company|risk|ipr|operation|history|executive)__/, 'mcp__$1__');
+  return legacy === name ? Object.freeze([name]) : Object.freeze([name, legacy]);
+}
+
+export const QCC_PHASE2_COMPANY_TOOLS = Object.freeze({
+  resolveEntity: companyTool('get_company_by_query'),
+  registration: companyTool('get_company_registration_info'),
+  profile: companyTool('get_company_profile'),
+  verifyIdentity: companyTool('verify_company_accuracy'),
+  actualController: companyTool('get_actual_controller'),
+  beneficialOwners: companyTool('get_beneficial_owners'),
+  shareholders: companyTool('get_shareholder_info'),
+  externalInvestments: companyTool('get_external_investments'),
+  branches: companyTool('get_branches'),
+  keyPersonnel: companyTool('get_key_personnel'),
+  changes: companyTool('get_change_records'),
+  annualReports: companyTool('get_annual_reports'),
+  contact: companyTool('get_contact_info'),
+  taxInvoice: companyTool('get_tax_invoice_info'),
+  listing: companyTool('get_listing_info'),
+  financial: companyTool('get_financial_data'),
+});
+
+export const QCC_PHASE2_HISTORY_TOOLS = Object.freeze({
+  shareholders: historyTool('get_historical_shareholders'),
+  legalRepresentative: historyTool('get_historical_legal_rep'),
+  executives: historyTool('get_historical_executives'),
+  registration: historyTool('get_historical_registration'),
+});
+
+/**
+ * 用户可选的维度组。identity 是任何任务的必需步骤；其余组按用户意图调用。
+ * 字段缺失、无权或上游不可用时，应保留状态而不是补造值。
+ */
+export const QCC_PHASE2_DIMENSION_GROUPS = Object.freeze({
+  identity: Object.freeze({
+    label: '主体锚定与核验',
+    access: 'basic',
+    tools: Object.freeze([
+      QCC_PHASE2_COMPANY_TOOLS.resolveEntity,
+      QCC_PHASE2_COMPANY_TOOLS.registration,
+      QCC_PHASE2_COMPANY_TOOLS.verifyIdentity,
+    ]),
+  }),
+  panorama: Object.freeze({
+    label: '企业全景',
+    access: 'basic',
+    tools: Object.freeze([
+      QCC_PHASE2_COMPANY_TOOLS.profile,
+      QCC_PHASE2_COMPANY_TOOLS.contact,
+      QCC_PHASE2_COMPANY_TOOLS.taxInvoice,
+      QCC_PHASE2_COMPANY_TOOLS.listing,
+      QCC_PHASE2_COMPANY_TOOLS.financial,
+    ]),
+  }),
+  ownership: Object.freeze({
+    label: '股权穿透',
+    access: 'basic',
+    tools: Object.freeze([
+      QCC_PHASE2_COMPANY_TOOLS.actualController,
+      QCC_PHASE2_COMPANY_TOOLS.beneficialOwners,
+      QCC_PHASE2_COMPANY_TOOLS.shareholders,
+      QCC_PHASE2_COMPANY_TOOLS.externalInvestments,
+    ]),
+  }),
+  governance: Object.freeze({
+    label: '组织与沿革',
+    access: 'basic',
+    tools: Object.freeze([
+      QCC_PHASE2_COMPANY_TOOLS.branches,
+      QCC_PHASE2_COMPANY_TOOLS.keyPersonnel,
+      QCC_PHASE2_COMPANY_TOOLS.changes,
+      QCC_PHASE2_COMPANY_TOOLS.annualReports,
+    ]),
+  }),
+  history: Object.freeze({
+    label: '历史工商',
+    access: 'enterprise-certified',
+    tools: Object.freeze(Object.values(QCC_PHASE2_HISTORY_TOOLS)),
+  }),
+});