常见报错排查

文档摘要

常见报错排查

本节摘要:按环境类、接入类、召回类、部署类组织的高频报错三列表(现象 → 可能原因 → 排查步骤)。出问题时先查这里,大部分常见错都能自助解决。复杂故障仍需回到对应章节理解原理后排查。

一、环境类(启动 / 连接)

现象	可能原因	排查步骤
服务起不来	端口被占 / Node 版本低 / 凭证缺失	查端口占用、`node -v` ≥ 22.16、确认两组凭证
控制台打不开(8125)	控制台服务没起 / 端口错	按启动顺序查控制台是否就绪
代理层无响应(8096)	代理层没起 / baseURL 错	确认 8096 监听、Agent 指向正确
抽取不工作	memory 组凭证错 / 核心服务异常	查核心服务日志、memory 组凭证

二、接入类(Agent 连不上 / 没记忆)

现象	可能原因	排查步骤
Agent 完全无响应	baseURL 指错 / 代理层没起	确认 8096 监听、baseURL 正确
Agent 响应但没记忆	密钥错(auth 失败)/ sessionInit 没完成	查代理日志 auth 步、是否触发表单
首次返回选择表单	sessionInit 正常流程(非故障)	选 team/agent/task,后续自动带
记忆没沉淀	extract 没触发 / 捕获失败	查代理日志 extract 步、控制台资产是否增
记忆沉淀没召回	Loadout 没绑定 / 可见性不允许	控制台查 Loadout 与可见性

三、召回类(记忆不准 / 慢 / 漏)

现象	可能原因	排查步骤
该召回的没召回	装配过滤掉了(没进候选集)	查 Loadout 绑定、可见性、状态
召回结果不准	抽取质量差 / 去重阈值不当	对照 L0 看 L1 抽取、查去重配置
召回重复	去重失效	查去重阈值是否太严
召回太慢(>200ms)	候选集太大 / 索引未优化 / 无超时兜底	收紧 Loadout、建好索引、配超时
上下文被挤爆	召回预算未配 / injection 全 inject	配条数/字符预算、易变内容用 toolize

四、部署类(生产 / 迁移)

现象	可能原因	排查步骤
v3 旧数据读不了	旧数据不带四元组	跑 v2→v3 迁移工具
跨团队数据串	隔离校验未生效	确认 v3 严格隔离、查四元组校验
费用失控	未配 TPM 限流	配 rateLimit 的 TPM 上限
系统常态跑 memory 存储	主后端(cos)未配好	查存储配置,主后端应常态跑 cos
跨域请求被拒	CORS 太严	限定前端域(别用 `*`,也别全拒)

五、排错主心骨:四节点分流

无论报什么错,先用第 1 章第 4 节的四节点分流图定位,再查上面对应表:


四节点分流(回忆第1章)
  沉淀了吗?(控制台资产增?)
   ├─ 否 → 抽取链路(核心服务/抽取Pipeline/凭证)→ 环境类/接入类表
   ├─ 是
      召回了吗?(使用计数增?)
       ├─ 否 → 召回引擎(检索/预算)→ 召回类表
       ├─ 是
          装配了吗?(绑定含该Agent?)
           ├─ 否 → 装配(Loadout/可见性)→ 接入类表
           ├─ 是
              对话对吗?
               ├─ 否 → 注入(代理injection)→ 接入类表
               └─ 是 → 全链路通过

六、排错通用建议

几个跨类别的通用建议:

建议	说明
先看日志	八步管道每步有日志,卡哪看哪(第 8 章)
用 trace	慢/故障用 traceId 串联定位(第 12 章)
分层查	召回不准先查装配(候选集)再查检索
备份再改	改配置/迁数据前必备份
对照 L0	记忆不准时,对照 L0 原话看 L1 抽取

💡 技巧:排错时最容易犯的错是「方向反」——比如召回不准去调检索参数,结果问题是装配过滤把该召回的挡在候选集外了。所以「四节点分流」先定位「卡在哪一层」,再查对应层的配置。方向对了,排错事半功倍。

本节要点回顾

四类报错:环境(启动连接)、接入(Agent 连不上)、召回(不准慢漏)、部署(生产迁移),各有表。
三列表:现象 → 可能原因 → 排查步骤,快速自助定位。
四节点分流:沉淀→召回→装配→注入,先定位卡在哪层再查表。
通用建议:先看日志、用 trace、分层查、备份再改、对照 L0。
方向优先:先定位「卡在哪层」再调,避免「方向反」白费功夫——附录与全书到此完成。