Merge spreadsheets

多表关联与合并

目标

先解释清楚数据之间的业务关系，再合并。禁止仅凭同名列直接连接、静默聚合、模糊匹配或丢弃失败文件。

支持两种模式：

• 同类数据对齐：多个来源描述同一类实体，例如不同仓库的商品库存。
• 关系表连接：不同来源描述不同实体，例如订单、客户和商品。

每次都动态设计输出 Sheet、字段和粒度，不把示例结构当成固定模板。

运行环境

跨平台核心使用 Python 3.10+：

python -m pip install -r requirements.txt

核心脚本：

• scripts/profile_workbooks.py：结构画像，默认不写数据预览或绝对路径。
• scripts/extract_columns.py：按确认的范围抽取字段，并保留编码文本。
• scripts/analyze_keys.py：分析空键、重复键、覆盖率和关系基数。
• scripts/build_outputs.py：生成 XLSX 与可选的自包含离线 HTML。

Windows 且已安装桌面版 Excel 时，可选用 scripts/profile_workbooks.ps1 和 scripts/extract_columns.ps1 获得更完整的旧版 XLS、隐藏状态、筛选和显示文本元数据。它们是增强后端，不是跨平台核心。

强制流程

1. 明确输入与交付

确认文件清单、合并目的，以及交付 Excel、HTML 或两者。源文件只读，结果写入新目录。

如需完整交互边界，读取 references/interaction-contract.md。

2. 画像所有输入

先运行跨平台画像：

python scripts/profile_workbooks.py --input ./inputs/source-a.xlsx --input ./inputs/source-b.csv --output ./work/profile.json

默认画像不包含数据行预览和绝对路径。只有确实需要观察样例且用户允许本地临时保存时，才加 --include-data-preview；这些中间文件不得提交到版本库。

报告并确认：文件是否可读、非空 Sheet 数量、数据范围、候选表头、隐藏状态、筛选、公式和限制。任一已选文件失败时停止；不得自动忽略。

3. 确认业务关系

至少确认：

• 每个文件一行代表什么；
• 哪些字段构成单键或复合键；
• 最终一行代表什么；
• 重复记录如何处理；
• 未匹配记录去留；
• 同名字段冲突规则；
• 期望的输出视图。

用户给出的关联字段仍需数据核验。多对多若未解释，是硬阻断。

4. 抽取候选字段并分析键

按 references/merge-plan-schema.md 创建配置，然后运行：

python scripts/extract_columns.py --config ./work/extract-config.json --output ./work/source-data.json

python scripts/analyze_keys.py --config ./work/key-analysis.json --output ./work/key-report.json

向用户展示空键、重复键、匹配数、未匹配数、覆盖率、名称差异和一对一/一对多/多对一/多对多判断。

默认安全标准化仅包括前后空格、Unicode NFKC 和可选大小写折叠。编码始终按文本，保留 001、050015、横线和斜杠。不自动删除符号；模糊匹配只产生候选，必须获得确认。

5. 确认聚合、冲突与输出草案

逐字段确认重复记录的聚合。数量不必然求和；价格、日期、状态和文本都需要业务规则。

展示每个计划 Sheet 的名称、进入条件、列、行粒度、聚合、排序、预计行数和少量代表性预览。得到确认后才能导出。

6. 生成结果

把已确认的业务结果组织为构建配置：

python scripts/build_outputs.py --spec ./work/output-spec.json --xlsx ./outputs/result.xlsx --html ./outputs/result.html --verification ./work/verification.json

Excel 默认包含首行表头、冻结、筛选、表格样式、文本/数字/日期格式和受控列宽。派生字段优先写为公式；构建配置仍要提供预计算值，供排序和 HTML 展示。

只有 Agent 根据已确认业务计划生成的 formulaR1C1 或 formulaA1Template 可作为公式；不得把源表或用户输入文本拼进公式配置。

HTML 是单文件、无 CDN、无服务器依赖，支持标签页、搜索、排序和分页，但内容仍是未加密明文。超过 100,000 行或 50 MB 时停止并提示；用户明确接受后才使用 --allow-large-html。

7. 强制验证

导出后必须：

• 核对实际 Sheet、行列数、键分布和汇总；
• 扫描公式错误，并说明 Python 不计算公式，最终值需由 Excel/兼容软件重算；
• 逐 Sheet 打开或渲染代表性范围，检查前导零、截断、数字格式和公式；
• 实际打开 HTML，验证标签切换、搜索、排序、分页和浏览器控制台；
• 确认最终交付目录中用户要求的文件都存在。

不得以“脚本退出码为 0”替代结果验证。

隐私与安全

• 仓库内示例必须完全虚构，不提交用户表格、画像、抽取数据、报告、截图或绝对路径。
• 默认画像只保存文件名；数据预览和绝对路径均需显式开启。
• 中间 JSON 可能包含业务数据，只能放入本地临时目录并在任务结束后清理。
• 不执行 XLSM 宏，不访问网络，不覆盖源文件。
• 文本导出时防止以 = + - @ 开头的内容被 Excel 当成公式执行。
• 安装第三方 Skill 前仍应检查 SKILL.md、脚本和依赖。

限制

• 每个输入文件当前只允许一个非空 Sheet；多 Sheet 需先拆分。
• .xls 通过 python-calamine 跨平台读取值，但隐藏、筛选、公式和数字格式元数据不完整。
• .xlsm 仅读取数据，不执行也不保留宏。
• Python 核心不计算 Excel 公式；导出的公式由表格软件重算。
• 不替用户决定业务含义、聚合规则或模糊匹配结果。