Agent 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 就轮到「流程怎么分叉」。

Runnable

Mon, 24 Aug 2026 00:12:57 +0800

Runnable 组合件——并行、透传、加工、分支

翻车前的自白

昨天你拼出第一条链：prompt | model | parser——一步接一步，串行。

但真实应用从来不是一条直道：

想同时拿到「回答」和「关键词提取」→ 要并行，别等两次
想在链中间保留原始问题、再追加加工结果 → 要透传 + 追加
想把 W3 自研的 compress() / recall() 塞进链里 → 要把函数变成链的一环
想按问题类型走不同链路（天气 / 计算 / 默认）→ 要条件分支

昨天那四个需求，光靠 | 串不起来。今天这四件「组合件」就是干这个的——它们把「单链」升级成「有分流、合并、分支的管道」。

而且你会发现：每一件， W1-W3 都手写过一遍，只是名字不同。

一、为什么线性链不够用？

A | B | C 的本质是「上一个的输出，整个喂给下一个」。问题在于：

它只能串行：要两个产出就得跑两遍链，浪费 token 和时间。
它会「覆盖」输入：B 拿到的是 A 的输出，原始输入（比如用户原话）如果 A 改了，B 就拿不到了。
它接不进你的老代码：你 W3 的 compress() 是个普通 Python 函数，不是 Runnable，直接 | 会报错。
它不会「分叉」：所有输入走同一条路，无法按内容选不同处理。

这四件组合件，正好一一补上这四个缺口。

二、四件新武器（对照你的自研）

新武器	干啥的	你写过的对应物
`RunnableParallel`	一条输入，同时喂给 N 条链，结果合并成 dict	无（这是新能力：并行）
`RunnablePassthrough`	原样透传，常用 `.assign()` 保留原输入 + 追加新字段	`get_context` 里「保留原消息 + 插新消息」
`RunnableLambda`	把任意 Python 函数包成 Runnable	你的 `compress()` / `recall()` 自研函数
`RunnableBranch`	按条件把输入分到不同子链	你的 `auto_select` 路由

关键认知：RunnableParallel 是你之前「没有」的能力（手写并行要自己搞线程/异步）；其余三件，本质是把你 W1-W3 手写的逻辑，套上 Runnable 外壳——所以你不是学新东西，是在给旧轮子装「标准接口」，好让它们能进 | 管道。

三、逐个拆解（带代码）

① RunnableParallel —— 并行流水线

一条输入同时喂给多条链，最后汇总成一个 dict。键名就是你起的名字。

 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


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 RunnableParallel

load_dotenv()
model = ChatOpenAI(
 model="deepseek-v4-flash",
 api_key=os.getenv("DEEPSEEK_API_KEY"),
 base_url="https://api.deepseek.com",
)
parser = StrOutputParser()

# 两条子链：一个回答，一个提取关键词
answer_prompt = ChatPromptTemplate.from_messages([
 ("system", "你是一个简洁回答的助手"),
 ("user", "{question}"),
])
kw_prompt = ChatPromptTemplate.from_messages([
 ("system", "你是关键词提取器，请输出3个关键词，用逗号分隔"),
 ("user", "{question}"),
])
answer_chain = answer_prompt | model | parser
kw_chain = kw_prompt | model | parser

# 并行：一条 {"question": ...} 同时进两条链
parallel_chain = RunnableParallel(
 answer=answer_chain,
 keywords=kw_chain,
)

print("=== RunnableParallel 并行 ===")
res = parallel_chain.invoke({"question": "什么是LCEL？"})
print(res) # {'answer': '...', 'keywords': '...'}
print("类型:", {k: type(v).__name__ for k, v in res.items()}) # 每个值都是 str

对照你的自研：串行链只能「一次一个产出」。昨天你若想拿回答+关键词，得跑两遍。今天一句 RunnableParallel 搞定——这是你之前没有的新能力。

② RunnablePassthrough —— 复印机（保留 + 追加）

