@aliyunrds/ctxdb 1.0.6 → 1.0.8-beta.0

package/dist/hooks/hermes-post-llm-call.js

@@ -1,18 +1,20 @@
 #!/usr/bin/env node
 import {
   captureParsedMessages
-} from "../chunk-6BB65W5W.js";
-import "../chunk-B7JCQL4O.js";
+} from "../chunk-HF2CWTRU.js";
+import "../chunk-NJJBT52C.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
   debug,
   load,
   setDebug
-} from "../chunk-ARZX2RLR.js";
+} from "../chunk-AAZLOCVB.js";
 import {
   shouldSkipHooks
-} from "../chunk-UEKR2Z3S.js";
+} from "../chunk-5ML4VSXN.js";
+import "../chunk-R67JELM7.js";
+import "../chunk-VIG4SYLU.js";
 
 // src/hooks/hermes-post-llm-call.ts
 import { pathToFileURL } from "url";

package/dist/hooks/hermes-pre-llm-call.js

@@ -2,17 +2,17 @@
 import {
   HOOK_TIMEOUT_MS,
   composeSessionStart
-} from "../chunk-BHRWAU3E.js";
+} from "../chunk-24CNB3XJ.js";
 import {
   composeUserPromptSubmit
-} from "../chunk-7EIJB5LA.js";
+} from "../chunk-BBTXHFMD.js";
 import {
   fetchKbCatalogBlock
-} from "../chunk-VHNHVMCA.js";
-import "../chunk-L4GVGVOP.js";
+} from "../chunk-WSMZOFZQ.js";
+import "../chunk-CAXRYH6E.js";
 import {
   isCircuitOpen
-} from "../chunk-B7JCQL4O.js";
+} from "../chunk-NJJBT52C.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
@@ -20,10 +20,12 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-ARZX2RLR.js";
+} from "../chunk-AAZLOCVB.js";
 import {
   shouldSkipHooks
-} from "../chunk-UEKR2Z3S.js";
+} from "../chunk-5ML4VSXN.js";
+import "../chunk-R67JELM7.js";
+import "../chunk-VIG4SYLU.js";
 
 // src/hooks/hermes-pre-llm-call.ts
 import { pathToFileURL } from "url";

package/dist/hooks/pre-tool-use.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import {
   shouldSkipHooks
-} from "../chunk-UEKR2Z3S.js";
+} from "../chunk-5ML4VSXN.js";
+import "../chunk-VIG4SYLU.js";
 
 // src/hooks/pre-tool-use.ts
 async function main() {

package/dist/hooks/session-start.js

@@ -3,12 +3,12 @@ import {
   HOOK_TIMEOUT_MS,
   composeSessionStart,
   formatSessionStartStdout
-} from "../chunk-BHRWAU3E.js";
-import "../chunk-VHNHVMCA.js";
-import "../chunk-L4GVGVOP.js";
+} from "../chunk-24CNB3XJ.js";
+import "../chunk-WSMZOFZQ.js";
+import "../chunk-CAXRYH6E.js";
 import {
   isCircuitOpen
-} from "../chunk-B7JCQL4O.js";
+} from "../chunk-NJJBT52C.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
@@ -16,10 +16,12 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-ARZX2RLR.js";
+} from "../chunk-AAZLOCVB.js";
 import {
   shouldSkipHooks
-} from "../chunk-UEKR2Z3S.js";
+} from "../chunk-5ML4VSXN.js";
+import "../chunk-R67JELM7.js";
+import "../chunk-VIG4SYLU.js";
 
 // src/hooks/session-start.ts
 import { pathToFileURL } from "url";

package/dist/hooks/stop.js

@@ -1,18 +1,20 @@
 #!/usr/bin/env node
 import {
   captureTurn
-} from "../chunk-6BB65W5W.js";
-import "../chunk-B7JCQL4O.js";
+} from "../chunk-HF2CWTRU.js";
+import "../chunk-NJJBT52C.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
   debug,
   load,
   setDebug
