weflow-cli 1.6.2 → 1.6.4

package/CHANGELOG.md

@@ -4,6 +4,32 @@ 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.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
+
+- `npm install -g weflow-cli` no longer fails on machines without Visual Studio build tools. `lz4@0.6.5` declares an unconditional `"install": "node-gyp rebuild"` with no prebuilt binaries and no fallback, so having it in `dependencies` made the whole install abort with `gyp ERR! find VS could not find a version of Visual Studio 2017 or newer` - for every Windows user without a C++ toolchain, which is most of them. The code only ever used it for 3.x WCDB `CompressContent` decompression, and already loaded it lazily behind a `try/catch` that degrades to `null`, so it is now an `optionalDependency`: npm installs it best-effort and continues when the build fails. Measured on a machine with no Visual Studio: before, `npm install` exited 1; after, it exits 0 and the installed CLI runs.
+
 ## 1.6.2
 
 ### 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` |

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
@@ -322,6 +322,7 @@ python scripts/fav_server.py --date YYYY-MM-DD
 - [技术决策记录](./docs/DECISIONS.md)：长期维护中的关键设计取舍。
 - [分支与合并记录](./docs/BRANCHES.md)：分支用途、合并时间线与并行开发的对齐约定。
 - [发布清单](./docs/RELEASING.md)：版本号、打包敏感内容检查、npm 凭据、国内镜像同步。
+- [npm 发布速查](./docs/NPM-PUBLISH.md)：404 / 409 / ETARGET 是失败还是在传播，按症状查表。
 - [定期体检](./docs/HEALTH-CHECK.md)：一条命令查出版本漂移、分片漏读、会话不更新与导出失败。
 - [电子数据证据指南](./docs/EVIDENCE_GUIDE.md)：证据保全、法律边界与使用注意事项。
 - [贡献指南](./CONTRIBUTING.md) 与 [安全策略](./SECURITY.md)：开发、反馈和敏感问题处理。

package/docs/HEALTH-CHECK.md

@@ -15,16 +15,17 @@ py scripts/health_check.py          # 人读的报告
 py scripts/health_check.py --json   # 机器读
 ```
 
-退出码 `0` = 全部通过，`1` = 有失败项。报告长这样：
+退出码 `0` = 全部通过，`1` = 有失败项。报告长这样（版本号、日期、字节数都是
+当次运行的真实值，仅作示例）：
 
 ```
-WeFlow 健康检查 · 2026-09-17 23:11
+WeFlow 健康检查 · 2026-09-19 10:04
 
-[OK  ] 版本一致                      CLI 1.6.1 / package 1.6.1
+[OK  ] 版本一致                      CLI X.Y.Z / package X.Y.Z
 [OK  ] 环境自检                      已初始化=True 消息库=True
 [OK  ] Python 依赖                  齐全
-[OK  ] 会话新鲜度                     最新会话 2026-09-17 23:10（0.0 天前）
-[OK  ] 读取路径一致 (wxid_6xx1ehe4h…)  json 最新 2026-09-17 23:10 / html 最新 2026-09-17 23:10:13
+[OK  ] 会话新鲜度                     最新会话 2026-09-19 10:03（0.0 天前）
+[OK  ] 读取路径一致 (wxid_6xx1ehe4h…)  json 最新 2026-09-19 10:03 / html 最新 2026-09-19 10:03:12
 [OK  ] 导出格式 json                 938 字节
 [OK  ] 导出格式 txt                  145 字节
 [OK  ] 导出格式 excel                6788 字节

package/docs/MCP.md

@@ -92,4 +92,4 @@ The chat-data tools share service code with the optional `weflow-cli assistant`
 | --- | --- |
 | Server fails to start | Run `npm install` in the configured `cwd`, then run `npx tsx mcp-server/index.ts`. |
 | No articles found | Generate a daily collection first, then confirm `output/biz-daily/` exists under `cwd`. |
-| Client cannot find `npx` | Configure an absolute Node.js command path or install Node.js 18+. |
+| Client cannot find `npx` | Configure an absolute Node.js command path or install Node.js 22.13+. |

package/docs/NPM-PUBLISH.md

