@openviking/opencode-plugin 0.1.6 → 0.2.1

package/INSTALL-ZH.md

@@ -2,10 +2,10 @@
 
 这个插件新增了一个面向 OpenCode 的统一 OpenViking 插件：
 
-- 外部仓库语义检索
+- 面向 memory、resources 和 code context 的 OpenViking MCP 工具
 - 长期记忆、session 同步、生命周期边界 commit、自动 recall
 
-这是仓库中唯一继续维护的 OpenCode 插件示例。这个插件不再安装 `skills/openviking/SKILL.md`，也不要求 agent 使用 `ov` 命令。原 skill 风格的能力会通过 OpenCode tools 暴露。
+这是仓库中唯一继续维护的 OpenCode 插件示例。这个插件不再安装 `skills/openviking/SKILL.md`，也不要求 agent 使用 `ov` 命令。模型工具由 Claude Code 和 Codex 记忆插件同款的 stdio MCP proxy 提供。
 
 ## 前置条件
 
@@ -13,7 +13,7 @@
 
 - OpenCode
 - OpenViking HTTP Server
-- Node.js / npm，用于安装插件依赖
+- Node.js 18+
 - 如果服务端启用了认证，需要可用的 OpenViking API Key
 
 建议先启动 OpenViking：
@@ -53,8 +53,7 @@ mkdir -p ~/.config/opencode/plugins/openviking
 cp examples/opencode-plugin/wrappers/openviking.js ~/.config/opencode/plugins/openviking.js
 cp examples/opencode-plugin/index.mjs examples/opencode-plugin/package.json ~/.config/opencode/plugins/openviking/
 cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/
-cd ~/.config/opencode/plugins/openviking
-npm install
+cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/
 ```
 
 安装后结构应类似：
@@ -66,7 +65,7 @@ npm install
     ├── index.mjs
     ├── package.json
     ├── lib/
-    └── node_modules/
+    └── servers/
 ```
 
 顶层 `openviking.js` 只负责把 OpenCode 能发现的一级 `.js` 入口转发到插件目录：
@@ -92,22 +91,22 @@ export { OpenVikingPlugin, default } from "./openviking/index.mjs"
 
 ```json
 {
-  "endpoint": "http://localhost:1933",
-  "apiKey": "",
-  "account": "",
-  "user": "",
-  "peerId": "",
   "enabled": true,
   "timeoutMs": 30000,
   "repoContext": { "enabled": true, "cacheTtlMs": 60000 },
   "autoRecall": {
     "enabled": true,
     "limit": 6,
-    "scoreThreshold": 0.15,
+    "scoreThreshold": 0.35,
     "maxContentChars": 500,
     "preferAbstract": true,
-    "tokenBudget": 2000
-  }
+    "tokenBudget": 2000,
+    "minQueryLength": 3
+  },
+  "commitTokenThreshold": 20000,
+  "commitKeepRecentCount": 10,
+  "profileTokenBudget": 10000,
+  "resumeContextBudget": 32000
 }
 ```
 
@@ -117,7 +116,7 @@ export { OpenVikingPlugin, default } from "./openviking/index.mjs"
 export OPENVIKING_API_KEY="your-api-key-here"
 ```
 
-`apiKey` 会作为 `X-API-Key` 发送。`account` 和 `user` 是 trusted mode
+API key 会从环境变量或 `~/.openviking/ovcli.conf` 读取，并由 hooks 和 MCP proxy 作为 `Authorization: Bearer ...` 发送。`account` 和 `user` 是 trusted mode
 身份头，会作为 `X-OpenViking-Account`、`X-OpenViking-User` 发送；使用
 user/admin API key 的 API_KEY mode 时应留空。
 `peerId` 会作为 `X-OpenViking-Actor-Peer` 用于数据面的 memory/resource 请求；捕获 session message 时仍写入 body `peer_id`。需要 peer 维度路由时请显式配置。
@@ -132,13 +131,13 @@ user/admin API key 的 API_KEY mode 时应留空。
 
 修改插件或 OpenViking 配置后，需要重启 OpenCode。
 
-进入新的 OpenCode session 后，可以让 agent 浏览 OpenViking memory，或搜索一个已索引的资源。插件应暴露这些 tools：
+进入新的 OpenCode session 后，可以让 agent 浏览 OpenViking memory，或搜索一个已索引的资源。插件应暴露 OpenViking MCP server，OpenCode 中的工具名会带 `openviking_` 前缀：
 
-- `memsearch`、`memread`、`membrowse`
-- `memgrep`、`memglob`
-- `memadd`、`memwrite`、`memremove`、`memqueue`
-- `memcommit`
-- `codesearch`、`codeoutline`、`codeexpand`
+- `openviking_recall`、`openviking_search`、`openviking_find`
+- `openviking_read`、`openviking_list`、`openviking_grep`、`openviking_glob`
+- `openviking_remember`、`openviking_add_resource`、`openviking_forget`、`openviking_health`
+- `openviking_list_watches`、`openviking_cancel_watch`
+- `openviking_code_search`、`openviking_code_outline`、`openviking_code_expand`
 
 如果行为异常，先查看运行时文件：
 
@@ -153,35 +152,37 @@ tail -n 100 ~/.config/opencode/openviking/openviking-memory.log
 curl http://localhost:1933/health
 ```
 
