7.2 完整案例：一个客服 Agent 的上下文设计

7.2 完整案例：一个客服 Agent 的上下文设计

本节摘要：全书收官。用前六章的全部工具，为一个场景做一次从零到装配图的完整设计：电商退款客服 Agent，128k 窗口，带政策知识库、15 个候选工具、跨会话记忆与长尾 40+ 轮会话。流程是逐层合奏——指令层：3.1 节四块模板 + 引用契约与兜底，实测 1.6k token；工具层：3.2 节审计把 15 个精简合并到 9 个，常驻税从示意估值落到实测 2k；记忆层：三层分工（4.1）——会话历史占 14%、跨会话召回限 3.8k 且过写入门槛（4.2）、知识库不入记忆只走检索；素材层：政策检索 top-4 由预算倒推（5.1），选摆标束四道工序（5.2）；运维层：水位 80% 先驱逐、驱逐后仍超压成五栏简报（6.1），每轮落快照与组合版本号（6.2）。合成的产物是三件：一张各成分合计 100% 的预算总表、一张按位置效应落位的最终装配图、一份收工自查清单。设计流程本身就是全书的目录——每一层都标注了它回收的是哪一节。

学习目标

阅读完本节，你应当能够：

1. 按十步流程为一个真实 Agent 做完整的上下文设计。
2. 逐层给预算并用 ce_tools.py / ce_budget.py 把示意值落实测值。
3. 画出一张按位置效应落位的最终装配图。
4. 用收工自查清单验收设计（十项全过才算完）。

一、需求与约束

场景：某电商退款客服 Agent（承接 0.1 / 3.1 节的同一案例，现在把它做完整）。

设计输入就是前六章的六张表：四成分表（1.2）、分配与驱逐表（2.1）、位置模板（2.2）、系统提示模板（3.1）、工具三层写法（3.2）、三层记忆图（4.1）加写入门槛（4.2）、组装四工序（5.2）、压缩清单（6.1）与快照结构（6.2）。

二、指令层（回收 3.1 节）

直接套四块模板（3.1 节已有全文，此处只记增量）：角色与边界照搬；工具块按精简后的 9 个工具重写用法说明（先 search_user 还是先 get_order 的取舍规则写在这里）；输出契约追加 5.2 节的引用三条（事实带 [n]、编号可校验、无依据即声明）。实测长度：

角色 120 tok ＋ 边界 380 tok ＋ 工具用法 520 tok ＋ 输出契约与引用规则 310 tok
＋ 记忆区块说明 90 tok ＋ few-shot 2 例 220 tok ＝ 约 1.6k（实测口径示意）
​

管理照 3.1 节纪律：唯一真相源 prompts/refund_agent/v13.md，变更过 20 条评测集。

三、工具层（回收 3.2 节）

拿 ce_tools.py 审计 15 个候选：三个查单工具（search_orders / query_order / find_recent_orders）语义重叠，合并为一个带过滤参数的 search_orders；两个半年零调用的僵尸工具砍掉；analyze_logs 保留但标记为重活候选（子 Agent 外包，3.2 节第三招）。15 → 9 个，常驻税实测约 2k token（示意；用自家 schema 跑 tool_tax 落实数）。2.1 节分配表当初按 10% 保守估值——审计的意义正是把示意变成实测：省下的约 8% 额度，第七节重新分配。

四、记忆层（回收第 4 章）

按三层地图分工（4.1）：

• 会话内：历史全量保留，配额 14%（约 18k，够 40 轮上下的中等密度对话，示意）；驱逐顺序定制为——陈旧政策片段 → 已完结工单的过程历史 → 早期寒暄 → 可重取的订单快照（2.1 四顺位的应用版）；pinned 四项 + 最近 4 轮永不丢。
• 跨会话：召回限 3.8k（3%，ce_memory.py 的 RECALL_BUDGET）；写入走门槛三问，只收偏好 / 事实 / 约定三类；注入系统提示后的记忆区块，带时间戳（4.2）。
• 知识库：政策与 FAQ 不入跨会话记忆（4.1 事故一），只作为检索源——下一层的事。

五、素材层（回收第 5 章）

• 检索：查询用本轮问题构造；top-k 由预算倒推——素材配额 45%（约 57k）扣除工具结果预留（单轮 2k~4k）后，单轮政策检索取 top-4 × 0.5k，分数阈值以下的宁可不取（5.1 / 5.2）。
• 组装：块内保原序（政策条文顺序不能打乱，引用语义依赖它），块间按相关性——最相关片段 [1] 放窗口头部、次佳 [4] 放尾部（2.2 推论一）；每段带编号、来源（文档 + 条号 + 版本）、双时间戳（5.2 第三节模板）。
• 约束：输出契约的引用三条（第二节已并入）；检索为空 → "未找到政策依据"兜底；机器校验输出中 [n] ⊆ 本轮注入集合（5.2 第四节）。

