halo-dark-mode-plugin/docs/review-2026-08-08.md

代码审查交接单 — halo-dark-mode-plugin（2026-08-08）

由审查窗口产出，供开发窗口执行。结论：可合入，无 P1 阻断问题。 审查基线：HEAD = 363f30d（工作区干净，已与 origin/main 同步）。 审查范围：Dark Reader 迁移相关 4 个提交（202ab53 / 0bb552b / 88a071f / 363f30d）。

一、开发窗口无需重复验证（审查窗口已实测）

• vite build 通过：main.js 109.96KB（gzip 37.79KB）、style.css 3.76KB，Dark Reader 已打入 bundle，enable/disable 具名导出解析正常
• vue-tsc --build 通过（exit 0）
• pnpm-lock.yaml 与 file:../third-party/darkreader 依赖一致（含 malevic 0.20.2）
• 构建产物 style.css 已无 [data-halo-theme=dark] 规则（属性属历史遗留）
• DR 产物头 v4.9.129 与 README 一致

二、待办清单（建议按 P2 → P3 顺序执行）

P2-1 FOUC：深色用户刷新 console 会浅色闪烁

• 位置：ui/src/darkreader-engine.ts（watch immediate 块，33-46 行）
• 原因：bundle 在 console 渲染后才执行，DR enable() 是异步分析+注入，无同步兜底
• 建议：enable() 前同步设 document.documentElement.style.colorScheme = 'dark'；或作为已知限制写进文档

P2-2 本地项目文档滞后（与"纯 DR 策略"不符）

• AGENTS.md / CLAUDE.md：仍描述 halo-core.css、overrides/、Monaco 同步、FOUC 同步脚本——这些已不存在（ui/src/styles/ 只剩 index.css + variables.css）
• scripts/README.md 45-52 行：仍写"Monaco 日志查看器主题同步"，实际已改为检查 data-darkreader-mode
• 建议：同步到纯 DR 现状

P2-3 验证工具双份、命名不一致

• scripts/：login-wait.py、scan-dark.py、verify-toggle.py
• workplace/：login_wait.py、scan_dark.py、fetch_bundle.py、probe_conflict.py、aggregate.py
• 建议：统一收口到 scripts/，旧文件删除需用户书面确认

P2-4 前端零单元测试

• pnpm test:unit 为 vitest --passWithNoTests，恒绿
• 建议：为 ui/src/composables/useDarkMode.ts 补 3-4 个用例，覆盖 toggle() 的 light/dark/auto 三种迁移与持久化回退

P2-5 多标签页主题不同步

• 位置：ui/src/composables/useDarkMode.ts
• 建议：监听 storage 事件同步主题

P2-6 可访问性

• ui/src/components/ThemeToggle.vue 10-15 行：div+@click，无 role/tabindex/键盘/aria-pressed
• ui/src/views/SettingsView.vue 36-41 行：选项 div+@click，同上
• 建议：补键盘与 ARIA（或改原生 radio 语义）

P3-1 后端日志

• 位置：src/main/java/run/halo/darkmode/DarkModePlugin.java 24、29 行 System.out.println
• 建议：build.gradle 已有 Lombok，改 @Slf4j + log.info

P3-2 vendored package.json 保留完整 devDependencies

• 位置：third-party/darkreader/package.json
• 建议：裁剪为 name/version/main/module/types/license 最小字段（file: 依赖不会安装 devDeps，但保持干净）

P3-3 无 DR 升级/完整性机制

• 建议：README 或脚本记录 DR 产物 SHA-256，固定版本

P3-4 data-halo-theme 属性 + variables.css 已成历史遗留

• 构建产物已无 [data-halo-theme=dark] 规则，属性无 CSS 消费方
• 建议：保留可以，但注释说明是兼容性遗留

P3-5 文案硬编码中文，无 i18n

• 低优先级（目标用户中文），可暂缓

P3-6 plugin.yaml spec.enabled: true

• 确认是否有意（Halo 通常安装后由用户启用）

三、完成后回归验证清单

cd ui
pnpm build          # 构建通过
pnpm type-check     # 类型检查通过
pnpm lint           # 通过
# 真实环境验证（AGENTS.md 规定流程）
python scripts\verify-toggle.py   # 三向断言全 PASS（属性/存储/Dark Reader 翻转）

四、无需改动的亮点（避免开发窗口误改）

• third-party/darkreader 只跟踪 5 个构建必需文件 + gitignore 白名单，LICENSE/版权头保留，合规 ✅
• style.css 从 ~500KB 降到 3.76KB，纯 DR 策略成立 ✅
• verify-toggle.py 的 darkreader 断言与策略一致 ✅