镜像自 HugoXK/LaunchPad@5cfa983 · upstream · 在 GitHub 上编辑 docs/onboarding.md ↗
自助接入与项目规则
本部署继续只使用 Docker Compose。系统超级管理员进入「全局设置 → 接入向导」;项目管理员在自己项目的「模型」页配置权限范围内的任务模型,在「角色」页通过概览和角色详情表单编辑角色,并在 Manager 详情编辑完整分派提示词和分派模型。项目的能力上限、事件来源和标签触发统一在「项目设置 → 监听与触发」配置。账号、模型、安装、项目电脑与数据卷复用原控制面,不创建另一套资源系统。
向导共七步,地址记录当前步骤(#/settings/onboarding/<0-6>),刷新后仍停在该步;旧的 #onboarding/<0-5> 链接会跳转到对应步骤。退出登录后从第 1 步开始。项目和组织管理员看不到入口,直接访问向导 API 也会被拒绝。打开第 1 步时,已保存 tunnel token 则默认选中 Cloudflare Tunnel,否则默认自建 HTTPS 中转。

公网 HTTPS 与域名
先准备自己的域名。这个 HTTPS 地址是 Bot 唯一的入口:控制台、用户登录、App 回调和 Webhook 都经它到达业务端口 8791,不需要第二个域名或端口。自建中转需配置有效证书,把整个域名转发到 8791,不按路径拆分。填写 HTTPS origin 后点击「检查并使用」。检查向 /.well-known/bot-webhook-probe 取当前实例的一次性 nonce/proof,拒绝 HTTP、重定向和其他实例;入口正常提供管理页面不影响检查。DNS 地址在每次连接时校验并固定,不能指向回环、私网或链路本地地址。
Cloudflare Tunnel 是 Compose 中独立的 tunnel 服务。初始没有 token,不连接任何账号;在向导中保存 token 后自动连接。输入框支持直接粘贴 token,也支持 Cloudflare 给出的完整安装、运行命令(含引号或多行说明,最多 131072 个字符);系统只提取并保存唯一的合法 token,不执行命令。没有合法 token 或包含多个不同合法 token 时会拒绝保存。token 不进入 Compose 环境变量、命令参数或读取接口:数据库加密保存,专用凭据卷中以 0600 文件交给非 root tunnel 进程读取。更换后自动重连,停用会移除文件并断开。该服务不发布宿主端口。Tunnel 位于独立 edge 网络,只能经过固定转发到 bot:8791 的 webhook 入口网关,整个域名(含控制台)都经它到达业务端口;控制面和 manager 不加入 edge 网络。即使远端路由填错,Tunnel 也不能直接连接 bot 或 manager。
在 Cloudflare 控制台的 Networks → Tunnels 创建 tunnel,在 Routes → Published application 选择自有域名,Service URL 填 http://webhook:8791。向导读取 tunnel 的路由和连接状态,Service URL 不是 http://webhook:8791 的路由标为「不是 Bot 入口路由」;点击正确路由的「检查并使用此域名」后才保存公网地址。域名配置和 GitHub 确认由账号所有者在对应页面完成,Bot 不替用户点击。
Cloudflare 自带的无主机名 http_status:404 兜底规则表示:未匹配已发布域名的请求返回 404。向导只显示普通说明,不把它标成连接故障;具名域名若指向其他服务,仍显示「不是 Bot 入口路由」。
GitHub App 与安装
优先使用已有 GitHub App。选择「使用此 App」会检查 App 和安装,并将 webhook 更新到验证过的域名及该账号已登记的 webhook 路径。凭据不会返回浏览器。
没有 App 时,填写「App 所属组织」和 App 名称,向导生成 manifest,再点击「前往 GitHub 确认创建」。这里填写的是 App 的归属组织,安装目标在第 4 步选择。默认是组织私有 App;需要安装到其他组织或个人账号时,勾选「公开 App,允许安装到其他账号」。固定权限为 contents、issues、pull_requests、statuses、actions、checks 写,metadata 与 Members 读(之前创建的 App 在「全局设置 → 机器人账号」或本步「使用已登记的 App」下点「检查权限和事件订阅」:页面只列出 App 定义缺少的权限和未订阅的事件,保留 App 的 Permissions & events 链接;安装未接受的权限和事件在项目列表对应仓库行显示,悬浮徽章可查看缺项;GitHub 不提供修改 App 权限和事件订阅的接口,所以要 App 所有者在该页改好后保存一次,再由各安装方各接受一次);default_events 为 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 和提交检查状态)并保存,代码更新不会自动修改已有订阅。installation 和 installation_repositories 由 GitHub 自动投递,不写入 manifest。不存在创建 App 的 REST 调用,也不要求 fine-grained PAT。
GitHub 确认后返回本机管理回调。随机 state 绑定发起的超级管理员,15 分钟有效,一次性使用;manifest code 兑换不带 PAT。App 私钥和 webhook secret 只在控制面加密保存,不回读到浏览器。回调成功后,浏览器打开向导第 3 步「GitHub 登录」,使用独立 OAuth App 配置登录,不复用仓库 App 的 Client ID/Client secret;保存并启用前仍可使用本地登录。
第 4 步的「安装账号」支持个人账号名、组织名、owner/repo、GitHub 个人主页、组织或仓库链接(包括 Issue、PR、代码目录链接),以及 git@github.com:owner/repo.git、ssh://git@github.com/owner/repo.git。点击「解析账号」,控制面从链接提取 owner,再通过 GitHub 核对并显示规范名称和账号类型(组织或个人账号);无效链接、不存在的账号和不能安装的账号类型会显示原因。解析时不连接粘贴的网址,不读取仓库内容,也不会安装 App 或启用仓库。
确认账号后,点击「前往 <账号> 安装」,打开 GitHub 定向安装页 https://github.com/apps/<slug>/installations/new/permissions?suggested_target_id=<账号 ID>。这是 GitHub 文档支持的预选方式;一般安装入口仍使用 select_target,但该页没有文档说明会处理 suggested_target_id,因此向导在已知账号时保留 /new/permissions。仓库范围及安装权限由 GitHub 页面确认。如果此 App 已安装到该账号,入口改为现有的安装设置:组织使用组织设置页,个人账号使用个人设置页。安装到其他组织或个人账号仍要求公开 App 和相应的 GitHub 权限;个人安装需在 GitHub 登录该个人账号,向导不会绕过授权或替其他用户确认。控制面用 App JWT 查询对应的 /orgs/{org}/installation 或 /users/{username}/installation,不需要用户 PAT。
安装页展示当前有效安装数,取自当前安装投影,暂停、卸载或范围待同步的记录不计入,不使用历史保存的安装数量。安装页也保留「在 GitHub 选择账号」和「重新检查安装」。安装后点「重新检查安装」,再到第 7 步同步并启动目标仓库。也可以跳过并继续配置模型和规则;页面标明尚未安装,向导不启用检视。已有安装不会被删除或重新创建。确认安装、选择模型后,最后一步仅对用户明确选择的项目启用检视,自动开发保持关闭。提交完成前配置若已失效,服务端拒绝完成,页面自动重新读取步骤状态并展示缺项;重读失败时标为待核验、保持完成按钮禁用,可单独重试读取,不会重复提交完成操作。


