dsh-caduceus 0.4.1 → 0.5.1

package/README.md

@@ -87,6 +87,9 @@ onlyBuiltDependencies:
 | `reactionOnDone` | `DONE` | Reaction added when a turn completes |
 | `reactionOnFail` | `CROSS_MARK` | Reaction added when a turn errors/interrupts (falls back to `THINKING`) |
 | `gateRequireBotIdentity` | `true` | Group @ gate fails closed when the bot open id is unknown |
+| `images` | `true` | Accept image messages and attach them to the agent prompt |
+| `files` | `true` | Accept file messages (durable attachment or saved to cwd) |
+| `maxAttachmentBytes` | `20971520` | Per-attachment download limit (20 MiB) |
 
 ## Commands
 

package/README.zh.md

@@ -86,6 +86,9 @@ onlyBuiltDependencies:
 | `reactionOnDone` | `DONE` | 回合完成时添加的表情 |
 | `reactionOnFail` | `CROSS_MARK` | 回合出错/中断时添加的表情（失败退回 `THINKING`） |
 | `gateRequireBotIdentity` | `true` | bot open id 未知时群 @ 门禁 fail-closed（false 恢复旧放行） |
+| `images` | `true` | 接收图片消息并作为附件交给 agent |
+| `files` | `true` | 接收文件消息（附件服务或落到 cwd） |
+| `maxAttachmentBytes` | `20971520` | 单个附件下载上限（20 MiB） |
 
 ## 命令
 

package/dist/bridge/bridge.js

@@ -17,6 +17,8 @@
  * @module dsh-caduceus/bridge/bridge
  */
 import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { planSlashLine } from '../commands/dispatch.js';
 import { helpText } from '../commands/parse.js';
 import { evaluateGate, logGate } from '../gate.js';
@@ -27,7 +29,7 @@ import { writeOwnership } from '../ownership.js';
 import { finalCard, finalCardPlainText, progressCard, } from '../render/cards.js';
 import { CardStream, systemClock } from '../render/stream.js';
 import { mintSessionId, scopeKey, SCOPE_KEY_SEPARATOR } from '../session-key.js';
-import { StatusTracker, shouldNotifyTerminal, recentEventText, statusLabel, statusTemplate, statusText, terminalNotice, } from '../status.js';
+import { StatusTracker, shouldNotifyTerminal, stateForTurnEnd, recentEventText, statusLabel, statusTemplate, statusText, terminalNotice, } from '../status.js';
 import { ScopeQueue } from './scope-queue.js';
 function errorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -133,6 +135,13 @@ export class Bridge {
     }
     /** Process one inbound message (serialized per scope). */
     async handleInbound(message) {
+        if (message.unsupportedType !== undefined) {
+            const state = this.#stateFor(message);
+            this.#logger.info(`unsupported message type: ${message.unsupportedType}`);
+            await this.#replyText(state, '这类消息暂不支持。');
+            await this.#safeAddReaction(message.messageId, 'CROSS_MARK');
+            return;
+        }
         // Bot identity may have failed at startup; retry on the next group message
         // before deciding, so a late bot/v3/info success restores normal gating.
         if (message.chatType === 'group' && (this.#transport.getBotOpenId?.() ?? '').length === 0) {
@@ -149,7 +158,9 @@ export class Bridge {
             chatId: message.chatId,
             ...(message.threadId === undefined ? {} : { threadId: message.threadId }),
             senderOpenId: message.senderOpenId,
-            text: message.text,
+            text: message.text.trim().length === 0 && (message.attachments?.length ?? 0) > 0
+                ? '[attachment]'
+                : message.text,
             ...(message.mentions === undefined ? {} : { mentions: message.mentions }),
             ...(botOpenId === undefined ? {} : { botOpenId }),
             requireBotIdentity: this.#config.gateRequireBotIdentity !== false,
@@ -254,7 +265,10 @@ export class Bridge {
         }
         state.reactionQueue.push(message.messageId);
         this.#startReaction(state, message.messageId);
-        await this.#deliverTurn(state, message.text);
+        await this.#deliverTurn(state, {
+            text: message.text,
+            ...(message.attachments === undefined ? {} : { attachments: message.attachments }),
+        });
     }
     async #handleSlash(state, raw) {
         const plan = planSlashLine(raw);
@@ -410,14 +424,136 @@ export class Bridge {
             }
         }
     }
