dsh-data-cleaning-agent 0.8.17 → 0.8.19

package/CHANGELOG.md

@@ -4,6 +4,21 @@
 
 ## [Unreleased]
 
+## [0.8.19] - 2026-09-09
+
+- 受益人与主营业务收入增加待确认候选，明确首条限制及财务口径差异，不自动替换。
+- 映射依次展示搜索、大类、可见字段列表；组合筛选保留已有映射。
+- 区分去重主体处理数与输入行补全数，结果卡片和工作台提供原生预览入口。
+- 零异常时不展示空异常清单；有待核验记录时保留下载。
+- 245 项测试及 10 组浏览器布局回归通过；实际 DSH 宿主点击链路仍需升级后验收。
+
+## [0.8.18] - 2026-09-09
+
+- 新增受益所有人首条名称及首报告期营业总收入、利润总额、总资产，共 136 个字段；共享契约 0.2.0。
+- 映射支持大类与关键词联合筛选，统一十一类排序，保留既有选择。
+- 执行期间同步 Host 任务状态和已处理主体数，展示来源、条目数与补全字段数；状态徽标仅反映当前任务。
+- 工具结果返回真实 XLSX 预览/下载入口，绑定 taskId；安全预览前 50 行，不修改源文件、不重复收费查询。
+
 ## [0.8.17] - 2026-09-08
 
 ### Fixed

package/README.en.md

