Memory on 男娘教主

LangChain_Memory

Tue, 25 Aug 2026 07:44:10 +0800

辛辛苦苦写的 MemoryManager（短期窗口 + 长期 Chroma + 滚动压缩），它的 get_context() 返回的是一串 dict 消息。而 LangChain 的 prompt 里 ("placeholder", "{history}") 需要的，是 BaseMessage 对象（HumanMessage / AIMessage / SystemMessage）。

这中间隔着一层「格式不对」——dict 直接喂进去，prompt 展开不了，链就哑火。

D3 要做的，就是补上这层转换，让「取记忆」成为链的头一个环节。而补这层只需要三件东西，刚好对应你给的 lc_memory.py 里「入口适配层」的三大件：

_to_lc = 把 dict 翻成 LangChain 消息对象（格式转换器）
lambda = 一次性匿名函数 + 字典解包（在链首「加料」）
RunnableLambda = 把函数包成能入 | 管道的零件（适配器）

一句话：W3 的决策逻辑一行不改，只在外面套一层「适配器」，就能进 LangChain 的链。 这和你 W3 博客里说的「最小侵入」是一回事。

一、大局：记忆接在链的哪个位置

先看整条链的数据流向——记忆是「链首的第一道工序」：

1
2
3
4
5
6
7


用户输入 {"question": "我叫什么？"}
 ↓
load_mem (RunnableLambda) ← ① 给输入"加料"：补上 history 字段
 ↓
prompt (ChatPromptTemplate) ← ② {history} 和 {question} 这下都有值了
 ↓
model → parser ← ③ 生成回答

拆开看三大件各自在哪、干嘛：

部件	角色	一句话
`_to_lc(m: dict)`	格式转换器	dict 消息 → LangChain `BaseMessage` 对象
`lambda x: {...}`	一次性函数	在链首把 `history` 字段「加」进输入
`RunnableLambda(...)`	适配器	把上面的函数包成能进 `

接下来逐个拆。

二、`_to_lc`：dict → LangChain 消息对象（快递打包）

一句话：把「散装 dict 消息」翻译成「LangChain 标准消息对象」。

你的 MemoryManager.get_context() 返回的是普通 dict 列表：

1
2


[{"role": "user", "content": "我叫小明"},
 {"role": "assistant", "content": "你好小明"}]

但 LangChain 的 prompt 里 ("placeholder", "{history}") 需要的是消息对象，不是 dict。所以必须转换：

1
2
3
4
5
6
7


def _to_lc(m: dict):
 role, content = m.get("role", "user"), m.get("content", "") # 取出角色和内容，role 缺省默认 user
 if role == "system":
 return SystemMessage(content=content) # system → SystemMessage
 if role == "assistant":
 return AIMessage(content=content) # assistant → AIMessage
 return HumanMessage(content=content) # 其他（user）→ HumanMessage

类比：快递打包。你的记忆模块产出的是「散装货物」（dict：一张纸写着「谁说的 + 说了啥」），而 LangChain 的传送带只认「标准包装箱」（BaseMessage 对象）。_to_lc 就是打包员——按「谁说的」（role）选不同规格的箱子（Human/AI/System），把货装进去。

为什么 m.get("role", "user") 要带默认值？ 因为 get 是「有就拿，没有给默认」——万一某条消息漏写了 role，就按用户消息处理，不崩。这是防御性写法，跟你在 auto_select / MemoryManager 里用的「宽容解析」一个思路。

对照自研：你 W3 写 compress.py 时，把消息喂给 LLM 做摘要前，其实也隐含了这一层「dict → 文本」的转换（你当时用了 _fmt 拍平成纯文本）。只不过 LangChain 这边的「标准箱」是对象而不是字符串——道理一样：框架要的是它认得的格式，你得先把货装进它的箱子。

三、`lambda` 表达式 + 字典解包（链首加料）

lambda = 一次性匿名函数。语法只有一句话：lambda 参数: 返回值表达式。

1
2
3
4
5
6
7


# 你的代码里：
lambda x: {**x, "history": get_history(x)}
# ↑参数 ↑ 返回表达式（一个字典）

# 它等价于这个 def：
def 匿名函数(x):
 return {**x, "history": get_history(x)}

类比：便利贴 vs 正式文件。def 是正式文件（有名字、能反复用）；lambda 是便利贴——写完就用、用完就扔，适合「只在这一个地方用一次」的小函数。

为什么用 lambda 而不是 def？ 因为 RunnableLambda 只需要一个「输入→输出」的函数，而这个函数只在这一行用一次，没必要单独起个名字占地方。

{**x, "history": ...} 字典解包是什么？ **x 是把字典 x 的所有键值对「展开」，然后放进一个新字典：

1
2
3
4


x = {"question": "我叫什么？"}

{**x, "history": ["..."]}
# 展开 x → {"question": "我叫什么？", "history": ["..."]}

为什么不直接写 x["history"] = ...？ 因为那会修改原字典（副作用）。链式调用里要保持「纯函数」——输入不被改动，只产出新结果。{**x, ...} 是复制一份再追加，原输入 x 完好无损。

类比：复印并加批注——原文件不动，复印件上多了一行批注。这正是 D2 学的 RunnablePassthrough.assign 干的事，这里用字典解包手动实现了一遍。

所以这一行 lambda x: {**x, "history": get_history(x)} 的含义就是：拿到用户的 {"question": ...}，复印一份，再往里塞一个 history 字段（内容是记忆系统的召回结果），原样返回给下一个环节。

四、`RunnableLambda`：把函数变成能入链的零件（插头转换器）

一句话：把普通 Python 函数包装成「能参与 | 管道的零件」。

LangChain 的 | 传送带有规矩：每个零件都必须实现 Runnable 协议（有 invoke / stream / batch 方法）。你的 get_history() 是普通函数，没有这些方法，直接放管道里会崩：

1
2
3
4
5
6


# ❌ 直接放普通函数：
chain = get_history | prompt | model | parser # 报错：get_history 不是 Runnable

# ✅ 包一层 RunnableLambda：
load_mem = RunnableLambda(get_history)
chain = load_mem | prompt | model | parser # 能跑！

类比：插头转换器。你的函数是「两脚插头」（普通函数），LangChain 的管道是「三脚插座」（Runnable 协议）——直接插不进去，套个转换器（RunnableLambda）就通了。

这你其实在 D2 步骤 E 已经亲手跑过：RunnableLambda(TextCleansing)——当时是给链尾加了个「清洗加工站」，现在是给链首加了个「加载历史加工站」，同一个东西，位置不同。所以 D3 的桥，D2 就已经修好了，你只是把它从链尾挪到了链首。

⚠️ 类型对接（跟 D2 踩坑记④一致）：RunnableLambda 收到的是管道里上一个的输出类型。这里 load_mem 是链首，它收到的是你 .invoke({"question": ...}) 传进去的 dict，所以 lambda x 的参数 x 是 dict，x.get("question") 才对得上。如果上一个产出是 str，参数就得是 str。

五、完整可运行演示（不需要 API key）

先跑这个，把三个概念一次看懂——它不调模型，纯演示「转换 + 加料 + 入链」：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


# concepts_demo.py —— 三个概念一次看懂（无需 API key）
from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
from langchain_core.runnables import RunnableLambda

# ---------- 1. _to_lc：dict → 消息对象 ----------
def _to_lc(m: dict):
 role, content = m.get("role", "user"), m.get("content", "")
 if role == "system":
 return SystemMessage(content=content)
 if role == "assistant":
 return AIMessage(content=content)
 return HumanMessage(content=content)

raw = [{"role": "user", "content": "我叫小明"},
 {"role": "assistant", "content": "你好小明"}]
msgs = [_to_lc(r) for r in raw]
for m in msgs:
 print(type(m).__name__, "→", m.content)
# HumanMessage → 我叫小明
# AIMessage → 你好小明

# ---------- 2. lambda 语法 ----------
f = lambda x: x + "！" # lambda 参数: 返回表达式
def f_def(x): return x + "！" # 等价 def
print(f("你好"), "==", f_def("你好")) # 你好！ == 你好！

# ---------- 3. RunnableLambda + 字典解包 ----------
def get_history(x):
 return [_to_lc(r) for r in raw] # 返回消息对象列表（就是 _to_lc 的用武之地）

load_mem = RunnableLambda(lambda x: {**x, "history": get_history(x)})

result = load_mem.invoke({"question": "我叫什么？"})
print(result.keys()) # dict_keys(['question', 'history'])
print(result["history"]) # [HumanMessage, AIMessage] —— prompt 的 {history} 就能展开了

跑一下，你会看到：lambda 收到 {"question": ...}，返回一个新字典，原字段保留、history 字段追加——然后 prompt 里的 {question} 和 {history} 就都有值了。

六、`lc_memory.py` 完整代码（真实接 MemoryManager）

下面是把 W3 的 MemoryManager 真正接进链的版本。get_history 调的是 _mm.get_context(query=...)（带长期召回），_to_lc 负责格式转换，load_mem 用 RunnableLambda 包起来放到链首：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83


# lc_memory.py —— W3 MemoryManager 接进 LCEL 链（入口适配层）
import os
from dotenv import load_dotenv
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser
from langchain_core.runnables import RunnableLambda
from langchain_core.messages import SystemMessage, HumanMessage, AIMessage

load_dotenv()

# 桥的包装器：dict 消息 → LangChain BaseMessage
def _to_lc(m: dict):
 role, content = m.get("role", "user"), m.get("content", "")
 if role == "system":
 return SystemMessage(content=content)
 if role == "assistant":
 return AIMessage(content=content)
 return HumanMessage(content=content)

# 接入 W3 自研 MemoryManager（失败则降级最小窗口版）
# ⚠️ 注意：直接 `python lc_memory.py` 运行时，下面这行相对导入会找不到包——
# 因为直接运行脚本时 Python 把它当顶层模块，无法解析 "..memory" 这类上级路径。
# 正确做法（二选一）：
# 1) 把项目根目录加入 sys.path 再用绝对导入（见下方注释）；
# 2) 用 `python -m 包名.模块名` 启动，而非直接执行脚本文件。
try:
 from memory.memory_manager import MemoryManager
 _mm = MemoryManager(window=6, max_tokens=500)
 def get_history(x):
 # 真实版：query=本轮问题 → 长期召回 + 滚动窗口
 return [_to_lc(m) for m in _mm.get_context(query=x.get("question"))]
except Exception as e:
 print(f"[降级]未找到memory包({e}),使用最小窗口版")
 class _MinilMM:
 def __init__(self, window=6):
 self.buf, self.window = [], window
 def get_context(self, query=None):
 return self.buf[-self.window:]
 def add_user(self, t):
 return self.buf.append({"role": "user", "content": t})
 def add_ai(self, t):
 self.buf.append({"role": "assistant", "content": t})
 _mm = _MinilMM()
 def get_history(x):
 return [_to_lc(m) for m in _mm.get_context()]

# 链：链首选历史，再 prompt | model | parser
model = ChatOpenAI(
 model="deepseek-v4-flash",
 api_key=os.getenv("DEEPSEEK_API_KEY"),
 base_url="https://api.deepseek.com",
)

prompt = ChatPromptTemplate.from_messages([
 ("system", "你是一个有记忆的助手，记得之前聊过的内容。"),
 ("placeholder", "{history}"), # 关键：展开历史 messages
 ("human", "{question}"),
])

load_mem = RunnableLambda(lambda x: {**x, "history": get_history(x)})
chain = load_mem | prompt | model | StrOutputParser()

def ask(question: str) -> str:
 ans = chain.invoke({"question": question})
 if hasattr(_mm, "add_user"):
 _mm.add_user(question); _mm.add_ai(ans)
 else:
 _mm.add({"role": "user", "content": question})
 _mm.add({"role": "assistant", "content": ans})
 return ans

if __name__ == "__main__":
 # 验收：第 2、3 问能答出「篮球」「小明」=> 记忆生效
 for q in ["我叫小明，喜欢打篮球", "我刚说的爱好是什么？", "我名字叫什么？"]:
 print(f"Q: {q}\nA: {ask(q)}\n")

 # 确认 load_mem 在链首 + 看历史在累积
 print("=== 链结构图（load_mem 应排最前）===")
 chain.get_graph().print_ascii()
 print("=== 当前记忆历史 ===")
 for m in _mm.get_context():
 print(f" {m.get('role')}: {m.get('content')}")

("placeholder", "{history}") 是 LangChain 专门用来「展开一个消息列表」的占位符——它和 ("human", "{question}") 不同：后者填的是字符串，前者填的是消息对象列表，会被逐条展开成多轮对话历史。这就是 _to_lc 存在的意义。

七、踩坑记 & 知识点

① 相对导入在「直接运行脚本」时会炸 from memory.memory_manager import MemoryManager 只在「包上下文」里成立。你 python lc_memory.py 直接跑，Python 把文件当顶层脚本，__package__ 为空，解析不了 ..memory 这种上级路径，就抛 ModuleNotFoundError。

两种修法（二选一）：

加 sys.path 补丁：在导入前把项目根目录塞进 sys.path，再绝对导入（注释里写了模板）；
用 -m 启动：cd 到 AgentLearn\ 后 python -m memory.lc_memory（或对应包路径），Python 基于 cwd 找顶层包，自然能 import。

我上面的代码用 try/except 做了优雅降级——找不到真实 MemoryManager 就退回到一个最小窗口版，保证链一定能跑通、你能先看效果。但生产里你还是得用上面两种修法之一把真实版接上。

② placeholder 占位符要配「消息对象列表」，不是字符串 {history} 用 ("placeholder", ...) 声明，传进去的必须是 [HumanMessage, AIMessage, ...] 这种列表。如果你直接传字符串，LangChain 会不知道怎么展开。所以 _to_lc 把 dict 翻成对象这步，不能省。

③ lambda 里用 {**x, ...} 而不是 x["k"]=...（纯函数） 前面讲过：前者复制一份再追加，原输入不动；后者直接改原 dict，会在链式调用里留下副作用，导致后面环节拿到被偷偷改过的输入，极难排查。进 | 管道的函数，尽量写成纯函数。

④ RunnableLambda 的「输入输出类型」要对接上一个 Runnable load_mem 是链首，收到的是你 .invoke({"question": ...}) 传的 dict，所以 lambda x 里 x 是 dict、x.get("question") 对得上。若把 load_mem 挪到链中间（比如接在 prompt 后面），它收到的就会是 prompt 的输出了——类型全变，得重写函数。改完链先 get_graph().print_ascii() 看一眼流向（跟 D1/D2 踩坑记一脉相承）。

⑤ _mm.add_user / add_ai 是降级版的「自造」方法 真实 MemoryManager 的接口是 add({"role":..., "content":...})（你 W5 博客里写过）。降级类 _MinilMM 是我手写的最小版，用了 add_user/add_ai 方便演示——所以 ask() 里用 hasattr(_mm, "add_user") 来区分「降级版」和「真实版」，分别走不同写入路径。这提醒你：接第三方/自研模块时，先确认它的真实接口长啥样，别凭想象调方法。

八、总结

今天把 W3 的 MemoryManager 接进了 LangChain 链，靠的是「入口适配层三件套」——而且 W3 的决策逻辑一行没改，只是外面套了层适配器：

_to_lc = 格式转换器（dict → BaseMessage），快递打包员：按 role 选箱子
lambda + {**x, ...} = 链首加料（保留原输入 + 追加 history），便利贴 + 复印加批注
RunnableLambda = 适配器（普通函数 → 能进 | 管道），插头转换器：D2 的加工站从链尾挪到了链首

整条链：load_mem | prompt | model | parser——记忆从此成为「链的首道工序」，而不是链外的黑盒。

这印证了你 W3 博客那句结论：「最小侵入」——框架化不是重写逻辑，是把旧轮子套上标准接口。 你前三周手写的所有零件，到 W4 一个个「认领」进 LangChain，没有任何一个被推倒重来。

九、下一篇预告

D4：把 Retriever / RAG 也接进链（长期记忆的「知识版」）

今天接的是「对话记忆」（短期窗口 + 你手动落的事实）。但 W3 你还有一个更重的资产——Chroma 长期向量记忆，那东西在 LangChain 里叫 Retriever。

D4 要做的，是把 MemoryManager 里「长期召回」那部分，用 LangChain 的 Retriever 标准接口重写一遍——让你 W3 手写的向量召回，变成 chain 里的一环。而「对话记忆」和「知识召回」这两种 history，会在链首被 RunnableParallel / assign 一起拼进 prompt。

再往后，W5 LangGraph 会把今天这条「线性带记忆的链」升级成「有状态图」：每个零件变成 node，MemoryManager 变成图里一个会读写状态的节点。你 W4 这四天铺的路，正好接上 W5 的 node/edge。

一句话收尾：D1-D3 你学会了「零件怎么串、函数怎么进链、记忆怎么接入」；D4 补上「知识怎么召回」，W5 就轮到「流程怎么分叉」。

一二周整理

Fri, 21 Aug 2026 12:49:45 +0800

我一直想要一个这样的 Agent：

能记住：上一轮你说的话、你长期透露的偏好，它都记得；
会办事：能查天气、算算术、把你的偏好存进"长期记忆"里；
能换脑子：同一个问题，可以用思维链(CoT)慢慢推、用少样本(Few-shot)学样子、用 ReAct 调工具、用 Tree-of-Thought 多方案权衡。

D:\agent_project 就是这么一个东西。它不大，但把 Agent 工程里最该懂的几块都拆开了：LLM 层 / 记忆层 / 工具层 / Agent 层，外加一个 agent/main.py 把它们粘起来。

这篇文章把每个模块的作用、知识点、源码都摊开讲。你照着读一遍，基本就能自己复刻一个。

一、项目全景：四层 + 一个组装口

先看整体骨架。agent_project 的目录长这样：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


D:\agent_project\
├── agent\ # Agent 层：调度大脑
│ ├── __init__.py # 暴露 fc_loop / auto_select 等入口
│ ├── main.py # 组装所有层 + 交互循环
│ ├── core.py # Function Calling 主循环 fc_loop
│ ├── router.py # 选模型 + 选推理模式
│ └── modes\ # 四种推理模式
│ ├── cot.py # 思维链
│ ├── few_shot.py # 少样本
│ ├── react.py # 工具调用
│ └── tot.py # 树状思维
├── llm\ # LLM 层：模型抽象与封装
│ ├── base.py # 抽象接口 + 配置读取
│ ├── real_llm.py # 非流式客户端（带 .env + summarize）
│ └── stream_llm.py # 流式客户端
├── memory\ # 记忆层：短期 + 长期 + 压缩
│ ├── paths.py # 落盘路径集中管理
│ ├── shortmemory.py # 短期滑动窗口
│ ├── long_term.py # 长期向量库（Chroma）
│ ├── compress.py # 滚动摘要压缩
│ └── memory_manager.py # 统一调度者
├── tools\ # 工具层：工具定义 + 注册 + 执行
│ ├── base.py # 工具基类
│ ├── registry.py # 动态注册表
│ ├── executor.py # 带"自愈"的执行器
│ ├── weather.py # 查天气
│ ├── calculator.py # 计算器
│ ├── save_preference.py# 存长期偏好
│ └── recall_memory.py # 召回长期记忆
├── config.json # providers + tools 清单
└── .env # 密钥（不进 git）

用一张图把数据流说清楚：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


 用户输入 "你: ..."
 │
 ▼
 ┌─────────────────────────────────────────────┐
 │ agent/main.py (组装口) │
 │ 1. mm.add(user_msg, persist=是否长期事实) │
 │ 2. ctx = mm.get_context(query=用户问题) │
 │ 3. out = fc_loop(llm, ctx, registry, executor)│
 │ 4. mm.add(assistant_msg) │
 │ 5. mm.maybe_compress() ← 超阈值才压缩 │
 └───────────────────────┬─────────────────────┘
 │
 ┌───────────────────┼───────────────────┐
 ▼ ▼ ▼
 ┌──────────┐ ┌──────────────┐ ┌─────────────┐
 │ 记忆层 │ │ Agent 层 │ │ 工具层 │
 │ Memory │◄──────┤ fc_loop 循环 │───►│ 调 get_weather│
 │ Manager │ │ router 选模式 │ │ 调 calculator│
 └────┬─────┘ └──────┬───────┘ └──────┬──────┘
 │ │ │
 ▼ ▼ ▼
 短期窗口 + 长期向量库 RealLLM / StreamLLM 依赖注入 mm
 │ (LLM 层) (MemoryManager)
 └──────────────────────────────────────────┘

铁律 1：分层不是为了好看，是为了"换一层不影响其他层"。模型从 DeepSeek 换成 Kimi，只动 config.json；加一个新工具，只写一个 tools/xxx.py 再往 config.json 加一行——这就是分层架构的回报。

二、LLM 层：把"模型"抽象成可替换的零件

这一层解决两件事：① 统一接口，让上层不关心背后是哪家模型；② 配置与代码分离，密钥放 .env，模型地址放 config.json。

2.1 抽象基类 `llm/base.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


