volcengine · ZaynJarvis · Jun 24, 2026
diff --git a/docs/en/agent-integrations/08-community-plugins.md b/docs/en/agent-integrations/08-community-plugins.md
@@ -62,7 +62,7 @@ For development, debugging, or PR testing, install the plugin from this reposito
 git clone https://github.com/volcengine/OpenViking.git
 cd OpenViking
 mkdir -p ~/.config/opencode/plugins/openviking
-cp examples/opencode-plugin/wrappers/openviking.mjs ~/.config/opencode/plugins/openviking.mjs
+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
@@ -73,15 +73,16 @@ This source install creates the layout OpenCode can discover:
 
 ```text
 ~/.config/opencode/plugins/
-├── openviking.mjs
+├── openviking.js
 └── openviking/
     ├── index.mjs
     ├── package.json
     ├── lib/
     └── node_modules/
 ```
 
-The top-level `openviking.mjs` is only a wrapper that forwards OpenCode's first-level plugin entry to the installed package directory.
+The top-level `openviking.js` is only a wrapper that forwards OpenCode's first-level plugin entry to the installed package directory.
+Use the `.js` wrapper for source installs; OpenCode's local plugin scanner discovers JavaScript/TypeScript plugin files.
 
 ### Configure
 
@@ -139,7 +140,7 @@ Ask OpenCode to search or browse OpenViking memory, or request a manual session
 
 | Issue | What to check |
 |-------|---------------|
-| Plugin does not load | Confirm `~/.config/opencode/opencode.json` references `openviking-opencode-plugin`, or that `~/.config/opencode/plugins/openviking.mjs` exists for source installs |
+| Plugin does not load | Confirm `~/.config/opencode/opencode.json` references `openviking-opencode-plugin`, or that `~/.config/opencode/plugins/openviking.js` exists for source installs |
 | Tools call the wrong server | Check `endpoint` in `~/.config/opencode/openviking-config.json`, or set `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 the OpenViking server has indexed memories/resources and that `autoRecall.enabled` is `true` |

diff --git a/docs/images/agents/en/opencode.md b/docs/images/agents/en/opencode.md
@@ -38,7 +38,7 @@ For development, debugging, or PR testing, copy the plugin from the OpenViking r
 git clone https://github.com/volcengine/OpenViking.git
 cd OpenViking
 mkdir -p ~/.config/opencode/plugins/openviking
-cp examples/opencode-plugin/wrappers/openviking.mjs ~/.config/opencode/plugins/openviking.mjs
+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
@@ -49,7 +49,7 @@ The source install creates:
 
 ```text
 ~/.config/opencode/plugins/
-├── openviking.mjs
+├── openviking.js
 └── openviking/
     ├── index.mjs
     ├── package.json
@@ -108,7 +108,7 @@ Ask OpenCode to browse OpenViking or commit the current session. Check runtime l
 
 | Symptom | Fix |
 |---------|-----|
-| Plugin is not loaded | Check `~/.config/opencode/opencode.json` for package installs, or `~/.config/opencode/plugins/openviking.mjs` for source installs |
+| Plugin is not loaded | Check `~/.config/opencode/opencode.json` for package installs, or `~/.config/opencode/plugins/openviking.js` for source installs |
 | Tools call the wrong server | Check `endpoint`, or set `OPENVIKING_PLUGIN_CONFIG` to the intended config path |
 | 401 / 403 from OpenViking | Verify `OPENVIKING_API_KEY`; trusted-mode deployments also need `OPENVIKING_ACCOUNT` and `OPENVIKING_USER` |
 | Recall is empty | Confirm OpenViking has memories/resources and `autoRecall.enabled` is `true` |

diff --git a/docs/images/agents/zh/opencode.md b/docs/images/agents/zh/opencode.md
@@ -39,7 +39,7 @@ curl http://localhost:1933/health
 git clone https://github.com/volcengine/OpenViking.git
 cd OpenViking
 mkdir -p ~/.config/opencode/plugins/openviking
