男娘教主

HUGO搭建笔记

Sun, 06 Mar 2022 00:00:00 +0000

HUGO搭建笔记

通过Git推送到GitHub

安装git，下一步点到底 https://git-scm.com/install/windows
把 GitHub 仓库克隆到本地

1
2


 git clone https://github.com/AX7Princess/AX7Princess.github.io.git
 cd AX7Princess.github.io

在本地写文章
- 用 VS Code 打开这个文件夹。
- 在 content/posts/ 目录下新建 .md 文件，用 Markdown 写文章。
- 如果需要图片，放到 static/images/ 目录下。
推送到 GitHub

在本地终端（项目目录下）执行：

1
2
3


git add .
git commit -m "新增文章：xxx"
git push

你的代码就会推送到 GitHub。

服务器自动拉取并构建

推送后，你需要让服务器上的 /root/my-blog 目录自动拉取最新代码并重新生成网站。

在服务器上执行：

1

crontab -e

执行后会让打开编辑器，这里选nano，在文件末尾添加一行（每 5 分钟检查一次更新）：

1

*/5 * * * * cd /root/my-blog && git pull && hugo --minify

这行命令的含义：

*/5 * * * *：每5分钟执行一次。
cd /root/my-blog：进入博客目录。
git pull：从 GitHub 拉取最新代码。
hugo –minify：重新生成静态网站。

验证定时任务是否添加成功

1

crontab -l

会显示你刚才添加的那一行，说明已生效。

Welcome to Hugo theme Stack. This is your first post. Edit or delete it, then start writing!

For more information about this theme, check the documentation: https://stack.jimmycai.com/

Want a site like this? Check out hugo-theme-stack-stater

Photo by Pawel Czerwinski on Unsplash

LangChain

Tue, 25 Aug 2026 07:56:58 +0800

LangChain

一、LangChain 是什么（架构总览）

一句话定位

LangChain = 调模型之上的"编排层"。 它不替你调模型（那还是 OpenAI/DeepSeek 的活），它解决的是"调完模型之后那一堆 plumbing"：拼提示词、解析输出、接记忆、接检索、接工具、把流程串成管道。

你之前 W1-W3 手写过的 RealLLM / prompt_lib / fc_loop / MemoryManager / Chroma，在 LangChain 里都有标准件对应。学 LangChain 不是学新东西，是把你的"手动接线"换成"标准管道"。

全景架构图

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


┌──────────────────────────────────────────────────────────────┐
│ 你的应用 / Agent │
├──────────────────────────────────────────────────────────────┤
│ LangChain 编排层（本文重点） │
│ │
│ Prompt ──▶ Model ──▶ OutputParser （基础链 LCEL） │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ Memory Retriever Tool ◀── Agent（决定调谁） │
│ (记忆) (RAG检索) (工具) │
│ │
│ RunnableParallel / Passthrough / Lambda / Branch（组合件） │
│ LangGraph（状态图：把上面这些编排成有环的流程） │
├──────────────────────────────────────────────────────────────┤
│ langchain-core / langchain-openai / community（接入层） │
├──────────────────────────────────────────────────────────────┤
│ 模型供应商 API（DeepSeek / OpenAI / 通义 / Kimi ...） │
└──────────────────────────────────────────────────────────────┘

包结构 —— 别一股脑 `pip install langchain` 就完事

1
2
3
4
5
6


pip install langchain-core # 核心抽象：Runnable / Prompt / Parser / 基础接口（必装）
pip install langchain-openai # OpenAI 及兼容协议（DeepSeek 走这）的模型接入
pip install langchain-community # 社区集成：各种向量库、文档加载器、第三方工具
pip install langchain # 高层封装：agent / chain / 一些 conveniences（可选）
pip install langgraph # 状态图编排（W5 用，独立包）
pip install python-dotenv # 读 .env 里的密钥

包	干啥	你现在用得到吗
`langchain-core`	Runnable 协议、Prompt、Parser、Message 类型	✅ 必用
`langchain-openai`	`ChatOpenAI` 模型封装	✅ 必用
`langchain-community`	Chroma / FAISS / 各类 loader	✅ 做 RAG 用
`langchain`	旧的 `LLMChain`、`Agent` 封装	⚠️ 历史包袱多，新项目优先用 core + LCEL
`langgraph`	状态图 / 多轮循环编排	✅ W5 进阶

⚠️ 版本兼容是头号坑：LangChain 迭代极快，旧博客里的 LLMChain(...)、ConversationChain 在新版已弃用。本文全部基于 LCEL（core 0.2+） 写法，这是目前最稳、官方主推的范式。

裸调 vs LangChain 对照（先理解痛点）

1
2
3
4
5
6
7


# ===== 裸调（你 W1 的写法）=====
import openai
resp = openai.ChatCompletion.create(
 model="deepseek-chat",
 messages=[{"role": "user", "content": "你好"}]
)
text = resp["choices"][0]["message"]["content"] # 每次都要抠这一长串

1
2
3
4
5
6
7


# ===== LangChain（声明式）=====
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser

chain = ChatPromptTemplate.from_messages([("user", "{q}")]) | ChatOpenAI(...) | StrOutputParser()
text = chain.invoke({"q": "你好"}) # 一行拿到字符串，不用抠 dict

差别：裸调你写 plumbing，LangChain 你只声明"要什么流程"。

二、安装与环境

`pip install` —— 装依赖

1

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

-U 升级到最新版；建议锁版本做笔记：pip freeze > requirements.txt。

`.env` + `load_dotenv` —— 密钥分离

1
2
3
4
5


import os
from dotenv import load_dotenv

load_dotenv() # 自动读取项目根目录的 .env 文件
api_key = os.getenv("DEEPSEEK_API_KEY") # 从环境变量取，绝不硬编码进代码

.env 文件内容（放项目根目录）：

1

DEEPSEEK_API_KEY=sk-xxxxxxx

⚠️ 密钥红线：.env 必须写进 .gitignore，绝对不能 commit 进仓库。一旦泄露，第一时间去平台注销密钥并换新的（你一直强调的安全意识，这里再次强调）。

三、Model 模型：ChatModel

`ChatOpenAI` —— 统一接口调任意兼容模型

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


from langchain_openai import ChatOpenAI
import os

# DeepSeek 走 OpenAI 兼容协议：换 base_url 就行
model = ChatOpenAI(
 model="deepseek-chat", # 模型名（DeepSeek 用 deepseek-chat / deepseek-reasoner）
 api_key=os.getenv("DEEPSEEK_API_KEY"), # 从环境变量取
 base_url="https://api.deepseek.com", # 兼容协议入口
 temperature=0.7, # 随机性：0= deterministic，1= 发散
 max_tokens=1024, # 单次最多生成多少 token
)

参数	作用	常用值
`model`	模型名	`deepseek-chat` / `gpt-4o` / `qwen-max`
`temperature`	采样温度	0（严谨）/ 0.7（创意）/ 1（发散）
`max_tokens`	上限	按任务定，默认往往偏小
`streaming`	是否流式	`True` 时支持 `.stream()`
`base_url`	兼容入口	DeepSeek=`https://api.deepseek.com`

你 W1 的 RealLLM 其实就是这个 ChatOpenAI 的封装。所谓"统一厨师证"——不管底层是 DeepSeek 还是通义，接口都长一样，换模型只改两个字段。

`invoke` / `stream` / `batch` —— 三种调用方式

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


# 1) invoke：一次拿完整结果（最常用）
msg = model.invoke("你好") # 返回 AIMessage 对象
print(msg.content) # 取文本用 .content

# 2) stream：流式，一个字一个字冒（适合聊天界面）
for chunk in model.stream("写一首诗"):
 print(chunk.content, end="", flush=True)

# 3) batch：一次塞多个输入，并发处理（比循环 invoke 快）
results = model.batch(["1+1=?", "2+2=?"])
print([r.content for r in results])

这三个方法来自 Runnable 协议，后面所有组件（Prompt/Parser/Chain）都支持，这是 LCEL 能串起来的底层原因。

四、Prompt 提示词模板：ChatPromptTemplate

`ChatPromptTemplate.from_messages` —— 构造消息模板

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


from langchain_core.prompts import ChatPromptTemplate

# 用 (角色, 文本) 元组列表；{q} 是占位变量
prompt = ChatPromptTemplate.from_messages([
 ("system", "你是一个乐于助人的助手。"), # system 角色
 ("user", "{q}"), # user 角色，{q} 待填
])

# 调用时传字典填充变量
messages = prompt.invoke({"q": "什么是 LCEL？"})
print(messages.to_messages()) # 得到 [SystemMessage, HumanMessage]

你 W1 的 prompt_lib 干的就是这事——ChatPromptTemplate 是它的框架标准版，支持 {变量} 插值。

`MessagesPlaceholder` —— 历史消息占位

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


from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

prompt = ChatPromptTemplate.from_messages([
 ("system", "你是有记忆的助手。"),
 MessagesPlaceholder("history"), # 这里会展开成一串历史消息对象
 ("user", "{question}"),
])

# 调用时 history 必须传"消息对象列表"（不是 dict）
from langchain_core.messages import HumanMessage, AIMessage
chain.invoke({
 "question": "我叫什么？",
 "history": [HumanMessage(content="我叫小明"), AIMessage(content="你好小明")]
})

⚠️ placeholder 要配消息对象列表，不是 dict 列表。你自研记忆返回的是 dict，必须先用 _to_lc 转换（见第八节）。

`partial` —— 预填部分变量

1
2
3
4


# 有些变量每次都一样（如固定语言），可以提前 partial 掉
prompt = ChatPromptTemplate.from_messages([("system", "用{lang}回答：{q}")])
prompt_zh = prompt.partial(lang="中文") # 预填 lang，之后只需传 {q}
print(prompt_zh.invoke({"q": "你好"}).to_messages())

五、OutputParser 输出解析器

`StrOutputParser` —— 把 AIMessage 变成纯字符串

1
2
3
4
5


from langchain_core.output_parsers import StrOutputParser

parser = StrOutputParser()
text = parser.invoke(model.invoke("你好")) # AIMessage → str
print(type(text)) # <class 'str'>

`JsonOutputParser` —— 解析 JSON 输出

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


from langchain_core.output_parsers import JsonOutputParser
from langchain_core.prompts import ChatPromptTemplate

parser = JsonOutputParser()
prompt = ChatPromptTemplate.from_messages([
 ("system", "只输出 JSON，不要解释。{format_instructions}"),
 ("user", "列出三种水果和颜色"),
])

# JsonOutputParser 会给你一段"格式说明"塞进 prompt
chain = prompt | model | parser
data = chain.invoke({"format_instructions": parser.get_format_instructions()})
print(data) # 已经是 dict，不用自己 json.loads

`PydanticOutputParser` —— 强类型结构化（进阶）

1
2
3
4
5
6
7
8
9


from pydantic import BaseModel, Field
from langchain_core.output_parsers import PydanticOutputParser

class Person(BaseModel):
 name: str = Field(description="姓名")
 age: int = Field(description="年龄")

parser = PydanticOutputParser(pydantic_object=Person)
# parser.get_format_instructions() 会生成"必须输出符合 Person schema 的 JSON"

你平时手动 json.loads(...)，就是 StrOutputParser/JsonOutputParser 的活。框架的价值：连"格式说明"都帮你自动生成。

⚠️ 验收坑：StrOutputParser 在某些版本内部可能把结果裹一层包装类型（如旧版的 TextAccessor）。稳健验收写 isinstance(result, str)，别断言具体类名——类名会变，str 子类关系不会变。

六、LCEL 链：Runnable 与管道

`chain = prompt | model | parser` —— 一条最小链

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


from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from langchain_core.output_parsers import StrOutputParser
import os

prompt = ChatPromptTemplate.from_messages([("system", "你是一个简洁助手"), ("user", "{question}")])
model = ChatOpenAI(model="deepseek-chat", api_key=os.getenv("DEEPSEEK_API_KEY"),
 base_url="https://api.deepseek.com")
parser = StrOutputParser()

# | 就是传送带：前一个输出自动变成后一个输入
chain = prompt | model | parser

# 调用
print(chain.invoke({"question": "什么是 LCEL？"})) # 直接拿到 str

工厂流水线类比：

prompt = 配料机（dict → 消息列表）
model = 加工机（消息 → AIMessage）
parser = 包装机（AIMessage → 纯字符串）
| = 传送带（自动流转）

`get_graph().print_ascii()` —— 可视化整条链

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


chain.get_graph().print_ascii()
# 输出：
# PromptInput
# |
# ChatPromptTemplate
# |
# ChatOpenAI
# |
# StrOutputParser
# |
# StrOutputParserOutput

排错神器：链不工作时先打印结构图，看数据流向对不对。

Runnable 协议 —— 为什么能 `|`

所有 LangChain 组件都实现 Runnable 接口，至少有 invoke / stream / batch 三个方法。| 运算符本质是"把左边输出喂给右边输入"。普通 Python 函数没有这接口，必须先包成 RunnableLambda（见第七节）才能入链。

七、Runnable 组合件

`RunnableParallel` —— 一条输入，并行出多个结果

1
2
3
4
5
6
7
8
9


from langchain_core.runnables import RunnableParallel

# 同一条 question 同时喂给"回答链"和"关键词链"
parallel = RunnableParallel(
 answer=answer_chain, # 键名 answer 会成为结果 dict 的键
 keywords=kw_chain,
)
res = parallel.invoke({"question": "什么是 LCEL？"})
# res = {"answer": "...", "keywords": "..."} 返回 dict

你 W1-W3 没有"并行"概念，这是框架新增能力：一条输入复制多份，同时跑不同子链。

