@kevlns/xlmerge 1.2.1-beta.5 → 1.2.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.
Files changed (3) hide show
  1. package/AGENTS.md +1 -1
  2. package/README.md +76 -15
  3. package/package.json +1 -1
package/AGENTS.md CHANGED
@@ -9,7 +9,7 @@ xlmerge --repo <repo> detect
9
9
  xlmerge --repo <repo> launch
10
10
  ```
11
11
 
12
- `npx` 等价:`npx --package @kevlns/xlmerge@beta xlmerge --repo <repo> detect`。
12
+ `npx` 等价:`npx --package @kevlns/xlmerge@latest xlmerge --repo <repo> detect`。
13
13
 
14
14
  ## 何时使用
15
15
 
package/README.md CHANGED
@@ -1,28 +1,55 @@
1
+ <div align="center">
2
+
3
+ <img src="https://raw.githubusercontent.com/kevlns/xlmerge/main/logo.png" alt="xlmerge logo" width="320" />
4
+
1
5
  # xlmerge
2
6
 
3
- 解决 Git 仓库中 `.xlsx` / `.xlsm` 策划配置表的未合并冲突(merge conflict)。
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>
4
17
 
5
- 三方结构化差异引擎 + 本地可视化 UI:自动提取 Git index 的 base/ours/theirs 三方版本,按 Sheet、逻辑行、逻辑列、Cell 四级计算差异,浏览器中逐 Cell 选择本地/远端版本,最终写回工作簿并生成结构化 commit。冲突身份使用逻辑 ID(非物理坐标),插行删行后选择不会漂移。
18
+ ---
6
19
 
7
- - 保留公式(注入缓存值,`data_only` 读取正确)、样式、批注、合并单元格、冻结窗格、行高列宽
8
- - `.xlsm` 全程 `keep_vba`,保存后逐字节校验 VBA/ActiveX 负载
9
- - 自动识别 Luban 风格表头(`##var` / `##type` / `##group`),注释列、占位列参与对齐
10
- - 服务只监听 `127.0.0.1`,不自动 push
20
+ ## Why xlmerge?
11
21
 
12
- ## 安装
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
+ - **默认不越权** - 服务只监听 `127.0.0.1`,不自动 push
29
+
30
+ ## Getting started
31
+
32
+ ### Install
13
33
 
14
34
  ```bash
15
- # beta 阶段请显式安装预发布版本
16
- npm install -g @kevlns/xlmerge@beta
35
+ npm install -g @kevlns/xlmerge
17
36
 
18
37
  # 或直接从 GitHub 仓库安装开发版本
19
38
  npm install -g git+https://github.com/kevlns/xlmerge.git
20
39
  ```
21
40
 
22
- 发布稳定版并设置 `latest` 标签后,可直接使用 `npm install -g @kevlns/xlmerge`。
23
-
24
41
  要求:Node.js >= 16,系统 Python >= 3.9。首次运行若缺少依赖,会在 `~/.xlmerge/venv` 自动创建用户级 venv 并安装 `openpyxl==3.1.5`、`bottle==0.13.4`。
25
42
 
43
+ ### Quick start
44
+
45
+ ```bash
46
+ # 检测未合并的 .xlsx/.xlsm(输出 JSON)
47
+ xlmerge --repo <仓库路径> detect
48
+
49
+ # 提取三方版本并后台启动可视化解析器,返回 url(自动打开浏览器)
50
+ xlmerge --repo <仓库路径> launch
51
+ ```
52
+
26
53
  环境变量:
27
54
 
28
55
  | 变量 | 作用 |
@@ -30,7 +57,7 @@ npm install -g git+https://github.com/kevlns/xlmerge.git
30
57
  | `XLMERGE_PYTHON` | 指定解释器路径(如嵌入式 Python),跳过自动探测 |
31
58
  | `XLMERGE_VENV` | 覆盖默认 venv 目录 |
32
59
 
33
- ## 使用
60
+ ## Usage
34
61
 
35
62
  ```bash
36
63
  # 检测未合并的 .xlsx/.xlsm(输出 JSON)
@@ -67,7 +94,7 @@ decisions.json 格式(Cell 用 manifest 中的稳定逻辑 ID,如 `row:base:
67
94
 
68
95
  包根 `AGENTS.md` 是 AI Agent 调用规范正本,包含适用场景、快速流程、禁止事项与边界。首次通过 v-cli 调用前应运行 `v-cli agent docs xlmerge` 掌握该规范;独立安装时也可直接读取包内 `AGENTS.md`。
69
96
 
70
- ## 开发与测试
97
+ ## Development
71
98
 
72
99
  ```bash
73
100
  # 单元测试(72 个,覆盖引擎与解析器全流程)
@@ -83,7 +110,7 @@ python e2e_test.py bin/xlmerge.js node
83
110
  npm pack
84
111
  ```
85
112
 
86
- ## 包结构
113
+ ### 包结构
87
114
 
88
115
  ```
89
116
  bin/xlmerge.js # Node 启动垫片:探测 Python、按需建 venv、透传参数
@@ -98,6 +125,40 @@ python/
98
125
 
99
126
  > 注:为兼容嵌入式 Python 发行版(`._pth` 忽略 `PYTHONPATH`),模块内使用包内自举的 `sys.path` 注入而非纯包导入;这是有意为之。
100
127
 
128
+ ## Package family
129
+
130
+ kevlns 工具家族共享同一套发布约定(tag 驱动、CI 护栏、MIT)。
131
+
132
+ | Package | Purpose | Status |
133
+ | --- | --- | --- |
134
+ | [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI | v0.2.1 |
135
+ | [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具(本仓库) | v1.2.2 |
136
+ | [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包(Windows-first) | v0.1.1 |
137
+
138
+ ## Compatibility
139
+
140
+ | Runtime | Supported versions |
141
+ | --- | --- |
142
+ | Node.js | `16` and later |
143
+ | Python | `3.9` and later |
144
+
145
+ ## Contributing
146
+
147
+ ```bash
148
+ git clone https://github.com/kevlns/xlmerge.git
149
+ cd xlmerge
150
+ python -m unittest discover -s python/tests -v
151
+ npm run check:manifest
152
+ ```
153
+
154
+ For bugs and feature requests, use [GitHub Issues](https://github.com/kevlns/xlmerge/issues).
155
+
101
156
  ## License
102
157
 
103
- [MIT](LICENSE)
158
+ Released under the [MIT License](./LICENSE).
159
+
160
+ <div align="center">
161
+
162
+ Part of the **kevlns** tool family.
163
+
164
+ </div>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kevlns/xlmerge",
3
- "version": "1.2.1-beta.5",
3
+ "version": "1.2.2",
4
4
  "description": "Visual resolver for unresolved Git merge conflicts in .xlsx/.xlsm workbooks: three-way sheet/row/cell diff, local UI, write-back and commit.",
5
5
  "bin": {
6
6
  "xlmerge": "bin/xlmerge.js"