OpenViking Recall Trace API 使用文档

面向插件使用者、排障同学和集成方，专门说明 OpenViking OpenClaw 插件中与 recall trace 相关的配置、Agent 工具、Slash 命令、Gateway HTTP API、返回结构和排障方式。

1. 功能概览

Recall Trace 是 OpenViking 插件的召回可观测能力。启用后，插件会把每一次自动召回、显式记忆召回、资源搜索、归档搜索记录成结构化 trace，便于回答以下问题：

• 本轮到底搜索了哪些语义召回范围：resource、user、agent？归档搜索会单独记录为 session archive trace。
• 每个范围请求的目标 URI、limit、阈值和耗时是多少？
• 候选结果有哪些？最终哪些被注入 prompt 或展示给用户？
• 为什么没有召回？是低于分数阈值、预算不足，还是搜索失败？
• Gateway 重启后，是否还能从 JSONL 持久化文件查到近期 trace？

核心实现位于 recall-trace.ts:20、index.ts:704、index.ts:774 和 index.ts:784。

2. 启用方式与配置项

2.1 最小启用配置

关键点：必须显式设置 traceRecall: true。只配置 recallResources 或 recallTargetTypes 只会改变召回范围，不会启用 trace 记录。

{
  "plugins": {
    "entries": {
      "openviking": {
        "config": {
          "traceRecall": true
        }
      }
    }
  }
}

traceRecall 在配置解析中只有等于布尔值 true 才会启用：config.ts:430。插件注册阶段也只有启用后才创建 RecallTraceRecorder：index.ts:704。

2.2 推荐排障配置

{
  "plugins": {
    "entries": {
      "openviking": {
        "config": {
          "traceRecall": true,
          "traceRecallPersist": true,
          "traceRecallDir": "~/.openclaw/openviking/recall-traces",
          "traceRecallRetentionDays": 14,
          "traceRecallMaxEntries": 1000,
          "traceRecallMaxResultsPerSearch": 20,
          "traceRecallPreviewChars": 240,
          "traceRecallQueryMaxChars": 4000,
          "traceRecallQueryMaxDays": 14,
          "recallTargetTypes": ["user", "agent", "resource"]
        }
      }
    }
  }
}

2.3 Trace 配置项

2.4 召回范围配置与 Trace 的关系

Trace 会记录实际召回范围，但召回范围本身由 recallTargetTypes / recallResources 决定：

目标类型会被解析为以下搜索计划：resolveRecallSearchPlan 实现见 recall-trace.ts:141。

Session history is not a semantic recall target because the server does not vector-index session archives. Use ov_archive_search and ov_archive_expand for exact session-history recovery.

3. Trace 记录来源

4. Trace 数据结构

4.1 RecallTraceEntry

RecallTraceEntry 的完整类型定义在 recall-trace.ts:20。

4.2 searches[]

字段定义见 recall-trace.ts:37。

4.3 results[]

字段定义见 recall-trace.ts:10。

4.4 selected[]

字段定义见 recall-trace.ts:50。

4.5 返回示例

{
  "schemaVersion": "1.0",
  "traceId": "ov_search-1780329600000-a1b2c3d4",
  "ts": 1780329600000,
  "sessionId": "test-session",
  "sessionKey": "agent:main:example",
  "ovSessionId": "8d6e...",
  "agentId": "main",
  "source": "ov_search",
  "operationType": "semantic_find",
  "resourceTypes": ["resource"],
  "trigger": {
    "query": "OpenViking trace API"
  },
  "searches": [
    {
      "resourceType": "resource",
      "targetUriInput": "viking://resources",
      "targetUriResolved": "viking://resources",
      "limit": 20,
      "scoreThreshold": 0,
      "durationMs": 35,
      "total": 1,
      "results": [
        {
          "uri": "viking://resources/project/spec.md",
          "resourceType": "resource",
          "score": 0.88,
          "abstractPreview": "Recall trace design spec",
          "resultType": "resource"
        }
      ]
    }
  ],
  "selected": [
    {
      "uri": "viking://resources/project/spec.md",
      "resourceType": "resource",
      "score": 0.88,
      "abstractPreview": "Recall trace design spec",
      "displayed": true
    }
  ],
  "stats": {
    "candidateCount": 1,
    "selectedCount": 1,
    "injectedCount": 0
  }
}