`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？"})
# out = {"question": "什么是LCEL？", "长度": 7, "前5字": "什么是LC"}

这等价于字典解包 {**x, "新字段": ...}——你 W3 get_context 里"保留原消息 + 插新消息"的思路，框架用 .assign 标准化了。

`RunnableLambda` —— 任意 Python 函数入链（适配器）

1
2
3
4
5
6
7


from langchain_core.runnables import RunnableLambda

def 清洗(text: str) -> str:
 return " ".join(text.split())[:50] # 普通函数，参数类型要对接上一个 Runnable 的输出

chain = answer_chain | RunnableLambda(清洗) # 把函数包成 Runnable，才能用 |
print(chain.invoke({"question": "介绍 LangChain"}))

类比"插头转换器"：普通函数是两脚插头，LangChain 管道是三脚插座，套个 RunnableLambda 就通了。这也是你把 W3 自研 MemoryManager / compress() 接进链的桥。

`RunnableBranch` —— 条件分支（按判断走不同子链）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


from langchain_core.runnables import RunnableBranch

branch = RunnableBranch(
 (lambda x: "天气" in x["question"], weather_chain), # 条件1 成立 → 天气链
 (lambda x: "计算" in x["question"], calc_chain), # 条件2 成立 → 计算链
 default_chain, # 都不成立 → 默认链（必须放最后）
)

for q in ["北京天气？", "计算 12*8", "你好"]:
 print(branch.invoke({"question": q}))

条件短路：从上到下匹配，命中第一个就走，所以默认链必须置底。这是 W5 LangGraph 条件 edge 的雏形。

八、Memory 记忆

三种记忆模式

模式	存啥	对应你 W3
短期（窗口）	最近 N 轮对话	`ShortTermMemory`
长期（向量）	用户事实 / 知识	`LongTermMemory` + Chroma
压缩	老历史 → 一条摘要	`compress.py`

用 `RunnableLambda` 接入自研 `MemoryManager`（重点）

你的 MemoryManager.get_context() 返回 dict 列表，但 prompt 的 MessagesPlaceholder 要 消息对象列表。中间必须有一道"格式转换"——这就是 _to_lc：

 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


from langchain_core.messages import SystemMessage, HumanMessage, AIMessage
from langchain_core.runnables import RunnableLambda

# 桥的包装器：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（失败则降级最小窗口版）
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 _MiniMM:
 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):
 self.buf.append({"role": "user", "content": t})
 def add_ai(self, t):
 self.buf.append({"role": "assistant", "content": t})
 _mm = _MiniMM()
 def get_history(x):
 return [_to_lc(m) for m in _mm.get_context()]

# 链首用 RunnableLambda 加料：保留 question，追加 history 字段
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

for q in ["我叫小明，喜欢打篮球", "我刚说的爱好是什么？", "我名字叫什么？"]:
 print(f"Q: {q}\nA: {ask(q)}\n")

⚠️ 相对导入坑：上面的 from memory.memory_manager import ... 直接 python lc_memory.py 跑会炸（脚本被当顶层模块，.. / 包路径解析不了）。修法有二：① sys.path.insert(0, 项目根目录) + 绝对导入；② 用 python -m 包名.模块名 启动。你 W3 调试时踩过同款坑，这里是标准解法。

关键设计：MemoryManager 不重写，只包一层——延续你 W3 的"调度者不重写逻辑"原则。get_context / compress 原样复用，框架只是多了一个入口适配器。

九、Retriever 检索与 RAG

RAG 流程：文档 → 切分 → 向量化 → 存入 → 检索 → 拼进 prompt

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


from langchain_community.vectorstores import Chroma
from langchain_community.embeddings import HuggingFaceEmbeddings
from langchain_text_splitters import RecursiveCharacterTextSplitter

# 1) 切分文档
splitter = RecursiveCharacterTextSplitter(chunk_size=500, chunk_overlap=50)
docs = splitter.create_documents([open("知识库.txt", encoding="utf-8").read()])

# 2) 向量化 + 存入 Chroma（你 W3 的 Chroma 长期记忆就是它）
embeddings = HuggingFaceEmbeddings(model_name="BAAI/bge-small-zh-v1.5")
vectordb = Chroma.from_documents(docs, embeddings, persist_directory="./chroma_db")

# 3) 检索器：query → 相关片段
retriever = vectordb.as_retriever(search_kwargs={"k": 3})
hits = retriever.invoke("退款政策是什么？")
print([d.page_content for d in hits])

你 W3 的"长期向量记忆"和 RAG 的"知识检索"是同一个东西——Chroma 接一次复用，不用另起炉灶。

接进链（检索增强问答）

1
2
3
4
5
6
7


from langchain_core.runnables import RunnablePassthrough

# 用 .assign 把检索结果拼进上下文，原 question 保留
rag_chain = (
 {"context": retriever, "question": RunnablePassthrough()}
 | rag_prompt | model | parser
)

十、Tool 工具与 @tool

`@tool` —— 把函数变成模型可调用的工具

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


from langchain_core.tools import tool

@tool
def calculator(expr: str) -> str:
 """计算一个数学表达式。"""
 return str(eval(expr))

@tool
def get_weather(city: str) -> str:
 """查询某城市天气。"""
 return f"{city} 今天晴，25℃"

# 模型能"看到"工具的描述和参数，自己决定调哪个
tools = [calculator, get_weather]
model_with_tools = model.bind_tools(tools)

你 W2 的 fc_loop 手写了"拼 tool schema + 解析 tool_calls + 循环"。@tool 装饰器把函数自动变成标准接口，省掉手写 schema。

`bind_tools` + 工具调用循环

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


from langchain_core.messages import HumanMessage, ToolMessage

msg = model_with_tools.invoke("北京天气怎么样？计算 12*8")
# msg.tool_calls 里有模型想调的工具和参数
for call in msg.tool_calls:
 fn = {"calculator": calculator, "get_weather": get_weather}[call["name"]]
 result = fn.invoke(call["args"]) # 执行工具
 # 把结果回灌给模型，让它继续决定下一步（这就是 Agent 循环）
 follow = model_with_tools.invoke([
 HumanMessage("北京天气怎么样？计算 12*8"),
 msg,
 ToolMessage(content=str(result), tool_call_id=call["id"]),
 ])

十一、Agent 智能体

本质：模型决定调哪个工具 → 执行 → 结果喂回 → 再决定

你 W2 的 fc_loop 就是这个循环的标准化版本。LangChain 提供 create_react_agent 等高级封装：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


from langchain.agents import create_react_agent, AgentExecutor

prompt = ChatPromptTemplate.from_messages([
 ("system", "你是一个助手，可用工具完成任务。"),
 ("user", "{input}"),
 ("assistant", "{agent_scratchpad}"), # 思考轨迹占位
])
agent = create_react_agent(model_with_tools, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

print(executor.invoke({"input": "北京天气怎么样？再算下 12*8"})["output"])

AgentExecutor 帮你把"调模型 → 解析 tool_calls → 执行 → 回灌"的循环跑完。你自研的 fc_loop 逻辑完全等价，只是它更通用。

十二、Callbacks 回调

监听链路每一步事件（调试 / 日志 / 计费）

1
2
3
4


from langchain_core.callbacks import StdOutCallbackHandler

# verbose 等价写法：把回调传进 invoke
chain.invoke({"question": "你好"}, config={"callbacks": [StdOutCallbackHandler()]})

生产环境常用自定义 callback 统计 token 消耗、记录每次 LLM 调用——对应你 Vibe Coding 手册里"操作透明、禁止黑盒"的纪律。

十三、LangGraph 状态图（进阶）

`StateGraph` —— 把流程编排成"有状态 + 可有环"的图

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


from langgraph.graph import StateGraph, END
from typing import TypedDict, Annotated
import operator

class State(TypedDict):
 question: str
 answer: str
 steps: Annotated[list, operator.add] # 累加型字段，每步追加

def call_model(state: State):
 state["answer"] = chain.invoke({"question": state["question"]})
 state["steps"].append("call_model")
 return state

def should_continue(state: State):
 return END if "结束" in state["answer"] else "call_model" # 条件边

graph = StateGraph(State)
graph.add_node("call_model", call_model)
graph.add_edge("call_model", "call_model") # 自环：可多轮
graph.add_conditional_edges("call_model", should_continue)
app = graph.compile()

print(app.invoke({"question": "你好", "steps": []}))

LangGraph = LCEL 的"有环升级版"。你 W4 学的 RunnableLambda（node）、RunnableBranch（conditional edge）在这里成了 add_node / add_conditional_edges 的一等公民。W5 你会把手写 Agent 的循环搬进状态图。

十四、常用技巧与踩坑

技巧 1：流式 + 解析器组合

1
2


for chunk in chain.stream({"question": "数到5"}):
 print(chunk, end="", flush=True) # StrOutputParser 保证每块是 str

技巧 2：batch 并发提速

1

results = chain.batch([{"question": "1+1"}, {"question": "2+2"}]) # 比循环 invoke 快

技巧 3：降级保护

生产代码用 try/except 包住导入，导入失败就退回最小实现（见第八节 _MiniMM），保证程序不崩。

踩坑 1：相对导入直接跑脚本会炸 ⚠️

from ..memory import X 在 python xxx.py 下必然失败。改用 sys.path.insert(0, 根目录) + 绝对导入，或 python -m 包.模块。

踩坑 2：版本弃用 ⚠️

旧教程的 LLMChain、ConversationChain、initialize_agent 已弃用。坚持用 LCEL（core）+ create_react_agent + LangGraph。

踩坑 3：parser 输出类型 ⚠️

验收用 isinstance(result, str)，别写死类名（跨版本包装层会变）。

踩坑 4：流式不能用普通函数截断 ⚠️

RunnableLambda 包的函数在 .stream() 下要支持流式透传，否则丢字。简单场景用 StrOutputParser 最稳。

十五、小结

LangChain 看着庞大，日常 80% 的场景只用这几样：ChatPromptTemplate 拼提示 + ChatOpenAI 调模型 + StrOutputParser 解析 + | 串成链 + RunnableLambda 接你的老代码。先把这条主线跑熟，记忆/检索/工具/Agent 都是往这条主线上挂模块。

回顾你 W1-W3 的手写轮子，对应关系是：

你自研的	LangChain 标准件
`RealLLM` / `llm_client`	`ChatOpenAI`
`prompt_lib`	`ChatPromptTemplate`
手动取 `.content` / `json.loads`	`StrOutputParser` / `JsonOutputParser`
`fc_loop` 工具循环	`Agent` / `bind_tools` / `ToolMessage`
`MemoryManager`	`Memory` + `RunnableLambda` 接入
Chroma 长期记忆	`VectorStore` / `Retriever`
`tools/` 注册表	`@tool` 装饰器

框架化不是学新东西，是把手动接线变成标准管道。 你已有的底层认知（token、记忆、压缩、工具循环）全部复用，只是换了更通用的语法。

下一篇建议深入 LangGraph：把 Agent 的多轮循环、条件分支、状态共享，用状态图标准化——那是 W5 的主战场，也是你手写 fc_loop / MemoryManager 的自然归宿。

记住一条铁律：凡是接你自研代码的，先想"它实现 Runnable 了吗？没实现就包一层 RunnableLambda"；凡是接 dict 消息的，先想"prompt 要的是消息对象吗？要就过一道 _to_lc"。这两道桥通了，LangChain 的大门就彻底打开了。

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

如何开始vibcoding

Thu, 20 Aug 2026 13:04:51 +0800

Vibe Coding 实战手册（V1.5）

规划驱动 × 迭代循环 × Git 留痕 × 工程化返工的 AI 编程方法论适用对象：任何想用 AI 从 0 做出可用产品的人（无需先会写代码，但需会描述清楚）本版新增：① Git 基线纪律（每次操作必 commit、禁止删除、删/覆盖需申请权限）② 操作透明日志（每次操作写本地 OPERATIONS.md，AI 禁止黑盒）③ 部署与上线（产品落地）④ 全旅程问题排雷手册（从想法到落地的所有坑 + 解法 + 提示词）

0. 怎么用这本手册

这本手册不是理论，是操作说明书。你按页码走，每一步都明确三件事：

下一步干什么（行动）
哪一步最关键（别跳）
每一步盯着什么别翻车（避坑）

图标约定：

🎯 这一步最关键 / 决策点 —— 跳不过去
⚠️ 要盯紧的风险
📋 模板 / 可直接抄的提示词或命令
✅ 该步骤的交付清单（打勾用）
🚫 绝对禁止的行为（红线）

1. 总览：从「想法」到「落地」的全流程

 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


┌─────────────────────────────────────────────────────────────┐
│ 阶段零 Git 基线纪律 + 操作透明日志 Git Baseline │
│ 🎯最关键：从有想法第一天就建仓库；每次操作必 commit + 写日志； │
│ 禁止删除；删除/覆盖须申请权限；AI 操作全程透明，禁止黑盒。 │
└───────────────────────────┬─────────────────────────────────┘
 ▼
┌─────────────────────────────────────────────────────────────┐
│ 阶段一 设想与规划 Envision & Plan │
│ 🎯最关键：地基。需求/UI/后端/测试全敲定 + 准入闸门才许写码。 │
│ 交付：需求摘要·PRD·方案·UI图·质量准则·测试策略+闸门 │
└───────────────────────────┬─────────────────────────────────┘
 ▼
┌─────────────────────────────────────────────────────────────┐
│ 阶段二 开发初始原型 Develop Initial Prototype │
│ 原则：小步快跑。按 PRD 生成骨架 + 一个核心功能 │
└───────────────────────────┬─────────────────────────────────┘
 ▼
┌─────────────────────────────────────────────────────────────┐
│ 阶段三 & 核心循环 迭代开发 Iterative Development │
│ ↻ 提示 → 生成 → 🎯审查 → 优化 → 重复 │
│ + 每批结束做 自我审计 (Self-Audit) + 安全返工(4.7) │
└───────────────────────────┬─────────────────────────────────┘
 ▼
┌─────────────────────────────────────────────────────────────┐
│ 阶段四 部署与上线 Deploy & Launch（产品落地） │
│ 原则：密钥不上库、环境变量分离、上线自检、可回滚 │
└─────────────────────────────────────────────────────────────┘

贯穿全程：每个动作 → Git commit 留痕 + 写进本地操作日志（OPERATIONS.md）；删除/覆盖 → 先申请权限；AI 操作全程透明，禁止黑盒。
遇到问题 → 翻第 7 节「全旅程问题排雷手册」对号入座。

阶段速查表：

阶段	回答的核心问题	最关键交付	最常见的错
零 · Git	怎么保证随时可回滚	Git 仓库 + 提交纪律	不提交就改 → 翻车无退路
一 · 规划	要做啥、长啥样、啥标准	PRD + 架构方案	跳过直接写码 → 返工
二 · 原型	核心能跑通吗	可启动最小原型	一次生成太多 → 出错难查
三 · 迭代	怎么一点点变好	每轮可审查的增量	不审查直接接受 → 埋雷
四 · 部署	怎么让真用户用上	线上可访问 + 可回滚	密钥进仓库 / 无回滚 → 泄露或崩

2. 阶段零：Git 基线纪律 + 操作透明日志（一切动作之前）🎯

这是 V1.5 的两条核心铁律。从「你有了一个想法」的第一天就建仓库 + 建本地操作日志——在写任何代码、甚至写任何规划文档之前。后面所有阶段都建立在这两条纪律上：① Git 留痕 ② 操作透明（禁止黑盒）。

核心原则

每一次操作都留痕，任何一步翻车都能 pinpoint + 回滚。AI 永远没有「毁尸灭迹」的能力。

具体三条铁律：

每次操作必 commit：规划文档定稿、原型每批、每次迭代、每次修复，做完立刻 git commit。
🚫 禁止删除：AI 不得执行任何删除文件 / 删除分支 / 清空目录 / git reset --hard 的操作。
删除 / 覆盖须申请权限：任何「删除」或「覆盖已有文件」的动作，AI 必须先向你申请，说明要删/覆盖什么、为什么、影响哪些功能，等你明确同意后才执行。

🎯 为什么这是地基

Vibe Coding 最大的隐忧是「AI 改着改着把之前好的东西弄没了，你还不知道哪步出的事」。Git 纪律把这事变成不可能：

每步有 commit → 出事能 git revert 精确回退到上一个好状态，不用人肉查上万行。
禁止删除 + 覆盖需授权 → AI 不能「顺手」把你写好的代码删掉或整文件覆盖。
留痕本身也是一种「审计」，你能一眼看出项目每天长成什么样。

📋 启动命令（直接抄，项目第一天跑一次）

1
2
3
4


# 在项目根目录
git init
git add -A
git commit -m "init: 项目初始化 + 规划文档"

📋 日常纪律：每次操作后的提交（让 AI 或你自己照做）

1
2
3
4


git add -A
git commit -m "feat: 完成登录模块骨架" # 新功能用 feat:
# fix: 修复解析逻辑 docs: 更新 PRD refactor: 重构订单服务
git tag v0.1-prototype # 关键里程碑打 tag，方便回滚

⚠️ 提交信息要能让人看懂这次改了啥。千万别用 git commit -m "update" 这种糊弄写法——回滚时你分不清哪个是好的。

📋 回滚命令（出问题时）

1
2
3


git checkout -- . # 撤销「还没提交」的改动（回到上次 commit）
git revert <commit号> # 安全撤销「已提交」的某次改动（生成反向 commit，不丢历史）
git checkout <tag名> # 回到某个里程碑，例如 git checkout v0.1-prototype

🚫 AI 行为红线（写进 CLAUDE.md / .cursorrules / 项目规则，让 AI 自动遵守）

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


你在本项目中的 Git 纪律 + 透明日志（务必遵守）：
1. 每次改动后必须执行 git add -A && git commit -m "<类型>: <说明>"，不得跳过。
2. 绝对禁止执行删除类命令：rm / del / git reset --hard / 删除分支 / 整文件覆盖。
3. 任何「删除文件」或「覆盖已有文件」的操作，必须先向用户申请权限，说明：
 - 要删 / 覆盖的具体文件
 - 为什么必须这么做
 - 会影响哪些功能
 等用户明确回复「可以」后才执行。
4. 优先用「局部新增 / 局部修改」代替「删除重来」。
5. 每次 commit 信息要能让人看懂这次改了啥，方便日后回滚。
6. 每次操作（改动前/后）必须向用户简短汇报，并追加一条记录到本地日志文件
 OPERATIONS.md（格式：时间 / 动作 / 文件 / 改动摘要 / 原因 / 结果）。
 禁止「静默改完不说明」的黑盒操作。
7. 日志文件本身也要 git commit 进仓库。

✅ 阶段零交付清单

项目已 git init
规划文档已首次 commit
已把上面的「AI 行为红线」写进项目规则文件（CLAUDE.md / .cursorrules）
已建本地日志文件 OPERATIONS.md，AI 红线含「每次操作写日志」条款
你清楚：每次操作 = 一次 commit + 一条日志；删/覆盖 = 必须先问你

阶段零其二：操作透明日志（AI 操作完全透明，禁止黑盒）🎯

与 Git 纪律并列的第二条铁律。光有 commit 还不够——commit 只记录「代码变了」，不记录「AI 为什么变、动了哪、结果如何」。透明日志补上这层。

核心原则

每一次操作（AI 改了什么文件、哪段、为什么、结果如何）都立即写进本地日志文件（如 OPERATIONS.md 或 logs/operations.log），AI 操作完全透明，不允许黑盒。

具体要记三件事：

做了什么：改了 / 新增了 / 删除了（删需先申请）哪些文件，关键改动摘要。
为什么：基于哪条需求 / 哪个报错 / 哪次反馈。
结果如何：跑通了 / 有残留问题 / 待你确认。

🎯 为什么这条最关键

黑盒操作 = 你不知道 AI 动了哪里，出事无法定位、无法向人解释、也无法复盘学习。透明日志把每一步变成可审计、可追责、可学习的记录——既是安全网，也是你自己的「项目日记」。

⚠️ 关注

日志要结构化（时间 / 动作 / 文件 / 改动摘要 / 原因 / 结果），别只写「改了代码」。
每次操作后立即追加，不事后补（事后容易忘、容易美化）。
日志文件本身也要 git commit 进仓库（它也是项目资产）。

📋 本地日志格式模板（直接抄，每次操作追加一条）

1
2
3
4
5
6
7


## [2026-08-20 21:10] 操作：实现登录模块骨架
- 动作：新增
- 文件：src/auth/login.py, tests/test_login.py
- 改动摘要：新增 login() 函数，含输入校验；补充对应单元测试
- 原因：阶段二 批次1（按 PRD 核心功能第 2 条）
- 结果：本地测试通过；待你 review
- commit：feat: 登录模块骨架

📋 写进 AI 行为红线（与 Git 纪律同文件，规则 6、7）

1
2
3
4


6. 每次操作（改动前/后）必须向用户简短汇报，并追加一条记录到本地日志文件
 OPERATIONS.md（格式：时间 / 动作 / 文件 / 改动摘要 / 原因 / 结果）。
 禁止「静默改完不说明」的黑盒操作。
7. 日志文件本身也要 git commit 进仓库。

✅ 本步（透明日志）交付

已建本地日志文件 OPERATIONS.md（或 logs/operations.log）
AI 红线已含「每次操作写日志」条款
你清楚：每次操作 = 一次 commit + 一条日志
日志文件已随项目 commit 进仓库

⚠️ 阶段零没建仓库 / 没建日志纪律，不允许进入阶段一写码。这是硬门槛。

3. 阶段一：设想与规划（Envision & Plan）

核心原则

规划先行，文档驱动。 别一上来就让 AI 写代码。在敲下第一行代码之前，需求、UI 图、后端逻辑、测试策略、质量准则全部要先在文档里敲定。你和 AI 都拿着同一份文档干活，后面才不会各说各话——代码只是把文档「翻译」成可运行的产物。

🎯 为什么阶段一最关键

这是整条流水线的地基。地基歪了，后面盖得越快塌得越快。大量 Vibe Coding 项目死在「做着做着发现需求没想清」——而这份代价在阶段一花 1 小时写文档就能避开。

阶段一先由 AI 反问澄清需求（步骤 1.1），再按顺序产出 6 份文档（步骤 1.2~1.6）：

步骤 1.1 需求澄清：让 AI 反问你（阶段一入口）

做什么：你只抛一个模糊想法（「我想做个 XX」），让 AI 扮「需求分析师 + 技术顾问」，反过来一个个问你，把开发细节全挖清：UI 长啥样、用什么技术栈 / 框架、架构怎么搭、怎么交付、做到什么算合格、每个细节具体怎么做。直到 8 个维度全部确认，才输出《需求锁定摘要》放行。

🎯 最关键：这是整个项目的「信息采集入口」。用户（尤其不懂技术的）脑子里的需求是模糊的，不反问就写码 = 做出来不是他要的。AI 反问的质量，直接决定后面 PRD 的质量——这一步省了，后面全返工。

⚠️ 关注：

一次别问太多（1~3 个），否则用户懵。
用户说「不懂 / 不知道」，AI 要给推荐 + 理由，不是把问题原样甩回去。
必须覆盖 8 个维度（目标 / 功能 / UI / 技术栈 / 架构 / 交付 / 验收 / 约束），缺一不可，全确认了才能进下一步。

📋 提示词模板（阶段一第一步，直接发给 AI）：

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


你现在是我的「需求分析师 + 技术顾问」。我（用户）只有一个模糊的想法，几乎不懂技术。你的任务不是写代码，也不是直接给方案，而是**通过反问，把我脑子里的需求彻底挖清楚**，直到你能完整描述"要开发什么、怎么开发、做到什么算合格"。

你的工作方式：
1. 我每说一句，你先简短确认你理解的部分，然后只针对当前最缺口的一块提问（一次 1~3 个问题，别一上来甩 20 个）。
2. 遇到我不懂的词（如"前端框架""API""数据库"），先用一句话大白话解释，再给 2~3 个可选项让我挑，并说明每个选项的利弊和适合什么人。
3. 如果我答"不知道"，你就给推荐 + 理由，让我确认或改。
4. 把已确认的信息实时整理成「已锁定」清单回显给我，让我能看到进度。

你必须挖清楚的维度（逐项覆盖，缺一不可）：
- 目标与场景：给谁用？解决什么具体痛点？在哪用（网页 / 手机 / 桌面）？
- 核心功能：必须有的 3~5 个功能，每个一句话。哪些"暂时不要"？
- UI / 交互：大概长什么样？参考哪个现有产品？操作主流程是什么？
- 技术栈 / 框架：前端、后端、数据库分别用什么（不懂就你推荐）。要不要部署上线？部署到哪？
- 架构：数据从哪来（用户输入 / 第三方 / 爬虫）？要不要登录账号体系？
- 交付形式：我要的是可运行网站 / 可安装包 / 源码 / 还是先要个 demo？
- 验收标准：做到什么程度算"合格"？有没有性能指标（速度 / 并发）？
- 约束：时间、预算、必须合规的点（隐私 / 版权）？

结束条件（重要）：
只有当上面 8 个维度全部有明确结论且我确认过，你才输出一份《需求锁定摘要》（结构化），并明确告诉我："需求已敲定，可以进入 PRD 撰写 / 下一步。"
在此之前，不要写任何代码，不要直接给完整方案，专注把问题问完。

✅ 交付清单：

8 个维度全部问到且用户确认
输出了《需求锁定摘要》
AI 明确说「可以进入下一步」
用户对摘要无异议
本步产出已 git commit（docs: 需求锁定摘要）

步骤 1.2 产出产品需求文档（PRD）

做什么：和 AI 协作，把项目说清楚。

🎯 最关键：验收标准必须写死——「做到什么程度算完」。这是后面所有迭代的标尺。

⚠️ 关注：别写「做一个好用的 XX」，要写「用户能 XX，响应 < 2 秒，支持 100 并发」。模糊的需求 = 无限的返工。

📋 PRD 提示词模板（直接喂给 AI）：

1
2
3
4
5
6
7


请基于以下信息帮我写一份 PRD：
- 项目名：
- 解决谁的什么问题：
- 核心功能（3-5 条，每条一句话）：
- 技术约束（必须 / 禁止）：
- 验收标准（可量化，每条可测）：
- 明确不在范围内（排除项）：

✅ 交付清单：

用途说清了
核心功能列了 3-5 条
验收标准可量化
范围边界划了（什么不做）
本步产出已 git commit（docs: 完成 PRD）

步骤 1.3 技术方案与架构设计

做什么：让 AI 在写码前先给架构计划——技术栈、数据模型、模块划分、安全策略。

🎯 最关键：让 AI 「先出计划，你批准才写码」（research → plan → implement）。你卡的是「计划对不对」，不是「代码长啥样」。

⚠️ 关注：数据库变更、第三方依赖、密钥怎么存——这些提前定，别等代码生成了再返工。

📋 提示词模板：

1
2
3
4
5
6
7
8


基于上面的 PRD，给出技术方案：
1. 推荐技术栈及理由
2. 后端逻辑：核心 API / 接口契约、数据流、关键业务规则（先写清逻辑，暂不写实现）
3. 数据库表 / 数据模型设计（如有）
4. 模块划分与职责
5. 安全策略（鉴权、密钥、输入校验）
6. 实现计划（拆成可执行的批次，标顺序）
请先只给方案与逻辑，不要写代码，等我确认。

✅ 交付清单：

技术栈定了
数据模型清晰
安全策略有
实现计划拆成批次了
本步产出已 git commit（docs: 技术方案）

步骤 1.4 线框图与 UI/UX

做什么：让 AI 先出 UI 图（ASCII 线框或可视化草图），把界面布局和交互流程定下来，写码前就对齐「长啥样」。能用图形工具出真实 mockup 更好。

🎯 最关键：在写码前对齐「长啥样」，避免做出来不是你要的。

⚠️ 关注：聚焦核心页面，别一上来画 20 个页。先把主流程跑通。

📋 提示词模板：

1
2
3
4


基于 PRD，画出核心流程的线框图（ASCII 即可）：
- 页面1：XXX，含哪些元素、按钮去哪
- 交互：用户点 A → 发生 B
只画主流程，先不画边缘情况。

✅ 交付清单：

核心页面布局定了
主交互流程清楚了
本步产出已 git commit（docs: UI 线框图）

步骤 1.5 质量准则

做什么：定义编码标准、安全实践、测试策略——写成一份「准则文档」。

🎯 最关键：这份准则后面迭代时反复用，让 AI 每次都按同一套标准写，不用你每轮重复说。

⚠️ 关注：明确「禁止硬编码密钥」「必须有错误处理」「函数要 docstring」等硬规矩。

📋 质量准则模板：

1
2
3
4
5


本项目质量要求：
- 编码：函数有 docstring + 类型注解；不用魔法数字
- 安全：密钥走环境变量；用户输入必须校验；防注入
- 测试：核心逻辑有单元测试；每次迭代后跑测试
- 风格：中文注释；错误处理不吞异常

✅ 交付清单：

编码标准写了
安全硬规矩写了
测试要求写了
本步产出已 git commit（docs: 质量准则）

步骤 1.6 测试策略与验收用例

做什么：在写码前，让 AI 把「怎么证明做对了」定下来——测试策略 + 具体验收用例（每个核心功能一条可判定的检查）。

🎯 最关键：没有验收用例，「做完」就没有标准，AI 很容易「看起来能跑但其实没满足需求」。先定测试，后写码，等于先画靶再射箭。

⚠️ 关注：

验收用例要可量化、可自动判定（如「提交空表单应报错」），别写「功能正常」。
区分单元测试（逻辑）和端到端测试（用户走通主流程）。

📋 提示词模板（喂给 AI）：

1
2
3
4
5
6
7
8


基于 PRD 和质量准则，给出测试策略：
1. 单元测试：列出核心逻辑模块及每个要覆盖的边界（空输入、超长文本、并发等）。
2. 端到端用例：写 3~5 条主流程验收用例，每条格式：
 - 前置条件：
 - 操作：
 - 预期结果（可判定对错的）：
3. 验收门槛：所有端到端用例通过 + 单元测试绿，才算该模块"合格"。
请只给策略与用例，不要写测试代码，等我确认。

✅ 交付清单：

单元测试覆盖点列了
端到端验收用例写了 3~5 条
验收门槛定义了
本步产出已 git commit（docs: 测试策略）

步骤 1.7 代码准入闸门（写码前最后一关）

做什么：开工写码前，逐项打勾。任何一项没完成、没确认，不准进阶段二。

🎯 最关键：这是「规划驱动」的硬边界。闸门一开，后面代码只是执行文档，不再做决策。

✅ 准入清单（全绿才许写码）：

1.1 需求锁定摘要：8 维度全确认
1.2 PRD：验收标准可量化
1.3 技术方案：技术栈 / 后端逻辑 / 架构定了
1.4 UI 图：界面与交互对齐
1.5 质量准则：编码 / 安全 / 风格硬规矩写了
[质量准则已含安全/测试要求，见 1.5 / 1.6]

✅ 准入清单（续，含 Git 与确认）：

Git 仓库已初始化，阶段零纪律已落实（AI 红线写进项目规则）
用户对以上全部无异议

闸门全绿 = 可以进入阶段二写码。任何一项飘红，回到对应步骤补齐，不要带着疑问写码。

✅ 阶段一总交付：需求锁定摘要（1.1）+ PRD（1.2）+ 技术方案（1.3）+ UI 图（1.4）+ 质量准则（1.5）+ 测试策略（1.6），六项齐了 + 准入闸门（1.7）全绿，才进阶段二。

4. 阶段二：开发初始原型（Develop Initial Prototype）

核心原则

小步快跑。 目标不是「一次做全」，是「核心概念快速跑通」。注意：此时需求、UI、后端逻辑、测试策略都已在阶段一敲定，代码只是把文档翻译成可运行产物，不是边写边想。

⚠️ Git 纪律 + 透明日志提醒：阶段零已建仓库与日志。之后每个批次做完立刻 commit，并追加一条操作日志到 OPERATIONS.md，留可回滚记录——这是后面 5.7 安全返工的前提。禁止删除；覆盖需申请权限；AI 操作须透明。

步骤 2.1 分步实施

做什么：把阶段一的实现计划拆成小批次，让 AI 每次只做一个模块 / 一个功能。

🎯 最关键：每批可独立验证——做完这一批你能立刻看到 / 测到结果。

⚠️ 关注：批次之间要有清晰接口，别让 AI 同时改十个文件。

💡 技巧：第一批只搭骨架（项目结构 + 空模块 + 能启动），第二批再加第一个真实功能。

✅ 每批交付：一个能运行 / 能验证的增量 → 立刻 git commit（feat: 批次说明）。

步骤 2.2 避免「大跃进」

做什么：拒绝「一次性生成整个应用」。

🎯 最关键：小批量生成 = 高质量 + 易审查。一次 2000 行代码，你根本 review 不动，错了也找不出。

⚠️ 关注：如果 AI 一次吐出太多，打断它：「先只做 X，剩下的下一批」。

✅ 阶段二交付：一个能启动、核心功能跑通的最小原型。不用完美，能用就行 → git tag v0.1-prototype。

5. 阶段三 & 核心循环：迭代开发（Iterative Development）

这是 Vibe Coding 的心脏。每个功能点都走这个闭环：

1
2
3


提示(Prompt) → 生成(Generate) → 🎯审查(Review) → 优化(Refine) → ↻重复(Repeat)
 │
 └─ 每批结束 → 自我审计(Self-Audit) → 安全返工(5.7)

⚠️ Git 纪律 + 透明日志提醒：每完成一个功能点 / 一批改动，立即 git commit，并追加一条操作日志到 OPERATIONS.md。禁止删除；任何覆盖已有文件的操作先申请权限；AI 操作须透明。

步骤 5.1 提示（Prompt）

做什么：清晰描述要生成 / 改进的功能，给足上下文（贴 PRD 相关段、当前代码、报错）。

🎯 最关键：上下文给足 = 输出质量翻倍。AI 不知道你脑子里的东西。

⚠️ 关注：一次只说一件事；别在一条提示里塞五个不相关的改动。

📋 提示词模板：

1
2
3
4


基于质量准则和当前代码，请实现：<具体功能>
上下文：<贴相关代码 / PRD 段落>
约束：<必须 / 禁止>
验收：<做完怎么测>

步骤 5.2 生成（Generate）

做什么：AI 产出代码。

🎯 最关键：让 AI 解释它改了什么、为什么——你后面审查（5.3）要用。

⚠️ 关注：生成后先别急跑，先看一眼它说改了哪。

步骤 5.3 审查（Review）🎯 开发者核心价值

做什么：仔细阅读 AI 生成的代码——这是你作为人的不可替代环节。

🎯 最关键：这一步决定项目死活。不审查 = 把控制权全交出去 = 埋雷。

审查三件事：

正确性：逻辑对吗？边界情况处理了？
效率：有死循环 / 重复计算 / N+1 查询吗？
安全性：密钥硬编码？输入没校验？依赖不存在 / 有漏洞？

⚠️ 关注：AI 会「自信地」写错——编造不存在的 API、函数名拼错、漏错误处理。

✅ 审查清单：

逻辑正确，边界处理了
没有明显性能问题
无硬编码密钥 / 凭证
用户输入有校验
依赖真实存在
错误信息不被吞

步骤 5.4 优化（Refine）

做什么：根据审查结果改提示词或直接改代码，让 AI 按反馈重做。

🎯 最关键：反馈要具体——「登录失败没提示」比「登录有问题」有用 10 倍。

⚠️ 关注：改完再走一遍 5.3 审查，别以为改一次就对了。

步骤 5.5 重复（Repeat）

做什么：每完成一个功能点，回到 5.1，做下一个。

🎯 最关键：保持小闭环节奏，别贪多。一个功能点干净了再下一个 → 每点完成 git commit 一次。

步骤 5.6 自我审计（Self-Audit）

做什么：每完成一批（不是每个功能，是一批），让 AI 自己对照检查清单审一遍。

🎯 最关键：这是「双人复核」——你审一遍，AI 再审一遍，漏网之鱼少很多。

📋 提示词模板：

1
2
3
4
5
6


请对照以下清单自我审计刚才这批改动：
- 是否引入了硬编码密钥
- 是否有未处理的异常
- 是否符合质量准则里的编码标准
- 是否有死代码 / 重复代码
逐条给出：通过 / 有问题 + 位置。

⚠️ 关注：Self-Audit 不能替代人工审查（5.3），它是补充，不是替代。

✅ 阶段三每轮交付：一个通过审查 + 自审的功能增量，且测试仍全绿 → git commit。

步骤 5.7 安全返工：手术式干预 + 架构级回滚

做什么：当项目变大（上万行）、改出问题时，用「精准干预 + 架构级回滚」代替「从头改 / 全量覆盖」。核心原则：绝不直接改全量代码，只给 AI 提供「上下文切片」。

🎯 最关键：面对大代码库，返工死穴是「把全量代码喂给 AI 让它修」——上下文窗口有限，AI 会失焦、幻觉、顺手改坏好代码。正确姿势是「打点 → 定位 → 切片 → 嫁接 → 必要时重铸」。

⚠️ 关注：

第一反应永远是「打分支存原点」，不是「动手改」。
AI 返回的修复，永远用 Diff 逐块接受，不整文件覆盖。
底层架构错了，别硬改代码，回阶段一改方案重铸。
🚫 禁止 git reset --hard / 删文件 / 整文件覆盖；需要覆盖先申请权限。

五步流程：

① 紧急止血：立即创建检查点（Save Point） 发现重大错误，第一件事打分支，把当前状态（即使有错）完整保存。

1
2


git checkout -b fix/rollback-attempt # 新分支存原点
git add -A && git commit -m "checkpoint: 返工前快照"

这样你毫无心理负担地试错，随时 git checkout 主分支 回退到原点。

② 精准定位「病灶」，而非「全身」（Localize） 别对 AI 说「帮我修整个项目」。根据报错日志手动定位 1~3 个具体文件 / 函数，只把这几个文件 + 其依赖的接口定义复制出来喂给 AI。

③ 「反向提示词」与「定向手术」（Surgical Prompt） 提示词遵循 「保留 - 排除 - 约束」 结构：

❌ 错误示范：「这段代码报错，帮我改了。」
✅ 正确示范（📋 直接抄）：

1
2
3
4
5


我要修复 `src/utils/parser.ts` 中的解析逻辑错误。
- 保留：其他所有文件和数据库结构不变。
- 只修改：`parseData` 函数内部的循环逻辑。
- 不要重写：任何外部接口。
请输出修改后的完整函数代码。

④ 嫁接修复（Grafting），而非合并（Merging） AI 返回后，不要直接全量覆盖原文件。用 IDE 的 Diff 工具逐块接受；大文件只把 AI 生成的核心函数片段复制进去，手动调周边依赖。这样 AI 就算幻觉，也污染不到好代码。

🚫 若必须替换整个文件，先向用户申请权限并说明原因，获批后再操作。

⑤ 极端情况：架构级错误（大返工） 如果错误是底层数据模型 / 架构选型导致的（如 SQLite 必须换 PostgreSQL），千万不要手动改代码。正确流程：回退到阶段一 PRD，修改技术方案 → 清空当前代码目录（保留备份）→ 用新架构约束提示词让 AI 重新生成骨架 → 复用之前写好、无错的工具函数和 UI 组件（直接拷贝），只让 AI 重写核心业务逻辑层。这叫「保留零件，重铸引擎」。

🛡️ 防反工黄金法则（写进日常）：每完成一个独立功能点（如登录、支付），立即让 AI 生成该模块的单元测试。下次修改前先跑一遍测试——红了一大片的，说明本次改动出问题，立刻回滚本次修改（git revert），比人肉查上万行快一万倍。

✅ 本步交付：一个经 Diff 嫁接、测试仍绿的修复；必要时一份更新后的阶段一技术方案 → git commit。

6. 阶段四：部署与上线（产品落地）🎯

从「本地能跑」到「真用户能用」的一步。很多项目死在这里：本地好好的，一上线就崩，或者密钥泄露。

核心原则

密钥不上库、环境可分离、上线可自检、出事可回滚。 部署不是「把文件传上去」，是把阶段一~三的所有成果安全地交给真实用户。

⚠️ Git 纪律 + 透明日志提醒：每次部署 / 配置改动后立即 git commit，并追加一条操作日志到 OPERATIONS.md（含「改了哪个平台配置 / 为什么 / 结果」）。禁止删除；任何覆盖先申请权限；AI 操作须透明。

步骤 6.1 选部署形态

做什么：按阶段一的需求定平台。

形态	适合	典型平台
纯静态（前端）	落地页 / 工具	Vercel / Netlify / GitHub Pages / CloudStudio
前端 + 后端 API	多数 Web 应用	Render / Railway / 腾讯云 / 自有服务器
长期运行服务	需常驻进程	Docker + 云服务器

🎯 最关键：选错了平台后面迁移很痛（见 7 节「架构选错」）。阶段一就该定。

步骤 6.2 密钥与环境变量分离（🚫 红线）

做什么：所有密钥（API Key、数据库密码、Token）只存在环境变量 / 平台密钥管理里，绝对不进 Git 仓库。

🎯 最关键：一旦密钥进仓库并 push，就等于公开——必须立刻注销密钥（见 7 节「密钥泄露」）。

⚠️ 关注：

本地用 .env 文件，且 .env 必须写进 .gitignore。
云端在平台后台配环境变量，不写在代码里。

📋 命令（把 .env 挡在仓库外）：

1
2


echo ".env" >> .gitignore
git add -A && git commit -m "chore: 忽略 .env，密钥不入库"

步骤 6.3 构建与上线

做什么：按平台流程构建并发布。能用 CI（自动构建 + 测试通过才上线）最好。

⚠️ 关注：上线前确认测试全绿（阶段三的单元 + 端到端）。

📋 上线前自检清单（直接抄）：

1
2
3
4
5
6


- [ ] 本地跑通全部测试（单元 + 端到端）
- [ ] 无硬编码密钥（grep 一遍 API_KEY / password / secret）
- [ ] .env / 密钥已在平台配置
- [ ] 数据库已迁移且备份
- [ ] 有「上一个可部署版本」可回滚（git tag 或平台回滚点）
- [ ] 域名 / HTTPS 配置好（如需要）

步骤 6.4 监控与回滚

做什么：上线后盯日志 / 报错；一旦大面积异常，立刻回滚到上一个好版本。

📋 回滚命令：

1
2


git checkout <上一个好tag> # 本地回退
# 平台通常有「回滚到上次部署」按钮，优先用平台的

✅ 阶段四交付：线上可访问 + 密钥安全 + 有回滚预案 → git tag v1.0-launch。

7. 全旅程问题排雷手册（问题 → 原因 → 解决 → 提示词/命令）

从「有想法」到「产品落地」全程会踩的坑，按阶段归类。遇到事先翻这里对号入座，别瞎改。

7.1 阶段一（规划）常见问题

问题	为什么会这样	解决方法	提示词 / 命令
需求模糊，AI 瞎猜	没反问就写码	退回 1.1 让 AI 反问 8 维度	用 1.1 反问提示词
验收标准不可量化	PRD 写「好用」	改成可测指标（响应<2s、支持100并发）	用 1.2 PRD 模板
技术栈选错，后面大返工	没评审架构	阶段一 1.3 方案你拍板；真错了走 5.7 重铸	用 1.3 方案模板
没出 UI 图就写码，做出来不是要的	跳了 1.4	补线框图对齐长相	用 1.4 线框模板
规划文档丢了 / 被覆盖	没提交 + 误覆盖	阶段零纪律：每次定稿 commit；覆盖先申请	`git add -A && git commit -m "docs: 定稿PRD"`

7.2 阶段二（原型）常见问题

问题	为什么会这样	解决方法	提示词 / 命令
一次生成太多，错难查	让 AI 一把梭	拆小批，每批一个模块	用 2.2「先只做 X」打断
跑不起来（依赖缺失/版本错）	没锁版本	让 AI 给可复现环境 + 锁版本文件	📋 提示词：`请给出 requirements.txt / package.json 及精确版本，并说明启动命令`
骨架能启但核心功能没接上	批次接口不清	每批留清晰接口，分批验收	2.1 分步实施
原型文件被 AI 误删	没守 Git 纪律	阶段零红线：禁止删除；误删用 `git checkout -- .` 恢复	🚫 禁 `rm`；恢复：`git checkout -- .`

7.3 阶段三（迭代）常见问题

问题	为什么会这样	解决方法	提示词 / 命令
审查不充分，上线爆雷	直接接受 AI 输出	死守 5.3 审查三件事	用 5.3 审查清单
上下文丢失（长对话 AI 变笨）	对话太长稀释	开新对话 + 贴 PRD/架构文档当上下文	「基于以下 PRD 和质量准则，继续实现…」（贴文档）
改动牵一发动全身	给 AI 全量代码	5.7 切片：只给 1~3 文件	用 5.7 手术提示词
AI 幻觉（编造 API/依赖）	模型自信编造	5.3 审查「依赖真实存在」+ 5.6 自审	用 5.6 自审模板
没测试，改了不知坏没坏	没单测	黄金法则：每功能点即产单测	让 AI：「为 X 模块写单元测试，覆盖空输入/边界」
改完发现改坏了好代码	整文件覆盖	5.7 嫁接：Diff 逐块接受	🚫 禁整文件覆盖；需覆盖先申请
想回退到上周好状态	没留痕	阶段零：每次 commit + tag	`git revert <commit>` / `git checkout <tag>`

7.4 阶段四（部署/落地）常见问题

问题	为什么会这样	解决方法	提示词 / 命令
🔴 密钥泄露（最严重）	密钥写进代码并 push	立刻：① 去对应平台注销/重置密钥 ② 从仓库历史彻底删除 ③ 换新课	🚫 密钥绝不动进仓库；泄露应急见下方专框
本地能跑线上挂	环境变量没配	6.2 密钥走平台环境变量	平台后台配 env
数据库迁移出错	没备份直接迁	迁移前备份；出错回滚备份	`git checkout` 回滚代码 + 数据库备份恢复
没考虑并发/性能	阶段一没定指标	补阶段一验收指标 + 上线压测	用 1.2 量化验收标准
上线后大面积异常	没监控没回滚点	6.4 立刻回滚到上个好版本	平台「回滚部署」/ `git checkout <好tag>`
域名/HTTPS 没配	部署清单漏项	6.3 上线自检清单逐项打勾	用 6.3 自检清单

🔴 专框：密钥泄露应急流程（遇到立刻做）

1
2
3
4
5
6


① 第一时间去对应平台（云厂商 / API 提供方）注销或重置该密钥。
② 确认密钥是否已被 push 到远程仓库：
 - 是 → 从 Git 历史彻底清除（git filter-repo / BFG），并通知协作者重拉。
 - 否（仅本地）→ 从代码中删除，确认未提交。
③ 生成新密钥，只配置在环境变量 / 平台密钥管理，绝不进仓库。
④ 在 .gitignore 加 .env，并补一条阶段零红线到项目规则。

⚠️ 安全意识：涉及 API key 等敏感信息，第一反应是「是否已推送 → 怎么撤回 → 要不要去注销密钥」。宁可多此一举，不可泄露一次。

8. 里程碑检查点

你在这里	检查是否过关	不过关回哪
阶段零结束	Git 仓库建好 + AI 红线写进规则	回阶段零
阶段一结束	6 份文档齐全 + 准入闸门全绿	重做对应步骤 / 补闸门
阶段二结束	原型能启动 + 核心功能跑通	阶段二
每轮迭代结束	功能过审查 + 测试绿 + 已 commit	5.3 重审
阶段四前	密钥分离 + 测试全绿 + 有回滚点	6.2 / 6.3
项目交付后	上线自检通过 + 监控就位	6.4

9. 常见陷阱速查

陷阱	表现	解法
跳过规划	做着做着需求变	回阶段一补 PRD
大跃进生成	一次 2000 行，错难查	拆小批
不审查直接接受	上线后爆雷	死守 5.3
上下文丢失	长对话后 AI 变笨	开新对话 / 贴文档
维护债	需求一变回到原点	自己读懂关键模块
大改全量代码	AI 失焦/幻觉改坏好代码	用 5.7 切片返工 + 打分支
🚫 不提交就改	翻车无退路	阶段零：每次操作 commit
🚫 误删 / 整文件覆盖	好代码没了	阶段零红线：禁删；覆盖先申请
🔴 密钥进仓库	泄露风险	6.2 分离 + 泄露应急框
架构选错硬改	越改越乱	5.7 架构级重铸
黑盒操作	不知 AI 动了哪、出事难定位	阶段零透明日志：每次操作写 OPERATIONS.md

10. 一句话总结

Vibe Coding = 规划先行（文档驱动） + 小步原型 + 提示→生成→审查→优化→重复的闭环 + 每批自审 + 工程化返工；而这一切都建立在两条铁律上——Git 留痕、操作透明（每次操作写本地日志、禁止黑盒）、禁止删除、删/覆盖先申请权限。

你值钱的地方不在「打字」，在规划和审查——这两步跳不掉；而 Git 纪律，是你敢于让 AI 大步往前走的底气。

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）。箱子永远只有一个，但里面的东西是最新的浓缩版。

Json-os库常用速查

Mon, 17 Aug 2026 10:30:49 +0800

搞懂你代码里的 `os` 和 `json` —— 从记忆系统的真实调用讲起

0. 先记住一句话

os = 和"操作系统 / 文件路径"打交道的工具箱。你用它定位文件在哪、拼出路径。
json = 把 Python 的 dict / list 这类数据，变成字符串（存起来） 或 从字符串还原回来（读出来） 的工具。

你记忆系统里它们的关系：os 负责"把库文件放在哪个绝对位置"，json 负责"把要存的数据变成能写进文件/数据库的文本"。两个配合，记忆才能"存得下、读得回"。

一、`os.path`：和路径打交道

你的 paths.py 第一行就是它：

1
2
3
4
5


import os
BASE = os.path.dirname(os.path.abspath(__file__))
MEM_STORE = os.path.join(BASE, "mem_store")
PROFILE_DB = os.path.join(BASE, "memory.db")
FACTS_JSON = os.path.join(BASE, "facts.json")

下面把这一行拆成三块讲。

1.1 `file` —— “我这个文件自己叫啥、在哪”

每个 .py 文件运行时，Python 都会给它一个隐藏变量 __file__，内容是这个脚本的路径。

如果你在 C:\x\memory\ 里跑 python paths.py，那 __file__ 大致就是 C:\x\memory\paths.py。
但有时候它可能是相对路径（取决于你怎么启动），所以不能裸用。

1.2 `os.path.abspath(file)` —— 变成"从盘符算起的绝对路径"

1
2


os.path.abspath(__file__)
# 例：C:\Users\Think\Desktop\AgentLearn\memory\paths.py

作用：无论你从哪个目录启动程序，都把它矫正成完整的绝对路径。这样后面算出来的位置就不会随"当前目录（cwd）“漂移——这正是你记忆库"重启后还在原地"的关键。

1.3 `os.path.dirname(...)` —— 只拿走"目录"部分

1
2


os.path.dirname("C:\...\memory\paths.py")
# 得到：C:\Users\Think\Desktop\AgentLearn\memory

它把路径最后一段（文件名）砍掉，只留"文件夹”。于是：

1
2


BASE = os.path.dirname(os.path.abspath(__file__))
# BASE = C:\Users\Think\Desktop\AgentLearn\memory ← 本文件所在目录

记忆里的作用：所有库（Chroma 文件夹、SQLite 文件）都建在 BASE 旁边，换目录运行也指向同一处，不会"找不到记忆"。

1.4 `os.path.join(a, b)` —— 安全地拼路径（别手写斜杠！）

1
2
3


os.path.join(BASE, "mem_store")
# Windows → C:\...\memory\mem_store
# Linux → /home/.../memory/mem_store

为什么不用 BASE + "/mem_store"？因为 Windows 用 \、Linux/Mac 用 /，手写斜杠在不同系统会出错。os.path.join 自动用当前系统的正确分隔符，跨平台安全。

💡 你项目里所有的落盘路径都该用 os.path.join 拼，不要字符串硬拼。

1.5 `os.path.exists(path)` —— “这个路径在不在？”

来自你 local_store 示意里：

1
2
3


import json, os
def load_facts(path=FACTS_JSON):
 return json.load(open(path, encoding="utf-8")) if os.path.exists(path) else {}

1

os.path.exists(path) # 文件/文件夹存在 → True；不存在 → False

作用：第一次运行时 facts.json 还没建，os.path.exists 返回 False，就直接返回空字典 {}，避免去读一个不存在的文件而报错。

二、`json`：把数据变成"能存起来的文本"

SQLite 的字段是文本，文件也想存结构化的 Python 对象（dict / list）。但文本只能存字符串，不能直接塞 dict。json 就是干这个转换的。

你的 profile_store.py：

1
2
3
4
5


import sqlite3, json
...
self.con.execute("INSERT OR REPLACE INTO profile VALUES(?,?)", (k, json.dumps(v)))
...
return json.loads(row[0]) if row else None

local_store 示意：

1
2


json.load(open(path, encoding="utf-8"))
json.dump(d, open(path, "w", encoding="utf-8"), ensure_ascii=False, indent=2)

2.1 `json.dumps(obj)` —— Python 对象 → JSON 字符串

1
2
3
4


import json
v = {"age": 18, "like": "DeepSeek"}
s = json.dumps(v)
# s 现在是字符串：'{"age": 18, "like": "DeepSeek"}'

在记忆里的作用：ProfileStore.set_profile(k, v) 要把用户的画像 v（通常是 dict）写进 SQLite。但 SQLite 字段是文本，所以先用 json.dumps(v) 把它变成字符串，再存进去。

2.2 `json.loads(s)` —— JSON 字符串 → Python 对象

1
2


json.loads('{"age": 18, "like": "DeepSeek"}')
# 还原成 dict：{"age": 18, "like": "DeepSeek"}

在记忆里的作用：get_profile(k) 从 SQLite 读出来的是字符串（row[0]），用 json.loads(row[0]) 还原成原来的 dict，调用方才能当对象用。

2.3 `json.dump(obj, f)` / `json.load(f)` —— 直接读写整个文件

和上面那对很像，但这是直接操作文件对象：

1
2
3
4
5


# 写：把 dict d 直接写进 path 这个文件
json.dump(d, open(path, "w", encoding="utf-8"), ensure_ascii=False, indent=2)

# 读：从 path 这个文件直接读回 dict
d = json.load(open(path, encoding="utf-8"))

方法	吃进来的是	吐出去的是	记忆里谁用
`json.dumps(obj)`	Python 对象	字符串	`profile_store` 写 SQLite 前
`json.loads(s)`	字符串	Python 对象	`profile_store` 读 SQLite 后
`json.dump(obj, f)`	对象 + 文件对象	无（写进文件）	`local_store` 写 `facts.json`
`json.load(f)`	文件对象	Python 对象	`local_store` 读 `facts.json`

记法：带 s 的那对（dumps/loads）处理"字符串"；不带 s 的那对（dump/load）处理"文件"。

2.4 两个关键参数（你代码里已经用上了）

1

json.dump(d, f, ensure_ascii=False, indent=2)

ensure_ascii=False：默认 True 时，中文会被转成 \u4e2d\u6587 这种乱码。False 才能正常显示"用户喜欢 DeepSeek"。存中文必加。
indent=2：让 JSON 文件带缩进、换行，人眼可读。不加就是一整行挤在一起。

三、把 `os` + `json` 串起来看你的记忆系统

整条链路其实就三步：

os 定位保险柜 paths.py 用 os.path.dirname(os.path.abspath(__file__)) + os.path.join 算出 MEM_STORE / PROFILE_DB / FACTS_JSON 三个绝对路径。
json 把数据打包
- 存用户画像：json.dumps(v) 把 dict 变字符串 → 写进 SQLite（PROFILE_DB）。
- 存简单事实：json.dump(d, f, ensure_ascii=False, indent=2) 直接写 facts.json。
json 再把数据拆包
- 读画像：json.loads(row[0]) 把 SQLite 里的字符串还原成 dict。
- 读事实：json.load(f) 直接读回 facts.json，并用 os.path.exists 判断文件是否存在。

一句话：os 管"放在哪"，json 管"怎么变成能存的文本"。

四、新手最常踩的坑（重点看）

坑 1：`json.dumps` 默认中文变乱码

1
2


json.dumps({"like": "深度求索"}) # '{"like": "\\u6df1\\u5ea6\\u6c42\\u7d22"}' ← 看不懂
json.dumps({"like": "深度求索"}, ensure_ascii=False) # '{"like": "深度求索"}' ← 正确

坑 2：`loads` 和 `load` 搞混

1
2


json.loads(open("a.json")) # ❌ 报错！loads 只吃字符串，不吃文件对象
json.load(open("a.json")) # ✅ load 才吃文件对象

坑 3：手写路径分隔符

1
2


BASE + "/mem_store" # ❌ Windows 上会出错
os.path.join(BASE, "mem_store") # ✅ 跨平台安全

坑 4：文件打开不关（你代码里的隐藏小问题）

你现在的 json.load(open(path)) / open(path, "w") 没有关文件。学习期不影响，但规范写法用 with，出作用域自动关：

1
2
3
4
5
6


# 更稳的写法
with open(path, "w", encoding="utf-8") as f:
 json.dump(d, f, ensure_ascii=False, indent=2)

with open(path, encoding="utf-8") as f:
 d = json.load(f)

五、速查卡片（复习直接看这）

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


# ===== os.path：定位与拼路径 =====
__file__ # 当前脚本路径（可能相对）
os.path.abspath(__file__) # → 绝对路径（从盘符算起）
os.path.dirname(p) # 拿走目录部分，去掉文件名
os.path.join(a, b) # 安全拼路径（跨平台）
os.path.exists(p) # 路径在不在（bool）

# ===== json：对象 ↔ 文本 =====
json.dumps(obj, ensure_ascii=False, indent=2) # 对象 → 字符串（ensure_ascii=False 保中文）
json.loads(s) # 字符串 → 对象
json.dump(obj, f, ensure_ascii=False, indent=2) # 对象 → 写进文件 f
json.load(f) # 从文件 f 读回对象
# 口诀：带 s 处理"字符串"，不带 s 处理"文件"

记忆本地化

Mon, 17 Aug 2026 07:22:41 +0800

给 AI Agent 的记忆找个"保险柜"：三层持久化与隐私不出网的设计复盘

一、先给记忆分个类：三层持久化，不是替代而是分层

新手最容易踩的坑，是以为"记忆存一个地方就够了"。其实数据形态不同，落盘介质就得不同。我们用了三种，它们是分层分工，不是谁替代谁：

持久化方式	介质	适合存什么	典型场景
纯本地文件	`facts.json`	配置 / 简单开关 / 零依赖小事实	手改也行、不需要语义的键值
SQLite	`memory.db`	用户画像 KV / 结构化表	精确查询、按 key 取用户资料
Chroma on-disk	`mem_store/`	向量嵌入 / 语义召回	“用户喜欢什么"这种相关度检索

一句话记住：纯文件管配置，SQLite 管画像，Chroma 管语义。 别把用户画像塞进向量库，也别把聊天嵌入塞进 JSON。

二、存得稳：给"账本"找保险柜

记忆最先死在哪？路径漂移。

很多人写 PersistentClient(path="./mem_store")——这个 ./ 不是"项目目录”，而是你敲命令那一刻所在的目录（cwd）。在 A 目录跑建了库、在 B 目录跑就找不到，重启后记忆仿佛被偷了。

解决办法只有一条铁律：用绝对路径。

1
2
3
4
5


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") # 纯本地简单事实

__file__ 是"这个文件自己在哪里"，所以无论从哪个目录启动，所有落盘点都稳稳指向同一处。这就像给账本找了一个固定不动的保险柜，而不是随手塞进今天的裤兜。

三、存得安全：隐私默认不泄露

这是今天最核心的设计动作：隐私分流。它不会自动发生，是你必须主动写进代码里的。

大模型 API 调用，会把你传给它的 prompt 内容发出去。所以得想清楚：

🔒 永远留本地、绝不进 prompt：用户真实姓名、手机号、密钥、明文敏感偏好。
🌐 会发到云端 LLM API：你主动塞进 system/user 消息的"召回结果"（比如"已知用户长期事实：喜欢 DeepSeek"）。
⚠️ 敏感事实：存本地，但召回时默认不自动进 prompt，需用户显式确认才带上。

我们用一个极简机制实现"默认不泄露"：

1
2
3
4
5
6
7
8


# 存的时候贴标签
lt.add_fact("用户的手机号是 13800001234", fid="f_phone", private=True)

# 默认不泄露：recall 默认 include_private=False → 召回不到敏感事实
lt.recall("用户手机号") # -> []

# 要带才带：显式传 include_private=True 才召回
lt.recall("用户手机号", include_private=True) # -> ["用户的手机号是 13800001234"]

背后的逻辑就三行，却把"隐私底线"钉死了：

1
2
3
4
5
6
7
8


def recall(self, query, k=3, include_private=False):
 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

心智模型：存的时候贴标签（private=True），召回时默认"看都不看"，只有你明确说"这次可以带"才放行。你传给 LLM 的，永远只是召回出的非敏感摘要；原始记忆文件只在本地磁盘。

四、代码长什么样

下面是三个核心文件的完整源码，注释里把设计约定也写进去了。

`paths.py` —— 集中管理所有落盘路径

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


"""集中管理所有落盘路径, 避免各处硬编码 './xxx' (相对路径会随 cwd 漂移)."""
# ============ 隐私分流（设计约定, 不是代码自动给的） ============
# 🔒 永远留本地、绝不进 prompt: 用户真实姓名 / 联系方式 / 密钥 / 明文敏感偏好
# 🌐 会发到云端 LLM API: 你主动塞进 system/user 消息的"召回结果"
# (如"已知用户长期事实: 喜欢 DeepSeek")
# ⚠️ 敏感事实: 存本地, 但召回时不自动进 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") # 纯本地简单事实
if __name__=="__main__":
 print(BASE,"\n",MEM_STORE,"\n",PROFILE_DB,"\n",FACTS_JSON)

`long_term.py` —— Chroma 长期记忆（语义召回 + 隐私开关）

 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


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

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()}])

 #Chroma 的 add 要求每个参数都是列表（ids=[...]、documents=[...]）——因为 Chroma 的 add 支持批量加。就算你只存一条，也要写成 [fid]、[text]

 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])

`profile_store.py` —— SQLite 用户画像 KV

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


import sqlite3, json
from pathlib import Path
from memory.paths import PROFILE_DB
#BASE = Path(__file__).parent

class ProfileStore:
 def __init__(self, db_path=PROFILE_DB):
 self.con = sqlite3.connect(db_path) # 绝对路径
 self.con.execute("CREATE TABLE IF NOT EXISTS profile (k TEXT PRIMARY KEY, v TEXT)")
 self.con.commit()

 def set_profile(self, k, v):
 self.con.execute("INSERT OR REPLACE INTO profile VALUES(?,?)",(k,json.dumps(v)))

 def get_profile(self,k):
 row=self.con.execute("SELECT v FROM profile WHERE k=?",(k,)).fetchone()
 return json.loads(row[0]) if row else None

五、踩坑记：Python 包导入的"隐形墙"

顺手记一个今天踩到的坑，凡是把代码组织成"包"的人都会遇到。

我们的 memory/ 是一个包（有 __init__.py），long_term.py 里写的是 from memory.paths import MEM_STORE——这是包导入，要求 memory 的父目录在 sys.path 里。

如果你在 memory/ 目录里面直接 python test_c.py，而 test_c.py 又把 memory/ 自己（而不是它的父目录）加进 sys.path，就会炸：

1

ModuleNotFoundError: No module named 'memory'

原因：此时 Python 的搜索路径里只有 memory/ 自己，根本没有名为 memory 的包。

铁律：包名加不加，全工程必须统一。内部选了 from memory.xxx，外部调用方就必须夹包名。文件"在同一个文件夹"≠“可以不加包名”——import 永远是基于 sys.path 找顶层模块，不是基于"当前文件旁边有什么"。

最干净的运行方式，是从父目录用 -m 启动：

1
2


cd AgentLearn
python -m memory.test_c

六、总结

三层持久化是分层不是替代——文件管配置、SQLite 管画像、Chroma 管语义。
绝对路径是记忆不漂移的底线——os.path.dirname(os.path.abspath(__file__)) 用起来。
隐私是设计出来的，不是自动的——add_fact(private=True) 贴标签，recall() 默认不泄露，要带才带。

给账本找好保险柜、贴好标签、分好类，你的 Agent 才算真正"记得住、守得住"。下一步（Day4）我们做上下文压缩：把超长的老历史浓缩成一条系统摘要——压是浓缩，不是丢掉。

Pands

Sun, 16 Aug 2026 08:17:42 +0800

Pandas 增删改查完全指南：从入门到实战（附示例）

一、准备：创建示例数据

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


import pandas as pd

data = {
 "name": ["Alice", "Bob", "Charlie", "David"],
 "age": [20, 21, 19, 22],
 "score": [85, 92, 78, 88],
}
df = pd.DataFrame(data)
print(df)
# name age score
# 0 Alice 20 85
# 1 Bob 21 92
# 2 Charlie 19 78
# 3 David 22 88

下文所有「增删改查」都基于这份 df。

二、查（Read / 查询）

1. 从外部读取数据

1
2
3


df = pd.read_csv("data.csv") # CSV
df = pd.read_excel("data.xlsx") # Excel
df = pd.read_json("data.json") # JSON

2. 快速预览

1
2
3
4


df.head(3) # 前 3 行
df.tail(2) # 后 2 行
df.info() # 字段、类型、非空数
df.describe() # 数值列统计（均值/最值等）

3. 选择列

1
2


df["score"] # 单列（返回 Series）
df[["name", "score"]] # 多列（返回 DataFrame）

4. 选择行：`loc` 按标签，`iloc` 按位置

1
2
3
4


df.loc[0] # 索引为 0 的那一行
df.loc[0:2] # 索引 0~2（含 2）
df.iloc[0] # 第 1 行（按位置）
df.iloc[0:2] # 前 2 行（左闭右开）

5. 条件筛选

1
2
3


df[df["score"] > 80] # 分数大于 80
df[(df["age"] > 20) & (df["score"] > 80)] # 多条件用 & | ~，每个条件加括号
df[df["name"].isin(["Alice", "Bob"])] # 在列表中

三、增（Create / 新增）

1. 新增一列（最常用）

1

df["grade"] = df["score"].apply(lambda x: "A" if x >= 90 else "B")

2. 新增一行

1
2
3
4
5
6


# 推荐：pd.concat（pandas 2.x 中 append 已弃用）
new_row = {"name": "Eve", "age": 20, "score": 95}
df = pd.concat([df, pd.DataFrame([new_row])], ignore_index=True)

# 或：用 loc 直接追加到末尾
df.loc[len(df)] = ["Frank", 23, 90]

四、改（Update / 修改）

1. 修改单个单元格

1

df.loc[0, "score"] = 90

2. 批量修改（向量化 / apply）

1
2
3


df["score"] = df["score"] + 5 # 整列 +5
df["name"] = df["name"].str.upper() # 字符串列转大写
df["score"] = df["score"].apply(lambda x: x * 1.1) # apply 逐元素

3. 替换与填充

1
2


df.replace({"grade": "B"}, "C", inplace=True) # 值替换
df.fillna(0, inplace=True) # 缺失值填 0

4. 重命名列

1

df.rename(columns={"score": "成绩"}, inplace=True)

五、删（Delete / 删除）

1. 删除列

1
2


df.drop("age", axis=1, inplace=True) # axis=1 表示列
# 等价写法： del df["age"]

2. 删除行

1

df.drop(0, axis=0, inplace=True) # axis=0 表示行（默认）

3. 删除缺失值 / 重复行

1
2


df.dropna(inplace=True) # 删除含空值的行
df.drop_duplicates(inplace=True) # 删除完全重复的行

inplace=True 会直接修改原 DataFrame；不想改动原数据就去掉它，并用 df_new = ... 接收返回值。

六、高级查询：条件组合、多重筛选与字符串搜索

基础筛选 df[df["score"] > 80] 只够入门。真实分析里，你要的是「多条件组合 + 模糊匹配 + 跨列逻辑」。下面全部基于这份数据：

1
2
3
4
5
6
7


import pandas as pd
df = pd.DataFrame({
 "name": ["Alice", "Bob", "Charlie", "David", "Eve"],
 "age": [20, 21, 19, 22, 20],
 "score": [85, 92, 78, 88, 95],
 "city": ["BJ", "SH", "BJ", "GZ", "SH"],
})

1. 多条件组合：`&`（且）、`|`（或）、`~`（非）

1
2
3
4
5
6
7
8
9


# 分数>80 且 年龄>20
mask = (df["score"] > 80) & (df["age"] > 20)
df[mask]

# 分数<60 或 分数>95
df[(df["score"] < 60) | (df["score"] > 95)]

# 非：不在 90 分及以上
df[~(df["score"] >= 90)]

⚠️ 每个条件必须单独用括号包起来，&/| 优先级高于比较运算，不加括号会算错。

2. `df.query()`：用字符串表达式查询（推荐，可读性强）

1
2
3
4


df.query("score > 80 and age > 20")
df.query("city == 'BJ'") # 字符串值加引号
df.query("score > @t", local_dict={"t": 80}) # 引用外部变量加 @
df.query("score > 80 and city in ['BJ','SH']") # in 多值

query 支持 and / or / not / in，写法接近 SQL，复杂条件尤其清爽，性能也不错。

3. `isin()`：多值匹配（等于列表里任意一个）

1
2


df[df["name"].isin(["Alice", "Bob", "David"])] # 在列表中
df[~df["name"].isin(["Alice"])] # 不在列表中

4. `between()`：闭区间范围查询

1

df[df["score"].between(80, 90)] # 80 <= score <= 90

5. 字符串模糊与正则搜索：`str.contains` 等

1
2
3
4
5


df[df["name"].str.contains("li")] # 包含 "li"
df[df["name"].str.contains("li", case=False)] # 忽略大小写
df[df["name"].str.contains(r"^A", regex=True)] # 正则：以 A 开头
df[df["name"].str.startswith("A")] # 以 A 开头
df[df["name"].str.endswith("e")] # 以 e 结尾

6. 跨列自定义函数筛选

1

df[df.apply(lambda r: r["score"] > r["age"] * 4, axis=1)]

能用向量化就用向量化，apply 逐行执行，数据量大时慢很多。

7. 多条件赋值：`np.where`（二分类）/ `np.select`（多分类）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import numpy as np
df["pass"] = np.where(df["score"] >= 60, "及格", "不及格")

conditions = [
 df["score"] >= 90,
 (df["score"] >= 80) & (df["score"] < 90),
 df["score"] < 80,
]
choices = ["A", "B", "C"]
df["level"] = np.select(conditions, choices, default="?")

8. 取最大 / 最小 N 行

1
2


df.nlargest(3, "score") # 分数最高的 3 行
df.nsmallest(3, "score") # 分数最低的 3 行

9. 跨表关联查询：`merge` 再筛选

1
2
3


other = pd.DataFrame({"name": ["Alice", "Bob"], "status": ["active", "off"]})
merged = pd.merge(df, other, on="name", how="left")
merged[merged["status"] == "active"] # 筛出活跃用户

七、综合实战

需求：给不及格（<80）的同学每人加 5 分，新增「等级」列，删掉重复行，最后保存。

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


import pandas as pd

df = pd.DataFrame({
 "name": ["Alice", "Bob", "Charlie", "David", "Alice"],
 "score": [85, 92, 78, 88, 85],
})

# 改：不及格 +5
df.loc[df["score"] < 80, "score"] += 5

# 增：等级列
df["level"] = df["score"].apply(lambda x: "A" if x >= 90 else "B")

# 删：重复行（Alice 出现两次）
df.drop_duplicates(inplace=True)

# 查：看结果
print(df)

# 存盘
df.to_csv("result.csv", index=False)

小结

操作	核心 API
查	`[]`、`loc`、`iloc`、`df[条件]`、`query`、`isin`、`between`、`str.contains`、`read_*`
增	`df["新列"]=`、`pd.concat`、`df.loc[len]`
改	`df.loc[行,列]=`、`apply`、`replace`、`fillna`、`rename`、`np.where`/`np.select`
删	`drop`、`dropna`、`drop_duplicates`
高级查询	`&`/`

