v0.5.5 — 文库目录化导航 + 按关键词筛选下载

wx-kit v0.5.5 — 文库目录化导航 + 按关键词筛选下载（2026-07-18）

新增与改进

文库导航:首屏即目录（M23）——治「滚动好久才看到下面的文章」:

• 分组视图默认收起,打开文库先看到「公众号 · N 篇」的目录,一屏尽览,点开哪个看哪个;展开状态记忆(跨页面/跨重启保持),新公众号默认收起;工具栏一键「全部展开/全部收起」。
• 粘性组头:滚动时当前组头钉在顶部(卡片/列表视图皆是),随时可点收起、直接落到下一组;列表视图列头同钉。
• 回到顶部悬浮按钮。
• 性能实测背书:1000 篇假文库下目录态打开 ~170ms;卡片全展开后滚动曾降到 ~23fps,content-visibility: auto 修至 ~52fps——千篇量级流畅,无需虚拟滚动。

按公众号下载支持关键词筛选（M24,issue #1）:

• 抓取配置新增「关键词筛选」:下拉选仅下载含 / 排除含(互斥),关键词逗号分隔、按标题匹配(不区分大小写),留空不筛。
• 过滤发生在「列出 → 下载」之间,零额外请求、不加重频控;只在指定抓取范围内筛,不为凑数翻页。
• CLI 同步支持 crawl --include <kw,kw> / --exclude <kw,kw>(可组合,exclude 优先),JSON 输出含 filteredOut(被过滤篇数)。

验证

• 单测 279 全绿(关键词过滤矩阵、crawl 接线、设置字段)、tsc / lint / Playwright GUI e2e 全过(e2e 新增目录态/单组展开/展开态持久断言)。
• 真机:115 篇真实文库目录态/粘头/回顶/重启保持截图;CLI 对真实公众号实抓关键词过滤(listed 5 → filteredOut 5、零下载)。

需求与逐条验收：docs/PRD-v0.5.5.md；实现计划：docs/plans/2026-07-17-m23-m24-library-nav-and-keyword-filter.md；复盘：devlog §33。

v0.5.4 — 订阅检查:不重跑、看得清失败、请求更省

wx-kit v0.5.4 — 订阅检查:不重跑、看得清失败、请求更省（2026-07-16）

修复与改进

订阅检查加固（M22）——源于安哥真机检查日志的三个问题:

• 同一时段重复检查:检查耗时超过 1 分钟时,调度器下一个 tick 会再启动一个并发检查(真机曾同一时段两条相同记录,同批文章数了两遍)。现加防重入守卫:一次只跑一个;自动检查进行中手动点「检查更新」也只并入同一次。
• 「失败 x」可点开看明细:检查记录里的失败此前只有个数,失败原因(频控/网络/登录失效)无从知晓。现在逐号失败原因(公众号名 + 错误)进检查记录,点「失败 x」弹窗查看;落盘日志与 CLI subscription check-now JSON 同步携带。
• 每号请求省 75%:检查原固定取「最近 20 篇」——微信每页实回约 5 篇,要翻 4 页。现改「翻到水位为止」:日常每号 1 次请求即止;多日未开应用后自动翻深(封顶 20 篇),不漏文章。

存储兼容:检查记录新增可选字段 failures,旧记录不受影响(界面上保持纯文本)。

验证

• 单测 272 全绿(新增:防重入 tick 矩阵、失败明细三处落点、翻页到水位的请求次数断言)、tsc / lint / Playwright GUI e2e 全过。
• GUI 真机(seed 数据态):失败明细弹窗逐号显示「猫笔刀 — 微信频率限制（200013）」等;旧格式记录保持纯文本。

需求与逐条验收：docs/PRD-v0.5.4.md；实现计划：docs/plans/2026-07-16-m22-subscription-check-hardening.md；复盘：devlog §32。

v0.5.3 — 修复 macOS 关窗后程序坞无法重开窗口

wx-kit v0.5.3 — 修复 macOS 关窗后程序坞无法重开窗口（2026-07-13）

修复

macOS 程序坞激活重建窗口（M21）——修复关闭窗口后点程序坞图标无响应、应用"假死"只能强退重开的问题：

• 根因：主进程只做了 mac 惯例的一半——关窗后应用驻留程序坞（window-all-closed 在 darwin 不退出），但没有注册 activate 事件 handler，关窗后不存在任何重建窗口的代码路径。缺陷自 v0.1.0 起即存在，开发/测试均为整进程启停故一直未暴露。
• 修复：app.on('activate') 时若无窗口则重建主窗口——点程序坞图标、open -a 已运行实例（同一 reopen Apple Event）均恢复正常；窗口存在时不会重复开窗。

验证

• 单测 260 全绿、tsc / lint 过；Playwright GUI e2e 新增「关窗 → activate → 界面完整重建 → 不重复开窗」断言全过。
• 打包态 .app 真机：关窗后 open -a（与点程序坞图标相同的 reopen 事件）窗口重建、界面完整，stderr 无异常。

需求与逐条验收：docs/PRD-v0.5.3.md；实现计划：docs/plans/2026-07-13-m21-dock-reactivate.md；复盘：devlog §31。

v0.5.2 — 修复命令行入口在 macOS 上崩溃

wx-kit v0.5.2 — 修复命令行入口在 macOS 上崩溃（2026-07-10）

修复

命令行快捷方式从软链改为 wrapper 脚本（M20）——修复 wx-kit download 等命令报 Unable to find helper app + GPU/网络服务连环崩溃的致命问题：

• 根因：此前 ~/bin/wx-kit 是指向应用内层二进制的 symlink,macOS 上 Electron 按「被调用的路径」定位同 bundle 的 Helper 子进程 app,经软链调用必然找不到 → 一切需要子进程（GPU/网络/渲染,即 download、PDF 导出）的命令崩溃。--version/--help/library list 等纯主进程命令不受影响,故此前未暴露。
• 修复：快捷命令改为 shell wrapper 脚本（exec 应用真实路径,与 VS Code code 命令同款做法）,Helper 定位恢复正常。
• 旧软链自动修复：升级到本版后打开一次 GUI 即自动完成——应用启动时检测到旧版软链会静默升级为 wrapper,无需任何手动操作。

验证

• 单测 260 全绿（wrapper 生成 / 状态矩阵含 legacy / force 升级覆盖）、tsc / lint / Playwright GUI e2e 全过。
• 真机:旧 symlink → 开 GUI → 自动替换为 wrapper（内容/可执行位断言）;经 wrapper 入口跑 download --formats md,pdf 正常无报错。

需求与逐条验收：docs/PRD-v0.5.2.md；实现计划：docs/plans/2026-07-10-m20-cli-wrapper-script.md；复盘：devlog §30。

v0.5.1 — 支持文字消息与图文消息

wx-kit v0.5.1 — 支持文字消息与图文消息（2026-07-09）

修复 / 新增

非标准消息类型解析（M19）——此前下载微信「文字消息」和「图文消息（小绿书）」会得到坏数据，现已完整支持：

• 文字消息（纯文字短内容，item_show_type: '10'）：
  • 修复标题被塞入整篇正文（带字面 \n）导致的超长标题、乱码目录名、阅读器标题爆版。
  • 修复正文一片空白——正文实际藏在页面脚本变量里（前端渲染），现从 text_page_info.content 提取并分段。
  • 标题取正文首行截断（≤30 字 + …），与微信客户端列表展示一致。
• 图文消息 / 小绿书（item_show_type: '8'）：
  • 修复正文空白与图片全丢：文字从 cgiDataNew.content_noencode 提取，图片从 window.picture_page_info_list 提取主图（自动排除水印图与分享封面），全部走既有图片本地化管线。
• 通用加固：og:title / og:description 兜底值中的字面转义序列（\n、\x0a 等）统一清洗，任何路径都不再渗入标题/摘要。

md / html / pdf 导出、GUI 阅读器、CLI 全链路自动受益（解析层单点根治，下游零改动）。

说明

• 已下载的坏记录不做自动迁移：在文库删除后重新下载即可。
• 图文消息中的实况图（live photo）只保存静态图，不下载视频。

验证

• 单测 255 全绿（含两种类型的真实页面裁剪 fixture）、tsc / lint / Playwright GUI e2e 全过。
• 两条真实 URL 全格式（md/html/pdf/meta）下载 + GUI 阅读器真机验证（文字消息 12 段正文、图文消息 7 图 naturalWidth>0）。

需求与逐条验收：docs/PRD-v0.5.1.md；实现计划：docs/plans/2026-07-09-m19-message-type-parsing.md；复盘：devlog §29。

v0.5.0 · CLI 体验优化

v0.5.0 · 2026-06-29

「CLI 体验优化」迭代。把 CLI 从「能被 agent 调」打磨到**「顺手、自洽、与 GUI 同库」**：补齐帮助/版本与模式分流、按「agent 用得到」补足缺失的命令行入口、消除 CLI 与 GUI 默认操作不同库的隐性不一致，并在首次启动时引导用户为 wx-kit 建一个 PATH 软链，让安装后开箱即可在终端调用。

