@kevlns/xlmerge 2.0.6 → 2.0.8

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/README.md CHANGED
@@ -4,7 +4,7 @@
4
4
 
5
5
  ## 功能
6
6
 
7
- 在浏览器中审阅 Git 冲突工作簿的三方差异,校验后写回并提交合并结果。
7
+ 处理 Git 中的 Excel 三方冲突,支持 Agent 根据项目规则裁决并写回,也支持浏览器逐项审阅。
8
8
 
9
9
  ## 环境要求
10
10
 
@@ -20,7 +20,9 @@ npm install -g @kevlns/xlmerge
20
20
 
21
21
  ```sh
22
22
  xlmerge --repo <仓库目录> detect
23
- xlmerge --repo <仓库目录> launch
23
+ xlmerge --repo <仓库目录> prepare
24
+ # 根据清单生成 decisions.json 后写回并暂存
25
+ xlmerge --repo <仓库目录> apply --manifest <manifest.json> --decisions <decisions.json> --no-commit
24
26
  ```
25
27
 
26
28
  ## 使用说明
@@ -55,7 +57,7 @@ xlmerge --repo <仓库路径> launch --path new_meta/Items.xlsx
55
57
  # 前台阻塞式运行(与 launch 等价,进程前台等待完成)
56
58
  xlmerge --repo <仓库路径> resolve
57
59
 
58
- # 非交互(自动化/CI):先 prepare 再 apply
60
+ # Agent 自主裁决或自动化处理:先 prepare 再 apply
59
61
  xlmerge --repo <仓库路径> prepare
60
62
  xlmerge --repo <仓库路径> apply --manifest <manifest.json> --decisions <decisions.json> [--no-commit] [--message <text>] [--push]
