weflow-cli 1.16.0 → 1.19.0

package/src/services/qchatImport.ts

@@ -0,0 +1,327 @@
+/**
+ * `weflow-cli import qchat` —— 读 qchat-cli 的导出文件，归一化落进本地存储（D-129）。
+ *
+ * 边界是**文件契约**，不是进程耦合：qchat-cli 一行不用改，我们读它 `qce export --format json`
+ * 产出的那份 JSON（形状见 `parseQchatExport`）。落盘后的存储（`output/imports/qq/sessions/`）
+ * 是 weflow 这边的私有形状 `weflow-import/qq-v1`，字段语义与 `weflow-message/v1` 对齐
+ * （serverId/createTime/parsedContent/rawContent/13 个稳定 messageType）——一套词汇表两边用。
+ *
+ * QQ 的 `messageId` 是服务端全局唯一（OneBot 语义），所以去重/合并就靠它，不需要微信侧那套
+ * 重叠时间窗；这一点对 D-027 也成立：qq 来源天然满足 stable-identity 判据。
+ *
+ * 隐私边界：导入的是用户本人授权的 QQ 数据（qchat-cli 侧靠 NapCatQQ/OneBot 授权），落盘后
+ * 继承 weflow 的纪律——QQ 号与 wxid 同级敏感，不进公开输出；下游管道（搜索/知识卡）各自
+ * 已有的隐私门对它照常生效。
+ */
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { resolvePackageRoot } from '../utils/packageRoot.js'
+
+/** 存储根。`WEFLOW_IMPORT_ROOT` 可整体指到别处（测试用，Python 侧读同一个变量）。 */
+export function importRoot(): string {
+  if (process.env.WEFLOW_IMPORT_ROOT) return process.env.WEFLOW_IMPORT_ROOT
+  return join(resolvePackageRoot(import.meta.url), 'output', 'imports', 'qq')
+}
+
+function sessionsDir(): string {
+  return join(importRoot(), 'sessions')
+}
+
+export const IMPORT_SCHEMA = 'weflow-import/qq-v1'
+
+/** 与 weflow-message/v1 的 messageType 同一张表（13 个稳定名）。 */
+export type MessageType =
+  | 'text' | 'image' | 'voice' | 'card' | 'video' | 'emoji' | 'location'
+  | 'link' | 'call' | 'system' | 'quote' | 'other'
+
+export interface ImportedQqMessage {
+  /** qchat 的 messageId——全局唯一，去重/合并就靠它 */
+  serverId: string
+  messageSeq?: number
+  /** unix 秒（qchat 的 timestamp 字段） */
+  createTime: number
+  /** 仅当导入时给了 --own-id 才有；不给就是未知，消费方按"未知"处理而不是猜 */
+  isSend?: boolean
+  /** 发送者 QQ 号（敏感，同 wxid 级） */
+  senderUsername: string
+  /** 群名片优先，其次昵称，最后落回 QQ 号 */
+  senderName: string
+  messageType: MessageType
+  /** qchat 的 content（已拍平的文本） */
+  parsedContent: string
+  /** qchat 的 rawMessage */
+  rawContent: string
+}
+
+export interface ImportedQqSessionFile {
+  schema: typeof IMPORT_SCHEMA
+  session: { id: string; name: string; type: string }
+  importedAt: string
+  sourceFiles: string[]
+  messages: ImportedQqMessage[]
+}
+
+export interface QchatFilePlan {
+  file: string
+  ok: boolean
+  reason?: string
+  sessions: Array<{ id: string; name: string; type: string; messages: number }>
+}
+
+export interface ImportPlan {
+  files: QchatFilePlan[]
+  sessionsFound: number
+  messagesTotal: number
+  storeRoot: string
+}
+
+export interface ImportOutcome {
+  success: boolean
+  sessions: Array<{ id: string; name: string; added: number; updated: number; unchanged: number; total: number }>
+  filesOk: number
+  filesSkipped: number
+  storeRoot: string
+}
+
+/** OneBot 消息段 → weflow 的 13 个稳定类型。纯函数，映射表只有这一份。 */
+export function qqSegmentMessageType(segments: unknown[]): MessageType {
+  if (!Array.isArray(segments) || !segments.length) return 'text'
+  const priority: Array<[string, MessageType]> = [
+    ['record', 'voice'],
+    ['video', 'video'],
+    ['image', 'image'],
+    ['reply', 'quote'],
+    ['location', 'location'],
+    ['json', 'card'],
+    ['xml', 'card'],
+    ['contact', 'card'],
+    ['file', 'card'],
+    ['face', 'emoji'],
+  ]
+  const kinds = new Set(segments.map(s => String((s as any)?.type || '')))
+  for (const [seg, type] of priority) {
+    if (kinds.has(seg)) return type
+  }
+  return 'text'
+}
+
+/**
+ * qchat 导出 JSON 的形状识别与解析。判据是结构性的：顶层 `session` 对象 + `messages`
+ * 数组、且消息带 `messageId` 与 `timestamp`——认不出来就报错并给出原因，绝不猜。
+ */
+export function parseQchatExport(text: string, file: string): QchatFilePlan {
+  const fail = (reason: string): QchatFilePlan => ({
+    file, ok: false, reason, sessions: [],
+  })
+  let data: any
+  try {
+    data = JSON.parse(text)
+  } catch (e: any) {
+    return fail(`不是合法 JSON（${String(e?.message || e).slice(0, 80)}）`)
+  }
+  const session = data?.session
+  const messages = data?.messages
+  if (!session || typeof session !== 'object' || !Array.isArray(messages)) {
+    return fail('不是 qchat 导出形状（缺 session/messages；应为 `qce export --format json` 的产物）')
+  }
+  const id = String(session.id ?? '')
+  if (!id) return fail('session.id 为空')
+  let count = 0
+  for (const m of messages) {
+    if (m && (m.messageId !== undefined) && (m.timestamp !== undefined)) count += 1
+  }
+  if (!count && messages.length) {
+    return fail(`${messages.length} 条消息里没有一条带 messageId+timestamp——大概是别的格式的 JSON`)
+  }
+  return {
+    file, ok: true,
+    sessions: [{
+      id,
+      name: String(session.name || id),
+      type: String(session.type || 'private'),
+      messages: messages.length,
+    }],
+  }
+}
+
+/** 一条 qchat 消息 → 存储形状。字段映射只有这一处。 */
+export function normalizeQchatMessage(raw: any, ownId?: string): ImportedQqMessage | null {
+  if (!raw || raw.messageId === undefined || raw.timestamp === undefined) return null
+  const senderId = String(raw?.sender?.id ?? '')
+  const senderName = String(raw?.sender?.card || raw?.sender?.name || senderId)
+  const msg: ImportedQqMessage = {
+    serverId: String(raw.messageId),
+    ...(raw.message_seq !== undefined ? { messageSeq: Number(raw.message_seq) } : {}),
+    createTime: Number(raw.timestamp),
+    ...(ownId ? { isSend: senderId === ownId } : {}),
+    senderUsername: senderId,
+    senderName,
+    messageType: qqSegmentMessageType(raw.message),
+    parsedContent: String(raw.content ?? ''),
+    rawContent: String(raw.rawMessage ?? ''),
+  }
+  return msg
+}
+
+function safeSessionFile(id: string): string {
+  const safe = id.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 80)
+  return `${safe || 'session'}.json`
+}
+
+function readStoreSession(id: string): ImportedQqSessionFile | null {
+  const path = join(sessionsDir(), safeSessionFile(id))
+  if (!existsSync(path)) return null
+  try {
+    const data = JSON.parse(readFileSync(path, 'utf-8'))
+    if (data?.schema === IMPORT_SCHEMA && Array.isArray(data?.messages)) return data
+  } catch { /* 损坏的存储文件按"没有"处理，重导入会覆盖修复 */ }
+  return null
+}
+
+/** 收集输入路径下的候选文件（单文件或目录里的 *.json）。 */
+function candidateFiles(input: string): string[] {
+  if (!existsSync(input)) return []
+  // readdirSync 只对目录成立：文件会抛，正好当探测用
+  try {
+    const entries = readdirSync(input)
+    return entries.filter(f => f.toLowerCase().endsWith('.json'))
+      .map(f => join(input, f))
+  } catch {
+    return [input]
+  }
+}
+
+export function planImportQchat(input: string): ImportPlan {
+  const files = candidateFiles(input)
+  const plans: QchatFilePlan[] = []
+  if (!files.length) {
+    return {
+      files: [{ file: input, ok: false, reason: '输入不存在，或目录里没有 .json 文件', sessions: [] }],
+      sessionsFound: 0, messagesTotal: 0, storeRoot: sessionsDir(),
+    }
+  }
+  for (const file of files) {
+    let plan: QchatFilePlan
+    try {
+      plan = parseQchatExport(readFileSync(file, 'utf-8'), file)
+    } catch (e: any) {
+      plan = { file, ok: false, reason: `读不了（${String(e?.message || e).slice(0, 80)}）`, sessions: [] }
+    }
+    plans.push(plan)
+  }
+  const sessionIds = new Set(plans.flatMap(p => p.ok ? p.sessions.map(s => s.id) : []))
+  const messagesTotal = plans.flatMap(p => p.sessions).reduce((n, s) => n + s.messages, 0)
+  return {
+    files: plans,
+    sessionsFound: sessionIds.size,
+    messagesTotal,
+    storeRoot: sessionsDir(),
+  }
+}
+
+export function runImportQchat(input: string, ownId?: string): ImportOutcome {
+  const plan = planImportQchat(input)
+  const okFiles = plan.files.filter(f => f.ok)
+  if (!okFiles.length) {
+    return { success: false, sessions: [], filesOk: 0, filesSkipped: plan.files.length, storeRoot: plan.storeRoot }
+  }
+  mkdirSync(sessionsDir(), { recursive: true })
+  const merged = new Map<string, { existing: ImportedQqSessionFile | null; byId: Map<string, ImportedQqMessage>; sourceFiles: Set<string>; meta: { id: string; name: string; type: string } }>()
+  for (const f of okFiles) {
+    let data: any
+    try {
+      data = JSON.parse(readFileSync(f.file, 'utf-8'))
+    } catch {
+      continue // plan 已验证过可解析；这里的失败按跳过处理（计数在 filesSkipped）
+    }
+    const id = String(data.session.id)
+    let entry = merged.get(id)
+    if (!entry) {
+      entry = {
+        existing: readStoreSession(id),
+        byId: new Map((readStoreSession(id)?.messages ?? []).map(m => [m.serverId, m])),
+        sourceFiles: new Set(readStoreSession(id)?.sourceFiles ?? []),
+        meta: { id, name: String(data.session.name || id), type: String(data.session.type || 'private') },
+      }
+      merged.set(id, entry)
+    }
+    entry.sourceFiles.add(f.file)
+    for (const raw of data.messages ?? []) {
+      const msg = normalizeQchatMessage(raw, ownId)
+      if (msg) entry.byId.set(msg.serverId, msg)
+    }
+  }
+
+  const sessions = []
+  for (const [id, entry] of merged) {
+    const existing = entry.existing
+    const before = new Map((existing?.messages ?? []).map(m => [m.serverId, m]))
+    const messages = [...entry.byId.values()].sort((a, b) => a.createTime - b.createTime || a.serverId.localeCompare(b.serverId))
+    const file: ImportedQqSessionFile = {
+      schema: IMPORT_SCHEMA,
+      session: entry.meta,
+      importedAt: new Date().toISOString(),
+      sourceFiles: [...entry.sourceFiles],
+      messages,
+    }
+    writeFileSync(join(sessionsDir(), safeSessionFile(id)), JSON.stringify(file, null, 1), 'utf-8')
+    let added = 0, updated = 0, unchanged = 0
+    for (const m of messages) {
+      const old = before.get(m.serverId)
+      if (!old) added += 1
+      else if (JSON.stringify(old) !== JSON.stringify(m)) updated += 1
+      else unchanged += 1
+    }
+    sessions.push({ id: entry.meta.id, name: entry.meta.name, added, updated, unchanged, total: messages.length })
+  }
+
+  return {
+    success: true,
+    sessions,
+    filesOk: okFiles.length,
+    filesSkipped: plan.files.length - okFiles.length,
+    storeRoot: plan.storeRoot,
+  }
+}
+
+export interface ImportListEntry {
+  id: string
+  name: string
+  type: string
+  messages: number
+  oldestCreateTime: number | null
+  newestCreateTime: number | null
+  importedAt: string
+}
+
+export function listImports(): ImportListEntry[] {
+  const dir = sessionsDir()
+  if (!existsSync(dir)) return []
+  const out: ImportListEntry[] = []
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith('.json')) continue
+    try {
+      const data: any = JSON.parse(readFileSync(join(dir, f), 'utf-8'))
+      if (data?.schema !== IMPORT_SCHEMA) continue
+      const times = (data.messages ?? []).map((m: any) => Number(m.createTime) || 0).filter(Boolean)
+      out.push({
+        id: String(data.session?.id ?? ''),
+        name: String(data.session?.name ?? ''),
+        type: String(data.session?.type ?? ''),
+        messages: (data.messages ?? []).length,
+        oldestCreateTime: times.length ? Math.min(...times) : null,
+        newestCreateTime: times.length ? Math.max(...times) : null,
+        importedAt: String(data.importedAt ?? ''),
+      })
+    } catch { /* 单个损坏文件不挡住清单 */ }
+  }
+  return out.sort((a, b) => b.newestCreateTime! - a.newestCreateTime!)
+}
+
+/** 读回一个会话（验证导入用）。limit=0 是全部。 */
+export function readImportedSession(id: string, limit = 0): ImportedQqSessionFile | null {
+  const data = readStoreSession(id)
+  if (!data) return null
+  if (limit > 0) return { ...data, messages: data.messages.slice(-limit) }
+  return data
+}

