weflow-cli 1.6.3 → 1.7.0

package/docs/SYNC_CONTRACT.md

@@ -0,0 +1,152 @@
+# 同步与任务状态契约
+
+本文冻结两个内部状态 schema：`weflow-sync/v1`（跨运行的同步检查点）与 `weflow-job/v1`
+（单次运行的记录）。二者都在本机 `~/.weflow-cli/` 下，**不对外暴露**。
+
+它们是 [FUNCTIONAL-IMPROVEMENT-SPEC.md](FUNCTIONAL-IMPROVEMENT-SPEC.md) §4 与 §5 的落地，
+边界受 [DECISIONS.md](DECISIONS.md) 约束（尤其 D-014、D-019、D-025、D-027）。
+
+## 为什么是两个文件
+
+生命周期不同，不是猜测性抽象：
+
+| 文件 | 生命周期 | 记录的是 |
+| --- | --- | --- |
+| `sync/<source>-<name>-<hash>.json` | **跨运行**，每次同步覆盖 | 已覆盖到哪、分片读没读全 |
+| `jobs/<jobId>.json` | **单次运行** | 这次运行的起止、状态、结果 |
+
+一次运行写一个 job 记录；同步检查点记录"到目前为止覆盖范围"这一长期事实。
+
+## `weflow-sync/v1`
+
+路径：`~/.weflow-cli/sync/<source>-<sanitize(talker)>-<sha256(talker)[0:8]>.json`
+
+**按会话分文件**，不是一个全局文件。理由：全局文件要求跨会话读改写并合并，而分文件
+让每次写入都是整文件原子替换；同时文件名里的 hash 后缀让 `wxid_a@chatroom` 与
+`wxid_a_chatroom` 落到不同文件，而显示名不会出现在目录列表里。
+
+```json
+{
+  "schema": "weflow-sync/v1",
+  "schemaVersion": 1,
+  "source": "wechat-nt",
+  "scope": "<显示名，未知时等于 talker>",
+  "talker": "<会话标识，不是路径>",
+  "lastSuccessfulRun": "2026-09-19T09:00:00+08:00",
+  "lastAttempt": "2026-09-19T09:02:10+08:00",
+  "coveredFrom": "2026-09-01T00:00:00+08:00",
+  "coveredTo": "2026-09-19T08:59:59+08:00",
+  "checkpoint": { "newestCreateTime": 1789000000, "overlapSeconds": 300 },
+  "recordsRead": 1200,
+  "recordsDeduplicated": 14,
+  "recordsReturned": 1186,
+  "shardsRead": 4,
+  "shardsFailed": 0,
+  "shards": {
+    "scanned": 4, "opened": 4, "failed": 0,
+    "items": [
+      { "name": "message_0.db", "opened": true, "hasTalkerTable": true,
+        "rowsForTalker": 8123, "reason": null }
+    ]
+  },
+  "coverage": "complete",
+  "mayHaveMore": false,
+  "warnings": [],
+  "updatedAt": "2026-09-19T09:02:10+08:00"
+}
+```
+
+### 两个时间戳必须分开
+
+| 字段 | 何时推进 |
+| --- | --- |
+| `lastAttempt` | **每次尝试都推进**，无论结果 |
+| `lastSuccessfulRun` | **仅在 `coverage !== 'partial'` 时推进** |
+
+只有一个的话，"跑了但部分完成"会和"跑成功了"混为一谈——而这正是方案 §5.2 明令禁止的
+（部分完成不能返回成功状态）。
+
+### `coverage` 三档
+
+| 值 | 含义 |
+| --- | --- |
+| `complete` | 扫到的分片全部打开、打开的全读成功，且 `mayHaveMore` 为 false |
+| `unverified` | 有分片**打不开**，但打开的都读成功。已读部分是可信的，未打开的分片是否含本会话消息**无法判断** |
+| `partial` | 某个**已打开**的分片读失败，或 `mayHaveMore` 为 true，或分页在到达窗口起点前就短页结束 |
+
+`unverified` 不是失败：`connect_message_shards` 一直把打不开的分片当作可跳过的（这是有意设计），
+CLI 无法知道那个分片里有没有本会话的消息。如实标成 `unverified` + `warnings` 比直接失败更有用，
+也让自动化不至于卡死。
+
+`partial` 则**必须失败**（`code: 'SYNC_PARTIAL'`，退出码 1）：状态文件照写（方案 §5.2 要求
+部分完成不得删除已生成的可用结果），但 `lastSuccessfulRun` 不推进。
+
+### 身份
+
+按方案 §4.2，`serverId` 非零时优先；**`localId` 绝不单独作为全局身份**（D-014 同此约束）。
+
+```
+talker|s:<serverId>                   serverId 非零
+talker|l:<localId>|t:<createTime>     否则
+```
+
+**与方案 §4.2 的一处有意偏离**：键里**不含 `shard`**。消息载荷里没有 shard 字段
+（`nt_decrypt._message_dict` 不产出它），加进去要动 `export json` 的消息契约，而 D-016/D-027
+把那条线封住了。它对本契约要解决的**重叠去重**也不必要——同一条消息重读两次，得到的
+`serverId` 或 `(localId, createTime)` 本来就一样。只有跨分片的 `(localId, createTime)` 撞车
+才需要它，而 `talker` + `createTime` 已让这种撞车极其遥远。**真观测到再加，不预先加。**
+
+### 明确不做的事
+
+**`mayHaveMore` 不是稳定游标。** 按 D-027，稳定增量游标必须在所有相关后端都支持后才能
+对外宣称；在此之前只提供重叠时间窗 + 本地去重，由下游决定重复容忍度。
+
+**不得写入**：数据库密钥、`x'<key><salt>'`、聊天正文、绝对路径（D-001 / D-002 / D-025）。
+状态服务在写盘前统一过一遍脱敏，不指望每个调用方都记得。
+
+## `weflow-job/v1`
+
+路径：`~/.weflow-cli/jobs/<jobId>.json`。`jobId` 形如 `job_20260919_0001`。
+
+```json
+{
+  "schema": "weflow-job/v1",
+  "jobId": "job_20260919_0001",
+  "kind": "sync.messages",
+  "state": "running",
+  "createdAt": "2026-09-19T09:00:00+08:00",
+  "updatedAt": "2026-09-19T09:02:10+08:00",
+  "window": { "from": 1788000000, "to": 1789000000 },
+  "progress": { "completed": 800, "total": 1200 },
+  "resumeable": true,
+  "result": { "records": 800, "recordsDeduplicated": 14, "shardsFailed": 0 },
+  "error": null
+}
+```
+
+状态机：`planned → waiting_confirmation → running → paused`，终态 `completed | partial | failed | cancelled`。
+本轮只实现 `running | completed | partial | failed`，其余是预留（不实现的不写进状态机文档当既有能力）。
+
+`partial` 是本项目新增的一档，**不算成功**。`error` 只放既有的大写错误码
+（`NOT_INITIALIZED`、`CONFIRMATION_REQUIRED`、`INVALID_ARGUMENT`、`SYNC_PARTIAL`、
+`DATABASE_CONNECTION_FAILED` 等），不写中文长句供机器解析。
+
+**幂等**：同一范围重复提交应返回已有任务或明确新建，不得静默重复写入。本轮用
+`kind + talker + 窗口` 生成幂等提示，命中未完成的同键任务时返回该任务而非新建。
+
+> 本轮 `sync` 是 job 记录的唯一写入者。若日后认为不值得单独一个文件，
+> **回退路径**：删掉 job 存储、把那个 `lastJob` 对象并入各会话的 `weflow-sync/v1` 文件。
+> 因为此刻还没有第二个消费者，这是一次单文件改动，无兼容性影响。
+
+## 版本升级策略
+
+- `schema` 变化 = 不兼容变更，需要迁移说明。
+- 只增字段 = 兼容变更；读方必须容忍未知字段（与 `DATA_CONTRACT.md` 对下游的要求一致）。
+- 读到未知 `schema` 时**不得覆盖**：报明确错误并保留原文件。
+
+## 相关文档
+
+- [功能增强技术方案](FUNCTIONAL-IMPROVEMENT-SPEC.md)
+- [消息数据契约](DATA_CONTRACT.md)
+- [技术决策记录](DECISIONS.md)
+- [项目当前状态](PROJECT_STATE.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "weflow-cli",
-  "version": "1.6.3",
+  "version": "1.7.0",
   "description": "让 AI 读懂你的微信 — 公众号日报·聊天导出·知识库搜索·MCP Server",
   "type": "module",
   "bin": {
@@ -43,7 +43,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "test": "node --import tsx --test test/**/*.test.ts",
+    "test": "node --import tsx --test \"test/**/*.test.ts\"",
     "dev": "npx tsx bin/weflow-cli.ts",
     "start": "node cli.cjs",
     "prepublishOnly": "npm run build"
@@ -78,6 +78,6 @@
     "typescript": "^5.7.0"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22.13.0"
   }
 }

