dsh-data-cleaning-agent 0.8.11 → 0.8.13

package/CHANGELOG.md

@@ -4,6 +4,17 @@
 
 ## [Unreleased]
 
+## [0.8.13] - 2026-09-07
+
+### Added
+- 通过共享 `qcc-field-contracts` 接入实际控制人名称、直接持股比例、总持股比例、表决权比例；新增实控人别名搜索与原列补空。多名、分页和异常不自动选第一人，字段级原因随结果和异常清单导出。
+
+## [0.8.12] - 2026-09-07
+
+### Fixed
+- 导入页以已解析数据集显示当前来源、文件名与行数，不再依赖可能重建的原生文件选择框。文件选择后自动解析；文本按钮仅处理新粘贴内容，避免成功上传后误报「请粘贴或上传数据」。
+- 支持重新选择同一文件，失败替换保留现有数据；新粘贴内容需先解析或清空，避免带着未生效输入进入下一步。仅有历史摘要而无明细时明确要求重新导入。
+
 ## [0.8.11] - 2026-09-07
 
 ### Fixed

package/README.en.md

@@ -2,9 +2,9 @@
 
 > 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.11** (stable release)
+> Current source version / 当前源码版本: **0.8.13** (stable release)
 
-This release adds automatic mapping for all 128 fields using standard labels, field keys, and explicit aliases, with searchable grouped choices and confirmation for ambiguous or duplicate columns. Enrichment fills empty cells in mapped original columns and preserves nonempty values; selected fields without a mapped column are appended. Duplicate CSV/XLSX headers retain independent values. Preview and exports follow the same rules. QCC-blue menus, resizable workbench, and native DSH input/send behavior remain unchanged. Existing download artifacts are not rewritten.
+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.
 
 [![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)

package/README.md

@@ -2,9 +2,9 @@
 
 > 在 DeepSeek Harness 中清洗、补全、画像企业名单数据的智能体插件：本地 CSV/XLSX/JSON 引擎 + 可选企查查（Qichacha/QCC）MCP 企业数据补全，由企查查（Qichacha/QCC）团队发起并维护。
 >
-> 当前源码版本 / Current source version: **0.8.11**（正式版本）
+> 当前源码版本 / Current source version: **0.8.13**（正式版本）
 
-本版为全部 128 个字段加入标准名、英文键及明确别名自动映射，多义表头和重复列提供可确认推荐与分组搜索。补全结果优先写入已映射原列的空白单元格，保留非空原值；无对应原列的已选字段才新增列。CSV/XLSX 重复表头独立保留，预览与导出规则一致。保留企查查蓝菜单、可调宽工作台及 DSH 原生输入和发送机制。历史下载文件不自动改写。
+本版修复文件上传成功后的导入状态误报：文件选择后自动解析，当前来源、文件名和行数持续显示；文本解析仅处理新粘贴内容。支持重新选择同一文件，解析失败保留现有数据，新粘贴内容解析或清空后再进入下一步。保留 128 字段智能映射、原列补空、企查查蓝菜单、可调宽工作台及 DSH 原生发送机制。历史下载文件不自动改写。
 
 [![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)

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', '工商注册号'],
@@ -3054,6 +3066,17 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
     }
 
     /** 文本/JSON 直通 parse（与 web.js 内联页同构，含 JSON 数组直通）。 */
+    function intakeState(dataset, sourceRows, input, source) {
+      const count = Number(dataset?.rowCount || 0);
+      const available = count > 0 && Array.isArray(sourceRows) && sourceRows.length === count;
+      return {
+        available,
+        pendingText: Boolean(String(input ?? '').trim()),
+        fileName: source?.fileName || (source?.type === 'image' ? '图片识别名单' : '粘贴 / 向导导入名单'),
+        count,
+      };
+    }
+
     async function parseText(text, actions) {
       const trimmed = (text ?? '').trim();
       if (!trimmed) {
@@ -3361,6 +3384,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
       const runtime = runtimeFor(runtimeKey);
       const stagedSource = runtimeFor(`session:${activeSessionId || 'unassigned'}`, false);
       const sourceRows = stagedSource?.sourceRows ?? runtime.sourceRows ?? runtime.rows;
+      const intake = intakeState(dataset, sourceRows, input, runtime.source || stagedSource?.source || cachedTask?.source);
       const lastCsv = runtime.lastCsv;
       const fieldByPattern = (pattern) => runtime.headers.find((field) => pattern.test(field)) ?? null;
       const phoneField = fieldByPattern(/^(phone|mobile|tel|telephone|联系电话|手机号码|手机号)$/i);
@@ -3380,13 +3404,20 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
 
       const handleParse = async () => {
         if (busy) return;
+        if (!intake.pendingText) {
+          if (intake.available) actions.setError(null);
+          return;
+        }
         actions.setBusy(true);
         actions.setError(null);
         try {
           const result = await parseText(input, actions);
-          if (result) {
+          if (result && result.ok !== false) {
             applyParsed(result, actions, runtimeKey, { type: result.fmt || 'csv' });
             await persistParsedWorkflow(actions, activeSessionId, result, { type: result.fmt || 'csv' }, cachedTask);
+            actions.setInput('');
+          } else if (result) {
+            actions.setError(result.message || result.error || '解析失败，已导入的数据保持不变。');
           }
         } catch (err) {
           actions.setError(err instanceof Error ? err.message : String(err));
@@ -3404,6 +3435,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
         return true;
       };
       const handleFile = async (event) => {
+        if (busy) return;
         const file = event.target && event.target.files && event.target.files[0];
         if (!file) return;
         if (String(file.type ?? '').startsWith('image/')) {
@@ -3418,11 +3450,13 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
           if (result && result.ok !== false) {
             applyParsed(result, actions, runtimeKey, { type: result.fmt || 'csv', fileName: file.name, sizeBytes: file.size || 0 });
             await persistParsedWorkflow(actions, activeSessionId, result, { type: result.fmt || 'csv', fileName: file.name, sizeBytes: file.size || 0 }, cachedTask);
+            actions.setInput('');
           }
           else actions.setError((result && (result.message || result.error)) || '解析失败');
         } catch (err) {
           actions.setError(err instanceof Error ? err.message : String(err));
         } finally {
+          event.target.value = '';
           actions.setBusy(false);
         }
       };
@@ -3562,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),
@@ -3583,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,
           },
         });
@@ -3882,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' },
@@ -4078,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),
             ),
