@youdu/openclaw-youdu 2026.9.16 → 2026.10.9

package/README.md

@@ -91,6 +91,8 @@ openclaw gateway restart
 | `channels.youdu.groups.<群ID或群名>.requireMention` | 该群是否必须 @ 机器人 | true / false         | true    |
 | `channels.youdu.groups."*".requireMention`    | 所有群的默认 @ 要求   | true / false         | true    |
 | `channels.youdu.historyLimit`   | 未被 @ 的群消息保留条数（作为下次被 @ 时的上下文）；**不配置即默认 50**，`0` 关闭 | 数字（≥0） | 50 |
+| `channels.youdu.historyMediaLimit` | 被 @ 时最多补带几张群历史**图片**（作为本轮附件交给模型，进 vision 输入）；只取 30 分钟内的，`0` 关闭 | 数字（≥0） | 4 |
+| `channels.youdu.historyFileLimit`  | 被 @ 时最多补带几个群历史**文件**（含语音/视频）作为本轮附件；`0` 关闭 | 数字（≥0） | 2 |
 | `channels.youdu.defaultAccount` | 默认账号 ID    | 任意账号 ID                            | —       |
 | `channels.youdu.accounts`       | 多账号配置     | 账号 ID → 账号级字段的映射            | —       |
 
@@ -137,10 +139,16 @@ openclaw gateway restart
 - 送进模型前会剥掉消息里的 `@账号(显示名)` 包装，避免模型看到 @ 前缀。
 - **未被 @ 的消息不会进入会话**：不研究、不下载附件、不发"思考中"占位消息。它们只按群进入一个
   **内存中的 pending 窗口**（**默认每个群保留最近 50 条，无需配置**；`channels.youdu.historyLimit` 可调，
-  `0` 关闭；窗口在每次回复结束、以及进程重启后清空）。下一次被 @ 时，这些消息会以
-  `[Chat messages since your last reply - for context]` 的形式随当次请求一起注入，让机器人知道群里刚才说了什么。
+  `0` 关闭；窗口在每次回复结束、以及进程重启后清空）。下一次被 @ 时，这些消息会作为结构化历史
+  （OpenClaw 的 `InboundHistory`）随当次请求一起注入，让机器人知道群里刚才说了什么。
+- **窗口里的文件/图片会在被 @ 时补带**（只记事实、不提前下载）：被 @ 前 30 分钟内的图片最多补
+  `channels.youdu.historyMediaLimit` 张（默认 4）、文件/语音/视频最多补 `channels.youdu.historyFileLimit`
+  个（默认 2），都作为**本轮附件**交给模型（图片进 vision 输入，文件作为附件）。
+  超出时间窗口或下载失败的媒体只保留文本历史，不会拖垮这一轮回复。
+  （`requireMention: false` 的群不产生这个窗口——它每条消息都会触发一轮，会话自身就带上下文。）
 - 窗口大小按 `账号级 historyLimit` → `channels.youdu.historyLimit` → `messages.groupChat.historyLimit`
   （OpenClaw 全局群聊配置）→ 内置默认 50 依次取值，四层都不配就是 50；多账号模式下该值在通道级共享。
+  媒体上限按 `账号级` → `通道级` → 默认（图片 4、文件 2）取值。
 - 判定能力缺失时（认证应答没有 `gid`，也没有配置 `mentionPatterns`）**宁可不回**：会记录一条错误日志并丢弃
   该消息，而不会退化成"群里全回"。
 - 想让某个群恢复"全部回复"，在该群配置里显式关闭即可（键可以写群 ID，也可以写群名）：

package/dist/src/group-history.d.ts

