實戰

74k 星標的 learn-claude-code:Bash is all you need,從零打造 Claude Code 終端 Agent

shareAI-lab 的 nano 倉庫不教你怎麼接 API,而是把 LLM 塞進 terminal 跑成 Agent 的工程細節全部攤開——核心程式碼不到 500 行,harness 設計逐行拆解。

字級

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 迴圈。

架構怎麼運作

四步循環:

  1. system prompt 定義工具清單
  2. 使用者訊息進入佇列
  3. 呼叫 Claude API
  4. 解析回應中的 tool_use 區塊,在本地 subprocess 執行 bash 或 python
  5. 執行結果塞回 messages
  6. 跳回第 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 迴圈讀懂。


參考資料:

來源: https://github.com/shareAI-lab/learn-claude-code