企业官网建设流程全解析

thepopebot 是一个自托管的个人 AI 智能体（autonomous AI agent）平台，它能聊天、写代码、跑后台任务。它最巧妙的设计是“一个会话三入口”：同一份工作里的浏览器聊天、代码工作区终端和无头后台任务共享同一个 AI 会话，你在任何一个入口说的话，另外两个入口都记得。今天就把这套共享机制拆开讲清楚。

三个入口，一个“大脑”

thepopebot 的核心是一个 Next.js 事件处理器（event handler），所有消息都从三个入口汇入同一个大脑：

官方架构图（README.md 中的 “Three doors, one brain”）把这一思想表达得非常直观：三条路最终都通向同一个 coding agent 会话。

核心机制一：会话文件充当“记忆锚点”

三入口共享的关键，是一个放在工作区卷（volume）里的按端口命名的会话文件：

• 路径规则：~/.{agent}-ttyd-sessions/<端口号>（如.claude-ttyd-sessions/7681）
• 7681是主终端端口，7682、7683… 是额外标签页
• 文件内容就一行：AI 编程助手的会话 ID

规则很简单：最后说话的人把下一个会话 ID 写进文件，接下来说话的人读出来并用它恢复（resume）会话。读写逻辑非常薄，只有几十行：lib/ai/session-manager.js 里的readSessionId()/writeSessionId()。

因为文件位于工作区卷上，容器可以随时销毁重建，会话记忆却一直在。工作区卷挂载在/home/coding-agent，既存代码也存会话数据（见 docker/coding-agent/CLAUDE.md 的 “Volume Mounts” 一节）。

核心机制二：CONTINUE_SESSION 统一开关

不是所有容器都允许碰这个会话文件——一次性命令容器（commit / push / create-pr 等）如果也写入，就会把正在聊天的会话覆盖掉。

thepopebot 用一个环境变量解决：CONTINUE_SESSION=1既是“允许恢复会话”的开关，也是“允许捕获会话 ID”的闸门。交互容器启动时会注入该变量（lib/tools/docker.js），而命令容器不注入，各 agent 的会话跟踪钩子（hook）检测到它未开启就直接跳过写入，互不干扰。

一句话：共享靠同一个文件，隔离靠同一个开关。

核心机制三：聊天路径的双通道同步

聊天消息统一流经chatStream()（lib/ai/index.js），然后分两条路，产出格式完全一致的流式数据块：

• SDK 进程内路径：仅 Claude Code 支持，直接在事件处理器进程内跑 SDK，会话 ID 通过session-manager.js写回卷里
• 容器路径：其余 agent（Codex、Gemini、Pi、OpenCode、Kimi）起一个临时无头容器，容器内部读同一个会话文件并原生恢复

难点在于 SDK 在宿主机进程里跑、容器在 Docker 里跑，两者的工作目录编码不同，会话文件位置对不上。lib/ai/sdk-adapters/claude-code.js 的ensureSessionSymlink()专门创建一条软链接，把“容器视角的路径”指向“SDK 视角的路径”——这样你在聊天里说的话，点开工作区终端时 agent 依然接着上次的话题，反之亦然。

另外，无头容器的run.sh固定只读主端口7681的会话文件，保证后台任务与交互会话始终落在同一条对话线上。

为什么容器重启后也不会“失忆”

除了会话文件，工作区终端本身由 tmux 承载、ttyd 提供 WebSocket 服务（入口脚本见 docker/coding-agent/scripts/common/start-ttyd-session.sh）。这带来两层持久性：

1. 浏览器断开：关闭标签页再打开，tmux 会话原样重连，进程、命令历史都在
2. 容器挂了：系统检测到容器停止/消失后，用同一个卷重建容器，启动脚本读到会话文件里的 ID，加上 agent 的恢复参数（--resume/--session/--continue，因 agent 而异）继续对话

每个 agent 的会话捕获方式不同（钩子、插件、按端口目录等五种模式），完整清单在 docker/coding-agent/CLAUDE.md 的 “Session Tracking” 章节，还附带了各 agent 的会话 ID 校验方式，防止用过期的 ID 恢复出错误。

实战场景：一次完整的“接力”

假设你在做某个功能分支的开发：

1. 🖥️ 在聊天里问：“这个报错怎么修？”——agent 在共享卷上边改代码边回答
2. 🖱️ 从聊天打开工作区，终端里 agent 已知道你刚问的问题，继续改
3. ✨ 改到一半要出门了？直接派一个无头任务：“把剩下的做完，开好 PR，完了给我发私信”——后台容器接着同一会话往下做，PR 合并后自动给你发通知

三个入口之间零配置切换，因为“记忆”从不在某个进程里，而是始终落在那个共享卷的会话文件上。

小结

thepopebot 的“一个会话三入口”并不神秘，靠的是三件小事：

• 一个按端口命名的会话文件当记忆锚点，谁最后说话谁写入
• 一个CONTINUE_SESSION开关，让共享与隔离各得其所
• 一条软链接，把进程内 SDK 与容器会话对齐

想深入看更多细节，推荐阅读 docs/ARCHITECTURE.md 的 “Live Chat Flow” 与 “One session, three surfaces” 段落、docs/CODE_WORKSPACES.md 的工作区生命周期说明，以及 lib/code/CLAUDE.md 的 “Session Continuity” 章节。理解了这套机制，你也就掌握了让 AI 智能体“换门不换脑”的设计思路。