前言

为什么写这本书

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 抽象讲起，概念随用随定义。
不需要：机器学习数学、模型训练经验、编译器原理、操作系统内核开发经验。

全书知识地图

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 系统时，带着四问：

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

构建 AI Agent OS：octos 架构与实现

前言