@aliyunrds/ctxdb 0.0.7 → 0.0.8-beta.2

package/dist/hooks/stop.js

@@ -4,15 +4,16 @@ import {
   isConnectionError,
   resetCircuit,
   tripCircuit
-} from "../chunk-Q2EEP4CE.js";
+} from "../chunk-52IAVJRK.js";
 import {
   CtxdbError,
   HttpClient,
   agentFromArgvWithFallback,
   debug,
+  isDebug,
   load,
   setDebug
-} from "../chunk-S45GOYUU.js";
+} from "../chunk-BWPFGTF7.js";
 
 // src/lib/capture-orchestrator.ts
 import {
@@ -32,7 +33,7 @@ function getGitContext() {
     }).trim();
     const lines = raw.split("\n");
     if (lines.length < 2) return null;
-    const project = lines[0].split("/").pop();
+    const project = lines[0].split(/[/\\]/).pop();
     if (!project) return null;
     const branch = lines[1];
     return { project, branch };
@@ -122,6 +123,48 @@ function toKbDetectionMessages(rows) {
   }
   return out;
 }
+function selectTurnRows(rows) {
+  let turnStart = -1;
+  for (let ri = rows.length - 1; ri >= 0; ri--) {
+    if (hasExtractableUserText(rows[ri])) {
+      turnStart = ri;
+      while (turnStart > 0 && hasExtractableUserText(rows[turnStart - 1])) {
+        turnStart--;
+      }
+      break;
+    }
+  }
+  return turnStart >= 0 ? rows.slice(turnStart) : [];
+}
+function hasExtractableUserText(row) {
+  if (!row || typeof row !== "object") return false;
+  if (row.type === CODEX_RESPONSE_ITEM) {
+    const p = row.payload;
+    if (!p || typeof p !== "object") return false;
+    if (p.type !== "message" || p.role !== "user") return false;
+    const content2 = p.content;
+    if (!Array.isArray(content2)) return false;
+    return content2.some((block) => {
+      if (!block || typeof block !== "object") return false;
+      if (block.type !== "input_text") return false;
+      const text = block.text;
+      return typeof text === "string" && text.trim() && !isCodexScaffoldingText(text);
+    });
+  }
+  if (row.isMeta === true) return false;
+  const msg = row.message;
+  if (!msg || typeof msg !== "object") return false;
+  if (msg.role !== "user") return false;
+  const content = msg.content;
+  if (typeof content === "string") return Boolean(content.trim());
+  if (!Array.isArray(content)) return false;
+  return content.some((block) => {
+    if (!block || typeof block !== "object") return false;
+    if (block.type !== "text") return false;
+    const text = block.text;
+    return typeof text === "string" && Boolean(text.trim());
+  });
+}
 function parseArgs(raw) {
   if (typeof raw !== "string") return {};
   try {
@@ -275,15 +318,10 @@ async function captureTurn(transcriptPath, cfg, client, agent = "default") {
   if (rows.length === 0) {
     return { captured: false, reason: "empty_transcript", messageCount: 0 };
   }
-  const kb = isKnowledgeBaseUploadTurn(toKbDetectionMessages(rows));
-  if (kb.detected) {
-    return {
-      captured: false,
-      reason: `b3c_skip: ${kb.reason ?? "(no reason)"}`,
-      messageCount: 0
-    };
-  }
+  const dbg = isDebug();
+  if (dbg) debug("capture", "transcript rows", summarizeTranscriptRows(rows));
   const parsed = toParsedMessages(rows);
+  if (dbg) debug("capture", "parsed messages", summarizeTextMessages(parsed));
   if (parsed.length === 0) {
     return {
       captured: false,
@@ -292,31 +330,39 @@ async function captureTurn(transcriptPath, cfg, client, agent = "default") {
     };
   }
   const turn = selectTurnMessages(parsed);
+  if (dbg) debug("capture", "selected turn", summarizeTextMessages(turn));
   if (turn.length === 0) {
     return { captured: false, reason: "empty_turn_slice", messageCount: 0 };
   }
   if (!turn.some((m) => m.role === "user")) {
     return { captured: false, reason: "no_user_in_turn", messageCount: 0 };
   }
+  const turnRows = selectTurnRows(rows);
+  if (dbg) debug("capture", "current turn rows", summarizeTranscriptRows(turnRows));
+  const kb = isKnowledgeBaseUploadTurn(toKbDetectionMessages(turnRows));
+  if (kb.detected) {
+    return {
+      captured: false,
+      reason: `b3c_skip: ${kb.reason ?? "(no reason)"}`,
+      messageCount: 0
+    };
+  }
   const rawMessages = turn.map((m) => ({ role: m.role, content: m.content }));
   const filtered = filterMessagesForExtraction(rawMessages);
+  if (dbg) debug("capture", "filtered messages", summarizeTextMessages(filtered));
   if (filtered.length === 0) {
     return { captured: false, reason: "all_filtered", messageCount: 0 };
   }
   const git = getGitContext();
   const skills = extractSkillSignals(rows);
-  const bgParts = [];
-  if (git) {
-    bgParts.push(`This conversation took place in project "${git.project}", branch "${git.branch}".`);
-  }
-  if (skills.length > 0) {
-    const descs = skills.map((s) => {
-      const label = s.trigger === "command" ? "user-invoked" : "agent-invoked";
-      return s.args ? `${s.skill} (${label}, args: "${s.args}")` : `${s.skill} (${label})`;
-    });
-    bgParts.push(`Skills used: ${descs.join(", ")}.`);
-  }
-  const messages = bgParts.length > 0 ? [{ role: "background", content: bgParts.join("\n") }, ...filtered] : filtered;
+  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 hasBackground = Boolean(bg.git || bg.skills);
+  if (hasBackground) debug("capture", "background", bg);
+  const messages = hasBackground ? [{ role: "background", content: JSON.stringify(bg) }, ...filtered] : filtered;
   const payload = {
     messages,
     user_id: cfg.userId,
@@ -342,6 +388,104 @@ async function captureTurn(transcriptPath, cfg, client, agent = "default") {
     messageCount: filtered.length
   };
 }
+var DEBUG_TAIL_LIMIT = 25;
+var DEBUG_TEXT_LIMIT = 240;
+var DEBUG_BLOCK_LIMIT = 8;
+function summarizeTextMessages(messages) {
+  return {
+    count: messages.length,
+    roles: countRoles(messages),
+    tail: tailWithIndex(messages).map(({ index, item }) => ({
+      index,
+      parsedIndex: typeof item.index === "number" ? item.index : void 0,
+      role: item.role ?? "(unknown)",
+      content: summarizeText(item.content)
+    }))
+  };
+}
+function summarizeTranscriptRows(rows) {
+  return {
+    count: rows.length,
+    tail: tailWithIndex(rows).map(({ index, item: row }) => ({
+      index,
+      type: row.type,
+      role: rowRole(row),
+      isMeta: row.isMeta === true || void 0,
+      payloadType: row.payload?.type,
+      content: summarizeRowContent(row)
+    }))
+  };
+}
+function tailWithIndex(items) {
+  const start = Math.max(0, items.length - DEBUG_TAIL_LIMIT);
+  return items.slice(start).map((item, offset) => ({ index: start + offset, item }));
+}
+function countRoles(messages) {
+  const counts = {};
+  for (const msg of messages) {
+    const role = msg.role ?? "(unknown)";
+    counts[role] = (counts[role] ?? 0) + 1;
+  }
+  return counts;
+}
+function rowRole(row) {
+  const msgRole = row.message && typeof row.message === "object" ? row.message.role : void 0;
+  if (typeof msgRole === "string") return msgRole;
+  const payloadRole = row.payload && typeof row.payload === "object" ? row.payload.role : void 0;
+  return typeof payloadRole === "string" ? payloadRole : void 0;
+}
+function summarizeRowContent(row) {
+  if (row.type === "response_item") {
+    const p = row.payload;
+    if (!p || typeof p !== "object") return { kind: "missing" };
+    if (p.type === "function_call") {
+      return {
+        kind: "function_call",
+        name: p.name,
+        arguments: summarizeText(p.arguments)
+      };
+    }
+    return summarizeContent(p.content);
+  }
+  return summarizeContent(row.message?.content);
+}
+function summarizeContent(content) {
+  if (typeof content === "string") return summarizeText(content);
+  if (!Array.isArray(content)) {
+    return { kind: content === void 0 ? "missing" : typeof content };
+  }
+  return {
+    kind: "blocks",
+    count: content.length,
+    blocks: content.slice(0, DEBUG_BLOCK_LIMIT).map((block) => summarizeBlock(block)),
+    truncated: content.length > DEBUG_BLOCK_LIMIT || void 0
+  };
+}
+function summarizeBlock(block) {
+  if (!block || typeof block !== "object") return { kind: typeof block };
+  const b = block;
+  const summary = { type: b.type };
+  if (typeof b.name === "string") summary.name = b.name;
+  if (typeof b.text === "string") summary.text = summarizeText(b.text);
+  if (typeof b.thinking === "string") summary.thinking = summarizeText(b.thinking);
+  if (typeof b.content === "string") summary.content = summarizeText(b.content);
+  const input = b.input;
+  if (input && typeof input === "object" && !Array.isArray(input)) {
+    const i = input;
+    summary.inputKeys = Object.keys(i).sort();
+    if (typeof i.command === "string") summary.command = summarizeText(i.command);
+  }
+  return summary;
+}
+function summarizeText(text) {
+  if (typeof text !== "string") return { kind: text === void 0 ? "missing" : typeof text };
+  const normalized = text.replace(/\s+/g, " ").trim();
+  return {
+    kind: "text",
+    length: text.length,
+    snippet: normalized.length > DEBUG_TEXT_LIMIT ? `${normalized.slice(0, DEBUG_TEXT_LIMIT)}...` : normalized
+  };
+}
 
 // src/hooks/stop.ts
 async function readStdinJson() {

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

@@ -1,13 +1,12 @@
 #!/usr/bin/env node
 import {
-  listKnowledgeBases
-} from "../chunk-6S5RJYBC.js";
-import {
+  fetchKbCatalogBlock,
   recallTurn
-} from "../chunk-LIC44DR6.js";
+} from "../chunk-73OY44GY.js";
+import "../chunk-6S5RJYBC.js";
 import {
   isCircuitOpen
-} from "../chunk-Q2EEP4CE.js";
+} from "../chunk-52IAVJRK.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
@@ -15,23 +14,31 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-S45GOYUU.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-BWPFGTF7.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;
@@ -69,36 +76,19 @@ async function main() {
       return 0;
     }
     const client = new HttpClient({ baseUrl: cfg.baseUrl, apiKey: cfg.apiKey, timeoutMs: 5e3 });
-    const [result, kbBlock] = await Promise.all([
-      recallTurn(prompt, cfg, client, agent),
-      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}
+    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}
@@ -106,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

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