# llm/base.py —— LLM 抽象接口
from pathlib import Path
import json

# 配置路径：从"llm/ 的上级目录"找 config.json
CONFIG_PATH = Path(__file__).resolve().parent.parent / "config.json"

def load_provider_config(provider: str) -> dict:
 with open(CONFIG_PATH, encoding="utf-8") as f:
 return json.load(f)["providers"][provider]

class LLMClient:
 def chat(self, messages, tools=None):
 raise NotImplementedError("子类必须实现 chat()")
 def chat_stream(self, messages, **kwargs):
 raise NotImplementedError("子类必须实现 chat_stream()")

知识点补充：load_provider_config 拿到的 CONFIG_PATH 用的是 Path(__file__).resolve().parent.parent——这是"相对模块自身位置找文件"的写法，比 open("config.json") 稳，因为你从哪个目录运行脚本，__file__ 都在，而当前工作目录 cwd 会漂。

2.2 非流式客户端 `llm/real_llm.py`

这是项目的主力客户端（main.py 用的就是它）。它比基类多了两件关键事：读 .env 和 summarize 方法（记忆压缩要用）。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


# llm/real_llm.py —— 非流式客户端
import os
from pathlib import Path
from openai import OpenAI
from dotenv import load_dotenv
from .base import LLMClient, load_provider_config

# 加载项目根目录的 .env（让 DEEPSEEK_API_KEY 等从文件读取，优先级高于系统环境变量）
load_dotenv(Path(__file__).resolve().parent.parent / ".env", override=True)

class RealLLM(LLMClient):
 def __init__(self, provider="deepseek"):
 cfg = load_provider_config(provider) # 从 config.json 读
 self.client = OpenAI(api_key=os.getenv(cfg["key_env"]),
 base_url=cfg["base_url"])
 self.model = cfg["model"]
 print(f"实际使用的 provider={provider}, "
 f"key 已加载={'是' if os.getenv(cfg['key_env']) else '否'}")

 def chat(self, messages, tools=None,**kwargs) -> str:
 """普通对话：返回纯文本（demo / 对话循环用）"""
 resp = self.client.chat.completions.create(
 model=self.model, messages=messages, tools=tools,
 max_tokens=kwargs.get("max_tokens"))
 return resp.choices[0].message.content

 def chat_for_tools(self, messages, tools):
 """工具对话：返回完整 message 对象（fc_loop 用，能拿到 tool_calls）"""
 resp = self.client.chat.completions.create(
 model=self.model, messages=messages, tools=tools)
 return resp.choices[0].message

 def summarize(self, text: str) -> str:
 """把一段对话文本压缩成简短摘要（记忆压缩模块 compress 调用）"""
 messages = [
 {"role": "system", "content": "你是一个摘要助手。请把下面的对话浓缩成简洁的中文要点，"
 "保留关键事实、用户偏好与决策，不要添加新内容。"},
 {"role": "user", "content": text},
 ]
 return self.chat(messages, max_tokens=500)

逐行拆解：

第 9 行 load_dotenv(..., override=True) 是铁律级写法。override=True 表示".env 里的变量优先级高于系统环境变量"。否则如果你系统里曾设过一个错的 DEEPSEEK_API_KEY，Python 会先用系统的，.env 白读——这坑我踩过，报 401 查了半天才发现是系统里有个旧 key 顶掉了文件里的。
chat 返回 str（纯文本），chat_for_tools 返回完整 message 对象。为什么要两个？因为 Function Calling 要拿 message.tool_calls，只有完整对象里才有，chat 只吐 content 是不够的。这俩分工是后面 fc_loop 能跑起来的前提。
summarize 是给记忆压缩模块 compress.py 用的"摘要能力"。注意它本质就是一次普通 chat，只是 system 提示词换成了"你是摘要助手"。

