81 lines
4.0 KiB
Markdown
81 lines
4.0 KiB
Markdown
# 代码审查交接单 — 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 通常安装后由用户启用）
|
||
|
||
## 三、完成后回归验证清单
|
||
|
||
```bash
|
||
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 断言与策略一致 ✅ |