You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

13 KiB

验证记录

验证日期:2026-10-11(Asia/Hong_Kong)。本机 Windows 11 x64,Node 25.8.0,pnpm 11.5.2,Electron 44.7.0。

检查 结果
pnpm install --frozen-lockfile 通过;显式安装 Electron 并检查原生依赖
pnpm format:check 通过
pnpm lint 通过;没有错误或警告
pnpm typecheck main/preload、renderer 均通过
单元与原生测试 97 个通用单元测试 + 3 个真实 SQLite 测试通过;本机串行执行
pnpm build main、sandboxed CJS preload、Vue renderer 均成功构建
pnpm test:e2e 真实 Electron 测试通过
Windows 打包(下文命令) Windows x64 未安装包成功生成,安全 fuses 保持开启
pnpm test:packaged 实际启动打包 EXE,生产协议、桥接与 SQLite 通过
pnpm audit --prod 无已知漏洞

标题栏缩放对齐验证

本机 150% 缩放下原 1px CSS border 实际取整为约 0.67px,使内容区高度为约 36.33px。改为固定 36px 内容区和独立 1px 分隔带后,在真实 Electron 的 100%、125%、150%、200% 缩放下均验证:标题栏高 37px、内部内容与原生覆盖层均高 36px、32px 操作按钮上下间距均为 2px。已检查 150% 标题栏截图;lint、包含类型检查的 build、两项 Electron E2E、格式检查和 git diff --check 通过。E2E 增加实际原生覆盖层与按钮对齐检查;macOS/Linux 外观尚未实机验证。

应用配置迁移验证

配置迁移补充后,lint、main/preload 与 renderer 类型检查、97 个通用单元测试、3 个真实 SQLite 测试、构建及两项真实 Electron E2E 通过。继续使用本机进程内存限制和串行测试。新增 5 项迁移测试覆盖:旧配置迁移及原文备份、嵌套字段补齐、异常字段单独恢复、连续版本转换、非法写入拒绝、配置降级和迁移失败时保留原文件、损坏 JSON 恢复及重复启动不增加备份。

真实 Electron 的最小能力组合预置无版本配置,验证主题、语言和窗口宽度保留,缺失高度与诊断授权补齐,磁盘文件迁移至版本 1 并生成备份;已有重启持久化测试继续通过。最新源码重新打包至 dist/settings-migration-verify,指定该目录 EXE 的生产协议、SQLite 和桥接测试 1 项通过,安全 fuses 与 ASAR 完整性保持开启。格式检查和 git diff --check 通过。

日志上报与更新基础验证(M1 之后)

本轮 format:check、lint、main/preload 与 renderer 类型检查、92 个通用单元测试、3 个真实 SQLite 测试、构建、两项真实 Electron E2E、冻结锁文件安装和生产依赖审计均通过。继续使用下文的进程内存限制与串行测试方式;不宣称默认 pnpm check 一次运行成功。

新增测试覆盖诊断队列跨重启恢复、整批确认、退避重试、关闭授权后的中止与迟到确认、记录数量和期限、敏感字段拒绝;更新启动/周期检查、失败后重新检查、取消下载、安装前清理、清理后安装错误处理;renderer 进程退出时订阅与文件授权回收。真实 Electron E2E 验证默认关闭上报、renderer 诊断通过受控 API 写入本地文件。已检查更新后的中文深色设置页截图。

最新代码通过同版本本地 Electron 重新打包至 dist/diagnostics-updates-verify,实际启动该目录 EXE 的生产协议、原生 SQLite 与桥接测试 1 项通过;保留 ASAR 完整性与安全 fuses。原 ai-friend 工作区没有改动,既有 v0.1.0 标签没有移动。

诊断网络投递与更新状态测试使用注入的发送器和 updater 后端;尚无真实日志接收地址、签名发布包和更新服务器,因此没有完成真实 HTTPS 接收验收、原生崩溃转储验收、旧版到新版安装与灰度发布验收。这些是具体应用接入和上线时的验收边界,不作为模板封板的前置条件。接入约定见 诊断上报,应用发布验收见 发布流程。

M1 · v0.1.0 封板验收

