从教学循环到可嵌入的 Runtime

起点：把 Agent 循环拆给学习者看

早期网站把 M-Agent 定位为教学型框架，重点是看清模型决策、工具调用与消息回填。那时的价值在于降低理解一个 Agent 循环的门槛。

随着问题转向真实应用集成，只解释“怎么跑一次”就不够了。工具可能已经写入外部系统，进程却在结果落盘前退出；模型输出、业务状态与执行日志也不能互相替代。Durable Run 开始成为项目的核心问题。这里描述的是产品问题的变化，不根据当前源码倒推每项早期能力的发布日期。

Durable Run 建立版本化定义、持久化 Run、SQLite 跨进程恢复、Tool Effect、有界重试和 WAITING。它回答：执行记录由谁保存？恢复能相信什么？通知结果不确定时谁来决定？

这一阶段的重要取舍是接受 at-least-once 的边界：已确认结果复用，未确认操作按性质处理，非幂等效果不确定时停下等应用。不是为所有工具加一个重试循环。具体机制见技术页。¹

Runtime Baseline 重置公共契约：根包保留高频 Run 门面，m_agent.runtime 定义 Core 契约，m_agent.adapters 提供实现，m_agent.companion 提供组合能力，m_agent.testing 提供离线验收包。

Core 不反向依赖其余三层。代价是旧调用方需要按迁移说明调整导入与契约，收益是更换模型或存储、加入会话能力，不必把所有功能塞进 Runner。类型化模型契约与 Metadata / Payload 分离也把集成边界表达得更明确。²

SessionRunner 在 Run 周围组织会话，SessionStore 保存成功对话历史，Run Store 保存单次执行事实。两者分开，避免把“再聊一轮”误当成“恢复上一轮”。

ContextPlan 与 CompressionContract 进一步把上下文准备、预算与语义压缩变成显式步骤。压缩使用独立的模型用途，有自己的成本与恢复记录，不偷偷改写已经确认的资料。这增加了配置与持久化成本，也让应用能检查模型到底看到了什么。²

Routing 在 create_run 之前根据能力、限制与应用策略选择 Agent Variant。选择结果可检查，但已启动的 Run 不在中途换模来绕开原有定义。

Eval 在独立的执行与存储边界组织评估、基线比较和回归检查；模型裁判与被评估 Run 隔离。README 将这一阶段称为 Runtime Foundation 的完成，意思是这些组合能力建立在同一套基础契约上，不是所有生产部署工作都已经完成。²

多个 Run 共享 SQLite 时，Context 和压缩步骤可能合法地产生相同的确定性 step_id。如果数据库只按步骤 ID 存储，它们就可能覆盖彼此。

0.5.1 把相关持久化身份限定在 Run 范围内，并明确旧数据库迁移、完整性检查与拒绝不支持布局的规则。这不是新增业务功能，而是修复“不同执行的事实必须独立”这个基础约束。³

四篇源码解析已收录全文与配套视频：

主题	文章需要回答的问题
Adapter：已发布	一次模型请求怎样归一化？一个 Store 怎样兑现持久化、版本、租约与内容保护契约？
Durable Run：已发布	执行如何持久化与恢复，哪些崩溃窗口仍有反例？
Companion：已发布	Session、Context、Routing 与 Eval 怎样围绕 Run 组合？各自保存什么，不能改写什么？
Testing：已发布	怎样制造真实崩溃、观察独立外部效果，再从测试断言形成有范围的验收结论？

四篇文章分别保留自己的源码基线与验证范围，不能把某篇的离线结果当作其他版本或生产环境的认证。后续新增内容优先补充跨文章的应用案例、版本差异和公开验证，而不是继续拆分顶层栏目。

设计页解释各层的职责，实验验证先展开 Durable Run 的故障证据。

版本说明基于 v0.5.1 的 README、迁移文档及用户提供的 Durable Run 源码解析。本次未对所有旧版本重新验收，不将旧基准或发布报告改标为新版本结果。