# 课程勘误与文案更新 · 2026-10-22

本次以实际在线版 `20261022-analytics-a5f705ba` 为基线，采用 Gemini 返回的 15 批润色稿，结合人工编辑与技术核对更新首页和 34 课。没有直接将生成的 HTML 覆盖到站点：正文按原结构回填，保留章节 ID、63 幅图、75 个图示阶段、原有下载与参考链接。涉及确定性被夸大、图示说明混入正文或行内代码不一致的建议，保留原文或另行修正。

## 已修正

| 页面 | 问题与修改 |
| --- | --- |
| 环境准备 | 将与当前示例不一致的“Python 3.10+”改为建议 Python 3.12，并注明示例依赖使用 3.11–3.13；补充 Windows PowerShell 激活方式。 |
| 环境准备 | 删除固定“后续八周”的旧进度描述；补齐下载包、进入目录、依赖安装和离线测试的具体操作。 |
| 环境准备、工具概览 | 明确 CHAT、STRUCTURED、TOOLS、EMBEDDING 四组环境变量及 embedding 维度；说明 `.env` 文件不会由 Python 自动加载，密钥保留在后端。旧课号改为实际课程链接。 |
| 工具概览 | MCP 不仅是检索接口，还可提供工具、资源和提示词；Instructor 负责结构化输出解析与验证，不是状态或长期记忆管理组件。 |
| 生命周期、架构模式 | 删除没有署名或证据支持的“根据我的经验”“我见过多个系统”等亲历陈述。 |
| 检索评估、实践 | 用明确课程链接取代“第 8/9 课”等全站与阶段编号混用。说明示例分块大小以字符计数，不能当作 token 数；区分飞书 `docx` 类型与本地 Word 文件。 |
| 检索评估 | 说明资料级集合 Precision/Recall 与按排名计算的指标不同；空参考集计分是教学约定，应另报拒答表现。 |
| 数据摄取 | 补齐背压与有限重试的第 6 项标题，保留已有章节锚点，清除“原文缺序号”的编辑旁注。 |
| 结构化输出 | `chat.completions.parse()` 后直接读取 `message.parsed`，不再调用弃用的 `parse_raw()`；处理拒绝、缺少解析结果、长度截断及内容过滤异常。补上示例中未定义的 `prompt`。 |
| 结构化输出 | 将旧的 LangChain 导入改为 `langchain_core.output_parsers`、`langchain_core.prompts`；明确 Pydantic 模型、提供方格式约束和内容事实正确性是不同保证。速度取决于实际模型与请求，不能作通用承诺。 |
| 分块 | 明确 Contextual Retrieval 词法部分采用 BM25，并解释与图中 TF-IDF 标签的关系；在线步骤编号从 8 连续至 11，使“第 10 步”引用正确。 |
| 反思 | 用 `StateGraph` / `MessagesState` 替代弃用的 `MessageGraph`，用生成次数计数器限制循环，明确回调输入输出；示例文件提供相同代码。 |
| 反思、人类反馈、安全 | 删除机械重复的模板段落，分别恢复状态检查、反馈归档和工具授权等小节的具体内容；修正 `retrieve_context` 拼写，移除生产正文中的编辑说明。 |
| 首页及全部课程 | 压缩空泛开场、套话及重复表达；保持代码与链接的保护规则。生成稿把容器化、故障概率等说得过于确定的地方，按事实边界回调。 |

## 已核对、无需按生成稿修改

- `#sprint-0` 对应环境准备，`#sprint-1` 对应 Sprint 0，是按模块顺序命名，不能据此判定目录错误。
- 百炼官方文档目前列有 `qwen3.8-max`，不能因模型名称陌生便改成 `qwen-max`。实际可用性仍受地域、业务空间和权限影响。
- 北京业务空间 OpenAI 兼容地址、同地域 API Key 要求，以及当前 A2A v1.0.1 的发现路径和绑定规则，按官方资料核对；不采纳缺少依据的替换建议。
- 61 个原代码块中的改动仅针对明确勘误；结构化输出共享 `examples/pipeline.py` 片段保持源文件的真实换行，不采用 Gemini 曾产生的字面量 `\\n`。

## 核对依据

- [Pydantic v2 迁移](https://pydantic.dev/docs/validation/latest/get-started/migration/)
- [OpenAI Python SDK 2.6.1 结构化解析辅助接口](https://github.com/openai/openai-python/blob/v2.6.1/helpers.md#structured-outputs-parsing-helpers)
- [OpenAI 官方文档：Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs)
- [LangGraph 概览](https://docs.langchain.com/oss/python/langgraph/overview) · [MessageGraph 弃用说明](https://reference.langchain.com/python/langgraph/graph/message/MessageGraph)
- [LangChain v1 迁移](https://docs.langchain.com/oss/python/migrate/langchain-v1)
- [MCP 架构](https://modelcontextprotocol.io/docs/2026-07-28/learn/architecture)
- [百炼兼容接口与地域](https://help.aliyun.com/zh/model-studio/compatibility-of-openai-with-dashscope) · [结构化输出与模型支持](https://help.aliyun.com/zh/model-studio/qwen-structured-output)
- [A2A v1.0.1](https://a2a-protocol.org/v1.0.1/specification/)
- [Anthropic Contextual Retrieval 原始实验](https://www.anthropic.com/research/contextual-retrieval)

## 验证范围

验证结果保存在该次部署证据中。离线检查使用合成 HTTP 响应、真实 SDK 解析及本地状态图回调；它们可以验证语法、接口用法和程序分支，不能代替付费模型、真实飞书/钉钉租户或生产权限集成验收。本次没有使用学习者账户执行这些真实调用，也不声称逐一复现了所有外部研究或框架示例。

示例下载包与项目 `examples/` 同步；站点继续采用 Next.js 静态导出，Sentry 和 Umami 的集成保留。