weflow-cli 1.16.0 → 1.17.0

package/src/services/cursorProbe.ts

@@ -0,0 +1,222 @@
+/**
+ * 稳定增量游标的"路径可见"层（D-027）。
+ *
+ * `capabilities --json` 的 `stableCursor: false` 一直是一句结论；这里把它背后的
+ * 判据拆开，逐条给出当前状态与差在哪，让下游（she-love-me、MCP 客户端）能看见
+ * false → true 要满足什么，而不是等它某天悄悄变 true。
+ *
+ * 两类事实，来源不同、都必须如实标注：
+ *  - **代码事实**（静态）：每个后端有没有时间窗下推、有没有覆盖报告、合并顺序键是什么。
+ *    这些写在下面的表里，改读取器时要同步改。
+ *  - **数据事实**（实测）：NT 库里每张消息表有没有锚点列、采样的行带不带非零
+ *    `server_id`。这些只有开库才知道，由 `sync cursor-probe` 现场 probing，采样
+ *    有界且结果里写明 `exhaustive: false`。
+ */
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { configService } from './configService.js'
+import { NtCore } from '../core/ntCore.js'
+import type { NtCursorProbeResult, NtCursorProbeShard, NtCursorProbeSample } from '../core/ntCore.js'
+
+export type MessageBackend = 'nt' | 'raw-sqlite-4x' | 'wcdb-4x' | 'legacy-3x'
+
+export interface CursorCriterion {
+  id: string
+  /** 这条判据满足没有：true/false 是已核实的结论，null 是"当前无法判定" */
+  met: boolean | null
+  detail: string
+}
+
+export interface CursorProbeReport {
+  success: boolean
+  schema: 'weflow-cursor-probe/v1'
+  /** 结论不动：探针是让路径可见，不是替 D-027 翻案 */
+  stableCursor: false
+  backend: MessageBackend | null
+  backendNote: string
+  /** 数据事实那一半跑了没有（未初始化 / 非 NT 后端 = false） */
+  probedLive: boolean
+  criteria: CursorCriterion[]
+  /** NT 实测明细；probedLive=false 时为 undefined */
+  shards?: NtCursorProbeShard[]
+  sample?: NtCursorProbeSample
+  error?: string
+}
+
+/**
+ * 静态判断"这台机器会走哪条消息后端"。**镜像 `chatService.connect4x` 的尝试顺序**
+ * （先已解密 MSG0，再 NT，最后 WCDB），但只看配置与文件存在性、不开库——真正的
+ * 开库判定在 connect 里，而探测命令不该为了报一个名字去连数据库。
+ */
+export function likelyMessageBackend(): { backend: MessageBackend | null; note: string } {
+  const version = configService.get('dataVersion')
+  const dbPath = configService.get('dbPath')
+  const wxid = configService.get('wxid')
+  const dbPath3x = configService.get('dbPath3x')
+  const key3x = configService.get('decryptKey3x')
+  const ntDbPath = configService.get('ntDbPath')
+  const ntKey = configService.get('ntKey')
+  const ntSalt = configService.get('ntSalt')
+
+  if (version === '3.x' || (!version && dbPath3x && key3x)) {
+    return { backend: 'legacy-3x', note: '按 3.x 配置判定（sqlcipher + MSG 库）' }
+  }
+  if (version !== '4.x' && !dbPath && !(ntDbPath && ntKey && ntSalt)) {
+    return { backend: null, note: '未初始化：没有可判定的消息后端（先运行 weflow-cli init）' }
+  }
+  if (dbPath && wxid && existsSync(join(dbPath, wxid, 'Msg', 'Multi', 'MSG0_decrypted.db'))) {
+    return { backend: 'raw-sqlite-4x', note: '发现已解密的 MSG0_decrypted.db（connect4x 的第一优先）' }
+  }
+  if (ntDbPath && ntKey && ntSalt && existsSync(ntDbPath)) {
+    return { backend: 'nt', note: 'NT 配置完整（db_storage/message 分片）' }
+  }
+  if (dbPath) {
+    return { backend: 'wcdb-4x', note: '无解密 MSG0、无 NT 配置，connect4x 的最后兜底是 WCDB API' }
+  }
+  return { backend: null, note: '4.x 配置不完整：既无 dbPath 也无 NT 三件套' }
+}
+
+/** 各后端的**代码事实**。改读取器（下推 / 报告 / 顺序键）时同步改这张表。 */
+export const BACKEND_CAPS: Record<MessageBackend, {
+  identity: string
+  windowPushdown: boolean
+  coverageReport: boolean
+  liveProbe: boolean
+}> = {
+  'nt': {
+    identity: 'server_id（缺失时退化为 localId+createTime，后者不跨分片）',
+    windowPushdown: true,   // D-030: --from/--to 推进 SQL
+    coverageReport: true,   // 分片报告（connect_message_shards_detailed）
+    liveProbe: true,
+  },
+  'raw-sqlite-4x': {
+    identity: 'MsgSvrID 列被读取，但覆盖率从未实测',
+    windowPushdown: false,
+    coverageReport: false,
+    liveProbe: false,
+  },
+  'wcdb-4x': {
+    identity: 'server_id 随原生 API 返回，未实测；另有按时间的原生游标未接入 chatService',
+    windowPushdown: false,
+    coverageReport: false,
+    liveProbe: false,
+  },
+  'legacy-3x': {
+    identity: 'MsgSvrID 列被读取，但覆盖率从未实测',
+    windowPushdown: false,
+    coverageReport: false,
+    liveProbe: false,
+  },
+}
+
+export async function probeCursorReadiness(opts: {
+  tablesPerShard?: number
+  rowsPerTable?: number
+} = {}): Promise<CursorProbeReport> {
+  const { backend, note } = likelyMessageBackend()
+
+  const criteria: CursorCriterion[] = []
+  let live: NtCursorProbeResult | null = null
+  let shards: NtCursorProbeShard[] | undefined
+  let sample: NtCursorProbeSample | undefined
+
+  if (backend === 'nt') {
+    const ntDbPath = configService.get('ntDbPath')!
+    const ntKey = configService.get('ntKey')!
+    const ntSalt = configService.get('ntSalt')!
+    live = await new NtCore(ntDbPath, ntKey, ntSalt).cursorProbe(opts)
+    if (live.success) {
+      shards = live.shards
+      sample = live.sample
+    }
+  }
+
+  const caps = backend ? BACKEND_CAPS[backend] : null
+
+  // 1. stable-identity
+  if (backend === null) {
+    criteria.push({
+      id: 'stable-identity',
+      met: null,
+      detail: '没有可判定的后端',
+    })
+  } else if (backend === 'nt') {
+    if (!live?.success || !sample) {
+      criteria.push({
+        id: 'stable-identity',
+        met: null,
+        detail: `NT 实测没有跑成：${live?.error ?? '无结果'}`,
+      })
+    } else {
+      const failed = (live.shards ?? []).filter(s => !s.opened)
+      const anchorBad = live.schemaAnchorMissingTables ?? 0
+      const parts: string[] = []
+      if (failed.length) parts.push(`${failed.length} 个分片没打开`)
+      if (anchorBad > 0) parts.push(`${anchorBad} 组消息表缺锚点列`)
+      if (sample.serverIdMissing > 0) parts.push(`采样 ${sample.rowsSampled} 行里 ${sample.serverIdMissing} 行没有非零 server_id（这些行的身份退化为按分片的 localId+createTime）`)
+      if (sample.duplicateServerIds > 0) parts.push(`采样里 ${sample.duplicateServerIds} 个 server_id 出现在多个位置`)
+      criteria.push({
+        id: 'stable-identity',
+        met: parts.length === 0,
+        detail: parts.length
+          ? parts.join('；')
+          : `采样 ${sample.rowsSampled} 行（${sample.tablesSampled}/${sample.tablesTotal} 张表）全部带非零 server_id 且无重复；schema 全量检查 ${anchorBad} 组缺列。注意 exhaustive=false，这是采样结论`,
+      })
+    }
+  } else {
+    criteria.push({
+      id: 'stable-identity',
+      met: null,
+      detail: `${backend}：${caps!.identity}；该后端没有实测探针`,
+    })
+  }
+
+  // 2. globally-comparable-order（代码事实，对所有后端同为 false）
+  criteria.push({
+    id: 'globally-comparable-order',
+    met: false,
+    detail: '读取器跨分片合并的顺序键是 (createTime, localId)，localId 是分片内编号、不可跨分片比较；换成 (createTime, serverId) 是稳定游标在读取器侧的前提',
+  })
+
+  // 3. window-pushdown
+  criteria.push({
+    id: 'window-pushdown',
+    met: caps ? caps.windowPushdown : null,
+    detail: caps
+      ? (caps.windowPushdown
+          ? `${backend}：--from/--to 已下推进 SQL（D-030）`
+          : `${backend}：没有时间窗下推，窗口过滤全靠调用方拉全量后自筛`)
+      : '没有可判定的后端',
+  })
+
+  // 4. coverage-report
+  criteria.push({
+    id: 'coverage-report',
+    met: caps ? caps.coverageReport : null,
+    detail: caps
+      ? (caps.coverageReport
+          ? `${backend}：每分片读取结果都带覆盖报告（complete/unverified/partial）`
+          : `${backend}：无法报告读取是否完整，sync 在它上面永远是 unverified`)
+      : '没有可判定的后端',
+  })
+
+  // 5. every-backend（D-027 的总门）
+  const others = (Object.keys(BACKEND_CAPS) as MessageBackend[]).filter(b => b !== backend)
+  criteria.push({
+    id: 'every-backend',
+    met: false,
+    detail: `D-027：稳定游标要所有消息后端同时满足上述判据。当前后端 ${backend ?? '（未配置）'}；其余后端（${others.join('、')}）各自缺下推与覆盖报告`,
+  })
+
+  return {
+    success: true,
+    schema: 'weflow-cursor-probe/v1',
+    stableCursor: false,
+    backend,
+    backendNote: note,
+    probedLive: !!(backend === 'nt' && live?.success),
+    criteria,
+    ...(shards ? { shards } : {}),
+    ...(sample ? { sample } : {}),
+  }
+}

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