零代码文档驱动大模型开发---AI办公助手系列-bug修复-单看都对 一连就错

一、项目概要

上一篇讲验收测试时揪出来的那批 bug。它们有个共同之处：每一段代码单独看，都写得没毛病；是几件事碰在一起，才出的事。这一篇挑四个最典型的，拆开看就会发现，代码里最阴的坑，不是"写错了"，而是"各自都没错，碰一起就乱了"。修 bug 不难，难的是看懂这些 bug 为什么会出现。理解了它们的共性，下次写代码时才能从一开始就绕开。最值钱的不是"修好了"，是"搞明白它们为什么是这种 bug"。

二、bug定位

• 引用跳转修复：知识库问答里的引用，点击跳转不再串位。

• 删除联动修复：删文档、清回收站时，知识库里的记录跟着一起清，不留"幽灵"。

• 模型加载修复：embedding 模型加载失败后，能重试，不用重启整个软件。

• 定位修复：点引用跳到 PDF，目标加载失败时不再"污染"之后打开的其他 PDF。

三、bug修复思路分享

bug1：引用为什么会"串味"？

情况：知识库回答里的[1]、[2]是引用标记，点一下跳到原文档。实现的时候，图省事用了一个全局变量，只存"最近一次回答"的引用。结果连问两个问题后，翻回第一个回答点 [1]——跳到的是第二个回答的引用。因为所有历史消息的 [1]，都在用那个"最近一次"的全局变量去解析。

思路：全局变量是偷懒的便利，也是"串味"的根源。一个全局状态只记"最新的那个"，一旦有多条历史记录要用它，就必然串台。数据该跟着"谁产生的"走，而不是堆在一个"最新"的筐里。

bug2：定位指令为什么会"残留"？

情况：点引用跳到某个 PDF 的第 3 页，本质是发出一条"跳到第 3 页"的指令。但如果这个 PDF 加载失败（文件损坏），这条指令既没被执行、也没被清掉，就晾在那。之后用户打开另一个正常的 PDF，这个编辑器一看"有条跳页指令"，直接照做——结果在无关的文档里，莫名其妙滚到了第 3 页。

解法：加载失败时，主动把这条没被消费的指令清掉，不让它"串"到下一个文档。

思路：一次性指令，失败时也得清掉。一条指令如果没成功执行，它不会自动消失，只会变成一颗"延时炸弹"，炸在下一个不知情的操作上。

bug3：模型加载失败，为什么会"永久卡死"？

情况：本地 embedding 模型用了单例模式——第一次用的时候加载，之后复用。加载的动作是一个 Promise，加载失败后，这个 Promise 就一直是"失败"状态。但代码只判断了"有没有在加载"，没判断"加载是不是已经失败了"。于是后续所有调用，都傻乎乎地去等一个早就失败了的 Promise，永远起不来，直到重启软件。

解法：加载失败时，把这个"正在加载"的状态清空，让下次调用能重新发起加载。

思路：缓存"失败状态"，比"没有缓存"更糟。单例的初衷是复用"成功的结果"，但如果把"失败"也一起缓存了，就等于把一次失败，放大成永久失败。

bug4：删了文档，知识库为什么会留"幽灵"？

情况：文档存在一张表，知识库里的索引存在另一张表，两张表之间没有任何关联约束。用户删了一个文档，文档表里没了，但知识库表里还躺着它的记录。结果检索时，这条"幽灵记录"还会被搜出来，点引用跳转，跳到的是一个已经不存在的文档。

思路：删除一个东西，要顺着"谁还引用着它"把关联清干净。数据库里最脏的，就是"表面删了、其实还赖着"的孤儿数据。删的动作，从来不只是删那一行，而是删掉它跟整个世界的关系。