GitHub 用户登录
第 3 步使用独立 OAuth App 登录控制台;第 2 步的 GitHub App 负责仓库连接、执行和权限核验。两者凭据分别保存,选择或新建仓库 App 不会切换登录配置,不需要每名用户创建 App。
按本页顺序操作:
- 打开个人 Settings → Developer settings → OAuth Apps → New OAuth App(也可以由组织登记 OAuth App)。Application name 填容易辨认的名称,Homepage URL 填 Bot 统一入口,Authorization callback URL 填页面显示的
<统一入口>/auth/github/callback。不要选择 GitHub Apps,不需要启用 Device flow 或安装到仓库。 - 登记后复制这个 OAuth App 的 Client ID,在其 Client secrets 区域生成 Client secret,分别填入本页。不要使用仓库 App 的 App ID、Client ID 或 Secret。已有加密保存的登录 Secret 可以留空保留;更换 Client ID 必须同时填写新 Secret。
- 勾选「启用 GitHub 账号登录」,点「保存登录配置」,随后继续安装仓库 App。也可以暂不启用,继续使用本地账号。
登录明确请求空 scope,只读取公开 GitHub 身份,不申请 repo、read:org 或其他额外权限。若这个 OAuth App 曾获得额外权限,GitHub 仍返回带额外 scope 的令牌,Bot 会拒绝登录;用户应在 Settings → Applications → Authorized OAuth Apps 撤销该 App 的旧授权后重试,或由管理员使用专用于登录的新 OAuth App。授权页由 GitHub 控制,具体文案以实际页面为准。
组织和仓库管理权限由仓库 GitHub App 的只读安装令牌查询,查询后撤销临时令牌。组织 owner 识别需要仓库 App 的 Organization permissions → Members: Read-only 和 organization 事件;向导新建 App 已包含,已有 App 由所有者补齐并在安装处接受新增权限。此权限不在登录 OAuth App 上配置。仓库 App 的所有者和设置入口在第 2 步显示,缺少信息时可原地刷新。
「GitHub 地址及用途」列出登录 Callback URL、仓库 App 的安装 Setup URL /onboarding/github/setup、注册回调 /onboarding/github/callback 和 Webhook URL。登录回调只填入 OAuth App;其余地址用于仓库 GitHub App,不能互相替代。公网地址变化后,在 OAuth App 更新登录回调,在仓库 App 更新 Setup URL;Webhook 可由重新检查写入。没有公网地址时,页面给出本机回环地址,仅适用于本机测试。
升级前复用仓库 GitHub App 登录的配置继续运行,页面明确提示迁移并要求新 OAuth App 凭据,不会预填或复用仓库 App 的 Secret。保存新配置后,旧 GitHub 用户令牌和 GitHub 会话会清除;用户重新登录仍按 GitHub 数字 ID 关联原账号,已有本地会话、显式委派、项目和任务保留。迁移完成后,用户应在 GitHub 的 Authorized GitHub Apps 撤销旧个人授权,保留仓库 App 安装。
Secret 由管理员本人填写,不经聊天或 Issue 转发;输入框始终不回显。勾选「清除登录 Client secret,并停用 GitHub 登录」仅清除登录配置,不修改仓库 App 凭据。保存立即生效并在重启后保留;仅未保存向导配置时使用部署环境默认值。修改配置会使尚未完成的 OAuth 回调失效并要求重新核验派生权限。首次 GitHub 登录不会合并同名或同邮箱账号,也不会授予系统超级管理员;已有本地账号应先登录后绑定。详见身份与授权。
项目列表的快捷设置
项目列表的「同步安装列表」会留下权限和事件是否全部正常的结论;部分账号失败时说明无法判断全部正常。CI 改动由项目管理员创建、确认为 CI 改动的开发任务以 bot PR 交付,详见接入说明;「看板」由行上开关控制。
项目列表右侧将项目状态、检视/开发开关和任务数放在同一区域。两个开关是能力上限的快捷写法:开检视至少「可评论和打标签」、关检视为「只读问答」,开开发为「可开发并开 PR」、关开发至多「可评论和打标签」。点击开关即保存对应项目策略;保存中暂时锁定该项目的两个开关,成功显示结果,失败显示原因并保留原状态。超级管理员可配置全部项目,项目管理员只能配置分配给自己的项目。未启动的仓库需先启动;已禁用项目可以预先保存开关,但不会因此启用项目或启动任务。
「执行中」显示该项目当前执行阶段的任务数;有排队任务时同时显示「排队」。任务数每 5 秒刷新,点击可进入项目的运行状态,查看正在执行、排队和最近的任务。配置等待、环境等待、失败和已结束的任务不会计入执行中;计数覆盖全部任务,不受任务列表每页条数限制。该区域支持后续追加项目特性的状态或开关。


