---
title: "Markdown 转 EPUB（ebook-convert/Calibre）可复现执行文档"
asset_id: "ASSET-EPUB-MD2EPUB-20260225-3c7a9d1e"
version: "v1.0"
date: "2026-02-25"
maintainer: "<占位符>"
scope:
  - "Windows 环境下单个 Markdown 转 EPUB"
  - "以 Calibre ebook-convert 为核心的可复现转换流程（含证据与自检）"
non_scope:
  - "复杂排版需求（大量公式/引用文献/高级 Markdown 扩展）"
  - "DRM/受保护格式处理与分发合规审查"
min_input:
  - "Markdown 文件路径（绝对路径或相对路径）"
  - "书籍元数据（标题/作者/语言，可自动从 Markdown 头部提取）"
output_spec:
  deliverable_type: "EPUB 文件（主交付物）+ 可追溯证据（版本/日志/报告）"
  must_include:
    - "输出 EPUB 文件路径（可直接打开验证）"
    - "关键证据：工具版本、转换命令、转换日志/报告、自检结论"
  quality_bar:
    - "EPUB 可被 Calibre 或常见阅读器打开，且目录（NCX/NAV）存在"
    - "转换无 ERROR，输出文件大小非空且显著大于 0（建议 > 10KB）"
change_log:
  - ver: "v1.0"
    date: "2026-02-25"
    changes: "初始化"
tags:
  - "calibre"
  - "ebook-convert"
---

<!-- markdownlint-disable MD013 -->

## Markdown 转 EPUB（ebook-convert/Calibre）可复现执行文档

## 上下文背景（任务上下文源）

### 2.1 当前任务一句话背景

- 将 `C:\Users\lenovo\Downloads\逻辑 - 孟自黄.md` 转换为 EPUB，并完成工具选型与可复现构建（最终选用 Calibre `ebook-convert`）。

### 2.2 业务/项目背景要点（可选）

- 无/不适用

### 2.3 会话上下文源定义（默认信息源与优先级）

#### 2.3.1 信息源优先级（从高到低）

1. 会话内用户明确提供/确认的信息（含粘贴文本/附件/链接）
1. 会话内 AI 已执行得到的证据（命令输出/读到的文件片段）
1. 本地工作区文件与仓库（如存在）
1. 外部来源（仅限用户提供链接；若允许检索则必须记录链接与摘录为证据）
1. 必要时向用户提最少问题补齐

#### 2.3.2 工作目录/项目根定位规则（按需）

- 默认以会话提供的 `cwd` 作为工作目录；若输入为绝对路径，则以 Markdown 所在目录作为 `source-root`（用于解析本地资源）。

#### 2.3.3 关键文件/目录（README等）

- `C:\Users\lenovo\Downloads\逻辑 - 孟自黄.md`
- `C:\Users\lenovo\Downloads\逻辑 - 孟自黄.epub`
- `C:\Users\lenovo\Downloads\build_epub\report.json`
- `C:\Users\lenovo\.codex\skills\markdown-to-epub\scripts\build_epub.py`

#### 2.3.4 Git 状态/变更/提交历史（按需）

- 不适用（本任务不依赖 Git；如在仓库内执行，提交/推送/合并属于高风险动作，必须先请求用户批准）

#### 2.3.5 日志/配置/脚本/依赖信息

- 工具：Calibre `ebook-convert`（证据：`ebook-convert --version` 输出 `calibre 8.16.2`）
- 运行时：Python（证据：`python --version` 输出 `Python 3.14.2`）
- 可选工具：Pandoc（证据：`pandoc --version` 在本会话环境中不可用/未安装）
- 构建脚本（可选但推荐）：`C:\Users\lenovo\.codex\skills\markdown-to-epub\scripts\build_epub.py`（对本地图片与证据报告更友好；底层仍调用 `ebook-convert`）

#### 2.3.6 外部来源使用规则（按需）

- 默认仅用用户提供链接；本任务未使用外部链接检索

### 2.4 关键约束/假设（可选）

- 约束：尽量不改动源 Markdown；输出文件可覆盖需先征得用户同意
- 假设：输入 Markdown 为 UTF-8（本会话证据：用 `utf-8/utf-8-sig` 可正确解码，`gb18030/gbk/big5` 解码失败）

