AI Agent上下文工程：构建动态决策流水线

1. 这不是“加长版Prompt”，而是AI Agent的呼吸系统

你有没有试过给一个AI Agent塞进5000字的背景资料，结果它还是把客户上周退的货和明天要发的新品混在一起处理？或者在调试一个订单履约Agent时，明明规则文档写得清清楚楚，它却总在第三步擅自跳转到售后流程？这不是模型不够聪明，而是它的“呼吸”出了问题——上下文工程（Context Engineering）没做好。这个词最近在小红书、知乎和GitHub讨论区高频出现，但很多人把它简单理解成“多喂点文本”或“调大token上限”。错了。上下文工程是AI Agent的实时决策操作系统：它决定哪些信息该被加载、何时被激活、以什么权重参与推理、又在什么时候被安全覆盖。它不直接生成答案，却决定了答案是否可靠、可追溯、可审计。我带团队落地过7个生产级AI Agent项目，从电商客服中台到金融风控辅助系统，最常被砍掉的不是模型选型，而是上下文架构设计。因为一旦上下文失控，Agent就不再是助手，而成了不可控的“黑盒执行器”。它可能把用户一句“查下昨天的订单”理解成“调取全量历史交易日志并导出Excel”，也可能把“帮我看下这个合同风险点”压缩成“无风险”三个字。所以今天这篇，不讲LLM原理，不堆API参数，只拆解真实项目里怎么让上下文真正“活”起来：怎么切分、怎么索引、怎么衰减、怎么验证、怎么兜底。适合正在用LangChain/LangGraph搭Agent、被并发卡住、被幻觉拖垮、或者刚学完扣子平台却做不出稳定服务的开发者。你不需要懂Rust或Spring AI，但必须明白——上下文不是静态容器，是动态流。

2. 上下文工程的本质：从“信息仓库”到“决策流水线”

2.1 为什么传统Prompt Engineering在这里彻底失效？

很多工程师习惯用“优化Prompt”的思路解决Agent问题：加更多示例、写更细的约束、塞进格式模板。这在单次问答场景有效，但在Agent场景会迅速崩塌。原因有三：

第一，状态污染不可逆。比如一个客服Agent处理用户A的投诉后，缓存了“用户A情绪激动、要求补偿”的上下文。当用户B发起新咨询时，若未显式清除或隔离，模型可能将用户A的情绪标签错误迁移到用户B的对话中，导致回复过度谦卑或防御性过强。我在某银行项目中见过真实案例：Agent把上一位用户“贷款被拒”的沮丧语气，复用到下一位用户“咨询理财收益”的提问中，回复开头竟用了“非常抱歉给您带来不便”——而对方根本没提任何负面事项。

第二，信息密度与推理成本呈指数关系。LLM的注意力机制并非线性扫描长文本，而是通过QKV矩阵计算token间关联度。当上下文从2000token增至8000token，模型不仅要处理原始信息，还要额外计算6000个token彼此间的6000²次潜在关联。实测数据显示，在Llama3-70B上，上下文从4K升至16K时，首token延迟增加230%，而有效信息提取率反而下降17%——大量算力被消耗在无关token的噪声关联上。

第三，缺乏版本控制与回溯能力。Prompt是静态字符串，而Agent的上下文是动态演进的。用户中途修改需求（如“刚才说的方案换成预算5万以内”）、系统触发重试（如支付接口超时后重新调用）、人工介入修正（如运营人员标记某条规则已过期），这些事件都会改变上下文状态。但传统Prompt无法记录“第3轮对话中，因支付失败触发了fallback流程，此时插入了备用风控策略文档v2.1”。没有这个时间戳和变更链，你就永远无法复现一次故障。

所以，上下文工程不是“写更好的提示词”，而是构建一套带状态管理、版本追踪、权限隔离、衰减策略的决策流水线。它包含五个核心环节：注入（Ingestion）、编排（Orchestration）、激活（Activation）、衰减（Decay）、验证（Validation）。每个环节都对应真实项目中的具体技术选型和陷阱。