package/scripts/export_chat_html.py

@@ -72,10 +72,21 @@ except Exception:
 # Remote media is the single slowest step of an export: each miss costs a page
 # fetch plus an image download, and inline thumbnails alone run to several
 # hundred per conversation. Bound it per run and keep results on disk, misses
-# included, so re-exports are instant. Set by main().
+# included, so re-exports are instant.
+#
+# Two separate pools: share-page covers are rare and expensive, inline appmsg
+# thumbnails are common and cheap. Sharing one would let a run of thumbnails
+# starve the covers that actually change how a page looks.
+COVER_FETCH_LIMIT = 60
+THUMB_FETCH_LIMIT = 300
+
+# Seeded with the full budgets rather than 0: main() re-sets them, but anything
+# that reaches the fetchers without going through main() used to find a budget
+# of 0 and silently skip every remote fetch, returning None with no error.
 COVER_STATE = {
-    'dir': '', 'budget': 0, 'fetched': 0, 'cached': 0, 'skipped': 0,
-    'thumb_budget': 0, 'thumb_fetched': 0, 'thumb_cached': 0, 'thumb_skipped': 0,
+    'dir': '', 'budget': COVER_FETCH_LIMIT, 'fetched': 0, 'cached': 0, 'skipped': 0,
+    'thumb_budget': THUMB_FETCH_LIMIT,
+    'thumb_fetched': 0, 'thumb_cached': 0, 'thumb_skipped': 0,
 }
 
 # Off by default: full-resolution originals are 5-24MB / 3000-5700px each, and
