@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 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
+ }
@@ -0,0 +1,2 @@
1
+ # -*- coding: utf-8 -*-
2
+ """XLSX/XLSM 三方结构化差异引擎(源自 XlsxGitMergeBridge)。"""