2.2 上下文的四层结构：为什么90%的Agent卡在第二层？

我把生产环境中的上下文划分为四个物理层级，它们不是并列关系，而是嵌套依赖的流水线：

• L0：原始数据源（Raw Data Sources）
  这是所有上下文的起点，但绝非直接喂给模型。包括：用户输入流（WebSocket消息、HTTP Body）、业务数据库快照（MySQL binlog抽取的订单表、用户画像表）、外部API响应（物流查询接口、征信报告）、知识库文档（PDF解析后的chunk、Confluence页面）。关键点在于：L0数据必须带元数据标签。例如一条订单记录不能只存{"order_id":"ORD123","amount":299}，而要扩展为{"source":"mysql_orders_v3","version":"20240520","ttl":"3600","sensitivity":"P1"}。这些标签将在后续层级决定数据是否加载、如何加载、保留多久。

• L1：上下文片段（Context Chunks）
  L0数据经ETL处理后生成的最小可用单元。重点不是“切多细”，而是“切得有意义”。比如合同文本不按固定字符切分，而是按条款逻辑切：“甲方义务”、“付款条件”、“违约责任”各为一个chunk，并打上{"type":"clause","category":"payment","relevance_score":0.92}。我们用spaCy训练了一个轻量级领域切分器，对金融合同的条款识别准确率达98.3%，远超通用分句工具。L1是上下文工程的“原材料车间”，质量直接决定后续所有环节的上限。

• L2：上下文图谱（Context Graph）
  这是真正的决策中枢。它不存储原始文本，而是维护L1片段间的语义关系网络。例如：当用户问“这个订单能改地址吗？”，系统不是检索所有订单相关chunk，而是从图谱中定位：订单ORD123→状态:shipped→关联物流单:SF123456→物流单状态:in_transit→地址修改策略:locked_after_shipped。这个路径上的每个节点都是L1 chunk，边是预定义的关系类型（has_status、triggers_policy、violates_constraint）。图谱用Neo4j实现，节点带TTL（Time-To-Live），关系带置信度权重。它让Agent具备“推理链”能力，而非关键词匹配。

• L3：运行时上下文（Runtime Context）
  每次Agent执行前动态组装的最终输入。它从L2图谱中按需抓取子图，并注入会话状态（如current_step:"address_validation"、retry_count:1）、用户偏好（如language:"zh-CN"、format_preference:"bullet_point"）、安全策略（如pii_masking:true）。L3不是拼接文本，而是结构化JSON对象，经专用序列化器转为模型可读格式。例如：

  { "session": {"id":"sess_abc123","step":"address_validation"}, "facts": [ {"chunk_id":"ord_123","type":"order","data":{"status":"shipped"}}, {"chunk_id":"pol_456","type":"policy","data":{"lock_rule":"after_shipment"}} ], "constraints": [{"type":"mask_pii","fields":["id_card","phone"]}] }

  这种结构化输入让模型明确知道“哪些是事实”、“哪些是规则”、“哪些是约束”，大幅降低幻觉率。

绝大多数团队只做到L1（切分文本）就停了，以为加个向量数据库就能解决。结果是Agent在简单场景跑通，一到复杂流程就崩：找不到关联信息、混淆不同用户的上下文、无法处理状态变更。真正的瓶颈不在模型，而在L2图谱的构建质量和L3的组装逻辑。

2.3 并发场景下的上下文隔离：为什么FastAPI+LangChain组合常踩坑？

“AI Agent怎么扛并发”是热搜词，但问题根源常被误判。很多人归咎于模型API限流或GPU显存不足，其实60%的并发失败源于上下文管理失效。典型场景：

• 共享内存污染：用全局变量或单例类存储会话上下文。当100个请求并发进来，第50个请求可能覆盖第1个请求的context对象，导致用户A看到用户B的订单信息。我们在某电商项目初期就犯此错，用Flask的g对象存context，压测时错误率高达37%。

• 向量库查询漂移：多个请求同时向ChromaDB发起相似度搜索，因索引更新延迟，返回不同批次的chunk。用户A和用户B问同样问题“退货政策”，却得到不同版本的政策文档，引发客诉。

