@kevlns/xlmerge 2.0.2 → 2.0.4

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 CHANGED
@@ -1,4 +1,19 @@
1
- # xlmerge Agent 使用规范
1
+ # Vant 表格合并工具 Agent 规范
2
+
3
+ ## 定位
4
+
5
+ 在浏览器中审阅 Git 冲突工作簿的三方差异,校验后写回并提交合并结果。
6
+
7
+ ## 调用流程
8
+
9
+ ```sh
10
+ xlmerge --repo <仓库目录> detect
11
+ xlmerge --repo <仓库目录> launch
12
+ ```
13
+
14
+ 首次调用前读取本规范,使用命令帮助或插件清单核对参数和执行范围。
15
+
16
+ ## 调用规范
2
17
 
3
18
  > 三方工作簿会在结构对齐前分别计算并固化公式最终值;apply 对来源、快照和工作树做完整预检,并以可回滚批次执行写回(版本以 package.json / npm 包为准)。
4
19
 
@@ -14,11 +29,11 @@ xlmerge --repo <repo> launch
14
29
 
15
30
  `npx` 等价:`npx --package @kevlns/xlmerge@latest xlmerge --repo <repo> detect`。
16
31
 
17
- ## 何时使用
32
+ ### 何时使用
18
33
 
19
34
  用户要求处理策划表冲突、配置表冲突、xlsx/xlsm merge conflict 或多 Sheet 冲突,且 Git 仓库存在未合并的 `.xlsx`/`.xlsm` 时立即使用。这是一个**命令路由任务,不是表格分析任务**。
20
35
 
21
- ## 使用规范(Agent 必须遵守)
36
+ ### 使用规范(Agent 必须遵守)
22
37
 
23
38
  1. 用户确认要处理冲突后,**只做快速连贯的检测与启动**:`detect` → `count > 0` 时 `launch`。`reviewCount > 0` 时把返回的 `url` 告诉用户,然后停止分析,等待用户在页面完成选择;`reviewCount == 0` 时 `launch` 会直接采用过滤项的远端版本并提交,报告其 JSON 结果;`count == 0` 时报告没有未解决冲突并结束。
24
39
  2. **不额外审查冲突情况**:不检查工作簿 Cell、不自行做三方 diff、不总结冲突内容、不读取 base/ours/theirs;这些复杂度由工具内部流程处理。
@@ -27,7 +42,7 @@ xlmerge --repo <repo> launch
27
42
  5. `apply` 默认写回并 `git commit`;`--no-commit` 仅测试决策时使用;`--push` 仅用户明确要求推送时使用,正常流程不自动 push。
28
43
  6. 只处理单个文件时使用 `launch --path <仓库相对路径>`;多文件不按文件循环调用 `launch --path`,一次性同批次页面展示。
29
44
 
30
- ## 最高优先级快速流程
45
+ ### 最高优先级快速流程
31
46
 
32
47
  用户确认要处理冲突后,只做以下动作:
33
48
 
@@ -47,7 +62,7 @@ xlmerge --repo <repo> launch
47
62
 
48
63
  如果 `count` 为 `0`,报告没有未解决的 `.xlsx` / `.xlsm` 冲突并结束。
49
64
 
50
- ## 仓库过滤列表
65
+ ### 仓库过滤列表
51
66
 
52
67
  过滤列表默认为空,仅在用户明确要求某类生成表始终采用远端整表时添加:
53
68
 
@@ -59,7 +74,7 @@ xlmerge --repo <repo> filter add locale/Key.xlsx
59
74
 
60
75
  命中过滤项的冲突文件不进入结构化分析或 UI,而是逐字节写入 Git index stage 3(theirs)。若 stage 3 不存在则安全失败;混合批次会在用户确认人工冲突后,与 UI 处理结果一起写回并提交。
61
76
 
62
- ## 快速流程禁止事项
77
+ ### 快速流程禁止事项
63
78
 
64
79
  - 不调用通用 `xlsx` Skill、Excel API 或临时 Python 读取 base/ours/theirs。
65
80
  - 不运行 `prepare` 后读取 manifest,也不枚举或总结 Cell/Sheet 差异。
@@ -71,7 +86,7 @@ xlmerge --repo <repo> filter add locale/Key.xlsx
71
86
 
72
87
  只处理单个文件时,仍然直接使用 `launch --path <仓库相对路径>`。
73
88
 
74
- ## 程序负责的内部流程
89
+ ### 程序负责的内部流程
75
90
 
76
91
  以下内容由解析器自动完成,用于理解边界,不要由模型重复实现:
77
92
 
@@ -106,7 +121,7 @@ git -C <repo> log -1 --oneline
106
121
 
107
122
  第一条必须无输出;随后报告处理的文件、Sheet、人工选择数量和 commit 结果。
108
123
 
109
- ## 非交互入口
124
+ ### 非交互入口
110
125
 
111
126
  仅在自动化测试或用户已提供明确决策 JSON 时使用 prepare/apply;不要用于查看 diff。决策必须同时包含文件、Sheet 和 Cell(Cell 优先使用 manifest 的稳定逻辑 ID):
112
127
 
@@ -117,7 +132,7 @@ xlmerge --repo <repo> apply --manifest <manifest.json> --decisions <decisions.js
117
132
 
118
133
  测试决策但不 commit 时加 `--no-commit`;只有用户明确要求推送时加 `--push`。
119
134
 
120
- ## 边界与失败处理
135
+ ### 边界与失败处理
121
136
 
