当前实现边界与演进建议

这一章用于把今天代码里已经实现到哪里、还没有实现到哪里，明确说清楚。

1. 当前已经实现的能力

1.1 控制面与状态管理

已经具备：

session、artifact、mount grant、run 的完整 API
SessionStatus 的 close / reopen 语义
x-user-id 基础所有权隔离
本地 state.json 持久化

1.2 运行时编排

已经具备：

RuntimeProfile 装载
agent package 装载
每 run 独立 K3s Job
package ConfigMap
provider Secret
Job / Pod 状态观察
集群节点健康与预检 API

1.3 文件管理

已经具备：

上传文件持久化
相对路径保留
每 run 独立工作区
session 级 runtime state 目录与 checkpoint 摘要同步
输出文件列举与安全读取
mount grant 白名单校验

1.4 多轮对话

已经具备：

SessionRecord.history 累积
已完成 run 的主回答回填
同一 session 的 reopen 后继续运行

2. 当前最重要的实现边界

2.1 当前 session 连续性来自持久化状态

当前代码已经连续保存：

对话历史
已上传文件
历史结果文件
run 元数据

当前代码还没有复用：

常驻容器进程
进程内缓存
shell 状态
工具服务进程

因此当前连续性属于“持久化状态连续”。

2.2 当前已经有 session 级 runtime state，但恢复能力还不完整

这是当前最需要被准确描述的边界。

今天的代码里：

每个 run 都有独立 workspace_root
历史结果文件会长期保留
会话历史会长期保留
每个 session 都有自己的 sessions/<session-id>/ 持久化状态目录
每次 run 都会把该目录挂到 /workspace/session
backend 会扫描 checkpoints/ 并把最近 checkpoint 摘要写回 SessionRecord.runtime_state

今天的代码里还没有：

restore / resume API
明确的 checkpoint retention / GC 策略
输出文件自动进入下一轮输入的受控规则
适用于多节点集群的 PVC / 对象存储抽象

因此，今天的 backend 已经能承载“同一 session 的状态目录连续”，但距离“平台级可恢复运行时”还差恢复接口、治理策略和跨节点存储抽象。

2.3 当前 runtime family 名称仍是样例标识符

当前源码里的 RuntimeFamily（运行时家族）枚举仍使用样例标识符，例如：

Codex
ClaudeCode

这不影响运行时架构本身，因为真正决定容器行为的是：

image
executable
installStrategy
executionMode

但它说明当前代码在“可扩展 family 标识”上仍有代码级约束。如果后续要把 runtime family 做成完全开放的扩展点，可以把它进一步放宽成字符串或可扩展枚举。

2.4 当前 K8s 资源回收和工作区回收还没有完全打通

当前 run 结束后：

Job / Pod 会被 TTL 或取消逻辑处理
workspace、artifact、run record、session history 会继续保留
正常完成态 run 的 ConfigMap 和 Secret 还没有统一 GC

因此如果后续 run 数量很多，需要补充后台 GC 或 retention policy，把：

旧 workspaces/
旧 uploads/
旧 ConfigMap
旧 Secret

纳入统一清理策略。

2.5 当前工作区基于 `hostPath`

hostPath 的优点是简单直观、便于单节点 K3s 验证。当前代价也很明确：

强依赖 backend 所在节点的本地磁盘
磁盘压力会直接影响调度
不适合做跨节点迁移
隔离强度弱于更高级的沙箱方案

另外，当前代码还没有 nodeSelector、affinity 或 PVC 绑定逻辑，因此多节点场景下默认仍应视为“单节点优先”设计。

2.6 当前 backend 采用本地持久化控制面

FileBackedStore 使用本地：

state.json
uploads/
workspaces/
sessions/

所以现在 backend 更像：

单实例控制面
方便联调和演示的最小实现

多副本水平扩展控制面和外部数据库支撑的生产级 control plane 还需要后续演进。

2.7 当前没有流式输出和事件推送

现在前端 / helper 获取 run 进度主要靠轮询：

GET /api/v1/runs/{id}
GET /api/v1/runs/{id}/results

当前没有：

WebSocket
SSE
stdout / stderr 实时流
token 级别的模型输出流

2.8 当前 run 仍然是 batch `Job`，不是交互式 session worker

当前 backend 的真实语义是：

一次 POST /runs 创建一次新的执行
K3s 拉起一个新的 Job / Pod
容器读取一次上下文后执行并退出

因此当前还没有：

一个长驻容器持续等待同一 session 的下一条消息
一个运行中的容器直接接收新的用户 prompt
一个运行中的容器等待审批或文件补充后继续

K3s 可以承载这类模式，但需要从“每 run 一个 Job”演进到“每 session 一个可回收 worker Pod”或“checkpoint 后冷恢复”。

2.9 当前没有“Pod 状态镜像化恢复”能力

当前没有：

把正在运行的 Pod 全状态 commit 成镜像的标准链路
把该镜像作为平台级恢复语义的控制面设计
依赖 runtime-level checkpoint / restore 的跨节点恢复方案

当前更现实的恢复语义仍然是：

新 Pod
重新挂载 session state
从 checkpoint 文件或 checkpoint 数据库恢复

因此如果后续真的需要“冻结当前运行态”，推荐优先冻结持久化状态，而不是冻结 Pod 本身。

2.10 当前没有“远端容器直接调用本地用户工具”的桥

这点必须明确写清楚。

当前没有：

本地 Git CLI 代理
本地 shell 代理
本地 IDE / editor RPC
本地文件系统 FUSE 挂载代理

macos-helper 当前只负责文件同步、结果回写和本地 UI 代理。

3. 支持本地工具调用的可行方案