2.3 流式客户端 `llm/stream_llm.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


# llm/stream_llm.py —— 流式客户端
import os
from openai import OpenAI
from .base import LLMClient, load_provider_config

class StreamLLM(LLMClient):
 def __init__(self, provider="deepseek"):
 cfg = load_provider_config(provider)
 self.client = OpenAI(api_key=os.getenv(cfg["key_env"]),
 base_url=cfg["base_url"])
 self.model = cfg["model"]

 def chat_stream(self, messages, **kwargs):
 """流式：yield 逐段吐（边收边显示）"""
 stream = self.client.chat.completions.create(
 model=self.model, messages=messages, stream=True,
 reasoning_effort=kwargs.get("reasoning_effort", "low"),
 extra_body={"thinking": {"type": "enabled"}},
 max_tokens=kwargs.get("max_tokens", 500),
 )
 for chunk in stream:
 delta = chunk.choices[0].delta.content
 if delta: # 过滤空 chunk（思考过程不吐）
 yield delta

知识点补充：流式用 yield 而不是 return，于是它变成一个生成器，调用方可以 for piece in llm.chat_stream(msgs): print(piece, end="") 实现"边生成边打印"。if delta: 那行很关键——开了 thinking 的模型每个 chunk 可能先吐思考过程再吐正文，空 content 的 chunk 要过滤掉，否则会打印一堆 None。

注：stream_llm.py 没在 main.py 里用（主流程走 RealLLM），但它是 LLM 层"统一接口"的体现——StreamLLM 同样继承自 LLMClient，将来想让对话逐字蹦出来，换一行实例化就行。

2.4 `config.json`：模型与工具的"总清单"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


{
 "providers": {
 "deepseek": {
 "base_url": "https://api.deepseek.com",
 "key_env": "DEEPSEEK_API_KEY",
 "model": "deepseek-v4-flash"
 },
 "kimi": {
 "base_url": "https://api.moonshot.cn/v1",
 "key_env": "MOONSHOT_API_KEY",
 "model": "kimi-k2.6"
 }
 },
 "tools": [
 { "module": "tools.weather", "class": "WeatherTool" },
 { "module": "tools.calculator", "class": "CalculatorTool" },
 { "module": "tools.save_preference", "class": "SavePreferenceTool" },
 { "module": "tools.recall_memory", "class": "RecallMemoryTool" }
 ]
}

知识点补充：key_env 这种设计把"哪把钥匙对应哪个模型"写进了配置，代码里永远不直接写密钥，只写 os.getenv(cfg["key_env"])。密钥在 .env 里：DEEPSEEK_API_KEY=sk-xxxx，.env 不进 git。

一句话记住：LLM 层 = 一个抽象基类 + 两个实现 + 一份"模型说明书"（config.json）+ 一个密钥保险箱（.env）。

三、记忆层：短期窗口 + 长期向量库 + 一条滚动摘要

记忆层是整个项目里最"值钱"的部分，它把"对话记忆"拆成三种形态：

形态	实现	生命周期	用途
短期记忆	`ShortTermMemory`	进程内，窗口滑动	最近 N 轮对话
长期记忆	`LongTermMemory`(Chroma)	落盘，关电脑不丢	用户稳定偏好/事实
压缩摘要	`compress.py`	进程内，一条	老历史浓缩，省 token

3.1 路径集中管理 `memory/paths.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


"""集中管理所有落盘路径, 避免各处硬编码 './xxx' (相对路径会随 cwd 漂移)."""
# ============ 隐私分流（设计约定, 不是代码自动给的） ============
# 🔒 永远留本地、绝不进 prompt: 用户真实姓名 / 联系方式 / 密钥 / 明文敏感偏好
# 🌐 会发到云端 LLM API: 你主动塞进 system/user 消息的"召回结果"
# ⚠️ 敏感事实: 存本地, 但召回时不自动进 prompt, 需用户显式确认才带上
# ==============================================================

import os
BASE = os.path.dirname(os.path.abspath(__file__))
MEM_STORE = os.path.join(BASE, "mem_store") # Chroma 向量库
PROFILE_DB = os.path.join(BASE, "memory.db") # SQLite 用户画像
FACTS_JSON = os.path.join(BASE, "facts.json") # 纯本地简单事实

逐行拆解：注释里那套"隐私分流"是设计约定——MEM_STORE 是 Chroma 向量库路径，PROFILE_DB 是给 SQLite 画像预留的（当前代码用的是 facts.json 思路的简化版，向量库已足够）。所有路径都用 os.path.abspath(__file__) 算出来，保证无论从哪运行都不会找错地方。

3.2 短期记忆 `memory/shortmemory.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


class ShortTermMemory:
 def __init__(self,window=10,max_tokens:int=500,system_roles=("system",)):
 self.window=window # 聊天窗口大小
 self.max_tokens=max_tokens # 最大 tokens
 self.system_roles=system_roles
 self.buffer=[] # 消息缓存

 def _tokens(self,msgs) ->int: # 估算 token 数
 return sum(max(1,len(m.get("content",""))//3)for m in msgs)

 def add(self,msg:dict): # 消息缓存
 self.buffer.append(msg)

 def context(self)->list[dict]: # 返回最近 n 条消息，滑动窗口
 sys_msgs=[m for m in self.buffer if m.get("role") in self.system_roles]
 others=[m for m in self.buffer if m.get("role") not in self.system_roles]
 return sys_msgs+others[-self.window:]

 def trim(self): # 消息裁剪
 sys_msgs= [m for m in self.buffer if m.get("role") in self.system_roles]
 others =[m for m in self.buffer if m.get("role") not in self.system_roles]
 while self._tokens(others) >self.max_tokens and len(others)>1:
 others.pop(0)
 self.buffer=sys_msgs+others
 return self.buffer

知识点补充：context() 实现的是滑动窗口——永远只取最近 window 条非系统消息，系统消息（system）永远保留在最前。trim() 是更狠的"裁剪"：按 token 硬砍最老的，直到不超 max_tokens。压缩 ≠ 裁剪：trim 是"删"，compress 是"把老历史浓缩成一条摘要再保留"，两者互补。

3.3 长期记忆 `memory/long_term.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


'''
长期记忆 = 关电脑也不丢
长期记忆 = 单文档 RAG + 落盘
 嵌入/相似度召回 → 只是把"文档"换成"用户事实"且持久化
pip install chromadb
'''
import chromadb
from pathlib import Path
import chromadb, time
from memory.paths import MEM_STORE

class LongTermMemory:
 def __init__(self, path=MEM_STORE, collection_name="long_term"):
 self.client = chromadb.PersistentClient(path=path) # 绝对路径
 self.col = self.client.get_or_create_collection(collection_name)

 def add_fact(self, text: str, fid: str, private: bool = False):
 """存一条长期事实。private=True 表示敏感, 召回时默认不出网。"""
 self.col.add(ids=[fid], documents=[text],
 metadatas=[{"private": private, "ts": time.time()}])

 def recall(self,query:str,k:int=3,include_private=False)->list[str]:
 """召回相关事实。默认跳过 private=True 的敏感事实(不进 prompt)。"""
 res=self.col.query(query_texts=[query],n_results=k)
 facts=[]
 for doc,meta in zip(res["documents"][0],res["metadatas"][0]):
 if meta and meta.get("private") and not include_private:
 continue
 facts.append(doc)
 return facts

 def delete(self,fid:str):
 self.col.delete(ids=[fid])

知识点补充（RAG 召回）：这其实就是一个迷你版 RAG（检索增强生成）。Chroma 的 PersistentClient 把向量库落盘到 MEM_STORE 目录，所以关掉程序再打开，记忆还在。add_fact 时 Chroma 会用内置 embedding 模型把 text 变成向量；recall 时把 query 也变成向量，做相似度检索，返回最像的句子。代码里那个 from memory.paths import MEM_STORE 就是 3.1 集中路径管理的价值——改路径只动 paths.py 一处。

踩坑记：我第一次跑它时 chromadb 要联网下载 all-MiniLM-L6-v2 这个 embedding 模型，本地没代理直接 httpx.ConnectTimeout。后来走 Clash 代理（7890）把模型下到了本机缓存 C:\Users\MLoong\.cache\chroma\onnx_models，之后离线也能跑。

铁律 2：private 字段是隐私底线的代码化——敏感事实（真实姓名、密钥等）存本地但不自动进 prompt，recall 默认 include_private=False 跳过它。想让它进模型，必须显式传 include_private=True（且最好让用户确认）。

3.4 滚动摘要压缩 `memory/compress.py`

这是记忆层的"灵魂"，也是我修过 bug 的地方。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38


"""
上下文压缩——>一条滚动摘要，永远只有一条
"""

def _estimate_tokens(text:str) ->int:#token估算
 """
 估算tokens，达到上限压缩一次。
 中文为主：1 字≈1 token，直接用字符数估算（原 *0.6 严重低估中文，
 导致上下文要累积到 2500+ 字才触发压缩，实际等于不压缩）。
 """
 return max(1, len(text))

def _fmt(messages) ->str:#历史消息拼接
 """消息列表，摘要原材料"""
 return "\n".join(f"{m['role']}:{m['content']}" for m in messages)

def compress(messages:list[dict],llm,keep:int=4) ->list[dict]:#压缩逻辑函数
 """滚动压缩版本"""
 sys_msgs=[m for m in messages if m.get("role")=="system" and not m.get("is_summary")]
 old_sums=[m for m in messages if m.get("is_summary")]
 others=[m for m in messages if m.get("role")!="system" and not m.get("is_summary")]
 if len((others))<=keep:
 return messages
 old,recent=others[:-keep],others[-keep:]

 # 滚动关键：旧摘要 + 新滚出窗口的原文 → 合并成一条新摘要
 text=_fmt(old)
 if old_sums:
 text=f"已有摘要:{old_sums[-1]['content']}\n新增对话：\n{text}"
 summary=llm.summarize(text)
 summary_msg={"role":"system","content":f"历史摘要：{summary}","is_summary":True}
 return sys_msgs + [summary_msg] + recent

def maybe_compress(messages,llm,max_tokens:int=3000,keep=4):#自动压缩检测
 """自动触发，超阈值才压缩，没超原样返回"""
 if (_estimate_tokens(_fmt(messages))>max_tokens and len(messages)> keep+1):
 return compress(messages,llm,keep=keep)
 return messages

逐行拆解：

_estimate_tokens 现在是 return max(1, len(text))——中文 1 字≈1 token。原先写的是 len(text)*0.6，把中文 token 数严重低估，结果上下文要攒到 2500+ 字才触发压缩，等于永远不压缩。这是我在调试时发现的一个真 bug，改成字符数后，2520 字立刻触发了压缩，出来 5 条消息 + 1 条摘要。
compress 的"滚动"精髓在第 32-36 行：如果已经有旧摘要，就把"旧摘要 + 新滚出窗口的原文"一起喂给 llm.summarize。这样无论聊多久，摘要永远只有一条（is_summary=True），不会越压越多、越压越乱。
is_summary 这个标记位是防止"摘要被二次压缩"的关键。后面 sys_msgs 过滤时特意排除了 is_summary 的 system 消息，避免把摘要当普通消息再处理。

铁律 3：压缩是"浓缩"不是"删除"。keep 条最近对话永远原样保留，只有"滚出窗口的老历史"被压成摘要。所以 Agent 不会忘掉你刚说的，只会忘掉"你上周说的、但已浓缩进摘要"的细节。

3.5 统一调度者 `memory/memory_manager.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


"""
记忆调度：把三个记忆模块拼接起来，对外只暴露 add / get_context / maybe_compress / recall
- get_context 里召回结果是临时拼接、不写回 buffer → 避免"每次召回都追加 system 导致堆积"
- maybe_compress 用 `msgs is not self.stm.buffer` 判断"真的压了才写回" → 没超阈值不碰 buffer
- add_fact 的 fid 用内容 md5 哈希 → 稳定、不重复、跨进程
"""
from .compress import compress, maybe_compress as _auto_compress
from .shortmemory import ShortTermMemory
from .long_term import LongTermMemory
import hashlib

def _fid(text: str) -> str:
 """内容哈希生成稳定ID：不重复、可跨进程（比 hash() 稳，hash 有随机盐）"""
 return "f" + hashlib.md5(text.encode("utf-8")).hexdigest()[:12]

class MemoryManager:
 def __init__(self, window=8, max_tokens=2000, keep=4, llm=None):
 self.stm = ShortTermMemory(window=window, max_tokens=max_tokens)
 self.ltm = LongTermMemory()
 self.keep, self.max_tokens, self.llm = keep, max_tokens, llm

 def add(self, msg: dict, persist: bool = False):
 self.stm.add(msg)
 # 只有明确是用户事实才落长期（persist 默认 False，省 embedding 开销）
 if persist and msg.get("role") == "user":
 self.ltm.add_fact(msg["content"], fid=_fid(msg["content"]))

 def get_context(self, query: str = None) -> list[dict]:
 base = self.stm.context() # [系统提示] + [窗口消息]
 if not query:
 return base
 facts = self.ltm.recall(query, k=3)
 if not facts:
 return base
 facts_msg = {"role": "system", "content": "已知用户长期事实：" + "|".join(facts)}
 sys_msgs = [m for m in base if m.get("role") in self.stm.system_roles]
 others = [m for m in base if m.get("role") not in self.stm.system_roles]
 return sys_msgs + [facts_msg] + others # 系统提示 + 长期事实 + 窗口

 def maybe_compress(self, llm=None):
 llm = llm or self.llm
 if llm is None:
 return self.stm.buffer
 msgs = _auto_compress(self.stm.buffer, llm,
 max_tokens=self.max_tokens, keep=self.keep)
 if msgs is not self.stm.buffer: # 真压缩了才写回
 self.stm.buffer = msgs
 return self.stm.buffer

 def recall(self, query: str, k: int = 3) -> list[str]:
 return self.ltm.recall(query, k=k)

逐行拆解：

MemoryManager 是调度者，不是新逻辑。它自己不存东西，只把 ShortTermMemory 和 LongTermMemory 组合起来，对外暴露干净的四方法：add / get_context / maybe_compress / recall。上层（main.py）只跟它打交道。
get_context 里召回结果是临时拼进上下文的（第 38-40 行重新拼 sys_msgs + facts_msg + others），没有写回 buffer。这点很重要——否则每次召回都把"已知用户长期事实"塞进 buffer，buffer 会越滚越大、重复堆积。
maybe_compress 第 48 行用 msgs is not self.stm.buffer 判断"真的压了才写回"。is 是身份判断：没超阈值时 compress 原样返回同一个 list，身份不变 → 不写回；超阈值时返回新 list → 写回。一个 is 省掉了无意义的覆盖。
_fid 用 hashlib.md5(text) 生成稳定 ID，而不是 Python 内置 hash()——因为 hash() 有随机盐，每次进程重启同一个字符串 hash 值不一样，会导致 Chroma 里重复存储或删不掉。md5 跨进程稳定。

一句话记住：记忆层 = 短期窗口（删旧的）+ 长期向量库（存偏好）+ 滚动摘要（压老的），三者由一个只调度、不改写的 MemoryManager 串起来。

四、工具层：注册表 + 自愈执行器 + 依赖注入

工具层让 Agent “能干活”。它的设计亮点是配置驱动注册和执行时自愈。

4.1 工具基类 `tools/base.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


