前言

为什么写这本书

AI Agent 正在从演示走向生产。但多数 Agent 框架的源码读起来像一组脚本：字符串拼接的 prompt、宽松的错误处理、随进程重启即消失的状态。做原型时这不碍事；一旦你要求 Agent 长驻运行、执行 Shell 与文件操作、同时服务多个租户，缺的就不是某个功能，而是操作系统级别的基础设施：权限边界、并发调度、可恢复的执行账本、可审计的协议。

octos 是一个用 Rust 构建的 AI Agent 操作系统。本书写作基线为主分支约 70 万行 Rust 源码、26 个 crate 的工作区，workspace 级 deny(unsafe_code)。它不是某种语言重写的调用链封装，而是从第一行代码起就为多租户隔离、生产可靠性、可扩展并发设计的系统：Provider 容错链自带凭据轮换与断路器（详见第 3 章），沙箱与权限走 fail-closed（详见第 7 章），长程任务有事件账本与续跑调度（详见第 12 章）。

第二版把全书从 14 章扩展到 21 章，并新增第四部分「双环」：外环（一个监督用的强模型与运维面）如何驱动内环（干活的一群模型）。octoscode 终端客户端、OctoLoop 外环协议 OLP v2、herdr 运维工具三章合起来回答一个问题——当便宜模型在内环干活时，谁来验收、谁在出错时接管。

这本书不是用户手册。它是一本工程决策解析：每章深入一个子系统，展示为什么这样设计、考虑过哪些替代方案、付出了什么代价。所有论断都给出源码引用，读者可以逐条到仓库里核对。

阅读准备

前置知识

• 必备：熟练使用一门主流编程语言（Python、Go、Java、C++ 皆可），能读懂代码，了解 HTTP 与 JSON。
• 有帮助但不强制：Rust 基础语法。第 2 章会用到 trait 与枚举，第 12 章会用到 async/await。不熟 Rust 的读者不必却步：第 1-2 章特意放慢节奏，语言相关的细节在侧栏与注释里就地解释，跳过不影响主线。
• 有帮助但不强制：LLM API 的基本概念（token、上下文窗口、工具调用）。没调用过 LLM API 也能读：第 3 章从 Provider 抽象讲起，概念随用随定义。
• 不需要：机器学习数学、模型训练经验、编译器原理、操作系统内核开发经验。

推荐阅读路径

路径 A：Rust 初学者（借一个真实的大型项目入门 Rust 与 Agent 工程）

Ch1 → Ch2 → Ch5 → Ch6 → 选读 先在 Ch1 理解为什么选 Rust，Ch2 看类型系统如何定义领域语言，Ch5 跟完一次对话的完整生命周期，Ch6 读工具派发。之后按兴趣选读：Ch8（上下文压缩）、Ch12（并发模型）都是好去处。给自己留出适应借用检查器的前两周。

路径 B：资深 Rust 开发者（关心大型 Rust 系统的架构与并发实现）

Ch1 → Ch3 → Ch12 → 深入 Ch1 的 workspace 拓扑与选型论证是全书的地图；Ch3 看 trait object 在 Provider 抽象上的取舍；Ch12 的三层并发调度（Tokio 层、supervisor 层、peer/lease 层）是本书并发叙事的核心。之后按方向深入：安全看 Ch7 与 Ch10，平台看 Ch14 与 Ch15，多 agent 内核看 Ch16-18。

路径 C：AI 应用开发者（从会调 API 到理解运行时内部）

Ch1 → Ch5 → Ch6 → Ch14 → Ch19 → Ch20 → Ch21 Ch5-6 回答「我发的消息到底经历了什么」，Ch14 讲清运行模式与配置后，直接进入双环部分：octoscode 客户端（Ch19）、外环协议 OLP v2（Ch20）、herdr 运维实务（Ch21）。Ch18 的 goal/peer 是 Ch20 的服务端前提，时间允许先读。跳过实现细节侧栏不影响理解。

路径 D：octos 贡献者（要给仓库提第一个 PR）

全书按序 + 附录 A 与附录 E 附录 A 的 26 crate 依赖图（63 条边）帮你定位改动影响面，附录 E 给出从源码构建与贡献流程。第 10 章的契约测试与事件 ABI 是多数 PR 绕不开的接口。

全书知识地图

graph LR
    subgraph P1["第一部分 地基"]
        C1["Ch1 为什么是 Rust"]
        C2["Ch2 octos-core 类型"]
        C3["Ch3 octos-llm"]
        C4["Ch4 octos-memory"]
        C1 --> C2
        C2 --> C3
        C2 --> C4
    end
    subgraph P2["第二部分 引擎"]
        C5["Ch5 Agent Loop"]
        C6["Ch6 工具系统"]
        C7["Ch7 安全纵深"]
        C8["Ch8 上下文管理"]
        C9["Ch9 扩展机制"]
        C10["Ch10 Harness"]
        C5 --> C6 --> C7
        C5 --> C8
        C6 --> C9
        C5 --> C10
    end
    subgraph P3["第三部分 平台"]
        C11["Ch11 octos-bus"]
        C12["Ch12 并发模型"]
        C13["Ch13 pipeline"]
        C14["Ch14 运行模式"]
        C15["Ch15 生产化"]
        C16["Ch16 Fleet"]
        C17["Ch17 Swarm"]
        C18["Ch18 Goal 与 Peer"]
        C5 --> C11 --> C14 --> C15
        C10 --> C12
        C12 --> C16 --> C17
        C12 --> C18
    end
    subgraph P4["第四部分 双环"]
        C19["Ch19 octoscode"]
        C20["Ch20 OctoLoop"]
        C21["Ch21 herdr"]
        C18 --> C20
        C19 --> C20 --> C21
    end
    subgraph APX["附录"]
        A1["A Crate 依赖图"]
        A2["B 工具速查"]
        A3["C 配置参考"]
        A4["D Feature Flags"]
        A5["E 构建与贡献"]
        A6["F OLP 速查与 E2E 追踪"]
    end
    C3 --> C5
    C4 --> C5
    C15 -.-> A1
    C19 -.-> A5
    C20 -.-> A6

两个阅读提示。其一，Ch5（Agent Loop）是全书枢纽：前四章是它的地基，第 6-10 章是它的展开，第 12、16、18 章的执行内核都以它为基准变体。其二，第三部分内部有两条线：Ch11-15 讲平台基础设施（消息、并发、工作流、配置、生产化），Ch16-18 讲多 agent 内核（Fleet、Swarm、Goal/Peer）；第四部分（Ch19-21）站在外环视角回看全书，第 20 章依赖第 18 章的服务端机制。

阅读标记说明

• 源码引用：全路径加行号，如 crates/octos-agent/src/agent/execution.rs:2483，可在源码仓库直接定位。仓库持续演进，行号会漂移，因此正文同时给出符号名（函数、类型、常量）；行号对不上时以符号名为锚。
• 三层标注体系（第 20 章引入）：描述一个机制时标注它由哪一层强制——协议条款（纯文档）、Markdown 约定（黑板、ACK 等无运行时代码的约定）、契约测试（对快照或真实子进程的机械校验）。这一区分最初用于外环协议 OLP v2，回读第三、四部分时同样适用：知道「谁在强制这条规则」才能判断违约时会发生什么。
• 工程决策侧栏：每章一个引用块（> 开头），比较 2-3 种替代方案的利弊，说明最终取舍的代价。
• 版本演化说明：每章末尾交代该子系统的机制如何随版本变化，帮助读者对照手头版本的差异。
• 章首定位：每章开头的一段引用块，写明本章前置依赖与适用读者，可据此快速判断是否跳读。
• Mermaid 图：架构图、状态机、时序图穿插正文，均可在支持 Mermaid 的阅读器中渲染。
• 思考题：每章末 2-5 道开放式问题，适合团队讨论或自测。

本书基准

版本基线：octos 主仓 main @ 9c157101（2026-09-02 统计）、octoscode @ 1129fa33、herdr feat/octoscode-agent 分支 @ fefe5c4f。全书规模与行号数字（26 crate、约 70 万行 Rust、63 条依赖边、各模块行数）取自各章事实表（assets/chNN-facts.md），逐条附复现命令，可在对应基线上核对。第 19-21 章涉及的三个仓库迭代很快，行号漂移属正常现象，引用以符号名为准。

愿这本书帮你建立的不只是对 octos 的理解，还有一套评估 Agent 基础设施的尺子。读任何 Agent 系统时，带着四问：

• 安全边界在哪：哪个进程、哪条系统调用、哪行代码在强制？
• 谁在强制协议：编译器、运行时、契约测试，还是仅有一份文档？
• 状态能否恢复：崩溃之后，重启到哪个断点，丢掉哪段工作？
• 错误去了哪里：被吞掉、被记录、被上报，还是被静默重试？

第 1 章：为什么是 Rust？为什么是 Agent OS？

定位：本章是全书开篇，回答两个根本问题：多租户 AI Agent 平台究竟难在哪里？为什么 octos 用 Rust 写、又为什么长成今天这个 26 个 crate 的形状？前置依赖：无。适合全部四类读者：A（Rust 初学者）能借此建立「Rust 在真实大型系统里解决什么问题」的直观图景；B（资深 Rust 开发者）可以直接跳到 1.3 节看 workspace 分层与依赖拓扑；C（AI/LLM 应用开发者，不要求 Rust 背景）重点读 1.1 的问题空间，即使最终选择 Python，这三大挑战也绕不过去；D（贡献者）请特别留意 1.3.3 的三处事实澄清，它们是读懂仓库结构的前提。

当你第一次打开 octos 的源码仓库，ls crates | wc -l 会给出 26；find crates -name '*.rs' | xargs wc -l | tail -1 会给出 700,915 行 Rust；根 Cargo.toml 的 members 列表有 38 个成员。这里躺着一个消息总线（17 个频道源文件）、一个 Agent 运行时（crates/octos-agent/src/tools/ 下 59 个工具源文件）、一个 DOT 驱动的流水线引擎、一个 Fleet 计划执行内核，以及供 Python/Swift/Kotlin/浏览器/Node 嵌入的整条绑定链。看到这些，从 LangChain 或 AutoGen 过来的开发者第一反应是质疑语言选型；看到满屏的 tokio::spawn 与 Arc<Mutex<_>>，Go 开发者则会怀疑 goroutine 是不是更省事。

这不是语言品味之争。当你把「AI Agent」从单用户玩具推向多租户生产平台，你面对的是一组相互纠缠的工程约束——安全隔离、并发、性能。任何一条单独看都不难，三条同时成立时，语言与工程组织的选型就从偏好问题变成了架构决策。本章先讲清楚这三大挑战（1.1），再论证为什么 Rust 是当前对这组约束最合适的答案（1.2），然后展开 octos 的 workspace 拓扑，为后续 20 章建立全局地图（1.3）。本章所有规模数字都标注了统计口径，均可按第 1.3.1 节给出的命令在源码仓库逐条复现。

1.1 问题空间：多租户 AI Agent 平台的三大挑战

octos 不是 chatbot 框架，而是一个多租户 AI Agent 操作系统：同一份进程要为多个用户、多个 Agent 实例服务，而每个 Agent 都能调用带副作用的工具：执行 Shell、读写文件、发起网络请求、再派生子 Agent。三大挑战正是从这里生长出来的。

1.1.1 挑战一：安全隔离，59 个工具源文件就是 59 个攻击面入口

设想一个真实场景：租户 A 的 Agent 在总结一篇网页时被 prompt 注入，恶意指令试图读取租户 B 的会话历史，或者执行 rm -rf /。在多租户环境里这不是理论风险。octos 的攻击面可以从事实表直接量化：crates/octos-agent/src/tools/ 下有 59 个工具源文件（口径：ls crates/octos-agent/src/tools/*.rs | wc -l）。注意这是源文件数，不是工具数，其中包含 crates/octos-agent/src/tools/mod.rs、crates/octos-agent/src/tools/registry.rs、crates/octos-agent/src/prompt_guard.rs 这类框架文件。

每个真正暴露给 LLM 的工具（shell、browser、web_fetch、write_file、spawn 等）都是一条独立的攻击路径。再加上 crates/octos-bus/src/ 下的 17 个 *_channel.rs 频道源文件（Telegram、Discord、Slack、WhatsApp、飞书、邮件、Matrix、企业微信、钉钉、QQ Bot、Twilio、Line 等；其中 crates/octos-bus/src/api_channel.rs 与 crates/octos-bus/src/cli_channel.rs 是两个内部通道，并非全部对外），平台在物理上就是「一张接满了外部消息网络的、能执行代码的图」。每接入一个频道，就多一个入站消息的信任边界；每注册一个工具，就多一个出站副作用的通道。

Agent 场景的安全隔离比传统 Web 服务难，原因有三：

1. 工具调用是核心能力而非旁路。Web 服务的危险操作通常收敛到少数几个 handler；Agent 的每一次循环迭代都可能触发任意工具组合，且调用序列由 LLM 生成、不可预先枚举。防御必须下沉到「每次调用」的粒度，octos 因此在工具层实现了 deny-wins 的策略引擎与审批流（详见第 6、7 章）。
2. Prompt 注入是新型攻击向量。它发生在自然语言层面，WAF 式的正则规则基本失效。攻击载荷可以藏在一篇被 web_fetch 抓回来的文档里，再借工具调用落地为文件写入或命令执行。
3. 隔离边界必须是进程级的。语言层的权限检查只能挡「合法 API 的滥用」，挡不住 Shell 命令本身。octos 把真正的沙箱子系统放在 octos-agent 内部的 crates/octos-agent/src/sandbox/（六个文件：crates/octos-agent/src/sandbox/bwrap.rs、crates/octos-agent/src/sandbox/docker.rs、crates/octos-agent/src/sandbox/landlock.rs、crates/octos-agent/src/sandbox/macos.rs、crates/octos-agent/src/sandbox/windows.rs、crates/octos-agent/src/sandbox/mod.rs），分别对接 Linux 的 bubblewrap/Landlock、Docker、macOS 的 sandbox-exec 与 Windows 的 AppContainer（crates/octos-agent/src/sandbox/mod.rs:1-23）。第 7 章会逐个拆解。

这三层防御（语言内存安全 → 工具策略 → 进程沙箱）能成立的前提，是承载它们的运行时本身不引入新的内存安全漏洞。这正是 1.2 节语言选型的第一个约束。

1.1.2 挑战二：并发，同一进程里的三重并发面

第二个挑战同样可以量化。Gateway 模式下，17 个频道的入站消息同时到达；octos 用一个 tokio::sync::Semaphore 把并发会话数压在配置上限内（默认 10，crates/octos-cli/src/config.rs:1633-1635），信号量在 Gateway 启动时创建（crates/octos-cli/src/commands/gateway/gateway_runtime.rs:1731-1732）：

#![allow(unused)]
fn main() {
// Semaphore to bound concurrent session processing
let concurrency_semaphore = Arc::new(Semaphore::new(gw_config.max_concurrent_sessions));
}

但「限流」只是并发的第一重。第二重在 Agent 循环内部：单次迭代里 LLM 可能一次下发多个工具调用，octos 把每个调用 tokio::spawn 成独立任务再 join_all 聚合、保持调用顺序（crates/octos-agent/src/agent/execution.rs:598 的 spawn_tool_task 与 :2483 的 execute_tools）。第三重在进程外：后台 Cron/Heartbeat 定时唤醒会话、子 Agent 同步阻塞或后台异步双模式、fleet worker 独立进程消费任务，它们共享同一套会话状态与消息总线。

并发本身不是问题，并发中的正确性才是：

• 会话级串行化：同一会话的两条消息不能并发改写状态，需要 per-session 锁序；
• 工具级并行：同一批次内互不依赖的工具必须并行，否则延迟线性叠加；
• 优雅关停：收到 SIGTERM 时不能腰斩进行中的对话，octos 用 AtomicBool 标志位贯穿信号处理与循环预算检查；
• 无共享不误会：派生出的任务（spawned task）不允许借用栈上状态，一切跨 .await 与跨任务的数据都必须显式所有权转移或 Arc。

这四条里任何一条写错，症状都不是「崩溃」而是「偶发的、无法复现的数据错乱」。在生产多租户平台上，这是最贵的一类故障。

1.1.3 挑战三：性能，LLM 慢不代表框架可以慢

「LLM 调用都要几秒钟，框架性能无所谓」是 Agent 工程里最流行的误解。它错在三个地方：

第一，延迟是乘性的。 一次 Agent 执行可能跑几十次迭代，每次迭代都有消息构建、上下文压缩、工具调度。框架层每迭代多 50ms，几十次迭代就是肉眼可见的卡顿。在流式场景里，这直接决定「打字机手感」的成败。

第二，内存是多租户的硬约束。 每个会话都持有对话历史、工具状态与上下文窗口。运行时本身每会话的开销乘上并发会话数，就是必须提前规划的容量：解释型运行时的每会话基线开销通常显著高于编译型，具体差多少要按目标并发数实测容量，100 个并发会话时这笔差值直接决定还能不能再挤进一个容器。

第三，热路径在框架里，不在 LLM 里。 SSE 流式解析、消息频道的分片切割、上下文压缩的截断、工具输出的尺寸估算，这些都在每次迭代里执行。octos-core 里有一个典型的小函数 truncate_utf8（crates/octos-core/src/utils.rs:6-16）：

#![allow(unused)]
fn main() {
pub fn truncate_utf8(s: &mut String, max_len: usize, suffix: &str) {
    if s.len() <= max_len { return; }
    let mut limit = max_len;
    while limit > 0 && !s.is_char_boundary(limit) {
        limit -= 1;
    }
    s.truncate(limit);
    s.push_str(suffix);
}
}

它做的事很小：在 UTF-8 字符边界安全截断。但它出现在消息裁剪、频道分片、工具输出限幅等所有热路径上。注意它接收 &mut String 原地截断而不是返回新分配的 String：在每条消息都可能被截断的路径上，省掉的是每次迭代里成千上万次的堆分配。这类「不惊人但无处不在」的开销，恰恰是框架性能的主体。

三大挑战讲完了。它们的共性是：都不能靠「写代码时小心」解决，必须靠语言与组织的结构性保证。这就引出语言选型。

1.2 语言选型：Python、Go 与 Rust 的四维对比

octos 的候选集其实只有三个：Python（LangChain/AutoGen 生态最厚）、Go（云原生并发最顺手）、Rust（安全与性能的上限最高）。下面按安全、并发、性能、生态四个维度逐一对照，结论先行：Rust 赢在前三维，输在第四维，而第四维的缺口可以用工程手段弥补。

1.2.1 安全维度：内存安全是防御纵深的第零层

1.1.1 节的三层防御中，最底层是「运行时自身无内存安全漏洞」。一个用 C/C++ 写的 Agent 运行时，沙箱做得再好，也可能在解析恶意构造的 SSE 分片或 WebSocket 帧时自己先倒下，因为解析不可信输入正是内存安全漏洞的高发区。octos 的做法很直接：workspace 根 Cargo.toml 统一 lint（Cargo.toml:50-51）：

[workspace.lints.rust]
unsafe_code = "deny"

一行配置，26 个目录、38 个成员全部继承，unsafe 在整个代码库被编译器拒绝（除非逐 crate 显式豁免）。Python 与 Go 在这一层各有姿态：Python 解释器由 C 实现，历史上多次出现解析恶意输入导致的内存安全 CVE；Go 自带内存安全，但 unsafe 包与 cgo 交界处同样存在失守面。Rust 的差异在于把「无 unsafe」变成可机器验证的全库不变量，而不是编码规约。

类型系统的另一重价值是「让非法状态不可表示」。Agent 领域最容易出 bug 的地方（消息角色的枚举、任务状态的迁移、工具结果的形状）在 octos-core 里都是穷尽匹配的 enum，漏一个分支编译不过。这比「运行时校验 + 测试覆盖」的防线提前了整整一个阶段。

1.2.2 并发维度：把数据竞争消灭在编译期

先看三段语言语义的对照（示意代码，非 octos 源码）：

// Go:两个 goroutine 并发自增。编译通过，数据竞争潜伏
go func() { counter++ }()
go func() { counter++ }()

# Python:CPython GIL 使线程无法并行执行 CPU 工作
threads = [threading.Thread(target=process_chunk) for c in chunks]

#![allow(unused)]
fn main() {
// Rust:同样的写法无法通过编译，借用在跨线程时必须显式
s.spawn(|| counter += 1);  // ❌ error: closure may outlive borrowed value
}

Go 的 goroutine 模型写起来最省事，但正确性依赖纪律与 -race 检测。race detector 基于 happens-before 算法，本质上是测试期工具，覆盖不到的路径不受保护。Python 的 GIL 则直接封死了「单进程多线程并行」这条路，asyncio 能处理 I/O 并发但一个同步调用就会卡住整个事件循环，多进程方案的序列化开销又与 1.1.2 要求的细粒度共享状态模型相抵触。

Rust 的答案是把并发正确性编码进类型系统：Send（可跨线程转移）与 Sync（可跨线程共享）两个 marker trait 由编译器自动推导，跨 .await 持有非 Send 的借用会直接编译失败。1.1.2 节那四条正确性要求（会话串行化、工具并行、优雅关停、任务不借用栈状态）在 Rust 里每一条都有对应的编译期保障形态。代价是学习曲线，收益是整类故障从生产事故清单上消失。

1.2.3 性能维度：无 GC 的确定性延迟

Agent 框架的性能画像很特殊：大量短生命周期分配（消息、分片、工具结果）、长驻任务（会话、频道连接）、以及必须平滑的流式路径（SSE 解析逐 token 转发）。GC 语言在这种画像下的典型症状是：停顿本身不频繁，但停顿发生在哪次迭代里不可预测：今天压测 p99 很好，明天某条会话的长对话触发大回收，流式输出肉眼可见地卡一下。

Rust 无 GC：分配与释放跟随着所有权在编译期确定，Drop 析构让文件描述符、子进程句柄、锁的释放都确定性地发生。1.1.3 节的 truncate_utf8 已经展示了「避免分配」的写法；再往上一层，octos-agent 的工具 trait 签名（crates/octos-agent/src/tools/mod.rs:609-642，节选）：

#![allow(unused)]
fn main() {
#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn input_schema(&self) -> serde_json::Value;
    async fn execute(&self, args: &serde_json::Value) -> Result<ToolResult>;
}
}

注意 Tool: Send + Sync 这个约束，它是 1.2.2 节的编译期并发保证在工具系统上的落点：任何工具实现想被注册进注册表并在多会话间共享，编译器就强制它证明自己线程安全。性能与并发两个维度在这里合流：同一个类型系统约束，同时买到了并行安全与零开销抽象。

1.2.4 生态维度与选型代价

诚实地说，生态是 Rust 的相对短板：LangChain/AutoGen 的教程与现成集成更丰富，Python 是 LLM 事实上的「胶水语言」；Go 在云原生基础设施（K8s 生态、指标、部署工具链）上更成熟。octos 的应对是把生态问题转化为架构问题。这解释了 1.3 节拓扑里的两条链。

第一条链向外接语言生态：octos-ffi（C-ABI）之下挂 octos-pyo3 / octos-uniffi / octos-wasm，让 Python、Swift/Kotlin、浏览器以原生绑定嵌入 octos，Python 生态的用户不必放弃 Python。

第二条链接能力生态：octos-plugin 让外部能力以 manifest + 二进制协议接入，app-skills 14 个能力二进制干脆零 octos-* 依赖、完全独立演进。Rust 只负责必须由 Rust 负责的核心，边缘留给各个生态自己。

选型的代价同样要写明：学习曲线陡（借用检查器对新人不友好，读者 A 请预期前两周的挫败感）；编译时间长（全量构建 70 万行代码需要耐心，增量构建与 26 crate 的拆分正是缓解手段）；部分领域库（如某些新兴协议的 SDK）需要自己写而不是 pip install。这些代价换来的是上面三个维度的结构性保证。对「多租户 + 可执行代码 + 长驻进程」这三类工作负载，Rust 的编译期保证收益大于生态成本。

1.3 Workspace 拓扑：26 个 crate 的八层地图

语言解决「怎么写得对」，workspace 解决「怎么长得对」。octos 用一个 Cargo workspace 组织 26 个顶层目录，本节先立统计口径，再按依赖方向推导分层，然后澄清三处最容易搞错的事实，最后给出完整的依赖拓扑图。

1.3.1 规模基准与统计口径

本章所有规模数字以源码仓库 main 分支 commit 9c157101（2026-09-02 统计）为准，逐条可复现：

26 与 38 的关系值得单独强调：目录数 ≠ 成员数 ≠ 核心库数。crates/app-skills/ 没有顶层 Cargo.toml，它是一个装着 14 个独立二进制 crate 的目录；platform-skills/ 装 1 个（voice）；octos-web 连 Rust 都没有。把这四个数字混为一谈，是外部读者对 octos 结构最常见的第一重误解。

1.3.2 八层分层：L0–L7 加一层「能力层」

分层由依赖方向推导得出：每个 crate 的层 = 1 + max(其 [dependencies] 中所有 octos-* 依赖的层)，零内部依赖者为 L0。按此规则，26 个目录落入 8 层（L0–L7）加一个不计层数的能力层：

• L0 基础层：octos-core（核心类型、任务模型与协议，22,313 行，全库的领域语言）、octos-plugin（插件 SDK：manifest 解析、发现、门控，5,165 行）、octos-sandbox（1,468 行；注意它是平台助手二进制，见 1.3.3）。
• L1 原语层（只依赖 core）：octos-bus（消息总线、17 个频道、会话管理，42,767 行）、octos-llm（Provider 抽象，35,087 行）、octos-memory（情景记忆，6,428 行）、octos-diagnostics（诊断与更新规划，2,243 行）、octos-store（自包含持久化存储，2,664 行）、octos-fleet（Fleet 内核存储：事务记录 + 单写事务 CAS + 恢复对账，16,888 行）、octos-wasm（浏览器端协议绑定，883 行）。
• L2 运行时层：octos-agent（Agent 运行时、工具执行与协调，191,985 行，全库心脏，依赖 core/bus/memory/llm/plugin）、octos-services（从 CLI 抽出的支撑服务，3,223 行）、octos-embed-llama（进程内 GGUF embedding，911 行）。
• L3 编排层（直接依赖 agent）：octos-pipeline（DOT 流水线引擎，32,799 行）、octos-swarm（fan-out/sequence/pipeline 编排原语，4,980 行）、octos-dora-mcp（dora 桥兼容 re-export，11 行）、octos-fleet-worker（封闭非交互任务 worker，6,842 行）。
• L4 工作流层：octos-workflows（依赖 pipeline，1,059 行）。
• L5 集成层：octos-server（HTTP/WebSocket API + 会话运行时，门面薄层仅 21 行）、octos-cli（CLI 入口，307,299 行，依赖 15 个 crate，是全库汇聚点）。
• L6 嵌入核心层：octos-ffi（C-ABI 绑定，1,372 行，依赖 cli/agent/llm/memory/embed-llama 等）。
• L7 绑定层：octos-uniffi（Python/Swift/Kotlin，465 行）、octos-pyo3（推荐 Python 绑定，756 行）。
• 能力层（不计层数）：app-skills（14 个能力二进制，合计 12,098 行）、platform-skills/voice（1,188 行）、octos-web（前端，0 行 Rust）。它们的共同特征：零 octos-* 依赖、不被任何 crate 依赖，因此不参与核心库分层。

两个行数悬殊值得停下来看一眼：octos-server 只有 21 行却站在 L5，因为它是纯粹的组装门面，真正逻辑全在下层 crate；octos-cli 占全库 44% 站在 L5，因为它是「前门」，把 15 个下层 crate 的能力装配成 chat/gateway/serve 等运行模式。层反映的是依赖深度，不是重要性，更不是代码量。

1.3.3 三处事实澄清：读仓库前先纠正三个印象

外部材料（包括本书 v1 版稿）对 octos 结构有三处系统性误传，读源码前必须纠正：

澄清一：octos-sandbox 不是沙箱子系统。 它的 Cargo.toml description 是 "Platform sandbox helper for octos"，1,468 行，[dependencies] 只有 clap 和 eyre，零 octos-* 依赖。它是随平台分发的辅助二进制。真正的沙箱在 octos-agent 内部：crates/octos-agent/src/sandbox/ 下六个文件（crates/octos-agent/src/sandbox/bwrap.rs、crates/octos-agent/src/sandbox/docker.rs、crates/octos-agent/src/sandbox/landlock.rs、crates/octos-agent/src/sandbox/macos.rs、crates/octos-agent/src/sandbox/windows.rs、crates/octos-agent/src/sandbox/mod.rs），覆盖 Linux bubblewrap/Landlock、Docker、macOS sandbox-exec、Windows AppContainer 与无沙箱回退（crates/octos-agent/src/sandbox/mod.rs:1-23）。谈「octos 沙箱」，指的永远是 octos-agent::sandbox。

澄清二：octos-web 不含 Rust、不是 workspace 成员。 它是 TypeScript 项目（package.json/tsconfig.json/vitest.config.ts），0 个 .rs 文件；根 Cargo.toml 的 members 里 grep 不到 octos-web。它是前端静态资源，不在 Cargo 依赖图内，拓扑图里它是孤立节点。

澄清三：不存在 harness crate。 ls crates | grep harness 零命中。harness 是 octos-agent 内部的模块：crates/octos-agent/src/lib.rs:30-31 声明 pub mod harness_errors; 与 pub mod harness_events; 两个平级模块文件。别把 app-skills/harness-starter-* 四个脚手架当成 harness 本体，它们是面向用户的起步模板，不是 harness 实现。第 10 章会专门讲 Harness。

1.3.4 依赖拓扑图：63 条边一张图

下图是整个 workspace 的依赖拓扑，63 条依赖边一条不多、一条不少，每条边都来自对应 crate Cargo.toml 的 [dependencies] 段（机器核对命令：awk '/^\[dependencies\]/{f=1;next} /^\[/{f=0} f && /^octos-/' crates/*/Cargo.toml | wc -l → 63）。方向为 A --> B 即 A 依赖 B，graph BT 自底向上读：越靠上的 crate 越靠近用户。

graph BT
  subgraph L0["L0 基础层"]
    core[octos-core]
    plugin[octos-plugin]
    sandbox[octos-sandbox<br/>平台助手二进制]
  end
  subgraph L1["L1 原语层"]
    bus[octos-bus]
    llm[octos-llm]
    memory[octos-memory]
    diag[octos-diagnostics]
    store[octos-store]
    fleet[octos-fleet]
    wasm[octos-wasm]
  end
  subgraph L2["L2 运行时层"]
    agent[octos-agent]
    services[octos-services]
    embed[octos-embed-llama]
  end
  subgraph L3["L3 编排层"]
    swarm[octos-swarm]
    dora[octos-dora-mcp]
    fworker[octos-fleet-worker]
    pipeline[octos-pipeline]
  end
  subgraph L4["L4 工作流层"]
    workflows[octos-workflows]
  end
  subgraph L5["L5 集成层"]
    server[octos-server]
    cli[octos-cli]
  end
  subgraph L67["L6/L7 嵌入与绑定层"]
    ffi[octos-ffi]
    uniffi[octos-uniffi]
    pyo3[octos-pyo3]
  end
  subgraph CAP["能力层 / 前端（孤立，不计层数）"]
    appskills[app-skills<br/>14 个能力二进制]
    platskills[platform-skills/voice<br/>能力二进制]
    web[octos-web<br/>前端静态资源<br/>不在依赖图]
  end

  bus --> core
  llm --> core
  memory --> core
  diag --> core
  store --> core
  fleet --> core
  wasm --> core
  agent --> core
  agent --> bus
  agent --> memory
  agent --> llm
  agent --> plugin
  services --> core
  services --> llm
  services --> bus
  embed --> llm
  swarm --> agent
  dora --> agent
  fworker --> agent
  fworker --> core
  fworker --> fleet
  fworker --> llm
  fworker --> memory
  pipeline --> core
  pipeline --> agent
  pipeline --> plugin
  pipeline --> llm
  pipeline --> memory
  workflows --> core
  workflows --> agent
  workflows --> pipeline
  server --> core
  server --> agent
  server --> llm
  server --> bus
  server --> store
  server --> services
  server --> workflows
  server --> pipeline
  server --> plugin
  cli --> core
  cli --> bus
  cli --> llm
  cli --> memory
  cli --> agent
  cli --> diag
  cli --> store
  cli --> services
  cli --> workflows
  cli --> pipeline
  cli --> swarm
  cli --> plugin
  cli --> fleet
  cli --> fworker
  cli --> embed
  ffi --> core
  ffi --> agent
  ffi --> llm
  ffi --> memory
  ffi --> cli
  ffi --> embed
  uniffi --> ffi
  pyo3 --> ffi

读图要点：（1） octos-core 是唯一被 15 个 crate 依赖的根，它必须保持零内部依赖与极高稳定性（第 2 章的主题）。（2） octos-agent 被 8 个 crate 依赖（pipeline、swarm、dora-mcp、fleet-worker、workflows、server、ffi、cli），是事实上的第二枢纽。（3） 四个孤立节点（app-skills、platform-skills/voice、octos-web、octos-sandbox）不在 63 条边内：能力二进制与前端通过进程边界而非 Cargo 依赖接入，这正是它们「不属于核心库分层」的形式化表述。（4） 依赖全部指向下方，无环；新增任何一条向上的边都会在 cargo 那里直接报错，分层是被工具链强制的不变量。

工程决策侧栏：mono-repo workspace vs multi-repo

26 个 crate、63 条内部依赖边，摆在面前的组织方案至少有三种：

方案 A：multi-repo，每 crate 一仓。 优点：权限边界清晰、每仓可独立发版与裁剪 CI、外部贡献者 clone 面小。缺点对 octos 是致命的：63 条边意味着跨仓改动是常态而非例外：改一处 octos-core 的类型定义会波及 15 个下游 crate，multi-repo 下你要开 16 个 PR、维护 16 个版本号与 16 份 lockfile，跨仓原子重构不可能，CI 还要在每仓重复编译公共依赖。语义化版本挡不住「接口变了但版本没升对」的人祸。

方案 B：single mega-crate。 把全部 70 万行塞进一个 crate。优点：无跨 crate 版本问题、重构随便改。缺点同样致命：编译时间失控（任何一行改动触发全量重编）；octos-web 这类非 Rust 资产无处安放；app-skills 的 14 个二进制会被迫拖上全部核心依赖（它们本来零 octos-* 依赖）；feature flag 组合爆炸，任何一个模块开错 feature 都可能污染全局编译。

方案 C（octos 的选择）：Cargo workspace mono-repo。 既保留了单仓的原子性（跨 crate 重构是一个 commit、一次 CI），又用 crate 边界保住了编译隔离与依赖方向：根 Cargo.toml 统一 members（38 项）、统一 workspace.package（version/edition 2024/rust-version 1.85.0）、统一 workspace.lints（unsafe_code = "deny" 一处生效全库）、统一 workspace.dependencies 管内部 path 依赖版本。分层靠 [dependencies] 的方向自然成立，cargo 本身就是架构守护者。

附带的工程红利：能力二进制（app-skills/platform-skills）作为 workspace 成员享受统一工具链，却因零 octos-* 依赖而不进入核心编译图；将来若某个 crate 需要独立演进，从 workspace 拆出也远比从 mega-crate 拆出便宜。取舍：mono-repo 的代价是仓库体积增长、CI 必须做分层缓存、外部贡献者面对的是一棵 26 目录的大树，octos 用目录分层（1.3.2）与本书的导航（1.4）来对冲。

1.4 全书导览

本书 v2 版按「地基 → 引擎 → 平台 → 双环」四部分展开，共 21 章 + 附录。编号以 v2 重写计划为准（相对 v1 有平移：原第 10 章 bus 移至第 11 章，第 10 章成为新增的 Harness 章）：

阅读路线建议：A 类读者按顺序读，Ch1–Ch5 建立 Rust + Agent 的双基础；B 类读者可跳过语言论证直达 Ch5、Ch12、Ch16；C 类读者优先 Ch1、Ch7、Ch11、Ch13，跳过实现细节侧栏；D 类贡献者请先读完本章与附录 A 再动第一个 PR。

1.5 本章回顾

1. 问题空间：多租户 AI Agent 平台的安全隔离（59 个工具源文件 + 17 个频道的攻击面）、并发（会话/工具/进程三重并发面的正确性）、性能（乘性延迟、多租户内存、框架热路径）三大挑战相互纠缠，决定了选型是架构决策。
2. 语言选型：Rust 在安全（全库 deny(unsafe_code) + 类型系统）、并发（Send/Sync 编译期保证）、性能（无 GC、确定性析构、零分配热路径）三维胜出；生态短板用 FFI/绑定链（pyo3/uniffi/wasm）与 plugin/skill 扩展机制对冲。
3. Workspace 拓扑：26 目录 = 23 个 octos-* crate + 2 个技能目录 + 1 个前端目录；38 个 workspace 成员按依赖方向落入 L0–L7 八层加不计层数的能力层；63 条依赖边无一环、全部向下。octos-sandbox 是助手二进制（真沙箱在 octos-agent::sandbox 六文件）、octos-web 非 Rust 非成员、harness 是 octos-agent 内模块而非 crate，三处澄清是读仓库的正确起点。

从下一章开始自底向上：先看 L0 的 octos-core 如何用类型系统为整个平台定义领域语言。

延伸阅读

• Cargo Workspaces：官方文档 "Workspaces" 章，https://doc.rust-lang.org/cargo/reference/workspaces.html ，对照 1.3 的 members/lints/dependencies 继承机制。
• Rust 所有权与并发：The Rust Programming Language Ch4 "Understanding Ownership" 与 Ch16 "Fearless Concurrency"，https://doc.rust-lang.org/book/ ，Send/Sync 的推导规则。
• Tokio 教程：https://tokio.rs/tokio/tutorial ，Ch12 并发模型的前置。
• OWASP Top 10 for LLM Applications：https://owasp.org/www-project-top-10-for-large-language-model-applications/ ，prompt 注入与 Agent 安全的威胁分类。
• 本书附录 A：26 crate 完整依赖图（本章拓扑图的全量版）。

思考题

1. 攻击面估算：以 1.1.1 的口径为方法，为一个「接入 3 个频道、注册 20 个工具」的自建 Agent 服务估算攻击面：哪些边界需要独立信任模型？哪一层最薄弱？
2. 并发的编译期 vs 运行期：Go 的 -race 检测与 Rust 的 Send/Sync 各自兜住哪类错误、漏掉哪类？如果团队从 Go 迁到 Rust，哪些测试可以删，哪些必须保留？
3. 层数权衡：octos 的 L6/L7（ffi → uniffi/pyo3）拆成两层，而不是让 pyo3 直接依赖全部核心 crate。这样拆让什么变贵、让什么变便宜？如果明天要加一个 Kotlin 绑定，改哪一层？
4. 能力层的隔离价值：app-skills 的 14 个二进制零 octos-* 依赖。这带来什么工程性质？如果让它们直接依赖 octos-agent，编译图与发布节奏会发生什么变化？
5. 组织镜像：对照 1.3.4 的拓扑图，为一个你熟悉的系统画出同样的依赖图。它的分层是像 octos 一样被工具链强制，还是只存在于文档里？差异会带来什么长期后果？

版本演化说明

本章分析基于 octos main @ 9c157101（2026-09-02 统计）的 26 crate 工作区；所有规模数字（26 目录、38 成员、700,915 行 Rust、17 个频道源文件、59 个工具源文件、63 条依赖边）的统计口径与复现命令见 assets/ch01-facts.md，逐条可在源码仓库核对。

相对本书 v1 旧稿，本章作了三类更新。其一，三处事实纠正：octos-sandbox 是平台助手二进制而非沙箱子系统（真沙箱是 octos-agent::sandbox 的六个文件）；octos-web 不含 Rust、不是 workspace 成员；不存在 harness crate，harness 是 octos-agent 内部的 harness_errors/harness_events 模块。其二，拓扑层数更新：旧稿的四层架构与核心 crate 数口径作废，v2 按 [dependencies] 依赖方向推导为 L0–L7 共 8 层加不计层数的能力层。其三，全书结构调整：Harness 独立成第 10 章，原第 10 章 bus 平移至第 11 章，第 16 章起为新增章。

第 2 章：octos-core：用类型系统定义领域语言

定位：本章深入 octos 最底层的 crate octos-core（当前 22,313 行 Rust 源文件，剔除 crates/octos-cli/src/api/ui_protocol_tests.rs 测试后约 15,005 行，主要增长来自 UI Protocol wire 类型），展示如何用 Rust 类型系统构建 AI Agent 平台的领域语言。前置依赖：第 1 章。适用场景：想理解 octos 类型基础的所有读者，尤其是希望通过实战项目学习 Rust 枚举和错误处理设计的读者（读者 A），以及想了解"零依赖 core crate"设计哲学的资深开发者（读者 B）。

如果把 octos 比作一座城市，octos-core 就是它的语言——不是建筑、不是道路，而是居民用来交流的词汇和语法。Task、Message、MessageRole、Error、UI Protocol wire 类型，这些类型定义了系统中所有组件如何描述自己的状态和意图。octos 的上层 crate 都依赖这些类型，但 octos-core 本身不依赖 workspace 中的任何其他 crate。

这个零依赖约束不是偶然的。它是一个刻意的架构决策，确保领域语言演进时仍保持清晰边界：当 octos-llm 重构 Provider 实现或 octos-bus 调整频道时，core 只承接真正跨 crate 的 wire identity 与 domain model，而不吸收上层实现逻辑。本章将从 Task 状态机开始，逐个解析这些基础类型的设计，最后讨论这个零依赖策略的工程意义。

2.1 Task 状态机：用枚举编码合法状态

每个 AI Agent 执行的工作在 octos 中被建模为一个 Task。Task 是整个系统的工作单元：从"帮我写一段代码"到"审查这个 diff"，所有用户请求最终都被转化为 Task。

2.1.1 Task 结构体

Task 的定义位于 crates/octos-core/src/task.rs:11-29：

#![allow(unused)]
fn main() {
pub struct Task {
    pub id: TaskId,                      // UUID v7，自带时间排序
    pub parent_id: Option<TaskId>,       // 子任务层级
    pub status: TaskStatus,              // 当前状态
    pub kind: TaskKind,                  // 任务类型
    pub context: TaskContext,            // 执行上下文
    pub result: Option<TaskResult>,      // 完成后的结果
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}
}

几个值得注意的设计选择：

TaskId 使用 UUID v7 而非 v4（crates/octos-core/src/types.rs:180-189）。UUID v4 是纯随机的，而 v7 的前 48 位编码了毫秒级时间戳。这意味着 TaskId 天然按创建时间排序：在调试和日志分析中，你可以直接通过 ID 判断任务的先后顺序，无需额外查询 created_at 字段。

parent_id: Option<TaskId> 支持任务层级。当一个复杂任务需要分解为多个子任务时（例如，Pipeline 中的多步骤执行），每个子任务通过 parent_id 指向父任务，形成树状结构。

result: Option<TaskResult> 只在 Task 完成后存在。这利用了 Rust 的 Option 类型在编译期强制调用者处理"结果可能不存在"的情况：你无法在未检查的情况下访问一个 Pending 状态 Task 的结果。

2.1.2 TaskStatus：编译期防止非法转换

TaskStatus 是一个带数据的枚举（crates/octos-core/src/task.rs:63-77）：

#![allow(unused)]
fn main() {
pub enum TaskStatus {
    Pending,
    InProgress { agent_id: AgentId },
    Blocked { reason: String },
    Completed,
    Failed { error: String },
}
}

注意 InProgress 变体携带 agent_id，这不只是状态标记，还记录了谁在执行这个任务。同样，Blocked 携带阻塞原因，Failed 携带错误信息。这种"状态 + 上下文数据"的组合是 Rust 枚举相比其他语言的 enum（如 Go 的 iota 常量或 Java 的传统 enum）的核心优势。

在 Python 中，你可能会用一个字符串字段 status: str 加上几个可选字段 agent_id: Optional[str]、error: Optional[str] 来表达同样的语义。但这种设计允许非法状态：比如一个 status="pending" 但 agent_id="agent-1" 的 Task，或者 status="completed" 但 error="something failed" 的 Task。Rust 的枚举让这些状态在类型层面就不可能存在。

2.1.3 状态转换图

Task 的合法状态转换如下：

stateDiagram-v2
    [*] --> Pending: 创建
    Pending --> InProgress: 分配给 Agent
    InProgress --> Blocked: 等待外部资源
    InProgress --> Completed: 执行成功
    InProgress --> Failed: 执行失败
    Blocked --> InProgress: 阻塞解除
    Blocked --> Failed: 超时或取消

图 2-1：Task 状态机。 每个状态转换对应一个明确的业务事件。注意 Pending 只能转向 InProgress（不能直接跳到 Completed），InProgress 是唯一可以到达 Completed 的路径。这确保了每个完成的任务都经历过执行阶段。

2.1.4 TaskKind：五种任务类型

TaskKind 定义了五种工作类型（crates/octos-core/src/task.rs:79-99）：

#![allow(unused)]
fn main() {
pub enum TaskKind {
    Plan { goal: String },
    Code { instruction: String, files: Vec<PathBuf> },
    Review { diff: String },
    Test { command: String },
    Custom { name: String, params: serde_json::Value },
}
}

前四种是预定义的常见场景：规划（Plan）、编码（Code）、审查（Review）、测试（Test）。第五种 Custom 是扩展点：通过 name 标识任务类型，params 携带任意 JSON 数据。这种"有限预定义 + 开放扩展"的模式在 octos 中反复出现（详见第 6 章工具系统和第 9 章扩展机制）。

2.1.5 TaskContext 与 TaskResult

TaskContext（crates/octos-core/src/task.rs:102-115）是任务执行时的环境快照：

#![allow(unused)]
fn main() {
pub struct TaskContext {
    pub working_dir: PathBuf,
    pub git_state: Option<GitState>,      // 分支、未提交变更、HEAD commit
    pub working_memory: Vec<Message>,      // 近期对话轮次
    pub episodic_refs: Vec<EpisodeRef>,    // 过往 episode 引用
    pub files_in_scope: Vec<PathBuf>,
}
}

working_memory 和 episodic_refs 的区别值得关注：working_memory 是当前会话的短期记忆（最近几轮对话），而 episodic_refs 是从长期记忆中检索出的相关片段（详见第 4 章）。这种双记忆架构模仿了人类的工作记忆（working memory）和情景记忆（episodic memory）的区分。

TaskResult（crates/octos-core/src/task.rs:125-157）记录任务的产出，共 7 个字段：schema_version（durable ABI 版本，见 2.3 节）、success、output、files_modified、files_to_send、subtasks、token_usage。

TokenUsage（crates/octos-core/src/task.rs:159-173）值得特别关注。它不只追踪 input/output tokens，还包含 reasoning_tokens（思维链 token，用于 o1、kimi-k2.5 等推理模型）和 cache_read_tokens/cache_write_tokens（Provider 缓存命中/写入）。这五个维度让上层可以精确计算成本和优化缓存策略。序列化时，为零的字段会被跳过，避免 JSON 膨胀。

2.2 Message 与 MessageRole：跨 Provider 的统一抽象

AI Agent 平台需要对接多个 LLM Provider：Anthropic 的 Claude、OpenAI 的 GPT-4、Google 的 Gemini、本地的 Ollama。每个 Provider 的 API 对消息角色的命名和语义略有不同。octos-core 定义了统一的 Message 和 MessageRole 类型，作为所有 Provider 的公约数。

2.2.1 Message 结构体

Message 的定义位于 crates/octos-core/src/types.rs:227-258：

#![allow(unused)]
fn main() {
pub struct Message {
    pub role: MessageRole,
    pub content: String,
    pub media: Vec<String>,                         // 图片/音频文件路径
    pub tool_calls: Option<Vec<ToolCall>>,           // LLM 请求的工具调用
    pub tool_call_id: Option<String>,                // 工具响应对应的调用 ID
    pub reasoning_content: Option<String>,           // 思维链内容
    pub client_message_id: Option<String>,           // 客户端乐观 UI / 幂等 token
    pub thread_id: Option<String>,                   // AppUI thread 渲染分组 key
    pub timestamp: DateTime<Utc>,
}
}

media 字段（crates/octos-core/src/types.rs:232-234）支持多模态：当用户发送图片或语音时，文件路径存储在这里，由 octos-llm 在构建 API 请求时转换为对应 Provider 的格式（base64 编码或 URL 引用）。序列化时，空的 media 向量会被跳过。

reasoning_content（crates/octos-core/src/types.rs:239-241）是为推理模型（如 OpenAI o1、Kimi k2.5）设计的：这些模型会先输出一段内部推理过程，然后才给出最终回答。将推理内容与正式回答分离存储，让上层可以选择是否展示思维链。

client_message_id 和 thread_id 是当前主分支里很重要的 UI / 持久化 identity 字段（crates/octos-core/src/types.rs:229-256）。它们不是 Provider 消息格式的一部分，而是 AppUI、Gateway、Session 持久化共同依赖的跨 crate 协议字段：前者用于把客户端乐观 UI 气泡和服务端持久化 seq 对齐，后者用于把 user / assistant / tool 消息归入同一个渲染 thread。

2.2.2 Message identity：ClientMessageId、ThreadId、TurnId 不能混用

当前源码把三种看似相近的 identity 拆成三个不同类型：

flowchart LR
    C[ClientMessageId<br/>client optimistic identity] --> T[ThreadId<br/>render grouping]
    U[User Message] --> C
    U --> T
    A[Assistant / Tool Message] --> T
    R[TurnId<br/>server protocol identity] -. distinct .- T
    R -. distinct .- C

这个分离是一次真实 bug 链的类型化修复。ClientMessageId 和 ThreadId 都包的是 String，但语义完全不同；TurnId 则是 UUID 形态的协议 identity。把它们做成 newtype，可以让编译器阻止“把 client message id 当 turn id 用”这类错误（crates/octos-core/src/types.rs:12-177，crates/octos-core/src/ui_protocol.rs:607-623）。

Message 也提供了显式绑定构造函数：

#![allow(unused)]
fn main() {
pub fn user_with_cmid(content: impl Into<String>, cmid: ClientMessageId) -> Self
pub fn user_rooting_thread(content: impl Into<String>, cmid: ClientMessageId) -> Self
pub fn assistant_with_thread(content: impl Into<String>, thread_id: ThreadId) -> Self
pub fn tool_with_thread(content: impl Into<String>, tool_call_id: impl Into<String>, thread_id: ThreadId) -> Self
}

其中 assistant_with_thread() 和 tool_with_thread() 要求调用方显式传入 ThreadId（crates/octos-core/src/types.rs:310-350）。这和 Ch10 的 Session 写入规则是一致的：Assistant/Tool 新写入不能再靠“回看最近一个 user”来猜 thread，因为并发 turn 下这个猜测会把 late delta 或工具结果归到错误气泡。core crate 在类型层先表达这个约束，上层持久化路径再 fail closed。

2.2.3 MessageRole：as_str() 与 Display 的双重实现

MessageRole 只有四个变体（crates/octos-core/src/types.rs:444-451）：

#![allow(unused)]
fn main() {
pub enum MessageRole {
    System,
    User,
    Assistant,
    Tool,
}
}

关键在于它的两个方法实现。as_str()（crates/octos-core/src/types.rs:453-463）返回 &'static str，四个变体分别映射为 "system"、"user"、"assistant"、"tool"，一个穷尽的 match，没有通配分支，新增变体时编译器会强制补齐这里的映射。

Display trait 实现（crates/octos-core/src/types.rs:465-469）的函数体只有一行 f.write_str(self.as_str())。为什么要同时实现这两个？因为它们服务于不同场景：

• as_str() 接受 self（按值传递），返回 &'static str。这是可行的因为 MessageRole 实现了 Copy trait：枚举只有四个无数据变体，拷贝成本等同于拷贝一个字节。按值传递用于需要零分配的场景，比如构建 API 请求时设置 JSON 字段值。
• Display 用于格式化字符串（format!()、println!() 等），是 Rust 生态的标准接口。

这种模式确保了跨 Provider 的一致性：无论是发送给 Anthropic 还是 OpenAI，消息角色始终序列化为 "system"、"user"、"assistant"、"tool" 这四个小写字符串。各 Provider 的差异（比如 Anthropic 的 system message 是独立字段而非消息数组的一部分）在 octos-llm 中处理，不会泄漏到核心类型层。

2.2.4 ToolCall 与元数据扩展

ToolCall（crates/octos-core/src/types.rs:471-479）是 LLM 请求调用工具时的数据结构：

#![allow(unused)]
fn main() {
pub struct ToolCall {
    pub id: String,
    pub name: String,
    pub arguments: serde_json::Value,
    pub metadata: Option<serde_json::Value>,
}
}

metadata 字段（crates/octos-core/src/types.rs:476-478）是为 Provider 特定数据预留的扩展点。例如，Google Gemini 的工具调用会携带 thought_signature 字段，用于验证工具调用是否来自模型的推理过程。通过 Option<Value> 存储这些异构数据，核心类型无需为每个 Provider 添加特定字段。

2.2.5 便捷构造函数

Message 仍保留了三个 legacy 便捷构造函数（crates/octos-core/src/types.rs:355-417），用于测试、反序列化 round-trip 和旧调用点：Message::user(content)、Message::assistant(content)、Message::system(content)，签名均为 (content: impl Into<String>) -> Self。

注意参数类型是 impl Into<String> 而非 String 或 &str。这让调用者可以传入 String、&str、甚至 Cow<str>，编译器会自动选择最高效的转换路径。这是 Rust 中常见的 API 设计模式：通过泛型减少调用者的类型转换负担。三个构造器的函数体都只是把 content 包进对应 role 的 Message，不再赘述。

2.3 Durable ABI：TaskResult 与 SessionSummary 的 schema_version

octos-core 现在还承担一类更隐蔽的职责：给跨 crate 持久化 payload 定义 stable ABI。两个例子最典型。

TaskResult 带有 schema_version（crates/octos-core/src/task.rs:138-157）：

#![allow(unused)]
fn main() {
pub struct TaskResult {
    #[serde(default = "default_task_result_schema_version")]
    pub schema_version: u32,
    pub success: bool,
    pub output: String,
    pub files_modified: Vec<PathBuf>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub files_to_send: Vec<PathBuf>,
    pub subtasks: Vec<TaskId>,
    pub token_usage: TokenUsage,
}
}

这个字段不是展示用版本号，而是 Harness / workspace contract / task result 在磁盘和进程边界上传递时的 durable ABI。旧 payload 没有该字段时，会通过 serde default 回到 TASK_RESULT_SCHEMA_VERSION = 1，保证历史数据可读。

第二个例子是 SessionSummary（crates/octos-core/src/task.rs:233-305）。它是 Ch8 里 typed compaction 的核心载体：

#![allow(unused)]
fn main() {
pub struct SessionSummary {
    #[serde(default = "default_session_summary_schema_version")]
    pub schema_version: u32,
    pub goal: String,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub constraints: Vec<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub progress_done: Vec<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub progress_in_progress: Vec<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub decisions: Vec<DecisionRecord>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub files: Vec<FileRecord>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub next_steps: Vec<String>,
}
}

SessionSummary 的设计重点不是“把聊天记录压成一段摘要”，而是把 goal、constraints、progress、decisions、files、next_steps 分开保存，让后续 compaction 可以迭代更新结构化字段。缺失 schema_version 时默认到当前版本；如果读到未来版本，validate_schema_version() 返回 UnsupportedSessionSummaryVersion typed error，而不是 panic 或静默丢字段（crates/octos-core/src/task.rs:188-305）。

flowchart TD
    History[Conversation history] --> Summary[SessionSummary schema_version=1]
    Summary --> Goal[goal]
    Summary --> Constraints[constraints]
    Summary --> Decisions[decisions + stale markers]
    Summary --> Files[files]
    Summary --> Next[next_steps]
    Summary --> Check{future schema?}
    Check -->|no| Continue[compaction continues]
    Check -->|yes| Error[UnsupportedSessionSummaryVersion]

这也是为什么 SessionSummary 放在 octos-core 而不是 octos-agent：Ch8 的 compaction、Ch9 的 Harness ABI、Ch14 的 UI/runtime 观测都会引用它。core crate 在这里提供的是 wire-stable domain language，而不是具体 compaction 算法。

2.4 Error 设计：为什么选 eyre 而不是 anyhow

Rust 生态中有两个主流的错误处理库：anyhow 和 eyre。它们都提供类型擦除的错误报告（anyhow::Error / eyre::Report），但 octos 选择了 eyre/color-eyre。这个选择值得深入分析。

2.4.1 octos 的错误类型

octos-core 的 Error 定义在 crates/octos-core/src/error.rs:10-17：

#![allow(unused)]
fn main() {
pub struct Error {
    pub kind: ErrorKind,
    pub context: Option<String>,
    pub suggestion: Option<String>,
}
}

这里的关键设计是三层结构：kind 分类错误类型，context 添加执行上下文，suggestion 提供可操作的修复建议。

ErrorKind 是一个 15 变体的枚举（crates/octos-core/src/error.rs:20-56），覆盖了系统中所有错误类别：

#![allow(unused)]
fn main() {
pub enum ErrorKind {
    TaskNotFound(String),
    AgentNotFound(String),
    InvalidStateTransition { from: String, to: String },
    LlmError { provider: String, message: String },
    ApiError { provider: String, status: u16, body: String },
    ToolError { tool: String, message: String },
    ConfigError(String),
    ApiKeyNotSet { provider: String, env_var: String },
    UnknownProvider(String),
    Timeout { operation: String, seconds: u64 },
    ChannelError { channel: String, message: String },
    SessionError(String),
    IoError(std::io::Error),
    SerializationError(String),
    Other(eyre::Report),
}
}

注意最后一个变体 Other(eyre::Report)：这里使用了 eyre::Report 而非 anyhow::Error。

2.4.2 eyre vs anyhow：选型理由

anyhow 和 eyre 的核心 API 几乎相同，但有两个关键差异：

差异一：自定义错误报告器。 eyre 支持通过 eyre::set_hook() 安装自定义的错误报告器。color-eyre 就是这样一个报告器，它在错误发生时自动捕获 std::backtrace::Backtrace 和 tracing_error::SpanTrace，并以彩色格式输出。对于一个 CLI 工具来说，当 Agent 执行失败时，开发者能立即看到彩色高亮的错误链和调用栈，这比 anyhow 的纯文本输出提供了更好的调试体验。

差异二：生态对齐。 octos 的 workspace 依赖声明中同时使用了 eyre 和 color-eyre（Cargo.toml:97-98）。这是因为 color-eyre 在 CLI 入口初始化（main() 中调用 color_eyre::install()），而 eyre::Report 作为通用错误类型在整个代码库中使用。如果混用 anyhow::Error 和 eyre::Report，需要在边界处做转换，增加不必要的复杂度。

2.4.3 可操作的错误消息

octos 的错误设计最值得学习的不是库的选择，而是"让错误消息可操作"的理念。看几个便捷构造函数的实现（crates/octos-core/src/error.rs:80-173）：

#![allow(unused)]
fn main() {
pub fn api_key_not_set(provider: impl Into<String>, env_var: impl Into<String>) -> Self {
    let provider = provider.into();
    let env_var = env_var.into();
    Self::new(ErrorKind::ApiKeyNotSet {
        provider: provider.clone(),
        env_var: env_var.clone(),
    })
    .with_suggestion(format!(
        "Set the API key:\n    export {env_var}=your-api-key\n  Or add to .octos/config.json:\n    {{\"api_key_env\": \"{env_var}\"}}"
    ))
}
}

当用户忘记设置 API Key 时，错误消息不只告诉你"key 没设"，还告诉你"设置 ANTHROPIC_API_KEY 环境变量，或在 config.json 中配置"。同样，api_error() 会根据 HTTP 状态码给出不同的建议：401 提示检查 key，429 提示被限流，504 提示超时。

Display 实现（crates/octos-core/src/error.rs:174-224）将这三层信息格式化为用户友好的输出，并使用 truncated_utf8() 安全截断过长的 API 响应体，避免错误日志中出现巨大的 JSON dump。

2.5 truncate_utf8：一个小函数背后的 UTF-8 安全哲学

truncate_utf8 是 octos-core 中最小但最精巧的函数之一。它只有 10 行代码（crates/octos-core/src/utils.rs:6-16），却解决了一个在多语言 AI 应用中极其常见的问题：如何安全地截断可能包含中文、日文、emoji 等多字节字符的字符串。

2.5.1 问题：UTF-8 的多字节陷阱

UTF-8 是一种变长编码：ASCII 字符占 1 字节，中文字符占 3 字节，emoji 占 4 字节。当你需要将字符串截断到 N 个字节时，截断点可能正好落在一个多字节字符的中间。以"你好世界"为例：每个汉字 3 字节，四个字共 12 字节；若截断到 7 字节，保留的是 [E4 BD A0] [E5 A5 BD] 加上孤立的 [E4]，最后这个字节是"世"的第一个字节，不再构成合法的 UTF-8 序列。

在 C/C++ 中，这种截断会产生无效的 UTF-8 字符串，可能导致下游解析崩溃。Python 的 str[:7] 按字符而非字节截断，避免了这个问题但无法精确控制字节预算。

2.5.2 两个变体：in-place 与 copying

octos 提供了两个截断函数：

truncate_utf8（crates/octos-core/src/utils.rs:6-16）原地截断，修改原字符串：

#![allow(unused)]
fn main() {
pub fn truncate_utf8(s: &mut String, max_len: usize, suffix: &str) {
    if s.len() <= max_len {
        return;
    }
    let mut limit = max_len;
    while limit > 0 && !s.is_char_boundary(limit) {
        limit -= 1;
    }
    s.truncate(limit);
    s.push_str(suffix);
}
}

truncated_utf8（crates/octos-core/src/utils.rs:21-30）返回新字符串，不修改原始数据：

#![allow(unused)]
fn main() {
pub fn truncated_utf8(s: &str, max_len: usize, suffix: &str) -> String {
    if s.len() <= max_len {
        return s.to_string();
    }
    let mut limit = max_len;
    while limit > 0 && !s.is_char_boundary(limit) {
        limit -= 1;
    }
    format!("{}{}", &s[..limit], suffix)
}
}

核心算法相同：从 max_len 位置向前回退，直到找到一个合法的 UTF-8 字符边界（is_char_boundary()）。截断后追加 suffix。注意这两个函数的 max_len 不包含 suffix 的长度，追加 suffix 后最终字符串可能超过 max_len。这是有意的设计：max_len 控制的是保留内容的上限，suffix 是额外的标记。调用者需要在设置 max_len 时预留 suffix 的空间。

两个变体的区别在于所有权语义：

• truncate_utf8 接受 &mut String，原地修改，零额外分配（除了 suffix 追加）
• truncated_utf8 接受 &str（不可变引用），返回新 String，需要一次堆分配

调用者根据场景选择：如果拥有字符串所有权且不再需要原始内容，用 in-place 版本；如果字符串是借用的（比如来自 API 响应的 &str），用 copying 版本。

2.5.3 truncate_head_tail 与 TruncationReport：结构化的首尾截断

对于工具输出和错误消息，仅保留开头往往不够：尾部的错误信息或结论同样重要。2026-08-31 的提交 d8125d18 之后，octos 用一对函数解决这个问题：truncate_head_tail（crates/octos-core/src/utils.rs:91-96）与它背后的 truncate_head_tail_report（crates/octos-core/src/utils.rs:105）。

truncate_head_tail_report 是真正的实现，返回结构化的 TruncationReport：

#![allow(unused)]
fn main() {
pub fn truncate_head_tail_report(s: &str, max_len: usize, head_ratio: f32) -> TruncationReport
}

报告除了截断后的 content，还携带这次截断的全部事实：truncated 标记是否发生了截断；truncated_by 记录触发的是哪条上限（当前只有 TruncatedBy::Bytes 可达，Lines 变体为未来的行数截断预留）；total_bytes / output_bytes / omitted_bytes 分别是输入长度、输出长度和丢弃的字节数；max_len 与 head_ratio 回记实际生效的参数（head_ratio 已钳位到 [0.1, 0.9]）。截断输出中间以 \n\n... [N bytes omitted] ...\n\n 标记连接首尾，omitted_bytes 就是与标记中 N 一致的准确数字，两端的切点都经 is_char_boundary() 保证 UTF-8 安全。

为什么要把报告带回来？源码注释写明了动机：调用方若用 total - content.len() 反推丢弃量，会漏算省略标记自身的长度。上层需要向模型如实告知"你看到的是裁剪过的输出、裁掉了多少"时（第 8 章的上下文管理正是这样用），应从报告里读，而不是自己做减法。

truncate_head_tail 则是保持旧接口的薄包装，整个函数体只有一行：

#![allow(unused)]
fn main() {
pub fn truncate_head_tail(s: &str, max_len: usize, head_ratio: f32) -> String {
    truncate_head_tail_report(s, max_len, head_ratio).content
}
}

一份实现，两个出口：只要 String 的旧调用点继续用旧名字，需要完整报告的调用方换新函数，同样的输入产出字节一致的 content。

这个函数家族在 octos 的多个场景中使用：

• 工具输出截断（Shell 命令的 stdout/stderr）
• 错误消息中的 API 响应体截断（crates/octos-core/src/error.rs）
• 上下文压缩时的消息摘要（详见第 8 章）

2.5.4 tool_output_limit：按工具类型定制的截断策略

tool_output_limit（crates/octos-core/src/utils.rs:180-199）为不同工具设置了不同的字节上限：

search 是内建 deep-search 技能的运行时工具名，deep_search 是为未来变体保留的契约槽位，源码注释写明了这层防御性别名关系。这些限制不是任意的：普通搜索结果的信息密度高（每条结果都是有用的摘要），20,000 字节足够；源码文件的信息分布不均（可能需要看到完整的函数体），给 50,000 字节；深度搜索的输出是聚合了多个来源的原文，截短会砍断证据链，因此给到 200,000 字节。这些限制与 LLM 的上下文窗口预算配合使用（详见第 8 章上下文管理）。

2.6 SessionKey：多租户会话标识的设计

SessionKey（crates/octos-core/src/types.rs:489-567）是多租户系统中会话路由的关键。它的设计演进反映了从单频道到多频道、从单 Profile 到多 Profile，再到 topic 分支会话的需求扩展。

2.6.1 格式演变

SessionKey 支持四种格式，向后兼容：

base_key() 方法（crates/octos-core/src/types.rs:525-528）返回去掉 #topic 后缀的部分，用于会话持久化（同一个 base_key 的不同 topic 共享持久化文件）。topic() 方法（crates/octos-core/src/types.rs:530-533）提取主题后缀。

2.6.2 Channel 推断，而不是构造期验证

当前源码没有在 SessionKey::new() 构造时拒绝未知 channel；构造函数只是格式化字符串。公开的 is_reserved_channel_name()（crates/octos-core/src/types.rs:603-630，内部委托私有 is_channel_name()）的职责是帮助 split_base_key() 判断三段式 key 里的第一段究竟是 profile_id 还是 channel。白名单包含 19 个已知 channel：

api, cli, dingtalk, discord, email, feishu, line, local, matrix, qq-bot,
slack, system, telegram, test, twilio, wechat, wecom, wecom-bot, whatsapp

这个细节很重要：SessionKey 解决的是 session routing key 的结构化解析，不是 channel 配置合法性的全局验证。真正的 channel / profile 配置校验发生在更上层的 CLI/API 配置路径中；core 这里只提供低依赖、可序列化的 key 形态。

2.7 AgentMessage：Agent 间协调协议

AgentMessage（crates/octos-core/src/message.rs:10-29）定义了 Agent 之间的协调协议：

#![allow(unused)]
fn main() {
pub enum AgentMessage {
    TaskAssign { task: Box<Task> },
    TaskUpdate { task_id: TaskId, status: TaskStatus },
    TaskComplete { task_id: TaskId, result: TaskResult },
    ContextRequest { task_id: TaskId, query: String },
    ContextResponse { task_id: TaskId, context: Vec<Message> },
}
}

五种消息类型涵盖了 Agent 协调的核心场景：分配任务、更新状态、完成通知、请求上下文、返回上下文。注意 TaskAssign 中的 Box<Task>：Task 结构体较大，使用 Box 堆分配避免了枚举变体之间的大小不均导致的内存浪费。

task_id() 方法（crates/octos-core/src/message.rs:31-42）返回 Option<&TaskId>，为所有变体提供统一的任务 ID 访问接口。调用者无需对每个变体做模式匹配就能获取关联的任务 ID，只需处理 Option 即可。

2.8 abort：多语言中断检测

一个有趣的小模块：crates/octos-core/src/abort.rs 实现了多语言的 Agent 中断检测。当用户在 Agent 执行过程中发送"停"、"stop"、"やめて"、"стоп"等中断信号时，系统需要立即识别并终止当前操作。

ABORT_TRIGGERS 数组（crates/octos-core/src/abort.rs:32-71）包含 9 种语言、28 个触发词（源文件顶部注释写 30+，以数组实际条目数为准）。is_abort_trigger()（crates/octos-core/src/abort.rs:6-13）对输入进行 trim + lowercase 后精确匹配。abort_response()（crates/octos-core/src/abort.rs:15-30）返回与触发语言匹配的本地化取消确认。

代码注释还记录了故意排除的词："wait"、"exit"、"para" 在正常对话中出现频率太高，会导致误判。这是一个务实的设计选择：宁可漏掉一些中断信号（用户可以再说一次），也不要在正常对话中误触发中断。

2.9 core 的边界：2026 年新增的七个文件

octos-core 在 2026 年下半年又收进了七个模块。表面上看 core 变胖了，归类判据却是一致的：它们都是"被多个上层 crate 共同依赖、自身又不依赖任何上层"的单一事实源。逐个给出一句话定位：

crates/octos-core/src/session_scope.rs 和 crates/octos-core/src/git_worktree.rs 值得多看一眼。前者把"组件如何确定工作目录"从各自为政的 raw 输入推算，收拢成一份显式契约：solo / multi_tenant 两种 ScopeMode、路径分类结果、安全 session id 校验都在类型里。后者的顶部注释明说这是从 octos-agent 的 spawn 工具"借魂"上来的纯增量模块：agent 侧经过重重审查的旧实现保持原样，fleet-worker 走新路径，两者暂不合并。这两个例子给出了 core 边界的实际判据：进 core 的不是"最小的类型集"，而是"任何上层各留一份副本都会漂移的契约"。七个模块各自的实现细节属于后续章节，本章只做定位。

工程决策侧栏：为什么 core crate 零内部依赖

octos-core 是 workspace 中唯一没有依赖其他 octos crate 的基础 crate（octos-plugin 和 octos-sandbox 也无内部依赖，但它们不被其他 crate 依赖）。这个"零内部依赖"约束是刻意的设计选择。

方案一：胖 core（把更多逻辑下沉到 core）

优势：

• 所有公共逻辑集中在一处，减少 crate 间的重复
• 下游 crate 只需依赖 core 就能获得大部分能力

劣势：

• core 的编译时间随功能膨胀而增加，影响所有依赖它的 crate 的增量编译速度
• core 的变更频率增加，每次修改都触发全 workspace 重编译
• 不相关的功能被耦合，修改 LLM 相关逻辑可能影响 Task 类型

方案二：瘦 core（只放类型定义和最基础的工具函数）

优势：

• 极少变更，提供稳定的类型基础
• 编译边界清晰（octos-core 当前 22,313 行 Rust 源文件，剔除 crates/octos-cli/src/api/ui_protocol_tests.rs 后约 15,005 行，其中大头是 UI Protocol wire 类型与配套测试）
• 依赖图清晰：所有 crate 依赖 core 的类型，但 core 不依赖任何人

劣势：

• 跨 crate 共享的逻辑需要放在其他地方（比如 octos-agent 中的工具函数）
• 可能出现"本应在 core 中"的类型被定义在上层 crate 的情况

octos 的选择：瘦 core，理由如下。

octos-core 的外部依赖仅限于 serde、serde_json、chrono、uuid、eyre、tracing、sha2 这几个基础库，分别覆盖序列化、时间、错误处理、结构化日志与哈希，均为行业标准。这意味着 octos-core 的编译时间极短，而所有依赖它的 crate（octos-llm、octos-memory、octos-agent、octos-bus、octos-pipeline、octos-cli）都能从这个快速编译中获益。

更重要的是稳定性保证。在 octos 的开发历程中，octos-llm 经历了多次 Provider 重构，octos-agent 的工具系统不断扩展，octos-bus 新增了多个频道——但 octos-core 的核心类型（Task、Message、Error）保持了高度稳定。瘦 core 策略使得这种稳定性成为可能。

2.10 本章回顾

octos-core 用 22,313 行 Rust 源文件（剔除 crates/octos-cli/src/api/ui_protocol_tests.rs 后约 15,005 行）定义了整个系统的领域语言：

1. Task 状态机：用 Rust 枚举编码合法状态和转换，在类型层面消除非法状态组合。UUID v7 提供时间排序，五维 TokenUsage 支持精细的成本追踪。

2. Message 抽象：四角色统一模型（System/User/Assistant/Tool）+ as_str()/Display 双重实现，确保跨 Provider 的序列化一致性。ClientMessageId、ThreadId、TurnId 则把 UI 乐观消息、渲染分组和协议 turn identity 分开，避免并发 turn 下的错误归属。

3. Durable ABI：TaskResult.schema_version 和 SessionSummary.schema_version 让 task result 与 typed compaction summary 成为可升级的 wire-stable payload；未来版本通过 typed error fail closed。

4. Error 设计：选择 eyre/color-eyre 获取彩色错误报告和 SpanTrace 支持。三层结构（kind + context + suggestion）让错误消息可操作。

5. UTF-8 安全工具：truncate_utf8 的两个变体（in-place 和 copying）通过 is_char_boundary() 保证截断安全。truncate_head_tail_report 返回结构化 TruncationReport，truncate_head_tail 是其字节一致的薄包装。

6. 零依赖设计：瘦 core 策略确保类型基础稳定、编译快速，支撑上层 crate 的独立演进。

7. core 的边界：2026 年新增的七个模块（abort、app_ui、app_ui_codec、env_hygiene、gateway、git_worktree、session_scope）按"跨上层的单一事实源"判据归入 core。

下一章，我们将进入 octos-llm，看看这些核心类型如何被用来驯服多个 LLM Provider 的混乱接口。

延伸阅读

• Rust 枚举与模式匹配：The Rust Programming Language 第 6 章 "Enums and Pattern Matching"，https://doc.rust-lang.org/book/ch06-00-enums.html
• eyre 错误处理：eyre crate 文档，https://docs.rs/eyre/latest/eyre/
• color-eyre：color-eyre crate 文档，https://docs.rs/color-eyre/latest/color_eyre/
• UUID v7 规范：RFC 9562 "Universally Unique IDentifiers (UUIDs)"，Section 5.7
• UTF-8 编码：The Unicode Standard Chapter 3 "Conformance"：理解 UTF-8 变长编码对安全截断至关重要

思考题

1. 状态机扩展：如果要为 Task 添加一个 Cancelled 状态（用户主动取消），它应该从哪些状态可达？添加这个状态会对现有的 match 表达式产生什么影响？

2. 胖 core vs 瘦 core：假设 octos-core 把 LlmProvider trait 也放进来（因为所有上层 crate 都需要它），会带来什么问题？提示：考虑 async-trait、reqwest 等依赖的传递效应。

3. 错误设计权衡：octos 的 ErrorKind 有 15 个变体。如果系统继续增长到 50 个变体，这种设计会遇到什么问题？你会如何重构？

4. 截断策略的替代方案：truncate_utf8 按字节截断并回退到字符边界。另一种方案是按 Unicode 字素簇（grapheme cluster）截断。两种方案在处理 emoji 组合序列（如 👨‍👩‍👧‍👦）时有什么区别？哪种更适合 LLM 上下文管理场景？

版本演化说明

本章分析基于 octos main @ 9c157101（2026-09-02 勘误核对）：crates/octos-core/src/*.rs 全量 22,313 行（15 个源文件，其中 crates/octos-cli/src/api/ui_protocol_tests.rs 7,308 行），外部依赖为 serde / serde_json / chrono / uuid / eyre / tracing / sha2，全部引用行号经 assets/ch02-refcheck.md 逐条复核。

本次勘误要点：TurnId 区间更新为 crates/octos-core/src/ui_protocol.rs:607-623；api_key_not_set 摘录按 crates/octos-core/src/error.rs:89-99 源码改写为多行 export / config.json 提示；Error 的 Display 区间修正为 crates/octos-core/src/error.rs:174-224；2.5.3 按 d8125d18（2026-08-31）改写为 truncate_head_tail_report / TruncationReport 结构化截断；tool_output_limit 限额表更新（search、deep_search、news_fetch 均为 200,000）；channel 白名单 15 改 19（补 dingtalk、line、local、wechat）；eyre / color-eyre 依赖声明位于根 Cargo.toml:97-98；ABORT_TRIGGERS 实为 28 个触发词；依赖侧栏补 tracing、sha2；新增「core 的边界」小节归类 2026 年新增的七个源文件。

阅读后续版本时，除了 Task / Message / Error，还应核对 identity newtypes、SessionSummary ABI、UI Protocol capabilities 这些跨 crate wire 类型。

第 3 章：octos-llm：驯服 LLM Provider 的混乱

定位：本章深入 octos-llm crate，展示如何用 Rust trait 抽象统一多种 LLM Provider 的混乱接口，以及如何用三级容错能力与两级装配实现生产级可靠性。前置依赖：第 2 章。适用场景：想理解多 Provider 架构设计的 AI 应用开发者（读者 C），以及对 trait object、异步容错、凭据轮换和模型分层路由感兴趣的 Rust 开发者（读者 B）。

每个 LLM Provider 都有自己的 API 风格：Anthropic 把 system message 作为独立字段，OpenAI 把它放在消息数组里；Gemini 的工具调用格式与其他两家完全不同；Ollama 虽然是本地部署，但在 octos 里复用了 OpenAI 兼容接入层。当你需要同时支持少数专用协议实现，再加上一批复用 OpenAI / Anthropic 兼容层的 Provider 时，混乱是不可避免的——除非你在正确的层次建立正确的抽象。

octos-llm 的解决方案自底向上分三块：底层的 LlmProvider trait 统一调用接口，中层的 Provider 注册表实现模型名自动检测和工厂创建，顶层的容错装配提供生产级可靠性：每个 Provider 恒包一层 RetryProvider，外层再按配置二选一套上 ProviderChain（静态有序故障转移，缺省）或 AdaptiveRouter（评分路由，需显式 opt-in，替换而非叠加）。当前主分支还把 provider metadata、HTTP timeout knobs、credential pool、content classifier 和 routing.decision 事件纳入这条链路。本章将自底向上逐层展开。

3.1 LlmProvider trait：最小化的统一接口

3.1.1 trait 签名

LlmProvider 的定义位于 crates/octos-llm/src/provider.rs:16-121：

#![allow(unused)]
fn main() {
#[async_trait]
pub trait LlmProvider: Send + Sync {
    // 核心方法：非流式对话
    async fn chat(
        &self,
        messages: &[Message],
        tools: &[ToolSpec],
        config: &ChatConfig,
    ) -> Result<ChatResponse>;

    // 流式对话（默认实现：调 chat() 后合成事件流）
    async fn chat_stream(
        &self,
        messages: &[Message],
        tools: &[ToolSpec],
        config: &ChatConfig,
    ) -> Result<ChatStream> { /* Text→ToolCall→Usage→Done 依次产出 */ }

    // 元数据查询
    fn context_window(&self) -> u32 { context::context_window_tokens(self.model_id()) }

    // 异步初始化钩子：见下文
    async fn ensure_ready(&self) {}

    fn max_output_tokens(&self) -> u32 { context::max_output_tokens(self.model_id()) }

    // #2143 part 3：估算本 provider 实际发出的请求 token 数（含序列化开销）
    fn estimate_request_tokens(
        &self,
        messages: &[Message],
        tools: &[crate::types::ToolSpec],
    ) -> u32 { /* 默认走基线估算，具体 provider 可收紧 */ }

    fn model_id(&self) -> &str;
    fn provider_name(&self) -> &str;
    fn provider_metadata(&self) -> ProviderMetadata;
    fn provider_metadata_for_index(&self, _provider_index: Option<usize>) -> ProviderMetadata;

    // 可选：指标上报
    fn export_metrics(&self) -> Option<serde_json::Value> { None }
    fn report_late_failure(&self) {}
    fn report_stream_metrics(&self, _output_tokens: u32, _stream_duration_us: u64) {}
}
}

这个 trait 的设计遵循了"最小必要接口"原则（crates/octos-llm/src/provider.rs:13 的注释明确说明了这一点）：只定义所有 Provider 共同的能力，差异在各实现中处理。

几个值得关注的设计选择：

Send + Sync 约束。 trait 要求实现者是线程安全的，因为 Provider 实例会被多个异步任务通过 Arc 共享。这个约束在编译期保证了不会出现单线程 Provider 实现被意外用在多线程场景的错误。

chat_stream() 的默认实现。 不是所有 Provider 都原生支持流式响应。默认实现（crates/octos-llm/src/provider.rs:27-56）调用非流式的 chat() 方法，然后将完整响应包装为一个合成流：按内容、工具调用、usage、done 事件依次输出。这让新 Provider 只需实现 chat() 就能基本工作，流式支持可以后续优化。

Provider metadata。 provider_metadata() 与 provider_metadata_for_index() 是当前主分支新增的重要接口（crates/octos-llm/src/provider.rs:97-109）。它们把实际命中的 provider slot、模型 ID、provider name 等信息交给上层，用于观测、成本归因和多 provider chain 的精确指标记录。provider_metadata_for_index() 解决的是组合 Provider 的问题：当一个 ProviderChain 内部选中了第 N 个 slot，上层不能只看到 chain 本身的名字，而必须知道真正被调用的是哪一个后端。签名现在是 _provider_index: Option<usize>（103 行）：调用方知道具体 slot 时传 Some(idx)，只知道 provider 本体时传 None，简单调用方不必伪造下标。

指标上报方法。 export_metrics()、report_late_failure()、report_stream_metrics() 三个方法都有空的默认实现。它们为 AdaptiveRouter 的 EMA 评分系统提供数据源（见 3.4 节），但不强制所有 Provider 实现。这种"可选钩子"模式避免了 trait 膨胀。

ensure_ready() 与 estimate_request_tokens()。 这是基线上两个较新的成员。ensure_ready()（crates/octos-llm/src/provider.rs:65）是异步初始化钩子：agent loop 与 prompt-context 桥在每 turn 第一次依赖窗口数的决策前 await 它，本地上下文探测（见 3.7 节）借此保证真实窗口在首次 compaction 决策前 resolve，而不是在第一次 chat 之后；包装器逐层委托。estimate_request_tokens()（crates/octos-llm/src/provider.rs:82-89，#2143 part 3）估算该 provider 实际构建的请求 token 数，含 provider 特有序列化开销（独立 system 块、逐消息 content-block 框架、cache-control 元数据），路由适配守卫据此不再需要用 12.5% 的安全余量顶替这部分开销；默认是 provider 无关的基线估算，具体 provider 覆写收紧，包装器同样委托内层。

3.1.2 核心数据类型

ChatConfig（crates/octos-llm/src/config.rs:8-70）封装单次请求的全部可调参数：

• max_tokens: 最大输出 token 数
• temperature: 采样温度（Anthropic 协议路径上 Some(0.0) 视为未设置，不上 wire）
• tool_choice: 工具选择策略（auto/required/none/指定工具）
• stop_sequences: 停止序列
• reasoning_effort: 思考模型的推理力度（none/low/medium/high/max，映射到 OpenAI reasoning.effort、Anthropic thinking budget、Gemini thinkingConfig）
• response_format: 响应格式约束（文本/JSON/结构化输出）
• context_management: Anthropic 专有的不透明 payload（如 clear_tool_uses_20250919），让服务端做 tier-2 工具调用清理，其他 provider 忽略
• sampling_params: 运营者透传的额外采样参数表（机制见下文）
• cache_retention: 单次请求的 prompt-cache 保留偏好（None 表示这一次不写缓存，机制见 3.6 节）

这份清单刻意没有 model 和 system_prompt 两个看似必然的字段：model 在 provider 构造期由注册表工厂决定（见 3.2.3），system prompt 走 messages 数组（正是本章开头强调的各家协议差异点）。sampling_params 与 cache_retention 的完整机制分别展开于本小节下文与 3.6 节。

ChatResponse 包含 LLM 返回的完整信息：内容、stop reason、工具调用请求、token 使用量。ChatStream 是一个异步流（Pin<Box<dyn Stream<Item = Result<StreamEvent>>>>），逐事件产出流式响应。

sampling_params（crates/octos-llm/src/config.rs:44-57）承载 octos 不建模的采样参数，例如 {"repeat_penalty": 1.1, "top_p": 0.95}。OpenAI 兼容层把它们展平注入请求体（crates/octos-llm/src/openai.rs:635-640，字段文档 908-909，测试 1614-1616），并防御性剔除 octos 已有专用字段的同名键（#2172），避免流式与非流式两条序列化路径出现重复或分叉的字段。默认为空，展平后什么都不加，云端请求不变。这套 cloud-safe sampler passthrough 由提交 b0072e70（#2172/#2176）引入，服务 llama.cpp / vLLM / SGLang 这类接受非标采样参数的本地推理服务。

上下文窗口也不再只有静态目录一个来源。提交 3e479ce3（#2142）引入 per-profile context_window 覆盖，落点跨两个 crate：配置结构 LlmModelSelectionConfig（crates/octos-cli/src/profiles.rs:824-875，字段 875 行）、config.llm 侧字段（crates/octos-cli/src/config.rs:39-46、489-492）与装配函数 apply_context_window_override（crates/octos-cli/src/qos_catalog.rs:24-36）都在 octos-cli；octos-llm 只提供 crates/octos-llm/src/context_override.rs（135 行）的 ContextWindowOverride 薄包装。它被套在包装栈最外层，值同时压过静态目录与运行时探测（#2135）。profile 里 config.llm.primary.context_window / fallbacks[i].context_window 的接线主体在 octos-cli，不是 octos-llm 内部，引用时须如实标注这个跨 crate 落点。

Provider 工厂还接收 LLM HTTP timeout knobs。CreateParams::http_timeout()（crates/octos-llm/src/registry/mod.rs:110-118）把 llm_timeout_secs、llm_connect_timeout_secs 两个可选字段合成 Option<(u64, u64)>：任一字段缺省时用默认常量补齐，两者都缺省时返回 None。默认常量在 crates/octos-llm/src/provider.rs:158-172 定义：LLM 总超时 300 秒、连接超时 10 秒（从 30 秒下调，连不上就尽快 failover），流式读空闲超时 300 秒（DEFAULT_LLM_STREAM_IDLE_TIMEOUT_SECS，165 行，经 reqwest 的 .read_timeout() 生效，每次读到数据即重置，持续产 token 的长流不会被总时长截断），embedding 总超时 60 秒、连接超时 15 秒。这把"模型推理慢"和"网络连接失败"分开处理，避免所有超时都挤在一个不可解释的配置项里。

3.2 Provider 注册表：模型名自动检测

当用户配置 model: "claude-sonnet-4" 时，octos 需要自动确定使用 Anthropic Provider。这个映射由 Provider 注册表实现（crates/octos-llm/src/registry/mod.rs）。

3.2.1 检测机制

每个 Provider 注册时声明自己的名称、别名、API key 环境变量（含别名）、默认 base URL、各项要求、检测模式、模型发现能力和工厂函数（crates/octos-llm/src/registry/mod.rs:121-167，ProviderEntry 结构体）：

#![allow(unused)]
fn main() {
struct ProviderEntry {
    name: &'static str,
    aliases: &'static [&'static str],
    api_key_env: Option<&'static str>,
    key_env_aliases: &'static [&'static str],
    default_base_url: Option<&'static str>,
    requires_api_key: bool,
    requires_base_url: bool,
    requires_model: bool,
    detect_patterns: &'static [&'static str],
    model_discovery: ModelDiscovery,
    create: CreateFn,
}
}

detect_provider() 方法（crates/octos-llm/src/registry/mod.rs:244-260）按优先级顺序遍历所有 Provider，检查模型名是否包含检测模式。两处结构值得注意：default_model 不再是每个条目上的静态字符串，而是从 model_catalog.json 中标 "default": true 的行构建 family -> default model 映射（crates/octos-llm/src/registry/mod.rs:24-65）；model_discovery 字段声明该 family 的模型列举能力（协议或"手动输入"），由 crates/octos-llm/src/discovery.rs:134 的 resolve_model_discovery(family, api_type) 在运行时解析：api_type: "anthropic" 直接命中 Anthropic Messages 策略，已知 family 查注册表声明，未知或 custom family 回落 OpenAI 兼容策略，协议从不由单个 family 字面量推断。

特殊处理：O 系列模型。 OpenAI 的 o1、o3、o4 系列需要前缀匹配而非子串匹配（crates/octos-llm/src/registry/mod.rs:248-250），因为 "o1" 作为子串可能匹配到其他 Provider 的模型名中（如 ro1and 假设模型名）。

另一个容易误读的点是：有些 Provider 的 detect_patterns 为空，这不是遗漏，而是明确要求用户通过显式 provider 名或 alias 命中。典型例子包括 Vertex、R9s、OpenRouter、Z.AI、两个 coding-plan family、NVIDIA、Ollama、vLLM 和 local。它们的模型名往往是跨平台转发名、OpenAI 兼容名或用户本地自定义名，盲目做子串检测会产生错误路由。coding-plan family（moonshot-coding、zai-coding）注册在基础 family 之前，显式点名时 coding 端点先于普通端点解析，避免 coding-plan 密钥被静默送到会拒绝它的普通端点。

3.2.2 完整 Provider 注册表

octos 当前注册 19 个 provider family（口径：crates/octos-llm/src/registry/mod.rs 中 static ALL 的条目数，186-210 行；registry/ 目录 20 个文件 = 19 个 family 模块 + crates/octos-llm/src/registry/mod.rs 本身），按数组顺序即检测优先级：

相比旧稿的 15 个，新增 4 个 family：vertex（Vertex AI 上的 Gemini，凭据走 service-account JSON 环境变量 VERTEX_SA_JSON，无 base URL 默认值，模型列举标记 Unsupported）、moonshot-coding / zai-coding（两个 coding-plan 端点，显式点名命中，见上文）、local（llama.cpp / LM Studio 等本地服务器，别名最多，keyless 默认，缺模型时用占位符 local-default 而不是报错，真实窗口靠运行时探测，见 3.7 节）。

Anthropic、OpenAI、Gemini 使用专用实现；其余多数条目通过兼容层接入，其中 Ollama、vLLM、OpenRouter、DeepSeek、local 等复用 OpenAIProvider，Z.AI 复用 Anthropic Messages API，R9s 则按模型族在两种协议间自动切换。旧稿历史版本曾有 enum Provider 枚举，现已不存在。注册方式是"加一个文件 + 在 ALL 里加一行"（crates/octos-llm/src/registry/mod.rs:2-4 的模块注释），每个子模块导出 pub const ENTRY: ProviderEntry 和 create() 工厂。这种"少数专用实现 + 多数兼容适配"架构让新 Provider 的接入成本极低。

3.2.3 Provider 工厂

检测到 Provider 后，注册表通过工厂函数创建具体实例。每个工厂函数读取对应的环境变量（ANTHROPIC_API_KEY、OPENAI_API_KEY 等）或配置文件中的凭据，构造带有正确 base URL 和认证头的 HTTP 客户端。

工厂返回的类型是 Arc<dyn LlmProvider>——这是动态分发的关键点。注册表不知道（也不需要知道）具体的 Provider 类型，只知道它实现了 LlmProvider trait。这让上层代码可以用统一的方式处理所有 Provider，包括将它们放入容错链中。

3.3 容错链：三级能力与两级装配

生产环境中，LLM API 调用可能因为多种原因失败：速率限制（429）、服务器过载（503/529）、认证失效（401）、网络超时。octos-llm 把容错拆成三级能力、两级装配：RetryProvider 处理单个 Provider 的瞬时故障，是每个 slot 恒备的基座；其外的装配层二选一：ProviderChain 做静态有序故障转移（缺省装配），或 AdaptiveRouter 做评分路由（adaptive_routing.enabled 显式 opt-in，替换而非叠加 chain）。生产装配点在 crates/octos-cli/src/qos_catalog.rs:305-352。

flowchart TD
    Request["用户请求"] --> Sel{"adaptive_routing.enabled？<br/>（缺省 false）"}
    Sel -->|"false / 未配置"| PC["ProviderChain<br/>静态有序故障转移"]
    Sel -->|"true（显式 opt-in）"| AR["AdaptiveRouter<br/>EMA 评分路由 / 对冲竞赛"]
    PC --> RP1["RetryProvider<br/>（Provider A）"]
    PC -->|"failover"| RP2["RetryProvider<br/>（Provider B）"]
    AR -->|"评分选中"| RP1
    AR -.->|"hedge racing / 探针"| RP2
    RP1 --> LLM_A["Anthropic API"]
    RP2 --> LLM_B["OpenAI API"]

    style Sel fill:#f9f,stroke:#333
    style PC fill:#bbf,stroke:#333
    style AR fill:#bbf,stroke:#333
    style RP1 fill:#bfb,stroke:#333
    style RP2 fill:#bfb,stroke:#333

图 3-1：容错链的装配结构。 providers 向量的每个元素已是 RetryProvider 包装的 slot；外层按 adaptive_routing.enabled 二选一：缺省回退到静态 ProviderChain，显式 opt-in 才换成 AdaptiveRouter（替换而非叠加）。断路器也是两套独立的：ProviderChain 用 ProviderSlot.failures（crates/octos-llm/src/failover.rs），AdaptiveRouter 用自己的 per-slot circuit breaker（crates/octos-llm/src/adaptive.rs:1036 一带）。

装配点的源码事实：crates/octos-cli/src/qos_catalog.rs:305-352 是唯一的分叉处，crates/octos-cli/src/commands/gateway/profile_factory.rs:363,413、crates/octos-cli/src/commands/chat.rs:1210、crates/octos-cli/src/tools/switch_model.rs:289 全部是 ProviderChain::new(vec![RetryProvider...])，不存在 AdaptiveRouter 内嵌多个 ProviderChain 的路径。

3.3.1 基座：RetryProvider — 每个 Provider 恒包的指数退避

RetryProvider（crates/octos-llm/src/retry.rs:41-312）处理单个 Provider 的瞬时故障。

退避算法（crates/octos-llm/src/retry.rs:259-265）：

#![allow(unused)]
fn main() {
fn calculate_delay(&self, attempt: u32) -> Duration {
    let delay = self.config.initial_delay.as_secs_f64()
        * self.config.backoff_multiplier.powi(attempt as i32);
    let delay = Duration::from_secs_f64(delay);
    std::cmp::min(delay, self.config.max_delay)
}
}

默认配置（crates/octos-llm/src/retry.rs:28-37）：最多重试 3 次，初始延迟 1 秒，退避乘数 2.0，最大延迟 60 秒。重试循环是 for attempt in 0..=max_retries（crates/octos-llm/src/retry.rs:322，流式版同构），且仅当还有重试额度（attempt < max_retries）且错误可重试时才计算延迟并 sleep。因此默认退避序列实际是 1s → 2s → 4s，共三次等待，第 4 次调用失败后直接向上抛错；2^3 = 8s 那一档在循环里走不到，60 秒钳位对默认指数序列同样永不触达，它只在运营者调大退避参数、或 429 解析出超过 60 秒的 retry-after 时才生效。

哪些错误可重试？（crates/octos-llm/src/retry.rs:107-147）

注意 reqwest 级别的网络超时（连接超时、读超时）的特殊处理：不在本地重试（因为同一个 Provider 大概率还是超时），而是立即向上层触发 failover，让 ProviderChain 切换到另一个 Provider。HTTP 504（Gateway Timeout）则被视为可重试，因为服务器可能在短暂过载后恢复。

速率限制解析（crates/octos-llm/src/retry.rs:267-311）：当收到 429 响应时，RetryProvider 会尝试从错误消息中解析推荐的等待时间（如 "Please try again in 29.159s"），加上 1 秒缓冲后等待。如果无法解析，回退到 30 秒固定等待。

3.3.2 装配选项 A：ProviderChain — 静态有序故障转移（缺省）

ProviderChain（crates/octos-llm/src/failover.rs:36-249）管理一组 Provider 的故障转移顺序。

Circuit Breaker 设计（crates/octos-llm/src/failover.rs:27-30）：

#![allow(unused)]
fn main() {
struct ProviderSlot {
    provider: Arc<dyn LlmProvider>,
    failures: AtomicU32,  // 连续失败计数器
}
}

每个 Provider 维护一个原子计数器记录连续失败次数。当失败次数达到阈值（默认 3），该 Provider 被标记为"降级"（degraded）。成功调用后计数器重置为 0（record_success @ crates/octos-llm/src/failover.rs:111-114，swap(0) 在 114 行）。

故障转移逻辑（crates/octos-llm/src/failover.rs:85-99）：

1. 首先尝试第一个未降级的 Provider
2. 如果所有 Provider 都降级了，选择失败次数最少的那个
3. 跳过已降级的 Provider，除非它是最后的选择

延迟故障上报（crates/octos-llm/src/failover.rs:378）：report_late_failure() 处理一种微妙的场景：Provider 返回了 200 响应，但流式解析后发现内容为空或格式错误。这时需要回溯性地惩罚该 Provider，增加其失败计数，让后续请求优先选择其他 Provider。

3.3.3 装配选项 B：AdaptiveRouter — EMA 评分与对冲竞赛（显式 opt-in）

AdaptiveRouter（crates/octos-llm/src/adaptive.rs:803 起的 struct，inherent impl 延伸至文件尾 2795 行）是与 ProviderChain 同位的另一个装配选项：opt-in 时它接收的 providers 向量与 chain 本会是同一个（每个元素已包 RetryProvider），在其上做评分路由，而不是在 chain 外再叠一层。

三种模式（crates/octos-llm/src/adaptive.rs:619-631）：

• Off (0)：静态优先级排序 + circuit breaker，最简单可靠
• Hedge (1)：基于评分选择 + 对冲竞赛（hedge racing）
• Lane (2)：基于评分的车道切换，比 hedge 更节省成本

EMA 评分系统

AdaptiveRouter 为每个 Provider 维护一个实时评分。默认配置下，评分由四个因子的加权组合决定（score() @ crates/octos-llm/src/adaptive.rs:1766 起，权重配置字段 @ 42-64）；其中配置字段仍保留 weight_latency 这个名字，但第二项实际是"质量 + 吞吐"的复合因子，源码并不直接使用原始 latency：

混合权重设计（crates/octos-llm/src/adaptive.rs:1582 与 1772，score 内的 EMA 混合）：稳定性因子使用"目录基线 + 实时数据"的混合计算。混合权重按调用次数递增：min(total_calls / 20.0, 0.5)，这意味着目录基线始终至少占 50% 的影响力。这个设计防止了"冷启动"问题：新 Provider 只有少量调用时，不会因为一两次偶然失败就被判为不可靠。

这里要特别注意：score() 明确用 throughput 而不是原始 latency 做运行时速度信号，因为单次请求延迟更容易受任务复杂度影响，不适合作为跨 Provider 的直接质量指标。

对冲竞赛（Hedge Racing）

在 Hedge 模式下，AdaptiveRouter 会同时向两个 Provider 发起请求，取先返回的结果（hedged_chat() @ crates/octos-llm/src/adaptive.rs:2150 起，tokio::select! 竞赛在 ~2220）：

#![allow(unused)]
fn main() {
// 简化后的逻辑
tokio::select! {
    result = primary_future => {
        // 主 Provider 先返回
        // 备选 Provider 的 future 被 drop（取消）
        result
    }
    result = alternate_future => {
        // 备选 Provider 先返回
        // 主 Provider 的 future 被 drop（取消）
        result
    }
}
}

备选 Provider 的选择优先选最便宜的（减少冗余成本），且必须与主 Provider 不同名（避免向同一 API 发重复请求）。当前实现只记录完成请求的运行时指标；输掉竞赛而被 drop 的 future 不会可靠地产生完整指标，因此 hedge 能改善尾延迟，但会降低观测数据的完整性。

对冲竞赛的代价是双倍的 API 调用成本（输掉竞赛的请求仍然消耗 token，即使被取消，Provider 通常已经开始处理）。因此 Hedge 模式适用于延迟敏感、成本不敏感的场景。Lane 模式则通过评分排序实现类似的路由优化，但不发送冗余请求。

探针策略（Probe）

为了保持备用 Provider 的评分数据新鲜，AdaptiveRouter 以一定概率（默认 10%）向非最优 Provider 发送"探针"请求（should_probe() @ crates/octos-llm/src/adaptive.rs:2097，陈旧判定 is_stale @ 337，默认值 0.1/60s 在配置结构 42-44 与 62-63 行），刷新其性能指标。探针间隔默认 60 秒，避免频繁探测带来的成本。

3.3.4 Credential Pool 与 Content Classifier：从 Provider failover 到 key / tier 路由

当前主分支的容错链不只是在 Provider 之间切换，还会在同一 Provider 的多组凭据之间轮换，并根据内容复杂度选择模型 tier。

Credential pool。 crates/octos-llm/src/credential_pool.rs 的模块注释明确把目标定义为"持久化 cooldown / rotation state"（crates/octos-llm/src/credential_pool.rs:1-29）。每个凭据都有 cooldown、rate-limit 计数、reset 时间、last used、usage count、reservation 等状态；轮换策略包括 FillFirst、RoundRobin、Random、LeastUsed（crates/octos-llm/src/credential_pool.rs:166-189）。当 AdaptiveRouter 发现 401/403 或认证文本时，会把失败分类为 auth failure；发现 429 或 rate limit 文本时，会分类为 rate-limit failure，并通知 credential pool 进入 cooldown 或刷新流程（notify_credential_failure() @ crates/octos-llm/src/adaptive.rs:1081 起，错误侧入口 notify_credential_failure_from_error @ 2352）。轮换结果还会发出稳定的 harness event，schema 为 octos.harness.event.v1，kind 为 credential_rotation（crates/octos-llm/src/credential_pool.rs:213-245）。

Content classifier。 crates/octos-llm/src/content_classifier.rs 是一个无 I/O 的启发式分类器，默认关闭；关闭时返回 Strong，避免因为未启用策略而误把复杂任务路由到便宜模型（crates/octos-llm/src/content_classifier.rs:1-18, crates/octos-llm/src/content_classifier.rs:61-80）。启用后，它根据代码块、消息长度、强模型关键词和 URL 信号产生 Cheap 或 Strong tier：代码块、长度超过阈值、命中 debug/refactor/architecture/prove/proof/analyze/design 等关键词会升到 Strong；URL 只作为 reason 记录，不单独触发 Strong（crates/octos-llm/src/content_classifier.rs:158-209）。AdaptiveRouter 可挂载 classifier，并在选择 lane 之前通过 callback 发出 routing.decision harness event（RoutingDecisionCallback 类型 @ crates/octos-llm/src/adaptive.rs:801，安装入口 set_routing_decision_callback @ 1414）。这让上层 harness 可以解释"为什么这个 turn 走强模型"，而不是只能看到最终 provider。

3.4 SSE 流式解析：字节安全的有状态解析器

LLM 的流式响应以 Server-Sent Events（SSE）协议传输。SSE 看似简单（每个事件以 \n\n 分隔，每行以 data: 前缀标记数据），但在生产环境中，有几个工程挑战需要解决。

3.4.1 为什么需要有状态解析

HTTP 响应的 body 以任意大小的字节块（chunk）到达。一个 SSE 事件可能跨越多个 chunk，一个 chunk 也可能包含多个事件。更微妙的是，chunk 的边界可能正好切开一个 UTF-8 多字节字符。

考虑以下场景：

Chunk 1: data: {"text": "任务完
Chunk 2: 成后请检查结果"}\n\n

"完" 和 "成" 之间不会有问题（它们各自是完整的 UTF-8 字符），但如果 chunk 边界恰好落在"完"字的三个字节中间：

Chunk 1: data: {"text": "任务\xe5\xae
Chunk 2: \x8c成后请检查结果"}\n\n

此时 Chunk 1 末尾的 \xe5\xae 是"完"字的前两个字节，不是合法的 UTF-8。如果逐 chunk 做 String::from_utf8()，就会得到一个解析错误或替换字符（U+FFFD）。

3.4.2 octos 的字节安全解析器

octos-llm 的 SSE 解析器（crates/octos-llm/src/sse.rs:16-72）采用字节级缓冲策略：

1. 原始字节累积：将每个 chunk 的原始字节追加到 Vec<u8> 缓冲区，不做 UTF-8 转换
2. 事件边界检测：在原始字节中搜索 \n\n 或 \r\n\r\n 分隔符
3. 按事件转换：找到完整事件后，才将该事件的字节块转换为 UTF-8 字符串
4. 剩余字节保留：未形成完整事件的尾部字节保留在缓冲区中

这种设计保证了 UTF-8 转换只发生在完整事件上：SSE 协议保证事件边界不会落在 UTF-8 字符中间（因为 \n 是 ASCII 单字节字符）。

解析器使用 stream::unfold() 构建为一个异步流，保持状态（字节流 + 缓冲区）在 yield 事件之间传递。

3.4.3 1MB 缓冲上限

安全考量：如果恶意或异常的 LLM Provider 发送一个永远不包含 \n\n 的超长响应，缓冲区会无限增长。MAX_BUFFER_SIZE（crates/octos-llm/src/sse.rs:6-7）设为 1MB，超过后解析器发出错误事件并清空缓冲区。

#![allow(unused)]
fn main() {
const MAX_BUFFER_SIZE: usize = 1024 * 1024; // 1MB
}

1MB 对于单个 SSE 事件来说绰绰有余。正常的 LLM 流式响应中，每个事件通常只有几十到几百字节（一个 token 的 JSON 表示）。

3.4.4 UTF-8 分割测试：为什么字节级缓冲不可省略

crates/octos-llm/src/sse.rs 的测试（crates/octos-llm/src/sse.rs:261-281）构造了一个精确的多字节分割场景：

"完成后" 的 UTF-8 编码：
完 = [E5 AE 8C]   (3 bytes)
成 = [E6 88 90]   (3 bytes)
后 = [E5 90 8E]   (3 bytes)

故意在"成"字中间切开：
Chunk 1: data: {"text": "完[E6 88          ← "成"的前 2 字节
Chunk 2: 90]后"}\n\n                       ← "成"的第 3 字节 + "后"

如果逐 chunk 做 String::from_utf8()，Chunk 1 末尾的 [E6 88] 不是合法 UTF-8，会被替换为 U+FFFD（替换字符），"成"字永久丢失。

字节级缓冲策略避免了这个问题：两个 chunk 的原始字节被拼接后，在 \n\n 边界整体转换，"完成后" 被正确重组。

这不是一个理论风险：当 LLM 流式输出中文回复时，每个 SSE 事件通常只包含 1-3 个 token。HTTP 的 chunked transfer encoding 可能在任何字节位置切割，与 token 边界无关。对于一个服务中文、日文、韩文用户的 Agent 平台，字节级缓冲是必需的而非优化。

3.5 模型目录与成本追踪

ModelCatalog（crates/octos-llm/src/catalog.rs:48-274）为每个已知模型维护元数据：

#![allow(unused)]
fn main() {
pub struct ModelInfo {
    pub id: String,
    pub name: String,
    pub provider: String,
    pub context_window: u32,
    pub capabilities: ModelCapabilities,  // vision, tool_use, streaming, reasoning
    pub cost: ModelCost,                  // input/output/cache 每百万 token 价格
    pub aliases: Vec<String>,
}
}

别名系统：除了完整的模型 ID（如 claude-sonnet-4-20250514），目录还支持别名查找（如 sonnet → claude-sonnet-4-20250514）。查找顺序（crates/octos-llm/src/catalog.rs:72-74）：精确 ID 匹配 → 别名匹配 → None。

成本追踪：ModelCost 记录输入、输出、缓存读取三种 token 类型的百万 token 价格。AdaptiveRouter 的评分系统使用这些数据计算成本因子（见 3.3.3 节），在延迟和成本之间做权衡。

3.6 成本层：cache 经济学

容错链解决"能不能调通"，成本层解决"这次调用花多少钱"。提交 f3aa07f0（#2194）把 prompt cache 的写入与计价纳入这条链路，出发点是一个不对称的事实：cache 写按 1.25 倍输入价计费，cache 读有折扣，而一次不再重放前缀的调用（compaction 摘要、子 agent 汇总）写了缓存也不会有人读，写入的溢价是纯损失。

一次性调用的 cache-write 退出。 ChatConfig::cache_retention（crates/octos-llm/src/config.rs:58-75，CacheRetention 枚举 74-92 行）为单次请求声明缓存保留偏好：None 表示这次不写缓存。Anthropic 协议上的具体动作是不发任何 cache_control 断点，因为每个断点既读又写，一次没人读的写仍按 1.25 倍计费。Default 维持 provider 配置的缓存行为（Anthropic 的三个 ephemeral 断点）。默认值保持 Default 且 skip_serializing_if 不上 wire，持久化的 ChatConfig JSON 形状不变。装配点在 crates/octos-llm/src/anthropic.rs 的 build_request（cache_control 装配 179-207 行；一次性请求不写 cache 的分支见 148 行附近）。

cache-write 感知定价。 定价层（crates/octos-llm/src/pricing.rs:149-195）按应答 slot 的协议区别建模：只有 Anthropic Messages 协议上报 cache_creation_input_tokens（写，1.25 倍）与 cache_read_input_tokens（读，折扣）；其他协议（openai、openrouter、deepseek、local、未知）的缓存读折扣不可知：目录中唯一的 OpenAI 行 cache_read_per_mtok 为 None，折扣随模型代次变化，套一个 provider 级折扣等于替部分模型编数。因此读按全输入价（1.0 倍，宁可高估不低估）计，写按 1.25 倍而非 0 计（cache_write_tokens 只有 Anthropic 解析器会填）。

flowchart TD
    Req["请求到达"] --> CR{"ChatConfig::cache_retention?"}
    CR -->|Default| CC["Anthropic: 装配三个 cache_control 断点<br/>读 + 写"]
    CR -->|"None（一次性调用）"| NC["不发任何断点<br/>跳过 1.25x 写入溢价"]
    CC --> P["crates/octos-llm/src/pricing.rs 计价"]
    NC --> P
    P --> AP{"slot 说 Anthropic Messages?"}
    AP -->|是| W["写 1.25x / 读折扣价"]
    AP -->|否| F["读按全输入价 1.0x（不低估）<br/>写 1.25x，非 0"]

图 3-2：cache 经济学决策流。 配置层决定写不写，计价层决定怎么算。

3.7 车道与路由：容错链之外的调度件

容错链之外，基线上还有一组围绕"谁来接这次调用"的模块。它们不是同一条链的层，而是按场景挂在 provider 之上的调度件。

crates/octos-llm/src/lane.rs（per-topic 模型车道，RFC-3 / #1292）。 按会话主题（如 slides:*、code:*、research:*）把请求路由到不同模型档位，让"做幻灯片"和"写核心代码"不必共享同一个 primary/fallback 组合。

crates/octos-cli/src/api/router.rs（多模型子 agent 的 provider 路由）。 按前缀方案把 LLM 调用分派给不同子 provider：子 agent 用不同前缀声明自己的模型需求，路由器据此选中对应后端，母 agent 与子 agent 可以在同一会话内并行使用不同模型。

crates/octos-llm/src/call_policy.rs（每 turn 调用策略）。 语音 turn 把 agent run 包在 with_llm_call_policy(FailFast, ..) 里：每个 provider 包装器与叶子 provider 都短路 retry、failover 与 hedge，低延迟优先。策略是 per-turn 的任务级输入，不是全局开关。

crates/octos-llm/src/throttle.rs（信号量节流）。 用信号量限制 provider 的并发调用数，保护有严格并发配额的端点（多凭据时按池分摊）。它管的是"同时几条"，与 registry 管的"用哪个"正交。

crates/octos-llm/src/credential_pool.rs（凭据池，M6.5）。 见 3.3.3 节：多凭据轮换 + 持久化 cooldown，429/auth 失败驱动。

crates/octos-llm/src/local_context_probe.rs（本地窗口探测，#2135）。 提交 10022387 引入。目录里 local / ollama / vllm 家族的窗口数是注册时的保守猜测（约 32K），因为注册时没人知道运营者启动了什么引擎。探测器（1300 行模块，new @ 201，new_ollama @ 226）在后台问服务器拿真实窗口：OpenAI 兼容端点走 props/models 两个 URL，Ollama 原生走 GET /api/ps（取运行中模型的分配窗口，无需 key）。探测结果经 trait 的 ensure_ready() 钩子（crates/octos-llm/src/provider.rs:65）在首次 compaction 决策前 resolve，context_window() 不再是纯静态查表。要压过探测值，用 3.1.2 节的 per-profile context_window 覆盖（操作员覆盖 > 探测 > 目录）。

工程决策侧栏：Arc<dyn Trait> vs 泛型 vs 枚举分发

octos-llm 在 Provider 抽象层大量使用 Arc<dyn LlmProvider>。这个选择值得与两种替代方案对比。

方案一：泛型（impl LlmProvider / T: LlmProvider）

优势：

• 零运行时开销：编译器在每个调用点生成特化代码（单态化）
• 方法调用可被内联优化

劣势：

• RetryProvider、ProviderChain 等包装器需要泛型参数传染：RetryProvider<T: LlmProvider>
• 容错链的组合会产生类型爆炸：AdaptiveRouter<ProviderChain<RetryProvider<AnthropicProvider>>, ProviderChain<RetryProvider<OpenAIProvider>>>
• 无法在运行时基于用户配置动态选择 Provider（泛型在编译期就确定了具体类型）

方案二：枚举分发（enum Provider { Anthropic(...), OpenAI(...), ... }）

优势：

• 编译期确定所有变体，分支预测更友好
• 无 vtable 间接调用开销

劣势：

• 每增加一个 Provider 就需要修改枚举定义和所有 match 表达式
• 对于 19 个 provider family，match 块会非常庞大
• 无法支持用户自定义 Provider（除非用 Custom 变体退化回 trait object）

octos 的选择：Arc<dyn LlmProvider>，原因如下。

在 AI Agent 场景中，LLM 调用的网络延迟（100ms-10s）远大于 vtable 间接调用的开销（<1ns）。动态分发的性能代价在这里完全可以忽略。

更重要的是组合性。octos 的容错链本质上是装饰器模式的嵌套组合：RetryProvider 包装任意 Provider，ProviderChain 管理一组 Provider，AdaptiveRouter 在多个 Chain 之间路由。Arc<dyn LlmProvider> 让这些包装器可以自由组合，不受泛型参数的限制。

最后，Provider 的种类在运行时才确定：用户通过配置文件指定使用哪些 Provider，注册表工厂根据配置动态创建实例。这种"运行时多态"正是 trait object 的核心使用场景。

3.8 本章回顾

octos-llm 解决了 LLM Provider 集成的核心挑战：

1. LlmProvider trait：最小化的统一接口，chat() + chat_stream() 双方法设计，Send + Sync 约束保证线程安全。Provider metadata 让上层能看到实际命中的 provider slot，而不是只看到组合包装器。

2. Provider 注册表：模型名子串匹配自动检测 Provider，工厂模式动态创建 Arc<dyn LlmProvider> 实例。特殊处理 O 系列模型的前缀匹配，并明确把 R9s、OpenRouter、Z.AI、NVIDIA、Ollama、vLLM 这类 detect_patterns 为空的 Provider 留给显式 provider / alias 选择。

3. 容错链（三级能力、两级装配）：

   • RetryProvider：指数退避（1s→2s→4s），智能解析 429 响应的 retry-after 头
   • ProviderChain：有序故障转移 + circuit breaker（3 次连续失败触发降级），缺省装配
   • AdaptiveRouter：四因子 EMA 评分（稳定性 30% + 质量/吞吐 30% + 优先级 20% + 成本 20%）+ 对冲竞赛 + 探针策略，需显式 opt-in，替换而非叠加 chain

4. Credential pool 与 content classifier：429/auth failure 会进入凭据 cooldown / refresh 路径；content classifier 发出 routing.decision 事件，把 Cheap/Strong tier 的选择暴露给 harness。

5. 成本层与调度件：cache 经济学（cache_retention 退出 + cache-write 感知定价）把"写不写缓存"变成显式决策；lane / router / call_policy / throttle / credential_pool / local_context_probe 六个调度件按场景挂在容错链之外。

6. SSE 流式解析：字节级缓冲避免 UTF-8 分割问题，1MB 上限防止内存耗尽，stream::unfold() 构建有状态异步流。

7. Arc<dyn Trait> 选择：网络延迟远大于 vtable 开销，动态分发换来的组合性和运行时灵活性物超所值。

下一章将进入 octos-memory，看看混合搜索（BM25 + HNSW 向量索引）如何为 Agent 提供长期记忆能力。

延伸阅读

• async-trait crate：https://docs.rs/async-trait/latest/async_trait/ — 了解 #[async_trait] 宏如何将 async 方法编译为 trait object 兼容的形式
• SSE 协议规范：HTML Living Standard "Server-Sent Events" 章节，https://html.spec.whatwg.org/multipage/server-sent-events.html
• 指数退避算法：Google Cloud 的 "Truncated exponential backoff" 文档，https://cloud.google.com/storage/docs/exponential-backoff
• Circuit Breaker 模式：Martin Fowler, "CircuitBreaker"，https://martinfowler.com/bliki/CircuitBreaker.html
• Rust 动态分发：The Rust Programming Language 第 17 章 "Using Trait Objects That Allow for Values of Different Types"

思考题

1. 容错层次设计：octos 的容错装配中，如果把 RetryProvider 的重试职责合并进 ProviderChain（chain 直接管理裸 Provider 并自己做退避）会怎样？分离的好处是什么？

2. 对冲竞赛的成本模型：假设你有两个 Provider：Provider A 价格 $10/M tokens、平均延迟 500ms；Provider B 价格 $3/M tokens、平均延迟 1500ms。在什么条件下开启 hedge racing 是划算的？

3. SSE 解析器的替代方案：如果不用字节级缓冲，而是用 String::from_utf8_lossy() 处理每个 chunk，会产生什么问题？在什么场景下这些问题会变得可观测？

4. 泛型 vs trait object 的边界：如果 octos 只需要支持 3 个 Provider（Anthropic、OpenAI、Gemini），枚举分发是否是更好的选择？支持多少个 Provider 时动态分发才开始胜出？

版本演化说明 本章分析基于 ../octos main @ 9c157101（2026-09-02）。本次修订要点：① 注册表从 15 个 Provider 重列为 19 个 provider family（新增 vertex、moonshot-coding、zai-coding、local），注册叙事改为 registry/ 目录 + crates/octos-llm/src/discovery.rs:134 的模型发现协议，不再出现 enum Provider；② trait 补入 ensure_ready() 与 estimate_request_tokens()，provider_metadata_for_index 签名改为 Option<usize>；③ timeout 叙事改讲 CreateParams::http_timeout() 与 DEFAULT_LLM_STREAM_IDLE_TIMEOUT_SECS；④ 新增 3.6「成本层」（cache 经济学，提交 f3aa07f0）与 3.7「车道与路由」（六个调度件模块与 10022387 本地窗口探测）；⑤ sampler passthrough（b0072e70）与 per-profile context_window 覆盖（3e479ce3，接线主体在 octos-cli）写入 3.1.2；⑥ 全部引用行号按 9c157101 逐条重标（crates/octos-llm/src/adaptive.rs 已扩至 2795 行，crates/octos-llm/src/catalog.rs 勘误为 274 行，见 assets/ch03-refcheck.md）。Provider 注册表与评分权重可能继续调整。本轮修复（C2 报告 assets/ch03-techreview.md 裁定项）：⑦ 容错链叙事改为三级能力与两级装配（mermaid 图改为二选一分支，AdaptiveRouter 与 ProviderChain 同位替换而非嵌套）；⑧ ChatConfig 字段清单按 crates/octos-llm/src/config.rs:8-70 重列（删去不存在的 model/system_prompt，补入 stop_sequences、reasoning_effort、context_management）；⑨ 退避序列更正为 1s → 2s → 4s（8s 档位与 60s 钳位在默认序列下不可达）；⑩ 本章回顾由重号的 3.6 改为 3.8。容错能力的三级递进仍是理解 octos-llm 的主线。

第 4 章：octos-memory：混合搜索的工程实现

定位：本章深入 octos-memory crate（wc -l 口径 6,428 行，六个源文件，含测试），展示如何用纯 Rust 构建嵌入式 BM25 + HNSW 混合搜索引擎，为 Agent 提供长期记忆能力。前置依赖：第 2 章。适用场景：想理解 RAG（检索增强生成）底层实现的 AI 应用开发者（读者 C），以及对嵌入式数据库和搜索算法感兴趣的 Rust 开发者（读者 B）。

AI Agent 和 chatbot 的根本区别之一在于记忆。chatbot 的每次对话都是独立的——上一次帮你写的代码、做过的决策、踩过的坑，下一次全部忘记。Agent 需要记忆来积累经验：上次用户偏好什么代码风格？这个仓库最近修改了哪些文件？三天前解决一个类似 bug 时采取了什么策略？

octos-memory 用 6,428 行代码（wc -l 口径，含测试与注释）实现了这个记忆系统。它不依赖任何外部服务——没有 Qdrant，没有 Milvus，没有 PostgreSQL。一个 redb 嵌入式数据库文件加一个内存中的混合搜索索引，就是全部。本章将从存储层开始，逐步深入 BM25 全文搜索、HNSW 向量索引和混合排名融合的工程实现。

4.1 存储选型：redb 嵌入式数据库

4.1.1 为什么是 redb

octos-memory 的持久化层使用 redb（crates/octos-memory/src/store.rs），一个纯 Rust 实现的嵌入式键值数据库。在选型时，最直接的替代方案是 SQLite：Rust 生态中有成熟的 rusqlite 绑定。

redb 相比 SQLite 的优势在 octos 的场景中非常明确：

零 C 依赖。 SQLite 是 C 实现的，rusqlite 需要编译 C 代码或链接系统库。这与 octos workspace 级别的 deny(unsafe_code) 策略冲突：虽然 SQLite 的 C 代码质量极高，但它不受 Rust 编译器的安全检查。redb 是纯 Rust 实现，完全在 deny(unsafe_code) 的保护范围内。

ACID 事务。 redb 提供完整的 ACID 事务支持（读事务和写事务分离），足以满足 episode 存储的持久化需求。octos 不需要 SQL 查询，所有搜索都在内存中的混合索引上进行。

单文件部署。 redb 数据库是一个文件（episodes.redb），不需要额外的 WAL 文件或 SHM 文件。这简化了部署和备份。

4.1.2 三张表结构

Episode Store 在 redb 中定义了三张表（crates/octos-memory/src/store.rs:14-20）：

这个设计把 Episode 数据和向量嵌入分开存储。好处是当不需要向量搜索时（比如 embedding provider 不可用），Episode 的存取不受影响。向量嵌入使用 bincode 序列化（比 JSON 紧凑得多），减少存储和 I/O 开销。

CWD_INDEX_TABLE 是一个辅助索引，按工作目录聚合 Episode ID。当 Agent 在某个项目目录下工作时，优先检索该目录下的历史 episode，提高相关性。

4.2 Episode：Agent 的经验记录

4.2.1 Episode 结构体

Episode 是 Agent 完成一个任务后的经验摘要（crates/octos-memory/src/episode.rs:32-59；结构体前新增了 EpisodeSource 枚举，crates/octos-memory/src/episode.rs:26-31，区分任务摘要与会话压缩摘要，#[serde(default)] 让旧数据照常反序列化）：

#![allow(unused)]
fn main() {
pub struct Episode {
    pub schema_version: u32,     // 数据格式版本
    pub id: String,              // UUID v7
    pub task_id: TaskId,
    pub agent_id: AgentId,
    pub working_dir: PathBuf,    // 任务执行目录
    pub summary: String,         // 任务摘要
    pub outcome: EpisodeOutcome, // 结果
    pub source: EpisodeSource,   // 产生者：任务或会话压缩
    pub key_decisions: Vec<String>,  // 关键决策记录
    pub files_modified: Vec<PathBuf>,
    pub created_at: DateTime<Utc>,
}
}

EpisodeOutcome（crates/octos-memory/src/episode.rs:86-98）定义了内存层可表达的四种结果：Success、Failure、Blocked、Cancelled。它和 Task 的几类终态语义相近，但不能反推"系统一定会把所有终态都写成 Episode"；是否落库取决于上层调用点。当前主 Agent loop 实际只会写入 Success episode。

schema_version 字段（crates/octos-memory/src/episode.rs:36，#[serde(default)] 在 35）是前向兼容的关键。当 Episode 的格式需要升级时（比如新增字段），旧版本的数据仍然可以通过版本号正确解析。默认值为 1（crates/octos-memory/src/episode.rs:16-18，常量在 14），反序列化时如果 JSON 中没有这个字段，自动填充默认值。

4.2.2 写入时机

在当前主 Agent 路径里，Episode 只会在 LLM 响应以 StopReason::EndTurn 或 StopSequence 正常结束，且 save_episodes 打开时创建并存储（crates/octos-agent/src/agent/loop_runner.rs:2457-2504，EndTurn 臂从 2,457 起，写入块在 2,474-2,504；落库逻辑位于 crates/octos-memory/src/store.rs:371-423）。写入过程：

1. 将 Episode 序列化为 JSON，存入 EPISODES_TABLE
2. 更新 CWD_INDEX_TABLE，将 Episode ID 追加到对应工作目录的列表中
3. 更新内存中的混合搜索索引（文本部分）

向量并不是在 store() 中同步写入的。当前实现把 episode 文本和 embedding 分成两个阶段：store() 先写 JSON 和 BM25 索引；store_embedding() 再把 Vec<f32> 用 bincode 写入 EMBEDDINGS_TABLE，并调用 HybridIndex::add_embedding() 给已有文档补上 HNSW 向量。这让 episode 落库不依赖 embedding provider 的可用性。

启动时，EpisodeStore::open() 会扫描 EPISODES_TABLE 和 EMBEDDINGS_TABLE，重建内存中的 HybridIndex。这意味着 redb 是唯一持久源，HNSW 和倒排索引都是可重建缓存。

腐败恢复（crates/octos-memory/src/store.rs:84-111）：CWD_INDEX_TABLE 中的值是 JSON 数组（["id1", "id2", ...]）。如果之前的写入因为崩溃被中断，JSON 可能是损坏的。代码会尝试从损坏的 JSON 中按引号分割抢救 Episode ID，而不是丢弃整个索引。这种防御性编程确保了即使在非正常关闭后也不会丢失索引数据。

删除路径（crates/octos-memory/src/store.rs:757-825）：delete_by_id() 会从 EPISODES_TABLE、CWD_INDEX_TABLE 和 EMBEDDINGS_TABLE 中删除对应数据；内存索引侧调用 HybridIndex::remove()（crates/octos-memory/src/hybrid_search.rs:358-365），但它不会重排 HNSW 的内部 doc index，而是把 ids[pos] 清空作为 tombstone，搜索时过滤空 ID。这是一个典型的 ANN 索引工程取舍：删除快、索引稳定，代价是需要在未来重建索引来清理 tombstone。

4.3 BM25 全文搜索

BM25（Best Matching 25）是信息检索领域最经典的排名算法之一。octos-memory 在内存中维护一个倒排索引来实现 BM25 搜索（crates/octos-memory/src/hybrid_search.rs）。

4.3.1 倒排索引结构

#![allow(unused)]
fn main() {
// crates/octos-memory/src/hybrid_search.rs:8-39（简化）
struct HybridIndex {
    inverted: HashMap<String, Vec<(usize, u32)>>,  // 词项 → [(文档ID, 词频)]
    doc_lengths: Vec<usize>,                         // 每个文档的长度
    total_len: usize,                                // 所有文档长度之和
    avg_dl: f64,                                     // 平均文档长度
    ids: Vec<String>,                                // Episode ID 列表
    hnsw: Option<Hnsw<'static, f32, DistCosine>>,    // 向量索引（无 embedding 时为 None）
    dimension: usize,                                // 索引接受的向量宽度
    // ... 权重与向量覆盖统计字段
}
}

inverted 是倒排索引的核心：给定一个词项（如"重构"），可以快速找到包含该词项的所有文档及其出现频率。

分词策略（crates/octos-memory/src/hybrid_search.rs:731-737）：

#![allow(unused)]
fn main() {
fn tokenize(text: &str) -> Vec<String> {
    text.to_lowercase()
        .split(|c: char| !c.is_alphanumeric())
        .filter(|s| s.len() >= 2)
        .map(String::from)
        .collect()
}
}

采用最简单的分词方式：转小写后按非字母数字字符分割，过滤掉长度小于 2 的词项。对于中文，这并不会自动按单字切开：连续中文（如 中文测试）会保留成一个 token，只有遇到空格、标点等非字母数字字符才会断开，所以 中文 测试 会分成 中文 和 测试 两个 token；中英混写串（如 重构parser模块）也会连成一个 token。效果不如专业分词器（如 jieba），但胜在零依赖，适合摘要式经验检索。它也不过滤停用词，这一点会在 4.3.4 节的热路径优化里再出现。

4.3.2 BM25 评分公式

BM25 的核心公式（crates/octos-memory/src/hybrid_search.rs:636-722，bm25_score() 内；K1/B 项在 655-661）：

score(q, d) = Σ IDF(qi) × (tf(qi, d) × (K1 + 1)) / (tf(qi, d) + K1 × (1 - B + B × |d| / avgdl))

octos 使用的参数（crates/octos-memory/src/hybrid_search.rs:83-84）：

这两个参数值是信息检索领域经过数十年实践验证的经典默认值（源自 TREC 评测实验），octos 直接采用而非自行调优。

IDF 计算（crates/octos-memory/src/hybrid_search.rs:677）：

#![allow(unused)]
fn main() {
let idf = ((n - df + 0.5) / (df + 0.5) + 1.0).ln();
}

IDF（逆文档频率）衡量一个词项的区分度：出现在越多文档中的词（如"代码"、"修改"）IDF 越低，出现在越少文档中的词（如"deadlock"、"HNSW"）IDF 越高。

4.3.3 epsilon 防 NaN

BM25 的评分归一化步骤（crates/octos-memory/src/hybrid_search.rs:703-706 与 718-721）中有一个微妙的工程细节：

#![allow(unused)]
fn main() {
let max_score = result.iter().map(|&(_, s)| s).fold(0.0f64, f64::max);
if max_score < 1e-10 {
    return HashMap::new(); // 所有分数接近零，直接返回空结果
}
// 归一化到 [0, 1]
let normalized = score / max_score;
}

1e-10 阈值检查的作用是防止除以接近零的数。当所有文档的 BM25 分数都极小时（比如查询词没有出现在任何文档中），直接除以 max_score 会放大浮点噪声。通过提前返回空结果，避免了这个问题。

这看起来是一个微不足道的细节，但 NaN 的传播性极强：一旦出现 NaN，后续的排序和融合都会产生错误结果，且不会报错（浮点运算中 NaN 与任何值比较都返回 false），这类 bug 极难定位。

4.3.4 检索热路径：dense 累加器与 top-k 分区

bm25_score() 的两遍开销在高文档频率（df）查询下会成为瓶颈。octos 的分词器不过滤停用词，查询 the fix 里的 the 会命中几乎全部文档（df ≈ n）。2026-08 的 cc6744ba 提交（#1855）改写了这条热路径，结果不变，高 df 查询实测 10 倍加速。

累加器按触达量切换（crates/octos-memory/src/hybrid_search.rs:645-699）。打分前先预估查询会遍历多少 postings（matched_postings，L645-649）：

• dense 分支（L671-686）：触达 ≥ n_docs / 8 时（DENSE_ACCUM_DIVISOR = 8，L89），分配 vec![0.0f64; n_docs] 定长数组，用 touched 向量去重记录碰过的文档，最后回收。彻底消除哈希开销，代价是一次 O(n) 清零。
• sparse 分支（L688-699）：选择性查询留在 HashMap 累加器上，避免为少数几个文档付出整表清零的成本。

分支选择的注释写得很直白：哈希每个 posting 的开销在查询触达大半语料时占主导，而 selective 查询做 dense 清零是纯开销。BM25 每项贡献恒为正（IDF 对数参数对一切 df ≤ n 都大于 1，tf ≥ 1），dense 路径靠"分数从 0 变非 0"检测首次触碰，touched 因此不会漏。

top-k 分区替代全排序（crates/octos-memory/src/hybrid_search.rs:713-716）。旧的实现把所有命中文档全量排序再截断；单个高 df 词就能命中整个语料，全排序成了词法查询的最大成本。现在用 select_nth_unstable_by(limit - 1, by_score_desc) 做 O(matches) 分区后 truncate(limit)。返回类型是 HashMap，保留集内的顺序本来就不在契约里，契约只约束哪些候选存活，所以不需要排序。by_score_desc（L726-728）用 partial_cmp 并把 NaN 视为相等，与 4.3.3 的防 NaN 措施呼应。

4.4 HNSW 向量索引

4.4.1 HNSW 算法简介

HNSW（Hierarchical Navigable Small World）是目前最流行的近似最近邻（ANN）搜索算法之一。它构建一个多层图结构：

• 底层（Layer 0）：包含所有数据点，每个点连接到最多 M 个最近邻
• 上层（Layer 1, 2, ...）：只包含部分数据点，形成"高速公路"：搜索从最高层开始，快速定位到目标区域，然后逐层下降进行精细搜索

这种分层结构让搜索复杂度从线性 O(N) 降低到对数 O(log N)。

4.4.2 octos 中的 HNSW 配置

octos 使用 hnsw_rs crate 构建向量索引（crates/octos-memory/src/hybrid_search.rs:130-138，四个 HNSW_* 常量）：

10,000 的容量对于 Agent 的经验存储来说绰绰有余：即使每天执行 10 个任务，也需要近 3 年才会达到上限。索引在容量达到 80% 和 100% 时会打印警告（crates/octos-memory/src/hybrid_search.rs:277-290，insert() 内的 tracing::warn!；计数的是 HNSW 实际点数而非文档总数，BM25-only 文档不占向量槽位）。

4.4.3 L2 归一化与 cosine similarity

向量搜索的距离度量使用 cosine similarity（余弦相似度），但 HNSW 内部使用的是 DistCosine 距离（泛型参数见 crates/octos-memory/src/hybrid_search.rs:20）。两者的关系是：

similarity = 1.0 - distance

为了确保 cosine similarity 的正确性，所有嵌入向量在插入索引前都经过 L2 归一化（crates/octos-memory/src/hybrid_search.rs:741-747）：

#![allow(unused)]
fn main() {
fn l2_normalize(v: &[f32]) -> Option<Vec<f32>> {
    let norm: f32 = v.iter().map(|x| x * x).sum::<f32>().sqrt();
    if norm < f32::EPSILON {
        return None;  // 零向量无法归一化
    }
    Some(v.iter().map(|x| x / norm).collect())
}
}

零向量保护：norm < f32::EPSILON 检查（crates/octos-memory/src/hybrid_search.rs:743）防止除以零。当 embedding provider 返回全零向量时（可能因为模型错误或空输入），归一化函数返回 None，该文档不会被加入向量索引（但仍然可以通过 BM25 搜索到）。

4.5 混合排名融合

混合搜索的核心价值在于结合 BM25 的精确关键词匹配和向量搜索的语义理解。octos 采用简单的加权融合策略。

4.5.1 融合流程

flowchart LR
    Query["查询文本 + 查询向量"] --> BM25["BM25 搜索<br/>倒排索引<br/>关键词匹配"]
    Query --> HNSW["HNSW 搜索<br/>向量索引<br/>语义匹配"]
    BM25 --> Fusion["加权融合<br/>0.3 × BM25 + 0.7 × 向量"]
    HNSW --> Fusion
    Fusion --> TopK["Top-K 结果<br/>按分数降序"]

图 4-1：混合搜索流程。 查询同时走 BM25 和 HNSW 两路，结果通过加权求和融合。

4.5.2 权重配置

默认权重（crates/octos-memory/src/hybrid_search.rs:92、94）：

#![allow(unused)]
fn main() {
const DEFAULT_VECTOR_WEIGHT: f32 = 0.7;
const DEFAULT_BM25_WEIGHT: f32 = 0.3;
}

向量搜索权重（0.7）高于 BM25（0.3），因为语义相似性在 Agent 经验检索中通常比精确关键词匹配更有价值。例如，查询"如何解决并发死锁"应该能找到之前记录的"用 Mutex 排序避免循环等待"的 episode，即使两者没有共同的关键词。

权重可通过 with_weights() 方法配置（crates/octos-memory/src/hybrid_search.rs:250-254），适应不同场景需求。

4.5.3 融合算法

融合逻辑（crates/octos-memory/src/hybrid_search.rs:465-481，has_vectors 分支）：

#![allow(unused)]
fn main() {
// 对每个候选文档，计算最终分数
for doc_id in all_candidates {
    let vec_score = vector_scores.get(doc_id).unwrap_or(&0.0);
    let bm25_score = bm25_scores.get(doc_id).unwrap_or(&0.0);
    let score = self.vector_weight * vec_score + self.bm25_weight * bm25_score;
    results.push((doc_id, score));
}
}

候选集是两路搜索结果的并集：即使一个文档只出现在 BM25 结果中（向量分数为 0），它仍然可以通过 BM25 分数进入最终排名。这确保了精确关键词匹配不会被语义搜索完全淹没。

当前实现还有一个细节：只有当 vector_scores 非空时才使用 vector_weight / bm25_weight 做加权融合；如果没有可用向量结果，则直接采用归一化后的 BM25 分数，而不是把 BM25 再乘以 0.3。这避免了 BM25-only 降级时所有分数被人为压低。

4.5.4 无 embedding 时的降级策略

当 embedding provider 不可用时（未配置 API key，或 provider 暂时不可达），系统自动降级为纯 BM25 搜索：

1. 插入时：insert() 接受 embedding: Option<&[f32]>，为 None 时只更新倒排索引
2. 搜索时：query_embedding 为 None 时，向量分数全部为 0，最终分数完全由 BM25 决定
3. 索引为空时：如果混合索引中没有任何文档，退回到直接扫描 redb 数据库（判定分支 crates/octos-memory/src/store.rs:461-467，扫描实现 find_relevant_db_scan 在 crates/octos-memory/src/store.rs:554 起），通过 CWD 索引和词项匹配提供基础检索

这种三级降级（混合搜索 → BM25 only → DB 扫描）确保了记忆系统在任何条件下都能提供结果，只是精度逐级降低。

4.5.5 降级的可见性：VectorCoverage

三级降级有一个共同的问题：降级发生时，搜索结果是"悄悄变差"的。一条宽度与索引不符的向量被丢弃，该 episode 静默回落到 BM25-only 召回，查询结果里没有任何迹象。4ccdbe7e（#1851，承接修 1536/768 错宽 bug 的 #1816）把这种状态从"靠翻日志推断"变成"可查询"：

• VectorCoverage（crates/octos-memory/src/hybrid_search.rs:48-58）是一个四字段快照：total（索引内文档数）、vectorized（真正进了 HNSW 的文档数）、dimension_mismatches（因宽度不符被拒绝的向量数）、dimension（索引接受的宽度）。方法 bm25_only() / ratio() / has_dimension_mismatch()（L60-81）给出健康检查可直接上报的指标。
• 计数而非刷屏（crates/octos-memory/src/hybrid_search.rs:36-38、318-337）：store 启动重建索引时会重新插入每条持久化 episode，换过 embedding 模型后逐条告警意味着启动日志一条 episode 一行。现在第一条警告后只计数（mismatch_logged 标志），由 vector_coverage()（crates/octos-memory/src/hybrid_search.rs:231-243；store 侧入口 crates/octos-memory/src/store.rs:640）汇出总数。
• 启动汇总（crates/octos-memory/src/store.rs:289-300）：索引重建完成后打一条汇总警告：错宽 embedding 已丢弃、这些 episode 在重新嵌入前是 BM25-only、存储的向量无法转换只能再生。

配套的修复入口是 octos memory reindex（9ad56caa，#1853，见 4.7.2）。

4.6 MemoryStore：Markdown 持久化记忆

除了 Episode Store 的结构化记忆，octos-memory 还提供了 MemoryStore（`crates/octos-memory/src/memory_store.rs``），一个基于 Markdown 文件的简单记忆系统。

4.6.1 三种记忆形式

4.6.2 7 天窗口记忆

get_memory_context()（crates/octos-memory/src/memory_store.rs:571-573，只是把 load_sections() 的三段渲染成字符串；带 token 预算的版本 get_injectable_context 在 583 起）构建 Agent 的记忆上下文时，load_sections() 读取最近 7 天的笔记（crates/octos-memory/src/memory_store.rs:520）：

#![allow(unused)]
fn main() {
let recent = self.read_recent(7).await?;
}

7 天窗口是一个务实的选择：太短（如 1 天）会丢失近期上下文；太长（如 30 天）会引入过多噪音并占用 LLM 的上下文窗口。7 天大致对应一个工作周，覆盖了大部分"上次我做过类似的事"的记忆需求。

超过 7 天的经验不会消失：它们仍然存在于 Episode Store 中，可以通过混合搜索检索到。7 天窗口只影响自动注入到系统提示中的上下文量。

4.6.3 Memory Bank：二级检索

当前 MemoryStore 还有一层 entity bank（crates/octos-memory/src/memory_store.rs:673-841）。它把稳定事实按实体拆成 Markdown 文件，路径为 memory/bank/entities/<slug>.md。这套机制不是全文搜索，而是两级提示注入：

1. Level 1：摘要索引。 get_bank_summary()（crates/octos-memory/src/memory_store.rs:785-841）遍历所有 entity 文件（目录定位 bank_dir 673、枚举 list_entities 685），跳过 YAML frontmatter（extract_abstract，1222-1241），提取第一个非空、非标题行作为最多 100 字符的摘要，然后把 - **name**: abstract 注入系统提示。chat 和 gateway 都会在长期记忆/每日笔记之后追加这段 Memory Bank 摘要。
2. Level 2：按需全文。 当摘要不够时，Agent 调用 recall_memory 工具读取完整 entity 页面。工具会把用户传入的名字 trim、转小写、空格替换成 -，再从 read_entity() 读取对应 Markdown。

写入由 save_memory 工具完成（落盘在 write_entity，crates/octos-memory/src/memory_store.rs:734）。它要求内容以标题和一行摘要开头；更新已有 entity 时会先读出旧内容（read_entity，718），在工具结果中返回旧版本，提醒调用方不要覆盖掉已有事实。save_memory 的并发等级是 Exclusive，避免同一批工具调用中读写 Memory Bank 产生半写状态。

4.6.4 内容防线：crates/octos-memory/src/guard.rs

Memory Bank 的内容会进入每一次未来会话的系统提示，一条被投毒的条目会跨重启、跨渠道持续存在。多渠道入口（Telegram、邮件、web）意味着第三方文本可以借一句"记住这个"到达这些存储。octos-memory 的第六个源文件 crates/octos-memory/src/guard.rs（325 行）就是为此设的写入与渲染双侧闸门：

• 写入闸（crates/octos-memory/src/memory_store.rs:741 调 crates/octos-memory/src/guard.rs:117 的 first_threat）：write_entity 对内容做威胁模式扫描，命中即 bail! 拒绝落盘。
• 渲染闸（crates/octos-memory/src/memory_store.rs:815）：get_bank_summary 逐行扫描将要渲染进 bank 索引的行，含注入威胁的行被跳过而不是渲染。名称与摘要分开发检查，因为渲染时拼成 - **name**: abstract 一行，拼接缝隙可能重组出注入。

first_threat 的归一化处理两类廉价绕过：零宽字符被过滤、空白折叠；_/-/. 等分隔符映射为空格再扫一遍，让 ignore_all_previous_instructions 这类去分隔形式仍能命中。策略明确偏向严格：记忆内容是用户策展的，误报的代价（用户看到理由后改写）远小于静默接受一次注入。

工程决策侧栏：为什么不用 Qdrant/Milvus 等外部向量数据库

在 AI 应用领域，Qdrant、Milvus、Pinecone 等向量数据库是主流选择。octos 放弃它们而选择嵌入式方案，理由如下。

方案一：外部向量数据库（Qdrant/Milvus/Pinecone）

优势：

• 支持百万甚至亿级向量规模
• 丰富的索引类型和查询能力（过滤、多向量、稀疏向量）
• 分布式扩展能力
• 成熟的运维工具和监控

劣势：

• 增加部署复杂度：用户需要额外运行一个服务
• 网络延迟（即使本地部署也有 IPC 开销）
• 运维成本（备份、升级、监控）
• 启动依赖：向量库不可用时整个 Agent 无法工作

方案二：嵌入式方案（redb + hnsw_rs）

优势：

• 零部署依赖：cargo install 或下载二进制即可使用
• 零网络延迟：搜索在进程内完成
• 零运维：数据库是一个文件，随 Agent 一起备份和迁移
• 优雅降级：即使没有 embedding provider，BM25 搜索仍然可用

劣势：

• 规模上限（10,000 个向量，单机内存限制）
• 搜索功能有限（无过滤、无多向量支持）
• 非分布式（单实例）

octos 的选择：嵌入式方案。

关键洞察是规模需求的差异。RAG 应用需要在百万文档中搜索，这是外部向量库的主战场。但 Agent 的经验记忆是增量积累的：每天几个到几十个 episode，一年下来可能只有几千个。10,000 的容量上限对于绝大多数使用场景绰绰有余。

更重要的是部署体验。octos 的目标用户包括个人开发者和小团队，他们可能只想用一个命令启动 Agent，而不是先部署一套向量数据库基础设施。嵌入式方案让 octos 保持了"下载即用"的简洁性。

4.7 本章回顾

octos-memory 用六个源文件、wc -l 口径 6,428 行 Rust 构建了一个自包含的 Agent 记忆系统：

1. redb 嵌入式存储：三张表（Episodes/CWD 索引/向量嵌入），纯 Rust 实现，ACID 事务保证，单文件部署。

2. BM25 全文搜索：经典 K1=1.2/B=0.75 参数，倒排索引 + IDF 加权，epsilon 防 NaN 归一化。

3. HNSW 向量索引：hnsw_rs crate 提供分层图搜索，L2 归一化保证 cosine similarity 正确性，零向量保护防止索引污染。

4. 混合排名融合：0.7 向量 + 0.3 BM25 加权求和，候选集取并集，三级降级（混合→BM25→DB 扫描）确保任何条件下都能返回结果。

5. Markdown + Memory Bank：MEMORY.md、每日笔记和 entity bank 共同组成提示侧记忆；entity 摘要自动注入，全文通过 recall_memory 按需加载；crates/octos-memory/src/guard.rs 在写入与渲染两侧拦截注入内容。

4.7.1 行数口径

本章行数统一按 find crates/octos-memory -name '*.rs' | xargs wc -l | tail -1 实测（2026-09-02，基线 9c157101）：6,428 行，六个源文件（crates/octos-memory/src/memory_store.rs 2,417、crates/octos-memory/src/store.rs 1,940、crates/octos-memory/src/hybrid_search.rs 1,527、crates/octos-memory/src/guard.rs 325、crates/octos-memory/src/episode.rs 195、crates/octos-memory/src/lib.rs 24），含测试与注释。此前"约 1,750 行"与"1,635 行"两个数字分别对应旧基线与 tokei 代码行口径，本次勘误统一为 wc -l 原始口径。

4.7.2 运维：octos memory reindex

换 embedding 模型等于换向量宽度，旧向量无法转换只能再生。在此之前唯一的"修复"手段是删掉整个 episodes.redb。9ad56caa（#1853）补上了正路：octos memory reindex [--dry-run]（入口 crates/octos-cli/src/commands/memory.rs:44-51，分发 L95，run_reindex L148 起）用已持久化的 episode.summary 重新嵌入。工作清单由 episodes_needing_vectors()（crates/octos-memory/src/store.rs:670）从数据库而非内存索引计算：缺失 embedding 或宽度不符（跳过空摘要）的 episode 全部列出，回填走 store_embedding()（crates/octos-memory/src/store.rs:712）。未配置 embedder 时直接报错退出（L156）；reindex 需要 store 写锁，先停 octos serve 再跑。

下一章将进入 octos-agent，看看 Agent 主循环如何利用这些类型和记忆能力编排一次完整的对话。

延伸阅读

• BM25 算法：Robertson & Zaragoza, "The Probabilistic Relevance Framework: BM25 and Beyond"（Foundation and Trends in IR, 2009）
• HNSW 算法：Malkov & Yashunin, "Efficient and Robust Approximate Nearest Neighbor using Hierarchical Navigable Small World Graphs"（IEEE TPAMI, 2020）
• redb：https://docs.rs/redb/latest/redb/ — 纯 Rust 嵌入式数据库
• hnsw_rs：https://docs.rs/hnsw_rs/latest/hnsw_rs/ — Rust HNSW 实现
• 混合搜索：Anthropic 的 "Contextual Retrieval" 博文讨论了 BM25 + 向量搜索的互补价值

思考题

1. BM25 参数调优：如果 Agent 主要处理中文任务，K1 和 B 参数需要调整吗？中文的分词粒度（单字 vs 词组）如何影响 BM25 的检索效果？

2. 向量维度选择：octos 默认使用 1536 维向量（OpenAI text-embedding-3-small）。如果切换到 384 维的轻量模型，对检索质量和内存占用的影响分别是什么？

3. 混合权重的动态调整：固定的 0.7/0.3 权重是否最优？设想一种根据查询类型动态调整权重的策略：关键词精确查询偏向 BM25，开放式语义查询偏向向量搜索。这需要在架构上做什么修改？

4. 规模瓶颈：如果 octos 需要支持企业级部署（10 万个 episode），当前的嵌入式方案需要做哪些改造？有没有介于"嵌入式"和"外部数据库"之间的中间方案？

版本演化说明 本章分析基于 octos main @ 9c157101（2026-09-02），octos-memory crate 位于 crates/octos-memory/src/，六个源文件按 wc -l 口径共 6,428 行。本次勘误（v2）：① 24 处源码行号引用按 9c157101 重标（cc6744ba / 4ccdbe7e / 9ad56caa 三个提交后行号整体下移）；② 补写三处新面：cc6744ba 的 dense 累加器与 top-k 分区（§4.3.4）、4ccdbe7e 的 VectorCoverage 降级可见性（§4.5.5）、9ad56caa 的 octos memory reindex（§4.7.2），以及 spec 事实边界要求的 crates/octos-memory/src/guard.rs 定位段（§4.6.4）；③ L145 epsilon 摘录与现实现同步（result.iter().map(|&(_, s)| s) / 初值 0.0f64）；④ 行数口径统一为 wc -l 6,428。相比早期版本，MemoryStore 的 entity bank 已经接入 save_memory / recall_memory 工具和系统提示摘要注入；EpisodeStore 支持 embedding 后写入、tombstone 删除与降级可见性上报。

第 5 章：Agent Loop：一次对话的完整生命周期

定位：本章按 crates/octos-agent/src/agent/ 的 20 个模块重组 Agent Loop 的完整叙事，讲清一次 process_message / run_task 从入口到 stop_reason 的六阶段生命周期、预算五道闸与 #27e 落盘检查点、typed retry-bucket 状态机、错误恢复三层类型，以及 goal 层续跑队列与循环的边界。前置依赖：第 2 章（octos-core 类型）、第 3 章（LlmProvider 抽象）。适用场景：想知道「一条用户消息进来之后运行时到底做了什么」的 AI 应用开发者（读者 C），以及要给 loop 提 PR 的贡献者（读者 D）；第 16 章 fleet worker 与第 18 章 goal 续跑都以本章循环为基准变体。

Agent loop 的教科书定义只有一行：收到消息，调用 LLM，解析意图，要工具就执行工具，把结果喂回去，重复直到任务完成。生产级实现的全部难度藏在这行字的边界条件里：迭代上限、token 预算、空闲超时、上下文溢出、消息格式破损、重复输出、provider 故障、优雅关停。octos 把这些边界条件拆进了 crates/octos-agent/src/agent/ 的 20 个模块：排除 *crates/octos-agent/src/agent/loop_runner_tests.rs 后共 21,369 行（口径：cat $(ls *.rs | grep -v '_tests') | wc -l），最大模块不是主循环文件 crates/octos-agent/src/agent/loop_runner.rs（3,979 行），而是工具派发 crates/octos-agent/src/agent/execution.rs（4,730 行）。这个反直觉的事实本身就是本章的切入点：主循环的价值不在「循环」这个动词，而在它编排的决策面。本章所有行号与数字来自 assets/ch05-facts.md（基准 octos main @ 9c157101，2026-09-02），正文中每个源码引用(路径加行号)都可在事实表与源码仓库核对。

5.1 模块地图：20 个模块、21,369 行

先把目录读成一张地图。每个模块的首行 //! 文档注释就是它的自我声明：

按职责可以分三层。主线九模块承担一次 turn 的全部决策：crates/octos-agent/src/agent/loop_runner.rs（编排）、crates/octos-agent/src/agent/turn_state.rs / crates/octos-agent/src/agent/loop_state.rs（turn 内与跨 turn 的 typed 状态）、crates/octos-agent/src/agent/budget.rs（预算与检查点）、crates/octos-agent/src/agent/llm_call.rs / crates/octos-agent/src/agent/streaming.rs（调用与流消费）、crates/octos-agent/src/agent/execution.rs（工具派发）、crates/octos-agent/src/agent/message_repair.rs（消息修复）、crates/octos-agent/src/agent/detection.rs（退化检测）。支线模块各管一个侧面：crates/octos-agent/src/agent/activity.rs（空闲超时）、crates/octos-agent/src/agent/append_only_audit.rs（请求历史只增审计）、crates/octos-agent/src/agent/memory.rs（首轮消息与情节记忆）、crates/octos-agent/src/agent/prompt_segments.rs（系统提示分段）、crates/octos-agent/src/agent/verifier.rs（推理期校验）、crates/octos-agent/src/agent/realtime.rs / crates/octos-agent/src/agent/rich_output.rs / crates/octos-agent/src/agent/turn_failure.rs（实时、富输出、语音失败投影）。压缩双模块（crates/octos-agent/src/agent/compaction.rs 与 crates/octos-agent/src/agent/loop_compaction.rs）本章只交代入口，算法细节详见第 8 章。

crates/octos-agent/src/tools/mod.rs 是装配层：pub struct Agent 的构造与 builder 家族（with_reporter、with_hooks、with_snapshot_manager、with_realtime、with_compaction_runner、with_persistent_retry_state 等，crates/octos-agent/src/agent/mod.rs:691 起）把上述模块的运行时状态接进 Agent 结构体；超时与限额常量集中在 AgentConfig（first-token grace 180s、stream idle 90s、LLM call max 1200s，crates/octos-agent/src/agent/mod.rs:148）。

一个容易被忽略的分层事实：这个目录对外的公开面很窄。crates/octos-agent/src/agent/execution.rs 的工具派发主入口 execute_tools 是 pub(super)（crates/octos-agent/src/agent/execution.rs:2483），crates/octos-agent/src/agent/streaming.rs 的流消费主入口 consume_stream_with_input_estimate 同样是 pub(super)（crates/octos-agent/src/agent/streaming.rs:73），crates/octos-agent/src/agent/message_repair.rs 只有 normalize_tool_call_id 一个全 crate 公开函数（crates/octos-agent/src/agent/message_repair.rs:95）。真正的全公开入口只有 crates/octos-agent/src/agent/loop_runner.rs 的 process_message / run_task 家族。换句话说，crate 边界上只暴露「循环」，不暴露循环的器官。这个可见性设计有一层工程动机：器官级函数的签名还在演化（execute_tools 的返回元组已经长到七个元素，每加一种派发产物就要动签名），若把它们开成 pub，外部调用方会立刻把签名焊死，此后每次演化都是破坏性变更。只公开两个入口家族，等于把「循环怎么编排」的稳定性承诺收缩到最小面，内部模块得以自由重构——事实上 crates/octos-agent/src/agent/execution.rs 比 crates/octos-agent/src/agent/loop_runner.rs 更大，却没有一行代码泄漏到 crate 外。

主线九模块的拆分本身也值得追问：为什么是这九个，而不是按「调用 LLM 的代码」聚成一个文件？答案藏在变更轴上。crates/octos-agent/src/agent/message_repair.rs 修的是消息格式破损，变化频率跟随 Provider 协议差异（Anthropic 要求 tool result 紧跟 assistant、OpenAI 允许间隔）；crates/octos-agent/src/agent/detection.rs 检测的是模型行为退化，变化频率跟随模型生态（小模型的空响应、重复输出形态一直在出新）；crates/octos-agent/src/agent/budget.rs 是纯决策逻辑，几乎不变；crates/octos-agent/src/agent/execution.rs 跟随工具系统演化（详见第 6 章）；crates/octos-agent/src/agent/streaming.rs 跟随 SSE 解析与成本上报需求。五类变更轴互不相同，塞进一个文件意味着每次 Provider 协议调整都要在两千行混合代码里找上下文。按变更轴拆模块，让每个文件的 diff 都有单一主题。

5.2 一次 turn 的生命周期

5.2.1 入口家族

两个入口家族对应两种驱动方式。对话式入口给交互场景：process_message（crates/octos-agent/src/agent/loop_runner.rs:784）、process_message_with_attachments（L804）、process_message_tracked（L817，实时刷新 TokenTracker 供网关状态条）、process_message_tracked_with_attachments（L834），四者全部收敛到私有核心 process_message_inner（L852，循环体绵延至 L2242）。任务式入口给编排场景：run_task（L2243）与 run_task_with_tracker（L2254，供 fleet worker 在外部超时丢弃 future 后仍能读到真实 token 消耗）收敛到 run_task_inner（L2262）。

四个 process_message 变体不是过度设计，每个都对应一个真实调用方形态：基础版给最简单的聊天路径，attachments 版携带本轮附件上下文，tracked 版接 TokenTracker，tracked_with_attachments 版两者都要。若只留一个全参数入口，简单调用方就得传 TurnAttachmentContext::default() 与 None 之类的占位参数，编译器无法帮忙区分「调用方有意禁用」与「调用方忘了传」。收敛到单一 process_message_inner 则保证四个变体共享同一个循环体，不会出现交互路径与追踪路径行为漂移。run_task_with_tracker 的存在动机更具体：fleet worker 在外部墙钟超时会直接丢弃 future，返回的 TaskResult随之丢失，tracker 是唯一能存活下来的记账通道（源码注释明确要求超时路径的结算「never 0」）。

5.2.2 六个阶段

sequenceDiagram
    participant Caller as 调用方(gateway/fleet/orchestrator)
    participant LR as loop_runner<br/>(process_message_inner / run_task_inner)
    participant MR as message_repair + loop_compaction
    participant LC as llm_call
    participant ST as streaming
    participant EX as execution
    participant BU as budget + loop_state

    Caller->>LR: process_message / run_task
    LR->>MR: ① 消息准备(修复 + 压缩入口)
    MR-->>LR: 规范化后的 messages
    loop 每次迭代
        LR->>BU: ② 预算检查 check_budget
        BU-->>LR: BudgetStop 或放行
        LR->>LC: ③ call_llm_with_hooks
        LC->>ST: ④ consume_stream_with_input_estimate
        ST-->>LC: ChatResponse(含 stop_reason)
        LC-->>LR: response + attributed_cost
        alt stop_reason = ToolUse
            LR->>EX: ⑤ execute_tools(派发/超时/hooks)
            EX-->>LR: 工具结果消息 + files_modified
        else stop_reason = EndTurn / MaxTokens
            LR-->>Caller: ⑥ 返回 ConversationResponse / TaskResult
        end
    end

①消息准备：prepare_conversation_messages（crates/octos-agent/src/agent/loop_compaction.rs:27）与任务侧镜像 prepare_task_messages（L71）把历史送进修复管线。crates/octos-agent/src/agent/message_repair.rs 的七个 pub(crate) 函数各修一类破损：normalize_tool_call_ids（L27，统一跨 Provider 的 tool_call_id 前缀与字符集）、normalize_system_messages（L108）、repair_message_order（L189）、repair_tool_pairs（L325）、synthesize_missing_tool_results（L414）、truncate_old_tool_results（L513）。每类修复记入 LoopRepairReason 的七个变体（crates/octos-agent/src/agent/turn_state.rs:48，从 ContextTrimmed 到 ToolCallIdsNormalized），让「这次 turn 动过什么」可观测。

②预算检查：每次迭代开头跑 check_budget（见 5.3 节）。

③LLM 调用：整个调用编排收敛在 crates/octos-agent/src/agent/llm_call.rs 的单一主函数 call_llm_with_hooks（crates/octos-agent/src/agent/llm_call.rs:22），模块其余部分几乎全是测试 mock。它返回的三元组里，usage 把被丢弃的重试尝试合并进最终尝试，attributed_cost_usd 则按实际消耗 token 的 provider 分别计价，调用方必须直接记账而不是用胜出者费率重算合并总量（这是 #1632 P2 钉住的契约）。把调用编排压成单一函数是个自觉的选择：调用前后的 hook、跨 provider 的重试梯、成本归因三者必须严格咬合，任何一处插入新逻辑都可能破坏「重试尝试的 token 不丢账」这条不变量。单一入口让所有调用路径共享同一份编排逻辑，测试 mock 也只需模拟一个函数的形态。若每个调用点自行编排 hook 与重试，第一处遗漏就会造成成本统计黑洞。

④流消费：consume_stream_with_input_estimate（crates/octos-agent/src/agent/streaming.rs:73）消费 SSE 流，处理 shutdown 信号（wait_for_shutdown，L64），结束后由 response_usage_cost（L555）与 emit_cost_update（L581）上报成本，response_to_message（L669）把原始响应转成消息。流消费独立成模块的动机是它管着两类别的模块都不该管的资源：SSE 连接的生命周期（首 token 超时、token 间隔超时、中断检测）与输入 token 的估计。流式响应在结束前拿不到完整的 usage 块，而成本上报又不能等流结束，于是需要一个「边消费边估」的组件。把这段逻辑留在调用方意味着每个 provider 的重试路径都要重复实现一次中断检测；集中在 crates/octos-agent/src/agent/streaming.rs，中断语义全 crate 只有一份。

⑤工具派发：execute_tools（crates/octos-agent/src/agent/execution.rs:2483）决定串行还是并行、计算批超时（compute_batch_timeout_secs，L209）、执行前后 hook、识别长时工具（is_long_running_tool，L174）、处理 spawn_only 产物文件。工具语义本身详见第 6 章。这个 4,730 行的最大模块之所以最大，是因为它独自承担了「把 LLM 的意图变成副作用」的全部工程问题：批量调度（串行、并行、混合三路，run_serial_calls L2738 与 execute_mixed_batch L2846）、超时预算（批内最长工具决定整批时限）、取消与 panic 的结果投影（cancelled_result L3003、timed_out_result L3035、panic_result L3062，三种异常都要变成 LLM 能读的工具结果消息而不是让循环崩掉）、快照（snapshot_before_mutating_tools L2457，变更类工具执行前留底）。若这些职责留在 loop_runner，主循环文件会突破八千行且每条路径都混着工具细节；拆出来后 loop_runner 只看到「一批工具调用进、一批结果消息出」的干净接口。

⑥状态更新与 stop 判定：LoopTurnState（crates/octos-agent/src/agent/turn_state.rs:59）持有 iteration、total_usage、turn_spend_usd、retry/repair 原因列表与 terminal_reason，record_usage（L138）累积消耗，record_budget_stop（L187）记录终止。响应的 stop_reason 决定下一跳：EndTurn 返回、ToolUse 回到 ①、MaxTokens 走续跑与自愈（见 5.4 与 5.6 节）。turn 状态独立成类型（而非散落在循环体的局部变量）的动机在两个伴生枚举：LoopRetryReason（L41，三个变体）与 LoopRepairReason（L48，七个变体）把「这次 turn 重试过什么、修复过什么」变成可枚举的数据。当用户抱怨「这个任务为什么慢」，答案不再是翻日志猜，而是直接读 turn 结束时携带的原因列表。局部变量做不到这件事：它们没有类型，也没有序列化出口。

5.3 预算五道闸与 #27e 检查点

5.3.1 check_budget：五道闸的顺序

每次迭代开头，check_budget（crates/octos-agent/src/agent/budget.rs:100）按固定顺序过五道闸，任何一道命中即返回 BudgetStop：

#![allow(unused)]
fn main() {
pub(super) fn check_budget(
    &self,
    iteration: u32,
    start: Instant,
    total_usage: &TokenUsage,
    activity: &LoopActivityState,
) -> Option<BudgetStop> {
    use std::sync::atomic::Ordering;

    if self.shutdown.load(Ordering::Acquire) {
        return Some(BudgetStop::Shutdown);
    }
    if iteration >= self.config.max_iterations {
        return Some(BudgetStop::MaxIterations {
            limit: self.config.max_iterations,
        });
    }
}

（摘自 crates/octos-agent/src/agent/budget.rs:100，续后依次为 idle progress timeout、activity timeout、token 预算三道闸。）顺序本身就是设计：shutdown 是一次原子加载，用户中断必须最先响应；迭代数是最常见的停止原因，一次整数比较次之；两种超时依赖 crates/octos-agent/src/agent/activity.rs 的活动跟踪（LoopActivityState，crates/octos-agent/src/agent/activity.rs:16）；token 预算最后，因为 budget_tokens_used（crates/octos-agent/src/agent/budget.rs:90）要做四次饱和加法，且很多部署根本不设上限。token 统计把 cache_read 与 cache_write 一并计入：只加 input+output 会让开了 prompt caching 的 Anthropic 循环把预算跑穿约十倍。

BudgetStop（crates/octos-agent/src/agent/budget.rs:13）五个变体各携带对用户有意义的上下文：MaxIterations { limit } 带上限值，MaxTokens { used, limit } 带双方数字，两种 timeout 带 limit。BudgetStop::message()（L41）负责把这些变体渲染成可操作的终止消息；report_budget_stop（L141）再把它变成 ProgressEvent 上报。

预算侧四个公开函数各守一段，分工不是随手切的。BudgetStop 枚举（L13）把「为什么停」定义成数据，五个变体就是五种用户可区分的结局；message()（L41）是唯一的渲染点，终止文案集中在这里，用户在任何界面看到的预算终止话术都出自同一处，不会出现 CLI 说「达到上限」而网关说「budget exceeded」的分裂；budget_tokens_used（L90）是唯一的算术点，cache 计入规则改一处即全局生效；check_budget（L100）是唯一的判定点，五道闸顺序只在这一个函数里存在；report_budget_stop（L141）是唯一的上报点。判定、算术、渲染、上报四件事各一个函数，意味着预算行为的任何变更都能定位到单一函数，而调用方（两个循环体）只需面对 Option<BudgetStop> 这一种中间表示。若把这四件事摊进循环体，五道闸的顺序约束就会散落两处，两个循环迟早演化出不同的停止顺序。

5.3.2 Grace：硬停前的一次宽限

预算命中不总是立刻停。try_budget_grace_call（crates/octos-agent/src/agent/loop_runner.rs:602）先问 LoopRetryState：如果这是首次硬预算耗尽、且自上次宽限以来至少有过一次生产性工具调用，状态机回 Grace（observe_budget_exhaustion，crates/octos-agent/src/agent/loop_state.rs:303），循环多跑一轮，让 Agent 有机会把话说完、把文件写完。全局只宽限一次，第二次直接 Escalate。

5.3.3 #27e：落盘检查点

预算真正耗尽时的最大风险是丢工作树。#27e 在 crates/octos-agent/src/agent/budget.rs 的非测试段落（L484 起）实现落盘检查点，主函数 checkpoint_budget_exhaustion（crates/octos-agent/src/agent/budget.rs:546）：

#![allow(unused)]
fn main() {
pub(super) fn checkpoint_budget_exhaustion(
    workdir: Option<&std::path::Path>,
    stop: &BudgetStop,
    iteration: u32,
) -> Option<String> {
    // Only the ITERATION-cap stop checkpoints: MaxTokens/Shutdown/timeouts
    // have different re-dispatch semantics and stay on the legacy path.
    let BudgetStop::MaxIterations { limit } = stop else {
        return None;
    };
    let dir = workdir?;
    if !dir.join(".git").exists() {
        return None; // not a git worktree — nothing to checkpoint.
    }
}

（摘自 crates/octos-agent/src/agent/budget.rs:546。）触发条件是三个合取：stop 必须是 MaxIterations（L553 的 else 分支让其余四种走 legacy 路径）、workdir 必须是 git 仓库、git status --porcelain 必须非空。命中后做三件事：先以 tmp+rename 原子写 staged result（write_result_md_named，L499；tmp 文件名含 .tmp-27e 标记，L501），再 git add -A 并提交 wip: budget exhausted (#27e) — checkpointed mid-task（本地提交，永不 push），最后返回 budget_exhausted:{limit} 标记拼进 TaskResult.output。

不触发同样重要：clean 工作树不会产生空提交，非 git 目录直接返回，MaxTokens/Shutdown/两种 timeout 不走这条路径，默认 50 次的迭代预算不因此提高。#27h 的写权判定也在这里：result_md_owned_by_peer（L532）读 sidecar .result-owner，内容 trim 后恰为 peer 时，检查点改写 result.checkpoint.md（L579-581）而不碰 peer 的 result.md；sidecar 缺失或不可读按无 owner 处理，fail-open。该判定的唯一公开入口是 result_md_owner_content_is_peer（L542），cli 侧 #1824 安全读路径复用同一函数，保证两个消费者永不漂移。

调用点在任务循环的预算终止分支（crates/octos-agent/src/agent/loop_runner.rs:2328）：Grace 未获准时，先 record_budget_stop 与 report_budget_stop，再取 workspace_root 交给检查点函数，marker 存在时与 stop.message() 一起拼进 TaskResult。

落盘侧的调用链同样一条线：git_in（L484）是最底层的命令执行原语，dirty 判断与 commit 都走它；write_result_md_named（L499）是唯一的落盘写法（tmp 加 rename，tmp 名含 .tmp-27e 后缀，L501），并发读者永远看不到半个文件；result_md_owned_by_peer（L532）与 result_md_owner_content_is_peer（L542）构成写权判定的两层，前者负责读 sidecar、后者负责判断内容，公开的只有后者，cli 侧 #1824 的 fd 锚定安全读路径把读到的内容喂给同一个判断函数，两个消费者共享一份语义；checkpoint_budget_exhaustion（L546）在最上层编排：先做 MaxIterations 合取短路，再判 git 仓库、判 dirty，然后依写权选文件名、原子写 staged result、add -A、本地提交、返回 marker。五个函数一条依赖链，每个环节独立可测（原子写在 L626 起的 budget_checkpoint_tests 有独立测试模块），这正是不把整段逻辑内联进 loop_runner 的原因：检查点逻辑的测试需要真实的 git 仓库环境，放在 crates/octos-agent/src/agent/budget.rs 里可以独立构造临时仓库跑，而不用模拟整个 Agent。

5.4 stop_reason 决策树

把一次迭代的出口画成一棵树：

flowchart TD
    A[迭代开始] --> B{check_budget 五道闸}
    B -- Shutdown/MaxIterations/MaxTokens/ActivityTimeout/IdleProgressTimeout --> C{try_budget_grace_call}
    C -- Grace --> A
    C -- 未获准 --> D[#27e 检查点<br/>MaxIterations + git + dirty 才落盘] --> E[返回 TaskResult]
    B -- 放行 --> F[call_llm_with_hooks]
    F --> G{stop_reason}
    G -- EndTurn --> H[返回响应]
    G -- ToolUse --> I[execute_tools 派发] --> A
    G -- MaxTokens --> J{有内容?}
    J -- 是:任务循环 --> K[push_max_tokens_continuation<br/>续跑 ≤2 次] --> A
    J -- 空内容+无工具调用:对话循环 --> L[nudge-and-retry ≤2 次<br/>耗尽则终态错误]
    F -- 错误 --> M{HarnessError -> RecoveryHint<br/>-> LoopDecision}
    M -- Continue/RotateAndRetry/CompactAndRetry --> A
    M -- Escalate/Exhausted --> N[上抛错误]

任务循环与对话循环对 MaxTokens 的处理不对称。任务循环（run_task_inner）早在 #2174 之前就有续跑：push_max_tokens_continuation（crates/octos-agent/src/agent/loop_runner.rs:3912）在内容被截断时追加「从停下的地方继续」提示，上限 MAX_TOKENS_CONTINUATION_LIMIT = 2（L36），边界检查在 crates/octos-agent/src/agent/loop_runner.rs:2661。对话循环（process_message_inner）原来直接返回 content.unwrap_or_default()，空响应会让进程无错无声退出；#2174 补齐了这条路，见 5.6 节。

5.5 LoopDecision：typed retry-bucket 状态机

错误恢复的心脏在 crates/octos-agent/src/agent/loop_state.rs：LoopRetryState（crates/octos-agent/src/agent/loop_state.rs:217）持有 16 个错误桶各自的计数器（LoopRetryCounters，L186）与上限（LoopRetryLimits，L81）。上限刻意压低：结构性故障的桶几乎不给重试机会（authentication 1、quota 1、content_filtered 1、internal 1），瞬态故障给几次（rate_limited 5、network 4、provider_unavailable 4、timeout 3），shell_spiral 只有 1。

对循环的裁决是 LoopDecision（crates/octos-agent/src/agent/loop_state.rs:131）六个变体，每个变体的裁决语义都值得单独说清。Continue（L134）的含义是「失败预期会自愈」：限流突发、网络抖动、慢工具，重试时上下文原样保留，因为问题不在请求内容；RotateAndRetry（L138）是「当前 lane 病了但任务没病」：5xx、流中断、配额烧穿都属于 provider 级故障，换一条 credential lane 大概率就好，改写上下文反而浪费；CompactAndRetry（L141）是唯一的「改写上下文」裁决，且只服务 ContextOverflow：请求超窗时裸重试必然再失败，压缩是唯一出路，这个变体的存在把「哪类错误需要动上下文」从调用方判断收进类型系统；Escalate（L145）是不可重试类的归宿：auth、invalid request、content filter、工具或插件故障、内部 bug，继续循环只会烧钱，上抛给操作者才是正确动作；Exhausted（L149）不对应任何错误类别，它对应的是「同一桶的计数超过了上限」，这是 #489 不变量 2 的类型化表达：无限循环在这里被强制终结；Grace（L153）是最特殊的一个，它不是错误裁决而是预算裁决的延伸，硬预算耗尽后若循环至少做过一次生产性工具调用，多给一轮收尾。核心判定只有八行：

#![allow(unused)]
fn main() {
pub fn observe(&mut self, error: &HarnessError) -> LoopDecision {
    let (count, limit) = self.bump_counter(error);
    let decision = if count > limit {
        LoopDecision::Exhausted
    } else {
        decide_for_variant(error)
    };
    Self::record_metric(error.variant_name(), decision);
    decision
}
}

（摘自 crates/octos-agent/src/agent/loop_state.rs:266。）桶未满时交给 decide_for_variant（L431）按恢复提示映射：BackoffRetry 到 Continue、SwitchProvider 到 RotateAndRetry、CompactContext 到 CompactAndRetry、FailFast 与 Bug 都到 Escalate。

八个方法各在生命周期的固定位置被调用，拼起来才是一个完整的 turn。new（L234）在循环构造时建立初始态，全桶清零、装默认上限；with_limits（L240）给测试与运维留显式覆盖口；进入循环后，每次工具成功返回都调用 record_productive_tool_call（L253），把 Grace 资格计数器加一，这个资格的意义是：宽限只给「在干活却被预算掐断」的循环，不给空转的循环；LLM 或工具报错时 observe（L266）是主裁决入口，入桶、比限、出裁决、记指标，一次调用完成；shell 重试的退化走专用入口 observe_shell_spiral（L284），第一次螺旋就 Escalate（停住 shell 重试、上抛最近输出），超限则 Exhausted，计数由状态机持有而非 loop_runner 的局部变量，运维在 ledger 里看到的是同一本账；预算命中时 observe_budget_exhaustion（L303）决定 Grace 还是 Escalate，判据是「首次且生产性调用至少一次」；turn 结束或调试时 counters（L319）导出快照；emit_event（L327）把每次裁决写成结构化事件进 harness event sink。时序上一次典型 turn 的调用序是：new（或从持久句柄恢复）、若干次 record_productive_tool_call、零或数次 observe、可能一次 observe_budget_exhaustion、随时的 emit_event。整个状态经 serde 序列化，可随 session ledger 往返；PersistentRetryStateGuard（crates/octos-agent/src/agent/loop_runner.rs:255 附近）在构造时加载、drop 时写回，让桶计数跨 turn 存活，同一 session 里昨天烧掉的三次 network 重试今天仍然计入桶。

stateDiagram-v2
    [*] --> Looping
    Looping --> Continue : observe() 瞬态错误且桶未满
    Looping --> RotateAndRetry : observe() SwitchProvider(quota/provider 不可用)
    Looping --> CompactAndRetry : observe() ContextOverflow
    Looping --> Escalate : observe() FailFast/Bug 或 shell 螺旋首触发
    Looping --> Exhausted : observe() 计数 > 桶上限
    Continue --> Looping : 下一迭代
    RotateAndRetry --> Looping : 换 lane 后重试
    CompactAndRetry --> Looping : 压缩后重试
    Looping --> Grace : observe_budget_exhaustion() 首次且 productive ≥ 1
    Grace --> Looping : 宽限迭代
    Looping --> Escalate_2 : observe_budget_exhaustion() 二次耗尽
    Escalate --> [*]
    Exhausted --> [*]
    Escalate_2 --> [*]
    note right of Grace : record_productive_tool_call() 恢复资格, 全局仅一次

图里每条转移对应状态机里一个可指认的判定。五个从 Looping 出发的裁决转移全部由 observe()（或 observe_shell_spiral()）的一次返回值决定：桶计数与上限的比较结果决定走 Exhausted 还是按 decide_for_variant 的映射走其余四个；Continue / RotateAndRetry / CompactAndRetry 三个回到 Looping 的转移差别在「下一迭代开始前循环体做了什么」：Continue 什么都不做，RotateAndRetry 推进 provider chain 的 lane 指针，CompactAndRetry 触发一次对话压缩（由 dispatch_loop_error 在带内完成，调用方无感）。Grace 的进入条件是两个谓词的合取（grace_calls_fired == 0 且 productive_tool_calls_since_last_grace >= 1），进入即清零生产计数、自增 fired 计数，两个字段一读一写保证「全局仅一次」由数据结构自身而不是调用纪律来保证。Escalate_2 与 Escalate 终点相同但入口不同：前者来自预算耗尽的重访，后者来自错误裁决，分开画是因为两者的运维含义不同，错误上抛要看 variant，预算上抛要看 iteration。

工程决策侧栏：为什么把 retry 从 bool 提升为 typed bucket 状态机

朴素实现是一个「已重试几次」的计数器加一个退避计时器，全部错误共享额度。这在生产里有两个失败模式。其一，额度被错误的错误消耗：一次 429 风暴吃掉全部重试次数，后面真正的结构性 401 反而没有重试预算可谈；反过来 auth 错误被当作可重试错误空转，直到迭代上限。其二，决策不可解释：监控里只能看到「重试了」，看不到为什么重试、还能重试几次、下一跳是什么。M6.2（issue #489）的答案是给每类错误一个独立桶、每桶独立上限、每桶映射到带名字的裁决。LoopDecision::as_str()（crates/octos-agent/src/agent/loop_state.rs:159）输出稳定 snake_case 供指标与事件用，OCTOS_LOOP_RETRY_TOTAL（L42）是总计数指标名。类型化的代价是 16 个字段与 serde 兼容负担（quota 桶后加，还要 default_quota_limit 兜住旧 JSON），换来的是不变量可陈述：同一故障超过桶上限必然 Exhausted，无限循环在类型层面被挡住。

5.6 harness_errors：错误恢复的三层类型

crates/octos-agent/src/harness_errors.rs 用三个类型搭起恢复链：RecoveryHint（L47，五变体：BackoffRetry L50、SwitchProvider L53、CompactContext L56、FailFast L60、Bug L63）描述「这类错误该怎么救」；HarnessError（L93，十五变体，从 RateLimited L96 到 Internal L160）是规范化错误，变体名冻结，其他里程碑按名引用；HarnessErrorEvent（L166）把错误写成结构化事件进 sink。链路是 HarnessError 经 recovery_hint()（L240）得到 RecoveryHint，再由 loop 侧状态机裁决成 LoopDecision。

两处映射值得细看。ProviderUnavailable 映射到 SwitchProvider（crates/octos-agent/src/harness_errors.rs:249）：5xx、流中断、模型不可用都归此变体，agent 内部没有额外的 provider lane hook，实际换 lane 由 loop 侧 RotateAndRetry 裁决驱动 ProviderChain 前进。Quota 也映射到 SwitchProvider（L267，#27b）：配额烧穿是 provider 级降级而非致命错误，链上的 fallback lane 可能还健康；而真正的 401 Authentication 保持 FailFast，因为错误密钥在每条 lane 上都会失败。这条红线有测试钉住。

进入这条链的入口在 crates/octos-agent/src/agent/loop_runner.rs：classify_loop_error（crates/octos-agent/src/agent/loop_runner.rs:313）把 eyre::Report 经 HarnessError::classify_report 归类、记指标、写事件；dispatch_loop_error（L437）把归类结果喂给 LoopRetryState::observe 并再写一条 retry 事件；调用侧拿到的只是二选一的粗粒度动作 LoopErrorAction（L249，Retry 或 Bail），CompactAndRetry 在带内完成，调用方无须穿透压缩状态。

5.7 循环自愈：两个退化实例

小模型会让循环以两种方式退化，两个提交各修一种。

空 MaxTokens 的静默死路（#2174，提交 9fe39f1b，2026-08-28）。Qwen 3.8 在一次压缩后把 16,384 token 的输出预算全部花在 reasoning 上，没有内容也没有工具调用，octos chat 干净地退出，无输出无错误。修复只针对这个退化分支：MaxTokens 响应空内容且无工具调用时，做有界 nudge-and-retry：

#![allow(unused)]
fn main() {
if content_empty
    && response.tool_calls.is_empty()
    && max_token_empty_recoveries < MAX_TOKENS_CONTINUATION_LIMIT
{
    max_token_empty_recoveries += 1;
    let mut assistant = Message::assistant(String::new());
    assistant.reasoning_content = response.reasoning_content.clone();
    messages.push(assistant);
    messages.push(Message::user(MAX_TOKENS_EMPTY_RECOVERY_PROMPT));
}

（摘自 crates/octos-agent/src/agent/loop_runner.rs:2171 附近的对话循环 MaxTokens 分支；nudge 提示常量在 L42，上限仍是 2，耗尽后改为返回 L45 的终态错误消息而非空成功。带内容的 MaxTokens 响应原样返回，云端正常截断不受影响。）

强制贪心采样的重复坍缩（#2172，提交 3c7ff8bf，2026-08-28）。octos 曾对每个 chat 请求硬编码 temperature=0.0，本地小模型上贪心 argmax 会确定性重发同一工具调用，实测一条响应里重复了 763 次相同的 update_plan 调用。修复加了 gateway.llm_temperature 配置项，穿透到 AgentConfig.chat_temperature（crates/octos-agent/src/agent/mod.rs:97），在纯函数 build_chat_config（crates/octos-agent/src/agent/loop_runner.rs:3957）里应用。云端安全是构造保证：配置缺省时函数保持 ChatConfig::default() 的 0.0，云端请求逐字节不变；本地模型运维方设置如 0.7 即可避开坍缩。把覆盖语义提为自由函数，正是为了让「缺省不动默认值」这条不变量可以脱离完整 Agent 做单元测试。

这两个实例共同说明循环自愈的形状：检测退化条件（空内容、无进展），有界恢复（≤2 次），恢复不了就给可读的终态而不是空成功或静默退出。

5.8 退化检测

crates/octos-agent/src/agent/detection.rs 是循环的免疫层，五个 pub(super) 函数：is_retriable_response（crates/octos-agent/src/agent/detection.rs:60，空响应等可在调用层重试的形态）、normalize_inline_invokes（L84）、is_repetitive_output（L111，重复文本检测）、is_retryable_stream_error（L146）、is_truncated_tool_call_error（L168）。加上工具序列层面的 LoopDetector（窗口 12，任务循环注释明确对齐对话循环窗口）与 crates/octos-agent/src/agent/loop_state.rs 的 SHELL_SPIRAL_VARIANT（L180，shell 螺旋计数由状态机持有），构成三层：响应层、序列层、桶层。检测命中后的动作都已类型化：响应层回到调用重试梯，序列层停住本轮工具执行并上抛最近输出，桶层走 5.5 节的裁决。

5.9 支线模块一览

四个支线模块各用一段交代。crates/octos-agent/src/agent/memory.rs 负责首轮消息构建与情节记忆召回：build_initial_messages（crates/octos-agent/src/agent/memory.rs:249）、recall_relevant_episodes（L86）、save_conversation_episode（L174），相似度阈值 MIN_EPISODE_SIMILARITY = 0.55（L44）；检索机制详见第 4 章。crates/octos-agent/src/agent/prompt_segments.rs 用 PromptSegmentProvider trait（crates/octos-agent/src/agent/prompt_segments.rs:25）维护有序系统提示段，支持具名替换与热刷新。crates/octos-agent/src/agent/verifier.rs 是可选的推理期校验器加紧凑 turn ledger：TurnLedger（L168）逐工具批记录条目，should_verify_after_tool_batch（L212）决定是否触发校验，ready_gate_active（L243）实现「校验通过才许终止」的门。crates/octos-agent/src/agent/append_only_audit.rs 回答一个问题：一次 turn 的请求历史是否只增不减（Rewrite 枚举，L162），默认关闭，OCTOS_APPEND_ONLY_AUDIT=1 才开启且绝不改写请求。crates/octos-agent/src/agent/realtime.rs（心跳与传感器注入，Heartbeat L128、SensorContextInjector L238）、crates/octos-agent/src/agent/rich_output.rs（从短 brief 生成自包含 HTML，author_html L85）、crates/octos-agent/src/agent/turn_failure.rs（语音 turn 失败投影，TurnFailure L9）服务特定运行模式，详见第 14 章。

5.10 续跑边界：goal 层的 master_continuation_scheduler

循环返回 stop_reason 之后，谁决定再开一个 turn？答案不在 agent crate。crates/octos-cli/src/autonomy/master_continuation_scheduler.rs（1,416 行）是一个纯数据结构：延迟优先队列，无 tokio 依赖、无 LLM 调用。入队原因 MasterContinuationReason（L137）六变体：ChildCompleted、ScatterJoinComplete、LoopFire、GoalContinue、GoalWrapUp（#1131，预算耗尽的收尾 turn）、External(String)；优先级映射在 priority()（L152）：LoopFire 最高，ChildCompleted 与 ScatterJoinComplete 次之，GoalContinue 与 GoalWrapUp 同级，External 最低。队列本体 MasterContinuationScheduler（L477）提供 enqueue（L525）、drain_ready（L687）、drain_ready_for_session（L706）等接口。

它被 AgentOrchestrator 持有为状态字段 continuations（crates/octos-cli/src/autonomy/agent_orchestrator.rs:11783），出队走 drain_ready_continuations_for_session（L3027）到内部 drain_ready_continuations_locked（L3112）。loop 侧唯一可见的效果是：一次 run_task 返回后，orchestrator 依据 ready 队列与优先级再次派发新 turn。「turn 结束后再创造 turn」的完整语义属于 goal 层，详见第 18 章。

5.11 本章回顾

1. 模块地图：agent/ 20 模块 21,369 行，三层分工（主线九模块、支线模块、压缩双模块），公开面只有 crates/octos-agent/src/agent/loop_runner.rs 的 process_message / run_task 家族，器官级入口全部 pub(crate) / pub(super)。
2. 生命周期：消息准备（修复七函数）、预算检查（五道闸）、LLM 调用（单一主函数）、流消费、工具派发、状态更新六阶段，主循环文件编排而不实现。
3. 预算与检查点：check_budget 顺序即设计；Grace 给硬停前一次宽限；#27e 在 MaxIterations 且 git 且 dirty 三条件合取时本地提交 WIP、原子写 staged result（peer 持有写权时写 result.checkpoint.md）、永不 push、fail-open。
4. 错误恢复：HarnessError（十五变体）→ RecoveryHint（五变体）→ LoopDecision（六变体）三层链路，16 桶独立上限，ProviderUnavailable 与 Quota 换 lane、Authentication 保持 FailFast。
5. 循环自愈：空 MaxTokens 的有界 nudge（9fe39f1b）与云端安全的 temperature 覆盖（3c7ff8bf），检测退化、有界恢复、终态可读。
6. 续跑边界：scheduler 是 goal 层纯队列，loop 只负责把 stop_reason 交回去。

延伸阅读

• assets/ch05-facts.md：本章全部行号与数字的事实表，附生成命令，可逐条复现。
• 第 3 章的三层容错链（RetryProvider / ProviderChain / AdaptiveRouter）：RotateAndRetry 裁决落地后实际换 lane 的机制。
• 第 8 章：crates/octos-agent/src/agent/compaction.rs / crates/octos-agent/src/agent/loop_compaction.rs 背后的分层压缩算法。
• 第 18 章：MasterContinuationScheduler 的消费侧与 goal 续跑全貌。
• issue #489（M6.2 typed retry bucket）与 #2172 / #2174 的提交说明：本章状态机与两个自愈实例的第一手动机。

思考题

1. check_budget 的五道闸顺序如果重排（比如把 token 预算放最前），会在什么部署形态下引入可观开销或行为回退？给出你的排序理由与边界条件。
2. #27e 只在 MaxIterations 触发。若要让 MaxTokens 也支持「耗尽即检查点」，re-dispatch 语义需要哪些额外信息？改触发条件本身够吗？
3. 16 个桶的上限里，provider_unavailable 给 4 次、authentication 给 1 次。假如引入一种新的「provider 计费窗口冷却」错误，你会给它独立桶还是并入 quota？判断标准是什么？
4. 对话循环的空 MaxTokens nudge 上限是 2。把这个上限做成可配置，收益与风险各是什么？谁应该是这个配置的所有者：模型运维、平台运维，还是用户？
5. execute_tools 是 pub(super) 而 process_message 是全公开。如果外部调用方需要绕过循环直接执行一批工具，应该在 crate 边界上开新口，还是复用 execute_approved_tool（crates/octos-agent/src/agent/execution.rs:469）这样的既有公开函数？两种选择的审计面差异在哪里？

版本演化说明

本章分析基于 octos main @ 9c157101（9c1571016e5ea86955b4b3486c04f0359dfff339，2026-09-02 19:37 +0800 统计）。所有行号与规模数字（20 模块、21,369 行、crates/octos-agent/src/agent/execution.rs 4,730 行、crates/octos-agent/src/agent/loop_runner.rs 3,979 行等）的口径与复现命令见 assets/ch05-facts.md。相对 v1 旧稿，本章整章重写：按 20 模块地图重组叙事，取代旧稿「单文件逐段走读」骨架；预算检查点（#27e）、Grace 宽限、typed retry-bucket 状态机（M6.2 #489）、循环自愈两实例（#2172 / #2174）与 goal 层续跑边界为新增内容；旧稿引用的 loop_detect 等行号如与新版源码不符，以事实表为准。

第 6 章 工具系统：按能力域组织的 58 个源文件

定位：本章深入 Agent Loop 中"行动"阶段的核心,即工具系统。与旧稿按固定数量罗列内置工具的线性清单写法不同，本章按能力域重组叙事：先纵览 crates/octos-agent/src/tools/ 的 58 个条目如何划分成 10 个能力域，再下沉到三个骨架文件(crates/octos-agent/src/tools/registry.rs 3,581 行、crates/octos-agent/src/tools/policy.rs 741 行、crates/octos-agent/src/tools/args.rs 479 行)讲清 Tool trait 契约、注册与查找、曝光控制、策略判定与参数安全。前置依赖：第 5 章(agent loop 如何调用工具)。适用场景：想理解 Agent 工具架构的 AI 应用开发者(读者 C)，以及想为 octos 贡献新工具的开发者(读者 D)。

Agent 的"智能"来自 LLM,但 Agent 的"能力"来自工具。没有工具,Agent 只能生成文本;有了工具,Agent 可以读写文件、执行命令、搜索网页、管理 Git 仓库、派出子代理。

先统一口径。以 ls crates/octos-agent/src/tools/ | grep -v test 实测,tools/ 下共 58 个条目:57 个 .rs 文件加一个 admin/ 子目录(内含 7 个文件,合计 3,424 行)。黑板与早期规划里出现的"59 个源文件"是把测试类文件与 crates/octos-agent/src/tools/mod.rs 计满后的口径(ls crates/octos-agent/src/tools/*.rs | wc -l)。本章统一采用"58 条目 + admin 子目录 7 文件"的结构口径,不再沿用旧稿那个早已失效的固定工具数:当前源码里本来就不存在一个稳定的"总工具数":同一批源文件在不同构造路径下注册出不同的工具面,理解这个分层注册模型,比记住一个固定数字更重要。

工具带来能力的同时也带来风险:每个工具调用都是一个潜在的攻击面。octos 的答案是一道骨架三防线:ToolPolicy 控制哪些工具可用(deny-wins),参数验证控制输入安全(1 MB 上限与结构化报错),symlink-safe I/O 与 SSRF 校验控制文件系统与网络边界。第 7 章会展开沙箱与 write_grant 的运行时语义,本章只讲工具侧的接口与注册。

6.1 能力域全景:58 个条目怎么分组

按事实表(assets/ch06-facts.md,commit 552be31)的归属,tools/ 下的源文件可以划分成 10 个能力域。下表是本章的导航图,每个能力域随后各有一小节:

表的合计口径:58 个条目 = 上表 10 域的 55 个文件级条目(平台杂项按实际清单 6 条,admin/ 整体算 1 条)+ 不归属任何域的骨架三件(registry、policy、args)。

图 6-1 能力域工具家族(mermaid,正文渲染):

graph LR
    subgraph 文件系统
        A1[read_file] --> A2[read_window]
        A3[write_file] --> A4[edit_file/diff_edit]
        A5[apply_patch] --> A6[replacer]
        A7[list_dir/glob/grep] --> A8[workspace_history]
    end
    subgraph 执行
        B1[shell] --> B2[check]
        B3[write_grant]
    end
    subgraph Web/研究
        C1[web_fetch/web_search] --> C2[site_crawl/deep_search]
        C3[synthesize_research] --> C4[http/ssrf]
        C5[browser]
    end
    subgraph 记忆
        D1[save_memory] --> D2[recall_memory/recall]
        D3[memory_note] --> D4[record_memory_use]
    end
    subgraph Peer/Fleet
        E1[spawn/delegate] --> E2[peer_* 六件]
        E3[check_background_tasks] --> E4[read_task_output]
    end

有几个名字与直觉不符,值得先说清。crates/octos-agent/src/tools/glob_tool.rs 注册的工具名是 glob,crates/octos-agent/src/tools/grep_tool.rs 是 grep,crates/octos-agent/src/tools/workspace_history.rs 里是 workspace_log,crates/octos-agent/src/tools/site_crawl.rs 是 deep_crawl,crates/octos-agent/src/tools/deep_search.rs 是 search,crates/octos-agent/src/tools/delegate.rs 是 delegate_task。文件名与工具名分离,是这批文件早期为避让 Codex 兼容别名留下的痕迹。crates/octos-agent/src/tools/coding_tools.rs 更特殊:一个文件里实现了 exec_command、write_stdin、spawn_agent、bash、delegate、view_image、tool_search、tool_suggest、image_generation 等一整组 Codex 兼容 shim(crates/octos-agent/src/tools/coding_tools.rs:381、:738、:1283、:1945、:2428、:2800、:3149、:3250、:3388),所以"文件数不等于工具数"在两个方向都成立。crates/octos-agent/src/tools/replacer.rs、crates/octos-agent/src/tools/read_paging_probe.rs、crates/octos-agent/src/tools/ssrf.rs、crates/octos-agent/src/tools/dora_bridge.rs、crates/octos-agent/src/tools/http.rs、crates/octos-agent/src/tools/read_window.rs、crates/octos-agent/src/tools/write_grant.rs 甚至不是独立工具,而是被其他工具复用的支撑模块或特性开关,这也是能力域分组的第二个维度:按"谁依赖谁"而不只按"叫什么名字"。

能力域之外还有第二套坐标系要认清。上面的域是文件组织的事实划分,crates/octos-agent/src/tools/policy.rs 里另有一张按 LLM 可见入口划分的策略分组表 TOOL_GROUPS(crates/octos-agent/src/tools/policy.rs:187 起,ToolGroupInfo 结构在 :179-183,共 10 组),两套并不重合。group:fs 只收 read_file、write_file、edit_file、diff_edit、apply_patch 五个主入口,文件系统域的 12 个文件里过半不在组内;bash 别名的实现在 crates/octos-agent/src/tools/coding_tools.rs(代码/结构域),却因 #1172 被收进 group:runtime;group:sessions 的七个成员横跨 Peer/Fleet 域与 Codex 兼容 shim。分组按工具名而非文件名,理由直接:策略要约束的是模型喊得到的名字,不是源码存放的位置。

这张静态表有一条硬不变量。group:delegated(M6.7,crates/octos-agent/src/tools/policy.rs:307 起)是委派子代理的标准 deny 表,必须覆盖 group:sessions 的全部成员,否则子代理能再派孙代理,从递归护栏底下穿过去。expand_group 返回扁平静态切片,组机制没有组内组展开,超集只能手工维护,测试 group_delegated_supersets_session_spawn_family 在每次构建时逐项核对,注释里记录了这次漂移确实发生过:spawn_agent、send_input、*_agent 生命周期工具与 delegate 包装器一度全部可达。同一张表还故意不收 shell,注释原文写明这里不是 confinement boundary,命令执行的约束交给沙箱层,工具策略层管不了也不该装作能管。

下面按域速览,每域点出代表性设计与源码位置。

6.1.1 文件系统(12 个)

这是最重的一域:crates/octos-agent/src/tools/read_file.rs 2,366 行、crates/octos-agent/src/tools/write_file.rs 2,220 行,单文件就超过多数域的总和。设计要点有三。

第一,读有多条路径而不是一条。read_file 负责常规读取,crates/octos-agent/src/tools/read_paging_probe.rs 是一个"只观察不改变行为"的分页探针(crates/octos-agent/src/tools/read_paging_probe.rs:1-6),用来回答"强制分页到底省不省 token"这个测量问题;crates/octos-agent/src/tools/read_window.rs 是特性开关 OCTOS_READ_WINDOW=1 才启用的窗口化强制(crates/octos-agent/src/tools/read_window.rs:3、:178),默认关闭,不设环境变量时行为与旧版逐字节一致。三者并存说明:读路径的每一次收紧都必须先拿数据,再拿默认值。

第二,写有四个层次。write_file 全量写,edit_file 精确替换,diff_edit 按上下文匹配,apply_patch 接受标准 patch 格式。它们共用 crates/octos-agent/src/tools/replacer.rs 的级联模糊匹配链(#1771):LLM 给出的 old_string 常有空白、缩进、转义差异,edit_file 不再硬失败,而是按 exact → line_trimmed → … 的顺序逐级放宽,用第一个有结果的匹配器(crates/octos-agent/src/tools/replacer.rs:1-8)。这条链是"容忍模型的不精确"这一原则的落地。

第三,检索三件(list_dir/glob/grep)与 crates/octos-agent/src/tools/workspace_history.rs(注册名 workspace_log,见 crates/octos-agent/src/tools/workspace_history.rs:101)补齐"找文件"与"看历史"。

6.1.2 Shell/执行(3 个)

crates/octos-agent/src/tools/shell.rs 2,745 行,注册名 shell,是执行域的主力;同域的 bash 别名在 crates/octos-agent/src/tools/coding_tools.rs:1945。crates/octos-agent/src/tools/check.rs 是工作区检查器(注册名 check,crates/octos-agent/src/tools/check.rs:526)。crates/octos-agent/src/tools/write_grant.rs 不是工具而是 #1976 引入的按路径写授权结构:WritePathGrant 通过 write_file/edit_file 的 with_write_grant 构造器绑定,让"写越界"从礼貌请求变成类型化拒绝(crates/octos-agent/src/tools/write_grant.rs:53、:72)。它的运行时语义与沙箱翻译在第 7 章,这里只需要知道:授权的匹配语法是单段通配(*/? 限一段,拒绝 **、[...]、{...})。

6.1.3 Web/研究(9 个)

从 web_fetch 单页抓取、web_search 搜索,到 site_crawl(注册名 deep_crawl)与 deep_search(注册名 search)的站点级/多跳研究,再到 synthesize_research 汇总成文。支撑模块三个:crates/octos-agent/src/tools/http.rs 是原始 HTTP 客户端(工具名由构造器传入,crates/octos-agent/src/tools/http.rs:130),crates/octos-agent/src/tools/ssrf.rs 是共享的 SSRF 防护(check_ssrf_with_addrs 在 crates/octos-agent/src/tools/ssrf.rs:24,含 DNS pinning 防重绑定,validate_answer_set 在 :69,重定向上限 SSRF_MAX_REDIRECTS = 10 在 :101),crates/octos-agent/src/tools/browser.rs 是无头浏览器。注意输出限额按工具名区分:octos_core::tool_output_limit 里 read_file 50,000 字节、shell 30,000、web_fetch 40,000、web_search 20,000、search(deep_search)200,000(crates/octos-core/src/utils.rs:180-196)(研究类工具拿到的是最宽的额度)。

6.1.4 记忆(5 个)

save_memory 写入、recall_memory 召回、memory_note 记笔记、record_memory_use 记使用账;crates/octos-agent/src/tools/recall.rs 是 #2131 引入的新成员:当上下文压缩把某次工具输出替换成占位符后,recall 凭 tool_call_id 从内容寻址的输出台账里把完整字节重新物化,而不必重跑那次调用(crates/octos-agent/src/tools/recall.rs:1-4)。它通过 ToolOutputLedger trait 与 octos-cli 的 ContextManager 保持独立(crates/octos-agent/src/tools/recall.rs:15-21),注册名 recall(:106)。这条机制与第 8 章的压缩台账直接呼应。

6.1.5 消息/交互(4 个)

message 发文本、send_file 发文件、send_app_card 发卡片、ask_user_question 向用户提问。这一域的特点是"结果不是给模型的,是给人的":输出走消息总线而非工具结果(MessageTool/SendAppCardTool 共享同一个 tx 通道注册,crates/octos-agent/src/tools/registry.rs:1735-1736;send_app_card 的描述里明确要求 initial_state 必须来自真实工具数据、严禁编造,crates/octos-agent/src/tools/send_app_card.rs:130-140),第 10 章展开。

6.1.6 Peer/Fleet(10 个)

最大的一域。crates/octos-agent/src/tools/spawn.rs 5,309 行,是全书最大的单工具文件(注册名 spawn,crates/octos-agent/src/tools/spawn.rs:2922);crates/octos-agent/src/tools/delegate.rs(注册名 delegate_task)是单次调用版。peer_handoff/peer_send_input/peer_gather/peer_list/peer_respond/peer_close 六件构成 peer 通道原语,check_background_tasks 与 read_task_output 补齐后台查询。这一域与 spawn_only 曝光控制(6.3 节)绑定最深:后台化工具的调用正是被执行循环拦截转成后台任务的。

6.1.7 代码/结构(2 个)与 Git(1 个)

crates/octos-agent/src/tools/code_structure.rs 输出源码符号结构(注册名 code_structure;内部有 1 MB 解析上限,crates/octos-agent/src/tools/code_structure.rs:72),crates/octos-agent/src/tools/coding_tools.rs 如上是 Codex 兼容 shim 集合。crates/octos-agent/src/tools/git.rs 注册名 git,diff 侧同样有 1 MB 单文件上限(crates/octos-agent/src/tools/git.rs:291)。

6.1.8 技能/插件(3 个)与平台杂项

manage_skills 管理技能包,dora_bridge 接机器人框架(工具名来自映射表,crates/octos-agent/src/tools/dora_bridge.rs:178),mcp_agent 让 spawn 能把任务派给任何 MCP 后端(crates/octos-agent/src/tools/mcp_agent.rs:1-6)。平台杂项里 crates/octos-agent/src/tools/tool_config.rs 注册名是 configure_tool(crates/octos-agent/src/tools/tool_config.rs:633),mofa_make 是分发器(其目标工具被 mark_internal_hidden 隐藏,6.3 节),crates/octos-agent/src/tools/robot_groups.rs 维护机器人安全分级(SafetyTier:工具在 RobotToolRegistry 里按最低所需档位注册,档位展开时低档自动包含高档工具,crates/octos-agent/src/tools/robot_groups.rs:26-38、51-59),admin/ 子目录 7 文件提供 20 个 admin_* 运维工具(admin_list_profiles、admin_system_health、admin_update_octos 等)。

为什么按域拆文件,而不是一个大文件

回到 6.1 开头的分组表,值得问一句:12 个文件系统工具为什么不并成单个大文件?域内共享的是不变量与依赖方向,不是代码量。文件系统域共享三条:路径必须先过 resolve_path 族归一;读写必须走 no-follow 系调用;输出必须接受 tool_output_limit 截断。把这三条放进一个共享模块、把工具语义放进各自的文件,新增一个读路径工具时只需要实现语义,不用重抄防线。反过来,域与域之间刻意不共享:Web 域的 SSRF 校验与文件域的路径校验互不引用,因为两者的威胁模型不同(前者是外发请求重定向,后者是本地符号链接),混装会让一个域的修改变成另一个域的回归面。crates/octos-agent/src/tools/spawn.rs 5,309 行已经证明单文件膨胀的代价,crates/octos-agent/src/tools/registry.rs 3,581 行是另一个极端,中间态就是按域分文件的现状。

6.2 Tool trait:契约在 crates/octos-agent/src/tools/mod.rs

所有工具实现同一个 trait(crates/octos-agent/src/tools/mod.rs:609):

#![allow(unused)]
fn main() {
#[async_trait]
pub trait Tool: Send + Sync {
    fn name(&self) -> &str;
    fn description(&self) -> &str;
    fn input_schema(&self) -> serde_json::Value;
    fn tags(&self) -> &[&str] { &[] }
    fn contexts(&self) -> &[String] { &[] }
    async fn execute(&self, args: &serde_json::Value) -> Result<ToolResult>;
    fn truncation_recovery(
        &self,
        args: &serde_json::Value,
        omitted_bytes: usize,
    ) -> Option<String> { None }
    async fn execute_with_context(
        &self,
        ctx: &ToolContext,
        args: &serde_json::Value,
    ) -> Result<ToolResult> { /* 默认委托 execute */ }
}
}

契约分三层。声明层(name + description + input_schema)构成发给 LLM 的 ToolSpec。执行层是两个入口:execute 是遗留的仅参数签名,execute_with_context 是 M8.1 引入的类型化入口(crates/octos-agent/src/tools/mod.rs:11-28 的模块文档详细记录了这次迁移):默认实现互相委托,迁移后的工具覆写 execute_with_context 并让 execute 以零值上下文重入,保证外部调用者行为可预测。一个工具至多覆写其一,同时覆写会产生执行器无法调和的两条独立路径。治理层是 tags()(能力标签,供 require_tags 过滤)与 contexts()(声明本工具只在哪些模型上下文曝光,空列表表示处处可见)。

truncation_recovery 值得单说。截断发生在执行循环,而执行循环拿到的是裸字符串,不知道哪个工具产出、是否支持分页、参数叫什么;工具知道怎么续读,却不知道自己被截了。这个钩子是缺失的另一半:循环截断后带着 args 与 omitted_bytes 来问,工具返回一条"下一步该怎么调"的具体建议,默认 None 表示没有续读路径,不编造。配套的输出上限正是 6.1.3 提到的 tool_output_limit(crates/octos-core/src/utils.rs:180)。

类型化上下文 ToolContext(crates/octos-agent/src/tools/mod.rs:261)本身是一份架构自传:reporter 与 harness 事件槽是 UI 通道,agent_definitions、permissions、file_state_cache、notifications、app_state 是 M8.1 预埋、后续里程碑逐一填充的桩(各自标注了归属 issue),subagent_output_router/subagent_summary_generator/task_supervisor/cost_accountant/parent_session_key 让 spawn 子代理与流水线 worker 共享父会话的路由、汇总、监督与成本台账,spawn_depth 是 #607 的 spawn 嵌套深度护栏。读这个 struct 的字段顺序,基本等于读 octos 半年的演进史。

6.3 ToolRegistry:注册、查找与曝光控制

crates/octos-agent/src/tools/registry.rs 3,581 行,ToolRegistry 定义在 crates/octos-agent/src/tools/registry.rs:127。它不是"名字到工具"的简单字典,字段清单(:127-235 附近)暴露了它同时管着七件事:工具表、workspace 根、provider 级策略(过滤 specs() 但不移除工具)、上下文标签过滤器、缓存过的 specs、插件工具标记、MCP 传输句柄所有权。

这些字段不是一次设计出来的,读注释里的 issue 编号能看出沉积顺序。spawn_only 与 spawn_only_messages(:164-166)是 RFC-0 之后的幸存者;live_catalog(:179)是 #1148 加的:tool_search 与 tool_suggest 需要一个随注册表变更实时刷新的目录,而工具本身的执行又拿不到注册表引用,于是注册表在每次变更(register、apply_policy、mark_spawn_only 等,统一经 invalidate_cache,:1086)时把可见工具克隆进这个 Mutex 保护的单元,查询侧持 live_catalog_handle()(:1420)取快照。注释特意说明 Mutex 在这里是合适的:刷新只是克隆一个小 Vec,且只发生在注册表变更时。internal_hidden(:206)与 mcp_services 的所有权语义(#1886,可见性过滤不得决定传输生命周期)分别是 RFC-1 fixup 与 MCP 并入时补上的。

字段之外还有一条容易被忽略的性质:specs() 对输出排序(:746)。tools 是 HashMap,迭代顺序随进程与重建变化,而 provider 会把这个数组原样重放进 LLM 的 prompt 前缀,顺序一变就打穿 provider 侧的 prompt 缓存(工具数组是缓存前缀的首段,如 Anthropic 的 cache_control)。按名字排序后,同一工具集的序列化字节稳定,缓存命中才成立。这是"实现细节变成对外契约"的例子:字段顺序本可随意,缓存成本把它钉死了。

6.3.1 三种构造

#![allow(unused)]
fn main() {
pub fn with_builtins(cwd: impl AsRef<Path>) -> Self {
    Self::with_builtins_and_sandbox(cwd, Box::new(NoSandbox))
}

pub fn with_builtins_and_sandbox(cwd: impl AsRef<Path>, sandbox: Box<dyn Sandbox>) -> Self {
    let permissions = EffectivePermissions::workspace_write();
    Self::with_builtins_and_permissions(cwd, sandbox, permissions)
}
}

(摘自 crates/octos-agent/src/tools/registry.rs:1243-1252)

with_builtins 用 no-op 沙箱启动,with_builtins_and_sandbox 接自定义沙箱但权限仍是工作区可写,只有 with_builtins_and_permissions(:1254)把权限也交出来。#1607 的注释写明:no-op 沙箱下 Agent 内部的工作区校验器直接跑 argv,因为没有可逃逸的东西。空构造 new()(:236)则从零开始,留给测试与特殊组装。

6.3.2 注册与查找

register(:536)接所有权注册,register_arc(:558)接 Arc<dyn Tool>:同一个工具实例要同时出现在多个注册表(父会话与 spawn 子代理)时必须走后者。查找是 get/get_tool,分派边界在 execute_with_context,那里叠着四层防线:provider 策略拒绝、参数体积上限(6.5 节)、catch_unwind 的 panic 隔离(一个工具 panic 只降级为失败的 ToolResult,不再连带杀死 session actor 与其子代理)、全局执行超时(默认 1,800 秒,set_tool_timeout_secs 在 :279)。

6.3.3 曝光控制:LRU 已死,spawn_only 当立

旧稿花了大量篇幅讲 LRU 工具延迟激活与 activate_tools,必须先明确:该机制已在 RFC-0(commit 172fb2be,issue #1289)中连同 activate_tools 一并删除,find_evictable 与 ToolLifecycle 已不存在。specs() 的当前注释写得很直白:每轮发出所有启用的工具,剩余的排除项只有 internal-hidden、provider 策略拒绝与上下文过滤器 miss,不再有任何基于近因的延迟(crates/octos-agent/src/tools/registry.rs:706-711)。

存活下来的机制是 spawn_only(mark_spawn_only 在 :299):被标记的工具在 specs() 里始终可见、LLM 始终可调,但调用在执行循环的分派点被拦截,转成后台任务并立即返回任务句柄(crates/octos-agent/src/agent/execution.rs:775-780 附近)。图 6-2 是这条路径的时序:

sequenceDiagram
    participant LLM
    participant Loop as 执行循环
    participant Reg as ToolRegistry
    participant BG as 后台任务
    LLM->>Loop: tool_call(spawn_only 工具)
    Loop->>Reg: is_spawn_only(name)?
    Reg-->>Loop: true
    Loop->>Loop: provider 策略复查(拦截点)
    Loop->>BG: 起后台 tokio task 执行
    Loop-->>LLM: 立即返回 task_handle
    BG--)Loop: 完成回调(background_result_sender)
    Loop--)LLM: 下一轮注入结果消息

配套细节:每注册表持 spawn_only_invoked 原子布尔记录本运行是否真的用过;background_result_sender 让 session actor 在任务完成时收到通知;#896 修复了文件名在 task_handle 信封里的传播,让 LLM 有稳定文件名可引用。配套细节之外还有两个容易漏看的语义。其一,标记可以被整体清除:clear_spawn_only(crates/octos-agent/src/tools/registry.rs:355)会清空两个集合并让 specs 缓存失效,注释写明它的用途是子代理注册表,在那里 spawn_only 工具应当可以直接调用,因为子代理本身就是后台上下文,再后台化一次没有意义。这个方向性(父会话拦截、子会话放行)与 6.3.4 的注册路径分层对上:曝光控制是每注册表一份的状态,不是工具的固有属性。其二,M10 Phase 4 之后 LLM 拿到的不再是那行自由文本加完整 stdout,而是 spawn_only_handle_message(crates/octos-agent/src/tools/registry.rs:388)构造的小型 task_handle 信封:任务 id、期望产物文件、输出目录、以及一个 read_with: read_task_output 的提示和五种读法(head/tail/grep/line_range/file)。完整输出仍经 M8.7 的 SubAgentOutputRouter 落盘并送达 SPA,这条改动只影响模型看到什么。设计动机是让模型能按需检查中间产物而不撑大上下文,与 read_window 的预限制方向互补。

RFC-0 删 LRU 的取舍放在本章末的侧栏。

mark_internal_hidden(:324)是另一个方向的隐藏:internal-hidden 工具仍可被内部转发器调用,但从 specs() 消失,且没有 LLM 可达的"取消隐藏"路径,即单向。mofa_make 的分发目标(mofa_slides、mofa_cards 等)靠它保证只经分发器可达。

6.3.4 注册路径六处

"58 个条目"并不等于"每次会话都有 58 个工具"。同一批源文件经由六条路径进入注册表,每条路径都会追加或裁剪:

1. 内置基座:构造器(crates/octos-agent/src/tools/registry.rs:1243-1254)注册文件/shell/检索/git 等核心工具。
2. profile 名册:crates/octos-agent/src/assets/profiles/coding.json 声明 allow_list(lean coding roster,9ecc5845 引入),crates/octos-agent/src/profile/mod.rs 负责应用;名单只有 12 项但含 group:runtime/group:search/group:memory 三个组条目,并特意补回 check、update_plan、tool_search。早期 lean 名单把后者也拒了,导致默认 coding 会话跑不了工作区检查、建不了计划。tool_search 是逃生口:模型可动态发现被 allow_list 排除的工具。
3. chat 命令:crates/octos-cli/src/commands/chat.rs:855、:1337 用 with_builtins_and_permissions 起 registry,再补 peer 工具等运行时注入。
4. ACP:crates/octos-cli/src/commands/acp.rs:224、:501 等多处用 with_builtins_and_sandbox。
5. gateway:crates/octos-cli/src/commands/gateway/gateway_runtime.rs:823;注意它调 apply_policy 的时机早于 session actor 复用注册表(crates/octos-cli/src/session_actor.rs:2884 的注释记录了这一顺序约定)。
6. MCP:crates/octos-agent/src/mcp.rs:532 的 register_tools 把远端工具并入,名字与内置冲突即拒绝,防止远端服务器静默替换核心功能;传输句柄在工具之前先交给注册表持有(#1886:可见性过滤不得决定传输生命周期,否则 profile 收窄会顺手杀掉 stdio 子进程)。

图 6-3 注册路径叠加(mermaid):基座 → profile 名册 → 各运行模式的追加 → 策略裁剪 → specs() 输出。

graph TD
    A[with_builtins 基座] --> B[profile allow_list 裁剪]
    B --> C1[crates/octos-cli/src/commands/chat.rs 注入 peer 等]
    B --> C2[crates/octos-cli/src/commands/acp.rs / gateway 追加]
    B --> C3[session_actor: cron/pipeline]
    C1 --> D[apply_policy / provider 策略]
    C2 --> D
    C3 --> D
    D --> E[mcp.register_tools 并入远端]
    E --> F[specs 缓存输出]

6.4 ToolPolicy:deny-wins 与分组

crates/octos-agent/src/tools/policy.rs 741 行。核心结构(crates/octos-agent/src/tools/policy.rs:28-40):

#![allow(unused)]
fn main() {
pub struct ToolPolicy {
    pub allow: Vec<String>,
    pub deny: Vec<String>,
    pub require_tags: Vec<String>,
    pub bash_file_writes: BashFileWrites,
}
}

三维语义加一个 shell 专项。allow 空表示"未显式拒绝即允许";deny 永远压过 allow;require_tags 非空时工具必须声明至少一个匹配标签,无标签的工具直接失败(fail closed)。这是 peer 评审后改过的行为,is_allowed_with_tags(crates/octos-agent/src/tools/policy.rs:131-148)的注释保留了这次安全收紧的记录。判定流程见图 6-4:

flowchart TD
    S[evaluate(name)] --> D{deny 列表命中?}
    D -- 是 --> DR[Deny, reason=policy_deny<br/>或 robot_tier_gate]
    D -- 否 --> A{allow 为空?}
    A -- 是 --> OK[Allow]
    A -- 否 --> M{allow 命中?}
    M -- 是 --> OK
    M -- 否 --> DR2[Deny, 记 metric]
    OK --> T{require_tags 非空?}
    T -- 否 --> PASS[可见]
    T -- 是 --> TG{工具标签有交集?}
    TG -- 是 --> PASS
    TG -- 否 --> FAIL[不可见, fail closed]

evaluate(crates/octos-agent/src/tools/policy.rs:77-128)在拒绝时发 octos_tool_policy_denial_total 指标,拒绝原因区分 robot_tier_gate 与 policy_deny,机器人集成的运维可据此告警。

条目支持三种形态:工具名、group:* 分组、通配。分组表 TOOL_GROUPS(crates/octos-agent/src/tools/policy.rs:180 起,ToolGroupInfo)把工具归成 group:fs、group:runtime、group:web、group:search、group:sessions 等。#1172 的教训写在 group:runtime 里:组内必须包含 Codex 兼容别名 bash,否则禁用 runtime 的 profile 仍可经 bash(cmd=…) 绕过。别名等价是策略正确性的硬约束。

bash_file_writes(#28b)是三档开关(crates/octos-agent/src/tools/policy.rs:55-68):allow(默认)零行为变化;warn 在变更回执尾部追加"改用 edit_file/diff_edit"的提示;deny 用启发式预筛拒绝写形命令,带 # octos:allow-write 行尾注释逃生口。

两个应用入口要分清。apply_policy(crates/octos-agent/src/tools/registry.rs:869-875)用 retain 物理裁剪注册表:被裁的工具真的没了;set_provider_policy(crates/octos-agent/src/tools/registry.rs:947-953)只设一个过滤器,工具留在表里,specs() 与分派边界按 deny-wins-then-allow 语义(含别名等价)动态判断,provider_policy_permits 还供工作区校验器确认"provider 策略是否允许模型调这个工具"。provider 级策略的配置键是 tool_policy_by_provider(crates/octos-cli/src/config.rs:132),按 provider 名映射到各自的 ToolPolicy,provider_policy() 取出的策略会随 spawn 传播到子代理注册表。

6.5 参数与路径安全

三道闸门。

第一道,体积。分派边界拒绝超限参数,上限 1 MB(MAX_ARGS_SIZE = 1_048_576),estimate_json_size 递归估算序列化体积(crates/octos-agent/src/tools/registry.rs:1132-1143,估算函数在 :95-119)。注意这个 1 MB 在源码里的位置是 crates/octos-agent/src/tools/registry.rs 而非 crates/octos-agent/src/tools/args.rs。事实表对此的口径提醒是对的,crates/octos-agent/src/tools/args.rs 里没有这个常量。

值得停在 estimate_json_size(crates/octos-agent/src/tools/registry.rs:95-119)的实现上多看一眼,因为它示范了一类常见取舍。最省事的做法是 serde_json::to_string(args).len(),但那要先把整个参数序列化成 String,分配一块与参数等大的内存,只为得到一个数字,然后扔掉。在分派边界这个每轮工具调用都要过的位置,这个分配纯属浪费。这个函数改为递归走查 serde_json::Value 树按节点计字节:字符串按内容长度加转义开销加两个引号,数组按 2 加元素和加逗号,对象对每个键值加键长加 3(冒号与引号)再加子树,拿到的估算值恰好够做"是否超限"这一个判断。零分配、零拷贝、够用即止,是边界检查类代码该有的形状。

第二道,结构。crates/octos-agent/src/tools/args.rs 479 行解决的是"报错质量"而非"报不报错":serde 失败时只说第一个问题且无视未知字段,模型要么原样重试(死循环,#1765)要么瞎猜修法。parse_tool_args 保持 serde 为解析真源,失败后对照工具自己的 input_schema() 走查原始 JSON,一次性报出全部问题:缺哪个必填参数、哪个参数名拼错(附 did-you-mean)、哪个类型不对(crates/octos-agent/src/tools/args.rs:1-30)。错误经 ToolInputError 送达模型,消息上限 4,096 字节(crates/octos-agent/src/tools/mod.rs 的 TOOL_INPUT_ERROR_MAX_BYTES),既保证模型能自我修复,又保证调用方可控内容不会把错误撑爆输出限额(#2193 R4)。同时这类失败被标记为无副作用、不级联(#1690):一次坏调用不连坐同批好调用。

第三道,边界。路径经 resolve_path(crates/octos-agent/src/tools/mod.rs:972)及带 scope 的变体(:1014、:1052、:1061)归一到会话文件系统契约;文件读写走 read_no_follow/write_no_follow 防 symlink 逃逸(crates/octos-agent/src/tools/edit_file.rs:182 附近可见其用法);网络侧由 crates/octos-agent/src/tools/ssrf.rs 把关(6.1.3 节)。这三者的完整威胁模型在第 7 章。

6.5.1 编码工具契约

前端要的可不是"大概这些工具",而是一份机器可校验的契约。crates/octos-cli/src/api/coding_tool_contract.rs 定义 coding.tool_contract.v1(:12),契约 ID codex-compatible-coding-v1,策略 ID coding-v1。P0 必备工具集 CODING_P0_REQUIRED_TOOL_NAMES(:85)列出 10 项:apply_patch、exec_command、write_stdin、update_plan、request_user_input、spawn_agent、send_input、resume_agent、wait_agent、close_agent。工具状态词汇是 available/aliased/disabled_by_policy/missing/unimplemented/deferred(:21-34),MCP 侧另有 connected/connecting/failed/disabled。有趣的是 deferred 的注释仍提到 LRU 自动淘汰与 activate_tools 恢复(那是契约词汇表为前端兼容保留的历史语义),机制本身已随 RFC-0 删除,不要据此以为 LRU 还在。

6.5.2 三个治理工具的样本

write_grant(#1976)、read_window(#1638)、recall(#2131)代表了工具系统近期的演化方向:不再加"能做更多事"的工具,而加"把已做的事管起来"的工具。write_grant 把 fleet 任务的 fs.write 授权下沉为工具内的内核侧栅栏;read_window 默认关闭、需 OCTOS_READ_WINDOW=1 显式启用,参数来源有据可查。2,000 行上限取自 pi harness 的实测默认,字节上限 48 KiB 是为连页脚一起塞进 50,000 字节的输出上限反推的(crates/octos-agent/src/tools/read_window.rs:1-30);recall 让被压缩替换的输出可凭 id 取回,与第 8 章的内容寻址台账一体。三者共同的前缀是:默认不改变现有行为,启用才收紧。

6.6 工程决策侧栏:为什么删掉 LRU 延迟激活

RFC-0(commit 172fb2be,#1289)删 LRU,不是因为它坏了,而是因为它解决的问题换了答案。LRU 的假设是"工具 schema 是显著的每轮 token 开销,冷工具应藏起来,需要时由模型经 activate_tools 取回"。三个事实瓦解了这个假设:其一,取回路径本身要求模型知道自己缺什么工具,而模型恰恰在被藏起来后不知道。tool_search 逃生口(现随 lean coding roster 默认提供)以更低的复杂度解决了发现问题;其二,延迟激活让工具面的可见性变得依赖会话历史,"这个会话里到底有哪些工具"从静态问题变成动态问题,契约校验、策略审计、前端渲染都要为此买单;其三,真正需要"先声明后执行"的长任务工具,需求其实是"别阻塞前台轮次",这正是 spawn_only 自动后台化的语义,与曝光控制无关。删掉后,specs() 每轮全量输出,缓存机制(cached_specs,注册表变更时失效)把重复序列化的开销吃掉。教训:当两个机制看似解决同一个症状时,先问它们各自的因果链是否还成立。

6.7 小结

本章按能力域纵览了 tools/ 的 58 个条目与 10 个域,再下沉到三个骨架文件:Tool trait 的三层契约与类型化上下文迁移,ToolRegistry 的三种构造、六条注册路径与以 spawn_only 为核心的曝光控制(LRU 已删),ToolPolicy 的 deny-wins、分组、别名等价与 fail-closed 标签门,以及参数体积、结构化报错、路径与网络三道安全闸。第 7 章把沙箱与授权的运行时语义补全,第 16 章的封闭注册表与第 18 章的 goal/peer 工具,都建立在本章的注册与策略语义上。

延伸阅读

• crates/octos-agent/src/tools/mod.rs 顶部模块文档:typed ToolContext 迁移(M8.1)的完整设计说明。
• crates/octos-agent/src/tools/registry.rs 的 ToolRegistry 字段注释:MCP 传输所有权(#1886)与 panic 隔离的设计依据。
• crates/octos-agent/src/tools/policy.rs:is_allowed_with_tags 的 fail-closed 修订注释。
• 第 5 章(agent loop 的工具调用循环)、第 7 章(沙箱与 write_grant)、第 8 章(recall 与压缩台账)。

思考题

1. 同一份 coding.json allow_list 在 apply_policy(物理裁剪)与 set_provider_policy(动态过滤)两种应用方式下,行为差异会在什么场景暴露?提示:考虑 MCP 工具随后并入的情形。
2. require_tags 非空时,无标签工具 fail closed 而不是 pass,这个"不友好"的选择换来了什么安全性质?
3. group:runtime 必须包含 bash 别名。如果新增一个 shell 入口别名而忘了进组,攻击面在哪一层出现:策略层、注册表层,还是执行层?
4. recall 依赖内容寻址台账,read_window 依赖窗口加页脚。两者都在"截断"上做文章,但方向相反(一个取回,一个预先限制)。哪种更适合迁移到 grep 这类输出形态不可预测的工具?为什么?
5. RFC-0 删 LRU 时保留了 spawn_only。假如你要为新工具决定是否标 spawn_only,判据应该看工具的什么性质?

版本演化说明

本章基线为 octos 源码 commit 9c157101(2026-09-03 实测,main 分支)。行号与结构以 assets/ch06-facts.md(commit 552be31)为准,关键行号均经亲测复核。历史注记:LRU 工具延迟激活与 activate_tools 已于 RFC-0(172fb2be,#1289)删除;crates/octos-cli/src/api/coding_tool_contract.rs 的 deferred 状态词汇为前端兼容保留,不代表机制存续。

第 7 章：安全纵深：沙箱 fail-closed、注入防御与能力授予

定位：本章从纵深防御的视角完整展示 octos 的安全体系：进程沙箱的 fail-closed 语义、命令与派发策略、注入检测与输出脱敏，以及 WorkerGrant 能力授予模型。前置依赖：第 6 章（ToolPolicy 与 deny-wins 语义）。适用场景：需要理解或扩展沙箱后端、为 fleet worker 设计能力授予的读者（B/D 类），以及关心 Agent 安全实践的 AI 应用开发者（C 类）。

7.0 本章解决什么问题

Agent 与普通软件的区别在于它执行动作：运行 shell 命令、读写文件、发起网络请求。每一项都是攻击面，而其中 shell 命令最危险，它能触达前两者的全部能力。安全设计因此面临一个具体问题：当操作者要求「命令必须在沙箱里跑」而宿主机上根本没有可用沙箱时，系统应该怎么办？

旧版本的答案是尽力而为：探测不到后端就静默降级为无沙箱直通，命令照跑。这个答案在 2026-08-31 被推翻。eb7c7221（PR #2196，14 个文件，+1621/−158）把决策改成了 fail-closed：显式指定的模式无法兑现时拒绝执行，Auto 模式找不到后端时降级照旧但告警响亮。同一时期的 ffcde205 收紧了 cargo 授权，crates/octos-fleet/src/grant.rs 的 WorkerGrant 则把「worker 能做什么」从配置文件变成了带验证的类型。本章按四层展开这套体系：进程沙箱 → 命令与派发策略 → 注入与脱敏 → 能力授予。

先澄清一个容易搞错的 crate 边界。crates/octos-sandbox/src/main.rs:1 的文档写着「octos-sandbox: platform sandbox helper binary」：它是一个平台助手二进制，Windows 上创建/复用 AppContainer profile 并在其中启动命令，Linux 上应用 Landlock 文件系统规则加 seccomp 拒绝清单后再 exec，macOS 与其他平台上是 no-op 直通。真正的沙箱子系统在 crates/octos-agent/src/sandbox/，下文的引用均使用完整 crates/ 路径。

7.1 进程沙箱：七个 impl 与 fail-closed 决策

7.1.1 规模与全貌

crates/octos-agent/src/sandbox/ 目录六个文件合计 5,347 行：

核心抽象是 pub trait Sandbox（crates/octos-agent/src/sandbox/mod.rs:443），只有一个必须实现的方法 wrap_command(&self, shell_command: &str, cwd: &Path) -> Command：把 shell 命令字符串包装成受限的进程启动。围绕这个 trait 有恰好七个 impl Sandbox for：五个真后端加两个哨兵。

两个哨兵值得注意：NoSandbox 不是「没有沙箱」这个概念的名字，而是一个真的类型（pub struct NoSandbox; 在 crates/octos-agent/src/sandbox/mod.rs:498），is_noop() 返回 true 让调用方可以检查；RefusingSandbox（crates/octos-agent/src/sandbox/mod.rs:909 定义 struct）的 wrap_command 永远不执行请求的命令，而是替换成一个打印拒绝文本到 stderr 并 exit 1 的命令。

7.1.2 SandboxMode 与 MountMode

配置层由两个枚举驱动。MountMode（crates/octos-agent/src/sandbox/mod.rs:408）控制 Docker 后端如何挂载 workspace，serde 小写命名，三个变体：None（:410，不挂载）、ReadOnly（:413，serde 名 ro）、ReadWrite（:417，默认，serde 名 rw）。

SandboxMode（crates/octos-agent/src/sandbox/mod.rs:423）七个变体：

• Auto（:426，默认）：文档注释写明「bwrap on Linux, sandbox-exec on macOS, AppContainer on Windows」
• Bwrap（:428）、Landlock（:430）、Macos（:432）、Docker（:434）
• AppContainer（:437，serde 名 appcontainer）
• None（:439）：不沙箱，直通

Auto 是唯一「找不到后端可以降级」的模式，其余显式模式都走 fail-closed 拒绝。这个不对称是 7.1.3 的主题。

Auto 的探测序与回退逻辑全在 decide_sandbox 的 SandboxMode::Auto 分支（crates/octos-agent/src/sandbox/mod.rs:875-901）：先按 OS 找原生后端（macOS 查 sandbox_exec，Linux 先查 bwrap 再查 Landlock 助手，Windows 查 AppContainer 助手），原生全无才用 docker().then_some(SandboxBackendChoice::Docker) 兜底，再无则按 fail_closed 分流为拒绝或降级。这个顺序有两层考量。原生优先是因为隔离粒度：bwrap/sandbox-exec/AppContainer 直接复用内核机制，无守护进程依赖，失败模式是探测期一次性的；Docker 兜底任何 OS 都可用但依赖守护进程与镜像。探测本身分诚实度两档：HostBackendProbe（crates/octos-agent/src/sandbox/mod.rs:574）的 bwrap() 文档写明「actually runs bwrap, not a PATH scan」，RealHostProbe 里它调 bwrap_works()（crates/octos-agent/src/sandbox/mod.rs:1140）真实跑一次带最小挂载的 bwrap 加 /bin/true，验证内核允许当前用户建 namespace；而 docker() 只是 which_exists("docker") 的 PATH 扫描。Linux 上这个差别尤其重要：unprivileged user namespace 常被发行版关闭，PATH 里有 bwrap 不等于 bwrap 能跑，PATH 式探测会造出一个每次 spawn 都失败的假后端，而「配置了却每次失败」正是 eb7c7221 要消灭的那类静默失败。Linux 原生内部 bwrap 优先于 Landlock，两者粒度相近，但 bwrap 不依赖助手二进制，Landlock 探测要等助手应答 --probe-linux 才为真。

7.1.3 decide_sandbox：纯函数决策与 fail-closed

eb7c7221 之前，create_sandbox 把 cfg! 平台探测与后端构造交织在一起，结果是两个问题：跨平台矩阵没法在开发机上测试（你在 macOS 上测不了 Linux 路径），以及显式模式悄悄降级。重构把决策抽成纯函数 pub fn decide_sandbox(config, os, probe)（crates/octos-agent/src/sandbox/mod.rs:809）：

#![allow(unused)]
fn main() {
pub fn decide_sandbox(
    config: &SandboxConfig,
    os: HostOs,
    probe: &dyn HostBackendProbe,
) -> SandboxDecision {
}

所有宿主机事实（HostOs 是数据枚举，crates/octos-agent/src/sandbox/mod.rs:534；后端可用性走 HostBackendProbe trait）都以参数传入，每个 OS 的完整矩阵可以从任何开发主机测试。返回 SandboxDecision（crates/octos-agent/src/sandbox/mod.rs:744）三值：Confine(SandboxBackendChoice)、Unconfined(UnconfinedReason)、Refuse(SandboxUnavailable)。契约直接写在函数文档里（crates/octos-agent/src/sandbox/mod.rs:800-808）：

• enabled = false 与 mode = "none" 是显式 opt-out，直通且优先于 fail_closed
• 显式后端模式无法兑现（OS 不对或后端缺失）时拒绝，绝不静默降级为无隔离
• Auto 选最佳可用后端（原生优先，Docker 兜底）；全无时降级为直通但要告警；fail_closed 可把降级变成拒绝

UnconfinedReason（crates/octos-agent/src/sandbox/mod.rs:664）区分三种直通原因：Disabled（--danger-full-access 设置的显式 opt-out）、ExplicitNone（mode="none"）、AutoNoBackend（Auto 全无后端，唯一合法的降级）。SandboxUnavailable（crates/octos-agent/src/sandbox/mod.rs:694）是类型化的拒绝理由，携带 requested、reason 和 per-OS 的 remediation 块（remediation_for 在 crates/octos-agent/src/sandbox/mod.rs:754，按 OS 给安装建议）。

拒绝如何到达用户分两个受众，这是 #2196 review 的 MUST-FIX：Display 实现面向模型，写明「Shell/exec commands will keep refusing until then」；操作者修复建议只进日志和 octos doctor，不进模型上下文。stderr_line()（crates/octos-agent/src/sandbox/mod.rs:724）把拒绝文本过滤到只剩 [A-Za-z0-9 ./:_=,-]，确保嵌入 sh -c 'echo ... >&2; exit 1' 时不可能被引号逃逸重新变成命令执行。

fail-closed 的执行还有一条更早的短路路径。exec 形态的工具在 spawn 之前先查 refusal()：crates/octos-agent/src/tools/shell.rs:1069 与 crates/octos-agent/src/tools/coding_tools.rs:501、:625、:2068 都是 if let Some(refusal) = self.sandbox.refusal() 开头，命中就直接把模型侧拒绝文本作为工具结果返回，连子进程都不起。也就是说 RefusingSandbox 的 wrap_command（crates/octos-agent/src/sandbox/mod.rs:914 起的 impl）只是兜底：真正到达它的命令（例如经第三方调用点直接拿 Box<dyn Sandbox> 包装的）才会走 echo 加 exit 1 的替身命令。两层设计的分工是，工具层短路保证模型看到可读的拒绝而非一条 exit 1 的裸输出，trait 层兜底保证任何调用点都不可能把命令无沙箱跑出去。

这个改动的工程动机值得展开。eb7c7221 之前的行为由 crates/octos-agent/src/sandbox/mod.rs:524-528 的重构注释记录在案：create_sandbox 把 cfg! 门控的探测与后端构造交织在一起，导致「两个显式模式静默降级为无隔离」。具体场景是操作者在 CI 或 fleet 配置里写死 sandbox.mode = "bwrap"，宿主机没装 bwrap，命令照跑无沙箱，唯一的线索是启动日志里一行容易淹没的 warn。故障模式有三个叠加属性使它必须修：配置表达了隔离意图而被覆盖（fail-open）；覆盖不可见（用户以为有沙箱）；行为矩阵不可测（cfg! 编译期分派意味着 macOS 开发机上根本没有 Linux 的代码路径，回归只能靠真实 Linux CI 撞出来）。decide_sandbox 把三类事实全部参数化（配置、HostOs、probe），一次重构同时解决三个：显式模式不可兑现返回 Refuse，拒绝对操作者可见且带修复建议，全平台矩阵可以在任何开发机的单元测试里穷举。

create_sandbox（crates/octos-agent/src/sandbox/mod.rs:1005）是决策到后端的投影：Confine 构造后端，Unconfined 返回 NoSandbox 并按原因记日志（AutoNoBackend 走 warn_auto_unconfined_once，crates/octos-agent/src/sandbox/mod.rs:1039，std::sync::Once 保证每进程只告警一次），Refuse 返回 RefusingSandbox。签名保持不可失败，大量构造点不用改；但结果上的每条命令都会带着类型化的 SandboxUnavailable 拒绝。

flowchart TB
    S["decide_sandbox(config, os, probe)<br/>crates/octos-agent/src/sandbox/mod.rs:809"] --> Q1{"enabled = false<br/>或 mode = none?"}
    Q1 -->|是| U["Unconfined(Disabled / ExplicitNone)<br/>显式 opt-out，直通"]
    Q1 -->|否| Q2{"mode 是显式后端?"}
    Q2 -->|是| Q3{"OS 匹配且后端可用?"}
    Q3 -->|是| C["Confine(backend)"]
    Q3 -->|否| R["Refuse(SandboxUnavailable)<br/>RefusingSandbox：拒绝执行<br/>fail-closed"]
    Q2 -->|Auto| Q4{"有可用后端?<br/>原生优先，Docker 兜底"}
    Q4 -->|有| C
    Q4 -->|无| Q5{"fail_closed?"}
    Q5 -->|false| U2["Unconfined(AutoNoBackend)<br/>唯一合法降级，每进程告警一次"]
    Q5 -->|true| R

图 7-1：SandboxMode 解析与 fail-closed 决策流。 显式模式不可兑现必然拒绝；只有 Auto 找不到后端才可能降级为直通。

7.1.4 五个后端各自的实现要点

bwrap（Linux）：wrap_command 的顺序是：清掉 BLOCKED_ENV_VARS → --ro-bind 只读挂 /usr、/lib、/lib64、/bin、/sbin、/etc → --tmpfs /tmp 和 --tmpfs /var/tmp（先于 workspace bind，防止 workspace 在 /tmp 下时被 tmpfs 语义反噬）→ workspace --bind 或 --ro-bind（取决于 workspace_write）→ 可选的 .git 定向 rw bind（repo_git_write）→ --dev、--proc → !allow_network 时 --unshare-net → --unshare-pid、--die-with-parent。repo_git_write 的注释写得很清楚：这是窄授权，只 bind <repo>/.git，绝不 bind 整个 /，因为后者会把 SSH_AUTH_SOCK、docker.sock 这类宿主 AF_UNIX socket 暴露给沙箱内进程（crates/octos-agent/src/sandbox/bwrap.rs:17-26 的字段文档）。

Landlock（Linux）：crates/octos-agent/src/sandbox/landlock.rs:27 的 LinuxContainerSandbox 不自己施加任何限制，全部委托给 octos-sandbox 助手进程，让 Landlock 与 seccomp 的设置发生在 exec shell 之前。找不到助手时不是降级而是拒绝：构造一条 echo 'sandbox error: octos-sandbox helper not found' >&2; exit 1 命令（crates/octos-agent/src/sandbox/landlock.rs:31-39）。

macOS sandbox-exec：最厚的后端（1,767 行），生成 SBPL（sandbox profile 语言）profile。注入防御在 crates/octos-agent/src/sandbox/macos.rs:205-212：cwd 含控制字符或 SBPL 元字符（(、)、\、"）时直接拒绝执行，因为路径已验证不含引号，后续拼接无需转义。macOS 也是唯一能精确表达 #1976 写围栏的后端：每个 glob 变成一条 (allow file-write* (regex ...)) 规则（build_backend 的注释，crates/octos-agent/src/sandbox/mod.rs:1081-1085）。

Docker：跨平台兜底。按 MountMode 挂 workspace（ReadWrite → -v cwd:/workspace，ReadOnly → 加 :ro，None → 不挂），支持 CPU/内存限制。is_blocked_bind_source（crates/octos-agent/src/sandbox/docker.rs:20-30）拒绝把 docker.sock、/etc、/proc、/sys、/dev 作为 bind source，cwd 命中危险源时整个命令拒绝执行。

AppContainer（Windows）：crates/octos-agent/src/sandbox/windows.rs:46 委托 octos-sandbox.exe 创建/复用 AppContainer profile。每个 octos profile 有自己的 AppContainer SID，提供默认拒绝的文件系统访问与可配置的网络隔离。

7.1.5 环境变量清理

所有后端共享 BLOCKED_ENV_VARS（从 octos-core 转发，crates/octos-agent/src/sandbox/mod.rs:33），一个 18 项的清单，按注入面分组：Linux 动态库注入（LD_PRELOAD 等 3 项）、macOS dylib 注入（DYLD_* 5 项）、运行时代码注入（NODE_OPTIONS、PYTHONSTARTUP 等 7 项）、shell 启动注入（BASH_ENV、ENV、ZDOTDIR 3 项）。清单的执行点因后端而异：bwrap、Landlock、macOS（crates/octos-agent/src/sandbox/macos.rs:478）与 Windows（crates/octos-agent/src/sandbox/windows.rs:90、:139）都会逐项 env_remove；Docker 后端反而一处不清理，容器隔离本身承担了环境隔离。

7.1.6 cargo 授权：从尽力写到 lock-only

ffcde205（4 个文件，+140/−82）解决的是编码 agent 的一个实际矛盾：沙箱把写权限收得越紧，cargo build 越容易死在编译之前。修复后的策略是默认 lock-only：可写集仅 ~/.cargo/.package-cache（锁文件所需），registry index/cache/src、git checkout、rustup 安装全部只读；只有配置 allow_network 时才补上下载所需的写权限与网络。配套的 allow_toolchains 字段（crates/octos-agent/src/sandbox/mod.rs:149）默认 true，授予工具链运转必需的少量写路径，但 ~/.cargo/bin（PATH 上的可写 shim 等于持久化后门）与 ~/.rustup/toolchains（可写编译器二进制）明确不授。deny-wins 在这里同样生效：只读 workspace 或 #1976 写围栏会整体压制这些授予。

工程决策侧栏：为什么放弃「尽力而为的沙箱」

旧语义下，操作者写 sandbox.mode = "bwrap"，宿主机上没有 bwrap，结果是命令无沙箱照跑。从安全角度这是 fail-open：配置表达了隔离意图，系统用「能跑就行」覆盖了它。问题在于这条路径不可见，用户以为有沙箱。eb7c7221 的取舍是：显式模式不可兑现就拒绝执行，把矛盾暴露给操作者（附 per-OS 修复建议与 octos doctor 入口）；Auto 保持降级（「最佳可用」本就是它的契约）但每进程告警一次，并提供 sandbox.fail_closed 开关把降级也变成拒绝。代价是可用性：装错环境的用户会看到命令全部拒绝。团队接受这个代价，理由是拒绝文本本身可操作，而静默无沙箱不可修复。

7.2 命令与派发策略：每条路径都有门

沙箱管「命令在什么环境里跑」，策略层管「命令/工具能不能跑」。

crates/octos-agent/src/policy.rs（746 行）：命令审批策略。Decision（crates/octos-agent/src/policy.rs:16）三值 Allow / Deny / Ask，ApprovalPolicy（:28）决定 Ask 在无人值守时是弹审批还是直接失败（Never），FilesystemScope（:46）的 Workspace / Host 二值在 7.4 节的 grant 模型里会再次出现。ShellTool 的 SafePolicy（危险命令拒绝、whitespace 归一化、词边界检测）在第 6 章已展开，这里不重复；本章强调的是它明确自称「不是安全边界」，真正的边界是本节的沙箱与下一节的脱敏。

crates/octos-agent/src/dispatch_policy.rs（566 行）：MCP-agent 派发前策略门。模块文档（crates/octos-agent/src/dispatch_policy.rs:1-10）记录了它的来历：#714 之前 SpawnTool 的 agent_mcp 分支直接派发，完全绕过策略，哪怕 octos serve 在 swarm 侧装了门。把门提到本 crate 让两个调用点（SpawnTool::agent_mcp 分支与 octos_swarm::Swarm 派发器）执行同一形状的检查：工具策略、审批、sandbox-required、env 允许/拒绝清单。每个失败产生带稳定标签的 GateDenial（crates/octos-agent/src/dispatch_policy.rs:253，last_dispatch_outcome 字段），其中 approval_unavailable（需要审批但没有接审批器）与 sandbox_required（策略要求沙箱后端但后端不自报沙箱）都 fail-closed，不落空到派发。

crates/octos-agent/src/permissions.rs（167 行）：机器人工具的监督安全分级。SafetyTier（crates/octos-agent/src/permissions.rs:19）四级从低到高 Observe < SafeMotion < FullActuation < EmergencyOverride，通过 ToolPolicy 的 group:robot:<tier> 分组执行而非独立 trait 方法。物理世界的风险分级与本章的数字沙箱共用同一套 deny-wins 机制，此处一段带过。

为什么这扇门长成这样，设计判据有三条，全部写在 crates/octos-agent/src/dispatch_policy.rs 自身的文档里。判据一，门必须共享而不是复制：模块文档（:1-10）记录了 #714 之前的旁路，SpawnTool 的 agent_mcp 分支直接派发，octos serve 在 swarm 侧装了门也拦不住；把门提进 octos-agent crate，两个调用点对同一组共享类型（ToolPolicy、ToolApprovalRequester、McpAgentBackend）执行同一形状检查，将来出现第三个派发点时没有「自己再写一套检查」这个选项。判据二，默认 no-op、生产显式装配：DispatchPolicy（:121）每个门独立可选，全默认值时 is_noop()（:175）为真、派发行为与旧版逐字节一致，这是为了不回归既有调用方；生产构造器 from_agent_gates（:223）则刻意只继承 #701 审计点名的两道门（工作区级工具名策略与 BLOCKED_ENV_VARS 注入环境拒绝清单），审批桥与 sandbox-required 故意不镜像，理由写在构造器 rustdoc（:197 起）：原生审批桥 TOOL_APPROVAL_CTX 是 per-turn task-local，服务器启动时没有可克隆的全局请求器；尚无 MCP 后端自报沙箱，require_sandboxed 只是为前向兼容保留（:150-152），今日置真等于每次派发都 fail-closed。判据三，门序固定且失败可观测：enforce_dispatch_gates 的文档（:285 起）规定检查顺序为 sandbox-required（纯配置，最便宜）→ 工具策略 → env 拒绝清单 → env 允许清单 → 审批（唯一可能阻塞等人的，放最后），拒绝清单先于允许清单是防宽松允许清单放过已知坏键（:144-146）；每道失败产生带稳定标签的 GateDenial（:253，五个标签枚举在字段文档里），调用方把它折进自己的 outcome 形状，本 crate 对外的 API 面因此只是门语义，不是又一套失败类型。

7.3 注入检测与输出脱敏

7.3.1 prompt_guard：明文注入的检测层

crates/octos-agent/src/prompt_guard.rs（772 行）扫描工具输出与用户消息中的注入模式。ThreatKind（crates/octos-agent/src/prompt_guard.rs:29）五类：SystemOverride（覆盖系统提示）、RoleConfusion（「System: you are now...」式角色混淆）、ToolCallInjection（注入工具调用 JSON/XML）、SecretExtraction（套取系统提示或密钥）、InstructionInjection（「you must / always respond with」式通用指令注入）。入口 pub fn scan(text) 在 :195。

这个模块的文档（crates/octos-agent/src/prompt_guard.rs:5-19）第一句就自我定位：「Not a security boundary.」它用正则匹配朴素明文注入，可被 base64 编码、URL 编码、HTML 实体、Unicode 同形字、零宽字符、RTL 覆盖字符绕过，这些都记录在测试套件里作为已知局限。真正的缓解是架构性的：沙箱隔离保证不管 prompt 状态如何工具层损害有限，工具策略限制可调用的工具集，human-in-the-loop（before_tool_call hook exit 1）拦截高影响动作待人工批准。prompt_guard 提供的是日志与尽力脱敏这层额外防线，不是前三者的替代品。

7.3.2 sanitize：工具输出进上下文前的清洗

crates/octos-agent/src/sanitize.rs（245 行）的 sanitize_tool_output（:90）在工具结果回喂 LLM 前剥掉三类内容。噪声类：base64 data URI（data:...;base64,<64+ 字符>，:13）与 64 位以上连续 hex（SHA-256、原始密钥，:16），目的是省上下文。凭据类七个正则：OpenAI（sk- 前缀，:24）、Anthropic（sk-ant-）、AWS（AKIA + 16 位大写）、GitHub（ghp_/gho_/ghs_/ghr_/github_pat_）、GitLab（glpat-）、Bearer token、以及通用赋值模式（password|secret|api_key|... = "..."）。redact_credential（:55）保留前 4 个可见字符加 [credential-redacted] 标记，兼顾可辨识与不泄漏。scrub_credentials（:62）的注释强调顺序：Anthropic 先于 OpenAI 处理，避免 sk-ant-... 被 sk- 规则截断匹配。

7.3.3 SSRF：网络工具的入口检查

crates/octos-agent/src/tools/ssrf.rs（620 行）被 web_fetch 与 browser 两个工具共享。check_ssrf_with_addrs（:24）的流程：解析 URL → is_private_host（:228）拦 localhost 与字面私有 IP → 域名走 DNS 解析，答案集经 validate_answer_set（:69）做 DNS pinning（防 rebinding：校验时解析到的地址绑定到实际抓取，TOCTOU 不复存在）。DNS 失败 fail-closed 当作阻断处理，注释写明原因：攻击者可以让校验时 DNS 失败、抓取时成功。

is_private_ip（:258）的范围清单超出 std 谓词：IPv4 除 is_private/is_link_local/is_loopback/is_unspecified 外，is_special_purpose_v4（:244）显式匹配 std 夜行版才有的段：CGNAT 100.64.0.0/10（运营商级 NAT）、192.0.0.0/24（IETF 协议分配）、198.18.0.0/15（基准测试）、224.0.0.0/4（组播）与 240.0.0.0/4（保留）。IPv6 覆盖 loopback、::、组播、ULA fc00::/7、链路本地 fe80::/10、废弃的站点本地 fec0::/10，以及两条映射规则：IPv4-mapped ::ffff:x.x.x.x 递归回 IPv4 检查，IPv4-compatible ::x.x.x.x 同样处理。漏掉映射规则是经典绕过，测试里有专门用例（:580、:590）。

prompt_guard 与 sanitize 的分工边界值得单独说清：两个模块都在「输出进上下文之前」动手，但管的对象不同。crates/octos-agent/src/prompt_guard.rs 管指令，即文本里是否有人试图操纵模型的下一步行为；crates/octos-agent/src/sanitize.rs 管物质，即文本里是否携带不该回喂的字节（凭据、base64 data URI、长 hex）。分工的接点在 sanitize_tool_output（crates/octos-agent/src/sanitize.rs:90-94）：流水线依次替换 data URI、长 hex、七类凭据，最后一步调用 prompt_guard::sanitize_injection，注入 defang 因此是清洗流水线的末段而不是一条独立通道；执行侧的调用点是 crates/octos-agent/src/agent/execution.rs:2414，每条工具结果在截断之后、回喂模型之前统一过这一道，单点漏斗意味着绕过清洗需要绕过整个执行层，而不是挑某个不设防的工具。检测粒度同样分层：scan（crates/octos-agent/src/prompt_guard.rs:195）产出带 Severity 三档（:56，Low/Medium/High）的 Threat 列表，Low 只记日志，Medium 起才动手脱敏（sanitize_injection 内部按 severity >= Medium 过滤，:262），替换按 span 逆序进行以保住字节偏移（:270 起）。这套阈值承认的是正则检测的误报成本：宁可只对中高置信度动手，把「检测不到的情形」明确留给架构性控制（沙箱、工具策略、human-in-the-loop），与模块文档第一句「Not a security boundary」的自我定位一致。两个模块都是纵深里的额外一层，不是边界本身。

7.4 WorkerGrant：能力授予的类型化

前三层防御都在「限制」侧。fleet 架构（第 16 章讲装配）还需要反向的能力：master 派任务给 worker 时，如何精确表达「这个 worker 可以用网络、只能写这三个路径」？答案是 crates/octos-fleet/src/grant.rs（714 行）的 WorkerGrant，一个带验证的类型，而不是散落的配置项。

7.4.1 三个粒度轴

NetworkGrant（crates/octos-fleet/src/grant.rs:76）三值：None（默认，零网络）、Hosts(Vec<String>)（按主机允许表）、Full（原始出网全开）。关键语义在方法注释里：allows_raw_egress 仅对 Full 为真，Hosts 刻意保持原始出网关闭，它的许可完全通过被授予的 web 工具按主机允许表实现，shell 永远 curl 不到允许表之外。文档同时坦承 v1 局限：原始网络是全有或全无，按主机过滤原始流量需要内核级 egress proxy，Hosts 只覆盖 web 工具的 HTTP(S)，这是记录在案的未解问题。

FsGrant（crates/octos-fleet/src/grant.rs:127）刻意粗粒度：Workspace（默认，仅 worker 自己的尝试目录可读写）或 Host（全盘读写，须操作者显式授予）。v1 不做按路径的文件系统允许表，所以诚实的授予也是二值的。

WorkerGrant（crates/octos-fleet/src/grant.rs:151）五个字段把这些轴组装成一个可序列化、可验证的整体：

#![allow(unused)]
fn main() {
pub struct WorkerGrant {
    #[serde(default)]
    pub network: NetworkGrant,        // :154，默认 None
    #[serde(default = "base_tools_vec")]
    pub tools: Vec<String>,           // :157，默认 BASE_TOOLS 七项
    #[serde(default)]
    pub fs: FsGrant,                  // :160，默认 Workspace
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub write_paths: Option<Vec<String>>, // :179，#1976 写围栏
    #[serde(default, skip_serializing_if = "core::ops::Not::not")]
    pub create_only: bool,            // :189，仅创建不覆盖
}
}

每个字段的 #[serde(default)] 有一层设计：grant 出现之前持久化的旧任务（或什么都没指定的 master）加载为 WorkerGrant::minimal()，最小权限是默认值，旧记录无需 schema 升级就可读。skip_serializing_if 让无围栏的 grant 序列化出与 pre-#1976 逐字节相同的形状，旧读者读新记录看不到新键。

五个字段不是随手凑的，每一条对应一类必须显式回答的授权问题，缺一个就留一个默认放行的洞。没有 network，web 工具与 shell 的出网能力无法区分，「不给网络」无处表达，WEB_TOOLS 只能授予或整体禁用；没有 tools，注册表形状就只能全有或全无，sorted_tools() 这个审计键（「操作者授予了什么，一个不多」）没有存在基础；没有 fs，workspace 与 host 的文件系统边界退回隐式的 cwd 约定，FsGrant::Host 这种操作者的显式信任决定无处落笔；没有 write_paths，#1976 之前「worker 只能写这几个文件」只能靠 workspace_write 二值粗调，要么全 workspace 可写要么全只读；没有 create_only，「创建可以、覆盖不行」这个防篡改语义（重放安全的关注点）在类型上不可表达。反过来，字段也只有这五个：v1 刻意不做按主机的原始网络过滤（需要内核级 egress proxy）、不做文件系统的任意 ACL（工具层没有对应机制，grant 诚实反映它能执行的范围）。字段集合等于「两层执行机制都能兑现的授权问题」的精确并集，多一个是撒谎，少一个是漏洞。

7.4.2 #1976 写围栏：三层语义

write_paths 是 issue 1976 引入的按路径写围栏，三种取值各有语义：

• None（默认）：无围栏，二值 fs 独自管辖写权限，行为与 pre-#1976 worker 逐字节一致
• Some(vec![])：一致的只读围栏，workspace 内什么都不能写
• Some(列表)：列表内可写，workspace 其余部分只读

v1 模式语法刻意收窄：workspace 相对路径、/ 分隔、段内 *（任意字符）与 ?（单字符）通配，没有 **、[...]、{...}。原因写在字段文档里：这个语法是工具层匹配器（globset，literal_separator）与沙箱翻译（SBPL regex）能完全相同表达的交集，两层对「授予了什么」永远不可能产生分歧。validate_write_path_pattern（crates/octos-fleet/src/grant.rs:307）逐条拒绝绝对路径、..、控制字节、SBPL 元字符、:（Docker mount 分隔符/Windows 盘符）与两类通配语法。

create_only: true 表示允许表内的路径只能创建不能覆盖/编辑/删除（文件工具层的 O_CREAT|O_EXCL 语义；edit_file 无论是否在表内都直接拒绝）。沙箱层只能执行路径围栏，没有 OS 后端能区分创建与覆盖，所以 create_only 的不覆盖一半由工具层执行，这是文档写明的降级。

围栏下各后端的 shell 侧表达不一，deny-wins 保证没有后端放宽围栏（crates/octos-agent/src/sandbox/mod.rs:955-1000 三个函数）：macOS 精确表达（per-glob SBPL regex）；bwrap/Landlock/AppContainer 无法表达按 glob 的 shell 写，workspace 对 shell 整体降为只读，授予路径仅通过受围栏的文件工具保持可写（fence_degraded_workspace_write，:955，构造时告警一次）；Docker 同理挂 :ro（fence_degraded_docker，:970）；解析结果是无沙箱时告警 shell 围栏完全未执行（warn_fence_unenforced）。

flowchart LR
    subgraph G["WorkerGrant（crates/octos-fleet/src/grant.rs:151）"]
        N["network: NetworkGrant<br/>None / Hosts / Full"]
        T["tools: Vec&lt;String&gt;<br/>默认 BASE_TOOLS 七项"]
        F["fs: FsGrant<br/>Workspace / Host"]
        W["write_paths: Option&lt;Vec&lt;String&gt;&gt;<br/>#1976 写围栏"]
        CO["create_only: bool<br/>仅创建不覆盖"]
    end
    V["validate()（crates/octos-fleet/src/grant.rs:247）"] --> G
    G --> SB["沙箱投影（crates/octos-agent/src/sandbox/mod.rs:955-1000）<br/>macOS 精确 / 其余降级只读"]
    G --> FT["工具层执行<br/>globset 围栏 + O_CREAT|O_EXCL"]

图 7-2：WorkerGrant 结构与两个执行层。

7.4.3 validate：把不一致挡在解析时

WorkerGrant::validate（crates/octos-fleet/src/grant.rs:247）拒绝五类不一致，每类对应 GrantError（crates/octos-fleet/src/grant.rs:359）一个变体：

• UnknownTool：授予的工具有不在 GRANTABLE_TOOLS 目录里的（操作者不能授予宿主构建不出的工具）
• WebToolWithoutNetwork：NetworkGrant::None 下授予 web_fetch/web_search（无网络的网络工具）
• EmptyHostAllowlist：Hosts(vec![]) 空允许表。注释点名这是 fail-open 陷阱：空表绝不能读作「无限制」，操作者没列主机就是 None
• #1976 四连：WritePathsWithHostFs（围栏配 fs: Host 不一致，Host 让 shell 够得着围栏禁止的一切，deny-wins 直接拒）、CreateOnlyWithoutWritePaths（无表可应用）、EmptyWritePathsWithCreateOnly（空表加 create_only 等于授予创建无）、InvalidWritePath { pattern, reason }（语法外模式）

validate 在两个时点调用：master 的 goal_plan 解析时，以及防御性地在 registry 构建时。与第 6 章 crates/octos-agent/src/tools/write_grant.rs 的关系：第 6 章讲了单工具的参数级写授权，本章的 WorkerGrant 是 worker 级的整体授予模型；fleet 如何把这个 grant 装配成封闭工具注册表与沙箱配置，详见第 16 章。

工程决策侧栏：为什么 grant 是类型而不是配置约定

「worker 能做什么」如果只是若干独立配置项（一个网络布尔、一个工具列表、一个路径列表），不一致组合要到运行时才暴露，甚至永远不暴露（空允许表被读成无限制就是实例）。WorkerGrant 把五轴收进一个 struct，validate 把跨字段不一致在解析时类型化拒绝，GrantError 七个变体每个都能直接转成给操作者的错误消息。minimal() 作为 serde 默认值把最小权限变成无需声明的基线，旧记录自动落入。代价是新增能力要同时扩 GRANTABLE_TOOLS 目录、validate 规则与错误变体，三处必须同步；换来的是「授予了什么」在序列化形状、注册表审计键（sorted_tools）与错误消息三处始终一致。

7.5 本章回顾

本章沿四层展示了 octos 的安全纵深。进程沙箱层：crates/octos-agent/src/sandbox/ 六文件 5,347 行、七个 impl Sandbox for（五后端加 NoSandbox/RefusingSandbox 两哨兵），decide_sandbox 纯函数（crates/octos-agent/src/sandbox/mod.rs:809）执行 fail-closed 契约，显式模式不可兑现即拒绝，Auto 降级告警一次且可用 fail_closed 升级为拒绝。策略层：crates/octos-agent/src/policy.rs 的命令审批、crates/octos-agent/src/dispatch_policy.rs 补上 MCP 派发旁路（#714）、crates/octos-agent/src/permissions.rs 的机器人安全分级。注入与脱敏层：crates/octos-agent/src/prompt_guard.rs 自认非安全边界的明文检测、crates/octos-agent/src/sanitize.rs 的七凭据正则与 DNS pinning 的 SSRF 检查。能力层：WorkerGrant 五字段（network/tools/fs/write_paths/create_only）配 validate 的五类不一致拒绝，#1976 写围栏经沙箱投影与工具层双层执行。

贯穿全章的一条线是 deny-wins 与 fail-closed 在每一层的重复出现：工具策略 deny 优先于 allow（第 6 章），沙箱显式模式不可兑现拒绝而非降级，空允许表拒绝而非读作无限制，围栏配 Host fs 拒绝而非取宽者。同一原则在四个抽象层级上的相同形状，比任何单点的强度更能说明这套体系的设计一致性。

延伸阅读

• Landlock 文档与 seccomp BPF 手册（man 2 seccomp）：crates/octos-agent/src/sandbox/landlock.rs 委托助手所施加的两类内核机制
• Apple Sandbox Guide（SBPL 参考）：crates/octos-agent/src/sandbox/macos.rs 生成 profile 的语言
• bubblewrap 项目文档：crates/octos-agent/src/sandbox/bwrap.rs 使用的 mount namespace 与 --die-with-parent 语义
• OWASP SSRF Prevention Cheat Sheet：crates/octos-agent/src/tools/ssrf.rs 阻断范围清单的对照参考
• issue #1976 与 PR #2196（eb7c7221）、ffcde205 的 commit message：本章三个主线的原始讨论

思考题

1. decide_sandbox 为什么把 HostOs 与后端探测做成参数而不是在函数内读环境？如果 probe 是真实全局的，哪个质量属性先坏掉？
2. RefusingSandbox 的 wrap_command 仍然构造一条真的 shell 命令（echo 拒绝文本并 exit 1），而不是返回错误。保持 Sandbox trait 签名不可失败带来了什么好处？exec 形态工具经 refusal() 短路又解决了这个设计的哪个剩余问题？
3. NetworkGrant::Hosts 刻意不让 shell 获得原始出网，许可全部经 web 工具的允许表实现。如果 v2 要支持「git 只能 clone 允许表内的主机」，需要什么基础设施？
4. validate 把「Hosts 空允许表」列为错误而不是等价于 None。从操作者心理模型出发论证或反驳这个选择。
5. bwrap 后端在 #1976 围栏下把 workspace 对 shell 降为只读（授予路径仅文件工具可写）。一个只能用 shell 工具完成任务的 worker 在围栏下会遇到什么？这个降级是设计缺陷还是合理取舍？

版本演化说明

本章分析基线为 octos main @ 9c157101（2026-09-02 提交）。主线变化：eb7c7221（2026-08-31，PR #2196，14 个文件）引入显式模式 fail-closed 与 Auto 降级告警，并把沙箱决策重构为纯函数 decide_sandbox；ffcde205（2026-08-26，4 个文件）将 cargo 授权默认收紧为 lock-only、下载经 allow_network 门控；issue #1976 引入 WorkerGrant 按路径写围栏与 create_only。行号与文件行数均以此基准实测，事实来源为 assets/ch07-facts.md 事实表。

第 8 章：上下文管理：让 Agent 在有限窗口中高效工作

定位：本章展示 octos 如何通过上下文压缩（compaction）、recall 重物化、分层压缩面（tiered compaction）、保真度分级（fidelity）、提示层构建（prompt layer）、steering 与系统提示防篡改（prompt guard），在有限的 LLM 上下文窗口中高效工作。前置依赖：第 5 章（CompactAndRetry 触发点）。适用场景：需要理解或调优 Agent 上下文策略的开发者。

LLM 的上下文窗口是稀缺资源。一个 200K token 的窗口，在十几次工具迭代后就可能耗尽：每次调用的参数和结果都在累积，一次 read_file 的输出可能就占数千 token。窗口接近满时只有两条路，停止任务，或压缩历史。octos 选择压缩，但当前主分支的答案已经从单一摘要函数演进成一套体系：先分层削减（本地占位符、服务端清理、完整摘要三档），再折叠旧消息，压缩掉的输出还能通过 recall 工具凭 id 重新取回。本章沿这条主线展开，并覆盖支撑它的提示层构建、steering 注入与工具输出防篡改。

8.1 Context Compaction：80% 阈值加 recall 的双机制

8.1.1 触发条件与安全边际

legacy 触发路径在 trim_to_context_window()（[crates/octos-agent/src/agent/compaction.rs:11-60]）。预算公式（[crates/octos-agent/src/agent/compaction.rs:25]）：

#![allow(unused)]
fn main() {
let window = self.llm.context_window();
let budget = (window as f64 * 0.8 / crate::compaction::SAFETY_MARGIN) as u32;
}

SAFETY_MARGIN = 1.2（[crates/octos-agent/src/compaction.rs:45]）。实际预算是 window * 0.8 / 1.2 ≈ window * 67%：一边预留 20% 给新一轮对话，一边为 token 估算误差再留缓冲。128K 窗口的模型，触发点约在 85K tokens。总量低于预算就直接返回，不动历史。

8.1.2 保留边界：最近六条与工具组完整性

find_recent_boundary()（[crates/octos-agent/src/compaction.rs:68-89]）从最后一条消息向前扫描，决定哪些消息原样保留：

#![allow(unused)]
fn main() {
for i in (1..messages.len()).rev() {
    let msg_tokens = estimate_message_tokens(&messages[i]);
    count += 1;
    if count >= MIN_RECENT_MESSAGES
        && system_tokens + recent_tokens + msg_tokens > budget / 2
    {
        break;
    }
    recent_tokens += msg_tokens;
    split = i;
}
while split > 1 && messages[split].role == MessageRole::Tool {
    split -= 1;
}
}

MIN_RECENT_MESSAGES = 6（[crates/octos-agent/src/compaction.rs:48]）。最近消息无条件保留满六条，同时不允许超过预算的一半，给旧消息的摘要留出空间。末尾的 while 回退保证切割点不落在 Tool 消息上：Assistant 与 Tool 的配对组一旦拆开，孤立的 Tool 消息会让 provider 校验失败或让模型困惑。

8.1.3 提取式摘要：参数剥离与首行截取

旧消息交给 compact_messages()（[crates/octos-agent/src/compaction.rs:99-153]），逐条经 summarize_message()（[crates/octos-agent/src/compaction.rs:155-201]）压成一行。压缩比最高的是工具参数剥离：一次 write_file 调用的参数可能包含整份文件内容，上千 token，压缩后只剩 - Called write_file，约五个 token，压缩比接近 200:1。这个设计还有一个安全副作用：工具参数是不受信输入，剥掉它意味着压缩摘要里不会残留恶意 payload 的原文。

各消息角色的处理规则：

工具结果的 ok/error 判定很朴素：内容以 Error: 开头即视为失败（[crates/octos-agent/src/compaction.rs:180-188]）。find_tool_name()（[crates/octos-agent/src/compaction.rs:219-234]）从上下文反查 tool_call_id 对应的工具名，查不到时降级为 unknown_tool。首行截取的理由是信息密度：LLM 的回复通常以结论开头，首行携带最高的语义密度。first_line()（[crates/octos-agent/src/compaction.rs:203-216]）按 UTF-8 字符边界截断，不会把一个汉字切成两半。摘要目标占预算的 40%（BASE_CHUNK_RATIO，[crates/octos-agent/src/compaction.rs:51]），超出后停止逐条展开，剩余消息记为 ... (N earlier messages omitted)。

一个容易被漏掉的细节：compact_messages 会先把最新的 plan 快照从预算里扣除（#2132），保证保留块不会把摘要顶出预算上界（[crates/octos-agent/src/compaction.rs:104-114]）。注释里写得很清楚：这个扣除发生在生产者内部，AppUI、session actor、legacy agent channel、summarizer tiers 所有压缩路径自动继承，不需要逐点接线。

如果最近消息本身已超预算，代码退回 fallback_truncate() 尾部截断（[crates/octos-agent/src/agent/compaction.rs:319-358]）：从尾部向前保留能放下的消息，至少留两条非系统消息，同样避免拆开工具组。压缩的语义是「能摘要就摘要，放不下才截断」，摘要优先但不是无条件。

8.1.4 recall：压缩之后重新物化

以上机制有一个固有代价：被压缩的输出不可逆。#2131 观测到的病态是同一个源文件被反复读取 66 次，每次读取的结果进窗口、被截断、被压缩、再被读取。e312e4c1（2026-08-27 合入）补上了恢复侧：recall 工具。

被逐出的工具结果在窗口里留下一个带类型的 ToolResultPlaceholder（[crates/octos-agent/src/compaction.rs:346-361]），其中携带 tool_call_id。RecallTool（[crates/octos-agent/src/tools/recall.rs:27-35]）凭这个 id 从 ledger 取回原始字节，不需要重新执行工具。抽象层是 ToolOutputLedger trait（[crates/octos-agent/src/tools/recall.rs:19-24]），octos-agent 只依赖这个接口，具体实现由 session 侧注入，避免了跨 crate 依赖。大输出按页返回（render_page()，[crates/octos-agent/src/tools/recall.rs:51-99]），页脚标明「下一页调 recall(tool_call_id=…, page=N)」，不静默丢中间段。

ledger 侧的关键实现在 octos-cli 的 ContextManager：recall_index（[crates/octos-cli/src/api/context_manager.rs:391-398]）在记录时写入 tool_call_id → (artifact_ref, model_visible_content)，并且不被 compaction 清理。这正是 825d6a52 修的问题：早期 recall 从 items 解析，而 compact_context 会把 items 清到最近约 16 条，导致真正被逐出的输出（恰恰是 recall 存在的理由）反而取不回，磁盘上的 artifact 字节成了孤儿。修复后的测试 recall_survives_compaction_that_prunes_the_transcript（[crates/octos-cli/src/api/context_manager.rs:2408-2440]）先构造 20KB 输出（超过 inline 阈值，spill 到 ledger）、压掉其 transcript 信封、再断言完整字节可取回。读取入口是 tool_output_by_call_id()（[crates/octos-cli/src/api/context_manager.rs:1192-1206]）：spill 到内容寻址 ledger 的输出返回完整原始字节；未 spill 的返回记录时的模型可见内容（截断标记保留，不误导模型）；未知 id 返回 None。

recall 句柄选 tool_call_id 而不是内容 sha256，是一个刻意的架构决定（e312e4c1 提交说明）：sha256 只存在于 octos-cli 的 ledger 信封，把它加到 octos_core::Message 需要改动约 560 处构造点；而 tool_call_id 已经出现在每个占位符上，零 schema 变更。

8.1.5 recall 与记忆子系统的边界

octos 里有两个名字相近的工具：recall（本章）和 recall_memory（第 4 章）。它们解决不同时间尺度的问题，共用的只有分页器实现。recall 作用于当前 session 的 context ledger：工具输出 spill 到内容寻址存储后，凭 id 取回原始字节，作用域随 session 结束。recall_memory 作用于跨 session 的 memory store：向量检索历史观察与事实，服务于「上次会话学到什么」。

两者的衔接点在压缩摘要的持久化。loop 侧每完成一次压缩，会把摘要作为可检索的 episode 存档（save_conversation_episode，#1587 写侧，见 [crates/octos-agent/src/agent/loop_runner.rs:1215-1245] 的两处调用：入口压缩与轮内压缩各存一次）。判断逻辑写在注释里：一段对话大到需要压缩，就值得被未来的会话回想起。这样 session 内的 recall 取回字节，跨 session 的 recall_memory 取回语义摘要，两层合起来覆盖「压缩之后信息去了哪里」的完整答案：字节在 ledger，语义在 episode，结构化任务状态在 SessionSummary。

recall 把「压缩不可逆」改写成「压缩后有损但可按需恢复」，这是 8.1 双机制的第二条腿。

8.1.6 预算感知读取：预防先于恢复

#2131 的另一半是预防：read_file 在未指定范围读取一个超过工具输出预算的文件时，不返回注定被截断再被逐出的正文，而是返回范围提示（[crates/octos-agent/src/tools/read_file.rs:484-506]）：文件多大、预算多少、建议传 start_line/end_line 或先 grep。已经显式指定范围的读取不受影响。这一步把「接受再逐出」的死循环在源头掐断。

flowchart TD
    Start["每次迭代"] --> Count["估算总 token"]
    Count --> Check{"总量 > window×0.67?"}
    Check -->|否| Skip["不压缩"]
    Check -->|是| T1["Tier 1 本地清理<br/>stale/oversized 工具结果"]
    T1 --> Need{"仍超阈值?"}
    Need -->|否| Keep["占位符替代,继续"]
    Need -->|是| Sum["摘要折叠旧消息"]
    Sum --> Later["后续需要细节时"]
    Later --> Recall["recall(tool_call_id)<br/>从 ledger 取回原始字节"]
    Keep --> Later

图 8-1：压缩与 recall 回路。 压缩不再是一条单行道。

8.2 分层压缩面：三个档位各管一段

crates/octos-agent/src/compaction_tiered.rs（1,271 行，M8.5 #540）把压缩面拆成三档，动机写在模块头：便宜的 tier-1 就能消化大部分压力，昂贵的完整摘要尽量少触发（[crates/octos-agent/src/compaction_tiered.rs:1-34]）。

Tier 1 的策略结构是 MicroCompactionPolicy（[crates/octos-agent/src/compaction_tiered.rs:72-106]）：超过 5 个用户轮（DEFAULT_TIER1_MAX_AGE_TURNS）或单结果超过 8KB（DEFAULT_TIER1_MAX_SIZE_BYTES_PER_RESULT）即替换为占位符；同时带 #2131 的两个补充：最近触碰的 5 个文件的工作集钉住（pin_recent_files，[crates/octos-agent/src/compaction_tiered.rs:78-88]），正在操作的文件的读写结果不逐出，否则模型下一轮还得重读它，正是那 66 次重读的成因；同文件同范围的重复读取只保留最新一条，其余当场变占位符（dedup_duplicate_reads，[crates/octos-agent/src/compaction_tiered.rs:89-104]），消掉重读循环留下的一堆同文件残根。被替换的原因标注为 tier1_stale/tier1_oversized/tier1_superseded（[crates/octos-agent/src/compaction_tiered.rs:237-241]）。prune() 的调用方必须传 protected_tool_call_ids（[crates/octos-agent/src/compaction_tiered.rs:139-142]）：retry bucket 或 contract artifact 还引用的结果一个都不动，M6 的契约保证先于压缩。

Tier 1 还照顾了 provider 前缀缓存（KV cache）：过期结果位于历史深处，改写它会使整个缓存前缀失效，所以这类清理集中在每轮第一次调用做；超大结果刚落在前缀尾部附近，改写代价小，每轮迭代都可做。这个区分体现在 Tier1Pass::Full / OversizedOnly（[crates/octos-agent/src/compaction_tiered.rs:47-57]）和 loop 侧的 tier1_pass()（[crates/octos-agent/src/agent/loop_runner.rs:3846-3852]）：iteration 1 跑 Full，之后只跑 OversizedOnly。会话模式与任务模式（后台 worker）都在 LLM 调用前跑这档清理（[crates/octos-agent/src/agent/loop_runner.rs:1227]、[crates/octos-agent/src/agent/loop_runner.rs:2366]）。

Tier 2 是请求期装饰而非运行时循环：ApiMicroCompactionConfig（[crates/octos-agent/src/compaction_tiered.rs:428-457]）默认关闭（enabled: false），开启后由 into_context_management_json()（[crates/octos-agent/src/compaction_tiered.rs:478-505]）产出 clear_tool_uses_20250919 payload，默认保留最近 10 轮（DEFAULT_TIER2_KEEP_LAST_N_TURNS，[crates/octos-agent/src/compaction_tiered.rs:419-421]）；loop 侧在构造请求时注入（with_tier2_context_management，[crates/octos-agent/src/agent/loop_runner.rs:203-213]）；非 Anthropic provider 静默忽略，不发任何多余字段。octos 不复刻 Anthropic 的服务端清理逻辑，只做选择加入的开关。

Tier 3 是既有 CompactionRunner 的 trait 包装（FullCompactor，[crates/octos-agent/src/compaction_tiered.rs:524-560]），阈值判断复用 needs_preflight()（[crates/octos-agent/src/compaction.rs:572-580]），执行复用 run()（[crates/octos-agent/src/compaction.rs:584-706]）。run() 内部先做占位符清理（prune_tool_results()，[crates/octos-agent/src/compaction.rs:709-796]），再按清理后的 token 量决定是否摘要：占位符清理本身已把对话压回预算时，就不做摘要，不为压缩而压缩（[crates/octos-agent/src/compaction.rs:597-612]）。摘要完成后 enforce_preservation() 检查声明的 artifact 与 invariant 是否仍在消息流中被引用，缺失即报错回滚该轮压缩（[crates/octos-agent/src/agent/compaction.rs:278-318]）。CompactionRunner 按 policy 选择 summarizer（with_provider，[crates/octos-agent/src/compaction.rs:494-514]），并可通过 with_workspace_policy() 把声明的 artifact 名解析为具体 glob 模式（[crates/octos-agent/src/compaction.rs:538-556]）。每次压缩发出 octos.harness.event.v1 { kind: phase } 事件，运维可以看到 preflight 与 turn_end 的 token 前后对比。

8.2.1 分层的语义：为什么三档而不是一档

三档不是把一个算法拆成三步，而是三个不同成本结构的操作。Tier 1 是纯本地字符串替换，无 LLM 调用、无网络往返，微秒级完成，可以对每轮迭代无脑执行；模块头的估算引用了 Claude Code 的数据：仅便宜的 tier-1 就让 20-40% 的轮次永远不必触达昂贵的摘要器（[crates/octos-agent/src/compaction_tiered.rs:5-8]）。Tier 2 是零成本附加：不改本地历史，只在请求里多带一个字段，清理由 Anthropic 服务端做。Tier 3 才需要一次 LLM 调用生成摘要，也是唯一可能丢信息的一档。

代价排序决定了触发顺序：每轮先跑 Tier 1，清理后没超阈值就到此为止；超了才在下一轮 LLM 请求时由 Tier 3 判断是否摘要。绝大多数压力在第一档就被消化掉。同时三档的失败域互相独立：Tier 3 的 LLM 调用失败或超时会退回提取式摘要（[crates/octos-agent/src/compaction.rs:683-695]），不影响 Tier 1 已完成的清理；Tier 2 被服务端拒绝时请求照常发送，只是没有服务端清理。

三档还有一个共同的保真度承诺：tool_call_id 在 Tier 1 占位符里完整保留（[crates/octos-agent/src/compaction.rs:346-361]），Tier 3 的摘要正文虽然丢弃工具输出细节，但被摘要消息里的占位符仍指向 recall 句柄。换句话说，档位越深丢的越多，但每一步丢弃的都是「可通过 recall 找回」的内容，不是永久丢失。这个性质把「压缩」从不可逆操作变成可分层回退的操作。

8.3 Fidelity 四档模式

压缩后的消息保真度分四档：

实现分两层：默认的 ExtractiveSummarizer 走 Compact 档（[crates/octos-agent/src/summarizer.rs:66-85]）；LlmIterativeSummarizer（M6.4，[crates/octos-agent/src/summarizer.rs:166-230]）调用 LLM 产出 typed SessionSummary，迭代更新已有摘要，连续 3 次失败（DEFAULT_LLM_SUMMARIZER_FAILURE_THRESHOLD，[crates/octos-agent/src/summarizer.rs:93-96]）后锁定回提取式并记录 WARN。锁定是单向的：latch 置位后本 session 不再尝试 LLM，成功调用才会重置计数器。Summary 档已是可用选项，不是未来预留；但提取式仍是所有失败路径的兜底。trait 本身刻意保持同步签名（[crates/octos-agent/src/summarizer.rs:33-64]）：异步实现自己桥接 runtime，调用方不必在消息准备管线里 await。

CompactionRunner 按 policy 选择 summarizer（with_provider，[crates/octos-agent/src/compaction.rs:500-514]），并可通过 with_workspace_policy() 把声明的 artifact 名解析为具体 glob 模式（[crates/octos-agent/src/compaction.rs:537-556]）。每次压缩发出 octos.harness.event.v1 { kind: phase } 事件，运维可以看到 preflight 与 turn_end 的 token 前后对比。

8.4 Prompt Layer：分层系统提示构建

系统提示不是一个静态字符串，由多层信息组装。PromptLayerBuilder（[crates/octos-agent/src/prompt_layer.rs:23-56]）的 discover()（[crates/octos-agent/src/prompt_layer.rs:58-80]）按类别命中第一个可用文件即停：项目指令按 CLAUDE.md → .octos/instructions.md → .claude/instructions.md 顺序，Agent 描述按 AGENTS.md → .octos/agents.md → agents.md 顺序。命中即停意味着项目目录里不会同时装进两份指令文件；且只有显式传入或发现到的层才会拼接。

真正叠加的是 build()（[crates/octos-agent/src/prompt_layer.rs:83-102]）里的四类内容：base prompt、## Project Instructions 段、## Available Agents 段，以及 with_extra() 注入的运行时层（技能提示、工具说明等由调用方按需追加）。单文件上限 64KB（MAX_PROMPT_FILE_SIZE，[crates/octos-agent/src/prompt_layer.rs:11]），超限文件整体跳过而非截断，防止恶意或意外的大文件把窗口吃光。系统提示本身是每轮请求的固定前缀，也正是 prompt caching 能命中的部分：这层的体积直接影响每轮的 cache 命中率与成本。

8.5 Steering：会话中消息注入

steering 有两套并存的原语。类型层是 SteeringMessage（[crates/octos-agent/src/steering.rs:80-90]）：FollowUp、SystemReminder、RequestPause、Cancel，配套 channel()（缓冲默认 16）与非阻塞 drain_pending()（[crates/octos-agent/src/steering.rs:92-105]）。这套 enum 接口定义齐备且有测试，但文件头的 TODO 说明 SteeringReceiver 尚未接入主循环。

已接线的是 SteerBuffer（[crates/octos-agent/src/steering.rs:36-63]）：宿主（如 octos serve 的 turn/steer RPC）经 SharedSteerBuffer 注入纯 user 消息，agent loop 在每轮迭代顶部、下一次 LLM 调用之前 FIFO 排干（drain_pending_steer_input，[crates/octos-agent/src/agent/loop_runner.rs:744-775]，调用点在 [crates/octos-agent/src/agent/loop_runner.rs:1136]）。steering 不是中断：模型回答结束后若 buffer 非空，steer_input_pending() 让循环多跑一轮（[crates/octos-agent/src/agent/loop_runner.rs:776-781]）。

8.6 Prompt Guard：工具输出回流的 defang 层

Prompt Guard 的注入检测在第 7 章已介绍。上下文管理视角下它的接线位置更关键：已验证主路径是 sanitize_tool_output()（[crates/octos-agent/src/sanitize.rs:90-95]），先剥 base64 data URI、长 hex、凭据模式，再调用 sanitize_injection()（[crates/octos-agent/src/prompt_guard.rs:217]）做 defang，最后才把工具结果写回对话历史。它保护的是外部文本回流这一步，不是统一改写所有输入。模块头明确写着 "Not a security boundary"（[crates/octos-agent/src/prompt_guard.rs:1-19]）：base64、Unicode 同形字、零宽字符都能绕过；真正的控制是 sandbox、tool policy 和 human-in-the-loop hook。

8.7 主干演进：contract-gated compaction 与 prompt_context 桥

8.7.1 CompactAndRetry 的承接

第 5 章看到 ContextOverflow 经分类器进入 LoopDecision::CompactAndRetry。loop 侧的处理（[crates/octos-agent/src/agent/loop_runner.rs:494-515]）先跑 turn compaction helper，再以 PromptContextPhase::Retry 请求重备提示，然后继续循环。压缩因此是 Agent Loop 的恢复路径，不只是 token 优化。

8.7.2 三层状态与 SessionSummary

压缩后的状态不能只是一段自然语言摘要。当前源码把状态分三层：

SessionSummary（[crates/octos-core/src/task.rs:217-263]）是 typed compaction summary：goal、constraints、progress、decisions、files、next_steps 结构化保存，迭代更新时决策要么原文保留要么显式标 [STALE]，不允许静默丢弃。它不是长期记忆，长期记忆归第 4 章的 memory 系统。

8.7.3 prompt_context：caller-owned 桥

crates/octos-agent/src/prompt_context.rs（64 行）定义了阶段化的桥接口，解决一个分层问题：octos-agent 刻意保持低层，不依赖 octos-cli 的持久 ContextManager；但 session 运行时确实拥有自己的 context ledger，需要在每次 LLM 调用前做最终 prompt 准备。PromptContextPhase 分 TurnStart / Iteration / Retry（[crates/octos-agent/src/prompt_context.rs:12-30]）三阶段，loop 在每轮 LLM 调用前按迭代号选择阶段调用 prepare_prompt（实现见 [crates/octos-agent/src/agent/compaction.rs:229-276]，调用点在 [crates/octos-agent/src/agent/loop_runner.rs:1251-1258]）。桥存在时，octos-agent 自带的 legacy 与 tiered 压缩路径全部让位（各入口的早退检查在 [crates/octos-agent/src/agent/compaction.rs:15-17]、[crates/octos-agent/src/agent/compaction.rs:90-93]、[crates/octos-agent/src/agent/compaction.rs:191-196]）：session 运行时独家负责 prompt 压缩，两个组件不同时改同一条消息向量。桥返回错误不致命，loop 记 WARN 后沿用现有 prompt 向量（[crates/octos-agent/src/agent/compaction.rs:263-270]）。

PromptContextReport（[crates/octos-agent/src/prompt_context.rs:44-53]）回报替换是否发生、消息前后数量、token 估计与 generation 号，让调用方可观测而不必侵入。这个桥是 AppUI 与 serve/gateway 路径走生产级压缩的原因，也是 octos chat 与其不同的根源：后者没有 ContextManager，仍走 legacy 路径。

阶段化的动机是「同一接口、不同压力模型」。TurnStart（iteration 1）面对的是刚从持久 ledger 加载或恢复的对话，可能远超预算，桥此时最有机会做一次彻底的整理；Iteration（iteration 2 起）面对的是刚追加了几条工具结果的窗口，通常只需要增量维护；Retry 是 CompactAndRetry 恢复路径的专用阶段，loop 刚跑完 turn compaction helper，桥需要知道这次准备是溢出恢复的一部分，而非正常推进。三个阶段对桥的实现方意味着不同的压缩激进度与不同的记账需求，接口上一枚枚举就把上下文带全了，不需要调用方额外传参。

这个设计的另一层动机是错误隔离。桥返回 Result 而不是直接 panic 或中止循环：session 运行时的 ledger 可能损坏、锁可能被占，任何一种失败都不应该让 agent loop 崩溃。trait 的文档注释写明「返回错误不会中止 agent loop，agent 记录日志并回退到现有 prompt 向量」（[crates/octos-agent/src/prompt_context.rs:55-58]）。生产路径的持久层挂掉时，最坏结果是退化到 octos-agent 自己的 legacy 压缩，而不是整轮任务失败。

8.7.4 validator preservation 与 evidence ledger

压缩策略的约束是「变短的同时保住可验证契约」。crates/octos-agent/src/validators.rs 的 outcome 以 schema version JSONL 持久化到 .octos/validator_outcomes.jsonl（[crates/octos-agent/src/workspace_git.rs:708-714]）；workspace contract 状态读取 ledger，required validator 不满足则 ready = false 阻止 terminal success，optional validator 失败只计入 warning（[crates/octos-agent/src/workspace_git.rs:662-690]）。validator runner 的安全执行路径在第 9 章，workflow artifact gate 在第 12 章展开。

8.7.5 cache 经济学：一次性调用退出缓存写入

压缩与 prompt caching 有交互。prompt caching 默认开启时每个请求都打缓存断点，缓存写入按 1.25 倍计价；而压缩摘要这类一次性调用的前缀永远不会被重放，付这笔溢价纯属浪费。f3aa07f0（#2194）为此加了 ChatConfig.cache_retention：CacheRetention::None 让 provider 一个 cache_control 块都不发。压缩摘要调用（[crates/octos-agent/src/compaction.rs:1192-1198]）和迭代 summarizer 的 LLM 调用（[crates/octos-agent/src/summarizer.rs:300-310]）都已选择退出；agent loop 主调用因为前缀确实会被重放，保持缓存。成本层的完整分析见第 3 章。

flowchart LR
    H[History window] --> T1[Tier 1<br/>占位符替换]
    T1 --> T2[Tier 2<br/>Anthropic payload]
    T2 --> T3[Tier 3<br/>full compactor]
    T3 --> R[最近消息原样保留]
    T3 --> S[typed SessionSummary<br/>cache_retention: None]
    T3 --> A[保留 artifact 检查]
    A --> P[workspace policy]
    P --> V[validator JSONL ledger]
    V --> G{required 通过?}
    G -->|是| L[允许 terminal success]
    G -->|否| F[阻止 terminal success]

图 8-2：contract-gated tiered compaction。 三档压缩面在 contract 检查之前完成。

工程决策侧栏：为什么 80% 固定阈值

备选方案一是动态阈值：按任务复杂度调整触发点。它需要预测剩余迭代数，这几乎不可准确预测，复杂度评估本身还要消耗上下文。方案二是预测式：按历史 token 增长率外推。工具输出大小高度可变，预测错误换来的是提前压缩丢信息或延迟压缩冒溢出风险。

固定 80% 的优势是可预测：开发者知道什么时候会发生压缩，运维知道怎么定位。20% 预留足以容纳一次典型迭代（系统提示加用户消息加模型响应加一次工具结果）。在充满不确定性的 Agent 系统里，基础设施层的确定性本身就是价值。安全边际 1.2 再叠一层，承认 token 估算永远不精确。

8.8 本章回顾

1. 80% 阈值：window × 0.8 / 1.2 ≈ 67% 触发，最近六条无条件保留且不超预算一半，切割点避开工具组。

2. recall 双机制：预算感知读取在源头拒绝注定被逐出的整读；recall 凭 tool_call_id 从 recall_index（压缩不清理）取回原始字节，压缩从不可逆变为可按需恢复。

3. 分层压缩面：Tier 1 本地占位符（含工作集钉住与读去重）、Tier 2 Anthropic 服务端 payload、Tier 3 完整摘要；Tier 1 按 KV cache 友好性区分清理时机。

4. Fidelity 四档：Full / Truncate / Compact / Summary；LLM iterative typed summary 可用，3 次失败锁定提取式兜底。

5. Prompt Layer 与 Steering：按类别命中即停的发现逻辑加 64KB 上限；SteerBuffer 已接线到每轮迭代顶部，SteeringMessage enum 仍是未接线的扩展点。

6. contract-gated compaction：CompactAndRetry 承接、三层状态分离、prompt_context 阶段化桥、validator JSONL ledger、一次性调用的 cache 写退出，共同保证压缩后任务约束仍可恢复可验证。

7. 成本视角：压缩面与 prompt caching 互相作用。Tier 1 把过期清理集中在轮首以保住 KV 前缀缓存；一次性摘要调用以 cache_retention: None 退出缓存写入；系统提示层命中缓存前缀。上下文管理的每个决定同时是成本决定。

延伸阅读

• Anthropic "Long context window tips"：长上下文使用的实践建议
• Luhn 的自动文摘方法：提取式首行摘要的理论源头
• Anthropic prompt caching 文档：cache-write 定价与断点机制

思考题

1. recall 依赖 tool_call_id 作恢复句柄。如果 session 重启后 ledger 冷加载，spill 的 artifact 还在磁盘上吗？此时 recall 返回什么？
2. Tier 1 的 pin_recent_files 钉住最近 5 个文件。如果一个任务真正的工作集有 15 个文件，这个参数会带来什么行为？调大它的代价是什么？
3. prompt_context 桥存在时 tiered 压缩全部让位。为什么不让两层同时工作，各压缩一部分？

版本演化说明 本章分析基线为 octos main @ 9c157101（2026-09-03 实测核对）。三个近期变更塑造了本章结构：e312e4c1（#2131，recall 工具 + 预算感知读取）、825d6a52（#2131，recall_index 压缩存活）、f3aa07f0（#2194，一次性调用的 cache-write 退出）。分层压缩面来自 M8.5 #540。后续阅读优先核对 crates/octos-agent/src/agent/compaction.rs（1,932 行）、crates/octos-agent/src/compaction_tiered.rs（1,271 行）、crates/octos-agent/src/agent/compaction.rs、crates/octos-agent/src/tools/recall.rs 与 crates/octos-cli/src/api/context_manager.rs（4,003 行）的 recall 相关段落。

第 9 章：扩展机制：Skills、Plugins 与 MCP

定位：本章展示 octos 当前源码中的三种扩展机制：Skills（Markdown 声明式）、Plugins（本地可执行工具 / skill package extras）、MCP（标准化协议集成）。前置依赖：第 6 章。适用场景：想为 octos 编写自定义扩展的贡献者，以及想理解 Agent 扩展架构设计的开发者。

Agent 的价值来自适配不同场景的能力。法律文书审查需要法律提示，研究 Agent 需要长时后台任务，远程服务集成又需要标准协议。把所有扩展都塞进同一种机制，会让简单需求过度工程化，也会让复杂需求被迫挤进不合适的抽象。

octos 当前的答案不是"一种万能插件"，而是三条互补轨道：

• Skills：改变 Agent 的提示与上下文
• Plugins：把本地可执行程序包装成 Tool，并承载 skill package extras
• MCP：通过标准协议连接外部工具服务器

9.1 Skills 轨道：Markdown 声明式扩展

Skills 是最轻量的扩展机制。一个 skill 的核心就是一个 SKILL.md，外加可选的 manifest.json。

先看两条轨道在代码量上的悬殊分工：crates/octos-agent/src/skills.rs 全文 942 行，而 crates/octos-agent/src/plugins/ 八个文件合计 14,675 行。这个数量差不是偶然，而是职责边界的直接体现。crates/octos-agent/src/skills.rs 只回答一个问题：模型能看见什么。它负责发现技能目录、解析极简 frontmatter、判断可用性、把结果压成一个 XML 摘要注入系统提示，全程不碰进程、不碰协议、不碰安全策略。plugins/ 回答的则是另一个问题：系统会执行什么。manifest 解析、可执行文件发现与校验、子进程协议、环境清理、审批与并发控制全部堆在这里；其中光是执行协议与安全约束（crates/octos-agent/src/plugins/tool.rs 3,219 行）加上对应测试（crates/octos-agent/src/plugins/tool_tests.rs 4,406 行）就占了一半以上（51.96%），可见"安全地跑一个外部程序"远比"描述一个提示片段"昂贵。一个 skill package 目录里同时放着 SKILL.md 与 manifest.json 时，正是这两条轨道的汇合点：SkillsLoader 读前者注入提示，PluginLoader 读后者注册工具，XML 索引里的 tools="true" 属性标记的就是这条接缝。

9.1.1 SKILL.md 格式

---
name: code-review
description: Review code changes for bugs, security issues, and style
version: 1.0.0
requires_bins: rg,git
requires_env: GITHUB_TOKEN
---

When reviewing code, focus on:
1. Security vulnerabilities
2. Error handling completeness
3. Behavior regressions

SkillsLoader 并没有实现完整 YAML 解析器。它做的是两步简化处理：

1. 用 split_frontmatter() 找到首尾 --- 之间的 frontmatter 块（crates/octos-agent/src/skills.rs:301-320）
2. 用 fm_value() 从简单的 key: value 行里读取 name、description、requires_bins、requires_env、always、version、author 等字段（crates/octos-agent/src/skills.rs:322-343）

fm_value() 甚至会剥掉行内注释、把 [] / "" / ~ 这类 YAML 空值当缺失处理。这意味着 skill 元数据的设计目标不是"表达力最大"，而是"足够稳定、足够便宜"：引入完整 YAML 解析器会带来新依赖与解析歧义，而 skill 作者实际需要的只是几个扁平的键值对。测试里专门覆盖了重复键取首个、冒号出现在值里、空 frontmatter 这些边界（crates/octos-agent/src/skills.rs:590-645 的测试组），说明这条简化路径是被当作契约来维护的，不是权宜之计。

available 的判断也来自这里：parse_skill() 逐项检查 requires_bins 里的命令是否在 PATH（which_exists()），requires_env 里的变量是否已设置，两者全过才置 available: true（crates/octos-agent/src/skills.rs:244-294,351-369）。注意这是可用性检查而非安全边界：一个缺依赖的 skill 只是从摘要里标成不可用，并不会被隔离执行。

9.1.2 分层目录与加载顺序

SkillsLoader 只维护一个"技能目录列表"，先加的目录优先级高（crates/octos-agent/src/skills.rs:62-116）。list_skills() 的实际组装顺序是：先装入编译内置的 BUILTIN_SKILLS，再按"低优先级目录先扫描、高优先级目录后覆盖"遍历，用 retain 删同名旧条目（crates/octos-agent/src/skills.rs:118-173）。这个"倒序遍历加去重"的实现换来一个性质：无论目录有多少层，同名技能最终只保留最高优先级来源的一份，且加载逻辑不需要知道每层目录的语义。

目录列表本身来自部署面的拼装：Config::plugin_dirs_from_project() 依次收集 <octos_home>/plugins、<octos_home>/skills、<octos_home>/bundled-app-skills/，再追加冒号分隔的 OCTOS_SKILLS_PATH 环境变量目录；旧的 ~/.octos/skills HOME 全局目录已不再扫描，只发一次性迁移警告（crates/octos-cli/src/config.rs:1330-1375）。gateway 启动时还会把二进制里携带的 app-skills / platform-skills 引导到分层目录（crates/octos-cli/src/commands/gateway/gateway_runtime.rs:566-573、crates/octos-agent/src/bootstrap.rs:103-115）。

所以这不是"工作区 / 全局 / 内置"三层固定表，而是一个 layered view：部署目录提供共享基线，账号目录提供私有安装，环境变量提供额外注入。

9.1.3 skill layering v1：per-profile 选择继承（9b1fc38f）

分层目录解决"技能从哪来"，skill layering v1（提交 9b1fc38f）解决"这个 profile 允许加载哪些"。

配置面是 per-profile 的 skills 选择块，lowering 成 crate 无关的 SkillFilter（crates/octos-agent/src/skills.rs:12-36）：

• AllExcept(ids)：全发现，减去禁用名单
• Only(ids)：白名单模式，只加载列出的技能

这个枚举被刻意设计成不依赖任何 CLI 类型，为的是让提示侧的 SkillsLoader 与工具侧的 plugin loader 消费同一个选择决定。否则会出现一种危险的不一致：技能的提示卡被禁了，它的可执行工具却还注册着，模型看不到说明但工具仍然可调。

执行面有三处一致收敛（crates/octos-agent/src/skills.rs:156-176,176-201）：list_skills() 用 retain 把被禁技能从摘要里删掉；load_skill() 对被禁名字直接返回 None，正文永远进不了 prompt；get_always_skills() 因走 list_skills() 同样被过滤。plugin 侧同一个 filter 也生效：load_into_with_options_and_filter() 对 manifest id 命中禁用名单的 skill package 整体跳过，工具、hooks、prompt fragments 一并不加载（crates/octos-agent/src/plugins/loader.rs:296-316）。

接线发生在 gateway 组装处：runtime 从已解析 profile 的 config.skills 生成 filter，传给账号级 loader（crates/octos-cli/src/commands/gateway/gateway_runtime.rs:646-648）；子 bot 在 crates/octos-cli/src/commands/gateway/profile_factory.rs 里继承同一选择（crates/octos-cli/src/commands/gateway/profile_factory.rs:698-702）。None 表示没有 skills 层，一切照旧，完全向后兼容。

这里需要特别区分配置继承和本地 skill 继承：子账号可以继承父 profile 的 skill 选择 filter，但 customer-installed skills 不从父账号继承。account skills 目录严格解析为当前账号自己的 data_dir/skills，plugin dirs 也只返回当前账号的 skills 目录（crates/octos-cli/src/skills_scope.rs:96-112）。父账号安装的本地可执行扩展不会在子账号中静默启用。

9.1.4 XML 技能索引

build_skills_summary() 把过滤后的可见技能转成 XML 注入系统提示（crates/octos-agent/src/skills.rs:203-219）：

<skills>
  <skill available="true" tools="true">
    <name>deep-search</name>
    <description>Deep web research...</description>
    <location>/.../SKILL.md</location>
  </skill>
</skills>

三个容易写错的点：

• 当前 XML 里没有 name="..." 属性，而是 <name> 子节点
• tools="true" 的含义是"该 skill 目录包含 manifest.json"，不是"这个 skill 正在执行工具"
• location 把 skill 的真实来源路径暴露给模型，帮助它区分 builtin 与外部 skill

因此 XML 摘要不是单纯的"可用技能列表"，它是模型可见的技能目录索引，且已经被 skill layering 过滤过：被 profile 禁用的技能在这里完全不可见，模型连"它存在"这个事实都拿不到。

9.1.5 spawn_only：自动后台化，而不是隐藏工具

spawn_only 标记定义在 skill package manifest 的工具项上（crates/octos-agent/src/plugins/manifest.rs:452-455），但它的运行时语义不在 manifest 里，而在 registry 和 agent 执行循环里：

• PluginLoader 装载时为这些工具名调用 registry.mark_spawn_only(name, msg)（crates/octos-agent/src/plugins/loader.rs:332-339）
• ToolRegistry 为它们维护自定义提示文案和任务跟踪状态（crates/octos-agent/src/tools/registry.rs:156-172）
• 主 agent 发现某次 tool call 命中 spawn_only 时，不同步执行，而是 tokio::spawn 一个后台任务，立刻向模型返回 spawn_only_message（crates/octos-agent/src/agent/execution.rs:579 起）

这意味着 spawn_only 不是"从 ToolSpec 里隐藏掉"。按当前实现它们仍然注册在工具系统里并对模型可见；差别只是调用时被自动后台化。模型不需要学习一套新的"任务提交工具"，它照常发起 tool call，运行时替它决定这次调用是同步等待结果，还是立刻返回句柄转后台继续跑。

更进一步，resolve_extras() 在 skill package 含有 spawn_only 工具时注入技能卡 prompt fragment（crates/octos-agent/src/plugins/extras.rs:39-45,449-456）。这样模型既能看到工具，也能同时拿到"什么时候该用这个后台工具"的提示上下文。

而到了 subagent 场景，registry 会清空这些标记，因为"subagent 本身就是后台上下文"，此时工具会像普通工具一样直接执行：在已经后台化的上下文里再套一层后台化只会丢失结果句柄，白增加一层调度开销，还让子 agent 无法拿到工具返回值。

9.2 Plugins 轨道：本地可执行工具与 skill package extras

如果说 Skills 负责改变 Agent 的"思维方式"，Plugins 负责的就是让 Agent 真正调用外部程序完成工作。

9.2.1 runtime manifest：不只是工具声明

当前 runtime 热路径使用的是 crates/octos-agent/src/plugins/manifest.rs 中的 manifest 结构：

{
  "name": "weather",
  "version": "1.0.0",
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "input_schema": { "type": "object", "properties": { "city": { "type": "string" } } },
      "env": ["WEATHER_API_KEY"],
      "risk": "medium",
      "concurrency_class": "safe"
    }
  ],
  "sha256": "a1b2c3...",
  "timeout_secs": 600,
  "requires_network": true
}

但把它理解为"纯工具 manifest"已经不够了。当前这个结构还支持：id、mcp_servers（SkillMcpServer）、hooks（SkillHookDef）、prompts.include、actions、binaries（按 {os}-{arch} 键的预编译下载）、spawn_only / spawn_only_message、env / env_allowlist、risk、concurrency_class、make_type 等（crates/octos-agent/src/plugins/manifest.rs:8-110,387-477）。因此它更接近一个 skill package runtime manifest：工具只是其中一种载荷，MCP server 声明、生命周期 hooks、prompt 注入同样可以独立成包。如果 manifest.tools 为空但声明了 extras，PluginLoader 会跳过可执行文件搜索，照样把 extras 装进系统（has_extras()，crates/octos-agent/src/plugins/manifest.rs:180-198；装载分支 crates/octos-agent/src/plugins/loader.rs:607-626）。换句话说，"没有二进制的 plugin"是合法形态，它退化为纯 extras 包。

9.2.2 Plugin 二进制协议

sequenceDiagram
    participant Agent
    participant Plugin as Verified Executable

    Agent->>Plugin: exec(".weather_verified", argv[1]="get_weather")
    Agent->>Plugin: stdin: {"city":"Beijing"}
    Plugin->>Agent: stderr: line-oriented progress
    Plugin->>Agent: stdout: {"output":"Beijing: 25°C, sunny","success":true}
    Agent->>Plugin: process exits

图 9-1：Plugin 二进制协议时序图。

这里的实现细节比"stdin JSON / stdout JSON"稍复杂：

• runtime 实际执行的是经过 hash 校验后落盘的 verified 副本（crates/octos-agent/src/plugins/tool.rs:109-131）
• argv 第一个参数是 tool name
• stdin 发送 JSON 参数
• stderr 逐行读出并转成进度事件
• stdout 优先按结构化 JSON 解析；不是合法 JSON 时退回"原样拼接 stdout + stderr 文本"（crates/octos-agent/src/plugins/tool.rs:3117-3130 附近的结构化字段解析）

把 stderr 单独留作进度流是个务实的设计：很多现成命令行工具本来就会往 stderr 打日志，plugin 作者不需要重写输出逻辑，只要保证最终结果以 JSON 落在 stdout 即可；而调用侧拿到的是流式进度事件，长任务不再是一个黑盒等待。

结构化 stdout 还支持比 output/success 更丰富的语义：file_modified 标记文件系统被改动，files_to_send 请求把产出文件自动回传会话（crates/octos-agent/src/plugins/tool.rs:3117-3130、crates/octos-agent/src/plugins/tool.rs:1229-1307）。runtime 还会尝试从 out 参数或输出文本里自动探测生成文件。

所以 Plugin 协议的真实价值是：把"外部进程"包装成"可流式报告进度、可自动回传文件的 Tool"。

9.2.3 安全与运行时约束

Plugin 这一层的安全措施有几道必须写清楚。

第一道：可执行发现是保守的。 PluginLoader 只把"子目录 + manifest.json"当成候选项。找二进制时依次尝试 manifest 名、目录名、main，最后才是目录扫描（crates/octos-agent/src/plugins/loader.rs:640-646,1189-1193）。

第二道：SHA-256 校验封 TOCTOU 窗口。 Loader 把原始字节一次读进内存，对内存字节算 hash 与 manifest 比对，落盘 verified 副本并记录 load_time_hash；执行前的 re-hash gate 再对盘上文件复验同一 hash，封住 load→exec 的替换窗口（crates/octos-agent/src/plugins/loader.rs:649-712、crates/octos-agent/src/plugins/tool.rs:109-131）。

第三道：资源与环境约束。

• 100MB 可执行文件上限，超限在读入内存前就拒绝（MAX_EXECUTABLE_SIZE，crates/octos-agent/src/plugins/loader.rs:24,654-664）
• 子进程环境经 sanitize_command_env 清理注入向量；tool 级 env / env_allowlist 采用严格语义：secret-like 变量必须被 manifest 显式列出才转发，非 secret 走 legacy 兼容路径（crates/octos-agent/src/plugins/tool.rs:85-91）
• 运行时注入 OCTOS_WORK_DIR 给 plugin 放输出文件
• 默认超时是 600 秒，不是 30 秒（DEFAULT_TIMEOUT，crates/octos-agent/src/plugins/tool.rs:151-163）；manifest 的 timeout_secs 只是覆盖默认值

第四道：风险与并发类别不是装饰字段。 risk 会进入审批路径：high / critical 强制交互式 approval，缺少 approval bridge 时安全拒绝；low 默认不触发审批，medium / unknown 主要用于显式呈现（RiskLevel::classify / requires_approval，crates/octos-agent/src/plugins/manifest.rs:479-520）。

concurrency_class 识别 safe 和 exclusive。未知值不被乐观当作 safe：classify_concurrency_class() 返回 FailClosed，执行侧落到 Exclusive，声明笔误不会把互斥工具放成并行（crates/octos-agent/src/plugins/manifest.rs:569-609）。

第五道：Unix 上的符号链接拒绝。 is_executable() 用 symlink_metadata() 检查文件类型，只接受普通文件（crates/octos-agent/src/plugins/loader.rs:1354-1365）。这不是全部安全边界，但能缩小 link-swap 攻击面。

9.2.4 runtime PluginLoader 与 octos-plugin SDK 的边界

这一章最容易写错的地方，是把仓库里的两层代码混成一层。

当前 runtime 热路径是 crates/octos-agent/src/plugins/（8 文件合计 14,675 行，其中 crates/octos-agent/src/plugins/tool.rs 3,219 行、crates/octos-agent/src/plugins/tool_tests.rs 4,406 行）：扫描目录、加载 manifest、解析 extras、校验并注册可执行工具，单个 plugin 失败只 warn! 跳过。

crates/octos-plugin 则是 SDK / tooling crate，提供另一层抽象：

• discover_plugins()：按来源优先级扫描并按 manifest id 去重，首个出现者优先（crates/octos-plugin/src/discovery.rs:47-59）
• check_requirements()：做 bins/env/os 三类 gating（crates/octos-plugin/src/gating.rs:42）
• richer manifest：id/type/requires/install/...（crates/octos-plugin/src/manifest.rs:112）

两层有关联但不能混为一谈：runtime 加载有自己的 manifest 类型与路径，octos-plugin 面向校验器、市场、安装器这类工具链。还有一个很小但真实的细节：gating 把 darwin 和 macos 当等价别名，避免 manifest 与 Rust 平台字符串不一致时误伤（crates/octos-plugin/src/gating.rs:73-78）。

9.3 MCP 集成：rmcp SDK 上的标准协议客户端

MCP（Model Context Protocol）是标准化的工具集成协议。octos 的 MCP client 位于 crates/octos-agent/src/mcp.rs，整体构建在官方 rmcp SDK 之上（提交 65486dad 迁移；crates/octos-agent/Cargo.toml:41-44：rmcp = { version = "1.8", ... }，注释明确写着 "stdio + streamable-HTTP + OAuth 2.1"）。

9.3.1 为什么迁 rmcp：自研客户端的三个 spec 缺口

crates/octos-agent/src/mcp.rs 模块文档写得很直白：旧的手写客户端存在三个协议级缺陷——缺 notifications/initialized、硬编码协议版本、每请求一行的读取方式在并发下会错位（crates/octos-agent/src/mcp.rs:1-22）。

三个缺口各有真实后果。缺 initialized 通知时，按规范等待该信号才进入工作状态的 server 会永远停在半初始化；硬编码协议版本则在 server 协商出不同版本时要么被拒、要么静默降级；而"一次调用读一行响应"在并发调用下必然错位：JSON-RPC 响应靠 id 匹配请求，不是靠到达顺序，两个并行 tool call 的响应一旦交错，逐行读取的解析就会张冠李戴。

rmcp 把这三件事全部接管：完整生命周期握手（initialize + notifications/initialized）、协议版本协商，以及单连接上的并发请求多路复用与 id 路由。对上层意味着并发 tool call 不再需要排队等前一个响应读完，一个慢工具不会阻塞同 server 上的其他工具。

9.3.2 三种接入方式

McpServerConfig（crates/octos-agent/src/mcp.rs:53-88）按字段分派到三条连接路径：

stdio 路径 spawn 子进程并设 kill_on_drop，子进程的存活与 rmcp 会话的 Arc 引用绑定：最后一个引用释放时传输关闭、子进程被回收。环境沿用与所有 octos 子进程相同的清理规则：剥掉注入向量变量，只转发 operator 显式列出的 env 名，连显式列出的名字也要再过一遍 denylist，防止配置里写 LD_PRELOAD 重新打开进程劫持口子（crates/octos-agent/src/mcp.rs:452-485）。rmcp 的子进程传输用无界 read_until 读 JSON-RPC 帧，源码注释承认这丢掉了旧客户端的单行上限，接受的理由是 stdio server 是 operator 自己点名信任的本地二进制（crates/octos-agent/src/mcp.rs:465-472）。

HTTP 路径不是"纯 SSE 通道"：rmcp 的 StreamableHttpClientTransport 走 streamable-HTTP 语义（POST 请求、可流式响应），静态头（包括一条 Authorization bearer token）原样携带，octos 在外面套了 SSRF 防护（见 9.3.4）。

OAuth 路径服务那些需要真实用户授权的远端 server。token 的取得与使用分成两个命令面：octos mcp login <url> 交互式跑一遍 OAuth 2.1 授权码流程（本地回环 redirect 接收回调），把 access + refresh token 以 JSON 序列化写进 OS keyring，keyring 键是"规范化 URL + sha256 前缀"，同一 server 换写法也不会存出两份（crates/octos-agent/src/mcp_auth.rs:30-95,186 起）。运行时 connect_oauth() 从 keyring 取回 token 交给 rmcp 的 AuthClient，过期自动刷新，全程无需重新登录；连接前强制 HTTPS 并拒绝字面私网主机（crates/octos-agent/src/mcp_auth.rs:105-125）。这里有一个容易漏掉的细节：OAuth 下 HTTP 客户端有两份，传输客户端带配置头走 SSRF 过滤，而授权服务器端点（discovery / registration / token / refresh）走单独的 SsrfOAuthHttpClient，因为那些请求本来就可能指向另一台主机（crates/octos-agent/src/mcp_auth.rs:126-135）。

9.3.3 发现、超时与工具注册

启动流程是 fail-soft 的（McpClient::start()，crates/octos-agent/src/mcp.rs:374-437）：逐个 connect，连不上的 server 记 warning 跳过，不让一个坏 server 拖死整个 agent。工具发现也加了超时：一个完成了 initialize 却迟迟不答 tools/list 的 server 会在 HANDSHAKE_TIMEOUT（30 秒）后被跳过，不阻塞后面的 server。这层保护针对的是"握手成功但列表永不返回"的病态 server，它在协议上合法，在工程上却能把启动卡死。

对每个发现的 tool，validate_schema() 检查 input_schema：嵌套深度 $\le 10$（MAX_SCHEMA_DEPTH）、序列化大小 $\le 64\text{KB}$（MAX_SCHEMA_SIZE，crates/octos-agent/src/mcp.rs:47-49,296-322）。执行侧 McpTool::execute() 把 tools/call 包在 60 秒超时里，非文本 content（图片、资源）会被丢弃，因为 agent 工具面当前是纯文本的（crates/octos-agent/src/mcp.rs:586-612）。

注册前有两道保护（register_tools()，crates/octos-agent/src/mcp.rs:532-558）：

• 名称保护：PROTECTED_NAMES 列出 20 个内置工具名（shell、read_file、git、browser 等），同名 MCP tool 直接跳过，防止远端 server 静默劫持核心能力（crates/octos-agent/src/mcp.rs:349-372）
• 传输存活（提交 3934aeb6）：transports 先于 tools 移交 registry 持有（keep_mcp_service_alive）。否则工具是连接的唯一 owner，profile 收窄把最后一个 MCP tool 滤掉时会顺带杀掉子进程（issue #1886）。一个可见性过滤器不应该有终结连接的副作用

9.3.4 HTTP 路径的 SSRF 防线

远程 MCP 是外呼面，octos 在这一层放了两级防线（crates/octos-agent/src/mcp.rs:122-183）：

1. 配置级：reject_private_url_host() 拒绝字面私网/回环 IP 或 localhost 的 URL。reqwest 对字面 IP 主机会跳过自定义 resolver，这层专门补上（crates/octos-agent/src/mcp.rs:165-183）
2. 解析级：自定义 SsrfDnsResolver 挂进 HTTP client，每次解析都重新检查，命中私网/回环/link-local/元数据地址即拒，同时挫败 DNS rebinding；重定向策略设为 none，3xx 不能把请求走私到内网主机（crates/octos-agent/src/mcp.rs:122-163）

OAuth 路径的防线更宽：授权服务器的 discovery / registration / token / refresh 端点也全部经过 SSRF 校验的 HTTP client（SsrfOAuthHttpClient，crates/octos-agent/src/mcp.rs:211-293、crates/octos-agent/src/mcp_auth.rs:126-135）。一个自称公网的 MCP server 不能把 token 流量指向 127.0.0.1 或云元数据地址 169.254.169.254，否则攻击者可以用一个恶意 server 探测内网甚至收割凭证。

工程决策侧栏：为什么需要三种扩展机制

维度	Skills	Plugins	MCP
核心作用	改提示与上下文	跑本地可执行工具	接外部协议化工具服务器
主要载体	SKILL.md	manifest.json + executable	rmcp 会话（stdio / HTTP / OAuth）
运行边界	无独立执行边界	外部进程 + verified copy	本地子进程或远程连接
典型增值点	低成本行为定制	进度流、文件回传、后台任务	跨 Agent 平台复用
安全面	可用性检查 + profile 过滤	hash 校验 + env 清理 + work dir	SSRF + schema 验证 + 名称保护

为什么不能统一成一种？

因为它们解决的不是同一类问题。Skills 让模型学会"怎么想"，Plugin 让系统学会"怎么做"，MCP 让系统学会"怎么接别人的能力"。

如果把 Skills 也做成 Plugin，会让纯提示定制被迫带上二进制、协议和运行时安全成本。反过来，如果把 Plugin 做成纯 Skill，又无法提供真实执行、进度流和文件产出。MCP 看起来和 Plugin 都像"工具扩展"，但它追求的是协议互操作，而不是本地 runtime 集成的最低摩擦。

9.4 Harness 工程契约：详见第 10 章

Skills、Plugins 和 MCP 解决的是"能力如何进入 octos"；Harness 解决的是能力运行之后如何变成可验证、可观测、可升级的工程契约——ABI schema versioning、OCTOS_EVENT_SINK JSONL side-channel、validator runner 和 starter app skills。自 v2 起这部分独立成章，见 第 10 章。

9.5 配置车道：mcp_servers 与 sub_providers

扩展机制的两条配置车道都在 CLI 侧的顶层 Config 上。它们一个决定"接哪些外部工具服务器"，一个决定"子 agent 用哪些模型"，名字像但语义完全不同。

9.5.1 mcp_servers

顶层键 mcp_servers: Vec<octos_agent::McpServerConfig>（crates/octos-cli/src/config.rs:108-110）直接复用 agent crate 的配置类型。这是个刻意的接线选择：配置解析面与运行时消费面共享同一个 struct，McpClient::start() 收到的就是配置文件里写的东西，中间不存在第二次转换，也就不存在"配置写了一套、运行时理解另一套"的漂移空间。每个条目的字段就是 9.3.2 表里的三分派条件（command/args/env 或 url/headers 或再加 oauth/scopes），外加可选的 concurrency_class 覆盖（缺省 Safe，未知值同样 fail-safe 落 Exclusive）。最小示例：

{
  "mcp_servers": [
    { "command": "uvx", "args": ["mcp-server-fetch"] },
    { "url": "https://mcp.example.com/mcp", "oauth": true, "scopes": ["read"] }
  ]
}

9.5.2 sub_providers

顶层键 sub_providers: Vec<SubProviderConfig>（crates/octos-cli/src/config.rs:182-184；结构体定义 crates/octos-cli/src/config.rs:616-654）声明可供 spawn 工具选择的子 provider。字段包括 key（引用短名，如 cheap、strong）、provider、model、api_key_env、base_url、description、default_context_window、max_output_tokens、api_type。其中 description 会连同成本与能力元数据一起进 spawn 工具的 schema，模型据此挑模型；default_context_window 决定子 agent 裁剪历史的激进程度。最小示例：

{
  "sub_providers": [
    { "key": "cheap", "provider": "openai", "model": "gpt-4o-mini", "api_key_env": "OPENAI_API_KEY" }
  ]
}

保留键 goal_verifier：一个 sub_providers 条目若以 goal_verifier 为 key，goal 完成判定会路由到这个 provider 上验证（GOAL_VERIFIER_LANE_KEY 与 build_goal_verifier_provider()，crates/octos-cli/src/runtime/profile.rs:128-190）。这条车道的意义在于把"干活的模型"和"验收的模型"分开：未配置时回落到评分会话自身的 provider（#1935 之前的旧行为，作为兼容默认保留），此时目标完成与否由同一个模型自证，而配置了独立 verifier 后，判定由另一条 provider 车道给出。

9.6 本章回顾

1. Skills：SKILL.md + 简化 frontmatter 解析，分层目录去重合成一个视图，再由 per-profile 的 SkillFilter（layering v1，9b1fc38f）过滤出 XML 摘要注入系统提示。

2. Plugins：runtime manifest 已是 skill package manifest；verified copy 封 TOCTOU，env allowlist、risk 审批、concurrency fail-closed、600 秒默认超时共同构成执行边界。

3. spawn_only：不是隐藏工具，而是自动后台化。主 agent 立即返回 spawn_only_message，subagent 上下文里恢复直接执行。

4. MCP：rmcp SDK（1.8）上的 stdio + streamable-HTTP + OAuth 2.1 三接入（65486dad）；fail-soft 启动、schema 验证、PROTECTED_NAMES、SSRF 双级防线，registry 持有传输（3934aeb6）。

5. 架构边界：octos-agent/src/plugins/*（14,675 行）是 runtime 热路径；crates/octos-agent/src/skills.rs（942 行）是提示轨道；octos-plugin 是 discovery/gating SDK。

6. 配置车道：mcp_servers 决定接哪些 MCP server，sub_providers 决定子 agent 用哪些模型，goal_verifier 是后者的保留键。

Part 2 到此结束。下一章开始 Part 3，从单机会话推进到消息总线与多会话编排。

延伸阅读

• Model Context Protocol：https://modelcontextprotocol.io/
• rmcp（Rust MCP SDK）：https://crates.io/crates/rmcp
• JSON-RPC 2.0：https://www.jsonrpc.org/specification

思考题

1. Skill 过滤的收敛点：为什么 load_skill() 对被禁技能必须返回 None，而不只是从 XML 摘要里删掉？如果模型凭"记忆"直接点名加载一个被禁技能，会发生什么？

2. Plugin 信任链：verified copy 解决了 load→exec 的 TOCTOU，但如果 manifest 与原始二进制一起被替换，hash 仍然会"自洽"。你会如何把信任链再往前推进一层？

3. rmcp 的取舍：迁到 rmcp 修复了三个 spec 缺口，但也丢掉了 stdio 单行 1MB 上限（无界 read_until）。这个取舍在什么前提下是安全的？什么部署形态下需要重新审视？

版本演化说明 本章基于 octos 主分支 9c157101（2026-09-03 实测）撰写，覆盖三处近期演化：65486dad MCP 客户端整体迁到 rmcp SDK（stdio + streamable-HTTP + OAuth 2.1，crates/octos-agent/src/mcp.rs 重写、新增 crates/octos-agent/src/mcp_auth.rs）；9b1fc38f skill layering v1（per-profile 选择继承，crates/octos-agent/src/skills.rs、crates/octos-agent/src/plugins/loader.rs）；3934aeb6 registry 持有 MCP 传输。后续阅读时优先核对 crates/octos-agent/src/skills.rs、crates/octos-agent/src/plugins/、crates/octos-agent/src/mcp.rs、crates/octos-agent/src/mcp_auth.rs、crates/octos-plugin/src/ 与 crates/octos-cli/src/config.rs。

第 10 章：Harness：把「模型说做完了」变成可验证契约

定位：本章解剖 octos 的 harness 体系:声明式校验器、结构化事件 ABI、schema 版本化、工作区策略、结构化错误分类与生命周期 hooks。先澄清一个常见误解：不存在独立的 harness crate；harness 是 octos-agent 内的六个模块加上四个 starter 脚手架。前置依赖：第 5 章（错误恢复链）、第 6 章（Tool trait）、第 7 章（沙箱）。适用场景：需要让长跑 Agent 的产出可审计、可门禁、可回放的读者。

第 5 章讲 Agent Loop 时留了一个口子：模型回答「做完了」，运行时凭什么信？第 6 章的工具让 Agent 能改变世界，第 7 章的沙箱约束它能改到什么程度，但「改完之后是否达标」仍是空白。harness 补上这块：它不提升模型能力，而是把「完成」从一句自然语言变成机器可判定的契约。

先看这六个模块在源码中的体量（octos main @ 9c157101 实测）：

合计 12,676 行。没有 harness crate,这六份文件都住在 crates/octos-agent/src/ 下，加上 crates/app-skills/ 里的四个 starter 目录（audio/coding/generic/report），才是 harness 的全部。这个澄清本身有信息量：harness 不是又一层抽象盒子，而是把校验、事件、版本化直接织进 Agent 运行时。

flowchart LR
    subgraph octos-agent 内六模块
        WP[workspace_policy<br/>声明层 3165 行]
        V[validators<br/>执行层 2772 行]
        HE[harness_events<br/>事件 ABI 2789 行]
        AS[abi_schema<br/>版本化 349 行]
        H[hooks<br/>生命周期 2856 行]
        HErr[harness_errors<br/>错误分类 745 行]
    end
    ST[四个 starter<br/>app-skills/harness-starter-*] -->|workspace-policy.toml| WP
    WP -->|validators 列表| V
    V -->|ValidatorResult 事件| HE
    H -->|Feedback 注入模型| HE
    HErr -->|Error 事件| HE
    AS -.版本护栏.-> WP
    AS -.版本护栏.-> HE

三支柱的分工可以这样记：workspace_policy 声明什么算完成，validators 执行判定，abi_schema + harness_events 保证判定的过程与结果能被不同版本的组件听懂。hooks 与 harness_errors 是两翼：前者把生命周期变成可编程点，后者给一切失败配上类型。下面逐一展开。

10.1 支柱一：声明式校验器

10.1.1 为什么校验是数据，不是代码

harness 的第一支柱回答「什么算完成」。先看它反对什么：让 Agent 的产出可验证，最直觉的做法是写一个 fn validate() -> bool。但校验逻辑一旦写成代码，它就跟宿主版本锁死：旧 workspace 遇上新 runtime，函数签名对不上；反过来，runtime 升级也无法解释旧策略文件里的校验意图。octos 的选择是把校验器做成数据：WorkspacePolicy 里的一张表，由统一的 runner 解释执行。

三个工程理由支撑这个决策。第一，可序列化：策略文件能随 workspace 存档、diff、迁移，schema_version 字段让旧文件在新 runtime 里继续可读（见 10.3）。第二，可沙箱：runner 是唯一执行入口，命令型校验器统一过 shell 安全层（SafePolicy）与 BLOCKED_ENV_VARS 环境变量清洗，策略作者无法绕过（详见第 7 章的沙箱与 b64bd532/bf6be8cc 将 project-root 校验器收进沙箱、mcp-serve 路径 fail-closed 的决策）。第三，可回放：每条执行结果落成 JSONL 台账，重启后原样重读，不依赖进程内存里的瞬时状态。代价是表达力受限，复杂判定要拆成现有 ValidatorSpec 变体的组合，或者退到 Command 变体调用外部程序；这个取舍在思考题 1 里继续追问。

10.1.2 声明层：Validator 与三层语义

声明写进 ValidationPolicy（crates/octos-agent/src/workspace_policy.rs:115），它同时容纳旧式字符串校验与类型化校验器两套写法：

#![allow(unused)]
fn main() {
/// Tiered validation checks run at different points in the turn lifecycle.
#[derive(Clone, Debug, Default, PartialEq, Serialize, Deserialize)]
pub struct ValidationPolicy {
    /// Tier 1: cheap checks run every turn (< 100ms). e.g. file_exists, build exit code.
    #[serde(default)]
    pub on_turn_end: Vec<String>,
    /// Tier 2: medium checks run when source files change (1-5s). e.g. preview render.
    #[serde(default)]
    pub on_source_change: Vec<String>,
    /// Tier 3: expensive checks run on completion/publish only (10-30s). e.g. Playwright.
    #[serde(default)]
    pub on_completion: Vec<String>,
    /// Typed declarative validators (M4.3). Runs via `ValidatorRunner`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub validators: Vec<Validator>,
}
}

前三行是按成本分层的字符串校验（每轮跑、源码变了跑、完成时才跑），第四行的 Vec<Validator> 才是 harness 主推的类型化形态。每个 Validator（crates/octos-agent/src/workspace_policy.rs:143）有稳定 id、超时与运行相位，正文 spec 是一个按 kind 标注的枚举 ValidatorSpec（crates/octos-agent/src/workspace_policy.rs:301），从跑子进程、调工具、查文件存在，到 HTTP 探测、SHA-256 比对、音频非静音检测逐级扩展。

最有设计感的是失败语义。历史上只有布尔 required：true 失败即拦，false 仅告警。Wave-3a 引入 soft_fail 后，两个字段坍缩成三档 Required（crates/octos-agent/src/workspace_policy.rs:198）：

#![allow(unused)]
fn main() {
    pub fn tier(&self) -> Required {
        if self.soft_fail {
            Required::Soft
        } else if self.required {
            Required::Hard
        } else {
            Required::None
        }
    }
}

Hard 失败阻止 spawn 任务到达终态成功；Soft 失败只留台账与告警，用于「主产物必须交付、副产物尽力而为」的部分交付契约；None 的门禁行为与 Soft 相同，但台账里明确标注「仅供参考」。旧布尔字段原样保留以兼容旧策略文件，新旧两套字段由这一个函数收拢。声明式设计让这种平滑迁移成为可能。

三档的判据写在 Required 枚举（crates/octos-agent/src/workspace_policy.rs:198）的文档注释里，两个辅助方法把语义钉死：is_hard() 决定非 Pass 结果是否把 spawn 任务降级为 Failed，只有 Hard 为真；is_warning_only() 决定是否仅告警，Soft 与 None 都是。运维上这意味着 dashboard 可以按台账里的 tier 标签把失败切成三类：hard 失败要立刻处理，soft 失败要看副产物是否影响下游，none 失败纯属信息。选档的实用判据是问一句「这个校验不过，交付物还能用吗」：主产物文件存在性选 Hard，预览文件、附加报告选 Soft，风格类检查选 None。as_str() 输出的稳定标签（hard/soft/none）直接进指标与台账记录，运维面板不需要理解 Rust 枚举就能过滤。

10.1.3 执行层：ValidatorRunner 的五步时序

执行层的核心是 ValidatorRunner（crates/octos-agent/src/validators.rs:441）。它的构造函数本身就是一份安全清单：证据默认落在 <workspace_root>/.octos/validator-evidence/（常量 EVIDENCE_SUBDIR 定义在 crates/octos-agent/src/validators.rs:46），命令策略默认 SafePolicy，台账与沙箱可选挂载。工具调度被抽成 ValidatorToolDispatcher trait（crates/octos-agent/src/validators.rs:367）：生产路径绑定完整的 ToolRegistry，测试与短生命周期调用点用 MapToolDispatcher 只快照需要的几个工具，不必为构造 runner 克隆整个注册表。一批校验器共享的上下文是 ValidatorInvocation（crates/octos-agent/src/validators.rs:167），携带工作区根、仓库标签、运行相位（ValidatorPhase，crates/octos-agent/src/validators.rs:105，分 turn_end 与 completion 两档）以及可选的 spawn 任务输入与工具输出。run_all 一次跑完整批并按声明顺序返回结果，单条命令校验器的处理流程是：

sequenceDiagram
    participant P as WorkspacePolicy
    participant R as ValidatorRunner
    participant S as SafePolicy
    participant C as 子进程
    participant L as ValidatorLedger
    P->>R: run_all(invocation, validators)
    loop 每个 Validator
        R->>R: interpolate_template 解析 ${args.X}/${output.X}
        R->>S: policy.check(command_string, workspace_root)
        alt Deny / Ask
            R->>R: error_outcome（fail closed）
        else Allow
            R->>C: 启动（超时 SIGTERM→SIGKILL）
            C-->>R: exit code / stdout / stderr
        end
        R->>R: 组装 ValidatorOutcome（含 evidence 路径与时长）
        R->>L: ledger.append(outcome)
    end
    R-->>P: Vec<ValidatorOutcome>

这张时序图的每一步都能在 ValidatorRunner 的方法里找到落点。五个关键步骤如下。模板插值在 crates/octos-agent/src/validators.rs:677-696：${args.<key>} 取自 spawn 任务输入 JSON，${output.<key>} 取自工具产出的 named_outputs（如 mofa_publish 的 deploy_url），这让「校验刚发布的 URL 可达」成为一等公民；缺 key 直接产出 Error。安全闸门在 crates/octos-agent/src/validators.rs:719-734：SafePolicy 判 Deny 或 Ask 都按 Error 处理，宁可误拦不可放行。执行与超时杀进程（Unix 走 SIGTERM 转 SIGKILL，Windows 走 taskkill /F /T）对应 run_command（crates/octos-agent/src/validators.rs:661）。结果类型 ValidatorOutcome（crates/octos-agent/src/validators.rs:236）带 schema_version、时长、证据路径与 stderr 尾部，信息量刚好够事后审计。落账由 ValidatorLedger.append（crates/octos-agent/src/validators.rs:321）完成，一行一条 JSON。

台账是 append-only 的：ValidatorLedger（crates/octos-agent/src/validators.rs:298）只提供 append 与 read_all 两个动作，后者逐行反序列化并顺手把 Wave-3a 之前的旧记录归一化成新 tier 语义。契约测试 should_persist_outcomes_and_replay_them_byte_for_byte（crates/octos-agent/tests/validator_runner.rs:490）验证的就是「写进去什么样、重读回来就什么样」。回放不靠日志考古，靠结构化记录。

17 个用例的 crates/octos-agent/tests/validator_runner.rs 把这张时序图的每条边都钉住了：required 命令校验失败要拦（crates/octos-agent/tests/validator_runner.rs:123）、optional 失败只告警（:218）、超时杀子进程（:329）、stderr 进结果供操作员查看（:293）、BLOCKED_ENV_VARS 即便显式设置也被剥掉（:531）。

工程决策：为什么超时与拒答都算 Error 而不是 Fail ValidatorStatus（crates/octos-agent/src/validators.rs:131）把终态分为 Pass / Fail / Timeout / Error 四档：Fail 表示「校验跑完了、结论是不合格」，Timeout 与 Error 表示「校验根本没跑成」。这个区分对门禁语义至关重要:产物不合格可以打回让 Agent 修，而策略拒绝或环境损坏时「打回」只会让 Agent 对着坏环境空转。消费方（如 Ch16 的门禁）只需要看 required && status != Pass 这一个条件，四种终态就能各归其位。

10.1.4 工作区策略：一张 TOML 驱动全部

WorkspacePolicy（crates/octos-agent/src/workspace_policy.rs:22）是声明层的总纲：工作区类型、版本控制、追踪、校验、产物、spawn 任务、压缩策略七个段。其中 CompactionPolicy（crates/octos-agent/src/workspace_policy.rs:51）声明压缩的形状,包括目标 token 预算、必须存活的产物与不变量、摘要器风味（CompactionSummarizerKind，crates/octos-agent/src/workspace_policy.rs:104，可选 Extractive 或 LlmIterative）、preflight 阈值、旧工具结果的修剪轮数。缺席时运行时退回旧抽取式路径，行为与 M6.3 之前逐字节一致。「缺省即旧行为」是 harness 各模块共享的兼容哲学（压缩的运行时消费详见第 8 章）。

WorkspacePolicy 的读取端同样受版本护栏保护：文件里的 schema_version 缺席时按 v1 反序列化，超出编译进 runtime 的上限则整体拒绝，细节在 10.3 节。四个 starter 的 workspace-policy.toml 是这套声明的最小可运行样本，10.5 节走读。

10.2 支柱二：事件 ABI：运行中说了什么

10.2.1 octos.harness.event.v1 信封

第一支柱回答终点判定，第二支柱回答过程叙事：运行中都发生了什么、外部组件如何听到。这份需求落在 crates/octos-agent/src/harness_events.rs（2,789 行，六模块中最大）。所有事件共用一个信封：

#![allow(unused)]
fn main() {
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
pub struct HarnessEvent {
    pub schema: String,
    #[serde(flatten)]
    pub payload: HarnessEventPayload,
}
}

schema 字段恒为常量 HARNESS_EVENT_SCHEMA_V1（crates/octos-agent/src/harness_events.rs:29），值是字符串 octos.harness.event.v1,这是消费者应当分支判断的稳定标识。载荷 HarnessEventPayload（crates/octos-agent/src/harness_events.rs:368）以 kind 标注、按 snake_case 命名，是十几种事件的tagged union：Progress、Phase、Artifact、ValidatorResult、Retry、Failure、McpServerCall、SubAgentDispatch、SwarmDispatch、SwarmReviewDecision、CostAttribution、RoutingDecision、CredentialRotation、SessionSanitized、SubagentProgress、Error。第 13 章的 pipeline 进度事件与第 17 章的 swarm 门禁都会以这套词汇表为共享语言，本章先立词汇。

以最常用的 HarnessProgressEvent（crates/octos-agent/src/harness_events.rs:461）为例，它自带 schema_version、session_id、task_id、phase 与可选 message，还有一个 progress_fraction 的别名兼容字段:老生产者写 progress_fraction、新消费者读 fraction，serde alias 一行解决，不需要 bump 大版本。

10.2.2 本地 sink 传输

事件的传递通道是本地 JSONL 文件：外部 app skill 进程把单行事件写进 OCTOS_EVENT_SINK 指向的文件，runtime 校验 schema 后 tail 并折叠进任务快照，再向 /api/events/harness 广播类型化帧。这条 side-channel 与 stdout 工具结果协议分离：stdout 回答「工具返回了什么」，sink 回答「运行中发生了什么」。所以同一个 app skill 进程有两类输出通道，职责不混。这条通道上还有两道防线：事件写入前先做 schema 校验，单行超过大小上限的记录整条拒绝，脏数据进不了流；关联上下文由环境变量注入，OCTOS_SESSION_ID 与 OCTOS_TASK_ID（以及等价的 OCTOS_HARNESS_SESSION_ID / OCTOS_HARNESS_TASK_ID）让每条事件都能归到具体会话与任务，事后审计不用猜来源。对第 16 章的 fleet 门禁与第 17 章的 swarm 聚合而言，这套按任务归集事件的能力就是它们消费数据的地基，本章只立契约，不展开消费侧。

错误也有专属事件形态：HarnessErrorEvent（crates/octos-agent/src/harness_errors.rs:166）作为 kind: "error" 挂在同一个信封下，携带 snake_case 的变体标识与恢复提示，schema 版本常量 HARNESS_ERROR_SCHEMA_VERSION 注册在 abi_schema。契约测试 should_round_trip_harness_error_through_sink（crates/octos-agent/tests/harness_errors.rs:154）验证错误事件经 sink 写入再读回不变形；should_emit_harness_event_on_error_classification（:126）验证每次错误分类都产生事件。错误分类学本身（RecoveryHint crates/octos-agent/src/harness_errors.rs:47 与 HarnessError crates/octos-agent/src/harness_errors.rs:93 的五提示十数变体）第 5 章已随恢复链讲透，本章只强调两点。其一，错误分类与事件 ABI 的关系是「分类决定事件载荷」：variant_name() 是冻结的命名，事件消费者据此做确定性分支，不碰自然语言 message。其二，分类的粒度是为可观测性设计的：RecoveryHint 只有五个值（backoff_retry、switch_provider、compact_context、fail_fast、bug），可以直接当 Prometheus 标签用而不会基数爆炸；HarnessError 的变体则细到能区分「401 认证失败」与「403 配额耗尽」这两种 4xx 的情况，让操作员看到的提示分别是「检查 API key」与「充值或换供应商」。18 个用例的 crates/octos-agent/src/harness_errors.rs 把这套映射钉得很实：429 归 RateLimited 配 BackoffRetry（crates/octos-agent/tests/harness_errors.rs:26），5xx 归 ProviderUnavailable 配 SwitchProvider（:58），网络错误归 BackoffRetry（:77），同样的输入永远分到同样的变体（:110），403 带 quota 标记归 Quota、不带归 Authentication（:248、:271）。同一分类经 eyre 中转也不失真（:280），这是把分类放进类型而不放进出错现场的回报。

10.3 支柱三：schema 版本化：不同版本还能互相听懂

10.3.1 五个耐久类型与 check_supported

声明会被存档，事件会被回放，于是第三个问题出现了：跨了版本的组件还能不能听懂彼此？这是第三支柱 crates/octos-agent/src/abi_schema.rs 的领地。harness 对外暴露五个耐久序列化类型：WorkspacePolicy、HookPayload、ProgressEvent（发出形状）、TaskResult、SessionSummary。crates/octos-agent/src/abi_schema.rs 为每个类型集中维护版本常量，全部当前值为 1。这 349 行的小模块只干一件事：版本护栏。核心函数只有九行（crates/octos-agent/src/abi_schema.rs:159）：

#![allow(unused)]
fn main() {
pub fn check_supported(
    kind: &'static str,
    found: u32,
    supported: u32,
) -> Result<(), UnsupportedSchemaVersionError> {
    if found > supported {
        Err(UnsupportedSchemaVersionError {
            kind,
            found,
            supported,
        })
    } else {
        Ok(())
    }
}
}

规则是单向的：found <= supported 一律放行（旧版本靠缺省字段保持可读），found > supported 拒绝并返回类型化错误 UnsupportedSchemaVersionError（crates/octos-agent/src/abi_schema.rs:135），其 Display 消息固定含类型名、实际版本与支持上限，并提示「升级 octos 到更新版本」。不是 panic，不是静默截断。调用方可以记日志、向操作员呈现可行动的错误，或退回安全缺省。

10.3.2 版本协商决策流

flowchart TD
    A[反序列化载荷] --> B{schema_version 字段存在?}
    B -- 缺席 --> C[按 v1 处理<br/>serde default 补值]
    B -- 存在 --> D{found 与编译进<br/>runtime 的 supported 比较}
    D -- "found ≤ supported" --> E[正常读取<br/>未知新字段忽略]
    D -- "found > supported" --> F[UnsupportedSchemaVersionError<br/>fail closed]
    F --> G[操作员看到: 类型/实读/上限<br/>+ 升级提示]

为什么这扇门只朝一个方向关？「旧 runtime 读新 payload」与「新 runtime 读旧 payload」的风险天然不对称：旧数据缺的只是新字段，serde 缺省值补零即可安全读出，读到的语义是「老形状」，正确；而旧 runtime 遇上新 payload，新字段可能是旧代码无法理解的语义变更（比如一个字段从单值变成列表），任何「尽力解析」都是在猜，猜错的代价是静默错读。工程权衡因此落在保守侧：宁可让操作员看到一条带类型名、实读版本与支持上限的报错并升级 octos，也不让坏数据无声流过整条管线。这也是 check_supported 的错误消息固定附带「upgrade octos to a newer release」提示的原因（crates/octos-agent/src/abi_schema.rs:144-151 的 Display 实现）：fail closed 的报错必须同时给出解法，否则只是把故障换个形态。反向的「新读旧」则交给缺省值：五个耐久类型的 schema_version 字段全部用 #[serde(default = "...")] 标注，2026 年 4 月前的旧策略文件零改动继续加载，升级 octos 不需要迁移仪式。

这套语义与 docs/OCTOS_HARNESS_ABI_VERSIONING.md 的五条兼容规则逐条对应：缺 schema_version 按 v1 反序列化；未知大版本用类型化错误拒绝、绝不 panic；同一大版本内 stable 字段含义不变，新增可选字段必须缺省为空；破坏性变更必须 bump 大版本并留双版本过渡窗口；外部消费者应先分支 schema_version 再读版本特定字段。三条护栏中「缺字段默认 v1」让 2026 年 4 月之前的旧策略文件今天照常加载；「超上限拒绝」保证旧 runtime 不会错读未来 payload。should_reject_future_workspace_policy_schema_version（crates/octos-agent/tests/abi_compat.rs:259）与 should_default_workspace_policy_to_v1_when_schema_version_missing（:197）把两条各钉一钉。13 个用例的 crates/octos-agent/tests/abi_compat.rs 用 fixture 文件驱动，覆盖四个耐久类型的新旧两端。

版本化的对象是 runtime 序列化形状，不是 skill/plugin 自己的发布版本（那是 manifest.json 的 version 字段），第 9 章曾区分过这两个概念，本章是它的执行机制。

10.4 两翼：hooks 生命周期与沙箱交叉

10.4.1 十一个生命周期点

hooks 的会话上下文由 HookContext（crates/octos-agent/src/hooks.rs:24）携带，只有 session_id 与 profile_id 两个可选字段，由 gateway 在 Agent Loop 启动前注入；它让同一份 hook 配置在不同会话里能区分自己服务的是谁，也是 10.4.2 节会话隔离状态键的来源。HookEvent（crates/octos-agent/src/hooks.rs:32）枚举了十一个可挂载点：user_prompt_submit、before/after_tool_call、before/after_llm_call、on_resume、on_turn_end，外加 spawn 验证前后与完成/失败四点。每个 HookConfig（crates/octos-agent/src/hooks.rs:77）声明触发事件、argv 数组（不经 shell 解释）、超时（默认 5000ms）、可选的 tool_filter、path_filter glob（如把 cargo check 限定在 **/*.rs 编辑之后）与 requires_bin（二进制不在 PATH 就静默跳过，不强迫操作员装齐所有 linter）。

载荷 HookPayload（crates/octos-agent/src/hooks.rs:123）自带 schema_version 与事件、工具名、参数、时长、模型、迭代数等上下文；集成方可实现 HookPayloadEnricher（crates/octos-agent/src/hooks.rs:671）注入领域数据。执行结果是六态 HookResult（crates/octos-agent/src/hooks.rs:679）：Allow、Deny、Modified、Context、Error、Feedback。

其中 Feedback 最能体现设计取舍：after-hook 以 exit 1 且有输出退出时，那是反馈通道在正常工作：检查器在报告诊断，应注入模型会话；而缺二进制、超时、exit >= 2 属于基础设施故障 Error，绝不能混进模型上下文，否则 Agent 会把「hook 坏了」当成「代码有错」去修。提交 9ebaf468 与 fb0f9eeb 接通的编码反馈回路正是这条：after_tool_call 钩子把 cargo check 的编译错误作为 Feedback 喂回模型，形成「编辑→检查→修正」的循环，且按配置顺序逐条保留，后来的失败钩子不能覆盖编码缺省钩子的编译错误（#2129 评审第 8、9 条）。

10.4.2 断路器与会话隔离

HookExecutor 内建断路器：连续失败达到阈值即停用该钩子，避免一条坏 hook 拖垮每个 turn。值得记录的是 #2153 修复。断路器与去抖状态原先是执行器全局一份，Arc<HookExecutor> 跨所有会话共享时，一个工作区的基础设施故障会向全体会话计数。修复后状态按 session key 隔离（crates/octos-agent/src/hooks.rs:716 起），一个会话的熔断不再波及邻居；after 事件去抖窗口同理，一轮多次 edit_file 只付一次全项目 cargo check。

10.4.3 与第 7 章的安全交叉

harness 的可编程性天然带风险：workspace 里的 .octos-workspace.toml 是不可信输入，它声明的命令校验器不能裸跑在宿主机上。b64bd532 与 bf6be8cc 由此把 project-root 校验器收进沙箱，mcp-serve 路径 fail-closed（Windows 上无安全 argv 包装方案时宁可报错也不绕过沙箱，crates/octos-agent/src/validators.rs:735-749 的注释把这条决策写得很清楚）。沙箱机制本身是第 7 章的内容，此处不展开。

10.5 四个 starter：面向用户的脚手架

crates/app-skills/ 下有四个 harness starter：harness-starter-audio、harness-starter-coding、harness-starter-generic、harness-starter-report，目录结构完全一致，都是 Cargo.toml、manifest.json、SKILL.md、src/、tests/、workspace-policy.toml 六件套。它们不是参考实现意义上的玩具，而是把本章全部概念装配成可复制起点的模板：manifest 声明工具与并发类，workspace-policy 声明产物与校验，tests 里的 smoke test 则核对这两份声明没有说谎。

以 harness-starter-coding 走读。manifest.json 声明一个 spawn_only 的 propose_patch 工具，把补丁渲染成 patches/<slug>.diff 统一差分文件,外加一份 patches/<slug>.files.txt 预览清单，concurrency_class = "exclusive" 防止并发写冲突。workspace-policy.toml 则是 10.1 节声明的直接样本：

[validation]
on_turn_end = []
on_source_change = []
on_completion = ["file_exists:patches/*.diff"]

[artifacts]
primary = "patches/*.diff"
preview = "patches/*.files.txt"

[spawn_tasks.propose_patch]
artifacts = ["primary", "preview"]
on_verify = [
    "file_exists:$primary",
    "file_size_min:$primary:64",
    "file_exists:$preview",
]

注意 $primary 引用：产物声明与校验规则解耦，改名产物只动一处。这个 TOML 还展示了字符串校验的三层结构如何与 WorkspacePolicy 的段一一对应：[validation] 是校验层，[artifacts] 是产物层，[spawn_tasks.*] 把两者装配成任务契约，on_verify / on_deliver / on_failure 分别挂在验证、交付、失败三个时点。file_size_min 64 字节堵住「零字节 diff 也算交付」的漏洞。空补丁文本恰好过 file_exists，但过不了大小下限。字符串校验（on_completion）与类型化 validators 两轨在此并存，新代码建议走后者。

其余三个 starter 各占一段：harness-starter-audio 展示独占资源契约：synthesize_clip 写 audio/<slug>.wav 必须声明 exclusive 并发类，primary 产物配 file_size_min 4096 字节的下限校验；harness-starter-report 是最小报告契约:reports/*.md 主产物、completion file_exists、failure 时 notify_user；harness-starter-generic 则是剥掉领域细节的空白模板，适合作为新 app skill 的起点。写新 app skill 时应把这四个目录当工程清单逐项核对：manifest 声明、并发类、产物契约、校验门禁、失败通知，一项不缺再动手写业务代码。

从用户视角看，starter 的价值在于把本章机制收敛成「复制目录、改两份声明文件」的动手路径：manifest.json 描述工具长什么样（输入 schema、并发类、超时），workspace-policy.toml 描述产出怎么算数（产物模式、校验规则、失败通知），src/ 里的业务代码只管干活，不需要知道 ValidatorRunner 或事件信封的存在。四份 workspace-policy.toml 放在一起读还能看出契约松紧的梯度：coding 的 file_size_min:$primary:64 是字节级下限，audio 提到 4096 因为 WAV 头本身就不小，report 只用 file_exists 因为 Markdown 报告的合理大小无法预判，generic 则留空让用户自己填。同一个机制，四种松紧，全靠声明层的数据调整，一行 runner 代码不用改，这正是 10.1.1 节「校验是数据不是代码」在用户侧的兑现。

10.6 本章回顾

1. 事实澄清：不存在 harness crate。harness 是 octos-agent 内六模块（validators 2,772 行、harness_events 2,789 行、abi_schema 349 行、workspace_policy 3,165 行、harness_errors 745 行、hooks 2,856 行，合计 12,676 行）加 crates/app-skills/harness-starter-* 四个 starter。

2. 三支柱：workspace_policy 声明什么算完成，validators 执行判定并产出可回放台账，harness_events + abi_schema 让判定过程与结果跨版本可读。hooks 与 harness_errors 是两翼，starter 是面向用户的脚手架。

3. 声明式校验：校验器是数据不是代码，换来可序列化、可沙箱、可回放三重工程收益；Required 三档（Hard/Soft/None）收拢新旧字段，Soft 支持部分交付契约。

4. 事件 ABI：octos.harness.event.v1 信封 + kind 标注的载荷枚举，本地 JSONL sink 传输，validate 后入流；第 13 章 pipeline 进度与第 17 章 swarm 门禁共用这套词汇。

5. 版本护栏：五个耐久类型、check_supported 九行核心、缺字段默认 v1、超上限 fail closed；crates/octos-agent/tests/abi_compat.rs 13 用例钉住两端。

6. hooks 与安全：十一个生命周期点、六态结果、Feedback 与 Error 严格分流；断路器按会话隔离（#2153）；project-root 校验器进沙箱、mcp-serve fail-closed（详见第 7 章）。

第 10 章是第二部分的收官：从第 5 章的一次对话生命周期，到第 6 章的工具、第 7 章的安全、第 8 章的上下文、第 9 章的扩展，再到本章的可验证契约，Agent 引擎的内部机制到此完整。第三部分从单机会话走向消息总线与多会话编排，harness 埋下的事件词汇会在那里被大量复用。

延伸阅读

• docs/OCTOS_HARNESS_DEVELOPER_GUIDE.md：harness 开发者指南，外部 skill 作者的入口文档
• docs/OCTOS_HARNESS_ABI_VERSIONING.md：ABI 版本化契约，stable/experimental 字段清单与废弃规则（M4.6）
• docs/OCTOS_HARNESS_MASTER_PLAN.md：harness 总体规划，三阶段（后台任务信任 / Web 持久化与重载可靠性 / 自由编码与更丰富运行时）的路线图
• docs/OCTOS_HARNESS_DEVELOPER_INTERFACE.md：开发者接口约定
• docs/OCTOS_HARNESS_SKILL_COMPAT.md：skill 兼容性说明

思考题

1. 声明式的边界：如果你的校验需要「跑一段领域特定的判定程序」（比如解析内部格式再断言结构），你会扩展 ValidatorSpec 加一个新变体，还是退回 Command 校验器调外部程序？两种做法在沙箱、超时、证据留存上的差异是什么？

2. Soft 契约的滑坡：soft_fail 让部分交付成为合法终态。如果团队里每个 validator 都被「顺手」标成 soft，harness 的门禁价值还剩多少？你会用什么机制（评审规则、策略 lint、台账审计）防止这种滑坡？

3. 版本护栏的单向门：check_supported 只拒未来版本、不拒过去版本。假如某天 v2 需要删除一个 v1 的 stable 字段（而不是新增），缺省值策略还能兜住吗？双版本过渡窗口应该怎么设计，才能让 v1 生产者与 v2 消费者共存一个发布周期？

版本演化说明 本章基于 octos main @ 9c157101（2026-09-03 核对）。行号与代码摘录以该 commit 为准；后续阅读时优先复核 crates/octos-agent/src/{validators,harness_events,abi_schema,workspace_policy,harness_errors,hooks}.rs 与 crates/app-skills/harness-starter-*/。里程碑编号（M4.3/M4.6/M6.1/M6.3/M6.5/M6.6/M7.6/M8.6/M8.7）沿用源码注释与 docs/OCTOS_HARNESS_MASTER_PLAN.md 的阶段划分。

第 11 章：octos-bus：消息总线、频道抽象与会话持久化

定位：本章深入 octos-bus crate（当前 crates/octos-bus/ 约 40K 行 Rust 源文件（实测 40,937 行，其中 17 个频道文件 18,207 行）），展示如何用 Channel trait 抽象统一多种消息频道，以及会话管理、消息分片、thread-bound streaming、durable commit observer 和 child-session contract 的工程实现。前置依赖：第 5 章。适用场景：想理解多频道消息平台架构的开发者（读者 B），以及需要接入新频道的贡献者（读者 D）。

当 Agent 从单用户 CLI 走向多用户平台时，消息接入层的复杂度急剧上升。Telegram 的消息长度限制是 4,000 字符，Discord 是 1,900；Slack 用 Block Kit 格式化消息，飞书用 Rich Text；邮件是异步的，WhatsApp 需要模板消息。octos-bus 用一个 Channel trait 统一了这些差异。

11.1 Channel trait：统一消息接口

Channel trait（crates/octos-bus/src/channel.rs:17-265）定义了所有频道的统一接口：

当前版本的 Channel trait 一共有 26 个方法，但真正没有默认实现的只有 3 个：name()、start()、send()。其余能力都以默认实现挂在 trait 上，真实频道按需覆盖：

#![allow(unused)]
fn main() {
#[async_trait]
pub trait Channel: Send + Sync {
    fn name(&self) -> &str;
    async fn start(&self, inbound_tx: mpsc::Sender<InboundMessage>) -> Result<()>;
    async fn send(&self, msg: &OutboundMessage) -> Result<()>;
    fn max_message_length(&self) -> usize;  // 默认 4000，可覆盖
    fn is_allowed(&self, _sender_id: &str) -> bool { true }
    async fn send_typing(&self, _chat_id: &str) -> Result<()> { Ok(()) }
    fn supports_edit(&self) -> bool { false }
    async fn send_with_id(&self, msg: &OutboundMessage) -> Result<Option<String>> { ... }
    async fn edit_message(&self, ...) -> Result<()> { ... }
    async fn finish_stream(&self, ...) -> Result<()> { ... }
    async fn edit_message_bound(&self, ..., thread_id: Option<&str>) -> Result<()> { ... }
    async fn finish_stream_bound(&self, ..., thread_id: Option<&str>) -> Result<()> { ... }
    async fn send_raw_sse_bound(&self, ..., thread_id: Option<&str>) -> Result<()> { ... }
    async fn health_check(&self) -> Result<ChannelHealth> { ... }
    // + stop, send_typing_as, stop_typing, send_listening,
    //   delete_message, edit_message_with_metadata, reactions, embed, ...
}
}

这是一种典型的“大 trait + 多默认实现”设计：简单频道只实现 3 个基础方法就能工作；成熟频道则会继续覆盖 max_message_length()、supports_edit()、send_with_id()、edit_message()、format_outbound()、health_check() 等扩展点。这样做的代价是 trait 面会比较宽，但收益是所有平台能力都能通过一个统一抽象暴露给 Gateway。

关键方法：start() 接收一个 mpsc::Sender<InboundMessage>，频道将收到的用户消息通过这个 sender 发送给 Agent 处理层；send() 负责把 Agent 响应发送回目标频道；max_message_length() 虽然有默认值 4000，但 Discord、Slack、Twilio、WeCom 等真实实现都会覆盖它（例如 Discord=1900，Slack=3900，Twilio=1600）。

send_with_id() 返回消息 ID，支持后续编辑（流式输出场景下先发送占位消息，再逐步更新内容）。默认实现委托给 send() 并返回 None。

11.1.1 流式编辑三步法

对于支持消息编辑的频道（supports_edit() 返回 true），octos 使用三步法实现流式输出：

1. send_with_id()：发送初始消息（可能只有几个 token），返回平台消息 ID
2. edit_message()：随着 LLM 流式输出，不断更新同一条消息的内容（crates/octos-bus/src/channel.rs:85-93）
3. finish_stream()：流结束后发送最终版本；默认实现仍回退到 edit_message()（crates/octos-bus/src/channel.rs:122-133）

这种模式让用户看到 Agent 的回复逐渐生成，而不是等待完整响应后一次性显示。Telegram 和 Discord 都支持这种模式。对于不支持编辑的频道（如邮件），退回到等待完整响应后一次性发送。

11.1.2 thread-bound streaming：显式绑定 turn，而不是依赖 sticky map

当前 Channel trait 的流式编辑接口已经不只是一组“编辑消息”的便捷方法。它新增了三类带绑定参数的默认方法：

• edit_message_bound(chat_id, message_id, content, thread_id)
• finish_stream_bound(chat_id, message_id, content, thread_id)
• send_raw_sse_bound(chat_id, json, thread_id)

这些方法的核心不是多传一个字段，而是在并发 Web turn 下把每个流式增量、最终消息和历史 raw SSE 事件都显式绑定到 originating thread_id（crates/octos-bus/src/channel.rs:107-201）。旧路径会从 message id 解码或从 per-chat sticky map 里恢复 thread；当同一个 chat 连续快速发起多个 turn 时，sticky map 可能已经被后一个 turn 旋转，导致前一个 turn 的 late delta 被写进后一个气泡。bound API 的语义是：调用方已经知道这个增量属于哪个 turn，就不要再从共享状态里猜。

sequenceDiagram
    participant Turn as Web/API turn
    participant Reporter as Stream forwarder
    participant Channel as Channel bound API
    participant UI as Client thread bubble
    Turn->>Reporter: bind originating thread_id
    Reporter->>Channel: edit_message_bound(..., thread_id)
    Reporter->>Channel: send_raw_sse_bound(..., thread_id)
    Channel->>UI: update exact thread bubble

默认实现仍会退回旧的 edit_message() / send_raw_sse()，所以 Telegram、Discord 等不关心 thread 的频道保持兼容；历史 API channel 可以覆盖 bound 方法，把事件稳定落到正确的 UI thread。这里需要和第 13、14 章区分：当前 Serve/AppUI 的公开 chat transport 已经迁到 /api/ui-protocol/ws，send_raw_sse_bound() 是 bus trait 中保留的兼容/内部扩展点，不代表新客户端还应该使用 chat SSE。health_check() 也是同一轮演进的一部分：它让 admin dashboard 可以以统一方式展示频道健康状态，而不是把健康探测散落到每个频道自己的管理接口里（crates/octos-bus/src/channel.rs:245-251；ChannelHealth 枚举在同文件 253-265）。

11.1.3 AgentHandle 对称设计

消息总线使用 AgentHandle / BusPublisher（crates/octos-bus/src/bus.rs:8-77）连接频道和 Agent 处理层：

#![allow(unused)]
fn main() {
// AgentHandle 包含双向通道
struct AgentHandle {
    in_rx: Receiver<InboundMessage>,      // Agent 从这里接收消息
    out_tx: Sender<OutboundMessage>,      // Agent 从这里发送响应
}

struct BusPublisher {
    in_tx: Sender<InboundMessage>,         // 频道从这里发送消息给 Agent
    out_rx: Receiver<OutboundMessage>,     // 频道从这里接收 Agent 响应
}
}

这种对称设计的优势是：当所有 Channel 关闭时（所有 inbound_tx 被 drop），inbound_rx.recv() 返回 None，Agent 处理层自动感知到没有更多消息，可以优雅退出。不需要额外的 shutdown 信号。

11.1.4 is_allowed：发送者鉴权

is_allowed()（crates/octos-bus/src/channel.rs:27-30）在消息路由到 Agent 之前检查发送者是否有权使用 Agent。默认实现返回 true（允许所有人），各频道可以覆盖实现自定义鉴权逻辑，例如 Telegram 可以限制只有特定 chat_id 的用户才能访问。

11.2 消息 Coalescing：5 级切割策略

当 Agent 的回复超过频道的字符限制时，需要将长消息分割为多个短消息。octos-bus 的 coalescing 算法（crates/octos-bus/src/coalesce.rs:26-120）按 5 个优先级尝试切割：

flowchart TD
    Input["长消息"] --> P1["1. 段落分割 \\n\\n"]
    P1 -->|"找到"| Emit1["发送段落"]
    P1 -->|"未找到"| P2["2. 换行分割 \\n"]
    P2 -->|"找到"| Emit2["发送行"]
    P2 -->|"未找到"| P3["3. 句子分割 . + 空格"]
    P3 -->|"找到"| Emit3["发送句子"]
    P3 -->|"未找到"| P4["4. 空格分割"]
    P4 -->|"找到"| Emit4["发送词组"]
    P4 -->|"未找到"| P5["5. 硬切<br/>UTF-8 安全边界"]
    P5 --> Emit5["发送截断块"]

图 10-1：5 级消息切割策略。 优先在语义边界切割，硬切是最后手段。

MAX_CHUNKS = 50：防止极长消息被分割为数百个小消息导致 DoS。超过上限时，代码不会继续在最后一块后面追加文本，而是单独插入一个 "[message truncated - N chars omitted]" 的截断块（crates/octos-bus/src/coalesce.rs:47（MAX_CHUNKS 常量在同文件 27 行，截断时打 warn! 日志））。

UTF-8 安全：硬切时使用 is_char_boundary() 回退到安全的字符边界（与 octos-core 的 truncate_utf8 使用相同的策略，详见第 2 章）。

平台特定限制（crates/octos-bus/src/coalesce.rs:5-24）：

11.2.1 find_break_point：核心分割逻辑

find_break_point()（crates/octos-bus/src/coalesce.rs:87-118）是切割的核心,但真正的切割过程分两步：先在 max_chars 以内找一个 UTF-8 安全的搜索窗口，再在这个窗口内寻找最自然的断点。

#![allow(unused)]
fn main() {
let mut limit = config.max_chars.min(remaining.len());
while limit > 0 && !remaining.is_char_boundary(limit) {
    limit -= 1;
}
let search = &remaining[..limit];
let break_at = find_break_point(search);

chunks.push(remaining[..break_at].trim_end().to_string());
remaining = remaining[break_at..].trim_start_matches('\n');
if remaining.starts_with(' ') && !remaining.starts_with("  ") {
    remaining = &remaining[1..];
}
}

find_break_point(search) 内部依次对 \n\n、\n、. 、空格做 rfind()（从右向左搜索），只有完全找不到自然边界时才硬切。这保证断点尽量靠近上限，同时避免把多字节字符切坏。trim_end()、trim_start_matches('\n') 和“最多跳过一个前导空格”的小处理，则让最终发出去的块看起来更干净，不会把原始分隔符原样带到下一条消息开头。

11.3 Session 管理

11.3.1 Session 结构体

Session（crates/octos-bus/src/session.rs:587-608）是对话的持久化单元：

#![allow(unused)]
fn main() {
pub struct Session {
    pub key: SessionKey,               // 会话标识（channel:chat_id）
    pub parent_key: Option<SessionKey>, // fork 来源
    pub topic: Option<String>,          // 多主题支持
    pub title: Option<String>,          // 侧边栏标题
    pub title_manual: bool,             // 手动标题不被自动覆盖
    pub child_contracts: Vec<ChildSessionContract>,
    pub messages: Vec<Message>,         // 对话历史
    pub summary: Option<String>,        // 会话摘要
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
}
}

11.3.2 JSONL 持久化与文件命名

当前源码的 Session 持久化比“一个 JSONL 文件”稍复杂一些，核心有两个事实。

第一，JSONL 文件的第一行不是消息，而是 SessionMeta 元数据，后续每一行才是 Message（crates/octos-bus/src/session.rs:560-584、crates/octos-bus/src/session.rs:1365-1381、crates/octos-bus/src/session.rs:2992-3060）。所以它不是“纯消息流”，而是“头一行 schema/meta + 后续消息行”的轻量日志格式。SessionMeta 现在也承载 title、title_manual 与 child_contracts，这使侧边栏标题和后台子任务状态不必塞进普通消息文本。

第二，当前代码同时支持旧布局和新布局：

1. SessionManager 仍支持 legacy flat layout：data/sessions/{encoded-key}[_{hash}]?.jsonl（crates/octos-bus/src/session.rs:1096-1146）
2. SessionActor 使用的 SessionHandle 优先采用 per-user layout：data/users/{encoded_base_key}/sessions/{topic_or_default}.jsonl，并在打开时自动迁移旧文件（crates/octos-bus/src/session.rs:1611-1819）

只有在 legacy flat 布局里，文件名才由下面这两部分构成：

1. Percent-encoded SessionKey（crates/octos-bus/src/session.rs:129-140）：将 SessionKey 中的路径不安全字符（/、:、#）编码为 %2F、%3A、%23
2. FNV-1a 64-bit hash 后缀（crates/octos-bus/src/session.rs:116-127、crates/octos-bus/src/session.rs:1554-1610）：当编码后的名字过长、需要截断时，追加稳定哈希，避免“截断后同名前缀”碰撞

例如，旧布局中的长 key 可能落成 telegram%3A12345_0123ABCD....jsonl；而新布局则更像 users/telegram%3A12345/sessions/default.jsonl。

Schema 版本：CURRENT_SESSION_SCHEMA = 1（crates/octos-bus/src/session.rs:15-16），为未来格式迁移预留。

写入也分两类：

• 日常追加消息走 append_to_disk()，新文件先写 metadata，再逐条 append message 行（crates/octos-bus/src/session.rs:1312-1388、crates/octos-bus/src/session.rs:2992-3060）
• 需要重写整个会话时走 rewrite()，使用 write-then-rename 的原子替换模式（crates/octos-bus/src/session.rs:1914-1963、crates/octos-bus/src/session.rs:2862-2987）

当前 rewrite 的临时文件名也做了并发修正：rewrite_tmp_path() 使用进程 PID + 单调 counter 生成 {target}.jsonl.{pid}-{seq}.tmp，避免同一个父 session 被多个后台子任务同时 rewrite 时共享单一 .tmp 文件（crates/octos-bus/src/session.rs:90-117）。这不是性能优化，而是正确性修复：共享 temp path 会让两个 writer 互相截断，最后只有一个 rename 成功，另一个子任务可能被误标成 orphaned。

10MB 文件限制：单个会话文件最大 10MB，防止失控的对话历史耗尽磁盘（crates/octos-bus/src/session.rs:792-793、crates/octos-bus/src/session.rs:1197-1208、crates/octos-bus/src/session.rs:1644-1649）。

11.3.3 /new Fork 机制

用户发送 /new 命令创建新会话时，底层对应的是 fork(parent_key, new_chat_id, copy_messages)（crates/octos-bus/src/session.rs:1972-2010）。它不是“新建一个空白会话”，而是：

1. 从父会话复制最近 copy_messages 条消息
2. 记录 parent_key
3. 为新 key 重写一个新的 session 文件

这意味着 /new 在当前实现里更接近“带最近上下文的分支”，而不是“只继承配置、不带历史”。

11.3.4 SessionManager 与 LRU 缓存

SessionManager（crates/octos-bus/src/session.rs:903-905）管理 admin/命令侧看到的会话缓存；而真正在线处理消息时，SessionActor 会转而持有自己的 SessionHandle，避免所有活跃会话共用一个大锁（crates/octos-bus/src/session.rs:2426-2530）。

• LRU 内存缓存：活跃会话在内存中保持，减少磁盘 I/O
• 惰性加载：不活跃的会话按需从磁盘加载
• 布局兼容：同时扫描 legacy flat layout 和 per-user layout
• 用户列表性能边界：list_top_level_sessions*() 会跳过 child-* 与 *.tasks 等内部 topic，避免用户目录下大量后台子会话拖慢 /api/sessions（crates/octos-bus/src/session.rs:965-1005、crates/octos-bus/src/session.rs:934-947）
• 同 key 写入串行化：persist_message_through_canonical_path() 通过 per-key Tokio mutex 串行化 SessionActor、ApiChannel 与 /chat 路径的同 session 写入，避免多个独立 SessionHandle 同时看到相同长度并返回重复 sequence（crates/octos-bus/src/session.rs:2332-2420）

11.3.5 thread_id 持久化：新写入 fail closed，旧记录 load-time synthesis

AppUI 的聊天界面不再只是“一个 session 里顺序追加消息”，而是把消息分组成 thread。当前规则写在 derive_thread_id_for_new_write() 与 synthesize_thread_ids()（crates/octos-bus/src/session.rs:288（derive_thread_id_for_new_write）与 crates/octos-bus/src/session.rs:328（synthesize_thread_ids））：

这个分裂很重要。旧实现会在写 Assistant/Tool 时“回看最近一个 user”来推导 thread；在 rapid-fire 并发 turn 下，内存历史可能已经被另一个 sibling user 改写，导致 assistant 被归到错误气泡。新写入路径因此 fail closed：Assistant/Tool 没有预先绑定 thread_id 就返回错误，并打 octos_session_persist_total{outcome="rejected_unbound_assistant"} 指标（crates/octos-bus/src/session.rs:1676-1815、crates/octos-bus/src/session.rs:3061-3110）。

legacy JSONL 不能直接套用这个规则，因为历史文件本来没有 thread_id 字段。加载时的 synthesize_thread_ids() 只在内存里补齐旧记录，让旧 transcript 能按 thread 渲染；下一次新写入再进入 fail-closed 规则。也就是说，octos-bus 把“兼容历史数据”和“保护新写入正确性”拆成了两条路径。

11.3.6 durable commit observer：message/persisted 只在真正提交后发出

MessageCommitObserver 是 Session 层给 UI Protocol 的 durable commit hook（crates/octos-bus/src/session.rs:18-89）。add_message_with_seq() 的顺序是：

1. 必要时给 User 派生 thread_id，或要求 Assistant/Tool 已经预绑定。
2. 先 append_to_disk()，失败则直接返回。
3. 再更新内存 Session::messages。
4. 最后触发 observer，携带 SessionKey、Message 和 committed sequence。

flowchart TD
    Write["add_message_with_seq"] --> Stamp["stamp / validate thread_id"]
    Stamp --> Disk["append_to_disk"]
    Disk -->|fail| Err["return error<br/>no observer"]
    Disk -->|ok| Memory["push in-memory mirror"]
    Memory --> Observer["MessageCommitObserver"]
    Observer --> UI["UI Protocol message/persisted"]

observer 失败或 panic 不会回滚消息，因为 durable commit 已经完成；它只是 best-effort fan-out（crates/octos-bus/src/session.rs:71-89）。这条边界能避免一个常见错误：不要把 message/persisted 理解成“准备写入”，它表示“这一行已经 durable visible”。octos-cli 的 UI Protocol 测试也锁定了这个顺序和去重行为（crates/octos-cli/src/api/ui_protocol_ledger.rs 等 ui_protocol_{transport,ledger,progress,task_output,reasoning_effort,alpha2_bridge,alpha9_bridge}.rs 拆分文件家族（legacy message/persisted 记账在 crates/octos-cli/src/api/ui_protocol_ledger.rs:294-330，恢复期跳过在 1269-1423））。

11.3.7 child-session contract：后台子任务不是只靠消息文本追踪

Session metadata 还持久化 ChildSessionContract，用于把 background spawn / subagent 的生命周期回写到父 session（crates/octos-bus/src/session.rs:519-546、crates/octos-bus/src/session.rs:560-584）。它记录：

• task_id、task_label
• parent_session_key、child_session_key
• workflow_kind、current_phase
• terminal_state：Completed / RetryableFailure / TerminalFailure
• join_state：Joined / Orphaned
• failure_action：Retry / Escalate
• output_files

这说明 child session 不是“几条普通消息加一个 parent_key”就结束了。父 session 需要 durable contract 来判断后台任务是否完成、是否 joined、失败后应重试还是升级。这个 contract 也解释了为什么 rewrite temp path 必须唯一：多个子任务可能同时把 terminal outcome 写回同一个父 session metadata。

11.4 Coalescing 源码走读

让我们深入 split_message() 的完整实现（crates/octos-bus/src/coalesce.rs:34-82），理解它如何在安全性和可读性之间取得平衡：

#![allow(unused)]
fn main() {
pub fn split_message(text: &str, config: &ChunkConfig) -> Vec<String> {
    if text.len() <= config.max_chars {
        return if text.is_empty() { vec![] } else { vec![text.to_string()] };
    }

    let mut chunks = Vec::new();
    let mut remaining = text;

    while !remaining.is_empty() {
        if chunks.len() >= MAX_CHUNKS {
            chunks.push(format!(
                "[message truncated - {} chars omitted]",
                remaining.len()
            ));
            break;
        }

        if remaining.len() <= config.max_chars {
            chunks.push(remaining.to_string());
            break;
        }

        let mut limit = config.max_chars.min(remaining.len());
        while limit > 0 && !remaining.is_char_boundary(limit) {
            limit -= 1;
        }
        let search = &remaining[..limit];
        let break_at = find_break_point(search);

        chunks.push(remaining[..break_at].trim_end().to_string());
        remaining = remaining[break_at..].trim_start_matches('\n');
        if remaining.starts_with(' ') && !remaining.starts_with("  ") {
            remaining = &remaining[1..];
        }
    }

    chunks
}
}

关键设计点：

1. 提前返回：空字符串直接返回空 Vec，短消息返回单块
2. 先做 UTF-8 安全窗口，再找语义断点：避免把 find_break_point() 变成“逻辑断点 + 编码边界”双重职责
3. 边界清洗：trim_end()、去掉前导换行、最多跳过一个空格，让 chunk 之间的视觉边界更自然

窗口语义:先裁剪、再寻点

切割循环里最容易被忽略的是「窗口」这一步。split_message() 不是在整个剩余文本上找断点，而是先构造 search = &remaining[..limit] 这个不超过 max_chars 的搜索窗口，find_break_point() 只在这个窗口内做 rfind()（crates/octos-bus/src/coalesce.rs:72-73）。两层职责由此分开：窗口负责编码安全（is_char_boundary() 回退，crates/octos-bus/src/coalesce.rs:68-71），断点函数负责语义自然（`

→ →. ` → 空格 → 硬切，crates/octos-bus/src/coalesce.rs:87-118）。如果把两者混在一个函数里，每个候选断点都要重复做边界检查，而且很容易在「恰好卡在上限」的路径上漏掉一次。

另一个细节是 find_break_point() 对位置 0 的拒绝：rfind 找到的断点若等于 0 会被跳过，继续尝试下一级边界（crates/octos-bus/src/coalesce.rs:97-109）。这保证了向前推进：如果段落边界恰好是文本开头，切一刀切出空块，循环会永远停在原点。

切割之后的清洗也值得单独看：trim_end() 只作用于块尾，trim_start_matches('\n') 吃掉交界处累积的换行，然后「最多跳过一个前导空格、但两个空格不动」（crates/octos-bus/src/coalesce.rs:76-78）。两个空格在 Markdown 里意味着硬换行，跳过它会改变渲染语义；只跳一个空格是在「块间视觉干净」和「不破坏格式」之间取的折中。

去重与 Coalescing 的关系

Coalescing 解决「一条太长」，去重解决「一条收到两次」。Webhook 类平台（飞书、Twilio、企业微信）在超时重试时可能投递同一事件多次，MessageDedup 用容量 1,000、TTL 60 秒的 LRU 缓存记录已见过的消息 ID（crates/octos-bus/src/dedup.rs:12-25；is_duplicate 在 42-61 行）。Discord 网关重连后重放事件，也在 crates/octos-bus/src/discord_channel.rs:32 挂了同一个实例。两个机制正交：去重发生在 inbound 入口，切割发生在 outbound 出口，各管一段。入口不去重，一条重复消息会被切割成两倍量的块；出口不切割，任何一条超限消息直接被平台 API 拒收。

11.4.1 Unicode 安全的边界检测

find_break_point() 的硬切分支（第 5 级）使用了与 octos-core truncate_utf8 相同的字符边界回退算法：

#![allow(unused)]
fn main() {
// 硬切:从 max_len 向前回退到安全的 UTF-8 字符边界
let mut limit = max_len;
while limit > 0 && !text.is_char_boundary(limit) {
    limit -= 1;
}
limit
}

这保证了即使在中文、日文、emoji 等多字节字符的任意位置切割，也不会产生无效的 UTF-8 序列。考虑一个包含中文和 emoji 的消息在 Telegram（4000 字符限制）中的切割场景。没有这个保护，切割点可能恰好落在一个 4 字节的 emoji 中间，导致后续的 API 调用因为无效 UTF-8 而失败。

11.5 频道实现概览

octos-bus 通过 feature flags 按需编译各频道实现。每个频道实现 Channel trait 的具体方法：

表中较晚接入的四个频道值得各花一段说清定位。

DingTalk（crates/octos-bus/src/dingtalk_channel.rs，544 行）走「自定义机器人发送 + outgoing-robot webhook 接收」的双通道模式。关键在 sessionWebhook：outgoing 事件里携带一个短期有效的会话级 webhook URL，频道按会话缓存它，回复优先发往这个缓存地址而不是全局配置的 webhook（crates/octos-bus/src/dingtalk_channel.rs:281、发送优先级判定 188-199；无缓存且无配置时报错于 196 行）。这样设计是因为钉钉的 outgoing 模式下，回复必须回到「发起这次对话的那个机器人会话」，全局地址做不到这一点，而短期 URL 又要求缓存失效后能回退。

LINE（crates/octos-bus/src/line_channel.rs，826 行）是标准的 webhook + Messaging API 组合，安全链路在签名校验：对原始请求体做 HMAC-SHA256，Base64 后与 X-Line-Signature 头做常数时间比较（crates/octos-bus/src/line_channel.rs:87-95，ct_eq 来自 subtle crate）。用常数时间比较而不是 ==，是防时序侧信道逐字节猜签名；用原始 body 而不是反序列化后的字符串，是防 JSON 规整化差异导致验签失败。这两个选择都是平台集成里反复踩坑后的标准答案。

Matrix User（crates/octos-bus/src/matrix_user_channel.rs，1,525 行）与第 11.5 节表格里的 Matrix 行是同一平台的两种接入形态。AppService 模式需要 homeserver 侧注册，用户账号模式只需要 access token 或密码登录，然后对 Client-Server /sync API 做长轮询，超时 30 秒（crates/octos-bus/src/matrix_user_channel.rs:44 的 SYNC_TIMEOUT_MS）。长轮询让没有推送权限的自建服务器也能近实时收消息：请求挂着，有事件才返回，返回后立刻发下一个。它没有独立的 Cargo feature，随 matrix 一起编译，因为两者共享 Markdown-to-HTML 渲染和路径编码等基础设施。

CLI（crates/octos-bus/src/cli_channel.rs，137 行）是最小实现样本：stdin 按行读、stdout 写提示符（crates/octos-bus/src/cli_channel.rs:52-57），没有网络栈、没有鉴权、没有 feature 门控，始终编译。它存在的意义是让 Channel trait 的最小契约可验证：一个频道只需实现 name()、start()、send() 三个方法就能跑通全链路，也是新频道开发时最便宜的参照物。

每个频道实现都是独立的——Telegram 频道的 bug 不会影响 Discord，因为它们是不同的代码路径，通过不同的 feature flag 编译。需要注意的是，octos chat 的 CLI readline 不在 octos-bus 的 Cargo feature 频道列表中；bus 侧 feature-gated 频道当前为 api、telegram、discord、slack、whatsapp、email、feishu、dingtalk、line、twilio、wecom、matrix、wecom-bot、qq-bot、wechat 共 15 个，其中 crates/octos-bus/src/dingtalk_channel.rs 与 crates/octos-bus/src/line_channel.rs 是较新的接入；crates/octos-bus/src/matrix_user_channel.rs 没有独立 feature，随 matrix 一起编译；crates/octos-bus/src/cli_channel.rs 始终编译，三类合计 17 个频道源文件。这种隔离设计是 octos-bus 约 40K 行 Rust 源文件中大部分来自各频道独立实现的原因。

工程决策侧栏：为什么 JSONL 而非 SQLite / 单 JSON 文件

方案一：SQLite

优势：结构化查询、索引、事务、跨会话分析方便 劣势：需要显式 schema / migration 层；会话文件不再能直接用文本工具检查；和当前“每个会话按 key 读写”的访问模式相比，抽象更重

方案二：单个 JSON 文件

优势：实现最直观，序列化/反序列化简单 劣势：任何一次写入都要重写整个文件；崩溃恢复最脆弱；多会话下最容易形成热点锁

方案三：JSONL（octos 的选择）

优势：

• 第一行 metadata、后续逐行消息，既能 append，也能整会话 rewrite
• 易于保留 legacy flat layout 与 per-user layout 两套路径
• 每个会话一个文件，更贴合“按 session key 读写”的访问模式
• 备份、迁移、排障都可以直接在文件系统层面完成

劣势：

• 无索引，跨会话查询需要扫描所有文件
• 没有数据库级事务；复杂查询能力弱

选择理由： 从当前源码看，octos 的会话访问模式几乎总是“按 key 读取一个 session、append 新消息、必要时 rewrite 整个 session、按需迁移布局”。JSONL 正好覆盖这些路径，而且能自然配合 SessionActor 的 per-session file ownership。

11.6 Session 持久化的工程细节

11.6.1 FNV-1a 哈希

在 legacy flat layout 里，当编码后的 SessionKey 需要截断时，文件名会追加 FNV-1a 64-bit 哈希后缀（crates/octos-bus/src/session.rs:116-127、crates/octos-bus/src/session.rs:1554-1610）。这是一个非密码学哈希函数，优势在于实现极简且跨 Rust 版本稳定。它不用于安全目的（不防碰撞攻击），只用于“截断后文件名仍然可区分”。

#![allow(unused)]
fn main() {
fn fnv1a_64(data: &[u8]) -> u64 {
    let mut hash: u64 = 0xcbf29ce484222325;  // FNV offset basis
    for &byte in data {
        hash ^= byte as u64;
        hash = hash.wrapping_mul(0x100000001b3);  // FNV prime
    }
    hash
}
}

11.6.2 Percent-encoding

encode_path_component()（crates/octos-bus/src/session.rs:129-140）将 SessionKey 中的特殊字符编码为 URL 安全格式。这防止了 telegram:12345 这样的 key 被文件系统解释为目录路径（因为 : 在某些文件系统中是特殊字符）。

11.6.3 write-then-rename 原子性

整会话 rewrite() 路径的原子性通过两步操作实现：

1. 写入唯一临时文件 {session_file}.{pid}-{seq}.tmp
2. rename() 临时文件为正式文件

在 Unix/Linux 上，rename() 是原子操作——要么完全成功（新文件替换旧文件），要么完全失败（旧文件保持不变）。即使进程在 rename() 之前崩溃，也只会留下一个孤立的 .tmp 文件，不影响正式会话文件。

11.7 本章回顾

1. Channel trait：当前是 26 方法接口，但只有 name()、start()、send() 没有默认实现；流式编辑、typing、embed、health check 都是按需覆盖的扩展层。
2. Coalescing：5 级语义切割（段落→换行→句子→空格→硬切），MAX_CHUNKS=50 防 DoS，UTF-8 安全，超限时会追加独立的 truncation chunk。
3. Session：JSONL 文件第一行是 metadata，不是消息；当前同时兼容 legacy flat layout 和 per-user layout，/new/fork 会复制最近 N 条消息并记录 parent_key。
4. Thread binding：新写入路径要求 Assistant/Tool 预先绑定 thread_id，legacy load 则只做内存补齐；bound channel API 防止并发 turn 的流式增量落到错误气泡。
5. Durable observer 与 child contract：message/persisted 在磁盘写入和内存 mirror 更新后发出；后台子任务通过 ChildSessionContract 持久化 terminal/join/failure 状态，而不是只靠普通消息文本。

延伸阅读

• Server-Sent Events：MDN "Using server-sent events" — 理解流式消息推送模式
• Telegram Bot API：https://core.telegram.org/bots/api — Telegram 频道的 API 细节
• JSONL 格式：https://jsonlines.org/ — 行分隔 JSON 格式规范

思考题

1. 频道抽象的边界：某些频道支持富文本（Slack Block Kit、飞书 Rich Text），但 Channel::send() 只接受纯文本。你会如何扩展 trait 以支持富文本，同时保持向后兼容？
2. 会话恢复：如果 octos 进程崩溃，JSONL 文件的最后一行可能不完整。你会如何实现崩溃恢复？

版本演化说明 本章分析基于 ../octos 当前 main 分支源码。octos-bus crate 位于 crates/octos-bus/src/；相较早期版本，本章已更新 thread-bound streaming、per-user session layout、durable commit observer、child-session contract、per-key persist lock 与唯一 rewrite temp path 等主分支语义。

版本演化说明

本章基线为 octos main @ 9c157101（2026-09-03 核对）。相对旧稿的“约 30K 行、14 频道”口径：crate 现为约 40K 行（40,937 行，频道文件 18,207 行、共 17 个），新增 DingTalk、LINE 频道与 Matrix User 用户账号模式；crates/octos-bus/src/session.rs 扩至 3,417 行，SessionHandle 家族集中在约 2400-3100 行段；octos-cli 侧原 crates/octos-cli/src/api/ui_protocol.rs 已拆分为 transport、ledger 等 8 个文件（7 个实现文件 + 1 个测试文件 crates/octos-cli/src/api/ui_protocol_tests.rs）。本章行号引用以该基线为准。

crates/octos-bus/src/session.rs 的行号漂移不是简单膨胀，而是所有权模型重构的结果。旧稿写作时，读写都汇聚在 SessionManager 的大锁上；现在的代码把在线路径拆给 SessionHandle（crates/octos-bus/src/session.rs:2329 起，集中在约 2400-3100 行段），SessionActor 每会话持有独立 handle，跨会话零锁竞争（struct SessionHandle 上方的 doc 注释写明这一动机）。原 manager 退到两件事上：admin 侧列表查询，以及 persist_message_through_canonical_path()（2388 行）这类需要 per-key Tokio mutex 串行化的跨路径写入口（锁表在 2360 行）。文件变长，主要是迁移状态机（2441-2460 行的三种真实情形）和 child-session contract 带来的持久化分支，不是无序生长。

第 12 章：并发模型：三层调度的生产实现

定位：本章讲 octos 的并发模型如何分三层协同：Tokio 层的 session actor、信号量限流与工具批次并发；supervisor 层把长程编排做成重启幸存的事件账本与续跑调度；peer/lease 层用进程隐喻和租约管理多 agent。前置依赖：第 5 章（Agent Loop）、第 10 章（Harness 与事件 ABI）。适用场景：想看 Rust 异步并发在生产系统里如何落地的开发者，以及需要调优 gateway 并发参数的运维者。fleet 状态机细节详见第 16 章，goal/peer 编排详见第 18 章。

12.1 从一组数字说起

把并发相关源码按职责切开数一遍：17 个文件、74692 行、722 个公开符号，分成三层。

三个数字说明一件事：并发在 octos 里早已越过「怎么用 Tokio」的阶段。Tokio 层只占三分之一行数，真正的大头是 supervisor 层：4.5 万行代码在解决一个 Tokio 本身不管的问题：进程重启之后，编排状态怎么办。

flowchart TB
    subgraph L3["③ peer/lease 层"]
        PEERS["crates/octos-cli/src/peers/mod.rs<br/>peer 暂存与寻址"]
        LEASE["crates/octos-fleet/src/records.rs<br/>Lease / Attempt 状态机"]
    end
    subgraph L2["② supervisor 层（autonomy/，45544 行）"]
        STORE["SupervisorStore<br/>JSONL 事件账本 + snapshot"]
        SCHED["MasterContinuationScheduler<br/>dedupe + 优先级续跑"]
        ORCH["InProcessAgentOrchestrator"]
        WAKE["crates/octos-cli/src/autonomy/fleet_wake.rs<br/>outbox 消费者"]
        MON["crates/octos-cli/src/autonomy/monitor_runtime.rs<br/>零 token 监视器"]
    end
    subgraph L1["① Tokio 层（25154 行）"]
        GW["crates/octos-cli/src/commands/gateway/gateway_runtime.rs<br/>信号量限流"]
        REG["ActorRegistry<br/>会话生命周期"]
        ACTOR["SessionActor ×N<br/>每会话一个 tokio task"]
        TOOLS["crates/octos-agent/src/agent/execution.rs<br/>工具批次并发"]
        TS["TaskSupervisor<br/>spawn_only 状态"]
    end
    GW -->|"Semaphore permit"| REG --> ACTOR
    ACTOR --> TOOLS --> TS
    TS -->|"lifecycle 事件"| STORE
    SCHED -->|"续跑派发"| ACTOR
    ORCH --> TS
    STORE --> SCHED
    WAKE --> SCHED
    MON -->|"External continuation"| SCHED
    ORCH --> PEERS
    PEERS --> LEASE

本章按这个分层走：先讲 Tokio 层的会话状态所有权与并发分界（12.2–12.5），再讲 supervisor 层为什么存在、怎么落地（12.6），最后交代 peer/lease 层作为并发原语的角色（12.7），12.8 收在优雅关停。

12.2 Tokio 层：会话 actor 与分层 spawn

单用户 CLI 模式下 Agent 顺序执行，没有并发问题。Gateway 或 Serve 模式下，多个用户同时发消息，每个会话还夹杂取消、后台子任务结果与状态投递。octos 的答案不是给共享状态加锁，而是 session actor：每个会话由一个长期存活的 tokio 任务独占管理，核心状态只有这一个 owner。

入口在 ActorRegistry（crates/octos-cli/src/session_actor.rs:2524）。它持有 actor 表、工厂和一把信号量；新会话到来时创建 actor 并 tokio::spawn(actor.run())（crates/octos-cli/src/session_actor.rs:4122）。actor 本体 struct SessionActor 在 crates/octos-cli/src/session_actor.rs:4455，持有会话键、工具注册表、工作目录，以及两个关停标志（12.8 展开）。外部世界通过 ActorHandle（crates/octos-cli/src/session_actor.rs:2502）向 actor 的信箱发消息，信箱消息就是 ActorMessage 枚举（crates/octos-cli/src/session_actor.rs:2443）：

#![allow(unused)]
fn main() {
pub enum ActorMessage {
    /// A user message to process.
    Inbound { message: InboundMessage, /* … */ },
    BackgroundResult { /* … */ },
    TaskStatusChanged { /* … */ },
    ApprovalExpired { request_id: String },
    Cancel,
}
}

五种消息覆盖了 actor 要响应的全部事件类别：新输入、后台子任务结果、任务状态变化、审批过期、取消。同一会话的两条消息不可能并发修改历史，因为它们都在同一个 actor 的信箱里排队，由 actor 依次处理。

分层 spawn 是这层的主干。tokio::spawn() 在源码里出现在四个层级：

1. 会话级：ActorRegistry 为新 session 起 actor，长期存活（crates/octos-cli/src/session_actor.rs:4122）。
2. 消息级：actor 把当前消息的主 Agent 调用派生成独立任务，自己继续轮询信箱，随时能接住 Cancel 与后台结果。
3. 工具级：单轮多个 tool call 时每个工具各起一个任务（crates/octos-agent/src/agent/execution.rs:701），再按批次策略聚合（12.4）。
4. 后台级：spawn 工具的 background 模式起长期子 Agent，可见状态交给 TaskSupervisor（12.5）。

gateway 侧还有两个辅助 spawn：Ctrl+C 信号处理（crates/octos-cli/src/commands/gateway/gateway_runtime.rs:1653）与系统提示词的异步刷新（crates/octos-cli/src/commands/gateway/gateway_runtime.rs:1713）。派发参数统一由 DispatchParams（crates/octos-cli/src/session_actor.rs:86）从 gateway 传到 actor。

并发与串行的分界因此非常清楚：跨会话完全并发（每个 actor 一个任务）；会话内串行（信箱排队）；单轮工具调用按批次准入策略选择并行或串行；后台任务脱离主对话流，靠状态回投汇合。

工程决策：共享 Mutex、spawn-per-message 与 Session Actor

三种方案的取舍：

• 共享 Mutex<SessionState>：实现最快，但锁粒度随状态膨胀，一条消息持锁跨 await 会把其他会话的消息也堵住，取消信号更难插队。旧稿 v1 时代曾按「per-session Mutex 序列化」描述，当前源码已不是这个模型。
• spawn-per-message（每条消息一个无状态任务）：并发度最高，但会话历史、工具注册表、工作区必须外置到共享存储，状态一致性重新变成锁问题。
• Session Actor：状态所有权唯一，消息天然排队，取消只是信箱里的一条 Cancel。代价是 actor 自身要管理生命周期（空闲回收、死亡重生时保留 profile 覆盖，见 ActorHandle 字段注释）。

octos 选第三种，代价被 ActorRegistry 集中承担，业务侧只面对 ActorMessage。

12.3 信号量限流：max_concurrent_sessions

会话数量要有上界。gateway 启动时创建信号量，容量直接取配置：

#![allow(unused)]
fn main() {
// Semaphore to bound concurrent session processing
let concurrency_semaphore = Arc::new(Semaphore::new(gw_config.max_concurrent_sessions));
}

位置在 crates/octos-cli/src/commands/gateway/gateway_runtime.rs:1731-1732，紧随其后就把这把信号量交给 ActorRegistry::new。上限来自配置项 max_concurrent_sessions，serde 声明在 crates/octos-cli/src/config.rs:1548-1549，默认值函数 default_max_concurrent_sessions() 在 crates/octos-cli/src/config.rs:1633，函数体返回字面量 10（本会话亲测）。启动日志会打印这个值（crates/octos-cli/src/commands/gateway/gateway_runtime.rs:1666）。

permit 的消费点不在 gateway，而在 actor 侧的消息处理入口：crates/octos-cli/src/session_actor.rs:7485 与 crates/octos-cli/src/session_actor.rs:9293 两处 self.semaphore.acquire().await。这个位置决定了排队行为：超过 10 个会话同时在处理消息时，第 11 个会话的消息任务在 acquire() 上挂起等待，而不是被拒绝；actor 本身还活着、还能收消息，只是新消息的处理被信号量挡住。等某个活跃会话的处理结束、permit 释放，排队中的下一个自动获得执行权。

把限流放在消息处理层而非会话创建层，是一个有意识的选择：空闲会话不占并发额度，10 个名额全部留给真正在跑 LLM 调用的会话。

12.4 工具并发：批次准入三策略

单轮 LLM 响应包含多个 tool call 时，execute_tools（crates/octos-agent/src/agent/execution.rs:2483，可见性为 pub(super)，模块内部 API）不盲目并行。每个工具通过 concurrency_class 报告自己是 Safe（只读、无副作用）还是 Exclusive（写操作），执行器按整批构成选三种策略之一（模块文档 crates/octos-agent/src/agent/execution.rs:7-26）：

• All-Safe 批：每个调用 tokio::spawn 成独立任务（crates/octos-agent/src/agent/execution.rs:701），futures::future::join_all 聚合并保持调用顺序（crates/octos-agent/src/agent/execution.rs:2992）。
• All-Exclusive 批：按 LLM 调用顺序串行执行；首个错误（含 hook 拒绝与 panic）之后剩余调用跳过，各自收到合成的「因兄弟任务出错而取消」结果，保证每个 tool_call_id 都有应答。
• 混合批（#1766）：第一阶段并行跑所有 Safe 调用，第二阶段按原顺序串行跑 Exclusive 调用，最终按原始调用顺序重组结果。

并行路径还带统一超时：join_parallel_handles（crates/octos-cli 无关，位于 crates/octos-agent/src/agent/execution.rs:2959 起）对每个 handle 施加同一 deadline，超时先 abort()，再给一段有界的清理宽限等待，然后返回合成超时结果。LLM 看到的永远是一一对应的工具结果列表，并行细节不外泄。

两道闸（信号量与批次准入）解决的是不同粒度的过载，判据也不同。信号量闸的判据是资源：LLM 调用贵且慢，10 个并发会话大致对应上游配额与内存的安全水位，超了就该排队，排队无害。批次准入的判据是语义：并行本身没有成本问题，问题是 Exclusive 工具之间有顺序依赖（同一文件的写与写、写与读），乱序执行的结果不是慢而是错。所以信号量用「等待」处理超限，批次准入用「降级为串行」处理冲突，一个是背压，一个是正确性防御。把两者混在一处会出现经典误判：有人看到工具串行执行以为是并发不够，实际是批次里有 Exclusive 成员在保护语义。判别方法是看批次的构成：全 Safe 批永远并行，出现串行必有 Exclusive 参与（#1766 之前混合批整体串行，之后只串行必要部分，这是那次优化的全部内容）。

子 Agent 的并发形态由 spawn 工具的 mode 参数决定："background"（默认，crates/octos-agent/src/tools/spawn.rs:1929 的 default_mode()）或 "sync"（crates/octos-agent/src/tools/spawn.rs:1855 的字段定义，JSON schema 在 :3004）。sync 模式阻塞当前轮次等子 Agent 完成，结果直接进本轮上下文；background 模式把子 Agent 剥离主对话流，完成后以 BackgroundResult 消息回到 actor 信箱。前者适合「下一步依赖子任务产出」的场景，后者适合「发了就不用管、晚点收结果」的场景。

12.5 spawn_only 生命周期：TaskSupervisor

后台任务不是 fire-and-forget。TaskSupervisor（首行文档「Background task lifecycle management for spawn_only tools.」，crates/octos-agent/src/task_supervisor.rs:1）是一个状态库：跟踪 spawn_only 任务从派生到终态，并明确声明自己不执行 workspace contract：契约校验先发生，校验通过才更新 supervisor 状态（模块文档前六行）。运行状态用 TaskStatus（crates/octos-agent/src/task_supervisor.rs:140）：

#![allow(unused)]
fn main() {
pub enum TaskStatus {
    Spawned, Running, Completed, Failed,
    Cancelled,   // 用户取消，终态（:173 is_terminal）
    Parked,      // #27c：serve 重启后的孤儿任务，等待客户端重连收养
}
}

六个状态里 Parked 最特殊：它既非活跃（is_active 只含 Spawned/Running，crates/octos-agent/src/task_supervisor.rs:164）也非终态（crates/octos-cli 不涉及；is_terminal 在 crates/octos-agent/src/task_supervisor.rs:173），因为任务的工作成果（staged peer 的 brief 与 worktree）还在磁盘上，客户端重连后 mark_running 能把它救活。这正是「状态要不要持久化」影响并发语义的直接例子。

防失控有硬上限：每父会话最多 200 个注册子任务（MAX_CHILDREN_PER_PARENT，crates/octos-agent/src/task_supervisor.rs:43），可用环境变量 OCTOS_MAX_CHILDREN_PER_PARENT 在进程启动时覆盖（:41 的文档与 :77 的读取）。超限注册返回 RegisterTaskError（crates/octos-agent/src/task_supervisor.rs:90）。

对外的生命周期投射是另一个枚举 TaskLifecycleState（crates/octos-agent/src/task_supervisor.rs:243）：Queued、Running、Verifying、Ready、Failed、Cancelled。BackgroundTask::lifecycle_state()（crates/octos-agent/src/task_supervisor.rs:363）把内部 TaskStatus 翻译成这组面向调用方的状态。内部状态机关心「worker 还在不在」，投射状态关心「产出可不可信」，Verifying 这一态就是给 workspace contract 校验留的位置。两套状态的映射关系如下：

这个投射有两个消费面。MCP 侧：octos mcp-serve 只暴露一个工具 run_octos_session（crates/octos-agent/src/mcp_server.rs:66），会话派发通过 SessionLifecycleObserver::mark_state（crates/octos-agent/src/mcp_server.rs:145）上报 Queued → Running → Verifying → Ready/Failed 的迁移（trait 文档在 :142-144）；外层 MCP caller 最终收到的是会话级聚合结果（final_state: TaskLifecycleState，:108），不是内部工具事件流。Harness 侧：McpServerCall 事件携带 outcome 字段，取值 ready/failed/queued/running/verifying，与 TaskLifecycleState 一一对应（crates/octos-agent/src/harness_events.rs:651-652，事件变体定义见 :397 附近），后台任务的生命周期由此进入 harness events 与 metrics，成为 operator 可观测面的一部分。

12.6 supervisor 层：重启幸存的长程编排

Tokio task 活在进程里，进程一死全部蒸发。对「跑十分钟的工具调用」这无所谓；对「今天要把这本书二十一章写完」这种跨小时跨天的目标，编排状态必须比进程活得久。supervisor 层的 45544 行代码都在回答这一个问题。

工程决策：为什么把长程编排从 Tokio task 提升为持久化 supervisor

一个长程目标（比如派 5 个 peer 各写一章）天然是多次进程生命周期的叠加：master 会重启，peer 会跑很久，结果会晚到。如果编排状态只存在于内存里的 task 树，重启即失忆，唯一的恢复手段是让人重新下达指令。

提升为持久化 supervisor 后，三件事变了：状态落盘为事件账本，重启后重放恢复；「谁该被唤醒继续跑」从隐式的 task 依赖变成显式的续跑队列；长任务的完成不再要求任何进程持续存活。代价是所有状态迁移都要写成事件、都要处理重放幂等，这正是 crates/octos-cli/src/autonomy/supervisor_store.rs 与 crates/octos-cli/src/autonomy/master_continuation_scheduler.rs 加起来近五千行的原因。

事件账本：SupervisorStore

SupervisorStore（crates/octos-cli/src/autonomy/supervisor_store.rs:697）管理四个路径：事件文件、轮转事件文件、snapshot 与锁。事件文件名固定 supervisor-events.jsonl（常量在 :25），压缩后保留单代 .old（:33），且 .old 只用于取证、永不重放；降级到不认识 snapshot 的旧二进制时，它看到的会是截断视图，注释里把这个兼容性代价写得很直白。

崩溃恢复的设计核心在 load_state（crates/octos-cli/src/autonomy/supervisor_store.rs:780）里，只有十几行：先读 snapshot（若有），取其 last_sequence 作为水位线；再读账本行，只重放 row.sequence > snapshot_last_sequence 的尾部行（:780-793）。重放靠 apply_ledger_row（:381）把每行事件应用到状态机，事件以 serde 的 type/payload 标签自包含（:300-304 的注释解释了为什么变体按值携带完整记录：重放不需要热路径上的装箱优化）。三个设计决策撑起这套重放：

第一，快照节奏是行数触发而非时间触发。SNAPSHOT_EVERY_APPENDS = 512（crates/octos-cli/src/autonomy/supervisor_store.rs:49），常量注释给出了取值依据：512 行让启动重放尾巴保持在几百 KB、毫秒级解析，同时把全量序列化加 fsync 的代价摊到数百次 append 上；计数对象是账本里的行数而非单进程的 append 次数，多个写者共享一个账本时仍会在尾巴越线时统一压缩。

第二，last_sequence 是单调水位线而不是计数器。apply_ledger_row 每应用一行就取 max（:381-382），load_state 装载时也对 snapshot 与状态里的水位线取 max（:784）。这意味着乱序到达或多写者交错写入的行不会让水位线回退，snapshot 只需声明「截至哪个序号」就能安全截断重放。

第三，.old 一代轮转是取证妥协而不是恢复路径。压缩把已应用的行移入 .old 后，旧二进制（不认识 snapshot 的 pre-#1974 构建）重放 live 尾巴会得到截断视图；宁可让降级者看到少，也不让任何版本误读，因为认识 snapshot 的构建会拒绝 schema_version 更新的快照（load_snapshot，:876）而不是猜着解析。

写侧的四个方法在这套读语义上闭合：write_snapshot（:905）、snapshot_now（:920，带锁的强制压缩入口）、append_event（:935，写入同时按水位线判断是否触发压缩）。账本因此是一个「append 快、恢复有界」的结构：正常运行时每次事件只是一次追加写，崩溃后恢复成本被 512 行的尾巴钉死在上界。

续跑调度：MasterContinuationScheduler

账本记录「发生了什么」，调度器决定「接下来谁跑」。MasterContinuationScheduler（crates/octos-cli/src/autonomy/master_continuation_scheduler.rs:477）内部是一个 BinaryHeap 加一个按 dedupe key 索引的 pending_by_key 表（:506 起的 impl）。每个续跑请求带身份与去重键：MasterContinuationId（:99）、MasterContinuationDedupeKey（:112）、MasterContinuationRequest（:221）。

续跑原因是有优先级的：MasterContinuationReason（:137）枚举 ChildCompleted、ScatterJoinComplete、LoopFire、GoalContinue、GoalWrapUp 与 External(String)，映射到 MasterContinuationPriority（:186）：LoopFire 最高，泛化 External 唤醒最低，注释明说这是「刻意压低，除非未来接线把它映射到类型化原因」。结构体里还有一个 TOCTOU 防护字段 recently_claimed_external：同键的 External 续跑在窗口内重复入队会被拒绝，防止一次终态迁移被两条路径重复投递（:477 结构体字段文档）。去重键加优先级堆，就是「turn 结束后再创造 turn」的并发骨架；第 5 章从 loop 视角看过它的消费侧，完整语义属于第 18 章。

outbox 唤醒与零 token 监视器

唤醒有两条外部通路。crates/octos-cli/src/autonomy/fleet_wake.rs 的后台消费者 spawn_fleet_outbox_consumer（crates/octos-cli/src/autonomy/fleet_wake.rs:343）用 tokio::spawn 起一个每 3 秒的 interval 循环（常量 FLEET_WAKE_INTERVAL_SECS，:59），反复调用 drain_fleet_outbox_once（:235）把 fleet 内核 outbox 里的唤醒提交转成 keeper 的续跑请求。轮询而非推送，换来的是消费端崩溃后下一 tick 自动恢复，不丢唤醒。

crates/octos-cli/src/autonomy/monitor_runtime.rs（引入于 commit c4f03647，#1977/#1988，2026-08-12）提供零 token 的事件监视器：MonitorMode（crates/octos-cli/src/autonomy/monitor_runtime.rs:72）只有两态，Poll 模式按 interval_secs 周期执行探针命令、对 stdout 过滤后以「变化」为事件，Stream 模式跟随进程 stdout 逐行产出。监视器不花模型 token，只有观测变化时才通过 External 续跑唤醒 master，把「等一个外部条件」从对话循环里剥了出去。

AgentOrchestrator：编排器的 RPC 面

多 agent 操作统一在 AgentOrchestrator trait（crates/octos-cli/src/autonomy/agent_orchestrator.rs:606）：list_agents、read_agent_status、read_agent_output、list_agent_artifacts 是必选方法，spawn_agent（:662）、send_input（:675）、wait_agent（:688）、resume_agent（:699）四个带默认实现，默认全部返回 method_not_supported_error。也就是说 trait 定义了完整的 RPC 面，但并非每个实现都接线了全部操作，读代码时不能假设四个生命周期方法处处可用。

生产实现是 InProcessAgentOrchestrator（:746，内部 impl 块从 :1451 起，trait 实现块在 :9462）。它把 TaskSupervisor 的后台任务镜像成 agent 状态，核心路径 run_native_specialist（crates/octos-cli/src/autonomy/agent_orchestrator.rs:2471）串起完整一次受监督专家执行：注册 native agent、运行子 Agent、推送 output 与 artifact、最后回写 supervisor。crates/octos-cli/src/autonomy/goal_loop_runtime.rs（1562 行）则提供 goal 与 loop 的调度策略原语：GoalId（crates/octos-cli/src/autonomy/goal_loop_runtime.rs:10）、GoalRuntimePolicy（:239，含 cadence 与 max_continuations）、GoalRuntimeState（:265，Active/Paused/Completed/Failed）。

诚实边界：当前实现是「一个 master 监督一组受管子 agent、按事件续跑」的编排器，不是任意互联、实时对话的 multi-agent society。RPC 面的存在容易让人高估它，四个默认返回错误的方法就是提醒。

sequenceDiagram
    participant W as 子任务/fleet/monitor
    participant ST as SupervisorStore
    participant SC as MasterContinuationScheduler
    participant MA as master 会话

    W->>ST: append_event（终态/唤醒事件落盘）
    ST->>ST: snapshot + 压缩（超阈值时）
    ST->>SC: 事件转续跑请求（dedupe key）
    SC->>SC: 按优先级入堆，窗口内重复键拒绝
    SC->>MA: 就绪续跑出队，派发新 turn
    MA-->>ST: 新 turn 产生的新事件
    Note over ST,MA: 进程重启后：load_state 重放账本<br/>+ snapshot，续跑队列恢复

12.7 peer/lease 层：进程隐喻与租约

第三层解决「多个 quasi-agent 并存」的隔离与恢复。crates/octos-cli/src/peers/mod.rs 的首行文档是「Peer-agent staging, addressing, and parked-prompt plumbing.」（crates/octos-cli/src/peers/mod.rs:1），第二段注明它是从 api 门控的 ui_protocol 树里逐字提升出来的（Phase 3 peer-goal 提取，只改模块位置与可见性，逻辑未动）。peer 的并发原语角色体现在 PeerTaskBinding（:166）：把一个 peer 绑定到一条 TaskLivenessLease 上，绑定与退役走 bind_peer_supervised_task（:241）等函数，peer 的存活因此与 supervisor 的租约一致。

fleet 侧的并发原语是两个小结构体。Lease（crates/octos-fleet/src/records.rs:250）只有 owner_epoch 与 expires_at_ms 两个字段：daemon 每次启动拿到新 epoch，外来 epoch 或已过期的租约会由 recovery reconciliation 回收。一句话，重启后的旧主人自动失权。Attempt（:256）给一次执行尝试建档案，fleet id 冗余存储，使 (child_id, attempt_id) 就能定位 child 行。

peer 与 subagent 的差异可以用一张对比图说清：

flowchart TB
    subgraph SA["subagent ≈ 线程"]
        A1["tokio::spawn 于父进程内"]
        A2["生命周期 = 进程生命周期"]
        A3["状态在 TaskSupervisor 内存+账本"]
    end
    subgraph PE["peer ≈ 进程"]
        B1["独立工作目录 / 独立会话树"]
        B2["TaskLivenessLease 租约保活"]
        B3["serve 重启后 Parked，可重连收养"]
    end
    A1 --> A2 --> A3
    B1 --> B2 --> B3

subagent 像线程：共享进程命运，轻量，随父进程蒸发。peer 像进程：有自己的地址（slug）、自己的工作目录，靠租约声明存活，进程重启后工作成果仍在磁盘上等待收养。

fleet 侧的租约语义值得在本章展开，因为它是「并发所有权如何跨进程传递」的最小完整样本。Lease 结构体本身只有两个字段（crates/octos-fleet/src/records.rs:250）：owner_epoch 是本次 daemon 启动的身份，expires_at_ms 是绝对过期时刻。获取发生在派发时：crates/octos-fleet/src/store.rs 构造 Attempt 时把 status 置为 Leased、写入 lease { owner_epoch, expires_at_ms: now_ms + lease_ttl_ms }（crates/octos-fleet/src/store.rs:990-1001，TTL 加法用 checked_add 防溢出）。续期不是显式 API：worker 转入执行态走 mark_running（crates/octos-fleet/src/store.rs:1053），租约字段随 attempt 行持久存在，真正检查它的是所有写路径上的谓词。

让渡与回收靠同一个四部谓词。complete_child（crates/octos-fleet/src/store.rs:1158）提交结果前要求四个条件同时成立：child 的 current_attempt_id 指向本 attempt（attempt-id 栅栏，挡住同代重试）、attempt 状态为 Running、generation 等于 fleet 当前代（代栅栏，挡住重规划后的旧尝试）、lease.owner_epoch 等于调用者 epoch（租约栅栏，挡住重启后的旧主人），谓词本体在 :1230-1237。任一不满足就返回 Superseded，结果整个丢弃、账面零变动。回收则发生在 boot reconciliation：非终态 attempt 若租约的外来 epoch 不匹配或 expires_at_ms 已过（crates/octos-fleet/src/store.rs:2276-2277 的 stale 判定），被无条件置为 Interrupted 并释放预算预留；注释里记录了 #1973 修复：此前 Cancelled 的 fleet 被整体跳过，attempt 与预留被永久钉死。

这套设计的并发含义：旧进程崩溃后，新进程不需要与任何人协商：epoch 不同就自动失权，过期就自动回收，正确性不依赖崩溃方配合。租约与 supervisor 层的事件账本是同一命题的两个答案：账本用重放恢复「编排到哪了」，租约用栅栏废黜「不该再动的人」。Lease/Attempt 的完整状态机详见第 16 章，goal/peer 的编排语义详见第 18 章。

12.8 优雅关停：两个 AtomicBool

关停用两个原子布尔分层。global_shutdown 与 cancelled 是 SessionActor 的字段（crates/octos-cli/src/session_actor.rs:4500-4503）：前者是进程级信号（Ctrl+C），后者只影响当前会话。actor 对外的 ActorHandle.shutdown（crates/octos-cli/src/session_actor.rs:2872）暴露的也是 Arc<AtomicBool>。

写入侧在 gateway 的 Ctrl+C 处理任务里（crates/octos-cli/src/commands/gateway/gateway_runtime.rs:1653）：ctrl_c().await 返回后 shutdown.store(true, Ordering::Release)。Release 序保证此前的所有写入对获取者可见；读取侧用 Ordering::Acquire load，保证 actor 看到关停标志时也看到标志前的全部状态变更。一对 Release/Acquire 就是这条控制信号的全部内存序契约，没有锁。

广播式回收走另一条路：ActorRegistry::shutdown_all（crates/octos-cli/src/session_actor.rs:2795）直接 drop 全部 sender，actor 的 recv() 返回 None 后自然退出——信箱耗尽即关停，不需要每个 actor 轮询标志。两条路径互补：AtomicBool 给运行中的任务一个协作式检查点，drop sender 给等待中的 actor 一个确定性的终结。

12.9 小结

三层不是替代关系而是叠加关系：supervisor 的续跑最终还是要派发回某个 session actor 执行；peer 的存活判断复用 TaskSupervisor 的状态机。并发原语的分层，本质是把「快」（内存态、微秒级）、「久」（磁盘态、跨重启）、「隔离」（进程边界）三种正交需求分开买单。

延伸阅读

• 第 5 章：Agent Loop 的六阶段生命周期与预算闸；续跑队列的消费侧视角。
• 第 10 章：harness events 的完整事件 ABI，本章的 McpServerCall 是其中一个事件族。
• 第 16 章：fleet 的 Lease/Attempt/Recovery 状态机全貌。
• 第 18 章：goal 与 peer 的编排语义，MasterContinuationScheduler 的完整消费链。
• Tokio 官方文档 Graceful Shutdown 章节：运行时级优雅停机的任务取消与等待语义。

思考题

1. 若把 max_concurrent_sessions 从 10 调到 100，第 12.3 节的 permit 消费位置（消息处理层）会导致什么现象？如果 permit 改在会话创建层获取呢？
2. TaskStatus::Parked 不属于 is_active 也不属于 is_terminal。设计一个并发场景，说明若把 Parked 误归为终态会破坏什么。
3. 混合批策略（#1766）先并行 Safe 再串行 Exclusive，为什么不能反过来？结果按「原始 LLM 调用顺序重组」这一约束，消费方依赖它做什么？
4. MasterContinuationScheduler 的 TOCTOU 防护只记录 External 键。若一个新的 Internal 生产者也会在窗口内重复入队同键，会发生什么？注释里的 INVARIANT 要求新生产者怎么做？
5. shutdown_all 靠 drop sender 让 actor 退出。如果一个 actor 正在执行一个 30 分钟的工具调用，这条路径的表现与 global_shutdown 标志路径有何不同？

版本演化说明

• 本章分析基线：octos main @ 9c157101（2026-09-02 检出），行号与数字均为该 commit 实测；事实表见 assets/ch12-facts.md（2026-09-03）。
• 相对 v1 旧稿（原第 11 章）的变化：叙事从「per-session Mutex 序列化」纠正为 session actor 状态所有权模型；新增 supervisor 层（autonomy/ 十文件）与 peer/lease 层两章内容；crates/octos-cli/src/autonomy/monitor_runtime.rs 引入于 c4f03647（2026-08-12），当前行号含后续 e2f999a0（clippy 格式化）与 0c44b26f（OLP control channel）两次提交的偏移。
• 事实表四条「待 writer 核」已在本会话亲测：default_max_concurrent_sessions() 返回字面量 10；crates/octos-agent/src/task_supervisor.rs 与 crates/octos-cli/src/config.rs 首行均有 //! 文档（事实表原记「无/未采集」有误）；crates/octos-cli/src/autonomy/agent_orchestrator.rs 骨架行号 606/746/1451/2471/9462 全部确认；crates/octos-agent/src/agent/execution.rs 对外入口为 pub(super) fn execute_tools（:2483），本章按此口径引用。

第 13 章：octos-pipeline：DOT 图驱动的工作流引擎

定位：本章对照 crates/octos-pipeline/src/，解释 octos 如何把 Graphviz DOT 图解析成带类型的 PipelineGraph，执行器如何在九种 HandlerKind、十二种 IR 节点、静态并行、动态并行、检查点恢复、deadline 护栏和父会话资源继承之间落地，以及 run_pipeline 工具把 pipeline 暴露给 Agent 的方式。前置依赖：第 5 章、第 8 章、第 10 章、第 11 章。适用场景：需要理解多步骤 Agent 编排机制的开发者。

当任务已经不是"单个 Agent 循环 + 几次工具调用"能解决的问题时，就需要显式的工作流编排。典型例子是：先规划研究角度，再并发检索，再汇总分析，最后生成报告。octos-pipeline 解决的就是这类问题，但它的当前实现和"传统 DAG 调度器"的直觉并不完全一样：它既有图结构，也有运行时分支选择、并发汇合、模型路由和工具策略继承；同时还通过 PipelineHostContext 继承父 session 的文件缓存、子 Agent 输出路由、任务监督器和成本账本，让 pipeline 节点不再像早期实现那样孤立运行。

13.1 DOT 图如何进入运行时

13.1.1 为什么是 DOT

octos 用 Graphviz DOT 定义工作流，而不是 YAML/JSON。原因不是"DOT 更潮"，而是它天然把节点和边作为一等语义：同一个文件既能被执行器解析，也能直接被 Graphviz 渲染成图。

digraph research {
    graph [label="Deep Research", default_model="cheap"]

    start [label="规划", handler="dynamic_parallel",
           converge="analyze",
           planner_model="strong",
           worker_prompt="围绕 {task} 做资料检索，并保留来源",
           tools="deep_search",
           max_tasks="6"]

    analyze [label="分析", handler="codergen",
             model="strong",
             tools="read_file,write_file"]

    finish [label="结束", shape="Msquare"]

    start -> analyze
    analyze -> finish
}

这个例子已经体现了当前 parser 支持的几类关键能力：

• 图级属性：graph [label=..., default_model=...]
• 节点属性：handler、model、tools、converge、planner_model 等
• 边：A -> B
• 形状到 Handler 的隐式映射，例如 Msquare 会映射到 Noop

13.1.2 手写 parser，而不是第三方 DOT 库

入口是 crates/octos-pipeline/src/parser.rs:21-23 的 parse_dot()，真实工作发生在 DotParser::parse()（struct 定义在 crates/octos-pipeline/src/parser.rs:45，impl 在 :50）。这是一个手写 parser，不依赖外部 DOT 解析库。当前文件已增长到 1,445 行。

当前实现比"只支持一小撮语法"的简化说法要丰富一些：

• digraph 名称是可选的；如果模型生成了 digraph { ... }，parser 会把图 ID 设成 "pipeline"（crates/octos-pipeline/src/parser.rs:63-65）
• 支持图级属性 graph [key=value]，除了 label 和 default_model，现在还接受 max_total_tokens（运行级 token 预算）、default_timeout_secs（每条 pipeline 的默认墙钟超时）和 result_fidelity（结果体积降级注解），落点都在 apply_graph_attrs()（crates/octos-pipeline/src/parser.rs:520-537）
• 支持 subgraph name { ... }，并把子图中的节点归档到 PipelineGraph.subgraphs（crates/octos-pipeline/src/parser.rs:148-150、crates/octos-pipeline/src/graph.rs:48）
• 支持边链式写法 a -> b -> c，属性会应用到链上的每一条边（crates/octos-pipeline/src/parser.rs:163）
• 支持 //、/* */，以及额外的 # 行注释；后者明显是在为 LLM 生成的 DOT 做容错（crates/octos-pipeline/src/parser.rs:479-502）
• 如果边引用了未显式声明的节点，parser 会自动补出默认节点定义（crates/octos-pipeline/src/parser.rs:110-127）

这一层的结果不是"松散的 JSON 树"，而是带语义的 PipelineGraph。其核心结构在 crates/octos-pipeline/src/graph.rs:10-54（图）和 :118-184（节点）：

• PipelineGraph 有 id、label、default_model、max_total_tokens、default_timeout_secs、result_fidelity、nodes、edges、subgraphs。后三个 graph 级字段是旧稿没有的
• PipelineNode 除了 prompt 和 handler，还包含 model、context_window、max_output_tokens、max_iterations、tools、goal_gate、max_retries、timeout_secs、suggested_next、converge、worker_prompt、planner_model、max_tasks、deadline_secs、deadline_action、checkpoints，以及 human_gate（:163）、resolver（:166）、artifact_refs（:169）、checkpoint_refs（:172）、continue_on_error（:184）

13.1.3 属性到节点语义的映射

节点构建发生在 build_node()（crates/octos-pipeline/src/parser.rs:579-691）。这里有几个实现细节决定了 DOT 的"作者体验"：

• Handler 解析顺序是：显式 handler= 优先，其次是 shape= 到 Handler 的映射（crates/octos-pipeline/src/graph.rs:282-297，字符串形式 from_str 在 :270-279），最后默认 Codergen（crates/octos-pipeline/src/parser.rs:581-586）
• tools="a,b,c" 会被拆成字符串列表；如果用户写了 tools=""，解析结果是一个只含空字符串的 deny-all 标记，执行器把它当成"显式禁用所有工具"处理（crates/octos-pipeline/src/parser.rs:588-602）
• timeout_secs 不只接受整数秒，也接受 900s、15m、2h 这类后缀写法（crates/octos-pipeline/src/parser.rs:551-570）
• goal_gate 允许用 true/false/yes/no/1/0 表达（crates/octos-pipeline/src/parser.rs:619-623）
• deadline_secs 支持 ms/s/m/h 和小数秒（crates/octos-pipeline/src/parser.rs:601-603，底层 parse_duration_secs_f64 在 :665-689）；deadline_action 支持 abort、skip、escalate、retry:N 和 retry(N) 两种写法（crates/octos-pipeline/src/parser.rs:693-720）
• checkpoint="true" 或 checkpoint="name1,name2" 会解析成 MissionCheckpoint 声明（crates/octos-pipeline/src/parser.rs:721-751）
• max_iterations 现在是可写的节点属性（crates/octos-pipeline/src/parser.rs:620，字段在 crates/octos-pipeline/src/graph.rs:140），见 13.2.1

这意味着 DOT 在 octos 里不是"纯拓扑描述"，而是一个轻量的工作流 DSL。

13.2 九种 HandlerKind 与十二种 IR 节点

HandlerKind 的真实枚举在 crates/octos-pipeline/src/graph.rs:241-266。当前源码是 9 种，旧稿写的 6 种已经过时：

还有一个容易忽略但很重要的事实：Handler trait（crates/octos-pipeline/src/handler.rs:257）的实现现在是 7 个：CodergenHandler（:641）、ShellHandler（:1054）、GateHandler（:1190）、NoopHandler（:1226）、ShellCheckHandler（:1247）、NotifyHandler（:1326）、WaitHandler（:1365）。Parallel 和 DynamicParallel 不是独立 handler 类型，而是 PipelineExecutor::execute_graph() 里的专门分支（crates/octos-pipeline/src/executor.rs:2749 / :3122）。

handler 名到字符串的映射同步扩到 9 项，含 shell_check、notify、wait（crates/octos-pipeline/src/executor.rs:251-259）。

13.2.1 Codergen：节点就是一个子 Agent

CodergenHandler（struct crates/octos-pipeline/src/handler.rs:293，impl :641-1041）会为节点创建一个完整的 octos_agent::Agent，而不是做一次简化版 LLM 调用。这意味着节点天然继承了主 Agent 的很多能力：工具调用、循环式执行、token 统计、文件修改回传、进度事件上报。

它的关键行为有几层：

1. Provider 解析。 如果节点声明了 model，并且执行器配置了 ProviderRouter，handler 会走 router.resolve()，然后再包一层 capability-compatible fallback provider。这不是单纯的"model name -> provider"映射，而是带回退链的解析。
2. 上下文窗口覆盖。 context_window 会包装成 ContextWindowOverride。
3. 工具注册。 节点初始工具集来自 ToolRegistry::with_builtins()，然后应用一次性缓存的 plugin registration，避免每个节点重复做插件 SHA 校验和可执行文件读取（crates/octos-pipeline/src/handler.rs:23-56）。
4. 工具策略。 节点自己的 tools= 决定 allowlist；handler 仍会额外 deny spawn、run_pipeline、send_file、message，避免子节点递归失控；随后还会清理 spawn_only 标记，让原本 spawn_only 的插件工具在 pipeline worker 内同步执行（crates/octos-pipeline/src/handler.rs:125-130）。
5. 父会话资源继承。 如果 run_pipeline 从 session actor 内触发，节点 worker 会继承父会话的 FileStateCache、SubAgentOutputRouter、AgentSummaryGenerator、CostAccountant 和 parent session key（crates/octos-pipeline/src/host_context.rs:34-60、from_tool_context 在 :78）。
6. 系统提示词与任务输入分离。 执行器会先把 {input} 从 prompt 中移除，只保留角色/约束类说明；真正的前驱输出通过 TaskKind::Code.instruction 传给子 Agent。

和旧稿差异很大的一点是迭代预算：早期版本把 AgentConfig.max_iterations 硬编码成 30，节点无法干预。现在 PipelineNode.max_iterations（crates/octos-pipeline/src/graph.rs:140）是可写的 DOT 属性，build_node() 直接解析（crates/octos-pipeline/src/parser.rs:620）。字段注释写明了动机：pipeline 默认 30 次迭代对"逐个读 findings 文件再综合"的 synthesize 节点太低，预算耗尽在导航文件上、结果没发出来就把整条 pipeline 拖死。None 保持默认值。

另外，max_output_tokens 的默认行为也不是"全局 4096"。如果节点没写这个属性，handler 会退回到 provider 自身的最大输出能力。这对长报告生成很关键。

13.2.2 Shell：实现了，但被验证规则封禁

ShellHandler 本身仍是完整实现（struct crates/octos-pipeline/src/handler.rs:1043，impl :1054-1135）：命令来源是 node.prompt，非 Windows 下 sh -c、Windows 下 cmd /C，默认超时 300 秒，非零退出码映射成 OutcomeStatus::Fail，进程启动失败或超时映射成 OutcomeStatus::Error。