@openviking/opencode-plugin 0.2.4 → 2026.9.9-1

package/INSTALL-ZH.md

@@ -92,6 +92,7 @@ export { OpenVikingPlugin, default } from "./openviking/index.mjs"
 ```json
 {
   "enabled": true,
+  "mcp": { "enabled": true },
   "timeoutMs": 30000,
   "repoContext": { "enabled": true, "cacheTtlMs": 60000 },
   "autoRecall": {
@@ -130,15 +131,29 @@ user/admin API key 的 API_KEY mode 时应留空。
 
 高级场景可以用 `OPENVIKING_PLUGIN_CONFIG` 指向其他配置文件路径。
 
+### 仅 Hooks 模式
+
+如果其他 MCP server 已经提供 OpenViking，可以关闭本插件附带的 MCP 注册，同时保留生命周期 hooks：
+
+```json
+{
+  "mcp": { "enabled": false }
+}
+```
+
+repository context、自动 recall、消息 capture 和生命周期 commit 会继续工作，也不会添加或覆盖
+OpenCode 的 `mcp.openviking` 配置。
+
 ## 验证
 
 修改插件或 OpenViking 配置后，需要重启 OpenCode。
 
 进入新的 OpenCode session 后，可以让 agent 浏览 OpenViking memory，或搜索一个已索引的资源。插件应暴露 OpenViking MCP server，OpenCode 中的工具名会带 `openviking_` 前缀：
 
-- `openviking_recall`、`openviking_search`、`openviking_find`
-- `openviking_read`、`openviking_list`、`openviking_grep`、`openviking_glob`
-- `openviking_remember`、`openviking_add_resource`、`openviking_forget`、`openviking_health`
+- `openviking_search`、`openviking_find`
+- `openviking_read`、`openviking_list`、`openviking_tree`、`openviking_grep`、`openviking_glob`
+- `openviking_remember`、`openviking_write`、`openviking_edit`、`openviking_add_resource`
+- `openviking_list_watches`、`openviking_cancel_watch`、`openviking_forget`、`openviking_health`
 - `openviking_list_watches`、`openviking_cancel_watch`
 
 如果行为异常，先查看运行时文件：
@@ -158,14 +173,16 @@ curl http://localhost:1933/health
 
 插件会通过 OpenCode config 注册 OpenViking stdio MCP proxy。服务端实际返回的 `tools/list` 是最终工具清单；当前 OpenViking server 暴露：
 
-- `openviking_recall`：面向当前任务的平衡召回
-- `openviking_search`：跨 memories/resources/skills 的深度语义检索
+- `openviking_search`：跨 memories/resources/skills 的深度语义检索；使用 `mode="context"` 获取面向当前任务、可直接注入的平衡上下文
 - `openviking_find`：快速语义检索
 - `openviking_remember`：存储重要事实或决策，供记忆提取
 - `openviking_read`：读取一个或多个 `viking://` 文件
 - `openviking_list`：列出 `viking://` 目录
+- `openviking_tree`：展示 `viking://` 目录树
 - `openviking_grep`：精确文本或正则搜索
 - `openviking_glob`：glob 文件匹配
+- `openviking_write`：创建、覆盖或追加 `viking://` 文件
+- `openviking_edit`：对 `viking://` 文件做精确字符串替换
 - `openviking_add_resource`：添加 URL、本地文件、sitemap 或 feed
 - `openviking_forget`：在用户明确确认后删除 `viking://` URI
 - `openviking_list_watches` / `openviking_cancel_watch`：查看或取消资源 watch

package/INSTALL.md

