spec 生成物没有 merge driver:两个 PR 各改几行,语义上是集合运算,却每次都打成文本冲突 #4675

Activity

1. os-zhuang

   added

   enhancementNew feature or requestNew feature or request

   on Aug 2, 2026
2. os-zhuang commented on Aug 2, 2026

   

   os-zhuang

   on Aug 2, 2026 – with Claude

   ContributorAuthor

   More actions

   ⚠️ 自我更正:merge driver 解决不了合并队列的弹出,只解决本地返工

   立单时我把本单说成「立刻消除返工」。这话对本地 git merge origin/main 成立,对 GitHub 合并队列不成立,差别很重要。

   .gitattributes 里的 merge=os-regen 只是给合并策略起个名字;真正的驱动要在 git config merge.os-regen.driver 里定义,那是本地配置,不随仓库提交。GitHub 的服务端合并(合并队列、Update branch、squash)不会、也无法执行自定义 merge driver。

   实测佐证(2026-08-02):PR #4670 在解决完与 #4664 的冲突、全绿入队后,仍被队列以 MERGE_CONFLICT 弹出 —— 因为期间 main 又前进了 #4668、#4660 两个 spec PR。merge driver 即使已落地也拦不住这一次。

   修正后的定位

   • 本单仍然值得做:它消除的是 agent / 开发者在本地反复解同一类冲突的返工(今天实测三次,每次十几分钟门禁重跑)。
   • 但它不是队列弹出的解药。能减少队列冲突的是缩小冲突面 —— 即 投影类生成物是否该退出仓库 —— 分清「记忆」与「投影」,前者必须留在 PR 粒度,后者可以 CI 重算 #4676 把投影类移出仓库。以 feat(spec)!: converge RetryPolicy onto one declaration (#4661, C8) #4670 为例,6 个冲突文件里有 4 个(api-surface.json、spec-changes.json、docs/protocol-upgrade-guide.md,加上 gen:docs 产物)属投影类;移出后只剩 authorable-surface.json 与两个手写登记表。

   所以两单的优先级与我立单时写的相反:#4676 才是对队列有效的那个,#4675 是对本地开发体验有效的那个。已同步更新 #4676。

   (另一个与队列相关的现实解法是降低并发 —— v17 收尾期 main 上 spec PR 密度极高,最近 8 个提交里 6 个动 spec。这属于流程协调,不属于本单。)

   ---

   Generated by Claude Code
