官方文档引导：从规范读到可运行系统

检索日期：2026-07-27
使用方式：先读每章标记为 P0 的卡片，再按实验需要读 P1。P2 是毕业后的扩展。不要只“浏览过”，每张卡片都规定了可检查的完成证据。
来源原则：本页只收录规范维护方、项目维护方或标准组织发布的一手资料。版本敏感的结论以链接页面当前内容为准。

一眼选择

主题	首读来源	对应课程	优先级	预计时长
Skill 格式与渐进加载	Agent Skills Specification	第 2、5、7 章	P0	35 分钟
Tool、Resource、Prompt 的边界	MCP Server Overview	第 4 章	P0	25 分钟
本地和远程 MCP	MCP Architecture + Build Server	第 4 章	P0	60 分钟
MCP 鉴权与安全	Authorization + Security Best Practices	第 4、7 章	P0	75 分钟
MCP 对外登记	MCP Registry Remote Servers	第 4、7 章	P1	30 分钟
MR 触发与门禁	GitLab MR Pipelines + Rules	第 6 章	P0	50 分钟
MR 报告回写	GitLab Notes / Discussions API	第 6 章	P1	35 分钟
Web 运行状态	FastAPI Streaming + WHATWG SSE	第 1、7 章	P0	45 分钟
模型与工具调用	DeepSeek Chat Completion	第 1、4 章	P0	40 分钟
混合检索	PostgreSQL FTS + pgvector	第 3 章	P0	70 分钟
Agent 安全	OWASP LLM Top 10 + NIST Agent Hijacking	第 2、7 章	P0	60 分钟

1. Agent Skills 官方规范

• 稳定 URL：Agent Skills Specification
• 为什么读：课程里的 SKILL.md、scripts/、references/、assets/ 和跨 Harness 安装都以它为契约。它能防止我们把 Mini Emperor 的 Web 扩展误当成通用标准。
• 重点读哪里：
  1. Directory structure 与 SKILL.md frontmatter；
  2. name、description、compatibility、allowed-tools 的约束；
  3. Progressive disclosure、文件引用与验证；
  4. skills-ref validate 的用法。
• 带着什么问题：
  1. 为什么 description 同时要写“能做什么”和“何时使用”？
  2. 什么信息必须留在 SKILL.md，什么信息应该延迟到 references/？
  3. allowed-tools 为什么不能代替运行平台的权限策略？
• 完成证据：写出一个最小 Skill，能通过规范校验；再把一段超过 500 行的说明拆进 references/，说明拆分依据。
• 优先级：P0
• 预计时长：35 分钟
• 检索日期：2026-07-27

读完立即核对

通用 Skill 的最低结构是一个目录和其中的 SKILL.md。skill.web.json 是 Mini Emperor 的可选 Web 执行扩展，不属于 Agent Skills 标准；缺少它的 Skill 仍应能下载并安装。

2. MCP 架构与三种服务端原语

• 稳定 URL：
  • MCP Architecture Overview
  • MCP Server Overview（2025-06-18 规范）
• 为什么读：MCP 不是“另一种 Tool 函数”，而是让 Host、Client、Server 通过统一协议发现和调用能力。三种原语的控制方不同，直接影响产品交互和安全审批。
• 重点读哪里：
  1. Host、Client、Server 的边界；
  2. data layer 与 transport layer；
  3. Prompts、Resources、Tools 的控制层级；
  4. 生命周期、能力协商和通知。
• 带着什么问题：
  1. 为什么 Prompt 是用户控制、Resource 是应用控制、Tool 是模型控制？
  2. 一个客服知识库为什么同时适合暴露 search_kb Tool 和 support://... Resource？
  3. MCP Server 为什么不等于 Agent？
• 完成证据：画出 Mini Emperor、MCP Client、客服 MCP Server、PostgreSQL 之间的边界图，并为每条跨边界消息标出请求方和响应方。
• 优先级：P0
• 预计时长：25 分钟
• 检索日期：2026-07-27

3. 用官方 SDK 实现和验证 MCP Server

