aos-fs：AOS 的文件系统 Capsule——八个工具、VFS 气闸与能力声明的完整剖析

【免费下载链接】aos-ceAOS Community Edition: the open agent operating system.项目地址https://gitcode.com/gh_mirrors/ao/aos-ce点击查看免费下载aos-fs 是 Unicity AOS 中承担coreutils角色的第一方 Capsule它通过内核 VFS 气闸VFS airlock为 Agent 提供读、写、搜索、导航工作区文件系统的八件基础工具。读完本文你将完整掌握每个工具的参数、边界条件与错误语义理解Capsule.toml中能力声明capabilities与 IPC 路由的编写方式并能按仓库规范将该 Capsule 编译为wasm32-unknown-unknown目标产物。一、定位Agent 世界里的 coreutilsAOS 采用操作系统式模型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 的参数结构体与实现细节逐条展开。Tool描述参数read_file读取文件内容支持可选行范围start_line、end_linefile_path,start_line?,end_line?write_file将内容写入文件整文件替换file_path,contentreplace_in_file精确替换文件中唯一出现的字符串0 次或 1 次均拒绝file_path,old_string,new_stringlist_directory列出目录条目dir_pathgrep_search递归内容搜索带深度、文件数、匹配数上限dir_path?,patterncreate_directory创建目录dir_pathdelete_file删除文件仅限会话内创建的文件尚不支持 whiteoutfile_pathmove_file移动文件10MB 上限、存在性检查、失败回滚source_path,destination_path所有参数结构体都定义在 src/lib.rs并统一派生Deserialize与schemars::JsonSchema——这意味着工具的 JSON Schema 是从 Rust 类型直接生成的宿主据此做参数校验与向模型暴露工具描述。read_file1-based 行切片越界安全实现见 read_file先经 VFS 一次性读入全文件再手动按行切片。行号从 1 开始start_line缺省为 1end_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格式的匹配行实现。两点关键约束pattern 是字面量子串不是正则。纯匹配逻辑被抽到 src/grep.rs其单元测试literal_regex_chars与dot_is_literal明确断言.*和.都按字面字符匹配——这避免了 Agent 传入恶意或畸形的正则。三重上限防止失控搜索常量定义常量值含义GREP_MAX_MATCHES100最多返回的匹配行数GREP_MAX_FILES1000遍历过程中最多访问的文件数GREP_MAX_DEPTH20目录递归最大深度遍历函数 walk_and_grep 对应的 递归实现 在每层递归、每个条目处理前都检查这三个上限任何一项触顶即静默停止。不可读的文件被log::debug记录后跳过不会让搜索整体失败。delete_file 与 move_file会话边界内的删除与原子移动两者都受 VFS overlay 限制源码注释只能操作当前会话内创建的文件删除/移动已存在的 CWD 文件会因缺乏 whiteout 支持而失败。move_file实现的执行序列值得逐行看一次file_stat同时完成存在性与是目录两项检查stat.is_dir/stat.size见 FileStat源文件大于MOVE_FILE_MAX_BYTES10MB常量直接拒绝——因为移动需经 WASM guest 内存中转10MB 是该通道的硬上限目标路径已存在则拒绝防止覆盖执行 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.wasmRust 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 ACLtool.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.0crate-type [cdylib, lib]cdylib 产出.wasm依赖仅astrid-sdkworkspace 锁定为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.rsgrep 上限与纯函数测试capsules/capsule-fs/src/grep.rs能力字段全集与语义capsules/capsule-forge/src/guides/capabilities.mdCapsule.toml 完整作者面package / component / capabilities / publish / subscribecapsules/capsule-forge/src/guides/manifest.md。该 Capsule 采用 MIT 或 Apache-2.0 双重许可见 LICENSE-MIT、LICENSE-APACHE。赞分享【免费下载链接】aos-ceAOS Community Edition: the open agent operating system.项目地址https://gitcode.com/gh_mirrors/ao/aos-ce点击查看免费下载相关推荐AOS CE Capsule 能力清单实战Capsule.toml 中 [capabilities] 的完整字段目录与最小权限设计AOS CE Capsule 能力清单实战Capsule.toml 中 capabilities 的完整字段目录与最小权限设计 在 AOS CommunityMoukthar控制面板入门C2仪表盘界面与操作详解Moukthar控制面板入门C2仪表盘界面与操作详解 Moukthar是一款开源的Android远程管理工具而它的C2控制面板Command ContBindu Skills 系统Agent 能力声明、发现与智能路由的完整实战指南Bindu Skills 系统Agent 能力声明、发现与智能路由的完整实战指南 导读 Skills技能是 Bindu 中 Agent 可对外声明、供编排上一篇InternLM2.5-20B-Chat部署实战LMDeploy与vLLM高效部署方案下一篇如何高效获取中小学电子教材智慧教育平台解析工具的完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考