dsh-data-cleaning-agent 0.8.18 → 0.8.19

package/CHANGELOG.md

@@ -4,6 +4,14 @@
 
 ## [Unreleased]
 
+## [0.8.19] - 2026-09-09
+
+- 受益人与主营业务收入增加待确认候选，明确首条限制及财务口径差异，不自动替换。
+- 映射依次展示搜索、大类、可见字段列表；组合筛选保留已有映射。
+- 区分去重主体处理数与输入行补全数，结果卡片和工作台提供原生预览入口。
+- 零异常时不展示空异常清单；有待核验记录时保留下载。
+- 245 项测试及 10 组浏览器布局回归通过；实际 DSH 宿主点击链路仍需升级后验收。
+
 ## [0.8.18] - 2026-09-09
 
 - 新增受益所有人首条名称及首报告期营业总收入、利润总额、总资产，共 136 个字段；共享契约 0.2.0。

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.18** (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.18.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.18
+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.18
 
 > 在 DeepSeek Harness 中清洗、补全、画像企业名单数据的智能体插件：本地 CSV/XLSX/JSON 引擎 + 可选企查查（Qichacha/QCC）MCP 企业数据补全，由企查查（Qichacha/QCC）团队发起并维护。
 >
-> 当前源码版本 / Current source version: **0.8.18**（正式版本）
+> 当前源码版本 / 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/client.js

@@ -1497,7 +1497,8 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
     };
     // 语义不完全等同：只推荐，绝不冒充精确匹配或发起调用。
     const MAPPING_HINTS = {
-      受益所有人: ['beneficial_owner_first_name'], 受益所有人名称: ['beneficial_owner_first_name'], UBO: ['beneficial_owner_first_name'],
+      受益人: ['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'],
@@ -1524,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 };
       });
@@ -1567,7 +1570,12 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
       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 } },
@@ -1578,20 +1586,21 @@ 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: 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) => {
+            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.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]) =>
+              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 || category) && !groups.filter(([id]) => !category || id === category).flatMap(([, , items]) => items).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',
@@ -3165,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: '缺失率 · 去重值 · 金额分布' },
@@ -3203,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,
       );
     }
 
@@ -4343,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),
@@ -4354,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',
@@ -4366,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,
           ),
@@ -4517,7 +4535,8 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
               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,
+              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' },
@@ -4612,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

@@ -265,7 +265,7 @@ export class QccCommandStore {
       state: run.state,
       summary: run.summary,
       ...(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)}` })) } : {}),
+        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)}` })) } : {}),
     });
   }
 }
@@ -313,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' ? '存在多候选，请返回工作台确认主体。' : '请返回工作台查看任务状态。'}\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')}`,
+        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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-data-cleaning-agent",
-  "version": "0.8.18",
+  "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,7 +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/RELEASE-0.8.19.md",
     "docs/TEMPLATE-MAPPING-ACCEPTANCE.md",
     "docs/UI-WORKFLOW-V2.md",
     "docs/UI-WORKFLOW-V2-MIGRATION.md",

package/docs/RELEASE-0.8.18.md

@@ -1,15 +0,0 @@
-# 0.8.18
-
-新增共享首条快照契约（qcc-field-contracts 0.2.0），目录共 136 个字段。
-
-- 受益所有人仅取工具返回首条名称，不代表唯一或最大受益人；不以经营管理人员替代。
-- 财务三项取同一个首返回报告期的主要财务指标，缺项留空，不跨期拼接；保留 0、原始精度、报告期与披露等级。
-- 映射大类与关键词联合筛选，当前选择不因过滤丢失。十一类按工商、联系方式、实控人、受益所有人、简介、财务、税务、上市、进出口、自身风险、关联风险排序。
-- 执行中的任务每秒读取 Host 命令状态与任务元数据。显示来源方式、文件名、输入条数、补全字段数、去重后已处理主体数；已处理不等于成功补全。
-- 对话工具结果包含实际任务的 XLSX 链接：浏览器安全预览前 50 行、下载完整新文件。原上传文件不修改。
-
-## 验证
-
-使用合成返回测试首条规则、缺失和精度；验证原列补空、多列映射及 Host 跨重挂载下载。浏览器回归覆盖明暗主题及五种视口。无真实企查查收费查询。
-
-升级后完整重启 DSH 并重新生成任务说明；旧凭证不改写。