用 Claude Code 的 LLM 应用开发插件搭建 LangGraph 与 RAG 原型

如果你想快速验证一个 LLM 应用架构，最容易走偏的方式是先堆功能：接入模型、导入文档、增加工具，再试图把这些部分拼起来。更稳妥的做法，是先让 Claude Code 的 LLM 应用开发插件协助搭出一条最小链路：由 LangGraph 管理 Agent 状态和流程，用混合检索召回资料，最后通过结构化输出约束回答格式，再逐段人工验收。

先明确插件应该解决什么问题

这类插件的价值，不是替开发者凭空生成一套“看起来完整”的 AI 项目，而是把自然语言需求转成更容易检查的工程任务，例如：

• 梳理项目目录和模块职责；




• 设计 LangGraph 的状态节点与转移关系；




• 生成检索、重排或回答节点的初始代码；




• 检查链路中的输入输出是否一致；




• 为节点补充测试样例和异常分支。

资料中提到的相关开发能力覆盖 LangChain、LangGraph、Agent、工具开发、RAG，以及从文档切分到检索的完整链路。使用时应把它当作“开发协作工具”，而不是最终验收者。

在开始之前，先写清楚原型的边界。比如，本次只验证以下流程：

用户问题 → 查询处理 → 混合检索 → 结果整理 → 结构化回答 → 人工检查

暂时不加入复杂的多 Agent 协作、生产环境权限、长时间任务、流式前端或完整部署方案。原型阶段的目标是确认架构是否成立，而不是一次性完成产品化。

由于当前资料没有给出该插件的具体安装命令、启动参数或版本信息，不应直接套用网上其他工具的命令。实际操作时，应按照插件自身的安装说明完成启用，然后让它先阅读项目目标和已有文件，再开始生成代码。

用 LangGraph 表达 Agent 状态图

LangGraph 的核心不是“多写几个节点”，而是把一次回答过程中会变化的信息集中放进状态对象，再由图中的节点逐步处理。

一个适合 RAG 原型的状态，可以抽象为：

state:
  question        用户原始问题
  rewritten_query 改写后的检索问题
  documents       检索到的文档片段
  answer          最终回答
  citations       回答依据
  status          当前处理状态
  errors          错误信息

这里不必一开始就追求复杂类型。重要的是先回答三个问题：

1. 每个节点读取哪些字段？




2. 每个节点会新增或修改哪些字段？




3. 如果检索为空、输出不合规或模型调用失败，流程往哪里走？

可以先让插件按照下面的职责设计图：

START
  ↓
查询预处理
  ↓
混合检索
  ↓
结果整理
  ↓
生成结构化回答
  ↓
输出校验 ── 不通过 ──> 修正或人工处理
  ↓
END

如果后续需要加入意图识别、工具调用或人工确认，可以在这个基础上增加分支，而不是重新拆掉整个流程。

节点职责要保持单一

查询预处理节点可以负责清理问题、补充必要上下文，或者生成适合检索的查询。它不应该同时生成最终答案，否则后续很难判断答案到底来自哪里。

混合检索节点负责从不同检索方式获得候选内容。资料中出现了 FAISS 和 BM25 的混合方案：前者适合根据语义相似度查找内容，后者适合处理关键词、专有名词和精确匹配。原型中可以先保留两路结果，再交给结果整理节点合并。

结果整理节点负责去重、截取和排序。它不负责回答问题，只负责把更适合交给模型的上下文整理出来。这样做的好处是，检索效果不理想时，可以单独检查召回内容，而不用把问题归咎于生成模型。

生成节点才负责根据问题和检索上下文组织答案。输出校验节点则检查结果是否符合预先约定的结构，例如是否包含回答正文、依据列表，以及无法确认时是否明确说明信息不足。

让 Claude Code 协助完成 LangGraph 迁移

如果已有一个普通的 RAG 链，迁移到 LangGraph 时，不要直接要求插件“重写全部代码”。更可靠的协作顺序是先拆分，再迁移。

第一步，让插件分析现有链路，只输出以下内容：

• 当前输入从哪里开始；




• 文档在哪个环节被检索；




• 模型在哪个环节生成回答；




• 哪些变量会在多个步骤之间传递；




• 哪些异常目前没有处理。

第二步，将分析结果映射成节点。一个普通的串行链通常可以拆成查询处理、检索、上下文整理、回答生成和结果校验几个部分。每个节点先保持原有行为，不要在迁移时顺便改写检索策略。

第三步，再让插件创建状态图。此时重点检查状态字段是否完整，尤其要避免把检索结果藏在某个节点的局部变量中。如果后续节点需要使用该结果，它就应该明确出现在共享状态里。

第四步，补充分支条件。例如：

• 查询为空时，直接返回输入错误；




• 检索结果为空时，不进入普通回答流程；




• 输出格式不符合约束时，进入修正节点；




• 修正后仍不符合要求时，交给人工处理。

可以向插件提出类似这样的任务描述：

请先阅读现有 RAG 链路，不要修改业务逻辑。
输出：
1. 可拆分的节点及其输入输出；
2. LangGraph 状态字段；
3. 节点之间的转移条件；
4. 可能需要人工验收的环节。
确认设计后，再分别生成节点代码和测试样例。

这比一句“帮我做一个 LangGraph RAG Agent”更容易得到可审查的结果，也能减少插件擅自增加功能的情况。

把混合检索接入状态图

