用 300 行 Bash 复刻 Claude Code：最小化 AI 编程助手的原理与局限

作者：Lucky 发布日期：2026-03-24 标签：#ClaudeCode #BashAgent #HarnessEngineering

大多数人对 AI 编程助手的印象是：一个装满插件的 IDE，或者一个需要npm install半天的 Node.js 项目。

但有一个项目说：Bash is all you need。

shareAI-lab/learn-claude-code——一个用纯 Bash 脚本从零构建 AI 编程助手的开源项目——正在 GitHub Trending 上持续吸引关注。它没有 Python 依赖，没有复杂的构建流程，只有一堆 Bash 脚本和一个 Provocative 的命题：

“An agent is a model. Not a framework. Not a prompt chain. Not a drag-and-drop workflow.”

本文深入解析这个项目的设计哲学、核心实现，以及它揭示的 Agent 架构真相。

核心命题：Agent 究竟是代码还是模型？

这是项目 README 一开篇就摆出的立场，作者用一连串历史事实来支撑它：

  • 2013 年：DeepMind DQN 靠一个神经网络在没有游戏规则的前提下学会了 7 款 Atari 游戏——这个神经网络才是 Agent。
  • 2019 年：OpenAI Five 自我对弈了 45,000 年 Dota 2，最终击败世界冠军——模型才是 Agent。
  • 2024-2025 年：Claude、GPT、Gemini 被部署为编程 Agent——架构和上面完全一样，区别只在于规模。

作者的核心观点：Agent 是一个经过训练的模型，而非周围的代码。 框架、编排库、工作流引擎——它们不是 Agent，它们是 Agent 的 Harness（套具）。

Harness = Tools + Knowledge + Observation + Action Interfaces + Permissions

模型负责决策，Harness 负责执行。这套思路，是理解整个项目的钥匙。

Claude Code 的本质：一套极简 Harness

项目选择解剖 Claude Code，是因为它的设计足够克制——或者说，足够诚实地反映了"Harness"应有的样子：

Claude Code = one agent loop
            + tools (bash, read, write, edit, glob, grep, browser...)
            + on-demand skill loading
            + context compression
            + subagent spawning
            + task system with dependency graph
            + team coordination with async mailboxes
            + worktree isolation for parallel execution
            + permission governance

这就是全部。没有黑科技，没有魔法。每一项都是 Harness 机制——都是为了给模型提供"手"（执行能力）和"眼"（感知能力）。

12 个 Session：从单步循环到自主隔离执行

项目设计了 12 个渐进式的 Session（s01-s12），每个 Session 增加一个 Harness 机制。

s01：One Loop + Bash is All You Need

这是整个项目的起点。最小可行的 Agent 循环：

User --> messages[] --> LLM --> response
                          |
                stop_reason == "tool_use"?
               /                          \
             yes                           no
              |                             |
        execute tools              return text
        append results
        loop back -------------> messages[]

核心洞察：模型决定何时调用工具，何时停止。代码只需要执行模型要求的事。

Bash 在这里的优势是零门槛——任何 Linux/macOS 系统都有 Bash，不需要安装任何运行时。

s02：Adding a Tool Means Adding One Handler

增加一个新工具不需要修改循环本身，只需要向 dispatch map 注册一个 handler。循环保持稳定，扩展变得简单：

# dispatch map 示例
declare -A TOOL_HANDLERS
TOOL_HANDLERS["bash"]=handle_bash
TOOL_HANDLERS["read"]=handle_read
TOOL_HANDLERS["write"]=handle_write

# 调用时
execute_tool() {
    local tool_name=$1
    local handler=${TOOL_HANDLERS[$tool_name]}
    $handler "$2"
}

这个模式对应了 Claude Code 中工具注册的核心思路：Schema 定义工具，dispatch 执行工具，循环本身与具体工具解耦。

s03：An Agent Without a Plan Drifts

这一 Session 引入了 Plan（规划）机制：让模型先列出执行步骤，再逐一执行。研究表明，有 Plan 的 Agent 任务完成率是无 Plan 的两倍。

Bash 实现方式是先生成步骤列表，再循环执行：

# 生成计划
PLAN=$(echo "$RESPONSE" | extract_plan)

# 按计划执行
while IFS= read -r step; do
    execute_step "$step"
done <<< "$PLAN"

s04：Subagent Isolation

将大任务分解为子任务，每个子任务拥有独立的消息上下文，防止噪声泄漏。这是 Claude Code 多 Agent 协作的基础。

