@dai_ming/plugin-deliverables 1.0.19 → 1.0.20

package/README.md

@@ -182,8 +182,9 @@ fi
 | `group_id` | string | — | 群聊 ID |
 | `user_id` | string | — | 用户 ID |
 | `content_text` | string | — | 文本内容（单文件场景） |
-| `content_base64` | string | — | Base64 编码的二进制内容（单文件场景） |
-| `files` | array | — | 多文件列表（游戏/站点场景，优先使用） |
+| `content_base64` | string | — | Base64 编码的二进制内容（单文件场景）；工具会清理空白并校验格式 |
+| `file_path` | string | — | 本地文件路径，推荐用于 PDF/PPT/图片/zip 等二进制文件，工具会读取并自动编码 |
+| `files` | array | — | 多文件列表（游戏/站点场景，优先使用），每项可传 `content_text`、`content_base64` 或 `file_path` |
 
 返回值包含 `preview_url`、`download_url`、`reply_markdown`（可直接附在回复消息中）。
 
@@ -201,7 +202,7 @@ fi
 
 这三层一起工作的目标是：即使 prompt 漂移，也尽量把“message + file/media”这条旁路堵住，统一收敛到 `deliverables__upload_deliverable`。
 
-另外，Palz 渠道下如果交付物回复会被拆成“内容简介 + 最终链接”两条消息，runtime plugin 还会分别打印这两次真实 HTTP 发送的 request/response 日志，便于直接从 pod stdout 排查。
+另外，Palz 渠道下如果交付物回复包含可信 gateway 交付物链接，会被拆成“内容简介 + 最终链接”两条消息；任意外部 URL 或非 gateway OSS URL 不会被包装成 `file_url` 文件消息。runtime plugin 还会分别打印这两次真实 HTTP 发送的 request/response 日志，便于直接从 pod stdout 排查。
 
 ---
 

package/agents-rules/deliverables.md

@@ -54,24 +54,26 @@ Tool name note:
 1. Create content under current agent workspace `output/` directory first (for example `output/report.md`), then call the deliverables upload tool exposed in this session.
 2. If you need to use the `write` tool, the target path MUST be inside `output/`. Never write deliverable files to the workspace root.
 3. If you already wrote the file to the wrong place, move/copy it into `output/` before finalizing the task and before describing the saved path to the user.
-4. If format is HTML, prefer `type=article` and file name ends with `.html`.
-5. Every single-file deliverable MUST use a file name with an explicit extension.
-6. If format is markdown/text, use `type=article` and `.md`/`.txt`.
-7. If the user did not specify a document/text format, default to Markdown and use a `.md` file name.
-8. For multi-file deliverables (game/site), you MUST prefer `type=game` with `files[]`, keep files as a folder structure, and do NOT zip before upload unless the user explicitly asks for a zip package.
-9. Static multi-file game/site deliverables SHOULD include a root `index.html` so the preview link can open the homepage directly.
-10. If a generated project requires starting a separate backend service, custom port, database, or long-running process to work, do NOT pretend the deliverables preview can run it. Tell the user that deliverables preview only supports static output, and that runtime projects need deployment/ingress instead.
-11. After successful upload, the final assistant message MUST start with 1-2 short sentences in your own words, briefly describing what you generated for the user.
-12. The intro must be based on the actual deliverable content/request, not a fixed sentence like `交付物已上传成功，可直接在线预览或下载。`
-13. If tool result contains `reply_markdown`, append that field verbatim after your intro on the following lines.
-14. Otherwise final reply MUST include Markdown links (short label + full URL target):
+4. For binary deliverables such as PDF, PPT, images, video, or zip files, pass `file_path` pointing at the file under `output/`; do not paste shell output or partial base64 into `content_base64`.
+5. If the upload tool returns an error, retry with a valid `file_path` or report the upload failure. Never invent OSS, preview, or download URLs.
+6. If format is HTML, prefer `type=article` and file name ends with `.html`.
+7. Every single-file deliverable MUST use a file name with an explicit extension.
+8. If format is markdown/text, use `type=article` and `.md`/`.txt`.
+9. If the user did not specify a document/text format, default to Markdown and use a `.md` file name.
+10. For multi-file deliverables (game/site), you MUST prefer `type=game` with `files[]`, keep files as a folder structure, and do NOT zip before upload unless the user explicitly asks for a zip package.
+11. Static multi-file game/site deliverables SHOULD include a root `index.html` so the preview link can open the homepage directly.
+12. If a generated project requires starting a separate backend service, custom port, database, or long-running process to work, do NOT pretend the deliverables preview can run it. Tell the user that deliverables preview only supports static output, and that runtime projects need deployment/ingress instead.
+13. After successful upload, the final assistant message MUST start with 1-2 short sentences in your own words, briefly describing what you generated for the user.
+14. The intro must be based on the actual deliverable content/request, not a fixed sentence like `交付物已上传成功，可直接在线预览或下载。`
+15. If tool result contains `reply_markdown`, append that field verbatim after your intro on the following lines.
+16. Otherwise final reply MUST include Markdown links (short label + full URL target):
    `预览链接：[点击预览](<full_url>)`
    `下载链接：[点击下载](<full_url>)`
