feat: 新增mac ocr转文字，增加到问一问微信图片索引优化速度

- 图片文字索引性能与进度诚实化 - 问问微信：证据卡区分「消息类型」与「派生来源」，派生命中内容自报来源 - 问问微信：回答规则禁止未真实执行的多轮承诺 - 本地图片文字识别：支持 macOS 系统 OCR（Apple Vision）
2026-10-04 03:01:42 +08:00 · 2026-09-17 13:11:20 +08:00
parent b8f08d54c8
commit 1337bcb7de
53 changed files with 4985 additions and 624 deletions
@@ -1,5 +1,5 @@
 /**
- * 「图片文字索引」的 P0 语义测试。
+ * 「图片文字索引」的 checkpoint（增量水位）与覆盖度契约。
 *
 * 这里覆盖的都是**不能用 UI 数字糊过去**的硬约束：
 * - 覆盖度必须在重启后依然诚实（派生库只知道处理过什么，不知道源数据一共多少）；
@@ -93,7 +93,7 @@ function makeHarness(options: { messages?: chat.FormattedMessage[] } = {}): Harn
  }
 }

-describe('§2 增量水位：只比条数会漏掉「等量替换」', () => {
+describe('增量水位：只比条数会漏掉「等量替换」', () => {
  it('水位（条数 + 最大插入序）都没变时才跳过，不读 WCDB', async () => {
    const harness = makeHarness({ messages: [imageMessage(10, 1000), imageMessage(20, 2000)] })
    harness.watermark.count = 2
@@ -162,7 +162,7 @@ describe('§2 增量水位：只比条数会漏掉「等量替换」', () => {
  })
 })

-describe('§1 覆盖度诚实性', () => {
+describe('覆盖度诚实性', () => {
  it('重启后仍是 partial：分母来自落盘统计，不会退化成 processed', async () => {
    const { databaseRoot, databasePath } = makeHarness()
    // 先按「已建立过索引」写库：总数 100，实际只处理了 30 条。
@@ -227,7 +227,7 @@ describe('§1 覆盖度诚实性', () => {
  })
 })

-describe('§5 清理：删得掉才算成功', () => {
+describe('清理：删得掉才算成功', () => {
  it('清理后派生库文件消失，覆盖度回到未建立', async () => {
    const { service, databasePath } = makeHarness()
    // 建一份有内容的派生数据（建库 + 写 artifact/binding/水位 + 落盘总数）。
@@ -261,7 +261,7 @@ describe('§5 清理：删得掉才算成功', () => {
  })
 })

-describe('§1/§7 查询层：覆盖度必须是独立维度且带零结果诚实性', () => {
+describe('查询层：覆盖度必须是独立维度且带零结果诚实性', () => {
  const coverageOf = (input: Partial<ImageTextIndexCoverage>): ImageTextIndexCoverage => ({
    totalImageMessages: 0,
    processed: 0,
@@ -0,0 +1,500 @@
+/**
+ * 图片文字索引的**并发契约**。
+ *
+ * 背景：backfill 从「批内严格串行」改成有界流水线（prepare 同步 → OCR 有限并行 → 单 writer 落库）。
+ * 并发一旦引入，下面这些性质就不再是"显然成立"，必须被测试锁住：
+ *
+ * 1. 同一张图并发派发 → OCR **最多一次**（否则白算，还违反"最多识别一次"的契约）；
+ * 2. 不同图片并发 → 结果不许串（文本 / 状态 / 身份各归各的）；
+ * 3. 暂停 → 在途的**安全收尾**（算了不落库等于白算），但**不再领取新任务**；
+ * 4. 取消 → checkpoint 正确（partial），已落库的终态一条不丢；
+ * 5. 某个 worker 报错 → 其它图片照常完成，整体任务不崩；
+ * 6. 进度语义不因并发失真：`processed` 只在终态之后 +1，且不重不漏；
+ * 7. 已有终态在并发下**依然一次都不重算**（并发不能把复用逻辑绕过去）。
+ *
+ * 全部使用 synthetic 图片（合法 PNG 魔数 + 唯一尾部字节），不碰任何真实数据。
+ */
+import { mkdtempSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type * as chat from '../../src/main/services/chat-service'
+import { ImageTextIndexService } from '../../src/main/services/image-text-index-service'
+import type { ImageTextIndexStageTimings } from '../../src/shared/image-text-index'
+import {
+  ImageTextIndexStore,
+  getImageTextIndexDatabasePath
+} from '../../src/main/services/image-text-index-store'
+
+const ACCOUNT = 'wxid_concurrency_fixture'
+const CONVERSATION = 'md5-concurrency'
+const roots: string[] = []
+
+function makeRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), 'tm-image-concurrency-'))
+  roots.push(root)
+  return root
+}
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
+})
+
+/** 合法 PNG 头 + 唯一尾部：不同 seed → 不同内容身份（sha256）。 */
+function pngBytes(seed: number): Buffer {
+  return Buffer.from([
+    0x89,
+    0x50,
+    0x4e,
+    0x47,
+    0x0d,
+    0x0a,
+    0x1a,
+    0x0a,
+    seed & 0xff,
+    (seed >> 8) & 0xff,
+    0x00
+  ])
+}
+
+function imageMessage(localId: number): chat.FormattedMessage {
+  return {
+    id: String(localId),
+    localId: String(localId),
+    from: 'user',
+    type: '图片',
+    content: '',
+    isSender: false,
+    name: '对方',
+    contentData: { type: 'image', md5: `md5-${localId}`, datName: `dat-${localId}` },
+    createTime: 1_700_000_000 + localId
+  } as unknown as chat.FormattedMessage
+}
+
+const capability = async (): Promise<{
+  available: boolean
+  engine: 'windows-system-ocr'
+  platform: 'win32'
+  runtimeVersion: string
+  language: string
+}> => ({
+  available: true,
+  engine: 'windows-system-ocr',
+  platform: 'win32',
+  runtimeVersion: '1.2.0',
+  language: 'zh-Hans-CN'
+})
+
+/** 从 data URL 里还原出这张图的 seed，用来断言"结果没有串图"。 */
+function seedFromDataUrl(dataUrl: string): number {
+  const base64 = dataUrl.slice(dataUrl.indexOf(',') + 1)
+  const bytes = Buffer.from(base64, 'base64')
+  return bytes[8] | (bytes[9] << 8)
+}
+
+/**
+ * 从假路径里取消息序号。
+ *
+ * 刻意锚定 `.dat` 后缀：直接用 `replace(/\D/g,'')` 会连 "md5" 里那个 **5** 一起抓进来
+ * （`md5-1` → "51"），这种坑只有真跑一次才会发现。
+ */
+function seedFromPath(path: string): number {
+  const matched = /(\d+)\.dat$/.exec(String(path))
+  return matched ? Number(matched[1]) : 1
+}
+
+const fakeDecryptImage = (path: string): Buffer => pngBytes(seedFromPath(path))
+
+const fakeFindImageFile = (md5: string): string => `C:/fake/${md5}.dat`
+
+interface Harness {
+  service: ImageTextIndexService
+  recognize: ReturnType<typeof vi.fn>
+  databaseRoot: string
+  databasePath: string
+  close: () => void
+}
+
+function harness(options: {
+  count: number
+  ocrConcurrency: number
+  /** 自定义 decrypt：默认按消息 id 给出唯一图片。 */
+  decryptImage?: (path: string) => Buffer
+  recognizeImpl?: (
+    dataUrl: string,
+    ctx: { callIndex: number; service: ImageTextIndexService }
+  ) => Promise<{ success: boolean; text: string; language: string | null; errorCode?: string }>
+}): Harness {
+  const databaseRoot = makeRoot()
+  const databasePath = getImageTextIndexDatabasePath(databaseRoot, ACCOUNT)
+  const messages = Array.from({ length: options.count }, (_, index) => imageMessage(index + 1))
+
+  const service = new ImageTextIndexService()
+  let callIndex = 0
+  const recognize = vi.fn(async (dataUrl: string) => {
+    callIndex += 1
+    if (options.recognizeImpl) return options.recognizeImpl(dataUrl, { callIndex, service })
+    return { success: true, text: `TEXT_${seedFromDataUrl(dataUrl)}`, language: null }
+  })
+
+  const decryptImage = options.decryptImage ?? fakeDecryptImage
+
+  service.bind({
+    databaseRoot,
+    resolveAccountId: () => ACCOUNT,
+    ocrConcurrency: options.ocrConcurrency,
+    listContacts: async () => [
+      { md5: CONVERSATION, m_nsUsrName: 'concurrency', type: 'user' as const }
+    ],
+    listMessages: async () => messages,
+    countConversationImages: async () => ({ count: messages.length, typeColumn: 'local_type' }),
+    imageWatermark: async () => ({ count: messages.length, maxLocalId: messages.length }),
+    capability,
+    decryptService: () => ({ findImageFile: fakeFindImageFile, decryptImage }) as never,
+    recognize
+  })
+
+  return {
+    service,
+    recognize,
+    databaseRoot,
+    databasePath,
+    close: () => service.resetAccount()
+  }
+}
+
+const finishPass = async (service: ImageTextIndexService): Promise<void> => {
+  await vi.waitFor(() => expect(service.isRunning()).toBe(false))
+}
+
+describe('并发契约', () => {
+  it('同一张图被并发派发 → OCR 只执行一次，但每个消息各自有 binding', async () => {
+    // 8 条消息，decrypt 全部返回**同一份字节** → 同一个内容身份 / artifact key。
+    const h = harness({
+      count: 8,
+      ocrConcurrency: 4,
+      decryptImage: () => pngBytes(42)
+    })
+
+    await h.service.startPass()
+    await finishPass(h.service)
+
+    expect(h.recognize).toHaveBeenCalledTimes(1)
+
+    const store = new ImageTextIndexStore(h.databasePath, ACCOUNT)
+    // binding 去重不成 1 条：8 个消息各自有 binding（去重不许丢来源）。
+    expect(store.countByState().indexed).toBe(8)
+    expect(store.getConversationOcr(CONVERSATION).size).toBe(8)
+    // artifact 才是被去重的那一层：8 张相同内容只产生 1 个带文本的 artifact。
+    expect(store.storageStats().ocrTextCount).toBe(1)
+    store.close()
+    h.close()
+  })
+
+  it('不同图片并发 → 结果各归各的，不串图', async () => {
+    const h = harness({ count: 16, ocrConcurrency: 4 })
+
+    await h.service.startPass()
+    await finishPass(h.service)
+
+    expect(h.recognize).toHaveBeenCalledTimes(16)
+
+    const store = new ImageTextIndexStore(h.databasePath, ACCOUNT)
+    const ocr = store.getConversationOcr(CONVERSATION)
+    expect(ocr.size).toBe(16)
+    // 每条消息的文本必须等于**它自己那张图**的 seed —— 串图会立刻打挂这里。
+    for (let id = 1; id <= 16; id += 1) {
+      expect(ocr.get(`local:${id}`)?.text).toBe(`TEXT_${id}`)
+    }
+    store.close()
+    h.close()
+  })
+
+  it('同时在途的 OCR 不超过配置的并发度（有界，不是无界扇出）', async () => {
+    let inFlight = 0
+    let maxInFlight = 0
+    const h = harness({
+      count: 40,
+      ocrConcurrency: 2,
+      recognizeImpl: async () => {
+        inFlight += 1
+        maxInFlight = Math.max(maxInFlight, inFlight)
+        // 让所有任务都有机会重叠：无界实现会在这里冲到 40。
+        await new Promise((resolve) => setTimeout(resolve, 5))
+        inFlight -= 1
+        return { success: true, text: 'TEXT', language: null }
+      }
+    })
+
+    await h.service.startPass()
+    await finishPass(h.service)
+
+    expect(h.recognize).toHaveBeenCalledTimes(40)
+    expect(maxInFlight).toBe(2)
+
+    h.close()
+  })
+
+  it('并发下进度不重不漏：processed 只统计已进入终态的图片', async () => {
+    const h = harness({ count: 16, ocrConcurrency: 4 })
+
+    await h.service.startPass()
+    await finishPass(h.service)
+
+    const status = await h.service.getStatus()
+    const { processed, indexed, empty, missing, failed, totalImageMessages } = status.progress
+    expect(processed).toBe(16)
+    expect(indexed + empty + missing + failed).toBe(processed)
+    expect(totalImageMessages).toBe(16)
+    // 并发度必须如实反映在诊断字段上。
+    expect(status.stageTimings?.ocrConcurrency).toBe(4)
+    expect(status.stageTimings?.ocrExecutions).toBe(16)
+    h.close()
+  })
+
+  it('暂停 → 在途任务安全收尾，且不再领取新任务', async () => {
+    const CONCURRENCY = 4
+    let releaseGate: (() => void) | null = null
+    const gate = new Promise<void>((resolve) => {
+      releaseGate = () => resolve()
+    })
+
+    const h = harness({
+      count: 32,
+      ocrConcurrency: CONCURRENCY,
+      recognizeImpl: async (_dataUrl, ctx) => {
+        // 槽位刚好填满的那一刻按暂停：此后不应再派发任何新任务。
+        if (ctx.callIndex === CONCURRENCY) ctx.service.pause()
+        await gate
+        return { success: true, text: 'TRACE_PAUSED', language: null }
+      }
+    })
+
+    void h.service.startPass()
+    // 等槽位填满（4 个在途 OCR 都卡在 gate 上）。
+    await vi.waitFor(() => expect(h.recognize).toHaveBeenCalledTimes(CONCURRENCY))
+
+    releaseGate?.()
+    await finishPass(h.service)
+
+    // 只派发过这一批：暂停之后不再领取新任务。
+    expect(h.recognize).toHaveBeenCalledTimes(CONCURRENCY)
+
+    const store = new ImageTextIndexStore(h.databasePath, ACCOUNT)
+    // 在途的 4 张都**落库**了（算了不落库等于白算）。
+    expect(store.countByState().indexed).toBe(CONCURRENCY)
+    expect(store.getConversationOcr(CONVERSATION).size).toBe(CONCURRENCY)
+    // 中断的会话必须留 partial checkpoint，下一遍才接得上。
+    expect(store.readScanState().get(CONVERSATION)?.state).toBe('partial')
+    store.close()
+
+    const status = await h.service.getStatus()
+    expect(status.progress.state).toBe('paused')
+    h.close()
+  })
+
+  it('取消 → checkpoint 正确，已落库的终态一条不丢，且不重算', async () => {
+    const CONCURRENCY = 4
+    let releaseGate: (() => void) | null = null
+    const gate = new Promise<void>((resolve) => {
+      releaseGate = () => resolve()
+    })
+
+    const h = harness({
+      count: 32,
+      ocrConcurrency: CONCURRENCY,
+      recognizeImpl: async (_dataUrl, ctx) => {
+        if (ctx.callIndex === CONCURRENCY) void ctx.service.cancel()
+        await gate
+        return { success: true, text: 'TRACE_CANCELLED', language: null }
+      }
+    })
+
+    void h.service.startPass()
+    await vi.waitFor(() => expect(h.recognize).toHaveBeenCalledTimes(CONCURRENCY))
+    releaseGate?.()
+    await finishPass(h.service)
+
+    const store = new ImageTextIndexStore(h.databasePath, ACCOUNT)
+    const persisted = store.countByState().indexed
+    expect(persisted).toBe(CONCURRENCY)
+    expect(store.readScanState().get(CONVERSATION)?.state).toBe('partial')
+    store.close()
+
+    const status = await h.service.getStatus()
+    expect(status.progress.state).toBe('cancelled')
+    h.close()
+  })
+
+  it('某个 worker 报错 → 其它图片照常完成，整体任务不崩', async () => {
+    const h = harness({
+      count: 12,
+      ocrConcurrency: 4,
+      recognizeImpl: async (dataUrl) => {
+        const seed = seedFromDataUrl(dataUrl)
+        if (seed === 5) throw new Error('native OCR blew up')
+        return { success: true, text: `TEXT_${seed}`, language: null }
+      }
+    })
+
+    await h.service.startPass()
+    await finishPass(h.service)
+
+    const status = await h.service.getStatus()
+    // 崩掉的那张记成失败，其余全部成功 —— 不是"整批失败"。
+    expect(status.progress.processed).toBe(12)
+    expect(status.progress.indexed).toBe(11)
+    expect(status.progress.failed).toBe(1)
+
+    const store = new ImageTextIndexStore(h.databasePath, ACCOUNT)
+    expect(store.getConversationOcr(CONVERSATION).get('local:6')?.text).toBe('TEXT_6')
+    store.close()
+    h.close()
+  })
+
+  it('并发不绕过复用：已有 100 条终态 + 新增 20 张 → OCR 只跑 20 次', async () => {
+    const h = harness({ count: 120, ocrConcurrency: 4 })
+
+    // 预热 1..100 为终态（与生产一致的复用语义）。
+    const seed = new ImageTextIndexStore(h.databasePath, ACCOUNT)
+    for (let index = 1; index <= 100; index += 1) {
+      const artifactKey = `seeded|${index}`
+      seed.putArtifact({
+        accountId: ACCOUNT,
+        artifactKey,
+        imageIdentity: `sha256:seeded-${index}`,
+        state: 'indexed',
+        text: `TRACE_SEEDED_${index}`,
+        charCount: 16,
+        engine: 'windows-system-ocr',
+        platform: 'win32',
+        runtimeVersion: '1.2.0',
+        language: 'zh-Hans-CN',
+        createdAt: index,
+        updatedAt: index
+      })
+      seed.putBinding({
+        accountId: ACCOUNT,
+        conversationId: CONVERSATION,
+        messageId: `local:${index}`,
+        createTime: index,
+        imageIdentity: `sha256:seeded-${index}`,
+        artifactKey,
+        state: 'indexed',
+        updatedAt: index
+      })
+    }
+    seed.close()
+
+    await h.service.startPass()
+    await finishPass(h.service)
+
+    // 关键断言：20 次，不是 120 次。
+    expect(h.recognize).toHaveBeenCalledTimes(20)
+
+    const store = new ImageTextIndexStore(h.databasePath, ACCOUNT)
+    // 旧终态文本原样保留，一条都没被重算覆盖。
+    expect(store.getArtifact('seeded|1')?.text).toBe('TRACE_SEEDED_1')
+    expect(store.getArtifact('seeded|100')?.text).toBe('TRACE_SEEDED_100')
+    store.close()
+    h.close()
+  })
+
+  it('按固定张数间隔写出分阶段性能画像（供无 GUI 排查）', async () => {
+    const profiles: ImageTextIndexStageTimings[] = []
+    const h = harness({ count: 1050, ocrConcurrency: 2 })
+    h.service.bind({ logStageProfile: (profile) => profiles.push(profile) })
+
+    await h.service.startPass()
+    await finishPass(h.service)
+
+    // 1050 张 / 每 500 张一条 → 恰好 2 条（504 与 1008）。
+    expect(profiles).toHaveLength(2)
+
+    const first = profiles[0]
+    expect(first.ocrConcurrency).toBe(2)
+    // 五个阶段都必须有样本，否则"时间花在哪一段"仍然是猜的。
+    for (const stage of [first.locate, first.decrypt, first.ocr, first.persist]) {
+      expect(stage.count).toBeGreaterThan(0)
+    }
+    expect(first.ocr.p95).toBeGreaterThanOrEqual(first.ocr.p50)
+    // 计数必须自洽：日志里要能直接看出进度，不必再回 UI 对数。
+    expect(first.counters.processed).toBeGreaterThan(0)
+    expect(
+      first.counters.indexed + first.counters.empty + first.counters.missing + first.counters.failed
+    ).toBe(first.counters.processed)
+    // 速度字段必须在（样本不足时允许为 null，但不能缺字段）。
+    expect(first).toHaveProperty('ratePerSec')
+    // 单张净耗时与五段之和同量级：不能把 preLoop 的一次性成本摊进来。
+    expect(first.perImageMs).toBeGreaterThan(0)
+    expect(first.perImageMs).toBeLessThan(
+      first.locate.mean +
+        first.decrypt.mean +
+        first.normalize.mean +
+        first.ocr.mean +
+        first.persist.mean +
+        50
+    )
+    // 画像里的数字是**累计**推进的，第二条必须更大 —— 否则它就不是"随时间推移的画像"。
+    expect(profiles[1].ocrExecutions).toBeGreaterThan(first.ocrExecutions)
+
+    h.close()
+  })
+
+  it('预算（messageLimit）用完 → 写 partial，不写假的 done checkpoint', async () => {
+    const h = harness({ count: 30, ocrConcurrency: 2 })
+
+    await h.service.startPass({ messageLimit: 10 })
+    await finishPass(h.service)
+
+    expect(h.recognize).toHaveBeenCalledTimes(10)
+
+    const store = new ImageTextIndexStore(h.databasePath, ACCOUNT)
+    const scan = store.readScanState().get(CONVERSATION)
+    // 关键：不能是 done —— 否则"已完成"在说谎，下一遍要么错误跳过（永久漏索引），
+    // 要么整会话重扫。真实库里曾经躺着 `done + processed=20 / total=23712`。
+    expect(scan?.state).toBe('partial')
+    expect(scan?.processed).toBe(10)
+    expect(scan?.imageTotal).toBe(30)
+    store.close()
+    h.close()
+  })
+
+  it('重启后不丢终态：新实例重跑同一批 → OCR 一次都不再执行', async () => {
+    const h = harness({ count: 24, ocrConcurrency: 4 })
+    await h.service.startPass()
+    await finishPass(h.service)
+    expect(h.recognize).toHaveBeenCalledTimes(24)
+
+    // 换一个全新的 service 实例（模拟重启），复用同一个派生库。
+    const restarted = new ImageTextIndexService()
+    const recognize2 = vi.fn(async () => ({
+      success: true,
+      text: 'SHOULD_NOT_RUN',
+      language: null
+    }))
+    restarted.bind({
+      databaseRoot: h.databaseRoot,
+      resolveAccountId: () => ACCOUNT,
+      ocrConcurrency: 4,
+      listContacts: async () => [
+        { md5: CONVERSATION, m_nsUsrName: 'concurrency', type: 'user' as const }
+      ],
+      listMessages: async () => Array.from({ length: 24 }, (_, index) => imageMessage(index + 1)),
+      countConversationImages: async () => ({ count: 24, typeColumn: 'local_type' }),
+      imageWatermark: async () => ({ count: 24, maxLocalId: 24 }),
+      capability,
+      decryptService: () =>
+        ({ findImageFile: fakeFindImageFile, decryptImage: fakeDecryptImage }) as never,
+      recognize: recognize2
+    })
+
+    await restarted.startPass()
+    await vi.waitFor(() => expect(restarted.isRunning()).toBe(false))
+    expect(recognize2).not.toHaveBeenCalled()
+    restarted.resetAccount()
+
+    h.close()
+  })
+})
@@ -1,14 +1,13 @@
 /**
- * 事故回归：**"4.5 万张全部失败，UI 却说已建立"** 这一整套语义。
+ * 覆盖度诚实性：**派生库的统计绝不能替用户宣称"已经建好了"。**
 *
- * 真机现场（派生库实测）：
- *   total = 45,707 / 全部 binding = decrypt_failed 45,479 / artifacts = 0 行
- * 根因是解密服务在回填时不存在（只在 db:getImage 里懒加载），每张图都在
- * `processOne` 第一步就失败。这里把"不许再发生"的四件事钉死：
- *   1. 前置依赖缺失时必须**一条记录都不写**（preflight）；
- *   2. 处理过但一条没成功 = **异常**，不是"已建立"；
- *   3. 百分比不许四舍五入到 100（45,479 / 45,707）；
+ * 这一组覆盖四条彼此独立的硬约束：
+ *   1. 前置依赖缺失时必须**一条记录都不写**（否则会写出一堆假失败）；
+ *   2. 处理过但一条都没成功 = **异常**，不是"已建立"，且必须阻断 complete；
+ *   3. 百分比不许四舍五入到 100（99.5% 不能显示成"全部完成"）；
 *   4. 重置失败记录**不能**动已经成功的记录。
+ *
+ * 判据来自 `ImageTextIndexStore.countByState()` 的落盘统计，不依赖任何内存计数器。
 */
 import { mkdtempSync } from 'node:fs'
 import { rm } from 'node:fs/promises'
