dsh-data-cleaning-agent 0.8.23 → 0.9.1

package/CHANGELOG.md

@@ -4,6 +4,20 @@
 
 ## [Unreleased]
 
+## [0.9.1] - 2026-09-10
+
+- 新宿主 uiWorkspace 生命周期适配：新会话不再复用清洗空会话，普通草稿与菜单隔离。
+- 修复纯本地清洗完成后结果下载被外部补全状态门禁阻断。
+- 安装前只读组合预检，精确阻断已知双向不兼容；安装脚本须从完整包运行。
+- 260 项检查通过；新组合真实隔离 XLSX 导入、映射、清洗、导出、预览与普通会话验证通过。真实 MCP/OCR 和四产品共存尚未验证。
+
+## [0.9.0] - 2026-09-10
+
+- 工作台迁移到 Better Sidebar Session 单例 Tab；移除自有固定抽屉、宽度拖拽、展开/关闭按钮和中央会话让位逻辑。
+- 按 Session 隔离任务视图；关闭或折叠 Tab 不取消任务，五流程入口复用同一 Tab。
+- 可选 Provider 生命周期探测，缺失时提示安装/升级，不回退到旧抽屉；需要 targetedOpen 和 stateSubscription。
+- 完整 256 项测试及 10 组隔离 React/Chromium 回归通过；真实 DSH 四插件组合联调尚未完成，详见 docs/UI-V1.5.0-ADOPTION.md。
+
 ## [0.8.23] - 2026-09-09
 
 - 工作台顶部仅保留产品标题和展开、关闭按钮，移除重复状态与技术标识。

package/README.en.md

@@ -1,5 +1,7 @@
 # dsh-data-cleaning-agent
 
+> 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.
 
 Install a pinned release using the command in the [Chinese quick start](README.md), review the preview or evidence before confirming, and keep the previous version and task-directory backup for rollback. Qichacha calls use the customer's authorized account.
@@ -8,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.8.23** (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.
 
@@ -70,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,5 +1,7 @@
 # dsh-data-cleaning-agent
 
+> 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)。
 
 ## 安装与三分钟上手
@@ -7,7 +9,7 @@
 数据清洗补全智能体：面向 Excel/CSV/JSON 企业名单，提供数据清洗、表格清洗、清洗补全、去重、企业数据补全与字段补全，支持企查查 MCP 和结果导出。
 
 ```sh
-dsh plugin --profile web add dsh-data-cleaning-agent@0.8.23
+dsh plugin --profile web add dsh-data-cleaning-agent@0.9.1
 ```
 
 请先满足下文的 DSH、连接器及侧边栏依赖要求；安装后完整停止并重启对应 Profile。
@@ -25,7 +27,7 @@ dsh plugin --profile web add dsh-data-cleaning-agent@0.8.23
 
 > 在 DeepSeek Harness 中清洗、补全、画像企业名单数据的智能体插件：本地 CSV/XLSX/JSON 引擎 + 可选企查查（Qichacha/QCC）MCP 企业数据补全，由企查查（Qichacha/QCC）团队发起并维护。
 >
-> 当前源码版本 / Current source version: **0.8.23**（正式版本）
+> 当前源码版本 / Current source version: **0.9.1**（正式版本）
 
 本版上传表格后展示完整清单及空白数量，用绿色、琥珀色、红色及文字区分已通过、待确认和未匹配映射。已映射字段自动纳入补全范围，额外字段默认折叠；多个原列可经确认使用同一非主体字段，分别补空并保留非空原值。修复 Host 草稿重置为默认五字段的问题，增加前后端版本错配提示。生成说明不查询，发送才执行；升级后需完整重启 DSH，历史下载文件不自动改写。
 
@@ -79,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

@@ -1,8 +1,30 @@
 # 兼容性 / Compatibility
 
-## 1. 目标基线
+## 0.9.0：Session 单例 Tab
 
-本插件面向 DeepSeek Harness（DSH）预发布阶段，双基线验证：
+工作台通过可选 `ctx.inject(['betterSidebar'], ...)` 接入 Provider，探测 `targetedOpen` 与 `stateSubscription`；缺失时保留会话和 Host 工具，不提供私有抽屉回退。当前仅完成隔离模拟服务与 Chromium 回归，尚未实装组合验收；旧版本的 Host/UI 验证不自动覆盖此次迁移。详见 [采用记录](UI-V1.5.0-ADOPTION.md)。
+
+## 当前加固目标（2026-09-10）
+
+完整 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/docs/UI-V1.5.0-ADOPTION.md