六、运维层（回收第 6 章）

• 水位线：总用量达可用额度 80%（示意）→ 先驱逐；驱逐后仍超 → 压缩成五栏任务简报（6.1），近 4 轮保原文，简报落位窗口前部；原文 offload 到会话存储可回查。
• 快照：每轮组装后落 ce_snapshot.py 结构；组合版本号 prompt v13 × assembler v4 × memory v2 × retrieval v6，任一变更过评测（6.2）。
• 指标：用量曲线、驱逐计数、素材命中率（引用编号实际被使用的比例）三项接告警。

七、预算总表（最终合成）

合计 100%。对比 2.1 节的初始示意表，三处变化都有出处：工具 10%→2%（第三节的审计）、素材 42%→45% 与机动 5%→14.5%（省下的额度再分配——审计省的钱要花在明处）。

八、最终装配图

128k 窗口的落位（按 2.2 位置模板具体化，token 为典型轮示意）：

[窗口头部 ~9k]  系统提示 v13（指令，1.6k）── 四块模板 + 引用契约
                记忆区块（3.8k）── 跨会话召回，带时间戳与类型
                任务简报（触发压缩后出现，~1.5k）── 五栏，高熵靠前
                最佳检索片段 [1]（0.5k）
[窗口中部 ~20k] 会话历史（近 4~40 轮；压缩后 = 简报 + 近 4 轮原文）
                中等相关片段 [2][3]、政策背景等低熵素材
                工具结果（订单 JSON，已按决策字段裁剪）
[窗口尾部 ~1k]  次佳检索片段 [4]
                关键约束复述：先查单 → 再引政策 [n] → 禁政策外承诺
                本轮用户输入
[工具区 2.0k]   9 个 schema（API 自动注入，紧邻系统提示）
[输出预留 26k]  模型生成空间（不可侵占）
​

对着 2.2 节的两条推论各检查一次：高熵内容（简报、最佳片段、约束复述、用户输入）全部落在首尾；中部是历史与低熵背景。装配图贴在团队墙上，比十页文档都管用。

九、运行时事件流

十、收工自查清单

• 三问归位：窗口每段内容都能报出成分（1.2）
• 预算恒等式：各科目合计 100%，输出预留未被侵占（1.1 / 2.1）
• 常驻税实测：ce_tools.py 跑过，工具集评审留痕（3.2）
• 驱逐顺序成文 + pinned 四项 + 最近 K 轮保护（2.1）
• 位置：高熵内容在首尾，中部无关键事实（2.2）
• 记忆三层分工清楚，写入过门槛三问，召回带预算（4.1 / 4.2）
• 检索 k 由预算倒推，片段带编号来源时间戳（5.1 / 5.2）
• 引用契约可机器校验，空检索有兜底（5.2）
• 压缩触发线、五栏简报、禁区清单齐备（6.1）
• 每轮快照 + 组合版本号 + 变更过评测（6.2 / 3.1）

十项全过，这套上下文设计才算收工——缺任何一项，都能在前六章找到对应的翻车案例。

本节要点回顾

1. 设计流程 = 全书目录：指令（3.1）→ 工具（3.2）→ 记忆（4.1 / 4.2）→ 素材（5.1 / 5.2）→ 运维（6.1 / 6.2）→ 合成预算总表与装配图。
2. 示意值要落实测值：15→9 个工具、常驻税 10%→2%——审计省下的额度重新分配到素材与机动，且花在明处。
3. 最终产物三件：合计 100% 的预算总表、按位置效应落位的装配图、十项收工清单。
4. 事件流是设计的行为验证：正常轮、超预算轮、压缩轮、检索轮各有明确的系统动作与快照签名。
5. 每个数字都可追溯：表里每个值都标着它来自哪一节——这是"体系"区别于"技巧合集"的样子。

至此全书正文完结。四成分给你分类的语言，预算恒等式给你算账的框架，驱逐与位置给你装配的算法，记忆 / 检索 / 压缩给你动态层的三件工具，快照与版本给你运维的证据链，框架映射让你在任何生态里对号入座。接下来去附录 A 查术语、附录 B 选工具，然后做附录 C 的第 8 题——为你自己的应用，画一张属于自己的装配图。