@dai_ming/plugin-deliverables 1.1.4 → 1.1.5

package/agents-rules/deliverables.md

@@ -62,24 +62,29 @@ Tool name note:
 7. If the user asks for PDF, upload a `.pdf` deliverable with `type=pdf`; do not substitute HTML or Markdown unless PDF generation truly failed and you clearly say so.
 8. If the upload tool returns an error, retry with valid parameters or report the upload failure. Never invent OSS, preview, or download URLs.
 9. If format is HTML, prefer `type=article` and file name ends with `.html`.
-10. Every single-file deliverable MUST use a file name with an explicit extension.
-11. If format is markdown/text, use `type=article` and `.md`/`.txt`.
-12. If the user did not specify a document/text format, default to Markdown and use a `.md` file name.
-13. 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.
-14. Static multi-file game/site deliverables SHOULD include a root `index.html` so the preview link can open the homepage directly.
-15. 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.
-16. 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.
-17. For content deliverables such as articles, documents, reports, and PDFs, add 3-5 concise bullets after the intro summarizing the actual sections, highlights, or conclusions. Do not reply with only a one-sentence upload notice.
-18. The intro and bullets must be based on the actual deliverable content/request, not a fixed sentence like `交付物已上传成功，可直接在线预览或下载。`
-19. If tool result contains `reply_markdown`, append that field verbatim after your intro and content bullets on the following lines.
-20. Otherwise final reply MUST include Markdown links (short label + full URL target):
+10. Local file names or relative paths such as `review.html` and `output/report.md` are not links. Do not use `type=link` for them; upload them with `file_path` or `content_text`.
+11. Every single-file deliverable MUST use a file name with an explicit extension.
+12. If format is markdown/text, use `type=article` and `.md`/`.txt`.
+13. If the user did not specify a document/text format, default to Markdown and use a `.md` file name.
+14. 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.
+15. Static multi-file game/site deliverables SHOULD include a root `index.html` so the preview link can open the homepage directly.
+16. 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.
+17. 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.
+18. For content deliverables such as articles, documents, reports, and PDFs, add 3-5 concise bullets after the intro summarizing the actual sections, highlights, or conclusions. Do not reply with only a one-sentence upload notice.
+19. The intro and bullets must be based on the actual deliverable content/request, not a fixed sentence like `交付物已上传成功，可直接在线预览或下载。`
+20. If tool result contains `reply_markdown`, append that field verbatim after your intro and content bullets on the following lines.
+21. Otherwise final reply MUST include Markdown links (short label + full URL target):
    `预览链接：[点击预览](<full_url>)`
    `下载链接：[点击下载](<full_url>)`
-21. For multi-file/game deliverables, if the tool gives directory-style output, the second line may be:
+22. 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.
-22. Do NOT only say "已保存到工作空间".
-23. Do NOT append workspace path or a raw URL block after the Markdown links.
+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/index.js