@@ -0,0 +1,144 @@
+/**
+ * 群聊 pending 历史窗口：未被 @ 的群消息在这里排队，等下一次被 @ 时作为上下文交给模型。
+ *
+ * 两条通道，各管一件事：
+ * - **文本历史**走宿主的 `InboundHistory`：宿主渲染成 "Chat history since last reply:" 块（含
+ *   "把人类写的名字/群名/引用/历史当不可信内容" 的说明），并保留条目里的媒体类型标注。
+ * - **媒体本体**走**当前轮** `ctx.media`：图片和文件一样，都必须在这里，宿主才会读。
+ *   注意宿主的"最近历史图片"通道（`InboundHistory[].media` + 本地 path）**默认回复链路是关的**
+ *   （`current-turn-images` 显式传 `includeRecentHistoryImages: false`，只有 ACP 绑定会话才开），
+ *   所以不能把图片塞进历史条目就指望它到模型。
+ *
+ * 记录时**不下载**：跳过消息可能在群里刷很久而机器人一次都没被 @，下载全部媒体是纯浪费。
+ * 只有真正触发一轮时，才按时间窗口和上限把这几条媒体拉下来，作为本轮附件附上。
+ */
+import { type HistoryEntry } from 'openclaw/plugin-sdk/reply-history';
+import type { Youdu } from './media.js';
+/**
+ * 补带历史媒体的时间窗口：只把"刚刚发的"算作本轮上下文。
+ *
+ * 这是插件自己的策略（不是宿主常量）：群里半小时前的图不该冒充当前这句 @ 的附件。
+ */
+export declare const HISTORY_MEDIA_TTL_MS: number;
+/** 被 @ 时最多补带几张历史图片。 */
+export declare const DEFAULT_HISTORY_IMAGE_LIMIT = 4;
+/** 被 @ 时最多补带几个历史文件（含语音/视频）。 */
+export declare const DEFAULT_HISTORY_FILE_LIMIT = 2;
+/** 宿主的 `MediaKind`（openclaw dist/constants）。有度没有 sticker/unknown，文件在宿主口径里叫 document。 */
+export type HostMediaKind = 'image' | 'audio' | 'video' | 'document' | 'sticker' | 'unknown';
+/** 一条跳过消息带过的媒体事实：记录时不下载，只记够下载用的东西。 */
+export interface PendingMediaFact {
+    mediaId: string;
+    /** 宿主口径的媒体类型；下载时再用 `toYouduDownloadKind` 换回有度的 `kind` 参数。 */
+    kind: HostMediaKind;
+    name?: string;
+    contentType?: string;
+    /** 下载完成后回填；宿主的 history 图片通道只认本地 path。 */
+    path?: string;
+}
+/** One skipped group message kept for the next addressed turn. */
+export interface PendingGroupEntry {
+    sender: string;
+    body: string;
+    timestamp?: number;
+    messageId?: string;
+    /** 这条消息带的媒体（未下载）。 */
+    media?: PendingMediaFact[];
+}
+/** 从窗口里挑出的一条待下载媒体。 */
+export interface PendingMediaSelection {
+    entryIndex: number;
+    factIndex: number;
+    fact: PendingMediaFact;
+}
+/**
+ * Pending-window size: account → channel → `messages.groupChat` → fallback, clamped at 0.
+ * A resolved 0 disables recording, injection, and clearing in the shared helpers.
+ */
+export declare function resolveHistoryLimit(params: {
+    accountHistoryLimit?: unknown;
+    channelHistoryLimit?: unknown;
+    globalHistoryLimit?: unknown;
+    fallback: number;
+}): number;
+/** One pending entry, or null when the message carries nothing worth replaying. */
+export declare function pendingHistoryEntry(params: {
+    messageId?: string;
+    sender?: string;
+    body?: string;
+    timestamp?: number;
+    media?: readonly PendingMediaFact[];
+}): PendingGroupEntry | null;
+/** A redelivered frame must not fill the window with duplicates of the same message. */
+export declare function shouldRecordPendingEntry(entries: readonly PendingGroupEntry[] | undefined, messageId?: string): boolean;
+/**
+ * 取走窗口里当前这批条目：**注入即认领**。
+ *
+ * 比"run 结束再整段清空"更准：这一轮跑着的时候群里新到的消息属于下一次触发，不会被收尾顺手清掉；
+ * 同一批也不会被并发的两轮各注入一次。窗口本身就是内存态（进程重启即丢），所以"认领后这一轮
+ * 挂了就少了这批上下文"与原来"run 结束一律清空"的后果相同。
+ */
+export declare function claimPendingEntries(params: {
+    historyMap: Map<string, PendingGroupEntry[]>;
+    historyKey: string;
+}): PendingGroupEntry[];
+/**
+ * 把解析出的入站媒体变成窗口里的事实，只保留能下载的（有 mediaId）。
+ */
+export declare function mediaFactsForAttachments(attachments: readonly Youdu.InboundMediaAttachment[] | undefined): PendingMediaFact[];
+/** 有度的 `file` 在宿主里是 `document`，其余同名。 */
+export declare function toHostMediaKind(kind: Youdu.InboundMediaAttachment['kind']): HostMediaKind;
+/** 下载 URL 的 `kind` 参数只认有度自己的取值（`GET /cgi/bot/file/download?kind=…`）。 */
+export declare function toYouduDownloadKind(kind: HostMediaKind): Youdu.InboundMediaAttachment['kind'];
+/**
+ * 挑出要补带的历史媒体：最新优先，图片和文件各自计数，条目时间必须落在补带窗口内。
+ *
+ * 时间用 `Math.abs` 比较，和宿主处理"最近历史"时的口径一致：服务端时钟略快、条目时间比当前消息
+ * 晚几秒时，不该把它判成过期。
+ */
+export declare function selectPendingMedia(params: {
+    entries: readonly PendingGroupEntry[];
+    nowMs: number;
+    ttlMs?: number;
+    imageLimit: number;
+    fileLimit: number;
+}): {
+    images: PendingMediaSelection[];
+    files: PendingMediaSelection[];
+};
+/** 下载成功的一条历史媒体。 */
+export interface DownloadedHistoryMedia {
+    selection: PendingMediaSelection;
+    path: string;
+    contentType?: string;
+}
+/** 作为**当前轮**媒体附上的 canonical fact（宿主的 `ctx.media` 口径）。 */
+export interface TurnMediaFact {
+    path: string;
+    contentType?: string;
+    kind: HostMediaKind;
+    fileName?: string;
+}
+/** 下载结果 → 当前轮媒体 fact（图片和文件都走这里，宿主只读 `ctx.media`）。 */
+export declare function turnMediaFacts(downloads: readonly DownloadedHistoryMedia[]): TurnMediaFact[];
+/**
+ * 一轮投递要用的群上下文：把窗口里该带的媒体下载下来，产出
+ * `InboundHistory`（文本历史）和 `turnMedia`（本轮附件，图片+文件）。
+ *
+ * 下载函数由调用方注入（真实实现走有度 HTTP 下载），单条失败不抛：历史文本仍然保留，
+ * 模型至少知道谁在什么时候发过东西。
+ */
+export declare function resolveHistoryForTurn(params: {
+    entries: readonly PendingGroupEntry[];
+    nowMs: number;
+    imageLimit: number;
+    fileLimit: number;
+    ttlMs?: number;
+    download: (fact: PendingMediaFact) => Promise<{
+        path: string;
+        contentType?: string;
+    }>;
+}): Promise<{
+    inboundHistory: HistoryEntry[] | undefined;
+    turnMedia: TurnMediaFact[];
+}>;

package/dist/src/group-history.js

