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 使用量，並提升可靠性。