verify

驱动脚本是 scripts/redesign/drive.mjs。它用 Playwright 的 _electron 启动当前工作树的构建产物（electron .），每个会话（一次冷启动）一个全新的隔离目录，模型调用全部走本机假服务，不调用真实模型。单跑一个场景就是只含这个场景的会话。

应用窗口不出现在屏幕上。驱动用 electron -r scripts/redesign/offscreen-window.cjs 在应用主进程脚本之前挂上 browser-window-created 监听：窗口一创建就移到所有显示器右侧之外，去掉任务栏按钮，设为不可激活并交还焦点，不打扰正在用电脑的人。截图走页面视口，与窗口位置无关；页面焦点由 Playwright 的焦点模拟提供，document.hasFocus() 仍为 true。每次截图前断言 document.visibilityState 为 visible，防止屏幕外窗口被当作隐藏而停帧。

启动前

在要验证的工作树根目录依次运行：

pnpm install --frozen-lockfile
pnpm rebuild:electron
pnpm build

驱动加载的是 dist/ 与 dist-electron/，改了 src/ 或 electron/ 必须重新 pnpm build。better-sqlite3 刚为 vitest 切到 Node ABI（pnpm prepare:native-node）时，先 pnpm rebuild:electron 再驱动。

命令

pnpm verify:drive -- --scenario <名称> [--theme light|dark] [--shell writer|stage] [--out <目录>] [--dump-dom] [--console] [--video] [--app-root <目录>]
# 等价于
node scripts/redesign/drive.mjs --scenario <名称> ...

• --theme 默认 light，即外观里的「浅色」；dark 为「深色」。
• --shell 只对 RD-10 之前的构建（--app-root 指向的 trunk）有意义：不给时不碰外观里的外壳偏好（旧外壳），stage 选 RD-3 起的流程脊外壳，与主题在同一次写入里改，只重载一次；RD-2 及更早的 trunk 不认识 stage，不要传。RD-10 起的构建只有纸墨外壳，外观写在 v3 键里，没有外壳偏好：--shell 不必传，传 writer 直接报错。
• --video 在每个截图点的 run 期间录屏：CDP Page.startScreencast 收帧，按帧时间戳交给本机 ffmpeg 编成 H.264 mp4，写到 <场景>-<主题>.mp4。不需要 Playwright 自带的 ffmpeg。
• --out 默认 .runtime/redesign-baseline/（已被 git 忽略）。
• --app-root 默认当前工作树。性能对照时指向 trunk 的工作树，用同一个驱动测两边；目标工作树也要先跑完上面三条命令，它加载的是自己的 dist-electron/ 和 better-sqlite3。
• 退出码：0 全部通过；1 有场景失败、残留进程或隔离目录外写入；2 参数错误。

RD-10 删除旧外壳之后，场景分三类：

• 只走旧外壳的场景只对 trunk 跑（--app-root）：下面「场景」表的 8 个基线场景与 baseline-all、nav-*、write-latency、settings-appearance、run-write-steps、legacy-no-chat、arch-legacy-sidebar。对照时 head 一侧改跑对应的新外壳场景。
• 两种外壳都能跑的场景运行时按页面上有没有纸墨外壳选页面对象，head 与 trunk 用同一条命令：startup-timing、idle-memory、chapter-switch、chapter-open、typing-latency、chapter-regression、blueprint-regression、blueprint-timing、refs-regression、refs-timing、new-project-files。
• 其余声明了 shell: 'stage' 的场景只对 RD-3 及以后的构建跑。

场景

示例作品名为「灯塔」，第 1 章「旧港」，由公开 IPC 预置后从书房打开；打开后等项目树统一刷新结束再继续，之前的画面随刷新进度变化。

场景的 run 可以调 context.restart()：退出应用、用同一隔离目录冷启动（不重写外观），context 里的 app、page 换成新的，用于验证「重启后仍保持」。

scripts/redesign/scenarios.mjs 里每个场景分三段：setup 是单跑时的前置（预置作品、写一章、审稿等），run 从前置状态走到截图状态，after 在截图后执行。一个会话只跑首个场景的 setup，然后依次 run、截图、after。baseline-all 的会话在 BASELINE_SESSIONS：

