astrid-runtime/book · 上手攻略

  • 仓库：astrid-runtime/book
  • 链接：https://github.com/astrid-runtime/book
  • 分类：ai-os
  • 作者：Jay
  • 更新：2026-07-15

这是什么

astrid-runtime/book 是 Unicity Astrid OS 的权威技术参考文档，同样基于 mdBook 构建。它是理解 Astrid 操作系统内部设计的完整手册，面向构建 Capsule（胶囊）或深入理解系统架构的开发者。

Astrid OS 是一个专为 AI Agent 设计的操作系统，它的核心设计哲学是：像操作系统对待进程一样对待 AI Agent——隔离它、限制它的权限、记录它的一切行为，并且不需要信任它。

手册覆盖 9 大部分、共 40+ 章节，从内核三大法则到加密审计链，完整呈现了系统的每一层设计。

注意：unicity-astrid/handbook（贡献者手册）与本书（系统参考）是两份不同的文档。贡献者手册告诉你如何给 Astrid 投稿；本书告诉你 Astrid 本身是怎么工作的。

解决什么问题

当你在构建一个真实的 AI Agent 系统时，会遇到几个根本性问题：

  1. 信任问题：如何让 AI Agent 执行你不完全信任的任务，而不担心数据泄露或权限滥用？
  2. 隔离问题：如何让多个 Agent / 多个工具互不干扰，某个工具的 bug 不会波及整个系统？
  3. 可审计问题：当 Agent 执行了某个危险操作，如何事后证明"它做了什么、什么时候做的、依据是什么"？
  4. 可扩展问题：如何让工具（Astrid 中称 Capsule）以标准化方式接入系统，而不是硬编码？

Astrid OS 通过以下设计回答这四个问题：

  • 零信任安全模型：Agent 运行在 WebAssembly 沙箱中，无任何环境权限；每个操作都需要 Capability 签名授权
  • Capsule 隔离架构：每个工具是独立编译的 WASM 模块，内核只做路由和鉴权，不含业务逻辑
  • 五层安全门 + 密码学审计链：每一层都独立验证，审计链哈希环环相扣，不可篡改
  • Host ABI 标准化接口：所有 Capsule 通过统一的系统调用接口与宿主机交互，支持热插拔

快速安装（本地预览）

# 克隆仓库
git clone https://github.com/astrid-runtime/book.git
cd book

# 安装 mdbook（如尚未安装）
cargo install mdbook

# 本地预览
mdbook serve --open
# 浏览器打开 http://localhost:3000

核心用法

1. 先跑通 See It Work（动手体验）

手册推荐从实际运行开始：

# 安装 Astrid CLI
cargo install astrid

# 初始化（选择 Provider、填入 API Key）
astrid init

# 开始对话
astrid chat

# 在另一个终端观察系统状态
astrid capsule list   # 查看当前加载的 Capsule
astrid caps list      # 查看当前授权的 Capabilities
astrid logs           # 查看运行日志

⚠️ 版本说明：cargo install astrid 安装的是 CLI，内含 daemon 和 build 工具链。内核版本 0.7.0（参考 handbook polyrepo map）。

2. 理解 Astrid 的架构核心：Kernel-Is-Dumb

这是理解整个系统的钥匙。内核只做三件事，绝不越界：

内核职责 具体内容
路由（Routing） EventBus 接收 IPC 事件，分发给订阅者
鉴权（Gating） 每个 KernelRequest 触发 capability 检查，缺失权限直接 reject
验证（Validating） 检查 PrincipalId 格式、Quota 上限、Capsule.toml 合法性

内核结构体 Kernel 的字段清单就是这三个职责的代码级证明——event_bus、capsules、capabilities、audit_log……没有任何 LLM 相关字段。

3. Capsule 模型（开发核心）

Capsule 是 Astrid 的基本计算单元，本质是一个 WebAssembly 模块，声明式地描述它需要什么权限（imports）和提供什么能力（exports）。

Capsule 的生命周期：

安装 → 加载（验证签名 + capability 授信）→ 实例化 WASM → 订阅 Topics → 运行
                                                              ↓
                                              销毁 → 清理 workspace 副本

Capsule 之间通过 IPC topics 通信，内核只做消息路由，不解码 payload 内容。这意味着你可以新增一个 Topic 订阅者来扩展功能，而无需修改内核。

4. Host ABI 系统调用面

Capsule 通过标准化的 Host ABI 调用宿主机能力，分类如下（具体接口以源码为准，手册可能滞后）：