未签名首次打开仍需手动放行，见 README「30 秒上手(下载安装包)」。

---

🚦 模式分流修复 + help/version（M16）

修了「带 --version 反而误开 GUI」的分流 bug，并把帮助/版本补齐成行业惯例的样子：

• 分流判定收口：argv[0] 是已知子命令、或 argv 含 -h/--help/-v/--version、或 argv[0] 为 help → 进 CLI；无参 wx-kit 仍开窗口（首启引导依赖此）。
• flag 与子命令都给：-v/--version 输出裸版本号（0.5.0，agent 好 parse，不套 JSON）；-h/--help 每层可用，顶层列全部子命令与简介；help [cmd] 查单命令用法。
• 输出去向分清：help/version 是用户主动查询 → 走 stdout、退出码 0；仅报错触发的 usage 才走 stderr（拆了旧实现把两者都打到 stderr 的写法）。

🧰 CLI 能力补齐 + 与 GUI 同库（M17）

以「AI agent 会不会用到」为尺，补足命令行缺失的入口，并消除「GUI 走设置、CLI 走硬编码」导致的不同库：

• 同库：凡涉及库根的命令，--out 默认回落 settings.libraryRoot（与 GUI 同库），显式 --out 优先。
• 文库：library search <kw> [--account]（标题/正文命中）、library remove --ids <csv>（删文件 + 历史引用项 markDeleted，与 GUI 删-史联动一致）。
• 订阅：subscription list（账号/水位/上次检查/下次预计，与 GUI 订阅页同源）、subscription check-now（触发一次手动检查；命中频控不重试；未登录返回 note:'no-session' 且 ok:true）。
• 设置：settings get [key]（全量或单键）、settings set <key> <value>（白名单校验 + 值合法性校验后写入）。
• 重构：把 runSubscriptionCheck（及依赖）从 electron/ipc.ts 闭包抽到 electron/services/subscription-check.ts，参数化 emit/log，ipc 与 cli 共用——CLI 检查与 GUI 同步落盘 check log + 历史。

🔗 首启建命令行快捷方式（M18，macOS + Linux）

省去手敲 .app 内层长路径：

• 首启一次性引导：首次开 GUI（且未提示过、~/bin 未建软链）弹一次 Modal，接受则在 ~/bin 建指向二进制的软链；~/bin 不在 PATH 时再问是否写入 shell profile（按 $SHELL 选 ~/.zshrc/~/.bashrc/兜底 ~/.profile，幂等追加）并提示重开终端生效。接受/忽略都置 cliLinkPrompted=true，不再每次弹。
• 设置页可重建：新增「创建命令行快捷方式」按钮，显示当前 status、可随时重做；Windows 上隐藏。
• Windows CLI 可达性/软链不在本版范围（stdout 不回贴控制台尚无正解，见 ROADMAP 候选）。

🩹 解析兜底

• #js_name 为空时从页面脚本变量 d.nick_name 兜底提取公众号名，避免少数文章解析出空公众号（parse-article.ts）。

边界与立场

补 CLI 的尺子是**「AI agent 会不会用到」**，不是「GUI 有就镜像」：本版补文库管理/订阅触发/设置脚本化，不补纯人看的下载历史浏览；--version 出裸 semver、help 走 stdout，都为顺手与可解析，不为「stdout 必 JSON」破例。

---

需求见 docs/PRD-v0.5.0.md（逐条验收 §4），设计见 docs/superpowers/specs/2026-06-28-v0.5.0-cli-experience-design.md，逐里程碑决策/踩坑见 docs/devlog/wx-kit-vibe-coding.md §28。功能与质量：npm test（240）/ tsc / lint 全绿，npm run test:e2e 实机全流程通过（含 M18 软链真 e2e）。

安装包

• wx-kit-0.5.0-arm64.dmg（macOS Apple Silicon）
• wx-kit-0.5.0.dmg（macOS Intel）
• wx-kit Setup 0.5.0.exe（Windows）

均未签名/未公证，首次打开需手动放行（见 README）。

v0.4.0 · 文库供料 agent + 存储加固

v0.4.0 · 2026-06-23

「文库供料 agent + 存储加固」迭代。把文库从「自己看的归档」升级为可被 AI agent 消费的素材源——选中文章一键导出为结构化素材，交给应用之外的 Claude Code skill 驱动「选题 → 写作」的人在环中创作；并在此之前先把文件存储地基夯实。

未签名首次打开仍需手动放行，见 README「30 秒上手(下载安装包)」。

---

