Beads 与 Aider 集成实战：在人工审核工作流中用 `/run` 批准 `bd` 命令-编程实验室

Beads 与 Aider 集成实战：在人工审核工作流中用`/run`批准`bd`命令

【免费下载链接】beadsBeads - A memory upgrade for your coding agent项目地址: https://gitcode.com/GitHub_Trending/beads1/beads

Beads（bd）为编码 Agent 提供了一套完整的 issue 跟踪与记忆系统，而 Aider 是典型的人工在环（human-in-the-loop）AI 结对编程工具：它不会自主执行 shell 命令。本文介绍如何通过bd setup aider将两者对接，让 AI 在对话中建议bd命令，由你使用 Aider 的/run逐一确认执行，从而实现"AI 提议、人工把关"的受控 issue 工作流。读完本文，你将掌握从安装、配置到完整会话闭环（认领、创建、同步）的全部实操方法，并理解其背后的源码实现原理。

Aider 集成的设计理念

与 Claude Code 集成这类自主 Agent 不同，Aider 默认不允许 AI 直接执行任意 shell 命令。Beads 的 Aider 集成完全顺应这一设计约束：AI 的角色是"顾问"，它读取工作流说明后向你建议合适的bd命令，而你作为人类，通过 Aider 的/run命令批准并执行每一条命令。

这意味着整个 issue 操作链条——查看可认领的工作、创建新 issue、更新状态、推送数据库——都在你的显式确认下进行，AI 不会越过你的控制直接改动 issue 数据。这种模式尤其适合需要严格审核、逐步验证的开发场景。

前置条件

在开始集成前，需要满足两个基础条件：

Beads 已安装并完成项目初始化：如果项目根目录还没有.beads/目录，先运行bd init完成初始化。Beads 的安装方式（Homebrew、npm、安装脚本、go install等）参见安装文档。
Aider 已安装：通过pip或pipx安装均可：

pip install aider-chat # 或 pipx install aider-chat

快速设置：`bd setup aider`

安装完成后，在项目根目录执行：

bd setup aider

该命令会一次性生成三个文件，分别服务于 AI 和人类：

文件	用途	消费方
`.aider.conf.yml`	告诉 Aider 加载 Beads 工作流指令（只读注入）	Aider 启动配置
`.aider/BEADS.md`	AI 阅读的工作流指令（规则、命令速查）	AI 模型
`.aider/README.md`	面向人类的快速参考手册	开发人员

验证安装

bd setup aider --check

移除集成

bd setup aider --remove

该命令会删除上述三个文件；如果.aider/目录变空也会一并清理。

源码视角：集成背后的实现

bd setup命令的所有编辑器集成都是通过 recipe 机制统一管理的（cmd/bd/setup.go）。在runAiderRecipe分发函数中（cmd/bd/setup.go），bd setup aider的三个形态分别对应三个底层函数：

默认安装 →setup.InstallAider()
--check→setup.CheckAider()（仅校验.aider.conf.yml是否存在）
--remove→setup.RemoveAider()

具体实现在 cmd/bd/setup/aider.go：InstallAider先通过EnsureDir创建.aider/目录（权限 0755），再通过atomicWriteFile原子写入三个模板文件，避免写入中断产生半成品配置。RemoveAider对三个文件逐一执行删除，且对"文件不存在"的场景做了容错（os.IsNotExist时跳过），因此对从未安装过的目录执行--remove也不会报错。

这一套行为在 cmd/bd/setup/aider_test.go 中有完整测试覆盖：TestInstallAider验证三个文件的内容与模板完全一致，TestInstallAiderIdempotent验证重复安装不产生内容漂移，TestRemoveAider_DirectoryWithOtherFiles验证当.aider/目录中还留有其他文件时不会被误删。

配置文件解析

`.aider.conf.yml`：把指令注入只读上下文

生成的文件内容如下：

# Beads Issue Tracking Integration for Aider # Auto-generated by 'bd setup aider' # Load Beads workflow instructions for the AI # This file is marked read-only and cached for efficiency read: - .aider/BEADS.md

这是 Aider 的read配置指令：启动时把.aider/BEADS.md加载进 AI 的只读上下文。注释里特意标注"read-only and cached for efficiency"，说明该文件只作为参考信息注入，AI 不会修改它，且 Aider 会对其做缓存以提高效率。该模板定义于源码常量aiderConfigTemplate（cmd/bd/setup/aider.go）。

`.aider/BEADS.md`：AI 的工作流规则

.aider/BEADS.md是 AI 在会话中遵循的规则集，核心内容对应源码常量aiderBeadsInstructions（cmd/bd/setup/aider.go），主要包括：

核心工作流规则：

所有工作都记录在bd中（绝不使用 markdown TODO 或注释式任务清单）；
建议bd ready查找可认领的工作；
建议bd create创建新 issue / 任务 / bug；
会话结束时建议bd dolt push；
始终以"建议"形式给出命令——由用户通过/run执行。

命令速查表（AI 会建议这些命令）：

命令	作用
`bd ready`	显示无阻塞的 issue
`bd list --status=open`	列出所有打开中的 issue
`bd create --title="..." --type=task`	创建新 issue
`bd update <id> --claim`	原子认领工作
`bd unclaim <id>`	释放卡住的 issue
`bd close <id>`	标记完成
`bd dep add <issue> <depends-on>`	添加依赖关系
`bd dolt push`	推送变更到 Dolt 远程

