@dai_ming/plugin-deliverables 1.0.6 → 1.0.9

package/README.md

@@ -20,7 +20,7 @@ OpenClaw 交付物插件。安装后会把交付物 MCP、skill、AGENTS 规则
 
 ```yaml
 installPlugins:
-  - "@dai_ming/plugin-deliverables@1.0.6"
+  - "@dai_ming/plugin-deliverables@1.0.9"
 ```
 
 现有 chart 会在 init 阶段完成安装。
@@ -31,7 +31,7 @@ installPlugins:
 
 ```bash
 npm config set registry https://registry.npmmirror.com
-npm install @dai_ming/plugin-deliverables@1.0.6
+npm install @dai_ming/plugin-deliverables@1.0.9
 node node_modules/@dai_ming/plugin-deliverables/install.js
 ```
 
@@ -133,3 +133,7 @@ env | grep -E 'CLAW_GATEWAY|OPENCLAW_GATEWAY|botID'
 ```bash
 curl -H "X-API-Key: $CLAW_GATEWAY_API_KEY" "$CLAW_GATEWAY_URL/healthz"
 ```
+
+### 返回的是 `/preview/:uuid` 或内部地址
+
+`1.0.9` 起，插件会在 `output` 交付物场景下自动把相对/内部 preview 地址修正为最终的外部 `output` 直链，不再依赖 gateway 当前环境里是否显式配置了 `deliverable.gatewayPublicUrl`。

package/agents-rules/deliverables.md

@@ -12,25 +12,32 @@ Tool name note:
 
 ### Required output behavior
 
-0. Your final assistant message MUST start with 1-2 short sentences in your own words, briefly describing what you produced for the user.
+0. Your final assistant message MUST start with a richer Markdown intro section, not a single short confirmation sentence.
 1. The intro must be based on the actual content/request, not a fixed boilerplate like `交付物已上传成功，可直接在线预览或下载。`
-2. If tool result contains `reply_markdown`, append that field verbatim after your intro on the following lines. Do not rewrite the links inside it.
-3. If tool result has `preview_url`, include one line:
+2. The intro SHOULD use Markdown structure, preferably:
+   - a short title or summary line
+   - a `### 内容概览` section
+   - 3-6 bullet points describing the actual sections, highlights, features, or focus of the deliverable
+3. The intro should be noticeably more informative than one sentence. For normal articles/reports/introductions, aim for roughly 80-200 Chinese characters total before the links.
+4. The bullet points must describe the real deliverable content. Do not use empty filler like "内容丰富" / "结构清晰" / "值得阅读" unless paired with concrete details.
+5. If tool result contains `reply_markdown`, append a `### 访问链接` heading and then append that field verbatim on the following lines. Do not rewrite the links inside it.
+6. If tool result has `preview_url`, include one line:
    `预览链接：[点击预览](<full_url>)`
-4. If tool result has `download_url`, include one line:
+7. If tool result has `download_url`, include one line:
    `下载链接：[点击下载](<full_url>)`
-5. For multi-file/game deliverables, if tool result already formats the second line as
+8. For multi-file/game deliverables, if tool result already formats the second line as
    `文件列表：[查看目录](<full_url>)`
    then keep that exact label and URL. Do not rewrite it back to a raw long link.
-6. Keep URL target value exactly from tool result (no shortening, no masking, no redirect rewrite).
-7. Use short link labels (`点击预览` / `点击下载` / `查看目录`) to avoid exposing long raw URLs.
-8. Do not say "已上传/已完成" without links.
-9. Do not output naked long URLs outside Markdown link syntax.
-10. Keep the intro concise; do not paste the full file content, saved-path text, or a long summary after the Markdown links.
+9. Keep URL target value exactly from tool result (no shortening, no masking, no redirect rewrite).
+10. Use short link labels (`点击预览` / `点击下载` / `查看目录`) to avoid exposing long raw URLs.
+11. Do not say "已上传/已完成" without links.
+12. Do not output naked long URLs outside Markdown link syntax.
+13. Keep the intro concise but substantive; do not paste the full file content, saved-path text, or a huge essay after the Markdown links.
 
 ### Forbidden output behavior
 
 - "可点击预览链接查看" but no actual URL
