openviking-opencode 0.1.0 → 0.2.1

package/README.md

@@ -0,0 +1,148 @@
+# openviking-opencode
+
+[OpenViking](https://github.com/OpenVikingDB/OpenViking) official plugin for [OpenCode](https://opencode.ai).
+
+Automatically injects your indexed code repositories into the AI assistant's context, so it proactively searches them without you having to ask.
+
+## What It Does
+
+- **Auto-installs the `openviking` skill** into `~/.config/opencode/skills/openviking/` on first load
+- **Injects indexed repo summaries** into the system prompt so the AI knows what's available
+- **Auto-starts the OpenViking server** if it's installed and configured but not running
+- **Shows clear toast notifications** if setup is incomplete (missing install, missing config, failed start)
+
+## Prerequisites
+
+### 1. Install OpenViking
+
+```bash
+pip install openviking
+```
+
+### 2. Configure OpenViking
+
+OpenViking requires an embedding model and a VLM (for generating directory summaries). Create `~/.openviking/ov.conf`:
+
+```bash
+cp /path/to/OpenViking/examples/ov.conf.example ~/.openviking/ov.conf
+```
+
+Then fill in your API keys. Minimum required fields:
+
+```json
+{
+  "embedding": {
+    "provider": "openai",
+    "api_key": "sk-..."
+  },
+  "vlm": {
+    "provider": "openai",
+    "model": "gpt-4o-mini",
+    "api_key": "sk-..."
+  }
+}
+```
+
+> See the [OpenViking docs](https://github.com/OpenVikingDB/OpenViking) for all supported providers.
+
+### 3. Install OpenCode
+
+```bash
+npm install -g opencode-ai
+```
+
+## Installation
+
+Add the plugin to your OpenCode config at `~/.config/opencode/opencode.json`:
+
+```json
+{
+  "plugin": ["openviking-opencode"]
+}
+```
+
+OpenCode will automatically install the plugin via bun on next startup. No other steps needed — the skill is installed automatically.
+
+## Usage
+
+### Index a repository
+
+Once OpenViking is running, index any GitHub repo or local project:
+
+```
+# In OpenCode, just ask:
+"Add https://github.com/tiangolo/fastapi to OpenViking"
+```
+
+Indexing runs in the background. Small repos (~100 files) take 2–5 min; large repos (500+ files) can take 20–60 min. Search works progressively as files are indexed.
+
+### Search automatically
+
+Once repos are indexed, the AI will proactively search them when relevant — no need to ask:
+
+```
+"How does fastapi handle dependency injection?"
+→ AI automatically searches viking://resources/fastapi/ before answering
+
+"How is authentication implemented in my-project?"
+→ AI automatically searches viking://resources/my-project/ before answering
+```
+
+### Trigger manually
+
+You can also explicitly invoke the skill:
+
+```
+"Use openviking to find how JWT tokens are verified in my projects"
+```
+
+## Best Practices
+
+**Keep the server running persistently**
+
+The plugin auto-starts the server when OpenCode launches, but for the best experience start it as a background service:
+
+```bash
+openviking serve --config ~/.openviking/ov.conf > /tmp/openviking.log 2>&1 &
+```
+
+Or add it to your shell profile (`~/.zshrc` / `~/.bashrc`):
+
+```bash
+# Auto-start OpenViking if not already running
+openviking health 2>/dev/null || openviking serve --config ~/.openviking/ov.conf > /tmp/openviking.log 2>&1 &
+```
+
+**Use `viking://resources/` for all code repos**
+
+Always index under `viking://resources/` — this is the scope the plugin and skill are configured to search:
+
+```bash
+openviking add-resource https://github.com/owner/repo --to viking://resources/
+openviking add-resource /path/to/project --to viking://resources/
+```
+
+**Index repos you reference often**
+
+The more repos indexed, the more useful the AI becomes. Good candidates:
+- Internal libraries your project depends on
+- Open source libraries you frequently look up
+- Other projects in your monorepo
+
+**Don't index everything**
+
+Avoid indexing repos you rarely touch — it adds noise to search results. Use `openviking rm viking://resources/repo --recursive` to remove repos you no longer need.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---------|-----|
+| Toast: "openviking 未安装" | Run `pip install openviking` |
+| Toast: "未找到 ov.conf" | Create and configure `~/.openviking/ov.conf` |
+| Toast: "服务启动失败" | Check logs: `cat /tmp/openviking.log` |
+| AI doesn't search automatically | Ask "what repos do you have in openviking?" — if it can't answer, restart OpenCode |
+| Stale repo list | Restart OpenCode to refresh the repo cache |
+
+## License
+
+Apache-2.0

package/index.mjs

@@ -7,23 +7,54 @@ import { fileURLToPath } from "url"
 
 const execAsync = promisify(exec)
 const __dirname = dirname(fileURLToPath(import.meta.url))
+const OV_CONF = join(homedir(), ".openviking", "ov.conf")
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+async function run(cmd, opts = {}) {
+  return execAsync(cmd, { timeout: 10000, ...opts })
+}
+
+async function isInstalled() {
+  try {
+    await run("openviking --version")
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function isHealthy() {
+  try {
+    await run("openviking health")
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function startServer() {
+  // Start in background, wait up to 30s for healthy
+  await run("openviking serve --config " + OV_CONF + " > /tmp/openviking.log 2>&1 &")
+  for (let i = 0; i < 10; i++) {
+    await new Promise((r) => setTimeout(r, 3000))
+    if (await isHealthy()) return true
+  }
+  return false
+}
 
 // ── Skill auto-install ────────────────────────────────────────────────────────
 
 function installSkill() {
   const src = join(__dirname, "skills", "openviking", "SKILL.md")
   const dest = join(homedir(), ".config", "opencode", "skills", "openviking", "SKILL.md")
-  const destDir = dirname(dest)
   try {
-    if (!existsSync(destDir)) mkdirSync(destDir, { recursive: true })
+    if (!existsSync(dirname(dest))) mkdirSync(dirname(dest), { recursive: true })
     const content = readFileSync(src, "utf8")
-    // Only overwrite if content changed (avoid unnecessary disk writes)
     if (!existsSync(dest) || readFileSync(dest, "utf8") !== content) {
       writeFileSync(dest, content, "utf8")
     }
-  } catch {
-    // Non-fatal — skill stays as-is or isn't installed
-  }
+  } catch {}
 }
 
 // ── Repo context cache ────────────────────────────────────────────────────────
@@ -37,12 +68,10 @@ async function loadRepos() {
   if (cachedRepos !== null && now - lastFetchTime < CACHE_TTL_MS) return
 
   try {
-    const { stdout } = await execAsync(
-      "openviking --output json ls viking://resources/ --abs-limit 2000",
-      { timeout: 8000 }
+    const { stdout } = await run(
+      "openviking --output json ls viking://resources/ --abs-limit 2000"
     )
-    const parsed = JSON.parse(stdout)
-    const items = parsed?.result ?? []
+    const items = JSON.parse(stdout)?.result ?? []
     const repos = items
       .filter((item) => item.uri?.startsWith("viking://resources/"))
       .map((item) => {
@@ -51,14 +80,43 @@ async function loadRepos() {
           ? `- **${name}** (${item.uri})\n  ${item.abstract}`
           : `- **${name}** (${item.uri})`
       })
-
     if (repos.length > 0) {
       cachedRepos = repos.join("\n")
       lastFetchTime = now
     }
-  } catch {
-    // openviking not running — plugin is a no-op until it is
+  } catch {}
+}
+
+// ── Init: check deps, start server if needed ─────────────────────────────────
+
+async function init(client) {
+  const toast = (message, variant = "warning") =>
+    client.tui.showToast({
+      body: { title: "OpenViking", message, variant, duration: 8000 },
+    }).catch(() => {})
+
+  // 1. openviking 没装
+  if (!(await isInstalled())) {
+    await toast("openviking 未安装，请运行: pip install openviking", "error")
+    return false
   }
+
+  // 2. ov.conf 不存在（装了但没配置）
+  if (!existsSync(OV_CONF)) {
+    await toast("未找到 ~/.openviking/ov.conf，请先配置 API keys 后再启动服务", "warning")
+    return false
+  }
+
+  // 3. 服务没跑 → 静默自动启动
+  if (!(await isHealthy())) {
+    const started = await startServer()
+    if (!started) {
+      await toast("openviking 服务启动失败，查看日志: /tmp/openviking.log", "error")
+      return false
+    }
+  }
+
+  return true
 }
 
 // ── Plugin export ─────────────────────────────────────────────────────────────
@@ -66,9 +124,14 @@ async function loadRepos() {
 /**
  * @type {import('@opencode-ai/plugin').Plugin}
  */
-export async function OpenVikingPlugin() {
+export async function OpenVikingPlugin({ client }) {
   installSkill()
-  await loadRepos()
+
+  // 后台初始化，不阻塞 opencode 启动
+  Promise.resolve().then(async () => {
+    const ready = await init(client)
+    if (ready) await loadRepos()
+  })
 
   return {
     "experimental.chat.system.transform": (_input, output) => {
@@ -83,8 +146,11 @@ export async function OpenVikingPlugin() {
     },
 
     "session.created": async () => {
-      cachedRepos = null
-      await loadRepos()
+      const ready = await init(client)
+      if (ready) {
+        cachedRepos = null
+        await loadRepos()
+      }
     },
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openviking-opencode",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "OpenCode plugin for OpenViking — injects indexed repo context into the AI assistant and auto-installs the openviking skill",
   "type": "module",
   "main": "index.mjs",