📑 本页目录（点开跳转）
智能体工程教程 · 按需阅读
把知识助手做成一组能核对的交付物。
先跑通基线，再按阶段保留真实结果。勾选表示你已自查，不代表网站替你跑过测试。
这一次要留下什么
一份可复现的项目，加上解析、检索、权限、审批恢复和运维证据；没有实跑的部分继续标为待验收。
17b · 一个能拿去解释故障与取舍的知识助手
⏱ 按交付物推进 ｜ 应用工程、RAG 与 Agent 岗位的共同实践
🎯 一句话
把数据、检索、工具、审批和评测放进同一个项目，面试时才能沿一条真实请求解释全流程。 这里提供可运行基线与分阶段任务；完成基线之后，用自己的脱敏资料与保留集形成个人证据。
🔗 下载项目压缩包 ｜ 项目说明与代码入口 ｜ 岗位分支 ｜ 故障速查
这不是一个已经接好所有生产服务的成品。当前基线使用 SQLite、虚构设备与制度文档、可选真实 embedding/重排、真实 MCP 本地传输和 LangGraph 持久化；外部工单、身份签发与人工操作使用明确的本地夹具。
真实生成模型、复杂 OCR、外部 OAuth 登录、云端发布与生产压测需单独验收。
先运行，再选择自己的岗位路线
安装条件、命令与真实服务边界都保留在此。
🔬 先运行，再挑路线
有仓库时，以下命令在仓库根目录运行；只有压缩包时，解压后进入 knowledge-assistant 文件夹，按包内 README 的短路径命令运行。使用 Python 3.12。
python examples/knowledge-assistant/lab.py demo
python -m unittest discover -s examples/knowledge-assistant -p test_core.py -v
这两条仅用 Python 标准库；先观察文档入库、检索与引用、待审批工单、模拟响应丢失和恢复结果。本地 demo 由测试操作者自动批准示例动作，不能把这条命令当生产的人审流程。
需要 MCP、框架与向量模型时，创建隔离环境。Windows PowerShell 可以直接使用虚拟环境解释器，不必修改脚本执行策略：
python -m venv .venv-knowledge
.venv-knowledge/Scripts/python.exe -m pip install -r examples/knowledge-assistant/requirements.txt
.venv-knowledge/Scripts/python.exe -m unittest discover -s examples/knowledge-assistant -p test_protocol.py -v
后文的 python 均表示这个已装依赖的解释器。Linux/macOS 对应 .venv-knowledge/bin/python。首次神经检索会下载公开模型权重；纯标准库与协议测试不需要模型权重或 API Key。
| 你的目标 | 第一站 | 这一轮留下什么 |
|---|---|---|
| 企业知识库 / RAG | 11b · 入库 | 解析夹具、版本/ACL 测试、逐题检索报告 |
| 工具接入 / MCP | 08c · 鉴权与互操作 | 协议矩阵、拒绝用例、目标宿主联调记录 |
| Agent / 工作流 | 12b · 故障恢复 | 副作用幂等证据、跨进程恢复录像/日志 |
| 模型 / 推理 / 领域专项 | 17c · 岗位专项 | 与具体 JD 对应的训练、容量或专项实验 |
阶段一 · 数据事实
本阶段可停：能把任意 chunk 追溯到当前版本。下次从检索基线继续。
阶段一：把数据事实固定下来
目标是能解释每个答案来源，以及变更后何时生效。先用内置虚构语料跑通，再换成有使用权限的脱敏资料。项目中的题集公开可见，不能当作自己的独立保留集成绩。
- 核对 manifest 的文档身份、版本、readers 与租户；写出为什么身份字段不能由模型填写。
- 检查表头、单位、型号与章节是否保留在块中，保存至少一个解析失败样本。
- 运行重复导入、旧事件迟到、删除墓碑、撤权与提交失败测试，解释每项的最终状态。
- 为自己的文档建立按来源或时间隔离的开发集与保留集，包含无答案和权限负例。
阶段验收：任意 chunk 都能回到当前源版本；未经授权的块不能进入候选；失败发布不破坏旧版。具体操作见 11b。
阶段二 · 可比较的检索结果
本阶段可停：配置与逐题结果能复跑。下次从工具授权继续。
阶段二：让调优留下可比较的结果
- 导出 BM25 基线报告，能区分 Hit、Recall、MRR 与 NDCG。
- 比较同题集上的中文向量、RRF 与重排，列出至少三条改善或退化的具体问题。
- 只改变候选 K、切块长度或上下文预算中的一个，保存配置与差异；再验最终组合。
- 分开报告检索效果、引用有效性、答案支持度与无答案拒答，不用一个总分代替。
阶段验收：保留语料/代码/模型哈希、题目级结果、硬件与用量条件，能复跑同一配置。不要把 16 道有答案开发题的指标包装成生产准确率。方法见 11c 与 11d。
阶段三 · 工具连通与正确拒绝
本阶段可停：成功和拒绝都有证据。下次从审批与恢复继续。
阶段三：工具能连通，也能正确拒绝
- 跑通 HTTP/stdio 与新旧协议组合，查看真实
structuredContent。 - 验证缺 token、过期、撤销、audience 错误、scope 不足、跨租户查询与未知工具。
- 在实际目标宿主完成一次工具发现、调用和错误展示；记录宿主与 SDK 版本。
- 把真实身份平台接入列成单独验收项：登录、授权同意、回调、刷新、撤权与资源范围。
阶段验收：工具描述、输入 schema、输出 schema、错误与权限边界对得上；本地 token 夹具不能被称作完整 OAuth 上线。步骤见 08c。
阶段四 · 恢复不重复执行
本阶段可停：响应丢失后业务对象仍只有一个。下次从部署条件继续。
阶段四：恢复过程不制造第二次动作
- 用故障注入证明未审批、改参数、审批过期、取消都阻止新执行。
- 演示下游成功但响应丢失，恢复后业务对象总数仍为一。
- 使用两个独立进程演示 LangGraph 暂停与恢复，解释 checkpoint 和业务库的不同作用。
- 接真实下游前确认幂等键保存期限、结果查询一致性与取消语义，补响应未知时的人工处理入口。
阶段五 · 目标环境验收
本地测试不能代替真实负载、备份恢复与受控发布。
阶段五：按交付环境完成运维
- 在干净环境安装依赖并跑测试，记录 Python/SDK/模型版本和下载条件。
- 定义质量、错误率、p95/p99、首 token、成本与新鲜度目标，按真实业务预期设置阈值。
- 测单并发与目标并发、冷启动与热请求、限流、超时和断流；报告负载形状与样本数。
- 演练备份恢复、索引切换与回滚，并在恢复后复测删除和撤权。
本地 SQLite 不是横向扩容方案；复制数据库文件也不是 WAL 模式下完整的备份流程。
生产使用数据库提供的备份/快照机制，保存 schema 与索引版本，恢复到隔离环境验证业务状态与权限。
上线前接密钥管理、日志脱敏、错误告警和受控发布；这些验收结果需要真实环境证据。
整理交付包，明确做过与没做过
先核对证据，再填写简历；不要把教程样例成绩当作个人成果。
六、最终交付包与面试讲法
| 交付物 | 面试官能核对什么 |
|---|---|
| 一页架构与可信边界 | 身份、数据、模型、工具与业务状态在哪里 |
| 可运行代码、版本、启动命令 | 是否能从干净环境复现 |
| 原始评测与失败样本 | 数字是否有口径，退化是否被隐瞒 |
| 故障注入与恢复记录 | 超时、重复、撤权后系统真实行为 |
| 发布/回滚与监控说明 | 出问题时如何定位、止损、恢复 |
| 已知限制与岗位扩展 | 哪些做过，哪些只是方案 |
简历句子用自己的真实结果填写：“在某规模、某题型与某硬件下，对比 A/B 配置；指标从 X 到 Y，p95 从 U 到 V；通过版本乱序、权限变化和响应丢失测试。”不要把本教程内置成绩写成自己的线上业务成果。
🛑 现在可以停：每个阶段至少拿到一份可核对的交付物，再按岗位补专项。没有任何有限教程能穷尽线上所有事故，但你已经有新增故障时定位与回归的方法。
✅ 检查点
- 哪些数字可以写成“实测”，哪些只能写“待验收”？
- 只有成功演示视频，还缺哪类求职证据？
展开答案
- 有实际输入、配置、运行记录与口径的结果可写实测；真实模型、目标宿主、云环境等未跑过的部分应保留待验收状态。
- 负例、逐题评测、版本与权限变化、故障恢复、容量边界及复现方法。
同一项目串起五个阶段；阶段任务有从属关系；交付真实结果与失败证据；岗位差异再走专项。
🔗 接下来去哪
➡️ 下一站：17c · 岗位专项与进阶实验。