kungfu-systems/kungfu

Kungfu – LLM-代理的持久化工作層

是什麼

• Kungfu 是一個命令列工具（可選 TUI/GUI），可與任何基於 LLM 的編碼或推理代理（如 GitHub Copilot Codex、Anthropic Claude、OpenCode、Amp 或自架設模型）並行運行。它將 Work（目標、證據、決策和狀態）記錄在聊天會話之外，使同一 Work 能夠在代理交接、崩潰或斷線時依然存活。

核心概念

概念	含義
Project	用於分組相關 Work 項的資料夾。Kungfu 在此處建立隱藏的 .kungfu/ 目錄以儲存狀態。
Work	單一持久化任務（例如「準備發行說明」）。它保存目前真相、進度和所需證據。
Attempt	代理執行一次 Work 的嘗試。每次嘗試都會被記錄，即使失敗也不會覆蓋 Work。

如何運作

1. 透過 Kungfu 啟動代理 – kungfu run codex "Prepare the release notes"。Kungfu 啟動所選代理，傳遞提示，並將代理執行的每一步記錄為一次 Attempt。
2. 自由切換代理 – 由於 Work 存於 .kungfu/ 中，您之後可執行 kungfu run claude 並繼續同一任務，無需重新解釋上下文。
3. 故障恢復 – 如果代理崩潰或連線中斷，下一次 Attempt 會繼續同一 Work，保留先前的證據和決策。
4. 獨立完成 – 代理可提出結果，但 Kungfu 需要額外的審查/確認步驟才會將 Work 標記為完成，防止代理自我批准。

主要特性

• 代理無關：適用於任何可執行本地命令的 CLI 兼容 LLM 代理。
• 決定性模擬代理：內建代理（KUNGFU_MOCK_AGENT_SCENARIO）可在無需任何 API 金鑰的情況下示範連續性與故障恢復。
• 側車 UI：可選的終端 UI（kungfu）和圖形化 UI，用於視覺化 Projects、Work 和 Attempts。
• 可審計證據：每次 Attempt 都會儲存提示、回應和生成的任何工件，支援檢查與合規性。
• 安全防護：防止兩個代理同時寫入同一 Work。
• 開源標準：附帶 KFD 工程標準與 Buildchain，可產生可驗證的發布護照。

安裝（macOS / Linux / Windows）

# 一行安裝器（無需 sudo，無需修改 shell 設定）
curl -fsSL https://kungfu.tech/install.sh | sh

腳本輸出 PATH 新增後，加入您的 shell（或遵循 Windows 指南）。安裝程式會拉取最新的 Alpha 版本。

快速開始

# 在任意專案資料夾內
KUNGFU_MOCK_AGENT_SCENARIO=recovery-story kungfu   # 執行決定性的三步示範
# 或執行真實代理
kungfu run codex "Write the changelog for v2.3"

隱藏的 .kungfu/ 資料夾將出現；請勿納入版本控制。

典型用例

• 長時間執行的開發任務，您可能需要在較便宜與較強大的 LLM 之間切換。
• 團隊環境，多位工程師（或機器人）需協作處理同一 AI 生成的工作，且不遺失上下文。
• 合規/審計 場景，需要完整且不可變的日誌記錄模型生成內容及其原因。

成熟度

• 專案處於 Alpha（v4）階段。可在 macOS、Linux 和 Windows 上運行，但 API 和 UI 仍可能變更。README 提醒該版本為預發行渠道，並指向「Alpha 狀態」和「已知限制」文件以取得詳細資訊。

許可證

• Apache-2.0（參見 LICENSE）。

進一步了解

• 系統概覽：docs/concepts/system-overview.md
• 代理-工作實驗室教程：docs/guides/agent-work-lab.md
• 完整文件地圖：docs/MAP.md
• 發布製品：https://github.com/kungfu-systems/kungfu/releases/latest

---

Kungfu 本質上是 LLM 驅動代理的連續性層，讓您將 AI 生成的工作視為可抵禦崩潰、交接和模型變更的常規軟體資產。