dsh-data-cleaning-agent 0.8.12 → 0.8.14

package/CHANGELOG.md

@@ -4,6 +4,18 @@
 
 ## [Unreleased]
 
+## [0.8.14] - 2026-09-07
+
+### Changed
+- 质量体检后可直接生成可编辑任务说明，移除手动连接检测、手动调用估算和草稿阶段额度勾选。
+- Host 统一检查所选工具、去重主体及调用上界；中文草稿显示执行范围与账号提示。生成不查询，用户发送后才通过 Agent-owned 工具执行。
+- 候选确认与失败重试保留显式继续查询确认；执行时重新校验工具与范围，保留幂等及原列补空保护。
+
+## [0.8.13] - 2026-09-07
+
+### Added
+- 通过共享 `qcc-field-contracts` 接入实际控制人名称、直接持股比例、总持股比例、表决权比例；新增实控人别名搜索与原列补空。多名、分页和异常不自动选第一人，字段级原因随结果和异常清单导出。
+
 ## [0.8.12] - 2026-09-07
 
 ### Fixed

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.8.12** (stable release)
+> Current source version / 当前源码版本: **0.8.14** (stable release)
 
 This release fixes misleading import errors after a successful upload. Files are parsed automatically, with persistent source, filename, and row-count status; text parsing handles only newly pasted content. The same file can be selected again, failed parsing preserves existing data, and pending pasted content must be parsed or cleared before continuing. Automatic mapping for 128 fields, blank-cell enrichment in original columns, QCC-blue menus, the resizable workbench, and native DSH sending remain unchanged. Existing download artifacts are not rewritten.
 
@@ -110,8 +110,8 @@ Besides local deterministic completion, the plugin supports Qichacha MCP enterpr
   conversation. The Agent calls `data_cleaning_qcc_run` exactly once; the bridge then dispatches
   dynamic QCC tools as nested executions using the parent execution token and Session. This path
   supports batch enrichment, idempotency, candidate-resolution resume, manual retry of retryable
-  failures, and metadata-only auditing. Command staging requires `confirmPaidCalls:true`. The flag means the current user
-  confirms use of their own QCC account quota; it does not transfer the charge to the plugin maintainer.
+  failures, and metadata-only auditing. Since 0.8.14, initial draft staging automatically preflights tools and scope without a billing checkbox; only sending the readable draft starts queries.
+  Candidate resolution, retry and legacy direct-execution APIs still require `confirmPaidCalls:true` for the user's own QCC account quota.
   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.

package/README.md

@@ -2,7 +2,7 @@
 
 > 在 DeepSeek Harness 中清洗、补全、画像企业名单数据的智能体插件：本地 CSV/XLSX/JSON 引擎 + 可选企查查（Qichacha/QCC）MCP 企业数据补全，由企查查（Qichacha/QCC）团队发起并维护。
 >
-> 当前源码版本 / Current source version: **0.8.12**（正式版本）
+> 当前源码版本 / Current source version: **0.8.14**（正式版本）
 
 本版修复文件上传成功后的导入状态误报：文件选择后自动解析，当前来源、文件名和行数持续显示；文本解析仅处理新粘贴内容。支持重新选择同一文件，解析失败保留现有数据，新粘贴内容解析或清空后再进入下一步。保留 128 字段智能映射、原列补空、企查查蓝菜单、可调宽工作台及 DSH 原生发送机制。历史下载文件不自动改写。
 
@@ -102,8 +102,8 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
   Host，并只把不含企业名单的 commandId 类型化意图发送到原生会话；Agent 随后准确调用一次
   `data_cleaning_qcc_run`，Bridge 使用该父执行的 token/Session 以 nested execution 调度动态 QCC 工具。
   该路径实现批量补全、请求幂等、多候选人工确认续跑、retryable 失败人工重试与安全审计。
-  暂存命令前要求 `confirmPaidCalls:true`；该字段表示当前用户确认
-  使用自己的 QCC 账号额度，不代表插件开发者代客户付款；多候选绝不自动选择。
+  0.8.14 起初始草稿无需额度勾选：Host 自动检查工具与调用范围，用户阅读并发送说明后才查询。
+  候选确认、失败重试及旧版直接执行接口仍要求 `confirmPaidCalls:true`；使用用户自有账号额度，多候选绝不自动选择。
   默认关闭的本机 E2E Runner 已就绪；2026-09-01 已在隔离 rc.2 Host 完成真实 OAuth、跨重启恢复和
   20 家公开企业的 400 次 QCC 调用；自然过期 token 的真实刷新、动态工具恢复及 1 行续期后调用也已通过。
   401 / 429 / 配额耗尽使用 Web→Bridge→ToolRuntime 故障注入验证，不额外消耗真实付费批次。

