Agent Store Backend 运行时文档

本文档基于当前 backend/ 源码实现整理，目标是把“今天这套代码到底怎么运行、怎么编排、怎么隔离、怎样保持会话连续性、哪些地方已经实现、哪些地方还需要补齐”说清楚。

文档目标

这本书重点说明以下问题：

• agent-store-sandbox-backend（云端运行时编排后端）如何接收 session（会话）、artifact（上传文件）、mount grant（挂载授权）和 run（一次运行）
• agentcore（Agent 核心运行时）与 agent package（开发者提供的 Agent 包）如何组合成一次真实运行
• 当前隔离粒度到底是“一个用户一个环境”“一个会话一个环境”还是“一个运行一个环境”
• 容器与宿主机、用户上传文件、本地 Helper 之间如何交换文件
• 一次运行从 API 请求到 K3s Job（Kubernetes 批处理任务）结束的完整生命周期是什么
• 同一 session（会话）内的历史、结果文件和可恢复状态如何保持连续
• 当前代码里哪些能力已经落地，哪些能力还属于下一阶段演进

文档中的统一术语

本文档统一使用下面这组术语：

• agentcore（Agent 核心运行时）：负责执行推理、文件操作、状态恢复、checkpoint、工具调用的运行时执行器。它可以是 Rust 二进制，也可以是镜像内的其它可执行入口。
• agent package（Agent 包）：开发者提供的提示词、工具声明、环境事实、策略和附带资源。
• RuntimeProfile（运行时配置模板）：描述基础镜像、容器入口、资源限制、安装策略和执行模式的模板。
• SessionRecord（逻辑会话记录）：保存同一会话的历史消息、默认包、状态和最近一次运行引用。
• RunRecord（一次运行记录）：保存一次真实运行的工作区、状态、K8s 资源引用和结果索引。

当前代码里的 RuntimeFamily::Codex、RuntimeFamily::ClaudeCode、codex-standard、claude-code-standard 这些名字仍会出现在源码和配置里。本文档把它们统一视为样例 runtime family / profile 标识符。从运行时架构角度，真正决定行为的是：

• 基础镜像 image
• 容器入口 executable
• 安装策略 installStrategy
• 执行模式 executionMode
• 工作区挂载与资源限制

也就是说，架构并不依赖 agentcore 的实现语言，差异主要体现在基础镜像和容器入口。

一句话结论

当前实现的物理隔离单元是一次 RunRecord（一次运行记录），它会被渲染成一个独立的 K3s Job 和一个独立 Pod；SessionRecord（逻辑会话记录）负责保存多轮历史和会话状态。

当前代码已经保证：

• 同一 session 内的对话历史连续
• 已上传文件和历史结果文件长期保留
• 用户关闭前端或关闭 session 后，后续仍可重新打开同一 session

当前代码还没有把“同一 session 的 agentcore checkpoint 目录”做成显式 API 和显式挂载元数据；文档会把这一点作为当前边界和建议方案写清楚。

必须先澄清的三个事实

1. 当前按 run 创建独立容器

同一个 SessionRecord（逻辑会话记录）会跨越多次 create_run（创建运行）。每一轮都会新建一个独立工作区、独立 Job、独立 Pod。前一轮结束后继续复用的是：

• SessionRecord.history（会话消息历史）
• ArtifactRecord（上传文件记录）
• 已落盘的历史结果文件
• 选定的 agent package
• 选定的 RuntimeProfile

2. 当前采用“共享运行时模板 + 按 run 注入 package”的模式

RuntimeProfile（运行时配置模板）提供共享的运行时底座；AgentPackageManifest（Agent 包清单）提供本次运行要注入的业务层资源；LaunchPlan（启动计划）把两者与当前工作区、当前 provider 凭据、当前挂载授权拼成一次独立运行。

3. 当前会话连续性主要来自持久化状态

当前代码里，会话连续性主要来自：

• SessionRecord.history
• SessionRecord.latest_run_id
• ArtifactRecord
• RunRecord
• backend/data/workspaces/<run-id>/out/ 下的结果文件

如果 agentcore 自带 checkpoint，建议把 checkpoint 写到持久化挂载目录，并由 backend 保存“session_id -> checkpoint_root”的索引；当前代码还没有把这块做成显式 API。

代码入口

如果要从源码反向阅读整个流程，建议按下面顺序看：

1. backend/src/main.rs
2. backend/src/lib.rs
3. backend/src/api/mod.rs
4. backend/src/service.rs
5. backend/src/k8s/mod.rs
6. backend/src/k8s/job_builder.rs
7. backend/src/storage/mod.rs
8. backend/src/provider.rs
9. backend/src/package/mod.rs

其中有两个 K8s 相关入口需要先记住：

• backend/src/k8s/mod.rs：通过 kube（Rust Kubernetes 客户端）执行 namespace、service account、job、pod、node 相关的读写和状态检查。
• backend/src/k8s/job_builder.rs：通过 k8s_openapi（Rust Kubernetes 资源类型定义）在内存里构造 ConfigMap、Secret、Job，再渲染成 YAML 或提交到集群。

接下来的章节会按这个顺序拆开讲。