记住一个原则：查询多用布尔索引与 query()，新增多用 concat，修改多用 loc + 向量化，删除多用 drop 系列，复杂分类用 np.select。把本文示例跑一遍，pandas 的增删改查与高级搜索就真正上手了。

长期记忆

Sun, 16 Aug 2026 01:03:01 +0800

长期记忆原理：语义嵌入 · 向量库 · RAG 心智模型 · 学习笔记

0. 一句话心智模型

1
2
3
4
5
6


用户事实 / 偏好
 ├─► 精确 KV（SQLite） → "用户喜欢 DeepSeek"=确定事实, key/value 秒查
 └─► 语义向量（Chroma） → "聊过什么相关话题"=模糊语义, 相似度召回
 │
 ▼ 首次 add 时 Chroma 自动嵌入, 落盘 ./mem_store/
 跨会话: 程序重启 → 重新连 PersistentClient → 之前存的事实还在

长期记忆 = 把用户事实嵌入成向量 → 落盘到本地 → 查询时语义召回。

1. 三个必须记住的点

短期 vs 长期是两种"不忘"：短期 = 本次对话不丢（在内存里）；长期 = 跨进程、跨天不丢（落盘到磁盘）。
Chroma 首次 add 会联网下载嵌入模型（默认 all-MiniLM 约 80MB）——需要联网，第一次跑会慢。
KV 和向量互补：确定事实（名字、默认模型）用 SQLite；语义相关历史（“之前吐槽过什么”）才走向量。不是谁替代谁。