-15. For multi-file/game deliverables, if the tool gives directory-style output, the second line may be:
+17. For multi-file/game deliverables, if the tool gives directory-style output, the second line may be:
    `文件列表：[查看目录](<full_url>)`
    Keep that format instead of forcing a zip link.
-16. Do NOT only say "已保存到工作空间".
-17. Do NOT append workspace path or a raw URL block after the Markdown links.
+18. Do NOT only say "已保存到工作空间".
+19. Do NOT append workspace path or a raw URL block after the Markdown links.
 
 ### Exception
 

package/index.js

@@ -4,15 +4,24 @@ const FETCH_PATCH_KEY = "__plugin_deliverables_palz_fetch_patch__";
 const SUMMARY_CACHE_KEY = "__plugin_deliverables_summary_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 DELIVERABLE_GATEWAY_PATH_RE = /^\/openclaw-gateway\/(?:output|preview)(?:\/|$)/u;
+const DELIVERABLE_LINK_PREFIX_RE =
+  /^\s*(?:[-*+]\s+)?(?:预览链接|下载链接|文件列表|项目入口|在线预览|在线体验|目录链接)\s*[:：]/u;
+const DELIVERABLE_LINK_LABEL_RE =
+  /^\s*(?:[-*+]\s+)?(?:预览链接|下载链接|文件列表|项目入口|在线预览|在线体验|目录链接)\s*[:：]\s*\[[^\]]+\]\([^)]+\)\s*$/u;
 
 const RUNTIME_DELIVERABLES_GUIDANCE = [
   "## Deliverables Runtime Guard (HARD CONSTRAINT)",
   "",
   "- These rules apply to the main agent and all subagents.",
   "- When the user asks for a document, article, report, 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 binary deliverables such as PDF, 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`.",
   "- 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.",
+  "- 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, prefer 1 short intro plus 3-6 concise bullets covering key sections, highlights, or findings, then preserve the Markdown links returned by the deliverables tool.",
 ].join("\n");
 
@@ -392,16 +401,97 @@ function extractDeliverableURL(line) {
   return "";
 }
 