🧱 存储加固（M13）

把 library.json / history.json / subscriptions.json 三个索引的写入做得抗崩、抗并发：

• 原子写：改为「写临时文件 → 原子 rename 替换」，进程中途被杀 / 断电不再把索引写成半截 JSON。
• 写串行化：同一索引文件的「读-改-写」按文件加锁串行，杜绝后台订阅自动下载与前台操作并发时的丢更新。
• 损坏可重建：新增「重建索引」能力——扫描库根各文章目录的 meta.json 重建 library.json。CLI library rebuild + 设置页「重建索引」按钮；索引损坏的提示也从「手删重来」改为「可重建修复」。

📤 供料能力（M14）

把选中的文库文章变成 agent 能直接吃的结构化素材：

• library export CLI：输出 JSON 清单（每篇含标题/公众号/作者/发布时间/原文链接/目录/content.md 绝对路径，正文不内联），选料器 --ids / --since <日期> / --account <公众号名> / --all（无选料器时报错，避免误导全库）。
• 文库 GUI「导出选中为素材」：复用文库多选，选中后一键把素材清单写到库内 exports/<时间戳>.json，提示路径、可在文件夹显示。外部 skill 接这个文件即可。

🤖 贯通样例 skill（M15）

仓库新增 agent/wx-kit-compose——一个消费 wx-kit 的 Claude Code skill 参考实现（与应用代码隔离，只经 CLI / 导出文件取数据，绝不 import 应用代码）：

• 编排「选料 → 选题候选 → 🛑你拍板 → 委派 khazix-writer 出初稿 → 🛑你审定」，两个检查点强制人在环中。
• 选题轻量内联，写作委派给写作 skill（khazix-writer），wx-kit 只供料、不内置创作模块。
• 安装与用法见 agent/README.md。

边界与立场

wx-kit 守住「下载器 + 文库」本分，只供料；选题/写作/审阅的编排活在应用之外的 skill 里，人在环中。文库素材用于选题/研究/启发 + 人工主导创作，不洗稿、不自动转发。

---

需求见 docs/PRD-v0.4.0.md，设计见 docs/superpowers/specs/2026-06-22-v0.4.0-agent-feed-and-storage-design.md，逐里程碑决策/踩坑见 docs/devlog/wx-kit-vibe-coding.md §24–§26。功能与质量：npm test / tsc / lint 全绿，npm run test:e2e 实机全流程通过。

安装包

• wx-kit-0.4.0-arm64.dmg（macOS Apple Silicon）
• wx-kit-0.4.0.dmg（macOS Intel）
• wx-kit Setup 0.4.0.exe（Windows）

均未签名/未公证，首次打开需手动放行（见 README）。

v0.3.0 · 列表优化 + 公众号订阅

文库列表视图优化（列宽可调 + 表头排序）+ 类 RSS 公众号订阅（订阅页、定时检查 daily/interval、新文章提示/自动下载、检查可观测性）。详见 docs/releases/v0.3.0.md。

v0.2.1 — 安全补丁（electron 42 / builder 26）

v0.2.1 · 2026-06-09

安全补丁版。功能与 v0.2.0 完全一致，仅升级运行时与构建工具链，清掉 v0.2.0 发布后 GitHub Dependabot 报的全部漏洞提示。

未签名首次打开仍需手动放行，见 README「30 秒上手(下载安装包)」。

---

🔒 依赖安全升级

• electron 31.7.7 → 42.3.3：修复一批 use-after-free、ASAR 完整性绕过、service-worker IPC 欺骗、clipboard 崩溃等 CVE。
• electron-builder 24.13.3 → 26.15.2：其捆绑的 tar（→7.5.11+）、glob（→10.5.0+）升到修复版，清掉打包工具链的路径穿越类告警。
• vite 5.4 → 6.4.3、vitest 2 → 3.2.6（v0.2.0 收尾时已升）：修 dev-server 路径穿越 / UI server 文件读取类告警。

Dependabot 提示从 v0.2.0 时的 26 项清零。

✅ 验证

• 119 单测 + tsc + lint + 24 步 Playwright e2e 全绿（electron 42）。
• mac dmg(arm64+x64) + win nsis exe 重新出包；electron 二进制与构建工具链均走 npmmirror 国内镜像下载。
• 真实启动打包后的 .app + 触发 cheerio 解析路径，零 console/page 错误 —— undici external 不变量在 electron 42 仍成立（不会因 node:sqlite 缺失而崩）。

📦 安装包