+- A single short sentence plus links when the deliverable is an article/report/introduction and concrete highlights are available
 - Replacing URL target with a non-original URL
 - Omitting both links when tool already returned links
 - Outputting only naked long URL without Markdown link label
@@ -59,17 +66,22 @@ Tool name note:
 6. 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.
 7. Static multi-file game/site deliverables SHOULD include a root `index.html` so the preview link can open the homepage directly.
 8. 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.
-9. 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.
+9. After successful upload, the final assistant message MUST start with a richer Markdown intro section, not just one short sentence.
 10. The intro must be based on the actual deliverable content/request, not a fixed sentence like `交付物已上传成功，可直接在线预览或下载。`
-11. If tool result contains `reply_markdown`, append that field verbatim after your intro on the following lines.
-12. Otherwise final reply MUST include Markdown links (short label + full URL target):
+11. Prefer this Markdown structure:
+   - a short title or summary line
+   - `### 内容概览`
+   - 3-6 bullet points summarizing the actual content sections, highlights, or key features
+12. For ordinary articles/reports/introductions, the intro before the links should normally reach roughly 80-200 Chinese characters total.
+13. If tool result contains `reply_markdown`, add `### 访问链接` and append that field verbatim on the following lines.
+14. Otherwise final reply MUST include Markdown links (short label + full URL target):
    `预览链接：[点击预览](<full_url>)`
    `下载链接：[点击下载](<full_url>)`
-13. For multi-file/game deliverables, if the tool gives directory-style output, the second line may be:
+15. 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.
-14. Do NOT only say "已保存到工作空间".
-15. Do NOT append workspace path or a raw URL block after the Markdown links.
+16. Do NOT only say "已保存到工作空间".
+17. Do NOT append workspace path or a raw URL block after the Markdown links.
 
 ### Exception
 

package/mcp-servers/deliverables.js

@@ -16,11 +16,12 @@ var http  = require("http");
 var https = require("https");
 
 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(/\/$/, "");
+var RAW_GATEWAY_PUBLIC = (process.env.CLAW_GATEWAY_PUBLIC_URL || GATEWAY_URL).replace(/\/$/, "");
 // Some existing pods were created without CLAW_GATEWAY_API_KEY injected.
 // Keep env-driven behavior first, but provide a dev-compatible fallback to avoid
 // breaking deliverable uploads during rolling migration.
 var API_KEY        = process.env.CLAW_GATEWAY_API_KEY || process.env.OPENCLAW_GATEWAY_API_KEY || "api-key-1";
