第 5 周 · Session/Context 精简版 + RAG 数据管道
建立够用的上下文管理机制，完成可增量更新的知识入库系统
本周产出：基本 Session Log、Prompt Registry、Upload 到 Index 全链路 · 预计投入：15 到 20 小时 · 对应原 24 周编号：第 6、7 周
分档说明
Session 深度实现（JSONL 树、branch / fork / replay、压缩保真度测试）与 Skills / Extensions 在程序员进阶版模块 A2 完成，本周只做基本可用的上下文管理。
学前自测
1. 什么是 Lost-in-the-middle？它对上下文组装有什么直接影响？
模型对长上下文中间部分的信息利用率明显低于开头和结尾。直接影响是：检索到的关键证据不能随便扔在上下文中段，重要内容要放在靠前或靠后的位置。这不是玄学，是有实验数据支撑的工程约束。
2. Chunk 切多大合适？为什么这个问题没有标准答案？
因为它同时受三个变量牵制：检索精度（越小越准）、上下文完整性（越大越全）、Token 成本（越大越贵）。合适的做法是 Parent / Child 双层：用小 Chunk 检索保证精度，命中后返回它的 Parent 保证完整性。第 6 周会实现这个。
3. 同一个文件上传两次，你的系统怎么知道不用重新索引？
靠 Content Hash。对文件内容算哈希，入库前先查这个哈希是否已存在。这看起来是小细节，但没有它的系统在真实使用中会迅速产生大量重复 Chunk，检索结果里全是同一段话的复制品。
4. Prompt 为什么需要版本管理？和代码版本管理有什么不同？
因为 Prompt 改一个字就可能让线上效果掉一截，而且这种回归不会被单元测试发现。和代码不同的是：Prompt 的正确性只能靠评测集验证，所以 Prompt Registry 必须绑定测试，发布前跑一遍，效果下降就阻断。
学习目标
建立够用的上下文管理机制，并完成可增量更新的知识入库系统。
上下文管理是 Agent 成本和质量的最大杠杆。同样一个任务，上下文组装做得好和做得差，成本可能差五倍，准确率可能差三成。
课程内容
Session / Context 精简版
- System / Developer / User / Tool 边界
- Context Assembly、Transform 与 Token Budget
- 基本 Session Log（记录多轮对话上下文）
- Prompt Registry、版本、变量、依赖和回滚
- Context Rot、Lost-in-the-middle 的基本认知
RAG 数据管道
- Loader / Parser / OCR 边界 / 文档清洗
- Chunking、Parent / Child Chunk
- Metadata、Document Version、Content Hash
- 增量更新、删除与重建
- 多租户隔离、文档权限
- 框架无关 Document / Chunk Contract
- 数据来源、版本与删除事件
实施任务
实现：
ContextEngine：预算、选择、排序、transform（不要求 compaction 全集）- 基本
SessionLog：记录多轮对话上下文，不要求 branch / fork / replay PromptRegistry：版本、变量 Schema、依赖、发布和回滚- RAG 管道：
支持 PDF、Markdown、HTML、CSV。
动手挑战
做一次 Chunk 尺寸的对照实验，用数据说话而不是凭感觉选。
准备 20 个真实问题和对应的标准答案位置，然后用三种切分策略入库同一批文档：256 Token 固定切分、512 Token 带重叠、按语义段落切分。对每种策略测量：
- Recall@5（标准答案所在的 Chunk 有没有被召回）
- 平均返回 Token 数（成本）
- 索引后的 Chunk 总数（存储成本）
把结果做成一张表。这张表是你第 6 周调优的基线，也是面试时证明你做过量化优化的证据。
Agent OS 里程碑
完成基本上下文管理、Prompt Registry，以及知识库上传、索引任务与框架无关 DocumentContract。
验收标准
核心档（程序员基础版毕业线）
- Session 能正确维护多轮对话上下文
- Prompt 发布前必须通过测试，运行记录包含 Prompt Version，可回滚上一版本
- 同一文件重复上传不会重复索引
- 文件更新可增量重建，删除文件同步删除 Chunk
- 每个 Chunk 可追溯原文
- 租户之间数据隔离
- 入库代码不依赖 LangChain 或 Mastra Document 私有类型
进阶档验收见程序员进阶版模块 A2 与附录 B。
学后自测
1. 一次 Agent Run 里，上下文里的哪些部分是每一步都要重发的？可以怎么省？
System Instructions 和工具定义每步都发，这部分适合用 Prompt Caching 省钱。历史消息随步数线性增长，这部分要靠预算裁剪。能算清楚一次十步的 Run 里 Token 是怎么分布的，你就知道优化该往哪使劲。
2. 用户删除了一份文档，你的系统要级联删除哪些数据？
Chunk、向量索引、BM25 索引、缓存、以及引用了这份文档的历史回答里的溯源链接。最容易漏的是向量库里的记录和缓存，导致文档删了但还能被检索出来。这在合规场景是硬伤，用户有删除权。
3. 你的 Chunk 元数据里有哪些字段？少了哪个会让权限过滤失效？
最小集：document_id、tenant_id、source_url、version、chunk_index、parent_id、created_at。少了 tenant_id 就无法在检索时做租户隔离，会导致跨租户数据泄漏，这是最严重的一类事故。
本周作业
packages/context-engine/：上下文组装、预算、transformpackages/session/：基本 Session Logpackages/prompt-registry/：版本、变量 Schema、发布与回滚packages/rag-pipeline/：Upload 到 Index 全链路，支持四种格式docs/chunking-experiment.md：动手挑战的对照实验报告
面试考点
这一周对应面试里的上下文工程考察，是近两年新增的高频区。
- 「上下文窗口不够用了怎么办？」：分三层答：先做检索而不是全塞（RAG）、再做预算裁剪按重要性排序、最后才是压缩摘要。压缩是最后手段因为它有信息损失。
- 「你怎么控制 RAG 的成本？」：答 Chunk 尺寸和返回数量的取舍，最好能报出你实验里的具体数字。有数据的回答和没数据的回答不是一个层级。
- 「Prompt 改了怎么保证不出事？」：答 Prompt Registry 加评测门禁加版本回滚。这个问题在有真实线上业务的团队面试里几乎必问，因为他们踩过坑。
- 「文档更新了知识库怎么同步？」：答 Content Hash 加增量重建加级联删除。顺带提用户删除权，展示合规意识。
- 陷阱题：「直接把整个文档塞进长上下文，是不是就不需要 RAG 了？」答成本、延迟和 Lost-in-the-middle 三点，同时承认在小文档场景下确实可以，不要绝对化。
复习与延伸
官方文档与论文
起手代码（测试即规格）
examples/week-05/ 是这一周的练习仓，25 条测试。
pnpm --filter @agent-os/example-week-05 test最容易漏的一条：删除文档要连 contentHash 记录一起清。只删 Chunk 不删记录的话，用户删完再上传同一份文档会被去重短路，永远传不进去。
本仓库对应源码
packages/contracts/src/session.ts：Session 事件契约packages/rag-kit/src/vector-store.ts：最小向量库实现，第 6 周会在此基础上扩展