@@ -0,0 +1,43 @@
+# v1.5.0 统一侧拉采用记录（0.9.0 采用记录）
+
+开发基线 main / 623408e（0.8.23）。2026-09-10 用户授权推进 commit、push、tag 和 npm 发布，本次版本为 0.9.0；不包含市场条目更新。
+
+已完整阅读规范第 7、13.4、14、15、15.1 节，并检查配套 Mockup 的 Session 单例、历史同 Tab 和宿主管理几何语义。
+
+## 主链路与采用范围
+
+- lib/client.js 不再注册 shell.overlay 工作台。移除固定抽屉、拖拽分隔条、width/expanded 状态、容器展开/关闭按钮、全局 resize 与中央会话 padding/位移逻辑。
+- WorkbenchContent 只渲染当前任务、五阶段、任务历史和结果操作。Header 由 Host Tab 提供；业务状态集中在任务进度卡。窄栏采用容器查询，不依赖浏览器窗口宽度判断布局。
+- lib/better-sidebar-adapter.js 注册稳定命名空间 id：dsh-data-cleaning-agent:workbench，single:true。显式传入 Session scope；五个快捷入口、Header 恢复、执行进度自动打开均经过同一 adapter。
+- 插件级控制器按 Session 保存独立业务 store，Tab 只是视图。关闭/隐藏 Tab 不删除、取消或重跑 Host 任务；重新打开恢复原数据和内部视图。读取已有任务绑定不再隐式新建任务。
+- 跨作用域事件由一个带引用计数的控制器接收，提示词准备/OCR/数据暂存无需先挂载 Tab。跨 Session 不共用业务 store；非前台 Session reveal 等待订阅切换后消费，不挤占当前会话布局。
+- 使用可选 ctx.inject(['betterSidebar'], ...) 子生命周期，避免访问未授予的 Cordis 服务；Provider 缺失或移除不卸载业务控制器、会话入口和 Host 工具。
+- 缺依赖/过旧契约/Tab 禁用时显示可行动提示，无旧抽屉回退。Provider 卸载释放描述符和状态订阅；插件卸载移除事件监听、pending intent 和本地命令观察，Host 任务不受影响。
+- 任务、规则、字段目录、OCR、MCP 和制品后端契约未重写。
+
+## 接口与构建边界
+
+探测 registerTab/openTab/isTabEnabled/getSnapshot/subscribeState 和 targetedOpen/stateSubscription。
+type-only openTab 后通过该 Tab 的公开 store.reduce reveal 所在右侧/底部容器；浮窗不变更几何。
+未使用 tabLifecycle，所以没有依赖该能力。
+
+参考类型：本地 Better Sidebar 0.17.1 的 service 声明及 Cordis 4.0.1 的 inject/Fiber 生命周期。
+不据此宣称其他 Provider 版本或真实组合场景已经验收。
+
+现有 ModuleLoader 为单文件 CJS 工厂：scripts/sync-sidebar-adapter.mjs 将被测试的 adapter 嵌入 client.js。
+修改 adapter 后运行 node scripts/sync-sidebar-adapter.mjs --write；静态测试校验嵌入内容一致，防止源码与运行代码漂移。
+
+## 本地验证
+
+- npm run check：语法、文档、营销/打包门禁与完整 256 项测试通过。
+- npm run test:ui：隔离 React/Chromium + 模拟 Better Sidebar，10 组明暗主题/窗口尺寸；另外验证桌面 320px 与宽 Tab。
+- 浏览器覆盖：上传/替换失败保留旧数据、映射搜索和重复列、表格横向滚动和固定表头、提示词准备、执行后自动打开、结果制品操作、Tab 关闭重开、宿主折叠恢复、Session 离开与普通会话隔离。
+- 单元/静态覆盖：单例注册和入口幂等、Session store 隔离、inactive pending reveal、底部/浮窗 reveal、依赖缺失/过旧/禁用、Provider 到达/移除、重复卸载幂等、无固定几何/中央让位、无任务取消删除副作用。
+- 证据：_scratch/ui-layout/results.json 与同目录截图（本地夹具产物，不进入 npm）。
+- 没有调用真实 QCC，不消耗用户额度；没有覆盖上传源文件。
+
+## 真实 DSH 验收限制与发布门
+
+本轮未替换运行中 3080 Profile，未进行真实 DSH + Better Sidebar 或四插件共存安装验收。
+真实侧栏生命周期、底部停靠/浮窗、四插件切换、Host 动态移除 Provider、实际 OCR/授权链路需在隔离 Profile 联调。
+本地 UI 模拟通过不等于真实 Provider 验收；用户已授权在上述已知限制下发布 0.9.0；真实组合联调仍需补做，不将发布成功视为联调通过。

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/better-sidebar-adapter.js