-## 可用工具
+## 可用 MCP 工具
 
-插件会通过 OpenCode `tool` hook 暴露这些工具：
+插件会通过 OpenCode config 注册 OpenViking stdio MCP proxy。服务端实际返回的 `tools/list` 是最终工具清单；当前 OpenViking server 暴露：
 
-- `memsearch`：语义检索 memories/resources/skills
-- `memread`：读取具体 `viking://` URI
-- `membrowse`：浏览 OpenViking 文件系统
-- `memcommit`：提交当前 session 并触发记忆提取
-- `memgrep`：精确文本或模式搜索，替代原 `ov grep`
-- `memglob`：文件 glob 枚举，替代原 `ov glob`
-- `memadd`：添加远端 URL 或本地文件资源，替代常见 `ov add-resource` 场景
-- `memwrite`：通过 `/api/v1/content/write` 直接写入 `viking://` 文本文件
-- `memremove`：删除资源，替代 `ov rm`
-- `memqueue`：查看处理队列，替代 `ov observer queue`
+- `openviking_recall`：面向当前任务的平衡召回
+- `openviking_search`：跨 memories/resources/skills 的深度语义检索
+- `openviking_find`：快速语义检索
+- `openviking_remember`：存储重要事实或决策，供记忆提取
+- `openviking_read`：读取一个或多个 `viking://` 文件
+- `openviking_list`：列出 `viking://` 目录
+- `openviking_grep`：精确文本或正则搜索
+- `openviking_glob`：glob 文件匹配
+- `openviking_add_resource`：添加 URL、本地文件、sitemap 或 feed
+- `openviking_forget`：在用户明确确认后删除 `viking://` URI
+- `openviking_list_watches` / `openviking_cancel_watch`：查看或取消资源 watch
+- `openviking_code_search`、`openviking_code_outline`、`openviking_code_expand`：查看已索引代码符号
+- `openviking_health`：检查 OpenViking server 健康状态
 
 使用建议：
 
-- 概念性问题用 `memsearch`
-- 精确符号、函数名、类名、报错字符串用 `memgrep`
-- 枚举文件用 `memglob`
-- 读取内容用 `memread`
-- 探索目录结构用 `membrowse`
-- 持久化笔记或小型文本更新用 `memwrite`；默认是 `create`，避免误覆盖
-- 删除前必须先获得用户明确确认，再调用 `memremove` 且传入 `confirm: true`
-- 如果 agent 误用 OpenCode 本地 `read`、`glob`、`grep` 工具访问 `viking://` URI，插件会阻止这次本地文件系统调用，并提示改用 `memread`、`membrowse` 或 `memsearch`。
+- 概念性问题用 `openviking_search`
+- 精确符号、函数名、类名、报错字符串用 `openviking_grep`
+- 枚举文件用 `openviking_glob`
+- 读取内容用 `openviking_read`
+- 探索目录结构用 `openviking_list`
+- 删除前必须先获得用户明确确认，再调用 `openviking_forget`
+- 如果 agent 误用 OpenCode 本地 `read`、`glob`、`grep` 工具访问 `viking://` URI，插件会阻止这次本地文件系统调用，并提示改用 MCP 工具。
 
-## `memadd` 本地文件
+## `openviking_add_resource` 本地文件
 
-`memadd` 支持三类输入：
+`openviking_add_resource` 支持三类输入：
 
 - 远端 `http(s)` URL：直接调用 `/api/v1/resources`
 - 本地文件路径：先调用 `/api/v1/resources/temp_upload`，再用返回的 `temp_file_id` 添加资源