## 任务方法（可复现执行体：复制即让 AI 照着跑，必须可复现）

### A. 目标 & 成功标准

- 目标：将指定 Markdown 转为 EPUB（使用 `ebook-convert`），并落盘可追溯证据（版本/日志/报告/自检结论）
- 成功标准：
  - [ ] 产出 EPUB 文件，路径明确且可打开
  - [ ] EPUB 包含 OPF 且存在 NCX 或 NAV（目录可用）
  - [ ] 元数据（标题/作者/语言）正确
  - [ ] 关键内容结构不丢失（至少校验：章节标题与表格/段落）

### B. 复现总规则

- 少问用户、优先补齐；高风险先批准；每步记录证据；可回滚

### C. 复现主流程（Replay Workflow）

> 必须包含 Step1~Step6；每个 Step 严格按：输入→动作→证据→输出→自检→兜底

#### Step1 定位上下文

- 输入：
  - Markdown 路径："<输入 Markdown 路径>"
  - 工作目录（若给出）："<cwd 或占位符>"
- 动作（命令/读文件/搜索）：
  - 在 PowerShell 中确认文件存在：
    - `Test-Path -LiteralPath "<输入 Markdown 路径>"`
  - 读取开头 60 行用于提取标题/作者（注意编码）：
    - `Get-Content -LiteralPath "<输入 Markdown 路径>" -Encoding utf8 -TotalCount 60`
- 证据：
  - 记录 `Test-Path` 结果（True/False）
  - 记录前 60 行中是否存在 `# <标题>`、`**作者**：<作者>` 等可提取信息
- 输出：
  - 输入文件绝对路径
  - 可能的元数据候选：标题/作者/语言（若可从 Markdown 头部提取）
- 自检：
  - 若 `Get-Content` 输出乱码，优先改用 `-Encoding utf8`；仍异常则进入 Step2 做编码确认
- 兜底：
  - 若文件不存在：请求用户确认路径或提供文件
  - 若路径含空格/特殊字符：所有命令统一使用 `-LiteralPath` 或对参数加双引号

#### Step2 自动补全

- 输入：
  - Step1 的元数据候选（可能为空）
- 动作（命令/读文件/搜索）：
  - 检查 `ebook-convert` 是否可用并记录版本：
    - `ebook-convert --version`
  - （可选）检查 `pandoc` 是否可用（仅用于信息收集，不作为主路径）：
    - `pandoc --version`
  - 如需确认编码（推荐仅在出现乱码/异常时做）：
    - 运行 Python 尝试以 UTF-8 解码并打印前几行（示例）：
      - `@' ... '@ | python - "<输入 Markdown 路径>"`
- 证据：
  - `ebook-convert --version` 输出（例如：`ebook-convert.exe (calibre 8.16.2)`）
  - `pandoc --version` 输出或失败信息（若失败也需记录）
  - 编码确认输出（例如：`utf-8 -> # 逻辑 | **作者**：孟自黄 ...`）
- 输出：
  - 最终采用的工具与路径：优先 `ebook-convert`（Calibre）
  - 最终元数据：标题/作者/语言（无法自动提取则保留 `<占位符>` 待用户确认）
- 自检：
  - 若 `ebook-convert` 不可用：进入 E.4（环境异常）
- 兜底：
  - 若元数据无法自动提取：仅向用户提最少问题（标题/作者/语言）

#### Step3 计划

- 输入：
  - 输入 Markdown 路径
  - 输出 EPUB 目标路径（若未指定则默认与输入同目录/同名）
  - 元数据（标题/作者/语言）
- 动作（命令/读文件/搜索）：
  - 明确两条执行路径（按内容复杂度择一）：
    - 路径 A（最小路径）：直接调用 `ebook-convert` 生成 EPUB
    - 路径 B（稳健路径，仍以 `ebook-convert` 为核心）：使用构建脚本生成报告与可追溯证据（适合有本地图片/需要报告/需要更强可复跑性）
  - 检查是否会覆盖文件/删除目录（不可逆需先批准）：
    - 若输出 EPUB 已存在：必须先问用户是否覆盖
    - 若要清理构建目录（例如 `build_epub`）：必须先问用户是否允许删除
