@dai_ming/plugin-deliverables 1.1.3 → 1.1.5

package/INSTALL.md

@@ -1,11 +1,11 @@
 # plugin-deliverables 安装文档
 
-本文档描述 `@dai_ming/plugin-deliverables@1.1.1` 的安装、升级与验证方式。
+本文档描述 `@dai_ming/plugin-deliverables@1.1.2` 的安装、升级与验证方式。
 
 ## 安装
 
 ```bash
-openclaw plugins install @dai_ming/plugin-deliverables@1.1.1 --pin
+openclaw plugins install @dai_ming/plugin-deliverables@1.1.2 --pin
 openclaw plugins enable plugin-deliverables
 ```
 
@@ -13,7 +13,7 @@ gateway 部署配置：
 
 ```yaml
 installPlugins:
-  - "@dai_ming/plugin-deliverables@1.1.1"
+  - "@dai_ming/plugin-deliverables@1.1.2"
 ```
 
 ## 验证
@@ -21,7 +21,7 @@ installPlugins:
 1. `openclaw plugins info plugin-deliverables` 能看到插件已启用。
 2. Agent 工具列表里存在 `deliverables__upload_deliverable`。
 3. Pod 内不再出现 `node ...mcp-servers/deliverables.js` 进程。
-4. 生成交付物时，工具返回 `reply_markdown`、`preview_url`、`download_url`。
+4. 生成交付物时，工具返回 `reply_markdown`、`preview_url`、`download_url`、`document_id`。
 
 ## 说明
 

package/README.md

@@ -1,6 +1,6 @@
 # @dai_ming/plugin-deliverables
 
-OpenClaw Native 插件：注册 `deliverables__upload_deliverable` 原生 agent tool，把 AI 生成的文件上传到 claw-gateway 交付物系统，并返回可分享的预览/下载链接。
+OpenClaw Native 插件：注册 `deliverables__upload_deliverable` 原生 agent tool，把 AI 生成的文件上传到知识库交付物系统，并返回可分享的预览/下载链接。
 
 ## 包含内容
 
@@ -11,11 +11,12 @@ OpenClaw Native 插件：注册 `deliverables__upload_deliverable` 原生 agent
 | `openclaw-plugin.json` | gateway 兼容清单：声明 skill、AGENTS 规则和插件 entry |
 | `skills/deliverables/SKILL.md` | Agent 使用交付物工具的技能说明 |
 | `agents-rules/deliverables.md` | 注入到 workspace `AGENTS.md` 的硬规则 |
+| `deliverables.*.config.json` | 各环境知识库连接配置 |
 
 ## 安装
 
 ```bash
-openclaw plugins install @dai_ming/plugin-deliverables@1.1.1 --pin
+openclaw plugins install @dai_ming/plugin-deliverables@1.1.2 --pin
 openclaw plugins enable plugin-deliverables
 ```
 
@@ -23,7 +24,7 @@ openclaw plugins enable plugin-deliverables
 
 ```yaml
 installPlugins:
-  - "@dai_ming/plugin-deliverables@1.1.1"
+  - "@dai_ming/plugin-deliverables@1.1.2"
 ```
 
 ## 运行方式
