【免费下载链接】aos-ceAOS Community Edition: the open agent operating system.项目地址https://gitcode.com/gh_mirrors/ao/aos-ce点击查看免费下载本文围绕 AOS Community Edition下称 AOS CE中 capsule-forge 工作区章节 的完整内容展开它规定了 agent 在为 CapsuleWASM 能力模块选择源码位置时的四条决策规则、源/构建产物/安装镜像/运行时状态的四层边界、Capsule 内部应使用的 VFS 可移植路径方案以及落笔前的所有权决策清单。读完本文你可以为任何新 Capsule 确定合规的源码位置写出跨平台、可安装、可审计的便携路径并理解这些规则在 capsule-forge 源码 中的实际承载方式。1. 背景这份指南在 AOS CE 体系中的位置workspace.md并非独立的顶层文档而是 AOS 作者手册Author Manual的一个章节由capsule-forge这个作者工作台式Capsule 以工具形式按需分发。在 capsules/capsule-forge/src/lib.rs 中它被编译期嵌入到章节表GUIDE_CHAPTERSGuideChapter { topic: workspace, summary: portable source locations, repository discovery, scratch candidates, and ownership, content: include_str!(guides/workspace.md), },forge_guide工具lib.rs#L228-L247在不传topic参数或传index时返回全部章节索引传workspace时才返回本章全文。这种渐进式加载是有意为之触发技能文件 SKILL.md 中的表格明确规定workspace章节的加载时机是deciding where source belongs on this machine or in a repository——即当你正在决定源码在这台机器、这个仓库里应该放哪里时。因此本章的全部规则都是面向动手写代码之前的位置决策而非编码过程本身。2. 永远不要假设单一机器布局本章的第一条总原则不要硬编码开发者的 home 目录、仓库路径、插件缓存或运行时安装树。正确做法是从当前工作目录、仓库自带说明、CLI help、AOS 配置以及 agent 实际拥有的权限来发现当前环境。这里有一个容易混淆的关键区分已安装的运行时文件和插件缓存是部署产物deployment outputs不是源码工作区禁止在它们内部开发 Capsule。这条规则在 SKILL.md 中同样被重申为不可协商项Never develop inside an installed runtime tree or plugin cache. Never hardcode a particular users home or repository path.。为什么这条原则重要因为 AOS CE 的运行时布局是平台相关且按 principal调用主体隔离的安装目录由 AOS CLI 按平台选择Capsule 看到的是虚拟路径而非宿主机真实路径见第 4 节。硬编码某台机器的布局等价于把一份只能在单机上跑死的代码写进了一个设计上可移植的组件。3. 选择源码位置Source Home的四条规则原文给出的规则是按顺序取第一条命中的规则Use the first applicable rule完整继承如下规则 1已有仓库——遵循其既有布局如果当前工作在一个已存在的仓库中遵循该仓库的说明文件和既有的 Capsule/插件布局惯例。具体到 AOS CE monorepo 本身第一方 Capsule 位于capsules/capsule-name/下并参与工作区与发布契约。这一点可由仓库根 Cargo.toml 的 workspace members 列表直接印证——capsule-forge、capsule-fs、capsule-http等全部以capsules/capsule-name形式登记每个目录内都有Capsule.toml、Cargo.toml与src/构成统一的第一方布局。规则 2用户指定目标位置——原样使用用户显式给出了目标路径时就以它为准唯一约束是当前文件系统边界capability/sandbox 允许访问的范围。规则 3独立项目——用脚手架在当前目录或显式父目录下生成独立于任何既有仓库的新项目用 CLI 脚手架在当前工作目录生成aos capsule new name # 或显式指定父目录 aos capsule new name --path parentaos capsule new会一次生成全部初始文件见 quickstart.md 中的最小五文件集.cargo/config.toml、rust-toolchain.toml、Cargo.toml、Capsule.toml、src/lib.rs。在 Capsule 内部capsule-forge还暴露了对应的scaffold_capsule工具lib.rs#L259-L273返回相对文件路径 → 文件内容的 JSON 映射v1 仅支持tool类型它对name参数做了路径穿越校验validate_namelib.rs#L187-L197拒绝/、\、..这与不要假设机器布局、不接受任意路径注入的总原则一脉相承。规则 4agent 主动提出、尚无持久归属的候选——放进一次性工作区这是针对 agent 工作流的专门规则当你主动产生了一个候选 Capsule而它还没有持久归属durable owner时应在隔离的、可抛弃的 scratch 目录或 worktree 中创建、构建和评估它。在移动、提交、安装或发布之前如果该目标位置会实质性地改变用户项目先询问它应该放在哪里。补充约束对共享的shared或脏的dirty仓库保留既有改动当仓库策略或用户要求隔离时在做特性工作之前先从请求的 base 创建全新 worktree。4. 源码、构建产物、安装、状态是四个不同的位置本章要求把以下四层边界保持显式区分原文给出的数据流为source project - build output: dist/name.capsule - installed capsule mirror and content-addressed component bytes - principal-scoped runtime state, config, secrets, logs, and KV逐层含义层归属说明源码工程用户或仓库唯一可开发的位置dist/*.capsule可安装的构建输出由aos capsule build产生安装目录AOS CLI 决定平台相关的安装位置CLI 自动选择运行时状态principal 作用域状态、配置、密钥、日志、KV 都按调用主体隔离两条硬性规则值得特别注意Capsule 看到的是虚拟路径和按 principal 作用域的存储而不是任意宿主机路径。永远不要把原始.wasm手工拷贝进运行时树。安装过程会记录并校验内容身份content identity即安装是内容寻址的——quickstart.md 把这一点列为常见踩坑第 4 条Install viaaos capsule install, never hand-copy the.wasm— install is content-addressed.这一原则在capsule-forge的诊断逻辑中有具体体现capsule_doctor工具在排查已安装 Capsule 时读取的是安装镜像中的home://.local/capsules/name/Capsule.toml与meta.jsonlib.rs#L36-L39、lib.rs#L347-L362即安装镜像是运行时读取的权威副本而非源码树——源码、安装镜像、运行时状态三者各司其职正对应上面四层的划分。5. Capsule 内部的可移植路径使用 AOS VFS 方案在 manifest 和 SDK 代码中应使用 AOS VFS 方案scheme来表达位置本章列出三种home://— 解析到调用方 principal 的 home。cwd://— 解析到运行时提供的 Capsule/workspace 根目录。*— 可以表示宽泛的、被工作区限制workspace-confined的访问但应优先使用更窄的前缀。capsule-forge 的能力章节 对前两条给出了补充解释home://是调用 principal 的 home且随调用作用域变化cwd://是运行时提供的 capsule/workspace 根。它同时给出了收窄前缀的示范写法fs_read [home://documents/] fs_write [home://data/my-capsule/]本章的禁令同样明确不要在 Capsule 代码中嵌入/Users/...、/home/...、Windows 盘符或 shell 展开后的 home 路径。正确姿势是向 VFS 和 AOS 服务请求该 principal 被允许看到的世界——把我能访问哪里的判断权交给运行时而不是写死在组件里。这与第 2 节的不要假设单一机器布局是同一条原则在组件内部的落地home://会随调用主体而变因此同一个字节码安装给不同 principal 时看到的目录不同这正是可移植性的来源。6. 仓库所有权与生成镜像Generated Mirrors当涉及改哪里的问题时先识别规范源canonical source。本章给出两类典型情况宿主插件可能 vendor 第一方技能skill的一份快照而持久的运行时副本住在 Capsule 里。快照是分发产物不是可变的运行时状态。SKILL.md 与此呼应宿主插件可以把同一批章节 vendor 到references/topic.md下作为离线快照——use that offline snapshot when the Forge tool is unavailable但它明确不是mutable runtime state or a machine-specific source location。发布产物和安装镜像都是生成输出generated outputs除非仓库显式声明例外。涉及多个仓库时的操作规则每一处改动都应在该仓库自己 remote main 拉出的分支上进行不要为了同步一份生成镜像而悄悄去编辑一个脏的相邻仓库——应走文档化的生成或发布路径。这与第 3 节规则 4 的 scratch/worktree 约束共同构成改动永远从干净、可归因的起点出发的纪律。7. 落笔前决策清单Decision Checklist本章最后给出六个落笔前必答问题完整继承如下哪个仓库或用户空间作用域拥有这份源码What repository or user-space scope owns the source?当前 checkout 是共享的还是脏的Is the current checkout shared or dirty?这是一份持久实现还是一个隔离候选Is this a durable implementation or an isolated candidate?所选目录在其他受支持平台上存在吗Does the chosen directory exist on other supported platforms?我编辑的是源码而不是缓存或已安装运行时吗Am I editing source rather than a cache or installed runtime?谁有权授权移动、安装、授予或发布这个结果Who may authorize moving, installing, granting, or publishing the result?原文还给出了清单的兜底策略如果只有最终归属不明应继续在 scratch 中安全地推进而不是阻塞设计continue safely in scratch rather than blocking the design。保留该候选并在第一个不可逆或对外可见的边界移动、提交、安装、发布出现时再向用户确认。这与 SKILL.md 中的权限模型一致idea - source candidate - compiled artifact - installed capsule - principal grant - per-action consent - observed result各状态严格区分Generated code does not self-promote——可逆的源码编辑与编译是正常工作但安装、持久授权、发布仍需由用户/AOS/运营策略提供授权。8. 小结把四条规则压缩成一张操作表场景动作禁止已有仓库遵循其布局AOS CE monorepo 用capsules/capsule-name/硬编码机器路径用户指定位置原样使用受文件系统边界约束静默改换位置独立项目aos capsule new name/--path parent或scaffold_capsule手工拼装初始文件无主候选scratch 目录或 worktree 中构建评估首个不可逆边界前确认归属在脏仓库/安装树/插件缓存里开发Capsule 代码内路径home://、cwd://必要时收窄前缀/Users/...、盘符、shell 展开 home安装aos capsule install内容寻址手工拷贝.wasm进运行时树这些规则的共同指向是AOS CE 的可移植性建立在位置由运行时发现、权限由 principal 决定、产物由内容身份校验三点之上workspace章节正是把这三点前置到写第一行代码之前让源码选址本身成为可审计、跨平台、不与部署产物混淆的一步。赞分享【免费下载链接】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-ce capsule-forge IPC 指南:主题路由、ACL 匹配、优先级分层与工具事件流aos ce capsule forge IPC 指南:主题路由、ACL 匹配、优先级分层与工具事件流 本篇基于 capsules/capsule forge/deepseek-harness-desktop 工作区准入所有权重构用 ElectronWorkspaceAdmission 收拢桌面端路径决策deepseek harness desktop 工作区准入所有权重构用 ElectronWorkspaceAdmission 收拢桌面端路径决策 导读 本文人工智能AI 应用AI Agent桌面应用插件系统DeepSeekdsh-plugin上一篇如何为ta-lib-python搭建GitLab CI/CD自动化测试与部署的完整指南 下一篇MyLayout实战案例剖析从电商应用到社交APP的完美布局解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考