@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/skill/SKILL.md ADDED
@@ -0,0 +1,114 @@
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
+ ---
5
+
6
+ # XLSX/XLSM Conflict Resolver(npm 通用版)
7
+
8
+ > 处理任意 Git 仓库中未合并的 `.xlsx` / `.xlsm` 二进制冲突。
9
+
10
+ 命令入口(npm 安装后全局可用,`<repo>` 为配置表 Git 仓库路径):
11
+
12
+ ```bash
13
+ xlmerge --repo <repo> detect
14
+ xlmerge --repo <repo> launch
15
+ ```
16
+
17
+ `npx` 方式等价:`npx --package @kevlns/xlmerge@beta xlmerge --repo <repo> detect`。
18
+
19
+ ## 最高优先级快速流程
20
+
21
+ 这是一个命令路由 Skill,不是表格分析任务。用户确认要处理冲突后,只做以下动作:
22
+
23
+ 1. 执行检测:
24
+
25
+ ```bash
26
+ xlmerge --repo <repo> detect
27
+ ```
28
+
29
+ 2. `count > 0` 时立即启动解析器;不传 `--path`,一次性把所有冲突工作簿放进同一页面:
30
+
31
+ ```bash
32
+ xlmerge --repo <repo> launch
33
+ ```
34
+
35
+ 3. 把 `launch` 返回的 `url` 告诉用户,然后停止分析,等待用户在页面完成选择。`launch` 已经负责提取全部 Git 三方版本、计算多文件多 Sheet diff、后台启动服务并打开浏览器。
36
+
37
+ 如果 `count` 为 `0`,报告没有未解决的 `.xlsx` / `.xlsm` 冲突并结束。
38
+
39
+ ### 快速流程禁止事项
40
+
41
+ - 不调用通用 `xlsx` Skill、Excel API 或临时 Python 读取 base/ours/theirs。
42
+ - 不运行 `prepare` 后读取 manifest,也不枚举或总结 Cell/Sheet 差异。
43
+ - 不先搜索配置表结构、Luban schema、策划字段含义或项目代码。
44
+ - 不替用户判断某个 Cell 应选 ours 还是 theirs。
45
+ - 不因为冲突文件多、Sheet 多而进入计划模式;这些复杂度由固化程序处理。
46
+ - 不使用阻塞式 `resolve` 作为正常入口;正常调用始终使用会快速返回 URL 的 `launch`。
47
+ - 默认流程禁止按文件循环调用 `launch --path`;单个文件异常也必须由同一批次页面展示或明确报错。
48
+
49
+ 只处理单个文件时,仍然直接使用 `launch --path <仓库相对路径>`。
50
+
51
+ ## 程序负责的内部流程
52
+
53
+ 以下内容由解析器自动完成,用于理解边界,不要由模型重复实现:
54
+
55
+ 1. 从 Git index 提取 base/ours/theirs(stage 1/2/3),经内容锚点引擎生成 Sheet、行、列和 Cell 四级三方差异。冲突身份是 `仓库相对路径 + 逻辑 Sheet + 逻辑行 ID + 逻辑列 ID`,物理坐标只用于展示;新增/删除行列后选择不会漂移。Luban 风格表头(`##var` / `##type` / `##group` / `##`)会被自动识别并保留,`##var` 为空的注释列、占位列同样参与对齐与写回。
56
+
57
+ 2. 本地服务只监听 `127.0.0.1`,浏览器负责用户交互:
58
+
59
+ - 顶部第一层标签切换冲突文件,第二层 `SHEET` 标签切换工作表;选择状态按文件和 Sheet 隔离。
60
+ - 两侧修改同一 Cell 且结果不同:默认显示 `theirs`,单击可在 `ours` / `theirs` 间切换;只有一侧修改时默认采用修改侧,仍可单击覆盖。
61
+ - 一侧删除 Sheet、另一侧修改:按整个 Sheet 选择保留 `ours` 或 `theirs`;只在一侧新增的 Sheet 自动保留。
62
+ - `.xlsm` 的 VBA/ActiveX 单边变化自动采用变化侧;双边变化时在文件级选择本地宏/远端宏(默认本地)。
63
+ - 相对本地可自动合入的远端新增行/列用浅绿色整行/列展示并锁定;已确定删除的行/列用灰色墓碑展示并锁定。
64
+ - 单击行号/列头批量切换;“全部本地/全部远端”作用于当前 Sheet;“撤销”回退最近一次选择,“重置”恢复默认三方选择。
65
+ - 悬停 Cell 时展示 base、双方值、双方文件作者和当前选择。
66
+
67
+ 3. 用户点击“写回并提交”后:
68
+
69
+ - 先请求只读 `/api/commit-preview` 生成 commit 信息,弹出居中的二次确认窗口;确认后才执行写回与 `git add` / `git commit`。
70
+ - 以 `ours` 工作簿为基底重建受影响 Sheet;保留所选来源的值、公式、样式、批注、超链接、数字格式、行高列宽、冻结拆分等视图状态;公式保留并从源文件注入缓存值。
71
+ - 保存到仓库原路径并重新打开验证可读;`.xlsm` 全程 `keep_vba` 模式,保存后逐字节校验 VBA 负载。
72
+ - 存在冲突 Cell 选择时自动生成结构化提交信息(每个冲突 Cell 一行,含表、Sheet、单元格、选择、双方值),`--message` 可覆盖。
73
+ - 可视化入口不自动 push。
74
+
75
+ 4. 用户完成页面操作并返回后复核:
76
+
77
+ ```bash
78
+ git -C <repo> diff --name-only --diff-filter=U
79
+ git -C <repo> status --short --branch
80
+ git -C <repo> log -1 --oneline
81
+ ```
82
+
83
+ 第一条必须无输出;随后报告处理的文件、Sheet、人工选择数量和 commit 结果。
84
+
85
+ ## 非交互入口
86
+
87
+ 仅在自动化测试或用户已提供明确决策 JSON 时使用 prepare/apply;不要为了让模型查看 diff 而使用。决策必须同时包含文件、Sheet 和 Cell(Cell 优先使用 manifest 的稳定逻辑 ID):
88
+
89
+ ```bash
90
+ xlmerge --repo <repo> prepare
91
+ xlmerge --repo <repo> apply --manifest <manifest.json> --decisions <decisions.json>
92
+ ```
93
+
94
+ 测试决策但不 commit 时加 `--no-commit`;只有用户明确要求推送时加 `--push`。
95
+
96
+ ## 边界与失败处理
97
+
98
+ - 只处理 Git 未合并状态中的 `.xlsx` / `.xlsm`;不处理普通修改。
99
+ - 文件级 delete/modify 冲突缺少完整双方工作簿时,解析器停止并报告;不要猜测删除还是保留。
100
+ - 写回前必须收齐所有人工选择;缺少任何选择时不改工作树。
101
+ - Excel 正在占用目标文件导致替换失败时,要求用户关闭该工作簿后重试。
102
+ - 不直接修改 XLSX 内部 XML,不把公式替换为缓存值。
103
+ - 运行时提取文件和 manifest 默认放系统临时目录,不写入业务仓库。
104
+
105
+ ## 环境
106
+
107
+ 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
+
109
+ ## 验证 Skill 本身
110
+
111
+ ```bash
112
+ cd <npm 包目录>
113
+ python -m unittest discover -s python/tests -v
114
+ ```