SelfLearn · 技术手记

切换深色模式

10 · 交付参考项目：让别人能运行，也能看懂失败 ​

前置：08、09。本课预计 3–4 小时。交付：可独立解压运行的项目包、真实文章回放、检索报告和结课覆盖表。

这份参考项目演示了从真实文件到候选回答的闭环。它不是上线服务：没有真实认证、写操作、持久化任务或自动语义评分。cli.mjs 默认回放读取第一个结果；新增的 结课参考解答提供三来源比较、冲突与缺证的完整预编排案例。独立毕业作品还要实现自己的策略与评估。

1. 项目结构与阅读顺序 ​

下载 完整项目包，解压后会看到 START-HERE.txt 与 docs。只需 Node.js，无需安装 npm 包；所有文件保留与课程仓库一致的相对路径。

text
docs/
  notes/delayed-tasks.md            真实课程笔记
  java/jvm/heap.md                  第二个检索主题
  public/examples/research-project/
    cli.mjs                        配置、回放与可选在线入口
    knowledge.mjs                  解析、检索、授权与版本
    runtime.mjs                    异步控制循环
    claude.mjs                     Messages API 适配器
    retrieval-eval.mjs              真实文章召回评测
    project.test.mjs                隔离临时数据的测试
    capstone-eval.mjs               十二类完整参考案例回放
    capstone-reviews.json           与输出摘要绑定的参考判定
    capstone.test.mjs               案例与评审版本测试
    fixtures/                      七份原创合成资料

先看 cli.mjs 中的回放器，再看 runtime 的单轮分支，然后看 knowledge 的读取；最后读适配器。这样能先理解“期待返回什么”，再核对“如何限制它”。

2. 三个命令形成最小交付证据 ​

在解压后的根目录运行：

powershell
node docs/public/examples/research-project/cli.mjs "延时任务 故障 恢复"
node docs/public/examples/research-project/retrieval-eval.mjs
node --test docs/public/examples/research-project/project.test.mjs

第一次输出实际片段、版本和轨迹；第二次输出开发查询集指标；第三次验证执行与适配契约。它们回答不同问题，不合并成一个“准确率”。

额外运行 node docs/public/examples/research-project/cli.mjs "JVM 回收"，检查来源属于 JVM 笔记。再换成一个不存在的英文词，观察资料不足路径。若查询含“任务”等常见词而仍有结果，这可能是词项基线过宽，不是工具报错。

3. 正常轨迹应怎样讲解 ​

阶段本项目保存的证据可以说明的事实
启动snapshot、promptVersion、question这次任务所用数据与提示词标识
模型或回放请求modelCalls、durationMs、usage做过几次决策，请求是否得到结果
搜索查询参数、候选、截断标记返回哪些候选，不代表已读正文
读取ID、revision、原文和行号读取过该快照的资料
提交claims 与 citations引用形状有效，待语义复核
停止status、reason、总时长为什么没有继续调度

默认回放有三条动作记录，第三条是 submit_answer。旧基础示例把 final 放在工具之外，所以只有两条工具记录。指标比较前先统一口径，不能说“新系统多调用一次检索”。

4. 与结课任务逐项对照 ​

任务参考项目提供的证据学员还要补什么
C01 正常问题真实文件搜索读取，引用结构测试对综合回答作语义与任务满足检查
C02 第二主题JVM 回放与测试自己加入的新主题及问法
C03 无资料空查询结果结束测试检查合理同义表达是否被误拒绝
C04 缺容量原文章缺容量数据在线模型或自实现策略的真实输出与人工判定
C05 私有资源猜 ID 拒绝，私有正文不外泄测试真实登录集成若作为作品承诺
C06 版本改变文件修改后旧引用拒绝测试刷新索引的产品策略
C07 文档注入未允许的工具拒绝将注入放进文档后的模型路径评测
C08 循环预算轮数、重复 ID、期限和取消测试更丰富的无信息增量检测
C09 无关结论未读引用拒绝，候选答案待复核合法引用但无关内容的人工拒绝记录
C10 新问法不预填保留题结果由验收人出题、实跑并保留轨迹
C11 条件冲突引用可以映射多个已读片段冲突资料、比较策略与语义标签
C12 缺用户条件request_input 的结构与暂停测试模型是否在恰当时机澄清

表中的“还要补”是结课作品的工作量，不是自动化测试已经替你完成的部分。基础参考项目与完整业务研究能力的差异应在演示开头说明。

需要参考写法时，运行 node docs/public/examples/research-project/capstone-eval.mjs，阅读 完整解答。其中 C04、C09、C11、C12 提供具体的缺证、错误、条件冲突和澄清文本；这些公开题不能再充当自己的保留集。

5. 运行故障复盘：一次超时的责任归属 ​

假设工具迟迟不返回。先看 modelCalls 是否已收到模型结果，再查 trace：若读操作因 deadline 停止，说明候选动作已产生，但正文没有及时成为证据。不能给答案补上一个“应该读到”的片段。

复盘至少写明：起始预算、故障位置、已执行动作、未确认结果、终态、是否允许重试。对本课只读文件，重跑可能看到新版本；新运行应记录新快照。若未来改为外部发布，必须先查询外部操作状态，不能照搬读取重跑策略。

6. 为什么当前不提供崩溃恢复按钮 ​

任务状态只在内存，进程退出就丢失。本项目保存的终态 JSON 是交付报告，不是可直接恢复的检查点。没有完整消息、调用意图、审批版本和去重规则时，给它加一个 resume 参数会造成错误安全感。

扩展恢复时先定义以下故障点，再实现存储：模型已返回但工具未开始；工具已开始但结果未记录；结果已记录但下一轮未开始；最终产物已保存但终态未保存。每个故障点都需要不同的恢复依据。

在只读版本中可先保存“已读来源版本 + 未完成目标”，恢复时重新校验来源后从新的决策轮继续。未来写操作需要独立业务幂等与结果查询。该扩展在课程中作为设计任务，当前源码不声称具备恢复能力。

7. 对照实验报告应该包含什么 ​

用实验模板记录两个版本的唯一变化。至少报告各任务修复与回归、所有尝试的总消耗、未知 usage 数量、人工复核分歧，以及资料快照是否相同。

如果只把 deadline 从 60 秒改为 120 秒后成功次数增加，不能直接说“推理能力增强”。可能只是允许了更长执行和更多成本；需要结合任务价值判断。若某题因资料不存在而失败，增加时间通常不能补出证据。

8. 最后一次交付自检 ​

把完整包解压到一个新目录，不共享旧输出，重新运行三条命令。检查源码下载、资料路径、环境说明和错误提示。让同伴用新问题测试，并在第一次失败时解释数据、策略还是执行边界出了问题。

合格交付应让读者知道：哪些命令确实执行过，哪些是模拟，哪些需要自己的模型账户，哪些能力尚未实现。下一步回到结课评分，用自己的作品补齐覆盖表中的剩余证据。