镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/architecture.md ↗

架构与行为

本文说明控制面、权限、虚拟电脑以及检视和开发的工作方式。部署见部署细节,接口见管理 API,开发与测试见开发与验证,接入向导和项目规则见 Onboarding。

概览

一个 Node.js 22.13+ / TypeScript 控制面,使用系统内账号管理多个 GitHub App、机器人账号、仓库权限、模型配置和 Webhook 投递。

当前提供多账号控制面、每仓库一个长期 Docker 环境,以及可读代码、运行命令和修改文件的检视/开发 Agent。没有内置账号或仓库;开启仓库检视后接收事件并创建任务,满足开发条件时自动实现、测试、发布 bot 分支和 PR。/api/status 的项目环境、检视、开发及模型调用能力均可用;具体任务缺配置或失败会显示故障状态。

检视和开发由固定版本 Pi SDK 在项目长期容器内运行。能写 GitHub 的凭据和模型 Key 仅在控制面;Pi 的 loopback 模型入口通过任务专属 runner 邮箱请求控制面代理,没有跨项目共享服务或新增公网端口。模型需要自己读 GitHub 时(Issue、PR、评论、行内检视、Actions 运行、检查状态等),调用 github_read_token 经同一邮箱向控制面兑换只读令牌,见下文「任务只读令牌」。开发由模型在准备好时调用 create_pull_request:控制面立即固定唯一一次工作树快照,只在项目策略配置了非空测试命令时在快照之后运行它;模型提供的已执行测试命令只写入 PR 说明。策略测试失败、超时或输出截断时,工具返回 validation_failed 和输出,模型可修改后再次调用;成功只发布调用时的树,测试生成文件不进入 PR,无改动则正常结束且不创建 PR。控制面验证 diff 位置、head 和 bot 分支归属并负责推送与开 PR,同一 Issue 复用同一 bot 分支和 PR,Review 只允许 COMMENT,检视和开发流程不自动合并;Manager 默认有 Contents 写,可以另经 github_write 合并 PR,见角色池。

使用与权限

超级管理员登记 GitHub App(App ID、RSA 私钥)或机器人账号(Token),为入口保存签名凭据,控制面随后自动同步每个账号可见的仓库:GitHub App 列出全部安装及其仓库,机器人账号列出 /user/repos;启动时和每 10 分钟全量对账一次,installation/installation_repositories 投递在同一事务里即时更新,并随后触发一次全量同步。同步只记录“已安装”,不登记、不启用:超级管理员在仓库页点“启动”,选择模型(部署共享模型会同时授权给该仓库)和项目能力上限后,才登记仓库、创建虚拟电脑并开始检视;启动前收到的事件只归档,不补跑。超级管理员可以信任一个 GitHub owner(组织或个人账号,按数字 owner ID 保存,记录信任人、时间,以及可选的默认共享模型和启动时的项目能力上限,默认「可评论和打标签」),或在启动它的第一个仓库时勾选信任;此后这个 owner 下、GitHub 证明自己是管理员(仓库 Admin 或组织 owner 的派生授权)的项目管理员可以自己启动尚未启动的仓库,不能选择模型或其他参数:默认共享模型授权给新项目,资源按全局默认值,机器配置仍只归超级管理员,重新启用已禁用的项目也仍只归超级管理员。受信任组织之外的启动请求返回 403 organization_not_trusted,不是该仓库管理员返回 403 repository_admin_required。撤销信任只影响以后的启动。审计记录 organization.trusted、organization.trust_updated、organization.untrusted,启动仍记 repository.activated,操作人就是启动的人。已启用的仓库可以“禁用”:停止处理新事件、中止正在执行的任务并停止虚拟电脑,数据保留,之后可再启用。仓库只能经同步出现、再由超级管理员(或受信任组织的仓库管理员)启动,没有手动登记入口。超级管理员可以“删除”项目,但只在仓库已删除、或当前账号已完全不能访问它时允许:已移出安装(公开仓库别人仍能匿名读取也算)、安装被暂停或已不存在,以及读取仓库得到 404 或 403。删除时当场向 GitHub 核对,不看列表上的旧状态;仍能访问(包括权限不足)、GitHub 不可用、凭据缺失或答复不确定时拒绝,记录保留。核对通过后先禁用项目并取消未结束的任务,再走现有的环境删除(去掉各代容器和网络,工作卷都保留,不执行 docker volume rm),等执行中的任务退出后,在一个事务里删掉只属于该项目的记录:策略、成员分配、专属模型及其价格和授权、外部客户端及其授权、订阅、轮询进度和转发、投递、看板数据、任务及其日志和用量、环境记录、接入状态以及各账号安装列表里的这一行;操作审计保留。之后安装同步再看到这个仓库,它会像新仓库一样出现。从未启动的仓库满足同样条件时,只去掉安装列表里的行。项目列表在仍能看到、但安装授予的权限低于所需(对照 App 所需权限;机器人账号对照写入角色)的仓库上标出“权限不足”,标题写明缺哪些权限、当前是什么;这种仓库不能删除。徽章用同步时读到的授予权限,打开列表时若已超过 10 分钟,后台重读一次并就地替换徽章,不随任务数刷新,也不重画列表。任务执行时校验账号、实际仓库 ID 和所有者;App 在控制面签发 JWT、取得目标仓库安装令牌,机器人账号使用已保存的 Token,均不进入项目环境。仓库 ID 使用字符串提交,避免 JavaScript 大整数丢精度。

超级管理员可创建用户和分配项目管理员。每名项目管理员可分配多个仓库,每个仓库可有多名项目管理员。授权分两种,可以同时存在并取并集:单个仓库(可以是已安装但尚未启用的仓库,启用后项目沿用安装 ID,授权随即生效)和整个组织(按 owner_id,覆盖该组织已经启用和以后启用的项目,但不会因此启用安装)。项目管理员只看到并操作自己的仓库、投递、模型、策略及任务读取接口;无筛选查询同样受限,未关联仓库或验签失败的投递仅超级管理员可见。账号凭据、全局用户和授权关系接口只允许超级管理员调用。用户停用会撤销已有会话,仓库分配调整和组织下新启用的项目在后续请求立即生效;不能停用最后一名超级管理员。超级管理员可以删除用户:会话立即失效,仓库和组织授权、个人看板设置一并删除,登录名可以重新使用,操作审计保留;不能删除最后一名活跃的超级管理员,删除自己也要求还有另一名活跃的超级管理员。超级管理员可以删除 GitHub App 或机器人账号,前提是没有项目还在使用它;删除只从本系统移除账号、它的 Webhook 入口、安装同步记录和封存的凭据,不在 GitHub 上卸载 App,也不删除任何仓库。

