实战

74k star 的 learn-claude-code:Bash is all you need,从 0 搓一个 Claude Code 外壳

shareAI-lab 这个 nano 仓库不教你怎么调 API,教你怎么把 LLM 装进终端跑成 Agent——核心代码不到 500 行,harness 工程逐行拆给你看。

字号

74k star 的 learn-claude-code:Bash is all you need,从 0 搓一个 Claude Code 外壳

市面上的 Agent 教程,90% 在讲 prompt 怎么写、ReAct 论文怎么读、LangChain 编排多优雅。但有个问题没人在意:Claude Code 这种终端 Agent 内部到底怎么把模型接进 shell?模型是司机,harness 是车——大部分资料只讲司机怎么培训,没人拆车怎么造。

shareAI-lab/learn-claude-code 这个仓库专门补这块缺。目前 74,754 star,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

然后你就能在终端跟 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 60% 的秘密:就是个 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 工程师在播客里说过类似的话:"我们试过给 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,3 轮总共消耗约 4k tokens。最终生成的脚本用 wc -l 验证,数字一致。

比直接让官方 Claude Code CLI 跑同样任务慢——CLI 启动开销小、工具实现优化好。但这个版本每轮工具调用都看得清清楚楚:[tool_use] bash: ls -la → [tool_result] total 48...。教学价值就在这里。

谁该用

适合:

  • 想搞懂 Claude Code 内部机制的工程师
  • 给团队做 Agent 培训的 tech lead
  • 想从 0 写自己的 coding agent 的独立开发者
  • 准备面试 System Design 轮,要聊 Agent 架构的求职者

不适合:

  • 想直接拿框架搭生产服务的创业者
  • 需要 MCP、多 agent 协作、复杂权限管理的企业场景
  • 不想碰 Python subprocess 模块的前端同学

一句话总结

Bash is all you need。但前提是你得愿意把那个 while 循环读懂。


参考:

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