Multiwfn 在线版手册：拉取、转换与使用

归档日期 2026-10-15 ｜ 作者 Tian Lu（sobereva）｜ 源站 http://sobereva.com/multiwfn/manual/公告 http://sobereva.com/783《Multiwfn在线版手册已上线！！！》(2026-Oct-13)产物落点：.\manuals\multiwfn\online\（md\ + assets\figures\ + INDEX.md）

本文记录三件事：为什么要拉、怎么拉和怎么转、拉回来怎么用。写给人看，所以把理由、证据和踩过的坑都留在正文里，方便日后复查或重做。

0. 一句话结论

2026-10-13，Multiwfn 作者 sobereva 发布了官方在线版手册。我们把它整体归档到本地，转成 Markdown，保留 LaTeX 公式、660 张插图和页面间的超链接。在检索和阅读上，这一版全面优于此前由 PDF 转换的 2026.9.1\ 版；后者降级为离线兜底和 PDF 页码回溯之用。

1. 起因：为什么要做这件事

Multiwfn 的手册过去只有 PDF。官网曾有一个 "online manual"，但那是把 PDF 直接转成 HTML 的产物，作者本人在网页上声明它过时、不可信——所以本 hub 之前的规矩是"手册以包内 PDF 为准"，并按书签把 1154 页切成 84 节、转成了本地 Markdown（即 2026.9.1\）。

这本 PDF 转换版有两个绕不过去的硬伤：

• • 公式全丢。PDF 里的公式是图形，文字层抽不出来，转出来只剩"…can be represented as"后面一片空白。
• • 插图全丢。转换时关了图片提取，0 张图进库。

2026-10-13 的公告改变了前提。作者说这份在线版是他亲手转换、又花了一周多反复打磨校对做出来的，和 PDF 版会同步维护。他给了六个理由：可以直接链接到某个小节、加载快、不用反复下新版 PDF、正文互引都做成超链接、对搜索引擎友好、对 AI 友好（便于被爬取、便于引用）。最后一条正对本 hub 的用途。

于是"必须忍受公式和插图丢失"就不再成立了。剩下的问题只是：这份在线版能不能完整、干净地拿下来。

2. 拉取：拿了什么、有多大

目标站是 http://sobereva.com/multiwfn/manual/，一套 MkDocs 1.6.1 + Material 9.7.7 生成的静态站（页脚 generator 元数据可见）。作者提到它与 Shermo 的在线手册用同一套框架和转换方法。

盘点结果：

页面结构与旧 PDF 版对得上：86 个节页 = 旧版 84 个编号节 + 第 1 章概览 + 第 4 章前言。

一个省事的发现：站点暴露了 MkDocs Material 的全文检索索引 /search/search_index.json（3.2 MB），里面是每一页、每一小节的完整文本。拿它可以一次性核对全站内容是否齐全，不必逐页抓。

最终产物放进了 manuals\multiwfn\online\：

online\  INDEX.md            ← 90 页清单（节号 | 标题 | 文件）  README.md           ← 入口指针  CONVERSION-NOTES.md ← 本文件  md\                 ← 90 个 md，3.02 MB  assets\figures\     ← 660 张插图（ch4\ 581 + ch5\ 3 + sec3-*\ 76）

3. 转换：路线、理由与踩过的坑

3.1 工具选型

环境里没有 pandoc；按本机纪律，装任何包都要先经批准，所以不去 pip install。查了一圈，mcp_env 环境里已经有 bs4 和 markdownify——正好够用，于是整条转换链在 mcp_env 里跑，没有新增任何依赖。

3.2 只取正文

MkDocs 生成的页面带着顶栏、侧边导航、页脚等外壳。正文都在 <article class="md-content__inner md-typeset"> 里，用 BeautifulSoup 选这一个节点，把外壳整体丢掉，再交给 markdownify。

3.3 五处关键处理

这五处决定了成品好不好用，逐条记下"问题—做法—为什么"。

① 去掉 ¶ 永久链接。 MkDocs 给每个标题都挂了一个 <a class="headerlink">¶</a>。转成 Markdown 后会变成 ## 标题¶，是噪音。转换前统一 decompose() 掉。

