wechaty-puppet-matrix 0.0.54 → 0.0.56

package/dist/esm/src/puppet-matrix.js

@@ -5,6 +5,7 @@ import { WechatMessageType } from './matrix/types.js';
 import Client from './matrix/service/request.js';
 import { getUnixTime } from 'date-fns';
 import { mergeWithFallback } from './matrix/utils/index.js';
+import { detectImageExt, fetchRemoteHead, replaceExt } from './matrix/utils/file-type.js';
 import path from 'path';
 import { CacheManager } from './matrix/cache-manager.js';
 import { isIMContactId, isRoomId } from './matrix/utils/is-type.js';
@@ -16,6 +17,7 @@ import { parseImageMessagePayload } from './matrix/messages/message-image.js';
 import { parseAudioMessagePayload } from './matrix/messages/message-audio.js';
 import { parseVideoMessagePayload } from './matrix/messages/message-video.js';
 import { parseLocationMessagePayload } from './matrix/messages/message-location.js';
+import { parseContactCardMessagePayload } from './matrix/messages/message-contact-card.js';
 import { CachedPromiseFunc } from './matrix/utils/cached-promise.js';
 import { engineMessageToWechaty } from './matrix/schema-mapper/message.js';
 import { engineContactToWechaty } from './matrix/schema-mapper/contact.js';
@@ -23,7 +25,6 @@ import { chatRoomMemberToContact, engineRoomMemberToWechaty, engineRoomToWechaty
 import { parseEvent, EventType } from './matrix/events/mod.js';
 import { addRunningPuppet, removeRunningPuppet } from './cleanup.js';
 import { packageJson } from './package-json.js';
-import { JsonToXml } from './matrix/utils/xml-to-json.js';
 const VERSION = packageJson.version || '0.0.0';
 const PRE = '[PuppetMatrix]';
 const SEARCH_CONTACT_PREFIX = '$search$-';
@@ -520,7 +521,7 @@ class PuppetMatrix extends PUPPET.Puppet {
                 hello = option.hello;
             }
         }
