企业官网建设流程全解析

learn-claude-code 完整实战指南：从零搭建 coding agent 的 Agent Loop 与 Harness

【免费下载链接】learn-claude-codeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1项目地址: https://gitcode.com/GitHub_Trending/an/learn-claude-code

如果你一直想拆开 coding agent 的黑盒，看看 AI Agent 到底是怎么造出来的，learn-claude-code 这个仓库值得一路跟下来。它的立场非常直接：一个能用的 Agent 产品 = 模型 + 一套 Harness（模型的运行环境），智能长在模型里，而你该投入的工程精力，是搭建 Harness。全仓 17 个会话，从一个十几行的 while 循环（也就是 Agent Loop）起步，一路拼到目标闭环，每一节都配一个能独立运行的 code.py。读完并跟着跑完，你至少能做到三件事：把 s01 示例亲手跑起来，说清楚"模型负责到哪里、代码负责从哪里开始"，以及看清全部 17 个会话的主线安排。

先跑起来：如何三步跑通第一个 Agent Loop 🚀

不需要任何前置知识，三步。第一条命令把仓库克隆下来：

git clone https://gitcode.com/GitHub_Trending/an/learn-claude-code cd learn-claude-code pip install -r requirements.txt cp .env.example .env # 填入 ANTHROPIC_API_KEY 和 MODEL_ID python s01_agent_loop/code.py

这段命令说明了什么：依赖只有 anthropic、python-dotenv、pyyaml 三个包，配置只有两个必填字段，然后一条 python 命令进入 s01 的交互终端——这就是从零到"能对话的 agent"的全部成本。

跑起来之后实际发生了什么？终端出现s01 >>提示符，你输入"列出当前目录的 Python 文件"回车，接着屏幕上会滚出一串带$前缀的黄色命令行——那是模型决定调用 bash，而你的代码真刀真枪地执行了它，把输出以 tool_result 的形式塞回 messages，模型看到结果后决定要不要再发下一条命令。如此往复，直到模型某次不再返回工具调用，最后打印一段文字结论。中间没有编排库、没有节点图，就一次 LLM 调用套着一个 while 在转。

想换模型或者用国内访问更顺的端点，也只需要改.env，这一点放到后面"坑"那一节细说。

看懂全貌：Agent Loop 的最小骨架

整个仓库就是围着这一张图长出来的：

把 s01_agent_loop/ 的 code.py 剥到骨头，就是下面这十几行：

def agent_loop(messages): while True: response = client.messages.create( model=MODEL, system=SYSTEM, messages=messages, tools=TOOLS) messages.append({"role": "assistant", "content": response.content}) if response.stop_reason != "tool_use": return results = [ {"type": "tool_result", "tool_use_id": b.id, "content": run_bash(b.input["command"])} for b in response.content if b.type == "tool_use" ] messages.append({"role": "user", "content": results})

这段说明了什么：唯一的工具是 bash，system prompt 只有一句话要求模型"行动，别解释"，而退出条件只有stop_reason != "tool_use"一条——"什么时候该停"完全交给模型，代码只剩一个职责：执行工具、把结果回灌 messages、让循环继续转。模型做决策，代码只负责执行，这条分工线贯穿后面所有 16 节。

顺手看一眼 bash 执行器的开头，它藏着后面两节课的胚胎：

def run_bash(command: str) -> str: dangerous = ["rm -rf /", "sudo", "shutdown", "reboot", "> /dev/"] if any(d in command for d in dangerous): return "Error: Dangerous command blocked" r = subprocess.run(command, shell=True, timeout=120, capture_output=True, text=True) return ((r.stdout + r.stderr).strip() or "(no output)")[:50000]

这段说明了什么：危险命令黑名单、120 秒超时、输出截断到 5 万字符——就给模型"自由"套的第一道边界。s03 的 Permission 和 s04 的 Hooks 要做的，就是把这种"拦一下"升级为一条有规则、有审批、有扩展点的正式流水线。

Harness 到底是什么：模型与代码的真实分工

先澄清一个最容易搞混的问题：模型不是被周围代码"教会"做 agent 的。感知、推理、行动这套能力来自训练本身——2013 年一个神经网络只靠原始像素和分数就自学会了 7 款 Atari 游戏，没有任何规则表；2019 年 OpenAI Five 纯粹靠自我对弈学会团队配合，直播中 2-0 击败世界冠军战队。这两个案例里，"能动性"都是从权重里长出来的，不是从编排脚本里拼出来的。

所以真正的工作天然分成两半。把模型看成选手，球技是数据中心的千万张显卡喂出来的；Harness 就是赛场和装备：文件读写、shell、API 调用，是选手在场上能完成的动作；领域文档、风格指南，是比赛规则；git diff 和错误日志，是记分牌；沙箱和审批流，是裁判。选手做判断，赛场提供执行条件；选手做推理，赛场提供上下文。coding agent 的赛场就是 IDE、终端和文件系统——换成农业、酒店、制造这些领域，循环一个字不用改，变的只是赛场。这也解释了课程反复强调的一点：你要写的是 Harness，不是 Intelligence。