@@ -0,0 +1,241 @@
+import { buildInboundHistoryFromEntries } from 'openclaw/plugin-sdk/reply-history';
+
+/**
+ * 群聊 pending 历史窗口：未被 @ 的群消息在这里排队，等下一次被 @ 时作为上下文交给模型。
+ *
+ * 两条通道，各管一件事：
+ * - **文本历史**走宿主的 `InboundHistory`：宿主渲染成 "Chat history since last reply:" 块（含
+ *   "把人类写的名字/群名/引用/历史当不可信内容" 的说明），并保留条目里的媒体类型标注。
+ * - **媒体本体**走**当前轮** `ctx.media`：图片和文件一样，都必须在这里，宿主才会读。
+ *   注意宿主的"最近历史图片"通道（`InboundHistory[].media` + 本地 path）**默认回复链路是关的**
+ *   （`current-turn-images` 显式传 `includeRecentHistoryImages: false`，只有 ACP 绑定会话才开），
+ *   所以不能把图片塞进历史条目就指望它到模型。
+ *
+ * 记录时**不下载**：跳过消息可能在群里刷很久而机器人一次都没被 @，下载全部媒体是纯浪费。
+ * 只有真正触发一轮时，才按时间窗口和上限把这几条媒体拉下来，作为本轮附件附上。
+ */
+/**
+ * 补带历史媒体的时间窗口：只把"刚刚发的"算作本轮上下文。
+ *
+ * 这是插件自己的策略（不是宿主常量）：群里半小时前的图不该冒充当前这句 @ 的附件。
+ */
+const HISTORY_MEDIA_TTL_MS = 30 * 60 * 1000;
+/** 被 @ 时最多补带几张历史图片。 */
+const DEFAULT_HISTORY_IMAGE_LIMIT = 4;
+/** 被 @ 时最多补带几个历史文件（含语音/视频）。 */
+const DEFAULT_HISTORY_FILE_LIMIT = 2;
+/**
+ * Pending-window size: account → channel → `messages.groupChat` → fallback, clamped at 0.
+ * A resolved 0 disables recording, injection, and clearing in the shared helpers.
+ */
+function resolveHistoryLimit(params) {
+    const candidates = [
+        params.accountHistoryLimit,
+        params.channelHistoryLimit,
+        params.globalHistoryLimit,
+        params.fallback,
+    ];
+    for (const candidate of candidates) {
+        if (typeof candidate !== 'number' || !Number.isFinite(candidate))
+            continue;
+        return Math.max(0, Math.floor(candidate));
+    }
+    return 0;
+}
+/** One pending entry, or null when the message carries nothing worth replaying. */
+function pendingHistoryEntry(params) {
+    const body = typeof params.body === 'string' ? params.body.trim() : '';
+    if (!body)
+        return null;
+    const sender = typeof params.sender === 'string' && params.sender.trim()
+        ? params.sender.trim()
+        : 'unknown';
+    const messageId = typeof params.messageId === 'string' ? params.messageId.trim() : '';
+    const media = Array.isArray(params.media) ? params.media.filter((fact) => Boolean(fact?.mediaId)) : [];
+    return {
+        sender,
+        body,
+        ...(typeof params.timestamp === 'number' && Number.isFinite(params.timestamp)
+            ? { timestamp: params.timestamp }
+            : {}),
+        ...(messageId ? { messageId } : {}),
+        ...(media.length > 0 ? { media: [...media] } : {}),
+    };
+}
+/** A redelivered frame must not fill the window with duplicates of the same message. */
+function shouldRecordPendingEntry(entries, messageId) {
+    const id = typeof messageId === 'string' ? messageId.trim() : '';
+    if (!id)
+        return true;
+    return !(entries ?? []).some((entry) => entry?.messageId === id);
+}
+/**
+ * 取走窗口里当前这批条目：**注入即认领**。
+ *
+ * 比"run 结束再整段清空"更准：这一轮跑着的时候群里新到的消息属于下一次触发，不会被收尾顺手清掉；
+ * 同一批也不会被并发的两轮各注入一次。窗口本身就是内存态（进程重启即丢），所以"认领后这一轮
+ * 挂了就少了这批上下文"与原来"run 结束一律清空"的后果相同。
+ */
+function claimPendingEntries(params) {
+    const entries = params.historyMap.get(params.historyKey) ?? [];
+    params.historyMap.set(params.historyKey, []);
+    return [...entries];
+}
+/**
+ * 把解析出的入站媒体变成窗口里的事实，只保留能下载的（有 mediaId）。
+ */
+function mediaFactsForAttachments(attachments) {
+    const facts = [];
+    for (const attachment of attachments ?? []) {
+        const mediaId = typeof attachment?.mediaId === 'string' ? attachment.mediaId.trim() : '';
+        if (!mediaId)
+            continue;
+        const name = typeof attachment.name === 'string' ? attachment.name.trim() : '';
+        const contentType = typeof attachment.contentType === 'string' ? attachment.contentType.trim() : '';
+        facts.push({
+            kind: toHostMediaKind(attachment.kind),
+            mediaId,
+            ...(name ? { name } : {}),
+            ...(contentType ? { contentType } : {}),
+        });
+    }
+    return facts;
+}
+/** 有度的 `file` 在宿主里是 `document`，其余同名。 */
+function toHostMediaKind(kind) {
+    return kind === 'file' ? 'document' : kind;
+}
+/** 下载 URL 的 `kind` 参数只认有度自己的取值（`GET /cgi/bot/file/download?kind=…`）。 */
+function toYouduDownloadKind(kind) {
+    if (kind === 'image' || kind === 'audio' || kind === 'video')
+        return kind;
+    // 有度协议没有 sticker/unknown，按文件处理（`file` 的默认值）
+    return 'file';
+}
+/**
+ * 挑出要补带的历史媒体：最新优先，图片和文件各自计数，条目时间必须落在补带窗口内。
+ *
+ * 时间用 `Math.abs` 比较，和宿主处理"最近历史"时的口径一致：服务端时钟略快、条目时间比当前消息
+ * 晚几秒时，不该把它判成过期。
+ */
+function selectPendingMedia(params) {
+    const ttlMs = typeof params.ttlMs === 'number' && Number.isFinite(params.ttlMs)
+        ? params.ttlMs
+        : HISTORY_MEDIA_TTL_MS;
+    const imageLimit = normalizeLimit(params.imageLimit);
+    const fileLimit = normalizeLimit(params.fileLimit);
+    const images = [];
+    const files = [];
+    if (imageLimit === 0 && fileLimit === 0)
+        return { images, files };
+    for (let entryIndex = params.entries.length - 1; entryIndex >= 0; entryIndex -= 1) {
+        if (images.length >= imageLimit && files.length >= fileLimit)
+            break;
+        const entry = params.entries[entryIndex];
+        const media = Array.isArray(entry?.media) ? entry.media : [];
+        if (media.length === 0)
+            continue;
+        if (!isInsideHistoryWindow(entry.timestamp, params.nowMs, ttlMs))
+            continue;
+        for (let factIndex = 0; factIndex < media.length; factIndex += 1) {
+            const fact = media[factIndex];
+            if (!fact?.mediaId)
+                continue;
+            const selection = { entryIndex, factIndex, fact };
+            if (fact.kind === 'image') {
+                if (images.length < imageLimit)
+                    images.push(selection);
+            }
+            else if (files.length < fileLimit) {
+                files.push(selection);
+            }
+        }
+    }
+    return { images, files };
+}
+function normalizeLimit(value) {
+    if (typeof value !== 'number' || !Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.floor(value));
+}
+function isInsideHistoryWindow(timestamp, nowMs, ttlMs) {
+    const value = typeof timestamp === 'number' && Number.isFinite(timestamp) ? timestamp : undefined;
+    const now = typeof nowMs === 'number' && Number.isFinite(nowMs) ? nowMs : undefined;
+    if (value === undefined || now === undefined)
+        return false;
+    return Math.abs(now - value) <= ttlMs;
+}
+/** 下载结果 → 当前轮媒体 fact（图片和文件都走这里，宿主只读 `ctx.media`）。 */
+function turnMediaFacts(downloads) {
+    return downloads.map((download) => ({
+        path: download.path,
+        kind: download.selection.fact.kind,
+        ...(download.contentType ? { contentType: download.contentType } : {}),
+        ...(download.selection.fact.name ? { fileName: download.selection.fact.name } : {}),
+    }));
+}
+/**
+ * 一轮投递要用的群上下文：把窗口里该带的媒体下载下来，产出
+ * `InboundHistory`（文本历史）和 `turnMedia`（本轮附件，图片+文件）。
+ *
+ * 下载函数由调用方注入（真实实现走有度 HTTP 下载），单条失败不抛：历史文本仍然保留，
+ * 模型至少知道谁在什么时候发过东西。
+ */
+async function resolveHistoryForTurn(params) {
+    const selected = selectPendingMedia({
+        entries: params.entries,
+        nowMs: params.nowMs,
+        ...(params.ttlMs === undefined ? {} : { ttlMs: params.ttlMs }),
+        imageLimit: params.imageLimit,
+        fileLimit: params.fileLimit,
+    });
+    const images = await downloadSelections(selected.images, params.download);
+    const files = await downloadSelections(selected.files, params.download);
+    // 附件顺序按历史时间序（选出来的是最新优先），和上面的文本历史一一对应
+    const ordered = [...images, ...files].sort((left, right) => left.selection.entryIndex - right.selection.entryIndex
+        || left.selection.factIndex - right.selection.factIndex);
+    return {
+        inboundHistory: buildInboundHistoryFromEntries({
+            entries: params.entries,
+            limit: params.entries.length,
+        }),
+        turnMedia: turnMediaFacts(ordered),
+    };
+}
+/**
+ * 一批历史媒体同时下载的上限。
+ *
+ * 补带通常只有几条，但 `historyMediaLimit`/`historyFileLimit` 是开放配置，串行下载会让
+ * "被 @ 后到模型开始思考"之间白白多出 N 次往返，全并发又可能把服务端打成一批并发请求。
+ */
+const HISTORY_MEDIA_DOWNLOAD_CONCURRENCY = 4;
+async function downloadSelections(selections, download) {
+    const downloads = [];
+    for (let index = 0; index < selections.length; index += HISTORY_MEDIA_DOWNLOAD_CONCURRENCY) {
+        const chunk = selections.slice(index, index + HISTORY_MEDIA_DOWNLOAD_CONCURRENCY);
+        const settled = await Promise.all(chunk.map(async (selection) => {
+            try {
+                const downloaded = await download(selection.fact);
+                const path = typeof downloaded?.path === 'string' ? downloaded.path.trim() : '';
+                if (!path)
+                    return null;
+                return {
+                    selection,
+                    path,
+                    ...(downloaded.contentType ? { contentType: downloaded.contentType } : {}),
+                };
+            }
+            catch {
+                // 单条媒体下载失败不能拖垮这一轮，也不能拖垮同一批里的其他媒体
+                return null;
+            }
+        }));
+        for (const item of settled) {
+            if (item)
+                downloads.push(item);
+        }
+    }
+    return downloads;
+}
+
+export { DEFAULT_HISTORY_FILE_LIMIT, DEFAULT_HISTORY_IMAGE_LIMIT, HISTORY_MEDIA_TTL_MS, claimPendingEntries, mediaFactsForAttachments, pendingHistoryEntry, resolveHistoryForTurn, resolveHistoryLimit, selectPendingMedia, shouldRecordPendingEntry, toHostMediaKind, toYouduDownloadKind, turnMediaFacts };