# 为子任务创建独立上下文
create_subagent() {
    local task=$1
    local sub_messages="[]"
    # 子 Agent 拥有独立消息历史
    loop "$task" "$sub_messages"
}

s05：On-Demand Knowledge Loading

知识不是一股脑塞进 System Prompt，而是通过工具按需注入。好处是 System Prompt 不会随知识库膨胀，同时模型只在需要时获取相关知识。

# 按需加载知识
load_knowledge() {
    local topic=$1
    local knowledge=$(cat "knowledge/$topic.md")
    # 注入到 tool_result，而非 system prompt
    echo "Loaded knowledge about $topic"
}

s06：Context Compression

长对话会耗尽 Context Window，Claude Code 的解法是三层压缩策略：

  1. 摘要压缩：对历史消息做摘要
  2. 选择性保留：保留关键代码片段和决策点
  3. 滑动窗口：只保留最近 N 条消息

Bash 实现需要借助外部工具（如awk）做文本处理。

为什么说这个项目不是玩具？

一个纯 Bash 实现的 Agent，听起来确实像是 Demo。但项目想表达的远不止"能用 Bash 调用 LLM"。

它在回答一个真实的工程问题

当你用 LangChain、AutoGPT、CrewAI 构建应用时，你实际上在做什么？作者的观点毫不客气：

“What they build is a Rube Goldberg machine — an over-engineered, brittle pipeline of procedural rules, with an LLM wedged in as a glorified text-completion node.”

项目要论证的是：框架本身的复杂度并不直接转化为 Agent 能力。 Claude Code 的成功不是因为它有复杂的编排逻辑，而是因为它的 Harness 设计足够干净——给模型足够的信息，然后让模型自己做决定。

它的教育价值是真实的

项目提供了 12 个从简单到复杂的 Session，每个 Session 聚焦一个机制。开发者可以通过修改少量代码，亲自实验"去掉 Plan 机制会怎样"、“加上 Subagent 隔离会怎样”。

这种白盒可读性，是 Python 框架生态中大量缺失的。

天花板：纯 Bash 的真实局限

诚实地讲，这个项目有它翻不过去的天花板。

1. 并发能力几乎为零

Bash 原生的并发模型（& + wait）对于需要真正并行的任务（如多个 Subagent 同时工作）极其脆弱。Claude Code 的 worktree isolation 和 async mailbox 在纯 Bash 下基本无法优雅实现。

2. 复杂 Tool 的表达能力

Claude Code 的 Read、Edit、Glob、Grep 等工具背后是精心设计的 Schema 和错误处理。Bash 的字符串处理能力在这些场景下会迅速显得吃力。

3. Context 管理的天花板

三层 Context Compression 需要对文本进行处理和决策。Bash 的文本处理虽然强大，但面对大规模代码库时，其效率和可维护性远不如有类型系统的语言。

4. 无法处理二进制数据

Tool 结果中常包含图片、PDF、结构化数据。Bash 对这些内容基本没有原生处理能力。

5. 跨平台一致性问题

Bash 在 Linux 和 macOS 上行为较为一致，但在 Windows 上（WSL 之外）基本无法原生运行。这限制了项目的适用范围。

核心启示：Harness 工程师的思维模型

项目最有价值的部分，不是那些 Bash 脚本，而是 README 里反复强调的一个思维转换：

从"我在开发 Agent"转变为"我在开发 Agent 的 Harness"。

这不是语义游戏，而是工程思维上的根本区别：

维度错误的思路正确的思路（Harness）
关注点写更复杂的编排逻辑设计更好的工具抽象
扩展方式修改主循环向 dispatch map 注册新工具
知识管理塞进 System Prompt按需加载
上下文全部保留主动压缩
权限控制默认全授权最小权限 + 审批流

Claude Code 之所以优雅，是因为 Anthropic 的工程师把精力花在了这些 Harness 机制上，而不是试图在代码里"写智能"。

结论

learn-claude-code 是一个 Provocative 的教育项目。它用 300 行 Bash 演示了 Agent 架构中最核心的那些机制，同时逼迫你重新思考一个根本问题：

你写的代码，是 Agent 本身，还是 Agent 的世界？

如果你在构建 AI 应用，把这个项目 clone 下来，逐个 Session 跑一遍。它的价值不在于你能用 Bash 替代 Claude Code——你不能——而在于它让你看清楚，Claude Code 优雅在哪里，以及为什么那些优雅不是来自"AI"，而是来自"Engineering"。

延伸阅读