• 稳定 URL：
  • Build an MCP Server
  • Build an MCP Client
• 为什么读：课程要求不只会“声明 MCP”，还要走完初始化、发现、调用、错误处理和客户端验证。服务端教程还明确了 stdio 日志不能写到 stdout 这一类工程陷阱。
• 重点读哪里：
  1. Python FastMCP 初始化与工具装饰器；
  2. stdio 运行方式和日志规则；
  3. Client Session 的初始化、列举工具与调用；
  4. 类型提示、docstring 如何生成工具定义。
• 带着什么问题：
  1. stdio Server 的普通 print() 为什么会破坏协议？
  2. “Server 启动成功”和“Client 完成 capability discovery”有什么差别？
  3. 客户端应该怎样显示工具失败，而不是把错误伪装成正常答案？
• 完成证据：本地运行客服 MCP Server，再用独立 Client 完成 initialize → list_tools → call_tool(search_kb)，保存一次脱敏后的 JSON-RPC 轨迹。
• 优先级：P0
• 预计时长：60 分钟
• 检索日期：2026-07-27

4. MCP Authorization

• 稳定 URL：
  • Authorization Specification（2025-06-18）
  • Understanding Authorization in MCP
• 为什么读：远程 MCP 一旦能创建工单，就不能只检查“有没有某个字符串形式的 API Key”。规范给出了资源服务器、授权服务器、Client、scope 和 token audience 的边界。
• 重点读哪里：
  1. HTTP 与 stdio 在凭证处理上的区别；
  2. Protected Resource Metadata 与授权服务器发现；
  3. resource 参数、audience 验证和 PKCE；
  4. 最小权限 scope、HTTPS 与敏感日志清理。
• 带着什么问题：
  1. kb:read 和 ticket:write 应该在哪里验证？
  2. 为什么 token passthrough 是危险设计？
  3. 401 响应怎样告诉 Client 去哪里发现授权信息？
• 完成证据：为 search_kb 和 create_support_ticket 写两组权限测试；用只含 kb:read 的令牌证明前者成功、后者返回拒绝。
• 优先级：P0
• 预计时长：45 分钟
• 检索日期：2026-07-27

5. MCP 安全最佳实践

• 稳定 URL：MCP Security Best Practices
• 为什么读：协议连通不等于安全。MCP 会把外部描述、内容与可执行能力带进 Agent，必须防 token 误用、恶意 Server、工具描述投毒和越权调用。
• 重点读哪里：
  1. attacks and mitigations；
  2. confused deputy 与 token passthrough；
  3. session hijacking、DNS rebinding 与本地 Server；
  4. 最小授权、人类确认、审计与敏感数据处理。
• 带着什么问题：
  1. 哪些字段来自不可信 Server，不能直接当系统指令？
  2. 为什么工具描述也需要当作不可信输入？
  3. 人工确认应该发生在“模型决定调用”之前还是“真正产生副作用”之前？
• 完成证据：给客服 MCP 写一张威胁表，至少覆盖资产、信任边界、攻击入口、最坏影响、阻断措施和检测信号。
• 优先级：P0
• 预计时长：30 分钟
• 检索日期：2026-07-27

6. MCP Registry 与远程 Server 发布

• 稳定 URL：
  • Publishing Remote Servers
  • The MCP Registry
• 为什么读：这两页给出别人“如何发现并连接你的 MCP”的发布层答案，而不仅是部署一个 /mcp URL。Registry 当前处于预览期，因此课程必须保留 PyPI、Git 和远程 URL 三条分发路径。
• 重点读哪里：
  1. server.json 的 remotes 与 packages；
  2. streamable-http 和旧 SSE transport；
  3. URL 变量、secret header 声明；
  4. 公开可访问条件与 Registry 预览警告。
• 带着什么问题：
  1. 为什么远程地址应优先写 streamable-http？
  2. API Key 的“名字和输入提示”可以进 server.json，真实值为什么绝不能进入？
  3. Registry 数据重置时，用户还能从哪里安装？