模型配置包含接口 URL、API Key、模型名。超级管理员可管理全部模型;项目管理员可为自己的仓库创建和更新模型。部署共享模型默认对所有仓库可用(#850),超级管理员可以通过 models/:id/projects 把它限定给部分仓库;项目管理员只能读配置状态、选用,不能修改共享模型。超级管理员在仓库策略或“启动”中选择一个受限的共享模型时,会同时把它授权给该仓库。仓库策略保存选用的模型 ID。保存即信任,可以发送本项目代码、日志和测试材料,不增加数据授权等待状态。接口采用兼容 Chat Completions 的 JSON 工具调用协议;URL 按填写的路径使用:去掉末尾的 / 和末尾的 /chat/completions 得到基址,对话请求发往「基址 + /chat/completions」,模型列表取自「基址 + /models」;不会自动添加或删除 /v1。路由接在 URL 文本末尾,所以 URL 不能带查询串或 #,否则路由会落进其中。因此 https://example.com/v1 请求 https://example.com/v1/chat/completions,https://example.com 请求 https://example.com/chat/completions。多数兼容接口的基址以 /v1 结尾;基址不以 /v1 结尾时,添加模型的表单、接入向导和已保存的模型都会提示,但仍允许保存。供应商的新增/编辑表单统一提供「获取模型列表」(最多返回 200 个 id,超出时注明已截断),支持多选或手动添加模型,并对同一范围、同一请求地址下的模型批量更新 URL 或更换/撤销 Key;模型行保留单条「测试模型」(用固定的一句探测请求、max_completion_tokens 为 32 发送一次 Chat Completions);二者 15 秒超时,只返回上游状态码和上游 JSON 错误字段里的简短说明,不回显其他响应正文,也不返回 Key,不创建任务、不读取仓库,权限与编辑该模型相同。没有模型配置、撤销 Key、认证失败会显示 waiting_configuration;网络故障退避重试,持续的尝试失败进入每任务 8 小时重试周期;限流按自己的窗口等待。

账号凭据、入口签名材料和模型 Key 用 AES-256-GCM 加密,密文绑定记录 ID。读取和写入响应均只返回是否已配置,不返回明文或密文。更新时留空或仅空白的凭据保持原值;撤销使用专用动作,不能靠提交空字符串撤销。模型 PATCH 必须带读取到的 version,旧版本返回 409。撤销账号凭据不会连带撤销入口签名;要禁用入口需单独撤销该入口。

浏览器管理入口以项目为单位组织:“项目”页列出已安装和已登记的仓库及“未启动/工作中/已禁用/已移出安装”状态,超级管理员可同步安装列表、启动、启用或禁用;已启动的项目点每行的“设置”进入该项目独立的设置页(#/projects/<仓库 ID>/<类别>,可直接分享和刷新),未启动的仓库没有设置页,该行给出“启动”,直接打开它的项目地址时页面说明尚未启动并可就地启动;左侧类别为基本设置(仓库信息、处理账号、基准分支)、监听与触发(项目整体的事件来源与自动处理范围)、机器配置(虚拟电脑状态、实时资源、软件安装与初始化结果、启停与重置,以及 CPU、内存、进程数、/tmp、外网、额外软件包、环境变量和初始化脚本)、角色(可编辑概览和每个角色的模型、提示词、Agent、逐项权限、环境、预算与技能;Manager 详情还包含完整分派提示词与最近分派;事件开关放在项目级「监听与触发」页,见项目 Manager 与工作类型)、模型(项目默认模型、任务模型覆盖、项目专属供应商,以及只读展示和选用的部署共享模型)、发版本、项目笔记、外部执行、成员(仅超级管理员,分配项目管理员)和运行状态(正在执行、排队任务与最近任务)。/model 项目地址进入独立的「模型」页;旧的 /tasks、/review、/development、/rules 项目地址(以及原来的 /workflows)规范到「角色」页。项目管理员只看到自己的项目,机器配置只读。看板卡片进入的任务详情按时间线展示 Agent 工作过程:工作区准备、每一步模型思考与工具选择、读写的文件、在项目容器中执行的命令及退出码和输出、GitHub 发布和故障;运行中每 2 秒刷新,正在执行的命令单独显示并实时追加输出。每个页面都有地址(如 #/board、#/settings/users),刷新后停在原页面;旧地址 #/reviews、#/developments 分别选择看板的检视、开发类别。账号和用户在「全局设置」的对应类别里新增,凭据轮换等其余管理操作通过管理 API 完成。

工作看板

「任务看板」按 (repository_id,object_type,object_number,card_category) 标识一类工作。检视和开发各投影一张卡,即使另一类任务更新更晚,也不会改变当前卡片的状态或点击范围;尚无任务的 GitHub 对象保留未开始的检视卡。bot 发布的 PR 与来源 Issue 保持分离。发版本使用 project_releases 的现有记录,以 release_id 标识。默认显示全部对象,也可筛 Issue 或 PR;PR 开发的徽章显示「跟进」。筛选与分列分区呈现,分列支持 bot 执行阶段、仓库、执行状态、类别和自定义字段;明确筛掉的仓库或类别不生成列,零数量状态用紧凑计数表示。桌面锁定视口、列内纵向滚动;窄屏通过当前分组下拉显示一组纵向卡片。每 15 秒静默刷新第一页,拖动、输入或打开弹窗时跳过。卡片标题查询自身类别的关联任务,只有一个时直接进入任务详情,多个时在同一个弹窗内选择;执行状态筛选不隐藏该类别的历史任务。发版本进入项目现有发版记录,GitHub 外链直接打开 GitHub。

board_objects 是本地摘要表,由 tasks 与已验证、完整、非重复的 deliveries 在写入事务内通过触发器更新;包含评论里的 PR、检查和工作流事件引用的 PR 列表,以及开发任务结果中的新 PR 编号。首次升级按 rowid 每批 250 行回填历史。标题、GitHub 打开/关闭状态和草稿标记各自保留最近已知值,缺省字段不会抹掉之前的元数据。看板不扫描 GitHub,也不在绘制时按卡片请求 GitHub;对象与发版本的混合查询只取摘要、最新任务和发布阶段的必要列,每页最多 100 张,不返回发版本原始 data。对象、最近更新时间及任务对象关联均有索引;两类卡片都先应用仓库授权,空筛选不会扩展项目管理员的权限。

bot 执行阶段沿用未检视、正在检视、已检视、正在开发、已开发、需要处理、已停止七个阶段;已停止用于自动停止且没有已完成阶段可回退的卡片。混合对象时开发阶段文案同时涵盖跟进和发版。每一类任务单独按 updated_at(空值回退 created_at)取最近记录,独立计算该卡的阶段和执行状态。执行状态为正在执行、排队、失败、已完成、等待处理和其他/未开始,取消和过时任务不算正在执行、排队或失败。默认排除已关闭对象,可显式包含;草稿 PR 保留标记。查询返回全量筛选结果的 work_count 与 column_counts,列计数不受当前已加载页数影响;counts 则表示去重的 Issue/PR 对象数量,忽略对象类型筛选但保留其他条件。

board_views 按用户保存分列、筛选(包括对象类型)和折叠列(hidden_columns)。全部对象可用无对象筛选或 object_type:all 表示;不再使用浏览器中另存的对象类型覆盖视图。旧地址只在进入时设置类别,随即替换为 #/board,不能覆盖后来选择或另存的视图。内置默认看板可保存标准维度,不能删除、改名或增加阶段。自定义单选字段、选项和对象值仍分别存于 board_fields、board_options、board_values,按用户隔离;同一 GitHub 对象的工作卡共享个人字段值。只有自定义字段允许拖动与选择框修改值,执行阶段没有写接口,也不会因看板操作触发、停止或重试任务。

任务用量与成本

task_metrics 随任务状态进入和离开执行区间累计毫秒,运行中的时长在查询时动态补足;执行器定时保存计时检查点,排队与等待不计入。恢复上一个进程遗留的运行任务时关闭旧计时区间并标记不完整,避免把停机时间算成执行。重试保留累计值。升级前没有可靠计时的历史任务明确标记不完整,任务删除时附属计时级联删除。

模型调用只在控制面代理中记账:发起 HTTP 请求前插入 model_requests(项目运行记在 repository_id 上,管理助手等服务角色记在 service_role_id 上,范围只有一个仓库的飞书群同时记在这个项目上),收到响应后先保存用量,再将响应交给 runner。一次实际请求只有一条记录;同一回复尚未被 runner 取走时的重复轮询不会重记,实际发出的重试请求单独计数,runner 交付失败也不会抹掉已经发生的用量。连接异常、服务错误、缺少 usage 等保留为未知记录。兼容标准 Chat Completions 的 prompt_tokens_details.cached_tokens 与 DeepSeek 的 prompt_cache_hit_tokens,同时接受 input_tokens/output_tokens 形式。缓存命中 token 是输入子集;命中率按累计 token 加权,缺少数据不当作零命中。字段口径见 Chat Completions 对象 和 DeepSeek Chat Completions。

model_pricing 按模型保存美元或人民币的每百万输入/输出/缓存命中单价。请求账本保存当时的模型名、币种、单价快照和估算费用,不保存密钥或请求/响应全文;改价不重算历史。输入费用先扣除缓存命中部分,再分别按输入价和缓存价计算。未配置价格或缺少必要 token 时费用未知,不伪造免费请求;币种分别汇总,不作汇率换算。任务删除后账本仅解除任务关联,保留项目费用。共享模型价格沿用超级管理员编辑边界。

GET /api/costs 接收浏览器 IANA 时区,在用户授权仓库和限定本地日期区间内按 requested_at 的本地日、项目聚合费用和 token。使用带边界余量的日期与仓库/日期索引过滤,再按该时区的历史偏移和夏令时规则精确筛选与分桶;默认最近 30 天,最多 366 天及 5000 个费用分组。每类工作的任务(检视、开发、通用回复、Actions 失败分析、CI 观察等)独立聚合,不放大费用分组配额;数量和整段累计执行耗时都归入 created_at 的本地日,不按执行区间拆分。创建日期缺失时单独列为日期不明,不进入每日或范围总数;缺失耗时保留 null 和不完整计数。统计页同时展示 token、任务数量及耗时,并保留按项目着色的每日堆叠费用柱状图、可聚焦色块的当日金额和占比、项目汇总及每日明细。金额与占比只针对已计价记录,未知请求单独提示,历史未记录的数据不推算。这里只覆盖经控制面代理的模型费用,不包含外部执行端自行调用的模型或项目容器内其他服务的费用。

项目环境生命周期

新增仓库默认启用,后台登记一个环境;创建与周期对账均按仓库 ID 幂等,不随 Issue 或 PR 结束而删除。启动和后续命令复用同一容器及卷。每个仓库仍只有一台虚拟电脑,不为单个任务另开容器,但一台电脑可以同时运行多个任务(并发度见「检视与开发数据流」):manager 让同一仓库最多 N 个执行请求并行,N 由控制面按项目并发度下发,调低时不少于正在运行的任务数;启动、停止、重置、删除和配置独占这台电脑,与执行请求按到达顺序排队,不会被持续到来的执行请求饿死。电脑上有执行请求时状态为 busy,busy 本身不拒绝新的执行请求;不同仓库可并行。CPU、内存、进程数和 /tmp 仍是这台电脑的一份限额,由同时运行的任务共用,不随并发度放大。项目没有自己设置的资源跟随 manager 保存的全局默认值(超级管理员在全局设置里修改,内置为 2 CPU、4096 MiB、1024 个进程、1024 MiB /tmp);manager 记下当前容器创建时用的资源,默认值改变后在详情里报告 resources_pending,控制面对账时只在这台电脑没有任务认领、也没有其他待完成操作时记下一次 refresh 操作,engine 在它完成前不在这台电脑上领取新任务,manager 收到 refresh 后按当前规格重建不一致的容器,工作卷和代次不变。升级到可配置默认值时,manager 和控制面各把已保存规格里等于内置默认值的资源删除一次,让这些项目跟随全局默认。命令结束后容器继续运行,不再重启:默认清理命令的进程组,再由 runner 结束这个任务残留的进程(另建会话的守护进程也会被结束),其他任务的进程不受影响。runner 按进程环境里的 BOT_WORKSPACE_ID 标记、发起它的 runner 请求或 agent、所在的任务目录或父进程判断进程属于哪个任务。任务结束时结束自己的全部进程;电脑上最后一个结束的任务再清理除 init、空闲进程和 runner 以外的所有残留进程(几个任务同时结束时,已进入收尾的任务不算在内,所以其中最后一个仍会清理),清理期间控制面不在这台电脑上启动新任务;清理失败时才回退为重启容器。这次重启在项目锁内独占进行:先等正在执行的请求结束,之后到达的请求排在它后面,所以没有请求会在容器被换掉的中途执行;重启结束了电脑上各任务的进程,这些任务重新开始一次尝试,电脑保持就绪,工作卷和代次不变。某个任务的执行请求失败时,只结束该任务的进程,电脑和其他任务继续运行,连这一步也失败才停止整台电脑。命令可声明 keep_background,这时它启动的后台进程保留给同一任务后续的命令使用,任务结束时统一结束,其他任务的命令不会结束它们。容器以 Docker init 运行以回收僵尸进程;批准镜像、init 或网络策略变化后,下次 provision 时原地重建容器,卷和 generation 不变。

停止会将仓库 enabled 设为 false,停容器并保留卷;再次启动复用原代次和数据。签名可信的 App 卸载/暂停事件按账号和所有者范围停用,移除仓库事件按账号和仓库 ID 停用;这些意图随投递事务保存,再由后台停止环境,不在 webhook 响应链路调用 Docker。全量同步发现仓库不再安装时只标记“已移出安装”,不自动改变启用状态。停止、重置或删除会先中断这台电脑上所有正在执行的长命令。

重置先停止所有旧代容器并确认不再运行,然后增加 generation、保存旧卷,创建新代容器、新卷和新网络。失败进入 reset_failed,禁止普通启动旧环境,必须显式重试重置。删除虚拟电脑只删除受管容器和网络,保留工作卷和笔记卷;停用和卸载不会删除资源。旧代容器始终停止,旧卷仅保留待备份/清理,不挂到新项目环境。

manager 重启会先停止不确定的执行,标记未完成操作 interrupted,再用同一代容器和卷检查 runner/journal 后恢复 ready;重置中断则保持 reset_failed。运行期发现容器重启或退出同样重新恢复,不以 Docker running 代替 ready:空闲电脑由周期检查恢复;执行请求发现容器已被 manager 以外的原因重启或停止时,这个请求失败(recovery_required),电脑按上面的方式独占重启,不再整台停下并标记失败。已启用项目的电脑处于 failed 时,控制面对账会自动再启动它,两次尝试之间从 30 秒起每次翻倍、最长 30 分钟,启动成功后重新计时;重置失败(reset_failed)仍需人工重置。操作 ID 持久化去重,代次检查阻止旧请求写新环境,状态 revision 防止旧响应覆盖新状态。控制面保存操作意图并以原 ID 重试丢失响应,不自动重复重置。

当前 runner 为无网络监听的一次性固定执行入口:manager 通过 Docker exec 发送校验后的请求,返回 JSON 与持久 journal,调用者不能指定 exec argv 或用户。支持工作区相对文件读取/写入和 shell 命令,普通工作流未指定 timeout_seconds 时等待命令结束;观察与独立 QA 默认 120 秒,角色开发与请求执行默认 180 秒,显式超时由 BOT_COMMAND_TIMEOUT_MAX_SECONDS 限制(默认 600 秒)。keep_background 让服务和 watcher 提前返回,后续日志保存在 log_path;命令超时只回收本次操作,runner 健康时其他并发任务继续。停止或重置虚拟电脑会中断整台电脑的任务。单次写入 48 KiB、读取 1 MiB;命令完整执行并保存完整输出,超过 1 MiB 时返回首尾预览与可分页文件,详见执行运行时。命令运行中输出同步写入 journal 旁的临时文件,manager 的只读 output 接口按字节偏移读取,不占用项目锁;命令完成后该文件删除,完整结果保存在 journal。journal 每次调用一条记录,只在调用后不久有用(重复的操作 ID 取回首次结果、读取刚结束命令的输出),所以 manager 在每次 provision 后和运行中每 6 小时在后台、不占项目锁地清理一次:删除超过 1 天的记录,仍记为运行中的命令和它的输出保留 7 天。runner 的健康检查不读 journal,记录再多也不拖慢启动。项目运行用户为 10001,根文件系统只读,工作卷可写,CPU、内存、进程数和 /tmp 默认为 2 核、4096 MB、1024、1024 MB,超级管理员可按仓库在 manager 允许的范围内修改。内存上限之外不使用宿主的 swap:内存用满时由内核结束占用最多的进程,不会因换出到 swap 而变得很慢,宿主有没有 swap 表现都一样;/tmp 是计入内存的限额 tmpfs,和工作卷一样可以运行程序(例如在 /tmp 建的 Python 虚拟环境、下载的工具)。批准的项目镜像自带 Node.js 22(npm、corepack 的 pnpm/yarn)、Python 3.11(pip、venv、uv)、gcc/g++/make、git、git-lfs、curl、wget、jq、ripgrep、sqlite3、zip/unzip、Debian 的 Chromium 及 fonts-liberation/fonts-noto-cjk(经 /usr/local/bin/bot-chromium 启动,BOT_BROWSER_EXECUTABLE 指向它),镜像自带包清单在 /opt/bot/image-packages。仓库需要的系统软件包由 manager 以批准镜像为底、用固定的 apt 命令构建派生镜像(按底层镜像和包集合缓存,root 只出现在构建阶段);非机密环境变量注入容器并传给每条命令;初始化脚本以项目用户在 /workspace 运行,HOME=/workspace/home 在工作卷中,~/.local/bin、~/.cargo/bin、~/.npm-global/bin 在 PATH 上,脚本或代次变化时重新运行,结果和输出在虚拟电脑页可见。Git 操作在容器内执行。任务工具支持隔离工作目录、分块文件与 Git 候选;上游 API 认证始终由控制面代理。执行入口仅供内部控制面和验收调用,管理页面没有通用终端。

群聊助手和管理助手不使用项目电脑:manager 按对话归属(群按群、私信按人)为它们创建无网络的短时助手电脑,回合结束后空闲 5 分钟回收,持久 HOME 按归属和代次存放在 assistant-homes 卷,控制面负责归属、授权围栏、HOME 代次、容量和保留,细节见服务角色 · 助手电脑。

每个仓库的独立稳定笔记卷读写挂在 /workspace/project-notes,任务通过 ../notes/ 使用;停机、重建、禁用和重置代次后保留,删除项目时随环境删除笔记卷,旧工作卷仍保留。项目页由 manager 直接读写同一份卷内文件,电脑未启动时也能编辑,无需启动项目或辅助容器。

检视与开发数据流

在仓库 policy 中选择 model_id,把能力上限 capability_ceiling 设为 comment(检视),需要自动实现时设为 develop(见项目能力上限),建议设置可信的 test_command。Issue 在 opened 时检视一次;PR 在 opened、ready_for_review、synchronize 且非草稿时检视当前 head。这些事件先交给项目 Manager 分派,由它决定检视、续接还是不处理;三类事件可在「项目设置 → 监听与触发」中分别关闭(关闭 PR 新提交后,bot PR 的自动跟进也随之停止)。

打开后的更新也会再检视一次,两个开关默认打开:「Issue 的标题或正文被修改、有新评论后」对应 issues.edited(changes 含 title 或 body)和 issue_comment.created;「PR 的标题或描述被修改、有新评论、提交检视或回复检视意见后」对应 pull_request.edited、PR 对话里的 issue_comment.created、pull_request_review_comment.created,以及有正文或要求修改的 pull_request_review.submitted(GitHub 给每条行内回复包的无正文 review 由对应的评论事件处理)。Issue 更新还要求 Issue 检视开启,PR 讨论还要求 PR 检视开启;草稿、已关闭对象和 bot 自己写的内容不触发。评论、行内回复和提交的检视只在发言人是对象作者,或 author_association 为 OWNER、MEMBER、COLLABORATOR 时触发,公开仓库里的其他人发言不会消耗模型额度;修改标题或正文在 GitHub 上本来就只有作者和有仓库权限的人能做。机器人账号以普通用户身份发言,所以按正文里的 <!-- dept-bot 标记识别,App 发言另按 sender.type=Bot 识别;bot 账号修改自己创建的 PR 描述也不触发。例外是 bot 自己创建的 PR:其他 App(sender.type=Bot,且不是这个 PR 的作者,也就是不是本 bot)在上面的评论、行内评论和提交的检视也触发再次检视,触发记录带 actor_type: Bot,由检视判断是否采纳。同一仓库、同一检视类型(review.issue/review.pr)、同一编号上的更新进入当前检视。尚未发出第一次模型请求时,包括排队、重试等待、等待配置/环境和准备阶段,触发记录全部并入,不设 20 条截断;开始前重新读取 GitHub 当前标题、完整正文和全部讨论。模型已经开始时,不取消任务,不增加另一条任务,也不打断当前模型 HTTP 请求或工具调用。Pi 在每一回合的工具结果写入历史后,通过控制面邮箱检查持久更新收件箱;控制面同时刷新 ../context/ 的对象与讨论文件,再按投递顺序补入用户消息,包含操作者、改动内容和新正文。模型和工具调用费用仍记在当前任务上。并发度大于 1、同一对象存在多条执行中的检视时,选择最近认领开始的那条,不取消其他检视。每次更新按 repositoryId:kind:number:update:<投递记录> 去重。任务上下文带 trigger(原因、操作者、改动前的标题或正文、评论或检视链接),评论类触发同时带 trigger_comment;模型先回应这次更新,再对照当前状态核对之前的发现,不重复已解决的问题。PR 推送新提交(pull_request.synchronize)也是一种更新,进入当前检视,不再另建检视、也不把旧检视作废(#770),见下文「PR 新提交」。已经发布的检视同样接收更新,作为同一任务的下一轮继续,见下文「检视的下一轮」。未启用检视的仓库只归档,草稿不建检视任务。投递去重和任务逻辑去重独立;归档、去重与入队在同一事务提交后才确认成功。

打开的 Issue 或 PR 对话中新发布的评论(issue_comment.created)提到配置名字时,触发一次检视或补入当前检视。BOT_MENTION_NAMES 未设置时为 bot,agent-ci-infra-bot;设置后按逗号分隔替换默认名字,忽略大小写和名字两侧空白,整个值为 off 时关闭评论触发。匹配纯文本 @名字,无需该 GitHub 账号存在或属于本部署,也不查询用户接口;@ 前须为开头或非字母数字,名字后不能紧跟字母、数字或连字符,因此 @bot-extra 不匹配 bot。提到名字的评论不受上面的更新开关限制,也不按评论人过滤:上面「只在发言人是对象作者或仓库成员时触发」只适用于更新类评论,任何人(包括公开仓库里的仓库外人员)提到名字都会交给 Manager 分派一次,由它按提示词决定怎样回应;Issue 上的提到也提供「开发 Issue」,但开始开发要有 Manager 写明、控制面核对的依据(#815),外人的评论不算依据。除此之外和普通更新一样:开始前并入、开始后在回合之间补用户消息;对象上没有可续接的检视才新建任务。Bot 发送的评论、评论的编辑、删除和重新打开不按提到触发(不提到名字的新评论按上面的更新规则处理)。评论遵守 Issue/PR 的检视开关,PR 评论读取当前 head,草稿或已关闭对象不入队。每条评论按 repositoryId:kind:number:comment:commentId 去重,PR 的 head_sha 仍为当前 40 位 SHA;不同评论可以再次检视同一 head,原有 opened/head 去重键不变。任务保留触发评论的 ID、正文和链接,并把它作为 trigger_comment 交给检视上下文。

检视恢复的只是消息历史:从控制面 review_sessions 表读取同一对象最近一次发布成功时保存的会话,不读取登录用的 sessions。会话只在检视发布成功时保存,所以保存它的任务之后续跑下一轮、下一轮失败或被停掉,它仍是来源;失败、取消和 superseded 的执行本身不保存会话。自动重试和手动重试使用空会话,并在第一次模型请求前重读最新讨论。例外是新提交时工作区无法原地移动、改在新工作区重新准备的那一次,以及已发布检视的下一轮(见下文),它们和第一次一样延续上次发布的会话。系统提示、规则、skills、工具、检出和 ../notes/ 每次按当前任务加载;延续的第一条内容写明当前 head,并提醒历史代码结论可能属于旧版本。会话不依赖容器内存或任务目录,容器重建与三天任务目录清理不会删除控制面会话;对象关闭后再保留 15 天,期间重开可延续,超过期限重开从空会话开始,项目删除时一并删除。检出是电脑上共享的 git worktree(#769),在任务第一次用到仓库文件时绑定:任务的主控(Manager)可以在委派之前先替任务选或不用;任务固定下来的角色配置没有让主控安排这类任务时(角色团队没打开,或这类入口没交给主控,例如按旧配置运行的历史任务),由执行任务的 agent 自己选。没人选时检视拿同一提交上没人占着、核对无改动的 worktree,规则见部署细节。项目笔记独立保留、只向前更新;开发任务不加载检视会话,也不接收检视更新。

Pi 启用会话压缩,控制面保存压缩后的消息投影,不恢复旧系统提示或工具配置。历史通过分块邮箱传输,检查点至多 32 MiB;发往模型的单次请求仍须同时满足 2 MiB 和 128k 上下文上限(包含输出预留),压缩费用记在本次任务。超限的请求由 runner 按上下文溢出回给 Pi,Pi 压缩一次再重试(见 agent-runtime.md);压缩后仍超限则本次失败,重试丢弃这次历史,使用空会话。

finish_review 暂存当前结果,Pi 保持可继续状态。在 GitHub 第一次写入之前,控制面重新检查更新收件箱;若有新更新,则补回同一会话,允许模型再次调用 finish_review,只发布最后一版。一旦总结评论、行内 review 或标签的第一次写入发出,这次发布按原 outbox 契约完成,不因讨论更新而取消;之后的更新仍并入同一任务,发布完成、执行释放认领后,任务作为下一轮继续(#770,见下文「检视的下一轮」)。Manager 另建的同对象检视仍等待当前发布完成后才开始。关闭、转为草稿以及 bot 自己的评论的处理保持原约定。

PR 新提交(#770)不再让正在做的任务作废。推送事件交给 Manager 时,同一 PR 上的检视作为续接选项:排队、执行中或发布中的检视,没有这些时是最近一次已发布的检视;这时不提供「检视 PR」新建选项,同一次推送不会有两条检视。检视在 validate() 发现 head 变化时:准备阶段直接取新 head;之后在工作区里没有工具运行时(回合之间、模型阶段开始前、发布前)把同一个 git worktree 原地移到新 head(runner 的 workspace_advance),目录、未跟踪文件和构建产物保留,已跟踪文件的改动和会被新提交覆盖的未跟踪文件先存成 ../context/saved-changes-<旧 head>.patch;随后刷新 files.json 和讨论文件,记一条 head_moved 日志,并作为更新补入会话:写明新旧 head、两者之间的提交和文件(GitHub compare,最多 50 个提交、300 个文件)、推送人、改动保存在哪,以及可用的 git log/git diff 命令。同一回合里多次推送合成一次。发布前发现新 head 时同样先移过去,再回到同一会话改结论。工作区不是 worktree(Git 缓存不可用时的文件拷贝)、或这个 worktree 还有别的未结束任务占着(#769),无法原地移动时,同一任务以 pull_request_head_changed 回到排队,在新工作区按新 head 重新准备。已经开始发布的检视按它检视的 head 发完,之后的推送由它的下一轮检视。检视结果的 reviewed_sha 是最后的 head,reviewed_heads 列出它读过的各个 head。开发任务遇到别人推送的新提交时停下来(needs_replan,不计入失败重试),工作区先存为进度检查点,由 Manager 决定怎样继续;下一次准备取新 head,旧 head 上的工作不覆盖到新 head 上,而是作为 earlier_work 告诉 agent 提交位置。只回复的任务按它读到的 head 回答。superseded 只留给人停掉的任务。

检视的下一轮(#770):已发布的检视不再因为新的评论、修改、标签或推送另建任务。对象上没有排队、执行中或发布中的检视时,Manager 收到同一对象最近一次已发布的检视作为续接选项;续接后同一任务作为下一轮重新排队,轮次记在任务输入的 round(缺省为 1)。发布期间并入的更新在执行释放认领后开始下一轮;控制面重启时,补上因停机没来得及开始的下一轮。下一轮的处理:

开发任务不按轮续接:bot PR 上的评论和检视仍由 PR 检视转成修订任务,Issue 上的更新由 Issue 检视回答。

新建 App 的 manifest 订阅 issues、pull_request、issue_comment、pull_request_review、pull_request_review_comment、check_run、status,以及用于组织成员权限核验的 organization,不包含由 GitHub 自动投递的 installation 或 installation_repositories。已创建的 App 不会随代码更新自动新增订阅:App 所有者需要在 GitHub App 的 Permissions & events 设置中勾选 Issue comment、Pull request review、Pull request review comment(检视跟进)以及 Check run、Status(控制台检查状态推送)并保存;用令牌登记仓库 webhook 的部署也需要把对应事件加入订阅。

后台按项目并发度认领任务。全局设置给出默认并发度,未设置时为 1,所以不改设置时同一仓库仍一次只运行一个任务;项目可以在「机器配置」里覆盖,留空时用全局默认,两者都是 1–32 的整数,项目值就是这台电脑同时运行的任务数。超级管理员在「全局设置」改默认值;项目管理员只能改自己项目的覆盖值,不能读写全局设置。超出并发度的任务按创建顺序继续排队,不会因此失败。每个任务持有自己的认领(task_claims),检查点只核对本任务的认领,并使用自己的 /workspace/tasks/<workspace_id>;文件工具和 runner 写入只落在本任务的检出内(repo 链接到共享 worktree 时按 worktree 的真实目录判断,repo 指向 /workspace/worktrees/<id> 以外的位置视为工作区被替换),越界路径和指向检出外的符号链接被拒绝,各任务的命令都从自己的仓库目录开始运行。命令仍以同一项目用户运行,共用 HOME=/workspace/home。停止、重置、代次变化和禁用项目仍会中止这台电脑上所有进行中的任务;修改电脑配置会重建容器,正在运行的任务被中断后重新准备。任务拉取本仓 Issue/PR、讨论、完整分页 diff 与固定 SHA 的代码材料。已保存模型只收到这个项目的上下文,并可调用 read_file、write_file、run_command 等受任务约束的工具。仓库材料属于不可信输入,不能修改权限、镜像、发布目标或认证。单个任务不限模型调用次数,也没有总时长上限,禁用项目或停止虚拟电脑可以中止正在执行的任务;模型调用 run_command 时命令不限时长,可选 timeout_seconds 为可能卡住的命令自设超时,服务和监视进程用 keep_background 放到后台;仓库测试验证同样不限时长;任务上下文包含虚拟电脑的资源、工具链、额外软件包和环境变量名;临时调用失败先短退避,同码连续 5 次后进入每任务 8 小时重试周期,配置条件尚未就绪时单独等待。

每个 Issue 或 PR 只有一条总结讨论评论,包含总结、非行内 finding 和检视 SHA:第一次检视发布它,之后的检视(新提交、更新、提到触发)都改写这条评论,不再新发;评论开头写明这是第几次检视、更新时间、检视的提交,以及回应的是谁的评论(写成 @某人,GitHub 会通知对方)。这条评论由 review_summaries 记录;它出现之前检视过的对象沿用最早那次检视的总结评论;被人删除时重新发一条,之后改写新的这条。改写 GitHub 不另外通知订阅者,行内 finding 仍随新的行内 Review 发出。需要人处理的事项(模型标了 requires_human_decision 的 finding,用 human_action 一句话写明要决定或要做什么;PR 改了 bot 自身行为文件;需求待人确认)在评论开头用 [!IMPORTANT] 提示一次,并在评论末尾单独列出,对应的行内评论附链接;这些 finding 本身也标「需要人工处理」。用语跟随仓库检视语言,auto 时跟随总结所用语言。PR 再次检视时,模型把当前 head 已修复的、本 bot 之前的顶层行内评论 ID 写进 resolved_comments;控制面只接受本 bot 发表、不是回复、且发表在更早提交上的评论(即作者之后改过代码),经 GraphQL resolveReviewThread 关闭对应讨论串,并在总结评论里列出关闭了哪些。GitHub 只允许有 Contents 写权限的 App 令牌关闭讨论串,检视任务的令牌只有 Contents 读,所以控制面为这一步单独签发一个只含本仓库、带 contents: write 的临时令牌,用完立即吊销;安装没有授予 Contents 写(只开了检视权限)时 GitHub 返回 422,讨论串保持打开。GitHub 拒绝时不影响检视发布,原因写进任务日志的 review_threads_unresolved。模型认为仍然成立的旧行内意见用 comment_id 指回原评论,不再重复发行内评论,总结评论里列为「之前的行内意见仍未解决」并附链接。Issue 只用普通评论。PR 每条 finding 由模型选择普通评论或行内评论并给出理由,服务端用真实 diff 校验 path/line/side;缺少可核对位置时转普通评论,不猜行号。行内 Review 的 event 恒为 COMMENT,模型不能选择批准或请求变更,没有自动合并接口。发布前重新检查 head,还没开始发布的检视先转到新 head 再改结论;评论写明实际检视 SHA,检视途中换过 head 时另列之前读过的 head,Review 和每条行内评论的 GitHub ID 保存到任务回执。标签都在总结评论发布成功后由控制面用同一安装令牌一次加上,重复执行不会重复添加:

模型不调用标签接口,也不能让 GitHub 新建标签。

仓库的能力上限为 develop 时,Issue 的事件(打开、编辑、评论、提到 bot、有人加开发标签,以及标签在时每次 Issue 检视发布)都把「开发 Issue」作为可以新建的工作交给项目 Manager。开发别人开的 Issue 要有依据(#815):有人加的开发标签(项目设置的 development_label,默认 bot-develop)、triage 以上权限的维护者在评论里的要求,或 Manager 提示词里的规则;控制面在 create_task 时核对,依据记在 task_development_basis,不成立时拒绝并把原因记在事件上。Manager 根据最近一次检视的结论和建议、Issue、指派人和已有任务判断现在能不能开发;不开发时新建检视,在 Issue 上回复缺什么。开发按 Manager 简要说明的目标和验收标准进行。以标签为依据的开发在发布前再次确认标签仍在。同一 Issue 同时只有一个开发任务。在同一项目容器的新任务工作目录中修改代码,模型准备好时调用 create_pull_request:控制面固定工作树快照,项目策略配置了非空 test_command 时在快照之后运行它;没有配置时不运行策略测试,模型报告的已执行测试命令只写进 PR 说明,控制面不替它运行。策略测试失败或超时时工具返回 validation_failed,不推分支、不开 PR,模型可以修改后再次调用。成功后只发布调用时固定的快照(测试生成的文件不进入 PR),由控制面发布唯一 bot/issue-... 分支,并创建 PR、回填链接。默认分支从 GitHub 元数据或仓库 policy 获取,不写死。

PR 的标签由仓库自己的规则决定(#845):仓库的贡献指南或 skill(例如 create-github-pr 要求选一个 release:* 类别)告诉 agent 选哪个,create_pull_request(以及角色团队和普通任务的软件交付 submit_delivery)可以带可选的 labels。规则与检视的分类标签相同(src/review/labels.ts):每个标签必须是仓库已有的,不能是保留标签(agent/、pr/、gate/ 开头,blocker、priority/critical),也不能是 bot 自己的检视标签和开发标签,最多 8 个。不满足时在发布任何分支之前以工具错误 pull_request_labels_refused 返回,列出每个被拒的标签和原因,agent 改正后再调用。PR 创建或更新之后,控制面对照仓库和 PR 当前的标签再筛一次后加上:已有的不重复加,人在同一类(type/… 这类前缀)已经选过的不覆盖;GitHub 拒绝加标签时只在任务日志记 pr_labels 和错误码,不影响已发布的 PR。平台代码和提示词不针对任何仓库。

webhook 不直接创建开发任务,开发只由 Manager 按上述依据创建。同一 Issue 已有排队、重试、等待配置/环境/权限/PR head/发布或执行中的 development.issue 时,不再创建第二条开发任务。PR 对话里的 @ 和其他更新只再次检视当前 head,不直接启动开发或推送提交;入队后 head 变化时,这条评论检视转到新 head,并因此同时算作这个 head 的检视。bot 自己创建的 PR 例外见下一段:检视采纳的修改要求会启动一次修订。

别人的 PR 只检视,不产生向作者分支提交的任务;分支名或机器人名称不能代替归属记录。由本系统创建的 PR 保存不可变 PR ID、作者、head 仓库、分支和发布 SHA,只有这些身份仍匹配、策略允许且确有修改项时才在原分支跟进。跟进有三种来源:

修订任务的上下文带 revision_requests(作者、类型、链接和评论原文),只有因这些要求而修订时,推送后不计入修订轮数。同一个 PR 同时只有一个修订任务;已有修订在排队或执行时,新的要求记为待处理(pending),任务日志记 revision_deferred,之后对这个 PR 的检视会把它们放进 discussion_requests 再采纳。不另开 PR,不强推,不自动合并。

仓库只读探索

检视、开发与 CI 观察共享 RepositoryExplorer,通过 github_read、github_search 和 read_job_log 读取当前接入仓库的代码、其他 Issue/PR、讨论和相关 Actions。触发对象是分析起点,不是全部可读上下文。CI 通过控制面执行这些工具;Pi 使用任务邮箱传递工具请求与分块结果。读取路径、HTTP GET 方法和搜索仓库由控制面校验,内容及日志在返回模型前脱敏。具体工具和触发目标边界见共享 Agent 后端。

任务只读令牌

模型调用 github_read_token 时,runner 在任务邮箱写入请求,控制面轮询到后为本仓库签发一个 GitHub App 安装令牌:repository_ids 只含当前仓库,权限只取 metadata、contents、issues、pull_requests、actions、checks、statuses 中安装已授予的项,并一律降为 read;签发结果里只要有任何一项不是 read 就拒绝。机器人账号只有一个能写的长期 Token,不能派生更窄的令牌,所以不提供只读令牌,模型会收到 github_app_required。

令牌经 manager 直接交给 runner,不写入 task_tools 或任务日志;runner 只把它放进该任务之后的 run_command 环境变量 GH_TOKEN、GITHUB_TOKEN,并在命令输出中替换为 [REDACTED]。模型拿到的工具结果只有变量名、仓库、权限和到期时间,看不到令牌本身。令牌加入任务的脱敏表,发往模型服务商的请求也会先脱敏。同一任务最多签发 10 次;模型阶段结束(完成、失败或被中止)时,控制面逐个调用 DELETE /installation/token 撤销。

GitHub 安装令牌只有一小时,而一次检视常常跑得更久。控制面的每个 GitHub App 客户端(任务自身、只读令牌、github_write 等)在令牌剩余不足 15 分钟时先重新签发再发请求,权限与原令牌相同;GitHub 对 bot 自己签发的安装令牌回 401(过期或被吊销)时,重新签发并重试一次,第二次仍是 401 才进入 waiting_permission,诊断写明两枚令牌由哪个客户端在何时签发、何时到期、是否被 bot 吊销,不含令牌值。runner 不信任自己持有的令牌:模型每次调用 github_read_token 都向控制面重新换取,令牌剩余不足 10 分钟或检视会话进入下一轮(上一轮结束时控制面已撤销它)时,在下一条命令前先换取。

令牌和 PR 检视时运行的仓库测试处在同一台虚拟电脑里,测试代码能读到这些环境变量,所以令牌被设计成只读、只覆盖本仓库,并在模型阶段结束时撤销;GitHub 安装令牌最长有效一小时。评论、标签、行内检视、分支和 PR 仍只由控制面用自己的令牌发布。读取 Actions 和检查状态需要 App 授予 Actions、Checks、Commit statuses 权限;接入向导生成的 manifest 申请 Actions、Checks、Commit statuses 写(写权限留给控制面发布 commit status、检查结果和重跑 CI;任务令牌仍一律降为读)。之前创建的 App 需要在 GitHub 上补加这三项权限,并由安装方同意。检视和开发的令牌刻意不申请 workflows:开发任务改到 .github/workflows/ 时 GitHub 会拒绝发布。App 本身可以为一键接入获得 Workflows,但它只出现在接入专用的令牌里(见下文「一键接入」),检视、开发和只读令牌都不申请。也不申请 administration、secrets、security_events、vulnerability_alerts、secret_scanning_alerts:任务令牌对 PR 代码可见,不能让它读到仓库设置、密钥或未公开的漏洞告警。

一键接入与公共看板托管

仓库列表直接提供「看板」开关,与检视、开发开关并列;无需启动项目。公开仓默认开启,私有仓默认关闭。超管可以为任意已安装仓库保存开启或关闭状态,开关同时控制单仓页面与公共 Dashboard 汇总。关闭后立即停止对外提供旧快照,webhook 和后台采集也不能重新开启它。

公共 Dashboard 位于已验证的公网地址 /dashboard/,单仓看板位于 /boards/<owner>/<repo>/(小写),看板目录位于 /boards/。三者和控制台由同一个业务端口 8791 提供,但不需要控制台登录,使用自己的内容安全策略;控制台的「任务看板」页面是另一页面,仍需登录。公共地址沿用安装向导验证的 onboarding.public.origin。

开关设置保存在 public_board_settings,按仓库持久化,不随安装同步或重启重置。已有明确启用的私有仓授权迁移为开启,已经保存的关闭状态不会被旧授权重新打开。未保存选择的仓库在可见性变化后按新可见性使用默认值;已经保存的开或关保持不变,直到管理员再次拨动。开启私有仓会使其看板数据无需登录即可访问。卸载或删除后,公开路由立即排除该仓。门禁 PR 不改变开关设置。

验签通过且未重复的 webhook 在同一数据库事务中递增该仓的采集代数,包括已安装但未启动的仓库。后台持久队列合并投递、按仓采集、失败退避重试;新投递在采集过程中到达会保留为下一代任务。启动时补齐公开仓初始采集,重启后继续未完成的代数。采集失败保留上一份有效快照,新快照校验仓库身份后整体切换。聚合读取按仓隔离:/dashboard/data/index.json、/dashboard/data/config.json 与 /boards/ 中任何一个仓库的导出文件缺失或损坏,只把该仓记入 unavailable(reason 为 read_failed 或 invalid_json,不回显内部路径),健康仓照常返回 200;/boards/ 仍列出该仓,生成时间为 null。所有公开请求重新核对安装状态和私有仓授权,内部 checkpoint、源码及凭据没有公开路由。

Dashboard React 页面、单仓静态页面、社区统计采集器和增量采集器随 bot 一起构建,作为本仓自有实现维护,不再跟随上游模板。看板只展示任何仓库都有的 GitHub 原生数据(#938):Dashboard 是社区统计(PR、Issue、贡献者、成长、版本),单仓看板是 Issue、PR、每个 workflow 和 job 的运行历史(成功率、耗时中位数和 P90、失败最多的 job)及发版,以及定时 workflow 每次运行报告的结构化结果:依次读取该运行检查套件里各检查运行输出中的 Markdown 表格、运行产物里的 JUnit XML 和简单 JSON({"metrics": [{"name", "value", "unit"}]}),都没有时只用 job 的结论和耗时,按运行先后画趋势图(Actions 的 step summary 不经 API 提供,不能读取)。定时 workflow 指有定时触发运行的 workflow,它在默认分支上的定时和手动运行都算;每次运行只读一次,解析不写死任何仓库或产物名称。不按任何 CI 约定打分,门禁页、lane、覆盖率、E2E 记录和模板示例页已删除。升级后第一次采集删除旧快照里的 gate.json 和 E2E 页面、私有状态里的标签目录与覆盖率存储,并把运行记录里只为这些视图保存的字段(测试报告、覆盖率等)去掉。Python 采集器只用标准库。快照、历史与内部增量状态保存在数据库旁的 public-boards/ 数据目录,容器镜像包含 Python 3 和时区数据。BOT_DASHBOARD_REPO 与 GitHub Pages 不再参与托管或接入。

操作 目标 权限
改 CI 的 bot PR(项目管理员确认为 CI 改动的开发任务) 源仓 推送 bot 分支时 contents 写、issues 写、pull_requests 写、workflows 写,按安装实际授权裁剪;其他推送和 github_write 都没有 workflows
看板采集 源仓 contents、issues、pull_requests、actions、checks、metadata 只读,按安装实际授权裁剪;没有 checks 时定时运行的结果只从产物读取
看板开关 bot 本地 控制台超管;不向 GitHub 写配置

每次采集使用源仓自己的只读安装令牌并在结束时撤销,不再需要外部 dashboard 的 App 安装或 PRIVATE_SOURCE_TOKEN。bot 不再生成门禁文件:CI 改动由开发任务按仓库自己的情况修改 workflow,以 bot PR 交付,人合并后才生效(见接入说明)。

代码快照与发布

控制面在自己的数据卷上为每个已启用仓库保留一份 bare mirror(/data/git-cache/<仓库 ID>.git,BOT_GIT_CACHE_DIR 可改位置),任务不必每次从 GitHub 重新下载整个仓库。任务准备时先把镜像更新到这次要检视或开发的提交,PR 任务还包括读取规则的默认分支提交:镜像里已有这些提交就不访问 GitHub;缺少时按 SHA git fetch 这些提交,GitHub 不按 SHA 提供时改取对应的 PR head 或分支 ref,而不是只更新默认分支。同一镜像的更新逐个进行;拉到的每个提交固定在 refs/bot/commits/<sha> 下,后续更新和维护不会删掉。安装令牌只作为一次性 HTTP 头经这次 fetch 的进程环境传给 git,只对 GitHub 返回的 clone 地址所在源生效,不写进 remote URL、镜像配置、FETCH_HEAD 或日志,也不进入项目容器;github_read_token 仍是只读,语义不变。仓库 skill(.agents/skills/)随后从镜像在固定提交上读取;.bot/ 文件只列出名字,不读取内容。工作区优先是一个 git worktree:每台项目电脑在工作卷里有一份自己的 git 对象库(/workspace/git/repo.git),控制面先问它已有哪些提交(git_have),再从镜像打一个只含缺少部分的 pack(git pack-objects --revs,第一次是整个历史,之后通常只有新提交),按约 45 KB 分块直接传给电脑(git_pack,不写入任务记录),电脑用 git index-pack 校验并收下,把提交固定在 refs/bot/commits/<sha> 下(git_import);任务在第一次用到仓库文件时才得到一个 git worktree(#769),任务的主控(Manager)可以在委派之前先用 list_workspaces、use_workspace、create_workspace 替任务选(没有角色团队的任务由执行 agent 自己选):worktree 放在 /workspace/worktrees/<id>,任务目录里的 repo 是指向它的链接。没人选时,只读的任务(检视、事件任务)先取同一提交上没有未结束任务占着、runner 核对过 HEAD、tree 且没有改动的 worktree(workspace_worktree_bind),被忽略的依赖和构建产物随 worktree 留给下一个任务;会写的任务和找不到可用 worktree 的读者 git worktree add --detach 一个新的并核对 tree(workspace_worktree_create)。观察者角色和独立 QA 不再复制写者的目录:写者的候选提交是在它的 worktree 里做的,本来就在电脑的对象库里,所以它们各用一个自己的任务目录,按同样的规则拿一个为读而建、停在候选提交上的 worktree,并带上写者目录里 ../context/ 的副本;同时运行的读者各拿各的,一个读者结束后它的 worktree 交给下一个读者。写者是文件拷贝时仍从写者目录 git clone --shared 一份。登记、占用和清理规则见部署细节。PR 任务同时带上 PR 的 base 提交,agent 能用 git diff <base>...<head>、git log 自己查看改动;工作区里没有 remote 和凭据,令牌不进电脑。文件不再经控制面逐个复制,控制面改为在镜像里用 git grep 检查文件是否含有本任务的凭据,含有时任务停下(credential_in_repository)。子模块条目留在 tree 里但不检出,开发结果也不把它当作文件。任务目录和 worktree 由控制面按用过它们的任务的状态定时删除(规则见部署细节),删除 worktree 时一并清理对象库里的登记;电脑的定期维护只删除中断传输留下的 pack、清理 worktree 登记并按需整理对象库。镜像不可用(fetch 失败、仓库没有 clone 地址、拉取后读不出等)、电脑上的这条路走不通时,回到下面原来的方式:从镜像或 Git 数据 API 逐个读取文件,按文件经 manager 以约 30 KB 分块写进任务自己的新工作目录,再构建只有这一个提交的本地 Git 快照,任务不会因此失败,日志写明原因。文件数超过 2000、单文件超过 1 MiB、合计超过 32 MiB 都不再使准备失败;递归 tree 被截断时丢弃不完整列表,改为逐目录非递归列举。子模块不克隆,子模块和不支持的 Git mode 不下载,日志记录路径和 mode;回到 Git 数据 API 读取时,GitHub blob API 支持约 100 MB 以内的 blob,接口明确因文件过大拒绝返回时记录路径、大小和 HTTP 状态并跳过,coverage 列出跳过数量。权限错误、限流和普通 HTTP 错误仍按原有故障处理。跳过条目保留在上游,发布时沿用源 tree 并校验合并后的完整 tree,避免误删。复制方式下控制面一次只处理一个文件的内容,快照 blob 下载不受普通 GitHub 响应的 48 MiB 限制;二进制和符号链接按 Git 对象处理,相对文件工具不跟随越界符号链接;哈希不一致、路径越界和工作区被替换仍然失败,说明包含路径、期望与实际 SHA 或具体原因。

agent 拿到的是索引而不是全文:系统提示只含 Manager 提示词里的行为指南和规则章节(标签章节开头写明项目设置的标签名)以及 skill 的边界;用户提示里是对象摘要(编号、标题、状态、作者、标签、正文前 1000 字)、PR 的 base 和 head(ref 与 SHA,以及查看改动的 git 命令)、上下文文件清单和 skill 索引(名称、用途、路径)。完整内容写在工作目录旁的 ../context/ 下,agent 需要时用 read_file 或命令读取:object.json(GitHub 返回的 Issue 或 PR)、comments.json(全部讨论评论),PR 另有 files.json(改动文件及 GitHub 的 patch)、reviews.json(全部 review)和 review_comments.json(全部行内评论),以及 skills/<名称>/SKILL.md(各 skill 全文)。这些文件经脱敏后直接写进电脑,不写入任务记录;skill 取自默认分支,工作目录里 PR 自带的 .agents/skills/ 和任何 .bot/ 文件只是被检视的内容。

GitHub 按发出请求的身份分别限制每小时请求数:GitHub App 的每个安装(一个组织或用户)一份,其中所有仓库和任务 agent 共用;Token 账号按 Token 所属的 GitHub 用户一份,这个用户的所有 Token 共用;App 自身的 JWT 请求另算,它的额度取自这些请求响应里的 x-ratelimit-* 头(GET /rate_limit 不接受 JWT),所以 App 发过请求之后才列出。控制面从每次 GitHub 响应的 x-ratelimit-* 头记下所属窗口的额度、剩余和重置时间,安装同步每 10 分钟也经 GET /rate_limit(不消耗额度)读取一次;窗口用完或被 GitHub 拒绝(含次级限流)后,同一凭据的请求不再发送,任务以 github_rate_limited 等到窗口重置(或 GitHub 要求的时长)后几秒内再继续,这类等待不占自动重试次数。引擎自动轮询的等待(等电脑、等配置、等 PR head、无重置时间的限流)同一原因连续出现时,每次等待时长翻倍,分别封顶 5、30、5、15 分钟,换了原因或手动重试后重新计算。电脑尚未就绪或代次变化、配置未就绪(包括仓库尚无提交)、PR head 尚未更新,以及 manager 不可用导致的 task_runtime_failure 都是条件等待,不占用或重置尝试失败的连续计数,也不新建 8 小时周期;任务已有周期时保留其起点和失败计数,本次仍按条件自己的翻倍等待调度。

任务入队和准备、Agent 执行、策略测试、GitHub 发布阶段开始时即写入任务日志,包含仓库、固定提交 SHA、检视或开发模式、实际测试命令或发布目标;同一次尝试内的阶段开始去重,策略测试按实际命令操作记录,没有策略命令时不写测试开始日志。准备过程中每写完 100 个文件记录已写入数量、字节数和刚写完的路径,每个跳过条目立即记录路径及原因,构建本地 Git 树前再记一条,结束时保留 snapshot 汇总,其中记录文件来源(git_cache 或 github_api)和镜像状态(已有 hit、本次拉取 fetched、不可用 unavailable),跳过说明过长时标明省略条数。Pi 保留模型决策和工具结果事件,并在工具执行前写入 tool_start(文件路径、命令或动作名,不含写入内容),经现有 poll 复制到 task_logs;runner 在事件落盘前屏蔽已兑换的令牌,控制面继续经 Redactor 脱敏。运行中和成功后、失败或 waiting_*、retry_wait 的详情均保留完整时间线,故障步骤和侧栏直接展示 fault detail,无需打开原始数据;相同故障码、状态、说明和周期起点在自动重试时只记录一次,进入 8 小时周期时另记一条带 retry_cycle_started_at 的 fault。

retry_wait 的短退避从 5 秒起按 3 倍增长(5、15、45、135 秒,上限 300 秒),同码连续第 5 次失败后保持可调度状态,改为每任务 8 小时一次的重试周期。waiting_environment 中的执行中断(execution_interrupted)、工作区初始化/写入/快照失败及候选或候选内容不可读同样计入连续失败,第 5 次后进入该周期;进入前仍按 5 秒起翻倍、封顶 5 分钟等待。槽点以任务自己的周期起点计算,重启后保留,后续换成其他可重试失败也不再开始 5 次快重试;条件等待和 GitHub 限流各按自己的等待调度,保留但不消耗失败计数或周期。成功、取消、被取代和人工重试退出周期;重试前仍复核对象和开发条件,需重新规划或权限确认的任务不因周期被重新领取。页面只在当前失败确实采用周期槽时提示「大约 8 小时后再试」;真正的尝试失败在短退避和周期重试时均显示真实的 next_run_at。条件等待保留自己的说明,不附加「下次重试」;空仓库与 PR head 等待的专用原句保持不变。

runner 在写任务 worktree 的索引或 HEAD 之前(收集候选、快照、集成、恢复),检查该 worktree 自己的 Git 目录(共享仓库 /workspace/git/repo.git/worktrees/<名字>,或独立仓库的 .git)里的 *.lock:本机没有 git 进程在这个 worktree 工作(当前目录或参数指向它,或带着该任务的工作区标记)且锁已存在 10 秒以上时删除,并在操作结果 stale_git_locks_removed 和任务日志中记下文件名和存在时长;有 git 进程在用或锁太新时保留锁,操作以 git_worktree_busy 失败,按上面的节奏重试。

本该以 failed 结束的停止,若原因属于 Bot 自身、模型、项目电脑或外部服务(意外的运行异常、重启后残留的操作冲突等),改为进入 retry_wait 按上面的节奏自动重试;冲突类与执行中断一样,在发布阶段以外换一个新尝试,用新的操作键。需要人处理的原因(权限、配置、仓库内容、任务条件变化、GitHub 拒绝或写入结果未知)保持原状态,等人处理或条件满足后继续。

src/agent/failures.ts 把每个故障码归入一类原因并给出下一步,任务和日志接口在读取时附上 error_cause/cause,旧日志同样适用。GitHub 和模型请求失败写明方法与路径(或模型名与主机)、HTTP 状态、对方的简短说明,以及超时、DNS、连接重置、TLS 等网络原因;GitHub 5xx 附带 X-GitHub-Request-Id。日志截断保持合法 JSON,并保留故障说明。

开发候选由容器内 Git 生成,控制面保存候选 tree、文件清单、测试输出与本地提交映射,经 Git 数据 API 上传 blob/tree/commit。tree 只把改动、新增和删除的路径叠加在源快照的 tree 上(base_tree),不再每次列出整个仓库:大仓库的完整清单会让 GitHub 超过单个请求 10 秒的处理上限,每次重试都返回 502/504。路径在文件和目录之间转换,或 GitHub 算出的 tree 与候选不一致时,退回完整清单。只有 GitHub 返回 tree 与已验证候选完全一致,才创建或更新登记的 bot 分支。更新固定 force:false;未知或变化的分支 head 会阻止发布。容器里没有 GitHub remote 认证、私钥或模型 Key;控制面只对仓库镜像运行 git fetch、ls-tree 和 cat-file,不检出代码,也不运行仓库里的脚本或钩子,命令仍不在 bot 宿主机上执行。真实仓库访问仍需为 App/账号提供相应 Contents、Issues 和 Pull requests 权限。

评论、Review、分支和 PR 都有持久 outbox。请求结果未知时按任务 marker、head 和远端对象先对账(从未发出或确定被拒绝的请求不查找,直接在发送前校验一次任务对象);未能确认就保持 waiting_publication,不盲目重复;人工重试视为确认,结果未知的写入先再对账一次,仍查不到才重新发送。例外是把 bot 自己的分支指向某个提交:这一步是幂等的,GitHub 也能如实回答分支现在指向哪个提交(重复创建会返回 422,此时分支已在位;快进到同一提交不会有变化)。所以分支推送结果未知时,下一次执行会先查分支、查不到就重发,不进入 waiting_publication,也不需要人点重试。分支已推送后,基础分支前进不再阻止创建对应 PR。控制面重启后恢复未完成阶段,已完成任务不重新入队;manager 中断的命令不当作通过,重新检查环境后在新 attempt 工作目录继续,旧目录保留。同代已完成工具通过原操作 ID 回放,generation 变化会阻止旧任务直接写入新环境。

仓库自动化规则

PR 门禁、标签规范和合并队列是仓库策略,不写进每个仓库的 GitHub Actions:src/automation/ 提供规则引擎和内置模块(label-lint、pr-status、gate、merge-queue)。每个仓库用 config/repositories/<owner>__<repo>.yml 声明自己的标签轴、门禁、合并策略和 CI 阶段(仓库示例见 Jianyu010__PPMA.yml),policy 的 automation 字段仍可覆盖,默认 dry-run、默认不自动合并。webhook 落库时规划动作并写入 automation_runs,执行器接入 outbox 后再产生真实写入。配置 schema 与新增模块的步骤见 自动化规则。

外部执行端

管理入口的「外部执行端」可登记逐仓库客户端、配置 Webhook 事件过滤与签名转发,并查看投递和临时授权记录。个人电脑登记公钥、用本机私钥签发两分钟内有效的证明,GitHub Actions 使用受信任 OIDC 身份;检视完成后向公开 /external/token 兑换限定仓库的 Bot 安装令牌,再以 Bot 身份回复结果。只有 GitHub App 能签发此类临时 GitHub 凭据,不分发长期账号 Token。超级管理员可在该页设置实际 HTTPS 兑换地址,未设置时使用接入向导已验证的公开地址;旧客户端保留 ID 和订阅,但须登记公钥后才能继续兑换。完整接入、重试、权限与撤销边界见 外部执行端。

当前限制

回退到逐文件复制时,任务工作区不含上游历史;尚未接入子模块/LFS、按域名白名单的出口代理和长命令跨 manager 重启续跑(manager 重启会中断正在执行的命令)。命令输出由控制台每 2 秒轮询增量读取,不是推送。策略编辑和部分授权管理继续通过已有管理 API 完成。没有聊天、图形桌面、浏览器接管或远程桌面能力。