Export-Zhihu-Collections

Export-Zhihu-Collections

项目介绍

一个功能强大的知乎收藏夹导出工具，支持将知乎收藏夹（公开和私密）批量导出为 Markdown 格式文件。支持自定义输出路径、跨平台兼容、图片下载和 Obsidian 兼容格式。支持使用大模型API一键生成文章总结。

同时提供 MCP Server，可被 AI Agent (如 Claude Code) 直接调用，为大模型提供保存知乎收藏夹的能力。

主要特性

• 📚 批量处理: 支持同时处理多个收藏夹
• 📂 自定义输出: 支持用户指定输出目录
• 🖥️ 跨平台兼容: 支持 Windows、Linux、macOS 等系统
• ✨ 智能去重: 自动检查已存在文件，避免重复下载
• 🖼️ 图片下载: 自动下载并保存文章中的图片
• 📝 Obsidian 兼容: 输出的 Markdown 格式完全兼容 Obsidian
• 📈 实时日志: 支持实时日志刷新，立即显示处理进度
• 🔍 自动收藏夹获取: 通过独立脚本自动获取用户收藏夹列表
• 🛠️ 健壮错误处理: 单个文章失败不影响整体处理流程
• 🔧 增强调试支持: 自动生成调试文件，便于问题排查
• 🤖 MCP 支持: 提供 MCP Server，可被 AI Agent 调用

两种运行方式

方式一：命令行运行（传统方式）

适合直接在终端运行导出任务。

安装

pip install -r requirements.txt

配置文件设置

首先创建主配置文件：

# 复制配置示例文件
cp config_examples.json config.json

编辑 config.json 文件，配置你的收藏夹信息：

{
  "zhihuUrls": [
    {
      "name": "收藏夹名称",
      "url": "https://www.zhihu.com/collection/123456789"
    },
    {
      "name": "另一个收藏夹",
      "url": "https://www.zhihu.com/collection/987654321"
    }
  ],
  "outputPath": "/path/to/your/output/directory",
  "os": "linux"
}

其中zhihuUrls的获取可看

自动获取收藏夹（可选）

如果你想自动获取所有收藏夹，可以先运行：

python fetch_collections.py

这将自动更新 config.json 文件中的收藏夹列表。

运行主程序

python main.py

方式二：MCP Server 运行（AI Agent 方式）

适合被 Claude Code 或其他 AI 工具集成调用。

安装 MCP 依赖

# 安装MCP包
pip install mcp

启动 MCP Server

python mcp_server.py

Server 会通过 stdio 通信，可以在 Claude Code 或其他 MCP 客户端中使用。

可用工具

list_collections

# 返回格式化的收藏夹列表

export_collection

参数：

• collection_url (必需): 收藏夹URL
• collection_name (可选): 收藏夹名称
• output_dir (可选): 输出目录

# 示例
export_collection(
    collection_url="https://www.zhihu.com/collection/123456789",
    collection_name="Python学习",
    output_dir="my_downloads"
)

get_collection_info

参数：

• collection_url (必需): 收藏夹URL

search_collections

参数：

• keyword (必需): 搜索关键词

在 Claude Code 中使用

在项目根目录的 CLAUDE.md 或用户配置文件中的 MCP 配置段添加服务器配置：

{
  "mcpServers": {
    "zhihu-collections": {
      "command": "python",
      "args": ["mcp_server.py"],
      "env": {},
      "cwd": "你的项目路径"
    }
  }
}

然后就可以用自然语言调用：

• "列出我的知乎收藏夹"
• "导出收藏夹 https://www.zhihu.com/collection/123456789"
• "搜索包含Python的收藏夹"
• "获取收藏夹 https://www.zhihu.com/collection/123456789 的文章数量"

配置选项说明

基本配置

• zhihuUrls: 收藏夹列表，每个收藏夹包含名称和 URL
• outputPath: 自定义输出路径（可选，留空使用默认路径）
• os: 操作系统类型（可选，留空自动检测）

支持的操作系统和路径格式

• Windows: "D:\\Documents\\ZhihuExports" 或 "D:/Documents/ZhihuExports"
• Linux/Unix: "/usr/local/share/zhihu-exports"
• macOS: "~/Documents/ZhihuExports"
• Cygwin: "/cygdrive/d/Documents/ZhihuExports"

私密收藏夹访问