- 证据：
  - 记录用户对“覆盖/清理”的明确批准或拒绝
  - 记录最终选择的执行路径（A 或 B）及理由（1 句话）
- 输出：
  - 可执行命令（单条或两条）+ 预计输出路径
- 自检：
  - 命令必须非交互式；路径包含空格时必须加引号
- 兜底：
  - 若用户拒绝覆盖：改用新文件名（例如追加日期或版本号）
  - 若用户拒绝清理：禁用清理参数，改为新建 build 目录（例如 `build_epub_<YYYYMMDDHHMM>`）

#### Step4 执行取证

- 输入：
  - 最终确认的执行路径（A 或 B）
  - 输出 EPUB 路径
  - 元数据（标题/作者/语言）
- 动作（命令/读文件/搜索）：
  - 路径 A（直接转换）示例：
    - `ebook-convert "<输入 Markdown 路径>" "<输出 EPUB 路径>" --title "<标题>" --authors "<作者>" --language "<语言>"`
  - 路径 B（稳健转换，底层仍用 ebook-convert；推荐用于留证与处理本地资源）示例：
    - `python "C:/Users/lenovo/.codex/skills/markdown-to-epub/scripts/build_epub.py" --input-md "<输入 Markdown 路径>" --output-epub "<输出 EPUB 路径>" --title "<标题>" --authors "<作者>" --language "<语言>" --clean-build-dir`
  - 注意：`--clean-build-dir` 会删除构建目录，属于不可逆动作；执行前必须有用户批准
- 证据：
  - 记录完整命令行（含所有参数）
  - 记录命令输出（stdout/stderr）与生成的日志/报告路径
  - 本会话转换成功证据（示例摘要，供对照）：

    ```json
    {
      "output_epub": "C:\\Users\\lenovo\\Downloads\\逻辑 - 孟自黄.epub",
      "build_dir": "C:\\Users\\lenovo\\Downloads\\build_epub",
      "total_image_refs": 0,
      "missing_images": [],
      "epub": {
        "file_size": 158236,
        "has_opf": true,
        "has_ncx_or_nav": true,
        "ncx_nav_points": 58
      }
    }
    ```

- 输出：
  - 生成的 EPUB 文件（路径）
  - （若路径 B）构建目录与报告：`build_epub\report.json`、`build_epub\conversion.log`
- 自检：
  - 校验输出文件存在且大小合理（建议 > 10KB）
- 兜底：
  - 若转换失败：收集错误信息并进入 E.4
  - 若提示编码相关问题：优先确保输入为 UTF-8 或在工具侧指定编码/改用稳健路径 B

#### Step5 自检验收

- 输入：
  - 输出 EPUB 路径
  - （若有）报告 JSON 路径
- 动作（命令/读文件/搜索）：
  - 最小自检（结构完整性）：
    - （路径 B 已自动生成）检查 `report.json` 中 `has_opf`、`has_ncx_or_nav`、`missing_images`
  - 内容自检（抽样验证关键文本存在）示例：
    - 用 Python 读取 EPUB（zip）并搜索标题/作者/关键句：
      - 搜索 `"逻辑"`、`"孟自黄"` 是否在 HTML 中出现
  - 表格自检（如 Markdown 含表格）：
    - 搜索表格关键行是否被转换为 `<table>`（例如包含 `"妥善处理污水"` 的表格）
- 证据：
  - 本会话自检证据（示例）：
    - 在 EPUB 内找到标题与作者：`found in index_split_000.html`
    - 表格存在：`has_table True`，`tr_count 6`
- 输出：
  - 验收结论（通过/不通过）+ 不通过原因（若有）
- 自检：
  - 若发现目录缺失、章节结构异常：回到 Step3 调整分章/目录策略（必要时改用稳健路径 B）
- 兜底：
  - 若阅读器显示乱码：优先确认输入/转换链路全程 UTF-8，并检查语言参数（`--language "zh-CN"`）

#### Step6 交付落盘更新

- 输入：
  - 最终通过验收的 EPUB 文件
  - 证据材料（命令输出/日志/报告/自检结论）
