企业官网建设流程全解析

aos-fs 是 Unicity AOS 中承担"coreutils"角色的第一方 Capsule，它通过内核 VFS 气闸（VFS airlock）为 Agent 提供读、写、搜索、导航工作区文件系统的八件基础工具。读完本文，你将完整掌握每个工具的参数、边界条件与错误语义，理解Capsule.toml中能力声明（capabilities）与 IPC 路由的编写方式，并能按仓库规范将该 Capsule 编译为wasm32-unknown-unknown目标产物。

一、定位：Agent 世界里的 coreutils

AOS 采用操作系统式模型：Agent 运行在内核之上，所有对外资源的访问都经过受控边界。capsule-fs 的 README 开篇即给出定位——"In the OS model, this capsule is the coreutils package"：它为 Agent 提供读取、写入、搜索和导航工作区文件系统的能力，且全部操作经由 VFS 气闸完成，由内核在执行任何宿主文件系统访问之前强制路径边界、写时复制（copy-on-write）隔离与能力检查。

从源码结构看，这个定位被严格执行：src/lib.rs 的模块文档注释写明"All operations go through the Astrid VFS — the agent cannot escape the CWD boundary. Write operations are copy-on-write (changes are staged in an overlay until committed)"。也就是说，Agent 的写入先落在 overlay 暂存层，提交后才可见；这为"会话内可回滚"的沙箱语义提供了基础。

二、工具清单：八个工具及其完整语义

README 给出了一张工具总表，这里完整继承并结合 src/lib.rs 的参数结构体与实现细节逐条展开。

所有参数结构体都定义在 src/lib.rs，并统一派生Deserialize与schemars::JsonSchema——这意味着工具的 JSON Schema 是从 Rust 类型直接生成的，宿主据此做参数校验与向模型暴露工具描述。

read_file：1-based 行切片，越界安全

实现见 read_file：先经 VFS 一次性读入全文件，再手动按行切片。行号从 1 开始；start_line缺省为 1，end_line缺省为文件总行数并被min(lines.len())钳制到合法区间。两个越界分支都返回空字符串而不是报错：start >= lines.len()或start >= end。这是一个值得注意的工程取舍——用saturating_sub(1)加区间钳制，使"读不存在的行"成为无副作用的空结果，而不是失败。

write_file 与 create_directory：整文件替换 + 显式建目录

write_file是覆盖式写入（实现），文档明确要求"整文件被替换——对已有文件的手术式编辑请用replace_in_file"，且父目录必须已存在，需要先create_directory。两者都以mutable标记注册（见#[astrid::tool("write_file", mutable)]），从源码结构看，mutable标记区分只读工具与会产生状态变更的工具，供运行时做权限/审计分类。

replace_in_file：唯一性约束是核心设计

这是该 Capsule 最有辨识度的编辑原语（实现）：old_string必须在文件中恰好出现一次。计数逻辑用content.matches(&old_string).count()：

• 出现 0 次 → 报Exact string not found in {path}；
• 出现 >1 次 → 报Found {n} occurrences ... Please be more specific.，要求调用方补充上下文使匹配唯一。

这个"拒绝歧义"的策略把"编辑可能落错位置"这类风险从静默失败变成了显式错误，迫使 Agent 提供更长的上下文锚点。

grep_search：字面量匹配 + 三重资源上限

grep_search递归遍历目录树，返回path:line_number:content格式的匹配行（实现）。两点关键约束：

1. pattern 是字面量子串，不是正则。纯匹配逻辑被抽到 src/grep.rs，其单元测试literal_regex_chars与dot_is_literal明确断言.*和.都按字面字符匹配——这避免了 Agent 传入恶意或畸形的正则。
2. 三重上限防止失控搜索（常量定义）：

遍历函数 walk_and_grep 对应的 递归实现 在每层递归、每个条目处理前都检查这三个上限，任何一项触顶即静默停止。不可读的文件被log::debug记录后跳过，不会让搜索整体失败。

delete_file 与 move_file：会话边界内的删除与原子移动

两者都受 VFS overlay 限制（源码注释）：只能操作当前会话内创建的文件，删除/移动已存在的 CWD 文件会因缺乏 whiteout 支持而失败。

move_file（实现）的执行序列值得逐行看：

1. 一次file_stat同时完成存在性与"是目录"两项检查（stat.is_dir/stat.size，见 FileStat）；
2. 源文件大于MOVE_FILE_MAX_BYTES（10MB，常量）直接拒绝——因为移动需经 WASM guest 内存中转，10MB 是该通道的硬上限；
3. 目标路径已存在则拒绝，防止覆盖；
4. 执行 read → write 到新路径 → remove 源文件；若最后一步删除源文件失败，回滚已写入的目标文件，避免留下"幽灵副本"。

