文档教程【免费下载链接】bookThe canonical reference for Astrid: kernel, capsules, host ABI, IPC, and the security model.项目地址https://gitcode.com/gh_mirrors/book269/book点击查看免费下载导读astrid build是 Astrid 生态中将一个 Rust capsule 源码树编译为.capsule安装归档的标准工具其实现位于core/crates/astrid-build。本文以该工具为线索深入讲解 WASM 目标的选定规则、wasm32-unknown-unknown下getrandom自定义后端的双层机制、Component Model 组件封装步骤、Capsule.toml清单合并、WIT 暂存以及.capsule归档格式。读完本文你将掌握从源码到可安装归档的每一步细节并能在自己的 capsule 项目中正确配置.cargo/config.toml、排查构建问题、理解归档内部结构。说明文档中引用的core/crates/astrid-build、astrid-sys、capsules/等源码路径属于 Astrid 多仓库polyrepo源码树与本书为同级目录详见 README.md 的说明本文同时给出本书内可直接阅读的关联章节链接。一、调用构建器命令与项目类型探测astrid build的典型调用方式如下# 在 capsule 源码目录中运行自动探测项目类型 astrid build # 指定输出目录 astrid build --output dist/ # 显式覆盖项目类型 astrid build --type rust库入口点是astrid_build::run()源码src/lib.rs:54命令分发逻辑位于src/build.rs。项目类型探测按顺序检查以下标记文件Cargo.toml—— Rust capsulegemini-extension.json—— Gemini 扩展类项目package.json—— Node 类项目如 MCP capsulemcp.json—— MCP 配置类项目Capsule.toml—— 兜底视为纯静态 capsulesrc/build.rs:66-98。对于 Rust capsulebuild::run_build将工作委托给rust::buildsrc/rust.rs:40高层步骤为校验cargo是否在PATH中解析cargo metadata获得包名、版本与 WASM 产物名以 release 模式编译注入必要的RUSTFLAGS定位编译生成的.wasm二进制按需将其封装为 Component Model 组件将Capsule.toml与若有提取的描述信息合并暂存wit/目录打包为.capsuletar.gz 归档。与本书另一篇 Getting Started: Your First Capsule 中的astrid capsule build相比astrid build是更底层、可独立面向源码目录调用的构建器而astrid capsule build则是 CLI 封装后的完整流水线入口cargo 编译、组件封装、签名打包一并完成。二、WASM 目标选择wasm32-unknown-unknown是唯一合法目标2.1 为什么必须是wasm32-unknown-unknown每一个 Astrid capsule 都必须以wasm32-unknown-unknown为目标。这是一条硬性架构约束而不是约定。该目标产出的 core WASM 模块零wasi:*导入capsule 对宿主的每一次调用都必须经由astrid:*这一 WIT 接口面到达内核且全程能力门控capability-gated与审计。换言之WIT 导入列表就是 capsule 的能力清单——任何调用都无法绕过审计从未审计的 WASI 后门溜过去。内核链接器只注册astrid:*接口一旦 capsule 意外携带wasi:*导入加载时就会以 interface not found 失败这正是设计预期的姿态详见 The Host ABI: The Syscall Surface。对应地每个随树发布的 capsule 都携带如下配置以capsules/astrid-capsule-skills/.cargo/config.toml为例[build] target wasm32-unknown-unknown [target.wasm32-unknown-unknown] rustflags [--cfggetrandom_backend\custom\]其中[build] target一行保证直接调用cargo build不经astrid build时也会编译到正确架构。2.2astrid build如何确定目标构建器不会向 Cargo 传--target而是让 capsule 自身的.cargo/config.toml决定目标架构。函数compile_wasmsrc/rust.rs:139通过cargo_config_target_and_rustflags读取该配置同时尊重调用方环境中的CARGO_BUILD_TARGET环境变量该变量优先级高于配置文件与 Cargo 自身的优先级规则一致。编译完成后locate_wasm_binarysrc/rust.rs:329探测产物const TARGETS: [str] [wasm32-unknown-unknown];它会同时检查本地target/目录与工作区target/根目录从而覆盖工作区构建Cargo 可能将产物重定向到工作区根的情况。三、getrandom 自定义后端为wasm32-unknown-unknown补上熵源3.1 问题根源wasm32-unknown-unknown没有任何平台级随机数来源。getrandomcrate 会通过uuidv4 与HashMap播种被传递引入在未显式配置后端时拒绝在该目标上链接——最直接的表现是HashMap首次构造时因播种失败而 panic。解决方案是一个双层机制。3.2 第一层cfg 标志每个wasm32-unknown-unknowncapsule 的.cargo/config.toml中必须包含[target.wasm32-unknown-unknown] rustflags [--cfggetrandom_backend\custom\]这会激活getrandom的自定义后端协议该协议要求在二进制中存在一个名为__getrandom_v03_custom的#[no_mangle]符号。3.3 第二层astrid-sys中的符号实现astrid-sys/src/lib.rs第 133 行提供该符号仅在target_arch wasm32与getrandom_backend custom两个条件同时成立时条件编译#[cfg(all(target_arch wasm32, getrandom_backend custom))] #[unsafe(no_mangle)] unsafe extern Rust fn __getrandom_v03_custom( dest: *mut u8, len: usize, ) - Result(), getrandom::Error { const CHUNK: usize 4096; let mut written 0usize; while written len { let want core::cmp::min(CHUNK, len - written); let chunk generated::astrid::sys::host::random_bytes(want as u64) .map_err(|_| getrandom::Error::new_custom(1))?; // 拷贝 min(chunk.len(), want) 字节到 dest推进 written written take; } Ok(()) }该实现调用astrid:sys/host.random-bytes由内核的 OS CSPRNG 提供服务。按astrid:sys的 WIT 契约这个调用有意不做能力门控、也不审计只读、无副作用length单次上限 4096 字节更大请求返回too-large。因为astrid-sys始终处于依赖图中任何依赖astrid-sdk的 capsule 无需逐 capsule 接线即可获得可用的 CSPRNG。在宿主侧工具构建build scripts、proc-macros、开发者机器上的cargo test中cfg 标志不存在该符号被整体省略改用宿主平台默认 RNG。astrid-sys/build.rs同时声明该 cfg 已知以抑制unexpected_cfgslintprintln!(cargo::rustc-check-cfgcfg(getrandom_backend, values(\custom\)));3.4 第三层安全网astrid build的自动注入capsule 的.cargo/config.toml中保留该标志是为了让不经astrid build的cargo build也能正常工作。但如果某个 capsule 缺失该配置项astrid build会自动注入。encoded_rustflags_with_getrandomsrc/rust.rs:255的处理逻辑为仅在wasm32-unknown-unknown下生效任何其他目标直接返回None环境保持不变折叠已有标志读取调用方环境中已有的CARGO_ENCODED_RUSTFLAGS或RUSTFLAGS保证开发者设置的标志不丢失合并配置文件的 rustflags读取 capsule.cargo/config.toml中声明的rustflags数组形式与空格分隔字符串形式均可并追加追加 getrandom cfg若尚未出现--cfggetrandom_backendcustom则补上写回环境结果写入CARGO_ENCODED_RUSTFLAGS标志之间用 ASCII 单元分隔符\u{1f}分隔并移除RUSTFLAGS从而既保证含空格的标志存活又避免两个来源同时生效。随后 Cargo 在不传--target的情况下被调用环境标志只作用于 WASM 产物。由于这是一次交叉编译宿主并非wasm32该标志只到达 guest 产物不会影响 build scripts 或 proc-macros。去重是有意为之且范围收窄只对 getrandom 这一个 cfg 去重。若做 token 级去重会破坏像-C opt-level3 -C debuginfo2这样的多 token 标志第二个-C会被误删。而重复的完整标志对rustc是无害的。四、组件封装从 core WASM 到 Component Model 组件wasm32-unknown-unknown构建产物是 core WASM 模块而非 Component Model 组件。wit-bindgen的generate!宏会在模块中嵌入一个component-type自定义段描述组件的导入与导出Component Model 链接器读取该段以完成组件适配。ensure_componentsrc/rust.rs:291通过读取 WASM 魔数区分两种情况core 模块魔数\0asm版本字段第 4–7 字节为0x00 0x00 0x00 0x01组件魔数\0asm版本字段为0x00 0x00 0x01 0x00第 6 字节的 layer 位为0x01。当输入是 core 模块时使用wit_component::ComponentEncoder进行封装let component wit_component::ComponentEncoder::default() .validate(true) .module(bytes)? .encode()?;校验是开启的。如果wit-bindgen的generate!宏未被使用或产出了错误的自定义段ComponentEncoder会以清晰的错误拒绝该模块而不是静默产出一个损坏的组件。封装结果写回输入产物同路径因此Capsule.toml中对crate_name.wasm的引用无需任何清单改动即可继续解析。五、Capsule.toml清单安装器的契约capsule 清单是安装器的契约。若 capsule 源码目录中已存在Capsule.tomlastrid build会用toml_edit读取并解析它从清单既有内容中填充[package] description字段旧版本还曾从名为astrid_export_schemas的 WASM 导出中提取描述该导出路径如今已是 no-op 桩extract_capsule_description位于src/rust.rs:535——随着 Component Model 迁移描述完全来自源码中的Capsule.toml。若不存在Capsule.toml则合成一个最小清单[package] name astrid-capsule-example version 0.1.0 description [[component]] id astrid-capsule-example file astrid_capsule_example.wasm type executable真实 capsule 的Capsule.toml还会声明 IPC 订阅与发布。[subscribe]与[publish]表使用 topic 通配模式并关联 WIT 类型[subscribe] tool.v1.execute.list_skills { wit unicity-astrid/wit/types/tool-call, handler tool_execute_list_skills } [publish] tool.v1.execute.*.result { wit unicity-astrid/wit/types/tool-call-result }这些表键本身就是内核的 IPC ACLcapsule 只能发布到匹配[publish]键的 topic、只能订阅匹配[subscribe]键的 topic完整清单语义参见 The Capsule Manifest and Engines。清单从内存直接写入归档绝不经过临时文件因此归档内的Capsule.toml始终是构建时合并的结果。六、WIT 暂存把 schema 装进归档astrid build会暂存 capsule 的 WIT 文件并纳入归档使安装器在目标机器上无需 SDK 源码树即可获得 schema 信息。stage_wit_directorysrc/rust.rs:420在workspace_target/.astrid-wit-staging/生成暂存目录布局如下.astrid-wit-staging/ [capsules own .wit files, or a stub package] deps/ astrid-contracts/ astrid-contracts.wit ← 来自 astrid-sdk 源码的共享 SDK 契约其中的 stub 包STUB_WIT_PACKAGE用于在 capsule 没有本地 WIT 时为wit-parser的push_dir提供根包锚点。共享 SDK 契约的定位方式是在cargo metadata中搜索astrid-sdk包然后读取其 crate 根下的wit/astrid-contracts.wit。若 SDK 源码不可用如发布构建、缺少 registry 源码会发出警告并在归档中省略共享契约。七、.capsule归档格式gzip 压缩的 tar.capsule文件是一个 gzip 压缩的 tar 归档。pack_capsule_archivesrc/archiver.rs:12按如下顺序写入条目Capsule.toml—— 直接从内存字符串写入而非从磁盘读取WASM 二进制若存在Rust capsule 这里是被组件封装后的产物其他上下文文件skills、commands、README 等以base_dir下的相对路径存放暂存后的wit/目录递归写入归档路径wit/。归档器显式启用符号链接解引用tar.follow_symlinks(true)而不是依赖库默认值。符号链接在归档前即被解析为真实内容——安装器解压路径会拒绝符号链接作为安全措施。append_dir_recursivesrc/archiver.rs:117中的循环检测以规范化路径跟踪已访问目录当符号链接解析到已访问目录时跳过并告警而不是引发无限递归和 OOM。归档条目在解压时会校验不含绝对路径与不含../路径穿越组件见src/build.rs:139的测试辅助函数unpack_capsule。若归档超过 50 MBLARGE_ARCHIVE_BYTESsrc/archiver.rs:9会触发体积警告并提示 node_modules 膨胀是 Node 类 MCP capsule 体积过大的典型原因。输出文件命名为crate_name.capsule默认置于./dist/或由--output指定的目录。八、构建前置安装 rustup target在构建 Rust capsule 之前需先安装对应 rustup targetrustup target add wasm32-unknown-unknown缺少该 target 时编译会直接失败。若使用astrid capsule new脚手架其会在 target 缺失时主动询问是否添加或通过--install-target跳过提示参见 Your First Capsule。九、最小 capsule.cargo/config.toml参考一个规范的 capsule 在其源码树中携带如下配置[build] target wasm32-unknown-unknown [target.wasm32-unknown-unknown] # 将 uuid v4 / HashMap 的 RNG 播种路由到 astrid:sys/host.random-bytes。 # 必需因为 wasm32-unknown-unknown 没有平台熵源。 # astrid build 会作为兜底自动注入但保留在此可使 # 不经 astrid build 的纯 cargo build 与 cargo test 也能工作。 rustflags [--cfggetrandom_backend\custom\]两个缺失各有代价缺少[build] target不经astrid build的cargo build会以宿主平台为目标产出原生二进制而非 WASM 模块缺少rustflags条目cargo build无法链接uuidv4 或任何在初始化时播种HashMap的 crate。astrid build会捕获缺失的标志但该配置项对开发者直接运行cargo check/cargo test的开发工作流是必需的。十、实践要点小结目标是架构约束而非约定wasm32-unknown-unknown是唯一的 capsule 构建目标零wasi:*导入是审计完备性的前提熵源是双层方案.cargo/config.toml的 cfg 标志 astrid-sys的__getrandom_v03_custom符号astrid build另有自动注入兜底组件封装开启校验ComponentEncoder::validate(true)拒绝畸形模块产物写回原路径以保持清单引用稳定归档契约清晰Capsule.toml从内存写入、符号链接预先解引用、解压侧拒绝穿越路径、50 MB 体积告警调试入口明确astrid_build::run()src/lib.rs:54→build::run_build→rust::buildsrc/rust.rs:40目标选择看compile_wasm与locate_wasm_binary。构建完成后.capsule归档即可进入安装链路——安装器的解压、内容寻址存储bin/与wit/store/、meta.json写入等后续环节详见 Distros and the Content-Addressed Store构建产物的能力边界最终由内核的ManifestSecurityGate在每次宿主调用前强制见 Capability Gating。参见Distros and the Content-Addressed StoreThe Syscall SurfaceThe Capsule Manifest and EnginesCapability GatingGetting Started: Your First Capsule赞分享文档教程【免费下载链接】bookThe canonical reference for Astrid: kernel, capsules, host ABI, IPC, and the security model.项目地址https://gitcode.com/gh_mirrors/book269/book点击查看免费下载相关推荐unicity-astrid/build 构建流水线深度解析从 TypeScript 类到 WASM Capsule 的编译器unicity astrid/build 构建流水线深度解析从 TypeScript 类到 WASM Capsule 的编译器 导读 unicity asAstrid Capsule 构建指南使用 astrid-build 将 Rust 与遗留 MCP 项目打包为 .capsuleAstrid Capsule 构建指南使用 astrid build 将 Rust 与遗留 MCP 项目打包为 .capsule Astrid 是可移植、基于unicity-astrid/sdk 全解析用 TypeScript 构建 Astrid OS 用户态 Capsule 的系统 SDKunicity astrid/sdk 全解析用 TypeScript 构建 Astrid OS 用户态 Capsule 的系统 SDK 导读 unicit上一篇Jellium Desktop媒体格式基础教程轻松掌握格式支持与播放技巧下一篇BongoCat桌面伴侣应用完整使用手册5分钟打造专属互动猫咪创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考