weflow-cli 1.8.2 → 1.10.0

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/outboundSend.ts

@@ -0,0 +1,126 @@
+/**
+ * 出站发送的**那一份策略**：黑名单 → 白名单 → 限速，以及"每次尝试都写审计"。
+ *
+ * 为什么抽成一份：这条链是一条**安全策略**，而 2026-10-01 起有了第二条发送路
+ * （`draft --pick N --send`，见 D-063）。两份写同一件事迟早分叉，而这里分叉的后果具体是
+ * "有一条路绕过了白名单" —— 悄悄多出一个能发给任何人的入口。
+ *
+ * **它不面向模型。** 助手与 MCP 的工具表里没有任何发送工具（`docs/EXTENDING.md`：
+ * *sending is structurally unreachable from a model-driven path*）。这个模块只被**人在命令行上
+ * 显式驱动**的命令调用，而且第二条路还要求先点名"发第几条"。
+ *
+ * 一条实测出来的硬约束写在错误信息里：发送需要**对方的 context_token**，也就是对方得先给你
+ * 发过消息。没有它，"主动发给任何人"这条路本来就不通。
+ */
+import { configService } from './configService.js'
+import { whitelistService } from './whitelistService.js'
+import { WechatMessageService } from './wechatMessageService.js'
+
+export type OutboundKind = 'text' | 'image' | 'file'
+
+export interface OutboundAttempt {
+  wxid: string
+  displayName: string
+  kind: OutboundKind
+  /** 审计与预览里那一行（文本截断后的样子，或 `[image] 文件名 (字节)`） */
+  preview: string
+  /** 纯文本内容（kind 为 text 时用；媒体走 mediaPath） */
+  text?: string
+  mediaPath?: string
+}
+
+export interface OutboundPolicy {
+  windowMs: number
+  max: number
+}
+
+export type OutboundRefusalCode =
+  | 'INVALID_RATE_LIMIT'
+  | 'TARGET_BLOCKED'
+  | 'TARGET_NOT_ALLOWED'
+  | 'RATE_LIMITED'
+
+export interface OutboundRefusal {
+  code: OutboundRefusalCode
+  error: string
+  /** 限速时带上窗口与计数，好让调用方原样报出来 */
+  rateLimit?: { count: number; max: number; windowMs: number }
+}
+
+function auditRefusal(attempt: OutboundAttempt, error: string): void {
+  whitelistService.auditSend({
+    timestamp: Date.now(), action: 'send', targetWxid: attempt.wxid,
+    targetName: attempt.displayName, kind: attempt.kind, success: false,
+    preview: attempt.preview, error,
+  })
+}
+
+/** 速率参数合法性。`send` 与 `draft --send` 用的是同一条规则。 */
+export function parseOutboundPolicy(windowMs: number, max: number): OutboundPolicy | OutboundRefusal {
+  if (!Number.isInteger(windowMs) || windowMs < 1000 || windowMs > 3_600_000
+      || !Number.isInteger(max) || max < 1 || max > 100) {
+    return { code: 'INVALID_RATE_LIMIT', error: 'rate-window 必须为 1000-3600000，rate-max 必须为 1-100' }
+  }
+  return { windowMs, max }
+}
+
+export interface OutboundRate { count: number; max: number; windowMs: number }
+export type OutboundDecision =
+  | { ok: true; rate: OutboundRate }
+  | { ok: false; refusal: OutboundRefusal }
+
+/**
+ * 发送前的三道闸。拒绝时**先写审计**再返回原因（"每次尝试都留痕"是策略的一部分，不只是成功的那些）。
+ *
+ * 放行时把**当时的速率计数**一起带回去 —— 调用方要拿它写进预览（原来那一条命令里
+ * 是先 `checkRateLimit` 再复用同一个对象）。少一次重复查询，也免得两处看到的数不一样。
+ */
+export function authorizeOutbound(attempt: OutboundAttempt, policy: OutboundPolicy): OutboundDecision {
+  if (whitelistService.isBlocked(attempt.wxid)) {
+    auditRefusal(attempt, 'blocked by blacklist')
+    return { ok: false, refusal: { code: 'TARGET_BLOCKED', error: '目标在黑名单中' } }
+  }
+  if (!whitelistService.isAllowed(attempt.wxid)) {
+    // **白名单是这一层真正的边界**：不在名单上的人，任何一条命令行都发不出去。
+    // 这一条**不写审计** —— 与黑名单那条不一样，原实现就是如此，保持一致。
+    return { ok: false, refusal: { code: 'TARGET_NOT_ALLOWED', error: '目标不在白名单中' } }
+  }
+  const rate = whitelistService.checkRateLimit(policy.windowMs, policy.max)
+  if (!rate.allowed) {
+    auditRefusal(attempt, `rate limited (${rate.count}/${rate.max})`)
+    return { ok: false, refusal: { code: 'RATE_LIMITED', error: '触发发送速率限制', rateLimit: rate } }
+  }
+  return { ok: true, rate }
+}
+
+/** 真的发出去，并按结果写审计。返回 `{success, error}`（不抛）。 */
+export async function performOutbound(attempt: OutboundAttempt): Promise<{ success: boolean; error?: string }> {
+  const token = configService.get('wechatOcToken')
+  const service = new WechatMessageService({ token })
+  let success = false
+  let error: string | undefined
+  try {
+    if (attempt.kind === 'image' && attempt.mediaPath) {
+      success = await service.sendImage(attempt.wxid, attempt.mediaPath)
+    } else if (attempt.kind === 'file' && attempt.mediaPath) {
+      success = await service.sendFile(attempt.wxid, attempt.mediaPath)
+    } else {
+      success = await service.sendText(attempt.wxid, attempt.text ?? '')
+    }
+  } catch {
+    error = '消息通道调用失败'
+  }
+  if (!success && !error) {
+    // 最像的原因就是缺 context_token —— 说清楚，别让人以为是"发失败"这种含糊的锅
+    const hasToken = !!(configService.getContextTokens()[attempt.wxid])
+    error = hasToken
+      ? '发送失败 (接口返回错误, 可能 token 过期)'
+      : '缺少 context_token — 需先收到对方一条消息 (或运行 weflow-cli listen 等待对方消息)'
+  }
+  whitelistService.auditSend({
+    timestamp: Date.now(), action: 'send', targetWxid: attempt.wxid,
+    targetName: attempt.displayName, kind: attempt.kind, success,
+    preview: attempt.preview, error: success ? undefined : error,
+  })
+  return { success, error }
+}

package/src/services/pythonBridge.ts

@@ -45,6 +45,7 @@ function realRunner(scriptPath: string, args: string[],
                     options: { timeoutMs: number; stdin?: string; env?: Record<string, string> }): Promise<ScriptRun> {
   return new Promise((resolve, reject) => {
     const child = spawn(getPythonCommand(), [scriptPath, ...args], {
+      windowsHide: true,
       // 用户输入走**环境变量**而不是 argv：这是仓库写进测试的隐私纪律（进程列表里看不到正文）
       env: createPythonProcessEnv(options.env ?? {}),
       stdio: ['pipe', 'pipe', 'pipe'],

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),
+  }
+}