@@ -34,11 +35,21 @@ installPlugins:
 deliverables__upload_deliverable
 ```
 
-上传工具通过以下环境变量调用 claw-gateway：
+上传工具根据 `HELM_ENV` 环境变量加载对应配置文件：
 
-- `CLAW_GATEWAY_URL`
-- `CLAW_GATEWAY_PUBLIC_URL`
-- `CLAW_GATEWAY_API_KEY` 或 `OPENCLAW_GATEWAY_API_KEY`
+| HELM_ENV | 配置文件 | 说明 |
+|----------|---------|------|
+| (空) | `deliverables.config.json` | 本地开发（127.0.0.1） |
+| `dev` | `deliverables.dev.config.json` | dev 环境 |
+| `staging` | `deliverables.staging.config.json` | staging 环境 |
+| `prod` | `deliverables.prod.config.json` | 生产环境 |
+
+配置字段：
+
+- `kbBaseUrl` — 知识库 API 内部地址（Pod 内通信）
+- `kbPublicUrl` — 用户可见的预览链接地址
+
+环境变量 `KNOWLEDGE_DB_URL` / `KNOWLEDGE_DB_PUBLIC_URL` 可覆盖配置文件值。`KNOWLEDGE_DB_API_KEY` 仅通过环境变量配置（默认 `kb-agent-key-2025`）。
 
 ## 发布
 

package/agents-rules/deliverables.md

@@ -81,6 +81,10 @@ Tool name note:
    Keep that format instead of forcing a zip link.
 23. Do NOT only say "已保存到工作空间".
 24. Do NOT append workspace path or a raw URL block after the Markdown links.
+25. 群聊场景（消息元数据包含 `is_group_chat == true` 或 `conversation_type == "group"`）调用上传工具时，MUST 传入 `group_id`（取自元数据的 `group_id` 或 `conversation_id`）和 `group_name`（取自元数据的 `group_name` 或 `group_subject`）。
+26. 单聊/私聊场景，不传 `group_id` 或传 `"default"`，不传 `group_name`。
+27. 无法判断会话类型时，若 `resource_id` 存在且不是 `"default"`，将 `resource_id` 作为 `group_id` 传入。
+28. 调用上传工具时 MUST 传入 `user_id`：单聊取 `owner_id`，群聊取 `sender_id`。漏传 `user_id` 会导致 KB 上传失败（error 13002: 用户不存在），尤其在同时传了真实 `group_id` 的场景下。
 
 ### Exception
 

package/deliverables.dev.config.json

@@ -0,0 +1,4 @@
+{
+  "kbBaseUrl": "http://knowledge-db:8080/api/v1",
+  "kbPublicUrl": "https://uniclaw-ai-kb.csaiagent.com/api/v1"
+}

package/deliverables.prod.config.json

@@ -0,0 +1,4 @@
+{
+  "kbBaseUrl": "http://knowledge-db:8080/api/v1",
+  "kbPublicUrl": "https://uniclaw-ai-kb.csagentai.com/api/v1"
+}

package/deliverables.staging.config.json

@@ -0,0 +1,4 @@
+{
+  "kbBaseUrl": "http://knowledge-db:8080/api/v1",
+  "kbPublicUrl": "https://uniclaw-ai-kb.csjkagent.com/api/v1"
+}

package/index.js

@@ -11,14 +11,50 @@ const PENDING_FILES_KEY = "__plugin_deliverables_pending_files__";
 const UPLOAD_CACHE_KEY = "__plugin_deliverables_upload_cache__";
 const SUMMARY_CACHE_LIMIT = 200;
 const SHORT_SUMMARY_THRESHOLD = 120;
-const DEFAULT_GATEWAY_PUBLIC_URL = "https://claw-gateway.csagentai.com";
-const DEFAULT_GATEWAY_INTERNAL_URL = "http://claw-gateway:8080";
+const DEFAULT_KB_BASE_URL = "http://knowledge-db:8080/api/v1";
+const DEFAULT_KB_API_KEY = "kb-agent-key-2025";
+const DEFAULT_GROUP_ID = "default";
+const DEFAULT_GROUP_NAME = "我的文件夹";
+const DEFAULT_DELIVERABLES_CONFIG_FILENAME = "deliverables.config.json";
+let _cachedDeliverableConfig = null;
+
+function getDeliverableConfigFilename() {
+  const helmEnv = (process.env.HELM_ENV || "").trim();
+  return helmEnv
+    ? "deliverables." + helmEnv + ".config.json"
+    : DEFAULT_DELIVERABLES_CONFIG_FILENAME;
+}
+
+function loadDeliverableConfig() {
+  if (_cachedDeliverableConfig) return _cachedDeliverableConfig;
+  const helmEnv = (process.env.HELM_ENV || "").trim();
+  const configFilename = getDeliverableConfigFilename();
+  const candidates = [
+    path.resolve(process.cwd(), configFilename),
+    path.resolve(__dirname, configFilename),
+  ];
+  for (const filePath of candidates) {
+    try {
+      if (fs.existsSync(filePath)) {
+        _cachedDeliverableConfig = JSON.parse(fs.readFileSync(filePath, "utf-8"));
+        return _cachedDeliverableConfig;
+      }
+    } catch (_err) { /* ignore */ }
+  }
+  if (helmEnv) {
+    throw new Error(
+      "plugin-deliverables: HELM_ENV=\"" + helmEnv + "\" but config file \"" + configFilename + "\" not found, searched: " + candidates.join(", ")
+    );
+  }
+  _cachedDeliverableConfig = {};
+  return _cachedDeliverableConfig;
+}
 const AUTO_UPLOAD_TTL_MS = 15 * 60 * 1000;
 const AUTO_UPLOAD_MAX_FILES = 8;
 const AUTO_UPLOAD_MAX_BYTES = 200 * 1024 * 1024;
 const AUTO_UPLOAD_SCAN_MAX_ENTRIES = 4000;
 const AUTO_UPLOAD_SCAN_DEPTH = 5;
-const DELIVERABLE_GATEWAY_PATH_RE = /^\/openclaw-gateway\/(?:output|preview)(?:\/|$)/u;
+const DELIVERABLE_KB_PATH_RE = /\/documents\/content\b/u;
 const DELIVERABLE_LINK_PREFIX_RE =
   /^\s*(?:[-*+]\s+)?(?:预览链接|下载链接|文件列表|项目入口|在线预览|在线体验|目录链接)\s*[:：]/u;
 const DELIVERABLE_LINK_LABEL_RE =
@@ -26,8 +62,8 @@ const DELIVERABLE_LINK_LABEL_RE =
 const INTERNAL_ABSOLUTE_PATH_RE =
   /(?:\/data\/workspace-[^\s`"'<>，。；：、)）\]}]+|\/home\/node\/\.openclaw\/workspace(?:-[A-Za-z0-9_.-]+)?\/[^\s`"'<>，。；：、)）\]}]+)/gu;
 const INLINE_FILE_REF_RE = /`([^`\n]{1,512}\.[A-Za-z0-9]{1,16})`/gu;
-const MARKDOWN_FILE_LINK_RE = /\[[^\]\n]{0,200}\]\(([^)\s]+?\.[A-Za-z0-9]{1,16})\)/gu;
 const OUTPUT_RELATIVE_REF_RE = /(?:^|[\s(:：])((?:\.\/)?output\/[^\s`"'<>，。；：、)）\]}]+\.[A-Za-z0-9]{1,16})/gu;