虽然当前没有本地工具桥，但有几种可行方案可以接到现有架构上。

3.1 方案 A：Helper 本地工具 RPC 桥

最自然的方案是让 macos-helper（macOS 本地桥接服务）增加一个本地工具执行层：

helper 在本地暴露受控 RPC 接口
backend 在创建 run 时下发一组 session 级或 run 级工具描述
agentcore 通过受控 API 调用 helper
helper 在本机执行 Git、shell、编辑器脚本等工具
执行结果再回传给 agentcore

这个方案需要补齐：

工具白名单
参数校验
审批模型
超时和取消
审计日志
会话级认证

3.2 方案 B：Helper 反向长连接工具隧道

可以让 helper 主动和 backend 保持长连接，由 backend 把工具请求转发给 helper，再由 helper 本地执行。

这个方案的好处是：

后端不需要直接访问用户本机
连接模型更适合 NAT 后的用户机器

需要补齐的能力包括：

双向流式消息协议
工具请求队列
断线重连
session / run 级权限绑定

3.3 方案 C：本地只负责文件，同步后由远端容器执行

这是当前代码最接近的模式：

helper 只负责把本地目录同步成 artifact
远端容器只处理文件，不直接调用本地工具

它实现简单，安全边界清楚，但能力上限较低。

3.4 方案 D：受控宿主机工具代理

如果未来不仅要访问本地工具，还要访问 backend 所在 Linux 主机上的受控工具，也可以增加宿主机工具代理层。

这个方案需要非常严格的：

白名单
身份隔离
审计
资源限制

因为它的权限风险明显高于文件同步。

4. 当前架构为什么仍然是合理的

尽管上面有不少边界，但以当前代码目标来看，这套方案仍然成立，因为它先解决了最核心的几件事：

把 Agent 运行从 backend 进程里剥离到了独立容器
把 agent package、运行时模板、provider、workspace 拆成了清晰的组合关系
把 session 多轮上下文和 run 物理隔离分开建模
让前端、helper、backend、K3s 之间有了可验证的 API 契约

5. 如果继续演进，优先级建议是什么

5.1 第一优先级：补齐 session 级状态目录

优先补齐：

resume / restore API
checkpoint retention / GC 策略
输出文件到下一轮输入的受控提升机制
面向多节点的持久化卷抽象

这是把“会话历史连续”升级成“完整运行时状态连续”的关键一步。

5.2 第二优先级：把“声明型策略”变成“强执行策略”

优先补齐：

permissionProfile 到真实能力矩阵
networkProfile 到真实 NetworkPolicy
builtInTools 到真实工具调度层

5.3 第三优先级：补齐交互式等待与恢复模型

建议优先补齐：

WAITING_USER_INPUT、WAITING_APPROVAL、WAITING_ARTIFACTS
PendingAction 数据模型
冷恢复模式下的 resume API
job_ttl_seconds 和未来 session_idle_ttl_seconds 的区分
需要时再增加 warm sandbox 模式

这一步是把“连续对话”升级成“可中断、可等待、可恢复执行”的关键。

5.4 第四优先级：明确 checkpoint store 形态

建议优先明确：

checkpoint 是文件 / 嵌入式数据库
还是外部数据库服务

因为这会直接影响：

Pod 如何访问状态
是否必须引入 Service / Secret / 网络治理
是否还能继续沿用当前 /workspace/session 模型

5.5 第五优先级：补齐本地工具桥

建议优先落地 Helper 侧 RPC 桥，因为它和当前“本地 Helper + 云端 backend”结构最匹配。

5.6 第六优先级：把工作区从 `hostPath` 升级出去

重点是：

降低宿主机磁盘压力对调度的直接影响
支持更强的多节点与弹性调度
把 workspace 生命周期和 node 生命周期更好地解耦

5.7 第七优先级：把 backend 升级成可水平扩展控制面

也就是逐步把：

state.json
本地 uploads
本地 workspaces 元数据

迁移到更适合多副本的外部存储体系。

6. 当前技术方案的最终判断

如果基于当前源码评价，这套 backend 已经具备“Agent 商店运行时最小可用控制面”的完整骨架：

会话有了
文件有了
挂载有了
run 有了
K3s 编排有了
provider 注入有了
多轮历史有了
节点预检和状态观察也有了

当前离“生产级多租户高隔离 Agent Runtime 平台”的主要差距集中在：

session 级 checkpoint 连续性
交互式等待与恢复模型
checkpoint store 形态收敛
本地工具桥
强权限
强网络策略
工作区存储外部化
控制面外部化持久存储

7. [TODO] K3s 交互式运行改造清单

下面这些能力都可以建立在 K3s 之上，但今天还没落地：

TODO：为 run / session 增加阻塞态和超时态
TODO：增加 PendingAction、ApprovalRequest、ArtifactRequest 之类的控制面对象
TODO：支持 checkpoint 后退出、等用户事件后 resumed run 的冷恢复链路
TODO：支持可选 warm sandbox：Deployment 或 StatefulSet 承载每 session worker
TODO：为 warm sandbox 增加 Service、探针、心跳和空闲回收
TODO：把 builtin.ask_user 升级为真实工具而不是仅供模型参考的元数据
TODO：把权限审批统一收敛到 backend，而不是由容器内提示词自行决定
TODO：把 session state 和工作区从 hostPath 逐步迁移到更适合多节点的持久化存储
TODO：明确 checkpoint store 是文件型、嵌入式数据库型，还是外部数据库服务型
TODO：如果采用外部数据库服务，为其补齐 Service / Secret / 网络策略 / 恢复契约

Keyboard shortcuts

Agent Store Backend Runtime Book