astrid-runtime/handbook · 上手攻略

  • 仓库：astrid-runtime/handbook
  • 链接：https://github.com/astrid-runtime/handbook
  • 分类：工程手册 / 贡献者文档（mdBook）
  • 作者：spark
  • 更新：2026-07-15

是什么

astrid-runtime/handbook 是 Unicity Astrid OS 的 贡献者手册——专门写给"在 Astrid 内部改代码的人"（改 kernel、SDK、契约面、参考 capsule 的工程师），而不是给"用 Astrid 做应用的人"。后者请读配套的 astrid-runtime/book（The Unicity Astrid OS Book，参考规范）和 astrid-runtime/sdk-js（JavaScript/TypeScript SDK）。

整个仓库是一个 mdBook 工程（Rust 生态最常用的静态文档站点生成器），源码放在 src/ 下，由 SUMMARY.md 编排章节，编译产出 book/ 静态站点。

目录骨架：

Introduction
├── Working on Unicity Astrid OS: The Polyrepo and Git Workflow
├── The Kernel-Is-Dumb Law
├── The RFC Trigger
├── Contribution Tiers and Security-Critical Crates
└── Release Process and Coding Standards

仓库许可证：MIT + Apache 2.0 双协议（LICENSE-MIT、LICENSE-APACHE），Copyright 2025-2026 Joshua J. Bouw and Unicity Labs。

解决什么问题

Astrid OS 是一个 polyrepo（kernel / SDK / RFCs / 每个 capsule 各成一个 git 仓库，全归在 unicity-astrid 组织下）。新人贡献者最容易踩的坑：

  • 在错误的仓库提 PR。
  • 不知道什么改动算"契约变化"、什么时候必须先发 RFC。
  • 提交时没 GPG 签名、版本号 bump 没拆 PR、没附 issue 引用。
  • 把业务逻辑塞进 kernel，破坏 "kernel-is-dumb" 架构约束。

这份手册把上面这些"操作规矩"写死成 5 个章节，强制新人先读后改。

快速安装 / 本地阅读

# 方式 1：在线读（最快）
# 直接打开 GitHub 仓库页面或 mdBook 的 GitHub Pages：
#   https://astrid-runtime.github.io/handbook/  （如有 Pages 部署）

# 方式 2：本地 mdBook 阅读（推荐贡献者）
# 安装 mdBook
cargo install mdbook           # 需要 Rust 工具链

# 克隆并启动热重载预览
git clone https://github.com/astrid-runtime/handbook.git
cd handbook
mdbook serve --open            # 浏览器打开 http://localhost:3000，文件改动自动刷新

# 纯构建（输出到 ./book 目录）
mdbook build

mdbook serve --open 就是 README 里唯一一行命令，跑通就算"安装成功"。

核心用法（贡献者必须吃的三页）

三条总律（introduction.md · Three rules that govern everything）

  1. The kernel is dumb：kernel 只做三件事——路由事件、强制 capability、跑沙箱。不放业务逻辑。任何"kernel 路由不了 / 不把关 / 不验证"的东西，都属于 capsule-space IPC，不属于 kernel 类型。这是架构铁律，不是风格偏好。违反它 = 系统开始腐烂。
  2. RFCs are for contract changes：改 kernel ↔ user space 的"表面"必须先发 RFC：host ABI、IPC schema、capability model、manifest schema、VFS 语义、capsule interface standards、SDK public API。kernel 内部实现改动若保持 guest 可见契约不变，不需要 RFC。提 PR 前先确认属于哪类。
  3. Ground in the code：文档（包括本仓库老 README）会漂；代码是真相。代码与文档冲突 = 文档是 bug，立即提 PR 改文档，永远以源码为准。

Polyrepo 与 Git 工作流（handbook/polyrepo-and-workflow.md）

Astrid OS 是 polyrepo，不是 monorepo：

内容 仓库 归口
Kernel（最薄最纯） unicity-astrid/kernel kernel 团队
SDK（JS/TS） astrid-runtime/sdk-js SDK 团队
规范（"参考书"） astrid-runtime/book 规范维护者
每个 capsule unicity-astrid/<capsule-name> 各 capsule owner
RFC 文档 unicity-astrid/rfcs RFC 流程

改 kernel 不可能顺手改 SDK 的 public API；改 capsule 不能改 kernel 任何类型；改 host ABI 一定跨多个仓库 → 必须 RFC 先行。

The RFC Trigger（handbook/rfc-trigger.md）

何时必须发 RFC——只要命中下列任意一项，先开 RFC 仓库下的 issue + 草稿，再动代码：

  • Host ABI：syscall 表、寄存器约定、调用栈帧。
  • IPC schema：跨边界消息结构、序列化协议。
  • Capability model：cap token 的 grant / attenuate / revoke 语义。
  • Manifest schema：capsule 元数据。
  • VFS semantics：路径解析、挂载、权限。
  • Capsule interface standards：capsule 间通信契约。
  • SDK public API：暴露给 capsule 开发者的方法签名。

不属于上述的 kernel-internal 重构、bug fix、内部性能优化不需要 RFC，但仍要按 release 流程走。

Contribution Tiers and Security-Critical Crates（handbook/contribution-tiers.md）

