2026-07-21 第十五阶段提示词、API 与检索状态合同深审记录
阶段结论
本阶段完成了 提示词工程 与 LLM API 集成 的逐章深审，并针对 Embedding、语义搜索 和 向量数据库 的评测、安全与生命周期页面做专项深审。共修改 26 篇课程页面、五组离线项目及其 fixtures/tests；课程目录名称与角色路线未改变。
重点不是扩写篇幅，而是把此前只存在于文字中的工程边界落实成可运行证据：
- prompt、schema、dataset 与报告不再彼此漂移，非法教学 schema 和篡改报告失败关闭；
- 三家 Provider 的状态、存储、续接、流式事件和工具结果不再被抹平成一个伪统一接口；
- Embedding/检索指标拒绝重复排名 ID 与非法 qrels，安全审计覆盖完整候选窗口；
- 向量库把 source CAS、delete-before-create、tombstone fence、resurrection、旧实例读写冲突和资源上限变成严格状态机；
- 独立 reviewer 找到并推动修复 GitHub 来源路径逃逸、删除意图丢失、旧实例误确认和 stale-read 等主审未首先发现的问题。
结论边界
本阶段证明当前离线合同、fixtures、负向测试和公开构建自洽；不证明真实供应商端点、模型语义质量、IAM、分布式数据库一致性、永久审计账本或所有历史课程均已完成深审。向量查询仍未实现端到端 space-signature envelope。长期 /goal 继续保持 active。
多 Agent 执行与复核
主 Agent 冻结范围、证据标准与共享术语后，将工作拆成三条可独立修改的边界：
- 提示词工程课程、schema 与离线实验；
- LLM API 课程、可靠客户端和三家 Provider 合同；
- Embedding、语义搜索与向量库状态合同。
另设两个只读 reviewer，分别复核 Provider 动态事实/实现和检索生命周期。所有 Agent 只修改分配目录，不做 stage、commit、reset 或跨目录重构；跨课程的术语、测试计数、来源边界、已知限制与最终链接由主 Agent 统一复核。
这次独立复核产生了实质改进：
- Prompt 主审后的复核要求教学 JSON Schema 使用精确关键词白名单，并让报告按完整 CaseResult 重算，不能只比较 passed；
- LLM reviewer 证明原 GitHub 路径前缀检查可被 ../、百分号编码和重复分隔符绕过，并纠正 Gemini Standard key 迁移范围；
- Retrieval reviewer 证明“point 不存在就返回删除成功”会丢失 delete-before-create 意图，也发现 stale no-op、stale search、tombstone 资源增长和裸 query space identity 等边界。
提示词工程深审
版本化资产与可重复评测
提示词实验项目 现在把 prompt、dataset、schema 和评测报告视为四个独立但相互绑定的版本化资产：
- dataset v2 含 12 个 typical、boundary、multilingual、insufficient 与 adversarial cases，并记录 annotation reason；
- prompt version、dataset version、schema version 与三个资产的 SHA-256 进入报告；
- label、risk、summary、reason 等字段进入教学 schema，未知字段、未知 schema 关键词、错误 dialect、错误 ID 与运行时 schema 漂移都会失败；
- 报告按每条 case 重算完整结果，篡改 label、risk、errors、prompt_chars 或 passed 均不能被接受；
- CLI 在输入、schema 或资产错误时写 stderr 并以非零状态退出，普通与 -O 输出一致。
这里的 schema validator 是明确声明的教学子集，不冒充完整 Draft 2020-12 实现。真实生产系统应使用锁定版本的成熟 validator，并另外执行 refusal、incomplete、业务语义与授权检查。
当前产品事实与安全边界
课程已按 2026-07-21 官方状态更正：
- OpenAI reusable prompt objects 与旧 Evals platform 已于 2026-06-03 宣布弃用，课程改用代码内 prompt/schema/dataset 版本，不把即将关闭的平台对象作为主线；
- Structured Outputs 只约束结构，不能消除 refusal、incomplete、事实错误、业务错误或越权；
- 第三方网页、用户正文和工具输出保持低信任数据身份，不能拼进 system/developer instruction；提示注入防护与身份、授权、工具 allow-list、输出验证和审计共同工作。
LLM API 集成深审
三层合同与状态续接
九篇课程现在统一区分：
- 应用 canonical contract；
- Provider wire/API contract；
- SDK convenience layer。
三家 Provider 合同项目 用三份手工维护的离线 fixture 分别描述 OpenAI Responses、Anthropic Messages 与 Gemini Interactions 的当前流式工具调用。它们是带官方来源、版本和校验日期的原创教学工件，不是线上抓包，也不是第三方文档的完整复刻。
课程明确保留供应商差异：
- OpenAI previous_response_id/Conversation、instructions 继承、store 与历史 Items 的关系；
- Anthropic Messages 的客户端历史、mid-conversation system、refusal/fallback beta 与 retention；
- Gemini Interactions 的 previous_interaction_id、store、完整 Step 历史，以及 tools、system_instruction、generation_config 的逐轮重放。
Stateless continuation 只有在完整、来源绑定的历史快照存在时才生成；未知终止状态、未知关键 block、截断、stream error 或不完整工具参数失败关闭。
来源 URL 与认证事实修复
Fixture 的 source URL 校验现在要求精确官方 host；GitHub URL 还要在一次严格 percent-decode 后按 path segment 匹配批准仓库。Dot segment、重复/编码分隔符、反斜杠、畸形 UTF-8、嵌套编码、userinfo、非默认端口和跨仓库路径均被拒绝。此 allow-list 只证明元数据形状符合本项目政策，不证明远端内容真实性、完整性或未被替换。
认证章节同步了三项动态事实：
- OpenAI Python SDK 当前支持 workload identity 短期身份；
- Anthropic 提供 API key 与 WIF；
- Gemini API 当前已拒绝 unrestricted Standard keys，并说明 2026 年 9 月起将拒绝所有 Standard keys，因此受限 Standard keys 也要迁移 Auth keys。
Anthropic server-side fallback 只由 safety-classifier decline 触发；429、overload 与 server error 不触发。允许的目标从 Models API 的 allowed_fallback_models 读取，不能硬编码。当前 parser 对 fallback block 明确抛 UnsupportedProviderState，直到项目实现并验证完整 continuation 语义。
可靠客户端资源边界
可靠客户端项目 增加 client 生命周期、monotonic retry deadline 与有界 stream：
- 只有显式分类的暂时错误进入唯一 retry owner；
- attempt 与 deadline 共用一个预算，Retry-After 不得越过总 deadline；
- canonical stream 最多 4096 个事件、累计最多 100000 个文本字符；
- 同一累计字符上限同时拦截一个超大 delta 和许多小 delta，不虚构独立单-delta 常量；
- 超限、partial、缺 terminal 或流内错误都不释放 provisional 结果。
检索链路专项深审
Embedding 与语义搜索评测
Embedding 评测项目 的 MRR、Recall 与 nDCG 现在拒绝重复 ranked IDs；qrels 只接受非布尔的 1..3 整数 grade，nDCG 结果显式约束在 0..1。这样可避免同一文档重复占位或非法标签把离线质量指标抬高。
离线混合检索项目 的 must-not-return、tenant、ACL 与 eligibility 审计改为检查完整 channel candidate window，而不是只检查最终 top-k。越权记录即使在融合后落到截断线之外，也会使安全门禁失败。
向量库删除、并发与资源合同
玩具向量存储 升级到严格 schema v2：
- 完全相同 upsert 是不增长 revision 的 no-op；非同值更新必须匹配 expected-current source revision；
- 同 source revision 对应不同 vector、payload 或 content hash 时进入冲突；
- delete 即使早于 create 也持久化 tenant/source/event fence，阻止迟到 upsert；
- resurrection 必须同 tenant、匹配旧 source/delete event 且使用新的 source identity；token 不是授权凭据；
- no-op、delete replay、search 与 snapshot summary 均先检查磁盘 revision，旧实例不再误报成功或返回旧 ACL/删除状态；
- live points 与 tombstones 合计最多 100000 条，完整序列化状态按真实 UTF-8 bytes 限制为 20 MiB，并在 replace 和内存更新前失败。
Source revision 仍是 opaque identity，只比较相等性，不按字符串猜先后。同一 point 跨生命周期必须由 canonical source 保证 identity 不复用；本项目没有永久 generation/history ledger，不能防止 r1 → delete → r2 → delete → r1 的 ABA。Resurrection 会移除当前 tombstone，因此永久 create/update/delete/resurrection 历史必须进入外部 append-only lifecycle/audit ledger。
当前 search 仍接收裸 query vector，只检查 dimension、finite、norm 和 store metric；同维但来自另一模型/encoding role 的 query 仍可能误用。课程已将 QueryVector(contract_signature, encoding_role) envelope 与同维异空间反例列为后续任务，不声称端到端空间绑定完成。
核心来源
本阶段优先使用官方文档、规范和原始论文，动态事实均记录 2026-07-21 复核日期：
- OpenAI Prompt engineering、Structured Outputs、Deprecations、Conversation state 与 Function calling；
- OpenAI Python SDK；
- Anthropic prompt-injection guardrails、Refusals and fallback、Authentication 与 API/data retention；
- Gemini Interactions、Gemini API keys 与 Interactions v1 reference；
- Sentence Transformers semantic search、Elasticsearch RRF、Qdrant hybrid queries 与 Qdrant points；
- MTEB、RRF、HNSW、DPR、ColBERT 与 Sentence-BERT 原始论文。
验证证据
| 检查 | 结果 |
|---|---|
| Prompt 回归 | 19 项 unittest 在普通与 -O、-W error 下均通过；CLI 12/12，通过且双模式逐字一致 |
| Reliable client 回归 | 22 项 unittest 在普通与 -O、-W error 下均通过 |
| Provider 合同回归 | 99 项 unittest 在普通与 -O、-W error 下均通过；包含 11 个 URL 攻击子用例 |
| Embedding 回归 | 31 项 unittest 在普通与 -O、-W error 下均通过 |
| 语义搜索回归 | 34 项 unittest 在普通与 -O、-W error 下均通过 |
| 向量库回归 | 41 项 unittest 在普通与 -O、-W error 下均通过；测试内验证 demo 与 CLI 双模式等价 |
| 本阶段 Python 合计 | 每种模式 246 项，普通与 -O 共 492 次用例执行 |
| 站点单元测试 | 46/46 通过 |
| 完整公开构建 | 905 个源 Markdown；559 个全文、346 个 fail-closed stub、220 个资源；生成 908 个 staged Markdown 与 2425 个 HTML 页面 |
| 导航验收 | 57 个课程入口、10 个知识域、4 条角色路径、72 个导航文件夹 |
| 发布门禁 | broken local links、禁止文件、进度泄漏、敏感信息、自重定向、表格 wikilink 泄漏、交互 checkbox 与 KaTeX 错误均为 0 |
| 作用域检查 | 各专项与全局 git diff —check、测试计数、维护记录链接和独立 reviewer 均通过 |
各 Agent 均未手工 stage、commit、reset 或回退其他工作；本阶段修改继续保留为工作区 diff。外层 vault 的 .obsidian/workspace.json 与 Remarks/账号.md 等用户状态未被本阶段读取、修改或纳入处理。
后续队列
- 为向量查询加入 contract signature、encoding role 与 query/document role envelope，补同维异空间负向测试，并把相同空间合同贯通 Embedding、向量库与语义搜索。
- 为向量生命周期加入不可复用 generation/row version、永久 history fence、append-only audit ledger、tombstone retention/purge 与跨进程事务；当前 JSON 教学库只展示局部状态合同。
- 将三家 Provider fixtures 接入锁定 SDK 版本的 capture/redaction/replay 流程，并在隔离账号运行真实 API 合同测试；动态 fallback、storage、retention 与事件 union 仍需持续复核。
- 将提示词实验接入真实 tokenizer、模型与任务级评测，加入人工标注一致性、跨模型对比、统计区间和回归发布门；当前 deterministic evaluator 只证明资产与规则自洽。
- 继续统一文本规范化、dtype 物理表示、embedding metadata 与迁移 manifest；NFC/NFKC、序列化 dtype 和模型兼容不能只靠教学字段推断。
- 在 Obsidian 阅读视图抽查新增 Mermaid、长表、callout、代码链接和移动端布局；Quartz 通过不能替代桌面端渲染。
- 继续逐页审阅尚缺来源/状态元数据的历史课程，不做机械批量填充。
本记录只覆盖第十五阶段，不表示整个长期 /goal 已完成。