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 本地安装与查看启动组合¶
日常试用发布版可在自己的目录运行：
npx --yes @deepseek-ai/[email protected] web --no-open
默认 Web 是 127.0.0.1:3080；外部域名、反向代理、客户端授权、密钥和操作权限要分别配置。此课程部署的是静态教材，不开放一个具有服务器操作能力的 Web Agent。
要精读主分支的同一源码：
git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
git checkout da00f7f5358f2949383b35c14f548bc20187d80c
pnpm install
pnpm run build
pnpm dsh web --no-open
上述源码构建是官方主路径的说明，本次没有把整个上游应用及所有平台完整构建/测试。课程实验采用 npm 发布包，已执行固定 lockfile 安装、类型检查与真实 CLI 运行。不要把这两类验证混为一谈。
运行前检查自己的实际 tree：
npx --yes @deepseek-ai/[email protected] --profile sdk-minimal --dump-config
minimal preset 与 sdk-minimal profile 不同；code/creator UI 标签与实际 preset id 也不同。profile 决定启动载体与 bundle，preset 改 Agent 能力组合，patch 修改配置树。第 04 章逐项拆解。
01.4 分阶段的阅读产出¶
| 阶段 | 章节 | 你应能自己回答的问题 |
|---|---|---|
| 运行时思想 | 02–04 | 为什么要 definition/provider/consumer？插件卸载后谁持有资源？ |
| 请求与证据 | 05–09 | 模型看到的内容怎样从日志生成？retry 重做哪部分？ |
| 能力与隔离 | 10–13 | Shell/PTC/MCP/subagent 分别经过哪些 gate？ |
| 产品与耐久性 | 14–17 | SDK idle 是否成功？Web 身份和业务身份相同吗？哪些状态可恢复？ |
| 自建 Agent | 18–20 | 能否不用修改 loop，就替换笔记数据源并拒绝越界工具？ |
| 选择与验收 | 21–26 | 哪种设计适合自己？哪些结论真正跑过？如何追上新版本？ |
01.5 源码引用与图的读法¶
每处源码链接使用完整 Git commit 加文件/行号，图是对相关代码的解释，不是额外 API。时序图箭头表达调用与等待；flowchart 表达控制路径，不暗示跨事件的原子事务。若图里出现 log/idle/flush 三个词，它们对应不同完成层次：内存追加、运行状态静止、磁盘持久提交。
本课程保留独立审查发现的初始错误，展示修正证据和复验结果。准确课程需要的是可纠错、可追溯的结论，而不是声称第一次写作就没有问题。