122
137
  - 只处理 Git 未合并状态中的 `.xlsx` / `.xlsm`;不处理普通修改。
123
138
  - 文件级 delete/modify 冲突缺少完整双方工作簿时,解析器停止并报告;不要猜测删除还是保留。
@@ -130,13 +145,27 @@ xlmerge --repo <repo> apply --manifest <manifest.json> --decisions <decisions.js
130
145
  - 不直接修改 XLSX 内部 XML,不使用未经本次完整计算验证的旧公式缓存冒充最终值。
131
146
  - 运行时提取文件和 manifest 默认放系统临时目录,不写入业务仓库。
132
147
 
133
- ## 环境
148
+ ### 环境
134
149
 
135
150
  npm 包通过 `bin/xlmerge.js` 启动:自动检测系统 Python(≥3.9,`XLMERGE_PYTHON` 可直接指定;否则按平台探测 `python3` / `python`,Windows 追加 `py -3`);若缺 `openpyxl` / `bottle` 依赖,则在 `~/.xlmerge/venv` 创建用户级 venv 并安装 `openpyxl==3.1.5`、`bottle==0.13.4`。不含公式的工作簿保持跨平台;含公式时必须在 Windows 上安装桌面版 Excel,解析器只让 Excel 打开隔离的临时副本,并拒绝外链、UDF/VBA、volatile、循环引用、动态数组等不可安全复现的公式语义。`XLMERGE_EXCEL_TIMEOUT_SECONDS` 可覆盖每个工作簿默认 120 秒的重算硬超时。正常流程不检查环境;仅入口明确报环境错误时诊断。
136
151
 
137
- ## 验证
152
+ ### 验证
138
153
 
139
154
  ```bash
140
155
  cd <npm 包目录>
141
156
  python -m unittest discover -s python/tests -v
142
157
  ```
158
+
159
+ 后台审阅用 `xlmerge launch`。`xlmerge status --manifest <file>` 查询原服务,`xlmerge cancel --manifest <file>` 请求停止并检查 stopConfirmed;身份不一致拒绝停止。通过 v-cli 结构化执行时,launch/resolve 返回 accepted 与 handle;status/cancel 使用原 handle,后台进程继续持有工程租约,停止前不重放启动。
160
+
161
+ ## 结果验证
162
+
163
+ 核对原始错误、任务身份、停止状态及实际产物。只报告已经完成的验证,模拟测试与真实执行分别说明。
164
+
165
+ ## 参考资料
166
+
167
+ [使用说明](README.md) · [文档规范](docs/documentation.md) · v-cli.plugin.json
168
+
169
+ ## 许可与版权
170
+
171
+ MIT。Copyright © 2026 Vant。
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 kevlns <936277610@qq.com>
3
+ Copyright © 2026 Vant
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,23 +1,31 @@
1
- <div align="center">
1
+ # Vant 表格合并工具
2
2
 
3
- <img src="https://raw.githubusercontent.com/kevlns/xlmerge/main/logo.png" alt="xlmerge logo" width="320" />
3
+ `@kevlns/xlmerge`
4
4
 
5
- # xlmerge
5
+ ## 功能
6
6
 
7
- **解决 Git 仓库中 `.xlsx` / `.xlsm` 策划配置表未合并冲突的可视化工具。**
7
+ 在浏览器中审阅 Git 冲突工作簿的三方差异,校验后写回并提交合并结果。
8
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)
9
+ ## 环境要求
13
10
 
14
- [Getting started](#getting-started) · [Usage](#usage) · [Development](#development) · [Package family](#package-family)
11
+ Node.js 16 及以上、Python 3.9 及以上;包含公式的工作簿需要 Windows 桌面版 Excel 生成可靠的计算快照。
15
12
 
16
- </div>
13
+ ## 安装
17
14
 
18
- ---
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
+ ## 使用说明
19
27
 
20
- ## Why xlmerge?
28
+ ### 功能说明
21
29
 
22
30
  Git 对二进制 `.xlsx`/`.xlsm` 只会整文件冲突,无法像文本一样逐行合并。xlmerge 用**公式最终值快照 + 三方结构化差异引擎 + 本地可视化 UI**把这件事变得可控:自动提取 Git index 的 base/ours/theirs 三方版本,按 Sheet、逻辑行、逻辑列、Cell 四级计算差异,浏览器中逐 Cell 选择本地/远端版本,最终原子写回工作簿并生成结构化 commit。
23
31
 
@@ -29,45 +37,7 @@ Git 对二进制 `.xlsx`/`.xlsm` 只会整文件冲突,无法像文本一样
29
37
  - **可配置整表过滤** - 仓库可把生成表加入过滤列表;命中时直接采用 Git stage 3 的远端原始文件
30
38
  - **默认不越权** - 服务只监听 `127.0.0.1`,不自动 push
31
39
 
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
- 支持 Excel 共享公式:先校验每个工作表内的共享组、主公式和引用范围,再展开各单元格的相对/绝对引用,执行公式安全检查并由 Excel 重算隔离副本。缺少或重复主公式、越界成员及不可安全展开的公式会明确失败;数组公式和数据表公式仍不支持。源工作簿保持不变,差异比较使用本次重算得到的最终值快照。
46
-
47
- 计算完成后直接校验 Excel 保存的公式缓存类型、错误和缺失结果,不再通过 COM 逐单元格遍历格式范围。三方版本的计算错误保留原公式、错误与位置,作为未知值进入界面;必须选择有效来源,错误涉及无法可靠确认的记录身份、表头或行列结构时需选择整个 Sheet。双方同一记录、同一字段都报错,且有一致的显式基础类型时,数值自动替换为 0、string 为 `""`、bool 为 false;ID、引用、约束字段、未知类型及重复 ID 不自动替换。替换只发生在审阅快照,原始表不变,界面与提交信息记录替代值。未处理错误不能写入结果。外链、宏/UDF、volatile、循环引用、缺失缓存等安全限制保持不变。
48
-
49
- ### Quick start
50
-
51
- ```bash
52
- # 检测未合并的 .xlsx/.xlsm(输出 JSON)
53
- xlmerge --repo <仓库路径> detect
54
-
55
- # 可选:把无需逐 Cell 审查的生成表加入仓库过滤列表
56
- xlmerge --repo <仓库路径> filter add locale/Key.xlsx
57
-
58
- # 提取三方版本并后台启动可视化解析器,返回 url(自动打开浏览器)
59
- xlmerge --repo <仓库路径> launch
60
- ```
61
-
62
- 环境变量:
63
-
64
- | 变量 | 作用 |
65
- |------|------|
66
- | `XLMERGE_PYTHON` | 指定解释器路径(如嵌入式 Python),跳过自动探测 |
67
- | `XLMERGE_VENV` | 覆盖默认 venv 目录 |
68
- | `XLMERGE_EXCEL_TIMEOUT_SECONDS` | 单个工作簿通过 Excel 隔离重算的硬超时,默认 120 秒 |
69
-
70
- ## Usage
40
+ ### 操作流程
71
41
 
72
42
  ```bash
73
43
  # 检测未合并的 .xlsx/.xlsm(输出 JSON)
@@ -118,80 +88,24 @@ decisions.json 格式(Cell 用 manifest 中的稳定逻辑 ID,如 `row:base:
118
88
  }