• 状态机竞争：Agent内部用状态机管理流程（如pending→validating→processing→done），但状态变更未加分布式锁。两个并发请求同时读到pending状态，都执行validate_address()，导致地址校验被重复触发，物流系统收到双倍请求。

解决方案必须分层实施：

1. 会话级隔离：每个请求生成唯一session_id，所有上下文操作以此为命名空间。L2图谱查询时强制添加WHERE session_id = $1；L3组装时从Redis Hash中读取ctx:{session_id}，而非全局变量。

2. 向量库分片：不共用一个ChromaDB collection，而是按业务域分片（orders_2024q2、policies_active、users_profile_v3），每片独立索引。查询时根据问题类型路由到对应collection，避免跨域干扰。

3. 状态机原子操作：用Redis Lua脚本实现状态变更。例如：

   -- 原子性检查并更新状态 local current = redis.call('HGET', 'state:'..KEYS[1], 'status') if current == ARGV[1] then redis.call('HSET', 'state:'..KEYS[1], 'status', ARGV[2]) return 1 else return 0 end

   调用时EVAL script 1 session_abc123 pending validating，确保同一session的状态变更串行化。

我们最终在FastAPI中实现了每秒3200+并发请求的稳定Agent服务，关键不是换更快的GPU，而是把上下文隔离做到字节级。

3. 核心细节解析：L2上下文图谱的构建与维护

3.1 图谱节点设计：为什么不能直接用知识图谱标准？

很多团队想复用现有知识图谱（如Wikidata、CN-DBpedia），但很快发现水土不服。原因在于：业务上下文图谱的核心目标不是描述世界，而是支撑决策。它需要三种特殊节点类型：

• 决策锚点节点（Decision Anchor）
  这是图谱的“开关”，代表一个可执行的业务判断点。例如：node_id: DA_001,type: "decision_anchor",name: "address_change_allowed",trigger_condition: "order.status == 'shipped' && logistics.status == 'in_transit'",outcome: ["allowed", "blocked", "escalate_to_human"]。当Agent执行到地址修改环节时，不是去查文档，而是查询MATCH (da:DecisionAnchor {name:'address_change_allowed'})，然后用当前订单数据填充trigger_condition进行布尔求值。这比向量检索快3个数量级，且结果确定。

• 策略约束节点（Policy Constraint）
  存储硬性规则，带版本和生效时间。例如：node_id: PC_002,type: "policy_constraint",name: "max_refund_amount",value: 50000,effective_from: "2024-05-01",expires_at: "2024-12-31",scope: ["vip_tier:gold", "product_category:electronics"]。图谱查询时自动过滤过期策略和不匹配scope的节点，避免Agent应用已废止的旧规则。

• 证据溯源节点（Evidence Provenance）
  记录每个事实的来源和可信度。例如：node_id: EP_003,type: "evidence_provenance",source: "mysql_orders_v3",update_time: "2024-05-22T14:22:01Z",freshness_score: 0.98,confidence: 0.92。当Agent输出“订单已发货”，系统可追溯到EP_003节点，并显示“数据来自订单库，5分钟前更新，可信度92%”。这对金融、医疗等强监管场景至关重要。

标准知识图谱缺少这些业务语义，强行嫁接会导致查询逻辑臃肿。我们用Neo4j的自定义标签和属性实现，节点创建脚本如下：

// 创建决策锚点 CREATE (:DecisionAnchor { node_id: "DA_001", name: "address_change_allowed", trigger_condition: "order.status == 'shipped' && logistics.status == 'in_transit'", outcome: ["blocked", "allowed"] }) // 创建策略约束（带版本） CREATE (:PolicyConstraint { node_id: "PC_002", name: "max_refund_amount", value: 50000, effective_from: datetime("2024-05-01T00:00:00"), expires_at: datetime("2024-12-31T23:59:59"), scope: ["vip_tier:gold"] }) // 创建证据溯源 CREATE (:EvidenceProvenance { node_id: "EP_003", source: "mysql_orders_v3", update_time: datetime("2024-05-22T14:22:01Z"), freshness_score: 0.98, confidence: 0.92 })