② 命令输入序列还原成代码块。 作者用 <p class="mw-cmd"> 包裹"在 Multiwfn 里依次输入什么"的片段（内部用 <em> 和 <br> 分行），全站共 599 处。直接转出来会变成一堆斜体行，看着像正文。做法是先把 <br> 换成换行、把非断行空格归一，再整段包成 <pre><code>——转成 Markdown 就是标准的围栏代码块。这几段恰是手册里最常用的操作步骤，值得单独处理。

③ 交叉引用改成本地链接。 正文里到处是 "see Section 3.100.8" 这类引用，在网页上是可以点的 href="../sec-.../"。归档后这些相对路径失效，改成指向本地文件 sec-*.md，并保留小节锚点（例如 sec-4-2-topology-analysis.md#421-...）。全站改出 1081 处本地链接。指向站点其它资源（如作者主页 ../Tian_Lu.html）的相对链接，则补全成源站绝对 URL，联网时仍可用。

④ 图片路径归一。 网页里的图片是 ../assets/figures/...。归档后 md 放在 md\、图片放在 assets\figures\，两者正好同层，所以这个相对路径天然成立，只需统一成 ../assets/figures/... 即可，不必重写。

⑤ 关掉 markdownify 的转义。 markdownify 默认会把 _、* 转义（_ → \_），这会破坏 LaTeX 公式。关掉 escape_underscores 和 escape_asterisks 两项后，`

` 之类的公式原样保留。

3.4 两个拦路坑

坑一：sec-3-300 这一页死活下不来。

90 页里只有它一页，在不加参数的情况下反复超时、收到 0 字节。做了一组对照请求才看清：

结论是这一页在边缘节点（Server: ESA）被无条件以 gzip 变体提供，而客户端完全不带 Accept-Encoding 时，这个缓存对象会让连接悬住。--http1.1 照样失败，说明与 HTTP 版本无关。修复办法很简单：批量下载一律加 --compressed，让 curl 声明并自行解压。加上之后 0.16 秒就下来了。

坑二：PowerShell 把 -and 当成了参数名。

下载脚本里我写了这样一句守卫：

if (Test-Path $out -and (Get-Item $out).Length -gt 2000) { ... }   # 报错：找不到与参数名称 'and' 匹配的参数

PowerShell 把 -and 解析成了 Test-Path 的一个参数（因为第一个操作数没加括号），同时 (Get-Item $out) 对尚未存在的文件报"路径不存在"。结果这个 if 条件求值失败、被当作假，网页照样照常下载——纯属噪音。它的唯一副作用是"已存在则跳过"的幂等守卫失效了（初次运行本就没有文件可跳，所以没造成损失）。正确写法是给每个操作数都加上括号：

if ((Test-Path $out) -and ((Get-Item $out).Length -gt 2000)) { ... }

3.5 验证

转换完成后按项核对，全部通过：

4. 质量对比：为什么值得换

2026.9.1\ 是旧版（PDF 转），online\ 是新版（在线 HTML 转）。六个维度：

分工也就清楚了：检索和阅读走online\；2026.9.1\ 留着做两件事——离线兜底（在线的要联网），以及按 PDF 页码回溯（旧版保留了页码锚点）。

5. 使用

5.1 先查 INDEX，再 rg

拿到一个需求，先翻 INDEX.md 定位到节，再对文件检索。例如"电子激发分析"对应参考节 sec-3-21-electron-excitation-analysis.md、教程节 sec-4-18-electron-excitation-analysis.md。

# 找配置参数（跨全库）rg -i -n "Multiwfnpath" .\manuals\multiwfn\online\md\# 只列命中文件（最省上下文）：先看范围，再决定读哪段rg -i -l "cubegen" .\manuals\multiwfn\online\md\# 找公式——旧 PDF 版搜不到（公式全丢），此版可搜（LaTeX 源）rg -n "\\\\\[" .\manuals\multiwfn\online\md\sec-3-21-electron-excitation-analysis.md# 列出某节所有小节标题（拿锚点，可拼深链）rg -n "^#{2,3} " .\manuals\multiwfn\online\md\sec-3-21-electron-excitation-analysis.md