2. 向量库和"写本地文件"到底差在哪

文件靠"精确匹配"（key 对上才有），向量库靠"语义相似"（意思接近就能找出来）。

向量库底层也是文件——Chroma 把"数字指纹"和原文一起写进 ./mem_store/ 文件夹。它并没有比"写本地文件"更高级，只是额外多存了那份"数字指纹"，并把指纹组织成"能快速按相似度找"的索引结构。所以"向量库" = 本地文件 + 指纹索引。

3. 长期记忆的完整过程（三步）

假设用户昨天说"我特别不喜欢用 GPT，觉得它回答太啰嗦"，你想让它今天还能"记得"。

第 1 步：嵌入（embedding）——把文字变成"指纹"

计算机看不懂文字，只看得懂数字。嵌入就是把一句话变成一串固定长度的数字（向量，比如 384 个）：

1

"我特别不喜欢用 GPT" → [0.21, -0.03, 0.88, ...] (384 个数字)

关键：意思相近的句子，数字也相近。这是嵌入模型（如 all-MiniLM）训练出来的本领。

第 2 步：落盘——把"指纹 + 原文"一起存进本地文件夹

Chroma 把这个数字指纹和原文一起写进本地 ./mem_store/（本质就是一些文件）。这就是"写本地文件"！只是多了那份指纹和索引。

第 3 步：召回（recall）——把新问题也变指纹，然后"找指纹最像的"

