@kevlns/xlmerge 1.3.1 → 2.0.1

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,183 +1,193 @@
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` 策划配置表未合并冲突(merge conflict)的可视化工具。**
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
- - **保真写回** - 保留公式(注入缓存值,`data_only` 读取正确)、样式、批注、合并单元格、冻结窗格、行高列宽
26
- - **VBA 安全** - `.xlsm` 全程 `keep_vba`,保存后逐字节校验 VBA/ActiveX 负载
27
- - **Luban 表头识别** - 自动识别 `##var` / `##type` / `##group`,注释列、占位列参与对齐
28
- - **可配置整表过滤** - 仓库可把生成表加入过滤列表;命中时直接采用 Git stage 3 的远端原始文件
29
- - **默认不越权** - 服务只监听 `127.0.0.1`,不自动 push
30
-
31
- ## Getting started
32
-
33
- ### Install
34
-
35
- ```bash
36
- npm install -g @kevlns/xlmerge
37
-
38
- # 或直接从 GitHub 仓库安装开发版本
39
- npm install -g git+https://github.com/kevlns/xlmerge.git
40
- ```
41
-
42
- 要求:Node.js >= 16,系统 Python >= 3.9。首次运行若缺少依赖,会在 `~/.xlmerge/venv` 自动创建用户级 venv 并安装 `openpyxl==3.1.5`、`bottle==0.13.4`。
43
-
44
- ### Quick start
45
-
46
- ```bash
47
- # 检测未合并的 .xlsx/.xlsm(输出 JSON)
48
- xlmerge --repo <仓库路径> detect
49
-
50
- # 可选:把无需逐 Cell 审查的生成表加入仓库过滤列表
51
- xlmerge --repo <仓库路径> filter add locale/Key.xlsx
52
-
53
- # 提取三方版本并后台启动可视化解析器,返回 url(自动打开浏览器)
54
- xlmerge --repo <仓库路径> launch
55
- ```
56
-
57
- 环境变量:
58
-
59
- | 变量 | 作用 |
60
- |------|------|
61
- | `XLMERGE_PYTHON` | 指定解释器路径(如嵌入式 Python),跳过自动探测 |
62
- | `XLMERGE_VENV` | 覆盖默认 venv 目录 |
63
-
64
- ## Usage
65
-
66
- ```bash
67
- # 检测未合并的 .xlsx/.xlsm(输出 JSON)
68
- xlmerge --repo <仓库路径> detect
69
-
70
- # 添加整表过滤项(写入仓库根目录 .xlmerge.json)
71
- xlmerge --repo <仓库路径> filter add <相对路径或路径后缀.xlsx>
72
-
73
- # 提取三方版本并后台启动可视化解析器,返回 url(自动打开浏览器)
74
- xlmerge --repo <仓库路径> launch
75
-
76
- # 只处理单个文件
77
- xlmerge --repo <仓库路径> launch --path new_meta/Items.xlsx
78
-
79
- # 非交互(自动化/CI):先 prepare 再 apply
80
- xlmerge --repo <仓库路径> prepare
81
- xlmerge --repo <仓库路径> apply --manifest <manifest.json> --decisions <decisions.json> [--no-commit] [--push]
82
- ```
83
-
84
- `--repo` 缺省为当前目录(向上查找 Git 根)。
85
-
86
- 过滤列表默认为空,保存在仓库根目录的 `.xlmerge.json`:
87
-
88
- ```json
89
- {
90
- "autoTheirs": [
91
- "locale/Key.xlsx"
92
- ]
93
- }
94
- ```
95
-
96
- 过滤项按路径段做不区分大小写的后缀匹配。命中的冲突工作簿不做 Cell 分析,而是逐字节采用 Git stage 3(theirs)并随同本批次提交;如果整批冲突都命中过滤项,`launch`/`resolve` 会直接写回并提交,不启动空白 UI。命令可重复执行,已有项不会重复写入。
97
-
98
- decisions.json 格式(Cell 用 manifest 中的稳定逻辑 ID,如 `row:base:4|name`):
99
-
100
- ```json
101
- {
102
- "files": {
103
- "new_meta/Items.xlsx": {
104
- "sheets": {
105
- "Items": { "cells": { "row:base:4|name": "theirs" } }
106
- }
107
- }
108
- }
109
- }
110
- ```
111
-
112
- ### Agent 调用规范
113
-
114
- 包根 `AGENTS.md` 是 AI Agent 调用规范正本,包含适用场景、快速流程、禁止事项与边界。首次通过 v-cli 调用前应运行 `v-cli agent docs xlmerge` 掌握该规范;独立安装时也可直接读取包内 `AGENTS.md`。
115
-
116
- ## Development
117
-
118
- ```bash
119
- # 单元测试(覆盖引擎、解析器、过滤配置与大请求体全流程)
120
- python -m unittest discover -s python/tests -v
121
-
122
- # 校验 v-cli.plugin.json 与 CLI 解析器未漂移(命令/选项/副作用覆盖)
123
- npm run check:manifest
124
-
125
- # 端到端(构造真实冲突仓库 -> detect -> launch -> API 决策 -> 写回提交)
126
- python e2e_test.py bin/xlmerge.js node
127
-
128
- # 打包
129
- npm pack
130
- ```
131
-
132
- ### 包结构
133
-
134
- ```
135
- bin/xlmerge.js # Node 启动垫片:探测 Python、按需建 venv、透传参数
136
- AGENTS.md # AI Agent 调用规范正本(场景/规范/流程/边界)
137
- v-cli.plugin.json # Agent 插件清单(命令/选项/副作用),与 CLI 解析器做漂移校验
138
- python/
139
- ├── xlsx_merge_engine/ # 三方结构化差异引擎(可独立 CLI 调试)
140
- │ └── xlsx_git_merge_bridge.py
141
- ├── xlsx_resolver/ # 冲突解析器(detect/prepare/launch/apply + bottle UI)
142
- └── tests/ # 引擎与解析器测试(不随 npm 包发布)
143
- ```
144
-
145
- > 注:为兼容嵌入式 Python 发行版(`._pth` 忽略 `PYTHONPATH`),模块内使用包内自举的 `sys.path` 注入而非纯包导入;这是有意为之。
146
-
147
- ## Package family
148
-
149
- kevlns 工具家族共享同一套发布约定(tag 驱动、CI 护栏、MIT)。
150
-
151
- | Package | Purpose | Status |
152
- | --- | --- | --- |
153
- | [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI | v0.2.3 |
154
- | [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具(本仓库) | v1.3.1 |
155
- | [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包(Windows-first) | v0.1.4 |
156
-
157
- ## Compatibility
158
-
159
- | Runtime | Supported versions |
160
- | --- | --- |
161
- | Node.js | `16` and later |
162
- | Python | `3.9` and later |
163
-
164
- ## Contributing
165
-
166
- ```bash
167
- git clone https://github.com/kevlns/xlmerge.git
168
- cd xlmerge
169
- python -m unittest discover -s python/tests -v
170
- npm run check:manifest
171
- ```
172
-
173
- For bugs and feature requests, use [GitHub Issues](https://github.com/kevlns/xlmerge/issues).
174
-
175
- ## License
176
-
177
- Released under the [MIT License](./LICENSE).
178
-
179
- <div align="center">
180
-
181
- Part of the **kevlns** tool family.
182
-
183
- </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
+ ### 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>