@xgjktech/xg_cwork_im 1.0.8 → 1.10.0

package/src/inbound-media-local.ts

@@ -0,0 +1,199 @@
+/**
+ * 入站附件：可选落盘到当前 Agent workspace 下指定子目录（相对路径）。
+ *
+ * 目录约定：{subdir}/{userId}/{YYYY-MM-DD}/{stem}_{HHmmssmmm}{ext}
+ * 时间取写入时的本地时区。
+ */
+
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { Log } from "./auth.js";
+import { downloadMediaBuffer, resolveMaxAttachmentBytes } from "./resource-file.js";
+import type { MsgFileVO, XgImConfig } from "./types.js";
+
+/** 校验：非空、相对路径、不含 `..` 段 */
+export function normalizeInboundWorkspaceSubdir(subdir: string): string | null {
+    const t = subdir.trim().replace(/\\/g, "/");
+    if (!t || t === "." || t === "..") return null;
+    const parts = t.split("/").filter(Boolean);
+    for (const p of parts) {
+        if (p === "..") return null;
+    }
+    if (path.isAbsolute(t)) return null;
+    return parts.join("/");
+}
+
+export function resolveAgentWorkspaceDirFromRuntime(rt: unknown, cfg: OpenClawConfig): string | undefined {
+    const agent = (rt as { agent?: { resolveAgentWorkspaceDir?: (c: OpenClawConfig) => unknown } })?.agent;
+    const fn = agent?.resolveAgentWorkspaceDir;
+    if (typeof fn !== "function") return undefined;
+    try {
+        const out = fn(cfg);
+        if (typeof out === "string" && out.trim()) return path.resolve(out.trim());
+    } catch {
+        /* ignore */
+    }
+    return undefined;
+}
+
+export async function ensureAgentWorkspaceFromRuntime(rt: unknown, cfg: OpenClawConfig): Promise<void> {
+    const agent = (rt as { agent?: { ensureAgentWorkspace?: (c: OpenClawConfig) => Promise<void> } })?.agent;
+    const fn = agent?.ensureAgentWorkspace;
+    if (typeof fn !== "function") return;
+    try {
+        await fn(cfg);
+    } catch {
+        /* 落盘前仍会 mkdir，不阻断 */
+    }
+}
+
+function sanitizeUserIdForPath(id: string): string {
+    const t = id.trim();
+    if (/^-?\d+$/.test(t) && t.length <= 32) return t;
+    const safe = t.replace(/[^\w.-]/g, "_").replace(/_+/g, "_").replace(/^_|_$/g, "");
+    return safe.slice(0, 64) || "unknown";
+}
+
+function formatDateFolderLocal(d: Date): string {
+    const y = d.getFullYear();
+    const m = String(d.getMonth() + 1).padStart(2, "0");
+    const day = String(d.getDate()).padStart(2, "0");
+    return `${y}-${m}-${day}`;
+}
+
+/** `HHmmss` + 三位毫秒，如 `120459237` */
+export function formatInboundTimeSuffix(d: Date): string {
+    const h = String(d.getHours()).padStart(2, "0");
+    const min = String(d.getMinutes()).padStart(2, "0");
+    const s = String(d.getSeconds()).padStart(2, "0");
+    const ms = String(d.getMilliseconds()).padStart(3, "0");
+    return `${h}${min}${s}${ms}`;
+}
+
+const MAX_STEM_LEN = 120;
+
+function sanitizeStem(stem: string): string {
+    const s = stem
+        .replace(/[<>:"/\\|?*\u0000-\u001f]/g, "_")
+        .replace(/_+/g, "_")
+        .replace(/^\.+|\.+$/g, "")
+        .trim();
+    const out = s || "file";
+    return out.length > MAX_STEM_LEN ? out.slice(0, MAX_STEM_LEN) : out;
+}
+
+/**
+ * 将落盘绝对路径转为 OpenClaw / 沙箱可用的 workspace 相对引用（POSIX 风格，带 `./` 前缀）。
+ * 若文件不在 workspaceRoot 之下则返回 null（调用方应回退 file:// 或报错）。
+ */
+export function absPathToWorkspaceRelativeOpenClawRef(workspaceRoot: string, absPath: string): string | null {
+    const root = path.resolve(workspaceRoot.trim());
+    const abs = path.resolve(absPath);
+    const rel = path.relative(root, abs);
+    if (rel.startsWith("..") || path.isAbsolute(rel)) return null;
+    const piece = rel.length > 0 ? rel : path.basename(abs);
+    const posix = piece.split(path.sep).join("/");
+    return posix.startsWith("./") ? posix : `./${posix}`;
+}
+
+function openClawMediaRefForSavedFile(args: {
+    workspaceRoot: string;
+    absPath: string;
+    style: "workspaceRelative" | "absoluteFileUrl" | undefined;
+    log?: Log;
+}): string {
+    const { workspaceRoot, absPath, style, log } = args;
+    if (style === "absoluteFileUrl") {
+        return pathToFileURL(absPath).href;
+    }
+    const rel = absPathToWorkspaceRelativeOpenClawRef(workspaceRoot, absPath);
+    if (rel) return rel;
+    log?.warn?.(
+        `[cwork_im:inbound-local] file not under workspace root, fallback to file:// absPath=${absPath.slice(0, 120)}`,
+    );
+    return pathToFileURL(absPath).href;
+}
+
+/** `report_120459237.pdf` */
+export function buildInboundStoredFilename(originalFilename: string, at: Date): string {
+    const base = path.basename(originalFilename) || "file";
+    const ext = path.extname(base);
+    const stem = ext ? base.slice(0, -ext.length) : base;
+    const suffix = formatInboundTimeSuffix(at);
+    return `${sanitizeStem(stem)}_${suffix}${ext.toLowerCase()}`;
+}
+
+/**
+ * 将入站附件下载到 workspace 下子目录；失败项保留原 URL。
+ */
+export async function saveInboundFilesToWorkspace(args: {
+    rt: unknown;
+    cfg: OpenClawConfig;
+    config: XgImConfig;
+    workspaceSubdir: string;
+    senderUserId: string | undefined;
+    fileItems: MsgFileVO[];
+    log?: Log;
+}): Promise<MsgFileVO[]> {
+    const { rt, cfg, config, workspaceSubdir, senderUserId, fileItems, log } = args;
+    const normalized = normalizeInboundWorkspaceSubdir(workspaceSubdir);
+    if (!normalized || fileItems.length === 0) return fileItems;
+
+    const workspaceRoot = resolveAgentWorkspaceDirFromRuntime(rt, cfg);
+    if (!workspaceRoot) {
+        log?.warn?.(
+            "[cwork_im:inbound-local] resolveAgentWorkspaceDir unavailable, skip inbound download; keep remote URLs",
+        );
+        return fileItems;
+    }
+
+    await ensureAgentWorkspaceFromRuntime(rt, cfg);
+
+    const maxBytes = resolveMaxAttachmentBytes(config);
+    const userSeg = sanitizeUserIdForPath(senderUserId ?? "unknown");
+    const relParts = normalized.split("/");
+
+    const out: MsgFileVO[] = [];
+    for (const item of fileItems) {
+        const srcUrl = item.url?.trim();
+        if (!srcUrl) {
+            out.push(item);
+            continue;
+        }
+        const now = new Date();
+        const dateFolder = formatDateFolderLocal(now);
+        const localName = buildInboundStoredFilename(item.name?.trim() || "file", now);
+        const dir = path.join(workspaceRoot, ...relParts, userSeg, dateFolder);
+        const absPath = path.join(dir, localName);
+
+        try {
+            await mkdir(dir, { recursive: true });
+            const { buffer } = await downloadMediaBuffer(srcUrl, maxBytes, log);
+            await writeFile(absPath, buffer);
+            const pathStyle = config.inboundMediaOpenClawPath ?? "workspaceRelative";
+            const mediaRef = openClawMediaRefForSavedFile({
+                workspaceRoot,
+                absPath,
+                style: pathStyle,
+                log,
+            });
+            log?.info?.(
+                `[cwork_im:inbound-local] saved ${localName} bytes=${buffer.length} abs=${absPath} openclawRef=${mediaRef.slice(0, 120)}`,
+            );
+            out.push({
+                ...item,
+                url: mediaRef,
+                size: buffer.length,
+                name: localName,
+            });
+        } catch (e: unknown) {
+            log?.warn?.(
+                `[cwork_im:inbound-local] download/save failed, keep original URL: ${String(e)} ref=${srcUrl.slice(0, 80)}`,
+            );
+            out.push(item);
+        }
+    }
+    return out;
+}

package/src/types.ts

@@ -40,6 +40,14 @@ export interface XgImAccountConfig {
     /** multipart 整文件上传字段名，默认 file（与 `/file/upDownload/uploadWholeFile` 约定一致时可不改） */
     fileUploadFormField?: string;
     maxAttachmentBytes?: number;
+    /** 覆盖顶层的入站附件 workspace 子目录（相对 Agent workspace） */
+    inboundMediaWorkspaceSubdir?: string;
+    /**
+     * 覆盖顶层：入站落盘后交给 OpenClaw 的 `MediaPath` 形式。
+     * - `workspaceRelative`（默认）：`./xg_im_inbound/...`，沙箱内 `/workspace` 可解析。
+     * - `absoluteFileUrl`：宿主机 `file://...`，仅适合无沙箱、同进程读盘场景。
+     */
+    inboundMediaOpenClawPath?: "workspaceRelative" | "absoluteFileUrl";
 }
 
 export interface XgImConfig extends OpenClawConfig {
@@ -87,6 +95,18 @@ export interface XgImConfig extends OpenClawConfig {
     fileUploadFormField?: string;
     /** 单个附件下载/上传允许的最大字节数，默认 50MB */
     maxAttachmentBytes?: number;
+
+    /**
+     * 若配置为非空相对路径（相对于当前 Agent workspace 根目录）：入站附件会先下载到
+     * `{workspace}/{本字段}/{userId}/{YYYY-MM-DD}/{name}_{HHmmssmmm}.ext`，再向 OpenClaw 传入 **workspace 相对路径**（默认 `./子目录/...`，便于沙箱挂载 `/workspace`）或 `file://`（见 `inboundMediaOpenClawPath`）。
+     * 未配置或为空则仍使用 IM 返回的远程 URL。
+     */
+    inboundMediaWorkspaceSubdir?: string;
+    /**
+     * 入站落盘后写入 `MediaPath` 的引用形式；默认与 `workspaceRelative` 等价（未填时）。
+     * Agent 在沙箱中运行时应用 `workspaceRelative`，避免宿主机绝对 `file://` 在沙箱内不可读。
+     */
+    inboundMediaOpenClawPath?: "workspaceRelative" | "absoluteFileUrl";
 }
 
 // ─── IM 接口 Request / Response ─────────────────────────────────────────────
@@ -128,7 +148,7 @@ export interface WsMessage {
  * 与 IM 服务 `MsgFileVO` 对齐的附件项（WebSocket `msgContent.files[]`）。
  */
 export interface MsgFileVO {
-    /** 文件下载链接，短期有效 */
+    /** 远程下载链接，或入站落盘后的 `file://` / workspace 相对引用（如 `./xg_im_inbound/...`） */
     url: string;
     /** 文件格式，小写：pdf、png、docx、doc、ppt、txt、md 等 */
     format?: string;
@@ -138,6 +158,11 @@ export interface MsgFileVO {
     size?: number;
     /** 文件名称，如 xxx.pdf */
     name?: string;
+    /**
+     * IM 侧已解析的正文（如图片 OCR/说明、文档抽取的文本等）。
+     * 非空时插件会拼入入站 `Body`/`RawBody`，一并交给 OpenClaw。
+     */
+    content?: string;
 }
 
 /** @deprecated 使用 {@link MsgFileVO} */
@@ -175,7 +200,7 @@ export function imFormatToMimeType(format: string | undefined): string | undefin
  * 入站消息内容体（与 IM WebSocket `params.msgContent` 对齐）。
  *
  * - **type=`text`**：纯文本；**text** 建议非空。
- * - **type=`file`**：带 1..N 个文件，**files** 建议至少 1 项；**text** 可为配文（同时上传多文件 + 一句话）。
+ * - **type=`file`**：带 1..N 个文件，**files** 建议至少 1 项；**text** 可为配文（同时上传多文件 + 一句话）。**files[].content** 可由 IM 填已解析文本（如图/文档），插件会拼入入站正文。
  * - 语音在 IM 侧已转写为文字时，应以 **type=`text`** 推送转写结果，不再使用 voice。
  */
 export interface WsMessageContent {