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(plugins): stop the pi installer loading the extension twice (#5059)
t0saki65b009c578b1
diff --git a/docs/en/agent-integrations/11-pi.md b/docs/en/agent-integrations/11-pi.mdindex e1fda917e..040897db3 100644--- a/docs/en/agent-integrations/11-pi.md+++ b/docs/en/agent-integrations/11-pi.md@@ -35,7 +35,7 @@ In regions where GitHub is hard to reach, run the same installer from the Volcenbash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)```-The installer copies the extension into `~/.pi/agent/extensions/openviking`, registers it with `pi install`, and configures `~/.openviking/ovcli.conf`.+The installer copies the extension into `~/.pi/agent/extensions/openviking` and configures `~/.openviking/ovcli.conf`. That directory is one of pi's auto-discovery roots, so pi loads the extension on the next start — no `pi install` needed. (Running `pi install` on the same path would load it twice — once via auto-discovery, once via the `packages` entry — producing a duplicate `/viking` command.)Manual copy from a repo checkout also works:@@ -44,7 +44,6 @@ git clone https://github.com/volcengine/OpenViking.gitcd OpenVikingmkdir -p ~/.pi/agent/extensionscp -r examples/pi-coding-agent-extension ~/.pi/agent/extensions/openviking-pi install ~/.pi/agent/extensions/openviking```## Configure@@ -100,7 +99,8 @@ Start `pi`. Once connected, the footer shows an `OV ✓` status segment, and `/v| Issue | What to check ||-------|---------------|| `OV ✗` in the footer or "server not reachable" | `curl http://localhost:1933/health`; check the endpoint in `~/.openviking/ovcli.conf` |-| Extension does not load | `pi list` should show `extensions/openviking`; re-run the installer or `pi install ~/.pi/agent/extensions/openviking` |+| 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) || 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/en/agent-integrations/16-capability-reference.md b/docs/en/agent-integrations/16-capability-reference.mdindex b447e3995..e61881c54 100644--- a/docs/en/agent-integrations/16-capability-reference.md+++ b/docs/en/agent-integrations/16-capability-reference.md@@ -172,7 +172,7 @@ Core modules at a glance (detailed further in the per-dimension sections):| zcode | Config-driven (merged into `~/.zcode/cli/config.json`, forcing `hooks.enabled=true`) | One-line `--harness zcode` | `zc-<sess_…>` | env + ovcli.conf `plugin.zcode` | ❌ || opencode | npm plugin `@openviking/opencode-plugin` (its config hook dynamically injects the MCP entry) | One-line `--harness opencode` (uses npm registration with a proxy snapshot fallback) / manual npm / from source | `oc-<id>`; subagents use `oc-<parent>__subagent-<child>` | env + ovcli.conf `plugin.opencode` | ✅ || dsh | In-process Cordis plugin (`cordis.patch.yml` plugin group) | Unified installer (asks for the profile, default `web`), or `dsh plugin --profile web add @openviking/dsh-memory-plugin` | `dsh-<session.id as-is>`; each subagent is assigned its own session | env + ovcli.conf `plugin.dsh` + the cordis patch config, which is the lowest behavior layer (credentials still come from the patch first) | ❌ |-| pi | Native pi extension (loaded from a directory, with TypeScript transpiled on the fly via jiti) | One-line `--harness pi` (including `pi install` registration) | `pi-<piSessionId>` | env + ovcli.conf `plugin.pi` (credential fields are resolved via the shared credential chain) | ✅ |+| pi | Native pi extension (loaded from a directory, with TypeScript transpiled on the fly via jiti) | One-line `--harness pi` (copied into the auto-discovery directory, no `pi install` needed) | `pi-<piSessionId>` | env + ovcli.conf `plugin.pi` (credential fields are resolved via the shared credential chain) | ✅ || openclaw | context-engine plugin (`ownsCompaction:true`) + 15 tools + 5 slash + 4 hooks + HTTP routes | ClawHub: run `openclaw plugins install clawhub:@openviking/openclaw-plugin` alongside `openclaw openviking setup` / npm installer / TOS offline bundle | A UUID is lowercased as-is, otherwise `sha256(sessionKey)`; `memory_store` temporary sessions use `memory-store-<ts>-<rand>` | `plugins.entries.openviking.config` in `openclaw.json` (strictly validated: unknown keys or invalid values force the plugin into setup-only mode) + a few env vars | ✅ `openclaw openviking setup` (interactive/non-interactive + key role probing + version compatibility check) || hermes | Hermes bundled MemoryProvider (ships with Hermes; no plugin installation required) | Run `hermes memory setup openviking` (interactive curses wizard), or manually run `config set memory.provider openviking` + `.env` | Hermes generates `%Y%m%d_%H%M%S_<hex6>`; the plugin uses it verbatim | `.env` (`OPENVIKING_*`) or linked ovcli.conf (`use_ovcli_config` mode clears the 5 corresponding variables from .env) + config.yaml | ✅ (multi-level menu) || ov CLI | Native Rust binary | npm `@openviking/cli` / `uv tool install openviking` / cargo / GitHub Releases | Does not manage its own session (`ov chat` defaults to the machine-uid) | `ovcli.conf` (multiple profiles) + a few env vars | ✅ `ov config` (TUI wizard) |diff --git a/docs/zh/agent-integrations/11-pi.md b/docs/zh/agent-integrations/11-pi.mdindex d8cbb7f49..a2aedb2bd 100644--- a/docs/zh/agent-integrations/11-pi.md+++ b/docs/zh/agent-integrations/11-pi.md@@ -35,7 +35,7 @@ bash <(curl -fsSL https://raw.githubusercontent.com/volcengine/OpenViking/main/ebash <(curl -fsSL https://ovrelease.tos-cn-beijing.volces.com/memory-plugin-shared/install.sh)```-安装器会把扩展复制到 `~/.pi/agent/extensions/openviking`,用 `pi install` 完成注册,并配置 `~/.openviking/ovcli.conf`。+安装器会把扩展复制到 `~/.pi/agent/extensions/openviking`,并配置 `~/.openviking/ovcli.conf`。该目录是 pi 的自动发现根目录之一,复制到位后 pi 会在下次启动时自动加载,无需再执行 `pi install`。(对同一路径再跑 `pi install` 会让扩展被加载两遍——一次来自自动发现,一次来自 `packages` 条目——出现重复的 `/viking` 命令。)也可以从仓库 checkout 手动复制:@@ -44,7 +44,6 @@ git clone https://github.com/volcengine/OpenViking.gitcd OpenVikingmkdir -p ~/.pi/agent/extensionscp -r examples/pi-coding-agent-extension ~/.pi/agent/extensions/openviking-pi install ~/.pi/agent/extensions/openviking```## 配置@@ -100,7 +99,8 @@ Takeover 是 fail-open:如果 pending 写入无法 flush、commit 失败、arc| 问题 | 排查方向 ||------|----------|| 状态栏显示 `OV ✗` 或提示 "server not reachable" | `curl http://localhost:1933/health`;检查 `~/.openviking/ovcli.conf` 中的 endpoint |-| 扩展没有加载 | `pi list` 应能看到 `extensions/openviking`;重跑安装器或执行 `pi install ~/.pi/agent/extensions/openviking` |+| 扩展没有加载 | 确认 `~/.pi/agent/extensions/openviking/index.ts` 存在(该目录会被自动发现);重跑安装器即可。不要用 `pi install` 注册它——那样会重复加载 |+| `/viking` 命令出现两次(`viking:1` / `viking:2`) | 老版本安装器用 `pi install` 留下了冗余的 `packages` 条目,导致自动发现和 `packages` 各加载一次;执行 `pi remove ~/.pi/agent/extensions/openviking` 清掉该条目(只改 settings,不删文件) || 报错提到 `@mariozechner/*` | pi 迁移到 `@earendil-works/*` 之前的旧副本——重跑安装器 || OpenViking 返回 401 / 403 | 检查 `OPENVIKING_API_KEY`;trusted-mode 部署还要检查 `OPENVIKING_ACCOUNT` 和 `OPENVIKING_USER` || recall 为空 | 确认 server 中已有记忆,且 prompt 长度超过 `minQueryLength` |diff --git a/docs/zh/agent-integrations/16-capability-reference.md b/docs/zh/agent-integrations/16-capability-reference.mdindex 9366429aa..fc1be2b2a 100644--- a/docs/zh/agent-integrations/16-capability-reference.md+++ b/docs/zh/agent-integrations/16-capability-reference.md@@ -174,7 +174,7 @@ per-harness 章节(档案卡)只写差异;所有共享事实均在本章| zcode | 配置驱动(合并进 `~/.zcode/cli/config.json`,并强制 `hooks.enabled=true`) | 一键 `--harness zcode` | `zc-<sess_…>` | env + ovcli.conf `plugin.zcode` | ❌ || opencode | npm 插件 `@openviking/opencode-plugin`(config hook 自注入 MCP 条目) | 一键 `--harness opencode`(npm 注册 + 代理快照兜底)/ 手动 npm / 源码 | `oc-<id>`;subagent 格式为 `oc-<parent>__subagent-<child>` | env + ovcli.conf `plugin.opencode` | ✅ || dsh | Cordis 同进程插件(`cordis.patch.yml` plugin group) | 统一安装器(会询问 profile,默认 `web`),或执行 `dsh plugin --profile web add @openviking/dsh-memory-plugin` | `dsh-<session.id 原样>`;subagent 各自独立会话 | env + ovcli.conf `plugin.dsh` + cordis patch config(行为旋钮的最低层;凭据仍以 patch 优先) | ❌ |-| pi | pi 原生扩展(目录装载,jiti 直译 TS) | 一键 `--harness pi`(含 `pi install` 注册) | `pi-<piSessionId>` | env + ovcli.conf `plugin.pi`(凭据字段由凭据链统一解析) | ✅ |+| pi | pi 原生扩展(目录装载,jiti 直译 TS) | 一键 `--harness pi`(复制到自动发现目录,无需 `pi install`) | `pi-<piSessionId>` | env + ovcli.conf `plugin.pi`(凭据字段由凭据链统一解析) | ✅ || openclaw | context-engine 插件(`ownsCompaction:true`)+ 15 工具 + 5 slash + 4 hook + HTTP 路由 | ClawHub 执行 `openclaw plugins install clawhub:@openviking/openclaw-plugin` 搭配 `openclaw openviking setup` / npm 安装器 / TOS 离线包 | UUID 原样小写,否则 `sha256(sessionKey)`;`memory_store` 临时会话 `memory-store-<ts>-<rand>` | `openclaw.json` 的 `plugins.entries.openviking.config`(严格校验:存在未知键/非法值时插件进入 setup-only 模式)+ 少量 env | ✅ `openclaw openviking setup`(交互/非交互 + key 角色探测 + 版本兼容检查) || hermes | Hermes bundled MemoryProvider(随 Hermes 发布,无需装插件) | 执行 `hermes memory setup openviking`(curses 向导)或手动 `config set memory.provider openviking` + `.env` | 由 Hermes 生成 `%Y%m%d_%H%M%S_<hex6>`,插件原样使用 | `.env`(`OPENVIKING_*`)或 ovcli.conf 联动(`use_ovcli_config` 模式会清空 .env 里的 5 个对应变量)+ config.yaml | ✅(多层菜单) || ov CLI | Rust 原生二进制 | npm `@openviking/cli` / `uv tool install openviking` / cargo / GitHub Releases | 无自有会话(`ov chat` 默认使用 machine-uid) | `ovcli.conf`(多 profile)+ 少量 env | ✅ `ov config`(TUI 向导) |diff --git a/examples/memory-plugin-shared/install.sh b/examples/memory-plugin-shared/install.shindex 35317580c..a409e9e5e 100644--- a/examples/memory-plugin-shared/install.sh+++ b/examples/memory-plugin-shared/install.sh@@ -2338,8 +2338,16 @@ install_pi() {rm -rf "$dest"mkdir -p "$(dirname "$dest")"mv "$tmp" "$dest"- pi install "$dest" || warn "$(t 'pi extension copied but pi install registration failed; run pi install manually.' 'pi 扩展文件已复制,但 pi install 注册失败;请手动运行 pi install。')"- info "$(t 'pi extension installed:' 'pi 扩展已安装:') $dest"+ # ~/.pi/agent/extensions/ is one of pi's auto-discovery roots, so copying the+ # extension there is enough for pi to load it. Do NOT also `pi install` the+ # same path: that adds a "packages" entry pointing at the directory while+ # auto-discovery already found its index.ts, and pi dedupes on the canonical+ # path — a directory and its index.ts don't match, so the extension loads+ # twice (duplicate /viking command). Instead, purge any stale packages entry+ # left by older installer versions; `pi remove` on a local path only edits+ # settings and never deletes the copied files.+ pi remove "$dest" >/dev/null 2>&1 || true+ info "$(t 'pi extension installed (auto-discovered):' 'pi 扩展已安装(自动发现):') $dest"}# ---------------------------------------------------------------------------@@ -2558,16 +2566,16 @@ EOFfiif contains_harness pi; thenif [ -f "$HOME/.pi/agent/extensions/openviking/index.ts" ] || [ -f "$HOME/.pi/agent/extensions/openviking/index.js" ]; then- info "pi: $PLUGIN_NAME $(t 'extension files present' '扩展文件已存在')"+ info "pi: $PLUGIN_NAME $(t 'extension files present (auto-discovered)' '扩展文件已存在(自动发现)')"elsewarn "pi: $PLUGIN_NAME $(t 'extension files not found' '未找到扩展文件')"ok=0fiif command -v pi >/dev/null 2>&1; then+ # The extension lives under pi's auto-discovery root, so it must NOT appear+ # as a configured "packages" entry — a stale entry there loads it twice.if pi list 2>/dev/null | grep -q 'extensions/openviking'; then- info "pi: $PLUGIN_NAME $(t 'registered in pi settings' '已注册到 pi settings')"- else- warn "pi: $PLUGIN_NAME $(t 'not registered in pi settings' '未注册到 pi settings')"+ warn "pi: $PLUGIN_NAME $(t 'still registered as a package (duplicate load); run pi remove ~/.pi/agent/extensions/openviking' '仍作为 package 注册(会重复加载);请运行 pi remove ~/.pi/agent/extensions/openviking')"ok=0fifidiff --git a/examples/pi-coding-agent-extension/README.md b/examples/pi-coding-agent-extension/README.mdindex 697cbc7ce..c9f10afb3 100644--- a/examples/pi-coding-agent-extension/README.md+++ b/examples/pi-coding-agent-extension/README.md@@ -34,7 +34,7 @@ Use the shared installer:bash examples/memory-plugin-shared/install.sh --harness pi```-The installer copies the extension to `~/.pi/agent/extensions/openviking` and registers it with `pi install`. The extension loads on next `pi` invocation.+The installer copies the extension to `~/.pi/agent/extensions/openviking`, which is one of pi's auto-discovery roots, so pi loads it on the next `pi` invocation — no `packages` entry is needed. (Registering the same path with `pi install` would load it twice, so the installer avoids that and clears any stale entry left by older versions.)### 3. Configure (optional)