@kevlns/xlmerge 1.3.0 → 2.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +9 -4
- package/README.md +12 -6
- package/package.json +2 -2
- package/python/xlsx_merge_engine/xlsx_git_merge_bridge.py +24 -0
- package/python/xlsx_resolver/__init__.py +1 -1
- package/python/xlsx_resolver/formula_values.py +565 -0
- package/python/xlsx_resolver/merge_ui.html +345 -50
- package/python/xlsx_resolver/recalculate_workbook.ps1 +155 -0
- package/python/xlsx_resolver/resolve_xlsx_conflict.py +9 -0
- package/python/xlsx_resolver/xlsx_conflict.py +506 -113
- package/v-cli.plugin.json +5 -1
package/AGENTS.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# xlmerge Agent 使用规范
|
|
2
2
|
|
|
3
|
+
> 当前版本:v2.0.0。三方工作簿会在结构对齐前分别计算并固化公式最终值;apply 对来源、快照和工作树做完整预检,并以可回滚批次执行写回。
|
|
4
|
+
|
|
3
5
|
> 本文件是 AI Agent 调用 xlmerge 的规范正本。完整参数以 `xlmerge --help` / 子命令 `--help` 与 `v-cli.plugin.json`(经 v-cli 路由时用 `v-cli agent describe xlmerge`)为准;本文件锁定使用场景、调用规范、快速流程与边界。
|
|
4
6
|
|
|
5
7
|
处理任意 Git 仓库中未合并的 `.xlsx` / `.xlsm` 二进制冲突。命令入口(npm 安装后全局可用,`<repo>` 为配置表 Git 仓库路径;经 v-cli 路由为 `v-cli xlmerge …`):
|
|
@@ -73,7 +75,7 @@ xlmerge --repo <repo> filter add locale/Key.xlsx
|
|
|
73
75
|
|
|
74
76
|
以下内容由解析器自动完成,用于理解边界,不要由模型重复实现:
|
|
75
77
|
|
|
76
|
-
1. 从 Git index 提取 base/ours/theirs(stage 1/2/3
|
|
78
|
+
1. 从 Git index 提取 base/ours/theirs(stage 1/2/3)。含公式时,三方原始工作簿先分别在隔离副本中完整计算并固化最终值快照,再经内容锚点引擎生成 Sheet、行、列和 Cell 四级三方差异;不含公式时走原文件快路径。冲突身份是 `仓库相对路径 + 逻辑 Sheet + 逻辑行 ID + 逻辑列 ID`,物理坐标只用于展示;新增/删除行列后选择不会漂移。Luban 风格表头(`##var` / `##type` / `##group` / `##`)会被自动识别并保留,`##var` 为空的注释列、占位列同样参与对齐与写回。
|
|
77
79
|
|
|
78
80
|
2. 本地服务只监听 `127.0.0.1`,浏览器负责用户交互:
|
|
79
81
|
|
|
@@ -83,12 +85,13 @@ xlmerge --repo <repo> filter add locale/Key.xlsx
|
|
|
83
85
|
- `.xlsm` 的 VBA/ActiveX 单边变化自动采用变化侧;双边变化时在文件级选择本地宏/远端宏(默认本地)。
|
|
84
86
|
- 相对本地可自动合入的远端新增行/列用浅绿色整行/列展示并锁定;已确定删除的行/列用灰色墓碑展示并锁定。
|
|
85
87
|
- 单击行号/列头批量切换;“全部本地/全部远端”作用于当前 Sheet;“撤销”回退最近一次选择,“重置”恢复默认三方选择。
|
|
88
|
+
- 当前 Sheet 提供上一个/下一个冲突定位;每个需人工审阅的 Sheet 必须独立勾选“已确认”,顶部统计跨文件显示已确认数量,未全部确认时提交会给出可点击的定位清单。
|
|
86
89
|
- 悬停 Cell 时展示 base、双方值、双方文件作者和当前选择。
|
|
87
90
|
|
|
88
91
|
3. 用户点击“写回并提交”后:
|
|
89
92
|
|
|
90
93
|
- 先请求只读 `/api/commit-preview` 生成 commit 信息,弹出居中的二次确认窗口;确认后才执行写回与 `git add` / `git commit`。
|
|
91
|
-
-
|
|
94
|
+
- 以原始 `ours` 工作簿为宏包/样式基底重建受影响 Sheet;受影响 Sheet 的全部公式写为已验证的最终静态值,未受影响 Sheet 保留原公式及缓存。保留所选来源的样式、批注、超链接、数字格式、行高列宽、冻结拆分等视图状态。
|
|
92
95
|
- 保存到仓库原路径并重新打开验证可读;`.xlsm` 全程 `keep_vba` 模式,保存后逐字节校验 VBA 负载。
|
|
93
96
|
- 存在冲突 Cell 选择时自动生成结构化提交信息(每个冲突 Cell 一行,含表、Sheet、单元格、选择、双方值);过滤项以“远端全量”记录,`--message` 可覆盖。
|
|
94
97
|
- 可视化入口不自动 push。
|
|
@@ -120,13 +123,15 @@ xlmerge --repo <repo> apply --manifest <manifest.json> --decisions <decisions.js
|
|
|
120
123
|
- 文件级 delete/modify 冲突缺少完整双方工作簿时,解析器停止并报告;不要猜测删除还是保留。
|
|
121
124
|
- 过滤项要求 Git stage 3 存在;缺少远端版本时停止并报告,不退回本地版本。
|
|
122
125
|
- 写回前必须收齐所有人工选择;缺少任何选择时不改工作树。
|
|
126
|
+
- prepare 生成的三方来源、最终值快照和当时工作树指纹会在 apply 前全部校验;快照篡改、Git stage 变化、公式计算失败、公式错误或不可靠公式语义都会明确中止,整批次不写回、不 `git add`。
|
|
127
|
+
- 所有人工表和自动表先生成临时输出并通过预检,再统一替换;替换中途失败会回滚已替换文件,若文件系统同时阻止回滚则保留恢复副本并报告路径。
|
|
123
128
|
- Excel 正在占用目标文件导致替换失败时,要求用户关闭该工作簿后重试。
|
|
124
|
-
- 不直接修改 XLSX 内部 XML
|
|
129
|
+
- 不直接修改 XLSX 内部 XML,不使用未经本次完整计算验证的旧公式缓存冒充最终值。
|
|
125
130
|
- 运行时提取文件和 manifest 默认放系统临时目录,不写入业务仓库。
|
|
126
131
|
|
|
127
132
|
## 环境
|
|
128
133
|
|
|
129
|
-
npm 包通过 `bin/xlmerge.js` 启动:自动检测系统 Python(≥3.9,顺序为 `XLMERGE_PYTHON` 环境变量 > `python3` > `python` > `py -3`);若缺 `openpyxl` / `bottle` 依赖,则在 `~/.xlmerge/venv` 创建用户级 venv 并安装 `openpyxl==3.1.5`、`bottle==0.13.4
|
|
134
|
+
npm 包通过 `bin/xlmerge.js` 启动:自动检测系统 Python(≥3.9,顺序为 `XLMERGE_PYTHON` 环境变量 > `python3` > `python` > `py -3`);若缺 `openpyxl` / `bottle` 依赖,则在 `~/.xlmerge/venv` 创建用户级 venv 并安装 `openpyxl==3.1.5`、`bottle==0.13.4`。不含公式的工作簿保持跨平台;含公式时必须在 Windows 上安装桌面版 Excel,解析器只让 Excel 打开隔离的临时副本,并拒绝外链、UDF/VBA、volatile、循环引用、动态数组等不可安全复现的公式语义。`XLMERGE_EXCEL_TIMEOUT_SECONDS` 可覆盖每个工作簿默认 120 秒的重算硬超时。正常流程不检查环境;仅入口明确报环境错误时诊断。
|
|
130
135
|
|
|
131
136
|
## 验证
|
|
132
137
|
|
package/README.md
CHANGED
|
@@ -19,10 +19,11 @@
|
|
|
19
19
|
|
|
20
20
|
## Why xlmerge?
|
|
21
21
|
|
|
22
|
-
Git 对二进制 `.xlsx`/`.xlsm` 只会整文件冲突,无法像文本一样逐行合并。xlmerge
|
|
22
|
+
Git 对二进制 `.xlsx`/`.xlsm` 只会整文件冲突,无法像文本一样逐行合并。xlmerge 用**公式最终值快照 + 三方结构化差异引擎 + 本地可视化 UI**把这件事变得可控:自动提取 Git index 的 base/ours/theirs 三方版本,按 Sheet、逻辑行、逻辑列、Cell 四级计算差异,浏览器中逐 Cell 选择本地/远端版本,最终原子写回工作簿并生成结构化 commit。
|
|
23
23
|
|
|
24
24
|
- **逻辑 ID 定位** - 冲突身份用逻辑 ID(非物理坐标),插行删行后选择不会漂移
|
|
25
|
-
-
|
|
25
|
+
- **公式感知** - 三方工作簿先各自完整计算;diff 使用最终值,受影响 Sheet 固化为静态值,未受影响 Sheet 保留原公式及缓存
|
|
26
|
+
- **安全写回** - apply 校验三方来源、值快照与工作树指纹;批次替换失败自动回滚,并保留所选来源的样式、批注、合并单元格、冻结窗格、行高列宽
|
|
26
27
|
- **VBA 安全** - `.xlsm` 全程 `keep_vba`,保存后逐字节校验 VBA/ActiveX 负载
|
|
27
28
|
- **Luban 表头识别** - 自动识别 `##var` / `##type` / `##group`,注释列、占位列参与对齐
|
|
28
29
|
- **可配置整表过滤** - 仓库可把生成表加入过滤列表;命中时直接采用 Git stage 3 的远端原始文件
|
|
@@ -39,7 +40,7 @@ npm install -g @kevlns/xlmerge
|
|
|
39
40
|
npm install -g git+https://github.com/kevlns/xlmerge.git
|
|
40
41
|
```
|
|
41
42
|
|
|
42
|
-
要求:Node.js >= 16,系统 Python >= 3.9。首次运行若缺少依赖,会在 `~/.xlmerge/venv` 自动创建用户级 venv 并安装 `openpyxl==3.1.5`、`bottle==0.13.4
|
|
43
|
+
要求:Node.js >= 16,系统 Python >= 3.9。首次运行若缺少依赖,会在 `~/.xlmerge/venv` 自动创建用户级 venv 并安装 `openpyxl==3.1.5`、`bottle==0.13.4`。不含公式的工作簿保持跨平台;工作簿含公式时,安全的最终值快照需要 Windows 桌面版 Excel,缺失时会明确失败而不会采用旧缓存。
|
|
43
44
|
|
|
44
45
|
### Quick start
|
|
45
46
|
|
|
@@ -60,6 +61,7 @@ xlmerge --repo <仓库路径> launch
|
|
|
60
61
|
|------|------|
|
|
61
62
|
| `XLMERGE_PYTHON` | 指定解释器路径(如嵌入式 Python),跳过自动探测 |
|
|
62
63
|
| `XLMERGE_VENV` | 覆盖默认 venv 目录 |
|
|
64
|
+
| `XLMERGE_EXCEL_TIMEOUT_SECONDS` | 单个工作簿通过 Excel 隔离重算的硬超时,默认 120 秒 |
|
|
63
65
|
|
|
64
66
|
## Usage
|
|
65
67
|
|
|
@@ -116,9 +118,12 @@ decisions.json 格式(Cell 用 manifest 中的稳定逻辑 ID,如 `row:base:
|
|
|
116
118
|
## Development
|
|
117
119
|
|
|
118
120
|
```bash
|
|
119
|
-
#
|
|
121
|
+
# 单元测试(覆盖引擎、公式安全、原子写回、过滤配置与大请求体全流程)
|
|
120
122
|
python -m unittest discover -s python/tests -v
|
|
121
123
|
|
|
124
|
+
# 可选:调用本机 Excel 的真实公式重算回归(仅操作临时目录)
|
|
125
|
+
$env:XLSX_EXCEL_E2E=1; python -m unittest discover -s python/tests -v
|
|
126
|
+
|
|
122
127
|
# 校验 v-cli.plugin.json 与 CLI 解析器未漂移(命令/选项/副作用覆盖)
|
|
123
128
|
npm run check:manifest
|
|
124
129
|
|
|
@@ -138,7 +143,7 @@ v-cli.plugin.json # Agent 插件清单(命令/选项/副作用
|
|
|
138
143
|
python/
|
|
139
144
|
├── xlsx_merge_engine/ # 三方结构化差异引擎(可独立 CLI 调试)
|
|
140
145
|
│ └── xlsx_git_merge_bridge.py
|
|
141
|
-
├── xlsx_resolver/ #
|
|
146
|
+
├── xlsx_resolver/ # 冲突解析器、公式值快照与 bottle UI
|
|
142
147
|
└── tests/ # 引擎与解析器测试(不随 npm 包发布)
|
|
143
148
|
```
|
|
144
149
|
|
|
@@ -151,7 +156,7 @@ kevlns 工具家族共享同一套发布约定(tag 驱动、CI 护栏、MIT)
|
|
|
151
156
|
| Package | Purpose | Status |
|
|
152
157
|
| --- | --- | --- |
|
|
153
158
|
| [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI | v0.2.3 |
|
|
154
|
-
| [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具(本仓库) |
|
|
159
|
+
| [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具(本仓库) | v2.0.0 |
|
|
155
160
|
| [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包(Windows-first) | v0.1.4 |
|
|
156
161
|
|
|
157
162
|
## Compatibility
|
|
@@ -160,6 +165,7 @@ kevlns 工具家族共享同一套发布约定(tag 驱动、CI 护栏、MIT)
|
|
|
160
165
|
| --- | --- |
|
|
161
166
|
| Node.js | `16` and later |
|
|
162
167
|
| Python | `3.9` and later |
|
|
168
|
+
| Excel formula calculation | Windows desktop Excel; formula-free workbooks remain cross-platform |
|
|
163
169
|
|
|
164
170
|
## Contributing
|
|
165
171
|
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kevlns/xlmerge",
|
|
3
|
-
"version": "
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "2.0.0",
|
|
4
|
+
"description": "Formula-aware visual resolver for unresolved Git merge conflicts in .xlsx/.xlsm workbooks: three-way sheet/row/cell diff, local UI, atomic write-back and commit.",
|
|
5
5
|
"bin": {
|
|
6
6
|
"xlmerge": "bin/xlmerge.js"
|
|
7
7
|
},
|
|
@@ -651,6 +651,30 @@ def _fast_row_side_alignment(
|
|
|
651
651
|
def _row_side_alignment(
|
|
652
652
|
base_rows: list[RowProjection], side_rows: list[RowProjection]
|
|
653
653
|
) -> tuple[dict[int, int], dict[int, list[int]]]:
|
|
654
|
+
# Constant columns (including padding, flags and repeated formula results)
|
|
655
|
+
# provide no evidence of row identity. Counting them as matches can make a
|
|
656
|
+
# deleted row plus an insertion score higher than the surviving record.
|
|
657
|
+
# Drop them only from the alignment projection; all_cells stays intact for
|
|
658
|
+
# the actual three-way comparison and output. If all columns are constant,
|
|
659
|
+
# retain the original sequence semantics for duplicate/empty rows.
|
|
660
|
+
combined = [*base_rows, *side_rows]
|
|
661
|
+
width = max((len(row.projection) for row in combined), default=0)
|
|
662
|
+
informative = [
|
|
663
|
+
column for column in range(width)
|
|
664
|
+
if len({
|
|
665
|
+
_line([row.projection[column] if column < len(row.projection) else None])
|
|
666
|
+
for row in combined
|
|
667
|
+
}) > 1
|
|
668
|
+
]
|
|
669
|
+
if informative and len(informative) < width:
|
|
670
|
+
def project(rows):
|
|
671
|
+
return [RowProjection(
|
|
672
|
+
row.xlsx_row,
|
|
673
|
+
tuple(row.projection[column] if column < len(row.projection) else None
|
|
674
|
+
for column in informative),
|
|
675
|
+
row.all_cells, row.empty,
|
|
676
|
+
) for row in rows]
|
|
677
|
+
base_rows, side_rows = project(base_rows), project(side_rows)
|
|
654
678
|
if len(base_rows) * len(side_rows) > _FAST_ALIGN_THRESHOLD:
|
|
655
679
|
return _fast_row_side_alignment(base_rows, side_rows)
|
|
656
680
|
base_count = len(base_rows)
|
|
@@ -1,2 +1,2 @@
|
|
|
1
1
|
# -*- coding: utf-8 -*-
|
|
2
|
-
"""
|
|
2
|
+
"""xlmerge XLSX/XLSM 冲突解析器(detect/prepare/launch/apply)。"""
|