知识星球一键归档：从复制抓取脚本到自动保存 Markdown

我原来保存知识星球内容，需要先打开 Chrome，按 Option + Command + J 打开开发者控制台，把「知识星球抓取脚本（含图片版）.js」复制进去。等脚本抓到内容后，再导出 JSON，调用 zsxq-json-to-md 技能，把帖子转换成 Markdown，放入对应的资料库文件夹。

这条流程能用，但每次都要重复复制、下载、找文件、调用技能。于是我让 Codex 把现有的两个脚本串起来，做成「油猴 + 本地归档助手」。

现在日常操作变成了：双击启动文件 → 打开星球 → 点击「抓取并归档」。抓取仍然需要等待，但中间的文件搬运和转换可以自动完成。

本文记录的是我在 macOS、Chrome 上实际搭建和使用的流程。当前本机脚本版本为 1.0.3。这是一套个人工具的操作与搭建笔记，文中没有提供完整安装包；如果还没有这些程序，需要先按后面的搭建要求准备，不能只装油猴就直接使用。

一、这套工具分别做什么

知识星球一键归档流程示意图

三个部分各有分工：

油猴（Tampermonkey）：在知识星球网页上自动运行抓取脚本，显示操作面板，省掉每次打开控制台粘贴代码。
本地归档助手：接收浏览器抓到的数据，备份 JSON，并运行转换程序。
JSON 转 Markdown 脚本：把每篇帖子保存成独立文件，按年份放置，并跳过已存在的帖子。

原来的技能里已经有可以独立运行的转换脚本，所以归档时直接运行它即可，不必每次再找 AI 操作。Codex 负责搭建和维护工具，日常抓取与转换由程序执行。

本地助手监听 127.0.0.1:18761，使用本机生成的令牌验证请求。浏览器把数据交给这台电脑上的助手，没有另设一个云端转换服务。

二、第一次需要准备哪些文件

下面用一个示例资料库说明结构，路径和星球 ID 都是占位示例：

星球资料库/
├── 知识星球抓取脚本（含图片版）.js
├── zsxq_example/
│   └── 2026/
│       └── 日期-时间-正文摘要-唯一ID.md
└── 一键归档助手/
    ├── 启动知识星球归档.command
    ├── prepare.py
    ├── server.py
    ├── verify.py
    ├── pyproject.toml
    ├── uv.lock
    ├── 使用说明.md
    ├── 知识星球一键归档.user.js
    ├── .local-token
    ├── folders.json
    └── JSON备份/
        └── 星球ID/
            └── 导出时间-随机标识.json

prepare.py 把原来的抓取脚本包装成油猴脚本，加入本地归档功能，并生成本机专用的安装脚本。server.py 负责安装说明页、文件夹列表和归档操作。folders.json 记住每个星球上次使用的保存目录。

转换脚本可以仍放在技能目录中，但助手里的 CONVERTER 路径必须指向本机实际存在的 split_json_to_md_online_images.py。换电脑或移动技能目录后，需要调整这里的路径。

Python 环境用 uv 管理

已有完整助手项目时，进入其目录执行一次：

uv sync
uv run prepare.py
chmod +x "启动知识星球归档.command"

如果从零创建项目，用 uv init --bare --name zsxq-one-click "一键归档助手" 初始化，再放入程序文件。这几个 Python 程序当前只用标准库，不需要额外安装第三方依赖；后续增加依赖时用 uv add。

没有安装 uv 的电脑，可以参考 uv 官方安装说明。我的启动文件查找的是 $HOME/.local/bin/uv；如果你的 uv 在其他位置，需要让维护者调整启动文件。

这些是首次搭建步骤。配好以后，日常使用不用输入命令。

三、安装油猴，并开启用户脚本权限

1. 先确认是否已经安装

点击 Chrome 右上角的拼图图标，查看扩展列表。如果已有「篡改猴」或「Tampermonkey」，可以跳过安装。

没有的话，从 Tampermonkey 官方网站进入 Chrome 的安装入口，确认添加扩展。

2. 打开正确的开关

在 Chrome 地址栏输入下面的地址并回车：

chrome://extensions/

找到「篡改猴 / Tampermonkey」，点击「详细信息」，往下找到 「允许运行用户脚本」，把右侧的灰色开关打开。

我在这里卡过一次：说明写的是「允许用户脚本」，但我的 Chrome 界面写的是「允许运行用户脚本」。它们指的是同一个功能，不需要去油猴的脚本编辑器里寻找。

这个开关与「已启用」「允许访问文件网址」不同。扩展已经启用，不代表已经允许运行用户脚本。我的方案通过本机 HTTP 服务安装脚本，不需要为此开启文件网址访问。

不同 Chrome 版本的界面可能不同。若没有用户脚本开关，按 Tampermonkey 官方权限说明检查是否需要在扩展管理页开启开发者模式。

