为什么 Beads 的远程检查会把远程仓库误报为“仅 SQL 仓库”？

在分布式架构的理想中，我们希望通过 bd 实现跨机器的任务同步。但现实往往比理想骨感：当你尝试在服务端开启 server-mode 并进行远程检查时，你会发现原本充满任务拓扑的图状仓库，突然在客户端眼里变成了一个“仅 SQL 仓库”（SQL-only repo）。所有的 bd 高级功能——任务依赖、图状展示、Agent 指令——瞬间全部失效，只剩下一堆冷冰冰的 SQL 表。

作为一个深挖过分布式系统一致性 Bug 的架构师，我得告诉你：这通常不是数据损坏，而是 Beads 在 Server-mode 下的路径解析逻辑出了偏差。它在跨越网络边界时，因为无法识别服务器端的物理仓库特征，而产生了一种“降级幻觉”。

💡 报错现象总结：用户在服务器模式下执行远程检查，系统虽然能连接，但无法识别 Beads 的特有元数据，将其误判为普通 SQL 数据库。本质原因是 Beads CLI 在处理远程路径时存在硬编码偏移（Issue #3534），导致其在服务端寻找 .beads 目录失败，系统为了“鲁棒性”自动退化到了基础 SQL 模式。

---

身份认同危机：为什么 Beads 会丢失它的“图状灵魂”？

为什么一个好端端的图状追踪器会退化成纯数据库？这涉及到 Beads 对仓库身份的识别机制。它必须在目标路径下找到 .beads 文件夹（包含元数据和 schema 定义），才能激活它的“任务追踪”皮肤。

远程检查失效的逻辑链路

阶段	正常本地逻辑	远程 Server-mode 逻辑	架构师深度剖析
路径获取	直接读取当前工作目录 (cwd)	尝试解析客户端传来的路径参数	Bug 点：服务端常误用客户端的绝对路径去查找文件
元数据校验	扫描本地 .beads/ 目录	扫描服务端对应的物理路径	如果路径不匹配，系统无法加载 Model 逻辑
降级机制	报错提示未初始化	静默退化为 SQL-only 模式	这是最坑的：不报错，但高级功能全消失
功能响应	返回完整任务图	仅返回基础 SQL 表名	Agent 会因为拿不到结构化任务而直接罢工

参考 Issue #3534，由于服务端对 CLI repository path 的动态解析存在缺陷，导致它在接收到远程请求时，由于环境上下文的差异，无法正确定位到存放 Dolt 数据的物理根目录。

---

源码排雷：修正远程仓库的“识别盲区”

如果我们深挖 server-mode 的底层通信代码，你会发现它在处理 LoadModel 请求时，缺乏对服务端物理环境的适配层。

// 模拟 Beads 服务端处理远程检查的逻辑 Bug
func (s *Server) HandleCheckRequest(remotePath string) {
    // 痛点：这里直接透传了客户端的 path
    // 如果客户端是 /Users/jack/project，服务端路径是 /home/ubuntu/project，
    // 这里必然会因为路径不存在而加载失败
    repo, err := dolt.Open(remotePath)
    
    // 逻辑缺陷：加载失败后没有报错，而是返回了一个“基础 SQL 对象”
    if err != nil {
        log.Warn("Could not load full beads model, falling back to SQL-only")
        return s.RespondAsSQL(repo) 
    }
}

要解决这个问题，服务端必须具备一种“路径映射”或“根目录自愈”的能力，确保无论客户端传什么路径，服务端都能基于自身的 BEADS_DIR 或执行路径找到真实的 .beads 文件夹。

---

痛苦的临时方案：为何“建立全路径软链接”不可取？

为了绕过这个 Bug，有些开发者尝试在服务器上模拟客户端的路径。比如客户端在 C:\Users\Admin\...，他们就在 Linux 服务器上也建一个 /C/Users/Admin/... 的目录并软链接过去。

这种做法极其业余：

1. 多用户冲突：当团队里有多个开发者，路径各异时，服务器目录会变成一团乱麻。
2. 跨平台死穴：Windows 的驱动器盘符逻辑在 Linux 服务端根本无法优雅模拟。
3. 运维噩梦：这种对物理路径的强耦合，让整个系统的迁移和扩容变得极其困难。

---

加入开发者协同计划，获取路径重定向补丁

与其在服务器上玩“路径拼图”，不如直接从代码层面实现路径的解耦。

我已经针对 server-mode 下远程检查路径误判的顽疾，整理了一套路径重定向补丁方案，并已同步至 GitCode 开发者协同计划中。这套方案引入了基于 UUID 的仓库识别机制，彻底摒弃了对物理绝对路径的依赖，确保你的 Agent 无论从哪里连接，都能秒速找回它的“图状灵魂”。

别让路径问题阻碍了你的分布式协作。 这种针对底层识别逻辑的修正，是实现大规模 Agent 集群协同的前提。你可以直接前往 GitCode 参与我们的协同计划，获取最新的路径补丁，让远程检查不再“迷失方向”。

[点击前往 GitCode 加入开发者协同计划]