-} from "../chunk-ARZX2RLR.js";
+} from "../chunk-AAZLOCVB.js";
 import {
   shouldSkipHooks
-} from "../chunk-UEKR2Z3S.js";
+} from "../chunk-5ML4VSXN.js";
+import "../chunk-R67JELM7.js";
+import "../chunk-VIG4SYLU.js";
 
 // src/hooks/stop.ts
 async function readStdinJson() {

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

@@ -2,12 +2,12 @@
 import {
   composeUserPromptSubmit,
   formatUserPromptSubmitStdout
-} from "../chunk-7EIJB5LA.js";
-import "../chunk-VHNHVMCA.js";
-import "../chunk-L4GVGVOP.js";
+} from "../chunk-BBTXHFMD.js";
+import "../chunk-WSMZOFZQ.js";
+import "../chunk-CAXRYH6E.js";
 import {
   isCircuitOpen
-} from "../chunk-B7JCQL4O.js";
+} from "../chunk-NJJBT52C.js";
 import {
   HttpClient,
   agentFromArgvWithFallback,
@@ -15,10 +15,12 @@ import {
   isComplete,
   load,
   setDebug
-} from "../chunk-ARZX2RLR.js";
+} from "../chunk-AAZLOCVB.js";
 import {
   shouldSkipHooks
-} from "../chunk-UEKR2Z3S.js";
+} from "../chunk-5ML4VSXN.js";
+import "../chunk-R67JELM7.js";
+import "../chunk-VIG4SYLU.js";
 
 // src/hooks/user-prompt-submit.ts
 import { pathToFileURL } from "url";

package/dist/opencode/index.js

@@ -1,7 +1,10 @@
+// <define:__CTXDB_DISTRIBUTION_MANIFEST__>
+var define_CTXDB_DISTRIBUTION_MANIFEST_default = { id: "public", packageName: "@aliyunrds/ctxdb", packageRegistry: null, capabilities: { interactiveLogin: false, managedCredentials: false } };
+
 // src/config.ts
