企业官网建设流程全解析

在thepopebot里，你只需要对 AI 说一句「帮我做完这件事」，它就能在后台独立完成一整套开发工作：自动创建分支、克隆代码、执行任务、提交推送，最后打开 PR 并自动合并。这个过程完全在后台进行，无需人工盯着屏幕。

本文将完整拆解这条「后台任务全链路」，带你从创建分支到PR 自动合并，一步步看清这6 步流程是如何串起来的。无论你是不是开发者，都能看懂 AI 后台任务是怎么跑起来的。

一、后台任务是什么？和实时聊天有什么不同

thepopebot 支持两种工作模式，后台任务（agent job）就是其中之一：

后台任务的核心价值就是异步 + 无人值守：你下达指令后可以去干别的事，AI 在后台默默完成，最后用一个 PR 把结果交给你。

二、6 步流程总览

整条链路由两部分协同完成：

• 宿主机侧（Node.js）负责建分支、推配置、拉起容器
• 容器侧（Docker）按编号脚本顺序执行克隆、运行、提交、建 PR

下面按执行顺序逐步拆解。

三、第 1 步：创建分支并写入任务配置

流程的起点在 lib/tools/create-agent-job.js。当你提出一个任务时，系统会：

1. 用辅助 LLM 为任务生成一个约 10 个字的短标题
2. 读取main分支的最新提交和树哈希
3. 生成任务配置agent-job.config.json（含标题、任务描述、模型、用户 ID 等）
4. 在 GitHub 上基于main创建一个新提交，并指向一个全新的分支agent-job/<id>
5. 最后拉起一个本地 Docker 容器，开始后续工作

这一步的关键产物就是一条独立的agent-job/<id>分支——它是整个后台任务的「工作区」，之后所有改动都会落在它上面，互不干扰。

四、第 2 步：克隆代码并准备工作区

容器启动后，入口脚本 docker/coding-agent/entrypoint.sh 会按数字前缀顺序逐个执行agent-job目录下的脚本。

第 2 步由 2_clone.sh 完成：采用--single-branch --depth 1的浅克隆方式，只拉取任务分支所需的最小代码量，既快又省空间。

在此之前，1_setup-git.sh 已经根据 GitHub token 自动推导出了 git 用户名和邮箱，确保后续提交身份正确。

五、第 3 步：构建系统提示词与任务提示词

这是 AI「知道要干什么」的关键一步，对应 5_build-prompt.sh：

• 创建日志目录logs/<id>/，用于存放会话记录
• 读取任务配置，还原出预渲染好的系统提示词，写入SYSTEM.md
• 把任务描述包装成一句完整的任务提示词（PROMPT）交给 AI

系统提示词的模板来自 templates/agent-job/SYSTEM.md，它向 AI 说明了运行环境、目录结构、哪些文件可以编辑、哪些不能动等规则，让后台任务在「受限且安全」的边界内工作。

六、第 4 步：运行 AI 智能体干活

第 4 步由 6_agent-run.sh 驱动，它调用对应 AI（Claude Code、Codex、Gemini、OpenCode、Kimi 等）的run.sh，把上一步的提示词交给 AI 执行。

这一步会以完整权限模式运行，AI 会真正动手改代码、建文件、跑命令。整个过程的输出会被完整记录到日志目录，方便事后追溯。脚本会捕获 AI 的退出码（AGENT_EXIT），这一步的成败直接决定了下一步如何提交。

七、第 5 步：提交并推送

对应脚本 7_commit-and-push.sh，它有一个很巧妙的设计：

• AI 成功：把 workspace 里的所有改动全部提交并推送
• AI 失败：只提交会话日志，不带入任何半成品代码

推送完成后，它会把日志删除再推一次，避免日志文件混入主分支——日志只保留在独立的提交上，用于生成 PR 的查看链接。

八、第 6 步：创建 PR 并自动合并

最后一步由 8_create-pr.sh 完成：

1. 调用 GitHub CLI 创建一个 PR，标题带 🤖 标记，正文附上任务日志的永久链接
2. 若 AI 执行失败，容器会以非零码退出，让后台报告问题

PR 创建后，真正的「自动合并」由托管在仓库.github/workflows/下的auto-merge.yml工作流接管，合并完成后再由notify-pr-complete.yml私聊通知你。

这套自动合并的行为可以通过两个仓库变量精细控制，详见 docs/AUTO_MERGE.md：

比如把ALLOWED_PATHS设为/可让所有 AI 改动自动合并；设为/logs则只有日志变更会自动合并，其余一律留待人工把关。这样既享受自动化，又保留了对关键改动的审核权。

九、小结：一条链路，六个环节

把整条链路串起来看：

建分支+配置 → 克隆代码 → 构建提示词 → AI 干活 → 提交推送 → 建 PR + 自动合并 (create-agent-job.js) (2_clone) (5_build-prompt) (6_agent-run) (7_commit) (8_create-pr)

• 第 1 步在宿主机侧完成，产出一条独立agent-job/<id>分支
• 第 2~6 步在 Docker 容器内按编号脚本顺序执行
• 全程日志留痕、失败可追溯、合并可控

这就是 thepopebot 后台任务的全貌：你只说一句话，AI 就自动完成了从分支到 PR 合并的完整闭环。想了解更多架构细节，可参考 docs/ARCHITECTURE.md 与 docker/coding-agent/CLAUDE.md。