透明代理定位与八步管道全景

透明代理定位与八步管道全景

本节摘要:第 8 章是全书最硬核的第二章,本节先立全景——MemoryProxy 这个透明代理的定位,以及它处理一次请求的八步管道。代理层的精髓不在「做了八件事」,而在「让 Agent 一行代码都不用改」:你只改一行 baseURL,Agent 的所有流量就被导向代理,代理在转发给真正 LLM 的前后做八步处理。本节讲清「透明」二字的工程含义、八步如何串成「准备→执行→收尾」的流水线、以及为什么是这个顺序。

一、透明代理:「零改造接入」的工程含义

「透明」是代理层的核心定位——它对 Agent 是「不可见」的,Agent 以为自己在和真正的 LLM 对话:

没有代理层(传统)
  Agent ──请求──▶ 真正的 LLM
  (Agent 要自己实现记忆逻辑,改代码)

有代理层(透明)
  Agent ──请求──▶ 代理层 ──(夹带记忆)──▶ 真正的 LLM
  (Agent 不改代码,只改 baseURL 指向代理)
​

关键概念:「透明」的本质是「反向托管」——代理层接管了 Agent 与 LLM 之间的通路,在通路上夹带记忆能力,而 Agent 浑然不觉。这与第 9 章 SDK 的「正向集成」(Agent 主动调记忆 API)形成对比。两条路殊途同归,但代理层让「不可能改源码的成熟 Agent」也能拥有记忆。

二、八步管道:准备 → 执行 → 收尾

代理层处理一次请求,做八步处理,天然分三段:

八步管道(三段)
  ┌─── 准备段(0→4):让请求带上记忆 ───┐
  │ 1.auth        验证密钥换 user_id
  │ 2.systemUser  解析系统用户
  │ 3.sessionInit 确定team/agent/task
  │ 4.injection   注入记忆(inject/toolize)
  └──────────────────────────────────┘
  ┌─── 执行段(5→6):转发并限流 ───────┐
  │ 5.rateLimit   TPM/QPM 滑窗检查
  │ 6.forward     转发给真正的 LLM
  └──────────────────────────────────┘
  ┌─── 收尾段(7→8):回写并上报 ───────┐
  │ 7.extract     把对话回写(沉淀记忆)
  │ 8.report      上报可观测数据
  └──────────────────────────────────┘
​

三、为什么是这个顺序:依赖关系决定

八步的顺序不是随意的,每一步依赖前一步的产物:

顺序的依赖逻辑
  auth(1) → 产出 user_id
    ↓ (没 user_id 无法做后续)
  systemUser(2) → 解析系统用户身份
    ↓ (没身份无法确定范围)
  sessionInit(3) → 确定 team/agent/task
    ↓ (没三元组无法装配过滤、召回无的放矢)
  injection(4) → 按范围召回并注入记忆
    ↓ (注入完成才能转发)
  rateLimit(5) → 限流检查
    ↓ (过了限流才转发)
  forward(6) → 转发 LLM,拿答复
    ↓ (有答复才能回写)
  extract(7) → 回写对话
    ↓ (回写完才能上报)
  report(8) → 上报可观测
​

💡 技巧:理解八步顺序,抓「每步产出什么、下一步需要什么」。auth 产出身份、sessionInit 产出范围、injection 产出注入后的请求、forward 产出答复、extract 产出记忆。这是一条「产出-消费」链,顺序由依赖决定,不可随意调换。

四、准备段的「夹带」:请求在被转发前已被改造

准备段(1-4)最关键的认知:Agent 发来的请求,在被转发给 LLM 之前,已经被代理层「夹带」改造过了:

准备段的改造
  Agent 原始请求
    └─ system prompt: "你是助手..."
    
  经过准备段后(被夹带)
    └─ system prompt: "你是助手...
                       [inject 的 persona/scene/skill]
                       [inject 的团队约定]
                       [toolize 暴露的知识工具说明]"
    
  → LLM 收到的是「已注入记忆」的请求,不是原始请求
​

LLM 根本不知道这些记忆是「代理夹带」的——它以为这就是完整的请求。这种「透明夹带」让 Agent 无需任何改造就获得了记忆能力。第 3 节会详解 injection 的 inject/toolize 双策略。

五、收尾段的「沉淀」:答复之后记忆在生长

收尾段(7-8)同样关键——用户拿到答复走了,但代理层还在工作:

收尾段的沉淀
  forward(6) 返回答复 → Agent 拿到答复(用户走了)
    ↓ (但代理层不闲着)
  extract(7):把这次对话回写给核心服务
    → 触发 L0 录制 + 异步抽取 Pipeline(第6章)
    → 这次对话成为下次可召回的记忆
  report(8):上报可观测数据
    → 链路/成本/质量三路观测(第12章)
​

⚠️ 注意:extract 是「记忆生长的入口」——没有它,系统只消耗记忆不产生记忆,越用越空。这就是第 2 章强调「回写不是可选」的原因。代理层把 extract 和 forward 放在同等地位,正是因为「记忆复利」依赖回写。

本节要点回顾

1. 透明=零改造:代理反向托管通路,Agent 只改 baseURL;与 SDK 正向集成形成对比。
2. 八步三段:准备(1-4 带记忆)→ 执行(5-6 限流转发)→ 收尾(7-8 回写上报)。
3. 顺序由依赖定:auth 产身份→sessionInit 产范围→injection 注入→forward 转发→extract 回写,产出-消费链。
4. 准备段夹带:请求转发前已被注入记忆,LLM 收到的是「已夹带」的请求,不知情。
5. 收尾段沉淀:extract 是记忆生长入口,没有它系统越用越空——回写不是可选。

全景已立,下一节深入准备段前三步——auth + systemUser + sessionInit,看身份与场景如何被确定。