为项目构建Agent知识库：定位生产故障的完整方法论

刚接手一个新项目，需要搭建支撑故障定位的Agent知识库时，很多人容易陷入一个误区：把能找到的架构文档、接口说明、历史复盘一股脑塞进去，做个索引就以为大功告成。这种做法确实解决了资料从哪里找的问题，但如果目标是让Agent能够定位生产故障，那还远远不够。Agent查到资料后，凭什么判断这次问题发生在哪里？比如删除接口返回HTTP 500，Agent据此判断删除失败，但检查数据后发现删除已经完成。服务端处理请求时出错，不代表之前执行的动作都没有生效。单纯凭状态码决定重试或回滚，都可能造成错误处理。

先确定知识库要支持的判断类型

搭建Agent知识库之前，必须先明确它要帮Agent做什么。在故障定位场景下，知识库的目标是定位生产问题，并为是否修改、修改哪里提供依据。这个目标决定了资料要整理到什么程度。判断一个行为有没有问题，需要一个预期作为参照——接口原本要完成什么、允许哪些中间状态、出现错误后保证到哪一步，这些都得先说清楚。否则，『当前状态是什么』只是一条记录，还不足以判断它是否异常。有了预期，还需要知道系统靠什么实现它。同一个结果可能经过多个服务和后台任务，用户看到的错误可能出现在后面的环节，原因却在前面。只列组件名称没法解释这种关系，需要把过程连起来，写清每一步的输入、结果以及失败后会发生什么。

不熟悉项目时从正常业务流程入手

有了上述结构，仍然不能凭空知道某个模块有哪些状态，也不能推导出线上使用了什么配置。第一性原理能帮助确定需要了解什么，但项目事实还得去查。可以从一条完整的业务流程开始，而不是试图一次读懂整个仓库。先用文档确定这条流程的目的和边界，再沿代码核对它实际经过的环节。调用顺序、状态变化和失败处理放在一起看，才能得到一份正常工作过程的说明。不熟悉的地方要留下问题，而不是猜一个解释让文章读起来完整。文档和实现对不上，就记录冲突；代码看不出设计原因，就找设计记录或请维护者确认。暂时没有答案，并不妨碍先整理已经核实的部分。逐条补充关键流程以后，系统的整体结构也会清楚起来：哪些过程共享同一项状态，哪些失败会传到其他环节，哪些结果可以重试，哪些动作一旦完成就不能简单撤销。

产业落地中的知识分类与验证机制

在实际落地过程中，我们总结出一条关键经验：知识要分开保存，才能按不同速度更新。领域知识记录在不同项目中也能使用的概念和机制，适用条件通常比较稳定，但应用到当前项目时仍需核对。项目设计与实现记录这个系统自己的组成、流程和约束，是定位当前项目问题必不可少的内容。接口文档保存精确契约，字段和错误语义需要跟版本一起维护。使用与运维资料保存操作方法、适用条件和回滚步骤。日期目录和草稿区用于留下分析过程，尚未确认的猜测可以保留，但不应和已经核实的结论混在一起。分类时看一条内容的用途、变化速度，以及由什么来源来确认它。每条重要结论都要保留依据、适用条件和待确认事项，整理者相信它，不足以让另一个Agent直接拿去使用。

建立专家底座实现知识复用

经过核验的知识仍然可能分散在很多文件里，Agent每次都从全库搜索容易先命中旧复盘或零散细节，而没有读到当前机制的完整说明。可以在这些资料前面放一份较短的入口文档，说明系统的关键过程、列出正常行为和重要约束、再指向详细资料与查证位置。这份优先读取的文档就是专家底座。专家知识指内容本身，专家底座指组织和提供这些内容的方式。底座不需要装下全部资料，但也不能只剩一张目录——Agent读完以后，至少应当理解当前问题所在模块正常时怎样工作。使用时，Agent先把现象放到对应流程中，知识库提供的是正常过程和已知约束，现场调查确认的是这一次发生了什么。两者不一致时需要继续取证，不能为了让事实符合文档而忽略差异。求证方法也要单独准备：哪些信息只是线索，怎样检查一个解释是否有反例，什么情况下仍不能动手修改，这些不属于某个模块的工作原理。

知识库是否真正有用，要看它在下一次问题中起了什么作用。每次排查结束后，记录Agent是从哪里开始走偏的，然后针对性补充。如果找错了模块，检查入口是否清楚；如果正常流程理解错了，核对相关文档；如果知道流程却得出没有证据的结论，检查求证要求。刚接手一个陌生项目时，不可能一次写出完整的专家知识，能够做到的是让每个判断有出处，让不知道的地方清楚可见。新问题来了可以沿着已有过程继续核对，处理完以后，下一位使用者少走一段相同的弯路。