WFGY：开源AI工作流诊断图谱，解决RAG幻觉与Agent逻辑混乱

1. 项目概述：一个为AI系统“看病”的开源图谱

如果你正在用RAG（检索增强生成）或者AI智能体（Agent）构建应用，大概率遇到过这样的场景：昨天还跑得好好的流程，今天突然就“胡言乱语”了；或者，你精心设计的Agent，在处理某些边界情况时，会给出完全不合逻辑、甚至自相矛盾的回答。你看着日志，面对着一堆模糊的错误信息，感觉就像在给一个黑箱系统做诊断，无从下手。

WFGY（Workflow Guidance Yard）这个开源项目，就是为解决这个痛点而生的。你可以把它理解为一个专为AI工作流打造的“故障诊断图谱”和“工程化治理引擎”。它不是一个具体的工具库，而是一套方法论、一套问题分类体系，以及一系列用于验证、调试和治理AI系统行为的实践工具集。简单说，当你的AI应用“生病”了，WFGY提供了一张详细的“病症地图”和一套“诊疗方案”，告诉你问题可能出在哪里，以及如何一步步修复。

这个项目特别适合三类人：一是正在被RAG幻觉、信息检索不准、Agent逻辑混乱等问题困扰的一线AI工程师；二是需要系统性评估和提升AI应用可靠性的技术负责人；三是对AI对齐（Alignment）、可解释性（Explainability）和稳健性（Robustness）有研究兴趣的开发者。它的核心价值在于，将AI系统开发中那些模糊、依赖经验的调试过程，变得结构化、可复现、可协作。

2. WFGY的核心架构与设计哲学

2.1 从1.0到5.0：一个不断演进的治理体系

WFGY不是一个静态的项目，它的版本迭代清晰地反映了其设计思路的演进。理解这个脉络，能帮你更好地使用它。

WFGY 1.0 & 2.0：概念与诊断内核这是项目的起点。1.0奠定了公共概念基础，提出了用“问题地图”来结构化认知AI故障的想法。2.0则强化了推理和诊断内核，开始系统化地定义“什么构成了一个AI工作流问题”。此时，项目更像一个研究框架，为后续的工程化实践打下了理论基础。

WFGY 3.0：前沿推理与验证层3.0是一个重要的转折点，它引入了“Tension Universe”（张力宇宙）的概念，专注于极端情况下的推理压力测试和基于纯文本（TXT）的调用界面。其标志性的“奇点演示”（Singularity Demo）TXT文件，本身就是一个可自验证的AI交互剧本。它要求AI系统能够读取该文件，并按照内置的指令进行SHA256校验和交互。这实际上是在测试和定义AI系统处理复杂、结构化指令的“服从性”和“精确性”，是治理逻辑的早期实践。

WFGY 4.0：治理引擎如果说3.0是“测试用例”，那么4.0就是“评分规则”和“执法机构”。4.0不再直接面向用户，而是作为底层引擎，负责治理路由纪律、评估压力、合法性边界以及高压下的推理行为。它包含了“双生图谱”（Twin Atlas）和“逆图谱”（Inverse Atlas）等核心组件。“双生图谱”可能指的是对同一问题，从正反两个角度（如“如何成功” vs “如何失败”）构建的对比分析框架，用于精细化评估。“逆图谱”则可能用于追溯错误根源。这一层确保了整个体系的严谨性和可重复性。

WFGY 5.0 Avatar：旗舰运行时这是目前面向公众的主要界面。Avatar（化身）的概念非常巧妙，它不是一个简单的聊天机器人预设。你可以把它看作一个“受治理的运行时环境”，用于构建、调优、复制和迁移“语言自我”。简单来说，它提供了一套协议和工具，让你能创建行为可预测、可分支、可复用的AI交互代理，并能将这个“代理”的“行为模式”在不同的会话、任务甚至模拟环境中携带和复用。这解决了AI应用开发中“状态管理”和“行为一致性”的难题。

2.2 核心组件：你的AI调试工具箱

WFGY提供了一套组合工具，你可以根据问题的紧急程度和复杂度选择入口。

问题图谱3.0：最直接的实践入口这是当你系统已经“挂了”时的首选急救包。它不是一个简单的列表，而是一个结构化的“故障树”。

