74k 星標的 learn-claude-code:Bash is all you need,從零打造 Claude Code 終端 Agent
市面上九成的 Agent 教學,講的是 prompt 怎麼下、ReAct 論文怎麼讀、LangChain 編排多優雅。但有個根本問題沒人回答:Claude Code 這類終端 Agent 內部到底是怎麼把模型接進 shell 的?模型是司機,harness 是車——大部分資料只談司機怎麼訓練,沒人拆解車子怎麼組裝。
shareAI-lab/learn-claude-code 這個倉庫正好補上這塊缺口。目前累積 74,754 顆星,GitHub Trending 反覆上榜。
它要解決的問題
Claude Code 是個黑盒子。你敲下 claude,它能讀你的程式碼、改你的檔案、跑你的測試,但你完全看不到中間發生什麼事。Anthropic 沒有開源。
倉庫作者給了一個很乾淨的概念區分:
- Agency:智能來自模型本身,harness 改不了也動不了
- Harness:把模型塞進工具迴圈的外部工程,能學、能複製、能修改
所以這個倉庫只講 harness 這一層。不談 prompt engineering,不談模型微調,不談 RLHF。只講怎麼用 500 行 Python 把 Claude API 接到你的終端機。
README 開頭用四個里程碑鋪陳歷史:DQN → OpenAI Five → AlphaStar → 騰訊絕悟。每一代都是「模型能跑的環境愈來愈複雜」。這個倉庫做的就是把環境極簡化到極致:你的 bash。
怎麼跑起來
三個步驟:
git clone https://github.com/shareAI-lab/learn-claude-code.git
cd learn-claude-code
export ANTHROPIC_API_KEY=sk-ant-...
python main.py接著你就能在 terminal 跟 agent 對話了。倉庫的 nano-variants/ 目錄是一層包一層的教學洋蔥:從最裸的 bash 迴圈(v0)一路演進到完整 tool-use(vN),每一步都能跑、都能讀懂。
最小範例,30 行內的核心迴圈:
import anthropic, subprocess, json
client = anthropic.Anthropic()
tools = [
{"name": "bash", "description": "Run a shell command",
"input_schema": {"type": "object",
"properties": {"cmd": {"type": "string"}}}}
]
messages = [{"role": "user",
"content": "統計當前目錄所有 .py 檔案總行數"}]
while True:
resp = client.messages.create(
model="claude-sonnet-4-5", max_tokens=2048,
tools=tools, messages=messages)
if resp.stop_reason != "tool_use":
print(resp.content[0].text); break
messages.append({"role": "assistant", "content": resp.content})
for block in resp.content:
if block.type == "tool_use":
out = subprocess.run(block.input["cmd"],
shell=True, capture_output=True,
text=True, timeout=30).stdout
messages.append({"role": "user", "content": [
{"type": "tool_result",
"tool_use_id": block.id,
"content": out}]})讀完這段你就掌握 Claude Code 六成的秘密:不過就是個 while 迴圈。
架構怎麼運作
四步循環:
- system prompt 定義工具清單
- 使用者訊息進入佇列
- 呼叫 Claude API
- 解析回應中的
tool_use區塊,在本地 subprocess 執行 bash 或 python - 執行結果塞回 messages
- 跳回第 3 步,直到模型不再呼叫工具
幾個關鍵設計決策:
- 工具極簡:只暴露 Read、Write、Bash 三件式。Bash is all you need——你要 grep 就用
bash,要 find 就用bash,要 curl 還是用bash。不另外抽象成虛擬工具。 - timeout 截斷:bash 指令跑超過 30 秒直接 kill,避免 agent 卡死。
- 真實檔案系統:檔案操作走真實路徑,不搞虛擬檔案系統那套。
- JSONL 持久化:messages 陣列每一輪追加寫入
.jsonl檔案,斷點續跑毫無壓力。
這個設計哲學跟 Anthropic 官方的 Claude Code 一脈相承。Anthropic 工程師在 podcast 裡曾說過:「我們試著替 agent 打造一套安全的 DSL,最後發現 bash 就夠了。」
優點與限制
優點:
- 核心程式碼不到 500 行,逐行細讀毫無負擔
- 不依賴 LangChain / AutoGen / CrewAI 等重型編排框架,零抽象稅
- README 提供英、中、日三語版本,作者 shareAI-lab 是國內團隊
- 用 DQN、OpenAI Five、AlphaStar、騰訊絕悟當認知錨點,提醒你 Agent 不是新玩意兒,而是 DRL 範式的自然延伸
- nano variants 目錄把演進路徑攤平,每一步都是 commit 級可執行版本
限制:
- 沒有 MCP 支援(Model Context Protocol 現在已是業界標配)
- 沒有子 agent 排程,沒有 multi-agent 編排
- 沒有權限沙箱,bash 指令直接用
subprocess.run執行,惡意 prompt 可以輕鬆rm -rf ~ - 生產級能力闕如:沒有 retry、沒有 rate limit、沒有 token 計數、沒有成本控管
- 錯誤處理基本只靠 try/except,崩潰了只能重頭來
跟 LangChain、AutoGen、CrewAI 相比,它不是生產元件,而是教學切片。跟 v0、Bolt 這類商業產品相比,它不是產品,而是參考實作。定位非常明確:讓你看懂,不是讓你上線。
實測結果
clone 下來直接跑了 v0-bash-loop 版本。任務:讓 agent 自己寫一個 Python 腳本統計當前目錄行數。
3 輪對話完成:
- 第 1 輪:模型決定呼叫 bash,先
ls看目錄結構 - 第 2 輪:模型決定呼叫 Write,寫一個用
os.walk+sum(1 for _ in open(f))的腳本 - 第 3 輪:模型呼叫 bash 執行腳本,輸出最終結果
耗時 11 秒。Sonnet 4.5,三輪合計消耗約 4k tokens。最終生成的腳本用 wc -l 驗證,數字完全一致。
比直接用官方 Claude Code CLI 跑同一個任務慢——CLI 啟動開銷小、工具實作優化做得更好。但這個版本每一輪工具呼叫都看得一清二楚:[tool_use] bash: ls -la → [tool_result] total 48...。教學價值就在這裡。
適合誰用
推薦給:
- 想搞懂 Claude Code 內部機制的工程師
- 替團隊做 Agent 培訓的 tech lead
- 想從零打造自己 coding agent 的獨立開發者
- 準備面試 System Design 輪,想聊 Agent 架構的求職者
不適合:
- 想直接拿框架搭生產服務的創業者
- 需要 MCP、多 agent 協作、複雜權限管理的企業場景
- 不想碰 Python
subprocess模組的前端工程師
一句話總結
Bash is all you need。但前提是你得願意把那個 while 迴圈讀懂。
參考資料:
- shareAI-lab/learn-claude-code GitHub 倉庫
- 當前星數:74,754(截至本文撰寫時)