Harness Sample

VibeWeed Studio — 氣氛對了工作室

以 LangChain + LangGraph 建立的 Planner–Executor–Reviewer AI Harness，附帶 Textual TUI 互動介面。

流程架構

Planner → Executor(step 1) → Executor(step 2) → ... → Reviewer
                                                           │
                                              needs_revision → retry / replan
                                                           │
                                                        pass → Finalize

1. Planner 理解需求，產生多步驟執行計畫與成功標準
2. Executor 依序執行每個 step，記錄工具呼叫與輸出
3. Reviewer 審查所有 step 輸出，決定 finalize / retry / replan
4. LangGraph 控制流程，MemorySaver 持久化多輪對話狀態

專案結構

src/
├── agent/
│   ├── base_langraph_agent.py   # Agent 基底（LangGraph 單節點）
│   ├── planner_agent.py
│   ├── executor_agent.py
│   └── reviewer_agent.py
├── graph/
│   └── harness_graph.py         # HarnessGraph 流程控制
├── service/
│   ├── config_service.py        # ~/.harness_config.json 讀寫
│   └── i18n_service.py          # 雙語字串（zh / en）
├── ui/
│   ├── app.py                   # HarnessChatApp entry
│   ├── constants.py             # 主題、模型清單、slash 指令定義
│   └── screens/
│       ├── provider_screen.py   # 啟動設定畫面
│       └── chat_screen.py       # 主對話畫面
└── utils/
    ├── llm_factory.py           # LLM provider 工廠
    └── token_tracker.py         # Session token 追蹤
prompts/
├── planner.md
├── executor.md
└── reviewer.md
tests/
└── test_harness_graph.py        # 20 個路由與流程單元測試
main.py                          # 啟動入口

快速開始

1. 環境設定

cp .env.example .env
# 填入 API key 與 model name

2. 安裝依賴

uv sync

3. 啟動 TUI

uv run main.py

首次啟動出現設定畫面，選擇語言與 LLM Provider 後進入對話。設定存入 ~/.harness_config.json，之後直接跳過。

LLM Provider 設定

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

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

TUI Slash 指令

指令	功能
/help	列出所有指令
/model [name]	切換 LLM model name
/provider [name]	切換 LLM provider
/theme [name]	切換主題（dracula / nord / light）
/lang [zh\|en]	切換介面語言
/tokens	查看本 session token 用量
/test	測試 custom provider 連線
/retry	重跑上一輪對話
/clear	清空對話紀錄
/history	顯示對話輪數
/copy	複製上一筆輸出
/setup	回到啟動設定畫面

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

鍵盤快捷鍵

按鍵	功能
Enter	送出訊息
Shift+Enter	換行
Ctrl+T	循環切換主題
Ctrl+Y	複製上一筆輸出
Ctrl+C	退出

執行測試

uv run python -m pytest tests/ -v

目前限制

• 尚未支援 streaming output
• 無 PostgreSQL session 持久化
• 無 production-grade logging / tracing
• Tool permission model 尚未完整實作

License

目前尚未指定 license。