@@ -0,0 +1,76 @@
+/** Public Better Sidebar seam. No business task creation, cancellation or geometry. */
+export const CLEANING_TAB_ID = 'dsh-data-cleaning-agent:workbench';
+export const SIDEBAR_DEPENDENCY_MESSAGE = '请安装或升级兼容的 dsh-better-sidebar 并重启 DSH（需要 targetedOpen 和 stateSubscription 能力），然后重新点击流程按钮。现有任务和文件不会删除。';
+
+export function sidebarCompatibility(service) {
+  const methods = ['registerTab', 'openTab', 'isTabEnabled', 'getSnapshot', 'subscribeState'];
+  return Boolean(service && methods.every(key => typeof service[key] === 'function')
+    && ['targetedOpen', 'stateSubscription'].every(key => service.features?.includes(key)));
+}
+
+function contains(node, id) {
+  if (!node) return false;
+  return node.kind === 'leaf' ? node.tabs.some(tab => tab.id === id)
+    : node.children.some(child => contains(child, id));
+}
+
+export function revealCleaningTab(state, id) {
+  if (state.floats?.some(item => item.tab.id === id)) return state;
+  if (contains(state.bottomSplits, id)) return state.bottomOpen ? state : { ...state, bottomOpen: true };
+  if (contains(state.splits, id)) return state.panelOpen ? state : { ...state, panelOpen: true };
+  return state;
+}
+
+/** One adapter per plugin activation. Session navigation survives closing its Tab. */
+export function createCleaningSidebarAdapter(service, { component, icon, onUnavailable = () => {} }) {
+  const targets = new Map();
+  const destinations = new Map();
+  const pending = new Set();
+  let disposed = false;
+  const compatible = sidebarCompatibility(service);
+  const applyPending = sessionId => {
+    if (disposed || service.getSnapshot().sessionId !== sessionId || !pending.has(sessionId)) return;
+    const target = targets.get(sessionId);
+    if (!target) return;
+    pending.delete(sessionId);
+    target.navigate(destinations.get(sessionId));
+    target.store.reduce(state => revealCleaningTab(state, target.tabId));
+  };
+  const unregister = compatible ? service.registerTab({
+    id: CLEANING_TAB_ID, title: '数据清洗补全', icon, order: 30, single: true, component,
+  }) : () => {};
+  const unsubscribe = compatible ? service.subscribeState(() => {
+    const sessionId = service.getSnapshot().sessionId;
+    if (sessionId) applyPending(sessionId);
+  }) : () => {};
+  return {
+    compatible,
+    open(scope, destination = 'upload') {
+      if (disposed) return false;
+      if (!compatible || !service.isTabEnabled(CLEANING_TAB_ID)) {
+        onUnavailable(compatible ? '请在 Better Sidebar 设置中启用「数据清洗补全」Tab。' : SIDEBAR_DEPENDENCY_MESSAGE);
+        return false;
+      }
+      if (!scope?.sessionId) throw new Error('A target Session is required');
+      destinations.set(scope.sessionId, destination);
+      pending.add(scope.sessionId);
+      service.openTab({ type: CLEANING_TAB_ID }, scope);
+      applyPending(scope.sessionId);
+      return true;
+    },
+    attach(scope, target) {
+      if (disposed) return () => {};
+      targets.set(scope.sessionId, target);
+      // Without a pending shortcut, preserve the Session business store's current view.
+      // Closing/reopening a Tab must not rewind an in-progress task to an older shortcut.
+      applyPending(scope.sessionId);
+      return () => { if (targets.get(scope.sessionId) === target) targets.delete(scope.sessionId); };
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      unsubscribe(); unregister();
+      targets.clear(); pending.clear(); destinations.clear();
+    },
+  };
+}