• 16问题全局调试卡：这是精髓。它将常见的RAG/Agent故障归纳为16个核心问题域，例如：查询理解偏差、检索器失效（召回率/精准度问题）、上下文窗口污染、思维链断裂、指令遵循失败、自我一致性冲突等。这张“卡片”是一个诊断流程图，帮你快速定位问题大类。
• 图谱路由器TXT：一个可被AI直接读取和执行的文本文件。你把它喂给LLM（如ChatGPT、Claude），它就能引导LLM扮演一个“调试助手”，根据你的问题描述，在16问题地图中导航，提出诊断性问题并给出排查建议。这实现了“用AI调试AI”的自动化辅助。
• 全局修复地图：在定位问题后，这里提供了针对每个问题类别的具体修复策略、代码片段思路和配置调整建议。

公共证明层：建立信任的基石开源项目常被质疑是否“纸上谈兵”。WFGY特意设置了“公共证明”板块，展示采用者案例、外部认可证据和时间线。这对于一个解决“软性”工程问题的项目至关重要，它通过社会证明来验证其方法论的有效性。

协作与支持框架项目提供了清晰的协作路径，从试点项目（Pilot）的一页纸说明，到示例交付物，甚至支持方式。这表明项目团队希望其方法论能在真实商业场景中得到锤炼和扩展。

3. 实战：使用WFGY诊断一个RAG幻觉问题

让我们模拟一个真实场景。假设你构建了一个基于公司技术文档的问答机器人，用户反馈：“我问‘如何配置数据库连接池的最大线程数’，它给出的步骤里混入了隔壁Java项目的Spring Boot配置，完全不对。”

3.1 第一步：启动问题图谱3.0路由器

我们不走UI，直接使用最“极客”也最有效的方式：使用图谱路由器TXT。

1. 获取路由器文件：从WFGY仓库的./ProblemMap/Atlas/目录下找到troubleshooting-atlas-router-v1.txt。
2. 开启调试会话：将整个TXT文件内容粘贴到ChatGPT-4或Claude 3的对话窗口中。文件开头通常有明确的指令，如“你现在是WFGY问题图谱路由器，请遵循以下流程...”。
3. 描述问题：根据路由器的提示，清晰地描述问题：“我的RAG问答系统出现了严重幻觉。用户查询关于‘数据库连接池最大线程数配置’的具体步骤，系统返回的答案中包含了无关技术栈（Spring Boot）的配置项，而我们的文档是基于Python SQLAlchemy的。”

3.2 第二步：跟随路由器进行诊断

一个设计良好的路由器会引导你进行一系列问答。它可能会问你：

• “检索环节返回的源文档片段，是否确实包含了Spring Boot内容？”（验证检索污染）
• “你的文档中，关于SQLAlchemy和Spring Boot的连接池配置，是否存在于相邻的段落或页面？”（验证文档分块或上下文窗口问题）
• “系统提示词（Prompt）中是否明确限定了技术栈范围？”（验证指令遵循）

根据我们的假设，我们回答：1) 是的，检索结果里混入了Java项目的文档页；2) 两个技术的文档在知识库中确实存在，但属于不同产品线；3) 提示词有写“请基于Python技术栈回答”。

路由器此时很可能会将问题定位到“问题#5：检索器特异性不足/跨域污染”和“问题#12：指令遵循在复杂上下文中失效”。

实操心得：路由器TXT的有效性极度依赖于你对问题的描述精度。避免说“它回答错了”，而要像给医生陈述病情一样，提供“症状”（错误答案样例）、“环境”（你的技术栈）和“诱因”（什么样的查询容易触发）。这能极大提升诊断效率。

3.3 第三步：查阅全局修复地图

定位到问题编号后，我们打开Global Fix Map。

• 针对问题#5，修复地图可能建议：
  1. 优化元数据过滤：在检索时，除了语义相似度，必须增加严格的元数据过滤，例如technology_stack: Python。
  2. 重新评估分块策略：当前的分块可能将不同技术栈的配置说明切分到了同一个块中。建议按“产品线-技术栈”进行更粗粒度的分隔，或采用语义分块（如LangChain的SemanticChunker），确保块内主题一致。
  3. 引入重排序器：在初步检索后，使用一个轻量级的交叉编码器模型（如bge-reranker）对结果进行重排序，将最符合查询指令（如包含“Python”）的文档排到最前。
• 针对问题#12，修复地图可能建议：
  1. 强化系统提示词：采用“负面强化”方式。例如：“你是一个只精通Python技术栈的专家。你必须忽略并绝对不参考任何关于Java、Spring Boot、.NET等非Python技术栈的文档内容。如果检索到的材料中包含这些，视其为无效信息。”
  2. 结构化输出要求：在提示词中要求模型先进行“技术栈确认”步骤。例如：“在回答前，请先判断：该问题是否明确属于Python技术栈范畴？如果是，请继续；如果否或存疑，请回答‘该问题超出我的知识范围’。”
  3. 使用WFGY 4.0的评估纪律：可以设计一个评估用例集，专门测试这种“跨域指令遵循”能力，利用双生图谱来量化模型在有无强化指令下的表现差异，从而迭代优化提示词。

