weflow-cli 1.5.0 → 1.6.0

package/ARCHITECTURE.md

@@ -0,0 +1,105 @@
+# WeFlow CLI 技术架构
+
+> 本文描述当前代码的边界和数据流。维护时先以 `bin/weflow-cli.ts`、`src/` 和 `scripts/` 为准，再更新本文。
+
+## 定位
+
+WeFlow CLI 是一个本地优先的命令行工具和 stdio MCP Server，面向用户本人有权访问的微信本地数据，提供查询、导出、公众号阅读、知识整理和可选 AI 助手能力。
+
+## 分层结构
+
+```text
+MCP 客户端 / 终端用户
+          |
+          v
+CLI 入口 bin/weflow-cli.ts  ----  mcp-server/index.ts
+          |
+          v
+业务服务层
+  chat / contact / export / evidence / favorites / sns
+  daily / vault / weread / assistant / config / privacy
+          |
+          +--> Node 原生层：路径发现、配置、数据库适配、消息通道
+          +--> Python 工作流：NT 数据、公众号日报、HTML 阅读器、知识管道
+          |
+          v
+本地数据与明确选择的外部服务
+  微信本地数据库、缓存、日报输出、Vault
+  公众号网页、微信读书、用户配置的 AI 端点、官方 Bot 通道
+```
+
+## 代码边界
+
+| 目录 | 职责 |
+| --- | --- |
+| `bin/` | Commander 命令定义、参数校验和交互式菜单。 |
+| `src/core/` | 数据目录发现、数据库连接、密钥配置适配和客户端底层集成。 |
+| `src/services/` | 聊天、导出、证据包、日报、助手、白名单和隐私策略。 |
+| `scripts/` | Python 数据读取、公众号抓取、日报、HTML、搜索和报告脚本。 |
+| `mcp-server/` | 通过 stdio 暴露受控工具，不监听网络端口。 |
+| `test/` | Node 和 Python 回归测试，优先使用合成数据。 |
+| `resources/` | 随包发布的只读资源，例如默认表情素材。 |
+
+## 主要数据流
+
+### 聊天查询与导出
+
+```text
+用户指定的数据根目录
+  -> 分片数据库发现与配置验证
+  -> 聊天/联系人查询
+  -> 导出 JSON、TXT、Markdown、HTML 或 Excel
+  -> HTML 按稳定消息身份匹配媒体，无法确认时保留占位符
+```
+
+4.x 数据可能包含多个 `message_*.db` 分片，以及联系人、朋友圈、收藏和媒体资源库。跨分片查询时不能把本地消息 ID 当作全局唯一值；媒体关联优先使用稳定的服务端消息身份，并结合内容指纹和资源记录。这个策略用于避免把别的消息图片串到当前聊天中。
+
+### 公众号日报与阅读器
+
+```text
+本地公众号推送数据
+  -> 按来源筛选
+  -> 抓取用户选择的文章正文（需要联网）
+  -> AI 摘要/分类（可关闭）
+  -> output/biz-daily/YYYY-MM-DD/
+  -> 127.0.0.1:8765 本地阅读器
+```
+
+来源类别优先于文章主题分类：已配置类别的公众号保留其类别，并跳过该文章的自动主题分类；未配置类别时才使用文章分类逻辑。`daily --no-ai` 或持久化配置 `dailyAiEnabled=false` 时不调用 AI，但仍可抓取、生成 HTML 和更新本地索引。
+
+未指定日期运行 `daily` 时，会先检查昨天是否缺少 `README.md`、`.articles.json` 或 `index.html`；昨天不完整则先补齐，成功后再生成今天。显式 `--date` 和 `--dry-run` 是单日期操作。
+
+### 知识库与报告
+
+```text
+日报 / 收藏 / 微信读书笔记
+  -> Vault 文件与 Wiki 概念页
+  -> 本地搜索或可选 AI RAG
+  -> review、report、annual-report、todos 等报告
+```
+
+Vault promotion 默认不调用 AI；只有显式使用 `--with-ai` 并提供凭据时才生成 AI 内容。
+
+### 助手与 MCP
+
+```text
+MCP stdio 或官方 Bot 通道
+  -> 白名单与隐私策略
+  -> 受控工具调用
+  -> 本地数据查询 / 可选云端模型
+  -> 脱敏后的回复或工具结果
+```
+
+MCP 客户端本身是可信调用方，配置前必须审查其权限和工作目录。默认 MCP 工具面只读，不提供发布、发送、记忆写入、待办修改、配置变更或删除。助手默认拒绝所有来信；`send` 仅用于已建立的官方 Bot 通道会话，不等于操控个人微信账号，也不能向普通个人联系人或群聊发消息。
+
+## 支持与限制
+
+- 当前重点验证 Windows 微信 4.x；Linux 可使用相应 NT 数据路径；macOS 不提供自动初始化，需用户自行提供合法的本地访问凭据。
+- 数据库格式、微信版本、官方通道和账号策略可能变化；本地运行不保证兼容性、账号安全或法律结果。
+- 图片和表情导出会尽力使用本地缓存、媒体资源记录和消息提供的 URL。没有可靠身份或原始资源时不会猜测其他图片，而是显示占位信息。
+- 阅读器只绑定回环地址，默认不是局域网服务。
+- 云端 AI、文章抓取、微信读书和发布草稿都可能产生网络请求；本地推理可避免对应的正文出网，但仍应审查客户端和模型配置。
+
+## 维护规则
+
+功能、平台、限制或验证状态变化时更新 `docs/PROJECT_STATE.md`；影响安全、数据流或兼容性的取舍写入 `docs/DECISIONS.md`；用户可见变化才写入 `CHANGELOG.md`。