119
89
  ```
120
90
 
121
- ### Agent 调用规范
122
-
123
- 包根 `AGENTS.md` 是 AI Agent 调用规范正本,包含适用场景、快速流程、禁止事项与边界。首次通过 v-cli 调用前应运行 `v-cli agent docs xlmerge` 掌握该规范;独立安装时也可直接读取包内 `AGENTS.md`。
124
-
125
- ## Development
126
-
127
- ```bash
128
- # 单元测试(覆盖引擎、公式安全、原子写回、过滤配置与大请求体全流程)
129
- python -m unittest discover -s python/tests -v
130
-
131
- # 可选:调用本机 Excel 的真实公式重算回归(仅操作临时目录)
132
- $env:XLSX_EXCEL_E2E=1; python -m unittest discover -s python/tests -v
133
-
134
- # 校验 v-cli.plugin.json 与 CLI 解析器未漂移(命令/选项/副作用覆盖)
135
- npm run check:manifest
136
-
137
- # 端到端(构造真实冲突仓库 -> detect -> launch -> API 决策 -> 写回提交)
138
- python e2e_test.py bin/xlmerge.js node
139
-
140
- # 打包
141
- npm pack
142
- ```
143
-
144
- ### 包结构
145
-
146
- ```
147
- bin/xlmerge.js # Node 启动垫片:探测 Python、按需建 venv、透传参数
148
- AGENTS.md # AI Agent 调用规范正本(场景/规范/流程/边界)
149
- v-cli.plugin.json # Agent 插件清单(命令/选项/副作用),与 CLI 解析器做漂移校验
150
- python/
151
- ├── xlsx_merge_engine/ # 三方结构化差异引擎(可独立 CLI 调试)
152
- │ └── xlsx_git_merge_bridge.py
153
- ├── xlsx_resolver/ # 冲突解析器、公式值快照与 bottle UI
154
- └── tests/ # 引擎与解析器测试(不随 npm 包发布)
155
- ```
156
-
157
- > 注:为兼容嵌入式 Python 发行版(`._pth` 忽略 `PYTHONPATH`),模块内通过自举 `sys.path` 注入定位依赖,勿改为纯包导入。
91
+ #### Agent 调用规范
158
92
 
159
- ## Package family
93
+ 包根 `AGENTS.md` 是 AI Agent 调用规范正本,包含适用场景、快速流程、禁止事项与边界。首次通过 v-cli 调用前应运行 `v-cli agent docs xlmerge` 掌握该规范;直接安装时也可直接读取包内 `AGENTS.md`。
160
94
 
161
- kevlns 工具家族共享同一套发布约定(tag 驱动、CI 护栏、MIT)。
95
+ ## 开发与验证
162
96
 
163
- | Package | Purpose | Version |
164
- | --- | --- | --- |
165
- | [`v-cli`](https://github.com/kevlns/v-cli) | 个人工具箱 CLI | v0.2.14 |
166
- | [`xlmerge`](https://github.com/kevlns/xlmerge) | Git 中 .xlsx/.xlsm 冲突可视化解决工具(本仓库) | v2.0.0 |
167
- | [`u-cli-mod`](https://github.com/kevlns/u-cli-mod) | Unity 精确版本路由 + CLI + pipeline 包(Windows-first) | v0.2.3 |
168
- | [`figma-to-uprefab`](https://github.com/kevlns/figma-to-uprefab) | Figma 导出、契约校验与 Unity UGUI staging Prefab 构建 | v0.1.1 |
169
-
170
- ## Compatibility
171
-
172
- | Runtime | Supported versions |
173
- | --- | --- |
174
- | Node.js | `16` and later |
175
- | Python | `3.9` and later |
176
- | Excel formula calculation | Windows desktop Excel; formula-free workbooks remain cross-platform |
177
-
178
- ## Contributing
179
-
180
- ```bash
181
- git clone https://github.com/kevlns/xlmerge.git
182
- cd xlmerge
183
- python -m unittest discover -s python/tests -v
184
- npm run check:manifest
97
+ ```sh
98
+ npm ci
99
+ npm test
100
+ npm run test:python
185
101
  ```
