@yanhaidao/wecom 2.3.3 → 2.3.9

package/src/app/bootstrap.ts

@@ -0,0 +1,29 @@
+import type { ChannelGatewayContext } from "openclaw/plugin-sdk";
+
+import { resolveWecomRuntimeAccount } from "../config/runtime-config.js";
+import type { ResolvedWecomAccount } from "../types/index.js";
+import { WecomAccountRuntime } from "./account-runtime.js";
+import { getWecomRuntime } from "./index.js";
+
+export function createAccountRuntime(ctx: ChannelGatewayContext<ResolvedWecomAccount>): WecomAccountRuntime {
+  const resolved = resolveWecomRuntimeAccount({
+    cfg: ctx.cfg,
+    accountId: ctx.accountId,
+  });
+  return new WecomAccountRuntime(
+    getWecomRuntime(),
+    ctx.cfg,
+    resolved,
+    {
+      info: (message) => ctx.log?.info(message),
+      warn: (message) => ctx.log?.warn(message),
+      error: (message) => ctx.log?.error(message),
+    },
+    (snapshot) => {
+      ctx.setStatus({
+        accountId: ctx.accountId,
+        ...snapshot,
+      });
+    },
+  );
+}

package/src/app/index.ts

@@ -0,0 +1,31 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+import { WecomAccountRuntime } from "./account-runtime.js";
+
+let runtime: PluginRuntime | null = null;
+const runtimes = new Map<string, WecomAccountRuntime>();
+
+export function setWecomRuntime(next: PluginRuntime): void {
+  runtime = next;
+}
+
+export function getWecomRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("WeCom runtime not initialized");
+  }
+  return runtime;
+}
+
+export function registerAccountRuntime(accountRuntime: WecomAccountRuntime): void {
+  runtimes.set(accountRuntime.account.accountId, accountRuntime);
+  console.log(`[wecom-runtime] register account=${accountRuntime.account.accountId}`);
+}
+
+export function getAccountRuntimeSnapshot(accountId: string) {
+  return runtimes.get(accountId)?.buildRuntimeStatus();
+}
+
+export function unregisterAccountRuntime(accountId: string): void {
+  runtimes.delete(accountId);
+  console.log(`[wecom-runtime] unregister account=${accountId}`);
+}

package/src/capability/agent/delivery-service.ts

@@ -0,0 +1,79 @@
+import type { ResolvedAgentAccount } from "../../types/index.js";
+import { resolveScopedWecomTarget } from "../../target.js";
+import { deliverAgentApiMedia, deliverAgentApiText } from "../../transport/agent-api/delivery.js";
+import { canUseAgentApiDelivery } from "./fallback-policy.js";
+
+export class WecomAgentDeliveryService {
+  constructor(private readonly agent: ResolvedAgentAccount) {}
+
+  assertAvailable(): void {
+    if (!canUseAgentApiDelivery(this.agent)) {
+      throw new Error(
+        `WeCom outbound requires channels.wecom.accounts.<accountId>.agent.agentId (or legacy channels.wecom.agent.agentId) for account=${this.agent.accountId}.`,
+      );
+    }
+  }
+
+  resolveTargetOrThrow(to: string | undefined) {
+    const scoped = resolveScopedWecomTarget(to, this.agent.accountId);
+    if (!scoped) {
+      console.error(`[wecom-agent-delivery] missing target account=${this.agent.accountId}`);
+      throw new Error("WeCom outbound requires a target (userid, partyid, tagid or chatid).");
+    }
+    if (scoped.accountId && scoped.accountId !== this.agent.accountId) {
+      console.error(
+        `[wecom-agent-delivery] account mismatch current=${this.agent.accountId} targetAccount=${scoped.accountId} raw=${String(to ?? "")}`,
+      );
+      throw new Error(
+        `WeCom outbound account mismatch: target belongs to account=${scoped.accountId}, current account=${this.agent.accountId}.`,
+      );
+    }
+    const target = scoped.target;
+    if (target.chatid) {
+      console.warn(
+        `[wecom-agent-delivery] blocked chat target account=${this.agent.accountId} chatId=${target.chatid}`,
+      );
+      throw new Error(
+        `企业微信（WeCom）Agent 主动发送不支持向群 chatId 发送（chatId=${target.chatid}）。` +
+          `该路径在实际环境中经常失败（例如 86008：无权限访问该会话/会话由其他应用创建）。` +
+          `请改为发送给用户（userid / user:xxx），或由 Bot 模式在群内交付。`,
+      );
+    }
+    return target;
+  }
+
+  async sendText(params: { to: string | undefined; text: string }): Promise<void> {
+    this.assertAvailable();
+    const target = this.resolveTargetOrThrow(params.to);
+    console.log(
+      `[wecom-agent-delivery] sendText account=${this.agent.accountId} to=${String(params.to ?? "")} len=${params.text.length}`,
+    );
+    await deliverAgentApiText({
+      agent: this.agent,
+      target,
+      text: params.text,
+    });
+  }
+
+  async sendMedia(params: {
+    to: string | undefined;
+    text?: string;
+    buffer: Buffer;
+    filename: string;
+    contentType: string;
+  }): Promise<void> {
+    this.assertAvailable();
+    const target = this.resolveTargetOrThrow(params.to);
+    console.log(
+      `[wecom-agent-delivery] sendMedia account=${this.agent.accountId} to=${String(params.to ?? "")} filename=${params.filename} contentType=${params.contentType}`,
+    );
+    await deliverAgentApiMedia({
+      agent: this.agent,
+      target,
+      buffer: params.buffer,
+      filename: params.filename,
+      contentType: params.contentType,
+      text: params.text,
+    });
+  }
+}