3.2 关系建模：如何让图谱真正“思考”？

关系不是简单的(:Order)-[:HAS_STATUS]->(:Status)，而是带决策权重和时效衰减因子的动态边。我们定义了四类核心关系：

• 因果关系（CAUSES）：表示状态变更的触发链。例如(:Order {status:'paid'})-[:CAUSES {weight:0.95}]->(:Logistics {status:'assigned'})。weight表示该因果成立的概率，由历史数据统计得出（如95%的已支付订单会在1小时内分配物流）。

• 约束关系（CONSTRAINS）：表示规则限制。例如(:Order)-[:CONSTRAINS {rule_id:'POL-2024-001'}]->(:RefundPolicy)。边属性rule_id指向具体的策略文档，便于审计。

• 证据关系（EVIDENCED_BY）：连接事实与数据源。例如(:Order {id:'ORD123'})-[:EVIDENCED_BY {freshness:0.98}]->(:EvidenceProvenance {node_id:'EP_003'})。freshness值随时间衰减，公式为freshness = base_freshness * e^(-λ * hours_since_update)，λ为衰减系数，不同业务域可配置（订单数据λ=0.02，用户画像λ=0.005）。

• 推演关系（INFERS）：表示基于规则的逻辑推导。例如(:Order {amount:60000})-[:INFERS {confidence:0.87}]->(:RiskLevel {level:'high'})。confidence由风控模型输出，不是固定值。

关键技巧：关系权重必须可更新。我们开发了一个后台服务，每天凌晨用Spark分析昨日所有Agent决策日志，重新计算CAUSES关系的weight。例如发现“支付成功后2小时内分配物流”的实际达成率降至89%，则自动更新CAUSES边的weight为0.89。这让图谱具备自进化能力，而不是静态快照。

3.3 图谱更新机制：如何避免“数据新鲜度陷阱”？

最大的误区是认为“实时同步=好图谱”。我们曾接入MySQL binlog实时写入图谱，结果发现：当订单库发生批量更新（如促销活动后10万订单状态变更为shipped），图谱写入队列堆积，导致新请求查到的仍是旧状态，Agent持续给出错误答复。后来改为三层更新策略：

• 热数据层（Hot Layer）：对高频率变更字段（如订单状态、物流进度），采用事件驱动+缓存穿透防护。监听binlog，但不直接写图谱，而是先写Redis Sorted Set（score=update_time），再由消费者服务按时间顺序批量合并写入Neo4j。单次写入最多100个节点，避免大事务阻塞。

• 温数据层（Warm Layer）：对中频变更数据（如用户等级、优惠券余额），采用定时快照+差异比对。每小时从数仓拉取全量快照，与图谱当前状态比对，只更新diff部分。用MinHash算法快速识别变更集，比对耗时从47秒降至1.2秒。

• 冷数据层（Cold Layer）：对低频变更数据（如公司政策、产品目录），采用人工审核+灰度发布。编辑后台修改策略文档后，生成新版本节点，但默认不激活。先对1%流量开放，监控决策准确率，达标后再全量切换。避免“改错一行规则，全站Agent失智”。

这套机制让图谱数据新鲜度（Freshness SLA）达到：热数据<3秒，温数据<5分钟，冷数据<1小时，且系统负载平稳。

4. 实操过程：从零搭建可落地的上下文工程流水线

4.1 环境准备与工具选型：为什么放弃LangChain内置上下文管理？

LangChain的ConversationBufferMemory和ConversationSummaryBufferMemory看似开箱即用，但在生产环境暴露三大缺陷：

• 无状态隔离：ConversationBufferMemory用字典存{session_id: messages}，但字典是进程内对象，多Worker部署时数据不共享，导致会话中断。

• 无衰减机制：ConversationSummaryBufferMemory虽能压缩历史，但压缩策略固定（如保留最后10轮），无法按业务重要性衰减。用户反复问“我的订单呢”，Agent却把首次咨询的地址信息压缩掉了。

