16-代码案例索引与改造练习

核对日期：2026-05-18
官方资料：JS overview https://docs.langchain.com/oss/javascript/langchain/overview；Tools https://docs.langchain.com/oss/javascript/langchain/tools；Structured output https://docs.langchain.com/oss/javascript/langchain/structured-output。

目标

本章把 src/examples/ 和 src/projects/ 变成练习路径。每个练习都包含改哪里、为什么改、怎么验收，避免只“看懂”代码。

机制

学习闭环：

读章节 -> 跑 example -> 修改一个行为 -> 加测试/eval -> 复盘失败

只运行不修改，学到的是 API 名字；修改并写验收，学到的是工程边界。

TypeScript 案例索引

案例	文件	改造练习	验收
Chat model	src/examples/01-chat-model.ts	增加 token budget 估算	输出包含预算
Tools	src/examples/02-tools.ts	增加缺权限调用	ok=false
Agent dynamic tools	src/examples/03-agent-dynamic-tools.ts	按 role 暴露工具	employee 无高风险工具
Structured output	src/examples/04-structured-output.ts	增加非法枚举	parse 失败
Memory	src/examples/05-memory.ts	增加删除记忆	search 不再返回
RAG	src/examples/06-rag.ts	增加 chunkId	citation 可定位 chunk
Guardrails	src/examples/07-streaming-runtime-guardrails.ts	增加输出过滤	注入输入拒答

项目改造路径

企业知识库 Agent

1. 增加 chunkId。
2. 增加 refusalReason。
3. 增加 10 条 eval cases。
4. 把 keyword retrieval 抽象成 interface，后续可替换向量库。

个人学习助手

1. 增加 StudyEvent。
2. 增加薄弱点记忆。
3. 增加隐私过滤。
4. 增加“低时间预算”计划模式。

多工具任务 Agent

1. 增加 tool risk metadata。
2. 增加审批输入 hash。
3. 增加 permanent error 不重试测试。
4. 增加 audit log 导出。

Python 差异

如果用 Python 重写这些练习，保持三件事一致：输入/输出 JSON shape、一组 eval cases、失败语义。API 名称可以不同，验收标准不能漂。

常见反模式

反模式	后果
只复制代码不写测试	不知道改动是否有效
每个案例都接真实模型	学习成本高，失败难定位
不做负例	只能证明 happy path 能跑
改项目不更新 README	下一个人不知道如何运行

完成标准

• 每个 example 至少改过一次。
• 每个项目至少新增 2 条 eval。
• npm run typecheck 通过。
• npm test 通过。
• npm run projects:eval 通过。
• 能解释一次失败是怎么被 eval 捕获的。

练习任务

1. 从上表任选 3 个 example，完成改造并写测试。
2. 把企业知识库 Agent eval 从 4 条扩到 10 条。
3. 写一份失败复盘，使用 15-故障排查与反模式手册.md 的模板。