186
102
 
187
- For bugs and feature requests, use [GitHub Issues](https://github.com/kevlns/xlmerge/issues).
188
-
189
- ## License
103
+ 命令返回、结构校验、模拟测试与外部平台实际运行分别核验。发布版本和依赖以随包 `package.json` 为准。
190
104
 
191
- Released under the [MIT License](./LICENSE).
105
+ ## 文档
192
106
 
193
- <div align="center">
107
+ [Agent 调用规范](AGENTS.md) · [文档规范](docs/documentation.md)
194
108
 
195
- Part of the **kevlns** tool family.
109
+ ## 许可与版权
196
110
 
197
- </div>
111
+ 本工具采用 [MIT 许可](LICENSE)。Copyright © 2026 Vant。Vant 为工具集品牌;Figma、Unity、Steam、微信及其组件归各自权利人所有,第三方组件适用各自许可。
@@ -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
+ 修改生成器、插件清单与源文档后重新生成随包文档。示例使用占位符,不包含账号、密钥或具体业务数据。命令、字段、链接和打包内容应通过检查;模拟验证不能替代真实平台结果。
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@kevlns/xlmerge",
3
- "version": "2.0.2",
4
- "description": "Formula-aware visual resolver for unresolved Git merge conflicts in .xlsx/.xlsm workbooks: three-way sheet/row/cell diff, local UI, atomic write-back and commit.",
3
+ "version": "2.0.4",
4
+ "description": "在浏览器中审阅 Git 冲突工作簿的三方差异,校验后写回并提交合并结果。",
5
5
  "bin": {
6
6
  "xlmerge": "bin/xlmerge.js"
7
7
  },
@@ -10,7 +10,8 @@
10
10
  "python/xlsx_merge_engine/",
11
11
  "python/xlsx_resolver/",
12
12
  "v-cli.plugin.json",
13
- "AGENTS.md"
13
+ "AGENTS.md",
14
+ "docs/"
14
15
  ],