混合检索的重点，不是简单地把两种搜索结果拼接起来，而是明确它们各自解决什么问题。

假设用户询问某个具体概念、产品名称或配置项，关键词检索通常更容易保留精确匹配；如果用户使用了口语化描述，语义检索则可能召回表达不同但含义相近的内容。两路结果合并后，还需要处理重复片段和相互矛盾的内容。

可以把检索节点设计成下面的逻辑：

读取 rewritten_query
   ↓
执行语义检索
   ↓
执行关键词检索
   ↓
合并候选片段
   ↓
去重与排序
   ↓
写入 documents

这段流程中的 documents 不应只保存一段拼接后的文本。原型阶段至少要保留文档来源标识、片段内容和检索来源，方便检查最终回答引用了哪些内容。

检索链路的验收也不能只看“模型有没有回答出来”。应该单独准备几类问题进行检查：

• 只有关键词匹配才能找到的问题；




• 换一种说法后仍应召回的问题；




• 文档中没有答案的问题；




• 同时命中多个相似片段的问题；




• 不同文档给出不一致表述的问题。

如果检索结果本身就不相关，后面的结构化输出再漂亮，也只是把错误包装得更整齐。

用结构化输出限制回答边界

RAG 原型常见的问题，是模型返回一段看似流畅的文字，却没有清楚区分资料依据、推断内容和无法确认的部分。结构化输出可以先解决“回答应该长什么样”，但不能自动保证内容一定正确。

可以为回答设计一个简单的数据结构：

answer:
  response    面向用户的回答
  evidence    使用到的资料片段或来源标识
  confidence  对当前回答的谨慎程度
  needs_review 是否需要人工复核

字段名称可以根据项目实际约定调整。关键在于，每个字段都要有明确用途。

response 只放最终答复，不要混入内部调试信息。evidence 用来记录回答依据，便于追溯。confidence 不应被理解为绝对准确率，它只能表达当前证据是否充分。needs_review 则为人工验收留出明确入口。

还应给模型设定几条边界：

• 检索资料没有支持时，不要补写具体事实；




• 资料互相冲突时，指出冲突，而不是强行合并；




• 无法确认时，明确说明缺少依据；




• 不要把模型自身常识伪装成检索结果；




• 输出必须符合约定字段，不能只返回自由文本。

插件可以协助生成结构定义和校验逻辑，但开发者需要确认校验失败后的处理方式。是让模型重新生成，还是直接返回“需要人工核验”，应根据应用风险决定。对于原型，保留人工处理出口通常比无限重试更安全。

一次完整的原型运行路径

完成节点设计后，可以用一条问题贯穿整个流程，而不是只测试最后的回答。建议按以下顺序观察：

首先检查原始问题是否被正确写入状态。若用户问题在进入图之前就被截断或改写错误，后面所有节点都会受到影响。

接着查看查询处理结果。改写后的查询应该更适合检索，但不能改变用户真正想问的对象。尤其是包含专有名词、条件限制或否定表达的问题，需要人工对照原始问题检查。

然后查看两路检索分别召回了什么。不要只看合并后的结果，否则很难判断问题来自语义检索、关键词检索，还是合并规则。

接下来检查传给生成节点的上下文。上下文过少，模型可能缺乏依据；上下文过多，则可能混入无关内容或相互矛盾的表述。原型阶段不必追求复杂优化，但应保留能够回看的中间结果。

最后检查结构化回答，包括回答内容、依据字段和人工复核标记。只有当这些字段都符合预期，才算一次完整运行成功。

哪些环节必须人工验收

插件生成的代码即使能够运行，也不代表架构已经可靠。以下环节不应完全交给自动生成结果。

验收状态与转移关系

检查每个节点是否只做一类工作，状态字段是否被正确读写，以及异常分支是否真的能够到达。尤其要关注“检索为空”和“结构化输出失败”这两条路径，它们最容易在演示流程中被忽略。

验收检索质量

随机抽查若干问题，分别观察关键词检索、语义检索和合并后的结果。若文档来源、片段位置或检索方式没有保留下来，后续排错会变得困难。

验收事实依据

把最终回答逐句与检索内容对照，区分哪些内容有资料支持，哪些内容只是模型推断。结构化字段可以帮助整理证据，但不能替代人工判断。

验收失败处理

故意输入空问题、资料不存在的问题，以及会命中冲突资料的问题，确认系统不会用一段流畅文字掩盖失败。对于无法确认的内容，明确标记人工复核，通常比强行生成更适合原型阶段。

适合原型阶段的取舍

这个方案的重点是验证三件事是否能够衔接：

1. LangGraph 是否清楚表达了 Agent 的状态变化；




2. 混合检索是否能提供可追溯的上下文；




3. 结构化输出是否能约束回答并暴露需要复核的情况。

只要这三点还没有验证，就不必急着加入更多 Agent、复杂工具调用或完整前端。资料中已有 LangGraph、混合检索和 Agentic RAG 的多种实现方向，但它们适合作为后续扩展参考，不应在第一个原型里全部叠加。

更稳的迭代顺序是：先跑通单一问题，再检查中间状态；随后增加空结果和冲突资料测试；最后才考虑查询路由、工具调用或多 Agent 分工。Claude Code 的插件可以帮助你加快拆解、生成和修改过程，但架构边界、证据质量和最终回答是否可信，仍然需要开发者逐项确认。