首页
看点啥
插画图片
首页 科技看点 weread-guizang：实践指南

weread-guizang：实践指南

2026-10-05 0

在项目中评估weread-guizang，可以先看清用途边界：把微信读书 skills 还原成开箱即用的工具 —— 取书、搜索、笔记回顾、Anki 导出、MCP 接入 - GitHub -等相关能力。把它放到网页与浏览器自动化流程中，最容易暴露的是登录状态、页面变化和失败恢复往往不稳定，不能只看演示是否顺利。更实际的做法是选择一个权限清楚的网页流程做端到端短测，同时核对会话保持、元素定位、错误恢复和工件留存，不要直接在关键项目上。如果团队属于需要可观测网页自动化流程的开发者，它有继续测试的理由；否则先看替代方案会更省时间。

KEQingFeng/weread-guizang 项目截图 1

归藏 · weread-guizang

把微信读书的书籍以md格式导出到本地，也把外部内容（公众号文章、知乎 / 小红书 / X 的帖子、RSS 订阅、视频）收进同一个本地书架：整本导出为 Markdown、本地多格式阅读器，外加一个 AI 只搭手不代笔的写作台。

方案

归藏把微信读书那套只服务 AI Agent、且只读的接口还原成可用的本地工具，并补齐它没有的部分：

三项能力都在本机完成，服务只侦听 127.0.0.1，不经第三方服务器。

它可以做什么

一句话：把「读写」这件事的产出——正文、划线、想法、笔记、导图、画板，以及你自己写下的稿子——都落到你自己的文件夹里，顺带把你在别处读的东西（公众号、知乎 / 小红书 / X、RSS 订阅、视频）和你在别处记的东西（flomo 导出的便签）也收进同一个本地书架。

取书与导出

本地阅读器

边读边记

笔记脑图与画板

书架

剪藏

订阅阅读器

视频转笔记

AI 小结：一个入口，两种模式

便签（flomo）

写作平台

个人主界面与两张热力图

侧边栏与导航

统计、回顾与同步

界面自己盯得住后端的成色

给 AI Agent 用

它在细节上在意什么

这个工具是围绕几件很具体的事在做取舍，写在这里，方便你判断它合不合你的用法。

东西是你的，就得放在你能看见的地方。 取回的书、导入的书、笔记、脑图、画板，统一放在 ~/Documents/归藏/；笔记跟着书走，跟着目录一起搬走就行。应用包本身始终只读、可以随便挪；运行时要写的（虚拟环境、缓存、登录态）都在 ~/Library/Application Support/归藏/。设置里的「清除本地数据」不会碰你的书——它清的是登录态、索引、封面、下载中间件这些它自己攒的东西。

不替你连任何第三方。 服务只绑 127.0.0.1，不经任何中转。唯一的外发是你自己在设置里填的接口：划句翻译 / 问助手会把你选中的那一段发给你填的 AI 接口，视频转笔记在选了云端转写时把音频发给你填的转写接口。归藏不预置地址、不代传，没填就不发——所以没配 AI 时它只存转写全文，而不是偷偷把音频传出去。

密钥只回显末 4 位。 Key 存在本机 cache/config.json（权限 600），界面上永远只看到尾巴四位；所有按目录 id 取路径的接口都过一遍正则 + realpath，图片写盘前校验魔数。

大东西不拦门。 Chromium 那 368 MB 是取书的硬前置，所以放在配置页等；转写模型是 GB 级的，就改成进门之后在后台下——视频页那排灯会告诉你「准备中 37%」。组件下载失败也不堵住取书：它只是视频那条线暂时不能用，进门后在设置里补一下就行。

删东西都给一次反悔。 划掉一条笔记，右下角那条提示上挂一颗「撤销」，点一下就原样放回去；订阅的清理先跑一遍「会删多少条」给你看，点了才真动手。比起弹个确认框拦在前面问一遍，这样更省事。

抓回来的东西是数据，不是命令。 订阅正文、剪藏正文一律按数据渲染（Markdown 渲染器关掉 HTML 直通），标签和正文里写什么都不会被执行。

两处真相会越用越歪。 导图的坐标一律在后端算完再交给前端画——命令行、MCP 适配器和自测都没有浏览器，却都要能出图；前端要是再排一遍，存回去的坐标和屏幕上看见的就会一天天对不上。

