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
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.mdindex 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.mdindex 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 themThey 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 diffeThe 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.mdindex 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.mdsimilarity index 82%rename from examples/openclaw-plugin/DISCUSSION-ov-import.mdrename to examples/openclaw-plugin/docs/oc-resource-skill-import-design.mdindex 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 dict2. 返回 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: completedTry: /memory-search "OpenViking install" --uri viking://resources/openviking-readme```-`ov_import` 导入 skill 后也应返回 skill URI,并给出 skill 检索建议:+`add_skill` 导入 skill 后也应返回 skill URI,并给出 skill 检索建议:```textImported 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.tsindex 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): booleareturn 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.jsonindex 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.tsindex 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);