- 十个问题不是十个坑,是三套错法重复出现
- 最值钱的一条:规则写对了但排在第 8 条,等于没写
- Zotero 开着就锁数据库,这一条卡了最久
- 每一类都配了一条能直接抄走的判断规则
上一篇写的是「搭起来的工具修不完,所以卸掉」。这一篇反过来:有一个工具我一直在修,而且修得动。
它是个论文阅读助手,自己写的 Flask 应用,跑在 localhost:8889。丢一个 PDF 进去就能问它问题,回答里带页码引用,点页码能跳到原文那一页。
前后修了十个问题。修完回头看,这十个问题如果列成清单,那只是一张 bug 列表;但按错在哪归类,它们只剩三类,而且每一类都有固定的判断动作。
下面按这三类讲,每类挑最值得说的展开。代码都是能直接抄走的。
第一类:看错了地方
这一类的共同点是症状和原因之间隔了一层。你盯着症状看,怎么修都修不对,因为它根本不是原因。
Token 全是 0,但它确实被消耗了
现象:所有对话的 token 统计都是 0。但模型明明在正常工作,回答长度也对。
第一反应是去查统计逻辑——是不是累加写错了?是不是没落库?查了半天都是对的。
真正的原因在更前面一层:调用网关的那个函数,根本没把用量信息带回来。
# 错误写法:只返回内容,用量的字段当没看见
def call_llm(messages):
resp = requests.post(GATEWAY, json={"messages": messages})
return resp.json()["choices"][0]["message"]["content"]
# 上游返回的其实是这样,usage 就在同一层,只是被丢了
# {"choices": [{"message": {"content": "..."}}], "usage": {"prompt_tokens": 812, ...}}上游的响应体里 usage 就在 choices 旁边,函数只取了自己要的那个字段,剩下的全丢了。下游统计逻辑再完美,也拿不到不存在的数据。
# 正确写法:返回一个二元组,把用量一起递出去
def call_llm(messages):
resp = requests.post(GATEWAY, json={"messages": messages})
data = resp.json()
content = data["choices"][0]["message"]["content"]
usage = data.get("usage") or {}
return content, usage数据全是 0 的时候,先怀疑数据没传过来
统计显示 0、列表显示空、数量对不上——先往上游回退一层,确认那个值到底有没有被产生出来,而不是去查消费它的那段代码。因为「没有数据」和「数据是 0」在展示层长得一模一样。
这个 bug 修完,立刻暴露了第二个——切换论文时 Token 数不变。这个是前端的事,所有论文共用了一个 localStorage 的 key,把每篇论文的用量混在一起了。改成按论文名拼 key 就完事:
// 错误写法:整个应用共用一个 key
localStorage.setItem("chat_tokens", JSON.stringify(tokens))
// 正确写法:按论文区分,各存各的
localStorage.setItem(`chat_tokens_${paperKey}`, JSON.stringify(tokens))有意思的是这两条是串联的:第一个不修,第二个根本看不见——数字全是 0,你当然不会注意到切论文的时候它没变。
十三篇论文全都在「未分类」里
现象:侧栏分类导航只有一项「未分类」,十三篇论文全挤在里面。
我先去看数据库查询。写了个只读连接:
con = sqlite3.connect("file:zotero.sqlite?mode=ro", uri=True)
rows = con.execute("SELECT ...").fetchall()
print(len(rows)) # 0一行都没有。但 Zotero 界面里分类明明是有的。
原因:**Zotero 正开着的时候,它一直握着数据库的写锁。**只读连接也得先拿到共享锁,一样会被挡住。SQLite 在这种情况下不会报错,它只是让你读到空——这比报错更难查。
真正解决它的是 immutable=1,一行参数:
# 加 immutable=1:告诉 SQLite「我读的这段时间里这个文件不会变」
con = sqlite3.connect(f"file:{path}?mode=ro&immutable=1", uri=True)| 试过的方案 | 结果 |
|---|---|
connect(path, timeout=10) | 等十秒,Zotero 不放手就照样失败 |
?mode=ro + uri=True | 读锁也被挡,读到空 |
?mode=ro&immutable=1 | 绕过全部锁,Zotero 开着也能读 |
immutable=1 的语义是「我保证这个文件在读取期间不会变化」。SQLite 信了这句话,于是跳过所有锁机制,直接读磁盘。
这是明知有风险还选的方案
如果 Zotero 在读取的瞬间写了新数据,可能读到半新半旧的内容。但这里读的是论文标题和分类——这种数据不是账本,读差一点没有后果。
反过来说,如果读的是金额、库存、状态机,这个参数绝对不能加。**同一行代码,在读缓存场景是最优解,在读账本场景是数据事故。**判断的依据不是代码,是你读的是什么数据。
接口报错,但返回的是一整页 HTML
前端报的是 Unexpected token '<'——解析 JSON 的时候遇到了 <。
浏览器收到的响应第一行是:
<!DOCTYPE html>
<html><head>...这个 < 就是 Flask 的默认错误页。后端抛了没被接住的异常,Flask 就返回一个 HTML 格式的 500 页面,而前端按 JSON 解析,于是报「意外的 <」。
顺着这条线索查后端日志,找到真正的原因:/api/chat 这个函数里用到了一个变量 zotero_key,但这个函数里从来没定义过它——是从另一个函数里复制代码时漏带了。补上调用就完事:
# 在 chat 路由里补上这一行
zotero_key = get_zotero_item_key(paper_id)< 出现在 JSON 解析报错里,就是后端出错页
Unexpected token '<'、Unexpected token <,或者任何「期望 JSON 但收到 HTML」的报错——问题不在前端,在后端挂了。因为 HTML 永远不会是接口的正常返回格式。
正确动作是去看后端日志里那个 500 的堆栈,别在前端找。
第二类:代码写对了,但放错了地方
这一类的代码,你逐行读都没毛病。错的不是内容,是位置、顺序、或者作用范围。所以我把它单列一类——修这类问题,翻代码是没用的,得去看「谁先执行」和「改的是哪一个」。
最值钱的一条:规则写对了,但排在第 8 条
这是三个类里我认为最值得单独记住的一个。
需求是让回答里带页码引用,格式 【第3页】。规则我写了,而且写得很清楚。但 LLM 就是不执行——一问它「总结一下」,出来的回答干干净净,一个页码都没有。
查了 prompt 才发现:那份系统提示词里塞了整篇论文的正文,总共四万五千字左右,而我的引用规则排在第 8 条——最后一条。
改了三版才对:
| 版本 | 做法 | 结果 |
|---|---|---|
| V1 | 在末尾加一条「引用页面编号」的规则 | 无效,一条引用都没有 |
| V2 | 挪到第 1 条,加上正反示例 | 部分生效,「研究方法」这个问题有 3 处引用,「总结」还是 0 |
| V3 | 第 1 条 + 「绝对必须」+ 在输出模板里嵌 【第3页】 | 所有问题稳定 3 处以上 |
V3 相比 V2 多做的两件事,每一件都有原因:
第一件事:把「必须」升级成「绝对必须,否则视为不合格」
—— LLM 需要知道「什么样算错」,光说「要怎样」约束力不够
第二件事:在输出示范里直接写上一个【第3页】
—— LLM 会模仿示范的格式,嵌进去的示例比规则描述管用得多长 prompt 里,位置决定权重
四万五千字的上下文,排在第 1 条的规则被执行的概率,远远高于第 8 条。这就是所谓的 Lost in the Middle:模型对开头和结尾敏感,中间那段等于半失忆。
推论有三条:
- 最重要的规则必须放第一条。
- 规则总数别超过三条左右。超过某个密度之后,多写的规则等于没写——它们会互相稀释。
- 给三个带正确格式的示例,好过写一百字的规则说明。
这一条我后来一直在用。写系统提示词的时候,先数一数自己塞了几条规则,超过三条就开始往前提。
高亮显示不出来:执行顺序错了
功能是回答里的关键词要标黄。代码写了,正则也写了,就是不亮。
因为你先把它渲染成 HTML 了:
// 错误写法:先渲染,再对渲染结果做高亮
const html = marked.parse(answerText); // "总结" → "<p>总结</p>"
el.innerHTML = highlight(html); // 正则去匹配 HTML 标签,全落空
// 正确写法:先在纯文本上高亮,再展示
const safe = escapeHtml(answerText); // 先把 < > 转义掉
const marked = highlight(safe); // 在纯文本上做正则匹配
el.innerHTML = marked; // 直接插入顺序反了,两步各自都对也没用——第一步的输出已经不是第二步期待的输入了。
顺带一个中英文的坑:中文没有空格分词,正则得分开写。
// 中文:匹配连续汉字,至少两个字
const cn = text.match(/[\u4e00-\u9fa5]{2,}/g);
// 英文:匹配连续字母,至少三个字符
const en = text.match(/[a-zA-Z]{3,}/g);总结 是两个字,论文 也是两个字——中文最少要取两个字才有意义,取一个字匹配到的全是「的」「是」「在」这种。
分类少了两个:循环里变量互相覆盖
现象很怪:Zotero 里明明有五个分类,程序只能认出来三个,丢的是字母靠后的那两个。
错在循环里那个逗号:
# 错误写法:每一轮都把上一次的结果覆盖掉
pairs = []
for row in cursor:
pairs = [(row[0], row[1])] # 注意这里的方括号,每轮都重建一个新列表
# 结果 pairs 里只剩最后一轮的那一个元素
# 正确写法:一次性取全部
pairs = cursor.fetchall()这一行的问题特别有代表性:它在语法上完全合法,在小数据量下甚至看起来"能用"(只有一条数据的时候结果是对的)。错的是它每次循环都把前面攒下的东西扔掉。
= 和 += 的区别,在循环里会放大
循环里出现 x = [...] 这种重建赋值,基本可以断定是错的——循环的意义就是累积,重建等于每轮从零开始。
这类问题还有个变体:list.append() 忘了调用(写成 list.append),以及字典更新时用了新字典赋值。都是同一个错法的不同长相。
第三类:环境在骗你
这一类的代码完全没问题。是另一个程序的状态,或者它天生就不支持你要干的事。
这类问题的特点是:你怎么改自己的代码都没用,因为它根本不在你的代码里。
退出程序了,端口还占着
改完代码重启服务,发现端口还占着。杀进程,再启,还是占着。
排查过程是这样的:
# 看端口是谁占的
netstat -ano | grep :8889
# 拿到了 PID,杀掉它
taskkill /f /pid 12345 /t
# 再启,还是 EADDRINUSE问题的来源有两个,叠在一起:
**一是进程托管关系。**用 nohup ... & 后台启动的进程,是被 shell 托管着的。你杀掉 Python 进程,shell 那一层可能又把它拉起来。taskkill /t 杀的是进程树,但树外面的孙进程杀不到。
二是 Windows 的端口回收时机。netstat 里那条 LISTENING 记录,要等内核把 TCP 状态收完才会消失。刚 kill 完,列表里可能还挂着。
最后我写了个重启脚本,把这套动作固定下来:
# restart-clean.ps1 —— 先按端口精确杀,再验证端口真的空了,最后才启动
$conns = netstat -ano | Select-String ":8889 "
foreach ($c in $conns) {
$procId = ($c -split '\s+')[-1]
if ($procId -match '^\d+$') {
taskkill /F /PID $procId /T 2>$null
}
}
Start-Sleep -Seconds 2
# 验证:端口必须真的没人听了才往下走
$still = netstat -ano | Select-String ":8889 "
if ($still) { Write-Host "端口仍被占用,先别启动"; exit 1 }
python app.py别用 taskkill /f /im python.exe
那个命令会杀这台机器上所有 Python 进程——包括你开着的数据处理、别的服务、正在跑的脚本。为重启一个服务,把无关的东西全干掉,这个代价和收益完全不成比例。
正确做法是按端口定位 PID 再杀。当然,更快的办法是——直接换个端口。调试阶段换端口比跟僵尸进程斗快十倍,改一次配置的事。
跳转只到首页,不跳页
功能是点了 【第3页】 就跳回 Zotero 打开那篇论文、翻到第 3 页。链接长这样:
zotero://select/library/items/ABCD1234?page=3实际结果:Zotero 被拉起来了,论文也打开了,但停在第一页。
原因不复杂:**Zotero 注册的这个协议处理器,不认 ?page= 这个参数。**它会忽略掉不认识的参数,做它能做的部分——打开这篇论文。
这个没法修,因为它不在我的控制范围内。能做的只是给个兜底:
<!-- 主按钮:尝试带页码跳转(能跳的版本会跳) -->
<a href="zotero://select/library/items/ABCD1234?page=3">跳转到 Zotero</a>
<!-- 兜底按钮:明确只保证定位到论文,页码靠用户自己看 【第3页】这个标记 -->
<button onclick="navigator.clipboard.writeText('【第3页】')">
复制页码标记
</button>外部协议能做什么,取决于对面那版程序
zotero://、obsidian://、vscode:// 这类协议,参数支持是版本相关的、且没有任何统一规范。同一个链接在不同版本上行为可以完全不同,而且它不会报错——只会静默忽略。
所以设计这类跳转时,永远要有一个「不依赖参数」的兜底路径。主路径负责体验,兜底路径负责「至少能用」。
三类的判断动作
| 看到的现象 | 先别急着做什么 | 该做的是 |
|---|---|---|
| 统计是 0 / 列表是空 | 别去查统计和渲染逻辑 | 往上游回退一层,确认那个值有没有被产生出来 |
| 报错内容是解析失败 / 格式不对 | 别在前端找 | 去看后端日志,多半是后端返回了错误页 |
| 逐行读代码都没问题 | 别继续读代码了 | 检查执行顺序:谁先执行、改的是哪一个 |
| 改了代码完全没效果 | 别以为是代码没生效 | 可能是别的程序的状态问题,问题不在你的代码里 |
| 外部协议 / 外部接口行为不符预期 | 别猜参数怎么写 | 它可能就是不支持,先设计一条兜底路径 |
事先的判断 vs 实际是什么
| 环节 | 我一开始的判断 | 实际是什么 |
|---|---|---|
| Token 显示 0 | 统计逻辑写错了 | 数据在上游就被丢掉了,消费端根本拿不到 |
| 分类全在「未分类」 | 查询语句有问题 | Zotero 握着锁,只读连接读到的是空 |
| 前端报解析错误 | 前端 JSON 处理有问题 | 后端抛异常返回了 HTML 错误页 |
| 引用规则不生效 | 规则写得不够清楚 | 规则清楚,但排在第 8 条被上下文稀释了 |
| 高亮代码没生效 | 正则写错了 | 正则没错,是执行顺序反了 |
| 分类少了两个 | 数据库里数据不全 | 数据全在,循环里被覆盖掉了 |
| 端口一直占用 | 进程没杀干净 | 进程托管关系 + 内核状态回收时机 |
| Zotero 跳转不跳页 | 链接参数写错了 | 那版协议处理器不支持这个参数 |
八个判断,只有最后一个是「猜错了参数」——其余七个,我一开始怀疑的地方都不是真正的原因。
三件事
**修不动的问题里,有相当一部分是因为看错了地方。**症状和原因之间隔一层的时候,你会把时间全花在修一个没坏的地方。「往回追一层」这个动作本身,比任何调试技巧都值得先形成习惯。
代码写对了但没生效,去查顺序和范围,别改内容。
on()是追加还是替换、高亮在渲染前还是后、循环里是累积还是重建——这三个问题的答案决定了结果,而这三行代码单看都是对的。**区分「我该修的问题」和「它就是这个样子」。**Zotero 锁数据库、协议不认参数、Windows 端口回收慢——这些不是 bug,是别人的程序按它的方式运行。对这类问题的正确动作是绕开和兜底,不是硬碰。
如果只想记三件事
- 数据全是 0 → 往上游追一层,确认值有没有被产生出来。
- 长 prompt 里最重要的规则放第一条,规则别超过三条。
- Zotero 开着要读它的库 →
?mode=ro&immutable=1。