Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(openclaw): split OpenViking import tools (#1946)

Mingjian Que0073ce7e051c
diff --git a/docs/plans/agent-tool-name-convergence.md b/docs/plans/agent-tool-name-convergence.md
index 74d2b0a3e..4fb35c397 100644
--- a/docs/plans/agent-tool-name-convergence.md
+++ b/docs/plans/agent-tool-name-convergence.md
@@ -24,8 +24,8 @@
| `read` | 是:REST `/api/v1/content/read`、MCP `read`、CLI `ov read` | 读取指定 URI 的内容。 |
| `list` | 是:REST `/api/v1/fs/ls`、MCP `list`、CLI `ov ls` | 列出目录或命名空间下的节点。 |
| `add_resource` | 是:REST `/api/v1/resources`、MCP `add_resource`、CLI `ov add-resource` | 添加外部资源。 |
+| `add_skill` | 是:REST `/api/v1/skills`、CLI `ov add-skill` | 添加或注册 Agent skill。 |
| `grep` / `glob` | 是:REST `/api/v1/search/grep` 等、MCP `grep` / `glob`、CLI `ov grep` / `ov glob` | 精确文本检索和路径匹配。 |
-| `import` | 否 | OpenClaw 的 `ov_import` 同时覆盖 resource / skill 导入,目前 OV 没有完全等价的单一通用工具。 |
| `archive_search` / `archive_read` | 否 | OpenClaw archive 工具绑定 session archive 语义,目前 OV 只有底层 grep/read 能力。 |
## 1. Search
@@ -97,13 +97,16 @@ Remember 是写入长期记忆:把文本、消息或会话内容写入 OpenVik
| opencode skill plugin | `ov health` | OV CLI | 已下沉,不改名 | 这是 CLI 命令名前缀。 |
| Hermes OpenViking provider | 无公开 `viking_health` 工具 | 配置 / provider 初始化检查 endpoint | 不在本 PR 改 | 最新公开工具列举不包含 health。 |
-## 6. Import / Archive / Read / Browse
+## 6. Add Resource / Add Skill / Archive / Read / Browse
-这些能力当前不能简单改名到通用工具,因为宿主语义尚未完全下沉。
+Resource 和 skill 导入不再合并成 `import`。二者落点命名空间、底层 API 和参数不同:resource 进入 `viking://resources/...`,skill 进入 `viking://agent/skills/...`。因此 OpenClaw 的 Agent 可见工具应直接拆成 `add_resource` 和 `add_skill`,而不是继续暴露 `ov_import(kind=...)`。
| 插件 / 接入 | 当前暴露工具名 / 入口 | 当前实际调用的 OV 接口 | 能否直接收敛到通用工具名 | 结论 / 原因 |
|---|---|---|---|---|
-| OpenClaw | `ov_import` | resource 走 `/api/v1/resources` / `add_resource`;skill 走 `/api/v1/skills` | 否 | 同时覆盖 resource / skill 导入,OV 还没有完全等价的 `import` 通用工具。 |
+| OpenClaw | 原 `ov_import(kind=resource)`,现 `add_resource` | local 文件 / 目录先 `temp_upload`,再走 `/api/v1/resources`;remote URL / Git URL 直接走 `/api/v1/resources` | 是 | resource 导入已有稳定 OV 能力名和底层接口。OpenClaw 插件仍负责本地文件 / 目录上传与 zip,但 Agent 可见工具名收敛为 `add_resource`。 |
+| OpenClaw | 原 `ov_import(kind=skill)`,现 `add_skill` | local skill 文件 / 目录先 `temp_upload`,或 `data` 直接走 `/api/v1/skills` | 是 | skill 导入已有稳定 OV 能力名和底层接口,且参数与 resource 不同,拆成独立工具比 `ov_import + kind` 更清晰。 |
+| OpenClaw slash command | 原 `/ov-import`,现 `/add-resource` / `/add-skill` | 分别调用 `add_resource` / `add_skill` 执行路径 | 是 | 用户手动命令也和 Agent 可见工具名保持一致;不再用 `--kind` 在一个命令里复用两种导入语义。 |
+| OV server `/mcp` | `add_resource` | MCP tool `add_resource` 调 resource service | 已收敛 | 当前只支持 remote URL / Git URL,不支持本地 path,也没有 `add_skill`。 |
| OpenClaw | `ov_archive_search` | REST `/api/v1/search/grep` 等底层能力 | 否 | 语义是搜索当前 session history archive,不是通用 grep。 |
| OpenClaw | `ov_archive_expand` | REST `/api/v1/sessions/{id}/archives/{archive_id}` | 否 | 语义是读取当前 session archive 片段,不是通用 read。 |
| Codex MCP | 无 import / archive / browse 工具;可通过 OV `/mcp` 使用 `read` 等通用能力 | REST / MCP | 不涉及 | Codex 示例插件只保留显式 memory 四件套。 |
@@ -113,11 +116,13 @@ Remember 是写入长期记忆:把文本、消息或会话内容写入 OpenVik
| opencode skill plugin | `ov search` / `ov read` / `ov ls` / `ov rm` 等 CLI 命令 | OV CLI | 已下沉,不改名 | 这是 shell skill,不是 native tool;`ov` 是 CLI 命令名前缀,不属于 Agent 工具名收敛问题。 |
| Hermes OpenViking provider | `viking_read` / `viking_browse` / `viking_add_resource` | provider 内部调用 OpenViking read / browse / resource ingest | 不在本 PR 改 | Hermes 最新公开工具包含 read、browse、add_resource;未公开 archive_search / archive_read。 |
+`import_ovpack` 不归入普通 Agent 导入能力。它走 `POST /api/v1/pack/import`,用于导入 `.ovpack` 上下文包,更接近备份、迁移和恢复,不是聊天中“把这个文档 / skill 加入 OpenViking”的 resource / skill 导入。
+
## 本 PR 的实际收敛
- OV server `/mcp`:提供 `find` 和 `search` 两层显式搜索;`find` 是轻量检索,`search` 是 session-aware deep search。
- Codex MCP:当前暴露 `find`、`remember`、`forget`、`health`,全部不带 `viking_` 前缀。
-- OpenClaw:当前暴露 `memory_search` 并同步 `openclaw.plugin.json`;`memory_recall` 继续作为召回语义保留,不和 search 混成一个通用工具。
+- OpenClaw:当前暴露 `memory_search` 并同步 `openclaw.plugin.json`;`memory_recall` 继续作为召回语义保留,不和 search 混成一个通用工具;原 Agent 可见 `ov_import` 已拆成 `add_resource` / `add_skill`。
- 不引入新的 ToolCatalog / agent tools 抽象,不迁移 Claude Code、opencode、Hermes 的既有工具名和执行语义。
## 后续下沉原则
diff --git a/examples/openclaw-plugin/README.md b/examples/openclaw-plugin/README.md
index 8d890675f..daa4ddf6f 100644
--- a/examples/openclaw-plugin/README.md
+++ b/examples/openclaw-plugin/README.md
@@ -197,13 +197,14 @@ So `afterTurn()` is closer to "incremental append plus threshold-triggered async
## Tools and Expandability
-Beyond automatic behavior, the plugin exposes six tools directly:
+Beyond automatic behavior, the plugin exposes seven tools directly:
- `memory_recall`: explicit long-term memory search
- `memory_store`: write text into an OpenViking session and trigger commit
- `memory_forget`: delete by URI, or search first and remove a single strong match
- `ov_archive_expand`: expand a concrete archive back into raw messages
-- `ov_import`: import a resource or skill; defaults to resource and uses `kind: "skill"` for skills
+- `add_resource`: import a document, directory, URL, or Git repository as an OpenViking resource
+- `add_skill`: import or register an OpenViking agent skill
- `memory_search`: search OpenViking resources and skills, especially after importing them
They serve different roles:
@@ -212,7 +213,8 @@ They serve different roles:
- `memory_recall` gives the model an explicit follow-up search path
- `memory_store` is for immediately persisting clearly important information
- `ov_archive_expand` is the "go back to archive detail" escape hatch when summaries are not enough
-- `ov_import` lets the agent complete explicit import requests without asking the user to remember slash commands
+- `add_resource` lets the agent save explicit document or repository import requests without asking the user to remember slash commands
+- `add_skill` imports skills into OpenViking, while `add_resource` imports resources
- `memory_search` closes the loop after import by letting the user or agent confirm and consume resources and skills
`ov_archive_expand` is especially important because `assemble()` normally returns archive summaries and indexes, not the full raw transcript.
@@ -227,8 +229,8 @@ Resource and skill imports are intentionally separate because they land in diffe
The plugin also registers explicit slash commands for manual imports:
```text
-/ov-import ./README.md --to viking://resources/openviking-readme --wait
-/ov-import ./skills/install-openviking-memory --kind skill --wait
+/add-resource ./README.md --to viking://resources/openviking-readme --wait
+/add-skill ./skills/install-openviking-memory --wait
/memory-search "OpenViking install" --uri viking://resources/openviking-readme
/memory-search "memory install skill" --uri viking://agent/skills
```
diff --git a/examples/openclaw-plugin/README_CN.md b/examples/openclaw-plugin/README_CN.md
index 297f224d6..5a728f5ed 100644
--- a/examples/openclaw-plugin/README_CN.md
+++ b/examples/openclaw-plugin/README_CN.md
@@ -193,13 +193,14 @@ preflight 阶段的 `assemble()` 并不是简单地把旧聊天记录塞回来
## 工具层与可展开能力
-这套插件除了自动行为,还直接暴露了 6 个工具:
+这套插件除了自动行为,还直接暴露了 7 个工具:
- `memory_recall`:显式检索长期记忆
- `memory_store`:把文本写入 OpenViking session 并立即触发 commit
- `memory_forget`:按 URI 删除,或先搜索再删除唯一高置信候选
- `ov_archive_expand`:展开某个 archive 的原始消息
-- `ov_import`:导入 resource 或 skill;默认 resource,导入 skill 时使用 `kind: "skill"`
+- `add_resource`:把文档、目录、URL 或 Git 仓库导入为 OpenViking resource
+- `add_skill`:导入或注册 OpenViking agent skill
- `memory_search`:检索 OpenViking resources 和 skills,尤其用于导入后的确认和消费
它们各自的作用不同:
@@ -208,7 +209,8 @@ preflight 阶段的 `assemble()` 并不是简单地把旧聊天记录塞回来
- `memory_recall` 给模型一个显式补查入口。
- `memory_store` 适合把一段明确的重要信息立刻落入记忆管线。
- `ov_archive_expand` 负责在 summary 不够细时回到 archive 级原文。
-- `ov_import` 让 agent 在用户明确提出导入需求时直接完成操作,不要求用户记住 slash command。
+- `add_resource` 让 agent 在用户明确提出文档或仓库导入需求时直接完成操作,不要求用户记住 slash command。
+- `add_skill` 把 skill 导入 OpenViking,`add_resource` 把文档、目录、URL 或 Git 仓库导入为 resource。
- `memory_search` 补齐导入后的使用闭环,让用户或 agent 可以确认并消费 resources 和 skills。
其中 `ov_archive_expand` 是 `assemble()` 的重要补充,因为 `assemble()` 默认给的是压缩后的索引和摘要,而不是完整历史正文。
@@ -223,8 +225,8 @@ Resource 和 skill 保持两个入口,因为它们落在不同 OpenViking 命
插件也提供显式 slash command,方便手动导入:
```text
-/ov-import ./README.md --to viking://resources/openviking-readme --wait
-/ov-import ./skills/install-openviking-memory --kind skill --wait
+/add-resource ./README.md --to viking://resources/openviking-readme --wait
+/add-skill ./skills/install-openviking-memory --wait
/memory-search "OpenViking install" --uri viking://resources/openviking-readme
/memory-search "memory install skill" --uri viking://agent/skills
```
diff --git a/examples/openclaw-plugin/DISCUSSION-ov-import.md b/examples/openclaw-plugin/docs/oc-resource-skill-import-design.md
similarity index 82%
rename from examples/openclaw-plugin/DISCUSSION-ov-import.md
rename to examples/openclaw-plugin/docs/oc-resource-skill-import-design.md
index 0ffcb5167..bf1c2e4e3 100644
--- a/examples/openclaw-plugin/DISCUSSION-ov-import.md
+++ b/examples/openclaw-plugin/docs/oc-resource-skill-import-design.md
@@ -1,5 +1,7 @@
# [RFC] OpenClaw Plugin 支持通过 OpenViking 导入/查询 Resource 与 Skill
+> 当前实现已调整:Agent 可见工具不再使用统一的 `ov_import(kind=...)`,而是拆为 `add_resource` 和 `add_skill`;手动 slash command 也对应拆为 `/add-resource` 和 `/add-skill`,不再保留 `/ov-import`。
+
## 背景
当前 `examples/openclaw-plugin` 已经承担 OpenClaw 与 OpenViking 的 context-engine 集成,包括 session context、memory recall/store/forget、archive expand,以及 local/remote OpenViking runtime 管理。
@@ -15,10 +17,10 @@
1. 在 OpenClaw 中支持通过插件导入 OpenViking resource。
2. 在 OpenClaw 中支持通过插件导入 OpenViking skill。
-3. 为简化使用,对外合并为一个统一入口:
- - LLM tool:`ov_import`
- - slash command:`/ov-import`
-4. 通过参数 `kind: "resource" | "skill"` 区分导入类型,默认 `resource`。
+3. 对外拆成两个明确入口:
+ - resource:LLM tool `add_resource`,slash command `/add-resource`
+ - skill:LLM tool `add_skill`,slash command `/add-skill`
+4. 不再通过 `kind: "resource" | "skill"` 在一个入口里分流。
5. 保持 HTTP server 的本地路径安全边界:不把本地路径直接发给 OpenViking 服务端。
6. 底层仍复用 `OpenVikingClient.addResource()` / `OpenVikingClient.addSkill()`,避免在 resource 和 skill 之间复制上传逻辑。
7. 导入后提供检索入口,让用户能在 OpenClaw 内确认和消费已导入 resource 与 skill。
@@ -73,68 +75,47 @@ HTTP 安全边界是:直接通过 HTTP 调 `/api/v1/skills` 时,不能传宿
## 设计方案
-### 1. 对外合并为一个入口
-
-为简化用户和 LLM 的使用成本,对外只暴露一个导入入口:
-
-- LLM tool:`ov_import`
-- slash command:`/ov-import`
-
-使用 `kind` 参数区分导入类型:
-
-```ts
-kind?: "resource" | "skill";
-```
+### 1. 对外拆成两个入口
-默认:
+Resource 和 skill 的落点、参数和服务端 API 不同,对外暴露两个入口:
-```ts
-kind = "resource";
-```
+- resource:LLM tool `add_resource`,slash command `/add-resource`
+- skill:LLM tool `add_skill`,slash command `/add-skill`
-这样最常见的 resource 导入不需要额外指定类型:
+Resource 导入:
```text
-/ov-import ./README.md --to viking://resources/openviking-readme --wait
+/add-resource ./README.md --to viking://resources/openviking-readme --wait
```
-导入 skill 时显式指定:
+Skill 导入:
```text
-/ov-import ./skills/install-openviking-memory --kind skill --wait
+/add-skill ./skills/install-openviking-memory --wait
```
-### 2. 为什么不拆成两个入口
-
-最初也可以设计为:
-
-- `ov_resource_import`
-- `ov_skill_import`
+### 2. 为什么拆成两个入口
-但讨论后更倾向统一入口,原因是:
+- 工具名直接对应 OV 已有能力名:`add_resource` / `add_skill`
+- schema 不再混入 `kind`、`data`、`to`、`parent` 这类互斥参数
+- 用户手动命令也不再靠 `--kind skill` 切换语义
+- 底层仍复用 `OpenVikingClient.addResource()` / `addSkill()`,不复制上传逻辑
-- 用户只需要记一个命令:`/ov-import`
-- LLM 只需要学习一个工具:`ov_import`
-- 默认 resource 符合更常见的导入场景
-- `kind=skill` 仍然是显式选择,不依赖完全自动猜测
-- 底层实现仍然区分 resource 与 skill,不牺牲语义清晰度
-
-换句话说:对外入口合并,对内处理分流。
+换句话说:对外和对内都保持 resource / skill 分离。
### 3. LLM Tool 参数设计
新增工具:
```text
-ov_import
+add_resource
+add_skill
```
参数:
```ts
{
- kind?: "resource" | "skill"; // default: resource
-
// resource 或 skill path 模式共用
source?: string; // local path, directory path, public URL, Git URL
@@ -155,13 +136,12 @@ ov_import
校验规则:
-- `kind` 为空时按 `resource`。
-- `kind=resource`:
+- `add_resource`:
- 必须提供 `source`
- `source` 可为本地路径、目录、远程 URL 或 Git URL
- `to` 与 `parent` 互斥
- 忽略或拒绝 `data`
-- `kind=skill`:
+- `add_skill`:
- 必须提供 `source` 或 `data`
- `source` 可为本地 `SKILL.md`、skill 目录或 zip
- `data` 可为 raw `SKILL.md` 或 MCP tool dict
@@ -180,7 +160,7 @@ Resource 的导入路径由 `to` 或 `parent` 控制,二者互斥:
推荐用户在希望得到稳定引用 URI 时使用 `to`:
```text
-/ov-import ./README.md --to viking://resources/openviking-readme --wait
+/add-resource ./README.md --to viking://resources/openviking-readme --wait
```
结果会尽量落到:
@@ -192,7 +172,7 @@ viking://resources/openviking-readme
如果只想把资源放到某个集合下,可使用 `parent`:
```text
-/ov-import ./README.md --parent viking://resources/docs --wait
+/add-resource ./README.md --parent viking://resources/docs --wait
```
结果会落在类似:
@@ -206,26 +186,27 @@ viking://resources/docs/README
新增命令:
```text
-/ov-import <source> [--kind resource|skill] [--to URI] [--parent URI] [--reason TEXT] [--instruction TEXT] [--wait] [--timeout SEC]
+/add-resource <source> [--to URI] [--parent URI] [--reason TEXT] [--instruction TEXT] [--wait] [--timeout SEC]
+/add-skill <source> [--wait] [--timeout SEC]
```
-默认 resource:
+导入 resource:
```text
-/ov-import ./README.md --to viking://resources/openviking-readme --wait
+/add-resource ./README.md --to viking://resources/openviking-readme --wait
```
导入远程 resource:
```text
-/ov-import https://github.com/volcengine/OpenViking --to viking://resources/openviking-repo --reason "OpenViking source docs"
+/add-resource https://github.com/volcengine/OpenViking --to viking://resources/openviking-repo --reason "OpenViking source docs"
```
导入 skill:
```text
-/ov-import ./skills/install-openviking-memory --kind skill --wait
-/ov-import ./SKILL.md --kind skill --wait
+/add-skill ./skills/install-openviking-memory --wait
+/add-skill ./SKILL.md --wait
```
Slash command 暂不支持 raw multi-line `SKILL.md` 或 MCP dict JSON;如果需要导入这些结构化数据,使用 LLM tool 的 `data` 参数。
@@ -249,13 +230,11 @@ preserveStructure?: boolean;
- `addResource(input)`
- `addSkill(input)`
-`ov_import` 工具和 `/ov-import` 命令根据 `kind` 分流:
+`add_resource` 和 `add_skill` 分别调用底层 client 方法:
```ts
-if (kind === "skill") {
- return client.addSkill(...);
-}
-return client.addResource(...);
+add_resource -> client.addResource(...)
+add_skill -> client.addSkill(...)
```
本地文件/目录流程:
@@ -293,7 +272,7 @@ raw SKILL.md or MCP dict
### 8. 导入后的检索入口:memory_search
-只提供 `ov_import` 会让体验不闭环:用户可以把 resource 或 skill 导入 OpenViking,但在 OpenClaw 内不一定知道如何检索、读取或验证导入结果。
+只提供导入工具会让体验不闭环:用户可以把 resource 或 skill 导入 OpenViking,但在 OpenClaw 内不一定知道如何检索、读取或验证导入结果。
因此建议同时讨论一个轻量检索入口:
@@ -306,9 +285,9 @@ raw SKILL.md or MCP dict
2. 返回 resource 的 `root_uri` 或 skill 的 `uri`。
3. 用户或 LLM 可以立刻按返回 URI 检索。
-#### ov_import 返回建议
+#### add_resource 返回建议
-`ov_import` 导入 resource 后,结果中应包含:
+`add_resource` 导入 resource 后,结果中应包含:
- `root_uri`
- `status`
@@ -324,7 +303,7 @@ Processing: completed
Try: /memory-search "OpenViking install" --uri viking://resources/openviking-readme
```
-`ov_import` 导入 skill 后也应返回 skill URI,并给出 skill 检索建议:
+`add_skill` 导入 skill 后也应返回 skill URI,并给出 skill 检索建议:
```text
Imported OpenViking skill: viking://agent/skills/install-openviking-memory
@@ -541,19 +520,16 @@ v1 暂不加入,避免把导入 RFC 扩展成完整 OpenViking CLI replica。
- raw `SKILL.md` 通过 `data` 直传
- MCP tool dict 通过 `data` 直传
-覆盖 `ov_import`:
+覆盖 `add_resource` / `add_skill`:
-- 注册单个 tool:`ov_import`
-- 注册单个 command:`/ov-import`
-- `kind` 默认 `resource`
-- `kind=skill` 正确分流到 `addSkill`
-- `--kind skill`
+- 注册 tool:`add_resource` / `add_skill`
+- 注册 command:`/add-resource` / `/add-skill`
- quoted args
- `--flag`
- `--key value`
- `--key=value`
- `--to` 与 `--parent` 冲突
-- `kind=skill` 时拒绝 `to`、`parent`、`reason`、`instruction`
+- `/add-skill` 拒绝 `to`、`parent`、`reason`、`instruction`
覆盖 `memory_search`:
@@ -567,9 +543,9 @@ v1 暂不加入,避免把导入 RFC 扩展成完整 OpenViking CLI replica。
### Manual smoke
```text
-/ov-import ./README.md --to viking://resources/openviking-readme --wait
+/add-resource ./README.md --to viking://resources/openviking-readme --wait
/memory-search "OpenViking install" --uri viking://resources/openviking-readme
-/ov-import ./skills/install-openviking-memory --kind skill --wait
+/add-skill ./skills/install-openviking-memory --wait
/memory-search "install OpenViking memory" --uri viking://agent/skills
```
@@ -585,13 +561,13 @@ v1 暂不加入,避免把导入 RFC 扩展成完整 OpenViking CLI replica。
## 待讨论问题
-1. `ov_import` 是否应默认 `wait=false`?
+1. `add_resource` / `add_skill` 是否应默认 `wait=false`?
- 当前建议默认不等待,只有用户显式要求“等待处理完成”或传 `wait=true` 时才等待。
-2. `kind=skill` 时 resource-only 参数应直接报错,还是静默忽略?
+2. `/add-skill` 遇到 resource-only 参数应直接报错,还是静默忽略?
- 当前建议直接报错,避免用户误以为 `to/parent` 对 skill 生效。
3. 是否需要插件侧自动识别 skill?
- - 可选增强:当本地文件名为 `SKILL.md` 或目录包含 `SKILL.md` 时自动设置 `kind=skill`。
- - 但当前建议先使用显式 `--kind skill`,默认 resource,行为更可解释。
+ - 可选增强:当本地文件名为 `SKILL.md` 或目录包含 `SKILL.md` 时提示用户使用 `/add-skill` 或 agent tool `add_skill`。
+ - 当前建议先使用显式 `/add-skill`,避免在 `/add-resource` 中自动猜测并改变用户意图。
4. 导入本地大目录前是否需要确认机制?
- 当前方案先不加确认;后续可基于文件数量/zip 大小增加保护。
5. `memory_search` v1 是否默认检索 `viking://resources` 和 `viking://agent/skills`?
diff --git a/examples/openclaw-plugin/index.ts b/examples/openclaw-plugin/index.ts
index 3069bdd91..93fde75c9 100644
--- a/examples/openclaw-plugin/index.ts
+++ b/examples/openclaw-plugin/index.ts
@@ -127,12 +127,8 @@ type CommandDefinition = {
handler: (ctx: PluginCommandContext) => CommandResult | Promise<CommandResult>;
};
-type OvImportKind = "resource" | "skill";
-
-type OvImportInput = {
- kind?: OvImportKind;
+type AddResourceToolInput = {
source?: string;
- data?: unknown;
to?: string;
parent?: string;
reason?: string;
@@ -141,6 +137,13 @@ type OvImportInput = {
timeout?: number;
};
+type AddSkillToolInput = {
+ source?: string;
+ data?: unknown;
+ wait?: boolean;
+ timeout?: number;
+};
+
type MemorySearchInput = {
query: string;
uri?: string;
@@ -304,16 +307,6 @@ function getBoolFlag(flags: Map<string, string | boolean>, name: string): boolea
return flags.get(name) === true;
}
-function parseImportKind(value: string | undefined): OvImportKind {
- if (!value) {
- return "resource";
- }
- if (value === "resource" || value === "skill") {
- return value;
- }
- throw new Error("--kind must be resource or skill");
-}
-
function extractToolSenderId(ctx: unknown): string | undefined {
if (!ctx || typeof ctx !== "object") {
return undefined;
@@ -334,24 +327,19 @@ function extractToolSenderId(ctx: unknown): string | undefined {
return undefined;
}
-export function parseOvImportCommandArgs(args: string): OvImportInput {
+export function parseAddResourceCommandArgs(args: string): AddResourceToolInput {
const parsed = parseFlagArgs(args);
- const kind = parseImportKind(getStringFlag(parsed.flags, "kind"));
const source =
parsed.positionals.length <= 1 ? parsed.positionals[0] : parsed.positionals.join(" ").trim();
if (!source) {
- throw new Error("Usage: /ov-import <source> [--kind resource|skill] [--to URI] [--parent URI] [--wait]");
+ throw new Error("Usage: /add-resource <source> [--to URI] [--parent URI] [--reason TEXT] [--instruction TEXT] [--wait] [--timeout SEC]");
}
const to = getStringFlag(parsed.flags, "to");
const parent = getStringFlag(parsed.flags, "parent");
if (to && parent) {
throw new Error("Cannot specify both --to and --parent.");
}
- if (kind === "skill" && (to || parent || parsed.flags.has("reason") || parsed.flags.has("instruction"))) {
- throw new Error("--to, --parent, --reason, and --instruction are resource-only options.");
- }
return {
- kind,
source,
to,
parent,
@@ -362,6 +350,23 @@ export function parseOvImportCommandArgs(args: string): OvImportInput {
};
}
+export function parseAddSkillCommandArgs(args: string): AddSkillToolInput {
+ const parsed = parseFlagArgs(args);
+ const source =
+ parsed.positionals.length <= 1 ? parsed.positionals[0] : parsed.positionals.join(" ").trim();
+ if (!source) {
+ throw new Error("Usage: /add-skill <source> [--wait] [--timeout SEC]");
+ }
+ if (parsed.flags.has("to") || parsed.flags.has("parent") || parsed.flags.has("reason") || parsed.flags.has("instruction")) {
+ throw new Error("--to, --parent, --reason, and --instruction are resource-only options.");
+ }
+ return {
+ source,
+ wait: getBoolFlag(parsed.flags, "wait"),
+ timeout: getNumberFlag(parsed.flags, "timeout"),
+ };
+}
+
export function parseMemorySearchCommandArgs(args: string): MemorySearchInput {
const parsed = parseFlagArgs(args);
// `/memory-search` only accepts a single query string, so positional segments are
@@ -678,23 +683,8 @@ const contextEnginePlugin = {
};
};
- const executeImport = async (input: OvImportInput, agentId?: string) => {
- const kind = input.kind ?? "resource";
- if (kind === "skill") {
- if (input.to || input.parent || input.reason || input.instruction) {
- throw new Error("to, parent, reason, and instruction are resource-only options.");
- }
- return importSkill({
- path: input.source,
- data: input.data,
- wait: input.wait,
- timeout: input.timeout,
- }, agentId);
- }
- if (input.data !== undefined && input.data !== null) {
- throw new Error("data is only supported for skill imports.");
- }
- return importResource({
+ const addResourceOpenViking = (input: AddResourceToolInput, agentId?: string) =>
+ importResource({
pathOrUrl: input.source ?? "",
to: input.to,
parent: input.parent,
@@ -703,24 +693,31 @@ const contextEnginePlugin = {
wait: input.wait,
timeout: input.timeout,
}, agentId);
- };
-const mergeFindResults = (results: FindResult[]): FindResult => {
- const deduplicate = (items: FindResultItem[]): FindResultItem[] => {
- const seen = new Map<string, FindResultItem>();
- for (const item of items) {
- if (!seen.has(item.uri)) {
- seen.set(item.uri, item);
- }
- }
- return Array.from(seen.values());
- };
- const memories = deduplicate(results.flatMap((result) => result.memories ?? []));
- const resources = deduplicate(results.flatMap((result) => result.resources ?? []));
- const skills = deduplicate(results.flatMap((result) => result.skills ?? []));
- return {
- memories,
- resources,
+ const addSkillOpenViking = (input: AddSkillToolInput, agentId?: string) =>
+ importSkill({
+ path: input.source,
+ data: input.data,
+ wait: input.wait,
+ timeout: input.timeout,
+ }, agentId);
+
+ const mergeFindResults = (results: FindResult[]): FindResult => {
+ const deduplicate = (items: FindResultItem[]): FindResultItem[] => {
+ const seen = new Map<string, FindResultItem>();
+ for (const item of items) {
+ if (!seen.has(item.uri)) {
+ seen.set(item.uri, item);
+ }
+ }
+ return Array.from(seen.values());
+ };
+ const memories = deduplicate(results.flatMap((result) => result.memories ?? []));
+ const resources = deduplicate(results.flatMap((result) => result.resources ?? []));
+ const skills = deduplicate(results.flatMap((result) => result.skills ?? []));
+ return {
+ memories,
+ resources,
skills,
total: memories.length + resources.length + skills.length,
};
@@ -836,31 +833,27 @@ const mergeFindResults = (results: FindResult[]): FindResult => {
api.registerTool(
(ctx: ToolContext) => ({
- name: "ov_import",
- label: "Import (OpenViking)",
+ name: "add_resource",
+ label: "Add Resource (OpenViking)",
description:
- "Import an OpenViking resource or skill only when the user explicitly asks to import, add, or index one. " +
- "Defaults to resource; set kind=skill for SKILL.md, skill directories, raw skill content, or MCP tool dicts.",
+ "Use only when the user explicitly asks to import, add, upload, save, or index a document, directory, URL, Git repository, or OpenClaw media attachment into OpenViking resources. " +
+ "For a '[media attached: /path ...]' document, set source to that exact local media path. Do not invent OpenViking upload REST endpoints.",
parameters: Type.Object({
- kind: Type.Optional(Type.Union([Type.Literal("resource"), Type.Literal("skill")], { description: "Import kind. Default: resource" })),
- source: Type.Optional(Type.String({ description: "Local path, directory path, public URL, or Git URL" })),
- data: Type.Optional(Type.Any({ description: "Skill only: raw SKILL.md content or MCP tool dict" })),
- to: Type.Optional(Type.String({ description: "Resource only: exact target URI, e.g. viking://resources/project-docs" })),
- parent: Type.Optional(Type.String({ description: "Resource only: parent URI under viking://resources" })),
- reason: Type.Optional(Type.String({ description: "Resource only: reason or note for adding this resource" })),
- instruction: Type.Optional(Type.String({ description: "Resource only: processing instruction for semantic extraction" })),
+ source: Type.String({ description: "Local path, OpenClaw media attachment path, directory path, public URL, or Git URL" }),
+ to: Type.Optional(Type.String({ description: "Exact target URI, e.g. viking://resources/project-docs" })),
+ parent: Type.Optional(Type.String({ description: "Parent URI under viking://resources" })),
+ reason: Type.Optional(Type.String({ description: "Reason or note for adding this resource" })),
+ instruction: Type.Optional(Type.String({ description: "Processing instruction for semantic extraction" })),
wait: Type.Optional(Type.Boolean({ description: "Wait for processing to complete" })),
timeout: Type.Optional(Type.Number({ description: "Timeout in seconds when wait is true" })),
}),
async execute(_toolCallId: string, params: Record<string, unknown>) {
if (isBypassedSession(ctx)) {
- return makeBypassedToolResult("ov_import");
+ return makeBypassedToolResult("add_resource");
}
const session = resolvePluginSessionRouting(ctx);
- return executeImport({
- kind: params.kind === "skill" ? "skill" : "resource",
+ return addResourceOpenViking({
source: typeof params.source === "string" ? params.source : undefined,
- data: params.data,
to: typeof params.to === "string" ? params.to : undefined,
parent: typeof params.parent === "string" ? params.parent : undefined,
reason: typeof params.reason === "string" ? params.reason : undefined,
@@ -870,7 +863,36 @@ const mergeFindResults = (results: FindResult[]): FindResult => {
}, session.agentId);
},
}),
- { name: "ov_import" },
+ { name: "add_resource" },
+ );
+
+ api.registerTool(
+ (ctx: ToolContext) => ({
+ name: "add_skill",
+ label: "Add Skill (OpenViking)",
+ description:
+ "Use only when the user explicitly asks to import, add, install, or register a skill into OpenViking. " +
+ "Set source to a local SKILL.md file or skill directory, or data to raw SKILL.md content or an MCP tool dict.",
+ parameters: Type.Object({
+ source: Type.Optional(Type.String({ description: "Local SKILL.md path or skill directory path" })),
+ data: Type.Optional(Type.Any({ description: "Raw SKILL.md content or MCP tool dict" })),
+ wait: Type.Optional(Type.Boolean({ description: "Wait for processing to complete" })),
+ timeout: Type.Optional(Type.Number({ description: "Timeout in seconds when wait is true" })),
+ }),
+ async execute(_toolCallId: string, params: Record<string, unknown>) {
+ if (isBypassedSession(ctx)) {
+ return makeBypassedToolResult("add_skill");
+ }
+ const session = resolvePluginSessionRouting(ctx);
+ return addSkillOpenViking({
+ source: typeof params.source === "string" ? params.source : undefined,
+ data: params.data,
+ wait: typeof params.wait === "boolean" ? params.wait : undefined,
+ timeout: typeof params.timeout === "number" ? params.timeout : undefined,
+ }, session.agentId);
+ },
+ }),
+ { name: "add_skill" },
);
api.registerTool(
@@ -900,21 +922,41 @@ const mergeFindResults = (results: FindResult[]): FindResult => {
);
api.registerCommand?.({
- name: "ov-import",
- description: "Import a resource or skill into OpenViking.",
+ name: "add-resource",
+ description: "Add a resource into OpenViking.",
+ acceptsArgs: true,
+ handler: async (ctx: PluginCommandContext) => {
+ try {
+ if (isBypassedSession(ctx)) {
+ const bypassed = makeBypassedToolResult("add_resource");
+ return { text: bypassed.content[0]!.text, details: bypassed.details };
+ }
+ const session = resolvePluginSessionRouting(ctx);
+ const input = parseAddResourceCommandArgs(ctx.args ?? "");
+ const result = await addResourceOpenViking(input, session.agentId);
+ return { text: result.content[0]!.text, details: result.details };
+ } catch (err) {
+ return { text: `OpenViking add resource failed: ${err instanceof Error ? err.message : String(err)}` };
+ }
+ },
+ });
+
+ api.registerCommand?.({
+ name: "add-skill",
+ description: "Add a skill into OpenViking.",
acceptsArgs: true,
handler: async (ctx: PluginCommandContext) => {
try {
if (isBypassedSession(ctx)) {
- const bypassed = makeBypassedToolResult("ov_import");
+ const bypassed = makeBypassedToolResult("add_skill");
return { text: bypassed.content[0]!.text, details: bypassed.details };
}
const session = resolvePluginSessionRouting(ctx);
- const input = parseOvImportCommandArgs(ctx.args ?? "");
- const result = await executeImport(input, session.agentId);
+ const input = parseAddSkillCommandArgs(ctx.args ?? "");
+ const result = await addSkillOpenViking(input, session.agentId);
return { text: result.content[0]!.text, details: result.details };
} catch (err) {
- return { text: `OpenViking import failed: ${err instanceof Error ? err.message : String(err)}` };
+ return { text: `OpenViking add skill failed: ${err instanceof Error ? err.message : String(err)}` };
}
},
});
diff --git a/examples/openclaw-plugin/openclaw.plugin.json b/examples/openclaw-plugin/openclaw.plugin.json
index c5f32807e..5a732aeab 100644
--- a/examples/openclaw-plugin/openclaw.plugin.json
+++ b/examples/openclaw-plugin/openclaw.plugin.json
@@ -12,7 +12,8 @@
},
"contracts": {
"tools": [
- "ov_import",
+ "add_resource",
+ "add_skill",
"memory_search",
"memory_recall",
"memory_store",
diff --git a/examples/openclaw-plugin/tests/ut/tools.test.ts b/examples/openclaw-plugin/tests/ut/tools.test.ts
index e6b001ef1..5f9913d23 100644
--- a/examples/openclaw-plugin/tests/ut/tools.test.ts
+++ b/examples/openclaw-plugin/tests/ut/tools.test.ts
@@ -1,7 +1,11 @@
import { afterEach, describe, expect, it, vi } from "vitest";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
import contextEnginePlugin, {
- parseOvImportCommandArgs,
+ parseAddResourceCommandArgs,
+ parseAddSkillCommandArgs,
parseMemorySearchCommandArgs,
tokenizeCommandArgs,
} from "../../index.js";
@@ -335,20 +339,41 @@ describe("Tool: ov_archive_expand (behavioral)", () => {
});
});
-describe("Tool: ov_import and memory_search (registration)", () => {
- it("registers unified import tool with expected parameters", () => {
+describe("Tool: add_resource, add_skill, and memory_search (registration)", () => {
+ it("registers add_resource tool with expected parameters", () => {
const { tools, api } = setupPlugin();
contextEnginePlugin.register(api as any);
- const tool = tools.get("ov_import");
+ const tool = tools.get("add_resource");
expect(tool).toBeDefined();
expect(tool!.description).toContain("explicitly asks");
+ expect(tool!.description).toContain("[media attached: /path");
+ expect(tool!.description).toContain("Do not invent OpenViking upload REST endpoints");
const props = (tool!.parameters as any).properties;
- expect(props).toHaveProperty("kind");
expect(props).toHaveProperty("source");
- expect(props).toHaveProperty("data");
+ expect(props.source.description).toContain("OpenClaw media attachment path");
expect(props).toHaveProperty("to");
expect(props).toHaveProperty("parent");
+ expect(props).toHaveProperty("reason");
+ expect(props).toHaveProperty("instruction");
+ expect(props).toHaveProperty("wait");
+ });
+
+ it("registers add_skill tool with expected parameters", () => {
+ const { tools, api } = setupPlugin();
+ contextEnginePlugin.register(api as any);
+ const tool = tools.get("add_skill");
+ expect(tool).toBeDefined();
+ expect(tool!.description).toContain("explicitly asks");
+ expect(tool!.description).toContain("into OpenViking");
+ expect(tool!.description).toContain("SKILL.md");
+ expect(tool!.description).toContain("MCP tool dict");
+ const props = (tool!.parameters as any).properties;
+ expect(props).toHaveProperty("source");
+ expect(props).toHaveProperty("data");
expect(props).toHaveProperty("wait");
+ expect(props).toHaveProperty("timeout");
+ expect(props).not.toHaveProperty("to");
+ expect(props).not.toHaveProperty("parent");
});
it("registers memory_search tool with natural-language trigger guidance", () => {
@@ -536,21 +561,19 @@ describe("OpenViking import command parsing", () => {
it("preserves Windows path backslashes in slash-command args", () => {
expect(
- parseOvImportCommandArgs(String.raw`C:\Users\alice\skill-dir --kind skill --wait`),
+ parseAddSkillCommandArgs(String.raw`C:\Users\alice\skill-dir --wait`),
).toMatchObject({
- kind: "skill",
source: String.raw`C:\Users\alice\skill-dir`,
wait: true,
});
});
- it("parses ov-import resource flags with resource default", () => {
+ it("parses add-resource flags", () => {
expect(
- parseOvImportCommandArgs(
+ parseAddResourceCommandArgs(
`./README.md --to viking://resources/readme --reason "project docs" --instruction='summarize APIs' --wait`,
),
).toMatchObject({
- kind: "resource",
source: "./README.md",
to: "viking://resources/readme",
reason: "project docs",
@@ -561,11 +584,10 @@ describe("OpenViking import command parsing", () => {
it("keeps unquoted space-containing import sources intact", () => {
expect(
- parseOvImportCommandArgs(
+ parseAddResourceCommandArgs(
`My Docs/README.md --to viking://resources/readme`,
),
).toMatchObject({
- kind: "resource",
source: "My Docs/README.md",
to: "viking://resources/readme",
});
@@ -573,13 +595,12 @@ describe("OpenViking import command parsing", () => {
it("rejects resource import with both to and parent", () => {
expect(() =>
- parseOvImportCommandArgs("./README.md --to viking://resources/a --parent viking://resources"),
+ parseAddResourceCommandArgs("./README.md --to viking://resources/a --parent viking://resources"),
).toThrow("Cannot specify both");
});
- it("parses ov-import skill flags", () => {
- expect(parseOvImportCommandArgs("./skills/demo --kind skill --wait --timeout=30")).toMatchObject({
- kind: "skill",
+ it("parses add-skill flags", () => {
+ expect(parseAddSkillCommandArgs("./skills/demo --wait --timeout=30")).toMatchObject({
source: "./skills/demo",
wait: true,
timeout: 30,
@@ -588,7 +609,7 @@ describe("OpenViking import command parsing", () => {
it("rejects resource-only flags for skill imports", () => {
expect(() =>
- parseOvImportCommandArgs("./skills/demo --kind skill --to viking://resources/nope"),
+ parseAddSkillCommandArgs("./skills/demo --to viking://resources/nope"),
).toThrow("resource-only");
});
});
@@ -611,18 +632,22 @@ describe("OpenViking memory_search command parsing", () => {
});
describe("Plugin registration", () => {
- it("registers all 7 tools", () => {
+ it("registers all 8 tools", () => {
const { api } = setupPlugin();
contextEnginePlugin.register(api as any);
- expect(api.registerTool).toHaveBeenCalledTimes(7);
+ expect(api.registerTool).toHaveBeenCalledTimes(8);
});
- it("registers import and search commands", () => {
+ it("registers add and search commands", () => {
const { commands, api } = setupPlugin();
contextEnginePlugin.register(api as any);
- expect(commands.get("ov-import")).toMatchObject({
+ expect(commands.get("add-resource")).toMatchObject({
acceptsArgs: true,
- description: "Import a resource or skill into OpenViking.",
+ description: "Add a resource into OpenViking.",
+ });
+ expect(commands.get("add-skill")).toMatchObject({
+ acceptsArgs: true,
+ description: "Add a skill into OpenViking.",
});
expect(commands.get("memory-search")).toMatchObject({
acceptsArgs: true,
@@ -630,18 +655,23 @@ describe("Plugin registration", () => {
});
});
- it("import and search commands return usage errors when args are missing", async () => {
+ it("add and search commands return usage errors when args are missing", async () => {
const { commands, api } = setupPlugin();
contextEnginePlugin.register(api as any);
- const resource = await commands.get("ov-import")!.handler({
+ const resource = await commands.get("add-resource")!.handler({
args: "",
- commandBody: "/ov-import",
+ commandBody: "/add-resource",
+ });
+ const skill = await commands.get("add-skill")!.handler({
+ args: "",
+ commandBody: "/add-skill",
});
const search = await commands.get("memory-search")!.handler({
args: "",
commandBody: "/memory-search",
});
- expect(resource.text).toContain("Usage: /ov-import");
+ expect(resource.text).toContain("Usage: /add-resource");
+ expect(skill.text).toContain("Usage: /add-skill");
expect(search.text).toContain("Usage: /memory-search");
});
@@ -702,7 +732,7 @@ describe("Plugin registration", () => {
expect(headers.get("X-OpenViking-Agent")).toBe("worker");
});
- it("import tool propagates configured tenant headers for resource imports", async () => {
+ it("add_resource propagates configured tenant headers", async () => {
const fetchMock = vi.fn(async () =>
okResponse({ root_uri: "viking://resources/shared-docs", status: "success" }),
);
@@ -716,9 +746,8 @@ describe("Plugin registration", () => {
};
contextEnginePlugin.register(api as any);
- const tool = tools.get("ov_import")!;
- await tool.execute("tc-import", {
- kind: "resource",
+ const tool = tools.get("add_resource")!;
+ await tool.execute("tc-add-resource", {
source: "https://example.com/docs",
to: "viking://resources/shared-docs",
wait: true,
@@ -730,6 +759,67 @@ describe("Plugin registration", () => {
expect(headers.get("X-OpenViking-User")).toBe("alice");
});
+ it("add_resource uploads local media attachment paths as resources", async () => {
+ const tempDir = await mkdtemp(join(tmpdir(), "openclaw-media-"));
+ const filePath = join(tempDir, "大秦-TOP20.xlsx");
+ await writeFile(filePath, "spreadsheet bytes");
+
+ const fetchMock = vi
+ .fn()
+ .mockResolvedValueOnce(okResponse({ temp_file_id: "upload_sheet.xlsx" }))
+ .mockResolvedValueOnce(okResponse({ root_uri: "viking://resources/sheet", status: "success" }));
+ vi.stubGlobal("fetch", fetchMock);
+
+ try {
+ const { tools, api } = setupPlugin();
+ contextEnginePlugin.register(api as any);
+
+ const tool = tools.get("add_resource")!;
+ const result = await tool.execute("tc-add-resource-local-media", {
+ source: filePath,
+ wait: true,
+ }) as ToolResult;
+
+ expect(result.content[0]!.text).toContain("Imported OpenViking resource");
+ expect(fetchMock.mock.calls[0]![0]).toBe("http://127.0.0.1:1933/api/v1/resources/temp_upload");
+ expect(fetchMock.mock.calls[1]![0]).toBe("http://127.0.0.1:1933/api/v1/resources");
+ const body = JSON.parse(String(fetchMock.mock.calls[1]![1]!.body));
+ expect(body).toMatchObject({
+ temp_file_id: "upload_sheet.xlsx",
+ wait: true,
+ });
+ } finally {
+ await rm(tempDir, { recursive: true, force: true });
+ }
+ });
+
+ it("add_skill posts skill imports to the skills API", async () => {
+ const fetchMock = vi.fn(async () =>
+ okResponse({ uri: "viking://agent/skills/demo", name: "demo" }),
+ );
+ vi.stubGlobal("fetch", fetchMock);
+
+ const { tools, api } = setupPlugin();
+ contextEnginePlugin.register(api as any);
+
+ const tool = tools.get("add_skill")!;
+ const result = await tool.execute("tc-add-skill", {
+ data: "name: demo\n",
+ wait: true,
+ timeout: 30,
+ }) as ToolResult;
+
+ expect(result.content[0]!.text).toContain("Imported OpenViking skill");
+ const [url, init] = fetchMock.mock.calls.find((call) => String(call[0]).endsWith("/api/v1/skills")) as [string, RequestInit];
+ expect(url).toBe("http://127.0.0.1:1933/api/v1/skills");
+ const body = JSON.parse(String(init.body));
+ expect(body).toMatchObject({
+ data: "name: demo\n",
+ wait: true,
+ timeout: 30,
+ });
+ });
+
it("slash commands honor bypassSessionPatterns", async () => {
const fetchMock = vi.fn(async () => okResponse({}));
vi.stubGlobal("fetch", fetchMock);