jcode 跨设备 Worktree Sync 提案：多机多Agent协作的完整落地蓝图指南
【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode
jcode 是一款以内存占用极低著称的 AI Agent 终端工具（Rust 编写），它的 跨设备 Worktree Sync 提案 正在解决一个真实痛点：当你在 MacBook 和 Linux 笔记本上同时开发同一个项目时，两台机器如何像"一个工作区"一样协作——包括多机多Agent之间的冲突感知与版本一致性。
为什么需要跨设备 Worktree Sync
在单台机器上，jcode 已经做到了多 Agent 共享一个 worktree：服务器端统一中介文件编辑，并通过 file_activity.rs 追踪文件级别的冲突（比如"另一个 Agent 正在编辑第 40-60 行"这种警告）。
但一旦代码库分散在多台机器上，这套机制就断了：
- 🖥️ 在 Linux 笔记本上
selfdev build，MacBook 上的 jcode 完全无感知，反之亦然 - 📡 没有共享 worktree，一台机器上的改动，另一台机器的 Agent 和会话"看不见"，只能手动 push/pull
提案的目标很明确：让多台机器表现得像一个逻辑 worktree + 一个逻辑构建通道，与单机上多 Agent 共享 worktree 的体验对齐。
提案的地基：这些构件已经存在
这份提案不是空中楼阁，作者逐一在代码中验证了现有构件：
| 能力 | 所在位置 | 作用 |
|---|---|---|
| 跨架构一致的版本指纹 | source_state.rs | 对完整 commit、工作区状态和二进制 diff 做哈希，两台机器源码一致时指纹相同（尽管产物二进制不同） |
| 新二进制自动重载 | server/util.rs | 基于 mtime 的构建产物扫描，触发即自动 reload |
| 拉取→构建→安装→执行 | session_rebuild.rs | 接收端已有的完整流水线形态 |
| 跨设备网络门 | gateway.rs | WebSocket + 纯 HTTP（默认端口 7643），远程客户端与本地 Unix socket 客户端说同一套协议 |
| 可穿透 NAT 的事件总线 | jade_relay.rs | 设备 ID、心跳、长轮询命令事件，机器互不可达时也能工作 |
| 远程构建先例 | remote_build.sh | 已验证过的 rsync + ssh 同步模式 |
有一个已知缺口：现有repo_scope_key哈希的是本地路径（如/Users/jeremy/...vs/home/jeremy/...），跨机器永远不匹配。提案给出的解法是用可移植的仓库身份——归一化的 origin URL，或配置里显式声明[sync] repo_id = "jcode"。
核心机制：不动 HEAD 就能"打包"一个脏工作区
跨设备同步最难的是：如何原子地捕获一个可能有大量未提交改动（甚至含未跟踪文件）的 worktree，同时不干扰用户正在进行的开发？
提案采用纯 git plumbing 方案：把暂存区临时指向一个临时索引，git add -A后write-tree生成内容寻址的树对象，再挂一个临时 sync ref（refs/jcode/sync/<device>）推到共享远端。接收端拉取后应用，并用指纹校验保证字节级一致。发送方的 HEAD、索引和工作区纹丝不动。
三阶段落地路径：先止痛，再进化
阶段 B：构建对等（优先做，直接消灭痛点）
一台机器构建成功后，向对端广播一条版本信标（version beacon）：包含仓库 ID、版本标签、指纹、同步 ref 和设备信息。广播走三级通道——直连 HTTP 快速路径 → NAT 中继兜底 → 轮询 git 远端慢路径。
接收端默认采取保守策略：
- ✅ 本地工作区干净、且本地 HEAD 是信标提交的祖先 → 自动拉取、重建、发布，随后既有的自动重载机制接管
- ⛔ 否则绝不覆盖，只在 TUI 里提示
peer build available: <label> from <device> (blocked: local changes)，一键确认
还有关键的回声抑制：如果两台机器已经跑着相同版本，信标直接忽略，避免"你重建、我重建"的死循环。
阶段 A：Hub Attach（双方在线时的权威工作区）
提供jcode attach <host>命令：TUI 通过已有的网关 WebSocket 直接挂到另一台机器的服务器上。由于工具在服务器端执行，远程客户端天然参与那台机器的 worktree 和冲突追踪——相当于把单机多 Agent 体验跨机器复现。
阶段 C：真正的 Worktree 联邦（长期愿景）
把 B 的快照机制 + A 的对等连接泛化为持续双向同步：限流的自动快照、离线分叉时标记仓库为 "split" 并自动生成一个 Agent 来执行合并（正是单机冲突管理的跨设备类比），以及跨设备共享FileTouchService事件——让两台机器上的 Agent 都能收到"另一台机器的 Agent 正在编辑 40-60 行"的警告。
被否决的替代方案：为什么不直接用 Syncthing？
提案认真评估了三条备选路：
- Syncthing/mutagen 字节级同步：冲突文件（
.sync-conflict）语义糟糕、无多文件原子性 - 单机构建 + 拷贝二进制：darwin 与 linux 架构不匹配，交叉编译成本不划算
- NFS/SSHFS 共享 worktree：离线惩罚大，文件监视器性能差，笔记本直接劝退
最终选择 git 语义的原因很朴素：原子、内容寻址、可合并，且用户已经懂这套规则。
总结
这份 CROSS_DEVICE_WORKTREE_SYNC.md 是一份典型的"设计先行"提案（状态：Proposed，尚未实现）。它的价值在于：把"多机开发像单机一样顺"这个模糊愿望，拆成了版本指纹、sync ref、版本信标、attach 对等、冲突联邦五个可独立落地的原语，并优先实现收益最大的阶段 B。
如果你对 AI Agent 协作、多机开发工作流或 jcode 的架构设计感兴趣，这份提案值得通读——它也清晰地展示了：跨设备多机多Agent协作，可能不需要发明新协议，只需要把已有的构件接起来。
【免费下载链接】jcodeThe most RAM efficient harness项目地址: https://gitcode.com/GitHub_Trending/jcod/jcode
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