+var GATEWAY_PUBLIC = resolveGatewayPublicBase();
 
 var TOOL_DEFS = [
   {
@@ -93,6 +94,200 @@ function parseURL(rawURL) {
   }
 }
 
+function isPrivateIPv4(hostname) {
+  if (!hostname) return false;
+  if (/^10\./.test(hostname)) return true;
+  if (/^127\./.test(hostname)) return true;
+  if (/^192\.168\./.test(hostname)) return true;
+  var m = hostname.match(/^172\.(\d+)\./);
+  if (m) {
+    var second = parseInt(m[1], 10);
+    return second >= 16 && second <= 31;
+  }
+  return false;
+}
+
+function isInternalHostname(hostname) {
+  var host = String(hostname || "").toLowerCase();
+  if (!host) return false;
+  if (host === "localhost" || host === "claw-gateway") return true;
+  if (host.indexOf(".svc") >= 0 || host.indexOf(".cluster.local") >= 0) return true;
+  if (host.indexOf("claw-gateway:") === 0) return true;
+  if (isPrivateIPv4(host)) return true;
+  if (host.indexOf(".") < 0) return true;
+  return false;
+}
+
+function isProbablyInternalURL(rawURL) {
+  var parsed = parseURL(rawURL);
+  if (!parsed) return false;
+  return isInternalHostname(parsed.hostname);
+}
+
+function envGatewayPublicFallback() {
+  var helmEnv = String(process.env.HELM_ENV || process.env.ENV || "").toLowerCase();
+  if (helmEnv === "prod" || helmEnv === "production" || helmEnv === "online") {
+    return "https://claw-gateway.csagentai.com";
+  }
+  if (helmEnv === "dev" || helmEnv === "development" || helmEnv === "staging" || helmEnv === "stage") {
+    return "https://claw-dev.csaiagent.com";
+  }
+  return "";
+}
+
+function resolveGatewayPublicBase() {
+  var candidate = RAW_GATEWAY_PUBLIC;
+  if (candidate && !isProbablyInternalURL(candidate)) {
+    return candidate;
+  }
+  var fallback = envGatewayPublicFallback();
+  if (fallback) {
+    return fallback.replace(/\/$/, "");
+  }
+  return candidate;
+}
+
+function absolutizePublicURL(rawURL) {
+  var val = String(rawURL || "").trim();
+  if (!val) return "";
+  if (/^https?:\/\//i.test(val)) {
+    if (isProbablyInternalURL(val) && GATEWAY_PUBLIC && !isProbablyInternalURL(GATEWAY_PUBLIC)) {
+      var parsed = parseURL(val);
+      if (parsed) {
+        return GATEWAY_PUBLIC + parsed.pathname + (parsed.search || "") + (parsed.hash || "");
+      }
+    }
+    return val;
+  }
+  if (val.charAt(0) !== "/") {
+    val = "/" + val;
+  }
+  return (GATEWAY_PUBLIC || RAW_GATEWAY_PUBLIC || "").replace(/\/$/, "") + val;
+}
+
+function outputPublicBase() {
+  return absolutizePublicURL("/openclaw-gateway/output");
+}
+
+function encodePathSegments(parts) {
+  return parts.map(function(part) {
+    return encodeURIComponent(String(part || ""));
+  }).join("/");
+}
+
+function sanitizePathSegment(v) {
+  var s = String(v || "").trim();
+  if (!s) return "unknown";
+  s = s.replace(/\//g, "_");
+  s = s.replace(/\\/g, "_");
+  s = s.replace(/\.\./g, "_");
+  return s;
+}
+
+function sanitizeFileName(v) {
+  var name = String(v || "").trim();
+  if (!name) return "file";
+  name = name.replace(/^.*[\/\\]/, "");
+  name = name.replace(/\//g, "_");
+  name = name.replace(/\\/g, "_");
+  name = name.replace(/\.\./g, "_");
+  if (!name || name === ".") return "file";
+  return name;
+}
+
+function extractUserIDFromResource(resourceID) {
+  var trimmed = String(resourceID || "").trim();
+  var prefix = "user_";
+  if (!trimmed || trimmed.indexOf(prefix) !== 0) {
+    return "";
+  }
+  var rest = trimmed.slice(prefix.length);
+  var end = rest.indexOf("_");
+  if (end <= 0) {
+    return "";
+  }
+  return rest.slice(0, end);
+}
+
+function deriveRelease(release, resourceID, userID) {
+  var rel = sanitizePathSegment(release);
+  if (rel && rel !== "unknown") {
+    return rel;
+  }
+  var uid = String(userID || "").trim();
+  if (!uid) {
+    uid = extractUserIDFromResource(resourceID);
+  }
+  if (uid) {
+    return "user-" + uid;
+  }
+  return "unknown";
+}
+
+function looksLikePreviewRoute(rawURL) {
+  var val = String(rawURL || "").trim();
+  return /\/openclaw-gateway\/preview\/[^/?#]+(?:[?#].*)?$/i.test(val);
+}
+
+function needsOutputURLRepair(data) {
+  if (!data) return false;
+  if (String(data.backend || "").toLowerCase() !== "output") {
+    return false;
+  }
+  var previewURL = String(data.previewUrl || "").trim();
+  var downloadURL = String(data.downloadUrl || "").trim();
+  if (!previewURL || !downloadURL) {
+    return true;
+  }
+  if (previewURL.charAt(0) === "/" || downloadURL.charAt(0) === "/") {
+    return true;
+  }
+  if (isProbablyInternalURL(previewURL) || isProbablyInternalURL(downloadURL)) {
+    return true;
+  }
+  if (looksLikePreviewRoute(previewURL) || looksLikePreviewRoute(downloadURL)) {
+    return true;
+  }
+  return false;
+}
+
+function fetchDeliverableMeta(uuid) {
+  if (!uuid) return Promise.resolve(null);
+  return httpRequest("GET", "/openclaw-gateway/be/deliverables/" + encodeURIComponent(uuid)).then(function(resp) {
+    return resp.body.data || resp.body || null;
+  });
+}
+
+function buildOutputURLs(meta, args, body, data) {
+  var base = outputPublicBase();
+  if (!base) {
+    return null;
+  }
+  var resourceID = sanitizePathSegment((meta && meta.resourceId) || body.resourceId || args.resource_id);
+  var userID = (meta && meta.userId) || body.userId || args.user_id;
+  var release = deriveRelease((meta && meta.release) || body.release, resourceID, userID);
+  var uuid = String((meta && meta.uuid) || (data && data.uuid) || "").trim();
+  if (!resourceID || !uuid) {
+    return null;
+  }
+  var isDirectory = !!(args.files && args.files.length > 0) || String((meta && meta.mime) || "").trim() === "application/x-directory";
+  if (isDirectory) {
+    var dirURL = base.replace(/\/$/, "") + "/" + encodePathSegments([release, resourceID, uuid]);
+    return {
+      previewURL: dirURL,
+      downloadURL: dirURL + "?list=1",
+      isDirectory: true
+    };
+  }
+  var fileName = sanitizeFileName((meta && meta.fileName) || body.fileName || args.file_name);
+  var fileURL = base.replace(/\/$/, "") + "/" + encodePathSegments([release, resourceID, uuid, fileName]);
+  return {
+    previewURL: fileURL,
+    downloadURL: fileURL,
+    isDirectory: false
+  };
+}
+
 function httpRequest(method, path, body) {
   return new Promise(function(resolve, reject) {
     var parsed = parseURL(GATEWAY_URL + path);
@@ -167,6 +362,17 @@ function buildReplyMarkdown(opts) {
   return lines.join("\n");
 }
 
+function resolveReplyURLs(data, args, body) {
+  if (!needsOutputURLRepair(data)) {
+    return Promise.resolve(null);
+  }
+  return fetchDeliverableMeta(data.uuid).catch(function() {
+    return null;
+  }).then(function(meta) {
+    return buildOutputURLs(meta, args, body, data);
+  });
+}
+
 // ─── Tool implementations ─────────────────────────────────────────────────────
 
 function uploadDeliverable(args) {
@@ -205,29 +411,32 @@ function uploadDeliverable(args) {
 
   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.
-    var previewURL = d.previewUrl || (GATEWAY_PUBLIC + "/openclaw-gateway/preview/" + d.uuid);
-    var isDirectory = !!(args.files && args.files.length > 0);
-    if (!isDirectory && d.downloadUrl && previewURL && d.downloadUrl !== previewURL && /(?:\?|&)list=1(?:&|$)/.test(d.downloadUrl)) {
-      isDirectory = true;
-    }
-    var replyMarkdown = buildReplyMarkdown({
-      previewURL: previewURL,
-      downloadURL: d.downloadUrl,
-      type: args.type,
-      isDirectory: isDirectory
+    return resolveReplyURLs(d, args, body).then(function(repaired) {
+      // Prefer backend-aware previewUrl returned by gateway (OSS/output/link).
+      // Fallback to legacy gateway preview endpoint for compatibility.
+      var previewURL = absolutizePublicURL((repaired && repaired.previewURL) || d.previewUrl || ("/openclaw-gateway/preview/" + d.uuid));
+      var downloadURL = absolutizePublicURL((repaired && repaired.downloadURL) || d.downloadUrl);
+      var isDirectory = !!(repaired && repaired.isDirectory) || !!(args.files && args.files.length > 0);
+      if (!isDirectory && downloadURL && previewURL && downloadURL !== previewURL && /(?:\?|&)list=1(?:&|$)/.test(downloadURL)) {
+        isDirectory = true;
+      }
+      var replyMarkdown = buildReplyMarkdown({
+        previewURL: previewURL,
+        downloadURL: downloadURL,
+        type: args.type,
+        isDirectory: isDirectory
+      });
+      return {
+        uuid:         d.uuid,
+        backend:      d.backend || "",
+        download_url: downloadURL,
+        preview_url:  previewURL,
+        expire_at:    d.expireAt,
+        reply_markdown: replyMarkdown,
+        trace_id:     resp.traceID || "",
+        message: replyMarkdown
+      };
     });
-    return {
-      uuid:         d.uuid,
-      backend:      d.backend || "",
-      download_url: d.downloadUrl,
-      preview_url:  previewURL,
-      expire_at:    d.expireAt,
-      reply_markdown: replyMarkdown,
-      trace_id:     resp.traceID || "",
-      message: replyMarkdown
-    };
   });
 }
 
@@ -252,7 +461,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.9" }
       }});
       return Promise.resolve();
 

package/openclaw-plugin.json

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

package/package.json

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

package/skills/deliverables/SKILL.md

@@ -57,13 +57,19 @@ files: [
 ## 上传成功后
 
 优先规则：
-- 最终消息必须先用你自己的话写 1-2 句简短介绍，粗略说明你生成了什么内容、包含哪些重点。
-- 这句介绍必须基于实际产物内容，不要使用固定模板，例如：`交付物已上传成功，可直接在线预览或下载。`
-- 如果工具结果里有 `reply_markdown`，把它原样放在这句介绍后面，不要改写其中的链接。
+- 最终消息必须先给出一段更完整的 Markdown 介绍，不要只写一句短确认。
+- 建议结构是：
+  - 一行简短标题或总结
+  - `### 内容概览`
+  - 3-6 个 bullet，概括这份产物实际包含的章节、重点、亮点或功能
+- 这段介绍必须基于实际产物内容，不要使用固定模板，例如：`交付物已上传成功，可直接在线预览或下载。`
+- 对于常见文章、介绍、报告类交付物，链接前的介绍通常应达到约 80-200 个中文字符，明显长于一句话确认。
+- bullet 必须写具体内容，例如“基本信息、代表作品、奖项与影响力”，不要只写“内容完整、结构清晰”这类空话。
+- 如果工具结果里有 `reply_markdown`，先输出 `### 访问链接`，再把它原样放在后面，不要改写其中的链接。
 
 否则只发给用户：
 - 预览链接（`preview_url`，必须用 Markdown 链接格式）
 - 下载链接（`download_url`，必须用 Markdown 链接格式）
 - 多文件/游戏目录场景下，第二行也可以是 `文件列表：[查看目录](...)`，不要改成裸 URL 或 zip 描述。
 
-不要在消息里输出文件的完整内容、工作区保存路径或裸链接。
+不要在消息里输出文件的完整内容、工作区保存路径或裸链接，也不要只输出“一句简介 + 两个链接”这种过短格式。