AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He
feat(source-to-md): batch/directory conversion + web title naming
hugohe3088450db3275
diff --git a/AGENTS.md b/AGENTS.mdindex db558f38..2f5513fd 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -43,11 +43,11 @@ Convenience summary only — full workflow in [`skills/ppt-master/SKILL.md`](ski```bash# Source content conversion-python3 skills/ppt-master/scripts/source_to_md.py <file_or_URL> [<file_or_URL> ...]+python3 skills/ppt-master/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or_URL_or_dir> ...]# Project managementpython3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169-python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_URLs...> --move+python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_dirs_or_URLs...> --movepython3 skills/ppt-master/scripts/project_manager.py validate <project_path># Icon selection — copy chosen library icons into <project>/icons/ (missing names reported + non-zero = re-pick)diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex ca2ec66e..a1e476ae 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -136,15 +136,15 @@ routes by source type, and writes the standard Markdown plus conversion profile.| User Provides | Action ||---------------|--------|-| PDF / DOCX / Office document / XLSX / XLSM / PPTX / EPUB / HTML / LaTeX / RST / web URL | `python3 ${SKILL_DIR}/scripts/source_to_md.py <file_or_URL> [<file_or_URL> ...]` |+| PDF / DOCX / Office document / XLSX / XLSM / PPTX / EPUB / HTML / LaTeX / RST / web URL | `python3 ${SKILL_DIR}/scripts/source_to_md.py <file_or_URL_or_dir> [<file_or_URL_or_dir> ...]` || CSV / TSV | Read directly as plain-text table source || Markdown | Read directly |For PPTX sources, Step 1 converts the deck to Markdown content; after Step 2`import-sources`, standard PPTX intake is also written to `<project>/analysis/`.-Use `source_to_md.py -t <type>` only when extension detection is ambiguous. Use-`-o` only with a single input; explicit multi-input conversion writes one-Markdown/profile pair per source. Backend converter details are documented in+Use `source_to_md.py -t <type>` only when extension detection is ambiguous. With+multiple inputs or directory inputs, `-o` is an output directory and conversion+writes one Markdown/profile pair per source. Backend converter details are documented in[`scripts/docs/conversion.md`](scripts/docs/conversion.md).> **Office vector assets (EMF/WMF) from DOCX/PPTX sources**:@@ -179,7 +179,7 @@ Import source content (choose based on the situation):| Situation | Action ||-----------|--------|-| Has source files (PDF/MD/etc.) | `python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files...> --move` |+| Has source files (PDF/MD/etc.) | `python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...> --move` || User provided text directly in conversation | No import needed — content is already in conversation context; subsequent steps can reference it directly |For PPTX sources, `import-sources` automatically runs the standard intake enrichment:@@ -192,7 +192,7 @@ For each PPTX it writes `<stem>.identity.json` (canvas, theme palette/fonts, obsMulti-deck: several PPTX files may be imported into one main-pipeline project — each gets its own `<stem>.*` artifacts and a deck entry in `source_profile.json`. `source_profile.json` stays the single must-read index (one entry for a one-deck project, several for a combined-source project). Stems must be distinct; re-importing the same stem replaces that deck's entry. The beautify / template-fill workflows remain single-deck (1:1 to one chosen source deck) and read that deck's `<stem>.*` artifacts.-> ⚠️ **MUST use `--move`** (not copy): all source files — Step 1's generated Markdown, original PDFs / MDs / images — go into `sources/` via `import-sources --move`. After execution they no longer exist at the original location. Intermediate artifacts (e.g., `_files/`) are handled automatically.+> ⚠️ **MUST use `--move`** (not copy): all source files — Step 1's generated Markdown, original PDFs / MDs / images — go into `sources/` via `import-sources --move`. Pass both the original source path(s)/directory and the Step 1 Markdown output path(s)/directory. After execution they no longer exist at the original location. Intermediate artifacts (e.g., `_files/`) are handled automatically.**✅ Checkpoint — Confirm project structure created successfully, `sources/` contains all source files, converted materials are ready. Proceed to Step 3.**diff --git a/skills/ppt-master/scripts/README.md b/skills/ppt-master/scripts/README.mdindex ec9c0e0a..8fca4444 100644--- a/skills/ppt-master/scripts/README.md+++ b/skills/ppt-master/scripts/README.md@@ -6,7 +6,7 @@ This directory contains user-facing scripts for conversion, project setup, direc- Top-level `scripts/`: runnable entry scripts- `scripts/source_to_md.py`: unified source-document → Markdown dispatcher-- `scripts/source_to_md/`: source-document → Markdown routing helpers and backend converters (`_dispatcher.py`, `pdf_to_md.py`, `doc_to_md.py`, `excel_to_md.py`, `ppt_to_md.py`, `web_to_md.py`)+- `scripts/source_to_md/`: source-document → Markdown routing/batch helpers and backend converters (`_dispatcher.py`, `_batch.py`, `pdf_to_md.py`, `doc_to_md.py`, `excel_to_md.py`, `ppt_to_md.py`, `web_to_md.py`)- `scripts/image_backends/`: internal provider implementations used by `image_gen.py`- `scripts/tts_backends/`: internal TTS provider implementations used by `notes_to_audio.py`- `scripts/template_import/`: internal PPTX reference-preparation helpers used by `pptx_template_import.py`@@ -19,14 +19,14 @@ This directory contains user-facing scripts for conversion, project setup, direcTypical end-to-end workflow:```bash-python3 scripts/source_to_md.py <file-or-url> [<file-or-url> ...]+python3 scripts/source_to_md.py <file-or-url-or-dir> [<file-or-url-or-dir> ...]# or direct backend calls:python3 scripts/source_to_md/pdf_to_md.py <file.pdf># orpython3 scripts/source_to_md/ppt_to_md.py <deck.pptx>python3 scripts/source_to_md/excel_to_md.py <workbook.xlsx>python3 scripts/project_manager.py init <project_name> --format ppt169-python3 scripts/project_manager.py import-sources <project_path> <source_files...> --move+python3 scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...> --movepython3 scripts/total_md_split.py <project_path>python3 scripts/finalize_svg.py <project_path>python3 scripts/animation_config.py scaffold <project_path> # optional object-level animation overrides@@ -56,7 +56,7 @@ python3 scripts/update_repo.pyConversion:```bash-python3 scripts/source_to_md.py <file-or-url> [<file-or-url> ...]+python3 scripts/source_to_md.py <file-or-url-or-dir> [<file-or-url-or-dir> ...]python3 scripts/source_to_md/pdf_to_md.py <file.pdf>python3 scripts/source_to_md/ppt_to_md.py <deck.pptx>python3 scripts/source_to_md/doc_to_md.py <file.docx>@@ -68,7 +68,7 @@ Project setup:```bashpython3 scripts/project_manager.py init <project_name> --format ppt169-python3 scripts/project_manager.py import-sources <project_path> <source_files...> --move+python3 scripts/project_manager.py import-sources <project_path> <source_files_or_dirs...> --movepython3 scripts/project_manager.py validate <project_path>```diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.mdindex 338b5fe1..a8996cfb 100644--- a/skills/ppt-master/scripts/docs/conversion.md+++ b/skills/ppt-master/scripts/docs/conversion.md@@ -36,6 +36,7 @@ Routing is centralized in `source_to_md/_dispatcher.py` and reused by```bashpython3 scripts/source_to_md.py paper.pdfpython3 scripts/source_to_md.py paper.pdf report.docx deck.pptx+python3 scripts/source_to_md.py ./sources -o ./markdownpython3 scripts/source_to_md.py ./pdfs/*.pdfpython3 scripts/source_to_md.py ./decks/*.pptxpython3 scripts/source_to_md.py report.docx -o report.md@@ -54,16 +55,12 @@ Useful options:existing PDF image mode. They are intentionally PDF-only until other backendsexpose the same behavior natively.- Unknown backend-specific flags are passed through to each selected converter.-- `-o/--output` is valid only with one input. Multiple explicit inputs write- one Markdown/profile pair per source.+- `-o/--output` selects one Markdown file for one input, or an output directory+ for multiple inputs / directory inputs.For multi-source project intake, use `project_manager.py import-sources` with-all source paths / URLs. `source_to_md.py` intentionally rejects directory-batching; pass explicit files/URLs or use project intake.--Backend converters are single-file tools. For ad hoc multi-file conversion,-pass explicit files or shell-expanded globs to `source_to_md.py`; for project-intake, use `project_manager.py import-sources`.+all source paths / URLs. `source_to_md.py` and the backend converters support+single files, explicit multi-file inputs, and non-recursive directory inputs.## `source_to_md/pdf_to_md.py`@@ -72,6 +69,8 @@ Recommended first choice for native PDFs.```bashpython3 scripts/source_to_md/pdf_to_md.py book.pdfpython3 scripts/source_to_md/pdf_to_md.py book.pdf -o output.md+python3 scripts/source_to_md/pdf_to_md.py book.pdf appendix.pdf+python3 scripts/source_to_md/pdf_to_md.py ./pdfs -o ./markdown# Image extraction control (default: filtered)python3 scripts/source_to_md/pdf_to_md.py book.pdf --images filtered # size/quality filters applied@@ -111,6 +110,8 @@ Pandoc fallback (only if you need these):```bashpython3 scripts/source_to_md/doc_to_md.py lecture.docxpython3 scripts/source_to_md/doc_to_md.py lecture.docx -o output.md+python3 scripts/source_to_md/doc_to_md.py lecture.docx notes.html+python3 scripts/source_to_md/doc_to_md.py ./docs -o ./markdownpython3 scripts/source_to_md/doc_to_md.py notes.epubpython3 scripts/source_to_md/doc_to_md.py paper.tex -o paper.md # uses pandoc```@@ -144,6 +145,8 @@ Unsupported by default:```bashpython3 scripts/source_to_md/excel_to_md.py report.xlsxpython3 scripts/source_to_md/excel_to_md.py report.xlsx -o output.md+python3 scripts/source_to_md/excel_to_md.py report.xlsx budget.xlsm+python3 scripts/source_to_md/excel_to_md.py ./workbooks -o ./markdownpython3 scripts/source_to_md/excel_to_md.py report.xlsm --max-rows 200 --max-cols 40```@@ -175,6 +178,8 @@ Supported formats include:```bashpython3 scripts/source_to_md/ppt_to_md.py sales_deck.pptxpython3 scripts/source_to_md/ppt_to_md.py sales_deck.pptx -o output.md+python3 scripts/source_to_md/ppt_to_md.py sales_deck.pptx appendix.pptx+python3 scripts/source_to_md/ppt_to_md.py ./decks -o ./markdownpython3 scripts/source_to_md/ppt_to_md.py template.ppsx -o notes/template.md```@@ -225,6 +230,7 @@ python3 scripts/source_to_md/web_to_md.py https://example.com/articlepython3 scripts/source_to_md/web_to_md.py https://url1.com https://url2.compython3 scripts/source_to_md/web_to_md.py -f urls.txtpython3 scripts/source_to_md/web_to_md.py https://example.com -o output.md+python3 scripts/source_to_md/web_to_md.py https://example.com --emit-result /tmp/result.json```When `curl_cffi` is installed (included in `requirements.txt`), this script@@ -235,6 +241,8 @@ block Python's default TLS fingerprint. No extra flags needed. IfOn success, the converter writes `<output>.conversion_profile.json` beside theMarkdown output.+`--emit-result` is for wrapper scripts that need the actual saved Markdown path+when the converter derives a title-based filename.## `rotate_images.py`diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.mdindex b31829d4..97630686 100644--- a/skills/ppt-master/scripts/docs/project.md+++ b/skills/ppt-master/scripts/docs/project.md@@ -10,7 +10,7 @@ Main entry point for project setup and validation.```bashpython3 scripts/project_manager.py init <project_name> --format ppt169-python3 scripts/project_manager.py import-sources <project_path> <source1> [<source2> ...]+python3 scripts/project_manager.py import-sources <project_path> <source1_or_dir> [<source2_or_dir> ...]python3 scripts/project_manager.py validate <project_path>python3 scripts/project_manager.py info <project_path>```@@ -18,6 +18,9 @@ python3 scripts/project_manager.py info <project_path>Notes:- Files outside the repo are copied into `sources/` by default- With `--move`, files outside the repo are moved into `sources/`+- Directory inputs are expanded non-recursively. After Step 1 conversion,+ pass both the original source file/directory and the generated Markdown+ file/directory so both are archived under `sources/`.- Files already inside the repo are moved into `sources/` by default (with a stderrnote), to avoid leaving unintended artifacts that could be committed by mistake.Pass `--copy` to force a copy for in-repo sources instead.diff --git a/skills/ppt-master/scripts/project_manager.py b/skills/ppt-master/scripts/project_manager.pyindex 72ad4fc6..bff93017 100644--- a/skills/ppt-master/scripts/project_manager.py+++ b/skills/ppt-master/scripts/project_manager.py@@ -612,16 +612,37 @@ class ProjectManager:"notes": [],"skipped": [],}++ expanded_items: list[str] = []+ for item in source_items:+ if is_url(item):+ expanded_items.append(item)+ continue+ item_path = Path(item)+ if item_path.is_dir():+ directory_files = sorted(+ path for path in item_path.iterdir() if path.is_file()+ )+ if directory_files:+ expanded_items.extend(str(path) for path in directory_files)+ summary["notes"].append(+ f"{item}: expanded directory into {len(directory_files)} file(s)"+ )+ else:+ summary["skipped"].append(f"{item}: directory contains no files")+ continue+ expanded_items.append(item)+explicit_markdown_stems = {Path(item).stem- for item in source_items+ for item in expanded_itemsif not is_url(item)and Path(item).exists()and Path(item).is_file()and Path(item).suffix.lower() in {".md", ".markdown"}}- for item in source_items:+ for item in expanded_items:if is_url(item):markdown_path = self._ensure_unique_path(sources_dir / f"{derive_url_basename(item)}.md"@@ -861,7 +882,7 @@ def build_parser() -> argparse.ArgumentParser:help="Import source files or URLs into a project",)import_sources.add_argument("project_path", help="Project directory")- import_sources.add_argument("sources", nargs="+", help="Source files or URLs")+ import_sources.add_argument("sources", nargs="+", help="Source files, directories, or URLs")mode = import_sources.add_mutually_exclusive_group()mode.add_argument("--move", action="store_true", help="Move local source files")mode.add_argument("--copy", action="store_true", help="Copy local source files")diff --git a/skills/ppt-master/scripts/source_to_md.py b/skills/ppt-master/scripts/source_to_md.pyindex 31574885..68bb3d93 100644--- a/skills/ppt-master/scripts/source_to_md.py+++ b/skills/ppt-master/scripts/source_to_md.py@@ -5,11 +5,12 @@ PPT Master - Unified Markdown ConverterAuto-detect source type and dispatch to the existing source_to_md converters.Usage:- python3 scripts/source_to_md.py <file_or_url> [<file_or_url> ...] [options]+ python3 scripts/source_to_md.py <file_or_url_or_dir> [<file_or_url_or_dir> ...] [options]Examples:python3 scripts/source_to_md.py paper.pdfpython3 scripts/source_to_md.py paper.pdf report.docx deck.pptx+ python3 scripts/source_to_md.py ./sources -o ./markdownpython3 scripts/source_to_md.py report.docx -o report.mdpython3 scripts/source_to_md.py deck.pptx --json@@ -21,11 +22,10 @@ from __future__ import annotationsimport argparseimport json-import reimport subprocessimport sys+import tempfilefrom pathlib import Path-from urllib.parse import urlparse_SCRIPTS_DIR = Path(__file__).resolve().parentif str(_SCRIPTS_DIR) not in sys.path:@@ -42,6 +42,7 @@ from _conversion_profile import ( # noqa: E402profile_path_for,write_conversion_profile,)+from _batch import expand_directory_inputs, unique_output_path # noqa: E402from _dispatcher import ( # noqa: E402build_conversion_command,default_markdown_path,@@ -60,23 +61,34 @@ def _print_status(message: str) -> None:print(message, file=sys.stderr)-def _sanitize_output_stem(value: str) -> str:- safe = re.sub(r"[^A-Za-z0-9_.-]+", "_", value.strip())- safe = safe.strip("._-")- while "__" in safe:- safe = safe.replace("__", "_")- return safe[:120] or "web_source"+def _is_supported_directory_item(path: Path) -> bool:+ return detect_source_type(str(path)) in {+ "pdf", "doc", "excel", "pptx", "markdown", "text",+ }-def _default_batch_output(input_arg: str, conversion_type: str) -> str | None:- """Return a deterministic per-source output path for batch mode."""- if conversion_type == "web":- parsed = urlparse(input_arg)- parts = [parsed.netloc]- if parsed.path and parsed.path != "/":- parts.append(parsed.path.strip("/").replace("/", "_"))- return str(Path(f"{_sanitize_output_stem('_'.join(parts))}.md"))- return str(default_markdown_path(input_arg))+def _dispatch_output_arg(+ input_arg: str,+ conversion_type: str,+ output_arg: str | None,+ batch_mode: bool,+ used_outputs: set[Path],+) -> str | None:+ if output_arg and batch_mode and conversion_type == "web":+ return None+ if output_arg and batch_mode:+ return str(+ unique_output_path(+ Path(output_arg),+ default_markdown_path(input_arg).stem,+ used_outputs,+ )+ )+ if output_arg:+ return output_arg+ if batch_mode and conversion_type != "web":+ return str(default_markdown_path(input_arg))+ return Nonedef run_backend(command: list[str], script_name: str) -> int:@@ -176,6 +188,15 @@ def print_json_result(print(json.dumps(payload, ensure_ascii=False))+def _read_emit_result(path: Path) -> Path | None:+ try:+ payload = json.loads(path.read_text(encoding="utf-8"))+ except (OSError, json.JSONDecodeError):+ return None+ markdown = payload.get("markdown")+ return Path(markdown) if isinstance(markdown, str) and markdown else None++def _pdf_image_mode(args: argparse.Namespace) -> str | None:image_mode = args.imagesif args.no_images:@@ -202,19 +223,12 @@ def dispatch_single(output_arg: str | None,args: argparse.Namespace,unknown_args: list[str],+ web_output_dir: str | None = None,) -> int:"""Dispatch one source to the matching existing converter."""if conversion_type == "auto":conversion_type = detect_source_type(input_arg)- if conversion_type == "directory":- print(- "[ERROR] Directories are not supported by source_to_md.py; "- "use project_manager.py import-sources for multi-source project intake.",- file=sys.stderr,- )- return 1-if conversion_type == "markdown":output = resolve_output(output_arg, input_arg)return write_passthrough(input_arg, output, "markdown", args.json)@@ -224,25 +238,51 @@ def dispatch_single(if conversion_type == "web":output = Path(output_arg) if output_arg else None+ emit_result: Path | None = None+ extra_args = list(unknown_args)+ if output is None:+ emit_file = tempfile.NamedTemporaryFile(+ prefix="ppt-master-web-result-",+ suffix=".json",+ delete=False,+ )+ emit_file.close()+ emit_result = Path(emit_file.name)+ extra_args.extend(["--emit-result", str(emit_result)])+ if web_output_dir:+ extra_args.extend(["--dir", web_output_dir])try:route = build_conversion_command(input_arg,output,forced_type="web",- extra_args=unknown_args,+ extra_args=extra_args,)except ValueError as exc:+ if emit_result:+ emit_result.unlink(missing_ok=True)print(f"[ERROR] {exc}", file=sys.stderr)return 1rc = run_backend(route.command, route.script_name)if rc != 0:+ if emit_result:+ emit_result.unlink(missing_ok=True)return rc- if route.output_path and route.output_path.is_file():- profile = ensure_profile(input_arg, route.output_path, route.script_name, "web")- print_output(route.output_path)+ output_path = route.output_path+ if output_path is None and emit_result is not None:+ output_path = _read_emit_result(emit_result)+ emit_result.unlink(missing_ok=True)+ if output_path and output_path.is_file():+ profile = ensure_profile(input_arg, output_path, route.script_name, "web")+ print_output(output_path)if args.json:- print_json_result(input_arg, route.output_path, route.script_name, "web", profile)- return 0+ print_json_result(input_arg, output_path, route.script_name, "web", profile)+ return 0+ if output is not None:+ print(f"[ERROR] Expected Markdown output not found: {output}", file=sys.stderr)+ else:+ print("[ERROR] Web conversion did not report a Markdown output path", file=sys.stderr)+ return 1if conversion_type not in {"pdf", "doc", "excel", "pptx"}:print(@@ -291,6 +331,7 @@ def build_parser() -> argparse.ArgumentParser:Examples:python3 scripts/source_to_md.py paper.pdfpython3 scripts/source_to_md.py paper.pdf report.docx deck.pptx+ python3 scripts/source_to_md.py ./sources -o ./markdownpython3 scripts/source_to_md.py report.docx -o output.mdpython3 scripts/source_to_md.py deck.pptx --jsonpython3 scripts/source_to_md.py https://example.com/article -o article.md@@ -299,7 +340,7 @@ Backend-specific flags not listed here are passed through to the selectedconverter, so existing converter behavior remains the source of truth.""",)- parser.add_argument("inputs", nargs="+", help="Input file(s) or URL(s)")+ parser.add_argument("inputs", nargs="+", help="Input file(s), directories, or URL(s)")parser.add_argument("-t","--type",@@ -307,7 +348,11 @@ converter, so existing converter behavior remains the source of truth.default="auto",help="Force a conversion type (default: auto)",)- parser.add_argument("-o", "--output", help="Output Markdown file")+ parser.add_argument(+ "-o",+ "--output",+ help="Output Markdown file for one input, or output directory for multiple inputs/directories",+ )parser.add_argument("--images",choices=["all", "filtered", "none"],@@ -360,31 +405,63 @@ def dispatch_many(args: argparse.Namespace,unknown_args: list[str],conversion_types: list[str],+ batch_mode: bool = False,+ initial_failures: list[str] | None = None,) -> int:success_count = 0- failed: list[tuple[str, int]] = []- batch_mode = len(inputs) > 1+ failed: list[str] = []+ skipped: list[str] = list(initial_failures or [])+ batch_mode = batch_mode or len(inputs) > 1+ if args.output and batch_mode:+ output_dir = Path(args.output)+ if output_dir.exists() and not output_dir.is_dir():+ print(f"[ERROR] Batch output path is not a directory: {args.output}", file=sys.stderr)+ return 1+ output_dir.mkdir(parents=True, exist_ok=True)+ used_outputs: set[Path] = set()for input_arg, conversion_type in zip(inputs, conversion_types):- output_arg = args.output+ output_arg = _dispatch_output_arg(+ input_arg,+ conversion_type,+ args.output,+ batch_mode,+ used_outputs,+ )+ web_output_dir = (+ args.output+ if args.output and batch_mode and conversion_type == "web"+ else None+ )if batch_mode:- output_arg = _default_batch_output(input_arg, conversion_type)_print_status(f"\n==> {input_arg}")- rc = dispatch_single(input_arg, conversion_type, output_arg, args, unknown_args)+ rc = dispatch_single(+ input_arg,+ conversion_type,+ output_arg,+ args,+ unknown_args,+ web_output_dir=web_output_dir,+ )if rc == 0:success_count += 1else:- failed.append((input_arg, rc))+ failed.append(f"{input_arg}: exit {rc}")if batch_mode:_print_status(f"\n[Done] Success: {success_count}/{len(inputs)}, Failed: {len(failed)}")+ if skipped:+ _print_status("\n[Skipped directories]:")+ for item in skipped:+ _print_status(f" - {item}")if failed:_print_status("\n[Failed inputs]:")- for input_arg, rc in failed:- _print_status(f" - {input_arg}: exit {rc}")- return 1- return 0 if not failed else failed[0][1]+ for item in failed:+ _print_status(f" - {item}")+ if not inputs:+ return 1+ return 0 if not failed and not skipped else 1def main(argv: list[str] | None = None) -> int:@@ -394,11 +471,14 @@ def main(argv: list[str] | None = None) -> int:if not _validate_image_options(args):return 2- if len(args.inputs) > 1 and args.output:- print("[ERROR] -o/--output is only valid with a single input", file=sys.stderr)- return 2+ inputs, expansion_errors, saw_directory = expand_directory_inputs(+ args.inputs,+ _is_supported_directory_item,+ is_external_ref=is_url,+ )+ batch_mode = saw_directory or len(inputs) > 1- conversion_types = [_conversion_type_for_input(item, args.type) for item in args.inputs]+ conversion_types = [_conversion_type_for_input(item, args.type) for item in inputs]if not _validate_pdf_image_flags(args, conversion_types):return 2@@ -411,7 +491,14 @@ def main(argv: list[str] | None = None) -> int:)return 2- return dispatch_many(args.inputs, args, unknown_args, conversion_types)+ return dispatch_many(+ inputs,+ args,+ unknown_args,+ conversion_types,+ batch_mode=batch_mode,+ initial_failures=expansion_errors,+ )if __name__ == "__main__":diff --git a/skills/ppt-master/scripts/source_to_md/_batch.py b/skills/ppt-master/scripts/source_to_md/_batch.pynew file mode 100644index 00000000..ef98a09f--- /dev/null+++ b/skills/ppt-master/scripts/source_to_md/_batch.py@@ -0,0 +1,150 @@+#!/usr/bin/env python3+"""+PPT Master - Source Converter Batch Helpers++Share explicit multi-file and directory expansion logic across source_to_md+backend converters.++Usage:+ Imported by scripts/source_to_md/*_to_md.py++Examples:+ run_path_batch(["docs"], {".docx"}, None, convert_one)++Dependencies:+ None+"""++from __future__ import annotations++import sys+from collections.abc import Callable+from pathlib import Path+++ConvertOne = Callable[[Path, Path], bool]+IsSupportedFile = Callable[[Path], bool]+++def _print_status(message: str) -> None:+ print(message, file=sys.stderr)+++def expand_directory_inputs(+ inputs: list[str],+ is_supported_file: IsSupportedFile,+ is_external_ref: Callable[[str], bool] | None = None,+) -> tuple[list[str], list[str], bool]:+ """Expand non-recursive directory inputs while preserving other items."""+ expanded: list[str] = []+ errors: list[str] = []+ saw_directory = False+ is_external = is_external_ref or (lambda _item: False)++ for item in inputs:+ if is_external(item):+ expanded.append(item)+ continue+ path = Path(item)+ if path.is_dir():+ saw_directory = True+ matches = sorted(+ child for child in path.iterdir()+ if child.is_file() and is_supported_file(child)+ )+ if matches:+ expanded.extend(str(match) for match in matches)+ else:+ errors.append(f"{item}: no supported files found")+ continue+ expanded.append(item)++ return expanded, errors, saw_directory+++def _output_key(path: Path) -> Path:+ return path.resolve(strict=False)+++def unique_output_path(output_dir: Path, stem: str, used_outputs: set[Path]) -> Path:+ """Return an in-run unique Markdown path without consulting the filesystem."""+ base = stem or "output"+ candidate = output_dir / f"{base}.md"+ suffix = 2+ while _output_key(candidate) in used_outputs:+ candidate = output_dir / f"{base}_{suffix}.md"+ suffix += 1+ used_outputs.add(_output_key(candidate))+ return candidate+++def _output_for(+ source: Path,+ output_arg: str | None,+ batch_mode: bool,+ used_outputs: set[Path],+) -> Path:+ if output_arg and batch_mode:+ return unique_output_path(Path(output_arg), source.stem, used_outputs)+ if output_arg:+ return Path(output_arg)+ return source.with_suffix(".md")+++def run_path_batch(+ inputs: list[str],+ supported_suffixes: set[str],+ output_arg: str | None,+ convert_one: ConvertOne,+) -> int:+ """Run one converter across explicit files and non-recursive directories."""+ expanded, expansion_errors, saw_directory = expand_directory_inputs(+ inputs,+ lambda path: path.suffix.lower() in supported_suffixes,+ )+ sources = [Path(item) for item in expanded]+ batch_mode = saw_directory or len(sources) > 1++ if output_arg and batch_mode:+ output_dir = Path(output_arg)+ if output_dir.exists() and not output_dir.is_dir():+ _print_status(f"[ERROR] Batch output path is not a directory: {output_arg}")+ return 1+ output_dir.mkdir(parents=True, exist_ok=True)++ success_count = 0+ failed: list[str] = []+ skipped: list[str] = list(expansion_errors)+ used_outputs: set[Path] = set()++ for source in sources:+ output = _output_for(source, output_arg, batch_mode, used_outputs)+ if batch_mode:+ _print_status(f"\n==> {source}")+ try:+ converted = convert_one(source, output)+ sys.stdout.flush()+ if converted:+ success_count += 1+ else:+ failed.append(str(source))+ except Exception as exc:+ sys.stdout.flush()+ failed.append(f"{source}: {exc}")+ _print_status(f"[ERROR] {source}: {exc}")++ if batch_mode:+ sys.stdout.flush()+ _print_status(f"\n[Done] Success: {success_count}/{len(sources)}, Failed: {len(failed)}")+ if skipped:+ _print_status("\n[Skipped directories]:")+ for item in skipped:+ _print_status(f" - {item}")+ if failed:+ _print_status("\n[Failed inputs]:")+ for item in failed:+ _print_status(f" - {item}")++ if not sources:+ return 1+ return 0 if not failed and not skipped else 1diff --git a/skills/ppt-master/scripts/source_to_md/doc_to_md.py b/skills/ppt-master/scripts/source_to_md/doc_to_md.pyindex cc691c93..9d2801c3 100644--- a/skills/ppt-master/scripts/source_to_md/doc_to_md.py+++ b/skills/ppt-master/scripts/source_to_md/doc_to_md.py@@ -38,6 +38,7 @@ if str(_SCRIPTS_DIR) not in sys.path:sys.path.insert(0, str(_SCRIPTS_DIR))from console_encoding import configure_utf8_stdio # noqa: E402+from _batch import run_path_batch # noqa: E402from _conversion_profile import write_conversion_profile_best_effort # noqa: E402configure_utf8_stdio()@@ -1448,7 +1449,7 @@ def convert_to_markdown(input_path: str, output_path: str | None = None) -> str:return markdown-def main() -> None:+def main() -> int:parser = argparse.ArgumentParser(description="Convert documents to Markdown ""(pure-Python for common formats, pandoc fallback for the rest)",@@ -1456,6 +1457,8 @@ def main() -> None:epilog="""Examples:python doc_to_md.py lecture.docx # Word → Markdown (mammoth)+ python doc_to_md.py lecture.docx notes.html # Convert multiple files+ python doc_to_md.py ./docs -o ./markdown # Convert supported files in a directorypython doc_to_md.py article.html # HTML → Markdown (markdownify)python doc_to_md.py book.epub # EPUB → Markdown (ebooklib)python doc_to_md.py notebook.ipynb # Jupyter → Markdown (nbconvert)@@ -1468,13 +1471,22 @@ Pandoc fallback formats (require system pandoc):.doc .odt .rtf .tex/.latex .rst .org .typ""",)- parser.add_argument("input", help="Input document file")- parser.add_argument("-o", "--output", help="Output Markdown file path")+ parser.add_argument("inputs", nargs="+", help="Input document file(s) or directories")+ parser.add_argument(+ "-o",+ "--output",+ help="Output Markdown file for one input, or output directory for multiple inputs/directories",+ )args = parser.parse_args()- result = convert_to_markdown(args.input, args.output)- sys.exit(0 if result else 1)+ supported_suffixes = set(NATIVE_FORMATS) | set(PANDOC_FORMATS)+ return run_path_batch(+ args.inputs,+ supported_suffixes,+ args.output,+ lambda source, output: bool(convert_to_markdown(str(source), str(output))),+ )if __name__ == "__main__":- main()+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/source_to_md/excel_to_md.py b/skills/ppt-master/scripts/source_to_md/excel_to_md.pyindex b14692b1..54506a1f 100644--- a/skills/ppt-master/scripts/source_to_md/excel_to_md.py+++ b/skills/ppt-master/scripts/source_to_md/excel_to_md.py@@ -25,6 +25,7 @@ if str(_SCRIPTS_DIR) not in sys.path:sys.path.insert(0, str(_SCRIPTS_DIR))from console_encoding import configure_utf8_stdio # noqa: E402+from _batch import run_path_batch # noqa: E402from _conversion_profile import write_conversion_profile_best_effort # noqa: E402configure_utf8_stdio()@@ -351,13 +352,15 @@ def convert_to_markdown(return markdown-def main() -> None:+def main() -> int:parser = argparse.ArgumentParser(description="Convert Excel workbooks to Markdown",formatter_class=argparse.RawDescriptionHelpFormatter,epilog="""Examples:python excel_to_md.py report.xlsx+ python excel_to_md.py report.xlsx budget.xlsm+ python excel_to_md.py ./workbooks -o ./markdownpython excel_to_md.py report.xlsx -o output.mdpython excel_to_md.py report.xlsm --max-rows 200 --max-cols 40@@ -368,8 +371,12 @@ Unsupported by default:.xls Resave as .xlsx first""",)- parser.add_argument("input", help="Input Excel workbook")- parser.add_argument("-o", "--output", help="Output Markdown file path")+ parser.add_argument("inputs", nargs="+", help="Input Excel workbook(s) or directories")+ parser.add_argument(+ "-o",+ "--output",+ help="Output Markdown file for one input, or output directory for multiple inputs/directories",+ )parser.add_argument("--max-rows",type=int,@@ -384,14 +391,20 @@ Unsupported by default:)args = parser.parse_args()- result = convert_to_markdown(- args.input,+ return run_path_batch(+ args.inputs,+ EXCEL_FORMATS | LEGACY_EXCEL_FORMATS,args.output,- max_rows=args.max_rows,- max_cols=args.max_cols,+ lambda source, output: bool(+ convert_to_markdown(+ str(source),+ str(output),+ max_rows=args.max_rows,+ max_cols=args.max_cols,+ )+ ),)- sys.exit(0 if result else 1)if __name__ == "__main__":- main()+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/source_to_md/pdf_to_md.py b/skills/ppt-master/scripts/source_to_md/pdf_to_md.pyindex d4081912..22460d7e 100644--- a/skills/ppt-master/scripts/source_to_md/pdf_to_md.py+++ b/skills/ppt-master/scripts/source_to_md/pdf_to_md.py@@ -19,6 +19,7 @@ if str(_SCRIPTS_DIR) not in sys.path:sys.path.insert(0, str(_SCRIPTS_DIR))from console_encoding import configure_utf8_stdio # noqa: E402+from _batch import run_path_batch # noqa: E402from _conversion_profile import write_conversion_profile_best_effort # noqa: E402configure_utf8_stdio()@@ -1082,6 +1083,8 @@ def main() -> int:epilog='''Examples:python pdf_to_md.py book.pdf # Convert a single file+ python pdf_to_md.py book.pdf appendix.pdf # Convert multiple files+ python pdf_to_md.py ./pdfs -o ./markdown # Convert PDFs in a directorypython pdf_to_md.py book.pdf -o output.md # Specify output filepython pdf_to_md.py book.pdf --render-vector-figures@@ -1095,8 +1098,12 @@ Structure detection features:''')- parser.add_argument('input', help='PDF file')- parser.add_argument('-o', '--output', help='Output Markdown file')+ parser.add_argument('inputs', nargs='+', help='PDF file(s) or directories')+ parser.add_argument(+ '-o',+ '--output',+ help='Output Markdown file for one input, or output directory for multiple inputs/directories',+ )parser.add_argument('--images',choices=['all', 'filtered', 'none'],@@ -1117,22 +1124,21 @@ Structure detection features:args = parser.parse_args()- input_path = Path(args.input)-- if not input_path.is_file():- print(f"Error: PDF file not found: {args.input}")- return 1-- output = args.output or str(input_path.with_suffix('.md'))- extract_pdf_to_markdown(- str(input_path),- output,- images=args.images,- render_vector_figures=args.render_vector_figures,- vector_figure_dpi=args.vector_figure_dpi,+ return run_path_batch(+ args.inputs,+ {'.pdf'},+ args.output,+ lambda source, output: bool(+ extract_pdf_to_markdown(+ str(source),+ str(output),+ images=args.images,+ render_vector_figures=args.render_vector_figures,+ vector_figure_dpi=args.vector_figure_dpi,+ )+ ),)- return 0if __name__ == '__main__':- exit(main())+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/source_to_md/ppt_to_md.py b/skills/ppt-master/scripts/source_to_md/ppt_to_md.pyindex 6bd79116..c6774d6a 100644--- a/skills/ppt-master/scripts/source_to_md/ppt_to_md.py+++ b/skills/ppt-master/scripts/source_to_md/ppt_to_md.py@@ -39,6 +39,7 @@ if str(_SCRIPTS_DIR) not in sys.path:sys.path.insert(0, str(_SCRIPTS_DIR))from console_encoding import configure_utf8_stdio # noqa: E402+from _batch import run_path_batch # noqa: E402from _conversion_profile import write_conversion_profile_best_effort # noqa: E402from pptx import Presentation@@ -842,7 +843,7 @@ def convert_presentation_to_markdown(return markdown_content-def main() -> None:+def main() -> int:"""Run the CLI entry point."""parser = argparse.ArgumentParser(description="Convert PowerPoint files to Markdown",@@ -850,6 +851,8 @@ def main() -> None:epilog="""Examples:python ppt_to_md.py slides.pptx+ python ppt_to_md.py slides.pptx appendix.pptx+ python ppt_to_md.py ./decks -o ./markdownpython ppt_to_md.py slides.pptx -o output.mdpython ppt_to_md.py deck.ppsx -o notes/deck.md@@ -859,20 +862,22 @@ Supported formats:Legacy .ppt is not parsed directly. Resave it as .pptx or export it to PDF first.""",)- parser.add_argument("input", help="Input PowerPoint file")- parser.add_argument("-o", "--output", help="Output Markdown file")+ parser.add_argument("inputs", nargs="+", help="Input PowerPoint file(s) or directories")+ parser.add_argument(+ "-o",+ "--output",+ help="Output Markdown file for one input, or output directory for multiple inputs/directories",+ )args = parser.parse_args()- input_path = Path(args.input)-- if not input_path.is_file():- print(f"Error: PowerPoint file not found: {args.input}")- sys.exit(1)- output = args.output or str(input_path.with_suffix(".md"))- result = convert_presentation_to_markdown(str(input_path), output)- sys.exit(0 if result else 1)+ return run_path_batch(+ args.inputs,+ set(SUPPORTED_FORMATS),+ args.output,+ lambda source, output: bool(convert_presentation_to_markdown(str(source), str(output))),+ )if __name__ == "__main__":- main()+ raise SystemExit(main())diff --git a/skills/ppt-master/scripts/source_to_md/web_to_md.py b/skills/ppt-master/scripts/source_to_md/web_to_md.pyindex 1c550a78..4dfbe9ef 100644--- a/skills/ppt-master/scripts/source_to_md/web_to_md.py+++ b/skills/ppt-master/scripts/source_to_md/web_to_md.py@@ -43,7 +43,10 @@ if str(_SCRIPTS_DIR) not in sys.path:sys.path.insert(0, str(_SCRIPTS_DIR))from console_encoding import configure_utf8_stdio # noqa: E402-from _conversion_profile import write_conversion_profile_best_effort # noqa: E402+from _conversion_profile import ( # noqa: E402+ profile_path_for,+ write_conversion_profile_best_effort,+)configure_utf8_stdio()@@ -805,8 +808,13 @@ def simple_html_to_markdown_traversal(soup: Tag | BeautifulSoup | None) -> str:return md or ""-def process_url(url: str, output_file: str | None = None) -> tuple[bool, str, str | None]:- """Fetch, convert, and save one web page as Markdown."""+def process_url(url: str, output_file: str | None = None) -> tuple[bool, str, str | None, str | None]:+ """Fetch, convert, and save one web page as Markdown.++ Returns (success, url, error, output_path). output_path is the actual saved+ Markdown path (derived from the article title when no output_file is given),+ so a caller can locate a title-named file it did not choose upfront.+ """print(f"\n[Fetching] {url}")try:html = fetch_url(url)@@ -881,11 +889,27 @@ def process_url(url: str, output_file: str | None = None) -> tuple[bool, str, stprint(f" [OK] Saved: {output_path}")if profile_path:print(f" [OK] Conversion profile: {profile_path}")- return True, url, None+ return True, url, None, output_pathexcept Exception as e:print(f" [ERROR] {str(e)}")- return False, url, str(e)+ return False, url, str(e), None+++def _write_emit_result(result_file: str, url: str, markdown_path: str) -> None:+ """Write the actual saved path as JSON so a caller can locate the output."""+ md = Path(markdown_path).resolve()+ profile = profile_path_for(md)+ payload = {+ "input": url,+ "markdown": str(md),+ "conversion_profile": str(profile) if profile.is_file() else "",+ }+ try:+ Path(result_file).write_text(+ json.dumps(payload, ensure_ascii=False), encoding="utf-8")+ except OSError as exc:+ print(f" [WARN] Could not write --emit-result: {exc}")def main() -> None:@@ -897,6 +921,10 @@ def main() -> None:"-f", "--file", help="File containing URLs (one per line)")parser.add_argument("-o", "--output", help="Output file (single URL only)")parser.add_argument("-d", "--dir", help="Output directory")+ parser.add_argument(+ "--emit-result",+ help="On success, write the saved output path as JSON to this file "+ "(single-URL dispatcher use, so a title-named file can be located)")args = parser.parse_args()@@ -924,8 +952,10 @@ def main() -> None:for i, url in enumerate(targets):# Allow specific output file only if 1 URLout = args.output if (len(targets) == 1 and args.output) else None- success, url, err = process_url(url, out)+ success, url, err, out_path = process_url(url, out)results.append((success, url, err))+ if args.emit_result and success and out_path:+ _write_emit_result(args.emit_result, url, out_path)# Summarysuccess_count = sum(1 for r in results if r[0])