四、启动本地助手，安装归档脚本

1. 在 Finder 中双击启动文件

打开「一键归档助手」文件夹，双击：

启动知识星球归档.command

它会准备脚本、启动本地服务，并用 Chrome 打开「知识星球一键归档」说明页。终端窗口会显示助手已启动，保持窗口打开即可，不需要输入命令。

启动页的地址以 http://127.0.0.1:18761/ 开头，后面带本机访问令牌。因此，不建议自己拼接安装地址，也不要分享这个完整地址。

2. 点击安装脚本

在说明网页找到第三步，点击 「安装『知识星球一键归档』脚本」。

Chrome 会打开油猴的安装确认页，显示脚本名称和版本。首次安装点击「安装」；已经装过时会显示「更新」。

如果点击后下载了一个 .user.js 文件，可以在油猴管理面板的「实用工具」中找到导入文件入口，选择刚下载的文件。不要导入别人电脑生成的本机专用脚本，因为其中的令牌与本地助手不匹配。

3. 打开具体星球并刷新

打开知识星球，正常登录，点击左侧某个星球。进入具体星球后，按 Command + R 刷新，右侧应出现「知识星球一键归档」面板。

连接成功时，状态显示：

已连接本地助手，请确认保存文件夹

看到这个状态和可选择的文件夹，才说明网页脚本与本机助手都准备好了。

五、第一次归档：先少量试运行

1. 先选抓取范围

网页当前显示的列表决定抓取范围。例如想保存星主的帖子，可以先点击网页上的「只看星主」；想处理某个时间范围，可以先用网页提供的日期筛选。

助手不会自动替你把所有筛选条件改成全量。抓取前先确认当前星球、列表和时间范围。

2. 选择原来的保存文件夹

在面板「保存文件夹」下拉框中，选择已有的星球目录。例如我保存阳志平老师帖子的目录是 zsxq_yangzhiping，就继续选它。

下拉框也会出现一个类似 zsxq_group_123456789 的选项。它是以星球 ID 命名的备用目录，用于还没有对应文件夹的星球。出现这个选项不代表目录已经创建，实际归档时才会创建。

已有资料库时优先选择原目录，才能利用已有文件去重。成功归档后，助手会记住星球与目录的对应关系。

3. 点击「抓取并归档」

脚本会尝试展开正文、收集帖子并向下滚动。面板显示已收集的条数和图片数。

第一次建议只运行一小会儿，然后点击 「停止并归档」。这个按钮会结束当前抓取，并把已收集内容交给本地助手保存。

随后打开保存目录，检查几篇文章的作者、时间、正文、图片链接和评论。确认符合预期以后，再处理更大的范围。

4. 读懂结果

新版面板只显示简短结果，例如：

归档完成：新增 16 篇，跳过重复 1 篇。

这表示收集的内容中有 16 篇新文件，另有 1 篇已存在。不是抓取失败，也不表示整个星球只有这些帖子。

详细转换日志在「查看详细日志」中，需要时再展开。日志可以在区域内滚动，不会把操作面板撑成整屏长条。

六、以后每天怎么用

日常只需要重复下面四步：

双击 启动知识星球归档.command，保持服务窗口打开。
在 Chrome 进入要保存的星球，确认筛选条件，并刷新页面。
检查保存目录，点击「抓取并归档」。
等待自动归档，或随时点击「停止并归档」。

当前脚本每轮等待、抓取和滚动，连续 12 轮没有新增内容时结束并归档，大约是一分钟。“没有新增”只是脚本的停止条件，不是已经完整抓到全部历史内容的证明。 网络加载、页面结构和筛选都可能影响结果。

浏览器标签页处于后台时，当前脚本会暂停抓取；切回这个页面后继续。切换到另一个星球后，要重新刷新，避免把不同星球的内容混在一起。

使用结束后，关闭服务窗口或按 Control + C 停止本地助手。当前版本没有配置登录后自动启动，因此重新开机后需要再次双击启动文件。

七、文件保存在哪里，图片是否下载了

每篇帖子单独保存为 Markdown，并默认按年份归档：

zsxq_example/
├── 2025/
└── 2026/
    └── 2026-10-02-0830-正文摘要-唯一ID.md

正文以外，转换程序会按抓到的数据写入图片链接、正文链接、附件名称、评论和话题标识。日期无法按转换器预期格式解析时，文件会进入 _日期未知，便于后续检查。

去重沿用原有转换器：根据正文和日期计算内容指纹，再递归扫描目标目录的已有文件名。它能跳过已有帖子，但不会自动更新已有文件中的新增评论或修改后的正文；正文或日期变化也可能产生新的指纹。

原始 JSON 另存于 一键归档助手/JSON备份/星球ID/，方便排查或重新转换。网页上的「手动备份 JSON」则把当前收集内容另行下载到浏览器下载目录。

