@kevlns/xlmerge 1.2.1-beta.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/LICENSE +21 -0
- package/README.md +99 -0
- package/bin/xlmerge.js +152 -0
- package/package.json +43 -0
- package/python/xlsx_merge_engine/__init__.py +2 -0
- package/python/xlsx_merge_engine/xlsx_git_merge_bridge.py +1581 -0
- package/python/xlsx_resolver/__init__.py +2 -0
- package/python/xlsx_resolver/__main__.py +4 -0
- package/python/xlsx_resolver/merge_server.py +105 -0
- package/python/xlsx_resolver/merge_ui.html +1222 -0
- package/python/xlsx_resolver/resolve_xlsx_conflict.py +159 -0
- package/python/xlsx_resolver/xlsx_conflict.py +1478 -0
- package/skill/SKILL.md +114 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 kevlns <936277610@qq.com>
|
|
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
ADDED
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# xlmerge
|
|
2
|
+
|
|
3
|
+
解决 Git 仓库中 `.xlsx` / `.xlsm` 策划配置表的未合并冲突(merge conflict)。
|
|
4
|
+
|
|
5
|
+
三方结构化差异引擎 + 本地可视化 UI:自动提取 Git index 的 base/ours/theirs 三方版本,按 Sheet、逻辑行、逻辑列、Cell 四级计算差异,浏览器中逐 Cell 选择本地/远端版本,最终写回工作簿并生成结构化 commit。冲突身份使用逻辑 ID(非物理坐标),插行删行后选择不会漂移。
|
|
6
|
+
|
|
7
|
+
- 保留公式(注入缓存值,`data_only` 读取正确)、样式、批注、合并单元格、冻结窗格、行高列宽
|
|
8
|
+
- `.xlsm` 全程 `keep_vba`,保存后逐字节校验 VBA/ActiveX 负载
|
|
9
|
+
- 自动识别 Luban 风格表头(`##var` / `##type` / `##group`),注释列、占位列参与对齐
|
|
10
|
+
- 服务只监听 `127.0.0.1`,不自动 push
|
|
11
|
+
|
|
12
|
+
## 安装
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
# beta 阶段请显式安装预发布版本
|
|
16
|
+
npm install -g @kevlns/xlmerge@beta
|
|
17
|
+
|
|
18
|
+
# 或直接从 GitHub 仓库安装开发版本
|
|
19
|
+
npm install -g git+https://github.com/kevlns/xlmerge.git
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
发布稳定版并设置 `latest` 标签后,可直接使用 `npm install -g @kevlns/xlmerge`。
|
|
23
|
+
|
|
24
|
+
要求:Node.js >= 16,系统 Python >= 3.9。首次运行若缺少依赖,会在 `~/.xlmerge/venv` 自动创建用户级 venv 并安装 `openpyxl==3.1.5`、`bottle==0.13.4`。
|
|
25
|
+
|
|
26
|
+
环境变量:
|
|
27
|
+
|
|
28
|
+
| 变量 | 作用 |
|
|
29
|
+
|------|------|
|
|
30
|
+
| `XLMERGE_PYTHON` | 指定解释器路径(如嵌入式 Python),跳过自动探测 |
|
|
31
|
+
| `XLMERGE_VENV` | 覆盖默认 venv 目录 |
|
|
32
|
+
|
|
33
|
+
## 使用
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
# 检测未合并的 .xlsx/.xlsm(输出 JSON)
|
|
37
|
+
xlmerge --repo <仓库路径> detect
|
|
38
|
+
|
|
39
|
+
# 提取三方版本并后台启动可视化解析器,返回 url(自动打开浏览器)
|
|
40
|
+
xlmerge --repo <仓库路径> launch
|
|
41
|
+
|
|
42
|
+
# 只处理单个文件
|
|
43
|
+
xlmerge --repo <仓库路径> launch --path new_meta/Items.xlsx
|
|
44
|
+
|
|
45
|
+
# 非交互(自动化/CI):先 prepare 再 apply
|
|
46
|
+
xlmerge --repo <仓库路径> prepare
|
|
47
|
+
xlmerge --repo <仓库路径> apply --manifest <manifest.json> --decisions <decisions.json> [--no-commit] [--push]
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`--repo` 缺省为当前目录(向上查找 Git 根)。
|
|
51
|
+
|
|
52
|
+
decisions.json 格式(Cell 用 manifest 中的稳定逻辑 ID,如 `row:base:4|name`):
|
|
53
|
+
|
|
54
|
+
```json
|
|
55
|
+
{
|
|
56
|
+
"files": {
|
|
57
|
+
"new_meta/Items.xlsx": {
|
|
58
|
+
"sheets": {
|
|
59
|
+
"Items": { "cells": { "row:base:4|name": "theirs" } }
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
### 作为 Agent Skill 使用
|
|
67
|
+
|
|
68
|
+
`skill/SKILL.md` 为技能文档,可复制(或软链)到目标 Agent 的 skills 目录(如 `.claude/skills/xlmerge/`、`~/.pi/agent/skills/`)。Skill 要求模型只做命令路由:`detect` -> `launch` -> 等待用户在 UI 完成 Cell 选择,禁止模型自行读取或总结 diff。
|
|
69
|
+
|
|
70
|
+
## 开发与测试
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
# 单元测试(63 个,覆盖引擎与解析器全流程)
|
|
74
|
+
python -m unittest discover -s python/tests -v
|
|
75
|
+
|
|
76
|
+
# 端到端(构造真实冲突仓库 -> detect -> launch -> API 决策 -> 写回提交)
|
|
77
|
+
python e2e_test.py bin/xlmerge.js node
|
|
78
|
+
|
|
79
|
+
# 打包
|
|
80
|
+
npm pack
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
## 包结构
|
|
84
|
+
|
|
85
|
+
```
|
|
86
|
+
bin/xlmerge.js # Node 启动垫片:探测 Python、按需建 venv、透传参数
|
|
87
|
+
skill/SKILL.md # Agent Skill 文档
|
|
88
|
+
python/
|
|
89
|
+
├── xlsx_merge_engine/ # 三方结构化差异引擎(可独立 CLI 调试)
|
|
90
|
+
│ └── xlsx_git_merge_bridge.py
|
|
91
|
+
├── xlsx_resolver/ # 冲突解析器(detect/prepare/launch/apply + bottle UI)
|
|
92
|
+
└── tests/ # 引擎与解析器测试
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
> 注:为兼容嵌入式 Python 发行版(`._pth` 忽略 `PYTHONPATH`),模块内使用包内自举的 `sys.path` 注入而非纯包导入;这是有意为之。
|
|
96
|
+
|
|
97
|
+
## License
|
|
98
|
+
|
|
99
|
+
[MIT](LICENSE)
|
package/bin/xlmerge.js
ADDED
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
/**
|
|
3
|
+
* xlmerge 启动垫片:定位可用 Python 解释器后透传参数给包内 CLI。
|
|
4
|
+
* - 解释器优先级:XLMERGE_PYTHON > python3 > python > py -3(需 >= 3.9)
|
|
5
|
+
* - 系统解释器已有 openpyxl/bottle 时直接使用;否则在 ~/.xlmerge/venv
|
|
6
|
+
* 创建用户级 venv 并安装固定版本依赖
|
|
7
|
+
* - 所有诊断信息输出到 stderr,保证 stdout 只有 Python CLI 的 JSON 结果
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
"use strict";
|
|
11
|
+
|
|
12
|
+
const { spawnSync, spawn } = require("child_process");
|
|
13
|
+
const fs = require("fs");
|
|
14
|
+
const os = require("os");
|
|
15
|
+
const path = require("path");
|
|
16
|
+
|
|
17
|
+
const PKG_ROOT = path.resolve(__dirname, "..");
|
|
18
|
+
const ENTRY = path.join(PKG_ROOT, "python", "xlsx_resolver", "resolve_xlsx_conflict.py");
|
|
19
|
+
const PY_ROOT = path.join(PKG_ROOT, "python");
|
|
20
|
+
const VENV_DIR = process.env.XLMERGE_VENV || path.join(os.homedir(), ".xlmerge", "venv");
|
|
21
|
+
const DEPS = ["openpyxl==3.1.5", "bottle==0.13.4"];
|
|
22
|
+
|
|
23
|
+
function log(msg) {
|
|
24
|
+
process.stderr.write(`[xlmerge] ${msg}\n`);
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** 候选解释器命令(数组形式,兼容 "py -3") */
|
|
28
|
+
function candidates() {
|
|
29
|
+
const list = [];
|
|
30
|
+
if (process.env.XLMERGE_PYTHON) list.push([process.env.XLMERGE_PYTHON]);
|
|
31
|
+
if (process.platform !== "win32") list.push(["python3"]);
|
|
32
|
+
list.push(["python"]);
|
|
33
|
+
if (process.platform === "win32") list.push(["py", "-3"]);
|
|
34
|
+
// 去重
|
|
35
|
+
const seen = new Set();
|
|
36
|
+
return list.filter((c) => {
|
|
37
|
+
const key = c.join(" ");
|
|
38
|
+
if (seen.has(key)) return false;
|
|
39
|
+
seen.add(key);
|
|
40
|
+
return true;
|
|
41
|
+
});
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
/** 探测候选解释器,返回 { cmd, version } 或 null */
|
|
45
|
+
function probeInterpreter() {
|
|
46
|
+
for (const cmd of candidates()) {
|
|
47
|
+
let result;
|
|
48
|
+
try {
|
|
49
|
+
result = spawnSync(cmd[0], [...cmd.slice(1), "-c", "import sys; print(sys.version_info >= (3, 9))"], {
|
|
50
|
+
encoding: "utf-8",
|
|
51
|
+
timeout: 20000,
|
|
52
|
+
});
|
|
53
|
+
} catch {
|
|
54
|
+
continue;
|
|
55
|
+
}
|
|
56
|
+
if (result.error || result.status !== 0) continue;
|
|
57
|
+
if (result.stdout.trim() === "True") {
|
|
58
|
+
return cmd;
|
|
59
|
+
}
|
|
60
|
+
if (result.stdout.trim() === "False") {
|
|
61
|
+
log(`跳过 ${cmd.join(" ")}:Python 版本低于 3.9`);
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
return null;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
function venvPython(venvDir) {
|
|
68
|
+
return process.platform === "win32"
|
|
69
|
+
? path.join(venvDir, "Scripts", "python.exe")
|
|
70
|
+
: path.join(venvDir, "bin", "python");
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
function hasDeps(cmd) {
|
|
74
|
+
const result = spawnSync(cmd[0], [...cmd.slice(1), "-c", "import openpyxl, bottle"], {
|
|
75
|
+
encoding: "utf-8",
|
|
76
|
+
timeout: 20000,
|
|
77
|
+
});
|
|
78
|
+
return result.status === 0 && !result.error;
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/** 确保依赖可用:优先系统解释器,其次用户级 venv;返回解释器命令 */
|
|
82
|
+
function ensureInterpreter() {
|
|
83
|
+
const system = probeInterpreter();
|
|
84
|
+
if (!system) {
|
|
85
|
+
log("未找到可用的 Python >= 3.9,请安装 Python 或设置 XLMERGE_PYTHON 指向解释器路径。");
|
|
86
|
+
process.exit(1);
|
|
87
|
+
}
|
|
88
|
+
if (hasDeps(system)) return system;
|
|
89
|
+
|
|
90
|
+
const vpy = venvPython(VENV_DIR);
|
|
91
|
+
if (fs.existsSync(vpy)) {
|
|
92
|
+
if (hasDeps([vpy])) return [vpy];
|
|
93
|
+
log("已有 venv 缺少依赖,重新安装...");
|
|
94
|
+
} else {
|
|
95
|
+
log(`系统 Python 缺少 openpyxl/bottle,创建用户级 venv:${VENV_DIR}`);
|
|
96
|
+
const created = spawnSync(system[0], [...system.slice(1), "-m", "venv", VENV_DIR], {
|
|
97
|
+
stdio: ["ignore", "ignore", "inherit"],
|
|
98
|
+
timeout: 180000,
|
|
99
|
+
});
|
|
100
|
+
if (created.status !== 0) {
|
|
101
|
+
log("venv 创建失败,请手动执行:python -m venv \"" + VENV_DIR + '" 并 pip 安装 ' + DEPS.join(" "));
|
|
102
|
+
process.exit(1);
|
|
103
|
+
}
|
|
104
|
+
}
|
|
105
|
+
const installed = spawnSync(vpy, ["-m", "pip", "install", "--quiet", ...DEPS], {
|
|
106
|
+
stdio: ["ignore", "ignore", "inherit"],
|
|
107
|
+
timeout: 600000,
|
|
108
|
+
});
|
|
109
|
+
if (installed.status !== 0) {
|
|
110
|
+
log(`pip 安装失败(${DEPS.join(" ")}),请检查网络或手动安装。`);
|
|
111
|
+
process.exit(1);
|
|
112
|
+
}
|
|
113
|
+
return [vpy];
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
function main() {
|
|
117
|
+
if (!fs.existsSync(ENTRY)) {
|
|
118
|
+
log(`找不到入口脚本:${ENTRY}`);
|
|
119
|
+
process.exit(1);
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
if (process.argv.includes("--selfcheck")) {
|
|
123
|
+
const system = probeInterpreter();
|
|
124
|
+
const cmd = system ? ensureInterpreter() : null;
|
|
125
|
+
process.stdout.write(
|
|
126
|
+
JSON.stringify(
|
|
127
|
+
{
|
|
128
|
+
ok: Boolean(cmd),
|
|
129
|
+
entry: ENTRY,
|
|
130
|
+
python: cmd ? cmd.join(" ") : null,
|
|
131
|
+
venv: fs.existsSync(venvPython(VENV_DIR)) ? VENV_DIR : null,
|
|
132
|
+
},
|
|
133
|
+
null,
|
|
134
|
+
2,
|
|
135
|
+
) + "\n",
|
|
136
|
+
);
|
|
137
|
+
process.exit(cmd ? 0 : 1);
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
const cmd = ensureInterpreter();
|
|
141
|
+
const child = spawn(cmd[0], [...cmd.slice(1), ENTRY, ...process.argv.slice(2)], {
|
|
142
|
+
stdio: "inherit",
|
|
143
|
+
env: process.env,
|
|
144
|
+
});
|
|
145
|
+
child.on("error", (err) => {
|
|
146
|
+
log(`启动失败:${err.message}`);
|
|
147
|
+
process.exit(1);
|
|
148
|
+
});
|
|
149
|
+
child.on("exit", (code) => process.exit(code === null ? 1 : code));
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
main();
|
package/package.json
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@kevlns/xlmerge",
|
|
3
|
+
"version": "1.2.1-beta.1",
|
|
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
|
+
"bin": {
|
|
6
|
+
"xlmerge": "bin/xlmerge.js"
|
|
7
|
+
},
|
|
8
|
+
"files": [
|
|
9
|
+
"bin/",
|
|
10
|
+
"skill/",
|
|
11
|
+
"python/xlsx_merge_engine/",
|
|
12
|
+
"python/xlsx_resolver/"
|
|
13
|
+
],
|
|
14
|
+
"scripts": {
|
|
15
|
+
"test": "node bin/xlmerge.js --selfcheck",
|
|
16
|
+
"test:python": "python -m unittest discover -s python/tests -v"
|
|
17
|
+
},
|
|
18
|
+
"repository": {
|
|
19
|
+
"type": "git",
|
|
20
|
+
"url": "git+https://github.com/kevlns/xlmerge.git"
|
|
21
|
+
},
|
|
22
|
+
"homepage": "https://github.com/kevlns/xlmerge#readme",
|
|
23
|
+
"bugs": {
|
|
24
|
+
"url": "https://github.com/kevlns/xlmerge/issues"
|
|
25
|
+
},
|
|
26
|
+
"author": "kevlns <936277610@qq.com>",
|
|
27
|
+
"engines": {
|
|
28
|
+
"node": ">=16"
|
|
29
|
+
},
|
|
30
|
+
"private": false,
|
|
31
|
+
"publishConfig": {
|
|
32
|
+
"access": "public"
|
|
33
|
+
},
|
|
34
|
+
"license": "MIT",
|
|
35
|
+
"keywords": [
|
|
36
|
+
"xlsx",
|
|
37
|
+
"xlsm",
|
|
38
|
+
"git",
|
|
39
|
+
"merge-conflict",
|
|
40
|
+
"excel",
|
|
41
|
+
"agent-skill"
|
|
42
|
+
]
|
|
43
|
+
}
|