用户今天问"你觉得我用哪个模型好？"：

先把这句话也变成指纹（同一个嵌入模型）；
拿这个指纹去 mem_store 里找"指纹最像的几条"（数学上叫算余弦相似度）；
找到"我特别不喜欢用 GPT" → 把它塞进这次的上下文里告诉模型。

所以长期记忆 = 存的时候"文字→指纹→落盘"；查的时候"问题→指纹→找最像的→取回原文"。

4. 三种存储方式对比（一张表记牢）

方式	怎么查	适合	类比
本地文件（JSON/txt）	按 key 精确读	少量确定数据	手写便签
SQLite（KV）	按 key 秒查、可更新	用户画像：名字、默认模型	有编号的档案柜
Chroma（向量）	按语义相似度召回	模糊历史、偏好、相关话题	按内容指纹找书的图书馆

向量库并没有"更高级"，它只是"换了一种查法"——用语义相似度代替精确 key。存"用户叫什么"用 SQLite/文件就够了；存"用户之前吐槽过什么"这种需要"意思接近就找到"的，才用向量库。两者配合才完整。

5. 和 RAG 的对应关系（同一个套路）

长期记忆，其实就是单文档 RAG 把"文档"换成"用户事实"且持久化：

你的方法	RAG 里的角色
`add_fact`	写入 / 索引（`chunk + embed + store`）
`recall`	检索（`query embed + similarity search`）
`PersistentClient(path=...)`	让向量库落到磁盘，而不是内存版

6. 源码逐段讲解（注释拆解）

6.1 `long_term.py`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


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

BASE = Path(__file__).parent

__file__：Python 内置变量，代表"当前这个文件自己的路径"（含文件名）。例如 long_term.py 在 C:\Desktop\AgentLearn\memory\long_term.py，那 __file__ 就是这个完整字符串。
Path(...)：把字符串"升级"成路径对象，才能用它做路径拼接、取上级目录（而不是手动拼字符串）。
.parent：取这个文件的"爸爸"（上一级目录）。C:\...\memory\long_term.py 的 .parent = C:\...\memory\（去掉文件名，回到 memory 目录）。
合起来：BASE = Path(__file__).parent = “记下我这个代码文件所在的文件夹”。

1
2
3
4


class LongTermMemory:
 def __init__(self, path=str(BASE/"mem_store"), collection="long_term"):
 self.client = chromadb.PersistentClient(path=path) # 建客户端(连上本地存储)
 self.col = self.client.get_or_create_collection(collection) # 拿货架(没有就建)

PersistentClient(path=path)：创建持久化客户端——向量库落到磁盘（不是内存），关掉程序数据还在。
collection（集合） = Chroma 里的一个"货架/分档"，用来把不同类型的数据分开存。collection="long_term" = 指定"我要用/建一个叫 long_term 的货架"。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


 def add_fact(self, text: str, fid: str):
 # Chroma 的 add 要求每个参数都是列表（ids=[...]、documents=[...]）
 # ——因为 Chroma 的 add 支持批量加。就算你只存一条，也要写成 [fid]、[text]
 self.col.add(ids=[fid], documents=[text])

 def recall(self, query: str, k: int = 3) -> list[str]:
 res = self.col.query(query_texts=[query], n_results=k)
 return res["documents"][0] if res["documents"] else []

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

add_fact：存一条事实。Chroma 首次 add 会自动调用嵌入模型把 text 变成向量，连同原文存进 mem_store/。
recall：把 query 也嵌入，找最像的 k 条，返回原文列表 res["documents"][0]（[0] 因为一次只问一个问题）。
delete：按 fid 删除。

6.2 `profile_store.py`

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


import sqlite3, json
from pathlib import Path
BASE = Path(__file__).parent

class ProfileStore:
 def __init__(self, db_path=str(BASE / "memory.db")):
 self.con = sqlite3.connect(db_path) # 连接/创建库
 self.con.execute("CREATE TABLE IF NOT EXISTS profile (k TEXT PRIMARY KEY, v TEXT)") # 建表
 self.con.commit() # 提交

 def set_profile(self, k, v):
 self.con.execute("INSERT OR REPLACE INTO profile VALUES(?,?)", (k, json.dumps(v))) # 写

 def get_profile(self, k):
 row = self.con.execute("SELECT v FROM profile WHERE k=?", (k,)).fetchone() # 查
 return json.loads(row[0]) if row else None # 取第一列 / 防空 / 还原 dict

sqlite3.connect(db_path)：连接（或创建）SQLite 库。
CREATE TABLE IF NOT EXISTS profile (k TEXT PRIMARY KEY, v TEXT)：建一张表，k 主键、v 文本。
json.dumps(v) / json.loads(row[0])：因为 SQLite 字段是文本，Python 的 dict 要先 dumps 成字符串再存，读出后 loads 还原。
? 占位符：防注入，值通过第二个参数传。

7. 最终源码（干净附录）

