bongocat-mcp 开发日记#

昨天发了使用指南，文末「后续方向」第一条是 AstrBot 接入，当时的措辞是「方案已论证完成」。今天这个方案进入实现：8 个提交全部推上 main，代码净增约 1900 行，另产出 19.4MB 的免安装分发包。工作沿四条主线推进——使用门槛、AstrBot 生态、免安装分发、文档同步。以下按时间线记录。

上午：把指南里的「第一步」变成双击#

昨天指南的「第一步：准备（一次性）」要求手动执行四条命令：clone、创建 venv、激活、安装依赖。对熟悉 Python 的开发者这不算负担，但对只想用起来的使用者，每一步都是门槛。上午的工作是把这些命令收进脚本：

新增 start.bat / stop.bat。首次双击 start.bat 会自动创建虚拟环境、安装依赖、生成配置，然后后台启动仪表盘并打开浏览器；之后双击即直接启动。stop.bat 一键停止后台服务与 Mver 镜像。源码的使用门槛从「手动 venv + 命令行」降到了「双击」。

同时修复了一个体验问题：重启或切换猫之后气泡无法正常显示，涉及 overlay.py、两个 driver 与 win32_utils.py。

中午：AstrBot 插件落地，猫成为消息播报员#

今天最大的提交是 AstrBot 插件（+1413 行）。功能一句话概括：机器人收到 QQ 消息 → 经仪表盘 API → 猫以气泡转述并切换表情。猫的职责从「编程助手播报员」扩展为「消息播报员」，复用的正是昨天文章里那条链路。

三车道路由#

如果每条群消息都触发一次播报，猫会成为刷屏源。因此消息路由分三条车道：

车道	消息	处理
快车道	私聊消息	逐条转述
快车道	命中规则的群消息（@机器人、关键词等）	逐条转述
慢车道	其余群消息	聚合为摘要，不逐条播报

配合黑白名单，哪些会话播报、哪些静默，全部由配置决定。表情沿用昨天文章介绍的实时适配机制：每次播报时读取当前猫的表情列表按名称匹配，换皮肤无需改插件，没有表情的皮肤自动降级为只弹气泡。

离线测试与版本号#

插件附带完整离线测试：编写了一个 AstrBot stub 模拟宿主环境，26 个用例全部通过，不依赖真实 QQ 即可验证。接入论证过程整理为 docs/astrbot-integration.md。

期间有个值得记录的插曲：排障时遇到过一次「假 bug」——现象指向插件缺陷，实际是 AstrBot 进程里运行着未重载的旧模块。为此插件升级到 v0.2.0，加载时与 /bongocat_status 指令都会输出版本号。此后再遇到类似现象，可以第一时间确认进程里运行的代码版本。这个需求直接来自当天的事故，也是此后排障中最实用的改进之一。

下午（上）：一次隐蔽的进程误杀#

打包测试时发现的 bug 值得单独记录，它的表象非常有迷惑性。

症状：打包出的 exe 双击运行后，大约存活一个探测周期便无声退出——退出码 1，日志为空。最初怀疑是杀毒软件拦截，因为「无声退出且不留日志」符合这类行为的典型特征。

排查：实际原因在自身代码。detect.py 与 cdp_webview2.py 通过子串匹配寻找猫：进程信息含 bongo 即视为候选（排除 mver/ui/converter）。而打包产物名为 bongocat-mcp.exe，同样命中 bongo，于是被 cdp 接管逻辑当成了猫，遭到 taskkill。

影响推演：更严重的场景在终端用户机器上——当系统中没有任何猫时，exe 会「终止自己 → 把自己当猫重启 → 再次终止」，陷入无限循环。这个 bug 在源码版上从未出现，是因为源码以 python dashboard.py 运行，进程信息不含 bongo。

修复：排除词增加 mcp（共 6 处），并将「分发产物名称含 mcp」确立为命名契约写入文档。这是源码层面的修复，对所有运行形态生效。

WARNING
用子串匹配识别进程，匹配规则迟早会命中自己的产物。为分发产物制定明确的命名契约并写入文档，比依赖对个案的记忆更可靠。

下午（下）：免安装打包#

误杀修复之后，packaging/ 打包工程落地（+339 行，源码零改动）：

launcher.py 冻结入口：通过 BONGOCAT_MCP_CONFIG_FILE 将配置固定到 exe 旁边，数据文件按原有相对路径落位，并识别源码版的隐藏重启参数——同一份代码支持源码与打包两种运行形态
bongocat-mcp.spec：PyInstaller onedir 模式，解压后约 40MB（tkinter/uvicorn 等依赖全部打入），build.bat 一键构建出 zip
子命令设计：单个 exe 覆盖四种用法

命令	行为
双击（无参）	启动仪表盘，自隐藏后台运行
`server`	MCP stdio 模式，挂载给 AI 客户端
`mirror`	Mver 镜像
`stop`	停止全部后台进程

全部实测通过：双击后台运行、/api/status 返回 200、自动探测真实 Mver 猫、stop 生效、首次运行自动生成配置、MCP 握手 14 个工具齐全且 ping 可连通真实猫。README 附百度网盘下载链接（提取码 s4tf），GitHub 访客无需安装 Python 即可直接使用。

期间还修复了开发版仪表盘 pid 文件过期不匹配的问题——打包排障的副产物。

傍晚：文档同步#

功能落地之后同步文档：审查了仓库全部 14 份文档，修正 6 处过时内容。架构文档与需求文档升级至 v1.2（模块清单补入 packaging/、误杀修复写入问题档案、分发项标记为已实现、命名契约写入约束边界）；根 README 的结构图补上 packaging/；四个插件的 README 补充免安装版启动方式。