报错那句不能编。 界面每 2.6 秒跟后端对一次话，对不上的种类是有区别的：连不上、后端比界面旧、后端回了一句看不懂的话。以前这三样揉成一条「本机服务没在跑」，于是明明服务跑着、只是旧，人被引去查一件本来没事的事。现在这四条各说各的话，页顶横幅还会把两边版本号打出来，点一下就能换。存转写也一样：回执说「存好了 8 段」的那一帧，按钮上那颗「待存 3 处」的红点必须同时退掉，不能等下一次刷新才想起来。

窄的地方不牺牲最要紧的那两颗钮。 划词小条在窄窗里会折行、宽度封顶，但「写想法」「写条目」一定留着——被挤出去过的正是这两个。

装过的能卸干净。 设置 → 维护里有「卸载组件」与「清除本地数据」两步：前者卸引擎、模型、ffmpeg、Chromium（几百 MB 到 1.6 GB），后者清登录态与各种索引；软件本体你自己拖进废纸篓就行。

这些不是说说而已。 仓库里那套自测是真开一个 Chromium 点一遍的：

bash tests/run_all.sh          # 静态检查 + 真机走查
bash tests/run_all.sh --fast   # 只跑静态那几项，秒级

每一次改动都在这个门禁里过一遍才提交——包括上面这些「细节」：截图里的排版、笔记能不能点、删掉能不能撤、服务没起时适配器能不能自己把它拉起来。

环境要求

安装

装（macOS，三步）

1 · 下载　归藏-1.0.5.dmg　（约 2 MB · macOS 13+ · Intel 与 Apple 芯片）

2 · 拖进「应用程序」，双击打开

若弹出 「归藏」已损坏，无法打开：这是 macOS 对未签名应用的默认拦截，不是文件坏了。粘这一行就好（装在别处请改路径；提示 Operation not permitted 就在前面加 sudo）：

xattr -dr com.apple.quarantine /Applications/归藏.app

也可以在 系统设置 → 隐私与安全性 → 安全性 里找到被拦的那条，点「仍要打开」。

3 · 点一下「我思故我在」

剩下交给它：装依赖、下取书用的 Chromium（约 370 MB）、装转写引擎，然后弹出浏览器让你扫码。装完直接进界面；转写模型（几百 MB ～ 1.6 GB）稍后在后台自己下，下的时候照常用别的功能。之后每次打开都是直接进。

需要机器上已有 Python 3.9+：python.org/downloads 装一个，装完不用重启。包里另附《首次打开必读.txt》，细节与替代做法见 部署说明.md。

从源码跑

# macOS / Linux
git clone https://github.com/KEQingFeng/weread-guizang.git
cd weread-guizang
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m playwright install chromium     # 约 368 MB
.venv/bin/python ui_server.py --port 8770           # 打开 http://127.0.0.1:8770

# Windows（把上面最后两条换成）
.venv\Scripts\python.exe -m playwright install chromium
.venv\Scripts\python.exe ui_server.py --port 8770

也可双击 启动归藏.command（Windows 上是 启动归藏.bat）：自动识别目录、缺虚拟环境就创建并装依赖，服务已在跑就直接开界面。

想装成可双击的 macOS 程序、或打成可分发的 dmg：

./shell/build_macos.sh     # 产出 dist/归藏.app
./shell/make_dmg.sh        # 产出桌面上的 归藏-<版本>.dmg

外壳是 Swift + WKWebView 的原生应用，界面仍是 ui.html；构建只要 CommandLineTools，不需要完整 Xcode。

首次使用

  1. 齿轮 → 连接账号：在弹出来的浏览器窗口里用微信扫码。登录态持久化在 cache/browser_profile/，之后自动复用。
  2. 填 接口 Key：微信读书网页版「设置 → 开放 API」里复制形如 wrk-… 的 Key。存本机 cache/config.json（权限 600），界面只回显末 4 位。书架、笔记、统计、推荐、书城搜索、书籍详情都靠它；不填也能用（只列出本地已导出的书）。
  3. 想用划句翻译 / 单击查词 / 问 AI 助手，在「小 Agent」一栏填一个兼容 OpenAI 的接口（地址写到 /v1 为止）、Key 与模型名。
  4. 想用视频转笔记：B 站 / 视频平台 直接贴链接就行；云端转写与 AI 归纳也走上面那个接口。
  5. 想把划线转进 flomo：在设置里填 flomo 的 API（形如 https://flomoapp.com/iwh/xxxx/），需要 flomo PRO。

