Bash4LLM+ 概覽：輕量級的 Bash 包裝器，用於 LLM API

Bash4LLM+ 是一個輕量、無依賴的 Bash 包裝器，旨在與 Groq 的 OpenAI 相容 API 以及其他 LLM 供應商介面。它允許使用者透過單一、可審計的 Bash 腳本，直接在命令列與大型語言模型互動，並優先考慮安全性與在類 Unix 環境中的可移植性。

核心功能與架構

Bash4LLM+ 作為一個自包含的腳本運行，只需要標準的 Unix 工具（bash、coreutils、findutils、util-linux、gawk、curl 與 jq）。它被設計為可在 Linux、macOS、WSL、Cygwin、BSD 以及 Android 上的 Termux 中移植與相容。

設計即安全

此工具實作了多項安全措施，以確保在單一使用者環境中的安全性：

• 不使用 eval 或 /tmp：腳本避免使用 eval，且不使用共享的系統 /tmp 目錄，以防止常見的 Shell 漏洞。
• 隔離的暫存檔案：暫存檔案儲存在使用者自訂的 $RUN_TMPDIR，並使用限制性的權限（umask 077）。
• 輸出安全：腳本永不執行從 LLM 收到的輸出。
• 權限控制：檔案以 600 權限儲存，以確保隱私。

UI 狀態系統（ui_state）

Bash4LLM+ 的一大特色是其 ui_state 系統。核心腳本會將操作中繼資料以原子 JSON 檔案的形式暴露在 $BASH4LLM_CONFIG_DIR/ui_state 中。這讓外部 GUI 或工具（例如 Home Assistant）能在不必解析原始日誌的情況下與 CLI 整合。系統會追蹤：

• 會話狀態：活躍會話、訊息數量與時間戳記。
• API 結果：HTTP 狀態、請求 ID 與偵測到的邊緣案例。
• 供應商能力：活躍供應商是否支援串流或模型刷新。

會話管理與情境記憶

Bash4LLM+ 預設不保留記憶。情境記憶僅在使用者明確以 --session <id> 旗標啟動會話時才會啟用。

永續歷史

當會話啟動時，工具會在 $BASH4LLM_HISTORY_DIR/sessions/<session_id>.ndjson 建立永續的 NDJSON 檔案。此檔案儲存對話歷史，並在後續呼叫 API 時回傳以維持情境。使用者可透過 --session-window [n] 旗標控制傳送的情境量，預設為 10 條訊息。

操作使用與指令介面

基本互動

使用者可以透過多種方式傳送提示：

• 直接提示：./bash4llm "prompt text"
• 管道輸入：echo "prompt" | ./bash4llm
• 檔案輸入：./bash4llm -f prompt.txt
• 多行輸入：使用 heredoc（<<'EOF'）。

模型與供應商管理

Bash4LLM+ 透過供應商的 API 動態取得可用模型清單（例如 GET https://api.groq.com/openai/v1/models），避免硬編碼模型。

• --refresh-models：更新本地模型白名單。
• -m <model>：為單次執行指定模型。
• --set-default <model>：為活躍供應商設定永久預設模型。
• --provider <name>：切換 LLM 供應商（可透過 --install-extras 指令安裝額外供應商，如 Gemini、Hugging Face 與 Mistral）。

輸出選項

使用者可以自訂回應的接收方式：

• 串流：--stream 旗標啟用即時非同步輸出。
• JSON 輸出：--json 或 --pretty 旗標回傳 API 的原始或格式化 JSON 回應。
• 自動儲存：腳本會自動儲存超過可設定位元組門檻（預設 1000 位元組）的輸出。

技術需求與安裝

執行 Bash4LLM+ 前，使用者必須在 PATH 中安裝 bash、coreutils、findutils、util-linux、gawk、curl 與 jq。

安裝步驟包括克隆儲存庫、將 bin/bash4llm 設為可執行，並匯出必要的 API 金鑰（例如 export GROQ_API_KEY="your_key"）。可選的額外功能（包括其他供應商與範本）可透過 ./bash4llm --install-extras 指令安裝。