对于私密收藏夹，需要创建 cookies.json 文件：

[
  {"name": "cookie_name", "value": "cookie_value"},
  {"name": "another_cookie", "value": "another_value"}
]

输出结果

文件结构

输出目录/
├── 收藏夹名称1/
│   ├── 文章1.md
│   ├── 文章2.md
│   └── assets/
│       ├── image1.jpg
│       └── image2.png
├── 收藏夹名称2/
├── logs/
│   ├── debug_20240101_120000.log
│   └── 20240101_120000.json
└── debug/
    ├── debug_answer_123456.html
    └── debug_post_789012.html

默认输出位置

• 默认路径: 项目目录下的 downloads/ 文件夹
• 自定义路径: 在 config.json 中指定 outputPath
• 图片存储: 每个收藏夹目录下的 assets/ 文件夹
• 日志文件: 输出目录下的 logs/ 文件夹
• 调试文件: 输出目录下的 debug/ 文件夹（保存无法解析的页面HTML）

故障排除

常见问题

1. 内容下载失败

   • 查看 downloads/debug/ 目录中的HTML文件分析页面结构
   • 检查网络连接和cookies是否有效
   • 确认文章URL是否可正常访问

2. 日志文件为空

   • 程序已修复了日志实时刷新问题
   • 如仍有问题，请检查输出目录的写入权限

3. TypeError: cannot unpack non-iterable NoneType object

   • 该问题已在v2.1版本中修复
   • 如仍遇到，请更新到最新版本

4. 专栏文章返回"该文章链接被404"但浏览器能正常打开

   • v2.1版本新增了智能内容检测和精准错误分析
   • 检查debug目录中的HTML文件了解具体原因
   • 可能需要更新cookies或页面结构发生变化

调试支持

• 日志文件: downloads/logs/debug_*.log 包含详细的处理信息
• 调试HTML: downloads/debug/debug_*.html 保存无法解析的页面
• 测试脚本: test/ 目录包含各种功能测试脚本

BUG 反馈

若您在使用过程中遇到任何问题，请在 issue 中提供 BUG 信息。为了方便我复现并解决该问题，请务必附上问题报错的提示或者相关网址。

建议

若您有任何建议，欢迎在 issue 中发起讨论

更新日志

v2.3 反爬机制绕过

• 🔄 API 备用机制: 当 HTML 请求返回 403 时，自动调用知乎 API (/api/v4/answers/{id}?include=content) 获取回答内容
• 📦 流式下载: 专栏文章使用流式下载，解决大文章（如图片多的长文）的网络中断问题
• 🔁 重试机制: 专栏文章添加 3 次重试，提高下载成功率
• 🔐 Headers 增强: 更新请求 Headers 以模拟现代浏览器，减少被反爬拦截的概率

v2.2 MCP 支持

• 🤖 MCP Server: 新增 mcp_server.py，支持被 AI Agent 直接调用
• 📋 4个工具: 提供 list_collections / export_collection / get_collection_info / search_collections 工具
• 🔌 标准协议: 遵循 MCP 协议，支持 Claude Code 等主流 AI 工具集成

v2.1 增强功能

• 🚀 实时日志系统: 支持实时日志刷新和立即显示处理进度
• 🛠️ 健壮错误处理: 修复了 TypeError 等关键错误，单个文章失败不影响整体处理
• 🔍 增强HTML解析: 支持多种知乎页面结构，提高内容获取成功率
• 🔧 调试文件生成: 自动保存无法解析的页面HTML到 debug/ 目录供分析
• 🔄 自动收藏夹获取: 新增 fetch_collections.py 独立脚本自动获取收藏夹列表
• 📊 详细错误日志: 记录具体错误信息和堆栈跟踪，便于问题定位
• 🎯 智能内容检测: 当标准CSS选择器失效时，自动启用智能算法检测文章内容
• 🔍 精准错误分析: 区分404、登录要求、权限问题等不同错误类型

v2.0 新增功能

• ✨ 批量处理多个收藏夹
• ⚙️ 配置文件系统 (config.json)
• 📂 自定义输出路径支持
• 🖥️ 跨平台路径处理
• ✨ 智能文件去重功能
• 📈 详细处理日志系统
• 🔄 向后兼容旧版配置文件

Todo

• 优化抓取速度
• 增加更多导出格式支持
• GUI 界面开发
• 第三方大模型API支持