中文 | English below
这份文档解决一个问题:MagicMD 没按预期工作时,你先看哪里、跑什么命令、该带什么信息反馈。
MagicMD 只处理公开文章页面。登录、付费墙、验证码、私有内容和平台访问限制不属于支持范围。遇到这些情况时,工具会尽量保留已经拿到的内容,并在报告里记录 warning 或失败原因。
先确认运行环境:
magicmd doctor脚本、CI 或 Agent 需要机器可读结果时:
magicmd doctor --json它会检查:
- Python 和 MagicMD 版本
- 配置文件是否能解析
- 输出目录是否可写
- Camoufox 是否可用
- 微信公众号、掘金、CSDN、通用网页的默认抓取方式
如果你是在源码目录里运行,还没有全局安装:
uv run magicmd doctornpm 包只是一个轻量入口,真正运行的是 PyPI 版 MagicMD CLI:
uvx --from "magicmd==0.7.1" magicmd所以只安装 Node.js 还不够,本机还需要 uvx。
macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | shWindows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"也可以不走 npm,直接安装 Python CLI:
uv tool install magicmd
pipx install magicmd微信公众号、掘金、CSDN 默认使用浏览器模式抓取。如果 doctor 里 Camoufox 不可用,先确认当前环境能启动浏览器依赖。
常见处理方式:
uv run magicmd doctor如果你是通过 PyPI 安装:
magicmd doctor如果问题只发生在某个站点,保留输出目录里的 extraction-report.json。里面会记录平台、抓取方式、阶段、重试次数和 warning。
这通常是平台访问限制,不一定是 MagicMD 代码坏了。
常见情况:
- 原文需要登录或微信内访问
- 页面触发验证码或风控
- 视频链接带防盗链,复制出来后浏览器直接打开会 403
- 动态资源已经过期
MagicMD 会尽量做到:
- 能提取视频链接时保留链接
- 不能提取时保留占位说明
- 图片能下载时写入
images/ - 抓取或下载失败时写入
extraction-report.json
如果视频链接本身被微信限制,MagicMD 不会绕过防盗链。
先看输出目录:
output/article-title/
├── article.md
├── extraction-report.json
└── images/
检查三件事:
article.md里图片路径是否指向images/images/里是否真的有文件extraction-report.json里是否有 media warning
微信公众号里有些小动图只是编辑器装饰或占位素材。MagicMD 会过滤一部分空动图和装饰图,避免 Markdown 里出现无意义图片。
掘金有些链接会经过平台跳转页。MagicMD 会尽量还原 title 或跳转参数里的真实目标链接,减少打开时进入风险提示页。
如果某个链接仍然打不开,请反馈:
- 原文链接
article.md中对应链接片段- 浏览器里原始链接元素截图或说明
CSDN 页面里常见的问题包括:
- 代码块混入复制按钮、行号或“AI 写代码”控件
- Mermaid / SVG 图在页面里不是标准 Markdown
- 文章目录链接指向页面内锚点,转换后可能失效
- 某些代码块内容由前端脚本重排
MagicMD 已经针对真实样本做过清洗,但 CSDN 页面形态很多。如果某篇文章仍然错位,请按下面的反馈格式给信息。
重复跑一批链接时,建议使用:
magicmd batch urls.txt -o output/ --skip-existing这样已经生成过的内容包会跳过,只继续处理没完成的链接。
如果你确认要重新生成同名输出包:
magicmd batch urls.txt -o output/ --overwrite开 GitHub Issue 时,尽量带上这些信息:
## 原文链接
https://...
## 使用命令
magicmd "https://..." -o output/
## 问题描述
例如:代码块错位 / 图片缺失 / 链接不能跳转 / 视频打不开 / 标题层级不对
## 附件或片段
- 输出目录里的 `extraction-report.json`
- `article.md` 中有问题的片段
- 原文截图和转换后截图不要上传 token、cookie、私有文章内容或账号信息。
This document answers one question: when MagicMD does not behave as expected, what should you check first, what command should you run, and what information should you include in a report?
MagicMD only targets public article pages. Login-only pages, paywalls, CAPTCHA, private content, and platform access controls are out of scope. In those cases, MagicMD keeps as much extractable content as possible and records warnings or failure reasons in the reports.
Check the runtime:
magicmd doctorFor machine-readable output in scripts, CI, or agents:
magicmd doctor --jsonIt checks:
- Python and MagicMD versions
- config parsing
- output directory writability
- Camoufox availability
- default fetch mode for WeChat, Juejin, CSDN, and generic pages
If you are running from the source tree:
uv run magicmd doctorThe npm package is a thin entrypoint. It runs the PyPI CLI through:
uvx --from "magicmd==0.7.1" magicmdThat means Node.js alone is not enough. uvx must also be available.
macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | shWindows:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"You can also install the Python CLI directly:
uv tool install magicmd
pipx install magicmdWeChat, Juejin, and CSDN use browser fetching by default. If doctor says Camoufox is unavailable, first confirm your environment can start the browser dependency:
magicmd doctorIf the problem only happens on one site, keep extraction-report.json. It records the platform, fetcher, stage, retry count, and warnings.
These are usually platform restrictions, not necessarily a MagicMD bug.
Common cases:
- the original article requires login or in-WeChat access
- the page triggers CAPTCHA or risk control
- video links are protected and return 403 when opened directly
- dynamic resources have expired
MagicMD tries to:
- keep video links when they can be extracted
- keep placeholders when they cannot
- download images into
images/when possible - record fetch and media failures in
extraction-report.json
MagicMD does not bypass WeChat hotlink protection.
Check the output package:
output/article-title/
├── article.md
├── extraction-report.json
└── images/
Look at:
- whether image paths in
article.mdpoint toimages/ - whether files exist in
images/ - whether
extraction-report.jsoncontains media warnings
Some WeChat GIFs are editor decorations or placeholders. MagicMD filters some empty or decorative assets so the Markdown does not keep meaningless images.
Some Juejin links pass through a redirect page. MagicMD tries to restore the direct target from the title attribute or redirect parameters.
If a link still fails, include:
- original article URL
- the related
article.mdlink snippet - a screenshot or note showing the original link element
CSDN pages often include:
- copy buttons, line counters, or AI-code widgets inside code blocks
- Mermaid / SVG diagrams that are not standard Markdown
- in-page TOC anchors that may not survive conversion
- code blocks rearranged by frontend scripts
MagicMD already cleans several real-world samples, but CSDN has many page variants. If an article still converts poorly, use the feedback format below.
When rerunning the same URL list:
magicmd batch urls.txt -o output/ --skip-existingExisting packages are skipped, and unfinished links continue.
If you want to regenerate matching packages:
magicmd batch urls.txt -o output/ --overwriteWhen opening a GitHub Issue, include:
## Original URL
https://...
## Command
magicmd "https://..." -o output/
## What went wrong
For example: code block mismatch / missing image / broken link / failed video / wrong heading depth
## Attachments or snippets
- `extraction-report.json`
- the problematic `article.md` snippet
- original and converted screenshotsDo not upload tokens, cookies, private article content, or account information.