-cp examples/opencode-plugin/wrappers/openviking.mjs ~/.config/opencode/plugins/openviking.mjs
+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
@@ -50,7 +50,7 @@ npm install
 
 ```text
 ~/.config/opencode/plugins/
-├── openviking.mjs
+├── openviking.js
 └── openviking/
     ├── index.mjs
     ├── package.json
@@ -109,7 +109,7 @@ export OPENVIKING_PEER_ID="opencode"  # 可选，peer 维度记忆路由需要
 
 | 现象 | 修复 |
 |------|------|
-| 插件没有加载 | package 安装检查 `~/.config/opencode/opencode.json`；源码安装检查 `~/.config/opencode/plugins/openviking.mjs` |
+| 插件没有加载 | package 安装检查 `~/.config/opencode/opencode.json`；源码安装检查 `~/.config/opencode/plugins/openviking.js` |
 | Tools 连到了错误的 server | 检查 `endpoint`，或用 `OPENVIKING_PLUGIN_CONFIG` 指向正确配置文件 |
 | OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`；trusted-mode 部署还需要 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` |
 | recall 为空 | 确认 OpenViking 中已有 memories/resources，并且 `autoRecall.enabled` 为 `true` |

diff --git a/docs/zh/agent-integrations/08-community-plugins.md b/docs/zh/agent-integrations/08-community-plugins.md
@@ -62,7 +62,7 @@ curl http://localhost:1933/health
 git clone https://github.com/volcengine/OpenViking.git
 cd OpenViking
 mkdir -p ~/.config/opencode/plugins/openviking
-cp examples/opencode-plugin/wrappers/openviking.mjs ~/.config/opencode/plugins/openviking.mjs
+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
@@ -73,15 +73,16 @@ npm install
 
 ```text
 ~/.config/opencode/plugins/
-├── openviking.mjs
+├── openviking.js
 └── openviking/
     ├── index.mjs
     ├── package.json
     ├── lib/
     └── node_modules/
 ```
 
-顶层 `openviking.mjs` 只是一个 wrapper，用来把 OpenCode 可发现的一级插件入口转发到实际安装目录。
+顶层 `openviking.js` 只是一个 wrapper，用来把 OpenCode 可发现的一级插件入口转发到实际安装目录。
+源码安装请使用 `.js` wrapper；OpenCode 的本地插件扫描器会发现 JavaScript/TypeScript 插件文件。
 
 ### 配置
 
@@ -139,7 +140,7 @@ export OPENVIKING_PEER_ID="opencode"  # 可选，peer 维度记忆路由需要
 
 | 问题 | 排查方向 |
 |------|----------|
-| 插件没有加载 | 确认 `~/.config/opencode/opencode.json` 引用了 `openviking-opencode-plugin`；源码安装时确认 `~/.config/opencode/plugins/openviking.mjs` 存在 |
+| 插件没有加载 | 确认 `~/.config/opencode/opencode.json` 引用了 `openviking-opencode-plugin`；源码安装时确认 `~/.config/opencode/plugins/openviking.js` 存在 |
 | Tools 连到了错误的 server | 检查 `~/.config/opencode/openviking-config.json` 里的 `endpoint`，或用 `OPENVIKING_PLUGIN_CONFIG` 指向正确配置文件 |
 | OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`；trusted-mode 部署还要检查 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` |
 | recall 为空 | 确认 OpenViking server 中已有 memories/resources，并且 `autoRecall.enabled` 为 `true` |

diff --git a/examples/opencode-plugin/INSTALL-ZH.md b/examples/opencode-plugin/INSTALL-ZH.md
@@ -50,7 +50,7 @@ curl http://localhost:1933/health
 
 ```bash
 mkdir -p ~/.config/opencode/plugins/openviking
-cp examples/opencode-plugin/wrappers/openviking.mjs ~/.config/opencode/plugins/openviking.mjs
+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
@@ -61,21 +61,22 @@ npm install
 
 ```text
 ~/.config/opencode/plugins/
-├── openviking.mjs
+├── openviking.js
 └── openviking/
     ├── index.mjs
     ├── package.json
     ├── lib/
     └── node_modules/
 ```
 
-顶层 `openviking.mjs` 只负责把 OpenCode 能发现的一级 `.mjs` 入口转发到插件目录：
+顶层 `openviking.js` 只负责把 OpenCode 能发现的一级 `.js` 入口转发到插件目录：
 
 ```js
 export { OpenVikingPlugin, default } from "./openviking/index.mjs"
 ```
 
 这个 wrapper 只用于上面这种源码安装目录结构。npm 包安装会通过 `package.json` 直接加载 `index.mjs`。