Package 能力
fs 文件系统读写（路径由 capability 白名单限制）
io 标准输入输出
storage KV 持久化存储
net 网络访问（同样受 capability 控制）
http HTTP 请求
process 进程 / Shell 命令执行
approval 交互式用户授权（用于需要人类确认的操作）
identity PrincipalId 和身份管理
uplink 与 CLI 前端的 Unix Socket 通信

5. Capability 权限模型

核心原则：零默认权限（fail-closed）。Agent 没有任何 ambient authority，每次操作必须持有对应 capability。

# 查看当前会话的所有 granted capabilities
astrid caps list

Capsule.toml 中声明 [imports]，初始化时内核逐一授权。如果 Agent 尝试调用未被授权的 capability，host ABI 返回 PermissionError，内核拒绝执行。

6. 五层安全门

从请求发出到执行完成，经过五层独立验证（详见 Security/Five-Layer Gate）：

  1. Principal 认证（谁在调用）
  2. Capability 检查（是否有权）
  3. Policy 评估（该操作是否在 policy 允许范围内）
  4. Budget / Quota 检查（是否超限）
  5. Approval 拦截（是否需要人工确认）

7. 密码学审计链

每次敏感操作都写入哈希链表（类似区块链），每条记录包含： - 操作内容 - 时间戳 - PrincipalId - 前一条记录的哈希

修改任何历史记录都会导致后续所有哈希断裂，可检测、可证明。

8. 关键阅读路径

你的目标 推荐章节
先跑通看效果 Getting Started: See It Work
写自己的 Capsule Part II: Capsule Model + Part III: Host ABI
理解信任与安全 Part V: Security（五层安全门、Capability、审计链）
理解 IPC / 消息总线 Part IV: The Bus
理解存储与状态 Part VI: Storage and State
变更公共接口（ABI/WIT） Part IX: Evolution（RFC 流程）

典型适用场景

场景 Astrid 的优势
运行第三方 / 不可信 Agent WebAssembly 沙箱 + 零默认权限，jailbreak 也无法突破 capability 边界
多 Agent 协作 每个 Agent 是独立 Principal，Per-Principal 隔离，互不干扰
高安全合规环境 五层安全门 + 密码学审计链，可事后举证
工具调用链路审计 所有 IPC 事件和 capability 授予记录全部留存
替换 LangChain Agent Astrid 的 Capsule 模型是更结构化的工具定义，kernel-is-dumb 使内核稳定

坑与注意

  1. 文档可能滞后于代码：handbook 明确指出——代码优先，文档次之。当两者矛盾时，源码是 ground truth。本书的接口描述需要对照源码交叉验证。
  2. Astrid 仍处于活跃开发阶段（2025-2026），部分章节标注为 stub 或尚无生产调用者，阅读时注意区分"已实现"和"规划中"。
  3. cargo install astrid 可能耗时较长：需要编译整个 Rust 项目（内核 + daemon + CLI），建议在有足够资源的机器上执行，或等待官方提供预编译二进制。
  4. Provider 需要 API Key：Astrid 支持 Anthropic / OpenAI / OpenAI-compatible 端点，但需要自行准备 key。没有 key 的情况下 astrid chat 无法完成推理。
  5. Capsule 开发需要 Rust：Astrid 的 SDK 是 Rust 写的（sdk-rust），编写新 Capsule 目前主要使用 Rust。如果你想贡献 Capsule，需要熟悉 Rust + WebAssembly。
  6. Appendix 是代码生成的：Capability Catalog、Host ABI Error Codes、Topic Registry 由源码中的 tools/gen-appendices.sh 和 tools/gen-see-also.pl 自动生成，说明这些内容与实现高度一致，但需要运行脚本从 polyrepo 源码中重新生成。

与同类对比

系统 定位 与 Astrid 的关键区别
LangChain / LangGraph Agent 应用框架 非 OS 级隔离，依赖 LLM API，无强安全模型
AutoGPT / CrewAI Agent 编排 纯 Python 进程隔离，安全靠 prompt engineering
E2B 云端代码执行沙箱 隔离粒度是 VM/容器，非 WASM
Midspace / Anthropic Artifacts 代码执行环境 面向终端用户，非系统级 Agent OS
Astrid OS AI Agent 操作系统 OS 级零信任、WASM 沙箱、Capsule 标准化、安全可审计

Astrid 的差异化在于：它把安全边界做到操作系统级别，而不是依赖应用层的 prompt 约束。对于需要运行不受信任或半可信 Agent 的场景，这是目前开源生态中最系统化的方案。

一句话推荐结论

如果你在构建需要运行不可信 Agent、多工具协作或合规审计的系统，Astrid OS 的 WASM 沙箱 + capability 模型 + 密码学审计链提供了目前开源领域最完整的 OS 级安全基础——先读本书的 Getting Started 跑通 demo，再按需深入各子系统。