@@ -0,0 +1,130 @@
+# npm 发布 — 速查与故障对照
+
+只讲 npm 这一侧。**流程清单**在 [RELEASING.md](RELEASING.md)，这里只解决
+「命令跑完了，现在到底算成功没有」。
+
+单个环节按需查，不必通读。
+
+## 0. 省上下文（先看这条）
+
+发布命令会打印几百行 `Tarball Contents`。**永远加过滤**，否则整个文件清单
+会灌进上下文，既没用又挤掉真正要看的信息：
+
+```bash
+npm publish --registry=https://registry.npmjs.org 2>&1 \
+  | grep -vE "^npm notice [0-9.]+[kMB]+ |^npm notice [0-9.]+B " | tail -25
+```
+
+`npm pack --dry-run` 同理。要看文件清单时**输出到文件再 grep**，不要直接打印：
+
+```bash
+npm pack --dry-run 2>&1 | grep "npm notice [0-9]" > /tmp/packlist.txt
+grep -c " dist/" /tmp/packlist.txt     # 注意: 行首是体积, 不是路径
+```
+
+## 1. 唯一可靠的判据
+
+**别信命令的输出，信 registry 的 `versions` 表：**
+
+下面用 `X.Y.Z` 代表这次要发的版本，**照抄时换成实际版本号**——写死在这里的版本
+过几天就是错的。
+
+```bash
+V=X.Y.Z
+curl -s "https://registry.npmjs.org/weflow-cli?nocache=$RANDOM" --max-time 30 \
+| python -c "
+import json,sys,os
+d=json.load(sys.stdin)
+print('latest:', d['dist-tags']['latest'])
+print('目标版本存在:', os.environ['V'] in d['versions'])" V="$V"
+```
+
+- `目标版本存在: True` → **发布成功**，剩下只是传播
+- `False` → 没发出去，看第 2 节
+
+`npm view` 会读到客户端缓存，`--prefer-online` 或上面的 `nocache` 才准。
+
+## 2. 症状 → 含义 → 动作
+
+| 现象 | 含义 | 动作 |
+| --- | --- | --- |
+| `+ weflow-cli@X.Y.Z` | 已被接受 | 继续，等传播 |
+| `being processed and may take a few minutes` | 正常提示 | 等，别重发 |
+| `npm view` 仍是旧版本 | CDN 传播中 | **不是失败**，等 2–5 分钟 |
+| 重发报 `409 Conflict - Cannot publish over previously staged version` | **已经发布成功了** | 别再发，去等传播 |
+| tarball `404`（`/-/weflow-cli-X.Y.Z.tgz`） | 元数据已发布，tarball 还在传播 | 等，不是失败 |
+| `install` 报 `ETARGET No matching version` | 客户端缓存了旧 packument | 加 `--prefer-online` 重试 |
+| `install` 报 `404` | 元数据在、tarball 未到 | 等传播 |
+| `403 ... bypass 2fa enabled is required` | token 没勾 Bypass 2FA | 重新生成 token（见第 3 节） |
+| `E404` 发布时 | 包名或权限问题 | 查 `npm whoami` |
+
+> **404 / 409 / ETARGET 在发布后的几分钟内都是传播现象，不是错误。**
+> 唯一例外：`403` 和发布时的 `E404`。
+
+## 3. 凭据自检
+
+不打印 token 本身：
+
+```bash
+npm whoami --registry=https://registry.npmjs.org
+
+TOKEN=$(sed -n 's/.*_authToken=//p' ~/.npmrc | tr -d '\r\n')
+curl -s -H "Authorization: Bearer $TOKEN" \
+  "https://registry.npmjs.org/-/npm/v1/tokens" --max-time 30 \
+| python -c "
+import json,sys
+for t in (json.load(sys.stdin).get('objects') or []):
+    print(t.get('tokenId','')[:12], 'bypass_2fa=', t.get('bypass2fa'), 'created=', t.get('created'))"
+```
+
+`bypass_2fa` 必须是 `True`，否则发布会要 OTP。
+
+## 4. 触发国内镜像同步
+
+```bash
+curl -s -X PUT "https://registry.npmmirror.com/-/package/weflow-cli/syncs" --max-time 40
+```
+
+`{"ok":true,...,"state":"waiting"}` 即受理，**约 5 分钟**生效。
+
+两个源不一致时，先怀疑镜像同步，不要怀疑包：
+
+```bash
+npm view weflow-cli version --registry=https://registry.npmjs.org
+npm view weflow-cli version --registry=https://registry.npmmirror.com
+```
+
+## 5. 装一份下来验（最终确认）
+
+```bash
+mkdir -p /tmp/verify && cd /tmp/verify && npm init -y >/dev/null
+npm install weflow-cli@X.Y.Z --registry=https://registry.npmjs.org --prefer-online --no-audit --no-fund
+node -e "console.log(require('./node_modules/weflow-cli/package.json').version)"
+```
+
+装不上但第 1 节显示版本存在 → 就是 tarball 传播中，等。
+
+## 6. 打包安全检查（发布前，不能跳）
+
+```bash
+npm pack --dry-run 2>&1 | grep "npm notice [0-9]" > /tmp/packlist.txt
+grep -E "output/|models/|node_modules|\.env|\.db$|\.dat$|_env\.json|secret|credential|\.key$|\.pem$" /tmp/packlist.txt
+```
+
+**这条必须没有输出。** 有输出就停下查。
+
+再确认新增文件确实**在**包里（`files` 白名单按目录配，容易漏）：
+
+```bash
+for f in scripts/health_check.py docs/HEALTH-CHECK.md cli.cjs; do
+  grep -qF "$f" /tmp/packlist.txt && echo "✓ $f" || echo "✗ 缺失 $f"
+done
+```
+
+## 已知坑
+
+- **`bin` 会被 npm 改写**：`"bin": {"weflow-cli": "./cli.cjs"}` 发布时报
+  `script name cli.cjs was invalid and removed`，同时 `repository.url` 被规范化。
+  是 warning，不影响发布结果，但要知道它每次都出现，不是本次引入的问题。
+- **`.gitignore` 里 `*.md` 默认忽略、逐个放行**：新增文档必须同时加
+  `!docs/<名字>.md`，否则 `git add` 会被挡。

