@xyagent/cli 0.0.1

package/src-ext/runtime/_shared/relayObjectToBlock.mjs

@@ -0,0 +1,307 @@
+/**
+ * relayObjectToBlock.mjs — 共享 relay_object → daemon block 转换模块
+ *
+ * 本模块是所有 runtime adapter 的单一 attachment block 构造入口。
+ * 将 relay resolver 处理后的 kind=url relay_object source block 转换为
+ * 对应 runtime 所需的 daemon content block。
+ *
+ * spec ref: openspec/changes/multimodal-attachment-llm-dispatch
+ *           specs/cli-multimodal-dispatch/spec.md
+ *
+ * @param {object} block - kind=url 的 relay_object block，shape:
+ *   { type: "image"|"attachment", source: { kind: "url", url, media_type, attachment_kind }, name?, mime?, size? }
+ *
+ * @param {object} opts
+ * @param {string}   opts.runtimeHint          - "claude"|"openclaw"|"picoclaw"|"codex"|"hermes"
+ * @param {string[]|null} opts.modelCaps        - modalities 数组（如 ["text","image","pdf"]）。
+ *                                               null 表示跳过 caps 检查（picoclaw）。
+ *                                               缺失时默认 ["text"]。
+ * @param {Function} opts.fetchAndBase64Encode  - async (url, opts) => { base64, mediaType, bytes }
+ * @param {Function} [opts.fetchAndDecodeText]  - async (url, opts) => string
+ *                                               text/document text-fallback 路径需要。
+ *
+ * @returns {Promise<DaemonBlock | ErrorResult>}
+ *
+ * DaemonBlock:
+ *   { type: "input_image",   source: { type: "base64", media_type, data } }
+ *   { type: "input_file",    source: { type: "base64", media_type: "application/pdf", filename, data } }
+ *   { type: "input_text",    text }
+ *   { type: "url_ref",       url, media_type }   // picoclaw only
+ *
+ * ErrorResult:
+ *   { error: { code: "caps_mismatch",    message, model?, missing_modality } }
+ *   { error: { code: "fetch_failed",     message } }
+ *   { error: { code: "size_exceeded",    message, bytes, cap } }
+ *   { error: { code: "unsupported_kind", message, hint_url? } }
+ */
+
+// 10 MiB image cap / 20 MiB PDF cap / 256 KiB text cap
+const IMAGE_SIZE_CAP = 10 * 1024 * 1024;
+const PDF_SIZE_CAP = 20 * 1024 * 1024;
+// TEXT_CHAR_CAP 在 ASCII-dominant 场景下兼作字节上限（sizeCapBytes）和字符截断上限
+// （content.length 截断）。对 CJK 多字节内容而言，256 KiB 字节 ≈ 85K 个 CJK 字符，
+// 截断粒度略粗但不影响正确性。如需分开，可拆成 TEXT_BYTES_CAP + TEXT_CHARS_CAP。
+const TEXT_CHAR_CAP = 256 * 1024;
+
+/**
+ * 从 block 推断 attachment_kind（用于缺少字段的历史消息兼容）。
+ *
+ * 优先读 block.source.attachment_kind；
+ * 缺失时按 block.type + media_type 推断。
+ */
+function resolveAttachmentKind(block) {
+  const kind = block?.source?.attachment_kind;
+  if (kind && kind !== "file") return kind; // 已有明确 kind（非存量 "file"）
+
+  // 存量 kind="file" 或缺失时：按 media_type 推断
+  const mime = block?.source?.media_type ?? block?.mime ?? "";
+  if (block?.type === "image" || mime.startsWith("image/")) return "image";
+  if (mime === "application/pdf") return "document";
+  if (
+    mime.startsWith("text/") ||
+    mime === "application/json" ||
+    mime === "application/yaml" ||
+    mime === "application/xml" ||
+    mime.startsWith("application/typescript") ||
+    /^text\/x-/.test(mime)
+  ) return "text";
+  return "binary";
+}
+
+export async function relayObjectToBlock(block, opts = {}) {
+  const {
+    runtimeHint,
+    modelCaps,       // null = skip caps check (picoclaw); undefined/missing = default ["text"]
+    fetchAndBase64Encode,
+    fetchAndDecodeText,
+  } = opts;
+
+  // 解析 caps（null 表示跳过检查，undefined/missing 默认 ["text"]）
+  const caps = modelCaps === null ? null : (modelCaps ?? ["text"]);
+
+  const url = block?.source?.url;
+  // source.name 优先级最高（go_relay 透传的原始文件名，未编码），
+  // 其次 block.name（顶层字段），再次 source.filename（旧字段），最后兜底 "file"。
+  const name = block?.source?.name || block?.name || block?.source?.filename || "file";
+  const sizeBytes = block?.size ?? null;
+
+  const attachmentKind = resolveAttachmentKind(block);
+
+  // image kind の場合は media_type のデフォルトを image/jpeg にする
+  const mediaTypeRaw = block?.source?.media_type ?? block?.mime ?? "application/octet-stream";
+  const mediaType = (attachmentKind === "image" && mediaTypeRaw === "application/octet-stream")
+    ? "image/jpeg"
+    : mediaTypeRaw;
+
+  // ─── kind = image ────────────────────────────────────────────────────────
+
+  if (attachmentKind === "image") {
+    // 1. caps check（null 跳过）
+    if (caps !== null && !caps.includes("image")) {
+      return {
+        error: {
+          code: "caps_mismatch",
+          message: `Model does not support image attachments. Add "image" to modalities in openclaw.json.`,
+          missing_modality: "image",
+        },
+      };
+    }
+
+    // 2. picoclaw → url_ref（无 fetch）
+    if (runtimeHint === "picoclaw") {
+      return { type: "url_ref", url, media_type: mediaType };
+    }
+
+    // 3. fetch + base64
+    try {
+      const { base64, mediaType: resolvedMime, bytes } = await fetchAndBase64Encode(url, {
+        expectedMime: mediaType,
+        sizeCapBytes: IMAGE_SIZE_CAP,
+      });
+      // 检测 size_exceeded（fetchAndBase64Encode 抛错时在 catch 里处理）
+      void bytes; // suppress unused
+      return {
+        type: "input_image",
+        source: {
+          type: "base64",
+          media_type: resolvedMime,
+          data: base64,
+        },
+      };
+    } catch (err) {
+      const msg = err?.message ?? String(err);
+      // size exceeded 检测：fetchAndBase64Encode 的错误消息含 "size" + "exceeds"
+      if (/size.*exceed|exceed.*size/i.test(msg)) {
+        // 提取 bytes（尽力解析）
+        const bytesMatch = msg.match(/(\d+)\s*bytes/);
+        const bytes = bytesMatch ? parseInt(bytesMatch[1], 10) : (sizeBytes ?? 0);
+        return {
+          error: {
+            code: "size_exceeded",
+            message: msg,
+            bytes,
+            cap: IMAGE_SIZE_CAP,
+          },
+        };
+      }
+      return {
+        error: {
+          code: "fetch_failed",
+          message: msg,
+        },
+      };
+    }
+  }
+
+  // ─── kind = document ────────────────────────────────────────────────────
+
+  if (attachmentKind === "document") {
+    const filename = name.endsWith(".pdf") ? name : `${name}.pdf`;
+
+    // native pdf caps → base64 input_file
+    if (caps !== null && caps.includes("pdf")) {
+      try {
+        const { base64 } = await fetchAndBase64Encode(url, {
+          expectedMime: "application/pdf",
+          sizeCapBytes: PDF_SIZE_CAP,
+        });
+        return {
+          type: "input_file",
+          source: {
+            type: "base64",
+            media_type: "application/pdf",
+            filename,
+            data: base64,
+          },
+        };
+      } catch (_err) {
+        // fall through to text-extraction path (not a hard error)
+      }
+    }
+
+    // text extraction fallback（pdfjs-dist）
+    // 注意：上方 catch 只覆盖 fetchAndBase64Encode 的网络/尺寸失败（fetch 失败 → fall through 到此）。
+    // 本段的 catch 覆盖 pdfjs 文本抽取失败（_extractPdfText 内部错误或 pdfjs-dist 未安装）。
+    // 两层 catch 语义不同，不合并。
+    try {
+      // pdfjs-dist 文本抽取（pdfjs-dist 已声明于 package.json dependencies）
+      const { base64, bytes: _bytes } = await fetchAndBase64Encode(url, {
+        expectedMime: "application/pdf",
+        sizeCapBytes: PDF_SIZE_CAP,
+      });
+      const pdfBuffer = Buffer.from(base64, "base64");
+      const text = await _extractPdfText(pdfBuffer, { cap: TEXT_CHAR_CAP });
+      const truncNote = text.length >= TEXT_CHAR_CAP
+        ? `\n... [truncated at 256 KB, original size: ${_bytes} bytes]`
+        : "";
+      return {
+        type: "input_text",
+        text: `<file name="${filename}" mime="application/pdf">\n${text}${truncNote}\n</file>`,
+      };
+    } catch (extractErr) {
+      // pdfjs 抽取失败（import 失败 / pdf 解析失败）→ graceful degradation
+      return {
+        type: "input_text",
+        text: `[file: ${filename}] (PDF content could not be extracted. Switch to a model that supports PDF, such as claude-opus-4.)`,
+      };
+    }
+  }
+
+  // ─── kind = text ────────────────────────────────────────────────────────
+
+  if (attachmentKind === "text") {
+    // no caps check
+    const mime = mediaType;
+    const filename = name;
+    try {
+      let content;
+      if (typeof fetchAndDecodeText === "function") {
+        content = await fetchAndDecodeText(url, { sizeCapBytes: TEXT_CHAR_CAP });
+      } else {
+        // fallback: use fetchAndBase64Encode + decode
+        const { base64, bytes } = await fetchAndBase64Encode(url, {
+          sizeCapBytes: TEXT_CHAR_CAP,
+        });
+        content = Buffer.from(base64, "base64").toString("utf-8");
+        if (bytes > TEXT_CHAR_CAP) {
+          content = content.slice(0, TEXT_CHAR_CAP);
+          content += `\n... [truncated, original size: ${bytes} bytes]`;
+        }
+      }
+      // 字符数截断
+      let truncNote = "";
+      if (content.length > TEXT_CHAR_CAP) {
+        truncNote = `\n... [truncated, original size: ${sizeBytes ?? content.length} bytes]`;
+        content = content.slice(0, TEXT_CHAR_CAP) + truncNote;
+      }
+      return {
+        type: "input_text",
+        text: `<file name="${filename}" mime="${mime}">\n${content}\n</file>`,
+      };
+    } catch (err) {
+      const msg = err?.message ?? String(err);
+      return {
+        type: "input_text",
+        text: `[file: ${filename}] (download failed: ${msg})`,
+      };
+    }
+  }
+
+  // ─── kind = binary ───────────────────────────────────────────────────────
+
+  // binary：描述 + no byte fetch；hint_url 仅 meta 返回（不进 LLM input）
+  const sizeDesc = sizeBytes != null ? `${sizeBytes} bytes` : "unknown size";
+  const mime = mediaType;
+  const filename = name;
+  const description = `[file: ${filename}] (type: ${mime}, size: ${sizeDesc}) — binary content cannot be inlined for the language model.`;
+
+  // hint_url: caller が必要なら block.source.url を参照可能（返り値には含めない）
+  // 鉄則 #1：URL は LLM context に入れない
+  return {
+    type: "input_text",
+    text: description,
+  };
+}
+
+// ── private: pdfjs text extraction ───────────────────────────────────────────
+
+/**
+ * PDF bytes から pdfjs-dist を使ってテキストを抽出する。
+ * pdfjs-dist が利用不可の場合は throw して caller が graceful degradation する。
+ */
+async function _extractPdfText(pdfBuffer, { cap = TEXT_CHAR_CAP } = {}) {
+  // dynamic import で pdfjs-dist を読み込む（未インストール時は throw → caller が catch）
+  let pdfjsLib;
+  try {
+    pdfjsLib = await import("pdfjs-dist/legacy/build/pdf.mjs");
+  } catch (_e) {
+    // try alternate import path
+    try {
+      pdfjsLib = await import("pdfjs-dist");
+    } catch (_e2) {
+      throw new Error("pdfjs-dist not available");
+    }
+  }
+
+  const loadingTask = pdfjsLib.getDocument({ data: new Uint8Array(pdfBuffer) });
+  const pdf = await loadingTask.promise;
+  const parts = [];
+  let totalChars = 0;
+
+  for (let pageNum = 1; pageNum <= pdf.numPages; pageNum++) {
+    if (totalChars >= cap) break;
+    const page = await pdf.getPage(pageNum);
+    const content = await page.getTextContent();
+    const pageText = content.items.map((item) => item.str ?? "").join(" ");
+    const remaining = cap - totalChars;
+    if (pageText.length > remaining) {
+      parts.push(pageText.slice(0, remaining));
+      totalChars += remaining;
+      break;
+    }
+    parts.push(pageText);
+    totalChars += pageText.length;
+  }
+
+  return parts.join("\n");
+}