ScholarMuse 接进现有 AI 助手，先分清检索请求和数据回填两件事

ScholarMuse 接进现有 AI 助手后，排查顺序建议固定为：先确认助手有没有发起检索请求，再确认检索接口本身能不能返回论文条目，最后确认条目有没有被回填进对话上下文。把这三段混在一起反复改配置，通常只会让问题看起来时好时坏。下面给的是可以按日志、命令和页面行为逐项验证的做法；接口字段名、鉴权方式和返回结构需要结合你实际接入的 ScholarMuse 版本确认。

接入排查不要从改提示词开始。先在助手调用日志里找 tool_call、request_id 和 result_count，再用最小请求单独测检索，最后在上下文组装日志里核对 items 数量与最终提示词。三段各自有独立证据，缺一段就回到对应层处理；这套判断只适用于有可观察日志和可替换配置的环境。

在助手会话里确认这次提问有没有发出检索请求

助手回答里没有出现论文，不等于检索请求没发出。先看助手侧的调用痕迹，常见位置包括工具调用面板、函数调用日志、编排层 trace、网关访问日志和浏览器网络面板。关键字段建议重点看：工具名是否出现 ScholarMuse 相关调用，request_id 能否串起一次会话，入参 query 是否为空或被改写，status 是 success 还是 error，result_count 是否为 0。有 tool_call 且入参完整，说明请求已经发出；只有用户消息和模型回答，没有任何工具记录，才更接近“助手没调用”。

没有任何调用痕迹时，不要只改模型提示词。可以先确认工具是否注册到当前助手、是否被意图路由拦截、是否只在某个模式或某个入口启用，再发一条明确要求“调用 ScholarMuse 检索”的测试消息，观察是否出现工具记录。仍然没有记录时，查编排层的 outbound 请求和网络出口日志。这个顺序的边界是：它只能证明请求有没有发出，不能证明检索结果是否可用，后者要放到下一段单独测。

绕开助手，用一段最小请求单独测检索这条路

把检索能力从助手集成里拆出来。用 curl 或任意 HTTP 客户端直接请求 ScholarMuse，把占位符替换成你环境里的地址、令牌和测试查询。下面的路径和字段名只表示结构，实际接入时按接口文档或现有配置替换。

POST {SCHOLARMUSE_BASE_URL}/search
Authorization: Bearer {TOKEN}
Content-Type: application/json

{
  "query": "{TEST_QUERY}",
  "limit": 5,
  "fields": ["id", "title", "authors", "year", "abstract", "url"]
}

预期返回至少能看出请求标识、状态和条目数组。字段名可能与你实际接口不同，但结构应能对应到“这次请求有没有结果、结果里有什么”。

{
  "request_id": "{REQUEST_ID}",
  "status": "ok",
  "items": [
    {
      "id": "{PAPER_ID}",
      "title": "{TITLE}",
      "authors": ["{AUTHOR}"],
      "year": "{YEAR}",
      "abstract": "{ABSTRACT}",
      "url": "{URL}"
    }
  ]
}

判定这次请求成功，建议同时满足：HTTP 状态码为 2xx；返回体可以解析为 JSON；status 不是错误态；items 是数组；选一个你认为应当命中的宽泛测试查询时，items 数量大于 0；条目里至少有 id 或 url、title 这类后续可回填的字段。只看到 200 但 items 为空，不能算检索链路通过。这一步只验证检索接口，不验证助手有没有正确调用它。

核对返回的论文条目有没有被回填进对话上下文

检索成功但回答里没有论文，问题通常出在回填。回填发生在助手拿到工具返回之后、组装上下文之前：编排层把 items 转成消息、引用块或结构化上下文，再交给模型。可以在编排日志里找 tool_result 原文、上下文组装前后的 messages，以及最终提示词。重点看 items 的条数在进入上下文后有没有从 N 变成 0，以及 title、abstract、url、id 是否还保留。

字段与对话内容的对应关系要逐个核对：items[].title 是否进入引用标题，items[].abstract 是否被截断，items[].url 或 id 是否保留为引用标识。常见丢弃原因包括：token 预算截断、只保留前几条、去重或过滤条件过严、返回字段路径写错、异步调用没有等待结果、把对象数组当成字符串拼接时序列化失败。先看原始 tool_result 的条数，再看最终上下文里的条数；两次数量不一致，就优先定位到回填层，而不是继续改检索查询。

把这次的失败点写进一张分层对照表

把失败点固定成三层对照表，下一次按顺序看，不要跳层改配置。表里的判定依据都应当来自配置、日志、命令输出或页面行为。

层	观察点	判定依据	对应处理动作
助手侧	工具调用记录、trace、网关请求	有 tool_call 且入参完整，说明已发起；只有对话记录没有工具痕迹，说明未发起	查工具注册、意图路由、启用模式；补一条强制调用测试
检索侧	直连请求的 HTTP 状态、request_id、items	2xx 且 items 非空且字段可用，说明通过；2xx 空数组或解析失败，说明未通过	改测试查询、limit、fields；查鉴权、路径和参数名
数据回填侧	tool_result 条数与最终上下文条数	条数一致且字段进入上下文，说明通过；原始有结果、上下文没有，说明回填丢失	查截断阈值、字段映射、异步等待和序列化逻辑

下面这条失败走查记录按日志顺序走一遍，占位值在实际排查时替换成你的记录：

助手日志出现 tool_name=ScholarMuse.search，request_id=R1，query=Q1，status=success，result_count=0。说明请求已发出，但检索没有返回条目，先不要改回填。
直连同一 query=Q1，HTTP 200，status=ok，items=[]。检索侧也未通过；检查 query 是否需要英文、limit 是否被设成 0、fields 是否包含不存在的字段。
换宽泛查询 Q2 并设 limit=5，返回 items 3 条，含 id、title、abstract、url。检索侧通过。
回到助手发 Q2，tool_result 有 3 条，但最终上下文里只有 0 条。回填层未通过；查上下文组装是否只接受字符串、items 是否放在错误字段、是否被 token 截断。
修正映射后，最终上下文出现 3 条标题和 url，回答可以引用。此时才算整条链路走通。

这张表的价值在于把“助手没调用”“检索没结果”“结果没回填”分开。每次只改当前层能验证的配置，改完用同一段最小请求和同一条测试消息复测，避免下一次又从头猜。