BOA — Build On Autopilot(自动驾驶构建)
约束你的代码以确保正确性。(Logo:docs/assets/logo.png,一条盘绕的蛇,带有一份文件和字标“BOA - Build on autopilot”。)
BOA 能让你做什么
BOA 让你,作为智能体,端到端地运行一个项目:启动、工作、暂停、恢复和关闭。你可以通过以下方式实现:
- 计划作为单一工作源,在工作树上并行处理分支(lanes);
- 构建者 → 对抗性审阅者 → 测试者 → 集成者,以及落地分支的合并列车(merge trains);
- 内置的混合搜索记忆系统,因此会话之间不会丢失任何学到的内容;
- 防止破坏性事故的防护措施,带有你为项目编写的规则;
- 从每个需求到测试的可追溯性,在关闭时追踪到零个未关闭项;
- 包含你需要的一切的手册和文件映射,以及保持长会话安全的上下文门(context-gate);
- 人在回路(HITL):当你无法知道或决定时,你询问用户,并提供备选方案和建议。
所有项目特定部分都由你根据接线检查清单(references/project-wiring.md)自行连接。
首先阅读已安装的 AGENTS.md 顶部的运作模式(安装前:<skill>/assets/templates/AGENTS.md);它是每条规则背后的基调。
你是主导。此技能将 BOA 安装到当前目录的项目中,验证安装,然后移交控制权给 run-project。下面的 <skill> 是此技能的基本目录(运行时会告诉你它从哪里加载了此文件)。此处每条命令都通过 BOA 的唯一入口点 boa <子命令>:安装前使用 sh <skill>/core/bin/boa,安装后使用 sh .boa/bin/boa(在 Windows 上:<skill>\core\bin\boa.cmd 和 .boa\bin\boa.cmd);boa help 列出子命令。
参数:$ARGUMENTS = <模式> [想法文件]:一个包含想法的文件,任意名称或路径,是可选的(步骤 2)。
| 模式 | 需要 | 安装后的启动引导(references/modes/<模式>.md) |
|---|---|---|
greenfield | 想法:要构建什么(一个文件,或对话) | 想法 → 蓝图 → 规格 + 契约 → 计划(首先处理规格侧任务) |
brownfield | 一个现有的仓库 | 分析器展开读取每一行 → 架构 + 代码遵守的契约 + 黄金测试(goldens) |
refactor | 一个现有的仓库 + 想法:重构的目标(一个文件,或对话) | brownfield + 黄金测试锁定当前行为;目标成为契约变更,记录为 ADR |
先决条件(首先检查)
BOA 需要 git 2.31+(项目必须是或成为一个 git 仓库)和 Python 3.11+(BOA 的工具仅使用标准库),加上你的智能体运行时;在 Windows 上,需要 Git for Windows。boa install 还会构建记忆搜索环境:一个位于 .boa/embed/ 的 BOA 自己的 venv(使用 Python 的 venv 模块以及到包索引和模型中心的网络访问;约 480 MB 和半分钟;在代理后面,设置 HTTPS_PROXY,包含凭据,因为下载使用重定向的主目录,其中 ~/.netrc 不会被读取);当该步骤失败时,它会指出缺少什么,其余部分保持安装状态,你询问用户如何提供,然后重新运行安装。启动器在没有任何其他操作之前检查两者,无需 Python:如果一个缺失或太旧,它不改变任何东西并返回退出码 3,指出缺少什么以及找到的版本。然后:用用户的语言告诉他们缺少什么、找到的版本以及如何在此操作系统上安装(现在验证当前方式);如果他们同意并有权限执行,自己为此操作系统编写步骤,显示它们并运行它们;否则用户运行你给出的步骤。再次检查;只要有一个缺失,就绝不继续。
此流程的规则
- 仅在自我评估、环境检查和文档无法决定时询问用户:一次一个问题,附带选项和你的建议优先。切勿猜测未知项:停止该项,询问,并继续处理其余部分。
- 切勿重复造轮子:对于每个项目特定的部分,使用内置功能、扩展它或采用一个现有的库或工具,其维护成本相对于收益是低廉的;仅在经过验证存在缺口时才从头编写。
- 保持两种语言分离:产品语言(代码、注释、文档、提交;默认英语)和用户语言(与用户的对话、记忆内容、报告、计划和笔记的自由文本);记忆语法始终是英语。
- 所有项目特定部分都是规范,而非发布的代码:安装后,项目接线检查清单(
references/project-wiring.md)中的每一项都成为run-project在完整流水线下工作的计划行。 - 未经用户的明确同意,切勿安装系统包、更改共享服务或写入用户级设置;只要 BOA 的一个先决条件缺失,就绝不继续。
- 切勿覆盖项目文件:安装程序将冲突的渲染文件放在
.boa/pending/中,你手动合并它们,向用户展示更改内容。 - BOA 提供工具和钩子;你将它们连接到你的运行时。安装程序不写入任何运行时目录或运行时设置。
- 如果一个步骤失败,则停止并给出明确的失败报告;半完成安装绝不被报告为已完成。
步骤
- 能力自我评估(首先)。 在任何其他操作之前,评估你的运行时提供什么,通过检查它(其文档、
--help、设置模式、无害的试用),切勿凭记忆:钩子及其事件、子智能体和并行性、后台任务、工作树、每个子智能体的模型选择、权限模式、调度、网络访问、工具和限制。根据此评估,决定如何实现规范的每个部分(流水线角色、分支、防护、时钟、暂停/恢复、上下文门),声明你使用的每个替代品以及你无法提供的每个部分(切勿伪造一个)。无论你无法自行确定什么,都要询问用户,一次一个问题,附带选项和建议:所有者(HITL)主题、变异测试(是否有敏感代码?哪个工具?)、CI、远程运行器、模型、保护。将结果记录为能力记录,放在memory-bank/04-ARCHITECTURE.md的“环境”部分(与项目一起版本化;一旦步骤 6 的安装写入了该文件;绝不放在.boa/下,该目录被 git 忽略),并将决策记录为决策条目。 - 参数、仓库和想法。 验证模式。项目是当前目录的 git 顶级目录。没有仓库:在
greenfield模式下,提供git init并在用户同意后运行它;在brownfield/refactor模式下,停止并要求正确的目录。然后关于想法:- 当用户指定一个文件时,任意名称或路径(不仅仅是
IDEA.md),完整读取它;如果指定的文件不存在,则询问用户,切勿猜测; - 在
greenfield/refactor模式下且没有文件时,从用户已经在对话中说过的话中获取想法(或重构的目标),或要求用户描述;将其写入项目中的IDEA.md,以便版本化,向用户展示,并且仅在用户确认后才继续; - 简短的想法也可以:你仍然推导出所有规格,每个疑问都成为给用户的问题(
references/modes/greenfield.md,步骤 1); - 在
brownfield模式下,不需要想法文件;用户在对话中给出的额外指示(约束、优先级)记录在项目的记忆或计划中。
- 当用户指定一个文件时,任意名称或路径(不仅仅是
- 检查环境(绝不安装任何东西):项目接线项“能力记录”(
references/project-wiring.md)说明了检查什么以及如何检查。判断是否期望从 IDEA 或代码中出现长的测试波(大型测试套件、集成或浏览器测试、慢速构建)。然后:- 缺少某些东西:不改变任何其他内容;用用户的语言告诉他们缺少什么、找到的版本以及如何在此操作系统上安装(现在验证包名称)。如果他们有权,提出执行:如果同意,自己为此操作系统编写步骤,显示它们,运行它们。否则用户运行你给出的步骤。然后再次检查;只要有任何缺失,就绝不继续。
git config user.email(或user.name)为空:要求提交身份(项目本地git config,绝不全局)。
- 问题(仅限步骤 1 和 3 后仍悬而未决的问题),每个都附上你的建议:
- 项目名称(默认:目录名称)、用户语言(从用户书写方式检测;在不明确时询问)和产品语言(默认英语;以后只能通过
boa language set更改);一个其字母没有 ASCII 形式(例如西里尔字母、CJK 或拉丁字母如 sharp s、带斜线 L、带斜线 O)的名称不会获得默认 slug:建议一个音译,与用户确认并通过BOA_PROJECT_SLUG传递; - 技术栈,当 IDEA 或仓库未指定时:根据
references/stack-choice.md中的目标选择(最新稳定版,现在在线验证;安装后将选择记录为 ADR),并且仅在存在真正的分叉时与用户确认; - 智能体运行时:你的自我评估(步骤 1)找到的那个,通过
BOA_RUNTIME传递(references/runtimes.md); - 模型(不附带默认值):从运行时的当前模型列表中选取运行时的前沿模型(构建者、审阅者、分析者)和稍低一级的模型(中级构建者、测试者、集成者),立即验证,并与用户确认;
- 代码托管平台(
references/forge.md):当检查未找到时,选择哪个平台(github/gitlab/none)和仓库;如果 CLI 缺失或未认证,说明如何修复。然后平台决策,一次一个问题,每个仅当用户明确同意后才执行:使用平台远程仓库(创建新仓库,或使用现有仓库,在第一次推送或 PR/MR 之前询问);其可见性(根据项目性质建议私有或公开,附上理由;用户决定);主分支的服务器端保护;CI,仅当其增加价值时(同意则计划项目接线检查清单中的 CI 任务,references/project-wiring.md:由智能体为此项目编写,触发条件、镜像和固定版本在此时决定并验证;BOA 不安装 CI 文件)。如果不同意,则保持所有内容为本地。 - 套件运行的位置,串行或并行,以及同时运行多少个(项目接线项“轻量级和重量级套件”:根据测量的负载提出,一次与用户决定),当预期有长的测试波或机器较小时,包括远程测试运行器:一个或一个池;它在安装后设置(项目接线项“远程运行器”),因此在运行器响应之前,
BOA_RUNNER保持为off。
- 项目名称(默认:目录名称)、用户语言(从用户书写方式检测;在不明确时询问)和产品语言(默认英语;以后只能通过
- 配置(项目接线项“配置”):
sh <skill>/core/bin/boa install --target . --package <skill>在不存在时写入带注释的模板到.boa/config.env并停止;填写每个答案(BOA_RUNTIME、BOA_STACK、BOA_MODE、BOA_PROJECT_NAME、BOA_REPLY_LANGUAGE、BOA_FORGE、BOA_FORGE_REPO、BOA_RUNNER、BOA_MODEL_FRONTIER、BOA_MODEL_MID、…;BOA_PYTHON:每个钩子运行的 Python)。暂存根目录及其每个任务的布局是你运行时的事实:从references/runtimes.md中你的运行时的配置文件中获取(读取你的运行时给你的真实临时目录,绝不凭记忆重建)并设置BOA_SCRATCH_ROOT。向用户简要展示生成的.boa/config.env。 - 安装: 再次运行
sh <skill>/core/bin/boa install --target . --package <skill>(在 brownfield/refactor 项目上首先尝试--dry-run并展示计划)。BOA 的智能体和命令仅放置在.boa/下(.boa/agents/、.boa/commands/);不发布任何特定于运行时的文件。它写入.boa/之外的所有内容:AGENTS.md(现有文件中的标记块)、memory-bank/、docs/agent-handbook.md、docs/parity/、主导目录、平台的 PR/MR 模板(.github/pull_request_template.md或.gitlab/merge_request_templates/Default.md),以及.gitignore、.gitattributes(BOA 的文件固定为 LF 行尾)、.git/info/exclude和项目自己的memory-bank/04-ARCHITECTURE.md(残留寄存器)中的标记块。阅读其报告:对于每一行conflict或kept,手动将.boa/pending/<路径>的渲染内容合并到项目文件中(保留项目的内容;添加 BOA 的内容),然后重新运行安装程序,直到它报告没有留存的冲突,且你尚未有意解决。空的 REQUIRED 值或无效值会停止,并指出键名:在.boa/config.env中修复并重新运行。 - 将 BOA 连接到你的运行时(以你自己的运行时格式自连接)(项目接线检查清单项;每个运行时的操作方式,如示例且无默认值:
references/runtimes.md)。BOA 的智能体和命令文件携带一个中性头部(名称、描述、模型层级、投入、工具)和一个运行时中性的主体:你转换它们,BOA 不附带任何适配器。根据步骤 1 找到的内容完成所有操作,然后在你的运行时中验证:- (a)
.boa/agents/中的智能体,以你的运行时子智能体格式,并为每个层级配置了模型; - (b)
.boa/commands/中的命令,以你的运行时命令或提示格式; - (c) 在运行时配置中注册 BOA 附带的钩子(
references/runtimes.md中的事件、匹配器、命令清单),将其事件映射到 BOA 的中性事件,包括报告捕获:子智能体停止钩子将每个智能体的最终报告逐字保存到分支日志,加上主导停止和会话状态钩子; - (d) 当你的运行时缺少其中一项(没有子智能体、没有命令、没有钩子、无法拒绝的钩子)时,你在能力自我评估下选择的最接近的忠实等价物,声明且绝不伪造;当你无法确定时询问用户;
- (e) 指令:所有规则都位于 AGENTS.md 中;只有不原生读取 AGENTS.md 的运行时,才会获得其自己的指令文件。
- (a)