AI Agent Engineer

AI Agent Engineer

2026-07-20 第十阶段来源许可、路线元数据与 OpenAI 动态页记录

16 min read

2026-07-20 第十阶段来源许可、路线元数据与 OpenAI 动态页记录

目标与证据边界

本阶段没有把“尚未审阅的第三方页面数量”当作完成指标，而是优先处理会改变公开边界、主路线或当前 API 实践的高风险问题：

  1. 按真实入链与来源证据审计冻结参考页，只恢复能证明来源、许可和附件边界的页面；
  2. 纠正 Agent Skills 与 MCP 的许可证事实和发布门禁；
  3. 将第二批经正文确认的课程关系迁移到学习路线元数据 v2；
  4. 依据 2026-07-20 的 OpenAI 官方文档与 SDK 源码修订动态 API 页面；
  5. 用反例测试、完整 Quartz 构建和 Python 多模式测试验证，而不是只检查 Markdown 外观。

“公开构建通过”只证明当前导出策略、链接和静态门禁成立，不证明第三方材料已经取得额外授权，也不证明远程 API、账户权限或 SDK live behavior 已执行。

1. 冻结参考页审计与小范围恢复

1.1 审计结果

第九阶段生成物中的目标队列原有 186 个 third-party-metadata-missing stub：D2L 141、LangChain 25、MCP 12、Agent Skills 8。逐页入链分析确认 71 页至少被一个全文页引用，但“有入链”不等于“可再分发”。

本阶段没有机械补 frontmatter。最终参考层保持 189 个 fail-closed stub：

参考层当前 stub处理结论
D2L 中文参考正文140Apache-2.0 仓库来源明确，但页面内插图、代码例外与精确快照仍待抽查；只把本地 00-来源与目录.md 恢复为 curated 导航
LangChain 官方参考层23恢复 2 个无附件阻塞的高入链 MIT 页面；Semantic Search 因终审发现事实、术语与代码问题而撤回，Memory、RAG 等仍被图片治理或快照证据阻塞
MCP 官方参考层18当前/跨迁移页面的许可不能统一写 MIT；全部继续 stub
Agent Skills 官方参考层8文档为 CC BY 4.0，但尚未形成逐页固定内容快照；全部继续 stub

最终数比原队列多 3，不是回退：D2L 本地目录与 2 个 LangChain 页面共恢复 3 页；同时更严格的路径审计发现 1 个缺来源字段的 MCP 页，以及冻结前缀把真实目录错写成不存在的 MCP/03-使用 MCP/，此前漏拦 5 篇 MCP/03-使用 MCP 开发/ 官方参考正文。修正真实路径后，这 6 页也进入 fail-closed 队列。

1.2 恢复的两个 LangChain 页面

以下页面补齐 third-party、frozen-reference、source_url、MIT、上游署名与本地改动说明，并在正文显示冻结来源 callout：

两页均无当前附件阻塞，且来源匹配 LangChain 官方文档仓库 MIT 登记。由于本地正文的精确 Git commit 仍未知，页面明确写成固定日期参考，而不是当前 SDK 教程。Quartz HTML 抽查确认两页 callout 和上游链接可见；本地改动说明同步披露术语纠正、解释性注释和窄范围代码处理。

语义搜索原计划作为第三个恢复页，但独立终审发现 ISAACUS 示例缩进错误、5 个运行输出误标为 Python、InMemoryVectorStore 分数方向写反，以及 Cohere、Voyage AI、IBM watsonx、Milvus、Retriever 等机器翻译术语错误。本阶段只修复这些已确认问题，并把页面改为 needs-review；公开构建使用专用质量待复核 stub，完成 39 个剩余 Python fence 的 AST 检查也不等于所有外部集成可运行。

2. Agent Skills 与 MCP 许可边界

2.1 Agent Skills：代码 Apache-2.0 不等于文档 CC BY 4.0

上游仓库根目录代码使用 Apache-2.0，docs/ 与网站文档使用 CC BY 4.0。原发布登记把整套 Agent Skills 文档写成 Apache-2.0，虽然页面当时仍因缺元数据而没有泄漏正文，但一旦补字段就会产生错误放行。

