fix: 按审查报告修复 P2/P3 问题并升级 1.0.5

docs/fix-plan-2026-08-08.md

@@ -0,0 +1,151 @@
+# 修复计划 — halo-dark-mode-plugin（2026-08-08）
+
+> 依据：`docs/review-2026-08-08.md`
+> 状态：待用户审批
+> 审批通过后按 P2 → P3 顺序执行
+
+## 一、修复总览
+
+| ID | 优先级 | 问题 | 修复方式 | 主要涉及文件 |
+| --- | --- | --- | --- | --- |
+| P2-1 | P2 | 深色用户刷新 console 会浅色闪烁 | 同步设置 `color-scheme`，在 `enable()` 前减少闪烁 | `ui/src/composables/useDarkMode.ts`、`ui/src/darkreader-engine.ts` |
+| P2-2 | P2 | 本地项目文档仍描述旧的手工 CSS / Monaco 架构 | 同步 AGENTS.md、CLAUDE.md、scripts/README.md 到纯 Dark Reader 现状 | `AGENTS.md`、`CLAUDE.md`、`scripts/README.md` |
+| P2-3 | P2 | `scripts/` 与 `workplace/` 脚本双份 | 删除重复脚本；专用分析脚本保留在 `workplace/` 或迁移，待确认 | `workplace/login_wait.py`、`workplace/scan_dark.py` 等 |
+| P2-4 | P2 | 前端无单元测试 | 为 `useDarkMode` 补测试，覆盖 light/dark/auto、持久化与非法回退 | `ui/src/composables/__tests__/useDarkMode.spec.ts` |
+| P2-5 | P2 | 多标签页主题不同步 | 监听 `storage` 事件同步主题 | `ui/src/composables/useDarkMode.ts` |
+| P2-6 | P2 | 切换器/设置选项不可键盘操作 | 改为原生 `button` + ARIA，或原生 radio 语义 | `ui/src/components/ThemeToggle.vue`、`ui/src/views/SettingsView.vue` |
+| P3-1 | P3 | 后端使用 `System.out.println` | 使用 Lombok `@Slf4j` 输出日志 | `src/main/java/run/halo/darkmode/DarkModePlugin.java` |
+| P3-2 | P3 | vendored package.json 保留完整 devDependencies | 裁剪为最小字段，只保留构建所需元数据 | `third-party/darkreader/package.json` |
+| P3-3 | P3 | 无 Dark Reader 升级/完整性机制 | 增加 `SHA256SUMS` 并写入 README 校验说明 | `third-party/darkreader/SHA256SUMS`、`README.md`、`.gitignore` |
+| P3-4 | P3 | `data-halo-theme` 属性为历史遗留 | 保留属性，但在代码注释中说明兼容性遗留 | `ui/src/composables/useDarkMode.ts`、`ui/src/styles/variables.css` |
+| P3-6 | P3 | `plugin.yaml` 的 `spec.enabled: true` | 建议改为 `false`，安装后由用户启用 | `src/main/resources/plugin.yaml` |
+
+## 二、详细修复说明
+
+### P2-1 FOUC 闪烁
+
+- 在 `useDarkMode.ts` 的 `applyHtmlAttribute()` 中同步设置：
+  `document.documentElement.style.colorScheme = isDark ? 'dark' : 'light'`
+- `darkreader-engine.ts` 保持现有 `enable()/disable()` 逻辑。
+- `color-scheme` 只能缓解浏览器控件/滚动条闪烁，无法完全消除 DR 异步注入间隙；
+  该限制会写进注释和 README。
+
+### P2-2 本地项目文档
+
+- `AGENTS.md` / `CLAUDE.md`：
+  - 删除 `overrides/`、`halo-core.css`、Monaco 同步、FOUC 同步脚本等旧描述
+  - 统一为“纯 Dark Reader 策略”
+- `scripts/README.md`：
+  - 把“Monaco 日志查看器主题同步”改为检查 `data-darkreader-mode`
+  - 补充 `verify-toggle.py` 的新三向断言说明
+
+### P2-3 脚本收口
+
+- 明确 `scripts/` 为正式工具目录。
+- 计划删除的重复文件（需审批）：
+  - `workplace/login_wait.py`（重复 `scripts/login-wait.py`）
+  - `workplace/scan_dark.py`（重复 `scripts/scan-dark.py`）
+- `workplace/fetch_bundle.py`、`probe_conflict.py`、`aggregate.py` 属于专用分析工具，
+  默认保留在 `workplace/`；如需一并迁移到 `scripts/`，请在审批时注明。
+
+### P2-4 单元测试
+
+新增 `ui/src/composables/__tests__/useDarkMode.spec.ts`，覆盖：
+
+1. 默认 `auto` + 系统深色 → `isDark = true`
+2. `auto` 下点击切换 → 变成显式深色/浅色
+3. `dark ↔ light` 往返切换
+4. `setTheme()` 持久化到 localStorage
+5. localStorage 非法值回退到 `auto`
+6. `storage` 事件跨标签页同步
+
+同时移除 `pnpm test:unit` 的 `--passWithNoTests`，防止测试静默通过。
+
+### P2-5 多标签页同步
+
+- `useDarkMode.ts` 增加：
+  `window.addEventListener('storage', handler)`
+- 仅当 `newValue` 是合法 `light/dark/auto` 时更新 `theme`。
+
+### P2-6 可访问性
+
+- `ThemeToggle.vue`：
+  - `div` 改为 `<button type="button">`
+  - 增加 `:aria-pressed="isDark"`
+  - 保留现有样式并补按钮 reset
+- `SettingsView.vue`：
+  - 选项容器加 `role="radiogroup"`
+  - 每个选项改为 `<button type="button" role="radio" :aria-checked="...">`
+  - 键盘 Tab / Enter / Space 原生可用
+
+### P3-1 后端日志
+
+- `DarkModePlugin.java` 增加 `@Slf4j`
+- `System.out.println` 改为 `log.info(...)`
+- 保留 start/stop 语义不变
+
+### P3-2 vendored package.json
+
+- 裁剪为：
+  `name / version / description / main / module / types / license`
+- 删除 scripts、devDependencies、optionalDependencies 等构建无关字段
+- 更新后执行 `pnpm install` 同步 lockfile
+
+### P3-3 完整性校验
+
+- 新增 `third-party/darkreader/SHA256SUMS`，记录：
+  `darkreader.js`、`darkreader.mjs`、`package.json`、`index.d.ts`、`LICENSE`
+- `.gitignore` 白名单增加 `SHA256SUMS`
+- README 增加“升级 Dark Reader 后校验 SHA256SUMS”说明
+
+### P3-4 历史遗留属性
+
+- 保留 `data-halo-theme`（verify-toggle.py 仍使用）
+- 在 `useDarkMode.ts` 与 `variables.css` 增加注释：
+  该属性当前无 CSS 消费方，仅为兼容性遗留标记
+
+### P3-6 plugin.yaml
+
+- 建议将 `spec.enabled` 改为 `false`
+- 理由：官方 manifest 文档建议生产环境由用户安装后手动启用
+
+## 三、暂缓项（本计划不做）
+
+- P3-5 i18n：目标用户为中文，暂不引入国际化
+- Dark Reader 完整源码保留在本地但不入库：维持现状
+- 不新增界面截图：README 已可用，后续上架前再补
+
+## 四、回归验证
+
+```bash
+cd ui
+pnpm install
+pnpm type-check
+pnpm lint
+pnpm test:unit
+pnpm build
+
+cd ..
+./gradlew test
+./gradlew build
+```
+
+运行时验证：
+
+```bash
+D:\settings\settings\uv\my_uv_env\Scripts\python.exe scripts\verify-toggle.py
+```
+
+验收标准：
+
+- 单测至少覆盖 P2-4 中列出的 6 个场景且全部通过
+- `pnpm test:unit` 不再 `--passWithNoTests`
+- 深色刷新时 `color-scheme` 已同步
+- 键盘可操作侧边栏按钮与设置选项
+- `SHA256SUMS` 可校验，README 有说明
+- 后端日志不再输出到 stdout
+
+## 五、版本与提交
+
+- 修复内容涉及运行时代码，后续打 JAR 时按项目约定递增版本（1.0.4 → 1.0.5）
+- 本次审批通过后，先提交代码修复，再按需打包

docs/review-2026-08-08.md

@@ -0,0 +1,81 @@
+# 代码审查交接单 — 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 断言与策略一致 ✅