拓冰网站定制 
Orca 跨执行主机的 Git 兼容性策略以能力探测为核心的 Git 版本适配体系【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orcaOrca 作为面向多智能体并行工作的桌面端与远端运行时会调用用户机器上已安装的 Git 二进制完成仓库操作而这些 Git 可能运行在 native、WSL、SSH 三类差异极大的执行主机上。本文以仓库中的 Git Compatibility Policy 为骨架结合 git-capability-cache.ts 等源码实现完整讲解 Orca 如何以 Git 2.25 为兼容基线、通过“行为探测 精确回退 主机级缓存”来适配多版本 Git并给出 CI 验证契约。读完本文你将理解 Orca 的能力矩阵、GitCapabilityCache的运行机制、为何不能依赖git --version分支判断以及如何为新增的 Git 特性安全地建立降级路径。一、适用范围三类执行主机与主机级能力状态Orca 不会自己解析 Git 仓库的内部格式而是执行用户的 Git 二进制。该二进制可能出现在三类执行主机上git-compatibility.md 的Scope一节nativeOrca 直接在本机操作系统上调用的 GitWSLWindows 下经 WSL 发行版distro调用的 GitSSH通过 SSH 连接到的远端主机上的 Git。每一台主机的 Git 版本都可能不同因此“某个能力是否可用”这一兼容性状态必须按真正执行命令的那台主机来划分作用域而不能是进程级的单一全局状态。这一点在源码中体现得很直接git-capability-state.ts 里用const localCapabilitiesByExecutionHost new Mapstring, GitCapabilityCache()维护本地主机含 WSL各自的缓存键由getLocalGitExecutionHostKey生成存在 WSL distro 时返回wsl:${distro}否则返回local而 SSH 侧则使用WeakMapobject, GitCapabilityCachesshCapabilitiesByProvider——因为重连会产生新的 provider 对象而同一 SSH 连接的并发 IPC/runtime 调用方必须共享同一份远端能力结果。文件头注释还解释了为何不用普通 Map 存 SSH provider避免 provider 销毁后内存无法回收。2.25 核心工作流基线文档明确约定Git 2.25 是命令选型的核心工作流兼容基线。它是最老的、能覆盖 Orca 基线用法的版本线涵盖以下能力porcelain v2git status --porcelainv2输出解析branch --show-currentrestore命令sparse checkout稀疏检出。仓库中确实同时维护了新旧两种输出通道的实现例如 porcelain-v2-records.ts 与 porcelain-v1-records.ts 并存以及 worktree-sparse-checkout.ts 等稀疏检出相关实现这正印证了“永远保留基线可用的命令或解析器作为回退”的工程原则。需要强调的是两条基线约束Orca当前不在启动时阻止旧版 Git即旧 Git 用户仍可使用但新命令的构造不得假设存在 2.25 之后才引入的特性——凡是依赖新特性的地方都必须走下面的能力规则。二、能力规则新增特性如何安全降级当一个较新的 Git 特性确实能显著改善正确性或性能时Orca 要求开发者遵循五步规则文档Capability Rules一节保留基线兼容的命令或解析器作为 fallback用针对该选项/子命令的窄谓词narrow predicate识别“被拒绝”而不是笼统地匹配任意报错让首选命令经由GitCapabilityCache执行这样一次拒绝会被“记住”并归属到产生该拒绝的 native 主机、WSL 发行版或 SSH provider 名下在缓存间隔之后重试使原地升级 Gitin-place upgrade无需重启 Orca 即可自愈测试首个 fallback、后续跳过已拒绝探测的调用、并发探测合并coalescing、以及执行主机隔离。为什么不能用git --version做分支文档给出一条非常明确的工程纪律不要只依据解析出的git --version字符串来分支。原因有二发行版厂商会 backport某些发行版会把新特性移植回旧版本号wrapper 会撒谎外层包装程序报告的宿主版本可能与实际在 WSL 或 SSH 内部真正执行的二进制版本不一致。因此最终裁决权属于行为探测 精确回退版本号只能作为提示。这正是CapabilityProbeCache存在的意义。缓存与探测的运行机制能力缓存的核心实现在 capability-probe-cache.ts。值得注意该文件头注释说明它是“从GitCapabilityCache中抽取出来”的通用基类目标是为仓库里所有主机能力缓存统一三种行为探测一次、只记住“确实缺失”的阳性信号、让并发调用等待正在进行的探测而不是重复发起。它的内部状态由三个容器构成retryAfterByCapability: MapTCapability, number——记录某能力被判定为不支持后的重试时间点probesByCapability: MapTCapability, PromiseOutcome——正在进行的探测 promise用于并发合并supportedCapabilities: SetTCapability——已被证明支持的能力集合。其公开 API 及语义如下与源码对应API行为shouldTry(capability)能力从未失败或已过重试期则返回true未到重试期返回false调用方直接走 fallbackisKnownSupported(capability)该能力是否已被证明支持rememberSupported(capability)主动记录支持清除失败时间并加入集合rememberUnsupported(capability)记录“不支持”从支持集合删除并把重试时间设为now retryIntervalMs见 git-capability-cache.ts 中的GIT_CAPABILITY_RETRY_INTERVAL_MS 30 * 60_000即 30 分钟runWithFallback(capability, runPreferred, runFallback, isUnsupportedError)探测并执行的首选入口clear()测试与重置用runWithFallback是整套机制的心脏值得逐行拆解其状态机capability-probe-cache.ts若能力已在supportedCapabilities中直接“乐观”地执行首选路径——注意注释强调“受支持的命令是真实工作而非一次性探测”所以要让同仓库/同 SSH 的并发调用保持原有并发度不再走探测锁若shouldTry返回false仍在 30 分钟冷却期直接执行 fallback避免每个 poll/search 都重复一次已知失败、白白消耗子进程与 trace 空间若已有 in-flight 探测则等待其 outcome再决定走首选还是 fallback——这就是“并发探测合并”否则由本调用充当探针把 promise 放入probesByCapability执行runPreferredOrFallback无论成功失败都会 settle 出supported | unsupported | unknown三种结果之一并在finally中清理探测槽位且有一个防挂起的兜底即便isUnsupportedError抛异常等待方也不会永久等待。在runPreferredOrFallback内部有一个精妙细节首选回调成功返回后并不会盲目标记为 supported而是检查该能力是否已被回调自己在执行过程中通过更弱的“阳性信号”例如旧 Git 对未知选项原样回显且 exit 0标记为 unsupported——如果有更强的否定信号就不覆盖它。只有真正确认支持时才写入supportedCapabilities。专门的并发探测合并实现见 coalesced-probe.ts 及其测试 coalesced-probe.test.ts用于验证“同一能力并发请求只发起一次真实探测”。三、当前能力矩阵文档用一张表完整列出了当前登记在案的能力及其首选/兼容行为这里完整继承并逐项结合源码展开Capability首选行为兼容行为fetch-no-write-fetch-headFetch 私有 rebase ref 时不改写 worktree 本地的FETCH_HEADGit 2.29 之前按 worktree Git 目录串行化 Orca 的所有 fetch/pull 操作worktree-list-zNUL 分隔的 worktree 路径并带prunable标记对worktree list -z2.36之前的 Git 使用行块解析器Git 2.31–2.35 上仍可解析prunable/locked注解2.31 之前的 Git 用路径存在性探测恢复prunable检测rev-parse-path-format返回绝对仓库元数据路径针对被扫描仓库解析旧版相对路径输出for-each-ref-exclude在输出上限之前先排除远端 HEAD多请求部分 refs再由 Orca 内部过滤远端 HEADmerge-tree-write-tree推导真实合并冲突与 no-op tree 证明Git 2.38 之前省略冲突摘要并保持保守的分支清理行为merge-tree-merge-base提供已解析的 merge base使用旧版两提交形式的merge-tree --write-tree所有这些能力标识构成一个受类型约束的联合定义在 git-capability-cache.ts 的GitCapability类型中编译期即可防止拼错能力名。逐项源码印证worktree-list-z/rev-parse-path-format在 worktree-list-reader.ts 中可以看到真实调用模式——通过withLocalGitCapabilityCacheForExecution拿到主机对应的缓存后以capabilities.runWithFallback(...)包裹首选与回退两种解析路径当首选路径失败且被窄谓词判定为“不支持”时还会显式调用capabilities.rememberUnsupported(rev-parse-path-format)见第 63、114 行并在第 203–207 行对worktree-list-z走同样的runWithFallback。对应地判别函数isUnsupportedWorktreeListZError位于 git-worktree-command-capabilities.ts。fetch-no-write-fetch-head在 remote-rebase.ts 中rebase 前的 fetch 通过withLocalGitCapabilityCacheForExecution包裹并探测fetch-no-write-fetch-head其第 58 行注释点出了该问题的根源并发 fetch 会在 fetch 与 rebase 之间改写FETCH_HEAD与 remote-tracking refs这正是首选行为要规避的竞态而兼容行为则牺牲并发换取正确性。merge-tree-write-tree/merge-tree-merge-base两个能力的窄谓词都在 git-merge-tree-capability.ts 中实现它们不是宽泛地匹配任何报错文本而是精确匹配 Git 的报错形态isUnsupportedMergeTreeWriteTreeError匹配unknown/invalid/unrecognized option ... --write-tree、unknown rev --write-tree以及旧版git merge-tree base-tree branch1 branch2的 usage 文本isUnsupportedMergeTreeMergeBaseError只匹配--merge-base选项不被识别的报错。for-each-ref-exclude判别函数isForEachRefExcludeUnsupportedError位于 git-ref-command-capabilities.ts它把错误文本小写化后要求同时包含unknown option与exclude才判定为不支持——这就是“窄谓词”的典型范例。窄谓词为何必须“窄”窄谓词直接决定能力状态机的正确性若谓词过宽会把真实的 Git 故障如网络错误、仓库损坏、权限问题误判为“该选项不受支持”从而悄悄把用户导向功能缩水的兼容路径掩盖真正的错误若过窄则探测会反复失败并不断触发 fallback。因此每个谓词都要精确模拟 Git 针对“该选项不存在”时的报错形态而这类形态恰恰无法用单个真实二进制在 CI 中确定性地构造这也是文档要求单元测试覆盖“error-stream shapes”的原因见下文 CI 契约。四、占位符“Fail Open”问题%(decorate:…)文档特别辟出一节讨论一类无法被缓存记录的失败模式。GitCapabilityCache记录的是 Git明确拒绝的命令但git log --format的占位符如果 Git 不认识并不会报错——Git 会把它原样回显并 exit 0因此“没有错误可记也没有可缓存的探测”。Placeholder首选行为兼容行为%(decorate:…)Git 2.43 起用\x1f分隔提交装饰信息含逗号的 ref 名因此可以存活同一条记录同时携带%DGit 2.10 可用解析时若发现%(decorate未被展开则退回%D代价是逗号会被拆开解决思路是文档明确给出的在一条记录里同时请求两种形式在解析阶段再做选择。也就是说输出的 log 记录同时携带%(decorate:...)与%D两个字段解析器看到%(decorate仍保持原样未被 Git 展开就说明二进制太老于是改用%D的语义。这是“探测 回退”哲学在“无法被拒绝、只能被静默透传”的场景下的变体把兼容性判断从执行时推迟到解析时。五、为什么不用simple-git文档单列一节解释不采用simple-git库的架构决策。simple-git本质是已安装 Git 二进制外的进程包装器其自定义选项与rawAPI 只是把参数透传给 Git因此它无法让一个新 flag 在一个旧二进制上生效它也无法自动替 Orca 选择语义等价的自定义回退。simple-git固然提供了版本报告与子进程队列但这些恰恰不是 Orca 的瓶颈。Orca 自身已经需要实现 WSL/SSH 路由、取消、追踪、敏感信息脱敏、进程清理与有界输出处理这些能力散见于 src/main/git 下的 runner、wsl-* 系列文件与 command-runner 子目录。若引入simple-git替换 runner能力问题只是从一个地方搬到另一个地方并没有被消除反而会引入一层无法接入 Orca 主机路由与能力缓存的间接层。六、CI 契约真实二进制矩阵 单元测试矩阵能力策略是否成立最终靠 CI 契约来兜底文档CI Contract一节。PR 检查会针对真实 Git 二进制运行能力契约覆盖三个版本点Git 2.25.5验证 2.29 之前串行化FETCH_HEAD的回退路径最老的受支持版本线Git 2.38.1验证--merge-base出现之前、过渡期的merge-tree --write-tree行为Git 2.49.1验证当前 Git 下的首选行为。这三个版本横跨了能力矩阵中的关键分水岭。更重要的是文档强调要让单元测试与该矩阵并行存在真实二进制无法确定性地构造某些场景因此单测必须覆盖并发探测合并见 coalesced-probe.test.tsnative / WSL / SSH / relay 的执行主机隔离见 git-capability-state.test.ts 与 git-capability-cache.test.ts后者还覆盖缓存重试、同主机多调用跳过重复探测等行为错误流形态error-stream shapes——即各类窄谓词对真实 Git 报错文本的匹配例如 git-merge-tree-capability.test.ts 会验证上面那些正则是否能命中、是否会误伤其他错误。仓库中另有 worktree-git-capabilities.test.ts将 worktree 场景与 Git 能力矩阵绑定做真实 Git 级别的验证与文档描述的“真实二进制矩阵 单测矩阵并行”完全吻合。七、给调用方与贡献者的工程要点把整篇策略收敛为几条可直接落地的工程要点新命令一律按“最老的支持版本”假设任何超出 Git 2.25 基线的特性都要走runWithFallback(capability, runPreferred, runFallback, isUnsupportedError)不要把版本判断写死在命令构造处一律通过能力缓存且每个能力都要有独立的窄谓词新能力三步接入在 git-capability-cache.ts 的GitCapability联合类型里登记名称 → 用主机级缓存包装调用点参考 worktree-list-reader.ts 的既有用法→ 为该能力补窄谓词放在 shared 下对应 capability 模块与单测区分“被拒绝”与“被静默透传”对git log --format这类会 exit 0 的占位符采用“同记录双形式 解析时选择”而非“探测 缓存”版本自愈依赖 30 分钟重试窗口rememberUnsupported写入的冷却期意味着用户原地升级 Git 后最多 30 分钟内 Orca 会自动重新探测到新能力无需重启。这条策略的完整原始定义始终以仓库中的 git-compatibility.md 为权威来源本文的所有源码引用均可在 src/shared 与 src/main/git 目录下复核。【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Orca 跨执行主机的 Git 兼容性策略：以能力探测为核心的 Git 版本适配体系
Orca 跨执行主机的 Git 兼容性策略以能力探测为核心的 Git 版本适配体系【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orcaOrca 作为面向多智能体并行工作的桌面端与远端运行时会调用用户机器上已安装的 Git 二进制完成仓库操作而这些 Git 可能运行在 native、WSL、SSH 三类差异极大的执行主机上。本文以仓库中的 Git Compatibility Policy 为骨架结合 git-capability-cache.ts 等源码实现完整讲解 Orca 如何以 Git 2.25 为兼容基线、通过“行为探测 精确回退 主机级缓存”来适配多版本 Git并给出 CI 验证契约。读完本文你将理解 Orca 的能力矩阵、GitCapabilityCache的运行机制、为何不能依赖git --version分支判断以及如何为新增的 Git 特性安全地建立降级路径。一、适用范围三类执行主机与主机级能力状态Orca 不会自己解析 Git 仓库的内部格式而是执行用户的 Git 二进制。该二进制可能出现在三类执行主机上git-compatibility.md 的Scope一节nativeOrca 直接在本机操作系统上调用的 GitWSLWindows 下经 WSL 发行版distro调用的 GitSSH通过 SSH 连接到的远端主机上的 Git。每一台主机的 Git 版本都可能不同因此“某个能力是否可用”这一兼容性状态必须按真正执行命令的那台主机来划分作用域而不能是进程级的单一全局状态。这一点在源码中体现得很直接git-capability-state.ts 里用const localCapabilitiesByExecutionHost new Mapstring, GitCapabilityCache()维护本地主机含 WSL各自的缓存键由getLocalGitExecutionHostKey生成存在 WSL distro 时返回wsl:${distro}否则返回local而 SSH 侧则使用WeakMapobject, GitCapabilityCachesshCapabilitiesByProvider——因为重连会产生新的 provider 对象而同一 SSH 连接的并发 IPC/runtime 调用方必须共享同一份远端能力结果。文件头注释还解释了为何不用普通 Map 存 SSH provider避免 provider 销毁后内存无法回收。2.25 核心工作流基线文档明确约定Git 2.25 是命令选型的核心工作流兼容基线。它是最老的、能覆盖 Orca 基线用法的版本线涵盖以下能力porcelain v2git status --porcelainv2输出解析branch --show-currentrestore命令sparse checkout稀疏检出。仓库中确实同时维护了新旧两种输出通道的实现例如 porcelain-v2-records.ts 与 porcelain-v1-records.ts 并存以及 worktree-sparse-checkout.ts 等稀疏检出相关实现这正印证了“永远保留基线可用的命令或解析器作为回退”的工程原则。需要强调的是两条基线约束Orca当前不在启动时阻止旧版 Git即旧 Git 用户仍可使用但新命令的构造不得假设存在 2.25 之后才引入的特性——凡是依赖新特性的地方都必须走下面的能力规则。二、能力规则新增特性如何安全降级当一个较新的 Git 特性确实能显著改善正确性或性能时Orca 要求开发者遵循五步规则文档Capability Rules一节保留基线兼容的命令或解析器作为 fallback用针对该选项/子命令的窄谓词narrow predicate识别“被拒绝”而不是笼统地匹配任意报错让首选命令经由GitCapabilityCache执行这样一次拒绝会被“记住”并归属到产生该拒绝的 native 主机、WSL 发行版或 SSH provider 名下在缓存间隔之后重试使原地升级 Gitin-place upgrade无需重启 Orca 即可自愈测试首个 fallback、后续跳过已拒绝探测的调用、并发探测合并coalescing、以及执行主机隔离。为什么不能用git --version做分支文档给出一条非常明确的工程纪律不要只依据解析出的git --version字符串来分支。原因有二发行版厂商会 backport某些发行版会把新特性移植回旧版本号wrapper 会撒谎外层包装程序报告的宿主版本可能与实际在 WSL 或 SSH 内部真正执行的二进制版本不一致。因此最终裁决权属于行为探测 精确回退版本号只能作为提示。这正是CapabilityProbeCache存在的意义。缓存与探测的运行机制能力缓存的核心实现在 capability-probe-cache.ts。值得注意该文件头注释说明它是“从GitCapabilityCache中抽取出来”的通用基类目标是为仓库里所有主机能力缓存统一三种行为探测一次、只记住“确实缺失”的阳性信号、让并发调用等待正在进行的探测而不是重复发起。它的内部状态由三个容器构成retryAfterByCapability: MapTCapability, number——记录某能力被判定为不支持后的重试时间点probesByCapability: MapTCapability, PromiseOutcome——正在进行的探测 promise用于并发合并supportedCapabilities: SetTCapability——已被证明支持的能力集合。其公开 API 及语义如下与源码对应API行为shouldTry(capability)能力从未失败或已过重试期则返回true未到重试期返回false调用方直接走 fallbackisKnownSupported(capability)该能力是否已被证明支持rememberSupported(capability)主动记录支持清除失败时间并加入集合rememberUnsupported(capability)记录“不支持”从支持集合删除并把重试时间设为now retryIntervalMs见 git-capability-cache.ts 中的GIT_CAPABILITY_RETRY_INTERVAL_MS 30 * 60_000即 30 分钟runWithFallback(capability, runPreferred, runFallback, isUnsupportedError)探测并执行的首选入口clear()测试与重置用runWithFallback是整套机制的心脏值得逐行拆解其状态机capability-probe-cache.ts若能力已在supportedCapabilities中直接“乐观”地执行首选路径——注意注释强调“受支持的命令是真实工作而非一次性探测”所以要让同仓库/同 SSH 的并发调用保持原有并发度不再走探测锁若shouldTry返回false仍在 30 分钟冷却期直接执行 fallback避免每个 poll/search 都重复一次已知失败、白白消耗子进程与 trace 空间若已有 in-flight 探测则等待其 outcome再决定走首选还是 fallback——这就是“并发探测合并”否则由本调用充当探针把 promise 放入probesByCapability执行runPreferredOrFallback无论成功失败都会 settle 出supported | unsupported | unknown三种结果之一并在finally中清理探测槽位且有一个防挂起的兜底即便isUnsupportedError抛异常等待方也不会永久等待。在runPreferredOrFallback内部有一个精妙细节首选回调成功返回后并不会盲目标记为 supported而是检查该能力是否已被回调自己在执行过程中通过更弱的“阳性信号”例如旧 Git 对未知选项原样回显且 exit 0标记为 unsupported——如果有更强的否定信号就不覆盖它。只有真正确认支持时才写入supportedCapabilities。专门的并发探测合并实现见 coalesced-probe.ts 及其测试 coalesced-probe.test.ts用于验证“同一能力并发请求只发起一次真实探测”。三、当前能力矩阵文档用一张表完整列出了当前登记在案的能力及其首选/兼容行为这里完整继承并逐项结合源码展开Capability首选行为兼容行为fetch-no-write-fetch-headFetch 私有 rebase ref 时不改写 worktree 本地的FETCH_HEADGit 2.29 之前按 worktree Git 目录串行化 Orca 的所有 fetch/pull 操作worktree-list-zNUL 分隔的 worktree 路径并带prunable标记对worktree list -z2.36之前的 Git 使用行块解析器Git 2.31–2.35 上仍可解析prunable/locked注解2.31 之前的 Git 用路径存在性探测恢复prunable检测rev-parse-path-format返回绝对仓库元数据路径针对被扫描仓库解析旧版相对路径输出for-each-ref-exclude在输出上限之前先排除远端 HEAD多请求部分 refs再由 Orca 内部过滤远端 HEADmerge-tree-write-tree推导真实合并冲突与 no-op tree 证明Git 2.38 之前省略冲突摘要并保持保守的分支清理行为merge-tree-merge-base提供已解析的 merge base使用旧版两提交形式的merge-tree --write-tree所有这些能力标识构成一个受类型约束的联合定义在 git-capability-cache.ts 的GitCapability类型中编译期即可防止拼错能力名。逐项源码印证worktree-list-z/rev-parse-path-format在 worktree-list-reader.ts 中可以看到真实调用模式——通过withLocalGitCapabilityCacheForExecution拿到主机对应的缓存后以capabilities.runWithFallback(...)包裹首选与回退两种解析路径当首选路径失败且被窄谓词判定为“不支持”时还会显式调用capabilities.rememberUnsupported(rev-parse-path-format)见第 63、114 行并在第 203–207 行对worktree-list-z走同样的runWithFallback。对应地判别函数isUnsupportedWorktreeListZError位于 git-worktree-command-capabilities.ts。fetch-no-write-fetch-head在 remote-rebase.ts 中rebase 前的 fetch 通过withLocalGitCapabilityCacheForExecution包裹并探测fetch-no-write-fetch-head其第 58 行注释点出了该问题的根源并发 fetch 会在 fetch 与 rebase 之间改写FETCH_HEAD与 remote-tracking refs这正是首选行为要规避的竞态而兼容行为则牺牲并发换取正确性。merge-tree-write-tree/merge-tree-merge-base两个能力的窄谓词都在 git-merge-tree-capability.ts 中实现它们不是宽泛地匹配任何报错文本而是精确匹配 Git 的报错形态isUnsupportedMergeTreeWriteTreeError匹配unknown/invalid/unrecognized option ... --write-tree、unknown rev --write-tree以及旧版git merge-tree base-tree branch1 branch2的 usage 文本isUnsupportedMergeTreeMergeBaseError只匹配--merge-base选项不被识别的报错。for-each-ref-exclude判别函数isForEachRefExcludeUnsupportedError位于 git-ref-command-capabilities.ts它把错误文本小写化后要求同时包含unknown option与exclude才判定为不支持——这就是“窄谓词”的典型范例。窄谓词为何必须“窄”窄谓词直接决定能力状态机的正确性若谓词过宽会把真实的 Git 故障如网络错误、仓库损坏、权限问题误判为“该选项不受支持”从而悄悄把用户导向功能缩水的兼容路径掩盖真正的错误若过窄则探测会反复失败并不断触发 fallback。因此每个谓词都要精确模拟 Git 针对“该选项不存在”时的报错形态而这类形态恰恰无法用单个真实二进制在 CI 中确定性地构造这也是文档要求单元测试覆盖“error-stream shapes”的原因见下文 CI 契约。四、占位符“Fail Open”问题%(decorate:…)文档特别辟出一节讨论一类无法被缓存记录的失败模式。GitCapabilityCache记录的是 Git明确拒绝的命令但git log --format的占位符如果 Git 不认识并不会报错——Git 会把它原样回显并 exit 0因此“没有错误可记也没有可缓存的探测”。Placeholder首选行为兼容行为%(decorate:…)Git 2.43 起用\x1f分隔提交装饰信息含逗号的 ref 名因此可以存活同一条记录同时携带%DGit 2.10 可用解析时若发现%(decorate未被展开则退回%D代价是逗号会被拆开解决思路是文档明确给出的在一条记录里同时请求两种形式在解析阶段再做选择。也就是说输出的 log 记录同时携带%(decorate:...)与%D两个字段解析器看到%(decorate仍保持原样未被 Git 展开就说明二进制太老于是改用%D的语义。这是“探测 回退”哲学在“无法被拒绝、只能被静默透传”的场景下的变体把兼容性判断从执行时推迟到解析时。五、为什么不用simple-git文档单列一节解释不采用simple-git库的架构决策。simple-git本质是已安装 Git 二进制外的进程包装器其自定义选项与rawAPI 只是把参数透传给 Git因此它无法让一个新 flag 在一个旧二进制上生效它也无法自动替 Orca 选择语义等价的自定义回退。simple-git固然提供了版本报告与子进程队列但这些恰恰不是 Orca 的瓶颈。Orca 自身已经需要实现 WSL/SSH 路由、取消、追踪、敏感信息脱敏、进程清理与有界输出处理这些能力散见于 src/main/git 下的 runner、wsl-* 系列文件与 command-runner 子目录。若引入simple-git替换 runner能力问题只是从一个地方搬到另一个地方并没有被消除反而会引入一层无法接入 Orca 主机路由与能力缓存的间接层。六、CI 契约真实二进制矩阵 单元测试矩阵能力策略是否成立最终靠 CI 契约来兜底文档CI Contract一节。PR 检查会针对真实 Git 二进制运行能力契约覆盖三个版本点Git 2.25.5验证 2.29 之前串行化FETCH_HEAD的回退路径最老的受支持版本线Git 2.38.1验证--merge-base出现之前、过渡期的merge-tree --write-tree行为Git 2.49.1验证当前 Git 下的首选行为。这三个版本横跨了能力矩阵中的关键分水岭。更重要的是文档强调要让单元测试与该矩阵并行存在真实二进制无法确定性地构造某些场景因此单测必须覆盖并发探测合并见 coalesced-probe.test.tsnative / WSL / SSH / relay 的执行主机隔离见 git-capability-state.test.ts 与 git-capability-cache.test.ts后者还覆盖缓存重试、同主机多调用跳过重复探测等行为错误流形态error-stream shapes——即各类窄谓词对真实 Git 报错文本的匹配例如 git-merge-tree-capability.test.ts 会验证上面那些正则是否能命中、是否会误伤其他错误。仓库中另有 worktree-git-capabilities.test.ts将 worktree 场景与 Git 能力矩阵绑定做真实 Git 级别的验证与文档描述的“真实二进制矩阵 单测矩阵并行”完全吻合。七、给调用方与贡献者的工程要点把整篇策略收敛为几条可直接落地的工程要点新命令一律按“最老的支持版本”假设任何超出 Git 2.25 基线的特性都要走runWithFallback(capability, runPreferred, runFallback, isUnsupportedError)不要把版本判断写死在命令构造处一律通过能力缓存且每个能力都要有独立的窄谓词新能力三步接入在 git-capability-cache.ts 的GitCapability联合类型里登记名称 → 用主机级缓存包装调用点参考 worktree-list-reader.ts 的既有用法→ 为该能力补窄谓词放在 shared 下对应 capability 模块与单测区分“被拒绝”与“被静默透传”对git log --format这类会 exit 0 的占位符采用“同记录双形式 解析时选择”而非“探测 缓存”版本自愈依赖 30 分钟重试窗口rememberUnsupported写入的冷却期意味着用户原地升级 Git 后最多 30 分钟内 Orca 会自动重新探测到新能力无需重启。这条策略的完整原始定义始终以仓库中的 git-compatibility.md 为权威来源本文的所有源码引用均可在 src/shared 与 src/main/git 目录下复核。【免费下载链接】orcaOrca is the ADE for working with a fleet of parallel agents. Run any coding agent with your own subscription. Available on desktop, mobile and remote runtime.项目地址: https://gitcode.com/GitHub_Trending/orca48/orca创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考