From 393c472b2d8778ede78b5c959e82a694c901272c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=88=98=E8=88=AA=E5=AE=87?= <3364451258@qq.com>
Date: Thu, 6 Aug 2026 21:10:04 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README.md=20?=
 =?UTF-8?q?=E5=92=8C=E6=96=B0=E5=A2=9E=20CLAUDE.md?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- README: 补充功能列表、前端命令、更新项目结构
- CLAUDE.md: 添加项目架构、构建命令、设计决策文档

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CLAUDE.md | 107 ++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  67 ++++++++++++++++++++++++++++++----
 2 files changed, 166 insertions(+), 8 deletions(-)
 create mode 100644 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..7cefff5
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,107 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## 项目概述
+
+Halo 暗色模式插件 — 为 Halo 2.25 后台管理面板提供深色/浅色模式切换。不修改 Halo 核心代码，完全通过插件机制实现。
+
+**核心技术栈**：Java 21（后端插件骨架）、Vue 3 + TypeScript（前端 UI）、OKLCH 色彩空间（CSS 变量体系）、Gradle（构建）
+
+## 常用命令
+
+```bash
+# 后端 — 启用插件并启动 Halo 开发服务器
+./gradlew haloServer
+
+# 后端 — 构建插件 JAR（产物在 build/libs/）
+./gradlew build
+
+# 前端 — 进入 ui/ 开发
+cd ui && pnpm install
+
+# 前端 — 开发模式（watch 构建）
+pnpm dev
+
+# 前端 — 生产构建
+pnpm build
+
+# 前端 — 类型检查
+pnpm type-check
+
+# 前端 — Lint（oxlint + eslint）
+pnpm lint
+
+# 前端 — 格式化
+pnpm prettier
+
+# 前端 — 单元测试
+pnpm test:unit
+
+# 后端 — 仅运行 Java 测试
+./gradlew test
+```
+
+## 架构概览
+
+```
+halo-dark-mode-plugin/
+├── 后端 (Java/Gradle)              ← 插件骨架，极简
+│   ├── DarkModePlugin.java         ← 继承 BasePlugin，仅 start()/stop()
+│   └── plugin.yaml                 ← 插件清单（声明式元数据 + 版本约束）
+│
+├── 前端 (Vue 3 / TypeScript)       ← 核心实现
+│   ├── index.ts                    ← definePlugin() 入口，注册路由+组件
+│   ├── composables/
+│   │   ├── useDarkMode.ts          ← 单例状态管理（light/dark/auto + localStorage 持久化）
+│   │   └── useSystemPreference.ts  ← matchMedia 系统偏好监听
+│   ├── components/
+│   │   └── ThemeToggle.vue         ← 侧边栏切换按钮
+│   ├── views/
+│   │   └── SettingsView.vue        ← 设置页面（浅色/深色/跟随系统 三选一）
+│   └── styles/
+│       ├── variables.css           ← 40+ CSS 变量（:root 浅色 + [data-halo-theme="dark"] 深色）
+│       └── overrides/              ← 按区域分层覆盖（layout/components/forms/editor/scrollbar/utilities）
+│
+└── 构建链
+    └── processUiResources          ← Gradle task: ui/dist/ → resources/main/ui/
+```
+
+## 关键设计决策
+
+### 主题切换机制
+
+- **触发方式**：`document.documentElement` 上设置/移除 `data-halo-theme="dark"` 属性
+- **CSS 变量体系**：所有颜色通过 `--halo-*` 前缀的 CSS 自定义属性控制，一个语义变量对应一个视觉属性
+- **颜色空间**：全部使用 OKLCH（感知均匀，暗色模式天然适配，Chrome 111+/Firefox 113+/Safari 15.4+）
+- **暗色配色策略**：用亮度层次区分背景（越"高"的层越亮），中性色含微量蓝色调，强调色略降饱和
+
+### 状态管理
+
+- `useDarkMode()` 是**模块级单例** — 所有组件共享同一份 `theme` ref 和 `isDark` computed
+- 三个主题模式：`light` / `dark` / `auto`（跟随系统）
+- 持久化：`localStorage` key `halo-dark-mode-theme`，默认 `auto`
+- FOUC 防护：插件 bundle 顶部同步执行脚本，DOM 渲染前设置 `data-halo-theme`
+
+### 前端入口
+
+- `definePlugin()` 从 `@halo-dev/ui-shared` 导入（非 `@halo-dev/console-shared`，那是旧版 plugin-starter 的源）
+- 路由使用 `() => import(...)` 懒加载
+- 构建使用 `@halo-dev/ui-plugin-bundler-kit` 的 `viteConfig()` 包装器
+
+### 覆盖策略
+
+三级渐进覆盖：
+1. **CSS 变量注入**（~80% 场景）— 通过 `--halo-*` 变量重定义 Tailwind 颜色语义
+2. **选择器覆盖**（~17% 场景）— `[data-halo-theme="dark"]` 前缀高特异性选择器
+3. **组件穿透**（~3% 场景）— FormKit/编辑器等第三方组件的自有 CSS 变量接口
+
+### 后端
+
+后端极简 — `DarkModePlugin extends BasePlugin` 仅含 `start()`/`stop()` 生命周期钩子。所有核心逻辑在前端。插件不依赖后端 Setting API。
+
+## 项目文档
+
+- `设计文档.md` — 完整的技术设计（架构图、CSS 变量清单、调色板、组件覆盖策略、实现阶段划分、测试策略）
+- `调查文档.md` — 技术调查（create-halo-plugin vs plugin-starter 差异、dev-skills、Halo 插件机制）
+- `README.md` — 用户向 README
diff --git a/README.md b/README.md
index e09d5ed..7bec697 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,17 @@
 # dark-mode
 
