halo-dark-mode-plugin/docs/fix-plan-2026-08-08.md

修复计划 — 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 已可用，后续上架前再补

四、回归验证

cd ui
pnpm install
pnpm type-check
pnpm lint
pnpm test:unit
pnpm build

cd ..
./gradlew test
./gradlew build

运行时验证：

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）
• 本次审批通过后，先提交代码修复，再按需打包