• baseline-shelf：settings → new-project。不预置作品，new-project 要在空项目目录里建「灯塔」，与示例作品不能共存。
• baseline-sample：open-sample → write-chapter → run-panel → review → revise-merge → finalize。预置一次带草稿_v1 的示例作品，后面每步接着上一步的状态。

改动前 baseline-all 每个场景各冷启动一次（8 次）；现在 2 次。

输出

在 --out 目录下：

• <场景>-<主题>.png：场景截图，1440×900（stage-1280 为 1280×900）。
• --video 时另有 <场景>-<主题>.mp4，结果项的 video 字段指向它。
• <场景>-<主题>.json：本次运行的结果数组，每个截图点一项。scenario、screenshot 属于这个截图点；session（会话名，单跑时等于场景名）、timing、shell（外壳的 data-shell-presentation，writer 或 stage：startup-timing 取计时那次启动显示的外壳，其余场景取写好外观、重载之后的外壳，用来确认测的就是要测的外壳）、externalRequests、residualProcesses、externalWrites、quit、isolationRoot 属于整个会话，会话里每一项都抄一份；会话用了夹具模型时另含 modelRequests（整个会话里假服务收到的全部请求数，嵌入请求也计入，与 --console 里的 [fake-model] 行一一对应）。失败时含 error：截图点自己的失败写在该项；同一会话里排在失败点之后的截图点不再运行，error 写明是被哪个场景拖住；会话级失败（启动、外部请求、退出、进程枚举）写进该会话的每一项。
• 失败时额外写 <失败场景>-<主题>.failure.png、.dom.html、.aria.yml 和 <会话>-<主题>.console.log，隔离目录保留以便排查。

每个会话结束后，驱动检查三件事，任一不满足即退出码 1：

• externalRequests 为空。每个会话都在 Electron 启动后替换主进程的 globalThis.fetch：用夹具模型的会话只放行 https://api.openai.com/v1/* 并改道到本机假服务，其余会话一律不放行。被拒的请求记下来源并抛错。检查范围只有主进程 fetch，且从 electron.launch 返回后才生效；更早的请求、渲染进程的请求和 Electron net 模块的请求都不在内。
• residualProcesses 为空：应用关闭后，以 --user-data-dir 匹配不到存活进程。子进程退出需要时间，驱动最多查 10 次、间隔 300 ms。
• externalWrites 为空：~/.vela、%APPDATA%\ai-novel-writer、%APPDATA%\AI小说作家 的最新修改时间不变。

枚举或结束进程本身失败时，原因写进该会话每一项的 error，结果 JSON 照常写出。

只读诊断

node scripts/redesign/drive.mjs --scenario open-sample --dump-dom --console --out <目录>

• --dump-dom 在每个截图点截图后写 <场景>-<主题>.dom.html（page.content()）和 .aria.yml（Playwright 无障碍快照）。改页面对象前先看 .aria.yml，选择器优先用其中的角色与可访问名称。
• --console 每个会话写一份 <会话>-<主题>.console.log（单跑时会话名就是场景名，baseline-all 为 baseline-shelf、baseline-sample）：渲染进程控制台、页面异常、主进程 stdout/stderr，以及假模型每次请求的分类（[fake-model] prose|review|revision|character-state|embedding）。

截图可重复性

同一场景连续跑三次再比较：

for i in 1 2 3; do node scripts/redesign/drive.mjs --scenario review --out shots/r$i; done
node scripts/redesign/pixel-diff.mjs shots/r1/review-light.png shots/r2/review-light.png shots/r3/review-light.png

pixel-diff.mjs 输出各张相对第一张的不同像素占比，maxRatio 小于 0.005 时退出码 0，否则 1。尺寸与第一张不同的图记为全部不同（ratio 为 1），reason 写明两边尺寸。任一通道差值超过 2 级才算不同像素（ratio），因为同一状态连续截图时，渲染器在背景模糊和渐变上偶发全屏 ±1～2 级抖动；逐字节比较的结果另列为 strictRatio，供判断差异是不是这种抖动。

启动耗时

