weflow-cli 1.10.0 → 1.11.1

package/CHANGELOG.md

@@ -17,6 +17,147 @@ purpose** - a hand-written "latest is X" is exactly the claim that goes stale he
 
 All notable user-facing changes are recorded here. This project follows [Semantic Versioning](https://semver.org/).
 
+## 1.11.1
+
+- **Five defects in 1.11.0's document export, all found by looking at a real export instead of the code.**
+  Re-exporting one 1,914-message conversation (29 documents on disk) and asking whether what got written can
+  actually be **opened** turned up two files that would have been unopenable in the reader's own editor:
+
+  1. A document whose name contains a half-width parenthesis - `…开题报告(2).pdf` - landed in the link target
+     as-is, and **every markdown renderer ends a target at the first `)`**, so the link stopped at `…报告(2`
+     and opened nothing. A space breaks it the same way (the target ends at whitespace). Targets are now
+     percent-encoded per path segment (`%282%29`, `%20`) while the link text stays the original name and
+     Chinese characters stay literal - `%E5%…` would be correct but unreadable.
+  2. The 80-character filename limit was applied to the whole name, so a long title lost its **extension**:
+     one file landed as `Chang 等 - 2022 - Environmental Justice Assessment of Fine Particles, Ozone, and`
+     with no `.pdf`, leaving the OS and every editor without a clue how to open it. The limit now applies to
+     the stem, with the extension kept.
+
+  Both were **invisible to the code and to the existing tests** - the first pass "worked" and produced a
+  complete-looking asset directory. Hunting for the rest of that class turned up three more:
+
+  3. **A filename containing a control character killed the whole export at the last step.** A tab in a message
+     title makes `open()` raise `OSError: Invalid argument` on Windows, and nothing caught it - minutes of
+     parsing and image extraction were thrown away by one bad name. Copy failures (bad name, path too long,
+     target locked) are now counted as `unavailable` instead. Control characters are also stripped from the
+     on-disk name, the link text, and `sanitize_filename` generally.
+  4. **Windows reserved device names** (`CON.pdf`, `NUL.txt`, `aux.docx`) cannot be created at all; they are now
+     prefixed with `_`. Checked alongside: 200-character titles, `[草稿]` brackets, `#`, `%`, quotes, emoji,
+     trailing dots, `|*?` - a battery of 21 real-world names, with every resulting link asserted to *resolve*.
+  5. **A narrower export silently erased a wider one's manifest.** The manifest lives in the shared
+     `<talker>_assets/` directory, so exporting the whole conversation and then running
+     `json --media --limit 600` into the same folder overwrote 585 entries with 150 - the wider run's documents
+     kept their links in the markdown but vanished from the manifest, and neither side reported anything. The
+     manifest is now **merged** with the existing one (entries whose file is gone are dropped), and it records
+     both `copied` (this run) and `exported` (present in the directory), because those were being conflated.
+
+  One more, not a defect but the same "silent" shape: `--media` together with `html` did nothing at all (HTML
+  writes no document bodies by design, so that is not a missing feature) and said nothing, which reads as a
+  broken switch. The CLI now names the reason and points at `md` / `json --media`.
+
+## 1.11.0
+
+- **Documents now travel with the export — all five formats, bodies included.** The same user report that asked
+  about images asked about *documents*; images got fixed, documents had not, and no format exported them (the page
+  showed `[文件] <name>` and stopped there). A file message carries only a name and an md5 — the body lives under
+  the account directory's `msg/file/` — so the export gained a **stat-only index** of that tree and matches on
+  `(normalized name, byte size)`, falling back to md5 only when several candidates share a name. Measured here:
+  1,855 file messages, 1,489 unique matches, 154 resolved by md5, **212 with no local copy** (never downloaded or
+  already cleaned) — **88.6%**, and the remaining 11.4% is *counted*, not guessed. Bodies are copied into
+  `<output>/<talker>_assets/files/` under their **original name and extension**, and markdown links to them by the
+  original file name (an image embed would render as a broken picture); `json`/`txt`/`excel` carry the same through
+  the manifest (`media` + `mediaKind`/`mediaName`, `[文件: name]`, the 「媒体」 column). HTML deliberately does not
+  embed them — base64-inlining a 3 MB PDF into a page nobody can open is not "supporting documents". Verified end
+  to end on a 600-message slice: 61 documents / 27 MB on disk, every extension matching its magic bytes, 63 links
+  in the markdown with no broken target, manifest and JSON agreeing on the same 58 entries (and 0 without
+  `--media`). The manifest is now `weflow-media-manifest/v2` (values are objects carrying `kind`); v1 files still
+  read, because nobody should have to re-export after an upgrade.
+
+  Two traps, both found by measuring instead of reasoning. First, a quoted reply keeps the quoted text in
+  `<refermsg>` — which sits **inside** `<appmsg>` — so it carries a nested `type=6` block with its own
+  `<title>`/`<appattach>`. The first pass searched the XML for the first matching tag and reported 7,083 "files",
+  nearly all of them quoted text; the parser now reads `<appmsg>`'s **direct children** only. Second, because a
+  re-run copies nothing new, a count of "files we wrote" read `0` on the second export into the same directory
+  while 67 documents sat on disk — the CLI said "0 document(s)". `exported` (is it there) and `written` (did we
+  copy it just now) are separate counts now. `--media` also stopped extracting the **whole** conversation while
+  the format it feeds was sliced by `--limit` (67 documents extracted, 33 of them used); it takes the same window.
+
+- **`export … json|txt|excel --media` puts the images in one command.** The markdown export is what extracts
+  media, so the other formats needed it run first - two steps, and a user who did not know that would see
+  `[图片]` and conclude the feature was missing. `--media` runs the same extraction (same Python path, same
+  `<output>/<talker>_assets/`, same manifest) and then writes the format it was asked for. Verified from a clean
+  state: one `export "…" json --media` produced the assets directory and a JSON in which 556 of 1,914 messages
+  carry their image's relative path.
+
+- **Animated GIFs survive every export path - and now the files say so.** Asked whether GIFs come through, the
+  answer was measured rather than assumed: of the 556 images in one real conversation, **87 are GIFs** (animated:
+  `NETSCAPE2.0` plus frame blocks) and 27 are PNGs, and both the markdown assets and the HTML embeds carried them
+  intact (`image/gif` ×87 in the page, 84 of them animated) - `wechat_image.shrink` has always passed *animated*
+  GIFs through untouched, precisely because a JPEG re-encode would show a still of what the sender saw moving.
+  What was wrong was the **file names**: the new markdown path hard-coded `.jpg`, so 87 GIFs and 27 PNGs landed as
+  `img_….jpg` - content right, extension lying, which is what an editor decodes by. The extension is now sniffed
+  from the bytes (`detect_mime_from_bytes`, which the script already had), so it is
+  `.gif`/`.png`/`.jpg`/`.webp` as appropriate: measured after the fix, the four formats agree exactly - 87 `.gif`,
+  27 `.png`, 442 `.jpg` references each (433 distinct jpg files, nine of them shared by two messages).
+
+- **`export … md` exists, and the other formats now carry the same images.** A user reported that only HTML
+  exported images; that was true, and the root cause was not a missing switch. Images are matched through the
+  cache/account indexes, and only the Python exporter did that - so the fix routes markdown through the same
+  Python path (`--format md`) instead of reimplementing the matching in TypeScript. Markdown **writes the images
+  out** to `<output>/<talker>_assets/` and references them relatively, because markdown's job is to be fed to
+  editors and other tools, where `![](data:image/…)` is not understood. That pass also writes
+  `manifest.json`, and `json` / `txt` / `excel` exports in the same directory now pick it up automatically
+  (a `media` field, `[图片: <path>]`, and a 「媒体」 column respectively) - **the matching runs once**, which is
+  the only way two implementations would not drift.
+
+  Two things surfaced while building it, both worth recording. First, the manifest was keyed by `local_id`, and
+  **`local_id` repeats across shards** (a conversation's table can exist in more than one shard, each numbering
+  its own rows): measured on a 1,914-message chat, 763 messages matched 522 entries, so the non-markdown formats
+  would have pointed at the wrong picture. Keyed by `local_id:create_time` now, and all four formats land on 556
+  (= the number of messages with an image). Second, when the Python export failed, the TypeScript side fell back
+  to the basic HTML renderer and the CLI still printed `✓ 导出成功` - a failure dressed as success (it was found
+  by asking for markdown and getting an `.html` file back). Markdown no longer has a silent fallback at all (there
+  is no "basic markdown"), and the HTML fallback now says on stderr that it dropped the images.
+
+- **The default semantic search path warned on stdout — and the warning was the important part.** `semantic_search.py`
+  has four `[WARN]` prints; three (the rerank ones) went to **stdout** while the rest already used
+  `file=sys.stderr`. Since `search` reranks by default, `search --json` answered with a line of prose *before* the
+  JSON and a machine caller got a parse error instead of results. Fixed, and the three paths now assert
+  `stdout == ''` in `test/semantic_rerank_test.py` — the two tests that already existed there asserted the warning
+  on **stdout**, i.e. they pinned the bug, so they were updated rather than duplicated beside them.
+
+  What the warning was saying, and why it stayed hidden for so long: on this machine the rerank layer **cannot run
+  at all** — `JevError … HTTP 451: Typesafe is not available in your region`. Rerank calls Typesafe
+  (`api.typesafe.ai`), a cloud decision service, not a local model, so on a geo-blocked machine the "default" path
+  is really the un-reranked one and the only signal was that stdout line. Two consequences are deliberately **not**
+  fixed here: the machine-readable result does not say the rerank failed (a degraded search is byte-identical to a
+  successful un-reranked one, because `rerank` returns just the list), and whether the index/rerank split is what
+  users should get on such a machine is a decision, not a patch. Both are written down in `docs/PROJECT_STATE.md`.
+
+- **The semantic index was built and used on a real machine for the first time** (2026-10-13, 7-day chat /
+  3-article window, 749 records, inside DashScope's free quota). The scoped search returns
+  `indexCounts: {all: 749, wiki: 383, chat: 366}` — the two lines add up to the whole index — and a query for
+  `开会` returns a chat message that says `…记得参加会议，8:30`: a semantic hit, not a keyword one. The default
+  90/30 window is still unbuilt (it would exceed the free quota; the measured cost is roughly ¥1.3–2.2).
+
+- **The semantic index would have embedded only the *older* part of its window, silently.** `semantic_search.py`
+  opened exactly one file — `config.ntDbPath` — with the account's global key. WeChat 4.x spreads messages across
+  shards and **each shard needs its own derived key**; the repo already had that path
+  (`nt_decrypt.connect_message_shards_detailed`, which also reports *which* shards failed). Measured here on
+  2026-10-13 before the fix: the configured `message_0.db` holds 67,292 messages whose newest is **2026-08-30**,
+  while `message_3.db` holds 16,081 whose newest is **that same day's date** — so a build would have indexed 1,396
+  chat messages and **nothing newer than six weeks ago**, missing 5,217 that a correct read finds in the same
+  90-day window (7-day window: 0 → 376). Three quieter losses went with it: the session list was `[:100]` —
+  unsorted, so effectively arbitrary, on a machine with 122 sessions; the id was `chat:<talker>:<ts>`, which merges
+  messages inside one second (measured: 12,106 rows on 12,058 distinct seconds); and one conversation's table can
+  exist in several shards, so a shared id would double-count. The build result now reports `shardsFailed`, because
+  "read everything" and "read what happened to be reachable" must not look alike.
+
+  `test/semantic_shards_test.py` pins each of the three with fake shard connections (no sqlcipher, no real vault),
+  and all three mutations — single shard, no-rowid id, `[:100]` — turn their own test red. **This is also why the
+  index is still not built**: building it first would have spent the embedding budget on a month the user is not
+  asking about. Closing that now costs one `search-index --yes` once `dashscopeApiKey` is set.
+
 ## 1.10.0
 
 - **`mcp-config --json-result` printed a tool list *after* the JSON.** Its read path printed the config JSON and

package/OPERATIONS.md

@@ -86,7 +86,42 @@ weflow-cli export "联系人A" html --output ./output
 weflow-cli export "联系人A" json --output ./output
 ```
 
-支持 `json`、`txt`、`md`、`html` 和 `excel`。HTML 导出会尽力匹配本地图片、表情、公众号卡片和其他媒体；匹配不到时应显示类型或占位信息，不应从其他会话猜图。跨分片数据尤其要保留原始导出和完整上下文，导出后请人工抽查发送者、时间和媒体对应关系。
+支持 `json`、`txt`、`html`、`md` 和 `excel` 五种。**媒体匹配只做一遍**：`md` 导出是那个"抽取者"——
+图片落盘到 `<输出>/<会话>_assets/`、**文档本体按原名与扩展名拷进 `<会话>_assets/files/`**，同时写一份
+`manifest.json`；随后在同一输出目录里导出 `json`/`txt`/`excel`，它们会**自动**带上同样的路径（`json`
+每条多 `media`，文档还多 `mediaKind`/`mediaName`；`txt` 里是 `[图片: <相对路径>]` / `[文件: 名字 (路径)]`；
+`excel` 多一列「媒体」）。**不想分两步就给 `--media`**：`json`/`txt`/`excel` 会先自己抽一次（同一份清单，
+且**吃同一个 `--limit`/`--date`**），命令只有一条：
+`weflow-cli export "某人" json --media`。没跑过 `md` 导出也没给 `--media` 时，这三种格式与从前一致
+（图片位置是 `[图片]` 这样的占位）。清单的键是 `local_id:create_time` —— **`local_id` 会在分片之间重复**（同一会话
+的表可能存在于多个分片、各片自己编号），只按它会引用到别的消息的图。清单 schema 是 `weflow-media-manifest/v2`
+（值是带 `kind` 的对象）；磁盘上留着的 v1（裸字符串）仍读得出来，升级不必重跑导出。
+
+**文档本体是纯拷贝，不重编码、不改名**（只清洗文件名里的非法字符）。消息里只有名字与 md5，文件在账号目录的
+`msg/file/YYYY-MM/` 下，按 `(归一化名, 字节数)` 对上，同名多份时用 md5 定。本机实测 1,855 条文件消息里
+**1,643 条对得上（88.6%）**，其余 212 条本地确实没有那份文件（没下载过或已清理）—— 这些消息仍是
+`[文件] 名字` 的标签，不清单里凑数、也不猜。导出的计数里 `exported` 是"这份文档在 assets 里"，
+`written`（清单里叫 `documents.copied`）才是"这次新拷了几个"，别把后者当成前者的成绩。
+另外 `--media` 配 `html` 不生效（HTML 不写文档本体），CLI 会提示一句而不是静默忽略。
+
+md 里指向文档的链接**把路径里的空格、括号等字符做了百分号编码**（如 `报告%282%29.pdf`），链接文字仍是原名。
+这不是洁癖：文档名里带半角括号时（`报告(2).pdf` 这种），链接目标会被任何 markdown 渲染器在**第一个 `)`
+处截断**，点开是空的（2026-10-13 重导时实测到；同一批里还有一份超长标题被 80 字符上限连 `.pdf` 一起截掉，
+落成一个没有扩展名的文件——那条也修了）。
+
+**HTML 导出（含 `--full-images`）不写文件本体**：HTML 的用法是"单文件可分享"，把几 MB 的 PDF 内嵌成
+base64 既没人打得开、也把网页撑大。要在文件本体上要文档，用 `md` 或 `json|txt|excel --media`。
+（`--media` 会把文档拷进输出目录，几百份的时代价几十到几百 MB，先看一眼 `msg/file` 的规模再按整段历史跑。）
+
+**动图（GIF）会照原样带出来**：落盘的文件名按**字节**定扩展名（`.gif`/`.png`/`.jpg`/`.webp`），内容不动 ——
+实测一段真实会话里 556 张图有 87 个是 GIF（带动画扩展的 84 个），markdown 里就是 `.gif`、HTML 里是
+`data:image/gif`。`--full-images` 那档也**不会**把动画 GIF 压成静态图（`wechat_image.shrink` 对动画 GIF
+直接原样穿过，理由写在它的注释里：PIL 只解第一帧，重编码会把"发的人看到在动"变成一张静止图）。
+
+HTML 导出会尽力匹配本地图片、表情、公众号卡片和其他媒体（内嵌，单文件可分享，并给出一份媒体覆盖报告）；
+匹配不到时应显示类型或占位信息，不应从其他会话猜图。`.pdf`/`.docx` 这类文件消息在 HTML 里是一张标题卡片
+（HTML 刻意不嵌文件本体，理由见上一段）；文件本体走 `md` 或 `--media`。跨分片数据尤其要保留
+原始导出和完整上下文，导出后请人工抽查发送者、时间和媒体对应关系。
 
 ### 导出耗时与远程媒体
 
@@ -95,7 +130,10 @@ HTML 导出的时间几乎全部花在远程媒体上（公众号封面、B 站
 - 同一会话的**重复导出接近瞬时**（实测 1614 条约 2 秒）；首次导出才是真正要付网络成本的。
 - 首次导出会先做一遍**只记录 URL、不联网**的扫描，再用 24 线程并发取回，最后用热缓存正式生成。逐条串行取回会慢一个数量级。
 - `.cover-cache/` 可以随时删除，删了只会退回「首次导出」的耗时，不会影响产出内容。
-- 原图（5–24MB/张）默认不嵌入，用微信缓存里的缩略图；确需原图时加 `--full-images`，代价是数分钟。
+- 默认嵌入的是微信缓存里的**缩略图**；加 `--full-images` 会改用**原图作为来源**（原图常有 5–24MB、3000+px，
+  `wechat_image.shrink` 处理它们要数分钟）。**两档嵌入前都会按上限缩放**，所以导出物体积不会因为这一档变成几百 MB
+  ——2026-10-13 实测同一会话两档：HTML 体积 2.0 MB vs 1.5 MB、图片像素分布基本一致（`--full-images` 让 4 张的来源
+  从缓存缩略图换成了原图 ⇒ 720px 的那批从 10 张变成 14 张）。它的价值在**那几张缩略图本来就小**的会话上。
 
 ### 图片显示为 `[图片]`、群聊看不出谁在说话
 

package/README.md

@@ -92,7 +92,7 @@ Linux 的自动初始化能力取决于微信发行版、Python 依赖和当前
 
 | 场景 | 能力 |
 | --- | --- |
-| 聊天记录 | 查询会话、联系人和消息；导出 JSON、TXT、HTML、Excel。HTML 导出会同时给出一份媒体覆盖报告，说明哪些图片/表情没能嵌入以及原因。 |
+| 聊天记录 | 查询会话、联系人和消息；导出 **Markdown / JSON / TXT / HTML / Excel**。Markdown 导出把图片**落盘**到 `<会话>_assets/`、正文用相对路径引用（喂给编辑器或别的工具时这才是能用的形态）；**文档本体**（微信里的 Word/Excel/PDF/PPT 等）按原名与扩展名拷进 `<会话>_assets/files/`，正文里按原名链接到 `files/` 下；HTML 导出内嵌图片并给出一份媒体覆盖报告（哪些没嵌上、为什么）。**匹配只做一遍**：Markdown 导出写下清单，之后 JSON/TXT/Excel 导出（或 `--media`）会自动带上同样的图片与文档路径。 |
 | 公众号日报 | 抓取文章、AI 摘要与分类、生成本地阅读页，保留收藏和已读状态。 |
 | 个人知识库 | 同步微信读书笔记、构建 Obsidian Vault、语义搜索、RAG 问答和概念 Wiki，以及**双击就能打开**的概念图谱页面（`weflow-cli wiki graph --open` 出 3D、加 `--flat` 出 2D；自包含、不联网、不需要服务器；`--min-degree N` 只看枢纽、`--line wiki\|chat` 只看一条线）。 |
 | AI 协作 | 通过 MCP 把文章、知识库、日报和受控的本地数据能力交给兼容客户端；工具清单以 `weflow-cli mcp-config` 和 `docs/MCP.md` 为准。 |
@@ -158,7 +158,7 @@ weflow-cli messages "联系人" -n 10
 weflow-cli export "联系人" html --output ./output
 ```
 
-HTML 导出默认内嵌微信缓存里的缩略图，并尽力还原图片、表情包、系统消息和公众号卡片。远程媒体按 URL 缓存在输出目录的 `.cover-cache/`，所以**重复导出接近瞬时**（实测 1600+ 条约 2 秒），首次导出才需要联网。自定义表情包从本地缓存离线解密，seed 未配置时会自动扫描微信内存反推并提示固化命令。确需原图（5–24MB/张）时加 `--full-images`，代价是慢数倍。细节见[操作与排障手册](./OPERATIONS.md#4-导出聊天记录)。
+HTML 导出默认内嵌微信缓存里的缩略图，并尽力还原图片、表情包、系统消息和公众号卡片。远程媒体按 URL 缓存在输出目录的 `.cover-cache/`，所以**重复导出接近瞬时**（实测 1600+ 条约 2 秒），首次导出才需要联网。自定义表情包从本地缓存离线解密，seed 未配置时会自动扫描微信内存反推并提示固化命令。想改用**原图作为来源**时加 `--full-images`（原图常有 5–24MB/张，处理它们会慢数倍；**嵌入前仍按上限缩放**，所以导出物不会因此变大成几百 MB，实测两档体积相当）。细节见[操作与排障手册](./OPERATIONS.md#4-导出聊天记录)。
 
 **生成当天公众号日报**
 

package/bin/weflow-cli.ts

@@ -1821,8 +1821,9 @@ program
   .option('--json', '输出机器可读的导出结果，不改变导出文件格式')
   .option('--non-interactive', '禁止交互选择；匹配不唯一时返回错误')
   .option('--full-images', '使用原图而非微信缓存缩略图（更清晰，但导出慢数倍）')
+  .option('--media', 'json/txt/excel 导出时一并抽出图片与文档（落盘到 <输出>/<会话>_assets，并在导出物里给出相对路径）')
   .action(async (talkerInput: string, format: string, opts) => {
-    const validFormats = ['json', 'txt', 'html', 'excel']
+    const validFormats = ['json', 'txt', 'html', 'md', 'excel']
     if (!validFormats.includes(format)) {
       if (opts.json) console.log(JSON.stringify({ success: false, code: 'INVALID_FORMAT', error: '导出格式无效', supported: validFormats }))
       else {
@@ -1871,6 +1872,23 @@ program
       }
       process.exit(1)
     }
+    // 图片要靠 Python 那条路匹配（缓存缩略图、资源 md5、原图那档）。`--media` 就是"先抽一次"，
+    // 抽完 json/txt/excel 各自消费同一份清单 —— 匹配只跑一遍，也不会在 TS 里重写一遍。
+    if (opts.media && (format === 'json' || format === 'txt' || format === 'excel')) {
+      const media = await exportService.extractMedia(talker, opts.output, !!opts.json, { fullImages: opts.fullImages === true }, limit, opts.date || '')
+      if (!media.success) {
+        if (opts.json) console.log(JSON.stringify({ success: false, code: 'MEDIA_EXPORT_FAILED', error: media.error || '媒体抽取失败' }))
+        else console.log(chalk.red(`✗ 媒体抽取失败: ${media.error}`))
+        process.exit(1)
+      }
+    } else if (opts.media && format === 'html') {
+      // HTML 的用法是"单文件可分享"，所以它不写文档本体（把几 MB 的 PDF 内嵌进网页，既打不开也把文件撑大）。
+      // 静默忽略这个开关会让人以为它生效了 —— 明说一句，并给出该用哪个格式。
+      if (!opts.json) {
+        console.error(chalk.gray('  提示：HTML 导出不含文档本体（单文件分享的用法），--media 对它不生效；'))
+        console.error(chalk.gray('        要连文档一起导出请用 md，或 json|txt|excel --media。'))
+      }
+    }
     switch (format) {
       case 'json':
         result = await exportService.exportJson(talker, opts.output, limit, from, to, opts.contract)
@@ -1881,6 +1899,10 @@ program
       case 'html':
         result = await exportService.exportHtml(talker, opts.output, limit, opts.date || '', from, to, !!opts.json, { fullImages: opts.fullImages === true })
         break
+      case 'md':
+        // markdown + 图片落盘（`<输出>/<talker>_assets/`）；json/txt/excel 之后会自动带上那些图。
+        result = await exportService.exportMarkdown(talker, opts.output, limit, opts.date || '', from, to, !!opts.json, { fullImages: opts.fullImages === true })
+        break
       case 'excel':
         result = await exportService.exportExcel(talker, opts.output, limit, from, to)
         break

package/dist/bin/weflow-cli.js

@@ -1845,8 +1845,9 @@ program
     .option('--json', '输出机器可读的导出结果，不改变导出文件格式')
     .option('--non-interactive', '禁止交互选择；匹配不唯一时返回错误')
     .option('--full-images', '使用原图而非微信缓存缩略图（更清晰，但导出慢数倍）')
+    .option('--media', 'json/txt/excel 导出时一并抽出图片与文档（落盘到 <输出>/<会话>_assets，并在导出物里给出相对路径）')
     .action(async (talkerInput, format, opts) => {
-    const validFormats = ['json', 'txt', 'html', 'excel'];
+    const validFormats = ['json', 'txt', 'html', 'md', 'excel'];
     if (!validFormats.includes(format)) {
         if (opts.json)
             console.log(JSON.stringify({ success: false, code: 'INVALID_FORMAT', error: '导出格式无效', supported: validFormats }));
@@ -1899,6 +1900,26 @@ program
         }
         process.exit(1);
     }
+    // 图片要靠 Python 那条路匹配（缓存缩略图、资源 md5、原图那档）。`--media` 就是"先抽一次"，
+    // 抽完 json/txt/excel 各自消费同一份清单 —— 匹配只跑一遍，也不会在 TS 里重写一遍。
+    if (opts.media && (format === 'json' || format === 'txt' || format === 'excel')) {
+        const media = await exportService.extractMedia(talker, opts.output, !!opts.json, { fullImages: opts.fullImages === true }, limit, opts.date || '');
+        if (!media.success) {
+            if (opts.json)
+                console.log(JSON.stringify({ success: false, code: 'MEDIA_EXPORT_FAILED', error: media.error || '媒体抽取失败' }));
+            else
+                console.log(chalk.red(`✗ 媒体抽取失败: ${media.error}`));
+            process.exit(1);
+        }
+    }
+    else if (opts.media && format === 'html') {
+        // HTML 的用法是"单文件可分享"，所以它不写文档本体（把几 MB 的 PDF 内嵌进网页，既打不开也把文件撑大）。
+        // 静默忽略这个开关会让人以为它生效了 —— 明说一句，并给出该用哪个格式。
+        if (!opts.json) {
+            console.error(chalk.gray('  提示：HTML 导出不含文档本体（单文件分享的用法），--media 对它不生效；'));
+            console.error(chalk.gray('        要连文档一起导出请用 md，或 json|txt|excel --media。'));
+        }
+    }
     switch (format) {
         case 'json':
             result = await exportService.exportJson(talker, opts.output, limit, from, to, opts.contract);
@@ -1909,6 +1930,10 @@ program
         case 'html':
             result = await exportService.exportHtml(talker, opts.output, limit, opts.date || '', from, to, !!opts.json, { fullImages: opts.fullImages === true });
             break;
+        case 'md':
+            // markdown + 图片落盘（`<输出>/<talker>_assets/`）；json/txt/excel 之后会自动带上那些图。
+            result = await exportService.exportMarkdown(talker, opts.output, limit, opts.date || '', from, to, !!opts.json, { fullImages: opts.fullImages === true });
+            break;
         case 'excel':
             result = await exportService.exportExcel(talker, opts.output, limit, from, to);
             break;