“含图片”在这里指的是 Markdown 中保留在线图片链接，当前助手没有把图片下载为本地文件。在线地址失效、需要登录或网络不可用时，图片可能无法显示。附件当前只记录名称，不下载附件本身。

如果想做长期离线收藏，需要单独增加图片下载、相对路径替换和失败重试，不能把当前版本当作完整离线备份。

八、脚本有新版时，怎样更新

本地程序文件更新后，油猴中已安装的脚本不会因此立即变化。需要再安装一次新版脚本：

在 Finder 中双击 启动知识星球归档.command，重新打开说明网页。
点击第三步的「安装『知识星球一键归档』脚本」。
油猴显示新旧版本，点击 「更新」。
回到知识星球，按 Command + R 刷新。

找不到安装网页时，重新双击启动文件即可，不用在一堆浏览器标签里翻找，也不用复制整段代码。

如果更新涉及 server.py，需要先结束原来的助手，再双击启动；只更新生成的网页脚本时，安装新版并刷新星球页面即可。

九、这次实际遇到的问题

点「抓取并归档」没有反应

先看面板状态。如果显示「请进入具体星球后刷新页面」，即使左侧已经选中了星球，也可以先按 Command + R。

我第一次就是这样：脚本在首页加载时记录了页面地址，随后点击星球属于站内切换，脚本没有重载，仍然认为没有进入具体星球。更新后，连接时会再次尝试识别当前星球；刷新仍然是最直接的恢复办法。

如果状态提示先启动本地助手，则双击启动文件、保持终端窗口打开，再刷新网页。不要只反复点击绿色按钮。

停止后面板变得特别长，拖不动

最初版本把转换程序的完整输出直接当作状态文字，其中包含很长的绝对路径。面板没有高度限制，被日志撑出屏幕后，标题也看不到了，自然很难拖回来。

后来改成短结果、折叠日志、限制面板高度，并把拖动位置约束在屏幕内。版本 1.0.3 还增加了面板被网站重新渲染移除后的恢复逻辑。

如果仍看到旧界面，应按上一节更新油猴脚本，再刷新网页。已经成功写入的 Markdown 不会因刷新而删除。

为什么会有一个 zsxq_group 文件夹

它是备用目录，不是另一套必须使用的资料库。已有自己的目录时，在下拉框选择原目录即可。

同一个星球既保存“全部帖子”又保存“只看星主”时，可能需要两个目录。当前记忆按星球 ID 保存，不会为每一种筛选分别记忆，所以切换筛选后仍要检查保存位置。

结果里“新增 0 篇”是不是失败

如果同时显示跳过了重复帖子，通常说明这些内容已经保存过。若收集条数一直是 0，应检查页面是否有帖子、是否仍在加载，以及网站结构是否改变。

评论只保存当前脚本实际抓到的内容。它没有保证自动展开全部评论或访问每一条详情，正文、评论、图片都应以抽样核对为准。

十、让 Codex 帮忙搭建时，可以这样说

如果你已经有抓取脚本和 JSON 转 Markdown 程序，可以把它们的位置提供给 Codex，再交代下面的要求：

请把我现有的知识星球网页抓取脚本和 JSON 转 Markdown 程序，
改造成 macOS + Chrome 上可以双击启动的一键归档工具。

1. 使用 uv init 建立 Python 项目，uv sync 同步环境；
   如需依赖用 uv add，运行程序用 uv run。
2. 把现有抓取逻辑包装为油猴脚本，只在知识星球网页运行。
3. 在面板提供保存目录、抓取并归档、停止并归档、手动备份 JSON。
4. 本地助手只监听 127.0.0.1，用本机令牌验证请求，
   将保存目录限制在我指定的资料库内。
5. 复用现有转换程序，备份原始 JSON、按年份保存、跳过重复帖子。
6. 记住星球 ID 对应的目录，兼容站内切换后的星球识别。
7. 连续无新增时结束，但明确提醒这不保证抓取完整。
8. 状态只显示简短结果；完整日志折叠，面板能拖动且不会移出屏幕。
9. 提供可双击的 .command 启动文件和清楚的安装、更新说明。
10. 先在临时目录验证转换、去重、目录记忆和访问限制，
    再在已登录的真实网页上少量验证正文、图片、评论和面板操作。
11. 不公开令牌、个人绝对路径或付费星球正文。

请根据实际页面验证，不要只通过代码语法检查就宣称全流程可用。

我会把原始抓取脚本、转换程序和助手保留在自己的资料库中。.local-token、生成的本机专用 .user.js、带令牌的安装地址和原始 JSON 都不放进公开博客。

这次改造最大的收获，是把一个“每次都要重新教 AI 怎么做”的任务，变成了可以重复执行的本地流程。首次搭建仍需要一点耐心，但之后保存内容的入口就只剩下双击启动和一个网页按钮。