@@ -190,9 +191,9 @@ curl http://localhost:1933/health
 相对路径会按 OpenCode 当前项目目录解析。示例：
 
 ```text
-memadd path="https://example.com/spec.md" to="viking://resources/spec"
-memadd path="./docs/notes.md" parent="viking://resources/"
-memadd path="file:///home/alice/project/notes.md" reason="project notes"
+openviking_add_resource(path="https://example.com/spec.md", to="viking://resources/spec")
+openviking_add_resource(path="./docs/notes.md", to="viking://resources/notes.md")
+openviking_add_resource(path="file:///home/alice/project/notes.md", description="project notes")
 ```
 
 当前仍不支持本地目录自动打 zip 上传；传入目录时会返回明确错误。
@@ -208,7 +209,7 @@ memadd path="file:///home/alice/project/notes.md" reason="project notes"
 可能包含：
 
 - `openviking-memory.log`
-- `openviking-session-map.json`
+- `openviking-session-state.json`
 
 可以通过配置里的 `runtime.dataDir` 修改这个目录。
 
@@ -219,7 +220,7 @@ memadd path="file:///home/alice/project/notes.md" reason="project notes"
 | 问题 | 排查方向 |
 |------|----------|
 | 插件没有加载 | package 安装检查 `~/.config/opencode/opencode.json` 是否包含 `@openviking/opencode-plugin`；源码安装检查 `~/.config/opencode/plugins/openviking.js` 是否存在 |
-| Tools 连到了错误的 server | 检查 `~/.config/opencode/openviking-config.json` 里的 `endpoint`，或用 `OPENVIKING_PLUGIN_CONFIG` 指向正确配置文件 |
+| MCP tools 连到了错误的 server | 检查 `~/.openviking/ovcli.conf`，或用 `OPENVIKING_*` 环境变量 / `OPENVIKING_PLUGIN_CONFIG` 指向正确配置 |
 | OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`；trusted-mode 部署还要检查 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` |
 | recall 为空 | 确认 OpenViking 中已有 memories/resources，并且 `autoRecall.enabled` 为 `true` |
-| 本地 `memadd` 失败 | 传入文件路径而不是目录；目前还不支持自动上传本地目录 |
+| 本地 `openviking_add_resource` 失败 | 传入文件路径而不是目录；目前还不支持自动上传本地目录 |

package/INSTALL.md

@@ -2,10 +2,10 @@
 
 This plugin adds one unified OpenViking plugin for OpenCode:
 
-- Semantic retrieval for external repositories
+- OpenViking MCP tools for memory, resources, and code context
 - Long-term memory, session synchronization, lifecycle commit, and automatic recall
 
-This is the only OpenCode plugin example maintained in this repository. It does not install `skills/openviking/SKILL.md`, and it does not require the agent to use the `ov` command. The former skill-style capabilities are exposed as OpenCode tools here.
+This is the only OpenCode plugin example maintained in this repository. It does not install `skills/openviking/SKILL.md`, and it does not require the agent to use the `ov` command. Model tools are provided by the same stdio MCP proxy used by the Claude Code and Codex memory plugins.
 
 ## Prerequisites
 
@@ -13,7 +13,7 @@ Prepare the following first:
 
 - OpenCode
 - OpenViking HTTP Server
-- Node.js / npm, used to install plugin dependencies
+- Node.js 18+
 - A valid OpenViking API key if authentication is enabled on the server
 
 Start OpenViking first:
@@ -53,8 +53,7 @@ mkdir -p ~/.config/opencode/plugins/openviking
 cp examples/opencode-plugin/wrappers/openviking.js ~/.config/opencode/plugins/openviking.js
 cp examples/opencode-plugin/index.mjs examples/opencode-plugin/package.json ~/.config/opencode/plugins/openviking/
 cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/
-cd ~/.config/opencode/plugins/openviking
-npm install
+cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/
 ```
 
 After installation, the layout should look like this:
@@ -66,7 +65,7 @@ After installation, the layout should look like this:
     ├── index.mjs
     ├── package.json
     ├── lib/
-    └── node_modules/
+    └── servers/
 ```
 
 The top-level `openviking.js` forwards the first-level `.js` entry that OpenCode can discover to the actual plugin directory:
@@ -92,22 +91,22 @@ Example configuration:
 
 ```json
 {
-  "endpoint": "http://localhost:1933",
-  "apiKey": "",
-  "account": "",
-  "user": "",
-  "peerId": "",
   "enabled": true,
   "timeoutMs": 30000,
   "repoContext": { "enabled": true, "cacheTtlMs": 60000 },
   "autoRecall": {
     "enabled": true,
     "limit": 6,
-    "scoreThreshold": 0.15,
+    "scoreThreshold": 0.35,
     "maxContentChars": 500,
     "preferAbstract": true,
-    "tokenBudget": 2000
-  }
+    "tokenBudget": 2000,
+    "minQueryLength": 3
+  },
+  "commitTokenThreshold": 20000,
+  "commitKeepRecentCount": 10,
+  "profileTokenBudget": 10000,
+  "resumeContextBudget": 32000
 }
 ```
 
@@ -117,7 +116,7 @@ It is recommended to provide the API key through an environment variable instead
 export OPENVIKING_API_KEY="your-api-key-here"
 ```
 
-`apiKey` is sent as `X-API-Key`. `account` and `user` are trusted-mode identity headers sent as `X-OpenViking-Account` and `X-OpenViking-User`; leave them empty when using API-key mode with user/admin API keys. `peerId` is sent as `X-OpenViking-Actor-Peer` on data-plane memory/resource requests; captured session messages store it as body `peer_id`.
+API keys are resolved from environment variables or `~/.openviking/ovcli.conf` and sent as `Authorization: Bearer ...` by both hooks and the MCP proxy. `account` and `user` are trusted-mode identity headers sent as `X-OpenViking-Account` and `X-OpenViking-User`; leave them empty when using API-key mode with user/admin API keys. `peerId` is sent as `X-OpenViking-Actor-Peer` on data-plane memory/resource requests; captured session messages store it as body `peer_id`.
 
 `OPENVIKING_API_KEY`, `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`, and `OPENVIKING_PEER_ID` take precedence over the corresponding values in `openviking-config.json`.
 
@@ -127,13 +126,13 @@ For advanced setups, use `OPENVIKING_PLUGIN_CONFIG` to point to another configur
 
 Restart OpenCode after changing plugin or OpenViking configuration.
 
-In a new OpenCode session, ask the agent to browse OpenViking memory or search for a known indexed resource. The plugin should expose these tools:
+In a new OpenCode session, ask the agent to browse OpenViking memory or search for a known indexed resource. The plugin should expose the OpenViking MCP server, with tools namespaced by OpenCode as `openviking_*`:
 
-- `memsearch`, `memread`, `membrowse`
-- `memgrep`, `memglob`
-- `memadd`, `memwrite`, `memremove`, `memqueue`
-- `memcommit`
-- `codesearch`, `codeoutline`, `codeexpand`
+- `openviking_recall`, `openviking_search`, `openviking_find`
+- `openviking_read`, `openviking_list`, `openviking_grep`, `openviking_glob`
+- `openviking_remember`, `openviking_add_resource`, `openviking_forget`, `openviking_health`
+- `openviking_list_watches`, `openviking_cancel_watch`
+- `openviking_code_search`, `openviking_code_outline`, `openviking_code_expand`
 
 If anything looks wrong, check the runtime files:
 
@@ -148,35 +147,37 @@ For a local server, also confirm OpenViking is reachable:
 curl http://localhost:1933/health
 ```
 
-## Available Tools
+## Available MCP Tools
 
-The plugin exposes the following tools through the OpenCode `tool` hook:
+The plugin registers OpenViking's stdio MCP proxy through OpenCode config. The server's real `tools/list` response is the source of truth; current OpenViking servers expose:
 
-- `memsearch`: semantic retrieval across memories, resources, and skills
-- `memread`: read a specific `viking://` URI
-- `membrowse`: browse the OpenViking filesystem
-- `memcommit`: commit the current session and trigger memory extraction
-- `memgrep`: exact text or pattern search, replacing the former `ov grep` use case
-- `memglob`: file glob enumeration, replacing the former `ov glob` use case
-- `memadd`: add a remote URL or local file resource, replacing common `ov add-resource` scenarios
-- `memwrite`: write text to a `viking://` file through `/api/v1/content/write`
-- `memremove`: remove resources, replacing `ov rm`
-- `memqueue`: inspect the processing queue, replacing `ov observer queue`
+- `openviking_recall`: balanced current-task recall.
+- `openviking_search`: deep semantic retrieval across memories, resources, and skills.
+- `openviking_find`: fast semantic retrieval.
+- `openviking_remember`: store important facts or decisions for memory extraction.
+- `openviking_read`: read one or more `viking://` files.
+- `openviking_list`: list a `viking://` directory.
+- `openviking_grep`: exact text or regex search.
+- `openviking_glob`: glob file matching.
+- `openviking_add_resource`: add a URL, local file, sitemap, or feed.
+- `openviking_forget`: delete a `viking://` URI after explicit user confirmation.
+- `openviking_list_watches` / `openviking_cancel_watch`: inspect or cancel resource watches.
+- `openviking_code_search`, `openviking_code_outline`, `openviking_code_expand`: inspect indexed code symbols.
+- `openviking_health`: check OpenViking server health.
 
 Usage guidance:
 