@@ -92,6 +92,7 @@ Example configuration:
 ```json
 {
   "enabled": true,
+  "mcp": { "enabled": true },
   "timeoutMs": 30000,
   "repoContext": { "enabled": true, "cacheTtlMs": 60000 },
   "autoRecall": {
@@ -126,15 +127,30 @@ API keys are resolved from environment variables or `~/.openviking/ovcli.conf` a
 
 For advanced setups, use `OPENVIKING_PLUGIN_CONFIG` to point to another configuration file path.
 
+### Hook-only mode
+
+If another MCP server already exposes OpenViking, set the bundled MCP registration to `false` while
+keeping this plugin's lifecycle hooks active:
+
+```json
+{
+  "mcp": { "enabled": false }
+}
+```
+
+Repository context, automatic recall, message capture, and lifecycle commits remain enabled. This
+does not add or overwrite OpenCode's `mcp.openviking` entry.
+
 ## Verify
 
 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 the OpenViking MCP server, with tools namespaced by OpenCode as `openviking_*`:
 
-- `openviking_recall`, `openviking_search`, `openviking_find`
-- `openviking_read`, `openviking_list`, `openviking_grep`, `openviking_glob`
-- `openviking_remember`, `openviking_add_resource`, `openviking_forget`, `openviking_health`
+- `openviking_search`, `openviking_find`
+- `openviking_read`, `openviking_list`, `openviking_tree`, `openviking_grep`, `openviking_glob`
+- `openviking_remember`, `openviking_write`, `openviking_edit`, `openviking_add_resource`
+- `openviking_list_watches`, `openviking_cancel_watch`, `openviking_forget`, `openviking_health`
 - `openviking_list_watches`, `openviking_cancel_watch`
 
 If anything looks wrong, check the runtime files:
@@ -154,14 +170,16 @@ curl http://localhost:1933/health
 
 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:
 
-- `openviking_recall`: balanced current-task recall.
-- `openviking_search`: deep semantic retrieval across memories, resources, and skills.
+- `openviking_search`: deep semantic retrieval across memories, resources, and skills; use `mode="context"` for balanced, injection-ready context.
 - `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_tree`: show a `viking://` directory tree.
 - `openviking_grep`: exact text or regex search.
 - `openviking_glob`: glob file matching.
+- `openviking_write`: create, overwrite, or append to a `viking://` file.
+- `openviking_edit`: exact string replacement in a `viking://` file.
 - `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.

package/README.md

@@ -2,6 +2,10 @@
 
 A unified OpenCode plugin for OpenViking repository retrieval and long-term memory.
 
+> **Requires an OpenViking server with `viking://~` home-alias support.** Recall targets the
+> caller's own context space through `viking://~/memories` and `viking://~/skills`; the uid-less
+> `viking://user/memories` shorthand is rejected by newer servers.
+
 This is the only OpenCode plugin example maintained in this repository. It supersedes the former split examples for indexed repository prompt injection and long-term memory.
 
 The plugin uses OpenCode hooks for lifecycle behavior and registers OpenViking's standard stdio MCP proxy for model tools. It does not install or require an OpenCode skill, and agents do not need to run `ov` shell commands.
@@ -114,6 +118,7 @@ Create `~/.config/opencode/openviking-config.json`:
 ```json
 {
   "enabled": true,
+  "mcp": { "enabled": true },
   "timeoutMs": 30000,
   "repoContext": { "enabled": true, "cacheTtlMs": 60000 },
   "autoRecall": {
@@ -140,14 +145,7 @@ when exact category ceilings are required.
 API keys are resolved from environment variables or `~/.openviking/ovcli.conf` and sent as `Authorization: Bearer ...` by both hooks and the MCP proxy. Recall goes through the server-side context face (`POST /api/v1/search/search` with `mode="context"`), falling back to the deprecated `/api/v1/search/recall` on older deployments. `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.
