表格差异审阅 po-et/dsh-sheet-diff

SheetDiff

先审阅表格改动，再决定是否采信。

SheetDiff 按业务键比较两个 CSV 或 XLSX 文件，不按行位置比较。它生成一份本地 HTML 报告，你可以在里面查看值、类型、公式和公式的存储结果，然后留下评论，方便后续和智能体跟进。

它是独立的 DeepSeek Harness 插件，也带一个小型命令行。它不编辑工作簿、不计算公式、不上传数据，也不需要 API key。

本地审阅报告，显示一处公式改动和一条导出的评论

本地试用

需要 Node.js 22.19 或更高版本。克隆仓库，跑一遍合成演示：

git clone https://github.com/po-et/dsh-sheet-diff.git
cd dsh-sheet-diff
npm ci --ignore-scripts
npm test
npm run demo

演示会在 artifacts/ 下新建一个目录，写入两个合成工作簿和一个 report.html。用浏览器打开打印出来的报告路径。预期结果是新增三行、四处单元格改动：两个金额、一个公式的存储结果变了、一个数字变成了文本。调整行序和列序不会产生任何改动。

处理你自己的文件：

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。

CSV 对 CSV，XLSX 对 XLSX。本版本拒绝混合格式比较。

配合 DeepSeek Harness 使用

把带版本号的发布包安装到配置档：

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

安装后重启该配置档。包里带 JavaScript 和一个 dsh.bundle 补丁，没有插件构建步骤，也没有安装脚本。你也可以用 npm pack 从源码构建发布包，再安装它的本地绝对路径。发布包通过 GitHub Releases 分发；本项目未发布到 npm。

已在 Harness 0.2.0-rc.2 和 0.2.1-alpha.2 上测试，peer 范围明确限定为预览版本。两者都装进全新配置档，并通过官方配置档启动入口跑通，全程未调用模型。仅在测试配置档里关闭了 HMR；从源码构建的 alpha 宿主还打印了无关的可选 Typert 导入警告。

对 Harness 说：

用 OrderID 作键，比较 before.xlsx 和 after.xlsx。把 SheetDiff 报告存到 reviews/run-001。不要改动任何一个工作簿。

插件注册两个工具：

| 工具 | 输入 | 结果 |
| sheet_diff_compare | before、after、keyColumns、outputDir；可选 sheet、headerRow | 新的 HTML/JSON 路径、哈希、摘要和警告 |
| sheet_diff_review | reportJson、reviewJson | 校验通过的评论，附带对应的变更 |

路径必须留在当前会话工作区内，解析后的符号链接目标也算在内。创建报告需要可写的沙箱。已有报告绝不会被覆盖。如果第二个输出写入失败，工具会报告保留下来的第一个文件，而不是删掉它。

交互式报告在普通浏览器中打开。禁用 JavaScript 的 Harness 预览无法运行它的评论控件。本版本没有内置的应用内电子表格编辑器。

先审阅，再把评论交回来

1. 打开 HTML 报告，筛选变更，在你想检查的变更旁边写评论。
2. 导出审阅 JSON。草稿评论只留在页面内存里，直到导出为止。
3. 把导出文件放进工作区，连同原始报告 JSON 一起传给 sheet_diff_review。

等价的命令行写法是：

node src/cli.js review review-001/report.json review-comments.json

评论必须匹配报告 ID、两个输入哈希和已知的变更 ID。过期或不相关的审阅会被拒绝。哈希匹配不是数字签名，不能证明报告没有被刻意改写。评论和单元格内容都是不可信数据；本插件绝不会执行其中的指令，也不会应用其中建议的修改。

比较规则

- 列名和键精确匹配。复合键包含单元格类型；数字 42 与文本 "42" 不同。重复键、缺失键和重复表头一律报错，不做猜测。
- 表头行出现在所有非空数据之后时，直接拒绝，而不是产出一个空比较。有效表头之前的引导内容和真正空白的表仍受支持。
- CSV 是逗号分隔的 UTF-8，支持带引号的字段、内嵌换行和 BOM。值保持文本；不推断 CSV 公式。
- XLSX 保留数字、文本、布尔值、日期、错误和公式之间的区别。公式文本和保存的缓存结果是变更的两个独立方面。缓存不是重新计算。
- 以 ISO 8601 单元格存储的日期（t="d"，例如 openpyxl 的 iso_dates=True）会被拒绝，因为底层读取器会把它们误读成数字。改用数值型 Excel 日期存储重新导出（openpyxl 中 iso_dates=False）；1900 和 1904 两种日期系统都仍受支持。包含 ISO 日期的普通文本仍是文本。这项检查覆盖每个工作表，包括未选中的工作表。
- v0.1 拒绝包含显式空字符串的公式缓存：底层读取器无法可靠地把它们与缺失缓存区分开。零值和 false 缓存会保留。
- 公式文本按字面比较。移动公式可能改变它的 A1 引用，但含义不变；SheetDiff 不会把这种等价关系归一化。
- 跳过空行。新增/删除的行会带上其中已填写的字段。新增/删除的列会产生结构性变更，同时保留行中已填写的值也会产生单元格变更。
- Sheet 重命名会报告为删除加新增。关键变更会报告为行删除加新增。

这是表格数据审查工具，不做整个工作簿的保真校验。格式、数字格式、合并布局、图表、透视表、图片、批注和超链接目标都不在它的范围内。隐藏数据仍会被读取，但可见性本身不参与比较。不支持旧版 XLS、宏、加密压缩包和外部工作簿连接。复杂的多表 Sheet 可能需要先导出成独立的表。

限制与隐私

每个输入上限 20 MiB，XLSX 展开内容上限 64 MiB、每个 ZIP 分片上限 8 MiB，比较结果上限 10,000 条变更记录或 24 MiB 序列化变更。解析器还会把序列化后的单元格/行数限制在 100,000，并在解析前检查展开后的合并、列和校验范围。超出限制会让比较失败；绝不会把截短的报告当作完整报告呈现。

报告包含变更的单元格数据、源文件名和哈希。请把 HTML、报告 JSON 和审查 JSON 视同工作簿一样敏感。分享需要手动操作。页面不加载远程资源，不做分析统计，也不自动持久化。在 AI 宿主内使用时，工具结果和导入的评论可能作为其正常运行的一部分，发送给该宿主配置的模型。

开发

npm test
npm run smoke:host
npm pack --dry-run

smoke:host 用真实的 Cordis 加载器加载随包发布的补丁，并通过真实的工具运行时、文件系统服务商和沙箱策略派发两个工具。它还会检查源字节、覆盖拒绝和插件释放。它使用全新的临时工作区，不会改动已有的 Harness 配置档。该测试独立于完整的命令行安装，也不使用在线模型。

中文简介

AI 改完表格后，先看清楚改了什么，再决定是否采用。SheetDiff 按订单号、账户号等业务主键对齐记录，避免把行列重排当成大量修改；数值、类型、公式和保存的计算结果分开显示。你可以在本地报告中逐条评论，导出后交回 Harness 继续处理。

首版只读 CSV/XLSX，不上传表格、不重算公式、不自动改文件。它不是表格编辑器，也不承诺检测格式、图表或所有 Excel 功能的变化。

MIT licensed. Bug reports are most useful with a small anonymized example and the expected comparison result. Please do not post confidential workbooks.