@aliyunrds/ctxdb 0.0.9 → 1.0.0-beta.1

package/README.md

@@ -5,10 +5,12 @@ Unified access layer for RDS ContextDatabase. One `ctxdb` CLI (memory + KB ops),
 | Agent | Hooks | Skill install path | Skill style |
 |---|---|---|---|
 | **qoder** | ✅ UserPromptSubmit + Stop + SessionStart | `~/.qoder/skills/ctxdb/` | hooks-driven (auto capture/recall) |
+| **qoderwork** | ✅ UserPromptSubmit + Stop + SessionStart | `~/.qoderwork/skills/ctxdb/` | hooks-driven (auto capture/recall) |
 | **codex** | ✅ UserPromptSubmit + Stop + SessionStart | `~/.codex/skills/ctxdb/` | hooks-driven (auto capture/recall) |
 | **claude** | ✅ UserPromptSubmit + Stop + SessionStart | `~/.claude/skills/ctxdb/` | hooks-driven (auto capture/recall) |
+| **opencode** | Plugin shim (`~/.config/opencode/plugins/ctxdb.ts`) | `~/.config/opencode/skills/` | in-process plugin (auto capture/recall + KB catalog injection) |
 
-Config and logs live under `~/.ctxdb/`. `~/.ctxdb/ctxdb.json` is one file, but runtime config is isolated per agent under `agents.qoder`, `agents.codex`, and `agents.claude`. (Pre-2026-05-23 installs used `~/.ctxdb.json` at the home root; running `ctxdb setup --agent <name>` migrates the file into the selected agent section.)
+Config and logs live under `~/.ctxdb/`. `~/.ctxdb/ctxdb.json` is one file, but runtime config is isolated per agent under `agents.qoder`, `agents.qoderwork`, `agents.codex`, `agents.claude`, and `agents.opencode`. (Pre-2026-05-23 installs used `~/.ctxdb.json` at the home root; running `ctxdb setup --agent <name>` migrates the file into the selected agent section.)
 
 ## Install
 
@@ -17,10 +19,14 @@ npm install -g @aliyunrds/ctxdb
 
 # Qoder (hooks + skill)
 ctxdb setup --agent qoder --api-key ctxdb-...
+# QoderWork (hooks + skill)
+ctxdb setup --agent qoderwork --api-key ctxdb-...
 # Codex (hooks + skill)
 ctxdb setup --agent codex --api-key ctxdb-...
 # Claude Code (hooks + skill)
 ctxdb setup --agent claude --api-key ctxdb-...
+# OpenCode (plugin shim + skill)
+ctxdb setup --agent opencode --api-key ctxdb-...
 
 # --base-url defaults to https://context-database.aliyuncs.com (public prod).
 #   Pass --base-url <host> only if you target a different deployment
@@ -33,13 +39,13 @@ ctxdb setup --agent claude --api-key ctxdb-...
 ctxdb status --json
 ```
 
-Setup first checks that the target agent home exists (`~/.qoder`, `~/.codex`, or `~/.claude`). If the directory is missing, install or start that agent once before running `ctxdb setup --agent <name>`.
+Setup first checks that the target agent home exists (`~/.qoder`, `~/.qoderwork`, `~/.codex`, or `~/.claude`). If the directory is missing, install or start that agent once before running `ctxdb setup --agent <name>`. OpenCode is XDG-style: setup creates `~/.config/opencode` and `~/.config/opencode/plugins` when they are missing.
 
-For **qoder**, **codex**, and **claude**, restart the harness (CLI: just exit + restart; app: Cmd+R or quit/relaunch) so it picks up the new hooks/skill. For **codex**, setup also writes `[features].hooks = true` into `~/.codex/config.toml` (creating the file if missing) — Codex won't fire any hook entries without it. On first use Codex may prompt you to trust the new hook commands.
+For **qoder**, **qoderwork**, **codex**, and **claude**, restart the harness (CLI: just exit + restart; app: Cmd+R or quit/relaunch) so it picks up the new hooks/skill. For **codex**, setup also writes `[features].hooks = true` into `~/.codex/config.toml` (creating the file if missing) — Codex won't fire any hook entries without it. On first use Codex may prompt you to trust the new hook commands. For **opencode**, restart OpenCode so it loads `~/.config/opencode/plugins/ctxdb.ts`.
 
 ## What it does
 
-For **qoder**, **codex**, and **claude**, hooks fire automatically:
+For **qoder**, **qoderwork**, **codex**, and **claude**, hooks fire automatically:
 
 | Trigger | Hook | What runs |
 |---|---|---|
@@ -49,6 +55,8 @@ For **qoder**, **codex**, and **claude**, hooks fire automatically:
 
 Implementation note: qoder/Claude consume the JSON `hookSpecificOutput.additionalContext` shape; Codex has been verified on this machine through `~/.codex/hooks.json`, `[features].hooks = true`, and hook audit logs, where non-empty stdout from `UserPromptSubmit`/`SessionStart` is treated as injected context. The same hook core is shared; setup passes `--agent=<name>` so each hook reads its own config section.
 
+For **opencode**, `ctxdb setup --agent opencode` writes a small re-export shim at `~/.config/opencode/plugins/ctxdb.ts`. The shim points into this package's bundled `dist/opencode/index.js`, so `npm update -g @aliyunrds/ctxdb` updates the plugin implementation without copying source into the user config directory. `ctxdb upgrade --agent opencode` refreshes the absolute shim target after package moves.
+
 ## CLI
 
 `ctxdb` ships 18 subcommands:
@@ -59,7 +67,7 @@ Implementation note: qoder/Claude consume the JSON `hookSpecificOutput.additiona
 
 See `ctxdb --help`.
 