-- Use `memsearch` for conceptual questions.
-- Use `memgrep` for exact symbols, function names, class names, or error strings.
-- Use `memglob` to enumerate files.
-- Use `memread` to read content.
-- Use `membrowse` to explore directory structure.
-- Use `memwrite` for durable notes or small direct text updates; default mode is `create`.
-- Before deleting anything, obtain explicit user confirmation first; then call `memremove` with `confirm: true`.
-- If an agent tries to use OpenCode's local `read`, `glob`, or `grep` tools on a `viking://` URI, the plugin blocks that call and points it to `memread`, `membrowse`, or `memsearch`.
+- Use `openviking_search` for conceptual questions.
+- Use `openviking_grep` for exact symbols, function names, class names, or error strings.
+- Use `openviking_glob` to enumerate files.
+- Use `openviking_read` to read content.
+- Use `openviking_list` to explore directory structure.
+- Before deleting anything, obtain explicit user confirmation first; then call `openviking_forget`.
+- If an agent tries to use OpenCode's local `read`, `glob`, or `grep` tools on a `viking://` URI, the plugin blocks that call and points it to the MCP tools.
 
-## Local Files with `memadd`
+## Local Files with `openviking_add_resource`
 
-`memadd` supports three input types:
+`openviking_add_resource` supports three input types:
 
 - Remote `http(s)` URL: directly calls `/api/v1/resources`
 - Local file path: first calls `/api/v1/resources/temp_upload`, then adds the resource using the returned `temp_file_id`
@@ -185,9 +186,9 @@ Usage guidance:
 Relative paths are resolved against the current OpenCode project directory. Examples:
 
 ```text
-memadd path="https://example.com/spec.md" to="viking://resources/spec"
-memadd path="./docs/notes.md" parent="viking://resources/"
-memadd path="file:///home/alice/project/notes.md" reason="project notes"
+openviking_add_resource(path="https://example.com/spec.md", to="viking://resources/spec")
+openviking_add_resource(path="./docs/notes.md", to="viking://resources/notes.md")
+openviking_add_resource(path="file:///home/alice/project/notes.md", description="project notes")
 ```
 
 Automatic zip upload for local directories is not supported yet. Passing a directory will return a clear error.
@@ -203,7 +204,7 @@ By default, the plugin writes runtime files to:
 Possible files include:
 
 - `openviking-memory.log`
-- `openviking-session-map.json`
+- `openviking-session-state.json`
 
 You can change this directory with `runtime.dataDir` in the configuration.
 
@@ -214,7 +215,7 @@ These are local runtime files and should not be committed to the repository.
 | Issue | What to check |
 |-------|---------------|
 | Plugin does not load | For package installs, confirm `~/.config/opencode/opencode.json` contains `@openviking/opencode-plugin`; for source installs, confirm `~/.config/opencode/plugins/openviking.js` exists |
-| Tools call the wrong server | Check `endpoint` in `~/.config/opencode/openviking-config.json`, or set `OPENVIKING_PLUGIN_CONFIG` to the intended config path |
+| MCP tools call the wrong server | Check `~/.openviking/ovcli.conf`, or set `OPENVIKING_*` env vars / `OPENVIKING_PLUGIN_CONFIG` to the intended config path |
 | 401 / 403 from OpenViking | Verify `OPENVIKING_API_KEY`; for trusted-mode deployments, also verify `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` |
 | Recall is empty | Confirm OpenViking has indexed memories/resources and `autoRecall.enabled` is `true` |
-| Local `memadd` fails | Pass a file path, not a directory; local directories are not uploaded automatically yet |
+| Local `openviking_add_resource` fails | Pass a file path, not a directory; local directories are not uploaded automatically yet |