• macOS (Apple Silicon): wx-kit-0.2.1-arm64.dmg
• macOS (Intel): wx-kit-0.2.1.dmg
• Windows (x64): wx-kit Setup 0.2.1.exe

🛠 工程说明

• 依赖下载改走国内镜像优先策略（见 AGENTS.md 与 docs/plans/2026-06-09-deps-audit.md）：ELECTRON_MIRROR / ELECTRON_BUILDER_BINARIES_MIRROR 指向 npmmirror，镜像域名加 no_proxy 直连，代理仅作国外站不可达时兜底。

功能清单与 v0.2.0 一致，见 docs/releases/v0.2.0.md。

v0.2.0 — 下得放心、找得到、看得见

v0.2.0 · 2026-06-09

v0.1.0 之后的迭代:把下载闭环做扎实、信息架构理顺——「下得放心、找得到、看得见」。
五个里程碑 (M5–M9) 全部合入 main,端到端在真实微信公众号后台验证通过。

未签名首次打开仍需手动放行,见 README「30 秒上手(下载安装包)」。macOS 签名+公证计划在后续版本。

---

✨ 新增功能

M5 · 信息架构重构

• 导航三项:下载 / 文库 / 设置(去「批量」项,「书架」改名「文库」)。
• 「下载」页双模式:按链接 / 按公众号,编辑页签切换;默认进按链接,常驻开关可切。
• 双模式共享「保存为」配置卡,共用「开始下载」按钮。
• 字体规则:衬线=专名/标题,无衬线=正文/功能。

M6 · 下载闭环 + 历史

• 下载完成后就地确认:每篇展示实际产出格式、可阅读、可在文件夹显示。
• 下载历史 history.json 索引(默认保留 1 年、可配置、支持清空):
  • 排序、分页懒加载(「加载更多」,非页码)。
  • 复制下载项回填来源+范围+格式到配置卡再下一遍。
  • 每条记录可单删;失败行有重试;跳过项也保留就地操作。
  • 清空/过期只清动作记录,绝不触碰已下文件与文库条目。

M7 · 反馈引导

• 频控可见:公众号列表阶段命中频控时,朱砂退避横幅 + 客户端倒数(「约 N 秒后重试 · 第 k 次」),不再像卡死;core 经 onBackoff 回调上报,IPC 透传为 {kind:'backoff'} 事件。
• 失败有指引:把 fetch timeout… / invalid or unavailable article 等原始报错归一为「人话标题 + 下一步建议」,原始信息折叠在 tooltip 备查。
• 公众号取消需二次确认;未下载的文章不蒸发——补登记为 cancelled 进历史,以「未下载」徽章列出,提供单篇「下载」补下。

M8 · PDF 保真

• 导出 PDF 不再跨页切图:在 buildHtml 的内联样式注入 @media print { img/figure/table/pre/blockquote { break-inside: avoid } },只作用于打印态,屏幕阅读器零影响。
• 真实 PDF 出件 + 对照截图验证:无规则版切到第 17 行,有规则版整块下移完整。

M9 · 文库组织

• 排序:按下载时间 / 发布时间 / 标题,升降切换;空发布时间恒置末尾。
• 按公众号筛选 + 按公众号分组折叠——两者可叠加。
• 批量选择 + 批量删除(library:removeMany):只删记录不删文件,联动历史标记已删除。
• 卡片 ⇄ 列表 视图切换(访达式):列表为紧凑行(缩略图·标题·公众号·发布·下载·行尾常驻操作);列表分组时列头只显示一次,各分区只留「印章+号名+篇数」分隔头;单击=选中、双击=阅读;底部浮动批量条选中即见、不挤动列表。
• 视图变换为纯逻辑 src/renderer/library-view.ts(TDD),只 import 类型——不破 renderer↔core 边界。

---

🔧 改进

• 测试: 119 单测 + 24 条 Playwright Electron e2e 全部绿;e2e 用真实缓存 session 跑公众号链路(无 session 退化登录门)。
• 错误处理: explainError 纯展示逻辑放 renderer 层(CLI 契约是 JSON,本不要人话),避免破「renderer 绝不 import core 运行时」的架构边界。
• UI 一致性: 全站「暖色编辑杂志风」与新控件(批量条、退避横幅、勾选徽章、未下载徽章)统一在同一设计系统。
• README / 截图 / ROADMAP / PRD-v0.2.0 全部同步到 v0.2.0。

---

📦 安装包

• macOS (Apple Silicon): wx-kit-0.2.0-arm64.dmg
• macOS (Intel): wx-kit-0.2.0.dmg
• Windows (x64): wx-kit Setup 0.2.0.exe

详见 README.md §下载安装包。