dsh-data-cleaning-agent 0.9.0 → 0.9.1

package/CHANGELOG.md

@@ -4,6 +4,13 @@
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-09-10
+
+- 新宿主 uiWorkspace 生命周期适配：新会话不再复用清洗空会话，普通草稿与菜单隔离。
+- 修复纯本地清洗完成后结果下载被外部补全状态门禁阻断。
+- 安装前只读组合预检，精确阻断已知双向不兼容；安装脚本须从完整包运行。
+- 260 项检查通过；新组合真实隔离 XLSX 导入、映射、清洗、导出、预览与普通会话验证通过。真实 MCP/OCR 和四产品共存尚未验证。
+
 ## [0.9.0] - 2026-09-10
 
 - 工作台迁移到 Better Sidebar Session 单例 Tab；移除自有固定抽屉、宽度拖拽、展开/关闭按钮和中央会话让位逻辑。

package/README.en.md

@@ -1,6 +1,6 @@
 # dsh-data-cleaning-agent
 
-> 0.9.0 upgrade: the workbench now uses a Session-singleton Better Sidebar Tab, requiring `targetedOpen` and `stateSubscription`. Missing providers show an install/upgrade message, not a private drawer. See the [adoption and validation record](docs/UI-V1.5.0-ADOPTION.md).
+> 0.9.1 upgrade: the workbench now uses a Session-singleton Better Sidebar Tab, requiring `targetedOpen` and `stateSubscription`. Missing providers show an install/upgrade message, not a private drawer. See the [adoption and validation record](docs/UI-V1.5.0-ADOPTION.md).
 
 Data cleaning and data enrichment for CSV/XLSX/JSON enterprise lists in DeepSeek Harness, including spreadsheet cleaning, deduplication, profiling, optional Qichacha MCP and exports.
 
@@ -10,7 +10,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.9.0** (stable release)
+> Current source version / 当前源码版本: **0.9.1** (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.
 
@@ -72,10 +72,13 @@ temporary files. The local server uploads the explicitly submitted file to the Q
 Both use the current customer's own QCC account and quota. Without the local connector,
 image intake fails closed with actionable guidance; text and spreadsheet paths remain available.
 
-Without the `dsh` CLI, use the install script:
+Check the complete DSH `0.1.2-rc.1` + Better Sidebar `0.18.1` combination first. Context is optional; an existing `0.36.0` installation must be upgraded to `0.48.0`. Preflight does not upgrade the global host or prove business acceptance.
+
+Run from a full checkout or unpacked npm package with the actual `dsh` CLI (streamed shell installation is no longer supported):
 
 ```bash
-bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-agent/main/install.sh)
+node lib/install-preflight.js "$DSH_HOME/profiles/web"
+bash install.sh
 ```
 
 Or let an agent install it for you:

package/README.md

@@ -1,6 +1,6 @@
 # dsh-data-cleaning-agent
 
-> 0.9.0 升级说明：工作台已迁移到 Better Sidebar 的 Session 单例 Tab，需要兼容的 `dsh-better-sidebar`（`targetedOpen`、`stateSubscription`）。缺失时会提示安装/升级，不回退到自有抽屉；本轮验证边界见 [采用记录](docs/UI-V1.5.0-ADOPTION.md)。
+> 0.9.1 升级说明：工作台已迁移到 Better Sidebar 的 Session 单例 Tab，需要兼容的 `dsh-better-sidebar`（`targetedOpen`、`stateSubscription`）。缺失时会提示安装/升级，不回退到自有抽屉；本轮验证边界见 [采用记录](docs/UI-V1.5.0-ADOPTION.md)。
 
 本版统一向导与工作台的 Host 执行闭环：发送后自动生成新 Excel，原文件不修改，工作台入口可恢复；发布记录见 [发布说明](docs/RELEASE-0.8.22.md)。
 
@@ -9,7 +9,7 @@
 数据清洗补全智能体：面向 Excel/CSV/JSON 企业名单，提供数据清洗、表格清洗、清洗补全、去重、企业数据补全与字段补全，支持企查查 MCP 和结果导出。
 
 ```sh
-dsh plugin --profile web add dsh-data-cleaning-agent@0.9.0
+dsh plugin --profile web add dsh-data-cleaning-agent@0.9.1
 ```
 
 请先满足下文的 DSH、连接器及侧边栏依赖要求；安装后完整停止并重启对应 Profile。
@@ -27,7 +27,7 @@ dsh plugin --profile web add dsh-data-cleaning-agent@0.9.0
 
 > 在 DeepSeek Harness 中清洗、补全、画像企业名单数据的智能体插件：本地 CSV/XLSX/JSON 引擎 + 可选企查查（Qichacha/QCC）MCP 企业数据补全，由企查查（Qichacha/QCC）团队发起并维护。
 >
-> 当前源码版本 / Current source version: **0.9.0**（正式版本）
+> 当前源码版本 / Current source version: **0.9.1**（正式版本）
 
 本版上传表格后展示完整清单及空白数量，用绿色、琥珀色、红色及文字区分已通过、待确认和未匹配映射。已映射字段自动纳入补全范围，额外字段默认折叠；多个原列可经确认使用同一非主体字段，分别补空并保留非空原值。修复 Host 草稿重置为默认五字段的问题，增加前后端版本错配提示。生成说明不查询，发送才执行；升级后需完整重启 DSH，历史下载文件不自动改写。
 
@@ -81,10 +81,13 @@ Composer 图片附件，因此不支持视觉输入的文本模型也能调度 A
 或分发凭据。本地服务会把用户明确提交的图片上传到企查查文档解析网关；未连接本地服务时功能会
 fail closed，并明确提示配置要求，文本与 Excel 流程不受影响。
 
-没有 `dsh` CLI 时，也可以用安装脚本：
+安装前请核验完整 DSH `0.1.2-rc.1` + Better Sidebar `0.18.1`。context 不是必装依赖；若已装 `0.36.0`，需先升级到 `0.48.0`。预检不会升级全局宿主，也不代表业务验收通过。
+
+从完整源码或解压的 npm 包运行安装脚本（需要实际 `dsh` CLI；不再支持流式脚本）：
 
 ```bash
-bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-agent/main/install.sh)
+node lib/install-preflight.js "$DSH_HOME/profiles/web"
+bash install.sh
 ```
 
 或直接让 Agent 安装：

package/docs/COMPATIBILITY.md

@@ -4,9 +4,27 @@
 
 工作台通过可选 `ctx.inject(['betterSidebar'], ...)` 接入 Provider，探测 `targetedOpen` 与 `stateSubscription`；缺失时保留会话和 Host 工具，不提供私有抽屉回退。当前仅完成隔离模拟服务与 Chromium 回归，尚未实装组合验收；旧版本的 Host/UI 验证不自动覆盖此次迁移。详见 [采用记录](UI-V1.5.0-ADOPTION.md)。
 
-## 1. 目标基线
+## 当前加固目标（2026-09-10）
 
-本插件面向 DeepSeek Harness（DSH）预发布阶段，双基线验证：
+完整 DSH `0.1.2-rc.1` + Better Sidebar `0.18.1`；可选 context 共存版本 `0.48.0`。版本预检通过仅代表排除已知版本冲突，不代表模块加载、服务激活或业务闭环已通过。其他版本提示未验证，旧宿主配 Sidebar 0.18.1、rc.1 配 Sidebar 0.17.1 或 context 0.36.0 阻断安装。反向冲突证据由 AI 填表隔离验收共享：`/tmp/ff-compat-oldhost.log`（实际宿主为 rc.1，文件名并非版本依据），缺少 `settingsNamespace` 导致导入失败。不推断整个版本区间。
+
+安装前从完整包运行 `node lib/install-preflight.js <目标Profile目录> [实际dsh可执行文件]`；只读取包版本并执行 CLI `--version`，不读取密钥或修改安装。先备份 Profile 与锁文件，由宿主管理者升级完整宿主，不能只升级 Session 子包；回滚须还原成套宿主和插件锁定版本，不能把 Sidebar 0.18.1 留在旧宿主上。
+
+## 1. 历史基线（不代表 0.9.0 新组合承诺）
+
+### 本轮隔离证据（2026-09-10，候选未发布）
+
+- Node `v25.9.0`；临时根 `/private/tmp/dcq-host-rc1`，独立 DSH_HOME `home`，端口 `43278`。未访问正式 Profile，未调用真实 MCP。
+- npm pack 候选安装到临时 Profile，完整 DSH `0.1.2-rc.1` / Sidebar `0.18.1` / context `0.48.0`：Host apply、真实浏览器入口和 Session Tab 可见，pageErrors 为 0。未用旧 runtime 模块替身。
+- 合成 XLSX（2 行）实际上传、自动映射、规则确认、质量体检、本地确定性清洗、本地补全、生成 XLSX 均执行；导出工作表 `清洗补全结果` 可反向解析，预览 HTTP 200。
+- 实证修复：纯本地任务完成后仍被下载导航的外部补全状态门禁阻断。现在只在非 QCC 目标、规则已确认且确有本地结果时允许进入下载；QCC 目标仍保持原门禁。
+- 第二处实证修复：rc.1 原生 New Session 已迁至 `uiWorkspace.startSession`，旧桥挂在 `workspaces.startSession` 因而失效。现在通过可选服务注入跟随 `uiWorkspace` 生命周期挂载/恢复兼容桥，保留旧接口回退。重打包安装后 New Session 切换、清洗 dock 隐藏、普通会话自写草稿均通过，pageErrors=0。
+- **待验收**：真实 QCC、图片 OCR、候选确认、多插件完整共存和关闭/恢复回归尚未在此组合完成；不能以本地合成闭环代替这些验收。
+- 环境调整：初次跳过 peer 安装缺失宿主依赖，补全后启动；文件监听 EMFILE，测试 Profile 设 `patchReload: startup` 并关闭 settings/credentials watch。磁盘 ENOSPC 曾阻断工作区创建，清理本轮下载缓存后重试成功。上述不是产品兼容通过依据。
+- 重现脚本：`DCQ_PLAYWRIGHT=<playwright模块路径> DCQ_SMOKE_ROOT=/private/tmp/dcq-host-rc1 node scripts/host-rc1-smoke.cjs`。仅对该布局、指定独立端口运行；需先按上文安装包、注册 bundle 并启动测试 Host，脚本不启动或升级宿主。脚本包含普通会话隔离断言，修复后通过。
+- 本机证据：`/private/tmp/dcq-host-rc1/business-result.log`、`startup.png`、`workbench.png`，全量单测/发布包检查 `/private/tmp/dcq-compat-check.log`（260 通过）。本轮 tarball 是未发布候选，沿用基线版本用于隔离安装，**不允许覆盖发布 npm 0.9.0**。
+
+以下是旧发布的历史证据，不继承为当前组合验收：
 
 | 基线 | 框架 npm 包线 | 备注 |
 | --- | --- | --- |

package/install.sh

@@ -2,8 +2,8 @@
 # dsh-data-cleaning-agent 一键安装脚本（DeepSeek Harness）
 # 用法：
 #   本地：  bash install.sh
-#   远端：  bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-agent/main/install.sh)
-# 支持：优先 dsh CLI（自动注册 bundle）；无 dsh 时回退 pnpm 并兜底注册 bundles。
+#   请从完整 npm 包或源码目录运行，确保随包预检可用。
+# 需要实际 dsh CLI 通过预检；脚本不会升级全局宿主。
 # 幂等：重复执行不会重复注册或破坏已有配置。
 set -euo pipefail
 
@@ -21,6 +21,14 @@ if [ ! -d "$PROFILE_DIR" ]; then
   exit 1
 fi
 
+# 在任何安装/配置写入前，只读检查实际 CLI 与目标 Profile 的组合。
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [ ! -f "$SCRIPT_DIR/lib/install-preflight.js" ]; then
+  echo "错误：缺少随包预检。请解压 npm pack dsh-data-cleaning-agent 的完整包后运行 bash package/install.sh；不再支持流式执行脚本。"
+  exit 1
+fi
+node "$SCRIPT_DIR/lib/install-preflight.js" "$PROFILE_DIR"
+
 # ── 1) 安装依赖 ──
 if command -v dsh >/dev/null 2>&1; then
   echo "==> dsh plugin --profile $PROFILE add $PKG"

package/lib/client.js

@@ -1810,11 +1810,20 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
 
     // rc/alpha 兼容边界：原生 startSession 会复用工作区内的空白会话。
     // 只在清洗会话激活时替换此动作，创建普通会话；不改 connectWorkspace 或全局点击。
-    function installNewSessionBridge(ctx) {
+    function installNewSessionBridge(ctx, navigation) {
+      if (!navigation && typeof ctx.inject === 'function') {
+        const legacy = typeof ctx.workspaces?.startSession === 'function'
+          ? installNewSessionBridge(ctx, ctx.workspaces) : () => {};
+        const fiber = ctx.inject(['uiWorkspace'], scope => {
+          scope.effect(() => installNewSessionBridge(scope, scope.uiWorkspace), 'data-cleaning-agent: native new session');
+        });
+        return () => { legacy(); fiber?.dispose?.(); };
+      }
       const workspaces = ctx.workspaces;
-      const original = workspaces?.startSession;
+      navigation = navigation || workspaces;
+      const original = navigation?.startSession;
       if (typeof original !== 'function' || typeof ctx.sessions?.create !== 'function') return () => {};
-      const ownDescriptor = Object.getOwnPropertyDescriptor(workspaces, 'startSession');
+      const ownDescriptor = Object.getOwnPropertyDescriptor(navigation, 'startSession');
       let pending = null;
       let disposed = false;
       const wrapped = function (workspaceId) {
@@ -1837,13 +1846,13 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
             console.warn('[dc-agent] new session failed; current draft retained:', error instanceof Error ? error.message : String(error));
           }).finally(() => { pending = null; });
       };
-      try { workspaces.startSession = wrapped; }
+      try { navigation.startSession = wrapped; }
       catch (_error) { console.warn('[dc-agent] New Session compatibility bridge unavailable'); return () => {}; }
       return () => {
         disposed = true;
-        if (workspaces.startSession !== wrapped) return;
-        if (ownDescriptor) Object.defineProperty(workspaces, 'startSession', ownDescriptor);
-        else delete workspaces.startSession;
+        if (navigation.startSession !== wrapped) return;
+        if (ownDescriptor) Object.defineProperty(navigation, 'startSession', ownDescriptor);
+        else delete navigation.startSession;
       };
     }
 