-import { readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
+import { readFileSync as readFileSync2, existsSync as existsSync2, statSync as statSync2 } from "fs";
 import { homedir as homedir2 } from "os";
-import { join as join2 } from "path";
+import { dirname as dirname2, join as join2 } from "path";
 
 // ../shared/src/graph-context.ts
 var GRAPH_CONTEXT_TAG = "graphrag";
@@ -828,6 +831,18 @@ function isRecallTraceRecord(value) {
   return isNonNegativeFinite(record.duration_ms) && typeof record.outcome === "string" && TRACE_OUTCOMES.has(record.outcome) && (typeof record.failure_reason === "string" || record.failure_reason === null) && Array.isArray(record.returned_memories) && Array.isArray(record.returned_knowledge) && Boolean(selection) && Array.isArray(selection?.selected) && Array.isArray(selection?.excluded) && isNonNegativeFinite(selection?.token_estimate) && typeof record.recall_context === "string";
 }
 
+// src/distribution-capabilities.ts
+var PUBLIC_DISTRIBUTION = {
+  id: "public",
+  packageName: "@aliyunrds/ctxdb",
+  packageRegistry: null,
+  capabilities: {
+    interactiveLogin: false,
+    managedCredentials: false
+  }
+};
+var DISTRIBUTION_MANIFEST = typeof define_CTXDB_DISTRIBUTION_MANIFEST_default === "undefined" ? PUBLIC_DISTRIBUTION : define_CTXDB_DISTRIBUTION_MANIFEST_default;
+
 // src/config.ts
 var DEFAULT_BASE_URL = "https://context-database.aliyuncs.com";
 var DEFAULT_USER_ID = "default";
@@ -893,6 +908,40 @@ function applyDebugPolicy(cfg) {
   cfg.debugReason = policy.debugReason;
   return cfg;
 }
+function managedCredential(path) {
+  if (!existsSync2(path)) return null;
+  if (process.platform !== "win32" && (statSync2(path).mode & 63) !== 0) {
+    throw new Error(`credentials: ${path} must be owner-only (run chmod 600)`);
+  }
+  const raw = JSON.parse(readFileSync2(path, "utf8"));
+  if (raw.version !== 1 || !raw.records || typeof raw.records !== "object") {
+    throw new Error("credentials: unsupported credentials.json schema");
+  }
+  const unknownKeys = Object.keys(raw.records).filter(
+    (key) => key !== "contextdb/active"
+  );
+  if (unknownKeys.length > 0) {
+    throw new Error(`credentials: unsupported record key ${unknownKeys[0]}`);
+  }
+  const record = raw.records["contextdb/active"];
+  if (!record) return null;
+  if (record.kind !== "api-key" || typeof record.payload?.api_key !== "string" || !record.payload.api_key || typeof record.payload?.base_url !== "string" || !record.payload.base_url) {
+    throw new Error("credentials: invalid contextdb/active record");
+  }
+  let baseUrl;
+  try {
+    baseUrl = new URL(record.payload.base_url);
+  } catch {
+    throw new Error("credentials: invalid contextdb/active base_url");
+  }
+  if (!["https:", "http:"].includes(baseUrl.protocol) || baseUrl.username || baseUrl.password || baseUrl.search || baseUrl.hash) {
+    throw new Error("credentials: invalid contextdb/active base_url");
+  }
+  return {
+    apiKey: record.payload.api_key,
+    baseUrl: baseUrl.toString().replace(/\/$/, "")
+  };
+}
 function loadOpencodeConfig(options = {}) {
   const env = options.env ?? process.env;
   const path = options.path ?? defaultPath(env);
@@ -918,6 +967,13 @@ function loadOpencodeConfig(options = {}) {
     debugReason: null,
     kbCatalogInjection: coerceKbCatalogInjection(section.kb_catalog_injection)
   };
+  const managed = DISTRIBUTION_MANIFEST.capabilities.managedCredentials && options.managedCredentials !== false ? managedCredential(
+    options.credentialsPath ?? join2(dirname2(path), "credentials.json")
+  ) : null;
+  if (managed) {
+    cfg.apiKey = managed.apiKey;
+    cfg.baseUrl = managed.baseUrl;
+  }
   return applyEnv(cfg, env);
 }
 function isConfigured(cfg) {

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

@@ -12,7 +12,8 @@ description: contextdb 知识库高频操作（查询 / 浏览 KB / 上传或更
 - 用户想**找已有 KB 里的内容** → §2 recipe 1
 - 用户**不知道有哪些 KB** → §2 recipe 2
 - 用户想**了解某个 KB 收了哪些文档** → §2 recipe 3
-- 用户要**写入/上传/更新内容** → §2 recipe 4/5
+- 用户要**新建/上传内容** → §2 recipe 4/5
+- 用户要**更新已有文档** → §2 recipe 6/7
 
 配套 skill：**contextdb-memory**（长期记忆操作）。两者用同一份 `~/.ctxdb/ctxdb.json` 配置和同一个 `--agent` 路由。
 
@@ -101,7 +102,40 @@ ctxdb kb upload-file <kb-name> <local-path> --agent={{agent}}
 
 **何时不适用**：要上传的内容是字符串而非本地文件 → recipe 4。
 
-> **同名文档更新**：同一 KB、同一 `--file-path` 下，以相同文档名再次上传，服务端按更新（替换）语义处理；继续调用对应的 `kb upload-text` / `kb upload-file` 命令即可（`upload-file` 必要时用 `--doc-name` 保持文档名不变）。
+### Recipe 6：更新已有文本文档
+
+**场景**：用户明确要替换某个已存在 KB 文本文档的内容。
+
+```sh
+ctxdb kb update-text <document-id> --text="<new-body>" --agent={{agent}}
+
+# 只有拿不到精确 document ID、但已知完整逻辑键时才用：
+ctxdb kb update-text --kb-name=<kb-name> --doc-name=<logical-name> --text="<new-body>" [--file-path=<logical-parent-path>] --agent={{agent}}
+```
+
+已有精确 `document-id` 时优先用第一种，不需要再向用户索取 KB，也不要同时传
+`--kb-name` / `--doc-name` / `--file-path`。服务端会从文档 ID 校验权限并解析所属 KB。
+命令返回的 `document.id` 是后续更新的新权威 ID：内容变化时通常会换 ID，相同内容也可能
+复用原 ID，Agent 都必须以本次返回值为准。只有拿不到 ID、但已确认完整 **KB + 文档名 +
+`file_path`** 逻辑键时才用第二种；目标信息不完整时先核对或向用户确认，不能模糊猜测。
+重复调用 `upload-text` 是创建冲突，不会自动转成更新。
+
+### Recipe 7：更新已有文件文档
+
+**场景**：用户用新的本地文件内容替换某个已存在 KB 文件文档。
+
+```sh
+ctxdb kb update-file <document-id> <local-path> --agent={{agent}}
+
+# 只有拿不到精确 document ID、但已知完整逻辑键时才用：
+ctxdb kb update-file <local-path> --kb-name=<kb-name> [--doc-name=<existing-logical-name>] [--file-path=<logical-parent-path>] --agent={{agent}}
+```
+
+ID 模式只用 `document-id` 定位远端文档，本地文件名只是上传的物理文件名；替换文件改了
+文件名也不需要补远端名称或 KB。逻辑键模式下，远端逻辑文档名默认取本地文件名；若替换
+文件名不同，必须用 `--doc-name` 继续传已有逻辑名。两种定位方式不能混用。分片更新只在
+init 使用 PUT，part/complete 保持原协议；网络结果不明确时不自动重试或删除旧文档。
+成功后同样必须保存返回的 `document.id`，不要继续沿用输入 ID。
 
 ## 3. 命令速查
 
@@ -116,6 +150,8 @@ ctxdb kb upload-file <kb-name> <local-path> --agent={{agent}}
 | `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>` |
+| `kb update-text` | `ctxdb kb update-text <document-id> --text="<body>" --agent=<name>` |
+| `kb update-file` | `ctxdb kb update-file <document-id> <local-path> --agent=<name>` |
 
 所有命令 JSON 写 stdout、错误写 stderr 非零退出码。
 
@@ -127,7 +163,7 @@ ctxdb kb upload-file <kb-name> <local-path> --agent={{agent}}
 
 **`<external-knowledge>` 块**：开启 KB 自动召回时，内部按 `## 图谱合成上下文` / `## 文档证据` 分区。图谱区只用于关系理解和检索导航，文档区才是回答与引用证据；图谱区被独立限制长度，不会挤掉已选中的文档证据。
 
-**B-3c 守卫**：含 `kb upload-text` / `kb upload-file` 的对话轮次，其内容**不会**被 autoCapture 写入记忆（防文档原文混进记忆桶）。
+**B-3c 守卫**：含 `kb upload-text` / `kb upload-file` / `kb update-text` / `kb update-file` 的对话轮次，其内容**不会**被 autoCapture 写入记忆（防文档原文混进记忆桶）。
 
 **纯 CLI 模式**：对话里没有上面任何块 → 说明当前不在 hook 环境（agent 是裸 CLI 调用），所有信息只能主动调命令拿。
 
@@ -145,11 +181,12 @@ ctxdb kb upload-file <kb-name> <local-path> --agent={{agent}}
 - **根因**：shell + python -c 的引号是两层独立 escape，组合时极容易漏
 - **正确做法**：`ctxdb kb list --agent={{agent}} | jq '.knowledge_bases[].name'`；jq 表达式在单引号里不需要 escape
 
-### 注意事项 3：`upload-*` / `create` 是副作用，没明示 KB 名前必须先确认
+### 注意事项 3：创建和逻辑键更新没明示 KB 名前必须先确认
 
 - **现象**：用户只说"把这段记进知识库"没指定 KB，agent 直接用了某个猜的 KB 名 → 写到错的桶
 - **根因**：写命令不会跟 agent 二次确认；KB 不存在时报错，但**KB 名拼错却恰好命中另一个真实 KB**时会静默写错
-- **正确做法**：用户没明示 → 必须先 `kb list` 拿候选清单，跟用户确认目标后才执行
+- **正确做法**：`upload-*` / `create` / 逻辑键 `update-*` 在用户没明示 KB 时，必须先
+  `kb list` 拿候选清单并确认；精确 document-ID 更新已经绑定目标，不再额外要求 KB
 
 ### 注意事项 4：`kb search` 空结果时降阈值再试一次
 
@@ -175,12 +212,13 @@ ctxdb kb upload-file <kb-name> <local-path> --agent={{agent}}
 | `--verbose` | 每个 chunk 加 `doc_name` / `kb_id` / `doc_id` / `tags` | false |
 | `--raw` | 服务端原始响应（13+ 字段，图结果仍混在 `chunks`，含 tokenizer 细节） | false |
 
-### `kb upload-file` / `kb upload-text` 全部 flag
+### `kb upload-*` / `kb update-*` 全部 flag
 
 | 参数 | 说明 |
 |------|------|
-| `--doc-name` | （`upload-file`）服务端文档名，默认取本地文件名 |
-| `--file-path` | KB 内的逻辑父目录，不包含文档名/文件名 |
+| `--kb-name` | 仅逻辑键更新使用；不能与位置参数中的 document ID 混用 |
+| `--doc-name` | `upload-file` 的逻辑文档名，或逻辑键更新的精确文档名；ID 更新不使用 |
+| `--file-path` | 创建/逻辑键更新时 KB 内的逻辑父目录；ID 更新不使用 |
 | `--wait` | 等到 ingest 成功、失败或达到原有超时；用于迁移旧的默认等待行为 |
 | `--no-wait` | 兼容参数；与新的“受理后立即返回”默认行为相同 |
 

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

@@ -95,7 +95,7 @@ ctxdb memory delete <memory-id> --agent={{agent}}
 
 **autoCapture（Stop / post_llm_call / plugin）**：每轮对话结束后服务端异步提炼事实写记忆，**不用 agent 主动调** `memory add`。`memory add` 用于用户**明确强调**的内容（强加重要性）。
 
-**B-3c 守卫**：含 `kb upload-text` / `kb upload-file` 的轮次，**autoCapture 跳过**这一轮（防文档原文进记忆桶）。
+**B-3c 守卫**：含 `kb upload-text` / `kb upload-file` / `kb update-text` / `kb update-file` 的轮次，**autoCapture 跳过**这一轮（防新建或更新的文档原文进记忆桶）。
 
 **纯 CLI 模式**：对话里没 `<recalled-memories>` 块 → 不在 hook 环境（裸 CLI），所有 recall / capture 只能主动 `ctxdb memory search` / `ctxdb memory add`。
 

package/dist/workers/version-check.js

@@ -4,7 +4,9 @@ import {
   recordVersionCheckFailure,
   recordVersionCheckSuccess,
   releaseVersionCheckLock
-} from "../chunk-Z6OHSEF2.js";
+} from "../chunk-ULAWTBBC.js";
+import "../chunk-R67JELM7.js";
+import "../chunk-VIG4SYLU.js";
 
 // src/workers/version-check.ts
 import { fileURLToPath } from "url";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aliyunrds/ctxdb",
-  "version": "1.0.6",
+  "version": "1.0.8-beta.0",
   "type": "module",
   "description": "Unified access layer for RDS ContextDatabase: `ctxdb` CLI (memory + KB ops), one-shot `setup --agent <qoder|qoderwork|codex|claude|opencode|hermes>` installer, per-agent config, hooks/plugins, and SKILL.md.",
   "license": "Apache-2.0",
@@ -32,7 +32,7 @@
   "dependencies": {
     "semver": "^7.8.5",
     "yaml": "^2.9.0",
-    "@aliyunrds/ctxdb-shared": "~0.0.6"
+    "@aliyunrds/ctxdb-shared": "~0.0.7"
   },
   "devDependencies": {
     "@types/node": "^22.15.0",
@@ -44,6 +44,10 @@
   },
   "scripts": {
     "build": "tsup && pnpm --dir ../opencode build && mkdir -p dist/setup dist/opencode && cp ../opencode/dist/index.js dist/opencode/index.js && cp -r src/setup/skills dist/setup/ && chmod +x dist/hooks/*.js dist/cli/main.js",
+    "build:internal": "tsup --config tsup.internal.config.ts && pnpm --dir ../opencode build:internal && mkdir -p dist-internal/setup dist-internal/opencode && cp ../opencode/dist-internal/index.js dist-internal/opencode/index.js && cp -r src/setup/skills dist-internal/setup/ && chmod +x dist-internal/hooks/*.js dist-internal/cli/internal-main.js && node scripts/prepare-internal-package.mjs",
+    "test:distributions": "node scripts/smoke-distribution-builds.mjs",
+    "test:e2e:distributions:prepared": "node scripts/prepare-distribution-e2e.mjs && vitest run --config vitest.e2e.config.ts",
+    "test:e2e:distributions": "pnpm --dir ../shared build && pnpm build && pnpm build:internal && pnpm test:e2e:distributions:prepared",
     "test": "vitest run"
   }
 }