-`setup` without `--agent` writes `agents.default` in `~/.ctxdb/ctxdb.json` (CLI-only, no hooks or skills); with `--agent <qoder|codex|claude>` it writes agent config and installs hooks + skills for that harness. Memory and KB commands also accept `--agent <name>` so agents use their own config section; when omitted, `CTXDB_AGENT` env wins, otherwise `agents.default` is used. `uninstall` without `--agent` loops every supported agent; with `--agent <name>` it targets just that one. `teardown` is an alias for `uninstall`.
+`setup` without `--agent` writes `agents.default` in `~/.ctxdb/ctxdb.json` (CLI-only, no hooks or skills); with `--agent <qoder|qoderwork|codex|claude|opencode>` it writes agent config and installs hooks/plugins + skills for that harness. Memory and KB commands also accept `--agent <name>` so agents use their own config section; when omitted, `CTXDB_AGENT` env wins, otherwise `agents.default` is used. `uninstall` without `--agent` loops every supported agent; with `--agent <name>` it targets just that one. `teardown` is an alias for `uninstall`.
 
 `memory add … --no-infer` stores the text verbatim (skips server-side LLM
 fact-extraction). Use it when the user explicitly asks for a verbatim
@@ -87,20 +95,22 @@ Lives at `~/.ctxdb/ctxdb.json` (co-located with logs at `~/.ctxdb/logs/`). Schem
       "user_id": "default",
       "auto_capture": true,
       "auto_recall": true,
-      "warmup_recall": true,
+      "warmup_recall": false,
       "recall_knowledge": false,
       "top_k": 5,
       "threshold": 0.4,
       "knowledge_top_k": 6,
       "debug": false
     },
+    "qoderwork": { "...": "same schema, independent values" },
     "codex": { "...": "same schema, independent values" },
-    "claude": { "...": "same schema, independent values" }
+    "claude": { "...": "same schema, independent values" },
+    "opencode": { "...": "same schema, independent values" }
   }
 }
 ```
 
-Agent selection is driven by `--agent <qoder|codex|claude|default>` on every CLI invocation, falling back to `CTXDB_AGENT` env, then to `default`. There is no `default_agent` field — older installs that have one written get it dropped on the next save.
+Agent selection is driven by `--agent <qoder|qoderwork|codex|claude|opencode|default>` on every CLI invocation, falling back to `CTXDB_AGENT` env, then to `default`. There is no `default_agent` field — older installs that have one written get it dropped on the next save.
 
 Field reference:
 
@@ -109,7 +119,7 @@ Field reference:
 | `user_id` | str | `"default"` | mem0-layer bucket key on every capture/recall call. The server's tenant isolation runs on `member_id` (injected from `X-API-Key`), so this is an optional per-user/agent slice. Override with `ctxdb setup --agent <a> --user-id <bucket>` or `CTXDB_USER_ID=<bucket>` when you need to isolate this install from another access layer or machine sharing the same workspace |
 | `auto_capture` | bool | `true` | Stop hook captures each turn into long-term memory for the selected agent |
 | `auto_recall` | bool | `true` | UserPromptSubmit hook recalls memory on each user prompt for the selected agent |
-| `warmup_recall` | bool | `true` | SessionStart hook recalls cwd/git-related memories for the selected agent |
+| `warmup_recall` | bool | `false` | SessionStart hook recalls cwd/git-related memories for the selected agent. **Default is off** — open it per-agent when you want session-start warmup (adds one bounded, circuit-protected recall call on session start) |
 | `recall_knowledge` | bool | `false` | When `auto_recall` is on, also pull KB chunks alongside memory. Default is **off** — the recommended KB-recall path is the agent calling `kb search --agent <name>` explicitly when the user asks |
 | `top_k` / `threshold` | int / float | `5` / `0.4` | Memory recall pagination + similarity floor. `5` keeps the codex TUI `hook context: ...` line short enough to scan and bounds token spend on the modal recall path; raise it per-agent if you want more candidates |
 | `knowledge_top_k` | int | `6` | KB chunks pulled per recall (only effective when `recall_knowledge: true`) |
@@ -121,6 +131,8 @@ Env-var overrides apply to the selected agent config (env wins): `CTXDB_AGENT` /
 
 ```
 @aliyunrds/ctxdb            ← this package (CLI + setup + hooks + skills)