startup-timing 的 timing 字段：readyToShowToInteractiveMs（主窗口 ready-to-show 到书房「新建作品」按钮可见，计划里的性能指标）、launchToInteractiveMs、navigationToInteractiveMs。ready-to-show 监听在预加载脚本里、先于移窗挂上，窗口创建前就已就位，所以每次都有值。trunk 与 head 交替各跑 5 次取中位数：

node scripts/redesign/drive.mjs --scenario startup-timing --app-root <trunk 工作树> --out <目录>
node scripts/redesign/drive.mjs --scenario startup-timing --out <目录>

空闲内存

idle-memory 与 startup-timing 一样先在同一隔离目录预启动一次写好主题，再冷启动一次；第二次启动到书房可交互后静置 10 秒，再每隔 1 秒用 app.getAppMetrics() 采样 5 次全部进程的内存，结果写进 memory：workingSetKB、privateKB（Windows 才有私有字节）是各次合计的中位数，byType 按进程类型（Browser、Tab、GPU、Utility 等）各取工作集中位数，samples 是采样次数。不截图、不用夹具模型。计划 RD-10 的性能复测与启动耗时交替跑：trunk 与 head 各 5 次，取中位数比较，跑的时候机器上不开别的程序。

node scripts/redesign/drive.mjs --scenario idle-memory --app-root <trunk 工作树> --out <目录>
node scripts/redesign/drive.mjs --scenario idle-memory --out <目录>

不进 baseline-all 的场景

scenarios.mjs 的 EXTRA_SCENARIOS 只能单跑，不进 baseline-all。run 的返回值写进结果的 measured。需要卡住模型调用时，场景从上下文的 fake.gate 调 hold()，在 after 里 release()。hold() 只卡对话请求；只走嵌入的步骤（参考文本入库）用 hold({ embeddings: true }) 连嵌入一起卡。fake.gate.waiting 是正卡在门上的请求数，截图前等它大于 0，画面才停在确定的那一步。

nav- 场景对 trunk（--app-root）与 head 各跑一次，两边都通过即行为一致。write-latency 与 startup-timing 一样交替各跑 5 次取中位数。

新外壳（RD-3 起）

页面对象在 scripts/redesign/pages/stage.mjs，选择器用角色与可访问名称（流程脊是 navigation「创作流程」，章节是其中的列表「章节」，标签条是 tablist「已打开的页面」，顶栏是 banner）。示例作品在 scripts/redesign/stage-sample.mjs：「灯塔」12 章全有蓝图，架构四节齐全，1、2 章定稿，3 章已审稿，4 章草稿，其余待写；与旧外壳基线的 SAMPLE 分开，基线截图不受影响。打开后落在第 4 章（几章都在写时取最后一章在写的，#407 第 2 轮用户决定）；seedStageSample 默认等落点后切到第 3 章并关掉第 4 章标签，场景都从只开着第 3 章开始（对照用的旧构建本来就落在第 3 章，不切）。两种外壳都能用这份示例：新外壳从书房打开，旧外壳从项目树打开第 3 章草稿。

lane 1 的旧外壳部分：head 与 trunk 各跑一次 baseline-all，逐张 pixel-diff.mjs，maxRatio 小于 0.005。

perf：三组交替，各预热 2 次不计，再各计 5 次：trunk 旧外壳、head 旧外壳、head 新外壳。head 旧外壳对 trunk 旧外壳量的是新外壳模块被 App.tsx 静态引入后旧外壳用户付出的启动代价。这是 RD-3 到 RD-9 的做法；RD-10 起 head 没有旧外壳，只比 trunk 旧外壳与 head 纸墨外壳两组，下面带 --shell stage 的命令对 head 去掉 --shell。

node scripts/redesign/drive.mjs --scenario startup-timing --app-root <trunk 工作树> --out <目录>
node scripts/redesign/drive.mjs --scenario startup-timing --out <目录>
node scripts/redesign/drive.mjs --scenario startup-timing --shell stage --out <目录>
node scripts/redesign/drive.mjs --scenario chapter-switch --app-root <trunk 工作树> --out <目录>
node scripts/redesign/drive.mjs --scenario chapter-switch --shell stage --out <目录>

