@kevlns/xlmerge 2.0.1 → 2.0.2

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/README.md CHANGED
@@ -1,193 +1,197 @@
1
- <div align="center">
2
-
3
- <img src="https://raw.githubusercontent.com/kevlns/xlmerge/main/logo.png" alt="xlmerge logo" width="320" />
4
-
5
- # xlmerge
6
-
7
- **解决 Git 仓库中 `.xlsx` / `.xlsm` 策划配置表未合并冲突的可视化工具。**
8
-
9
- [![npm version](https://img.shields.io/npm/v/%40kevlns%2Fxlmerge?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@kevlns/xlmerge)
10
- [![npm downloads](https://img.shields.io/npm/dm/%40kevlns%2Fxlmerge?style=flat-square&color=4c8bf5)](https://www.npmjs.com/package/@kevlns/xlmerge)
11
- [![CI](https://img.shields.io/github/actions/workflow/status/kevlns/xlmerge/test.yml?branch=main&style=flat-square&label=CI)](https://github.com/kevlns/xlmerge/actions/workflows/test.yml)
12
- [![license](https://img.shields.io/github/license/kevlns/xlmerge?style=flat-square&color=2e8b57)](./LICENSE)
13
-
14
- [Getting started](#getting-started) · [Usage](#usage) · [Development](#development) · [Package family](#package-family)
15
-
16
- </div>
17
-
18
- ---
19
-
20
- ## Why xlmerge?
21
-
22
- Git 对二进制 `.xlsx`/`.xlsm` 只会整文件冲突,无法像文本一样逐行合并。xlmerge 用**公式最终值快照 + 三方结构化差异引擎 + 本地可视化 UI**把这件事变得可控:自动提取 Git index 的 base/ours/theirs 三方版本,按 Sheet、逻辑行、逻辑列、Cell 四级计算差异,浏览器中逐 Cell 选择本地/远端版本,最终原子写回工作簿并生成结构化 commit。
23
-
24
- - **逻辑 ID 定位** - 冲突身份用逻辑 ID(非物理坐标),插行删行后选择不会漂移
25
- - **公式感知** - 三方工作簿先各自完整计算;diff 使用最终值,受影响 Sheet 固化为静态值,未受影响 Sheet 保留原公式及缓存
26
- - **安全写回** - apply 校验三方来源、值快照与工作树指纹;批次替换失败自动回滚,并保留所选来源的样式、批注、合并单元格、冻结窗格、行高列宽
27
- - **VBA 安全** - `.xlsm` 全程 `keep_vba`,保存后逐字节校验 VBA/ActiveX 负载
28
- - **Luban 表头识别** - 自动识别 `##var` / `##type` / `##group`,注释列、占位列参与对齐
29
- - **可配置整表过滤** - 仓库可把生成表加入过滤列表;命中时直接采用 Git stage 3 的远端原始文件
30
- - **默认不越权** - 服务只监听 `127.0.0.1`,不自动 push
31
-
32
- ## Getting started
33
-
34
- ### Install
35
-
36
- ```bash
37
- npm install -g @kevlns/xlmerge
38
-
39
- # 或直接从 GitHub 仓库安装开发版本
40
- npm install -g git+https://github.com/kevlns/xlmerge.git
41
- ```
42
-
43
- 要求:Node.js >= 16,系统 Python >= 3.9。首次运行若缺少依赖,会在 `~/.xlmerge/venv` 自动创建用户级 venv 并安装 `openpyxl==3.1.5`、`bottle==0.13.4`。不含公式的工作簿保持跨平台;工作簿含公式时,安全的最终值快照需要 Windows 桌面版 Excel,缺失时会明确失败而不会采用旧缓存。
44
-
45
- ### Quick start
46
-
47
- ```bash
48
- # 检测未合并的 .xlsx/.xlsm(输出 JSON)
49
- xlmerge --repo <仓库路径> detect
50
-
51
- # 可选:把无需逐 Cell 审查的生成表加入仓库过滤列表
52
- xlmerge --repo <仓库路径> filter add locale/Key.xlsx
53
-
54
- # 提取三方版本并后台启动可视化解析器,返回 url(自动打开浏览器)
55
- xlmerge --repo <仓库路径> launch
56
- ```
57
-
58
- 环境变量:
59
-
60
- | 变量 | 作用 |
61
- |------|------|
62
- | `XLMERGE_PYTHON` | 指定解释器路径(如嵌入式 Python),跳过自动探测 |
63
- | `XLMERGE_VENV` | 覆盖默认 venv 目录 |
64
- | `XLMERGE_EXCEL_TIMEOUT_SECONDS` | 单个工作簿通过 Excel 隔离重算的硬超时,默认 120 秒 |
65
-
66
- ## Usage
67
-
68
- ```bash
69
- # 检测未合并的 .xlsx/.xlsm(输出 JSON)
70
- xlmerge --repo <仓库路径> detect
71
-
72
- # 添加整表过滤项(写入仓库根目录 .xlmerge.json)
73
- xlmerge --repo <仓库路径> filter add <相对路径或路径后缀.xlsx>
74
-
75
- # 提取三方版本并后台启动可视化解析器,返回 url(自动打开浏览器)
76
- xlmerge --repo <仓库路径> launch
77
-
78
- # 只处理单个文件
79
- xlmerge --repo <仓库路径> launch --path new_meta/Items.xlsx
80
-
81
- # 前台阻塞式运行(与 launch 等价,进程前台等待完成)
82
- xlmerge --repo <仓库路径> resolve
83
-
84
- # 非交互(自动化/CI):先 prepare 再 apply
85
- xlmerge --repo <仓库路径> prepare
86
- xlmerge --repo <仓库路径> apply --manifest <manifest.json> --decisions <decisions.json> [--no-commit] [--message <text>] [--push]
87
- ```
88
-
89
- `--repo` 缺省为当前目录(向上查找 Git 根)。
90
-
91
- 过滤列表默认为空,保存在仓库根目录的 `.xlmerge.json`:
92
-
93
- ```json
94
- {
95
- "autoTheirs": [
96
- "locale/Key.xlsx"
97
- ]
98
- }
99
- ```
100
-
101
- 过滤项按路径段做不区分大小写的后缀匹配。命中的冲突工作簿不做 Cell 分析,而是逐字节采用 Git stage 3(theirs)并随同本批次提交;如果整批冲突都命中过滤项,`launch`/`resolve` 会直接写回并提交,不启动空白 UI。命令可重复执行,已有项不会重复写入。
102
-
103
- decisions.json 格式(Cell 用 manifest 中的稳定逻辑 ID,如 `row:base:4|name`):
104
-
105
- ```json
106
- {
107
- "files": {
108
- "new_meta/Items.xlsx": {
109
- "sheets": {
110
- "Items": { "cells": { "row:base:4|name": "theirs" } }
111
- }
112
- }
113
- }
114
- }
115
- ```
116
-
117
- ### Agent 调用规范
118
-
119
- 包根 `AGENTS.md` 是 AI Agent 调用规范正本,包含适用场景、快速流程、禁止事项与边界。首次通过 v-cli 调用前应运行 `v-cli agent docs xlmerge` 掌握该规范;独立安装时也可直接读取包内 `AGENTS.md`。
120
-
121
- ## Development
122
-
123
- ```bash
124
- # 单元测试(覆盖引擎、公式安全、原子写回、过滤配置与大请求体全流程)
125
- python -m unittest discover -s python/tests -v
126
-
127
- # 可选:调用本机 Excel 的真实公式重算回归(仅操作临时目录)
128
- $env:XLSX_EXCEL_E2E=1; python -m unittest discover -s python/tests -v
129
-
130
- # 校验 v-cli.plugin.json 与 CLI 解析器未漂移(命令/选项/副作用覆盖)
131
- npm run check:manifest
132
-
133
- # 端到端(构造真实冲突仓库 -> detect -> launch -> API 决策 -> 写回提交)
134
- python e2e_test.py bin/xlmerge.js node
135
-
136
- # 打包
137
- npm pack
138
- ```
139
-
140
- ### 包结构
141
-
142
- ```
143
- bin/xlmerge.js # Node 启动垫片:探测 Python、按需建 venv、透传参数
144
- AGENTS.md # AI Agent 调用规范正本(场景/规范/流程/边界)
145
- v-cli.plugin.json # Agent 插件清单(命令/选项/副作用),与 CLI 解析器做漂移校验
146
- python/
147
- ├── xlsx_merge_engine/ # 三方结构化差异引擎(可独立 CLI 调试)
148
- │ └── xlsx_git_merge_bridge.py
149
- ├── xlsx_resolver/ # 冲突解析器、公式值快照与 bottle UI
150
- └── tests/ # 引擎与解析器测试(不随 npm 包发布)
151
- ```
152
-
153
- > 注:为兼容嵌入式 Python 发行版(`._pth` 忽略 `PYTHONPATH`),模块内通过自举 `sys.path` 注入定位依赖,勿改为纯包导入。
154
-
155
- ## Package family
156
-
157
- kevlns 工具家族共享同一套发布约定(tag 驱动、CI 护栏、MIT)。
158
-
159
- | Package | Purpose | Version |
160
- | --- | --- | --- |
161
- | [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI | v0.2.14 |
162
- | [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具(本仓库) | v2.0.0 |
163
- | [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包(Windows-first) | v0.2.3 |
164
- | [`figma-to-uprefab`](https://github.com/kevlns/figma-to-uprefab) | Figma 导出、契约校验与 Unity UGUI staging Prefab 构建 | v0.1.1 |
165
-
166
- ## Compatibility
167
-
168
- | Runtime | Supported versions |
169
- | --- | --- |
170
- | Node.js | `16` and later |
171
- | Python | `3.9` and later |
172
- | Excel formula calculation | Windows desktop Excel; formula-free workbooks remain cross-platform |
173
-
174
- ## Contributing
175
-
176
- ```bash
177
- git clone https://github.com/kevlns/xlmerge.git
178
- cd xlmerge
179
- python -m unittest discover -s python/tests -v
180
- npm run check:manifest
181
- ```
182
-
183
- For bugs and feature requests, use [GitHub Issues](https://github.com/kevlns/xlmerge/issues).
184
-
185
- ## License
186
-
187
- Released under the [MIT License](./LICENSE).
188
-
189
- <div align="center">
190
-
191
- Part of the **kevlns** tool family.
192
-
193
- </div>
1
+ <div align="center">
2
+
3
+ <img src="https://raw.githubusercontent.com/kevlns/xlmerge/main/logo.png" alt="xlmerge logo" width="320" />
4
+
5
+ # xlmerge
6
+
7
+ **解决 Git 仓库中 `.xlsx` / `.xlsm` 策划配置表未合并冲突的可视化工具。**
8
+
9
+ [![npm version](https://img.shields.io/npm/v/%40kevlns%2Fxlmerge?style=flat-square&color=cb3837)](https://www.npmjs.com/package/@kevlns/xlmerge)
10
+ [![npm downloads](https://img.shields.io/npm/dm/%40kevlns%2Fxlmerge?style=flat-square&color=4c8bf5)](https://www.npmjs.com/package/@kevlns/xlmerge)
11
+ [![CI](https://img.shields.io/github/actions/workflow/status/kevlns/xlmerge/test.yml?branch=main&style=flat-square&label=CI)](https://github.com/kevlns/xlmerge/actions/workflows/test.yml)
12
+ [![license](https://img.shields.io/github/license/kevlns/xlmerge?style=flat-square&color=2e8b57)](./LICENSE)
13
+
14
+ [Getting started](#getting-started) · [Usage](#usage) · [Development](#development) · [Package family](#package-family)
15
+
16
+ </div>
17
+
18
+ ---
19
+
20
+ ## Why xlmerge?
21
+
22
+ Git 对二进制 `.xlsx`/`.xlsm` 只会整文件冲突,无法像文本一样逐行合并。xlmerge 用**公式最终值快照 + 三方结构化差异引擎 + 本地可视化 UI**把这件事变得可控:自动提取 Git index 的 base/ours/theirs 三方版本,按 Sheet、逻辑行、逻辑列、Cell 四级计算差异,浏览器中逐 Cell 选择本地/远端版本,最终原子写回工作簿并生成结构化 commit。
23
+
24
+ - **逻辑 ID 定位** - 冲突身份用逻辑 ID(非物理坐标),插行删行后选择不会漂移
25
+ - **公式感知** - 三方工作簿先各自完整计算;diff 使用最终值,受影响 Sheet 固化为静态值,未受影响 Sheet 保留原公式及缓存
26
+ - **安全写回** - apply 校验三方来源、值快照与工作树指纹;批次替换失败自动回滚,并保留所选来源的样式、批注、合并单元格、冻结窗格、行高列宽
27
+ - **VBA 安全** - `.xlsm` 全程 `keep_vba`,保存后逐字节校验 VBA/ActiveX 负载
28
+ - **Luban 表头识别** - 自动识别 `##var` / `##type` / `##group`,注释列、占位列参与对齐
29
+ - **可配置整表过滤** - 仓库可把生成表加入过滤列表;命中时直接采用 Git stage 3 的远端原始文件
30
+ - **默认不越权** - 服务只监听 `127.0.0.1`,不自动 push
31
+
32
+ ## Getting started
33
+
34
+ ### Install
35
+
36
+ ```bash
37
+ npm install -g @kevlns/xlmerge
38
+
39
+ # 或直接从 GitHub 仓库安装开发版本
40
+ npm install -g git+https://github.com/kevlns/xlmerge.git
41
+ ```
42
+
43
+ 要求:Node.js >= 16,系统 Python >= 3.9。首次运行若缺少依赖,会在 `~/.xlmerge/venv` 自动创建用户级 venv 并安装 `openpyxl==3.1.5`、`bottle==0.13.4`。不含公式的工作簿保持跨平台;工作簿含公式时,安全的最终值快照需要 Windows 桌面版 Excel,缺失时会明确失败而不会采用旧缓存。
44
+
45
+ 支持 Excel 共享公式:先校验每个工作表内的共享组、主公式和引用范围,再展开各单元格的相对/绝对引用,执行公式安全检查并由 Excel 重算隔离副本。缺少或重复主公式、越界成员及不可安全展开的公式会明确失败;数组公式和数据表公式仍不支持。源工作簿保持不变,差异比较使用本次重算得到的最终值快照。
46
+
47
+ 计算完成后直接校验 Excel 保存的公式缓存类型、错误和缺失结果,不再通过 COM 逐单元格遍历格式范围。三方版本的计算错误保留原公式、错误与位置,作为未知值进入界面;必须选择有效来源,错误涉及无法可靠确认的记录身份、表头或行列结构时需选择整个 Sheet。双方同一记录、同一字段都报错,且有一致的显式基础类型时,数值自动替换为 0、string 为 `""`、bool 为 false;ID、引用、约束字段、未知类型及重复 ID 不自动替换。替换只发生在审阅快照,原始表不变,界面与提交信息记录替代值。未处理错误不能写入结果。外链、宏/UDF、volatile、循环引用、缺失缓存等安全限制保持不变。
48
+
49
+ ### Quick start
50
+
51
+ ```bash
52
+ # 检测未合并的 .xlsx/.xlsm(输出 JSON)
53
+ xlmerge --repo <仓库路径> detect
54
+
55
+ # 可选:把无需逐 Cell 审查的生成表加入仓库过滤列表
56
+ xlmerge --repo <仓库路径> filter add locale/Key.xlsx
57
+
58
+ # 提取三方版本并后台启动可视化解析器,返回 url(自动打开浏览器)
59
+ xlmerge --repo <仓库路径> launch
60
+ ```
61
+
62
+ 环境变量:
63
+
64
+ | 变量 | 作用 |
65
+ |------|------|
66
+ | `XLMERGE_PYTHON` | 指定解释器路径(如嵌入式 Python),跳过自动探测 |
67
+ | `XLMERGE_VENV` | 覆盖默认 venv 目录 |
68
+ | `XLMERGE_EXCEL_TIMEOUT_SECONDS` | 单个工作簿通过 Excel 隔离重算的硬超时,默认 120 秒 |
69
+
70
+ ## Usage
71
+
72
+ ```bash
73
+ # 检测未合并的 .xlsx/.xlsm(输出 JSON)
74
+ xlmerge --repo <仓库路径> detect
75
+
76
+ # 添加整表过滤项(写入仓库根目录 .xlmerge.json)
77
+ xlmerge --repo <仓库路径> filter add <相对路径或路径后缀.xlsx>
78
+
79
+ # 提取三方版本并后台启动可视化解析器,返回 url(自动打开浏览器)
80
+ xlmerge --repo <仓库路径> launch
81
+
82
+ # 只处理单个文件
83
+ xlmerge --repo <仓库路径> launch --path new_meta/Items.xlsx
84
+
85
+ # 前台阻塞式运行(与 launch 等价,进程前台等待完成)
86
+ xlmerge --repo <仓库路径> resolve
87
+
88
+ # 非交互(自动化/CI):先 prepare 再 apply
89
+ xlmerge --repo <仓库路径> prepare
90
+ xlmerge --repo <仓库路径> apply --manifest <manifest.json> --decisions <decisions.json> [--no-commit] [--message <text>] [--push]
91
+ ```
92
+
93
+ `--repo` 缺省为当前目录(向上查找 Git 根)。
94
+
95
+ 过滤列表默认为空,保存在仓库根目录的 `.xlmerge.json`:
96
+
97
+ ```json
98
+ {
99
+ "autoTheirs": [
100
+ "locale/Key.xlsx"
101
+ ]
102
+ }
103
+ ```
104
+
105
+ 过滤项按路径段做不区分大小写的后缀匹配。命中的冲突工作簿不做 Cell 分析,而是逐字节采用 Git stage 3(theirs)并随同本批次提交;如果整批冲突都命中过滤项,`launch`/`resolve` 会直接写回并提交,不启动空白 UI。命令可重复执行,已有项不会重复写入。
106
+
107
+ decisions.json 格式(Cell 用 manifest 中的稳定逻辑 ID,如 `row:base:4|name`):
108
+
109
+ ```json
110
+ {
111
+ "files": {
112
+ "new_meta/Items.xlsx": {
113
+ "sheets": {
114
+ "Items": { "cells": { "row:base:4|name": "theirs" } }
115
+ }
116
+ }
117
+ }
118
+ }
119
+ ```
120
+
121
+ ### Agent 调用规范
122
+
123
+ 包根 `AGENTS.md` 是 AI Agent 调用规范正本,包含适用场景、快速流程、禁止事项与边界。首次通过 v-cli 调用前应运行 `v-cli agent docs xlmerge` 掌握该规范;独立安装时也可直接读取包内 `AGENTS.md`。
124
+
125
+ ## Development
126
+
127
+ ```bash
128
+ # 单元测试(覆盖引擎、公式安全、原子写回、过滤配置与大请求体全流程)
129
+ python -m unittest discover -s python/tests -v
130
+
131
+ # 可选:调用本机 Excel 的真实公式重算回归(仅操作临时目录)
132
+ $env:XLSX_EXCEL_E2E=1; python -m unittest discover -s python/tests -v
133
+
134
+ # 校验 v-cli.plugin.json 与 CLI 解析器未漂移(命令/选项/副作用覆盖)
135
+ npm run check:manifest
136
+
137
+ # 端到端(构造真实冲突仓库 -> detect -> launch -> API 决策 -> 写回提交)
138
+ python e2e_test.py bin/xlmerge.js node
139
+
140
+ # 打包
141
+ npm pack
142
+ ```
143
+
144
+ ### 包结构
145
+
146
+ ```
147
+ bin/xlmerge.js # Node 启动垫片:探测 Python、按需建 venv、透传参数
148
+ AGENTS.md # AI Agent 调用规范正本(场景/规范/流程/边界)
149
+ v-cli.plugin.json # Agent 插件清单(命令/选项/副作用),与 CLI 解析器做漂移校验
150
+ python/
151
+ ├── xlsx_merge_engine/ # 三方结构化差异引擎(可独立 CLI 调试)
152
+ │ └── xlsx_git_merge_bridge.py
153
+ ├── xlsx_resolver/ # 冲突解析器、公式值快照与 bottle UI
154
+ └── tests/ # 引擎与解析器测试(不随 npm 包发布)
155
+ ```
156
+
157
+ > 注:为兼容嵌入式 Python 发行版(`._pth` 忽略 `PYTHONPATH`),模块内通过自举 `sys.path` 注入定位依赖,勿改为纯包导入。
158
+
159
+ ## Package family
160
+
161
+ kevlns 工具家族共享同一套发布约定(tag 驱动、CI 护栏、MIT)。
162
+
163
+ | Package | Purpose | Version |
164
+ | --- | --- | --- |
165
+ | [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI | v0.2.14 |
166
+ | [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具(本仓库) | v2.0.0 |
167
+ | [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包(Windows-first) | v0.2.3 |
168
+ | [`figma-to-uprefab`](https://github.com/kevlns/figma-to-uprefab) | Figma 导出、契约校验与 Unity UGUI staging Prefab 构建 | v0.1.1 |
169
+
170
+ ## Compatibility
171
+
172
+ | Runtime | Supported versions |
173
+ | --- | --- |
174
+ | Node.js | `16` and later |
175
+ | Python | `3.9` and later |
176
+ | Excel formula calculation | Windows desktop Excel; formula-free workbooks remain cross-platform |
177
+
178
+ ## Contributing
179
+
180
+ ```bash
181
+ git clone https://github.com/kevlns/xlmerge.git
182
+ cd xlmerge
183
+ python -m unittest discover -s python/tests -v
184
+ npm run check:manifest
185
+ ```
186
+
187
+ For bugs and feature requests, use [GitHub Issues](https://github.com/kevlns/xlmerge/issues).
188
+
189
+ ## License
190
+
191
+ Released under the [MIT License](./LICENSE).
192
+
193
+ <div align="center">
194
+
195
+ Part of the **kevlns** tool family.
196
+
197
+ </div>