源码学习项目的渐进式设计
这篇解释“为什么本学习仓库要有首页分流、最小示例、逐步检查和 CI”。编写时联网查看了几个公开的源码学习项目和文档测试项目，再把能迁移的做法翻译成 DSH 学习场景。这里引用的是项目公开页面在本次检索时呈现的结构，不把它们的课程质量、维护状态或全部运行结果夸大成已经验证的事实。
本轮补充核对（2026-08-17）包括 Rust Book、Kubernetes Basics、TypeScript Handbook、React Learn 和 GitHub Skills 的公开页面标题与可见章节结构；网络页面会变化，这些链接只用于说明教材组织方法，不构成 DSH 官方背书。
先说结论：渐进式不是把内容删薄
真正适合新手的入口，应该让读者每一步都知道四件事：
- 现在打开什么：一个明确的页面、目录或命令。
- 应该看到什么：文件出现、测试通过、页面出现，或输出里的某个字段。
- 如果不一样怎么办：给出最短的排错分支，而不是只说“检查环境”。
- 这一步没有证明什么：把静态阅读、宿主本地实验、真实 DSH、provider 和模型证据分开。
所以本仓库的“渐进式”是把 2,973 个文件放在一个不会迷路的阅读层里：先用首页选择路线，再用 15 分钟任务单得到第一次可见结果，之后才进入逐文件索引和高风险人工抽查。涉及个人取舍的判断集中在作者的判断与理由，那里是观点不是课程结论。
参考了哪些公开做法
展开参考了哪些公开做法（14 行）
| 项目或资料 | 页面中可以直接观察到的做法 | 我们借到 DSH 教材里的做法 | 不直接照搬的部分 |
|---|---|---|---|
| GitHub Skills | 用一个具体、可完成的 GitHub 任务教会用户技能，学习发生在自己的仓库和操作里 | 把“读懂 DSH”拆成可执行任务：打开入口、读一条调用链、跑一个离线检查、留下四行记录 | GitHub Skills 的机器人课程和事件自动化不属于本学习仓库默认前置条件 |
| GitHub Learn | 把课程标成项目式练习、预计时长和难度，并让学习者从一个明确的“Start Learning”入口进入 | 首页给出“只读网页／运行示例／进入 Codespaces”的前置条件和预计时间，避免把所有人都带进终端 | 外部课程的账号、编辑器和 Copilot 环境不属于本仓库的必需前置条件 |
| Microsoft MCP for Beginners | 教材仓库把模块、样例、文档检查命令和代码示例验证写进贡献者入口；学习内容和可重复检查放在一起 | 给 DSH 示例同时维护 README、源码、test、lint、预期输出和“不能证明什么”，让教材不会只剩概念 | 它的 MCP 协议课程和样例不等于 DSH 插件契约，也不证明 DSH 兼容 MCP 的全部行为 |
| Project Based Learning | 用 README 做入口目录，把学习者按语言和项目目标分流，降低第一次选择的成本 | 保留首页三条路线和“按问题选一条”的表格；不让新手先面对完整 monorepo 或 2,973 个索引条目 | 资源清单里的每个外部教程不由本仓库维护，也没有逐个复现其全部步骤 |
| Kubernetes Basics | 页面先给 Objectives，再按模块逐节展开，最后给 What's next；读者能先知道目标、再按顺序操作 | 每篇关键课程先写“这一轮目标、步骤、预期看到什么、下一步”，不要让新手从长篇背景中猜任务 | Kubernetes 的集群操作和交互式终端不属于 DSH 网页阅读的前置条件 |
| TypeScript Handbook | 先说明 Handbook 的结构、非目标、Get Started、基础和进阶入口，再把不同深度的资料分开 | 首页先分流，基础课、插件课、工具箱和逐文件索引各自有入口；新手不必先读完整参考资料 | TypeScript Handbook 是语言参考，不是 DSH 的架构说明或兼容性证明 |
| React Learn | 先用 You will learn 列出结果，再把 JSX、样式、数据、条件、列表和事件拆成小节，形成连续的学习台阶 | 给 DSH 课程写“你会产出”和小检查点，把一个大问题拆成可以在十几分钟内完成的小步 | React 的交互式示例和编辑器体验不属于本仓库默认运行层 |
| The Rust Programming Language | 书籍页面提供章节导航、搜索和键盘翻页，并把安装、章节和附录放在同一条可回退的阅读路径上 | 保留固定版本源码链接、上一页／下一页和站内搜索，同时让读者随时能回到首页路线，不在索引里迷路 | Rust Book 的编译练习和 Rust 工具链不能证明 DSH 的运行行为 |
| 100 Exercises to Learn Rust | 课程按小节展开；每节配一个练习和测试，网页、仓库、练习运行器互相指向 | 给最小插件配 README、源码、测试、lint 和“不能证明什么”；把每一步的完成判定写出来 | 我们没有伪造 DSH 的真实安装器，也没有把离线教材夹具包装成完整 Profile |
| Quint 的 Classic / CodeTour lessons | 同一学习内容提供普通 Markdown 阅读和可选 CodeTour；读者可以先在浏览器学习，再选择编辑器导览 | Pages 先保证纯网页可读；最小示例和源码链接作为第二层；未来可再加编辑器导览或短视频 | CodeTour 需要编辑器扩展，本仓库不把它设成“点开始学习”必需步骤 |
| .NET Hello World tutorial | 先列目标和前置条件，再明确“打开 Codespace／创建文件／运行命令／你将看到什么” | 在每个练习中补“你要做什么、预期看到什么、失败时先查什么”；把 Codespaces 作为可选路线而不是唯一路线 | DSH 是大型 TypeScript workspace，不能承诺一个跨平台、零依赖的运行体验 |
| Doc Detective | 把文档步骤转成可执行测试动作，例如跳转、点击、检查链接、运行代码和截图 | 把入口、链接、构建产物、示例 test/lint 和固定源码链接放进 CI；以后再扩展真实浏览器点击 smoke | 本仓库当前的 Pages 检查仍主要是静态构建和 HTML/链接检查，不冒充完整浏览器 E2E |
| Docs Like Code：Test the Docs | 最小 CI 先做“构建文档 + 检查链接和图片”，再考虑 lint 等增强项 | CI 先保证 install/build/链接/fragment/示例 test/lint，再把运行时 A/B 作为明确边界的本地观察 | 不把外部链接偶尔不可达误写成 DSH 运行时失败；网络检查应标注网络依赖和失败原因 |
| Archon Learning curriculum 的公开 PR | 变更说明同时写学习者旅程、架构图、课程包、练习、毕业检查、维护、发布、验证证据、人审和回滚；读者能知道“改了什么、如何验证、哪里仍未验证” | 本仓库把“学习目标 → 页面/示例 → 自检 → 证据边界 → 下一步”写进首页、课程和 CI；以后新增课程也按这组字段补齐 | 这是公开 PR 描述中的课程设计记录，不等于我们已经验证 Archon 的全部页面、练习或运行结果；这里只借鉴组织方式 |
另外，Project Based Learning 的公开链接维护工作流把定时扫描、手动触发、并发控制、超时、状态汇总和人工判断边界单独写出来。这个做法适合提醒我们：外部参考链接是会腐烂的资源，应有独立维护任务；但不能把自动替换链接直接套到固定版本 DSH 源码链接上，否则可能悄悄改变教材证据基线。
新增课程时按这五个字段自查：内容、动作、检查、反馈、下一步；少一个，读者就会停在半路。
上面路径里的两步都有现成的交互入口：「真实宿主离线 A/B」的原理可以先在提示词装配实验里换参数看缓存账单，三层工具集合的收窄在工具可见性实验里逐层勾选。
把规律翻译成 DSH 的一条学习路径
text
首页三条入口
-> 第一课：先建立六个词的心智模型
-> 最小示例：只观察 tools/result，不改写结果
-> 学习工具箱：跑确定性检查并读懂边界
-> 逐文件索引：从文件卡片跳到固定提交源码
-> 高风险抽查：检查索引是否夸大
-> 真实宿主离线 A/B：观察 ToolRuntime / prompt assembly
-> 以后再做 provider A/B：输入 token、延迟、质量、成本每一层都有自己的完成条件：
| 层 | 初学者完成后应该能说什么 | 不能顺手声称什么 |
|---|---|---|
| 入口 | 我知道从哪一页开始，并能选择“第一次来／15 分钟／最小示例” | 我已经理解全部源码 |
| 静态课程 | 我能沿着文件、函数和测试的下一跳阅读 | 这些函数已经在我的 Profile 中运行 |
| 最小示例 | 我能写一个使用公开事件的观察 Bundle，并用 Node test/lint 检查它 | 真实 Loader 已安装它，或 provider 已收到它 |
| 快照 A/B | 我能比较注册、可见、schema 和执行字段的层次 | 工具少一定让模型更快或更聪明 |
| 真实宿主离线 A/B | 我能看到 ToolRuntime.debugSnapshot()、schemas() 和 SystemPrompt.assemble() 的本地差异 | 这就是 provider token、首 token 延迟或模型质量 |
| provider A/B | 在固定模型和任务下，我有交错运行、token、延迟、失败和质量记录 | 一次实验就能推出所有模型和 Profile 的普遍规律 |
教材也要教“循环变复杂”不等于“效果变好”
源码学习不能只教读者继续加组件，还要教读者在加之前停下来核对四件事：组件落在循环的哪一层、省下了什么成本、引入了什么新失败、以及拿哪条证据能证明收益确实存在。
| 组件或做法 | 主要改变循环的哪一层 | 第一批应该观察什么 |
|---|---|---|
| Skill 渐进加载 | 上下文与观测 | 当前任务实际加载了什么，遗漏后能否恢复 |
| Browser use / 截图 | 动作与观测 | 页面状态是否可读，点击失败和重试怎样处理 |
| 记忆 | 长程状态 | 写入、召回、过期、冲突和错误记忆怎样处理 |
| RAG | 证据输入 | Recall@k、最终证据覆盖、无答案拒答和成本 |
| 工具延迟加载 | 候选动作与上下文 | 找到工具、选对工具、首次调用延迟和漏选恢复 |
| 自动修改组件 | 控制策略与配置 | 版本、对照实验、holdout、护栏指标和回滚 |
这张表要阻止一种常见误读：看到系统从一个 loop 变成很多层，就把“更复杂”写成“更智能”。教材应该让读者把架构变化翻译成假设，再翻译成测量和证据。
一个真正易学的单页应该长什么样
以后新增课程或示例时，优先按下面模板写，不要从“概念定义”开始堆长段落：
markdown
# 这一步要完成什么
## 你会得到什么
- 最终文件、页面或命令输出：
- 预计用时：
- 前置条件：
## 第 1 步：点哪里 / 打开什么
1. 明确路径或按钮。
2. 给出 Windows PowerShell 和 macOS/Linux 命令（如果两者不同）。
3. 说明正常情况下会看到什么。
## 第 2 步：只读哪一段源码
- 文件：固定提交链接
- 先找的符号：
- 下一跳：
## 自检：看到什么才算通过
- [ ] 结构检查：
- [ ] 测试检查：
- [ ] 事实边界：
## 卡住时先看这三种情况
- 找不到文件：
- 命令失败：
- 页面和本地不一致：
## 这一步没有证明什么
- 未启动的服务：
- 未调用的 provider/model：
- 未验证的平台或版本：这里的“预期看到什么”很重要。只写“执行 pnpm test”会把新手留在黑箱里；写“应该看到 1 passed、0 failed；如果出现模块未找到，先确认是否完成 host build”才是可复核的教学。
这对现有仓库的具体改动方向
本仓库已经有这些部件：
- 根首页和
START-HERE.md的三条路线卡。 study-examples/minimal-observer-plugin/的最小观察示例。study-tools/quick-check.mjs的一个入口和--example、--deep、--runtime深度开关。verify-study-entry.mjs、verify-built-study-site.mjs、固定源码链接和逐文件索引检查。verify-study-learning-contract.mjs对首页、START-HERE、关键课程和最小示例 README 检查“现在做什么、应该看到什么、没有证明什么”等新手提示；它不判断读者是否真的理解。- 示例自己的 Node test/lint，以及 CI 的文档构建、链接、fragment 和静态质量门禁。
- 质量工作流在
doc-sync成功后上传 7 天保留的website/.dist工件，并把“本次证据不包含真实 DSH/provider/model”写入 Actions job summary；这让维护者能审阅实际网页，又不会把静态构建包装成运行时结论。 - 真实本地
ToolRuntimeA/B：它记录可见数量、schema 字节数和 prompt assembly 准备阶段，但明确显示不调用 provider/model。 - 首页的四步学习地图和长页面阅读进度条：把“先认识、再定位、留记录、想动手再验证”放在视觉上；进度条只保存在当前浏览器页面，不记录读者历史。
- 首页的门禁状态条把 120 页教材、2,973 张逐文件导读卡和 30 个离线实验压缩成一眼能读懂的事实。
verify-study-home-metrics.mjs会把首页的data-*数字与当前清单和测试约定对上，verify-built-study-site.mjs再确认它确实进入 Pages 产物；数字随基线刷新而变，以门禁输出为准。 verify-built-study-site.mjs对首页路线和进度资源设置发布契约；美化可以改 HTML 结构，但不能悄悄删掉新手入口。- 首页的「卡住时」恢复卡：找不到页面、命令报错和结论不确定分别回到哪一层；
verify-study-learning-contract.mjs与构建后检查都会保留这条入口。 - 状态条不是实时监控面板，也不是 DSH 健康检查；它是最近一次本地确定性门禁的摘要。数字改变时，先重跑门禁，再同步首页和对应的验证器。
还值得继续做的增强，按收益排序是：
- 给 15 分钟任务单加一组截图或短 GIF，让用户知道按钮和终端输出应该长什么样。
- 给 3～5 个高风险文件补“源码片段 → 下一跳 → 测试断言”的小练习，而不是只给索引卡。
- 用真实浏览器做首页、示例、课程页的移动端、深色模式和内部链接 smoke；静态 HTML 检查不能替代点击。
- 如果未来用户提供固定 provider、模型、预算和任务，再把 runtime A/B 接到交错的 provider A/B 记录器；没有这些条件时不要偷偷调用线上模型。
- 如果要启用 agent review，只把它作为带固定范围和人工复核的 PR 辅助意见；不要把模型输出接到自动合并、秘密读取或安全背书。
参考资料的使用边界
这些链接用于学习“教材产品怎么组织”，不是 DSH 的依赖、官方背书或兼容性声明。外部项目会继续变化；如果以后把它们写进正式维护规则，应在更新时重新检查页面内容和版本。DSH 自己的行为仍以学习仓库记录的固定上游源码、测试输出和实际实验结果为准。