01 · 版本锁定、项目身份与学习路线¶

01.1 先确认学的是哪个项目¶

官方仓库是 deepseek-ai/deepseek-harness，命令行名 dsh，npm launcher 包名 @deepseek-ai/dsh。它不是 DeepSeek 模型权重仓库，也不是 Pi 的一个 provider，更不是一个同名第三方 Agent 项目。官方 README 明确标记 developer preview，允许兼容性破坏；因此“最新版”不能代替可复现版本。固定 README

本课程继承用户对 Pi 课程的研究和验收标准，但 不会把 Pi 的 1.0 版本号套在 DeepSeek Harness 上。初次研究时，npm latest 和 next 都指向 0.2.0-rc.2，GitHub 该 tag 的 release 是 prerelease；releases/latest 接口不能据其 404 认定没有发布。

01.2 三个版本面必须分别记录¶

对象	本课程使用的版本	用途
官方主分支源码	`da00f7f5358f2949383b35c14f548bc20187d80c`	02–17 的主要源码分析，全部引用固定提交
官方 npm 发布版本	`0.2.0-rc.2`，tag `dsh-v0.2.0-rc.2`，提交 `639ed015397290b3745d163aafe02ffee4aa3f84`	18–20 实验、SDK、可下载 lockfile
官方 Python 发布面	PyPI 当时最新 `0.1.5rc1`	用来说明生态发布不同步，实验不混装此旧运行时

本仓库实际默认分支名为 master；文中的 main 是“主分支研究快照”的标签，并非一个名叫 main 的 Git 分支，操作命令应使用 master 或完整 SHA。主分支工作树为 upstream/，发布版工作树为 release/。主分支快照超过 tag 的变化单独见 26 · 版本差异，而不是把 main 类型随意套在 rc.2 npm 对象上。

版本研究记录保存完整 SHA、时间和文件数量；交付前远端复核保存最终检查结果。课程内容锁在上述快照；如果远端在后续继续变化，读者可以看清课程时点与今天远端的区别。

01.3 第一件事：让自己的资料进入一个真实 Agent¶

贯穿全书的问题只有一个：“失败的模型尝试会进入下一次模型历史吗？请查我的 Session 笔记并引用。” 我们先让运行时收到问题，再加资料、政策、预算与持久化。到最后，你应能指出答案里的每个证据是在哪次请求之前进入日志的。

下载首页的实验 ZIP，解压并进入 examples。先只装 Node 依赖；Python 可以等第20章。

npm ci --ignore-scripts
npm run build
node dist/checkpoints.js 0
node dist/checkpoints.js 1

阶段0应打印 requests: 1、reason: "completed"、运行时已接收问题。。阶段1应打印 requests: 3，答案为 失败 attempt 保留诊断，不进入模型历史。[session]。UUID、时间和绝对目录每次会变。Node 24.14+ 是实验验证环境；若 dist 不存在，先 build；若启动失败，先看排错。

这里真正启动 npm rc.2 的 dsh --profile sdk-minimal，官方 SDK、模型 adapter、Agent loop、两个笔记工具和日志都参与。只有模型端换成 loopback HTTP fixture，它按脚本选择工具，检查上一工具的真实返回后才给下一响应。因此这个实验研究运行机制；模型能否自主选择正确工具，要到后面的真实模型评估回答。

打开 artifacts/checkpoint-1/requests.json 和 events.json。第一请求只有问题；第二请求多了搜索摘要；第三请求才有笔记全文。搜索故意只给24个 JavaScript 字符预览，结论位于全文末尾：如果删掉读取步骤，前两次请求的模型消息里没有完整证据。 这是全书后续设计讨论的起点。

01.4 六个检查点：先递进，再做单因素对照¶

0→1→2依次建立收信、内存资料、JSON资料。3、4、5分别回到阶段2基线，各改变一个条件，并非把前一阶段的限制继续叠加。 因此阶段4没有阶段3的deny，阶段5又恢复正常8步预算。

命令（在examples中）	相对对应基线改变什么	应观察到什么	对应理解
`node dist/checkpoints.js 0`	只验证收信和回应	1次HTTP，无工具调用	SDK和runtime的关系
`node dist/checkpoints.js 1`	内存笔记供搜索/读取	3次HTTP，2个结果，末尾有来源	工具、Session、下一请求
`node dist/checkpoints.js 2`	provider改成宿主JSON文件	工具名和结果语义相同	definition/provider/consumer
`node dist/checkpoints.js 3`	政策禁止读取session全文	工具仍可见，结果isError，答案说证据不足	能力与执行许可分开
`node dist/checkpoints.js 4`	每轮最多2步	2次HTTP，turn为blocked，无最终答案	步骤、请求、业务完成
`node dist/checkpoints.js 5`	保留home并冷读日志	正常关闭后官方reader读V4，核对原事件	活动结束与持久事实

每步保存 summary.json、requests.json、events.json、实际 notes.patch.json；第5步另外保存 home/ 与 cold-read.json。第一次顺着01→18→19→20做完，再回02–09解释已经看到的机制。第二遍按顺序精读。10–17是给这个Agent增加产品需求时的能力参考：没有那项需求时可以跳过实现细节。21帮助选型，22–26用于查源码、维护和验证。

需要精读同一上游代码时再克隆，不必先构建整个monorepo才能做课程实验：

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
git checkout da00f7f5358f2949383b35c14f548bc20187d80c

01.5 源码引用与图的读法¶

每处源码链接使用完整 Git commit 加文件/行号，图是对相关代码的解释，不是额外 API。时序图箭头表达调用与等待；flowchart 表达控制路径，不暗示跨事件的原子事务。若图里出现 log/idle/flush 三个词，它们对应不同完成层次：内存追加、运行状态静止、磁盘持久提交。

本课程保留独立审查发现的初始错误，展示修正证据和复验结果。准确课程需要的是可纠错、可追溯的结论，而不是声称第一次写作就没有问题。