151 lines
6.2 KiB
Markdown
151 lines
6.2 KiB
Markdown
# 修复计划 — 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）
|
||
- 本次审批通过后，先提交代码修复，再按需打包 |