顺带划掉一类"伪选手"：拖拽式工作流构建器、无代码 AI Agent 平台、用 if-else 和节点图串 LLM 调用的编排库。这不是在培养选手，是在提线——路线被程序逻辑预先画死，模型只是流程里某个节点的文本补全器。智能不可能从规则树里"组装"出来，它只会在一个开放循环里、由模型自己一步步做决策时出现。这也是为什么本课程的每一个会话都拒绝往循环里塞死流程。

17 个会话怎么安排：按五个能力阶段走主线 🧩

每节只加一个 Harness 机制，机制配一句口号。17 节连起来是一条能力曲线：能动 → 能干复杂活 → 能记能长跑 → 能协作 → 能编排收尾。

阶段 1 里，s02 把 s01 里硬编码的 bash 调用换成一张 TOOL_HANDLERS 分派表，从此"加工具 = 加一个 handler"，工具从 1 个涨到 5 个；s03 和 s04 则把放行、拦截、问用户三态做成权限流水线，并在循环外留出 PreToolUse / PostToolUse 钩子，扩展不改主循环。阶段 2 是干活能力：s05 逼模型先写计划再动手；s06 给子任务一份全新的 messages[]，干完只回传一个 tool_result，上下文互不污染；s07 的知识加载只先给模型目录，需要时才展开正文；s08 的四级压缩按 budget、snip、micro-compact、summary 的顺序先整理工具结果，超限了才动历史摘要。

阶段 3 管"活得久"：s09 的记忆拆成选择、提取、整理三个子系统；s10 把目标拆成带 blockedBy 依赖的任务图写进文件，目标因此能活在一个会话之外；s11 把慢命令丢进后台线程，完成时再往对话里注入通知；s12 用持久化的 cron 让任务到点自己启动。阶段 4 的 s13 是全仓信息量最大的一节：常驻队友、原子认领可执行任务、任务绑定的 worktree 隔离并行、类型化团队协议，全部收在一节里。

阶段 5 是收口：s14 让 MCP 外部工具接入同一个工具池；s15 把此前所有机制收回一个循环，s15_integrated_harness/ 单文件 3000 多行，用 DEFAULT_MAX_TOKENS、CONTEXT_LIMIT、KEEP_RECENT_TOOL_RESULTS 这类显式常量管理运行时预算，和 s08 的压缩机制一脉相承；s16 让固化的 Workflow 能从 journal 恢复执行；终点 s17_goal_loop/ 的机制很小但很妙——模型说"这轮我想停"不再等于结束，一个独立的 evaluator 会复核目标是否达成，没达成就把没干完的活送回同一个 agent loop，"该不该结束由目标说了算"。

容易踩的两个坑：新旧章节编号与兼容模型端点 ⚠️

第一个坑是编号。仓库里现存两条教程轨道：根目录 s01–s17 是现行正式版，每节带中/英/日三语 README 加独立 code.py，这是你该走的路；而agents/和docs/目录是旧 12 节版，仅为兼容旧读者在过渡期保留。两套编号并不对齐——最典型的是旧 s03 讲的是 TodoWrite，现行 s03 讲的是 Permission，照旧教程的章节号去找内容会直接找错门。旧 12 节与现行 17 节的大致对应关系如下：

第二个坑是模型端点。.env有三个字段，ANTHROPIC_BASE_URL是可选的，而.env.example里直接内嵌了一张 Anthropic 协议兼容提供方对照表：MiniMax、GLM、Kimi、DeepSeek 各自的 Base URL 和 MODEL_ID 取值，国际站和大陆站两组都列了，抄一行就能用。换句话说，这门课从第一天起就默认模型的"人"可以换、赛场不用换——端点一换，整套 Harness 原样工作，这正是"模型与 Harness 解耦"最具体的体现。另外提一句，tests/ 里有 13 个测试文件覆盖压缩配对、技能加载、任务系统、目标闭环等机制，想核对某个行为又舍不得花 token 时，直接读对应测试比真跑一遍更划算。

结语：代码与智能的分界线在哪

17 节跑完，你手里多出的不是"一个更聪明的模型"，而是一张边界图：智能在训练里长出来，你的代码只负责把赛场修好——动作要原子、知识要按需、边界要清楚、目标要能验收。循环永远长一个样，变的是工具、知识、规则和赛场的大小；从填好一个终端，到填好一个团队的工作流，路径是同一句话。

你写的代码永远不会让模型变聪明，只会让模型的聪明有地方落地。

【免费下载链接】learn-claude-codeBash is all you need - A nano claude code–like 「agent harness」, built from 0 to 1项目地址: https://gitcode.com/GitHub_Trending/an/learn-claude-code