@kevlns/xlmerge 2.0.5 → 2.0.7
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 +25 -25
- package/LICENSE +21 -21
- package/README.md +113 -111
- package/bin/xlmerge.js +152 -152
- package/package.json +2 -2
- package/python/xlsx_merge_engine/__init__.py +2 -2
- package/python/xlsx_merge_engine/xlsx_git_merge_bridge.py +1614 -1614
- package/python/xlsx_resolver/__init__.py +2 -2
- package/python/xlsx_resolver/__main__.py +4 -4
- package/python/xlsx_resolver/formula_values.py +677 -677
- package/python/xlsx_resolver/merge_ui.html +1635 -1635
- package/python/xlsx_resolver/recalculate_workbook.ps1 +140 -140
- package/python/xlsx_resolver/xlsx_conflict.py +2381 -2381
- package/skills/xlmerge/SKILL.md +8 -8
- package/skills/xlmerge/references/project.md +59 -171
- package/v-cli.plugin.json +305 -305
package/skills/xlmerge/SKILL.md
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
---
|
|
2
|
-
name: xlmerge
|
|
3
|
-
description: "
|
|
4
|
-
---
|
|
5
|
-
|
|
6
|
-
#
|
|
7
|
-
|
|
8
|
-
|
|
1
|
+
---
|
|
2
|
+
name: xlmerge
|
|
3
|
+
description: "处理 Git 中的 Excel 三方冲突,支持 Agent 根据项目规则裁决并写回,也支持浏览器逐项审阅。"
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# 配表冲突
|
|
7
|
+
|
|
8
|
+
在发生合并的工区 detect → prepare,读取 manifest 中 base/ours/theirs 的差异与稳定 ID,按项目约束及变更意图裁决。仅将无法判断的业务项交控制源。用 apply --no-commit 写回并验证 Git 索引,按原任务完成提交或交付。用户选择可视化审阅时使用 launch。参数与裁决格式见[操作规范](references/project.md)。
|
|
@@ -1,171 +1,59 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
## 定位
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
## 调用流程
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
xlmerge --repo
|
|
11
|
-
|
|
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
|
-
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
|
-
后台审阅用 `xlmerge launch`。`xlmerge status --manifest <file>` 查询原服务,`xlmerge cancel --manifest <file>` 请求停止并检查 stopConfirmed;身份不一致拒绝停止。通过 v-cli 结构化执行时,launch/resolve 返回 accepted 与 handle;status/cancel 使用原 handle,后台进程继续持有工程租约,停止前不重放启动。
|
|
160
|
-
|
|
161
|
-
## 结果验证
|
|
162
|
-
|
|
163
|
-
核对原始错误、任务身份、停止状态及实际产物。只报告已经完成的验证,模拟测试与真实执行分别说明。
|
|
164
|
-
|
|
165
|
-
## 参考资料
|
|
166
|
-
|
|
167
|
-
使用说明(工具包 `README.md`) · 文档规范(工具包 `docs/documentation.md`) · v-cli.plugin.json
|
|
168
|
-
|
|
169
|
-
## 许可与版权
|
|
170
|
-
|
|
171
|
-
MIT。Copyright © 2026 Vant。
|
|
1
|
+
# 配表冲突处理
|
|
2
|
+
|
|
3
|
+
## 定位
|
|
4
|
+
|
|
5
|
+
在工单或会话绑定的 Git 工区运行。原始三方、工作表、逻辑行列、公式计算值和稳定 ID 均由 xlmerge 生成。
|
|
6
|
+
|
|
7
|
+
## 调用流程
|
|
8
|
+
|
|
9
|
+
1. 用 `xlmerge --repo <repo> detect` 核对未合并的工作簿。没有冲突则结束。先核对 Git 合并双方,明确 ours 和 theirs 在本次操作中指向谁。
|
|
10
|
+
2. 用 `xlmerge --repo <repo> prepare` 获取 manifest 路径。仅处理指定文件时加 `--path <相对路径>`。按 files[].diff.sheets 读取三方变化与项目规则、字段约束、引用及两侧提交意图。保留可兼容的单边变化。命中仓库既有 autoTheirs 规则的文件由工具处理。
|
|
11
|
+
3. 对双边改动使用清单稳定 ID,记录选择和业务依据。只上报无法同时满足的具体取舍,保留当前清单和已判项。Agent 在获得裁决后续办原任务。
|
|
12
|
+
4. 构造 decisions.json。例如同一工作表内两个字段分别取不同来源:
|
|
13
|
+
|
|
14
|
+
```json
|
|
15
|
+
{"files":{"<文件ID>":{"sheets":{"<Sheet名>":{"cells":{"<逻辑单元格ID一>":"ours","<逻辑单元格ID二>":"theirs"}}}}}}
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
工作表冲突使用 sheet,重命名用 rename,合并区域用 mergedCells,均按清单选 ours/theirs。rows 和 columns 中的 delete_modify 按 ID 选 keep/delete。宏冲突使用文件级 macro。遇到需要工作簿两侧都没有的新值,单独安排普通改表与验证。
|
|
19
|
+
|
|
20
|
+
5. 用 `xlmerge --repo <repo> apply --manifest <manifest.json> --decisions <decisions.json> --no-commit` 写回并暂存。逐项核对 success、Git 未合并列表与暂存结果;按原授权继续合并或交 Reviewer。只在明确要求推送时推送。来源变动重新 prepare;写回结果未知时先检查实际工作簿与索引。
|
|
21
|
+
6. 用户想亲自审阅时可用 launch,status/cancel 使用同一会话的 manifest。launch 在所有文件都命中 autoTheirs 时会直接完成合并并提交。只有明确要求长期改变过滤策略才用 filter add。
|
|
22
|
+
|
|
23
|
+
## 调用规范
|
|
24
|
+
|
|
25
|
+
- 只处理 Git 未合并状态中的 `.xlsx` / `.xlsm`;不处理普通修改。
|
|
26
|
+
- 文件级 delete/modify 冲突缺少完整双方工作簿时,解析器停止并报告;不要猜测删除还是保留。
|
|
27
|
+
- 过滤项要求 Git stage 3 存在;缺少远端版本时停止并报告,不退回本地版本。
|
|
28
|
+
- 写回前必须收齐所有必需裁决;缺少任何选择时不改工作树。
|
|
29
|
+
- prepare 生成的三方来源、审阅值快照和当时工作树指纹会在 apply 前全部校验;快照篡改、Git stage 变化、计算未完成或不可靠公式语义都会明确中止,整批次不写回、不 `git add`。
|
|
30
|
+
- 三方计算错误保留原公式、错误与位置作为未知值进入同一批次 UI,必须选择有效来源;无法可靠确认记录身份、表头或行列结构时必须选择整个 Sheet。双方同一记录、同一字段都错误时,工具按一致的显式基础类型替换(数值 0、string 空串、bool false),保留审计信息;ID、引用、约束字段、未知类型、重复 ID 不自动替换。未经处理的错误不能写回,安全限制不变。业务歧义按任务的决策渠道上报。
|
|
31
|
+
- 所有人工表和自动表先生成临时输出并通过预检,再统一替换;替换中途失败会回滚已替换文件,若文件系统同时阻止回滚则保留恢复副本并报告路径。
|
|
32
|
+
- 替换失败(如 Excel 正在占用目标文件,替换整体回滚)时,应要求用户关闭该工作簿后重试。
|
|
33
|
+
- 不直接修改 XLSX 内部 XML,不使用未经本次完整计算验证的旧公式缓存冒充最终值。
|
|
34
|
+
- 运行时提取文件和 manifest 默认放系统临时目录,不写入业务仓库。
|
|
35
|
+
|
|
36
|
+
### 环境
|
|
37
|
+
|
|
38
|
+
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 秒的重算硬超时。正常流程不检查环境;仅入口明确报环境错误时诊断。
|
|
39
|
+
|
|
40
|
+
### 验证
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
cd <npm 包目录>
|
|
44
|
+
python -m unittest discover -s python/tests -v
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
后台审阅用 `xlmerge launch`。`xlmerge status --manifest <file>` 查询原服务,`xlmerge cancel --manifest <file>` 请求停止并检查 stopConfirmed;身份不一致拒绝停止。通过 v-cli 结构化执行时,launch/resolve 返回 accepted 与 handle;status/cancel 使用原 handle,后台进程继续持有工程租约,停止前不重放启动。
|
|
48
|
+
|
|
49
|
+
## 结果验证
|
|
50
|
+
|
|
51
|
+
核对原始错误、任务身份、停止状态及实际产物。只报告已经完成的验证,模拟测试与真实执行分别说明。
|
|
52
|
+
|
|
53
|
+
## 参考资料
|
|
54
|
+
|
|
55
|
+
使用说明(工具包 `README.md`) · 文档规范(工具包 `docs/documentation.md`) · v-cli.plugin.json
|
|
56
|
+
|
|
57
|
+
## 许可与版权
|
|
58
|
+
|
|
59
|
+
MIT。Copyright © 2026 Vant。
|