RunnablePassthrough 把输入原样传给下一步，不改动。它的升级版 .assign() 更常用：保留原输入，再追加新字段。

1
2
3
4
5
6
7
8
9


from langchain_core.runnables import RunnablePassthrough

# 保留 {"question": ...}，再追加「长度」「前5个字」
enrich = RunnablePassthrough.assign(
 长度=lambda x: len(x["question"]),
 前5个字=lambda x: x["question"][:5],
)
out = enrich.invoke({"question": "什么是LCEL？"})
print(out) # {'question': '什么是LCEL？', '长度': 7, '前5个字': '什么是LC'}

对照你的自研：这跟你 W3 get_context 里干的完全一致——「保留原消息列表 + 插入一条『已知用户长期事实』」。get_context 是你手写 sys_msgs + [facts_msg] + others 拼接；.assign() 是框架版「保留 + 插字段」。D3 接 MemoryManager 时就靠它保留窗口、追加长期事实。

③ RunnableLambda —— 临时加工站（D3 接 MemoryManager 的桥）

RunnableLambda 把任意 Python 函数包装成 Runnable，塞进链里。这是 D3 把你 W3 compress() / recall() 接进链的关键桥。

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


from langchain_core.runnables import RunnableLambda

def TextCleansing(text: str) -> str:
 """模拟自研后处理函数：去多余空格并截断到 50 字"""
 return " ".join(text.split())[:50]

# 函数包成 Runnable，直接接到链尾
chain_with_func = answer_prompt | model | parser | RunnableLambda(TextCleansing)

print("=== RunnableLambda 加工站 ===")
out_e = chain_with_func.invoke({"question": "用一句话介绍 LangChain"})
print(out_e)
print("类型:", type(out_e).__name__) # str

对照你的自研：TextCleansing 是个普通函数。你 W3 的 compress()（压缩）、recall()（召回）也是普通函数。把它们用 RunnableLambda(...) 一包，就能写进 | 管道——不用改函数内部一行代码。D3 的实战就是：get_context 包成 Lambda 接进链，让「取记忆」成为链的一环。

⚠️ 注意类型对接：Lambda 拿到的是上一个 Runnable 的输出类型。上面 parser 产出 str，所以 TextCleansing(text: str) 接收 str 才对得上。如果上一个产出是 dict，你的函数参数就得是 dict。

④ RunnableBranch —— 岔路口（W5 LangGraph 条件 edge 雏形）

RunnableBranch 按条件把输入分到不同子链。条件按顺序短路（第一个命中就走，不走后面的），最后一个是默认分支（无条件的 Runnable，不是元组）。

 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


from langchain_core.runnables import RunnableBranch

weather_prompt = ChatPromptTemplate.from_messages([
 ("system", "你是天气助手，用一句话回答天气问题"),
 ("user", "{question}"),
])
calc_prompt = ChatPromptTemplate.from_messages([
 ("system", "你是计算小助手，只输出计算结果"),
 ("user", "{question}"),
])
default_prompt = ChatPromptTemplate.from_messages([
 ("system", "你是智能助手，简要回答"),
 ("user", "{question}"),
])
weather_chain = weather_prompt | model | parser
calc_chain = calc_prompt | model | parser
default_chain = default_prompt | model | parser

# (条件, 子链) 元组列表 + 最后放默认链
branch = RunnableBranch(
 (lambda x: "天气" in x["question"], weather_chain),
 (lambda x: "计算" in x["question"], calc_chain),
 default_chain,
)

print("=== RunnableBranch 分支 ===")
for q in ["北京天气怎么样？", "计算 12*8", "你好呀"]:
 ans = branch.invoke({"question": q})
 print(f"问: {q}\n答: {ans}\n")

对照你的自研：这就是你 W2 的 auto_select 路由——「看用户输入，决定走哪条工具链」。RunnableBranch 把这套 if/elif 路由标准化了。它正是 W5 LangGraph「条件 edge」的雏形：在图里，节点之间的边可以按条件选走哪条。