61
63
  ```
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@kevlns/xlmerge",
3
- "version": "2.0.6",
4
- "description": "在浏览器中审阅 Git 冲突工作簿的三方差异,校验后写回并提交合并结果。",
3
+ "version": "2.0.8",
4
+ "description": "处理 Git 中的 Excel 三方冲突,支持 Agent 根据项目规则裁决并写回,也支持浏览器逐项审阅。",
5
5
  "bin": {
6
6
  "xlmerge": "bin/xlmerge.js"
7
7
  },
@@ -1,8 +1,10 @@
1
1
  ---
2
2
  name: xlmerge
3
- description: "在浏览器中审阅 Git 冲突工作簿的三方差异,校验后写回并提交合并结果。"
3
+ description: "处理 Git 中的 Excel 三方冲突,支持 Agent 根据项目规则裁决并写回,也支持浏览器逐项审阅。"
4
4
  ---
5
5
 
6
- # 表格合并
6
+ # 配表冲突
7
7
 
8
- 按用户目标调用工具,执行前读取 [操作与边界](references/project.md),以实时 describe 返回的参数契约为准。失败时报告实际状态,不通过重复提交或修改身份掩盖未知结果。
8
+ 在冲突仓库用 `detect` 定位工作簿,`prepare` 生成三方差异。根据稳定 ID 和业务规则裁决歧义,通过 `resolve` 提交裁决、`apply --no-commit` 写回,检查 `status` 与项目验证结果后继续原合并。需要人工可视化审阅时使用 `launch`。
9
+
10
+ 在 Vant 会话的 shell 中,示例里的 `v-cli` 代表插件入口:PowerShell 写作 `node "$env:DSH_VANT_CLI"`,sh 写作 `node "$DSH_VANT_CLI"`。 后接 `xlmerge` 和对应参数。完整参数与交付条件见[操作与边界](references/project.md)。
@@ -1,145 +1,33 @@
1
- # Vant 表格合并工具 Agent 规范
1
+ # 配表冲突处理
2
2
 
3
3
  ## 定位
4
4
 
5
- 在浏览器中审阅 Git 冲突工作簿的三方差异,校验后写回并提交合并结果。
5
+ 在工单或会话绑定的 Git 工区运行。原始三方、工作表、逻辑行列、公式计算值和稳定 ID 均由 xlmerge 生成。
6
6
 
7
7
  ## 调用流程
8
8
 
9
- ```sh
10
- xlmerge --repo <仓库目录> detect
11
- xlmerge --repo <仓库目录> launch
12
- ```
13
-
14
- 首次调用前读取本规范,使用命令帮助或插件清单核对参数和执行范围。
15
-
16
- ## 调用规范
17
-
18
- > 三方工作簿会在结构对齐前分别计算并固化公式最终值;apply 对来源、快照和工作树做完整预检,并以可回滚批次执行写回(版本以 package.json / npm 包为准)。
19
-
20
- > 本文件是 AI Agent 调用 xlmerge 的规范正本。完整参数以 `xlmerge --help` / 子命令 `--help` 与 `v-cli.plugin.json`(经 v-cli 路由时用 `v-cli agent describe xlmerge`)为准;本文件锁定使用场景、调用规范、快速流程与边界。
21
-
22
- 处理任意 Git 仓库中未合并的 `.xlsx` / `.xlsm` 二进制冲突。命令入口(npm 安装后全局可用,`<repo>` 为配置表 Git 仓库路径;经 v-cli 路由为 `v-cli xlmerge …`):
23
-
24
- ```bash
25
- xlmerge --repo <repo> detect
26
- xlmerge --repo <repo> filter add <path.xlsx>
27
- xlmerge --repo <repo> launch
28
- ```
29
-
30
- `npx` 等价:`npx --package @kevlns/xlmerge@latest xlmerge --repo <repo> detect`。
31
-
32
- ### 何时使用
33
-
34
- 用户要求处理策划表冲突、配置表冲突、xlsx/xlsm merge conflict 或多 Sheet 冲突,且 Git 仓库存在未合并的 `.xlsx`/`.xlsm` 时立即使用。这是一个**命令路由任务,不是表格分析任务**。
35
-
36
- ### 使用规范(Agent 必须遵守)
37
-
38
- 1. 用户确认要处理冲突后,**只做快速连贯的检测与启动**:`detect` → `count > 0` 时 `launch`。`reviewCount > 0` 时把返回的 `url` 告诉用户,然后停止分析,等待用户在页面完成选择;`reviewCount == 0` 时 `launch` 会直接采用过滤项的远端版本并提交,报告其 JSON 结果;`count == 0` 时报告没有未解决冲突并结束。
39
- 2. **不额外审查冲突情况**:不检查工作簿 Cell、不自行做三方 diff、不总结冲突内容、不读取 base/ours/theirs;这些复杂度由工具内部流程处理。
40
- 3. **不默认走无头自动合并**:`launch --no-browser` + 程序化 decisions/apply 的无头链路仅限自动化测试或用户明确提供决策 JSON / 明确要求自动化的场景;默认流程必须走 UI `launch`,决策权始终在用户。
41
- 4. **不替用户选择 ours/theirs**;不因为冲突文件多、Sheet 多而进入计划模式。
42
- 5. `apply` 默认写回并 `git commit`;`--no-commit` 仅测试决策时使用;`--push` 仅用户明确要求推送时使用,正常流程不自动 push。
43
- 6. 只处理单个文件时使用 `launch --path <仓库相对路径>`;多文件不按文件循环调用 `launch --path`,一次性同批次页面展示。
44
-
45
- ### 最高优先级快速流程
46
-
47
- 用户确认要处理冲突后,只做以下动作:
48
-
49
- 1. 执行检测:
50
-
51
- ```bash
52
- xlmerge --repo <repo> detect
53
- ```
54
-
55
- 2. `count > 0` 时立即启动解析器;不传 `--path`,一次性处理所有冲突工作簿:
56
-
57
- ```bash
58
- xlmerge --repo <repo> launch
59
- ```
60
-
61
- 3. `reviewCount > 0` 时,把 `launch` 返回的 `url` 告诉用户,然后停止分析,等待用户在页面完成选择。`launch` 负责提取全部 Git 三方版本、计算多文件多 Sheet diff、后台启动服务并打开浏览器。`reviewCount == 0` 时不会启动 UI,命令会写回所有过滤项、提交并返回 `autoResolved`。
9
+ 1. 用 `xlmerge --repo <repo> detect` 核对未合并的工作簿。没有冲突则结束。先核对 Git 合并双方,明确 ours 和 theirs 在本次操作中指向谁。
10
+ 2. 用 `xlmerge --repo <repo> prepare` 获取 manifest 路径。仅处理指定文件时加 `--path <相对路径>`。按 files[].diff.sheets 读取三方变化与项目规则、字段约束、引用及两侧提交意图。保留可兼容的单边变化。命中仓库既有 autoTheirs 规则的文件由工具处理。
11
+ 3. 对双边改动使用清单稳定 ID,记录选择和业务依据。只上报无法同时满足的具体取舍,保留当前清单和已判项。Agent 在获得裁决后续办原任务。
12
+ 4. 构造 decisions.json。例如同一工作表内两个字段分别取不同来源:
62
13
 
63
- 如果 `count` 为 `0`,报告没有未解决的 `.xlsx` / `.xlsm` 冲突并结束。
64
-
65
- ### 仓库过滤列表
66
-
67
- 过滤列表默认为空,仅在用户明确要求某类生成表始终采用远端整表时添加:
68
-
69
- ```bash
70
- xlmerge --repo <repo> filter add locale/Key.xlsx
71
- ```
72
-
73
- 命令把规范化后的相对 `.xlsx`/`.xlsm` 路径后缀写入仓库根目录 `.xlmerge.json` 的 `autoTheirs` 数组;匹配不区分大小写,重复添加是幂等操作。工具不内置任何业务路径。
74
-
75
- 命中过滤项的冲突文件不进入结构化分析或 UI,而是逐字节写入 Git index stage 3(theirs)。若 stage 3 不存在则安全失败;混合批次会在用户确认人工冲突后,与 UI 处理结果一起写回并提交。
76
-
77
- ### 快速流程禁止事项
78
-
79
- - 不调用通用 `xlsx` Skill、Excel API 或临时 Python 读取 base/ours/theirs。
80
- - 不运行 `prepare` 后读取 manifest,也不枚举或总结 Cell/Sheet 差异。
81
- - 不先搜索配置表结构、Luban schema、策划字段含义或项目代码。
82
- - 不替用户判断某个 Cell 应选 ours 还是 theirs。
83
- - 不因为冲突文件多、Sheet 多而进入计划模式;这些复杂度由工具内部流程处理。
84
- - 不使用阻塞式 `resolve` 作为正常入口;正常调用始终使用会快速返回 URL 的 `launch`。
85
- - 默认流程禁止按文件循环调用 `launch --path`;单个文件异常也必须由同一批次页面展示或明确报错。
86
-
87
- 只处理单个文件时,仍然直接使用 `launch --path <仓库相对路径>`。
88
-
89
- ### 程序负责的内部流程
90
-
91
- 以下内容由解析器自动完成,用于理解边界,不要由模型重复实现:
92
-
93
- 1. 从 Git index 提取 base/ours/theirs(stage 1/2/3)。含公式时,三方原始工作簿先分别在隔离副本中完整计算并固化最终值快照,再经内容锚点引擎生成 Sheet、行、列和 Cell 四级三方差异;不含公式时走原文件快路径。冲突身份是 `仓库相对路径 + 逻辑 Sheet + 逻辑行 ID + 逻辑列 ID`,物理坐标只用于展示;新增/删除行列后选择不会漂移。Luban 风格表头(`##var` / `##type` / `##group` / `##`)会被自动识别并保留,`##var` 为空的注释列、占位列同样参与对齐与写回。
94
-
95
- 2. 本地服务只监听 `127.0.0.1`,浏览器负责用户交互:
96
-
97
- - 顶部第一层标签切换冲突文件,第二层 `SHEET` 标签切换工作表;选择状态按文件和 Sheet 隔离。
98
- - 两侧修改同一 Cell 且结果不同:默认显示 `theirs`,单击可在 `ours` / `theirs` 间切换;只有一侧修改时默认采用修改侧,仍可单击覆盖。
99
- - 一侧删除 Sheet、另一侧修改:按整个 Sheet 选择保留 `ours` 或 `theirs`;只在一侧新增的 Sheet 自动保留。
100
- - `.xlsm` 的 VBA/ActiveX 单边变化自动采用变化侧;双边变化时在文件级选择本地宏/远端宏(默认本地)。
101
- - 相对本地可自动合入的远端新增行/列用浅绿色整行/列展示并锁定;已确定删除的行/列用灰色墓碑展示并锁定。
102
- - 单击行号/列头批量切换;“全部本地/全部远端”作用于当前 Sheet;“撤销”回退最近一次选择,“重置”恢复默认三方选择。
103
- - 当前 Sheet 提供上一个/下一个冲突定位,覆盖可人工选择的单侧改动及双侧冲突,支持跨页循环跳转;每个含可选择改动或结构冲突的 Sheet 必须独立勾选“已确认”,顶部统计跨文件显示已确认数量,未全部确认时提交会给出可点击的定位清单。双方一致变化和锁定的自动处理项不单独要求确认。
104
- - 悬停 Cell 时展示 base、双方值、双方文件作者和当前选择。
105
-
106
- 3. 用户点击“写回并提交”后:
107
-
108
- - 先请求只读 `/api/commit-preview` 生成 commit 信息,弹出居中的二次确认窗口;确认后才执行写回与 `git add` / `git commit`。
109
- - 以原始 `ours` 工作簿为宏包/样式基底重建受影响 Sheet;受影响 Sheet 的全部公式写为已验证的最终静态值,未受影响 Sheet 保留原公式及缓存。保留所选来源的样式、批注、超链接、数字格式、行高列宽、冻结拆分等视图状态。
110
- - 保存到仓库原路径并重新打开验证可读;`.xlsm` 全程 `keep_vba` 模式,保存后逐字节校验 VBA 负载。
111
- - 存在冲突 Cell 选择时自动生成结构化提交信息(每个冲突 Cell 一行,含表、Sheet、单元格、选择、双方值);过滤项以“远端全量”记录,`--message` 可覆盖。
112
- - 可视化入口不自动 push。
113
-
114
- 4. 用户完成页面操作并返回后复核:
115
-
116
- ```bash
117
- git -C <repo> diff --name-only --diff-filter=U
118
- git -C <repo> status --short --branch
119
- git -C <repo> log -1 --oneline
14
+ ```json
15
+ {"files":{"<文件ID>":{"sheets":{"<Sheet名>":{"cells":{"<逻辑单元格ID一>":"ours","<逻辑单元格ID二>":"theirs"}}}}}}
120
16
  ```
121
17
 
122
- 第一条必须无输出;随后报告处理的文件、Sheet、人工选择数量和 commit 结果。
18
+ 工作表冲突使用 sheet,重命名用 rename,合并区域用 mergedCells,均按清单选 ours/theirs。rows 和 columns 中的 delete_modify 按 ID 选 keep/delete。宏冲突使用文件级 macro。遇到需要工作簿两侧都没有的新值,单独安排普通改表与验证。
123
19
 
124
- ### 非交互入口
20
+ 5. 用 `xlmerge --repo <repo> apply --manifest <manifest.json> --decisions <decisions.json> --no-commit` 写回并暂存。逐项核对 success、Git 未合并列表与暂存结果;按原授权继续合并或交 Reviewer。只在明确要求推送时推送。来源变动重新 prepare;写回结果未知时先检查实际工作簿与索引。
21
+ 6. 用户想亲自审阅时可用 launch,status/cancel 使用同一会话的 manifest。launch 在所有文件都命中 autoTheirs 时会直接完成合并并提交。只有明确要求长期改变过滤策略才用 filter add。
125
22
 
126
- 仅在自动化测试或用户已提供明确决策 JSON 时使用 prepare/apply;不要用于查看 diff。决策必须同时包含文件、Sheet 和 Cell(Cell 优先使用 manifest 的稳定逻辑 ID):
127
-
128
- ```bash
129
- xlmerge --repo <repo> prepare
130
- xlmerge --repo <repo> apply --manifest <manifest.json> --decisions <decisions.json>
131
- ```
132
-
133
- 测试决策但不 commit 时加 `--no-commit`;只有用户明确要求推送时加 `--push`。
134
-
135
- ### 边界与失败处理
23
+ ## 调用规范
136
24
 
137
25
  - 只处理 Git 未合并状态中的 `.xlsx` / `.xlsm`;不处理普通修改。
138
26
  - 文件级 delete/modify 冲突缺少完整双方工作簿时,解析器停止并报告;不要猜测删除还是保留。
139
27
  - 过滤项要求 Git stage 3 存在;缺少远端版本时停止并报告,不退回本地版本。
140
- - 写回前必须收齐所有人工选择;缺少任何选择时不改工作树。
28
+ - 写回前必须收齐所有必需裁决;缺少任何选择时不改工作树。
141
29
  - prepare 生成的三方来源、审阅值快照和当时工作树指纹会在 apply 前全部校验;快照篡改、Git stage 变化、计算未完成或不可靠公式语义都会明确中止,整批次不写回、不 `git add`。
142
- - 三方计算错误保留原公式、错误与位置作为未知值进入同一批次 UI,必须选择有效来源;无法可靠确认记录身份、表头或行列结构时必须选择整个 Sheet。双方同一记录、同一字段都错误时,工具按一致的显式基础类型替换(数值 0、string 空串、bool false),保留审计信息;ID、引用、约束字段、未知类型、重复 ID 不自动替换。未经处理的错误不能写回,安全限制不变。Agent 不代替用户选择人工项。
30
+ - 三方计算错误保留原公式、错误与位置作为未知值进入同一批次 UI,必须选择有效来源;无法可靠确认记录身份、表头或行列结构时必须选择整个 Sheet。双方同一记录、同一字段都错误时,工具按一致的显式基础类型替换(数值 0、string 空串、bool false),保留审计信息;ID、引用、约束字段、未知类型、重复 ID 不自动替换。未经处理的错误不能写回,安全限制不变。业务歧义按任务的决策渠道上报。
143
31
  - 所有人工表和自动表先生成临时输出并通过预检,再统一替换;替换中途失败会回滚已替换文件,若文件系统同时阻止回滚则保留恢复副本并报告路径。
144
32
  - 替换失败(如 Excel 正在占用目标文件,替换整体回滚)时,应要求用户关闭该工作簿后重试。
145
33
  - 不直接修改 XLSX 内部 XML,不使用未经本次完整计算验证的旧公式缓存冒充最终值。
package/v-cli.plugin.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "package": "@kevlns/xlmerge",
4
4
  "command": "xlmerge",
5
5
  "bin": "xlmerge",
6
- "description": "在浏览器中审阅 Git 冲突工作簿的三方差异,校验后写回并提交合并结果。",
6
+ "description": "处理 Git 中的 Excel 三方冲突,支持 Agent 根据项目规则裁决并写回,也支持浏览器逐项审阅。",
7
7
  "platforms": [
8
8
  "darwin",
9
9
  "linux",
@@ -32,7 +32,7 @@
32
32
  }
33
33
  ],
34
34
  "agent": {
35
- "whenToUse": "When a user asks to resolve Git merge conflicts in .xlsx/.xlsm planning or configuration tables (策划表/配置表冲突): run detect first; when reviewCount > 0 run launch and give the returned url to the user. Configured auto-theirs filters may resolve and commit matched generated workbooks without opening the UI. Do not inspect workbook cells or summarize diffs yourself; the resolver owns diff, choices, write-back and commit.",
35
+ "whenToUse": "在发生合并的工区 detect → prepare,读取 manifest 中 base/ours/theirs 的差异与稳定 ID,按项目约束及变更意图裁决。仅将无法判断的业务项交控制源。用 apply --no-commit 写回并验证 Git 索引,按原任务完成提交或交付。用户选择可视化审阅时使用 launch。",
36
36
  "globalOptions": [
37
37
  {
38
38
  "flags": "--repo <path>",
@@ -217,7 +217,7 @@
217
217
  },
218
218
  {
219
219
  "flags": "--no-commit",
220
- "description": "写回后不执行 git add/commit。"
220
+ "description": "写回并暂存已解决的工作簿,保留当前合并,跳过提交。"
221
221
  },
222
222
  {
223
223
  "flags": "--push",