Skip to content

Repository files navigation

WeChat Obsidian Bridge

项目介绍 / Project Introduction

中文

微信到 Obsidian 桥接工具:把微信资料沉淀为 Markdown、摘要和个人知识库素材。

English

WeChat-to-Obsidian bridge for turning WeChat materials into Markdown, summaries, and PKM assets.

使用方式 / Usage

中文

  1. 先阅读 SKILL.md,确认触发场景、输入要求和执行步骤。
  2. 按仓库 README 的安装方式复制或安装 Skill。
  3. 在真实任务中调用前,先用示例或测试脚本做一次小范围验证。

English

  1. Read SKILL.md first to understand triggers, inputs, and workflow steps.
  2. Install or copy the skill according to this README.
  3. Before using it on real work, run a small example or validation script.

入口与元信息 / Entry Points & Metadata

  • GitHub 仓库 / Repository: https://github.com/siuserxiaowei/wechat-to-obsidian
  • 默认分支 / Default branch: main
  • 主要语言 / Primary language: Python
  • 可见性 / Visibility: public
  • 仓库类型 / Repository type: source
  • Topics / 主题:knowledge-management, markdown, obsidian, wechat, weflow

本地运行 / Local Run

git clone https://github.com/siuserxiaowei/wechat-to-obsidian.git
cd wechat-to-obsidian
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python3 -m pytest

仓库结构 / Repository Map

路径 / Path 中文说明 English
README.md 项目入口说明,先读这里。 Main project entry point and orientation.
SKILL.md Skill 的核心说明、触发条件和执行步骤。 Core skill instructions, trigger rules, and workflow.
requirements.txt Python 依赖列表。 Python dependency list.
assets 图片、样式、数据等资源。 Images, styles, data, and other assets.
docs 文档或 GitHub Pages 输出目录。 Documentation or GitHub Pages output.
scripts 构建、同步、生成或维护脚本。 Build, sync, generation, or maintenance scripts.
tests 测试用例与验证脚本。 Tests and validation scripts.
LICENSE 许可证文件。 License file.
agents Agent 配置或平台适配文件。 Agent configuration or platform adapters.
configs 项目文件或目录。 Project file or directory.
launchd 项目文件或目录。 Project file or directory.
references 参考资料、规范或补充说明。 References, specifications, or supporting notes.

维护备注 / Maintenance Notes

  • 中文:当项目目标、在线入口、运行命令或目录结构变化时,同步更新本说明。
  • English: Keep this guide updated when the project purpose, live link, run commands, or structure changes.
  • 中文:修改代码、数据或生成页面后,优先运行相关构建、测试或校验命令。
  • English: After changing code, data, or generated pages, run the relevant build, test, or validation command.

安全与隐私 / Safety & Privacy

  • 中文:不要提交 API key、token、密码、cookie、私有链接或内部账号资料。
  • English: Do not commit API keys, tokens, passwords, cookies, private URLs, or internal account data.
  • 中文:公开 GitHub Pages 前,确认资料已脱敏并允许公开。
  • English: Before publishing GitHub Pages output, confirm the material is redacted and cleared for public release.

项目介绍 / Project Introduction

中文介绍:微信 Obsidian Bridge,把微信和 WeFlow 的聊天记录、链接、图片和文件导入 Obsidian Markdown 知识库。

English: A WeChat Obsidian bridge that imports WeChat and WeFlow chat records, links, images, and files into an Obsidian Markdown vault.

SEO 关键词 / SEO Keywords: WeChat, Obsidian, Markdown, PKM, chat export, 知识库

微信 Obsidian 桥:把微信里的聊天记录、文件传输助手、链接、图片、语音、视频和学习资料导入到 Obsidian vault,变成可搜索、可链接、可长期沉淀的 Markdown 知识库。

