dsh-data-cleaning-agent 0.5.2 → 0.6.0

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`。

package/docs/USER-GUIDE.md

@@ -24,14 +24,27 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
 
 插件会加载内嵌 Skill `data-cleaning`，自动按 `data_profile → data_clean_rows → data_complete_rows` 工作流调度。
 
-### 2.2 应用内入口（侧边栏「数据清洗」）
+### 2.2 应用内入口（侧边栏「数据清洗补全」）
 
-重启后，DeepSeek Harness 侧边栏底部会出现「数据清洗」按钮。点击打开全屏工作台，按四步操作：
+重启后，DeepSeek Harness 侧栏顶部的「新会话」与「工作区」之间会出现「数据清洗补全」。点击后先进入
+中央业务首页，右侧工作台保持关闭；输入框下方的五个入口分别定位到上传清洗、质量体检、匹配核验、
+字段补全和任务历史。处理步骤为：
 
-1. **上传与映射**：粘贴或上传 CSV / XLSX / JSON，确认企业名称字段；
-2. **数据体检**：查看列概览、缺失和金额分布；
-3. **匹配核验**：先做本地清洗，再选择风险/知产/经营域；多候选由人工确认；
-4. **补全与导出**：恢复任务、重试可重试失败，下载结果 CSV 和复核 CSV。
+1. **上传数据**：粘贴或上传 CSV / XLSX / JSON，预览列和行；
+2. **规则确认**：映射企业名称/统一社会信用代码/注册号，选择清洗目标与补全字段；
+3. **数据匹配**：运行质量体检与主体匹配，多候选由人工确认；
+4. **清洗补全**：执行本地确定性清洗；需要 QCC 时先零调用估算，再由当前用户确认使用自己的账号额度；
+5. **下载数据**：生成结果 CSV/XLSX 与异常清单 CSV/XLSX，后续可从任务历史恢复下载。
+
+输入框左上角的「提示词生成」提供三种名单录入方式：
+
+- **粘贴名单**：每行一个企业名称或统一社会信用代码；
+- **上传 Excel**：支持 XLSX/XLS/CSV/JSON，识别企业名称/信用代码列并把完整数据载入右侧工作台；
+- **上传图片**：把 PNG/JPEG/WebP 附加到当前原生对话，并生成“使用当前已连接且可用的企查查智能文档解析 MCP”要求。
+
+随后可选择名称规范、信用代码校验、去重、模糊候选复核等清洗动作，以及工商字段或已支持的维度组。
+点击「生成并回填」后，任务描述进入原生对话框；发送前仍可人工修改。图片能力不可用时，请改用输入框
+原生“＋”或文本/Excel。提示词生成器不会硬编码未验证的 QCC 工具名，也不会绕过付费确认门。
 
 模型在对话中调用 `data_clean_rows` / `data_complete_rows` / `data_profile` 时，
 对话内会渲染对应的工具结果卡片（含运行中 / 已完成 / 失败状态）；工作台头部用任务 pill
@@ -40,7 +53,8 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
 ### 2.3 web 界面
 
 打开 DeepSeek Harness 后访问插件的同源界面（`/data-cleaning/`），可上传 CSV/XLSX/JSON，
-执行解析、清洗、补全、导出 CSV。web 界面的后端路由前缀为 `/data-cleaning/api/mvp/*`。
+执行解析、清洗、补全与导出。旧 MVP 路由前缀为 `/data-cleaning/api/mvp/*`；0.6.0 五步任务和
+耐久制品使用 `/data-cleaning/api/workflow/*`。
 
 ## 3. 能力说明
 
@@ -122,7 +136,7 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
 4. 点击“估算调用量”。估算为上界且不执行 QCC 工具；
 5. 只有在核对企业数、工具数、估算调用量和 `maxCalls` 后，才勾选“确认使用当前用户的企查查账号额度”；
 6. 多候选逐项人工选择；失败项只在明确点击重试时重放；
-7. 下载补全结果 CSV，必要时下载候选复核 CSV。
+7. 生成并下载结果/异常清单的 CSV 或 XLSX；需要重新核验的行会进入异常清单。
 
 同源 API 为 `/data-cleaning/api/phase3/*`。单批最多 100 行，并发上限 4，硬调用上限 2000；
 默认调用上限 500。`enrich` / `resolve` / `retry` 均要求 `confirmPaidCalls:true` 和唯一幂等键。
@@ -152,5 +166,6 @@ bash <(curl -fsSL https://raw.githubusercontent.com/duhu2000/dsh-data-cleaning-a
   [QCC-ENRICHMENT-DESIGN.md](QCC-ENRICHMENT-DESIGN.md)。
 - **Q：可以在后台批量补全吗？** A：可以。0.4.0 G5 工商批量已发布并完成真实 OAuth/token 验收；
   0.5.0 风险/知产/经营三域已发布，先用 estimate 核对调用上限，再显式确认使用当前用户自己的 QCC 账号额度。
-- **Q：刷新页面或重启后还能恢复吗？** A：同一 Host 进程内可用 `runId` 恢复，默认保留 30 分钟；
-  Host 重启后内存 run 失效，但已下载 CSV 和本地源文件不受影响。
+- **Q：刷新页面或重启后还能恢复吗？** A：五步任务元数据与已生成制品可按 taskId 跨 Host 重启恢复；
+  尚未导出的浏览器原始行不会持久化，需要重新上传。QCC 的临时 `runId` 仍只在同一 Host 进程保留
+  30 分钟，但完成任务的 CSV/XLSX 不依赖该内存 run。

package/lib/artifacts.js

@@ -0,0 +1,239 @@
+/**
+ * Host 耐久导出制品。
+ *
+ * DSH rc.2 / alpha.2 已验证的 fs seam 只提供原子 writeText 与有界
+ * readBytes，没有稳定的二进制写接口。因此 CSV 以 UTF-8 文本保存，XLSX
+ * 先生成真实工作簿，再以 Base64 文本保存，下载时还原为原始字节。
+ */
+import { createHash, randomUUID } from 'node:crypto';
+import XLSX from 'xlsx';
+
+const ROOT = '.dsh-data-cleaning-artifacts/v1';
+const MAX_ARTIFACT_BYTES = 32 * 1024 * 1024;
+// Base64 最坏会把二进制扩大到 4/3；readBytes 必须允许读取完整编码文本，
+// 再对解码后的真实制品执行 MAX_ARTIFACT_BYTES 限制。
+const MAX_STORED_BYTES = Math.ceil(MAX_ARTIFACT_BYTES / 3) * 4 + 4;
+const SAFE_ID = /^(?:dcw|dca)-[a-zA-Z0-9-]{8,80}$/;
+
+export class ArtifactError extends Error {
+  constructor(code, message, status = 400) {
+    super(message);
+    this.name = 'ArtifactError';
+    this.code = code;
+    this.status = status;
+  }
+}
+
+function safeFilePart(value, fallback) {
+  const text = String(value ?? '').trim()
+    .replace(/[\\/:*?"<>|\u0000-\u001f]/g, '-')
+    .replace(/\s+/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^[-.]+|[-.]+$/g, '')
+    .slice(0, 80);
+  return text || fallback;
+}
+
+function assertId(value, label) {
+  const id = String(value ?? '');
+  if (!SAFE_ID.test(id)) throw new ArtifactError('DC_ARTIFACT_ID_INVALID', `${label} is invalid.`, 400);
+  return id;
+}
+
+function sha256(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+function normalizeHeaders(headers, rows) {
+  const fromInput = Array.isArray(headers) ? headers.map((item) => String(item ?? '').trim()).filter(Boolean) : [];
+  const discovered = [];
+  const seen = new Set(fromInput);
+  for (const row of rows) {
+    for (const key of Object.keys(row ?? {})) {
+      if (!seen.has(key)) {
+        seen.add(key);
+        discovered.push(key);
+      }
+    }
+  }
+  return [...fromInput, ...discovered].slice(0, 256);
+}
+
+function normalizeRows(value) {
+  if (!Array.isArray(value)) throw new ArtifactError('DC_ARTIFACT_ROWS_REQUIRED', 'Export rows must be an array.', 400);
+  if (value.length > 100_000) throw new ArtifactError('DC_ARTIFACT_ROWS_TOO_MANY', 'Export is limited to 100,000 rows.', 413);
+  const normalizeCell = (cell) => {
+    if (cell === null || cell === undefined) return '';
+    if (cell instanceof Date) return cell.toISOString();
+    if (typeof cell === 'number' || typeof cell === 'boolean') return cell;
+    if (typeof cell === 'string') return cell.slice(0, 32_767);
+    try {
+      const serialized = JSON.stringify(cell);
+      return String(serialized ?? cell).slice(0, 32_767);
+    } catch {
+      return String(cell).slice(0, 32_767);
+    }
+  };
+  return value.map((row) => {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) return { value: normalizeCell(row) };
+    return Object.fromEntries(Object.entries(row).slice(0, 256).map(([key, cell]) => [String(key), normalizeCell(cell)]));
+  });
+}
+
+function exceptionReason(row) {
+  const status = String(
+    row?.qcc_match_status
+      ?? row?.match_status
+      ?? row?.['匹配状态']
+      ?? '',
+  ).trim().toLowerCase();
+  const error = row?.qcc_error ?? row?.error ?? row?.['错误原因'];
+  if (error) return String(error).slice(0, 500);
+  if (['candidate', 'ambiguous', 'review_required'].includes(status)) return '存在多个候选主体，需人工核验';
+  if (['unresolved', 'not_found'].includes(status)) return '未匹配到可验证主体';
+  if (['failed', 'error', 'partial'].includes(status)) return '匹配或补全未完成';
+  return '';
+}
+
+export function deriveExceptionRows(rows) {
+  return rows.flatMap((row) => {
+    const reason = exceptionReason(row);
+    return reason ? [{ ...row, _exception_reason: reason }] : [];
+  });
+}
+
+function workbookBytes(rows, headers, sheetName) {
+  const workbook = XLSX.utils.book_new();
+  const worksheet = XLSX.utils.json_to_sheet(rows, { header: headers, skipHeader: false });
+  worksheet['!cols'] = headers.map((header) => ({ wch: Math.min(42, Math.max(12, String(header).length * 2 + 4)) }));
+  XLSX.utils.book_append_sheet(workbook, worksheet, sheetName.slice(0, 31));
+  workbook.Props = {
+    Title: sheetName,
+    Subject: 'DeepSeek Harness 数据清洗补全智能体导出',
+    Author: 'dsh-data-cleaning-agent',
+    Company: 'QCC',
+  };
+  return Buffer.from(XLSX.write(workbook, {
+    type: 'buffer',
+    bookType: 'xlsx',
+    compression: true,
+    cellDates: true,
+  }));
+}
+
+function csvBytes(rows, headers) {
+  const escapeCell = (value) => {
+    let text = String(value ?? '');
+    // 防止 Excel / LibreOffice 将外部数据解释为公式。数字类型不经过此前缀；
+    // 以危险字符开头的文本保留原值但加前导单引号。
+    if (/^[\u0009\u000d\u000a ]*[=+\-@]/.test(text)) text = `'${text}`;
+    return /[",\r\n]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+  };
+  const lines = [
+    headers.map(escapeCell).join(','),
+    ...rows.map((row) => headers.map((header) => escapeCell(row?.[header])).join(',')),
+  ];
+  return Buffer.from(`\uFEFF${lines.join('\r\n')}`, 'utf8');
+}
+
+function artifactDescriptor({ id, kind, format, fileName, rowCount, bytes, createdAt }) {
+  return {
+    id,
+    kind,
+    format,
+    fileName,
+    rowCount,
+    sizeBytes: bytes.length,
+    checksum: `sha256:${sha256(bytes)}`,
+    mediaType: format === 'xlsx'
+      ? 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
+      : 'text/csv; charset=utf-8',
+    createdAt,
+  };
+}
+
+export class WorkflowArtifactStore {
+  constructor({ fs, nowFn = () => new Date().toISOString(), idFactory = () => `dca-${randomUUID()}` }) {
+    if (!fs) throw new ArtifactError('DC_ARTIFACT_UNAVAILABLE', 'DSH fs service unavailable.', 503);
+    this.fs = fs;
+    this.nowFn = nowFn;
+    this.idFactory = idFactory;
+  }
+
+  pathFor(taskId, artifact) {
+    const safeTaskId = assertId(taskId, 'taskId');
+    const artifactId = assertId(artifact.id, 'artifactId');
+    const suffix = artifact.format === 'xlsx' ? 'xlsx.b64' : 'csv';
+    return `${ROOT}/${safeTaskId}/${artifactId}.${suffix}`;
+  }
+
+  async write(taskId, descriptor, bytes) {
+    if (bytes.length > MAX_ARTIFACT_BYTES) {
+      throw new ArtifactError('DC_ARTIFACT_TOO_LARGE', 'Generated artifact exceeds the 32 MiB limit.', 413);
+    }
+    const target = await this.fs.resolve(this.pathFor(taskId, descriptor));
+    const content = descriptor.format === 'xlsx' ? bytes.toString('base64') : bytes.toString('utf8');
+    await this.fs.writeText(target, content);
+    return descriptor;
+  }
+
+  async createBundle(taskId, input = {}) {
+    assertId(taskId, 'taskId');
+    const rows = normalizeRows(input.rows);
+    const headers = normalizeHeaders(input.headers, rows);
+    if (!headers.length) throw new ArtifactError('DC_ARTIFACT_HEADERS_REQUIRED', 'At least one export column is required.', 400);
+    const exceptions = input.exceptionRows === undefined
+      ? deriveExceptionRows(rows)
+      : normalizeRows(input.exceptionRows);
+    const exceptionHeaders = normalizeHeaders([...headers, '_exception_reason'], exceptions);
+    const baseName = safeFilePart(input.baseName, '数据清洗补全结果');
+    const timestamp = this.nowFn();
+    const definitions = [
+      { kind: 'complete', format: 'csv', fileName: `${baseName}.csv`, rows, headers, sheet: '清洗补全结果' },
+      { kind: 'complete', format: 'xlsx', fileName: `${baseName}.xlsx`, rows, headers, sheet: '清洗补全结果' },
+      { kind: 'review', format: 'csv', fileName: `${baseName}-异常清单.csv`, rows: exceptions, headers: exceptionHeaders, sheet: '异常清单' },
+      { kind: 'review', format: 'xlsx', fileName: `${baseName}-异常清单.xlsx`, rows: exceptions, headers: exceptionHeaders, sheet: '异常清单' },
+    ];
+    const artifacts = [];
+    for (const definition of definitions) {
+      const bytes = definition.format === 'xlsx'
+        ? workbookBytes(definition.rows, definition.headers, definition.sheet)
+        : csvBytes(definition.rows, definition.headers);
+      const descriptor = artifactDescriptor({
+        id: this.idFactory(),
+        kind: definition.kind,
+        format: definition.format,
+        fileName: definition.fileName,
+        rowCount: definition.rows.length,
+        bytes,
+        createdAt: timestamp,
+      });
+      await this.write(taskId, descriptor, bytes);
+      artifacts.push(descriptor);
+    }
+    return artifacts;
+  }
+
+  async read(taskId, artifact) {
+    const target = await this.fs.resolve(this.pathFor(taskId, artifact));
+    const storedLimit = artifact.format === 'xlsx' ? MAX_STORED_BYTES : MAX_ARTIFACT_BYTES;
+    const stored = Buffer.from(await this.fs.readBytes(target, undefined, storedLimit));
+    const bytes = artifact.format === 'xlsx'
+      ? Buffer.from(stored.toString('utf8'), 'base64')
+      : stored;
+    if (bytes.length > MAX_ARTIFACT_BYTES) {
+      throw new ArtifactError('DC_ARTIFACT_TOO_LARGE', 'Stored artifact exceeds the 32 MiB limit.', 413);
+    }
+    const actual = `sha256:${sha256(bytes)}`;
+    if (artifact.checksum && actual !== artifact.checksum) {
+      throw new ArtifactError('DC_ARTIFACT_CHECKSUM', 'Stored artifact checksum verification failed.', 409);
+    }
+    return bytes;
+  }
+}
+
+export const ARTIFACT_STORAGE = Object.freeze({
+  root: ROOT,
+  maxBytes: MAX_ARTIFACT_BYTES,
+  maxStoredBytes: MAX_STORED_BYTES,
+});