3. os-zhuang commented on Aug 2, 2026

   

   os-zhuang

   on Aug 2, 2026 – with Claude

   ContributorAuthor

   More actions

   已验证的先行实现(2026-08-02,用它解决了 PR #4670 的冲突)

   维护者问是否现在同步做本单。建议排到 v17 之后,理由见上一条更正(driver 是客户端机制,救不了合并队列)+ 两点:本单自身也要挤同一个队列;且 driver 需要每个 clone 单独 git config merge.<name>.driver,而 agent 都在新建 worktree 里工作,等于给派发流程加一步配置。

   但解法本身已经跑通了,留给实现者省一轮摸索。

   三路集合合并

   这批生成物是排序集合,合并语义是集合运算而非文本:

   • 任一侧显式删除某条目 → 结果中删除(退休 / 收敛清理)
   • 任一侧新增 → 结果中保留
   • 双方各自增删 → 直接可组合,无需人工判断

   git show :1:/:2:/:3: 拿到 base/ours/theirs 后按此规则合并即可。核心逻辑:

   function mergeStringArray(base, ours, theirs) {
     const B = new Set(base), O = new Set(ours), T = new Set(theirs);
     const out = new Set();
     for (const v of new Set([...O, ...T])) {
       const inB = B.has(v);
       if ((inB && !O.has(v)) || (inB && !T.has(v))) continue; // 任一侧的显式删除胜出
       out.add(v);
     }
     return [...out].sort();
   }

   对象节点递归、标量取「相对 base 变了的那一侧」。

   实测结果(PR #4670 合并 origin/main):7 个冲突文件里 api-surface.json / authorable-surface.json / dual-source-exports.baseline.json git 自己就合干净了,spec-changes.json 用上述集合合并秒级解决,结果正确 —— dual-source-exports.baseline.json 从 base 的 22 条正确收敛到 19(本 PR 删 RetryPolicy ×2,main 的 #4662 删 ActivationEventSchema ×1)。

   两个坑

   1. 必须保留生成器的尾换行约定。check:generated 比对字节,凭空加/减一个 \n 会让 CI 因纯装饰性原因变红。从 :2: 的原始字节判断即可。
   2. 手写登记表不适用集合合并。conversions/registry.ts / migrations/registry.ts 是代码,且双方新增的条目会共享结构行(});、fixture: {),union 策略会把两个条目的片段拼碎。feat(spec)!: converge RetryPolicy onto one declaration (#4661, C8) #4670 里可行的办法是:以 main 版为底,把 diff base ours 的 hunk 用 patch -F3 打上去,然后逐一验证注册落在正确的聚合数组里(fuzz 匹配可能落错位置 —— 我实测两个 hunk 都用了 fuzz 3,验证后确认正确)。

   所以 driver 的覆盖范围应当只含生成物,.gitattributes 里不要把两个 registry 纳进来。

   生成器不可用时的降级

   driver 跑不了生成器(裸 CI、rebase 中间态、worktree 未 pnpm install)时,集合合并不需要任何依赖,只要 node,可以作为主路径而不只是降级 —— 再由 CI 的 check:generated 验证结果确实等于重新生成。#4670 走的就是这条路。

   ---

   Generated by Claude Code
4. os-zhuang commented on Aug 2, 2026

   

   os-zhuang

   on Aug 2, 2026 – with Claude

   ContributorAuthor

   More actions

   ⚠️ 更正上一条:集合合并只对字符串数组成立,对象数组会丢条目

   上一条我把三路集合合并当作先行实现贴了出来。那段代码有缺陷,实测把 CI 打红了,在有人照着实现之前必须说清。

   发生了什么

   PR #4670 用它解决 spec-changes.json 的冲突后,CI 报:

   spec-changes.json is stale — the ADR-0087 registries changed without regenerating the manifest.
   Run: pnpm --filter @objectstack/spec gen:spec-changes  (and commit the result)
   

   原因:spec-changes.json 装的是对象数组(变更记录),不是字符串数组。我那段代码只在「两侧元素全是字符串」时走集合合并,其余情况回退成「取相对 base 变了的那一侧」—— 直接丢掉另一侧的条目。本 PR 因此丢了 main 侧 #3355 的 object-managed-by-system-to-system-data。

   修正后的适用边界

   文件	结构	集合合并
   dual-source-exports.baseline.json	字符串数组	✅ 实测正确(22 → 19)
   authorable-surface.json	字符串数组	✅ (本次 git 自己就合干净了)
   docs-import-surface.baseline.json	字符串数组	✅
   api-surface.json	嵌套字符串数组	✅
   spec-changes.json	对象数组	❌ 必须跑生成器
   docs/protocol-upgrade-guide.md	markdown	❌ 生成器(本次手工保留两行恰好与生成结果一致,是运气)

   对象数组要做正确的集合合并,得先定义元素身份(如 id),再按 id 做三路合并。 但 spec-changes.json 是 ADR-0087 登记表的投影 —— 与其猜它的合并语义,不如直接从已合并好的登记表重算,那才是唯一正确的定义。

   给实现者的结论

   driver 不要试图用通用集合合并覆盖所有生成物。分两档:

   1. 纯字符串集合的 ratchet 基线 —— 集合合并安全,且不需要任何依赖(只要 node),在裸环境也能跑。
   2. 投影类(spec-changes.json、upgrade guide、reference 文档、api-surface.json)—— 必须跑生成器。好消息是成本比想象低:本次 pnpm install --filter @objectstack/spec... 走缓存 2.5 秒,gen:spec-changes + gen:upgrade-guide 秒级完成。

   也就是说本单原本设想的「driver 调生成器」是对的,我上一条提出的「集合合并作为主路径」只适用于第 1 档。

   附带教训

   「让 CI 验」这条快路径确实抓住了错误 —— 但它抓住的是一个本可以在本地十秒内避免的错误(跑一次 check:spec-changes 即可)。跳过本地验证换来的时间,被一次 CI 往返和一次队列重排赔了回去。若 driver 落地,它应当在解决完冲突后自动跑对应的 check:*,而不是把验证推给 CI。

   ---

   Generated by Claude Code
5. os-zhuang commented on Aug 2, 2026

   

   os-zhuang

   on Aug 2, 2026 – with Claude

   ContributorAuthor

   More actions

   第四个样本，以及一条会改变实现方式的失败模式

   今晚 #4687 与 main（742cebb）又撞了一次，按本单的分类拆开完全吻合：

   冲突文件	建议清单里的 driver	实际正确解法
   packages/spec/spec-changes.json	gen:spec-changes	丢掉两边文本，重新生成
   docs/protocol-upgrade-guide.md	gen:upgrade-guide	丢掉两边文本，重新生成
   packages/spec/src/migrations/registry.ts	本单明确排除	双方各自追加一条 retirement，保留两边

   前两个是生成物，我实际做的就是 git checkout 掉冲突副本再跑生成器——和本单的处方逐字一致。第三个是手写登记表，正如实现注意 2 所说需要人看，但也确实又一次是「保留两边」。driver 会把 3 个冲突降到 1 个，且消掉的恰好是贵的那两个（重新生成 + 重跑门禁）。三次冲突里仍然没有一次是真语义冲突。

   实现注意 3 需要加强：不可用是安全的，陈旧才是危险的

   原文的顾虑是「driver 在裸 CI 或 rebase 中间态可能不可用」。不可用其实是安全的失败——它会报错，人能看见。真正危险的是可用但 dist 陈旧。

   api-surface.json 的生成器 readsDist。本会话实测过一次：在不完整的 dist 上跑 gen:api-surface，它静默抹掉了一个与本次改动完全无关的 ./studio 的 ActivationEvent (type) 导出，并顺手往 docs-import-surface.baseline.json 里为这个缺口加了一条棘轮豁免——正是该工具自己警告过的「棘轮悄悄停止棘轮」。没有任何报错；是把生成物与 main 逐文件对比才发现的。

   放到 merge driver 的语境里，这个性质会翻转本单的收益：

   冲突标记是可见的错误；静默生成的错误内容是不可见的错误。

   一个对 api-surface.json 乐观重算的 driver，会在 dist 陈旧时把「人能看见的冲突」换成「人看不见的错误产物」，而且它落在 diff 里长得完全合理。那比现状更糟。

   建议

   api-surface.json 这一条（以及任何 readsDist 的生成器）应当 fail-loud 而非 best-effort：

   1. 先 build 再 regen；或
   2. 检测到 dist 比 src 旧 / 缺失时拒绝生成，保留冲突标记并提示手工跑生成器。

   不读 dist 的那几个（gen:schema、gen:spec-changes、gen:upgrade-guide、gen:docs）没有这个问题，可以直接按原方案重算——今晚我手工走的正是这条路径，结果与门禁完全一致（17 项 check:* 全绿）。

   与 #4663 的互补关系不变：那边要求生成物与重算结果逐字节相同，本单保证冲突时必定走重算——前提是重算本身可信，这也正是上面那条要求存在的理由。

   ---

   Generated by Claude Code
6. os-zhuang

   closed this as completedin #4702on Aug 2, 2026
7. akarma-synetal

   added 2 commits that reference this issue on Aug 3, 2026

   build: merge driver for generator-owned spec artifacts (objectstack-a…

   ...

   e336549

   fix(spec): --check must not write json-schema.manifest.json (objectst…

   ...

   23338c3
8. os-zhuang

   added 4 commits that reference this issue on Aug 7, 2026

   Merge origin/main into claude/issue-5553-file-description-rendering

   ...

   c500a43

   chore(docs): 合入 main 后整体重跑 gen:schema && gen:docs (#5553, #6136)

   ...

   201ab12

   Merge origin/main into claude/issue-5553-file-description-rendering

   ...

   a1c6ed5

   Merge origin/main into claude/issue-5553-file-description-rendering

   ...

   72afb37