ToolBox零基础导读（先读这一篇）
如果你第一次接触「智能体 / agent / 大模型」这些词，别急着从第 1 章开始。这一篇用大白话把你需要的几个概念先讲清楚，后面 14 章都会用到它们。
0.1 什么是「agent（智能体）」
agent 是一个会自动「想一步、做一步、看结果、再想下一步」的程序。
想象你请了一个助理，跟他说：「帮我查一下最近有什么新手机，写一份对比报告。」
这个助理不会只回你一句话，而是会自己：
- 想：先上网查手机 →
- 做：打开网页搜索 →
- 看结果：搜到一堆资料 →
- 再想：资料不够，还要查价格 →
- 做：再搜价格 →
- ……直到把报告写完交给你
这个「想 → 做 → 看 → 再想」的循环，就是 agent 的核心。 传统程序是「你让它干嘛它就干嘛，一步都不多走」；agent 是「你给它一个目标，它自己拆步骤、自己动手、遇到问题自己想办法」。
0.2 agent 由两样东西组成
一个 agent，本质上就是两个零件：
- 大脑（大语言模型，简称 LLM）：负责「想」和「说」。它就是 ChatGPT、DeepSeek 背后那种模型——你给它一段话，它回你一段话。
- 手（工具，tool）：负责「做」。读文件、写文件、跑命令、上网搜索、发消息……这些都是工具。
大脑只负责「决定下一步干什么」，真正动手的是工具。大脑说「我要读这个文件」，工具就去读；读完把结果给大脑看，大脑再决定下一步。
注意：大脑自己碰不到电脑上的任何东西。没有工具，它只会空想、干说。给它配上工具，它才「长了手」。
0.3 那「harness（框架）」又是什么
光有大脑和手还不够。谁来：
- 把大脑和手接起来？
- 记下每一步干了什么（免得忘了）？
- 管权限（哪些文件能碰、哪些不能）？
- 出错了怎么兜底、卡住了怎么办？
harness（框架）就是干这些的——一个「装配台 / 骨架」。 它把大脑和一堆手组装成一个能正常工作的 agent，并负责后面的记录、权限、容错。
DeepSeek Harness（本教程的主角，简称 dsh）就是这样一个装配台。 本教程就是讲：这个装配台是怎么搭的、有哪些零件、以及你怎么往上加自己的零件。
0.4 dsh 最特别的一点：一切皆插件
dsh 有个核心设计，就一句话：所有零件都是「插件（plugin）」，像乐高积木一样能插能拔能换。
- 大脑是一个插件，想换成别家的模型？换一块积木就行。
- 每只手（读写文件、跑命令、上网搜索）各是一个插件，想加一只新手？插一块新积木。
- 记忆、权限、记录日志……也都是插件。
好处是：你要扩展 dsh，不用去改它的代码，只需要「插一块自己的积木」。 这和「换电脑的 USB 设备不用拆电脑」是一个道理——只要接口（下面说的「接缝」）对得上。
所以整本教程反复出现的词，你都可以先记成这个意思：
| 词 | 大白话 |
|---|---|
| 插件 plugin | 一块可插拔的积木 / 零件 |
| 服务 service | 每块积木对外提供的「能力」（比如「我会跑命令」） |
| 事件 event | 零件之间互相喊话（「我做完了」「我要开始了」） |
| 接缝 seam | 标准接口 / 插座（换设备不用换电脑，就靠它） |
| 上下文 context | 一个「放所有零件的大箱子」，零件之间通过它互相找到对方 |
第 3 章会把这些词逐个讲透；这里先混个脸熟，读到后面不慌。
0.5 两个贯穿全书的原则（先记住，会反复遇到）
- 模型所见，必入日志。 凡是要给大脑看的东西，都会被记进一本「流水账」（会话日志）。好处：随时能查「当时到底发生了什么」、能回放、能恢复。
- 换零件，不重造整台机器。 想换一个功能，就换掉对应的那块积木，其它部分不用动。
0.6 教程怎么读
按顺序读就行，每一章都建立在前一章之上：
- 第 1 章：看全景——dsh 长什么样、有哪些大块零件。
- 第 2 章：亲手把它跑起来，眼见为实。
- 第 3 章：学会「积木怎么拼」（Cordis 框架）。这是最重要的地基，后面全靠它。
- 第 4–12 章：一块块认识零件——大脑、各种「手」、记忆、权限、对外接口……
- 第 13 章：自己动手加一块零件。
- 第 14 章：怎么把活干得规范、怎么测试。
前 3 章基本不需要会编程，看懂概念就行；从第 4 章开始会出现代码片段，但每段都配了讲解，跟着看也能懂个七八成。
0.7 需要的准备（真的不多）
- 会用电脑、会在「命令行 / 终端」里敲几行命令——第 2 章会手把手带。
- 会一点编程更好，但不是必须（想自己动手加零件时才需要）。
- 需要装两个工具：Node.js 和 pnpm，第 2 章会教怎么装、怎么验证。
准备好了？从第 1 章：总体架构开始吧。