@@ -4159,13 +4193,26 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
       } else {
         pane = h('div', { className: 'dcAgentPane' },
           h('p', { className: 'dcAgentHint' }, '上传 CSV / XLSX / XLS / JSON，或粘贴数据。也可选择图片，通过企查查智能文档解析提取名单后继续清洗补全。'),
-          h('input', {
+          dataset ? h('section', { className: 'dcAgentSection', 'aria-label': '当前导入数据', role: 'status' },
+            h('h3', null, intake.available ? `已解析 ${intake.count} 条数据` : '已保存导入摘要'),
+            h('p', { className: 'dcAgentHint', style: { overflowWrap: 'anywhere' } }, `当前来源：${intake.fileName}`),
+            h('p', { className: 'dcAgentHint' }, intake.available
+              ? '文件选择后已自动解析，无需再次点击解析。核对下方名单后可直接进入规则与体检；重新选择文件会替换当前导入数据。'
+              : '当前页面没有完整原始数据。请重新导入原文件；历史下载制品仍可从任务历史获取。'),
+          ) : null,
+          h('div', { className: 'dcAgentRow' },
+            h('button', { type: 'button', className: 'dcAgentButton', disabled: busy,
+              onClick: (event) => event.currentTarget.nextElementSibling?.click() },
+            dataset ? '重新选择文件（自动解析）' : '选择文件（自动解析）'),
+            h('input', {
             type: 'file',
             accept: '.csv,.json,.xlsx,.xls,image/png,image/jpeg,image/webp',
             className: 'dcAgentField',
+            style: { display: 'none' },
+            disabled: busy,
             'aria-label': '选择数据文件',
             onChange: handleFile,
-          }),
+          })),
           h('button', { type: 'button', className: 'dcAgentButton', disabled: busy,
             onClick: () => openImageIntake() }, '图片识别（粘贴 / 选择）'),
           h('textarea', {
@@ -4173,6 +4220,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
             placeholder: '粘贴 CSV 文本，或 JSON 数组（例如 [{"name":"某公司","amount":"100"}]）…',
             'aria-label': '粘贴数据',
             value: input,
+            disabled: busy,
             onPaste: (event) => {
               const files = imageFilesFromTransfer(event.clipboardData);
               if (files.length && openImageIntake(files[0])) {
@@ -4180,7 +4228,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
                 event.stopPropagation?.();
               }
             },
-            onInput: (event) => actions.setInput(event.target.value),
+            onInput: (event) => { actions.setInput(event.target.value); actions.setError(null); },
           }),
           dataset ? h('div', { className: 'dcAgentChips' },
             h('span', { className: 'dcAgentChip' }, `格式 ${dataset.fmt}`),
@@ -4196,8 +4244,9 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
           }) : null,
           hasData ? h('p', { className: 'dcAgentHint' }, '请核对完整名单。识别清单不代表已完成企查查匹配。核对后进入「规则与体检」，确认规则生成质量体检；再进入「主体匹配」估算调用量并确认账号额度，点击「生成可编辑任务说明」自动回填中央对话框，无需手工复制任务凭证。') : null,
           h('div', { className: 'dcAgentRow' },
-            h('button', { type: 'button', className: 'dcAgentButton is-primary', disabled: busy, 'aria-label': '解析数据', onClick: handleParse }, busy ? '解析中…' : '解析数据'),
-            hasData ? h('button', { type: 'button', className: 'dcAgentButton', disabled: busy || sourceRows.length !== dataset.rowCount, onClick: () => actions.setStep('rules') }, '已核对清单，下一步：字段映射与规则') : null,
+            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,
+            hasData ? h('button', { type: 'button', className: 'dcAgentButton', disabled: busy || !intake.available || intake.pendingText, onClick: () => { actions.setError(null); actions.setStep('rules'); } }, '已核对清单，下一步：字段映射与规则') : null,
           ),
         );
       }
@@ -4414,6 +4463,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
       isImagePathEntry,
       requestPromptImage,
       guessMappings,
+      intakeState,
       projectCompletionResult,
       mappingRecommendations,
       mergeRecommendedMappings,

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.11",
+  "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": {