错误信息明确告诉调用方发生了什么："move failed: source could not be removed (...); destination write was rolled back"。

三、Capsule.toml：能力声明即权限边界

capsules/capsule-fs/Capsule.toml 是该 Capsule 的权限与路由契约，分四部分解读。

包元数据：astrid-version = ">=0.1.0"声明运行时兼容性下界。

组件与能力：

[[component]] id = "fs-tools" file = "aos_fs.wasm" type = "executable" capabilities = { fs_read = ["cwd://", "home://"], fs_write = ["cwd://"] }

组件指向构建产物aos_fs.wasm（Rust crate 名aos-fs中的连字符在 WASM 文件名中变下划线）。能力字段是这份清单的安全核心：fs_read覆盖cwd://与home://两个 VFS 前缀，而fs_write只有cwd://。注释解释了原因——home://下的~/.astrid/存放密钥与审计库等敏感状态，fs-tools只允许读（用于文件检视），写home://的能力应只按需在专门 Capsule（如插件安装器）上授予。这与 capsule-forge 的 capabilities 指南中的规则一致：fs_read不蕴含写，fs_write也不蕴含读，两者独立声明。

IPC 发布/订阅路由（publish/subscribe 段）：

[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.read_file" = { wit = "@unicity-astrid/wit/types/tool-call", handler = "tool_execute_read_file" } # ... 其余 7 个工具 topic 与 "tool.v1.request.describe" 同构

从源码结构看，[subscribe]的每个键既是路由声明也是被强制的 topic ACL：tool.v1.execute.<tool>把宿主下发的工具调用绑定到 WASM 侧的具名 handler；[publish]用通配 topictool.v1.execute.*.result声明该 Capsule 有权回发全部执行结果，WIT 类型来自 astrid 的共享 WIT 包，保证消息双方类型一致。

四、构建：wasm32-unknown-unknown 目标

README 给出的开发命令只有一行：

cargo build --target wasm32-unknown-unknown --release

仓库内的配套约束让这条命令可复现：

• rust-toolchain.toml 固定工具链为1.94.0，并声明targets = ["wasm32-unknown-unknown"]——这就是 README 徽章上 MSRV 1.94 的来源；
• Cargo.toml 中 crate 名为aos-fsv0.2.0，crate-type = ["cdylib", "lib"]（cdylib 产出.wasm），依赖仅astrid-sdk（workspace 锁定为=0.7.1）、serde、serde_json；其中对 astrid-sdk 的本地路径覆写有注释说明：在 per-domain WIT SDK 发布到 crates.io 之前临时使用本地路径，届时移除；
• 工作区 Cargo.toml 的 release profile 对该目标做了 WASM 友好优化：opt-level = "z"（体积优先）、lto = true、codegen-units = 1、panic = "abort"；
• 纯逻辑部分可脱离 WASM 验证：grep_content被刻意与 VFS 解耦（src/grep.rs 注释："Pure grep matching logic, separated from VFS for testability"），其 7 个单元测试覆盖基本匹配、无匹配、首尾行、上限钳制、字面量正则字符与空内容等场景，可在原生 target 上直接跑cargo test。

另外，src/lib.rs 顶部以#![deny(unsafe_code)]、#![deny(clippy::all)]拒绝 unsafe 与常见 lint——对一个运行在沙箱边界上、直接面向宿主文件系统的工具 Capsule 来说，这是刻意的安全姿态。

五、小结与延伸阅读

aos-fs 展示了 AOS Capsule 生态的一个标准范式：README 声明工具面，Capsule.toml声明能力与路由，Rust 源码实现带边界检查的工具逻辑，VFS 气闸在内核侧兜底。它的八件工具刻意保持小而正确——精确匹配、唯一性编辑、字面量搜索、资源上限、原子移动加回滚——把"Agent 误操作宿主文件系统"这一风险面压缩到最小。

若要继续深入：

• 工具实现与参数结构体：capsules/capsule-fs/src/lib.rs；
• grep 上限与纯函数测试：capsules/capsule-fs/src/grep.rs；
• 能力字段全集与语义：capsules/capsule-forge/src/guides/capabilities.md；
• Capsule.toml 完整作者面（package / component / capabilities / publish / subscribe）：capsules/capsule-forge/src/guides/manifest.md。

该 Capsule 采用 MIT 或 Apache-2.0 双重许可（见 LICENSE-MIT、LICENSE-APACHE）。