20000419/fauxnix

fauxnix – AI代理用的Bash到PowerShell橋接器

能做什麼

• 提供一個決定性、零LLM的翻譯層，讓大型語言模型（LLM）代理能在Windows機器上撰寫一般的Linux風格bash命令。
• 該工具解析bash的一個子集（109個指令 + 常見shell語法），將指令轉換為等效的PowerShell腳本，原生執行，並返回與GNU coreutils完全一致的輸出（相同的欄位佈局、錯誤訊息、結束碼、UTF-8處理）。
• 以npm套件（fauxnix-cli）形式發行，可在任何安裝PowerShell 5.1+ 和 Node ≥ 18 的Windows上運行——無需虛擬機、無需WSL、無需額外二進位檔。

對AI為何重要

• LLM代理主要在bash上訓練；在Windows上，它們常產生在PowerShell中失敗的指令，原因包括引號、編碼或缺少工具。
• 透過即時將bash翻譯為PowerShell，fauxnix讓代理能繼續使用它們熟悉的語言，同時在Windows上正確執行，從而提升程式碼產生助手（Claude Code、Codex、OpenCode、Kimi Code、Qwen Code）及任何MCP相容客戶端的可靠性。

主要功能

• 一鍵安裝：支援主要LLM編碼助手（fauxnix install --claude等）和通用fauxnix mcp伺服器用於自訂代理。
• MCP會話持久化：伺服器在呼叫之間記住目前目錄、環境變數和位置參數，模擬真實互動式shell。
• 批次模式：代理可傳送一系列步驟，這些步驟被原子性編譯和執行，每步返回結構化結果。
• 廣泛測試覆蓋：400多個自動化測試和253個案例的差異語料庫，已與Git Bash上的真實GNU coreutils驗證。
• 效能：基準測試顯示，與原始PowerShell相比，工具呼叫錯誤減少約一半，任務執行速度最高提升2.5倍。
• 支援指令集包括核心檔案工具（ls, cp, rm, find）、文字處理（grep, sed, awk, sort）、shell內建指令（cd, export, set）、網路工具（curl, wget, ping）和歸檔工具（tar, zip）。
• 優雅失敗：不支援的結構（如背景&、heredocs、完整eval）會拋出清晰的GNU風格錯誤訊息，而非靜默錯誤行為。

運作方式

1. 解析器 – 輕量級bash子集解析器建構AST。
2. 翻譯器 – AST被轉換為遵循「Fauxnix契約」（逐行stdout、錯誤串流、結束碼）的自包含PowerShell腳本。
3. 執行器 – 腳本透過PowerShell（-EncodedCommand或暫時.ps1檔案）執行，強制UTF-8並進行輸出後處理以去除PowerShell特有雜訊。
4. MCP伺服器 – 作為MCP服務公開（fauxnix mcp），代理可透過標準模型-程式碼協定呼叫。

安裝與快速開始

# 無需安裝即可執行單一指令
npx fauxnix-cli@latest "ls -la src | head -3"

# 全域安裝並整合至LLM助手
npm install -g fauxnix-cli
fauxnix install --claude   # 或 --codex, --kimi, --qwen

安裝後的fauxnix指令可直接使用或透過MCP伺服器呼叫。

限制與已知差異

• 變數指派行為類似於export（不區分shell本地與導出變數）。
• 某些bash功能被有意不支援（如yes有上限，tail -f，背景&）。
• chmod僅處理唯讀位；chown在Windows上為無作用（no-op）。
• 部分輸出細節（如ps aux欄位值）為近似值。

安全 倉儲包含SECURITY.md，描述信任模型、網路防護與報告流程。

授權 MIT © 20000419。

---

Fauxnix讓AI代理能繼續使用它們訓練時的語言——bash——同時在原生Windows上安全高效地執行。