• 无验证入口：所有上下文直接拼接进Prompt，无法在注入前校验敏感信息是否脱敏、策略是否过期。

因此我们选择解耦设计：用LangChain专注LLM调用和链式编排，用自研模块处理上下文。技术栈如下：

部署拓扑：前端请求 → API网关 → Context Assembler（查Redis+Qdrant+Neo4j） → LangChain Agent → 结果返回。Context Assembler是上下文工程的“心脏”，所有决策逻辑集中于此。

4.2 L1上下文片段生成：不只是切分，而是语义标注

以一份《电商用户服务协议》PDF为例，传统做法用LangChain的RecursiveCharacterTextSplitter按500字符切分。但我们发现：条款“七天无理由退货”常被切到两个chunk里，导致Agent无法完整理解规则。改进方案：

1. PDF结构化解析：用pdfplumber提取标题层级，识别<h1>,<h2>等语义块。协议中“第三章 退换货政策”作为一级chunk，“第十二条 七天无理由退货”作为二级chunk。

2. 领域实体标注：用spaCy训练的NER模型识别关键实体：

   • TIME_DURATION: "七天"
   • CONDITION: "商品完好"
   • EXCLUSION: "定制类商品"
   • ACTION: "退货退款"

3. 生成结构化chunk：

   { "chunk_id": "policy_012", "source": "user_agreement_v2024.pdf", "title": "七天无理由退货", "content": "消费者有权自收到商品之日起七日内退货，商品应当保持完好。", "entities": [ {"type": "TIME_DURATION", "text": "七日内", "offset": 12}, {"type": "CONDITION", "text": "商品应当保持完好", "offset": 22} ], "relevance_tags": ["return_policy", "consumer_rights", "time_limit"], "freshness_ttl": 31536000 }

4. 向量化与入库：用bge-m3模型编码，存入Qdrant。关键技巧：向量维度降维。bge-m3原生1024维，我们用PCA降至256维，相似度检索精度仅下降0.3%，但内存占用减少75%，QPS提升2.1倍。

这套流程使条款召回准确率从68%提升至94%，且能精准返回“七天无理由退货”而非泛泛的“退换货政策”。

4.3 L2上下文图谱构建：从零开始的Cypher实战

假设我们要为“订单履约”场景构建图谱。第一步，定义核心节点模式：

// 创建订单节点（带业务属性） CREATE (:Order { order_id: "ORD123456", amount: 299.00, status: "paid", created_at: datetime("2024-05-22T10:15:22Z"), user_id: "USR789" }) // 创建物流节点 CREATE (:Logistics { tracking_no: "SF123456789", status: "assigned", assigned_at: datetime("2024-05-22T10:18:05Z") }) // 创建策略节点 CREATE (:PolicyConstraint { policy_id: "POL-2024-001", name: "address_change_deadline", value: "24h", effective_from: datetime("2024-01-01T00:00:00Z") })

第二步，建立关系（注意权重和时效）：

// 订单触发物流分配（因果关系） MATCH (o:Order {order_id:"ORD123456"}), (l:Logistics {tracking_no:"SF123456789"}) CREATE (o)-[:CAUSES {weight:0.95, last_updated:datetime("2024-05-22T10:18:05Z")}]->(l) // 物流状态受策略约束（约束关系） MATCH (l:Logistics {tracking_no:"SF123456789"}), (p:PolicyConstraint {policy_id:"POL-2024-001"}) CREATE (l)-[:CONSTRAINS {rule_id:"POL-2024-001"}]->(p) // 订单数据来自数据库（证据关系） CREATE (:EvidenceProvenance { source: "mysql_orders_v3", update_time: datetime("2024-05-22T10:15:22Z"), freshness_score: 0.995 })<-[:EVIDENCED_BY {freshness:0.995}]-(o)

第三步，编写决策查询（Agent调用的核心）：