@@ -93,12 +104,6 @@ COVER_HEAD_BYTES = 64 * 1024
 # cost time, which matters across thousands of media entries.
 EMBED_SHRINK_THRESHOLD = 400 * 1024
 
-# Two separate budgets: share-page covers are rare and expensive, inline
-# appmsg thumbnails are common and cheap. Sharing one pool lets a run of
-# thumbnails starve the covers that actually change how a page looks.
-COVER_FETCH_LIMIT = 60
-THUMB_FETCH_LIMIT = 300
-
 # Set up by main(); custom stickers decrypted from WeChat's local cache.
 STICKER_STATE = {'key': b'', 'dirs': [], 'cache_dir': ''}
 
@@ -119,6 +124,12 @@ VOICE_STATE = {'map': {}, 'cache': None}
 # runs a throwaway formatting pass that only records the URLs (0.1s, no
 # network), fetches them concurrently, then formats for real against a warm
 # cache. Set to a list during that pass; None otherwise.
+# Why the most recent remote fetch produced nothing. The skip counter alone
+# said "not fetched" without saying why, so "no budget left" and "the URL is
+# dead" were indistinguishable in the export - and both looked like a bare
+# placeholder to the reader.
+MEDIA_STATE = {'remote_reason': None}
+
 PREFETCH = {'sink': None, 'active': False}
 PREFETCH_WORKERS = 24
 PREFETCH_MAX_URLS = 800
@@ -386,6 +397,29 @@ def scan_nt_cache(nt_cache_dir, talker, account_dir='', own_wxid=''):
             if key.startswith('md5:'):
                 image_map.setdefault(key, image)
 
