@kevlns/xlmerge 2.0.3 → 2.0.5
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 -169
- package/LICENSE +21 -21
- package/README.md +111 -111
- package/bin/xlmerge.js +152 -152
- package/package.json +3 -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 -660
- package/python/xlsx_resolver/merge_server.py +24 -0
- package/python/xlsx_resolver/merge_ui.html +1635 -1634
- package/python/xlsx_resolver/recalculate_workbook.ps1 +140 -141
- package/python/xlsx_resolver/resolve_xlsx_conflict.py +9 -0
- package/python/xlsx_resolver/session.py +49 -0
- package/python/xlsx_resolver/xlsx_conflict.py +2381 -2317
- package/skills/xlmerge/SKILL.md +8 -0
- package/skills/xlmerge/references/project.md +171 -0
- package/v-cli.plugin.json +305 -248
package/AGENTS.md
CHANGED
|
@@ -1,169 +1,25 @@
|
|
|
1
|
-
# Vant
|
|
2
|
-
|
|
3
|
-
## 定位
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
## 调用流程
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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。
|
|
1
|
+
# Vant 表格合并开发规范
|
|
2
|
+
|
|
3
|
+
## 定位
|
|
4
|
+
|
|
5
|
+
本文件仅指导维护 xlmerge 仓库。运行时技能正本为 skills/xlmerge/SKILL.md;命令机器契约为 v-cli.plugin.json。
|
|
6
|
+
|
|
7
|
+
## 调用流程
|
|
8
|
+
|
|
9
|
+
修改前读取相关源文件与 package.json 中的检查命令,保留已有工作区改动。
|
|
10
|
+
|
|
11
|
+
## 调用规范
|
|
12
|
+
|
|
13
|
+
技能正文与 references 独立维护,不从本文件生成运行规范。修改命令时同步机器清单及生成的命令文档。宿主配置和状态使用 VANT_HOME(默认 ~/.vant),项目数据保留在工程 .vant;安装不扫描其他 Agent 目录。外部宿主仅显式适配。
|
|
14
|
+
|
|
15
|
+
## 结果验证
|
|
16
|
+
|
|
17
|
+
运行 package.json 中与改动相关的检查;区分单测、真实后端、界面和安装验证。不得将模拟结果报告为真实生图或发布成功。
|
|
18
|
+
|
|
19
|
+
## 参考资料
|
|
20
|
+
|
|
21
|
+
[使用说明](README.md) · [运行技能](skills/xlmerge/SKILL.md)
|
|
22
|
+
|
|
23
|
+
## 许可与版权
|
|
24
|
+
|
|
25
|
+
MIT。Copyright © 2026 Vant。
|
package/LICENSE
CHANGED
|
@@ -1,21 +1,21 @@
|
|
|
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.
|
|
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.
|
package/README.md
CHANGED
|
@@ -1,111 +1,111 @@
|
|
|
1
|
-
# Vant 表格合并工具
|
|
2
|
-
|
|
3
|
-
`@kevlns/xlmerge`
|
|
4
|
-
|
|
5
|
-
## 功能
|
|
6
|
-
|
|
7
|
-
在浏览器中审阅 Git 冲突工作簿的三方差异,校验后写回并提交合并结果。
|
|
8
|
-
|
|
9
|
-
## 环境要求
|
|
10
|
-
|
|
11
|
-
Node.js 16 及以上、Python 3.9 及以上;包含公式的工作簿需要 Windows 桌面版 Excel 生成可靠的计算快照。
|
|
12
|
-
|
|
13
|
-
## 安装
|
|
14
|
-
|
|
15
|
-
```sh
|
|
16
|
-
npm install -g @kevlns/xlmerge
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
## 快速开始
|
|
20
|
-
|
|
21
|
-
```sh
|
|
22
|
-
xlmerge --repo <仓库目录> detect
|
|
23
|
-
xlmerge --repo <仓库目录> launch
|
|
24
|
-
```
|
|
25
|
-
|
|
26
|
-
## 使用说明
|
|
27
|
-
|
|
28
|
-
### 功能说明
|
|
29
|
-
|
|
30
|
-
Git 对二进制 `.xlsx`/`.xlsm` 只会整文件冲突,无法像文本一样逐行合并。xlmerge 用**公式最终值快照 + 三方结构化差异引擎 + 本地可视化 UI**把这件事变得可控:自动提取 Git index 的 base/ours/theirs 三方版本,按 Sheet、逻辑行、逻辑列、Cell 四级计算差异,浏览器中逐 Cell 选择本地/远端版本,最终原子写回工作簿并生成结构化 commit。
|
|
31
|
-
|
|
32
|
-
- **逻辑 ID 定位** - 冲突身份用逻辑 ID(非物理坐标),插行删行后选择不会漂移
|
|
33
|
-
- **公式感知** - 三方工作簿先各自完整计算;diff 使用最终值,受影响 Sheet 固化为静态值,未受影响 Sheet 保留原公式及缓存
|
|
34
|
-
- **安全写回** - apply 校验三方来源、值快照与工作树指纹;批次替换失败自动回滚,并保留所选来源的样式、批注、合并单元格、冻结窗格、行高列宽
|
|
35
|
-
- **VBA 安全** - `.xlsm` 全程 `keep_vba`,保存后逐字节校验 VBA/ActiveX 负载
|
|
36
|
-
- **Luban 表头识别** - 自动识别 `##var` / `##type` / `##group`,注释列、占位列参与对齐
|
|
37
|
-
- **可配置整表过滤** - 仓库可把生成表加入过滤列表;命中时直接采用 Git stage 3 的远端原始文件
|
|
38
|
-
- **默认不越权** - 服务只监听 `127.0.0.1`,不自动 push
|
|
39
|
-
|
|
40
|
-
### 操作流程
|
|
41
|
-
|
|
42
|
-
```bash
|
|
43
|
-
# 检测未合并的 .xlsx/.xlsm(输出 JSON)
|
|
44
|
-
xlmerge --repo <仓库路径> detect
|
|
45
|
-
|
|
46
|
-
# 添加整表过滤项(写入仓库根目录 .xlmerge.json)
|
|
47
|
-
xlmerge --repo <仓库路径> filter add <相对路径或路径后缀.xlsx>
|
|
48
|
-
|
|
49
|
-
# 提取三方版本并后台启动可视化解析器,返回 url(自动打开浏览器)
|
|
50
|
-
xlmerge --repo <仓库路径> launch
|
|
51
|
-
|
|
52
|
-
# 只处理单个文件
|
|
53
|
-
xlmerge --repo <仓库路径> launch --path new_meta/Items.xlsx
|
|
54
|
-
|
|
55
|
-
# 前台阻塞式运行(与 launch 等价,进程前台等待完成)
|
|
56
|
-
xlmerge --repo <仓库路径> resolve
|
|
57
|
-
|
|
58
|
-
# 非交互(自动化/CI):先 prepare 再 apply
|
|
59
|
-
xlmerge --repo <仓库路径> prepare
|
|
60
|
-
xlmerge --repo <仓库路径> apply --manifest <manifest.json> --decisions <decisions.json> [--no-commit] [--message <text>] [--push]
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
`--repo` 缺省为当前目录(向上查找 Git 根)。
|
|
64
|
-
|
|
65
|
-
过滤列表默认为空,保存在仓库根目录的 `.xlmerge.json`:
|
|
66
|
-
|
|
67
|
-
```json
|
|
68
|
-
{
|
|
69
|
-
"autoTheirs": [
|
|
70
|
-
"locale/Key.xlsx"
|
|
71
|
-
]
|
|
72
|
-
}
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
过滤项按路径段做不区分大小写的后缀匹配。命中的冲突工作簿不做 Cell 分析,而是逐字节采用 Git stage 3(theirs)并随同本批次提交;如果整批冲突都命中过滤项,`launch`/`resolve` 会直接写回并提交,不启动空白 UI。命令可重复执行,已有项不会重复写入。
|
|
76
|
-
|
|
77
|
-
decisions.json 格式(Cell 用 manifest 中的稳定逻辑 ID,如 `row:base:4|name`):
|
|
78
|
-
|
|
79
|
-
```json
|
|
80
|
-
{
|
|
81
|
-
"files": {
|
|
82
|
-
"new_meta/Items.xlsx": {
|
|
83
|
-
"sheets": {
|
|
84
|
-
"Items": { "cells": { "row:base:4|name": "theirs" } }
|
|
85
|
-
}
|
|
86
|
-
}
|
|
87
|
-
}
|
|
88
|
-
}
|
|
89
|
-
```
|
|
90
|
-
|
|
91
|
-
#### Agent 调用规范
|
|
92
|
-
|
|
93
|
-
包根 `AGENTS.md` 是 AI Agent 调用规范正本,包含适用场景、快速流程、禁止事项与边界。首次通过 v-cli 调用前应运行 `v-cli agent docs xlmerge` 掌握该规范;直接安装时也可直接读取包内 `AGENTS.md`。
|
|
94
|
-
|
|
95
|
-
## 开发与验证
|
|
96
|
-
|
|
97
|
-
```sh
|
|
98
|
-
npm ci
|
|
99
|
-
npm test
|
|
100
|
-
npm run test:python
|
|
101
|
-
```
|
|
102
|
-
|
|
103
|
-
命令返回、结构校验、模拟测试与外部平台实际运行分别核验。发布版本和依赖以随包 `package.json` 为准。
|
|
104
|
-
|
|
105
|
-
## 文档
|
|
106
|
-
|
|
107
|
-
[Agent 调用规范](
|
|
108
|
-
|
|
109
|
-
## 许可与版权
|
|
110
|
-
|
|
111
|
-
本工具采用 [MIT 许可](LICENSE)。Copyright © 2026 Vant。Vant 为工具集品牌;Figma、Unity、Steam、微信及其组件归各自权利人所有,第三方组件适用各自许可。
|
|
1
|
+
# Vant 表格合并工具
|
|
2
|
+
|
|
3
|
+
`@kevlns/xlmerge`
|
|
4
|
+
|
|
5
|
+
## 功能
|
|
6
|
+
|
|
7
|
+
在浏览器中审阅 Git 冲突工作簿的三方差异,校验后写回并提交合并结果。
|
|
8
|
+
|
|
9
|
+
## 环境要求
|
|
10
|
+
|
|
11
|
+
Node.js 16 及以上、Python 3.9 及以上;包含公式的工作簿需要 Windows 桌面版 Excel 生成可靠的计算快照。
|
|
12
|
+
|
|
13
|
+
## 安装
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
npm install -g @kevlns/xlmerge
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## 快速开始
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
xlmerge --repo <仓库目录> detect
|
|
23
|
+
xlmerge --repo <仓库目录> launch
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## 使用说明
|
|
27
|
+
|
|
28
|
+
### 功能说明
|
|
29
|
+
|
|
30
|
+
Git 对二进制 `.xlsx`/`.xlsm` 只会整文件冲突,无法像文本一样逐行合并。xlmerge 用**公式最终值快照 + 三方结构化差异引擎 + 本地可视化 UI**把这件事变得可控:自动提取 Git index 的 base/ours/theirs 三方版本,按 Sheet、逻辑行、逻辑列、Cell 四级计算差异,浏览器中逐 Cell 选择本地/远端版本,最终原子写回工作簿并生成结构化 commit。
|
|
31
|
+
|
|
32
|
+
- **逻辑 ID 定位** - 冲突身份用逻辑 ID(非物理坐标),插行删行后选择不会漂移
|
|
33
|
+
- **公式感知** - 三方工作簿先各自完整计算;diff 使用最终值,受影响 Sheet 固化为静态值,未受影响 Sheet 保留原公式及缓存
|
|
34
|
+
- **安全写回** - apply 校验三方来源、值快照与工作树指纹;批次替换失败自动回滚,并保留所选来源的样式、批注、合并单元格、冻结窗格、行高列宽
|
|
35
|
+
- **VBA 安全** - `.xlsm` 全程 `keep_vba`,保存后逐字节校验 VBA/ActiveX 负载
|
|
36
|
+
- **Luban 表头识别** - 自动识别 `##var` / `##type` / `##group`,注释列、占位列参与对齐
|
|
37
|
+
- **可配置整表过滤** - 仓库可把生成表加入过滤列表;命中时直接采用 Git stage 3 的远端原始文件
|
|
38
|
+
- **默认不越权** - 服务只监听 `127.0.0.1`,不自动 push
|
|
39
|
+
|
|
40
|
+
### 操作流程
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
# 检测未合并的 .xlsx/.xlsm(输出 JSON)
|
|
44
|
+
xlmerge --repo <仓库路径> detect
|
|
45
|
+
|
|
46
|
+
# 添加整表过滤项(写入仓库根目录 .xlmerge.json)
|
|
47
|
+
xlmerge --repo <仓库路径> filter add <相对路径或路径后缀.xlsx>
|
|
48
|
+
|
|
49
|
+
# 提取三方版本并后台启动可视化解析器,返回 url(自动打开浏览器)
|
|
50
|
+
xlmerge --repo <仓库路径> launch
|
|
51
|
+
|
|
52
|
+
# 只处理单个文件
|
|
53
|
+
xlmerge --repo <仓库路径> launch --path new_meta/Items.xlsx
|
|
54
|
+
|
|
55
|
+
# 前台阻塞式运行(与 launch 等价,进程前台等待完成)
|
|
56
|
+
xlmerge --repo <仓库路径> resolve
|
|
57
|
+
|
|
58
|
+
# 非交互(自动化/CI):先 prepare 再 apply
|
|
59
|
+
xlmerge --repo <仓库路径> prepare
|
|
60
|
+
xlmerge --repo <仓库路径> apply --manifest <manifest.json> --decisions <decisions.json> [--no-commit] [--message <text>] [--push]
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`--repo` 缺省为当前目录(向上查找 Git 根)。
|
|
64
|
+
|
|
65
|
+
过滤列表默认为空,保存在仓库根目录的 `.xlmerge.json`:
|
|
66
|
+
|
|
67
|
+
```json
|
|
68
|
+
{
|
|
69
|
+
"autoTheirs": [
|
|
70
|
+
"locale/Key.xlsx"
|
|
71
|
+
]
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
过滤项按路径段做不区分大小写的后缀匹配。命中的冲突工作簿不做 Cell 分析,而是逐字节采用 Git stage 3(theirs)并随同本批次提交;如果整批冲突都命中过滤项,`launch`/`resolve` 会直接写回并提交,不启动空白 UI。命令可重复执行,已有项不会重复写入。
|
|
76
|
+
|
|
77
|
+
decisions.json 格式(Cell 用 manifest 中的稳定逻辑 ID,如 `row:base:4|name`):
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"files": {
|
|
82
|
+
"new_meta/Items.xlsx": {
|
|
83
|
+
"sheets": {
|
|
84
|
+
"Items": { "cells": { "row:base:4|name": "theirs" } }
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
#### Agent 调用规范
|
|
92
|
+
|
|
93
|
+
包根 `AGENTS.md` 是 AI Agent 调用规范正本,包含适用场景、快速流程、禁止事项与边界。首次通过 v-cli 调用前应运行 `v-cli agent docs xlmerge` 掌握该规范;直接安装时也可直接读取包内 `AGENTS.md`。
|
|
94
|
+
|
|
95
|
+
## 开发与验证
|
|
96
|
+
|
|
97
|
+
```sh
|
|
98
|
+
npm ci
|
|
99
|
+
npm test
|
|
100
|
+
npm run test:python
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
命令返回、结构校验、模拟测试与外部平台实际运行分别核验。发布版本和依赖以随包 `package.json` 为准。
|
|
104
|
+
|
|
105
|
+
## 文档
|
|
106
|
+
|
|
107
|
+
[Agent 调用规范](skills/xlmerge/SKILL.md) · [文档规范](docs/documentation.md)
|
|
108
|
+
|
|
109
|
+
## 许可与版权
|
|
110
|
+
|
|
111
|
+
本工具采用 [MIT 许可](LICENSE)。Copyright © 2026 Vant。Vant 为工具集品牌;Figma、Unity、Steam、微信及其组件归各自权利人所有,第三方组件适用各自许可。
|