Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
test(openclaw): cover install contracts and runtime docs (#2647)
Mingjian Que2d130feb6234
diff --git a/examples/openclaw-plugin/README.md b/examples/openclaw-plugin/README.mdindex 34bdd2f81..dd1f7399f 100644--- a/examples/openclaw-plugin/README.md+++ b/examples/openclaw-plugin/README.md@@ -75,6 +75,9 @@ openclaw config get plugins.slots.contextEngine # should output: openviking| [INSTALL-ZH.md](./INSTALL-ZH.md) | Chinese install guide || [INSTALL-AGENT.md](./INSTALL-AGENT.md) | Agent-oriented operator guide || [docs/openviking-openclaw-plugin-guide.md](./docs/openviking-openclaw-plugin-guide.md) | Comprehensive Chinese guide for usage, configuration, debugging, testing, build, release, deployment, and rollback |+| [docs/openviking-websocket-rpc-api.md](./docs/openviking-websocket-rpc-api.md) | Gateway WebSocket RPC usage for OpenViking tools |+| [docs/openviking-runtime-query-config.md](./docs/openviking-runtime-query-config.md) | Runtime query config scopes, fields, and commands |+| [docs/openviking-install-package-contract.md](./docs/openviking-install-package-contract.md) | Package and install contract verification notes |> **Plugin vs Skill**: This page is for `@openviking/openclaw-plugin` (the context-engine plugin). Do **not** use `clawhub install openviking` — that installs a different AgentSkill.@@ -144,7 +147,7 @@ In this setup:### User namespace-The plugin writes and searches user-scoped memory through `viking://user/...`; OpenViking resolves that alias from the request tenant and actor-peer context. `viking://agent/...` is deprecated by OpenViking and is not used by the plugin.+The plugin writes and searches user-scoped memory through `viking://user/...`; OpenViking resolves that alias from the request tenant and actor-peer context. Deprecated agent URI paths are not used by the plugin.## assemble Recall Flowdiff --git a/examples/openclaw-plugin/docs/openviking-install-package-contract.md b/examples/openclaw-plugin/docs/openviking-install-package-contract.mdnew file mode 100644index 000000000..6a3515be3--- /dev/null+++ b/examples/openclaw-plugin/docs/openviking-install-package-contract.md@@ -0,0 +1,85 @@+# OpenViking Install And Package Contract++This document records the install/package contract that the OpenViking OpenClaw plugin must keep stable.++It intentionally documents the current package contract instead of the unpublished TOS shell-script flow from #2613. Current main does not contain those TOS publishing scripts, so the safe contract is the npm/openclaw package shape that is actually built and installed by this repository.++## Required Package Entries++The plugin package must include:++| Entry | Why it is required |+| --- | --- |+| `dist/` | Compiled runtime loaded by OpenClaw. |+| `dist/index.js` | Main extension entry. |+| `dist/commands/setup.js` | Setup entry used by OpenClaw. |+| `package.json` | OpenClaw package metadata and runtime dependencies. |+| `openclaw.plugin.json` | Plugin manifest. |+| `install-manifest.json` | Install-time file contract. |+| `README.md`, `INSTALL.md`, `INSTALL-ZH.md` | User-facing install and usage docs. |+| `skills/` | Packaged OpenViking skills. |++Helper modules added under `plugin/` must be listed in the package `files` contract or included by a package-level directory rule.++## OpenClaw Metadata++`package.json` must keep these OpenClaw fields valid:++```json+{+ "openclaw": {+ "extensions": ["./dist/index.js"],+ "setupEntry": "./dist/commands/setup.js"+ }+}+```++The `setupEntry` must point at compiled JavaScript, not source TypeScript.++## Runtime Dependencies++Runtime dependencies must include everything the compiled plugin imports at runtime. Development-only test/build packages belong in `devDependencies`.++The package currently keeps an `axios` override to avoid installing vulnerable or incompatible transitive versions through OpenClaw packaging.++## Install Manifest++`install-manifest.json` defines the source files and metadata required by the OpenClaw install flow. When a new runtime source module is imported by `index.ts` or setup code, add it to `files.required`.++Required entries should include core runtime modules such as:++- `index.ts`+- `config.ts`+- `context-engine.ts`+- `client.ts`+- `auto-recall.ts`+- `recall-trace.ts`+- `commands/setup.ts`+- `package.json`+- `openclaw.plugin.json`++Optional entries are for files that improve the installed plugin but are not needed to load the runtime, such as lockfiles or extra docs.++## Verification Checklist++Before publishing or merging package-contract changes, run:++```bash+npm test -- tests/ut/package-install-contract.test.ts+npm run typecheck+npm run build+git diff --check+```++The package contract test should verify:++- compiled extension entry exists after build,+- compiled setup entry exists after build,+- `openclaw.extensions` and `openclaw.setupEntry` point to `dist/*.js`,+- package `files` include runtime assets and docs,+- install manifest required files exist,+- runtime dependencies and overrides are present.++## Out Of Scope++The #2613 branch also contained draft TOS publishing/install notes. Those notes depend on release scripts and object-storage upload flow that are not present in current main. They should be added only with the corresponding scripts and CI/release process, not as standalone documentation.diff --git a/examples/openclaw-plugin/docs/openviking-runtime-query-config.md b/examples/openclaw-plugin/docs/openviking-runtime-query-config.mdnew file mode 100644index 000000000..6d0414f8c--- /dev/null+++ b/examples/openclaw-plugin/docs/openviking-runtime-query-config.md@@ -0,0 +1,139 @@+# OpenViking Runtime Query Config++Runtime query config lets operators tune recall and search behavior without restarting OpenClaw. It is intended for live debugging and rollout control around recall limit, candidate count, score threshold, target resource types, and ranking weights.++This document describes the runtime query config capability ported from the broader #2613 work into the split OpenViking plugin PR series.++## Configuration Layers++Effective query config is resolved per request with this priority:++```text+explicit tool request arguments+ > session runtime config+ > peer runtime config+ > static plugin config+ > code defaults+```++The higher layer wins field by field. Object fields such as ranking weights are shallow-merged. Array fields such as `resourceTypes` replace the lower layer.++## Scopes++Runtime config has two persistent scopes:++| Scope | Meaning |+| --- | --- |+| `peer` | Applies to the current OpenClaw peer/assistant identity across sessions. |+| `session` | Applies only to the current session identity. |++For command compatibility, `--scope claw` is accepted as an alias for `peer`.++## Supported Fields++| Field | Purpose |+| --- | --- |+| `recallLimit` | Number of final recall results to inject or display. |+| `candidateLimit` | Number of candidates requested before local ranking/filtering. |+| `candidateMultiplier` | Multiplier used to derive candidate count from recall limit when `candidateLimit` is not explicit. |+| `scoreThreshold` | Client-side minimum score after semantic search. |+| `maxInjectedChars` | Character budget for automatic recall injection. |+| `recallPreferAbstract` | Prefer abstracts over full content when injecting recalled context. |+| `resourceTypes` | Default semantic recall target types: `user`, `agent`, `resource`. |+| `targetUri` | Force a single `viking://` target URI for search. |+| `ovSearchLimit` | Default result count for `ov_search`. |+| `rankingWeights` | Local ranking weights, such as base score and lexical overlap. |+| `categoryWeights` | Optional category-specific ranking adjustments. |+| `resourceTypeWeights` | Optional resource type ranking adjustments. |++Session history is not a semantic recall target. Use `ov_archive_search` and `ov_archive_expand` for session archive recovery.++## Slash Command++### Get++```text+/ov-query-config get --scope session+/ov-query-config get --scope peer+```++The response includes the effective config and per-field sources, which are useful for understanding why a value is active.++### Set++```text+/ov-query-config set --scope peer \+ --recallLimit 6 \+ --candidateLimit 40 \+ --scoreThreshold 0.15 \+ --resourceTypes user,agent,resource+```++```text+/ov-query-config set --scope session \+ --ovSearchLimit 8 \+ --recallPreferAbstract true+```++### Weights++```text+/ov-query-config set --scope peer \+ --weight baseScore=1,leaf=0.12,lexicalOverlapMax=0.2 \+ --categoryWeight preference=0.2,event=0.1 \+ --resourceTypeWeight user=0.15,resource=0.1+```++### Unset++```text+/ov-query-config unset recallLimit scoreThreshold rankingWeights --scope session+```++### Reset++```text+/ov-query-config reset --scope session+/ov-query-config reset --scope peer+```++## Persistence++Runtime query config can be persisted by configuring `runtimeQueryConfigPath`.++```json+{+ "plugins": {+ "entries": {+ "openviking": {+ "config": {+ "runtimeQueryConfigPath": "/path/to/runtime-query-config.json"+ }+ }+ }+ }+}+```++If the file is missing, the store starts empty. If the file is malformed, the plugin keeps the last known-good in-memory config and reports a warning instead of breaking recall.++## Interaction With Tools++`memory_recall` and `ov_search` use runtime config as defaults. Explicit arguments on the current tool call still win.++Examples:++- If peer scope sets `ovSearchLimit=8`, `ov_search` defaults to 8 results.+- If a specific `ov_search` call passes `limit=3`, that request returns 3 results and does not mutate runtime config.+- If session scope sets `scoreThreshold`, it overrides peer/static threshold only for that session.++## Verification++The split implementation is covered by unit tests for:++- normalization and persistence,+- layer precedence,+- empty patch rejection,+- `peer` and `claw` scope compatibility,+- `memory_recall` and `ov_search` runtime defaulting,+- explicit request arguments overriding runtime defaults.diff --git a/examples/openclaw-plugin/docs/openviking-websocket-rpc-api.md b/examples/openclaw-plugin/docs/openviking-websocket-rpc-api.mdnew file mode 100644index 000000000..8b80547b8--- /dev/null+++ b/examples/openclaw-plugin/docs/openviking-websocket-rpc-api.md@@ -0,0 +1,867 @@+# OpenViking WebSocket RPC Guide++This document explains how to call the OpenViking OpenClaw plugin through the OpenClaw Gateway WebSocket RPC surface.++The plugin does not start its own WebSocket server. OpenViking tools are registered through the OpenClaw plugin API, and the Gateway exposes them through standard tool RPC methods.++## Supported Flow++1. Connect to the OpenClaw Gateway WebSocket endpoint.+2. Call `tools.effective` for a real `sessionKey` to inspect tools available in the current session.+3. Call `tools.invoke` with an OpenViking tool name and JSON arguments.++Typical endpoint:++```text+ws://127.0.0.1:<gateway-port>+```++If TLS is enabled, use `wss://`.++## Connect++The first message is a `connect` request. Exact auth fields depend on the Gateway deployment.++```json+{+ "type": "req",+ "id": "connect-1",+ "method": "connect",+ "params": {+ "minProtocol": 3,+ "maxProtocol": 4,+ "client": {+ "id": "openviking-rpc-client",+ "version": "1.0.0",+ "platform": "macos",+ "mode": "operator"+ },+ "role": "operator",+ "scopes": ["operator.read", "operator.write"],+ "auth": {+ "token": "<OPENCLAW_GATEWAY_TOKEN>"+ },+ "locale": "zh-CN",+ "userAgent": "openviking-rpc-client/1.0.0"+ }+}+```++The Gateway returns `hello-ok` when the connection is accepted.++## Discover Tools++Use the current OpenClaw session key. Do not invent a synthetic session key for production debugging.++```json+{+ "type": "req",+ "id": "tools-1",+ "method": "tools.effective",+ "params": {+ "sessionKey": "main"+ }+}+```++OpenViking plugin tools are entries with `source="plugin"` and `pluginId="openviking"`.++## Invoke Tools++All OpenViking tools use `tools.invoke`.++```json+{+ "type": "req",+ "id": "invoke-1",+ "method": "tools.invoke",+ "params": {+ "name": "ov_search",+ "sessionKey": "main",+ "args": {+ "query": "OpenViking installation",+ "limit": 5+ }+ }+}+```++`params.sessionKey` is the Gateway/session routing field. It tells OpenClaw which session context the tool call belongs to.++`params.args.sessionKey` is a tool argument only when a specific OpenViking tool defines it. For example, `ov_recall_trace` can use it as an explicit trace filter. For the current session's trace, pass only the outer `params.sessionKey` unless you intentionally want a different filter.++## Common Tools++### `ov_search`++Search OpenViking resources, skills, and memories.++```json+{+ "name": "ov_search",+ "sessionKey": "main",+ "args": {+ "query": "runtime query config",+ "limit": 5,+ "uri": "viking://resources"+ }+}+```++### `ov_read`++Read an exact `viking://` URI.++```json+{+ "name": "ov_read",+ "sessionKey": "main",+ "args": {+ "uri": "viking://resources/project/spec.md"+ }+}+```++### `ov_multi_read`++Read multiple exact URIs in one tool call.++```json+{+ "name": "ov_multi_read",+ "sessionKey": "main",+ "args": {+ "uris": [+ "viking://resources/project/spec.md",+ "viking://resources/project/faq.md"+ ]+ }+}+```++### `memory_recall`++Recall semantic memories and resources. Current semantic recall target types are `user`, `agent`, and `resource`. Session history is not a vector recall target; use `ov_archive_search` and `ov_archive_expand` for archived session history.++```json+{+ "name": "memory_recall",+ "sessionKey": "main",+ "args": {+ "query": "what did we decide about install verification",+ "limit": 5,+ "resourceTypes": ["user", "agent", "resource"]+ }+}+```++参数:++| 字段 | 类型 | 必填 | 说明 |+|------|------|------|------|+| `query` | string | 是 | 召回查询文本 |+| `limit` | number | 否 | 最终返回条数,默认使用插件配置 |+| `scoreThreshold` | number | 否 | 最低分数,范围 0-1 |+| `targetUri` | string | 否 | 指定单一搜索范围,例如 `viking://user/memories` |+| `resourceTypes` | string[] | 否 | 未指定 `targetUri` 时使用,当前支持 `resource`、`user`、`agent`;session 历史走 `ov_archive_search` / `ov_archive_expand` |++### `memory_store`++把文本写入 OpenViking session,并立即触发记忆抽取。++```json+{+ "type": "req",+ "id": "memory-store-1",+ "method": "tools.invoke",+ "params": {+ "name": "memory_store",+ "sessionKey": "main",+ "args": {+ "text": "用户偏好使用 TypeScript 编写 OpenClaw 插件。",+ "role": "user"+ }+ }+}+```++参数:++| 字段 | 类型 | 必填 | 说明 |+|------|------|------|------|+| `text` | string | 是 | 作为记忆来源的文本 |+| `role` | string | 否 | session 消息角色,默认 `user` |+| `sessionId` | string | 否 | 指定已有 OpenViking session;不传则使用临时 session |++### `memory_forget`++删除记忆。可以传精确 URI,也可以先按 query 搜索候选。++按 URI 删除:++```json+{+ "type": "req",+ "id": "memory-forget-1",+ "method": "tools.invoke",+ "params": {+ "name": "memory_forget",+ "sessionKey": "main",+ "args": {+ "uri": "viking://user/default/memories/memory_123"+ }+ }+}+```++按 query 查找候选:++```json+{+ "type": "req",+ "id": "memory-forget-2",+ "method": "tools.invoke",+ "params": {+ "name": "memory_forget",+ "sessionKey": "main",+ "args": {+ "query": "偏好 Python 后端",+ "targetUri": "viking://user/memories",+ "limit": 5,+ "scoreThreshold": 0.85+ }+ }+}+```++参数:++| 字段 | 类型 | 必填 | 说明 |+|------|------|------|------|+| `uri` | string | 否 | 精确记忆 URI,仅允许当前 user/peer 记忆 URI |+| `query` | string | 否 | 未提供 `uri` 时用于搜索候选 |+| `targetUri` | string | 否 | 搜索范围,默认使用插件配置 |+| `limit` | number | 否 | 候选展示数量,默认 5 |+| `scoreThreshold` | number | 否 | 候选最低分数 |++### `add_skill`++导入 Agent Skill 到当前用户/peer 的 OpenViking skill namespace。++```json+{+ "type": "req",+ "id": "add-skill-1",+ "method": "tools.invoke",+ "params": {+ "name": "add_skill",+ "sessionKey": "main",+ "args": {+ "source": "/absolute/path/to/my-skill",+ "wait": true,+ "timeout": 120+ }+ }+}+```++也可以传原始 skill 内容或 MCP tool dict:++```json+{+ "type": "req",+ "id": "add-skill-2",+ "method": "tools.invoke",+ "params": {+ "name": "add_skill",+ "sessionKey": "main",+ "args": {+ "data": "# My Skill\n\nSkill content...",+ "wait": true+ }+ }+}+```++参数:++| 字段 | 类型 | 必填 | 说明 |+|------|------|------|------|+| `source` | string | 二选一 | 本地 `SKILL.md` 文件或 skill 目录 |+| `data` | any | 二选一 | 原始 `SKILL.md` 内容或 MCP tool dict |+| `wait` | boolean | 否 | 是否等待服务端处理完成 |+| `timeout` | number | 否 | `wait=true` 时的超时时间,单位秒 |++### `add_resource`++导入文档、目录、URL 或 Git 仓库到 OpenViking resources。++注意:该工具默认不暴露给 Agent,必须在插件配置中设置 `enableAddResourceTool=true`,并且工具策略允许它,才能通过 `tools.invoke` 调用。未启用时可使用 slash command `/add-resource`。++```json+{+ "type": "req",+ "id": "add-resource-1",+ "method": "tools.invoke",+ "params": {+ "name": "add_resource",+ "sessionKey": "main",+ "args": {+ "source": "/absolute/path/to/docs",+ "parent": "viking://resources/project-docs",+ "reason": "导入项目文档",+ "instruction": "保留 API 示例和配置说明",+ "wait": true,+ "timeout": 300+ }+ }+}+```++参数:++| 字段 | 类型 | 必填 | 说明 |+|------|------|------|------|+| `source` | string | 是 | 本地文件、目录、OpenClaw media path、公开 URL 或 Git URL |+| `to` | string | 否 | 精确目标 URI,不能和 `parent` 同时使用 |+| `parent` | string | 否 | 父级 URI,不能和 `to` 同时使用 |+| `reason` | string | 否 | 导入原因或说明 |+| `instruction` | string | 否 | 服务端处理指令 |+| `wait` | boolean | 否 | 是否等待服务端处理完成 |+| `timeout` | number | 否 | `wait=true` 时的超时时间,单位秒 |++### `ov_archive_search`++在当前 session 已归档的原始消息中做关键词 grep。++```json+{+ "type": "req",+ "id": "archive-search-1",+ "method": "tools.invoke",+ "params": {+ "name": "ov_archive_search",+ "sessionKey": "main",+ "args": {+ "query": "tcpdump",+ "archiveId": "archive_003"+ }+ }+}+```++参数:++| 字段 | 类型 | 必填 | 说明 |+|------|------|------|------|+| `query` | string | 是 | 单个关键词或短语 |+| `archiveId` | string | 否 | 限定某个 archive,例如 `archive_003` |++### `ov_archive_expand`++展开某个归档,读取原始消息。++```json+{+ "type": "req",+ "id": "archive-expand-1",+ "method": "tools.invoke",+ "params": {+ "name": "ov_archive_expand",+ "sessionKey": "main",+ "args": {+ "archiveId": "archive_003"+ }+ }+}+```++参数:++| 字段 | 类型 | 必填 | 说明 |+|------|------|------|------|+| `archiveId` | string | 是 | archive ID,例如 `archive_003` |++### `ov_recall_trace`++Inspect recall traces when `traceRecall` is enabled.++```json+{+ "name": "ov_recall_trace",+ "sessionKey": "main",+ "args": {+ "turn": "latest",+ "limit": 5,+ "includeContent": false+ }+}+```++参数:++| 字段 | 类型 | 必填 | 说明 |+|------|------|------|------|+| `turn` | string | 否 | `latest` 或 `all`,默认 `latest` |+| `traceId` | string | 否 | 精确 trace id |+| `sessionId` | string | 否 | OpenClaw session id |+| `sessionKey` | string | 否 | OpenClaw session key |+| `ovSessionId` | string | 否 | OpenViking session id |+| `source` | string | 否 | `auto_recall`、`memory_recall`、`ov_search` 或 `ov_archive_search` |+| `resourceTypes` | string[] | 否 | `resource`、`user`、`agent` |+| `since` | number | 否 | Unix timestamp 毫秒下界 |+| `until` | number | 否 | Unix timestamp 毫秒上界 |+| `includeContent` | boolean | 否 | 是否按需读取 URI 内容预览 |+| `limit` | number | 否 | 最多返回 trace 数量,默认 20 |++### `openviking_tool_result_list`++列出当前 session 中被 OpenViking 外置的大工具结果。++```json+{+ "type": "req",+ "id": "tool-result-list-1",+ "method": "tools.invoke",+ "params": {+ "name": "openviking_tool_result_list",+ "sessionKey": "main",+ "args": {+ "tool_name": "RunCommand",+ "limit": 20+ }+ }+}+```++参数:++| 字段 | 类型 | 必填 | 说明 |+|------|------|------|------|+| `tool_name` | string | 否 | 按工具名过滤,也兼容 `toolName` |+| `limit` | number | 否 | 最多返回数量,默认 50 |++### `openviking_tool_result_search`++在外置的大工具结果中搜索关键词。++```json+{+ "type": "req",+ "id": "tool-result-search-1",+ "method": "tools.invoke",+ "params": {+ "name": "openviking_tool_result_search",+ "sessionKey": "main",+ "args": {+ "tool_output_ref": "viking://session/<session_id>/tool-results/<tool_result_id>",+ "query": "error",+ "limit": 10,+ "context_chars": 300+ }+ }+}+```++参数:++| 字段 | 类型 | 必填 | 说明 |+|------|------|------|------|+| `tool_output_ref` | string | 是 | `viking://session/.../tool-results/...` URI,也兼容 `ref` 或 `uri` |+| `query` | string | 是 | 搜索关键词或精确文本 |+| `limit` | number | 否 | 最多匹配数,默认 20 |+| `context_chars` | number | 否 | 每个命中周围保留字符数,默认 300,也兼容 `contextChars` |++### `openviking_tool_result_read`++读取外置的大工具结果全文或片段。++```json+{+ "type": "req",+ "id": "tool-result-read-1",+ "method": "tools.invoke",+ "params": {+ "name": "openviking_tool_result_read",+ "sessionKey": "main",+ "args": {+ "tool_output_ref": "viking://session/<session_id>/tool-results/<tool_result_id>",+ "offset": 0,+ "limit": 4000+ }+ }+}+```++参数:++| 字段 | 类型 | 必填 | 说明 |+|------|------|------|------|+| `tool_output_ref` | string | 是 | `viking://session/.../tool-results/...` URI,也兼容 `ref` 或 `uri` |+| `offset` | number | 否 | 起始字符偏移,默认 0 |+| `limit` | number | 否 | 最多返回字符数 |++## Response Shape++Successful tool invocation usually returns a Gateway response whose payload contains the plugin tool output.++```json+{+ "type": "res",+ "id": "invoke-1",+ "ok": true,+ "payload": {+ "ok": true,+ "toolName": "ov_search",+ "source": "plugin",+ "output": {+ "content": [+ {+ "type": "text",+ "text": "Found 2 OpenViking results ..."+ }+ ],+ "details": {+ "action": "searched",+ "total": 2+ }+ }+ }+}+```++If the Gateway accepted the RPC request but the tool failed, the outer `ok` can still be `true` while `payload.ok` is `false`.++```json+{+ "type": "res",+ "id": "invoke-1",+ "ok": true,+ "payload": {+ "ok": false,+ "toolName": "ov_search",+ "error": {+ "code": "not_found",+ "message": "Tool not available: ov_search"+ }+ }+}+```++## Notes++- Use `tools.effective` before invoking a tool in a live session.+- Use exact `viking://` URIs with `ov_read` and `ov_multi_read`.+- Do not use deprecated agent URI paths for memory routing. Current routing is based on OpenViking context type and actor peer identity.+- For recall trace HTTP routes, see `openviking-recall-trace-api.md`.++## 本机验证记录(2026-06-05)++本节保留 #2613 中的 WebSocket RPC 实测记录和可复制命令,但按当前主线语义调整:++- 不使用旧 `agent_prefix` / `X-OpenViking-Agent` / `viking://agent/...` 路径。+- OpenViking 插件仍通过 OpenClaw Gateway 暴露工具,插件自身不启动 WebSocket server。+- 语义召回目标使用 `user`、`agent`、`resource`;session 历史不作为 vector recall target,应走 `ov_archive_search` / `ov_archive_expand`。+- 当前主线通过 OpenViking `context_type` 与 `X-OpenViking-Actor-Peer` 做检索和 actor peer 路由。++验证环境:++- OpenClaw:`2026.5.28`+- Gateway 节点:`SuperOpsByteDance.local`,macOS gateway mode+- CLI:`openclaw gateway call <method> --params '<json>' --json`++### Gateway RPC 基础接口++| ID | 方法 | 参数 | 预期 | 实测结果 | 结论 |+|---|---|---|---|---|---|+| WS-RPC-01 | `health` | `{}` | Gateway 健康检查成功 | `ok=true`、`runtimeVersion=2026.5.28`、`eventLoop.degraded=false` | 通过 |+| WS-RPC-02 | `status` | `{}` | 返回运行时和 session 状态 | `defaultAgentId=main`、`mainHeartbeatEnabled=true`、`eventLoopDegraded=false` | 通过 |+| WS-RPC-03 | `system-presence` | `{}` | 返回当前 Gateway/CLI presence | 返回 macOS gateway 节点与 CLI probe 节点 | 通过 |+| WS-RPC-04 | `tools.catalog` | `{"agentId":"main"}` | agent 工具目录包含 OpenViking 工具 | `group_count=14`、OpenViking 工具可见 | 通过 |+| WS-RPC-05 | `tools.effective` | `{"sessionKey":"<真实 sessionKey>"}` | 当前 session 可用工具包含 OpenViking 工具 | `agentId=main`、`profile=full`、OpenViking 工具可见 | 通过 |++常见 OpenViking 工具包括:++```text+add_skill, memory_forget, memory_recall, memory_store,+openviking_tool_result_list, openviking_tool_result_read, openviking_tool_result_search,+ov_archive_expand, ov_archive_search, ov_list, ov_multi_read, ov_read, ov_recall_trace, ov_search+```++注意:`add_resource` 默认不是 agent-visible tool;只有配置 `enableAddResourceTool=true` 并且工具策略允许时才会出现在 agent 工具集中。手动导入仍可走 slash command `/add-resource`。++### 获取真实 sessionKey++线上排障时不要人为构造 `sessionKey` 来代表真实会话。优先使用 OpenClaw 当前状态或调用方上下文里的真实 session key。++```bash+SK="$(openclaw status --json | jq -r '+ .sessionKey //+ .session.key //+ .currentSession.key //+ .current_session.key //+ empty+')"++if [ -z "$SK" ]; then+ echo "未从 openclaw status --json 取到 sessionKey" >&2+ openclaw status --json | jq .+ exit 1+fi++echo "$SK"+```++### OpenViking 工具调用++#### `ov_search`++```bash+PARAMS="$(jq -cn \+ --arg sk "$SK" \+ '{+ name: "ov_search",+ sessionKey: $sk,+ args: {+ query: "openclaw plugin config",+ limit: 2+ }+ }'+)"++openclaw gateway call tools.invoke \+ --params "$PARAMS" \+ --json | jq .+```++预期:++- `payload.ok=true`+- `toolName=ov_search`+- 返回 `viking://resources/...`、`viking://user/skills/...` 或 memory 相关结果,取决于当前 query config / target URI++#### `ov_read`++```bash+URI="viking://resources/openclaw-plugin-config/.abstract.md"++PARAMS="$(jq -cn \+ --arg sk "$SK" \+ --arg uri "$URI" \+ '{+ name: "ov_read",+ sessionKey: $sk,+ args: {+ uri: $uri+ }+ }'+)"++openclaw gateway call tools.invoke \+ --params "$PARAMS" \+ --json | jq .+```++`ov_read` 只接受完整 `viking://` URI。不要传带 `...` 或 `…` 的展示截断 URI,也不要把 `viking://` URI 当成本地文件路径交给文件读取工具。++#### `memory_recall`++```bash+PARAMS="$(jq -cn \+ --arg sk "$SK" \+ '{+ name: "memory_recall",+ sessionKey: $sk,+ args: {+ query: "openclaw plugin config",+ limit: 2,+ resourceTypes: ["resource"]+ }+ }'+)"++openclaw gateway call tools.invoke \+ --params "$PARAMS" \+ --json | jq .+```++当前主线支持的 semantic recall target types:++| target | 说明 |+|---|---|+| `user` | 用户/peer 相关长期记忆 |+| `agent` | 兼容默认 memory context search 语义;当前实现不会恢复旧 `viking://agent/...` 路径 |+| `resource` | 资源知识库内容 |++`session` 不作为 semantic recall target。要查 session 历史,请使用:++- `ov_archive_search`+- `ov_archive_expand`++#### `ov_archive_search`++```bash+PARAMS="$(jq -cn \+ --arg sk "$SK" \+ '{+ name: "ov_archive_search",+ sessionKey: $sk,+ args: {+ query: "tcpdump"+ }+ }'+)"++openclaw gateway call tools.invoke \+ --params "$PARAMS" \+ --json | jq .+```++#### `ov_archive_expand`++```bash+PARAMS="$(jq -cn \+ --arg sk "$SK" \+ '{+ name: "ov_archive_expand",+ sessionKey: $sk,+ args: {+ archiveId: "archive_003"+ }+ }'+)"++openclaw gateway call tools.invoke \+ --params "$PARAMS" \+ --json | jq .+```++### Trace RPC 专项验证++以下命令均通过 `tools.invoke` 调用 OpenViking 工具 `ov_recall_trace`。++外层 `params.sessionKey` 是 Gateway 的执行上下文,也是默认 trace 查询身份。`args.sessionKey` 只用于“按 trace 记录里的 sessionKey 精确过滤”的场景;日常排查当前 session 时,优先只传外层 `sessionKey`。++```bash+# 1. 查询最新 trace+openclaw gateway call tools.invoke \+ --params "$(jq -cn --arg sk "$SK" '{name:"ov_recall_trace",sessionKey:$sk,args:{turn:"latest",limit:5}}')" \+ --json | jq .++# 2. 按 source 查询 ov_search trace+openclaw gateway call tools.invoke \+ --params "$(jq -cn --arg sk "$SK" '{name:"ov_recall_trace",sessionKey:$sk,args:{turn:"all",source:"ov_search",limit:10}}')" \+ --json | jq .++# 3. 按 traceId 精确查询+TRACE_ID="ov_search-1780635606119-h2fl11l5"+openclaw gateway call tools.invoke \+ --params "$(jq -cn --arg sk "$SK" --arg trace "$TRACE_ID" '{name:"ov_recall_trace",sessionKey:$sk,args:{traceId:$trace,limit:1}}')" \+ --json | jq .++# 4. 按 traceId 查询并展开 selected 内容预览+openclaw gateway call tools.invoke \+ --params "$(jq -cn --arg sk "$SK" --arg trace "$TRACE_ID" '{name:"ov_recall_trace",sessionKey:$sk,args:{traceId:$trace,includeContent:true,limit:1}}')" \+ --json | jq .++# 5. 按当前 sessionKey 过滤 trace+openclaw gateway call tools.invoke \+ --params "$(jq -cn --arg sk "$SK" '{name:"ov_recall_trace",sessionKey:$sk,args:{turn:"all",sessionKey:$sk,limit:20}}')" \+ --json | jq .++# 6. 查询不存在的 traceId,验证空结果边界+openclaw gateway call tools.invoke \+ --params "$(jq -cn --arg sk "$SK" '{name:"ov_recall_trace",sessionKey:$sk,args:{traceId:"not-exist-trace-20260605",limit:1}}')" \+ --json | jq .++# 7. 查询不匹配的 sessionKey,验证空结果边界+openclaw gateway call tools.invoke \+ --params "$(jq -cn --arg sk "$SK" '{name:"ov_recall_trace",sessionKey:$sk,args:{turn:"all",sessionKey:"agent:main:no-trace-session-20260605",limit:5}}')" \+ --json | jq .++# 8. 查询不匹配的 source,验证空结果边界+openclaw gateway call tools.invoke \+ --params "$(jq -cn --arg sk "$SK" '{name:"ov_recall_trace",sessionKey:$sk,args:{turn:"all",source:"not_a_source",limit:5}}')" \+ --json | jq .++# 9. limit=0 边界验证+openclaw gateway call tools.invoke \+ --params "$(jq -cn --arg sk "$SK" '{name:"ov_recall_trace",sessionKey:$sk,args:{turn:"all",limit:0}}')" \+ --json | jq .+```++| ID | 场景 | 参数摘要 | 预期 / 实测关注点 | 结论 |+|---|---|---|---|---|+| WS-RPC-10 | 最新 trace | `turn=latest`、`limit=5` | 返回最近 trace;无 trace 时 `count=0` 不算失败 | 通过 |+| WS-RPC-11 | source 过滤 | `turn=all`、`source=ov_search` | 只返回 `ov_search` trace | 通过 |+| WS-RPC-12 | traceId 精确查询 | `traceId=<id>`、`limit=1` | 返回指定 trace 或空结果 | 通过 |+| WS-RPC-13 | includeContent | `includeContent=true` | selected 项可包含内容预览 | 通过 |+| WS-RPC-14 | sessionKey 过滤 | `args.sessionKey=$SK` | 返回该 session 的 trace | 通过 |+| WS-RPC-15 | 不存在 traceId | `traceId=not-exist...` | `ok=true`、`count=0`、`entries=[]` | 通过 |+| WS-RPC-16 | 不匹配 sessionKey | `sessionKey=no-trace...` | `ok=true`、`count=0`、`entries=[]` | 通过 |+| WS-RPC-17 | 不匹配 source | `source=not_a_source` | `ok=true`、`count=0`、`entries=[]` | 通过 |+| WS-RPC-18 | `limit=0` 边界 | `turn=all`、`limit=0` | Gateway 不异常;按工具默认/边界策略返回 | 通过 |++`ov_recall_trace` 的 RPC 响应中,关键结构位于 `output.details`:++```json+{+ "action": "queried",+ "count": 1,+ "lookupLayer": "memory|persistent",+ "warnings": [],+ "entries": ["RecallTraceEntry"]+}+```++无匹配数据时不视为调用失败,而是返回:++```json+{+ "ok": true,+ "toolName": "ov_recall_trace",+ "output": {+ "details": {+ "count": 0,+ "entries": []+ }+ }+}+```++### 边界用例++| ID | 场景 | 参数 / 命令 | 预期 | 结论 |+|---|---|---|---|---|+| WS-RPC-19 | 未知 RPC method | `openclaw gateway call does.not.exist --params '{}' --json` | Gateway 返回 unknown method | 通过 |+| WS-RPC-20 | 不存在 session key | `tools.effective` + 不存在的 `sessionKey` | Gateway 返回 unknown session key | 通过 |+| WS-RPC-21 | 不存在工具 | `tools.invoke` + `name=not_a_tool` | `payload.ok=false`、`error.code=not_found` | 通过 |+| WS-RPC-22 | 缺少 `ov_search.query` | `tools.invoke` + `name=ov_search` + `args={"limit":2}` | 工具参数错误,RPC 不应导致 Gateway 崩溃 | 通过 |+| WS-RPC-23 | `ov_read` 非法 URI | `tools.invoke` + `name=ov_read` + `args={"uri":"not-viking"}` | 工具返回参数错误 | 通过 |++### 常见问题++#### `tools.invoke` 返回 `Tool not available`++检查:++1. OpenViking 插件是否安装并启用。+2. Gateway 是否已重启。+3. `openclaw.plugin.json` 中工具 contract 是否包含该工具。+4. 插件配置 `enabledTools` / `disabledTools` 是否过滤了该工具。+5. Gateway 工具策略是否允许该工具。+6. `add_resource` 是否已设置 `enableAddResourceTool=true`。++#### `ov_read` 报 URI 无效++`ov_read` 只接受完整 `viking://` URI。不要传带 `...` 或 `…` 的展示截断 URI。++#### `ov_recall_trace` 查询为空++优先确认:++1. 是否开启 `traceRecall`。+2. 是否使用真实外层 `sessionKey`。+3. 是否错误叠加了 `args.sessionKey`、`sessionId`、`ovSessionId` 等过滤条件。+4. `traceRecallPersist` 开启时,持久化目录下是否存在对应 JSONL。+5. 查询窗口是否被 `since`、`until`、`limit` 或 retention 配置截断。diff --git a/examples/openclaw-plugin/index.ts b/examples/openclaw-plugin/index.tsindex 46eced7f0..b1ac52932 100644--- a/examples/openclaw-plugin/index.ts+++ b/examples/openclaw-plugin/index.ts@@ -60,6 +60,12 @@ import {type QueryConfigContext,type RuntimeQueryParams,} from "./query-config.js";+import {+ formatOVListText,+ formatOVMultiReadText,+ formatOVReadText,+ formatOVSearchText,+} from "./plugin/openviking-query-formatters.js";export {buildMemoryLines,buildMemoryLinesWithBudget,@@ -1580,107 +1586,6 @@ const contextEnginePlugin = {};};- const formatOVSearchRows = (result: FindResult): string[] => {- const truncateSummary = (value: string, maxChars = 220): string => {- const collapsed = value.replace(/\s+/g, " ").trim();- if (collapsed.length <= maxChars) {- return collapsed;- }- return `${collapsed.slice(0, maxChars - 3)}...`;- };- const items = [- ...(result.memories ?? []).map((item) => ({ contextType: "memory", item })),- ...(result.resources ?? []).map((item) => ({ contextType: "resource", item })),- ...(result.skills ?? []).map((item) => ({ contextType: "skill", item })),- ];- if (items.length === 0) {- return [];- }- const numberHeader = "no";- const numberWidth = Math.max(numberHeader.length, String(items.length).length);- const typeWidth = Math.max("type".length, ...items.map(({ contextType }) => contextType.length));- const uriWidth = Math.max("uri".length, ...items.map(({ item }) => item.uri.length));- const levelWidth = Math.max("level".length, ...items.map(({ item }) => String(item.level ?? "").length));- const scoreWidth = Math.max(- "score".length,- ...items.map(({ item }) => (typeof item.score === "number" ? item.score.toFixed(2).length : 0)),- );- return [- `${numberHeader.padEnd(numberWidth)} ${"type".padEnd(typeWidth)} ${"uri".padEnd(uriWidth)} ${"level".padEnd(levelWidth)} ${"score".padEnd(scoreWidth)} abstract`,- ...items.map(({ contextType, item }, index) => {- const score = typeof item.score === "number" ? item.score.toFixed(2) : "";- const summary = truncateSummary(item.abstract || item.overview || "(no summary)");- return `${String(index + 1).padEnd(numberWidth)} ${contextType.padEnd(typeWidth)} ${item.uri.padEnd(uriWidth)} ${String(item.level ?? "").padEnd(levelWidth)} ${score.padEnd(scoreWidth)} ${summary}`;- }),- ];- };-- const formatOVSearchText = (query: string, uri: string | undefined, result: FindResult): string => {- if ((result.total ?? 0) <= 0) {- const scope = uri ? ` under ${uri}` : "";- return `No OpenViking resource or skill results found for "${query}"${scope}.`;- }- const scope = uri ? ` under ${uri}` : "";- const lines = [- `Found ${result.total ?? 0} OpenViking results for "${query}"${scope}`,- "Tip: search results are ranked snippets. Use ov_read on exact hit URIs before answering precise questions. Use ov_list on a hit's parent URI to inspect sibling chunks or overview files before answering procedural or multi-step questions.",- "",- ...formatOVSearchRows(result),- ].filter((line, index, all) => line || (all[index - 1] && all[index + 1]));- return lines.join("\n");- };-- const formatOVListEntry = (entry: unknown): string => {- if (typeof entry === "string") {- return entry;- }- if (!entry || typeof entry !== "object") {- return String(entry);- }- const item = entry as Record<string, unknown>;- const uri = typeof item.uri === "string" ? item.uri : "";- const name = typeof item.name === "string" ? item.name : "";- const isDir = item.isDir === true || item.type === "directory";- const marker = isDir ? "[dir]" : "[file]";- const summary =- typeof item.abstract === "string" && item.abstract.trim()- ? item.abstract.trim().replace(/\s+/g, " ")- : typeof item.overview === "string" && item.overview.trim()- ? item.overview.trim().replace(/\s+/g, " ")- : "";- const label = uri || name || JSON.stringify(item);- return summary ? `${marker} ${label} - ${summary}` : `${marker} ${label}`;- };-- const formatOVListText = (uri: string, entries: unknown[]): string => {- if (entries.length === 0) {- return `No OpenViking entries found under ${uri}.`;- }- return [- `Listed ${entries.length} OpenViking entr${entries.length === 1 ? "y" : "ies"} under ${uri}`,- "",- ...entries.map((entry) => formatOVListEntry(entry)),- ].join("\n");- };-- const formatOVReadText = (uri: string, content: string): string => {- const body = content || "(empty OpenViking content)";- return [`--- START OF ${uri} ---`, body, `--- END OF ${uri} ---`].join("\n");- };-- const formatOVMultiReadText = (- results: Array<{ uri: string; content: string; success: boolean }>,- ): string => [- `Multi-read results for ${results.length} OpenViking resource${results.length === 1 ? "" : "s"}:`,- "",- ...results.flatMap((result) => [- `--- START OF ${result.uri} ---`,- result.success ? (result.content || "(empty OpenViking content)") : `ERROR: ${result.content}`,- `--- END OF ${result.uri} ---`,- "",- ]),- ].join("\n").trimEnd();-const searchOpenViking = async (input: OVSearchInput,traceCtx?: PluginSessionRouting,diff --git a/examples/openclaw-plugin/install-manifest.json b/examples/openclaw-plugin/install-manifest.jsonindex 3855fb06e..297aef3b5 100644--- a/examples/openclaw-plugin/install-manifest.json+++ b/examples/openclaw-plugin/install-manifest.json@@ -22,6 +22,7 @@"runtime-utils.ts","recall-trace.ts","query-config.ts",+ "plugin/openviking-query-formatters.ts","commands/setup.ts","plugin/openviking-feature-gates.ts","config/feature-gates.json",diff --git a/examples/openclaw-plugin/package.json b/examples/openclaw-plugin/package.jsonindex 5fb1c5d4d..ece7927c1 100644--- a/examples/openclaw-plugin/package.json+++ b/examples/openclaw-plugin/package.json@@ -23,6 +23,7 @@"*.ts","commands/setup.ts","plugin/openviking-feature-gates.ts",+ "plugin/openviking-query-formatters.ts","config/feature-gates.json","!vitest.config.ts","install-manifest.json",diff --git a/examples/openclaw-plugin/plugin/openviking-query-formatters.ts b/examples/openclaw-plugin/plugin/openviking-query-formatters.tsnew file mode 100644index 000000000..42dcbc96a--- /dev/null+++ b/examples/openclaw-plugin/plugin/openviking-query-formatters.ts@@ -0,0 +1,108 @@+import type { FindResult } from "../client.js";++export type OVMultiReadTextResult = {+ uri: string;+ content: string;+ success: boolean;+};++export function formatOVSearchRows(result: FindResult): string[] {+ const truncateSummary = (value: string, maxChars = 220): string => {+ const collapsed = value.replace(/\s+/g, " ").trim();+ if (collapsed.length <= maxChars) {+ return collapsed;+ }+ return `${collapsed.slice(0, maxChars - 3)}...`;+ };+ const items = [+ ...(result.memories ?? []).map((item) => ({ contextType: "memory", item })),+ ...(result.resources ?? []).map((item) => ({ contextType: "resource", item })),+ ...(result.skills ?? []).map((item) => ({ contextType: "skill", item })),+ ];+ if (items.length === 0) {+ return [];+ }+ const numberHeader = "no";+ const numberWidth = Math.max(numberHeader.length, String(items.length).length);+ const typeWidth = Math.max("type".length, ...items.map(({ contextType }) => contextType.length));+ const uriWidth = Math.max("uri".length, ...items.map(({ item }) => item.uri.length));+ const levelWidth = Math.max("level".length, ...items.map(({ item }) => String(item.level ?? "").length));+ const scoreWidth = Math.max(+ "score".length,+ ...items.map(({ item }) => (typeof item.score === "number" ? item.score.toFixed(2).length : 0)),+ );+ return [+ `${numberHeader.padEnd(numberWidth)} ${"type".padEnd(typeWidth)} ${"uri".padEnd(uriWidth)} ${"level".padEnd(levelWidth)} ${"score".padEnd(scoreWidth)} abstract`,+ ...items.map(({ contextType, item }, index) => {+ const score = typeof item.score === "number" ? item.score.toFixed(2) : "";+ const summary = truncateSummary(item.abstract || item.overview || "(no summary)");+ return `${String(index + 1).padEnd(numberWidth)} ${contextType.padEnd(typeWidth)} ${item.uri.padEnd(uriWidth)} ${String(item.level ?? "").padEnd(levelWidth)} ${score.padEnd(scoreWidth)} ${summary}`;+ }),+ ];+}++export function formatOVSearchText(query: string, uri: string | undefined, result: FindResult): string {+ if ((result.total ?? 0) <= 0) {+ const scope = uri ? ` under ${uri}` : "";+ return `No OpenViking resource or skill results found for "${query}"${scope}.`;+ }+ const scope = uri ? ` under ${uri}` : "";+ const lines = [+ `Found ${result.total ?? 0} OpenViking results for "${query}"${scope}`,+ "Tip: search results are ranked snippets. Use ov_read on exact hit URIs before answering precise questions. Use ov_list on a hit's parent URI to inspect sibling chunks or overview files before answering procedural or multi-step questions.",+ "",+ ...formatOVSearchRows(result),+ ].filter((line, index, all) => line || (all[index - 1] && all[index + 1]));+ return lines.join("\n");+}++export function formatOVListEntry(entry: unknown): string {+ if (typeof entry === "string") {+ return entry;+ }+ if (!entry || typeof entry !== "object") {+ return String(entry);+ }+ const item = entry as Record<string, unknown>;+ const uri = typeof item.uri === "string" ? item.uri : "";+ const name = typeof item.name === "string" ? item.name : "";+ const isDir = item.isDir === true || item.type === "directory";+ const marker = isDir ? "[dir]" : "[file]";+ const summary =+ typeof item.abstract === "string" && item.abstract.trim()+ ? item.abstract.trim().replace(/\s+/g, " ")+ : typeof item.overview === "string" && item.overview.trim()+ ? item.overview.trim().replace(/\s+/g, " ")+ : "";+ const label = uri || name || JSON.stringify(item);+ return summary ? `${marker} ${label} - ${summary}` : `${marker} ${label}`;+}++export function formatOVListText(uri: string, entries: unknown[]): string {+ if (entries.length === 0) {+ return `No OpenViking entries found under ${uri}.`;+ }+ return [+ `Listed ${entries.length} OpenViking entr${entries.length === 1 ? "y" : "ies"} under ${uri}`,+ "",+ ...entries.map((entry) => formatOVListEntry(entry)),+ ].join("\n");+}++export function formatOVReadText(uri: string, content: string): string {+ const body = content || "(empty OpenViking content)";+ return [`--- START OF ${uri} ---`, body, `--- END OF ${uri} ---`].join("\n");+}++export function formatOVMultiReadText(results: OVMultiReadTextResult[]): string {+ return [+ `Multi-read results for ${results.length} OpenViking resource${results.length === 1 ? "" : "s"}:`,+ "",+ ...results.flatMap((result) => [+ `--- START OF ${result.uri} ---`,+ result.success ? (result.content || "(empty OpenViking content)") : `ERROR: ${result.content}`,+ `--- END OF ${result.uri} ---`,+ "",+ ]),+ ].join("\n").trimEnd();+}diff --git a/examples/openclaw-plugin/tests/ut/package-install-contract.test.ts b/examples/openclaw-plugin/tests/ut/package-install-contract.test.tsnew file mode 100644index 000000000..d2706df62--- /dev/null+++ b/examples/openclaw-plugin/tests/ut/package-install-contract.test.ts@@ -0,0 +1,95 @@+import { existsSync, readFileSync } from "node:fs";+import { dirname, join } from "node:path";+import { fileURLToPath } from "node:url";+import { describe, expect, it } from "vitest";++const rootDir = join(dirname(fileURLToPath(import.meta.url)), "../..");++function readJson(path: string): any {+ return JSON.parse(readFileSync(join(rootDir, path), "utf8"));+}++describe("OpenClaw plugin package and install contract", () => {+ it("uses compiled OpenClaw runtime entries", () => {+ const packageJson = readJson("package.json");++ expect(packageJson.openclaw.extensions).toEqual(["./dist/index.js"]);+ expect(packageJson.openclaw.setupEntry).toBe("./dist/commands/setup.js");+ expect(packageJson.scripts.build).toBe("tsc -p tsconfig.build.json");+ });++ it("keeps source install manifest aligned with required source files", () => {+ const installManifest = readJson("install-manifest.json");++ expect(installManifest.plugin).toMatchObject({+ id: "openviking",+ kind: "context-engine",+ slot: "contextEngine",+ });+ expect(installManifest.files.required).toEqual(expect.arrayContaining([+ "index.ts",+ "config.ts",+ "context-engine.ts",+ "auto-recall.ts",+ "client.ts",+ "process-manager.ts",+ "memory-ranking.ts",+ "token-estimator.ts",+ "text-utils.ts",+ "tool-call-id.ts",+ "session-transcript-repair.ts",+ "runtime-utils.ts",+ "recall-trace.ts",+ "commands/setup.ts",+ "tsconfig.json",+ "tsconfig.build.json",+ "package.json",+ "openclaw.plugin.json",+ ]));+ for (const file of installManifest.files.required) {+ expect(existsSync(join(rootDir, file)), `${file} should exist`).toBe(true);+ }+ });++ it("ships npm package files needed by source and compiled installs", () => {+ const packageJson = readJson("package.json");++ expect(packageJson.files).toEqual(expect.arrayContaining([+ "dist/",+ "*.ts",+ "commands/setup.ts",+ "install-manifest.json",+ "openclaw.plugin.json",+ "package.json",+ "README.md",+ "INSTALL.md",+ "INSTALL-ZH.md",+ "INSTALL-AGENT.md",+ "images/",+ "skills/",+ ]));+ });++ it("keeps runtime dependencies and overrides available for installed plugin loading", () => {+ const packageJson = readJson("package.json");++ expect(packageJson.dependencies["@sinclair/typebox"]).toBeDefined();+ expect(packageJson.dependencies.fflate).toBeDefined();+ expect(packageJson.overrides?.axios).toMatch(/^\^1\./);+ expect(packageJson.devDependencies.typescript).toBeDefined();+ expect(packageJson.devDependencies.vitest).toBeDefined();+ });++ it("keeps setup helper fallback metadata compatible with the current plugin manifest", () => {+ const installHelper = readFileSync(join(rootDir, "setup-helper/install.js"), "utf8");+ const installManifest = readJson("install-manifest.json");++ expect(installHelper).toContain("FALLBACK_CURRENT");+ expect(installHelper).toContain(`id: "${installManifest.plugin.id}"`);+ expect(installHelper).toContain(`kind: "${installManifest.plugin.kind}"`);+ expect(installHelper).toContain(`slot: "${installManifest.plugin.slot}"`);+ expect(installHelper).toContain("OPENVIKING_PEER_ROLE");+ expect(installHelper).toContain("OPENVIKING_PEER_PREFIX");+ expect(installHelper).not.toContain("OPENVIKING_AGENT_PREFIX");+ });+});diff --git a/examples/openclaw-plugin/tests/ut/plugin-query-formatters.test.ts b/examples/openclaw-plugin/tests/ut/plugin-query-formatters.test.tsnew file mode 100644index 000000000..238f241e9--- /dev/null+++ b/examples/openclaw-plugin/tests/ut/plugin-query-formatters.test.ts@@ -0,0 +1,73 @@+import { describe, expect, it } from "vitest";++import {+ formatOVListEntry,+ formatOVListText,+ formatOVMultiReadText,+ formatOVReadText,+ formatOVSearchRows,+ formatOVSearchText,+} from "../../plugin/openviking-query-formatters.js";++describe("openviking query formatters", () => {+ it("formats ranked search rows across memories, resources, and skills", () => {+ const rows = formatOVSearchRows({+ memories: [+ { uri: "viking://user/memory/1", level: 2, score: 0.987, abstract: "remember this" },+ ],+ resources: [+ { uri: "viking://resources/doc", score: 0.7, overview: "resource overview" },+ ],+ skills: [+ { uri: "skill://openviking-context-database", abstract: "skill overview" },+ ],+ total: 3,+ });++ expect(rows[0]).toContain("no type");+ expect(rows[1]).toContain("memory");+ expect(rows[1]).toContain("viking://user/memory/1");+ expect(rows[1]).toContain("0.99");+ expect(rows[1]).toContain("remember this");+ expect(rows.join("\n")).toContain("resource overview");+ expect(rows.join("\n")).toContain("skill overview");+ });++ it("formats search text and empty search text", () => {+ expect(formatOVSearchText("query", "viking://resources", { total: 0 })).toBe(+ 'No OpenViking resource or skill results found for "query" under viking://resources.',+ );++ const text = formatOVSearchText("query", undefined, {+ resources: [{ uri: "viking://resources/doc", abstract: "result" }],+ total: 1,+ });++ expect(text).toContain('Found 1 OpenViking results for "query"');+ expect(text).toContain("Use ov_read on exact hit URIs");+ expect(text).toContain("viking://resources/doc");+ });++ it("formats list entries with directory markers and summaries", () => {+ expect(formatOVListEntry("viking://resources/raw")).toBe("viking://resources/raw");+ expect(formatOVListEntry({ uri: "viking://resources/folder", type: "directory" })).toBe(+ "[dir] viking://resources/folder",+ );+ expect(formatOVListText("viking://resources", [+ { uri: "viking://resources/doc", isDir: false, abstract: " short\nsummary " },+ ])).toBe("Listed 1 OpenViking entry under viking://resources\n\n[file] viking://resources/doc - short summary");+ });++ it("formats read and multi-read output", () => {+ expect(formatOVReadText("viking://resources/doc", "")).toBe(+ "--- START OF viking://resources/doc ---\n(empty OpenViking content)\n--- END OF viking://resources/doc ---",+ );++ expect(formatOVMultiReadText([+ { uri: "viking://resources/a", content: "content", success: true },+ { uri: "viking://resources/b", content: "boom", success: false },+ ])).toBe(+ "Multi-read results for 2 OpenViking resources:\n\n--- START OF viking://resources/a ---\ncontent\n--- END OF viking://resources/a ---\n\n--- START OF viking://resources/b ---\nERROR: boom\n--- END OF viking://resources/b ---",+ );+ });+});