@@ -8,7 +8,7 @@ Related agents: [数据清洗补全](https://github.com/duhu2000/dsh-data-cleani
 
 > 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.17** (stable release)
+> Current source version / 当前源码版本: **0.8.19** (stable release)
 
 This release unifies spreadsheet previews, column mapping, and enrichment scope across the prompt wizard and workbench. Mapping statuses use color and text; mapped fields automatically enter the scope, with optional extra fields collapsed. Multiple confirmed output columns may share a non-identity field while preserving non-empty values. It fixes saved drafts resetting the scope to five defaults and detects stale Host versions. Preparing a draft does not query QCC; sending starts execution. Fully restart DSH after upgrading. Existing download artifacts are not rewritten.
 

package/README.md

@@ -1,13 +1,13 @@
 # dsh-data-cleaning-agent
 
-本版统一向导与工作台的 Host 执行闭环：发送后自动生成新 Excel，原文件不修改，工作台入口可恢复；发布记录见 [发布说明](docs/RELEASE-0.8.17.md)。
+本版统一向导与工作台的 Host 执行闭环：发送后自动生成新 Excel，原文件不修改，工作台入口可恢复；发布记录见 [发布说明](docs/RELEASE-0.8.19.md)。
 
 ## 安装与三分钟上手
 
 数据清洗补全智能体：面向 Excel/CSV/JSON 企业名单，提供数据清洗、表格清洗、清洗补全、去重、企业数据补全与字段补全，支持企查查 MCP 和结果导出。
 
 ```sh
-dsh plugin --profile web add dsh-data-cleaning-agent@0.8.17
+dsh plugin --profile web add dsh-data-cleaning-agent@0.8.19
 ```
 
 请先满足下文的 DSH、连接器及侧边栏依赖要求；安装后完整停止并重启对应 Profile。
@@ -25,7 +25,7 @@ dsh plugin --profile web add dsh-data-cleaning-agent@0.8.17
 
 > 在 DeepSeek Harness 中清洗、补全、画像企业名单数据的智能体插件：本地 CSV/XLSX/JSON 引擎 + 可选企查查（Qichacha/QCC）MCP 企业数据补全，由企查查（Qichacha/QCC）团队发起并维护。
 >
-> 当前源码版本 / Current source version: **0.8.17**（正式版本）
+> 当前源码版本 / Current source version: **0.8.19**（正式版本）
 
 本版上传表格后展示完整清单及空白数量，用绿色、琥珀色、红色及文字区分已通过、待确认和未匹配映射。已映射字段自动纳入补全范围，额外字段默认折叠；多个原列可经确认使用同一非主体字段，分别补空并保留非空原值。修复 Host 草稿重置为默认五字段的问题，增加前后端版本错配提示。生成说明不查询，发送才执行；升级后需完整重启 DSH，历史下载文件不自动改写。
 

package/docs/RELEASE-0.8.19.md

@@ -0,0 +1,13 @@
+# 0.8.19 发布说明
+
+本版修复字段候选、搜索展示和结果交付体验。
+
+- “受益人”推荐首条受益所有人；“主营业务收入”推荐营业总收入并提示口径不同，均需人工确认。
+- 映射选择器按当前映射、搜索、大类、字段清单展示；筛选不修改已选映射。
+- 已处理主体数包含未匹配或失败，不代表已补全；同时展示按输入行统计的补全与待核验数。
+- QCC 工具结果卡片与工作台增加原生文件链接，不只依赖模型生成 Markdown。
+- 空异常清单不展示；实际存在异常时保留。
+
+验证：245 项自动测试、10 组明暗色与响应式浏览器回归通过。未发起付费 QCC 查询，未修改上传源文件。实际 DSH 宿主中的文件点击仍需升级后验收。
+
+升级至 0.8.19 后完整重启 DSH。历史对话文本不会自动重写；历史制品可从工作台获取。

package/lib/artifacts.js

@@ -23,6 +23,7 @@ const SYSTEM_FIELD_LABELS = Object.freeze({
   qcc_match_status: '匹配状态',
   qcc_field_issues: '字段补全待核验原因',
   qcc_source: '数据来源',
+  qcc_snapshot_note: '取值口径与报告期',
   qcc_error: '错误原因',
   match_status: '匹配状态',
   error: '错误原因',

package/lib/client.js

@@ -1141,7 +1141,10 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
       ['tax_violation', '税收违法'], ['judgment_debtor', '被执行人'], ['terminated_case', '终本案件'],
       ['equity_freeze', '股权冻结'],
     ];
+    const FIELD_GROUP_ORDER = ['company_registration', 'contact_info', 'actual_controller', 'beneficial_owners', 'company_profile', 'financial_data', 'tax_invoice_info', 'listing_info', 'import_export_credit', 'company_risk_scan', 'company_related_risk_scan'];
     const FIELD_GROUPS = [
+      ['beneficial_owners', '受益所有人', [['beneficial_owner_first_name', '受益所有人名称（首条）']], 'get_beneficial_owners'],
+      ['financial_data', '财务数据', [['financial_total_revenue', '营业总收入'], ['financial_total_profit', '利润总额'], ['financial_total_assets', '总资产']], 'get_financial_data'],
       // Shared contract mirror: checked against qcc-field-contracts in tests.
       ['actual_controller', '实际控制人', [
         ['actual_controller_name', '实际控制人名称'],
@@ -1204,6 +1207,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
         ...RELATED_RISK_KEY_FIELD_OPTIONS.map(([id, label]) => [`related_risk_${id}_party_count`, `关联风险-${label}命中关联方数`]),
       ], 'get_company_related_risk_scan'],
     ];
+    FIELD_GROUPS.sort((a, b) => FIELD_GROUP_ORDER.indexOf(a[0]) - FIELD_GROUP_ORDER.indexOf(b[0]));
     const ENRICHMENT_OPTIONS = FIELD_GROUPS.flatMap(([, , fields]) => fields);
     const INPUT_ONLY_MAPPING_OPTIONS = [['phone', '联系电话']];
     const RESULT_FIELD_LABELS = new Map([
@@ -1476,6 +1480,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
     }
 
     const MAPPING_ALIASES = {
+      beneficial_owner_first_name: ['首条受益所有人名称'],
       actual_controller_name: ['实控人', '实际控制人', '企业实控人名称', '企业实际控制人', '企业实控人名称（自然人请填写姓名）'],
       actual_controller_direct_ratio: ['实际控制人直接持股比例'],
       actual_controller_total_ratio: ['实际控制人总持股比例'],
@@ -1492,6 +1497,8 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
     };
     // 语义不完全等同：只推荐，绝不冒充精确匹配或发起调用。
     const MAPPING_HINTS = {
+      受益人: ['beneficial_owner_first_name'], 受益所有人: ['beneficial_owner_first_name'], 受益所有人名称: ['beneficial_owner_first_name'], UBO: ['beneficial_owner_first_name'],
+      主营业务收入: ['financial_total_revenue'],
       地址: ['registered_address', 'mailing_address', 'invoice_address'],
       address: ['registered_address', 'mailing_address'],
       企业地址: ['registered_address', 'mailing_address'], 公司地址: ['registered_address', 'mailing_address'],
@@ -1518,6 +1525,8 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
           const hints = Object.entries(MAPPING_HINTS).find(([key]) => normalizeMappingLabel(key) === label)?.[1] || [];
           candidates = hints.flatMap((key) => fields.filter(([id]) => id === key));
           reason = candidates.length ? '含义需确认，点击推荐后采用' : '未识别表头，请手动选择';
+          if (candidates.length && label === normalizeMappingLabel('主营业务收入')) reason = '主营业务收入与营业总收入口径不同；确认接受该口径后采用';
+          if (candidates.length && label === normalizeMappingLabel('受益人')) reason = '受益人含义需确认；仅取首条受益所有人，不代表唯一或最大受益人';
         }
         return { sourceField: String(sourceField), candidates, automatic: exact, reason };
       });
@@ -1556,11 +1565,17 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
 
     function MappingPicker({ sourceField, mappings, groups, recommendation, onChange }) {
       const [query, setQuery] = react.useState('');
+      const [category, setCategory] = react.useState('');
       const value = mappings.find((item) => item.sourceField === sourceField)?.targetField || '';
       const occupied = (id) => isAnchorField(id) && mappings.some((item) => item.sourceField !== sourceField && item.targetField === id);
       const fields = groups.flatMap(([, , items]) => items);
       const label = fields.find(([id]) => id === value)?.[1] || '不参与匹配 / 补全';
-      const matches = (id, name) => normalizeMappingLabel([id, name, ...(MAPPING_ALIASES[id] || [])].join(' ')).includes(normalizeMappingLabel(query));
+      const matches = (id, name) => normalizeMappingLabel([id, name, ...(MAPPING_ALIASES[id] || []), ...Object.entries(MAPPING_HINTS).filter(([, ids]) => ids.includes(id)).map(([hint]) => hint)].join(' ')).includes(normalizeMappingLabel(query));
+      const filteredGroups = groups.filter(([id]) => !category || id === category)
+        .map(([id, title, items]) => [id, title, items.filter(([key, name]) => matches(key, name))])
+        .filter(([, , items]) => items.length);
+      const filteredFields = filteredGroups.flatMap(([, , items]) => items);
+      const hiddenSelection = value && !filteredFields.some(([id]) => id === value);
       return h('div', { className: 'dcAgentMappingRow' },
         h('span', { title: sourceField }, sourceField), h('b', { 'aria-hidden': 'true' }, '→'),
         h('div', { style: { minWidth: 0 } },
@@ -1571,18 +1586,23 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
             }
           } },
             h('summary', { className: 'dcAgentField', 'aria-label': `${sourceField} 当前映射` }, label),
-            h('input', { className: 'dcAgentField', value: query, placeholder: '搜索字段名称 / 英文键 / 别名', 'aria-label': `${sourceField} 搜索映射字段`, onChange: (event) => setQuery(event.target.value) }),
-            h('select', { className: 'dcAgentField', value, 'aria-label': `${sourceField} 字段映射`, onChange: (event) => {
+            h('input', { className: 'dcAgentField', value: query, placeholder: '模糊搜索字段名称 / 英文键 / 别名', 'aria-label': `${sourceField} 搜索映射字段`, onChange: (event) => setQuery(event.target.value) }),
+            h('select', { className: 'dcAgentField', value: category, 'aria-label': `${sourceField} 映射大类`, onChange: (event) => setCategory(event.target.value) },
+              h('option', { value: '' }, '全部维度'),
+              groups.map(([id, title]) => h('option', { key: id, value: id }, title))),
+            h('select', { className: 'dcAgentField', size: 8, style: { height: 'auto', minHeight: '180px' }, value, 'aria-label': `${sourceField} 字段映射`, onChange: (event) => {
               onChange(sourceField, event.target.value);
               const details = event.currentTarget.closest('details');
               if (details) { details.open = false; details.querySelector('summary')?.focus(); }
             } },
               h('option', { value: '' }, '不参与匹配 / 补全'),
-              groups.map(([id, title, items]) => h('optgroup', { key: id, label: title }, items.filter(([key, name]) => key === value || matches(key, name)).map(([key, name]) =>
+              hiddenSelection ? h('option', { value, disabled: true }, `当前选择：${label}（不符合筛选，保持不变）`) : null,
+              filteredGroups.map(([id, title, items]) => h('optgroup', { key: id, label: title }, items.map(([key, name]) =>
                 h('option', { key, value: key, disabled: occupied(key) }, `${name}${occupied(key) ? '（已被其他列使用）' : ''}`)))),
             ),
-            query && !fields.some(([id, name]) => matches(id, name)) ? h('p', { className: 'dcAgentHint', role: 'status' }, '无匹配字段；当前选择保持不变。') : null,
+            h('p', { className: 'dcAgentHint', role: 'status' }, filteredFields.length ? `匹配 ${filteredFields.length} 个字段；选择后采用。` : '无匹配字段；当前选择保持不变。'),
           ),
+          value === 'beneficial_owner_first_name' || value.startsWith('financial_') ? h('p', { className: 'dcAgentHint' }, value === 'beneficial_owner_first_name' ? '仅取返回首条受益所有人，不代表唯一或最大受益人。' : '取返回首个报告期，不跨期补值；报告期保留在结果取值说明中。') : null,
           h('small', { className: 'dcAgentMappingStatus', 'data-status': value ? 'confirmed' : recommendation.candidates.length ? 'review' : 'unmatched',
             style: { display: 'block', padding: '6px 0' } },
             value ? `${recommendation.automatic && recommendation.candidates[0]?.[0] === value ? '自动通过' : '已确认'}：${label}；可手动调整` : recommendation.candidates.length ? `待人工确认：${recommendation.conflict ? '重复列可确认使用同一补全字段；主体标识只选一列' : recommendation.reason}` : '未匹配：保留原列，可手动选择字段'),
@@ -1670,10 +1690,11 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
       return requestJson(path, body === undefined ? 'GET' : 'POST', body);
     }
 
-    async function waitForQccCommand(commandId, attempts = 180) {
+    async function waitForQccCommand(commandId, attempts = 180, onStatus) {
       for (let attempt = 0; attempt < attempts; attempt += 1) {
         const response = await api(`/data-cleaning/api/g5/commands/${encodeURIComponent(commandId)}`);
         const command = response?.command;
+        await onStatus?.(command);
         if (command?.state === 'completed' || command?.state === 'failed') return command;
         await new Promise((resolve) => setTimeout(resolve, 1000));
       }
@@ -1834,7 +1855,11 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
       return response.task;
     }
     function watchHostedCommand(actions, sessionId, command) {
-      void waitForQccCommand(command.commandId, 1800).then(async (completed) => {
+      void waitForQccCommand(command.commandId, 1800, async (status) => {
+        if (!status || status.state === 'prepared') return;
+        await refreshHostedTask(actions, sessionId, command.taskId, null, true).catch(() => {});
+        if (isCleaningSession(sessionId) && workflowTaskBySession.get(String(sessionId))?.id === command.taskId) actions.setCommandProgress?.({ taskId: command.taskId, ...status.progress });
+      }).then(async (completed) => {
         await refreshHostedTask(actions, sessionId, command.taskId, completed.run);
         if (completed.state === 'failed') throw new Error(completed.error?.message || 'Host 执行失败，请在工作台查看状态。');
       }).catch((error) => {
@@ -1893,6 +1918,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
           setError: (draft, error) => { draft.error = error; },
           setInput: (draft, input) => { draft.input = input; },
           setWorkflowContract: (draft, value) => { draft.workflowContract = value; },
+          setCommandProgress: (draft, value) => { draft.commandProgress = value; },
           setWorkflowTask: (draft, value) => { draft.workflowTask = value ?? null; },
           setWorkflowTasks: (draft, value) => { draft.workflowTasks = Array.isArray(value) ? value : []; },
           setTaskTitle: (draft, value) => { draft.taskTitle = String(value ?? ''); },
@@ -3148,6 +3174,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
 
     /** 模型工具 tool.call.toolview 卡片元数据（wire 名 → 展示文案）。 */
     const TOOL_VIEW_META = {
+      data_cleaning_qcc_run: { icon: '🧩', label: '企查查清洗补全结果', hint: '已处理包含未匹配或失败；不等于已补全。' },
       data_clean_rows: { icon: '🧹', label: '数据清洗', hint: '去重 · 剔除非法金额 · 缺失补 0' },
       data_complete_rows: { icon: '🧩', label: '数据补全', hint: '名称 / 金额 / 手机号归一' },
       data_profile: { icon: '🩺', label: '数据体检', hint: '缺失率 · 去重值 · 金额分布' },
@@ -3186,6 +3213,9 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
         ),
         meta.hint ? h('div', { className: 'dcAgentToolCardHint' }, meta.hint) : null,
         summary ? h('div', { className: 'dcAgentToolCardBody' }, summary) : null,
+        toolName === 'data_cleaning_qcc_run' ? h('div', { className: 'dcAgentArtifactList' },
+          [...summary.matchAll(/\[([^\]]+)\]\((\/data-cleaning\/api\/workflow\/tasks\/[a-zA-Z0-9%_-]+\/artifacts\/[a-zA-Z0-9%_-]+(?:\?preview=1)?)\)/g)].map((match, index) =>
+            h('a', { key: index, className: 'dcAgentButton', href: match[2], target: '_blank', rel: 'noopener noreferrer' }, match[1]))) : null,
       );
     }
 
@@ -3429,6 +3459,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
       const selectedDomains = useStore((state) => state.selectedDomains);
       const qccCapabilities = useStore((state) => state.qccCapabilities);
       const qccRun = useStore((state) => state.qccRun);
+      const commandProgress = useStore((state) => state.commandProgress);
       const paidConfirmed = useStore((state) => state.paidConfirmed);
       const jobs = useStore((state) => state.jobs);
       const activeSessionId = useStore((state) => state.activeSessionId);
@@ -4325,10 +4356,10 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
           h('div', { className: 'dcAgentRow' }, h('button', { type: 'button', className: 'dcAgentButton is-primary', onClick: () => actions.setStep('download') }, '进入下载数据')),
         );
       } else if (step === 'download') {
-        const availableArtifacts = cachedTask?.artifacts || [];
+        const availableArtifacts = (cachedTask?.artifacts || []).filter(artifact => artifact.kind !== 'review' || artifact.rowCount > 0);
         const canCreateArtifacts = Boolean(exportRows()?.length) && ['rules_confirmed', 'diagnosed', 'export_ready', 'partial'].includes(cachedTask?.state);
         pane = h('div', { className: 'dcAgentPane' },
-          h('p', { className: 'dcAgentHint' }, '结果与异常清单由 Host 生成 CSV/XLSX 四件套并耐久保存。任务或插件重启后，可从任务历史继续下载；无需再次调用企查查。'),
+          h('p', { className: 'dcAgentHint' }, '结果文件由 Host 保存；仅在有待核验记录时展示异常清单。任务或插件重启后，可从任务历史继续下载；无需再次调用企查查。'),
           h('div', { className: 'dcAgentGrid' },
             stat('输入行数', dataset ? dataset.rowCount : workflowTask?.source?.rowCount ?? '—'),
             stat('匹配补全', qccEnrichedCount, qccEnrichedCount > 0 ? 'good' : null),
@@ -4336,6 +4367,11 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
             stat('任务状态', WORKFLOW_STATE_LABELS[cachedTask?.state] || cachedTask?.state || '进行中'),
           ),
           availableArtifacts.length ? h('div', { className: 'dcAgentArtifactList' },
+            availableArtifacts.filter(artifact => artifact.format === 'xlsx').map(artifact => h('a', {
+              key: 'preview-' + artifact.id, className: 'dcAgentButton',
+              href: `/data-cleaning/api/workflow/tasks/${encodeURIComponent(cachedTask.id)}/artifacts/${encodeURIComponent(artifact.id)}?preview=1`,
+              target: '_blank', rel: 'noopener noreferrer',
+            }, `预览 / 打开：${artifact.fileName}`)),
             availableArtifacts.map((artifact) => h('button', {
               key: artifact.id,
               type: 'button',
@@ -4348,8 +4384,8 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
             h('div', { className: 'dcAgentRow' },
               h('button', { type: 'button', className: 'dcAgentButton is-primary', disabled: busy || !canCreateArtifacts, onClick: () => createAndDownload('complete', 'xlsx') }, '生成并下载结果 XLSX'),
               h('button', { type: 'button', className: 'dcAgentButton', disabled: busy || !canCreateArtifacts, onClick: () => createAndDownload('complete', 'csv') }, '生成并下载结果 CSV'),
-              h('button', { type: 'button', className: 'dcAgentButton', disabled: busy || !canCreateArtifacts, onClick: () => createAndDownload('review', 'xlsx') }, '生成并下载异常清单 XLSX'),
-              h('button', { type: 'button', className: 'dcAgentButton', disabled: busy || !canCreateArtifacts, onClick: () => createAndDownload('review', 'csv') }, '生成并下载异常清单 CSV'),
+              qccReviewCount > 0 ? h('button', { type: 'button', className: 'dcAgentButton', disabled: busy || !canCreateArtifacts, onClick: () => createAndDownload('review', 'xlsx') }, '生成并下载异常清单 XLSX') : null,
+              qccReviewCount > 0 ? h('button', { type: 'button', className: 'dcAgentButton', disabled: busy || !canCreateArtifacts, onClick: () => createAndDownload('review', 'csv') }, '生成并下载异常清单 CSV') : null,
             ),
             !canCreateArtifacts ? h('p', { className: 'dcAgentHint' }, '请先完成规则确认与清洗补全；历史任务若尚未生成制品，需要重新上传源文件。') : null,
           ),
@@ -4456,7 +4492,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
                 className: 'dcAgentQccBadge',
                 title: qccRun ? `任务 ${qccRun.runId}` : '仅在当前用户确认使用自己的企查查账号后调用',
               }, 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('span', { className: 'dcAgentJobsPill', 'data-state': cachedTask?.state || 'idle', title: '当前清洗任务状态' }, cachedTask ? WORKFLOW_STATE_LABELS[cachedTask.state] || cachedTask.state : '尚未开始'),
               h('button', {
                 className: 'dcAgentWbClose',
                 type: 'button',
@@ -4495,6 +4531,13 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
             h('span', { className: 'dcAgentStepLabel' }, st.label))),
           ) : null,
           h('div', { className: 'dcAgentWbBody' },
+            cachedTask && step !== 'history' ? h('section', { className: 'dcAgentSection', 'aria-label': '当前任务进展', 'aria-live': 'polite' },
+              h('b', null, WORKFLOW_STATE_LABELS[cachedTask.state] || cachedTask.state),
+              h('p', { className: 'dcAgentHint' }, `任务：${cachedTask.id}`),
+              h('p', null, `${cachedTask.source?.type === 'image' ? '图片识别' : cachedTask.source?.type === 'text' ? '粘贴名单' : '上传表格'} · ${cachedTask.source?.fileName || ''} · ${cachedTask.source?.rowCount || 0} 条 · ${cachedTask.fieldSelection?.length || 0} 个补全字段`),
+              commandProgress?.taskId === cachedTask.id && Number.isFinite(commandProgress.totalUnique) ? h('p', null, `已处理主体 ${commandProgress.completedUnique}/${commandProgress.totalUnique}（去重后，含未匹配或失败，不代表补全成功）`) : null,
+              h('p', null, `已补全 ${qccEnrichedCount} 条 · 待核验 ${qccReviewCount} 条（按输入行统计）`),
+            ) : null,
             error ? h('div', { className: 'dcAgentError', role: 'alert' }, error) : null,
             step !== 'history' ? h('details', { className: 'dcAgentSection' },
               h('summary', null, '使用说明与任务流程'),
@@ -4588,7 +4631,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
 
         // 模型工具的 tool.call.toolview 富化卡片（keyed by wire name，替代裸 JSON 摘要）。
         // 说明：分三条独立 inject（而非 generator）——测试 shim 对 inject 回调仅执行一次并 push 其返回值。
-        const toolviewKeys = ['data_clean_rows', 'data_complete_rows', 'data_profile', 'data_cleaning_extract_image_companies'];
+        const toolviewKeys = ['data_clean_rows', 'data_complete_rows', 'data_profile', 'data_cleaning_extract_image_companies', 'data_cleaning_qcc_run'];
         for (const key of toolviewKeys) {
           ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({
             name: 'tool.call.toolview',

package/lib/qcc-command.js

@@ -104,6 +104,7 @@ export function serializeQccCommandPrompt(command) {
     `安全任务凭证：${command.commandId}`,
     '',
     `发送本说明后，请仅调用一次数据清洗补全执行工具（${TOOL_QCC_COMMAND}），参数只传递上述安全任务凭证。`,
+    '完成后请在对话中列出工具返回的 XLSX 文件名、预览和下载链接；只使用实际返回的链接，不编造文件或要求源文件路径。',
     '不要要求重复粘贴企业名单，不要直接调用 mcp__qcc-* 工具，不要重试、扩大名单或追加字段。',
     input.workflowOwned
       ? '发送即执行已确认方案，不再询问额度或写回确认。Host 会自动生成新的清洗补全结果 XLSX，原始上传文件不修改。不要寻找源文件路径、运行 Bash、编写导出脚本或另行覆盖源文件。'
@@ -182,6 +183,7 @@ export class QccCommandStore {
       runId: record.runId,
       error: record.error,
       estimate: record.estimate,
+      progress: record.progress ?? null,
       workflowOwned: record.input.workflowOwned === true,
       delivery: record.delivery ?? null,
       expiresInMs: this.ttlMs,
@@ -233,6 +235,7 @@ export class QccCommandStore {
       return this.runs.retryCompanies(record.input.runId, record.input.companyNames, this.bridge, options);
     }
     const audit = [];
+    record.progress = { completedUnique: 0, totalUnique: record.estimate?.uniqueCompanies || 0 };
     const result = await this.bridge.enrichRows(record.input.rows, {
       nameField: record.input.nameField,
       includeRisk: record.input.includeRisk,
@@ -241,6 +244,7 @@ export class QccCommandStore {
       maxRows: 100,
       execution,
       onAudit: (event) => audit.push(event),
+      onProgress: (progress) => { record.progress = progress; },
     });
     return this.runs.createRun({
       headers: record.input.headers,
@@ -260,7 +264,8 @@ export class QccCommandStore {
       runId: run.runId,
       state: run.state,
       summary: run.summary,
-      ...(record.delivery ? { deliveryState: record.delivery.state, artifactCount: record.delivery.artifacts.length } : {}),
+      ...(record.delivery ? { deliveryState: record.delivery.state, artifactCount: record.delivery.artifacts.length,
+        artifacts: record.delivery.artifacts.filter(a => a.format === 'xlsx' && (a.kind !== 'review' || a.rowCount > 0)).map(a => ({ fileName: a.fileName, url: `/data-cleaning/api/workflow/tasks/${encodeURIComponent(record.taskId)}/artifacts/${encodeURIComponent(a.id)}` })) } : {}),
     });
   }
 }
@@ -286,6 +291,7 @@ export function registerQccCommandTool(tools, commands) {
           state: { type: 'string' },
           deliveryState: { type: 'string' },
           artifactCount: { type: 'integer' },
+          artifacts: { type: 'array', items: { type: 'object', additionalProperties: false, properties: { fileName: { type: 'string' }, url: { type: 'string' } }, required: ['fileName', 'url'] } },
           summary: {
             type: 'object',
             additionalProperties: false,
@@ -307,7 +313,7 @@ export function registerQccCommandTool(tools, commands) {
       },
       render: (_args, value) => [{
         type: 'text',
-        text: `数据清洗补全：${value.summary?.enriched ?? 0}/${value.summary?.totalRows ?? 0} 条已补全。${value.artifactCount ? 'Host 已生成新的结果 XLSX，请返回工作台「结果下载」。源文件未修改，无需再次确认或提供路径。' : value.deliveryState === 'review_required' ? '存在多候选，请返回工作台确认主体。' : '请返回工作台查看任务状态。'}`,
+        text: `处理结束：已处理 ${value.summary?.uniqueCompanies ?? 0} 个去重主体（含未匹配或失败）；按输入行统计：${value.summary?.enriched ?? 0}/${value.summary?.totalRows ?? 0} 条已补全。未匹配 ${value.summary?.unresolved ?? 0} 条、失败 ${value.summary?.failed ?? 0} 条、多候选 ${value.summary?.ambiguous ?? 0} 条、字段待核验 ${value.summary?.fieldReview ?? 0} 条。不得仅凭补全为 0 推断授权异常；请依据实际错误记录。${value.artifactCount ? 'Host 已生成新的结果 XLSX，请返回工作台「结果下载」。源文件未修改，无需再次确认或提供路径。' : value.deliveryState === 'review_required' ? '存在多候选，请返回工作台确认主体。' : '请返回工作台查看任务状态。'}\n${(value.artifacts || []).map(a => `${String(a.fileName).replace(/[^a-zA-Z0-9\u4e00-\u9fff._ -]/g, '_')}：[预览 / 打开](${a.url}?preview=1) · [下载 Excel](${a.url})`).join('\n')}`,
       }],
     },
     async execute(args, exec) {

package/lib/qcc-field-catalog.js

@@ -5,7 +5,7 @@
  * 任何明细列表（电话全集、海关资质、风险关联方等）都不得进入本目录。
  */
 
-import { ACTUAL_CONTROLLER_GROUP } from 'qcc-field-contracts';
+import { ACTUAL_CONTROLLER_GROUP, SNAPSHOT_GROUPS, SNAPSHOT_GROUP_ORDER } from 'qcc-field-contracts';
 const field = (id, label, options = {}) => Object.freeze({ id, label, ...options });
 const group = (id, label, sourceTool, fields, options = {}) => Object.freeze({
   id,
@@ -175,7 +175,8 @@ export const QCC_FIELD_CATALOG = Object.freeze([
     ...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,
-]);
+  ...SNAPSHOT_GROUPS,
+].sort((a, b) => SNAPSHOT_GROUP_ORDER.indexOf(a.id) - SNAPSHOT_GROUP_ORDER.indexOf(b.id)));
 
 export const QCC_FIELD_SOURCE_TOOL = Object.freeze(Object.fromEntries(
   QCC_FIELD_CATALOG.flatMap((entry) => entry.fields.map((item) => [item.id, entry.sourceTool])),

package/lib/qcc-runs.js

@@ -235,6 +235,7 @@ export class G5RunStore {
           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',
+          ...(result.snapshotNote ? { qcc_snapshot_note: result.snapshotNote } : {}),
         };
       } else {
         record.rows[index] = { ...row, qcc_match_status: result.status };

package/lib/qcc.js

@@ -8,7 +8,7 @@
  * - 批量补全只在 Host/Web 内处理明细；模型仍只接收摘要。
  */
 import { safeAuditEvent } from './qcc-safety.js';
-import { projectActualController } from 'qcc-field-contracts';
+import { projectActualController, projectFirstSnapshot } from 'qcc-field-contracts';
 import {
   QCC_PHASE2_COMPANY_TOOLS,
   QCC_PHASE2_HISTORY_TOOLS,
@@ -558,6 +558,7 @@ export function mapActualControllerFields(value, match) {
   return result.values;
 }
 const SOURCE_TOOL_CONFIG = Object.freeze({
+  ...Object.fromEntries(['get_beneficial_owners', 'get_financial_data'].map(tool => [tool, { name: `mcp__qcc-company__${tool}`, map: data => projectFirstSnapshot(data, tool).values }])),
   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 }),
@@ -928,6 +929,7 @@ export class QccHostBridge {
     const sourceTools = sourceToolsForFieldSelection(options.fieldSelection, options.includeRisk);
     let mapped = {};
     const fieldIssues = {};
+    const snapshotNotes = [];
     let legacyRiskTags = '';
     for (const sourceTool of sourceTools) {
       const config = SOURCE_TOOL_CONFIG[sourceTool];
@@ -935,6 +937,11 @@ 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 (['get_beneficial_owners', 'get_financial_data'].includes(sourceTool)) {
+        const projection = projectFirstSnapshot(response.data, sourceTool);
+        Object.assign(fieldIssues, Object.fromEntries(Object.entries(projection.issues).filter(([id]) => options.fieldSelection?.includes(id))));
+        snapshotNotes.push(sourceTool === 'get_financial_data' ? `get_financial_data：返回首期 ${projection.provenance.reportPeriod || '未返回报告期'}；${projection.provenance.disclosure || '未返回披露等级'}；金额原值未换算` : `get_beneficial_owners：仅取首条；返回 ${projection.provenance.recordCount} 条，不代表唯一受益人`);
+      }
       if (sourceTool === 'get_actual_controller') {
         Object.assign(fieldIssues, Object.fromEntries(Object.entries(projectActualController(response.data).issues)
           .filter(([field]) => options.fieldSelection?.includes(field))));
@@ -958,6 +965,7 @@ export class QccHostBridge {
     const fields = projectSelectedFields(mapped, options.fieldSelection);
     if (options.includeRisk) fields.risk_tags = legacyRiskTags;
     return { status: 'enriched', companyName: String(match?.companyName ?? ''), fields,
+      ...(snapshotNotes.length ? { snapshotNote: snapshotNotes.join('；') } : {}),
       ...(Object.keys(fieldIssues).length ? { fieldIssues } : {}) };
   }
 
@@ -1061,6 +1069,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',
+          ...(result.snapshotNote ? { qcc_snapshot_note: result.snapshotNote } : {}),
           ...(row.qcc_field_issues || result.fieldIssues ? { qcc_field_issues: Object.entries(result.fieldIssues || {}).map(([field, issue]) => field + ': ' + issue.message).join('；') } : {}),
         };
       }

package/lib/web.js

@@ -559,6 +559,16 @@ export function mountWebRoutes(wctx, { logger, report, TOOL_NAME, SKILL_NAME })
           const artifact = current.artifacts.find((item) => item.id === artifactId);
           if (!artifact) throw new ArtifactError('DC_ARTIFACT_NOT_FOUND', 'Artifact not found for this task.', 404);
           const bytes = await artifactStore.read(taskId, artifact);
+          if (artifact.format === 'xlsx' && new URL(req.url, 'http://127.0.0.1').searchParams.get('preview') === '1') {
+            const parsed = await parseXlsx(bytes);
+            const escape = value => String(value ?? '').replace(/[&<>\"]/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '\"': '&quot;' }[c]));
+            const columns = parsed.headers || [];
+            const rows = (parsed.rows || []).slice(0, 50);
+            const download = `/data-cleaning/api/workflow/tasks/${encodeURIComponent(taskId)}/artifacts/${encodeURIComponent(artifactId)}`;
+            const html = `<!doctype html><meta charset="utf-8"><meta name="viewport" content="width=device-width"><title>${escape(artifact.fileName)}</title><style>body{font:14px system-ui;padding:24px;color:#243044}table{border-collapse:collapse}td,th{border:1px solid #dde5ef;padding:8px;min-width:100px;white-space:pre-wrap}th{background:#e5f3ff}a{color:#0875ce}</style><h1>${escape(artifact.fileName)}</h1><p>任务 ${escape(taskId)} · 共 ${artifact.rowCount} 行，预览前 50 行；源文件未修改。</p><a href="${download}">下载完整 Excel</a><table><thead><tr>${columns.map(c => `<th>${escape(c)}</th>`).join('')}</tr></thead><tbody>${rows.map(row => `<tr>${columns.map(c => `<td>${escape(row[c])}</td>`).join('')}</tr>`).join('')}</tbody></table>`;
+            res.writeHead(200, { 'content-type': 'text/html; charset=utf-8', 'cache-control': 'no-store', 'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'self'", 'x-content-type-options': 'nosniff' });
+            return res.end(html);
+          }
           const fallback = artifact.format === 'xlsx' ? 'export.xlsx' : 'export.csv';
           const asciiName = String(artifact.fileName || fallback).replace(/[^\x20-\x7e]/g, '_').replace(/["\\]/g, '_');
           res.writeHead(200, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-data-cleaning-agent",
-  "version": "0.8.17",
+  "version": "0.8.19",
   "description": "Data cleaning and data enrichment for CSV/XLSX/JSON enterprise lists in DeepSeek Harness, including spreadsheet cleaning, deduplication, profiling, optional Qichacha MCP and exports.",
   "type": "module",
   "main": "lib/index.js",
@@ -40,6 +40,7 @@
     "docs/RELEASE-0.8.1.md",
     "docs/RELEASE-0.8.16.md",
     "docs/RELEASE-0.8.17.md",
+    "docs/RELEASE-0.8.19.md",
     "docs/TEMPLATE-MAPPING-ACCEPTANCE.md",
     "docs/UI-WORKFLOW-V2.md",
     "docs/UI-WORKFLOW-V2-MIGRATION.md",
@@ -117,7 +118,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "qcc-field-contracts": "0.1.0",
+    "qcc-field-contracts": "0.2.0",
     "xlsx": "^0.18.5"
   },
   "peerDependencies": {