epub2md-cli

# epub2md CLI Use this skill to operate on local EPUB files with `epub2md` instead of hand-rolling parsing logic. ## Bundled script For any conversion that writes files, use the bundled wrapper script: `/home/admin1/.agents/skills/epub2md-cli/scripts/run_epub2md.py` The wrapper exists to enforce a stable workspace layout and avoid `epub2md 1.6.2` merge-path quirks. One more `epub2md 1.6.2` quirk: source filenames containing glob metacharacters such as `[` `]` `?` or `*` can still be treated as patterns by `epub2md`, even when the shell path was quoted correctly. When that happens, keep the original EPUB in `inputs/`, but stage a temporary safe basename such as `book.epub` before calling raw `epub2md`, then copy the generated `book/` directory into the expected workspace output folder. ## What `epub2md` is good at - Inspecting book metadata with `--info` - Inspecting table of contents and nesting with `--structure` - Listing sections/chapters with `--sections` - Converting an EPUB into chapter-by-chapter Markdown files - Merging an EPUB into one Markdown file, preferably with an explicit output name - Merging an existing Markdown directory with plain `--merge` - Downloading remote images referenced by the EPUB with `--localize` - Unzipping EPUB contents for inspection with `--unzip` - Batch conversion with quoted glob patterns like `"books/*.epub"` ## Prerequisites Check the command first: ```bash command -v epub2md ``` If it is missing and the environment allows installs, install it with npm: ```bash npm install -g epub2md ``` If `--localize` is needed, make sure Node.js is at least `18.0.0`. ## Workspace layout By default, write conversion jobs to: `/home/admin1/.agents/skills/epub2md-cli-workspace/{bookname}` Within that directory: - `inputs/` contains the original EPUB file - `outputs/` contains conversion results - `outputs/split/` contains chapter-by-chapter Markdown output - `outputs/merge/` contains merged Markdown output and related assets - `outputs/inspect/` contains saved inspection results when the user explicitly asks for inspection output Do not write conversion output next to the user's source EPUB unless they explicitly ask for a different layout. ## Working style 1. Start from the user's real goal, not from the default conversion. - If they only want metadata or structure, do not convert the book. - Inspection is opt-in only. Do not run it unless the user explicitly asked to inspect the EPUB. - If they want one final Markdown file from an EPUB, use merge mode. - If they want chapter files, use split mode. 2. Confirm the source path before running commands. - Prefer exact paths the user already gave you. - If they referred to "that epub in this folder", discover it with shell tools such as `rg --files -g '*.epub'`. - Quote paths and glob patterns when they contain spaces or wildcard characters. - Quoting is necessary but not sufficient when the EPUB basename itself contains `[` `]` `?` or `*`; `epub2md` may still interpret the basename as a glob internally. 3. If the user asked for conversion but did not specify the output shape, ask one short clarifying question before writing files. - Ask whether they want `多个文件`、`只要 merge 文件`、or `都转换`. - Do not guess between split and merge when the user clearly cares about the output form. 4. Use the wrapper script for any file-writing conversion task. - Do not call `epub2md` directly for split/merge/both output jobs unless the user explicitly asked for raw CLI invocation. - The wrapper copies the original EPUB into `inputs/` and writes results into `outputs/`. - The wrapper always uses a safe merge invocation and should not produce a stray `home/` directory. - If conversion still fails with `No files found matching pattern:` or a wrapper `FileNotFoundError` caused by a glob-like source basename, fall back to safe-basename staging: copy the EPUB into a temp directory as `book.epub`, run raw `epub2md` there, then copy the generated `book/` directory back into `outputs/merge/` or `outputs/split/`. 5. After the command finishes, report concrete outputs. - Say which command you ran. - Say where the generated files were written. - Mention any limitations, such as remote images not being localized unless `--localize` was used. 6. Treat `--sections` as an inspection tool, not a default user-facing output. - In `epub2md 1.6.2`, `--sections` prints very large objects with raw HTML. - Use it when you need deep inspection. - Summarize the findings for the user unless they explicitly asked for the raw dump. ## Command selection ### Inspect only ```bash epub2md --info "/path/to/book.epub" epub2md --structure "/path/to/book.epub" epub2md --sections "/path/to/book.epub" epub2md --unzip "/path/to/book.epub" python3 /home/admin1/.agents/skills/epub2md-cli/scripts/run_epub2md.py \ --input "/path/to/book.epub" \ --mode inspect python3 /home/admin1/.agents/skills/epub2md-cli/scripts/run_epub2md.py \ --input "/path/to/book.epub" \ --mode inspect \ --inspect-actions info structure sections ``` Use these only when the user explicitly wants to understand the book before deciding how to export it. ### Convert into chapter Markdown files ```bash python3 /home/admin1/.agents/skills/epub2md-cli/scripts/run_epub2md.py \ --input "/path/to/book.epub" \ --mode split python3 /home/admin1/.agents/skills/epub2md-cli/scripts/run_epub2md.py \ --input "/path/to/book.epub" \ --mode split \ --autocorrect ``` Use `--autocorrect` when the user explicitly wants spacing or punctuation cleanup in the Markdown output. ### Merge into one Markdown file ```bash python3 /home/admin1/.agents/skills/epub2md-cli/scripts/run_epub2md.py \ --input "/path/to/book.epub" \ --mode merge python3 /home/admin1/.agents/skills/epub2md-cli/scripts/run_epub2md.py \ --input "/path/to/book.epub" \ --mode merge \ --merge-name custom-name.md ``` Use the custom merged filename form when the user asks for a specific final filename. ### Convert both split and merge outputs ```bash python3 /home/admin1/.agents/skills/epub2md-cli/scripts/run_epub2md.py \ --input "/path/to/book.epub" \ --mode both ``` ### Localize remote images ```bash python3 /home/admin1/.agents/skills/epub2md-cli/scripts/run_epub2md.py \ --input "/path/to/book.epub" \ --mode split \ --localize python3 /home/admin1/.agents/skills/epub2md-cli/scripts/run_epub2md.py \ --input "/path/to/book.epub" \ --mode merge \ --merge-name custom-name.md \ --localize ``` Use this only when the user wants remote images downloaded into the output folder. Mention the Node.js `>=18` requirement if needed. ### Batch conversion ```bash epub2md "books/*.epub" epub2md --merge "books/*.epub" ``` Keep the glob quoted so `epub2md` receives the pattern directly. This is a raw CLI fallback for explicit bulk-processing requests. It does not use the per-book workspace layout above. Prefer the bundled wrapper for normal single-book conversion jobs. ### Fallback for glob-like EPUB filenames Use this only when the source basename itself contains `[` `]` `?` or `*` and the normal wrapper flow fails. ```bash src="/path/to/Book [Annotated].epub" book_name="Book [Annotated]" book_dir="/home/admin1/.agents/skills/epub2md-cli-workspace/$book_name" merge_dir="$book_dir/outputs/merge" merge_name="$book_name-merged.md" mkdir -p "$book_dir/inputs" "$merge_dir" cp "$src" "$book_dir/inputs/" tmpdir=$(mktemp -d "$book_dir/.manual-merge-XXXXXX") cp "$src" "$tmpdir/book.epub" cd "$tmpdir" epub2md --merge="$merge_name" "book.epub" cp -a "$tmpdir/book/." "$merge_dir/" ``` This preserves the normal workspace layout while avoiding `epub2md`'s internal glob matching on the original basename. ## Expected outputs Use these expectations when explaining results: - The original EPUB is copied to `.../{bookname}/inputs/{bookname}.epub` - Split output is written under `.../{bookname}/outputs/split/` - Merge output is written under `.../{bookname}/outputs/merge/` - Inspection output is written under `.../{bookname}/outputs/inspect/` only when the user asked for inspection - Chapter Markdown files are typically written as numbered Markdown files - Many chapter files are named like `NNN-title.md`, but fallback names such as `NNN-partXXXX.md` can also appear - Images are stored under an `images/` subdirectory inside the relevant output folder - Merge mode defaults to `{bookname}-merged.md` unless the user asked for another filename Do not claim remote images were downloaded unless `--localize` was part of the command. ## Known quirks These were validated against `epub2md 1.6.2`: - `--sections` is often too verbose to show directly because it includes raw HTML payloads - Plain `--merge` on an absolute EPUB path can generate an awkward nested path and keep the `.epub` extension on the merged Markdown file - The bundled wrapper avoids that behavior by never relying on plain `--merge` for EPUB merge jobs - EPUB basenames containing `[` `]` `?` or `*` can be interpreted as glob patterns by `epub2md` itself, even when shell quoting is correct - The common symptom is `No files found matching pattern:` from `epub2md`, or a wrapper `FileNotFoundError` because `epub2md` created `book/` while the wrapper expected a directory named after the original book - The practical workaround is to stage the source EPUB to a safe basename such as `book.epub`, run `epub2md` from that temp directory, then copy the generated `book/` contents back into the expected workspace output directory ## Response format Keep the response practical and concrete: 1. State the action you took 2. Show the exact `epub2md` command you ran 3. List the output path or paths created 4. Mention blockers or caveats, if any ## Examples **Example 1: convert to chapter files** User intent: "把 `~/Books/foo.epub` 转成多个 markdown 章节。" Good command: ```bash python3 /home/admin1/.agents/skills/epub2md-cli/scripts/run_epub2md.py \ --input "$HOME/Books/foo.epub" \ --mode split ``` **Example 2: merge and localize** User intent: "把 `~/Books/foo.epub` 合成一个 markdown，并把远程图片下载到本地。" Good command: ```bash python3 /home/admin1/.agents/skills/epub2md-cli/scripts/run_epub2md.py \ --input "$HOME/Books/foo.epub" \ --mode merge \ --merge-name foo.md \ --localize ``` **Example 3: user did not specify split or merge** User intent: "把这个 epub 转成 markdown。" Good response: ```text 要哪种输出：多个章节文件、只要一个 merge 文件，还是两种都要？ ``` **Example 4: inspect only** User intent: "先帮我看看这本书的目录结构，不要导出正文。" Good command: ```bash python3 /home/admin1/.agents/skills/epub2md-cli/scripts/run_epub2md.py \ --input "/path/to/book.epub" \ --mode inspect ```