package/CHANGELOG.md

@@ -0,0 +1,110 @@
+# Changelog
+
+The npm package is published separately from GitHub. It may lag behind the `master` branch until a release is published.
+
+All notable user-facing changes are recorded here. This project follows [Semantic Versioning](https://semver.org/).
+
+## 1.6.0
+
+### Documentation
+
+- Synchronized setup, operations, architecture, security, MCP, and maintenance guidance with the current `1.6.0` source baseline.
+- Clarified source-versus-npm version drift, no-AI daily runs, staged data-directory discovery, media-export limitations, and local-data privacy boundaries.
+- Replaced the outdated architecture image with a GPT-image-2 diagram covering current CLI, MCP, service, workflow, data, and privacy boundaries.
+
+### Fixed
+
+- Decode locally cached WeChat 4.x V2 image containers during HTML chat export by deriving and validating the account-specific media key from local `kvcomm` data.
+- Match exported chat media by stable server-message identity so reused local IDs cannot attach an unrelated image or emoji.
+- Match NT cache media by the exact local-message-ID and timestamp pair when server-resource metadata is unavailable, including reused local IDs.
+- Preserve forwarded app cards with cached covers, including CDATA-wrapped Bilibili links, and decrypt remote WeChat 4.x emoticons with their message-provided AES key.
+- Decode entity-escaped emoji XML and try `encrypturl`, `thumburl`, `cdnurl`, and `externurl` fallbacks; resolve Bilibili BV covers when a share page omits `og:image`.
+- Render signature-only WeChat default `[打脸]` messages with the bundled official `Facepalm` asset when no message-specific resource is available.
+- Cache remote export media (covers, article thumbnails, emoticon CDN) on disk, misses included, so a re-export no longer repeats hundreds of requests against dead WeChat CDN links. First export of a link-heavy conversation dropped from 228s to 28s and re-export to 1.8s, with identical output.
+- Fetch that remote media concurrently instead of one URL per message. A throwaway local-only pass records what the conversation needs, the URLs are fetched in parallel, then the real pass runs against a warm cache.
+- Try WeChat's local sticker cache before the CDN for custom emoticons. The local path is offline and instant; the CDN cost 1.32s per sticker and was tried first.
+- Discover the account's sticker seed automatically. `find_seed`/`any_sticker_file` existed but nothing called them, so `emoticonSeed` stayed empty, local decryption never ran, and custom stickers silently degraded. The export now derives it from a real cached sticker, memoises it, and prints the command to persist it.
+- Render `local_type=10000` system rows as text. Escaping the raw row put WeChat's own display markup (`<img src="SystemMessages_HongbaoIcon.png"/>`, `<_wc_custom_link_ ...>`) in the bubble as a wall of `&lt;sysmsg ...&gt;`, so a revoke notice read as XML instead of naming who revoked what. `$wxid_...$` placeholders are expanded too.
+- Flatten quoted replies (appmsg type 57) whose `<des>` carries a whole escaped nested message, instead of dumping the nested markup.
+- Surface the Python exporter's progress and diagnostics in `export html` output; only the trailing JSON summary was read, so a multi-minute export showed nothing in between.
+- Name the actual speaker in group chats. `display_name` is the group, so every bubble was labelled with the group name and no message could be attributed; group rows now use the sender id carried by the content prefix, falling back to the sender map.
+- Render `local_type=48` location rows as their place label (`[位置] ...`) instead of dumping the location XML.
+- Strip the redundant `wxid_...: ` content prefix from group rows once it has been used to identify the speaker.
+- Resolve group senders to names from the contact database (remark, then nickname, then alias). A group transcript previously showed raw wxids for every speaker; unresolved ids still fall back to the id rather than a blank.
+- Merge the conversation cache and the account media index instead of choosing between them. A `--cache-dir` short-circuited the account scan, and a conversation cache only keeps recent months, so a group photo from last year resolved 0 of 1444 images and every one rendered as a bare `[图片]`. The same fix also recovered 82 additional images in a 1:1 conversation.
+- Show a cached poster frame for `local_type=43` videos when one exists, and always show the clip's duration (`[视频 10″]`) instead of a bare `[视频]`. Where WeChat never downloaded the video, no poster exists locally to show.
+- Fix HTML part navigation, which linked to `<talker>_partN.html` while the files were written as `<remark>_partN.html`, so every "第 N 部分" link opened a missing file (`ERR_FILE_NOT_FOUND`). Affected both group and 1:1 exports; all 16165 links across the two test conversations now resolve.
+- Correct the exported page footer, which still claimed images cover only the most recent two months.
+- Show the drawn frame of a `wxgf` sticker instead of a blank white square. Sticker H.265 streams routinely open with a blank transition frame, and taking frame 1 embedded that; decoding a few frames and keeping the one carrying the most artwork fixes it (one sticker measured 99.1% white before, 2.1% after). Verified across three conversations: 2215 embedded images, 0 blank.
+- Treat an all-blank sticker payload as a failed decode rather than an image, so a truncated local download or a CDN placeholder falls back to the `[表情]` label instead of rendering an empty square.
+- Test the plain-text branch against the message body rather than the row's combined metadata. `metadata_content` always carries `<msgsource>`, so the check always saw a `<` and every text message that had sender metadata skipped the text branch and fell through to the emoji one - rendering a Tencent Meeting invite as `[表情]` beside a broken image.
+- Label `local_type=10000` system rows as `系统` and never fall back to the conversation name for a group speaker. A revoke notice or join template resolves to no member, and the fallback labelled it with the group name, reading as if the group itself had spoken.
+- Render `sysmsgtemplate` join notices from their template and member list (`"彪弟"邀请你和"777"加入了群聊`) instead of stripping the tags and leaving only the chatroom id.
+- Never emit a remote URL as an `<img>` source. The candidate comes from a catch-all that accepts any URL in the row, and a sample of 57 such sources found 56 were web page links (`meeting.tencent.com`, `github.com`, `support.weixin.qq.com`) rather than images, each rendering as a broken-image icon. Images we could not fetch are now simply not shown.
+- Improved WeChat data-directory discovery for custom locations, nested folders, and database subdirectories.
+- Added staged guidance and optional `init --full-scan` fallback when automatic discovery cannot find the data.
+- Completed incomplete yesterday output before an unqualified daily report run.
+
+### Added
+
+- Transcribe voice messages into HTML exports. WeChat voice is SILK v3, which browsers cannot play and ffmpeg cannot decode at all, so a voice message previously carried no information whatsoever. `scripts/wechat_voice.py` decodes the payloads from `media_*.db`'s `VoiceInfo` table and recognises them on-device, and the export renders `[语音 6″]` with the transcript beneath it.
+- Transcription is a separate, resumable pass rather than part of the export: exports only read a content-addressed transcript cache, so a long conversation never blocks an export and an interrupted run continues where it stopped.
+- Prefer a Cantonese fine-tune over stock Whisper. Stock Whisper answers Cantonese speech with fluent, confident Mandarin that was never said — worse than no transcript, because it reads as a real sentence. The Cantonese model transcribes the same clips into actual Cantonese, and stock `large-v3` was measurably worse still, hallucinating Vietnamese and English.
+- Use the GPU when one is available, falling back to CPU. The same clip goes from 2.0s to 0.07s, which is the difference between a ~30 minute pass and an overnight one. Includes the Windows DLL-path setup the recognition library needs for its CUDA runtime.
+- `requirements-voice.txt` declares the optional voice dependencies.
+- Label machine transcripts and state the limitation in the page footer. Sampling a Cantonese family group found the recogniser producing Cantonese-shaped text whose meaning often does not hold - right sounds, wrong words. A confidently wrong transcript is worse than an obvious placeholder in a record that may be cited, so transcripts are marked `机器转写·粤语欠准` and the footer says they must not be quoted as the original words. See OPERATIONS.md for the measurements that rule out decoding, audio quality, and model confidence as causes.
+
+### Security and reliability
+
+- Run the regression suite in CI and make NT path-discovery checks independent of the optional SQLCipher runtime.
+- Make data-directory search staged: common locations by default, explicit cross-drive search, then explicit deep structural search.
+- Avoid printing database salts, account identifiers, and message paths in `dbkey` diagnostics.
+- Added `daily favorites` commands to synchronize and manage reader favorites as local files.
+- Added `vault promote ideas` and `vault promote all`; both default to no-AI local generation and require explicit opt-in for AI outputs.
+- Keep the default MCP surface read-only and require unique conversation-name resolution with bounded query limits.
+- Require preview and explicit confirmation for machine-driven messaging, configuration, access-control, todo, assistant lifecycle, MCP configuration, key reset, and Vault synchronization changes.
+- Require preview and explicit confirmation for Vault initialization, semantic indexing, knowledge pipelines, and report generation; expose no-AI/source filtering and strict bounded parameters for Agent use.
+- Validate local-reader ports before process startup and open browser URLs without shell interpolation.
+- Restrict MCP article fetching to bounded HTTPS requests on the exact WeChat article host, including redirect revalidation.
+- Validate outbound media files and remove full local paths from message previews and audit records.
+- Resolve bundled Python scripts consistently from both source and compiled package layouts, and propagate worker failures through nonzero exit codes.
+- Remove the ineffective `mcp-config --port` option; the MCP server uses stdio and does not bind a network port.
+- Reject absolute, non-Markdown, symlink-escaping, and parent-traversal entries in daily favorite state before linking or copying files.
+- Add preview, confirmation, and content-free JSON results to Vault content mutations, WeRead synchronization, daily favorites, and personal consumption reports.
+- Add preview and confirmation to Wiki compilation and AI todo extraction; keep process-memory key capture explicitly human-gated.
+- Add a machine-safe preview for database-key capture and require an interactive terminal for execution.
+- Add a content-free initialization preview while keeping actual database discovery and key capture human-gated.
+- Require preview and confirmation before Vault RAG reads local knowledge or sends selected context to AI.
+- Require preview and confirmation for semantic search and RAG chat, and keep their private inputs out of child-process arguments.
+- Keep report conversation selections and NT scan roots out of child-process arguments, and clear unrelated internal values from long-lived worker environments.
+- Require preview and confirmation for evidence review, with content-free and path-free machine results.
+- Reject unsupported WCDB query parameters instead of silently executing SQL without bindings.
+
+### Agent interfaces
+
+- Added `capabilities --json`, redacted configuration status, structured export results, reader status, diagnostics, access-list JSON, and no-AI daily JSON output.
+- Added the versioned `weflow-message/v1` contract to CLI exports and the read-only `wechat.export_messages` MCP tool for downstream projects.
+- Added conservative `coverage` metadata to versioned message exports and capability discovery, while preserving the legacy raw JSON array.
+- Added bounded local evidence-package and explicitly authorized evidence-review commands.
+- Applied message date ranges before pagination and preserved unknown message types in downstream contracts.
+- Added content-free JSON summaries for account scanning and assistant logs, plus structured todo reminders.
+- Added preview and confirmed background startup for Agent-controlled local daily readers.
+- Apply the same startup confirmation to the legacy `fav-server` compatibility command.
+- Require explicit confirmation for machine-driven daily generation, including no-AI runs, while preserving human and scheduled non-JSON commands.
+- Add content-free previews for configuration, key, access-list, and audit-log clearing before confirmed deletion.
+
+### Documentation and packaging
+
+- Added a unified Python dependency manifest for the standard Windows 4.x workflow and an optional legacy 3.x manifest.
+- Added MCP integration, contribution and security guidance.
+- Included README architecture assets and installation manifests in npm and portable releases.
+
+## 1.5.0
+
+### Added
+
+- Local reader dark mode, keyboard navigation and read/favorite tracking.
+- WeChat Moments local-cache commands and AI learning daily reports.
+- Improved knowledge-pipeline and reader workflows.
+
+For earlier history, see the [commit log](https://github.com/zhuobichen/weflow-cli/commits/master).

package/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing to WeFlow CLI
+
+Thanks for improving WeFlow CLI. This project handles local personal data, so correctness, privacy and reproducibility matter more than broad refactors.
+
+## Before opening an issue
+
+Include the command you ran, the operating system, Node.js and Python versions, the WeChat version, and a minimal reproduction. Remove names, wxid values, database paths, API keys, tokens, chat content and screenshots containing private data.
+
+For security-sensitive reports, use the process in [SECURITY.md](./SECURITY.md) instead of a public issue.
+
+## Development setup
+
+```powershell
+git clone https://github.com/zhuobichen/weflow-cli.git
+cd weflow-cli
+npm install
+python -m pip install -r requirements.txt
+npm run build
+```
+
+Use `npm run dev -- <command>` while developing. Run `npm run build` before opening a pull request.
+
+## Pull request guidelines
+
+- Keep pull requests focused on one user-visible change or repair.
+- Do not commit `.env`, `.mcp.json`, `output/`, databases, decrypted data, keys, tokens, chat exports or screenshots containing personal data.
+- Update README, setup instructions or command help when a workflow changes.
+- Explain the validation performed and any platform limitation in the pull request description.
+- Preserve Windows compatibility unless the change explicitly documents a supported-platform adjustment.
+
+## Documentation changes
+
+Keep documentation responsibilities separate:
+
+- `README.md`: product overview and shortest path to first use.
+- `docs/SETUP.md`: a complete fresh-machine installation.
+- `OPERATIONS.md`: maintenance and deep troubleshooting.
+- `docs/MCP.md`: MCP client integration and tool boundaries.
+- `docs/EVIDENCE_GUIDE.md`: evidence preservation and legal limitations.
+- `docs/PROJECT_STATE.md`: current baseline, verified capabilities and constraints.
+- `docs/DECISIONS.md`: durable design decisions and their consequences.
+- `ARCHITECTURE.md`: current module boundaries and data flows.
+- `OPERATIONS.md`: operational procedures and troubleshooting.
+
+Before opening a PR, verify command examples against `weflow-cli <command> --help`, update the relevant documentation in the same change, and run `npm run build`, `npm test`, and `git diff --check`. Do not use the changelog as an engineering diary.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 shixiansheng
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/OPERATIONS.md

@@ -0,0 +1,272 @@
+# WeFlow CLI 操作与排障手册
+
+本文面向用户和维护 Agent。所有命令都应在项目目录或已安装 CLI 的终端中执行；示例中的路径、联系人和密钥均为占位符。
+
+## 1. 环境
+
+| 依赖 | 用途 | 检查 |
+| --- | --- | --- |
+| Node.js 18+ | 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` |
+
+先运行：
+
+```powershell
+weflow-cli check
+```
+
+源码开发使用：
+
+```powershell
+npm install
+npm run build
+npm run dev -- check
+```
+
+## 2. 初始化与已有配置
+
+首次使用：
+
+```powershell
+weflow-cli init
+```
+
+初始化会发现常见数据位置、识别账号目录并验证本地数据库访问。默认优先复用已验证配置；配置有效时不会重复初始化。迁移、切换账号或访问失败时显式刷新：
+
+```powershell
+weflow-cli init --refresh
+```
+
+数据目录不在常见位置时按成本递增尝试：
+
+```powershell
+weflow-cli init --path "D:\WeChatData"
+weflow-cli init --search-drives
+weflow-cli init --full-scan
+```
+
+`--path` 可以指向微信数据根目录、账号目录或其 `db_storage` 目录。全盘结构搜索可能耗时较长，且会枚举更多本地目录，只有前两种方式找不到时再使用。
+
+测试“密钥缺失但不破坏当前配置”的首次初始化流程：
+
+```powershell
+weflow-cli init --test-missing-keys
+```
+
+确认密钥确实需要重新获取时，才使用：
+
+```powershell
+weflow-cli config forget-keys --yes
+weflow-cli init --refresh
+```
+
+## 3. 数据读取验证
+
+```powershell
+weflow-cli config show
+weflow-cli sessions -n 10
+weflow-cli contacts -k "关键词"
+weflow-cli messages "联系人A" -n 10
+```
+
+看到 `WCDB 初始化失败: -1006` 时，先不要反复登录或删除全部配置。先运行 `check`，确认 Python、数据路径和 NT 数据库状态；然后检查 `config show` 是否只显示“已设置”，不要把密钥复制到 Issue 或日志中。若配置失效，再按第二节执行 `init --refresh`。
+
+## 4. 导出聊天记录
+
+```powershell
+weflow-cli export "联系人A" html --output ./output
+weflow-cli export "联系人A" json --output ./output
+```
+
+支持 `json`、`txt`、`md`、`html` 和 `excel`。HTML 导出会尽力匹配本地图片、表情、公众号卡片和其他媒体；匹配不到时应显示类型或占位信息，不应从其他会话猜图。跨分片数据尤其要保留原始导出和完整上下文，导出后请人工抽查发送者、时间和媒体对应关系。
+
+### 导出耗时与远程媒体
+
+HTML 导出的时间几乎全部花在远程媒体上（公众号封面、B 站封面、表情 CDN）。这些结果按 URL 缓存在输出目录的 `.cover-cache/`，**成功和失败都会记**——多数是已失效的微信 CDN 链接，不记负结果的话每次重导都要把几百次请求重跑一遍。因此：
+
+- 同一会话的**重复导出接近瞬时**（实测 1614 条约 2 秒）；首次导出才是真正要付网络成本的。
+- 首次导出会先做一遍**只记录 URL、不联网**的扫描，再用 24 线程并发取回，最后用热缓存正式生成。逐条串行取回会慢一个数量级。
+- `.cover-cache/` 可以随时删除，删了只会退回「首次导出」的耗时，不会影响产出内容。
+- 原图（5–24MB/张）默认不嵌入，用微信缓存里的缩略图；确需原图时加 `--full-images`，代价是数分钟。
+
+### 图片显示为 `[图片]`、群聊看不出谁在说话
+
+导出会同时合并两个索引：**会话缓存**（`cache/YYYY-MM/Message/<会话md5>/`，只有最近几个月）和**账号媒体索引**（`msg/attach/<会话md5>/`，历史图片都在这里）。只有前者时，去年的群图片命中率是 0，全部退化成光秃秃的 `[图片]`。
+
+群聊的发言人从联系人库解析：**备注 > 昵称 > 别名**。都取不到时显示 wxid 本身——它仍能区分是谁，比留空或写群名有用。
+
+以下情况是**数据本身不在本机**，改代码也解决不了，导出会如实标注而不是猜：
+
+- 视频显示为 `[视频 10″]` 而没有封面图。微信只在视频被完整下载过之后才在本地留下封面（`msg/video/<月份>/<md5>_thumb.jpg`）；没下载过就没有，而 `cdnthumburl` 是加密标识、不是能直接下载的地址，离线拿不到。
+- 图片显示为 `[图片]` 且无图：该图片从未在这台设备上下载过。
+- `[位置]` 只有地名、没有地图：位置消息本身不携带地图图片。
+
+### 语音消息转文字
+
+HTML 里放不出语音：微信语音是 **SILK v3** 格式，浏览器不支持，ffmpeg 也没有 SILK 解码器（只有 AMR）。所以语音转文字是让语音消息在导出里能携带信息的唯一办法。
+
+**它是独立的、可断点续跑的一步，不在导出过程里。** 导出只读转写缓存；缓存没有的语音显示为 `[语音 6″]`。这样可以随时跑、随时停，跑过一遍就永久命中（按语音内容的 md5 缓存，同一条语音被转发到别处也只识别一次）。
+
+安装（可选，较重）：
+
+```powershell
+python -m pip install -r requirements-voice.txt
+```
+
+下载模型。**这一步对粤语是必须的**：原版 Whisper 遇到粤语会输出通顺但完全是编造的普通话——看着像真句子，实际什么都没说过，比不转写更危险。粤语微调版才转得出真正的粤语：
+
+```powershell
+$env:HF_ENDPOINT = "https://hf-mirror.com"; $env:HF_HUB_DISABLE_XET = "1"
+python -c "from huggingface_hub import snapshot_download; snapshot_download('alvanlii/whisper-small-cantonese', allow_patterns=['cts/*'], local_dir='models/whisper-small-cantonese')"
+```
+
+> `HF_HUB_DISABLE_XET=1` 是必需的：hf-mirror 不代理 HuggingFace 的 Xet 传输，不加会报 401。
+
+模型放好后会自动被优先使用（`models/whisper-small-cantonese/cts` 存在即可，该目录已在 `.gitignore` 中）。跑转写：
+
+```powershell
+python scripts/wechat_voice.py --db "<message_0.db>" --key <key> --salt <salt> `
+  --passphrase <passphrase> --talker "<会话id>" --cache-dir "output\.voice-cache"
+```
+
+- **有 NVIDIA GPU 时自动走 GPU**，约快 30 倍（实测 0.07 秒/条 vs 2.0 秒/条）；GPU 不可用则退回 CPU，不会报错。需要 `pip install nvidia-cublas-cu12 nvidia-cudnn-cu12`。
+- 语言**自动检测**。强制 `--language yue` 在粤语模型上会返回空，别加。
+- 中断后重跑会从缓存未命中的地方继续，不会从头再来。
+- 实测：1775 条语音（约 2.5 小时音频）全量约 9 分钟。
+
+> **⚠️ 粤语/方言的准确率有限，务必当作草稿。** 实测一个钦州/东兴一带的家族群
+> （疑为钦廉片白话）1777 条语音：模型输出的是**粤语形态的文字，但相当一部分句子
+> 意思不成立**——音对、词不对。公开的粤语微调模型基本训练于广府片（香港/广州话），
+> 与钦廉片差异明显，这很可能是主因。
+>
+> 排除了这些可能：SILK 解码（三种采样率结果一致、`\x02` 前缀处理无差别）、
+> 音频质量（峰值/RMS/过零率均为正常语音特征）、模型置信度（`avg_logprob` 中位
+> -0.25，模型对自己输出的内容很有把握——这恰恰说明它错得自信）。
+>
+> 因此导出的每条转写都标注「机器转写·粤语欠准」，页脚也写明**不可作为原话引用**。
+> 需要确证时以录音为准。若某个会话不需要转写，删掉输出目录下的 `.voice-cache`
+> 即可，导出会退回只显示 `[语音 N″]`。
+
+实测对比（同一条粤语语音）：
+
+| 设置 | 输出 |
+| --- | --- |
+| 原版 small，`zh` | 有些人在拍攝,我們都很懶拍七六歲 ← 编造 |
+| large-v3，自动检测 | `Các bạn hãy đăng ký kênh...` ← 幻觉成越南语 |
+| **粤语 small，自动检测** | 你所以東興人沒處來囉，東興人沒處來開囉 ← 正确识别出地名 |
+
+### 自定义表情包（表情包/贴纸）
+
+自定义表情包是 AES 加密的，密钥由一个**账号级 seed** 参与派生。该 seed 只存在于微信进程内存中：
+
+- 导出时如果 `emoticonSeed` 未配置，会自动扫描微信内存反推（用真实缓存文件验证，误报基本不可能），结果记在输出目录的 `.sticker-cache/seed`，只需扫一次。
+- 扫描要求**微信正在运行**，且账号曾在微信里查看过表情包。否则自定义表情包会退回 CDN 或显示为 `[表情]`（若其后紧跟图片，说明已渲染成功，`[表情]` 只是标签文字）。
+- 固化：`weflow-cli config set emoticonSeed <值>`，之后不再需要扫描。导出日志里会直接给出这条命令。
+- wxgf（H.265）贴纸需要 ffmpeg，由 `imageio-ffmpeg` 提供；缺失时这类贴纸无法解码。
+
+## 5. 公众号日报与阅读器
+
+生成今天的日报：
+
+```powershell
+weflow-cli daily
+```
+
+关闭本次运行的全部 AI：
+
+```powershell
+weflow-cli daily --no-ai
+```
+
+无日期运行会先补齐昨天的不完整产物；指定日期只处理该日期：
+
+```powershell
+weflow-cli daily --date YYYY-MM-DD --no-ai
+```
+
+只处理指定来源：
+
+```powershell
+weflow-cli daily --source "公众号A" --source "公众号B"
+weflow-cli daily --source "公众号A,公众号B"
+```
+
+仅预览来源文章，不写日报、不调用 AI：
+
+```powershell
+weflow-cli daily --dry-run
+```
+
+持久化来源和 AI 设置：
+
+```powershell
+weflow-cli config set dailySources "公众号A,公众号B"
+weflow-cli config set dailyAiEnabled false
+weflow-cli config set dailyAiEnabled true
+weflow-cli config show
+```
+
+来源类别配置使用 JSON；值可以是公众号名称或稳定来源 ID：
+
+```powershell
+weflow-cli config set dailySourceCategories '{"公众号A":"新闻","公众号B":"政治"}'
+```
+
+启动指定日期阅读器：
+
+```powershell
+weflow-cli daily-server --date YYYY-MM-DD --open
+```
+
+默认地址为 `http://127.0.0.1:8765/`。阅读器是本地服务，已生成的日报可离线阅读；文章正文、封面或图片的抓取可能需要联网。
+
+查看来源阅读频率：
+
+```powershell
+weflow-cli daily-stats --days 30 --limit 30
+```
+
+## 6. AI 和助手
+
+日报关闭 AI 不会自动关闭其他命令的 AI。报告、RAG、助手和证据线索分析分别按命令参数和配置决定是否调用模型。云端分析前应确认输入范围、供应商和隐私设置；优先使用本地模型处理聊天正文。
+
+助手基础配置：
+
+```powershell
+weflow-cli config set aiEngine ollama
+weflow-cli login-wechat
+weflow-cli assistant start
+weflow-cli assistant status
+```
+
+助手默认拒绝所有发送者，需明确设置 `assistantWhitelist`。群聊还需要群白名单、成员白名单和 @ 门槛；项目不通过客户端自动化或非官方协议拉群。
+
+## 7. 常见问题
+
+| 现象 | 处理 |
+| --- | --- |
+| 找不到数据目录 | 先 `init --path`，再 `--search-drives`，最后 `--full-scan`。 |
+| `Python not found` | 安装 Python 并确保当前 PowerShell 能执行 `python --version`。 |
+| 缺少 `sqlcipher3` 等依赖 | 用同一个 Python 执行 `python -m pip install -r requirements.txt`，再 `weflow-cli check`。 |
+| `WCDB ... -1006` | 检查 NT 配置和数据库路径，不要只看 WCDB 降级信息；必要时刷新初始化。 |
+| 日报缺昨天 | 无日期运行 `daily` 会检查并补齐昨天；补齐失败会停止今天，不覆盖失败状态。 |
+| `daily --dry-run` 不识别 | 确认使用的是当前源码或最新发布包；当前源码支持该参数，旧 npm 包可能落后。 |
+| 阅读器打不开 | 使用 `daily-server --date YYYY-MM-DD --open`，不要直接双击 `file://` 页面。 |
+| 图片或表情串错 | 保留原始数据库和导出日志，反馈脱敏后的消息类型、版本和最小复现；不要提交真实媒体。 |
+
+## 8. 安全排查原则
+
+不要在 Issue、PR、截图或共享日志中包含数据库、密钥、token、账号 ID、聊天正文或完整本地路径。公开报告只需操作系统、Node/Python 版本、微信版本、命令和脱敏错误。安全漏洞按 `SECURITY.md` 私下报告。
+
+## 9. 维护验证
+
+```powershell
+npm run build
+npm test
+python -m unittest discover -s test -p '*_test.py' -v
+git diff --check
+```
+
+测试优先使用合成数据。涉及真实账号时只做最小范围读取，并在完成后关闭本地服务和清理临时导出。