@kevlns/xlmerge 1.2.1-beta.3 → 1.2.1-beta.5

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.
@@ -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
- # XLSX/XLSM Conflict Resolver(npm 通用版)
3
+ > 本文件是 AI Agent 调用 xlmerge 的规范正本。完整参数以 `xlmerge --help` / 子命令 `--help` 与 `v-cli.plugin.json`(经 v-cli 路由时用 `v-cli agent describe xlmerge`)为准;本文件锁定使用场景、调用规范、快速流程与边界。
7
4
 
8
- > 处理任意 Git 仓库中未合并的 `.xlsx` / `.xlsm` 二进制冲突。
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` 方式等价:`npx --package @kevlns/xlmerge@beta xlmerge --repo <repo> detect`。
12
+ `npx` 等价:`npx --package @kevlns/xlmerge@beta 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
- ## 验证 Skill 本身
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
@@ -63,9 +63,9 @@ decisions.json 格式(Cell 用 manifest 中的稳定逻辑 ID,如 `row:base:
63
63
  }
64
64
  ```
65
65
 
66
- ### 作为 Agent Skill 使用
66
+ ### Agent 调用规范
67
67
 
68
- `skill/SKILL.md` 为技能文档,可复制(或软链)到目标 Agent 的 skills 目录(如 `.claude/skills/xlmerge/`、`~/.pi/agent/skills/`)。Skill 要求模型只做命令路由:`detect` -> `launch` -> 等待用户在 UI 完成 Cell 选择,禁止模型自行读取或总结 diff。
68
+ 包根 `AGENTS.md` 是 AI Agent 调用规范正本,包含适用场景、快速流程、禁止事项与边界。首次通过 v-cli 调用前应运行 `v-cli agent docs xlmerge` 掌握该规范;独立安装时也可直接读取包内 `AGENTS.md`。
69
69
 
70
70
  ## 开发与测试
71
71
 
@@ -87,7 +87,7 @@ npm pack
87
87
 
88
88
  ```
89
89
  bin/xlmerge.js # Node 启动垫片:探测 Python、按需建 venv、透传参数
90
- skill/SKILL.md # Agent Skill 文档
90
+ AGENTS.md # AI Agent 调用规范正本(场景/规范/流程/边界)
91
91
  v-cli.plugin.json # Agent 插件清单(命令/选项/副作用),与 CLI 解析器做漂移校验
92
92
  python/
93
93
  ├── xlsx_merge_engine/ # 三方结构化差异引擎(可独立 CLI 调试)
package/package.json CHANGED
@@ -1,16 +1,16 @@
1
1
  {
2
2
  "name": "@kevlns/xlmerge",
3
- "version": "1.2.1-beta.3",
3
+ "version": "1.2.1-beta.5",
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
  }
@@ -887,11 +887,17 @@ def _annotate_column_conflicts(
887
887
  return conflict_count
888
888
 
889
889
 
890
+ def _write_text_lf(path: Path, content: str) -> None:
891
+ """3.9-compatible LF write (Path.write_text gained `newline` only in 3.10)."""
892
+ with path.open("w", encoding="utf-8", newline="\n") as handle:
893
+ handle.write(content)
894
+
895
+
890
896
  def _write_projection(path: Path, rows: list[RowProjection]) -> None:
891
897
  content = "\n".join(row.text for row in rows)
892
898
  if content:
893
899
  content += "\n"
894
- path.write_text(content, encoding="utf-8", newline="\n")
900
+ _write_text_lf(path, content)
895
901
 
896
902
 
897
903
  def _write_sidecar(path: Path, layout: SheetLayout, rows: list[RowProjection]) -> None:
@@ -1474,7 +1480,7 @@ def analyze_workbooks(
1474
1480
  paths["ours"], paths["base"], paths["theirs"]
1475
1481
  )
1476
1482
  merge_output_path = sheet_dir / "git-merge-output.txt"
1477
- merge_output_path.write_text(merged_text, encoding="utf-8", newline="\n")
1483
+ _write_text_lf(merge_output_path, merged_text)
1478
1484
  segments = _parse_merge(merged_text, projection_fields)
1479
1485
  conflict_count = sum(segment["type"] == "conflict" for segment in segments)
1480
1486
  total_conflicts += conflict_count