Open Agents 会话管理指南：如何创建、恢复与归档编码任务-开发者社区

Open Agents 会话管理指南：如何创建、恢复与归档编码任务

【免费下载链接】open-agentsAn open source template for building cloud agents.项目地址: https://gitcode.com/GitHub_Trending/op/open-agents

Open Agents 是一个开源的云编码智能体（Coding Agent）参考应用，它的会话管理（Session Management）是整套系统的核心：每个会话绑定一个独立云沙箱，负责编码任务的创建、恢复与归档。本文带你快速看懂这三件事是如何运作的——从一条提示词到可运行的代码变更，全程无需保持笔记本参与。

先搞懂结构：会话（Session）与聊天（Chat）

Open Agents 是三层系统：

Web -> Agent workflow -> Sandbox VM

Web 层：负责登录、会话列表、聊天界面与流式输出；
Agent 层：作为持久化工作流（Workflow）运行，可跨多个持久化步骤执行；
沙箱层：执行环境，提供文件系统、Shell、Git 与开发服务器。

在数据模型中，一个 Session（会话）对应一个沙箱，而一个会话下可以挂多个Chat（聊天）。每次新对话就是新建一个 Chat，消息按时间持久化，会话可随时切回。相关定义见 schema.ts，数据库操作层在 sessions.ts。

创建编码任务：一个请求，三步完成

当你点击"新建会话"，前端会向POST /api/sessions发起请求，route.ts 中按顺序完成三件事：

安全防护：机器人识别 + 每用户每分钟 10 次的创建频率限制；
写入数据库：通过 createSessionWithInitialChat 在同一个事务里创建会话和初始聊天，状态置为running，沙箱状态为provisioning（准备中）；
异步拉起沙箱：调用kickSandboxProvisioningWorkflow启动供给工作流，克隆仓库、切换分支、准备执行环境。

几个贴心细节：

自动命名：不填标题时，系统会从随机城市名中挑选一个不重复的名称（random-city.ts），避免列表里一片"新会话"；
自动开新分支：开启isNewBranch后，系统按用户名缩写/随机后缀生成分支名，你的改动不会直接落在主干上；
可选自动化：可以按会话覆盖"自动提交推送"和"自动创建 PR"的偏好。

📌 想本地跑起来：git clone https://gitcode.com/GitHub_Trending/op/open-agents，然后bun install && bun run web。

恢复会话：快照休眠与唤醒机制

云沙箱不会永远开机——闲置 30 分钟后自动休眠，这是 Open Agents 会话恢复的关键。完整状态机见 SANDBOX-LIFECYCLE.md：

provisioning ──▶ active ──▶ hibernating ──▶ hibernated ▲ │ └──── 用户点击 Resume ───────┘

事件	系统行为
用户发消息	刷新`lastActivityAt`，顺延休眠倒计时
闲置满 30 分钟	打快照（snapshot）并停止沙箱，进入`hibernated`
用户点击 Resume	从快照恢复沙箱，继续之前的工作
会话归档	停止沙箱、清理快照，状态置为`archived`

恢复之所以无缝，是因为沙箱支持基于快照的恢复：文件系统、Git 分支、开发服务器状态都保存在快照里。核心评估逻辑在 lifecycle.ts，持久化工作流（能扛过部署与冷启动的"可存活睡眠"）在 sandbox-lifecycle.ts。

前端每 15 秒轮询GET /api/sandbox/status同步状态，状态芯片会显示Active / Paused / No sandbox，你随时知道沙箱是醒着还是睡了。

归档编码任务：保留记录，释放资源

任务完成后，归档会话是"善后"的标准动作。调用PATCH /api/sessions/[sessionId]（route.ts）将状态改为archived，底层执行 archive-session.ts 中的流程：

回刷 Git 状态：连上沙箱读取真实分支，查询 PR 最新状态（open / merged / closed），确保列表显示的是准确信息；
更新会话记录：状态与生命周期状态同步置为archived，清空过期时间等字段；
后台收尾：异步停止沙箱、清除快照 URL 与沙箱状态——聊天历史、Diff 缓存、PR 编号全部保留，随时可以在"已归档"标签页翻查（侧边栏逻辑见 inbox-sidebar.tsx）。

归档后的会话在侧边栏有独立的分页列表（默认每页 50 条，最多 100 条），既不打扰进行中的任务，也不丢失历史成果。✅

会话状态速查表

状态（lifecycleState）	含义	你能做什么
`provisioning`	沙箱准备中	等待克隆完成
`active`	沙箱运行中	正常对话、看 Diff
`hibernated`	已休眠	点击 Resume 恢复
`archived`	已归档	查看历史、翻找 PR
`failed`	异常	查看 lifecycleError 详情