package/src/capability/agent/fallback-policy.ts

@@ -0,0 +1,13 @@
+import type { ResolvedAgentAccount } from "../../types/index.js";
+
+export function canUseAgentApiDelivery(agent: ResolvedAgentAccount | undefined): boolean {
+  return Boolean(agent?.apiConfigured && typeof agent.agentId === "number");
+}
+
+export function shouldFallbackToAgentApi(params: {
+  agent: ResolvedAgentAccount | undefined;
+  hasText?: boolean;
+  hasMedia?: boolean;
+}): boolean {
+  return canUseAgentApiDelivery(params.agent) && Boolean(params.hasText || params.hasMedia);
+}

package/src/capability/agent/index.ts

@@ -0,0 +1,3 @@
+export { WecomAgentIngressService } from "./ingress-service.js";
+export { WecomAgentDeliveryService } from "./delivery-service.js";
+export { canUseAgentApiDelivery, shouldFallbackToAgentApi } from "./fallback-policy.js";

package/src/capability/agent/ingress-service.ts

@@ -0,0 +1,38 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+import type { WecomRuntimeEnv } from "../../types/runtime-context.js";
+import type { WecomAccountRuntime } from "../../app/account-runtime.js";
+import { startAgentCallbackTransport } from "../../transport/agent-callback/http-handler.js";
+
+export class WecomAgentIngressService {
+  private stopTransport?: () => void;
+
+  constructor(
+    private readonly runtime: WecomAccountRuntime,
+    private readonly cfg: OpenClawConfig,
+    private readonly runtimeEnv: WecomRuntimeEnv,
+  ) {}
+
+  start(): { transport: "agent-callback"; descriptors: string[] } | undefined {
+    const agent = this.runtime.account.agent;
+    if (!agent?.callbackConfigured) {
+      return undefined;
+    }
+    const callback = startAgentCallbackTransport({
+      account: agent,
+      cfg: this.cfg,
+      runtime: this.runtime,
+      runtimeEnv: this.runtimeEnv,
+    });
+    this.stopTransport = callback.stop;
+    return {
+      transport: "agent-callback",
+      descriptors: callback.paths,
+    };
+  }
+
+  stop(): void {
+    this.stopTransport?.();
+    this.stopTransport = undefined;
+  }
+}

package/src/capability/bot/dispatch-config.ts

