weflow-cli 1.9.0 → 1.10.0

package/src/services/configService.ts

@@ -28,6 +28,8 @@ interface CliConfig {
   wechatOcSyncBuf: string
   /** 持久化的 context_token: wxid -> token (加密 JSON 字符串) */
   wechatOcContextTokens: string
+  /** 官方通道的**入站媒体**是否下载到本地（默认 'false'）：'true' 才下载，落到 output/wechat-media/ */
+  wechatMediaDownload: string
   // 白名单
   whitelist: string[]
   // 黑名单 (绝对禁止收发)
@@ -109,7 +111,7 @@ const CONFIG_DIR = join(homedir(), '.weflow-cli')
 const CONFIG_FILE = join(CONFIG_DIR, 'config.json')
 
 export class ConfigService {
-  private config: CliConfig = { dbPath: '', wxid: '', decryptKey: '', decryptKey3x: '', dataVersion: '', dbPath3x: '', ntDbPath: '', ntKey: '', ntSalt: '', contactDbPath: '', contactKey: '', contactSalt: '', wechatOcToken: '', wechatOcAccountId: '', wechatOcBaseUrl: '', wechatOcSyncBuf: '', wechatOcContextTokens: '', whitelist: [], blacklist: [], whitelistEntries: [], blacklistEntries: [], vaultRepo: '', aiEngine: 'deepseek', wereadApiKey: '', deepseekApiKey: '', typesafeApiKey: '', dashscopeApiKey: '', snsDbPath: '', snsKey: '', snsSalt: '', favDbPath: '', favKey: '', favPassphrase: '', emoticonSeed: '', assistantPrivacy: 'strict', localModel: '', aiBaseUrl: '', aiModel: '', assistantWhitelist: '', assistantGroupWhitelist: '', assistantGroupRequireMention: 'true', assistantFastRoute: 'off', assistantPanelUser: '', quickReplyContacts: '', skillDirs: '', skillDisabled: '', dailySources: '', dailySourceCategories: '', dailyExcludeTopics: '', dailyAiEnabled: 'true' }
+  private config: CliConfig = { dbPath: '', wxid: '', decryptKey: '', decryptKey3x: '', dataVersion: '', dbPath3x: '', ntDbPath: '', ntKey: '', ntSalt: '', contactDbPath: '', contactKey: '', contactSalt: '', wechatOcToken: '', wechatOcAccountId: '', wechatOcBaseUrl: '', wechatOcSyncBuf: '', wechatOcContextTokens: '', wechatMediaDownload: 'false', whitelist: [], blacklist: [], whitelistEntries: [], blacklistEntries: [], vaultRepo: '', aiEngine: 'deepseek', wereadApiKey: '', deepseekApiKey: '', typesafeApiKey: '', dashscopeApiKey: '', snsDbPath: '', snsKey: '', snsSalt: '', favDbPath: '', favKey: '', favPassphrase: '', emoticonSeed: '', assistantPrivacy: 'strict', localModel: '', aiBaseUrl: '', aiModel: '', assistantWhitelist: '', assistantGroupWhitelist: '', assistantGroupRequireMention: 'true', assistantFastRoute: 'off', assistantPanelUser: '', quickReplyContacts: '', skillDirs: '', skillDisabled: '', dailySources: '', dailySourceCategories: '', dailyExcludeTopics: '', dailyAiEnabled: 'true' }
 
   /** 本进程修改过、待回写的字段 (多进程并发写保护) */
   private dirty = new Set<keyof CliConfig>()
@@ -149,6 +151,7 @@ export class ConfigService {
           wechatOcBaseUrl: data.wechatOcBaseUrl || '',
           wechatOcSyncBuf: data.wechatOcSyncBuf || '',
           wechatOcContextTokens: data.wechatOcContextTokens || '',
+          wechatMediaDownload: data.wechatMediaDownload === 'true' ? 'true' : 'false',
           whitelist,
           blacklist,
           whitelistEntries,
@@ -366,7 +369,7 @@ export class ConfigService {
   }
 
   clear(): void {
-    this.config = { dbPath: '', wxid: '', decryptKey: '', decryptKey3x: '', dataVersion: '', dbPath3x: '', ntDbPath: '', ntKey: '', ntSalt: '', contactDbPath: '', contactKey: '', contactSalt: '', wechatOcToken: '', wechatOcAccountId: '', wechatOcBaseUrl: '', wechatOcSyncBuf: '', wechatOcContextTokens: '', whitelist: [], blacklist: [], whitelistEntries: [], blacklistEntries: [], vaultRepo: '', aiEngine: 'deepseek', wereadApiKey: '', deepseekApiKey: '', typesafeApiKey: '', dashscopeApiKey: '', snsDbPath: '', snsKey: '', snsSalt: '', favDbPath: '', favKey: '', favPassphrase: '', emoticonSeed: '', assistantPrivacy: 'strict', localModel: '', aiBaseUrl: '', aiModel: '', assistantWhitelist: '', assistantGroupWhitelist: '', assistantGroupRequireMention: 'true', assistantFastRoute: 'off', assistantPanelUser: '', quickReplyContacts: '', skillDirs: '', skillDisabled: '', dailySources: '', dailySourceCategories: '', dailyExcludeTopics: '', dailyAiEnabled: 'true' }
+    this.config = { dbPath: '', wxid: '', decryptKey: '', decryptKey3x: '', dataVersion: '', dbPath3x: '', ntDbPath: '', ntKey: '', ntSalt: '', contactDbPath: '', contactKey: '', contactSalt: '', wechatOcToken: '', wechatOcAccountId: '', wechatOcBaseUrl: '', wechatOcSyncBuf: '', wechatOcContextTokens: '', wechatMediaDownload: 'false', whitelist: [], blacklist: [], whitelistEntries: [], blacklistEntries: [], vaultRepo: '', aiEngine: 'deepseek', wereadApiKey: '', deepseekApiKey: '', typesafeApiKey: '', dashscopeApiKey: '', snsDbPath: '', snsKey: '', snsSalt: '', favDbPath: '', favKey: '', favPassphrase: '', emoticonSeed: '', assistantPrivacy: 'strict', localModel: '', aiBaseUrl: '', aiModel: '', assistantWhitelist: '', assistantGroupWhitelist: '', assistantGroupRequireMention: 'true', assistantFastRoute: 'off', assistantPanelUser: '', quickReplyContacts: '', skillDirs: '', skillDisabled: '', dailySources: '', dailySourceCategories: '', dailyExcludeTopics: '', dailyAiEnabled: 'true' }
     // clear 意图是全量重置: 所有字段标记为脏, 覆盖磁盘上的全部旧值
     this.dirty = new Set(Object.keys(this.config) as (keyof CliConfig)[])
     this.save()

package/src/services/messageQuery.ts

@@ -5,6 +5,35 @@ export interface MessageTimeRange {
   to?: number
 }
 
+/**
+ * 这三种形状的输入会被 `resolveTalker` **原样返回**（见 `src/utils/talkerUtils.ts`），
+ * 于是拼错的 ID 会一路走到「取不到消息」，和「这条会话在窗口内确实没有消息」长得一模一样。
+ * 只看形状，不碰 IO —— 判定所需的名单由调用方传进来。
+ */
+export function looksLikeTalkerId(input: string): boolean {
+  const value = String(input || '')
+  return value.startsWith('wxid_') || value.includes('@chatroom') || value.includes('@openim')
+}
+
+/**
+ * 空结果时补的一句话：**只在"看起来是 ID、但会话与联系人都没有它"时**才给。
+ * 返回空串表示没什么可补的 —— 名字形状的输入本来就由 `resolveTalker` 报错，认识的 ID
+ * 取不到消息是正常结果。
+ *
+ * 这里**不改退出码、也不改 `success`**：既有契约里「没有消息」不是错误（脚本与 MCP 依赖它，
+ * 见 `docs/HEALTH-CHECK.md` 的那一行），所以只把歧义说出来，不动语义。
+ */
+export function emptyMessagesNote(
+  input: string,
+  known: { sessionUsernames: Iterable<string>; contactUsernames: Iterable<string> },
+): string {
+  if (!looksLikeTalkerId(input)) return ''
+  for (const id of known.sessionUsernames) if (id === input) return ''
+  for (const id of known.contactUsernames) if (id === input) return ''
+  return `这个 ID 既不在会话里、也不在联系人里：${input}` +
+    ' —— 先确认有没有拼错（weflow-cli sessions / weflow-cli contacts）'
+}
+
 export async function collectMessagesInRange(
   fetchPage: (limit: number, offset: number) => Promise<Message[]>,
   limit: number,

package/src/services/wechatClient.ts

@@ -0,0 +1,380 @@
+/**
+ * **这台机器上的微信客户端，运行时到底加载的是哪一份。**
+ *
+ * 为什么需要它：`check` / `health_check` 一直在报"数据版本 4.x"（那是**数据库格式**），
+ * 而"客户端是哪个版本"从来没人报过 —— 出问题时（数据读不出来、客户端起不来）这恰恰是
+ * 第一个要问的。
+ *
+ * **判据来自一份实测的启动器逆向分析**（报告在仓库外），它纠正了一个很自然的错法：
+ *
+ * - `Weixin.exe` 里**确实**硬编码着一个版本字面量，而且**恰好与本机的版本目录同名** ——
+ *   看起来"读它就能知道版本"。但控制流显示它只是**兜底**：主路径读
+ *   `%APPDATA%\Tencent\xwechat\update\update.data` 里记的目录，只有那次失败才会用到它。
+ *   ⇒ **读字面量判版本是错的**，哪怕它在这台机器上碰巧对。（报告里那条"2/2 实测"就是先
+ *   写错、后被控制流推翻的。）
+ * - 正确的判据是**活进程命令行里的 `--user-lib-dir`** —— 那是真的被加载的那个目录。
+ * - 而"磁盘上有个版本目录"**不代表它能用**：本机 `D:\WeiXin\4.1.15.11\` 是升级残留，
+ *   只剩 `crashpad_handler.exe` 一个文件（**本机实测** 1 个文件 / 2.1 MB；报告 §2.3 记了同一件事）。
+ *
+ * 所以这个模块只做两件事，且都**不猜**：从进程命令行取实际目录；把一个安装根下的版本目录
+ * 分成"能用/不能用"（判据是**有没有 `Weixin.dll`** —— 启动器加载的就是它）。
+ * 取不到就是 `null` + 一句 `note`，不拿别的来源顶替。
+ */
+import { existsSync, readdirSync, realpathSync, statSync } from 'node:fs'
+import { join, win32 } from 'node:path'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+
+const execFileAsync = promisify(execFile)
+
+/** 一个 `Weixin.exe` 进程的画像（只留判版本要用的两个字段）。 */
+export interface WechatClientProcess {
+  pid: number
+  exe: string
+  /** 命令行里的 `--user-lib-dir`；进程没带就是 null（**逆向报告实测**：`--type=xplayer` 那个不带）。 */
+  loadedDir: string | null
+  /** 命令行里的 `--wechat-files-path`：客户端自己说数据目录在哪（小程序那组进程会带）。 */
+  dataDir: string | null
+  /** 命令行里的 `--client_version`：客户端自己的版本 token（十进制，如 `0xF2541F0D`）。 */
+  versionToken: string | null
+}
+
+/** 版本的判据与结论 —— 只跟"哪个进程加载了哪个目录"有关，读不到**别的来源**。 */
+export interface WechatVersionFacts {
+  /** 本机有没有在跑的 `Weixin.exe`（没跑 ⇒ 版本未知，不是"没问题"）。 */
+  running: boolean
+  /** 去重后的实际加载目录，按出现顺序。 */
+  loadedDirs: string[]
+  /** 版本号 = 加载目录的名字；**恰好一个**目录时才给，否则 null。 */
+  version: string | null
+  /** `version` 为 null 时说清为什么。 */
+  note: string
+  /** 安装根下**不能用的**版本目录（没有 `Weixin.dll`）。 */
+  unusableVersionDirs: Array<{ dir: string; files: number }>
+}
+
+export interface WechatClientFacts extends WechatVersionFacts {
+  /** 客户端自报的构建 token（`--client_version`，如 `0xF2541F0D`）—— 与目录名并列的**第二个来源**。 */
+  versionTokens: string[]
+  /** 进程命令行里的 `--wechat-files-path`：**客户端自己说**数据目录在哪。 */
+  dataDirs: string[]
+  /** `update\update.data` 在不在（在 ⇒ 加载路径可能不由命令行决定；见 `caveats`）。 */
+  updateData: { path: string; present: boolean }
+  /** 客户端崩溃记录：只报条数与最近时间，**不读内容**。 */
+  crashRecords: { dir: string; reports: number; records: number; newest: string | null }
+  /** 读这个版本时**必须一起说出去**的不确定（目前只有一条：`update.data` 在场）。 */
+  caveats: string[]
+}
+
+/** 版本目录名：`4.1.15.13` 这种。别的一律不当版本目录（不猜）。 */
+const VERSION_DIR = /^\d+(\.\d+)+$/
+
+/**
+ * PowerShell 一行取所有 `Weixin.exe` 的 pid / 可执行路径 / 命令行。
+ *
+ * 与 `keyService.isProcessRunning` 用同一种调法（`-NoProfile -NonInteractive`）：这台机器上
+ * 那是仓库既有做法，不引第二种。`ConvertTo-Json` 在只有一个结果时会给对象而不是数组，
+ * 所以下面 `parseProcessRows` 两种都收。
+ */
+// **两个镜像名都要问**：`--user-lib-dir` 在 `Weixin.exe` 那组上，而 `--wechat-files-path`
+// 只在 `WeChatAppEx.exe`（小程序运行时那组）的命令行上（**本机实测**：拿它去筛 `Weixin.exe` 会一条都取不到，
+// 于是"客户端自报数据目录"这一项**永远是空的**而看不出来）。版本那一支只认 `Weixin.exe`（见 `summarize`）。
+const PS_LIST = "$p = Get-CimInstance Win32_Process -Filter (\"Name='Weixin.exe' or Name='WeChatAppEx.exe'\") | "
+  + 'Select-Object ProcessId, ExecutablePath, CommandLine; '
+  + 'if ($p) { $p | ConvertTo-Json -Compress }'
+
+export function parseProcessRows(raw: string): WechatClientProcess[] {
+  const text = String(raw || '').trim()
+  if (!text) return []
+  let data: unknown
+  try {
+    data = JSON.parse(text)
+  } catch {
+    return []
+  }
+  const rows = Array.isArray(data) ? data : [data]
+  const out: WechatClientProcess[] = []
+  for (const row of rows) {
+    if (!row || typeof row !== 'object') continue
+    const r = row as Record<string, unknown>
+    const pid = Number(r.ProcessId)
+    if (!Number.isFinite(pid)) continue
+    const commandLine = String(r.CommandLine || '')
+    out.push({
+      pid,
+      exe: String(r.ExecutablePath || ''),
+      loadedDir: userLibDir(commandLine),
+      dataDir: wechatFilesPath(commandLine),
+      versionToken: clientVersionToken(commandLine),
+    })
+  }
+  return out
+}
+
+/**
+ * 从一条命令行里取 `--user-lib-dir` 的值。**两种写法都认**（`=` 与空格、带引号与不带），
+ * 取不到返回 null。
+ *
+ * 注意这个参数**不在 `Weixin.exe` 的字符串表里**（**逆向报告实测**：0 命中）—— 它是被加载的 DLL
+ * 自己解析的。也就是说：只有**进程**能告诉我们它，二进制里搜不到。
+ */
+export function userLibDir(commandLine: string): string | null {
+  const m = /--user-lib-dir\s*=\s*(?:"([^"]+)"|'([^']+)'|(\S+))/.exec(String(commandLine || ''))
+  if (!m) return null
+  const value = (m[1] || m[2] || m[3] || '').trim().replace(/["']/g, '')
+  return value || null
+}
+
+/**
+ * 从命令行里取 `--wechat-files-path`：**客户端自己说数据目录在哪**。
+ *
+ * 用处在排查：它和配置里的数据目录不一致时，说明两边指向的不是同一份库（本机数据目录
+ * 还有 D 盘软链，同一份库两条路径）。只报出来，**不拿它去改配置**。
+ */
+export function wechatFilesPath(commandLine: string): string | null {
+  const m = /--wechat-files-path\s*=\s*(?:"([^"]+)"|'([^']+)'|(\S+))/.exec(String(commandLine || ''))
+  if (!m) return null
+  const value = (m[1] || m[2] || m[3] || '').trim().replace(/["']/g, '')
+  return value || null
+}
+
+/**
+ * 命令行里的 `--client_version`：客户端**自己的版本 token**（十进制）。
+ *
+ * 为什么要报它：它是"哪个构建"的**另一个独立来源** —— 版本目录名（`4.1.15.13`）是装载位置，
+ * 而这个是客户端自报的构建标识，两者来自不同的地方。顺带：实测本机这个值 `4065599245`
+ * 正是 `0xF2541F0D`，也就是那份逆向报告从三处（反编译 / 插件 manifest / UA）定下来的版本号。
+ *
+ * ⚠️ **不给"版本号"**：token 与三段式版本号之间的编码规则**没人解出来**（报告只确认"旧版
+ * `0xF2541D0C` → 新版 `0xF2541F0D`，高 16 位两版都是 `F254`"）。所以它只作为**并列的第二来源**
+ * 报出去，不拿它去推版本号。
+ */
+export function clientVersionToken(commandLine: string): string | null {
+  const m = /--client_version\s*=\s*(\d+)/.exec(String(commandLine || ''))
+  if (!m) return null
+  const value = Number(m[1])
+  if (!Number.isFinite(value) || value <= 0) return null
+  return '0x' + value.toString(16).toUpperCase().padStart(8, '0')
+}
+
+/** 客户端崩溃记录：只数文件、只取最近时间，**不读任何内容**。 */
+export function crashSummary(root: string): WechatClientFacts['crashRecords'] {
+  const reports = countFiles(join(root, 'reports'))
+  const records = countFiles(join(root, 'records')) + countFiles(join(root, 'metadata'))
+  let newest: string | null = null
+  try {
+    for (const sub of ['reports', 'records', 'metadata']) {
+      const dir = join(root, sub)
+      if (!existsSync(dir)) continue
+      for (const name of readdirSync(dir)) {
+        const at = statSync(join(dir, name)).mtime
+        if (!newest || at > new Date(newest)) newest = at.toISOString()
+      }
+    }
+  } catch {
+    // 读不到时间就给 null —— 不拿当前时间顶替（那会造出一个假的"最近崩溃"）
+  }
+  return { dir: root, reports, records, newest }
+}
+
+function countFiles(dir: string): number {
+  try {
+    return readdirSync(dir).filter(name => {
+      try {
+        return statSync(join(dir, name)).isFile()
+      } catch {
+        return false
+      }
+    }).length
+  } catch {
+    return 0
+  }
+}
+
+/** 两条路径是不是同一个位置。**按真身比**：本机数据目录有 D 盘软链，同一份库有两条路径。 */
+export function samePath(a: string, b: string): boolean {
+  try {
+    return realpathSync(a).toLowerCase() === realpathSync(b).toLowerCase()
+  } catch {
+    return false
+  }
+}
+
+/** `%APPDATA%\Tencent\xwechat` —— 崩溃记录与 `update.data` 都在这棵树下。 */
+export function xwechatRoot(appData: string | undefined = process.env.APPDATA): string | null {
+  return appData ? join(appData, 'Tencent', 'xwechat') : null
+}
+
+/**
+ * `update.data` 在场时**必须一起说出去**的那句话。
+ *
+ * 报告把这条明确留成未解："若该文件存在，exe 侧第一次 `LoadLibraryExW` 就会用它，
+ * 根本不会看命令行 —— 两条路谁优先【未知】"。所以这个函数的存在意义是：
+ * 别让新报出去的那个版本在那种机器上**悄悄变成错的**。
+ */
+export function updateDataCaveats(present: boolean): string[] {
+  if (!present) return []
+  return ['update\\update.data 存在：加载路径**可能**由它决定，命令行给的版本未必是实际加载的那个'
+    + '（那份逆向没解开它的内部格式，也没判定两条路谁优先）']
+}
+
+/** 一个版本目录能不能用：**有没有 `Weixin.dll`**（启动器加载的就是它）。 */
+export function versionDirFiles(dir: string): string[] | null {
+  try {
+    if (!statSync(dir).isDirectory()) return null
+    return readdirSync(dir)
+  } catch {
+    return null
+  }
+}
+
+/** 把一堆目录名分成"能用的版本目录 / 不能用的 / 与版本无关的"。纯函数，便于测。 */
+export function classifyVersionDirs(entries: Array<{ name: string; files: string[] }>): {
+  usable: string[]
+  unusable: Array<{ dir: string; files: number }>
+} {
+  const usable: string[] = []
+  const unusable: Array<{ dir: string; files: number }> = []
+  for (const entry of entries) {
+    if (!VERSION_DIR.test(entry.name)) continue
+    if (entry.files.includes('Weixin.dll')) usable.push(entry.name)
+    else unusable.push({ dir: entry.name, files: entry.files.length })
+  }
+  return { usable, unusable }
+}
+
+/** 安装根（`D:\WeiXin`）→ 它的版本目录分类。读不出来就当空（不猜）。 */
+export function versionDirsUnder(installRoot: string): ReturnType<typeof classifyVersionDirs> {
+  let names: string[]
+  try {
+    names = readdirSync(installRoot)
+  } catch {
+    return { usable: [], unusable: [] }
+  }
+  const entries = names.map(name => ({ name, files: versionDirFiles(join(installRoot, name)) || [] }))
+  return classifyVersionDirs(entries)
+}
+
+export function summarize(processes: WechatClientProcess[],
+                          unusable: Array<{ dir: string; files: number }>): WechatVersionFacts {
+  // 去重按**规范形**（去掉尾部分隔符、大小写折叠 —— Windows 路径大小写不敏感）：
+  // 同一个目录写成 `D:\WeiXin\4.1.15.13` 与 `…\4.1.15.13\` 是**一个**目录，
+  // 不折算的话会被当成"两个进程指向不同目录"从而拒绝给出版本号。
+  // **版本只跟 `Weixin.exe` 有关**：`WeChatAppEx.exe`（小程序那组）与它在同一张进程表里
+  // （后者的命令行上带着 `--wechat-files-path`），但它不加载 `Weixin.dll` —— 拿它的
+  // "没带 `--user-lib-dir`"去说事会把"客户端在跑、版本取得到"讲成"取不到"。
+  // 用 `win32` 而不是平台 `path`：这里拆的**永远是 Windows 路径**（进程表/命令行给的），
+  // 而平台 `basename` 在别的平台上会把 `D:\WeiXin\4.1.15.13\Weixin.exe` 当成**一个文件名**
+  // —— 于是过滤出 0 个启动器、版本退回"未知"，在 Windows 上还看不出来（CI 的 ubuntu 上红了 4 条）。
+  // 在 Windows 上 `win32.*` 与平台版完全等价，所以目标机器的行为一点没变。
+  const launchers = processes.filter(p => win32.basename(p.exe).toLowerCase() === 'weixin.exe')
+  const seen = new Map<string, string>()
+  for (const p of launchers) {
+    if (!p.loadedDir) continue
+    const shown = p.loadedDir.replace(/[\\/]+$/, '')
+    if (!shown) continue
+    const key = shown.toLowerCase()
+    if (!seen.has(key)) seen.set(key, shown)
+  }
+  const loadedDirs = [...seen.values()]
+  let version: string | null = null
+  let note = ''
+  if (!launchers.length) {
+    note = '客户端没在运行 ⇒ 版本未知（`--user-lib-dir` 只有进程知道）'
+  } else if (!loadedDirs.length) {
+    note = `在跑 ${launchers.length} 个进程，但命令行里都没有 --user-lib-dir`
+  } else if (loadedDirs.length > 1) {
+    // **不猜**：多个目录各有各的来源（子进程可以指到不同的库），挑一个报出去就是编。
+    // 目录本身照旧列出来（那是实测到的），只是不给"版本号"这个单一结论。
+    note = `有 ${loadedDirs.length} 个不同的目录在使用，不挑一个报版本`
+  } else {
+    version = win32.basename(loadedDirs[0])
+  }
+  return {
+    running: processes.length > 0,
+    loadedDirs,
+    version,
+    note,
+    unusableVersionDirs: unusable,
+  }
+}
+
+/** 默认的执行器：`Get-CimInstance`。测试里换掉它，别真去问系统。 */
+export type PowershellRunner = (command: string) => Promise<string>
+
+/**
+ * **只要那一句话**：客户端自报的数据目录。
+ *
+ * 给 `init` 的数据目录发现用（`DbPathService.autoDetect({ hintedRoots })`）—— 它是唯一
+ * **来自客户端自己**的来源，别的都是按目录名猜的。找不到就返回空数组（调用方走老路），
+ * **不抛**：这只是个线索，不该让初始化失败。
+ */
+export async function reportedDataDirs(run: PowershellRunner = defaultRunner): Promise<string[]> {
+  if (process.platform !== 'win32') return []
+  let raw = ''
+  try {
+    raw = await run(PS_LIST)
+  } catch {
+    return []
+  }
+  const dirs = parseProcessRows(raw).map(p => p.dataDir).filter((d): d is string => !!d)
+  return [...new Set(dirs.map(d => d.replace(/[\\/]+$/, '')).filter(Boolean))]
+}
+
+const defaultRunner: PowershellRunner = async (command) => {
+  const { stdout } = await execFileAsync('powershell.exe',
+    ['-NoProfile', '-NonInteractive', '-Command', command], { timeout: 15_000 })
+  return String(stdout || '')
+}
+
+/**
+ * 汇总：进程画像 + 每个安装根下"不能用的版本目录"。
+ *
+ * 非 Windows 直接返回"平台不支持"（`Get-CimInstance` 是 Windows 的），**不是**返回"没问题"。
+ */
+export async function detectWechatClient(run: PowershellRunner = defaultRunner): Promise<WechatClientFacts> {
+  const root = xwechatRoot()
+  const nothing: WechatClientFacts = {
+    running: false, loadedDirs: [], version: null, note: '', unusableVersionDirs: [],
+    versionTokens: [],
+    dataDirs: [], updateData: { path: root ? join(root, 'update', 'update.data') : '', present: false },
+    crashRecords: { dir: root ? join(root, 'crashinfo') : '', reports: 0, records: 0, newest: null },
+    caveats: [],
+  }
+  if (process.platform !== 'win32') {
+    return { ...nothing, note: `判版本只做了 Windows（当前平台 ${process.platform}）` }
+  }
+  let raw = ''
+  try {
+    raw = await run(PS_LIST)
+  } catch {
+    raw = ''
+  }
+  const processes = parseProcessRows(raw)
+  // 安装根从**启动器**的可执行路径推（**别去猜**：注册表与常见路径都不可靠 ——
+  // 注册表那条空的是**我们自己**的旧结论，出处是 `docs/DECISIONS.md` 里那句"`WeChat Files`
+  // 与注册表 InstallPath 都为空"（讲的是 3.x）；**别把它记成那份逆向报告的结论**，
+  // 报告里没有注册表这一段）。只取 `Weixin.exe` 的目录：小程序的目录是插件目录，
+  // 那里的版本号子目录不是客户端版本。
+  const roots = [...new Set(processes
+    .filter(p => win32.basename(p.exe).toLowerCase() === 'weixin.exe')
+    .map(p => win32.dirname(p.exe))
+    .filter(dir => dir && existsSync(dir)))]
+  const unusable = roots.flatMap(r => versionDirsUnder(r).unusable)
+  const version = summarize(processes, unusable)
+
+  // `update.data` 在场 ⇒ **它可能才是决定加载路径的那个**，命令行给的版本就未必是加载的那个。
+  // 报告把这条明确留成未解（"两条路谁优先 —— 【未知】"），所以这里**不猜**：只说存在，
+  // 并把不确定性跟着版本一起带出去（否则新报的这个版本会在那种机器上悄悄变成错的）。
+  const updateFile = nothing.updateData.path
+  const present = !!updateFile && existsSync(updateFile)
+  return {
+    ...version,
+    // 客户端自报的构建 token（与"目录名"并列的第二来源）——**不拿它推版本号**，编码规则没人解出来
+    versionTokens: [...new Set(processes.map(p => p.versionToken).filter((t): t is string => !!t))],
+    dataDirs: [...new Set(processes.map(p => p.dataDir).filter((d): d is string => !!d))],
+    updateData: { path: updateFile, present },
+    crashRecords: crashSummary(nothing.crashRecords.dir),
+    caveats: updateDataCaveats(present),
+  }
+}

package/src/services/wechatMedia.ts

@@ -0,0 +1,166 @@
+/**
+ * 官方通道（ilink）**入站媒体**的落地：把 CDN 上的密文拉下来、解密、写到本地磁盘。
+ *
+ * 为什么值得做：入站图片/语音/文件/视频此前只解析出"有这一项"，`filePath` 是空串，于是助手拿到消息
+ * 也不知道图里是什么（那四项的落地当时是显式延后的）。下载与解密的本事本来就有
+ * （`WechatClient.downloadMedia`：`<cdn>/download?encrypted_query_param=…` + AES-128-ECB + 去 PKCS#7），
+ * 缺的只是把它接上入站这条路。
+ *
+ * 字段名与优先级照**厂商自己的实现**（`third-party/WeKnora/internal/im/wechat/longpoll.go`）：
+ * 图片优先用 `image_item.aeskey`（十六进制字符串，**不走 base64**），退回 `media.aes_key`（base64）；
+ * 语音/文件/视频只有 `media.aes_key`。两种编码都由 `WechatClient.parseMediaAesKey` 认。
+ *
+ * 三条边界写在这里，不指望调用方记得：
+ * 1. **它不是默认行为** —— 打开 `wechatMediaDownload` 才发生网络访问；
+ * 2. **文件名永远由本地决定** —— 服务端给的名字只取 basename 并过滤字符，`../` 之类必须在这里被吃掉；
+ * 3. **超过上限就不写**（`WECHAT_MEDIA_MAX_BYTES`），失败不留半个文件 —— 半个文件比没有更难查。
+ */
+import { basename, join } from 'path'
+import { mkdir, writeFile } from 'fs/promises'
+
+/** 单件上限。够大（手机拍的视频也能过），又不至于一次 CDN 事故把磁盘写满 */
+export const WECHAT_MEDIA_MAX_BYTES = 25 * 1024 * 1024
+
+/** 落地目录：默认仓库相对 `output/wechat-media/`（`output/` 已在 .gitignore 里），可用环境变量改（测试用临时目录） */
+export function wechatMediaDir(env: NodeJS.ProcessEnv = process.env): string {
+  const fromEnv = env.WEFLOW_WECHAT_MEDIA_DIR
+  return fromEnv && fromEnv.trim() ? fromEnv : join('output', 'wechat-media')
+}
+
+export type InboundMediaType = 'image' | 'record' | 'file' | 'video'
+
+/** item.type 的数字编码（与服务端 item_list 一致） */
+export function mediaTypeOf(itemType: number): InboundMediaType | null {
+  if (itemType === 2) return 'image'
+  if (itemType === 3) return 'record'
+  if (itemType === 4) return 'file'
+  if (itemType === 5) return 'video'
+  return null
+}
+
+/** 服务端给的名字只当作"一个字符串"用：取 basename、去掉控制字符与路径字符、去掉前导点、限长 */
+export function sanitizeFileName(name: string): string {
+  const base = basename(String(name || '').replace(/\\/g, '/')).trim()
+  return base
+    .replace(/[\u0000-\u001f<>:"|?*]/g, '_')
+    .replace(/^\.+/, '')
+    .trim()
+    .slice(0, 80)
+}
+
+/** 按魔数认扩展名。认不出就返回空串（调用方退回按类型给的后缀），不猜 */
+export function extFromMagic(buf: Buffer): string {
+  const b = buf
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return '.jpg'
+  if (b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47) return '.png'
+  if (b.length >= 6 && b.subarray(0, 6).toString('latin1').startsWith('GIF8')) return '.gif'
+  if (b.length >= 12 && b.subarray(0, 4).toString('latin1') === 'RIFF'
+    && b.subarray(8, 12).toString('latin1') === 'WEBP') return '.webp'
+  if (b.length >= 2 && b[0] === 0x42 && b[1] === 0x4d) return '.bmp'
+  if (b.length >= 12 && b.subarray(4, 8).toString('latin1') === 'ftyp') return '.mp4'
+  if (b.length >= 4 && b[0] === 0x1a && b[1] === 0x45 && b[2] === 0xdf && b[3] === 0xa3) return '.webm'
+  if (b.length >= 5 && b.subarray(0, 5).toString('latin1') === '#!AMR') return '.amr'
+  if (b.length >= 4 && b.subarray(0, 4).toString('latin1') === 'OggS') return '.ogg'
+  if (b.length >= 2 && b[0] === 0x49 && b[1] === 0x44 && b[2] === 0x33) return '.mp3'
+  if (b.length >= 12 && b.subarray(0, 4).toString('latin1') === 'RIFF'
+    && b.subarray(8, 12).toString('latin1') === 'WAVE') return '.wav'
+  return ''
+}
+
+/** 该媒体类型在服务端字段树里的节点名 */
+function mediaNode(item: any, mediaType: InboundMediaType): any {
+  if (mediaType === 'image') return item?.image_item
+  if (mediaType === 'record') return item?.voice_item
+  if (mediaType === 'file') return item?.file_item
+  return item?.video_item
+}
+
+/** 下载参数（`encrypt_query_param`）。取不到就没法下载——**这时候不猜、不留空文件** */
+export function pickEncryptParam(item: any, mediaType: InboundMediaType): string {
+  const node = mediaNode(item, mediaType)
+  return String(node?.media?.encrypt_query_param || '')
+}
+
+/**
+ * AES key 的取值优先级。**图片这一支必须照厂商实现**：`image_item.aeskey` 是十六进制字符串，
+ * 比 `media.aes_key`（base64）更靠前；漏了这个优先级，图片会解出一堆乱码却不报错。
+ */
+export function pickAesKeyValue(item: any, mediaType: InboundMediaType): string {
+  const node = mediaNode(item, mediaType)
+  if (mediaType === 'image' && node?.aeskey) return String(node.aeskey)
+  return String(node?.media?.aes_key || '')
+}
+
+export interface SaveMediaOptions {
+  item: any
+  mediaType: InboundMediaType
+  /** 同一条消息里的第几项（一条消息可以带多张图） */
+  index: number
+  /** 名字前缀：优先用服务端给的 client_id */
+  messageId: string
+  dir?: string
+  /** 注入的下载器（默认由调用方传 `client.downloadMedia`），测试里换成假的 */
+  download: (encryptedQueryParam: string, aesKeyValue: string) => Promise<Buffer>
+  /** 文件类消息里服务端给的文件名 */
+  serverFileName?: string
+  maxBytes?: number
+}
+
+export interface SaveMediaResult {
+  /** 成功是磁盘路径；失败是空串（**绝不返回"看起来成功"的半成品**） */
+  path: string
+  /** 失败原因，进日志用 */
+  reason: string
+}
+
+/**
+ * 下载一件入站媒体并落盘。失败一律返回 `{ path: '', reason }` 且**不留下文件**：
+ * 助手与导出拿到空 path 时知道"没有这玩意"，比拿到一个 0 字节文件强。
+ */
+export async function saveInboundMedia(opts: SaveMediaOptions): Promise<SaveMediaResult> {
+  const { item, mediaType, index, messageId, download } = opts
+  const cap = opts.maxBytes ?? WECHAT_MEDIA_MAX_BYTES
+
+  const encryptParam = pickEncryptParam(item, mediaType)
+  if (!encryptParam) return { path: '', reason: '服务端没给 encrypt_query_param' }
+
+  const aesKeyValue = pickAesKeyValue(item, mediaType)
+  if (!aesKeyValue) return { path: '', reason: '服务端没给 aes key' }
+
+  let bytes: Buffer
+  try {
+    bytes = await download(encryptParam, aesKeyValue)
+  } catch (error: any) {
+    return { path: '', reason: `下载或解密失败：${error?.message || error}` }
+  }
+  if (!bytes || bytes.length === 0) return { path: '', reason: '下载结果为空' }
+  if (bytes.length > cap) {
+    return { path: '', reason: `超过上限（${bytes.length} > ${cap} 字节）` }
+  }
+
+  const byMagic = extFromMagic(bytes)
+  const fallbackExt = mediaType === 'image' ? '.jpg' : ''
+  const prefix = sanitizeFileName(messageId) || 'msg'
+  let name: string
+  if (mediaType === 'file' && opts.serverFileName) {
+    const safe = sanitizeFileName(opts.serverFileName)
+    if (safe) {
+      const hasExt = /\.[A-Za-z0-9]{1,8}$/.test(safe)
+      name = `${prefix}-${index}-${hasExt || !byMagic ? safe : safe + byMagic}`
+    } else {
+      name = `${prefix}-${index}${byMagic}`
+    }
+  } else {
+    name = `${prefix}-${index}${byMagic || fallbackExt}`
+  }
+
+  const dir = opts.dir || wechatMediaDir()
+  const full = join(dir, name)
+  try {
+    await mkdir(dir, { recursive: true })
+    await writeFile(full, bytes)
+  } catch (error: any) {
+    return { path: '', reason: `写盘失败：${error?.message || error}` }
+  }
+  return { path: full, reason: '' }
+}