四、可视化调试：get_graph().print_ascii()

链一复杂（并行、分支、Lambda），肉眼看不清数据流向。每个 Runnable 都能 .get_graph().print_ascii() 打印结构。

1
2
3
4
5


print("=== 并行链结构图 ===")
parallel_chain.get_graph().print_ascii() # 应看到 question → answer / keywords 两路

print("\n=== 分支链结构图 ===")
branch.get_graph().print_ascii() # 应看到按条件分三路

为什么必用：你改完一条链，先打一张图，比对着报错猜「数据从哪断的」快十倍。这是你排错的第一双眼——和昨天踩坑记里说的一样。

五、完整代码（可直接抄）

 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
84
85
86
87
88
89
90
91
92
93
94


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 (
 RunnableParallel,
 RunnablePassthrough,
 RunnableLambda,
 RunnableBranch,
)

load_dotenv()
model = ChatOpenAI(
 model="deepseek-v4-flash",
 api_key=os.getenv("DEEPSEEK_API_KEY"),
 base_url="https://api.deepseek.com",
)
parser = StrOutputParser()

# ---- 两条基础子链 ----
answer_prompt = ChatPromptTemplate.from_messages([
 ("system", "你是一个简洁回答的助手"),
 ("user", "{question}"),
])
kw_prompt = ChatPromptTemplate.from_messages([
 ("system", "你是关键词提取器，请输出3个关键词，用逗号分隔"),
 ("user", "{question}"),
])
answer_chain = answer_prompt | model | parser
kw_chain = kw_prompt | model | parser

# 步骤A1：RunnableParallel 并行
parallel_chain = RunnableParallel(
 answer=answer_chain,
 keywords=kw_chain,
)
print("=== 步骤A1：RunnableParallel 并行 ===")
res = parallel_chain.invoke({"question": "什么是LCEL？"})
print(res)
print("类型:", {k: type(v).__name__ for k, v in res.items()})

# 步骤A2：RunnablePassthrough.assign 追加字段
print("\n=== 步骤A2：RunnablePassthrough.assign 追加字段 ===")
enrich = RunnablePassthrough.assign(
 长度=lambda x: len(x["question"]),
 前5个字=lambda x: x["question"][:5],
)
out = enrich.invoke({"question": "什么是LCEL？"})
print(out)

# 步骤C：RunnableBranch 分支
weather_prompt = ChatPromptTemplate.from_messages([
 ("system", "你是天气助手，用一句话回答天气问题"),
 ("user", "{question}"),
])
calc_prompt = ChatPromptTemplate.from_messages([
 ("system", "你是计算小助手，只输出计算结果"),
 ("user", "{question}"),
])
default_prompt = ChatPromptTemplate.from_messages([
 ("system", "你只智能助手,简要回答"),
 ("user", "{question}"),
])
weather_chain = weather_prompt | model | parser
calc_chain = calc_prompt | model | parser
default_chain = default_prompt | model | parser

branch = RunnableBranch(
 (lambda x: "天气" in x["question"], weather_chain),
 (lambda x: "计算" in x["question"], calc_chain),
 default_chain,
)
print("\n=== 步骤C：RunnableBranch 分支 ===")
for q in ["北京天气怎么样？", "计算 12*8", "你好呀"]:
 ans = branch.invoke({"question": q})
 print(f"问: {q}\n答: {ans}\n")

# 步骤D：get_graph().print_ascii() 可视化
print("=== 步骤D：并行链结构图 ===")
parallel_chain.get_graph().print_ascii()
print("\n=== 步骤D：分支链结构图 ===")
branch.get_graph().print_ascii()

# 步骤E：RunnableLambda 接自研函数
def TextCleansing(text: str) -> str:
 """模拟自研函数，无实际逻辑处理"""
 return " ".join(text.split())[:50]

chain_with_func = answer_prompt | model | parser | RunnableLambda(TextCleansing)
print("\n=== 步骤E：RunnableLambda 加工站 ===")
out_e = chain_with_func.invoke({"question": "用一句话介绍 LangChain"})
print(out_e)
print("类型:", type(out_e).__name__)

六、踩坑记 & 知识点

① RunnableParallel 返回的是 dict，键名 = 你起的名 RunnableParallel(answer=..., keywords=...) 的结果永远是 {"answer": ..., "keywords": ...}。别指望它返回 str 或 list——它是「多产出汇总」，天然是 dict。验收直接 res["answer"]、res["keywords"]。

② RunnablePassthrough.assign 是「保留 + 追加」，不是「替换」 .assign(新键=...) 会保留原 dict 所有字段，再加新键。想「替换」某字段，得显式写 原键=lambda x: 新值。这点跟你 W3 get_context 的「sys_msgs + [facts_msg] + others 保留原系统提示」逻辑一致。

③ RunnableBranch 条件按顺序短路，默认分支必须放最后且无条件 (条件, 链) 元组从前往后判，命中第一个就走，后面不判。最后一个参数必须是裸 Runnable（不是元组），它是兜底。放反了（把默认放前面）会导致永远走默认。

④ RunnableLambda 的「输入输出类型」要对齐上一个 Runnable Lambda 收到的是管道里上一个的输出类型。parser 出 str → 你的函数参数就得是 str；若上一个出 dict → 参数得是 dict。类型对不上不会在定义时报错，会在 .invoke() 时炸——所以写完先跑一次。

⑤ get_graph().print_ascii() 是排错第一双眼 并行/分支链肉眼难 Debug。改完链先打图确认流向，再写业务逻辑。跟昨天踩坑记④一脉相承。

七、总结

今天四件组合件，把「单链」升级成「有分流、合并、分支的管道」：

RunnableParallel = 并行流水线（一条输入 → N 条链 → dict 汇总），是你之前没有的新能力
RunnablePassthrough = 复印机（.assign() 保留原输入 + 追加字段），对应你 W3 get_context 的「保留 + 插消息」
RunnableLambda = 加工站（任意函数包成 Runnable），是 D3 把 W3 compress()/recall() 接进链的桥
RunnableBranch = 岔路口（按条件走不同子链），对应你 W2 auto_select 路由，也是 W5 LangGraph 条件 edge 的雏形

它们和你 W1-W3 的自研一一对应——框架化不是学新东西，是把你的手动逻辑套上标准接口，好让它们能进 | 管道。

LangChain 入门 + LCEL

Sun, 23 Aug 2026 02:39:38 +0800

W4 · LCEL：用管道把零件串成流水线

关键词：LCEL / Runnable / 声明式 / 零件库 + 组装流水线前置：W1 llm_client、W2 fc_loop、W3 MemoryManager（全是手撸）收尾预告：W5 LangGraph —— node/edge 的雏形

翻车前的自白

W1 你写 llm_client，每次调完模型都要手动抠 resp.choices[0].message.content； W2 你写 fc_loop，自己拼 tools schema、解析 tool_calls、再写循环； W3 你写 MemoryManager，短期窗口、长期 Chroma、滚动压缩，全自己管。

回头看，这三周你一直在做同一件事：手动接线。

每加一个功能，就多一串「把 A 的输出塞进 B 的输入」的胶水代码。功能一多，胶水比功能还多——这就是手写 Agent 的隐性成本。

W4 要解决的，就是这团胶水。LCEL 不是新概念，是把你 W1-W3 的手动接线，标准化成一条「传送带」。

零、LangChain 是什么？

如果你之前只用手写 requests 或 openai SDK 直连大模型，第一次听到「LangChain」大概率会懵：这玩意儿和「直接调 API」差在哪？

一句话：LangChain 是一套给 LLM 应用用的「乐高积木 + 说明书」。

先想清楚：不用框架，你怎么调大模型？

裸调一个模型，你其实要手写一堆「杂活」：

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


# 没有框架时，一次问答你要操心的事
import openai

