前言¶
在 DeepSeek Harness（DSH）里让智能体改表格，常见做法是直接覆盖或另存一份新文件。若两份表只是行、列顺序不同，逐行对比很容易把「重排」误判成大量修改；若涉及公式，还要看公式文本和 Excel 保存的缓存结果是否一致。缺少一个只读、可本地打开的审阅环节，很难在采纳变更前把风险说清楚。
下面介绍社区插件 dsh-sheet-diff（维护者 po-et，分类：工作流）。它按业务主键对齐两份 CSV 或 XLSX，生成本地 HTML/JSON 报告，支持在浏览器里查看数值、类型、公式与缓存结果，并导出评论 JSON 交回 Harness 继续处理。插件不编辑工作簿、不重算公式、不上传数据，也不要 API Key。
这是什么¶
SheetDiff 是独立的 DSH 插件，同时提供小型 CLI（sheet-diff）。核心定位是：在信任 AI 产出的表格之前，先做一次按键对齐的变更审阅。GitHub 仓库：po-et/dsh-sheet-diff；社区目录页：skillhub.cn 插件条目。
首版（v0.1.0，MIT 许可证）仅支持只读比较 CSV 与 CSV、XLSX 与 XLSX；混合格式会被拒绝。
核心功能¶
按键对齐，而非按行号¶
比较时使用你指定的列作为业务主键（可用多个 --key 组成复合键）。列名与键值需精确匹配；复合键包含单元格类型，数值 42 与文本 "42" 视为不同。重复键、缺键、重复表头会直接失败，不做猜测。行、列重排本身不应产生无意义的单元格变更（演示数据里重排行列不会计入变更）。
报告里能看到什么¶
本地 HTML 报告可筛选变更，并区分：
- 数值、文本、布尔、日期、错误等类型（XLSX）
- 公式文本与保存的公式缓存结果（缓存不是重新计算）
- 增删行、增删列及结构变化
CSV 为逗号分隔 UTF-8，支持引号字段、内嵌换行与 BOM；CSV 侧不把内容推断为公式。
注册的两个 Harness 工具¶
| 工具 | 主要输入 | 结果 |
|---|---|---|
sheet_diff_compare |
before、after、keyColumns、outputDir；可选 sheet、headerRow |
新 HTML/JSON 路径、哈希、摘要与警告 |
sheet_diff_review |
reportJson、reviewJson |
校验后的评论及对应变更 |
路径须落在当前会话工作区内（含符号链接解析目标）。生成报告需要可写沙箱；已有报告不会被覆盖。若第二次写出失败，工具会保留已写出的第一个文件，而不是删掉它。
审阅与回传¶
- 在浏览器打开 HTML 报告，筛选变更，在需要跟进的项旁写评论。
- 导出审阅 JSON（草稿仅留在页面内存，导出后才落盘）。
- 将导出文件与原始
report.json一并放在工作区内，调用sheet_diff_review。
评论须匹配报告 ID、两份输入文件的哈希及已知变更 ID；过期或不相关的审阅会被拒绝。哈希一致不代表报告未被人为改写；评论与单元格内容均视为不可信数据，插件不会执行其中的指令或自动改表。
范围与限制（摘要）¶
- 单文件输入上限 20 MiB；XLSX 解压后 64 MiB、单 ZIP 分片 8 MiB；变更记录 10,000 条或序列化变更 24 MiB 等上限超限则比较失败，不会给出「截断但看似完整」的报告。
- 不比较整本工作簿的格式、合并单元格布局、图表、透视等；隐藏数据仍会读取，但不比较「是否隐藏」。
- 不支持旧版 XLS、宏、加密包、外部链接等。以 ISO 8601 存储的日期单元格（如 openpyxl
iso_dates=True）会被拒绝，需用数值 Excel 日期重新导出。
运行环境要求 Node.js 22.19 或更高（见 package.json 的 engines）。在 Harness 0.2.0-rc.2 与 0.2.1-alpha.2 上做过安装与工具调用测试（无模型调用）。
安装与启用¶
插件通过 GitHub Releases 分发，未发布到 npm。安装到指定 profile 使用官方命令（版本以 v0.1.0 发布包为准）：
dsh plugin --profile YOUR_PROFILE add https://github.com/po-et/dsh-sheet-diff/releases/download/v0.1.0/dsh-sheet-diff-0.1.0.tgz
安装后重启该 profile。包内为 JavaScript 与 dsh.bundle 补丁，无插件侧构建步骤或 install 脚本。也可在源码目录执行 npm pack 后，用生成的 tgz 的本地绝对路径安装。
DSH 社区目录是独立站点，与 DeepSeek / 幻方无官方从属关系；安装前请自行查看仓库源码与 MIT 许可证。插件以当前 DSH 进程权限访问工作区文件，审阅报告可能包含变更单元格数据与源文件名、哈希，请按敏感数据处理。
典型用法¶
在 Harness 里用自然语言驱动¶
可向智能体说明意图，例如：
Compare
before.xlsxandafter.xlsxusingOrderIDas the key. Save a SheetDiff report inreviews/run-001. Do not change either workbook.
交互式报告需在支持 JavaScript 的浏览器中打开；禁用 JS 的预览无法使用页面上的评论控件。本版没有内置电子表格编辑器。
CLI 直接比较两份文件¶
在工作目录准备好 before / after 文件后：
node src/cli.js before.xlsx after.xlsx --key OrderID --out review-001
node src/cli.js examples/before.csv examples/after.csv --key OrderID --out review-csv
--out 必须指向新建的目录。复合键可重复 --key。--sheet Orders 指定工作表；--header-row 3 指定表头行，否则各表默认第 1 行为表头且须包含所选键列。CSV 逻辑上只有名为 CSV 的一张表。
审阅 JSON 的 CLI 等价命令：
node src/cli.js review review-001/report.json review-comments.json
若已通过发布包或 npm pack 安装 CLI，可使用 sheet-diff 二进制，参数与 README 中 node src/cli.js 示例一致。
适用场景与注意¶
适合：智能体或脚本生成「修订版」表格后，人工或二次 Agent 回合前，按订单号、账户号等主键核对金额、类型、公式与缓存结果；需要把审阅意见结构化回传给 Harness 的工作流。
不适合：需要重算公式、写回 Excel、或整本工作簿版式 fidelity 校验的场景；多表混排在一张 sheet 上的复杂布局可能需要先导出为独立表再比较。
比较规则、隐私与开发测试（npm test、npm run smoke:host）等细节以 GitHub README 为准。
结尾¶
dsh-sheet-diff 把「改表」拆成只读对比、本地 HTML 审阅、评论 JSON 回传三步，用业务主键减少行列重排带来的噪音，并把公式与缓存结果分开展示。若你在 DSH 工作流里频繁处理 CSV/XLSX 变更，可在安装 v0.1.0 发布包并重启 profile 后，通过 sheet_diff_compare / sheet_diff_review 或 CLI 接入同一套流程。
