atlas：AI Agent 工具实践指南
2026-10-03
2026-10-05 0
在项目中评估weread-guizang，可以先看清用途边界：把微信读书 skills 还原成开箱即用的工具 —— 取书、搜索、笔记回顾、Anki 导出、MCP 接入 - GitHub -等相关能力。把它放到网页与浏览器自动化流程中，最容易暴露的是登录状态、页面变化和失败恢复往往不稳定，不能只看演示是否顺利。更实际的做法是选择一个权限清楚的网页流程做端到端短测，同时核对会话保持、元素定位、错误恢复和工件留存，不要直接在关键项目上。如果团队属于需要可观测网页自动化流程的开发者，它有继续测试的理由；否则先看替代方案会更省时间。
归藏 · weread-guizang
把微信读书的书籍以md格式导出到本地，也把外部内容（公众号文章、知乎 / 小红书 / X 的帖子、RSS 订阅、视频）收进同一个本地书架：整本导出为 Markdown、本地多格式阅读器，外加一个 AI 只搭手不代笔的写作台。
方案
归藏把微信读书那套只服务 AI Agent、且只读的接口还原成可用的本地工具，并补齐它没有的部分：
三项能力都在本机完成，服务只侦听 127.0.0.1，不经第三方服务器。
它可以做什么
一句话：把「读写」这件事的产出——正文、划线、想法、笔记、导图、画板，以及你自己写下的稿子——都落到你自己的文件夹里，顺带把你在别处读的东西（公众号、知乎 / 小红书 / X、RSS 订阅、视频）和你在别处记的东西（flomo 导出的便签）也收进同一个本地书架。
取书与导出
.apkg）。本地阅读器
边读边记
notes.json / notes.md / mindmap.json / boards/）：拷走书就等于拷走笔记，不进数据库。笔记脑图与画板
书架
~/Documents/归藏/ 下按这七格各一个文件夹（写作那格装你的稿子），访达里一眼能认出哪本是从哪来的。剪藏
订阅阅读器
视频转笔记
AI 小结：一个入口，两种模式
便签（flomo）
读书 会把 读书/神经科学 一起捞上来；下面那排药丸写着几条，点进去就筛出几条。flomo_notes 按标签 / 关键字 / id 取原文，flomo_portrait 读那份「记忆画像」。cache/flomo/portrait/），此后每次任务先读画像再动手——画像只有骨架数字与分类习惯，不含任何一条笔记原文。写作平台
书库/写作/write_*），于是目录、标签、封面、清理、MCP 那一整批能力，稿子一行接口都没改就全跟着走。个人主界面与两张热力图
侧边栏与导航
统计、回顾与同步
界面自己盯得住后端的成色
给 AI Agent 用
skills/ 可直接安装；界面里「一键建立 MCP」把接入提示词复制给你的 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 # 只跑静态那几项，秒级
每一次改动都在这个门禁里过一遍才提交——包括上面这些「细节」：截图里的排版、笔记能不能点、删掉能不能撤、服务没起时适配器能不能自己把它拉起来。
环境要求
node -v 能输出版本号就行。其余功能都不需要它。安装
装（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。
首次使用
cache/browser_profile/，之后自动复用。wrk-… 的 Key。存本机 cache/config.json（权限 600），界面只回显末 4 位。书架、笔记、统计、推荐、书城搜索、书籍详情都靠它；不填也能用（只列出本地已导出的书）。/v1 为止）、Key 与模型名。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 可读取：
app_status / task_log 轮询。不要等待其执行完毕，否则必然超时。video_transcript_save 的 edits / drop / add（只说改了哪几段，适配器自己读回整本再写盘），map_save 不带 nodes 就只改标题 / 形态，board_save 不带 canvas 就不动画面。把整本抄一遍发上去，或者顺手清空用户手画的东西，都是这一层要挡住的事故。writer_save 也是整篇覆盖：要改哪一段，先用 writer_read 把最新正文取回来、改完整篇存回；带上 rev 时版本对不上会被拒，防的就是拿着旧稿盖新稿。后端存前自动留快照，退错了用 writer_restore 退回来。writer_ai 的 polish 只回差异建议、不动原文。shelf_add 是唯一会改动真实微信读书书架的写操作；cache_delete 默认只列出，需带 confirm=true 才真正删除；board_delete 不可恢复。feed_add / feed_remove / feed_refresh / feed_to_shelf 只动本机的订阅与本地书架。video_capability 报现在还缺什么（yt-dlp / ffmpeg / 本地转写引擎），缺了就先补齐再发起，不要盲发。flomo_portrait：那份记忆画像只有骨架数字与分类习惯，读它比翻一百条原文便宜，也不会把原文一次性搬进上下文；要原话再用 flomo_notes 按标签 / 关键字 / id 取，一条一条来。配套 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
抓取引擎中几个关键决定及其原因：
page.evaluate 默认无超时，渲染进程卡死时调用永久挂起；asyncio.wait_for 对不响应取消的调用无效，因此使用 asyncio.wait 取得超时后直接返回，再终止浏览器回收连接。 就当 RSS，会把整页 HTML 认成订阅源，反而把页面里 / 。
喜欢(0)
Copyright(C) 2020-2026 jiyx.com All Rights Reserved 联系方式：[email protected]