@@ -63,6 +63,7 @@ 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 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",
@@ -121,8 +122,11 @@ const RUNTIME_DELIVERABLES_GUIDANCE = [
   "- 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 = {
@@ -158,7 +162,7 @@ const UPLOAD_DELIVERABLE_TOOL = {
       type: {
         type: "string",
         enum: ["article", "game", "zip", "image", "video", "ppt", "pdf", "link"],
-        description: "交付物类型。若使用 file_path 且未准确判断，可由插件按文件扩展名兜底。",
+        description: "交付物类型。link 仅用于外部 http(s) URL；本地/生成文件必须使用 file_path、content_text 或 files。",
       },
       file_name: {
         type: "string",
@@ -170,7 +174,7 @@ const UPLOAD_DELIVERABLE_TOOL = {
       },
       content_text: {
         type: "string",
-        description: "文本内容（Markdown、HTML 等）。type=pdf 时可传纯文本/Markdown，插件会生成基础 PDF。",
+        description: "文本内容（Markdown、HTML 等）。",
       },
       content_base64: {
         type: "string",
@@ -241,6 +245,15 @@ function isURLLike(value) {
   return /^[a-z][a-z0-9+.-]*:\/\//i.test(String(value || ""));
 }
 
+function isHTTPURLLike(value) {
+  try {
+    const parsed = new URL(String(value || "").trim());
+    return (parsed.protocol === "http:" || parsed.protocol === "https:") && !!parsed.hostname;
+  } catch (_err) {
+    return false;
+  }
+}
+
 function fileExtension(filePath) {
   return path.extname(stripTrailingPathPunctuation(filePath)).toLowerCase();
 }
@@ -438,6 +451,9 @@ function extractFileReferencesFromText(text) {
   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;
 }
 
@@ -553,13 +569,87 @@ function payloadResourceId(body) {
 }
 
 function payloadGroupId(body) {
-  return extractStringField(body, ["group_id", "groupId"]);
+  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");
@@ -1029,7 +1119,11 @@ function buildNativeUploadRequestBody(args) {
   if (fileCandidate) {
     const stat = safeStat(fileCandidate.path);
     const isDirectory = !!(stat && stat.isDirectory());
-    body.type = trimString(args.type) || deliverableTypeForPath(fileCandidate.path, isDirectory);
+    const requestedType = trimString(args.type);
+    body.type =
+      requestedType === "link"
+        ? deliverableTypeForPath(fileCandidate.path, isDirectory)
+        : requestedType || deliverableTypeForPath(fileCandidate.path, isDirectory);
     body.fileName = normalizeDeliverableFileName(args, fileCandidate.fileName);
     if (isDirectory) {
       const files = collectDirectoryFiles(fileCandidate.path);
@@ -1049,9 +1143,23 @@ function buildNativeUploadRequestBody(args) {
   body.fileName = normalizeDeliverableFileName(args, "");
   const files = normalizeNativeToolFiles(args && args.files);
   if (files.length > 0) {
+    if (body.type === "link") {
+      body.type = "game";
+    }
     body.files = files;
     return { body, isDirectory: true };
   }
+  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)) {
+      throw new Error(
+        "type=link requires file_name to be an absolute http(s) URL; use file_path or content_text for local/generated files",
+      );
+    }
+  }
   const contentText = (args && (args.content_text || args.contentText)) || "";
   const contentBase64 = (args && (args.content_base64 || args.contentBase64)) || "";
   if (body.type === "pdf" && trimString(contentText) && !trimString(contentBase64)) {
@@ -1066,8 +1174,8 @@ function buildNativeUploadRequestBody(args) {
 async function uploadDeliverable(args) {
   const { body, isDirectory } = buildNativeUploadRequestBody(args || {});
   const userId = payloadUserId(args) || "default";
-  const groupId = trimString(args && args.group_id) || DEFAULT_GROUP_ID;
-  const groupName = trimString(args && args.group_name);
+  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 = {
@@ -2060,6 +2168,7 @@ const plugin = {
 
     api.on("before_tool_call", async (event) => {
       if (isDeliverablesUploadTool(event.toolName)) {
+        enrichDeliverableGroupContext(event);
         cacheUploadSummary(event.params);
         return;
       }

package/openclaw-plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "plugin-deliverables",
-  "version": "1.1.4",
+  "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.4",
+  "version": "1.1.5",
   "skills": ["./skills"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dai_ming/plugin-deliverables",
-  "version": "1.1.4",
+  "version": "1.1.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,25 +28,25 @@ description: 上传AI生成的文件到交付物系统，返回可分享的预
 
 | 参数 | 必填 | 取值来源 | 示例 |
 |------|------|---------|------|
-| `user_id` | 是 | 单聊取 `owner_id`，群聊取 `sender_id` | `cbb0fab9...` |
+| `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` | `article` |
+| `type` | 是 | 根据内容选择：`article`/`game`/`image`/`video`/`ppt`/`pdf`/`zip`；`link` 仅用于外部 `http(s)` URL | `article` |
 | `file_name` | 是 | 有意义的文件名，单文件必须含扩展名；若用户未指定文档格式，默认用 `.md` | `report-2026.html` |
-| `content_text` | 按需 | 文件的完整文本内容（HTML/Markdown等）；简单 PDF 可传文本/Markdown，由工具生成基础 PDF | `<html>...</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: 用户不存在`。
 
 ## 二进制文件上传（强制）
 
-- 简单文本 PDF 可以直接调用 `deliverables__upload_deliverable`：`type=pdf`、`.pdf` 文件名、`content_text` 填完整内容；工具会生成基础 PDF，不需要额外依赖。
-- 已经生成好的 PDF、PPT、图片、视频、zip 等二进制文件必须优先传 `file_path`，不要把 `base64` 命令输出复制到 `content_base64`。
+- PDF、PPT、图片、视频、zip 等二进制文件必须优先传 `file_path`，不要把 `base64` 命令输出复制到 `content_base64`。
 - `file_path` 指向你已经写入 `output/` 的文件，例如 `output/sample.pdf`；上传工具会读取文件并自动编码。
-- 不要为了生成 PDF 临时执行 `pip install`、`npm install`、`apt-get` 等依赖安装。使用已有工具或上面的 PDF `content_text` 兜底；如果复杂 PDF 渲染器不可用，要明确说明限制。
-- 用户要求 PDF 时，必须上传 `.pdf` 交付物，`type` 使用 `pdf`；不要只返回 HTML/Markdown 作为替代格式。
+- 用户要求 PDF 时，必须上传生成好的 `.pdf` 文件，`type` 使用 `pdf`；不要只返回 HTML/Markdown 作为替代格式。
 - 如果上传工具返回错误，必须修正参数后重试，或明确告诉用户上传失败；禁止编造 OSS、下载或预览链接。
+- 本地文件名或相对路径（例如 `review.html`、`output/report.md`）不是外部链接，不能用 `type=link`；必须用 `file_path` 或 `content_text` 上传。
 
 ## 多文件（游戏）