-        await this._client?.addFriendByWxid({ content: hello, ticket, scene: addContactScene, wxid: contactId });
+        await this._client?.addFriendByWxid({ content: hello, ticket, scene: addContactScene, wxid: cachedContactSearch?.wxid || contactId });
     }
     async friendshipSearchPhone(phone) {
         return this._friendshipSearch(phone, '15');
@@ -557,7 +558,58 @@ class PuppetMatrix extends PUPPET.Puppet {
     }
     async messageContact(messageId) {
         log.verbose('PuppetWeChat', 'messageContact(%s)', messageId);
-        return PUPPET.throwUnsupportedError(messageId);
+        const rawPayload = await this.messageRawPayload(messageId);
+        if (rawPayload.msgType !== WechatMessageType.ShareCard) {
+            throw new Error(`message ${messageId} is not a contact card`);
+        }
+        const card = await parseContactCardMessagePayload(rawPayload.msg);
+        if (!card) {
+            throw new Error(`can not parse contact card from message ${messageId}`);
+        }
+        if (!card.username.includes(STRANGER_SUFFIX)) {
+            return card.username;
+        }
+        const friendId = await this._findFriendByCard(card);
+        if (friendId) {
+            log.verbose(PRE, 'messageContact(%s) matched friend %s', messageId, friendId);
+            return friendId;
+        }
+        const searchId = `${SEARCH_CONTACT_PREFIX}${card.username}`;
+        await this._cacheMgr.setContactSearch(searchId, {
+            alias: '',
+            avatar: card.avatar,
+            city: card.city,
+            country: '',
+            isFriend: 0,
+            name: card.nickname,
+            province: card.province,
+            scene: card.scene,
+            sex: card.sex,
+            sign: card.sign,
+            ticket: card.antispamticket,
+            wxNum: card.alias,
+            wxid: card.username,
+        });
+        return searchId;
+    }
+    async _findFriendByCard(card) {
+        const avatarKey = (url) => (url || '').replace(/^https?:\/\//, '').replace(/\/\d+$/, '');
+        const cardAvatar = avatarKey(card.avatar);
+        const contacts = (await this._cacheMgr.getAllContacts())
+            .filter(c => c.wxid && !isRoomId(c.wxid) && !c.wxid.includes(STRANGER_SUFFIX) && c.isFriend !== 0);
+        if (cardAvatar) {
+            const byAvatar = contacts.find(c => avatarKey(c.avatar) === cardAvatar);
+            if (byAvatar) {
+                return byAvatar.wxid;
+            }
+        }
+        if (card.nickname) {
+            const byName = contacts.filter(c => c.name === card.nickname);
+            if (byName.length === 1) {
+                return byName[0].wxid;
+            }
+        }
+        return undefined;
     }
     async messageChannel(messageId) {
         log.verbose('PuppetService', 'messageChannel(%s)', messageId);
@@ -596,12 +648,20 @@ class PuppetMatrix extends PUPPET.Puppet {
                 return this._getMessageFileFileBox(messageId, messagePayload);
             case PUPPET.types.Message.Emoticon: {
                 const emotionPayload = await parseEmotionMessagePayload(messagePayload);
-                const emoticonBox = emotionPayload.is_ww ? await this._client?.downloadWWMedia({
-                    aes_key: emotionPayload.aeskey || '',
-                    auth_key: emotionPayload.authkey || '',
-                    file_id: emotionPayload.cdnurl || '',
-                    file_name: `message-${messageId}-emoticon.jpg`,
-                }, 3) : FileBox.fromUrl(emotionPayload.cdnurl, { name: `message-${messageId}-emoticon.jpg` });
+                const url = emotionPayload.is_ww
+                    ? (await this._client?.downloadWWMedia({
+                        aes_key: emotionPayload.aeskey || '',
+                        auth_key: emotionPayload.authkey || '',
+                        file_id: emotionPayload.cdnurl || '',
+                        file_name: `message-${messageId}-emoticon.gif`,
+                    }, 3)) || ''
+                    : emotionPayload.cdnurl;
+                if (!url) {
+                    throw new Error(`Can not get emoticon url for message: ${messageId}`);
+                }
+                const head = await fetchRemoteHead(url);
+                const ext = (head && detectImageExt(head)) || (emotionPayload.type === 2 && !emotionPayload.game ? 'gif' : 'png');
+                const emoticonBox = FileBox.fromUrl(url, { name: `message-${messageId}-emoticon.${ext}` });
                 emoticonBox.metadata = {
                     payload: emotionPayload,
                     type: 'emoticon',
@@ -736,28 +796,14 @@ class PuppetMatrix extends PUPPET.Puppet {
         }
     }
     async messageSendContact(toUserId, contactId) {
-        log.verbose('PuppetWeChat', 'messageSend("%s", %s)', toUserId, contactId);
+        log.verbose('PuppetWeChat', 'messageSendContact("%s", %s)', toUserId, contactId);
         const contactPayload = await this.contactRawPayload(contactId);
-        const xmlObj = {
-            msg: {
-                antispamticket: '',
-                bigheadimgurl: contactPayload?.avatar,
-                brandFlags: '0',
-                certflag: '0',
-                city: contactPayload?.city,
-                fullpy: contactPayload?.name,
-                imagestatus: '3',
-                nickname: contactPayload?.name,
-                province: contactPayload?.province,
-                regionCode: 'CN_Shanghai',
-                scene: '17',
-                sex: contactPayload?.sex,
-                smallheadimgurl: contactPayload?.avatar,
-                username: contactPayload?.ticket,
-            },
-        };
-        const xml = JsonToXml(xmlObj);
-        const res = await this._client?.sendContactCard(toUserId, xml, this._self?.wxid);
+        const res = await this._client?.sendContact({
+            shareHeadImg: contactPayload?.avatar,
+            shareId: contactPayload?.wxid || contactId,
+            shareNickname: contactPayload?.name,
+            toId: toUserId,
+        }, this._self?.wxid);
         if (res) {
             await this._cacheMgr?.setMessage(res.id, res);
             return res.id;
@@ -770,7 +816,16 @@ class PuppetMatrix extends PUPPET.Puppet {
             : path.extname(fileBox.name);
         const fileUrl = fileBox.remoteUrl || '';
         if (metadata.type === 'emoticon') {
-            PUPPET.throwUnsupportedError(conversationId, fileBox);
+            const emoji = metadata.payload;
+            const byMd5 = emoji?.md5 && emoji.len
+                ? await this._client?.sendEmojiMd5(conversationId, emoji.md5, emoji.len, this._self?.wxid)
+                : undefined;
+            const msgInfo = byMd5 || (fileUrl ? await this._client?.sendEmojiUrl(conversationId, fileUrl, this._self?.wxid) : undefined);
+            if (!msgInfo) {
+                throw new Error(`send emoticon failed: ${fileBox.name}`);
+            }
+            await this._cacheMgr?.setMessage(msgInfo.id, msgInfo);
+            return msgInfo.id;
         }
         else if (fileBox.mediaType.startsWith('image/')) {
             if (fileUrl) {
@@ -875,8 +930,27 @@ class PuppetMatrix extends PUPPET.Puppet {
             throw new Error(`Wrong Post!!! please check your Post payload to make sure it right ${conversationId}`);
         }
     }
+    async sendPat(conversationId, contactId) {
+        log.verbose(PRE, 'sendPat(%s, %s)', conversationId, contactId);
+        const patted = contactId || conversationId;
+        if (isRoomId(patted)) {
+            throw new Error('sendPat: contactId is required in room');
+        }
+        return (await this._client?.sendPat(conversationId, patted)) || false;
+    }
     async messageRecall(messageId) {
-        return PUPPET.throwUnsupportedError(messageId);
+        log.verbose(PRE, 'messageRecall(%s)', messageId);
+        const payload = await this._cacheMgr?.getMessage(messageId);
+        if (!payload) {
+            log.warn(PRE, 'messageRecall(%s): message not found in cache', messageId);
+            return false;
+        }
+        const toId = payload.listenerId || payload.fromWxid || '';
+        if (!toId) {
+            log.warn(PRE, 'messageRecall(%s): can not find conversation id', messageId);
+            return false;
+        }
+        return (await this._client?.revokeMsg(toId, messageId, payload.clientMsgId)) || false;
     }
     async messageForward(toUserName, messageId) {
         const messagePayload = await this.messageRawPayload(messageId);
@@ -1456,7 +1530,21 @@ class PuppetMatrix extends PUPPET.Puppet {
             log.error(`Can not get file for message: ${messageId}`);
         }
         const url = imageInfo.is_ww ? await this._client?.downloadWWMedia(imageInfo, 1) : await this._client?.downloadImage(imageInfo);
-        return this._fileBoxFromUrl(url, messageId);
+        return this._fileBoxFromUrl(url, messageId, url ? await this._imageNameByHead(url) : undefined);
+    }
+    async _imageNameByHead(url) {
+        const head = await fetchRemoteHead(url);
+        const ext = head && detectImageExt(head);
+        if (!ext) {
+            return undefined;
+        }
+        let rawName = 'image';
+        try {
+            rawName = decodeURIComponent(new URL(url).pathname.split('/').pop() || rawName);
+        }
+        catch {
+        }
+        return replaceExt(rawName, ext);
     }
     async _getMessageAudioFileBox(messageId, messagePayload) {
         const audioInfo = await parseAudioMessagePayload(messagePayload);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wechaty-puppet-matrix",
-  "version": "0.0.54",
+  "version": "0.0.56",
   "description": "Puppet matrix for Wechaty",
   "type": "module",
   "typings": "./dist/esm/src/mod.d.ts",

package/src/engine-schema.ts

@@ -29,6 +29,7 @@ export interface MessagePayload {
   msg: string, // 消息内容
   listenerId: string,
   voiceText?: string, // 语音消息转出的文字
+  clientMsgId?: number, // 发送接口返回的 client_msg_id，撤回时需要
 }
 export interface ChatRoomMember {
   wxid: string,

package/src/matrix/messages/message-contact-card.ts

@@ -0,0 +1,48 @@
+import { xmlToJson } from '../utils/xml-to-json.js'
+
+/**
+ * 名片消息(msgType 42)
+ *
+ * <msg username="wxid_xxx | v3_xxx@stranger" nickname="" alias="" bigheadimgurl="" smallheadimgurl=""
+ *      province="" city="" sex="1" sign="" scene="17" antispamticket="v4_xxx@stranger" ... />
+ */
+export interface ContactCardPayload {
+  /** 好友为 wxid，非好友为 v3_xxx@stranger 加密用户名 */
+  username: string
+  nickname: string
+  /** 微信号 */
+  alias: string
+  avatar: string
+  province: string
+  city: string
+  sex: number
+  sign: string
+  scene: string
+  /** 添加好友用的 v4 票据 */
+  antispamticket: string
+  /** 公众号名片 brandType/certflag 非 0 */
+  brandType: number
+  certflag: number
+}
+
+export async function parseContactCardMessagePayload (content: string): Promise<ContactCardPayload | undefined> {
+  const json = await xmlToJson(content)
+  const attrs = json?.msg?.$
+  if (!attrs?.username) {
+    return undefined
+  }
+  return {
+    alias: attrs.alias || '',
+    antispamticket: attrs.antispamticket || '',
+    avatar: attrs.bigheadimgurl || attrs.smallheadimgurl || '',
+    brandType: parseInt(attrs.brandType, 10) || 0,
+    certflag: parseInt(attrs.certflag, 10) || 0,
+    city: attrs.city || '',
+    nickname: attrs.nickname || '',
+    province: attrs.province || '',
+    scene: attrs.scene || '17',
+    sex: parseInt(attrs.sex, 10) || 0,
+    sign: attrs.sign || '',
+    username: attrs.username,
+  }
+}

package/src/matrix/messages/message-emotion.ts

@@ -26,6 +26,37 @@ interface EmotionXmlSchema {
   };
 }
 
+/**
+ * 表情小游戏结果
+ * gameext type=1 猜拳: content 1=剪刀 2=石头 3=布
+ * gameext type=2 骰子: content 4~9 对应 1~6 点
+ */
+export interface EmojiGamePayload {
+  kind: 'rps' | 'dice';
+  /** 猜拳: scissors | rock | paper；骰子: 1~6 */
+  value: string | number;
+  /** 中文描述，如 "石头"、"6点" */
+  text: string;
+}
+
+const RPS: Record<number, [string, string]> = {
+  1: [ 'scissors', '剪刀' ],
+  2: [ 'rock', '石头' ],
+  3: [ 'paper', '布' ],
+}
+
+export function parseEmojiGame (type: number, content: number): EmojiGamePayload | undefined {
+  if (type === 1 && RPS[content]) {
+    const [ value, text ] = RPS[content]!
+    return { kind: 'rps', text, value }
+  }
+  if (type === 2 && content >= 4 && content <= 9) {
+    const point = content - 3
+    return { kind: 'dice', text: `${point}点`, value: point }
+  }
+  return undefined
+}
+
 export interface EmojiMessagePayload {
   type: number;
   len: number;
@@ -34,6 +65,8 @@ export interface EmojiMessagePayload {
   width: number;
   height: number;
   gameext?: string;
+  /** 骰子 / 猜拳的可读结果，普通表情为 undefined */
+  game?: EmojiGamePayload;
   aeskey?: string;
   authkey?: string;
   is_ww: boolean;
@@ -50,10 +83,12 @@ export async function parseEmotionMessagePayload (message: MessagePayload): Prom
   const md5 = jsonPayload.msg.emoji.$.md5
 
   let gameext
+  let game: EmojiGamePayload | undefined
   if (jsonPayload.msg.gameext) {
     const gameextType = parseInt(jsonPayload.msg.gameext.$.type, 10) || 0
     const gameextContent = parseInt(jsonPayload.msg.gameext.$.content, 10) || 0
     gameext = `<gameext type="${gameextType}" content="${gameextContent}" ></gameext>`
+    game = parseEmojiGame(gameextType, gameextContent)
   }
 
   return {
@@ -61,6 +96,7 @@ export async function parseEmotionMessagePayload (message: MessagePayload): Prom
     aeskey: jsonPayload.msg.emoji.$?.aeskey,
     is_ww: !!jsonPayload.msg.emoji.$?.tpurl,
     cdnurl,
+    game,
     gameext,
     height,
     len,

package/src/matrix/messages/message-image.spec.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env -S node -r ts-node/register
+import { test } from 'tstest'
+
+import type { MessagePayload } from '../../engine-schema.js'
+import { parseImageMessagePayload } from './message-image.js'
+
+const buildPayload = (imgAttrs: string): MessagePayload => ({
+  msg: `<?xml version="1.0"?>\n<msg>\n\t<img ${imgAttrs}>\n\t</img>\n</msg>\n`,
+} as unknown as MessagePayload)
+
+test('parseImageMessagePayload uses hevc_mid_size when downloading mid image', async t => {
+  const payload = await parseImageMessagePayload(buildPayload(
+    'aeskey="key" cdnmidimgurl="mid-url" length="157626" md5="md5" hevc_mid_size="53274"',
+  ))
+
+  t.equal(payload.file_id, 'mid-url', 'should use mid image url')
+  t.equal(payload.file_size, '53274', 'size should match the mid image, not the origin length')
+  t.equal(payload.is_ww, false, 'should not be ww image')
+})
+
+test('parseImageMessagePayload prefers cdnmidimgurl_size', async t => {
+  const payload = await parseImageMessagePayload(buildPayload(
+    'aeskey="key" cdnmidimgurl="mid-url" length="157626" hevc_mid_size="53274" cdnmidimgurl_size="60000"',
+  ))
+
+  t.equal(payload.file_size, '60000', 'cdnmidimgurl_size should win')
+})
+
+test('parseImageMessagePayload falls back to length for legacy xml', async t => {
+  const payload = await parseImageMessagePayload(buildPayload(
+    'aeskey="key" cdnmidimgurl="mid-url" length="12345" hevc_mid_size="0"',
+  ))
+
+  t.equal(payload.file_size, '12345', 'length should be used when no mid size is available')
+})
+
+test('parseImageMessagePayload falls back to length when mid size attrs are absent', async t => {
+  const payload = await parseImageMessagePayload(buildPayload(
+    'aeskey="key" cdnmidimgurl="mid-url" length="12345" md5="md5"',
+  ))
+
+  t.equal(payload.file_size, '12345', 'length should be used when hevc_mid_size is missing')
+})
+
+test('parseImageMessagePayload uses big image url when mid size is missing', async t => {
+  const payload = await parseImageMessagePayload(buildPayload(
+    'aeskey="key" cdnmidimgurl="mid-url" cdnbigimgurl="big-url" length="157626"',
+  ))
+
+  t.equal(payload.file_id, 'big-url', 'should switch to origin image url')
+  t.equal(payload.file_size, '157626', 'size should be origin length')
+})
+
+test('parseImageMessagePayload keeps mid url for legacy xml with hdlength', async t => {
+  const payload = await parseImageMessagePayload(buildPayload(
+    'aeskey="key" cdnmidimgurl="mid-url" cdnbigimgurl="big-url" length="12345" hdlength="99999"',
+  ))
+
+  t.equal(payload.file_id, 'mid-url', 'legacy xml should still use mid url')
+  t.equal(payload.file_size, '12345', 'legacy length is mid image size')
+})
+
+test('parseImageMessagePayload keeps length for ww image', async t => {
+  const payload = await parseImageMessagePayload(buildPayload(
+    'aeskey="key" tpurl="tp-url" tpauthkey="auth" length="888" hevc_mid_size="111"',
+  ))
+
+  t.equal(payload.is_ww, true, 'should be ww image')
+  t.equal(payload.file_id, 'tp-url', 'should use tpurl')
+  t.equal(payload.file_size, '888', 'ww image should keep length')
+})
+
+test('parseImageMessagePayload builds fallback candidates for new xml', async t => {
+  const payload = await parseImageMessagePayload(buildPayload(
+    'aeskey="key" cdnmidimgurl="mid-url" cdnbigimgurl="big-url" length="157626" hevc_mid_size="53274"',
+  ))
+
+  t.same(payload.candidates, [
+    { file_id: 'mid-url', file_size: '53274' },
+    { file_id: 'big-url', file_size: '157626' },
+    { file_id: 'mid-url', file_size: '157626' },
+  ], 'should try mid size first, then origin, then legacy combination')
+  t.equal(payload.file_id, payload.candidates?.[0]?.file_id, 'file_id should be first candidate')
+  t.equal(payload.file_size, payload.candidates?.[0]?.file_size, 'file_size should be first candidate')
+})
+
+test('parseImageMessagePayload builds fallback candidates for legacy xml', async t => {
+  const payload = await parseImageMessagePayload(buildPayload(
+    'aeskey="key" cdnmidimgurl="mid-url" cdnbigimgurl="big-url" length="12345" hdlength="99999"',
+  ))
+
+  t.same(payload.candidates, [
+    { file_id: 'mid-url', file_size: '12345' },
+    { file_id: 'big-url', file_size: '99999' },
+  ], 'legacy xml should try mid + length, then big + hdlength')
+})
+
+test('parseImageMessagePayload dedupes candidates', async t => {
+  const payload = await parseImageMessagePayload(buildPayload(
+    'aeskey="key" cdnmidimgurl="mid-url" length="157626" hevc_mid_size="53274" cdnmidimgurl_size="53274"',
+  ))
+
+  t.same(payload.candidates, [
+    { file_id: 'mid-url', file_size: '53274' },
+    { file_id: 'mid-url', file_size: '157626' },
+  ], 'same url + size should only appear once')
+})

package/src/matrix/messages/message-image.ts

@@ -20,6 +20,9 @@ export interface ImageXmlSchema {
                 length: string
                 cdnbigimgurl: string
                 hdlength: string
+                // 新版 XML 中 length 是原图大小，中图大小单独给出
+                hevc_mid_size?: string
+                cdnmidimgurl_size?: string
                 md5: string
                 tpurl?: string
                 tpauthkey?: string
@@ -28,6 +31,11 @@ export interface ImageXmlSchema {
     }
 }
 
+export interface ImageFileCandidate {
+  file_id: string,
+  file_size: string,
+}
+
 export interface ImageMessagePayload {
   aes_key: string,
   auth_key: string,
@@ -35,18 +43,71 @@ export interface ImageMessagePayload {
   file_size: string,
   file_name: string,
   is_ww: boolean,
+  /**
+   * 按优先级排列的 (file_id, file_size) 组合，第一项即 file_id/file_size。
+   * 下载失败时按顺序回落到下一项，避免在错误的 size 上反复重试。
+   */
+  candidates?: ImageFileCandidate[],
 }
 
 export async function parseImageMessagePayload (rawPayload: MessagePayload): Promise<ImageMessagePayload> {
   const imageXml: ImageXmlSchema = await xmlToJson(rawPayload.msg)
   const schema = imageXml.msg.img.$
 
+  const candidates = buildImageCandidates(schema)
+  const primary = candidates[0] || { file_id: schema.cdnmidimgurl || schema.tpurl || '', file_size: schema.length }
+
   return {
     is_ww: !!schema.tpurl,
     aes_key: schema.aeskey,
     auth_key: schema.tpauthkey || '',
-    file_id: schema.cdnmidimgurl || schema.tpurl || '',
-    file_size: schema.length,
+    file_id: primary.file_id,
+    file_size: primary.file_size,
     file_name: '',
+    candidates: candidates.length ? candidates : [ primary ],
+  }
+}
+
+const isPositiveSize = (size?: string): size is string => !!size && Number(size) > 0
+
+/**
+ * file_id 和 file_size 必须指向同一张图，否则下载端按错误的 size 做 Range/断点会失败。
+ * 候选优先级：
+ * 1. 企业微信 (tpurl)：保持原逻辑，只有一个候选，size 用 length
+ * 2. cdnmidimgurl + 中图大小 (cdnmidimgurl_size，其次 hevc_mid_size)
+ * 3. 旧版 XML (有 hdlength，length 是中图大小)：cdnmidimgurl + length，其次 cdnbigimgurl + hdlength
+ *    新版 XML (无 hdlength，length 是原图大小)：cdnbigimgurl + length，其次 cdnmidimgurl + length
+ */
+export function buildImageCandidates (schema: ImageXmlSchema['msg']['img']['$']): ImageFileCandidate[] {
+  if (schema.tpurl) {
+    return [ { file_id: schema.cdnmidimgurl || schema.tpurl, file_size: schema.length } ]
+  }
+
+  const midUrl = schema.cdnmidimgurl
+  const bigUrl = schema.cdnbigimgurl
+  const list: Array<[string | undefined, string | undefined]> = [
+    [ midUrl, schema.cdnmidimgurl_size ],
+    [ midUrl, schema.hevc_mid_size ],
+  ]
+
+  if (isPositiveSize(schema.hdlength)) {
+    list.push([ midUrl, schema.length ], [ bigUrl, schema.hdlength ])
+  } else {
+    list.push([ bigUrl, schema.length ], [ midUrl, schema.length ])
+  }
+
+  const seen = new Set<string>()
+  const candidates: ImageFileCandidate[] = []
+  for (const [ fileId, fileSize ] of list) {
+    if (!fileId || !isPositiveSize(fileSize)) {
+      continue
+    }
+    const key = `${fileId}|${fileSize}`
+    if (seen.has(key)) {
+      continue
+    }
+    seen.add(key)
+    candidates.push({ file_id: fileId, file_size: fileSize })
   }
+  return candidates
 }

package/src/matrix/messages/message-video.spec.ts

@@ -0,0 +1,37 @@
+#!/usr/bin/env -S node -r ts-node/register
+import { test } from 'tstest'
+
+import type { MessagePayload } from '../../engine-schema.js'
+import { parseVideoMessagePayload } from './message-video.js'
+import { parseSizeMismatch } from '../service/request.js'
+
+const buildPayload = (attrs: string): MessagePayload => ({
+  msg: `<?xml version="1.0"?>\n<msg>\n\t<videomsg ${attrs} />\n</msg>\n`,
+} as unknown as MessagePayload)
+
+test('parseVideoMessagePayload adds raw video as fallback candidate', async t => {
+  const payload = await parseVideoMessagePayload(buildPayload(
+    'aeskey="key" cdnvideourl="video-url" length="766838" playlength="5" rawlength="769445" cdnrawvideourl="raw-url" cdnrawvideoaeskey="raw-key"',
+  ))
+
+  t.equal(payload.file_id, 'video-url', 'primary file_id unchanged')
+  t.equal(payload.file_size, '766838', 'primary file_size unchanged')
+  t.same(payload.candidates, [
+    { file_id: 'video-url', file_size: '766838' },
+    { file_id: 'raw-url', file_size: '769445', aes_key: 'raw-key' },
+  ], 'raw video should be second candidate with its own aes key')
+})
+
+test('parseVideoMessagePayload skips empty raw video', async t => {
+  const payload = await parseVideoMessagePayload(buildPayload(
+    'aeskey="key" cdnvideourl="video-url" length="766838" playlength="5" rawlength="0" cdnrawvideourl="" cdnrawvideoaeskey=""',
+  ))
+
+  t.same(payload.candidates, [ { file_id: 'video-url', file_size: '766838' } ], 'only cdn video candidate')
+})
+
+test('parseSizeMismatch extracts actual size from backend error', async t => {
+  t.equal(parseSizeMismatch('download plaintext size differs: expected 766838, got 1228708'), '1228708', 'should return actual size')
+  t.equal(parseSizeMismatch('timeout'), undefined, 'other errors return undefined')
+  t.equal(parseSizeMismatch(undefined), undefined, 'undefined returns undefined')
+})

package/src/matrix/messages/message-video.ts

@@ -50,9 +50,17 @@ export interface VideoMessagePayload {
   thumb_size: string,
   thumb_width: string,
   thumb_height: string,
-  file_name: ''
+  file_name: '',
+  /**
+   * 按优先级排列的下载候选，第一项即 file_id/file_size。
+   * 实测 XML 的 length 可能和 CDN 实际大小不一致 (expected 766838, got 1228708)，
+   * 有原始视频时回落到 cdnrawvideourl + rawlength
+   */
+  candidates?: Array<{ file_id: string, file_size: string, aes_key?: string }>,
 }
 
+const isPositiveSize = (size?: string): size is string => !!size && Number(size) > 0
+
 export async function parseVideoMessagePayload (rawPayload: MessagePayload): Promise<VideoMessagePayload> {
   const videoXml: VideoXmlSchema = await xmlToJson(rawPayload.msg)
   const videoSchema = videoXml.msg.videomsg.$
@@ -70,5 +78,24 @@ export async function parseVideoMessagePayload (rawPayload: MessagePayload): Pro
     thumb_width: videoSchema.cdnthumbwidth || videoSchema.tpthumbwidth || '',
     thumb_height: videoSchema.cdnthumbheight || videoSchema.tpthumbheight || '',
     file_name: '',
+    candidates: buildVideoCandidates(videoSchema),
+  }
+}
+
+export function buildVideoCandidates (schema: VideoXmlSchema['msg']['videomsg']['$']): VideoMessagePayload['candidates'] {
+  if (schema.tpvideourl) {
+    return undefined
+  }
+  const candidates: NonNullable<VideoMessagePayload['candidates']> = []
+  if (schema.cdnvideourl && isPositiveSize(schema.length)) {
+    candidates.push({ file_id: schema.cdnvideourl, file_size: schema.length })
+  }
+  if (schema.cdnrawvideourl && isPositiveSize(schema.rawlength)) {
+    candidates.push({
+      file_id: schema.cdnrawvideourl,
+      file_size: schema.rawlength,
+      aes_key: schema.cdnrawvideoaeskey || schema.aeskey,
+    })
   }
+  return candidates.length ? candidates : undefined
 }