阶段 0 工程基线

返回文档导航

• 本文档记录阶段 0 的验证范围、性能基准和人工回归清单。
• 后续依赖升级或模块重构不得降低这些基线。

自动化验证

本地完整验证：

npm run validate

验证由以下部分组成：

• TypeScript：使用 strict 检查主进程、服务端、预加载 API、渲染 ESM 模块、工程脚本、测试及 Windows Script Host 辅助脚本。

• npm run test:build：两次完整重建，检查编译入口、页面资源、共享脚本加载顺序，并确认删除临时源码后没有残留产物。该命令独占 .build/，不要和其他构建、测试并行运行。

• ESLint：检查主进程、预加载脚本、渲染进程和构建脚本；测试保持由严格类型检查及执行验证。

  • 控制流块使用花括号及两空格缩进；带注释的空 catch 块也需将注释放在独立行，保留忽略异常的原因。
  • npm run lint 先检查文件行数，再执行 ESLint；需要单独定位格式错误时可运行 npx eslint .。
  • 当前文件长度门禁为 800 行，Markdown 和测试文件不进入该脚本的检查范围；超过上限的模块另行集中拆分，不与纯格式修复混合。

• Node 单元测试：覆盖文档状态、路径和协议校验、文件读写、图片复制、Markdown 渲染与 HTML 清洗。

• Electron 冒烟测试：使用与正式应用一致的安全配置加载页面，确认预加载 API、初始无文档状态、新建标签和预览渲染可用。

• electron-builder --dir：验证当前平台可以生成未签名测试应用。

• GitHub Actions 会在 Windows 和 macOS 上分别执行 lint、单元测试、Electron 冒烟测试和目录打包，并保留 7 天测试制品。

• 正式签名、公证和安装包发布属于后续发布工作。

Electron 冒烟测试

• npm run test:smoke 先完整构建一次 TypeScript 产物和编辑器，然后依次执行全部专项分支、独立冒烟测试和原有综合流程。
• 总入口收集 .build/test/electron-smoke.js 中的全部 --…-only 分支，以及 package.json 中的 test:smoke:* Electron 测试入口。
  • 没有单独 npm 脚本的分支也会执行。
  • 每项使用独立 Electron 进程和测试目录，避免专项分支提前退出或共享状态影响后续测试。
  • 共用 Electron 流程销毁测试窗口后，等待已开始的 IPC 请求结束，再删除临时目录；清理开始后不接受排队请求，避免恢复会话和仓库界面状态的原子写入与目录删除冲突。
  • 测试串行执行，避免系统剪贴板与快捷键互相干扰。
  • 任一测试失败后继续执行其余项目，最后列出失败项目并返回非零退出码。
  • 单项进程最长运行 6 分钟，防止未正常退出的测试阻塞剩余项目。
  • Windows 回收站专项在其他平台由测试自身跳过。
  • 真实拖拽专项会显示测试窗口，并在系统临时目录生成 mynote-tree-drag-live.png 和 mynote-tree-drag-live-copy.png。
• 可在 -- 后指定一项或多项验证；未指定的项目不会执行。
  • 分支参数：npm run test:smoke -- --tree-drag-live-only。
  • 简写参数：npm run test:smoke -- --tree-drag-live --editor。
  • 原有综合流程：npm run test:smoke -- --full。
  • 重复指定同一项只执行一次；未知参数会报错，不会静默运行其他测试。
• 专项断言按当前界面和隔离环境验证。
  • 大纲图标按钮检查不包含使用文字标签的拼音开关。
  • 回收站流程等待目录树条目移除和操作结束（最多 10 秒），再执行重命名；Windows 删除后定位回收站记录也属于该操作。
  • 大纲专项和综合流程等待预览源码定位区块实际生成，最多等待 5 秒；本地大纲就绪不代表跨 IPC 的预览已就绪。
  • 选区工具栏的上方定位检查使用隐藏窗口编辑器视口内的选区。
  • dirty-sync 的账号替身包含已同步笔记库的远端成员查询，定时同步仍经过真实管理器和同步引擎。
  • dirty-sync 的同步配置使用临时目录，不迁移 Chromium 会话目录，避免 Windows 网络数据库锁影响清理并掩盖断言错误。
• 总入口和单项 npm 专项在测试结束后汇总每项耗时和总耗时，单位为秒，保留两位小数。
  • 每项执行完立即输出一次该项耗时，再启动下一项；最后的统一耗时汇总保持不变。
  • 每项耗时包含 Electron 启动、断言和清理；失败或超时的项目也报告耗时。
  • 总耗时包含汇总器执行各项测试及处理诊断输出的时间，不包含命令前置的完整构建。
• 原有 npm run test:smoke:* 专项命令继续可用，并使用相同汇总器报告数量。
  • 例如 npm run test:smoke:workspace-trash 成功时输出 Smoke suites: 1/1 passed.。
  • 失败时输出 Smoke suites: 0/1 passed. 和失败项目名称，并返回非零退出码。
