1. 这不是一份“资料清单”而是一张AI Agent实战通关地图你搜过“AI Agent学习资料整理”——页面刷出来几百个GitHub仓库、几十篇公众号长文、一堆PDF和Notion链接点开一个发现是LangChain v0.1的旧教程再点一个标题写着“从零搭建Agent”内容却卡在环境安装就没了下文最常见的是把RAG、LangGraph、MCP全堆进一个目录不讲它们之间怎么咬合只说“都学了你就懂了”。我去年带三个实习生做政务知识助手项目他们就是被这种“资料海洋”淹过的学了两周LangChain写不出能调用真实API的Agent看了三篇RAG多路召回文章连embedding模型选型依据都说不清听说MCP是新热点下载了Yakit插件结果连“server端注册一个tool”都配不成功。这不是资料少是资料没经过实战淬炼。真正能跑通的Agent从来不是靠拼凑模块堆出来的——它需要一条清晰的能力演进路径从单步工具调用Tool Calling到带记忆的决策流Stateful Workflow再到多角色协同Multi-Agent Coordination最后落地到业务闭环如政务问答里的权限校验工单生成日志审计。这份整理就是按这条路径拆解的。核心关键词全部来自真实开发场景LangChain是基础胶水LangGraph是状态引擎RAG是知识注入器MCP是跨系统连接协议。它不教你“怎么装pip”而是告诉你“为什么LangGraph里send(node_name, state)必须传不可变对象”不罗列“RAG框架有哪些”而是用Dify完成政务知识库的实操案例展示如何把“政策文件PDF→向量库→多路召回→重排序→答案生成”这整条链路拧紧螺丝更关键的是它把MCP从协议文档变成可调试的代码——比如用Java把REST接口发布为MCP server时你必须处理的token鉴权头、tool_id命名规范、以及Figma插件调用时的session上下文透传。适合谁刚写完第一个LLM API调用的开发者想跳过“玩具项目”直接进真实战场也适合技术负责人用来评估团队是否真具备Agent交付能力——因为每一步都附带“验收标准”比如LangChain入门阶段你能独立写出带Fallback机制的ToolExecutorRAG阶段你的召回准确率在测试集上稳定超过82%MCP阶段你的server能被Blender和MasterGo两个不同客户端同时调用且状态一致。这不是学习资料是踩过坑后画出的作战地形图。2. 能力演进四阶从单点调用到业务闭环的底层逻辑2.1 第一阶Tool Calling——让大模型“动手做事”的最小闭环很多人以为Agent就是“让LLM自己思考”其实第一步是让它学会“伸手拿工具”。LangChain的早期设计就聚焦于此把HTTP请求、数据库查询、计算器这些操作封装成Tool再让LLM根据用户问题决定调用哪个。但真实场景远比demo复杂。比如政务系统里用户问“我的社保缴费记录在哪查”LLM不能只调用“查询接口”还要先验证用户身份调用Auth Tool、再检查权限调用RBAC Tool、最后才触发查询调用SocialSecurity Tool。这要求Tool之间有依赖关系而原生LangChain的ToolExecutor是扁平调用的——它不保证执行顺序也不处理中间失败。我见过太多项目卡在这里当Auth Tool返回401时整个流程就崩了因为后续Tool根本没收到错误信号。解决方案是引入Tool Graph概念把每个Tool看作图中的节点用DAG定义执行依赖。LangGraph正是为此诞生——它把Tool调用过程显式建模为state transition。举个例子定义一个state schema包含user_id,auth_status,query_result三个字段初始state只有user_id第一个node执行Auth Tool成功则更新auth_statusvalid失败则跳转到error handler只有auth_statusvalid时第二个node才允许执行SocialSecurity Tool。这比单纯写tool装饰器多做了什么它把“条件判断”从LLM prompt里解放出来变成可调试、可监控、可回滚的代码逻辑。LangChain的AgentExecutor本质是prompt engineering的封装而LangGraph的Workflow是状态机编程。所以当你看到“LangChain和LangGraph的区别”这类热搜别纠结语法差异要问你的业务是否需要跨步骤的状态保持如果只是做单次问答LangChain够用如果涉及多轮会话、数据流转、异常恢复LangGraph是必选项。这也是为什么Spring AI Multi-Agent方案强调“stateful agent”——没有状态管理的Agent在真实系统里就是纸老虎。2.2 第二阶Stateful Workflow——让Agent记住“刚才发生了什么”LangGraph的核心价值不在“图”本身而在state。很多初学者卡在send(node_name, state)以为这是个魔法函数。其实它就是Python的字典更新操作但关键在于state的设计哲学。政务知识库项目里我们定义state为class AgentState(TypedDict): messages: Annotated[list, add_messages] # 存储对话历史 user_profile: dict # 用户基本信息户籍、参保类型 context_chunks: list[Document] # RAG召回的片段 workflow_step: str # 当前执行步骤auth, query, format error_code: Optional[str] # 错误码用于路由注意Annotated[list, add_messages]——这是LangGraph的特殊语法表示对messages列表执行“追加”而非“覆盖”。如果你直接state[messages] new_msg历史就丢了。这就是为什么send必须传不可变对象LangGraph内部会对state做deep copy避免意外修改。实操中最大的坑是state字段命名冲突。比如你定义了user_id但RAG检索时又用了同名字段存用户ID结果workflow_step里读到的user_id可能是RAG模块塞进去的脏数据。我们的解决方法是强制命名空间所有RAG相关字段加rag_前缀rag_query,rag_top_k所有权限字段加auth_前缀。这看起来琐碎但在多人协作时能避免90%的诡异bug。另一个关键是state的生命周期管理。政务系统要求会话超时自动清理我们在state里加入last_active_time字段每个node执行前检查时间戳超时则重置state。这无法用LangChain的Memory组件实现——因为Memory只管对话历史不管业务状态。LangGraph的state是真正的业务状态容器它让Agent从“对话机器人”升级为“业务流程引擎”。2.3 第三阶RAG增强——给Agent装上“活的知识大脑”RAG不是“把文档扔进向量库”而是构建一个知识供应链。政务知识库项目里我们面对的是2000份PDF政策文件其中70%含表格和扫描件。直接用默认embedding模型如text-embedding-ada-002处理召回准确率只有53%。问题出在三个环节文档解析层PDF解析工具选型。我们对比了PyPDF2、pdfplumber、Unstructured最终选择Unstructured OCR pipeline。因为政策文件常有盖章扫描页PyPDF2完全提取不到文字pdfplumber对表格识别不准而Unstructured能自动检测扫描页并调用Tesseract OCR准确率提升38%。向量化层embedding模型微调。通用模型对“城乡居民基本医疗保险”这类长尾词泛化差。我们用政务术语表构造1000条query-document pair用LoRA微调bge-large-zh使“医保报销比例”相关query的top-5召回率从61%升至89%。召回层多路召回不是简单“加权平均”。我们部署了三路语义召回bge模型、关键词召回ElasticSearch BM25、实体召回NER识别政策文件中的“参保地”“缴费年限”等实体后精确匹配。但关键在rerank——用Cross-Encoder对100个候选做重排序而不是用向量相似度硬过滤。Dify实践里我们发现rerank模型必须用政务语料训练通用模型如bge-reranker-base在“灵活就业人员参保”这类query上表现极差。最终方案是先用BM25召回50个粗筛结果再用bge语义召回50个合并去重后送入政务专用rerank模型top-3准确率达92%。这解释了为什么“RAG多路召回”是高频热词——它不是技术炫技而是应对真实文档噪声的生存策略。当你看到“ontology RAG”时本质是把政策知识结构化用本体定义“参保类型”“待遇享受条件”“办理流程”之间的关系让RAG召回时不仅找文本更找逻辑关联。这已超出传统RAG范畴进入知识图谱驱动的智能问答。2.4 第四阶MCP协议——让Agent成为系统级“数字员工”MCPModel Context Protocol常被误解为“又一个API协议”其实它是Agent的OS层。LangChain/LangGraph解决的是Agent内部逻辑MCP解决的是Agent与外部世界交互的标准化问题。政务系统里Agent需要同时对接前端Figma插件供设计师调用政策查询后端Java Spring Boot服务处理工单生成桌面端Yakit安全工具审计API调用日志如果每个系统都写一套REST适配器维护成本爆炸。MCP的价值在于定义统一的tool注册、调用、响应格式。以Java发布MCP server为例核心不是写HTTP接口而是实现MCP规范的三个核心接口/mcp/tools返回tool元数据name, description, input_schema/mcp/execute接收tool_call请求返回result或error/mcp/health健康检查难点在于input_schema的JSON Schema兼容性。比如Figma插件要求tool参数必须是{ type: string }但Java的RequestBody默认反序列化为Object需用Jackson配置DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIESfalse。更隐蔽的坑是token鉴权——MCP要求所有请求带Authorization: Bearer token但Yakit插件生成的token是JWT而Spring Security默认只校验Bearer token需额外配置JWT解析器。我们最终方案是用Spring Boot Actuator暴露/actuator/mcp端点用RestController实现MCP接口用Valid校验input_schema用ResponseEntity统一封装响应。这样Figma、MasterGo、Blender都能用同一套server只需在各自客户端配置MCP endpoint URL。这就是“蓝湖MCP”“MasterGo MCP”热词背后的真相不是工具厂商在推协议而是开发者在用MCP解决跨平台集成的物理难题。MCP不是替代REST而是给REST加上语义层——让不同系统理解“这个tool叫‘查询社保’它需要user_id和date_range参数返回JSON格式的缴费明细”。3. 核心工具链深度拆解从选型依据到避坑指南3.1 LangChain胶水还是枷锁何时该放弃它LangChain常被当作Agent开发的“默认起点”但它的定位其实是LLM应用开发的脚手架而非Agent框架。它的优势在于快速原型验证用几行代码就能把OpenAI API、Chroma向量库、SQLDatabaseChain串起来。但深入业务后问题凸显异步支持薄弱政务系统要求并发处理100会话LangChain的AsyncCallbackHandler在高负载下内存泄漏我们实测QPS超过30就OOM。错误处理粒度粗Tool调用失败时只返回generic error message无法区分是网络超时、认证失败还是参数错误。扩展性瓶颈自定义Tool需继承BaseTool类但复杂业务Tool如带事务回滚的工单生成需要重写_run方法破坏了单一职责原则。我们的取舍策略是用LangChain做PoC用LangGraph做生产。具体分工LangChain负责“胶水层”封装LLM调用OpenAI、Qwen、向量库操作Chroma、Milvus、文档加载器UnstructuredLoader。这些组件在LangGraph里依然复用只是不再用AgentExecutor调度。LangGraph负责“引擎层”定义state schema、编写node函数、配置graph.checkpointer。自研“Adapter层”把LangChain的Tool包装成LangGraph兼容的node。例如将LangChain的SQLDatabaseTool转换为def sql_node(state: AgentState) - AgentState: try: result sql_tool.invoke({query: state[rag_query]}) return {sql_result: result, workflow_step: sql_executed} except Exception as e: return {error_code: SQL_EXEC_ERROR, workflow_step: error_handler}这样既保留LangChain生态的成熟组件又获得LangGraph的状态控制能力。所以当你搜索“LangChain入门”时重点学它的组件封装思想搜索“LangGraph实战”时重点学state管理和node编排。二者不是替代关系而是分层协作。3.2 LangGraph状态机编程的实操心法LangGraph的文档强调“graph is the program”但新手常陷入两个误区过度设计graph为每个小功能建node导致graph节点数暴增调试困难。我们政务项目初期建了12个node后来精简到5个auth_check、rag_retrieve、llm_generate、format_response、error_handler。原则是一个node只做一件事且这件事必须有明确的输入输出契约。比如rag_retrieve只负责召回不处理重排序重排序交给独立的rerank_node但实际因性能考虑合并到rag_retrieve里——这是权衡不是教条。忽略checkpointer本地开发用MemorySaver没问题但生产环境必须用Redis或PostgreSQL checkpointer。我们曾因没配checkpointer导致Agent在K8s pod重启后丢失所有会话状态用户正在填的工单表单全丢。配置要点Redis checkpointer需设置ttl防止key堆积PostgreSQL checkpointer需建表langgraph_checkpoints字段包括thread_id,checkpoint,metadata关键是thread_id生成政务系统用user_id session_id组合确保同一用户不同会话隔离send(node_name, state)的实操技巧永远用state.copy()传递避免node内部修改影响其他分支用__getitem__安全取值state.get(user_profile, {})比state[user_profile]防崩溃批量send用yield当一个node需触发多个下游时用yield返回多个send指令比循环调用高效LangGraph的调试神器是graph.get_graph().draw_mermaid_png()但生产环境禁用——它依赖graphviz增加部署复杂度。我们改用日志埋点在每个node开头打logger.info(fEnter {node_name} with state keys: {list(state.keys())})配合ELK日志系统故障时秒级定位卡点。3.3 RAG框架从Dify到自研的取舍逻辑Dify是RAG落地的“瑞士军刀”但政务项目最终走向自研原因有三数据主权要求Dify Cloud版数据走第三方服务器政务数据必须本地化。我们用Dify开源版但发现其RAG pipeline硬编码了OpenAI embedding替换为国产模型需改17个文件。定制化召回需求Dify的多路召回是插件式但我们需要“政策时效性权重”——2023年发布的文件比2018年文件权重高3倍。这需修改rerank逻辑Dify的插件机制不支持。审计合规压力Dify的audit log只记录LLM输入输出但政务要求记录“谁在何时调用了哪个政策文件”。这需在RAG检索层埋点Dify架构不开放此能力。自研RAG框架的核心模块Ingestion Service用Apache NiFi构建数据管道PDF→OCR→文本清洗→chunking按标题分割非固定token→embedding→入库Retrieval Service三路召回引擎用Redis Sorted Set存BM25分数用FAISS索引存向量用Neo4j存实体关系Rerank Service基于政务语料微调的Cross-Encoder输入querydocument pair输出0-1相关分Cache Layer对高频query如“医保报销比例”用LRU Cache命中率82%降低LLM调用成本Dify的价值在于它的可视化编排界面——非技术人员能拖拽配置RAG流程。我们保留Dify作为运营后台让政务人员自主上传新政策、调整召回权重而核心RAG引擎跑在私有集群。这解释了“dify 完成政务 rag 知识库的实践项目”为何是热词它代表一种务实路线——用Dify降门槛用自研保底线。3.4 MCP ServerJava实现的细节陷阱Java实现MCP server不是写REST API那么简单以下是踩坑总结Tool注册的schema校验MCP要求tool input_schema是JSON Schema Draft 7。Java的Jackson不原生支持需用json-schema-validator库。我们定义了一个McpTool注解运行时生成schemaMcpTool(name query_social_security, description 查询用户社保缴费记录) public class SocialSecurityTool { JsonProperty(user_id) NotBlank private String userId; JsonProperty(date_range) Pattern(regexp ^\\d{4}-\\d{2}-\\d{2}:\\d{4}-\\d{2}-\\d{2}$) private String dateRange; }并发安全MCP server需处理多客户端并发调用。我们用Scope(prototype)确保每个请求有独立bean实例避免static变量污染。错误响应规范MCP要求error response必须含error_code和error_message字段。Spring Boot的ControllerAdvice全局异常处理器需重写确保所有异常转为MCP标准格式。客户端兼容性Figma插件要求response header含Content-Type: application/json而Yakit要求X-MCP-Version: 1.0。我们用OncePerRequestFilter动态添加header根据User-Agent识别客户端。最关键的实践是MCP server的灰度发布。政务系统不能全量切换我们设计了双通道新请求走MCP server旧请求走Legacy REST API用Nginx按URL path分流。这样Figma设计师先用上MCP业务系统逐步迁移零 downtime。这解释了“java将rest接口发布为mcp”为何是刚需——它不是技术升级而是系统演进的过渡策略。4. 实战项目拆解政务RAG知识库从0到1的完整链路4.1 需求分析为什么政务场景是Agent最佳试验田政务问答看似简单实则是Agent能力的终极考场知识权威性答案必须100%准确LLM幻觉行政事故流程强约束查社保需先验身份办退休需先核工龄步骤不可跳过数据敏感性用户身份证号、缴费明细等PII数据全程需加密传输与存储审计强要求每次查询必须留痕记录操作人、时间、调用的政策文件因此政务RAG不是“把政策文档喂给LLM”而是构建一个可信知识执行体。我们的目标系统叫“政知通”核心指标答案准确率 ≥ 99.2%人工抽检1000条平均响应时间 ≤ 1.8s含OCR、RAG、LLM支持并发 ≥ 200 QPS全链路审计日志留存 ≥ 180天这决定了技术选型必须放弃“炫技”专注可靠。比如放弃Llama3-70B选用Qwen2-7B-Int4量化模型——精度损失0.3%但推理速度提升3倍显存占用从24GB降至6GB单卡可部署。4.2 架构设计四层解耦的生产级架构政知通采用分层架构每层可独立演进接入层Nginx JWT网关负责身份认证、流量限流、MCP/REST协议路由Agent层LangGraph Workflow含5个核心nodestate存于RedisRAG层自研检索引擎含Ingestion、Retrieval、Rerank三子系统数据层PostgreSQL业务数据、Milvus向量库、MinIO原始PDF关键设计决策RAG与LLM解耦RAG只返回context chunksLLM prompt里明确要求“仅基于以下context回答禁止编造”。这用system_prompt硬约束而非依赖LLM自身可靠性。缓存策略分级L1Redis缓存高频query的rerank结果TTL 1hL2LLM输出缓存TTL 24h用query hash做keyL3向量库预热——启动时加载top 1000政策文件的embedding到GPU显存降级开关当LLM服务不可用时自动切换至“RAG-only模式”返回召回的政策原文片段加提示“当前AI服务暂不可用请参考以下原文”。架构图虽未用Mermaid但逻辑清晰所有数据流单向流动无环状依赖。这保证了故障隔离——RAG层宕机不影响身份认证LLM层延迟不阻塞工单生成。4.3 数据工程政务文档的“庖丁解牛”式处理政务PDF处理是最大技术债。我们建立了一套文档治理流水线来源校验每份PDF必须带政府官网水印、发布文号如“国发〔2023〕12号”无文号文件自动拒收OCR增强对扫描页用PaddleOCR对文字页用pdfplumber提取混合结果用规则去重相同段落只留一次结构化解析用LayoutParser识别PDF版式区分“标题”“正文”“表格”“附件”。政策文件中表格常含关键数据如“各档缴费基数”需单独提取为JSON存入Neo4jChunking策略不用固定token切分而用语义切分——以“条款”为单位每个chunk含完整条款编号、标题、正文。例如《社会保险法》第十二条“用人单位应当按照国家规定的本单位职工工资总额的比例缴纳基本养老保险费...”作为一个chunk而非截断在“缴纳”二字处Embedding优化用政务术语表构造对比学习样本微调bge模型。例如正样本“城乡居民医保报销比例” ↔ “参保人员在定点医疗机构发生的符合规定的住院医疗费用统筹基金支付比例为70%-90%”负样本替换为“职工医保报销比例”这套流程使RAG召回质量提升显著条款级召回准确率从68%升至94%因为chunk语义完整性保障了LLM能获取完整逻辑单元。4.4 安全与审计政务系统的生命线政知通的安全设计不是附加功能而是架构基因PII脱敏用户提问中含身份证号用正则识别后替换为IDLLM输出时再用密钥还原。密钥存于HashiCorp Vault不硬编码权限沙箱每个user_id绑定role市民/社区工作人员/社保局管理员RAG检索时自动注入role字段向量库查询加filter“policy_type IN (role_allowed_types)”审计日志每条日志含trace_id全链路追踪、user_id、tool_called、context_used召回的政策文件ID、llm_input脱敏后、llm_output脱敏后。用Filebeat采集到ELKKibana配置“政策文件调用TOP10”看板模型水印在LLM输出末尾添加不可见Unicode字符如U2063用于溯源——若答案泄露可反向追踪到哪次调用生成这些不是合规检查时才补的而是从第一行代码就植入。比如context_used字段是在RAG retrieval node里硬编码写入state的确保任何绕过Agent的直连RAG调用都不产生审计日志——系统只认Agent层的调用。5. 面试与实战高频问题的底层答案与避坑指南5.1 LangChain面试题超越语法的记忆点面试官问“LangChain Agent的执行流程”别背initialize → plan → act → observe。讲真实场景“上周我们遇到一个case用户问‘我孩子能参加居民医保吗’Agent调用年龄查询Tool返回‘3岁’但LLM仍生成‘可以参保’因为政策文件说‘新生儿出生即参保’。问题出在prompt里没强调‘必须引用具体条款’。我们修复方案是在system prompt加一句‘答案必须标注政策文件名称及条款编号如【《XX市居民医保办法》第三条】’并在output parser里校验是否含方括号引用。这比改模型参数有效得多。”高频题“LangChain和LangGraph区别”用状态机比喻“LangChain像乐高积木给你现成的轮子、窗户、门你拼出房子LangGraph像建筑蓝图规定承重墙在哪、电路怎么走、消防通道宽度。做玩具房子用LangChain盖真实住宅必须用LangGraph。”5.2 RAG考题多路召回与重排序的实战逻辑“RAG多路召回”不是技术名词是工程权衡“单路召回就像只用百度搜索多路召回是同时用百度、天眼查、企查查。BM25擅长找关键词向量召回擅长找语义相似实体召回擅长找精确匹配。但合并结果时不能简单加权——比如‘灵活就业人员’这个词BM25可能召回100个含该词的文件但向量召回的5个文件里有2个是最新政策。我们的策略是BM25取top20向量取top20实体取top5去重后送rerank。rerank模型用政务语料训练它知道‘2023年新规’比‘2018年旧规’权重高。”“Embedding rerank RAG有关考题”直击痛点“rerank不是万能药。我们测试发现当query长度50字时Cross-Encoder效果反降——因为长query含噪音。解决方案是query rewrite用LLM把‘我爸爸60岁在杭州交了15年社保能领养老金吗’压缩为‘杭州灵活就业人员60岁养老金领取条件’再送rerank。这步提升top-3准确率12%。”5.3 MCP协议从协议文档到可调试代码“MCP是什么”不能答“模型上下文协议”要说“MCP是Agent的USB-C接口。就像手机用USB-C能连显示器、硬盘、充电器Agent用MCP能连Figma、Yakit、Java服务。它的价值不是技术多先进而是让不同厂商的工具能‘即插即用’。我们用MCP省掉了为每个工具写适配器的人力——原来接Figma要3人日现在只要配置endpoint URL。”“Yakit MCP如何使用”的实操答案“Yakit的MCP插件本质是个客户端。你只需在Yakit里填MCP server地址它会自动调用/mcp/tools获取可用tool列表。但关键在tool参数Yakit要求参数名严格匹配schema比如tool定义{user_id: {type: string}}你传{userId: 123}就会报错。我们用Postman调试时先GET/mcp/tools看schema再POST/mcp/execute用Yakit的log功能看它发了什么请求——这才是调试真谛。”5.4 AI Agent学习路线拒绝“从零开始”的幻觉网上“AI Agent学习路线图”常列“Python基础→LLM原理→LangChain→LangGraph→MCP”这是误导。真实路径是先做一道题用LangChain写一个能查天气的Agent调用OpenWeatherMap API目标不是代码多美而是理解Tool、AgentExecutor、Memory怎么协作再破一个坑故意让Tool返回错误观察Agent怎么崩然后用LangGraph重写体验state如何捕获错误并路由到error handler接着造一个轮子不用Dify用UnstructuredChromaOllama搭最小RAG亲手调参看召回变化最后连一个系统用Java写个MCP server让Figma插件调用它——这时你才懂什么是“Agent落地”这条路的里程碑不是“学完多少课”而是能独立修复LangChain Agent的fallback失效问题能用LangGraph实现带超时重试的workflow能用政务语料微调出RAG rerank模型能让MCP server被三个不同客户端调用且日志可追溯没有捷径只有把每个模块的真实缺陷亲手暴露出来再解决它。那些“30天速成AI Agent”的课程教的都是不会崩的demo而真实世界崩是常态。6. 常见问题速查表从环境配置到线上故障问题现象根本原因解决方案实操验证LangChain Agent调用Tool后无响应Tool的return_directTrue未设导致结果被LLM二次处理在Tool定义中显式设置return_directTrue或用ToolExecutor手动控制写一个echo Tool返回字符串观察是否被LLM改写LangGraph workflow卡在某个node不继续send时传入的state未包含下游node所需的字段在node函数开头打印state.keys()确认必需字段存在用state.get(required_key, default_value)安全取值添加logger.info(f{node_name} state: {state})RAG召回结果与query语义无关embedding模型未针对领域微调或chunking破坏语义完整性用领域语料微调embedding模型改用语义chunking按标题/条款分割对比微调前后top-5召回人工评估相关性MCP server被Figma调用返回404Figma插件发送的请求path不是/mcp/execute而是/execute检查Figma插件文档确认其MCP版本用Wireshark抓包看实际请求URL在Nginx配置rewrite ^/execute$ /mcp/execute break;临时兼容Dify RAG知识库更新后不生效Dify的向量库未重建或缓存未刷新在Dify后台点击“重新嵌入”等待状态变为“已完成”清除浏览器缓存用curl调用Dify的/api/v1/knowledge-base/{kb_id}/documents确认文档状态Java MCP server并发时出现数据错乱Tool bean作用域为singleton多线程共享state将Tool bean改为Scope(prototype)或用ThreadLocal存储临时数据用JMeter模拟100并发检查返回结果是否混杂独家避坑技巧LangGraph调试黄金法则永远在graph创建后加graph.get_graph().print_ascii()它会输出ASCII流程图一眼看出node连接是否正确RAG性能瓶颈定位用cProfile分析RAG pipeline90%的慢在OCR或rerank而非向量检索。优先优化这两步MCP协议兼容性测试用curl模拟各客户端请求curl -X POST http://localhost:8000/mcp/execute -H Content-Type: application/json -d {tool:query_social_security,parameters:{user_id:123}}政务系统上线 checklist① 所有PII字段脱敏 ② 审计日志字段完整 ③ 降级开关已验证 ④ 压测QPS达标 ⑤ 政策文件文号校验通过最后分享一个小技巧政务RAG项目上线前我们让社区工作人员用真实问题测试不是问“医保怎么交”而是问“我户口在A区但人在B区打工孩子上学能在B区参保吗”——这种含地域、身份、政策交叉的问题才是检验Agent真实能力的试金石。当它能准确引用《XX市流动人口子女参保办法》第二章第三条并给出办理路径时你知道它真的活了。