本阶段改为：

  • 只登记 8 个本地参考页与 8 个精确 agentskills.io 路径，不允许任意同域路径、错绑页面、query 或 fragment；
  • 强制 content_origin: third-party、content_status: frozen-reference、license: CC-BY-4.0；
  • 强制固定的项目署名与中文翻译改动声明，拒绝 false、0、否定句、占位文本和 YAML 转义控制字符；
  • 生成期把署名、来源、许可和本地改动注入可见 callout，不依赖隐藏 properties；
  • 固定上游 docs/LICENSE 的本地副本，构建期核对 SHA256 9E5F1B3C610B9C2DA5C313BF81D577A7D1ACEC686BDB0384EDEFA6DF0F90CD94；
  • 把 Agent Skills/examples/ 从整目录豁免改为 5 个已审文件的精确白名单；新增 Markdown、代码或数据默认排除；
  • 恢复 Specification 正文中示例 Skill 自己的 license: Apache-2.0，不再把页面许可证误写进技能元数据示例。

独立安全复核重放了 origin/status、路径、页面绑定、许可证错配、占位署名、控制字符、fenced heading、stub title 和未审示例资产等反例，未发现剩余 P0。8 个 Agent Skills 官方参考页仍全部是 stub；首次真正恢复任一 CC BY 页面前，还要补固定内容 blob，并对最终 Quartz HTML 增加署名集成断言。

2.2 MCP：旧仓库 MIT 不覆盖新文档与跨许可页面

官方旧 modelcontextprotocol/docs 仓库以 MIT 归档。项目迁入 modelcontextprotocol/modelcontextprotocol 后，2026-01-05 的许可切换规定普通新文档贡献使用 CC BY 4.0，未重新许可的旧贡献保留原许可；跨切换演进的页面可能同时包含不同许可贡献。

因此：

  • 公开来源注册表只保留已归档旧仓库的 MIT 路径；当前 modelcontextprotocol.io 不再自动继承旧 MIT；
  • MCP 入口的 reference_layer_license 改为 page-specific，18 个冻结参考页继续逐页失败关闭；
  • 架构页把 logging 误列为 client capability 的错误已改为：roots、sampling、elicitation 属于 client 侧能力，logging 是 server 向 client 发送日志消息的 server capability；勘误不代表全页已重译；
  • 客户端概念页其实是本地摘要；移除无法按当前页面证明的 MIT 断言，标记 needs-review，并记录后续迁移到原创学习路线的边界；
  • 生成的第三方声明明确区分“已归档旧文档 MIT”和“新/跨迁移页面待逐页核验”。

3. 学习路线元数据 v2 第二批

在不改变 legacy 课程目录顺序的前提下，新增 12 门 v2 课程：JSON、数据清洗、现代 LLM 能力与模型选择、提示词工程、上下文工程、LLM API 集成、文档解析、知识库构建、RAG、工作流自动化、运行监控与 Benchmark 设计。全库现为 16 门 v2、40 门 legacy。

机器硬依赖只保留正文使用“先完成”等强语义且能在同一角色闭合的关系：

  • json + data-cleaning → document-parsing → knowledge-base；
  • prompt-engineering → context-engineering；
  • tool-calling → agent-core；
  • evaluation → benchmark-design；
  • evaluation → llmops。

RAG 作为角色路线集成站进入 v2，但没有把“建议先学”的 Chunking、Embedding、向量数据库、语义搜索与 Reranking 伪造为硬前置。角色 order 继续表达推荐顺序；完整 RAG 路径仍由 总路线人工承载。

验证器新增三条闭包不变量：硬前置必须出现在依赖课程的每条角色路线中、order 必须更早、core 课程的硬前置也必须为 core。总路线新增 Mermaid 硬依赖图，并明确它不代表推荐 track 或早期 milestone。

4. OpenAI 动态 API 页

OpenAI API 调用依据官方 Docs MCP、当前模型解析结果和 openai-python v2.46.0 源码完成深审：

  • 说明 Chat Completions 仍受支持，但新项目推荐 Responses；gpt-5.6 是会变化的别名，生产升级前必须重跑回归；
  • 所有 Responses 示例显式选择 store；新增 Responses、previous_response_id、Conversations 与 Files 的保留/删除边界，明确 store=False 不等于 ZDR；
  • 文件示例同时设置 expires_after，并在 finally 主动删除；
  • 文本、结构化输出、图片、搜索与图像生成都先验证合法终态，不把 output_text / output_parsed 当作完成证明；
  • 统一终态 helper 会遍历 output[*].content[*] 拒绝 refusal；即使响应同时含部分 output_text 与拒答，也不会提交为成功结果；
  • 流式示例区分 provisional delta、refusal、failed、incomplete、顶层 error 与 EOF 无 terminal；
  • 函数调用改为有限多轮循环，拒绝未知工具、重复 call_id、非有限 JSON、字段外参数与轮数耗尽，并说明内存去重不等于 durable ledger；
  • 解释 SDK 默认两次重试、单一 retry owner、per-attempt timeout 与业务总 deadline 的区别，不承诺通用 HTTP exactly-once；
  • 增加 docs/API/examples/test_openai_api_markdown.py，离线解析 16 个 Python code fence，并锁住显式存储、文件清理、混合文本/拒答、工具终态和流式 terminal 合同。