模型与规则
模型沿用 URL、API Key、模型名;保存的端点视为可信,项目代码、日志和测试输出可发送给它。Key 只保存、不回显,空白更新保持原值,撤销仍通过已有独立接口。向导可保存部署共享模型,实际项目在「模型」页选用,并配置项目默认模型和任务模型覆盖。共享模型的供应商、Key、模型名和计费单价只在「全局设置 → 模型」修改。
bot 在一个仓库里的行为只在项目配置里调整(#935):检视、开发、标签和行为指南是「角色 → Manager」里 Manager 提示词的章节,检视和开发标签的名字在「项目设置 → 基本 → 标签」,电脑规格在「机器配置」。章节没写时使用 prompts/ 下的内置原文。完整说明见在角色配置里调整行为。
仓库里只读取 .agents/skills/**/SKILL.md:仓库追加的简单 skill,仅加载文本,不加载 JS 扩展,取自默认分支。skill 只指导本仓库的工作,不能扩大权限或改变平台规则。PR 修改 .agents/skills(含移动、删除)时,检视总结会强制写明「这些文件改变了 bot 的行为,需要人来决定」;PR 新内容不会成为该次任务的 skill。
仓库里的 .bot/guide.md、.bot/rules/*.md 和 .bot/computer.yaml 不再读取:升级时每个已有项目按当时生效的那一层一次性导入 Manager 章节、标签设置和机器配置,并在「角色 → Manager」留下导入记录;仓库还留着这些文件时,项目页提示可以删除。控制台覆盖层和 PUT /api/repositories/:id/rules 已删除(返回 410)。
检视的行内事件始终是 COMMENT,不能 APPROVE、REQUEST_CHANGES 或自动合并。
为什么选择 Pi
选用 Pi SDK,固定 @earendil-works/pi-coding-agent 1.4.0,MIT 许可证随项目镜像保留。Pi 可无界面嵌入 Node 进程,支持显式工具、会话、模型与资源加载器;无需引入独立 Agent 服务或桌面。OpenCode 的 headless server 也可工作,但本项目已有 Node runner 和控制面权限边界,SDK 更适合保留这些边界。
Pi 在每项目容器的任务工作目录执行现有文件/命令工具,模型循环由 Pi 驱动。项目内只存在指向 loopback 的无真实凭据代理;任务专属请求/响应邮箱通过 manager 中继给控制面,控制面选择已授权模型并附加真实 Key。只允许该项目选定模型的 chat completion,不代理任意 URL,也不暴露 GitHub、管理员或 manager 凭据。仓库网络仍各自独立,容器不发布公网端口。
控制面将上游非流式结果转成 Pi 需要的本地 SSE,兼容现有接口并在写回容器前脱敏;不会把真实模型 Key 带入 SDK。任务不限模型请求次数,原独立测试验证、GitHub outbox、head 和分支归属校验继续有效。容器重启依据启动标识检查 Pi 状态,未完成工作重新准备,不把 Docker running 当作任务完成。
检视与修订的发布边界
检视指引写在 Manager 提示词的检视章节里,随规则章节放进 Issue/PR 检视的系统提示,不再以额外管理员提示或上下文字段发送给模型;检视和开发标签是项目设置,标签章节开头写明它们的名字。GitHub 评论不发布选用行内/讨论形式的理由;这些理由保留在任务结果中,重复的相同发现只保留一次。
bot 自己的 PR 仅修订开出它的开发的目标与明确可执行、属于该目标、无需人工决定的发现;待人决定和超出范围的发现不会进入修订上下文。每次修订确认 head 后同步更新 PR 标题、正文和测试结果;提交使用独立的代码变更标题,不套用检视总结模板。提交邮箱根据当前账号 ID/登录名动态推导,控制面和容器内本地 git 使用同一身份。
推送后 PR head 尚未更新时,任务先短暂重读;超时显示「等待 PR 更新」和已推送 SHA,并自动继续核对。等待不重复推送、不增加修订轮数。作者、仓库和分支真正变化时分别暂停说明,不能把延迟当成权限变化。Webhook 列表区分已创建任务、草稿、非触发和重复,并链接对应任务。手机上导航与向导步骤完整换行,规则正文随页面展开。
验证
npm run check、npm test 和 npm run test:e2e 覆盖协议、权限、向导及来源界面。npm run test:agent 使用真实 Pi 和 Docker 项目容器配合假模型/GitHub,验证检视、开发、恢复与凭据隔离。测试实例使用独立 Compose 项目与卷;不要对人类试用实例运行 down -v。
完成页在替换内容前读齐接入配置、模型和已安装仓库列表;其中任一读取失败时,当前页面保留可见的状态未知提示、禁用的完成按钮和独立重读入口。第三次仓库列表读取失败也沿用相同恢复方式,离页后的回包不替换新页面。