ARTICLE DETAIL

资讯详情

深耕网站视觉设计与运营推广的一线实战洞察。

Astrid OS Book:源码驱动文档生成与 mdBook 技术参考书构建实践

Astrid OS Book:源码驱动文档生成与 mdBook 技术参考书构建实践 文档教程【免费下载链接】bookThe canonical reference for Astrid: kernel, capsules, host ABI, IPC, and the security model.项目地址https://gitcode.com/gh_mirrors/book269/book点击查看免费下载导读本文讲解 Unicity Astrid OS 官方技术参考书The Unicity Astrid OS Book的构建方式与文档工程实践。这本以 mdBook 构建的 canonical reference 覆盖内核、胶囊模型、宿主 ABI、总线与安全模型且其关键附录能力目录、宿主 ABI 错误码、主题注册表全部由源码自动生成。读完本文你将掌握如何在本仓库用mdbook serve --open本地运行整本书、附录生成与跨章节See also脚注生成工具的运行前提与原理以及生成式文档如何在仓库中落地以源码为唯一事实源的工程规范。一、这本书是什么以源码为锚点的 canonical referenceREADME.md 的第一句即定义了本书的定位Unicity Astrid OS 的权威参考canonical reference覆盖五大主题域内核kernel包括 启动序列、内核原则 The Kernel Is Dumb胶囊模型capsule model清单manifest、引擎、导入导出与依赖解析、生命周期、胶囊设计见 src/capsule-model宿主 ABIhost ABI系统调用面、能力门控、ABI 演进及各能力包见 src/host-abi总线bus主题与通配符、拦截器、作为 IPC 约定的工具、按主体路由与背压见 src/bus安全模型security model五层安全门、能力与令牌、策略/预算/审批/审计、OS 进程沙箱见 src/security。与常见的宣传型文档不同这本书在 引言 中明确声明其写作纪律本书逐字对照真实代码带有文件与行号锚点并将已交付并测试与已规划或桩实现严格区分——当某个函数还是 stub 时书中会直接写明当某个路径没有生产调用方时书中也会写明。也就是说这本参考书是你在需要精确知道某物如何工作时引用它的文本而非入门读物。整本书的章节编排由 src/SUMMARY.md 维护分为九大部分加后记与附录Part I Foundations内核原则、启动序列Part II The Capsule Model清单、依赖、生命周期、设计Part III The Host ABI系统调用面与六大能力包Part IV The Bus主题、拦截器、工具即 IPC、路由与背压Part V Security五层门、能力令牌、审计、沙箱Part VI Storage and StateVFS 覆盖层、KV、审计链Part VII IdentityPrincipalId、配置档/组/配额Part VIII Distribution发行版与内容寻址存储、构建管线Part IX EvolutionRFC 流程、WIT 契约Afterword 三章The Labyrinth / The Lineage / The NamesakeAppendices 三章能力目录、错误码、主题注册表二、本地构建与运行mdbook serve --openREADME 给出了最小可运行路径本仓库是一个标准的 mdBook 工程源码目录为src构建配置见 book.toml。只需一行命令即可在本地起一个带实时预览的站点mdbook serve --open该命令会编译src/下的全部 Markdown 章节 → 生成静态站点 → 在本地起 HTTP 服务并在浏览器中打开。book.toml 关键配置解读当前 book.toml 的配置要点如下配置项值作用titleThe Unicity Astrid OS Book站点标题authorsJoshua J. Bouw, Unicity Labs作者元数据descriptionThe canonical reference for Unicity Astrid OS…站点描述利于搜索引擎与 Agent 检索languageen文档语言srcsrcMarkdown 源目录output.html.default-theme/preferred-dark-themeayu默认与深色主题保证深色环境下阅读体验一致output.html.git-repository-url/edit-url-template上游 GitHub 仓库为每页生成编辑本页链接方便读者直接提交改进output.html.fold.enabletruelevel 1启用侧边栏章节折叠output.html.search.enabletruelimit-results 30启用站内全文搜索限制单次结果 30 条如果你只是阅读这本书而不修改仓库直接用mdbook serve --open即可需要离线 PDF 等格式时mdBook 生态通常通过插件扩展但本仓库只声明了 HTML 输出未包含 PDF 等额外输出插件。三、生成式附录tools/gen-appendices.sh与单一事实源README 强调三份参考附录不是手写的而是从 Astrid 源码自动生成的。这是本书文档工程最值得借鉴的部分——附录内容永远与源码保持一致杜绝手写文档与实现漂移。执行脚本bash astrid-book/tools/gen-appendices.sh脚本源码见 tools/gen-appendices.sh其头部注释明确了纪律These appendices are GENERATED, not hand-written. Do not edit the output files. Edit the source of truth (the Rust constants and the WIT files) and re-run this script.输出文件不可手改改事实源Rust 常量与 WIT 文件后重跑脚本。脚本的运行前提polyrepo 源树脚本与 README 都强调两者会读取 polyrepo多仓库的源码树因此必须在包含core/、wit/、capsules/这三个兄弟目录的检出根目录运行。也就是说仓库中的tools/脚本设计为在多仓库工作区源码仓库与本书仓库平级下运行仅 clone 本书仓库时无法直接生成附录。也可通过环境变量ASTRID_SRC覆盖源码根目录见脚本第 15 行ROOT${ASTRID_SRC:-$(pwd)}输出目录固定为$ROOT/astrid-book/src/appendix。附录 1Capability Catalog能力目录生成输入core/crates/astrid-core/src/capability_grammar.rs中的CAPABILITY_CATALOG常量。生成逻辑脚本第 25-63 行用 Perl 从 Rust 源码中提取CapabilityInfo { id, description, scope, danger }结构拼出 Markdown 表格。生成的 src/appendix/capability-catalog.md 还编码了两套语义作用域Scopeself表示该能力只作用于调用方自身的主体global表示可作用于任意主体或系统级状态。危险等级Danger tiers由低到高为 Safe → Normal → Elevated → Extreme。当前生成的目录共34 项管理能力例如system:shutdownglobal / Extreme优雅停止 Astrid 守护进程、capsule:installglobal / Extreme安装胶囊影响全主机、caps:grantglobal / Extreme可铸出通配*授权属于元权限——谁拥有它谁就能自我提权、invite:issueElevated铸出邀请令牌令牌即认证。目录顺序本身属于稳定线上契约的一部分Order matches the catalog, which is part of the stable wire contract。该附录头部还说明同一份CAPABILITY_CATALOG是内核漂移测试kernel drift tests与网关/api/sys/capabilities路由共享的唯一事实源——也就是说这份附录同时约束了内核能力实现与网关对外暴露的 API。目录之外脚本还会从源码中提取运行时豁免能力Runtime exemption capabilitiesCAP_RESOURCES_UNBOUNDED→system:resources:unbounded、CAP_NET_BIND→net_bind、CAP_UPLINK→uplink。这类能力不是管理 API 能力而是操作员授予的 profile 能力用于解除运行时上限每次调用的 CPU epoch 中断或 bind/uplink 限制胶囊不能通过自己的 manifest 自我授予它们。附录 2Host ABI Error Codes宿主 ABI 错误码生成输入wit/host/*.wit中各包中的error-code变体。脚本第 70-92 行为每个*.wit文件解析variant error-code { ... }中的具名分支按包分节输出。协议约定每个可失败的宿主函数都返回result_, error-code其中unknown(string)分支携带宿主格式化的详情字符串作为兜底而具名分支让胶囊可以在不解析文本的情况下匹配特定失败。生成的 src/appendix/error-codes.md 按 WIT 包分类例如fs1.0.0not-found、access、capability-denied、boundary-escape、invalid-path、would-block、quota、cross-vfs、already-exists等ipc1.0.0capability-denied、rate-limited、backpressure、quota等注意backpressure是显式错误码对应总线背压语义net1.0.0airlock-rejected、name-unresolvable、not-tcp、connection-refused等kv1.0.0invalid-key、cas-mismatchCAS 冲突等。对胶囊开发者而言这份附录就是宿主 ABI 的错误契约速查表——写胶囊时直接按包名匹配具名错误分支而不是靠解析字符串。附录 3Topic Registry主题注册表生成输入capsules/*/Capsule.toml的 publish/subscribe 表 core/crates/astrid-kernel/src中的内核主题常量。脚本第 98-110 行用 grep 提取形如agent.v1.command.sphere.*的版本化主题字符串去重排序后按命名空间分组输出。生成的 src/appendix/topic-registry.md 列出静态声明的主题按命名空间组织例如agent.*agent.v1.response、agent.v1.stream.delta等、astrid.*astrid.v1.lifecycle.*、astrid.v1.audit.entry、astrid.v1.approval等、cli.*、client.*等。附录明确提示胶囊在运行时通过拼接 correlation id 构造的回复主题如...response.corr_id不在枚举之列其约定见总线章节Topics and Wildcards。四、跨章节关联tools/gen-see-also.pl与See also脚注README 提到第二个生成器跨章节的 See also 脚注由 tools/gen-see-also.pl 生成。脚本用手写的关系映射表%rel编码各章在架构上的联系例如foundations/kernel-is-dumb→ 关联foundations/boot-sequence、bus/topics-and-wildcards、host-abi/the-syscall-surfacesecurity/five-layer-gate→ 关联security/capabilities-and-tokens、security/policy-budget-approval-audit、storage/audit-chain、security/os-process-sandboxbus/topics-and-wildcards→ 关联bus/interceptors、bus/tools-as-ipc、bus/routing-and-backpressure。关键工程细节幂等idempotent脚本会先删除文件末尾已有的## See also节再重新生成第 114 行反复执行不会叠加内容链接计算link_for按两章是否同目录生成相对链接——同目录用name.md跨目录用../dir/name.md运行前提同样要求多仓库根目录源码中handbook/前缀的章节属于astrid-handbook仓库其余属于astrid-book见file_for第 89-93 行。脚本运行时输出see-also footers written to N chapters便于确认影响范围。这类自动维护的交叉引用解决了长文档最头疼的问题章节重组或重命名后交叉链接不再静默失效。五、文档工程总结README 背后的三条可复用原则从 README.md 与两个生成器工具中可以提炼出这本参考书文档工程的三条原则对其他技术文档仓库同样适用单一事实源Single Source of Truth能力目录、错误码、主题注册表全部由 Rust 源码 / WIT / Capsule.toml 生成手改输出文件被脚本头部注释明确禁止避免文档与代码分叉。契约可机器校验CAPABILITY_CATALOG同时被内核漂移测试与网关/api/sys/capabilities路由引用——文档生成器与测试共享同一数据源保证文档、内核、API 三者一致。交叉引用自动化且幂等章节间的关系由手写映射表声明脚注由脚本幂等生成既保留了架构含义的人工标注又避免了手工维护链接的脆弱性。对于读者而言本仓库的日常用法非常简单clone 后执行mdbook serve --open即可在浏览器中阅读完整参考书只有当你需要重新生成附录或 See also 脚注例如拿到包含core/、wit/、capsules/的多仓库检出树时才需要运行 tools/gen-appendices.sh 与 tools/gen-see-also.pl。六、许可与来源本书采用双许可证MITLICENSE-MIT与 Apache 2.0LICENSE-APACHE版权归 Joshua J. Bouw 与 Unicity LabsCopyright © 2025-2026。在基于本书内容撰写衍生文章或代码时请遵守对应许可证的署名与再分发条款。想要深入阅读正文的读者建议按 src/SUMMARY.md 的导读路径进入Getting Started: See It Work 带你几分钟跑通一个受约束的 agentThe Capsule Manifest and Engines 与 Designing Capsules 是胶囊开发者的契约起点The Five-Layer Security Gate 与 Capabilities, Tokens, and Delegation 则是理解信任边界与审计模型的核心章节。赞分享文档教程【免费下载链接】bookThe canonical reference for Astrid: kernel, capsules, host ABI, IPC, and the security model.项目地址https://gitcode.com/gh_mirrors/book269/book点击查看免费下载相关推荐Kubebuilder 文档编写标准与实践参考mdBook 构建、testdata 生成与代码示例规范Kubebuilder 文档编写标准与实践参考mdBook 构建、testdata 生成与代码示例规范 导读 本文是 Kubebuilder 项目文档编写标准开发者工具代码生成CLI云原生后端nghttp2 文档构建机制解析Sphinx 与 mkapiref.py 驱动的 API 参考生成流水线Fluent Bit 仓库实践nghttp2 文档构建机制解析Sphinx 与 mkapiref.py 驱动的 API 参考生成流水线Fluent Bit 仓库实践 本文以 Fluen可观测性日志分析云原生流处理Open Brain REST API参考大全从/search到/capture的20个端点逐一详解Open Brain REST API参考大全从/search到/capture的20个端点逐一详解 Open BrainOB1是你思考的基础设施层—上一篇dgrid技术深度解析现代Web数据网格的架构设计与性能优化下一篇Meta-Llama-3-8B-Instruct全面解析Meta革命性80亿参数对话模型深度评测创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表