@@ -0,0 +1,47 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+export function buildWecomBotDispatchConfig(config: OpenClawConfig): OpenClawConfig {
+  const baseAgents = (config as any)?.agents ?? {};
+  const baseAgentDefaults = (baseAgents as any)?.defaults ?? {};
+  const baseBlockChunk = (baseAgentDefaults as any)?.blockStreamingChunk ?? {};
+  const baseBlockCoalesce = (baseAgentDefaults as any)?.blockStreamingCoalesce ?? {};
+  const baseTools = (config as any)?.tools ?? {};
+  const baseSandbox = (baseTools as any)?.sandbox ?? {};
+  const baseSandboxTools = (baseSandbox as any)?.tools ?? {};
+  const existingTopLevelDeny = Array.isArray((baseTools as any).deny) ? ((baseTools as any).deny as string[]) : [];
+  const existingSandboxDeny = Array.isArray((baseSandboxTools as any).deny) ? ((baseSandboxTools as any).deny as string[]) : [];
+  const topLevelDeny = Array.from(new Set([...existingTopLevelDeny, "message"]));
+  const sandboxDeny = Array.from(new Set([...existingSandboxDeny, "message"]));
+  return {
+    ...(config as any),
+    agents: {
+      ...baseAgents,
+      defaults: {
+        ...baseAgentDefaults,
+        blockStreamingChunk: {
+          ...baseBlockChunk,
+          minChars: baseBlockChunk.minChars ?? 120,
+          maxChars: baseBlockChunk.maxChars ?? 360,
+          breakPreference: baseBlockChunk.breakPreference ?? "sentence",
+        },
+        blockStreamingCoalesce: {
+          ...baseBlockCoalesce,
+          minChars: baseBlockCoalesce.minChars ?? 120,
+          maxChars: baseBlockCoalesce.maxChars ?? 360,
+          idleMs: baseBlockCoalesce.idleMs ?? 250,
+        },
+      },
+    },
+    tools: {
+      ...baseTools,
+      deny: topLevelDeny,
+      sandbox: {
+        ...baseSandbox,
+        tools: {
+          ...baseSandboxTools,
+          deny: sandboxDeny,
+        },
+      },
+    },
+  } as OpenClawConfig;
+}

package/src/capability/bot/fallback-delivery.ts

