@aliyunrds/ctxdb 0.0.5 → 0.0.8-beta.1

package/dist/hooks/session-start.js

@@ -1,7 +1,12 @@
 #!/usr/bin/env node
 import {
+  fetchKbCatalogBlock,
   recallTurn
-} from "../chunk-7NOXAU2X.js";
+} from "../chunk-C62I23HL.js";
+import "../chunk-6S5RJYBC.js";
+import {
+  isCircuitOpen
+} from "../chunk-KEQMJ6IO.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
@@ -9,7 +14,10 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-QSSNPN3M.js";
+} from "../chunk-U3T5O6NX.js";
+
+// src/hooks/session-start.ts
+import { pathToFileURL } from "url";
 
 // src/lib/warmup-recall.ts
 import { execSync } from "child_process";
@@ -63,7 +71,42 @@ async function warmupRecall(cwd, cfg, client) {
 }
 
 // src/hooks/session-start.ts
-var HOOK_TIMEOUT_MS = 3e4;
+var HOOK_TIMEOUT_MS = 5e3;
+function timeout(ms) {
+  return new Promise((resolve) => setTimeout(() => resolve(null), ms));
+}
+async function composeSessionStart(cfg, agent, client, cwd, timeoutMs = HOOK_TIMEOUT_MS) {
+  const kbInjectHere = cfg.kbCatalogInjection === "session_start";
+  const warmupPromise = cfg.warmupRecall ? Promise.race([warmupRecall(cwd, cfg, client), timeout(timeoutMs).then(() => null)]) : Promise.resolve(null);
+  const kbPromise = kbInjectHere ? Promise.race([fetchKbCatalogBlock(client, agent).catch(() => ""), timeout(timeoutMs).then(() => "")]) : Promise.resolve("");
+  const [result, kbBlock] = await Promise.all([warmupPromise, kbPromise]);
+  const warmupTimedOut = cfg.warmupRecall && result === null;
+  const warmupCtx = result && result.ok ? result.additionalContext || "" : "";
+  if (!warmupCtx && result && !result.ok) {
+    debug("warmup", `no result: ${result.reason}`);
+  }
+  let ctx = warmupCtx;
+  if (kbBlock) ctx = ctx ? `${ctx}
+
+${kbBlock}` : kbBlock;
+  return {
+    ctx,
+    memoryCount: result?.ok ? result.memoryCount : 0,
+    kbChunkCount: result?.ok ? result.knowledgeChunkCount : 0,
+    kbCatalogLines: kbBlock ? kbBlock.split("\n").length : 0,
+    warmupTimedOut
+  };
+}
+function formatSessionStartStdout(agent, ctx) {
+  if (agent === "codex") return ctx + "\n";
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: ctx
+    }
+  };
+  return JSON.stringify(out) + "\n";
+}
 async function readStdinJson() {
   let raw = "";
   for await (const chunk of process.stdin) raw += chunk;
@@ -75,9 +118,6 @@ async function readStdinJson() {
     return {};
   }
 }
-function timeout(ms) {
-  return new Promise((resolve) => setTimeout(() => resolve(null), ms));
-}
 async function main() {
   try {
     const event = await readStdinJson();
@@ -93,8 +133,13 @@ async function main() {
     const cfg = load({ agent });
     setDebug(cfg.debug);
     debug("warmup", "start", { cwd, userId: cfg.userId });
-    if (!isComplete(cfg) || !cfg.warmupRecall) {
-      debug("warmup", "skip (config incomplete or warmupRecall=false)");
+    const kbInjectHere = cfg.kbCatalogInjection === "session_start";
+    if (!isComplete(cfg) || !cfg.warmupRecall && !kbInjectHere) {
+      debug("warmup", "skip (config incomplete or both warmup+kb off)");
+      return 0;
+    }
+    if (isCircuitOpen(agent, cfg.baseUrl)) {
+      debug("warmup", "skip (circuit open)");
       return 0;
     }
     const client = new HttpClient({
@@ -102,34 +147,21 @@ async function main() {
       apiKey: cfg.apiKey,
       timeoutMs: HOOK_TIMEOUT_MS
     });
-    const result = await Promise.race([
-      warmupRecall(cwd, cfg, client),
-      timeout(HOOK_TIMEOUT_MS).then(() => null)
-    ]);
-    if (!result) {
+    const composed = await composeSessionStart(cfg, agent, client, cwd);
+    if (composed.warmupTimedOut) {
       process.stderr.write("ctxdb warmup: timeout\n");
-      return 0;
     }
-    if (!result.ok || !result.additionalContext) {
-      debug("warmup", `no result: ${result.reason}`);
-      return 0;
-    }
-    debug("warmup", `ok, memories=${result.memoryCount} kb=${result.knowledgeChunkCount}`);
+    if (!composed.ctx) return 0;
+    const { memoryCount, kbChunkCount, kbCatalogLines, ctx } = composed;
+    debug(
+      "warmup",
+      `ok, memories=${memoryCount} kb=${kbChunkCount} kb_catalog=${kbCatalogLines}`
+    );
     process.stderr.write(
-      `ctxdb warmup: ok (${result.memoryCount} memories, ${result.knowledgeChunkCount} kb chunks)
+      `ctxdb warmup: ok (${memoryCount} memories, ${kbChunkCount} kb chunks, kb_catalog=${kbCatalogLines} lines)
 `
     );
-    if (agent === "codex") {
-      process.stdout.write(result.additionalContext + "\n");
-    } else {
-      const out = {
-        hookSpecificOutput: {
-          hookEventName: "SessionStart",
-          additionalContext: result.additionalContext
-        }
-      };
-      process.stdout.write(JSON.stringify(out) + "\n");
-    }
+    process.stdout.write(formatSessionStartStdout(agent, ctx));
     return 0;
   } catch (err) {
     process.stderr.write(`ctxdb warmup: unexpected error: ${err?.message ?? err}
@@ -137,4 +169,11 @@ async function main() {
     return 0;
   }
 }
-main().then((code) => process.exit(code));
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().then((code) => process.exit(code));
+}
+export {
+  HOOK_TIMEOUT_MS,
+  composeSessionStart,
+  formatSessionStartStdout
+};

package/dist/hooks/stop.js

@@ -1,4 +1,10 @@
 #!/usr/bin/env node
+import {
+  isCircuitOpen,
+  isConnectionError,
+  resetCircuit,
+  tripCircuit
+} from "../chunk-KEQMJ6IO.js";
 import {
   CtxdbError,
   HttpClient,
@@ -6,7 +12,7 @@ import {
   debug,
   load,
   setDebug
-} from "../chunk-QSSNPN3M.js";
+} from "../chunk-U3T5O6NX.js";
 
 // src/lib/capture-orchestrator.ts
 import {
@@ -15,6 +21,26 @@ import {
   selectTurnMessages
 } from "@aliyunrds/ctxdb-shared";
 
+// src/lib/git-context.ts
+import { execSync } from "child_process";
+function getGitContext() {
+  try {
+    const raw = execSync("git rev-parse --show-toplevel --abbrev-ref HEAD", {
+      encoding: "utf-8",
+      timeout: 3e3,
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+    const lines = raw.split("\n");
+    if (lines.length < 2) return null;
+    const project = lines[0].split(/[/\\]/).pop();
+    if (!project) return null;
+    const branch = lines[1];
+    return { project, branch };
+  } catch {
+    return null;
+  }
+}
+
 // src/lib/transcript.ts
 import { existsSync, readFileSync } from "fs";
 var ANTHROPIC_MESSAGE_TYPES = /* @__PURE__ */ new Set(["user", "assistant"]);
@@ -157,21 +183,10 @@ function toParsedMessages(rows) {
         }
         continue;
       }
-      if (ptype === "reasoning") {
-        const summary = p.summary;
-        if (!Array.isArray(summary)) continue;
-        for (const block of summary) {
-          if (!block || typeof block !== "object") continue;
-          const btype = block.type;
-          if (btype === "summary_text") {
-            const v = block.text;
-            if (typeof v === "string") push("assistant", v);
-          }
-        }
-        continue;
-      }
+      if (ptype === "reasoning") continue;
       continue;
     }
+    if (row.isMeta === true) continue;
     const msg = row.message;
     if (!msg || typeof msg !== "object") continue;
     const role = msg.role;
@@ -189,9 +204,6 @@ function toParsedMessages(rows) {
         if (btype === "text") {
           const v = block.text;
           if (typeof v === "string") text = v;
-        } else if (btype === "thinking") {
-          const v = block.thinking;
-          if (typeof v === "string") text = v;
         }
         if (text) push(role, text);
       }
@@ -199,15 +211,66 @@ function toParsedMessages(rows) {
   }
   return parsed;
 }
+var COMMAND_MESSAGE_RE = /<command-message>([\s\S]*?)<\/command-message>/;
+var COMMAND_ARGS_RE = /<command-args>([\s\S]*?)<\/command-args>/;
+function extractSkillSignals(rows) {
+  const signals = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (s) => {
+    const key = `${s.trigger}:${s.skill}`;
+    if (seen.has(key)) return;
+    seen.add(key);
+    signals.push(s);
+  };
+  for (const row of rows) {
+    if (!row || typeof row !== "object") continue;
+    if (row.type === "user") {
+      const msg = row.message;
+      if (!msg || typeof msg !== "object") continue;
+      const content = msg.content;
+      if (typeof content === "string") {
+        const m = COMMAND_MESSAGE_RE.exec(content);
+        if (m) {
+          const argsMatch = COMMAND_ARGS_RE.exec(content);
+          add({
+            skill: m[1].trim(),
+            args: argsMatch?.[1]?.trim() || void 0,
+            trigger: "command"
+          });
+        }
+      }
+    }
+    if (row.type === "assistant") {
+      const msg = row.message;
+      if (!msg || typeof msg !== "object") continue;
+      const content = msg.content;
+      if (!Array.isArray(content)) continue;
+      for (const block of content) {
+        if (block && typeof block === "object" && block.type === "tool_use" && block.name === "Skill") {
+          const input = block.input;
+          if (input && typeof input === "object") {
+            const skill = typeof input.skill === "string" ? input.skill : "";
+            const args = typeof input.args === "string" ? input.args : void 0;
+            if (skill) add({ skill, args, trigger: "agent" });
+          }
+        }
+      }
+    }
+  }
+  return signals;
+}
 
 // src/lib/capture-orchestrator.ts
-async function captureTurn(transcriptPath, cfg, client) {
+async function captureTurn(transcriptPath, cfg, client, agent = "default") {
   if (!cfg.apiKey || !cfg.baseUrl) {
     return { captured: false, reason: "config_incomplete", messageCount: 0 };
   }
   if (!cfg.autoCapture) {
     return { captured: false, reason: "auto_capture_disabled", messageCount: 0 };
   }
+  if (isCircuitOpen(agent, cfg.baseUrl)) {
+    return { captured: false, reason: `circuit_open: ${cfg.baseUrl}`, messageCount: 0 };
+  }
   const rows = readTranscript(transcriptPath);
   if (rows.length === 0) {
     return { captured: false, reason: "empty_transcript", messageCount: 0 };
@@ -240,16 +303,26 @@ async function captureTurn(transcriptPath, cfg, client) {
   if (filtered.length === 0) {
     return { captured: false, reason: "all_filtered", messageCount: 0 };
   }
+  const git = getGitContext();
+  const skills = extractSkillSignals(rows);
+  const bg = {};
+  if (git) bg.git = git;
+  if (skills.length > 0) bg.skills = skills.map(
+    ({ skill, trigger, args }) => args ? { skill, trigger, args } : { skill, trigger }
+  );
+  const messages = bg.git || bg.skills ? [{ role: "background", content: JSON.stringify(bg) }, ...filtered] : filtered;
   const payload = {
-    messages: filtered,
+    messages,
     user_id: cfg.userId,
     async_mode: true
   };
   let resp;
   try {
     resp = await client.postJson("/v3/memories/add/", payload);
+    resetCircuit(agent);
   } catch (err) {
     const msg = err instanceof CtxdbError ? err.message : String(err);
+    if (isConnectionError(err)) tripCircuit(agent, cfg.baseUrl, msg);
     return {
       captured: false,
       reason: `http_error: ${msg}`,
@@ -295,8 +368,8 @@ async function main() {
       debug("capture", "skip (config incomplete)");
       return 0;
     }
-    const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
-    const result = await captureTurn(transcriptPath, cfg, client);
+    const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey, timeoutMs: 5e3 });
+    const result = await captureTurn(transcriptPath, cfg, client, agent);
     if (result.captured) {
       debug("capture", `ok (${result.messageCount} msgs)`, result);
       process.stderr.write(

package/dist/hooks/user-prompt-submit.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 import {
-  listKnowledgeBases
-} from "../chunk-HAUTENYD.js";
-import {
+  fetchKbCatalogBlock,
   recallTurn
-} from "../chunk-7NOXAU2X.js";
+} from "../chunk-C62I23HL.js";
+import "../chunk-6S5RJYBC.js";
+import {
+  isCircuitOpen
+} from "../chunk-KEQMJ6IO.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
@@ -12,23 +14,31 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-QSSNPN3M.js";
-
-// src/lib/kb-catalog.ts
-async function fetchKbCatalogBlock(client, agent) {
-  const kbs = await listKnowledgeBases(client);
-  const active = kbs.filter((kb) => kb.status === "active");
-  if (active.length === 0) return "";
-  const lines = active.map((kb) => `\xB7 ${kb.name}`);
-  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:`,
-    ...lines,
-    "</available-knowledge-bases>"
-  ].join("\n");
-}
+} from "../chunk-U3T5O6NX.js";
 
 // src/hooks/user-prompt-submit.ts
+import { pathToFileURL } from "url";
+async function composeUserPromptSubmit(cfg, agent, client, prompt) {
+  const [recall, kbBlock] = await Promise.all([
+    recallTurn(prompt, cfg, client, agent),
+    cfg.kbCatalogInjection === "user_prompt_submit" ? fetchKbCatalogBlock(client, agent).catch(() => "") : Promise.resolve("")
+  ]);
+  let ctx = recall.additionalContext || "";
+  if (kbBlock) ctx = ctx ? `${ctx}
+
+${kbBlock}` : kbBlock;
+  return { ctx, recall, kbBlock };
+}
+function formatUserPromptSubmitStdout(agent, ctx) {
+  if (agent === "codex") return ctx + "\n";
+  const out = {
+    hookSpecificOutput: {
+      hookEventName: "UserPromptSubmit",
+      additionalContext: ctx
+    }
+  };
+  return JSON.stringify(out) + "\n";
+}
 async function readStdinJson() {
   let raw = "";
   for await (const chunk of process.stdin) raw += chunk;
@@ -59,37 +69,26 @@ async function main() {
       debug("recall", "skip (config incomplete or autoRecall=false)");
       return 0;
     }
-    const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey });
-    const [result, kbBlock] = await Promise.all([
-      recallTurn(prompt, cfg, client),
-      fetchKbCatalogBlock(client, agent).catch(() => "")
-    ]);
-    if (!result.ok && !result.additionalContext && !kbBlock) {
-      const reason = result.reason ?? "no_context";
-      debug("recall", `no result: ${reason}`, result);
-      if (result.reason && result.reason.startsWith("http_error:")) {
-        process.stderr.write(`ctxdb recall: ${result.reason}
+    if (isCircuitOpen(agent, cfg.baseUrl)) {
+      debug("recall", "skip (circuit open)");
+      process.stderr.write(`ctxdb recall: skip (circuit_open: ${cfg.baseUrl})
+`);
+      return 0;
+    }
+    const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey, timeoutMs: 5e3 });
+    const { ctx, recall, kbBlock } = await composeUserPromptSubmit(cfg, agent, client, prompt);
+    if (!recall.ok && !recall.additionalContext && !kbBlock) {
+      const reason = recall.reason ?? "no_context";
+      debug("recall", `no result: ${reason}`, recall);
+      if (recall.reason && recall.reason.startsWith("http_error:")) {
+        process.stderr.write(`ctxdb recall: ${recall.reason}
 `);
       }
       return 0;
     }
-    let ctx = result.additionalContext || "";
-    if (kbBlock) ctx = ctx ? `${ctx}
-
-${kbBlock}` : kbBlock;
     if (!ctx) return 0;
     debug("recall", `ok, additionalContext length=${ctx.length}`);
-    if (agent === "codex") {
-      process.stdout.write(ctx + "\n");
-    } else {
-      const out = {
-        hookSpecificOutput: {
-          hookEventName: "UserPromptSubmit",
-          additionalContext: ctx
-        }
-      };
-      process.stdout.write(JSON.stringify(out) + "\n");
-    }
+    process.stdout.write(formatUserPromptSubmitStdout(agent, ctx));
     return 0;
   } catch (err) {
     process.stderr.write(`ctxdb recall: unexpected error: ${err?.message ?? err}
@@ -97,4 +96,10 @@ ${kbBlock}` : kbBlock;
     return 0;
   }
 }
-main().then((code) => process.exit(code));
+if (import.meta.url === pathToFileURL(process.argv[1] ?? "").href) {
+  main().then((code) => process.exit(code));
+}
+export {
+  composeUserPromptSubmit,
+  formatUserPromptSubmitStdout
+};

package/dist/setup/skills/contextdb-knowledge/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: contextdb-knowledge
+description: contextdb 知识库高频操作（查询 / 浏览 KB / 上传文档）和命令速查。当用户提到"查知识库 / 查 KB / 搜知识库 / 查 KB chunks / 上传到 KB / 灌进知识库 / 列出知识库 / 列出 KB / 看文档 / 建知识库 / 建 KB"等场景时使用。配套 contextdb-memory 处理长期记忆。
+---
+
+# contextdb Knowledge Base 操作
+
+## 1. 什么时候用这个 skill
+
+用户在做"查/灌/列知识库"的任何动作时进这个 skill。触发关键词：**查知识库 / 查 KB / 搜知识库 / 查 KB chunks / 上传到 KB / 灌进知识库 / 列出知识库 / 列出 KB / 看文档 / 建知识库**。
+
+- 用户想**找已有 KB 里的内容** → §2 recipe 1
+- 用户**不知道有哪些 KB** → §2 recipe 2
+- 用户想**了解某个 KB 收了哪些文档** → §2 recipe 3
+- 用户要**写入/上传内容** → §2 recipe 4/5
+
+配套 skill：**contextdb-memory**（长期记忆操作）。两者用同一份 `~/.ctxdb/ctxdb.json` 配置和同一个 `--agent` 路由。
+
+## 2. 高频 recipes
+
+> 命令里 `--agent=qoder` 是必填参数。如果用户跑别的 agent（codex / claude），把 `qoder` 替换成对应名字。
+
+### Recipe 1：在已知 KB 中查内容（最常见）
+
+**场景**：用户问"X KB 里关于 Y 的内容"、"在知识库 Z 查一下 W"。
+
+```sh
+ctxdb kb search "<query>" --kb=<kb-name> --top-k=6 --agent=qoder
+```
+
+返回 `chunks` 数组，按 `score` 倒序判断相关性；默认 threshold 0.4，空结果时见 §5 注意事项 4。
+
+**何时不适用**：用户没指定 KB → 先走 recipe 2 列出来确认。
+
+### Recipe 2：列出所有 KB（不知道有哪些）
+
+**场景**：用户问"有哪些知识库"、"列一下 KB"，或本身在写 recipe 1 之前需要确认 KB 名。
+
+```sh
+ctxdb kb list --agent=qoder
+```
+
+返回 `knowledge_bases` 数组，每项含 `name` / `id` / `document_count`。跨多 KB 查 chunk 时把 `name` 拼起来：`--kb=a,b,c`。
+
+**何时不适用**：hook 已注入 `<available-knowledge-bases>` 块时，直接读那个块更省一次调用（见 §4）。
+
+### Recipe 3：列出某 KB 的文档清单
+
+**场景**：用户问"X KB 收了哪些文档"、"X KB 里有几篇"。
+
+```sh
+ctxdb kb documents-list <kb-name> --agent=qoder
+```
+
+返回 `documents` 数组，每项含 `name` / `id` / `size`。
+
+**何时不适用**：用户要的是文档**正文**而不是清单 → 走 recipe 1 用 `kb search`（见 §5 注意事项 1）。
+
+### Recipe 4：灌一段文字进 KB
+
+**场景**：用户说"把这段记进 X KB"、"上传这段文字到知识库 Y"。
+
+```sh
+ctxdb kb upload-text <kb-name> <doc-name> --text="<body>" --agent=qoder
+```
+
+副作用操作。**用户没明示 KB 名前先 recipe 2 列出来确认**（见 §5 注意事项 3）。KB 不存在会直接报错，不自动创建。
+
+**何时不适用**：内容是本地文件 → recipe 5。
+
+### Recipe 5：上传本地文件到 KB
+
+**场景**：用户说"把 X.pdf 上传到 Y KB"、"灌这个文件进知识库 Z"。
+
+```sh
+ctxdb kb upload-file <kb-name> <local-path> --agent=qoder
+```
+
+支持格式：PDF / DOCX / MD / TXT。默认等待 chunking 完成；想立即返回加 `--no-wait`（见 §6）。
+
+**何时不适用**：要上传的内容是字符串而非本地文件 → recipe 4。
+
+## 3. 命令速查
+
+`--agent=<name>` 必填；详细解析链见 §6。其他 advanced flag 见 §6。
+
+| 子命令 | minimal signature |
+|---|---|
+| `kb search` | `ctxdb kb search "<query>" --agent=<name>` |
+| `kb list` | `ctxdb kb list --agent=<name>` |
+| `kb documents-list` | `ctxdb kb documents-list <kb-name> --agent=<name>` |
+| `kb document-get` | `ctxdb kb document-get <kb-name> <doc-id> --agent=<name>` |
+| `kb create` | `ctxdb kb create <kb-name> --agent=<name>` |
+| `kb upload-text` | `ctxdb kb upload-text <kb-name> <doc-name> --text="<body>" --agent=<name>` |
+| `kb upload-file` | `ctxdb kb upload-file <kb-name> <local-path> --agent=<name>` |
+
+所有命令 JSON 写 stdout、错误写 stderr 非零退出码。
+
+## 4. Hooks 感知
+
+**`<available-knowledge-bases>` 块**：UPS / SessionStart hook 注入到 system context；存在时直接列出 workspace 内所有 KB 名（省一次 `kb list` 调用）。可直接喂给 `--kb=<name>`。
+
+**`<recalled-memories>` 块**：是 contextdb-memory 的产物，但 `kb search --knowledge` 会复用同样的 retrieval 路径。两块独立。
+
+**B-3c 守卫**：含 `kb upload-text` / `kb upload-file` 的对话轮次，其内容**不会**被 autoCapture 写入记忆（防文档原文混进记忆桶）。
+
+**纯 CLI 模式**：对话里没有上面任何块 → 说明当前不在 hook 环境（agent 是裸 CLI 调用），所有信息只能主动调命令拿。
+
+## 5. 注意事项
+
+### 注意事项 1：`kb document-get` 只返 metadata，**不返正文**
+
+- **现象**：想读文档内容，调 `kb document-get` 拿到的只有 `{id, name, size, upload_time, tags}`，没 `content` 字段
+- **根因**：服务端当前只暴露元信息端点；获取正文需走 chunk 检索
+- **正确做法**：用 `kb search "<关键词>" --kb=<name>` 拿 chunks，或 `kb documents-list <kb-name>` 后浏览返回的内嵌 chunk（如有）
+
+### 注意事项 2：解析 JSON 用 `jq`，**不要 inline `python3 -c`**
+
+- **现象**：在 shell 里写 `ctxdb kb list | python3 -c "import json,sys; ..."` 经常因为单/双引号嵌套 escape 失败
+- **根因**：shell + python -c 的引号是两层独立 escape，组合时极容易漏
+- **正确做法**：`ctxdb kb list --agent=qoder | jq '.knowledge_bases[].name'`；jq 表达式在单引号里不需要 escape
+
+### 注意事项 3：`upload-*` / `create` 是副作用，没明示 KB 名前必须先确认
+
+- **现象**：用户只说"把这段记进知识库"没指定 KB，agent 直接用了某个猜的 KB 名 → 写到错的桶
+- **根因**：写命令不会跟 agent 二次确认；KB 不存在时报错，但**KB 名拼错却恰好命中另一个真实 KB**时会静默写错
+- **正确做法**：用户没明示 → 必须先 `kb list` 拿候选清单，跟用户确认目标后才执行
+
+### 注意事项 4：`kb search` 空结果时降阈值再试一次
+
+- **现象**：query 明明跟内容相关，但 `chunks: []`
+- **根因**：默认 `--threshold=0.4`，短 query / 关键词偏冷时打不到
+- **正确做法**：降到 `--threshold=0.2` 或 `--threshold=0.3` 重试一次再判定真的没命中；仍空才放弃
+
+### 注意事项 5：`upload-*` 不会自动建 KB
+
+- **现象**：`kb upload-text foo bar --text=...` 报错 "kb 'foo' not found"
+- **根因**：上传命令只写已有 KB，**不会**为了你 implicit 建一个
+- **正确做法**：先 `ctxdb kb create foo --agent=qoder`，再 upload
+
+## 6. 高级参数
+
+### `kb search` 全部 flag
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--kb=<name1,name2>` | 限定搜索的 KB，逗号分隔 | 搜所有 |
+| `--top-k=N` | chunk 数上限 | 6 |
+| `--threshold=F` | 相关度阈值 | 0.4 |
+| `--verbose` | 每个 chunk 加 `doc_name` / `kb_id` / `doc_id` / `tags` | false |
+| `--raw` | 服务端原始响应（13+ 字段，含 tokenizer 细节） | false |
+
+### `kb upload-file` / `kb upload-text` 全部 flag
+
+| 参数 | 说明 |
+|------|------|
+| `--doc-name` | （`upload-file`）服务端文档名，默认取本地文件名 |
+| `--file-path` | 服务端逻辑路径（归档/分类用） |
+| `--no-wait` | 不等 chunking 完成立即返回 |
+
+### `kb create` 全部 flag
+
+| 参数 | 说明 |
+|------|------|
+| `--description` | 知识库描述 |
+
+### `kb list` / `kb documents-list` / `kb document-get`
+
+无额外 flag（除通用参数）。
+
+### 通用参数
+
+| 参数 | 说明 |
+|------|------|
+| `--agent=<name>` | **必填**。指定操作哪个 agent 的配置桶（`qoder` / `codex` / `claude` / `default`） |
+
+`--agent` 解析顺序：
+1. 命令行显式 `--agent=<name>` → 用它
+2. 缺省 → 读 `CTXDB_AGENT` 环境变量
+3. env 也没有 → 落到 `"default"` 桶
+4. 若 `"default"` 桶未通过 `ctxdb setup --api-key=... --base-url=...` 配置过 → exit 2 "config incomplete for agent default"
+
+## 7. 配置
+
+- 配置文件：`~/.ctxdb/ctxdb.json`，分 `agents.<name>` 段（`qoder` / `codex` / `claude` / `default`），互不复用
+- 配置命令：`ctxdb setup --agent <name> --api-key=<key> --base-url=<url> [--user-id=<id>]`
+  - 带 `--agent` 时还会装 hooks + skill；不带 `--agent` 时只写 `agents.default` 段（仅 CLI 用）
+- 连接检查：`ctxdb ping --agent=<name>`
+- 状态查看：`ctxdb status --agent=<name>`