AFT – 编码代理的感官运动皮层

是什么 – AFT（Agent File Tools）是一个基于 Rust 的核心，为 LLM 驱动的编码代理（如 OpenCode、Pi 等）提供真实的 IDE 式代码库视图和类操作系统执行层。它位于代理（例如 OpenCode、Pi 或 oh-my-pi）与主机文件系统之间，暴露高级、符号感知的工具（aft_outline、aft_zoom、aft_edit、aft_bash 等），而非原始的 read/write/grep 调用。

---

核心理念（大脑隐喻）

区域	角色	示例工具
感觉皮层	感知代码结构、语义和关系	aft_outline、aft_zoom、aft_search、aft_callgraph、aft_inspect
运动皮层	执行精确的解析编辑和重构	aft_edit、aft_write、aft_apply_patch、aft_import、ast_grep_*
脑干	保持长时间运行的进程、压缩输出、提供撤销/恢复功能	aft_bash、后台任务、PTY 会话、aft_safety

---

支持的代理“夹具”

夹具	AFT 如何集成
OpenCode	原生适配器（@cortexkit/aft-opencode）将内置的 read、write、edit、apply_patch 替换为 AFT 支持的版本，并添加 aft_ 工具家族。
Pi	原生扩展（@cortexkit/aft-pi）替换 read、write、edit、grep 并添加 aft_ 工具。
OMP（oh-my-pi）	通过 Pi 插件支持；默认在顶层注册工具，支持可选的“host_default”展示模式。

---

突出功能

• 结构感知感知 – aft_outline 返回每个符号（函数、类、类型等）的种类、可见性、行范围和嵌套成员；aft_zoom 可深入单个符号并包含调用图信息。
• 混合语义+词法搜索 – aft_search 使用三元组索引加上可选的嵌入后端（OpenAI 兼容或 Ollama）根据语义查找代码。
• 符号级编辑 – aft_edit 可直接替换命名函数、执行模糊查找/替换，或运行多文件事务性编辑。所有更改在写入前都会被解析、格式化并备份。
• 自动导入管理 – aft_import 以语言感知方式添加、删除或整理导入。
• 基于 AST 的结构替换 – ast_grep_search / ast_grep_replace 允许代理使用 tree-sitter AST 匹配代码模式。
• 健壮的 bash 执行 – aft_bash 运行 shell 命令时支持输出压缩、权限扫描，并自动重写常见工具（cat → read、grep → grep tool）。后台任务在代理重启后仍存活。
• 撤销 / 检查点 – 每次编辑都会保存到文件级撤销栈；代理可创建命名检查点并安全回滚。
• 语言覆盖 – 支持 30 多种语言（TS/JS、Python、Rust、Go、C/C++、Java、Kotlin、Swift 等）的 tree-sitter 解析器，实现大纲、编辑、AST 和语义功能。
• 持久索引与 LSP – 三元组搜索、语义嵌入索引和嵌入式 LSP 客户端在每个项目根目录的长期运行 aft 进程中保持活跃。

---

快速入门（一行命令）

npx @cortexkit/aft@latest setup

该命令检测您已安装的夹具，注册 AFT 工具，并确保 aft 二进制文件可用。可通过 --harness opencode|pi|omp 指定特定夹具。

---

安装详情

• Rust crate – crates.io 上的 agent-file-tools（核心二进制文件）。
• NPM 包 – @cortexkit/aft（CLI）、@cortexkit/aft-opencode、@cortexkit/aft-pi（夹具适配器）。
• 二进制分发 – CLI 首次使用时会下载适用于您平台的预构建二进制文件，必要时回退到 cargo install 或 GitHub 发布版本。
• 配置 – 可选的 aft.jsonc（用户级 ~/.config/cortexkit/aft.jsonc 或项目级 <repo>/.cortexkit/aft.jsonc）。设置 enabled: false 可关闭 AFT，或调整工具表面、语义后端、LSP 服务器、压缩等。
• 卸载 – 运行 npx @cortexkit/aft@latest doctor 查看残留项，然后手动从夹具配置中删除插件条目，并删除 ~/.local/share/cortexkit/aft/ 数据目录。AFT 本身无专用卸载命令。

---

开发与贡献

• 使用 Bun 工作区管理 TypeScript 适配器，使用 Cargo 工作区管理 Rust 核心的单体仓库。
• 构建步骤：

  bun install            # 安装 JS 依赖
  cargo build --release  # 编译 Rust 二进制文件
  bun run build          # 构建 TS 插件
  

• 测试：bun run test（TS）和 cargo test（Rust）。
• 格式化：bun run lint（Biome）和 cargo fmt。
• 贡献遵循“设计优先”流程：打开问题，获得 design-approved 标签，然后提交 PR。

---

许可证

MIT – 个人和商业用途均可自由使用。

---

简而言之：AFT 为 LLM 驱动的编码代理提供全功能、语言感知的 IDE 和轻量级 OS 层，显著减少代理读取、编辑或运行代码时的 token 使用量，并提升可靠性。