class BaseTool:
 name: str = "" # 工具名（模型调用时用）
 description: str = "" # 给模型看的说明（决定它会不会调）
 parameters: dict = {} # JSON Schema（声明参数格式）

 def __init__(self, **kwargs):
 pass # 允许注册时传入 mm=... 等依赖，不需要的工具直接忽略

 def execute(self, **kwargs) -> str:
 raise NotImplementedError("子类必须实现 execute()")

知识点补充：__init__(self, **kwargs) 是关键设计。注册时 ToolRegistry 会往所有工具里塞 **deps（比如 mm=MemoryManager 实例）。不需要依赖的工具（天气、计算器）就靠这个 **kwargs 把多余参数"吞掉"，不会因为多传了个 mm 就报错。name / description / parameters 三个类属性，是给 LLM 看的"说明书"——description 写得好不好，直接决定模型会不会调这个工具。

4.2 动态注册表 `tools/registry.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


# 读 config.json 动态注册工具
import json, importlib
from .base import BaseTool

class ToolRegistry:
 def __init__(self, config_path: str, deps: dict = None):
 self._deps = deps or {} # 依赖注入：{"mm": MemoryManager实例}
 self._tools = {}
 with open(config_path, encoding="utf-8") as f:
 self._config = json.load(f)

 def register_all(self):
 """按 config.json 的 tools 列表加载所有工具"""
 for item in self._config.get("tools", []):
 mod = importlib.import_module(item["module"]) # 按路径导入模块
 cls = getattr(mod, item["class"]) # 取类
 tool = cls(**self._deps) # 实例化（注入依赖）
 self._tools[tool.name] = tool
 return self

 def get_schemas(self): 
 """给 LLM 的说明书，返回 openai 可读的格式"""
 return [{"type": "function", "function": {
 "name": t.name, "description": t.description, "parameters": t.parameters,
 }} for t in self._tools.values()]

 def execute(self, name: str, args: dict) -> str:
 if name not in self._tools:
 return f"未注册的工具: {name}"
 return self._tools[name].execute(**args)

逐行拆解：

register_all 是配置驱动的典范。加一个新工具，只需：① 写 tools/xxx.py 定义 XxxTool；② 在 config.json 的 tools 里加一行 {"module":"tools.xxx","class":"XxxTool"}。不用改任何注册代码。importlib.import_module + getattr 把字符串变成真正的类，再 cls(**self._deps) 实例化。
get_schemas 把每个工具的 name/description/parameters 包成 OpenAI Function Calling 要的 JSON 格式。这就是"让模型知道有哪些工具可用"的关键一步——fc_loop 会把它的返回值传给 chat_for_tools。
deps={"mm": mm} 是依赖注入（DI）：save_preference 和 recall_memory 需要访问记忆，于是注册时把 MemoryManager 实例塞进去。工具自己不负责创建记忆管理器，由外面"注入"，解耦且便于测试。

4.3 带"自愈"的执行器 `tools/executor.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# 出错重试 / 参数修复（跨工具通用）
from __future__ import annotations

import time

class ToolExecutor:
 def __init__(self, registry:ToolRegistry, max_retries=2):
 self._registry = registry
 self._max_retries = max_retries

 def execute_with_healing(self, name: str, args: dict) -> str:
 last_err = None # 记录"最后一次错误"，备用
 for attempt in range(self._max_retries + 1):
 try:
 return self._registry.execute(name, args) # 试执行工具
 except TypeError as e: # 模型给错参数键，修复重试
 args = self._repair_args(name, args, e) # 修复参数再试
 last_err = e
 except Exception as e: # 其他异常 → 重试
 last_err = e
 time.sleep(1)
 return f"[自愈失败] 工具 {name} 重试 {self._max_retries} 次仍失败: {last_err}"

 def _repair_args(self, name, args, err):
 """把模型给的别名参数映射回工具要的键名"""
 alias = {"user_fact": "fact", "preference": "fact",
 "question": "query", "keyword": "query"}
 return {alias.get(k, k): v for k, v in args.items()}

逐行拆解：

第 2 行 from __future__ import annotations 是修过的一个 bug。原来的代码里 ToolRegistry 类型注解在 ToolExecutor.__init__ 里用到了，但 ToolRegistry 这个类在 registry.py 里定义、导入顺序导致 NameError。加上这行后，类型注解被延迟求值（变成字符串），不再在导入时就真去解析 ToolRegistry，报错消失。这是 Python 3.10+ 处理"循环/前向引用"的标准姿势。
execute_with_healing 实现了自愈：模型有时候会把参数名搞错（比如该传 fact 却传了 user_fact）。TypeError 被捕获后，_repair_args 用别名表把参数键"翻译"回工具要的名字再重试。这是让 Agent 在模型不完美时依然能跑通的实用技巧。

铁律 4：自愈只修"参数键名错配"这种廉价错误，不掩盖真正的逻辑 bug。重试耗尽会明确返回 [自愈失败]，而不是假装成功——这点很重要，否则你永远不知道工具其实没执行。

4.4 四个工具的实现

天气（真实 HTTP 调用，带天气码字典）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


# tools/weather.py（节选核心）
class WeatherTool(BaseTool):
 name = "get_weather"
 description = "查天气（按经纬度），返回天气、温度、湿度、日出日落、降雨概率"
 parameters = {
 "type": "object",
 "properties": {
 "latitude": {"type": "number", "description": "纬度"},
 "longitude": {"type": "number", "description": "经度"},
 },
 "required": ["latitude", "longitude"],
 }
 def execute(self, latitude: float, longitude: float) -> str:
 try:
 url = (f"https://api.open-meteo.com/v1/forecast?latitude={latitude}"
 f"&longitude={longitude}&current=...&daily=...&timezone=Asia%2FShanghai")
 data = json.loads(urllib.request.urlopen(url).read())
 # ... 把 weather_code 翻成中文描述，拼成 JSON 返回
 except Exception as e:
 return f"查天气失败: {e}"

计算器（安全 eval，只放行四则运算 AST 节点，防代码注入）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# tools/calculator.py（节选核心）
class CalculatorTool(BaseTool):
 name = "calculator"
 description = "四则运算（如 1+2*3）"
 parameters = {
 "type": "object",
 "properties": {"expr": {"type": "string", "description": "数学表达式"}},
 "required": ["expr"],
 }
 def execute(self, expr: str) -> str:
 try:
 tree = ast.parse(expr, mode="eval")
 # 只允许数字和四则运算，防止模型注入危险代码
 allowed = (ast.Expression, ast.BinOp, ast.UnaryOp, ast.Constant,
 ast.Add, ast.Sub, ast.Mult, ast.Div, ast.USub)
 for node in ast.walk(tree):
 if not isinstance(node, allowed):
 return f"表达式包含不允许的语法: {type(node).__name__}"
 result = eval(compile(tree, "<string>", "eval"),
 {"__builtins__": {}}, {})
 return str(result)
 except Exception as e:
 return f"计算失败: {e}"

知识点补充：CalculatorTool 用的是 ast 白名单，而不是裸 eval(expr)。裸 eval 能让模型注入 os.system("rm -rf /") 这种东西。这里先用 ast.parse 把表达式解析成语法树，逐个节点检查是不是在 allowed 白名单里（只有数字、加减乘除），不在就拒绝。最后 eval(..., {"__builtins__": {}}, {}) 还把内置函数全清空。这是**“让 LLM 能算数但不能搞破坏"的标准做法**。

保存偏好 / 召回记忆（依赖注入 mm 的范例）：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33


# tools/save_preference.py
class SavePreferenceTool(BaseTool):
 name = "save_preference"
 description = "当用户表达稳定偏好/事实时调用，跨会话记住"
 parameters = {
 "type": "object",
 "properties": {"fact": {"type": "string", "description": "要记住的用户事实"}},
 "required": ["fact"],
 }
 def __init__(self, mm=None):
 self.mm = mm # 依赖注入：MemoryManager 由外面传入
 def execute(self, fact: str) -> str:
 if self.mm is None:
 return "错误：记忆管理器未注入"
 self.mm.add({"role": "user", "content": fact}, persist=True) # 落长期
 return f"已保存到长期记忆 ✓"

# tools/recall_memory.py
class RecallMemoryTool(BaseTool):
 name = "recall_memory"
 description = "需要回顾用户历史偏好/事实时调用"
 parameters = {
 "type": "object",
 "properties": {"query": {"type": "string", "description": "检索关键词"}},
 "required": ["query"],
 }
 def __init__(self, mm=None):
 self.mm = mm
 def execute(self, query: str) -> str:
 if self.mm is None:
 return "错误：记忆管理器未注入"
 facts = self.mm.recall(query, k=3) # 召回结果拼回上下文
 return "；".join(facts) if facts else "（没有找到相关记忆）"

逐行拆解：这俩工具展示了依赖注入的实际落点。__init__(self, mm=None) 接收外面传进来的 MemoryManager 实例，execute 里就能直接 self.mm.add(...) / self.mm.recall(...)。注意 save_preference 调 add(..., persist=True)——对应 3.5 里"只有 persist 才落长期记忆”，于是这条偏好就进了 Chroma 向量库，下次会话还能回忆起来。

一句话记住：工具层 = 一个基类（统一接口）+ 一个注册表（配置驱动、DI 注入 mm）+ 一个自愈执行器（修参数键名错配）+ 四个干活的工具。

五、Agent 层：Function Calling 循环 + 路由器 + 四种推理模式

这一层是"大脑的决策中枢"。

5.1 Function Calling 主循环 `agent/core.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


import json
from .modes import BUILDERS

def fc_loop(llm, messages, registry, executor, max_rounds=3):
 """
 Function Calling 主循环
 1. llm.chat_for_tools 返回 message 对象 → 能拿到 tool_calls
 2. registry.get_schemas() 从 config.json 动态生成 schema
 3. executor.execute_with_healing 带自愈
 """
 tool_records = []
 for _ in range(max_rounds):
 msg = llm.chat_for_tools(messages, registry.get_schemas())
 if not msg.tool_calls:
 # 模型没调工具 → 返回答案 + 记录
 return {"answer": msg.content, "tool_records": tool_records}
 messages.append(msg)
 for tc in msg.tool_calls:
 try:
 args = json.loads(tc.function.arguments)
 except Exception as e:
 messages.append({"role": "tool", "tool_call_id": tc.id,
 "content": f"参数解析失败:{e}"})
 continue
 result = executor.execute_with_healing(tc.function.name, args) # 自愈执行
 tool_records.append({"tool": tc.function.name, "args": args, "result": result})
 messages.append({"role": "tool", "tool_call_id": tc.id, "content": str(result)})
 return {"answer": "达到最大工具轮数", "tool_records": tool_records}

def get_response(msgs, llm, **kw):
 """调 LLM 生成回复"""
 return llm.chat(msgs, **kw)

def run_mode(mode, question, llm, builders=None, **kw):
 """按模式调度：查注册表 → 构造消息 → 调 LLM"""
 builders = builders or BUILDERS
 if mode not in builders:
 raise ValueError(f"未知模式:{mode},可选 {list(builders)}")
 msgs = builders[mode](question, **kw)
 return get_response(msgs, llm, **kw)

知识点补充（Function Calling 循环）：这是整个 Agent “会办事"的核心。流程是：

把"当前消息 + 工具清单"发给模型（chat_for_tools）；
模型如果返回 tool_calls，说明它想调工具——把模型这步的 msg 先塞回 messages（必须把模型的 tool_calls 消息留在上下文里，否则模型看不到自己刚才的决定）；
逐个 tool_calls 解析参数 → executor 执行 → 把结果以 role:"tool" 消息塞回；
带着"工具结果"再问一次模型，循环最多 max_rounds 轮，直到模型不再调工具、直接给答案。

铁律 5：messages.append(msg)（第 18 行）不能省。Function Calling 是"多轮对话"范式，模型返回的带 tool_calls 的 assistant 消息必须原样留在 messages 里，下一轮模型才能把 role:"tool" 的结果对应上。漏了这步，模型会反复"决定调工具但永远拿不到结果”。

5.2 路由器 `agent/router.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


# 路由：选模型 + 选推理模式
def route_model(question: str, default: str = "deepseek") -> str:
 """从用户输入里找模型名,找不到用默认"""
 for name in ["kimi", "deepseek", "qwen", "gpt"]:
 if name in question.lower():
 return name
 return default