+function configuredGatewayHosts() {
+  const values = [
+    process.env.CLAW_GATEWAY_PUBLIC_URL,
+    process.env.CLAW_GATEWAY_URL,
+    DEFAULT_GATEWAY_PUBLIC_URL,
+    DEFAULT_GATEWAY_INTERNAL_URL,
+  ];
+  const hosts = new Set();
+  for (const value of values) {
+    if (!isString(value) || !value.trim()) {
+      continue;
+    }
+    try {
+      const parsed = new URL(value.trim());
+      hosts.add(parsed.host.toLowerCase());
+      hosts.add(parsed.hostname.toLowerCase());
+    } catch (_err) {
+      // Ignore malformed configuration placeholders.
+    }
+  }
+  return hosts;
+}
+
+function isTrustedDeliverableURL(rawURL) {
+  if (!isString(rawURL) || !rawURL.trim()) {
+    return false;
+  }
+  let parsed;
+  try {
+    parsed = new URL(rawURL.trim());
+  } catch (_err) {
+    return false;
+  }
+  if (!DELIVERABLE_GATEWAY_PATH_RE.test(parsed.pathname)) {
+    return false;
+  }
+  const hosts = configuredGatewayHosts();
+  const host = parsed.host.toLowerCase();
+  const hostname = parsed.hostname.toLowerCase();
+  return hosts.has(host) || hosts.has(hostname);
+}
+
+function isOSSLikeURL(rawURL) {
+  if (!isString(rawURL) || !rawURL.trim()) {
+    return false;
+  }
+  let parsed;
+  try {
+    parsed = new URL(rawURL.trim());
+  } catch (_err) {
+    return false;
+  }
+  const host = parsed.hostname.toLowerCase();
+  return (
+    host.includes("aliyuncs.com") ||
+    host.includes("oss-cn-") ||
+    parsed.searchParams.has("OSSAccessKeyId")
+  );
+}
+
+function findUntrustedOSSDeliverableURL(text) {
+  const normalized = String(text || "").replace(/\r\n/g, "\n");
+  if (!normalized.trim()) {
+    return "";
+  }
+  const lines = normalized.split("\n");
+  let hasTrustedDeliverableURL = false;
+  let firstSuspiciousURL = "";
+  for (const line of lines) {
+    const url = extractDeliverableURL(line);
+    if (!url) {
+      continue;
+    }
+    if (isTrustedDeliverableURL(url)) {
+      hasTrustedDeliverableURL = true;
+      continue;
+    }
+    if (!firstSuspiciousURL && DELIVERABLE_LINK_PREFIX_RE.test(line) && isOSSLikeURL(url)) {
+      firstSuspiciousURL = url;
+    }
+  }
+  return !hasTrustedDeliverableURL ? firstSuspiciousURL : "";
+}
+
 function isDeliverableLinkLine(line) {
   const text = String(line || "");
-  if (
-    /^\s*(?:[-*+]\s+)?(?:预览链接|下载链接|文件列表|项目入口|在线预览|在线体验|目录链接)\s*[:：]\s*\[[^\]]+\]\([^)]+\)\s*$/u.test(
-      text,
-    )
-  ) {
-    return true;
+  const url = extractDeliverableURL(text);
+  if (!url || !isTrustedDeliverableURL(url)) {
+    return false;
   }
-  return !!extractDeliverableURL(text);
+  return DELIVERABLE_LINK_LABEL_RE.test(text) || !!url;
 }
 
 function splitDeliverableMessage(text) {
@@ -478,6 +568,14 @@ function cloneBodyAsFileLink(body, fileUrl, suffix) {
   return next;
 }
 
+function cloneBodyAsBlockedDeliverableLink(body) {
+  return cloneBody(
+    body,
+    "交付物上传未成功，已阻止发送未通过 gateway 交付物系统生成的 OSS 文件链接。请重新通过交付物上传工具上传后再发送。",
+    "",
+  );
+}
+
 function shouldSplitPalzPayload(body) {
   if (!body || typeof body !== "object" || Array.isArray(body)) {
     return null;
@@ -582,6 +680,17 @@ function installPalzFetchPatch(api) {
 
     const split = shouldSplitPalzPayload(parsed);
     if (!split) {
+      const suspiciousURL = isString(parsed.content)
+        ? findUntrustedOSSDeliverableURL(parsed.content)
+        : "";
+      if (suspiciousURL) {
+        const blockedBody = cloneBodyAsBlockedDeliverableLink(parsed);
+        const blockedBodyStr = JSON.stringify(blockedBody);
+        api.logger.warn?.(
+          `[plugin-deliverables] blocked untrusted OSS deliverable link target=${String(parsed.conversation_id || "")} url=${suspiciousURL}`,
+        );
+        return originalFetch(input, Object.assign({}, init, { body: blockedBodyStr }));
+      }
       return originalFetch(input, init);
     }
 
@@ -679,5 +788,14 @@ const plugin = {
   },
 };
 
+plugin.__test = {
+  extractDeliverableURL,
+  findUntrustedOSSDeliverableURL,
+  isDeliverableLinkLine,
+  isOSSLikeURL,
+  isTrustedDeliverableURL,
+  splitDeliverableMessage,
+};
+
 module.exports = plugin;
 module.exports.default = plugin;

package/mcp-servers/deliverables.js

@@ -12,8 +12,10 @@
  *   CLAW_GATEWAY_API_KEY / OPENCLAW_GATEWAY_API_KEY — API key with access to /openclaw-gateway/be/*
  */
 
+var fs    = require("fs");
 var http  = require("http");
 var https = require("https");
+var path  = require("path");
 
 var GATEWAY_URL    = (process.env.CLAW_GATEWAY_URL        || "http://claw-gateway:8080").replace(/\/$/, "");
 var GATEWAY_PUBLIC = (process.env.CLAW_GATEWAY_PUBLIC_URL || GATEWAY_URL).replace(/\/$/, "");
@@ -68,6 +70,9 @@ function defaultExtensionForDeliverable(args) {
 
 function normalizeDeliverableFileName(args) {
   var fileName = trimString(args && args.file_name);
+  if (!fileName && trimString(args && args.file_path)) {
+    fileName = path.basename(trimString(args && args.file_path));
+  }
   if (!fileName) {
     fileName = "file";
   }
@@ -89,8 +94,8 @@ var TOOL_DEFS = [
     name: "upload_deliverable",
     description: [
       "将 AI 生成的内容（文章、游戏、图片等）上传为交付物，返回可分享的下载/预览链接。",
-      "单文件交付物：提供 content_text 或 content_base64。",
-      "多文件交付物（网页游戏/静态站点等）：必须优先提供 files 列表，每项包含 name（相对路径）和 content_text 或 content_base64，不要先打 zip。",
+      "单文件交付物：文本内容提供 content_text；PDF/PPT/图片/zip 等二进制文件优先提供 file_path，由工具读取文件并自动编码，不要手工复制 base64。",
+      "多文件交付物（网页游戏/静态站点等）：必须优先提供 files 列表，每项包含 name（相对路径）和 content_text、content_base64 或 file_path，不要先打 zip。",
       "静态多文件预览建议在根目录提供 index.html；需要单独启动端口/后端服务的项目不属于交付物预览范围，应走部署流程。",
       "返回的 download_url / preview_url 为长期可用链接。"
     ].join(" "),
@@ -124,7 +129,11 @@ var TOOL_DEFS = [
         },
         content_base64: {
           type: "string",
-          description: "Base64 编码的二进制内容（图片、zip 等），单文件时使用"
+          description: "Base64 编码的二进制内容，单文件时使用。二进制文件更推荐 file_path，避免复制/截断导致上传失败。"
+        },
+        file_path: {
+          type: "string",
+          description: "本地文件路径，推荐用于 PDF/PPT/图片/zip 等二进制交付物。工具会读取文件并自动生成 contentBase64。"
         },
         files: {
           type: "array",
@@ -134,7 +143,8 @@ var TOOL_DEFS = [
             properties: {
               name:           { type: "string", description: "文件在交付物目录内的相对路径，例如 index.html 或 assets/main.js" },
               content_text:   { type: "string", description: "文本内容" },
-              content_base64: { type: "string", description: "Base64 二进制内容" }
+              content_base64: { type: "string", description: "Base64 二进制内容" },
+              file_path:      { type: "string", description: "本地文件路径，工具会读取并自动编码" }
             },
             required: ["name"]
           }
@@ -229,9 +239,84 @@ function buildReplyMarkdown(opts) {
   return lines.join("\n");
 }
 
-// ─── Tool implementations ─────────────────────────────────────────────────────
+function normalizeBase64Content(value, label) {
+  var text = trimString(value);
+  if (!text) {
+    return "";
+  }
+  if (/^data:/i.test(text)) {
+    var commaIndex = text.indexOf(",");
+    if (commaIndex >= 0) {
+      text = text.slice(commaIndex + 1);
+    }
+  }
+  text = text.replace(/\s+/g, "");
+  if (!text) {
+    return "";
+  }
+  if (!/^[A-Za-z0-9+/]*={0,2}$/.test(text)) {
+    throw new Error("invalid base64 for " + label + ": contains non-base64 characters; use file_path for binary files");
+  }
+  var unpadded = text.replace(/=+$/, "");
+  if (unpadded.indexOf("=") >= 0) {
+    throw new Error("invalid base64 for " + label + ": padding must be at the end; use file_path for binary files");
+  }
+  var remainder = unpadded.length % 4;
+  if (remainder === 1) {
+    throw new Error("invalid base64 for " + label + ": truncated input; use file_path for binary files");
+  }
+  var padded = unpadded;
+  if (remainder === 2) {
+    padded += "==";
+  } else if (remainder === 3) {
+    padded += "=";
+  }
+  return Buffer.from(padded, "base64").toString("base64");
+}
 
-function uploadDeliverable(args) {
+function readFileAsBase64(filePath, label) {
+  var rawPath = trimString(filePath);
+  if (!rawPath) {
+    return "";
+  }
+  var resolvedPath = path.resolve(process.cwd(), rawPath);
+  var stat;
+  try {
+    stat = fs.statSync(resolvedPath);
+  } catch (err) {
+    throw new Error("cannot read " + label + " file_path " + rawPath + ": " + err.message);
+  }
+  if (!stat.isFile()) {
+    throw new Error("cannot read " + label + " file_path " + rawPath + ": not a file");
+  }
+  return fs.readFileSync(resolvedPath).toString("base64");
+}
+
+function buildContentPayload(entry, label) {
+  var filePath = trimString(entry && entry.file_path);
+  if (filePath) {
+    return {
+      contentText: "",
+      contentBase64: readFileAsBase64(filePath, label)
+    };
+  }
+  return {
+    contentText: (entry && entry.content_text) || "",
+    contentBase64: normalizeBase64Content(entry && entry.content_base64, label)
+  };
+}
+
+function deriveReleaseName() {
+  var release = process.env.botID || process.env.OPENCLAW_RELEASE || process.env.BOT_ID || "";
+  if (!release) {
+    var tok = process.env.OPENCLAW_GATEWAY_TOKEN || "";
+    if (tok.indexOf("oc-") === 0) release = tok.slice(3);
+  }
+  return release;
+}
+
+function buildUploadRequestBody(args) {
+  args = args || {};
   var normalizedFileName = normalizeDeliverableFileName(args);
   var body = {
     resourceId: args.resource_id,
@@ -239,34 +324,35 @@ function uploadDeliverable(args) {
     userId:     args.user_id,
     type:       args.type,
     fileName:   normalizedFileName,
-    release:    ""  // overwritten below after release name derivation
+    release:    deriveReleaseName()
   };
 
   if (args.files && args.files.length > 0) {
-    body.files = args.files.map(function(f) {
+    body.files = args.files.map(function(f, index) {
+      var payload = buildContentPayload(f, "files[" + index + "] " + f.name);
       return {
         name:          f.name,
-        contentText:   f.content_text   || "",
-        contentBase64: f.content_base64 || ""
+        contentText:   payload.contentText,
+        contentBase64: payload.contentBase64
       };
     });
   } else {
-    body.contentText   = args.content_text   || "";
-    body.contentBase64 = args.content_base64 || "";
+    var singlePayload = buildContentPayload(args, "content_base64");
+    body.contentText   = singlePayload.contentText;
+    body.contentBase64 = singlePayload.contentBase64;
   }
 
-  // Derive release name:
-  // 1) botID (runtime env, e.g. "user-xxx") is preferred
-  // 2) OPENCLAW_RELEASE / BOT_ID (compat)
-  // 3) fallback to stripping "oc-" prefix from OPENCLAW_GATEWAY_TOKEN
-  var release = process.env.botID || process.env.OPENCLAW_RELEASE || process.env.BOT_ID || "";
-  if (!release) {
-    var tok = process.env.OPENCLAW_GATEWAY_TOKEN || "";
-    if (tok.indexOf("oc-") === 0) release = tok.slice(3);
-  }
-  body.release = release;
+  return body;
+}
+
+// ─── Tool implementations ─────────────────────────────────────────────────────
 
-  return httpRequest("POST", "/openclaw-gateway/be/deliverables", body).then(function(resp) {
+function uploadDeliverable(args) {
+  return Promise.resolve().then(function() {
+    return buildUploadRequestBody(args);
+  }).then(function(body) {
+    return httpRequest("POST", "/openclaw-gateway/be/deliverables", body);
+  }).then(function(resp) {
     var d = resp.body.data || resp.body;
     // Prefer backend-aware previewUrl returned by gateway (OSS/output/link).
     // Fallback to legacy gateway preview endpoint for compatibility.
@@ -315,7 +401,7 @@ function handleMessage(msg) {
       send({ jsonrpc: "2.0", id: id, result: {
         protocolVersion: "2024-11-05",
         capabilities: { tools: {} },
-        serverInfo: { name: "deliverables", version: "1.0.2" }
+        serverInfo: { name: "deliverables", version: "1.0.3" }
       }});
       return Promise.resolve();
 
@@ -347,12 +433,24 @@ function handleMessage(msg) {
   }
 }
 
-var rl = require("readline").createInterface({ input: process.stdin, terminal: false });
-rl.on("line", function(line) {
-  if (!line.trim()) return;
-  var msg;
-  try { msg = JSON.parse(line); } catch(e) { return; }
-  handleMessage(msg).catch(function(err) {
-    process.stderr.write("[deliverables] unhandled error: " + err.message + "\n");
+function startMCPServer() {
+  var rl = require("readline").createInterface({ input: process.stdin, terminal: false });
+  rl.on("line", function(line) {
+    if (!line.trim()) return;
+    var msg;
+    try { msg = JSON.parse(line); } catch(e) { return; }
+    handleMessage(msg).catch(function(err) {
+      process.stderr.write("[deliverables] unhandled error: " + err.message + "\n");
+    });
   });
-});
+}
+
+module.exports.__test = {
+  buildContentPayload: buildContentPayload,
+  buildUploadRequestBody: buildUploadRequestBody,
+  normalizeBase64Content: normalizeBase64Content
+};
+
+if (require.main === module) {
+  startMCPServer();
+}

package/openclaw-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "plugin-deliverables",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "npm_package": "@dai_ming/plugin-deliverables",
   "description": "Deliverables plugin: MCP server + skill + AGENTS rules for AI-generated file uploads",
   "mcp_servers": {

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.0.19",
+  "version": "1.0.20",
   "skills": ["./skills"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dai_ming/plugin-deliverables",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "description": "OpenClaw deliverables plugin — upload AI-generated files to OSS and return shareable preview/download links",
   "keywords": [
     "openclaw",
@@ -10,6 +10,9 @@
   ],
   "license": "MIT",
   "main": "index.js",
+  "scripts": {
+    "test": "node test/index.test.js && node test/mcp-server.test.js"
+  },
   "files": [
     "INSTALL.md",
     "index.js",
@@ -17,7 +20,8 @@
     "openclaw-plugin.json",
     "mcp-servers/",
     "skills/",
-    "agents-rules/"
+    "agents-rules/",
+    "test/"
   ],
   "openclaw": {
     "extensions": [

package/skills/deliverables/SKILL.md

@@ -34,9 +34,16 @@ description: 上传AI生成的文件到交付物系统，返回可分享的预
 | `type` | 根据内容选择：`article`/`game`/`image`/`video`/`ppt`/`zip`/`link` | `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`。
 
+## 二进制文件上传（强制）
+
+- PDF、PPT、图片、视频、zip 等二进制文件必须优先传 `file_path`，不要把 `base64` 命令输出复制到 `content_base64`。
+- `file_path` 指向你已经写入 `output/` 的文件，例如 `output/sample.pdf`；上传工具会读取文件并自动编码。
+- 如果上传工具返回错误，必须修正参数后重试，或明确告诉用户上传失败；禁止编造 OSS、下载或预览链接。
+
 ## 多文件（游戏）
 
 type 为 `game` 时，使用 `files` 数组替代 `content_text`：

package/test/index.test.js

@@ -0,0 +1,73 @@
+"use strict";
+
+const assert = require("assert");
+
+process.env.CLAW_GATEWAY_PUBLIC_URL = "https://claw-gateway.csagentai.com";
+
+const plugin = require("../index.js");
+const {
+  findUntrustedOSSDeliverableURL,
+  isDeliverableLinkLine,
+  isTrustedDeliverableURL,
+  splitDeliverableMessage,
+} = plugin.__test;
+
+const gatewayURL =
+  "https://claw-gateway.csagentai.com/openclaw-gateway/output/user/res/uuid/sample.pdf";
+const bogusOSSURL =
+  "https://palz-deliverable.oss-cn-shanghai.aliyuncs.com/user/res/sample.pdf?OSSAccessKeyId=fake";
+
+assert.strictEqual(isTrustedDeliverableURL(gatewayURL), true);
+assert.strictEqual(isTrustedDeliverableURL(bogusOSSURL), false);
+assert.strictEqual(
+  isDeliverableLinkLine(`预览链接：[点击预览](${gatewayURL})`),
+  true,
+);
+assert.strictEqual(
+  isDeliverableLinkLine(`预览链接：[点击预览](${bogusOSSURL})`),
+  false,
+);
+
+const split = splitDeliverableMessage(
+  [
+    "我生成了一个 1 页 PDF。",
+    "",
+    `预览链接：[点击预览](${gatewayURL})`,
+    `下载链接：[点击下载](${gatewayURL})`,
+  ].join("\n"),
+);
+assert.ok(split);
+assert.strictEqual(split.primaryLinkUrl, gatewayURL);
+
+assert.strictEqual(
+  splitDeliverableMessage(
+    [
+      "我生成了一个 1 页 PDF。",
+      "",
+      `预览链接：[点击预览](${bogusOSSURL})`,
+      `下载链接：[点击下载](${bogusOSSURL})`,
+    ].join("\n"),
+  ),
+  null,
+);
+assert.strictEqual(
+  findUntrustedOSSDeliverableURL(
+    [
+      "我生成了一个 1 页 PDF。",
+      "",
+      `预览链接：[点击预览](${bogusOSSURL})`,
+    ].join("\n"),
+  ),
+  bogusOSSURL,
+);
+assert.strictEqual(
+  findUntrustedOSSDeliverableURL(
+    [
+      "我生成了一个大文件。",
+      "",
+      `预览链接：[点击预览](${gatewayURL})`,
+      `下载链接：[点击下载](${bogusOSSURL})`,
+    ].join("\n"),
+  ),
+  "",
+);

package/test/mcp-server.test.js

@@ -0,0 +1,44 @@
+"use strict";
+
+const assert = require("assert");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+const {
+  buildUploadRequestBody,
+  normalizeBase64Content,
+} = require("../mcp-servers/deliverables.js").__test;
+
+assert.strictEqual(
+  normalizeBase64Content("SGVs\nbG8", "content_base64"),
+  Buffer.from("Hello").toString("base64"),
+);
+assert.strictEqual(
+  normalizeBase64Content("data:application/pdf;base64,JVBERi0xLjM", "content_base64"),
+  Buffer.from("%PDF-1.3").toString("base64"),
+);
+assert.throws(
+  () => normalizeBase64Content("SGVsb", "content_base64"),
+  /truncated input/,
+);
+
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "deliverables-mcp-"));
+const pdfPath = path.join(tmpDir, "sample.pdf");
+const pdfBytes = Buffer.from("%PDF-1.3\nsample\n", "utf8");
+fs.writeFileSync(pdfPath, pdfBytes);
+
+const body = buildUploadRequestBody({
+  resource_id: "res-1",
+  group_id: "group-1",
+  user_id: "user-1",
+  type: "article",
+  file_name: "sample.pdf",
+  file_path: pdfPath,
+  content_base64: "not-used",
+});
+
+assert.strictEqual(body.resourceId, "res-1");
+assert.strictEqual(body.fileName, "sample.pdf");
+assert.strictEqual(body.contentText, "");
+assert.strictEqual(body.contentBase64, pdfBytes.toString("base64"));