xlmerge

解决 Git 仓库中 .xlsx / .xlsm 策划配置表未合并冲突（merge conflict）的可视化工具。

Getting started · Usage · Development · Package family

Git 对二进制 .xlsx/.xlsm 只会整文件冲突，无法像文本一样逐行合并。xlmerge 用三方结构化差异引擎 + 本地可视化 UI把这件事变得可控：自动提取 Git index 的 base/ours/theirs 三方版本，按 Sheet、逻辑行、逻辑列、Cell 四级计算差异，浏览器中逐 Cell 选择本地/远端版本，最终写回工作簿并生成结构化 commit。

• 逻辑 ID 定位 - 冲突身份用逻辑 ID（非物理坐标），插行删行后选择不会漂移
• 保真写回 - 保留公式（注入缓存值，data_only 读取正确）、样式、批注、合并单元格、冻结窗格、行高列宽
• VBA 安全 - .xlsm 全程 keep_vba，保存后逐字节校验 VBA/ActiveX 负载
• Luban 表头识别 - 自动识别 ##var / ##type / ##group，注释列、占位列参与对齐
• 可配置整表过滤 - 仓库可把生成表加入过滤列表；命中时直接采用 Git stage 3 的远端原始文件
• 默认不越权 - 服务只监听 127.0.0.1，不自动 push

npm install -g @kevlns/xlmerge

# 或直接从 GitHub 仓库安装开发版本
npm install -g git+https://github.com/kevlns/xlmerge.git

要求：Node.js >= 16，系统 Python >= 3.9。首次运行若缺少依赖，会在 ~/.xlmerge/venv 自动创建用户级 venv 并安装 openpyxl==3.1.5、bottle==0.13.4。

# 检测未合并的 .xlsx/.xlsm（输出 JSON）
xlmerge --repo <仓库路径> detect

# 可选：把无需逐 Cell 审查的生成表加入仓库过滤列表
xlmerge --repo <仓库路径> filter add locale/Key.xlsx

# 提取三方版本并后台启动可视化解析器，返回 url（自动打开浏览器）
xlmerge --repo <仓库路径> launch

环境变量：

# 检测未合并的 .xlsx/.xlsm（输出 JSON）
xlmerge --repo <仓库路径> detect

# 添加整表过滤项（写入仓库根目录 .xlmerge.json）
xlmerge --repo <仓库路径> filter add <相对路径或路径后缀.xlsx>

# 提取三方版本并后台启动可视化解析器，返回 url（自动打开浏览器）
xlmerge --repo <仓库路径> launch

# 只处理单个文件
xlmerge --repo <仓库路径> launch --path new_meta/Items.xlsx

# 非交互（自动化/CI）：先 prepare 再 apply
xlmerge --repo <仓库路径> prepare
xlmerge --repo <仓库路径> apply --manifest <manifest.json> --decisions <decisions.json> [--no-commit] [--push]

--repo 缺省为当前目录（向上查找 Git 根）。

过滤列表默认为空，保存在仓库根目录的 .xlmerge.json：

{
  "autoTheirs": [
    "locale/Key.xlsx"
  ]
}

过滤项按路径段做不区分大小写的后缀匹配。命中的冲突工作簿不做 Cell 分析，而是逐字节采用 Git stage 3（theirs）并随同本批次提交；如果整批冲突都命中过滤项，launch/resolve 会直接写回并提交，不启动空白 UI。命令可重复执行，已有项不会重复写入。

decisions.json 格式（Cell 用 manifest 中的稳定逻辑 ID，如 row:base:4|name）：

{
  "files": {
    "new_meta/Items.xlsx": {
      "sheets": {
        "Items": { "cells": { "row:base:4|name": "theirs" } }
      }
    }
  }
}

包根 AGENTS.md 是 AI Agent 调用规范正本，包含适用场景、快速流程、禁止事项与边界。首次通过 v-cli 调用前应运行 v-cli agent docs xlmerge 掌握该规范；独立安装时也可直接读取包内 AGENTS.md。

# 单元测试（覆盖引擎、解析器、过滤配置与大请求体全流程）
python -m unittest discover -s python/tests -v

# 校验 v-cli.plugin.json 与 CLI 解析器未漂移（命令/选项/副作用覆盖）
npm run check:manifest

# 端到端（构造真实冲突仓库 -> detect -> launch -> API 决策 -> 写回提交）
python e2e_test.py bin/xlmerge.js node

# 打包
npm pack

bin/xlmerge.js                  # Node 启动垫片：探测 Python、按需建 venv、透传参数
AGENTS.md                       # AI Agent 调用规范正本（场景/规范/流程/边界）
v-cli.plugin.json               # Agent 插件清单（命令/选项/副作用），与 CLI 解析器做漂移校验
python/
├── xlsx_merge_engine/          # 三方结构化差异引擎（可独立 CLI 调试）
│   └── xlsx_git_merge_bridge.py
├── xlsx_resolver/              # 冲突解析器（detect/prepare/launch/apply + bottle UI）
└── tests/                      # 引擎与解析器测试（不随 npm 包发布）

注：为兼容嵌入式 Python 发行版（._pth 忽略 PYTHONPATH），模块内使用包内自举的 sys.path 注入而非纯包导入；这是有意为之。

kevlns 工具家族共享同一套发布约定（tag 驱动、CI 护栏、MIT）。

git clone https://github.com/kevlns/xlmerge.git
cd xlmerge
python -m unittest discover -s python/tests -v
npm run check:manifest

For bugs and feature requests, use GitHub Issues.

Released under the MIT License.