K3s 运行时模块文档

本文档面向需要了解 K3s 运行时模块工作原理的所有人，包括产品经理、运维人员和对技术细节感兴趣的非开发人员。文档会在每个技术术语第一次出现时用“术语（中文解释）“的格式进行说明。

提示：文档中的流程图使用 Mermaid 语法。在 GitHub 上可直接渲染；本地使用 mdBook 阅读时，可安装 mdbook-mermaid 插件。

这个模块是什么

K3s 运行时模块是整个智能体商店（Agent Store）的执行引擎层。它负责：

• 把用户的一次“运行请求“变成一个真实运行在本地机器上的容器（Container，一种轻量级隔离运行环境）
• 管理容器的创建、监控和清理
• 确保每次运行之间互不干扰
• 保证同一个会话的多轮对话能够保持上下文连续

简单来说：后端控制面负责“决定做什么“，K3s 运行时模块负责“真正去做“。

统一术语表

下面这些术语会在后续文档中反复出现。建议先浏览一遍，后续遇到时可随时回来查阅。

核心设计理念

在阅读后续文档前，请先记住以下三个关键设计原则：

1. 逻辑连续按会话，物理隔离按运行：同一个 Session（会话）可以包含多次 Run（运行），每次运行都是一个全新的容器，但它们共享同一个会话状态目录。
2. 镜像层负责“能跑“，状态层负责“能续“：容器镜像只包含运行时环境和工具；用户数据、对话历史、检查点文件等状态信息存储在外部挂载的目录中。
3. 声明式编排，分层职责：后端只负责“声明需要什么资源“，真正创建和管理容器的是 K3s 系统本身。

文档阅读指南

本系列文档按照从整体到细节的顺序组织，建议按以下顺序阅读：

如需深入了解代码层面的模块拆分，还可以参考以下技术附录：

• backend 与 crate 的调用边界
• 输入输出契约（代码级）
• crate 内部模块职责