# 1. 自己拼消息格式
messages = [
 {"role": "system", "content": "你是一个简洁的助手"},
 {"role": "user", "content": "什么是 LCEL？"},
]

# 2. 自己发起请求
resp = openai.chat.completions.create(
 model="xxx",
 messages=messages,
)

# 3. 自己从嵌套结构里抠出文本
text = resp.choices[0].message.content

# 4. 想要流式？再写一套 chunk 拼接逻辑
# 5. 想要批量？再写一套并发
# 6. 想接数据库/工具/记忆？每一块都自己接线

上面 6 步，每一步都是「胶水」。功能越复杂，胶水越多。这就是你 W1-W3 手写 Agent 的真实体感——你不是在写业务，是在写「让零件转起来的 plumbing」。

LangChain 把这堆杂活标准化了

LangChain 做的事，本质上是把上面那些重复的 plumbing 抽成可复用的标准零件，再用统一的接口（Runnable）接起来：

1
2
3
4
5
6


没有框架： 有了 LangChain：
你写 plumbing ──→ 你只声明「要什么」：
requests请求 chain = prompt | model | parser
手抠 .content 框架自动：拼消息→请求→抠结果→流式/批量
自己写流式/批量
自己接工具/记忆

所以它不是「另一个能调模型的库」——openai SDK 也能调模型。它是「调模型之上的那层编排」：当你需要的不是「问一句话」，而是「带记忆、能查资料、会调工具、能多轮决策」的应用时，框架的价值才显出来。

LangChain 全家福（你后面会陆续碰到）

包名	干什么	你现在用到没
`langchain-core`	最核心：Runnable 接口、LCEL 管道、`	`
`langchain-openai`	把 OpenAI / DeepSeek(兼容) 等模型接进来	✅ 本文用到
`langchain-community`	社区集成：各种向量库、工具、检索器	⏳ 后面接 Chroma/工具时
`langchain`	上层高级封装（chains/agents 老接口）	⏳ 渐进接触
`langgraph`	有状态图编排（W5 主角）	⏳ 下周

记住一句话就够了：LangChain = 「调模型之上的编排层」。你 W1-W3 手写的那些零件，它都有现成的；你手写那些胶水，它用 | 一条管道替你接好。

回到开头那句自白：你前三周手写的所有东西，不是白写——它们让你亲手踩过每个零件的坑，所以现在看 LangChain，你是在「认领」自己造过的轮子，而不是从天书开始学。

一、LCEL 到底是什么？

LCEL（LangChain Expression Language）= 用 | 把零件串成流水线。

它是 LLM 应用的「零件库 + 组装流水线」：零件（模型、提示词、解析器、记忆、检索、工具）是标准化的，组装方式（管道 |）也是标准化的。

一句话记忆：| 就是传送带，前一个的输出自动变成后一个的输入。

为什么需要它（对照你的自研）

你自研的（W1-W3）	LangChain 里的名字	一句话
`RealLLM` / `llm_client`	`ChatOpenAI` / `ChatModel`	调模型的封装
`prompt_lib`（W1）	`ChatPromptTemplate`	提示词模板
手动取 `.content` / `json.loads`	`StrOutputParser` / `JsonOutputParser`	解析 AI 输出
`fc_loop` 工具循环（W2）	`Agent` / Tool Calling	工具调用循环
`MemoryManager`（W3）	`Memory`（或包一层自研）	记忆
Chroma 长期记忆（W3）	`Retriever` / `VectorStore`	向量召回
`tools/` 注册表（天气/计算器）	`@tool` 装饰器	工具标准接口

关键认知：框架化不是「学新东西」，是「把你的手动接线变成标准管道」。右边每一格，你左边都写过一遍——所以你不是在从零学，是在给旧东西换统一接口。

LangChain / LangGraph 是 Agent 岗位出现率最高的框架。会这套「通用语言」，比会某个手写实现更有市场价值。

二、八个零件：从你的自研到 LangChain

LangChain 把 LLM 应用拆成 8 个标准化零件。下面每个都对应你 W1-W3 的代码——你早就造过它们，只是名字不同。

 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


┌──────────────────────────────────────────────────────────┐
│ 1. Model（模型）= 厨师 │
│ 你已有 RealLLM。ChatOpenAI 是"统一厨师证"—— │
│ DeepSeek/通义/Kimi 都一个接口，走 OpenAI 兼容协议， │
│ 换 base_url 就行（你早就这么干了） │
├──────────────────────────────────────────────────────────┤
│ 2. Prompt（提示词模板）= 菜谱模板 │
│ 你 W1 的 prompt_lib。ChatPromptTemplate 支持 {变量} 插值： │
│ "请翻译成英文：{text}"，传 {"text":"你好"} 自动填 │
├──────────────────────────────────────────────────────────┤
│ 3. OutputParser（输出解析器）= 装盘 │
│ 你平时手动 json.loads(...)。StrOutputParser 把复杂输出 │
│ 变纯字符串；JsonOutputParser 帮你做 json.loads │
├──────────────────────────────────────────────────────────┤
│ 4. Chain / LCEL（链）= 传送带 ⭐ 本周核心 │
│ 前者的输出自动变后者的输入。"声明式"：你描述"要什么流程"， │
│ 不用写"怎么一步步调" │
├──────────────────────────────────────────────────────────┤
│ 5. Memory（记忆）= 记忆 │
│ 你 W3 的 MemoryManager 已经很强（短期窗口+长期Chroma+ │
│ 滚动压缩）。本周 D3 把它接进链，而不是重写 │
├──────────────────────────────────────────────────────────┤
│ 6. Retriever（检索器）= 档案室管理员 │
│ 你 W3 的 Chroma 就是这个。RAG 的"知识记忆"和你的 │
│ "长期向量记忆"是同一个东西——接一次复用，不另起炉灶 │
├──────────────────────────────────────────────────────────┤
│ 7. Tool（工具）= 工具箱 │
│ 你 W2 的天气、计算器。LangChain 用 @tool 装饰器把函数 │
│ 变成"模型可调用的工具" │
├──────────────────────────────────────────────────────────┤
│ 8. Agent（智能体）= 服务员 │
│ 你 W2 的 fc_loop：模型决定调哪个工具→执行→结果喂回→再决定。│
│ LangChain 的 Agent 把这个循环标准化了 │
└──────────────────────────────────────────────────────────┘

三个核心概念先记住（它们是 W5 LangGraph 的 node/edge 雏形）：

Chain = 组合：把零件用 | 串起来
Retriever = 取数：从外部/向量库取上下文
Tool = 可调函数：模型能主动调用的函数

三、工厂流水线：prompt | model | parser

LCEL 最小形态就是一条三件套链。| 是传送带——配料出来自动进加工机，加工完自动进包装机。

1
2
3
4
5
6
7
8
9


PromptInput ← 入口：你传的 {"question": "..."}（dict）
 ↓
ChatPromptTemplate ← 配料机：dict → [system, user] 消息列表
 ↓
ChatOpenAI ← 加工机：消息 → AIMessage
 ↓
StrOutputParser ← 包装机：AIMessage → 纯字符串
 ↓
StrOutputParserOutput ← 出口：str

声明式 vs 命令式（这是 LCEL 的精髓，面试爱问）：

命令式（你 W1-W3 的写法）：resp = client.chat(...); text = resp.choices[0].message.content——你写「怎么一步步调」
声明式（LCEL）：chain = prompt | model | parser——你只描述「要什么流程」，中间的传递、类型转换全交给框架

这就是为什么叫「表达式语言」：你写的是一个表达式（一条链），不是一串语句。

四、最小可跑代码（逐块讲解）

先装依赖（一行命令）：

1
2


pip install langchain langchain-openai langchain-community python-dotenv
pip install -U langchain langchain-openai langchain-core

① 配料机：ChatPromptTemplate

