weflow-cli 1.6.3 → 1.7.0

package/CHANGELOG.md

@@ -4,6 +4,44 @@ The npm package is published separately from GitHub. It may lag behind the `mast
 
 All notable user-facing changes are recorded here. This project follows [Semantic Versioning](https://semver.org/).
 
+## 1.7.0
+
+### Added
+
+- `sync run|status|verify`: a local message-sync checkpoint. `sync run` reads a time window, deduplicates against the previous checkpoint and records what it covered; `sync status` reports coverage without touching the database, so it still works while the database is locked. It does **not** advertise a stable cursor - overlapping windows plus local deduplication is what it offers, per D-027.
+- Per-shard read reporting. Shard open and read failures used to be swallowed by a bare `except: continue`, so "read 31 messages" and "read one shard and silently skipped three" were indistinguishable from the outside. `--report-shards` (opt-in; without it the JSON is byte-identical) surfaces `scanned/opened/failed` and one entry per shard. On the machine this was developed against the report reads `message_0.db` 31 rows and `message_3.db` 1258 - exactly the shape of the shard-read bug fixed in 1.6.4, which was completely invisible at the time.
+- A media coverage report on HTML export: `<prefix>_media.json` beside the parts, with a status and a reason for every media item (`embedded | cached | remote-fetched | missing | unsupported`). The exporter had been computing `COVER_STATE` counters and discarding them, and a media miss showed up only as a bare `[图片]` with no reason recorded. A real 120-message export reports 54 items: 35 embedded, 15 missing, 2 unsupported, 2 remote-fetched, with reasons `not-in-local-cache` and `voice-not-in-media-index`.
+- `docs/SYNC_CONTRACT.md` freezing the `weflow-sync/v1` and `weflow-job/v1` state schemas, and `D-029` recording the additive-only boundary, why the identity omits `shard`, and why `sync retry` is deliberately not implemented.
+
+### Changed
+
+- The HTML exporter now tries the conversation cache before the network when resolving an article thumbnail; it had been downloading covers it already had on disk.
+- `collectMessagesInRangeDetailed` distinguishes why paging stopped. The original loop ended on a short page exactly as it ended on an exhausted conversation, so a short page caused by offset shifting on a live database looked identical to having reached the end. The original function is unchanged; the variant is used by the new sync path and available to the export path next.
+
+### Fixed
+
+- A leaked database handle when a shard opened but its key was rejected: the connection was left open, which on Windows keeps the file locked.
+
+## 1.6.4
+
+### Fixed
+
+- Restored four pieces of matching logic in the HTML exporter that the `90b165a` clone-consolidation merge had silently dropped, all of which lowered media coverage without failing loudly:
+  - the `unique:<local_id>` fallback, which matches an image when that id resolves to exactly one distinct picture in the conversation (content-deduped, so the shard-collision risk that rules out a bare `local_id` does not apply);
+  - `is_encoded_media_type`, needed because WeChat stores some forwards as high-bit variants of type 49 — the mask turns those into a plain 49, which is a registered type, so the branch guarding them had become unreachable;
+  - the guard that keeps a type-49 row carrying a title or url on the link-card path instead of hiding it behind a cached thumbnail;
+  - the cache-first lookup in the article branch, which had been downloading covers it already had on disk.
+- Seeded `COVER_STATE`'s budgets with their limits instead of 0. They were only ever set by `main()`, so any caller reaching the fetchers another way silently skipped every remote fetch and got `None` back with no error.
+- `pipeline_security_test` no longer reads the developer's real `~/.weflow-cli/config.json`; it points `CONFIG_PATH` at an empty temp file. The test only passed on a machine that happened to have a config, and reading a real config from a unit test is exactly what the repo rules forbid.
+- CI actually runs, for the first time. `npm test` passed locally and failed on every push: the script used `test/**/*.test.ts`, which Git Bash expands locally but CI's bash does not (globstar is off by default), so Node received the literal pattern and reported `Could not find ...`. The glob is now quoted so Node expands it. The single combined job was also split into `node` / `python` / `release-consistency`, because a Node failure previously stopped the Python tests from running at all — they had been failing unnoticed.
+- Raised the Node floor to 22.13.0. `src/core/sqlcipherCore.ts` imports `node:sqlite` at module scope; that builtin arrives in 22.5.0 and stops needing `--experimental-sqlite` at 22.13.0, so on Node 18/20 every command died at load while `engines` still claimed `>=18`. Both are past end-of-life, so the floor moved rather than adding a lazy-load path for dead runtimes.
+- Rebuilt `package-lock.json`, which still said 1.6.1 and still listed `lz4` as an ordinary dependency after the 1.6.3 change moved it to optional. `npm audit fix` then took production vulnerabilities from 17 to 6; the remainder (`@xmldom/xmldom`, `exceljs`, `@wenyan-md/core`, `mermaid`, `speech-rule-engine`, `uuid`) have no non-breaking fix — `exceljs@4.4.0` and `@wenyan-md/core@3.0.11` are already the newest releases and the advisories' suggested "fix" is to downgrade them.
+
+### Added
+
+- `docs/PROJECT_STATE.md` no longer carries a hardcoded version — it points at `package.json`, which is what drifted to `1.5.1`. Example version numbers in `docs/NPM-PUBLISH.md` and `docs/HEALTH-CHECK.md` became placeholders for the same reason.
+- Git tags and GitHub Releases for `1.6.0`, `1.6.1` and `1.6.3`, so npm versions map to commits. `1.6.2` has neither: it was published, but its version bump was never committed.
+
 ## 1.6.3
 
 ### Fixed

package/OPERATIONS.md

@@ -6,7 +6,7 @@
 
 | 依赖 | 用途 | 检查 |
 | --- | --- | --- |
-| Node.js 18+ | CLI、MCP、构建 | `node --version` |
+| Node.js 22.13+ | CLI、MCP、构建 | `node --version` |
 | Python 3.10+ | NT 数据、日报、阅读器 | `python --version` |
 | `requirements.txt` | 标准 4.x 工作流 | `python -m pip install -r requirements.txt` |
 | `requirements-3x.txt` | 旧版 3.x 数据，可选 | `python -m pip install -r requirements-3x.txt` |
@@ -103,6 +103,41 @@ HTML 导出的时间几乎全部花在远程媒体上（公众号封面、B 站
 - 图片显示为 `[图片]` 且无图：该图片从未在这台设备上下载过。
 - `[位置]` 只有地名、没有地图：位置消息本身不携带地图图片。
 
+每次 HTML 导出还会在输出目录里写一份 **`<会话名>_media.json`**，逐项记录每个媒体的状态与原因，不用再靠肉眼比对：
+
+| status | 含义 |
+| --- | --- |
+| `embedded` | 已内嵌进页面，`mediaKey` 说明按哪个键命中 |
+| `cached` | 用了本地缓存 |
+| `remote-fetched` | 从网络取回的（封面/链接图） |
+| `missing` | 没有可用媒体，`reason` 说明为什么 |
+| `unsupported` | 该类型暂不支持（如语音不在媒体索引里） |
+
+`missing` 的常见 reason：`not-in-local-cache`（本机没有）、`no-reliable-identity`（这条消息没有可靠身份可匹配——按 D-014 宁缺毋滥，不会拿相邻消息或裸 localId 去猜）、`budget-exhausted`（本次远程抓取配额用完）、`download-failed`（链接失效）。
+
+### 同步检查点与覆盖范围
+
+`sync` 用重叠时间窗增量读取，并在本机记下覆盖到哪：
+
+```powershell
+weflow-cli sync run <会话> --since 2026-09-01   # 首次需要 --since 或 --full
+weflow-cli sync run <会话>                      # 之后从上次检查点继续
+weflow-cli sync status                          # 不访问数据库，数据库被占用时也能看
+weflow-cli sync verify <会话>                   # 重读记录范围并与当前数据比对
+```
+
+每次运行都给出 `coverage`：
+
+| coverage | 含义 |
+| --- | --- |
+| `complete` | 扫到的分片全部打开、打开的都读成功 |
+| `unverified` | 有分片**打不开**——读到的部分可信，但那几个分片里有没有本会话消息**无法判断** |
+| `partial` | 已打开的分片读失败、或还有更多未读。**不算成功**，退出码 1，且不推进"上次成功时间" |
+
+看到 `unverified` 时，`sync status` 的 `warnings` 会点名是哪个分片。这通常意味着该分片的密钥没解开——先排查 `init` 是否覆盖了全部分片。
+
+**没有"稳定游标"**：`sync` 提供的是重叠窗口 + 本地去重，不是可直接续传的游标（D-027 要求所有后端都支持后才能宣称）。边界消息被重复读取是**预期行为**，会被去重吸收。
+
 ### 语音消息转文字
 
 HTML 里放不出语音：微信语音是 **SILK v3** 格式，浏览器不支持，ffmpeg 也没有 SILK 解码器（只有 AMR）。所以语音转文字是让语音消息在导出里能携带信息的唯一办法。

package/README.en.md

@@ -78,7 +78,7 @@ weflow-cli mcp-config                  # one-shot MCP client integration
 
 ### 1. Install and Check
 
-Requires Node.js 18+, Python 3.10+, and a signed-in Windows WeChat. After installation, check your environment first:
+Requires Node.js 22.13+, Python 3.10+, and a signed-in Windows WeChat. After installation, check your environment first:
 
 ```powershell
 npm install -g weflow-cli