startup-timing 三组都先在同一隔离目录启动一次写好主题（新外壳另写外壳偏好）再退出，计时的是之后那次冷启动；首次启动还要迁移旧配置、建库，与之后的启动不可比，所以两侧都不计首次。启动计时以驱动发现「新建作品」可见为准，Playwright 的轮询间隔随等待时间变长，所以晚出现的界面会被多计一些。

运行侧页（RD-4 起）

场景在 scripts/redesign/run-scenarios.mjs，页面对象在 scripts/redesign/pages/run-sheet.mjs（侧页是 complementary「运行」，分页是其中的 tab，运行与恢复项是 article，按标题命名）。假模型另有两种回复：fake.streamProse({ chunks, intervalMs }) 之后的正文按块定速流出，每块发出的时刻记进 fake.streamLog；fake.replyCharacterCards() 之后，提示词里有「【资料 」时回一份角色提取 JSON（守塔人与林岚），不开时照旧回正文、提取失败。复制类操作在页面里改写 navigator.clipboard.writeText 记录内容，不碰系统剪贴板。

run-olddata 的状态对比只看对话内容：重开作品时主进程会把旧会话里没写完的助手任务登记为暂停、改期限，这是主进程的租约记账，与界面无关。

书房、设定与设置（RD-5 起）

书房、设定页与设置页的页面对象也在 pages/stage.mjs：书架是列表「最近的作品」，封面按钮叫「预览《书名》」，右侧概览是区域「《书名》概览」，里面唯一的主按钮是「打开《书名》」（只预览的书）或「继续写作 · 下一步」（当前作品）；每本书的更多操作是「《书名》更多操作」菜单。openFromLibrary 先点封面再点「打开《书名》」，openFromPalette 从 Ctrl K 打开（同一部作品也会开新的会话）。新建作品的对话框旧外壳叫「新建小说项目」，新外壳叫「新建作品」，bookshelf.createProject 两种都认。设定页的核心大纲是文本框「核心大纲」（缺这项时名字带「 · 必填」），三项必填是下拉「类型」「目标读者」与一组「篇幅」，更多设定是按钮组「更多设定」，展开的每项是同名区域；dirtySetup 在核心大纲末尾补一句。假模型认出配置 JSON 合同的提示词时返回 FIXTURE_CONFIG。设置页是导航「设置分组」，每页标题是一级标题；openSettings 从流程脊打开，showSettingsPage 切页，closeSettings 点「返回作品／返回书房」。

页面内计时

计时会话（startup-timing、library-timing）启动时设环境变量 DRIVE_RENDER_TIMING，offscreen-window.cjs 据此给默认会话注册页面预加载 render-timing-preload.cjs：它在页面脚本之前装好 MutationObserver，把「新建作品」与书架上的书第一次进入 DOM 的时刻（performance.now()）写在 <html> 的 data-drive-interactive、data-drive-shelf 上，驱动启动后读出，写进 timing.renderInteractiveMs、timing.renderShelfMs。它们没有 Playwright 轮询的量化误差。其他场景不注册这个预加载。

改外壳时

类名选择器只出现在 scripts/redesign/pages/，按任务域分文件：shell（启动、外壳就绪、标题栏、状态栏、左右栏与可收起面板）、bookshelf（旧外壳书房与两种外壳的新建作品）、project（项目树）、chapter（单章写作、审稿、修稿合并、定稿）、run-panel（运行面板）、settings（设置，含外观里切换界面布局）、materials（知识库与角色卡导入）、stage（新外壳：流程脊、章节列表、标签条、Ctrl K 与 Ctrl P、保存状态、沉浸写作、书房）、run-sheet（新外壳的运行侧页）。shell.waitForShell 对两种外壳都成立。外壳替换后只改这些页面对象，场景 scripts/redesign/scenarios.mjs 不动。

/.claude/ 在 .gitignore 里，提交本文件的改动要用 git add -f .claude/skills/verify/SKILL.md（或 git add -u）。假模型在 scripts/redesign/fake-model.mjs，按提示词特征返回正文、短细纲（与正文同一段文字，但不参与定速流出）、审稿 JSON、修稿正文、角色状态 JSON 或角色提取 JSON。

架构阶段与角色名单（RD-6 起）

