weread-import#

通过 scripts/run.sh 运行 CLI。首次执行时会自动安装依赖。

默认策略#

1. 默认使用官方 Gateway 后端，需要环境变量 WEREAD_API_KEY。
2. WEREAD_API_KEY 获取路径：打开微信读书 App 最新版 -> 我的 -> 右上角设置按钮 -> 微信读书 Skill -> 快速配置第 2 步 -> 获取 API Key。
3. 未配置 WEREAD_API_KEY 时，提示用户配置并复述获取路径，同时展示 Gateway、受管浏览器、外部 Chrome、手动 Cookie 四种可选路径；不要自行切换到 Cookie。
4. Gateway 已配置但网络失败、HTTP 5xx、网关不可达或接口不支持时，自动回退 web 后端。
5. 用户显式传入 --cookie-from 或 --cookie 时，视为老用户旧链路，自动使用 web 后端；若显式 --api-backend gateway，则 Gateway 优先并忽略 cookie 参数。
6. 修改模板、合并逻辑或 frontmatter 后，先输出到临时目录验证。
7. 验证通过后，再对真实目录执行。
8. 目的是重新渲染或验证时，加上 --force 跳过增量检查。

详细命令模板见 references/workflows.md。

推荐命令#

bash

# 导入单本书
bash ./scripts/run.sh --book "自卑与超越" --output "/path/to/Reading"

# 导入全部书
bash ./scripts/run.sh --all --output "/path/to/Reading"

# 强制重新渲染
bash ./scripts/run.sh --book "自卑与超越" --output "/path/to/Reading" --force

# 覆盖 frontmatter tags
bash ./scripts/run.sh --book "自卑与超越" --output "/path/to/Reading" --tags "reading/weread,book"

# 明确不使用官方 Gateway，改用旧浏览器/Cookie 链路
bash ./scripts/run.sh --all --no-gateway --cookie-from browser-managed --output "/path/to/Reading"

Agent 决策表#

场景行为新用户 / 常规导入使用默认 Gateway 命令： bash ./scripts/run.sh --all --output "/path/to/Reading"缺少 WEREAD_API_KEY报告 CLI 给出的可选项，并复述获取路径：微信读书 App 最新版 -> 我的 -> 右上角设置按钮 -> 微信读书 Skill -> 快速配置第 2 步 -> 获取 API Key；不要替用户选择老用户命令含 --cookie-from 或 --cookie直接执行，CLI 会按旧 web 后端运行，并提示 Gateway 升级优势用户明确不用 Gateway使用 --no-gateway --cookie-from browser-managed，或按用户指定的 cookie/browser 参数执行Gateway 临时不可用允许 CLI 自动回退 web 后端，报告最终 backendGateway 鉴权失败或 upgrade_info不回退，报告原始错误和升级/配置要求定时任务新任务推荐 Gateway 固定命令；已有旧 cron 命令继续执行，不要自动改参数或加 --force

可用参数#

• --all
• --book <title>
• --book-id <id>
• --output <dir>
• --mode <api>
• --api-backend <gateway|web>
• --no-gateway
• --cookie <cookie>
• --cookie-from <manual|browser-live|browser-managed>
• --force
• --tags <a,b,c>

定时任务#

定时 / 自动执行场景下，必须严格遵守以下规则。

固定命令#

bash

bash ./scripts/run.sh --all --output "/path/to/Reading"

原样执行，禁止修改参数。不要添加 --force、不要替换 Gateway 为硬编码 cookie、不要省略 --output。

前置条件#

• 默认 Gateway 需要 WEREAD_API_KEY。
• 显式 --cookie-from / --cookie 的老命令会按 web 后端执行，不要求 WEREAD_API_KEY。
• --no-gateway / web 后端下， browser-live 需要外部 Chrome CDP 已运行且已登录微信读书。
• --no-gateway / web 后端下， browser-managed 会自动拉起隔离浏览器；首次需要用户在该独立窗口里登录微信读书。
• 如果 CDP 未运行或登录已过期，命令会以非零 exit code 退出 — 这是预期行为，不要尝试修复。

禁止事项#

• 禁止加 --force — 增量跳过是定时场景的正确行为，不是 bug。
• 禁止用 --cookie '...' 硬编码 cookie — cookie 会过期，应优先使用 Gateway 或浏览器模式。
• 禁止在失败后自行重试、变更参数、或尝试其他方式绕过错误。

错误处理#

• exit code 0 = 成功，直接报告结果。
• exit code 非 0 = 失败，将完整错误输出报告给用户，不做任何额外操作。
• 鉴权失败时，不要立刻断言用户已退出登录。先按 references/workflows.md 的验证流程区分登录态、CDP 环境和浏览器上下文问题。

运行须知#

• 默认后端为官方 Gateway，调用 https://i.weread.qq.com/api/agent/gateway。
• run.sh 在 browser-managed 下会自动拉起隔离 Chrome； browser-live 下只校验外部 CDP，不会自动拉起浏览器。
• Chrome 146+ 要求非默认 --user-data-dir 才能开启远程调试， open-chrome-debug.sh 会自动处理。
• browser-managed 默认使用 ~/.weread-import-profile-isolated，不会同步默认 Chrome 的整份登录态。
• browser 仍然可用，但仅作为 browser-managed 的兼容别名。
• 如需保留旧的整份 profile 同步行为，显式设置 WEREAD_PROFILE_SYNC_MODE=legacy。
• 浏览器 cookie / 浏览器上下文请求在 CDP 会话结束后会正确关闭 Playwright 连接，不会关闭用户自己的 Chrome。
• API 请求自动附加时间戳防缓存，减少因 CDN 缓存导致的鉴权失败。
• API 鉴权失败会自动刷新当前 session 重试；浏览器模式下的书籍详情接口会复用浏览器上下文。
• 官方口径中 noteCount 是划线数， reviewCount 是想法/点评数， bookmarkCount 是书签数；书签只统计，不导出正文。
• 合并统计支持新增 / 更新 / 保留 / 删除四种分类。
• 被删除的条目会归档到 ## 已删除，而非直接丢弃。
• 元信息由 YAML frontmatter 承载，正文中不重复。
• Skill 在脚本层面自包含，但运行环境需提供 Node.js 和 Playwright。

环境变量#

参见 env.example.md。

变量说明默认值WEREAD_API_KEY官方 Gateway API Key-WEREAD_API_BACKENDAPI 后端： gateway 或 web``gateway``WEREAD_GATEWAY_SKILL_VERSION官方 Gateway skill 版本1.0.3``WEREAD_COOKIE手动 Cookie-WEREAD_IMPORT_MODE导出模式api``WEREAD_CDP_URLChrome CDP 地址http://127.0.0.1:9222``WEREAD_OUTPUT输出目录./out/weread``WEREAD_TAGSFrontmatter tagsreading,weread``WEREAD_USER_AGENT自定义 UAChrome 146

资源#

• GitHub: https://github.com/gnixner/weread-import

scripts/#

• scripts/run.sh：Skill 执行入口（首次自动安装依赖； browser-managed 自动拉起隔离 Chrome， browser-live 只校验外部 CDP）
• scripts/open-chrome-debug.sh：启动隔离的 Chrome 远程调试； legacy 模式下才同步默认 Profile 登录态
• scripts/prepare-staging-skill.sh：生成隔离的 staging skill 目录，供发版前安装态验证使用

references/#

• references/workflows.md：推荐工作流、验证流程与常见问题处理