5. Agent 工具：ov_recall_trace

5.1 用途

ov_recall_trace 用于在 Agent 内部查询已记录的 trace。它不会重新调用 OpenViking 搜索接口，只查询插件记录；仅当传入 includeContent: true 或配置了 traceRecallIncludeContentByDefault: true 时，才会额外调用 OpenViking read 给 selected 结果补充内容预览。工具注册见 index.ts:1637。

5.2 参数

参数类型定义见 index.ts:167，工具参数声明见 index.ts:1642。

当前接口不支持自由文本模糊查询 trace trigger。需要按 source、sessionId、ovSessionId、resourceTypes、traceId 或时间范围过滤。

5.3 调用示例

查询当前 session 最新一条 trace：

{
  "turn": "latest"
}

查询当前 session 内最近 10 条 ov_search trace：

{
  "turn": "all",
  "source": "ov_search",
  "limit": 10
}

查询某条 trace 并补充 selected 内容预览：

{
  "traceId": "ov_search-1780329600000-a1b2c3d4",
  "includeContent": true
}

按时间范围和召回类型查询：

{
  "turn": "all",
  "resourceTypes": ["user"],
  "since": 1780320000000,
  "until": 1780406399999,
  "limit": 50
}

5.4 返回值

工具返回 OpenClaw ToolResult：

{
  "content": [
    {
      "type": "text",
      "text": "## Trace 1: ov_search\ntraceId: ...\nquery: ..."
    }
  ],
  "details": {
    "action": "queried",
    "count": 1,
    "lookupLayer": "memory",
    "warnings": [],
    "entries": []
  }
}

6. Slash 命令：/ov-recall-trace

6.1 用途

用户可以在 OpenClaw 会话中直接执行 /ov-recall-trace 查询 trace。命令注册见 index.ts:1676。

6.2 参数

Slash 命令使用 --kebab-case 参数，解析逻辑见 index.ts:1687。

6.3 示例

/ov-recall-trace --turn all --source auto_recall --limit 5

/ov-recall-trace --trace-id ov_search-1780329600000-a1b2c3d4 --include-content

/ov-recall-trace --turn all --resource-types user,agent --since 1780320000000 --until 1780406399999

6.4 返回值

Slash 命令返回：

{
  "text": "## Trace 1: auto_recall\ntraceId: ...",
  "details": {
    "count": 1,
    "lookupLayer": "memory",
    "warnings": [],
    "entries": []
  }
}

返回结构与 ov_recall_trace 的 details 基本一致；text 是人类可读摘要，details.entries 是机器可读数据。

7. Gateway HTTP API

插件 service 启动时会尝试注册 Recall Trace Gateway 路由：index.ts:2540。如果当前 Gateway 不支持 route adapter，日志会提示使用 ov_recall_trace 工具或 /ov-recall-trace 命令替代：index.ts:2548。

7.1 GET /api/openviking/recall-traces

用途

查询多条 trace。路由注册见 index.ts:830。

Query 参数

请求示例

curl 'http://127.0.0.1:<gateway-port>/api/openviking/recall-traces?turn=all&source=ov_search&limit=10'

curl 'http://127.0.0.1:<gateway-port>/api/openviking/recall-traces?turn=all&resourceTypes=user,agent&since=1780320000000&until=1780406399999'

返回值

Handler 返回结构见 index.ts:812。

{
  "status": 200,
  "body": {
    "ok": true,
    "entries": [],
    "lookupLayer": "memory",
    "warnings": []
  }
}

根据 Gateway 适配层，客户端通常会看到 body 中的 JSON：

{
  "ok": true,
  "entries": [],
  "lookupLayer": "memory",
  "warnings": []
}

7.2 GET /api/openviking/recall-traces/:traceId

用途

按 traceId 查询单条 trace。路由注册见 index.ts:831。

Path 参数

Query 参数

除 traceId 外，支持与列表接口相同的 query 参数，例如 includeContent=true。

请求示例

curl 'http://127.0.0.1:<gateway-port>/api/openviking/recall-traces/ov_search-1780329600000-a1b2c3d4?includeContent=true'

返回值