+源码安装请使用 `.js` wrapper；OpenCode 的本地插件扫描器会发现 JavaScript/TypeScript 插件文件。
 
 如果你使用 npm 包方式安装，也可以将 `examples/opencode-plugin` 作为一个普通 OpenCode 插件包使用。
 
@@ -216,7 +217,7 @@ memadd path="file:///home/alice/project/notes.md" reason="project notes"
 
 | 问题 | 排查方向 |
 |------|----------|
-| 插件没有加载 | package 安装检查 `~/.config/opencode/opencode.json` 是否包含 `openviking-opencode-plugin`；源码安装检查 `~/.config/opencode/plugins/openviking.mjs` 是否存在 |
+| 插件没有加载 | package 安装检查 `~/.config/opencode/opencode.json` 是否包含 `openviking-opencode-plugin`；源码安装检查 `~/.config/opencode/plugins/openviking.js` 是否存在 |
 | Tools 连到了错误的 server | 检查 `~/.config/opencode/openviking-config.json` 里的 `endpoint`，或用 `OPENVIKING_PLUGIN_CONFIG` 指向正确配置文件 |
 | OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`；trusted-mode 部署还要检查 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` |
 | recall 为空 | 确认 OpenViking 中已有 memories/resources，并且 `autoRecall.enabled` 为 `true` |

diff --git a/examples/opencode-plugin/INSTALL.md b/examples/opencode-plugin/INSTALL.md
@@ -50,7 +50,7 @@ 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/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
@@ -61,21 +61,22 @@ After installation, the layout should look like this:
 
 ```text
 ~/.config/opencode/plugins/
-├── openviking.mjs
+├── openviking.js
 └── 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:
+The top-level `openviking.js` forwards the first-level `.js` 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`.
+Use the `.js` wrapper for source installs; OpenCode's local plugin scanner discovers JavaScript/TypeScript plugin files.
 
 If you install through an npm package, you can also use `examples/opencode-plugin` as a normal OpenCode plugin package.
 
@@ -211,7 +212,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.mjs` exists |
+| 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 |
 | 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` |

diff --git a/examples/opencode-plugin/README.md b/examples/opencode-plugin/README.md
@@ -35,7 +35,7 @@ examples/opencode-plugin/
 │   └── utils.mjs
 ├── tests/
 └── wrappers/
-    └── openviking.mjs
+    └── openviking.js
 ```
 
 There is intentionally no `skills/openviking/SKILL.md`. The former skill behavior is implemented as tools.
@@ -71,7 +71,7 @@ For development or PR testing, copy the package into OpenCode's plugin directory
 
 ```bash
 mkdir -p ~/.config/opencode/plugins/openviking
-cp examples/opencode-plugin/wrappers/openviking.mjs ~/.config/opencode/plugins/openviking.mjs
+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
@@ -82,21 +82,22 @@ This creates a stable OpenCode plugin layout:
 
 ```text
 ~/.config/opencode/plugins/
-├── openviking.mjs
+├── openviking.js
 └── openviking/
     ├── index.mjs
     ├── package.json
     ├── lib/
     └── node_modules/
 ```
 
-The top-level `openviking.mjs` is only a wrapper:
+The top-level `openviking.js` is only a wrapper:
 
 ```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`.
+Use the `.js` wrapper for source installs; OpenCode's local plugin scanner discovers JavaScript/TypeScript plugin files.
 
 ## Configuration
 

