refactor(plugin):Merge OpenCode plugins

examples/opencode-plugin/INSTALL-ZH.md

@@ -0,0 +1,186 @@
+# 安装 OpenViking OpenCode 统一插件
+
+这个插件新增了一个面向 OpenCode 的统一 OpenViking 插件：
+
+- 外部仓库语义检索
+- 长期记忆、session 同步、生命周期边界 commit、自动 recall
+
+旧示例目前仍然保留，后续会下线。这个插件不再安装 `skills/openviking/SKILL.md`，也不要求 agent 使用 `ov` 命令。原 skill 中的能力会通过 OpenCode tools 暴露。
+
+## 前置条件
+
+需要先准备：
+
+- OpenCode
+- OpenViking HTTP Server
+- Node.js / npm，用于安装插件依赖
+- 如果服务端启用了认证，需要可用的 OpenViking API Key
+
+建议先启动 OpenViking：
+
+```bash
+openviking-server --config ~/.openviking/ov.conf
+```
+
+检查服务：
+
+```bash
+curl http://localhost:1933/health
+```
+
+## 安装方式一：发布包安装
+
+普通用户推荐通过 OpenCode 的 package plugin 机制启用：
+
+```json
+{
+  "plugin": ["openviking-opencode-plugin"]
+}
+```
+
+如果发布前包名有调整，请使用最终发布包名。
+
+## 安装方式二：源码安装
+
+用于开发调试或 PR 测试。OpenCode 推荐插件目录：
+
+```bash
+~/.config/opencode/plugins
+```
+
+在仓库根目录执行：
+
+```bash
+mkdir -p ~/.config/opencode/plugins/openviking
+cp examples/opencode-plugin/wrappers/openviking.mjs ~/.config/opencode/plugins/openviking.mjs
+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
+```
+
+安装后结构应类似：
+
+```text
+~/.config/opencode/plugins/
+├── openviking.mjs
+└── openviking/
+    ├── index.mjs
+    ├── package.json
+    ├── lib/
+    └── node_modules/
+```
+
+顶层 `openviking.mjs` 只负责把 OpenCode 能发现的一级 `.mjs` 入口转发到插件目录：
+
+```js
+export { OpenVikingPlugin, default } from "./openviking/index.mjs"
+```
+
+这个 wrapper 只用于上面这种源码安装目录结构。npm 包安装会通过 `package.json` 直接加载 `index.mjs`。
+
+如果你使用 npm 包方式安装，也可以将 `examples/opencode-plugin` 作为一个普通 OpenCode 插件包使用。
+
+## 配置
+
+创建用户级配置文件：
+
+```bash
+~/.config/opencode/openviking-config.json
+```
+
+示例配置：
+
+```json
+{
+  "endpoint": "http://localhost:1933",
+  "apiKey": "",
+  "account": "",
+  "user": "",
+  "agentId": "",
+  "enabled": true,
+  "timeoutMs": 30000,
+  "repoContext": { "enabled": true, "cacheTtlMs": 60000 },
+  "autoRecall": {
+    "enabled": true,
+    "limit": 6,
+    "scoreThreshold": 0.15,
+    "maxContentChars": 500,
+    "preferAbstract": true,
+    "tokenBudget": 2000
+  }
+}
+```
+
+推荐通过环境变量提供 API Key，而不是写入配置文件：
+
+```bash
+export OPENVIKING_API_KEY="your-api-key-here"
+```
+
+`apiKey` 会作为 `X-API-Key` 发送。`account`、`user`、`agentId` 会分别作为
+`X-OpenViking-Account`、`X-OpenViking-User`、`X-OpenViking-Agent` 发送。
+如果 OpenViking 服务启用了多租户认证，租户级 API 通常必须配置 `account` 和 `user`。
+
+`OPENVIKING_API_KEY`、`OPENVIKING_ACCOUNT`、`OPENVIKING_USER`、`OPENVIKING_AGENT_ID`
+优先级高于 `openviking-config.json` 里的同名配置。
+
+高级场景可以用 `OPENVIKING_PLUGIN_CONFIG` 指向其他配置文件路径。
+
+## 可用工具
+
+插件会通过 OpenCode `tool` hook 暴露这些工具：
+
+- `memsearch`：语义检索 memories/resources/skills
+- `memread`：读取具体 `viking://` URI
+- `membrowse`：浏览 OpenViking 文件系统
+- `memcommit`：提交当前 session 并触发记忆提取
+- `memgrep`：精确文本或模式搜索，替代原 `ov grep`
+- `memglob`：文件 glob 枚举，替代原 `ov glob`
+- `memadd`：添加远端 URL 或本地文件资源，替代常见 `ov add-resource` 场景
+- `memremove`：删除资源，替代 `ov rm`
+- `memqueue`：查看处理队列，替代 `ov observer queue`
+
+使用建议：
+
+- 概念性问题用 `memsearch`
+- 精确符号、函数名、类名、报错字符串用 `memgrep`
+- 枚举文件用 `memglob`
+- 读取内容用 `memread`
+- 探索目录结构用 `membrowse`
+- 删除前必须先获得用户明确确认，再调用 `memremove` 且传入 `confirm: true`
+
+## `memadd` 本地文件
+
+`memadd` 支持三类输入：
+
+- 远端 `http(s)` URL：直接调用 `/api/v1/resources`
+- 本地文件路径：先调用 `/api/v1/resources/temp_upload`，再用返回的 `temp_file_id` 添加资源
+- `file://` URL：按本地文件处理
+
+相对路径会按 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"
+```
+
+当前仍不支持本地目录自动打 zip 上传；传入目录时会返回明确错误。
+
+## 运行时文件
+
+插件默认会把运行时文件写入：
+
+```bash
+~/.config/opencode/openviking/
+```
+
+可能包含：
+
+- `openviking-memory.log`
+- `openviking-session-map.json`
+
+可以通过配置里的 `runtime.dataDir` 修改这个目录。
+
+这些是本地运行时文件，不建议提交到版本库。

examples/opencode-plugin/INSTALL.md

@@ -0,0 +1,183 @@
+# Install the Unified OpenViking OpenCode Plugin
+
+This plugin adds one unified OpenViking plugin for OpenCode:
+
+- Semantic retrieval for external repositories
+- Long-term memory, session synchronization, lifecycle commit, and automatic recall
+
+The older split examples remain available for now and will be deprecated in a future update. This plugin does not install `skills/openviking/SKILL.md`, and it does not require the agent to use the `ov` command. The capabilities from the former skill are exposed as OpenCode tools here.
+
+## Prerequisites
+
+Prepare the following first:
+
+- OpenCode
+- OpenViking HTTP Server
+- Node.js / npm, used to install plugin dependencies
+- A valid OpenViking API key if authentication is enabled on the server
+
+Start OpenViking first:
+
+```bash
+openviking-server --config ~/.openviking/ov.conf
+```
+
+Check the service:
+
+```bash
+curl http://localhost:1933/health
+```
+
+## Installation Method 1: Published Package
+
+Normal users are recommended to enable it through OpenCode's package plugin mechanism:
+
+```json
+{
+  "plugin": ["openviking-opencode-plugin"]
+}
+```
+
+Use the final published package name if it changes before release.
+
+## Installation Method 2: Source Install
+
+Use this method for development, debugging, or PR testing. OpenCode's recommended plugin directory is:
+
+```bash
+~/.config/opencode/plugins
+```
+
+Run the following commands from the repository root:
+
+```bash
+mkdir -p ~/.config/opencode/plugins/openviking
+cp examples/opencode-plugin/wrappers/openviking.mjs ~/.config/opencode/plugins/openviking.mjs
+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
+```
+
+After installation, the layout should look like this:
+
+```text
+~/.config/opencode/plugins/
+├── openviking.mjs
+└── openviking/
+    ├── index.mjs
+    ├── package.json
+    ├── lib/
+    └── node_modules/
+```
+
+The top-level `openviking.mjs` forwards the first-level `.mjs` entry that OpenCode can discover to the actual plugin directory:
+
+```js
+export { OpenVikingPlugin, default } from "./openviking/index.mjs"
+```
+
+This wrapper is only for source installs with the directory layout shown above. npm package installs load `index.mjs` directly through `package.json`.
+
+If you install through an npm package, you can also use `examples/opencode-plugin` as a normal OpenCode plugin package.
+
+## Configuration
+
+Create the user-level configuration file:
+
+```bash
+~/.config/opencode/openviking-config.json
+```
+
+Example configuration:
+
+```json
+{
+  "endpoint": "http://localhost:1933",
+  "apiKey": "",
+  "account": "",
+  "user": "",
+  "agentId": "",
+  "enabled": true,
+  "timeoutMs": 30000,
+  "repoContext": { "enabled": true, "cacheTtlMs": 60000 },
+  "autoRecall": {
+    "enabled": true,
+    "limit": 6,
+    "scoreThreshold": 0.15,
+    "maxContentChars": 500,
+    "preferAbstract": true,
+    "tokenBudget": 2000
+  }
+}
+```
+
+It is recommended to provide the API key through an environment variable instead of writing it into the configuration file:
+
+```bash
+export OPENVIKING_API_KEY="your-api-key-here"
+```
+
+`apiKey` is sent as `X-API-Key`. `account`, `user`, and `agentId` are sent as `X-OpenViking-Account`, `X-OpenViking-User`, and `X-OpenViking-Agent`, respectively. If multi-tenant authentication is enabled on the OpenViking server, tenant-scoped APIs usually require `account` and `user` to be configured.
+
+`OPENVIKING_API_KEY`, `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`, and `OPENVIKING_AGENT_ID` take precedence over the corresponding values in `openviking-config.json`.
+
+For advanced setups, use `OPENVIKING_PLUGIN_CONFIG` to point to another configuration file path.
+
+## Available Tools
+
+The plugin exposes the following tools through the OpenCode `tool` hook:
+
+- `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
+- `memremove`: remove resources, replacing `ov rm`
+- `memqueue`: inspect the processing queue, replacing `ov observer queue`
+
+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.
+- Before deleting anything, obtain explicit user confirmation first; then call `memremove` with `confirm: true`.
+
+## Local Files with `memadd`
+
+`memadd` 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`
+- `file://` URL: handled as a local file
+
+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"
+```
+
+Automatic zip upload for local directories is not supported yet. Passing a directory will return a clear error.
+
+## Runtime Files
+
+By default, the plugin writes runtime files to:
+
+```bash
+~/.config/opencode/openviking/
+```
+
+Possible files include:
+
+- `openviking-memory.log`
+- `openviking-session-map.json`
+
+You can change this directory with `runtime.dataDir` in the configuration.
+
+These are local runtime files and should not be committed to the repository.