+    # `unique:<local_id>`: an id that resolves to exactly one distinct image in
+    # this conversation is safe to match on its own. The id restarts across
+    # shards, but uniqueness inside one conversation's scan rules that out -
+    # which is what separates this from the bare-local_id match that
+    # get_cached_image deliberately refuses. Deduped by content, so one picture
+    # cached at several timestamps still counts as unique.
+    local_candidates = {}
+    for key, image in image_map.items():
+        if isinstance(key, str) and key.startswith('pair:'):
+            parts = key.split(':', 2)
+            if len(parts) != 3:
+                continue
+            local_id = parts[1]
+        elif isinstance(key, int):
+            local_id = str(key)
+        else:
+            continue
+        digest = hashlib.sha256(image[0].encode('ascii')).hexdigest()
+        local_candidates.setdefault(local_id, {})[digest] = image
+    for local_id, candidates in local_candidates.items():
+        if len(candidates) == 1:
+            image_map[f'unique:{local_id}'] = next(iter(candidates.values()))
+
     return image_map
 
 
@@ -724,35 +758,57 @@ def shrink_embedded(image, max_side=720, force=False):
         return image
 
 
-def get_cached_image(image_map, local_id, create_time, content='', resource_md5s=None, server_id=0):
-    """Best local media for a message: by content md5, then by identity.
+def resolve_media(image_map, local_id, create_time, content='', resource_md5s=None, server_id=0):
+    """Best local media for a message, with the identity that matched.
 
-    md5 is the strongest key, but it is not always derivable - a group row can
-    lack the resource mapping that carries it. The conversation cache also
-    indexes by `(local_id, create_time)`, which is identity-aware and was
-    already being stored; reading it recovers media the md5 path alone misses.
+    Returns `(base64, mime, media_key)` or None. `media_key` is the image_map
+    key that produced the hit, which is what the coverage report records - so
+    a report can never claim a match the page itself did not get, because both
+    come from this one function.
 
     Deliberately *not* falling back to a bare `local_id`: that id restarts in
     every message shard, so matching on it alone attaches one conversation's
-    image to another conversation's message.
+    image to another conversation's message. `unique:<local_id>` is the sound
+    version of that idea - scan_nt_cache only emits it when the id maps to a
+    single distinct image, so uniqueness has already ruled the collision out.
     """
     if not image_map:
         return None
     for media_md5 in resource_md5s or []:
-        if image_map.get(f'md5:{media_md5}'):
-            return shrink_embedded(image_map[f'md5:{media_md5}'])
+        key = f'md5:{media_md5}'
+        if image_map.get(key):
+            return shrink_embedded(image_map[key]) + (key,)
     for media_md5 in extract_media_md5s(content):
-        if image_map.get(f'md5:{media_md5}'):
-            return shrink_embedded(image_map[f'md5:{media_md5}'])
+        key = f'md5:{media_md5}'
+        if image_map.get(key):
+            return shrink_embedded(image_map[key]) + (key,)
     try:
         pair_key = f'pair:{int(local_id)}:{int(create_time)}'
     except (TypeError, ValueError):
         return None
     if image_map.get(pair_key):
-        return shrink_embedded(image_map[pair_key])
+        return shrink_embedded(image_map[pair_key]) + (pair_key,)
+    try:
+        unique_key = f'unique:{int(local_id)}'
+    except (TypeError, ValueError):
+        return None
+    if image_map.get(unique_key):
+        return shrink_embedded(image_map[unique_key]) + (unique_key,)
     return None
 
 
+def get_cached_image(image_map, local_id, create_time, content='', resource_md5s=None, server_id=0):
+    """`resolve_media` without the matched key, for every pre-existing caller.
+
+    md5 is the strongest key, but it is not always derivable - a group row can
+    lack the resource mapping that carries it. The conversation cache also
+    indexes by `(local_id, create_time)`, which is identity-aware and was
+    already being stored; reading it recovers media the md5 path alone misses.
+    """
+    hit = resolve_media(image_map, local_id, create_time, content, resource_md5s, server_id)
+    return (hit[0], hit[1]) if hit else None
+
+
 def detect_mime(filepath):
     """Detect MIME type from file header."""
     try:
@@ -882,12 +938,14 @@ def download_image_as_base64(url, aes_key='', timeout=10, budgeted=True):
     already spent their own budget for this URL.
     """
     if not url or not url.startswith(('http://', 'https://')):