-    async #deliverTurn(state, text) {
+    async #prepareAttachments(state, input) {
+        const attachments = input.attachments ?? [];
+        if (attachments.length === 0) {
+            return { content: [{ type: 'text', text: input.text }] };
+        }
+        const maxBytes = this.#config.maxAttachmentBytes ?? 20 * 1024 * 1024;
+        const imagesEnabled = this.#config.images !== false;
+        const filesEnabled = this.#config.files !== false;
+        const kept = [];
+        let imageCount = 0;
+        let truncatedImages = 0;
+        let ignored = 0;
+        for (const attachment of attachments) {
+            if (attachment.kind === 'image') {
+                if (!imagesEnabled) {
+                    ignored += 1;
+                    continue;
+                }
+                if (imageCount >= 9) {
+                    truncatedImages += 1;
+                    continue;
+                }
+                imageCount += 1;
+                kept.push(attachment);
+            }
+            else if (!filesEnabled) {
+                ignored += 1;
+            }
+            else {
+                kept.push(attachment);
+            }
+        }
+        if (ignored > 0) {
+            await this.#replyText(state, '当前未启用图片/文件消息，已忽略部分附件。');
+        }
+        let annotated = input.text;
+        if (truncatedImages > 0) {
+            annotated += `（图片超过 9 张，已截断 ${truncatedImages} 张）`;
+        }
+        const store = this.#options.attachmentProvider?.();
+        const parts = [];
+        for (const attachment of kept) {
+            let downloaded;
+            try {
+                downloaded = await this.#transport.downloadResource(state.lastInboundMessageId ?? '', attachment.fileKey, attachment.kind, maxBytes);
+            }
+            catch (error) {
+                const tooLarge = errorMessage(error).includes('too large');
+                await this.#replyText(state, tooLarge ? '文件太大，已跳过。' : '附件下载失败，已跳过。');
+                await this.#safeAddReaction(state.lastInboundMessageId ?? '', 'CROSS_MARK');
+                return undefined;
+            }
+            if (downloaded.bytes.length > maxBytes) {
+                await this.#replyText(state, '文件太大，已跳过。');
+                await this.#safeAddReaction(state.lastInboundMessageId ?? '', 'CROSS_MARK');
+                return undefined;
+            }
+            const base64 = Buffer.from(downloaded.bytes).toString('base64');
+            if (attachment.kind === 'image') {
+                if (store === undefined) {
+                    await this.#replyText(state, '当前无法处理图片（attachments 服务不可用）。');
+                    await this.#safeAddReaction(state.lastInboundMessageId ?? '', 'CROSS_MARK');
+                    return undefined;
+                }
+                parts.push({
+                    type: 'image',
+                    mediaType: imageMediaType(downloaded.contentType),
+                    data: base64,
+                    ...(attachment.fileName === undefined ? {} : { name: attachment.fileName }),
+                });
+                continue;
+            }
+            const fileName = attachment.fileName ?? attachment.fileKey;
+            let admitted = false;
+            if (store !== undefined) {
+                try {
+                    const ref = await store.admitEncodedFile({ data: base64, name: fileName });
+                    parts.push({ type: 'file', attachment: ref });
+                    admitted = true;
+                }
+                catch {
+                    admitted = false;
+                }
+            }
+            if (!admitted) {
+                try {
+                    const dir = this.#config.defaultCwd;
+                    mkdirSync(dir, { recursive: true });
+                    const target = join(dir, `${Date.now()}-${fileName.replace(/[^\w.-]+/g, '_')}`);
+                    writeFileSync(target, downloaded.bytes);
+                    annotated += `（文件已保存：${target}）`;
+                }
+                catch (error) {
+                    this.#logger.warn(`attachment file save failed: ${errorMessage(error)}`);
+                    await this.#replyText(state, '附件保存失败，已跳过。');
+                    await this.#safeAddReaction(state.lastInboundMessageId ?? '', 'CROSS_MARK');
+                    return undefined;
+                }
+            }
+        }
+        if (parts.length === 0)
+            return { content: [{ type: 'text', text: annotated }] };
+        if (store !== undefined) {
+            try {
+                const admitted = await store.admitPromptContent([
+                    { type: 'text', text: annotated },
+                    ...parts,
+                ]);
+                return { content: admitted };
+            }
+            catch (error) {
+                this.#logger.warn(`attachment admission failed: ${errorMessage(error)}`);
+                await this.#replyText(state, '附件处理失败，已跳过。');
+                await this.#safeAddReaction(state.lastInboundMessageId ?? '', 'CROSS_MARK');
+                return undefined;
+            }
+        }
+        return { content: [{ type: 'text', text: annotated }, ...parts] };
+    }
+    async #deliverTurn(state, input) {
+        const prepared = await this.#prepareAttachments(state, input);
+        if (prepared === undefined)
+            return;
         const resolved = await this.#tryResolve(state);
         if (resolved === undefined) {
             await this.#replyText(state, '无法创建会话（agents 服务不可用）。');
             return;
         }
         const message = createUserMessage({
-            content: [{ type: 'text', text }],
+            content: prepared.content,
             source: { kind: 'user' },
         });
         const agent = resolved.agent;
