我们的桌面 AI 应用(Electron 壳 + Next.js 前端 + 本地 SQLite,模型走 OpenAI 兼容协议,可接云端也可接本机 Ollama)做到上一个大版本之后,对话、知识库、语音、桌面代理这些能力线已经全部跑通:作者本机能打包、能安装、能日常使用。
但真要把安装包发给另一个人,断点一个接一个浮出来:
- exe 和任务栏上挂着 Electron 默认图标,自己的源图直接缩到 16px 糊成一团紫块;
- 安装器只有英文、一键装到底,没有许可页,卸载时删不删数据全凭默认行为;
- 代码签名和图标/版本资源写入被整体关掉,没有签名证书就出不了带品牌的包;
- 没有 Windows 打包流水线,版本号在四个文件里手写,health 接口在安装版上报的是旧版本号;
- 深色模式只做了一半:侧边栏开关写 localStorage,设置页写数据库,两边互相不认,也没有跟随系统;
- 自动更新源停在很早的版本,已经装机的老用户根本收不到新版本;
- 控制面板里的卸载项是默认英文名,多个版本并存时分不清谁是谁;
- 界面文案全硬编码中文,无障碍没有体系,新用户装完之后零引导。
每一条单看都不影响「作者本机能跑」,合起来就是一句话:这还不像一个可以对外分发的正式产品。
v1.2 我们没有新增长功能线。整个版本补的是「从下载安装到第一次成功对话」这条链路上所有不像产品的断点。
这条链路的起点是用户拿到安装包,终点是新用户配好供应商、发出第一句话并收到回复。中间任何一个断点,都足以把一个人永远挡在产品之外——哪怕对话内核本身做得再好。
断点与回答
| 链路上的断点 | v1.2 的回答 |
|---|---|
| 图标全默认,源图直缩糊成色块 | Python + Pillow 生成脚本入仓:按主体包围盒紧裁,产出多帧 ico、安装器侧栏图、web favicon,幂等重跑字节一致 |
| 英文一键安装器,卸载行为不明 | assisted 安装器:可改目录/程序组/快捷方式,简中默认可切英文,GPL 许可页,卸载项显示名带版本 |
| 无证书就没有品牌包 | 签名双态:有证书走 signtool,无证书跳过签名但保留 rcedit 的图标与版本资源 |
| 版本号四处手写、接口误报 | 单一真源脚本从根 package.json 同步四处,--check 进 CI;shared 包导出统一版本号供 MCP 握手与 health/system 接口读 |
| 没有 Windows 发布流水线 | v* 标签触发 + 手动触发双入口:版本硬校验 → 全量单测 → 构建 → 打包发 draft Release → 产物自检 → 上传 |
| 深色半套、双写互斥 | 设置表为唯一真源,localStorage 只是水合前首帧缓存;light/dark/system 三态,matchMedia 实时跟随 |
| a11y 无体系 | skip link、main landmark、命令面板完整 ARIA 语义、全局焦点环、统一确认框;axe-core 六场景门禁 |
| 文案硬编码中文 | 零依赖自研 i18n:纯函数 t()、21 个业务域字典、编译期锁键、中英叶子键对齐测试 |
| 新用户零引导 | 4 步首启向导(复用正式业务链路,不造平行实现)、帮助中心双语 FAQ、快捷键浮层 |
安装器与流水线的细节下一篇讲,深色模式、无障碍与自研 i18n 这「完检三件套」放第三篇。这篇先讲清楚几个关键取舍。
为什么值得停整整一个版本
这类断点有个共性:每一个都不挡作者自己用,所以在功能冲刺期会被无限期推后。而它们彼此又是咬合的——图标要进安装器,安装器要走流水线,流水线要校验版本号,版本号又喂给 MCP 握手和自动更新;深色、语言、首启态又共用一张设置表。零碎掺在功能迭代里做,只会做出一半接通、一半悬空的状态。
一个完整版本的价值,是允许把整条链路从一张源图走到一个可升级的安装包,并让每一环都落一个自动化验证点,而不是靠发版当晚手工对一遍。
取舍一:签名只做流程,不买证书
个人开发者买一张 OV 证书的成本不低,而「没有证书」不该阻塞产品的其他一切。我们把两件本来被绑死的事拆开:
- 品牌资源:exe 图标、版本号、产品名等写入可执行文件的元数据,由 rcedit 完成;
- 可信度:signtool 签名链,回答的是「这个 exe 有没有被篡改过」。
拆开之后,无证书路径也能产出完整品牌安装包,只是没有签名;CI 里只留两个 secret 注入位,将来买到证书,填进去零改配置即可。产物自检脚本也是双态的:有证书就加验签名链,没有就只校验版本资源与图标。
「可能永远没有」的东西应该做成双态,而不是在代码里留一个占位 TODO。
取舍二:应用 ID 冻结,让位于升级链连续性
品牌化最直觉的动作,是连应用 ID 一起改成自己的,但我们没有动。
Windows 上,应用的私有数据目录、注册表卸载项、自动更新器识别的「应用身份」,全部由 appId 推导(形如 com.example.app 的倒序域名串,改一个字符就是另一个应用)。一旦改了 ID,新包会被系统识别为一个全新应用:老版本收不到更新,数据目录对不上,升级链当场断裂。品牌表达全部落在图标、显示名、安装器文案这一层,身份标识冻结不动。
对一个已经有老版本装机量的产品来说,升级链的连续性比命名洁癖重要。
取舍三:卸载默认不删数据,静默卸载永不删
这是本地优先产品的硬约束:用户的对话、知识库、记忆都在本机 SQLite 里,删了没有云端可以恢复。
所以卸载配置里「删除用户数据」恒为关闭。交互式卸载时弹一次二次询问,用户明确确认才删数据;而静默卸载——自动更新跨版本安装时,更新器会用静默参数调用旧版本卸载器——永远不进删除分支,连询问都跳过。升级过程中,任何默认值都不该有机会删掉用户数据。
取舍四:无障碍门禁只卡严重档
引入 axe-core 做自动化扫描后,如果第一次就把所有档位全部卡成红灯,会得到几十上百个对比度和语义问题;单人开发只会被红灯淹没,然后整个门禁形同虚设。
实际做法是:serious/critical(严重与致命)问题零容忍,卡 CI;moderate(次要)问题只出报告,人工逐项关——比如次要文字的对比度就按 4.5:1 标准手动调到位。门禁先立住、可信,再逐步收紧,比一次拉满然后被绕过强得多。
数字与边界
- 七个功能批次合计约 283 文件次改动(批次间有重叠),+8949 / -1233 行,增量主要在双语字典与双语改造、首启向导和测试;
- 运行时依赖 0 新增;dev 依赖只加了 axe-core 的 Playwright 集成这一个;图标生成依赖本机 Pillow,不进 npm 依赖;
- 数据库迁移 1 个,纯数据回填(按有无用户痕迹回填首启标记),没有任何表结构变更;
- 自动化门禁全绿:类型检查、lint、全量单测与集成、端到端用例、生产构建;web 端 61 个测试文件,端到端 32 个用例,另有六个场景的无障碍扫描与六页面双语冒烟。
刻意不做的事也列清楚:
- 不买签名证书:只交付接入位与无证书降级,不处理 SmartScreen 信誉积累;
- 不改应用身份以保升级链,不做其他桌面平台适配,不做视觉体系重设计;
- 非核心面板的英文缺键显式回退中文,而不是强行翻译出半成品。
跨版本真机更新、隔离数据目录的安装包 smoke 这类只能在 Windows 真机上签字的项目,列入封版清单逐项走查——CI 全绿不替代真机装一遍。
发布工程也是功能
这个版本最大的体会是:「可分发、可升级、可卸载、可被读屏使用」和对话能力一样,不会自己长出来,需要被设计。
图标要能从源图确定性地重算出来;版本号要有唯一真源;签名缺失要有体面的降级;卸载要在「用户主动发起」和「更新器静默调用」两种语境下做出不同决策;深色模式的真源只能有一个;每一个界面文案键都要在编译期和测试里被钉住。它们没有一个出现在功能清单上,但新用户对产品的全部信任,恰恰建立在这条链路上的每一个断点都不存在之上。
三篇的分工交代一下:本篇是总览与取舍;下一篇讲安装器、图标脚本与标签发布流水线;第三篇讲深色模式、无障碍门禁与自研 i18n 的技术细节。每篇独立成文,不读另外两篇也能看懂。
下一篇讲 Windows 安装器与标签触发的发布流水线:一个被编译两次的 NSIS 脚本、一个 dev 正常但装包启动即挂的原生动态库,以及流水线首跑踩的换行与权限两个坑。