命令行

以下命令可在不启动界面的情况下使用。

# macOS / Linux
.venv/bin/python export_precise.py <书籍链接或ID>          # 链接会自动提取 ID
.venv/bin/python export_precise.py  --headed          # 显示翻页过程
EXPORT_DEBUG=1 .venv/bin/python export_precise.py     # 卡住时每 60 秒输出 Python 栈

# Windows
.venv\Scripts\python.exe export_precise.py <书籍链接或ID>
.venv\Scripts\python.exe export_precise.py  --headed
set EXPORT_DEBUG=1 && .venv\Scripts\python.exe export_precise.py

登录与加书架也可单独运行：login.py（登录与登录态检测）、shelf_add.py <书城 id>。

剪藏、订阅、视频这几条也各有可以直接跑的命令，用于排查而不必开界面（macOS / Linux 用 .venv/bin/python，Windows 换成 .venv\Scripts\python.exe）：

.venv/bin/python clip_article.py <文章链接>          # 看这一篇能解析出什么（公众号 / 知乎 / 小红书 / X 自动选路）
.venv/bin/python web_parse.py <链接>                 # 看这条链接被归到哪个站，以及正文前 1200 字
.venv/bin/python feed.py <站点或订阅地址>             # 从任意网址里找出订阅源
.venv/bin/python feed.py --list                     # 现有订阅与各条目的抓取状态
.venv/bin/python feed.py --refresh                  # 刷新全部订阅
.venv/bin/python video_note.py <视频链接> [输出目录]   # 打印视频信息，再整条跑一遍转笔记
.venv/bin/python video_note.py --task <链接>         # 界面用的那条路：选项走 GUIZANG_VIDEO_OPTS、结果打 ##GUIZANG## 一行
.venv/bin/python ffmpeg_tool.py --status            # 看 ffmpeg 备好没有
.venv/bin/python ffmpeg_tool.py --ensure            # 下一份静态 ffmpeg 放进数据目录

接入 AI Agent（MCP）

仓库自带零依赖的 Node 适配器（mcp/guizang-mcp.mjs，stdio + JSON-RPC 2.0）。在 MCP 配置中加入一项，路径替换为实际的归藏目录：

"guizang": {
  "type": "stdio",
  "command": "node",
  "args": ["<归藏目录>/mcp/guizang-mcp.mjs"],
  "timeout": 180000,
  "env": { "GUIZANG_REPO": "<归藏目录>" }
}

Qoder CN 写在设置文件的 mcpServers；ZCode 写在 config.json 的 mcp.servers。配置完成后重启 Agent（MCP 在启动时加载，不支持热加载）。

适配器按以下顺序查找项目目录：环境变量 GUIZANG_REPO → 依据「本文件位于项目 mcp/ 下」推断 → 常见路径回退。解释器按平台选择（Windows 用 .venv\Scripts\python.exe，macOS / Linux 用 .venv/bin/python），均不存在时回退至系统 python。服务未启动时自行拉起。

共 56 个工具，分为十一类：

分类 工具
书架与状态 shelf_list、app_status、task_log、book_files、folder_create、book_move
取书与账号 book_fetch、task_stop、batch_fetch、account_connect
书与笔记 book_detail、search_books、notes_index、notes_search、notes_random、book_mark
写回与导出 shelf_add、apkg_export、zip_export、cache_delete
网页剪藏 clip_url
订阅（RSS） feed_list、feed_discover、feed_add、feed_entries、feed_entry、feed_refresh、feed_to_shelf、feed_remove
视频转笔记 video_capability、video_plan、video_to_shelf、video_books、video_transcript、video_transcript_save、video_rebuild、video_export
思维导图 map_show、map_from_notes、map_save
画板 board_list、board_show、board_new、board_save、board_delete
便签（flomo） flomo_notes、flomo_portrait
写作 writer_list、writer_read、writer_create、writer_save、writer_versions、writer_snapshot、writer_restore、writer_export、writer_ai