+        MEDIA_STATE['remote_reason'] = 'not-http'
         return None
 
     sink = PREFETCH['sink']
     if sink is not None:
         # Dry pass: record the request, spend no budget, touch no network.
         sink.append(('img', url, aes_key))
+        MEDIA_STATE['remote_reason'] = 'deferred-to-prefetch'
         return None
 
     cache_dir = COVER_STATE.get('dir') or ''
@@ -899,11 +957,13 @@ def download_image_as_base64(url, aes_key='', timeout=10, budgeted=True):
     if cached != 'unknown':
         if budgeted:
             COVER_STATE['thumb_cached'] += 1
+        MEDIA_STATE['remote_reason'] = None
         return cached
 
     if budgeted and not PREFETCH['active']:
         if COVER_STATE.get('thumb_budget', 0) <= 0:
             COVER_STATE['thumb_skipped'] += 1
+            MEDIA_STATE['remote_reason'] = 'budget-exhausted'
             return None
         COVER_STATE['thumb_budget'] -= 1
         COVER_STATE['thumb_fetched'] += 1
@@ -920,6 +980,7 @@ def download_image_as_base64(url, aes_key='', timeout=10, budgeted=True):
             # it so the next export does not pay for the same dead URL.
             if len(data) > MAX_EMBED_SIZE:
                 _cache_media(cache_file, None)
+                MEDIA_STATE['remote_reason'] = 'too-large'
                 return None
             candidates = [data]
             decrypted = _decrypt_aes_cbc(data, aes_key)
@@ -933,10 +994,12 @@ def download_image_as_base64(url, aes_key='', timeout=10, budgeted=True):
                     data, mime = wechat_image.shrink(data, mime, max_side=480)
                 result = (base64.b64encode(data).decode(), mime)
                 _cache_media(cache_file, result)
+                MEDIA_STATE['remote_reason'] = None
                 return result
         except Exception:
             continue
     _cache_media(cache_file, None)
+    MEDIA_STATE['remote_reason'] = 'download-failed'
     return None
 
 
