Skip to content

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

docs: demote Node.js from required fallback to rare-edge-case backup

hugohe378a00319f69f
diff --git a/AGENTS.md b/AGENTS.md
index 4bafc524..7f00bf57 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,8 +30,8 @@ PPT Master is an AI-driven presentation generation system. Through multi-role co
python3 skills/ppt-master/scripts/source_to_md/pdf_to_md.py <PDF_file>
python3 skills/ppt-master/scripts/source_to_md/doc_to_md.py <DOCX_or_other_file> # Native: .docx/.html/.epub/.ipynb; pandoc fallback: .doc/.odt/.rtf/.tex/.rst/.org/.typ
python3 skills/ppt-master/scripts/source_to_md/ppt_to_md.py <PPTX_file>
-python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL>
-node skills/ppt-master/scripts/source_to_md/web_to_md.cjs <URL>
+python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL> # auto-uses curl_cffi if installed (covers WeChat etc.)
+node skills/ppt-master/scripts/source_to_md/web_to_md.cjs <URL> # fallback only; use if curl_cffi is unavailable
# Project management
python3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169
diff --git a/CLAUDE.md b/CLAUDE.md
index 4066f978..1d01d92e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -15,8 +15,8 @@ PPT Master is an AI-driven presentation generation system. Through multi-role co
python3 skills/ppt-master/scripts/source_to_md/pdf_to_md.py <PDF_file>
python3 skills/ppt-master/scripts/source_to_md/doc_to_md.py <DOCX_or_other_file> # Native: .docx/.html/.epub/.ipynb; pandoc fallback: .doc/.odt/.rtf/.tex/.rst/.org/.typ
python3 skills/ppt-master/scripts/source_to_md/ppt_to_md.py <PPTX_file>
-python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL>
-node skills/ppt-master/scripts/source_to_md/web_to_md.cjs <URL>
+python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL> # auto-uses curl_cffi if installed (covers WeChat etc.)
+node skills/ppt-master/scripts/source_to_md/web_to_md.cjs <URL> # fallback only; use if curl_cffi is unavailable
# Project management
python3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169
diff --git a/README.md b/README.md
index a08ef728..04783a42 100644
--- a/README.md
+++ b/README.md
@@ -69,14 +69,13 @@ This project is my attempt to bridge the gap between **domain expertise** and **
### 1. Prerequisites
-| Dependency | Required? | What it does | If you skip it |
-|------------|:---------:|--------------|----------------|
-| [Python](https://www.python.org/downloads/) 3.10+ | ✅ **Yes** | Core runtime — everything depends on this | Nothing works |
-| [Node.js](https://nodejs.org/) 18+ | ❌ Optional | Converts WeChat articles and complex web pages to Markdown | You can still use PDF, DOCX, plain text, and simple URLs as source |
-| [Pandoc](https://pandoc.org/) | ❌ Optional | Converts legacy formats (`.doc`, `.odt`, `.rtf`, `.tex`, `.rst`, `.org`, `.typ`) to Markdown. `.docx`, `.html`, `.epub`, `.ipynb` are handled natively in Python — no pandoc needed. | You can still use PDF, DOCX, HTML, EPUB, Jupyter, plain text, and URLs as source |
+**You only need Python.** Everything else is installed via `pip install -r requirements.txt`.
+| Dependency | Required? | What it does |
+|------------|:---------:|--------------|
+| [Python](https://www.python.org/downloads/) 3.10+ | ✅ **Yes** | Core runtime — the only thing you actually need to install |
-> **TL;DR** — Install Python, run `pip install -r requirements.txt`, and you're ready to generate presentations. Install the rest only when you need them.
+> **TL;DR** — Install Python, run `pip install -r requirements.txt`, and you're ready to generate presentations.
<details open>
<summary><strong>Windows</strong> — see the dedicated step-by-step guide ⚠️</summary>
@@ -94,13 +93,32 @@ Quick version: download Python from [python.org](https://www.python.org/download
```bash
# macOS
brew install python
-brew install node # optional — for WeChat page conversion
-brew install pandoc # optional — only for legacy .doc/.odt/.rtf/.tex/.rst/.org/.typ
+pip install -r requirements.txt
# Ubuntu / Debian
sudo apt install python3 python3-pip
-sudo apt install nodejs npm # optional
-sudo apt install pandoc # optional — only for legacy .doc/.odt/.rtf/.tex/.rst/.org/.typ
+pip install -r requirements.txt
+```
+</details>
+
+<details>
+<summary><strong>Edge-case fallbacks</strong> — 99% of users don't need these</summary>
+
+Two external tools exist as fallbacks for edge cases. **Most users will never need them** — install only if you hit one of the specific scenarios below.
+
+| Fallback | Install only if… |
+|----------|-----------------|
+| [Node.js](https://nodejs.org/) 18+ | You need to import WeChat Official Account articles **and** `curl_cffi` (part of `requirements.txt`) has no prebuilt wheel for your Python + OS + CPU combination. In normal setups `web_to_md.py` handles WeChat directly through `curl_cffi`. |
+| [Pandoc](https://pandoc.org/) | You need to convert legacy formats: `.doc`, `.odt`, `.rtf`, `.tex`, `.rst`, `.org`, or `.typ`. `.docx`, `.html`, `.epub`, `.ipynb` are handled natively by Python — no pandoc required. |
+
+```bash
+# macOS (only if the above conditions apply)
+brew install node
+brew install pandoc
+
+# Ubuntu / Debian
+sudo apt install nodejs npm
+sudo apt install pandoc
```
</details>
diff --git a/README_CN.md b/README_CN.md
index 3c20341d..dbbba8ba 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -71,12 +71,13 @@ PPT Master 源于一个真实的痛点:在投融资和咨询工作中,我每
| 依赖项 | 是否必需 | 作用 | 不装会怎样 |
|--------|:--------:|------|-----------|
-| [Python](https://www.python.org/downloads/) 3.10+ | ✅ **必需** | 核心运行时——一切都依赖它 | 什么都跑不了 |
-| [Node.js](https://nodejs.org/) 18+ | ❌ 可选 | 将微信公众号文章、复杂网页转换为 Markdown | 仍可用 PDF、DOCX、纯文本、简单 URL 作为素材 |
-| [Pandoc](https://pandoc.org/) | ❌ 可选 | 将小众格式(`.doc`/`.odt`/`.rtf`/`.tex`/`.rst`/`.org`/`.typ`)转换为 Markdown。`.docx`、`.html`、`.epub`、`.ipynb` 已由 Python 原生处理,无需 pandoc。 | 仍可用 PDF、DOCX、HTML、EPUB、Jupyter、纯文本、URL 作为素材 |
+**只需装 Python 即可。** 其余依赖通过 `pip install -r requirements.txt` 一次装齐。
+| 依赖 | 是否必须 | 用途 |
+|------|:--------:|------|
+| [Python](https://www.python.org/downloads/) 3.10+ | ✅ **必需** | 核心运行时——唯一真正需要安装的东西 |
-> **一句话总结** — 装好 Python,跑一行 `pip install -r requirements.txt`,就可以开始生成 PPT 了。其余的用到时再装。
+> **一句话总结** — 装好 Python,跑一行 `pip install -r requirements.txt`,就可以开始生成 PPT 了。
<details open>
<summary><strong>Windows</strong> — 请看专门的手把手安装指南 ⚠️</summary>
@@ -94,13 +95,32 @@ Windows 需要一些额外步骤(PATH 设置、执行策略等)。我们为
```bash
# macOS
brew install python
-brew install node # 可选——用于微信公众号等网页转换
-brew install pandoc # 可选——仅用于 .doc/.odt/.rtf/.tex/.rst/.org/.typ 等小众格式
+pip install -r requirements.txt
# Ubuntu / Debian
sudo apt install python3 python3-pip
-sudo apt install nodejs npm # 可选
-sudo apt install pandoc # 可选——仅用于 .doc/.odt/.rtf/.tex/.rst/.org/.typ 等小众格式
+pip install -r requirements.txt
+```
+</details>
+
+<details>
+<summary><strong>边缘场景备用方案</strong> — 99% 的用户用不到</summary>
+
+下面两个外部程序只作为极端场景的兜底。**绝大多数用户根本不需要装**,只有遇到以下具体场景才装:
+
+| 备用方案 | 只在以下情况才装 |
+|---------|-----------------|
+| [Node.js](https://nodejs.org/) 18+ | 你需要抓取微信公众号文章,**且**你的 Python + 系统 + CPU 组合下 `curl_cffi`(`requirements.txt` 里已默认安装)没有预编译 wheel。正常安装下 `web_to_md.py` 已能通过 `curl_cffi` 直接抓微信。 |
+| [Pandoc](https://pandoc.org/) | 你需要转 `.doc`、`.odt`、`.rtf`、`.tex`、`.rst`、`.org`、`.typ` 这些小众格式。`.docx`、`.html`、`.epub`、`.ipynb` 已由 Python 原生处理,不需要 pandoc。 |
+
+```bash
+# macOS(仅在上述条件成立时才装)
+brew install node
+brew install pandoc
+
+# Ubuntu / Debian
+sudo apt install nodejs npm
+sudo apt install pandoc
```
</details>
diff --git a/docs/windows-installation.md b/docs/windows-installation.md
index b35e07c3..ae816566 100644
--- a/docs/windows-installation.md
+++ b/docs/windows-installation.md
@@ -80,15 +80,15 @@ If a `.pptx` file appears in `exports/` that opens in PowerPoint — **you're do
---
-## Step 6 — Optional Dependencies (install when needed)
+## Step 6 — Optional Enhancements (most users can skip this)
-| Dependency | How to install | Verify |
-|------------|----------------|--------|
-| **Node.js** — WeChat articles / complex web pages | Download LTS from [nodejs.org](https://nodejs.org/) | `node --version` → v18+ |
-| **Pandoc** — legacy formats only (`.doc`, `.odt`, `.rtf`, `.tex`, `.rst`, `.org`, `.typ`); `.docx`/`.html`/`.epub`/`.ipynb` work natively in Python | Download `.msi` from [pandoc.org](https://pandoc.org/installing.html) | `pandoc --version` |
-| **CairoSVG** — higher quality PNG fallbacks | Install [GTK3 Runtime](https://github.com/nickvdp/gtk3/releases), then `pip install cairosvg` | `python -c "import cairosvg"` |
+With Python and `requirements.txt` installed, you already have everything needed to generate presentations. The items below are **edge-case fallbacks and enhancements** — install only if you hit the specific scenario.
-> Skip CairoSVG if unsure. PPT Master auto-falls back to `svglib` (already installed via `requirements.txt`), which works fine for most cases.
+| Enhancement | Install only if… | How to install | Verify |
+|-------------|-----------------|----------------|--------|
+| **CairoSVG** — higher quality PNG fallbacks | You want crisper PNG fallbacks for Office versions that don't render SVG natively. `svglib` (already installed) is fine for most cases. | Install [GTK3 Runtime](https://github.com/nickvdp/gtk3/releases), then `pip install cairosvg` | `python -c "import cairosvg"` |
+| **Node.js** 18+ — WeChat fallback | You need to import WeChat Official Account articles **and** `curl_cffi` (part of `requirements.txt`) has no wheel for your Python version. Normally `web_to_md.py` handles WeChat through `curl_cffi`. | Download LTS from [nodejs.org](https://nodejs.org/) | `node --version` → v18+ |
+| **Pandoc** — legacy document formats | You need to convert `.doc`, `.odt`, `.rtf`, `.tex`, `.rst`, `.org`, or `.typ`. `.docx`/`.html`/`.epub`/`.ipynb` work natively in Python. | Download `.msi` from [pandoc.org](https://pandoc.org/installing.html) | `pandoc --version` |
---
diff --git a/docs/zh/windows-installation.md b/docs/zh/windows-installation.md
index 5330fa61..3300de57 100644
--- a/docs/zh/windows-installation.md
+++ b/docs/zh/windows-installation.md
@@ -83,15 +83,15 @@ python -c "import pptx; import fitz; print('All core dependencies OK')"
---
-## Step 6 — 可选依赖(用到时再装)
+## Step 6 — 可选增强(大多数用户可以跳过)
-| 依赖 | 安装方式 | 验证 |
-|------|---------|------|
-| **Node.js** — 微信公众号 / 复杂网页转换 | [nodejs.org](https://nodejs.org/) 下载 LTS 版安装 | `node --version` → v18+ |
-| **Pandoc** — 仅用于小众格式(`.doc`/`.odt`/`.rtf`/`.tex`/`.rst`/`.org`/`.typ`);`.docx`/`.html`/`.epub`/`.ipynb` 已由 Python 原生处理 | [pandoc.org](https://pandoc.org/installing.html) 下载 `.msi` 安装 | `pandoc --version` |
-| **CairoSVG** — 更高质量 PNG 后备图 | 安装 [GTK3 Runtime](https://github.com/nickvdp/gtk3/releases) 后 `pip install cairosvg` | `python -c "import cairosvg"` |
+装好 Python 和 `requirements.txt` 后,生成 PPT 的全部功能已经就绪。下面是**边缘场景的备用方案和增强项**——只有遇到对应的具体场景才需要装。
-> CairoSVG 不确定就跳过。PPT Master 会自动用 `svglib`(已随 `requirements.txt` 安装),大多数情况够用。
+| 增强项 | 只在以下情况才装 | 安装方式 | 验证 |
+|--------|-----------------|---------|------|
+| **CairoSVG** — 更高质量 PNG 后备图 | 你希望在不原生支持 SVG 的 Office 版本下获得更清晰的 PNG 后备图。`svglib`(已默认安装)足够大多数场景。 | 安装 [GTK3 Runtime](https://github.com/nickvdp/gtk3/releases) 后 `pip install cairosvg` | `python -c "import cairosvg"` |
+| **Node.js** 18+ — 微信备用 | 你需要抓微信公众号文章,**且** `curl_cffi`(`requirements.txt` 里已默认安装)在你的 Python 版本下没有预编译 wheel。正常安装下 `web_to_md.py` 已能通过 `curl_cffi` 直接抓微信。 | [nodejs.org](https://nodejs.org/) 下载 LTS 版安装 | `node --version` → v18+ |
+| **Pandoc** — 旧格式文档 | 你需要转 `.doc`、`.odt`、`.rtf`、`.tex`、`.rst`、`.org`、`.typ`。`.docx`/`.html`/`.epub`/`.ipynb` 已由 Python 原生处理。 | [pandoc.org](https://pandoc.org/installing.html) 下载 `.msi` 安装 | `pandoc --version` |
---
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index 56b1c610..b7fe8239 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -48,7 +48,7 @@ description: >
| `${SKILL_DIR}/scripts/source_to_md/doc_to_md.py` | Documents to Markdown — native Python for DOCX/HTML/EPUB/IPYNB, pandoc fallback for legacy formats (.doc/.odt/.rtf/.tex/.rst/.org/.typ) |
| `${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py` | PowerPoint to Markdown |
| `${SKILL_DIR}/scripts/source_to_md/web_to_md.py` | Web page to Markdown |
-| `${SKILL_DIR}/scripts/source_to_md/web_to_md.cjs` | WeChat / high-security sites to Markdown |
+| `${SKILL_DIR}/scripts/source_to_md/web_to_md.cjs` | Node.js fallback for WeChat / TLS-blocked sites (use only if `curl_cffi` is unavailable; `web_to_md.py` now handles WeChat when `curl_cffi` is installed) |
| `${SKILL_DIR}/scripts/project_manager.py` | Project init / validate / manage |
| `${SKILL_DIR}/scripts/analyze_images.py` | Image analysis |
| `${SKILL_DIR}/scripts/image_gen.py` | AI image generation (multi-provider) |
@@ -90,7 +90,7 @@ When the user provides non-Markdown content, convert immediately:
| PPTX / PowerPoint deck | `python3 ${SKILL_DIR}/scripts/source_to_md/ppt_to_md.py <file>` |
| EPUB / HTML / LaTeX / RST / other | `python3 ${SKILL_DIR}/scripts/source_to_md/doc_to_md.py <file>` |
| Web link | `python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL>` |
-| WeChat / high-security site | `node ${SKILL_DIR}/scripts/source_to_md/web_to_md.cjs <URL>` |
+| WeChat / high-security site | `python3 ${SKILL_DIR}/scripts/source_to_md/web_to_md.py <URL>` (requires `curl_cffi`; falls back to `node web_to_md.cjs <URL>` only if that package is unavailable) |
| Markdown | Read directly |
**✅ Checkpoint — Confirm source content is ready, proceed to Step 2.**
diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.md
index 5fe61a1b..a7a517a7 100644
--- a/skills/ppt-master/scripts/docs/conversion.md
+++ b/skills/ppt-master/scripts/docs/conversion.md
@@ -98,7 +98,7 @@ Legacy `.ppt` is not parsed directly. Resave it as `.pptx` or export it to PDF f
Convert web pages to Markdown and download images locally.
-Python version:
+### Python version (preferred)
```bash
python3 scripts/source_to_md/web_to_md.py https://example.com/article
@@ -107,14 +107,24 @@ python3 scripts/source_to_md/web_to_md.py -f urls.txt
python3 scripts/source_to_md/web_to_md.py https://example.com -o output.md
```
-Node.js version for WeChat or anti-bot pages:
+When `curl_cffi` is installed (included in `requirements.txt`), this script
+automatically impersonates a modern Chrome TLS fingerprint, which lets it
+fetch WeChat Official Accounts (`mp.weixin.qq.com`) and other sites that
+block Python's default TLS fingerprint. No extra flags needed. If
+`curl_cffi` is not available, it falls back to plain `requests`.
+
+### Node.js version (fallback)
+
+Retained as a backup for rare environments where `curl_cffi` can't be
+installed (e.g., uncommon Python + OS + CPU combinations without prebuilt
+wheels):
```bash
node scripts/source_to_md/web_to_md.cjs https://mp.weixin.qq.com/s/xxxx
-node scripts/source_to_md/web_to_md.cjs https://url1.com https://url2.com
```
-Use the Node.js version first for WeChat Official Accounts and similar high-security sites.
+For most users the Python version is sufficient — Node.js is no longer
+required for WeChat coverage.
## `rotate_images.py`
diff --git a/skills/ppt-master/scripts/project_manager.py b/skills/ppt-master/scripts/project_manager.py
index 276831d4..4ab37efc 100644
--- a/skills/ppt-master/scripts/project_manager.py
+++ b/skills/ppt-master/scripts/project_manager.py
@@ -55,6 +55,15 @@ DOC_SUFFIXES = {
WECHAT_HOST_KEYWORDS = ("mp.weixin.qq.com", "weixin.qq.com")
+def _curl_cffi_available() -> bool:
+ """Return whether curl_cffi is importable (enables Python TLS impersonation)."""
+ try:
+ import curl_cffi # noqa: F401
+ return True
+ except ImportError:
+ return False
+
+
def is_url(value: str) -> bool:
"""Return whether a string looks like an HTTP(S) URL."""
parsed = urlparse(value)
@@ -255,9 +264,16 @@ class ProjectManager:
)
def _import_url(self, url: str, markdown_path: Path) -> None:
+ # Prefer web_to_md.py: it uses curl_cffi internally when available,
+ # which handles WeChat and other TLS-fingerprint-blocked sites.
+ # Fall back to the Node.js version only when the URL is known to
+ # require TLS impersonation AND curl_cffi isn't installed.
host = urlparse(url).netloc.lower()
- if any(keyword in host for keyword in WECHAT_HOST_KEYWORDS):
- command = ["node", str(TOOLS_DIR / "source_to_md" / "web_to_md.cjs"), url, "-o", str(markdown_path)]
+ is_tls_sensitive = any(keyword in host for keyword in WECHAT_HOST_KEYWORDS)
+
+ if is_tls_sensitive and not _curl_cffi_available() and shutil.which("node"):
+ command = ["node", str(TOOLS_DIR / "source_to_md" / "web_to_md.cjs"),
+ url, "-o", str(markdown_path)]
else:
command = [
sys.executable,
diff --git a/skills/ppt-master/scripts/source_to_md/web_to_md.cjs b/skills/ppt-master/scripts/source_to_md/web_to_md.cjs
index 12701051..039c76e5 100644
--- a/skills/ppt-master/scripts/source_to_md/web_to_md.cjs
+++ b/skills/ppt-master/scripts/source_to_md/web_to_md.cjs
@@ -2,6 +2,11 @@
/**
* web_to_md.cjs - Web Page to Markdown Converter (Enhanced)
*
+ * STATUS: Fallback only. The Python version (web_to_md.py) now uses
+ * curl_cffi to impersonate a Chrome TLS fingerprint, which covers WeChat
+ * and other sites that previously required Node. Use this script only when
+ * curl_cffi cannot be installed on your platform.
+ *
* Usage:
* node skills/ppt-master/scripts/source_to_md/web_to_md.cjs <url> # Single URL
* node skills/ppt-master/scripts/source_to_md/web_to_md.cjs <url1> <url2> ... # Multiple URLs