【免费下载链接】aos-ceAOS Community Edition: the open agent operating system.项目地址https://gitcode.com/gh_mirrors/ao/aos-ce点击查看免费下载本文基于 AOS Community Edition下称 AOS CE中 Forge 胶囊内置的作者手册首章 foundations.md系统讲解 Unicity AOS 的三层技术栈AOS、Astrid Runtime、Forge、八类核心工件的定义、最小持久化工件选型决策流程以及胶囊Capsule的架构约束与组合规则。读完后你将能够理解 AOS 中内核保持简单、智能位于用户空间的设计哲学并为自己的 agent 能力扩展选对承载形态——从一段记忆、一个 Skill 到一个受治理边界的 WASM 组件。一、技术栈三层分工各司其职Foundations 章节开篇给出了 AOS 生态的三层划分。理解这三层各自的职责边界是理解后续所有工件选型的前提。1.1 Unicity AOSagent 的操作系统文档原文的定位是Unicity AOS is an operating system for agents. It supplies a governed user space in which agents can compose instructions, skills, memory, context, models, tools, capsules, providers, connectors, workers, traces, and evaluations.即 AOS 为 agent 提供一个受治理governed的用户空间agent 在其中组合指令instructions、技能skills、记忆memory、上下文context、模型models、工具tools、胶囊capsules、模型提供方providers、连接器connectors、工作者workers、追踪traces与评测evaluations。仓库 README 中Build on AOS一节的表述与之呼应胶囊是通用的用户空间构建块用户可以把它们组合成 harness、meta-harness、连接器、服务等系统。1.2 Astrid Runtime低层内核机制文档将 Astrid Runtime 定义为 AOS 之下的低层机制职责明确且克制路由类型化 IPCtyped IPC加载并计量meterWASM 组件执行manifest 能力与主题 ACL把工作限定在principal主体作用域内存储状态并对副作用进行审计。随之而来的核心设计原则是原文的一句话Keep the kernel simple. Domain logic and policy intelligence belong at capsule edges.保持内核简单领域逻辑与策略智能应位于胶囊边缘。这一点在 Forge 胶囊自身的实现中得到印证。lib.rs 的模块文档写道所有操作都通过内核的 VFS 和能力系统完成胶囊无法绕过沙箱边界All operations go through the kernels VFS and capability system — the capsule cannot bypass sandbox boundaries。quickstart.md 也把内核描述为笨dumb的内核只负责路由事件和执行能力检查所有智能都住在胶囊里The kernel is dumb — it routes events and enforces capabilities; all intelligence lives in capsules。1.3 ForgeOS 级构建工作台文档对 Forge 的定位Forge is AOSs construction workbench. It helps an agent inspect contracts, scaffold a capsule, choose capabilities, validate a manifest, and diagnose an installation. Forge is part of a meta-harness; it is not the supervisor and it does not grant its own output authority.即 Forge 帮助 agent检查契约inspect contracts、脚手架化一个胶囊scaffold a capsule、选择能力choose capabilities、校验 manifestvalidate a manifest、诊断安装diagnose an installation。同时划出两条关键边界Forge 是 meta-harness 的一部分但它不是监督者也不赋予自身输出任何权威性。从源码看这条边界是如何落地的capsule-forge/src/lib.rs 中的GUIDE_CHAPTERS常量把 12 章作者手册foundations、workspace、capsule、manifest、capabilities、ipc、wit、skills、authority、build、security、meta-harness通过include_str!编译进 WASM 组件由forge_guide工具按主题渐进式提供。Capsule.toml 中 Forge 自身的能力声明极其克制——[capabilities]下只有一行fs_read [home://]它的[publish]与[subscribe]则声明了工具总线tool bus的固定话题 ACL例如[publish] tool.v1.execute.*.result { wit unicity-astrid/wit/types/tool-call-result } tool.v1.response.describe.* { wit unicity-astrid/wit/tool/describe-response } [subscribe] tool.v1.execute.forge_guide { wit unicity-astrid/wit/types/tool-call, handler tool_execute_forge_guide } tool.v1.execute.scaffold_capsule { wit unicity-astrid/wit/types/tool-call, handler tool_execute_scaffold_capsule }这正是文档所说执行 manifest 能力与主题 ACL的内核机制的具体形态[publish]/[subscribe]的键就是内核强制执行的发布/订阅 ACL。二、工件词汇表八类持久化载体的精确定义Foundations 章节给出了 AOS 生态中八类核心工件的定义。这份词汇表是整个选型决策的词典以下完整继承原文定义并补充代码层面的印证。工件定义原文语义Instruction or memory指令或记忆持久化的事实、偏好、约束或经验教训Skill技能可复用的指令与流程知识在当前工作匹配技能描述时才加载Harness执行框架模型周围的整套用户空间系统上下文组装、检索、记忆、工具、控制流、恢复与评测Meta-harness元框架反思式循环agent 注意到摩擦或杠杆点、检查自己的世界、改进它、评估变化、保留有效部分Capsule胶囊一个内聚的沙箱化 WASM 组件在 AOS 上提供工具、服务、连接器、策略边缘、状态或类型化契约Composition组合既有胶囊之间的配置与 IPC 接线Worker工作者可选的持久化或委托角色仅当安装宿主支持且工作负载受益时才引入Host plugin宿主插件面向 Codex 或 Claude 等宿主的客户端侧分发适配器可携带vendorskills、hooks、MCP 配置与命令它不替代AOS 胶囊或 AOS 权限模型两个定义值得特别展开Meta-harness 的循环结构。meta_harness_quickstart.md 把这个循环展开成一条流水线可作为词汇表条目的可视化补充do work - notice friction or leverage - inspect what exists - remember | reuse | compose | change harness code | Forge-build - evaluate - retain - continue with a better world注意其中inspect what exists与remember | reuse | compose | change harness code | Forge-build的并列关系——这正对应后文最小持久化工件的选型顺序。Host plugin 的边界。原文强调宿主插件不替代 AOS 胶囊或 AOS 权限模型。capsule-forge Skill 文档 中给出了配套的分发约定宿主插件可以把 Forge 的指南章节作为references/topic.md离线快照 vendored 出去供 Forge 工具不可用时离线查阅但这只是分发快照不是可变运行态也不是机器特定的源码位置。三、选型决策从现有能力到宿主插件的七级阶梯Foundations 章节的核心方法论是一句指令Use this order. Stop as soon as the need is met.按此顺序执行需求一旦满足立即停止。原文的完整顺序是发现并复用已有的 skill、tool、capsule 或 contract配置或组合已安装的部分记住一个持久化的事实或偏好为可复用的推理或流程写一个 Skill修改 harness 代码以改进上下文、检索、规划或恢复当确实需要新的可执行行为或新的受治理边界时构建一个胶囊仅当某个特定客户端需要原生启动发现、hooks 或 MCP 适配器时添加宿主插件。3.1 三条不是授权的警示选型顺序之后原文给出三句极易被忽视但极其重要的断言仅靠 prompt 的规则不构成授权A prompt-only rule is not authorization宿主插件不是安全边界A host plugin is not a security boundary一个胶囊不会因为由 LLM 生成就变得可信A capsule does not become trusted because an LLM generated it。这三句话在仓库中多处得到呼应。SKILL.md 的权限模型一节定义了状态链idea - source candidate - compiled artifact - installed capsule - principal grant - per-action consent - observed result并声明Generated code does not self-promote生成代码不能自我提升authority.md 更进一步指出安装、授予 principal 持久访问、扩展现有安装的能力/ACL、启动持久宿主进程、写出作用域外、触发外部效应等边界不能仅仅因为源码是被生成的就静默跨越。此外lib.rs 中的单元测试authority_manual_separates_construction_from_activation甚至把Generated code cannot self-promote作为必须存在的文本断言写进了测试说明这条边界是项目用测试钉死的不变量。3.2 渐进式加载为什么手册不一次性给出从源码结构看Forge 把这 12 章手册设计成渐进式披露progressive disclosureforge_guide工具不带参数或传index/list/help大小写不敏感时返回章节索引传具体topic时才返回该章全文。lib.rs 中的实现会先把主题参数做小写化与分隔符归一化_、空格转-再在GUIDE_CHAPTERS中查找。测试author_manual_is_progressive_and_complete对每一章都断言不少于 35 行防止手册章节退化成空壳。这种设计本身就体现了本文的方法论agent 不应一次性吞下全部参考材料而应只加载当前决策需要的章节——正如 SKILL.md 中加载时机表Load when对每个主题给出的触发条件。四、胶囊架构wasm32 目标、audited 导入与 manifest 声明Foundations 章节对胶囊的架构描述虽然简短却定义了 AOS 胶囊区别于普通 WASI WASM 插件的全部硬约束。4.1 编译目标与宿主效应通道原文两条硬约束胶囊的目标是wasm32-unknown-unknown而非 WASI宿主效应host effects必须通过astrid-sdk暴露的、经过审计的astrid:*WIT 导入进行。SKILL.md 的Non-negotiable capsule boundaries一节把这扩展成完整清单[publish]/[subscribe]键视为被强制执行的 ACL调用者身份必须读自内核盖章的上下文kernel-stamped context而非 payload 里的声称环境、home 路径、秘密与状态必须按 principal 作用域隔离不得全局缓存安装物必须用aos capsule build构建.capsule归档——裸 WASM 不可安装。4.2 Capsule.toml 声明什么文档列出 manifest 的五类声明内容组件与打包资产components and packaged assets宿主能力如文件、网络、进程、身份访问host capabilities[publish]与[subscribe]的主题 ACL 及 handler 绑定类型化的导入与导出typed imports and exports安装期配置、命令、MCP 服务器与上下文文件install-time configuration, commands, MCP servers, and context files。以 quickstart 中最小胶囊 manifest 为例前四类声明一目了然摘自 quickstart.md[package] name my-capsule version 0.1.0 description What this capsule does authors [Your Name youexample.com] astrid-version 0.7.0 [[component]] id my-capsule file my_capsule.wasm # hyphens - underscores, .wasm type executable [capabilities] fs_read [home://] [publish] tool.v1.execute.*.result { wit unicity-astrid/wit/types/tool-call-result } tool.v1.response.describe.* { wit unicity-astrid/wit/tool/describe-response } [subscribe] tool.v1.execute.hello { wit unicity-astrid/wit/types/tool-call, handler tool_execute_hello } tool.v1.request.describe { wit unicity-astrid/wit/tool/describe-request, handler tool_describe }对照 Forge 自己的 Capsule.toml可以看到两条容易被新作者漏掉的工具总线样板tool-bus boilerplatetool.v1.execute.*.result与tool.v1.response.describe.*这两行[publish]是强制项——缺少它们工具结果永远回不来describe 扇出fan-out也无从应答。[subscribe]中每个#[astrid::tool]工具对应一行tool.v1.execute.tool话题并绑定tool_execute_toolhandler而tool_describe由#[capsule]宏自动生成、在 manifest 中声明但不手写。4.3 有效权限 多层授权的交集缺失即失败文档给出了权限计算的核心公式The effective authority is the intersection of the components imports, the manifest, the principals grants, operator policy, and any runtime consent. Missing authority fails closed.即有效权限 组件导入 ∩ manifest ∩ principal 授权 ∩ 操作者策略 ∩ 运行时同意且缺失权限失败关闭fail closed。capabilities.md 把 fail-closed 语义具体化到每个字段列表默认空、布尔默认 false并强调能力声明是必要但不一定充分的——principal、操作者策略或运行时同意可以进一步收紧使用。同一章节还列出了完整的字段目录uplink、net、kv、fs_read、fs_write、host_process、allow_persistent、net_bind、net_connect、identity、allow_prompt_injection并明确告诫不要发明shell、internet、filesystem或通用admin这类不存在的 manifest 能力lib.rs 中的测试capability_manual_names_the_complete_current_surface会逐个断言这些字段名出现在能力手册中防止手册与当前能力面漂移。五、组合规则小而内聚的权限单元Foundations 章节的 Composition rule 给出了 AOS 胶囊设计的第一性原则优先选择权限内聚的小型胶囊Prefer small capsules with cohesive authority拆分红线如果一个候选胶囊同时需要文件、网络、进程、身份与 prompt 注入等互不相关的授权除非这些能力真正属于同一个安全边界否则应拆分通过类型化 IPC 组合胶囊而不是把所有能力塞进一个二进制Compose capsules over typed IPC rather than embedding every capability in one binary。从源码结构看这条规则在工具链中有对应的执行辅助suggest_capabilities工具把自然语言意图映射为精确的 manifest 能力行lib.rs 中suggest_from_intent覆盖文件、HTTP、TCP、KV、进程、套接字、身份与 LLM 提供方/消费者等场景而 capabilities.md 的能力选择工作流第 4 步明确要求把不相关的权限分离到另一个胶囊Separate unrelated authority into another capsule。capsule_doctor则负责安装后诊断读取home://.local/capsules/name/Capsule.toml交叉检查[imports]是否被任何已安装胶囊的meta.jsonexports 满足输出{ level, message, fix }结构的诊断项——这正是文档diagnose an installation职责的实现载体。六、导航读完 Foundations 之后加载哪些章节原文档结尾是一份next read导航本质上是 Forge 手册章节间的依赖图。结合 lib.rs 中GUIDE_CHAPTERS的完整注册可整理为下表路径均相对于仓库根目录先读章节触发条件workspace.md决定源码应该放在哪里之前capsule.md、manifest.md、capabilities.md开始实现之前ipc.md涉及工具、handler、中间件、分层或优先级skills.md分发 agent 指令或宿主插件时authority.md安装、授权或激活新能力之前meta-harness.mdagent 正在扩展自己的用户空间世界时这份导航的设计意图值得点明Foundations 章回答的是什么放在哪里what belongs where其余章节各自回答一个更具体的子问题——源码位置、项目解剖、manifest 全貌、能力面、IPC 语义、WIT 契约、技能分发、授权模型、安全审查。agent 的工作流应当是当前决策需要什么就加载哪一章这与 Forge 把触发型 Skill 保持简短测试断言 capsule-forge SKILL.md 全文少于 500 行、把权威细节全部放在forge_guide章节里的渐进式架构是同一套思想的两个侧面。七、小结把最小持久化工件变成可执行的纪律回顾 foundations.md 的核心脉络可以浓缩为三条可操作的纪律分层纪律内核Astrid Runtime只做类型化 IPC 路由、能力与 ACL 执行、principal 作用域与审计一切领域逻辑与策略智能放在胶囊边缘。写代码前先用 Capsule.toml 这类真实 manifest 对照[publish]/[subscribe]键与 handler 的对应关系确认自己理解manifest 键即 ACL这一机制。选型纪律按复用 → 组合 → 记忆 → Skill → harness 代码 → 胶囊 → 宿主插件七级阶梯逐级尝试需求满足即停同时牢记 prompt 规则不是授权、宿主插件不是安全边界、LLM 生成的胶囊不自动可信。权限纪律有效权限是组件导入、manifest、principal 授权、操作者策略与运行时同意的交集缺失即 fail closed胶囊应保持权限内聚跨话题的异质授权宁可拆成多个胶囊走类型化 IPC。这三条纪律在仓库中并非只存在于文档层forge_guide的章节完整性测试、能力字段目录测试、权限手册边界断言lib.rs 测试模块共同构成了对这份手册自身内容的持续守护确保 agent 从 Forge 读到的基础概念与当前运行时能力面始终一致。赞分享【免费下载链接】aos-ceAOS Community Edition: the open agent operating system.项目地址https://gitcode.com/gh_mirrors/ao/aos-ce点击查看免费下载相关推荐aos-ce capsule-forge 的权限模型Agent 主动性、OS 授权、同意与激活的边界分离aos ce capsule forge 的权限模型Agent 主动性、OS 授权、同意与激活的边界分离 本文围绕 Unicity AOSaos ce 社区AOS Community Edition 的 capsule-context-engine 深度解析可插拔上下文窗口压缩引擎的设计与实现AOS Community Edition 的 capsule context engine 深度解析可插拔上下文窗口压缩引擎的设计与实现 在 UnicityBoot2Docker存储模型分层文件系统与数据持久化方案Boot2Docker存储模型分层文件系统与数据持久化方案 Boot2Docker作为轻量级Docker运行环境其存储模型设计直接影响容器数据的安全性和系统云原生开发工具操作系统上一篇Angular指令开发指南基于johnpapa/styleguide的最佳实践下一篇Remotion错误恢复机制渲染失败的自动重试与断点续传创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考