当前实现边界与演进建议

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

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 独立工作区
输出文件列举与安全读取
mount grant 白名单校验

1.4 多轮对话

已经具备：

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

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

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

当前代码已经连续保存：

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

当前代码还没有复用：

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

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

2.2 当前还没有显式的 session 级 checkpoint 模型

这是当前最需要被说清楚的边界。

今天的代码里：

每个 run 都有独立 workspace_root
历史结果文件会长期保留
会话历史会长期保留

今天的代码里还没有：

checkpoint_root 字段
session 级持久化状态卷
自动把上一轮 checkpoint 挂到下一轮
resume token / resume handle API

因此，如果 agentcore 本身支持 checkpoint，当前 backend 还需要再补一层“session 级状态目录索引”，才能把 agentcore 的内部状态恢复完整接上。

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 所在节点的本地磁盘
磁盘压力会直接影响调度
不适合做跨节点迁移
隔离强度弱于更高级的沙箱方案

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

FileBackedStore 使用本地：

state.json
uploads/
workspaces/

所以现在 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 当前没有“远端容器直接调用本地用户工具”的桥

这点必须明确写清楚。

当前没有：

本地 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 级状态目录

优先补齐：

checkpoint_root
session 级持久化状态卷
resume / restore API
输出文件到下一轮输入的受控提升机制

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

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

优先补齐：

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

5.3 第三优先级：补齐本地工具桥

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

5.4 第四优先级：把工作区从 `hostPath` 升级出去

重点是：

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

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

也就是逐步把：

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

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

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

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

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

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

session 级 checkpoint 连续性
本地工具桥
强权限
强网络策略
工作区存储外部化
控制面外部化持久存储

Keyboard shortcuts

Agent Store Backend Runtime Book