+       │
+       ├─ bundles OpenCode plugin in dist/opencode/index.js
        │
        └─ depends on @aliyunrds/ctxdb-shared  ← input sanitation,
                                           prompt-injection defenses,
@@ -155,8 +167,10 @@ After step 1, `ctxdb uninstall` prints the exact `npm uninstall` command to run
 # itself is unlinked so a future `ctxdb setup --agent <X>` runs through the
 # first-time install path cleanly.
 ctxdb uninstall --agent qoder
+ctxdb uninstall --agent qoderwork
 ctxdb uninstall --agent codex
 ctxdb uninstall --agent claude
+ctxdb uninstall --agent opencode
 
 # Wholesale across all agents, but keep config + logs for re-setup later:
 ctxdb uninstall                  # all agents, keeps ~/.ctxdb/{ctxdb.json,logs/}

package/dist/{chunk-PZJZ5O62.js → chunk-PLWEIEFH.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   configDir
-} from "./chunk-TOXXGL5L.js";
+} from "./chunk-QHYJ7OXC.js";
 
 // src/lib/circuit.ts
 import { statSync, writeFileSync, unlinkSync, mkdirSync, readdirSync, readFileSync } from "fs";

package/dist/{chunk-TOXXGL5L.js → chunk-QHYJ7OXC.js}

@@ -262,7 +262,7 @@ function extractErrorDetail(text, fallback) {
 // src/lib/agents.ts
 import { homedir as homedir2 } from "os";
 import { join as join3 } from "path";
-var SUPPORTED_AGENTS = ["qoder", "qoderwork", "codex", "claude"];
+var SUPPORTED_AGENTS = ["qoder", "qoderwork", "codex", "claude", "opencode"];
 function isBuiltinAgent(v) {
   return typeof v === "string" && SUPPORTED_AGENTS.includes(v);
 }
@@ -280,9 +280,12 @@ function agentHomeDir(agent) {
       return join3(homedir2(), ".codex");
     case "claude":
       return join3(homedir2(), ".claude");
+    case "opencode":
+      return join3(homedir2(), ".config", "opencode");
   }
 }
 var AGENT_VARIANT_HOMES = {
+  qoder: [".qoder-cn"],
   qoderwork: [".qoderworkcn"]
 };
 function agentHomeDirs(agent) {

package/dist/{chunk-RHWGDY6S.js → chunk-QPFFMW52.js}

@@ -6,10 +6,10 @@ import {
   isConnectionError,
   resetCircuit,
   tripCircuit
-} from "./chunk-PZJZ5O62.js";
+} from "./chunk-PLWEIEFH.js";
 import {
   CtxdbError
-} from "./chunk-TOXXGL5L.js";
+} from "./chunk-QHYJ7OXC.js";
 
 // src/lib/recall-orchestrator.ts
 import {
@@ -165,7 +165,7 @@ async function fetchKbCatalogBlock(client, agent) {
   });
   return [
     "<available-knowledge-bases>",
-    `When you identify that relevant information may exist in the knowledge bases below, you MUST run \`ctxdb kb search "<query>" --kb=<name> --agent=${agent}\` with targeted keywords after initial analysis to supplement and correct your approach. Knowledge bases:`,
+    `When you identify that relevant information may exist in the knowledge bases below, you MUST run \`ctxdb kb search "<query>" --kb=<name> --agent=${agent}\` with targeted keywords after initial analysis to supplement and correct your approach. For keyword-based KB search, keep each single query focused: use at most 5 keywords or short phrases; run multiple targeted searches if more are needed. Knowledge bases:`,
     ...lines,
     "</available-knowledge-bases>"
   ].join("\n");