这个仓库不是一个单纯的备份脚本,而是一个面向个人知识管理的导入桥:

  • 通过可插拔 provider 读取本地微信会话,统一导入 Obsidian。
  • 默认仍用 jackwener/wx-cli;也可以接入 wechat-decrypt HTTP 服务或探测 wechat-mcp-macos
  • 如果 wx-cli 获取不到,可以用本地 wechat-cli-pkg.tar.gz 解压出来的 wechat-cli 二进制。
  • 仍支持从 WeFlow 导出的 JSON 或 WeFlow 本地 HTTP API 导入 Obsidian。
  • 在没有 WeFlow 的情况下,直接处理 macOS 微信 4.x 本地数据库,解密后导出指定聊天。
  • 把聊天按日期拆成 Markdown,并把能拿到的媒体文件放到 attachments/

截图预览

下面是示意截图,内容使用的是示例数据,不包含真实聊天隐私。

三条导入路线总览

WeFlow API 导入流程

不用 WeFlow 的直接解库流程

导入到 Obsidian 后的效果

三种方式对比

你想要的效果

1. 把 Obsidian 跟微信聊天记录打通

可以做到,但当前形态不是“安装一个 Obsidian 插件后自动同步微信”。

当前是这个链路:

微信
  -> wx-cli / wechat-decrypt / wechat-mcp-macos / 本地 wechat-cli 包 / WeFlow
  -> wechat2obsidian.py
  -> Obsidian vault 里的 Markdown + attachments
  -> Obsidian 搜索、标签、反链、图谱、Dataview 等能力

也就是说,它是一个“导入桥”,把微信数据写进 Obsidian vault。写进去之后,Obsidian 会把这些聊天记录当作普通 Markdown 笔记处理。

2. 在 Obsidian 里看到聊天记录、文件、聊天资料和聊天数据

可以看到大部分本地能拿到的内容:

内容 当前支持情况
文本聊天 支持,按日期生成 Markdown
文件传输助手 支持,推荐优先导入
群聊 / 私聊 支持,需要知道 talker / wxid / @chatroom
链接 / 公众号文章卡片 支持渲染为 Markdown 链接,取决于源数据字段
图片 / 视频 / 语音 / 表情 支持复制或引用本地媒体,取决于 WeFlow 或微信本地是否已缓存
附件文件 支持复制到 attachments/,取决于源数据能否给出本地路径
聊天数据统计 当前会生成 manifest;更复杂的年报/统计建议先用 WeFlow,再把结果或数据导入 Obsidian
微信收藏 通过 WeFlow 导出或聊天里的收藏/转发内容导入更稳;直接解析 favorite.db 仍属于后续增强

不能保证 100% 拿到的内容:

  • 只存在云端、没有落到本地缓存的图片/视频/文件。
  • 小程序、视频号、朋友圈等复杂云端内容。
  • 微信本身没有保存完整原件的历史媒体。
  • WeFlow/API 没有返回本地路径的媒体文件。

导入方式

不是只能使用 WeFlow。现在推荐先用通用 provider 入口选择读取后端,再把结果统一写入 Obsidian。

方式 推荐度 适合场景 说明
wx-cli provider 默认 日常同步、文件传输助手、群聊/私聊 jackwener/wx-cli 负责读取微信记录,本仓库负责导入 Obsidian
wechat-decrypt provider 优先备用 微信 4.x、本地数据库解密、需要 HTTP/MCP 能力 启动 wechat-decrypt 的本地服务后,通过 HTTP provider 导入
wechat-mcp-macos provider 探测中 macOS MCP 生态 当前先做安装/config/ready 探测;稳定 stdio 包装后再作为导入后端
本地 wechat-cli 包 备用 wx-cli 装不上或获取不到时 使用你给的 wechat-cli-pkg.tar.gz 解压后的二进制
WeFlow API / JSON 兼容 已经在用 WeFlow 的场景 继续支持,但不再是第一推荐
直接解微信本地库 最后兜底 需要底层控制 需要 Frida 抓 key、解密 DB,步骤更多

推荐顺序:

wx-cli provider -> wechat-decrypt provider -> 本地 wechat-cli 包 -> WeFlow API/JSON -> 直接解微信本地库

不建议把 PyWxDump、已移除的 sjzar/chatlog 原仓库或偏 Windows 的 chatlog_alpha 作为默认依赖;这些项目可能存在兼容、维护或合规风险。WDecipher 当前明确不支持 macOS,也不纳入默认路线。

通用 provider 入口,推荐

查看当前可用后端:

python3 scripts/wechat2obsidian.py providers

查看某个后端的修复提示:

python3 scripts/wechat2obsidian.py provider-doctor --provider wechat-decrypt \
  --base-url http://127.0.0.1:5678

用默认 wx-cli provider 导入文件传输助手:

python3 scripts/wechat2obsidian.py import-wechat \
  --provider wx-cli \
  --chat-id filehelper \
  --vault ~/Documents/Obsidian\ Vault \
  --folder "微信渠道" \
  --subfolder "文件传输助手" \
  --page-size 500 \
  --max-messages 20000

wechat-decrypt provider 导入:

# 先在 wechat-decrypt 仓库启动本地服务,默认监听 http://127.0.0.1:5678
python3 main.py

python3 scripts/wechat2obsidian.py import-wechat \
  --provider wechat-decrypt \
  --base-url http://127.0.0.1:5678 \
  --chat-id "1234567890@chatroom" \
  --vault ~/Documents/Obsidian\ Vault \
  --folder "微信渠道" \
  --page-size 500 \
  --max-messages 50000

import-wechat 和旧的 import-wx-cli 使用同一套 Markdown 渲染、附件处理、分页、去重和 manifest 审计字段。默认不会保存 provider 原始响应;只有显式传 --raw-output 时,才会把本地 raw response 保存到导入目录,便于排查。

路线 A:wx-cli 导入,默认 provider

安装并初始化 jackwener/wx-cli

npm install -g @jackwener/wx-cli
codesign --force --deep --sign - /Applications/WeChat.app
killall WeChat && open /Applications/WeChat.app
sudo wx init

确认能列出会话:

python3 scripts/wechat2obsidian.py wx-sessions --limit 500 --json

建议优先从输出里复制唯一的 username,例如 filehelperwxid_**@chatroom。群名可能重复,折叠会话里也可能出现占位项;如果用群名称导入且匹配到多个会话,CLI 会停止并列出候选,避免悄悄导错群。

导入文件传输助手:

python3 scripts/wechat2obsidian.py import-wx-cli \
  --chat-id filehelper \
  --vault ~/Documents/Obsidian\ Vault \
  --folder "微信渠道" \
  --subfolder "文件传输助手" \
  --since 2026-01-01 \
  --until 2026-05-01 \
  --page-size 500 \
  --max-messages 20000 \
  --media

导入某个群聊:

python3 scripts/wechat2obsidian.py import-wx-cli \
  --chat-id "1234567890@chatroom" \
  --vault ~/Documents/Obsidian\ Vault \
  --folder "微信渠道" \
  --subfolder "重要群聊/群名" \
  --since 2026-04-01 \
  --until 2026-05-01 \
  --page-size 500 \
  --max-messages 50000

也可以用 --chat-name "群名称" 让 CLI 先通过 wx-sessions 解析会话;只有唯一匹配时才会继续导入。导入 manifest 会记录 resolved_sessionpages_fetchedraw_message_countdeduped_countfiltered_countdropped_count、首尾消息时间和 warnings,方便判断这次是否真的抓全。

路线 B:本地 wechat-cli 包导入,备用

如果 wx-cli 获取不到,就用你本地的包:

tar -xzf /Users/siuserxiaowei/Library/Containers/com.tencent.xinWeChat/Data/Documents/xwechat_files/wxid_276exkqyuyd422_20a2/msg/file/2026-04/wechat-cli-pkg.tar.gz -C /tmp/wechat-cli-pkg

导入:

python3 scripts/wechat2obsidian.py import-wx-cli \
  --binary /tmp/wechat-cli-pkg/wechat-cli-pkg/wechat-cli/node_modules/@canghe_ai/wechat-cli-darwin-arm64/bin/wechat-cli \
  --chat-id "群 chatroom id 或 filehelper" \
  --vault ~/Documents/Obsidian\ Vault \
  --folder "微信渠道" \
  --subfolder "wx-cli导入" \
  --since 2026-04-01 \
  --until 2026-05-01

路线 C:WeFlow 本地 API 导入,兼容

  1. 打开 WeFlow。
  2. 进入设置,开启 API 服务
  3. 如果设置了 Access Token,复制 token;如果 token 是空的,可以不传。
  4. 在终端进入本仓库:
