企业官网建设流程全解析

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）**的后端身份信息，覆盖三类内容：

1. 仓库路径：.beads目录、仓库根、当前工作目录所属仓库等；
2. 后端配置：存储后端类型、Dolt 模式、数据库名、服务器地址等；
3. 同步设置：同步远端（sync remote）。

它被设计为只读命令，注册方式见 cmd/bd/context_cmd.go：

func 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 format

context命令归属于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.go）；redirected、worktree、role均为条件打印；
• Backend 节：mode、database属于 Dolt 专属身份——注册的第三方后端两者都为空串，此时一律省略不打印，避免“mode 后面空无一物”被误读为“判定失败”而不是“不适用”（context_cmd.go）；server以host:port形式打印；
• Sync 节：仅当配置了同步远端时才出现。

JSON 输出

--json模式下，ContextInfo结构体（cmd/bd/context_cmd.go）按如下 JSON 键序列化：

错误路径同样尊重--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.

其组装流程为：

1. selectedNoDBBeadsDir(cmd)解析目标.beads目录（支持--db标志、BEADS_DB/BD_DB/BEADS_DIR环境变量，见 cmd/bd/main.go），使得无需打开数据库也能针对指定工作区回答问题；
2. beads.GetRepoContext()解析仓库路径（内部有sync.Once缓存）；
3. rc.Role()读取角色；角色未配置且发生重定向时隐式判定为contributor；
4. configfile.LoadForDiscovery(rc.BeadsDir)加载配置，失败时回退到configfile.DefaultConfig()；
5. applyContextBackend填充后端身份与 Dolt 专属字段；
6. resolveSyncRemoteFromDir(rc.BeadsDir)解析同步远端；
7. 统一交给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持续守护。

contextInfoView（context_proxied_server.go）内部先用domain.PublishedContext投影出所有“对外发布”字段（与 HTTP 端点GET /v0/beads/context完全同源），再把重定向标志、worktree 标志、绝对主机路径、绑定端点、角色与同步远端等本地诊断字段叠加在快照之上——这些字段是给工作区属主终端看的，不会进入共享投影。

四、后端身份策略：SetBackendIdentity与 Dolt 专属字段

后端身份是bd context输出的核心，其赋值逻辑集中在 internal/storage/domain/context.go：

func (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 = "dolt"；
• Dolt 模式常量：embedded/server/proxied-server（configfile.go）；
• 默认值：主机127.0.0.1、端口3307（刻意避开 MySQL 默认 3306）、数据库beads（configfile.go）。

各字段的优先级规则（均有对应 Getter 实现）：

其中data_dir的典型使用场景是 WSL：项目位于慢速 NTFS（9P 协议）挂载上，而 Dolt 数据可放到原生 ext4 以获得明显更好的 I/O（configfile.go）。

环境变量覆盖是一个真实的漂移向量

测试 cmd/bd/context_cmd_test.go 的TestContextInfo_EnvVarOverrides验证了这一点：metadata.json中写入dolt_server_host: 192.168.1.50，设置环境变量BEADS_DOLT_SERVER_HOST=10.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_dir（GH#2251），防止绝对路径扩散到其他克隆导致数据丢失，见TestContextInfo_SaveStripAbsoluteDataDir（context_cmd_test.go）；
• project_id由GenerateProjectID()生成 UUID v4（configfile.go），用于项目身份校验（GH#2372）。

六、仓库上下文解析：路径、重定向与 worktree

bd 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标志即用于标记这些情形。

解析流程（buildRepoContext）

1. FindBeadsDir()查找.beads目录（尊重BEADS_DIR环境变量）；
2. 安全边界校验（SEC-003）：isPathInSafeBoundary拒绝/etc、/usr、/var、/root、/System、/Library、/bin、/sbin、/opt、/private等系统目录，并拒绝其他用户的主目录，同时为os.TempDir()、/var/home（Fedora Silverblue 系）、/var/tmp、/Users/Shared（macOS 共享目录）提供带符号链接解析的放行通道（context.go）；
3. 检查重定向文件GetRedirectInfo()，重定向或外部.beads目录时以该目录所在仓库根为 RepoRoot；
4. 通过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-002，context.go）。详细设计另见 engdocs/REPO_CONTEXT.md。

七、同步远端解析

同步远端由 cmd/bd/sync_remote.go 的resolveSyncRemoteFromDir解析，针对指定.beads目录的配置读取：

1. sync.remote（首选，任何 Dolt 兼容远端 URL）；
2. sync.git-remote（已废弃的兼容回退）；
3. 空串（未配置）。

该函数被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:TOKEN@host/...），任何经由该类型发布身份的 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仍能通过以下机制给出可靠答案：

1. 直接读配置而非打开数据库（direct 路由）；
2. selectedNoDBBeadsDir允许通过--db标志或BEADS_DIR等环境变量指向任意工作区，即便当前目录不是该工作区（cmd/bd/main.go）；
3. 配置加载失败时回退到configfile.DefaultConfig()，保证在.beads目录残缺时也能返回部分信息而不是直接崩溃（context_cmd.go）。

典型排障路径：

# 数据库打不开时，先确认工作区绑定的后端与环境 bd context bd context --json # 指定一个具体的 .beads 目录做诊断（无需 cd 过去） bd context --db /path/to/workspace/.beads

bd context也因此与bd doctor等诊断工具共用同一套按目录解析的同步远端与仓库上下文基础设施（sync_remote.go），是全仓库诊断体系的第一块拼图。

十、从源码到实践的快速索引

结语

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