package/dist/cli/main.js

@@ -31,7 +31,7 @@ import {
   removeAgent,
   save,
   writeInstalledPkgVersion
-} from "../chunk-TOXXGL5L.js";
+} from "../chunk-QHYJ7OXC.js";
 
 // src/cli/util.ts
 var BOOLEAN_FLAGS = /* @__PURE__ */ new Set([
@@ -115,6 +115,9 @@ var BOLD = "\x1B[1m";
 var RESET = "\x1B[0m";
 var CHECK = `${GREEN}\u2714${RESET}`;
 var CROSS = `${RED}\u2718${RESET}`;
+function dim(text) {
+  return `${DIM}${text}${RESET}`;
+}
 function isSetupResult(v) {
   if (typeof v !== "object" || v === null) return false;
   return "steps" in v && Array.isArray(v.steps);
@@ -249,11 +252,14 @@ function skillInstallRoot(agent) {
       return join(homedir(), ".codex", "skills");
     case "claude":
       return join(homedir(), ".claude", "skills");
+    case "opencode":
+      return join(homedir(), ".config", "opencode", "skills");
   }
 }
 var SKILL_DIRS = ["contextdb-memory", "contextdb-knowledge"];
 var LEGACY_SKILL_DIRS = ["ctxdb"];
 function agentSupportsHooks(agent) {
+  if (agent === "opencode") return false;
   return isBuiltinAgent(agent);
 }
 function hookConfigPath(agent) {
@@ -266,6 +272,8 @@ function hookConfigPath(agent) {
       return join(homedir(), ".codex", "hooks.json");
     case "claude":
       return join(homedir(), ".claude", "settings.json");
+    case "opencode":
+      return null;
   }
 }
 var LEGACY_QODER_SKILL_DIRS = [
@@ -274,6 +282,24 @@ var LEGACY_QODER_SKILL_DIRS = [
   "qoder-ctxdb"
 ];
 var HOOK_EVENTS = ["UserPromptSubmit", "Stop", "SessionStart"];
+var MIN_NODE_MAJOR = 20;
+function parseNodeMajor(version) {
+  const match = /^v?(\d+)/.exec(version.trim());
+  if (!match) return null;
+  const major = Number.parseInt(match[1], 10);
+  return Number.isFinite(major) ? major : null;
+}
+function checkCurrentNodeVersion() {
+  const version = process.versions.node;
+  const major = parseNodeMajor(version);
+  if (major !== null && major >= MIN_NODE_MAJOR) return null;
+  const current = version.startsWith("v") ? version : `v${version}`;
+  return {
+    step: "check-node-version",
+    ok: false,
+    detail: `Node.js >=${MIN_NODE_MAJOR} is required by ctxdb; current ${current} at ${process.execPath}. Switch to Node 20+ (for example: \`nvm install 20 && nvm use 20\`), reinstall @aliyunrds/ctxdb, then rerun \`ctxdb setup\`.`
+  };
+}
 async function runSetup(options) {
   const steps = [];
   if (!isAgentSlug(options.agent)) {
@@ -287,6 +313,11 @@ async function runSetup(options) {
   const agent = options.agent;
   const installSkill = options.installSkill !== false;
   const validate = options.validate !== false;
+  const nodeVersionCheck = checkCurrentNodeVersion();
+  if (nodeVersionCheck) {
+    steps.push(nodeVersionCheck);
+    return { ok: false, steps };
+  }
   if (isBuiltinAgent(agent)) {
     const homeCheck = checkAgentHome(agent);
     steps.push(homeCheck);
@@ -407,6 +438,32 @@ async function runSetup(options) {
       }
     }
   }
+  if (agent === "opencode") {
+    const absEntry = resolveOpencodePluginEntry();
+    if (!absEntry) {
+      steps.push({
+        step: "install-opencode-shim",
+        ok: false,
+        detail: "could not resolve plugin entry under @aliyunrds/ctxdb/dist/opencode"
+      });
+      return { ok: false, steps };
+    }
+    try {
+      writeOpencodeShim(absEntry);
+      steps.push({
+        step: "install-opencode-shim",
+        ok: true,
+        detail: `${opencodeShimPath()} \u2192 ${absEntry}`
+      });
+    } catch (err) {
+      steps.push({
+        step: "install-opencode-shim",
+        ok: false,
+        detail: err?.message ?? String(err)
+      });
+      return { ok: false, steps };
+    }
+  }
   if (validate) {
     if (!cfg.apiKey || !cfg.baseUrl) {
       steps.push({
@@ -429,8 +486,14 @@ async function runSetup(options) {
     }
   }
   const ok = steps.every((s) => s.ok);
-  const hints = ok ? [UNINSTALL_ORDER_HINT] : void 0;
-  return { ok, steps, hints };
+  const hints = ok ? [UNINSTALL_ORDER_HINT] : [];
+  if (ok && agent === "opencode") {
+    hints.unshift(
+      `OpenCode plugin shim: ${opencodeShimPath()}`,
+      "Restart OpenCode to load the plugin. `ctxdb upgrade` auto-refreshes the shim after npm updates; only re-run setup if you move ctxdb's install dir."
+    );
+  }
+  return { ok, steps, hints: hints.length > 0 ? hints : void 0 };
 }
 function runRemove(agent, options = {}) {
   const steps = [];
@@ -537,6 +600,32 @@ function runRemove(agent, options = {}) {
       }
     }
   }
+  if (agent === "opencode") {
+    const removed = removeOpencodeShim();
+    steps.push({
+      step: "remove-opencode-shim",
+      ok: true,
+      detail: removed ? opencodeShimPath() : "nothing to remove"
+    });
+    const root = skillInstallRoot(agent);
+    const dirs = [
+      ...SKILL_DIRS.map((d) => join(root, d)),
+      ...LEGACY_SKILL_DIRS.map((d) => join(root, d))
+    ];
+    for (const p of dirs) {
+      if (!existsSync(p)) continue;
+      try {
+        rmSync(p, { recursive: true, force: true });
+        steps.push({ step: "remove-skill-dir", ok: true, detail: p });
+      } catch (err) {
+        steps.push({
+          step: "remove-skill-dir",
+          ok: false,
+          detail: `${p}: ${err?.message ?? String(err)}`
+        });
+      }
+    }
+  }
   try {
     const r = removeAgent(agent, void 0, {
       keepEmptyShell: !!options.keepConfigShell
@@ -570,6 +659,19 @@ function runRemove(agent, options = {}) {
   return { ok: steps.every((s) => s.ok), steps };
 }
 function checkAgentHome(agent) {
+  if (agent === "opencode") {
+    const primary = agentHomeDir(agent);
+    try {
+      mkdirSync(primary, { recursive: true });
+      return { step: "check-agent-home", ok: true, detail: primary };
+    } catch (err) {
+      return {
+        step: "check-agent-home",
+        ok: false,
+        detail: `${primary}: ${err?.message ?? String(err)}`
+      };
+    }
+  }
   const dirs = agentHomeDirs(agent).filter((d) => existsSync(d));
   if (dirs.length === 0) {
     const primary = agentHomeDir(agent);
@@ -679,6 +781,7 @@ function verifyNodeBinary(nodePath) {
   }
 }
 function checkHookNodePaths(agent) {
+  if (agent === "opencode") return checkOpencodeShimHealth();
   const empty = {
     installed: false,
     nodePaths: [],
@@ -712,7 +815,7 @@ function checkHookNodePaths(agent) {
             if (closeQuote > 1) nodePath = cmd.slice(1, closeQuote);
           } else {
             const parts = cmd.split(" ");
-            if (parts.length >= 2 && !parts[0].endsWith(".js") && !parts[0].endsWith(".ts")) {
+            if (parts.length >= 2 && !parts[0].endsWith(".js") && !parts[0].endsWith(".ts") && (parts[0].includes("/") || parts[0].includes("\\"))) {
               nodePath = parts[0];
             }
           }
@@ -742,6 +845,51 @@ function checkHookNodePaths(agent) {
   }
   return { installed: true, nodePaths: paths, nodeOk: true, detail: `${paths[0]} (${goodVersion})` };
 }
+function checkOpencodeShimHealth() {
+  const path = opencodeShimPath();
+  if (!existsSync(path)) {
+    return {
+      installed: false,
+      nodePaths: [],
+      nodeOk: false,
+      detail: `opencode shim not installed \u2014 run \`ctxdb setup --agent opencode\``
+    };
+  }
+  let text = "";
+  try {
+    text = readFileSync(path, "utf-8");
+  } catch (err) {
+    return {
+      installed: true,
+      nodePaths: [],
+      nodeOk: false,
+      detail: `opencode shim unreadable: ${err?.message ?? String(err)}`
+    };
+  }
+  const target = text.match(/export\s+\{\s*default\s*\}\s+from\s+["']([^"']+)["'];/)?.[1];
+  if (!target) {
+    return {
+      installed: true,
+      nodePaths: [],
+      nodeOk: false,
+      detail: `opencode shim malformed: ${path} \u2014 re-run \`ctxdb setup --agent opencode\``
+    };
+  }
+  if (!existsSync(target)) {
+    return {
+      installed: true,
+      nodePaths: [target],
+      nodeOk: false,
+      detail: `opencode shim target missing: ${target} \u2014 re-run \`ctxdb setup --agent opencode\``
+    };
+  }
+  return {
+    installed: true,
+    nodePaths: [target],
+    nodeOk: true,
+    detail: `opencode shim: ${path} \u2192 ${target}`
+  };
+}
 var SETTINGS_BACKUP_KEEP = 5;
 function backupSettingsFile(path) {
   if (!existsSync(path)) return;
@@ -899,10 +1047,12 @@ function copySkillDir(src, dest, agent) {
 }
 var SKILL_INSTALL_TARGETS = {
   qoder: join(homedir(), ".qoder", "skills"),
+  qodercn: join(homedir(), ".qoder-cn", "skills"),
   qoderwork: join(homedir(), ".qoderwork", "skills"),
   qoderworkcn: join(homedir(), ".qoderworkcn", "skills"),
   codex: join(homedir(), ".codex", "skills"),
   claude: join(homedir(), ".claude", "skills"),
+  opencode: join(homedir(), ".config", "opencode", "skills"),
   openclaw: join(homedir(), ".openclaw", "skills"),
   hermes: join(homedir(), ".hermes", "skills")
 };
@@ -958,6 +1108,39 @@ function appendHooks(agent, hookPaths) {
   if (!path) return;
   appendHooksToFile(path, agent, hookPaths);
 }
+var OPENCODE_SHIM_FILENAME = "ctxdb.ts";
+function opencodeShimPath() {
+  return join(homedir(), ".config", "opencode", "plugins", OPENCODE_SHIM_FILENAME);
+}
+function resolveOpencodePluginEntry() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const pkgRoot = walkUpToPackageJson(here, "@aliyunrds/ctxdb");
+  if (!pkgRoot) return null;
+  const candidates = [
+    join(pkgRoot, "dist", "opencode", "index.js"),
+    join(pkgRoot, "..", "opencode", "src", "index.ts")
+  ];
+  return candidates.find((candidate) => existsSync(candidate)) ?? null;
+}
+var OPENCODE_SHIM_HEADER = "// Generated by ctxdb setup --agent opencode. Do not edit by hand.\n// To refresh after moving ctxdb's install directory, run ctxdb upgrade --agent opencode or re-run setup.\n// To remove, run: ctxdb setup --remove --agent opencode\n";
+function writeOpencodeShim(absEntry) {
+  const path = opencodeShimPath();
+  mkdirSync(dirname(path), { recursive: true });
+  const importSpec = absEntry.replace(/\\/g, "/");
+  const body = `${OPENCODE_SHIM_HEADER}export { default } from ${JSON.stringify(importSpec)};
+`;
+  writeFileSync(path, body, "utf-8");
+}
+function removeOpencodeShim() {
+  const path = opencodeShimPath();
+  if (!existsSync(path)) return false;
+  try {
+    unlinkSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
 var ENTRY_MARKER_KEY = "_ctxdb";
 var ENTRY_MARKER_VALUE = "@aliyunrds/ctxdb";
 var ENTRY_AGENT_KEY = "_ctxdbAgent";
@@ -967,7 +1150,8 @@ var TOOL_SCOPED_EVENTS = /* @__PURE__ */ new Set(["PreToolUse", "PostToolUse"]);
 function appendOne(hooks, event, command, agent) {
   if (!Array.isArray(hooks[event])) hooks[event] = [];
   const useExecForm = agent === "claude";
-  const shellCmd = process.platform === "win32" ? `"${process.execPath.replace(/\\/g, "/")}" "${command.replace(/\\/g, "/")}" --agent=${agent}` : `${process.execPath} ${command} --agent=${agent}`;
+  const cmdRunner = agent === "qoder";
+  const shellCmd = process.platform === "win32" ? cmdRunner ? `node ${command.replace(/\\/g, "/")} --agent=${agent}` : `"${process.execPath.replace(/\\/g, "/")}" "${command.replace(/\\/g, "/")}" --agent=${agent}` : `${process.execPath} ${command} --agent=${agent}`;
   const dup = hooks[event].some(
     (entry2) => Array.isArray(entry2?.hooks) && entry2.hooks.some(
       (h) => h?.type === "command" && (Array.isArray(h.args) && h.args[0] === command || typeof h.command === "string" && h.command.includes(command))
@@ -1300,6 +1484,28 @@ function upgradeOneAgent(agent) {
       }
     }
   }
+  if (agent === "opencode") {
+    const absEntry = resolveOpencodePluginEntry();
+    if (!absEntry) {
+      steps.push({
+        step: "refresh-opencode-shim",
+        ok: false,
+        detail: "could not resolve plugin entry under @aliyunrds/ctxdb/dist/opencode"
+      });
+      return { ok: false, steps };
+    }
+    try {
+      writeOpencodeShim(absEntry);
+      steps.push({
+        step: "refresh-opencode-shim",
+        ok: true,
+        detail: `${opencodeShimPath()} \u2192 ${absEntry}`
+      });
+    } catch (err) {
+      steps.push({ step: "refresh-opencode-shim", ok: false, detail: err?.message ?? String(err) });
+      return { ok: false, steps };
+    }
+  }
   return { ok: steps.every((s) => s.ok), steps };
 }
 
@@ -1360,7 +1566,7 @@ async function ping(args) {
 var HELP = `ctxdb setup \u2014 configure an agent
 
 USAGE
-  ctxdb setup [--agent <qoder|qoderwork|codex|claude>]
+  ctxdb setup [--agent <qoder|qoderwork|codex|claude|opencode>]
               [--api-key=K] [--base-url=URL] [--user-id=ID]
               [--no-install-skill] [--no-validate] [--json]
 
@@ -1371,7 +1577,7 @@ BEHAVIOR
                    specified agent harness.
 
 FLAGS
-  --agent <name>        Target agent (qoder|qoderwork|codex|claude)
+  --agent <name>        Target agent (qoder|qoderwork|codex|claude|opencode)
   --api-key <key>       API key (required on first setup)
   --base-url <url>      Server URL (default: https://context-database.aliyuncs.com)
   --user-id <id>        User bucket (default: "default")
@@ -1398,7 +1604,7 @@ async function setup(args) {
   const json = !!args.flags.json;
   if (agent === "default" && !json && !configuredAgents().includes("default")) {
     process.stderr.write(
-      `hint: creating CLI-only "default" agent (no hooks/skills). Use --agent <claude|qoder|qoderwork|codex> for full setup.
+      `hint: creating CLI-only "default" agent (no hooks/skills). Use --agent <claude|qoder|qoderwork|codex|opencode> for full setup.
 `
     );
   }
@@ -1416,6 +1622,13 @@ async function setup(args) {
 ${h}
 `);
   }
+  if (!json && agent === "codex" && result.ok) {
+    process.stderr.write(
+      `
+${dim("codex hooks \u914D\u7F6E\u540E\uFF0C\u9700\u8981\u91CD\u542F Codex \u5BF9\u8BDD\uFF0C\u5728\u5F39\u51FA\u7684 hooks \u786E\u8BA4\u754C\u9762\u9009\u62E9\u63A5\u6536\u6240\u6709 hooks(\u94A9\u5B50)\u9009\u9879")}
+`
+    );
+  }
   return result.ok ? 0 : 1;
 }
 
@@ -1423,11 +1636,11 @@ ${h}
 var HELP2 = `ctxdb uninstall \u2014 remove hooks + skills
 
 USAGE
-  ctxdb uninstall [--agent <qoder|qoderwork|codex|claude>] [--purge-config] [--purge-logs] [--purge-all] [--json]
+  ctxdb uninstall [--agent <qoder|qoderwork|codex|claude|opencode>] [--purge-config] [--purge-logs] [--purge-all] [--json]
 
 DEFAULT BEHAVIOR (no --agent, no purge flags)
   Strips ctxdb hook entries and skill directories for ALL agents (qoder,
-  qoderwork, codex, claude). Keeps ~/.ctxdb/ctxdb.json (credentials) and ~/.ctxdb/logs/
+  qoderwork, codex, claude, opencode). Keeps ~/.ctxdb/ctxdb.json (credentials) and ~/.ctxdb/logs/
   so you can re-run \`ctxdb setup\` later without losing configuration.
 
 WITH --agent <name>
@@ -1435,7 +1648,7 @@ WITH --agent <name>
   Other agents remain untouched.
 
 FLAGS
-  --agent <name>   Target a single agent (qoder|qoderwork|codex|claude)
+  --agent <name>   Target a single agent (qoder|qoderwork|codex|claude|opencode)
   --purge-config   Also delete ~/.ctxdb/ctxdb.json
   --purge-logs     Also delete ~/.ctxdb/logs/
   --purge-all      Delete everything under ~/.ctxdb/
@@ -1593,7 +1806,7 @@ function runSelfUpdate(currentVersion, passthroughArgs = []) {
 var HELP3 = `ctxdb upgrade \u2014 refresh skills + hooks
 
 USAGE
-  ctxdb upgrade [--agent <qoder|qoderwork|codex|claude>] [--self-update] [--json]
+  ctxdb upgrade [--agent <qoder|qoderwork|codex|claude|opencode>] [--self-update] [--json]
 
 BEHAVIOR
   Refreshes skill files and hook entries for configured agents without
@@ -1603,7 +1816,7 @@ BEHAVIOR
   With --agent:    upgrades only the specified agent.
 
 FLAGS
-  --agent <name>   Target a single agent (qoder|qoderwork|codex|claude)
+  --agent <name>   Target a single agent (qoder|qoderwork|codex|claude|opencode)
   --self-update    Also pull latest package from npm before upgrading
   --json           Machine-readable JSON output
 `;
@@ -1709,7 +1922,11 @@ function skillInstall(args) {
     }
     targetRoot = resolved;
   }
-  const templateAgent = target && isBuiltinAgent(target) ? target : "default";
+  const TARGET_TEMPLATE_AGENT = {
+    qodercn: "qoder",
+    qoderworkcn: "qoderwork"
+  };
+  const templateAgent = TARGET_TEMPLATE_AGENT[target] ?? (target && isBuiltinAgent(target) ? target : "default");
   const result = installSkillsTo(targetRoot, templateAgent);
   const ok = result.ok;
   const output = {
@@ -1966,7 +2183,7 @@ USAGE
   ctxdb <command> [args] [--flags]
 
 COMMANDS
-  setup [--agent <qoder|qoderwork|codex|claude>]
+  setup [--agent <qoder|qoderwork|codex|claude|opencode>]
         [--api-key=K] [--base-url=URL] [--user-id=ID]
         [--no-install-skill] [--no-validate] [--json]
                                  Without --agent \u2192 writes agents.default (CLI-only, no hooks/skills)
@@ -1974,6 +2191,7 @@ COMMANDS
                                  QoderWork  \u2192 writes agents.qoderwork config + ~/.qoderwork/settings.json hooks + skill
                                  Codex      \u2192 writes agents.codex config + ~/.codex/hooks.json hooks + skill
                                  Claude     \u2192 writes agents.claude config + ~/.claude/settings.json hooks + skill
+                                 OpenCode   \u2192 writes agents.opencode config + ~/.config/opencode/plugins/ctxdb.ts shim + skill
   status [--agent <name>] [--json]
   ping [--agent <name>] [--json]
   uninstall [--agent <name>] [--purge-config] [--purge-logs] [--purge-all] [--json]
@@ -2016,7 +2234,7 @@ COMMANDS
                                  doc_id?/tags? for citation.
                                  --raw: server response verbatim (curl parity).
 
-  skill install --target <qoder|qoderwork|codex|claude|openclaw|hermes> [--json]
+  skill install --target <qoder|qoderwork|codex|claude|opencode|openclaw|hermes> [--json]
   skill install --path <dir> [--json]
                                  Install skill files (contextdb-memory,
                                  contextdb-knowledge) to an agent's skill directory.
@@ -2029,7 +2247,7 @@ AGENT RESOLUTION (when --agent is omitted):
 ENV VARS (override selected ~/.ctxdb/ctxdb.json agent config):
   CTXDB_AGENT  CTXDB_API_KEY  CTXDB_BASE_URL  CTXDB_USER_ID
 
-CONFIG: ~/.ctxdb/ctxdb.json (agents.default / agents.qoder / agents.qoderwork / agents.codex / agents.claude)
+CONFIG: ~/.ctxdb/ctxdb.json (agents.default / agents.qoder / agents.qoderwork / agents.codex / agents.claude / agents.opencode)
 LOGS:   ~/.ctxdb/logs/ctxdb.log
 `;
 var ROUTES = {

package/dist/hooks/session-start.js

@@ -2,11 +2,11 @@
 import {
   fetchKbCatalogBlock,
   recallTurn
-} from "../chunk-RHWGDY6S.js";
+} from "../chunk-QPFFMW52.js";
 import "../chunk-6S5RJYBC.js";
 import {
   isCircuitOpen
-} from "../chunk-PZJZ5O62.js";
+} from "../chunk-PLWEIEFH.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
@@ -14,7 +14,7 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-TOXXGL5L.js";
+} from "../chunk-QHYJ7OXC.js";
 
 // src/hooks/session-start.ts
 import { pathToFileURL } from "url";