TUI 使用指南

AI Harness 提供終端機互動介面（TUI），支援多輪對話、slash 指令與多 LLM provider 切換。

安裝與啟動

# 複製環境設定
cp .env.example .env
# 填入對應 provider 的 API key

# 安裝依賴
uv sync

# 啟動
uv run main.py

首次設定

首次啟動（或 ~/.harness_config.json 不存在時）會進入設定畫面：

選擇介面語言（繁體中文 / English）
選擇 LLM Provider（Custom / OpenAI / Anthropic / Gemini）
按「開始」進入對話

設定存入 ~/.harness_config.json，下次直接跳過。

要重新設定：TUI 內輸入 /setup。

Provider 與 .env 設定

Provider	必填 .env 變數
`custom`	`CUSTOM_API_KEY`, `CUSTOM_BASE_URL`, `CUSTOM_MODEL_NAME`
`openai`	`OPENAI_API_KEY`, `OPENAI_MODEL_NAME`
`anthropic`	`ANTHROPIC_API_KEY`, `ANTHROPIC_MODEL_NAME`
`gemini`	`GEMINI_API_KEY`（`GEMINI_MODEL_NAME` 選填，預設 `gemini-1.5-flash`）

custom 為預設，連接任何 OpenAI-compatible endpoint（本機 proxy、自建 gateway 等）。

對話操作

你  → 在下方 TextArea 輸入訊息，按 Enter 送出
AI  → Planner → Executor(s) → Reviewer 依序執行，完成後顯示結果

執行過程可看到每個 agent 的狀態：

▸ planner  planning user request
▸ executor  executing step 1/3
▸ reviewer  reviewing outputs

Slash 指令

輸入 / 自動觸發補全，Up/Down 導航，Enter 選取。

指令	說明
`/help`	列出所有可用指令
`/model [name]`	切換 LLM model name
`/provider [name]`	切換 LLM provider（custom / openai / anthropic / gemini）
`/test`	測試 custom provider 連線（顯示 HTTP 狀態）
`/theme [name]`	切換主題（dracula / nord / light）
`/lang [zh\\|en]`	切換介面語言
`/tokens`	查看本 session prompt / completion / total token 用量
`/retry`	重跑上一輪對話
`/clear`	清空對話紀錄
`/history`	顯示本 session 對話輪數
`/copy`	複製上一筆輸出到剪貼簿
`/setup`	刪除 config，回到啟動設定畫面

範例

# 切換到 OpenAI 並指定 model
/provider openai
/model gpt-4o

# 測試 custom endpoint 連線
/test
# → 連線測試 OK  / FAILED  HTTP 403: ...

# 查看 token 用量
/tokens
# → prompt=1,234  completion=567  total=1,801

鍵盤快捷鍵

按鍵	功能
`Enter`	送出訊息
`Shift+Enter`	換行（不送出）
`Ctrl+T`	循環切換主題
`Ctrl+Y`	複製上一筆輸出
`Ctrl+C`	退出
`↑` / `↓`	在 slash 補全清單導航
`Esc`	關閉 slash 補全清單

常見問題

Custom provider 出現 `HTTP 403: Your request was blocked`

後端 WAF block 了 OpenAI SDK 的 user-agent header。
LLMFactory 已內建 header sanitizer，若仍出現此錯誤，先用 /test 確認連線狀態。

Token 計數顯示 0

部分 LLM provider 的 response 不回傳 usage 欄位，TokenTracker 無法累計。屬正常現象，不影響對話。

多輪對話怎麼運作

每次對話的 session_context 包含 history 陣列（前幾輪的 user/assistant），Planner 收到後會參考前輪意圖。

如何重跑失敗的請求

輸入 /retry，系統會取出上一輪 user 訊息重新送出。

執行測試

uv run python -m pytest tests/ -v