1
2
3
4
5
6
7


from langchain_core.prompts import ChatPromptTemplate

# {question} 是占位符，invoke 时传 dict 自动填
prompt = ChatPromptTemplate([
 ("system", "你是一个简洁的助手"),
 ("user", "{question}"),
])

对应你 W1 的 prompt_lib：把「系统提示 + 用户问题」拼成消息列表，但不用你手写 f-string 拼接了。

② 加工机：ChatOpenAI（接 DeepSeek）

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


import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI

load_dotenv()

# DeepSeek 走 OpenAI 兼容协议：换 model 名 + base_url 即可
model = ChatOpenAI(
 model="deepseek-v4-flash",
 api_key=os.getenv("DEEPSEEK_API_KEY"),
 base_url="https://api.deepseek.com",
)

对应你 W1 的 RealLLM：你当时就是靠 base_url 切到 DeepSeek 的。ChatOpenAI 是「统一厨师证」——DeepSeek、通义、Kimi 都是同一套接口，换 model + base_url 就行，不用为每家重写客户端。

③ 包装机：StrOutputParser

1
2
3
4


from langchain_core.output_parsers import StrOutputParser

# AIMessage → 纯字符串，对应你平时手写的 .content 提取
parser = StrOutputParser()

对应你 W1 手动抠的 resp.choices[0].message.content——现在一句 StrOutputParser() 替代，而且流式/批量场景自动适配。

④ 传送带：一条链

1
2


# 核心就这一行：前一个的输出自动喂给后一个
chain = prompt | model | parser

这就是本周核心。| 把三个零件声明式地组装成 Runnable。

⑤ 三种调用方式

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


# invoke：一次性拿到完整结果
result = chain.invoke({"question": "什么是 LCEL？"})
print(isinstance(result, str)) # True ← 这才是验收

# stream：流式，一个字一个字往外冒（对应你 W3 博客里写的 streaming）
for chunk in chain.stream({"question": "数到5"}):
 print(chunk, end="", flush=True)

# batch：一次处理多个输入，框架自动并行
results = chain.batch([
 {"question": "1+1=?"},
 {"question": "2+2=?"},
])
print(results)

# get_graph：把链结构打印成 ASCII 图，肉眼确认流向
chain.get_graph().print_ascii() # 应看到 prompt → model → parser

invoke / stream / batch 是 LCEL 所有 Runnable 的统一三件套——你写的任何链都自动获得这三种能力，不用自己实现。

五、完整代码（可直接抄）

 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


# 安装依赖
# pip install langchain langchain-openai langchain-community python-dotenv
# pip install -U langchain langchain-openai langchain-core

# 最小 LCEL 链：管道 prompt | model | parser

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

load_dotenv()

# 配料机：{question} → [system, user] 消息
prompt = ChatPromptTemplate([
 ("system", "你是一个简洁的助手"),
 ("user", "{question}"),
])

# 加工机：ChatOpenAI 接 DeepSeek（OpenAI 兼容协议，换 base_url 即可）
model = ChatOpenAI(
 model="deepseek-v4-flash",
 api_key=os.getenv("DEEPSEEK_API_KEY"),
 base_url="https://api.deepseek.com",
)

# 包装机：AIMessage → 纯字符串
parser = StrOutputParser()

# 传送带：一条链
chain = prompt | model | parser

# 调用
print("=== invoke ===")
result = chain.invoke({"question": "什么是 LCEL？"})
# StrOutputParser 返回 Python str
print(isinstance(result, str)) # True ← 这才是验收

print("\n=== stream（流式，一个字一个字冒）===")
for chunk in chain.stream({"question": "数到5"}):
 print(chunk, end="", flush=True)

print("\n\n=== batch（一次处理多个）===")
results = chain.batch([
 {"question": "1+1=?"},
 {"question": "2+2=?"},
])
print(results)

print("\n=== 链结构图 ===")
chain.get_graph().print_ascii() # 应看到 prompt → model → parser 的流向