cd /Users/siuserxiaowei/Desktop/dont哥\ 对谈/wechat-to-obsidian
  1. 看看 WeFlow API 是否能列出会话:
python3 scripts/wechat2obsidian.py weflow-sessions --keyword 文件

如果你想列出更多会话:

python3 scripts/wechat2obsidian.py weflow-sessions --limit 200
  1. 导入文件传输助手到 Obsidian:
python3 scripts/wechat2obsidian.py import-weflow-api \
  --talker filehelper \
  --vault ~/Documents/Obsidian\ Vault \
  --folder "微信渠道" \
  --subfolder "文件传输助手" \
  --media

如果 WeFlow 配了 token:

python3 scripts/wechat2obsidian.py import-weflow-api \
  --talker filehelper \
  --vault ~/Documents/Obsidian\ Vault \
  --folder "微信渠道" \
  --subfolder "文件传输助手" \
  --token "你的 WeFlow Token" \
  --media

限制日期范围:

python3 scripts/wechat2obsidian.py import-weflow-api \
  --talker filehelper \
  --vault ~/Documents/Obsidian\ Vault \
  --folder "微信渠道" \
  --subfolder "文件传输助手" \
  --since 2026-01-01 \
  --until 2026-05-01 \
  --media

导入后 Obsidian 里会出现类似结构:

Obsidian Vault/
└── 微信渠道/
    └── 文件传输助手/
        ├── 2026-01/
        │   ├── 2026-01-03.md
        │   └── attachments/
        ├── 2026-02/
        │   ├── 2026-02-18.md
        │   └── attachments/
        └── _weflow_import_manifest.json

路线 D:导入 WeFlow 导出的 JSON

如果你已经在 WeFlow 里导出了 JSON 文件:

python3 scripts/wechat2obsidian.py import-weflow-json \
  --input ~/Downloads/weflow-export.json \
  --vault ~/Documents/Obsidian\ Vault \
  --folder "微信渠道" \
  --subfolder "某个会话"

这条路线适合一次性导入,也适合你先在 WeFlow 里筛选/导出,再进 Obsidian。

路线 E:不用 wx-cli/WeFlow,直接解微信本地库

这条路线更底层,适合 WeFlow 不可用或你想直接处理 macOS 微信 4.x 本地数据库。

安装依赖:

python3 -m pip install -r requirements.txt

检查环境:

python3 scripts/wechat2obsidian.py doctor

签名一个可被 Frida attach 的微信副本:

python3 scripts/wechat2obsidian.py sign-wechat \
  --dest ~/Desktop/WeChat-Obsidian.app

抓取数据库 key:

python3 scripts/wechat2obsidian.py capture-keys \
  --wechat-app ~/Desktop/WeChat-Obsidian.app \
  --launch \
  --wait 300

抓 key 时,在微信里打开你要导出的聊天,比如 文件传输助手

解密 message_0.db

USER_DIR=$(python3 scripts/wechat2obsidian.py locate-user --print-path)

python3 scripts/wechat2obsidian.py decrypt \
  --db "$USER_DIR/db_storage/message/message_0.db" \
  --out /tmp/message_0.decrypted.db

列出可导出的会话:

python3 scripts/wechat2obsidian.py list-targets \
  --db /tmp/message_0.decrypted.db \
  --limit 50

导出文件传输助手:

python3 scripts/wechat2obsidian.py export-chat \
  --db /tmp/message_0.decrypted.db \
  --target filehelper \
  --vault ~/Documents/Obsidian\ Vault \
  --folder "微信渠道" \
  --subfolder "文件传输助手" \
  --with-senders

路线 F:模块化工具链 + 自动化

如果你要管理几百个群、想要增量更新、需要按类型分类和去重,路线 E 的一站式 CLI 不够用。本仓库另外提供了一套模块化脚本(基于 Jane-xiaoer/wechat-to-obsidian 扩展),每个脚本职责单一,组合使用:

脚本 来源 职责
scripts/extract_key.py upstream Frida hook CCKeyDerivationPBKDF 抓 SQLCipher 密钥
scripts/decrypt_db.py upstream AES-256-CBC 按页解密 SQLCipher v4 数据库
scripts/export_chat.py upstream 单会话导出 → Markdown 日报 + 附件
scripts/list_chats.py 本仓库 跨多个 message DB 列出所有会话,附真实联系人/群名
scripts/batch_export.py 本仓库 批量导出,支持 --top N / --skip-existing / 容错
scripts/import_real_files.py 本仓库 msg/file/ msg/video/ 真实文档按月份 + 类型双视图入库(硬链接,不占额外空间)
scripts/dedup_attachments.py 本仓库 SHA-256 找重复附件,可选择硬链接合并
scripts/dedup_msgfile.py 本仓库 清理微信原始 msg/file/ 内的真实重复文件
scripts/categorize_attachments.py 本仓库 按文件类型生成 _by_type/ 软链接视图
scripts/cleanup_cache.py 本仓库 清理 cache/ 目录的老月份缓存

一键启动

# 1. 抓密钥(一次性,登录后点开你想导出的所有会话)
./run_capture_key.sh

# 2. 增量更新(解密 + 列表 + 批量导出 + 真实文件入库)
./update.sh

update.sh 支持环境变量自定义:

WX_USER_WXID=wxid_xxx_xxxx \
VAULT="$HOME/Documents/MyVault" \
./update.sh

自动化(macOS launchd 每周自动跑)

详见 USAGE.md

Obsidian 里怎么看

导入完成后,打开你的 Obsidian vault:

  1. 左侧文件树会看到 微信渠道/文件传输助手/2026-xx/2026-xx-xx.md
  2. 每天一个 Markdown 文件。
  3. 每条消息是一个时间戳小标题。
  4. 图片、视频、语音、文件会尽量放在同月份的 attachments/
  5. 链接类消息会尽量渲染成 Markdown 链接。
  6. 你可以用 Obsidian 全文搜索、标签、反链、图谱、Dataview 等插件继续整理。

Obsidian 配置文档

已经准备了一份可以直接放进 Obsidian 的配置手册:

docs/Obsidian-微信资料库配置.md

里面包含推荐目录、WeFlow 设置、导入命令、Dataview 查询、搜索语法、日常同步流程和排错清单。

当前不是 Obsidian 插件

这点很重要:

  • 不能直接在 Obsidian 社区插件里搜索安装。
  • 不是安装 Obsidian 后自动同步微信。
  • 当前需要你运行一次 CLI 命令,把数据导入 vault。
  • 后续可以在这个仓库上继续做一个真正的 Obsidian 插件,把按钮、同步任务、配置界面都放进 Obsidian。

常用命令速查

# 检查环境
python3 scripts/wechat2obsidian.py doctor

# 列出可插拔微信读取后端
python3 scripts/wechat2obsidian.py providers

# 检查某个 provider
python3 scripts/wechat2obsidian.py provider-doctor --provider wx-cli

# 列 wx-cli 会话
python3 scripts/wechat2obsidian.py wx-sessions --limit 100

# 通用 provider 导入入口
python3 scripts/wechat2obsidian.py import-wechat \
  --provider wx-cli \
  --chat-id filehelper \
  --vault ~/Documents/Obsidian\ Vault \
  --folder "微信渠道" \
  --subfolder "文件传输助手" \
  --page-size 500 \
  --max-messages 20000

# 从 wx-cli 导入文件传输助手
python3 scripts/wechat2obsidian.py import-wx-cli \
  --chat-id filehelper \
  --vault ~/Documents/Obsidian\ Vault \
  --folder "微信渠道" \
  --subfolder "文件传输助手" \
  --page-size 500 \
  --max-messages 20000 \
  --media

# 从 WeFlow JSON 导入
python3 scripts/wechat2obsidian.py import-weflow-json \
  --input ~/Downloads/weflow-export.json \
  --vault ~/Documents/Obsidian\ Vault \
  --folder "微信渠道"

一键群日报流水线

每天只跑一条命令:

python3 scripts/group_daily_pipeline.py \
  --chat "付费群名称" \
  --date yesterday \
  --vault ~/Documents/Obsidian\ Vault \
  --folder "微信渠道" \
  --subfolder "付费群/付费群名称"

