阅读说明与证据

0. 本页学习目标

确认本站对应的精确源码版本。
看懂正文里的固定提交链接与行号。
区分源码事实、设计解读和教学推演。

1. 一句话讲明白

每个重要判断都能回到固定提交 47f943859bef60e4160492346772ded9b24f765a 的真实源码，而不是依赖会漂移的 master 或 README 摘要。

证据等级

标记	含义	验证方法
源码事实	代码、类型或配置直接表达的行为	打开固定 commit 的源码链接，核对行号与符号
设计解读	从依赖方向、生命周期或失败策略得出的工程判断	同时检查调用方、被调用方与测试
教学推演	为理解而构造的典型输入路径	不声称是实际录制，按章节命令自行运行

版本与状态

上游仓库：deepseek-ai/deepseek-harness
固定提交：47f943859bef60e4160492346772ded9b24f765a
包版本：0.1.0-rc.5
状态：Developer Preview；上游明确提示未来会有破坏性变更。

阅读约定

正文先给全局地图，再只引入下一段源码所需的 TypeScript/Cordis 概念。Java 类比只帮助定位：Cordis Context 不等于 Spring ApplicationContext，Effect 也不等于普通 Bean 生命周期；真正行为以源码为准。

一章应该怎样读

每章都用一个具体场景贯穿，并按相同的认知顺序展开：

学习者的问题
  → 位置图与边界
  → 最短正确机制
  → 一次真实源码旅程
  → 决定性分支与失败路径
  → Harness 的设计取舍
  → 可迁移方法
  → 费曼复述与练习

这不是要求你从头到尾一次读完。推荐分三遍：

遍次	只做什么	通过标准
第一遍：画地图	读开头、位置图和最小机制，暂时跳过深挖	不看文档也能画出上游、核心模块和下游
第二遍：追旅程	跟着贯穿场景打开固定提交链接，核对输入、输出与状态变化	能指出每一步由哪个真实符号完成
第三遍：做迁移	阅读失败边界、设计取舍并完成费曼自测	能解释为什么没有选择更直觉的实现

第一遍不需要点击所有源码链接。链接是证据检查点，不是把阅读重新变成文件列表；遇到“为什么会继续”“谁拥有这个状态”“失败后谁清理”这类关键问题时再打开。

章节完成标准

本站不再把提纲当作课程。每章至少包含完整地图、最小机制、端到端源码路径、失败或停止边界、设计取舍、Java 类比边界、费曼自测和三级练习；自动验证还会检查固定提交、源码文件存在性与行锚点范围。

本地复核

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
git checkout 47f943859bef60e4160492346772ded9b24f765a
pnpm install
pnpm run build

上游要求 Node ^22.19.0 || >=24.0.0 与 pnpm 11.7.0。真实模型路径还需要 DEEPSEEK_API_KEY；没有密钥时，优先运行单元测试与 keyless snapshot。