@@ -28,12 +27,12 @@ import {
  type ImageTextIndexCoverage
 } from '../../src/shared/image-text-index'

-const ACCOUNT = 'wxid_incident_fixture'
-const CONVERSATION = 'md5-incident'
+const ACCOUNT = 'wxid_coverage_fixture'
+const CONVERSATION = 'md5-coverage'
 const roots: string[] = []

 function makeRoot(): string {
-  const root = mkdtempSync(join(tmpdir(), 'tm-image-incident-'))
+  const root = mkdtempSync(join(tmpdir(), 'tm-image-coverage-'))
  roots.push(root)
  return root
 }
@@ -69,13 +68,13 @@ function coverageOf(overrides: Partial<ImageTextIndexCoverage>): ImageTextIndexC
  }
 }

-describe('事故语义：全失败不能叫"已建立"', () => {
+describe('全失败不能叫"已建立"', () => {
  it('indexed/empty/missing 全为 0 而 failed 不为 0 → 异常，且 complete 必为 false', () => {
    const coverage = coverageOf({
-      totalImageMessages: 45_707,
-      processed: 45_479,
-      failed: 45_479,
-      pending: 228,
+      totalImageMessages: 2000,
+      processed: 1990,
+      failed: 1990,
+      pending: 10,
      established: true,
      countedAt: 1_789_516_520_246,
      complete: false, // 服务侧已经算出 false；这里验证状态与文案
@@ -87,12 +86,12 @@ describe('事故语义：全失败不能叫"已建立"', () => {
    expect(describeImageTextCoverage(coverage)).not.toContain('已覆盖全部')
  })

-  it('45,479 / 45,707 不能显示成 100%', () => {
-    // Math.round(45479 / 45707 * 100) === 100 —— 这正是"仅完成 100%"的来源。
-    expect(Math.round((45_479 / 45_707) * 100)).toBe(100)
+  it('处理好绝大多数时不能四舍五入显示成 100%', () => {
+    // Math.round(1990 / 2000 * 100) === 100 —— 这就是"未完成却显示 100%"的来源。
+    expect(Math.round((1990 / 2000) * 100)).toBe(100)
    // 正确口径：保留 1 位小数，未完成时封顶 99.9。
-    expect(imageTextProcessedPercent(45_479, 45_707)).toBe(99.5)
-    expect(imageTextProcessedPercent(45_707, 45_707)).toBe(100)
+    expect(imageTextProcessedPercent(1990, 2000)).toBe(99.5)
+    expect(imageTextProcessedPercent(2000, 2000)).toBe(100)
    expect(imageTextProcessedPercent(0, 0)).toBe(0)
  })

@@ -172,7 +171,7 @@ describe('事故语义：全失败不能叫"已建立"', () => {
  })
 })

-describe('事故防线：前置依赖缺失时一条记录都不写', () => {
+describe('前置依赖缺失时一条记录都不写', () => {
  it('解密服务不可用 → pass 直接报错，不写任何 binding', async () => {
    const databaseRoot = makeRoot()
    const databasePath = getImageTextIndexDatabasePath(databaseRoot, ACCOUNT)
@@ -181,7 +180,7 @@ describe('事故防线：前置依赖缺失时一条记录都不写', () => {
      databaseRoot,
      resolveAccountId: () => ACCOUNT,
      listContacts: async () => [
-        { md5: CONVERSATION, m_nsUsrName: 'incident', type: 'group' as const }
+        { md5: CONVERSATION, m_nsUsrName: 'coverage', type: 'group' as const }
      ],
      listMessages: async () => [imageMessage(1)],
      countConversationImages: async () => ({ count: 1, typeColumn: 'local_type' }),
@@ -193,7 +192,7 @@ describe('事故防线：前置依赖缺失时一条记录都不写', () => {
        runtimeVersion: '1.2.0',
        language: 'zh-Hans-CN'
      }),
-      // 关键：没有解密服务（本次事故的根因形态）
+      // 关键：解密服务缺失是**运行时**问题，不能落成每张图的"解密失败"
      decryptService: () => null
    })

@@ -201,7 +200,7 @@ describe('事故防线：前置依赖缺失时一条记录都不写', () => {
    await vi.waitFor(() => expect(service.isRunning()).toBe(false))

    const status = await service.getStatus()
-    // 这一条就是整场事故的防线：宁可一次都不跑，也不要写 45,479 条假失败。
+    // 判据：宁可一次都不跑，也不要写一堆假失败把派生库和 coverage 一起污染。
    expect(status.progress.state).toBe('error')
    expect(status.progress.lastError).toContain('解密服务')
    expect(status.coverage.processed).toBe(0)
@@ -215,7 +214,7 @@ describe('事故防线：前置依赖缺失时一条记录都不写', () => {
  })
 })

-describe('事故收尾：重置失败记录不能动成功记录', () => {
+describe('重置失败记录不能动成功记录', () => {
  it('只删失败绑定与它们的 checkpoint，indexed 一条不动', async () => {
    const databaseRoot = makeRoot()
    const databasePath = getImageTextIndexDatabasePath(databaseRoot, ACCOUNT)
@@ -0,0 +1,190 @@
+/**
+ * 图片索引的**数据边界**契约。
+ *
+ * 历史问题：图片索引为了找图片，先读整个会话（十几万到二十几万条消息）再在 JS 里筛。
+ * 大会话实测单次读取 15s 以上，而那些行 99% 以上是图片索引根本不看的文本消息 ——
+ * 这是数据边界错了，不是 OCR 慢。
+ *
+ * 这一组锁三件事：
+ *   1. 接了专用查询就必须走它，**不能再回退到全量读取**；
+ *   2. 专用查询产出的 `FormattedMessage` 与全量路径**逐字段同构**（否则 artifact /
+ *      binding / checkpoint 的键会变）；
+ *   3. 专用路径仍然按图片类型过滤（召回归档可能补进非图片的撤回消息）。
+ */
+import { mkdtempSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type * as chat from '../../src/main/services/chat-service'
+import { ImageTextIndexService } from '../../src/main/services/image-text-index-service'
+import {
+  ImageTextIndexStore,
+  getImageTextIndexDatabasePath
+} from '../../src/main/services/image-text-index-store'
+
+const ACCOUNT = 'wxid_boundary_fixture'
+const CONVERSATION = 'md5-boundary'
+const TEXT_COUNT = 40
+const IMAGE_COUNT = 12
+const roots: string[] = []
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
+})
+
+function pngBytes(seed: number): Buffer {
+  return Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, seed & 0xff])
+}
+
+/** 一半文本、一半图片：只有真图片会被索引。 */
+function mixedMessages(): chat.FormattedMessage[] {
+  const messages: chat.FormattedMessage[] = []
+  for (let index = 0; index < TEXT_COUNT; index += 1) {
+    messages.push({
+      id: `text-${index}`,
+      localId: String(index + 1),
+      from: 'user',
+      type: '文本',
+      content: `第 ${index} 条文本`,
+      isSender: false,
+      name: '对方',
+      contentData: { type: 'text', text: `第 ${index} 条文本` },
+      createTime: 1_700_000_000 + index
+    } as unknown as chat.FormattedMessage)
+  }
+  for (let index = 0; index < IMAGE_COUNT; index += 1) {
+    messages.push({
+      id: `image-${index}`,
+      localId: String(TEXT_COUNT + index + 1),
+      from: 'user',
+      type: '图片',
+      content: '',
+      isSender: false,
+      name: '对方',
+      contentData: {
+        type: 'image',
+        md5: `imgmd5-${index}`,
+        datName: `imgdat-${index}`
+      },
+      createTime: 1_700_000_000 + TEXT_COUNT + index
+    } as unknown as chat.FormattedMessage)
+  }
+  return messages
+}
+
+interface Harness {
+  service: ImageTextIndexService
+  databasePath: string
+  listMessages: ReturnType<typeof vi.fn>
+  listImageMessages: ReturnType<typeof vi.fn>
+}
+
+function createHarness(): Harness {
+  const databaseRoot = mkdtempSync(join(tmpdir(), 'tm-boundary-'))
+  roots.push(databaseRoot)
+  const all = mixedMessages()
+  const imagesOnly = all.filter((message) => message.contentData?.type === 'image')
+
+  const listMessages = vi.fn(async () => all)
+  const listImageMessages = vi.fn(async () => imagesOnly)
+
+  const service = new ImageTextIndexService()
+  service.bind({
+    databaseRoot,
+    progressNotifyIntervalMs: 0,
+    resolveAccountId: () => ACCOUNT,
+    ocrConcurrency: 1,
+    listContacts: async () => [
+      { md5: CONVERSATION, m_nsUsrName: 'boundary', type: 'user' as const }
+    ],
+    countConversationImages: async () => ({ count: IMAGE_COUNT, typeColumn: 'local_type' }),
+    imageWatermark: async () => ({ count: IMAGE_COUNT, maxLocalId: TEXT_COUNT + IMAGE_COUNT }),
+    listMessages,
+    listImageMessages,
+    capability: async () => ({
+      available: true,
+      engine: 'macos-system-ocr',
+      platform: 'darwin',
+      runtimeVersion: '1.2.0',
+      language: null
+    }),
+    decryptService: () =>
+      ({
+        findImageFile: (md5: string) => `C:/fake/${md5}.dat`,
+        decryptImage: (path: string) => pngBytes(Number(/(\d+)\.dat$/.exec(String(path))?.[1] ?? 0))
+      }) as never,
+    recognize: async () => ({ success: true, text: 'TEXT', language: null })
+  })
+
+  return {
+    service,
+    databasePath: getImageTextIndexDatabasePath(databaseRoot, ACCOUNT),
+    listMessages,
+    listImageMessages
+  }
+}
+
+describe('图片索引的数据边界', () => {
+  it('uses the image-only query and never falls back to the full conversation read', async () => {
+    const h = createHarness()
+
+    await h.service.startPass()
+    await vi.waitFor(() => expect(h.service.isRunning()).toBe(false), { timeout: 60_000 })
+
+    // 专用查询被调用；全量读取**一次都不许发生**。
+    expect(h.listImageMessages).toHaveBeenCalledTimes(1)
+    expect(h.listMessages).not.toHaveBeenCalled()
+    // 拿到的行数必须只与图片有关，而不是整个会话。
+    expect(h.listImageMessages.mock.calls[0][0]).toBe(CONVERSATION)
+
+    const status = await h.service.getStatus()
+    expect(status.progress.processed).toBe(IMAGE_COUNT)
+
+    h.service.resetAccount()
+  })
+
+  it('produces the same bindings as the full-conversation path', async () => {
+    const h = createHarness()
+    const full = createHarness()
+    // 对照：拿掉专用查询，强制走老的"全量读 + JS 筛"。
+    full.service.bind({ listImageMessages: undefined })
+
+    await h.service.startPass()
+    await vi.waitFor(() => expect(h.service.isRunning()).toBe(false), { timeout: 60_000 })
+    await full.service.startPass()
+    await vi.waitFor(() => expect(full.service.isRunning()).toBe(false), { timeout: 60_000 })
+
+    expect(h.listMessages).not.toHaveBeenCalled()
+    expect(full.listMessages).toHaveBeenCalledTimes(1)
+
+    const readBindings = (databasePath: string): Array<Record<string, unknown>> => {
+      const store = new ImageTextIndexStore(databasePath, ACCOUNT)
+      try {
+        return store.getConversationOcr(CONVERSATION).size > 0
+          ? [...store.getConversationOcr(CONVERSATION).entries()].map(([messageId, entry]) => ({
+              messageId,
+              state: entry.state,
+              text: entry.text
+            }))
+          : []
+      } finally {
+        store.close()
+      }
+    }
+
+    const withImageQuery = readBindings(h.databasePath)
+    const withFullRead = readBindings(full.databasePath)
+
+    expect(withImageQuery.length).toBe(IMAGE_COUNT)
+    /**
+     * 这条是本用例的核心：两条路径产出的**绑定键与结果**必须逐条相同。
+     * 一旦有人改了图片专用查询里的字段映射，`messageId` 会变、键会变，
+     * 已有的 artifact / checkpoint 就会全部失效 —— 那正是不会报错但很贵的回归。
+     */
+    expect(withImageQuery).toEqual(withFullRead)
+
+    h.service.resetAccount()
+    full.service.resetAccount()
+  })
+})
@@ -1,5 +1,5 @@
 /**
- * §2 / §3 的硬条件：清理图片文字索引必须让 **Knowledge 里已经产生的 OCR 派生文字**一起失效。
+ * 硬条件：清理图片文字索引必须让 **Knowledge 里已经产生的 OCR 派生文字**一起失效。
 *
 * 背景：OCR 文本经 normalizer 的固定前缀 `图片文字：` 拼进 `searchableText`，
 * 再进 chunks / FTS。所以"清理成功"不能只等于"派生 SQLite 删掉了" ——
@@ -96,9 +96,7 @@ function imageMessageWithoutOcr(caption?: string): KnowledgeSourceMessage {
 }

 function searchTokens(store: KnowledgeStore, text: string): string[] {
-  return store
-    .search({ accountId: ACCOUNT, text, limit: 20 })
-    .map((item) => item.messageId)
+  return store.search({ accountId: ACCOUNT, text, limit: 20 }).map((item) => item.messageId)
 }

 function evidenceFor(store: KnowledgeStore, text: string) {
@@ -115,7 +113,7 @@ async function indexConversation(
  })
 }

-describe('§2-A Knowledge 侧的失效机制：OCR 派生文字必须能真的消失', () => {
+describe('Knowledge 侧的失效机制：OCR 派生文字必须能真的消失', () => {
  it('图片消息仍然存在、只是 OCR 文本没了 → 旧 OCR 文字搜不到，普通文字不受影响', async () => {
    const store = new KnowledgeStore(makeRoot(), ACCOUNT, fts)

@@ -155,7 +153,7 @@ describe('§2-A Knowledge 侧的失效机制：OCR 派生文字必须能真的
    store.close()
  })

-  it('§3：OCR 文本变化（state 仍是 indexed）也必须让旧文本失效', async () => {
+  it('OCR 文本变化（state 仍是 indexed）也必须让旧文本失效', async () => {
    const store = new KnowledgeStore(makeRoot(), ACCOUNT, fts)

    await indexConversation(store, [textMessage(), imageMessageWithOcr()])
@@ -175,7 +173,7 @@ describe('§2-A Knowledge 侧的失效机制：OCR 派生文字必须能真的
  })
 })

-describe('§2-B 生产路径：清理必须逐会话重建 Knowledge', () => {
+describe('生产路径：清理必须逐会话重建 Knowledge', () => {
  function imageMessage(localId: number, conversationId: string): chat.FormattedMessage {
    return {
      localId: String(localId),
@@ -215,9 +213,14 @@ describe('§2-B 生产路径：清理必须逐会话重建 Knowledge', () => {
    await service.startPass()
    await vi.waitFor(() => expect(service.isRunning()).toBe(false))

-    // 两个会话都真的产生了绑定。
+    /**
+     * 这个 fixture **刻意没有解密服务** ⇒ 所有图片都落成 `image_missing`，没有一条
+     * 可搜索的 OCR 文字。所以本遍**不应该**叫醒 Knowledge：
+     * 索引侧没有可搜索内容变化，重建纯属白读一遍 WCDB。
+     * （"有文字 ⇒ 必须重建"由 image-text-index-store-cache 的门控用例覆盖。）
+     */
    const databasePath = getImageTextIndexDatabasePath(databaseRoot, ACCOUNT)
-    expect(onConversationIndexed).toHaveBeenCalledTimes(2)
+    expect(onConversationIndexed).toHaveBeenCalledTimes(0)

    onConversationIndexed.mockClear()
    const result = await service.clear()
@@ -0,0 +1,240 @@
+/**
+ * 图片文字索引的**进度通知节流**契约。
+ *
+ * 背景：后台按 `BATCH_SIZE = 12` 推进，但 UI 不该感知 batch 大小 ——
+ * 每批都推会让计数以「+12」的粒度跳动。
+ *
+ * 硬要求：
+ *  1. 正常运行态最多每 `progressNotifyIntervalMs` 推一次**最新权威快照**；
+ *  2. 状态变化（开始/暂停/继续/取消/完成/失败）**立即**推，不等窗口；
+ *  3. 完成必须立即给出最终值；
+ *  4. 同时最多一个 timer，pass 结束后不留残留定时器；
+ *  5. 推的是快照，不是把窗口内几十个 delta 重放给 Renderer。
+ *
+ * 为了避免时序脆弱的测试，最关键的一条用**把窗口设得极大**来表达：
+ * 如果节流正确，整遍 pass 里只应有「开始」和「完成」两次状态变化通知。
+ */
+import { mkdtempSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type * as chat from '../../src/main/services/chat-service'
+import { ImageTextIndexService } from '../../src/main/services/image-text-index-service'
+import type { ImageTextIndexStatus } from '../../src/shared/image-text-index'
+
+const ACCOUNT = 'wxid_progress_notify_fixture'
+const CONVERSATION = 'md5-progress-notify'
+const roots: string[] = []
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
+})
+
+function makeRoot(): string {
+  const root = mkdtempSync(join(tmpdir(), 'tm-progress-notify-'))
+  roots.push(root)
+  return root
+}
+
+function pngBytes(seed: number): Buffer {
+  return Buffer.from([
+    0x89,
+    0x50,
+    0x4e,
+    0x47,
+    0x0d,
+    0x0a,
+    0x1a,
+    0x0a,
+    seed & 0xff,
+    (seed >> 8) & 0xff
+  ])
+}
+
+function imageMessage(localId: number): chat.FormattedMessage {
+  return {
+    id: String(localId),
+    localId: String(localId),
+    from: 'user',
+    type: '图片',
+    content: '',
+    isSender: false,
+    name: '对方',
+    contentData: { type: 'image', md5: `md5-${localId}`, datName: `dat-${localId}` },
+    createTime: 1_700_000_000 + localId
+  } as unknown as chat.FormattedMessage
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
+
+/** 每张图 sleep 一点，让 pass 有可观测的持续时间。 */
+function createService(options: { count: number; notifyIntervalMs: number; perImageMs?: number }): {
+  service: ImageTextIndexService
+  notifications: Array<{ at: number; processed: number; state: string }>
+} {
+  const databaseRoot = makeRoot()
+  const messages = Array.from({ length: options.count }, (_, index) => imageMessage(index + 1))
+  const perImageMs = options.perImageMs ?? 0
+
+  const service = new ImageTextIndexService()
+  service.bind({
+    databaseRoot,
+    progressNotifyIntervalMs: options.notifyIntervalMs,
+    resolveAccountId: () => ACCOUNT,
+    ocrConcurrency: 2,
+    listContacts: async () => [{ md5: CONVERSATION, m_nsUsrName: 'notify', type: 'user' as const }],
+    listMessages: async () => messages,
+    countConversationImages: async () => ({ count: messages.length, typeColumn: 'local_type' }),
+    imageWatermark: async () => ({ count: messages.length, maxLocalId: messages.length }),
+    capability: async () => ({
+      available: true,
+      engine: 'windows-system-ocr',
+      platform: 'win32',
+      runtimeVersion: '1.2.0',
+      language: 'zh-Hans-CN'
+    }),
+    decryptService: () =>
+      ({
+        findImageFile: (md5: string) => `C:/fake/${md5}.dat`,
+        decryptImage: (path: string) => pngBytes(Number(/(\d+)\.dat$/.exec(String(path))?.[1] ?? 1))
+      }) as never,
+    recognize: async () => {
+      if (perImageMs > 0) await sleep(perImageMs)
+      return { success: true, text: 'TEXT', language: null }
+    }
+  })
+
+  const notifications: Array<{ at: number; processed: number; state: string }> = []
+  service.onStatusChange((status: ImageTextIndexStatus) => {
+    notifications.push({
+      at: Date.now(),
+      processed: status.progress.processed,
+      state: status.progress.state
+    })
+  })
+
+  return { service, notifications }
+}
+
+const finish = async (service: ImageTextIndexService): Promise<void> => {
+  await vi.waitFor(() => expect(service.isRunning()).toBe(false))
+}
+
+describe('进度通知节流', () => {
+  it('窗口极大时，整遍 pass 只推「开始」和「完成」两次状态变化', async () => {
+    // 240 张 = 20 个 batch。若每批都推会有 20+ 次通知；节流正确则只有状态变化。
+    const { service, notifications } = createService({
+      count: 240,
+      notifyIntervalMs: 100_000,
+      perImageMs: 2
+    })
+
+    await service.startPass()
+    await finish(service)
+
+    expect(notifications.map((n) => n.state)).toEqual(['running', 'completed'])
+    // 完成必须带**最终值**，不能等下一次 5 秒 timer。
+    expect(notifications[notifications.length - 1].processed).toBe(240)
+    service.resetAccount()
+  })
+
+  it('窗口为 0 时不做节流（每次都推最新快照）', async () => {
+    const { service, notifications } = createService({
+      count: 240,
+      notifyIntervalMs: 0,
+      perImageMs: 2
+    })
+
+    await service.startPass()
+    await finish(service)
+
+    // 不节流 ⇒ 通知数应远多于「仅两次状态变化」，且处理量单调不减。
+    expect(notifications.length).toBeGreaterThan(4)
+    const processed = notifications.map((n) => n.processed)
+    expect([...processed].sort((a, b) => a - b)).toEqual(processed)
+    expect(processed[processed.length - 1]).toBe(240)
+    service.resetAccount()
+  })
+
+  it('暂停立即推送，不等窗口', async () => {
+    const { service, notifications } = createService({
+      count: 600,
+      notifyIntervalMs: 100_000,
+      perImageMs: 4
+    })
+
+    void service.startPass()
+    // 注意：窗口是 100 秒，**进度通知按设计不会来**，所以不能用通知当等待条件。
+    await vi.waitFor(async () => {
+      const status = await service.getStatus()
+      expect(status.progress.processed).toBeGreaterThan(0)
+    })
+    service.pause()
+    await finish(service)
+
+    const pausedAt = notifications.findIndex((n) => n.state === 'paused')
+    expect(pausedAt).toBeGreaterThanOrEqual(0)
+    // 暂停之后不应再有「运行中」的进度推送（窗口是 100 秒，等不到）。
+    expect(notifications.slice(pausedAt + 1).some((n) => n.state === 'running')).toBe(false)
+    service.resetAccount()
+  })
+
+  it('pass 结束后不留残留 timer：不再产生额外通知', async () => {
+    const { service, notifications } = createService({
+      count: 120,
+      notifyIntervalMs: 30,
+      perImageMs: 1
+    })
+
+    await service.startPass()
+    await finish(service)
+    const afterFinish = notifications.length
+    // 窗口只有 30ms，如果尾随 timer 没被清掉，这段时间里一定会再冒出通知。
+    await sleep(200)
+    expect(notifications.length).toBe(afterFinish)
+    expect(notifications[notifications.length - 1].state).toBe('completed')
+    service.resetAccount()
+  })
+
+  it('continue（重新 startPass）不会叠加出第二个 timer', async () => {
+    const { service, notifications } = createService({
+      count: 240,
+      notifyIntervalMs: 30,
+      perImageMs: 1
+    })
+
+    void service.startPass()
+    await vi.waitFor(async () => {
+      const status = await service.getStatus()
+      expect(status.progress.processed).toBeGreaterThan(0)
+    })
+    service.pause()
+    await finish(service)
+
+    const pausedCount = notifications.length
+    await service.resume()
+    await finish(service)
+    await sleep(200)
+
+    // 恢复后应重新开始推送，但不应因"两个 interval 并存"而翻倍：
+    // 第一遍以 paused 收尾、第二遍以 completed 收尾 ⇒ completed 恰好 1 次。
+    expect(notifications.length).toBeGreaterThan(pausedCount)
+    const completed = notifications.filter((n) => n.state === 'completed')
+    expect(completed).toHaveLength(1)
+    expect(notifications.filter((n) => n.state === 'paused')).toHaveLength(1)
+    service.resetAccount()
+  })
+
+  it('速度与 ETA 只在窗口样本足够时给出，否则为 null', async () => {
+    const { service } = createService({ count: 120, notifyIntervalMs: 0, perImageMs: 1 })
+    await service.startPass()
+    await finish(service)
+
+    const status = await service.getStatus()
+    // 这遍跑得太快，窗口跨度不足 ⇒ 必须如实为 null（UI 显示"计算中"），不许编数。
+    expect(status.progress.speedPerSec).toBeNull()
+    expect(status.progress.etaMs).toBeNull()
+    service.resetAccount()
+  })
+})
@@ -0,0 +1,572 @@
+/**
+ * 派生库句柄的**账号身份缓存契约**。
+ *
+ * `resolveAccountId()` 不是廉价 getter：main 把它绑定成同步 WCDB 查询。
+ * 而 `ensureStore()` 在图片处理热路径上会被每张图片调用多次，所以身份解析
+ * **必须**只发生常数次；否则它就成了每张图片的固定成本，且完全不随 OCR 并发改善。
+ *
+ * 这一组用例把契约钉住：
+ *   1. 身份解析只发生常数次（不是每张图片一次）；
+ *   2. 解析本身再慢，也只能让整遍多付一次；
+ *   3. 切账号仍然换库 —— `resetAccount()` 是权威的失效信号；
+ *   4. 解析失败（空结果）不被永久缓存；
+ *   5. 进入流水线之前的一次性成本不算进单张净耗时。
+ */
+import { existsSync, mkdtempSync } from 'node:fs'
+import { rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import type * as chat from '../../src/main/services/chat-service'
+import { ImageTextIndexService } from '../../src/main/services/image-text-index-service'
+import { getImageTextIndexDatabasePath } from '../../src/main/services/image-text-index-store'
+
+const ACCOUNT = 'wxid_store_cache_fixture'
+const IMAGES = 24
+const roots: string[] = []
+
+afterEach(async () => {
+  await Promise.all(roots.splice(0).map((root) => rm(root, { recursive: true, force: true })))
+})
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms))
+
+/** 同步阻塞：模拟同步 WCDB 查询（不是 await，是实打实占住主线程）。 */
+function blockFor(ms: number): void {
+  const end = Date.now() + ms
+  while (Date.now() < end) {
+    /* busy */
+  }
+}
+
+/** 合法 PNG 头 + 唯一尾部：不同 seed → 不同内容身份（sha256）。 */
+function pngBytes(seed: number): Buffer {
+  return Buffer.from([
+    0x89,
+    0x50,
+    0x4e,
+    0x47,
+    0x0d,
+    0x0a,
+    0x1a,
+    0x0a,
+    seed & 0xff,
+    (seed >> 8) & 0xff
+  ])
+}
+
+function imageMessage(localId: number): chat.FormattedMessage {
+  return {
+    id: String(localId),
+    localId: String(localId),
+    from: 'user',
+    type: '图片',
+    content: '',
+    isSender: false,
+    name: '对方',
+    contentData: { type: 'image', md5: `md5-${localId}`, datName: `dat-${localId}` },
+    createTime: 1_700_000_000 + localId
+  } as unknown as chat.FormattedMessage
+}
+
+const seedFromPath = (path: string): number => Number(/(\d+)\.dat$/.exec(String(path))?.[1] ?? 1)
+
+interface Harness {
+  service: ImageTextIndexService
+  databaseRoot: string
+  /** 切换当前会话：让下一遍不被 checkpoint 跳过，用来验证"换库后重新处理"。 */
+  setConversation: (conversationId: string) => void
+  bindingCount: (accountId: string) => number
+}
+
+function createHarness(options: {
+  resolveAccountId: () => string
+  /** 注入到"每个会话一次"的前置路径上（countConversationImages / listMessages）。 */
+  preLoopDelayMs?: number
+  /** 注入到会话完成后的 Knowledge 重建回调（属于别的模块的成本）。 */
+  onConversationIndexedDelayMs?: number
+  /** OCR 返回的文字；空串 = 识别成"没有文字"（非可搜索结果）。 */
+  recognizeText?: string
+  ocrMs?: number
+}): Harness {
+  const databaseRoot = mkdtempSync(join(tmpdir(), 'tm-store-cache-'))
+  roots.push(databaseRoot)
+  const messages = Array.from({ length: IMAGES }, (_, index) => imageMessage(index + 1))
+  let conversation = 'conv-initial'
+
+  const service = new ImageTextIndexService()
+  service.bind({
+    databaseRoot,
+    progressNotifyIntervalMs: 0,
+    resolveAccountId: options.resolveAccountId,
+    ocrConcurrency: 1,
+    listContacts: async () => [
+      { md5: conversation, m_nsUsrName: conversation, type: 'user' as const }
+    ],
+    countConversationImages: async () => {
+      if (options.preLoopDelayMs) await sleep(options.preLoopDelayMs)
+      return { count: messages.length, typeColumn: 'local_type' }
+    },
+    imageWatermark: async () => ({ count: messages.length, maxLocalId: messages.length }),
+    listMessages: async () => {
+      if (options.preLoopDelayMs) await sleep(options.preLoopDelayMs)
+      return messages
+    },
+    capability: async () => ({
+      available: true,
+      engine: 'macos-system-ocr',
+      platform: 'darwin',
+      runtimeVersion: '1.2.0',
+      language: null
+    }),
+    decryptService: () =>
+      ({
+        findImageFile: (md5: string) => `C:/fake/${md5}.dat`,
+        decryptImage: (path: string) => pngBytes(seedFromPath(path))
+      }) as never,
+    recognize: async () => {
+      if (options.ocrMs) await sleep(options.ocrMs)
+      return { success: true, text: options.recognizeText ?? 'TEXT', language: null }
+    },
+    onConversationIndexed: async () => {
+      if (options.onConversationIndexedDelayMs) await sleep(options.onConversationIndexedDelayMs)
+    }
+  })
+
+  return {
+    service,
+    databaseRoot,
+    setConversation: (conversationId) => {
+      conversation = conversationId
+    },
+    bindingCount: (accountId) => {
+      const path = getImageTextIndexDatabasePath(databaseRoot, accountId)
+      if (!existsSync(path)) return 0
+      const db = new DatabaseSync(path)
+      try {
+        const row = db.prepare('SELECT COUNT(*) AS n FROM image_ocr_bindings').get() as {
+          n: number
+        }
+        return Number(row?.n ?? 0)
+      } finally {
+        db.close()
+      }
+    }
+  }
+}
+
+const runPass = async (
+  service: ImageTextIndexService,
+  options: { sinceMs?: number } = {}
+): Promise<void> => {
+  await service.startPass(options)
+  await vi.waitFor(() => expect(service.isRunning()).toBe(false), { timeout: 60_000 })
+}
+
+describe('派生库句柄的账号身份缓存', () => {
+  it('caches account identity until reset', async () => {
+    let resolveCalls = 0
+    const h = createHarness({
+      resolveAccountId: () => {
+        resolveCalls += 1
+        blockFor(30)
+        return ACCOUNT
+      },
+      ocrMs: 5
+    })
+
+    await runPass(h.service)
+
+    expect((await h.service.getStatus()).progress.processed).toBe(IMAGES)
+    console.log(`[store-cache] 张数=${IMAGES} resolveAccountId 调用=${resolveCalls}`)
+    // 每张图片都要重新解析的话，这里会是 2 × IMAGES 的量级。
+    expect(resolveCalls).toBeLessThanOrEqual(3)
+
+    h.service.resetAccount()
+  })
+
+  it('identity resolution cost is paid once per pass, not per image', async () => {
+    const RESOLVE_MS = 30
+    const OCR_MS = 5
+    const slow = createHarness({
+      resolveAccountId: () => {
+        blockFor(RESOLVE_MS)
+        return ACCOUNT
+      },
+      ocrMs: OCR_MS
+    })
+    const fast = createHarness({ resolveAccountId: () => ACCOUNT, ocrMs: OCR_MS })
+
+    await runPass(fast.service)
+    await runPass(slow.service)
+
+    const fastPerImage = (await fast.service.getStatus()).stageTimings?.perImageMs ?? 0
+    const slowPerImage = (await slow.service.getStatus()).stageTimings?.perImageMs ?? 0
+
+    /**
+     * 用**差值**断言而不是绝对阈值，避免锁住某台机器的速度：
+     * 身份解析变慢 30ms，若只付一次，单张净耗时最多只涨这一点点；
+     * 若每张都要付（甚至两次），差值会是 30ms 的倍数。
+     */
+    expect(slowPerImage - fastPerImage).toBeLessThan(RESOLVE_MS + 70)
+
+    fast.service.resetAccount()
+    slow.service.resetAccount()
+  })
+
+  it('invalidates store cache on reset', async () => {
+    let account = 'account-A'
+    const h = createHarness({ resolveAccountId: () => account })
+
+    await runPass(h.service)
+    expect(h.bindingCount('account-A')).toBe(IMAGES)
+    expect(h.bindingCount('account-B')).toBe(0)
+
+    // 切账号：换身份 + 显式失效（main 在全部切换路径上都会这样做）。
+    account = 'account-B'
+    h.setConversation('conv-B')
+    h.service.resetAccount()
+    await runPass(h.service)
+
+    expect(h.bindingCount('account-B')).toBe(IMAGES)
+    // A 的库不得被继续写入 —— 这就是"切账号必须换句柄"要防的串账号。
+    expect(h.bindingCount('account-A')).toBe(IMAGES)
+
+    h.service.resetAccount()
+  })
+
+  it('does not cache unresolved account identity', async () => {
+    let account = ''
+    let resolveCalls = 0
+    const h = createHarness({
+      resolveAccountId: () => {
+        resolveCalls += 1
+        return account
+      }
+    })
+
+    // 微信还没就绪：解析结果为空 → 不建库、也不该把空结果记成"已解析"。
+    await runPass(h.service)
+    expect((await h.service.getStatus()).progress.state).toBe('error')
+    const callsWhileUnresolved = resolveCalls
+    expect(callsWhileUnresolved).toBeGreaterThan(0)
+
+    // 数据就绪之后再跑：必须能重新解析出来（空结果没有被永久缓存）。
+    account = ACCOUNT
+    h.service.resetAccount()
+    await runPass(h.service)
+    expect((await h.service.getStatus()).progress.processed).toBe(IMAGES)
+    expect(resolveCalls).toBeGreaterThan(callsWhileUnresolved)
+
+    h.service.resetAccount()
+  })
+
+  it('pre-loop cost is excluded from per-image cost', async () => {
+    const PRE_LOOP_MS = 400
+    const withPreLoop = createHarness({
+      resolveAccountId: () => ACCOUNT,
+      preLoopDelayMs: PRE_LOOP_MS,
+      ocrMs: 5
+    })
+    const control = createHarness({ resolveAccountId: () => ACCOUNT, ocrMs: 5 })
+
+    const wallStartedAt = Date.now()
+    await runPass(withPreLoop.service)
+    const wallMs = Date.now() - wallStartedAt
+    await runPass(control.service)
+
+    const status = await withPreLoop.service.getStatus()
+    const timings = status.stageTimings
+    expect(timings).toBeDefined()
+    if (!timings) return
+    const processed = status.progress.processed
+    expect(processed).toBe(IMAGES)
+
+    const controlPerImage = (await control.service.getStatus()).stageTimings?.perImageMs ?? 0
+    console.log(
+      `[store-cache] 整遍 wall=${wallMs}ms 整遍/张=${(wallMs / processed).toFixed(1)}ms ` +
+        `单张净=${timings.perImageMs}ms（对照 ${controlPerImage}ms）startup=${timings.preLoop.startupMs}ms`
+    )
+
+    // 前置成本必须被单独量出来（本用例在 countConversationImages 与 listMessages 各注入一次）。
+    expect(timings.preLoop.startupMs).toBeGreaterThanOrEqual(PRE_LOOP_MS * 2 - 100)
+    expect(timings.preLoop.countImageMessagesMs).toBeGreaterThanOrEqual(PRE_LOOP_MS - 100)
+    expect(timings.preLoop.listMessagesMs).toBeGreaterThanOrEqual(PRE_LOOP_MS - 100)
+    // 会话级准备必须覆盖 listMessages，否则"每会话一次"的成本会漏出去。
+    expect(timings.preLoop.conversationSetupMs).toBeGreaterThanOrEqual(
+      timings.preLoop.listMessagesMs
+    )
+
+    /**
+     * 单张净耗时**不能**因为前置成本变贵而变贵 —— 用对照实例做差值断言，
+     * 这样既锁住了语义，又不会锁住某台机器的速度。
+     */
+    expect(timings.perImageMs).toBeLessThan(controlPerImage + 60)
+    // 反过来，"整遍 ÷ 张数"必然被前置成本抬高 —— 这正是它不能当成单张成本的原因。
+    expect(wallMs / processed).toBeGreaterThan(timings.perImageMs * 5)
+
+    withPreLoop.service.resetAccount()
+    control.service.resetAccount()
+  })
+})
+
+/**
+ * 会话完成后等待 Knowledge 重建的成本（`onConversationIndexed`）。
+ *
+ * 这一段是**别的模块**的成本：Knowledge 会对同一个会话再全量读一遍消息并整篇写索引，
+ * 而且如果此时有索引在跑还会先等它。它不在 batch 循环里。
+ *
+ * 这一组锁两件容易同时搞砸的事：
+ *   1. 它必须被**单独量出来**（否则"单张很快、整遍很慢"无从归因）；
+ *   2. 它**不能**被算进单张净耗时（否则单张数字会被别的模块污染）。
+ */
+describe('会话级 Knowledge 重建成本的归因', () => {
+  it('attributes the Knowledge callback to preLoop, not to per-image cost', async () => {
+    const INDEXED_MS = 300
+    const slow = createHarness({
+      resolveAccountId: () => ACCOUNT,
+      onConversationIndexedDelayMs: INDEXED_MS,
+      ocrMs: 5
+    })
+    const control = createHarness({ resolveAccountId: () => ACCOUNT, ocrMs: 5 })
+
+    await runPass(control.service)
+    await runPass(slow.service)
+
+    const timings = (await slow.service.getStatus()).stageTimings
+    expect(timings).toBeDefined()
+    if (!timings) return
+    const controlPerImage = (await control.service.getStatus()).stageTimings?.perImageMs ?? 0
+
+    // 必须被单独量出来：本用例只跑了一个会话，回调延迟应完整落在该桶里。
+    expect(timings.preLoop.onConversationIndexedMs).toBeGreaterThanOrEqual(INDEXED_MS - 60)
+    console.log(
+      `[store-cache] onConversationIndexedMs=${timings.preLoop.onConversationIndexedMs}ms ` +
+        `单张净=${timings.perImageMs}ms（对照 ${controlPerImage}ms）`
+    )
+
+    /**
+     * 用差值断言：回调再慢，单张净耗时也不该跟着涨。
+     * 若有人把这段并进 `perImageMs`，这里会立刻红 —— 那正是"图片索引变慢"被误判成
+     * "OCR 变慢"的起因。
+     */
+    expect(timings.perImageMs).toBeLessThan(controlPerImage + 60)
+
+    slow.service.resetAccount()
+    control.service.resetAccount()
+  })
+})
+
+/**
+ * 可观测性契约：**慢步骤必须自己说出"卡在哪一步"**。
+ *
+ * 背景：实测出现过"一次运行 81 分钟零落库"。没有这条日志时只能看到"没有进度"，
+ * 无法区分"自己慢"和"被别的模块按住" —— 而这两者的修法完全不同。
+ */
+describe('慢步骤告警', () => {
+  it('reports which step is blocking when it exceeds the threshold', async () => {
+    const h = createHarness({
+      resolveAccountId: () => ACCOUNT,
+      onConversationIndexedDelayMs: 400
+    })
+    // 自己接管这一步：先证明它真的被调用了，再断言告警。
+    const indexed = vi.fn(async () => {
+      await sleep(400)
+    })
+    h.service.bind({ onConversationIndexed: indexed, slowStepWarnMs: 100 })
+
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    try {
+      await runPass(h.service)
+      // 前提：这一步确实被调用了 —— 否则下面找不到告警的原因是错的。
+      expect(indexed).toHaveBeenCalled()
+
+      const lines = warn.mock.calls
+        .map((call) => String(call[0] ?? ''))
+        .filter((message) => message.includes('[ImageTextIndex] slow step='))
+
+      // 必须报出被按住的那一步，并且带耗时。
+      expect(lines.find((line) => line.includes('knowledge-index'))).toBeDefined()
+      expect(lines.some((line) => /elapsedMs=\d+/.test(line))).toBe(true)
+      // 只报步骤名与耗时，不得出现会话标识 / 内容。
+      expect(lines.join(' ')).not.toContain('conv-initial')
+    } finally {
+      warn.mockRestore()
+    }
+
+    h.service.resetAccount()
+  })
+
+  it('stays quiet when every step is fast', async () => {
+    const h = createHarness({ resolveAccountId: () => ACCOUNT, ocrMs: 1 })
+    h.service.bind({ slowStepWarnMs: 100_000 })
+
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => undefined)
+    try {
+      await runPass(h.service)
+      expect(
+        warn.mock.calls
+          .map((call) => String(call[0] ?? ''))
+          .filter((message) => message.includes('slow step='))
+      ).toEqual([])
+    } finally {
+      warn.mockRestore()
+    }
+
+    h.service.resetAccount()
+  })
+})
+
+/**
+ * 画像触发的时间兜底。
+ *
+ * 只按处理量触发时，吞吐掉到个位数会让画像十几分钟才出一条 ——
+ * 而那正是最需要画像的时刻。
+ */
+describe('画像的时间兜底触发', () => {
+  it('emits a profile after the idle window even when the image count is far below the interval', async () => {
+    const h = createHarness({ resolveAccountId: () => ACCOUNT, ocrMs: 30 })
+    const profiles: unknown[] = []
+    h.service.bind({
+      logStageProfile: (profile) => profiles.push(profile),
+      // 张数阈值仍是 500（默认），本用例只有 IMAGES 张 ⇒ 只能靠时间触发。
+      stageProfileMaxIdleMs: 1
+    })
+
+    await runPass(h.service)
+
+    expect(IMAGES).toBeLessThan(500)
+    expect(profiles.length).toBeGreaterThan(0)
+
+    h.service.resetAccount()
+  })
+})
+
+/**
+ * Knowledge 重建的门控：**没有可搜索内容变化就不要叫醒它。**
+ *
+ * 为什么这是硬要求：Knowledge 侧是"读整个会话 → 重分片整会话"，代价与消息数成正比，
+ * 而且这一步在 `await` 路径上。图片索引走过的大多数会话里，被识别的图片要么没有文字、
+ * 要么图片文件已被清理 —— 那些结果不改变可搜索内容，重建纯属白做，却会把索引按住十几秒。
+ *
+ * 这一组锁三件事：
+ *   1. 全部结果都不可搜索（无文字 / 图片缺失）⇒ **不调用** Knowledge；
+ *   2. 只要有**一条**识别出文字 ⇒ 必须调用（可搜索内容变了）；
+ *   3. **已知终态直接跳过**的图片不得让会话被判成 dirty（用户明确要求的那条）。
+ */
+describe('Knowledge 重建门控', () => {
+  const runOnceWith = async (options: {
+    recognizeText?: string
+  }): Promise<{ indexed: ReturnType<typeof vi.fn>; skipped: number }> => {
+    const h = createHarness({
+      resolveAccountId: () => ACCOUNT,
+      ocrMs: 1,
+      ...(options.recognizeText === undefined ? {} : { recognizeText: options.recognizeText })
+    })
+    const indexed = vi.fn(async () => undefined)
+    h.service.bind({ onConversationIndexed: indexed })
+
+    await runPass(h.service)
+    const timings = (await h.service.getStatus()).stageTimings
+    h.service.resetAccount()
+    return { indexed, skipped: timings?.knowledgeIndexSkipped ?? -1 }
+  }
+
+  it('all non-searchable results → Knowledge is not woken up', async () => {
+    const { indexed, skipped } = await runOnceWith({ recognizeText: '' })
+
+    expect(indexed).not.toHaveBeenCalled()
+    expect(skipped).toBe(1)
+  })
+
+  it('a single searchable result → Knowledge must be rebuilt', async () => {
+    const { indexed, skipped } = await runOnceWith({ recognizeText: '识别出来的文字' })
+
+    expect(indexed).toHaveBeenCalledTimes(1)
+    expect(skipped).toBe(0)
+  })
+
+  it('images skipped as already-terminal do not mark the conversation dirty', async () => {
+    const h = createHarness({ resolveAccountId: () => ACCOUNT, ocrMs: 1 })
+    const indexed = vi.fn(async () => undefined)
+    h.service.bind({ onConversationIndexed: indexed })
+
+    // 第一遍：正常识别出文字 ⇒ 会调用一次。
+    await runPass(h.service)
+    expect(indexed).toHaveBeenCalledTimes(1)
+
+    /**
+     * 第二遍带时间窗 ⇒ **刻意绕过 checkpoint 跳过**（窗口模式下不做增量跳过），
+     * 这样才会真的进到"逐张检查"这一步：所有图片都已是终态 ⇒ `fill()` 直接短路、
+     * 不调 `settle()` ⇒ 会话不得被判成 dirty ⇒ 不得再叫 Knowledge。
+     *
+     * 若不带窗口，整个会话会被 checkpoint 整体跳过 —— 那也安全，但测不到这条规则。
+     */
+    await runPass(h.service, { sinceMs: 1 })
+    expect(indexed).toHaveBeenCalledTimes(1)
+
+    const timings = (await h.service.getStatus()).stageTimings
+    expect(timings?.knowledgeIndexSkipped).toBeGreaterThanOrEqual(1)
+
+    h.service.resetAccount()
+  })
+})
+
+/**
+ * 「可搜索 → 不可搜索」是否可能**经由 settle()** 发生。
+ *
+ * 为什么必须证明它：dirty 判定是 `state === 'indexed' && text.trim()`。
+ * 如果存在一条路径能让一条**原本有 OCR 文字**的消息重新进 settle() 并落成
+ * empty / image_missing / 空文字，那么旧的可搜索文字就会留在 Knowledge 里 —— 搜索能搜到、
+ * 但索引已经"没有"那段文字，属于静默的 stale 结果。
+ *
+ * 结论：**不可达**。依据是全量穷举写入/删除面（见下两条用例）。
+ */
+describe('dirty 判定的安全边界', () => {
+  it('an already-indexed message never re-enters settle() on a later pass', async () => {
+    const h = createHarness({ resolveAccountId: () => ACCOUNT, ocrMs: 1 })
+    const recognize = vi.fn(async () => ({ success: true, text: '识别出来的文字', language: null }))
+    h.service.bind({ recognize })
+
+    await runPass(h.service)
+    const firstCalls = recognize.mock.calls.length
+    expect(firstCalls).toBeGreaterThan(0)
+
+    // 带时间窗 ⇒ 绕过 checkpoint 跳过，逼它逐张检查（否则整个会话被 skip，测不到这条规则）。
+    await runPass(h.service, { sinceMs: 1 })
+
+    /**
+     * 关键断言：第二遍**一次 OCR 都不该发生**。
+     * 只要 binding 是 `indexed`（终态）就会被 `fill()` 短路 —— 短路即不 settle，
+     * 也就不可能把"有文字"改写成"没有文字"。
+     */
+    expect(recognize.mock.calls.length).toBe(firstCalls)
+
+    h.service.resetAccount()
+  })
+
+  it('resetRetriableFailures leaves searchable results untouched', async () => {
+    const h = createHarness({ resolveAccountId: () => ACCOUNT, ocrMs: 1 })
+    await runPass(h.service)
+
+    const before = (await h.service.getStatus()).coverage
+    // 本用例识别出的全是"有文字"，所以 indexed === 全部绑定。
+    expect(before.indexed).toBe(IMAGES)
+    expect(before.failed).toBe(0)
+
+    /**
+     * 走生产路径复位失败记录（「修复图片搜索索引」用的就是它）。
+     * 它按**可重试失败状态**删除；`indexed` 不在那个集合里 ⇒ 一条都不会被删。
+     * 只要 binding 还在且是终态，那条消息就永远不会重新进 `settle()`。
+     */
+    const reset = await h.service.resetRetriableFailures()
+    expect(reset.reset).toBe(0)
+
+    const after = (await h.service.getStatus()).coverage
+    expect(after.indexed).toBe(IMAGES)
+    expect(after.processed).toBe(before.processed)
+
+    h.service.resetAccount()
+  })
+})
@@ -1,5 +1,5 @@
 /**
- * §2：图片 OCR 来源语义的 **deterministic synthetic E2E**。
+ * 图片 OCR 来源语义的 **deterministic synthetic E2E**。
 *
 * 硬要求是"不依赖真实线上 AI 模型也能 PASS"，所以这里把两个外部边界**确定性**地固定住：
 * - WCDB（chat-service）→ 用合成联系人 / 合成消息；
@@ -124,7 +124,7 @@ function makeKnowledge() {

 const NOW = new Date('2026-09-16T09:00:00+08:00')

-describe('§2 图片文字索引 synthetic E2E（确定性，不依赖真模型）', () => {
+describe('图片文字索引 synthetic E2E（确定性，不依赖真模型）', () => {
  let knowledge: ReturnType<typeof makeKnowledge>
  let service: LocalQueryApiService

@@ -244,7 +244,7 @@ describe('§2 图片文字索引 synthetic E2E（确定性，不依赖真模型
  })
 })

-describe('§3 partial coverage honesty（确定性，不依赖真模型）', () => {
+describe('partial coverage honesty（确定性，不依赖真模型）', () => {
  const NOT_INDEXED_KEYWORD = 'TRACE_NOT_YET_INDEXED_IMAGE'

  function partialImageCoverage() {
@@ -0,0 +1,131 @@
+// 【macOS】System OCR native fidelity。
+//
+// capability-gated 的原生冒烟测试：只有在「macOS + native 运行时可用」时才真正跑。
+// macOS 的 Apple Vision 后端没有"语言包缺失"这一失败模式，所以门槛只有运行时本身；
+// mock 单元测试仍然是 mandatory（tests/unit/system-ocr-service.test.ts）。
+//
+// 这里断言的是 **macOS 专有**的性质，与 system-ocr-windows.test.ts 刻意不同：
+//   - 引擎标识是 macos-system-ocr；
+//   - 不做任何图片归一化：Vision 原生接受 PNG / JPEG，不得转码、不得起 ffmpeg；
+//   - capability.language 恒为 null（识别语言由 Vision 决定）；
+//   - line.confidence 是 Vision 的真实置信度，不像 Windows 恒为 1.0。
+//
+// fixture 全部是 synthetic 图片（tests/fixtures/ocr/*），不含任何真实聊天数据。
+
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+import { SYSTEM_OCR_ENGINE_MACOS } from '../../src/shared/system-ocr'
+
+vi.mock('../../src/main/image-decrypt-service', () => ({
+  resolveFfmpegExecutable: (): string => 'ffmpeg'
+}))
+
+import { SystemOcrService, systemOcrService } from '../../src/main/services/system-ocr-service'
+
+const fixtureDirectory = join(__dirname, '..', 'fixtures', 'ocr')
+
+const toDataUrl = (fileName: string, mimeType: string): string =>
+  `data:${mimeType};base64,${readFileSync(join(fixtureDirectory, fileName)).toString('base64')}`
+
+/** 只比较"主要 token"，避免识别微差造成脆弱测试。 */
+const expectContainsTokens = (text: string, tokens: string[]): void => {
+  const normalized = text.replace(/[\s\u3000]+/g, '').toLowerCase()
+  for (const token of tokens) {
+    expect(normalized).toContain(token.replace(/[\s\u3000]+/g, '').toLowerCase())
+  }
+}
+
+const capability = await systemOcrService.getCapability()
+const onMac = process.platform === 'darwin'
+const platformGate = onMac ? it : it.skip
+const nativeGate = onMac && capability.available ? it : it.skip
+
+/**
+ * 走「真实 process.platform/arch + 真实 native binding + 默认归一化路径」的实例，
+ * 只把 ffmpeg 解析器换成 spy —— 用来证明 macOS 路径根本没有碰归一化。
+ */
+const ffmpegResolver = vi.fn(() => 'ffmpeg')
+const nativeService = new SystemOcrService({ resolveFfmpegExecutable: ffmpegResolver })
+
+describe('macOS System OCR native fidelity', () => {
+  platformGate('reports a usable capability backed by Apple Vision', () => {
+    expect(capability.engine).toBe(SYSTEM_OCR_ENGINE_MACOS)
+    expect(capability.platform).toBe('darwin')
+    expect(capability.runtimeVersion).not.toBeNull()
+    // Vision 自行决定识别语言，不声称任何语言包。
+    expect(capability.language).toBeNull()
+    if (!capability.available) {
+      console.warn(`[integration] macOS System OCR smoke skipped: ${capability.message}`)
+    }
+  })
+
+  nativeGate('recognizes simplified Chinese text', async () => {
+    const result = await nativeService.recognize({
+      imageDataUrl: toDataUrl('system-ocr-zh.png', 'image/png')
+    })
+    expect(result.success).toBe(true)
+    expectContainsTokens(result.text, ['TraceMemo', '本地', '文字', '识别'])
+    expect(result.language).toBeNull()
+    expect(result.durationMs).toBeGreaterThan(0)
+  })
+
+  nativeGate('recognizes English text', async () => {
+    const result = await nativeService.recognize({
+      imageDataUrl: toDataUrl('system-ocr-en.png', 'image/png')
+    })
+    expect(result.success).toBe(true)
+    expectContainsTokens(result.text, ['TraceMemo', 'System', 'OCR'])
+  })
+
+  nativeGate('recognizes mixed Chinese/English text', async () => {
+    const result = await nativeService.recognize({
+      imageDataUrl: toDataUrl('system-ocr-mixed.png', 'image/png')
+    })
+    expect(result.success).toBe(true)
+    expectContainsTokens(result.text, ['TraceMemo', '本地', 'OCR', '2026'])
+  })
+
+  /**
+   * Vision 原生接受 JPEG —— 这条用例同时是「macOS 不做归一化」的回归保护：
+   * 一旦有人把 Windows 的 PNG-only 假设搬过来，ffmpeg 解析器就会被调用。
+   */
+  nativeGate('accepts JPEG directly without any image normalization', async () => {
+    ffmpegResolver.mockClear()
+    const result = await nativeService.recognize({
+      imageDataUrl: toDataUrl('system-ocr-mixed.jpg', 'image/jpeg')
+    })
+    expect(result.success).toBe(true)
+    expectContainsTokens(result.text, ['TraceMemo', 'OCR', '2026'])
+    expect(ffmpegResolver).not.toHaveBeenCalled()
+  })
+
+  nativeGate('reports real Vision confidence and top-left-origin boxes', async () => {
+    const result = await nativeService.recognize({
+      imageDataUrl: toDataUrl('system-ocr-mixed.png', 'image/png')
+    })
+    expect(result.success).toBe(true)
+    expect(result.lines.length).toBeGreaterThan(0)
+    for (const line of result.lines) {
+      // Windows 恒为 1.0；macOS 必须给出真实置信度。
+      expect(line.confidence).toBeGreaterThanOrEqual(0)
+      expect(line.confidence).toBeLessThanOrEqual(1)
+      const { x, y, width, height } = line.boundingBox
+      for (const value of [x, y, width, height]) {
+        expect(Number.isFinite(value)).toBe(true)
+      }
+      expect(x).toBeGreaterThanOrEqual(0)
+      expect(y).toBeGreaterThanOrEqual(0)
+      expect(x + width).toBeLessThanOrEqual(1.0001)
+      expect(y + height).toBeLessThanOrEqual(1.0001)
+    }
+  })
+
+  nativeGate('caches an identical repeat request', async () => {
+    const request = { imageDataUrl: toDataUrl('system-ocr-en.png', 'image/png') }
+    const first = await systemOcrService.recognize(request)
+    const second = await systemOcrService.recognize(request)
+    expect(first.success).toBe(true)
+    expect(second.fromCache).toBe(true)
+  })
+})
@@ -1,17 +1,21 @@
-// Windows System OCR native fidelity。
+// 【Windows】System OCR native fidelity。
 //
 // 这是 capability-gated 的原生冒烟测试：
-//   - 只有在「当前平台支持 + native 运行时可用 + 有可用 OCR 语言包」时才真正跑；
+//   - 只有在「Windows + native 运行时可用 + 有可用 OCR 语言包」时才真正跑；
 //   - CI 环境无法保证 Windows OCR 语言包，所以中文识别不作为所有 CI 的硬门槛
 //     （mock 单元测试才是 mandatory，见 tests/unit/system-ocr-service.test.ts）；
 //   - 在 Windows 真机上必须实际通过。
 //
+// 这个文件断言的是 **Windows 专有**的性质：Windows 引擎标识、以及「引擎只吃 PNG，
+// JPEG 必须走本服务归一化」这条约束。macOS 的对应测试见 system-ocr-macos.test.ts
+// （macOS 不做归一化，不要把这个文件里的约束套到 macOS 上）。
+//
 // fixture 全部是 synthetic 图片（tests/fixtures/ocr/*），不含任何真实聊天数据。

 import { readFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { describe, expect, it, vi } from 'vitest'
-import { SYSTEM_OCR_ENGINE } from '../../src/shared/system-ocr'
+import { SYSTEM_OCR_ENGINE_WINDOWS } from '../../src/shared/system-ocr'

 vi.mock('../../src/main/image-decrypt-service', () => ({
  resolveFfmpegExecutable: (): string => 'ffmpeg'
@@ -33,11 +37,13 @@ const expectContainsTokens = (text: string, tokens: string[]): void => {
 }

 const capability = await systemOcrService.getCapability()
-const nativeGate = capability.available ? it : it.skip
+const onWindows = process.platform === 'win32'
+const platformGate = onWindows ? it : it.skip
+const nativeGate = onWindows && capability.available ? it : it.skip

 describe('Windows System OCR native fidelity', () => {
-  it('reports a usable capability on this machine', () => {
-    expect(capability.engine).toBe(SYSTEM_OCR_ENGINE)
+  platformGate('reports a usable capability on this machine', () => {
+    expect(capability.engine).toBe(SYSTEM_OCR_ENGINE_WINDOWS)
    if (!capability.available) {
      console.warn(`[integration] System OCR native smoke skipped: ${capability.message}`)
    }