def auto_select(question: str, llm=None) -> str:
 """
 判断问题适合哪种推理模式
 升级可选：让 LLM 输出 JSON 再解析，比关键词匹配更稳（防格式漂移）
 """
 if llm is not None:
 text = (f"判断下面用户的问题适合哪种回答，只输出以下之一：cot / few_shot / react / tot。"
 f"规则：需要动手查/调工具用 react；需要多方案权衡用 tot；"
 f"需要解释原因用 cot；需要举例对比用 few_shot。\n问题:{question}")
 out = llm.chat([{"role": "user", "content": text}]).lower()
 for mode in ["tot", "react", "few_shot", "cot"]:
 if mode in out:
 return mode

 q = question.lower()
 if any(k in q for k in ["帮我", "执行", "查询", "搜索"]):
 return "react"
 if any(k in q for k in ["如果", "方案", "计划"]):
 return "tot"
 if any(k in q for k in ["比较", "对比", "哪个"]):
 return "few_shot"
 return "cot" # 默认

知识点补充：auto_select 有两套策略——有 LLM 时用 LLM 判断（让模型输出 cot/few_shot/react/tot 之一，最准），没 LLM 时退化为关键词匹配（“帮我/查询”→react，“方案/计划”→tot，兜底 cot）。这就是"能换脑子"的实现：同一个问题，根据类型走不同推理模式。

5.3 四种推理模式 `agent/modes/`

四种模式本质都是"构造一套 messages"，区别在 system 提示词和是否带示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49


# agent/modes/cot.py —— 思维链：让模型一步步推
def cot_prompt(question: str) -> list[dict]:
 return [
 {"role": "system", "content": "你是擅长逐步推理的专家,请一步一步思考,先列思路再给结论。"},
 {"role": "user", "content": question},
 ]

# agent/modes/few_shot.py —— 少样本：给例子让它学格式
DEFAULT_EXAMPLES = [
 {"question": "我明天下午3点约了张医生复诊",
 "answer": "时间:明天下午3点;人物:张医生;事项:复诊"},
 {"question": "周五晚上和李总在望江楼吃饭",
 "answer": "时间:周五晚上;人物:李总;事项:吃饭"},
]
def few_shot_prompt(question, examples=DEFAULT_EXAMPLES,
 system_prompt="你是擅长信息抽取的助手"):
 msgs = [{"role": "system", "content": system_prompt}]
 for ex in examples:
 msgs.append({"role": "user", "content": ex["question"]})
 msgs.append({"role": "assistant", "content": ex["answer"]})
 msgs.append({"role": "user", "content": question})
 return msgs

# agent/modes/react.py —— 工具调用：给个系统提示就完事，真正调工具靠 fc_loop
def react_prompt(question, system_prompt="你是会调用工具的智能助手，"
 "需要查询/计算/记忆时调用工具，并把工具结果结合进回答。"):
 return [
 {"role": "system", "content": system_prompt},
 {"role": "user", "content": question},
 ]

# agent/modes/tot.py —— 树状思维：三次调用（发散→评审→决策）
def ask(llm, question, system_prompt="你是擅长多种角度对比方案的资深决策专家",
 max_tokens=500):
 msgs = [{"role": "system", "content": system_prompt},
 {"role": "user", "content": question}]
 return llm.chat(msgs, max_tokens=max_tokens)

def tot_solve(question, n=3, llm=None):
 """三段式：发散 → 评审 → 决策（三次调用）"""
 if llm is None:
 raise ValueError("tot 模式需要注入 llm")
 schemes = ask(llm, f"请针对以下问题给出{n}种不同解决思路,编号列出:\n{question}\n",
 system_prompt="你是擅长发散思维的规划专家", max_tokens=600)
 scores = ask(llm, f"请对以下 {n} 个方案根据实行难度,风险评估逐一打分(1-10分),并各用一句话说明理由:\n{schemes}",
 system_prompt="你是严格的评审专家,打分要客观", max_tokens=500)
 best = ask(llm, f"综合以下评分,选出最优方案,并给出具体实施步骤:\n{scores}",
 system_prompt="你是决策专家,直接给最终选择", max_tokens=600)
 return schemes, scores, best

知识点补充：CoT / Few-shot / ReAct / ToT 是 LLM 推理的四种经典范式——

模式	一句话	适合场景
CoT	一步步想	要解释原因、推导
Few-shot	照例子学	格式固定的抽取/分类
ReAct	想一步、干一步	要查/算/调工具
ToT	多方案打分选优	需要权衡决策

BUILDERS 字典（modes/__init__.py）把它们按名字收口，于是 run_mode("cot", q, llm) 一行就能切换模式。

一句话记住：Agent 层 = 一个 fc_loop（Function Calling 循环）+ 一个路由器（选模型/选模式）+ 四种"造消息"的范式。

六、组装口 `agent/main.py`：把四层粘起来

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


# main.py —— 组装所有层
import sys
from pathlib import Path

# 让 agent/main.py 直接运行时也能找到项目根目录的 llm/memory/tools 包
PROJECT_ROOT = Path(__file__).parent.parent
sys.path.insert(0, str(PROJECT_ROOT))

from llm import RealLLM
from memory import MemoryManager
from tools import ToolRegistry, ToolExecutor
from agent import fc_loop, auto_select

llm = RealLLM("deepseek")
mm = MemoryManager(window=8, max_tokens=1500, keep=4, llm=llm)
registry = ToolRegistry(str(PROJECT_ROOT / "config.json"), deps={"mm": mm}).register_all()
executor = ToolExecutor(registry)

while True:
 u = input("你: ")
 if u.lower() == "exit":
 break
 mm.add({"role": "user", "content": u}, persist=u.startswith("记住:"))
 ctx = mm.get_context(query=u)
 out = fc_loop(llm, ctx, registry, executor) # 返回 {"answer", "tool_records"}
 mm.add({"role": "assistant", "content": out["answer"]})
 mm.maybe_compress()
 print("Agent:", out["answer"])

逐行拆解：

第 6-7 行 sys.path.insert(0, str(PROJECT_ROOT)) 是个修过的坑。直接 python agent/main.py 运行时，Python 的模块搜索路径默认是 agent/ 而不是项目根，于是 from llm import ... 会报 ModuleNotFoundError: No module named 'llm'。把项目根插进 sys.path 就解决了。
第 16 行 deps={"mm": mm} 是把 MemoryManager 实例注入工具层的关键一步——这样 save_preference / recall_memory 才有记忆可用。
主循环（19-28 行）是整条链路的"呼吸"：add 用户消息（以"记住:“开头就落长期）→ get_context（短期窗口 + 长期召回拼接）→ fc_loop（可能调工具）→ add 助手消息 → maybe_compress（超阈值才压）。每一轮都完整走一遍"记→取→想→答→压”。

铁律 6：persist=u.startswith("记住:") 是个巧妙的约定——用户说"记住:我喜欢用 DeepSeek"时，这句话带着"记住:“前缀，于是 mm.add(..., persist=True) 把它存进长期向量库；普通闲聊不落长期，省 embedding 开销。

七、知识点总盘点

把全文的知识点收个表，方便你回看：

知识点	落在哪	一句话
分层架构	四目录	换一层不碰其他层
OpenAI 兼容客户端	`real_llm.py`	一个 client 通吃各家模型
`.env` + `override=True`	`real_llm.py`	文件密钥优先于系统环境变量
`chat` vs `chat_for_tools`	`real_llm.py`	要 tool_calls 必须拿完整 message 对象
流式生成器 `yield`	`stream_llm.py`	边生成边打印，过滤空 chunk
配置与密钥分离	`config.json` / `.env`	代码里永不写密钥
滑动窗口 / 裁剪	`shortmemory.py`	取最近 N 条 / 按 token 硬砍老的
长期向量记忆(RAG 召回)	`long_term.py`	Chroma 落盘，相似度检索用户事实
滚动摘要压缩	`compress.py`	旧摘要+新原文→永远一条新摘要
中文 token 估算	`compress.py`	1 字≈1 token，别乘 0.6
隐私字段 `private`	`long_term.py`	敏感事实存本地、不自动进 prompt
依赖注入 DI	`registry.py`/`base.py`	外面把 mm 塞进工具，解耦
配置驱动注册	`registry.py`	加工具只改 config.json
执行器自愈	`executor.py`	修参数键名错配，重试兜底
`from __future__ import annotations`	`executor.py`	延迟类型求值，解前向引用报错
安全 eval(白名单 AST)	`calculator.py`	只放行四则运算，防注入
Function Calling 循环	`core.py`	模型调工具→执行→结果回灌→再问
必须回灌 assistant tool_calls 消息	`core.py`	否则模型拿不到工具结果
四种推理范式	`modes/`	CoT / Few-shot / ReAct / ToT
`sys.path` 注入项目根	`main.py`	解决直接运行找不到包

八、踩坑记合集（ debugging 实录）

这一节把项目从"跑不起来"到"全功能可用"期间踩的坑一次性列出来，每一条都是真金白银换的。

ModuleNotFoundError: No module named 'llm' 直接 python agent/main.py 时 Python 找不到项目根的 llm 包。→ 在 main.py 开头 sys.path.insert(0, PROJECT_ROOT)；同时补 agent/__init__.py 暴露 fc_loop/auto_select。
SyntaxError: f-string: unmatched '['（compress.py） Python 3.10 的 f-string 里不允许嵌套双引号。→ 把内层双引号改成单引号 f"{m['role']}:{m['content']}"。
ModuleNotFoundError: No module named 'openai' 机器上有多个 Python，跑脚本的解释器没装依赖。→ 用对应解释器的 python -m pip install openai chromadb python-dotenv。
NameError: name 'ToolRegistry' is not defined（executor.py） 类型注解里前向引用了还没解析的类。→ 文件头加 from __future__ import annotations。
TypeError: WeatherTool() takes no arguments 工具实例化时被注入了 mm=...，但基类没接收。→ 给 BaseTool 加 def __init__(self, **kwargs): pass。
httpx.ConnectTimeout（Chroma 下载 embedding 模型） 本地没代理，Chroma 联网下 all-MiniLM-L6-v2 超时。→ 走 Clash 代理(7890)把模型下到本机缓存，之后离线可用。
openai.AuthenticationError: 401（key 不对） 系统环境变量里有个旧的 DEEPSEEK_API_KEY 顶掉了 .env 里的。→ load_dotenv(..., override=True)，让文件里的密钥优先级最高。
AttributeError: 'RealLLM' object has no attribute 'summarize' compress.py 调了 llm.summarize，但 RealLLM 没这个方法。→ 在 RealLLM 里补 summarize。
压缩永远不触发 _estimate_tokens 原写 len(text)*0.6，中文被严重低估，要攒 2500+ 字才压。→ 改成 max(1, len(text))，2500 字立刻触发。
长期记忆里混进了脏数据（跨会话旧事实） 调试期存过测试事实，污染了召回。→ 删掉 mem_store/ 目录，下次运行自动重建。

九、总结

D:\agent_project 麻雀虽小，五脏俱全。它用四层架构把一个能"记事儿、会调工具、能换脑子"的 Agent 讲清楚了：

LLM 层把模型抽象成可替换零件，密钥与模型配置分离；
记忆层用短期窗口 + 长期向量库 + 滚动摘要，解决了"记性"问题，还顺手做了隐私分流；
工具层用配置驱动注册 + 依赖注入 + 自愈执行器，让 Agent 安全、可扩展地"干活”；
Agent 层用 Function Calling 循环把"想+干"串起来，用路由器在四种推理范式间切换；
main.py 把这一切粘成一个能对话的循环。

一句话记住：Agent 不是某个神奇模型，而是"LLM（脑子）+ 记忆（记性）+ 工具（手脚）+ 循环调度（决策）“四件套的工程化组装——分层清晰，每一层都能单独换、单独测、单独升级。

项目路径：D:\agent_project ｜备份：D:\agent_project_backup_20260821

Manager

Wed, 19 Aug 2026 15:48:04 +0800

给 AI Agent 的记忆装个"调度台"：MemoryManager 为什么"薄"才是对的

前两天我们分别造好了短期窗口、长期档案、上下文压缩三块积木。今天把它们拼起来——但拼的方式不是"再写一大坨逻辑"，而是放一个"调度台"上去。这一课比跑通测试更值钱的，是藏在最后那条报错里的一句话：压缩没触发不是 bug，是没到压缩点。

一、先搞清楚：为什么需要一个调度台

前两天我们写了三个能独立干活的模块：

模块	干啥的	形态
`ShortTermMemory`	短期窗口，记最近 N 条对话	内存里的 `buffer` 列表
`LongTermMemory`	长期档案，按语义召回用户事实	Chroma 向量库
`compress`	上下文压缩，老历史浓缩成一条摘要	纯函数

三块积木各自都能跑。但一个真正的对话 Agent 需要回答一个问题：“此刻该让谁上场？”

用户说了句重要的事，要不要落进长期档案？还是只在短期窗口待一会儿？
这轮要回复了，要不要去长期档案里翻翻有没有相关的？
窗口是不是太长了，要不要压缩？

这些"决策"如果散落在业务代码里，每接一个场景（测试、对话、demo）都得重写一遍接线。所以今天加一层 MemoryManager——它是总开关，把三个模块的插头接到一个开关上。

一句话记住：模块是电器，MemoryManager 是接线板。接线板本身不生产电，但没它，电器各干各的。 它的代码"薄"不是偷懒，而是因为它本就不该有逻辑——逻辑都在三个模块里，它只负责"何时让谁干活"。

二、热身：两个视角的文件，别被"蒙"

上手整合时最容易懵：为啥 test_manager.py 和 chat_with_memory.py 看起来"长得不像同一套东西"？因为它们俩角色完全不同：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


┌─────────────────────────────────────────────────┐
│ test_manager.py（质检员） │
│ 目的: 不接真 LLM, 用假数据验证 MemoryManager │
│ 这个"管家"的 5 个功能没写错 │
│ 特点: 全是 assert(断言), 没有真对话 │
└─────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────┐
│ chat_with_memory.py（真店员） │
│ 目的: 把管家接进真正的对话循环, 用户一句句聊 │
│ 特点: input() 接收输入, 调真 LLM 回答 │
└─────────────────────────────────────────────────┘

类比：汽车出厂前。test_manager.py 是质检员在车间里"踩油门、转方向盘、测刹车"（不真上路）；chat_with_memory.py 是车交付后你真正开上路。

质检员在查什么（test_manager.py 的 5 项检查）

整个测试就一句话：“管家，我考考你——存了的能想起来吗？窗口会爆吗？”

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


开始
 │ 造一个管家 mm（窗口=8条, 超2000 token才压缩）
 ├─① mm.add(system) → 交代人格"你是客服小M"
 ├─① mm.add("我叫小明喜欢蓝色", persist=True)
 │ → 这句"重要", 抄进长期档案室
 ├─② 聊 20 轮, 每轮都 mm.maybe_compress()
 ├─③ mm.get_context("用户叫什么名字?")
 │ assert "小明" 在里面 → 检查①: 长期召回生效(没失忆)
 ├─④ assert buffer里没有"已知用户长期事实"
 │ → 检查②: 查完档案不留痕迹(不污染工作台)
 ├─⑤ assert 摘要条数==1 → 检查③: 压缩生效, 摘要恒1条
 ├─⑥ 新建 mm2（模拟重启）
 │ assert mm2.recall("用户喜欢什么颜色?") 有"蓝色"
 │ → 检查④: 关电脑再开, 档案室的东西还在
 └─⑦ assert system提示还在 buffer → 检查⑤: 人格永留

终点 → 5 项全过 → ✅

为什么全用假数据 + assert？ 因为要在"没有 LLM、不花钱、可重复"的情况下验证管家逻辑。真实对话里 LLM 的回答不可控，没法断言"模型答对没"；但"该不该召回、该不该压缩、摘要几条"是确定的逻辑，可以用断言死死卡住。

真店员的一天（chat_with_memory.py 的循环）

1
2
3
4
5
6
7
8


while True（营业中）
 ├─ u = input("你: ") → 顾客说话
 └─ bot.chat(u)（服务一次 = 5 步）
 ├─ ① mm.add(用户消息) → 先记在工作台便签(短期窗口)
 ├─ ② ctx = mm.get_context(u)→ 管家去档案室翻相关事实, 拼进上下文
 ├─ ③ resp = llm.chat(ctx) → 把【档案+最近对话】交给 LLM 回答
 ├─ ④ mm.add(助手回复) → 回答也记进便签
 └─ ⑤ mm.maybe_compress() → 每轮后问: 便签太多了吗? 超了就浓缩

对比你之前写的 LLM 对话：以前是 messages.append(...) 自己管列表，现在列表变成了管家的 buffer——你只通过 mm.add（记）和 mm.get_context（取）间接操作。这就是"最小侵入"接法：把"取上下文"这一步换成管家来取，业务循环几乎不用改。

三、MemoryManager 到底在干嘛：就三个"决定"

方法	它做的"决定"	问自己的问题
`add(msg, persist)`	这条消息只进短期窗口，还是也要落长期档案？	“这是重要事实吗？”
`get_context(query)`	现在要不要去档案室召回？召回结果放哪？	“现在要用以前的资料吗？”
`maybe_compress()`	工作台满了吗？满了才压缩	“是不是该收拾了？”

关键认知：MemoryManager 代码"薄"是它正确的标志。它不该有逻辑，逻辑都在三个模块里，它只做"决定"。你读它时看不到"拧螺丝"的动作，只看到"调用"——这不是空，是项目经理的活。

类比：以前你是自己开餐厅（自己记账、自己端菜）；现在你雇了经理（MemoryManager），你只需要说"客人来了"（add）、“上菜”（chat）。经理怎么查 VIP 档案、怎么整理库存，你不需要插手。

四、代码长什么样（逐块讲解，最后放完整代码）

memory/manager.py 一共一个类，下面逐方法拆，文末给完整源码。

顶部：导入 + 稳定 ID 生成器

1
2
3
4
5
6
7
8


from memory.compress import compress, maybe_compress as _auto_compress
from memory.shortmemory import ShortTermMemory
from memory.long_term import LongTermMemory
import hashlib

def _fid(text: str) -> str:
 """内容哈希生成稳定ID：不重复、可跨进程（比 hash() 稳，hash有随机盐）"""
 return "f" + hashlib.md5(text.encode("utf-8")).hexdigest()[:12]

四个 import，正好对应"三个电器 + 一个压缩纯函数"。_fid 用 md5(内容) 的前 12 位当事实 ID——同一个事实内容永远得到同一个 ID，跨进程也稳定。这点很重要：Python 内置的 hash() 每次进程启动都带随机盐（PYTHONHASHSEED），同一个字符串在不同进程里 hash 值不同，做长期事实的 ID 会乱套。所以用 md5 给内容一个"指纹"。

`init` —— 把三个电器接上电

1
2
3
4
5


class MemoryManager:
 def __init__(self, window=8, max_tokens=2000, keep=4, llm=None):
 self.stm = ShortTermMemory(window=window, maxtokens=max_tokens) # 短期
 self.ltm = LongTermMemory() # 长期(Chroma)
 self.keep, self.max_tokens, self.llm = keep, max_tokens, llm

三个参数全透传给底层：window/keep 给短期窗口，max_tokens 给压缩阈值，llm 是压缩时用的摘要器。调度台自己不存任何业务状态，状态都在 stm 和 ltm 里。

`add` —— 客人说的话，记哪？

1
2
3
4
5


def add(self, msg: dict, persist: bool = False):
 """① 永远进短期窗口; 只有明确用户事实才落长期(省嵌入开销)"""
 self.stm.add(msg)
 if persist and msg.get("role") == "user":
 self.ltm.add_fact(msg["content"], fid=_fid(msg["content"]))

两个动作，决策点在 persist：

self.stm.add(msg)——永远执行，先记在工作台便签（短期窗口）。
只有当 persist=True 且是用户消息时，才 ltm.add_fact(...) 抄进长期档案。

为什么 persist 默认 False？ 因为每次落长期都要算 embedding（花钱花时间）。普通闲聊不值得进档案室，只有明确"这是用户事实"才值得。这行决策让"落长期"成为有意识的选择，而不是默认行为。

`get_context` —— 上菜前，先查 VIP 档案？

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


def get_context(self, query: str = None) -> list[dict]:
 """② 取上下文: 有query才召回; 召回结果临时拼接, 不污染buffer(防重复累加)"""
 base = self.stm.context() # [sys提示...] + [窗口内消息]
 if not query:
 return base
 facts = self.ltm.recall(query, k=3)
 if not facts:
 return base
 facts_msg = {"role": "system",
 "content": "已知用户长期事实: " + " | ".join(facts)}
 sys_msgs = [m for m in base if m.get("role") in self.stm.system_roles]
 others = [m for m in base if m.get("role") not in self.stm.system_roles]
 return sys_msgs + [facts_msg] + others # 系统提示 → 长期事实 → 窗口

三个决策：

没 query？ 直接返回 base，连档案室都不进（省一次检索）。
召回到了吗？ 没相关事实也返回 base，绝不硬塞。
拼在哪？ 召回结果放在 [系统提示] 和 [窗口对话] 之间，形成"系统提示 → 长期事实 → 最近对话"的结构。

面试考点就在这：召回结果是临时拼进去的，不写回 buffer。如果写回，每次 get_context 都会往 buffer 加一条 system，多轮后越堆越多——这就是需求文档里明说的"召回结果要防重复累加"。buffer 里只有"真实发生的对话 + 压缩摘要"，长期事实只是"借来用一下"就还回去了。

`maybe_compress` —— 打烊前，工作台满了吗？

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


def maybe_compress(self, llm=None):
 """③ 超阈值才压; 压完写回buffer(下次context取到压缩后结果)"""
 llm = llm or self.llm
 if llm is None:
 return self.stm.buffer
 msgs = _auto_compress(self.stm.buffer, llm,
 max_tokens=self.max_tokens, keep=self.keep)
 if msgs is not self.stm.buffer: # 真的压缩了才写回
 self.stm.buffer = msgs
 return self.stm.buffer

注意它调用了 compress 模块里的 _auto_compress 纯函数，自己只做两件事：

处理 llm 兜底（调用方没传就用初始化时的）。
判断"是不是真的压了"——compress 函数没超阈值时会原样返回同一个 list 对象，所以 msgs is not self.stm.buffer 是 False，不写回；只有真的压了才把新 list 写回 buffer。

这是个精巧的"零成本判断"：用 is（身份比较）而不是 ==（值比较）来检测"有没有动过"，避免了无意义的 buffer 重赋值。

`recall` —— 对外暴露长期检索

1
2
3


def recall(self, query: str, k: int = 3) -> list[str]:
 """④ 对外暴露长期检索(验收: 重启后仍能recall到DeepSeek)"""
 return self.ltm.recall(query, k=k)

纯粹的转发——把长期检索能力暴露成管家的公开 API，让外部（比如测试里的"模拟重启"mm2.recall(...)）能直接查档案室，而不用知道底层是 Chroma。

完整代码

四个方法拼起来就是 memory/manager.py 的全部，可直接抄：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50


# memory/manager.py —— 记忆总调度台：只做决策，不重写逻辑
from memory.compress import compress, maybe_compress as _auto_compress
from memory.shortmemory import ShortTermMemory
from memory.long_term import LongTermMemory
import hashlib

def _fid(text: str) -> str:
 """内容哈希生成稳定ID：不重复、可跨进程（比 hash() 稳，hash有随机盐）"""
 return "f" + hashlib.md5(text.encode("utf-8")).hexdigest()[:12]

class MemoryManager:
 def __init__(self, window=8, max_tokens=2000, keep=4, llm=None):
 self.stm = ShortTermMemory(window=window, maxtokens=max_tokens) # 短期
 self.ltm = LongTermMemory() # 长期(Chroma)
 self.keep, self.max_tokens, self.llm = keep, max_tokens, llm

 def add(self, msg: dict, persist: bool = False):
 """① 永远进短期窗口; 只有明确用户事实才落长期(省嵌入开销)"""
 self.stm.add(msg)
 if persist and msg.get("role") == "user":
 self.ltm.add_fact(msg["content"], fid=_fid(msg["content"]))

 def get_context(self, query: str = None) -> list[dict]:
 """② 取上下文: 有query才召回; 召回结果临时拼接, 不污染buffer(防重复累加)"""
 base = self.stm.context() # [sys提示...] + [窗口内消息]
 if not query:
 return base
 facts = self.ltm.recall(query, k=3)
 if not facts:
 return base
 facts_msg = {"role": "system",
 "content": "已知用户长期事实: " + " | ".join(facts)}
 sys_msgs = [m for m in base if m.get("role") in self.stm.system_roles]
 others = [m for m in base if m.get("role") not in self.stm.system_roles]
 return sys_msgs + [facts_msg] + others # 系统提示 → 长期事实 → 窗口

 def maybe_compress(self, llm=None):
 """③ 超阈值才压; 压完写回buffer(下次context取到压缩后结果)"""
 llm = llm or self.llm
 if llm is None:
 return self.stm.buffer
 msgs = _auto_compress(self.stm.buffer, llm,
 max_tokens=self.max_tokens, keep=self.keep)
 if msgs is not self.stm.buffer: # 真的压缩了才写回
 self.stm.buffer = msgs
 return self.stm.buffer

 def recall(self, query: str, k: int = 3) -> list[str]:
 """④ 对外暴露长期检索(验收: 重启后仍能recall到DeepSeek)"""
 return self.ltm.recall(query, k=k)

五、踩坑记：maybe_compress 没压 ≠ bug

这堂课最值钱的一课，藏在昨天那条测试失败里。

一开始你写 test_e2e.py 断言"20 轮后 buffer ≤ 11"，结果断言挂了——因为 20 轮短对话根本没超过 2000 token 阈值，管家"正确地"没压。buffer 里 20 多条全是原文，自然 > 11。

第一次看到这个，本能反应是"压缩坏了"。但真相是：管家没触发压缩是对的。