@@ -440,11 +576,17 @@ export class Bridge {
     }
     async #settleTurn(state, event) {
         state.running = false;
+        const kind = turnEndReasonKind(event.data);
+        const finalState = stateForTurnEnd(kind);
+        const finalStateLabel = statusLabel(finalState);
+        // The tracker is usually already terminal (apply ran before this method),
+        // but re-apply to guarantee /status never disagrees with the final card.
+        state.status.apply(event);
         const snapshot = state.status.get();
         const body = state.lastOutput.trim().length > 0
             ? state.lastOutput
-            : `本轮已结束（${statusLabel(snapshot.state)}）。`;
-        const finalInput = this.#finalCardInput(state, snapshot, body);
+            : `本轮已结束（${finalStateLabel}）。`;
+        const finalInput = this.#finalCardInput(state, snapshot, body, finalState, finalStateLabel);
         const stream = state.progress;
         const messageId = stream?.messageId;
         if (stream !== undefined) {
@@ -469,7 +611,6 @@ export class Bridge {
                 await this.#finalFallback(state, finalInput, error);
             }
         }
-        const kind = turnEndReasonKind(event.data);
         if (shouldNotifyTerminal(kind)) {
             const notice = terminalNotice(kind, snapshot.errorMessage);
             if (notice !== undefined)
@@ -478,11 +619,12 @@ export class Bridge {
         await this.#finishReactions(state, kind);
         state.lastOutput = '';
     }
-    #finalCardInput(state, snapshot, body) {
+    #finalCardInput(state, snapshot, body, finalState, finalStateLabel) {
         const sessionTitle = this.#titleOf(state)?.trim() ?? state.title;
         return {
             title: '飞书会话 · 过程',
-            stateLabel: statusLabel(snapshot.state),
+            // Event-derived, never the (possibly stale) tracker snapshot.
+            stateLabel: finalStateLabel,
             steps: snapshot.steps,
             tools: snapshot.tools,
             ...(sessionTitle === undefined ? {} : { sessionTitle }),
@@ -490,7 +632,7 @@ export class Bridge {
             ...(snapshot.startedAt === undefined ? {} : { startedAt: snapshot.startedAt }),
             ...(snapshot.endedAt === undefined ? {} : { endedAt: snapshot.endedAt }),
             body,
-            template: statusTemplate(snapshot.state),
+            template: statusTemplate(finalState),
         };
     }
     /** The ONLY fallback path: card edit failed, so send the same content as text once. */
@@ -1275,3 +1417,14 @@ export function progressCardForSnapshot(snapshot, sessionTitle, recentEvent, tai
         now,
     });
 }
+/** Normalize a resource content-type to one of dsh's accepted image types. */
+function imageMediaType(contentType) {
+    const normalized = (contentType ?? '').split(';')[0]?.trim().toLowerCase();
+    if (normalized === 'image/png' ||
+        normalized === 'image/jpeg' ||
+        normalized === 'image/webp' ||
+        normalized === 'image/gif') {
+        return normalized;
+    }
+    return 'image/jpeg';
+}

package/dist/bridge/types.d.ts