3.4 第四步：实施与验证

我们选择实施“元数据过滤”和“强化系统提示词”的组合方案。

1. 在文档入库（向量化）阶段，为每一段文本（chunk）打上清晰的技术栈标签。
2. 修改检索查询，在相似度搜索的基础上，增加过滤器：where metadata['tech_stack'] == 'Python'。
3. 重写系统提示词，采用上述的负面强化和结构化输出格式。
4. 构造一批包含混合技术栈关键词的测试查询，观察幻觉是否消失。

注意事项：元数据过滤是一把双刃剑。如果过滤条件太严格，可能会导致召回不全（例如，有些通用性知识可能没有明确标签）。最佳实践是采用“混合检索”策略：先进行宽松的语义检索，再对结果进行严格的元数据和后过滤（post-filtering），并在两者之间根据业务需求进行权衡（如设置最低分数阈值）。

4. 深入WFGY 4.0：利用双生图谱进行系统性评估

修复了具体问题后，如何防止类似问题再次发生？如何系统性地提升整个AI应用的稳健性？这就需要用到WFGY 4.0的治理能力，特别是“双生图谱”。

4.1 双生图谱是什么？

想象一下，你要评估一个AI助手回答“如何泡一杯好茶”的能力。传统的评估可能只准备一组“标准问题”和“标准答案”。而双生图谱会同时构建两个相互对照的图谱：

• 正图谱：包含所有通向“成功泡一杯好茶”的知识节点和推理路径。例如：水质选择、水温控制、茶叶用量、冲泡时间等。
• 逆图谱：包含所有导致“失败”的可能路径。例如：使用自来水、沸水烫坏茶叶、茶具未预热、浸泡过久导致苦涩等。

评估时，你不仅问“应该如何做”，还会故意注入来自逆图谱的干扰信息或错误前提，观察AI是否能识别并抵抗这些“错误路径”的诱导，坚守正图谱的逻辑。

4.2 用双生图谱设计一个评估案例

延续我们的数据库配置RAG场景。我们可以为“配置连接池”这个任务构建双生图谱。

正图谱节点示例：

• P1: 确认数据库驱动（如psycopg2,asyncpg）
• P2: 导入正确的连接池类（如from sqlalchemy.pool import QueuePool）
• P3: 设置pool_size(最大连接数)
• P4: 设置max_overflow(允许超出pool_size的连接数)
• P5: 设置pool_recycle(连接回收时间，防超时)

逆图谱节点示例：

• N1: 混淆不同ORM的连接池参数名（如把Hibernate的hibernate.connection.pool_size当成SQLAlchemy的）
• N2: 推荐不安全的无限连接池设置（pool_size=-1）
• N3: 忽略连接泄露的配置（未设置pool_pre_ping=True或超时）
• N4: 在异步环境中错误使用同步连接池

设计评估查询：

1. 正向测试：“用SQLAlchemy配置一个PostgreSQL数据库连接池，要求最大10连接，允许溢出5个。” 期望答案应涵盖P1-P5。
2. 逆向压力测试：“我在Spring Boot项目里用JPA，该怎么设置pool_size？另外，SQLAlchemy的max_overflow设为-1是不是表示无限？” 期望答案应：a) 澄清技术栈混淆（识别N1），b) 指出max_overflow=-1在SQLAlchemy中通常不建议或含义不同（识别N2），并给出安全建议。
3. 混合干扰测试：“看文档说设置pool_recycle=3600和pool_pre_ping=True都能防超时，是不是用一个就行了？” 期望答案应解释两者作用不同（pool_recycle是定期重置连接，pool_pre_ping是使用前检查），推荐同时使用，从而展示对N3的深入理解。

通过运行一批这样的正逆交织的测试用例，你可以量化你的RAG系统在“坚持正确知识”和“抵抗错误诱导”两方面的能力得分。WFGY 4.0的“AI Eval”模块很可能就提供了运行此类评估的框架或示例。

实操心得：构建高质量的双生图谱需要深厚的领域知识。最好的方式是“众包”：让开发团队、测试团队甚至资深用户共同贡献“正例”和“反例”。逆图谱中的节点往往比正图谱更有价值，它们直接对应着系统可能“翻车”的陷阱。

5. 常见问题与排查技巧实录

在实际使用WFGY方法论和工具的过程中，我总结了一些常见困惑和解决技巧。