• 完成证据：生成并校验 server.json，其中同时声明远程 MCP 和 PyPI stdio 包；从一台干净环境按文档完成连接。
• 优先级：P1
• 预计时长：30 分钟
• 检索日期：2026-07-27

7. GitLab Merge Request Pipeline

• 稳定 URL：GitLab Merge Request Pipelines
• 为什么读：课程的审核任务必须发生在真正合并之前，并在 MR 新提交后重新运行。MR Pipeline 是触发边界，不等于普通 feature 分支 Pipeline。
• 重点读哪里：
  1. CI_PIPELINE_SOURCE == "merge_request_event"；
  2. job rules 与 workflow: rules；
  3. fork MR 的权限与受保护变量；
  4. source branch pipeline 与 merged results pipeline 的差异。
• 带着什么问题：
  1. 为什么仅匹配 feature/* 分支不足以得到 MR 上下文？
  2. 来自 fork 的代码为什么不应拿到生产密钥？
  3. 审核的是 source branch 快照，还是与目标分支合并后的结果？
• 完成证据：提交一个 feature/demo → master 的 MR，保存 CI 页面，证明创建 MR 和推送新 commit 都触发审核，普通 push 不重复触发。
• 优先级：P0
• 预计时长：30 分钟
• 检索日期：2026-07-27

8. GitLab Rules 与重复 Pipeline 防护

• 稳定 URL：
  • Specify when jobs run with rules
  • workflow keyword
• 为什么读：错误的末尾兜底规则会同时创建 branch pipeline 和 MR pipeline，既浪费模型费用，也让同一报告被回写两次。
• 重点读哪里：
  1. rules:if、changes 与 when；
  2. CI_MERGE_REQUEST_SOURCE_BRANCH_NAME 和 CI_MERGE_REQUEST_TARGET_BRANCH_NAME；
  3. CI_OPEN_MERGE_REQUESTS；
  4. duplicate pipelines 的警告与避免方式。
• 带着什么问题：
  1. 如何精确表达 source 匹配 feature/* 且 target 等于 master？
  2. 怎样让确定性检查和 Agent Review 共享触发条件？
  3. 哪一层适合阻止整个 Pipeline，哪一层只跳过一个 Job？
• 完成证据：为 .gitlab-ci.yml 列出 4 个输入场景及预期结果：普通 feature push、目标为 develop 的 MR、目标为 master 的 MR、master push。
• 优先级：P0
• 预计时长：20 分钟
• 检索日期：2026-07-27

9. GitLab MR 报告与行级讨论

• 稳定 URL：
  • GitLab Notes API
  • GitLab Discussions API
  • GitLab Merge Requests API
• 为什么读：整份 Markdown 报告适合 Note，带文件和行号的可解决问题适合 Discussion。若不区分，Reviewer Agent 虽生成了证据，开发者却无法在代码旁处理。
• 重点读哪里：
  1. 创建、更新 MR Note；
  2. Note 与 Discussion / DiscussionNote 的差别；
  3. Diff position 所需的 SHA 和位置字段；
  4. detailed_merge_status、ci_must_pass 与 unresolved discussion。
• 带着什么问题：
  1. 新 commit 到达后如何更新旧报告而不是刷屏？
  2. fingerprint 应保存在哪里，才能找到同一问题？
  3. API 报告的行号在 diff 更新后失效时如何降级？
• 完成证据：同一 MR 连续运行两次，第二次更新汇总 Note；另创建一条可解决的行级 Discussion，并记录其 fingerprint。
• 优先级：P1
• 预计时长：35 分钟
• 检索日期：2026-07-27

10. FastAPI 流式响应

• 稳定 URL：
  • FastAPI Stream Data
  • FastAPI Custom Response: StreamingResponse
• 为什么读：Agent 的“当前状态”需要边运行边显示。流式响应把 Agent Event 逐条送给浏览器，但断线、取消和内容类型必须由应用层处理。
• 重点读哪里：
  1. async generator / iterator 与 yield；
  2. chunk 不会被自动转换为 JSON；
  3. generator 的取消点；
  4. media_type、header 与无限流。
• 带着什么问题：
  1. 为什么一个长循环至少要能到达 await 才能及时取消？
  2. SSE 事件为什么要自己编码为 id:、event:、data:？
  3. 浏览器断线是否应该取消 Agent Run？
• 完成证据：本地打开 /runs/:id，观察至少四种事件；中途关闭页面，证明后端不会因为无法取消而永久占用 worker。
• 优先级：P0
• 预计时长：25 分钟
• 检索日期：2026-07-27

11. SSE 浏览器协议

• 稳定 URL：WHATWG HTML Standard: Server-sent events
• 为什么读：FastAPI 负责“流”，EventSource 规范负责浏览器如何重连、解析事件 ID 和发送 Last-Event-ID。两者不是同一层。
• 重点读哪里：
  1. EventSource 接口；
  2. text/event-stream 格式；
  3. id、event、data、retry；
  4. Last-Event-ID 与自动重连。
• 带着什么问题：
  1. 为什么重连游标是事件 ID，而不是 Agent 的“第几步”文本？
  2. 同一个事件重复投递和 Skill 重复执行有什么区别？
  3. 服务端怎样发送心跳，避免代理层误判连接空闲？
• 完成证据：断开再恢复网络，证明 UI 从最后事件 ID 续播；数据库中同一 Run 的执行次数仍为 1。
• 优先级：P0
• 预计时长：20 分钟
• 检索日期：2026-07-27

12. DeepSeek Chat Completion、流式输出与 Tool Calls

• 稳定 URL：
  • DeepSeek Create Chat Completion
  • DeepSeek Rate Limit & Isolation
• 为什么读：课程默认 ModelClient 需要正确处理消息、工具 schema、流式 chunk、结束原因、用量和隔离。模型名、默认行为和 Beta 字段会变化，不能靠旧博客记忆。
• 重点读哪里：
  1. messages、model、thinking 与 max_tokens；
  2. tools、tool_choice、JSON Schema 与参数校验警告；
  3. stream、stream_options.include_usage、[DONE]；
  4. finish_reason、usage、user_id 和 KVCache 隔离。
• 带着什么问题：
  1. 模型生成的工具参数为什么必须再次由 Pydantic 校验？
  2. finish_reason=tool_calls 与普通文本结束如何驱动 Agent Loop？
  3. user_id 为什么不能塞入姓名、手机号等隐私信息？
• 完成证据：录制一次“模型请求工具 → 本地校验参数 → 执行工具 → 结果回填 → 最终回答”的脱敏事件序列，同时记录 tokens 与 finish reason。
• 优先级：P0
• 预计时长：40 分钟
• 检索日期：2026-07-27

版本提醒：本页检索时，官方接口页面列出的模型包括 deepseek-v4-flash 和 deepseek-v4-pro。实现中应把模型名放入配置，不要散落为硬编码；每次开课前重新检查官方更新日志。

13. PostgreSQL 全文检索

• 稳定 URL：PostgreSQL Current: Text Search Functions and Operators
• 为什么读：中文客服的混合召回不能只靠向量相似度。全文检索负责精确词、订单号、政策名等词法信号，并提供可解释的匹配和排序。
• 重点读哪里：
  1. tsvector、tsquery 与 @@；
  2. plainto_tsquery、websearch_to_tsquery；
  3. ts_rank / ts_rank_cd；
  4. 当前 PostgreSQL 版本对应的索引章节。
• 带着什么问题：
  1. 中文分词配置会怎样影响召回？
  2. 文档标题和正文如何设置不同权重？
  3. 为什么 SQL 查询正确不代表 Recall@5 达标？
• 完成证据：为一个政策名称、一个订单号样例和一个自然语言问题分别展示 query、top 5 和排名分数。
• 优先级：P0
• 预计时长：30 分钟
• 检索日期：2026-07-27

14. pgvector 与混合检索

• 稳定 URL：pgvector Project README
• 为什么读：这是 pgvector 维护方给出的类型、距离函数、HNSW/IVFFlat、过滤、重排与 hybrid search 基线。它说明“存下 embedding”只是起点。
• 重点读哪里：
  1. cosine/L2/inner product 运算符；
  2. HNSW 与 IVFFlat 的索引及查询参数；
  3. filtering、iterative scans；
  4. Hybrid Search 与 Reciprocal Rank Fusion / cross-encoder 建议。
• 带着什么问题：
  1. bge-small-zh-v1.5 的向量维度应怎样进入 schema？
  2. 为什么近似索引加过滤时可能丢失结果？
  3. RRF 如何合并向量名次和全文名次，而不直接比较不可比的原始分数？
• 完成证据：在同一 30 题评估集上比较 FTS-only、vector-only、hybrid 的 Recall@5，并保留查询延迟。
• 优先级：P0
• 预计时长：40 分钟
• 检索日期：2026-07-27

15. OWASP LLM 应用风险

• 稳定 URL：
  • OWASP Top 10 for LLM Applications
  • OWASP Top 10 for LLM Applications 2025 PDF
• 为什么读：Prompt injection（把不可信数据伪装成指令来改变模型行为）不是唯一风险。Skill Hub 同时面对不安全输出、供应链、敏感信息泄露和 excessive agency。
• 重点读哪里：
  1. LLM01 Prompt Injection；
  2. 2025 版 LLM03 Supply Chain；
  3. 2025 版 LLM02 Sensitive Information Disclosure 与 LLM06 Excessive Agency；
  4. mitigation 与攻击场景。
• 带着什么问题：
  1. 为什么 RAG 和微调不能彻底消除 Prompt Injection？
  2. Skill 包的 SHA-256、发布审核和能力策略分别挡住哪类风险？
  3. 模型输出为什么必须被当作不可信输入再验证？
• 完成证据：把课程 12 条强制安全测试逐条映射到 OWASP 风险；每条写出预防控制和检测控制。
• 优先级：P0
• 预计时长：35 分钟
• 检索日期：2026-07-27

16. NIST Agent Hijacking 评估

• 稳定 URL：NIST CAISI: Strengthening AI Agent Hijacking Evaluations
• 为什么读：NIST 把间接 Prompt Injection 描述为 Agent 从网页、邮件、仓库等外部数据中摄入恶意指令后被劫持。它提醒我们要评估完整 Agent，而不是只测模型拒答。
• 重点读哪里：
  1. trusted instruction 与 untrusted data 未分离的问题；
  2. Agent hijacking 的评估构造；
  3. 攻击成功和防御有效性的度量；
  4. 评估集对真实工具与任务的覆盖。
• 带着什么问题：
  1. 客服知识文章中藏有“导出所有密钥”时，哪个系统层必须阻止？
  2. 只看最终回答，是否会漏掉已经发生的越权 Tool Call？
  3. 安全回归为什么应按 trajectory（轨迹）验证？
• 完成证据：创建 5 个间接注入样例，至少覆盖知识库、Diff、Skill reference；验证它们既不能扩大权限，也不能把 secret 写进日志或产物。
• 优先级：P0
• 预计时长：25 分钟
• 检索日期：2026-07-27

阅读顺序建议

第 1 周：DeepSeek Chat Completion → FastAPI Streaming → WHATWG SSE
第 2 周：Agent Skills Specification → OWASP → NIST
第 3 周：PostgreSQL FTS → pgvector
第 4 周：MCP Architecture → Build Server/Client → Authorization → Security
第 6 周：GitLab MR Pipelines → Rules → Notes/Discussions API
第 7 周：MCP Registry Remote Servers → 回读 Agent Skills 与 OWASP

版本敏感点清单

每次课程正式开课前，应重新检查以下内容：

1. Agent Skills 的实验性 allowed-tools 是否已稳定，以及校验器版本；
2. MCP 当前 protocol revision、Registry schema 和预览状态；
3. GitLab CI 预定义变量、fork pipeline 与 protected variable 规则；
4. FastAPI streaming API 和取消行为；
5. DeepSeek 可用模型名、工具调用和 thinking 字段；
6. pgvector 当前版本、索引参数与 PostgreSQL 支持范围；
7. OWASP LLM Top 10 当前版本。