@@ -20,6 +20,14 @@ import type { Transport } from '../transport/types.js';
 export type BusyMode = 'queue' | 'steer' | 'interrupt';
 /** Session approval policy understood by dsh's approval service. */
 export type ApprovalPolicy = 'ask' | 'never';
+/** The slice of dsh's attachment service the bridge needs. */
+export interface AttachmentStoreLike {
+    admitPromptContent(content: readonly unknown[]): Promise<readonly unknown[]>;
+    admitEncodedFile(input: {
+        readonly data: string;
+        readonly name?: string;
+    }): Promise<unknown>;
+}
 /** The slice of dsh's approval service the bridge needs. */
 export interface ApprovalServiceLike {
     setPolicy(agent: AgentLike, policy: ApprovalPolicy): void;
@@ -100,6 +108,12 @@ export interface BridgeConfig {
     readonly reactionOnFail?: string;
     /** Default true: group @ gate fails closed when bot open id is unknown. */
     readonly gateRequireBotIdentity?: boolean;
+    /** Process image attachments (default true). */
+    readonly images?: boolean;
+    /** Process file attachments (default true). */
+    readonly files?: boolean;
+    /** Per-attachment byte cap (default 20 MiB). */
+    readonly maxAttachmentBytes?: number;
 }
 /** Everything the bridge needs; unit tests provide fakes for every seam. */
 export interface BridgeOptions {
@@ -129,6 +143,8 @@ export interface BridgeOptions {
     readonly interactive?: InteractiveRuntime;
     /** Plugin root Cordis context; answerers register here once, not per agent. */
     readonly rootCtx?: unknown;
+    /** Lazily resolve dsh's attachment service (image admission / file refs). */
+    readonly attachmentProvider?: () => AttachmentStoreLike | undefined;
     /** Lazily resolve dsh's approval service (agent-scoped setPolicy). */
     readonly approvalProvider?: () => ApprovalServiceLike | undefined;
     /** Desired session approval policy (default `ask`). */

package/dist/config.d.ts

@@ -35,6 +35,12 @@ export interface GatewayConfig {
     readonly reactionOnFail?: string;
     /** Require the bot's own open id for the group @ gate (default true). */
     readonly gateRequireBotIdentity?: boolean;
+    /** Process image attachments (default true). */
+    readonly images?: boolean;
+    /** Process file attachments (default true). */
+    readonly files?: boolean;
+    /** Per-attachment byte cap (default 20 MiB). */
+    readonly maxAttachmentBytes?: number;
 }
 /** Schemastery schema for the `caduceus-gateway` entry. */
 export declare const Config: z<Schemastery.ObjectS<NoInfer<{
@@ -58,6 +64,9 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     reactionOnDone: z<string, string, "plain">;
     reactionOnFail: z<string, string, "plain">;
     gateRequireBotIdentity: z<boolean, boolean, "plain">;
+    images: z<boolean, boolean, "plain">;
+    files: z<boolean, boolean, "plain">;
+    maxAttachmentBytes: z<number, number, "plain">;
 }>>, Schemastery.ObjectT<NoInfer<{
     appId: z<string, string, "plain">;
     appSecret: z<string, string, "plain">;
@@ -79,6 +88,9 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
     reactionOnDone: z<string, string, "plain">;
     reactionOnFail: z<string, string, "plain">;
     gateRequireBotIdentity: z<boolean, boolean, "plain">;
+    images: z<boolean, boolean, "plain">;
+    files: z<boolean, boolean, "plain">;
+    maxAttachmentBytes: z<number, number, "plain">;
 }>>, "plain">;
 /** Default card patch throttle: half of Feishu's 5 QPS budget. */
 export declare const DEFAULT_CARD_THROTTLE_MS = 400;
@@ -92,6 +104,10 @@ export declare const DEFAULT_LOG_LEVEL: 'info' | 'debug';
 export declare const DEFAULT_PERSONA_AUTO_SYNC = true;
 /** Default agent preset for caduceus sessions. */
 export declare const DEFAULT_AGENT_PRESET = "standard";
+/** Default attachment switches/limit. */
+export declare const DEFAULT_IMAGES = true;
+export declare const DEFAULT_FILES = true;
+export declare const DEFAULT_MAX_ATTACHMENT_BYTES: number;
 /** Default message reactions. */
 export declare const DEFAULT_REACTIONS = true;
 export declare const DEFAULT_REACTION_ON_START = "OnIt";

package/dist/config.js

@@ -32,6 +32,9 @@ export const Config = z.object({
     reactionOnDone: z.string().required(false),
     reactionOnFail: z.string().required(false),
     gateRequireBotIdentity: z.boolean().required(false),
+    images: z.boolean().required(false),
+    files: z.boolean().required(false),
+    maxAttachmentBytes: z.natural().min(1).required(false),
 });
 /** Default card patch throttle: half of Feishu's 5 QPS budget. */
 export const DEFAULT_CARD_THROTTLE_MS = 400;
@@ -45,6 +48,10 @@ export const DEFAULT_LOG_LEVEL = 'info';
 export const DEFAULT_PERSONA_AUTO_SYNC = true;
 /** Default agent preset for caduceus sessions. */
 export const DEFAULT_AGENT_PRESET = 'standard';
+/** Default attachment switches/limit. */
+export const DEFAULT_IMAGES = true;
+export const DEFAULT_FILES = true;
+export const DEFAULT_MAX_ATTACHMENT_BYTES = 20 * 1024 * 1024;
 /** Default message reactions. */
 export const DEFAULT_REACTIONS = true;
 export const DEFAULT_REACTION_ON_START = 'OnIt';
@@ -86,6 +93,9 @@ export function resolveGatewayConfig(config = {}, env = process.env, cwd = proce
         reactionOnDone: config.reactionOnDone ?? DEFAULT_REACTION_ON_DONE,
         reactionOnFail: config.reactionOnFail ?? DEFAULT_REACTION_ON_FAIL,
         gateRequireBotIdentity: config.gateRequireBotIdentity ?? true,
+        images: config.images ?? DEFAULT_IMAGES,
+        files: config.files ?? DEFAULT_FILES,
+        maxAttachmentBytes: config.maxAttachmentBytes ?? DEFAULT_MAX_ATTACHMENT_BYTES,
     };
     return {
         ...(appId === undefined || appSecret === undefined ? {} : { credentials: { appId, appSecret } }),

package/dist/index.js

@@ -193,6 +193,7 @@ export function apply(ctx, config = {}) {
         interactive,
         rootCtx: ctx,
         approvalProvider: () => ctx.get('approval'),
+        attachmentProvider: () => ctx.get('attachments'),
         approvalPolicy: resolved.approvalPolicy,
         sessionPresetLookup: (sessionId) => ctx.get('sessions')?.get(sessionId)?.header
             ?.agentPreset,

package/dist/transport/feishu-api.d.ts

@@ -34,6 +34,11 @@ export interface FeishuApi {
     addReaction(messageId: string, emojiType: string): Promise<string>;
     /** Remove one reaction previously added by this bot. */
     removeReaction(messageId: string, reactionId: string): Promise<void>;
+    /** Download a message resource (image/file), enforcing a byte limit. */
+    downloadResource(messageId: string, fileKey: string, type: 'image' | 'file', maxBytes: number): Promise<{
+        readonly bytes: Uint8Array;
+        readonly contentType?: string;
+    }>;
     createMessage(input: CreateMessageInput): Promise<{
         messageId: string;
     }>;

package/dist/transport/lark.d.ts

@@ -42,6 +42,10 @@ export declare class LarkFeishuApi implements FeishuApi {
     }>;
     addReaction(messageId: string, emojiType: string): Promise<string>;
     removeReaction(messageId: string, reactionId: string): Promise<void>;
+    downloadResource(messageId: string, fileKey: string, type: 'image' | 'file', maxBytes: number): Promise<{
+        readonly bytes: Uint8Array;
+        readonly contentType?: string;
+    }>;
     patchCard(messageId: string, card: FeishuCard): Promise<void>;
     private messageIdOf;
     private assertOk;

package/dist/transport/lark.js

@@ -166,6 +166,33 @@ export class LarkFeishuApi {
         }));
         this.assertOk(response, 'im.v1.message.reaction.delete');
     }
+    async downloadResource(messageId, fileKey, type, maxBytes) {
+        const response = await this.client.im.v1.messageResource.get({
+            params: { type },
+            path: { message_id: messageId, file_key: fileKey },
+        });
+        const headers = (response.headers ?? {});
+        const declared = Number(headers['content-length']);
+        if (Number.isFinite(declared) && declared > maxBytes) {
+            throw new FeishuApiError(`attachment too large (${declared} > ${maxBytes})`, -2);
+        }
+        const contentType = headers['content-type'] ?? headers['Content-Type'];
+        const stream = response.getReadableStream();
+        const chunks = [];
+        let total = 0;
+        for await (const chunk of stream) {
+            total += chunk.length;
+            if (total > maxBytes) {
+                stream.destroy?.();
+                throw new FeishuApiError(`attachment too large (> ${maxBytes})`, -2);
+            }
+            chunks.push(chunk);
+        }
+        return {
+            bytes: new Uint8Array(Buffer.concat(chunks)),
+            ...(contentType === undefined ? {} : { contentType }),
+        };
+    }
     async patchCard(messageId, card) {
         const response = (await this.client.im.v1.message.patch({
             data: { content: JSON.stringify(card) },

package/dist/transport/normalize.d.ts

@@ -30,7 +30,8 @@ export interface RawMessageEventLike {
  * Normalize one raw event.
  *
  * @returns the normalized message, or `undefined` for unsupported/malformed
- *   payloads or empty text.
+ *   payloads or empty text. Unsupported message types return a message with
+ *   `unsupportedType` so the bridge can reply and react explicitly.
  */
 export declare function normalizeMessageEvent(raw: RawMessageEventLike, botOpenId?: string): InboundMessage | undefined;
 /** Raw `card.action.trigger` payload fields used by the surface. */

package/dist/transport/normalize.js

@@ -20,87 +20,132 @@
  */
 import { stripLeadingMentions } from '../mentions.js';
 const AT_TAG_PATTERN = /<at[^>]*>(.*?)<\/at>/gs;
-/** Message types the v0.1 surface handles (attachments are v0.2). */
-const SUPPORTED_MESSAGE_TYPES = new Set(['text']);
+/** Message types the surface can process (attachments included). */
+const KNOWN_MESSAGE_TYPES = new Set(['text', 'image', 'file', 'post']);
+function restoreMentions(text, rawMentions, botOpenId) {
+    text = text.replace(AT_TAG_PATTERN, (_match, inner) => ` @${inner.trim().replace(/^@/, '')} `);
+    text = text.replace(/\r\n?/g, '\n');
+    const entries = rawMentions
+        .map((mention) => ({ key: mention.key, name: mention.name, openId: mention.id?.open_id }))
+        .filter((entry) => entry.key !== undefined || entry.name !== undefined || entry.openId !== undefined);
+    if (entries.length === 0)
+        return stripLeadingMentions(text.trim()).trim();
+    for (const entry of entries) {
+        const own = botOpenId !== undefined && botOpenId.length > 0 && entry.openId === botOpenId;
+        if (!own)
+            continue;
+        if (entry.key !== undefined && entry.key.length > 0)
+            text = text.split(entry.key).join(' ');
+        if (entry.name !== undefined && entry.name.length > 0)
+            text = text.split(`@${entry.name}`).join(' ');
+    }
+    const replaceable = entries
+        .filter((entry) => entry.name !== undefined && entry.name.length > 0 && entry.key !== undefined)
+        .sort((left, right) => (right.key?.length ?? 0) - (left.key?.length ?? 0));
+    for (const entry of replaceable) {
+        text = text.split(entry.key).join(`@${entry.name}`);
+    }
+    return text.replace(/[ \t]{2,}/g, ' ').trim();
+}
+function postParts(parsed) {
+    const attachments = [];
+    const texts = [];
+    if (typeof parsed.title === 'string' && parsed.title.trim().length > 0) {
+        texts.push(parsed.title.trim());
+    }
+    const flatten = (value) => {
+        if (!Array.isArray(value))
+            return;
+        for (const item of value) {
+            if (Array.isArray(item)) {
+                flatten(item);
+                continue;
+            }
+            if (typeof item !== 'object' || item === null)
+                continue;
+            const block = item;
+            if (block.tag === 'text' && typeof block.text === 'string')
+                texts.push(block.text);
+            if ((block.tag === 'img' || block.tag === 'image') &&
+                typeof block.image_key === 'string' &&
+                block.image_key.length > 0) {
+                attachments.push({ kind: 'image', fileKey: block.image_key });
+            }
+        }
+    };
+    flatten(parsed.content);
+    return { text: texts.join(' '), attachments };
+}
 /**
  * Normalize one raw event.
  *
  * @returns the normalized message, or `undefined` for unsupported/malformed
- *   payloads or empty text.
+ *   payloads or empty text. Unsupported message types return a message with
+ *   `unsupportedType` so the bridge can reply and react explicitly.
  */
 export function normalizeMessageEvent(raw, botOpenId) {
-    // Priority #1: only human messages may enter a session.
     const senderType = raw.sender?.sender_type;
     if (senderType !== 'user')
         return undefined;
     const message = raw.message;
-    if (!SUPPORTED_MESSAGE_TYPES.has(message.message_type))
-        return undefined;
-    let text;
-    try {
-        const parsed = JSON.parse(message.content);
-        if (typeof parsed.text !== 'string')
-            return undefined;
-        text = parsed.text;
-    }
-    catch {
-        return undefined;
-    }
-    // Preserve the display text inside <at> tags first: key -> @name replacement
-    // below needs the placeholder text to still be present.
-    text = text.replace(AT_TAG_PATTERN, (_match, inner) => ` @${inner.trim().replace(/^@/, '')} `);
-    text = text.replace(/\r\n?/g, '\n');
-    const rawMentions = message.mentions ?? [];
-    const entries = rawMentions
-        .map((mention) => ({
-        key: mention.key,
-        name: mention.name,
-        openId: mention.id?.open_id,
-    }))
-        .filter((entry) => entry.key !== undefined || entry.name !== undefined || entry.openId !== undefined);
-    if (entries.length === 0) {
-        // No mention metadata: keep the previous behaviour (strip placeholders).
-        text = text.trim();
-        text = stripLeadingMentions(text).trim();
-    }
-    else {
-        // 1) Remove the bot's own mention(s) entirely (agent need not see "@self").
-        for (const entry of entries) {
-            const own = botOpenId !== undefined && botOpenId.length > 0 && entry.openId === botOpenId;
-            if (!own)
-                continue;
-            if (entry.key !== undefined && entry.key.length > 0)
-                text = text.split(entry.key).join(' ');
-            if (entry.name !== undefined && entry.name.length > 0)
-                text = text.split(`@${entry.name}`).join(' ');
-        }
-        // 2) Replace remaining placeholder keys with @display-name (longest first,
-        // so @_user_10 is never clobbered by @_user_1).
-        const replaceable = entries
-            .filter((entry) => entry.name !== undefined && entry.name.length > 0 && entry.key !== undefined)
-            .sort((left, right) => (right.key?.length ?? 0) - (left.key?.length ?? 0));
-        for (const entry of replaceable) {
-            text = text.split(entry.key).join(`@${entry.name}`);
-        }
-        text = text.replace(/[ \t]{2,}/g, ' ').trim();
-    }
-    if (text.length === 0)
-        return undefined;
     const threadId = firstNonEmpty(message.thread_id, message.root_id);
     const rootId = firstNonEmpty(message.root_id);
     const mentions = (message.mentions ?? [])
         .map((mention) => mention.id?.open_id)
         .filter((openId) => typeof openId === 'string' && openId.length > 0);
-    return {
+    const base = () => ({
         messageId: message.message_id,
         chatId: message.chat_id,
         chatType: message.chat_type === 'group' ? 'group' : 'p2p',
         senderOpenId: raw.sender?.sender_id?.open_id ?? '',
         ...(mentions.length === 0 ? {} : { mentions }),
-        text,
         ...(threadId === undefined ? {} : { threadId }),
         ...(rootId === undefined ? {} : { rootId }),
         createdAt: Number(message.create_time) || 0,
+    });
+    let parsed;
+    try {
+        parsed = JSON.parse(message.content);
+    }
+    catch {
+        return undefined;
+    }
+    if (!KNOWN_MESSAGE_TYPES.has(message.message_type)) {
+        return { ...base(), text: '', unsupportedType: message.message_type };
+    }
+    let text = '';
+    let attachments = [];
+    if (message.message_type === 'image') {
+        if (typeof parsed.image_key !== 'string' || parsed.image_key.length === 0)
+            return undefined;
+        attachments = [{ kind: 'image', fileKey: parsed.image_key }];
+    }
+    else if (message.message_type === 'file') {
+        if (typeof parsed.file_key !== 'string' || parsed.file_key.length === 0)
+            return undefined;
+        attachments = [{
+                kind: 'file',
+                fileKey: parsed.file_key,
+                ...(typeof parsed.file_name === 'string' && parsed.file_name.length > 0
+                    ? { fileName: parsed.file_name }
+                    : {}),
+            }];
+    }
+    else if (message.message_type === 'post') {
+        const parts = postParts(parsed);
+        text = parts.text;
+        attachments = parts.attachments;
+    }
+    else {
+        text = typeof parsed.text === 'string' ? parsed.text : '';
+    }
+    text = restoreMentions(text, message.mentions ?? [], botOpenId);
+    if (text.length === 0 && attachments.length === 0)
+        return undefined;
+    return {
+        ...base(),
+        text,
+        ...(attachments.length === 0 ? {} : { attachments }),
     };
 }
 function firstNonEmpty(...values) {

package/dist/transport/reliable.d.ts

@@ -34,6 +34,10 @@ export declare class ReliableTransport implements Transport {
     sendCard(chatId: string, card: FeishuCard, options?: SendOptions): Promise<SentMessage>;
     addReaction(messageId: string, emojiType: string): Promise<string>;
     removeReaction(messageId: string, reactionId: string): Promise<void>;
+    downloadResource(messageId: string, fileKey: string, type: 'image' | 'file', maxBytes: number): Promise<{
+        readonly bytes: Uint8Array;
+        readonly contentType?: string;
+    }>;
     updateCard(messageId: string, card: FeishuCard): Promise<void>;
     reply(chatId: string, messageId: string, payload: ReplyPayload, options?: ReplyOptions): Promise<SentMessage>;
 }

package/dist/transport/reliable.js

@@ -106,6 +106,9 @@ export class ReliableTransport {
     removeReaction(messageId, reactionId) {
         return this.api.removeReaction(messageId, reactionId);
     }
+    downloadResource(messageId, fileKey, type, maxBytes) {
+        return this.api.downloadResource(messageId, fileKey, type, maxBytes);
+    }
     async updateCard(messageId, card) {
         assertUpdateMulti(card);
         await this.#recordVoid('卡片', () => this.api.patchCard(messageId, card));

package/dist/transport/types.d.ts

@@ -46,6 +46,17 @@ export interface InboundMessage {
     readonly rootId?: string;
     /** Unix epoch milliseconds from Feishu; `0` when the event omitted it. */
     readonly createdAt: number;
+    /** Image/file attachments carried by this message. */
+    readonly attachments?: readonly InboundAttachment[];
+    /** Set for message types caduceus cannot process (audio/video/sticker/...). */
+    readonly unsupportedType?: string;
+}
+/** One inbound attachment reference (image/file message or post image). */
+export interface InboundAttachment {
+    readonly kind: 'image' | 'file';
+    readonly fileKey: string;
+    readonly fileName?: string;
+    readonly mediaType?: string;
 }
 /** One interactive-card button click, normalized for the bridge. */
 export interface CardAction {
@@ -123,6 +134,11 @@ export interface Transport {
     addReaction(messageId: string, emojiType: string): Promise<string>;
     /** Remove one reaction previously added by this bot. */
     removeReaction(messageId: string, reactionId: string): Promise<void>;
+    /** Download a message resource (image/file), enforcing a byte limit. */
+    downloadResource(messageId: string, fileKey: string, type: 'image' | 'file', maxBytes: number): Promise<{
+        readonly bytes: Uint8Array;
+        readonly contentType?: string;
+    }>;
     /**
      * The bot's own open id when known (needed for the group @ gate). Optional:
      * fake transports may omit it, and the real one resolves it lazily.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-caduceus",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "description": "Feishu/Lark surface plugin for DeepSeek Harness (dsh): one topic per session, SOUL persona sync, streaming process cards, /status and /doctor.",
   "type": "module",
   "main": "./dist/index.js",