• 直接执行 node scripts/run.mts electron test/electron-smoke.js 仍只运行原有综合流程；需要全部分支时使用 npm run test:smoke。

TypeScript 构建边界

• Node/Electron 模块使用 tsconfig.node.json，编译为 CommonJS。
• 浏览器 ESM 使用 tsconfig.renderer.json，.mts 输出为 .mjs。
• 浏览器端冒烟夹具使用 tsconfig.scripts.json，显式导入生产 ESM 模块，不引入 Node 全局类型。
• 日志值快照由 src/shared/log-values.mts 共用，随 ESM 编译，不再使用独立的日志编译配置。
• Windows 回收站辅助脚本使用 tsconfig.wsh.json，输出 ES5 普通脚本，供 Windows Script Host 执行，不注入 CommonJS 导出标记。
• 构建及命令引导器使用 Node.js 24 原生类型擦除；应用与测试执行编译产物。
• .build/ 保留目录结构和独立包元数据，重建前只清理这个目录；源码检查不包含构建产物。
• 安装包包含 .build/src/、编辑器资源和依赖许可证，不需要 TypeScript 源码。

性能基准

运行：

npm run benchmark

基准条件与结果：

• 输入：约 100 KiB、包含标题、强调、链接和列表的 Markdown。

• 方法：预热后连续渲染 20 次。

• 环境：2026-08-14 的开发环境，Node.js 22.23.2。

• 结果：多次运行的平均完整解析与清洗耗时约为 100–130 ms。

• 该结果用于发现相对性能回退，不作为所有设备的硬性指标。

• 阶段 1 已在渲染端增加去抖和过期结果丢弃，后续仍需在真实 Electron IPC 路径补充输入延迟指标。

人工回归清单

发布测试制品前至少检查：

文档与标签

• 应用启动且没有可恢复会话时不自动创建文档，保存和图片操作保持不可用。
• 新建文档会出现欢迎内容和一个活动标签。
• 可一次打开多个受支持的 Markdown 文件；重复打开只切换标签。
• 在两个标签中分别编辑并滚动到不同位置，来回切换后确认各自的滚动、选区及撤销/重做记录仍然保留。
• 编辑后标签显示未保存标记，保存或撤销至最近保存的正文后标记消失；继续撤销越过保存点时标记重新出现。
• 新文档首次保存会弹出保存对话框，并以当前笔记库根目录作为初始保存位置。
• 关闭未保存标签会确认，取消确认不会丢失内容。
• 关闭最后一个标签后保持无文档状态，可以再次新建或打开文档。

Markdown 与预览

• 标题、列表、表格、代码块、链接和图片可以正常预览。
• 当前行高亮始终保留；列表项仍可以单独高亮。
• 光标移动时，源码与预览另以较淡背景高亮最近所属大纲节点的完整范围（含标题和子章节），截至下一个同级或更高级标题之前；大纲面板隐藏时仍生效。
• 例如 aaaa 归属 # a，b1b1 归属 ## b1 而不是 # b；选区存在时按活动光标端确定归属。
• 首个标题之前或没有标题时，源码保留当前行高亮，预览保留对应区块高亮；列表项可以单独高亮。
• 编辑区与预览区可以双向同步滚动。
• 预览开关可以隐藏和恢复预览区域。
• HTTP、HTTPS、邮件链接由系统外部应用打开，应用窗口不发生导航。
• javascript:、file: 等危险外链不会被打开。

图片与文件

• 选择本地图片会复制到文档同级 assets/ 并插入相对路径。
• 粘贴剪贴板图片会保存 PNG 并插入相对路径。
• 未保存文档插入图片时会先要求保存文档。
• PNG、JPEG、GIF、WebP、BMP 可插入，其他扩展名会被拒绝。
• 中文文件名、中文正文和 LF 换行可以正常读写。

平台与界面

• Windows/macOS 均可启动打包后的测试应用。
• 窄窗口切换为上下布局，宽窗口保持左右布局。
• 工具栏、标签栏和状态栏不随编辑内容滚动。
• macOS 使用 Command、Windows 使用 Ctrl 执行既有快捷键。

已知未覆盖项

以下能力属于阶段 1 或更晚，本阶段不宣称已经解决：

• 原子保存、恢复稿、外部文件监听和并发修改冲突界面已在阶段 1 补齐，详见阶段 1 可靠性设计。
• 自动更新、正式代码签名和 macOS 公证。
• 输入去抖和过期渲染结果丢弃已在阶段 1 补齐；持续性能门槛仍待真实设备数据确定。
• 笔记库、目录树和搜索已在阶段 2 补齐，详见阶段 2 桌面笔记库。
• 同步协议与托管同步已在阶段 4/5 补齐，详见阶段 5 账号与托管同步 Beta。