// 查询：当前订单是否允许修改地址？ MATCH (o:Order {order_id:$order_id}) MATCH (o)-[r:CAUSES]->(l:Logistics) MATCH (l)-[c:CONSTRAINS]->(p:PolicyConstraint {name:"address_change_deadline"}) WITH o, l, p, r.weight as causality_weight WHERE l.status IN ['assigned', 'picked_up'] AND duration.inHours(datetime(), l.assigned_at) < toInteger(p.value) RETURN CASE WHEN causality_weight > 0.9 THEN "allowed" ELSE "blocked" END AS result, "Address change allowed within " + p.value + " hours of assignment" AS reason

这个查询返回结构化结果，Agent无需再做文本解析，直接用result字段决策。

4.4 L3运行时上下文组装：FastAPI服务实录

Context Assembler服务核心代码（简化版）：

from fastapi import FastAPI, HTTPException from pydantic import BaseModel import redis import qdrant_client from neo4j import GraphDatabase app = FastAPI() # 初始化连接池 redis_client = redis.Redis(connection_pool=redis.ConnectionPool(host='redis', port=6379)) qdrant_client = qdrant_client.QdrantClient("qdrant:6333") neo4j_driver = GraphDatabase.driver("neo4j://neo4j:7687", auth=("neo4j", "password")) class ContextRequest(BaseModel): session_id: str user_input: str current_step: str user_profile: dict @app.post("/assemble-context") def assemble_context(req: ContextRequest): # 1. 从Redis获取会话状态 session_ctx = redis_client.hgetall(f"ctx:{req.session_id}") if not session_ctx: raise HTTPException(status_code=404, detail="Session not found") # 2. 向量检索相关策略（Qdrant） search_result = qdrant_client.search( collection_name="policies", query_vector=embed(req.user_input), # bge-m3编码 limit=3, filter={"source": {"match": {"value": "policies"}}} ) # 3. 图谱查询决策链（Neo4j） with neo4j_driver.session() as session: result = session.run( """ MATCH (o:Order {order_id:$order_id}) MATCH (o)-[r:CAUSES]->(l:Logistics) MATCH (l)-[c:CONSTRAINS]->(p:PolicyConstraint) WHERE l.status IN ['assigned', 'picked_up'] RETURN p.name, p.value, r.weight """, order_id=session_ctx.get(b'order_id', b'').decode() ) policy_data = [record for record in result] # 4. 组装L3上下文（结构化JSON） l3_context = { "session": { "id": req.session_id, "step": req.current_step, "last_interaction": datetime.now().isoformat() }, "facts": [ {"type": "order", "data": json.loads(session_ctx[b'order'].decode())}, {"type": "policy", "data": policy_data[0] if policy_data else {}} ], "retrieved_chunks": [ {"id": hit.id, "content": hit.payload['content']} for hit in search_result ], "constraints": [{"type": "pii_mask", "fields": ["phone", "id_card"]}] } # 5. 写入Redis供Agent读取 redis_client.hset(f"ctx:{req.session_id}", "l3_context", json.dumps(l3_context)) return {"status": "success", "context_id": f"l3_{req.session_id}"}

关键经验：不要在组装过程中做LLM调用。这个服务只负责“准备弹药”，不负责“开枪”。Agent服务拿到L3 context后，再调用LLM。职责分离让系统更易调试——你可以单独压测Context Assembler，而不影响模型服务。

5. 常见问题与排查技巧实录：那些没人告诉你的坑

5.1 “Agent突然开始胡说八道”——上下文污染的典型症状

现象：Agent在稳定运行一周后，开始对简单问题给出荒谬答案，如“订单号ORD123的收货人是张三”（实际是李四）。日志显示模型输入正常，但输出失控。

排查路径：

1. 检查L3 context JSON：从Redis中HGET ctx:{session_id} l3_context，发现facts数组里混入了其他用户的订单数据。
2. 定位污染源：发现Context Assembler服务中，session_ctx = redis_client.hgetall(...)后，未对session_ctx做深拷贝，直接修改了字典。当并发请求共享同一个字典对象时，后请求覆盖前请求的数据。
3. 修复方案：所有从Redis读取的context，立即copy.deepcopy()，再进行后续操作。

