Astrid Polyrepo地图：一张表看懂19个仓库在AI Agent运行时中的分工-平芜编程栈

Astrid Polyrepo地图：一张表看懂19个仓库在AI Agent运行时中的分工

【免费下载链接】handbookContributor handbook for Astrid: the polyrepo, public contracts, contribution process, and release workflow.项目地址: https://gitcode.com/gh_mirrors/handbook76/handbook

Astrid 是一个基于 WASM 沙箱的 AI Agent 运行时，它的源码采用polyrepo（多仓库）架构：除了内核、SDK、RFC 三个基础仓库外，还有19 个独立仓库的胶囊（Capsule），各自承担 AI Agent 运行时的不同职能。这篇指南用一张 Polyrepo 地图，带你快速看懂 Astrid 的 22 个仓库（3 个基础 + 19 个胶囊）如何分工协作，以及在新手参与贡献前必须知道的操作细节。

🧭 全景速览：一张表看懂 Polyrepo 结构

Astrid 不是一个 monorepo。本地工作目录下，每个组件都是一个独立的 git 仓库，层叠在同一个父目录中。完整清单如下：

本地路径	远端仓库	层级	在 AI Agent 运行时中的分工
`core/`	`astrid`	基础	内核、守护进程、CLI：事件路由、能力校验、WASM 沙箱宿主
`sdk-rust/`	`sdk-rust`	基础	胶囊开发 SDK（`astrid-sdk`、`astrid-sdk-macros`、`astrid-sys`）
`astrid-rfcs/`	`rfcs`	基础	内核-用户空间契约的设计提案（RFC），无版本号
`capsules/astrid-capsule-agents/`	`capsule-agents`	胶囊	Agent 编排
`capsules/astrid-capsule-react/`	`capsule-react`	胶囊	响应式事件处理（认知循环）
`capsules/astrid-capsule-session/`	`capsule-session`	胶囊	会话生命周期管理
`capsules/astrid-capsule-skills/`	`capsule-skills`	胶囊	技能（Skill）加载器
`capsules/astrid-capsule-prompt-builder/`	`capsule-prompt-builder`	胶囊	Prompt 组装
`capsules/astrid-capsule-context-engine/`	`capsule-context-engine`	胶囊	上下文窗口管理
`capsules/astrid-capsule-memory/`	`capsule-memory`	胶囊	持久化 Agent 记忆
`capsules/astrid-capsule-registry/`	`capsule-registry`	胶囊	模型注册表与当前模型选择
`capsules/astrid-capsule-openai/`	`capsule-openai`	胶囊	OpenAI 模型提供商接入
`capsules/astrid-capsule-openai-compat/`	`capsule-openai-compat`	胶囊	OpenAI 兼容推理路由
`capsules/astrid-capsule-fs/`	`capsule-fs`	胶囊	文件系统宿主函数
`capsules/astrid-capsule-http/`	`capsule-http`	胶囊	出站 HTTP 请求
`capsules/astrid-capsule-shell/`	`capsule-shell`	胶囊	Shell 命令执行（`host_process`特权豁免）
`capsules/astrid-capsule-identity/`	`capsule-identity`	胶囊	认证与主体（Principal）管理
`capsules/astrid-capsule-users/`	`capsule-users`	胶囊	用户管理
`capsules/astrid-capsule-system/`	`capsule-system`	胶囊	系统级能力
`capsules/astrid-capsule-router/`	`capsule-router`	胶囊	IPC 主题路由
`capsules/astrid-capsule-cli/`	`capsule-cli`	胶囊	CLI 前端的 Unix socket 桥接（Uplink）
`capsules/astrid-capsule-hook-bridge/`	`capsule-hook-bridge`	胶囊	Hook 桥接胶水层

📌 命名规律：本地目录统一叫astrid-capsule-<name>，而 GitHub 远端仓库去掉前缀，只叫capsule-<name>。这是新手最容易踩坑的地方。

🔒 分工核心法则：内核"很笨"，胶囊"干活"

Astrid 的架构有一条硬性法则——内核是笨的（The Kernel Is Dumb）：

内核只干三件事：路由 IPC 事件、执行能力校验、管理 WASM 沙箱。它不含任何业务逻辑、没有 LLM 胶水代码、没有会话状态
所有智能都住进胶囊：Prompt 组装、模型选择、工具调度、会话管理、记忆读写——分别由capsule-prompt-builder、capsule-registry、capsule-session、capsule-memory各自承载
胶囊之间只通过 IPC 事件总线通信：内核只负责投递字节，永远不解包也不解释负载的语义
契约变更必须先写 RFC：主机 ABI、IPC 主题格式、能力令牌、Capsule.toml清单、VFS 语义、SDK 公开 API 这 7 类"契约面"的任何改动，都要先在astrid-rfcs/走 RFC 流程

简单说：内核管"能不能做"，胶囊管"做什么"。这也是为什么 19 个胶囊仓库比内核更重要——AI Agent 的绝大部分行为都由它们定义。

🛠️ Polyrepo 实战：Git 操作的 3 个关键细节

先cd再git：git命令只对当前所在的那个仓库生效。在 Polyrepo 根目录跑git status，看到的既不是内核也不是 SDK 的状态
分支永远从origin/main切出（本地main经常是过期的），并使用feat/、fix/、refactor/等 Conventional Commits 风格命名；提交必须带 GPG 签名
构建目标因仓库而异：
组件目标平台 Rust 工具链
core/（内核）宿主机 1.95
sdk-rust/（SDK）宿主机 1.94
19 个胶囊 wasm32-unknown-unknown 1.94（由各自rust-toolchain.toml锁定）
⚠️ 胶囊不要手动传--target，每个胶囊的.cargo/config.toml已替你选好目标；用内核的 cargo 去编译胶囊会编译失败。

组件	目标平台	Rust 工具链
`core/`（内核）	宿主机	1.95
`sdk-rust/`（SDK）	宿主机	1.94
19 个胶囊	`wasm32-unknown-unknown`	1.94（由各自`rust-toolchain.toml`锁定）

另外，贡献者分为New / Astrinaut / Core / Maintainer四级，由 CI 的contributor-gate任务强制：8 个安全关键 crate（如astrid-crypto、astrid-capabilities、astrid-audit）只对高层级贡献者开放，新手改非核心 crate（CLI、SDK、胶囊、文档）即可起步。