@kevlns/xlmerge 2.0.1 → 2.0.3
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/AGENTS.md +169 -141
- package/LICENSE +21 -21
- package/README.md +111 -193
- package/bin/xlmerge.js +152 -152
- package/docs/documentation.md +24 -0
- package/package.json +7 -5
- package/python/xlsx_merge_engine/__init__.py +2 -2
- package/python/xlsx_merge_engine/xlsx_git_merge_bridge.py +1614 -1611
- package/python/xlsx_resolver/__init__.py +2 -2
- package/python/xlsx_resolver/__main__.py +4 -4
- package/python/xlsx_resolver/formula_values.py +660 -565
- package/python/xlsx_resolver/loading_ui.html +44 -0
- package/python/xlsx_resolver/merge_server.py +179 -126
- package/python/xlsx_resolver/merge_ui.html +1634 -1522
- package/python/xlsx_resolver/prepare_progress.py +34 -0
- package/python/xlsx_resolver/recalculate_workbook.ps1 +141 -155
- package/python/xlsx_resolver/resolve_xlsx_conflict.py +236 -222
- package/python/xlsx_resolver/xlsx_conflict.py +2317 -1994
- package/v-cli.plugin.json +248 -194
package/README.md
CHANGED
|
@@ -1,193 +1,111 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
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
|
+
# Vant 表格合并工具
|
|
2
|
+
|
|
3
|
+
`@kevlns/xlmerge`
|
|
4
|
+
|
|
5
|
+
## 功能
|
|
6
|
+
|
|
7
|
+
在浏览器中审阅 Git 冲突工作簿的三方差异,校验后写回并提交合并结果。
|
|
8
|
+
|
|
9
|
+
## 环境要求
|
|
10
|
+
|
|
11
|
+
Node.js 16 及以上、Python 3.9 及以上;包含公式的工作簿需要 Windows 桌面版 Excel 生成可靠的计算快照。
|
|
12
|
+
|
|
13
|
+
## 安装
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
npm install -g @kevlns/xlmerge
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
## 快速开始
|
|
20
|
+
|
|
21
|
+
```sh
|
|
22
|
+
xlmerge --repo <仓库目录> detect
|
|
23
|
+
xlmerge --repo <仓库目录> launch
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## 使用说明
|
|
27
|
+
|
|
28
|
+
### 功能说明
|
|
29
|
+
|
|
30
|
+
Git 对二进制 `.xlsx`/`.xlsm` 只会整文件冲突,无法像文本一样逐行合并。xlmerge 用**公式最终值快照 + 三方结构化差异引擎 + 本地可视化 UI**把这件事变得可控:自动提取 Git index 的 base/ours/theirs 三方版本,按 Sheet、逻辑行、逻辑列、Cell 四级计算差异,浏览器中逐 Cell 选择本地/远端版本,最终原子写回工作簿并生成结构化 commit。
|
|
31
|
+
|
|
32
|
+
- **逻辑 ID 定位** - 冲突身份用逻辑 ID(非物理坐标),插行删行后选择不会漂移
|
|
33
|
+
- **公式感知** - 三方工作簿先各自完整计算;diff 使用最终值,受影响 Sheet 固化为静态值,未受影响 Sheet 保留原公式及缓存
|
|
34
|
+
- **安全写回** - apply 校验三方来源、值快照与工作树指纹;批次替换失败自动回滚,并保留所选来源的样式、批注、合并单元格、冻结窗格、行高列宽
|
|
35
|
+
- **VBA 安全** - `.xlsm` 全程 `keep_vba`,保存后逐字节校验 VBA/ActiveX 负载
|
|
36
|
+
- **Luban 表头识别** - 自动识别 `##var` / `##type` / `##group`,注释列、占位列参与对齐
|
|
37
|
+
- **可配置整表过滤** - 仓库可把生成表加入过滤列表;命中时直接采用 Git stage 3 的远端原始文件
|
|
38
|
+
- **默认不越权** - 服务只监听 `127.0.0.1`,不自动 push
|
|
39
|
+
|
|
40
|
+
### 操作流程
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
# 检测未合并的 .xlsx/.xlsm(输出 JSON)
|
|
44
|
+
xlmerge --repo <仓库路径> detect
|
|
45
|
+
|
|
46
|
+
# 添加整表过滤项(写入仓库根目录 .xlmerge.json)
|
|
47
|
+
xlmerge --repo <仓库路径> filter add <相对路径或路径后缀.xlsx>
|
|
48
|
+
|
|
49
|
+
# 提取三方版本并后台启动可视化解析器,返回 url(自动打开浏览器)
|
|
50
|
+
xlmerge --repo <仓库路径> launch
|
|
51
|
+
|
|
52
|
+
# 只处理单个文件
|
|
53
|
+
xlmerge --repo <仓库路径> launch --path new_meta/Items.xlsx
|
|
54
|
+
|
|
55
|
+
# 前台阻塞式运行(与 launch 等价,进程前台等待完成)
|
|
56
|
+
xlmerge --repo <仓库路径> resolve
|
|
57
|
+
|
|
58
|
+
# 非交互(自动化/CI):先 prepare 再 apply
|
|
59
|
+
xlmerge --repo <仓库路径> prepare
|
|
60
|
+
xlmerge --repo <仓库路径> apply --manifest <manifest.json> --decisions <decisions.json> [--no-commit] [--message <text>] [--push]
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
`--repo` 缺省为当前目录(向上查找 Git 根)。
|
|
64
|
+
|
|
65
|
+
过滤列表默认为空,保存在仓库根目录的 `.xlmerge.json`:
|
|
66
|
+
|
|
67
|
+
```json
|
|
68
|
+
{
|
|
69
|
+
"autoTheirs": [
|
|
70
|
+
"locale/Key.xlsx"
|
|
71
|
+
]
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
过滤项按路径段做不区分大小写的后缀匹配。命中的冲突工作簿不做 Cell 分析,而是逐字节采用 Git stage 3(theirs)并随同本批次提交;如果整批冲突都命中过滤项,`launch`/`resolve` 会直接写回并提交,不启动空白 UI。命令可重复执行,已有项不会重复写入。
|
|
76
|
+
|
|
77
|
+
decisions.json 格式(Cell 用 manifest 中的稳定逻辑 ID,如 `row:base:4|name`):
|
|
78
|
+
|
|
79
|
+
```json
|
|
80
|
+
{
|
|
81
|
+
"files": {
|
|
82
|
+
"new_meta/Items.xlsx": {
|
|
83
|
+
"sheets": {
|
|
84
|
+
"Items": { "cells": { "row:base:4|name": "theirs" } }
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
#### Agent 调用规范
|
|
92
|
+
|
|
93
|
+
包根 `AGENTS.md` 是 AI Agent 调用规范正本,包含适用场景、快速流程、禁止事项与边界。首次通过 v-cli 调用前应运行 `v-cli agent docs xlmerge` 掌握该规范;直接安装时也可直接读取包内 `AGENTS.md`。
|
|
94
|
+
|
|
95
|
+
## 开发与验证
|
|
96
|
+
|
|
97
|
+
```sh
|
|
98
|
+
npm ci
|
|
99
|
+
npm test
|
|
100
|
+
npm run test:python
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
命令返回、结构校验、模拟测试与外部平台实际运行分别核验。发布版本和依赖以随包 `package.json` 为准。
|
|
104
|
+
|
|
105
|
+
## 文档
|
|
106
|
+
|
|
107
|
+
[Agent 调用规范](AGENTS.md) · [文档规范](docs/documentation.md)
|
|
108
|
+
|
|
109
|
+
## 许可与版权
|
|
110
|
+
|
|
111
|
+
本工具采用 [MIT 许可](LICENSE)。Copyright © 2026 Vant。Vant 为工具集品牌;Figma、Unity、Steam、微信及其组件归各自权利人所有,第三方组件适用各自许可。
|
package/bin/xlmerge.js
CHANGED
|
@@ -1,152 +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();
|
|
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();
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# Vant 文档规范
|
|
2
|
+
|
|
3
|
+
## 定位
|
|
4
|
+
|
|
5
|
+
所有包以简体中文为默认语言。包名、命令、参数、路径、协议、字段、错误码、第三方产品名与许可原文保留必要英文。品牌统一使用 Vant,版权统一为 Copyright © 2026 Vant;第三方归属声明保持准确。
|
|
6
|
+
|
|
7
|
+
## 结构
|
|
8
|
+
|
|
9
|
+
| 文档 | 一级内容顺序 |
|
|
10
|
+
| --- | --- |
|
|
11
|
+
| README | 功能、环境要求、安装、快速开始、使用说明、开发与验证、文档、许可与版权 |
|
|
12
|
+
| Agent 规范 | 定位、调用流程、调用规范、结果验证、参考资料、许可与版权 |
|
|
13
|
+
| 命令参考 | 定位、调用方式、参数与输出、执行边界、结果验证、参考资料 |
|
|
14
|
+
| 配置与协议 | 定位、前置条件、字段与示例、执行边界、结果验证、参考资料 |
|
|
15
|
+
| 操作指南 | 定位、前置条件、操作流程、结果验证、参考资料 |
|
|
16
|
+
| 故障诊断 | 定位、问题与处理、结果验证、参考资料 |
|
|
17
|
+
|
|
18
|
+
## 内容
|
|
19
|
+
|
|
20
|
+
只描述当前版本的功能、约束和可执行流程。正文不保存研发过程、历史兼容方案、失效版本表或未经验证的成功结论。版本历史集中在 CHANGELOG。已实现的数据转换命令按当前功能说明,不将历史方案混入常规操作。
|
|
21
|
+
|
|
22
|
+
## 维护
|
|
23
|
+
|
|
24
|
+
修改生成器、插件清单与源文档后重新生成随包文档。示例使用占位符,不包含账号、密钥或具体业务数据。命令、字段、链接和打包内容应通过检查;模拟验证不能替代真实平台结果。
|