package/docs/PROJECT_STATE.md

@@ -1,6 +1,6 @@
 # Project State
 
-> Last reviewed: 2026-09-08. This is the current maintenance snapshot, not a release note. Keep it factual and update it with meaningful project changes.
+> Last reviewed: 2026-09-19. This is the current maintenance snapshot, not a release note. Keep it factual and update it with meaningful project changes.
 
 ## Purpose
 
@@ -8,8 +8,8 @@ WeFlow CLI is a local-first command-line tool and MCP server for user-authorized
 
 ## Current Baseline
 
-- Source package version: `1.5.1`. The npm registry may remain on an earlier version until a maintainer publishes a release.
-- Runtime: Node.js 18+; Python 3.10+ is required for database and daily-reading workflows.
+- Source package version: take it from `package.json` -> `version` rather than from this file - a hardcoded copy drifts silently, and `package-lock.json` must always match it. The npm registry may remain on an earlier version until a maintainer publishes a release.
+- Runtime: Node.js 22.13+; Python 3.10+ is required for database and daily-reading workflows. The floor is set by `src/core/sqlcipherCore.ts`, which imports `node:sqlite` at module scope; that builtin exists from 22.5.0 and stops needing `--experimental-sqlite` at 22.13.0.
 - Main development command: `npm run dev -- <command>`.
 - Compiled/package command: `node cli.cjs <command>`; CLI, MCP, database, export, and assistant services resolve resources from the same package root in both source and compiled layouts.
 - Build check: `npm run build`.
@@ -53,7 +53,7 @@ Date-bounded message exports and `wechat.export_messages` page through the selec
 - `search` and `chat` use the same preview/confirmation boundary. Queries, questions, and optional conversation restrictions are inherited through the worker environment instead of appearing in process arguments; machine callers cannot start interactive RAG chat.
 - `daily-server --status --json` remains read-only. Machine startup uses `daily-server --dry-run --json` followed by `daily-server --yes --json`; the confirmed process is detached and remains bound to loopback. The legacy `fav-server` compatibility entry enforces the same preview and confirmation rules.
 
-Documentation was synchronized with the `1.5.1` source baseline on 2026-09-09. Command behavior is defined by `bin/weflow-cli.ts`; detached reader startup waits for service readiness, and release packages can lag behind the GitHub source until published.
+Documentation was synchronized with the current source baseline on 2026-09-19. Command behavior is defined by `bin/weflow-cli.ts`; detached reader startup waits for service readiness, and release packages can lag behind the GitHub source until published.
 
 ## Active Constraints
 

package/docs/RELEASING.md

@@ -1,5 +1,8 @@
 # 发布清单
 
+> npm 侧的**症状对照与省上下文技巧**在 [NPM-PUBLISH.md](NPM-PUBLISH.md)：
+> 404 / 409 / ETARGET 到底是失败还是在传播，查那一份，不用通读本文。
+
 npm 包与 GitHub 分开发布，中间隔多久都不奇怪——`1.5.0` 与主线之间曾拉开 128 个提交、
 两个多月，直接导致用户照着 README 敲 `init --path` 却报 `unknown option`。
 

package/docs/SETUP.md

@@ -4,7 +4,7 @@
 
 ## 前置条件
 
-- Windows 10/11 x64 是当前重点验证平台；Node.js 18+、Python 3.10+。
+- Windows 10/11 x64 是当前重点验证平台；Node.js 22.13+、Python 3.10+。
 - 已安装并登录兼容的微信版本。微信数据库格式和平台行为可能随版本变化。
 - 足够的磁盘空间保存本地日报或导出副本。
 