package/docs/G5-HOST-BRIDGE.md

@@ -53,8 +53,9 @@
 
 ### Agent-owned 命令（正式工作台路径）
 
-- `POST /data-cleaning/api/g5/commands`：要求 `confirmPaidCalls:true`，把 enrich/resolve/retry 输入暂存
-  在 Host；返回 commandId 与不含企业名单的可见会话提示，本步骤 `paidCalls:false`。
+- `POST /data-cleaning/api/g5/commands`：0.8.14 起 enrich 暂存不要求额度勾选，Host 自动检查所选工具、行数和调用上界；
+  resolve/retry 暂存仍要求 `confirmPaidCalls:true`。返回 commandId、Host estimate 与不含企业名单的可编辑提示，本步骤 `paidCalls:false`。
+  生成说明不代表已执行，用户发送可见说明后才由 Agent-owned 工具执行。执行阶段重新检查工具和上限，草稿不伪造“已确认额度”状态。
 - `data_cleaning_qcc_run({commandId})`：只能在 Agent tool execution 内运行，缺少父执行 token/Session
   时返回 `QCC_AGENT_EXECUTION_REQUIRED`。
 - `GET /data-cleaning/api/g5/commands/<commandId>`：同源读取 prepared/running/completed/failed 和完成后的

package/lib/artifacts.js