六条约束写入适配器的工具说明，Agent 可读取：

配套 Skills

skills/ 目录包含用于读书与学习的 Skill，将对应文件夹复制到本机 skills 目录即可（Qoder CN 为 ~/.qoder-cn/skills/，其他平台使用各自的目录）：

Skill 用途
skills/guizang/ 将归藏接入为读书助手：先查看状态再执行，长任务仅发起一次并轮询，写操作仅执行明确要求的那一个；包含找书→取书→划线检索→抽卡→导出 Anki 的完整动作序列与排障口径
skills/book-speedrun/ 将一本书一次讲透：前导地图 → 核心讲义 → 全书串讲 → 一页速记与分层行动清单，每部分末尾附一条可立即执行的动手项。含完整示例

分工判据：需要内容（把书讲透、读完即用）使用 book-speedrun；需要数据（把书取到本地、检索划线、导出 Anki）使用 guizang。两者可衔接：先用归藏取书，再用 book-speedrun 讲透。

book-speedrun 中提到的 grace-coach、learn-from-materials、learn-anything-skill 属于同一生态的其他 Skill，不在本仓库，仅用于划分职责。

界面中的「一键建立 MCP」会把接入提示词复制到剪贴板，粘贴给 Agent 即可。该提示词不含任何本机路径、用户名或端口，可直接分享。

工作原理

flowchart LR
  A[登录 profile
cache/browser_profile] --> B[export_precise.py]
  B --> C[Playwright 驱动 Chromium
打开网页版阅读器]
  C --> D[hook fillText
收集每个字符的坐标]
  C --> E[取视口内的 img
过滤预加载的下一页]
  D --> F[按 y 自适应聚类成行
检测 y 重置点拆双页]
  E --> G[文字行与图片
按 y 坐标排序交错]
  F --> G
  G --> H[按正文里出现的目录标题分章]
  H --> I[chapters/NNNN.md]
  E --> J[download_images.py
强制 IPv4 · 8 线程并发]
  J --> K[images/]

flowchart TB
  UI[ui.html
单文件前端 · 无构建步骤]
  S[ui_server.py
标准库后端 · 只 127.0.0.1]
  E[export_precise.py
抓取引擎 · 子进程]
  SA[shelf_add.py
加书架 · 子进程]
  CL[clip_article.py + web_parse.py
剪藏：公众号 · 知乎 · 小红书 · X]
  FS[feed.py
RSS 发现 · 抓取 · 入库]
  VN[video_note.py
视频转笔记 · 子进程]
  FF[ffmpeg_tool.py
静态 ffmpeg 按需下载]
  MM[mindmap.py
可编辑导图 · 服务端布局 · SVG]
  BD[board.py
画板存储 · SVG / PNG 导出]
  AS[ai_sum.py
AI 小结 · 一个入口两种模式]
  FN[flomo_notes.py
便签账本 · 导入 / 标签 / 记忆画像]
  AC[activity.py
学习 / 写作时长账 · 热力图数据]
  PE[person.py
头像与简介 · 本机存储]
  WR[writer.py
写作平台 · 稿子与快照 · 多格式导出]
  YT[yt-dlp
取音频 · 元信息]
  WG[微信读书官方 Agent Gateway
wrk- Key · 16 个 api_name · 只读]
  WP[微信读书网页端 /mp/
复用登录 cookie · 唯一的写路径]
  FL[flomo]
  PC[platform_compat.py
解释器 / 建组 / 中止 / 结束进程树]
  M[mcp/guizang-mcp.mjs
stdio JSON-RPC · 56 工具]
  AG[AI Agent]

  UI <-->|JSON| S
  S --> E
  S --> SA
  S --> CL
  S --> FS
  S --> VN
  S --> MM
  S --> BD
  S --> AS
  S --> FN
  S --> AC
  S --> PE
  S --> WR
  S -->|HTTPS| WG
  SA -->|HTTPS| WP
  S -->|HTTPS| FL
  S --- PC
  E --- PC
  SA --- PC
  VN --- PC
  VN --> YT
  VN --> FF
  M <-->|HTTP| S
  AG <--> M

抓取引擎中几个关键决定及其原因：