unicity-astrid/handbook · 上手攻略

  • 仓库：unicity-astrid/handbook
  • 链接：https://github.com/astrid-runtime/handbook
  • 分类：developer-docs
  • 作者：Jay
  • 更新：2026-07-15

这是什么

unicity-astrid/handbook（当前托管于 astrid-runtime/handbook）是 Unicity Astrid OS 贡献者手册，一本用 mdBook 构建的电子书籍，面向直接在 Astrid 操作系统源码层面工作的开发者，而非使用 Astrid 构建 AI 应用的终端用户。

如果你在构建一个 Capsule（胶囊，即 Astrid 中的插件/扩展单元），你更需要看的是《Astrid OS Book》（astrid-runtime/book）这个前端文档；如果你在修改内核、SDK、公共契约面或参考胶囊的实现，则先读这本手册。

手册覆盖以下核心主题：

章节 内容
Polyrepo 与 Git 工作流 内核、SDK、RFC、Capsule 各仓库的关系与本地目录布局
Kernel-Is-Dumb 法则 内核只做路由、鉴权、验证，不含任何业务逻辑
RFC 触发机制 何时需要提 RFC、RFC 的适用范围
贡献等级与安全关键 crate 不同等级的贡献对应哪些审查要求
发布流程与代码规范 版本号规范、GPG 签名提交、Issue-First PR 规则

解决什么问题

Astrid 是一个多仓库（polyrepo）操作系统，内核、SDK、二十余个 Capsule 和 RFC 提案各在独立的 Git 仓库中维护。初次参与贡献的开发者如果不理解仓库边界、贡献规则和 RFC 触发条件，很容易在错误的地方修改代码，或发出需要打回重做的 PR。

这本手册就是贡献者的"操作手册"：在动手之前，先把 Polyrepo 结构、提交规范、安全审查流程和版本策略全部讲清楚，减少来回沟通成本，保证代码质量和安全审计的完整性。

快速安装（本地预览）

# 克隆仓库（当前 redirect 到 astrid-runtime/handbook）
git clone https://github.com/astrid-runtime/handbook.git
cd handbook

# 安装 mdbook（如果还没有）
cargo install mdbook

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

构建无需额外依赖，mdBook 会自动处理 src/ 下的 Markdown 并渲染为 HTML。

核心用法

1. 理解 Polyrepo 布局

本地工作目录包含多个独立 Git 仓库：

your-workdir/
├── core/                    # unicity-astrid/astrid          (内核、CLI、daemon)
├── sdk-rust/               # unicity-astrid/sdk-rust       (Rust SDK)
├── astrid-rfcs/            # unicity-astrid/rfcs            (设计提案)
└── capsules/               # 各 capsule 独立仓库
    ├── astrid-capsule-cli/
    ├── astrid-capsule-fs/
    ├── astrid-capsule-http/
    └── ... (共 20+ 个)

每个 Capsule 的 GitHub 仓库名省略 astrid-capsule- 前缀，例如 capsule-cli 仓库对应 unicity-astrid/capsule-cli。

2. 正确的 Git 操作方式

⚠️ 每个仓库是独立的：在哪个目录运行 git，操作的就是哪个仓库。不要在父目录运行 git log 来查看内核历史。

# 查看内核日志（正确）
cd core
git log --oneline -5

# 永远从远程 main 创建分支，不要直接 commit 到 main
git fetch origin
git checkout -b feat/your-feature origin/main

# 提交规范遵循 Conventional Commits
git commit -m "feat(emit): astrid-emit, agent-agnostic stdio→bus hook pipe"

3. GPG 签名提交

所有提交必须 GPG 签名。如果遇到 gpg failed to sign the data，可能是沙箱阻止了 GPG：

# 尝试验证最近提交是否已签名
git log --format="%H %G?" -5
# G? 字段应为 G（good），N = 无签名，U = 未知

4. 理解 Kernel-Is-Dumb 法则

这是 Astrid 架构的第一性原则：内核只做三件事：

内核职责 说明
路由（Routing） 通过 EventBus 接收事件并分发给订阅者
鉴权（Gating） 在请求到达 handler 之前校验 capability
验证（Validating） 检查 PrincipalId、Quotas、Capsule.toml 等类型合法性

永远不能放进内核的东西：业务逻辑、LLM 调用、Prompt 组装、模型选择、会话管理、Provider 集成。这些全部属于 Capsule 范畴。

5. 判断是否需要提 RFC

RFC 是公共契约变更的正式提案。触发条件为：

  • 变更 host ABI（系统调用接口）
  • 变更 IPC schema
  • 变更 capability model
  • 变更 manifest schema、VFS 语义
  • 变更 Capsule 接口标准
  • 变更 SDK 公开 API

内核内部修改（不改变 Guest 可见契约）不需要 RFC。

6. 提交 PR 的 Issue-First 规则

内核（core/）的每个 PR 必须关联一个 GitHub Issue，CI 会检查 PR body 中是否引用了 Issue。

# 先建 Issue，拿到编号
# 然后在 PR body 中写：Closes #<issue-number>

典型适用场景

  • 新贡献者 onboarding：第一次给 Astrid 投稿之前必读，理解仓库边界和工作流程
  • Capsule 开发者确认接口规范：当你不确定某个功能应该在 Capsule 还是内核实现时，查手册的 Kernel-Is-Dumb 法则
  • 安全审查：安全关键 crate 的额外审查要求在 Contribution Tiers 章节有明确定义
  • 发布工程师：理解版本号分离 PR 规则、Distro.toml / Distro.lock 的角色

坑与注意

  1. 不要在 polyrepo 根目录执行 git 命令：新手常犯的错误，以为 git log 会查所有子仓库，它只查当前 worktree。
  2. HTTPS push 而非 SSH：Astrid 环境没有 SSH 密钥，所有 push 都要用 HTTPS URL，显式指定远程地址。
  3. RFC 触发条件容易误判：如果你不确定是否需要 RFC，优先去 Issue 或 Discussion 区提问，而不是直接提 PR，否则大概率被打回。
  4. GPG 签名失败：沙箱可能阻止 GPG 操作，手册提到可用 dangerouslyDisableSandbox: true 重试，但这仅限 scratch 分支。
  5. 文档可能滞后于代码：手册明确说明——代码优先，文档次之；当两者矛盾时，代码是正确答案。

与同类对比

文档 定位 目标读者
handbook（本文） 贡献者操作手册：polyrepo 工作流、贡献规范、RFC 触发条件 往 Astrid 内核/SDK/Capsule 源码投稿的开发者
book（astrid-runtime/book） 系统架构参考：内核、Capsule 模型、ABI、安全模型 理解 Astrid 内部设计，或基于 ABI 构建 Capsule 的开发者
sdk-js / sdk-rust SDK API 文档 使用 Astrid SDK 编写 Capsule 的开发者

如果你做的是业务层面的 AI 应用集成（调用现成 Capsule），你可能根本不需要这本手册，只需要 book 或 SDK 文档。

一句话推荐结论

想参与 Astrid OS 内核/SDK/Capsule 开发？先读这本手册搞清楚"哪个仓、什么规范、要不要 RFC"，别用直觉代替规则——手册里写得清清楚楚的流程，比代码审查时的打回要高效得多。