dsh-data-cleaning-agent 0.8.12 → 0.8.13

package/CHANGELOG.md

@@ -4,6 +4,11 @@
 
 ## [Unreleased]
 
+## [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.13** (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.
 

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.13**（正式版本）
 
 本版修复文件上传成功后的导入状态误报：文件选择后自动解析，当前来源、文件名和行数持续显示；文本解析仅处理新粘贴内容。支持重新选择同一文件，解析失败保留现有数据，新粘贴内容解析或清空后再进入下一步。保留 128 字段智能映射、原列补空、企查查蓝菜单、可调宽工作台及 DSH 原生发送机制。历史下载文件不自动改写。
 

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', '工商注册号'],
@@ -3584,7 +3596,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 +3617,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,
           },
         });
@@ -3904,7 +3916,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' },
@@ -4100,7 +4112,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
             h('h3', null, `任务 ${qccRun.runId} · ${qccRun.state}`),
             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),
             ),

package/lib/qcc-command.js

@@ -268,6 +268,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 = {}) {
@@ -1030,6 +1046,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 +1063,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-data-cleaning-agent",
-  "version": "0.8.12",
+  "version": "0.8.13",
   "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": {