`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


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

BASE = Path(__file__).parent

class LongTermMemory:
 def __init__(self, path=str(BASE/"mem_store"), collection="long_term"):
 self.client = chromadb.PersistentClient(path=path) #建客户端(连上本地存储)
 self.col = self.client.get_or_create_collection(collection)# 拿货架(没有就建)

 def add_fact(self, text: str, fid: str):
 #Chroma 的 add 要求每个参数都是列表（ids=[...]、documents=[...]）——因为 Chroma 的 add 支持批量加。就算你只存一条，也要写成 [fid]、[text]
 self.col.add(ids=[fid], documents=[text])

 def recall(self, query: str, k: int = 3) -> list[str]:
 res = self.col.query(query_texts=[query], n_results=k)
 return res["documents"][0] if res["documents"] else []

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

`profile_store.py`

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


import sqlite3, json
from pathlib import Path
BASE = Path(__file__).parent

class ProfileStore:
 def __init__(self, db_path=str(BASE / "memory.db")):
 self.con = sqlite3.connect(db_path)
 self.con.execute("CREATE TABLE IF NOT EXISTS profile (k TEXT PRIMARY KEY, v TEXT)")
 self.con.commit()

 def set_profile(self, k, v):
 self.con.execute("INSERT OR REPLACE INTO profile VALUES(?,?)", (k, json.dumps(v)))

 def get_profile(self, k):
 row = self.con.execute("SELECT v FROM profile WHERE k=?", (k,)).fetchone()
 return json.loads(row[0]) if row else None

8. 验收 & 避坑

能口头说清"嵌入→落盘→召回"三步分别是干嘛的。
能区分：确定事实走 SQLite，模糊语义走 Chroma，不是替代关系。
能说清 PersistentClient 是"落盘版"、跨会话重启后数据还在。
理解 res["documents"][0] 里 [0] 是因为一次只查一个问题。

现象	最可能原因
首次 `add` 很慢 / 卡住	在联网下载嵌入模型（all-MiniLM ~80MB），正常现象，等一次即可
`recall` 返回空	`mem_store/` 路径不对或库为空；检查 `PersistentClient(path=)` 是否指向同一目录
`KeyError: 'documents'`	写成 `res["document"]`（单数）了，正确是复数 `res["documents"]`
SQLite “database is locked”	多进程同时写；学习期单进程即可

把"长期记忆"从一句口号拆成了可运行的机制：文字→向量→落盘→相似度召回，本质上就是单文档 RAG 把"文档"换成"用户事实"。

魔术方法是什么，下划线在Python中的作用

Sat, 15 Aug 2026 14:04:59 +0800

下划线的作用

Python 用下划线表达"访问级别"，但都是约定，不是强制（Python 没有 private 那种编译期强制的封装）：

写法	含义	类比
`_x`（单个前导）	“别碰我"——约定为私有，但还是能访问	贴了"内部文件"标签的柜子，锁没锁
`__x`（双前导）	“我真的不想让你碰"——名称改写（name mangling），外部访问会被改名	上了锁的柜子，钥匙藏在你看不到的地方
`__x__`（双前导+双结尾）	魔术方法/特殊属性（dunder）	系统的"官方接口”，比如 `__init__`、`__str__`
`x_`（单结尾）	避免和关键字冲突，比如 `class_`	命名时的权宜之计

init 是 x 这一类——双下划线包起来 = Python 官方预留的特殊方法名。init 就是"构造方法”，str 就是"Java 的 toString()"：

if name == “main” 是什么

name 是一个内置变量，Python 会给每个文件自动设置，值有两种可能：

这个文件被直接运行，"main"
这个文件被别人 import，“baseloop”（模块名）

常用魔法方法清单

1.对象生命周期

魔法方法	作用	Java 类比
`__init__(self, ...)`	创建对象时初始化	构造函数
`__new__(cls, ...)`	真正分配内存（先于 `__init__`）	`new` 关键字底层
`__del__(self)`	对象被回收前	析构函数（几乎不写）

字符串类

魔法方法	作用	Java 类比
`__str__`	`print` / `str()` 调用	`toString()`
`__repr__`	`repr()` / 调试输出调用	`Object.toString()` 的严格版

比较运算（核心！）

魔法方法	运算符	Java 类比
`__eq__(self, other)`	`==`	`equals()`
`__lt__` / `__gt__` / `__le__` / `__ge__`	`<` `>` `<=` `>=`	`compareTo()` 相关
`__hash__(self)`	`hash(obj)`	`hashCode()`

注意：Python 的 == 默认比较"是不是同一个对象"（内存地址），跟 Java 的 == 一样。要比较"内容相同"必须重写 eq——就是 Java 里重写 equals()。

4.算数类

魔法方法	运算符	例子
`__add__`	`+`	让 `向量 + 向量`
`__sub__`	`-`	同上
`__mul__`	`*`	让 `向量 * 标量`

让对象函数

魔法方法	作用	调用方式
`__call__`	实例可调用	`obj(参数)`

上下文管理（with函数）

魔法方法	作用	调用方式
`__enter__`	进入 with 时	`with obj as x:`
`__exit__`	退出 with 时（自动清理）	同上

第一阶段整合代码

Sat, 15 Aug 2026 08:43:51 +0800

 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
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245


from openai import OpenAI
from dotenv import load_dotenv, find_dotenv
import json,os,ast
import urllib.request
from pathlib import Path
import openmeteo_requests
load_dotenv(override=True, dotenv_path=find_dotenv())

class LLMClient():
 def chat(self,message,tools=None):
 raise NotImplemented("子类必须实现 chat()")

class RealLLM(LLMClient): #client初始化

 def __init__(self,provide="deepseek"):
 cfg={
 "deepseek":{"base_url":"https://api.deepseek.com","key":"DEEPSEEK_API_KEY","model":"deepseek-v4-flash"},
 "kimi": {"base_url": "https://api.moonshot.cn/v1", "key": "MOONSHOT_API_KEY", "model": "kimi-k2.6"},
 }[provide]
 self.client = OpenAI(api_key=os.getenv(cfg["key"]), base_url=cfg["base_url"])
 print(f"实际使用的 provider={provide}, key 已加载={'是' if os.getenv(cfg['key']) else '否'}")
 # print(repr(os.getenv(cfg["key"])))
 self.model=cfg["model"]
 print(provide)
 def chat(self,messages,tools=None):
 return self.client.chat.completions.create(model=self.model,messages=messages,tools=tools)

class StreamLLM(LLMClient):
 def __init__(self,provide="deepseek"):
 cfg={
 "deepseek":{"base_url":"https://api.deepseek.com","key":"DEEPSEEK_API_KEY","model":"deepseek-v4-flash"},
 "kimi": {"base_url": "https://api.moonshot.cn/v1", "key": "MOONSHOT_API_KEY", "model": "kimi-k2.6"},
 }[provide]
 self.client = OpenAI(api_key=os.getenv(cfg["key"]), base_url=cfg["base_url"])
 self.model=cfg["model"]
 print(provide)
 def chat(self, messages,**kwargs):
 return 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))

def route_model(question): #模型硬路由

 """从用户输入里找模型名,找不到用默认"""
 for name in ["kimi", "deepseek", "qwen", "gpt"]:
 if name in question.lower():
 return name
 return "deepseek" # 默认



def run_tool(name,arg):#调用工具
 try:
 return TOOLS_FUNC[name](**arg)
 except Exception as e:
 return(f"参数出错了:{e}")

def fc_loop(question,llm,max_rounds=3):#fc主函数
 messages=[{"role":"user","content":question}]
 tool_records = [] 
 for _ in range(max_rounds):
 rep=llm.chat(messages,tools=TOOLS_SCHEMA)
 msg=rep.choices[0].message
 if not msg.tool_calls:
 return {
 "answer": msg.content, # 最终答案
 "tool_records": tool_records, # [] = 没调工具(模型猜的!)
 }
 #return msg.content
 messages.append(msg)
 for tc in msg.tool_calls:
 try:
 arg=json.loads(tc.function.arguments)
 except Exception as e:
 messages.append({"role": "tool", "tool_call_id": tc.id, "content": f"参数解析失败:{e}"})
 continue
 result=run_tool(tc.function.name,arg)
 print(arg)
 tool_records.append({"tool": tc.function.name, "args": arg, "result": result})
 messages.append({"role":"tool","tool_call_id":tc.id,"content":result})
 # print(msg)
 return {"answer": "达到最大轮数", "tool_records": tool_records}

def get_weather(latitude:float,longitude:float)->str:#查询天气函数实现
 openmeteo = openmeteo_requests.Client()
 url = (f"https://api.open-meteo.com/v1/forecast?latitude={latitude}"
 f"&longitude={longitude}"
 f"&current=temperature_2m,relative_humidity_2m,wind_speed_10m,wind_direction_10m"
 f"&daily=weather_code,temperature_2m_max,temperature_2m_min,sunrise,sunset,precipitation_probability_max"
 f"&timezone=Asia%2FShanghai")
 data = json.loads(urllib.request.urlopen(url).read())
 WEATHER_CODE_DESC = {
 0: "晴朗的天空",
 1: "主要晴朗",
 2: "局部多云",
 3: "阴天",
 45: "雾气",
 48: "霜雾沉积",
 51: "毛毛雨：轻度",
 53: "毛毛雨：中度",
 55: "毛毛雨：密集",
 56: "冻毛毛雨：轻微",
 57: "冻毛毛雨：强度高",
 61: "降雨：轻度",
 63: "降雨：中度",
 65: "降雨：强雨",
 66: "冻雨：轻度",
 67: "冻雨：强烈",
 71: "降雪量：轻度",
 73: "降雪量：中度",
 75: "降雪量：重度",
 77: "雪粒",
 80: "阵雨：轻度",
 81: "阵雨：中度",
 82: "阵雨：猛烈",
 85: "雪阵阵：轻微",
 86: "雪阵阵：猛烈",
 95: "雷暴：轻度或中度",
 96: "雷暴伴轻微冰雹",
 99: "雷暴伴强烈冰雹",
 }
 cur = data["current"]
 today = {k: v[0] for k, v in data["daily"].items()}
 return json.dumps({
 "天气": WEATHER_CODE_DESC.get(today["weather_code"], f"未知天气码{today['weather_code']}"),
 "当前温度_C": cur["temperature_2m"],
 "湿度_%": cur["relative_humidity_2m"],
 "今日最高_C": today["temperature_2m_max"],
 "今日最低_C": today["temperature_2m_min"],
 "日出": today["sunrise"][11:16],
 "日落": today["sunset"][11:16],
 "降雨概率_%": today["precipitation_probability_max"],
 }, ensure_ascii=False)

def calculator(expr: str) -> str:#四则运算函数实现
 return str(ast.literal_eval(expr))

TOOLS_FUNC = {"get_weather": get_weather, "calculator": calculator} 

with open("D:\\Desktop\\桌面文件\\AgentLearn\\agent\\tools.json", encoding="utf-8") as f:
 TOOLS_SCHEMA = json.load(f) 

def get_response(messages,max_tokens=500):#流式回复
 streamllm=StreamLLM()
 response = streamllm.chat(messages,max_tokens=max_tokens)
 reasoning_content, content = "", ""
 for chunk in response:
 delta = chunk.choices[0].delta
 if delta.reasoning_content:
 reasoning_content += delta.reasoning_content
 if delta.content:
 content += delta.content
 if content:
 messages.append({"role": "assistant", "content": content})
 else:
 content = reasoning_content
 return content

def ask(quextion,system_prompt="你是擅长多种角度对比方案的资深决策专家",max_tokens=500):
 msgs=[
 {"role": "system", "content": system_prompt},
 {"role": "user", "content": quextion}
 ]
 response = get_response(msgs, max_tokens)
 return response

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

def cot_prompt(question,system_prompt="你是一个逻辑缜密，思维严谨的推理助手"):#cot实现函数
 u=f"请一步步思考，再给出答案。\n问题:{question}"
 return [{"role": "system", "content": system_prompt}, {"role": "user", "content": u}]

DEFAULT_EXAMPLES = [
 {"question": "我明天下午3点约了张医生复诊",
 "answer": "时间:明天下午3点;人物:张医生;事项:复诊"},
 {"question": "周五晚上和李总在望江楼吃饭",
 "answer": "时间:周五晚上;人物:李总;事项:吃饭"},
]

def few_shot_prompt(question,examples=DEFAULT_EXAMPLES,system_prompt="你是擅长信息抽取的助手") :#fewshort实现
 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

def react_prompt(question):#react启动
 return fc_loop(question, RealLLM(route_model(question))) 

BUILDERS = {"cot": cot_prompt, "few_shot": few_shot_prompt, "react": react_prompt}

def auto_select(question):#思维选择器
 content=f"判断下面用户的问题适合哪种回答，只输出四个英文字符串中的一个输出格式：cot_prompt或few_shot_prompt或react_prompt或tot_solve)\n规则:注重结果中间思考过程的任务，逻辑推理，数学解题过程，公式推导输出,日常对话cot_prompt,格式固定模板化输出的，格式化输出文本，文本提取特定词汇格式化输出的输出,Few_shot_prompt,需要依赖其他工具的输出react_prompt,开放性有多种选择回答的问题，思维发散问题，思维风暴，多种选择多种路径实现，多选择对比找最优解决方案输出tot_solve\n问题:{question}"
 msgs = get_response([{"role": "user", "content": content}], max_tokens=50)
 print(f"[调试] 原始: {msgs!r}")
 text = msgs.lower()
 for mode in ["tot", "react", "few_shot", "cot"]: 
 if mode in text:
 return mode
 print("[警告] 未识别到模式名,兜底 cot")
 return "cot"

def run_mode(mode,question,**kw):
 if mode =="tot":
 schemes, scores, best = tot_solve(question, n=kw.get("n", 3))
 return f"【方案】\n{schemes}\n\n【评审】\n{scores}\n\n【决策】\n{best}"
 if mode =="react":
 out = react_prompt(question) 
 if out["tool_records"]:
 # 展示调用记录
 print("工具调用记录:", out["tool_records"])
 else:
 # ⚠️ 模型没调工具,可能是在猜(幻觉风险)
 print("警告:模型未调用任何工具,回答可能为模型推断")
 return out["answer"]
 #return fc_loop(question, RealLLM("deepseek")) 
 if mode not in BUILDERS:
 raise ValueError(f"未知模式:{mode},可选 {list(BUILDERS) + ['tot']}")
 msgs = BUILDERS[mode](question,**kw)
 return get_response(msgs,**kw) 

if __name__=="__main__":
 while True:
 user_input = input("User: ")
 if user_input.lower() in ["exit", "quit"]:
 break
 mode = auto_select(user_input) 
 print(f"[使用模式] {mode}")
 result = run_mode(mode, user_input) # ② 按模式调度(统一返回字符串)
 print("Agent导师:", result) 

ShotMemory

Sat, 15 Aug 2026 00:04:07 +0800

Agent短期记忆

大模型是没有记忆的，它不会记住上次聊了什么，每次聊天都是一个新的任务。短期记忆 = “给大模型的对话历史设一个上限”，因为模型每次只能"看"有限的上下文（token 窗口），你不可能把无限长的聊天记录全塞给它。主要包括四个概念，全量缓冲 / 滑动窗口 / token 裁剪 / 保留策略

全量缓冲（conversation buffer）

把所有对话一条不落全存着，像记账一样，代价就是每次给大模型输入的历史逐渐增加，Token消耗也逐渐增加直至最大上下文窗口。

1
2
3
4
5
6


buffer = [
 {"role": "user", "content": "你好"},
 {"role": "assistant", "content": "你好，有什么可以帮你？"},
 {"role": "user", "content": "我叫小王"},
 # ... 越攒越多,永不丢弃
]

滑动窗口（sliding window）

1
2
3


# 从 buffer 里取:系统提示 + 最近 N 条
def context(self):
 return sys_msgs + buffer[-N:] # 只看最近 N 条

给模型看的时候，只取最近 N 条——像手机相册"最近 10 张，滑动窗口解决的是"给模型的输入太长"，不是"存储"太长。

存储 = 你程序里"攒着"的对话记录（buffer）输入 = 你每次请求发给模型的那段消息

窗口只给模型看最近 10 条（输入可控），但 buffer 里存了 100 轮的原文 → 内存/文件越来越大，重启时加载越来越慢。

token 裁剪（trim）

抽屉真的装不下了，扔最旧的东西。这是"真删"——和窗口的"只是不给你看"完全不同。裁剪直接改 buffer。

保留策略（retention policy）

哪些消息是"红线"，永远不能删——就是 system_roles（系统提示）。

1
2
3


system_roles = ("system",) # 系统提示是红线
# 窗口和裁剪都先把它单独拎出来,永远保留
sys_msgs = [m for m in buffer if m["role"] in system_roles]

三者关系：由粗到细的三级防线

全量缓冲(全留,最费token) ↓ 取上下文时滑动窗口(只看最近N条,不删) ← 管"输入"长短 ↓ buffer 真的超了 token 裁剪(从头部真删,超了删) ← 管"存储"大小 ↓ 但无论怎么删保留策略(系统提示永远不动) ← 红线,兜底

 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


class ShortTermMemory:
 def __init__(self,window=10,maxtokens:int=500,system_roles=("system",)):
 self.window=window #聊天窗口大小
 self.maxtokens=maxtokens #最大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) #1 个 token ≈ 3~4 个英文字符（约 0.75 个英文单词）

 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.maxtokens and len(others)>1:
 others.pop(0)
 self.buffer=sys_msgs+others
 return self.buffer
 

总结：短期记忆 = buffer 存 + context 取窗口 + trim 真删 + system 永留

Function Calling

Mon, 10 Aug 2026 02:58:11 +0800

完整流程

函数注册：告诉 LLM"我有哪些函数、每个函数要什么参数"(tools 列表)
LLM 决定:输出"我要调 get_weather,参数 city=北京"(不是直接回答)
代码执行:代码解析出函数名和参数,真正调用 get_weather(“北京”)
结果回填:把函数返回值作为 tool 消息喂回给 LLM,让它基于真实结果回答 → 如果还需要别的信息,重复2，3，4,直到 LLM 直接给最终答案

最小系统模拟示例

FC 循环的"骨架清单 ① 开头: messages = [{“role”:“user”, …}] ← 只有一条用户消息 ② 循环: for _ in range(MAX_ROUNDS): ← 最多转几圈 ③ 判断: if not msg.tool_calls: 返回 ← 模型没要工具 → 结束 ④ 有工具: append assistant(带tool_calls) + 执行 + append tool ⑤ 结果: 模型看到 tool 结果,再回答 → 回到③

 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


import json
from openai import OpenAI
import os
def get_weather(city:str)->str: 
 #天气实际查询函数
 return f"{city}"+"今天台风，注意安全"

# 注册工具
tools=[ 
 {
 "type":"function","function":{
 "name":"get_weather","description":"获取指定城市天气","parameters":{
 "type":"object",
 "properties":{
 "city":{
 "type":"string"
 }
 },
 "required":["city"]
 }
 }
 } 
]
messages=[{"role":"user","content":"今天北京天气怎么样"}]
client=OpenAI(api_key=os.getenv("DEEPSEEK_API_KEY"),base_url="https://api.deepseek.com")
res=client.chat.completions.create(
 model="deepseek-v4-flash",
 messages=messages,
 tools=tools,
 max_tokens=100,
)
msg=res.choices[0].message
try:
 print("msg:type",type(msg),"\n\n",msg)
except:
 print("无法打印")
if msg.tool_calls:
 messages.append(msg)
 for tc in msg.tool_calls:
 result=get_weather(**json.loads(tc.function.arguments))
 try:
 print("result:"+result+"\n")
 except Exception as e:
 print("result无法打印",e)
 messages.append({"role":"tool","tool_call_id":tc.id,"content":result})
 final=client.chat.completions.create(model="deepseek-v4-flash", messages=messages, tools=tools)
 print(final.choices[0].message.content)

改为真实API接口

 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


import json
from openai import OpenAI
import os
import urllib.request
def get_weather(city:str)->str: 
 city_encoded = urllib.parse.quote(city) # 深圳 → %E6%B7%B1%E5%9C%B3
 url = f"https://wttr.in/{city_encoded}?format=3"
 # 返回简短的天气文本
 return urllib.request.urlopen(url).read().decode()

# 注册工具
TOOLS_SEARCH=[
 {
 "type":"function","function":{
 "name":"get_weather","description":"获取指定城市天气","parameters":{
 "type":"object",
 "properties":{
 "city":{
 "type":"string"
 }
 },
 "required":["city"]
 }
 }
 } 
]

def fc_loop(user_input,max_runs=3):
 messages=[{"role":"user","content":user_input}]
 client=OpenAI(api_key=os.getenv("DEEPSEEK_API_KEY"),base_url="https://api.deepseek.com")
 for _ in range(max_runs):
 res=client.chat.completions.create(
 model="deepseek-v4-flash",
 messages=messages,
 tools= TOOLS_SEARCH,
 max_tokens=100,
 )
 msg=res.choices[0].message
 try:
 print("msg:type",type(msg),"\n\n",msg)
 except:
 print("无法打印")
 if not msg.tool_calls:
 return msg.content
 messages.append(msg)
 for tc in msg.tool_calls:
 #result=get_weather(**json.loads(tc.function.arguments))
 try:
 arg=json.loads(tc.function.arguments)
 except Exception as e:
 messages.append({"role": "tool", "tool_call_id": tc.id, "content": f"参数解析失败:{e}"})
 continue
 result=run_status(tc.function.name,arg)
 messages.append({"role":"tool","tool_call_id":tc.id,"content":result})
 try:
 print("arg:", arg, "result:", result)
 except Exception as e:
 print("result无法打印",e)
 return "达到最大轮数,已停止"
TOOLS_FUNC = {"get_weather": get_weather}
def run_status(name:str,args:dict)->str:
 #执行工具;出错不崩,把错误信息返回给模型,让它自己修正
 try:
 if name not in TOOLS_FUNC:
 return f"未知工具:{name}"
 return TOOLS_FUNC[name](**args)
 except Exception as e:
 return f"工具执行失败:{e}"


if __name__=="__main__":
 print(fc_loop(input("天气助手:")))

仿照Open接口，做假模型测试，优点不消耗token

 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
 95
 96
 97
 98
 99
100
101


from openai import OpenAI
from dotenv import load_dotenv, find_dotenv
import json,os,ast
import urllib.request
load_dotenv(override=True, dotenv_path=find_dotenv())

class LLMClient():
 def chat(self,message,tools=None):
 raise NotImplemented("子类必须实现 chat()")

class RealLLM(LLMClient):
 def __init__(self,provide="deepseek"):
 cfg={
 "deepseek":{"base_url":"https://api.deepseek.com","key":"DEEPSEEK_API_KEY","model":"deepseek-v4-flash"},
 "openai": {"base_url": None, "key": "OPENAI_API_KEY", "model": "gpt-4o-mini"},
 }[provide]
 self.client = OpenAI(api_key=os.getenv(cfg["key"]), base_url=cfg["base_url"])
 print(f"实际使用的 provider={provide}, key 尾号={os.getenv(cfg['key'])[-6:] if os.getenv(cfg['key']) else 'None'}")

 self.model=cfg["model"]
 def chat(self,messages,tools=None):
 return self.client.chat.completions.create(model=self.model,messages=messages,tools=tools)

class FakeMessage:
 def __init__(self,content=None,tool_calls=None):
 self.content,self.tool_calls=content,tool_calls

class FakeChoice:
 def __init__(self,message):
 self.message=message

class FakeResponse:
 def __init__(self, message): self.choices = [FakeChoice(message)]

class FakeFunction:
 def __init__(self, name, arguments):
 self.name, self.arguments = name, arguments


class FakeToolCall:
 def __init__(self, name, arguments):
 self.id = "call_mock_001"
 self.function = FakeFunction(name, arguments)

class MockLLM(LLMClient):
 def chat(self,message,tools=None):
 if message[-1]["role"]=="tool":
 result=message[-1]["content"]
 return FakeResponse(FakeMessage(content=f"模型看到工具结果[{result}]后给出的最终回答"))
 q=message[-1]["content"]
 if "天气" in q:
 return FakeResponse(FakeMessage(tool_calls=[FakeToolCall("get_weather",'{"city":"天津"}')]))
 if "等于" in q or "计算" in q:
 return FakeResponse(FakeMessage(tool_calls=[FakeToolCall("calculator", '{"expr": "1+1"}')]))
 return FakeResponse(FakeMessage(content="Mock回答"))

def run_tool(name,arg):
 try:
 return TOOLS_FUNC[name](**arg)
 except Exception as e:
 return(f"参数出错了:{e}")

def fc_loop(question,llm,max_rounds=3):
 messages=[{"role":"user","content":question}]
 for _ in range(max_rounds):
 rep=llm.chat(messages,tools=TOOLS_SCHEMA)
 msg=rep.choices[0].message
 if not msg.tool_calls:
 return msg.content
 messages.append(msg)
 for tc in msg.tool_calls:
 try:
 arg=json.loads(tc.function.arguments)
 except Exception as e:
 messages.append({"role": "tool", "tool_call_id": tc.id, "content": f"参数解析失败:{e}"})
 continue
 result=run_tool(tc.function.name,arg)
 messages.append({"role":"tool","tool_call_id":tc.id,"content":result})
 return "达到最大访问次数"

def get_weather(city:str)->str:#查询天气
 city_encoded = urllib.parse.quote(city) # 深圳 → %E6%B7%B1%E5%9C%B3
 url = f"https://wttr.in/{city_encoded}?format=3"
 # 返回简短的天气文本
 return urllib.request.urlopen(url).read().decode()

def calculator(expr: str) -> str:#四则运算
 return str(ast.literal_eval(expr))

TOOLS_FUNC = {"get_weather": get_weather, "calculator": calculator} 
TOOLS_SCHEMA = [
 {"type": "function", "function": {"name": "get_weather", "description": "查天气",
 "parameters": {"type": "object", "properties": {"city": {"type": "string"}}, "required": ["city"]}}},
 {"type": "function", "function": {"name": "calculator", "description": "四则运算",
 "parameters": {"type": "object", "properties": {"expr": {"type": "string"}}, "required": ["expr"]}}},
]

if __name__=="__main__":
 load_dotenv(override=True, dotenv_path=find_dotenv())
 llm = RealLLM("deepseek")
 print(fc_loop("天津天气怎么样", llm))

##接入真实天气api，接入模型路由

 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
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175


from openai import OpenAI
from dotenv import load_dotenv, find_dotenv
import json,os,ast
import urllib.request
from pathlib import Path
import openmeteo_requests
load_dotenv(override=True, dotenv_path=find_dotenv())

class LLMClient():
 def chat(self,message,tools=None):
 raise NotImplemented("子类必须实现 chat()")

class RealLLM(LLMClient):
 def __init__(self,provide="deepseek"):
 cfg={
 "deepseek":{"base_url":"https://api.deepseek.com","key":"DEEPSEEK_API_KEY","model":"deepseek-v4-flash"},
 "kimi": {"base_url": "https://api.moonshot.cn/v1", "key": "MOONSHOT_API_KEY", "model": "kimi-k2.6"},
 }[provide]
 self.client = OpenAI(api_key=os.getenv(cfg["key"]), base_url=cfg["base_url"])
 print(f"实际使用的 provider={provide}, key 已加载={'是' if os.getenv(cfg['key']) else '否'}")
 # print(repr(os.getenv(cfg["key"])))
 self.model=cfg["model"]
 print(provide)
 def chat(self,messages,tools=None):
 return self.client.chat.completions.create(model=self.model,messages=messages,tools=tools)

class FakeMessage:
 def __init__(self,content=None,tool_calls=None):
 self.content,self.tool_calls=content,tool_calls

class FakeChoice:
 def __init__(self,message):
 self.message=message

class FakeResponse:
 def __init__(self, message): self.choices = [FakeChoice(message)]

class FakeFunction:
 def __init__(self, name, arguments):
 self.name, self.arguments = name, arguments


class FakeToolCall:
 def __init__(self, name, arguments):
 self.id = "call_mock_001"
 self.function = FakeFunction(name, arguments)

class MockLLM(LLMClient):
 def chat(self,message,tools=None):
 if message[-1]["role"]=="tool":
 result=message[-1]["content"]
 return FakeResponse(FakeMessage(content=f"模型看到工具结果[{result}]后给出的最终回答"))
 q=message[-1]["content"]
 if "天气" in q:
 return FakeResponse(FakeMessage(tool_calls=[FakeToolCall("get_weather",'{"city":"天津"}')]))
 if "等于" in q or "计算" in q:
 return FakeResponse(FakeMessage(tool_calls=[FakeToolCall("calculator", '{"expr": "1+1"}')]))
 return FakeResponse(FakeMessage(content="Mock回答"))

def route_model(question): #模型硬路由
 """从用户输入里找模型名,找不到用默认"""
 for name in ["kimi", "deepseek", "qwen", "gpt"]:
 if name in question.lower():
 return name
 return "deepseek" # 默认


def run_tool(name,arg):
 try:
 return TOOLS_FUNC[name](**arg)
 except Exception as e:
 return(f"参数出错了:{e}")

def fc_loop(question,llm,max_rounds=3):
 messages=[{"role":"user","content":question}]
 tool_records = [] 
 for _ in range(max_rounds):
 rep=llm.chat(messages,tools=TOOLS_SCHEMA)
 msg=rep.choices[0].message
 if not msg.tool_calls:
 return {
 "answer": msg.content, # 最终答案
 "tool_records": tool_records, # [] = 没调工具(模型猜的!)
 }
 #return msg.content
 messages.append(msg)
 for tc in msg.tool_calls:
 try:
 arg=json.loads(tc.function.arguments)
 except Exception as e:
 messages.append({"role": "tool", "tool_call_id": tc.id, "content": f"参数解析失败:{e}"})
 continue
 result=run_tool(tc.function.name,arg)
 print(arg)
 tool_records.append({"tool": tc.function.name, "args": arg, "result": result})
 messages.append({"role":"tool","tool_call_id":tc.id,"content":result})
 # print(msg)
 return {"answer": "达到最大轮数", "tool_records": tool_records}

def get_weather(latitude:float,longitude:float)->str:#查询天气
 openmeteo = openmeteo_requests.Client()
 url = (f"https://api.open-meteo.com/v1/forecast?latitude={latitude}"
 f"&longitude={longitude}"
 f"&current=temperature_2m,relative_humidity_2m,wind_speed_10m,wind_direction_10m"
 f"&daily=weather_code,temperature_2m_max,temperature_2m_min,sunrise,sunset,precipitation_probability_max"
 f"&timezone=Asia%2FShanghai")
 data = json.loads(urllib.request.urlopen(url).read())
 WEATHER_CODE_DESC = {
 0: "晴朗的天空",
 1: "主要晴朗",
 2: "局部多云",
 3: "阴天",
 45: "雾气",
 48: "霜雾沉积",
 51: "毛毛雨：轻度",
 53: "毛毛雨：中度",
 55: "毛毛雨：密集",
 56: "冻毛毛雨：轻微",
 57: "冻毛毛雨：强度高",
 61: "降雨：轻度",
 63: "降雨：中度",
 65: "降雨：强雨",
 66: "冻雨：轻度",
 67: "冻雨：强烈",
 71: "降雪量：轻度",
 73: "降雪量：中度",
 75: "降雪量：重度",
 77: "雪粒",
 80: "阵雨：轻度",
 81: "阵雨：中度",
 82: "阵雨：猛烈",
 85: "雪阵阵：轻微",
 86: "雪阵阵：猛烈",
 95: "雷暴：轻度或中度",
 96: "雷暴伴轻微冰雹",
 99: "雷暴伴强烈冰雹",
 }
 cur = data["current"]
 today = {k: v[0] for k, v in data["daily"].items()}
 return json.dumps({
 "天气": WEATHER_CODE_DESC.get(today["weather_code"], f"未知天气码{today['weather_code']}"),
 "当前温度_C": cur["temperature_2m"],
 "湿度_%": cur["relative_humidity_2m"],
 "今日最高_C": today["temperature_2m_max"],
 "今日最低_C": today["temperature_2m_min"],
 "日出": today["sunrise"][11:16],
 "日落": today["sunset"][11:16],
 "降雨概率_%": today["precipitation_probability_max"],
 }, ensure_ascii=False)
 # print(result)
 return result
 #city_encoded = urllib.parse.quote(city) # 深圳 → %E6%B7%B1%E5%9C%B3
 #url = f"https://wttr.in/{city_encoded}?format=3"
 # 返回简短的天气文本
 # print(url)
 #return urllib.request.urlopen(url).read().decode()


def calculator(expr: str) -> str:#四则运算“
 return str(ast.literal_eval(expr))

TOOLS_FUNC = {"get_weather": get_weather, "calculator": calculator} 
TOOLS_SCHEMA = [
 {"type": "function", "function": {"name": "get_weather", "description": "查天气",
 "parameters": {"type": "object", "properties": {"latitude": {"type": "number"}, "longitude": {"type": "number"}}, "required": ["latitude", "longitude"]}}},
 {"type": "function", "function": {"name": "calculator", "description": "四则运算",
 "parameters": {"type": "object", "properties": {"expr": {"type": "string"}}, "required": ["expr"]}}},
]

if __name__=="__main__":
 user_input = input("User: ")
 llm = RealLLM(route_model(user_input))
 # 真实 DeepSeek 下问一个同时触发两个工具的问题
 print(fc_loop(user_input, llm))
 # get_weather(39.08,117.20)

##整合后prompt文件

 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
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126


from openai import OpenAI
from llm_client import fc_loop,route_model,RealLLM
import os

client = OpenAI(api_key=os.getenv("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com")

def get_response(messages,**kwargs):
 response = client.chat.completions.create(
 model=kwargs.get("model","deepseek-v4-flash"),
 messages=messages,
 stream=True,
 reasoning_effort=kwargs.get("reasoning_effort","low"),
 extra_body={"thinking": {"type": "enabled"}},
 max_tokens=kwargs.get("max_tokens", 500),
 )
 reasoning_content, content = "", ""
 for chunk in response:
 delta = chunk.choices[0].delta
 if delta.reasoning_content:
 reasoning_content += delta.reasoning_content
 if delta.content:
 content += delta.content
 if content:
 messages.append({"role": "assistant", "content": content})
 else:
 content = reasoning_content
 return content

def ask(quextion,system_prompt="你是擅长多种角度对比方案的资深决策专家",max_tokens=500):
 msgs=[
 {"role": "system", "content": system_prompt},
 {"role": "user", "content": quextion}
 ]
 response = get_response(msgs, max_tokens=max_tokens)
 return response

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

def cot_prompt(question,system_prompt="你是一个逻辑缜密，思维严谨的推理助手"):
 u=f"请一步步思考，再给出答案。\n问题:{question}"
 return [{"role": "system", "content": system_prompt}, {"role": "user", "content": u}]

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

def react_prompt(question,system_prompt="你是一位有多种能力的小助手",tools="天气查询、计算器"):
 # u=(f"可用工具:{tools}。严格按格式回答：\n"
 # f"Thought:先根据用户问题想清楚要干什么\n"
 # f"Action:调用哪个工具更适合该问题\n"
 # f"Action Input:参数\n"
 # f"Observation:工具返回结果\n"
 # f"Answer:最终答案\n\n问题:{question}" 
 # )
 #return [{"role": "system", "content": system_prompt}, {"role": "user", "content": u}]1
 return fc_loop(question, RealLLM(route_model(question))) 

BUILDERS = {"cot": cot_prompt, "few_shot": few_shot_prompt, "react": react_prompt}


def auto_select(question):
 content=f"判断下面用户的问题适合哪种回答，输出格式：cot_prompt或few_shot_prompt或react_prompt或tot_solve)\n规则:注重结果中间思考过程的任务，逻辑推理，数学解题过程，公式推导输出cot_prompt,格式固定模板化输出的，文本提取特定词汇格式化输出的输出Few_shot_prompt,需要依赖其他工具的输出react_prompt,开放性问题，思维发散问题，思维风暴，多种选择多种路径实现，多选择对比找最优解决方案输出tot_solve\n问题:{question}"
 msgs = get_response([{"role": "user", "content": content}], max_tokens=50)
 print(f"[调试] 原始: {msgs!r}")
 text = msgs.lower()
 for mode in ["tot", "react", "few_shot", "cot"]: # 顺序:先长的后短的?不,注意下面
 if mode in text:
 return mode
 print("[警告] 未识别到模式名,兜底 cot")
 return "cot"



def run_mode(mode,question,**kw):
 if mode =="tot":
 schemes, scores, best = tot_solve(question, n=kw.get("n", 3))
 return f"【方案】\n{schemes}\n\n【评审】\n{scores}\n\n【决策】\n{best}"
 if mode =="react":
 out = react_prompt(question) 
 if out["tool_records"]:
 # 展示调用记录
 print("工具调用记录:", out["tool_records"])
 else:
 # ⚠️ 模型没调工具,可能是在猜(幻觉风险)
 print("警告:模型未调用任何工具,回答可能为模型推断")
 return out["answer"]
 #return fc_loop(question, RealLLM("deepseek")) 
 if mode not in BUILDERS:
 raise ValueError(f"未知模式:{mode},可选 {list(BUILDERS) + ['tot']}")
 msgs = BUILDERS[mode](question, **kw)
 return get_response(msgs, **kw) 
while True:
 user_input = input("User: ")
 if user_input.lower() in ["exit", "quit"]:
 break
 mode = auto_select(user_input) 
 print(f"[使用模式] {mode}")
 result = run_mode(mode, user_input) 
 print("Agent导师:", result) 

思维链

Sat, 08 Aug 2026 02:58:24 +0800

什么样的 prompt 算"过及格线"？

Prompt三个硬指标：

指标	白话版	怎么检验
角色任务清晰	模型知道"你是谁、要干什么	换个人看 prompt，也能说出它的用途
输入输出边界明确	输入什么、输出什么格式	说死了连续跑 3 次，格式稳定
可复用可测试	换参数能复用，不是一次性	同一个函数换 3 组参数都能跑

为什么 Agent 工程师日常做的是 prompt 工程而不是微调？因为微调贵、慢、且改不动"工具调用"这种动态行为。prompt 工程便宜、灵活、可迭代——先 prompt，不够再考虑微调（那是模型工程师的活）

Codex 能写代码，但架构设计、工具拆分、安全审查、调试评估、部署运维这些工程决策必须由人来做。AI 是加速器，不是替代者——我学代码是为了能判断它写得好不好、能在它之上搭产品。

Prompt 及格线 = 角色清晰 + 边界明确 + 可复用可测试，与技巧高级与否无关。它是工程（组织输入）而不是微调（改权重）。AI 工具能写代码，但架构、调试、安全、评估是工程师的活。而 MD skill 能’一读就用’，靠的是代码把 MD 内容组装成 messages 调 API——文字和代码缺一不可。

提示词不是 md 文件，而是所有给模型看的内容；工具是给模型接的外肢，但工具的描述本身也是提示词。代码分工具和编排两层，前者被模型调用，后者指挥模型。

CoT 是什么

就是：别让模型"张口就答"，让它先把推理步骤写出来，再给结论。就像做数学题老师要求你"写出解题过程"，不许直接填答案。

解决什么问题：多步推理、数学逻辑题——模型直接答容易"跳步出错"，逼它写过程就能大幅提对

解决什么问题：格式固定、样本少的任务——比如"把消息分类成情绪/任务/闲聊"，规则说不清，但给 2~3 个例子它立刻就会

本质是一条指令（“请一步步思考”），放在System（当规则）或 User（当任务要求）都可以

Few-shot 是什么

在问题前面放几个「输入 → 输出」的例子，让模型照葫芦画瓢。

类比：新员工入职，先看老员工处理过的几单（输入→标准输出），再自己上手。给的是"范例"，不是"规则"。

解决什么问题：格式固定、样本少的任务——比如"把消息分类成情绪/任务/闲聊"，规则说不清，但给 2~3 个例子它立刻就会

本质是一组「输入→输出」示例，既不在 system 也不在 user，而是自己组成多轮 user/assistant 消息对，示例必须是"一问一答"的格式，所以拆成 user(示例问题) + assistant(示例答案) 交替出现

CoT 和 Few-shot 不是固定的角色位置，而是 prompt 技巧：CoT 是一条’要求一步步推理’的指令，可放 system 当规则或 user 当任务；Few-shot 是穿插在历史里的 user/assistant 问答对，让模型模仿格式。它们必须用代码实现，是因为 API 只接收带 role 的 messages 结构——文字是 content，代码是组装，两者结合才能复用。

多轮对话练习代码

 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 openai import OpenAI
import os
client =OpenAI(api_key=os.getenv("DEEPSEEK_API_KEY") ,base_url="https://api.deepseek.com")
def get_response(messages,**kwargs):
 response=client.chat.completions.create(model="deepseek-v4-flash",messages=messages,stream=True,reasoning_effort="low",extra_body={"thinking":{"type":"disabled"}},max_tokens=kwargs.get("max_tokens", 500),)
 reasoning_content=""
 content=""
 for chunk in response:
 delta=chunk.choices[0].delta
 if delta.reasoning_content:
 reasoning_content+=delta.reasoning_content
 if delta.content:
 content+=delta.content
 if content:
 messages.append({"role":"assistant","content":content})
 if not content:
 content = reasoning_content 
 return content
messages = [{"role": "system", "content": "你是一个耐心Agent老师，擅长用通俗的语言解释学生提到的问题。请根据问题一步步分析学生当前的学习阶段，给出最适合当前阶段的回答。"}]
while True:
 user_input = input("User: ")
 if user_input.lower() in ["exit", "quit"]:
 break
 messages.append({"role":"user","content":user_input})
 response = get_response(messages)
 print("Agent导师:", response)
if __name__ == "__main__": 
 pass

Recat

ReAct = 边思考边行动（Thought → Action → Observation → Answer），是 Agent 的前身。 ReAct = Reason + Act（边思考边行动），模型不闷头答，而是"想一步 → 做一步 → 看结果 → 再想下一步"，像人一样边动脑子边动手

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


Thought: 我先想清楚要做什么
Action: 调哪个工具
Action Input: 传什么参数
Observation: 工具返回了什么
Answer: 最终答案

---------------------------------------------------------------------

f"可用工具:{tools}。请严格按格式回答:\n"
 f"Thought: 我先想清楚要做什么\n"
 f"Action: 调哪个工具\n"
 f"Action Input: 参数\n"
 f"Observation: (工具返回,此处先占位)\n"
 f"Answer: 最终答案\n\n问题:{question}")

ToT

ToT 的实现核心是三步循环：发散（生成多条路径）→ 评估（打分）→ 收敛（选最优）。工程上两种做法：单 prompt 版让模型一口气走完三步、成本低；真 ToT 分三次调用 API、每步可控可干预，代价是 3 倍调用。选型看任务——快速出方案用单 prompt，关键决策用多轮循环

单词调用

 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


from openai import OpenAI
import os

client = OpenAI(api_key=os.getenv("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com")

def get_response(messages, **kwargs):
 response = client.chat.completions.create(
 model="deepseek-v4-flash",
 messages=messages,
 stream=True,
 reasoning_effort="low",
 extra_body={"thinking": {"type": "enabled"}},
 max_tokens=kwargs.get("max_tokens", 500),
 )
 reasoning_content, content = "", ""
 for chunk in response:
 delta = chunk.choices[0].delta
 if delta.reasoning_content:
 reasoning_content += delta.reasoning_content
 if delta.content:
 content += delta.content
 if content:
 messages.append({"role": "assistant", "content": content})
 else:
 content = reasoning_content
 return content
def tot_prompt(system_prompt,question,n=3):
 u=(f"请针对以下问题，提供{n}个不同的解决方案，"
 f"然后逐步分析每个解决方案的优缺点，最后给出最优方案。"
 f"最后选出最佳方案并说明理由。\n\n问题：{question}")
 return [
 {"role": "system", "content": system_prompt},
 {"role": "user", "content": u}
 ]
while True:
 user_input = input("User: ")
 if user_input.lower() in ["exit", "quit"]:
 break
 msgs = tot_prompt("你是资深的Agent架构师，擅长多种角度对比方案", user_input)
 response = get_response(msgs, max_tokens=1000)
 print("Agent导师:", response)

多轮循环调用

 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


from openai import OpenAI
import os

client = OpenAI(api_key=os.getenv("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com")

def get_response(messages, **kwargs):
 response = client.chat.completions.create(
 model="deepseek-v4-flash",
 messages=messages,
 stream=True,
 reasoning_effort="low",
 extra_body={"thinking": {"type": "enabled"}},
 max_tokens=kwargs.get("max_tokens", 500),
 )
 reasoning_content, content = "", ""
 for chunk in response:
 delta = chunk.choices[0].delta
 if delta.reasoning_content:
 reasoning_content += delta.reasoning_content
 if delta.content:
 content += delta.content
 if content:
 messages.append({"role": "assistant", "content": content})
 else:
 content = reasoning_content
 return content
def ask(quextion,system_prompt="你是擅长多种角度对比方案的资深Agent架构师",max_tokens=500):
 msgs=[
 {"role": "system", "content": system_prompt},
 {"role": "user", "content": quextion}
 ]
 response = get_response(msgs, max_tokens=max_tokens)
 return response
def tot_solve(question,n=3):
 schemes=ask(
 f"请针对以下问题给出{n}种不同解决思路，编号列出：\n{question}\n",
 system_prompt="你是擅长发散思维的规划专家",
 max_tokens=600,
 )
 scores = ask(
 f"请对以下 {n} 个方案逐一打分(1-10分),并各用一句话说明理由:\n{schemes}",
 system_prompt="你是严格的评审专家,打分要客观",
 max_tokens=500,
 )
 best = ask(
 f"综合以下评分,选出最优方案,并给出具体实施步骤:\n{scores}",
 system_prompt="你是决策专家,直接给最终选择",
 max_tokens=600,
 )
 return schemes, scores, best
while True:
 user_input = input("User: ")
 if user_input.lower() in ["exit", "quit"]:
 break
 s1, s2, s3 = tot_solve(user_input)
 #response = get_response(msgs, max_tokens=1000)
 print("方案:", s1)
 print("评审:", s2)
 print("决策:", s3)

ToT 输出量大、最容易触 token 上限；判断信号是"结尾突兀/结构缺块/数量不足"；对策是给足 token、拆多轮循环、约束格式。你这次结果结构完整、没有截断

***手动粘贴提示词是单次、人工、不可复用的；代码路由的价值有三层：一是自动化，系统自己判断并调用，不用每次人工选；二是执行动作，路由选中的不只是提示词，而是一整套执行流程——比如 ReAct 模式会启动’调 API→执行工具→结果回填’的循环，ToT 是三次调用的编排，这是手动粘贴做不到的；三是可观测可优化，能打日志、能批量测试、能调策略。所以单次聊天靠 LLM 自动发挥就够了，但做 Agent 系统必须用代码路由 ***

 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
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113


#第一阶段完工
from openai import OpenAI
import os

client = OpenAI(api_key=os.getenv("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com")

def get_response(messages,**kwargs):
 response = client.chat.completions.create(
 model=kwargs.get("model","deepseek-v4-flash"),
 messages=messages,
 stream=True,
 reasoning_effort=kwargs.get("reasoning_effort","low"),
 extra_body={"thinking": {"type": "enabled"}},
 max_tokens=kwargs.get("max_tokens", 500),
 )
 reasoning_content, content = "", ""
 for chunk in response:
 delta = chunk.choices[0].delta
 if delta.reasoning_content:
 reasoning_content += delta.reasoning_content
 if delta.content:
 content += delta.content
 if content:
 messages.append({"role": "assistant", "content": content})
 else:
 content = reasoning_content
 return content

def ask(quextion,system_prompt="你是擅长多种角度对比方案的资深决策专家",max_tokens=500):
 msgs=[
 {"role": "system", "content": system_prompt},
 {"role": "user", "content": quextion}
 ]
 response = get_response(msgs, max_tokens=max_tokens)
 return response

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

def cot_prompt(question,system_prompt="你是一个逻辑缜密，思维严谨的推理助手"):
 u=f"请一步步思考，再给出答案。\n问题:{question}"
 return [{"role": "system", "content": system_prompt}, {"role": "user", "content": u}]

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

def react_prompt(question,system_prompt="你是以为多种能小助手",tools="搜索引擎、计算器"):
 u=(f"可用工具:{tools}。严格按格式回答：\n"
 f"Thought:先根据用户问题想清楚要干什么\n"
 f"Action:调用哪个工具更适合该问题\n"
 f"Action Input:参数\n"
 f"Observation:工具返回结果\n"
 f"Answer:最终答案\n\n问题:{question}" 
 )
 return [{"role": "system", "content": system_prompt}, {"role": "user", "content": u}]

BUILDERS = {"cot": cot_prompt, "few_shot": few_shot_prompt, "react": react_prompt}


def auto_select(question):
 content=f"判断下面用户的问题适合哪种回答，输出格式：cot_prompt或few_shot_prompt或react_prompt或tot_solve)\n规则:注重结果中间思考过程的任务，逻辑推理，数学解题过程，公式推导输出cot_prompt,格式固定模板化输出的，文本提取特定词汇格式化输出的输出Few_shot_prompt,需要依赖其他工具的输出react_prompt,开放性问题，思维发散问题，思维风暴，多种选择多种路径实现，多选择对比找最优解决方案输出tot_solve\n问题:{question}"
 msgs = get_response([{"role": "user", "content": content}], max_tokens=50)
 print(f"[调试] 原始: {msgs!r}")
 text = msgs.lower()
 for mode in ["tot", "react", "few_shot", "cot"]: 
 if mode in text:
 return mode
 print("[警告] 未识别到模式名,兜底 cot")
 return "cot"

def run_mode(mode,question,**kw):
 if mode =="tot":
 schemes, scores, best = tot_solve(question, n=kw.get("n", 3))
 return f"【方案】\n{schemes}\n\n【评审】\n{scores}\n\n【决策】\n{best}"
 if mode not in BUILDERS:
 raise ValueError(f"未知模式:{mode},可选 {list(BUILDERS) + ['tot']}")
 msgs = BUILDERS[mode](question, **kw)
 return get_response(msgs, **kw) 
while True:
 user_input = input("User: ")
 if user_input.lower() in ["exit", "quit"]:
 break
 mode = auto_select(user_input) 
 print(f"[使用模式] {mode}")
 result = run_mode(mode, user_input) 
 print("Agent导师:", result) 

思维链

Sat, 08 Aug 2026 02:58:24 +0800

什么样的 prompt 算"过及格线"？

Prompt三个硬指标：

指标	白话版	怎么检验
角色任务清晰	模型知道"你是谁、要干什么	换个人看 prompt，也能说出它的用途
输入输出边界明确	输入什么、输出什么格式	说死了连续跑 3 次，格式稳定
可复用可测试	换参数能复用，不是一次性	同一个函数换 3 组参数都能跑

CoT 是什么

就是：别让模型"张口就答"，让它先把推理步骤写出来，再给结论。就像做数学题老师要求你"写出解题过程"，不许直接填答案。

解决什么问题：多步推理、数学逻辑题——模型直接答容易"跳步出错"，逼它写过程就能大幅提对

解决什么问题：格式固定、样本少的任务——比如"把消息分类成情绪/任务/闲聊"，规则说不清，但给 2~3 个例子它立刻就会

本质是一条指令（“请一步步思考”），放在System（当规则）或 User（当任务要求）都可以

Few-shot 是什么

在问题前面放几个「输入 → 输出」的例子，让模型照葫芦画瓢。

类比：新员工入职，先看老员工处理过的几单（输入→标准输出），再自己上手。给的是"范例"，不是"规则"。

解决什么问题：格式固定、样本少的任务——比如"把消息分类成情绪/任务/闲聊"，规则说不清，但给 2~3 个例子它立刻就会

多轮对话练习代码

 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 openai import OpenAI
import os
client =OpenAI(api_key=os.getenv("DEEPSEEK_API_KEY") ,base_url="https://api.deepseek.com")
def get_response(messages,**kwargs):
 response=client.chat.completions.create(model="deepseek-v4-flash",messages=messages,stream=True,reasoning_effort="low",extra_body={"thinking":{"type":"disabled"}},max_tokens=kwargs.get("max_tokens", 500),)
 reasoning_content=""
 content=""
 for chunk in response:
 delta=chunk.choices[0].delta
 if delta.reasoning_content:
 reasoning_content+=delta.reasoning_content
 if delta.content:
 content+=delta.content
 if content:
 messages.append({"role":"assistant","content":content})
 if not content:
 content = reasoning_content 
 return content
messages = [{"role": "system", "content": "你是一个耐心Agent老师，擅长用通俗的语言解释学生提到的问题。请根据问题一步步分析学生当前的学习阶段，给出最适合当前阶段的回答。"}]
while True:
 user_input = input("User: ")
 if user_input.lower() in ["exit", "quit"]:
 break
 messages.append({"role":"user","content":user_input})
 response = get_response(messages)
 print("Agent导师:", response)
if __name__ == "__main__": 
 pass

Recat

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


Thought: 我先想清楚要做什么
Action: 调哪个工具
Action Input: 传什么参数
Observation: 工具返回了什么
Answer: 最终答案

---------------------------------------------------------------------

f"可用工具:{tools}。请严格按格式回答:\n"
 f"Thought: 我先想清楚要做什么\n"
 f"Action: 调哪个工具\n"
 f"Action Input: 参数\n"
 f"Observation: (工具返回,此处先占位)\n"
 f"Answer: 最终答案\n\n问题:{question}")

ToT

单词调用

 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


from openai import OpenAI
import os

client = OpenAI(api_key=os.getenv("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com")

def get_response(messages, **kwargs):
 response = client.chat.completions.create(
 model="deepseek-v4-flash",
 messages=messages,
 stream=True,
 reasoning_effort="low",
 extra_body={"thinking": {"type": "enabled"}},
 max_tokens=kwargs.get("max_tokens", 500),
 )
 reasoning_content, content = "", ""
 for chunk in response:
 delta = chunk.choices[0].delta
 if delta.reasoning_content:
 reasoning_content += delta.reasoning_content
 if delta.content:
 content += delta.content
 if content:
 messages.append({"role": "assistant", "content": content})
 else:
 content = reasoning_content
 return content
def tot_prompt(system_prompt,question,n=3):
 u=(f"请针对以下问题，提供{n}个不同的解决方案，"
 f"然后逐步分析每个解决方案的优缺点，最后给出最优方案。"
 f"最后选出最佳方案并说明理由。\n\n问题：{question}")
 return [
 {"role": "system", "content": system_prompt},
 {"role": "user", "content": u}
 ]
while True:
 user_input = input("User: ")
 if user_input.lower() in ["exit", "quit"]:
 break
 msgs = tot_prompt("你是资深的Agent架构师，擅长多种角度对比方案", user_input)
 response = get_response(msgs, max_tokens=1000)
 print("Agent导师:", response)

多轮循环调用

 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


from openai import OpenAI
import os

client = OpenAI(api_key=os.getenv("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com")

def get_response(messages, **kwargs):
 response = client.chat.completions.create(
 model="deepseek-v4-flash",
 messages=messages,
 stream=True,
 reasoning_effort="low",
 extra_body={"thinking": {"type": "enabled"}},
 max_tokens=kwargs.get("max_tokens", 500),
 )
 reasoning_content, content = "", ""
 for chunk in response:
 delta = chunk.choices[0].delta
 if delta.reasoning_content:
 reasoning_content += delta.reasoning_content
 if delta.content:
 content += delta.content
 if content:
 messages.append({"role": "assistant", "content": content})
 else:
 content = reasoning_content
 return content
def ask(quextion,system_prompt="你是擅长多种角度对比方案的资深Agent架构师",max_tokens=500):
 msgs=[
 {"role": "system", "content": system_prompt},
 {"role": "user", "content": quextion}
 ]
 response = get_response(msgs, max_tokens=max_tokens)
 return response
def tot_solve(question,n=3):
 schemes=ask(
 f"请针对以下问题给出{n}种不同解决思路，编号列出：\n{question}\n",
 system_prompt="你是擅长发散思维的规划专家",
 max_tokens=600,
 )
 scores = ask(
 f"请对以下 {n} 个方案逐一打分(1-10分),并各用一句话说明理由:\n{schemes}",
 system_prompt="你是严格的评审专家,打分要客观",
 max_tokens=500,
 )
 best = ask(
 f"综合以下评分,选出最优方案,并给出具体实施步骤:\n{scores}",
 system_prompt="你是决策专家,直接给最终选择",
 max_tokens=600,
 )
 return schemes, scores, best
while True:
 user_input = input("User: ")
 if user_input.lower() in ["exit", "quit"]:
 break
 s1, s2, s3 = tot_solve(user_input)
 #response = get_response(msgs, max_tokens=1000)
 print("方案:", s1)
 print("评审:", s2)
 print("决策:", s3)

 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
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113


#第一阶段完工
from openai import OpenAI
import os

client = OpenAI(api_key=os.getenv("DEEPSEEK_API_KEY"), base_url="https://api.deepseek.com")

def get_response(messages,**kwargs):
 response = client.chat.completions.create(
 model=kwargs.get("model","deepseek-v4-flash"),
 messages=messages,
 stream=True,
 reasoning_effort=kwargs.get("reasoning_effort","low"),
 extra_body={"thinking": {"type": "enabled"}},
 max_tokens=kwargs.get("max_tokens", 500),
 )
 reasoning_content, content = "", ""
 for chunk in response:
 delta = chunk.choices[0].delta
 if delta.reasoning_content:
 reasoning_content += delta.reasoning_content
 if delta.content:
 content += delta.content
 if content:
 messages.append({"role": "assistant", "content": content})
 else:
 content = reasoning_content
 return content

def ask(quextion,system_prompt="你是擅长多种角度对比方案的资深决策专家",max_tokens=500):
 msgs=[
 {"role": "system", "content": system_prompt},
 {"role": "user", "content": quextion}
 ]
 response = get_response(msgs, max_tokens=max_tokens)
 return response

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

def cot_prompt(question,system_prompt="你是一个逻辑缜密，思维严谨的推理助手"):
 u=f"请一步步思考，再给出答案。\n问题:{question}"
 return [{"role": "system", "content": system_prompt}, {"role": "user", "content": u}]

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

def react_prompt(question,system_prompt="你是以为多种能小助手",tools="搜索引擎、计算器"):
 u=(f"可用工具:{tools}。严格按格式回答：\n"
 f"Thought:先根据用户问题想清楚要干什么\n"
 f"Action:调用哪个工具更适合该问题\n"
 f"Action Input:参数\n"
 f"Observation:工具返回结果\n"
 f"Answer:最终答案\n\n问题:{question}" 
 )
 return [{"role": "system", "content": system_prompt}, {"role": "user", "content": u}]

BUILDERS = {"cot": cot_prompt, "few_shot": few_shot_prompt, "react": react_prompt}


def auto_select(question):
 content=f"判断下面用户的问题适合哪种回答，输出格式：cot_prompt或few_shot_prompt或react_prompt或tot_solve)\n规则:注重结果中间思考过程的任务，逻辑推理，数学解题过程，公式推导输出cot_prompt,格式固定模板化输出的，文本提取特定词汇格式化输出的输出Few_shot_prompt,需要依赖其他工具的输出react_prompt,开放性问题，思维发散问题，思维风暴，多种选择多种路径实现，多选择对比找最优解决方案输出tot_solve\n问题:{question}"
 msgs = get_response([{"role": "user", "content": content}], max_tokens=50)
 print(f"[调试] 原始: {msgs!r}")
 text = msgs.lower()
 for mode in ["tot", "react", "few_shot", "cot"]: 
 if mode in text:
 return mode
 print("[警告] 未识别到模式名,兜底 cot")
 return "cot"

def run_mode(mode,question,**kw):
 if mode =="tot":
 schemes, scores, best = tot_solve(question, n=kw.get("n", 3))
 return f"【方案】\n{schemes}\n\n【评审】\n{scores}\n\n【决策】\n{best}"
 if mode not in BUILDERS:
 raise ValueError(f"未知模式:{mode},可选 {list(BUILDERS) + ['tot']}")
 msgs = BUILDERS[mode](question, **kw)
 return get_response(msgs, **kw) 
while True:
 user_input = input("User: ")
 if user_input.lower() in ["exit", "quit"]:
 break
 mode = auto_select(user_input) 
 print(f"[使用模式] {mode}")
 result = run_mode(mode, user_input) 
 print("Agent导师:", result) 

初识流式输出

Fri, 07 Aug 2026 23:42:45 +0800

流式接收代码结构

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


from openai import OpenAI
client =OpenAI(api_key="",base_url="https://api.deepseek.com")
message=[{"role":"user","content":"你是哪个大模型"}]
response=client.chat.completions.create(model="deepseek-v4-flash",messages=message,stream=True,reasoning_effort="low",extra_body={"thinking":{"type":"enabled"}},)
reasoning_content=""
content=""

for chunk in response:
 if chunk.choices[0].delta.reasoning_content:
 reasoning_content+=chunk.choices[0].delta.reasoning_content
 if chunk.choices[0].delta.content: 
 content +=chunk.choices[0].delta.content
print("Reasoning Content:", reasoning_content)
print("Content:", content)

Chunk 就是"模型把一句话拆成一截一截，一截一截往外吐"里的那一截。每次吐出来的那一小块，就叫一个 chunk

流式解析里的经典坑

流式返回里不是每个 chunk 都带文字——开头只有角色标记、收尾只有结束标志，delta.content 可能是 None。直接 += 会报 TypeError: can only concatenate str (not ‘NoneType’)。所以拼接前要先判空：if delta.content: 再累加。这是流式解析的标准写法

delta.content 有时是 None，直接拿它去 += 字符串就炸了。 stream=True 时，模型一截截吐 chunk，不是每个 chunk 都带文字,典型有 3 种"空 chunk"：

流刚开始只有 role=“assistant” 的角色标记，没有 content

思考阶段只有 reasoning_content（草稿纸），content 是空

流快结束收尾 chunk 只带 finish_reason，content 是 None

choices 为什么是数组？因为 OpenAI 系 SDK 支持一个请求同时生成多个候选答案（参数 n=2 就是让它给两份不同回答）。每个候选是列表里的一项。但你日常流式场景只有一个候选，所以永远取第 0 个 → choices[0]

剥到 choices[0] 之后，里面那个 delta 才是真正装着文字的地方。delta 的英文原意就是"增量"——它不是完整答案，而是这一截新长出来的那一小块。

delta.content 正式回答的文字增量

delta.reasoning_content 思考过程的文字增量

delta.role 角色标记（只在第一截出现）

messages 里三种角色各管什么

“system” 规则制定者（你设定的人设/规则）

“user” 用户说的话

“assistant” 模型之前说过的话

Git学习笔记

Fri, 03 Jul 2026 07:50:31 +0800

Git 命令完全指南：从入门到日常够用的所有指令

一、配置与初始化

`git config` —— 配置用户信息

1
2


git config --global user.name "你的名字"
git config --global user.email "you@example.com"

--global 对当前用户所有仓库生效；去掉该参数则只对当前仓库生效。第一次提交前必须配置，否则会报错。

`git init` —— 初始化仓库

1

git init

在当前目录创建 .git 子目录，把它变成一个 Git 仓库。

`git clone` —— 克隆远程仓库

1
2


git clone https://github.com/user/repo.git
git clone https://github.com/user/repo.git my-folder # 克隆到指定目录

把远程仓库完整下载到本地，并自动建立名为 origin 的远程关联。

二、日常提交四步曲

Git 的核心工作流是：修改文件 → 暂存 → 提交 → 推送（可选）。

`git status` —— 查看当前状态

1

git status

显示哪些文件被修改、哪些已暂存、哪些未跟踪。最常用的"我当前在哪"命令。

`git add` —— 暂存改动

1
2
3
4


git add file.py # 暂存单个文件
git add . # 暂存当前目录所有改动（新增/修改/删除，受 .gitignore 约束）
git add -A # 暂存整个工作树所有改动
git add -p # 交互式暂存，按代码块选择

add 只是把改动放进"暂存区"，还没有真正提交。

`git commit` —— 提交

1
2


git commit -m "feat: 新增登录功能"
git commit -am "fix: 修复空指针" # 自动暂存已跟踪文件的修改并提交

把暂存区的内容生成一个永久快照（commit）。

`git push` —— 推送到远程

1
2


git push origin main
git push -u origin main # 首次推送并关联上游，之后直接 git push

把本地提交上传到远程仓库。-u 会记下"上游分支"，以后 git push / git pull 无需再写参数。

三、查看状态与差异

`git diff` —— 查看差异

1
2
3


git diff # 工作区 vs 暂存区
git diff --staged # 暂存区 vs 最近一次提交
git diff main backup # 两个分支之间的差异

`git log` —— 查看提交历史

1
2
3
4


git log
git log --oneline # 一行一条，简洁
git log --oneline -5 # 最近 5 条
git log --graph --all # 图形化展示分支关系

`git show` —— 查看某次提交详情

1

git show <commit-id>

`git blame` —— 逐行追溯

1

git blame file.py

显示每行代码最后是谁、在哪个提交改的，排查"这段代码谁写的"神器。

四、分支管理

`git branch` —— 分支操作

1
2
3
4


git branch # 列出本地分支
git branch feature # 新建分支
git branch -d feature # 删除已合并的分支
git branch -D feature # 强制删除（未合并也删）

`git switch` / `git checkout` —— 切换分支

1
2
3


git switch main # 切到 main
git switch -c feature # 新建并切换到 feature
git checkout main # 老写法，等价 switch

switch 是 Git 2.23+ 推荐的新命令，语义比 checkout（身兼数职）更清晰。

`git merge` —— 合并分支

1
2


git switch main
git merge feature # 把 feature 合并进当前分支

可能产生冲突，需手动解决后再 git add + git commit。

`git rebase` —— 变基

1
2


git switch feature
git rebase main # 把 feature 的提交"挪到" main 最新提交之后

让提交历史变成一条直线，比 merge 更整洁。但不要对已经推送到远程的提交做 rebase，否则会��写共享历史，给协作者制造麻烦。

五、远程协作

`git remote` —— 管理远程仓库

1
2
3


git remote -v # 查看已关联的远程
git remote add backup <url> # 添加第二个远程
git remote remove backup # 删除远程

一个本地仓库可以连接多个远程（例如 origin 指向主仓库，backup 指向你的备份仓库）。

`git fetch` —— 拉取但不合并

1

git fetch origin

把远程更新下载到本地，但不动你的工作区。先 fetch 再查看，比直接 pull 更安全。

`git pull` —— 拉取并合并

1
2


git pull origin main
git pull --rebase origin main # 用 rebase 方式拉取，历史更干净

等于 git fetch + git merge。

六、暂存与恢复（stash）

`git stash` —— 临时存放改动

1
2
3
4


git stash # 把未提交的改动藏起来
git stash pop # 恢复最近一次储藏并删除
git stash list # 查看所有储藏
git stash apply # 恢复但不删除

适合"活干到一半，却要切分支去修紧急 bug"的场景。

七、撤销与回退

`git restore` —— 丢弃工作区改动（Git 2.23+）

1
2


git restore file.py # 撤销单个文件的工作区修改
git restore --staged file.py # 把文件从暂存区移出（取消 add）

`git reset` —— 重置

1
2
3


git reset --soft HEAD~1 # 回退到上一次提交，改动留在暂存区
git reset --mixed HEAD~1 # 回退，改动留在工作区（默认行为）
git reset --hard HEAD~1 # 彻底回退，丢弃所有改动（危险！）

--hard 会直接删除未提交的代码，慎用。

`git revert` —— 安全撤销（推荐用于已推送的提交）

1

git revert <commit-id>

生成一个"反向"的新提交来抵消某次提交，不改写历史，非常适合团队协作场景。

八、标签

`git tag` —— 打标签

1
2
3


git tag v1.0 # 轻量标签
git tag -a v1.0 -m "发布版本 1.0" # 附注标签
git push origin v1.0 # 推送标签到远程

常用于标记发布版本。

九、实用技巧

`.gitignore` —— 忽略文件

在项目根目录创建 .gitignore，写进去的文件不会进入版本控制：

1
2
3
4


.env # 密钥/环境变量，禁止提交
node_modules/
__pycache__/
*.log

避免把敏感信息（如 .env 里的数据库密码）或垃圾文件提交上去。

一个 remote 推多个仓库

1

git remote set-url --add --push origin https://github.com/你的/AgentLearn.git

之后 git push origin 会同时推送到配置的所有 push 地址，适合 GitHub + Gitee 双备份。

设置别名

1
2
3


git config --global alias.st status
git config --global alias.co checkout
git config --global alias.lg "log --oneline --graph"

之后用 git st 代替 git status，省时省力。

十、常见工作流示例

日常提交

1
2
3
4


git status
git add .
git commit -m "feat: xxx"
git push

Fork 协作

1
2
3
4
5


git clone https://github.com/你的/fork.git
git remote add upstream https://github.com/原作者/repo.git
git fetch upstream
git merge upstream/main
git push origin main

修 bug 临时切换

1
2
3
4
5
6


git stash
git switch -c hotfix
# 修复、提交……
git switch main
git merge hotfix
git stash pop

十一、回退到历史某个版本

代码上线后出问题、或误提交了错误内容时，需要让仓库回到某个旧提交。

方式一：reset 回退（本地、未推送时推荐）

1
2
3


git log --oneline # 找到目标 commit 的 id
git reset --hard <commit-id> # 工作区/暂存区/版本库全部回到该版本
git reset --hard HEAD~3 # 回退最近 3 个提交

⚠️ --hard 会丢弃目标版本之后的所有改动，仅在未推送且确定不要时用。

方式二：revert 回退（已推送到远程时推荐）

1
2


git revert <commit-id> # 生成一个反向提交，抵消该次改动
git revert HEAD~2..HEAD # 批量撤销最近 2 个提交

不改写历史，对团队协作安全，之后 git push 即可。

方式三：临时查看旧版本（不改动当前状态）

1
2


git checkout <commit-id> # 进入 detached HEAD 查看旧代码
git switch - # 看完切回原分支

回退后强制同步远程

本地 reset --hard 回退后若已推送过，需强推（会覆盖远程历史，谨慎）：

1

git push --force-with-lease origin main

优先用 --force-with-lease，比 --force 安全：远程有他人新提交时会拒绝，避免误覆盖别人的工作。

误删提交找回

1
2


git reflog # 查看 HEAD 移动记录，定位丢失的 commit id
git reset --hard <commit-id> # 恢复

十二、远程仓库连接与认证管理

修改远程仓库地址（改名 / 换平台 / 换账号）

1
2
3


git remote -v # 查看当前关联
git remote set-url origin https://github.com/新用户名/新仓库名.git
git remote -v # 确认已更新

GitHub 改了仓库名或用户名后 URL 随之变化，用 set-url 重新指向即可，本地提交历史全部保留，无需重新 clone。

远程仓库“名字变了”重新连接

仓库名变了本质是远程 URL 变了，处理方法同上：

1

git remote set-url origin <新地址>

想顺便改本地 remote 的简称（如 origin → github）：

1

git remote rename origin github

HTTPS 与 SSH 互转

1
2
3
4
5


# HTTPS → SSH
git remote set-url origin git@github.com:用户名/仓库名.git

# SSH → HTTPS
git remote set-url origin https://github.com/用户名/仓库名.git

HTTPS：每次 push 用个人访问令牌（PAT）或系统凭据管理器认证，最省心
SSH：用本机 SSH 密钥认证，配好后无需每次输密码，适合自动化/脚本

生成并配置 SSH 密钥

1
2
3
4


ssh-keygen -t ed25519 -C "you@example.com" # 生成密钥对，一路回车
cat ~/.ssh/id_ed25519.pub # 复制公钥内容
# 到 GitHub → Settings → SSH and GPG keys 粘贴添加
ssh -T git@github.com # 测试连接，看到成功提示即可

更换 / 更新 HTTPS 凭据（令牌）

Windows：控制面板 → 凭据管理器 → Windows 凭据 → 找到 git:https://github.com → 编辑或删除，下次 push 重新输入
命令行清除后重输：

1

git credential-manager reject https://github.com

验证当前连接方式

1
2


git remote -v # URL 是 https:// 还是 git@ 一目了然
ssh -T git@github.com # 单独验证 SSH 是否连通

十三、查看与修改 .gitignore 文件

.gitignore 决定哪些文件不进版本库。下面是如何查看它、修改它，以及处理"加了规则却没生效"的常见坑。

查看 .gitignore

1
2
3


cat .gitignore # 直接查看文件内容
code .gitignore # 用编辑器打开（VS Code）
git status --ignored # 查看当前被忽略的文件列表

检查某个文件是否被忽略、被哪条规则命中

1
2


git check-ignore -v node_modules # 显示匹配的规则及其所在行
git check-ignore .env # 有输出 = 被忽略；无输出 = 未被忽略

-v（verbose）会告诉你具体是哪一行规则、来自哪个 .gitignore 文件，调试"为什么这个文件没被忽略"时极有用。

修改 .gitignore

1
2
3
4


# 方式一：直接编辑文件（记事本 / VS Code / vim）
# 方式二：命令行追加一条规则
echo "*.log" >> .gitignore
echo ".env" >> .gitignore

常见规则写法：

1
2
3
4
5


.env # 忽略名为 .env 的文件
.env.* # 忽略 .env.local 等变体
*.log # 忽略所有 .log
node_modules/ # 忽略目录
/build # 忽略根目录下的 build

关键坑：文件已被跟踪，加了规则也不生效

如果某文件（如 .env）之前已经被 commit 进版本库，后来才加进 .gitignore，Git 仍会继续跟踪它。需要先从版本库移除跟踪（本地文件会保留）：

1
2


git rm --cached .env # 从版本库/暂存区移除，但保留本地文件
git commit -m "stop tracking .env"

之后 .gitignore 才会真正生效，该文件不再被提交推送。

强制添加被忽略的文件（临时）

1

git add -f important.log # -f 强制添加，即使被 .gitignore 忽略

全局忽略（对所有仓库生效）

1
2


git config --global core.excludesfile ~/.gitignore_global
# 之后编辑 ~/.gitignore_global 写入规则，对当前用户所有仓库生效

小结

Git 命令看着多，其实日常 80% 的场景只用 add / commit / push / pull / branch / merge 这几个。先把它们用熟，剩下的 rebase、stash、revert 等按需查即可。建议把本文收藏，遇到忘记的命令随时翻。

记住一条铁律：还没推送到远程的提交，可以用 reset --hard 删；已经推送出去的，请用 revert 安全撤销。

Markdown Syntax Guide

Thu, 07 Sep 2023 00:00:00 +0000

This article offers a sample of basic Markdown syntax that can be used in Hugo content files, also it shows whether basic HTML elements are decorated with CSS in a Hugo theme.

Headings

The following HTML <h1>—<h6> elements represent six levels of section headings. <h1> is the highest section level while <h6> is the lowest.

H1

H2

H3

H4

H5

H6

Paragraph

Xerum, quo qui aut unt expliquam qui dolut labo. Aque venitatiusda cum, voluptionse latur sitiae dolessi aut parist aut dollo enim qui voluptate ma dolestendit peritin re plis aut quas inctum laceat est volestemque commosa as cus endigna tectur, offic to cor sequas etum rerum idem sintibus eiur? Quianimin porecus evelectur, cum que nis nust voloribus ratem aut omnimi, sitatur? Quiatem. Nam, omnis sum am facea corem alique molestrunt et eos evelece arcillit ut aut eos eos nus, sin conecerem erum fuga. Ri oditatquam, ad quibus unda veliamenimin cusam et facea ipsamus es exerum sitate dolores editium rerore eost, temped molorro ratiae volorro te reribus dolorer sperchicium faceata tiustia prat.

Itatur? Quiatae cullecum rem ent aut odis in re eossequodi nonsequ idebis ne sapicia is sinveli squiatum, core et que aut hariosam ex eat.

Blockquotes

The blockquote element represents content that is quoted from another source, optionally with a citation which must be within a footer or cite element, and optionally with in-line changes such as annotations and abbreviations.

Blockquote without attribution

Tiam, ad mint andaepu dandae nostion secatur sequo quae. Note that you can use Markdown syntax within a blockquote.

Blockquote with attribution

Don’t communicate by sharing memory, share memory by communicating.
— Rob Pike¹

Tables

Tables aren’t part of the core Markdown spec, but Hugo supports supports them out-of-the-box.

Name	Age
Bob	27
Alice	23

Inline Markdown within tables

Italics	Bold	Code
italics	bold	`code`

A	B	C	D	E	F
Lorem ipsum dolor sit amet, consectetur adipiscing elit.	Phasellus ultricies, sapien non euismod aliquam, dui ligula tincidunt odio, at accumsan nulla sapien eget ex.	Proin eleifend dictum ipsum, non euismod ipsum pulvinar et. Vivamus sollicitudin, quam in pulvinar aliquam, metus elit pretium purus	Proin sit amet velit nec enim imperdiet vehicula.	Ut bibendum vestibulum quam, eu egestas turpis gravida nec	Sed scelerisque nec turpis vel viverra. Vivamus vitae pretium sapien

Code Blocks

Code block with backticks

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


<!doctype html>
<html lang="en">
<head>
 <meta charset="utf-8">
 <title>Example HTML5 Document</title>
</head>
<body>
 <p>Test</p>
</body>
</html>

Code block indented with four spaces

<!doctype html>
<html lang="en">
<head>
 <meta charset="utf-8">
 <title>Example HTML5 Document</title>
</head>
<body>
 <p>Test</p>
</body>
</html>

Diff code block

1
2
3
4
5


[dependencies.bevy]
git = "https://github.com/bevyengine/bevy"
rev = "11f52b8c72fc3a568e8bb4a4cd1f3eb025ac2e13"
- features = ["dynamic"]
+ features = ["jpeg", "dynamic"]

One line code block

1

<p>A paragraph</p>

List Types

Ordered List

First item
Second item
Third item

Unordered List

List item
Another item
And another item

Nested list

Fruit
- Apple
- Orange
- Banana
Dairy
- Milk
- Cheese

Other Elements — abbr, sub, sup, kbd, mark

GIF is a bitmap image format.

H₂O

Xⁿ + Yⁿ = Zⁿ

Press CTRL + ALT + Delete to end the session.

Most salamanders are nocturnal, and hunt for insects, worms, and other small creatures.

The above quote is excerpted from Rob Pike’s talk during Gopherfest, November 18, 2015. ↩︎

Image gallery

Sat, 26 Aug 2023 00:00:00 +0000

Hugo theme Stack supports the creation of interactive image galleries using Markdown. It’s powered by PhotoSwipe and its syntax was inspired by Typlog.

To use this feature, the image must be in the same directory as the Markdown file, as it uses Hugo’s page bundle feature to read the dimensions of the image. External images are not supported.

Syntax

1

![Image 1](1.jpg) ![Image 2](2.jpg)

Result

Photo by mymind and Luke Chesser on Unsplash

Shortcodes

Fri, 25 Aug 2023 00:00:00 +0000

For more details, check out the documentation.

Bilibili video

Tencent video

YouTube video

Generic video file

Your browser doesn't support HTML5 video. Here is a link to the video instead.

GitLab

Quote

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
― A famous person, The book they wrote

Photo by Codioful on Unsplash

Math Typesetting

Thu, 24 Aug 2023 00:00:00 +0000

Stack has built-in support for math typesetting using KaTeX.

It’s not enabled by default side-wide, but you can enable it for individual posts by adding math: true to the front matter. Or you can enable it side-wide by adding math = true to the params.article section in config.toml.

Inline math

This is an inline mathematical expression: $\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…$

1

$\varphi = \dfrac{1+\sqrt5}{2}= 1.6180339887…$

Block math

$$ \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } $$

1
2
3


$$
 \varphi = 1+\frac{1} {1+\frac{1} {1+\frac{1} {1+\cdots} } } 
$$

$$ f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi $$

1
2
3


$$
 f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
$$

男娘教主

HUGO搭建笔记

HUGO搭建笔记

通过Git推送到GitHub

LangChain

LangChain

目录

一、LangChain 是什么（架构总览）

一句话定位

全景架构图

包结构 —— 别一股脑 pip install langchain 就完事

裸调 vs LangChain 对照（先理解痛点）

二、安装与环境

pip install —— 装依赖

.env + load_dotenv —— 密钥分离

三、Model 模型：ChatModel

ChatOpenAI —— 统一接口调任意兼容模型

invoke / stream / batch —— 三种调用方式

四、Prompt 提示词模板：ChatPromptTemplate

ChatPromptTemplate.from_messages —— 构造消息模板

MessagesPlaceholder —— 历史消息占位

partial —— 预填部分变量

五、OutputParser 输出解析器

StrOutputParser —— 把 AIMessage 变成纯字符串

JsonOutputParser —— 解析 JSON 输出

PydanticOutputParser —— 强类型结构化（进阶）

六、LCEL 链：Runnable 与管道

chain = prompt | model | parser —— 一条最小链

get_graph().print_ascii() —— 可视化整条链

Runnable 协议 —— 为什么能 |

七、Runnable 组合件

RunnableParallel —— 一条输入，并行出多个结果

RunnablePassthrough.assign —— 保留原输入，再追加新字段

RunnableLambda —— 任意 Python 函数入链（适配器）

RunnableBranch —— 条件分支（按判断走不同子链）

八、Memory 记忆

三种记忆模式

用 RunnableLambda 接入自研 MemoryManager（重点）

九、Retriever 检索与 RAG

RAG 流程：文档 → 切分 → 向量化 → 存入 → 检索 → 拼进 prompt

接进链（检索增强问答）

十、Tool 工具与 @tool

@tool —— 把函数变成模型可调用的工具

bind_tools + 工具调用循环

十一、Agent 智能体

本质：模型决定调哪个工具 → 执行 → 结果喂回 → 再决定

十二、Callbacks 回调

监听链路每一步事件（调试 / 日志 / 计费）

十三、LangGraph 状态图（进阶）

StateGraph —— 把流程编排成"有状态 + 可有环"的图

十四、常用技巧与踩坑

技巧 1：流式 + 解析器组合

技巧 2：batch 并发提速

技巧 3：降级保护

踩坑 1：相对导入直接跑脚本会炸 ⚠️

踩坑 2：版本弃用 ⚠️

踩坑 3：parser 输出类型 ⚠️

踩坑 4：流式不能用普通函数截断 ⚠️

十五、小结

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()

包结构 —— 别一股脑 `pip install langchain` 就完事

`pip install` —— 装依赖

`.env` + `load_dotenv` —— 密钥分离

`ChatOpenAI` —— 统一接口调任意兼容模型

`invoke` / `stream` / `batch` —— 三种调用方式

`ChatPromptTemplate.from_messages` —— 构造消息模板

`MessagesPlaceholder` —— 历史消息占位

`partial` —— 预填部分变量

`StrOutputParser` —— 把 AIMessage 变成纯字符串

`JsonOutputParser` —— 解析 JSON 输出

`PydanticOutputParser` —— 强类型结构化（进阶）

`chain = prompt | model | parser` —— 一条最小链

`get_graph().print_ascii()` —— 可视化整条链

Runnable 协议 —— 为什么能 `|`

`RunnableParallel` —— 一条输入，并行出多个结果

`RunnablePassthrough.assign` —— 保留原输入，再追加新字段

`RunnableLambda` —— 任意 Python 函数入链（适配器）

`RunnableBranch` —— 条件分支（按判断走不同子链）

用 `RunnableLambda` 接入自研 `MemoryManager`（重点）

`@tool` —— 把函数变成模型可调用的工具

`bind_tools` + 工具调用循环

`StateGraph` —— 把流程编排成"有状态 + 可有环"的图

二、`_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`：把四层粘起来