package/README.md

@@ -108,7 +108,7 @@ Linux 的自动初始化能力取决于微信发行版、Python 依赖和当前
 
 > npm 包与 GitHub 发布分开进行；需要最新修复时，请先确认 npm 包版本，或直接使用 GitHub `master` 分支代码。
 
-需要 Node.js 18+、Python 3.10+，以及已登录的 Windows 微信。安装后先检查本机环境：
+需要 Node.js 22.13+、Python 3.10+，以及已登录的 Windows 微信。安装后先检查本机环境：
 
 ```powershell
 npm install -g weflow-cli

package/bin/weflow-cli.ts

@@ -5,6 +5,8 @@ import inquirer from 'inquirer'
 import { basename, join } from 'path'
 import { existsSync, readFileSync, statSync, writeFileSync } from 'fs'
 import { homedir } from 'os'
+import { SYNC_SCHEMA, SYNC_SOURCE, syncStateStore } from '../src/services/syncState.js'
+import { SyncRangeRequiredError, runSync } from '../src/services/syncService.js'
 import { dbPathService } from '../src/core/dbPathService.js'
 import { keyService } from '../src/core/keyService.js'
 import { NtCore } from '../src/core/ntCore.js'
@@ -327,6 +329,26 @@ program
           previewExposesPaths: false,
         },
         evidencePackage: { cli: 'evidence <talker> --json --non-interactive', localOnly: true },
+        sync: {
+          preview: 'sync run <talker> --dry-run --json',
+          execute: 'sync run <talker> --yes --json',
+          status: 'sync status [<talker>] --json',
+          verify: 'sync verify <talker> --json',
+          confirmationRequired: true,
+          readsLocalData: true,
+          invokesAI: false,
+          sideEffects: ['local-checkpoint-file'],
+          stateSchema: 'weflow-sync/v1',
+          jobSchema: 'weflow-job/v1',
+          stateLocation: 'local-user-config-dir',
+          previewResolvesTalker: false,
+          previewExposesLocalPaths: false,
+          // D-027: a stable cursor must be backed by every database backend
+          // before it is advertised. This exposes overlapping windows only.
+          stableCursor: false,
+          coverageValues: ['complete', 'unverified', 'partial'],
+          partialCompletesSuccessfully: false,
+        },
         aiAnalysis: {
           preview: 'evidence-review <talker> --dry-run --json',
           execute: 'evidence-review <talker> --yes --json',
@@ -1237,6 +1259,296 @@ program
     }
   })
 
+// ==================== sync ====================
+// 增量同步检查点。契约见 docs/SYNC_CONTRACT.md, 边界见 D-029。
+// 不宣称「稳定游标」: D-027 要求它在所有后端支持前不得对外宣称,
+// 这里只做重叠时间窗 + 本地去重。
+const syncCmd = program.command('sync').description('本地消息同步检查点（重叠窗口读取与覆盖报告）')
+
+syncCmd
+  .command('run <talker>')
+  .description('执行一次同步并写入检查点')
+  .option('--since <date>', '起始日期或 ISO 时间（首次运行需要）')
+  .option('--full', '读取全部历史（首次运行需要；耗时可能较长）')
+  .option('--overlap <seconds>', '重叠窗口秒数', '300')
+  .option('-n, --limit <number>', '本次最多读取条数（0=不限）', '0')
+  .option('--dry-run', '仅预览，不读取消息、不写状态')
+  .option('--yes', '确认执行')
+  .option('--json', '输出机器可读结果')
+  .option('--non-interactive', '禁止交互确认')
+  .action(async (talker: string, opts) => {
+    const overlap = parseCliInteger(opts.overlap, 'overlap', 0, 86400, !!opts.json)
+    const limit = parseCliInteger(opts.limit, 'limit', 0, 1_000_000, !!opts.json)
+
+    let since: number | undefined
+    if (opts.since) {
+      try {
+        since = parseLocalDateOrIso(opts.since)
+      } catch (error) {
+        const message = error instanceof DateRangeError ? error.message : '日期格式无效'
+        if (opts.json) { console.log(JSON.stringify({ success: false, code: 'INVALID_DATE', error: message })); process.exit(1) }
+        console.error(chalk.red(`✗ ${message}`))
+        process.exit(1)
+      }
+    }
+    if (opts.full && since !== undefined) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'INVALID_ARGUMENT', error: '--since 与 --full 不能同时使用' })); process.exit(1) }
+      console.error(chalk.red('✗ --since 与 --full 不能同时使用'))
+      process.exit(1)
+    }
+
+    // Preview deliberately does not resolve the talker: that reads the
+    // database, and a preview must not touch local data (D-025).
+    const prior = (() => {
+      try { return syncStateStore.read(SYNC_SOURCE, talker) } catch { return null }
+    })()
+    const preview = {
+      success: true,
+      dryRun: true,
+      action: 'sync.run',
+      schema: SYNC_SCHEMA,
+      source: SYNC_SOURCE,
+      talkerResolved: false,
+      hasCheckpoint: !!prior,
+      window: {
+        from: since ?? prior?.checkpoint.newestCreateTime ?? null,
+        overlapSeconds: overlap,
+        full: !!opts.full,
+      },
+      estimatedRecords: prior?.recordsRead ?? null,
+      readsLocalChat: true,
+      writesLocalState: true,
+      stableCursor: false,
+    }
+
+    if (opts.dryRun) {
+      if (opts.json) console.log(JSON.stringify(preview))
+      else {
+        console.log(chalk.cyan('\n同步预览'))
+        console.log(chalk.gray(`  范围: ${opts.full ? '全部历史' : since ? new Date(since * 1000).toLocaleString() : '上次检查点'}`))
+        console.log(chalk.gray(`  重叠窗口: ${overlap} 秒`))
+        console.log(chalk.gray('  将读取本地聊天记录并写入同步检查点，不调用 AI。\n'))
+      }
+      return
+    }
+
+    if (!opts.yes) {
+      if (opts.json) {
+        console.log(JSON.stringify({ ...preview, success: false, dryRun: false, code: 'CONFIRMATION_REQUIRED' }))
+        process.exit(1)
+      }
+      if (opts.nonInteractive) {
+        console.error(chalk.red('✗ 非交互模式需要 --yes'))
+        process.exit(1)
+      }
+      const { confirmed } = await inquirer.prompt([{
+        type: 'confirm',
+        name: 'confirmed',
+        message: opts.full
+          ? '将读取该会话的全部历史消息，可能耗时数分钟。继续吗？'
+          : '将读取指定范围内的消息并写入本地同步检查点。继续吗？',
+        default: false,
+      }])
+      if (!confirmed) {
+        console.log(chalk.gray('已取消'))
+        return
+      }
+    }
+
+    if (!configService.isConfigured()) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'NOT_INITIALIZED', error: '未完成初始化' })); process.exit(1) }
+      console.error(chalk.red('✗ 未完成初始化，请先运行 weflow-cli init'))
+      process.exit(1)
+    }
+
+    let resolvedTalker = ''
+    try {
+      resolvedTalker = await resolveTalkerCore(talker, { interactive: !opts.nonInteractive })
+    } catch {
+      resolvedTalker = ''
+    }
+    if (!resolvedTalker) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'INVALID_ARGUMENT', error: '未找到该会话' })); process.exit(1) }
+      console.error(chalk.red('✗ 未找到该会话'))
+      process.exit(1)
+    }
+    // A display name is nicety only; the state is keyed by the resolved id.
+    let displayName = resolvedTalker
+    try {
+      const match = (await chatService.listSessions()).find(s => s.username === resolvedTalker)
+      if (match?.displayName && match.displayName !== resolvedTalker) displayName = match.displayName
+    } catch { /* keep the id */ }
+
+    try {
+      const result = await runSync(resolvedTalker, {
+        since, full: !!opts.full, overlapSeconds: overlap, limit,
+        scope: displayName,
+        read: (who, howMany) => chatService.getMessagesWithShards(who, howMany, 0),
+      })
+      if (opts.json) {
+        console.log(JSON.stringify({
+          success: result.success,
+          ...(result.code ? { code: result.code } : {}),
+          action: result.action,
+          schema: SYNC_SCHEMA,
+          source: SYNC_SOURCE,
+          scope: result.scope,
+          talker: resolvedTalker,
+          window: result.window,
+          recordsRead: result.recordsRead,
+          recordsDeduplicated: result.recordsDeduplicated,
+          recordsReturned: result.recordsReturned,
+          shards: result.shards,
+          coverage: result.coverage,
+          mayHaveMore: result.mayHaveMore,
+          partial: result.partial,
+          warnings: result.warnings,
+          jobId: result.jobId,
+        }))
+        if (!result.success) process.exit(1)
+        return
+      }
+      const mark = result.coverage === 'complete' ? '✓' : result.coverage === 'unverified' ? '!' : '✗'
+      console.log(chalk.green(`\n${mark} 同步完成: ${result.recordsReturned}/${result.recordsRead} 条（去重 ${result.recordsDeduplicated}）`))
+      console.log(chalk.gray(`  覆盖: ${result.coverage}  ·  分片: ${result.shards?.opened ?? '?'} 读 / ${result.shards?.failed ?? 0} 失败`))
+      for (const warning of result.warnings) console.log(chalk.yellow(`  ⚠ ${warning}`))
+      if (result.partial) {
+        console.log(chalk.yellow('  本次为部分完成，未推进成功时间；用 sync status 查看详情。'))
+      }
+      console.log('')
+      if (!result.success) process.exit(1)
+    } catch (error: any) {
+      if (error instanceof SyncRangeRequiredError) {
+        if (opts.json) { console.log(JSON.stringify({ success: false, code: 'SYNC_RANGE_REQUIRED', error: error.message })); process.exit(1) }
+        console.error(chalk.red(`✗ ${error.message}`))
+        process.exit(1)
+      }
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'SYNC_FAILED', error: '同步失败' })); process.exit(1) }
+      console.error(chalk.red(`✗ 同步失败: ${error?.message || error}`))
+      process.exit(1)
+    }
+  })
+
+syncCmd
+  .command('status [talker]')
+  .description('查看同步检查点与最近任务')
+  .option('--json', '输出 JSON 格式')
+  .action(async (talker: string | undefined, opts) => {
+    // No database access: this has to work while the database is locked.
+    let states: any[] = []
+    try { states = syncStateStore.list() } catch { states = [] }
+    const lastJob = syncStateStore.recentJobs(1)[0] ?? null
+
+    if (talker) {
+      const match = states.find(s => s.talker === talker || s.scope === talker)
+      if (!match) {
+        if (opts.json) { console.log(JSON.stringify({ success: false, code: 'SYNC_STATE_NOT_FOUND', error: '没有该会话的同步记录' })); process.exit(1) }
+        console.error(chalk.red('✗ 没有该会话的同步记录'))
+        process.exit(1)
+      }
+      if (opts.json) { console.log(JSON.stringify({ success: true, schema: SYNC_SCHEMA, state: match, lastJob })); return }
+      console.log(chalk.cyan(`\n同步记录 — ${match.scope}`))
+      console.log(chalk.gray(`  覆盖: ${match.coveredFrom || '—'} ~ ${match.coveredTo || '—'}`))
+      console.log(chalk.gray(`  可信度: ${match.coverage}  ·  分片 ${match.shardsRead} 读 / ${match.shardsFailed} 失败`))
+      console.log(chalk.gray(`  上次成功: ${match.lastSuccessfulRun || '—'}  ·  上次尝试: ${match.lastAttempt || '—'}\n`))
+      return
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify({
+        success: true,
+        schema: SYNC_SCHEMA,
+        stableCursor: false,
+        scopes: states.map(s => ({
+          source: s.source, scope: s.scope, talker: s.talker,
+          lastSuccessfulRun: s.lastSuccessfulRun, lastAttempt: s.lastAttempt,
+          coveredFrom: s.coveredFrom, coveredTo: s.coveredTo,
+          recordsRead: s.recordsRead, recordsDeduplicated: s.recordsDeduplicated,
+          coverage: s.coverage, shardsRead: s.shardsRead, shardsFailed: s.shardsFailed,
+          mayHaveMore: s.mayHaveMore, warnings: s.warnings,
+        })),
+        lastJob,
+      }))
+      return
+    }
+    if (!states.length) {
+      console.log(chalk.gray('\n还没有任何同步记录。首次运行: weflow-cli sync run <会话> --since <日期>\n'))
+      return
+    }
+    console.log(chalk.cyan(`\n同步记录 (${states.length} 个会话):\n`))
+    for (const s of states) {
+      const mark = s.coverage === 'complete' ? '✓' : s.coverage === 'unverified' ? '!' : '✗'
+      console.log(`  ${mark} ${s.scope}  ${chalk.gray(`${s.coveredFrom || '—'} ~ ${s.coveredTo || '—'}  分片 ${s.shardsRead}/${s.shardsFailed} 失败`)}`)
+    }
+    console.log('')
+  })
+
+syncCmd
+  .command('verify <talker>')
+  .description('核对检查点与当前数据的边界')
+  .option('--json', '输出 JSON 格式')
+  .action(async (talker: string, opts) => {
+    // Read-only: it writes nothing, so it needs no confirmation - the same
+    // posture as `messages`.
+    if (!configService.isConfigured()) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'NOT_INITIALIZED', error: '未完成初始化' })); process.exit(1) }
+      console.error(chalk.red('✗ 未完成初始化'))
+      process.exit(1)
+    }
+    let state: any = null
+    try { state = syncStateStore.read(SYNC_SOURCE, talker) } catch { state = null }
+    if (!state) state = syncStateStore.list().find(s => s.scope === talker) ?? null
+    if (!state) {
+      if (opts.json) { console.log(JSON.stringify({ success: false, code: 'SYNC_STATE_NOT_FOUND', error: '没有该会话的同步记录' })); process.exit(1) }
+      console.error(chalk.red('✗ 没有该会话的同步记录'))
+      process.exit(1)
+    }
+
+    const checks: Array<Record<string, unknown>> = [{ name: 'checkpoint-present', ok: true }]
+
+    // Re-read and compare. This is the count summary of §4.4 in the absence
+    // of a local index.
+    const read = await chatService.getMessagesWithShards(state.talker, 0, 0)
+    const fromSeconds = state.coveredFrom ? Math.floor(Date.parse(state.coveredFrom) / 1000) : null
+    const inWindow = fromSeconds === null
+      ? read.messages
+      : read.messages.filter(m => Number(m.createTime) >= fromSeconds)
+    checks.push({ name: 'window-re-readable', ok: inWindow.length > 0, returned: inWindow.length })
+
+    const newest = read.messages.length
+      ? Math.max(...read.messages.map(m => Number(m.createTime) || 0))
+      : null
+    checks.push({
+      name: 'newest-message-present',
+      ok: newest !== null && newest >= (state.checkpoint?.newestCreateTime ?? 0),
+      recorded: state.checkpoint?.newestCreateTime ?? null,
+      observed: newest,
+    })
+
+    if (read.shards) {
+      checks.push({ name: 'shards-readable', ok: read.shards.failed === 0,
+                    scanned: read.shards.scanned, failed: read.shards.failed })
+    } else {
+      // Neither a pass nor a failure: this backend simply cannot say.
+      checks.push({ name: 'shards-readable', ok: true, skipped: true,
+                    reason: 'backend-does-not-report-shards' })
+    }
+
+    const success = checks.every(c => c.ok || c.skipped)
+    if (opts.json) {
+      console.log(JSON.stringify({ success, schema: SYNC_SCHEMA, scope: state.scope, coverage: state.coverage, checks }))
+      if (!success) process.exit(1)
+      return
+    }
+    console.log(chalk.cyan(`\n核对 — ${state.scope}\n`))
+    for (const check of checks) {
+      const mark = check.skipped ? '–' : check.ok ? '✓' : '✗'
+      console.log(`  ${mark} ${check.name}${check.skipped ? chalk.gray(` (跳过: ${check.reason})`) : ''}`)
+    }
+    console.log('')
+    if (!success) process.exit(1)
+  })
+
 // ==================== contacts ====================
 program
   .command('contacts')