1. 这不是“造轮子”，是重新校准Agent开发的认知坐标系
我从2023年夏天开始写第一个能跑通的Agent，到今天手头维护着7个生产级Agent服务——有给制造业客户做的设备故障诊断助手，有嵌入ERP系统的采购决策支持模块，也有在内部知识库上跑的工程师问答机器人。中间重写了4次核心调度器，推翻过3套记忆管理方案，光是插件注册机制就迭代了6版。标题里说的“14个设计决策”，不是罗列教科书式的最佳实践，而是我在凌晨三点盯着日志崩溃堆栈、反复回滚代码、对比17种框架文档后，用真实错误换来的判断刻度。比如“是否让Agent自己决定调用哪个插件”这个看似 trivial 的问题，我们曾因默认开启自主路由，在客户现场把采购单生成逻辑误触发成合同扫描OCR，导致下游系统收到一堆乱码PDF——这背后牵扯的是控制权边界、失败兜底策略、以及人类监督介入时机的三重权衡。
“通用内核”这个词被太多人挂在嘴边，但真正跑起来才发现：90%的所谓“通用”，只是把OpenAI API封装得更漂亮些；剩下10%，才是真正把状态机、上下文生命周期、工具调用契约、错误传播路径全部收束进一个可验证、可审计、可灰度的内核里。而“四种复利”，不是玄学概念——是当你把插件注册、记忆快照、执行链路、安全沙箱这四个模块真正解耦并标准化后，每新增一个业务场景，你付出的边际成本会指数级下降。上周给新上线的仓储温控Agent加功能，只用了47分钟：2分钟注册温感API插件，8分钟写完记忆模板，35分钟配置编排规则，2分钟上线灰度——因为内核已经替你扛住了所有底层摩擦。
如果你正卡在“为什么LangChain流程跑不通”、“Dify部署后插件总超时”、“CrewAI团队协作状态丢失”这类具体问题里，这篇内容会直接切到你报错日志的第3行；如果你刚读完《Agentic Design Patterns》想动手，这里会告诉你第2章讲的“Tool Calling Contract”在真实HTTP网关下怎么落地；如果你在评估Rust写的Agent框架是否值得投入，我会摊开内存模型和线程调度的实际开销数据。不谈愿景，只讲踩坑时鞋底沾的泥、调试时盯花的眼、上线后收到的第一条用户表扬截图——这才是Agent开发该有的样子。
2. 14个关键设计决策：每个选择背后都是血泪教训
2.1 决策1：Agent必须拥有明确的“身份主权”，而非依赖LLM输出伪造
很多初学者以为只要prompt里写“你是XX领域的专家”，Agent就真具备领域能力。我们曾用这种模式上线客服助手，结果用户问“上个月订单#A7892的物流异常原因”，Agent直接编造出一套“因台风导致中转仓临时关闭”的完整故事——它根本没查数据库，只是把训练数据里的台风案例套用过来。后来我们强制要求：所有领域知识声明（如“我可查询订单状态”）必须对应到内核中已注册的插件ID，且每次调用前校验插件可用性。当Agent声称“我能处理退货”，内核会立刻检查退货API插件是否在线、配额是否充足、认证token是否有效。这不是限制LLM自由发挥，而是把“承诺”和“履约能力”做硬绑定。实操中，我们在插件注册表里增加了一个capability_manifest字段，用JSON Schema描述该插件能处理的输入范围、输出结构、失败码映射，Agent生成的tool_call必须严格匹配此Schema，否则内核直接拦截并返回结构化错误。
提示：别信LLM自己说“我能做什么”，要让它用你定义的契约去证明。我们把这步校验放在LLM输出解析之后、插件调用之前，耗时<3ms，却避免了90%的幻觉型错误。
2.2 决策2：拒绝“单次Prompt全量决策”，采用分层决策流
早期版本把所有逻辑塞进一个超长prompt：“请分析用户意图→识别需调用的工具→生成参数→执行→整合结果→生成回复”。结果发现：当用户问“对比A/B/C三款服务器的CPU和内存参数，并推荐最适合视频渲染的”，LLM经常漏掉C款或混淆内存类型。后来拆成三层：
- 意图层：用轻量分类模型（TinyBERT微调）快速判定是“查询类”还是“操作类”，准确率99.2%；
- 工具路由层：基于意图+实体识别结果（如“A/B/C”是产品型号），查预建的工具路由表，命中率98.7%；
- 参数生成层：针对已选定的工具，用专用prompt模板填充参数，避免跨工具干扰。
这样改完，复杂查询成功率从63%升到94%，且各层可独立监控——比如发现路由层对新型号识别率下降，直接优化路由表，不用动LLM主模型。
2.3 决策3：插件必须声明“副作用等级”，内核据此实施执行锁
这是踩坑最深的一条。我们有个财务插件“生成付款凭证”，某次用户连续发了三条“付给供应商X 10万元”，内核没做任何并发控制，结果生成了三张重复凭证。后来定义副作用等级：
level: 0（无副作用）：如天气查询，可并发；level: 1（幂等）：如发送通知，多次调用结果相同；level: 2（强副作用）：如扣款、发货，必须串行且带业务唯一键（如订单号）。
内核在调度时，对level≥2的插件自动加分布式锁（Redis Lock），锁key包含插件ID+业务标识。现在“付款凭证”插件的锁粒度精确到“供应商ID+金额+时间窗口”，既防重复又不阻塞其他供应商操作。
2.4 决策4：记忆存储必须分离“事实记忆”与“过程记忆”
新手常把所有对话存进向量库，结果Agent记混了“张三的邮箱是zhang@abc.com”和“刚才用户让我把文件发给李四”。我们拆成两套存储：
- 事实记忆（Fact Memory）：结构化存储，用SQLite存实体关系（人/物/事/时间），支持SQL查询。比如“张三-邮箱-zhang@abc.com”存为三元组，更新时自动覆盖旧值；
- 过程记忆（Process Memory）：非结构化存储，用向量库存对话片段，但只存最近3轮+关键决策点（如“用户确认选择方案B”）。
内核在生成回复前，先查事实库获取确定信息，再用向量库召回相关上下文。测试显示，事实准确性提升82%，而向量检索延迟降低40%——因为不用再索引整段对话。
2.5 决策5：拒绝“全局Context Window”，按角色动态分配Token预算
LangChain默认把所有历史塞进context，很快爆Token。我们给每个Agent角色设预算：
- 协调者角色（负责整体流程）：占总预算40%，存关键决策点；
- 执行者角色（调用具体插件）：占30%，只存当前任务输入输出；
- 审核者角色（人工复核前最后检查）：占20%，存风险提示和原始证据；
- 归档者角色（存档用）：占10%，压缩后存冷存储。
内核在组装prompt时，按角色预算截断内容，并插入结构化标记如[COORDINATOR_DECISION: 选方案B]。这样16K模型能稳定支撑12轮深度交互，而不会因无关细节挤掉关键信息。
2.6 决策6：工具调用必须携带“可信度锚点”，而非裸调用
LLM生成的tool_call常含模糊参数，如{"product_id": "server-X"}。我们要求所有插件注册时声明参数校验规则，内核在调用前注入锚点：
- 对
product_id字段，自动追加{"source": "user_utterance", "confidence": 0.92}（来自NER模型）； - 若参数来自其他插件输出，则标记
{"source": "plugin_weather_v1", "confidence": 0.98}。
插件实现时可基于锚点做降级：当置信度<0.8时，返回建议列表而非强行执行。上线后，插件失败率下降67%，且错误日志能直接定位到是用户表述不清还是上游插件不准。
2.7 决策7：失败处理必须区分“可恢复错误”与“不可恢复错误”
最初所有错误都走统一fallback，结果用户问“查订单”失败后，Agent反复重试直到超时。现在内核内置错误分类器：
- 网络超时（可恢复）：自动重试3次，间隔指数退避；
- 参数校验失败（可恢复）：调用解释插件生成友好提示，如“您输入的订单号格式应为8位数字，请确认”；
- 权限不足（不可恢复）：立即终止流程，返回
{"error_type": "AUTH_REQUIRED", "action": "contact_admin"}，前端据此展示联系管理员按钮。
分类依据是插件注册时声明的error_schema，包含HTTP状态码、错误码前缀、重试策略。运维看板能实时统计各类型错误占比，精准定位瓶颈。
2.8 决策8：Agent状态必须支持“可序列化快照”，而非依赖内存
早期用内存存session，重启后用户对话全丢。后来设计快照协议：每次关键节点（如插件调用完成、用户确认）生成快照，内容包括：
state_hash: 当前状态MD5（用于冲突检测）；context_tree: 结构化上下文树（含各角色内存摘要）；pending_actions: 待执行操作队列（如“30秒后发提醒邮件”）。
快照存入PostgreSQL的jsonb字段，用ON CONFLICT DO UPDATE保证原子性。现在Agent可随时水平扩缩容，用户无感知——因为新实例加载快照后，从断点继续执行。
2.9 决策9：安全沙箱必须隔离“数据平面”与“控制平面”
我们曾因插件代码执行恶意SQL，导致数据库被清空。现在沙箱分两层：
- 数据平面沙箱：插件运行在Docker容器中，只允许访问指定DB连接池（预置只读账号），网络仅限白名单API；
- 控制平面沙箱：内核自身用Rust编写，所有插件调用通过gRPC接口，参数经Protobuf序列化，天然防注入。
关键创新是“控制指令签名”：内核下发的每个执行指令，都带HMAC-SHA256签名，插件容器启动时加载公钥验证。即使容器被攻破，也无法伪造内核指令。
2.10 决策10：插件注册必须强制“契约先行”，而非事后适配
很多团队先写插件再对接Agent，结果字段名不一致（如user_idvsuid）、错误码混乱。我们推行契约驱动：
- 插件开发者先提交OpenAPI 3.0 YAML，内核自动生成SDK和mock服务；
- 测试阶段用mock服务验证Agent调用逻辑；
- 上线时，内核校验实际API响应是否符合YAML契约。
这使插件接入周期从平均3天缩短到4小时，且0兼容性事故——因为契约就是法律。
2.11 决策11：用户反馈必须闭环到“决策权重调整”，而非仅存日志
以前收集用户点击“不满意”按钮，只存日志。现在内核实时解析反馈：
- 若用户修改Agent生成的参数（如把“数量：5”改成“数量：3”），则降低该参数生成模型的权重；
- 若用户跳过Agent推荐直接选第三项，则提升“推荐多样性”模块的权重。
权重存在Redis Hash中，每小时同步到模型微调流水线。三个月后，推荐采纳率从51%升至79%。
2.12 决策12：多Agent协作必须定义“角色契约”，而非自由协商
CrewAI式自由协作在复杂场景易死锁。我们定义角色契约：
- 发起者：有权创建任务，但无权修改他人输出；
- 执行者：可修改自己输出，但必须标注修改原因；
- 仲裁者：当冲突时，基于预设规则（如“执行者修改优先于发起者原始输入”）裁决。
契约存于ZooKeeper，各Agent启动时监听变更。上线后，跨Agent协作任务失败率从34%降至5%。
2.13 决策13：可观测性必须“原生嵌入”，而非后期加埋点
初期用Prometheus手动埋点，结果漏掉关键路径。现在内核所有模块（调度器、记忆管理、插件网关）都实现Tracer接口，自动注入trace_id。特别设计“决策链路图”：
- 每次用户请求生成一张DAG图，节点是决策点（如“路由到库存插件”），边是置信度；
- 点击节点可查看原始prompt、LLM输出、插件响应、耗时。
运维人员5秒内定位到是LLM解析慢还是插件响应慢，而不是翻三天日志。
2.14 决策14：升级必须支持“灰度决策流”，而非全量切换
新模型上线不敢直接切流。我们实现灰度：
- 将用户按哈希分桶，10%流量走新决策流；
- 新流中每个决策点记录“新旧模型输出差异”，如参数不同、工具选择不同；
- 差异率>5%时自动告警，人工审核后决定是否扩大灰度。
这让我们两周内安全上线了3个LLM版本，零业务中断。
3. 通用内核的四大复利引擎：如何让每次迭代都放大价值
3.1 复利引擎1：插件化架构——新增业务能力从“周级”到“分钟级”
真正的插件化不是把API包成函数，而是建立可组合的契约体系。我们内核的插件注册表长这样：
| 插件ID | 类型 | 输入Schema | 输出Schema | 副作用等级 | 超时(ms) | 认证方式 |
|---|---|---|---|---|---|---|
erp_order_query | HTTP | {order_id: string} | {status: enum, items: array} | 0 | 2000 | OAuth2 |
warehouse_stock_update | gRPC | {sku: string, delta: number} | {new_stock: number, timestamp: string} | 2 | 5000 | mTLS |
关键在输入/输出Schema——它们是JSON Schema，内核用jsonschema库实时校验。当要接入新系统“MES生产报工”，只需：
- 写YAML契约（15分钟）；
- 用内核CLI生成SDK（
agent-cli plugin-gen --spec mes.yaml）； - 实现SDK接口（Java/Python/Rust任选，2小时）；
- 注册插件（
agent-cli plugin-register --id mes_report --file mes.yaml）。
全程无需改内核代码，新插件自动出现在所有Agent的工具列表里。上周接入的MES插件，从需求提出到上线仅用37分钟——因为契约、SDK、注册流程全部标准化。
注意：插件ID必须全局唯一且语义化（如
mes_production_report_v2），避免plugin123这类ID。我们用{domain}_{function}_{version}命名法，方便审计和灰度。
3.2 复利引擎2：记忆抽象层——让“记住什么”和“怎么记住”彻底解耦
内核的记忆抽象层（Memory Abstraction Layer, MAL）是复利的核心。它把记忆操作变成标准接口：
class MemoryInterface: def store_fact(self, subject: str, predicate: str, object: str, ttl: int = 3600) -> None: ... def query_facts(self, subject: str, predicate: str) -> List[str]: ... def snapshot_process(self, session_id: str, context: dict) -> str: ... def load_snapshot(self, snapshot_id: str) -> dict: ...底层可替换存储：
- 开发环境用SQLite（轻量，支持全文搜索）；
- 生产环境用TiDB（分布式，强一致）；
- 归档用S3+Parquet（低成本，支持Spark分析）。
切换存储只需重写MAL实现，Agent代码零修改。更关键的是，MAL支持“记忆策略”： fact_ttl=86400：客户联系方式存1天；process_ttl=300：临时计算过程存5分钟；snapshot_retention=7：快照保留7天。
这些策略在插件注册时声明，内核自动执行。现在新增一个需要长期记忆的Agent（如法律顾问），只需在注册时设置fact_ttl=2592000（30天），其他一切照旧。
3.3 复利引擎3：执行链路编排——用DSL替代硬编码流程
早期用Python写流程逻辑，改一个分支就要发版。现在用内核自研的AgentFlow DSL：
name: "procure_approval_flow" steps: - id: "extract_req" plugin: "nlp_requirement_parser" input: "{{ user_input }}" - id: "check_budget" plugin: "erp_budget_check" input: "{{ extract_req.budget_code }}" if: "{{ extract_req.amount > 10000 }}" - id: "escalate" plugin: "notify_manager" input: "{{ extract_req }}" when: "{{ check_budget.result == 'REJECTED' }}" - id: "generate_po" plugin: "erp_po_generator" input: "{{ extract_req }}" depends_on: ["extract_req", "check_budget"]内核的Flow Engine会：
- 静态分析依赖关系，生成执行DAG；
- 动态注入上下文变量（
{{ }}语法）； - 自动处理错误分支（
when条件）； - 记录每步耗时和输出。
新增采购审批流程？写个YAML文件，agent-cli flow-deploy --file procure.yaml，5秒生效。我们已有47个业务流程DSL，平均每个流程迭代周期从2周缩短到1.2天。
3.4 复利引擎4：安全沙箱即服务——让合规成为默认选项
安全不是附加功能，是内核的呼吸。沙箱设计遵循“最小权限原则”：
- 网络沙箱：eBPF程序拦截所有outbound连接，只放行白名单域名（如
api.erp.com）； - 文件沙箱：插件容器挂载tmpfs，禁止写入宿主机；
- 计算沙箱：Rust内核用
wasmer运行WASM插件，内存隔离，CPU时间片限制。
更关键的是“安全策略即代码”：
# security_policy.yaml rules: - name: "no_external_db_access" scope: "plugin" condition: "plugin.id == 'legacy_payment'" action: "block" - name: "require_mfa_for_high_risk" scope: "user" condition: "user.risk_score > 0.8" action: "enforce_mfa"策略用OPA（Open Policy Agent）引擎执行，实时生效。当审计要求“禁止支付插件访问外部数据库”，运维只需改一行YAML，无需重启服务。这套沙箱已通过ISO 27001认证，客户尽调时直接出示策略文件即可。
4. 实操：从零构建你的第一个生产级Agent（以设备报修场景为例）
4.1 步骤1：定义核心契约——用OpenAPI规范你的第一个插件
假设你要做“设备报修Agent”，第一步不是写代码，而是定义报修API契约。创建repair_api.yaml：
openapi: 3.0.3 info: title: Equipment Repair API version: 1.0.0 paths: /v1/repair: post: summary: Submit equipment repair request requestBody: required: true content: application/json: schema: type: object properties: device_id: type: string description: "设备唯一编号，如EQUIP-2023-001" problem_desc: type: string description: "故障现象描述，最大200字" urgency: type: string enum: ["LOW", "MEDIUM", "HIGH", "CRITICAL"] default: "MEDIUM" required: ["device_id", "problem_desc"] responses: '200': description: Success content: application/json: schema: type: object properties: ticket_id: type: string description: "报修单号，如TICKET-2024-08765" estimated_fix_time: type: string format: date-time assignee: type: string '400': description: Invalid input content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: Error: type: object properties: code: type: string message: type: string这个YAML就是法律文件。内核会用它：
- 生成Python SDK（含类型提示）；
- 创建mock服务（
agent-cli mock-server --spec repair_api.yaml）； - 在Agent调用时校验输入输出。
为什么先契约？因为设备维修系统可能由不同团队维护，契约确保双方对“设备ID格式”、“紧急程度枚举值”等细节零歧义。我们吃过亏：前端传urgency: "high"（小写），后端只认"HIGH"，结果报修单全卡住。
4.2 步骤2：注册插件并配置安全策略
用内核CLI注册插件：
# 生成SDK（自动生成client.py） agent-cli plugin-gen --spec repair_api.yaml --lang python # 注册插件（内核自动校验契约） agent-cli plugin-register \ --id "equipment_repair" \ --type "http" \ --url "https://api.maintenance-system.com/v1" \ --auth "bearer" \ --spec "repair_api.yaml" # 设置安全策略：只允许设备ID以EQUIP-开头 agent-cli policy-set \ --policy "repair_device_id_format" \ --rule "input.device_id =~ '^EQUIP-\\d{4}-\\d{5}$'" \ --plugin "equipment_repair"内核立即生效策略。当Agent生成{"device_id": "ABC-123"}时，内核在调用前拦截并返回结构化错误：{"error": "DEVICE_ID_INVALID", "suggestion": "设备ID应以EQUIP-开头，后接4位年份和5位序号"}。这比让后端返回400 Bad Request友好得多。
4.3 步骤3：编写Agent流程DSL——聚焦业务逻辑，不碰基础设施
创建repair_flow.yaml：
name: "equipment_repair_agent" description: "处理设备故障报修请求" steps: - id: "parse_input" plugin: "nlp_device_parser" input: "{{ user_input }}" # 解析用户输入，提取device_id, problem_desc等 - id: "validate_device" plugin: "equipment_inventory_check" input: "{{ parse_input.device_id }}" # 检查设备是否在库，是否在保修期 - id: "submit_repair" plugin: "equipment_repair" input: | { "device_id": "{{ parse_input.device_id }}", "problem_desc": "{{ parse_input.problem_desc }}", "urgency": "{{ parse_input.urgency | default('MEDIUM') }}" } depends_on: ["parse_input", "validate_device"] - id: "notify_user" plugin: "sms_notifier" input: | { "phone": "{{ user.phone }}", "message": "报修单{{ submit_repair.ticket_id }}已提交，预计{{ submit_repair.estimated_fix_time }}修复" } depends_on: ["submit_repair"]部署流程：
agent-cli flow-deploy --file repair_flow.yaml --env production内核自动：
- 校验所有插件已注册；
- 构建DAG，检测循环依赖；
- 生成执行计划。
整个过程无需重启Agent服务，策略和流程热更新。
4.4 步骤4：配置记忆策略——让Agent记住关键事实
为报修Agent设置记忆：
# 设备信息存30天（事实记忆） agent-cli memory-policy-set \ --plugin "equipment_inventory_check" \ --fact-ttl 2592000 \ --scope "device_info" # 报修单号存7天（过程记忆） agent-cli memory-policy-set \ --plugin "equipment_repair" \ --process-ttl 604800 \ --scope "repair_ticket" # 快照保留14天 agent-cli snapshot-policy-set --retention 1209600内核自动应用策略。当用户问“我的报修单TICKET-2024-08765处理到哪步了”，Agent先查事实库（设备信息），再查过程记忆（该单号状态），最后用快照恢复上下文。所有存储细节对Agent透明。
4.5 步骤5：上线与灰度——用数据驱动发布决策
首次上线，用灰度策略：
# 1%用户走新流程 agent-cli traffic-split --flow "equipment_repair_agent" --percentage 1 # 监控关键指标 agent-cli metrics-watch \ --flow "equipment_repair_agent" \ --metrics "success_rate, avg_latency, error_types"内核仪表盘实时显示：
- 成功率98.2%（目标≥95%）；
- 平均延迟1.2s（目标≤2s）；
- 错误类型中
DEVICE_ID_INVALID占82%（说明用户常输错ID）。
于是我们： - 优化
nlp_device_parser插件，增加ID格式提示； - 将灰度比例提到5%，验证改进效果；
- 一周后全量上线。
整个过程像开飞机——所有操作都有仪表盘数据支撑，不靠感觉。
5. 常见问题排查手册：那些让你抓狂的错误，其实有标准解法
5.1 问题1：Agent调用插件后无响应，日志显示“RPC timeout”
典型现象：
- 内核日志：
[ERROR] PluginCallTimeout: equipment_repair timeout after 5000ms - 插件容器日志：空白或只有启动日志
排查路径：
查网络连通性：
# 进入内核容器，测试到插件容器的连通性 curl -v http://equipment-repair-service:8000/health # 如果超时，检查K8s Service配置或Docker网络查插件健康检查：
- 确认插件实现了
/health端点，返回{"status": "ok"}； - 内核默认每30秒调用一次，失败3次则标记插件离线。
- 确认插件实现了
查超时配置：
- 检查插件注册时的
timeout值（本例设5000ms）； - 查插件自身超时设置（如Python requests的
timeout=(3, 3)）； - 关键点：插件超时必须小于内核超时，否则内核先杀进程。
- 检查插件注册时的
根治方案：
- 在插件容器内启用
tcpdump抓包，确认请求是否发出； - 用
agent-cli plugin-status --id equipment_repair查看实时状态； - 我们最终发现是插件容器DNS解析慢，改用
--dns=1.1.1.1启动参数解决。
5.2 问题2：Agent生成的tool_call参数格式错误，如{"device_id": null}
典型现象：
- 内核日志：
[WARN] PluginInputValidationError: equipment_repair input validation failed: device_id is null - LLM输出中
device_id字段为空
排查路径：
查LLM输出解析：
- 内核解析LLM输出时，用正则提取JSON，但LLM有时输出
{"device_id": ""}（空字符串）； - 检查
nlp_device_parser插件的输出Schema，是否允许空值。
- 内核解析LLM输出时，用正则提取JSON，但LLM有时输出
查插件契约：
- 打开
repair_api.yaml，确认device_id字段required: true； - 内核校验时，空字符串视为缺失，触发
400错误。
- 打开
根治方案：
- 在
nlp_device_parser插件中增加后处理：空字符串转为None，触发LLM重试； - 更优解：在DSL中加校验步骤：
- id: "validate_device_id" plugin: "string_validator" input: "{{ parse_input.device_id }}" if: "{{ parse_input.device_id == '' }}" then: "retry_with_prompt: 请提供设备编号，格式如EQUIP-2023-001"
5.3 问题3：多用户并发时，Agent记混了A用户的设备ID和B用户的设备ID
典型现象：
- 用户A问“EQUIP-2023-001故障”，Agent回复“已提交报修单”；
- 用户B紧接着问“EQUIP-2023-002故障”，Agent却回复“EQUIP-2023-001的报修单已处理”
排查路径：
查记忆作用域：
- 确认
store_fact调用时是否传入session_id； - 默认
session_id来自HTTP HeaderX-Session-ID，若前端未传，则所有用户共享同一session。
- 确认
查快照加载：
- 检查
load_snapshot是否用对session_id； - 我们曾因Redis Key拼写错误（
snap:{sid}写成snap:{session_id}），导致加载错快照。
- 检查
根治方案：
- 强制前端在请求头传
X-Session-ID（UUID v4）； - 内核中间件自动注入
session_id到所有插件调用上下文； - 在仪表盘加“跨Session污染”告警，当同一
device_id出现在不同session_id的记忆中时触发。
5.4 问题4：升级新LLM后，Agent开始频繁调用错误插件
典型现象：
- 旧模型：用户问“查订单”，95%路由到
erp_order_query； - 新模型：同一问题，40%路由到
weather_api
排查路径：
查路由层输入：
- 内核路由层输入是LLM输出的
tool_calls数组； - 用
agent-cli trace-last --session xxx查看新模型输出的tool_calls，发现weather_api被错误调用。
- 内核路由层输入是LLM输出的
查LLM prompt一致性：
- 新模型prompt中遗漏了
Available tools: [erp_order_query, ...]部分； - 或temperature设太高（0.8），导致随机性增强。
- 新模型prompt中遗漏了
根治方案：
- 所有LLM调用必须带
system_prompt模板，内核自动注入工具列表； - 灰度时，对比新旧模型的
tool_calls分布，用卡方检验（Chi-square test）判断是否显著差异； - 我们发现新模型对
weather_api的偏好源于训练数据偏差，于是加了一条路由规则：if intent=="query" and entity_type!="weather" then exclude weather_api。
5.5 问题5：插件返回敏感数据（如用户手机号），被意外记录到日志
典型现象：
- 日志中出现
{"phone": "138****1234", "message": "..."}； - 审计要求所有PII数据必须脱敏。
排查路径：
查日志级别：
- 内核默认INFO日志记录插件输入输出；
- 敏感字段需在插件注册时声明。
查脱敏策略：
- 内核支持
redact_fields配置，如["phone", "id_card"]； - 但需插件在响应中用标准字段名。
- 内核支持
根治方案：
- 在
repair_api.yaml中，为phone字段加x-redact: true扩展； - 内核自动识别并脱敏：
"phone": "138****1234"； - 更严格：用Vault动态生成临时令牌，插件返回
phone_token: "tok_abc123"，内核用令牌换真实号码。
6. 我的实战体会：复利不是等来的，是设计出来的
写完这篇，我打开终端看了眼今天的Agent监控面板：
- 新接入的MES插件，0错误，平均延迟320ms；
- 报修流程成功率99.1%，比上周提升0.3个百分点；
- 安全策略拦截了17次非法设备ID尝试，全部来自测试环境——说明策略生效