本页没有使用真实凭据或发起网络请求；execution_verified: false 保留。live 模型权限、远程事件对象、限流与账单行为仍待单独的低费用合同测试。

5. 发布门禁进一步收紧

除许可证修正外，本阶段关闭了以下 fail-open 或可见内容注入：

  • 冻结参考树不能通过把 origin 改成 original、curated 或 mixed 来释放镜像正文；
  • 治理字段拒绝解码后的控制字符与 Unicode 行分隔符；
  • stub 标题移除控制符、Markdown 图片/链接、HTML 与远程 URL，正文不会从 title 逃逸；
  • CC BY 可见署名固定插在 frontmatter 后，不会落入伪造的 fenced heading；
  • Agent Skills 示例资产在分类器本身默认拒绝，而不只依赖相邻 stub 检查；
  • Mermaid 已使用同源锁定模块，但 Quartz Head 残留的 cdnjs.cloudflare.com preconnect 仍会建立第三方连接；现已删除，站点校验拒绝任何 cdnjs 引用。

6. 实际验证

  • 网站单元/策略测试：npm test 为 45/45。
  • 依赖审计：npm audit --omit=dev 为 0 个当前 registry 已知漏洞；这不是未来安全保证。
  • 最终站点构建：892 个源 Markdown，其中 546 个全文、346 个 stub；连同 3 个生成页共 staged 895 个 Markdown，发布 214 个资源、2,392 个 HTML 页面和 2,730 个 public files。
  • 路线：56 门课程、8 个阶段、72 个导航文件夹；16 门 v2、40 门 legacy。
  • 门禁：brokenLocalLinks、forbiddenFiles、progressMetadataLeaks、sensitiveLeaks、selfRedirects、tableWikilinkLeaks、checkboxProgressRuntimeLeaks、interactiveCheckboxes、katexErrors 均为 0；最终 public 中 cdnjs 引用为 0。
  • OpenAI Markdown 专项：6 项在 normal、-O、warnings-as-errors 与组合模式通过；16 个 Python fenced block 全部可由 AST 解析。
  • Python 离线矩阵：固定清单共 69 个测试文件，SHA-256 为 9B12CAE593F7A1A8D72283A93AF81AA8C672537B4CC912161D399ED904131B02；每种模式 2,529/2,529，通过 normal、-O、warnings-as-errors 与组合模式，共执行 10,116 次测试方法。基础组 64 文件/2,485 项，OpenAI Markdown 6 项；离线缓存重建的 Python 3.11.9 环境另验证 LangGraph 1.2.9 + checkpoint-sqlite 3.1.0（8 项）、CrewAI 1.15.4（9 项）、Matplotlib 3.11.0（12 项）和 scikit-learn 1.9.0（9 项），四个环境 pip check 均通过。
  • git diff --check 通过；未运行真实 OpenAI 请求，也未使用 --apply 类外部写回命令。

7. 核心来源

8. 后续队列

  1. 继续审阅 189 个冻结参考 stub；优先完成 Semantic Search 的逐段重译与版本锁定，解决 LangChain Memory/RAG 的逐图 blob 与许可证、MCP 的逐页提交历史/组合许可，以及 Agent Skills 的固定正文快照。不得批量回填。
  2. 迁移剩余 40 门 legacy 课程；先解决 RAG 组件“能力建议、条件依赖、完整课程硬前置”的语义，再让 Homepage、CourseNavigator 和外层 Dataview 消费角色 track。
  3. 为“早期安全与评测”建立可机器引用的 milestone 类型，并为框架选择建立 choice group，避免用顺序号伪装必修链。
  4. 增加有凭据门控、低费用、无副作用的 OpenAI/Anthropic/Gemini live contract suite，验证真实 SDK 对象、SSE framing、超时、429、重试和请求 ID。
  5. 首次恢复 CC BY 正文时，对最终 Quartz HTML 增加署名、许可链接和改动说明集成断言；继续补 SBOM 与传递依赖 NOTICE。
  6. 在 Obsidian 桌面端抽查新增 Mermaid、宽表、callout、长代码块与移动端阅读体验；本阶段只完成 Quartz HTML 抽查。

本记录只覆盖第十阶段，不表示整个长期 /goal 已完成。

Backlinks