最终范围见 项目里程碑。2026-10-11 在当前 Windows 环境重新验证:format:check、lint、main/preload 与 renderer 类型检查、81 个通用单元测试、3 个真实 SQLite 测试、构建、默认与最小能力组合的两项真实 Electron E2E、生产依赖审计和冻结锁文件检查均通过。Google DESIGN.md 0.4.0 校验结果为 0 错误、0 警告。

本次首次执行 pnpm check 时 ESLint 因 V8 内存分配失败退出;限制进程内存后 lint 与 typecheck 通过,默认并行测试仍遇内存分配失败。改为相同测试串行执行全部通过;没有修改源码、测试断言或检查规则。实际复验命令:

$env:NODE_OPTIONS='--max-old-space-size=768 --max-semi-space-size=8'
pnpm lint
pnpm typecheck
pnpm exec vitest run --maxWorkers=1 --no-file-parallelism
pnpm test:native
pnpm build
pnpm exec playwright test

因此不能把本次结果表述为未经调整的 pnpm check 一次运行成功。上述内存参数仅用于本次校验进程,不写入应用或默认工程配置。

最新源码重新打包至独立目录,实际 EXE 的生产协议、原生 SQLite、preload 桥接和 renderer 隔离验证通过,ASAR 完整性与安全 fuses 保持原配置:

pnpm exec electron-builder --dir --config electron-builder.config.cjs --config.directories.output=dist/m1-v0.1.0-verify --config.electronDist=D:/Code/electron-template/node_modules/electron/dist
$env:WORKSHOP_PACKAGED_EXECUTABLE='D:\Code\electron-template\dist\m1-v0.1.0-verify\win-unpacked\Electron Workshop.exe'
pnpm test:packaged

最终产物测试 1 项通过;仍不等同于默认 pnpm package 下载解压路径已修复,也不代表安装包签名与跨平台发布验收。git diff --check 通过,原 ai-friend 工作区仍无改动;构建目录和测试临时文件由 gitignore 排除,不进入封板提交。

架构改进本轮验证

能力裁剪、异常诊断和统一异步生命周期改进后,lint、typecheck、79 个通用测试与 3 个真实 SQLite 测试、build、两项真实 Electron E2E 均通过。默认组合与最小组合都实际启动:最小组合不创建数据目录、不显示文件/笔记/草稿/凭证/更新功能,配置与主题继续工作。

新增测试覆盖部署配置校验、启动参数只能关闭能力、不构造禁用服务及资源清理、禁用 API 拒绝、安全错误分类与敏感信息排除、query/mutation 超时、AbortSignal、订阅启动上限与长期存活、取消投递但不重试 mutation、其他 frame 无法取消订阅,以及重连后的旧会话隔离和握手取消。

Windows 继续使用已安装的同版本 Electron,独立输出到 dist/architecture-improvements-verify;默认下载解压路径的本机限制仍未宣布修复。实际启动该目录 EXE 的生产协议、桥接与 SQLite 测试通过;format:check、git diff --check 和冻结锁文件安装也通过。原 ai-friend 的 git status --short 仍为空。评分与保留的边界见 template-review.md,裁剪操作见 capabilities.md。

Renderer 与设计阶段验证

renderer 按功能拆分后,pnpm lint(包含 tokens:check)、typecheck、63 个通用测试、3 个真实 SQLite 测试、build、真实 Electron E2E 和实际打包 EXE 测试全部通过;format:check、git diff --check、冻结锁文件安装也通过。新增行为检查覆盖:作用域退出后的迟到响应、迟到文件授权释放、目录刷新乱序、更新订阅启动与快照竞争、配置写入响应覆盖较新事件;页面无直接 RPC/订阅状态的边界检查,浅深色文本及输入边界对比度、37/36px 高度差也有测试。

Electron E2E 增加次级窗口修改 hash 后回到自身角色页面、具名可聚焦的滚动区域及 overscroll containment、最小 720×520 窗口单列布局。已检查浅深色、中文设置页与最小窗口截图,截图位于 docs/images。Windows 打包采用同版本本地 Electron 与新的 dist/renderer-linear-verify 输出目录,启动其中 EXE 的生产协议、SQLite 与桥接测试通过;该结果不代表下述默认下载解压命令的问题已解决。