（手册里的 Multiwfnpath、-silent、批处理规程与作者文章 #612 是同一套内容，可互查——文章快照在 ..\..\cache\sobereva\。）

5.2 什么时候仍需 firecrawl

只有两种情况：内容没归档（其它 sobereva 文章、论坛帖），或者要确认源站是否已经更新。

同一条"找 cubegen"的需求，两条路实测（2026-10-15）：

本地 rg 比 firecrawl 快 200–400 倍、0 credit、上下文可控（可以只回文件名）。走 firecrawl 的话，一次"先搜再抓"约 10.6 秒、3 credit、约 8.6 KB 上下文。

判据：先查本地，一条命令命中即止；未命中或需时效性才 firecrawl。 这也正是本 hub 一贯的规矩——本地缓存为主，网络是补漏。

5.3 与 hub 其它件的关系

• • md\（内容）↔ INDEX.md（路由）↔ assets\figures\（图）
• • ..\2026.9.1\ 旧 PDF 版：离线兜底、PDF 页码回溯
• • ..\..\cache\sobereva\ 作者文章快照（#331、#772 等）：与手册互补
• • ..\..\index\sobereva-index.md 文章→任务路由表

优先级链不变：机器事实（env_facts.md）> 手册原文/文章 > 模型记忆。

6. 已知局限（用前须知）

1. 1. 标题里有字面 **。作者的 md 源把页题写成 # **3.21 ...**，所以转出来的标题文本带星号。纯外观问题，不影响 rg。
2. 2. 图内文字没有 OCR。图片以 ![](../assets/figures/...) 形式保留，带 alt 文本；图里的参数只能看图。旧 PDF 版的 OCR 也仅覆盖第 4 章截图，且个别字符会错。
3. 3. 快照不是 canon。源站持续更新，引用关键参数前若疑过时，需在线复核（与 cache\sobereva\ 同一条纪律）。
4. 4. 在线版本身没有独立的 sec-3-300 图目录层级，该节 3 张图归在 figures\sec3-300\ 下，已在库。

7. 复现与更新

整条管线四步，脚本在 %TEMP%\opencode\multiwfn-online\：

Phase 0  curl.exe 串行下载 90 页 HTML（务必加 --compressed）Phase 1  扫所有页面提取 figures/* 引用，逐张下载到 assets\figures\（保留子目录）Phase 2  mcp_env python：bs4 取 article.md-content__inner → markdownify 转 md           - 删 a.headerlink           - p.mw-cmd → 围栏代码块           - 链接：../sec-*/ → 本地 sec-*.md(#anchor)；其余相对链接绝对化           - 图片：../assets/figures/*           - escape_underscores / escape_asterisks 关掉Phase 3  生成 INDEX.md

脚本：convert.py（转换）、mkindex.py（索引）、verify.py（校验）。重转 = 删掉 md\ 后依次跑 convert.py、mkindex.py，再跑 verify.py 核对。

更新：源站会变，务必按版本锚定的规矩来——新快照放进新的日期子目录（如 online-2027xxxx\），不要覆盖本目录。

8. 成本与证据

• • 拉取阶段 0 firecrawl credit：页面和图片都用 curl.exe 直取，转换在本地完成。
• • 本次基准测试：净耗 2 credit（scrape 1 + search 2 − 反馈退 1）。
• • 关键证据指针：
• • 公告：http://sobereva.com/783
• • 全文索引：http://sobereva.com/multiwfn/manual/search/search_index.json
• • 请求对照矩阵：见 §3.4
• • 各项计数：见 §2、§3.5、§5.2

9. 备忘与未决

• • index\sobereva-index.md 里指向 Multiwfn 手册的条目，是否改为指向 online\ 版——待定。
• • 作者提到 Shermo 的在线手册用同一套框架，是否也照此归档——待定。
• • 本文件与 README.md 的分工：README 是指针，正文与考据都在本文件。