练习 0：什么是 harness——模型不是产品

前言说清了 agent 是什么：LLM + tool use。这一章回答下一个问题—— 你每天用的 Claude Code、Cursor、各家的"智能助手"，到底是什么？

先做一个思想实验。同一个模型——同一天、同一个版本、同一个 API——把它装进两个产品： 一个是网页聊天框，一个是 Claude Code。前者只会跟你聊天， 后者能读你的仓库、改你的代码、跑你的测试、在删文件前停下来问你。

模型一模一样，能力天差地别。差别是谁给的？

harness：把马力变成拉力的那套东西

harness 这个词的本义是挽具——套在马身上，把马力变成拉力的那套装备。 没有挽具，马力再大也拉不动车。

在 agent 的世界里，harness 是包住模型的那层程序：它持有对话、注册工具、执行工具、 把结果喂回去，管权限、管上下文、管记忆。模型是马，harness 是挽具， 你看到的那辆跑起来的车，才是产品。

把你以为的"模型能力"逐项拆开看：

你看到的实际是谁提供的
它记得这段对话说过什么harness——messages 数组是你维护的（练习 3）
它会读文件、跑命令harness——工具是你注册的（练习 5–10）
它删文件前会先问你harness——权限是你设计的（练习 9）
聊了一下午也没失忆harness——压缩是你触发的（练习 13）
它懂你项目的规范harness——规则文件是你注入的（练习 14）
它"学会"了新技能harness——skill 是你加载的（练习 16–18）
它分身同时干几件事harness——subagent 是你实现的一个工具（练习 19）

模型提供的是什么？语言、推理，和最关键的一件事：决定下一步调哪个工具。 这已经足够惊人——但仅此而已。

智能来自模型，能力边界全来自 harness。

为什么要自己写一遍

不是让你去造一个轮子跟 Claude Code 竞争。是因为：你读不懂你没写过的东西。

只用过 agent 的人，对故障的解释全是玄学："它今天变笨了""它抽风了""多说几遍就好了"。 写过 harness 的人知道去查哪里：上下文是不是满了？工具结果是不是被截断了？ 权限是不是把调用拦了？规则文件是不是被压缩总结掉了？ 同一个现象，一边是烧香，一边是排查——差别就是有没有亲手写过这个循环。

还有一层，后记里会展开：这套东西一通百通。把 read_file 换成"查订单"， 把 bash 换成"退款"，再换一段 system prompt，它就是一个客服 agent。 你将来在公司里做的那个垂直 agent，和这本书教你写的，是同一个东西。

全书的路

一条命令行程序，从 60 行长到一个完整的 harness。每一部结束时，它都能跑：

  • Part 1（练习 1–4）：地基。一次调用、流式、多轮对话、接两种协议。
  • Part 2（练习 5–10）：心脏。第一个工具、注册表、bash、base prompt、权限、误删保护。
  • Part 3（练习 11–15）：记忆。会话落盘、上下文预算、压缩、规则文件、跨会话记忆。
  • Part 4（练习 16–18）：知识。skill 的加载、触发，和为什么别让它自己写。
  • Part 5（练习 19–21）：分身。subagent、并行扇出、编排该交给谁。
  • Part 6（练习 22–23）：高阶。MCP、沙箱。
  • Part 7（练习 24–30）：一个真正的产品。常驻界面、插话、定时循环、goal、 后台任务重构、更多工具，压轴是浏览器。
  • 终章（练习 31）：回望全部。

书里每一段代码都从一个真实生产 harness（octo）蒸馏而来——不是为教学发明的玩具， 是删掉了工程噪音的真实实现。

你需要准备的东西

三样，一样都不贵：

  1. Go 1.22+。为什么是 Go：单二进制、标准库够用、并发原语到 Part 5 会发光—— 而且本书的母本 octo 就是 Go 写的。你不需要精通 Go，会写函数和结构体就够， 剩下的跟着敲就会了。

  2. 一个能说 OpenAI 协议的模型。两条路，全书每个练习都同时支持，任选：

    • 云端 key：DeepSeek、Kimi、OpenAI 官方任选，本书示例用 DeepSeek。
    • 本机 Ollama：一分钱不花，断网也能跑。
    # macOS（其他系统见 ollama.com/download）
brew install ollama && brew services start ollama
ollama pull qwen3:4b-instruct

    模型选 qwen3:4b-instruct 不是随手挑的：够小（约 2.5GB，普通笔记本跑得动）， 支持工具调用——到 Part 2 你的 agent 长出手脚时，不支持工具的模型会直接出局。 注意别拉成 qwen3:4b——那是思考型版本，思考过程会吃光输出预算， 练习 1 你会亲眼看到这意味着什么。

  3. 一个终端。 没有 GPU，没有框架，没有 LangChain—— 全书唯一的第三方依赖要等到练习 30 才出现（一个 websocket 库， 到时会交代理由），在那之前标准库写到底。

规矩

the hard way 只有三条规矩：

  1. 敲，不贴。 复制粘贴学不会协议。
  2. 每章跑通再往下。 代码是累积的，练习 5 的 bug 会在练习 13 加倍奉还。
  3. 加分练习别跳过。 正文教你走路，加分练习才是你自己走的第一步。

准备好了。翻页，练习 1。