为Fix-System-Agent实现工具调用的幂等性与请求去重层

背景痛点

在当前 Agent 排障流程中，大模型存在典型的重试发散问题：当工具调用超时、返回异常、上下文截断时，模型很容易自主重复生成相同参数的工具请求。
带来几个典型问题：

1. 写类工具（变更配置、重启服务、清理资源）被重复执行，引发二次故障；
2. 读类工具重复调用，拉高监控、API、脚本的 QPS，浪费资源；
3. 证据链里出现大量重复日志，干扰后续基线对比、事实隔离模块的判断；
4. 现有的降级策略只处理失败结果，没有拦截重复请求，容易形成“失败→重试→再失败”循环。

单纯依赖业务工具自身实现幂等，成本很高：很多存量运维脚本、系统接口并没有唯一流水号、重复校验逻辑，Agent 层需要统一兜底。

核心设计思路

在工具网关之前，增加独立的幂等&去重中间层，作为请求的第一道拦截切面，不侵入原有工具实现。
核心是为每一次工具调用生成稳定的请求指纹，结合会话生命周期做去重判断。

1. 请求指纹生成规则

指纹由多维度哈希构成：

fingerprint = hash(agent_session_id + tool_name + sorted(parameters_kv) + 操作类型标记)

• agent_session_id：绑定本次排障会话，不同会话之间不去重；
• tool_name：目标工具标识；
• sorted(parameters_kv)：参数键值对排序后序列化，规避 JSON key 顺序不一致导致指纹不一致；
• 操作类型标记：区分只读查询 / 变更写入，做差异化策略。

关键点：不使用 LLM 输出原始字符串直接哈希，避免模型换行、空格扰动造成相同语义请求指纹不同。

2. 分层去重策略

缓存存储选用轻量化 KV，持久化到会话快照存储，和之前的会话快照模块打通，会话销毁时自动清理指纹记录，避免内存持续膨胀。

3. 命中去重后的返回协议

不能简单返回“重复请求”，需要给大模型足够的引导信息，防止模型误解为工具报错：

{
  "code": "DUPLICATE_REQUEST",
  "msg": "该工具请求在当前会话内已执行，无需重复调用",
  "fingerprint": "xxx",
  "last_result": {...上一次返回结果...},
  "suggestion": "请基于已有结果继续分析，或调整查询条件"
}

模型拿到这个结构，可以复用旧结果继续推理，而不是直接触发失败降级、再次重试。

和现有模块联动

1. 参数语义校验层：先校验参数合法性，合法请求才进入指纹计算与去重；
2. 证据链管理模块：所有命中去重、拦截、放行事件，都写入证据链，标注拦截原因；
3. 自动降级策略：区分 DUPLICATE_REQUEST 和真实执行失败，不触发重试降级；
4. 基线对比模块：减少重复采集的数据，降低基线计算的噪声。

工程权衡

1. 指纹碰撞风险：哈希冲突概率极低，可增加可选的二次参数比对开关，高风险变更场景开启；
2. 动态参数场景：时间戳、随机 token 这类动态参数会破坏指纹，支持配置参数忽略列表，计算指纹时剔除；
3. 主动刷新机制：支持 Agent 显式声明“需要强制刷新数据”，携带 force_refresh=true 绕过去重；
4. 运维可观测：新增指标 agent_duplicate_request_total，按工具名、操作类型统计拦截量，方便发现模型高频重复调用的 bad case。

后续演进方向

• 支持语义级去重：不仅仅匹配参数指纹，对语义等价、只是话术写法不同的同类查询做识别（依赖轻量嵌入向量）；
• 支持自定义幂等TTL：允许工具在注册元信息里单独配置去重窗口；
• 审计报表：导出会话内所有被拦截的重复操作，用于评估 Agent 推理稳定性。

小结

幂等去重层不是解决 Agent 幻觉本身，而是一道安全兜底防线：把模型无节制重试带来的风险收敛在网关侧。结合前面的语义校验、证据隔离、基线对比、自动降级，整套工具调用链路从“直接执行”变成一条有校验、有隔离、有防护、可追溯的可控流水线。