-By default the plugin derives a peer from the project directory using Claude's
-project-directory naming rule: every non-letter-or-digit character becomes `-`,
-with no path normalization. For example, `/Users/x/Dev/OpenViking` becomes
-`-Users-x-Dev-OpenViking`. Data-plane memory/resource requests send the
-effective peer as `X-OpenViking-Actor-Peer`; captured session messages store it
-as body `peer_id`. Configure `peerId` or `OPENVIKING_PEER_ID` to override the
-workspace-derived peer, or set `workspacePeer=false` /
-`OPENVIKING_WORKSPACE_PEER=0` to turn workspace-derived peers off.
+By default the plugin derives a peer from the git identity of the project directory: the normalized `origin` URL, else the repository root path. Outside a git repository no peer is sent at all, and what is remembered there goes to the user-level space `viking://user/<you>/memories`. `git@github.com:volcengine/OpenViking.git` becomes `github.com-volcengine-openviking`; the path fallback keeps the older naming rule where every non-letter-or-digit character becomes `-`, so `/Users/x/Dev/OpenViking` becomes `-Users-x-Dev-OpenViking`. One repository therefore keeps one peer across subdirectories, worktrees, clones and machines, while a fork's different origin keeps it separate. Derivation reads `.git` directly, so no `git` binary is needed. The plugin does not read workspace `.openviking/config.json` files, so a `peer.id` written there has no effect. Data-plane memory/resource requests send the effective peer as `X-OpenViking-Actor-Peer`; captured session messages store it as body `peer_id`. Configure `peerId` or `OPENVIKING_PEER_ID` to override the derived peer, or set `workspacePeer=false` / `OPENVIKING_WORKSPACE_PEER=0` to send no peer at all. Memories written under the older directory-derived peer stay reachable: the default broad recall sweeps every peer under the user, and `recallPeerScope="actor"` asks that previous peer separately.
 
 Recall defaults to the broad mode: global memory, the current workspace, and
 other workspace memories can all be recalled, with other workspaces penalized
@@ -159,10 +157,28 @@ with an explicit actor peer so one person's memories are not recalled into
 another person's session.
 
 `OPENVIKING_API_KEY`, `OPENVIKING_ACCOUNT`, `OPENVIKING_USER`,
-and `OPENVIKING_PEER_ID` take precedence over values in this file.
+and `OPENVIKING_PEER_ID` take precedence over values in this file. The config
+file's `peerId` still applies whenever shared credentials (ovcli.conf or
+environment variables) do not carry a peer of their own, so an authenticated
+setup keeps writing peer-scoped data instead of dropping into the shared user
+tree.
 
 For advanced setups, `OPENVIKING_PLUGIN_CONFIG` can point to another config file path.
 
+### Hook-only mode
+
+When OpenViking is already exposed through another MCP server, retain the lifecycle hooks while
+skipping this plugin's bundled MCP registration:
+
+```json
+{
+  "mcp": { "enabled": false }
+}
+```
+
+This leaves repository context, automatic recall, message capture, and lifecycle commits enabled.
+It does not add or overwrite OpenCode's `mcp.openviking` entry.
+
 OpenCode's local `read`, `glob`, and `grep` tools cannot read `viking://` URIs.
 When the agent accidentally tries that, the plugin blocks the filesystem tool
 call and points it to the OpenViking MCP tools.
@@ -171,14 +187,16 @@ call and points it to the OpenViking MCP tools.
 
 OpenCode sees the OpenViking MCP server as `openviking`, so tool names are namespaced with `openviking_`.
 
-- `openviking_recall`: balanced current-task recall using OpenViking's `/recall` endpoint.
-- `openviking_search`: deep semantic retrieval across memories, resources, and skills.
+- `openviking_search`: deep semantic retrieval across memories, resources, and skills; use `mode="context"` for balanced, injection-ready context.
 - `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_tree`: show a `viking://` directory tree.
 - `openviking_grep`: exact text or regex search.
 - `openviking_glob`: glob file matching.
+- `openviking_write`: create, overwrite, or append to a `viking://` file.
+- `openviking_edit`: exact string replacement in a `viking://` file.
 - `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.
@@ -194,3 +212,20 @@ The plugin writes runtime files to `~/.config/opencode/openviking/` by default:
 - `openviking-session-state.json`
 
 Set `runtime.dataDir` in config to override this directory.
+
+## Automated npm releases
+
+Changes merged into upstream `main` under `examples/opencode-plugin/` trigger
+`.github/workflows/opencode-plugin-release.yml`. Releases use the same calendar
+version convention as the OpenClaw plugin: `YYYY.M.D`, then `YYYY.M.D-N` for
+subsequent releases on that date (Asia/Shanghai). No manual source version bump
+is required. The workflow changes the version only in the package being published;
+it does not commit generated version changes back to the repository.
+
+Releases are serialized. A queued run checks out current `main`, so several quick
+merges may be included in one package. The npm manifest records
+`openvikingSourceCommit`; rerunning a successfully published commit skips publication.
+Registry failures stop the workflow instead of treating an unavailable registry as
+an unused version. Only upstream `main` can publish the official npm `latest` tag.
+Manual dispatch on `main` retries a failed release using the existing npm credentials
+or Trusted Publishing configuration.

package/index.mjs

@@ -44,8 +44,15 @@ export async function OpenVikingPlugin({ client, directory }) {
 
   return {
     config: async (opencodeConfig) => {
-      const injected = injectOpenVikingMcpConfig(opencodeConfig, pluginRoot)
-      log(injected ? "INFO" : "WARN", "mcp", injected ? "Registered OpenViking MCP server" : "OpenViking MCP server was not registered")
+      const injected = injectOpenVikingMcpConfig(opencodeConfig, pluginRoot, config.mcp.enabled)
+      const hookOnly = !config.mcp.enabled
+      log(
+        injected || hookOnly ? "INFO" : "WARN",
+        "mcp",
+        injected ? "Registered OpenViking MCP server" :
+          hookOnly ? "Skipped bundled MCP registration in hook-only mode" :
+            "OpenViking MCP server was not registered",
+      )
     },
 
     event: async ({ event }) => {

package/lib/config.mjs

@@ -21,6 +21,9 @@ const DEFAULT_CONFIG = {
   // it has to be switchable from the client that pays the latency.
   recallQueryExpansion: "auto",
   enabled: true,
+  mcp: {
+    enabled: true,
+  },
   timeoutMs: 30000,
   runtime: {
     dataDir: "",
@@ -42,7 +45,7 @@ const DEFAULT_CONFIG = {
   captureMode: "semantic",
   captureMaxLength: 24000,
   captureAssistantTurns: true,
-  captureToolMaxChars: 2000,
+  captureToolMaxChars: 1000000,
   commitTokenThreshold: 20000,
   commitKeepRecentCount: 10,
   profileTokenBudget: 10000,
@@ -120,6 +123,12 @@ function applyLegacyConnection(config, fileConfig) {
 
 function applyBehaviorConfig(config, fileConfig = {}) {
   if (fileConfig.enabled !== undefined) config.enabled = fileConfig.enabled !== false
+  const mcp = fileConfig.mcp && typeof fileConfig.mcp === "object" ? fileConfig.mcp : {}
+  config.mcp = {
+    ...DEFAULT_CONFIG.mcp,
+    ...mcp,
+    enabled: mcp.enabled !== false,
+  }
   if (fileConfig.timeoutMs !== undefined) config.timeoutMs = fileConfig.timeoutMs
   config.runtime = {
     ...DEFAULT_CONFIG.runtime,
@@ -236,6 +245,7 @@ function normalizeConfig(config) {
   config.accountId = config.account
   config.userId = config.user
   config.userAgent = USER_AGENT
+  config.harness = "opencode"
   config.timeoutMs = normalizeNumber(config.timeoutMs, DEFAULT_CONFIG.timeoutMs, 1000, 300000)
   config.repoContext.cacheTtlMs = normalizeNumber(
     config.repoContext.cacheTtlMs,
@@ -252,7 +262,7 @@ function normalizeConfig(config) {
   config.recallPeerScope = config.recallPeerScope === "actor" ? "actor" : "all"
   config.recallQueryExpansion = config.recallQueryExpansion === "off" ? "off" : "auto"
   config.captureMaxLength = Math.max(200, Math.min(100000, Math.round(Number(config.captureMaxLength) || 24000)))
-  config.captureToolMaxChars = Math.max(200, Math.min(20000, Math.round(Number(config.captureToolMaxChars) || 2000)))
+  config.captureToolMaxChars = Math.max(200, Math.min(1000000, Math.round(Number(config.captureToolMaxChars) || 1000000)))
   config.commitTokenThreshold = Math.max(1000, Math.round(Number(config.commitTokenThreshold) || 20000))
   const rawCommitKeepRecentCount = config.commitKeepRecentCount
   const commitKeepRecentCount = rawCommitKeepRecentCount == null ||
@@ -285,7 +295,11 @@ export function loadConfig(pluginRoot, projectDirectory) {
   config.apiKey = creds.apiKey
   config.account = creds.account
   config.user = creds.user
-  config.peerId = creds.peerId
+  // Shared credentials only carry a peer when ovcli.conf sets actor_peer_id
+  // (or OPENVIKING_PEER_ID is exported); without one the project config's
+  // peerId still applies so authenticated setups keep writing peer-scoped
+  // data instead of silently dropping into the shared user tree (#4487).
+  config.peerId = creds.peerId || str(fileConfig.peerId, "")
   config.mcpUrl = creds.mcpUrl
   config.credentialSource = creds.credentialSource
   config.credentialPath = creds.cliPath || creds.ovPath || ""

package/lib/mcp-config.mjs

@@ -11,8 +11,9 @@ export function createOpenVikingMcpConfig(pluginRoot) {
   }
 }
 
-export function injectOpenVikingMcpConfig(config, pluginRoot) {
+export function injectOpenVikingMcpConfig(config, pluginRoot, enabled = true) {
   if (!config || typeof config !== "object") return false
+  if (!enabled) return false
   config.mcp = config.mcp && typeof config.mcp === "object" ? config.mcp : {}
   const current = config.mcp[OPENCODE_MCP_NAME]
   if (current?.enabled === false) return false

package/lib/memory-recall.mjs

@@ -27,6 +27,7 @@ export function createMemoryRecall({ config, sessionManager }) {
       query,
       {
         actorPeerId: effectivePeerId(config),
+        legacyPeerId: config.effectivePeer?.legacyPeerId ?? "",
         // The mapped OV session is what turns on server-side query expansion
         // and the cross-turn dedup ledger.
         sessionId: sessionID ? sessionManager.getMappedSessionId(sessionID) : "",
@@ -57,8 +58,10 @@ export function extractCurrentUserText(parts) {
 
 function prependSyntheticRecallPart(input, output, injection) {
   const sessionID = input.sessionID ?? output.message?.sessionID
-  const messageID = input.messageID ?? output.message?.id
-  if (!sessionID || !messageID) return false
+  // messageID is optional in opencode's chat.message API (messageID?: string).
+  // When absent, generate a fallback so recall context is always injected.
+  const messageID = input.messageID ?? output.message?.id ?? `ov-recall-${Date.now()}`
+  if (!sessionID) return false
 
   output.parts.unshift({
     id: `prt-ov-recall-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,

