镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/admin.md ↗
部署这套 bot 和管理员面板
本文写给部署和管理这套 bot 的人。只想把 bot 装到自己仓库的用户看 README 即可。
一个控制面负责管理页面、接收 GitHub Webhook 和调度任务;每个启用的仓库各有一台长期运行的 Docker 容器(下文称“虚拟电脑”),bot 在里面读代码、跑命令。新开的 Issue 和 PR 会收到一条检视总结评论;打开自动开发后,明确要求改代码的 Issue 由 bot 实现、测试并开 PR。
项目页的「项目知识」以真实目录浏览共享项目文件,可创建空目录、预览 UTF-8 文本或 Markdown、编辑、重命名/移动、下载及查阅历史。历史按需展开,旧版本只读;确认恢复后创建新版本,已有历史保留。不能预览的二进制只提供原字节下载,不能在文本编辑器中覆盖。搜索限定文件名/路径,没有语义索引;旧角色/私有记录仍按原授权过滤,仓库来源文件只读,正文修改走 PR。保存使用 expected_revision,冲突时保留草稿并比较最新正文;草稿只在当前登录页面内存中保留,退出即清除。
每个仓库的稳定笔记卷读写挂在 /workspace/project-notes(任务使用 ../notes/),停机、重建、禁用和重置代次后保留;页面由 manager 直接访问同一份文件,无需启动项目电脑,删除项目时随环境删除笔记卷。相对路径拒绝穿越、绝对路径及符号链接;目录须先创建。.write-history/file-tree.json 在原卷锁内维护稳定文件 ID、旧 n: 别名和可恢复移动日志;版本 blob 与历史不随路径改名。旧文件及历史按首次访问迁入,旧 m: 记录保留原存储和来源。备份时须保存整个笔记卷,包括 .write-history,不能只复制当前正文。manager 与项目 runner 必须从同一版本源码构建并一起更新;manager 完成电脑镜像恢复前不会开放文件接口。目录历史启用后,回退旧版文件服务须恢复升级前的整卷备份,不能只切回旧镜像。
/api/repositories/:id/knowledge-files 支持按 directory 浏览、query 全目录文件路径搜索、deleted_only=1 查找已删除文件;创建兼容根目录 name 和相对 path。文件以稳定 ID 读取/保存,POST /:id/move 带目标 path 与 expected_revision;versions 与 restore 保留原版本语义。knowledge-directories 的 POST/DELETE 创建或删除空目录,不能删除根目录。所有操作沿用项目知识权限,读取完成后再次校验授权。
准备
- Docker Engine 和 Docker Compose v2(
docker compose version能输出版本)。 - 一个 GitHub 组织,以及能在其中创建和安装 GitHub App 的账号(组织所有者或 GitHub App 管理员)。
- 一个公网 HTTPS 入口(一个域名):控制台、用户登录、GitHub 回调和 Webhook 都经它到达这台机器。可以是自己的域名加 HTTPS 反向代理,或者 Cloudflare Tunnel。
- 一个兼容 Chat Completions 的模型:接口 URL、API Key 和模型名。
启动
不需要克隆仓库,也不在本机构建:
mkdir department-bot && cd department-bot
curl -fsSLO https://raw.githubusercontent.com/agent-CI-Infra/bot/main/compose.yaml
docker compose up -d
然后在这台机器的浏览器打开 http://127.0.0.1:8791/。Bot 装在远程服务器上时,先 ssh -L 8791:127.0.0.1:8791 <服务器>,再在自己电脑上打开同一地址。配好公网 HTTPS 入口后,也可以直接从那个地址使用控制台。
镜像发布在 GHCR,匿名拉取要求这些包已公开;如果拉取报 denied 或 unauthorized,克隆本仓库后从源码构建。
第一次配置
- 创建第一名管理员。 首页显示「创建第一名管理员」:填用户名和 12–256 位密码,点「初始化并登录」。初始化只成功一次,之后这里只有登录。
- 走完接入向导。 首次登录会自动打开「全局设置 → 接入向导」(仅系统超级管理员可用),按页内的七步走:
- 公网 HTTPS:选「自建 HTTPS 中转」,把一个专用域名整个反向代理到
http://<这台机器>:8791,填https://<你的域名>,点「检查并使用」。或者选「Cloudflare Tunnel」,粘贴 tunnel token 点「保存 token」,在 Cloudflare 的 Published application 把 Service URL 设为http://webhook:8791,回到向导点该路由的「检查并使用此域名」。这个域名是唯一的入口,控制台、登录和 Webhook 都走它,不需要第二个域名或端口;反向代理在另一台机器时,先在.env设置BOT_BIND_ADDRESS=0.0.0.0。 - GitHub App:填「App 所属组织」和「App 名称」,点「准备 GitHub 确认页」→「前往 GitHub 确认创建」,在 GitHub 上确认后会回到向导。权限固定为 Contents、Issues、Pull requests、Commit statuses、Actions、Checks 写,Metadata、Members 读(Actions、Checks、Commit statuses 让检视和开发任务能用只读令牌查看 CI 状态,这三项的写权限留给控制面发布状态、检查结果和重跑 CI;之前创建的 App 要在 GitHub 上补加),订阅
issues、pull_request、issue_comment、pull_request_review、pull_request_review_comment、check_run、status和organization(已有 App 需由所有者在 Permissions & events 勾选 Issue comment、Pull request review、Pull request review comment 以触发评论和检视回复跟进,并勾选 Check run、Status 以向控制台推送 GitHub Actions 与提交检查状态;「检查权限和事件订阅」会列出缺少的事件);Webhook 地址https://<你的域名>/hooks/github/<account_id>/<endpoint_id>由向导写进 App,不用手填。已在「全局设置 → 机器人账号」登记过的 App 点「使用此 App」。 - GitHub 登录:创建独立的 OAuth App,按页面指引填写 Homepage URL 和
https://<你的域名>/auth/github/callback,复制这个 OAuth App 的 Client ID 并生成 Client secret,勾选启用并保存。仓库 GitHub App 与登录 OAuth App 分开配置;Secret 不回读,留空保留。本步骤可暂不启用,本地恢复账号继续可用。详见接入说明。 - 安装:点「在 GitHub 安装此 App」,选好仓库后回来点「重新检查安装」。
- 模型:在「添加模型」填接口 URL、API Key、模型名,点「保存并继续」。URL 下方会显示实际的对话地址和模型列表地址;bot 不会替你补上或去掉
/v1,地址不以/v1结尾时页面会提示。保存前可以点「获取模型列表」从上游选模型名,或点「测试模型」确认 URL、Key 和模型名可用。 - 规则:看一下内置规则,点「下一步」。
- 完成:点「同步已安装仓库」,在要用的仓库那一行点「启动并启用检视」。公网地址已验证、仓库 App 有效、至少一个安装范围已完整同步且有效、共享默认模型仍有 Key 时,才可点「完成向导」。暂时跳过安装不会标记为完成;可从「返回项目,稍后继续」离开并保留已保存配置。完成接入配置不等于项目已启用或任务正在运行。
- 公网 HTTPS:选「自建 HTTPS 中转」,把一个专用域名整个反向代理到
- 确认跑通。 在已启用的仓库新开一个 Issue,bot 会在上面回复一条检视总结评论(之后再检视同一个 Issue 或 PR 时改写这条评论,不再新发);第一次要先启动该仓库的虚拟电脑,会慢一些。没等到时,到「任务看板」和「待处理」查看是否已经有对应任务。
日常使用
「待处理」只列出需要关注的任务,优先展示服务端记录的处理说明。任务详情中的模型、角色或环境配置故障提供对应的项目配置入口;由此进入配置页后,可用「返回待处理列表」回到原项目范围和分页。保存配置不代表任务已经恢复,返回后会重新读取任务记录。关闭任务详情也会刷新原列表,仍待处理时恢复到该任务的按钮,否则把焦点移到刷新入口;不会把自动排队计为人工待办。
不再需要任何人处理的任务会自动移出「待处理」(#713),改为 bot 自行停止的 cancelled(与 #655 相同),原因码写明是哪种情况:同一 Issue 或 PR 上已有更新的同类任务接手(obsolete_superseded;更新的那个也是 bot 自行停止的不算);Issue 或 PR 已关闭或合入,包括后续任务来源的那个(obsolete_closed,以 webhook 和任务输入记下的对象状态为准,没见过关闭的视为仍开着);以及超过 BOT_OBSOLETE_FAILURE_DAYS(默认 7 天)的平台类或临时失败、之后任务没有任何变化(obsolete_expired,只针对 failed)。后台每 15 分钟按创建时间从旧到新清扫一小批,同一工作的新任务开始时也立即清扫它之前的任务。手动暂停的任务、对象仍开着且未被取代的求助、权限等待和待确认的发布,以及引擎会自行重试的等待(重试等待、配置、环境、PR head)一律不动。被移出的任务保留历史、结果和原来的失败:时间线记下移出原因、原状态和原失败码,看板卡片回到最近一个不是 bot 自行停止的任务所在列,待处理列表和项目总览的计数同时变化;仍需要时可在任务详情点「重试」,按原状态重新开始。
在任务看板或项目总览打开“新建任务”;手机也可从底部“更多”进入。选择项目并填写原始需求、目标、工作范围、验收条件和交付类型。页面先读取服务端执行上下文;提交沿用当前身份和项目角色配置,代码 PR 仍需原有写入授权、验证及独立 QA。服务端回执分别显示已创建和失败;只有获得真实任务编号才提供详情入口。网络中断时保留本页草稿并核对同一次提交,不能改写需求后盲目重建。草稿仅保存在当前网页内存,退出登录或网页重新载入后不保留;结果未知时先在管理审计中核对。
项目「机器配置」将 manager 实时核验与保存的状态记录分开展示。连接失败、记录缺失、管理服务恢复中和状态异常分别显示对应提示,不能据旧的“就绪”判断当前可用;核验时间不代表心跳。资源指标缺失显示未知,真实零值仍显示零;超过 30 秒的采样或读取失败时保留的上次采样会明确标记。运行与排队数量可进入同一项目活动页核对。刷新只更新状态,保留表单草稿、已展开日志和焦点;授权失效会清除原电脑内容与配置。
配置按资源上限、软件与初始化、网络与环境变量分组,各字段分别标明全局默认或项目控制台来源;仓库里的 .bot/computer.yaml 不再读取(#935)。资源的配置目标与电脑报告分开展示,全局默认等待重建时不据目标值宣称运行中容器已应用。保存影响区列出本组未保存的字段及重建、后台进程结束和工作卷保留的影响;项目任务并发单独保存,与角色限额分开,也不会重建电脑。已保存的机器配置读取失败时,各字段显示来源未知并禁止保存;点击「重新读取电脑配置」重新读取。机器页不等待、也不读取默认分支(#935)。读取失败会在入口旁显示原因,仍可重试。
项目的「基本设置」按概况、分支、标签(检视标签和开发标签)、监听与触发入口和公开可见性分组;仓库还留着已导入的 .bot/ 文件时,概况里提示可以删除,能力上限和事件来源统一在项目「监听与触发」页编辑;启用、禁用与删除集中在危险区。分支和「监听与触发」页功能策略的未保存输入只在当前浏览器页面内存中保留,切换页面再返回或使用「刷新项目设置」不会丢弃草稿;重新载入整个网页后不保留。保存失败保留输入,可显式放弃本组草稿。项目列表和基本设置中的公开看板开关共用范围确认,列明目标项目;开启和关闭分别确认,取消不保存,失败保留原状态并显示原因。私有仓开启时也会说明无需登录的公开范围,且不随项目禁用自动关闭。
「成员」按当前项目展示实际授权来源、范围、状态和时效:「来自 GitHub(继承)」(仓库 Admin、组织 owner)、「来自 GitHub:Write/Maintain 协作者」「来自 GitHub:Triage/Read 协作者」、「来自组织授权(继承)」、「项目管理员 <名字> 授予」和「本项目手动分配」。读取需要本项目配置权限。项目管理员在页面底部「授权成员」里按 GitHub 用户名授出只读、成员或项目管理员,只能授出自己在本项目拥有的权限,也能逐条撤销本项目里不超出自己权限的委派;由项目管理员授予的权限只在授予人仍有这些权限时有效,否则显示为暂停(规则见项目内委派)。整个组织的授权和平台角色仍只由超级管理员授予;旧式项目管理员分配仍仅由平台管理员(用户页显示为「管理员」)编辑,移除项目分配不会撤销组织继承或独立委派。
启用更多仓库:在「项目」页点「同步安装列表」,在仓库行点「启动」,选好模型后确认;仓库所属组织还没有受信任时,可以同时勾选「信任 …」,以后由它的仓库管理员自己启动。受信任的组织在「全局设置 → 项目管理 → 受信任的组织」里维护:每个组织可设默认共享模型和启动时的能力上限,也可撤销信任(只影响以后的启动)。仓库管理员在自己的项目列表里看到「待接入的仓库」和每行的「开始接入」,经接入向导(#934,见接入指南)确认方案:受信任组织的仓库(标「可自行启动」)用组织默认值直接启动,不能改资源或机器配置;其他仓库确认后向超级管理员申请启动,申请出现在超级管理员「待处理」页顶部,同意时可改模型和能力上限、顺带信任组织,拒绝要写原因。超级管理员的仓库列表里,未启动仓库同时有「开始接入」和「启动」。启动时选择项目能力上限,默认「可评论和打标签」;只有需要 bot 自动改代码时才选「可开发并开 PR」,只想在飞书和控制台里问答时选「只读问答」,之后可以在「监听与触发」里调整;能力上限为「可开发并开 PR」时,由项目 Manager 判断一个 Issue 能不能开发,并写明依据:有人加了开发标签(默认
bot-develop)、triage 以上权限的维护者在评论里提出要求,或 Manager 提示词里允许开发这类 Issue 的规则;外人的评论不算。不能开发时 bot 在 Issue 上回复缺什么。仓库启动前收到的事件只存档,不会补跑。不再需要时点「禁用」,数据保留,之后可以再启用。仓库在 GitHub 上已删除,或当前账号已完全不能访问它(移出安装、安装被暂停)时,可以在项目行或项目设置里「删除」:先当场向 GitHub 核对,再停任务、去掉容器、网络和长期笔记卷并删掉项目记录,工作卷和操作审计保留。仍能看到、但授予的权限低于所需的仓库在列表上标为「权限不足」,不能删除。仓库行对照全部功能检查权限和事件订阅,未开启的功能也算:有缺项时显示带警告图标的「权限不足」「事件未订阅」或「需要 GitHub App」,点开逐项列出缺少什么、怎么操作、会影响哪些功能以及这些功能是否开启。缺项影响已开启的功能时为琥珀色,只影响未开启或手动使用的功能时为蓝色。暂停安装不算缺口。「同步安装列表」保留是否全部正常的结论与安装缺项,部分账号失败时说明还不能判断全部正常。全局「机器人账号」的检查只报告 App 定义缺口。看板由行上开关控制。清理用户和账号:「全局设置」的「用户」「机器人账号」两类里每行都能删除;不能删最后一名活跃的超级管理员,仍有项目使用的账号要先删掉这些项目。删除账号只从本系统移除,不会在 GitHub 上卸载 App。外部执行客户端在项目「外部执行」或全局「外部执行端」删除。
调整一个仓库:在「项目」页点该仓库的「设置」。「角色」紧跟「机器配置」,二级菜单先显示可编辑概览,再列出每个角色。可以用表单修改角色模型、Agent、提示词、技能、逐项权限、运行环境、预算和任务阶段要求,无需编辑 JSON。项目「监听与触发」页统一配置能力上限与事件来源。「角色 → Manager」详情编辑完整的分派提示词和分派模型,查看最近分派、仓库 skill 和
.bot/规则文件导入记录。权限按项目平铺:资源选择读写、只读或禁止,动作选择允许或拒绝;提示词不能授予权限。每个角色显示共用的系统提示词和完整可编辑的角色提示词,原固定职责与任务记录规则已成为模板内容;除 Manager、Coordinator 和 QA 外,内置或自定义角色都可以删除。「模型」单独配置项目默认模型、各工作类型和 Manager 分派的模型,以及项目专属供应商。部署共享模型在项目内只读展示和选用;即使是超级管理员,也需到「全局设置 → 模型」修改共享供应商、Key、模型名和计费单价。「机器配置」改虚拟电脑的资源、软件包和初始化脚本,以及这台电脑同时运行的任务数(项目管理员也能改,留空跟随全局默认)。规则、标签和机器配置都在这些页面调整,仓库里只读取.agents/skills/下的 skill;早期版本的.bot/文件已在升级时导入、不再读取,见在角色配置里调整行为。看 bot 在做什么:「任务看板」按工作类型收拢检视、开发、通用回复和发版本;点卡片标题时,当前筛选只有一个任务就直接看过程,有多个任务则在同一个弹窗里选择。任务详情展示公开输出、工具调用、命令和结果,不展示私有推理;实际运行记录按该次快照列出 Agent、模型来源和配置版本。工作日志先读取最近 100 条,可按需加载更早记录;刷新只追加新日志,保留已展开内容和阅读位置。任务结束不代表已读取到当前候选的 QA 通过记录,创建 PR 也不代表已合入;发版本卡片直接进入项目的发版本记录。
按工作看进展:「任务看板」默认显示全部对象,每张卡只代表一类工作在一个 Issue/PR 上的工作(检视、开发/跟进或通用回复),或一条发版本,卡片徽章写工作类型名称。同一对象的各类工作分别保留各自状态。工具栏的「筛选」包含仓库、工作类型、执行状态、对象类型、搜索和含已关闭;仓库和工作类型使用紧凑下拉选择,执行状态和对象类型保留平铺按钮,选中项会高亮;当前条件可以逐项移除。「按…分列」使用下拉选择,切换 bot 执行阶段、仓库、执行状态、工作类型或个人自定义字段,只改变排列,不改变卡片的任务目标。桌面在列内滚动,零数量状态用简短计数表示;窄屏用「当前分组」下拉选择一组,卡片纵向排列。更多菜单可在分栏与列表之间切换,列表复用相同筛选、分组和服务端计数,不另建任务。列表中的执行阶段只读;个人字段可用下拉修改,拖动仅在分栏的个人字段模式可用。排列选择和阅读位置仅在当前登录页面内存中保留,退出登录或重载网页后重置。视图选择器、未保存状态和保存动作常驻工具栏;更多菜单只保留分栏/列表切换、另存视图、自定义字段和删除视图等次级视图操作;视图保存筛选(含对象类型)、分列与折叠列。旧地址
#/reviews、#/developments只在进入时选择全部检视或全部开发/跟进,随后规范为#/board。自定义字段仍属于 GitHub 对象,同一对象的各张卡共享个人字段值,修改不会改变执行阶段或触发任务。全局设置:超级管理员在「全局设置」里管理整个部署,主内容区顶部横向二级导航按「系统与算力 / 接入与网络 / 连接与渠道 / 仓库与用户」分组,每个类别有自己的地址(
#/settings/<类别>),刷新或分享链接都停在同一类:- 「工作电脑」:项目里 Manager、Dev、QA 等工作角色执行任务的虚拟电脑,每个仓库一台。这里设置每台电脑默认同时运行的任务数(1–32,默认 1)和默认资源(CPU、内存、进程数上限、
/tmp大小,内置 2 核、4096 MB、1024 个、1024 MB),项目在「机器配置」里没有单独设置时使用;页面最后显示当前运行的镜像标签,源码运行时显示为源码运行。旧地址#/settings/general仍打开这一类。 - 「接入向导」:完整七步接入,包括新建 App、配置 GitHub 用户登录、安装与启用项目。
- 「公网接入」:修改并重新检查公网 HTTPS 地址;保存或撤销 Cloudflare Tunnel token(可以粘贴完整的 cloudflared 命令,只保存其中的 token,页面不回显)。
- 「机器人账号」:改选接入向导使用的 GitHub App,并把它的 webhook 改到当前公网地址;新增、检查权限和事件订阅、删除已登记的 GitHub App 与机器人 Token。
- 「模型」:更换向导启用仓库时使用的默认共享模型;添加、修改和删除部署共享模型。
- 「助手电脑」:群聊助手和管理助手电脑的空闲回收时长(默认 5 分钟)、同时存活的电脑上限(默认 20 台)、最长存活时长(默认 4 小时),每台电脑的资源(CPU、内存、进程数上限、
/tmp和工作目录大小,默认 1 核、2048 MB、512 个、各 512 MB,范围与工作电脑相同;新建的电脑立即使用,已有的在它的下一个回合开始时重建),每个 HOME 的容量上限(默认 5 GB)、不活跃数据保留期(默认 30 天)和所有 HOME 合计的告警值(默认 50 GB);下方列出每个群、每个人 HOME 的占用、文件数、最后活跃时间和状态(可写、超过上限只读、封存的旧代次),可以清空某个 HOME(同时删除它正在运行的电脑)。合计超过告警值时这里显示告警,日志每小时记一条。见 服务角色。 - 「Agent CLI 工具卷」:容器化后端运行的 Claude Code 与 Codex 版本。页面给出工具卷根目录、容器内路径、架构、Node 运行时和保留版本数,以及每个已安装版本的产物来源、sha256 与大小。安装填精确 semver(可选下载包 sha256,Claude Code 另有原生二进制 sha256),成功后这里填的保留版本数会存成新的默认值,之后的安装和清理没填这一项也用它;工具卷未挂载或读不到架构时给部署指引并禁止提交。清理只保留最新的几个版本,正在运行的任务用着的
task_runs.cli_version不会被删除;清单读不到的残留平时会被清理,只有仍被运行中或刚安装的版本指向的目录才保留并单独列出。安装正在运行的任务或角色用着的版本(含 Node 运行时)会被服务拒绝(agent_tool_version_in_use),工具卷不改动。角色页在 CLI 未就绪时给超级管理员「打开工具卷设置」的入口,其他角色只看到指路文字。这一类只对超级管理员开放。 - 「服务角色」:管理助手(控制台管理助手和个人私聊)、仓库问答助手和自定义服务角色的名称、职责、提示词、共享模型,以及按角色累计的用量;群能做什么不在这里设置,而是每个群绑定的权限档位(#849);项目管理员为自己项目建的群助手角色不在这里,在「个人设置 → 飞书绑定」维护;这些用量不计入任何项目,见 服务角色。
- 「用户」:新增用户、修改项目管理员的仓库权限、删除用户。
新建 App、GitHub 登录配置和安装到账号均在「全局设置 → 接入向导」完成。项目与组织管理员看不到全局设置。
- 「工作电脑」:项目里 Manager、Dev、QA 等工作角色执行任务的虚拟电脑,每个仓库一台。这里设置每台电脑默认同时运行的任务数(1–32,默认 1)和默认资源(CPU、内存、进程数上限、
给别人权限:在「全局设置 → 用户」新建项目管理员,从按组织分组的已安装仓库里多选:选「整个组织」时,这个组织已经启用和以后启用的项目都归他管理;只选仓库时不包括这个组织后来启用的仓库。用户列表列出每名项目管理员选的组织和仓库,「修改仓库权限」用同一份列表调整;不在安装列表里的整个组织会保持选中,直到管理员取消。也可以在仓库「设置」→「成员」单独添加或移除某个仓库。项目管理员只能看到和操作分给自己的仓库。
看用量和费用:任务列表和详情显示累计运行时长、输入/输出/缓存命中 token 及加权命中率,运行时长不含排队和等待。项目专属模型在项目「模型」页点「计费单价」,部署共享模型在「全局设置 → 模型」点「计费单价」,按需覆盖每百万 token 的输入、输出和缓存命中单价,留空字段继承同币种 models.dev 目录价格,清除手填后恢复目录;「用量与成本」页按浏览器本地日期展示费用、token,以及每类工作的任务数量和累计执行耗时(检视和开发四类总在表里,通用回复、Actions 失败分析、CI 观察等有任务时按名称列出),可按项目和日期范围筛选。关键数字、任务统计和每日图表排在默认折叠的「统计说明」之前。费用保留每日堆叠柱状图、项目占比、已保存单价与币种筛选;当前范围没有可计价记录时,柱状图和项目占比改按已记录的输入加输出 token 展示,缓存命中已包含在输入中,不重复相加。存在有效费用记录(包括 0 费用)时仍显示费用;token 也缺失时明确显示无可靠记录,不当作 0。币种只影响费用和 token。模型请求归入实际发生日;任务的整段执行耗时归入创建日,不跨日拆分。创建日期缺失的历史任务单独列为日期不明,缺失耗时显示不完整。统计仅包含控制面模型请求和任务,不含外部执行端自行调用或项目内其他服务。单价变更只影响新请求,缺少用量或单价的请求单独提示,历史未记录的数据不作补算。
项目「模型」页和「全局设置 → 模型」按供应商(同一范围、同一请求地址)分组显示模型。列表只在供应商标题旁提供「编辑供应商」,「新增供应商」使用同一套表单:连接信息在上,选择或手动添加模型在下。获取模型列表只在该表单提供,不再逐条模型重复展示;可以选择多个模型,保存时一并添加,也能填写列表外的模型名。
编辑供应商时,修改 URL 会更新组内全部模型;填写新 Key 会统一更换,留空保留各模型现有 Key。「撤销供应商 Key」是编辑表单内的独立操作,确认后撤销这组模型的 Key,不保存尚未提交的 URL 或待添加模型。Key 加密保存且不回显。已有数据即使同一地址下使用了不同 Key,也不会因为留空保存而丢失;只有明确填写新 Key 时才统一替换。供应商操作在一个事务中完成,其他页面修改过模型或组内模型有变化时拒绝过期保存,提示重新打开编辑。模型 ID、项目选择和计费单价保持不变。
模型行提供测试、修改模型名、计费单价、能力与目录和删除。「能力与目录」显示匹配条目与快照时间,可自动匹配、手动选择或取消匹配,并按字段覆盖上下文窗口、最大输出和推理能力;能力留空继承目录,没有匹配时使用默认值。目录每 6 小时刷新,超级管理员可立即刷新;失败保留旧快照并显示失败状态。目录价格以 USD 计价,不与 CNY 混算。共享供应商仍只有超级管理员能修改,项目管理员只能编辑自己负责项目的专属供应商。新增供应商至少添加一个模型,不保存空的供应商记录。


在项目「模型」中,本项目专属模型行的「删除」会先读取并列出项目默认/工作类型引用、当前已保存角色的显式引用(包括停用角色),以及接入默认模型的影响;历史角色版本和运行快照不计入当前引用。完整引用读取失败时不能确认删除。确认后只删除本系统的模型配置并销毁封存的 API Key,不会删除 GitHub 上的任何东西。项目管理员可删本项目专属模型;部署共享模型只能在「全局设置 → 模型」中由超级管理员删除,删除后所有项目都不能再选它。项目默认选择会改回「不使用模型」,任务专属选择保留为不可用,相关任务进入「配置待补」。项目角色的显式引用保留为不可用,之后执行等待补充配置,不换用其他模型;平台服务角色改为未配置模型。已经运行的任务不会被取消,已有请求和成本记录保留,仍按当时记下的模型名和单价展示。删除失败会留在确认框中,可重试或取消;删掉的若是接入向导的默认模型,这个默认随之清空。
- 准备版本与跟踪发布:项目「发版本」先显示合法版本、精确目标 SHA、上一版本和实际新增提交数,预检读取失败时不能确认。发布记录先给一张只读清单:版本、完整目标提交、阶段、发起者、更新时间和当前阻塞;阻塞只用记录里已有的阶段、错误与说明,进行中的阶段写明「进行中,无需操作」,未知阶段写「状态未确认」,不推断为正常。清单下方再按真实标签、run/attempt、草稿及正式发布事实展开每条记录。旧 attempt 的通过记录或运行建议不能代替当前检查结果;建议仅供排查。失败重跑或查证需要明确操作,正式发布仍单独确认。页面离开或权限失效后拒绝迟到回包,读取失败保留上次记录并标明状态未确认。
修改 CI
bot 不再生成门禁文件。要改 CI 时,项目管理员在「新建任务」写明要改什么,交付类型选「可检视的代码 PR」并勾选「允许修改 .github/workflows/(CI 改动)」;bot 按仓库自己的情况修改 workflow,测试和独立 QA 通过后开 PR,人检视合并后才生效。只有这样确认的任务推送时才申请 Workflows 权限,github_write 不能写 .github/workflows/。详见接入说明。
排查失败
- 任务失败或暂停:任务详情的「原因」说明是谁的问题(外部波动、GitHub 权限、模型配置、项目电脑、仓库内容、Bot 自身)和怎么处理;时间线里的「暂停或失败」带错误码和细节。执行进程(agent)失败时有一条「执行进程失败」,写着它给出的原因;Bot 自身的意外异常记为「运行故障」,带消息和出错位置。
- 虚拟电脑故障:项目「机器配置」的「故障」用中文说明错误码。manager 让电脑停止或恢复失败时,会在自己的日志里写一行原因(包括 Docker 拒绝操作时给出的说明)。
- GitHub 限流:「全局设置 → 机器人账号 → GitHub 请求额度」按账号列出每小时额度:GitHub App 每个组织(或个人账号)上的安装各一份,由那个组织下所有仓库和任务 agent 共用;Token 账号按 Token 所属的 GitHub 用户一份,由它处理的所有仓库和这个用户的其他 Token 共用;App 自身(JWT)只在 GitHub 报告时列出。每行显示额度、已用、剩余、窗口重置时间,以及流控中等待的任务数;「探测」立即读取一次:读窗口本身不计入额度,但 App 列出安装、签发临时令牌要用几次 App 自身(JWT)的请求,Token 账号第一次探测还要一次
GET /user读登录名。额度用完时任务等到窗口重置再继续,不占重试次数。 - 后台对账和外部转发:控制面周期对账、待发送的电脑操作和外部转发的内部失败写进控制面日志;同一个失败只在第一次出现、原因变化和恢复时各记一行,不会每 5 秒重复。
docker compose -p bot logs --since 1h manager # 虚拟电脑:Docker 失败、恢复失败、意外异常
docker compose -p bot logs --since 1h bot # 控制面:对账、任务运行故障、外部转发
任务记录里的消息先经过脱敏;日志只写错误码、Docker 的说明、异常消息和出错位置,不写请求内容和凭据。
升级与数据
在 compose.yaml 所在目录运行:
docker compose pull
docker compose up -d
数据在五个部署卷里:bot-data(控制面数据库)、bot-keys(加密凭据的主密钥)、internal-keys(bot 与 manager 的内部认证)、manager-data(虚拟电脑账本及各项目笔记卷的文件)和 assistant-homes(群聊助手、管理助手电脑的持久 HOME);tunnel-keys 只放 Cloudflare Tunnel token。丢了主密钥,已保存的 App 私钥和模型 Key 都解不开。docker compose down 会保留卷;日常升级不要加 -v(--volumes),它会删掉这些卷。备份见备份与恢复。
以前在仓库根目录用 docker compose up --build -d 从源码部署的实例,更新代码后再运行 docker compose up -d 会改为拉取 GHCR 镜像(同一目录,数据卷不变);要继续从源码构建,改用 docker compose -f compose.yaml -f compose.build.yaml up -d --build。
常用设置
在 compose.yaml 同目录的 .env 里写变量,然后重新 docker compose up -d:
- 改宿主端口:
BOT_PORT(默认8791)。反向代理在另一台机器时设BOT_BIND_ADDRESS=0.0.0.0(默认只绑定127.0.0.1)。 - 固定部署地址:
BOT_PUBLIC_ORIGIN=https://<你的域名>,并设置BOT_COOKIE_SECURE=true。远程使用控制台直接用这个域名,不再另建管理域名。 - 从旧的双端口版本升级:见从双端口升级。
- 虚拟电脑不访问外网:
BOT_PROJECT_EGRESS=false。 - 固定版本:
BOT_IMAGE_TAG=v<版本>(见 Releases;默认latest,即main最新发布的镜像)。
全部变量见端口与环境变量。
文档
- 接入向导与项目规则:向导每一步的细节、规则在哪里调整、仓库 skill
- 在角色配置里调整行为:规则、标签、机器配置在哪里改,
.bot/文件的一次性导入,仓库 skill 的边界 - 部署细节:镜像、从源码构建、版本发布与服务器部署、端口与环境变量、服务隔离、备份与恢复
- 外部执行端:在个人电脑或 GitHub Actions 里检视,再以 Bot 身份回复
- 仓库自动化规则:标签、门禁、合并队列和 CI 阶段
- 架构与行为:权限模型、虚拟电脑生命周期、检视与开发数据流、当前限制
- 管理 API
- 开发与验证:代码结构、测试命令、Docker 验收、CI 与合入
知识文件移动恢复出现 note_move_uncertain 时,本项目知识区会保持拒绝读写,不应手工清空 pending。停写、整卷备份与恢复步骤见知识文件恢复。