package/src/services/setupVenv.ts

@@ -0,0 +1,238 @@
+/**
+ * `weflow-cli setup` —— 自管 Python venv。
+ *
+ * Issues 里最大的两类环境噪音：PowerShell 执行策略拦 `.ps1`（.cmd 包装绕开），
+ * 和 PATH 上只有微软商店的 python 占位程序（一跑 exit 9009，`getPythonCommand()`
+ * 兜底返回裸名 `python` 时正好交给它）。后者真正的根因是"这台机器没有一个能
+ * `import sqlcipher3` 的 Python"——本命令一次性解决：在 `~/.weflow-cli/venv`
+ * 建一个 venv、装上 requirements，之后 `getPythonCommand()` 优先用它。
+ *
+ * Windows 上 `sqlcipher3` 被替换为 `sqlcipher3-wheels`（预编译轮，import 名
+ * 相同）：源码包要 OpenSSL 头文件 + MSVC，正是要消掉的那类支持负担。替换会
+ * 写进计划与输出，不藏在背后。
+ */
+import { execFile } from 'child_process'
+import { promisify } from 'util'
+import { existsSync, readFileSync, rmSync } from 'fs'
+import { basename, join } from 'path'
+import { homedir } from 'os'
+import { resolvePackageRoot } from '../utils/packageRoot.js'
+import { clearPythonCommandCache, getPythonCommand } from '../utils/python.js'
+
+const execFileAsync = promisify(execFile)
+
+export const VENV_DIR = join(homedir(), '.weflow-cli', 'venv')
+
+export interface SetupPlan {
+  venvDir: string
+  venvPython: string
+  /** 用来建 venv 的解释器；null = 这台机器连可运行的 Python 都没有 */
+  creator: string | null
+  recreate: boolean
+  requirementFiles: string[]
+  /** 解析后的安装清单（注释/空行已去掉，win32 的替换已做） */
+  packages: string[]
+  /** 替换说明，如 `sqlcipher3 -> sqlcipher3-binary (Windows 预编译轮)` */
+  substitutions: string[]
+  createsUnder: '~/.weflow-cli/venv'
+  network: true
+}
+
+export interface SetupStep {
+  name: string
+  ok: boolean
+  /** 一步的补充事实（版本号、跳过原因等），不放大段日志 */
+  detail?: string
+}
+
+export interface SetupResult {
+  success: boolean
+  steps: SetupStep[]
+  venvPython: string
+  /** 安装完清缓存后 getPythonCommand() 的实际选择——应等于 venvPython */
+  effectivePython: string | null
+  error?: string
+}
+
+/** requirements 文件 → 去注释/空行的依赖列表。 */
+export function parseRequirements(text: string): string[] {
+  return text
+    .split('\n')
+    .map(line => line.trim())
+    .filter(line => line && !line.startsWith('#'))
+}
+
+/** win32 下把源码包换成预编译轮；其余平台原样。 */
+export function resolvePackages(names: string[], platform: string): { packages: string[]; substitutions: string[] } {
+  if (platform !== 'win32') return { packages: [...names], substitutions: [] }
+  // Windows 上的预编译轮是 `sqlcipher3-wheels`（cp310+ 的 win32/amd64/arm64 都有）。
+  // `sqlcipher3-binary` 只有 Linux/macOS 轮——CI 的 ubuntu 能装它，Windows 上
+  // pip 直接报 "No matching distribution"（2026-10-23 实测）。
+  const packages = names.map(n => (n === 'sqlcipher3' ? 'sqlcipher3-wheels' : n))
+  const substitutions = packages.some(p => p === 'sqlcipher3-wheels') && names.some(n => n === 'sqlcipher3')
+    ? ['sqlcipher3 -> sqlcipher3-wheels (Windows 预编译轮，import 名相同；源码包要 OpenSSL 头文件 + MSVC)']
+    : []
+  return { packages, substitutions }
+}
+
+/**
+ * 建一个"能用来创建 venv"的解释器探测：PATH 上的 python/py 逐个 `--version`。
+ * 商店占位程序在这一步就会被排掉（`--version` 以 9009 退出）。
+ */
+async function findCreator(): Promise<{ creator: string | null; version: string | null }> {
+  const names = process.platform === 'win32'
+    ? ['python', 'python3', 'py']
+    : ['python3', 'python']
+  for (const name of names) {
+    try {
+      const { stdout } = await execFileAsync(name, ['--version'], { windowsHide: true, timeout: 10_000 })
+      const version = stdout.trim().split('\n')[0] || null
+      return { creator: name, version }
+    } catch {
+      // 这个名字跑不起来（商店占位程序 9009 也会落到这里），试下一个
+    }
+  }
+  return { creator: null, version: null }
+}
+
+export async function planSetup(opts: {
+  recreate?: boolean
+  withVoice?: boolean
+  with3x?: boolean
+} = {}): Promise<SetupPlan> {
+  const pkgRoot = resolvePackageRoot(import.meta.url)
+  const files = ['requirements.txt']
+  if (opts.with3x) files.push('requirements-3x.txt')
+  if (opts.withVoice) files.push('requirements-voice.txt')
+
+  const names: string[] = []
+  for (const f of files) {
+    names.push(...parseRequirements(readFileSync(join(pkgRoot, f), 'utf-8')))
+  }
+  const { packages, substitutions } = resolvePackages([...new Set(names)], process.platform)
+  const { creator } = await findCreator()
+  const venvPython = process.platform === 'win32'
+    ? join(VENV_DIR, 'Scripts', 'python.exe')
+    : join(VENV_DIR, 'bin', 'python')
+
+  return {
+    venvDir: VENV_DIR,
+    venvPython,
+    creator,
+    recreate: !!opts.recreate,
+    requirementFiles: files,
+    packages,
+    substitutions,
+    createsUnder: '~/.weflow-cli/venv',
+    network: true,
+  }
+}
+
+export async function runSetup(plan: SetupPlan, onLine?: (line: string) => void): Promise<SetupResult> {
+  const steps: SetupStep[] = []
+  const say = (line: string) => onLine?.(line)
+
+  if (!plan.creator) {
+    return {
+      success: false,
+      steps: [{ name: 'find-python', ok: false, detail: 'PATH 上没有可运行的 Python（商店占位程序不算）——先装一个真正的 Python 3.10+ 再运行 setup' }],
+      venvPython: plan.venvPython,
+      effectivePython: null,
+      error: 'NO_USABLE_PYTHON',
+    }
+  }
+
+  // 1. 重建或创建 venv
+  if (plan.recreate && existsSync(plan.venvDir)) {
+    rmSync(plan.venvDir, { recursive: true, force: true })
+    steps.push({ name: 'remove-existing-venv', ok: true, detail: basename(plan.venvDir) })
+    say(`已删除旧 venv: ${plan.venvDir}`)
+  }
+  if (!existsSync(plan.venvDir)) {
+    try {
+      await execFileAsync(plan.creator, ['-m', 'venv', plan.venvDir], { windowsHide: true, timeout: 180_000 })
+      steps.push({ name: 'create-venv', ok: true, detail: `由 ${plan.creator} 创建` })
+      say(`已创建 venv: ${plan.venvDir}`)
+    } catch (e: any) {
+      return {
+        success: false,
+        steps: [...steps, { name: 'create-venv', ok: false, detail: String(e?.message || e).slice(0, 200) }],
+        venvPython: plan.venvPython,
+        effectivePython: null,
+        error: 'VENV_CREATE_FAILED',
+      }
+    }
+  } else {
+    steps.push({ name: 'create-venv', ok: true, detail: '已存在，跳过（--recreate 可重建）' })
+  }
+
+  // 2. 装依赖（走 venv 自己的 pip；PyPI 网络请求就是这一步）。
+  // 失败重试一次：PyPI 的瞬时网络错误（本机 2026-10-23 实测过一次整批失败、
+  // 逐包重装全过）不值得让用户从头再来——重试前说一声。
+  const pipArgs = ['-m', 'pip', 'install', '--disable-pip-version-check', ...plan.packages]
+  const pipDetail = (e: unknown): string => {
+    const err = e as { stderr?: string; message?: string }
+    const tail = (err?.stderr || '').split('\n').map(l => l.trim()).filter(Boolean).slice(-3).join(' | ')
+    return (tail || String(err?.message || e)).slice(0, 300)
+  }
+  let installed = false
+  let pipError: unknown = null
+  for (let attempt = 1; attempt <= 2 && !installed; attempt++) {
+    try {
+      say(attempt === 1
+        ? `安装 ${plan.packages.length} 个包（来自 ${plan.requirementFiles.join('、')}）...`
+        : `重试安装（第 1 次失败：${pipDetail(pipError)}）...`)
+      await execFileAsync(plan.venvPython, pipArgs, {
+        windowsHide: true,
+        timeout: 600_000,
+        maxBuffer: 10 * 1024 * 1024,
+      })
+      installed = true
+    } catch (e) {
+      pipError = e
+    }
+  }
+  if (!installed) {
+    return {
+      success: false,
+      steps: [...steps, { name: 'pip-install', ok: false, detail: pipDetail(pipError) }],
+      venvPython: plan.venvPython,
+      effectivePython: null,
+      error: 'PIP_INSTALL_FAILED',
+    }
+  }
+  steps.push({ name: 'pip-install', ok: true, detail: `${plan.packages.length} 个包（${plan.requirementFiles.join('、')}）` })
+  for (const s of plan.substitutions) say(`  替换: ${s}`)
+
+  // 3. 验收：venv 里真能 import sqlcipher3（NT 解密的核心依赖）
+  let verified = false
+  try {
+    await execFileAsync(plan.venvPython, ['-c', 'import sqlcipher3'], { windowsHide: true, timeout: 30_000 })
+    verified = true
+  } catch {
+    verified = false
+  }
+  steps.push({
+    name: 'verify-sqlcipher3',
+    ok: verified,
+    detail: verified ? 'import sqlcipher3 通过' : 'import sqlcipher3 失败——pip 报成功但模块不可用，把上面 pip 的完整输出贴到 issue',
+  })
+
+  // 4. 确认运行时真的会选它（清掉模块级缓存再看选择）
+  clearPythonCommandCache()
+  const effective = getPythonCommand()
+  const wiringOk = existsSync(plan.venvPython) && effective === plan.venvPython
+  steps.push({
+    name: 'runtime-prefers-venv',
+    ok: wiringOk,
+    detail: wiringOk ? 'getPythonCommand() 已指向自管 venv' : `getPythonCommand() 选了 ${effective}——venv 未通过探测（sqlcipher3 不可用时按原顺序回退 PATH）`,
+  })
+
+  return {
+    success: steps.every(s => s.ok),
+    steps,
+    venvPython: plan.venvPython,
+    effectivePython: effective,
+    ...(verified && !wiringOk ? { error: 'VENV_NOT_PREFERRED' } : {}),
+  }
+}

