维护、更新与版本迁移

本仓库把解释固定到一个上游 commit；上游换 commit 后，源码链接、行号、API、CLI 命令和社区判断都可能失效。本篇说明什么时候应该更新，以及怎样更新才不会把新旧版本混在一起。

先分清两个版本

版本	看哪里	它表示什么
上游源码版本	`UPSTREAM.md` 和 `source-index-manifest.json`	导读当前解释的官方 DSH commit
学习仓库版本	GitHub 提交、分支或 tag	中文材料、生成器和验证器的变更

学习仓库可以在不改变上游版本的情况下改进中文解释。只有准备重新解释另一个 DSH commit 时，才更新上游基线；不要因为学习仓库有新提交，就把官方源码版本也写成新版本。

什么时候不要更新上游

只想修错别字、改善中文、增加学习练习或补一个静态链接时，不需要下载上游源码。保留当前固定 commit，修改学习材料并运行手写链接检查即可。

只有这些情况才考虑迁移：你要研究的新功能不在固定提交、固定链接已经不能回答问题、官方 API/CLI 发生变化，或者你明确要建立一个新的版本快照。

版本迁移的安全顺序

1. 先记录新基线

确认新的官方仓库、完整 commit SHA、标签或版本号和获取时间。不要只写 master，也不要把一个短 SHA 当作唯一来源。

2. 下载到独立临时目录

使用学习仓库实际使用手册中的固定提交下载方式，把完整上游源码放在学习仓库之外。生成文件级证据需要完整源码目录；sparse-checkout 只能支持路径导航，不能支持完整扫描。

powershell

$commit = '替换成完整的新提交 SHA'
$sourceRoot = Join-Path (Split-Path (Get-Location) -Parent) ('_dsh-study-upstream-' + $commit)
git clone --filter=blob:none https://github.com/deepseek-ai/deepseek-harness.git $sourceRoot
git -C $sourceRoot checkout --detach $commit
git -C $sourceRoot rev-parse HEAD

最后一条命令必须与 $commit 完全一致。若不一致就停止，不要生成新索引。

3. 在生成前保留旧版本

先提交或打 tag 保存当前学习仓库。生成新索引前，记录当前 UPSTREAM.md、清单数量、索引页数量和质量审计输出；这样新旧差异才可解释。

4. 重新生成并检查差异

按照根目录 README 的生成命令，把 --commit 和 --source-root 指向同一个新基线。生成后先查看 git diff --stat 和 git diff --name-only，确认没有把临时源码、node_modules 或其他项目文件写进学习仓库。

然后依次运行：

powershell

node study-tools/verify-source-index.mjs
node study-tools/audit-source-index-quality.mjs
node study-tools/verify-study-links.mjs
git diff --check

验证器通过只是第一道门。还要搜索旧 commit、旧行号、旧事件名、旧 CLI 命令和旧社区链接；这些内容可能位于手写专题中，不会全部由索引验证器发现。

5. 重新人工核对高风险专题

至少重新阅读这些材料：工具契约、Hook Bridge、Bundle/Profile/Loader、插件测试卸载、社区生态和所有安装命令。它们对版本最敏感，不能只依靠生成器重写。

6. 更新边界说明并清理临时目录

同步修改 UPSTREAM.md、根 README、固定版本链接和实验命令。确认质量审计错误和模板复用统计的变化有解释，再按明确路径核对临时目录，研究完成后清理下载物。

上面的步进器把六步安全顺序变成可步进的：点步骤名或用上一/下一按钮走流程；每步的说明来自对应小节，包括「不一致就停止」「验证器通过只是第一道门」这两条硬性守卫。

迁移时最容易犯的错误

只改 UPSTREAM.md 的 SHA，没有重新生成索引；
用新源码目录生成旧 commit 的索引，导致代码证据与链接错位；
在 sparse-checkout 工作树上生成，把所有 import 和行数错误地写成空值；
只更新自动索引，没有更新手写文章中的官方 URL 和命令；
把新版本的测试名称当成旧版本已经存在的证据；
发现条目数量变化，就直接删除旧索引页而不解释新增、移动和删除；
把上游版本升级写成“所有插件都兼容”，却没有重新做 Loader、构建和卸载测试。

版本迁移后的验收表

text

[ ] 新 commit 是完整 SHA，且 rev-parse 与它一致
[ ] source-index-manifest.json 与索引页来自同一提交
[ ] 源文件数量、读取数量和索引条目数量可解释
[ ] 固定 URL、标题路径和行号没有越界
[ ] 手写专题中的版本、事件、CLI 和社区链接已复核
[ ] 工具、Hook、Bundle/Profile、卸载和社区审计材料已人工重读
[ ] 文档门禁通过，质量提示有解释
[ ] 上游构建/运行/第三方安装未验证的部分仍明确标注
[ ] 临时源码目录已核对并清理

如果只是普通学习者，不需要自己做版本迁移。直接使用当前固定快照；只有你要研究新版本行为，或准备维护这个学习仓库时，才按本篇流程操作。

当前基线的语义复审记录

迁移到 aa6c361a（0.1.1-rc.2）时做过一次限定范围的语义复审：对照 47f943859..aa6c361a 的 diff，逐个检查手写课程引用的源码面。结论按证据状态记录：

引用面	diff 概况	复审结论
`packages/core/agent-loop/src/agent.ts`	+31：Turn 在流中途被取消时，已送达前缀落盘为 `assistant/message { interrupted: true }`	已写进 05 课的事件表；“模型可见即已记录”规则因此覆盖取消场景，不冲突
`packages/core/session/src/known-event-types.ts`	新增 `team/member`、`team/message/*`、`team/task` 四种事件类型	05 课事件表本就是教学选摘，已加“完整清单见 known-event-types.ts”指引
`packages/llm/llm/src/index.ts`、`assembler.ts`、新文件 `content.ts`	新增 `prepareCall` 把模型元数据与流入口绑定到同一适配器代际；图片内容投影	已写进 06 课；“Agent Loop 不知 HTTP 细节”的分层表述仍成立
`packages/core/tools/src/code-mode.ts`	工具描述文案微调；含图片的子调用结果在运行后作为上下文延迟注入	33 课引用的调度注释行区间未受这些改动影响，结论保持有效
`packages/boot/app-boot/src/index.ts`	bootstrap 环境变量黑名单加入 `BROWSER`	课程未逐项枚举该清单，无需改文
其余 packages/core、hooks、boot、cli、llm	多为 README 双语、package.json 版本号和测试增量	索引页由生成器从新归档重读，已自动反映

仍未复审的：上述面之外的 854 个上游提交（vendor、apps/web、python SDK 等）；需要真实运行的差异（模型行为、token 计费、SSE 细节）依旧属于 unknown。下次换基线时，把本表当作模板更新日期和结论。

维护、更新与版本迁移 ​

先分清两个版本 ​

什么时候不要更新上游 ​

版本迁移的安全顺序 ​

1. 先记录新基线 ​

2. 下载到独立临时目录 ​

3. 在生成前保留旧版本 ​

4. 重新生成并检查差异 ​

5. 重新人工核对高风险专题 ​

6. 更新边界说明并清理临时目录 ​

迁移时最容易犯的错误 ​

版本迁移后的验收表 ​

当前基线的语义复审记录 ​