后续研究路线：从学习材料走到运行证据
这篇把剩余工作按价值、前置条件和验收证据排好顺序。当前教材能解释设计、定位源码和运行离线文档检查；下面的项目会把静态结论换成更强的运行证据。
先看结论
最值得继续做的是把两层证据接起来：本学习工作树已经完成了一次不调用 provider/model 的真实 ToolRuntime provider-free A/B 观测；下一步才是让宿主或明确标注的 patched fork 导出稳定、脱敏的工具集合快照，再用同一套快照做真实模型 A/B 实验。普通插件作者不应为了完成这两件事而读取宿主私有 registry、模块缓存或进程状态。
当前状态要分开记：本地运行已经观察到“24 个工具注册不变、当前可见集合从 24 个变为 3 个、schema/wire 字节数和部分宿主准备阶段耗时发生变化”；真实 provider token、缓存 token、首 token 延迟、总延迟、回答质量和工具执行结果仍然没有测量。debugSnapshot() 是本学习工作树新增的调试观测接口，不是固定上游提交已经承诺的公共 API。
对初学者而言，最值得先做的是先读工具预算与插件责任决策卡，用一张卡把“工具预算”和“扩展责任”说清楚，再进入下面的运行研究路线。
Agent loop、Harness 与评估循环
先记住一个最小模型：
观察上下文与外部状态
-> 决定下一步
-> 调用模型或工具
-> 接收结果与副作用
-> 更新状态
-> 再次观察这个循环是 Agent 的基本执行抽象，但 Agent 不只有循环本身。模型、提示词、工具、记忆、权限、外部环境、错误恢复和评价标准共同决定循环能不能稳定地产生有用结果。
可以把几个容易混淆的词分开：
| 词 | 在循环里主要负责什么 | 一个简单例子 |
|---|---|---|
| Agent loop | 按顺序重复观察、决策、动作和更新 | 收到工具结果后决定继续还是结束 |
| Harness | 组织上下文、工具、状态、策略、重试和观测 | 决定哪些工具进入当前 agent 作用域 |
| Runtime / 环境 | 承担真实执行和副作用 | 文件、网络、子进程、浏览器或设备 |
| 评估循环 | 用固定任务和指标判断改动是否有收益 | 对照组、实验组、保留集和护栏指标 |
Skill 渐进加载主要改变上下文和观测面；Browser use 和截图扩大动作与观测面；记忆改变长程状态；RAG 改变检索到循环的证据输入；工具延迟加载改变候选动作集合；自动修改 prompt、工具配置、模型、Skill 或压缩策略，则改变控制策略和配置。它们都可能有价值，但“循环变复杂了”不等于“效果已经变好了”。
因此，“纯软 Agent 基本到头”不适合作为教材中的绝对结论。更准确的写法是：朴素的单循环方案已经遇到明显的边际收益和验证瓶颈。分层 Agent、Planner／Executor、事件驱动流程、状态机、多 Agent、专用模型和外部执行环境仍然有研究价值；它们通常可以理解为多个循环或状态机的组合。
“没有大量数据就几乎不能验证”也要改准。没有大规模用户数据时，仍然可以用固定任务集、离线 replay、确定性夹具和小型配对 A/B 验证机制是否工作、是否回归。缺少的是把结果推广到复杂且异质的真实用户群体的统计把握，而不是完全不能验证。
用户数据不能直接当成无偏实验。任务难度、用户熟练度、模型版本、Provider、工具集合、延迟、配置和成功样本选择都会混在一起。只看“某次改完成功了”无法知道收益来自哪一项变化。
如果要回答“某次改动造成了多少提升”，这已经是因果比较，不是普通日志统计。配对或交错 A/B 是最低起点；还要保存任务分层、版本、配置和失败样本。只有相关日志时，应写“观察到关联”，不要写“改动带来了提升”。
RAG 和工具延迟加载仍是开放的工程问题
本节的 RAG、Browser use、Skill 和“自进化”是通用 Agent 研究对象，不表示固定上游提交已经内置或验证了这些能力。是否存在于 DSH，要回到对应源码、测试和真实运行证据。
RAG 不能只问“有没有召回几段文字”。至少要分开记录检索召回、最终上下文和任务结果：
| 层次 | 可以测什么 | 常见误判 |
|---|---|---|
| 检索 | Recall@k、Precision@k、nDCG、证据覆盖 | 返回结果不为空就算有效 |
| 上下文 | 重排后证据顺序、重复、噪声、token 和截断 | 召回高就一定能回答 |
| 回答 | 正确性、引用证据、无答案时的拒答、多跳完成度 | 语言流畅就代表证据充分 |
| 系统 | 检索延迟、模型延迟、成本和失败恢复 | 离线指标好就代表线上体验好 |
工具列表也没有一个对所有任务都最优的固定答案。全量暴露、按 Profile、按任务、轻量目录加按需 schema、路由器筛选和失败后扩展搜索，都是可比较的设计。评价时至少同时看工具发现成功率、选择正确率、上下文 token、首个调用延迟、总延迟、任务成功率、恢复率和越权率。
“自进化”必须先变成可审计的实验
自动修改 prompt、工具配置、模型、Skill、记忆或压缩策略，首先是一种策略或配置搜索；它只有在目标、数据、版本和回滚都明确时，才值得称为“自进化”系统。自动产生改动不是自动证明改动有益。
最小的可信门槛是：
- 固定 Harness 版本、模型和 Provider；
- 固定分层任务，预先定义主指标和护栏指标；
- 保留不可见的 holdout 集；
- 交错或配对 A/B，记录环境；
- 人工批准推广，并能自动回滚。
否则，“这次 Agent 做得更好”可能只是模型换了、任务换了、用户更熟练了、工具数量变了、Provider 延迟变了，或者只记录了成功样本。教材应把这些混杂因素当作研究对象，而不是把“自进化”当作现成能力。
优先级与验收条件
展开优先级与验收条件（10 行）
| 优先级 | 研究项 | 为什么值得做 | 需要谁或什么 | 完成时必须留下的证据 |
|---|---|---|---|---|
| P0 | 宿主导出工具可见集合 | 没有真实的注册、可见和执行快照，就无法知道实验测的到底是哪一组工具 | 宿主维护者或明确标注的 patched fork | 版本、Profile、agent、四个观测时点、脱敏规则、失败处理和回滚说明 |
| P0 | 工具可见性 A/B 性能实验 | 验证“工具 schema 变多可能增加输入成本或选择负担”在指定模型和 provider 上的实际幅度 | API、固定模型、隔离 Profile 和可重复任务 | 成对实验、provider token、缓存字段、首 token/总延迟、工具错误、盲评质量和成本；没有字段就写未提供 |
| P1 | 分批人工抽查高风险索引 | 缩短自动卡片与实际源码之间的距离，同时不假装 2,973 个文件都逐行读过 | 能阅读固定 commit 的维护者 | 每批文件的源码事实、测试事实、修正记录和仍未验证项；模板复用只作提示，不作错误 |
| P1 | 社区插件、Hook bridge 和注入器复核 | 生态名称相似，公开 Bundle、兼容层、fork 和运行时注入的风险不同 | 固定 commit、隔离 Profile、可回滚环境 | 项目自述、manifest、安装脚本、权限、网络、子进程、版本绑定、安装/卸载日志和身份声明 |
| P1 | 最小示例插件工作台 | 让读者从“看懂公开扩展点”走到“注册一个工具并正确卸载” | 一个不需要真实模型的最小 Bundle 示例 | 目录、manifest、公开 API、schema、测试、卸载结果和清理说明 |
| P1 | 教材质量 CI 与审阅记录 | 防止链接、双语记录、示例行为和 Pages 构建悄悄回归，同时不把自动化或 Agent 意见夸大成运行证明 | GitHub Actions、维护者审阅和明确的证据分层 | 示例 test/lint、A/B 结构预检、文档门禁、Pages 构建、PR 证据表和人工判断；真实 DSH、模型和安全结论仍需各自证据 |
| P2 | Pages 移动端与长索引体验 | 内容已经能在网页发布，但窄屏、超长索引和搜索仍值得真实浏览器抽查 | 浏览器截图和固定 viewport | 首页、学习入口、长索引、表格和深色模式在窄屏无横向溢出，关键链接可点击 |
| P2 | GitHub 仓库治理 | 降低误删或强制推送风险，但不是 Pages 上线的前置条件 | 仓库管理员权限 | 当前 master 已禁止 force push、禁止删除；暂未强制 PR 或 Actions 检查，以保持 Pages 的 push 发布路径；以后可按协作规模再评估 |
| P2 | 依赖告警分类 | GitHub 页面显示的依赖告警需要按生产依赖、开发依赖、可达路径和修复兼容性分类 | 锁文件、审计命令和发布判断 | 原始告警、受影响包、可利用路径、升级范围、测试结果和未修复理由；不能直接批量 audit fix |
| P2 | Actions 运行时维护 | Node.js 20 弃用提示属于 CI 维护问题，不等于 DSH 运行时失败 | 工作流权限和 Actions 版本 | 具体 action、Node 运行时、升级后的构建结果和告警变化；不以改版本号代替验证 |
上面的看板把这张表变成可筛选的：按优先级过滤，点选研究项查看为什么值得做、需要谁或什么、完成时必须留下的证据；三栏文字逐字来自表格。
P0：怎样做可信的 A/B 实验
先固定实验对象：
- 同一模型、同一 provider；
- 同一用户 prompt 和历史上下文；
- 同一工具名称/描述/schema 与顺序；
- 同一 temperature；
- 同一平台和时间窗口。
只改变可见集合。A 组可以是“20 个注册、20 个可见”，B 组可以是“20 个注册、3 个可见”；不要让 B 组顺便改变工具实现、权限、系统提示词或网络环境。
每组先预热，再运行多次成对样本。记录 provider 返回的 input tokens、cached tokens、首 token 延迟、总延迟、工具调用错误、任务质量和成本；字符数除以 4 只能作为粗略提示，不能代替 tokenizer。
质量要用固定任务和盲评表，不要用一次回答下结论。若没有真实模型、provider 字段或可重复环境，结果表中的对应字段应写“未测”，不能填一个看起来完整的估算值。
实验结束后只得出带范围的结论，例如“在模型 X、provider Y、日期 Z、这个任务集合中，B 组的输入 token 中位数较低”；不要推广成“所有模型都更快”或“工具越多一定让模型变差”。
P0：宿主观测接口应该长什么样
观测接口至少要能回答四个不同问题：运行时注册了什么、作用域限制后还剩什么、实际请求组装了什么、执行策略为什么允许或拒绝。
每条记录只保留完成研究所需的最小字段，例如工具名、来源、版本、presentAs、schema 摘要、顺序、策略决定和时间戳；不要记录完整 prompt、用户内容、参数值、凭据、绝对路径或文件正文。
宿主要明确观测接口是调试能力，不是权限授予；它也不改变第 22 课划出的隔离边界。需要访问私有内部状态时，维护者要负责版本锁定、权限说明、回滚步骤和与普通插件 API 的区分。
P1：社区项目审核顺序
先看项目身份和固定 commit，再看 package.json、Bundle manifest、安装脚本和依赖；随后搜索模块缓存、Loader、registry、进程注入、Windows junction/注册表、网络和子进程行为。
再把“项目自称支持”按决策卡的证据分级拆层核对：从 README 声明到卸载回滚，每一层能证明的东西不同；审核记录要写清这次拿到了哪一层、还缺哪一层。
像 dsh-super-injector 这样的项目可以同时包含合法的 Bundle 外壳和高风险的运行时注入实现；不能因为它有 apply(ctx) 或 manifest，就把整套方案归类成只使用公开 API 的普通插件。
本轮公开 GitHub 观察（2026-08-16）
本轮先完成了静态公开证据的分层核对，再把未完成的运行工作保留为后续项目。查询结果、仓库页面、固定 commit 和 README 自述都带有来源；它们不构成官方背书、安全结论或生产兼容性结论。
| 观察对象 | 已有证据 | 证据等级 | 仍未验证 |
|---|---|---|---|
| 上游 Hook bridge | 固定提交 aa6c361a972c8369148dea7380bb5c21c24e07ec 的 hook-protocol README 写明 library 不注册、不注入；Claude/Codex bridge README、源码和测试分别列出 7/5 个事件子集。见协议 README、Claude bridge README、Codex bridge README。 | 固定上游源码/测试 | 未运行本轮 DSH、外部 shell hook 或模型验证；未来协议字段和支持子集仍需重查。 |
| 普通插件 | dsh-annotation、dsh-navbar 的固定 README/package 自称 Bundle/client 形态；dsh-agent-teams 自称提供团队工具和 Web UI；dsh-tui 自称 out-of-tree bundle，并明确写有 pre-release 兼容和测试尚未运行。见批注 README、导航条 README、AgentTeams README和TUI README。 | 固定社区 README/manifest | 未在隔离 Profile 中逐一安装、启动、执行、卸载，也未证明权限、版本矩阵或跨平台行为。 |
| patched fork | rpmalouin/deepseek-harness 的 GitHub 页面显示 forked from 上游，README 自称增加三类 workflow 集成；这足以记录“GitHub fork + 项目自述”，不足以代替差异审查。见rpm fork。 | GitHub 元数据 + 项目自述 | 未完成逐文件 diff、构建、运行、同步上游和发布产物核验。 |
| 注入/注册表修改 | dsh-super-injector 固定源码出现 junction、loader.create()、loadCache、Fiber/registry 和宿主内部表操作；其 patch 文件只装入引导器。见注入器源码。 | 固定社区源码 | 未证明官方 API 身份、卸载后完全 quiescent、无残留、无权限扩大或跨版本稳定。 |
| GitHub topic 数量 | q=topic:dsh-plugin&per_page=30 在 2026-08-16 返回 total_count=5142。见查询 URL。 | 搜索索引观测 | 数量随时间、索引和查询参数变化；不能用作验证项目数量、兼容项目数量或安全项目数量。 |
本轮的结论是“分类证据已补齐，运行证据没有补齐”。下一轮应沿着普通插件、bridge、fork、注入器四条路线分别建立安装/运行/卸载记录，不能用其中一条路线的绿色结果替代另外三条。
P1：索引怎样从自动定位走向人工理解
每批只选少量高风险文件，例如工具入口、system prompt、Profile 启动、Loader、Hook codec 和权限策略；先读自动卡片，再读固定源码、同目录 README 和测试，最后填写“源码事实／测试事实／仍未验证”。
44 条设计理由模板复用统计适合用来挑选人工抽查对象，不需要为了把数字变成零而批量改写相同句子。真正需要修正的是与源码冲突、测试关联错误、链接错误或把静态证据写成运行结论的条目。
现在可以做、以后再做、不要偷偷做
| 类别 | 现在的合理动作 |
|---|---|
| 现在可以做 | 在 Pages 阅读、使用离线快照检查器、按固定 commit 抽查源码、写不访问私有状态的示例插件、提交文档问题和链接问题 |
| 需要额外条件 | 真实模型 A/B、宿主内部快照、完整 DSH build、第三方插件安装/卸载、跨平台和移动端浏览器回归 |
| 不应偷偷做 | 让普通插件读取私有 registry、改模块缓存或 Windows 注册表；把 patch/fork/注入器冒称官方插件；把 Actions 绿色、文档构建成功或 44 条统计写成 DSH 运行通过 |
推荐的下一轮顺序
- 先为宿主或 patched fork 定义脱敏快照格式和四个观测时点。
- 先用决策卡审核一个社区项目或自己设计的插件，写出身份、权限、卸载和未验证项。
- 再用固定工具集合和固定任务运行 A/B，保存原始结果与环境信息。
- 选择高风险索引批次和社区项目，逐个补源码事实、测试事实和未验证边界。
- 提供一个最小公开 API 插件工作台，让读者可以验证注册、工具调用和卸载，而不依赖真实模型。
- 最后做真正生效的移动端网页抽查、依赖告警分类和 Actions Node 运行时维护；
master的最小分支保护已经属于当前仓库治理基线。
当前教材的诚实结论
从首页进入 Pages，读完整套中文导读、逐文件索引和固定源码链接是可行的；网页阅读已经覆盖“学习”和“定位”这两个目标。
网页不能替代真实 DSH 运行。当前材料足够作为固定版本的源码学习和插件生态研究教材，但还不能单独证明完整 build、真实模型性能、第三方插件生产可用性或所有文件已经人工逐行精读。