@@ -0,0 +1,178 @@
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk";
+
+import { resolveWecomAccount } from "../../config/index.js";
+import { wecomFetch } from "../../http.js";
+import { LIMITS } from "../../monitor/state.js";
+import type { StreamState } from "../../types/legacy-stream.js";
+import type { ResolvedAgentAccount } from "../../types/index.js";
+import { sendMedia as sendAgentMedia, sendText as sendAgentText, uploadMedia } from "../../transport/agent-api/core.js";
+import { buildStreamReplyFromState } from "../../transport/bot-webhook/protocol.js";
+import { useActiveReplyOnce } from "../../transport/bot-webhook/active-reply.js";
+import { guessContentTypeFromPath } from "../../transport/bot-webhook/inbound-normalizer.js";
+
+const STREAM_MAX_DM_BYTES = 200_000;
+
+export function appendDmContent(state: StreamState, text: string): void {
+  const next = state.dmContent ? `${state.dmContent}\n\n${text}`.trim() : text.trim();
+  const buf = Buffer.from(next, "utf8");
+  state.dmContent = buf.length <= STREAM_MAX_DM_BYTES ? next : buf.subarray(buf.length - STREAM_MAX_DM_BYTES).toString("utf8");
+}
+
+export function resolveAgentAccountOrUndefined(cfg: OpenClawConfig, accountId: string): ResolvedAgentAccount | undefined {
+  const agent = resolveWecomAccount({ cfg, accountId }).agent;
+  return agent?.configured ? agent : undefined;
+}
+
+export function buildFallbackPrompt(params: {
+  kind: "media" | "timeout" | "error";
+  agentConfigured: boolean;
+  userId?: string;
+  filename?: string;
+  chatType?: "group" | "direct";
+}): string {
+  const who = params.userId ? `（${params.userId}）` : "";
+  const scope = params.chatType === "group" ? "群聊" : params.chatType === "direct" ? "私聊" : "会话";
+  if (!params.agentConfigured) {
+    return `${scope}中需要通过应用私信发送${params.filename ? `（${params.filename}）` : ""}，但管理员尚未配置企业微信自建应用（Agent）通道。请联系管理员配置后再试。${who}`.trim();
+  }
+  if (!params.userId) {
+    return `${scope}中需要通过应用私信兜底发送${params.filename ? `（${params.filename}）` : ""}，但本次回调未能识别触发者 userid（请检查企微回调字段 from.userid / fromuserid）。请联系管理员排查配置。`.trim();
+  }
+  if (params.kind === "media") {
+    return `已生成文件${params.filename ? `（${params.filename}）` : ""}，将通过应用私信发送给你。${who}`.trim();
+  }
+  if (params.kind === "timeout") {
+    return `内容较长，为避免超时，后续内容将通过应用私信发送给你。${who}`.trim();
+  }
+  return `交付出现异常，已尝试通过应用私信发送给你。${who}`.trim();
+}
+
+export async function sendBotFallbackPromptNow(params: { streamId: string; text: string }): Promise<void> {
+  await useActiveReplyOnce(params.streamId, async ({ responseUrl, proxyUrl }) => {
+    const payload = {
+      msgtype: "stream",
+      stream: {
+        id: params.streamId,
+        finish: true,
+        content: params.text.trim() || "1",
+      },
+    };
+    const res = await wecomFetch(
+      responseUrl,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      },
+      { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS },
+    );
+    if (!res.ok) {
+      throw new Error(`fallback prompt push failed: ${res.status}`);
+    }
+  });
+}
+
+export async function pushFinalStreamReplyNow(params: { streamId: string; state: StreamState }): Promise<void> {
+  const finalReply = buildStreamReplyFromState(params.state) as unknown as Record<string, unknown>;
+  await useActiveReplyOnce(params.streamId, async ({ responseUrl, proxyUrl }) => {
+    const res = await wecomFetch(
+      responseUrl,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(finalReply),
+      },
+      { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS },
+    );
+    if (!res.ok) {
+      throw new Error(`final stream push failed: ${res.status}`);
+    }
+  });
+}
+
+export async function sendAgentDmText(params: {
+  agent: ResolvedAgentAccount;
+  userId: string;
+  text: string;
+  core: PluginRuntime;
+}): Promise<void> {
+  const chunks = params.core.channel.text.chunkText(params.text, 20480);
+  for (const chunk of chunks) {
+    const trimmed = chunk.trim();
+    if (!trimmed) continue;
+    await sendAgentText({ agent: params.agent, toUser: params.userId, text: trimmed });
+  }
+}
+
+export async function sendAgentDmMedia(params: {
+  agent: ResolvedAgentAccount;
+  userId: string;
+  mediaUrlOrPath: string;
+  contentType?: string;
+  filename: string;
+}): Promise<void> {
+  let buffer: Buffer;
+  let inferredContentType = params.contentType;
+  const looksLikeUrl = /^https?:\/\//i.test(params.mediaUrlOrPath);
+  if (looksLikeUrl) {
+    const res = await fetch(params.mediaUrlOrPath, { signal: AbortSignal.timeout(30_000) });
+    if (!res.ok) throw new Error(`media download failed: ${res.status}`);
+    buffer = Buffer.from(await res.arrayBuffer());
+    inferredContentType = inferredContentType || res.headers.get("content-type") || "application/octet-stream";
+  } else {
+    const fs = await import("node:fs/promises");
+    buffer = await fs.readFile(params.mediaUrlOrPath);
+  }
+
+  let mediaType: "image" | "voice" | "video" | "file" = "file";
+  const ct = (inferredContentType || "").toLowerCase();
+  if (ct.startsWith("image/")) mediaType = "image";
+  else if (ct.startsWith("audio/")) mediaType = "voice";
+  else if (ct.startsWith("video/")) mediaType = "video";
+
+  const mediaId = await uploadMedia({
+    agent: params.agent,
+    type: mediaType,
+    buffer,
+    filename: params.filename,
+  });
+  await sendAgentMedia({
+    agent: params.agent,
+    toUser: params.userId,
+    mediaId,
+    mediaType,
+  });
+}
+
+export function extractLocalImagePathsFromText(params: { text: string; mustAlsoAppearIn: string }): string[] {
+  const text = params.text;
+  const mustAlsoAppearIn = params.mustAlsoAppearIn;
+  if (!text.trim()) return [];
+  const exts = "(png|jpg|jpeg|gif|webp|bmp)";
+  const re = new RegExp(String.raw`(\/(?:Users|tmp|root|home)\/[^\s"'<>]+?\.${exts})`, "gi");
+  const found = new Set<string>();
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text))) {
+    const p = m[1];
+    if (!p) continue;
+    if (!mustAlsoAppearIn.includes(p)) continue;
+    found.add(p);
+  }
+  return Array.from(found);
+}
+
+export function extractLocalFilePathsFromText(text: string): string[] {
+  if (!text.trim()) return [];
+  const re = /\/(?:Users|tmp|root|home)\/[^\s"'<>]+/g;
+  const found = new Set<string>();
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(text))) {
+    const p = m[0]?.trim();
+    if (p) found.add(p);
+  }
+  return Array.from(found);
+}
+
+export function guessLocalPathContentType(filePath: string): string | undefined {
+  return guessContentTypeFromPath(filePath);
+}

package/src/capability/bot/index.ts

@@ -0,0 +1 @@
+export { WecomBotCapabilityService } from "./service.js";

package/src/capability/bot/local-path-delivery.ts

