@aliyunrds/ctxdb 0.0.4 → 0.0.7

package/dist/hooks/session-start.js

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 import {
   recallTurn
-} from "../chunk-7NOXAU2X.js";
+} from "../chunk-LIC44DR6.js";
+import {
+  isCircuitOpen
+} from "../chunk-Q2EEP4CE.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
@@ -9,7 +12,7 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-QSSNPN3M.js";
+} from "../chunk-S45GOYUU.js";
 
 // src/lib/warmup-recall.ts
 import { execSync } from "child_process";
@@ -63,7 +66,7 @@ async function warmupRecall(cwd, cfg, client) {
 }
 
 // src/hooks/session-start.ts
-var HOOK_TIMEOUT_MS = 3e4;
+var HOOK_TIMEOUT_MS = 5e3;
 async function readStdinJson() {
   let raw = "";
   for await (const chunk of process.stdin) raw += chunk;
@@ -97,6 +100,10 @@ async function main() {
       debug("warmup", "skip (config incomplete or warmupRecall=false)");
       return 0;
     }
+    if (isCircuitOpen(agent, cfg.baseUrl)) {
+      debug("warmup", "skip (circuit open)");
+      return 0;
+    }
     const client = new HttpClient({
       baseUrl: cfg.baseUrl,
       apiKey: cfg.apiKey,

package/dist/hooks/stop.js

@@ -1,4 +1,10 @@
 #!/usr/bin/env node
+import {
+  isCircuitOpen,
+  isConnectionError,
+  resetCircuit,
+  tripCircuit
+} from "../chunk-Q2EEP4CE.js";
 import {
   CtxdbError,
   HttpClient,
@@ -6,7 +12,7 @@ import {
   debug,
   load,
   setDebug
-} from "../chunk-QSSNPN3M.js";
+} from "../chunk-S45GOYUU.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,32 @@ 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 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 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 +374,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,7 +1,13 @@
 #!/usr/bin/env node
+import {
+  listKnowledgeBases
+} from "../chunk-6S5RJYBC.js";
 import {
   recallTurn
-} from "../chunk-7NOXAU2X.js";
+} from "../chunk-LIC44DR6.js";
+import {
+  isCircuitOpen
+} from "../chunk-Q2EEP4CE.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
@@ -9,7 +15,21 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-QSSNPN3M.js";
+} 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");
+}
 
 // src/hooks/user-prompt-submit.ts
 async function readStdinJson() {
@@ -42,9 +62,18 @@ 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 = await recallTurn(prompt, cfg, client);
-    if (!result.ok || !result.additionalContext) {
+    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 [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:")) {
@@ -53,14 +82,19 @@ async function main() {
       }
       return 0;
     }
-    debug("recall", `ok, additionalContext length=${result.additionalContext.length}`);
+    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(result.additionalContext + "\n");
+      process.stdout.write(ctx + "\n");
     } else {
       const out = {
         hookSpecificOutput: {
           hookEventName: "UserPromptSubmit",
-          additionalContext: result.additionalContext
+          additionalContext: ctx
         }
       };
       process.stdout.write(JSON.stringify(out) + "\n");

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

@@ -0,0 +1,161 @@
+---
+name: contextdb-knowledge
+description: RDS contextdb 知识库操作全量参考。覆盖 kb create / search / upload-text / upload-file / list / documents-list / document-get 的完整参数和 JSON 输出结构。当用户提到"查知识库"、"查 KB"、"上传到 KB"、"灌进知识库"、"列出知识库"、"看文档"、"建知识库"等场景时使用。
+---
+
+# contextdb Knowledge Base 操作参考
+
+## 配置
+
+- 配置文件：`~/.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`
+
+## kb search
+
+搜索知识库。
+
+```sh
+ctxdb kb search "<query>" [--kb=<name1,name2>] [--top-k=N] [--threshold=F] [--verbose] [--raw] [--agent=<name>]
+```
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `<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
+    }
+  ]
+}
+```
+
+`--verbose` 模式增加字段：
+
+```json
+{
+  "chunks": [
+    {
+      "content": "chunk 文本内容",
+      "score": 0.82,
+      "doc_name": "zircodb-overview",
+      "kb_id": "kb-uuid",
+      "doc_id": "doc-uuid",
+      "tags": ["architecture"]
+    }
+  ]
+}
+```
+
+## kb create
+
+创建知识库。
+
+```sh
+ctxdb kb create <kb-name> [--description=<desc>] [--agent=<name>]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `<kb-name>` | 知识库名称（必填） |
+| `--description` | 知识库描述 |
+
+上传前须先创建 KB。`upload-text` / `upload-file` 不会自动创建 KB，KB 不存在时会报错。
+
+## kb upload-file
+
+上传本地文件到知识库。
+
+```sh
+ctxdb kb upload-file <kb-name> <local-path> [--doc-name=<name>] [--file-path=<server-logical-path>] [--no-wait] [--agent=<name>]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `<kb-name>` | 目标知识库名称（须已存在） |
+| `<local-path>` | 本机文件路径 |
+| `--doc-name` | 服务端文档名（默认取文件名） |
+| `--file-path` | 服务端逻辑路径（归档/分类用） |
+| `--no-wait` | 不等待 chunking 完成，立即返回 |
+
+支持格式：PDF、DOCX、MD、TXT。
+
+## kb upload-text
+
+上传文本内容到知识库。
+
+```sh
+ctxdb kb upload-text <kb-name> <doc-name> --text="<body>" [--file-path=<server-logical-path>] [--no-wait] [--agent=<name>]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `<kb-name>` | 目标知识库名称（须已存在） |
+| `<doc-name>` | 文档名称 |
+| `--text` | 文本内容（必填） |
+| `--file-path` | 服务端逻辑路径 |
+| `--no-wait` | 不等待 chunking 完成 |
+
+## kb list
+
+列出所有知识库。
+
+```sh
+ctxdb kb list [--agent=<name>]
+```
+
+返回 `knowledge_bases` 数组，每项含知识库名称、ID、文档数等。
+
+## kb documents-list
+
+列出知识库中的文档。
+
+```sh
+ctxdb kb documents-list <kb-name> [--agent=<name>]
+```
+
+## kb document-get
+
+查看文档详情。
+
+```sh
+ctxdb kb document-get <kb-name> <doc-id> [--agent=<name>]
+```
+
+## 写操作注意事项
+
+`kb create`、`kb upload-text`、`kb upload-file` 是副作用操作（创建 KB / 写入文档）。执行前须明确目标 KB 名称：
+
+- 用户指定了 KB 名称 → 直接使用
+- 用户未指定 → 先用 `kb list` 查看现有知识库，向用户确认目标 KB 后再操作
+- KB 不存在时 upload 命令会自动创建，需确认用户意图是新建还是写入已有 KB
+
+## --agent 参数
+
+所有 kb 命令支持 `--agent <name>` 指定操作目标。知识库归属于 workspace，不同 agent 若共享同一 workspace 则访问相同的知识库。
+
+不带 `--agent` 时的解析顺序：`CTXDB_AGENT` 环境变量 → `agents.default` 配置段。
+
+## Hooks 感知
+
+**KB 目录注入**：如果对话中出现 `<available-knowledge-bases>` 块，表示 hooks 已启用，该块列出可用知识库名称，可直接用于 `--kb=<name>` 参数。
+
+**B-3c 守卫**：包含 `kb upload-text` 或 `kb upload-file` 操作的对话轮次，其内容不会被 autoCapture 写入记忆（防止文档原文混入记忆）。
+
+如果对话中没有 `<available-knowledge-bases>`，表示当前为纯 CLI 模式，用 `kb list` 查看可用知识库。
+
+所有命令输出 JSON 到 stdout，错误输出到 stderr 并返回非零退出码。

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

@@ -0,0 +1,142 @@
+---
+name: contextdb-memory
+description: RDS contextdb 记忆操作全量参考。覆盖 memory add / search / list / get / update / delete 的完整参数、JSON 输出结构和 hooks 感知机制。当用户提到"记住"、"记一下"、"查记忆"、"删记忆"、"改记忆"、"之前说过"等场景时使用。
+---
+
+# contextdb Memory 操作参考
+
+## 配置
+
+- 配置文件：`~/.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`
+
+## memory add
+
+将文本写入长期记忆。
+
+```sh
+ctxdb memory add "<text>" [--no-infer] [--user-id=<id>] [--metadata=K1=V1,K2=V2] [--agent=<name>]
+```
+
+| 参数 | 说明 |
+|------|------|
+| `<text>` | 要记忆的文本内容（必填） |
+| `--no-infer` | 跳过 LLM fact-extraction，原文直存 |
+| `--user-id` | 覆盖配置中的 user_id |
+| `--metadata` | 附加键值对元数据，逗号分隔 |
+| `--agent` | 指定操作哪个 agent 的记忆桶（默认使用 agents.default 配置） |
+
+服务端默认走同步模式（`async_mode: false`），等待 LLM fact-extraction 完成后返回结果。`--no-infer` 跳过提炼，适用于需要原文保留的场景（如项目代号、精确数值）。
+
+**输出 JSON 结构**（同步模式）：
+
+```json
+{
+  "results": [
+    {
+      "id": "mem-uuid",
+      "memory": "提炼后的事实文本",
+      "event": "ADD"
+    }
+  ]
+}
+```
+
+`event` 可能的值：`ADD`（新增）、`UPDATE`（更新已有记忆）、`NONE`（无新事实提取）。`results` 为空数组表示服务端未从输入中提取出新事实。
+
+## memory search
+
+搜索长期记忆。
+
+```sh
+ctxdb memory search "<query>" [--top-k=N] [--threshold=F] [--knowledge] [--verbose] [--raw] [--agent=<name>]
+```
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `<query>` | 搜索文本（必填） | |
+| `--top-k` | 返回条数上限 | 5 |
+| `--threshold` | 相关度阈值 | 0.4 |
+| `--knowledge` | 同时搜索知识库 chunks | false |
+| `--verbose` | 增加 doc_name/kb_id 等字段（knowledge 模式） | false |
+| `--raw` | 服务端原始响应 | false |
+| `--agent` | 指定操作哪个 agent 的记忆桶 | agents.default |
+
+**输出 JSON 结构**：
+
+```json
+{
+  "results": [
+    {
+      "id": "mem-uuid",
+      "memory": "事实文本",
+      "score": 0.85
+    }
+  ]
+}
+```
+
+`results` 为空数组表示未找到匹配记忆。
+
+带 `--knowledge` 时额外返回 `knowledge` 数组（每项含 `content` / `score`，`--verbose` 增加 `doc_name` / `kb_id` / `doc_id` / `tags`）。
+
+## memory list
+
+列出记忆。
+
+```sh
+ctxdb memory list [--page-size=N] [--category=<cat>] [--agent=<name>]
+```
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `--page-size` | 每页条数 | 100 |
+| `--category` | 按分类过滤 | |
+
+## memory get
+
+查看单条记忆。
+
+```sh
+ctxdb memory get <memory-id> [--agent=<name>]
+```
+
+## memory update
+
+修改记忆内容。
+
+```sh
+ctxdb memory update <memory-id> --text="<new-text>" [--agent=<name>]
+```
+
+## memory delete
+
+删除记忆。
+
+```sh
+ctxdb memory delete <memory-id> [--agent=<name>]
+ctxdb memory delete --all [--agent=<name>]
+```
+
+`--all` 删除当前 user_id 下的所有记忆。
+
+## --agent 参数
+
+所有 memory 命令支持 `--agent <name>` 指定操作目标。不同 agent 的记忆存储在各自的配置桶中（由 `~/.ctxdb/ctxdb.json` 的 `agents.<name>.user_id` 决定）。
+
+不带 `--agent` 时的解析顺序：`CTXDB_AGENT` 环境变量 → `agents.default` 配置段。
+
+## Hooks 感知
+
+**autoCapture**：如果对话中出现 `<recalled-memories>` 块，表示 Stop hook 在每轮对话结束后自动提取事实写入记忆。`memory add` 在此基础上用于用户主动强调的内容（加强记忆）。
+
+**autoRecall**：`<recalled-memories>` 块内容是 UserPromptSubmit hook 自动搜索当前 prompt 相关记忆的结果。
+
+**B-3c 守卫**：包含 `kb upload-text` 或 `kb upload-file` 操作的对话轮次，其内容不会被 autoCapture 写入记忆（防止文档原文混入记忆）。
+
+如果对话中没有 `<recalled-memories>`，表示当前为纯 CLI 模式，所有操作需主动调用。
+
+所有命令输出 JSON 到 stdout，错误输出到 stderr 并返回非零退出码。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliyunrds/ctxdb",
-  "version": "0.0.4",
+  "version": "0.0.7",
   "type": "module",
   "description": "Unified access layer for RDS ContextDatabase: `ctxdb` CLI (memory + KB ops), one-shot `setup --agent <qoder|codex|claude>` installer, per-agent config, hooks, and SKILL.md.",
   "license": "Apache-2.0",
@@ -28,7 +28,7 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@aliyunrds/ctxdb-shared": "~0.0.2"
+    "@aliyunrds/ctxdb-shared": "~0.0.3"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",