@kevlns/xlmerge 1.2.1-beta.4 → 1.2.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/{skill/SKILL.md → AGENTS.md} +19 -11
- package/README.md +5 -7
- package/package.json +4 -5
|
@@ -1,20 +1,28 @@
|
|
|
1
|
-
|
|
2
|
-
name: xlmerge
|
|
3
|
-
description: "Deterministic launcher for unresolved Git merge conflicts in planning-table .xlsx and .xlsm files. Use immediately whenever a user asks to handle 策划表冲突、配置表冲突、xlsx/xlsm merge conflict or multi-Sheet conflict: run the bundled detect command, then launch the bundled UI when conflicts exist. Do not inspect workbook cells, use a generic xlsx analysis flow, summarize the diff, or choose ours/theirs in the model; the resolver UI owns diff, user decisions, write-back and commit."
|
|
4
|
-
---
|
|
1
|
+
# xlmerge Agent 使用规范
|
|
5
2
|
|
|
6
|
-
|
|
3
|
+
> 本文件是 AI Agent 调用 xlmerge 的规范正本。完整参数以 `xlmerge --help` / 子命令 `--help` 与 `v-cli.plugin.json`(经 v-cli 路由时用 `v-cli agent describe xlmerge`)为准;本文件锁定使用场景、调用规范、快速流程与边界。
|
|
7
4
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
命令入口(npm 安装后全局可用,`<repo>` 为配置表 Git 仓库路径):
|
|
5
|
+
处理任意 Git 仓库中未合并的 `.xlsx` / `.xlsm` 二进制冲突。命令入口(npm 安装后全局可用,`<repo>` 为配置表 Git 仓库路径;经 v-cli 路由为 `v-cli xlmerge …`):
|
|
11
6
|
|
|
12
7
|
```bash
|
|
13
8
|
xlmerge --repo <repo> detect
|
|
14
9
|
xlmerge --repo <repo> launch
|
|
15
10
|
```
|
|
16
11
|
|
|
17
|
-
`npx`
|
|
12
|
+
`npx` 等价:`npx --package @kevlns/xlmerge@latest xlmerge --repo <repo> detect`。
|
|
13
|
+
|
|
14
|
+
## 何时使用
|
|
15
|
+
|
|
16
|
+
用户要求处理策划表冲突、配置表冲突、xlsx/xlsm merge conflict 或多 Sheet 冲突,且 Git 仓库存在未合并的 `.xlsx`/`.xlsm` 时立即使用。这是一个**命令路由任务,不是表格分析任务**。
|
|
17
|
+
|
|
18
|
+
## 使用规范(Agent 必须遵守)
|
|
19
|
+
|
|
20
|
+
1. 用户确认要处理冲突后,**只做快速连贯的检测与启动**:`detect` → `count > 0` 时 `launch` → 把返回的 `url` 告诉用户,然后停止分析,等待用户在页面完成选择;`count == 0` 时报告没有未解决冲突并结束。
|
|
21
|
+
2. **不额外审查冲突情况**:不检查工作簿 Cell、不自行做三方 diff、不总结冲突内容、不读取 base/ours/theirs;这些复杂度由固化程序处理。
|
|
22
|
+
3. **不默认走无头自动合并**:`launch --no-browser` + 程序化 decisions/apply 的无头链路仅限自动化测试或用户明确提供决策 JSON / 明确要求自动化的场景;默认流程必须走 UI `launch`,决策权始终在用户。
|
|
23
|
+
4. **不替用户选择 ours/theirs**;不因为冲突文件多、Sheet 多而进入计划模式。
|
|
24
|
+
5. `apply` 默认写回并 `git commit`;`--no-commit` 仅测试决策时使用;`--push` 仅用户明确要求推送时使用,正常流程不自动 push。
|
|
25
|
+
6. 只处理单个文件时使用 `launch --path <仓库相对路径>`;多文件不按文件循环调用 `launch --path`,一次性同批次页面展示。
|
|
18
26
|
|
|
19
27
|
## 最高优先级快速流程
|
|
20
28
|
|
|
@@ -106,9 +114,9 @@ xlmerge --repo <repo> apply --manifest <manifest.json> --decisions <decisions.js
|
|
|
106
114
|
|
|
107
115
|
npm 包通过 `bin/xlmerge.js` 启动:自动检测系统 Python(≥3.9,顺序为 `XLMERGE_PYTHON` 环境变量 > `python3` > `python` > `py -3`);若缺 `openpyxl` / `bottle` 依赖,则在 `~/.xlmerge/venv` 创建用户级 venv 并安装 `openpyxl==3.1.5`、`bottle==0.13.4`。正常流程不检查环境;仅入口明确报环境错误时诊断。
|
|
108
116
|
|
|
109
|
-
## 验证
|
|
117
|
+
## 验证
|
|
110
118
|
|
|
111
119
|
```bash
|
|
112
120
|
cd <npm 包目录>
|
|
113
121
|
python -m unittest discover -s python/tests -v
|
|
114
|
-
```
|
|
122
|
+
```
|
package/README.md
CHANGED
|
@@ -12,15 +12,13 @@
|
|
|
12
12
|
## 安装
|
|
13
13
|
|
|
14
14
|
```bash
|
|
15
|
-
#
|
|
16
|
-
npm install -g @kevlns/xlmerge
|
|
15
|
+
# 正式版直接安装
|
|
16
|
+
npm install -g @kevlns/xlmerge
|
|
17
17
|
|
|
18
18
|
# 或直接从 GitHub 仓库安装开发版本
|
|
19
19
|
npm install -g git+https://github.com/kevlns/xlmerge.git
|
|
20
20
|
```
|
|
21
21
|
|
|
22
|
-
发布稳定版并设置 `latest` 标签后,可直接使用 `npm install -g @kevlns/xlmerge`。
|
|
23
|
-
|
|
24
22
|
要求:Node.js >= 16,系统 Python >= 3.9。首次运行若缺少依赖,会在 `~/.xlmerge/venv` 自动创建用户级 venv 并安装 `openpyxl==3.1.5`、`bottle==0.13.4`。
|
|
25
23
|
|
|
26
24
|
环境变量:
|
|
@@ -63,9 +61,9 @@ decisions.json 格式(Cell 用 manifest 中的稳定逻辑 ID,如 `row:base:
|
|
|
63
61
|
}
|
|
64
62
|
```
|
|
65
63
|
|
|
66
|
-
###
|
|
64
|
+
### Agent 调用规范
|
|
67
65
|
|
|
68
|
-
`
|
|
66
|
+
包根 `AGENTS.md` 是 AI Agent 调用规范正本,包含适用场景、快速流程、禁止事项与边界。首次通过 v-cli 调用前应运行 `v-cli agent docs xlmerge` 掌握该规范;独立安装时也可直接读取包内 `AGENTS.md`。
|
|
69
67
|
|
|
70
68
|
## 开发与测试
|
|
71
69
|
|
|
@@ -87,7 +85,7 @@ npm pack
|
|
|
87
85
|
|
|
88
86
|
```
|
|
89
87
|
bin/xlmerge.js # Node 启动垫片:探测 Python、按需建 venv、透传参数
|
|
90
|
-
|
|
88
|
+
AGENTS.md # AI Agent 调用规范正本(场景/规范/流程/边界)
|
|
91
89
|
v-cli.plugin.json # Agent 插件清单(命令/选项/副作用),与 CLI 解析器做漂移校验
|
|
92
90
|
python/
|
|
93
91
|
├── xlsx_merge_engine/ # 三方结构化差异引擎(可独立 CLI 调试)
|
package/package.json
CHANGED
|
@@ -1,16 +1,16 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kevlns/xlmerge",
|
|
3
|
-
"version": "1.2.1
|
|
3
|
+
"version": "1.2.1",
|
|
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"
|
|
7
7
|
},
|
|
8
8
|
"files": [
|
|
9
9
|
"bin/",
|
|
10
|
-
"skill/",
|
|
11
10
|
"python/xlsx_merge_engine/",
|
|
12
11
|
"python/xlsx_resolver/",
|
|
13
|
-
"v-cli.plugin.json"
|
|
12
|
+
"v-cli.plugin.json",
|
|
13
|
+
"AGENTS.md"
|
|
14
14
|
],
|
|
15
15
|
"vCli": {
|
|
16
16
|
"manifest": "v-cli.plugin.json"
|
|
@@ -42,7 +42,6 @@
|
|
|
42
42
|
"xlsm",
|
|
43
43
|
"git",
|
|
44
44
|
"merge-conflict",
|
|
45
|
-
"excel"
|
|
46
|
-
"agent-skill"
|
|
45
|
+
"excel"
|
|
47
46
|
]
|
|
48
47
|
}
|