“maybe_compress 没压 ≠ bug，而是没到压缩点。”

这句话面试官超爱听，因为它证明你理解的是决策逻辑，不是"会调用函数"。展开说就是：

压缩是阈值驱动的——token 数 > max_tokens 才压，跟"聊了几轮"无关。
20 轮如果每句都短，总 token 没超，就不该压；反过来哪怕只聊了 5 轮但每句都很长，也该压。

所以端到端测试要分两个场景验证，而不是断言"20 轮后一定被压"：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 场景1：没超阈值 → 不该压（这"不压"是正确行为）
mm = MemoryManager(window=8, max_tokens=2000, keep=4, llm=FakeSummarize())
... 20 轮 ...
assert len([m for m in mm.stm.buffer if m.get("is_summary")]) == 0
# ✅ 摘要0条 = 正确

# 场景2：阈值调小到300，20轮必超 → 该压（摘要恒1条）
mm2 = MemoryManager(window=8, max_tokens=300, keep=4, llm=FakeSummarize())
... 20 轮 ...
assert len([m for m in mm2.stm.buffer if m.get("is_summary")]) == 1
# ✅ 摘要1条 = 正确

心智模型：压缩不是"清理工"，是"应急收纳"——没满就别收拾。把断言从"一定会压"改成"该压时压、不该压时不压"，测试才真正卡住了管家的决策边界。

六、知识点补充：调度层背后的设计

1. 调度者模式（Coordinator / Facade）

MemoryManager 是典型的协调者模式：它不实现具体能力，而是编排已有能力。好处是边界清晰——三个小模块的逻辑各管各的，调度层只决定"何时让谁上"。W5（或更后面）把它搬进 LangGraph 的状态节点时，内部逻辑一行不用改，只改"谁调用谁"的接线。

2. 同名不同层：`compress.maybe_compress` vs `MemoryManager.maybe_compress`

这俩最容易混，其实层级完全不同：

名字	身份	干什么
`compress.maybe_compress`	纯函数	给它消息列表，它根据 token 数决定压不压、回不回原列表
`MemoryManager.maybe_compress`	调度方法	调用上面的纯函数 + 把结果写回 `self.stm.buffer`

纯函数不知道"管家"的存在，它只认消息；调度方法知道 buffer，它把纯函数的结果接回状态。职责切得干净，测试能单独测纯函数，也能单独测调度逻辑。

3. 临时拼接 vs 写回——信息流的两种走向

操作	走向	风险
`get_context` 召回结果	临时拼进返回，不写 buffer	写回会"重复累加"，buffer 越堆越大
`maybe_compress` 摘要	写回 buffer	不写回，下次 `context()` 取到的是未压缩的旧列表

这两条规则一正一反，正好是记忆系统的"呼吸节奏"：召回是吸气（借来用，不囤），压缩是呼气（旧的出去，留浓缩版）。

4. 内容哈希做稳定 ID

hashlib.md5(text).hexdigest()[:12] 给每条长期事实一个内容指纹：

同一句话多次 add，fid 相同 → Chroma 的 add(ids=[fid]) 会覆盖而非重复，天然去重。
跨进程稳定（不像 hash() 带随机盐），会话重启后"小明喜欢蓝色"还是同一个 ID，召回一致。

七、面试一句话复述

“MemoryManager 是调度者不是实现者——它只做三个决定：add 时决定是否落长期（persist 默认 False 省嵌入开销）、get_context 时决定是否召回（有 query 才查，结果临时拼接不污染 buffer 防重复累加）、maybe_compress 时决定是否压缩（超阈值才压，压完写回窗口）。它的代码很薄，因为逻辑都在三个小模块里，它只负责’何时让谁干活’。我之前整合时踩过一个坑：断言'20 轮后必然被压’结果挂了——后来明白压缩是阈值驱动不是轮数驱动，没超 max_tokens 不压才是正确的。这证明我测的是决策边界，不是函数会被调用。”

八、总结

MemoryManager 是接线板不是电器——它不实现记忆能力，只编排短期/长期/压缩三块的调用时机。
代码"薄"是正确标志——决策层不该有业务逻辑，逻辑都在底层模块。
三个决策点：add 落不落长期、get_context 召不召回、maybe_compress 压不压。
召回临时拼接、压缩写回 buffer——一吸一呼，信息流不重复累加。
压缩没触发 ≠ bug——阈值驱动，没超 max_tokens 不压才是正确行为。

给记忆系统装好调度台，三个模块就不再是散兵游勇，而是听一个开关指挥的流水线。你之前觉得"整合没思路"，本质是还在用"工人的眼睛"看"经理的活"——经理的活看起来像什么都没做，但恰恰是它让整条线转起来。

下一步（Day6）：做一个「带记忆的多轮 Agent demo」——跨会话记住偏好（长期）、长对话自动压缩（压缩）、必要时 Function Calling 调工具。到那时你会看到：没有 MemoryManager，demo 里每个功能都要手动接线；有了它，ChatSession 只需要几行代码。

附：远端文件（无需修改，仅参考）

D:\Desktop\AgentLearn\memory\manager.py —— 本文第四节的完整源码
D:\Desktop\AgentLearn\test_manager.py —— 质检员视角，5 项断言验证管家行为
D:\Desktop\AgentLearn\test_e2e.py —— 端到端，分"不压/该压/召回/系统提示永留"四场景验收

上下文压缩，提取摘要

Tue, 18 Aug 2026 14:52:23 +0800

把老历史浓缩成一条线：滚动摘要式上下文压缩的设计复盘

W3-Day4 · 上下文压缩昨天做完本地化持久化，今天解决另一个问题：对话越聊越长，context window 装不下了怎么办。

一、先搞清楚：为什么要压缩

Agent 跑久了，消息列表会无限增长。每轮对话都往 messages 里追加 user 和 assistant 的内容，几十轮下来，几个问题接踵而至：

问题	后果
Token 超限	大模型 context window 有上限（GPT-4o 128K，DeepSeek 64K），超了直接报错
成本飙升	API 按 token 计费，每轮都把全部历史重发一遍，费用线性增长
延迟增大	prompt 越长，推理越慢，用户等得越久
注意力稀释	上下文太长，模型对早期信息的关注度下降（“Lost in the Middle"问题）

新手的第一反应是截断——砍掉老消息，只留最近几轮。简单粗暴，但问题是：砍掉的信息就彻底没了。用户十轮前说的偏好、做过的决策，全丢了。

所以我们需要一种更聪明的办法：压是浓缩，不是丢掉。

二、压缩策略选型：三种思路对比

在写代码之前，先看看业界主流的上下文压缩方案：

策略	做法	优点	缺点
截断（Truncation）	只留最近 N 条，老消息直接扔	零成本、零延迟	信息完全丢失
提取（Extraction）	从老消息中抽取关键实体/事实，结构化存储	信息精确、可检索	需要 NER 或规则引擎，实现复杂
摘要（Summarization）	把老历史交给 LLM 浓缩成一段摘要	保留语义、实现简单	每次压缩多一次 LLM 调用；有信息损失

我们选的是摘要，具体来说是滚动摘要（Rolling Summary）——不积累多条摘要，而是永远只维护一条，新摘要覆盖旧摘要。

一句话记住：截断是删聊天记录，提取是做笔记，摘要是写周报。 周报写完，旧的聊天记录可以删，但信息以浓缩形式留住了。

三、核心设计：滚动摘要的三条铁律

铁律一：压什么——只压窗口外的老历史

消息列表不是铁板一块，压缩前先分三类：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


┌─────────────────────────────────────────────┐
│ messages 列表 │
│ │
│ ┌──────────────┐ ← 原系统提示（人格/角色设定）│
│ │ system (原) │ 永远不动，不参与压缩 │
│ ├──────────────┤ │
│ │ 历史摘要 │ ← 上一轮压缩产生的摘要 │
│ │ (is_summary) │ 每次压缩会被新摘要替换 │
│ ├──────────────┤ │
│ │ old messages │ ← 滚出窗口的老对话 │
│ │ (要被压缩的) │ 压完就扔，只留浓缩版 │
│ ├──────────────┤ │
│ │ recent × K │ ← 最近 K 条原文 │
│ │ (保留不压) │ 模型对"刚说的话"不能断片 │
│ └──────────────┘ │
└─────────────────────────────────────────────┘

关键：最近 K 条（4~6 轮）原文必须保留。为什么？因为模型需要对"刚刚的上下文"保持连贯理解。你压缩了上一轮的对话，模型回复就会前言不搭后语。

铁律二：什么时候压——懒触发

不是每轮对话都压缩。压缩要调一次 LLM（摘要本身也是一次推理），有成本有延迟。所以策略是：

超过 token 阈值才触发，没超就原样返回。

这就是 maybe_compress 干的事——先估算当前消息列表的 token 数，超了才调 compress，没超直接返回原列表。省一次 LLM 调用。

铁律三：压完别二次压缩

这是最容易被忽略的坑。压缩后，列表变成：

1

[原system, 摘要(is_summary=True), recent×4]

下次再触发压缩时，如果不把 is_summary 的消息单独拎出来，它会被当成"普通老消息"再压一遍。摘要的摘要，越压越短，信息指数级丢失——就像你把周报再写成周报的周报，最后只剩一句话。

解决办法：用 is_summary 标记区分"摘要"和"真实系统提示”，压缩时把旧摘要单独取出来，和新滚出窗口的原文合并成一条新摘要，旧的扔掉。永远只有一条摘要。

四、代码长什么样

memory/compress.py 一共四个函数，各管一段。下面逐块拆解，文末给出完整源码。

`_estimate_tokens` —— 零依赖的 token 估算

1
2
3


def _estimate_tokens(text: str) -> int:
 """粗略估算 token 数（无外部依赖）：中文约 0.6 token/字，英文约 4 字符/token。"""
 return max(1, int(len(text) * 0.6))

一行核心逻辑：max(1, int(len(text) * 0.6))。不引入 tiktoken 等外部依赖，按"中文约 0.6 token/字"粗估，够用于阈值判断。

知识点补充：Token 是什么？

Token 是大模型处理文本的最小单位。它不是"一个字"也不是"一个词"，而是介于两者之间的子词单元（subword）。OpenAI 用 BPE（Byte Pair Encoding）分词，DeepSeek 用类似的 tokenizer。大致规律：

语言	分词粒度	估算系数
中文	1 字 ≈ 0.6~1 token	`len(text) * 0.6` 粗估
英文	1 token ≈ 4 字符	`len(text) / 4` 粗估
代码	符号多，1 token ≈ 3~4 字符	比英文略碎

精确计数要用 tiktoken（OpenAI）或对应模型的 tokenizer，但做阈值判断时粗估就够了——我们不需要知道"到底 2999 还是 3001"，只需要知道"是不是该压了"。

`_fmt` —— 消息列表转纯文本

1
2
3


def _fmt(messages) -> str:
 """消息列表 → 纯文本（喂给 LLM 做摘要的原料）。"""
 return "\n".join(f"{m['role']}: {m['content']}" for m in messages)

一行 join：把结构化的 messages（OpenAI 格式的 list[dict]）拍平成 "role: content" 每条一行的纯文本，方便塞进一个 prompt 让 LLM 做摘要，也顺带作为 token 估算的输入。

`compress` —— 核心压缩逻辑

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27


def compress(messages: list[dict], llm, keep: int = 4) -> list[dict]:
 """滚动摘要版压缩。llm 需要提供 summarize(text) -> str 方法。"""
 # ① 三类消息分开：原系统提示 / 旧摘要 / 其余对话
 # 用 is_summary 标记区分"摘要"和"真实系统提示"，防止混为一谈
 sys_msgs = [m for m in messages
 if m.get("role") == "system" and not m.get("is_summary")]
 old_sums = [m for m in messages if m.get("is_summary")]
 others = [m for m in messages
 if m.get("role") != "system" and not m.get("is_summary")]

 if len(others) <= keep:
 return messages # 还没长到需要压，原样返回

 old, recent = others[:-keep], others[-keep:]

 # ② 滚动关键：旧摘要 + 新滚出窗口的原文 → 合并成一条新摘要
 # 这就是"写周报"：把上周周报和这周的事浓缩成一份新周报，旧的扔掉
 text = _fmt(old)
 if old_sums:
 text = f"已有摘要: {old_sums[-1]['content']}\n新增对话:\n{text}"

 # ③ 交给 LLM 浓缩。生产环境的提示词要强调：保留事实/决策/偏好、控制长度
 summary = llm.summarize(text)
 summary_msg = {"role": "system",
 "content": f"历史摘要: {summary}",
 "is_summary": True}
 return sys_msgs + [summary_msg] + recent

逐步拆解三个步骤：

① 分流：用列表推导把消息分成三桶——原系统提示、旧摘要、其余对话。is_summary 是我们自定义的消息字段——OpenAI 的消息格式只认 role 和 content，但你可以往 dict 里塞额外字段，模型不会报错（它只读 role 和 content，多余的忽略）。我们利用这点来做内部标记。分流后如果 len(others) <= keep，说明还没长到需要压，原样返回。