+const MARKDOWN_FILE_LINK_RE = /\[[^\]\n]{0,200}\]\(([^)\s]+?\.[A-Za-z0-9]{1,16})\)/gu;
 const FILE_EXTENSION_RE = /\.[A-Za-z0-9]{1,16}$/u;
 const TEXT_EXTENSIONS = new Set([
   ".css",
@@ -81,14 +117,16 @@ const RUNTIME_DELIVERABLES_GUIDANCE = [
   "- When the user asks for a document, article, report, PDF, HTML page, Markdown file, PPT, image, archive, game, or any other file deliverable, you MUST create it under the current workspace `output/` directory and upload it with `deliverables__upload_deliverable`.",
   "- For simple text PDF deliverables, call `deliverables__upload_deliverable` with `type: \"pdf\"`, a `.pdf` `file_name`, and `content_text`; the tool will render a basic PDF without installing dependencies.",
   "- For existing binary deliverables such as rich PDFs, PPT, images, video, or zip files, pass `file_path` to `deliverables__upload_deliverable` after writing the file under `output/`; do not paste command output or partial base64 into `content_base64`.",
-  "- Never use `type: \"link\"` for local files, relative paths, or generated files such as `review.html`; use `file_path`, `content_text`, or `files` so the file is uploaded.",
   "- Never install PDF libraries or other packages at runtime just to create a deliverable. Use built-in tools or the PDF `content_text` fallback; if a rich PDF renderer is unavailable, say so clearly.",
   "- If the user asks for PDF, upload the generated `.pdf` as `type: \"pdf\"`; do not substitute HTML or Markdown unless PDF generation truly failed and you clearly say so.",
   "- Every single-file deliverable must use a file name with an explicit extension. If the user did not specify a document/text format, default to Markdown and use a `.md` file name.",
   "- Do not use direct message attachments to deliver generated files. This includes the message tool attachment fields such as `media`, `path`, `filePath`, `buffer`, `attachment`, or similar file-carrying fields.",
   "- Do not emit `MEDIA:` file references for user-facing deliverables. Deliverable links must come from the deliverables upload tool instead.",
+  "- Never use `type: \"link\"` for local files, relative paths, or generated files such as `review.html`; use `file_path`, `content_text`, or `files` so the file is uploaded.",
   "- If the deliverables upload tool returns an error, retry with a valid `file_path` or explain the upload failure; never invent or rewrite OSS/download URLs.",
   "- After a successful upload, reply with a substantive content summary before the links. For documents/articles/reports/PDFs, include 1 short intro plus 3-5 concise bullets covering the actual sections, highlights, or findings; never respond with only a generic one-sentence upload notice.",
+  "- CRITICAL: In group chats (metadata `is_group_chat == true` or `conversation_type == \"group\"`), you MUST pass `group_id` (from metadata `group_id` or `conversation_id`) and `group_name` (from metadata `group_name` or `group_subject`) to `deliverables__upload_deliverable`. For single/direct chats, omit `group_id` or pass `\"default\"`. Omitting `group_id` in a group chat causes the deliverable to land in the wrong knowledge base.",
+  "- CRITICAL: You MUST always pass `user_id` to `deliverables__upload_deliverable`. In single/direct chats, use `owner_id`; in group chats, use `sender_id`. Omitting `user_id` causes KB upload failures (error 13002: 用户不存在) when `group_id` is set to a real group.",
 ].join("\n");
 
 const UPLOAD_DELIVERABLE_TOOL = {
@@ -103,15 +141,23 @@ const UPLOAD_DELIVERABLE_TOOL = {
     properties: {
       resource_id: {
         type: "string",
-        description: "当前聊天框/会话的唯一 ID（必填）。",
+        description: "当前聊天框/会话的唯一 ID，用于缓存去重。",
+      },
+      user_id: {
+        type: "string",
+        description: "上传者用户 ID。单聊取 owner_id，群聊取 sender_id。",
+      },
+      owner_id: {
+        type: "string",
+        description: "等同于 user_id，从消息元数据 owner_id 字段获取。两者任传其一即可。",
       },
       group_id: {
         type: "string",
-        description: "当前会话所属的群聊 ID（可选）。",
+        description: "分组 ID。单聊不传或传 'default'；群聊传群 ID。",
       },
-      user_id: {
+      group_name: {
         type: "string",
-        description: "请求交付物的用户 ID（可选）。",
+        description: "群聊名称，群聊场景必填，用于构造知识库存储路径；单聊不传。",
       },
       type: {
         type: "string",
@@ -148,7 +194,7 @@ const UPLOAD_DELIVERABLE_TOOL = {
         },
       },
     },
-    required: ["resource_id", "type", "file_name"],
+    required: ["type", "file_name"],
   },
 };
 
@@ -241,10 +287,14 @@ function deliverableTypeForPath(filePath, isDirectory) {
 
 function isAllowedWorkspacePath(candidatePath) {
   const normalized = normalizeSlash(path.resolve(candidatePath));
-  return (
+  if (
     normalized.indexOf("/data/workspace-") === 0 ||
     normalized.indexOf("/home/node/.openclaw/workspace") === 0
-  );
+  ) {
+    return true;
+  }
+  const openclawRoot = normalizeSlash(path.resolve(__dirname, "..", ".."));
+  return normalized.indexOf(openclawRoot + "/workspace") === 0;
 }
 
 function shouldIgnorePath(candidatePath) {
@@ -286,6 +336,20 @@ function workspaceRoots() {
   } catch (_err) {
     // /data is not guaranteed in non-pod test environments.
   }
+  const openclawRoot = path.resolve(__dirname, "..", "..");
+  try {
+    for (const entry of fs.readdirSync(openclawRoot)) {
+      if (!entry || entry.indexOf("workspace") !== 0) {
+        continue;
+      }
+      const root = path.join(openclawRoot, entry);
+      if (safeStat(root) && roots.indexOf(root) === -1) {
+        roots.push(root);
+      }
+    }
+  } catch (_err) {
+    // local dev path may not exist
+  }
   return roots;
 }
 
@@ -384,12 +448,12 @@ function extractFileReferencesFromText(text) {
   for (const match of normalized.matchAll(INLINE_FILE_REF_RE)) {
     add(match[0], match[1], "inline");
   }
-  for (const match of normalized.matchAll(MARKDOWN_FILE_LINK_RE)) {
-    add(match[0], match[1], "markdown-link");
-  }
   for (const match of normalized.matchAll(OUTPUT_RELATIVE_REF_RE)) {
     add(match[1], match[1], "relative");
   }
+  for (const match of normalized.matchAll(MARKDOWN_FILE_LINK_RE)) {
+    add(match[0], match[1], "markdown-link");
+  }
   return refs;
 }
 
@@ -505,13 +569,87 @@ function payloadResourceId(body) {
 }
 
 function payloadGroupId(body) {
-  return extractStringField(body, ["group_id", "groupId", "conversation_id", "conversationId"]);
+  const explicit = extractStringField(body, ["group_id", "groupId"]);
+  if (explicit) {
+    return explicit;
+  }
+  const fallback = extractStringField(body, ["resource_id", "resourceId", "conversation_id", "conversationId"]);
+  return fallback && fallback !== "default" ? fallback : "";
+}
+
+function enrichDeliverableGroupContext(event) {
+  if (!event || !event.params || typeof event.params !== "object") {
+    return;
+  }
+  const existingGroupId = trimString(event.params.group_id);
+  if (!existingGroupId) {
+    const inferredGroupId = extractContextString(event, [
+      "group_id", "groupId", "conversation_id", "conversationId",
+    ]);
+    if (inferredGroupId && inferredGroupId !== "default") {
+      event.params.group_id = inferredGroupId;
+    }
+  }
+  const existingGroupName = trimString(event.params.group_name);
+  if (!existingGroupName) {
+    const inferredGroupName = extractContextString(event, [
+      "group_name", "groupName", "group_subject", "groupSubject",
+    ]);
+    if (inferredGroupName) {
+      event.params.group_name = inferredGroupName;
+    }
+  }
+  const existingUserId = trimString(event.params.user_id);
+  if (!existingUserId || existingUserId === "default") {
+    const inferredUserId = extractContextString(event, [
+      "sender_id", "senderId", "owner_id", "ownerId", "user_id", "userId",
+    ]);
+    if (inferredUserId && inferredUserId !== "default") {
+      event.params.user_id = inferredUserId;
+    }
+  }
 }
 
 function payloadUserId(body) {
   return extractStringField(body, ["user_id", "userId", "sender_id", "senderId", "owner_id", "ownerId"]);
 }
 
+function normalizeBareUserID(value) {
+  let raw = trimString(value);
+  if (!raw) {
+    return "";
+  }
+  if (raw.indexOf("user_") === 0 && raw.indexOf("_lobster_") > 0) {
+    raw = raw.slice("user_".length, raw.indexOf("_lobster_"));
+  } else if (raw.indexOf("user-") === 0 || raw.indexOf("user_") === 0) {
+    raw = raw.slice("user-".length);
+  }
+  return raw;
+}
+
+function userIDFromRelease(release) {
+  return normalizeBareUserID(release);
+}
+
+function userIDFromResourceID(resourceID) {
+  const raw = trimString(resourceID);
+  if (raw.indexOf("user_") !== 0 && raw.indexOf("user-") !== 0) {
+    return "";
+  }
+  return normalizeBareUserID(raw);
+}
+
+function deriveReleaseName() {
+  let release = process.env.botID || process.env.OPENCLAW_RELEASE || process.env.BOT_ID || "";
+  if (!release) {
+    const tok = process.env.OPENCLAW_GATEWAY_TOKEN || "";
+    if (tok.indexOf("oc-") === 0) {
+      release = tok.slice(3);
+    }
+  }
+  return release;
+}
+
 function isWriteTool(toolName) {
   const normalized = normalizeToolName(toolName);
   return normalized === "write" || normalized.endsWith("__write") || normalized === "write_file" || normalized.endsWith("__write_file");
@@ -572,76 +710,128 @@ function pendingCandidatesForPayload(body) {
   return out;
 }
 
-function gatewayURL() {
-  return (process.env.CLAW_GATEWAY_URL || DEFAULT_GATEWAY_INTERNAL_URL).replace(/\/$/, "");
+function kbBaseURL() {
+  const cfg = loadDeliverableConfig();
+  return (process.env.KNOWLEDGE_DB_URL || cfg.kbBaseUrl || DEFAULT_KB_BASE_URL).replace(/\/$/, "");
 }
 
-function gatewayPublicURL() {
-  return (process.env.CLAW_GATEWAY_PUBLIC_URL || process.env.CLAW_GATEWAY_URL || DEFAULT_GATEWAY_PUBLIC_URL).replace(/\/$/, "");
+function kbPublicURL() {
+  const cfg = loadDeliverableConfig();
+  return (process.env.KNOWLEDGE_DB_PUBLIC_URL || cfg.kbPublicUrl || process.env.KNOWLEDGE_DB_URL || cfg.kbBaseUrl || DEFAULT_KB_BASE_URL).replace(/\/$/, "");
 }
 
-function apiKey() {
-  return process.env.CLAW_GATEWAY_API_KEY || process.env.OPENCLAW_GATEWAY_API_KEY || "api-key-1";
+function kbApiKey() {
+  return process.env.KNOWLEDGE_DB_API_KEY || DEFAULT_KB_API_KEY;
 }
 
-function deriveReleaseName() {
-  let release = process.env.botID || process.env.OPENCLAW_RELEASE || process.env.BOT_ID || "";
-  if (!release) {
-    const tok = process.env.OPENCLAW_GATEWAY_TOKEN || "";
-    if (tok.indexOf("oc-") === 0) {
-      release = tok.slice(3);
-    }
-  }
-  return release;
+function kbUploadPath(groupId, groupName) {
+  const gid = trimString(groupId) || DEFAULT_GROUP_ID;
+  const gname = gid === DEFAULT_GROUP_ID
+    ? DEFAULT_GROUP_NAME
+    : trimString(groupName) || gid;
+  return "/" + gname + "/raw";
 }
 
-function normalizeBareUserID(value) {
-  let raw = trimString(value);
-  if (!raw) {
-    return "";
-  }
-  if (raw.indexOf("user_") === 0 && raw.indexOf("_lobster_") > 0) {
-    raw = raw.slice("user_".length, raw.indexOf("_lobster_"));
-  } else if (raw.indexOf("user-") === 0 || raw.indexOf("user_") === 0) {
-    raw = raw.slice("user-".length);
-  }
-  return raw;
+function kbPreviewURL(documentId, userId, groupId) {
+  return kbPublicURL() + "/documents/content?user_id="
+    + encodeURIComponent(trimString(userId) || "default")
+    + "&group_id=" + encodeURIComponent(trimString(groupId) || DEFAULT_GROUP_ID)
+    + "&id=" + encodeURIComponent(String(documentId));
 }
 
-function userIDFromRelease(release) {
-  return normalizeBareUserID(release);
+function kbExtractDocumentId(response) {
+  const data = (response && response.data) || response || {};
+  const items = Array.isArray(data.items) ? data.items : [];
+  if (items.length > 0 && items[0].document && items[0].document.id !== undefined) {
+    return items[0].document.id;
+  }
+  if (data.id !== undefined) {
+    return data.id;
+  }
+  return null;
 }
 
-function userIDFromResourceID(resourceID) {
-  const raw = trimString(resourceID);
-  if (raw.indexOf("user_") !== 0 && raw.indexOf("user-") !== 0) {
-    return "";
+function buildFileBuffersFromBody(body, isDirectory) {
+  if (isDirectory && Array.isArray(body.files)) {
+    return body.files.map((file) => ({
+      fileName: file.name || "file",
+      content: file.contentText
+        ? Buffer.from(file.contentText, "utf8")
+        : Buffer.from(file.contentBase64 || "", "base64"),
+    }));
   }
-  return normalizeBareUserID(raw);
+  const content = body.contentBase64
+    ? Buffer.from(body.contentBase64, "base64")
+    : Buffer.from(body.contentText || "", "utf8");
+  return [{ fileName: body.fileName || "file", content }];
 }
 
-function httpJSONRequest(method, requestPath, body) {
+function kbMultipartUpload(fileBuffers, fields, pathsArray) {
   return new Promise((resolve, reject) => {
     let parsed;
     try {
-      parsed = new URL(gatewayURL() + requestPath);
+      parsed = new URL(kbBaseURL() + "/documents/batch-upload");
     } catch (err) {
       reject(err);
       return;
     }
+    const boundary = "----Deliverables" + Date.now() + Math.random().toString(36).slice(2);
+    const parts = [];
+
+    for (const file of fileBuffers) {
+      parts.push(
+        Buffer.from(
+          "--" + boundary + "\r\n" +
+          'Content-Disposition: form-data; name="files"; filename="' + file.fileName + '"\r\n' +
+          "Content-Type: application/octet-stream\r\n\r\n",
+        ),
+      );
+      parts.push(file.content);
+      parts.push(Buffer.from("\r\n"));
+    }
+
+    if (Array.isArray(pathsArray) && pathsArray.length > 0) {
+      for (const p of pathsArray) {
+        parts.push(
+          Buffer.from(
+            "--" + boundary + "\r\n" +
+            'Content-Disposition: form-data; name="paths"\r\n\r\n' +
+            (p || "") + "\r\n",
+          ),
+        );
+      }
+    }
+
+    for (const [key, value] of Object.entries(fields || {})) {
+      if (value === undefined || value === null || value === "") {
+        continue;
+      }
+      parts.push(
+        Buffer.from(
+          "--" + boundary + "\r\n" +
+          'Content-Disposition: form-data; name="' + key + '"\r\n\r\n' +
+          String(value) + "\r\n",
+        ),
+      );
+    }
+
+    parts.push(Buffer.from("--" + boundary + "--\r\n"));
+    const body = Buffer.concat(parts);
+
     const isHTTPS = parsed.protocol === "https:";
     const transport = isHTTPS ? https : http;
-    const bodyStr = body ? JSON.stringify(body) : "";
+    const userId = (fields && fields.user_id) || "default";
     const req = transport.request(
       {
         hostname: parsed.hostname,
         port: parsed.port || (isHTTPS ? 443 : 80),
         path: parsed.pathname + (parsed.search || ""),
-        method,
+        method: "POST",
         headers: {
-          "Content-Type": "application/json",
-          "X-API-Key": apiKey(),
-          "Content-Length": Buffer.byteLength(bodyStr),
+          "Content-Type": "multipart/form-data; boundary=" + boundary,
+          "X-User-ID": userId,
+          "X-API-Key": kbApiKey(),
+          "Content-Length": body.length,
         },
       },
       (res) => {
@@ -653,11 +843,15 @@ function httpJSONRequest(method, requestPath, body) {
           try {
             obj = JSON.parse(text);
           } catch (_err) {
-            reject(new Error(`gateway ${res.statusCode}: non-JSON response: ${text.slice(0, 200)}`));
+            reject(new Error(`kb ${res.statusCode}: non-JSON response: ${text.slice(0, 200)}`));
             return;
           }
           if (res.statusCode >= 400) {
-            reject(new Error(`gateway ${res.statusCode}: ${obj.message || text.slice(0, 200)}`));
+            reject(new Error(`kb ${res.statusCode}: ${obj.message || text.slice(0, 200)}`));
+            return;
+          }
+          if (obj.code !== 0 && obj.code !== undefined && res.statusCode !== 206) {
+            reject(new Error(`kb API error: ${obj.message || text.slice(0, 200)}`));
             return;
           }
           resolve(obj);
@@ -665,9 +859,7 @@ function httpJSONRequest(method, requestPath, body) {
       },
     );
     req.on("error", reject);
-    if (bodyStr) {
-      req.write(bodyStr);
-    }
+    req.write(body);
     req.end();
   });
 }
@@ -888,7 +1080,7 @@ function buildReplyMarkdown(opts) {
   if (previewURL) {
     lines.push(`预览链接：[点击预览](${previewURL})`);
   }
-  if (downloadURL) {
+  if (downloadURL && downloadURL !== previewURL) {
     if (isDirectory || deliverableType === "game") {
       lines.push(`文件列表：[查看目录](${downloadURL})`);
     } else {
@@ -922,15 +1114,7 @@ function buildNativeUploadRequestBody(args) {
     }
   }
 
-  const body = {
-    resourceId: trimString(args && args.resource_id),
-    groupId: trimString(args && args.group_id) || trimString(args && args.resource_id),
-    userId:
-      normalizeBareUserID(args && args.user_id) ||
-      userIDFromResourceID(args && args.resource_id) ||
-      userIDFromRelease(deriveReleaseName()),
-    release: deriveReleaseName(),
-  };
+  const body = {};
 
   if (fileCandidate) {
     const stat = safeStat(fileCandidate.path);
@@ -965,9 +1149,9 @@ function buildNativeUploadRequestBody(args) {
     body.files = files;
     return { body, isDirectory: true };
   }
-  const contentText = (args && (args.content_text || args.contentText)) || "";
-  const contentBase64 = (args && (args.content_base64 || args.contentBase64)) || "";
   if (body.type === "link") {
+    const contentText = (args && (args.content_text || args.contentText)) || "";
+    const contentBase64 = (args && (args.content_base64 || args.contentBase64)) || "";
     if (trimString(contentText) || trimString(contentBase64)) {
       body.type = deliverableTypeForPath(body.fileName, false);
     } else if (!isHTTPURLLike(body.fileName)) {
@@ -976,6 +1160,8 @@ function buildNativeUploadRequestBody(args) {
       );
     }
   }
+  const contentText = (args && (args.content_text || args.contentText)) || "";
+  const contentBase64 = (args && (args.content_base64 || args.contentBase64)) || "";
   if (body.type === "pdf" && trimString(contentText) && !trimString(contentBase64)) {
     body.contentBase64 = createBasicTextPDF(contentText, body.fileName).toString("base64");
   } else {
@@ -987,10 +1173,20 @@ function buildNativeUploadRequestBody(args) {
 
 async function uploadDeliverable(args) {
   const { body, isDirectory } = buildNativeUploadRequestBody(args || {});
-  const response = await httpJSONRequest("POST", "/openclaw-gateway/be/deliverables", body);
-  const data = response.data || response;
-  const previewURL = data.previewUrl || `${gatewayPublicURL()}/openclaw-gateway/preview/${data.uuid}`;
-  const downloadURL = data.downloadUrl || previewURL;
+  const userId = payloadUserId(args) || "default";
+  const groupId = payloadGroupId(args) || DEFAULT_GROUP_ID;
+  const groupName = extractStringField(args || {}, ["group_name", "groupName", "group_subject", "groupSubject"]);
+  const uploadPath = kbUploadPath(groupId, groupName);
+  const fileBuffers = buildFileBuffersFromBody(body, isDirectory);
+  const fields = {
+    user_id: userId,
+    group_id: groupId,
+    path: uploadPath,
+  };
+  const response = await kbMultipartUpload(fileBuffers, fields);
+  const documentId = kbExtractDocumentId(response);
+  const previewURL = documentId ? kbPreviewURL(documentId, userId, groupId) : "";
+  const downloadURL = previewURL;
   const replyMarkdown = buildReplyMarkdown({
     previewURL,
     downloadURL,
@@ -998,11 +1194,9 @@ async function uploadDeliverable(args) {
     isDirectory,
   });
   return {
-    uuid: data.uuid,
-    backend: data.backend || "",
+    document_id: documentId,
     download_url: downloadURL,
     preview_url: previewURL,
-    expire_at: data.expireAt,
     reply_markdown: replyMarkdown,
     message: replyMarkdown,
   };
@@ -1032,35 +1226,41 @@ async function uploadCandidate(candidate, body) {
   if (!stat) {
     throw new Error(`file no longer exists: ${candidate.fileName}`);
   }
-  const requestBody = {
-    resourceId,
-    groupId: payloadGroupId(body) || resourceId,
-    userId: normalizeBareUserID(payloadUserId(body)) || userIDFromResourceID(resourceId) || userIDFromRelease(deriveReleaseName()),
-    release: deriveReleaseName(),
-    type: deliverableTypeForPath(candidate.path, stat.isDirectory()),
-    fileName: candidate.fileName || path.basename(candidate.path),
-  };
+
+  const userId = payloadUserId(body) || "default";
+  const groupId = payloadGroupId(body) || DEFAULT_GROUP_ID;
+  const fileName = candidate.fileName || path.basename(candidate.path);
+  const uploadPath = kbUploadPath(groupId, "");
+
+  let fileBuffers;
   if (stat.isDirectory()) {
     const files = collectDirectoryFiles(candidate.path);
     if (files.length === 0) {
       throw new Error(`directory has no uploadable files: ${candidate.fileName}`);
     }
-    requestBody.files = files;
+    fileBuffers = files.map((f) => ({
+      fileName: f.name,
+      content: f.contentText ? Buffer.from(f.contentText, "utf8") : Buffer.from(f.contentBase64 || "", "base64"),
+    }));
   } else {
     if (stat.size > AUTO_UPLOAD_MAX_BYTES) {
       throw new Error(`file exceeds auto-upload limit: ${candidate.fileName}`);
     }
-    requestBody.contentBase64 = fs.readFileSync(candidate.path).toString("base64");
+    fileBuffers = [{ fileName, content: fs.readFileSync(candidate.path) }];
   }
 
-  const response = await httpJSONRequest("POST", "/openclaw-gateway/be/deliverables", requestBody);
-  const data = response.data || response;
-  const previewURL = data.previewUrl || `${gatewayPublicURL()}/openclaw-gateway/preview/${data.uuid}`;
+  const response = await kbMultipartUpload(fileBuffers, {
+    user_id: userId,
+    group_id: groupId,
+    path: uploadPath,
+  });
+  const documentId = kbExtractDocumentId(response);
+  const previewURL = documentId ? kbPreviewURL(documentId, userId, groupId) : "";
   const result = {
-    fileName: requestBody.fileName,
-    uuid: data.uuid,
+    fileName,
+    document_id: documentId,
     previewURL,
-    downloadURL: data.downloadUrl || previewURL,
+    downloadURL: previewURL,
   };
   cache.set(cacheKey, { result, createdAt: Date.now() });
   return result;
@@ -1552,12 +1752,14 @@ function extractDeliverableURL(line) {
   return "";
 }
 
-function configuredGatewayHosts() {
+function configuredKBHosts() {
+  const cfg = loadDeliverableConfig();
   const values = [
-    process.env.CLAW_GATEWAY_PUBLIC_URL,
-    process.env.CLAW_GATEWAY_URL,
-    DEFAULT_GATEWAY_PUBLIC_URL,
-    DEFAULT_GATEWAY_INTERNAL_URL,
+    process.env.KNOWLEDGE_DB_PUBLIC_URL,
+    cfg.kbPublicUrl,
+    process.env.KNOWLEDGE_DB_URL,
+    cfg.kbBaseUrl,
+    DEFAULT_KB_BASE_URL,
   ];
   const hosts = new Set();
   for (const value of values) {
@@ -1585,10 +1787,10 @@ function isTrustedDeliverableURL(rawURL) {
   } catch (_err) {
     return false;
   }
-  if (!DELIVERABLE_GATEWAY_PATH_RE.test(parsed.pathname)) {
+  if (!DELIVERABLE_KB_PATH_RE.test(parsed.pathname)) {
     return false;
   }
-  const hosts = configuredGatewayHosts();
+  const hosts = configuredKBHosts();
   const host = parsed.host.toLowerCase();
   const hostname = parsed.hostname.toLowerCase();
   return hosts.has(host) || hosts.has(hostname);
@@ -1716,17 +1918,11 @@ function extractDeliverableIdentity(rawURL) {
   } catch (_err) {
     return "";
   }
-  if (!DELIVERABLE_GATEWAY_PATH_RE.test(parsed.pathname)) {
+  if (!DELIVERABLE_KB_PATH_RE.test(parsed.pathname)) {
     return "";
   }
-  const parts = parsed.pathname.split("/").filter(Boolean);
-  const uuidRe = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/iu;
-  for (const part of parts) {
-    if (uuidRe.test(part)) {
-      return part.toLowerCase();
-    }
-  }
-  return parsed.href;
+  const docId = parsed.searchParams.get("id");
+  return docId ? String(docId) : "";
 }
 
 function selectPalzFileURL(linkItems) {
@@ -1768,7 +1964,7 @@ function cloneBodyAsFileLink(body, fileUrl, suffix) {
 function cloneBodyAsBlockedDeliverableLink(body) {
   return cloneBody(
     body,
-    "交付物上传未成功，已阻止发送未通过 gateway 交付物系统生成的 OSS 文件链接。请重新通过交付物上传工具上传后再发送。",
+    "交付物上传未成功，已阻止发送未通过知识库交付物系统生成的文件链接。请重新通过交付物上传工具上传后再发送。",
     "",
   );
 }
@@ -1972,6 +2168,7 @@ const plugin = {
 
     api.on("before_tool_call", async (event) => {
       if (isDeliverablesUploadTool(event.toolName)) {
+        enrichDeliverableGroupContext(event);
         cacheUploadSummary(event.params);
         return;
       }
@@ -2009,15 +2206,21 @@ const plugin = {
 };
 
 plugin.__test = {
+  buildFileBuffersFromBody,
   buildNativeUploadRequestBody,
   createBasicTextPDF,
   deliverableTypeForPath,
-  extractFileReferencesFromText,
   extractDeliverableURL,
+  extractFileReferencesFromText,
   findUntrustedOSSDeliverableURL,
   isDeliverableLinkLine,
   isOSSLikeURL,
   isTrustedDeliverableURL,
+  kbExtractDocumentId,
+  kbMultipartUpload,
+  kbPreviewURL,
+  kbUploadPath,
+  loadDeliverableConfig,
   selectPalzFileURL,
   splitDeliverableMessage,
 };

package/openclaw-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "plugin-deliverables",
-  "version": "1.1.1",
+  "version": "1.1.5",
   "npm_package": "@dai_ming/plugin-deliverables",
   "description": "Deliverables plugin: native upload tool + skill + AGENTS rules for AI-generated file uploads",
   "skills": {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "plugin-deliverables",
   "name": "Deliverables",
   "description": "Deliverables runtime guard for upload-first file delivery with Palz split-send diagnostics.",
-  "version": "1.1.1",
+  "version": "1.1.5",
   "skills": ["./skills"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dai_ming/plugin-deliverables",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "OpenClaw deliverables native plugin — upload AI-generated files to OSS and return shareable preview/download links",
   "keywords": [
     "openclaw",
@@ -15,6 +15,7 @@
   "files": [
     "INSTALL.md",
     "index.js",
+    "deliverables.*.config.json",
     "openclaw.plugin.json",
     "openclaw-plugin.json",
     "skills/",

package/skills/deliverables/SKILL.md

@@ -22,21 +22,23 @@ description: 上传AI生成的文件到交付物系统，返回可分享的预
 - 如果你使用 `write` 工具创建交付物文件，目标路径必须在 `output/` 下。
 - 如果你已经误写到工作区根目录，必须先移动或复制到 `output/`，再继续上传交付物并向用户汇报。
 
-## 调用前必须准备的参数（全部必填）
+## 调用前必须准备的参数
 
 从当前会话上下文提取以下值，**调用时一次性填完，不要留空**：
 
-| 参数 | 取值来源 | 示例 |
-|------|---------|------|
-| `resource_id` | 消息元数据中的 `resource_id` 字段 | `user_xxx_lobster_yyy` |
-| `group_id` | 消息元数据中的 `group_id` 或 `conversation_id` | `group_abc123` |
-| `user_id` | 消息元数据中的 `sender_id` 或 `owner_id` | `cbb0fab9...` |
-| `type` | 根据内容选择：`article`/`game`/`image`/`video`/`ppt`/`pdf`/`zip`；`link` 仅用于外部 `http(s)` URL | `article` |
-| `file_name` | 有意义的文件名，单文件必须含扩展名；若用户未指定文档格式，默认用 `.md` | `report-2026.html` |
-| `content_text` | 文件的完整文本内容（HTML/Markdown等） | `<html>...</html>` |
-| `file_path` | PDF/PPT/图片/zip 等二进制文件的本地路径，推荐使用，避免手工复制 base64 | `output/sample.pdf` |
-
-> **直接对话（direct chat）时**：`group_id` 填 `conversation_id`，`user_id` 填 `owner_id`。
+| 参数 | 必填 | 取值来源 | 示例 |
+|------|------|---------|------|
+| `user_id` | **是（必传）** | 单聊取 `owner_id`，群聊取 `sender_id`。**不可省略**，否则 KB 上传报错 13002 | `cbb0fab9...` |
+| `group_id` | 群聊时必填 | 群聊取消息元数据中的 `group_id`；**单聊不传**（自动为 `default`） | `grp_43c75713` |
+| `group_name` | 群聊时必填 | 群聊取消息元数据中的群聊名称；**单聊不传** | `项目讨论群` |
+| `type` | 是 | 根据内容选择：`article`/`game`/`image`/`video`/`ppt`/`pdf`/`zip`；`link` 仅用于外部 `http(s)` URL | `article` |
+| `file_name` | 是 | 有意义的文件名，单文件必须含扩展名；若用户未指定文档格式，默认用 `.md` | `report-2026.html` |
+| `content_text` | 按需 | 文件的完整文本内容（HTML/Markdown等） | `<html>...</html>` |
+| `file_path` | 按需 | PDF/PPT/图片/zip 等二进制文件的本地路径，推荐使用，避免手工复制 base64 | `output/sample.pdf` |
+
+> **单聊（direct chat）**：`user_id` 填 `owner_id`，不传 `group_id` 和 `group_name`。
+> **群聊（group chat）**：`user_id` 填 `sender_id`，`group_id` 和 `group_name` 从群聊元数据获取。
+> **⚠ 警告**：`user_id` 必须传入真实值。当 `group_id` 是真实群 ID 但 `user_id` 缺失或为 `"default"` 时，KB 后端会返回 `500: 用户不存在`。
 
 ## 二进制文件上传（强制）