issue 类型与优先级：模板中内置了完整枚举——类型包括bug（损坏需修复）、feature（新功能）、task（工作项：测试/文档/重构）、epic（由多个 issue 组成的大型功能）、chore（维护类工作：依赖、工具链）；优先级0（严重：安全、数据丢失、构建损坏）到4（积压：未来想法），其中2为默认中等优先级。

你可以编辑.aider/BEADS.md追加项目专属指令，但注意重新运行bd setup aider会重新生成该文件，覆盖你的修改——如需持久化自定义，应通过bd prime的定制机制（见下文）或维护独立指令文件。

`.aider/README.md`：人类的速查手册

面向开发人员的快速参考（源码常量aiderReadmeTemplate，cmd/bd/setup/aider.go），包含 Quick Start 五步操作、issue 类型与优先级速查，以及"如何与 AI 对话"的建议提问方式（如"What issues are ready to work on?"、"Create an issue for this bug I found"、"Show me the details of bd-42"）。

会话工作流

启动会话

# Aider 会通过 .aider.conf.yml 自动读取 issue 上下文 aider # 或者手动注入完整上下文 bd prime | aider --message-file -

第二种方式把bd prime的输出通过管道喂给 Aider 作为初始消息，适用于未运行bd setup aider、或需要在会话开头就拿到完整工作流文档的场景。

Aider 内部的人机协作

在 Aider 中，以/开头的都是 Aider 自身命令（/run、/add、/help），其余输入都是发给 AI 的消息。AI 建议bd命令，你批准后用/run执行：

You: What issues are ready to work on? Aider: Let me check the available work. Run: /run bd ready You: Let's work on bd-42 Aider: To claim it, run: /run bd update bd-42 --claim

如果会话中途需要给 AI 补全 bd 上下文，直接执行/run bd prime——AI 会读取输出并掌握完整工作流指南。

工作中的旁路操作

有些操作更适合在另一个终端或退出 Aider 后直接执行：

# 工作中发现的 bug，记录为依赖 issue bd create "Found bug during work" --deps discovered-from:bd-42 --json bd update bd-42 --claim bd ready # 把已创建的 issue 关联为"工作中发现"的依赖 bd dep add bd-77 bd-42 --type discovered-from

--deps discovered-from:<parent-id>是 Beads 中记录"工作期间发现的新问题"的标准方式，用于还原问题的来源脉络。

结束会话

bd dolt push

将本地的 issue 数据库变更推送到 Dolt 远程，实现多端同步。

完整示例工作流

# 1. 查看可认领的工作 bd ready # 2. 带着 issue 上下文启动 Aider aider --message "Working on bd-42: Fix auth bug" # 3. 在 Aider 中工作... # 4. 创建工作期间发现的关联 issue bd create "Found related bug" --deps discovered-from:bd-42 --json # 5. 完成并同步 bd close bd-42 --reason "Fixed" bd dolt push

最佳实践

保持 issue 可见——用bd prime把 issue 上下文注入会话，AI 才能给出有针对性的建议；
定期推送——重要变更后运行bd dolt push，避免数据库长时间不同步；
善用 discovered-from——记录工作中发现的问题，形成完整依赖链；
写清描述——创建 issue 时附带有意义的信息，方便 AI 和协作者理解；
职责分离：Aider 提交代码，bd 同步数据——Aider 自动提交你的代码改动（git），issue 数据则通过bd dolt push独立同步，两者互不干扰。

深入理解`bd prime`的上下文注入

bd prime是整套 Aider（以及其他 Agent 集成）工作流的上下文支柱，实现在 cmd/bd/prime.go。它输出 AI 优化的 markdown 格式工作流上下文，并自动检测运行环境：

MCP 模式：输出精简的工作流提醒（约 50 tokens）；
CLI 模式：输出完整命令参考（约 1–2k tokens）——这正是 Aider 场景下注入的形态。

几个与 Aider 工作流直接相关的行为：

自定义工作流：在.beads/PRIME.md放置自定义模板可覆盖默认工作流文本，bd remember的持久记忆仍会追加，记忆注入不受影响；可用--export导出默认内容用于定制。
记忆上限：--max-memories N与--max-memory-chars N（或配置键prime.max-memories/prime.max-memory-chars）可限制注入的记忆量，防止大记忆集挤占 Aider 的上下文预算；超出部分会输出横幅提示用bd memories浏览。
超时控制：默认 10 秒，可通过环境变量BEADS_PRIME_TIMEOUT调整（cmd/bd/prime.go）。

由于注入的是紧凑文本而非 MCP 工具模式，bd prime的上下文成本远低于完整工具定义，这也是 CLI + 指令注入模式在 Aider 场景下高效的原因。

故障排查

配置未加载

# 检查配置文件是否存在 cat .aider.conf.yml # 重新生成 bd setup aider

Aider 在启动时读取.aider.conf.yml，因此重新生成配置后需要重启 Aider（/exit后重新执行aider）才能生效。

issue 不可见

# 用 bd prime 手动注入 issue 上下文 bd prime | aider --message-file - # 或者检查数据库健康状况 bd doctor

bd doctor会检查本地 issue 数据库的健康状态，若存在损坏或迁移问题，优先修复后再继续。

Beads 与 Aider 集成实战：在人工审核工作流中用 `/run` 批准 `bd` 命令