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 循环。
它怎么工作(架构)
四步循环:
- 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 工程师在播客里说过类似的话:"我们试过给 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 循环读懂。
参考:
- shareAI-lab/learn-claude-code GitHub 仓库
- 当前 star 数:74,754(截至文章写作时)