dsh-data-cleaning-agent 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,52 @@
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-04
+
+### Added
+- 启动 v2 五步工作流：上传数据、规则确认、数据匹配、清洗补全、下载数据；新增共享字段目录、
+  映射锚点和可审计匹配状态契约。
+- 新增 `dc_workflows_v2` Host 元数据存储与同源 `/data-cleaning/api/workflow/*` API，支持 taskId
+  隔离、revision 并发保护、任务恢复及阶段推进。
+- 上传/粘贴解析、数据预览、自动字段映射、任务目标、匹配规则与字段选择正式接入 taskId 工作流；
+  规则确认后自动生成本地质量体检并推进匹配阶段。
+- 提示词生成器升级为数据来源、匹配规则、清洗与补全、确认描述四步向导，并把解析数据和任务草稿
+  通过会话事件桥安全传入同一 Host 任务。
+- 增加中央七阶段业务首页、最近任务恢复、输入框下五能力入口，以及 taskId 驱动的右侧五步工作台。
+- 新增 Host 耐久制品层：每个任务生成清洗补全结果与异常清单的 CSV/XLSX 四个文件，提供列表、生成、
+  checksum 校验下载 API；XLSX 为可由 Excel/SheetJS 读取的真实工作簿。
+- 新增 v2 升级/迁移/回滚说明和 T6～T9 双基线、视觉、恢复及发布准备验收文档。
+
+### Changed
+- Client 原始数据按 taskId 隔离，不再使用跨任务模块级共享 session；同一会话并发创建与写操作分别
+  通过 coalescing 和串行队列避免重复任务及 revision 冲突。
+- 当前基础企业匹配、补全、预览和 CSV 下载复用 G5 Host Bridge，并保留零调用估算、客户自带 QCC
+  账号确认、幂等键与调用上限门。
+- 下载页改为读取 Host 四类耐久制品；已经完成的历史任务无需恢复浏览器原始行即可跨 Host 重启下载。
+- 本地确定性清洗可从规则确认/质量体检直接进入 `export_ready`，不会为零 QCC 调用强造匹配步骤。
+
+### Fixed
+- 修复中央业务首页条件调用组件导致真实 DSH 页面出现 React #310 的 Hooks 顺序问题。
+- 修复提示词数据集与任务草稿事件并发时可能创建两个 Host taskId 的竞态。
+- 修复规则按钮文案承诺“运行质量体检”但只切换页面的问题；现在规则确认后立即生成并持久化摘要。
+- 修复 `partial` 任务在显式重试后无新候选时走入非法匹配状态的问题；现在可继续补全并回到
+  `export_ready`。
+- 修复从中央首页最近任务打开工作台时只传阶段、未携带 taskId，导致误创建新草稿的问题。
+
+### Verified
+- `npm test` 165/165 通过；DSH `0.1.1-rc.2` 隔离 Host 43182 实际渲染 T3～T5，并完成
+  2 行 CSV 的上传、自动映射、规则确认与质量体检，任务达到 `diagnosed / match`。
+- 最新 tarball 在 rc.2（43190）与 alpha.2（43191）均完成四类制品创建、真实 XLSX 反向解析和
+  跨 Host 重启恢复；rc.2 完成浅色、深色和 820×900 窄屏视觉回归。未执行真实 QCC 调用。
+
+### Security
+- v2 Host KV 只保存任务元数据、数字汇总和制品引用，不持久化原始企业名单、候选详情、QCC 原始响应或凭据。
+- 工作流契约和任务元数据 API 不执行 QCC 工具；真实补全继续受零调用估算、用户付费确认、幂等键和调用上限保护。
+- 制品 ID 与路径严格校验，文件名去除控制字符，单制品限 32 MiB；下载前验证 SHA-256，运行制品目录
+  已从 Git 和 npm 包排除。
+- CSV 导出会中和以 `= + - @` 开头的外部文本，防止 Excel/LibreOffice 公式注入；XLSX Base64
+  读取上限覆盖编码后的 4/3 体积膨胀，解码后仍执行 32 MiB 硬限制。
+
 ## [0.5.3] - 2026-09-03
 
 > UI 二次对齐版本；不改变 Host/QCC 工具契约或计费安全门。

package/README.en.md

@@ -2,7 +2,7 @@
 
 > 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.5.3** (stable release)
