企业官网建设流程全解析

本文围绕 AOS Community Edition（下称 AOS CE）中 capsule-forge 工作区章节 的完整内容展开：它规定了 agent 在为 Capsule（WASM 能力模块）选择源码位置时的四条决策规则、源/构建产物/安装镜像/运行时状态的四层边界、Capsule 内部应使用的 VFS 可移植路径方案，以及落笔前的所有权决策清单。读完本文，你可以为任何新 Capsule 确定合规的源码位置，写出跨平台、可安装、可审计的便携路径，并理解这些规则在 capsule-forge 源码 中的实际承载方式。

1. 背景：这份指南在 AOS CE 体系中的位置

workspace.md并非独立的顶层文档，而是 AOS 作者手册（Author Manual）的一个章节，由capsule-forge这个"作者工作台式"Capsule 以工具形式按需分发。在 capsules/capsule-forge/src/lib.rs 中，它被编译期嵌入到章节表GUIDE_CHAPTERS：

GuideChapter { 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 user's 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 <parent>

aos 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_name，lib.rs#L187-L197，拒绝/、\、..），这与"不要假设机器布局、不接受任意路径注入"的总原则一脉相承。

规则 4：agent 主动提出、尚无持久归属的候选——放进一次性工作区

这是针对 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

逐层含义：

两条硬性规则值得特别注意：

1. Capsule 看到的是虚拟路径和按 principal 作用域的存储，而不是任意宿主机路径。
2. 永远不要把原始.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.json（lib.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 的可移植性建立在"位置由运行时发现、权限由 principal 决定、产物由内容身份校验"三点之上；workspace章节正是把这三点前置到写第一行代码之前，让源码选址本身成为可审计、跨平台、不与部署产物混淆的一步。