贡献等级：

  • T1：文档、示例、测试用例、低风险 helper——1 reviewer approve + CI 通过即可合并。
  • T2：常规 SDK / capsule 代码、IPC 实现、内部 API——1 maintainer approve + 全部测试通过。
  • T3（安全关键）：capability gating、sandbox 执行、密钥处理、签名校验、host ABI——必须双 reviewer（含至少 1 名 security maintainer）、要求额外 fuzz/audit 测试、合并前需签核。

哪些 crate 算"security-critical"，仓库会维护一张清单（以 handbook 当下版本为准），改这些 crate 的 PR 会自动被打 security label。

Release Process and Coding Standards（handbook/release-and-standards.md）

  • 版本号 bump 永远独立成 PR（"version-bump" / "chore: bump" 类），不允许和功能改动混在同一个 PR。
  • 每个核心 PR 必须关闭一个 GitHub issue，PR 描述里 Closes #xxx。
  • Commit 必须 GPG 签名（git commit -S），GitHub UI 显"Verified"。
  • 任何非琐碎改动，作者先做"对抗性自审"：问自己"凌晨三点生产环境，这段会怎么挂？违反了哪条 invariant？"，再请求 review。
  • 编码规范：rustfmt + clippy 强制、unsafe 代码必须 // SAFETY: 注释、crate 公开 API 必须有 doctest。

典型适用场景

  • 首次给 Astrid 提 PR 的贡献者：先读 Introduction → Polyrepo → RFC Trigger，确认自己改的东西要不要 RFC，再动键盘。
  • Capsule 作者：本手册不是你的菜，你应该看 astrid-runtime/book 和 astrid-runtime/sdk-js；但当你需要申请一个"host ABI 增项"或新 manifest 字段时，要按本手册的 RFC 流程走。
  • Kernel 维护者：日常 PR review 时直接对照 contribution tier 和 coding standards 来挡。
  • 安全审计：根据 contribution tiers 章节判断哪些 crate 属于 T3，单独走审计通道。
  • 组织 lead：把 introduction 的"三条总律"作为新人入职第一天必读内容。

坑与注意

  1. 仓库边界容易搞错：polyrepo 模式下，unicity-astrid/ 组织是 Astrid OS 早期命名空间（kernel、capsules、rfcs 在这里），astrid-runtime/ 是规范/SDK/手册命名空间（book、sdk-js、handbook 在这里）。两个前缀不同但属于同一个生态。贡献者要先确认目标仓库属于哪个前缀，避免去错地方提 PR。
  2. Introduction 第一句就是隐喻警告："If the agent lives inside the labyrinth, you are one of the people who build its walls."——这个项目极度强调"边界神圣"，对契约违规零容忍。新人友好度不高，需严肃对待。
  3. GPG 签名是硬门槛：没签名的 commit 不会被合并。先在本地 git config commit.gpgsign true，并把 GPG 公钥加到 GitHub。
  4. RFC ≠ Issue：RFC 是写在 unicity-astrid/rfcs 仓库的正式文档流程（issue + 草稿 + 评审 + 接受），不要把普通 feature request 标成 RFC。
  5. 文档会漂：仓库自己反复提醒——README 在早期可能过期，以代码为准。贡献者改文档时也要承担这个责任。
  6. 安全 crate 列表随版本变：T3 名单不是写死的，每次 minor release 都可能增减，改之前先 grep 最新版 handbook。
  7. mdBook 本地版 vs GitHub Pages 版本：线上版本可能滞后几个小时，调试新文档用本地 mdbook serve。
  8. 版权与许可证：双协议 MIT + Apache 2.0，贡献代码即同意按此双协议授权；下游商用请保留署名。
  9. 这是一个早期项目（2025–2026 起步）：流程文档可能还在快速迭代，章节命名、贡献等级细节可能在 minor version 之间变动；建议在 PR 时先确认 handbook 当前版本。

与同类对比

  • Linux Kernel Documentation/process/：kernel 新人入门的"how to work on Linux"模板。Astrid handbook 是它的微缩 + 现代化 + Rust 化 + mdBook 化版本。
  • Rust 自身 rust-lang/rust 的 CONTRIBUTING.md / rfc/：Rust 项目也有"RFC 触发器 + 贡献等级 + FCP 流程"。Astrid handbook 直接继承了这套范式，只是把"语言设计 RFC"换成了"host ABI / IPC schema / capability model RFC"。
  • Chromium /docs/contributing.md：大型 polyrepo + 安全敏感项目的工作流样板；Astrid handbook 在体量上更小，但骨架是同款（双 reviewer、Tier 制度、签名 commit、独立版本 PR）。
  • astrid-runtime/book（配套的"参考书"）：讲 kernel / capsule / host ABI / IPC / 安全模型是什么；handbook 讲怎么改。两者搭配阅读，不要混为一谈。
  • astrid-runtime/sdk-js：JS/TS SDK 文档，胶囊作者入口；handbook 与它正交，handbook 面向内核/SDK 维护者。
  • unicity-astrid/handbook（Jay 认领段的同名不同 owner）：是另一个"Astrid 风格"组织 unicity-astrid 的手册，两套生态、不同项目，不要混淆。

一句话推荐结论

要改 Astrid OS 内核、SDK、契约面之前，先读 introduction 的三条总律，再按 mdbook serve 起一份本地手册，逐章核对自己的改动是否触 RFC / 跨仓库 / 安全临界——这是这个 polyrepo 的最低门槛。胶囊作者请左转去 astrid-runtime/book 和 sdk-js，别把手册当成应用开发文档读。