@@ -21,6 +21,7 @@ const SYSTEM_FIELD_LABELS = Object.freeze({
   biz_status: '经营状态',
   risk_tags: '风险标签',
   qcc_match_status: '匹配状态',
+  qcc_field_issues: '字段补全待核验原因',
   qcc_source: '数据来源',
   qcc_error: '错误原因',
   match_status: '匹配状态',
@@ -115,6 +116,7 @@ function normalizeRows(value) {
 }
 
 function exceptionReason(row) {
+  if (row?.qcc_field_issues) return String(row.qcc_field_issues).slice(0, 2000);
   const status = String(
     row?.qcc_match_status
       ?? row?.match_status

package/lib/client.js

@@ -199,7 +199,7 @@ window.__ModuleLoader__.load({
       const needle = String(query || '').trim().toLowerCase();
       const [, label, fields, tool] = group;
       if (!needle || `${label} ${tool || ''}`.toLowerCase().includes(needle)) return fields;
-      return fields.filter(([id, fieldLabel]) => `${id} ${fieldLabel}`.toLowerCase().includes(needle));
+      return fields.filter(([id, fieldLabel]) => `${id} ${fieldLabel} ${(MAPPING_ALIASES[id] || []).join(' ')}`.toLowerCase().includes(needle));
     }
 
     /** 客户端所需服务：与 mcp-connector 对齐（槽位 + 会话/工作区/输入机）。 */
@@ -1139,6 +1139,13 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
       ['equity_freeze', '股权冻结'],
     ];
     const FIELD_GROUPS = [
+      // Shared contract mirror: checked against qcc-field-contracts in tests.
+      ['actual_controller', '实际控制人', [
+        ['actual_controller_name', '实际控制人名称'],
+        ['actual_controller_direct_ratio', '实控人直接持股比例'],
+        ['actual_controller_total_ratio', '实控人总持股比例'],
+        ['actual_controller_voting_ratio', '实控人表决权比例'],
+      ], 'get_actual_controller'],
       ['company_registration', '企业工商信息', [
         ['company_name', '企业名称'], ['credit_no', '统一社会信用代码'], ['reg_no', '注册号'],
         ['org_no', '组织机构代码'], ['tax_no', '纳税人识别号'], ['reg_status', '登记状态'],
@@ -1203,6 +1210,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
       ['risk_tags', '风险标签'],
       ['qcc_match_status', '匹配状态'],
       ['qcc_source', '数据来源'],
+      ['qcc_field_issues', '字段补全待核验原因'],
       ['qcc_error', '错误原因'],
       ['match_status', '匹配状态'],
       ['input_company', '原始企业名称'],
@@ -1434,6 +1442,10 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
     }
 
     const MAPPING_ALIASES = {
+      actual_controller_name: ['实控人', '实际控制人', '企业实控人名称', '企业实际控制人', '企业实控人名称（自然人请填写姓名）'],
+      actual_controller_direct_ratio: ['实际控制人直接持股比例'],
+      actual_controller_total_ratio: ['实际控制人总持股比例'],
+      actual_controller_voting_ratio: ['实际控制人表决权比例'],
       company_name: ['name', 'company', '公司名称', '单位名称', '企业全称', '公司全称', '主体标识'],
       credit_no: ['creditCode', 'unified_credit_code', '信用代码', '社会信用代码', '统一信用代码', 'USCC'],
       reg_no: ['registration_no', '工商注册号'],
@@ -3233,7 +3245,6 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
       const nameField = useStore((state) => state.nameField);
       const selectedDomains = useStore((state) => state.selectedDomains);
       const qccCapabilities = useStore((state) => state.qccCapabilities);
-      const qccEstimate = useStore((state) => state.qccEstimate);
       const qccRun = useStore((state) => state.qccRun);
       const paidConfirmed = useStore((state) => state.paidConfirmed);
       const jobs = useStore((state) => state.jobs);
@@ -3534,39 +3545,6 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
         }
       };
 
-      const loadQccCapabilities = async () => {
-        if (busy) return;
-        actions.setBusy(true);
-        actions.setError(null);
-        try {
-          const r = await api('/data-cleaning/api/g5/capabilities');
-          if (r && r.ok !== false) actions.setQccCapabilities(r);
-          else actions.setError((r && (r.message || r.error)) || '企查查能力检测失败');
-        } catch (err) {
-          actions.setError(err instanceof Error ? err.message : String(err));
-        } finally {
-          actions.setBusy(false);
-        }
-      };
-
-      const estimateQcc = async () => {
-        const uniqueCompanies = new Set(runtime.rows.map((row) => String(row?.[nameField] ?? '').trim()).filter(Boolean)).size;
-        const selected = fieldSelection.length ? fieldSelection : DEFAULT_ENRICHMENT_KEYS;
-        const selectedGroups = uiFieldGroups.filter(([, , fields]) => fields.some(([id]) => selected.includes(id)));
-        const sourceTools = [...new Set(selectedGroups.map(([, , , sourceTool]) => sourceTool).filter(Boolean))];
-        const callsPerCompany = 1 + sourceTools.length;
-        const estimatedCalls = uniqueCompanies * callsPerCompany;
-        actions.setQccEstimate({
-          uniqueCompanies,
-          tools: ['主体查询', ...selectedGroups.map(([, label]) => label)],
-          sourceTools,
-          estimatedCalls,
-          maxCalls: 300,
-          withinLimit: runtime.rows.length <= 100 && estimatedCalls <= 300,
-          estimateType: 'upper-bound',
-        });
-      };
-
       const applyQccRun = async (run) => {
         actions.setQccRun(run);
         runtime.rows = Array.isArray(run.rows) ? run.rows : runtime.rows;
@@ -3584,7 +3562,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
             qccRunId: run.runId,
             summary: {
               total: Number(summary.totalRows ?? runtime.rows.length),
-              exact: Number(summary.enriched ?? 0),
+              exact: Number(summary.enriched ?? 0) + Number(summary.fieldReview ?? 0),
               candidate: reviewRequired,
               confirmed: 0,
               unresolved: Number(summary.unresolved ?? summary.missingName ?? 0),
@@ -3605,7 +3583,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
             completed: Number(summary.enriched ?? 0),
             unchanged: Number(summary.unresolved ?? 0) + Number(summary.missingName ?? 0),
             failed: Number(summary.failed ?? 0),
-            reviewRequired: 0,
+            reviewRequired: Number(summary.fieldReview ?? 0),
             callsUsed: Array.isArray(run.audit) ? run.audit.length : 0,
           },
         });
@@ -3619,7 +3597,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
         }
         const prepared = await api('/data-cleaning/api/g5/commands', {
           ...payload,
-          confirmPaidCalls: true,
+          ...(payload.kind === 'enrich' ? {} : { confirmPaidCalls: true }),
         });
         const command = prepared?.command;
         if (!command?.commandId || !command?.prompt) throw new Error('Host 未返回有效的企查查任务命令');
@@ -3640,10 +3618,10 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
         }
         const prepared = await api('/data-cleaning/api/g5/commands', {
           ...payload,
-          confirmPaidCalls: true,
         });
         const command = prepared?.command;
         if (!command?.commandId || !command?.prompt) throw new Error('Host 未返回有效的企查查任务命令');
+        actions.setQccCapabilities({ capabilities: { ready: true } });
         setSessionDraft(activeSessionId, command.prompt);
         actions.close();
 
@@ -3668,7 +3646,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
       };
 
       const runQcc = async () => {
-        if (busy || !qccEstimate || !paidConfirmed || !qccEstimate.withinLimit) return;
+        if (busy || !cachedTask?.id || !hasData) return;
         actions.setBusy(true);
         actions.setError(null);
         try {
@@ -3904,7 +3882,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
         ? qccRun.summary?.enriched ?? 0
         : cachedTask?.enrichmentSummary?.completed;
       const qccReviewCount = qccRun
-        ? qccRun.summary?.ambiguous ?? 0
+        ? (qccRun.summary?.ambiguous ?? 0) + (qccRun.summary?.fieldReview ?? 0)
         : cachedTask?.enrichmentSummary?.reviewRequired
           ?? cachedTask?.matchSummary?.reviewRequired;
       const stat = (label, value, tone) => h('div', { className: 'dcAgentCard' },
@@ -4071,36 +4049,22 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
             h('p', { className: 'dcAgentHint' }, '统一社会信用代码等强标识优先；名称匹配不明确时进入人工核验队列。'),
           ),
           h('section', { className: 'dcAgentSection' },
-            h('h3', null, '企查查一企一行补全能力'),
+            h('h3', null, '准备任务说明'),
+            h('p', { className: 'dcAgentHint' }, `已导入 ${dataset?.rowCount ?? runtime.rows.length} 条记录，已选择 ${fieldSelection.length} 个补全字段。Host 自动检查所需工具并计算去重主体与调用上界。`),
+            h('p', { className: 'dcAgentHint' }, '回填后可修改；点击发送才开始查询，使用你已连接的企查查 MCP 账号及额度。'),
             h('div', { className: 'dcAgentRow' },
-              h('button', { type: 'button', className: 'dcAgentButton', disabled: busy, onClick: loadQccCapabilities }, busy ? '检测中…' : '检测企查查连接'),
-              qccCapabilities ? h('span', { className: 'dcAgentHint' }, qccCapabilities.capabilities?.ready ? '主体查询与工商信息工具已就绪' : '连接未就绪或基础工具不完整') : null,
+              h('button', { type: 'button', className: 'dcAgentButton is-primary', disabled: busy || !hasData || !cachedTask?.id, onClick: runQcc }, busy ? '检查并生成中…' : '生成可编辑任务说明'),
             ),
-            h('div', { className: 'dcAgentRow' },
-              h('button', { type: 'button', className: 'dcAgentButton', disabled: busy || !runtime.rows.length, onClick: estimateQcc }, '估算调用量'),
-            ),
-            qccEstimate ? h('div', null,
-              h('div', { className: 'dcAgentGrid' },
-                stat('唯一企业', qccEstimate.uniqueCompanies),
-                stat('所选工具', qccEstimate.tools.length),
-                stat('调用上界', qccEstimate.estimatedCalls, qccEstimate.withinLimit ? 'good' : 'bad'),
-                stat('调用上限', qccEstimate.maxCalls),
-              ),
-              h('label', { className: 'dcAgentCheck' },
-                h('input', { type: 'checkbox', checked: paidConfirmed, 'aria-label': '确认使用当前用户的企查查账号额度', onChange: (event) => actions.setPaidConfirmed(event.target.checked) }),
-                '我已核对企业数量和调用上界，并确认使用自己连接的企查查 MCP 账号；额度或费用由该账号自行承担',
-              ),
-              h('p', { className: 'dcAgentHint' }, '下一步只会把中文任务说明回填到中央对话框。你可先阅读、补充备注，点击发送后才开始企查查调用。'),
-              h('div', { className: 'dcAgentRow' },
-                h('button', { type: 'button', className: 'dcAgentButton is-primary', disabled: busy || !paidConfirmed || !qccEstimate.withinLimit, onClick: runQcc }, busy ? '生成中…' : '生成可编辑任务说明'),
-              ),
-            ) : null,
           ),
           qccRun ? h('section', { className: 'dcAgentSection' },
             h('h3', null, `任务 ${qccRun.runId} · ${qccRun.state}`),
+            ((qccRun.reviewQueue || []).length || (qccRun.errors || []).some((item) => item.error?.retryable)) ? h('label', { className: 'dcAgentCheck' },
+              h('input', { type: 'checkbox', checked: paidConfirmed, 'aria-label': '确认候选或重试的企查查调用', onChange: (event) => actions.setPaidConfirmed(event.target.checked) }),
+              '确认主体或重试会继续查询，使用当前连接的企查查账号；额度或费用由该账号自行承担。',
+            ) : null,
             h('div', { className: 'dcAgentGrid' },
               stat('已补全', qccRun.summary?.enriched ?? 0, 'good'),
-              stat('待核验', qccRun.summary?.ambiguous ?? 0, (qccRun.summary?.ambiguous ?? 0) > 0 ? 'warn' : null),
+              stat('待核验', (qccRun.summary?.ambiguous ?? 0) + (qccRun.summary?.fieldReview ?? 0), (qccRun.summary?.ambiguous || qccRun.summary?.fieldReview) > 0 ? 'warn' : null),
               stat('未匹配', qccRun.summary?.unresolved ?? 0, (qccRun.summary?.unresolved ?? 0) > 0 ? 'warn' : null),
               stat('失败', qccRun.summary?.failed ?? 0, (qccRun.summary?.failed ?? 0) > 0 ? 'bad' : null),
             ),
@@ -4230,7 +4194,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
             title: runtime.source?.type === 'image' ? '图片识别原始名单（尚未匹配）' : '导入原始清单',
             onError: actions.setError,
           }) : null,
-          hasData ? h('p', { className: 'dcAgentHint' }, '请核对完整名单。识别清单不代表已完成企查查匹配。核对后进入「规则与体检」，确认规则生成质量体检；再进入「主体匹配」估算调用量并确认账号额度，点击「生成可编辑任务说明」自动回填中央对话框，无需手工复制任务凭证。') : null,
+          hasData ? h('p', { className: 'dcAgentHint' }, '请核对完整名单。识别清单不代表已完成企查查匹配。核对后进入「规则与体检」，确认规则生成质量体检；再进入「主体匹配」直接生成可编辑任务说明。Host 自动检查工具和调用范围，回填中央对话框后点击发送才开始查询。') : null,
           h('div', { className: 'dcAgentRow' },
             h('button', { type: 'button', className: 'dcAgentButton is-primary', disabled: busy || !intake.pendingText, 'aria-label': '解析数据', onClick: handleParse }, busy ? '解析中…' : '解析粘贴内容'),
             intake.pendingText && hasData ? h('p', { className: 'dcAgentHint', role: 'status' }, '有尚未解析的新粘贴内容，请先解析或清空后再继续。') : null,
@@ -4279,7 +4243,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
               h('span', {
                 className: 'dcAgentQccBadge',
                 title: qccRun ? `任务 ${qccRun.runId}` : '仅在当前用户确认使用自己的企查查账号后调用',
-              }, qccRun ? `QCC · ${qccRun.state}` : qccCapabilities ? (qccCapabilities.capabilities?.ready ? 'QCC · 已连接' : 'QCC · 能力不完整') : 'QCC · 待检测'),
+              }, qccRun ? `QCC · ${qccRun.state}` : qccCapabilities ? (qccCapabilities.capabilities?.ready ? 'QCC · 工具已就绪' : 'QCC · 能力不完整') : 'QCC · 自动校验'),
               h('span', { className: 'dcAgentJobsPill', 'data-state': jobsPill(jobs).state, title: '后台任务状态' }, jobsPill(jobs).label),
               h('button', {
                 className: 'dcAgentWbClose',

package/lib/qcc-command.js

@@ -91,7 +91,8 @@ export function serializeQccCommandPrompt(command) {
     `任务编号：${command.taskId}。`,
     `处理数量：${rowCount} 条企业记录。`,
     ...(fields.length ? [`需要补全：${fields.join('、')}。`] : []),
-    '执行边界：名单、字段和额度确认已安全暂存在本机 Host；使用当前用户自己连接的企查查 MCP 账号。',
+    ...(command.estimate ? [`Host 调用估算：${command.estimate.uniqueCompanies} 家去重主体，最多 ${command.estimate.estimatedCalls} 次；本次调用上限 ${command.estimate.maxCalls} 次。`] : []),
+    '执行边界：名单与字段范围已安全暂存在本机 Host。生成说明不会查询；发送本说明即确认按上述范围使用自己连接的企查查 MCP 账号及额度，额度或费用由该账号自行承担。',
     '',
     '你可以在发送前补充任务备注。如需修改名单、匹配规则或补全字段，请先返回工作台调整后重新生成。',
     `安全任务凭证：${command.commandId}`,
@@ -128,6 +129,9 @@ export class QccCommandStore {
   prepare(input) {
     this.cleanup(true);
     const normalized = normalizedInput(input);
+    const estimate = normalized.kind === 'enrich'
+      ? this.bridge.previewEnrichment(normalized.rows, normalized)
+      : null;
     const commandId = `dcq-${randomUUID()}`;
     const at = new Date(this.clock()).toISOString();
     const record = {
@@ -139,6 +143,7 @@ export class QccCommandStore {
       updatedAt: at,
       touchedAtMs: this.clock(),
       input: normalized,
+      estimate,
       runId: null,
       error: null,
       promise: null,
@@ -165,6 +170,7 @@ export class QccCommandStore {
       updatedAt: record.updatedAt,
       runId: record.runId,
       error: record.error,
+      estimate: record.estimate,
       expiresInMs: this.ttlMs,
     });
   }
@@ -268,6 +274,7 @@ export function registerQccCommandTool(tools, commands) {
               totalRows: { type: 'integer' },
               uniqueCompanies: { type: 'integer' },
               enriched: { type: 'integer' },
+              fieldReview: { type: 'integer' },
               ambiguous: { type: 'integer' },
               unresolved: { type: 'integer' },
               failed: { type: 'integer' },

package/lib/qcc-field-catalog.js

@@ -5,6 +5,7 @@
  * 任何明细列表（电话全集、海关资质、风险关联方等）都不得进入本目录。
  */
 
+import { ACTUAL_CONTROLLER_GROUP } from 'qcc-field-contracts';
 const field = (id, label, options = {}) => Object.freeze({ id, label, ...options });
 const group = (id, label, sourceTool, fields, options = {}) => Object.freeze({
   id,
@@ -173,6 +174,7 @@ export const QCC_FIELD_CATALOG = Object.freeze([
     ...RELATED_RISK_FACTORS.map(([id, label]) => field(`related_risk_${id}_count`, `关联风险-${label}条目数`)),
     ...RELATED_RISK_KEY_FACTORS.map(([id, label]) => field(`related_risk_${id}_party_count`, `关联风险-${label}命中关联方数`)),
   ], { releaseBatch: 'batch-2', catalogVersion: RISK_FACTOR_CATALOG_VERSION }),
+  ACTUAL_CONTROLLER_GROUP,
 ]);
 
 export const QCC_FIELD_SOURCE_TOOL = Object.freeze(Object.fromEntries(

package/lib/qcc-runs.js

@@ -47,6 +47,7 @@ function deriveState(record) {
   if (record.reviewQueue.length > 0) return 'awaiting-review';
   if (record.errors.some((item) => item.error?.retryable)) return 'needs-retry';
   if (record.errors.length > 0) return 'completed-with-errors';
+  if (record.rows.some(row => row.qcc_field_issues)) return 'completed-with-errors';
   return 'completed';
 }
 
@@ -55,7 +56,8 @@ function recomputeSummary(record) {
   record.summary = {
     ...record.summary,
     totalRows: record.rows.length,
-    enriched: count('enriched'),
+    enriched: record.rows.filter(row => row.qcc_match_status === 'enriched' && !row.qcc_field_issues).length,
+    ...(record.summary.fieldReview !== undefined || record.rows.some(row => row.qcc_field_issues) ? { fieldReview: record.rows.filter(row => row.qcc_field_issues).length } : {}),
     ambiguous: count('ambiguous'),
     unresolved: count('unresolved'),
     failed: count('failed'),
@@ -231,6 +233,7 @@ export class G5RunStore {
           ...row,
           ...Object.fromEntries(Object.entries(result.fields || {}).filter(([key]) => row[key] == null || (typeof row[key] === 'string' && row[key].trim() === ''))),
           qcc_match_status: 'enriched',
+          ...(row.qcc_field_issues || result.fieldIssues ? { qcc_field_issues: Object.entries(result.fieldIssues || {}).map(([field, issue]) => field + ': ' + issue.message).join('；') } : {}),
           qcc_source: 'qcc-mcp',
         };
       } else {

package/lib/qcc.js

@@ -8,6 +8,7 @@
  * - 批量补全只在 Host/Web 内处理明细；模型仍只接收摘要。
  */
 import { safeAuditEvent } from './qcc-safety.js';
+import { projectActualController } from 'qcc-field-contracts';
 import {
   QCC_PHASE2_COMPANY_TOOLS,
   QCC_PHASE2_HISTORY_TOOLS,
@@ -32,6 +33,7 @@ export const QCC_TOOL_NAMES = Object.freeze({
   entityLookup: 'mcp__qcc-company__get_company_by_query',
   registration: 'mcp__qcc-company__get_company_registration_info',
   profile: 'mcp__qcc-company__get_company_profile',
+  actualController: 'mcp__qcc-company__get_actual_controller',
   contact: 'mcp__qcc-company__get_contact_info',
   listing: 'mcp__qcc-company__get_listing_info',
   taxInvoice: 'mcp__qcc-company__get_tax_invoice_info',
@@ -548,7 +550,15 @@ export function mapCompanyRelatedRiskScanFields(value) {
 const LEGACY_ENRICHMENT_FIELDS = Object.freeze([
   'credit_no', 'legal_rep', 'reg_capital', 'establish_date', 'reg_status',
 ]);
+export function mapActualControllerFields(value, match) {
+  if (value?.企业名称 && match?.companyName && value.企业名称 !== match.companyName) {
+    throw new QccBridgeError('QCC_ENTITY_MISMATCH', '实控人返回企业与已确认主体不一致');
+  }
+  const result=projectActualController(value);
+  return result.values;
+}
 const SOURCE_TOOL_CONFIG = Object.freeze({
+  get_actual_controller: Object.freeze({ name: QCC_TOOL_NAMES.actualController, map: mapActualControllerFields }),
   get_company_registration_info: Object.freeze({ name: QCC_TOOL_NAMES.registration, map: mapRegistrationFields }),
   get_company_profile: Object.freeze({ name: QCC_TOOL_NAMES.profile, map: mapProfileFields }),
   get_contact_info: Object.freeze({ name: QCC_TOOL_NAMES.contact, map: mapContactFields, args: { excludeInvalidPhone: false } }),
@@ -917,6 +927,7 @@ export class QccHostBridge {
     const lockedKey = String(match?.creditNo || match?.companyName || '').trim();
     const sourceTools = sourceToolsForFieldSelection(options.fieldSelection, options.includeRisk);
     let mapped = {};
+    const fieldIssues = {};
     let legacyRiskTags = '';
     for (const sourceTool of sourceTools) {
       const config = SOURCE_TOOL_CONFIG[sourceTool];
@@ -924,6 +935,10 @@ export class QccHostBridge {
       const response = await this.call(config.name, { searchKey: lockedKey, ...(config.args ?? {}) }, options);
       const fields = config.map(response.data, match);
       mapped = mergeMappedFields(mapped, fields);
+      if (sourceTool === 'get_actual_controller') {
+        Object.assign(fieldIssues, Object.fromEntries(Object.entries(projectActualController(response.data).issues)
+          .filter(([field]) => options.fieldSelection?.includes(field))));
+      }
       if (sourceTool === 'get_company_risk_scan') legacyRiskTags = mapRiskTags(response.data);
       if (config.inspect) {
         const catalog = config.inspect(response.data);
@@ -942,7 +957,8 @@ export class QccHostBridge {
     }
     const fields = projectSelectedFields(mapped, options.fieldSelection);
     if (options.includeRisk) fields.risk_tags = legacyRiskTags;
-    return { status: 'enriched', companyName: String(match?.companyName ?? ''), fields };
+    return { status: 'enriched', companyName: String(match?.companyName ?? ''), fields,
+      ...(Object.keys(fieldIssues).length ? { fieldIssues } : {}) };
   }
 
   async enrichLockedCompany(selection, options = {}) {
@@ -954,7 +970,7 @@ export class QccHostBridge {
     return this.enrichMatchedCompany({ companyName, creditNo }, options);
   }
 
-  async enrichRows(rows, options = {}) {
+  planEnrichment(rows, options = {}) {
     if (!Array.isArray(rows)) throw new QccBridgeError('QCC_INVALID_ROWS', 'rows must be an array');
     const maxRows = Math.max(1, Math.trunc(options.maxRows ?? DEFAULT_MAX_ROWS));
     if (rows.length > maxRows) {
@@ -984,6 +1000,21 @@ export class QccHostBridge {
         .map((sourceTool) => SOURCE_TOOL_CONFIG[sourceTool]?.name)
         .filter(Boolean),
     ];
+    return { normalized, names, estimate, maxRows, maxCalls, requiredTools };
+  }
+
+  previewEnrichment(rows, options = {}) {
+    const plan = this.planEnrichment(rows, options);
+    if (!plan.names.length) throw new QccBridgeError('QCC_INVALID_ROWS', '请先确认企业名称或统一社会信用代码的匹配映射。');
+    const missingTools = plan.requiredTools.filter((name) => !this.has(name));
+    if (missingTools.length) throw new QccBridgeError('QCC_NOT_CONNECTED', '企查查连接或所选字段工具未就绪，请在 MCP 连接器完成配置后重新生成任务说明。', {
+      connectRequired: true, retryable: true, details: { missingTools },
+    });
+    return { ...plan.estimate, rowCount: rows.length, maxRows: plan.maxRows, maxCalls: plan.maxCalls, withinLimit: true };
+  }
+
+  async enrichRows(rows, options = {}) {
+    const { normalized, names, estimate, requiredTools } = this.planEnrichment(rows, options);
     try {
       await Promise.all(requiredTools.map((name) => this.waitForTool(name, {
         signal: options.signal,
@@ -1030,6 +1061,7 @@ export class QccHostBridge {
           ...Object.fromEntries(Object.entries(result.fields || {}).filter(([key]) => row[key] == null || (typeof row[key] === 'string' && row[key].trim() === ''))),
           qcc_match_status: 'enriched',
           qcc_source: 'qcc-mcp',
+          ...(row.qcc_field_issues || result.fieldIssues ? { qcc_field_issues: Object.entries(result.fieldIssues || {}).map(([field, issue]) => field + ': ' + issue.message).join('；') } : {}),
         };
       }
       return { ...row, qcc_match_status: result?.status ?? 'failed' };
@@ -1046,7 +1078,8 @@ export class QccHostBridge {
     const summary = {
       totalRows: rows.length,
       uniqueCompanies: names.length,
-      enriched: outputRows.filter((row) => row.qcc_match_status === 'enriched').length,
+      enriched: outputRows.filter((row) => row.qcc_match_status === 'enriched' && !row.qcc_field_issues).length,
+      ...(outputRows.some(row => row.qcc_field_issues) ? { fieldReview: outputRows.filter(row => row.qcc_field_issues).length } : {}),
       ambiguous: outputRows.filter((row) => row.qcc_match_status === 'ambiguous').length,
       unresolved: outputRows.filter((row) => row.qcc_match_status === 'unresolved').length,
       failed: outputRows.filter((row) => row.qcc_match_status === 'failed').length,

package/lib/web.js

@@ -642,7 +642,7 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
           );
         }
         const payload = JSON.parse((await readBody(req)).toString('utf8'));
-        requirePaidConfirmation(payload);
+        if (payload.kind && payload.kind !== 'enrich') requirePaidConfirmation(payload);
         return writeJson(res, 201, {
           ok: true,
           marker: 'g5-agent-command',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-data-cleaning-agent",
-  "version": "0.8.12",
+  "version": "0.8.14",
   "description": "Clean, complete, and profile enterprise name lists in DeepSeek Harness — a data cleaning & completion agent plugin with local CSV/XLSX/JSON engine and optional Qichacha (QCC) MCP enrichment. Maintained by Qichacha/QCC.",
   "type": "module",
   "main": "lib/index.js",
@@ -99,6 +99,7 @@
     "node": ">=20"
   },
   "dependencies": {
+    "qcc-field-contracts": "0.1.0",
     "xlsx": "^0.18.5"
   },
   "peerDependencies": {