@@ -2102,7 +2111,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
         '导入企业名单或图片，核验主体、补全字段，并导出可追溯结果。');
     }
 
-    function workflowNavigationIssue(step, task, hasData, profile, qccRun) {
+    function workflowNavigationIssue(step, task, hasData, profile, qccRun, hasLocalResult = false) {
       if (['upload', 'history'].includes(step)) return null;
       if (step === 'download' && task?.artifacts?.length) return null;
       if (!hasData) return '请先在「导入与核验」载入并核对完整名单。';
@@ -2116,6 +2125,7 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
       if (step === 'enrich' && requiresQcc && !['matched', 'enriching', 'export_ready', 'completed', 'partial'].includes(task.state)) {
         return '请先在「主体匹配」确认企业；多候选需要人工核验。';
       }
+      if (step === 'download' && !requiresQcc && hasLocalResult && ['rules_confirmed', 'diagnosed'].includes(task.state)) return null;
       if (step === 'download' && !['export_ready', 'completed', 'partial'].includes(task.state) && !['completed', 'partial'].includes(qccRun?.state)) {
         return '请先完成清洗或字段补全。原始清单可在「导入与核验」下载。';
       }
@@ -4186,9 +4196,9 @@ body:has(.dcAgentPromptBackdrop) { overflow: hidden; }
               h('button', { type: 'button', className: 'dcAgentButton', 'aria-pressed': step === 'rules', onClick: () => actions.setStep('rules') }, '字段映射与规则'),
               h('button', { type: 'button', className: 'dcAgentButton', 'aria-pressed': step === 'profile', onClick: () => actions.setStep('profile') }, '质量体检报告'),
             ) : null,
-            workflowNavigationIssue(step, cachedTask, hasData, profile, qccRun)
+            workflowNavigationIssue(step, cachedTask, hasData, profile, qccRun, Boolean((clean || complete) && exportRows()?.length))
               ? h('section', { className: 'dcAgentSection', role: 'status' },
-                  h('p', null, workflowNavigationIssue(step, cachedTask, hasData, profile, qccRun)),
+                  h('p', null, workflowNavigationIssue(step, cachedTask, hasData, profile, qccRun, Boolean((clean || complete) && exportRows()?.length))),
                   h('button', { type: 'button', className: 'dcAgentButton',
                     onClick: () => actions.setStep(!hasData ? 'upload' : !cachedTask || ['draft', 'uploaded'].includes(cachedTask.state) ? 'rules' : cachedTask.state === 'rules_confirmed' ? 'profile' : step === 'download' ? 'enrich' : 'match') }, '前往前置步骤'))
               : pane,

package/lib/install-preflight.js

@@ -0,0 +1,49 @@
+/** Read-only combination check. Never installs packages or reads profile secrets. */
+import { readFileSync } from 'node:fs';
+import { resolve, dirname } from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { execFileSync } from 'node:child_process';
+
+export function assessCombination({ host, sidebar, context }) {
+  const errors = [], warnings = [];
+  if (host === '0.1.2-rc.1' && sidebar === '0.17.1') errors.push('DSH 0.1.2-rc.1 与 Better Sidebar 0.17.1 不兼容：缺少 settingsNamespace；请升级侧边栏到 0.18.1。');
+  if (!host) errors.push('无法识别实际 DSH CLI 版本；请先安装完整 DSH，再重新预检。');
+  if (sidebar === '0.18.1' && host && host !== '0.1.2-rc.1') {
+    if (['0.1.1-rc.2', '0.1.2-alpha.2'].includes(host)) {
+      errors.push('Better Sidebar 0.18.1 不兼容此旧宿主。备份后由宿主管理者升级完整 @deepseek-ai/dsh@0.1.2-rc.1；不要只升级 Session 子包。');
+    } else warnings.push('此宿主与 Better Sidebar 0.18.1 组合未验证。');
+  }
+  if (!sidebar) errors.push('工作台需要 dsh-better-sidebar；目标 Profile 请安装 0.18.1（需完整 DSH 0.1.2-rc.1）。');
+  else if (sidebar !== '0.18.1') warnings.push('此侧边栏版本未验证；仍需 targetedOpen 和 stateSubscription 能力。');
+  if (host === '0.1.2-rc.1' && context === '0.36.0') errors.push('已安装的 dsh-context 0.36.0 使用旧 settingsNamespace；先升级该插件到 0.48.0。context 并非本产品必装依赖。');
+  else if (context && context !== '0.48.0') warnings.push('已安装的 context 版本尚未做共存验证。');
+  if (host && host !== '0.1.2-rc.1' && !warnings.length && !errors.length) warnings.push('此宿主组合未验证。');
+  return { host, sidebar, context, errors, warnings, ok: errors.length === 0 };
+}
+
+export function inspectProfile(profile, host) {
+  const req = createRequire(resolve(profile, 'package.json'));
+  const version = name => {
+    let path;
+    try { path = req.resolve(`${name}/package.json`); }
+    catch { try { path = req.resolve(name); } catch { return null; } }
+    for (let dir = dirname(path); ; dir = dirname(dir)) {
+      try { const pkg = JSON.parse(readFileSync(resolve(dir, 'package.json'), 'utf8')); if (pkg.name === name) return pkg.version; } catch { /* no manifest here */ }
+      if (dirname(dir) === dir) return null;
+    }
+  };
+  return assessCombination({ host, sidebar: version('dsh-better-sidebar'), context: version('dsh-context') });
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  const profile = process.argv[2];
+  if (!profile) { console.error('Usage: node lib/install-preflight.js <profile-directory> [dsh-executable]'); process.exitCode = 2; }
+  else {
+    let host = null;
+    try { host = execFileSync(process.argv[3] || 'dsh', ['--version'], { encoding: 'utf8', timeout: 15000 }).match(/\b\d+\.\d+\.\d+(?:-[\w.]+)?\b/)?.[0] ?? null; } catch { /* reported below */ }
+    const report = inspectProfile(profile, host);
+    console.log(JSON.stringify(report, null, 2));
+    process.exitCode = report.ok ? 0 : 1;
+  }
+}

package/package.json

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