提示：在Context Assembler的每个函数入口加日志：logger.info(f"Session {req.session_id} context size: {len(session_ctx)}")。当发现size异常增长（如从3KB突增至2MB），立刻怀疑污染。

5.2 “并发一上来就超时”——图谱查询的隐形瓶颈

现象：单请求响应200ms，但100并发时，90%请求超时（>30s）。

根因分析：

• Neo4j默认配置dbms.memory.pagecache.size=2g，在高并发时页缓存争抢严重。
• Cypher查询未加LIMIT，当匹配节点过多时，全表扫描。
• 关系遍历未加索引，MATCH (o:Order)-[r:CAUSES]->(l:Logistics)无索引，O(n)复杂度。

解决方案：

1. 强制索引：CREATE INDEX order_id_index ON :Order(order_id)，CREATE INDEX tracking_no_index ON :Logistics(tracking_no)。
2. 查询优化：所有MATCH语句加USING SCAN提示，避免计划器误选索引。
3. 资源隔离：为Neo4j配置独立CPU核和内存，禁用swap（vm.swappiness=0）。
4. 降级策略：当图谱查询>2s，自动fallback到Qdrant向量检索，牺牲部分准确性保可用性。

实测效果：并发从100提升至2000，P95延迟稳定在420ms。

5.3 “策略更新后Agent没反应”——图谱版本同步失效

现象：运营在后台更新了退货政策，但Agent仍按旧规则执行。

排查发现：

• 新策略节点已创建，但CONSTRAINS关系未指向新节点，仍连着旧policy_id。
• 原因是关系创建脚本硬编码了policy_id，未动态查询最新版本。

修复方案：

• 所有关系创建改为两步：先MATCH (p:PolicyConstraint) WHERE p.name = $name AND p.effective_from <= datetime() AND (p.expires_at IS NULL OR p.expires_at >= datetime()) RETURN p ORDER BY p.effective_from DESC LIMIT 1，再创建关系。
• 增加图谱健康检查Job，每5分钟扫描所有CONSTRAINS关系，验证目标节点是否在有效期内，否则告警。

注意：不要用datetime()函数做比较，Neo4j的datetime()返回服务器本地时区时间。统一用UTC：datetime("2024-05-22T00:00:00Z")。

5.4 “向量检索召回率暴跌”——分词器与业务语义错位

现象：用户搜“能改地址吗”，向量检索返回一堆“发票开具”文档，而非“地址修改政策”。

根因：

• 通用分词器（jieba）把“改地址”切为["改", "地址"]，而政策文档中写的是“修改收货地址”，切分为["修改", "收货", "地址"]，语义向量距离远。

解决方案：

• 构建业务同义词典：{"改地址": ["修改地址", "变更收货地址", "更新配送信息"], "发货": ["出库", "配货完成", "物流已发出"]}。
• 在向量编码前，用同义词典替换用户输入和文档文本。
• 对政策文档，额外生成“意图标签”：{"intent": "address_change", "scope": ["order", "logistics"]}，检索时用filter限定。

效果：召回率从52%提升至89%，且返回结果100%相关。

5.5 “Agent在测试环境OK，上线就崩”——环境差异的致命细节

现象：本地用Docker Compose跑通，K8s集群部署后，Context Assembler频繁报ConnectionRefusedError连不上Neo4j。

排查：

• K8s Service DNS解析正常，telnet neo4j 7687通。
• 但Pythonneo4j.GraphDatabase.driver连接超时。
• 原因：Neo4j Helm Chart默认配置dbms.connector.bolt.advertised_address=neo4j.default.svc.cluster.local:7687，而Driver尝试连接neo4j:7687（Service名），但advertised_address指向集群内DNS，Driver无法解析。

修复：

• 修改Helm values.yaml：dbms.connector.bolt.advertised_address=neo4j:7687
• 或在Driver连接字符串中指定auth=None，强制走Service IP。

实操心得：所有中间件连接，务必在K8s环境用`kubectl