{
  "ok": true,
  "entries": [
    {
      "traceId": "ov_search-1780329600000-a1b2c3d4",
      "source": "ov_search"
    }
  ],
  "lookupLayer": "memory",
  "warnings": []
}

8. 查询与存储行为

8.1 内存 Ring Buffer

• RecallTraceMemoryStore 保存最近 N 条 trace，N 由 traceRecallMaxEntries 控制。
• 超出容量时删除最旧记录。
• 查询时先过滤，再按 ts 降序排序。
• turn: 'latest' 返回过滤结果中最新一条；turn: 'all' 返回最多 limit 条。

实现见 recall-trace.ts:172、recall-trace.ts:187。

8.2 JSONL 持久化

启用 traceRecallPersist: true 后，每条 trace 会追加到 traceRecallDir/YYYY-MM-DD.jsonl。

• 文件名使用 trace 的 UTC 日期：recall-trace.ts:214。
• 默认不会持久化 trigger.rawUserTextPreview，除非设置 traceRecallIncludeRawUserPreview: true：recall-trace.ts:271。
• 查询时如果内存命中，直接返回内存结果；只有内存未命中且存在持久化 store，才 fallback 扫描 JSONL：recall-trace.ts:431。
• JSONL 中的损坏行会被跳过，并返回 warning：recall-trace.ts:373。

8.3 includeContent 行为

默认 trace 只保存摘要预览，不读取完整内容。查询时开启 includeContent 后，插件会对每个 selected[].uri 调用 OpenViking read，并把结果压缩到 selected[].contentPreview：index.ts:747。

建议只在定位具体 trace 时使用 includeContent，避免一次查询大量 trace 触发额外读请求。

9. 常见使用场景

9.1 解释为什么自动召回没有注入记忆

1. 打开 trace：traceRecall: true。
2. 复现一轮会话。
3. 查询最新自动召回：

/ov-recall-trace --source auto_recall

重点查看：

• searches[].error 是否有搜索失败。
• searches[].total 是否为 0。
• stats.candidateCount、stats.selectedCount、stats.injectedCount 是否逐步变少。
• trigger.queryTruncated 是否为 true。

9.2 查看显式 memory_recall 查了哪些空间

/ov-recall-trace --turn all --source memory_recall --limit 5

重点查看 resourceTypes、searches[].contextType 和 searches[].targetUriResolved，确认是否使用 context_type=memory / context_type=resource，或是否按请求 resourceTypes 改变范围。

9.3 排查 /ov-search 或 ov_search 为什么结果不符合预期

/ov-recall-trace --turn all --source ov_search --include-content --limit 3

重点查看：

• trigger.query 是否与预期一致。
• searches[].targetUriInput 是否是正确资源目录。
• results[] 候选是否包含预期文档但未进入 selected[]。
• selected[].contentPreview 是否能读到真实内容。

9.4 排查归档搜索没有命中

/ov-recall-trace --turn all --source ov_archive_search --limit 5

重点查看：

• operationType 是否为 archive_grep。
• searches[].targetUriResolved 是否指向正确 session history 或 archive。
• searches[].caseInsensitive 是否为 true。
• stats.candidateCount 与 selected[].line。

10. 错误与排障

11. 测试覆盖

相关单元测试集中在：

• tests/ut/recall-trace.test.ts:56：召回类型归一化、搜索计划、内存 ring buffer、JSONL 持久化、隐私控制。
• tests/ut/tools.test.ts:1021：ov_recall_trace 工具、Slash 命令、Gateway 路由、includeContent、显式召回 trace、查询不重新触发搜索。

建议修改 trace 行为后至少运行：

npm run typecheck
npm test -- tests/ut/recall-trace.test.ts tests/ut/tools.test.ts

12. 快速参考

开启 trace

{
  "traceRecall": true,
  "traceRecallPersist": true
}

查最新 trace

/ov-recall-trace

查最近 10 条自动召回

/ov-recall-trace --turn all --source auto_recall --limit 10

查指定 trace 详情

/ov-recall-trace --trace-id <traceId> --include-content

HTTP 查询

curl 'http://127.0.0.1:<gateway-port>/api/openviking/recall-traces?turn=all&source=memory_recall&limit=10'

HTTP 查询单条

curl 'http://127.0.0.1:<gateway-port>/api/openviking/recall-traces/<traceId>?includeContent=true'