5.1 关于WFGY 5.0 Avatar的常见疑问

Q1: Avatar和普通ChatGPT预设有什么区别？A1: 核心区别在于“状态管理”和“行为工程”。一个预设是静态的提示词，而Avatar是一个运行时。它允许你定义的行为（如严谨的验证步骤、特定的思考框架）可以像程序一样被“暂停”、“分支”（针对不同问题走不同子流程）、“序列化保存”并在新的会话中“加载恢复”。它更接近于一个可编程的、有记忆的AI交互协议。

Q2: 我是否需要从Avatar开始学习WFGY？A2: 不一定。如果你的当务之急是解决现有系统的故障，问题图谱3.0是最直接的起点。Avatar更适合当你需要构建一个全新的、需要高度复杂和稳定行为的AI交互应用时，作为底层协议来使用。你可以先通过问题图谱解决眼前的“火情”，再通过Avatar来设计更防火的“建筑结构”。

5.2 问题图谱3.0使用中的陷阱

问题：路由器TXT在有些LLM上响应不佳，不按流程走。

• 排查：首先检查是否使用了足够强大的模型（如GPT-4、Claude 3 Opus）。其次，查看TXT文件的开头指令是否清晰。有些模型对超长上下文中的指令遵循会衰减。
• 技巧：可以尝试将路由器TXT的核心指令部分（通常是前几百字）单独提取出来，先发送给AI，等它确认角色后，再发送完整的诊断流程内容。这类似于“分阶段激活”。

问题：按照全局修复地图调整后，问题有所改善但未根除。

• 排查：这往往意味着问题不是单一的，而是多个问题类别的叠加。例如，可能是“检索污染”（问题#5）和“上下文窗口内信息冲突”（问题#8）共同导致的。
• 技巧：使用问题图谱的“全局调试卡”进行二次诊断。像排查电路故障一样，采用“隔离法”。例如，你可以临时将检索范围缩小到绝对正确的单一文档，测试生成效果。如果幻觉消失，则问题主要在检索端；如果仍有问题，则重点检查提示词和LLM生成环节。WFGY的方法论鼓励这种系统性的“分而治之”。

5.3 WFGY 4.0评估实践中的难点

难点：设计逆图谱（错误路径）时，思维有盲区，想不到那么多“坏主意”。

• 技巧：
  1. 利用历史：复盘所有真实的用户投诉、bad case，将其抽象为错误模式。
  2. 对立思考：针对正图谱的每一步，故意问“如果不这样做会怎样？”“最常见的误解是什么？”
  3. 外部输入：让非技术背景的同事或用户尝试“问垮”你的系统，他们的提问角度往往出乎意料。
  4. 参考已知模式：WFGY的16问题地图本身就是一个极好的逆图谱灵感库，每个问题类别都对应着一大类错误模式。

难点：评估结果如何量化？如何设定及格线？

• 技巧：WFGY 4.0的“结果摘要”可能提供了一些思路。你可以定义简单的指标：
  • 指令遵循准确率：在包含干扰信息的测试中，模型给出完全符合正图谱答案的比例。
  • 幻觉抵抗率：模型在逆图谱诱导下，明确拒绝或纠正错误信息的比例。
  • 关键信息召回率：在正向测试中，必须涵盖的核心知识点（如P1-P5）被提及的比例。 及格线没有统一标准，需结合业务风险设定。例如，对于金融客服，幻觉抵抗率必须要求99.9%以上；对于内部知识库，可能95%即可。关键是建立基线，并通过迭代看到提升趋势。

5.4 关于项目协作与贡献

Q: 我想为WFGY贡献一个我遇到的独特问题案例，该怎么做？A: 项目仓库的TensionUniverse目录下通常有贡献指南。贡献一个高质量的案例，远比贡献代码更有价值。一个好的案例应包括：1) 清晰的背景描述；2) 触发问题的具体输入；3) 观察到的错误输出；4) 根本原因分析（使用WFGY的问题分类）；5) 验证有效的解决方案。这将成为滋养整个问题图谱的宝贵养料。

WFGY这套体系，初看可能觉得概念繁多，但它的核心精神非常务实：承认AI系统的复杂性，并用工程化的方法去管理这种复杂性。它不是提供一个银弹，而是给你一套手术刀和一张解剖图。当你不再把LLM的“胡言乱语”看作神秘现象，而是能将其归类到“检索污染”、“指令冲突”或“上下文过载”等具体工程问题时，你就已经掌握了构建可靠AI应用的最关键能力。从这个角度看，WFGY的价值，在于它正在帮助社区建立一套关于AI系统故障的“共同语言”和“诊断标准”。