Beads 与 OpenCode 集成指南：通过 bd setup opencode 为 AI 编码代理注入管理工作流上下文

Beads 与 OpenCode 集成指南通过 bd setup opencode 为 AI 编码代理注入管理工作流上下文【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beadsBeadsbd为 AI 编码代理提供了一套完整的 issue 跟踪与任务管理工作流。本文讲解如何通过bd setup opencode命令以受管managed的AGENTS.md区块形式将 Beads 工作流上下文接入 OpenCode —— 让 OpenCode 在每次会话启动时自动读取 Beads 的任务跟踪指引从而在编码过程中遵循统一的 issue 驱动工作流。读完本文你将掌握 OpenCode 集成的安装、检查、更新与移除方法并理解其底层基于标记marker与哈希hash的托管机制是如何保证指引文件永不失效、可安全重复执行的。集成原理以受管的 AGENTS.md 为唯一入口OpenCode 会在每个会话开始时读取项目根目录下的AGENTS.md将其中的指令注入代理的系统提示。Beads 的 OpenCode 集成正是利用这一机制不需要安装任何插件或启动后台服务只需在AGENTS.md中维护一个由bd管理managed的 Beads 区块。从源码看该集成在 cmd/bd/setup/opencode.go 中被定义为一个标准的 agents 集成var opencodeIntegration agentsIntegration{ name: OpenCode, setupCommand: bd setup opencode, readHint: OpenCode reads AGENTS.md at the start of each session. Restart OpenCode if it is already running., profile: agents.ProfileFull, }几个值得注意的要点profile: agents.ProfileFullOpenCode 集成默认使用full完整信息档位注入的是包含完整 issue 工作流、优先级表、会话完成协议的高信息量区块这是为了确保代理在不依赖其他提示文件的情况下也能获得完整的任务跟踪上下文。readHint提示用户 OpenCode 在会话开始时读取AGENTS.md——如果 OpenCode 已经在运行需要重启才能让新注入的指引生效。原文档也明确强调了这一点Restart OpenCode after setup if it is already running.集成目标文件为AGENTS.md具体路径由 internal/config/config.go 中的SafeAgentsFile()校验后决定见下文安全与健壮性一节。快速开始安装 OpenCode 集成在项目根目录执行bd setup opencode该命令会在当前项目中创建或更新AGENTS.md并写入受管的 Beads 区块。执行后终端会输出类似如下的结果Installing OpenCode integration... ✓ Created new AGENTS.md with beads integration ✓ OpenCode integration installed File: /path/to/AGENTS.md OpenCode reads AGENTS.md at the start of each session. Restart OpenCode if it is already running. No additional configuration needed!根据 cmd/bd/setup/agents.go 中installAgents的实现安装过程按当前文件状态分三种情况处理AGENTS.md不存在创建新文件直接写入包含 Beads 区块的完整模板对应internal/templates/agents/defaults/agents.md.tmpl模板自带快速参考、非交互 Shell 命令注意事项等基础指引见下节AGENTS.md存在但无 Beads 标记保留用户原有内容在其末尾追加 Beads 区块输出✓ Added beads section to existing AGENTS.mdAGENTS.md存在且已有 Beads 区块原地更新该区块到最新版本输出✓ Updated existing beads section in AGENTS.md。整个过程无需额外配置源码明确输出No additional configuration needed!命令可重复执行是幂等的。验证安装状态--check 与新鲜度机制安装完成后可用检查命令确认集成的当前状态bd setup opencode --checkcheckAgents见 cmd/bd/setup/agents.go会依次检查三类情况并输出不同的提示检查结果输出含义AGENTS.md不存在✗ AGENTS.md not found并提示运行bd setup opencode未安装文件存在但无 Beads 标记⚠ AGENTS.md exists but no beads section found需要补装标记存在但已过期⚠ OpenCode integration installed but stale: path需要更新标记存在且为最新✓ OpenCode integration installed: path (current)状态正常这里的新鲜度并不是简单比对文件修改时间而是一套基于 profile 与内容哈希的机制注入区块的起始标记携带元数据形如!-- BEGIN BEADS INTEGRATION v:1 profile:full hash:bacef91e --checkAgents读取标记中的 profile 与 hash与agents.CurrentHashWithOpts(checkProfile, detectRenderOpts())计算的当前期望哈希比对只有当meta.Hash currentHash且 profile 匹配时才判定为(current)否则提示 stale 并要求重跑bd setup opencode更新。这意味着当 Beads 模板内容升级、或渲染选项如是否配置了同步远端、no-push策略变化导致区块应更新时--check都能准确识别出需要刷新避免代理读到过时的指引。对应的测试用例位于 cmd/bd/setup/opencode_test.go例如TestCheckOpenCodeMissingFile验证了缺文件时--check返回错误并输出 setup 指引。移除集成当不再需要该集成时bd setup opencode --removeremoveAgents见 cmd/bd/setup/agents.go只删除由!-- BEGIN BEADS INTEGRATION --与!-- END BEADS INTEGRATION --标记包裹的受管区块完整保留你在AGENTS.md中的其他自定义内容。如果文件中根本没有 Beads 区块命令会直接提示No beads section found in AGENTS.md并安全退出。命令执行成功后OpenCode 重启后即不再加载 Beads 指引。注入内容详解OpenCode 代理会读到什么安装后写入AGENTS.md的受管区块模板见 internal/templates/agents/defaults/beads-section.md为代理提供了完整的工作流上下文主要内容包括硬性规则Important Rules✅ 所有任务跟踪一律使用bd禁止创建 markdown TODO 列表、禁止使用外部 issue 跟踪器、禁止重复建跟踪系统✅ 程序化使用场景一律加--json标志✅ 发现的新工作必须用discovered-from依赖链接到父 issue。快速开始命令Quick Startbd ready --json # 查找可领取的 ready 工作 bd create Issue title --descriptionDetailed context -t bug|feature|task -p 0-4 --json bd create Issue title --descriptionWhat this issue is about -p 1 --deps discovered-from:bd-123 --json bd update id --claim --json bd close bd-42 --reason Completed --jsonIssue 类型与优先级表Issue 类型bug缺陷、feature新功能、task测试/文档/重构等工作项、epic含子任务的大型功能、chore依赖与工具维护优先级0Critical安全、数据丢失、构建损坏→1High →2Medium默认→3Low →4Backlog。代理工作流Workflow for AI Agents先跑bd ready查看未被阻塞的 issue用bd update id --claim原子认领任务实现、测试、完善文档发现新工作时用bd create ... --deps discovered-from:parent-id创建关联 issue用bd close id --reason Done完成任务。生命周期与同步指引管理类命令bd defer id/bd supersede id、bd stale/bd orphans/bd lint、bd human id、bd formula list/bd mol pour name同步类每次写入自动提交到 Dolt 历史跨机同步使用bd dolt push/bd dolt pull并明确警告不要把.beads/issues.jsonl当作同步协议它只是被动导出。会话完成协议Session Completion结束 Beads 实现工作流时为剩余工作建 issue → 运行质量门禁测试/lint/构建→ 更新 issue 状态 → 按当前 profile 处理 git/同步保守/最小档位默认只汇报git status并等待批准team-maintainer 档位经仓库显式选择后才可执行git pull --rebase、bd dolt push、git push→ 交接总结。区块还包含Agent Context Profiles说明管理块是任务跟踪指引不是对仓库、用户或编排器指令的越权Conservative默认档位禁止未经明确要求执行 git 提交、推送或 Dolt 远端同步。源码级细节安全与健壮性设计除了基本的增删改查该集成在底层实现上还有若干值得了解的安全设计1. 配置文件路径校验SafeAgentsFile目标文件名经由 internal/config/config.go 的ValidateAgentsFile校验拒绝空值、拒绝绝对路径与路径分隔符、拒绝超过 255 字符、拒绝非 Markdown 扩展名。若配置值非法例如被手工编辑成带目录穿越的路径SafeAgentsFile()会回退到默认文件名AGENTS.md并记录警告日志。2. 符号链接保护symlink guardinstallAgents在写入前会先用os.Lstat检查AGENTS.md是否为符号链接见 cmd/bd/setup/agents.go。如果是 symlink会跳过注入并输出警告提示直接修改链接目标文件或替换为普通文件后重跑——这是为了防止通过链接意外改写其他指令文件、或在某些工作流中破坏被跟踪的链接条目。3. Profile 优先级full 优先避免信息丢失当同一AGENTS.md被多个集成共用典型场景是CLAUDE.md符号链接指向AGENTS.mdClaude 与 Codex 同时以它为目标时若文件已有 full 档位区块而当前请求的是 minimal实现会保留 full 内容源码注释明确to avoid information loss。--check中同样有对称逻辑minimal 集成检查 full 区块时按 full 判定当前。4. 渲染选项感知随配置动态变化detectRenderOpts见 cmd/bd/setup/agents.go会读取sync.remote/sync.git-remote与no-push配置未配置同步远端时渲染出的会话完成指引会省略bd dolt push步骤配置了no-push时同样会相应调整。因此同一模板在不同项目配置下渲染结果不同这也是哈希新鲜度检查存在的意义。5. 原子写入区块更新/移除均通过atomicWriteFile完成见 cmd/bd/setup/agents.go 等调用点避免写入中途崩溃导致AGENTS.md损坏。验证与测试仓库为 OpenCode 集成提供了专门的测试文件 cmd/bd/setup/opencode_test.go覆盖两个核心路径TestInstallOpenCodeCreatesNewFile在无AGENTS.md的项目中执行安装断言输出包含OpenCode integration installedTestCheckOpenCodeMissingFile在缺文件时执行--check断言返回错误且输出包含bd setup opencode引导。此外cmd/bd/setup/agents_marker_test.go 对标记解析、区块更新旧格式迁移到带profile:full的新格式、区块移除、minimal 档位切换等行为做了更细粒度的验证是理解该托管机制的补充材料。命令分发入口位于 cmd/bd/setup.go 的runOpenCodeRecipe。最佳实践小结安装后立即重启 OpenCodeOpenCode 在会话开始时读取AGENTS.md已运行的会话不会感知到新注入的指引每次升级 Beads 后跑一次--check利用哈希新鲜度机制确认区块是否过期过期时重跑bd setup opencode即可原地刷新不要把AGENTS.md设为符号链接否则安装命令会跳过注入如需多工具共享同一份指引建议直接共用一个普通文件并在各工具间复用如将 Claude 与 Codex 指向同一AGENTS.mdfull 档位优先级机制会保护内容不降级移除操作安全可逆--remove只删除标记内的受管区块不会触碰你在AGENTS.md中手写的任何其他内容。通过bd setup opencodeBeads 将完整的 issue 工作流无缝嵌入了 OpenCode 的代理上下文——无需插件、无需额外配置一条命令即可让 AI 编码代理在每次会话中自动遵循统一的 Beads 任务跟踪协议。【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考