package/dist/src/group-mention.d.ts

@@ -2,16 +2,9 @@
  * Pure helpers for Youdu group mention gating.
  *
  * These functions deliberately avoid the OpenClaw runtime so they can be unit tested on their
- * own; the shared policy evaluation itself comes from `openclaw/plugin-sdk/channel-inbound`, and
- * the pending-history window from `openclaw/plugin-sdk/reply-history`.
+ * own; the shared policy evaluation itself comes from `openclaw/plugin-sdk/channel-inbound`.
+ * 未被 @ 的群消息窗口（含媒体）在 `group-history.ts`。
  */
-/** One skipped group message kept for the next addressed turn. */
-export interface PendingGroupEntry {
-    sender: string;
-    body: string;
-    timestamp?: number;
-    messageId?: string;
-}
 /** Native mention evidence consumed by `matchesMentionWithExplicit`. */
 export interface ExplicitMentionFacts {
     hasAnyMention: boolean;
@@ -34,22 +27,3 @@ export declare function mentionFactsFor(params: {
 }): ExplicitMentionFacts;
 /** `groups.<chatId>.requireMention` wins, then `groups."*"`, defaulting to true. */
 export declare function resolveGroupRequireMention(groups: unknown, chatId: string): boolean;
-/**
- * Pending-window size: account → channel → `messages.groupChat` → fallback, clamped at 0.
- * A resolved 0 disables recording, injection, and clearing in the shared helpers.
- */
-export declare function resolveHistoryLimit(params: {
-    accountHistoryLimit?: unknown;
-    channelHistoryLimit?: unknown;
-    globalHistoryLimit?: unknown;
-    fallback: number;
-}): number;
-/** One pending entry, or null when the message carries nothing worth replaying. */
-export declare function pendingHistoryEntry(params: {
-    messageId?: string;
-    sender?: string;
-    body?: string;
-    timestamp?: number;
-}): PendingGroupEntry | null;
-/** A redelivered frame must not fill the window with duplicates of the same message. */
-export declare function shouldRecordPendingEntry(entries: readonly PendingGroupEntry[] | undefined, messageId?: string): boolean;

package/dist/src/group-mention.js

@@ -2,8 +2,8 @@
  * Pure helpers for Youdu group mention gating.
  *
  * These functions deliberately avoid the OpenClaw runtime so they can be unit tested on their
- * own; the shared policy evaluation itself comes from `openclaw/plugin-sdk/channel-inbound`, and
- * the pending-history window from `openclaw/plugin-sdk/reply-history`.
+ * own; the shared policy evaluation itself comes from `openclaw/plugin-sdk/channel-inbound`.
+ * 未被 @ 的群消息窗口（含媒体）在 `group-history.ts`。
  */
 /**
  * Youdu renders a mention as `@<account>(<display name>)`; strip it before the model sees it.
@@ -67,48 +67,5 @@ function resolveGroupRequireMention(groups, chatId) {
     }
     return true;
 }
-/**
- * Pending-window size: account → channel → `messages.groupChat` → fallback, clamped at 0.
- * A resolved 0 disables recording, injection, and clearing in the shared helpers.
- */
-function resolveHistoryLimit(params) {
-    const candidates = [
-        params.accountHistoryLimit,
-        params.channelHistoryLimit,
-        params.globalHistoryLimit,
-        params.fallback,
-    ];
-    for (const candidate of candidates) {
-        if (typeof candidate !== 'number' || !Number.isFinite(candidate))
-            continue;
-        return Math.max(0, Math.floor(candidate));
-    }
-    return 0;
-}
-/** One pending entry, or null when the message carries nothing worth replaying. */
-function pendingHistoryEntry(params) {
-    const body = typeof params.body === 'string' ? params.body.trim() : '';
-    if (!body)
-        return null;
-    const sender = typeof params.sender === 'string' && params.sender.trim()
-        ? params.sender.trim()
-        : 'unknown';
-    const messageId = typeof params.messageId === 'string' ? params.messageId.trim() : '';
-    return {
-        sender,
-        body,
-        ...(typeof params.timestamp === 'number' && Number.isFinite(params.timestamp)
-            ? { timestamp: params.timestamp }
-            : {}),
-        ...(messageId ? { messageId } : {}),
-    };
-}
-/** A redelivered frame must not fill the window with duplicates of the same message. */
-function shouldRecordPendingEntry(entries, messageId) {
-    const id = typeof messageId === 'string' ? messageId.trim() : '';
-    if (!id)
-        return true;
-    return !(entries ?? []).some((entry) => entry?.messageId === id);
-}
 
-export { mentionFactsFor, normalizeAtUsers, pendingHistoryEntry, resolveGroupRequireMention, resolveHistoryLimit, shouldRecordPendingEntry, stripMentionWrappers };
+export { mentionFactsFor, normalizeAtUsers, resolveGroupRequireMention, stripMentionWrappers };

package/dist/src/media.d.ts

@@ -20,6 +20,9 @@ export declare namespace Youdu {
     interface DownloadedInboundMedia {
         path: string;
         contentType?: string;
+        /** 下载时用的有度媒体类型与文件名，回填给调用方，避免再按索引对齐入参。 */
+        kind?: MediaKind;
+        name?: string;
     }
     interface UploadAndSendMediaOptions {
         wsClient: WSClient;

package/dist/src/media.js

@@ -294,7 +294,7 @@ function buildMediaMessageBody(media) {
     }
 }
 async function downloadInboundMedia(params) {
-    const { account, attachments, config, token } = params;
+    const { account, attachments, messageId, config, token } = params;
     const mediaList = [];
     const rt = getYouDuRuntime();
     const maxSize = config?.mediaMaxMb ? config.mediaMaxMb * 1024 * 1024 : DEFAULT_MEDIA_MAX_SIZE;
@@ -319,6 +319,8 @@ async function downloadInboundMedia(params) {
             mediaList.push({
                 path: saved.path,
                 contentType: saved.contentType,
+                kind: attachment.kind,
+                ...(attachment.name ? { name: attachment.name } : {}),
             });
         }
         catch (error) {

package/dist/src/monitor.d.ts

@@ -5,6 +5,7 @@ import type { WsFrame } from './sdk/ws-client.js';
 import type { ResolvedYouDuAccount } from './utils.js';
 import { type Youdu } from './media.js';
 import { type YouduDecodedBody } from './message-prepare.js';
+import { type PendingMediaFact } from './group-history.js';
 /**
  * 消息体类型（待用户完善）
  */
@@ -49,6 +50,15 @@ export interface YouDuMonitorOptions {
     setStatus?: (next: any) => void;
     /** Test/runtime seam for supplying a client without changing reconnect ownership. */
     createClient?: (options: any) => WSClient;
+    /**
+     * 群历史媒体下载的测试接缝（默认走有度 HTTP 下载）。
+     *
+     * 真实下载需要凭据与网络，单测用它把"选中 → 下载 → 作为本轮附件"这段接线跑通。
+     */
+    downloadHistoryMedia?: (fact: PendingMediaFact) => Promise<{
+        path: string;
+        contentType?: string;
+    }>;
 }
 export declare const YOUDU_CONFIGURATION_ERROR_HEALTH_STATE = "configuration-error";
 /**

package/dist/src/monitor.js

@@ -14,8 +14,9 @@ import { bindYouDuKbRunContext, releaseYouDuKbRunContext } from './kb/run-contex
 import { buildMentionRegexes, matchesMentionWithExplicit } from 'openclaw/plugin-sdk/channel-inbound';
 import { resolveYouduMentionGate } from './mention-gate.js';
 import { hasControlCommand, shouldHandleTextCommands } from 'openclaw/plugin-sdk/command-auth';
-import { recordPendingHistoryEntryIfEnabled, DEFAULT_GROUP_HISTORY_LIMIT, buildPendingHistoryContextFromMap, clearHistoryEntriesIfEnabled } from 'openclaw/plugin-sdk/reply-history';
-import { resolveHistoryLimit, stripMentionWrappers, mentionFactsFor, pendingHistoryEntry, shouldRecordPendingEntry, resolveGroupRequireMention } from './group-mention.js';
+import { createChannelHistoryWindow, DEFAULT_GROUP_HISTORY_LIMIT } from 'openclaw/plugin-sdk/reply-history';
+import { stripMentionWrappers, mentionFactsFor, resolveGroupRequireMention } from './group-mention.js';
+import { resolveHistoryLimit, pendingHistoryEntry, mediaFactsForAttachments, shouldRecordPendingEntry, resolveHistoryForTurn, claimPendingEntries, DEFAULT_HISTORY_FILE_LIMIT, DEFAULT_HISTORY_IMAGE_LIMIT, toHostMediaKind, toYouduDownloadKind } from './group-history.js';
 
 /*
 * Licensed under the MIT License.
@@ -39,7 +40,7 @@ function resolveFrameRoute(frame, account, config) {
         peer: { kind: chatType, id: chatId },
     });
 }
-function buildMessageContext(frame, account, config, text, mediaList, route, pendingHistory = null) {
+function buildMessageContext(frame, account, config, text, mediaList, route, inboundHistory = undefined, historyTurnMedia = []) {
     const core = getYouDuRuntime();
     const body = frame.body;
     const senderId = String(body.from.userId).trim();
@@ -54,24 +55,21 @@ function buildMessageContext(frame, account, config, text, mediaList, route, pen
     // 当只有媒体没有文本时，使用占位符标识媒体类型
     const hasImages = mediaList.some((m) => m.contentType?.startsWith("image/"));
     const messageBody = text || (mediaList.length > 0 ? (hasImages ? MEDIA_IMAGE_PLACEHOLDER : MEDIA_DOCUMENT_PLACEHOLDER) : "");
-    // 未被 @ 的群消息只在这个窗口里；触发时以 [自上次回复以来的群消息] 形式并入 Body。
-    // RawBody / CommandBody 保持当前消息原文，命令解析与 @ 判定都不会看到历史块。
-    const combinedBody = pendingHistory && pendingHistory.limit > 0
-        ? buildPendingHistoryContextFromMap({
-            historyMap: pendingHistory.historyMap,
-            historyKey: pendingHistory.historyKey,
-            limit: pendingHistory.limit,
-            currentMessage: messageBody,
-            formatEntry: (entry) => `${entry?.sender ?? 'unknown'}: ${entry?.body ?? ''}`,
-        })
-        : messageBody;
-    // 构建多媒体数组
-    const mediaPaths = mediaList.length > 0 ? mediaList.map((m) => m.path) : undefined;
-    const mediaTypes = mediaList.length > 0
-        ? mediaList.map((m) => m.contentType).filter(Boolean)
-        : undefined;
+    // 当前消息的媒体 + 从群历史里补带的历史媒体（图片和文件都在这里），合成一份有序列表。
+    // 宿主只读 canonical `media`（`normalizeAttachments` 不认 legacy 字段），这里两份都写只是为了
+    // 兼容旧读取方；顺序保持一致是对齐习惯，不是正确性前提。
+    const turnMedia = [
+        ...mediaList.map((media) => ({
+            path: media.path,
+            ...(media.contentType ? { contentType: media.contentType } : {}),
+            ...(media.kind ? { kind: toHostMediaKind(media.kind) } : {}),
+            ...(media.name ? { fileName: media.name } : {}),
+        })),
+        ...historyTurnMedia,
+    ];
+    const mediaPaths = turnMedia.map((media) => media.path);
     return core.channel.reply.finalizeInboundContext({
-        Body: combinedBody,
+        Body: messageBody,
         RawBody: messageBody,
         CommandBody: messageBody,
         MessageSid: body.msgId,
@@ -93,11 +91,15 @@ function buildMessageContext(frame, account, config, text, mediaList, route, pen
         CommandAuthorized: true,
         ResponseUrl: body.responseUrl,
         ReqId: frame.headers.reqId,
-        MediaPath: mediaList[0]?.path,
-        MediaType: mediaList[0]?.contentType,
-        MediaPaths: mediaPaths,
-        MediaTypes: mediaTypes,
-        MediaUrls: mediaPaths,
+        // 未被 @ 的群消息的**文本**走结构化通道：宿主渲染成 "Chat history since last reply:" 块，
+        // 并把人类写的名字/历史当不可信内容处理。媒体本体在上面走 ctx.media。
+        InboundHistory: inboundHistory?.length ? inboundHistory : undefined,
+        media: turnMedia.length > 0 ? turnMedia : undefined,
+        MediaPath: turnMedia[0]?.path,
+        MediaType: turnMedia[0]?.contentType,
+        MediaPaths: turnMedia.length > 0 ? mediaPaths : undefined,
+        MediaTypes: turnMedia.length > 0 ? turnMedia.map((media) => media.contentType) : undefined,
+        MediaUrls: turnMedia.length > 0 ? mediaPaths : undefined,
     });
 }
 /**
@@ -107,7 +109,7 @@ function buildMessageContext(frame, account, config, text, mediaList, route, pen
  * 消息解析部分留空，供用户后续完善
  */
 async function processYouDuMessage(params) {
-    const { frame, account, config, runtime, wsClient, groupHistories, historyLimit } = params;
+    const { frame, account, config, runtime, wsClient, groupHistories, historyLimit, historyImageLimit, historyFileLimit, historyMediaDownloader } = params;
     const body = frame.body;
     const chatId = body.chatId;
     const senderId = String(body.from.userId).trim();
@@ -165,12 +167,12 @@ async function processYouDuMessage(params) {
     }
     // 群 @ 门控：默认只应答复「@ 了机器人」的群消息。
     // 未被 @ 的消息不起 turn、不下载附件、不发占位消息，只记进 pending 窗口，
-    // 等下一次被 @ 时作为上下文一并注入（窗口在 run 结束时清空）。
+    // 等下一次被 @ 时作为上下文一并注入（**注入即认领**，见 claimPendingEntries）。
     const route = resolveFrameRoute(frame, account, config);
     const isGroup = chatType === 'group';
     const cleanedText = stripMentionWrappers(text);
     const pendingHistory = isGroup && route?.sessionKey
-        ? { historyMap: groupHistories, historyKey: route.sessionKey, limit: historyLimit }
+        ? { historyKey: route.sessionKey}
         : null;
     if (isGroup) {
         const requireMention = resolveGroupRequireMentionFor({
@@ -222,11 +224,12 @@ async function processYouDuMessage(params) {
                 sender: currentUserName,
                 body: cleanedText,
                 timestamp: body.createTime,
+                // 只记事实、不下载：这条消息可能永远不会触发一轮
+                media: mediaFactsForAttachments(inboundMedia),
             });
             if (entry && pendingHistory
                 && shouldRecordPendingEntry(groupHistories.get(pendingHistory.historyKey), messageId)) {
-                recordPendingHistoryEntryIfEnabled({
-                    historyMap: groupHistories,
+                createChannelHistoryWindow({ historyMap: groupHistories }).record({
                     historyKey: pendingHistory.historyKey,
                     limit: historyLimit,
                     entry,
@@ -245,11 +248,12 @@ async function processYouDuMessage(params) {
     const mediaList = await downloadInboundMedia({
         account,
         attachments: inboundMedia,
+        messageId,
         config: youduConfig,
         token: wsClient.getToken()
     });
     const shouldSendThinking = account.sendThinkingMessage;
-    // 发送"思考中"消息（可选）
+    // 发送"思考中"消息（可选）——放在历史媒体下载之前，别让补带历史把"已收到"的反馈拖后
     if (account.sendThinkingMessage) {
         try {
             await sendYouDuReply({
@@ -263,8 +267,34 @@ async function processYouDuMessage(params) {
             runtime.error?.(`[youdu] Failed to send thinking message: ${JSON.stringify(err)}`);
         }
     }
+    // 这一轮要带上的群上下文：文本历史走 InboundHistory；窗口里的媒体按时间窗口和上限下载，
+    // 图片和文件都作为**当前轮**附件附上（宿主只读 ctx.media；历史图片通道默认链路是关的）。
+    // 条目在注入前就认领走：run 期间新到的消息留给下一轮，不会被这一轮的收尾清掉。
+    const history = pendingHistory
+        ? await resolveHistoryForTurn({
+            entries: claimPendingEntries({
+                historyMap: groupHistories,
+                historyKey: pendingHistory.historyKey,
+            }),
+            nowMs: body.createTime || Date.now(),
+            imageLimit: historyImageLimit,
+            fileLimit: historyFileLimit,
+            download: (fact) => (historyMediaDownloader
+                ? historyMediaDownloader(fact)
+                : downloadHistoryMedia({
+                    account,
+                    fact,
+                    config: youduConfig,
+                    token: wsClient.getToken(),
+                    runtime,
+                })),
+        })
+        : { inboundHistory: undefined, turnMedia: [] };
+    if (history.turnMedia.length > 0) {
+        runtime.log?.(`[youdu] backfilled ${history.turnMedia.length} history media for group ${chatId}`);
+    }
     // 构建上下文并路由到 OpenClaw 核心处理
-    const ctxPayload = buildMessageContext(frame, account, config, cleanedText, mediaList, route, pendingHistory);
+    const ctxPayload = buildMessageContext(frame, account, config, cleanedText, mediaList, route, history.inboundHistory, history.turnMedia);
     const runId = generateReqId('run');
     bindYouDuKbRunContext(runId, { accountId: account.accountId, chatId, messageId, senderId });
     try {
@@ -278,7 +308,6 @@ async function processYouDuMessage(params) {
             runtime,
             runId,
             onCleanup: cleanupState,
-            pendingHistory,
         }), {
             intervalMs: REMINDER_INTERVAL_MS,
             onReminder: async (elapsedMs) => {
@@ -307,6 +336,37 @@ async function processYouDuMessage(params) {
         cleanupState();
     }
 }
+/**
+ * 下载窗口里的一条历史媒体。
+ *
+ * 单条失败由 `resolveHistoryForTurn` 吞掉（历史文本仍然保留），这里只把有度口径的 `kind`
+ * 换回去并记日志 —— 排查"群里发的文件机器人看不到"时，日志里能直接看到是哪条下载挂了。
+ */
+async function downloadHistoryMedia(params) {
+    const { account, fact, config, token, runtime } = params;
+    try {
+        const downloaded = await downloadInboundMedia({
+            account,
+            attachments: [{
+                    kind: toYouduDownloadKind(fact.kind),
+                    mediaId: fact.mediaId,
+                    ...(fact.name ? { name: fact.name } : {}),
+                    ...(fact.contentType ? { contentType: fact.contentType } : {}),
+                }],
+            messageId: `history-${fact.mediaId}`,
+            config,
+            token,
+        });
+        const first = downloaded[0];
+        if (!first)
+            throw new Error('download returned no media');
+        return { path: first.path, ...(first.contentType ? { contentType: first.contentType } : {}) };
+    }
+    catch (err) {
+        runtime.error?.(`[youdu] Failed to download history media ${fact.mediaId}: ${String(err)}`);
+        throw err;
+    }
+}
 /**
  * 路由消息到 OpenClaw 核心处理
  */
@@ -361,14 +421,8 @@ async function routeAndDispatchMessage(params) {
     }
     finally {
         releaseYouDuKbRunContext(runId);
-        // 这一轮已经消费掉窗口内容（无论成功失败），下一次触发只带上之后的新消息。
-        if (params.pendingHistory) {
-            clearHistoryEntriesIfEnabled({
-                historyMap: params.pendingHistory.historyMap,
-                historyKey: params.pendingHistory.historyKey,
-                limit: params.pendingHistory.limit,
-            });
-        }
+        // 窗口不在这里清：条目在注入前就已经被 claimPendingEntries 认领走了，
+        // 这一轮跑着的时候新到的消息要留给下一次触发。
     }
 }
 async function sendMediaBatch(ctx, mediaUrls) {
@@ -643,6 +697,18 @@ async function monitorYouDuProvider(options) {
             globalHistoryLimit: config?.messages?.groupChat?.historyLimit,
             fallback: DEFAULT_GROUP_HISTORY_LIMIT,
         });
+        // 带进来的历史媒体上限：图片走宿主的 InboundHistory 附件通道（宿主自己也是 4），
+        // 文件/语音/视频当当前轮媒体附上。两者都可以用 0 关掉。
+        const historyImageLimit = resolveHistoryLimit({
+            accountHistoryLimit: account.config?.historyMediaLimit,
+            channelHistoryLimit: config.channels?.youdu?.historyMediaLimit,
+            fallback: DEFAULT_HISTORY_IMAGE_LIMIT,
+        });
+        const historyFileLimit = resolveHistoryLimit({
+            accountHistoryLimit: account.config?.historyFileLimit,
+            channelHistoryLimit: config.channels?.youdu?.historyFileLimit,
+            fallback: DEFAULT_HISTORY_FILE_LIMIT,
+        });
         // 监听所有消息
         wsClient.on('message', async (frame) => {
             try {
@@ -661,6 +727,9 @@ async function monitorYouDuProvider(options) {
                     wsClient,
                     groupHistories,
                     historyLimit,
+                    historyImageLimit,
+                    historyFileLimit,
+                    ...(options.downloadHistoryMedia ? { historyMediaDownloader: options.downloadHistoryMedia } : {}),
                 });
             }
             catch (err) {

package/dist/src/utils.d.ts

@@ -51,6 +51,19 @@ export interface YouDuAccountConfig {
      * 不配置即用 OpenClaw 全局默认（50）；`0` 表示关闭该窗口。账号级覆盖通道级。
      */
     historyLimit?: number;
+    /**
+     * 被 @ 时最多补带几张群历史图片。
+     *
+     * 补带的图片作为**本轮附件**交给模型（宿主只读 `ctx.media`）；只补带 30 分钟内、且在被 @ 这条
+     * 之前的图片。`0` 表示不带图片。不配置即 4。账号级覆盖通道级。
+     */
+    historyMediaLimit?: number;
+    /**
+     * 被 @ 时最多补带几个群历史文件（含语音/视频）。
+     *
+     * 和时间窗口内的图片一样作为本轮附件附上；`0` 表示不带。不配置即 2。账号级覆盖通道级。
+     */
+    historyFileLimit?: number;
     /** 入站媒体文件大小上限（MB） */
     mediaMaxMb?: number;
     /** 额外允许访问的本地媒体路径白名单（支持 ~ 表示 home 目录），如 ["~/Downloads", "~/Documents"] */

package/openclaw.plugin.json

@@ -196,6 +196,16 @@
                   "minimum": 0,
                   "description": "该账号每个群保留的“未被 @ 的群消息”条数（默认 50，0 表示关闭）"
                 },
+                "historyMediaLimit": {
+                  "type": "number",
+                  "minimum": 0,
+                  "description": "该账号被 @ 时最多补带几张群历史图片作为本轮附件（默认 4，0 表示关闭）。只补带 30 分钟内的图片"
+                },
+                "historyFileLimit": {
+                  "type": "number",
+                  "minimum": 0,
+                  "description": "该账号被 @ 时最多补带几个群历史文件（含语音/视频，默认 2，0 表示关闭）"
+                },
                 "sendThinkingMessage": {
                   "type": "boolean",
                   "description": "收到消息后是否先回一条“思考中”（默认 true）"
@@ -212,6 +222,16 @@
             "minimum": 0,
             "description": "每个群保留的“未被 @ 的群消息”条数，作为下次被 @ 时的上下文（默认 50，0 表示关闭）。账号级同名配置优先"
           },
+          "historyMediaLimit": {
+            "type": "number",
+            "minimum": 0,
+            "description": "被 @ 时最多补带几张群历史图片（作为本轮附件交给模型，进 vision 输入）；只补带 30 分钟内的图片，默认 4，0 关闭。账号级同名配置优先"
+          },
+          "historyFileLimit": {
+            "type": "number",
+            "minimum": 0,
+            "description": "被 @ 时最多补带几个群历史文件（含语音/视频）作为本轮附件（默认 2，0 表示关闭）；账号级同名配置优先"
+          },
           "groups": {
             "type": "object",
             "propertyNames": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@youdu/openclaw-youdu",
-  "version": "2026.9.16",
+  "version": "2026.10.9",
   "type": "module",
   "main": "dist/index.esm.js",
   "module": "dist/index.esm.js",
@@ -19,7 +19,7 @@
     "test": "npm run test:kb && npm run test:runtime && npm run test:smoke",
     "test:kb": "npm run test:compile && node --test .test-dist/test/*.test.js",
     "test:integration": "npm run test:compile && node --test .test-dist/test/*.integration.js",
-    "test:runtime": "rollup -c rollup.test.config.mjs && node --test .test-dist/network-reconnect.test.mjs .test-dist/ws-manager.test.mjs .test-dist/utils-accounts.test.mjs .test-dist/tls-ca-path.test.mjs .test-dist/youdu-outbound-target.test.mjs .test-dist/youdu-group-names.test.mjs .test-dist/group-mention.test.mjs .test-dist/monitor-group-mention.test.mjs .test-dist/mention-gate.test.mjs",
+    "test:runtime": "rollup -c rollup.test.config.mjs && node --test .test-dist/network-reconnect.test.mjs .test-dist/ws-manager.test.mjs .test-dist/utils-accounts.test.mjs .test-dist/tls-ca-path.test.mjs .test-dist/youdu-outbound-target.test.mjs .test-dist/youdu-group-names.test.mjs .test-dist/group-mention.test.mjs .test-dist/group-history.test.mjs .test-dist/monitor-group-mention.test.mjs .test-dist/mention-gate.test.mjs",
     "test:smoke": "npm run build && node tools/smoke-plugin-load.mjs",
     "build": "rollup -c",
     "dev": "rollup -c -w",