wx-kit v0.8.1 — dock 图标真修复

wx-kit v0.8.1 — 补上 v0.8.0 没真正修好的 dock 图标(2026-07-22)

v0.8.0 宣称修复了「mac 上跑 CLI 会在程序坞堆图标」,实际没修好。本版换了修法,真正解决。

修复

mac CLI 不再冒程序坞图标(R1)

• v0.8.0 的修法为什么无效:app.dock.hide() 放在 app.whenReady() 之前并不生效——dock API 要等 app ready 才被应用,而 AppKit 在那之前就已把进程注册成前台应用并画出了图标。实测 wx-kit -h 期间的进程状态序列是 NULL → Foreground → UIElement:图标先出现,随后才被隐藏。命令跑得越短,图标可见占比越大,-h 几乎全程可见。
• 本版修法:打包配置加 LSUIElement: true(mac Info.plist),由 Launch Services 在进程启动时就定为 accessory,不给图标出现的机会——图标是 JS 执行前画的,只能在 plist 层拦。GUI 分支在 ready 后 app.dock.show() 把图标要回来,并 app.focus({ steal: true }) 确保窗口正常到前台。
• 实测(打包态):-h 全程 40/40 采样为 NULL,从未出现 Foreground;download 为 NULL → UIElement;GUI 启动 Foreground + 窗口到前台,一切照旧。
• win/linux 不受影响(LSUIElement 是 mac 专有键)。

新增

设置页「站点同步」的建站指引(R2)——标题旁一个 ?,hover 才显示,不常驻占版面:

同步目标是一个 Astro 静态站。我的开源项目 dreamble 的 site/ 子目录就是这个站点的完整源码——主题、发文规范、构建脚本都在里面,想自建个人站可直接取用。

含可点链接 github.com/monkeychen/dreamble(走系统浏览器打开)。

验证

• 单测 350 全绿、tsc / lint 通过;Playwright GUI e2e 全套 ALL PASSED(新增 ? 图标与 tooltip 文案两条断言),控制台 0 错误。
• 打包态真机采样验证 dock 行为(方法:lsappinfo info -only ApplicationType <pid>,覆盖启动瞬间)。
• brew 安装的正式包跑 --version / download / library list 全通。

需求与逐条验收:docs/PRD-v0.8.1.md;复盘:docs/devlog/wx-kit-vibe-coding.md §36。

wx-kit v0.8.0 — 让内容流到该去的地方

wx-kit v0.8.0 — 让内容流到该去的地方(2026-07-22)

本版两条主线:让 agent 用 CLI 用得更顺(订阅可按号点检、列表默认按发布时间排好序、-h 给出仓库地址),以及让下载到的文章能一键流进个人站点。外加修掉一个 mac 上的老毛病。

新增

文库/CLI 同步到个人站点(M32 · R2)——把已下载的文章按 Astro 站点的发布规范直接生成到 content/posts/:

• 产出 YYYY-MM-DD-<slug>/index.md,目录日期取自文章的 publishTime;frontmatter 只写 title / date / source: wechat(严格对齐站点 strict schema,多一个字段站点就构建失败)。
• 正文自动去掉 wx-kit 的 frontmatter 与重复的首个 H1;图片摊平到同目录(images/img-1.png → ./img-1.png),站点侧零手工调整。
• 目录级原子写入:先写暂存目录、写全再整体 rename,中途失败不留半成品;slug 与已有目录冲突时不覆盖,该篇记失败、不阻断其他篇。
• 这是纯个人需求,故默认隐藏:设置页新增「站点同步」开关(默认关)+ 目标目录;开关只管 GUI 按钮可见性,CLI 通道不受限(agent 配好目录即可用)。
• GUI:文库选中文章 → 底部指令区「同步到站点」→ 逐篇填 slug → 结果汇总(成功列目录、失败列原因)。
• CLI:wx-kit site sync --ids <id> --slug <slug>,批量用 --slugs <id>=<slug>,... 或 --slugs-file(按 id 映射,不靠位置对应)。

订阅支持按号点检(M31 · R1)——以前只有一个全量「检查更新」,想单独看某个号有没有更新没地方点:

• 订阅页每行新增「检查」动作,顶部按钮改名「检查全部」(语义对照)。
• 频控纪律不变:子集照样串行 + 账号间随机延迟;与全量检查共享同一个 in-flight 守卫,检查进行中两处按钮一并置灰,不会叠加请求。
• CLI:wx-kit subscription check-now --accounts <fakeid,fakeid>(fakeid 从 subscription list 取)。

改进

library list / search 默认按发布时间降序(M31 · R3)——为「每天拉取所有公众号最近文章清单」这个 agent 场景:

• 新增 --sort publish|download|title 与 --order asc|desc,默认即 --sort publish --order desc,agent 直接 library list 取前 N 条就是最近 N 篇。
• 空 publishTime 的条目在升降序下恒置末尾(与 GUI 同一份 sortArticles,逻辑抽到 core 共享,不双份维护)。
• ⚠️ 轻度 breaking:默认输出顺序从「索引写入序」变为「publishTime 降序」。原顺序本就不确定、不应被依赖,新默认更可预期。

wx-kit -h 给出仓库地址(M31 · R4)——帮助末尾附 https://github.com/monkeychen/wx-kit,agent 遇到 skill 没覆盖的细节可自助去读 README / issues / releases。

修复

mac 上 CLI 命令堆程序坞图标(M31 · R5)——跑一次 CLI 冒一个图标、跑 N 次堆 N 个:

• 根因:Electron 在 mac 是 GUI 子系统应用,进程一启动就在程序坞冒头,哪怕一个窗口都不开;CLI 分支复用 Electron 进程(PDF 渲染需要 BrowserWindow)却没压制。
• 修复:CLI 分支在 whenReady 前 app.dock.hide()(仅 mac 存在,win/linux 天然 no-op)。GUI 启动的 dock 图标、CLI 的 PDF 离屏窗口均不受影响。

验证

• 单测 350 全绿(新增站点同步核心 17 例、排序 5 例、订阅部分检查 2 例,以及 20 例 CLI 契约测试覆盖新命令的参数解析与退出码)、tsc / lint / Playwright GUI e2e 全过。
• 跨项目端到端:站点同步产物落进真实 Astro 站点跑 npm run check(strict schema + 目录日期 + slug 唯一)全过,astro check 0 errors;验完清理不留痕。
• CLI 真机:单篇 / 含图 / slug 冲突 / 非法 slug / 缺 slug / 批量映射逐个走通,退出码 0/1/2 符合契约。
• mac 真机:连续跑多条 CLI 命令,程序坞全程无图标;无参启动 GUI 图标正常。

需求与逐条验收:docs/PRD-v0.8.0.md;实现计划:docs/plans/2026-07-22-m31.md、docs/plans/2026-07-22-m32.md;复盘:docs/devlog/wx-kit-vibe-coding.md §36。

v0.7.0 — 磨平「下载 → 创作」链路

wx-kit v0.7.0 — 磨平「下载 → 创作」链路的四处毛刺(2026-07-20)

本版不铺新平台、不改架构,只把「下载到的东西」和「用它创作」之间用户天天踩的四颗小石子磨掉。

改进

Markdown 导出保留表格(M29 · R1)——以前含表格的文章存成 md,表格直接散架变成一坨文本:

• 自写 GFM 表格规则转出标准 | 列 | 列 | 表;不引 turndown-plugin-gfm——插件产出的骨架对,但微信单元格外那层 <section> 会被当块级元素、炸出裸换行(非法 GFM),要修等于把插件核心重写,不如自己 40 行搞定,还少一个依赖。
• 单元格内行内格式(粗体/链接)、双引号、特殊符号原样保留;管道符转义。合并单元格(rowspan/colspan)按 GFM 限制尽力而为。
• 真实文章端到端验证:两张不同列数的表(2 列、3 列)均转成紧凑合法 GFM,GUI 阅读器渲染成真表格。

应用内可见版本号(M29 · R2)——以前只有 CLI --version 能看到版本号,GUI 完全不可见:

• 设置页新增「关于」区块:版本号(取自 app.getVersion(),发版自动跟上)+ 项目主页 / 查看新版本外链。
• (刊头版本号上线后即按反馈撤回——用户不关心版本号,常驻刊头是噪音;版本信息留「关于」即可查。)

窗口标题栏去重(M29 · R3)——原生标题栏那个「wx-kit」与应用内刊头品牌区信息重复:

• BrowserWindow title 与 index.html <title> 同改为空(mac 上标题栏只剩红绿灯 + 一条干净浅灰条),刊头零变化。一行配置改动、零风险。

导出素材一键递给 agent(M30 · R4)——以前导出素材后要「去 Finder 找路径 → 切到 agent → 自己拼提示词」三步:

• 导出成功由一条提示升级为 Modal:清单路径就地可见、可选中。
• 主按钮**「复制给 agent 的指令」**复制一段可直接粘进 Claude Code 等任意 agent 的自然语言(含清单绝对路径、contentPath 用法、引导「先读再确认选题」),省掉找路径和拼提示词两步。
• 调研后否决「直接唤起 Claude Code」:claude CLI 虽能带 prompt 起会话,但唤起的是新终端 + 陌生 cwd 的新会话,而用户真实场景是粘进已开着的会话——复制指令对任意 agent 通用、更贴合真实用法。

验证

• 单测 307 全绿(新增 GFM 表格 6 例 + agent 指令拼装 5 例)、tsc / lint / Playwright GUI e2e 全过。
• 真实文章端到端:下载含表格文章 → content.md 是合法紧凑 GFM 表格 → 阅读器 md 视图渲染成真表格。
• GUI 真机验证:导出 → Modal → 复制指令 → 主进程读回剪贴板逐字比对;清单 contentPath 逐条可达。

需求与逐条验收:docs/PRD-v0.7.0.md;实现计划:docs/plans/2026-07-20-m29.md、docs/plans/2026-07-20-m30.md。

v0.6.0 — Agent 自动化闭环:命令行安装、登录态迁移、专属 skill

wx-kit v0.6.0 — Agent 自动化闭环:命令行安装、登录态迁移、专属 skill(2026-07-19)

新增

命令行安装通道(M26)——agent/用户一条命令装好,不再手动下 dmg:

# macOS(Homebrew)
brew install --cask monkeychen/wx-kit/wx-kit
xattr -cr /Applications/wx-kit.app     # 未签名 app 必须清 quarantine,否则 CLI 也会被 Gatekeeper 卡住

# macOS / Linux(npm,Node 20+;国内先设 ELECTRON_MIRROR)
npm install -g wx-kit

登录态跨机器迁移(M27)——headless/服务器环境无法扫码的正解:

• wx-kit session export [-o <file>]:导出登录态(文件权限 0600,等同登录凭证,用后即删);
• wx-kit session import <file>:结构校验 → 导入 → 立即真探测有效性(失效如实报 valid:false)。
• 工作流:mac 扫码 login → export → scp → 服务器 import → agent 全自动 crawl/订阅检查。

wx-kit 使用 skill(M28)——agent/wx-kit-skill/:agent 的安装与使用教程(检测未装即自动安装、登录态分场景处理、全部 CLI 原子能力速查、组合任务范例、频控纪律),样例逐条实测;与 wx-kit-compose(创作编排)互补。

改进

日常体验(M25):

• 文库默认按发布时间降序(最新发表在最前),切换排序后跨会话记忆;
• 设置页新增「打开检查日志」入口(完整检查历史含逐号失败原因),订阅页同入口提升可见性;
• wx-kit -h 帮助大改:双模式说明、stdout JSON/退出码契约、命令组子命令清单、常用示例、库默认位置。

验证

• 单测 296 全绿、tsc / lint / Playwright GUI e2e 全过(新增排序默认/记忆、日志入口断言)。
• 双通道隔离安装真机验证:brew 装 .app 跑 --version + md+pdf 下载;npm tarball 全局装跑真实文章下载。
• 全新 agent 四步端到端(隔离 npm prefix + 隔离 HOME):安装 → session import(valid:true)→ download → library list,零人工。

需求与逐条验收:docs/PRD-v0.6.0.md;实现计划:docs/plans/2026-07-19-m25*~m28*.md;复盘:devlog §34。

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）。