六、踩坑记 & 知识点

① 验收用 isinstance(result, str)，别 assert 具体类名 StrOutputParser 在不同 LangChain 版本里，底层返回类型可能裹一层包装类型（比如某些版本会看到 TextAccessor 这类名字）。跨版本会变的是具体类名，不会变的是「它是 str 的子类」。所以稳健验收写 isinstance(result, str) == True，不要写 type(result).__name__ == 'str'，后者会在版本升级时假红。

② DeepSeek 是 OpenAI 兼容协议，不是特例 你 W1 的 RealLLM 已经验证了 base_url="https://api.deepseek.com" 这套走法。ChatOpenAI 只是把这套走法做成标准接口——model 名按 DeepSeek 官方给的填（笔记里写的 deepseek-v4-flash 按你当时环境填，真实环境以官方模型名为准），api_key 走环境变量，别硬编码进代码（呼应你 Vibe Coding 手册里的「密钥不上库」红线）。

③ 「声明式」省的是胶水，不是脑子 chain = prompt | model | parser 看起来比手写 resp = ...; text = ... 短，但它没替你设计流程——你 still 得想清楚「先配料、再加工、再装盘」的顺序。LCEL 把「传递」自动化了，把「架构决策」留给你。这也是为什么 W3 的 MemoryManager 不用重写、直接包一层接进链——决策逻辑是你的，管道只是载体。

④ get_graph().print_ascii() 是你的排错眼 链一复杂（尤其后面接 Retriever / Tool / Memory），print_ascii() 能一眼看出「数据从哪流到哪、有没有断」。每次改完链先打一张图，比对着报错猜快十倍。

七、总结

LangChain 是 LLM 应用的编排框架：模型、提示词、解析器、记忆、检索、工具都标准化成 Runnable，用 LCEL 管道（|）声明式组合。

它和你 W1-W3 的自研一一对应——RealLLM=ChatModel、prompt_lib=ChatPromptTemplate、手动解析=OutputParser、fc_loop=Agent、MemoryManager=Memory、Chroma=Retriever。所以框架化不是学新东西，是把你的手动接线变成标准管道。

三个核心概念记住：Chain=组合、Retriever=取数、Tool=可调函数——这正是 W5 LangGraph 的 node/edge 雏形。

一二周整理

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 —— 端到端，分"不压/该压/召回/系统提示永留"四场景验收

Agent on 男娘教主

LangChain_Memory

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

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

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

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

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

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

七、踩坑记 & 知识点

八、总结

九、下一篇预告

Runnable

Runnable 组合件——并行、透传、加工、分支

翻车前的自白

一、为什么线性链不够用？

二、四件新武器（对照你的自研）

三、逐个拆解（带代码）

① RunnableParallel —— 并行流水线

② RunnablePassthrough —— 复印机（保留 + 追加）

③ RunnableLambda —— 临时加工站（D3 接 MemoryManager 的桥）

④ RunnableBranch —— 岔路口（W5 LangGraph 条件 edge 雏形）

四、可视化调试：get_graph().print_ascii()

五、完整代码（可直接抄）

六、踩坑记 & 知识点

七、总结

LangChain 入门 + LCEL

W4 · LCEL：用管道把零件串成流水线

翻车前的自白

零、LangChain 是什么？

先想清楚：不用框架，你怎么调大模型？

LangChain 把这堆杂活标准化了

LangChain 全家福（你后面会陆续碰到）

一、LCEL 到底是什么？

为什么需要它（对照你的自研）

二、八个零件：从你的自研到 LangChain

三、工厂流水线：prompt | model | parser

四、最小可跑代码（逐块讲解）

① 配料机：ChatPromptTemplate

② 加工机：ChatOpenAI（接 DeepSeek）

③ 包装机：StrOutputParser

④ 传送带：一条链

⑤ 三种调用方式

五、完整代码（可直接抄）

六、踩坑记 & 知识点

七、总结

一二周整理

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

二、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 生成器

二、`_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`