OpenViking 动态查询配置变更与测试报告

日期：2026-06-04 分支：feat/sharClawWithOpenViKing 仓库：iaasng/arkclaw-openviking-plugin 结论：本次动态查询配置能力、URI 详情 API、最近 ov_search 简化清单 API 已完成实现与二次验收；全量测试、类型检查、生产构建、生产风格稳定性模拟均通过。

1. 本次变更总结

本次变更围绕 OpenViking 插件的“查询参数运行期动态配置”展开，目标是支持不重启 OpenClaw 即可调整召回数量、候选数量、阈值、资源范围和排序权重，并支持 claw 与 session 两级粒度。整体能力由新增运行期配置存储、召回链路接入、命令入口、Gateway 查询接口和测试保障共同组成。

1.1 核心能力

1.2 本次重点修复

2. 新增动态配置规则

2.1 生效优先级

每次自动召回、memory_recall、ov_search 执行前都会生成一次有效配置。字段级优先级如下：

request 覆盖参数
  > session 运行期配置
  > claw 运行期配置
  > plugins.entries.openviking.config 静态配置
  > 代码默认值

说明：

• request 级参数只影响当前调用，不写入运行期配置。
• session 级配置只影响当前会话，优先匹配 ovSessionId，再匹配 sessionId，最后匹配 sessionKey。
• claw 级配置以当前 agentId 为作用域，影响该 claw 下后续所有 session。
• sources 会标记字段来源，便于排查“为什么当前召回数量/阈值/权重是这个值”。

2.2 字段合并规则

2.3 支持字段与范围

2.4 持久化与热加载

运行期配置可以配置持久化路径：

{
  "plugins": {
    "entries": {
      "openviking": {
        "config": {
          "runtimeQueryConfigPath": "/path/to/runtime-query-config.json"
        }
      }
    }
  }
}

文件结构：

{
  "schemaVersion": "1.0",
  "updatedAt": 1780520000000,
  "claws": {
    "main": {
      "params": { "recallLimit": 8, "candidateLimit": 80 },
      "updatedAt": 1780520000000,
      "updatedBy": "command",
      "agentId": "main"
    }
  },
  "sessions": {
    "session:oc-session-123": {
      "params": { "scoreThreshold": 0.08 },
      "updatedAt": 1780520000000,
      "updatedBy": "command",
      "agentId": "main"
    }
  }
}

3. 使用方式

3.1 查看当前有效配置

/ov-query-config get --scope session

返回内容包含：

• scope：当前查看的作用域。
• effective：合并后的最终配置。
• effective.sources：字段来源，如 session / claw / static / default。
• effective.warnings：归一化或降级警告。

3.2 设置 claw 级默认召回策略

/ov-query-config set --scope claw \
  --recallLimit 4 \
  --candidateLimit 40 \
  --scoreThreshold 0.2 \
  --resourceTypes user,agent

效果：当前 claw 下所有 session 默认继承该配置；session 级配置仍可覆盖。

3.3 设置 session 级临时策略

/ov-query-config set --scope session \
  --recallLimit 10 \
  --candidateLimit 80 \
  --scoreThreshold 0.08 \
  --resourceTypes resource,user

效果：仅当前 session 生效，不影响同 claw 下其他 session。

3.4 调整排序权重

/ov-query-config set --scope claw \
  --weight baseScore=0.8,leaf=0.2,preference=0.18,event=0.04,lexicalOverlapMax=0.25 \
  --categoryWeight preferences=0.3,events=-0.1 \
  --resourceTypeWeight user=0.2,resource=0.1

说明：

• --weight 对应 rankingWeights。
• --categoryWeight 对应 categoryWeights。
• --resourceTypeWeight 对应 resourceTypeWeights。
• 权重只影响插件客户端侧排序，不改变 OpenViking 服务端搜索算法。

3.5 清理字段覆盖

/ov-query-config unset recallLimit scoreThreshold rankingWeights --scope session

效果：删除当前 session 的指定字段覆盖，下一次查询回退到 claw 或静态配置。

3.6 重置作用域配置

/ov-query-config reset --scope session
/ov-query-config reset --scope claw

效果：删除该作用域整条运行期配置。

4. API 接口整理

4.1 GET /api/openviking/uri-detail

用途：按完整 viking:// URI 查询详情和正文片段。该接口只调用读取能力，不重新发起搜索。

请求示例

curl --get 'http://127.0.0.1:<gateway-port>/api/openviking/uri-detail' \
  --data-urlencode 'uri=viking://resources/project/spec.md' \
  --data 'includeContent=true' \
  --data 'contentLimit=12000' \
  --data 'offset=0'

Query 参数

响应字段

状态码

4.2 GET /api/openviking/recall-traces/latest-ov-search-list

用途：获取当前会话最近一次 ov_search trace 的扁平化 URI 清单，方便前端展示“上次搜索到了哪些资源”。该接口不会重新发起 ov_search。

请求示例

curl --get 'http://127.0.0.1:<gateway-port>/api/openviking/recall-traces/latest-ov-search-list' \
  --data-urlencode 'sessionId=oc-session-123' \
  --data 'limit=20' \
  --data 'includeSelected=true' \
  --data 'dedupe=true'

Query 参数

响应字段

状态码

5. 本次测试范围

5.1 覆盖范围

5.2 未执行范围说明

仓库中的 Python e2e 脚本依赖真实 OpenClaw Gateway、OpenViking 服务、LLM 后端和有效 token。当前本地验收环境未提供这些外部运行前提，因此本次未执行会访问真实外部服务的 Python e2e。对应风险已通过全量 Vitest、真实 server 单测、生产风格稳定性模拟和 install dry-run 覆盖本次变更相关链路。

6. 测试用例执行情况

6.1 聚焦回归测试

6.2 全量测试 / 类型 / 构建

6.3 生产风格稳定性模拟

验证命令覆盖以下行为：

1. load() 与 set() 并发时，写操作等待初始加载，不会被旧文件覆盖。
2. 100 个 session 并发写入后，session 与 claw 配置仍按优先级正确合并。
3. 配置文件被破坏为非法 JSON 后，reloadIfChanged({ force: true }) 保留 last known-good 内存配置。
4. 持久化路径临时不可写导致一次写入失败后，修复路径后下一次写入可以恢复。
5. install.sh dry-run 对包含单引号的 URL/API key 不崩溃，resource-only recall 配置输出正确。

执行结果：

production-style runtime config stability check passed: in-flight load serialization + 100 concurrent session writes + corrupt-file recovery + write-queue recovery

7. 质量与风险结论

7.1 已关闭风险

• 动态配置优先级已通过单测与场景测试验证。
• candidateLimit 显式配置优先级已修复并回归。
• 权重参数 CLI 设置已补齐。
• 空 patch 不再覆盖已有配置。
• 持久化写入采用临时文件 + rename，写队列失败后可恢复。
• 配置文件损坏时保留 last known-good，不影响查询链路。
• install.sh 的 JSON 参数与 env 单引号转义均已覆盖。

7.2 后续建议

8. 最终结论

本次变更已完成“OpenViking 查询参数动态配置”主链路：支持 claw/session 粒度、支持运行期即时生效、支持配置持久化与热加载、支持召回数量/候选数量/阈值/资源类型/排序权重调整，并新增 URI 详情与最近 ov_search 简化清单 API。经过二次验收和追加复审后，发现的问题均已修复，当前自动化验证全部通过，可以进入提测/评审阶段。