场景在 scripts/redesign/arch-scenarios.mjs，页面对象在 scripts/redesign/pages/architecture.mjs（四节是 region，按节名命名；角色名单左栏是 complementary「角色名单」；生成架构对话框是 dialog「生成架构」）。示例作品沿用「灯塔」，按场景清空架构的某几节；示例作品有蓝图与正文，打开后落在写作位置（用户决定 B，#394 §6），场景等落点定下后从流程脊进架构。驱动读库用界面那次打开作品的会话（在主进程里包一层 project:open 记下租约），不必重开作品。夹具模型对「本次只写第 N 章」的情节大纲请求回这一章的二级标题与正文。

perf 交替各跑 5 次取中位数：

node scripts/redesign/drive.mjs --scenario arch-timing --app-root <trunk 工作树> --out <目录>
node scripts/redesign/drive.mjs --scenario arch-timing --out <目录>

蓝图阶段与写作弹层（RD-7 起）

场景在 scripts/redesign/blueprint-scenarios.mjs，页面对象在 scripts/redesign/pages/blueprint.mjs（章节规划是 complementary「章节规划」，单章蓝图是 region「第 N 章蓝图」，写作弹层是 dialog「本次写作选项」，主按钮「写第 N 章」直接开始写）。新外壳从蓝图写下一章的场景（stage-run、stage-tour、运行侧页各场景、write-stream --shell stage）都改走 blueprint.writeNext；旧外壳仍走 chapter.writeNextChapter。新外壳写作此章按设定里的每章字数写，不再在写作时填字数，所以示例作品的每章字数是夹具模型一次写得完的 100。假模型另记 fake.chats：每次对话请求的种类、模型与消息原文。

node scripts/redesign/drive.mjs --scenario blueprint-regression --app-root <trunk 工作树> --out <目录>/trunk
node scripts/redesign/drive.mjs --scenario blueprint-regression --shell stage --out <目录>/head
node scripts/redesign/drive.mjs --scenario blueprint-timing --app-root <trunk 工作树> --out <目录>
node scripts/redesign/drive.mjs --scenario blueprint-timing --shell stage --out <目录>

正文单章视图（RD-8 起）

场景在 scripts/redesign/chapter-scenarios.mjs，页面对象在 scripts/redesign/pages/chapter-view.mjs（单章视图是 .stage-ch，审稿侧页是 complementary「审稿报告」，修稿合并是 region「修稿合并」，定稿后处理是 region「定稿后处理」，版本切换器是按钮「本章版本：…」，定稿确认是 dialog「定稿第 N 章？」）。新外壳打开第 N 章就是单章视图，示例作品第 3 章带一份审稿（已审稿，打开时默认展开审稿侧页）；待写章显示本章蓝图与「写作此章」，草稿状态主按钮是 AI 审稿，已审稿是「按 N 项意见修稿」，有待合并修稿时直接摆出合并视图，已修稿是定稿，定稿后列出后处理各步。假模型另有 fake.breakCharacterState()：之后定稿后处理的角色状态更新收到不是 JSON 的回复而失败，传 false 恢复。

node scripts/redesign/drive.mjs --scenario chapter-regression --app-root <trunk 工作树> --out <目录>/trunk
node scripts/redesign/drive.mjs --scenario chapter-regression --shell stage --out <目录>/head
node scripts/redesign/drive.mjs --scenario chapter-open --app-root <trunk 工作树> --out <目录>
node scripts/redesign/drive.mjs --scenario chapter-open --shell stage --out <目录>
node scripts/redesign/drive.mjs --scenario typing-latency --app-root <trunk 工作树> --out <目录>
node scripts/redesign/drive.mjs --scenario typing-latency --shell stage --out <目录>

草稿、审稿、合并、定稿、1280 与沉浸写作各场景都用 contrastFailures 核对单章视图的文字对比度（正文与合并栏 4.5，说明文字 3）。屏幕外窗口的动画帧可能被系统节流，chapter-open 与 typing-latency 都同时报不依赖动画帧的 DOM 口径。RD-X1 起打开作品的默认落点随提交同步落下，读文件树期间打开的运行侧页不再被收起（x1-run-sheet-keep）；afterProjectOpenSettles 的 2 秒等待是之前留下的，保留无害。审稿侧页属于单章视图，不随落点收起。

作品资料页（RD-9 起）

