Skip to content

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

docs(plugins): run sync.mjs before copying a plugin out of a checkout (#5063)

t0sakia372c2dcfe7b
diff --git a/docs/en/agent-integrations/10-opencode.md b/docs/en/agent-integrations/10-opencode.md
index a1316e3b6..91aee2d9f 100644
--- a/docs/en/agent-integrations/10-opencode.md
+++ b/docs/en/agent-integrations/10-opencode.md
@@ -67,6 +67,7 @@ If package installation is not available in your environment:
```bash
git clone https://github.com/volcengine/OpenViking.git
cd OpenViking
+node examples/memory-plugin-shared/sync.mjs
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/
@@ -74,6 +75,8 @@ cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/
cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/
```
+`sync.mjs` generates `lib/shared/`, the shared modules the plugin and its MCP proxy import. That directory is not in git, so run it before copying, and again after every `git pull`.
+
This source install creates the layout OpenCode can discover:
```text
@@ -91,9 +94,10 @@ Use the `.js` wrapper for source installs; OpenCode's local plugin scanner disco
## Configure
-Credentials are shared with the Claude Code and Codex memory plugins. Run the setup wizard once, or set `OPENVIKING_*` environment variables:
+Credentials are shared with the Claude Code and Codex memory plugins. Run the setup wizard once from the repository root, or set `OPENVIKING_*` environment variables. The wizard imports `lib/shared/` too, so generate it first:
```bash
+node examples/memory-plugin-shared/sync.mjs
node examples/opencode-plugin/scripts/setup.mjs
```
@@ -155,6 +159,7 @@ Ask OpenCode to search or browse OpenViking memory. Runtime state and errors are
| Issue | What to check |
|-------|---------------|
| Plugin does not load | Confirm `~/.config/opencode/opencode.json` references `@openviking/opencode-plugin`, or that `~/.config/opencode/plugins/openviking.js` exists for source installs |
+| Load fails with a missing `lib/shared/*.mjs` module | The source copy was made without running `sync.mjs` first. Run `node examples/memory-plugin-shared/sync.mjs` from the repository root and copy `lib/` again |
| MCP tools call the wrong server | Check `~/.openviking/ovcli.conf`, or set `OPENVIKING_*` env vars; `OPENVIKING_CLI_CONFIG_FILE` points the plugin at a different ovcli.conf |
| 401 / 403 from OpenViking | Verify `OPENVIKING_API_KEY`; for trusted-mode deployments, also verify `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` |
| Recall is empty | Confirm the OpenViking server has indexed memories/resources and that `autoRecall` is not set to `false` |
diff --git a/docs/en/agent-integrations/11-pi.md b/docs/en/agent-integrations/11-pi.md
index 040897db3..c12f9b458 100644
--- a/docs/en/agent-integrations/11-pi.md
+++ b/docs/en/agent-integrations/11-pi.md
@@ -42,10 +42,13 @@ Manual copy from a repo checkout also works:
```bash
git clone https://github.com/volcengine/OpenViking.git
cd OpenViking
+node examples/memory-plugin-shared/sync.mjs
mkdir -p ~/.pi/agent/extensions
cp -r examples/pi-coding-agent-extension ~/.pi/agent/extensions/openviking
```
+The extension imports its shared modules from a `shared/` directory that is not in git; `sync.mjs` generates it, so run it before copying. After a `git pull`, run `sync.mjs` again before copying the update.
+
## Configure
Credentials resolve from `OPENVIKING_*` environment variables, then `~/.openviking/ovcli.conf`, then `~/.openviking/ov.conf` — shared with the Claude Code, Codex, and OpenCode plugins. Run the wizard once if you have not configured them yet:
@@ -101,6 +104,7 @@ Start `pi`. Once connected, the footer shows an `OV ✓` status segment, and `/v
| `OV ✗` in the footer or "server not reachable" | `curl http://localhost:1933/health`; check the endpoint in `~/.openviking/ovcli.conf` |
| Extension does not load | Confirm `~/.pi/agent/extensions/openviking/index.ts` exists (the directory is auto-discovered); re-run the installer. Do not register it with `pi install` — that loads it twice |
| `/viking` command appears twice (`viking:1` / `viking:2`) | An older installer registered the path with `pi install`, leaving a redundant `packages` entry so it loads once via auto-discovery and once via `packages`; run `pi remove ~/.pi/agent/extensions/openviking` to drop that entry (edits settings only, leaves the files) |
+| Load fails with a missing `shared/*.mjs` module (for example `shared/capture-utils.mjs`) | The copy was made without running `sync.mjs` first. Run `node examples/memory-plugin-shared/sync.mjs` from the repository root and copy again, or re-run the installer |
| Import errors mentioning `@mariozechner/*` | Stale copy from before pi's move to `@earendil-works/*` — re-run the installer |
| 401 / 403 from OpenViking | Verify `OPENVIKING_API_KEY`; for trusted-mode deployments, also verify `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` |
| Recall is empty | Confirm the server has indexed memories and the prompt is longer than `minQueryLength` |
diff --git a/docs/zh/agent-integrations/10-opencode.md b/docs/zh/agent-integrations/10-opencode.md
index 93518bf6a..50684388f 100644
--- a/docs/zh/agent-integrations/10-opencode.md
+++ b/docs/zh/agent-integrations/10-opencode.md
@@ -67,6 +67,7 @@ opencode
```bash
git clone https://github.com/volcengine/OpenViking.git
cd OpenViking
+node examples/memory-plugin-shared/sync.mjs
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/
@@ -74,6 +75,8 @@ cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/
cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/
```
+`sync.mjs` 会生成 `lib/shared/`,插件和 MCP 代理都从这里 import 共享模块。这个目录不在 git 里,所以复制前要先运行;之后每次 `git pull` 也要重新运行再复制。
+
源码安装后,OpenCode 能发现的目录结构应类似:
```text
@@ -91,9 +94,10 @@ cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/
## 配置
-凭据与 Claude Code / Codex 记忆插件共用。可以先运行 setup 向导,或使用 `OPENVIKING_*` 环境变量:
+凭据与 Claude Code / Codex 记忆插件共用。可以在仓库根目录运行一次 setup 向导,或使用 `OPENVIKING_*` 环境变量。向导同样 import `lib/shared/`,所以要先生成:
```bash
+node examples/memory-plugin-shared/sync.mjs
node examples/opencode-plugin/scripts/setup.mjs
```
@@ -155,6 +159,7 @@ API key 会由 hooks 和 MCP proxy 作为 `Authorization: Bearer ...` 发送;`
| 问题 | 排查方向 |
|------|----------|
| 插件没有加载 | 确认 `~/.config/opencode/opencode.json` 引用了 `@openviking/opencode-plugin`;源码安装时确认 `~/.config/opencode/plugins/openviking.js` 存在 |
+| 加载时报找不到 `lib/shared/*.mjs` | 源码复制前没有运行 `sync.mjs`。在仓库根目录运行 `node examples/memory-plugin-shared/sync.mjs` 后重新复制 `lib/` |
| MCP tools 连到了错误的 server | 检查 `~/.openviking/ovcli.conf`,或用 `OPENVIKING_*` 环境变量;`OPENVIKING_CLI_CONFIG_FILE` 可让插件改读另一份 ovcli.conf |
| OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`;trusted-mode 部署还要检查 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` |
| recall 为空 | 确认 OpenViking server 中已有 memories/resources,且 `autoRecall` 没有被设成 `false` |
diff --git a/docs/zh/agent-integrations/11-pi.md b/docs/zh/agent-integrations/11-pi.md
index a2aedb2bd..ac936230b 100644
--- a/docs/zh/agent-integrations/11-pi.md
+++ b/docs/zh/agent-integrations/11-pi.md
@@ -42,10 +42,13 @@ bash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shar
```bash
git clone https://github.com/volcengine/OpenViking.git
cd OpenViking
+node examples/memory-plugin-shared/sync.mjs
mkdir -p ~/.pi/agent/extensions
cp -r examples/pi-coding-agent-extension ~/.pi/agent/extensions/openviking
```
+扩展从 `shared/` 目录 import 共享模块,这个目录不在 git 里,由 `sync.mjs` 生成,所以复制前必须先运行它。之后 `git pull` 更新时,也要先重新运行 `sync.mjs` 再复制。
+
## 配置
凭据解析顺序是 `OPENVIKING_*` 环境变量、`~/.openviking/ovcli.conf`、`~/.openviking/ov.conf`——与 Claude Code、Codex、OpenCode 插件共用。尚未配置时可运行一次向导:
@@ -101,6 +104,7 @@ Takeover 是 fail-open:如果 pending 写入无法 flush、commit 失败、arc
| 状态栏显示 `OV ✗` 或提示 "server not reachable" | `curl http://localhost:1933/health`;检查 `~/.openviking/ovcli.conf` 中的 endpoint |
| 扩展没有加载 | 确认 `~/.pi/agent/extensions/openviking/index.ts` 存在(该目录会被自动发现);重跑安装器即可。不要用 `pi install` 注册它——那样会重复加载 |
| `/viking` 命令出现两次(`viking:1` / `viking:2`) | 老版本安装器用 `pi install` 留下了冗余的 `packages` 条目,导致自动发现和 `packages` 各加载一次;执行 `pi remove ~/.pi/agent/extensions/openviking` 清掉该条目(只改 settings,不删文件) |
+| 加载时报找不到 `shared/*.mjs`(例如 `shared/capture-utils.mjs`) | 手动复制前没有运行 `sync.mjs`。在仓库根目录运行 `node examples/memory-plugin-shared/sync.mjs` 后重新复制,或者重跑安装器 |
| 报错提到 `@mariozechner/*` | pi 迁移到 `@earendil-works/*` 之前的旧副本——重跑安装器 |
| OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`;trusted-mode 部署还要检查 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` |
| recall 为空 | 确认 server 中已有记忆,且 prompt 长度超过 `minQueryLength` |
diff --git a/examples/dsh-memory-plugin/README.md b/examples/dsh-memory-plugin/README.md
index 485e4a0ec..1f4502f7a 100644
--- a/examples/dsh-memory-plugin/README.md
+++ b/examples/dsh-memory-plugin/README.md
@@ -29,6 +29,8 @@ be a real package. Linking a source checkout (`dsh plugin --profile web add
./examples/dsh-memory-plugin`) only works when that checkout has its own
`node_modules`, because Node resolves the bundle's dsh peers from the source
tree's realpath rather than from the profile.
+It also needs `node examples/memory-plugin-shared/sync.mjs` run first: the
+`shared/` modules the bundle imports are generated, not committed.
## Requirements
diff --git a/examples/opencode-plugin/INSTALL-ZH.md b/examples/opencode-plugin/INSTALL-ZH.md
index d02d56b20..b24139820 100644
--- a/examples/opencode-plugin/INSTALL-ZH.md
+++ b/examples/opencode-plugin/INSTALL-ZH.md
@@ -49,6 +49,7 @@ curl http://localhost:1933/health
在仓库根目录执行:
```bash
+node examples/memory-plugin-shared/sync.mjs
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/
@@ -56,6 +57,8 @@ cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/
cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/
```
+`sync.mjs` 会生成 `lib/shared/`,插件和 MCP 代理都从这里 import 共享模块。这个目录不在 git 里,所以复制前要先运行;之后每次 `git pull` 也要重新运行再复制。
+
安装后结构应类似:
```text
@@ -247,6 +250,7 @@ openviking_add_resource(path="file:///home/alice/project/notes.md", description=
| 问题 | 排查方向 |
|------|----------|
| 插件没有加载 | package 安装检查 `~/.config/opencode/opencode.json` 是否包含 `@openviking/opencode-plugin`;源码安装检查 `~/.config/opencode/plugins/openviking.js` 是否存在 |
+| 加载时报找不到 `lib/shared/*.mjs` | 源码复制前没有运行 `sync.mjs`。在仓库根目录运行 `node examples/memory-plugin-shared/sync.mjs` 后重新复制 `lib/` |
| MCP tools 连到了错误的 server | 检查 `~/.openviking/ovcli.conf`,或用 `OPENVIKING_*` 环境变量 / `OPENVIKING_CLI_CONFIG_FILE` 指向正确配置 |
| OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`;trusted-mode 部署还要检查 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` |
| recall 为空 | 确认 OpenViking 中已有 memories/resources,并且 `autoRecall` 为 `true` |
diff --git a/examples/opencode-plugin/INSTALL.md b/examples/opencode-plugin/INSTALL.md
index cc4b24469..844ab2123 100644
--- a/examples/opencode-plugin/INSTALL.md
+++ b/examples/opencode-plugin/INSTALL.md
@@ -49,6 +49,7 @@ Use this method for development, debugging, or PR testing. OpenCode's recommende
Run the following commands from the repository root:
```bash
+node examples/memory-plugin-shared/sync.mjs
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/
@@ -56,6 +57,8 @@ cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/
cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/
```
+`sync.mjs` generates `lib/shared/`, the shared modules the plugin and its MCP proxy import. That directory is not in git, so run it before copying, and again after every `git pull`.
+
After installation, the layout should look like this:
```text
@@ -244,6 +247,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 |
+| Load fails with a missing `lib/shared/*.mjs` module | The source copy was made without running `sync.mjs` first. Run `node examples/memory-plugin-shared/sync.mjs` from the repository root and copy `lib/` again |
| MCP tools call the wrong server | Check `~/.openviking/ovcli.conf`, or set `OPENVIKING_*` env vars / `OPENVIKING_CLI_CONFIG_FILE` 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` is `true` |
diff --git a/examples/opencode-plugin/README.md b/examples/opencode-plugin/README.md
index e9f3662a1..d20c88f14 100644
--- a/examples/opencode-plugin/README.md
+++ b/examples/opencode-plugin/README.md
@@ -83,6 +83,7 @@ npm view @openviking/opencode-plugin version
For development or PR testing, copy the package into OpenCode's plugin directory with a top-level wrapper:
```bash
+node examples/memory-plugin-shared/sync.mjs
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/
@@ -90,6 +91,8 @@ cp -r examples/opencode-plugin/lib ~/.config/opencode/plugins/openviking/
cp -r examples/opencode-plugin/servers ~/.config/opencode/plugins/openviking/
```
+`sync.mjs` generates `lib/shared/`, the shared modules the plugin and its MCP proxy import. That directory is not in git, so run it before copying, and again after every `git pull`.
+
This creates a stable OpenCode plugin layout:
```text