Beadsbd context命令完全指南查询后端身份与仓库上下文的诊断利器【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读bd context是 Beads 仓库中一个面向运维诊断的只读命令用于展示“有效后端身份信息”——包括仓库路径、后端配置与同步设置。它最大的特点是直接读取配置文件、不依赖数据库打开因此在数据库损坏、迁移中断、配置漂移等“降级状态”degraded states下仍然可以给出答案是排查 Beads 工作区环境问题的第一入口。读完本文你将掌握bd context的文本/JSON 两种输出格式、每个字段的含义与来源、direct 与 proxied 双路由的底层实现、以及后端身份策略SetBackendIdentity如何防止“非 Dolt 工作区被谎报为嵌入式 Dolt”这类身份失真问题。一、命令概览做什么、什么时候用依据官方命令文档 docs/cli-reference/context.md该文档由bd help --doc context自动生成Show the effective backend identity information including repository paths, backend configuration, and sync settings. This command reads directly from config files and does not require the database to be open, making it useful for diagnostics in degraded states.即bd context展示**生效后effective**的后端身份信息覆盖三类内容仓库路径.beads目录、仓库根、当前工作目录所属仓库等后端配置存储后端类型、Dolt 模式、数据库名、服务器地址等同步设置同步远端sync remote。它被设计为只读命令注册方式见 cmd/bd/context_cmd.gofunc init() { rootCmd.AddCommand(contextCmd) readOnlyCommands[context] true }readOnlyCommands集合中的命令保证不写入任何状态可放心在只读/诊断场景下反复调用。典型适用场景数据库打不开时排查环境命令直接读配置文件无需打开数据库检查当前工作区到底绑定哪个后端区分嵌入式 Dolt、独立 Dolt server、proxied-server 还是注册的第三方后端检查仓库重定向redirect与 worktree 状态确认.beads是否落在与 CWD 不同的仓库检查同步远端是否配置正确确认sync.remote的生效值脚本化采集环境快照--json输出便于被 Agent、CI 或监控脚本消费。二、基本用法与两种输出格式bd context [flags]官方文档给出的两个示例bd context # Show context information bd context --json # Output in JSON formatcontext命令归属于setup命令组GroupID: setup完整命令定义见 cmd/bd/context_cmd.go。文本输出默认文本格式由printContextText渲染cmd/bd/context_cmd.go结构大致如下bd version: 1.2.3 Repository: beads dir: /path/to/repo/.beads repo root: /path/to/repo cwd repo: /path/to/other (仅当与 repo root 不同才显示) redirected: yes worktree: yes role: maintainer Backend: type: dolt mode: embedded database: beads server: 127.0.0.1:3307 proxied dir: /path/to/proxied/root data dir: custom-data project id: proj-abc123 Sync: remote: https://host/repo.git各节要点Repository 节beads dir是解析重定向后的实际.beads路径cwd repo仅在 CWD 所属仓库与 beads 仓库不同时打印context_cmd.goredirected、worktree、role均为条件打印Backend 节mode、database属于 Dolt 专属身份——注册的第三方后端两者都为空串此时一律省略不打印避免“mode 后面空无一物”被误读为“判定失败”而不是“不适用”context_cmd.goserver以host:port形式打印Sync 节仅当配置了同步远端时才出现。JSON 输出--json模式下ContextInfo结构体cmd/bd/context_cmd.go按如下 JSON 键序列化JSON 字段类型含义是否总是出现beads_dirstring实际的.beads目录路径是repo_rootstring存放.beads的仓库根是cwd_repo_rootstring当前工作目录所属仓库根否omitemptyis_redirectedbool是否发生仓库重定向是is_worktreeboolCWD 是否处于 git worktree是backendstring存储后端名dolt或注册后端名是dolt_modestringembedded/server/proxied-server否server_host/server_portstring / intDolt server 绑定地址否proxied_dirstringproxied-server 的根目录否databasestringDolt SQL 数据库名否data_dirstring自定义 dolt 数据目录否project_idstring项目标识UUID v4否sync_remotestring生效的同步远端 URL否sync_git_remotestring已废弃字段兼容别名否rolestringmaintainer/contributor否bd_versionstringBeads 版本号是错误路径同样尊重--json当无法解析仓库上下文时JSON 模式输出{error: cannot resolve repo context: ...}文本模式则返回HandleError提示context_cmd.go。三、双路由设计一条命令两个来源同一答案bd context是少数同时存在两条执行路径的命令理解这一点对正确使用至关重要。路径一direct 模式默认在 context_cmd.go 中非 proxied 环境下命令自行读取配置文件完成快照组装完全不经过存储层。源码注释明确说明了设计动机The direct route reads config files itself rather than through the contextinfo provider — it must answer in degraded states where no database can be opened.其组装流程为selectedNoDBBeadsDir(cmd)解析目标.beads目录支持--db标志、BEADS_DB/BD_DB/BEADS_DIR环境变量见 cmd/bd/main.go使得无需打开数据库也能针对指定工作区回答问题beads.GetRepoContext()解析仓库路径内部有sync.Once缓存rc.Role()读取角色角色未配置且发生重定向时隐式判定为contributorconfigfile.LoadForDiscovery(rc.BeadsDir)加载配置失败时回退到configfile.DefaultConfig()applyContextBackend填充后端身份与 Dolt 专属字段resolveSyncRemoteFromDir(rc.BeadsDir)解析同步远端统一交给contextInfoView生成视图再按--json分流输出。路径二proxied 模式当命令运行在 proxied server 环境中usesProxiedServer()为真走 cmd/bd/context_proxied_server.go通过contextinfo.NewContextProvider(cwd, Version).ContextUseCase().GetContextInfo(ctx)从存储层用例获取快照provider 组装见 internal/storage/contextinfo/provider.go随后同样调用contextInfoView渲染。为什么两条路径必须给出同一答案两条路径的快照来源不同一个读配置一个走 use case但都汇聚到同一个视图函数contextInfoView并由domain.SetBackendIdentity这一共享策略约束身份字段。源码注释指出what keepsbd contextone answer across two routes ... TestContextRoutesNameOneWorkspaceTheSameWay holds them to it; until it existed both routes carried their ownBackend: doltand agreed by telling the same lie.此前两条路径各自硬编码Backend: dolt非 Dolt 工作区被双双误报统一策略之后这一致性由测试TestContextRoutesNameOneWorkspaceTheSameWay持续守护。contextInfoViewcontext_proxied_server.go内部先用domain.PublishedContext投影出所有“对外发布”字段与 HTTP 端点GET /v0/beads/context完全同源再把重定向标志、worktree 标志、绝对主机路径、绑定端点、角色与同步远端等本地诊断字段叠加在快照之上——这些字段是给工作区属主终端看的不会进入共享投影。四、后端身份策略SetBackendIdentity与 Dolt 专属字段后端身份是bd context输出的核心其赋值逻辑集中在 internal/storage/domain/context.gofunc (info *ContextInfo) SetBackendIdentity(backend, doltMode, database string) { info.Backend backend info.DoltMode, info.Database , if backend configfile.BackendDolt { info.DoltMode, info.Database doltMode, database } }这一“门控”是承重的而非防御性的因为 Dolt 的两个字段默认值而非失败值——configfile将缺失的dolt_mode读作embedded、缺失的dolt_database读作beads见 internal/configfile/configfile.go 的常量定义。因此一个未配置这两项的注册后端工作区曾经会在bd context、bd context --json乃至GET /v0/beads/context上被自信地描述为“databasebeads上的嵌入式 Dolt”——这正是注释中点名要修复的“同样的谎言”。策略结果Dolt 后端如实报告dolt_mode与database注册的第三方后端两者一律输出空串且bd无法也不去猜测其逻辑数据库名——任何非空猜测都会重演更小声的谎言服务器绑定端点与 proxied 根目录在更下一层已经被IsDoltServerMode/IsDoltProxiedServerMode门控非 Dolt 后端天然不会发布。该策略同时被两条 CLI 路由与 HTTP 投影共享杜绝了三者对同一工作区命名不一致。五、输出字段的配置来源与优先级bd context展示的是“生效值”即环境变量、metadata.json、全局config.yaml叠加之后的最终结果。核心配置加载器在 internal/configfile/configfile.go其中工作区配置文件名为metadata.json位于.beads/目录下configfile.go后端常量BackendDolt doltDolt 模式常量embedded/server/proxied-serverconfigfile.go默认值主机127.0.0.1、端口3307刻意避开 MySQL 默认 3306、数据库beadsconfigfile.go。各字段的优先级规则均有对应 Getter 实现输出字段生效值解析优先级dolt_mode显式配置 → 未配置时若主机推断选中 server 模式则报server否则embeddedGetDoltMode见 configfile.goserver_hostBEADS_DOLT_SERVER_HOST环境变量 →metadata.json的dolt_server_host→ 全局/用户级config.yaml的dolt.host→ 默认127.0.0.1configfile.goserver_portBEADS_DOLT_SERVER_PORT→BEADS_DOLT_PORTorchestrator 注入→ 配置 → 默认3307configfile.godatabaseBEADS_DOLT_SERVER_DATABASE环境变量 → 配置 → 默认beadsconfigfile.godata_dirBEADS_DOLT_DATA_DIR环境变量 → 配置dolt_data_dirconfigfile.go其中data_dir的典型使用场景是 WSL项目位于慢速 NTFS9P 协议挂载上而 Dolt 数据可放到原生 ext4 以获得明显更好的 I/Oconfigfile.go。环境变量覆盖是一个真实的漂移向量测试 cmd/bd/context_cmd_test.go 的TestContextInfo_EnvVarOverrides验证了这一点metadata.json中写入dolt_server_host: 192.168.1.50设置环境变量BEADS_DOLT_SERVER_HOST10.0.0.99后GetDoltServerHost()返回10.0.0.99而结构体原始字段仍为192.168.1.50。这正是bd context要展示“生效值”的原因——配置文件与实际运行环境可能静默分叉对应 GH#2438 漂移场景。同文件还有TestContextInfo_ServerModeIdentity、TestContextInfo_EmbeddedModeIdentity、TestContextInfo_DataDirOverride、TestContextInfo_ProjectIDPresent等用例分别覆盖各身份字段的往返与优先级。其他值得注意的配置守卫Save()会剥离绝对路径的dolt_data_dirGH#2251防止绝对路径扩散到其他克隆导致数据丢失见TestContextInfo_SaveStripAbsoluteDataDircontext_cmd_test.goproject_id由GenerateProjectID()生成 UUID v4configfile.go用于项目身份校验GH#2372。六、仓库上下文解析路径、重定向与 worktreebd context的仓库路径信息来自beads.GetRepoContext()实现在 internal/beads/context.go。该包的背景注释点明了它解决的问题Problem: 50 git commands across the codebase assume CWD is the repository root. When BEADS_DIR points to a different repo, or when running from a worktree, these commands execute in the wrong directory.RepoContext严格区分两类路径RepoRoot.beads/所在仓库根Beads 数据的所有 git 操作都应在该目录执行CWDRepoRoot用户当前工作目录所属仓库根用于状态展示等场景。两者在BEADS_DIR指向别的仓库、或从 git worktree 运行时可能不一致IsRedirected与IsWorktree标志即用于标记这些情形。解析流程buildRepoContextFindBeadsDir()查找.beads目录尊重BEADS_DIR环境变量安全边界校验SEC-003isPathInSafeBoundary拒绝/etc、/usr、/var、/root、/System、/Library、/bin、/sbin、/opt、/private等系统目录并拒绝其他用户的主目录同时为os.TempDir()、/var/homeFedora Silverblue 系、/var/tmp、/Users/SharedmacOS 共享目录提供带符号链接解析的放行通道context.go检查重定向文件GetRedirectInfo()重定向或外部.beads目录时以该目录所在仓库根为 RepoRoot通过git.GetRepoRoot()获取 CWD 仓库根、git.IsWorktree()判断 worktree。角色的两种判定来源RepoContext.Role()context.go优先读取git config --get beads.role而一旦IsRedirected即BEADS_DIR生效则隐式判定为contributor——外部仓库模式总是对应贡献者工作流。因此bd context输出的role字段可能是显式配置也可能是重定向的隐式推断。git 操作的安全姿势GitCmd方法将 git 命令固定运行在 RepoRoot并显式设置GIT_TEMPLATE_DIR、GIT_DIR、GIT_WORK_TREE以兼容 worktree 场景GH#2538同时通过-c core.hooksPath与空模板目录禁用钩子与模板防止恶意仓库中的代码执行SEC-001/SEC-002context.go。详细设计另见 engdocs/REPO_CONTEXT.md。七、同步远端解析同步远端由 cmd/bd/sync_remote.go 的resolveSyncRemoteFromDir解析针对指定.beads目录的配置读取sync.remote首选任何 Dolt 兼容远端 URLsync.git-remote已废弃的兼容回退空串未配置。该函数被context_cmd、doctor等按已解析 beads 目录工作的路径复用。--json输出中的sync_git_remote字段即为废弃别名context_cmd.go新脚本应只消费sync_remote。八、与 HTTP 端点GET /v0/beads/context的一致性bd context并非孤立命令——它与 HTTP API 端点共享同一身份投影。在 internal/storage/domain/context.go 中PublishedContextFields是“每个上下文表面都必须回答的工作区身份”bd context文本输出、bd context --json以及GET /v0/beads/context三者的发布字段都经过PublishedContext投影因此不会对同一工作区命名出不同结果。刻意缺席的字段缺席即设计PublishedContextFields注释强调“缺席正是重点”且是结构性而非靠记忆维持的SyncRemote缺席远端 URL 常内嵌凭据如https://x-access-token:TOKENhost/...任何经由该类型发布身份的 surface 都无法“忘记排除”它数据库绑定端点缺席ServerHost/ServerPort不进入共享投影——对外广告端点会诱导客户端绕过 API 直连一个信任模型为“root 空密码 loopback”的服务器绝对主机路径缺席CWDRepoRoot、ProxiedDir、DataDir对消费者无标识意义。这些本地诊断信息只由 CLI 在属主自己的终端上打印。该策略由测试 internal/httpapi/context_test.go 的TestContextHandlerServesOnlyTheAllowlist强制执行断言响应体不得携带白名单之外的字段、不得包含 sync remote URL、不得包含伪造令牌与 Dolt 绑定端点如3307。九、降级状态下的诊断价值回到bd context最核心的定位——降级状态诊断。当数据库无法打开例如损坏、迁移未完成、schema 分叉时多数命令会失败但bd context仍能通过以下机制给出可靠答案直接读配置而非打开数据库direct 路由selectedNoDBBeadsDir允许通过--db标志或BEADS_DIR等环境变量指向任意工作区即便当前目录不是该工作区cmd/bd/main.go配置加载失败时回退到configfile.DefaultConfig()保证在.beads目录残缺时也能返回部分信息而不是直接崩溃context_cmd.go。典型排障路径# 数据库打不开时先确认工作区绑定的后端与环境 bd context bd context --json # 指定一个具体的 .beads 目录做诊断无需 cd 过去 bd context --db /path/to/workspace/.beadsbd context也因此与bd doctor等诊断工具共用同一套按目录解析的同步远端与仓库上下文基础设施sync_remote.go是全仓库诊断体系的第一块拼图。十、从源码到实践的快速索引关注点参考文件命令定义与 direct 路由cmd/bd/context_cmd.goproxied 路由与视图投影cmd/bd/context_proxied_server.go身份发布策略白名单投影internal/storage/domain/context.go仓库路径解析与安全边界internal/beads/context.go配置加载与默认值internal/configfile/configfile.go同步远端解析cmd/bd/sync_remote.goHTTP 端点白名单测试internal/httpapi/context_test.go配置优先级与漂移测试cmd/bd/context_cmd_test.go仓库上下文设计文档engdocs/REPO_CONTEXT.md命令官方文档docs/cli-reference/context.md结语bd context虽然是一条输出“环境信息”的命令但它的实现浓缩了 Beads 在多后端、多模式、重定向与 worktree 场景下身份解析的全部关键决策直接读配置以保障降级可用性、双路由共享同一视图以保证一致性、SetBackendIdentity门控 Dolt 专属字段以防止身份谎言、PublishedContext白名单投影以隔离可能携带凭据或诱导直连的敏感字段。无论是人工排障、脚本采集还是 Agent 自动化环境探测bd context都是理解“当前 Beads 工作区到底处于什么状态”的最快入口——记住它的 JSON 输出与不打开数据库这一特性就能在绝大多数疑难场景中先于问题一步定位环境。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Beads `bd context` 命令完全指南：查询后端身份与仓库上下文的诊断利器
Beadsbd context命令完全指南查询后端身份与仓库上下文的诊断利器【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads导读bd context是 Beads 仓库中一个面向运维诊断的只读命令用于展示“有效后端身份信息”——包括仓库路径、后端配置与同步设置。它最大的特点是直接读取配置文件、不依赖数据库打开因此在数据库损坏、迁移中断、配置漂移等“降级状态”degraded states下仍然可以给出答案是排查 Beads 工作区环境问题的第一入口。读完本文你将掌握bd context的文本/JSON 两种输出格式、每个字段的含义与来源、direct 与 proxied 双路由的底层实现、以及后端身份策略SetBackendIdentity如何防止“非 Dolt 工作区被谎报为嵌入式 Dolt”这类身份失真问题。一、命令概览做什么、什么时候用依据官方命令文档 docs/cli-reference/context.md该文档由bd help --doc context自动生成Show the effective backend identity information including repository paths, backend configuration, and sync settings. This command reads directly from config files and does not require the database to be open, making it useful for diagnostics in degraded states.即bd context展示**生效后effective**的后端身份信息覆盖三类内容仓库路径.beads目录、仓库根、当前工作目录所属仓库等后端配置存储后端类型、Dolt 模式、数据库名、服务器地址等同步设置同步远端sync remote。它被设计为只读命令注册方式见 cmd/bd/context_cmd.gofunc init() { rootCmd.AddCommand(contextCmd) readOnlyCommands[context] true }readOnlyCommands集合中的命令保证不写入任何状态可放心在只读/诊断场景下反复调用。典型适用场景数据库打不开时排查环境命令直接读配置文件无需打开数据库检查当前工作区到底绑定哪个后端区分嵌入式 Dolt、独立 Dolt server、proxied-server 还是注册的第三方后端检查仓库重定向redirect与 worktree 状态确认.beads是否落在与 CWD 不同的仓库检查同步远端是否配置正确确认sync.remote的生效值脚本化采集环境快照--json输出便于被 Agent、CI 或监控脚本消费。二、基本用法与两种输出格式bd context [flags]官方文档给出的两个示例bd context # Show context information bd context --json # Output in JSON formatcontext命令归属于setup命令组GroupID: setup完整命令定义见 cmd/bd/context_cmd.go。文本输出默认文本格式由printContextText渲染cmd/bd/context_cmd.go结构大致如下bd version: 1.2.3 Repository: beads dir: /path/to/repo/.beads repo root: /path/to/repo cwd repo: /path/to/other (仅当与 repo root 不同才显示) redirected: yes worktree: yes role: maintainer Backend: type: dolt mode: embedded database: beads server: 127.0.0.1:3307 proxied dir: /path/to/proxied/root data dir: custom-data project id: proj-abc123 Sync: remote: https://host/repo.git各节要点Repository 节beads dir是解析重定向后的实际.beads路径cwd repo仅在 CWD 所属仓库与 beads 仓库不同时打印context_cmd.goredirected、worktree、role均为条件打印Backend 节mode、database属于 Dolt 专属身份——注册的第三方后端两者都为空串此时一律省略不打印避免“mode 后面空无一物”被误读为“判定失败”而不是“不适用”context_cmd.goserver以host:port形式打印Sync 节仅当配置了同步远端时才出现。JSON 输出--json模式下ContextInfo结构体cmd/bd/context_cmd.go按如下 JSON 键序列化JSON 字段类型含义是否总是出现beads_dirstring实际的.beads目录路径是repo_rootstring存放.beads的仓库根是cwd_repo_rootstring当前工作目录所属仓库根否omitemptyis_redirectedbool是否发生仓库重定向是is_worktreeboolCWD 是否处于 git worktree是backendstring存储后端名dolt或注册后端名是dolt_modestringembedded/server/proxied-server否server_host/server_portstring / intDolt server 绑定地址否proxied_dirstringproxied-server 的根目录否databasestringDolt SQL 数据库名否data_dirstring自定义 dolt 数据目录否project_idstring项目标识UUID v4否sync_remotestring生效的同步远端 URL否sync_git_remotestring已废弃字段兼容别名否rolestringmaintainer/contributor否bd_versionstringBeads 版本号是错误路径同样尊重--json当无法解析仓库上下文时JSON 模式输出{error: cannot resolve repo context: ...}文本模式则返回HandleError提示context_cmd.go。三、双路由设计一条命令两个来源同一答案bd context是少数同时存在两条执行路径的命令理解这一点对正确使用至关重要。路径一direct 模式默认在 context_cmd.go 中非 proxied 环境下命令自行读取配置文件完成快照组装完全不经过存储层。源码注释明确说明了设计动机The direct route reads config files itself rather than through the contextinfo provider — it must answer in degraded states where no database can be opened.其组装流程为selectedNoDBBeadsDir(cmd)解析目标.beads目录支持--db标志、BEADS_DB/BD_DB/BEADS_DIR环境变量见 cmd/bd/main.go使得无需打开数据库也能针对指定工作区回答问题beads.GetRepoContext()解析仓库路径内部有sync.Once缓存rc.Role()读取角色角色未配置且发生重定向时隐式判定为contributorconfigfile.LoadForDiscovery(rc.BeadsDir)加载配置失败时回退到configfile.DefaultConfig()applyContextBackend填充后端身份与 Dolt 专属字段resolveSyncRemoteFromDir(rc.BeadsDir)解析同步远端统一交给contextInfoView生成视图再按--json分流输出。路径二proxied 模式当命令运行在 proxied server 环境中usesProxiedServer()为真走 cmd/bd/context_proxied_server.go通过contextinfo.NewContextProvider(cwd, Version).ContextUseCase().GetContextInfo(ctx)从存储层用例获取快照provider 组装见 internal/storage/contextinfo/provider.go随后同样调用contextInfoView渲染。为什么两条路径必须给出同一答案两条路径的快照来源不同一个读配置一个走 use case但都汇聚到同一个视图函数contextInfoView并由domain.SetBackendIdentity这一共享策略约束身份字段。源码注释指出what keepsbd contextone answer across two routes ... TestContextRoutesNameOneWorkspaceTheSameWay holds them to it; until it existed both routes carried their ownBackend: doltand agreed by telling the same lie.此前两条路径各自硬编码Backend: dolt非 Dolt 工作区被双双误报统一策略之后这一致性由测试TestContextRoutesNameOneWorkspaceTheSameWay持续守护。contextInfoViewcontext_proxied_server.go内部先用domain.PublishedContext投影出所有“对外发布”字段与 HTTP 端点GET /v0/beads/context完全同源再把重定向标志、worktree 标志、绝对主机路径、绑定端点、角色与同步远端等本地诊断字段叠加在快照之上——这些字段是给工作区属主终端看的不会进入共享投影。四、后端身份策略SetBackendIdentity与 Dolt 专属字段后端身份是bd context输出的核心其赋值逻辑集中在 internal/storage/domain/context.gofunc (info *ContextInfo) SetBackendIdentity(backend, doltMode, database string) { info.Backend backend info.DoltMode, info.Database , if backend configfile.BackendDolt { info.DoltMode, info.Database doltMode, database } }这一“门控”是承重的而非防御性的因为 Dolt 的两个字段默认值而非失败值——configfile将缺失的dolt_mode读作embedded、缺失的dolt_database读作beads见 internal/configfile/configfile.go 的常量定义。因此一个未配置这两项的注册后端工作区曾经会在bd context、bd context --json乃至GET /v0/beads/context上被自信地描述为“databasebeads上的嵌入式 Dolt”——这正是注释中点名要修复的“同样的谎言”。策略结果Dolt 后端如实报告dolt_mode与database注册的第三方后端两者一律输出空串且bd无法也不去猜测其逻辑数据库名——任何非空猜测都会重演更小声的谎言服务器绑定端点与 proxied 根目录在更下一层已经被IsDoltServerMode/IsDoltProxiedServerMode门控非 Dolt 后端天然不会发布。该策略同时被两条 CLI 路由与 HTTP 投影共享杜绝了三者对同一工作区命名不一致。五、输出字段的配置来源与优先级bd context展示的是“生效值”即环境变量、metadata.json、全局config.yaml叠加之后的最终结果。核心配置加载器在 internal/configfile/configfile.go其中工作区配置文件名为metadata.json位于.beads/目录下configfile.go后端常量BackendDolt doltDolt 模式常量embedded/server/proxied-serverconfigfile.go默认值主机127.0.0.1、端口3307刻意避开 MySQL 默认 3306、数据库beadsconfigfile.go。各字段的优先级规则均有对应 Getter 实现输出字段生效值解析优先级dolt_mode显式配置 → 未配置时若主机推断选中 server 模式则报server否则embeddedGetDoltMode见 configfile.goserver_hostBEADS_DOLT_SERVER_HOST环境变量 →metadata.json的dolt_server_host→ 全局/用户级config.yaml的dolt.host→ 默认127.0.0.1configfile.goserver_portBEADS_DOLT_SERVER_PORT→BEADS_DOLT_PORTorchestrator 注入→ 配置 → 默认3307configfile.godatabaseBEADS_DOLT_SERVER_DATABASE环境变量 → 配置 → 默认beadsconfigfile.godata_dirBEADS_DOLT_DATA_DIR环境变量 → 配置dolt_data_dirconfigfile.go其中data_dir的典型使用场景是 WSL项目位于慢速 NTFS9P 协议挂载上而 Dolt 数据可放到原生 ext4 以获得明显更好的 I/Oconfigfile.go。环境变量覆盖是一个真实的漂移向量测试 cmd/bd/context_cmd_test.go 的TestContextInfo_EnvVarOverrides验证了这一点metadata.json中写入dolt_server_host: 192.168.1.50设置环境变量BEADS_DOLT_SERVER_HOST10.0.0.99后GetDoltServerHost()返回10.0.0.99而结构体原始字段仍为192.168.1.50。这正是bd context要展示“生效值”的原因——配置文件与实际运行环境可能静默分叉对应 GH#2438 漂移场景。同文件还有TestContextInfo_ServerModeIdentity、TestContextInfo_EmbeddedModeIdentity、TestContextInfo_DataDirOverride、TestContextInfo_ProjectIDPresent等用例分别覆盖各身份字段的往返与优先级。其他值得注意的配置守卫Save()会剥离绝对路径的dolt_data_dirGH#2251防止绝对路径扩散到其他克隆导致数据丢失见TestContextInfo_SaveStripAbsoluteDataDircontext_cmd_test.goproject_id由GenerateProjectID()生成 UUID v4configfile.go用于项目身份校验GH#2372。六、仓库上下文解析路径、重定向与 worktreebd context的仓库路径信息来自beads.GetRepoContext()实现在 internal/beads/context.go。该包的背景注释点明了它解决的问题Problem: 50 git commands across the codebase assume CWD is the repository root. When BEADS_DIR points to a different repo, or when running from a worktree, these commands execute in the wrong directory.RepoContext严格区分两类路径RepoRoot.beads/所在仓库根Beads 数据的所有 git 操作都应在该目录执行CWDRepoRoot用户当前工作目录所属仓库根用于状态展示等场景。两者在BEADS_DIR指向别的仓库、或从 git worktree 运行时可能不一致IsRedirected与IsWorktree标志即用于标记这些情形。解析流程buildRepoContextFindBeadsDir()查找.beads目录尊重BEADS_DIR环境变量安全边界校验SEC-003isPathInSafeBoundary拒绝/etc、/usr、/var、/root、/System、/Library、/bin、/sbin、/opt、/private等系统目录并拒绝其他用户的主目录同时为os.TempDir()、/var/homeFedora Silverblue 系、/var/tmp、/Users/SharedmacOS 共享目录提供带符号链接解析的放行通道context.go检查重定向文件GetRedirectInfo()重定向或外部.beads目录时以该目录所在仓库根为 RepoRoot通过git.GetRepoRoot()获取 CWD 仓库根、git.IsWorktree()判断 worktree。角色的两种判定来源RepoContext.Role()context.go优先读取git config --get beads.role而一旦IsRedirected即BEADS_DIR生效则隐式判定为contributor——外部仓库模式总是对应贡献者工作流。因此bd context输出的role字段可能是显式配置也可能是重定向的隐式推断。git 操作的安全姿势GitCmd方法将 git 命令固定运行在 RepoRoot并显式设置GIT_TEMPLATE_DIR、GIT_DIR、GIT_WORK_TREE以兼容 worktree 场景GH#2538同时通过-c core.hooksPath与空模板目录禁用钩子与模板防止恶意仓库中的代码执行SEC-001/SEC-002context.go。详细设计另见 engdocs/REPO_CONTEXT.md。七、同步远端解析同步远端由 cmd/bd/sync_remote.go 的resolveSyncRemoteFromDir解析针对指定.beads目录的配置读取sync.remote首选任何 Dolt 兼容远端 URLsync.git-remote已废弃的兼容回退空串未配置。该函数被context_cmd、doctor等按已解析 beads 目录工作的路径复用。--json输出中的sync_git_remote字段即为废弃别名context_cmd.go新脚本应只消费sync_remote。八、与 HTTP 端点GET /v0/beads/context的一致性bd context并非孤立命令——它与 HTTP API 端点共享同一身份投影。在 internal/storage/domain/context.go 中PublishedContextFields是“每个上下文表面都必须回答的工作区身份”bd context文本输出、bd context --json以及GET /v0/beads/context三者的发布字段都经过PublishedContext投影因此不会对同一工作区命名出不同结果。刻意缺席的字段缺席即设计PublishedContextFields注释强调“缺席正是重点”且是结构性而非靠记忆维持的SyncRemote缺席远端 URL 常内嵌凭据如https://x-access-token:TOKENhost/...任何经由该类型发布身份的 surface 都无法“忘记排除”它数据库绑定端点缺席ServerHost/ServerPort不进入共享投影——对外广告端点会诱导客户端绕过 API 直连一个信任模型为“root 空密码 loopback”的服务器绝对主机路径缺席CWDRepoRoot、ProxiedDir、DataDir对消费者无标识意义。这些本地诊断信息只由 CLI 在属主自己的终端上打印。该策略由测试 internal/httpapi/context_test.go 的TestContextHandlerServesOnlyTheAllowlist强制执行断言响应体不得携带白名单之外的字段、不得包含 sync remote URL、不得包含伪造令牌与 Dolt 绑定端点如3307。九、降级状态下的诊断价值回到bd context最核心的定位——降级状态诊断。当数据库无法打开例如损坏、迁移未完成、schema 分叉时多数命令会失败但bd context仍能通过以下机制给出可靠答案直接读配置而非打开数据库direct 路由selectedNoDBBeadsDir允许通过--db标志或BEADS_DIR等环境变量指向任意工作区即便当前目录不是该工作区cmd/bd/main.go配置加载失败时回退到configfile.DefaultConfig()保证在.beads目录残缺时也能返回部分信息而不是直接崩溃context_cmd.go。典型排障路径# 数据库打不开时先确认工作区绑定的后端与环境 bd context bd context --json # 指定一个具体的 .beads 目录做诊断无需 cd 过去 bd context --db /path/to/workspace/.beadsbd context也因此与bd doctor等诊断工具共用同一套按目录解析的同步远端与仓库上下文基础设施sync_remote.go是全仓库诊断体系的第一块拼图。十、从源码到实践的快速索引关注点参考文件命令定义与 direct 路由cmd/bd/context_cmd.goproxied 路由与视图投影cmd/bd/context_proxied_server.go身份发布策略白名单投影internal/storage/domain/context.go仓库路径解析与安全边界internal/beads/context.go配置加载与默认值internal/configfile/configfile.go同步远端解析cmd/bd/sync_remote.goHTTP 端点白名单测试internal/httpapi/context_test.go配置优先级与漂移测试cmd/bd/context_cmd_test.go仓库上下文设计文档engdocs/REPO_CONTEXT.md命令官方文档docs/cli-reference/context.md结语bd context虽然是一条输出“环境信息”的命令但它的实现浓缩了 Beads 在多后端、多模式、重定向与 worktree 场景下身份解析的全部关键决策直接读配置以保障降级可用性、双路由共享同一视图以保证一致性、SetBackendIdentity门控 Dolt 专属字段以防止身份谎言、PublishedContext白名单投影以隔离可能携带凭据或诱导直连的敏感字段。无论是人工排障、脚本采集还是 Agent 自动化环境探测bd context都是理解“当前 Beads 工作区到底处于什么状态”的最快入口——记住它的 JSON 输出与不打开数据库这一特性就能在绝大多数疑难场景中先于问题一步定位环境。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考