diff --git a/...s/opencode-plugin/wrappers/openviking.mjs → ...es/opencode-plugin/wrappers/openviking.js b/...s/opencode-plugin/wrappers/openviking.mjs → ...es/opencode-plugin/wrappers/openviking.js
diff --git a/tests/oc2ov_test/README.md b/tests/oc2ov_test/README.md
@@ -153,6 +153,43 @@ TEST_CONFIG = {
 
 ## 🧪 运行测试
 
+### 插件契约测试
+
+`tests/plugins/` 是快速、低成本的 Agent 集成契约测试入口，用来在真正跑
+OpenCode、Hermes 或 OpenClaw E2E 前先验证安装文档、插件入口、工具注册和
+Hermes OpenViking preflight 是否仍然完整。
+
+当前覆盖：
+
+- OpenCode source install 使用 `openviking.js` wrapper，避免本地插件扫描器跳过 `.mjs` 文件
+- `opencode-plugin` 暴露核心 memory tools、code tools、`memwrite` 和 `viking://` URI guard
+- OpenCode 文档包含安装、健康检查、工具使用和本地 `read/glob/grep` 防误用说明
+- Hermes 文档明确 OpenViking 是内置 memory provider，无需安装插件
+- Hermes LoCoMo `e2e` benchmark 在正式导入/评测前会用 preflight 验证 Hermes 写入了目标 OpenViking
+
+推荐作为变更插件、agent 集成文档或 benchmark preflight 时的第一道 ovtest：
+
+```bash
+python run_tests.py --type plugins -v
+# 或
+./run.sh --plugins -v
+```
+
+插件相关变更推荐按这个顺序验证：
+
+1. 在 `tests/oc2ov_test` 运行 `python run_tests.py --type plugins -v`，先确认
+   OpenCode / Hermes + OpenViking 的轻量契约没有漂移。
+2. 如果改了 `examples/opencode-plugin` 代码，在 `examples/opencode-plugin` 运行
+   `npm run check && npm test`，验证 package 自身导出、工具定义和 guard 行为。
+3. 如果改了 OpenCode 安装文档或 wrapper，用 source install 方式把
+   `wrappers/openviking.js` 放到 `.opencode/plugins/` 或
+   `~/.config/opencode/plugins/`，给同级 `openviking/` 运行 `npm install`，
+   启动 OpenCode 后检查 `/experimental/tool/ids` 里有 `memwrite`、`memsearch`
+   和 `codeoutline`。
+4. 如果改了 Hermes 集成或 LoCoMo benchmark，带 `HERMES_URL` 和 `OPENVIKING_URL`
+   运行 `--suite e2e`，确认 preflight 能在导入和评测前发现 Hermes 没有写入目标
+   OpenViking 的配置错误。
+
 ### 推荐：使用 CLI 方式（更稳定）
 
 ```bash
@@ -191,6 +228,12 @@ pytest test_pytest.py -v --html=reports/test_report.html --self-contained-html
 # 仅运行复杂场景测试
 ./run.sh -x
 
+# 仅运行插件契约测试（OpenCode / Hermes + OpenViking）
+./run.sh --plugins
+
+# 或使用 unittest runner
+python run_tests.py --type plugins -v
+
 # 详细输出模式
 ./run.sh -v
 

diff --git a/tests/oc2ov_test/run.sh b/tests/oc2ov_test/run.sh
@@ -4,7 +4,7 @@
 set -e
 
 # 检查是否在虚拟环境中
-if [[ "$VIRTUAL_ENV" == "" ]]; then
+if [[ "$VIRTUAL_ENV" == "" && -f venv/bin/activate ]]; then
     echo "激活虚拟环境..."
     source venv/bin/activate
 fi
@@ -24,6 +24,7 @@ if [ "$1" = "--help" ] || [ "$1" = "-h" ]; then
     echo "  -p, --p0            仅运行 P0 级测试"
     echo "  -c, --crud          仅运行 CRUD 操作测试"
     echo "  -x, --complex       仅运行复杂场景测试"
+    echo "  -g, --plugins       仅运行 Agent 插件契约测试"
     echo "  -v, --verbose       详细输出模式"
     echo "  -r, --report        生成 HTML 测试报告"
     echo ""
@@ -34,6 +35,7 @@ fi
 VERBOSE=""
 REPORT=""
 TEST_TYPE=""
+PLUGIN_TEST=""
 
 # 解析参数
 while [[ $# -gt 0 ]]; do
@@ -62,6 +64,10 @@ while [[ $# -gt 0 ]]; do
             TEST_TYPE="tests/complex/"
             shift
             ;;
+        -g|--plugins)
+            PLUGIN_TEST="1"
+            shift
+            ;;
         *)
             echo "未知选项: $1"
             echo "使用 -h 查看帮助"
@@ -74,7 +80,14 @@ done
 mkdir -p reports logs
 
 # 运行测试
-if [ -n "$TEST_TYPE" ]; then
+if [ "$PLUGIN_TEST" = "1" ]; then
+    echo "运行 Agent 插件契约测试..."
+    if [ -n "$REPORT" ]; then
+        echo "插件契约测试使用 unittest runner，不生成 HTML 报告。"
+        REPORT=""
+    fi
+    python run_tests.py --type plugins $VERBOSE
+elif [ -n "$TEST_TYPE" ]; then
     echo "运行 $TEST_TYPE 目录下的测试..."
     pytest $TEST_TYPE $VERBOSE $REPORT
 else