② 滚动合并：这是整个设计的核心。others[:-keep] 是滚出窗口的老对话，others[-keep:] 是最近 K 条原文。如果已有旧摘要，就把旧摘要内容拼到新对话前面，一起喂给 LLM——LLM 看到的是"已有摘要: xxx + 新增对话: yyy"，输出的是合并后的新摘要。旧摘要被新摘要替代，永远只有一条。

③ 重组：最终消息列表 = 原系统提示 + 一条摘要（is_summary=True）+ 最近 K 条原文。结构清晰，角色明确。

`maybe_compress` —— 自动触发器

1
2
3
4
5
6


def maybe_compress(messages, llm, max_tokens: int = 3000, keep: int = 4):
 """自动触发：超阈值才压，没超原样返回。"""
 if (_estimate_tokens(_fmt(messages)) > max_tokens
 and len(messages) > keep + 1):
 return compress(messages, llm, keep=keep)
 return messages

外层的守门员，正常对话循环里每轮调一次它。两个条件同时满足才压：

token 总量超过阈值（max_tokens）
消息条数大于 keep + 1（至少有一条可以压的旧消息）

为什么用 and 而不是 or？因为如果消息条数不够（比如就 3 条但每条特别长），没有足够的内容可以压缩，强行压只会把最近对话也塞进摘要，得不偿失。

完整代码

四个函数拼起来就是 memory/compress.py 的全部，可直接抄：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45


# memory/compress.py
"""Day4 上下文压缩：老历史 → 一条滚动摘要，永远只有一条。"""

def _estimate_tokens(text: str) -> int:
 """粗略估算 token 数（无外部依赖）：中文约 0.6 token/字，英文约 4 字符/token。"""
 return max(1, int(len(text) * 0.6))

def _fmt(messages) -> str:
 """消息列表 → 纯文本（喂给 LLM 做摘要的原料）。"""
 return "\n".join(f"{m['role']}: {m['content']}" for m in messages)

def compress(messages: list[dict], llm, keep: int = 4) -> list[dict]:
 """滚动摘要版压缩。llm 需要提供 summarize(text) -> str 方法。"""
 # ① 三类消息分开：原系统提示 / 旧摘要 / 其余对话
 # 用 is_summary 标记区分"摘要"和"真实系统提示"，防止混为一谈
 sys_msgs = [m for m in messages
 if m.get("role") == "system" and not m.get("is_summary")]
 old_sums = [m for m in messages if m.get("is_summary")]
 others = [m for m in messages
 if m.get("role") != "system" and not m.get("is_summary")]

 if len(others) <= keep:
 return messages # 还没长到需要压，原样返回

 old, recent = others[:-keep], others[-keep:]

 # ② 滚动关键：旧摘要 + 新滚出窗口的原文 → 合并成一条新摘要
 # 这就是"写周报"：把上周周报和这周的事浓缩成一份新周报，旧的扔掉
 text = _fmt(old)
 if old_sums:
 text = f"已有摘要: {old_sums[-1]['content']}\n新增对话:\n{text}"

 # ③ 交给 LLM 浓缩。生产环境的提示词要强调：保留事实/决策/偏好、控制长度
 summary = llm.summarize(text)
 summary_msg = {"role": "system",
 "content": f"历史摘要: {summary}",
 "is_summary": True}
 return sys_msgs + [summary_msg] + recent

def maybe_compress(messages, llm, max_tokens: int = 3000, keep: int = 4):
 """自动触发：超阈值才压，没超原样返回。"""
 if (_estimate_tokens(_fmt(messages)) > max_tokens
 and len(messages) > keep + 1):
 return compress(messages, llm, keep=keep)
 return messages

五、LLM 摘要提示词怎么写

代码里 llm.summarize(text) 是个接口约定——llm 对象需要提供 summarize 方法。生产环境里，这个方法的提示词至关重要：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


def summarize(self, text: str) -> str:
 """将对话历史浓缩为摘要。"""
 prompt = f"""请将以下对话历史浓缩为一段摘要。
要求：
1. 保留关键事实、用户偏好、已做决策、未完成任务
2. 省略寒暄、重复内容、无信息量的对话
3. 控制在200字以内
4. 用第三人称客观陈述，不要编造未提及的信息

对话内容：
{text}"""
 return self.chat([{"role": "user", "content": prompt}])

四条要求各有深意：

要求	为什么
保留事实/决策/偏好	这些是 Agent 后续行为依赖的信息，丢了就失忆
省略寒暄/重复	“你好"“谢谢"这类没有信息量，浪费摘要空间
控制长度	摘要本身也要占 token，不限制就失去了压缩的意义
第三人称客观陈述	防止 LLM 编造或脑补，只复述已有内容

六、踩坑记：二次压缩的信息坍缩

这个坑如果不踩一次，很难意识到。

假设没有 is_summary 标记，消息列表压缩后长这样：

1
2
3
4
5
6


# 第一次压缩后
[system(原), system(摘要), msg_5, msg_6, msg_7, msg_8]

# 又聊了4轮，触发第二次压缩
# 如果不区分摘要和普通消息，摘要会被当 old 再压一次
# 摘要的摘要 → 信息再砍一刀

每压一次，信息量打一个折扣。假设每次摘要保留 70% 的信息，压 5 次后只剩 0.7^5 ≈ 23%。这就是信息坍缩——和反复存 JPEG 一样，每存一次画质掉一档。

is_summary 标记的作用就是把旧摘要从"待压缩"队列里拎出来，单独和新的老对话合并成一条新摘要。旧摘要不会自己被再压，而是作为"已有摘要"参与新摘要的生成——信息有损失，但只损失一轮，不会指数级衰减。

心智模型：摘要不是消息列表里的普通一员，它是"历史浓缩版”，身份特殊。每次压缩时，它和新的老对话一起被重新浓缩，生成一条全新的摘要替代它。就像写周报：不是在旧周报上追加，而是把旧周报和这周的事一起重新写一份。

七、知识点补充：上下文压缩的更多背景

1. Context Window 与"Lost in the Middle”

大模型的 context window 不是"填多少都能用好"。研究表明，模型对 context 中间部分的信息关注度显著低于开头和结尾——这就是 “Lost in the Middle” 问题（Liu et al., 2023）。

这意味着：即使你的 context window 够大（128K），塞满历史消息也不一定有好效果。压缩不只是省 token，更是把模型注意力集中在最近对话上。

2. 摘要有界性

滚动摘要能控制 token 总量，前提是摘要本身有界。如果 LLM 每次摘要都写 1000 字，那摘要本身就成了新的负担。所以提示词里必须限制长度（如 200 字），保证：

1

总 token ≈ system(固定) + 摘要(有界) + recent×K(有界)

三项都有上界，总 token 就是 O(1) 级别的常数，不随对话轮次增长。

3. 其他压缩方案（了解即可）

方案	代表	思路
LLMLingua	Microsoft	用小模型做 token 级别的"软删除"——删掉对输出影响小的 token，保留重要的
MemGPT	UC Berkeley	操作系统式记忆管理——主内存(context) + 外存(磁盘)，按需"换页"加载
CompAct	LangChain	检测对话主题切换点，在主题边界做压缩，避免跨主题摘要信息混乱

我们的滚动摘要是最简方案：实现 40 行代码，够用，够理解原理。生产环境可以考虑接入 LLMLingua 做更细粒度的压缩。

八、总结

压缩是浓缩不是丢掉——滚动摘要把老历史浓缩成一条 system 消息，信息以压缩形式保留。
三类消息分流是防错的基础——原系统提示永留、摘要单独标记、普通对话才参与压缩。
懒触发省成本——没超阈值就不压，避免每轮对话都多一次 LLM 调用。
is_summary 标记防止信息坍缩——旧摘要不二次压缩，而是和新老对话合并成新摘要，永远只有一条。

给消息列表做个"收纳箱"：最近的东西放台面上随手拿（recent × K），老东西装箱贴标签（摘要），装箱后不重复装箱（is_summary）。箱子永远只有一个，但里面的东西是最新的浓缩版。

Memory on 男娘教主

LangChain_Memory

一、大局：记忆接在链的哪个位置

二、_to_lc：dict → LangChain 消息对象（快递打包）

三、lambda 表达式 + 字典解包（链首加料）

四、RunnableLambda：把函数变成能入链的零件（插头转换器）

五、完整可运行演示（不需要 API key）

六、lc_memory.py 完整代码（真实接 MemoryManager）

七、踩坑记 & 知识点

八、总结

九、下一篇预告

一二周整理

一、项目全景：四层 + 一个组装口

二、LLM 层：把"模型"抽象成可替换的零件

2.1 抽象基类 llm/base.py

2.2 非流式客户端 llm/real_llm.py

2.3 流式客户端 llm/stream_llm.py

2.4 config.json：模型与工具的"总清单"

三、记忆层：短期窗口 + 长期向量库 + 一条滚动摘要

3.1 路径集中管理 memory/paths.py

3.2 短期记忆 memory/shortmemory.py

3.3 长期记忆 memory/long_term.py

3.4 滚动摘要压缩 memory/compress.py

3.5 统一调度者 memory/memory_manager.py

四、工具层：注册表 + 自愈执行器 + 依赖注入

4.1 工具基类 tools/base.py

4.2 动态注册表 tools/registry.py

4.3 带"自愈"的执行器 tools/executor.py

4.4 四个工具的实现

五、Agent 层：Function Calling 循环 + 路由器 + 四种推理模式

5.1 Function Calling 主循环 agent/core.py

5.2 路由器 agent/router.py

5.3 四种推理模式 agent/modes/

六、组装口 agent/main.py：把四层粘起来

七、知识点总盘点

八、踩坑记合集（ debugging 实录）

九、总结

Manager

给 AI Agent 的记忆装个"调度台"：MemoryManager 为什么"薄"才是对的

一、先搞清楚：为什么需要一个调度台

二、热身：两个视角的文件，别被"蒙"

质检员在查什么（test_manager.py 的 5 项检查）

真店员的一天（chat_with_memory.py 的循环）

三、MemoryManager 到底在干嘛：就三个"决定"

四、代码长什么样（逐块讲解，最后放完整代码）

顶部：导入 + 稳定 ID 生成器

__init__ —— 把三个电器接上电

add —— 客人说的话，记哪？

get_context —— 上菜前，先查 VIP 档案？

maybe_compress —— 打烊前，工作台满了吗？

recall —— 对外暴露长期检索

完整代码

五、踩坑记：maybe_compress 没压 ≠ bug

六、知识点补充：调度层背后的设计

1. 调度者模式（Coordinator / Facade）

2. 同名不同层：compress.maybe_compress vs MemoryManager.maybe_compress

3. 临时拼接 vs 写回——信息流的两种走向

4. 内容哈希做稳定 ID

七、面试一句话复述

八、总结

附：远端文件（无需修改，仅参考）

上下文压缩，提取摘要

把老历史浓缩成一条线：滚动摘要式上下文压缩的设计复盘

一、先搞清楚：为什么要压缩

二、压缩策略选型：三种思路对比

三、核心设计：滚动摘要的三条铁律

铁律一：压什么——只压窗口外的老历史

铁律二：什么时候压——懒触发

铁律三：压完别二次压缩

四、代码长什么样

_estimate_tokens —— 零依赖的 token 估算

_fmt —— 消息列表转纯文本

compress —— 核心压缩逻辑

maybe_compress —— 自动触发器

完整代码

五、LLM 摘要提示词怎么写

六、踩坑记：二次压缩的信息坍缩

七、知识点补充：上下文压缩的更多背景

1. Context Window 与"Lost in the Middle”

2. 摘要有界性

二、`_to_lc`：dict → LangChain 消息对象（快递打包）

三、`lambda` 表达式 + 字典解包（链首加料）

四、`RunnableLambda`：把函数变成能入链的零件（插头转换器）

六、`lc_memory.py` 完整代码（真实接 MemoryManager）

2.1 抽象基类 `llm/base.py`

2.2 非流式客户端 `llm/real_llm.py`

2.3 流式客户端 `llm/stream_llm.py`

2.4 `config.json`：模型与工具的"总清单"

3.1 路径集中管理 `memory/paths.py`

3.2 短期记忆 `memory/shortmemory.py`

3.3 长期记忆 `memory/long_term.py`

3.4 滚动摘要压缩 `memory/compress.py`

3.5 统一调度者 `memory/memory_manager.py`

4.1 工具基类 `tools/base.py`

4.2 动态注册表 `tools/registry.py`

4.3 带"自愈"的执行器 `tools/executor.py`

5.1 Function Calling 主循环 `agent/core.py`

5.2 路由器 `agent/router.py`

5.3 四种推理模式 `agent/modes/`

六、组装口 `agent/main.py`：把四层粘起来

`init` —— 把三个电器接上电

`add` —— 客人说的话，记哪？

`get_context` —— 上菜前，先查 VIP 档案？

`maybe_compress` —— 打烊前，工作台满了吗？

`recall` —— 对外暴露长期检索

2. 同名不同层：`compress.maybe_compress` vs `MemoryManager.maybe_compress`

`_estimate_tokens` —— 零依赖的 token 估算

`_fmt` —— 消息列表转纯文本

`compress` —— 核心压缩逻辑

`maybe_compress` —— 自动触发器