@@ -1560,8 +1623,14 @@ def format_message(row, talker, wx_dir, image_map=None, sender_map=None, display
     local_id = row[0] or 0
     server_id = row[1] or 0
     local_type = row[2] or 0
+    # WeChat stores some forwards as high-bit variants of type 49. The mask
+    # below turns those into plain 49, which is a known type - so the cached
+    # image branch further down can only recognise them if the pre-mask value
+    # is kept. Dropping this made that branch unreachable.
+    raw_local_type = local_type
     if local_type > 0xffffffff:
         local_type &= 0xffffffff
+    is_encoded_media_type = raw_local_type > 0xffffffff and local_type == 49
     real_sender_id = row[4] or 0
     create_time = row[5] or 0
     source = row[7]
@@ -1611,6 +1680,11 @@ def format_message(row, talker, wx_dir, image_map=None, sender_map=None, display
     if content and content != source_text:
         metadata_parts.append(content)
     metadata_content = '\n'.join(metadata_parts)
+    # A type-49 row carrying a title or url is a link/article card, not a bare
+    # image. Without this guard the encoded-media fallback below would hide the
+    # card (and its title/link) behind a cached thumbnail.
+    has_app_link_metadata = local_type == 49 and bool(
+        extract_xml_text(content, 'title') or extract_xml_text(content, 'url'))
     is_emoji_xml = bool(re.search(r'<(?:msg\s*>)?\s*<emoji\b|<emoji\b', metadata_content, re.IGNORECASE))
     is_contact_card = bool(
         re.search(r'<msg\b[^>]*(?:nickname|username)=', metadata_content, re.IGNORECASE)
@@ -1694,7 +1768,9 @@ def format_message(row, talker, wx_dir, image_map=None, sender_map=None, display
         if img_data:
             image_b64 = img_data
             display += f'<br><img src="data:{mime};base64,{img_data}" loading="lazy" />'
-    elif local_type not in MSG_TYPES and get_cached_image(image_map, local_id, create_time, content, resource_md5s):
+    elif (local_type not in MSG_TYPES or is_encoded_media_type) \
+            and not has_app_link_metadata \
+            and get_cached_image(image_map, local_id, create_time, content, resource_md5s):
         # Some image messages use encoded types (e.g. 21474836529 = images in appmsg)
         # Check image_map for any message type
         img_data, mime = get_cached_image(image_map, local_id, create_time, content, resource_md5s)
@@ -1787,11 +1863,14 @@ def format_message(row, talker, wx_dir, image_map=None, sender_map=None, display
                 builtin_title = _face_index.find_face(title)
                 title_html = (render_builtin_emoji(title, builtin_title)
                               if builtin_title else escape_html(title))
-                # Extract and embed article thumbnail image
+                # Try the conversation cache before the network: a cached
+                # thumbnail is already on disk and costs nothing, and without
+                # this the article branch downloaded covers it already had.
                 thumb_url = extract_appmsg_image(content)
-                if thumb_url:
+                img_data = get_cached_image(image_map, local_id, create_time, metadata_content, resource_md5s)
+                if not img_data and thumb_url:
                     img_data = download_image_as_base64(thumb_url, extract_media_aes_key(content))
-                else:
+                if not img_data:
                     page_url = extract_xml_text(content, 'url')
                     img_data = download_bilibili_cover(page_url)
                     if not img_data:
@@ -1839,9 +1918,117 @@ def format_message(row, talker, wx_dir, image_map=None, sender_map=None, display
         'local_type': local_type,
         'display': display,
         'image_b64': image_b64,
+        # Built here rather than accumulated in module state: format_message
+        # runs twice (the prefetch dry sweep and the real pass) and the dry
+        # pass is discarded, so a counter would double-count.
+        'media': build_media_record(
+            local_type, image_b64, image_map, local_id, create_time, content,
+            resource_md5s, metadata_content, bool(server_id)),
     }
 
 
+MEDIA_KIND_BY_TYPE = {
+    3: 'image', 34: 'voice', 43: 'video-thumb', 47: 'emoji', 49: 'link-cover',
+}
+MEDIA_KINDS = {'image', 'emoji', 'voice', 'video-thumb', 'link-cover'}
+
+
+def build_media_report(items, scope, talker, per_page):
+    """Coverage summary plus one entry per media item.
+
+    Written beside the HTML rather than into it: the page is for reading, this
+    is for answering "what is missing and why" without opening the export.
+    Paths, keys and message bodies are not included (D-001/D-002/D-025).
+    """
+    counts = {}
+    for item in items:
+        counts[item['status']] = counts.get(item['status'], 0) + 1
+    counts['total'] = len(items)
+    return {
+        'schema': 'weflow-media-report/v1',
+        'source': 'weflow-cli',
+        'generatedAt': datetime.datetime.now().astimezone().isoformat(timespec='seconds'),
+        'scope': scope,
+        'counts': counts,
+        'budget': {
+            'coversFetched': COVER_STATE.get('fetched', 0),
+            'coversCached': COVER_STATE.get('cached', 0),
+            'coversSkipped': COVER_STATE.get('skipped', 0),
+            'thumbsFetched': COVER_STATE.get('thumb_fetched', 0),
+            'thumbsCached': COVER_STATE.get('thumb_cached', 0),
+            'thumbsSkipped': COVER_STATE.get('thumb_skipped', 0),
+        },
+        'items': [
+            {
+                'mediaKey': item['mediaKey'],
+                'kind': item['kind'],
+                'status': item['status'],
+                'mime': item['mime'],
+                'bytes': item['bytes'],
+                'sha256': item['sha256'],
+                'reason': item['reason'],
+                'locator': {
+                    'part': (item['index'] // per_page + 1) if per_page else 1,
+                    'createTime': None,
+                },
+            }
+            for item in items
+        ],
+    }
+
+
+def build_media_record(local_type, image_b64, image_map, local_id, create_time,
+                       content, resource_md5s, metadata_content, has_server_id):
+    """What happened to this message's media, or None for a non-media message.
+
+    Derived from the same `resolve_media` the page used, so the report cannot
+    claim a match the page did not get (or vice versa). A media-free message
+    returns None: this is a media manifest, not a message manifest.
+    """
+    if local_type not in MEDIA_KIND_BY_TYPE:
+        return None
+    kind = MEDIA_KIND_BY_TYPE[local_type]
+    record = {
+        'mediaKey': None, 'kind': kind, 'status': None,
+        'mime': None, 'bytes': None, 'sha256': None, 'reason': None,
+    }
+
+    if image_b64:
+        hit = resolve_media(image_map, local_id, create_time, metadata_content,
+                            resource_md5s)
+        if hit:
+            # Matched a local key: report which one, so "why this image" is
+            # answerable without re-running the export.
+            record['mediaKey'] = hit[2]
+            record['status'] = 'embedded'
+        else:
+            # Bytes came from somewhere other than the conversation index.
+            if MEDIA_STATE['remote_reason'] is None:
+                record['status'] = 'remote-fetched'
+                record['mediaKey'] = 'remote'
+            else:
+                record['status'] = 'embedded'
+                record['mediaKey'] = 'unindexed-local'
+        raw = base64.b64decode(image_b64)
+        record['bytes'] = len(raw)
+        record['sha256'] = hashlib.sha256(raw).hexdigest()
+        return record
+
+    record['status'] = 'missing'
+    if not has_server_id and not extract_media_md5s(metadata_content) and not resource_md5s:
+        # D-014: with no reliable identity there is nothing safe to match on,
+        # and guessing would attach someone else's media.
+        record['reason'] = 'no-reliable-identity'
+    elif kind == 'voice':
+        record['status'] = 'unsupported'
+        record['reason'] = 'voice-not-in-media-index'
+    elif MEDIA_STATE['remote_reason']:
+        record['reason'] = MEDIA_STATE['remote_reason']
+    else:
+        record['reason'] = 'not-in-local-cache'
+    return record
+
+
 def decode_message_content(value):
     """Decode NT message content, which may be Zstandard compressed."""
     if not value:
@@ -2285,6 +2472,7 @@ def main():
 
     print(f"Formatting {len(messages)} messages...")
     formatted = []
+    media_items = []
     img_hit_count = 0
     article_img_count = 0
     progress_step = max(1, len(messages) // 20)
@@ -2296,6 +2484,12 @@ def main():
             img_hit_count += 1
             if result.get('local_type') == 49:
                 article_img_count += 1
+        record = result.get('media')
+        if record:
+            # Index kept so the report can point back at the page part.
+            record = dict(record)
+            record['index'] = i
+            media_items.append(record)
         formatted.append(result)
     print(f"  Messages with embedded images: {img_hit_count} (including {article_img_count} article thumbnails)")
 
@@ -2315,6 +2509,20 @@ def main():
     # Use display name for filename if provided, otherwise fallback to wxid
     file_prefix = sanitize_filename(display_name) if display_name else args.talker.replace('@', '_').replace('/', '_')
 
+    # Media coverage report. Written beside the HTML parts, under the same
+    # prefix, so it is always found next to what it describes.
+    media_report = None
+    media_report_path = None
+    if media_items:
+        media_report = build_media_report(media_items, display_name, args.talker, per_part)
+        media_report_path = os.path.join(args.out, f'{file_prefix}_media.json')
+        with open(media_report_path, 'w', encoding='utf-8') as handle:
+            json.dump(media_report, handle, ensure_ascii=False, indent=2)
+        summary = media_report['counts']
+        missing = summary.get('missing', 0) + summary.get('unsupported', 0)
+        print(f"Media report: {len(media_items)} item(s), {missing} unavailable "
+              f"-> {os.path.basename(media_report_path)}")
+
     html_files = []
     for i in range(parts):
         start = i * per_part
@@ -2343,12 +2551,20 @@ def main():
     print(f"\nDone! {len(html_files)} HTML files written to {args.out}")
     print(f"Total: {total} messages")
 
-    # Print JSON summary for CLI integration
+    # Print JSON summary for CLI integration.
+    # The four original keys are untouched; `media` is purely additive and the
+    # one existing consumer (src/services/exportService.ts) ignores it.
     print(json.dumps({
         "success": True,
         "total": total,
         "parts": len(html_files),
         "files": html_files,
+        "media": ({
+            "schema": "weflow-media-report/v1",
+            "records": len(media_items),
+            "status": media_report['counts'],
+            "report": os.path.basename(media_report_path) if media_report_path else None,
+        } if media_report else None),
     }))