@kevlns/xlmerge 2.0.1 → 2.0.3
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 +169 -141
- package/LICENSE +21 -21
- package/README.md +111 -193
- package/bin/xlmerge.js +152 -152
- package/docs/documentation.md +24 -0
- package/package.json +7 -5
- package/python/xlsx_merge_engine/__init__.py +2 -2
- package/python/xlsx_merge_engine/xlsx_git_merge_bridge.py +1614 -1611
- package/python/xlsx_resolver/__init__.py +2 -2
- package/python/xlsx_resolver/__main__.py +4 -4
- package/python/xlsx_resolver/formula_values.py +660 -565
- package/python/xlsx_resolver/loading_ui.html +44 -0
- package/python/xlsx_resolver/merge_server.py +179 -126
- package/python/xlsx_resolver/merge_ui.html +1634 -1522
- package/python/xlsx_resolver/prepare_progress.py +34 -0
- package/python/xlsx_resolver/recalculate_workbook.ps1 +141 -155
- package/python/xlsx_resolver/resolve_xlsx_conflict.py +236 -222
- package/python/xlsx_resolver/xlsx_conflict.py +2317 -1994
- package/v-cli.plugin.json +248 -194
package/AGENTS.md
CHANGED
|
@@ -1,141 +1,169 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
```
|
|
10
|
-
xlmerge --repo
|
|
11
|
-
xlmerge --repo
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
```
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
1
|
+
# Vant 表格合并工具 Agent 规范
|
|
2
|
+
|
|
3
|
+
## 定位
|
|
4
|
+
|
|
5
|
+
在浏览器中审阅 Git 冲突工作簿的三方差异,校验后写回并提交合并结果。
|
|
6
|
+
|
|
7
|
+
## 调用流程
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
xlmerge --repo <仓库目录> detect
|
|
11
|
+
xlmerge --repo <仓库目录> launch
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
首次调用前读取本规范,使用命令帮助或插件清单核对参数和执行范围。
|
|
15
|
+
|
|
16
|
+
## 调用规范
|
|
17
|
+
|
|
18
|
+
> 三方工作簿会在结构对齐前分别计算并固化公式最终值;apply 对来源、快照和工作树做完整预检,并以可回滚批次执行写回(版本以 package.json / npm 包为准)。
|
|
19
|
+
|
|
20
|
+
> 本文件是 AI Agent 调用 xlmerge 的规范正本。完整参数以 `xlmerge --help` / 子命令 `--help` 与 `v-cli.plugin.json`(经 v-cli 路由时用 `v-cli agent describe xlmerge`)为准;本文件锁定使用场景、调用规范、快速流程与边界。
|
|
21
|
+
|
|
22
|
+
处理任意 Git 仓库中未合并的 `.xlsx` / `.xlsm` 二进制冲突。命令入口(npm 安装后全局可用,`<repo>` 为配置表 Git 仓库路径;经 v-cli 路由为 `v-cli xlmerge …`):
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
xlmerge --repo <repo> detect
|
|
26
|
+
xlmerge --repo <repo> filter add <path.xlsx>
|
|
27
|
+
xlmerge --repo <repo> launch
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
`npx` 等价:`npx --package @kevlns/xlmerge@latest xlmerge --repo <repo> detect`。
|
|
31
|
+
|
|
32
|
+
### 何时使用
|
|
33
|
+
|
|
34
|
+
用户要求处理策划表冲突、配置表冲突、xlsx/xlsm merge conflict 或多 Sheet 冲突,且 Git 仓库存在未合并的 `.xlsx`/`.xlsm` 时立即使用。这是一个**命令路由任务,不是表格分析任务**。
|
|
35
|
+
|
|
36
|
+
### 使用规范(Agent 必须遵守)
|
|
37
|
+
|
|
38
|
+
1. 用户确认要处理冲突后,**只做快速连贯的检测与启动**:`detect` → `count > 0` 时 `launch`。`reviewCount > 0` 时把返回的 `url` 告诉用户,然后停止分析,等待用户在页面完成选择;`reviewCount == 0` 时 `launch` 会直接采用过滤项的远端版本并提交,报告其 JSON 结果;`count == 0` 时报告没有未解决冲突并结束。
|
|
39
|
+
2. **不额外审查冲突情况**:不检查工作簿 Cell、不自行做三方 diff、不总结冲突内容、不读取 base/ours/theirs;这些复杂度由工具内部流程处理。
|
|
40
|
+
3. **不默认走无头自动合并**:`launch --no-browser` + 程序化 decisions/apply 的无头链路仅限自动化测试或用户明确提供决策 JSON / 明确要求自动化的场景;默认流程必须走 UI `launch`,决策权始终在用户。
|
|
41
|
+
4. **不替用户选择 ours/theirs**;不因为冲突文件多、Sheet 多而进入计划模式。
|
|
42
|
+
5. `apply` 默认写回并 `git commit`;`--no-commit` 仅测试决策时使用;`--push` 仅用户明确要求推送时使用,正常流程不自动 push。
|
|
43
|
+
6. 只处理单个文件时使用 `launch --path <仓库相对路径>`;多文件不按文件循环调用 `launch --path`,一次性同批次页面展示。
|
|
44
|
+
|
|
45
|
+
### 最高优先级快速流程
|
|
46
|
+
|
|
47
|
+
用户确认要处理冲突后,只做以下动作:
|
|
48
|
+
|
|
49
|
+
1. 执行检测:
|
|
50
|
+
|
|
51
|
+
```bash
|
|
52
|
+
xlmerge --repo <repo> detect
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
2. `count > 0` 时立即启动解析器;不传 `--path`,一次性处理所有冲突工作簿:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
xlmerge --repo <repo> launch
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
3. `reviewCount > 0` 时,把 `launch` 返回的 `url` 告诉用户,然后停止分析,等待用户在页面完成选择。`launch` 负责提取全部 Git 三方版本、计算多文件多 Sheet diff、后台启动服务并打开浏览器。`reviewCount == 0` 时不会启动 UI,命令会写回所有过滤项、提交并返回 `autoResolved`。
|
|
62
|
+
|
|
63
|
+
如果 `count` 为 `0`,报告没有未解决的 `.xlsx` / `.xlsm` 冲突并结束。
|
|
64
|
+
|
|
65
|
+
### 仓库过滤列表
|
|
66
|
+
|
|
67
|
+
过滤列表默认为空,仅在用户明确要求某类生成表始终采用远端整表时添加:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
xlmerge --repo <repo> filter add locale/Key.xlsx
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
命令把规范化后的相对 `.xlsx`/`.xlsm` 路径后缀写入仓库根目录 `.xlmerge.json` 的 `autoTheirs` 数组;匹配不区分大小写,重复添加是幂等操作。工具不内置任何业务路径。
|
|
74
|
+
|
|
75
|
+
命中过滤项的冲突文件不进入结构化分析或 UI,而是逐字节写入 Git index stage 3(theirs)。若 stage 3 不存在则安全失败;混合批次会在用户确认人工冲突后,与 UI 处理结果一起写回并提交。
|
|
76
|
+
|
|
77
|
+
### 快速流程禁止事项
|
|
78
|
+
|
|
79
|
+
- 不调用通用 `xlsx` Skill、Excel API 或临时 Python 读取 base/ours/theirs。
|
|
80
|
+
- 不运行 `prepare` 后读取 manifest,也不枚举或总结 Cell/Sheet 差异。
|
|
81
|
+
- 不先搜索配置表结构、Luban schema、策划字段含义或项目代码。
|
|
82
|
+
- 不替用户判断某个 Cell 应选 ours 还是 theirs。
|
|
83
|
+
- 不因为冲突文件多、Sheet 多而进入计划模式;这些复杂度由工具内部流程处理。
|
|
84
|
+
- 不使用阻塞式 `resolve` 作为正常入口;正常调用始终使用会快速返回 URL 的 `launch`。
|
|
85
|
+
- 默认流程禁止按文件循环调用 `launch --path`;单个文件异常也必须由同一批次页面展示或明确报错。
|
|
86
|
+
|
|
87
|
+
只处理单个文件时,仍然直接使用 `launch --path <仓库相对路径>`。
|
|
88
|
+
|
|
89
|
+
### 程序负责的内部流程
|
|
90
|
+
|
|
91
|
+
以下内容由解析器自动完成,用于理解边界,不要由模型重复实现:
|
|
92
|
+
|
|
93
|
+
1. 从 Git index 提取 base/ours/theirs(stage 1/2/3)。含公式时,三方原始工作簿先分别在隔离副本中完整计算并固化最终值快照,再经内容锚点引擎生成 Sheet、行、列和 Cell 四级三方差异;不含公式时走原文件快路径。冲突身份是 `仓库相对路径 + 逻辑 Sheet + 逻辑行 ID + 逻辑列 ID`,物理坐标只用于展示;新增/删除行列后选择不会漂移。Luban 风格表头(`##var` / `##type` / `##group` / `##`)会被自动识别并保留,`##var` 为空的注释列、占位列同样参与对齐与写回。
|
|
94
|
+
|
|
95
|
+
2. 本地服务只监听 `127.0.0.1`,浏览器负责用户交互:
|
|
96
|
+
|
|
97
|
+
- 顶部第一层标签切换冲突文件,第二层 `SHEET` 标签切换工作表;选择状态按文件和 Sheet 隔离。
|
|
98
|
+
- 两侧修改同一 Cell 且结果不同:默认显示 `theirs`,单击可在 `ours` / `theirs` 间切换;只有一侧修改时默认采用修改侧,仍可单击覆盖。
|
|
99
|
+
- 一侧删除 Sheet、另一侧修改:按整个 Sheet 选择保留 `ours` 或 `theirs`;只在一侧新增的 Sheet 自动保留。
|
|
100
|
+
- `.xlsm` 的 VBA/ActiveX 单边变化自动采用变化侧;双边变化时在文件级选择本地宏/远端宏(默认本地)。
|
|
101
|
+
- 相对本地可自动合入的远端新增行/列用浅绿色整行/列展示并锁定;已确定删除的行/列用灰色墓碑展示并锁定。
|
|
102
|
+
- 单击行号/列头批量切换;“全部本地/全部远端”作用于当前 Sheet;“撤销”回退最近一次选择,“重置”恢复默认三方选择。
|
|
103
|
+
- 当前 Sheet 提供上一个/下一个冲突定位,覆盖可人工选择的单侧改动及双侧冲突,支持跨页循环跳转;每个含可选择改动或结构冲突的 Sheet 必须独立勾选“已确认”,顶部统计跨文件显示已确认数量,未全部确认时提交会给出可点击的定位清单。双方一致变化和锁定的自动处理项不单独要求确认。
|
|
104
|
+
- 悬停 Cell 时展示 base、双方值、双方文件作者和当前选择。
|
|
105
|
+
|
|
106
|
+
3. 用户点击“写回并提交”后:
|
|
107
|
+
|
|
108
|
+
- 先请求只读 `/api/commit-preview` 生成 commit 信息,弹出居中的二次确认窗口;确认后才执行写回与 `git add` / `git commit`。
|
|
109
|
+
- 以原始 `ours` 工作簿为宏包/样式基底重建受影响 Sheet;受影响 Sheet 的全部公式写为已验证的最终静态值,未受影响 Sheet 保留原公式及缓存。保留所选来源的样式、批注、超链接、数字格式、行高列宽、冻结拆分等视图状态。
|
|
110
|
+
- 保存到仓库原路径并重新打开验证可读;`.xlsm` 全程 `keep_vba` 模式,保存后逐字节校验 VBA 负载。
|
|
111
|
+
- 存在冲突 Cell 选择时自动生成结构化提交信息(每个冲突 Cell 一行,含表、Sheet、单元格、选择、双方值);过滤项以“远端全量”记录,`--message` 可覆盖。
|
|
112
|
+
- 可视化入口不自动 push。
|
|
113
|
+
|
|
114
|
+
4. 用户完成页面操作并返回后复核:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
git -C <repo> diff --name-only --diff-filter=U
|
|
118
|
+
git -C <repo> status --short --branch
|
|
119
|
+
git -C <repo> log -1 --oneline
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
第一条必须无输出;随后报告处理的文件、Sheet、人工选择数量和 commit 结果。
|
|
123
|
+
|
|
124
|
+
### 非交互入口
|
|
125
|
+
|
|
126
|
+
仅在自动化测试或用户已提供明确决策 JSON 时使用 prepare/apply;不要用于查看 diff。决策必须同时包含文件、Sheet 和 Cell(Cell 优先使用 manifest 的稳定逻辑 ID):
|
|
127
|
+
|
|
128
|
+
```bash
|
|
129
|
+
xlmerge --repo <repo> prepare
|
|
130
|
+
xlmerge --repo <repo> apply --manifest <manifest.json> --decisions <decisions.json>
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
测试决策但不 commit 时加 `--no-commit`;只有用户明确要求推送时加 `--push`。
|
|
134
|
+
|
|
135
|
+
### 边界与失败处理
|
|
136
|
+
|
|
137
|
+
- 只处理 Git 未合并状态中的 `.xlsx` / `.xlsm`;不处理普通修改。
|
|
138
|
+
- 文件级 delete/modify 冲突缺少完整双方工作簿时,解析器停止并报告;不要猜测删除还是保留。
|
|
139
|
+
- 过滤项要求 Git stage 3 存在;缺少远端版本时停止并报告,不退回本地版本。
|
|
140
|
+
- 写回前必须收齐所有人工选择;缺少任何选择时不改工作树。
|
|
141
|
+
- prepare 生成的三方来源、审阅值快照和当时工作树指纹会在 apply 前全部校验;快照篡改、Git stage 变化、计算未完成或不可靠公式语义都会明确中止,整批次不写回、不 `git add`。
|
|
142
|
+
- 三方计算错误保留原公式、错误与位置作为未知值进入同一批次 UI,必须选择有效来源;无法可靠确认记录身份、表头或行列结构时必须选择整个 Sheet。双方同一记录、同一字段都错误时,工具按一致的显式基础类型替换(数值 0、string 空串、bool false),保留审计信息;ID、引用、约束字段、未知类型、重复 ID 不自动替换。未经处理的错误不能写回,安全限制不变。Agent 不代替用户选择人工项。
|
|
143
|
+
- 所有人工表和自动表先生成临时输出并通过预检,再统一替换;替换中途失败会回滚已替换文件,若文件系统同时阻止回滚则保留恢复副本并报告路径。
|
|
144
|
+
- 替换失败(如 Excel 正在占用目标文件,替换整体回滚)时,应要求用户关闭该工作簿后重试。
|
|
145
|
+
- 不直接修改 XLSX 内部 XML,不使用未经本次完整计算验证的旧公式缓存冒充最终值。
|
|
146
|
+
- 运行时提取文件和 manifest 默认放系统临时目录,不写入业务仓库。
|
|
147
|
+
|
|
148
|
+
### 环境
|
|
149
|
+
|
|
150
|
+
npm 包通过 `bin/xlmerge.js` 启动:自动检测系统 Python(≥3.9,`XLMERGE_PYTHON` 可直接指定;否则按平台探测 `python3` / `python`,Windows 追加 `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 秒的重算硬超时。正常流程不检查环境;仅入口明确报环境错误时诊断。
|
|
151
|
+
|
|
152
|
+
### 验证
|
|
153
|
+
|
|
154
|
+
```bash
|
|
155
|
+
cd <npm 包目录>
|
|
156
|
+
python -m unittest discover -s python/tests -v
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## 结果验证
|
|
160
|
+
|
|
161
|
+
核对原始错误、任务身份、停止状态及实际产物。只报告已经完成的验证,模拟测试与真实执行分别说明。
|
|
162
|
+
|
|
163
|
+
## 参考资料
|
|
164
|
+
|
|
165
|
+
[使用说明](README.md) · [文档规范](docs/documentation.md) · v-cli.plugin.json
|
|
166
|
+
|
|
167
|
+
## 许可与版权
|
|
168
|
+
|
|
169
|
+
MIT。Copyright © 2026 Vant。
|
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
1
|
-
MIT License
|
|
2
|
-
|
|
3
|
-
Copyright
|
|
4
|
-
|
|
5
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
-
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
-
in the Software without restriction, including without limitation the rights
|
|
8
|
-
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
-
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
-
furnished to do so, subject to the following conditions:
|
|
11
|
-
|
|
12
|
-
The above copyright notice and this permission notice shall be included in all
|
|
13
|
-
copies or substantial portions of the Software.
|
|
14
|
-
|
|
15
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
-
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
-
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
-
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
-
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright © 2026 Vant
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|