智能体空间距离度量与碰撞规避（第 4 层）¶

状态：v0 已在 scripts/lib/agent-proximity/ 中实现。这是 ECC 2.0 的护城河 层——多个智能体（以及人类）在同一代码库上工作时的空间去冲突，借鉴飞机 防撞系统（TCAS）。

类比¶

共享空域的两架飞机不会等到相撞——TCAS 持续测量它们的间隔和闭合速率，先发出交通咨询（“附近有交通”），然后发出协调的决断咨询（“你爬升，另一架下降”）。我们希望智能体也如此：在代码空间中两个智能体有多近方面有一个连续概念，这样当它们接近时，我们触发一个信号，让它们向彼此传输自己正在做什么，并在必要时让其中一个转向避开——在它们在 git/merge 层发生碰撞之前。

1. 智能体状态¶

在时刻 t，智能体 a 有一个工作集

W_a = { (f, R_f, w_f) }                                              (1)

其中 f 是被触及的文件，R_f 是 f 中已编辑的行范围集合，w_f ∈ (0,1] 是新近度权重（较早的编辑会衰减到一个下限）。智能体还可以声明一个意图集 I_a，表示它即将触及的文件（前瞻）。

2. 碰撞是多通道的（noisy-OR）¶

两个智能体可能通过多个独立通道发生碰撞。每个通道 i 产生一个碰撞概率 r_i ∈ [0,1]；我们将它们组合为通过至少一个通道发生碰撞的概率：

R(a,b) = 1 − Π_i ( 1 − ω_i · r_i )                                   (2)

通道权重为 ω_i ∈ [0,1]。报告的距离是其对偶 D(a,b) = 1 − R(a,b)。

通道 1 — 编辑重叠 r_overlap¶

对于共享文件 S = files(W_a) ∩ files(W_b)：

lineOverlap(f) = |R_f^a ∩ R_f^b| / min(|R_f^a|, |R_f^b|)   (overlap coefficient)
r_overlap = max_{f∈S} w_f^a·w_f^b · lineOverlap(f)                        (3)

重叠系数（而非 Jaccard）是正确的度量：当一个智能体的小编辑位于另一个智能体的大区域内时，它保持较高值（Jaccard 会因并集大小而稀释它）。整文件编辑（无行信息）⇒ lineOverlap = 1。同一文件、重叠行 ⇒ 即将碰撞；同一文件、不相交的行范围（不同函数）⇒ 低 r_overlap。不同文件 ⇒ 没有共享的 f ⇒ r_overlap = 0。

通道 2 — 依赖耦合 r_dep¶

构建依赖图 G=(V,E)，当且仅当 f 导入 g 时存在边 f→g。即使两个文件位于遥远的子树中，如果一个智能体编辑了另一个智能体导入的文件，该编辑会破坏导入方。耦合随（不区分方向的）图距离 d_G 衰减：

coupling(f,g) = γ^{ d_G(f,g) − 1 }     γ ∈ (0,1), 0 if unreachable   (4)
r_dep = max_{f∈W_a, g∈W_b}  w_f · w_g · coupling(f,g)                (5)

直接导入（d_G = 1）⇒ coupling = 1。这是度量必须捕捉的“即使相距很远也会碰撞”项——一种跨文件的参数/返回值依赖，会在远处失效。

通道 3 — 树邻近度 r_tree（软先验）¶

对于最低公共祖先深度为 L 的两个路径：

treeDistance(f,g) = ((depth_f − L) + (depth_g − L)) / (depth_f + depth_g)  (6)
r_tree = 1 − min_{f∈W_a, g∈W_b} treeDistance(f,g)

（0 = 同一文件，1 = 不相交的根。）仅靠树邻近度很少导致碰撞，因此 ω_tree 很小——它只是推动度量，而不会主导度量。

未来通道（相同形状）¶

调用图距离（调用栈中相近的两个函数）、符号级读写危害（a 写入 b 读取的符号）以及测试覆盖率重叠，都可以作为额外的 r_i 并带有各自的权重嵌入——noisy-OR（2）可以吸收它们而不改变框架。

3. TCAS 协议¶

两个阈值在 R 周围划出一个保护区：

决断是协调且确定性的（类似一架飞机爬升而另一架下降），因此两个智能体永远不会选择相同的机动。优先权：

priority(a) = ( committed-work(a),  age(a) )      lexicographic

已提交工作更多者优先；平局按更早开始打破；最终平局按稳定的智能体 id 打破。低优先级智能体接收转向指令。

闭合速率。 TCAS 根据闭合速度升级，而不仅仅根据间隔。从相隔 Δt 的两个风险样本，closureRate = (R_t − R_{t−Δt}) / Δt；在 τ_TA 附近正的闭合速率可以在进入保护区之前预先升级。

4. 向量空间视图（可视化）¶

每个文件通过其路径的空间填充嵌入获得一个坐标（共享长目录前缀的文件共享大部分坐标），然后通过一次平均步骤向其依赖邻居拉近。智能体位于其文件坐标的按新近度加权的质心处。结果是：‖v_a − v_b‖ 跟踪碰撞风险 R，因此一个3D“智能体在哪里”视图将智能体渲染为文件云中的移动点——你可以直观地看到它们彼此爬近，看到咨询线亮起，并看到其中一个转向避开。

scanAirspace(agents, graph) 一次返回：非清除的 advisories（触发层所处理的内容）、3D positions 和 fileCoordinates（渲染器绘制的内容），以及带风险的成对 links（需要着色的边）。

5. 它如何接入 ECC¶

• 输入来自会话/工作状态：每个运行中会话的 worktree diff 给出其工作集 W_a；依赖图从仓库构建（buildDependencyGraph）。
• 触发器：控制窗口的 tick 调用 scanAirspace；交通咨询会在两个智能体会话之间注入一条“传输意图”消息；决断咨询会告诉低优先级智能体转向（重新指向另一个文件/子树）——这是即时多智能体（以及多人类）去冲突的首个具体实现。
• 看板：咨询会以邻近警告形式出现在看板上，扩展控制窗口中已有的智能体/人类 JIT 分配层。

路线图¶

• v0（已完成）：树 + 重叠 + 依赖通道，noisy-OR 风险，TCAS 建议， 优先级/转向，3D 嵌入，完整测试覆盖。
• v1：调用图与符号读写通道；意图前瞻；闭合率升级接入实时会话差异。
• v2：通过 Tailscale 的跨机器空域（队友代理进入同一空间）；录制的“N 个代理、M 个人类、零合并冲突”演示。