dsh-data-cleaning-agent 0.8.17 → 0.8.18

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 ## [Unreleased]
 
+## [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.18** (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.18.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.18
 ```
 
 请先满足下文的 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.18**（正式版本）
 
 本版上传表格后展示完整清单及空白数量，用绿色、琥珀色、红色及文字区分已通过、待确认和未匹配映射。已映射字段自动纳入补全范围，额外字段默认折叠；多个原列可经确认使用同一非主体字段，分别补空并保留非空原值。修复 Host 草稿重置为默认五字段的问题，增加前后端版本错配提示。生成说明不查询，发送才执行；升级后需完整重启 DSH，历史下载文件不自动改写。
 

package/docs/RELEASE-0.8.18.md

@@ -0,0 +1,15 @@
+# 0.8.18
+
+新增共享首条快照契约（qcc-field-contracts 0.2.0），目录共 136 个字段。
+
+- 受益所有人仅取工具返回首条名称，不代表唯一或最大受益人；不以经营管理人员替代。
+- 财务三项取同一个首返回报告期的主要财务指标，缺项留空，不跨期拼接；保留 0、原始精度、报告期与披露等级。
+- 映射大类与关键词联合筛选，当前选择不因过滤丢失。十一类按工商、联系方式、实控人、受益所有人、简介、财务、税务、上市、进出口、自身风险、关联风险排序。
+- 执行中的任务每秒读取 Host 命令状态与任务元数据。显示来源方式、文件名、输入条数、补全字段数、去重后已处理主体数；已处理不等于成功补全。
+- 对话工具结果包含实际任务的 XLSX 链接：浏览器安全预览前 50 行、下载完整新文件。原上传文件不修改。
+
+## 验证
+
+使用合成返回测试首条规则、缺失和精度；验证原列补空、多列映射及 Host 跨重挂载下载。浏览器回归覆盖明暗主题及五种视口。无真实企查查收费查询。
+
+升级后完整重启 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,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
     };
     // 语义不完全等同：只推荐，绝不冒充精确匹配或发起调用。
     const MAPPING_HINTS = {
+      受益所有人: ['beneficial_owner_first_name'], 受益所有人名称: ['beneficial_owner_first_name'], UBO: ['beneficial_owner_first_name'],
       地址: ['registered_address', 'mailing_address', 'invoice_address'],
       address: ['registered_address', 'mailing_address'],
       企业地址: ['registered_address', 'mailing_address'], 公司地址: ['registered_address', 'mailing_address'],
@@ -1556,6 +1562,7 @@ 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);
@@ -1571,6 +1578,9 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
             }
           } },
             h('summary', { className: 'dcAgentField', 'aria-label': `${sourceField} 当前映射` }, label),
+            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('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) => {
               onChange(sourceField, event.target.value);
@@ -1578,11 +1588,12 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
               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]) =>
+              groups.filter(([id, , items]) => !category || id === category || items.some(([key]) => key === value)).map(([id, title, items]) => h('optgroup', { key: id, label: title }, items.filter(([key, name]) => key === value || ((!category || category === id) && matches(key, name))).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,
+            (query || category) && !groups.filter(([id]) => !category || id === category).flatMap(([, , items]) => items).some(([id, name]) => matches(id, name)) ? h('p', { className: 'dcAgentHint', role: 'status' }, '无匹配字段；当前选择保持不变。') : null,
           ),
+          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 +1681,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 +1846,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 +1909,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 ?? ''); },
@@ -3429,6 +3446,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);
@@ -4456,7 +4474,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 +4513,12 @@ 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,
+            ) : null,
             error ? h('div', { className: 'dcAgentError', role: 'alert' }, error) : null,
             step !== 'history' ? h('details', { className: 'dcAgentSection' },
               h('summary', null, '使用说明与任务流程'),

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').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?.enriched ?? 0}/${value.summary?.totalRows ?? 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.18",
   "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.18.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": {