- 动作（命令/读文件/搜索）：
  - 交付文件落盘（若需归档目录，先确认目标路径存在）：
    - 将 EPUB 与证据文件（`report.json`、`conversion.log`）复制到用户指定目录
  - 更新本资产文档（如复跑后遇到新分支/新坑）：
    - 版本号 `v1.0 -> v1.1`，并在 `change_log` 新增一条记录
- 证据：
  - 记录最终交付路径清单（EPUB + 报告/日志）
  - 记录校验结论（Step5 输出）
- 输出：
  - 最终交付物路径列表
- 自检：
  - 确保交付路径下文件齐全且可打开
- 兜底：
  - 若用户不需要报告/日志：至少保留 `ebook-convert --version` 与最终命令行作为最小证据

### D. 固定步格式（强制约束）

- 每步必须且仅包含：输入 / 动作 / 证据 / 输出 / 自检 / 兜底

### E. 必要分支

#### E.1 信息不足

- 触发条件：
  - 无法从 Markdown 头部可靠提取标题/作者/语言，或用户未提供输出路径与覆盖策略
- 最小问题集（最多 3 个）：
  1. 输出 EPUB 文件名/路径是否固定？若已存在是否允许覆盖？
  1. 书籍元数据：标题、作者（语言默认 `zh-CN` 是否接受）？
  1. 是否需要生成/保留证据（report/log）用于复跑与追溯？
- 默认策略（用户不回时）：
  - 不覆盖任何既有文件；输出文件名追加日期；语言默认 `zh-CN`；保留最小证据（版本+命令行）

#### E.2 信息冲突

- 触发条件：
  - 标题/作者在文件头部与用户口述不一致；或同名输出文件存在但覆盖策略不明确
- 冲突点清单：
  - "<占位符>"
- 推荐决策与理由：
  - 以“用户明确确认”的元数据为准；若未确认，以 Markdown 文件头部为准（并在交付中标注来源）
- 需要用户批准的选项：
  - 覆盖现有输出文件
  - 删除/清理构建目录（如 `--clean-build-dir`）

#### E.3 时间紧（先交付 MVP）

- 触发条件：
  - 用户只要尽快拿到可读 EPUB，不要求详尽证据或复杂校验
- MVP 交付定义：
  - 直接 `ebook-convert` 生成 EPUB；仅做“能打开 + 目录存在 + 标题/作者正确”的最小自检
- 后续迭代清单：
  - 增加报告落盘（report/log）
  - 增加内容抽样自检（关键章节/表格/脚注）
  - 增加图片资产归一化（若后续出现本地图片）

#### E.4 命令失败/环境异常

- 触发条件：
  - `ebook-convert` 不存在/不可执行；转换报错；输出 EPUB 不生成或损坏
- 诊断步骤：
  1. `ebook-convert --version` 是否可用
  1. 记录完整错误输出（stderr）
  1. 检查输入文件编码与路径（空格/中文/权限）
  1. 若为资源问题（图片缺失）：改用稳健路径 B 并查看 `missing_images`
- 回退/替代方案：
  - 安装/修复 Calibre 后重试
  - 不清理构建目录，换新 build 目录与新输出名避免破坏现有文件
- 需要用户提供的信息（最少）：
  - 错误输出全文
  - 输入 Markdown 路径与（若有）相关资源文件目录结构截图/列表

### F. 交付模板（最终输出格式/命名/落盘路径）

- 命名规则：`YYYYMMDD-Markdown转EPUB-<版本>.md`
- 落盘路径：`<项目根>/docs/Markdown转EPUB/`
- 交付物模板：
  - 交付文件：
    - "<输出 EPUB 路径>"
  - 证据索引：
    - EVID-001 工具版本：`ebook-convert --version` 输出
    - EVID-002 转换命令：最终命令行全文
    - EVID-003 转换日志/报告（如有）：`conversion.log`、`report.json`
    - EVID-004 自检结论：目录存在/元数据命中/关键内容抽样命中

### G. 更新规则（用完写回：版本 + 0.1）

- 每次复跑后将新坑/新分支写回 D/E/F，并把版本 `v1.0 → v1.1`；变更记录新增一条