第 17 课：ResourceLoader 源码

从阶段二的上下文加载实践进入 Pi ResourceLoader 的资源发现、配置合并、extensions、skills、prompts、context files 和 diagnostics。

结论

ResourceLoader 是 Pi runtime 的资源发现层。它不直接跑模型，也不直接执行工具，而是把工作目录、用户级配置、项目级配置、临时输入、extensions 动态发现结果和 override 合并成一份可消费的资源快照。

入口问题

为什么上下文加载失败不应该静默发生？

心智模型

settings 决定默认资源来源和开关。
package manager 和 extensions 可以追加资源。
skills、prompts、context files 和 themes 被分别加载。
diagnostics 把缺失、冲突和解析失败交给上层处理。

源码推演（省略版）

下面不是完整源码，而是把本课主线压缩成可以在文档里直接阅读的关键形状。读者即使不打开本地源码，也应该能看出运行时如何组织职责。

async function reloadResources() {
  const settings = await loadSettings();
  const discovered = await discoverExtensionResources(settings);

  const resources = {
    skills: await loadSkills([...settings.skills, ...discovered.skills]),
    prompts: await loadPrompts([...settings.prompts, ...discovered.prompts]),
    context: await loadContextFiles(settings.contextRules),
  };

  return { resources, diagnostics: collectDiagnostics(resources) };
}

省略版源码把 ResourceLoader 的主线压缩成三步：加载配置、发现扩展资源、分别加载并收集 diagnostics。
diagnostics 是教学重点，因为资源缺失会直接改变模型行为。
企业内部 skills 搜索、prompt 模板市场和扩展资源发现，都可以放进这个模型。

课堂练习

设计一个资源加载诊断报告，覆盖目录不存在、frontmatter 错误、名称冲突和 extension 返回非法资源。

掌握标准

能说明 ResourceLoader 输出的不只是 prompt 字符串。
能解释 extension 为什么能参与资源发现。
能把上下文加载失败转成用户可理解的 diagnostics。

课后习题

实践题：基于本课的省略版源码，补出一个最小实现草图，要求写清输入、输出、副作用和错误处理。
思考题：本课机制如果只靠 prompt 约束，而不放进 harness 或 runtime，会出现什么工程风险？