334 lines
14 KiB
Markdown
334 lines
14 KiB
Markdown
---
|
||
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`；变更记录新增一条
|