package/package.json

@@ -1,81 +1,83 @@
-{
-  "name": "weflow-cli",
-  "version": "1.6.2",
-  "description": "让 AI 读懂你的微信 — 公众号日报·聊天导出·知识库搜索·MCP Server",
-  "type": "module",
-  "bin": {
-    "weflow-cli": "./cli.cjs"
-  },
-  "files": [
-    "cli.cjs",
-    "dist/",
-    "scripts/**/*.py",
-    "mcp-server/",
-    "bin/",
-    "src/",
-    "resources/",
-    "docs/images/",
-    "docs/*.md",
-    "README.md",
-    "OPERATIONS.md",
-    "ARCHITECTURE.md",
-    "CONTRIBUTING.md",
-    "SECURITY.md",
-    "CHANGELOG.md",
-    "requirements*.txt",
-    "LICENSE"
-  ],
-  "keywords": [
-    "wechat",
-    "weixin",
-    "mcp",
-    "rss",
-    "daily",
-    "公众号",
-    "聊天记录",
-    "ai",
-    "deepseek",
-    "claude"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/zhuobichen/weflow-cli"
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "node --import tsx --test test/**/*.test.ts",
-    "dev": "npx tsx bin/weflow-cli.ts",
-    "start": "node cli.cjs",
-    "prepublishOnly": "npm run build"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@wenyan-md/core": "^3.0.10",
-    "chalk": "^5.4.1",
-    "commander": "^13.1.0",
-    "css-tree": "^3.2.1",
-    "exceljs": "^4.4.0",
-    "form-data-encoder": "^4.1.0",
-    "formdata-node": "^6.0.3",
-    "front-matter": "^4.0.2",
-    "fzstd": "^0.1.1",
-    "highlight.js": "^11.11.1",
-    "inquirer": "^13.4.3",
-    "jsdom": "^27.4.0",
-    "koffi": "^2.9.0",
-    "lz4": "^0.6.5",
-    "marked": "^18.0.4",
-    "marked-highlight": "^2.2.4",
-    "qrcode-terminal": "^0.12.0"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "@types/qrcode-terminal": "^0.12.2",
-    "electron": "^42.0.1",
-    "tsx": "^4.19.0",
-    "typescript": "^5.7.0"
-  },
-  "engines": {
-    "node": ">=18"
-  }
-}
+{
+  "name": "weflow-cli",
+  "version": "1.6.4",
+  "description": "让 AI 读懂你的微信 — 公众号日报·聊天导出·知识库搜索·MCP Server",
+  "type": "module",
+  "bin": {
+    "weflow-cli": "./cli.cjs"
+  },
+  "files": [
+    "cli.cjs",
+    "dist/",
+    "scripts/**/*.py",
+    "mcp-server/",
+    "bin/",
+    "src/",
+    "resources/",
+    "docs/images/",
+    "docs/*.md",
+    "README.md",
+    "OPERATIONS.md",
+    "ARCHITECTURE.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "requirements*.txt",
+    "LICENSE"
+  ],
+  "keywords": [
+    "wechat",
+    "weixin",
+    "mcp",
+    "rss",
+    "daily",
+    "公众号",
+    "聊天记录",
+    "ai",
+    "deepseek",
+    "claude"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zhuobichen/weflow-cli"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --import tsx --test \"test/**/*.test.ts\"",
+    "dev": "npx tsx bin/weflow-cli.ts",
+    "start": "node cli.cjs",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@wenyan-md/core": "^3.0.10",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "css-tree": "^3.2.1",
+    "exceljs": "^4.4.0",
+    "form-data-encoder": "^4.1.0",
+    "formdata-node": "^6.0.3",
+    "front-matter": "^4.0.2",
+    "fzstd": "^0.1.1",
+    "highlight.js": "^11.11.1",
+    "inquirer": "^13.4.3",
+    "jsdom": "^27.4.0",
+    "koffi": "^2.9.0",
+    "marked": "^18.0.4",
+    "marked-highlight": "^2.2.4",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "optionalDependencies": {
+    "lz4": "^0.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/qrcode-terminal": "^0.12.2",
+    "electron": "^42.0.1",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "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': ''}
 
@@ -386,6 +391,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
 
 
@@ -734,7 +762,9 @@ def get_cached_image(image_map, local_id, create_time, content='', resource_md5s
 
     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
@@ -750,6 +780,12 @@ def get_cached_image(image_map, local_id, create_time, content='', resource_md5s
         return None
     if image_map.get(pair_key):
         return shrink_embedded(image_map[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])
     return None
 
 
@@ -1560,8 +1596,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 +1653,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 +1741,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 +1836,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: