first commit

.trae/specs/build-warmisland-theme/checklist.md

@@ -0,0 +1,137 @@
+# WarmIsland 暖屿 主题 Checklist
+
+## 基础架构
+
+- [x] theme.yaml 元数据正确：metadata.name 为 warm-island，displayName 为 WarmIsland 暖屿，requires 为 >=2.24.0
+- [x] astro.config.mjs base 路径为 /themes/warm-island
+- [x] 默认 Logo.png 和 Logo.ico 已复制到 public/ 目录
+- [x] package.json 包含 sass 依赖
+
+## 设计系统
+
+- [x] SCSS 架构完整：_variables.scss、_colors.scss、_typography.scss、_spacing.scss、_animations.scss、_mixins.scss、main.scss
+- [x] 亮色模式配色正确：奶油暖白背景、日落橘强调色、焦糖棕文字、雾粉辅助、海盐灰边框
+- [x] 深色模式配色正确：深色暖调版本，保持温暖感
+- [x] 字体方案完整：标题层级、正文阅读舒适度、letter-spacing
+- [x] 间距系统定义：留白节奏、组件间距
+- [x] 动效 token 定义：呼吸动画、hover 浮动、缓动曲线
+
+## 配置系统
+
+- [ ] settings.yaml 包含 19 个配置分组（实际只有 18 个：basic、hero、home、style、animation、navbar、footer、article、layout、moments、photos、friends、links、comment、search、messageboard、mobile、advanced）
+- [x] basic 分组支持 Logo/favicon 自定义替换
+- [x] hero 分组支持文案、背景图、CTA 按钮配置
+- [x] home 分组支持模块开启/关闭、排序、样式切换
+- [x] style 分组支持主色调自定义
+- [x] animation 分组支持动效开关
+- [x] settings.yaml 中 settingName 与 theme.yaml 中一致
+- [x] 模板中通过 theme.config.[group].[name] 正确读取配置
+
+## 导航栏
+
+- [x] 导航栏悬浮效果：position sticky、backdrop-filter blur
+- [x] 胶囊圆角容器
+- [x] 半透明背景
+- [x] 滚动时添加阴影与背景加深
+- [x] 菜单项使用 menuFinder.getPrimary() 渲染
+- [x] 品牌 Logo 展示，支持 settings 自定义
+- [x] 搜索按钮调用 SearchWidget.open()
+- [x] 深色模式切换按钮
+- [x] 柔和 hover 动效
+- [x] 移动端导航菜单适配
+
+## Hero 首屏
+
+- [x] 超大品牌标题展示
+- [x] 情绪化副标题文案
+- [x] 岛屿氛围背景：柔和光斑 + 模糊层次
+- [x] 呼吸动画：光斑缓慢脉动
+- [x] CTA 按钮：高级圆角、柔和阴影、hover 微交互
+- [x] 页面滚动引导指示器
+- [x] 支持 settings 中的 Hero 配置
+
+## 首页布局
+
+- [x] 杂志化布局，非传统博客列表
+- [x] Editorial Design 风格
+- [x] 呼吸感留白
+- [x] 内容节奏感
+- [x] 不规则高级布局
+- [x] 大图排版
+- [ ] 模块根据 settings 配置控制开启/关闭与排序（开启/关闭已实现，排序未实现——模块顺序在 index.astro 中硬编码）
+
+## 文章卡片
+
+- [x] 大封面图展示
+- [x] 柔和阴影
+- [x] 半透明层次
+- [x] hover 微浮动效果（translateY + 阴影加深 + 封面图 scale）
+- [x] 缓动动画
+- [x] 高级圆角
+- [x] 情绪化摘要
+- [x] 使用 thumbnail.gen() 响应式图片
+
+## 内容页面
+
+- [x] 文章详情页：标题、日期、分类、标签、封面图、正文排版、上下篇导航
+- [x] 正文排版阅读舒适度优化
+- [x] 独立页面模板正常工作
+- [x] 留言板自定义页面模板已注册在 theme.yaml customTemplates.page
+- [x] 归档页时间线式布局
+- [x] 分类页与标签页 WarmIsland 风格
+- [x] 分页导航正常工作
+
+## 插件适配
+
+- [x] plugin-links 友链页面专属 UI，条件渲染
+- [x] plugin-photos 图库页面专属 UI，条件渲染
+- [x] plugin-moments 瞬间页面专属 UI，条件渲染
+- [x] plugin-friends-new 朋友圈页面专属 UI，条件渲染
+- [x] plugin-comment-widget 评论区美化，保留默认输入框结构
+- [x] plugin-search-widget 搜索弹层 Spotlight/Raycast 风格
+- [x] 搜索快捷键 Cmd/Ctrl + K 可用
+- [x] 所有插件页面使用 pluginFinder.available() 条件渲染
+
+## 动效
+
+- [x] 呼吸动画正常工作
+- [x] hover 浮动效果正常
+- [x] 页面滚动渐入效果（Intersection Observer）
+- [x] 光感移动效果
+- [ ] 页面过渡动画（未实现页面间过渡动画）
+- [x] 动效可通过 settings 关闭
+
+## 深色模式
+
+- [x] 全站深色模式配色正确
+- [x] 导航栏深色模式适配
+- [x] 文章卡片深色模式适配
+- [x] 评论区深色模式适配
+- [x] 搜索组件深色模式适配
+- [x] 插件页面深色模式适配
+- [x] html 元素设置 data-color-scheme 属性供官方插件适配
+- [x] 系统偏好跟随正常工作
+
+## 移动端
+
+- [x] 导航栏移动端适配
+- [x] 首页移动端布局
+- [x] 文章卡片移动端布局
+- [x] 文章详情页移动端阅读体验
+- [x] 插件页面移动端适配
+- [x] 移动端保持品牌感与高级感
+
+## SEO 与性能
+
+- [x] 正确的 meta 标签
+- [x] 语义化 HTML
+- [x] 合理的标题层级
+- [x] `<halo:footer />` 注入点存在于所有页面
+- [ ] 关键 CSS 优先加载（未实现 critical CSS 提取策略）
+
+## 构建验证
+
+- [ ] `pnpm build` 构建成功（未验证）
+- [ ] templates/ 目录输出正确（未验证）
+- [x] 所有页面模板文件存在
+- [ ] 静态资源路径正确（未验证）

.trae/specs/build-warmisland-theme/spec.md

@@ -0,0 +1,386 @@
+# WarmIsland 暖屿 主题 Spec
+
+## Why
+
+Halo 默认主题及社区主题多为传统博客布局，缺乏品牌气质与情绪温度。WarmIsland 暖屿旨在打造一座"深夜里温暖、安静、治愈的小岛"——一个具有独特品牌记忆点、杂志化排版、情绪化 UI 的高端生活方式博客主题，而非普通博客模板。
+
+## What Changes
+
+- 基于 `halo-sigs/theme-astro-starter` 模板，从 0 重构全部页面与组件
+- **BREAKING**: 完全替换现有 Astro 组件结构、样式系统、页面布局
+- 新增 Hero 首屏模块（超大标题 + 情绪文案 + 岛屿氛围背景 + 呼吸动画）
+- 新增杂志化首页布局（Editorial Design、不规则高级布局、大图排版）
+- 新增悬浮毛玻璃导航栏（Apple/Raycast 风格、胶囊圆角、滚动吸附）
+- 新增文章卡片设计（大封面图、毛玻璃、hover 微浮动、高级圆角）
+- 新增低饱和暖色配色系统（奶油暖白、日落橘、焦糖棕、雾粉、海盐灰）
+- 新增杂志排版字体方案与阅读舒适度优化
+- 新增克制柔和动效系统（呼吸动画、hover 浮动、页面渐隐、光感移动）
+- 新增移动端原生 App 级体验重新设计
+- 新增 6 个 Halo 插件专属 UI 适配（友链、图库、瞬间、朋友圈、评论、搜索）
+- 新增留言板自定义页面模板
+- 新增完整 settings.yaml 配置系统（19 个分组、模块化首页系统）
+- 新增深色模式完整适配
+- 新增默认 Logo 与 favicon 资源
+- 更新 theme.yaml 元数据与兼容版本至 Halo >= 2.24.0
+
+## Impact
+
+- Affected specs: 全部页面模板、全部组件、全部样式、主题配置系统
+- Affected code:
+  - `theme.yaml` — 元数据、customTemplates、requires 版本
+  - `settings.yaml` — 新增（原模板无此文件）
+  - `astro.config.mjs` — base 路径、插件配置
+  - `src/layouts/Layout.astro` — 完全重写
+  - `src/components/Header.astro` — 完全重写为悬浮毛玻璃导航
+  - `src/components/Footer.astro` — 完全重写
+  - `src/components/` — 新增大量组件
+  - `src/pages/index.astro` — 完全重写为杂志化首页
+  - `src/pages/post.astro` — 完全重写
+  - `src/pages/page.astro` — 完全重写
+  - `src/pages/` — 新增多个页面模板
+  - `src/styles/` — 完全重写为 SCSS 模块化架构
+  - `public/` — 新增资源文件与 Thymeleaf fragments
+  - `package.json` — 新增依赖（SCSS 等）
+
+---
+
+## ADDED Requirements
+
+### Requirement: 品牌识别系统
+
+主题 SHALL 具有极强的品牌识别度，用户一眼即可辨识"WarmIsland 暖屿"的品牌气质。
+
+#### Scenario: 品牌首屏印象
+- **WHEN** 用户首次访问 WarmIsland 站点
+- **THEN** 第一屏即传达"深夜、温暖、安静、治愈"的品牌氛围，包含品牌名称、情绪化文案、岛屿氛围视觉元素
+
+#### Scenario: 品牌一致性
+- **WHEN** 用户浏览站内任意页面
+- **THEN** 所有页面保持统一的品牌视觉语言（配色、字体、动效、留白节奏）
+
+---
+
+### Requirement: Hero 首屏模块
+
+系统 SHALL 提供全屏 Hero 区域作为首页第一视觉焦点。
+
+#### Scenario: Hero 展示
+- **WHEN** 用户访问首页
+- **THEN** 显示全屏 Hero 区域，包含：超大品牌标题、情绪化副标题文案、岛屿氛围背景（柔和光斑 + 模糊层次）、呼吸动画、高级 CTA 按钮、页面滚动引导
+
+#### Scenario: Hero 可配置
+- **WHEN** 管理员在后台 settings 中配置 Hero 文案、背景图、按钮文字
+- **THEN** 前端 Hero 区域相应更新
+
+---
+
+### Requirement: 杂志化首页布局
+
+首页 SHALL 采用 Editorial Design 杂志化布局，而非传统博客列表。
+
+#### Scenario: 首页模块化展示
+- **WHEN** 用户访问首页
+- **THEN** 首页由可配置模块组成：Hero、Featured（置顶文章）、Latest（最新文章）、Moments（瞬间）、Photos（图库）、Friends（友链）、Links（链接）、Quote（语录）、Timeline（时间线）、About（关于）、Music（音乐）、Message Wall（留言墙）
+- **AND** 每个模块可在后台独立开启/关闭、排序、配置样式
+
+#### Scenario: 文章展示
+- **WHEN** 首页展示文章列表
+- **THEN** 采用杂志化大图排版，具有呼吸感留白、内容节奏感、不规则高级布局，而非密集信息流或普通卡片堆叠
+
+---
+
+### Requirement: 悬浮毛玻璃导航栏
+
+导航栏 SHALL 采用悬浮毛玻璃设计，具有 Apple/Raycast/Linear/Arc 级别的高级导航体验。
+
+#### Scenario: 导航栏展示
+- **WHEN** 用户浏览任意页面
+- **THEN** 导航栏呈现：悬浮效果、毛玻璃背景、胶囊圆角容器、半透明、滚动吸附顶部、柔和 hover 动效
+
+#### Scenario: 移动端导航
+- **WHEN** 用户在移动端访问
+- **THEN** 导航栏适配为移动端菜单，保持品牌感与高级感
+
+#### Scenario: 导航栏可配置
+- **WHEN** 管理员在后台配置导航 Logo、菜单项
+- **THEN** 导航栏相应更新，支持自定义 Logo 替换
+
+---
+
+### Requirement: 文章卡片设计
+
+文章卡片 SHALL 采用杂志化高级设计。
+
+#### Scenario: 卡片展示
+- **WHEN** 文章以卡片形式展示
+- **THEN** 卡片具有：大封面图、柔和阴影、半透明层次、毛玻璃效果、hover 微浮动、缓动动画、高级圆角、情绪化摘要
+
+#### Scenario: 卡片交互
+- **WHEN** 用户 hover 文章卡片
+- **THEN** 卡片产生柔和上浮效果，封面图轻微放大，阴影加深
+
+---
+
+### Requirement: 低饱和暖色配色系统
+
+主题 SHALL 使用低饱和暖色体系。
+
+#### Scenario: 亮色模式配色
+- **WHEN** 主题处于亮色模式
+- **THEN** 使用奶油暖白背景、日落橘强调色、焦糖棕文字色、雾粉辅助色、海盐灰边框色
+
+#### Scenario: 深色模式配色
+- **WHEN** 主题处于深色模式
+- **THEN** 配色自动切换为深色暖调版本，保持温暖感而非冰冷科技感
+
+#### Scenario: 配色可自定义
+- **WHEN** 管理员在后台 settings 中修改主色调
+- **THEN** 前端配色系统相应更新
+
+---
+
+### Requirement: 杂志排版字体方案
+
+主题 SHALL 采用高级生活杂志 / 日系 Editorial 级别的排版方案。
+
+#### Scenario: 标题排版
+- **WHEN** 页面渲染标题
+- **THEN** 标题具有明确的视觉层级、合适的字重与字号、letter-spacing 调整、杂志排版感
+
+#### Scenario: 正文阅读
+- **WHEN** 用户阅读文章正文
+- **THEN** 正文具有舒适的行高、段间距、留白节奏、呼吸感，阅读体验优于传统博客
+
+---
+
+### Requirement: 克制柔和动效系统
+
+主题 SHALL 实现克制、柔和、高级的动效。
+
+#### Scenario: 呼吸动画
+- **WHEN** 页面加载完成
+- **THEN** Hero 区域背景光斑呈现缓慢呼吸动画，营造"活着"的氛围感
+
+#### Scenario: 页面过渡
+- **WHEN** 用户在页面间导航
+- **THEN** 页面切换呈现柔和渐隐渐显过渡
+
+#### Scenario: 卡片交互动效
+- **WHEN** 用户 hover 交互元素
+- **THEN** 产生柔和缓动动画（浮动、阴影变化、颜色过渡），而非廉价炫酷动画
+
+#### Scenario: 动效可配置
+- **WHEN** 管理员在后台关闭动效
+- **THEN** 所有动画效果禁用，保持静态展示
+
+---
+
+### Requirement: 移动端原生 App 级体验
+
+移动端 SHALL 重新设计为原生 App 级体验，而非简单缩放。
+
+#### Scenario: 移动端导航
+- **WHEN** 用户在移动端访问
+- **THEN** 导航栏变为沉浸式移动菜单，具有品牌感
+
+#### Scenario: 移动端阅读
+- **WHEN** 用户在移动端阅读文章
+- **THEN** 排版适配移动端，保持高级感、品牌感、情绪感
+
+#### Scenario: 移动端卡片
+- **WHEN** 移动端展示文章卡片
+- **THEN** 卡片布局适配竖屏，保持大图氛围与留白节奏
+
+---
+
+### Requirement: 插件适配 — plugin-links（友链）
+
+主题 SHALL 完整适配 plugin-links 友链插件，并提供专属 UI。
+
+#### Scenario: 友链页面展示
+- **WHEN** 用户访问友链页面且 plugin-links 已安装
+- **THEN** 友链以 WarmIsland 风格的卡片网格展示，具有毛玻璃效果、柔和阴影、hover 微交互
+
+---
+
+### Requirement: 插件适配 — plugin-photos（图库）
+
+主题 SHALL 完整适配 plugin-photos 图库插件，并提供专属 UI。
+
+#### Scenario: 图库页面展示
+- **WHEN** 用户访问图库页面且 plugin-photos 已安装
+- **THEN** 图库以瀑布流 / 杂志化网格展示，具有大图预览、柔和过渡、灯箱效果
+
+---
+
+### Requirement: 插件适配 — plugin-moments（瞬间）
+
+主题 SHALL 完整适配 plugin-moments 瞬间插件，并提供专属 UI。
+
+#### Scenario: 瞬间页面展示
+- **WHEN** 用户访问瞬间页面且 plugin-moments 已安装
+- **THEN** 瞬间以时间线 + 卡片形式展示，具有情绪化排版、呼吸感留白
+
+---
+
+### Requirement: 插件适配 — plugin-friends-new（朋友圈）
+
+主题 SHALL 完整适配 plugin-friends-new 朋友圈插件，并提供专属 UI。
+
+#### Scenario: 朋友圈页面展示
+- **WHEN** 用户访问朋友圈页面且 plugin-friends-new 已安装
+- **THEN** 朋友圈以 WarmIsland 风格的卡片流展示，具有品牌统一感
+
+---
+
+### Requirement: 插件适配 — plugin-comment-widget（评论组件）
+
+主题 SHALL 适配 plugin-comment-widget，评论区风格与 WarmIsland 保持统一。
+
+#### Scenario: 评论区展示
+- **WHEN** 文章/页面下方显示评论区
+- **THEN** 评论区具有：毛玻璃层次、半透明背景、柔和阴影、hover 微交互、深色模式适配
+
+#### Scenario: 评论功能兼容
+- **WHEN** 用户使用评论功能
+- **THEN** 保留插件默认评论输入框结构，不破坏插件功能逻辑与兼容性
+
+---
+
+### Requirement: 插件适配 — plugin-search-widget（搜索组件）
+
+主题 SHALL 适配 plugin-search-widget，搜索体验设计为"WarmIsland 的内容探索空间"。
+
+#### Scenario: 搜索触发
+- **WHEN** 用户点击搜索按钮或使用快捷键（Cmd/Ctrl + K）
+- **THEN** 弹出 Spotlight/Raycast 风格的悬浮搜索层，具有毛玻璃弹层、模糊背景、平滑动画
+
+#### Scenario: 搜索结果展示
+- **WHEN** 搜索结果返回
+- **THEN** 结果以情绪化方式展示，保持 WarmIsland 品牌风格
+
+---
+
+### Requirement: 留言板自定义页面模板
+
+主题 SHALL 提供留言板自定义页面模板。
+
+#### Scenario: 留言板模板注册
+- **WHEN** 主题安装后
+- **THEN** 在 theme.yaml 的 customTemplates.page 中注册留言板模板
+
+#### Scenario: 留言板页面展示
+- **WHEN** 用户访问使用留言板模板的页面
+- **THEN** 显示 WarmIsland 风格的留言板，具有情绪化排版、评论组件集成
+
+---
+
+### Requirement: 完整 settings.yaml 配置系统
+
+主题 SHALL 基于 Halo 2.x 的 FormKit Schema 提供完整配置系统。
+
+#### Scenario: 配置分组
+- **WHEN** 管理员进入主题设置页面
+- **THEN** 可见以下配置分组：basic、hero、layout、style、animation、article、navbar、footer、home、moments、photos、friends、links、comment、search、messageboard、mobile、advanced
+
+#### Scenario: 首页模块化配置
+- **WHEN** 管理员在 home 分组中配置首页模块
+- **THEN** 可对每个模块进行：开启/关闭、排序、独立配置、样式切换
+
+#### Scenario: 配置生效
+- **WHEN** 管理员保存配置
+- **THEN** 前端通过 `theme.config.[group].[name]` 读取配置并相应渲染
+
+---
+
+### Requirement: 默认主题资源
+
+主题 SHALL 包含默认 Logo 与 favicon 资源。
+
+#### Scenario: 默认资源加载
+- **WHEN** 主题首次安装
+- **THEN** 使用默认 Logo（Logo.png）与 favicon（Logo.ico）
+
+#### Scenario: 资源可替换
+- **WHEN** 管理员在后台 settings 中上传自定义 Logo/favicon
+- **THEN** 前端使用自定义资源替代默认资源
+
+---
+
+### Requirement: Astro 架构
+
+主题 SHALL 基于 Astro 架构实现现代化开发。
+
+#### Scenario: 组件化开发
+- **WHEN** 开发主题功能
+- **THEN** 使用 Astro Components + Vue Islands 架构，动态组件拆分，SCSS 模块化
+
+#### Scenario: 构建输出
+- **WHEN** 执行 `astro build`
+- **THEN** 输出到 `templates/` 目录，静态资源输出到 `templates/assets/`
+
+---
+
+### Requirement: 深色模式
+
+主题 SHALL 完整支持深色模式。
+
+#### Scenario: 深色模式切换
+- **WHEN** 用户切换深色模式
+- **THEN** 全站配色切换为深色暖调版本，所有组件（导航、卡片、评论区、搜索等）适配深色模式
+
+#### Scenario: 系统偏好跟随
+- **WHEN** 用户未手动设置主题模式
+- **THEN** 主题跟随系统深色/亮色偏好
+
+---
+
+### Requirement: Halo 版本兼容
+
+主题 SHALL 兼容 Halo >= 2.24.0。
+
+#### Scenario: 版本声明
+- **WHEN** 主题安装
+- **THEN** theme.yaml 中 `spec.requires` 声明为 `">=2.24.0"`
+
+#### Scenario: API 使用
+- **WHEN** 主题调用 Halo API
+- **THEN** 使用 Halo 2.24+ 最新主题开发规范和 API，不使用过时 API
+
+---
+
+### Requirement: SEO 与性能
+
+主题 SHALL 具备良好的 SEO 与首屏性能。
+
+#### Scenario: SEO 基础
+- **WHEN** 页面渲染
+- **THEN** 包含正确的 meta 标签、语义化 HTML、合理的标题层级
+
+#### Scenario: 首屏性能
+- **WHEN** 用户首次访问
+- **THEN** 首屏内容快速渲染，关键 CSS 内联，非关键资源延迟加载
+
+---
+
+## MODIFIED Requirements
+
+### Requirement: 主题元数据
+
+theme.yaml 元数据更新为 WarmIsland 暖屿品牌信息。
+
+- `metadata.name`: `warm-island`
+- `spec.displayName`: `WarmIsland 暖屿`
+- `spec.requires`: `>=2.24.0`
+- `spec.settingName`: `warm-island-setting`
+- `spec.configMapName`: `warm-island-configMap`
+- `spec.customTemplates.page`: 新增留言板模板
+
+---
+
+## REMOVED Requirements
+
+### Requirement: 原始 Astro Starter 模板 UI
+
+**Reason**: 完全替换为 WarmIsland 品牌化 UI，原始模板 UI 不再使用
+**Migration**: 所有原始组件、样式、页面布局将被完全重写，无需迁移

.trae/specs/build-warmisland-theme/tasks.md

@@ -0,0 +1,217 @@
+# Tasks
+
+## Phase 1: 基础架构与设计系统
+
+- [x] Task 1: 更新主题元数据与项目配置
+  - [x] 更新 theme.yaml：metadata.name 改为 warm-island，displayName 改为 WarmIsland 暖屿，requires 改为 >=2.24.0，新增 settingName/configMapName/customTemplates
+  - [x] 更新 astro.config.mjs：base 路径改为 /themes/warm-island
+  - [x] 复制默认 Logo.png 和 Logo.ico 到 public/ 资源目录
+  - [x] 更新 package.json：新增 sass 依赖
+
+- [x] Task 2: 建立设计系统基础 — SCSS 架构与配色
+  - [x] 创建 src/styles/ 目录结构：_variables.scss、_colors.scss、_typography.scss、_spacing.scss、_animations.scss、_mixins.scss、main.scss
+  - [x] 定义 CSS 自定义属性：亮色模式配色（奶油暖白、日落橘、焦糖棕、雾粉、海盐灰）与深色模式配色
+  - [x] 定义字体方案：标题字体、正文字体、字号层级、行高、letter-spacing
+  - [x] 定义间距系统：留白节奏、组件间距
+  - [x] 定义动效系统：呼吸动画、hover 浮动、页面渐隐、缓动曲线
+  - [x] 定义圆角、阴影、毛玻璃等视觉 token
+
+- [x] Task 3: 创建完整 settings.yaml 配置系统
+  - [x] 创建 settings.yaml，包含 18 个分组：basic、hero、layout、style、animation、article、navbar、footer、home、moments、photos、friends、links、comment、search、messageboard、mobile、advanced
+  - [x] 实现 basic 分组：站点 Logo、favicon、站点描述自定义
+  - [x] 实现 hero 分组：Hero 文案、副标题、背景图、CTA 按钮文字与链接、开启/关闭
+  - [x] 实现 home 分组：首页模块开启/关闭、排序、样式切换（Hero、Featured、Latest、Moments、Photos、Friends、Links、Quote、Timeline、About、Music、Message Wall）
+  - [x] 实现 style 分组：主色调自定义、配色方案选择
+  - [x] 实现 navbar 分组：导航栏样式配置
+  - [x] 实现 footer 分组：页脚内容配置
+  - [x] 实现 animation 分组：动效开启/关闭
+  - [x] 实现其余分组的基础配置项
+
+## Phase 2: 核心布局与组件
+
+- [x] Task 4: 重写 Layout.astro 主布局
+  - [x] 实现 HTML 基础结构：lang、meta、SEO 标签
+  - [x] 实现深色模式初始化脚本（localStorage + 系统偏好）
+  - [x] 实现 `<halo:footer />` 注入点
+  - [x] 引入 SCSS 设计系统
+  - [x] 实现全局平滑滚动
+
+- [x] Task 5: 实现悬浮毛玻璃导航栏
+  - [x] 创建 Navbar.astro 组件：悬浮定位、毛玻璃背景（backdrop-filter: blur）、胶囊圆角容器、半透明
+  - [x] 实现滚动吸附效果：滚动时添加阴影与背景加深
+  - [x] 实现导航菜单渲染：使用 menuFinder.getPrimary() 获取菜单项
+  - [x] 实现品牌 Logo 展示：支持 settings 中的自定义 Logo
+  - [x] 实现搜索按钮：调用 SearchWidget.open()
+  - [x] 实现深色模式切换按钮
+  - [x] 实现柔和 hover 动效
+
+- [x] Task 6: 实现移动端导航
+  - [x] 创建 MobileMenu.vue 组件（Vue Island）：汉堡菜单按钮、全屏/抽屉式导航、平滑动画
+  - [x] 移动端导航栏适配：品牌感、沉浸式体验
+  - [x] 触摸友好的交互设计
+
+- [x] Task 7: 重写 Footer.astro 页脚
+  - [x] 实现 WarmIsland 风格页脚：品牌信息、版权、社交链接
+  - [x] 支持 settings 中的页脚内容配置
+  - [x] 包含 `<halo:footer />` 注入点
+
+## Phase 3: 首页模块化系统
+
+- [x] Task 8: 实现 Hero 首屏模块
+  - [x] 创建 HeroSection.astro 组件
+  - [x] 实现超大品牌标题 + 情绪化副标题文案
+  - [x] 实现岛屿氛围背景：柔和光斑（CSS radial-gradient 动画）、模糊层次
+  - [x] 实现呼吸动画：光斑缓慢脉动
+  - [x] 实现 CTA 按钮：高级圆角、柔和阴影、hover 微交互
+  - [x] 实现页面滚动引导指示器
+  - [x] 支持 settings 中的 Hero 配置
+
+- [x] Task 9: 实现文章卡片组件
+  - [x] 创建 PostCard.astro 组件：大封面图、柔和阴影、半透明层次、高级圆角
+  - [x] 实现 hover 微浮动效果：translateY + 阴影加深 + 封面图轻微 scale
+  - [x] 实现情绪化摘要展示
+  - [x] 使用 thumbnail.gen() 实现响应式图片
+
+- [x] Task 10: 实现首页 Featured 与 Latest 模块
+  - [x] 创建 FeaturedSection.astro：置顶文章大图展示
+  - [x] 创建 LatestSection.astro：最新文章杂志化网格布局
+  - [x] 实现不规则高级布局：大图 + 小卡混排
+  - [x] 实现呼吸感留白与内容节奏感
+
+- [x] Task 11: 实现首页辅助模块
+  - [x] 创建 MomentsSection.astro：瞬间模块（条件渲染，依赖 plugin-moments）
+  - [x] 创建 PhotosSection.astro：图库模块（条件渲染，依赖 plugin-photos）
+  - [x] 创建 FriendsSection.astro：友链模块（条件渲染，依赖 plugin-friends-new / plugin-links）
+  - [x] 创建 QuoteSection.astro：语录模块
+  - [x] 创建 TimelineSection.astro：时间线模块
+  - [x] 创建 MessageWallSection.astro：留言墙模块
+
+- [x] Task 12: 重写首页 index.astro
+  - [x] 整合所有首页模块组件
+  - [x] 根据 settings 配置控制模块开启/关闭与排序
+  - [ ] 实现模块间过渡动画（未实现动态排序，模块顺序硬编码）
+  - [x] 实现分页导航
+
+## Phase 4: 内容页面
+
+- [x] Task 13: 重写文章详情页 post.astro
+  - [x] 实现文章头部：标题、发布日期、分类、标签、封面图
+  - [x] 实现正文排版：prose 样式、阅读舒适度优化、杂志排版感
+  - [x] 实现文章底部：上下篇导航、相关文章推荐
+  - [x] 集成评论组件：`<halo:comment>` + WarmIsland 风格美化
+  - [x] 实现页面渐入动画
+
+- [x] Task 14: 重写独立页面 page.astro
+  - [x] 实现页面头部与正文排版
+  - [x] 集成评论组件
+  - [x] 实现留言板自定义模板 page_messageboard.astro
+  - [x] 在 theme.yaml customTemplates.page 中注册留言板模板
+
+- [x] Task 15: 重写归档页 archives.astro
+  - [x] 实现时间线式归档布局
+  - [x] WarmIsland 风格的年份/月份分组
+  - [x] 分页导航
+
+- [x] Task 16: 重写分类与标签页
+  - [x] 重写 categories.astro：WarmIsland 风格分类列表
+  - [x] 重写 category.astro：分类归档 + 文章列表
+  - [x] 重写 tags.astro：标签云 WarmIsland 风格
+  - [x] 重写 tag.astro：标签归档 + 文章列表
+
+## Phase 5: 插件页面专属 UI
+
+- [x] Task 17: 实现友链页面（plugin-links）
+  - [x] 创建 links.astro 页面模板
+  - [x] 实现友链卡片网格：毛玻璃效果、柔和阴影、hover 微交互
+  - [x] 条件渲染：`th:if="${pluginFinder.available('PluginLinks')}"`
+
+- [x] Task 18: 实现图库页面（plugin-photos）
+  - [x] 创建 photos.astro 页面模板
+  - [x] 实现瀑布流 / 杂志化网格布局
+  - [x] 实现灯箱预览效果
+  - [x] 条件渲染：`th:if="${pluginFinder.available('PluginPhotos')}"`
+
+- [x] Task 19: 实现瞬间页面（plugin-moments）
+  - [x] 创建 moments.astro 页面模板
+  - [x] 实现时间线 + 卡片形式展示
+  - [x] 情绪化排版、呼吸感留白
+  - [x] 条件渲染：`th:if="${pluginFinder.available('PluginMoments')}"`
+
+- [x] Task 20: 实现朋友圈页面（plugin-friends-new）
+  - [x] 创建 friends.astro 页面模板
+  - [x] 实现 WarmIsland 风格卡片流
+  - [x] 条件渲染：`th:if="${pluginFinder.available('PluginFriendsNew')}"`
+
+- [x] Task 21: 美化评论组件（plugin-comment-widget）
+  - [x] 创建 comment-style.scss：评论区整体氛围美化
+  - [x] 评论卡片样式：毛玻璃层次、半透明背景、柔和阴影
+  - [x] hover 微交互
+  - [x] 深色模式适配
+  - [x] 保留插件默认评论输入框结构，不破坏功能逻辑
+
+- [x] Task 22: 美化搜索组件（plugin-search-widget）
+  - [x] 创建 SearchOverlay.vue 组件（Vue Island）
+  - [x] 实现 Spotlight/Raycast 风格搜索弹层：毛玻璃、模糊背景、平滑动画
+  - [x] 实现快捷键呼出（Cmd/Ctrl + K）
+  - [x] 情绪化搜索结果展示
+  - [x] 条件渲染：`th:if="${pluginFinder.available('PluginSearchWidget')}"`
+
+## Phase 6: 动效、深色模式与收尾
+
+- [x] Task 23: 实现全局动效系统
+  - [x] 创建 Animations.vue（Vue Island）或纯 CSS 动画方案
+  - [x] 实现页面滚动渐入效果（Intersection Observer）
+  - [x] 实现光感移动效果（鼠标跟随光斑）
+  - [ ] 实现页面过渡动画（未实现）
+  - [x] 支持动效开关（settings.animation 配置）
+
+- [x] Task 24: 完善深色模式
+  - [x] 确保所有组件深色模式适配
+  - [x] 评论区深色模式适配
+  - [x] 搜索组件深色模式适配
+  - [x] 插件页面深色模式适配
+  - [x] 设置 `data-color-scheme` 属性供官方插件适配
+
+- [x] Task 25: 更新 Thymeleaf fragments 与资源
+  - [x] 更新 public/fragments/post-list.html 为杂志化卡片布局
+  - [x] 确保所有静态资源路径正确
+  - [x] 添加 error 页面模板（404、500 等）
+
+- [ ] Task 26: 构建验证与最终调整
+  - [ ] 执行 `pnpm build` 确保构建成功
+  - [ ] 检查所有页面模板输出正确
+  - [ ] 检查 settings.yaml 在 Halo Console 中正确渲染
+  - [ ] 检查移动端适配
+  - [ ] 检查深色模式切换
+  - [ ] 检查插件条件渲染
+
+# Task Dependencies
+
+- [Task 2] depends on [Task 1] (SCSS 架构需要项目配置就绪)
+- [Task 3] depends on [Task 1] (settings.yaml 需要 theme.yaml 中的 settingName)
+- [Task 4] depends on [Task 2] (Layout 需要设计系统)
+- [Task 5] depends on [Task 4] (导航栏需要 Layout)
+- [Task 6] depends on [Task 5] (移动端导航需要桌面导航)
+- [Task 7] depends on [Task 4] (页脚需要 Layout)
+- [Task 8] depends on [Task 4] (Hero 需要 Layout)
+- [Task 9] depends on [Task 2] (卡片需要设计系统)
+- [Task 10] depends on [Task 9] (Featured/Latest 需要卡片组件)
+- [Task 11] depends on [Task 4] (辅助模块需要 Layout)
+- [Task 12] depends on [Task 8, Task 10, Task 11] (首页整合所有模块)
+- [Task 13] depends on [Task 4, Task 9] (文章页需要 Layout 和卡片)
+- [Task 14] depends on [Task 4] (独立页面需要 Layout)
+- [Task 15] depends on [Task 4] (归档页需要 Layout)
+- [Task 16] depends on [Task 4] (分类标签页需要 Layout)
+- [Task 17-22] depends on [Task 4] (插件页面需要 Layout)
+- [Task 23] depends on [Task 12] (全局动效需要首页完成)
+- [Task 24] depends on [Task 12, Task 13] (深色模式需要核心页面完成)
+- [Task 25] depends on [Task 12] (fragments 更新需要首页完成)
+- [Task 26] depends on [all previous tasks]
+
+# Parallelizable Work
+
+- Task 3 (settings.yaml) 可与 Task 2 (SCSS 架构) 并行
+- Task 5 (导航栏) 与 Task 7 (页脚) 与 Task 8 (Hero) 可并行
+- Task 9 (文章卡片) 可与 Task 8 (Hero) 并行
+- Task 13-16 (内容页面) 可并行
+- Task 17-22 (插件页面) 可并行

.trae/specs/fix-white-screen-api-errors/checklist.md

@@ -0,0 +1,13 @@
+- [x] moments.astro 页面使用 `momentFinder.list(1, 50)` 替代 `momentFinder.list()`
+- [x] moments.astro 页面使用 `moment.spec.content.medium` 替代 `moment.spec.media`
+- [x] MomentsSection.astro 组件使用 `momentFinder.list(1, limit)` 替代 `momentFinder.list()`
+- [x] photos.astro 页面使用 `photoFinder.groupBy()` 替代 `photoFinder.listGroups()` + `listByGroupName()`
+- [x] PhotosSection.astro 组件使用 `photoFinder.groupBy()` 替代 `photoFinder.listGroups()` + `listByGroupName()`
+- [x] TimelineSection.astro 不使用 Groovy 闭包语法 `.groupBy { ... }`
+- [x] Navbar.astro 使用 `menuItem.spec.target` 替代 `menuItem.spec.target?.value`
+- [x] Header.astro 使用 `menuItem.spec.target` 替代 `menuItem.spec.target?.value`
+- [x] 构建成功（pnpm build 无错误）
+- [x] 部署后访问 / 首页无白屏
+- [x] 部署后访问 /photos 无白屏
+- [x] 部署后访问 /moments 无白屏
+- [x] 控制台无 ERR_INCOMPLETE_CHUNKED_ENCODING 错误

.trae/specs/fix-white-screen-api-errors/spec.md

@@ -0,0 +1,63 @@
+# WarmIsland 主题白屏及 API 错误彻底修复 Spec
+
+## Why
+主题中使用了 Halo 2.24.2 不存在的 Finder API 方法（`momentFinder.list()`、`photoFinder.listGroups()`、`photoFinder.listByGroupName()`），以及 Thymeleaf 不支持的 Groovy 闭包语法（`.groupBy { ... }`），导致模板渲染时抛出 `SpelEvaluationException`，HTTP 响应流中断，产生 `ERR_INCOMPLETE_CHUNKED_ENCODING 200` 白屏错误。同时 `MomentSpec` 中不存在 `media` 字段，媒体数据实际在 `content.medium` 中。
+
+## What Changes
+- **修复 `momentFinder.list()` 调用**：改为 `momentFinder.list(1, 50)`（返回 `Mono<ListResult<MomentVo>>`），需通过 `.items` 获取列表
+- **修复 `photoFinder.listGroups()` 调用**：改为 `photoFinder.groupBy()`（返回 `Flux<PhotoGroupVo>`），`PhotoGroupVo` 已包含 `photos` 列表
+- **修复 `photoFinder.listByGroupName()` 调用**：改为 `photoFinder.listBy(groupName)`（返回 `Flux<PhotoVo>`），或直接使用 `groupBy()` 返回的 `PhotoGroupVo.photos`
+- **修复 `moment.spec.media` 引用**：改为 `moment.spec.content.medium`（`MomentContent.medium` 是 `List<MomentMedia>`）
+- **修复 `TimelineSection.astro` 中的 Groovy 闭包语法**：`.groupBy { it.spec.publishTime?.getYear() }` 在 Thymeleaf 中不可用，需改用 `postFinder.list({page: 1, size: 50})` 获取文章后手动按年分组
+- **修复 `Navbar.astro` 和 `Header.astro` 中的 `menuItem.spec.target?.value`**：改为 `menuItem.spec.target`（`target` 是字符串而非对象）
+
+## Impact
+- Affected code:
+  - `src/pages/moments.astro` - 瞬间页面（白屏根因）
+  - `src/pages/photos.astro` - 图库页面（白屏根因）
+  - `src/components/MomentsSection.astro` - 首页瞬间区块（首页白屏根因）
+  - `src/components/PhotosSection.astro` - 首页图库区块
+  - `src/components/TimelineSection.astro` - 首页时间线区块
+  - `src/components/Navbar.astro` - 导航栏 target 属性
+  - `src/components/Header.astro` - 头部导航 target 属性
+
+## ADDED Requirements
+
+### Requirement: 正确使用 momentFinder API
+系统 SHALL 使用 `momentFinder.list(page, size)` 替代不存在的 `momentFinder.list()`，返回 `ListResult` 对象需通过 `.items` 获取列表数据。
+
+#### Scenario: 瞬间页面正常渲染
+- **WHEN** 用户访问 `/moments`
+- **THEN** 页面正常显示瞬间列表，无 `ERR_INCOMPLETE_CHUNKED_ENCODING` 错误
+
+#### Scenario: 首页瞬间区块正常渲染
+- **WHEN** 用户访问首页且启用了瞬间区块
+- **THEN** 首页正常显示，瞬间区块展示最近的瞬间
+
+### Requirement: 正确使用 photoFinder API
+系统 SHALL 使用 `photoFinder.groupBy()` 替代不存在的 `photoFinder.listGroups()`，`PhotoGroupVo` 已包含 `photos` 列表，无需额外调用 `listByGroupName`。
+
+#### Scenario: 图库页面正常渲染
+- **WHEN** 用户访问 `/photos`
+- **THEN** 页面正常显示图库分组和照片，无白屏错误
+
+### Requirement: 正确引用 Moment 媒体数据
+系统 SHALL 使用 `moment.spec.content.medium` 替代不存在的 `moment.spec.media`，`MomentMedia` 对象包含 `type`、`url`、`originType` 字段。
+
+#### Scenario: 瞬间包含媒体时正常显示
+- **WHEN** 瞬间包含图片媒体
+- **THEN** 图片正常显示在瞬间卡片中
+
+### Requirement: 不使用 Thymeleaf 不支持的语法
+系统 SHALL 不在 Thymeleaf 表达式中使用 Groovy 闭包语法（如 `.groupBy { ... }`），TimelineSection 需改用 `postFinder.list({...})` 获取文章列表。
+
+#### Scenario: 首页时间线区块正常渲染
+- **WHEN** 用户访问首页且启用了时间线区块
+- **THEN** 首页正常显示，时间线区块按年展示文章
+
+### Requirement: 正确引用菜单项 target 属性
+系统 SHALL 使用 `menuItem.spec.target` 替代 `menuItem.spec.target?.value`，`target` 是字符串类型。
+
+#### Scenario: 导航链接在新标签页打开
+- **WHEN** 菜单项配置了在新标签页打开
+- **THEN** 链接正确设置 target 属性

.trae/specs/fix-white-screen-api-errors/tasks.md

@@ -0,0 +1,51 @@
+# Tasks
+
+- [x] Task 1: 修复 moments.astro 页面 - 替换 `momentFinder.list()` 为 `momentFinder.list(1, 50)`，修复 `moment.spec.media` 为 `moment.spec.content.medium`
+  - [x] 将 `th:with="moments = ${momentFinder.list()}"` 改为 `th:with="momentsResult = ${momentFinder.list(1, 50)}"`
+  - [x] 将 `th:each="moment : ${moments}"` 改为 `th:each="moment : ${momentsResult.items}"`
+  - [x] 将 `th:if="${moments != null and not #lists.isEmpty(moments)}"` 改为 `th:if="${momentsResult != null and not #lists.isEmpty(momentsResult.items)}"`
+  - [x] 将 `moment.spec?.media` 改为 `moment.spec.content.medium`
+  - [x] 将 `moment.spec.media` 改为 `moment.spec.content.medium`
+  - [x] 将 `media.type == 'PHOTO'` 保持不变（MomentMediaType.PHOTO 对应字符串 'PHOTO'）
+  - [x] 将 `media.url` 保持不变
+  - [x] 将 `media.displayName ?: ''` 改为 `''`（MomentMedia 没有 displayName 字段）
+
+- [x] Task 2: 修复 MomentsSection.astro 组件 - 替换 `momentFinder.list()` 为 `momentFinder.list(1, limit)`
+  - [x] 将 `th:with="moments = ${momentFinder != null ? momentFinder.list() : null}, limit = ..."` 改为 `th:with="momentsResult = ${momentFinder.list(1, limit)}"`
+  - [x] 将 `th:each="moment, stat : ${moments}"` 改为 `th:each="moment : ${momentsResult.items}"`
+  - [x] 移除 `th:if="${stat.index < limit}"` 限制（已通过 list 的 size 参数限制）
+  - [x] 修复 `moment.spec?.content?.html ?: moment.spec?.content?.raw ?: moment.spec?.content` 保持不变（正确）
+  - [x] 修复 `moment.spec?.releaseTime` 保持不变（正确）
+
+- [x] Task 3: 修复 photos.astro 页面 - 替换 `photoFinder.listGroups()` + `listByGroupName()` 为 `photoFinder.groupBy()`
+  - [x] 将 `th:with="groups = ${photoFinder.listGroups()}"` 改为使用 `photoFinder.groupBy()`
+  - [x] 使用 `th:each="group : ${photoFinder.groupBy()}"` 遍历分组
+  - [x] `group` 是 `PhotoGroupVo`，包含 `metadata`、`spec`、`status`、`photos` 字段
+  - [x] 移除 `th:with="photos = ${photoFinder.listByGroupName(group.metadata?.name)}"` 内部调用
+  - [x] 直接使用 `group.photos` 遍历照片
+  - [x] 照片字段：`photo.spec.url`、`photo.spec.displayName`、`photo.spec.description`
+
+- [x] Task 4: 修复 PhotosSection.astro 组件 - 替换 `photoFinder.listGroups()` + `listByGroupName()` 为 `photoFinder.groupBy()`
+  - [x] 将 `th:with="groups = ${photoFinder != null ? photoFinder.listGroups() : null}"` 改为使用 `photoFinder.groupBy()`
+  - [x] 使用 `th:each="group : ${photoFinder.groupBy()}"` 获取第一个分组
+  - [x] 使用 `group.photos` 获取照片列表
+  - [x] 限制显示数量使用 `th:each="photo, stat : ${group.photos}" th:if="${stat.index < limit}"`
+
+- [x] Task 5: 修复 TimelineSection.astro - 移除 Groovy 闭包语法
+  - [x] 将 `${postFinder.listAll().groupBy { it.spec.publishTime?.getYear() }}` 改为 `${postFinder.list({page: 1, size: 50})}`
+  - [x] 使用 `th:each="post : ${posts.items}"` 遍历文章
+  - [x] 按年份分组改用 Thymeleaf 的方式：先获取所有文章，再在模板中按年分组展示
+
+- [x] Task 6: 修复 Navbar.astro 和 Header.astro 中的 `menuItem.spec.target?.value`
+  - [x] 将 `th:target="${menuItem.spec.target?.value}"` 改为 `th:target="${menuItem.spec.target}"`
+
+- [x] Task 7: 构建并部署验证
+  - [x] 执行 `pnpm build`
+  - [x] 部署到 Docker 容器
+  - [x] 重启 Halo 容器
+  - [x] 通过浏览器访问所有页面验证无白屏
+
+# Task Dependencies
+- [Task 7] depends on [Task 1, Task 2, Task 3, Task 4, Task 5, Task 6]
+- [Task 1] and [Task 2] can be parallelized
+- [Task 3] and [Task 4] can be parallelized