切换深色模式
开课指南：把 Agent 知识变成可验证的作品
这门课程要解决一个具体问题：你能让模型调用工具，但还不能解释它为什么失败，也不能证明换一次提示词以后系统更可靠。学完后，你应能设计研究助手的执行循环，复现权限和证据错误，用评测报告解释一次修改是否值得保留。
课程以 JavaScript / Node.js 提供最小参考实现。Java、Python 后端开发者也可以跟学；先读懂对象、函数、异常与测试，再用熟悉的语言重写。课程不要求训练模型，也不把框架 API 的记忆量当作能力。
适合谁，先补什么
| 你的起点 | 建议入口 | 第一份交付 |
|---|---|---|
| 能写 CRUD，没做过大模型应用 | 按 01 → 07 学习 | 搜索、读取、完成的执行轨迹 |
| 做过聊天或 RAG 演示 | 先做入学诊断，再读 05、06 | 一个“有引用但错误”的反例 |
| 已有 Agent 原型，缺少稳定性 | 05、07 后回查 02、04 | 失败归因表与回归门槛 |
| 尚不能独立运行脚本或读 JSON | 先完成下方环境练习 | 能修改查询并解释返回结果 |
学习前应能解释 async/await、数组与对象、HTTP 请求、环境变量和自动化断言。不熟悉的概念可以边做边补；如果一段 30 行脚本也无法逐行解释，应先练习语言基础。
入学诊断：先答，再展开
- 模型返回
read_note，说明笔记已经被读取了吗？ - 搜索结果为空，属于工具故障吗？
- 用户能读取一份文档，是否意味着可以把它发给任何人？
- 答案附有合法引用，能否直接判正确？
- 同一问题跑五次，选最好的一次，是否能代表日常稳定性？
参考答案与补课建议
- 不能。只是动作请求，执行器还要校验并执行。错此题先读 01、02。
- 不一定。成功检索也可能没有匹配；需要区分业务空结果与执行异常。读 02、06。
- 不能。读取授权和外发授权不同。读 07。
- 不能。引用存在与支持结论不同。读 03、05。
- 不能。这遗漏了另外四次的失败及消耗。读 05。
答对 4–5 题可从实验开始，2–3 题建议完整阅读，0–1 题先完成基础两章。这是学习分流建议，不是能力认证。
学习安排与阶段作品
建议投入 24–32 小时完成正文、实验和结课设计；这是排课估计，不是实测学时。真实模型接入和自主扩展另外安排时间。每次学习可以按“阅读 25 分钟 → 推演 15 分钟 → 实验 40 分钟 → 复盘 10 分钟”组织，实验未通过时先定位原因。
| 单元 | 预计投入 | 学习后能完成的动作 | 必须提交的作品 |
|---|---|---|---|
| 00 环境与诊断 | 1 小时 | 运行示例、定位入口 | 环境版本与首次运行记录 |
| 01 运行循环 | 2–3 小时 | 区分动作请求、观察和终态 | L1 三条轨迹 |
| 02 工具契约 | 3 小时 | 拒绝非法参数和越权读取 | L2 工具契约与反例 |
| 03 上下文与证据 | 3 小时 | 保留条件、版本和缺口 | L3 证据卡与召回计算 |
| 04 编排与协作 | 2–3 小时 | 拒绝旧任务结果，保留部分失败 | L4 合并规则与状态表 |
| 05 评估与可靠性 | 3–4 小时 | 按任务统计修复、回归和未知项 | L5 评测报告 |
| 06 实践 | 3–4 小时 | 替换决策策略并保留控制边界 | L6 新问题策略和失败复现 |
| 07 安全边界 | 2–3 小时 | 判断具体审批是否仍然有效 | L7 威胁模型与拒绝轨迹 |
| 结课项目 | 5–8 小时 | 演示、答辩并说明工程局限 | 项目、证据报告与改进决策 |
这些环节训练的是一条完整工程链：需求契约 → 执行边界 → 证据 → 编排 → 评估 → 演示。不能用“读过所有章节”代替项目验收。
环境练习：十分钟获得第一条轨迹
本站示例在 Node.js v24.19.0 上核验。先在项目根目录打开终端：
powershell
node --version
node docs/public/examples/research-agent.mjs
node --test docs/public/examples/research-agent.test.mjs
node docs/public/examples/course-labs.mjs
node --test docs/public/examples/course-labs.test.mjs离线示例只用 Node.js 内置模块，不需要先安装文档站点依赖，不需要 API 密钥。只有启动网站才需要 pnpm install 和 pnpm run docs:dev。
第一条命令记录实际版本；第二条应输出 completed，轨迹中有搜索与读取；测试应全部通过；实验报告会刻意展示语义错误被旧执行器接受的情况。实验能运行和被评对象正确，是两种不同结论。
若找不到文件，先确认终端所在目录；若不识别 node，安装并配置 Node.js 后重新打开终端；若测试报错，保留完整错误、版本和改动，参照实验排障定位。不要先通过删除失败断言“修复”测试。
每节课的学习方法
基础阶段完成后，进阶安排另计 9–12 小时：08 真实模型与异步执行、09 真实 Markdown 检索、10 项目交付与运行复盘，每课约 3–4 小时。下载项目包含真实文章快照，默认离线运行；在线实验需自行配置账户且会产生用量。
先写预测再运行，例如“私有 ID 应被拒绝且不进入 evidence”。运行后对比预测和实际，记录第一处不同。最后改一个条件再运行，如更换所有者或文档版本，观察变化是否符合解释。
每个实验交四样东西：输入条件、实际输出、关键代码位置、结论及不能证明的事情。代码可以简短，证据不能省略。参考答案折叠在实验后面，建议完成一次独立尝试后再展开。
结课阶段另有 完整参考解答：12 类任务都有可重放行为与判定理由，包含故意错误的容量结论。先交自己的答案，再对照来源与适用条件，避免把记住参考答案当作独立完成。
本课程交付边界
当前可下载运行的是基础执行器、课程实验及进阶研究项目。进阶项目包含真实文档检索、异步预算与可选 Claude 适配器；默认回放没有模型智能，适配器只完成模拟请求测试。编排实验是合并规则，不是多 Agent 调度服务；审批实验只验证候选参数，不实现认证和发送。
工程进阶的目标包含真实模型适配、真实文档检索、成本与超时观测。是否已经完成，以具体实战页、源码和运行报告为准。没有提供相应证据时，不将“会设计”写成“已部署”，也不把本文当作视频录播、商业售后或就业承诺。