它会自动完成:

读取群聊 -> 写入 Obsidian 原始记录 -> 生成干货分析 -> 生成日报 HTML/PNG

批量跑多个群,复制配置样例:

cp configs/group_daily.example.json configs/group_daily.json

编辑 configs/group_daily.json 里的 vault 和 groups,然后运行:

python3 scripts/group_daily_pipeline.py \
  --config configs/group_daily.json \
  --date yesterday

如果你要把 HTML/PNG 发布到 GitHub Pages,在配置里填写:

"publish": {
  "repo": "/path/to/github-pages-repo",
  "base_url": "https://你的用户名.github.io/你的仓库",
  "push": true,
  "privacy": "demo"
}

发布后的路径固定是:

https://你的用户名.github.io/你的仓库/reports/<公开slug>/<日期>/

privacy: "demo" 是默认公开模式:GitHub Pages 只展示匿名演示页,不会公开真实群名、成员名、头像、聊天原文、链接、词云和具体话题。每个群可以配置对外显示名:

{
  "chat": "真实群名",
  "title": "真实群名",
  "slug": "private-slug",
  "public_title": "一群",
  "public_slug": "group-1"
}

只有你明确把 privacy 改成 "full",才会把完整日报 HTML 复制到 GitHub Pages。公开演示不建议这样做。

如果要在跑完后同步提醒飞书和 Telegram,复制本地环境变量样例:

cp configs/group_daily.env.example configs/group_daily.env

编辑 configs/group_daily.env,填入:

TELEGRAM_BOT_TOKEN=你的 Telegram Bot Token
TELEGRAM_CHAT_ID=你的 Telegram Chat ID
FEISHU_WEBHOOK_URL=你的飞书自定义机器人 Webhook
FEISHU_WEBHOOK_SECRET=飞书机器人签名密钥,可选

然后在 configs/group_daily.json 里保留 env_file 并打开通知:

"env_file": "configs/group_daily.env",
"notify": {
  "telegram": {
    "enabled": true,
    "bot_token_env": "TELEGRAM_BOT_TOKEN",
    "chat_id_env": "TELEGRAM_CHAT_ID"
  },
  "feishu": {
    "enabled": true,
    "webhook_url_env": "FEISHU_WEBHOOK_URL",
    "secret_env": "FEISHU_WEBHOOK_SECRET"
  }
}

通知内容只包含日期、群名、消息数、活跃人数和日报链接,不会把原始聊天内容发到 IM。

本机每天早上自动跑,建议用 Codex 自动任务或系统定时任务执行:

cd /Users/siuserxiaowei/Desktop/dont哥\ 对谈/wechat-to-obsidian
python3 scripts/group_daily_pipeline.py --config configs/group_daily.json --date yesterday

安全说明

  • 只处理你自己的微信数据。
  • 不要把 key log、解密后的数据库、聊天附件上传到公开仓库。
  • .gitignore 已经默认排除数据库、key log、导出目录等敏感文件。
  • 优先使用 jackwener/wx-cli,避免自己维护 Frida 抓 key 和数据库解密链路。

参考项目

这个项目参考和吸收了这些公开项目的思路:

  • Jane-xiaoer/wechat-to-obsidian
  • jackwener/wx-cli
  • zhuyansen/wx-favorites-report
  • hicccc77/WeFlow
  • ILoveBingLu/CipherTalk

详细说明见 NOTICEreferences/upstream-projects.md

联系我 / Contact

想交流 AI 工具、内容自动化、SEO、私域增长或项目合作,可以扫码加我微信。

For collaboration on AI tools, content automation, SEO, private-domain growth, or product experiments, scan the WeChat QR code below.

WeChat QR code / 微信二维码

关键词 / Keywords: WeChat, Obsidian, Markdown, PKM, AI tools, AI automation, GitHub Pages, SEO

About

微信到 Obsidian 桥接工具:把微信资料沉淀为 Markdown、摘要和个人知识库素材。 | WeChat-to-Obsidian bridge for turning WeChat materials into Markdown, summaries, and PKM assets.

Topics

Resources

Stars

33 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages