DSH 源码学习仓库
August 28, 2026 · View on GitHub
这是 DeepSeek Harness 官方仓库 的社区学习型 fork：把官方 DSH 固定在提交 aa6c361a972c8369148dea7380bb5c21c24e07ec（根包 0.1.1-rc.2），为 2,973 个源文件提供中文逐文件导读，并配套五十九个可动手的确定性实验。它不属于 DeepSeek AI，不代表官方立场；"官方"在本文中只指上游来源，不表示本仓库获得授权。中文镜像：README.zh.md。
三条入口
第一次来不需要下载源码、配置 API key、安装 pnpm 或先会 TypeScript——普通 GitHub 网页就能完成第一轮。
- 开始学习入口 START-HERE.md：按你的目标告诉你下一步点哪一篇。
- 15 分钟动手任务单：不想选路线就照着做，最后留下一条带源码证据的学习记录。
- 最小插件示例与学习检查：想动手时先跑示例的单元测试和 lint。
发现文档事实错误、链接问题、教程无法复现或社区扩展风险时，请使用按类型填写的 Issue 表单；不要提交密钥、Cookie 或私有运行日志。
五十九个可以动手的实验
这套教材要求每个关键结论都能落到一个确定性实验里：实验全部离线运行——固定输入、固定输出、独立 oracle、公开 canProve/cannotProve；它们是教学模型，不启动真实 DSH、provider 或模型。完整清单见实验室总览。
| 实验 | 回答什么问题 |
|---|---|
| Turn 流程与日志对应 | 一次 Turn 怎样从输入走到 Session 日志；步进滑杆能停在任意一步；输入写进 URL hash，刷新不丢 |
| 包依赖图证据 | 227 个包、50 个组的依赖形状；含可选的 3D 组体量场景（带 2D 表格回退） |
| Profile 解析顺序 | Bundle 声明顺序怎样决定最终装配出的配置 |
| Session 日志重放 | 为什么模型可见内容必须能从事件日志重建 |
| LLM 流式拼装 | chunk 按到达顺序怎样拼成一条消息；finish 之后的迟到重复块为什么必须丢弃 |
| 提示词装配与缓存边界 | 系统提示词按 order 升序装配后，变化点之前的前缀为什么照旧命中缓存 |
| 文件编辑管线 | str_replace_editor 的唯一匹配替换、多义行号拒绝与沙箱写入执法 |
| Web 工具管线 | HTML→GFM 的深度守卫、有效截断脚注，以及搜索多查询的轮转合并去重 |
| 工具可见性三层集合 | "已注册、模型可见、执行允许"为什么是三件事 |
| Code Mode 权限管线 | Code Mode 子调用为什么仍要经过完整权限管线 |
| 上下文压缩 | 压缩前后各保留什么、丢什么、oracle 怎样核对 |
| 插件订阅与日志 | 订阅、策略拒绝和卸载怎样影响一个观察插件；插件动作与 Session 日志为什么是两回事 |
| Hook 瀑布短路 | 瀑布监听器直接 return 而不调用 next 会怎样；被跳过的兜底和最终结果的作者 |
| 审批流 | ask 的完整生命周期；没有应答者时怎样退化为拒绝、allow 的授权范围有多大 |
| Session fork 与修复 | fork 怎样继承父日志前缀；崩溃后的 interrupted 修复为什么记为 unknown 而不是成功 |
| subagent 委派 | 深度上限如何在边界拦下委派；子工作的回报结算与父子泳道隔离 |
| 循环卫生 | 重复调用的阈值拦截；为什么后置结算撤不回 guard 的拒绝、执行账目如何保持平衡 |
| Shell 解析缝隙 | resolve(request) 怎样补默认、封顶、盖沙箱章；run/start 为什么只收 Spec |
| 凭据解析 | 没有 Provider 能供应凭据引用时，fail-closed 怎样在解析处拒绝 |
| 文件设置热发布 | 另一个进程改了 settings.yaml 后，本进程靠 fs 监听器走同一条热发布路径 |
| 后台任务生命周期 | kill 的两种返回、先到先得的结算、reported 认领与通知抑制 |
| 定时与工作流编排 | 三种定时触发器的追投语义，工作流 agent 按 seq 配对与有界宽限强结算 |
| 工作流节点折叠 | 四条持久记录折成一个聊天节点；合法前缀与 interrupted 呈现，工具卡不变 |
| 客户端三面镜 | ui-tool 卡片状态机、ui-conversation 折叠引擎、ui-user-questions 提问接管 |
| Web 提供者矩阵 | 同一缝隙三种搜索实现的归一化对照；选择策略的六情形错误码表 |
| Trajectory 投影 | 事件流怎样按呈现契约折叠成用户气泡与三种工具卡（generic/terminal/diff） |
| 技能目录渐进加载 | 摘要信封、digest 驱动的替换退役，以及 skill 工具的三种结局 |
| 计划栈 | Todo 整表替换、Plan 状态机与 Goal 生命周期怎样落在同一份日志上 |
| Worker 协议 | workflow 子任务的阶段推进、取消语义与日志边界 |
| 溢出转储 | 超过 maxInlineBytes 的结果全文进工件，模型拿到预算内的预览加定位符 |
| 终端会话 | 持久会话的状态延续与一次性模式对比，单发送位与进程树停稳 |
| MCP 客户端 | 外部服务器工具以限定名进场；指数退避重连，卸载释放命名空间 |
| 自我修改 | define/run/stop/undefine 给自己装插件；坏定义 fail loud，动态工具同一条权限管线 |
| 子进程 | DSH_ 环境隔离、输出封顶保留 TAIL、spill 完整可恢复或明确丢弃 |
| 语言服务 | 扩展名独占预留与原子注册，查询按最终扩展名路由 |
| 线协议 | 按行分隔的 JSON-RPC：id 配对、通知单向、initialize 必须是第一句 |
| Token 计量 | 从日志重放推导读数；两种基线口径殊途同归，压力只报数不截断 |
| Agent 预设 | 常驻挂载装载一次，N 个 agent 经作用域加入而非复制 |
| 检查点策略 | 三个持久化时刻与崩溃后可恢复范围的推演 |
| 匿名身份 | home 作用域随机 id：删除即重铸，进程内记忆 |
| 时间上下文 | 选择性加入的带归因时间读数，durable 入册重放原样回来 |
| 图片附件 | 尺寸限制在保存处强制执行，拒收时零引用 |
| 消息反馈 | 按消息 id upsert，绑定已定稿生命周期，重复即更新 |
| Code 运行结果分类 | run() 失败也照常 resolve：error 是结果字段；六类失败彼此正交，binding 命名空间过三道检查 |
| 上下文指令发现 | pre-step 从项目根到 cwd 扫描指令文件候选名；同目录同字节内容去重取最早，durable 消息注入 |
| 宿主路由与接缝 | 路由未命中才轮到回退座位；directoryPicker 接缝换后端，消费方契约原样不动 |
| 运行时不变量 | ./invariant 伴生插件注册检查：关掉检查也占住名字；fail 带包名归属，失败释放保留位 |
| Session 日志查询 | 序号闭区间窗口加大写不敏感子串搜索，逐条合取；纯读不改日志 |
| 沙箱策略边界 | 三种模式三条边界；sandbox/mode 事件入册，重放重建同一策略；拒绝带升级指引 |
| 会话投影折叠 | 四条投影并行折叠同一条事件流；无关事件返回同一引用，下游零开销 |
| 存储后端契约 | 单元名同时当文件名和 SQL 标识符；版本戳对不上拒开；写完即持久，close 后报 closed |
| Typert 类型图 | TS 源抽成编译器无关的类型图；registry 两阶段提交，冲突在变更前抛错零残留 |
| 工作区注册表 | realpath 规范化后去重，先到者排前；header 校验挂靠，非法移动抛错原记录不动 |
| ACP 桥实验室 | 自动化客户端看到的 Turn 怎样被桥删减：stdin/stdout 按行 JSON-RPC，只有提交后的助手文本过线 |
| 研究 ↔ Debug 离线桥 | 课程网站与独立 Debug 工具怎样用显式文件交接 |
| 工具预算收窄实验室 | 已注册的工具要过注册、restrict、原生呈现、宿主能力、审批五层才轮得到模型：18 个最后剩几个，当场算给你看 |
课程地图
| 阶段 | 课程 |
|---|---|
| 认识 DSH | 00 从零开始 · 01 仓库地图 · 02 Cordis 与插件树 · 25 动手任务单 · 27 工具预算决策卡 |
| 主链路精读 | 03 核心文件 · 04 Agent 与 Turn · 05 Session 日志与恢复 · 06 LLM 与工具执行 · 07 Host/Client/测试发布 |
| 插件与生态 | 10 扩展边界 · 11 写合规插件 · 12 生态检索核验 · 13 工具插件契约 · 14 Hook Bridge · 15 Bundle/Loader · 22 工具可见性 · 35 最小插件工作台 |
| 实验与治理 | 16 工作簿 · 19 测试卸载证据 · 21 网页/Codespaces 路线 · 29 质量检查与审阅 · 30 安全告警与发布维护 · 31 学习工具箱 · 32 渐进式设计 · 33 可视化协议 |
其余专题（索引读法 08、业界案例 09、观测实验 23、人工抽查 24、完成度审计 17、维护迁移 18、实际使用手册 20、后续研究 26、Debug 协作 36 与作者判断 34）都从 START-HERE 可达。
逐文件索引
固定提交中按生成器白名单识别出 2,973 个代码或界面源文件（TypeScript 2,472、TSX 262、CSS 112、SQL 56、MJS 32、Python 20、JS 9、Shell 6 及其他），分到 study/文件索引/ 的 78 个索引页；每条目有 11 个必填字段：所属层、文件角色、用途、设计原因、文件级设计证据、直接协作者、对应测试、测试关联依据、阅读顺序、代码证据和固定版本，另有可选的「测试支持」字段。清单机器可查，生成器、验证器、质量审计器和手写路径验证器保证覆盖与路径正确。普通条目是结构化自动导读，不是逐行人工审查。
与上游的边界
- 上游固定提交
aa6c361a972c8369148dea7380bb5c21c24e07ec的 Git tree 有 7,903 个文件；本仓库不复制它们，每条源码链接都回到该 commit。要逐行构建时按 UPSTREAM.md 下载同一提交。 - 官方架构与开发文档仍在
docs/；study/是额外的中文学习层。本仓库对上游代码只做过两类已登记的改动：给ToolRuntime加只读debugSnapshot()观测接口供第 23 课的离线 A/B 使用，以及少量 CI/测试适配；除此之外不改写官方实现，源码解释一律以固定提交为准。 vendor/是 Cordis 等第三方项目的固定副本，DSH 对其有本地修改；不能把每项实现都归因于上游或 DSH 原创。- 本仓库的导读、索引和生成器不是官方 API，不承诺跟随 DSH 未来兼容性。
CI 只保留两条工作流
docs-pages.yml 把教材构建到 GitHub Pages；study-quality.yml 跑源码编译、单元测试、lint、最小示例、索引校验、学习契约和文档门禁。上游的发布/E2E/E2B 工作流已移除，避免误跑外部服务。绿色只证明各自列出的静态或离线检查通过，不证明 DSH 运行时、真实模型调用或社区插件安全。
在 Codespaces 里可以一条命令自查教材完整性（不启动 DSH）：pnpm run study:quick-check --example --runtime。
运行官方 DSH
pnpm install
pnpm run build
pnpm dsh web
需要网络、操作系统能力和 DEEPSEEK_API_KEY；文档索引生成成功不等于 DSH 构建成功。
重新生成索引
node study-tools/generate-source-index.mjs --commit aa6c361a972c8369148dea7380bb5c21c24e07ec --source-root <同一提交的完整源码目录>
省略 --source-root 会把行数、声明和 import 证据降级为空，不能用来覆盖已提交的学习材料。换基线的完整流程见第 18 课。
许可证
官方项目与本仓库新增材料均为 MIT 许可证；第三方依赖见 THIRD_PARTY_NOTICES.md。