package/src/services/wechatCompat.ts

@@ -0,0 +1,67 @@
+/**
+ * 微信版本兼容：**单一事实源** + 纯比较。
+ *
+ * 背景（2026-10-25 起立此规矩）：微信 4.x 几周一更，而"这版 weflow-cli 在哪个微信版本上
+ * 验证过"原来只写在 PROJECT_STATE 的一段散文里——CHANGELOG 不记、机器读不到，用户升级
+ * 微信后读不出数据时，第一件事（"你的微信比我们验证过的新吗"）没人答得上来。
+ *
+ * 三条接线，都只从这读、别处不许再写一份：
+ *  - `capabilities --json` 的 `compatibility.wechat`（机器可读）；
+ *  - `check`（含 `--json` / `--report`）拿本机**实际加载**的版本与此比对，给出四种判定之一；
+ *  - `docs/RELEASING.md` 的发布清单要求每个 CHANGELOG 版本段记录验证版本（来源就是这里）。
+ *
+ * 更新 `WECHAT_VERIFIED` 的门槛：**必须伴随一次真实数据验证**（不只是"进程起来了"），
+ * 验证日期与读了什么写进 `verifiedHow`。没验证就不许改——这正是这个常量存在的意义。
+ */
+export const WECHAT_VERIFIED = {
+  version: '4.1.15.56',
+  verifiedAt: '2026-10-26',
+  verifiedHow: '升级后不重新提钥，用旧密钥实读真实数据：sessions / messages / contacts / '
+    + 'daily-stats / fav / sns stats 全部返回数据（2026-10-19，记录见 PROJECT_STATE「Initialization」）；'
+    + '2026-10-26 复核：sessions 实读仍正常、check 判定 verified',
+} as const
+
+export type CompatVerdict =
+  | 'verified'              // 本机加载的就是验证过的版本
+  | 'newer-than-verified'   // 本机更新：可能不兼容，读不出数据先怀疑这里
+  | 'older-than-verified'   // 本机更旧：通常是兼容的（向下兼容是常态，但没验证过也说不上保证）
+  | 'unknown'               // 微信没在跑 / 版本探测失败 / 版本串形状不对——"不知道"不是"没问题"
+
+/**
+ * 四段数字逐段比较（`4.1.15.56` vs `4.1.15.60`）。缺段按 0 处理（`4.1.15` < `4.1.15.56`）；
+ * 任一侧不是纯数字点分串就不猜——返回 `unknown`。纯函数。
+ */
+export function compareWechatVersions(live: string | null | undefined, verified: string): CompatVerdict {
+  const parse = (v: string): number[] | null => {
+    const parts = v.split('.')
+    if (!parts.length || !parts.every(p => /^\d+$/.test(p))) return null
+    return parts.map(Number)
+  }
+  if (!live) return 'unknown'
+  const a = parse(live)
+  const b = parse(verified)
+  if (!a || !b) return 'unknown'
+  const len = Math.max(a.length, b.length)
+  for (let i = 0; i < len; i++) {
+    const x = a[i] ?? 0
+    const y = b[i] ?? 0
+    if (x > y) return 'newer-than-verified'
+    if (x < y) return 'older-than-verified'
+  }
+  return 'verified'
+}
+
+/** 判定的人类可读一句话（check 人类输出与 --report 共用，措辞只有这一份）。 */
+export function describeCompatVerdict(verdict: CompatVerdict, verifiedVersion: string): string {
+  switch (verdict) {
+    case 'verified':
+      return `本机加载的微信就是本版本验证过的 ${verifiedVersion}`
+    case 'newer-than-verified':
+      return `本机微信比本版本验证过的 ${verifiedVersion} 更新——如果读不出数据，先怀疑这里`
+        + '（去 GitHub 看有没有更新版本）'
+    case 'older-than-verified':
+      return `本机微信比本版本验证过的 ${verifiedVersion} 更旧——一般兼容，但没有专门验证过`
+    default:
+      return `无法判定（微信没在运行或版本探测失败）；本版本验证过的是 ${verifiedVersion}`
+  }
+}