@dai_ming/plugin-deliverables 1.2.3 → 1.2.5

package/agents-rules/deliverables.md

@@ -81,10 +81,9 @@ 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` 的场景下。
+25. 调用上传工具时，MUST 原样传入会话元数据：`conversation_type`（`"direct"` 或 `"group"`）、`conversation_id`、`owner_id`、`sender_id`、`lobster_id`、`lobster_name`，照消息元数据/会话上下文填，不要自己加工。这些都是必填。插件会据此推导 `user_id` 与 `group_id`（单聊 → `owner_id` + 个人文件夹；群聊 → `sender_id` + 群）。
+26. 群聊场景额外传 `group_id` 和 `group_name`（取自消息元数据）；单聊不传。
+27. 不要把单聊的 `conversation_id` 当 `group_id` 传——单聊请把 `group_id` 留空或传 `"default"`，否则 KB 会因"用户不在群内"上传失败。
 
 ### Exception
 

package/deliverables.dev.config.json

@@ -1,3 +1,4 @@
 {
-  "kbBaseUrl": "http://knowledge-db:8080/api/v1"
+  "kbBaseUrl": "http://knowledge-db:8080/api/v1",
+  "engineBaseUrl": "http://uniclaw-kb-engine:8070/uniclaw-kb-engine/api/v1"
 }

package/deliverables.prod.config.json

@@ -1,3 +1,4 @@
 {
-  "kbBaseUrl": "http://knowledge-db:8080/api/v1"
+  "kbBaseUrl": "http://knowledge-db:8080/api/v1",
+  "engineBaseUrl": "http://uniclaw-kb-engine:8070/uniclaw-kb-engine/api/v1"
 }

package/deliverables.staging.config.json

@@ -1,3 +1,4 @@
 {
-  "kbBaseUrl": "http://knowledge-db:8080/api/v1"
+  "kbBaseUrl": "http://knowledge-db:8080/api/v1",
+  "engineBaseUrl": "http://uniclaw-kb-engine:8070/uniclaw-kb-engine/api/v1"
 }

package/index.js

@@ -12,9 +12,10 @@ const UPLOAD_CACHE_KEY = "__plugin_deliverables_upload_cache__";
 const SUMMARY_CACHE_LIMIT = 200;
 const SHORT_SUMMARY_THRESHOLD = 120;
 const DEFAULT_KB_BASE_URL = "http://knowledge-db:8080/api/v1";
-const DEFAULT_KB_API_KEY = "kb-agent-key-2025";
+// Deliverables now go through the kb-engine (classification + path building +
+// async move) instead of calling ai-kb's batch-upload directly.
+const DEFAULT_ENGINE_BASE_URL = "http://uniclaw-kb-engine:8070/uniclaw-kb-engine/api/v1";
 const DEFAULT_GROUP_ID = "default";
-const DEFAULT_GROUP_NAME = "我的文件夹";
 const DEFAULT_DELIVERABLES_CONFIG_FILENAME = "deliverables.config.json";
 let _cachedDeliverableConfig = null;
 
@@ -125,8 +126,8 @@ const RUNTIME_DELIVERABLES_GUIDANCE = [
   "- 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.",
+  "- CRITICAL: Pass the raw conversation metadata to `deliverables__upload_deliverable` verbatim — `conversation_type` (\"direct\" or \"group\"), `conversation_id`, `owner_id`, `sender_id`, `lobster_id`, and `lobster_name` — exactly as they appear in the conversation context/message metadata. These are all required. The plugin derives `user_id` and `group_id` from them (direct → owner_id + personal folder; group → sender_id + the group), so you do NOT pick those yourself. In group chats you MUST also pass `group_id` and `group_name`. Never pass a single-chat `conversation_id` as `group_id` — it causes a KB upload failure (user is not a member of group).",
+  "- `lobster_name` is the deliverable's first-level isolation directory (keeps different agents' deliverables separated). Use the real `lobster_name` from conversation context/message metadata when present; do not invent one or fall back to release/resource ids.",
 ].join("\n");
 
 const UPLOAD_DELIVERABLE_TOOL = {
@@ -139,21 +140,33 @@ const UPLOAD_DELIVERABLE_TOOL = {
   inputSchema: {
     type: "object",
     properties: {
-      resource_id: {
+      conversation_type: {
         type: "string",
-        description: "当前聊天框/会话的唯一 ID，用于缓存去重。",
+        description: "会话类型，从消息元数据 conversation_type 获取：单聊为 'direct'，群聊为 'group'。决定 user_id 取值与是否按群归档。",
       },
-      user_id: {
+      conversation_id: {
         type: "string",
-        description: "上传者用户 ID。单聊取 owner_id，群聊取 sender_id。",
+        description: "会话 ID，从消息元数据 conversation_id 获取。群聊时作为 group_id 兜底；并用于缓存去重。",
       },
       owner_id: {
         type: "string",
-        description: "等同于 user_id，从消息元数据 owner_id 字段获取。两者任传其一即可。",
+        description: "会话归属用户 ID，从消息元数据 owner_id 获取。单聊上传者即 owner_id。",
+      },
+      sender_id: {
+        type: "string",
+        description: "消息发送者 ID，从消息元数据 sender_id 获取。群聊上传者即 sender_id。",
+      },
+      lobster_name: {
+        type: "string",
+        description: "产出该交付物的 agent 显示名，从会话上下文/消息元数据 lobster_name 获取；作为交付物的一级隔离目录。必填。",
+      },
+      lobster_id: {
+        type: "string",
+        description: "agent 稳定 ID，从消息元数据 lobster_id 获取。随交付物记录，预留按 ID 隔离。",
       },
       group_id: {
         type: "string",
-        description: "分组 ID。单聊不传或传 'default'；群聊传群 ID。",
+        description: "分组 ID。单聊不传或传 'default'；群聊传群 ID（不传则用 conversation_id 兜底）。",
       },
       group_name: {
         type: "string",
@@ -194,7 +207,16 @@ const UPLOAD_DELIVERABLE_TOOL = {
         },
       },
     },
-    required: ["type", "file_name"],
+    required: [
+      "type",
+      "file_name",
+      "conversation_type",
+      "conversation_id",
+      "owner_id",
+      "sender_id",
+      "lobster_name",
+      "lobster_id",
+    ],
   },
 };
 
@@ -285,23 +307,37 @@ function deliverableTypeForPath(filePath, isDirectory) {
   return "article";
 }
 
+function openclawRoot() {
+  return path.resolve(__dirname, "..", "..");
+}
+
+function workspaceTenantBases() {
+  return [
+    "/data/tenants",
+    process.env.OPENCLAW_HOME,
+    process.env.HOME ? path.join(process.env.HOME, ".openclaw") : "",
+    openclawRoot(),
+  ].filter((base, index, all) => base && all.indexOf(base) === index);
+}
+
+function isPathUnderTenantWorkspace(normalizedPath, normalizedBase) {
+  if (normalizedPath.indexOf(normalizedBase + "/") !== 0) {
+    return false;
+  }
+  const relative = normalizedPath.slice(normalizedBase.length + 1);
+  const parts = relative.split("/").filter(Boolean);
+  return parts.length >= 2 && parts[1].indexOf("workspace-") === 0;
+}
+
 function isAllowedWorkspacePath(candidatePath) {
   const normalized = normalizeSlash(path.resolve(candidatePath));
-  // 老布局：根目录直接挂 workspace（保持向后兼容）。
-  if (
-    normalized.indexOf("/data/workspace-") === 0 ||
-    normalized.indexOf("/home/node/.openclaw/workspace") === 0
-  ) {
-    return true;
-  }
-  const openclawRoot = normalizeSlash(path.resolve(__dirname, "..", ".."));
-  if (normalized.indexOf(openclawRoot + "/workspace") === 0) {
-    return true;
+  for (const base of workspaceTenantBases()) {
+    const normalizedBase = normalizeSlash(path.resolve(base));
+    if (isPathUnderTenantWorkspace(normalized, normalizedBase)) {
+      return true;
+    }
   }
-  // 新布局（多租户）及通用情况：绝对路径中任意位置含有 `xxx/workspace-*`
-  // 目录段都允许，覆盖 /data/tenants/<user>/workspace-<lobster>、
-  // /home/node/.openclaw/<user>/workspace-<lobster> 等。
-  return /\/workspace-[^/]+(?:\/|$)/.test(normalized);
+  return false;
 }
 
 function shouldIgnorePath(candidatePath) {
@@ -325,28 +361,7 @@ async function safeStat(candidatePath) {
 
 async function workspaceRoots() {
   const roots = [];
-  for (const root of ["/home/node/.openclaw/workspace-main", "/home/node/.openclaw/workspace"]) {
-    if (await safeStat(root)) {
-      roots.push(root);
-    }
-  }
-  try {
-    for (const entry of await fs.promises.readdir("/data")) {
-      if (!entry || entry.indexOf("workspace-") !== 0) {
-        continue;
-      }
-      const root = path.join("/data", entry);
-      if (await safeStat(root)) {
-        roots.push(root);
-      }
-    }
-  } catch (_err) {
-    // /data is not guaranteed in non-pod test environments.
-  }
-  // 多租户布局：枚举 <base>/<tenant-or-user>/workspace-* 下的 workspace 根目录，
-  // 覆盖 /data/tenants/<user>/workspace-<lobster>、
-  // /home/node/.openclaw/<user>/workspace-<lobster> 等。
-  for (const base of ["/data/tenants", "/home/node/.openclaw"]) {
+  for (const base of workspaceTenantBases()) {
     let tenants;
     try {
       tenants = await fs.promises.readdir(base);
@@ -369,26 +384,13 @@ async function workspaceRoots() {
           continue;
         }
         const root = path.join(tenantDir, child);
-        if ((await safeStat(root)) && roots.indexOf(root) === -1) {
+        const stat = await safeStat(root);
+        if (stat && stat.isDirectory() && roots.indexOf(root) === -1) {
           roots.push(root);
         }
       }
     }
   }
-  const openclawRoot = path.resolve(__dirname, "..", "..");
-  try {
-    for (const entry of await fs.promises.readdir(openclawRoot)) {
-      if (!entry || entry.indexOf("workspace") !== 0) {
-        continue;
-      }
-      const root = path.join(openclawRoot, entry);
-      if ((await safeStat(root)) && roots.indexOf(root) === -1) {
-        roots.push(root);
-      }
-    }
-  } catch (_err) {
-    // local dev path may not exist
-  }
   return roots;
 }
 
@@ -566,7 +568,22 @@ async function collectDirectoryFiles(dirPath) {
     }
   }
   await scan(dirPath, AUTO_UPLOAD_SCAN_DEPTH);
-  return files;
+  return sortDeliverableFiles(files);
+}
+
+function deliverableFileSortKey(file) {
+  const name = normalizeSlash(file && file.name ? file.name : "").toLowerCase();
+  if (name === "index.html" || name === "index.htm") {
+    return "0:" + name;
+  }
+  if (path.basename(name) === "index.html" || path.basename(name) === "index.htm") {
+    return "1:" + name;
+  }
+  return "2:" + name;
+}
+
+function sortDeliverableFiles(files) {
+  return (files || []).slice().sort((a, b) => deliverableFileSortKey(a).localeCompare(deliverableFileSortKey(b)));
 }
 
 function extractStringField(obj, keys) {
@@ -603,8 +620,25 @@ function extractContextString(event, keys) {
   return "";
 }
 
-function payloadResourceId(body) {
-  return extractStringField(body, ["resource_id", "resourceId", "conversation_id", "conversationId"]);
+// payloadConversationID is the per-conversation key used for cache dedup and for
+// correlating the upload-tool-call event with the later message-send event
+// (replaces the old resource_id). conversation_id is present in both contexts.
+function payloadConversationID(body) {
+  return extractStringField(body, ["conversation_id", "conversationId", "resource_id", "resourceId"]);
+}
+
+// isGroupChat reports whether the context is a group chat, keyed on
+// conversation_type (the authoritative field the runtime actually sends —
+// "direct" / "group", matching the engine). Only in a group chat is a
+// conversation_id a meaningful group_id; in a direct chat it is a per-user
+// session id (conv_<user>_<lobster>) that is NOT a group and must never be used
+// as group_id (ai-kb would reject it with "user is not a member of group").
+// Absent conversation_type, default to direct (single chat) — the safe choice.
+function isGroupChat(obj) {
+  if (!obj || typeof obj !== "object") {
+    return false;
+  }
+  return extractStringField(obj, ["conversation_type", "conversationType"]).toLowerCase() === "group";
 }
 
 function payloadGroupId(body) {
@@ -612,7 +646,12 @@ function payloadGroupId(body) {
   if (explicit) {
     return explicit;
   }
-  const fallback = extractStringField(body, ["resource_id", "resourceId", "conversation_id", "conversationId"]);
+  // Only fall back to the conversation id as a group id in a group chat; a direct
+  // chat must stay empty (-> engine treats it as the personal "我的文件夹" root).
+  if (!isGroupChat(body)) {
+    return "";
+  }
+  const fallback = extractStringField(body, ["conversation_id", "conversationId"]);
   return fallback && fallback !== "default" ? fallback : "";
 }
 
@@ -620,73 +659,76 @@ 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;
+  // Populate the raw routing fields from the message context when the agent did
+  // not pass them. group_id / user_id are then DERIVED from these at request time
+  // (payloadGroupId / payloadUserId), so we do not need to compute them here.
+  const rawFields = [
+    ["conversation_type", ["conversation_type", "conversationType"]],
+    ["conversation_id", ["conversation_id", "conversationId"]],
+    ["owner_id", ["owner_id", "ownerId"]],
+    ["sender_id", ["sender_id", "senderId"]],
+    ["group_id", ["group_id", "groupId"]],
+  ];
+  for (const [target, keys] of rawFields) {
+    if (trimString(event.params[target])) {
+      continue;
+    }
+    const inferred = extractContextString(event, keys);
+    if (inferred) {
+      event.params[target] = inferred;
     }
   }
   const existingGroupName = trimString(event.params.group_name);
   if (!existingGroupName) {
     const inferredGroupName = extractContextString(event, [
-      "group_name", "groupName", "group_subject", "groupSubject",
+      "group_name", "groupName",
     ]);
     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",
+  // lobster_name is the deliverable's first-level isolation dir. Prefer the real
+  // value from params/context/metadata; do NOT fall back to release/resource ids —
+  // those yield wrong, unreadable directory names. A still-missing value is
+  // rejected by the engine, which is the correct signal.
+  const existingLobsterName = trimString(event.params.lobster_name);
+  if (!existingLobsterName) {
+    const inferredLobsterName = extractContextString(event, [
+      "lobster_name", "lobsterName", "agent_name", "agentName",
+    ]);
+    if (inferredLobsterName) {
+      event.params.lobster_name = inferredLobsterName;
+    }
+  }
+  const existingLobsterId = trimString(event.params.lobster_id);
+  if (!existingLobsterId) {
+    const inferredLobsterId = extractContextString(event, [
+      "lobster_id", "lobsterId", "agent_id", "agentId",
     ]);
-    if (inferredUserId && inferredUserId !== "default") {
-      event.params.user_id = inferredUserId;
+    if (inferredLobsterId) {
+      event.params.lobster_id = inferredLobsterId;
     }
   }
 }
 
+// payloadUserId resolves the uploader id from conversation_type — direct chats
+// upload as owner_id, group chats as sender_id (matching the deliverables
+// guidance). Upstream never sends a `user_id`; it is always derived here. Each
+// branch falls back to the other id so a partially-populated payload still
+// resolves something.
 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 (isGroupChat(body)) {
+    return extractStringField(body, ["sender_id", "senderId", "owner_id", "ownerId"]);
   }
-  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);
+  return extractStringField(body, ["owner_id", "ownerId", "sender_id", "senderId"]);
 }
 
-function userIDFromResourceID(resourceID) {
-  const raw = trimString(resourceID);
-  if (raw.indexOf("user_") !== 0 && raw.indexOf("user-") !== 0) {
-    return "";
-  }
-  return normalizeBareUserID(raw);
+function payloadLobsterName(body) {
+  return extractStringField(body, ["lobster_name", "lobsterName", "agent_name", "agentName"]);
 }
 
-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 payloadLobsterId(body) {
+  return extractStringField(body, ["lobster_id", "lobsterId", "agent_id", "agentId"]);
 }
 
 function isWriteTool(toolName) {
@@ -719,25 +761,25 @@ function rememberPendingFile(event) {
   }
   const store = getPendingFileStore();
   pruneTimedMap(store, AUTO_UPLOAD_TTL_MS);
-  const resourceId = extractContextString(event, ["resource_id", "resourceId", "conversation_id", "conversationId"]);
-  const key = `${resourceId || "unknown"}:${writePath}`;
+  const conversationId = extractContextString(event, ["conversation_id", "conversationId", "resource_id", "resourceId"]);
+  const key = `${conversationId || "unknown"}:${writePath}`;
   store.set(key, {
     path: writePath,
-    resourceId,
+    conversationId,
     createdAt: Date.now(),
   });
 }
 
 async function pendingCandidatesForPayload(body) {
-  const resourceId = payloadResourceId(body);
-  if (!resourceId) {
+  const conversationId = payloadConversationID(body);
+  if (!conversationId) {
     return [];
   }
   const store = getPendingFileStore();
   pruneTimedMap(store, AUTO_UPLOAD_TTL_MS);
   const out = [];
   for (const entry of store.values()) {
-    if (!entry || entry.resourceId !== resourceId) {
+    if (!entry || entry.conversationId !== conversationId) {
       continue;
     }
     const ref = { raw: entry.path, value: entry.path, kind: "pending" };
@@ -749,97 +791,14 @@ async function pendingCandidatesForPayload(body) {
   return out;
 }
 
-function kbBaseURL() {
+function engineBaseURL() {
   const cfg = loadDeliverableConfig();
-  return (process.env.KNOWLEDGE_DB_URL || cfg.kbBaseUrl || DEFAULT_KB_BASE_URL).replace(/\/$/, "");
-}
-
-function kbApiKey() {
-  return process.env.KNOWLEDGE_DB_API_KEY || DEFAULT_KB_API_KEY;
-}
-
-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 kbUploadItems(response) {
-  const data = (response && response.data) || response || {};
-  return Array.isArray(data.items) ? data.items : [];
-}
-
-function kbFirstSuccessfulUploadItem(response) {
-  const items = kbUploadItems(response);
-  if (items.length === 0) {
-    return null;
-  }
-  return items.find((item) => item && !item.error && item.document) || items[0] || null;
-}
-
-function kbExtractDocument(response) {
-  const item = kbFirstSuccessfulUploadItem(response);
-  if (item && item.document && typeof item.document === "object" && !Array.isArray(item.document)) {
-    return item.document;
-  }
-  const data = (response && response.data) || response || {};
-  if (data.document && typeof data.document === "object" && !Array.isArray(data.document)) {
-    return data.document;
-  }
-  return data && typeof data === "object" && !Array.isArray(data) ? data : {};
-}
-
-function kbExtractDocumentId(response) {
-  const document = kbExtractDocument(response);
-  if (document.id !== undefined) {
-    return document.id;
-  }
-  const data = (response && response.data) || response || {};
-  if (data.id !== undefined) {
-    return data.id;
-  }
-  return null;
-}
-
-function extractURLField(obj, keys) {
-  if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
-    return "";
-  }
-  for (const key of keys) {
-    const value = obj[key];
-    if (isString(value) && value.trim()) {
-      return value.trim();
-    }
-  }
-  return "";
-}
-
-function kbExtractReturnedLinks(response) {
-  const item = kbFirstSuccessfulUploadItem(response) || {};
-  const document = kbExtractDocument(response);
-  return {
-    downloadURL:
-      extractURLField(document, ["download_url", "downloadURL"]) ||
-      extractURLField(item, ["download_url", "downloadURL"]),
-    previewURL:
-      extractURLField(document, ["preview_url", "previewURL"]) ||
-      extractURLField(item, ["preview_url", "previewURL"]),
-  };
-}
-
-function requireKBReturnedLink(response) {
-  const links = kbExtractReturnedLinks(response);
-  if (!links.previewURL && !links.downloadURL) {
-    throw new Error("kb upload response missing preview_url/download_url");
-  }
-  return links;
+  return (process.env.UNICLAW_KB_ENGINE_URL || cfg.engineBaseUrl || DEFAULT_ENGINE_BASE_URL).replace(/\/$/, "");
 }
 
 function buildFileBuffersFromBody(body, isDirectory) {
   if (isDirectory && Array.isArray(body.files)) {
-    return body.files.map((file) => ({
+    return sortDeliverableFiles(body.files).map((file) => ({
       fileName: file.name || "file",
       content: file.contentText
         ? Buffer.from(file.contentText, "utf8")
@@ -852,11 +811,29 @@ function buildFileBuffersFromBody(body, isDirectory) {
   return [{ fileName: body.fileName || "file", content }];
 }
 
-function kbMultipartUpload(fileBuffers, fields, pathsArray) {
+function multipartEscape(value) {
+  return String(value || "")
+    .replace(/\\/g, "\\\\")
+    .replace(/"/g, '\\"')
+    .replace(/\r/g, "")
+    .replace(/\n/g, "");
+}
+
+function multipartLeafName(value) {
+  const normalized = String(value || "file").replace(/\\/g, "/");
+  const leaf = path.basename(normalized) || "file";
+  return multipartEscape(leaf);
+}
+
+// engineDeliverableUpload posts a deliverable to the kb-engine sync endpoint
+// (multipart: a `payload` JSON field + repeated `files` parts). The engine
+// uploads to the agent root, returns preview/download links immediately, and
+// classifies + moves the file asynchronously. fileBuffers is [{fileName, content:Buffer}].
+function engineDeliverableUpload(fileBuffers, payload) {
   return new Promise((resolve, reject) => {
     let parsed;
     try {
-      parsed = new URL(kbBaseURL() + "/documents/batch-upload");
+      parsed = new URL(engineBaseURL() + "/deliverables");
     } catch (err) {
       reject(err);
       return;
@@ -864,49 +841,41 @@ function kbMultipartUpload(fileBuffers, fields, pathsArray) {
     const boundary = "----Deliverables" + Date.now() + Math.random().toString(36).slice(2);
     const parts = [];
 
+    // payload JSON field
+    parts.push(
+      Buffer.from(
+        "--" + boundary + "\r\n" +
+        'Content-Disposition: form-data; name="payload"\r\n\r\n' +
+        JSON.stringify(payload) + "\r\n",
+      ),
+    );
+
     for (const file of fileBuffers) {
+      // Strip CR/LF from the relative path so a newline in a file name cannot
+      // inject extra multipart parts; the leaf filename is escaped separately.
+      const relativePath = String(file.fileName || "file").replace(/\\/g, "/").replace(/[\r\n]/g, "");
       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",
+          'Content-Disposition: form-data; name="relative_paths"\r\n\r\n' +
+          relativePath + "\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",
+          'Content-Disposition: form-data; name="files"; filename="' + multipartLeafName(file.fileName) + '"\r\n' +
+          "Content-Type: application/octet-stream\r\n\r\n",
         ),
       );
+      parts.push(file.content);
+      parts.push(Buffer.from("\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 userId = (fields && fields.user_id) || "default";
     const req = transport.request(
       {
         hostname: parsed.hostname,
@@ -915,11 +884,9 @@ function kbMultipartUpload(fileBuffers, fields, pathsArray) {
         method: "POST",
         headers: {
           "Content-Type": "multipart/form-data; boundary=" + boundary,
-          "X-User-ID": userId,
-          "X-API-Key": kbApiKey(),
           "Content-Length": body.length,
         },
-        timeout: 30000,
+        timeout: 60000,
       },
       (res) => {
         const chunks = [];
@@ -930,23 +897,25 @@ function kbMultipartUpload(fileBuffers, fields, pathsArray) {
           try {
             obj = JSON.parse(text);
           } catch (_err) {
-            reject(new Error(`kb ${res.statusCode}: non-JSON response: ${text.slice(0, 200)}`));
+            reject(new Error(`engine ${res.statusCode}: non-JSON response: ${text.slice(0, 200)}`));
             return;
           }
           if (res.statusCode >= 400) {
-            reject(new Error(`kb ${res.statusCode}: ${obj.message || text.slice(0, 200)}`));
+            reject(new Error(`engine ${res.statusCode}: ${obj.err_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)}`));
+          // Unified engine envelope: {code, err_message, data}. code != 0 is a
+          // business error.
+          if (obj.code !== 0 && obj.code !== undefined) {
+            reject(new Error(`engine error: ${obj.err_message || text.slice(0, 200)}`));
             return;
           }
-          resolve(obj);
+          resolve(obj.data || obj);
         });
       },
     );
     req.on("timeout", () => {
-      req.destroy(new Error("kb upload timeout after 30s"));
+      req.destroy(new Error("engine upload timeout after 60s"));
     });
     req.on("error", reject);
     req.write(body);
@@ -1263,21 +1232,34 @@ async function buildNativeUploadRequestBody(args) {
 
 async function uploadDeliverable(args) {
   const { body, isDirectory } = await buildNativeUploadRequestBody(args || {});
+  const conversationType = extractStringField(args || {}, ["conversation_type", "conversationType"]);
   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 groupName = extractStringField(args || {}, ["group_name", "groupName"]);
+  // lobster_name must be the real context value (or the agent-supplied same
+  // value); no release/resource-id fallback. If still missing, engine rejects it.
+  const lobsterName = payloadLobsterName(args);
+  const lobsterId = payloadLobsterId(args);
   const fileBuffers = buildFileBuffersFromBody(body, isDirectory);
-  const fields = {
+  // The engine builds the storage path and classifies — the plugin only supplies
+  // the necessary parameters. content_text (single text file) is a classification
+  // hint so the async classifier can pick a topic without re-reading the file.
+  const payload = {
     user_id: userId,
+    conversation_type: conversationType,
+    lobster_name: lobsterName,
+    lobster_id: lobsterId,
     group_id: groupId,
-    path: uploadPath,
+    group_name: groupName,
+    deliverable_type: body.type || "",
+    content_text: !isDirectory && isString(body.contentText) ? body.contentText : "",
   };
-  const response = await kbMultipartUpload(fileBuffers, fields);
-  const documentId = kbExtractDocumentId(response);
-  const links = requireKBReturnedLink(response);
-  const previewURL = links.previewURL || links.downloadURL;
-  const downloadURL = links.downloadURL || previewURL;
+  const data = await engineDeliverableUpload(fileBuffers, payload);
+  const previewURL = data.preview_url || data.download_url || "";
+  const downloadURL = data.download_url || previewURL;
+  if (!previewURL && !downloadURL) {
+    throw new Error("engine upload response missing preview_url/download_url");
+  }
   const replyMarkdown = buildReplyMarkdown({
     previewURL,
     downloadURL,
@@ -1285,9 +1267,11 @@ async function uploadDeliverable(args) {
     isDirectory,
   });
   return {
-    document_id: documentId,
+    document_id: data.document_id,
     download_url: downloadURL,
     preview_url: previewURL,
+    category: data.category || "",
+    classify_task_id: data.classify_task_id || "",
     reply_markdown: replyMarkdown,
     message: replyMarkdown,
   };
@@ -1299,15 +1283,15 @@ function nativeToolResult(result) {
   };
 }
 
-function uploadCacheKey(candidate, resourceId) {
-  return `${resourceId || ""}:${candidate.path}:${candidate.mtimeMs || 0}:${candidate.size || 0}`;
+function uploadCacheKey(candidate, conversationId) {
+  return `${conversationId || ""}:${candidate.path}:${candidate.mtimeMs || 0}:${candidate.size || 0}`;
 }
 
 async function uploadCandidate(candidate, body) {
-  const resourceId = payloadResourceId(body);
+  const conversationId = payloadConversationID(body);
   const cache = getUploadCache();
   pruneTimedMap(cache, AUTO_UPLOAD_TTL_MS);
-  const cacheKey = uploadCacheKey(candidate, resourceId);
+  const cacheKey = uploadCacheKey(candidate, conversationId);
   const cached = cache.get(cacheKey);
   if (cached && cached.result) {
     return cached.result;
@@ -1319,12 +1303,19 @@ async function uploadCandidate(candidate, body) {
   }
 
   const userId = payloadUserId(body) || "default";
+  const conversationType = extractStringField(body || {}, ["conversation_type", "conversationType"]);
   const groupId = payloadGroupId(body) || DEFAULT_GROUP_ID;
+  const groupName = extractStringField(body || {}, ["group_name", "groupName"]);
+  // Auto-upload normally sees lobster_name on the outbound message body. If it is
+  // absent, fall back only to lobster_id (a real, stable metadata field), never to
+  // release/resource-derived names.
+  const lobsterId = payloadLobsterId(body);
+  const lobsterName = payloadLobsterName(body) || lobsterId;
   const fileName = candidate.fileName || path.basename(candidate.path);
-  const uploadPath = kbUploadPath(groupId, "");
+  const isDirectory = stat.isDirectory();
 
   let fileBuffers;
-  if (stat.isDirectory()) {
+  if (isDirectory) {
     const files = await collectDirectoryFiles(candidate.path);
     if (files.length === 0) {
       throw new Error(`directory has no uploadable files: ${candidate.fileName}`);
@@ -1340,18 +1331,24 @@ async function uploadCandidate(candidate, body) {
     fileBuffers = [{ fileName, content: await fs.promises.readFile(candidate.path) }];
   }
 
-  const response = await kbMultipartUpload(fileBuffers, {
+  const data = await engineDeliverableUpload(fileBuffers, {
     user_id: userId,
+    conversation_type: conversationType,
+    lobster_name: lobsterName,
+    lobster_id: lobsterId,
     group_id: groupId,
-    path: uploadPath,
+    group_name: groupName,
+    deliverable_type: deliverableTypeForPath(candidate.path, isDirectory),
+    content_text: "",
   });
-  const documentId = kbExtractDocumentId(response);
-  const links = requireKBReturnedLink(response);
-  const previewURL = links.previewURL || links.downloadURL;
-  const downloadURL = links.downloadURL || previewURL;
+  const previewURL = data.preview_url || data.download_url || "";
+  const downloadURL = data.download_url || previewURL;
+  if (!previewURL && !downloadURL) {
+    throw new Error("engine upload response missing preview_url/download_url");
+  }
   const result = {
     fileName,
-    document_id: documentId,
+    document_id: data.document_id,
     previewURL,
     downloadURL,
   };
@@ -1781,8 +1778,8 @@ function buildSummaryFromUploadParams(params) {
 }
 
 function cacheUploadSummary(params) {
-  const resourceId = isString(params && params.resource_id) ? params.resource_id.trim() : "";
-  if (!resourceId) {
+  const conversationId = payloadConversationID(params || {});
+  if (!conversationId) {
     return;
   }
   const summary = buildSummaryFromUploadParams(params);
@@ -1790,7 +1787,7 @@ function cacheUploadSummary(params) {
     return;
   }
   const cache = getSummaryCache();
-  cache.set(resourceId, {
+  cache.set(conversationId, {
     summary,
     createdAt: Date.now(),
   });
@@ -2151,7 +2148,7 @@ function shouldSplitPalzPayload(body) {
     return null;
   }
 
-  const cachedSummary = takeCachedSummary(body.resource_id);
+  const cachedSummary = takeCachedSummary(payloadConversationID(body));
   if (cachedSummary && isSummaryTooShort(split.summary)) {
     return {
       summary: cachedSummary,
@@ -2408,12 +2405,13 @@ plugin.__test = {
   isDeliverableLinkLine,
   isOSSLikeURL,
   isTrustedDeliverableURL,
-  kbExtractDocumentId,
-  kbExtractReturnedLinks,
-  kbMultipartUpload,
-  kbUploadPath,
+  isGroupChat,
+  payloadUserId,
+  payloadGroupId,
+  payloadConversationID,
+  engineDeliverableUpload,
+  enrichDeliverableGroupContext,
   loadDeliverableConfig,
-  requireKBReturnedLink,
   selectPalzFileURL,
   splitDeliverableMessage,
 };

package/openclaw-plugin.json

@@ -1,11 +1,14 @@
 {
   "name": "plugin-deliverables",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "npm_package": "@dai_ming/plugin-deliverables",
   "description": "Deliverables plugin: native upload tool + skill + AGENTS rules for AI-generated file uploads",
   "skills": {
     "deliverables": "skills/deliverables/SKILL.md"
   },
+  "contracts": {
+    "tools": ["deliverables__upload_deliverable"]
+  },
   "agents_rules": {
     "file": "agents-rules/deliverables.md",
     "start_marker": "DELIVERABLE_LINK_RULES_START",

package/openclaw.plugin.json

@@ -2,8 +2,11 @@
   "id": "plugin-deliverables",
   "name": "Deliverables",
   "description": "Deliverables runtime guard for upload-first file delivery with Palz split-send diagnostics.",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "skills": ["./skills"],
+  "contracts": {
+    "tools": ["deliverables__upload_deliverable"]
+  },
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dai_ming/plugin-deliverables",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "OpenClaw deliverables native plugin — upload AI-generated files to OSS and return shareable preview/download links",
   "keywords": [
     "openclaw",

package/skills/deliverables/SKILL.md

@@ -28,17 +28,21 @@ description: 上传AI生成的文件到交付物系统，返回可分享的预
 
 | 参数 | 必填 | 取值来源 | 示例 |
 |------|------|---------|------|
-| `user_id` | **是（必传）** | 单聊取 `owner_id`，群聊取 `sender_id`。**不可省略**，否则 KB 上传报错 13002 | `cbb0fab9...` |
-| `group_id` | 群聊时必填 | 群聊取消息元数据中的 `group_id`；**单聊不传**（自动为 `default`） | `grp_43c75713` |
-| `group_name` | 群聊时必填 | 群聊取消息元数据中的群聊名称；**单聊不传** | `项目讨论群` |
+| `conversation_type` | **是** | 消息元数据 `conversation_type`：单聊 `"direct"`，群聊 `"group"` | `direct` |
+| `conversation_id` | **是** | 消息元数据 `conversation_id`，原样传 | `conv_xxx_main` |
+| `owner_id` | **是** | 消息元数据 `owner_id`，原样传 | `cbb0fab9...` |
+| `sender_id` | **是** | 消息元数据 `sender_id`，原样传 | `cbb0fab9...` |
+| `lobster_name` | **是** | 会话上下文/消息元数据中的 `lobster_name`，作交付物一级目录 | `我的助手` |
+| `lobster_id` | **是** | 消息元数据 `lobster_id`，原样传 | `main` |
+| `group_id` | 群聊**必填** | 群聊取消息元数据 `group_id`；**单聊不传**（自动归个人文件夹） | `grp_xxx` |
+| `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: 用户不存在`。
+> **不用自己算 `user_id` / `group_id`**：把上面的原始元数据（`conversation_type`/`conversation_id`/`owner_id`/`sender_id`）照填，插件会自动推导——单聊用 `owner_id` 且归个人文件夹，群聊用 `sender_id` 且归该群。
+> **不要把单聊的 `conversation_id` 当 `group_id` 传**，否则 KB 会因"用户不在群内"上传失败。
 
 ## 二进制文件上传（强制）