package/lib/memory-session.mjs

@@ -30,6 +30,20 @@ export function createMemorySessionManager({ config, pluginRoot }) {
   const statePath = path.join(pluginRoot, "openviking-session-state.json")
   const oldSessionMapPath = path.join(pluginRoot, "openviking-session-map.json")
   let saveTimer = null
+  // Serialize saves: concurrent saveState() calls (a debounced save racing
+  // with flushAll / flushSession / session deletion) all share the same
+  // `${statePath}.tmp` temp file, so one rename can fail with ENOENT after
+  // another already moved it. Chaining through a promise queue keeps at most
+  // one write+rename in flight. Each queued save re-serializes the in-memory
+  // `sessions` map at execution time, so the last save always persists the
+  // latest state.
+  let saveChain = Promise.resolve()
+
+  function enqueueSave() {
+    const run = saveChain.then(() => saveState())
+    saveChain = run.catch(() => {})
+    return run
+  }
 
   async function init() {
     if (config.autoCapture) await migrateLegacySessionMap()
@@ -84,7 +98,7 @@ export function createMemorySessionManager({ config, pluginRoot }) {
   function debouncedSaveState() {
     if (saveTimer) clearTimeout(saveTimer)
     saveTimer = setTimeout(() => {
-      saveState().catch((error) => {
+      enqueueSave().catch((error) => {
         log("ERROR", "persistence", "Debounced save failed", { error: error?.message })
       })
     }, 300)
@@ -176,7 +190,7 @@ export function createMemorySessionManager({ config, pluginRoot }) {
     if (!sessionId) return
     await flushSession(sessionId, { commit: true, reason: event.type })
     sessions.delete(sessionId)
-    await saveState()
+    await enqueueSave()
   }
 
   async function handleSessionError(event) {
@@ -250,10 +264,20 @@ export function createMemorySessionManager({ config, pluginRoot }) {
       clearTimeout(saveTimer)
       saveTimer = null
     }
+    // Do not abort the whole dispose flush when one session fails (e.g. server
+    // already GC'd a stale session). Continue so later sessions still commit.
+    // See https://github.com/volcengine/OpenViking/issues/4490
     for (const sessionId of sessions.keys()) {
-      await flushSession(sessionId, { commit, reason: "flushAll" })
+      try {
+        await flushSession(sessionId, { commit, reason: "flushAll" })
+      } catch (err) {
+        console.warn(
+          `[opencode-plugin] flushAll skipped session ${sessionId}:`,
+          err?.message || err,
+        )
+      }
     }
-    await saveState()
+    await enqueueSave()
   }
 
   async function flushSession(opencodeSessionId, { commit = false, reason = "manual" } = {}) {
@@ -267,7 +291,7 @@ export function createMemorySessionManager({ config, pluginRoot }) {
     } else if (added > 0) {
       await maybeCommitByThreshold(state)
     }
-    await saveState()
+    await enqueueSave()
     return true
   }
 
@@ -441,15 +465,35 @@ export function createMemorySessionManager({ config, pluginRoot }) {
       for (const state of sessions.values()) {
         if (state.ovSessionId === ovSessionId) state.lastCommitTime = Date.now()
       }
-      log("INFO", "session", "Committed OpenViking session", { openviking_session: ovSessionId, reason })
-      return { status: "accepted", result: res.result }
+      const traceId = res.traceId || res.result?.trace_id
+      log("INFO", "session", "Committed OpenViking session", {
+        openviking_session: ovSessionId,
+        reason,
+        trace_id: traceId,
+      })
+      return { status: "accepted", result: res.result, traceId }
     }
     if (isRetryableFailure(res)) {
       await enqueue("commitSession", ovSessionId, body)
-      log("WARN", "session", "Queued OpenViking session commit", { openviking_session: ovSessionId, reason })
+      log("WARN", "session", "Queued OpenViking session commit", {
+        openviking_session: ovSessionId,
+        reason,
+        trace_id: res.traceId,
+        status: res.status,
+      })
       return { status: "queued" }
     }
-    throw new Error(`Failed to commit OpenViking session ${ovSessionId}: ${res.error?.message || res.status}`)
+    log("ERROR", "session", "Failed to commit OpenViking session", {
+      openviking_session: ovSessionId,
+      reason,
+      trace_id: res.traceId,
+      status: res.status,
+      error: res.error?.message || res.error?.code,
+    })
+    throw new Error(
+      `Failed to commit OpenViking session ${ovSessionId}: ${res.error?.message || res.status}` +
+      (res.traceId ? ` (trace_id=${res.traceId})` : ""),
+    )
   }
 
   async function migrateLegacySessionMap() {