+> Current source version / 当前源码版本: **0.6.0** (stable release)
 
 [![CI](https://github.com/duhu2000/dsh-data-cleaning-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/duhu2000/dsh-data-cleaning-agent/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/dsh-data-cleaning-agent)](https://www.npmjs.com/package/dsh-data-cleaning-agent)
@@ -46,7 +46,8 @@ near the top of the sidebar. It opens a dedicated native DSH session with a busi
 product/workflow introduction, and a prompt builder at the upper-left of the composer. The builder
 accepts pasted entities, locally parsed spreadsheet data, or image attachments and writes an editable
 task brief back to the native composer. Five workflow actions (upload, profile, match, enrich, history)
-sit below the composer and open the four-step workbench on demand.
+sit below the composer and open the five-step workbench (upload, rules, match, enrich, download)
+on demand. Completed tasks expose four durable Host artifacts: result and exception-list CSV/XLSX.
 
 Without the `dsh` CLI, use the install script:
 
@@ -68,6 +69,8 @@ Or let an agent install it for you:
 | Parse | web `/data-cleaning/api/mvp/parse` | CSV / XLSX / JSON |
 | Async jobs | web `/data-cleaning/api/mvp/jobs` | job state machine + persistent storage |
 | UI | web `/data-cleaning/` | upload → clean/complete → export |
+| Five-step tasks | web `/data-cleaning/api/workflow/*` | taskId/revision, rules, match, enrich, recovery, and state audit |
+| Durable artifacts | Host workspace `.dsh-data-cleaning-artifacts/v1` | result/exception CSV+XLSX, checksum verification, restart-safe download |
 | In-app entry | top "Data Cleaning & Completion" entry + five actions below the composer | dedicated business home in the center; opens the Mockup-aligned workbench on demand |
 | Prompt builder | `conversation.input.overlay` | text / spreadsheet / image intake, cleaning and enrichment selection, editable native-composer draft |
 | Tool cards | `tool.call.toolview` (`data_clean_rows`/`data_complete_rows`/`data_profile`) | render clean/complete/profile result cards in-conversation with running/done/failed state |
@@ -76,7 +79,7 @@ Or let an agent install it for you:
 | QCC Skill enrichment | `enterprise-enrichment` | 0.4.0: company panorama, ownership, governance, and historical registration |
 | 0.4.0 preflight | web `/data-cleaning/api/phase2/capabilities` | Read-only 16+4 dynamic-tool check; makes no QCC or paid calls |
 | QCC Host Bridge | web `/data-cleaning/api/g5/*` | 0.4.0: real OAuth/QCC path, natural-expiry refresh, and fault injection verified |
-| Three-domain enrichment | web `/data-cleaning/api/phase3/*` | 0.5.0: risk 38 + IPR 18 + operation 35, zero-call estimate, user-owned QCC quota confirmation, candidate review, recovery/retry, and two CSV exports |
+| Three-domain enrichment | web `/data-cleaning/api/phase3/*` | 0.5.0: risk 38 + IPR 18 + operation 35, zero-call estimate, user-owned QCC quota confirmation, candidate review, recovery/retry, and two CSV exports (no domain expansion in 0.6.0) |
 
 ## Qichacha MCP enrichment (status and roadmap)
 
@@ -112,6 +115,8 @@ See [the Phase-3 acceptance record](docs/PHASE3-ACCEPTANCE.md) and
 See [the 0.5.1 release record](docs/RELEASE-0.5.1.md) for the README fix and release-text gate.
 See [the 0.5.2 release record](docs/RELEASE-0.5.2.md) for native DSH UI alignment, verification, and rollback.
 See [the 0.5.3 release record](docs/RELEASE-0.5.3.md) for the business landing view and prompt builder.
+See [the 0.6.0 release record](docs/RELEASE-0.6.0.md) for the taskId workflow, durable artifacts,
+restart recovery, and dual-baseline validation.
 
 See [docs/PLAN-OSS.md](docs/PLAN-OSS.md) for details.
 

package/README.md

@@ -2,7 +2,7 @@
 
 > 在 DeepSeek Harness 中清洗、补全、画像企业名单数据的智能体插件：本地 CSV/XLSX/JSON 引擎 + 可选企查查（Qichacha/QCC）MCP 企业数据补全，由企查查（Qichacha/QCC）团队发起并维护。
 >
-> 当前源码版本 / Current source version: **0.5.3**（正式版本）
+> 当前源码版本 / Current source version: **0.6.0**（正式版本）
 
 [![CI](https://github.com/duhu2000/dsh-data-cleaning-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/duhu2000/dsh-data-cleaning-agent/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/dsh-data-cleaning-agent)](https://www.npmjs.com/package/dsh-data-cleaning-agent)
@@ -39,7 +39,8 @@ dsh plugin --profile web add dsh-data-cleaning-agent
 重启后，「数据清洗补全」入口会显示在侧边栏顶部的「新会话」与「工作区」之间。点击后打开专属的
 DSH 原生会话：首页标题、产品说明与工作流会替换通用探索页；输入框左上角提供提示词生成器，支持
 粘贴名单、解析 Excel/CSV/JSON 或附加图片并选择清洗动作、补全字段。上传清洗、质量体检、匹配核验、
-字段补全和任务历史五个入口位于输入框下方，右侧工作台承载完整四步闭环。
+字段补全和任务历史五个入口位于输入框下方，右侧工作台承载“上传数据 → 规则确认 → 数据匹配 →
+清洗补全 → 下载数据”五步闭环。完成后可下载结果与异常清单的 CSV/XLSX 四类 Host 耐久制品。
 
 没有 `dsh` CLI 时，也可以用安装脚本：
 
@@ -61,6 +62,8 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
 | 解析 | web `/data-cleaning/api/mvp/parse` | CSV / XLSX / JSON |
 | 异步任务 | web `/data-cleaning/api/mvp/jobs` | 任务状态机 + 持久化存储 |
 | UI | web `/data-cleaning/` | 上传 → 清洗/补全 → 导出 |
+| 五步任务 | web `/data-cleaning/api/workflow/*` | taskId/revision、规则、匹配、补全、恢复与状态审计 |
+| 耐久制品 | Host 工作区 `.dsh-data-cleaning-artifacts/v1` | 结果/异常 CSV+XLSX，checksum 校验，跨 Host 重启下载 |
 | 应用内入口 | 侧栏顶部「数据清洗补全」+ 输入框下方五能力按钮 | 中央业务首页与原生对话，右侧按需打开 Mockup 对齐工作台 |
 | 提示词生成 | `conversation.input.overlay` | 文本 / Excel / 图片录入、清洗项与补全维度选择，生成后回填原生输入框供人工修改 |
 | 工具卡片 | `tool.call.toolview`（`data_clean_rows`/`data_complete_rows`/`data_profile`） | 对话内渲染清洗/补全/画像结果卡，含运行/已完成/失败状态 |
@@ -69,7 +72,7 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
 | 企查查 Skill 补全 | `enterprise-enrichment` | 0.4.0：工商全景、股权穿透与历史工商 |
 | 0.4.0 工具预检 | web `/data-cleaning/api/phase2/capabilities` | 只读检查 16+4 动态工具，不发起 QCC/付费调用 |
 | QCC Host Bridge | web `/data-cleaning/api/g5/*` | 0.4.0：后台批量基础层；真实 OAuth/QCC 主路径、自然到期刷新与故障注入均已验收 |
-| 三域补全 | web `/data-cleaning/api/phase3/*` | 0.5.0：风险 38 + 知产 18 + 经营 35；零调用估算、显式付费确认、候选复核、恢复/重试与双 CSV 导出 |
+| 三域补全 | web `/data-cleaning/api/phase3/*` | 0.5.0：风险 38 + 知产 18 + 经营 35；零调用估算、显式付费确认、候选复核、恢复/重试与双 CSV 导出（当前按用户要求暂不扩展工具域） |
 
 ## 企查查 MCP 补全（状态与路线图）
 
@@ -108,6 +111,8 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
 0.5.1 文档补丁与防回归发布门见 [docs/RELEASE-0.5.1.md](docs/RELEASE-0.5.1.md)。
 0.5.2 DSH 原生 UI 对齐范围、验收与回滚见 [docs/RELEASE-0.5.2.md](docs/RELEASE-0.5.2.md)。
 0.5.3 业务首页、提示词生成和输入框下方流程栏见 [docs/RELEASE-0.5.3.md](docs/RELEASE-0.5.3.md)。
+0.6.0 五步 taskId 工作流、耐久制品、跨重启恢复与双基线验收见
+[docs/RELEASE-0.6.0.md](docs/RELEASE-0.6.0.md)。
 
 ## 本地开发
 

package/docs/COMPATIBILITY.md

@@ -33,6 +33,11 @@ MVP 路由、Phase-3 capabilities、estimate 与未确认 enrich 阻断均通过
 `conversation.createDraftImages` / `input.shell(sessionId).addImages` 做运行时探测，视为隔离兼容层，
 不承诺 alpha 实验面稳定。
 
+2026-09-04 的未发布 v2 工作流在 rc.2（43190）与 alpha.2（43191）完成最新本地 tarball
+隔离安装：两条基线均创建 `dc_workflows_v2` 任务与结果/异常 CSV+XLSX 四类制品，停止并重启 Host
+后可按原 taskId 下载，XLSX 反向解析工作表为“清洗补全结果”。稳定发布判断仍以 rc.2 为主，
+alpha.2 只作兼容探针。全程未触碰生产 43120，未调用 QCC。
+
 ## 2. Node 运行时
 
 - 本包 `engines.node` 声明 `>=20`。
@@ -59,7 +64,7 @@ MVP 路由、Phase-3 capabilities、estimate 与未确认 enrich 阻断均通过
 | --- | --- | --- |
 | 工具名前缀 | `qcc_oauth_*` + 规范 `mcp__qcc-*`；0.1.7 实测为 legacy `mcp__company__*` 等 | `data_clean_rows` / `data_complete_rows` / `data_profile` |
 | Skill | — | `data-cleaning`、`enterprise-enrichment` |
-| 存储域 | 自有 grant store | `dc_tasks_v1` |
+| 存储域 | 自有 grant store | `dc_tasks_v1` + `dc_workflows_v2` |
 | 能否共存 | ✅ | ✅（工具名 / Skill 名 / 存储域 / 条目 id 全独立） |
 
 - `enterprise-enrichment` Skill 本身**不重造 OAuth**：它只调用
@@ -102,9 +107,20 @@ Portal、原生会话、五能力按钮、跨 scope 状态桥、窄桌面布局
 插件只做运行时能力探测并保留 `sessions.create` 安全降级，不承诺 alpha 实验面稳定。Portal 失败时
 仍保留 footer 降级按钮。
 
-0.5.3 新增业务首页和提示词生成器，并把流程栏移出输入框。本地 tarball 已完成 rc.2 隔离
-Profile 装载与 Host 注册冒烟；受应用内浏览器本机 URL 策略限制，深浅色、窄屏和精确像素位置仍作为
-发布后人工观察项，当前单元测试与源码契约测试不能替代该视觉检查。
+0.5.3 新增业务首页和提示词生成器，并把流程栏移出输入框。当前未发布 v2 已在 rc.2 真实页面完成
+浅色、深色及 820×900 窄屏回归；窄屏页面无横向溢出，最近完成任务可恢复原 taskId 并显示四个
+Host 制品下载按钮。alpha.2 继续只检查 Host/路由/制品 Bridge，不作为精确视觉基线。
+
+### 4.4 未发布 v2 制品兼容面（2026-09-04）
+
+| 能力 | rc.2 | alpha.2 | 备注 |
+| --- | --- | --- | --- |
+| `dc_workflows_v2` schema 2 | ✅ | ✅ | taskId + revision；原始行不进入 KV |
+| `ctx.fs.writeText/readBytes` | ✅ | ✅ | 当前已验证的公共 Host seam |
+| 结果/异常 CSV | ✅ | ✅ | UTF-8 文本，工作区本地保存 |
+| 结果/异常 XLSX | ✅ | ✅ | Base64 over writeText；下载恢复真实 ZIP 字节 |
+| checksum / 跨重启下载 | ✅ | ✅ | SHA-256；同一 taskId/artifactId |
+| 深浅色/窄屏实际 UI | ✅ | 探针 | rc.2 为视觉基线，alpha.2 不作稳定视觉承诺 |
 
 ### 4.3 0.5.0 三域兼容面
 
@@ -127,3 +143,7 @@ Profile 装载与 Host 注册冒烟；受应用内浏览器本机 URL 策略限
 - `/data-cleaning/api/phase3/*` 为 0.5.0 已发布能力；单批最多 100 行、并发最多 4、默认/硬调用上限
   500/2000。run 只保留在 Host 内存 30 分钟，Host 重启不恢复。
 - alpha.2 的实际 UI 只作兼容探针；0.5.0 的稳定发布与回滚判断以 rc.2 为准。
+- v2 单制品上限 32 MiB、单次最多 100,000 行和 256 列；当前 Host 未验证稳定 `writeBytes`，
+  XLSX 因此以 Base64 文本落盘。未来切换二进制 seam 必须保留旧 `v1` 制品读取兼容。
+- v2 已生成制品可跨 Host 重启恢复，但浏览器 runtime 中尚未导出的原始行不会持久化；恢复中途任务
+  仍需用户重新提供输入。制品只在当前工作区，不承诺跨设备同步。

package/docs/RELEASE-0.5.3.md

@@ -2,9 +2,9 @@
 
 > 版本：**0.5.3**
 >
-> 状态：**正式版本；由 `v0.5.3` 标签触发 npm OIDC Trusted Publishing 与 GitHub Release。**
+> 状态：**✅ 已发布；npm `latest`、Git tag 与 GitHub Release 均为 `0.5.3`。**
 >
-> 发布日期：2026-09-03
+> 发布时间：2026-09-03T10:36:28Z
 
 ## 目标
 
@@ -52,8 +52,15 @@
 > 本轮应用内浏览器首次打开时已确认顶部菜单文案；隔离 Host 重启后，本机 URL 被浏览器安全策略阻止二次访问，
 > 因此标题、流程栏位置、弹层及深浅色/窄屏保留为发布后人工观察项，未用替代浏览器绕过。
 
+发布结果：
+
+- `v0.5.3` annotated tag 指向 `f7eac00`；Release workflow `33745170057` 全绿；
+- npm 公共 Registry 返回 `latest=0.5.3`，包含 38 个文件，SHA-1 为 `d349a593d8b45efc794456bf5854e4ec583ca70f`；
+- npm provenance predicate 为 SLSA v1；
+- GitHub Release 为非 draft、非 prerelease：https://github.com/duhu2000/dsh-data-cleaning-agent/releases/tag/v0.5.3 。
+
 ## 升级与回滚
 
-- 升级候选：安装本地 `npm pack` 产物并完全重启 DSH；不覆盖客户 OAuth grant 或 Key。
+- 升级：安装 `dsh-data-cleaning-agent@0.5.3` 并完全重启 DSH；不覆盖客户 OAuth grant 或 Key。
 - 回滚：重新安装 `dsh-data-cleaning-agent@0.5.2` 并完全重启 DSH。
 - 0.5.3 不修改 Host 路由、QCC 工具契约、存储 schema 或导出格式，回滚无需数据迁移。

package/docs/RELEASE-0.6.0.md

@@ -0,0 +1,46 @@
+# 0.6.0 五步工作流与耐久制品发布记录
+
+> 版本：**0.6.0**
+> 发布日期：2026-09-04
+> 发布来源：`v0.6.0` Tag 触发 GitHub Actions，使用 npm OIDC Trusted Publishing。
+
+## 目标
+
+0.6.0 将 0.5.3 的业务首页升级为可恢复的完整企业数据清洗补全系统：
+
+1. 主流程固定为上传数据、规则确认、数据匹配、清洗补全、下载数据五步；
+2. 每个会话绑定独立 taskId，并用 revision 防止并发覆盖；
+3. 上传解析、字段映射、质量体检、候选核验和补全状态统一进入 Host 工作流；
+4. 完成任务生成结果与异常清单的 CSV/XLSX 四类耐久制品；
+5. 浏览器原始行丢失或 Host 重启后，仍可按 taskId 恢复任务并下载既有制品。
+
+## 兼容与安全
+
+- 稳定发布基线为 DSH `0.1.1-rc.2`；`0.1.2-alpha.2` 只作兼容探针。
+- Host KV 只保存任务元数据、数字摘要和制品引用，不保存原始企业名单、候选详情、QCC 原始响应或凭据。
+- 制品写入用户工作区 `.dsh-data-cleaning-artifacts/v1/`，不进入 Git 或 npm 包。
+- 下载前验证 SHA-256；路径和 ID 严格校验；CSV 中和公式型外部文本。
+- QCC 继续采用 BYO 账号：客户使用自己的企查查 MCP 连接与额度，插件不共享 Key、不代付。
+- 历史域、人员域和招投标域仍不进入本版本新增范围。
+
+## 验收证据
+
+- `npm run check` 全绿，165/165 自动测试通过；
+- npm dry-run 包 45 个文件全部命中白名单；
+- rc.2（43190）和 alpha.2（43191）均完成四类制品生成、真实 XLSX 反向解析和跨 Host 重启恢复；
+- rc.2 完成浅色、深色和 820×900 窄屏真实页面回归，无页面横向溢出；
+- 最近任务恢复显示原 taskId 和四个下载按钮，不会误创建新草稿；
+- 未触碰生产端口 43120，未执行新的真实 QCC 调用。
+
+## 升级与回滚
+
+- 升级：安装 `dsh-data-cleaning-agent@0.6.0` 并完全重启 DSH。
+- 回滚：重新安装 `dsh-data-cleaning-agent@0.5.3` 并完全重启 DSH。
+- 回滚不会删除 `dc_workflows_v2` 或工作区制品；0.5.3 会忽略这些新增数据。
+- 完整说明见 `docs/UI-WORKFLOW-V2-MIGRATION.md`。
+
+## 外部发布核验
+
+Tag 推送后必须确认 Release workflow 全绿、npm `latest=0.6.0`、provenance 存在、GitHub Release
+非 draft/非 prerelease，并从公共 Registry 在全新隔离 Profile 安装验证。实际 workflow run、tarball
+哈希与公共安装结果在发布完成后的仓库进度记录中补充。

package/docs/UI-WORKFLOW-V2-ACCEPTANCE.md

@@ -0,0 +1,84 @@
+# 数据清洗补全 v2 · T6～T9 验收与发布准备
+
+> 验收日期：2026-09-04
+> 分支：`feat/ui-workflow-v2`，基线 `main@0be4de3`
+> 状态：本地开发与验收完成，作为 `0.6.0` 发布门；本文不替代 npm/GitHub 外部发布核验。
+
+## 1. 验收范围
+
+| 任务 | 交付 | 结论 |
+| --- | --- | --- |
+| T6 | Host 耐久制品、真实 XLSX、异常清单、双基线、视觉回归、迁移/回滚 | 通过 |
+| T7 | 匹配摘要、候选人工核验、部分失败显式重试、补全后导出 | 通过 |
+| T8 | 四类制品下载、taskId 历史恢复、跨 Host 重启下载 | 通过 |
+| T9 | 自动化门禁、tarball 白名单、兼容与发布决策 | 通过；版本确定为 0.6.0 |
+
+## 2. T6 制品契约
+
+每个完成任务生成四个工作区本地制品：
+
+1. 清洗补全结果 CSV；
+2. 清洗补全结果 XLSX；
+3. 异常清单 CSV；
+4. 异常清单 XLSX。
+
+DSH rc.2 / alpha.2 当前验证的 `ctx.fs` 只公开 `writeText` 与 `readBytes`，未验证稳定的二进制写接口。
+因此 CSV 以 UTF-8 文本保存，真实 XLSX 字节以 Base64 文本保存，下载时解码并校验 SHA-256。该策略被
+隔离在 `lib/artifacts.js`，以后 Host 提供稳定 `writeBytes` 时可只替换适配层。
+
+限制：单制品最大 32 MiB、单次最多 100,000 行、最多 256 列。制品目录是
+`.dsh-data-cleaning-artifacts/v1/<taskId>/`，已加入 Git 忽略规则，不进入 npm 包。
+CSV 会中和公式型外部文本；XLSX Base64 的读取上限按编码膨胀计算，解码后仍执行 32 MiB 硬限制。
+
+## 3. 双基线跨重启实测
+
+| DSH | 隔离端口 | 初次运行 | 重启恢复 | XLSX |
+| --- | ---: | --- | --- | --- |
+| `0.1.1-rc.2` | 43190 | seam、任务、四制品通过 | 同一 taskId/制品通过 | ZIP magic `PK`；工作表“清洗补全结果” |
+| `0.1.2-alpha.2` | 43191 | seam、任务、四制品通过 | 同一 taskId/制品通过 | ZIP magic `PK`；工作表“清洗补全结果” |
+
+实测使用合成的两行数据和隔离 Profile；未触碰生产端口 `43120`，未调用 QCC，未产生企查查费用。
+
+## 4. T7 匹配与补全闭环
+
+- 字段映射必须包含企业名称、统一社会信用代码或注册号之一。
+- `exact / candidate / confirmed / unresolved / failed` 数量受总数约束，不显示无来源置信度。
+- 多候选进入人工核验；`partial` 可显式重试并回到 `export_ready`。
+- QCC 估算为零调用；真正执行前仍要求 `confirmPaidCalls:true`、幂等键与调用上限。
+- 用户使用自己连接的 QCC MCP 账号并承担其账号额度/费用；插件不共享 Key、不代付。
+
+## 5. T8 恢复与下载
+
+- 最近任务入口会把完整 taskId 注入工作台，不会误创建新草稿。
+- 已完成任务即使浏览器 runtime 中没有原始行，也能从 Host 读取四类制品并下载。
+- 下载响应使用固定同源路由、受控文件名、内容类型、长度与 `nosniff`，读取时验证 checksum。
+- v2 不再登记 `browser-download:` 伪引用。
+
+## 6. 视觉回归
+
+真实 rc.2 页面已验证：
+
+- 浅色桌面：首页、原生 Composer、输入框下五能力、右侧非模态工作台位置正确；
+- 深色：首页、按钮、五步状态、下载制品信息可读；
+- 820×900 窄屏：`scrollWidth === viewport width`，页面无横向溢出；右栏按窄屏安全覆盖中央内容；
+- 完成任务恢复后显示原 taskId、输入行数及四个下载按钮。
+
+## 7. 自动化与发布门
+
+发布候选必须同时满足：
+
+```bash
+npm run check
+git diff --check
+npm pack --dry-run --json --cache .npm-cache
+```
+
+并复核 tarball 不包含测试、OAuth/Key、真实名单、QCC 原始响应、`.dsh-data-cleaning-artifacts/` 或
+`_scratch/`。2026-09-04 最新本地门禁结果为 `npm run check` 全绿、165/165 测试通过、npm tarball
+44 个文件全部命中白名单，`git diff --check` 无错误。
+
+## 8. 版本决策与剩余发布动作
+
+版本确定为 **0.6.0**，原因是新增 Host 工作流 API、持久化 domain、耐久制品和完整五步业务流程。
+发布按顺序执行：最终代码审查 → 版本/README/Changelog 快照 → commit/push → Tag → OIDC npm 发布 →
+GitHub Release → 公共 Registry 全新安装。验收记录本身不等于外部平台已经完成发布。

package/docs/UI-WORKFLOW-V2-MIGRATION.md

@@ -0,0 +1,62 @@
+# 数据清洗补全 v2 · 升级、迁移与回滚
+
+> 适用对象：从已发布 `0.5.3` 升级到 `0.6.0` 五步工作流版本。
+> 外部发布状态以 `docs/RELEASE-0.6.0.md` 和 npm/GitHub 为准。
+
+## 1. 为什么建议使用 0.6.0
+
+本次变更不是单纯视觉补丁：新增五步 taskId 工作流、Host 持久化元数据、耐久 CSV/XLSX 制品、
+异常清单以及任务恢复 API。旧功能继续可用，但公开的同源 Host 能力和用户任务生命周期都有实质新增，
+因此按语义化版本建议使用次版本 `0.6.0`，而不是 `0.5.4`。
+
+## 2. 升级前检查
+
+1. 记录当前 DSH Profile、插件版本和回滚目标；稳定基线使用 DSH `0.1.1-rc.2`。
+2. 完成当前任务并下载需要保留的文件；`0.5.3` 的浏览器下载引用不能迁移成 Host 制品。
+3. 确认工作区可写。v2 制品写入工作区 `.dsh-data-cleaning-artifacts/v1/`。
+4. 备份 DSH Profile 和工作区；不要复制 OAuth token、Key 或 QCC 原始响应到源码仓库。
+5. 在隔离 Profile 安装候选 tarball并运行验收，再更新日常使用的 Profile。
+
+## 3. 数据迁移行为
+
+| 数据 | 升级行为 | 回滚行为 |
+| --- | --- | --- |
+| `dc_tasks_v1` 旧异步任务 | 原样保留 | 原样可用 |
+| `dc_workflows_v2` 任务元数据 | 新版本按 schema 2 增量创建 | 0.5.3 忽略，不删除 |
+| `.dsh-data-cleaning-artifacts/v1` | 新版本创建并校验 SHA-256 | 0.5.3 忽略，文件保留 |
+| 浏览器 runtime 原始行 | 不迁移、不写入 Host KV | 回滚后仍不可恢复 |
+| QCC OAuth / Key | 不由本插件迁移或读取 | 由用户自己的 QCC MCP 连接管理 |
+
+v2 没有破坏性数据库迁移，也没有自动删除步骤。升级后首次打开任务时按 taskId 读取元数据；如果任务尚未
+生成 Host 制品，用户需要重新提供原始数据才能继续处理。已经生成的四类制品可跨 Host 重启下载。
+
+## 4. 隔离安装与验收
+
+以下命令中的 Profile 名称仅为示例，必须使用隔离 Profile，不得直接操作生产端口 `43120`：
+
+```bash
+npm pack --cache .npm-cache
+dsh plugin --profile data-cleaning-v2-test add ./dsh-data-cleaning-agent-0.6.0.tgz
+dsh web --profile data-cleaning-v2-test --port 43190
+```
+
+验收至少覆盖：创建任务、上传/映射、规则确认、匹配或本地清洗、生成四类制品、下载真实 XLSX、停止并
+重启 Host 后按同一 taskId 恢复。QCC 路径只有在用户自己的连接已授权且明确确认使用其账号额度时测试。
+
+## 5. 回滚
+
+若候选版本出现阻断问题，停止隔离 Host，并把插件切回已发布的 `0.5.3`：
+
+```bash
+dsh plugin --profile data-cleaning-v2-test add dsh-data-cleaning-agent@0.5.3
+```
+
+回滚不会删除 `dc_workflows_v2` 或 `.dsh-data-cleaning-artifacts/v1`。不要手工清空工作区；修复后重新升级
+即可继续读取同一批 v2 元数据和制品。0.5.3 无法显示 v2 五步任务属于预期降级，不是数据丢失。
+
+## 6. 前滚与兼容原则
+
+- schema 2 只做增量字段扩展；需要破坏性变化时必须新增 schema/domain 版本和显式迁移器。
+- 制品路径版本固定为 `v1`；格式变化必须创建新目录版本，不能原地重写旧文件。
+- `0.1.2-alpha.2` 只作兼容探针；发现差异时优先调整隔离 Bridge，不把实验 API变成稳定依赖。
+- 发布前必须通过 `npm run check`、双基线跨重启、深浅色/窄屏回归和 npm tarball 白名单。

package/docs/UI-WORKFLOW-V2.md

@@ -0,0 +1,174 @@
+# 数据清洗补全智能体 v2 · 工作流与 Host 契约
+
+> 状态：T0～T9 已完成实现与隔离验收，归入 `0.6.0`。
+> 开发基线：`main@0be4de3` / 已发布 `0.5.3`。
+> 本文记录实现契约；外部发布状态以 `docs/RELEASE-0.6.0.md` 和 npm/GitHub 为准。
+
+## 1. 产品主流程
+
+业务主流程与企查查专业版“数据清洗补全”一致，固定为五步：
+
+1. **上传数据**：文本、CSV、XLSX、JSON；图片入口需等待已验证的智能文档解析工具后接通。
+2. **规则确认**：字段映射、清洗目标、匹配规则、补全字段选择。
+3. **数据匹配**：以企业名称、统一社会信用代码或注册号作为主体锚点；精确、候选、已确认、未匹配、失败分流。
+4. **清洗补全**：本地确定性清洗优先；需要 QCC 数据时，先估算调用，再由当前用户确认使用自己的 QCC 账号额度。
+5. **下载数据**：生成 Host 制品引用，后续 UI 提供原始数据、清洗结果、补全结果与异常清单下载。
+
+任务设置（提示词生成）、质量体检和任务历史是横向能力，不占用五步编号。
+
+## 2. 当前范围
+
+当前字段目录：
+
+- 基础工商：企业名称、统一社会信用代码、注册号、组织机构代码、登记状态、法定代表人、注册/实缴资本、成立日期、企业类型、登记机关、曾用名、英文名。
+- 地址与联系方式：注册地址、省市区、电话、邮箱、官网。
+- 经营信息：经营范围、国标及一二级行业、营业期限、企业规模、企业简介。
+- 风险摘要、知识产权摘要：仅在 Host 能力探针确认对应 QCC 工具可用时开放。
+
+历史域、人员域、招投标域已明确延期，不进入当前实现或字段目录。
+
+## 3. 工作流状态
+
+正常路径：
+
+```text
+draft → uploaded → rules_confirmed → diagnosed(可选)
+      → matching → review_required(可选) → matched
+      → enriching → export_ready → completed
+```
+
+异常或暂停状态：`parse_failed`、`authorization_required`、`partial`、`failed`、`cancelled`。
+
+每次写入增加 `revision`。Client 必须带上最后读取的 `expectedRevision`，过期写入返回
+`409 DC_WORKFLOW_REVISION_CONFLICT`，防止两个会话互相覆盖。
+
+## 4. 字段映射与匹配契约
+
+- 至少映射一个主体锚点：`company_name`、`credit_no`、`reg_no`。
+- 同一目标字段不能被多个输入列重复映射。
+- 同一输入列不能重复映射到多个目标；未知目标字段按契约错误处理，不静默忽略。
+- 企业名称可以结合省份、地址、电话辅助人工核验，但辅助字段不能取代主体锚点。
+- 匹配结果只保存状态、数量汇总、运行引用和可审计依据；不得生成或展示无来源的置信度百分比。
+- 多候选必须进入 `review_required`；人工确认完成后才能进入补全。
+- `exact`、`candidate`、`confirmed`、`unresolved`、`failed` 是互斥数量，合计不得超过 `total`。
+
+契约实现位于 `lib/workflow-contract.js`，UI 应通过只读接口获取目录，避免在 Client 重复维护字段清单。
+
+## 5. Host 持久化与隐私边界
+
+`lib/workflow.js` 使用 DSH `storageDomain`：
+
+| 项 | 值 |
+| --- | --- |
+| domain | `dc_workflows_v2` |
+| domain version | `1` |
+| table | `tasks` |
+| record schema | `2` |
+
+允许持久化：任务标题、阶段/状态、输入文件元数据、表头、字段映射、选中字段、数字汇总、QCC run 引用、导出制品引用、时间和 revision。
+
+禁止持久化：原始数据行、企业名称清单、匹配候选详情、QCC 原始响应、OAuth token、Key、真实付费调用证据。
+
+原始数据行按 taskId 隔离在当前浏览器 runtime，Host KV 只保存来源元数据、映射、规则、质量/匹配/
+补全摘要和制品引用。导出时，Client 把最终结果行一次性提交给同源 Host 制品端点；Host 通过 `ctx.fs`
+写入工作区 `.dsh-data-cleaning-artifacts/v1/`。CSV 直接保存为 UTF-8，XLSX 保存为 Base64 文本并在下载
+时恢复真实字节；读取时验证 SHA-256。原始行不会进入 `storageDomain`。
+
+已完成任务可在浏览器 runtime 丢失原始行后，按 taskId 重新读取制品引用并跨 Host 重启下载；尚未生成
+制品的中途任务仍需用户重新上传输入。制品只保存在用户当前工作区，不跨设备同步。
+
+## 6. 同源 API
+
+所有接口继续使用回环同源守卫；以下接口不会调用 QCC，不产生费用：
+
+| 方法 | 路径 | 作用 |
+| --- | --- | --- |
+| GET | `/data-cleaning/api/workflow/contract` | 获取五步、状态、字段目录和隐私契约 |
+| GET | `/data-cleaning/api/workflow/tasks` | 任务列表 |
+| POST | `/data-cleaning/api/workflow/tasks` | 新建草稿 |
+| GET | `/data-cleaning/api/workflow/tasks/:id` | 按 taskId 恢复 |
+| PATCH | `/data-cleaning/api/workflow/tasks/:id` | 更新未锁定草稿 |
+| POST | `/data-cleaning/api/workflow/tasks/:id/actions/upload` | 记录上传元数据 |
+| POST | `/data-cleaning/api/workflow/tasks/:id/actions/rules` | 确认规则 |
+| POST | `/data-cleaning/api/workflow/tasks/:id/actions/quality` | 记录质量汇总 |
+| POST | `/data-cleaning/api/workflow/tasks/:id/actions/match-start` | 进入匹配中 |
+| POST | `/data-cleaning/api/workflow/tasks/:id/actions/match` | 记录匹配汇总 |
+| POST | `/data-cleaning/api/workflow/tasks/:id/actions/enrich-start` | 进入补全中 |
+| POST | `/data-cleaning/api/workflow/tasks/:id/actions/enrichment` | 记录补全汇总 |
+| POST | `/data-cleaning/api/workflow/tasks/:id/actions/local-export-ready` | 本地确定性流程进入可导出状态 |
+| GET | `/data-cleaning/api/workflow/tasks/:id/artifacts` | 列出已登记的 Host 耐久制品 |
+| POST | `/data-cleaning/api/workflow/tasks/:id/artifacts` | 生成结果/异常清单的 CSV 与 XLSX，并完成任务 |
+| GET | `/data-cleaning/api/workflow/tasks/:id/artifacts/:artifactId` | 校验 checksum 并下载制品 |
+| POST | `/data-cleaning/api/workflow/tasks/:id/actions/export` | 兼容记录已有制品引用并完成 |
+| POST | `/data-cleaning/api/workflow/tasks/:id/actions/parse-failed` | 记录解析失败（仅保存错误码） |
+| POST | `/data-cleaning/api/workflow/tasks/:id/actions/authorization-required` | 暂停并提示连接 QCC |
+| POST | `/data-cleaning/api/workflow/tasks/:id/actions/fail` | 记录失败（仅保存安全错误码） |
+| POST | `/data-cleaning/api/workflow/tasks/:id/actions/cancel` | 取消任务 |
+
+`/match` 与 `/enrichment` 记录的是已有执行结果摘要，不自行触发 QCC。后续编排器接入真实 QCC 时仍需沿用现有
+`estimate → confirmPaidCalls:true → idempotencyKey → maxCalls` 安全门。
+
+## 7. T0～T9 验收矩阵
+
+| 门 | 验收项 | 结论 |
+| --- | --- | --- |
+| T0 | 0.5.3 `main` 基线干净，建立 `feat/ui-workflow-v2` | 通过 |
+| T0 | 基线 `npm run check` | 138/138 通过 |
+| T1 | 五步、字段目录、映射锚点、状态转换、无虚构置信度 | 自动化覆盖 |
+| T2 | taskId 隔离、revision 并发保护、重启恢复 | 自动化覆盖 |
+| T2 | 原始行/企业名/候选/QCC 响应不进入 KV | 自动化覆盖 |
+| T2 | 同源守卫、无 storageDomain 降级、零 QCC 调用 | 自动化覆盖 |
+| T2 | DSH `0.1.1-rc.2` 真实 Host 写入与跨重启恢复 | 43180 隔离 Profile 通过 |
+| T3 | 上传/粘贴解析、数据预览、自动字段映射、任务目标、规则与字段选择全部绑定 taskId | 自动化 + rc.2 浏览器通过 |
+| T3 | 规则确认后自动质量体检并推进 `diagnosed / match` | revision 5 与质量摘要实测通过 |
+| T4 | 四步提示词向导：数据来源、匹配规则、清洗与补全、确认描述 | rc.2 浏览器通过 |
+| T4 | 文本/文件数据经事件桥进入同一任务，生成描述回填原生 Composer；并发创建收敛为单 taskId | 自动化覆盖 |
+| T5 | 中央七阶段业务首页、输入框下五能力入口、右侧五步工作台与最近任务恢复 | rc.2 浏览器通过 |
+| T5 | 当前基础企业 G5 匹配/补全、零调用估算、BYO-QCC 确认 | 自动化覆盖；未执行真实 QCC |
+| T6 | Host 四类耐久制品、真实 XLSX、异常清单、checksum 与安全路径 | 自动化 + 双基线通过 |
+| T6 | rc.2 / alpha.2 隔离安装、Host 重启恢复及真实 XLSX 反向解析 | 43190 / 43191 通过 |
+| T6 | rc.2 深色、浅色、820×900 窄屏无横向溢出 | 真实浏览器通过 |
+| T7 | 多候选人工核验、`partial` 显式重试、补全后回到 `export_ready` | 自动化覆盖 |
+| T8 | 最近任务携带原 taskId 恢复、无原始 runtime 行时下载四类 Host 制品 | 自动化 + rc.2 浏览器通过 |
+| T9 | 迁移/回滚、兼容矩阵、发布检查和版本决策 | 文档完成；建议 0.6.0，尚未发布 |
+
+### 真实 Host 证据（2026-09-03）
+
+- 将当前 41 文件 tarball 临时装入仓库内隔离 Profile，启动 DSH `0.1.1-rc.2` 于 `127.0.0.1:43180`。
+- `GET /workflow/contract` 返回 schema 2 和完整五步，明确 `executesTools:false`、`paidCalls:false`。
+- 新建测试任务后依次记录上传与规则确认，状态为 `rules_confirmed`、阶段为 `match`、revision 为 3。
+- 停止并重启 Host 后，使用同一 taskId 读回上述状态、映射和 revision，确认 `storageDomain` 跨进程恢复有效。
+- 测试 Host 已停止；隔离 Profile 的原插件目录已恢复。未触碰生产端口 `43120`，未安装/调用 QCC。
+
+### T3～T5 真实 UI 证据（2026-09-03）
+
+- 将最新本地 tarball 安装到隔离 DSH `0.1.1-rc.2` Profile，并启动于 `127.0.0.1:43182`。
+- 中央首页显示七阶段流程，五能力按钮位于原生 Composer 下方；右侧工作台显示 Host taskId 和五步状态。
+- 粘贴 2 行 CSV 后自动映射“企业名称”和“统一社会信用代码”，确认规则后自动生成质量报告。
+- Host 读回任务 `state=diagnosed`、`stage=match`、`revision=5`，`qualitySummary` 与页面统计一致。
+- 四步提示词向导在真实页面完整渲染；同一会话并发事件创建经 coalescing/队列保护后只生成一个任务。
+- 实测过程中未检测或调用 QCC，未使用真实企业数据；43182 隔离 Host 已停止。
+
+### T6～T9 真实 Host / UI 证据（2026-09-04）
+
+- 将最新本地 tarball 分别安装到隔离 DSH `0.1.1-rc.2`（43190）和
+  `0.1.2-alpha.2`（43191）Profile。
+- 两条基线均创建同一结构的完成任务和四类制品；XLSX 文件头为 `PK`，反向解析工作表为
+  “清洗补全结果”。停止并重启后按原 taskId 和 artifactId 下载仍通过。
+- rc.2 真实页面完成浅色、深色与 820×900 窄屏回归；窄屏 `scrollWidth` 与视口宽度相同。
+- 最近任务恢复实测显示原完成 taskId、输入行数和四个下载按钮，没有创建新草稿。
+- 全程使用合成数据，未触碰生产端口 43120，未连接或调用 QCC。
+
+## 8. 当前实现与发布顺序
+
+1. T3（完成）：上传解析、字段映射、任务设置和规则确认接入 v2 taskId API。
+2. T4（完成）：提示词生成器四步向导接入 taskId 工作流，支持文本/本地文件/图片 Bridge。
+3. T5（完成）：中央业务首页、五能力入口、右侧工作台、基础企业匹配/补全和任务历史统一到 taskId。
+4. T6（完成）：Host 耐久下载制品、XLSX 与异常清单、双基线、视觉回归、迁移与回滚。
+5. T7（完成）：候选人工核验、部分失败重试、匹配与补全状态闭环。
+6. T8（完成）：四类制品导出、最近任务恢复及跨 Host 重启下载。
+7. T9（发布准备完成）：建议下一版本使用 `0.6.0`；待最终代码审查与维护者另行批准 commit、push、
+   Tag、npm 和 GitHub Release。
+
+详细验收见 `docs/UI-WORKFLOW-V2-ACCEPTANCE.md`，升级/回滚见
+`docs/UI-WORKFLOW-V2-MIGRATION.md`。