在传统 IDE 插件式的 AI 辅助编程场景中，开发者通常通过多轮对话逐步完善代码实现。这种交互模式虽然灵活，但存在上下文漂移、 token 消耗累积以及响应延迟等问题。Broccoli 作为一款新兴的云端编码代理，提出了截然不同的工程范式：将完整的 Linear 工单转化为可直接合并的 Pull Request，整个过程在单次触发后自动完成，无需开发者持续参与交互。本文将从架构设计、上下文管理、工具链编排和部署策略四个维度，深入解析这一 one-shot 编码代理的工程实现。
一、整体架构与组件划分
Broccoli 部署在 Google Cloud Platform 上，采用 Serverless 架构实现成本优化与运维简化。其核心组件分为两个 Cloud Run 工作负载，通过共享的 PostgreSQL 数据库实现状态持久化。
服务组件 broccoli-oss-service 是一个基于 FastAPI 构建的 Web 服务，负责接收来自 GitHub 和 Linear 的 Webhook 事件。服务执行三项关键任务：首先是签名验证，确保 Webhook 请求来源可信；其次是去重处理，通过持久化交付记录避免重复执行；最后是任务创建，将合法的 Webhook 事件转换为可执行的作业记录。这一组件设计遵循了事件驱动架构的经典模式，将触发逻辑与执行逻辑清晰分离。
执行组件 broccoli-oss-runner 是 Cloud Run Job 类型的长时间运行任务，它调用 codex 和 claude 两条 CLI 工具链执行实际的编码工作。Runner 从数据库中读取作业配置和上下文信息，基于模板化的提示词完成代码生成、测试编写和 PR 创建。与传统的长驻进程不同，Cloud Run Job 按需启动、执行完成后自动销毁，这种无服务器模式避免了资源闲置浪费。
数据持久层选用 PostgreSQL 存储多类核心数据：Webhook 交付记录确保幂等性，作业状态追踪执行进度，GitHub PR 状态和 Linear 工单状态维护外部系统同步结果，仓库配置和全局设置则支撑路由决策。Secret Manager 负责安全管理所有敏感凭据，包括 GitHub App 私钥、Linear API 密钥、OpenAI 和 Anthropic 的模型 API 密钥，以及数据库连接字符串。这种分离设计使得凭据轮换无需重新部署服务代码。
二、One-Shot 范式与上下文窗口管理
Broccoli 的核心设计哲学是单次触发完成完整功能交付，这与传统多轮对话式 AI 编程形成鲜明对比。当开发者将 Linear 工单分配给配置的 Bot 用户时，自动化流程即被启动：系统首先解析工单内容，提取功能需求和验收条件；随后在单个执行周期内完成代码实现、单元测试编写、PR 创建以及自动化 Code Review 反馈。整个过程无需开发者逐轮确认或补充上下文，显著降低了协作成本。
实现这一范式的技术关键在于上下文窗口的高效利用。与在对话中渐进式补充信息不同，Broccoli 在任务启动时即将所有必要信息聚合到提示词模板中。这些模板经过精心设计，包含仓库结构描述、现有代码摘要、技术栈约定和代码规范指引。Runner 执行时通过一次性加载完整上下文，避免了多轮交互中的信息丢失和上下文漂移问题。
具体实现上，Broccoli 采用外部持久化文件作为上下文补充机制。AGENTS.md 文件记录团队级别的编码约定和注意事项，tasks.json 维护任务拆解进度，progress.txt 追踪各功能的实现状态。这些文件作为结构化外部记忆，使得长时间运行的作业能够在上下文窗口受限的情况下依然保持状态连贯。当 token 使用率达到约百分之五十时，系统触发上下文压缩，保留关键依赖关系的同时裁剪冗余信息。
上下文管理还涉及 Git 状态的精确追踪。Runner 在执行过程中持续更新 git log 和 progress.txt，下一次迭代启动时可快速定位已完成工作和待处理事项。这种基于文件系统的时间旅行设计，使得即使执行中断也能通过重试机制无缝衔接，而非从头重建整个上下文。
三、工具链编排与模型路由
Broccoli 的工具链架构采用双模型并行策略，同时支持 Anthropic Claude 和 OpenAI Codex 两条技术路径。这种设计提供了供应商层面的灵活性：开发者可根据成本、速度或模型能力的具体需求选择底层模型，而上层抽象保持一致。
工具调用通过统一的 CLI 外壳层封装。Runner 内部通过子进程调用 codex 或 claude 命令，传入精心构造的提示词和上下文文件，解析返回的执行结果。这种松耦合设计意味着添加新模型支持只需实现对应的 CLI 适配器，无需改动核心执行逻辑。提示词模板采用 vendored 方式管理，与代码仓库同版本控制，团队可 fork 并定制符合自身编码规范的提示策略。
执行流程中的工具编排遵循结构化步骤：首先是环境准备阶段，克隆目标仓库并安装依赖；接着是需求分析阶段，基于 Linear 工单生成实现计划；然后是代码生成阶段，按计划逐个实现功能模块；随后是测试验证阶段，运行单元测试和端到端测试确保功能正确；最后是 PR 创建阶段，生成符合团队约定的提交信息和变更描述。每个阶段都配置了超时阈值和错误处理策略，失败时提供可操作的诊断信息。
Broccoli 还内置了 AI Code Review 能力。每次 PR 创建后，Claude 和 Codex 会自动读取变更 diff，生成可执行的审查意见。对于标注为需要修复的问题，Agent 可在收到确认后推送修复提交。这种闭环设计将代码质量把控融入了自动化流程，而非依赖人工事后审查。
四、路由决策与触发机制
Broccoli 的触发机制建立在明确的路由规则之上，确保只有符合特定条件的 Linear 工单才会启动自动化流程。路由判断基于三个维度的匹配：工单必须分配给配置的 Bot 用户，工单必须携带匹配的标签以映射到具体仓库，工单的估算值决定了使用的技能路径。
仓库配置在数据库中持久化，每条记录包含仓库标识、GitHub 完整名称、安装 ID、克隆地址、默认分支和目标分支等关键属性。通过标签匹配 repo_key 的设计，使得同一 Linear 团队下的不同项目可路由到不同的代码仓库，实现了多仓库统一管理的灵活性。
当工单估算值小于三时，系统选择小估算技能路径，可能采用更快速的实现策略；其他情况使用默认路径。这种分级策略在保证功能完整性的同时，为小型改动提供了轻量级执行选项，优化了资源消耗和响应时间。
五、增量部署与运维策略
Broccoli 的部署流程被压缩在约三十分钟内完成，通过引导脚本实现半自动化部署。部署分为多个阶段：首先是基础设施准备，包括 GCP 项目创建、Cloud SQL 实例配置和 Secret Manager 密钥注入；然后是容器镜像构建，利用 Cloud Build 自动构建并推送至 Artifact Registry；最后是引导脚本执行，部署 Cloud Run Service 和 Job 并配置环境变量。
引导脚本设计为幂等执行，这意味着即使部署中断或配置变更，也可安全重试而不会产生副作用。脚本采用增量更新策略，仅修改发生变更的配置项，避免了全量重建带来的服务中断。对于生产环境，这种设计支持零停机迭代和快速回滚。
Webhook 去重是保证幂等性的关键机制。每个 Webhook 交付记录包含唯一标识，已处理的交付在数据库中有对应记录，重复交付直接返回而不创建新作业。对于作业记录已存在但执行失败的情况，重复交付会复用原作业 ID，支持安全的重试流程。这种设计避免了因网络抖动或上游重试导致的重复执行问题。
运维监控通过数据库查询接口暴露关键指标。webhook_deliveries 表记录所有 Webhook 处理的详细结果，包括忽略原因和错误阶段；jobs 表追踪作业生命周期，包含状态、路由仓库键和错误信息；run_metadata 字段则记录了发布评论、GitHub Review 反馈等执行细节。运维团队可通过这些表快速定位问题作业和异常模式。
六、工程启示与实践建议
Broccoli 的架构设计为云端 AI 编码代理提供了一个可参考的生产级范式。其核心启示包括：首先是分离触发层与执行层的分层设计，Webhook 接收服务保持轻量且高可用，耗时编码任务在独立 Job 中运行并按需扩缩容；其次是外部化的上下文管理策略，通过文件系统持久化状态而非依赖内存，避免了长作业的上下文溢出问题；再次是明确的路由规则和幂等性保证，使得自动化流程可预测、可审计、可重试；最后是对供应商锁定的规避，通过统一的 CLI 抽象层支持多模型切换。
对于计划构建类似系统的团队，建议从以下参数开始：Runner 超时时间可设为三千六百秒以支持复杂功能实现，数据库连接使用 Cloud SQL Auth Proxy 通过 Unix Socket 建立安全连接，API 密钥存储在 Secret Manager 中并配置轮换策略，Webhook 签名字段与 GitHub 和 Linear 配置保持一致。在监控层面，应关注作业成功率、平均执行时长和 Token 消耗量等关键指标，建立告警阈值以及时发现异常。
Broccoli 作为 one-shot 编码代理的代表，其架构思路不仅适用于 Linear 到 PR 的自动化场景，更可扩展至更广泛的工程自动化领域。理解其上下文管理、工具编排和增量部署的设计决策，对于构建可靠的 AI 原生开发流程具有重要的参考价值。
资料来源
本文核心信息来源于 Broccoli 开源项目 GitHub 仓库（https://github.com/besimple-oss/broccoli）及其架构设计文档。