场景在 scripts/redesign/refs-scenarios.mjs，页面对象在 scripts/redesign/pages/refs.mjs（流程脊「作品资料」里的三个按钮；剧情树是 table「剧情树」，线索路线是 list「线索路线」，知识库资料是 navigation「资料」，版本历史的章节是 navigation「章节」、各稿是 list「版本时间线」、对比是 region「对比」里的 article「与当前稿的差异」）。示例作品在 seedStageSample 之上加一条伏笔线索「雾钟为何提前」和第 3 章的第二稿。fake.replyPlotTree() 之后的剧情树整理回一份两轨 JSON（定稿章与单数位蓝图章进主线「雾钟与沉船」，双数位蓝图章进支线「父亲的地图」），来源取自提示里的资料；不开时假模型回正文，剧情树落到单轨的确定性快照。知识库导入用 stubOpenFiles 让系统打开对话框直接返回两份资料，外发提取确认点「取消」。

perf：trunk 与 head 交替各跑 5 次，取两项各自的中位数。head 加 --shell stage，trunk 用旧外壳的左栏「历史」「剧情」进入。

node scripts/redesign/drive.mjs --scenario refs-timing --app-root <trunk 工作树> --out <目录>
node scripts/redesign/drive.mjs --scenario refs-timing --shell stage --out <目录>

统一视觉层（RD-V）

场景在 scripts/redesign/visual-scenarios.mjs，都走新外壳，浅深各跑一次。断言的是浮层渲染进带 .paper-ink 的纸墨根或宿主（#ai-novel-ink-overlay），才取得到纸墨令牌与深色。对话框类场景截图前等 400 ms，让遮罩与对话框的淡入走完。

外部审查修复（RD-X1）

场景在 scripts/redesign/x1-scenarios.mjs，都走新外壳。竞态用主进程通道上的门稳定复现：holdChannel(app, 通道, { after }) 卡住接下来的调用，after: true 时先交给原处理函数、卡住的是回复（主进程已做完、渲染进程迟迟收不到）；untilHeld 等到有调用卡在门上，releaseChannel 放行。recordCalls 记下通道之后每次调用所属的作品路径，stubChannel 把通道换成固定回复并计数；两者遇到主进程没有的通道都直接报错，通道改名后断言不会因为记不到调用而假绿。seedTwoBooks 先建「港口」（三章定稿，第 3 章定稿带历史审稿），再建并打开灯塔；两部作品第 3 章的稿 id 相同。假模型另有 fake.failProse()：之后的正文回复（含 streamProse 的流式回复）以 content_filter 结束，写稿在这次打开里失败。蓝图页的 generateRange 让「架构还不完整」警告与运行侧页展开竞争等待，调用前运行侧页要收起。除 x1-open-folder-cancel（RD-V 栈顶上也应通过）和 x1-import-overlap（RD-V 栈顶不适用）外，每个场景对 RD-V 栈顶的构建（--app-root）跑一次应失败；所有场景对 head 跑一次都应通过。

外部审查修复（RD-X2）

场景在 scripts/redesign/x2-scenarios.mjs，都走新外壳，复用 RD-X1 的 holdChannel、untilHeld、releaseChannel 与 seedHarbor。每个场景把作者看到的值收进 measured 最后一次断言，对 RD-X1 栈顶的构建（--app-root）跑一次应失败，失败消息里能看到每一项的值。假模型另有 fake.replyReview(json)：之后的审稿（含合并后的复验）回这份 JSON；复验只覆盖带正文证据区间的本章目标意见，默认审稿只有文学类意见，合并后不会复验。主进程没有默认检索模型时退回默认生成模型，所以要演示「没有检索模型」得先删掉生成模型。

外部审查修复（RD-X3）

场景在 scripts/redesign/rdx3-scenarios.mjs，都走新外壳。要看修复前的样子，用 --app-root 指向 RD-V 栈顶（87097dbb）的构建再跑一次：这些场景在那边应当失败。

切换默认外壳（RD-10）

场景在 scripts/redesign/rd10-scenarios.mjs，对应计划 RD-10 的实机 lane 与功能保全矩阵的验证截图。被测构建是 RD-10 之后的纸墨外壳，--app-root 指向最终安装包的构建树。