15
16
  "vCli": {
16
17
  "manifest": "v-cli.plugin.json"
@@ -18,7 +19,8 @@
18
19
  "scripts": {
19
20
  "test": "node bin/xlmerge.js --selfcheck",
20
21
  "test:python": "python -m unittest discover -s python/tests -v",
21
- "check:manifest": "python -m unittest discover -s python/tests -p test_v_cli_plugin_manifest.py -v"
22
+ "check:manifest": "python -m unittest discover -s python/tests -p test_v_cli_plugin_manifest.py -v",
23
+ "docs:style": "node scripts/check-documentation.mjs"
22
24
  },
23
25
  "repository": {
24
26
  "type": "git",
@@ -28,7 +30,7 @@
28
30
  "bugs": {
29
31
  "url": "https://github.com/kevlns/xlmerge/issues"
30
32
  },
31
- "author": "kevlns <936277610@qq.com>",
33
+ "author": "Vant",
32
34
  "engines": {
33
35
  "node": ">=16"
34
36
  },
@@ -3,6 +3,8 @@
3
3
  from __future__ import annotations
4
4
 
5
5
  import json
6
+ import os
7
+ import uuid
6
8
  import sys
7
9
  import threading
8
10
  import webbrowser
@@ -16,6 +18,7 @@ if str(SCRIPT_DIR) not in sys.path:
16
18
  sys.path.insert(0, str(SCRIPT_DIR))
17
19
 
18
20
  from xlsx_conflict import ConflictError, _build_commit_message, apply_manifest, load_manifest
21
+ from session import save_session
19
22
  from prepare_progress import preparation_context, PreparationCancelled, checkpoint
20
23
 
21
24
 
@@ -73,6 +76,9 @@ def serve(manifest_path: Path | str, *, open_browser: bool = True, port: int = 0
73
76
  status = {'state': 'preparing' if prepare_repo else 'ready', 'phase': '开始解析',
74
77
  'file': '', 'fileDone': 0, 'fileTotal': 0, 'sheet': '', 'sheetDone': 0, 'sheetTotal': 0, 'side': ''}
75
78
 
79
+ receipt = {"sessionId": uuid.uuid4().hex, "pid": os.getpid(), "manifest": str(manifest_path), "state": "running"}
80
+ receipt_file = manifest_path.parent / "session.json"
81
+
76
82
  def report(progress):
77
83
  with lock:
78
84
  status.update(progress)
@@ -109,6 +115,11 @@ def serve(manifest_path: Path | str, *, open_browser: bool = True, port: int = 0
109
115
  with lock:
110
116
  return _json(dict(status))
111
117
 
118
+ @app.get("/api/session")
119
+ def session_status():
120
+ with lock:
121
+ return _json({**receipt, "progress": dict(status)})
122
+
112
123
  @app.get("/api/diff")
113
124
  def diff():
114
125
  if manifest is None:
@@ -141,6 +152,7 @@ def serve(manifest_path: Path | str, *, open_browser: bool = True, port: int = 0
141
152
  message=(payload.get("message") or "").strip() or None,
142
153
  )
143
154
  if result["success"]:
155
+ receipt.update(state="completed", result=result)
144
156
  state["resolved"] = True
145
157
  threading.Timer(2.0, state["server"].shutdown).start()
146
158
  return _json(result, 200 if result["success"] else 500)
@@ -153,6 +165,10 @@ def serve(manifest_path: Path | str, *, open_browser: bool = True, port: int = 0
153
165
 
154
166
  @app.post("/api/shutdown")
155
167
  def shutdown():
168
+ _payload()
169
+ identity = request.headers.get("X-Xlmerge-Session")
170
+ if identity is not None and identity != receipt["sessionId"]:
171
+ return _json({"success": False, "error": "审阅身份不一致"}, 409)
156
172
  with lock:
157
173
  if status['state'] == 'preparing':
158
174
  cancelled.set()
@@ -169,11 +185,19 @@ def serve(manifest_path: Path | str, *, open_browser: bool = True, port: int = 0
169
185
  if worker:
170
186
  worker.start()
171
187
  url = f"http://127.0.0.1:{server.server_port}"
188
+ receipt["url"] = url
189
+ save_session(receipt_file, receipt)
172
190
  print(f"MERGE_SERVER_URL={url}", flush=True)
173
191
  if open_browser:
174
192
  webbrowser.open(url)
175
193
  try:
176
194
  server.serve_forever()
177
195
  finally:
196
+ cancelled.set()
197
+ if worker:
198
+ worker.join()
178
199
  server.server_close()
200
+ if receipt["state"] != "completed":
201
+ receipt["state"] = "failed" if status["state"] == "failed" else "cancelled"
202
+ save_session(receipt_file, receipt)
179
203
  return bool(state["resolved"])
@@ -151,6 +151,10 @@ def build_parser() -> argparse.ArgumentParser:
151
151
  serve_parser.add_argument('--prepare', action='store_true', help=argparse.SUPPRESS)
152
152
  serve_parser.add_argument('--path', help=argparse.SUPPRESS)
153
153
 
154
+ for action in ("status", "cancel"):
155
+ control = subparsers.add_parser(action, help="查询或停止原审阅服务。")
156
+ control.add_argument("--manifest", required=True)
157
+
154
158
  apply_parser = subparsers.add_parser("apply", help="Apply a decisions JSON without launching the UI.")
155
159
  apply_parser.add_argument("--manifest", required=True)
156
160
  apply_parser.add_argument("--decisions", required=True)
@@ -164,6 +168,11 @@ def main(argv: list[str] | None = None) -> int:
164
168
  _configure_stdio()
165
169
  args = build_parser().parse_args(argv)
166
170
  try:
171
+ if args.command in ("status", "cancel"):
172
+ from session import inspect_session
173
+ result = inspect_session(args.manifest, cancel=args.command == "cancel")
174
+ _print(result)
175
+ return 0 if result["ok"] else 1
167
176
  # serve/apply 仅依赖 manifest(其 repoRoot 在 apply_manifest 内部解析),
168
177
  # 可在非 git 目录下运行;其余公开命令需要前置解析仓库。
169
178
  if args.command in ("detect", "filter", "prepare", "resolve", "launch"):
@@ -0,0 +1,49 @@
1
+ """审阅服务的持久化身份与完成回执。"""
2
+ import json
3
+ import os
4
+ import uuid
5
+ import time
6
+ from pathlib import Path
7
+ from urllib.request import Request, urlopen
8
+ from urllib.parse import urlparse
9
+
10
+
11
+ def save_session(file, data):
12
+ file = Path(file)
13
+ file.parent.mkdir(parents=True, exist_ok=True)
14
+ temp = file.with_name(file.name + '.' + uuid.uuid4().hex + '.tmp')
15
+ temp.write_text(json.dumps(data, ensure_ascii=False), encoding='utf-8')
16
+ os.replace(temp, file)
17
+
18
+
19
+ def inspect_session(manifest, cancel=False):
20
+ file = Path(manifest).resolve().parent / 'session.json'
21
+ original = json.loads(file.read_text(encoding='utf-8'))
22
+ if str(Path(original['manifest']).resolve()) != str(Path(manifest).resolve()):
23
+ raise ValueError('审阅身份与清单不一致')
24
+ if original['state'] in ('completed', 'cancelled', 'failed'):
25
+ return {**original, 'ok': True, 'stopConfirmed': True}
26
+ url = urlparse(original['url'])
27
+ if url.scheme != 'http' or url.hostname != '127.0.0.1' or not url.port or url.path:
28
+ raise ValueError('审阅服务地址无效')
29
+ try:
30
+ live = json.load(urlopen(original['url'] + '/api/session', timeout=3))
31
+ if live.get('sessionId') != original['sessionId'] or live.get('pid') != original['pid']:
32
+ raise ValueError('审阅服务身份变化,拒绝操作')
33
+ if not cancel:
34
+ return {**live, 'ok': True, 'stopConfirmed': False}
35
+ req = Request(original['url'] + '/api/shutdown', data=b'{}', headers={'X-Xlmerge-Session': original['sessionId']}, method='POST')
36
+ with urlopen(req, timeout=3):
37
+ pass
38
+ deadline = time.monotonic() + 5
39
+ while time.monotonic() < deadline:
40
+ settled = json.loads(file.read_text(encoding='utf-8'))
41
+ if settled['state'] in ('completed', 'cancelled', 'failed'):
42
+ return {**settled, 'ok': True, 'stopConfirmed': True}
43
+ time.sleep(.1)
44
+ return {**live, 'ok': True, 'state': 'cancelling', 'stopConfirmed': False}
45
+ except OSError as exc:
46
+ settled = json.loads(file.read_text(encoding='utf-8'))
47
+ if settled['state'] in ('completed', 'cancelled', 'failed'):
48
+ return {**settled, 'ok': True, 'stopConfirmed': True}
49
+ return {**original, 'ok': False, 'state': 'unknown', 'stopConfirmed': False, 'error': str(exc)}
package/v-cli.plugin.json CHANGED
@@ -3,25 +3,32 @@
3
3
  "package": "@kevlns/xlmerge",
4
4
  "command": "xlmerge",
5
5
  "bin": "xlmerge",
6
- "description": "Formula-aware visual resolver for Git merge conflicts in .xlsx/.xlsm planning tables: three-way sheet/row/cell diff, local UI, atomic write-back and commit.",
7
- "platforms": ["darwin", "linux", "win32"],
6
+ "description": "在浏览器中审阅 Git 冲突工作簿的三方差异,校验后写回并提交合并结果。",
7
+ "platforms": [
8
+ "darwin",
9
+ "linux",
10
+ "win32"
11
+ ],
8
12
  "runtime": {
9
13
  "node": ">=16",
10
14
  "python": ">=3.9",
11
- "pythonDependencies": ["openpyxl==3.1.5", "bottle==0.13.4"]
15
+ "pythonDependencies": [
16
+ "openpyxl==3.1.5",
17
+ "bottle==0.13.4"
18
+ ]
12
19
  },
13
20
  "environment": [
14
21
  {
15
22
  "name": "XLMERGE_PYTHON",
16
- "description": "Python interpreter path; highest precedence, bypasses automatic discovery."
23
+ "description": "Python 解释器路径,优先于自动查找。"
17
24
  },
18
25
  {
19
26
  "name": "XLMERGE_VENV",
20
- "description": "Directory for the on-demand user-level virtualenv (default: ~/.xlmerge/venv)."
27
+ "description": "按需创建的用户虚拟环境目录,默认 ~/.xlmerge/venv。"
21
28
  },
22
29
  {
23
30
  "name": "XLMERGE_EXCEL_TIMEOUT_SECONDS",
24
- "description": "Hard timeout for isolated Excel formula recalculation (default: 120 seconds per workbook)."
31
+ "description": "Excel 隔离重算单个工作簿的硬超时,默认 120 秒。"
25
32
  }
26
33
  ],
27
34
  "agent": {
@@ -29,165 +36,263 @@
29
36
  "globalOptions": [
30
37
  {
31
38
  "flags": "--repo <path>",
32
- "description": "Git repository (default: current directory; searches upward for the Git root)."
39
+ "description": "Git 仓库目录,默认当前目录并向上查找仓库根。"
33
40
  },
34
41
  {
35
42
  "flags": "--runtime-dir <dir>",
36
- "description": "Optional directory for extracted Git stage workbooks and manifest (default: system temp). Used by prepare, resolve and launch."
43
+ "description": "Git 三方工作簿与清单的暂存目录,默认系统临时目录,供 prepare、resolve、launch 使用。"
37
44
  }
38
45
  ],
39
46
  "commands": [
40
47
  {
41
- "path": ["detect"],
48
+ "path": [
49
+ "detect"
50
+ ],
42
51
  "usage": "xlmerge --repo <repo> detect",
43
- "description": "List unresolved .xlsx/.xlsm files in the repository.",
52
+ "description": "列出仓库中未解决的 .xlsx/.xlsm 冲突。",
44
53
  "arguments": [],
45
54
  "options": [],
46
55
  "output": {
47
56
  "format": "json",
48
- "description": "Object with ok, repo, count, reviewCount, autoTheirs and conflicts (array of {path, stages})."
57
+ "description": "返回 ok、repo、count、reviewCount、autoTheirs 和 conflicts(path、stages)。"
49
58
  },
50
59
  "exitCodes": {
51
- "0": "success",
52
- "1": "error (e.g. not a Git repository)",
53
- "2": "usage error"
60
+ "0": "成功。",
61
+ "1": "执行失败,例如目标不是 Git 仓库。",
62
+ "2": "用法错误。"
54
63
  },
55
- "safety": ["read-only", "no-worktree-modification"]
64
+ "safety": [
65
+ "read-only",
66
+ "no-worktree-modification"
67
+ ]
56
68
  },
57
69
  {
58
- "path": ["filter", "add"],
70
+ "path": [
71
+ "filter",
72
+ "add"
73
+ ],
59
74
  "usage": "xlmerge --repo <repo> filter add <path>",
60
- "description": "Add a repository-scoped case-insensitive workbook path-suffix filter whose conflicts are adopted byte-for-byte from Git stage 3.",
75
+ "description": "添加不区分大小写的工作簿路径后缀过滤项;匹配文件逐字节采用 Git stage 3。",
61
76
  "arguments": [
62
77
  {
63
78
  "name": "path",
64
79
  "required": true,
65
- "description": "Relative .xlsx/.xlsm path suffix to adopt from Git stage 3."
80
+ "description": "需采用 Git stage 3 的 .xlsx/.xlsm 相对路径后缀。"
66
81
  }
67
82
  ],
68
83
  "options": [],
69
84
  "output": {
70
85
  "format": "json",
71
- "description": "Object with ok, repo, config, filter, added and the complete filters list. Writes <repo>/.xlmerge.json."
86
+ "description": "返回 ok、repo、config、filter、added 和完整 filters,写入 <repo>/.xlmerge.json。"
72
87
  },
73
88
  "exitCodes": {
74
- "0": "success (including an already-present filter)",
75
- "1": "invalid repository, filter path or .xlmerge.json",
76
- "2": "usage error"
89
+ "0": "成功,包含过滤项已存在的情况。",
90
+ "1": "仓库、过滤路径或 .xlmerge.json 无效。",
91
+ "2": "用法错误。"
77
92
  },
78
- "safety": ["writes-worktree", "no-commit"]
93
+ "safety": [
94
+ "writes-worktree",
95
+ "no-commit"
96
+ ]
79
97
  },
80
98
  {
81
- "path": ["prepare"],
99
+ "path": [
100
+ "prepare"
101
+ ],
82
102
  "usage": "xlmerge --repo <repo> prepare [--path <file>]",
83
- "description": "Build a sheet-aware manifest; configured auto-theirs matches skip extraction and cell analysis.",
103
+ "description": "生成按工作表组织的清单;命中整表过滤的文件跳过单元格分析。",
84
104
  "arguments": [],
85
105
  "options": [
86
106
  {
87
107
  "flags": "--path <file>",
88
- "description": "Only prepare this repository-relative .xlsx/.xlsm path."
108
+ "description": "仅准备指定仓库相对路径的 .xlsx/.xlsm 文件。"
89
109
  }
90
110
  ],
91
111
  "output": {
92
112
  "format": "json",
93
- "description": "Object with ok and manifest (absolute path to the manifest JSON)."
113
+ "description": "返回 ok 和清单 JSON 的绝对路径 manifest。"
94
114
  },
95
115
  "exitCodes": {
96
- "0": "success",
97
- "1": "error (no conflicts found, not a Git repository, git failure)",
98
- "2": "usage error"
116
+ "0": "成功。",
117
+ "1": "无冲突、仓库无效或 Git 执行失败。",
118
+ "2": "用法错误。"
99
119
  },
100
- "safety": ["writes-runtime-dir", "no-worktree-modification", "no-commit"]
120
+ "safety": [
121
+ "writes-runtime-dir",
122
+ "no-worktree-modification",
123
+ "no-commit"
124
+ ]
101
125
  },
102
126
  {
103
- "path": ["resolve"],
127
+ "path": [
128
+ "resolve"
129
+ ],
104
130
  "usage": "xlmerge --repo <repo> resolve [--path <file>] [--no-browser]",
105
- "description": "Prepare conflicts and serve the local visual resolver in the foreground (blocking).",
131
+ "description": "准备冲突并以前台阻塞模式启动本地审阅界面。",
106
132
  "arguments": [],
107
133
  "options": [
108
134
  {
109
135
  "flags": "--path <file>",
110
- "description": "Only resolve this repository-relative .xlsx/.xlsm path."
136
+ "description": "仅处理指定仓库相对路径的 .xlsx/.xlsm 文件。"
111
137
  },
112
138
  {
113
139
  "flags": "--no-browser",
114
- "description": "Print the URL instead of opening a browser."
140
+ "description": "只输出地址,不打开浏览器。"
115
141
  }
116
142
  ],
117
143
  "output": {
118
144
  "format": "stdout",
119
- "description": "Prints MERGE_SERVER_URL=http://127.0.0.1:<port> for review conflicts; an all-filtered batch instead returns JSON after stage-3 write-back and commit."
145
+ "description": "审阅模式输出 MERGE_SERVER_URL=http://127.0.0.1:<port>;全量命中过滤时直接写回 stage 3 并提交,返回 JSON。"
120
146
  },
121
147
  "exitCodes": {
122
- "0": "success (resolution applied automatically or via UI; server shuts down after UI write-back)",
123
- "1": "error (prepare failure or server stopped before a resolution was applied)",
124
- "2": "usage error"
148
+ "0": "已应用解决结果:自动完成或通过界面写回,随后关闭服务。",
149
+ "1": "准备失败,或应用解决结果前服务已停止。",
150
+ "2": "用法错误。"
125
151
  },
126
- "safety": ["blocking", "binds-loopback", "opens-browser-by-default", "no-push", "writes-runtime-dir", "writes-worktree", "commits-by-default", "writes-worktree-via-ui", "commits-by-default-via-ui"]
152
+ "safety": [
153
+ "blocking",
154
+ "binds-loopback",
155
+ "opens-browser-by-default",
156
+ "no-push",
157
+ "writes-runtime-dir",
158
+ "writes-worktree",
159
+ "commits-by-default",
160
+ "writes-worktree-via-ui",
161
+ "commits-by-default-via-ui"
162
+ ]
127
163
  },
128
164
  {
129
- "path": ["launch"],
165
+ "path": [
166
+ "launch"
167
+ ],
130
168
  "usage": "xlmerge --repo <repo> launch [--path <file>] [--no-browser]",
131
- "description": "Prepare conflicts, start the visual resolver in the background and return its URL.",
169
+ "description": "准备冲突,在后台启动审阅界面并返回地址。",
132
170
  "arguments": [],
133
171
  "options": [
134
172
  {
135
173
  "flags": "--path <file>",
136
- "description": "Only resolve this repository-relative .xlsx/.xlsm path."
174
+ "description": "仅处理指定仓库相对路径的 .xlsx/.xlsm 文件。"
137
175
  },
138
176
  {
139
177
  "flags": "--no-browser",
140
- "description": "Start the server without opening a browser."
178
+ "description": "启动服务但不打开浏览器。"
141
179
  }
142
180
  ],
143
181
  "output": {
144
182
  "format": "json",
145
- "description": "For review conflicts: object with ok, pid, url, manifest and log paths. For an all-filtered batch: url is null and autoResolved/steps report automatic stage-3 write-back and commit."
183
+ "description": "审阅模式返回 ok、pid、url、manifest 和日志路径;全量过滤时 url 为 null,autoResolved 和 steps 记录写回与提交。"
146
184
  },
147
185
  "exitCodes": {
148
- "0": "success",
149
- "1": "error (prepare failure or server did not report a URL within 15 seconds)",
150
- "2": "usage error"
186
+ "0": "成功。",
187
+ "1": "准备失败,或服务未在 15 秒内报告地址。",
188
+ "2": "用法错误。"
151
189
  },
152
- "safety": ["starts-background-server", "binds-loopback", "opens-browser-by-default", "no-push", "writes-runtime-dir", "writes-worktree", "commits-by-default", "writes-worktree-via-ui", "commits-by-default-via-ui"]
190
+ "safety": [
191
+ "starts-background-server",
192
+ "binds-loopback",
193
+ "opens-browser-by-default",
194
+ "no-push",
195
+ "writes-runtime-dir",
196
+ "writes-worktree",
197
+ "commits-by-default",
198
+ "writes-worktree-via-ui",
199
+ "commits-by-default-via-ui"
200
+ ]
153
201
  },
154
202
  {
155
- "path": ["apply"],
203
+ "path": [
204
+ "apply"
205
+ ],
156
206
  "usage": "xlmerge --repo <repo> apply --manifest <manifest.json> --decisions <decisions.json> [--no-commit] [--push] [--message <text>]",
157
- "description": "Write back decisions from a decisions JSON without launching the UI.",
207
+ "description": "按决策 JSON 写回,不启动界面。",
158
208
  "arguments": [],
159
209
  "options": [
160
210
  {
161
211
  "flags": "--manifest <file>",
162
- "description": "Required. Manifest JSON produced by prepare."
212
+ "description": "prepare 生成的清单 JSON,必填。"
163
213
  },
164
214
  {
165
215
  "flags": "--decisions <file>",
166
- "description": "Required. Decisions JSON with per-file per-sheet cell, row, column, rename and macro choices keyed by logical IDs."
216
+ "description": "按逻辑 ID 指定文件、工作表、单元格、行列、重命名和宏选择的决策 JSON,必填。"
167
217
  },
168
218
  {
169
219
  "flags": "--no-commit",
170
- "description": "Skip git add/commit after writing merged workbooks."
220
+ "description": "写回后不执行 git add/commit。"
171
221
  },
172
222
  {
173
223
  "flags": "--push",
174
- "description": "Push after committing (off by default)."
224
+ "description": "提交后推送,默认关闭。"
175
225
  },
176
226
  {
177
227
  "flags": "--message <text>",
178
- "description": "Override the auto-generated structured commit message."
228
+ "description": "指定提交说明。"
229
+ }
230
+ ],
231
+ "output": {
232
+ "format": "json",
233
+ "description": "返回 success 与写回文件、提交摘要。"
234
+ },
235
+ "exitCodes": {
236
+ "0": "成功,包含指定 --no-commit 的情况。",
237
+ "1": "决策无效、不完整或 Git/系统操作失败。",
238
+ "2": "用法错误。"
239
+ },
240
+ "safety": [
241
+ "writes-worktree",
242
+ "commits-by-default",
243
+ "pushes-only-with-flag"
244
+ ]
245
+ },
246
+ {
247
+ "path": [
248
+ "status"
249
+ ],
250
+ "usage": "xlmerge status --manifest <file>",
251
+ "description": "查询原审阅服务。",
252
+ "arguments": [],
253
+ "options": [
254
+ {
255
+ "flags": "--manifest <file>",
256
+ "description": "原审阅清单路径,必须与 session.json 身份一致。"
257
+ }
258
+ ],
259
+ "output": {
260
+ "format": "json",
261
+ "description": "返回审阅身份、状态、完成回执及 stopConfirmed;unknown 不代表已停止。"
262
+ },
263
+ "exitCodes": {
264
+ "0": "查询或停止请求完成。",
265
+ "1": "身份、连接或状态不可确认。"
266
+ },
267
+ "safety": [
268
+ "read-only"
269
+ ]
270
+ },
271
+ {
272
+ "path": [
273
+ "cancel"
274
+ ],
275
+ "usage": "xlmerge cancel --manifest <file>",
276
+ "description": "请求停止原审阅服务并等待回执。",
277
+ "arguments": [],
278
+ "options": [
279
+ {
280
+ "flags": "--manifest <file>",
281
+ "description": "原审阅清单路径,必须与 session.json 身份一致。"
179
282
  }
180
283
  ],
181
284
  "output": {
182
285
  "format": "json",
183
- "description": "Result object with success and summary of written files and commit."
286
+ "description": "返回审阅身份、状态、完成回执及 stopConfirmed;unknown 不代表已停止。"
184
287
  },
185
288
  "exitCodes": {
186
- "0": "success (including with --no-commit)",
187
- "1": "error (invalid or incomplete decisions, git/OS failure)",
188
- "2": "usage error"
289
+ "0": "查询或停止请求完成。",
290
+ "1": "身份、连接或状态不可确认。"
189
291
  },
190
- "safety": ["writes-worktree", "commits-by-default", "pushes-only-with-flag"]
292
+ "safety": [
293
+ "binds-loopback",
294
+ "no-commit"
295
+ ]
191
296
  }
192
297
  ]
193
298
  }