@@ -0,0 +1,215 @@
+import crypto from "node:crypto";
+
+import { wecomFetch } from "../../http.js";
+import { LIMITS, type StreamStore } from "../../monitor/state.js";
+import { getActiveReplyUrl, useActiveReplyOnce } from "../../transport/bot-webhook/active-reply.js";
+import type { WecomWebhookTarget } from "../../types/runtime-context.js";
+import { buildStreamReplyFromState } from "../../transport/bot-webhook/protocol.js";
+import {
+  buildFallbackPrompt,
+  extractLocalFilePathsFromText,
+  guessLocalPathContentType,
+  resolveAgentAccountOrUndefined,
+  sendAgentDmMedia,
+  sendBotFallbackPromptNow,
+} from "./fallback-delivery.js";
+import type { BotRuntimeLogger } from "./types.js";
+
+export async function handleDirectLocalPathIntent(params: {
+  streamStore: StreamStore;
+  target: WecomWebhookTarget;
+  streamId: string;
+  rawBody: string;
+  userId: string;
+  chatType: "group" | "direct";
+  logVerbose: BotRuntimeLogger;
+  looksLikeSendLocalFileIntent: (rawBody: string) => boolean;
+}): Promise<boolean> {
+  const { streamStore, target, streamId, rawBody, userId, chatType, logVerbose, looksLikeSendLocalFileIntent } = params;
+  const directLocalPaths = extractLocalFilePathsFromText(rawBody);
+  if (directLocalPaths.length) {
+    logVerbose(
+      target,
+      `local-path: 检测到用户消息包含本机路径 count=${directLocalPaths.length} intent=${looksLikeSendLocalFileIntent(rawBody)}`,
+    );
+  }
+  if (!directLocalPaths.length || !looksLikeSendLocalFileIntent(rawBody)) {
+    return false;
+  }
+
+  const fs = await import("node:fs/promises");
+  const pathModule = await import("node:path");
+  const imageExts = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp"]);
+
+  const imagePaths: string[] = [];
+  const otherPaths: string[] = [];
+  for (const p of directLocalPaths) {
+    const ext = pathModule.extname(p).slice(1).toLowerCase();
+    if (imageExts.has(ext)) imagePaths.push(p);
+    else otherPaths.push(p);
+  }
+
+  if (imagePaths.length > 0 && otherPaths.length === 0) {
+    const loaded: Array<{ base64: string; md5: string; path: string }> = [];
+    for (const p of imagePaths) {
+      try {
+        const buf = await fs.readFile(p);
+        const base64 = buf.toString("base64");
+        const md5 = crypto.createHash("md5").update(buf).digest("hex");
+        loaded.push({ base64, md5, path: p });
+      } catch (err) {
+        target.runtime.error?.(`local-path: 读取图片失败 path=${p}: ${String(err)}`);
+      }
+    }
+
+    if (loaded.length > 0) {
+      streamStore.updateStream(streamId, (s) => {
+        s.images = loaded.map(({ base64, md5 }) => ({ base64, md5 }));
+        s.content = loaded.length === 1 ? `已发送图片（${pathModule.basename(loaded[0]!.path)}）` : `已发送 ${loaded.length} 张图片`;
+        s.finished = true;
+      });
+
+      const responseUrl = getActiveReplyUrl(streamId);
+      if (responseUrl) {
+        try {
+          const finalReply = buildStreamReplyFromState(streamStore.getStream(streamId)!) as unknown as Record<string, unknown>;
+          await useActiveReplyOnce(streamId, async ({ responseUrl, proxyUrl }) => {
+            const res = await wecomFetch(
+              responseUrl,
+              {
+                method: "POST",
+                headers: { "Content-Type": "application/json" },
+                body: JSON.stringify(finalReply),
+              },
+              { proxyUrl, timeoutMs: LIMITS.REQUEST_TIMEOUT_MS },
+            );
+            if (!res.ok) throw new Error(`local-path image push failed: ${res.status}`);
+          });
+          logVerbose(target, `local-path: 已通过 Bot response_url 推送图片 frames=final images=${loaded.length}`);
+        } catch (err) {
+          target.runtime.error?.(`local-path: Bot 主动推送图片失败（将依赖 stream_refresh 拉取）: ${String(err)}`);
+        }
+      } else {
+        logVerbose(target, "local-path: 无 response_url，等待 stream_refresh 拉取最终图片");
+      }
+      streamStore.onStreamFinished(streamId);
+      return true;
+    }
+
+    const agentCfg = resolveAgentAccountOrUndefined(target.config, target.account.accountId);
+    const agentOk = Boolean(agentCfg);
+    const fallbackName = imagePaths.length === 1 ? (imagePaths[0]!.split("/").pop() || "image") : `${imagePaths.length} 张图片`;
+    const prompt = buildFallbackPrompt({
+      kind: "media",
+      agentConfigured: agentOk,
+      userId,
+      filename: fallbackName,
+      chatType,
+    });
+
+    streamStore.updateStream(streamId, (s) => {
+      s.fallbackMode = "error";
+      s.finished = true;
+      s.content = prompt;
+      s.fallbackPromptSentAt = s.fallbackPromptSentAt ?? Date.now();
+    });
+
+    try {
+      await sendBotFallbackPromptNow({ streamId, text: prompt });
+      logVerbose(target, "local-path: 图片读取失败后已推送兜底提示");
+    } catch (err) {
+      target.runtime.error?.(`local-path: 图片读取失败后的兜底提示推送失败: ${String(err)}`);
+    }
+
+    if (agentCfg && userId && userId !== "unknown") {
+      for (const p of imagePaths) {
+        const guessedType = guessLocalPathContentType(p);
+        try {
+          await sendAgentDmMedia({
+            agent: agentCfg,
+            userId,
+            mediaUrlOrPath: p,
+            contentType: guessedType,
+            filename: p.split("/").pop() || "image",
+          });
+          streamStore.updateStream(streamId, (s) => {
+            s.agentMediaKeys = Array.from(new Set([...(s.agentMediaKeys ?? []), p]));
+          });
+          logVerbose(
+            target,
+            `local-path: 图片已通过 Agent 私信发送 user=${userId} path=${p} contentType=${guessedType ?? "unknown"}`,
+          );
+        } catch (err) {
+          target.runtime.error?.(`local-path: 图片 Agent 私信兜底失败 path=${p}: ${String(err)}`);
+        }
+      }
+    }
+    streamStore.onStreamFinished(streamId);
+    return true;
+  }
+
+  if (otherPaths.length > 0) {
+    const agentCfg = resolveAgentAccountOrUndefined(target.config, target.account.accountId);
+    const agentOk = Boolean(agentCfg);
+    const filename = otherPaths.length === 1 ? otherPaths[0]!.split("/").pop()! : `${otherPaths.length} 个文件`;
+    const prompt = buildFallbackPrompt({
+      kind: "media",
+      agentConfigured: agentOk,
+      userId,
+      filename,
+      chatType,
+    });
+
+    streamStore.updateStream(streamId, (s) => {
+      s.fallbackMode = "media";
+      s.finished = true;
+      s.content = prompt;
+      s.fallbackPromptSentAt = s.fallbackPromptSentAt ?? Date.now();
+    });
+
+    try {
+      await sendBotFallbackPromptNow({ streamId, text: prompt });
+      logVerbose(target, "local-path: 文件兜底提示已推送");
+    } catch (err) {
+      target.runtime.error?.(`local-path: 文件兜底提示推送失败: ${String(err)}`);
+    }
+
+    if (!agentCfg) {
+      streamStore.onStreamFinished(streamId);
+      return true;
+    }
+    if (!userId || userId === "unknown") {
+      target.runtime.error?.("local-path: 无法识别触发者 userId，无法 Agent 私信发送文件");
+      streamStore.onStreamFinished(streamId);
+      return true;
+    }
+
+    for (const p of otherPaths) {
+      const alreadySent = streamStore.getStream(streamId)?.agentMediaKeys?.includes(p);
+      if (alreadySent) continue;
+      const guessedType = guessLocalPathContentType(p);
+      try {
+        await sendAgentDmMedia({
+          agent: agentCfg,
+          userId,
+          mediaUrlOrPath: p,
+          contentType: guessedType,
+          filename: p.split("/").pop() || "file",
+        });
+        streamStore.updateStream(streamId, (s) => {
+          s.agentMediaKeys = Array.from(new Set([...(s.agentMediaKeys ?? []), p]));
+        });
+        logVerbose(
+          target,
+          `local-path: 文件已通过 Agent 私信发送 user=${userId} path=${p} contentType=${guessedType ?? "unknown"}`,
+        );
+      } catch (err) {
+        target.runtime.error?.(`local-path: Agent 私信发送文件失败 path=${p}: ${String(err)}`);
+      }
+    }
+    streamStore.onStreamFinished(streamId);
+    return true;
+  }
+
+  return false;
+}