-dark-mode - Halo 插件
+Halo 2.25 暗色模式插件 — 为 Halo 后台管理面板提供深色/浅色模式切换，支持跟随系统、手动切换和偏好记忆。
 
-## 简介
+## 功能
 
-这是一个基于 Halo 的插件项目。
+- ☀️/🌙 **三种模式**：浅色、深色、跟随系统
+- 💾 **偏好持久化**：自动记忆用户选择（localStorage），刷新不丢失
+- 🖥️ **系统偏好跟随**：切换系统外观时自动响应
+- ⚡ **瞬间切换**：CSS 变量瞬时生效，无可见闪烁
+- 🧩 **侧边栏注入**：切换按钮自动出现在侧边栏底部（UserProfileBanner 上方）
+- ⚙️ **设置页面**：提供详细的模式选择界面（菜单 → 偏好设置 → 深色模式）
+- 🎨 **OKLCH 色彩空间**：感知均匀，暗色模式天然适配，WCAG AA 对比度保证
+- 📦 **零后端依赖**：纯前端实现，不需要后端 API
 
 ## 开发环境
 
@@ -12,12 +19,13 @@ dark-mode - Halo 插件
 - Node.js 18+
 - pnpm
 
-## 开发
+## 快速开始
 
 ```bash
-# 启用插件
+# 启用插件并启动 Halo 开发服务器
 ./gradlew haloServer
-# 开发前端
+
+# 前端开发（watch 模式）
 cd ui
 pnpm install
 pnpm dev
@@ -26,11 +34,54 @@ pnpm dev
 ## 构建
 
 ```bash
+# 完整构建（后端 + 前端）
 ./gradlew build
 ```
 
-构建完成后，可以在 `build/libs` 目录找到插件 jar 文件。
+构建完成后，插件 JAR 文件位于 `build/libs/`，可直接在 Halo 后台安装。
+
+## 前端命令
+
+```bash
+cd ui
+
+pnpm dev           # 开发构建（watch）
+pnpm build         # 生产构建
+pnpm type-check    # TypeScript 类型检查
+pnpm lint          # Lint（oxlint + eslint）
+pnpm prettier      # 代码格式化
+pnpm test:unit     # 单元测试
+```
+
+## 项目结构
+
+```
+├── build.gradle              # 根构建（BOM 2.25.0, DevTools 0.8.0）
+├── settings.gradle           # 包含 :ui 子项目
+├── src/
+│   └── main/
+│       ├── java/run/halo/darkmode/
+│       │   └── DarkModePlugin.java    # 插件主类（极简骨架）
+│       └── resources/
+│           └── plugin.yaml            # 插件清单
+│
+└── ui/
+    └── src/
+        ├── index.ts                   # definePlugin 入口
+        ├── injector.ts                # ThemeToggle 侧边栏注入器
+        ├── composables/
+        │   ├── useDarkMode.ts         # 核心状态管理（模块级单例）
+        │   └── useSystemPreference.ts # 系统偏好监听
+        ├── components/
+        │   └── ThemeToggle.vue        # 侧边栏切换按钮
+        ├── views/
+        │   └── SettingsView.vue       # 设置页面
+        └── styles/
+            ├── index.css              # 样式入口
+            ├── variables.css          # 40+ CSS 变量（浅色 + 深色）
+            └── overrides/             # 组件覆盖样式
+```
 
 ## 许可证
 
-[GPL-3.0](./LICENSE) © LHY 
\ No newline at end of file
+[GPL-3.0](./LICENSE) © LHY