原 ai-friend 的 git status --short 仍为空。整体评估与继续修正的问题见 template-review.md。

行为覆盖

首次模板阶段已在全新 Git 检出目录完成首次安装、pnpm format:check 与 pnpm check;没有使用原工作目录的 node_modules 或 out,全部通过。tRPC 迁移后完成常规安装,并通过 pnpm install --frozen-lockfile --ignore-scripts 确认最新锁文件;44 项测试、完整 pnpm check、真实 Electron 与实际打包 EXE 均重新通过。

主进程直接定义 tRPC procedure 后,lint、两种进程的 typecheck、54 个通用测试、3 个 SQLite 测试和构建均通过。真实 Electron E2E 与新 Windows 打包 EXE 均通过。回归检查覆盖完整 main/settings/about 权限矩阵、输出校验、错误脱敏、事件载荷与 owner 隔离、订阅取消和资源清理;模型包不再包含 API 注册表,renderer 只导入 AppRouter 类型。

生成器现在只生成模块 router 并接入应用组合。在隔离副本中生成 capability-demo,主进程编译与客户端 Promise 类型检查通过;冻结锁文件安装通过。

  • 模块依赖顺序、循环/缺失/重复依赖拒绝、启动失败回滚、反向清理、清理异常不中断后续资源。
  • 配置默认合并、损坏文件备份、校验失败不写入、替换失败不改变内存、快照隔离、退订和通知行为。
  • 精确页面来源、IPC 主 frame、窗口角色、请求与结果校验、错误脱敏、未注册方法拒绝、事件接收权限。
  • tRPC 客户端逐路由类型推导、query/mutation 操作类型校验、解析后的输入与输出 schema、订阅限额与并发容量。
  • electron-trpc 退订竞态、刷新与销毁清理、其他 frame 无法退订、全局 listener 清理、preload 单一原生 listener 与固定通道约束。
  • 文件句柄所属窗口、撤销、对话框期间导航、大小/UTF-8 字节限制、二进制拒绝、目录授权和监听释放。
  • 真实 SQLite 迁移失败事务回滚、已有数据保留、拒绝降级、迁移编号校验、参数化文本与重连持久化。
  • 生成器正常集成、拒绝覆盖、拒绝路径遍历、产品元信息同步重命名。
  • 真实窗口的 Node API 隔离、settings 窗口拒绝文件权限、跨窗口语言/主题同步、重启后笔记/草稿/设置/尺寸恢复。
  • Windows safeStorage 加密与解密往返、磁盘无测试凭据明文、删除凭据;无有效系统加密时不执行加密部分。
  • 打包程序使用 app://desktop/index.html,isPackaged=true,原生 SQLite 可写入,renderer 无 require。

本机打包器限制

本次默认 electron-builder 解压下载包时,win-unpacked.tmp → win-unpacked 重命名出现 EPERM;独立目录也复现,未发现本项目打包 EXE 进程占用。复用已有输出目录另遇 EBUSY。未修改打包器依赖,改用已安装的同版本 Electron 44.7.0 和新的验证目录完成打包:

pnpm exec electron-builder --dir --config electron-builder.config.cjs --config.directories.output=dist/direct-trpc-verify --config.electronDist=./node_modules/electron/dist

实际启动 dist/direct-trpc-verify/win-unpacked/Electron Workshop.exe,通过 WORKSHOP_PACKAGED_EXECUTABLE 指定该产物运行 pnpm test:packaged,结果通过。该验证保留 ASAR 完整性与安全 fuses,没有放宽 Electron 安全配置。默认 pnpm package 的解压重命名问题仍属于本机环境限制,不能将上述结果表述为默认命令本次已通过。

尚未在本机验证的范围

macOS/Linux 已提供 CI 流程,但尚未在远程平台执行。平台签名、macOS notarization 和真实更新升级路径需要自己的证书、服务器与发布环境。默认更新禁用状态已验证。

完整依赖审计保留构建工具 sprintf-js 的一个上游未发布修复的中危告警,详情见 安全记录。不能将生产依赖审计通过解释为全依赖树没有告警。

原 Zephyr 项目的 git status --short 为空;没有修改原项目源码或 Git 历史。