diff --git a/.dockerignore b/.dockerignore
new file mode 100644
index 0000000000000000000000000000000000000000..d38aa906b0614a2716ee5838778a1378304f2c10
--- /dev/null
+++ b/.dockerignore
@@ -0,0 +1,21 @@
+.git
+.github
+.husky
+.vscode
+.idea
+
+node_modules
+dist
+dev
+coverage
+.nyc_output
+
+docs
+*.log
+npm-debug.log*
+
+.specstory
+.spec-workflow
+.serena
+.claude
+
diff --git a/.editorconfig b/.editorconfig
new file mode 100644
index 0000000000000000000000000000000000000000..1014ba78880c899e842b397cb89a878be4671f7d
--- /dev/null
+++ b/.editorconfig
@@ -0,0 +1,12 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+trim_trailing_whitespace = true
+
+[*.md]
+trim_trailing_whitespace = false
diff --git a/.gitattributes b/.gitattributes
index a6344aac8c09253b3b630fb776ae94478aa0275b..19b8fe80cf349f546c54624861a1951e6f34c00d 100644
--- a/.gitattributes
+++ b/.gitattributes
@@ -1,35 +1,21 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+* text=auto
+
+*.js text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.yml text eol=lf
+*.yaml text eol=lf
+*.css text eol=lf
+*.html text eol=lf
+*.sh text eol=lf
+
+# Husky hooks 必须使用 LF
+.husky/* text eol=lf
+
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.ico binary
+assets/preview_dark.png filter=lfs diff=lfs merge=lfs -text
+assets/preview_light.png filter=lfs diff=lfs merge=lfs -text
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000000000000000000000000000000000000..887c75fcec7c0fbf915e8ebca2b9b52b701fbfb0
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,43 @@
+# 依赖相关
+node_modules/
+npm-debug.log*
+
+# 构建输出
+dist/
+
+# IDE/编辑器配置
+.vscode/
+.idea/
+.specstory
+.cursorindexingignore
+.cursor
+.spec-workflow/
+.serena/
+
+# 系统文件
+.DS_Store
+Thumbs.db
+
+
+# 个人笔记
+docs/
+
+# 测试相关文件
+dev/
+jest.config.js
+tests/
+coverage/
+.nyc_output/
+jest-*.json
+jest.results.json
+.eslintcache
+tests/screenshots/
+tests/fixtures/
+*.test.js
+*.spec.js
+
+# SpecStory explanation file
+.specstory/.what-is-this.md
+AGENTS.md
+/.claude
+/discord-style-navstation
diff --git a/.husky/pre-commit b/.husky/pre-commit
new file mode 100644
index 0000000000000000000000000000000000000000..3d9b75819cc01fe79923ae3e2a21a87f59071897
--- /dev/null
+++ b/.husky/pre-commit
@@ -0,0 +1,10 @@
+#!/usr/bin/env sh
+
+# 进入仓库根目录，避免在子目录执行 git commit 时找不到脚本/依赖
+cd "$(dirname "$0")/.." || exit 1
+
+# Windows Git Bash 下如果需要中文输出不乱码，可在个人环境中设置终端编码/locale
+# 这里不强制设置 LANG/LC_ALL，避免在 Linux/macOS 上因 locale 不存在而产生警告
+
+# 优先使用项目内的 lint-staged，避免依赖全局 PATH
+./node_modules/.bin/lint-staged
diff --git a/.prettierignore b/.prettierignore
new file mode 100644
index 0000000000000000000000000000000000000000..851a24fce79c8102bdb103535dfe6437e9357925
--- /dev/null
+++ b/.prettierignore
@@ -0,0 +1,29 @@
+# 依赖和构建产物
+node_modules/
+dist/
+dev/
+
+# npm lockfile（避免提交时产生大面积格式化 diff）
+package-lock.json
+
+# Git 配置文件
+.gitattributes
+.gitignore
+
+# Husky hooks（shell 脚本，不需要 Prettier 格式化）
+.husky/
+
+# 缓存文件
+*.cache
+.cache/
+
+# 日志文件
+*.log
+
+# 临时文件
+*.tmp
+*.temp
+
+# 文档文件（保留排版灵活性，避免代码示例被格式化）
+**/README.md
+src/**/*.md
diff --git a/.prettierrc.json b/.prettierrc.json
new file mode 100644
index 0000000000000000000000000000000000000000..132f5de69bf995ec8a392b12d0d5d2ddb583b080
--- /dev/null
+++ b/.prettierrc.json
@@ -0,0 +1,7 @@
+{
+  "printWidth": 100,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "tabWidth": 2,
+  "useTabs": false
+}
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000000000000000000000000000000000000..19eaf541e0277240ee4bb3fb4697211af7a2942f
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,252 @@
+# 更新记录
+
+> 本文件维护 MeNav 历史更新记录。README 不再维护"更新记录"章节。
+
+### 2026/01/04
+
+**1. 首屏性能优化**
+
+- 移除首页副标题固定 Quicksand 外链字体，改为跟随全站字体
+- 字体外链 CSS 支持 `fonts.preload: true`（`preload + onload` 非阻塞加载，含 `<noscript>` 回退）
+- Font Awesome CSS 改为 `preload + onload` 非阻塞加载，降低 render-blocking 影响
+- 构建阶段压缩 `style.css` / `script.js` / `pinyin-match.js`，减少传输体积
+
+**2. 安全与部署稳定性**
+
+- 链接安全加固：模板与运行时统一校验 URL scheme（不安全链接降级为 `#`），新增 `security.allowedSchemes` 支持显式放行自定义协议
+- 去除外部输入的 `innerHTML` 拼接：分类标题更新/新增分类改用 DOM API 构建，降低注入风险
+- `sync-articles` 对齐 best-effort：同步失败不再以非 0 退出码阻断构建/部署
+- 版本号来源统一：`window.MeNav.version` 不再写死，自动读取构建注入版本（用于扩展/调试识别）
+
+**3. 模板图标 helper（Breaking）**
+
+- 模板 helper `faviconUrl` 更名为 `faviconV2Url`，避免与站点字段 `sites[].faviconUrl` 同名冲突；如有自定义模板调用 `{{faviconUrl url}}`，需同步改为 `{{faviconV2Url url}}`
+
+### 2026/01/03
+
+关联 Issue：[#31](https://github.com/rbetree/menav/issues/31)
+
+**1. favicon 加载优化**
+
+- 新增 `icons.region: com | cn` 配置项，允许用户选择优先使用国内源或国外源
+  - `com`（默认）：优先 gstatic.com，失败回退 gstatic.cn
+  - `cn`：优先 gstatic.cn，失败回退 gstatic.com
+- 修改 favicon 加载超时判断机制
+  - 自定义 faviconUrl：5秒超时后显示回退图标
+  - 自动 favicon：每次尝试3秒超时，最多等待6秒
+  - 避免网络慢时长时间显示加载动画
+
+### 2026/01/02
+
+关联 Issue：[#30](https://github.com/rbetree/menav/issues/30)
+
+细节见：[`config/update-instructions-20260102.md`](config/update-instructions-20260102.md)
+
+**1. 外部资源可用性**
+
+- Font Awesome：bootcdn → cdnjs（Cloudflare），降低被拦截风险
+- favicon：`t3.gstatic.com` 失败自动回退 `t3.gstatic.cn`，提升国内网络可用性
+
+**2. 图标模式与站点级覆盖**
+
+- 修复 `site.yml -> icons.mode` 配置未生效（构建期提升为顶层 `icons.mode`，供模板/运行时统一读取）
+- 新增站点级图标覆盖：`faviconUrl` / `forceIconMode: favicon | manual`（优先级：`faviconUrl` > `forceIconMode` > 全局 `icons.mode`）
+
+**3. 嵌套交互与链接打开**
+
+- 恢复二级分组折叠入口（桌面端默认隐藏，悬停/收起态显示，避免界面过密）
+- 多级结构下递归补齐 `sites[].external` 默认值，保证站点链接默认新标签页打开
+
+### 2025/12/27
+
+细节见：[`config/update-instructions-20251227.md`](config/update-instructions-20251227.md)
+
+**1. 页面模板差异化改进（Phase 1/Phase 2）**
+
+- 首页判定规则调整：`site.yml -> navigation` 第一项即首页（不再依赖 `home` 页面/ID）
+- 模板体系整理：通用 `page` + 特殊页 `projects/articles/bookmarks` + 内置 `search-results`
+- `bookmarks` 标题后追加只读更新时间：`update: YYYY-MM-DD | from: git|mtime`
+- `articles` Phase 2：RSS 聚合文章条目（只读 `data-type="article"`），按 `articles.yml` 分类聚合展示；保留隐藏写回结构避免干扰扩展
+- `projects`：repo 风格卡片（language/stars/forks 自动抓取）+ 可选 GitHub 贡献热力图
+
+**2. 工作流与时效性数据刷新**
+
+- GitHub Actions 构建前自动执行 `sync-projects` / `sync-articles`
+- 新增 `schedule` 定时触发刷新（cron 使用 UTC，可在 workflow 中调整）
+
+**3. 配置与兼容清理（Breaking）**
+
+- 移除旧版单文件配置 `config.yml/config.yaml` 回退
+- 移除独立 `navigation.yml` 回退
+- 移除 `pages/home.yml -> 顶层 categories` 与 `home` 子菜单特例
+- `navigation[].active` 不再生效（首页/默认打开页始终由 `navigation` 第一项决定）
+
+**4. 配置变更（字段新增/减少）**
+
+- 新增：
+  - `site.rss.*`：articles RSS 抓取与缓存配置（用于 `npm run sync-articles`）
+  - `site.github.*`：projects 热力图与仓库元信息抓取缓存配置（用于 `npm run sync-projects`）
+  - `pages/<id>.yml -> template`：页面模板选择（缺省时按回退规则使用 `page`）
+- 说明：
+  - “首页”始终由 `site.yml -> navigation` 第一项决定，不要求页面 id 为 `home`
+
+### 2025/12/23
+
+**1. 侧边栏与导航交互优化**
+
+- 高亮项有子菜单时会自动展开
+- 侧边栏 `logo_text` 左侧展示站点 Logo（复用 `site.favicon`）
+
+**2. 卡片层级折叠规则调整**
+
+- 仅 1 层分类：一级分类支持下拉/收起
+- 2/3 层分类：仅二级标题支持下拉/收起（一级/三级不提供折叠按钮与交互）
+
+**3.页面细节**
+
+- 主题蓝调整为 `#7694B9`，统一应用到高亮/渐变/阴影
+- 搜索无结果红色状态图标对齐修复（避免图标位置偏移）
+- `menav.svg` 优化暗色背景可读性（字母颜色加深）
+
+### 2025/11/09
+
+**1. 默认配置与文档**
+
+- 更新默认配置与项目 Logo，并同步完善 README
+
+### 2025/10/31
+
+**1. 书签导入与嵌套结构**
+
+- 优化书签转换逻辑与分类嵌套结构
+- 修复书签转换脚本问题，提升稳定性
+
+### 2025/10/24 - 2025/10/27
+
+**1. 分类/卡片交互与细节修复**
+
+- 为各结构补齐下拉指示与交互，并新增“分类展开/收起”按钮
+- 修复侧边栏切换图标错位、站点卡片悬浮层级遮挡问题
+- 调整卡片间距与 category/group 栏样式效果，移除废弃的 `restructure` 命令
+
+### 2025/10/18
+
+**1. 图标模式默认行为变更**
+
+- 默认启用 `icons.mode: favicon`，自动根据站点 URL 加载 favicon（失败回退为 Font Awesome 图标）
+- 如需关闭外部请求并完全使用手动图标，请在 `config/user/site.yml` 中设置：
+
+```yaml
+# config/user/site.yml
+icons:
+  mode: manual # 关闭 favicon 请求，纯手动图标
+```
+
+### 2025/10/14
+
+**1. 拼音搜索支持**
+
+- 支持中文拼音与首字母匹配检索（基于 `pinyin-match`）
+
+### 2025/07/30
+
+**1. 链接打开行为一致性**
+
+- 统一站点/导航外链为新标签页打开，改善导航体验
+
+### 2025/07/07
+
+**1. UI 细节优化**
+
+- 侧边栏显示与布局细节优化
+- 明暗主题切换按钮样式改进
+- 欢迎文本与布局对齐优化
+
+### 2025/05/22
+
+**1. MeNav 浏览器扩展支持接口**
+
+- 注入扩展元信息（`menav-config-data`）并输出 `dist/menav-config.json` 供扩展按需加载（避免把整站配置注入到 `index.html`）
+- 暴露 `window.MeNav` 基础能力与 DOM 数据属性，支持元素精准定位与更新
+- 为扩展推送与页面联动打通基础能力
+
+### 2025/05/16
+
+**1. MarksVault 浏览器扩展集成**
+
+- 支持与 [MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展集成
+- 使用扩展自动推送书签文件到 MeNav
+- 自动处理推送的书签文件并更新网站
+
+### 2025/05/09
+
+**1. 搜索引擎集成功能**
+
+- 集成Google、Bing、百度搜索引擎
+- 通过搜索框图标一键切换不同搜索引擎
+- 用户选择保存在本地，下次访问自动应用
+
+### 2025/05/08
+
+**1. Handlebars模板系统重构**
+
+- 使用Handlebars模板引擎重构整个前端生成系统
+- 实现模块化、组件化的模板结构，包含layouts、pages和components
+- 改进代码复用，提高可维护性和扩展性
+- 优化HTML生成逻辑，提升性能和代码质量
+
+### 2025/05/04
+
+**1. 移除双文件配置支持**
+
+- 完全移除了对双文件配置方法的支持
+- 简化了配置加载逻辑，现在仅支持模块化配置
+
+### 2025/05/03
+
+**1. 侧边栏收回功能**
+
+- 添加侧边栏折叠/展开按钮，位于Logo文本右侧
+- 侧边栏平滑折叠/展开过渡
+
+**2. 移动端UI优化**
+
+- 修复搜索按钮和侧边栏按钮遮挡问题
+- 点击侧边栏导航项后自动收起侧边栏
+
+### 2025/05/02
+
+**1. 模块化配置**
+
+- 支持将配置拆分为多个文件，便于管理和维护
+- 引入配置目录结构，分离页面配置
+- 配置统一采用模块化目录结构（`config/user/` / `config/_default/`）
+
+### 2025/05/01
+
+**1. 页面布局优化**
+
+- 优化了内容区域和侧边栏的间距，确保各种分辨率下内容不会贴近边缘
+- 卡片与边框始终保持合理间距，避免在窄屏设备上与滚动条贴边
+- 调整了搜索结果区域的边距，与常规分类保持样式一致性
+
+**2. 网站卡片文本优化**
+
+- 为站点卡片标题添加单行文本截断，过长标题显示省略号
+- 为站点描述添加两行限制和省略号，保持卡片布局整洁
+- 添加卡片悬停提示，方便查看完整信息
+
+**3. 移动端显示增强**
+
+- 优化了移动端卡片尺寸，一屏可显示更多网址
+- 图标大小自适应，在小屏幕上更加紧凑
+- 为不同尺寸移动设备（768px、480px、400px）提供递进式UI优化
+- 减小卡片内边距和元素间距，增加屏幕利用率
+
+**4. 书签导入功能**
+
+- 支持从Chrome、Firefox和Edge浏览器导入HTML格式书签
+- 自动处理书签文件，解析文件夹结构和链接
+- 图标处理：默认加载站点 favicon；在 manual 模式下保留 Font Awesome 匹配
+- 生成配置文件，无需手动录入即可批量导入网站链接
+- 与GitHub Actions集成，全自动化的导入和部署流程
diff --git a/CNAME b/CNAME
new file mode 100644
index 0000000000000000000000000000000000000000..6cc829ba56086dedf71d80e91bd2b108326c5978
--- /dev/null
+++ b/CNAME
@@ -0,0 +1 @@
+home.346247.xyz
\ No newline at end of file
diff --git a/Dockerfile b/Dockerfile
index a0f0c706fcc77ea01823066a2f2fd5d6c2719398..c24626fb436891ce2b40dc21445d16417ca582e1 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -1,71 +1,22 @@
-# 使用 Node.js 官方镜像作为基础
-FROM node:20-alpine AS builder
+# 动态构建版本（默认）：容器启动时执行 `npm run build` 生成 dist，再由 nginx 提供静态文件。
 
-WORKDIR /app
-
-# 复制项目文件
-COPY . .
-
-# 安装依赖
-RUN npm ci --omit=dev || npm install
-
-# 构建项目（每次启动时执行，但镜像中预先构建一次）
-RUN npm run build || echo "Build will run at runtime"
-
-# ===== 运行阶段 =====
-FROM node:20-alpine
+FROM node:22-alpine
 
 WORKDIR /app
 
-# 安装 nginx 和运行时依赖
-RUN apk add --no-cache nginx
+ENV HUSKY=0
 
-# 复制构建产物和源码
-COPY --from=builder /app /app
+COPY package.json package-lock.json ./
+RUN npm ci && apk add --no-cache nginx
 
-# 创建必要的目录
-RUN mkdir -p /app/dist /app/config /app/bookmarks /run/nginx /var/log/nginx
-
-# 复制 nginx 配置
-RUN cat > /etc/nginx/nginx.conf << 'EOF'
-pid /tmp/nginx.pid;
-events {
-    worker_connections 1024;
-}
-http {
-    include /etc/nginx/mime.types;
-    default_type application/octet-stream;
-    access_log /tmp/access.log;
-    error_log /tmp/error.log;
-    
-    server {
-        listen 7860;
-        server_name localhost;
-        root /app/dist;
-        index index.html;
-        
-        location / {
-            try_files $uri $uri/ /index.html;
-        }
-        
-        location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
-            expires 1y;
-            add_header Cache-Control "public, immutable";
-        }
-    }
-}
-EOF
+COPY . .
 
-# 设置环境变量
-ENV PORT=7860
-ENV MENAV_PORT=7860
-ENV MENAV_ENABLE_SYNC=false
-ENV MENAV_IMPORT_BOOKMARKS=false
+COPY docker/nginx/default.conf /etc/nginx/http.d/default.conf
+COPY docker/entrypoint-build-and-serve.sh /usr/local/bin/entrypoint-build-and-serve.sh
+RUN chmod +x /usr/local/bin/entrypoint-build-and-serve.sh
 
-EXPOSE 7860
+EXPOSE 80
 
-# 启动脚本
-COPY entrypoint.sh /entrypoint.sh
-RUN chmod +x /entrypoint.sh
+STOPSIGNAL SIGQUIT
 
-CMD ["/entrypoint.sh"]
\ No newline at end of file
+ENTRYPOINT ["/usr/local/bin/entrypoint-build-and-serve.sh"]
diff --git a/Dockerfile.static b/Dockerfile.static
new file mode 100644
index 0000000000000000000000000000000000000000..5fa7c10d2d350e6e59f869f4b270cf00c8efdfa2
--- /dev/null
+++ b/Dockerfile.static
@@ -0,0 +1,38 @@
+# 静态构建版本（可选）：构建阶段生成 dist，运行阶段仅 nginx 提供静态文件。
+# 默认 Docker 方案请使用仓库根目录的 Dockerfile（动态构建，可挂载配置并通过重启生效）。
+
+FROM node:22-alpine AS builder
+
+WORKDIR /app
+
+ENV HUSKY=0
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY . .
+
+ARG MENAV_ENABLE_SYNC=false
+ARG MENAV_IMPORT_BOOKMARKS=false
+
+RUN if [ "${MENAV_IMPORT_BOOKMARKS}" = "true" ]; then \
+      MENAV_BOOKMARKS_DETERMINISTIC=1 npm run import-bookmarks; \
+    fi \
+    && if [ "${MENAV_ENABLE_SYNC}" = "true" ]; then \
+      npm run build; \
+    else \
+      PROJECTS_ENABLED=false HEATMAP_ENABLED=false RSS_ENABLED=false npm run build; \
+    fi
+
+FROM nginx:1.27-alpine AS runtime
+
+WORKDIR /usr/share/nginx/html
+
+COPY docker/nginx/default.conf /etc/nginx/conf.d/default.conf
+COPY --from=builder /app/dist ./
+
+EXPOSE 80
+
+STOPSIGNAL SIGQUIT
+
+CMD ["nginx", "-g", "daemon off;"]
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000000000000000000000000000000000000..be3f7b28e564e7dd05eaf59d64adba1a4065ac0e
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,661 @@
+                    GNU AFFERO GENERAL PUBLIC LICENSE
+                       Version 3, 19 November 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+  A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+  The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+  An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU Affero General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Remote Network Interaction; Use with the GNU General Public License.
+
+  Notwithstanding any other provision of this License, if you modify the
+Program, your modified version must prominently offer all users
+interacting with it remotely through a computer network (if your version
+supports such interaction) an opportunity to receive the Corresponding
+Source of your version by providing access to the Corresponding Source
+from a network server at no charge, through some standard or customary
+means of facilitating copying of software.  This Corresponding Source
+shall include the Corresponding Source for any work covered by version 3
+of the GNU General Public License that is incorporated pursuant to the
+following paragraph.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the work with which it is combined will remain governed by version
+3 of the GNU General Public License.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU Affero General Public License from time to time.  Such new versions
+will be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU Affero General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU Affero General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU Affero General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.
diff --git a/README.md b/README.md
index 7f3da526d171850522f658a762379c2231876cda..ce881f6e8ebdbbbf73971957906daa67c9975433 100644
--- a/README.md
+++ b/README.md
@@ -1,10 +1,382 @@
----
-title: Me
-emoji: 🐠
-colorFrom: yellow
-colorTo: blue
-sdk: docker
-pinned: false
----
-
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+<div align="center">
+  <img src="assets/menav.svg" alt="MeNav" width="120">
+  <h1>MeNav</h1>
+  <p>
+    一个轻量的个人导航网站
+  </p>
+</div>
+
+[![License](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](https://www.gnu.org/licenses/agpl-3.0.html)
+[![GitHub stars](https://img.shields.io/github/stars/rbetree/menav)](https://github.com/rbetree/menav/stargazers)
+[![GitHub forks](https://img.shields.io/github/forks/rbetree/menav)](https://github.com/rbetree/menav/network/members)
+
+📋 静态一键部署 | ⚡ 自动化构建 | 🔖 支持书签导入
+
+> MeNav 是一个轻量级、高度可定制的个人导航网站生成器，让您轻松创建属于自己的导航主页。无需数据库和后端服务，完全静态部署，支持一键 Fork 部署到 GitHub Pages，还可以从浏览器书签一键导入网站。配合 [MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展，更支持书签自动同步和导航站自动更新。
+
+如果觉得项目有用，欢迎 Star/Fork 支持，谢谢！
+
+[直接开始部署>>](#部署方式)
+
+## 预览
+
+[在线访问](https://rbetree.github.io/menav/)
+
+<p align="center">
+  <img src="assets/preview_light.png" alt="明亮主题预览" width="48%">
+  <img src="assets/preview_dark.png" alt="黑暗主题预览" width="48%">
+</p>
+
+## 特点
+
+- 简洁美观的响应式布局设计
+- 集成外部搜索引擎
+- 分类展示网站链接
+- 模块化配置
+- 支持从浏览器导入书签
+- 支持2-4层级的多层级嵌套结构
+- 与 [MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展集成，支持自动推送书签
+- 可部署到GitHub Pages或任何类似的CI/CD服务
+
+> 历史更新记录已迁移至 [`CHANGELOG.md`](CHANGELOG.md)，README 不再维护该部分。
+
+
+## 技术栈
+
+- HTML5 + CSS3
+- JavaScript (原生)
+- Handlebars 模板引擎
+- Google Favicon API + Font Awesome 图标
+
+## 项目结构
+
+```text
+menav/
+├── src/        # 生成器、书签处理、前端脚本（入口：src/generator.js）
+├── templates/  # Handlebars 模板（layouts/pages/components）
+├── config/     # 模块化配置
+├── assets/     # 静态资源
+├── bookmarks/  # 书签导入相关
+└── dist/       # 构建产物
+```
+
+## 文档导航
+
+- 历史更新记录（README 不再维护）：[`CHANGELOG.md`](CHANGELOG.md)
+- 更新说明2025/12/27（兼容性移除 / 迁移指南）：[`config/update-instructions-20251227.md`](config/update-instructions-20251227.md)
+- 配置系统（完全替换策略、目录结构、示例）：[`config/README.md`](config/README.md)
+- 书签导入（格式要求、流程、常见问题）：[`bookmarks/README.md`](bookmarks/README.md)
+- 模板系统（组件、回退、数据流）：[`templates/README.md`](templates/README.md)
+- 源码结构（各脚本职责）：[`src/README.md`](src/README.md)
+- Handlebars helpers（模板辅助函数）：[`src/helpers/README.md`](src/helpers/README.md)
+- 静态资源（样式/图片等）：[`assets/README.md`](assets/README.md)
+
+## 快速开始
+
+用于本地开发预览与构建静态站点；在线部署见 [部署方式](#部署方式)。
+
+<details>
+<summary>点击展开</summary>
+
+通过以下步骤快速设置您的个人导航站：
+
+1. 克隆仓库
+
+```bash
+git clone https://github.com/rbetree/menav.git
+cd menav
+```
+
+2. 安装依赖
+
+```bash
+# 安装依赖
+npm install
+```
+
+（本仓库的 GitHub Actions/CI 已改为使用 `npm ci`，以获得更稳定、可复现的依赖安装（基于 `package-lock.json`）；本地开发可继续使用 `npm install`，也可直接使用 `npm ci`。）
+
+3. 完成配置（见[设置配置文件](#设置配置文件)）
+4. 导入书签（可选）
+   - 将浏览器导出的HTML格式书签文件放入`bookmarks`目录
+   - 运行书签处理命令：
+
+   ```bash
+   npm run import-bookmarks
+   ```
+
+   - 若希望生成结果保持确定性（便于版本管理，减少时间戳导致的无意义 diff）：
+
+   ```bash
+   MENAV_BOOKMARKS_DETERMINISTIC=1 npm run import-bookmarks
+   ```
+
+   - 系统会自动将书签转换为配置文件保存到`config/user/pages/bookmarks.yml`
+
+- **注意**：`npm run dev`命令不会自动处理书签文件，必须先手动运行上述命令
+- `npm run dev` 默认会刷新 `articles/projects` 的联网缓存（若你希望离线启动，请使用 `npm run dev:offline`）
+
+5. 构建
+
+```bash
+# 启动开发服务器
+npm run dev
+```
+
+```bash
+# 离线启动开发服务器（不刷新联网缓存）
+npm run dev:offline
+```
+
+```bash
+# 生成静态HTML文件
+npm run build
+```
+
+构建后的文件位于`dist`目录
+
+6. 提交前检查（推荐）
+
+```bash
+# 一键检查（语法检查 + 单元测试 + 构建）
+npm run check
+```
+
+（可选）格式化代码：
+
+```bash
+npm run format
+```
+
+</details>
+
+## 部署方式
+
+用于将生成的静态站点发布到 服务器 or CI/CD；本地构建见 [快速开始](#快速开始)。
+
+### 快速部署到GitHub Pages（推荐）
+
+<details>
+<summary>点击展开</summary>
+
+#### 第一步：前置设置
+
+1. Fork仓库:
+   - 点击右上角的 Fork 按钮复制此仓库到您的账号
+
+2. 启用Actions:
+   - 进入fork后的仓库
+   - 点击顶部的 "Actions" 标签页
+   - 点击绿色按钮 "I understand my workflows, go ahead and enable them"
+
+3. 配置Pages:
+   - 进入仓库的 Settings -> Pages
+   - 在 "Build and deployment" 部分
+   - Source: 选择 "GitHub Actions"
+
+#### 第二步：自定义配置
+
+创建个人配置文件:
+
+- **重要:** 始终创建自己的用户配置文件，不要直接修改默认配置文件
+- 完成配置文件（见[设置配置文件](#设置配置文件)）
+- 提交您的配置文件到仓库
+
+#### 第三步：等待自动部署
+
+- GitHub Actions会自动检测您的更改
+- 构建并部署您的网站
+- 部署完成后，您可以在 Settings -> Pages 中找到您的网站地址
+  - 站点内容的“时效性数据”（RSS 文章聚合、projects 仓库统计）会由部署工作流在构建前自动刷新
+  - 也支持定时刷新：默认每天 UTC 02:00 触发一次（GitHub Actions cron 使用 UTC；北京时间=UTC+8，可在 `.github/workflows/deploy.yml` 中调整 `schedule.cron`）
+
+**重要: Sync fork后需要手动触发工作流**:
+
+- 当您使用GitHub界面上的"Sync fork"按钮同步本仓库的更新后
+- GitHub Actions工作流不会自动运行
+- 您需要手动触发构建流程:
+  - 进入 Actions 标签页
+  - 选择左侧的 "Build and Deploy" 工作流
+  - 点击 "Run workflow" 按钮
+
+</details>
+
+### Docker 部署（可选）
+
+<details>
+<summary>点击展开</summary>
+
+仓库已内置 `docker-compose.yml`，并提供 GHCR 预构建镜像；两种方式都建议统一使用 Docker Compose。
+
+> 说明：容器每次启动都会在容器内执行 `npm run build` 生成 `dist/`，然后用 nginx 提供静态文件。
+>
+> 请在仓库根目录执行（需要 `config/_default` 等文件）。
+
+#### 方式 A：使用预构建镜像（推荐，免本地构建）
+
+```bash
+docker compose pull
+docker compose up -d --no-build
+```
+
+#### 方式 B：本地构建镜像（适合二次开发/改源码）
+
+```bash
+docker compose up -d --build
+```
+
+默认访问地址：`http://localhost:8080`
+
+#### 可选参数（环境变量）
+
+```bash
+MENAV_PORT=80 MENAV_ENABLE_SYNC=true MENAV_IMPORT_BOOKMARKS=true docker compose up -d --no-build
+```
+
+- `MENAV_PORT`：宿主机端口（默认 `8080`）
+- `MENAV_ENABLE_SYNC`：启动构建时是否联网执行 `sync-*`（默认 `false`，更稳定）
+- `MENAV_IMPORT_BOOKMARKS`：启动构建前是否执行 `npm run import-bookmarks`（默认 `false`）
+
+#### 配置与更新
+
+- 配置目录挂载在 `./config`，个人配置按“完全替换策略”建议：将 `config/_default/` 完整复制到 `config/user/` 再修改（见 [设置配置文件](#设置配置文件) 与 `config/README.md`）。
+- 如需导入书签：将浏览器导出的书签 HTML 放到 `./bookmarks/`，并设置 `MENAV_IMPORT_BOOKMARKS=true` 后重启容器。
+- 修改配置/书签后生效方式（触发重新构建）：
+
+```bash
+docker compose restart menav
+```
+
+</details>
+
+### 部署到服务器
+
+<details>
+<summary>点击展开</summary>
+
+如果您想部署到自己的Web服务器，只需要以下几个步骤：
+
+1. 构建静态网站:
+
+```bash
+npm run build
+```
+
+2. 复制构建结果:
+   - 所有生成的静态文件都位于 `dist` 目录中
+   - 将 `dist` 目录中的所有文件复制到您的Web服务器根目录
+
+3. 配置Web服务器:
+   - 确保服务器配置为提供静态文件
+   - 对于Apache: 在网站根目录中已有正确的 .htaccess 文件
+   - 对于Nginx: 添加以下配置到您的server块:
+
+```nginx
+server {
+    listen 80;
+    server_name your-domain.com;
+    root /path/to/dist;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /404.html;
+    }
+}
+```
+
+4. 更新配置:
+   - 如果您想在服务器上更新网站，只需重复上述步骤1-2
+   - 或者设置自动部署流程，例如使用GitLab CI/CD或Jenkins
+
+</details>
+
+### 其他CI/CD托管选项
+
+<details>
+<summary>点击展开</summary>
+
+除了GitHub Pages外，您还可以使用其他各种CI/CD服务部署MeNav：
+
+**如 Vercel / Netlify / Cloudflare Pages**:
+
+- 连接您的GitHub仓库
+- 设置构建命令为`npm run build`
+- 设置输出目录为`dist`
+
+Vercel 部署:
+
+1. 登录 Vercel，点击 `Add New...` → `Project`
+2. 选择 `Import Git Repository`，连接并选择你的 MeNav 仓库
+3. 构建配置（一般选择 `Other` 或保持默认自动识别即可）：
+   - `Build Command`: `npm run build`
+   - `Output Directory`: `dist`
+   - `Install Command`（可选，但更稳定）：`npm ci`
+4. 点击 `Deploy`，等待完成后用 Vercel 分配的域名/自定义域名访问
+
+**如果您只使用第三方平台部署（不使用 GitHub Pages）**：
+
+为避免 GitHub Actions 中的 Pages 配置错误，您可以禁用 GitHub Pages 部署步骤：
+
+1. 进入仓库的 Settings -> Secrets and variables -> Actions
+2. 点击 "Variables" 标签页
+3. 点击 "New repository variable"
+4. 名称填写：`ENABLE_GITHUB_PAGES`
+5. 值填写：`false`
+6. 点击 "Add variable"
+
+设置后，GitHub Actions 仍会自动构建网站（包括书签处理、RSS 同步等），但会跳过 GitHub Pages 部署步骤，避免报错。第三方平台（如 Vercel/Cloudflare Pages）会自动检测到代码变化并部署。
+
+> 如果你希望在构建时刷新“时效性数据”（RSS 文章聚合、projects 仓库统计），请将构建命令改为：
+>
+> ```bash
+> npm ci && npm run sync-projects && npm run sync-articles && npm run build
+> ```
+>
+> 说明：`sync-*` 会联网抓取并写入 `dev/` 缓存（仓库默认 gitignore）；同步脚本为 best-effort，失败不会阻断后续 `build`。
+>
+> 备注：`dev/` 只用于构建过程的中间缓存，默认不会被提交到仓库；部署时也只会上传 `dist/`，不会包含 `dev/`。
+
+> **书签转换依赖 GitHub Actions**
+> 如果需要使用书签自动推送功能，必须先在 GitHub 仓库中启用 GitHub Actions
+>
+> **部署流程**：
+>
+> ```
+> 1. 上传书签 → 2. GitHub Actions 处理 → 3. 使用处理完成的代码在 GitHub Pages 自动部署
+>                            ↓
+>           4. 其他 CI/CD 托管平台检测到变化 → 5. 使用处理完成的代码自动部署
+> ```
+
+无论选择哪种部署方式，请确保创建并使用您自己的配置文件，而不是直接修改默认配置。
+
+</details>
+
+## 设置配置文件
+
+MeNav 使用模块化配置方式，将配置分散到多个 YAML 文件中，更易于管理和维护。
+
+完整说明请直接看：[`config/README.md`](config/README.md)（以该文档为准）。
+
+> **🔔 重要提示：** 请务必在`config/user/`目录下创建并使用您自己的配置文件，不要直接修改默认配置文件，以便后续更新项目时不会丢失您的个性化设置。
+
+在加载配置时遵循以下优先级顺序：
+
+1. `config/user/` （用户配置）（优先级最高）
+2. `config/_default/` （默认配置）
+
+**注意：** 采用完全替换策略，而非合并。系统会选择存在的用户配置，完全忽略默认配置。
+
+### 最小可用配置（快速指引）
+
+- 首次使用建议先完整复制 `config/_default/` 到 `config/user/`，再按需修改（因为配置采用“完全替换”策略，不会从默认配置补齐缺失项）。
+- 至少需要有 `config/user/site.yml`（缺失时构建会直接报错退出，避免生成空白站点）。
+
+## 书签导入功能
+
+MeNav 支持从浏览器导入书签，快速批量添加网站链接；也支持与 MarksVault 扩展集成自动同步。
+
+完整说明请直接看：[`bookmarks/README.md`](bookmarks/README.md)（以该文档为准）。
+
+## Star-History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=rbetree/menav&type=Date)](https://www.star-history.com/#rbetree/menav&Date)
diff --git a/assets/README.md b/assets/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..448b1df5344600df667f6198bf09c1dbce3f279d
--- /dev/null
+++ b/assets/README.md
@@ -0,0 +1,98 @@
+# MeNav 资源目录
+
+## 目录
+
+- [目录概述](#目录概述)
+- [资源列表](#资源列表)
+- [CSS 模块化架构](#css-模块化架构)
+- [添加新资源](#添加新资源)
+
+## 目录概述
+
+`assets` 目录包含 MeNav 项目所需的所有静态资源文件，包括样式表、图标、图片等。这些资源文件直接被复制到生成的站点中，用于网站的展示和功能实现。
+
+## 资源列表
+
+目录包含以下主要资源：
+
+- **style.css**: 样式入口文件
+  - 通过 `@import` 聚合所有模块化 CSS
+  - 构建时由 esbuild 合并压缩为单文件
+
+- **styles/**: CSS 模块目录（详见下方）
+
+- **menav.svg**: 网站图标和项目logo
+  - 显示在浏览器标签页、书签和收藏夹中
+  - SVG格式，包含黑色字母"M"和蓝色向上箭头设计
+
+- **preview_light.png / preview_dark.png**: 主题预览图
+  - 用于 README 文档展示
+
+## CSS 模块化架构
+
+样式采用模块化组织，构建时自动合并：
+
+```
+assets/
+├── style.css              # 入口文件（@import 聚合）
+└── styles/
+    ├── _variables.css     # CSS 变量、主题色
+    ├── _base.css          # 全局重置、滚动条
+    ├── _animations.css    # @keyframes 动画
+    ├── _layout.css        # 页面容器布局
+    ├── _sidebar.css       # 侧边栏组件
+    ├── _search.css        # 搜索框组件
+    ├── _cards.css         # 卡片组件（站点卡片、tooltip）
+    ├── _modal.css         # 模态框、表单
+    ├── _content.css       # Markdown 内容页
+    ├── _dashboard.css     # 仪表盘（时钟/Todo）
+    └── _main.css          # 兜底样式（分类、热力图、响应式）
+```
+
+### 模块说明
+
+| 模块 | 职责 |
+|------|------|
+| `_variables.css` | CSS 变量、深色/浅色主题、间距/圆角系统 |
+| `_base.css` | 全局重置、滚动条、遮罩层、主题切换按钮 |
+| `_animations.css` | 所有 `@keyframes` 定义 |
+| `_layout.css` | 页面容器、欢迎区域、模板布局 |
+| `_sidebar.css` | 侧边栏、导航项、折叠状态、子菜单 |
+| `_search.css` | 搜索框、引擎下拉、快捷键提示 |
+| `_cards.css` | 站点卡片、网格布局、tooltip、编辑按钮 |
+| `_modal.css` | 模态框、表单控件、按钮样式 |
+| `_content.css` | Markdown 渲染（标题、代码块、表格等） |
+| `_dashboard.css` | 仪表盘网格、时钟卡片、Todo 列表 |
+| `_main.css` | 分类层级、GitHub 热力图、全局响应式 |
+
+### 构建流程
+
+构建时 esbuild 会：
+1. 解析 `style.css` 中的 `@import` 语句
+2. 合并所有模块为单文件
+3. 压缩输出到 `dist/style.css`
+
+> **开发提示**：修改 CSS 后运行 `npm run build` 或 `npm run dev` 查看效果。
+
+## 添加新资源
+
+### 文件命名规范
+
+- 使用小写字母和连字符 (`-`)
+- 避免使用空格和特殊字符
+- 名称应清晰表达文件用途
+
+### CSS 扩展指南
+
+1. **找到合适的模块**：根据功能选择对应的 `_*.css` 文件
+2. **遵循命名规范**：使用 BEM 风格或现有选择器模式
+3. **添加响应式支持**：在同一模块内添加 `@media` 查询
+4. **变量优先**：优先使用 `_variables.css` 中定义的变量
+
+### 图片优化
+
+- 压缩图片以减小文件大小
+- 使用 PNG、JPG、WebP 等 web 友好格式
+- 考虑添加合适的分辨率版本
+
+添加新资源后，构建系统会自动将这些文件复制到生成的网站中。
\ No newline at end of file
diff --git a/assets/menav.svg b/assets/menav.svg
new file mode 100644
index 0000000000000000000000000000000000000000..f30ad80c2120ed244922e5c3f08515931d41713f
--- /dev/null
+++ b/assets/menav.svg
@@ -0,0 +1,6 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="22 22 56 56">
+  <!-- 字母 M：使用比主题蓝更深一点的颜色，适配深色背景 -->
+  <path d="M 22 78 L 22 22 L 34 22 L 50 48 L 66 22 L 78 22 L 78 78 L 66 78 L 66 45 L 55 62 L 45 62 L 34 45 L 34 78 Z" fill="#425E82"/>
+  <!-- 蓝色的向上箭头 -->
+  <path d="M 45 70 L 45 45 L 36 48 L 50 28 L 64 48 L 55 45 L 55 70 Z" fill="#7694B9"/>
+</svg>
diff --git a/assets/pinyin-match.js b/assets/pinyin-match.js
new file mode 100644
index 0000000000000000000000000000000000000000..9a0d166c805d22799790ac9f131b8199610ee6b7
--- /dev/null
+++ b/assets/pinyin-match.js
@@ -0,0 +1 @@
+!function(n,i){"object"==typeof exports&&"undefined"!=typeof module?module.exports=i():"function"==typeof define&&define.amd?define(i):(n="undefined"!=typeof globalThis?globalThis:n||self).PinyinMatch=i()}(this,(function(){"use strict";function n(n,i,a){return(i=function(n){var i=function(n,i){if("object"!=typeof n||!n)return n;var a=n[Symbol.toPrimitive];if(void 0!==a){var u=a.call(n,i||"default");if("object"!=typeof u)return u;throw new TypeError("@@toPrimitive must return a primitive value.")}return("string"===i?String:Number)(n)}(n,"string");return"symbol"==typeof i?i:i+""}(i))in n?Object.defineProperty(n,i,{value:a,enumerable:!0,configurable:!0,writable:!0}):n[i]=a,n}var i=[],a={},u={};function e(n){for(var i=[],a=n.length,u=[],e=0;a>=e;e++)u.push(!0);return o(0,n,[],i,u),i}function o(n,a,u,e,r){var t=a.length;if(n!==t)for(var g=function(){var t=a.substring(n,h+1),g=!1;if(i.some((function(n){return 0===n.indexOf(t)}))&&!a[h+1]&&r[h+1]){if(1===t.length)u.push(t);else{var f=[];i.forEach((function(n){0===n.indexOf(t)&&f.push(n)})),u.push(f)}g=!0}else-1!==i.indexOf(t)&&r[h+1]&&(u.push(t),g=!0);if(g){var l=e.length;o(h+1,a,u,e,r),e.length===l&&(r[h+1]=!1),u.pop()}},h=n;t>h;h++)g();else e.push(u.join(" "))}function r(n,i,a,u){if(!n)return!1;var e=n.split(" ");return e.forEach((function(n){n.length>0&&u&&e.push(n.charAt(0))})),a?e.some((function(n){return 0===n.indexOf(i)})):-1!==e.indexOf(i)}var t=["lü","lüe","nü","nüe"];function g(i,o){if(!i||!o)return!1;i=i.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g,""),o=function(n){var i=n.replace(/\s+/g,"").toLowerCase();return t.some((function(n){return i.includes(n)}))&&(i=i.replace("ü","v")),i.normalize("NFD").replace(/[\u0300-\u036f]/g,"")}(o);var r=i.indexOf(o);if(-1!==r)return[r,r+o.length-1];var g=h(i.split(""),[o.split("")],o);if(g)return g;var f,l,c=function(n){for(var i=[],u=0,e=n.length;e>u;u++){var o=n.charAt(u);i.push(a[o]||o)}return i}(i);return h(c,u[o]||(l=[],e(f=o).forEach((function(n){var i=n.split(" "),a=i.length-1;i[a].indexOf(",")?i[a].split(",").forEach((function(n){i.splice(a,1,n),l.push(JSON.parse(JSON.stringify(i)))})):l.push(i)})),0!==l.length&&l[0].length===f.length||l.push(f.split("")),u=n({},f,l),l),o)}function h(n,i,a){for(var u=0;n.length>u;u++)for(var e=0;i.length>e;e++){var o=i[e],t=o.length,g=t===a.length,h=!0,f=0,l=0,c=0;if(n.length>=t){for(;o.length>f;f++)if(0===f&&" "===n[u+f+l])l+=1,f-=1;else if(" "===n[u+f+c])c+=1,f-=1;else if(!r(n[u+f+c],o[f],!n[u+f+1]||!o[f+1],g)){h=!1;break}if(h)return[u+l,c+u+f-1]}}return!1}var f={match:function(n){var u={},e=["ju","jun","jue","juan","qu","qun","que","xuan","xu","xue","yu","yuan","yue","yun","nve","lve"],o=["lv","lve","nv","nve"];return Object.keys(n).forEach((function(a){if(u[a]=n[a],i.push(a),e.includes(a)){var r=-1!==(t=a).indexOf("u")?t.replace("u","v"):t.replace("v","u");u[r]=n[a],i.push(r)}var t;if(o.includes(a)){var g=a.replace("v","ü");u[g]=n[a],i.push(g)}})),a=function(n){var i={};for(var a in n)for(var u=n[a],e=0,o=u.length;o>e;e++)i[u[e]]=i[u[e]]?i[u[e]]+" "+a:a;return i}(u),g}({a:"阿啊呵腌嗄吖锕",e:"额阿俄恶鹅遏鄂厄饿峨扼娥鳄哦蛾噩愕讹锷垩婀鹗萼谔莪腭锇颚呃阏屙苊轭",ai:"爱埃艾碍癌哀挨矮隘蔼唉皑哎霭捱暧嫒嗳瑷嗌锿砹",ei:"诶",xi:"系西席息希习吸喜细析戏洗悉锡溪惜稀袭夕洒晰昔牺腊烯熙媳栖膝隙犀蹊硒兮熄曦禧嬉玺奚汐徙羲铣淅嘻歙熹矽蟋郗唏皙隰樨浠忾蜥檄郄翕阋鳃舾屣葸螅咭粞觋欷僖醯鼷裼穸饩舄禊诶菥蓰",yi:"一以已意议义益亿易医艺食依移衣异伊仪宜射遗疑毅谊亦疫役忆抑尾乙译翼蛇溢椅沂泄逸蚁夷邑怡绎彝裔姨熠贻矣屹颐倚诣胰奕翌疙弈轶蛾驿壹猗臆弋铱旖漪迤佚翊诒怿痍懿饴峄揖眙镒仡黟肄咿翳挹缢呓刈咦嶷羿钇殪荑薏蜴镱噫癔苡悒嗌瘗衤佾埸圯舣酏劓",an:"安案按岸暗鞍氨俺胺铵谙庵黯鹌桉埯犴揞厂广",han:"厂汉韩含旱寒汗涵函喊憾罕焊翰邯撼瀚憨捍酣悍鼾邗颔蚶晗菡旰顸犴焓撖",ang:"昂仰盎肮",ao:"奥澳傲熬凹鳌敖遨鏖袄坳翱嗷拗懊岙螯骜獒鏊艹媪廒聱",wa:"瓦挖娃洼袜蛙凹哇佤娲呙腽",yu:"于与育余预域予遇奥语誉玉鱼雨渔裕愈娱欲吁舆宇羽逾豫郁寓吾狱喻御浴愉禹俞邪榆愚渝尉淤虞屿峪粥驭瑜禺毓钰隅芋熨瘀迂煜昱汩於臾盂聿竽萸妪腴圄谕觎揄龉谀俣馀庾妤瘐鬻欤鹬阈嵛雩鹆圉蜮伛纡窬窳饫蓣狳肀舁蝓燠",niu:"牛纽扭钮拗妞忸狃",o:"哦噢喔",ba:"把八巴拔伯吧坝爸霸罢芭跋扒叭靶疤笆耙鲅粑岜灞钯捌菝魃茇",pa:"怕帕爬扒趴琶啪葩耙杷钯筢",pi:"被批副否皮坏辟啤匹披疲罢僻毗坯脾譬劈媲屁琵邳裨痞癖陂丕枇噼霹吡纰砒铍淠郫埤濞睥芘蚍圮鼙罴蜱疋貔仳庀擗甓陴",bi:"比必币笔毕秘避闭佛辟壁弊彼逼碧鼻臂蔽拂泌璧庇痹毙弼匕鄙陛裨贲敝蓖吡篦纰俾铋毖筚荸薜婢哔跸濞秕荜愎睥妣芘箅髀畀滗狴萆嬖襞舭",bai:"百白败摆伯拜柏佰掰呗擘捭稗",bo:"波博播勃拨薄佛伯玻搏柏泊舶剥渤卜驳簿脖膊簸菠礴箔铂亳钵帛擘饽跛钹趵檗啵鹁擗踣",bei:"北被备倍背杯勃贝辈悲碑臂卑悖惫蓓陂钡狈呗焙碚褙庳鞴孛鹎邶鐾",ban:"办版半班般板颁伴搬斑扮拌扳瓣坂阪绊钣瘢舨癍",pan:"判盘番潘攀盼拚畔胖叛拌蹒磐爿蟠泮袢襻丬",bin:"份宾频滨斌彬濒殡缤鬓槟摈膑玢镔豳髌傧",bang:"帮邦彭旁榜棒膀镑绑傍磅蚌谤梆浜蒡",pang:"旁庞乓磅螃彷滂逄耪胖",beng:"泵崩蚌蹦迸绷甭嘣甏堋",bao:"报保包宝暴胞薄爆炮饱抱堡剥鲍曝葆瀑豹刨褒雹孢苞煲褓趵鸨龅勹",bu:"不部步布补捕堡埔卜埠簿哺怖钚卟瓿逋晡醭钸",pu:"普暴铺浦朴堡葡谱埔扑仆蒲曝瀑溥莆圃璞濮菩蹼匍噗氆攵镨攴镤",mian:"面棉免绵缅勉眠冕娩腼渑湎沔黾宀眄",po:"破繁坡迫颇朴泊婆泼魄粕鄱珀陂叵笸泺皤钋钷",fan:"反范犯繁饭泛翻凡返番贩烦拚帆樊藩矾梵蕃钒幡畈蘩蹯燔",fu:"府服副负富复福夫妇幅付扶父符附腐赴佛浮覆辅傅伏抚赋辐腹弗肤阜袱缚甫氟斧孚敷俯拂俘咐腑孵芙涪釜脯茯馥宓绂讣呋罘麸蝠匐芾蜉跗凫滏蝮驸绋蚨砩桴赙菔呒趺苻拊阝鲋怫稃郛莩幞祓艴黻黼鳆",ben:"本奔苯笨夯贲锛畚坌",feng:"风丰封峰奉凤锋冯逢缝蜂枫疯讽烽俸沣酆砜葑唪",bian:"变便边编遍辩鞭辨贬匾扁卞汴辫砭苄蝙鳊弁窆笾煸褊碥忭缏",pian:"便片篇偏骗翩扁骈胼蹁谝犏缏",zhen:"镇真针圳振震珍阵诊填侦臻贞枕桢赈祯帧甄斟缜箴疹砧榛鸩轸稹溱蓁胗椹朕畛浈",biao:"表标彪镖裱飚膘飙镳婊骠飑杓髟鳔灬瘭",piao:"票朴漂飘嫖瓢剽缥殍瞟骠嘌莩螵",huo:"和活或货获火伙惑霍祸豁嚯藿锪蠖钬耠镬夥灬劐攉",bie:"别鳖憋瘪蹩",min:"民敏闽闵皿泯岷悯珉抿黾缗玟愍苠鳘",fen:"分份纷奋粉氛芬愤粪坟汾焚酚吩忿棼玢鼢瀵偾鲼",bing:"并病兵冰屏饼炳秉丙摒柄槟禀枋邴冫",geng:"更耕颈庚耿梗埂羹哽赓绠鲠",fang:"方放房防访纺芳仿坊妨肪邡舫彷枋鲂匚钫",xian:"现先县见线限显险献鲜洗宪纤陷闲贤仙衔掀咸嫌掺羡弦腺痫娴舷馅酰铣冼涎暹籼锨苋蚬跹岘藓燹鹇氙莶霰跣猃彡祆筅",fou:"不否缶",ca:"拆擦嚓礤",cha:"查察差茶插叉刹茬楂岔诧碴嚓喳姹杈汊衩搽槎镲苴檫馇锸猹",cai:"才采财材菜彩裁蔡猜踩睬",can:"参残餐灿惨蚕掺璨惭粲孱骖黪",shen:"信深参身神什审申甚沈伸慎渗肾绅莘呻婶娠砷蜃哂椹葚吲糁渖诜谂矧胂",cen:"参岑涔",san:"三参散伞叁糁馓毵",cang:"藏仓苍沧舱臧伧",zang:"藏脏葬赃臧奘驵",chen:"称陈沈沉晨琛臣尘辰衬趁忱郴宸谌碜嗔抻榇伧谶龀肜",cao:"草操曹槽糙嘈漕螬艚屮",ce:"策测册侧厕栅恻",ze:"责则泽择侧咋啧仄箦赜笮舴昃迮帻",zhai:"债择齐宅寨侧摘窄斋祭翟砦瘵哜",dao:"到道导岛倒刀盗稻蹈悼捣叨祷焘氘纛刂帱忉",ceng:"层曾蹭噌",zha:"查扎炸诈闸渣咋乍榨楂札栅眨咤柞喳喋铡蚱吒怍砟揸痄哳齄",chai:"差拆柴钗豺侪虿瘥",ci:"次此差词辞刺瓷磁兹慈茨赐祠伺雌疵鹚糍呲粢",zi:"资自子字齐咨滋仔姿紫兹孜淄籽梓鲻渍姊吱秭恣甾孳訾滓锱辎趑龇赀眦缁呲笫谘嵫髭茈粢觜耔",cuo:"措错磋挫搓撮蹉锉厝嵯痤矬瘥脞鹾",chan:"产单阐崭缠掺禅颤铲蝉搀潺蟾馋忏婵孱觇廛谄谗澶骣羼躔蒇冁",shan:"山单善陕闪衫擅汕扇掺珊禅删膳缮赡鄯栅煽姗跚鳝嬗潸讪舢苫疝掸膻钐剡蟮芟埏彡骟",zhan:"展战占站崭粘湛沾瞻颤詹斩盏辗绽毡栈蘸旃谵搌",xin:"新心信辛欣薪馨鑫芯锌忻莘昕衅歆囟忄镡",lian:"联连练廉炼脸莲恋链帘怜涟敛琏镰濂楝鲢殓潋裢裣臁奁莶蠊蔹",chang:"场长厂常偿昌唱畅倡尝肠敞倘猖娼淌裳徜昶怅嫦菖鲳阊伥苌氅惝鬯",zhang:"长张章障涨掌帐胀彰丈仗漳樟账杖璋嶂仉瘴蟑獐幛鄣嫜",chao:"超朝潮炒钞抄巢吵剿绰嘲晁焯耖怊",zhao:"着照招找召朝赵兆昭肇罩钊沼嘲爪诏濯啁棹笊",zhou:"调州周洲舟骤轴昼宙粥皱肘咒帚胄绉纣妯啁诌繇碡籀酎荮",che:"车彻撤尺扯澈掣坼砗屮",ju:"车局据具举且居剧巨聚渠距句拒俱柜菊拘炬桔惧矩鞠驹锯踞咀瞿枸掬沮莒橘飓疽钜趄踽遽琚龃椐苣裾榘狙倨榉苴讵雎锔窭鞫犋屦醵",cheng:"成程城承称盛抢乘诚呈净惩撑澄秤橙骋逞瞠丞晟铛埕塍蛏柽铖酲裎枨",rong:"容荣融绒溶蓉熔戎榕茸冗嵘肜狨蝾",sheng:"生声升胜盛乘圣剩牲甸省绳笙甥嵊晟渑眚",deng:"等登邓灯澄凳瞪蹬噔磴嶝镫簦戥",zhi:"制之治质职只志至指织支值知识直致执置止植纸拓智殖秩旨址滞氏枝芝脂帜汁肢挚稚酯掷峙炙栉侄芷窒咫吱趾痔蜘郅桎雉祉郦陟痣蛭帙枳踯徵胝栀贽祗豸鸷摭轵卮轾彘觯絷跖埴夂黹忮骘膣踬",zheng:"政正证争整征郑丁症挣蒸睁铮筝拯峥怔诤狰徵钲",tang:"堂唐糖汤塘躺趟倘棠烫淌膛搪镗傥螳溏帑羰樘醣螗耥铴瑭",chi:"持吃池迟赤驰尺斥齿翅匙痴耻炽侈弛叱啻坻眙嗤墀哧茌豉敕笞饬踟蚩柢媸魑篪褫彳鸱螭瘛眵傺",shi:"是时实事市十使世施式势视识师史示石食始士失适试什泽室似诗饰殖释驶氏硕逝湿蚀狮誓拾尸匙仕柿矢峙侍噬嗜栅拭嘘屎恃轼虱耆舐莳铈谥炻豕鲥饣螫酾筮埘弑礻蓍鲺贳",qi:"企其起期气七器汽奇齐启旗棋妻弃揭枝歧欺骑契迄亟漆戚岂稽岐琦栖缉琪泣乞砌祁崎绮祺祈凄淇杞脐麒圻憩芪伎俟畦耆葺沏萋骐鳍綦讫蕲屺颀亓碛柒啐汔綮萁嘁蛴槭欹芑桤丌蜞",chuai:"揣踹啜搋膪",tuo:"托脱拓拖妥驼陀沱鸵驮唾椭坨佗砣跎庹柁橐乇铊沲酡鼍箨柝",duo:"多度夺朵躲铎隋咄堕舵垛惰哆踱跺掇剁柁缍沲裰哚隳",xue:"学血雪削薛穴靴谑噱鳕踅泶彐",chong:"重种充冲涌崇虫宠忡憧舂茺铳艟",chou:"筹抽绸酬愁丑臭仇畴稠瞅踌惆俦瘳雠帱",qiu:"求球秋丘邱仇酋裘龟囚遒鳅虬蚯泅楸湫犰逑巯艽俅蝤赇鼽糗",xiu:"修秀休宿袖绣臭朽锈羞嗅岫溴庥馐咻髹鸺貅",chu:"出处础初助除储畜触楚厨雏矗橱锄滁躇怵绌搐刍蜍黜杵蹰亍樗憷楮",tuan:"团揣湍疃抟彖",zhui:"追坠缀揣椎锥赘惴隹骓缒",chuan:"传川船穿串喘椽舛钏遄氚巛舡",zhuan:"专转传赚砖撰篆馔啭颛",yuan:"元员院原源远愿园援圆缘袁怨渊苑宛冤媛猿垣沅塬垸鸳辕鸢瑗圜爰芫鼋橼螈眢箢掾",cuan:"窜攒篡蹿撺爨汆镩",chuang:"创床窗闯幢疮怆",zhuang:"装状庄壮撞妆幢桩奘僮戆",chui:"吹垂锤炊椎陲槌捶棰",chun:"春纯醇淳唇椿蠢鹑朐莼肫蝽",zhun:"准屯淳谆肫窀",cu:"促趋趣粗簇醋卒蹴猝蹙蔟殂徂",dun:"吨顿盾敦蹲墩囤沌钝炖盹遁趸砘礅",qu:"区去取曲趋渠趣驱屈躯衢娶祛瞿岖龋觑朐蛐癯蛆苣阒诎劬蕖蘧氍黢蠼璩麴鸲磲",xu:"需许续须序徐休蓄畜虚吁绪叙旭邪恤墟栩絮圩婿戌胥嘘浒煦酗诩朐盱蓿溆洫顼勖糈砉醑",chuo:"辍绰戳淖啜龊踔辶",zu:"组族足祖租阻卒俎诅镞菹",ji:"济机其技基记计系期际及集级几给积极己纪即继击既激绩急奇吉季齐疾迹鸡剂辑籍寄挤圾冀亟寂暨脊跻肌稽忌饥祭缉棘矶汲畸姬藉瘠骥羁妓讥稷蓟悸嫉岌叽伎鲫诘楫荠戟箕霁嵇觊麂畿玑笈犄芨唧屐髻戢佶偈笄跽蒺乩咭赍嵴虮掎齑殛鲚剞洎丌墼蕺彐芰哜",cong:"从丛匆聪葱囱琮淙枞骢苁璁",zong:"总从综宗纵踪棕粽鬃偬枞腙",cou:"凑辏腠楱",cui:"衰催崔脆翠萃粹摧璀瘁悴淬啐隹毳榱",wei:"为位委未维卫围违威伟危味微唯谓伪慰尾魏韦胃畏帷喂巍萎蔚纬潍尉渭惟薇苇炜圩娓诿玮崴桅偎逶倭猥囗葳隗痿猬涠嵬韪煨艉隹帏闱洧沩隈鲔軎",cun:"村存寸忖皴",zuo:"作做座左坐昨佐琢撮祚柞唑嘬酢怍笮阼胙",zuan:"钻纂攥缵躜",da:"大达打答搭沓瘩惮嗒哒耷鞑靼褡笪怛妲",dai:"大代带待贷毒戴袋歹呆隶逮岱傣棣怠殆黛甙埭诒绐玳呔迨",tai:"台太态泰抬胎汰钛苔薹肽跆邰鲐酞骀炱",ta:"他它她拓塔踏塌榻沓漯獭嗒挞蹋趿遢铊鳎溻闼",dan:"但单石担丹胆旦弹蛋淡诞氮郸耽殚惮儋眈疸澹掸膻啖箪聃萏瘅赕",lu:"路六陆录绿露鲁卢炉鹿禄赂芦庐碌麓颅泸卤潞鹭辘虏璐漉噜戮鲈掳橹轳逯渌蓼撸鸬栌氇胪镥簏舻辂垆",tan:"谈探坦摊弹炭坛滩贪叹谭潭碳毯瘫檀痰袒坍覃忐昙郯澹钽锬",ren:"人任认仁忍韧刃纫饪妊荏稔壬仞轫亻衽",jie:"家结解价界接节她届介阶街借杰洁截姐揭捷劫戒皆竭桔诫楷秸睫藉拮芥诘碣嗟颉蚧孑婕疖桀讦疥偈羯袷哜喈卩鲒骱",yan:"研严验演言眼烟沿延盐炎燕岩宴艳颜殷彦掩淹阎衍铅雁咽厌焰堰砚唁焉晏檐蜒奄俨腌妍谚兖筵焱偃闫嫣鄢湮赝胭琰滟阉魇酽郾恹崦芫剡鼹菸餍埏谳讠厣罨",dang:"当党档荡挡宕砀铛裆凼菪谠",tao:"套讨跳陶涛逃桃萄淘掏滔韬叨洮啕绦饕鼗",tiao:"条调挑跳迢眺苕窕笤佻啁粜髫铫祧龆蜩鲦",te:"特忑忒铽慝",de:"的地得德底锝",dei:"得",di:"的地第提低底抵弟迪递帝敌堤蒂缔滴涤翟娣笛棣荻谛狄邸嘀砥坻诋嫡镝碲骶氐柢籴羝睇觌",ti:"体提题弟替梯踢惕剔蹄棣啼屉剃涕锑倜悌逖嚏荑醍绨鹈缇裼",tui:"推退弟腿褪颓蜕忒煺",you:"有由又优游油友右邮尤忧幼犹诱悠幽佑釉柚铀鱿囿酉攸黝莠猷蝣疣呦蚴莸莜铕宥繇卣牖鼬尢蚰侑",dian:"电点店典奠甸碘淀殿垫颠滇癫巅惦掂癜玷佃踮靛钿簟坫阽",tian:"天田添填甜甸恬腆佃舔钿阗忝殄畋栝掭",zhu:"主术住注助属逐宁著筑驻朱珠祝猪诸柱竹铸株瞩嘱贮煮烛苎褚蛛拄铢洙竺蛀渚伫杼侏澍诛茱箸炷躅翥潴邾槠舳橥丶瘃麈疰",nian:"年念酿辗碾廿捻撵拈蔫鲶埝鲇辇黏",diao:"调掉雕吊钓刁貂凋碉鲷叼铫铞",yao:"要么约药邀摇耀腰遥姚窑瑶咬尧钥谣肴夭侥吆疟妖幺杳舀窕窈曜鹞爻繇徭轺铫鳐崾珧",die:"跌叠蝶迭碟爹谍牒耋佚喋堞瓞鲽垤揲蹀",she:"设社摄涉射折舍蛇拾舌奢慑赦赊佘麝歙畲厍猞揲滠",ye:"业也夜叶射野液冶喝页爷耶邪咽椰烨掖拽曳晔谒腋噎揶靥邺铘揲",xie:"些解协写血叶谢械鞋胁斜携懈契卸谐泄蟹邪歇泻屑挟燮榭蝎撷偕亵楔颉缬邂鲑瀣勰榍薤绁渫廨獬躞",zhe:"喆这者着著浙折哲蔗遮辙辄柘锗褶蜇蛰鹧谪赭摺乇磔螫",ding:"定订顶丁鼎盯钉锭叮仃铤町酊啶碇腚疔玎耵",diu:"丢铥",ting:"听庭停厅廷挺亭艇婷汀铤烃霆町蜓葶梃莛",dong:"动东董冬洞懂冻栋侗咚峒氡恫胴硐垌鸫岽胨",tong:"同通统童痛铜桶桐筒彤侗佟潼捅酮砼瞳恸峒仝嗵僮垌茼",zhong:"中重种众终钟忠仲衷肿踵冢盅蚣忪锺舯螽夂",dou:"都斗读豆抖兜陡逗窦渎蚪痘蔸钭篼",du:"度都独督读毒渡杜堵赌睹肚镀渎笃竺嘟犊妒牍蠹椟黩芏髑",duan:"断段短端锻缎煅椴簖",dui:"对队追敦兑堆碓镦怼憝",rui:"瑞兑锐睿芮蕊蕤蚋枘",yue:"月说约越乐跃兑阅岳粤悦曰钥栎钺樾瀹龠哕刖",tun:"吞屯囤褪豚臀饨暾氽",hui:"会回挥汇惠辉恢徽绘毁慧灰贿卉悔秽溃荟晖彗讳诲珲堕诙蕙晦睢麾烩茴喙桧蛔洄浍虺恚蟪咴隳缋哕",wu:"务物无五武午吴舞伍污乌误亡恶屋晤悟吾雾芜梧勿巫侮坞毋诬呜钨邬捂鹜兀婺妩於戊鹉浯蜈唔骛仵焐芴鋈庑鼯牾怃圬忤痦迕杌寤阢",ya:"亚压雅牙押鸭呀轧涯崖邪芽哑讶鸦娅衙丫蚜碣垭伢氩桠琊揠吖睚痖疋迓岈砑",he:"和合河何核盖贺喝赫荷盒鹤吓呵苛禾菏壑褐涸阂阖劾诃颌嗬貉曷翮纥盍",wo:"我握窝沃卧挝涡斡渥幄蜗喔倭莴龌肟硪",en:"恩摁蒽",n:"嗯唔",er:"而二尔儿耳迩饵洱贰铒珥佴鸸鲕",fa:"发法罚乏伐阀筏砝垡珐",quan:"全权券泉圈拳劝犬铨痊诠荃醛蜷颧绻犭筌鬈悛辁畎",fei:"费非飞肥废菲肺啡沸匪斐蜚妃诽扉翡霏吠绯腓痱芾淝悱狒榧砩鲱篚镄",pei:"配培坏赔佩陪沛裴胚妃霈淠旆帔呸醅辔锫",ping:"平评凭瓶冯屏萍苹乒坪枰娉俜鲆",fo:"佛",hu:"和护户核湖互乎呼胡戏忽虎沪糊壶葫狐蝴弧瑚浒鹄琥扈唬滹惚祜囫斛笏芴醐猢怙唿戽槲觳煳鹕冱瓠虍岵鹱烀轷",ga:"夹咖嘎尬噶旮伽尕钆尜",ge:"个合各革格歌哥盖隔割阁戈葛鸽搁胳舸疙铬骼蛤咯圪镉颌仡硌嗝鬲膈纥袼搿塥哿虼",ha:"哈蛤铪",xia:"下夏峡厦辖霞夹虾狭吓侠暇遐瞎匣瑕唬呷黠硖罅狎瘕柙",gai:"改该盖概溉钙丐芥赅垓陔戤",hai:"海还害孩亥咳骸骇氦嗨胲醢",gan:"干感赶敢甘肝杆赣乾柑尴竿秆橄矸淦苷擀酐绀泔坩旰疳澉",gang:"港钢刚岗纲冈杠缸扛肛罡戆筻",jiang:"将强江港奖讲降疆蒋姜浆匠酱僵桨绛缰犟豇礓洚茳糨耩",hang:"行航杭巷夯吭桁沆绗颃",gong:"工公共供功红贡攻宫巩龚恭拱躬弓汞蚣珙觥肱廾",hong:"红宏洪轰虹鸿弘哄烘泓訇蕻闳讧荭黉薨",guang:"广光逛潢犷胱咣桄",qiong:"穷琼穹邛茕筇跫蛩銎",gao:"高告搞稿膏糕镐皋羔锆杲郜睾诰藁篙缟槁槔",hao:"好号毫豪耗浩郝皓昊皋蒿壕灏嚎濠蚝貉颢嗥薅嚆",li:"理力利立里李历例离励礼丽黎璃厉厘粒莉梨隶栗荔沥犁漓哩狸藜罹篱鲤砺吏澧俐骊溧砾莅锂笠蠡蛎痢雳俪傈醴栎郦俚枥喱逦娌鹂戾砬唳坜疠蜊黧猁鬲粝蓠呖跞疬缡鲡鳢嫠詈悝苈篥轹",jia:"家加价假佳架甲嘉贾驾嫁夹稼钾挟拮迦伽颊浃枷戛荚痂颉镓笳珈岬胛袈郏葭袷瘕铗跏蛱恝哿",luo:"啰落罗络洛逻螺锣骆萝裸漯烙摞骡咯箩珞捋荦硌雒椤镙跞瘰泺脶猡倮蠃",ke:"可科克客刻课颗渴壳柯棵呵坷恪苛咳磕珂稞瞌溘轲窠嗑疴蝌岢铪颏髁蚵缂氪骒钶锞",qia:"卡恰洽掐髂袷咭葜",gei:"给",gen:"根跟亘艮哏茛",hen:"很狠恨痕哏",gou:"构购够句沟狗钩拘勾苟垢枸篝佝媾诟岣彀缑笱鞲觏遘",kou:"口扣寇叩抠佝蔻芤眍筘",gu:"股古顾故固鼓骨估谷贾姑孤雇辜菇沽咕呱锢钴箍汩梏痼崮轱鸪牯蛊诂毂鹘菰罟嘏臌觚瞽蛄酤牿鲴",pai:"牌排派拍迫徘湃俳哌蒎",gua:"括挂瓜刮寡卦呱褂剐胍诖鸹栝呙",tou:"钭投头透偷愉骰亠",guai:"怪拐乖",kuai:"会快块筷脍蒯侩浍郐蒉狯哙",guan:"关管观馆官贯冠惯灌罐莞纶棺斡矜倌鹳鳏盥掼涫",wan:"万完晚湾玩碗顽挽弯蔓丸莞皖宛婉腕蜿惋烷琬畹豌剜纨绾脘菀芄箢",ne:"呢哪呐讷疒",gui:"规贵归轨桂柜圭鬼硅瑰跪龟匮闺诡癸鳜桧皈鲑刽晷傀眭妫炅庋簋刿宄匦",jun:"军均俊君峻菌竣钧骏龟浚隽郡筠皲麇捃",jiong:"窘炯迥炅冂扃",jue:"决绝角觉掘崛诀獗抉爵嚼倔厥蕨攫珏矍蹶谲镢鳜噱桷噘撅橛孓觖劂爝",gun:"滚棍辊衮磙鲧绲丨",hun:"婚混魂浑昏棍珲荤馄诨溷阍",guo:"国过果郭锅裹帼涡椁囗蝈虢聒埚掴猓崞蜾呙馘",hei:"黑嘿嗨",kan:"看刊勘堪坎砍侃嵌槛瞰阚龛戡凵莰",heng:"衡横恒亨哼珩桁蘅",mo:"万没么模末冒莫摩墨默磨摸漠脉膜魔沫陌抹寞蘑摹蓦馍茉嘿谟秣蟆貉嫫镆殁耱嬷麽瘼貊貘",peng:"鹏朋彭膨蓬碰苹棚捧亨烹篷澎抨硼怦砰嘭蟛堋",hou:"后候厚侯猴喉吼逅篌糇骺後鲎瘊堠",hua:"化华划话花画滑哗豁骅桦猾铧砉",huai:"怀坏淮徊槐踝",huan:"还环换欢患缓唤焕幻痪桓寰涣宦垸洹浣豢奂郇圜獾鲩鬟萑逭漶锾缳擐",xun:"讯训迅孙寻询循旬巡汛勋逊熏徇浚殉驯鲟薰荀浔洵峋埙巽郇醺恂荨窨蕈曛獯",huang:"黄荒煌皇凰慌晃潢谎惶簧璜恍幌湟蝗磺隍徨遑肓篁鳇蟥癀",nai:"能乃奶耐奈鼐萘氖柰佴艿",luan:"乱卵滦峦鸾栾銮挛孪脔娈",qie:"切且契窃茄砌锲怯伽惬妾趄挈郄箧慊",jian:"建间件见坚检健监减简艰践兼鉴键渐柬剑尖肩舰荐箭浅剪俭碱茧奸歼拣捡煎贱溅槛涧堑笺谏饯锏缄睑謇蹇腱菅翦戬毽笕犍硷鞯牮枧湔鲣囝裥踺搛缣鹣蒹谫僭戋趼楗",nan:"南难男楠喃囡赧腩囝蝻",qian:"前千钱签潜迁欠纤牵浅遣谦乾铅歉黔谴嵌倩钳茜虔堑钎骞阡掮钤扦芊犍荨仟芡悭缱佥愆褰凵肷岍搴箝慊椠",qiang:"强抢疆墙枪腔锵呛羌蔷襁羟跄樯戕嫱戗炝镪锖蜣",xiang:"向项相想乡象响香降像享箱羊祥湘详橡巷翔襄厢镶飨饷缃骧芗庠鲞葙蟓",jiao:"教交较校角觉叫脚缴胶轿郊焦骄浇椒礁佼蕉娇矫搅绞酵剿嚼饺窖跤蛟侥狡姣皎茭峤铰醮鲛湫徼鹪僬噍艽挢敫",zhuo:"着著缴桌卓捉琢灼浊酌拙茁涿镯淖啄濯焯倬擢斫棹诼浞禚",qiao:"桥乔侨巧悄敲俏壳雀瞧翘窍峭锹撬荞跷樵憔鞘橇峤诮谯愀鞒硗劁缲",xiao:"小效销消校晓笑肖削孝萧俏潇硝宵啸嚣霄淆哮筱逍姣箫骁枭哓绡蛸崤枵魈",si:"司四思斯食私死似丝饲寺肆撕泗伺嗣祀厮驷嘶锶俟巳蛳咝耜笥纟糸鸶缌澌姒汜厶兕",kai:"开凯慨岂楷恺揩锴铠忾垲剀锎蒈",jin:"进金今近仅紧尽津斤禁锦劲晋谨筋巾浸襟靳瑾烬缙钅矜觐堇馑荩噤廑妗槿赆衿卺",qin:"亲勤侵秦钦琴禽芹沁寝擒覃噙矜嗪揿溱芩衾廑锓吣檎螓",jing:"经京精境竞景警竟井惊径静劲敬净镜睛晶颈荆兢靖泾憬鲸茎腈菁胫阱旌粳靓痉箐儆迳婧肼刭弪獍",ying:"应营影英景迎映硬盈赢颖婴鹰荧莹樱瑛蝇萦莺颍膺缨瀛楹罂荥萤鹦滢蓥郢茔嘤璎嬴瘿媵撄潆",jiu:"就究九酒久救旧纠舅灸疚揪咎韭玖臼柩赳鸠鹫厩啾阄桕僦鬏",zui:"最罪嘴醉咀蕞觜",juan:"卷捐圈眷娟倦绢隽镌涓鹃鄄蠲狷锩桊",suan:"算酸蒜狻",yun:"员运云允孕蕴韵酝耘晕匀芸陨纭郧筠恽韫郓氲殒愠昀菀狁",qun:"群裙逡麇",ka:"卡喀咖咔咯佧胩",kang:"康抗扛慷炕亢糠伉钪闶",keng:"坑铿吭",kao:"考靠烤拷铐栲尻犒",ken:"肯垦恳啃龈裉",yin:"因引银印音饮阴隐姻殷淫尹荫吟瘾寅茵圻垠鄞湮蚓氤胤龈窨喑铟洇狺夤廴吲霪茚堙",kong:"空控孔恐倥崆箜",ku:"苦库哭酷裤枯窟挎骷堀绔刳喾",kua:"跨夸垮挎胯侉",kui:"亏奎愧魁馈溃匮葵窥盔逵睽馗聩喟夔篑岿喹揆隗傀暌跬蒉愦悝蝰",kuan:"款宽髋",kuang:"况矿框狂旷眶匡筐邝圹哐贶夼诳诓纩",que:"确却缺雀鹊阙瘸榷炔阕悫",kun:"困昆坤捆琨锟鲲醌髡悃阃",kuo:"扩括阔廓蛞",la:"拉落垃腊啦辣蜡喇剌旯砬邋瘌",lai:"来莱赖睐徕籁涞赉濑癞崃疠铼",lan:"兰览蓝篮栏岚烂滥缆揽澜拦懒榄斓婪阑褴罱啉谰镧漤",lin:"林临邻赁琳磷淋麟霖鳞凛拎遴蔺吝粼嶙躏廪檩啉辚膦瞵懔",lang:"浪朗郎廊狼琅榔螂阆锒莨啷蒗稂",liang:"量两粮良辆亮梁凉谅粱晾靓踉莨椋魉墚",lao:"老劳落络牢捞涝烙姥佬崂唠酪潦痨醪铑铹栳耢",mu:"目模木亩幕母牧莫穆姆墓慕牟牡募睦缪沐暮拇姥钼苜仫毪坶",le:"了乐勒肋叻鳓嘞仂泐",lei:"类累雷勒泪蕾垒磊擂镭肋羸耒儡嫘缧酹嘞诔檑",sui:"随岁虽碎尿隧遂髓穗绥隋邃睢祟濉燧谇眭荽",lie:"列烈劣裂猎冽咧趔洌鬣埒捩躐",leng:"冷愣棱楞塄",ling:"领令另零灵龄陵岭凌玲铃菱棱伶羚苓聆翎泠瓴囹绫呤棂蛉酃鲮柃",lia:"俩",liao:"了料疗辽廖聊寥缪僚燎缭撂撩嘹潦镣寮蓼獠钌尥鹩",liu:"流刘六留柳瘤硫溜碌浏榴琉馏遛鎏骝绺镏旒熘鹨锍",lun:"论轮伦仑纶沦抡囵",lv:"率律旅绿虑履吕铝屡氯缕滤侣驴榈闾偻褛捋膂稆",lou:"楼露漏陋娄搂篓喽镂偻瘘髅耧蝼嵝蒌",mao:"贸毛矛冒貌茂茅帽猫髦锚懋袤牦卯铆耄峁瑁蟊茆蝥旄泖昴瞀",long:"龙隆弄垄笼拢聋陇胧珑窿茏咙砻垅泷栊癃",nong:"农浓弄脓侬哝",shuang:"双爽霜孀泷",shu:"术书数属树输束述署熟殊蔬舒疏鼠淑叔暑枢墅俞曙抒竖蜀薯梳戍恕孰沭赎庶漱塾倏澍纾姝菽黍腧秫毹殳疋摅",shuai:"率衰帅摔甩蟀",lve:"略掠锊",ma:"么马吗摩麻码妈玛嘛骂抹蚂唛蟆犸杩",me:"么麽",mai:"买卖麦迈脉埋霾荬劢",man:"满慢曼漫埋蔓瞒蛮鳗馒幔谩螨熳缦镘颟墁鞔嫚",mi:"米密秘迷弥蜜谜觅靡泌眯麋猕谧咪糜宓汨醚嘧弭脒冖幂祢縻蘼芈糸敉",men:"们门闷瞒汶扪焖懑鞔钔",mang:"忙盲茫芒氓莽蟒邙硭漭",meng:"蒙盟梦猛孟萌氓朦锰檬勐懵蟒蜢虻黾蠓艨甍艋瞢礞",miao:"苗秒妙描庙瞄缪渺淼藐缈邈鹋杪眇喵",mou:"某谋牟缪眸哞鍪蛑侔厶",miu:"缪谬",mei:"美没每煤梅媒枚妹眉魅霉昧媚玫酶镁湄寐莓袂楣糜嵋镅浼猸鹛",wen:"文问闻稳温纹吻蚊雯紊瘟汶韫刎璺玟阌",mie:"灭蔑篾乜咩蠛",ming:"明名命鸣铭冥茗溟酩瞑螟暝",na:"内南那纳拿哪娜钠呐捺衲镎肭",nei:"内那哪馁",nuo:"难诺挪娜糯懦傩喏搦锘",ruo:"若弱偌箬",nang:"囊馕囔曩攮",nao:"脑闹恼挠瑙淖孬垴铙桡呶硇猱蛲",ni:"你尼呢泥疑拟逆倪妮腻匿霓溺旎昵坭铌鲵伲怩睨猊",nen:"嫩恁",neng:"能",nin:"您恁",niao:"鸟尿溺袅脲茑嬲",nie:"摄聂捏涅镍孽捻蘖啮蹑嗫臬镊颞乜陧",niang:"娘酿",ning:"宁凝拧泞柠咛狞佞聍甯",nu:"努怒奴弩驽帑孥胬",nv:"女钕衄恧",ru:"入如女乳儒辱汝茹褥孺濡蠕嚅缛溽铷洳薷襦颥蓐",nuan:"暖",nve:"虐疟",re:"热若惹喏",ou:"区欧偶殴呕禺藕讴鸥瓯沤耦怄",pao:"跑炮泡抛刨袍咆疱庖狍匏脬",pou:"剖掊裒",pen:"喷盆湓",pie:"瞥撇苤氕丿",pin:"品贫聘频拼拚颦姘嫔榀牝",se:"色塞瑟涩啬穑铯槭",qing:"情青清请亲轻庆倾顷卿晴氢擎氰罄磬蜻箐鲭綮苘黥圊檠謦",zan:"赞暂攒堑昝簪糌瓒錾趱拶",shao:"少绍召烧稍邵哨韶捎勺梢鞘芍苕劭艄筲杓潲",sao:"扫骚嫂梢缫搔瘙臊埽缲鳋",sha:"沙厦杀纱砂啥莎刹杉傻煞鲨霎嗄痧裟挲铩唼歃",xuan:"县选宣券旋悬轩喧玄绚渲璇炫萱癣漩眩暄煊铉楦泫谖痃碹揎镟儇",ran:"然染燃冉苒髯蚺",rang:"让壤攘嚷瓤穰禳",rao:"绕扰饶娆桡荛",reng:"仍扔",ri:"日",rou:"肉柔揉糅鞣蹂",ruan:"软阮朊",run:"润闰",sa:"萨洒撒飒卅仨脎",suo:"所些索缩锁莎梭琐嗦唆唢娑蓑羧挲桫嗍睃",sai:"思赛塞腮噻鳃",shui:"说水税谁睡氵",sang:"桑丧嗓搡颡磉",sen:"森",seng:"僧",shai:"筛晒",shang:"上商尚伤赏汤裳墒晌垧觞殇熵绱",xing:"行省星腥猩惺兴刑型形邢饧醒幸杏性姓陉荇荥擤悻硎",shou:"收手受首售授守寿瘦兽狩绶艏扌",shuo:"说数硕烁朔铄妁槊蒴搠",su:"速素苏诉缩塑肃俗宿粟溯酥夙愫簌稣僳谡涑蔌嗉觫",shua:"刷耍唰",shuan:"栓拴涮闩",shun:"顺瞬舜吮",song:"送松宋讼颂耸诵嵩淞怂悚崧凇忪竦菘",sou:"艘搜擞嗽嗖叟馊薮飕嗾溲锼螋瞍",sun:"损孙笋荪榫隼狲飧",teng:"腾疼藤滕誊",tie:"铁贴帖餮萜",tu:"土突图途徒涂吐屠兔秃凸荼钍菟堍酴",wai:"外歪崴",wang:"王望往网忘亡旺汪枉妄惘罔辋魍",weng:"翁嗡瓮蓊蕹",zhua:"抓挝爪",yang:"样养央阳洋扬杨羊详氧仰秧痒漾疡泱殃恙鸯徉佯怏炀烊鞅蛘",xiong:"雄兄熊胸凶匈汹芎",yo:"哟唷",yong:"用永拥勇涌泳庸俑踊佣咏雍甬镛臃邕蛹恿慵壅痈鳙墉饔喁",za:"杂扎咱砸咋匝咂拶",zai:"在再灾载栽仔宰哉崽甾",zao:"造早遭枣噪灶燥糟凿躁藻皂澡蚤唣",zei:"贼",zen:"怎谮",zeng:"增曾综赠憎锃甑罾缯",zhei:"这",zou:"走邹奏揍诹驺陬楱鄹鲰",zhuai:"转拽",zun:"尊遵鳟樽撙",dia:"嗲",nou:"耨"})};return f}));
diff --git a/assets/preview_dark.png b/assets/preview_dark.png
new file mode 100644
index 0000000000000000000000000000000000000000..78eb420d33ff0215e032500104fbde5b9b84ae5d
--- /dev/null
+++ b/assets/preview_dark.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a47b980857d9b64ff5eafaaca6c22b0a2de0dc07b33544cc5afdbdb0237d7edd
+size 413217
diff --git a/assets/preview_light.png b/assets/preview_light.png
new file mode 100644
index 0000000000000000000000000000000000000000..b607d470288e186b0e618fb5814ec67e4a3a166f
--- /dev/null
+++ b/assets/preview_light.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1f2c430eea96f46f35907ca5b2b73a39a6314cbab3df2e7d655856561dd7c9a6
+size 441564
diff --git a/assets/style.css b/assets/style.css
new file mode 100644
index 0000000000000000000000000000000000000000..28fcc1ea1e1922066d2745351a0a46f7139244aa
--- /dev/null
+++ b/assets/style.css
@@ -0,0 +1,33 @@
+/* ============================================
+   Menav Style System - Modular Entry Point
+   ============================================
+   
+   模块化 CSS 架构：
+   - 本文件作为入口，通过 @import 聚合所有模块
+   - esbuild bundle 模式会在构建时自动合并
+   - 模块导入顺序很重要！变量必须第一个导入
+   
+   ============================================ */
+
+/* 1. 基础层：变量和全局样式必须最先加载 */
+@import './styles/_variables.css';
+@import './styles/_base.css';
+@import './styles/_animations.css';
+
+/* 2. 布局层 */
+@import './styles/_layout.css';
+@import './styles/_sidebar.css';
+
+/* 3. 组件层 */
+@import './styles/_search.css';
+@import './styles/_cards.css';
+@import './styles/_modal.css';
+
+/* 4. 页面层 */
+@import './styles/_content.css';
+@import './styles/_dashboard.css';
+
+/* 5. 兜底样式（包含分类层级、GitHub热力图、响应式等）
+   注意：此文件包含所有未独立拆分的样式，部分选择器可能与上方模块重复
+   esbuild 会按导入顺序合并，后导入的样式优先级更高 */
+@import './styles/_main.css';
diff --git a/assets/styles/_animations.css b/assets/styles/_animations.css
new file mode 100644
index 0000000000000000000000000000000000000000..6745a5a189ccf796f45037e99553aecde9cd94d1
--- /dev/null
+++ b/assets/styles/_animations.css
@@ -0,0 +1,49 @@
+/* ============================================
+   Animations & Keyframes
+   ============================================ */
+
+@keyframes glow {
+  from {
+    filter: drop-shadow(0 0 2px rgba(118, 148, 185, 0.2))
+      drop-shadow(0 0 4px rgba(168, 85, 247, 0.2));
+  }
+
+  to {
+    filter: drop-shadow(0 0 4px rgba(118, 148, 185, 0.4))
+      drop-shadow(0 0 8px rgba(168, 85, 247, 0.4));
+  }
+}
+
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes modalFadeIn {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes modalContentShow {
+  from {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
diff --git a/assets/styles/_base.css b/assets/styles/_base.css
new file mode 100644
index 0000000000000000000000000000000000000000..dd8512d11ce5a591810520af5f42024b52e2ba64
--- /dev/null
+++ b/assets/styles/_base.css
@@ -0,0 +1,238 @@
+/* ============================================
+   Base Styles & Global Reset
+   ============================================ */
+
+/* 可访问性：视觉隐藏但保留屏幕阅读器可读 */
+.visually-hidden {
+  position: absolute !important;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* 主题切换按钮 - 调整为 iOS 风格 */
+.theme-toggle {
+  position: fixed;
+  bottom: var(--spacing-xl);
+  right: var(--spacing-xl);
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: var(--radius-lg);
+  background: rgba(var(--card-bg-rgb), 0.65);
+  border: 1px solid var(--border-color);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+  color: var(--text-color);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  transition: all var(--transition-normal);
+  transition-timing-function: var(--transition-bounce);
+  z-index: 100;
+  box-shadow: 0 4px 16px var(--shadow-color);
+}
+
+.theme-toggle:hover {
+  transform: translateY(-2px);
+  background: rgba(var(--card-bg-rgb), 0.75);
+  box-shadow: 0 6px 20px var(--shadow-color);
+  color: var(--accent-color);
+}
+
+.theme-toggle:active {
+  transform: translateY(0);
+  box-shadow: 0 2px 8px var(--shadow-color);
+}
+
+.theme-toggle i {
+  font-size: 18px;
+}
+
+/* 全局样式 */
+* {
+  margin: 0;
+  padding: 0;
+  box-sizing: border-box;
+}
+
+/* 全局 Focus Visible 样式 */
+:focus-visible {
+  outline: 2px solid var(--accent-color);
+  outline-offset: 2px;
+}
+
+/* 导航项 Focus 样式 */
+.nav-item:focus-visible,
+.submenu-item:focus-visible,
+.site-card:focus-visible,
+.theme-toggle:focus-visible,
+.category-toggle:focus-visible,
+.menu-toggle:focus-visible,
+.search-toggle:focus-visible {
+  outline: 2px solid var(--accent-color);
+  outline-offset: 2px;
+  z-index: 10;
+}
+
+/* 通用滚动条样式 */
+.custom-scrollbar {
+  scrollbar-width: thin;
+  /* Firefox */
+  scrollbar-color: var(--scrollbar-color) transparent;
+  /* Firefox */
+}
+
+/* Webkit滚动条样式（Chrome, Safari, Edge等） */
+.custom-scrollbar::-webkit-scrollbar {
+  width: 7px;
+  /* 统一滚动条宽度 */
+}
+
+.custom-scrollbar::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+.custom-scrollbar::-webkit-scrollbar-thumb {
+  background-color: var(--scrollbar-color);
+  /* 使用变量 */
+  border-radius: 4px;
+}
+
+.custom-scrollbar::-webkit-scrollbar-thumb:hover {
+  background-color: var(--scrollbar-hover-color);
+  /* 使用变量 */
+}
+
+/* 防止滚动条导致的布局偏移 */
+html {
+  overflow-y: hidden;
+  /* 改为hidden，移除强制显示的滚动条 */
+  scrollbar-width: thin;
+  /* Firefox */
+  /* 明确 rem 基准字号：便于用 rem 统一管理字号（1rem = 16px） */
+  font-size: 16px;
+}
+
+/* 搜索高亮样式 */
+.highlight {
+  background-color: var(--highlight-bg);
+  border-radius: var(--radius-sm);
+  padding: 0 2px;
+  font-weight: bold;
+  color: var(--text-color);
+}
+
+body {
+  font-family: var(
+    --font-body,
+    system-ui,
+    -apple-system,
+    'Segoe UI',
+    Roboto,
+    'Noto Sans',
+    'Helvetica Neue',
+    Arial,
+    sans-serif
+  );
+  font-weight: var(--font-weight-body, normal);
+  line-height: 1.6;
+  background-color: var(--bg-color);
+  color: var(--text-color);
+  min-height: var(--app-height, 100vh);
+  overflow: hidden;
+  /* 防止body滚动 */
+  padding-right: 0 !important;
+  /* 防止滚动条导致的布局偏移 */
+  transition:
+    background-color 0.3s ease,
+    color 0.3s ease;
+}
+
+/* 布局 */
+.layout {
+  display: flex;
+  min-height: var(--app-height, 100vh);
+  position: relative;
+  z-index: 1;
+  overflow: hidden;
+  /* 防止layout滚动 */
+  opacity: 0;
+  transition: opacity 0.3s ease;
+}
+
+/* 确保加载后立即显示 */
+body.loaded .layout {
+  opacity: 1;
+}
+
+/* 移动端基础样式 */
+.mobile-buttons {
+  display: none;
+  position: fixed;
+  top: var(--spacing-md);
+  top: calc(env(safe-area-inset-top) + var(--spacing-md));
+  left: 0;
+  right: 0;
+  width: 100%;
+  padding: 0 var(--spacing-md);
+  padding-left: calc(env(safe-area-inset-left) + var(--spacing-md));
+  padding-right: calc(env(safe-area-inset-right) + var(--spacing-md));
+  justify-content: space-between;
+  z-index: 910;
+  pointer-events: none;
+}
+
+.menu-toggle,
+.search-toggle {
+  background: var(--sidebar-bg);
+  border: none;
+  color: var(--text-color);
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: var(--radius-md);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  transition: all 0.25s var(--transition-bounce);
+  box-shadow: 0 2px 8px var(--shadow-color);
+  pointer-events: auto;
+}
+
+.menu-toggle:hover,
+.search-toggle:hover {
+  background: var(--secondary-bg);
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px var(--shadow-color);
+}
+
+.menu-toggle:active,
+.search-toggle:active {
+  transform: translateY(0);
+}
+
+/* 遮罩层 */
+.overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background: rgba(0, 0, 0, 0.5);
+  opacity: 0;
+  visibility: hidden;
+  transition: all 0.25s cubic-bezier(0.4, 0, 0.2, 1);
+  z-index: 950;
+  /* 调整遮罩层z-index，处于按钮与弹出面板之间 */
+}
+
+.overlay.active {
+  opacity: 1;
+  visibility: visible;
+}
diff --git a/assets/styles/_cards.css b/assets/styles/_cards.css
new file mode 100644
index 0000000000000000000000000000000000000000..d566978778ba847d729e0f24510ff29f7435e98d
--- /dev/null
+++ b/assets/styles/_cards.css
@@ -0,0 +1,1365 @@
+/* Cards Component */
+
+.site-card {
+  display: flex;
+  align-items: center;
+  padding: 1rem;
+  /* More generous padding */
+  gap: 0.8rem;
+  background-color: var(--site-card-bg-gradient-1);
+  /* Solid color */
+  border-radius: var(--radius-lg);
+  /* Larger radius */
+  text-decoration: none;
+  color: var(--text-color);
+  transition:
+    transform var(--transition-normal),
+    box-shadow var(--transition-normal),
+    background-color var(--transition-normal);
+  /* Spring transition */
+  position: relative;
+  overflow: hidden;
+  border: 0.5px solid var(--border-color);
+  /* Subtle separator */
+  /* Remove hard shadow by default for cleaner look, only adding on hover or using very subtle depth */
+}
+
+.site-card:hover {
+  transform: translateY(-2px) scale(1.01);
+  /* Subtle scale */
+  background-color: var(--site-card-hover-bg);
+  box-shadow: 0 8px 20px var(--shadow-color);
+  /* Deep soft shadow */
+  z-index: 2;
+  border-color: transparent;
+  /* Merge with shadow */
+}
+
+/* 分类样式 */
+.category {
+  background: linear-gradient(145deg, var(--card-bg-gradient-1), var(--card-bg-gradient-2));
+  border-radius: var(--radius-xl);
+  padding: 1rem;
+  margin: 0 auto 1.2rem auto;
+  width: 100%;
+  max-width: var(--page-max-width);
+  position: relative;
+  z-index: 1;
+  opacity: 1;
+  box-shadow: 0 4px 20px var(--shadow-color);
+  border: 1px solid var(--border-color);
+  transition:
+    background var(--transition-normal),
+    box-shadow var(--transition-normal);
+}
+
+/* 分类标题容器 */
+.category-header {
+  border-radius: var(--radius-md);
+  padding: 0.4rem;
+  margin: -0.4rem -0.4rem 0.8rem -0.4rem;
+  transition: all var(--transition-normal);
+}
+
+/* 标题前图标固定宽度：避免不同图标宽度导致标题文本不对齐 */
+.category-header [data-editable='category-name'] > i,
+.group-header [data-editable='group-name'] > i {
+  width: 1.25em;
+  min-width: 1.25em;
+  text-align: center;
+  flex: 0 0 1.25em;
+}
+
+/* 分组标题容器：与分类保持一致的悬浮动效基础 */
+.group-header {
+  border-radius: var(--radius-md);
+  transition: all var(--transition-normal);
+}
+
+/* 仅可折叠的标题显示交互态 */
+.category-header[data-toggle='category'],
+.group-header[data-toggle='group'] {
+  cursor: pointer;
+  user-select: none;
+}
+
+.category-header[data-toggle='category']:hover {
+  transform: translateY(-2px);
+  background: linear-gradient(145deg, rgba(255, 255, 255, 0.02), rgba(255, 255, 255, 0.01));
+}
+
+.group-header[data-toggle='group']:hover {
+  transform: translateY(-2px);
+  background: linear-gradient(145deg, rgba(255, 255, 255, 0.02), rgba(255, 255, 255, 0.01));
+}
+
+.category-header[data-toggle='category']:active {
+  transform: translateY(0);
+}
+
+.group-header[data-toggle='group']:active {
+  transform: translateY(0);
+}
+
+.category h2 {
+  font-size: 1.2rem;
+  margin-bottom: 0;
+  color: var(--text-bright);
+  display: flex;
+  align-items: center;
+  gap: 0.8rem;
+  letter-spacing: 0.3px;
+  transition: color 0.3s ease;
+}
+
+.category h2 > i {
+  color: var(--accent-color);
+  font-size: 1.3rem;
+  transition: all 0.3s ease;
+}
+
+.category-header[data-toggle='category']:hover h2 > i {
+  transform: scale(1.1);
+  color: var(--accent-hover);
+}
+
+/* 多层级嵌套样式 - 扁平化设计 */
+
+/* 通用重置：移除所有嵌套层级的卡片背景和边框 */
+.category-level-2,
+.category-level-3,
+.category-level-4,
+.group-level-3,
+.group-level-4 {
+  background: none;
+  border: none;
+  box-shadow: none;
+  padding: 0;
+  width: 100%;
+  margin: 0;
+}
+
+/* 嵌套层级指示线 (Hierarchy Indicator A) */
+.category-level-2::before,
+.category-level-3::before,
+.group-level-3::before,
+.category-level-4::before,
+.group-level-4::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background-color: var(--border-color);
+  opacity: 0.6;
+}
+
+/* 层级2: 子分类 */
+.category-level-2 {
+  margin-top: 0;
+  margin-bottom: 0;
+  padding-left: 1rem;
+  border-left: none;
+  position: relative;
+}
+
+/* 层级2: 标题样式 */
+.category-level-2 .category-header {
+  margin: 0 -0.5rem 1rem -0.5rem;
+  padding: 0.5rem;
+  background: none;
+  border-radius: var(--radius-md);
+}
+
+.category-level-2 .category-header h3 {
+  font-size: 1.1rem;
+  font-weight: 600;
+  color: var(--text-bright);
+  display: flex;
+  align-items: center;
+  gap: 0.8rem;
+}
+
+.category-level-2 .category-header h3 > i {
+  color: var(--accent-color);
+  font-size: 1.2rem;
+  opacity: 0.9;
+}
+
+/* 层级3: 分组 */
+.group-level-3,
+.category-level-3 {
+  margin-top: 0;
+  margin-bottom: 0;
+  padding-left: 1rem;
+  position: relative;
+}
+
+/* 层级3: 标题样式 */
+.group-level-3 .group-header,
+.category-level-3 .category-header {
+  margin: 0 0 0.8rem 0;
+  padding: 0.3rem 0;
+  background: none;
+}
+
+.group-level-3 .group-header h4,
+.category-level-3 .category-header h4 {
+  font-size: 1rem;
+  font-weight: 500;
+  color: var(--text-color);
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+}
+
+.group-level-3 .group-header h4 i,
+.category-level-3 .category-header h4 i {
+  color: var(--text-muted);
+  font-size: 1rem;
+}
+
+/* 层级4: 子分组 */
+.group-level-4,
+.category-level-4 {
+  margin-top: 0;
+  margin-bottom: 0;
+  padding-left: 1rem;
+  position: relative;
+}
+
+/* 嵌套层级间距：仅在同级相邻时增加间距，避免首项被额外下推 */
+.subcategories-container > .category-level-2 + .category-level-2 {
+  margin-top: 1rem;
+}
+
+.groups-container > .group-level-3 + .group-level-3,
+.groups-container > .category-level-3 + .category-level-3 {
+  margin-top: 0.8rem;
+}
+
+.subgroups-container > .group-level-4 + .group-level-4,
+.subcategories-container > .category-level-4 + .category-level-4 {
+  margin-top: 0.6rem;
+}
+
+/* 层级4: 标题样式 */
+.group-level-4 .group-header,
+.category-level-4 .category-header {
+  margin: 0 0 0.6rem 0;
+  padding: 0.2rem 0;
+  background: none;
+}
+
+.group-level-4 .group-header h5,
+.category-level-4 .category-header h5 {
+  font-size: 0.9rem;
+  font-weight: 500;
+  color: var(--text-muted);
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.group-level-4 .group-header h5 i,
+.category-level-4 .category-header h5 i {
+  font-size: 0.9rem;
+  opacity: 0.7;
+}
+
+/* 移除悬停时的缩放效果，保持简洁 */
+.category-level-2 .category-header:hover h3 > i,
+.group-level-3 .group-header:hover h4 i,
+.category-level-3 .category-header:hover h4 i,
+.group-level-4 .group-header:hover h5 i,
+.category-level-4 .category-header:hover h5 i {
+  transform: none;
+}
+
+/* 切换图标样式 */
+.category-header .toggle-icon,
+.group-header .toggle-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  margin-left: auto;
+  color: var(--text-muted);
+  font-size: 0.9rem;
+}
+
+.category-header .toggle-icon i,
+.group-header .toggle-icon i {
+  transition:
+    transform 0.3s ease,
+    color 0.3s ease;
+  transform: rotate(0deg);
+}
+
+/* 展开态：图标旋转 180°（类似参考样式1） */
+.category:not(.collapsed) > .category-header .toggle-icon i,
+.group:not(.collapsed) > .group-header .toggle-icon i {
+  transform: rotate(180deg);
+  color: var(--text-bright);
+}
+
+.category-header[data-toggle='category']:hover .toggle-icon i,
+.group-header[data-toggle='group']:hover .toggle-icon i {
+  color: var(--accent-color);
+}
+
+/* 分类/分组折叠图标：桌面端默认隐藏，悬停/收起时显示，避免按钮过多 */
+@media (hover: hover) and (pointer: fine) {
+  .category-header .toggle-icon,
+  .group-header .toggle-icon {
+    opacity: 0;
+    transition: opacity 0.2s ease;
+  }
+
+  .category-header[data-toggle='category']:hover .toggle-icon,
+  .category.collapsed > .category-header .toggle-icon,
+  .group-header[data-toggle='group']:hover .toggle-icon,
+  .group.collapsed > .group-header .toggle-icon {
+    opacity: 1;
+  }
+}
+
+/* 展开/折叠动画 */
+.category-content,
+.group-content {
+  overflow: visible;
+  transition:
+    max-height 0.3s cubic-bezier(0.4, 0, 0.2, 1),
+    opacity 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  max-height: 5000px;
+  opacity: 1;
+}
+
+.category.collapsed .category-content,
+.group.collapsed .group-content {
+  overflow: hidden;
+  max-height: 0;
+  opacity: 0;
+  margin-top: 0;
+}
+
+/* 收起状态下调整header的下边距 */
+.category.collapsed > .category-header {
+  margin-bottom: -0.5rem;
+}
+
+.category-level-2.collapsed > .category-header {
+  margin-bottom: 0;
+  border-bottom: none;
+}
+
+.group-level-3.collapsed > .group-header,
+.category-level-3.collapsed > .category-header {
+  margin-bottom: 0;
+}
+
+.group-level-4.collapsed > .group-header,
+.category-level-4.collapsed > .category-header {
+  margin-bottom: 0;
+}
+
+/* 收起态默认向下，无需额外旋转（保持 0deg） */
+
+/* 空内容提示 */
+.empty-content {
+  color: var(--text-muted);
+  font-style: italic;
+  text-align: center;
+  padding: 1rem;
+  font-size: 0.9rem;
+}
+
+/* 子容器样式 */
+.subcategories-container,
+.groups-container {
+  width: 100%;
+}
+
+/* 当分类同时包含子分类和站点时的样式优化 */
+.category-content .subcategories-container + .sites-grid {
+  margin-top: 1.2rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--border-color);
+}
+
+/* 当分类同时包含分组和站点时的样式优化 */
+.category-content .groups-container + .sites-grid {
+  margin-top: 1.2rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--border-color);
+}
+
+/* 子分类容器底部间距调整 */
+.category-content .subcategories-container:not(:last-child),
+.category-content .groups-container:not(:last-child) {
+  margin-bottom: 0.6rem;
+}
+
+/* 确保嵌套的网站网格正确显示 */
+.category-level-2 .sites-grid,
+.group-level-3 .sites-grid,
+.category-level-3 .sites-grid,
+.group-level-4 .sites-grid,
+.category-level-4 .sites-grid {
+  margin-top: 0;
+  gap: 0.75rem;
+  /* 保持与顶层一致的网格布局 */
+  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+}
+
+/* 响应式设计 - 嵌套结构 */
+@media (max-width: 768px) {
+  .category-level-2 {
+    padding-left: 0.75rem;
+  }
+
+  .group-level-3,
+  .category-level-3 {
+    padding-left: 0.75rem;
+  }
+
+  .group-level-4,
+  .category-level-4 {
+    padding-left: 0.75rem;
+  }
+
+  .subcategories-container > .category-level-2 + .category-level-2 {
+    margin-top: 0.8rem;
+  }
+
+  .groups-container > .group-level-3 + .group-level-3,
+  .groups-container > .category-level-3 + .category-level-3 {
+    margin-top: 0.7rem;
+  }
+
+  .subgroups-container > .group-level-4 + .group-level-4,
+  .subcategories-container > .category-level-4 + .category-level-4 {
+    margin-top: 0.55rem;
+  }
+
+  .category-level-2 .sites-grid,
+  .group-level-3 .sites-grid,
+  .category-level-3 .sites-grid,
+  .group-level-4 .sites-grid,
+  .category-level-4 .sites-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: var(--spacing-sm);
+  }
+}
+
+@media (max-width: 480px) {
+  .category {
+    margin-left: 0.5rem;
+    margin-right: 0.5rem;
+    padding: 1rem;
+  }
+
+  .category-level-2,
+  .group-level-3,
+  .category-level-3 {
+    margin-left: 0;
+    padding-left: 0.75rem;
+    width: 100%;
+  }
+
+  .group-level-4,
+  .category-level-4 {
+    margin-left: 0;
+    padding-left: 0.75rem;
+    width: 100%;
+  }
+
+  .category-level-2 .sites-grid,
+  .group-level-3 .sites-grid,
+  .category-level-3 .sites-grid,
+  .group-level-4 .sites-grid,
+  .category-level-4 .sites-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 0.5rem;
+  }
+}
+
+/* 网站卡片网格 */
+.sites-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+  gap: 0.75rem;
+  position: relative;
+  z-index: 1;
+  width: 100%;
+}
+
+/* projects：GitHub 热力图（github-calendar.js，底部展示） */
+.page-template-projects .gh-heatmap-category {
+  /* 外层已复用一级分类卡片（.category），这里仅保留热力图内部布局/色阶 */
+  --gh-text: var(--text-color);
+  --gh-text-muted: var(--text-muted);
+  --gh-level-0: rgba(255, 255, 255, 0.08);
+  --gh-level-1: rgba(55, 178, 77, 0.35);
+  --gh-level-2: rgba(55, 178, 77, 0.55);
+  --gh-level-3: rgba(55, 178, 77, 0.75);
+  --gh-level-4: rgba(55, 178, 77, 0.95);
+  --gh-radius: 3px;
+
+  margin: 0 auto 1.2rem auto;
+}
+
+.page-template-projects .gh-heatmap-wrapper {
+  margin-top: 0;
+}
+
+/* 浅色主题：更接近 GitHub 原色阶 */
+html.theme-preload .page-template-projects .gh-heatmap-category,
+body.light-theme .page-template-projects .gh-heatmap-category {
+  /* 浅色主题下，空格子需要比背景更明显一点 */
+  --gh-level-0: #d8dee4;
+  --gh-level-1: #9be9a8;
+  --gh-level-2: #40c463;
+  --gh-level-3: #30a14e;
+  --gh-level-4: #216e39;
+}
+
+/* 标题中的用户名（@xxx）更弱化一点，像副标题 */
+.page-template-projects .gh-heatmap-username {
+  color: var(--text-muted);
+  font-weight: 400;
+  margin-left: 0.35rem;
+}
+
+/* 使用一级分类标题的排版节奏，略收紧热力图区域 */
+.page-template-projects .gh-heatmap-category .category-header {
+  margin-bottom: 0.8rem;
+}
+
+/* 标题行：左侧标题 + 右侧 legend（不占内容区高度） */
+.page-template-projects .gh-heatmap-category .gh-heatmap-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.8rem;
+}
+
+.page-template-projects .gh-heatmap-category .gh-heatmap-header h2 {
+  margin: 0;
+}
+
+/* 让 legend 与标题体系保持一致：放在标题区右侧 */
+.page-template-projects .gh-heatmap-category .gh-legend {
+  justify-content: flex-end;
+  margin: 0;
+}
+
+.page-template-projects .gh-header {
+  display: none;
+}
+
+.page-template-projects .gh-legend {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 0.75rem;
+  color: var(--gh-text-muted);
+  white-space: nowrap;
+}
+
+/* heatmap：移动端标题/legend 文本简写 */
+.gh-text-mobile {
+  display: none;
+}
+
+@media (max-width: 480px) {
+  .gh-text-desktop {
+    display: none;
+  }
+
+  .gh-text-mobile {
+    display: inline;
+  }
+
+  .page-template-projects .gh-heatmap-category .gh-heatmap-header {
+    flex-wrap: wrap;
+  }
+
+  .page-template-projects .gh-heatmap-category .gh-legend {
+    gap: 2px;
+    font-size: 0.7rem;
+  }
+
+  .page-template-projects .gh-legend-item {
+    width: 8px;
+    height: 8px;
+  }
+}
+
+.page-template-projects .gh-legend-item {
+  width: 10px;
+  height: 10px;
+  border-radius: 2px;
+}
+
+.page-template-projects .gh-legend .level-0 {
+  background-color: var(--gh-level-0);
+}
+
+.page-template-projects .gh-legend .level-1 {
+  background-color: var(--gh-level-1);
+}
+
+.page-template-projects .gh-legend .level-2 {
+  background-color: var(--gh-level-2);
+}
+
+.page-template-projects .gh-legend .level-3 {
+  background-color: var(--gh-level-3);
+}
+
+.page-template-projects .gh-legend .level-4 {
+  background-color: var(--gh-level-4);
+}
+
+/* github-calendar 注入的内容容器 */
+.page-template-projects .gh-calendar {
+  border: none !important;
+  min-height: 0;
+  width: 100%;
+  /* 构建期注入：避免 flex 居中导致内容超宽“撑破卡片” */
+  display: block;
+}
+
+/* 顶部统计标题：XXX contributions in the last year */
+.page-template-projects .gh-calendar #js-contribution-activity-description {
+  /* 注意：全局 .category h2 会把 h2 设为 flex，导致“看起来左对齐”。这里强制回退为 block。 */
+  display: block;
+  width: 100%;
+  text-align: center;
+  margin: 0 0 12px 0;
+}
+
+/* 外层包裹：强制占满卡片宽度，滚动发生在内部 */
+.page-template-projects .gh-calendar .graph-before-activity-overview {
+  width: 100%;
+}
+
+/* 允许移动端横向滚动查看（GitHub 风格） */
+.page-template-projects .gh-calendar .js-calendar-graph {
+  width: 100%;
+  /* 构建期注入 GitHub 原生 table：滚动交给内层容器，避免裁剪 */
+  display: block;
+}
+
+/* GitHub 原生 markup：通常在 .js-calendar-graph 内有一个 div 设置 overflow-x */
+.page-template-projects .gh-calendar .js-calendar-graph > div {
+  width: 100%;
+  max-width: 100%;
+  overflow-x: auto;
+  overflow-y: hidden;
+  -webkit-overflow-scrolling: touch;
+  /* 由 table 的 margin:auto 来实现“可居中 + 可滚动时左对齐起始列” */
+  display: block;
+  padding-bottom: 10px;
+}
+
+.page-template-projects .gh-calendar .js-calendar-graph-svg {
+  width: 100%;
+  height: auto;
+}
+
+/* 覆盖每个方块的颜色（依赖 github-calendar 的 data-level） */
+.page-template-projects .gh-calendar .day {
+  rx: var(--gh-radius);
+  ry: var(--gh-radius);
+  outline: none;
+}
+
+.page-template-projects .gh-calendar .day[data-level='0'] {
+  fill: var(--gh-level-0);
+}
+
+.page-template-projects .gh-calendar .day[data-level='1'] {
+  fill: var(--gh-level-1);
+}
+
+.page-template-projects .gh-calendar .day[data-level='2'] {
+  fill: var(--gh-level-2);
+}
+
+.page-template-projects .gh-calendar .day[data-level='3'] {
+  fill: var(--gh-level-3);
+}
+
+.page-template-projects .gh-calendar .day[data-level='4'] {
+  fill: var(--gh-level-4);
+}
+
+.page-template-projects .gh-calendar text {
+  fill: var(--gh-text-muted);
+  font-size: 10px;
+}
+
+/* 去掉库自带 footer（更简洁） */
+.page-template-projects .gh-calendar .contrib-footer {
+  display: none !important;
+}
+
+.page-template-projects .gh-calendar.gh-calendar-error {
+  color: var(--gh-text-muted);
+  font-size: 0.85rem;
+}
+
+/* github-calendar（HTML table 版）：适配 ContributionCalendar-* 类名 */
+.page-template-projects .gh-calendar table {
+  /* 让热力图在卡片内尽量铺满宽度；需要时仍可横向滚动 */
+  /* 关键：避免 table 按列拉伸导致 day 变成长方形 */
+  display: table;
+  /* 不强制占满：保持自然宽度，并在容器内居中 */
+  width: max-content;
+  min-width: max-content;
+  max-width: none;
+  table-layout: auto;
+  border-collapse: separate;
+  border-spacing: 5px !important;
+  /* table 未超宽时居中；超宽时 margin auto 会退化为 0（滚动起始列左对齐） */
+  margin: 0 auto;
+}
+
+/* GitHub 原生 table：thead 行内写死 height:15px，需强制更高以避免月份 label 压到格子 */
+.page-template-projects .gh-calendar table thead tr {
+  height: 20px !important;
+}
+
+/* GitHub 原生 table 的月份 label 使用 absolute 定位，需要为 thead 行预留高度，避免与格子重叠 */
+.page-template-projects .gh-calendar .ContributionCalendar-label {
+  height: 16px;
+  position: relative;
+  padding-bottom: 4px;
+  font-size: 10px;
+  line-height: 10px;
+  font-weight: 400;
+  vertical-align: bottom;
+}
+
+@media (max-width: 600px) {
+  /* 移动端：格子更紧凑，减少横向滚动压力 */
+  .page-template-projects .gh-calendar table {
+    border-spacing: 3px !important;
+  }
+
+  .page-template-projects .gh-calendar .ContributionCalendar-day {
+    width: 12px;
+    height: 12px;
+    min-width: 12px;
+    min-height: 12px;
+  }
+
+  .page-template-projects .gh-calendar #js-contribution-activity-description {
+    font-size: 0.95rem;
+  }
+}
+
+/* GitHub 原生 footer：保留“Learn how we count contributions”，隐藏右侧自带 legend（避免与自定义 legend 重复） */
+.page-template-projects .gh-calendar .float-right.color-fg-muted.d-flex.flex-items-center {
+  display: none !important;
+}
+
+/* 按需求：去除 “Learn how we count contributions” */
+.page-template-projects .gh-calendar .float-left {
+  display: none !important;
+}
+
+/* Link--muted 目前不展示（float-left 已隐藏）；保留基础链接色由下方 a 规则兜底 */
+
+.page-template-projects .gh-calendar .ContributionCalendar-day {
+  /* 固定正方形，防止被 table 列宽拉伸 */
+  width: 15px;
+  height: 15px;
+  min-width: 15px;
+  min-height: 15px;
+  aspect-ratio: 1 / 1;
+  border-radius: var(--gh-radius);
+  background-color: var(--gh-level-0);
+}
+
+.page-template-projects .gh-calendar .ContributionCalendar-day[data-level='0'] {
+  background-color: var(--gh-level-0) !important;
+}
+
+.page-template-projects .gh-calendar .ContributionCalendar-day[data-level='1'] {
+  background-color: var(--gh-level-1) !important;
+}
+
+.page-template-projects .gh-calendar .ContributionCalendar-day[data-level='2'] {
+  background-color: var(--gh-level-2) !important;
+}
+
+.page-template-projects .gh-calendar .ContributionCalendar-day[data-level='3'] {
+  background-color: var(--gh-level-3) !important;
+}
+
+.page-template-projects .gh-calendar .ContributionCalendar-day[data-level='4'] {
+  background-color: var(--gh-level-4) !important;
+}
+
+/* a11y 跳转链接：视觉隐藏（保留可访问性） */
+.page-template-projects .gh-calendar a[href^='#year-list'],
+.page-template-projects .gh-calendar a[href*='year-list'],
+.page-template-projects .gh-calendar a[href*='contributions-year'],
+/* GitHub 注入的 "Skip to contributions year list"（常见为 show-on-focus） */
+.page-template-projects .gh-calendar a.show-on-focus {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* 隐藏库自带 footer/legend，避免与自定义 legend 重复 */
+.page-template-projects .gh-calendar .ContributionCalendar-footer,
+.page-template-projects .gh-calendar .contrib-footer,
+.page-template-projects .gh-calendar .legend,
+/* GitHub 原生 legend 容器（float-right + flex） */
+.page-template-projects .gh-calendar .float-right.color-fg-muted.d-flex.flex-items-center {
+  display: none !important;
+}
+
+/* 修复星期/月份 label 的意外高亮（如 Wed 蓝底） */
+.page-template-projects .gh-calendar .ContributionCalendar-label {
+  background: transparent !important;
+  background-color: transparent !important;
+  color: var(--gh-text-muted) !important;
+}
+
+/* 组件内链接样式：去掉默认紫色 */
+.page-template-projects .gh-calendar a {
+  color: var(--gh-text-muted);
+  text-decoration: none;
+}
+
+.page-template-projects .gh-calendar a:hover {
+  color: var(--gh-text);
+  text-decoration: underline;
+}
+
+/* Mobile text toggling for Heatmap Header：已在上方 heatmap 区域定义，避免重复 */
+
+/* projects：旧版 GitHub 热力图（ghchart 图片）已弃用，改用 github-calendar.js */
+
+.page-template-projects .sites-grid {
+  /* projects：桌面端固定 3 列（避免 auto-fill 在中等宽度下退化为 2 列） */
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+  gap: 24px;
+}
+
+@media (max-width: 1024px) {
+  .page-template-projects .sites-grid {
+    grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
+  }
+}
+
+@media (max-width: 600px) {
+  .page-template-projects .sites-grid {
+    grid-template-columns: 1fr;
+    gap: 0.75rem;
+  }
+}
+
+/* projects：代码仓库风卡片 */
+.site-card.site-card-repo {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  align-items: stretch;
+  padding: 1.1rem 1.1rem 1rem;
+  gap: 0;
+}
+
+.site-card.site-card-repo:hover {
+  transform: translateY(-4px);
+}
+
+.site-card.site-card-repo .repo-header {
+  display: flex;
+  align-items: center;
+  gap: 0.75rem;
+  margin-bottom: 12px;
+  min-width: 0;
+}
+
+.site-card.site-card-repo .repo-icon {
+  font-size: 1.15rem;
+  color: var(--nav-item-color);
+  opacity: 0.85;
+  transition:
+    color 0.3s ease,
+    opacity 0.3s ease;
+  flex: 0 0 auto;
+}
+
+.site-card.site-card-repo:hover .repo-icon {
+  color: var(--accent-color);
+  opacity: 1;
+}
+
+.site-card.site-card-repo .repo-title {
+  font-size: 1rem;
+  font-weight: 600;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.site-card.site-card-repo .repo-desc {
+  font-size: 0.9rem;
+  color: var(--nav-item-color);
+  opacity: 0.85;
+  line-height: 1.5;
+  flex-grow: 1;
+  margin: 0 0 16px 0;
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  overflow: hidden;
+  position: relative;
+  /* Ensure tooltip positioning context */
+}
+
+.site-card.site-card-repo .repo-stats {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  padding-top: 12px;
+  border-top: 1px solid rgba(255, 255, 255, 0.06);
+  font-size: 0.8rem;
+  color: var(--nav-item-color);
+  opacity: 0.85;
+}
+
+.site-card.site-card-repo .stat-item {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  min-width: 0;
+}
+
+.site-card.site-card-repo .lang-dot {
+  width: 10px;
+  height: 10px;
+  border-radius: 50%;
+  display: inline-block;
+}
+
+@media (max-width: 600px) {
+  .welcome-section-with-side {
+    align-items: flex-start;
+  }
+
+  .welcome-section-with-side .welcome-section-side {
+    width: 100%;
+  }
+
+  /* 旧版 heatmap-container/heatmap-img 已弃用 */
+}
+
+/* 网站卡片样式 */
+.site-card {
+  background: linear-gradient(
+    145deg,
+    var(--site-card-bg-gradient-1),
+    var(--site-card-bg-gradient-2)
+  );
+  border-radius: var(--radius-lg);
+  padding: 0.75rem 0.9rem;
+  text-decoration: none;
+  color: inherit;
+  transition:
+    background var(--transition-normal),
+    transform var(--transition-normal),
+    box-shadow var(--transition-normal),
+    border-color var(--transition-normal);
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  text-align: left;
+  backface-visibility: hidden;
+  transform: translateZ(0);
+  will-change: transform;
+  max-width: 100%;
+  position: relative;
+  box-shadow: 0 4px 16px var(--shadow-color);
+  border: 1px solid var(--border-color);
+  z-index: 2;
+  overflow: hidden;
+}
+
+/* 网站卡片变体：projects 大卡片 */
+.site-card.site-card-large {
+  padding: 1.1rem 1.2rem;
+  gap: 0.9rem;
+}
+
+.site-card.site-card-large .site-card-icon {
+  width: 3.1rem;
+  height: 3.1rem;
+}
+
+.site-card.site-card-large h3 {
+  font-size: 1rem;
+  font-weight: 600;
+}
+
+.site-card.site-card-large p {
+  font-size: 0.9rem;
+}
+
+/* Phase 2：articles 页面隐藏“扩展写回结构”，避免与文章条目渲染混淆 */
+.menav-extension-shadow {
+  display: none;
+}
+
+/* articles：文章元信息（日期 + 来源） */
+.site-card[data-type='article'] .site-card-meta {
+  margin: 0 0 8px 0;
+  font-size: 0.75rem;
+  color: var(--nav-item-color);
+  opacity: 0.9;
+  display: flex;
+  align-items: center;
+  gap: 0.4rem;
+}
+
+.site-card[data-type='article'] .site-card-meta-sep {
+  opacity: 0.8;
+}
+
+/* articles：文章卡片布局（首行：图标+标题；下方：时间/来源 + 简介 全宽对齐） */
+.site-card[data-type='article'] {
+  display: block;
+  padding: 1rem 1.1rem;
+}
+
+.site-card[data-type='article'] .article-card-header {
+  display: flex;
+  align-items: flex-start;
+  gap: 0.75rem;
+}
+
+.site-card[data-type='article'] .article-card-title {
+  min-width: 0;
+}
+
+.site-card[data-type='article'] .article-card-body {
+  margin-top: 0.55rem;
+}
+
+.site-card[data-type='article'] h3 {
+  margin: 0;
+}
+
+.site-card[data-type='article'] p {
+  margin: 0;
+}
+
+/* articles：桌面端网格固定 3 列（避免 auto-fill 在大屏上过多列导致阅读密度过高） */
+.page-template-articles .sites-grid {
+  grid-template-columns: repeat(3, minmax(0, 1fr));
+}
+
+@media (max-width: 1024px) {
+  .page-template-articles .sites-grid {
+    grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+  }
+}
+
+@media (max-width: 480px) {
+  .page-template-articles .sites-grid {
+    grid-template-columns: 1fr;
+    gap: 0.5rem;
+  }
+}
+
+/* articles：标题/描述允许两行显示（更适合多列宽卡片，也适用于搜索结果页） */
+.site-card[data-type='article'] h3 {
+  white-space: normal;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+}
+
+.site-card[data-type='article'] p {
+  white-space: normal;
+  display: -webkit-box;
+  -webkit-line-clamp: 2;
+  -webkit-box-orient: vertical;
+}
+
+.site-card:hover {
+  transform: translateY(-3px);
+  background: var(--site-card-hover-bg);
+  border-color: var(--border-color);
+}
+
+.site-card-icon {
+  flex-shrink: 0;
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: var(--radius-md);
+  background: rgba(var(--card-bg-rgb), 0.35);
+  border: 1px solid var(--border-color);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition:
+    transform 0.3s ease,
+    background-color 0.3s ease;
+}
+
+.site-card .site-icon {
+  font-size: 1.4rem;
+  color: var(--accent-color);
+  transition: color 0.3s ease;
+}
+
+.site-card:hover .site-card-icon {
+  transform: scale(1.06);
+}
+
+.site-card:hover .site-icon {
+  color: var(--accent-hover);
+}
+
+/* 网站卡片 favicon 图片样式，与图标尺寸保持一致 */
+.site-card .favicon-icon {
+  display: inline-block;
+  width: 1.8rem;
+  height: 1.8rem;
+  border-radius: var(--radius-sm);
+  object-fit: cover;
+  transition:
+    transform 0.3s ease,
+    box-shadow 0.3s ease;
+}
+
+.site-card .icon-placeholder,
+.site-card .icon-fallback {
+  display: inline-block;
+  width: 1.8rem;
+  height: 1.8rem;
+  border-radius: var(--radius-sm);
+  flex-shrink: 0;
+  vertical-align: middle;
+  text-align: center;
+  line-height: 1.8rem;
+  font-size: 1.5rem;
+  transition:
+    transform 0.3s ease,
+    box-shadow 0.3s ease;
+  color: var(--accent-color);
+}
+
+/* 确保图标容器在加载过程中保持固定尺寸 */
+.site-card .icon-container {
+  display: inline-block;
+  width: 1.8rem;
+  height: 1.8rem;
+  position: relative;
+  vertical-align: middle;
+}
+
+.site-card .icon-container .favicon-icon,
+.site-card .icon-container .icon-placeholder,
+.site-card .icon-container .icon-fallback {
+  position: absolute;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  margin-bottom: 0;
+}
+
+/* 优化图标切换动画 */
+.site-card .icon-container .favicon-icon {
+  opacity: 0;
+  transition: opacity 0.3s ease;
+}
+
+.site-card .icon-container .favicon-icon.loaded {
+  opacity: 1;
+}
+
+.site-card .icon-container .favicon-icon.error {
+  display: none;
+}
+
+.site-card .icon-container .icon-placeholder {
+  opacity: 1;
+  transition: opacity 0.3s ease;
+}
+
+.site-card .icon-container .icon-placeholder.hidden {
+  opacity: 0;
+  pointer-events: none;
+}
+
+.site-card .icon-container .icon-fallback {
+  opacity: 0;
+  transition: opacity 0.3s ease;
+}
+
+.site-card .icon-container .icon-fallback.visible {
+  opacity: 1;
+}
+
+.site-card:hover .icon-placeholder,
+.site-card:hover .icon-fallback {
+  color: var(--accent-hover);
+}
+
+.site-card-content {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+}
+
+.site-card h3 {
+  font-size: 1rem;
+  margin-bottom: 0.25rem;
+  color: var(--text-bright);
+  font-weight: 500;
+  letter-spacing: 0.3px;
+  transition: color 0.3s ease;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  max-width: 100%;
+}
+
+.site-card p {
+  font-size: 0.9rem;
+  color: var(--nav-item-color);
+  margin: 0;
+  line-height: 1.4;
+  transition: color 0.3s ease;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  width: 100%;
+  position: relative;
+  /* Ensure tooltip positioning context */
+}
+
+/* Tooltip styles */
+/* Tooltip styles */
+.site-card p[data-tooltip],
+.site-card .repo-desc[data-tooltip] {
+  cursor: default;
+  /* Indicate interactivity */
+}
+
+.custom-tooltip {
+  position: fixed;
+  background: rgba(47, 48, 53, 0.95);
+  /* Fallback dark */
+  background: rgba(var(--card-bg-rgb), 0.95);
+  color: var(--text-bright);
+  padding: 0.5rem 0.8rem;
+  border-radius: var(--radius-md);
+  box-shadow: 0 4px 12px var(--shadow-color);
+  border: 1px solid var(--border-color);
+  font-size: 0.85rem;
+  white-space: normal;
+  line-height: 1.4;
+  z-index: 9999;
+  pointer-events: none;
+  opacity: 0;
+  transition: opacity 0.2s ease-out;
+  backdrop-filter: blur(4px);
+  -webkit-backdrop-filter: blur(4px);
+  max-width: 300px;
+  word-break: break-word;
+}
+
+.custom-tooltip.visible {
+  opacity: 1;
+}
+
+/* 添加编辑按钮 */
+.edit-buttons {
+  position: absolute;
+  top: 0.5rem;
+  right: 0.5rem;
+  display: flex;
+  gap: 0.5rem;
+  opacity: 0;
+  transition: opacity 0.3s ease;
+}
+
+.site-card:hover .edit-buttons {
+  opacity: 1;
+}
+
+.edit-btn,
+.delete-btn {
+  background: none;
+  border: none;
+  color: var(--text-muted);
+  cursor: pointer;
+  padding: 0.3rem;
+  border-radius: 4px;
+  transition: all 0.3s ease;
+}
+
+.edit-btn:hover,
+.delete-btn:hover {
+  color: var(--text-bright);
+  background-color: var(--secondary-bg);
+}
+
+/* 添加网站按钮 */
+.add-site-btn {
+  background: linear-gradient(
+    145deg,
+    var(--site-card-bg-gradient-1),
+    var(--site-card-bg-gradient-2)
+  );
+  border: 2px dashed var(--border-color);
+  border-radius: var(--radius-lg);
+  padding: 1.5rem;
+  color: var(--text-muted);
+  cursor: pointer;
+  transition: all var(--transition-normal);
+  transition-timing-function: var(--transition-bounce);
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  min-height: 180px;
+  box-shadow: 0 4px 16px var(--shadow-color);
+}
+
+.add-site-btn:hover {
+  background: linear-gradient(145deg, var(--secondary-bg), var(--site-card-bg-gradient-1));
+  border-color: var(--accent-color);
+  color: var(--text-bright);
+  transform: translateY(-2px);
+  box-shadow: 0 6px 20px var(--shadow-color);
+}
+
+.add-site-btn i {
+  font-size: 2.2rem;
+  margin-bottom: 0.8rem;
+  transition: transform 0.3s ease;
+}
+
+.add-site-btn:hover i {
+  transform: scale(1.1);
+}
diff --git a/assets/styles/_content.css b/assets/styles/_content.css
new file mode 100644
index 0000000000000000000000000000000000000000..cb3f7211a37ac0fbccd985afd7510b04de345a09
--- /dev/null
+++ b/assets/styles/_content.css
@@ -0,0 +1,216 @@
+/* Markdown Content Page */
+
+/* ------------------------------------------------------------------
+   Markdown Content Styling (GitHub-like) - Scoped to .content-page
+   ------------------------------------------------------------------ */
+
+/* Increase inner spacing for content pages to separate text from card border */
+.content-category .content-page {
+  padding-left: var(--spacing-sm);
+  padding-right: var(--spacing-sm);
+}
+
+@media (max-width: 480px) {
+  .content-category .content-page {
+    padding-left: var(--spacing-xs);
+    padding-right: var(--spacing-xs);
+  }
+}
+
+.content-page {
+  font-family: var(
+    --font-body,
+    -apple-system,
+    BlinkMacSystemFont,
+    'Segoe UI',
+    'Noto Sans',
+    Helvetica,
+    Arial,
+    sans-serif,
+    'Apple Color Emoji',
+    'Segoe UI Emoji'
+  );
+  font-size: 16px;
+  line-height: 1.6;
+  color: var(--text-color);
+  word-wrap: break-word;
+  padding-bottom: 2rem;
+}
+
+.content-page h1,
+.content-page h2,
+.content-page h3,
+.content-page h4,
+.content-page h5,
+.content-page h6 {
+  margin-top: 24px;
+  margin-bottom: 16px;
+  font-weight: 600;
+  line-height: 1.25;
+  color: var(--text-bright);
+}
+
+.content-page h1 {
+  font-size: 2em;
+  padding-bottom: 0.3em;
+  border-bottom: 1px solid var(--border-color);
+}
+
+.content-page h2 {
+  font-size: 1.5em;
+  padding-bottom: 0.3em;
+  border-bottom: 1px solid var(--border-color);
+}
+
+.content-page h3 {
+  font-size: 1.25em;
+}
+
+.content-page h4 {
+  font-size: 1em;
+}
+
+.content-page h5 {
+  font-size: 0.875em;
+}
+
+.content-page h6 {
+  font-size: 0.85em;
+  color: var(--text-muted);
+}
+
+.content-page p {
+  margin-top: 0;
+  margin-bottom: 16px;
+}
+
+.content-page blockquote {
+  margin: 0 0 16px;
+  padding: 0 1em;
+  color: var(--text-muted);
+  border-left: 0.25em solid var(--border-color);
+  background-color: transparent;
+}
+
+.content-page ul,
+.content-page ol {
+  margin-top: 0;
+  margin-bottom: 16px;
+  padding-left: 2em;
+}
+
+.content-page li + li {
+  margin-top: 0.25em;
+}
+
+/* Inline code */
+.content-page code {
+  font-family:
+    ui-monospace,
+    SFMono-Regular,
+    SF Mono,
+    Menlo,
+    Consolas,
+    Liberation Mono,
+    monospace;
+  font-size: 85%;
+  padding: 0.2em 0.4em;
+  margin: 0;
+  border-radius: var(--radius-sm);
+  background-color: rgba(127, 127, 127, 0.15);
+  color: var(--text-bright);
+}
+
+/* Block code (pre) */
+.content-page pre {
+  padding: 16px;
+  overflow: auto;
+  font-size: 85%;
+  line-height: 1.45;
+  /* 代码块背景需要与内容卡片区分开：避免与 card-bg 过于接近 */
+  background-color: rgba(127, 127, 127, 0.08);
+  border-radius: var(--radius-md);
+  margin-top: 0;
+  margin-bottom: 16px;
+  border: 1px solid var(--border-color);
+}
+
+.content-page pre code {
+  background-color: transparent;
+  padding: 0;
+  font-size: 100%;
+  color: inherit;
+  word-break: normal;
+  border-radius: 0;
+}
+
+.content-page hr {
+  height: 0.25em;
+  padding: 0;
+  margin: 24px 0;
+  background-color: var(--border-color);
+  border: 0;
+}
+
+/* Tables */
+.content-page table {
+  border-spacing: 0;
+  border-collapse: collapse;
+  margin-top: 0;
+  margin-bottom: 16px;
+  display: block;
+  width: max-content;
+  max-width: 100%;
+  overflow: auto;
+}
+
+.content-page table th,
+.content-page table td {
+  padding: 6px 13px;
+  border: 1px solid var(--border-color);
+}
+
+.content-page table th {
+  font-weight: 600;
+  background-color: rgba(var(--card-bg-rgb), 0.3);
+}
+
+.content-page table tr {
+  background-color: transparent;
+  border-top: 1px solid var(--border-color);
+}
+
+.content-page table tr:nth-child(2n) {
+  background-color: rgba(127, 127, 127, 0.04);
+}
+
+.content-page img {
+  max-width: 100%;
+  box-sizing: content-box;
+  background-color: transparent;
+  border-radius: var(--radius-sm);
+}
+
+.content-page a {
+  color: var(--accent-color);
+  text-decoration: none;
+}
+
+.content-page a:hover {
+  text-decoration: underline;
+}
+
+/* Task lists */
+.content-page ul.contains-task-list {
+  list-style-type: none;
+  padding-left: 0;
+}
+
+.content-page .task-list-item input {
+  margin-right: 0.5em;
+  vertical-align: middle;
+}
+
+/* GitHub Calendar Fixes (HTML Table Version)
+ * 注：此处样式已合并到上方「projects：GitHub 热力图（github-calendar.js）」区域，避免重复维护。
+ */
diff --git a/assets/styles/_dashboard.css b/assets/styles/_dashboard.css
new file mode 100644
index 0000000000000000000000000000000000000000..d163d13ddce11077e1f01d847d9d4715e655ecc1
--- /dev/null
+++ b/assets/styles/_dashboard.css
@@ -0,0 +1,371 @@
+/* Dashboard (Clock & Todo) */
+
+/* =========================================
+   Home Dashboard Styles
+   ========================================= */
+
+.dashboard-grid {
+  display: grid;
+  grid-template-columns: 1fr;
+  /* Mobile first: stack vertically */
+  gap: var(--spacing-xl);
+  margin-bottom: var(--spacing-xl);
+}
+
+@media (min-width: 992px) {
+  .dashboard-grid {
+    grid-template-columns: 5fr 7fr;
+    /* Desktop: 5/12 - 7/12 ratio like 1.html */
+    align-items: stretch;
+    /* Stretch to align bottoms */
+    gap: var(--spacing-lg);
+    /* Reduced gap */
+    margin-bottom: var(--spacing-lg);
+    /* Reduced margin */
+  }
+}
+
+/* --- Left Column: Welcome & Clock --- */
+.dashboard-intro {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  /* Match grid row height */
+  gap: var(--spacing-md);
+  /* Reduced gap */
+  justify-content: space-between;
+  /* Spread welcome and clock */
+}
+
+.dashboard-welcome {
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-md);
+}
+
+.welcome-title {
+  font-size: 3.5rem;
+  font-family: var(--font-heading, var(--font-body, sans-serif));
+  font-weight: 800;
+  /* Extra Bold */
+  font-style: normal;
+  /* Remove italic */
+  text-transform: uppercase;
+  /* Pop Style */
+  letter-spacing: -0.03em;
+  /* Tight spacing */
+  color: var(--text-color);
+  /* Use primary text color, accent reserved for highlights */
+  line-height: 0.95;
+  margin: 0;
+  padding-left: var(--spacing-xl);
+  /* Shift right */
+}
+
+.welcome-subtitle {
+  font-size: 0.9rem;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  color: var(--accent-color);
+  /* Accent color for subtitle */
+  font-weight: 600;
+  margin-top: 1rem;
+  padding-left: var(--spacing-xl);
+  opacity: 0.9;
+}
+
+@media (min-width: 768px) {
+  .welcome-title {
+    font-size: 3.5rem;
+    padding-left: 2rem;
+    /* Reduced from 5rem */
+  }
+
+  .welcome-subtitle {
+    font-size: 1.125rem;
+    padding-left: 2rem;
+  }
+}
+
+/* Clock Card - Apple Style: Flat + Soft Shadow */
+.dashboard-clock-card {
+  position: relative;
+  background-color: var(--card-bg-gradient-1);
+  /* Solid color, no gradient needed for flat look */
+  border: 0.5px solid var(--border-color);
+  /* Very subtle border */
+  border-radius: var(--radius-xl);
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  flex: 1;
+  box-shadow: 0 8px 24px var(--shadow-color);
+  /* Soft, diffused shadow */
+  transition:
+    transform var(--transition-normal),
+    box-shadow var(--transition-normal);
+  overflow: hidden;
+  padding: var(--spacing-xl);
+  /* More padding for spatial luxury */
+}
+
+body.light-theme .dashboard-clock-card {
+  box-shadow: 0 8px 32px rgba(0, 0, 0, 0.08);
+  /* Lighter shadow for light mode */
+}
+
+.clock-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-start;
+  z-index: 1;
+}
+
+.clock-meta {
+  display: flex;
+  flex-direction: column;
+}
+
+.clock-main {
+  align-self: flex-end;
+  /* Time at bottom right */
+  z-index: 1;
+}
+
+.clock-time {
+  font-size: 3.5rem;
+  /* Reduced from 4.5rem to prevent overflow */
+  font-weight: 700;
+  color: var(--text-bright);
+  line-height: 1;
+  font-family: var(--font-body);
+  letter-spacing: -0.02em;
+}
+
+.clock-greeting {
+  font-size: 0.85rem;
+  color: var(--accent-color);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.1em;
+  margin-bottom: 0.2rem;
+}
+
+.clock-week {
+  font-size: 0.75rem;
+  color: var(--text-muted);
+  border: 1px solid var(--border-color);
+  padding: 2px 8px;
+  border-radius: 12px;
+}
+
+.clock-date {
+  font-size: 1.25rem;
+  /* Reduced from 1.5rem */
+  color: var(--text-muted);
+  font-family: var(--font-body);
+}
+
+/* --- Right Column: Stats / Todo --- */
+.dashboard-stats {
+  height: 100%;
+  min-height: 300px;
+}
+
+.dashboard-panel {
+  background-color: var(--card-bg-gradient-1);
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-xl);
+  display: flex;
+  height: 310px;
+  /* Increased from 280px to align with clock card better */
+  overflow: hidden;
+  box-shadow: 4px 4px 0px 0px rgba(255, 255, 255, 0.15);
+  transition: box-shadow 0.2s ease;
+}
+
+body.light-theme .dashboard-panel {
+  box-shadow: 4px 4px 0px 0px rgba(0, 0, 0, 0.2);
+}
+
+.panel-sidebar {
+  width: 4rem;
+  background-color: var(--sidebar-bg);
+  border-right: 4px solid var(--border-color);
+  display: flex;
+  flex-direction: column;
+  justify-content: space-between;
+  /* Icon at top, button at bottom */
+  align-items: center;
+  padding: var(--spacing-md) 0;
+}
+
+.panel-static-icon {
+  color: var(--text-muted);
+  font-size: 1.5rem;
+  padding: 0.5rem;
+}
+
+.panel-icon-btn {
+  background: none;
+  border: none;
+  color: var(--text-muted);
+  font-size: 1.5rem;
+  cursor: pointer;
+  padding: 0.5rem;
+  border-radius: var(--radius-md);
+  transition: color 0.2s;
+}
+
+.panel-icon-btn:hover {
+  color: var(--accent-color);
+}
+
+.panel-content-wrapper {
+  flex: 1;
+  display: flex;
+  flex-direction: column;
+  overflow: hidden;
+  height: 100%;
+}
+
+.panel-content {
+  flex: 1;
+  padding: var(--spacing-lg);
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  gap: var(--spacing-md);
+}
+
+/* Todo Items */
+.todo-item {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-md);
+  padding: 4px 0;
+  /* Tighter spacing */
+  cursor: pointer;
+  transition: opacity 0.2s;
+  opacity: 1;
+  position: relative;
+}
+
+.todo-item:hover .todo-delete-btn {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+.todo-checkbox {
+  width: 1.25rem;
+  height: 1.25rem;
+  border: 2px solid var(--text-muted);
+  border-radius: var(--radius-sm);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  transition: all 0.2s;
+}
+
+.todo-checkbox.checked {
+  background-color: var(--accent-color);
+  border-color: var(--accent-color);
+  color: white;
+}
+
+.todo-checkbox.checked span {
+  font-size: 0.8rem;
+}
+
+.todo-text {
+  font-size: 1.1rem;
+  color: var(--text-bright);
+  flex: 1;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+.todo-item.done .todo-text {
+  text-decoration: line-through;
+  opacity: 0.5;
+}
+
+/* Delete Button */
+.todo-delete-btn {
+  opacity: 0;
+  pointer-events: none;
+  background: none;
+  border: none;
+  color: var(--error-color);
+  padding: 0 0.5rem;
+  cursor: pointer;
+  transition: opacity 0.2s;
+  font-size: 0.85rem;
+}
+
+/* Todo Input Area */
+.todo-input-container {
+  padding-top: var(--spacing-sm);
+  border-top: 1px solid var(--border-color);
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  width: 100%;
+  /* Ensure full width */
+  margin-top: auto;
+  /* Push to bottom if flex child */
+}
+
+.todo-input {
+  flex: 1;
+  background: transparent;
+  border: none;
+  border-bottom: 2px solid var(--border-color);
+  color: var(--text-bright);
+  padding: 0.4rem 0;
+  font-size: 1rem;
+  font-family: var(--font-body);
+}
+
+.todo-input:focus {
+  outline: none;
+  border-bottom-color: var(--accent-color);
+}
+
+.todo-add-btn-small {
+  background: none;
+  border: none;
+  color: var(--accent-color);
+  cursor: pointer;
+  font-size: 1.2rem;
+}
+
+/* Light Mode Overrides for Specific Dashboard Colors if needed */
+
+@media (max-width: 768px) {
+  /* 移动端隐藏首页的时间卡片和Todo面板 */
+  .dashboard-clock-card,
+  .dashboard-stats {
+    display: none !important;
+  }
+
+  /* 调整移动端首页欢迎语布局 */
+  .dashboard-intro {
+    height: auto;
+    gap: 0;
+    margin-bottom: var(--spacing-md);
+  }
+
+  /* 适当减小欢迎语字号 */
+  .welcome-title {
+    font-size: 2.5rem;
+    padding-left: 1rem;
+  }
+
+  .welcome-subtitle {
+    padding-left: 1rem;
+    margin-top: 0.5rem;
+  }
+}
diff --git a/assets/styles/_layout.css b/assets/styles/_layout.css
new file mode 100644
index 0000000000000000000000000000000000000000..41a88e37cf4745a8ca2f70b308c2f79d726f269f
--- /dev/null
+++ b/assets/styles/_layout.css
@@ -0,0 +1,101 @@
+/* ============================================
+   Page Layout & Containers
+   ============================================ */
+
+/* 页面容器 */
+.page {
+  position: relative;
+  width: 100%;
+  display: none;
+  flex-direction: column;
+  align-items: center;
+  padding-top: 2rem;
+  padding-left: 0.5rem;
+  padding-right: 0.5rem;
+}
+
+.page.active {
+  display: flex;
+}
+
+/* 页面模板容器（friends/articles/projects 等） */
+.page-template {
+  width: 100%;
+  max-width: var(--page-max-width);
+  margin: 0 auto;
+}
+
+/* 欢迎区域 - Design A (Minimalist) */
+.welcome-section {
+  width: 100%;
+  max-width: var(--page-max-width);
+  margin: 0 auto 1.2rem auto;
+  padding: 0 var(--spacing-lg);
+  text-align: left;
+  position: relative;
+  z-index: 5;
+  display: flex;
+  justify-content: space-between;
+  align-items: flex-end;
+  flex-wrap: wrap;
+  gap: var(--spacing-md);
+}
+
+.welcome-section-main {
+  flex: 1;
+  min-width: 220px;
+}
+
+.welcome-section-side {
+  flex: 0 0 auto;
+}
+
+.welcome-section h2 {
+  font-size: 1.75rem;
+  color: var(--text-bright);
+  margin-bottom: 0.25rem;
+  letter-spacing: 0.5px;
+  transition: color 0.3s ease;
+}
+
+.welcome-section h3 {
+  font-family: var(--font-body);
+  font-weight: 400;
+  font-size: 1rem;
+  margin-bottom: 0.5rem;
+  letter-spacing: 0.3px;
+  color: var(--text-muted);
+  position: relative;
+  display: block;
+}
+
+.welcome-section h3::before {
+  display: none;
+}
+
+.welcome-section .subtitle {
+  color: var(--text-muted);
+  font-size: 0.95rem;
+  line-height: 1.5;
+  transition: color 0.3s ease;
+}
+
+/* bookmarks：标题后追加"更新时间"小字 */
+.welcome-title-row {
+  display: flex;
+  align-items: baseline;
+  flex-wrap: wrap;
+  gap: 0.6rem;
+  margin-bottom: 0.5rem;
+}
+
+.welcome-title-row h2 {
+  margin: 0;
+}
+
+.page-updated-inline {
+  color: var(--text-muted);
+  font-size: 0.9rem;
+  opacity: 0.85;
+  white-space: nowrap;
+}
diff --git a/assets/styles/_main.css b/assets/styles/_main.css
new file mode 100644
index 0000000000000000000000000000000000000000..1fb925857189e368fb6e3a38bda37d5ccd5101d5
--- /dev/null
+++ b/assets/styles/_main.css
@@ -0,0 +1,1448 @@
+/* ============================================
+   Main CSS - 分类层级、热力图、响应式
+   ============================================
+   
+   此文件包含以下未独立拆分的样式：
+   - 分类层级样式 (.category, .category-level-*, .group-*)
+   - GitHub 热力图 (.gh-*)
+   - 全局响应式设计 (@media)
+   - 搜索结果区域 (#search-results)
+   
+   ============================================ */
+
+/* 分类样式 */
+.category {
+  background: linear-gradient(145deg, var(--card-bg-gradient-1), var(--card-bg-gradient-2));
+  border-radius: var(--radius-xl);
+  padding: 1rem;
+  margin: 0 auto 1.2rem auto;
+  width: 100%;
+  max-width: var(--page-max-width);
+  position: relative;
+  z-index: 1;
+  opacity: 1;
+  box-shadow: 0 4px 20px var(--shadow-color);
+  border: 1px solid var(--border-color);
+  transition:
+    background var(--transition-normal),
+    box-shadow var(--transition-normal);
+}
+
+/* 分类标题容器 */
+.category-header {
+  border-radius: var(--radius-md);
+  padding: 0.4rem;
+  margin: -0.4rem -0.4rem 0.8rem -0.4rem;
+  transition: all var(--transition-normal);
+}
+
+/* 标题前图标固定宽度：避免不同图标宽度导致标题文本不对齐 */
+.category-header [data-editable='category-name'] > i,
+.group-header [data-editable='group-name'] > i {
+  width: 1.25em;
+  min-width: 1.25em;
+  text-align: center;
+  flex: 0 0 1.25em;
+}
+
+/* 分组标题容器：与分类保持一致的悬浮动效基础 */
+.group-header {
+  border-radius: var(--radius-md);
+  transition: all var(--transition-normal);
+}
+
+/* 仅可折叠的标题显示交互态 */
+.category-header[data-toggle='category'],
+.group-header[data-toggle='group'] {
+  cursor: pointer;
+  user-select: none;
+}
+
+.category-header[data-toggle='category']:hover {
+  transform: translateY(-2px);
+  background: linear-gradient(145deg, rgba(255, 255, 255, 0.02), rgba(255, 255, 255, 0.01));
+}
+
+.group-header[data-toggle='group']:hover {
+  transform: translateY(-2px);
+  background: linear-gradient(145deg, rgba(255, 255, 255, 0.02), rgba(255, 255, 255, 0.01));
+}
+
+.category-header[data-toggle='category']:active {
+  transform: translateY(0);
+}
+
+.group-header[data-toggle='group']:active {
+  transform: translateY(0);
+}
+
+.category h2 {
+  font-size: 1.2rem;
+  margin-bottom: 0;
+  color: var(--text-bright);
+  display: flex;
+  align-items: center;
+  gap: 0.8rem;
+  letter-spacing: 0.3px;
+  transition: color 0.3s ease;
+}
+
+.category h2 > i {
+  color: var(--accent-color);
+  font-size: 1.3rem;
+  transition: all 0.3s ease;
+}
+
+.category-header[data-toggle='category']:hover h2 > i {
+  transform: scale(1.1);
+  color: var(--accent-hover);
+}
+
+/* 多层级嵌套样式 - 扁平化设计 */
+
+/* 通用重置：移除所有嵌套层级的卡片背景和边框 */
+.category-level-2,
+.category-level-3,
+.category-level-4,
+.group-level-3,
+.group-level-4 {
+  background: none;
+  border: none;
+  box-shadow: none;
+  padding: 0;
+  width: 100%;
+  margin: 0;
+}
+
+/* 嵌套层级指示线 (Hierarchy Indicator A) */
+.category-level-2::before,
+.category-level-3::before,
+.group-level-3::before,
+.category-level-4::before,
+.group-level-4::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  top: 0;
+  bottom: 0;
+  width: 2px;
+  background-color: var(--border-color);
+  opacity: 0.6;
+}
+
+/* 层级2: 子分类 */
+.category-level-2 {
+  margin-top: 0;
+  margin-bottom: 0;
+  padding-left: 1rem;
+  border-left: none;
+  position: relative;
+}
+
+/* 层级2: 标题样式 */
+.category-level-2 .category-header {
+  margin: 0 -0.5rem 1rem -0.5rem;
+  padding: 0.5rem;
+  background: none;
+  border-radius: var(--radius-md);
+}
+
+.category-level-2 .category-header h3 {
+  font-size: 1.1rem;
+  font-weight: 600;
+  color: var(--text-bright);
+  display: flex;
+  align-items: center;
+  gap: 0.8rem;
+}
+
+.category-level-2 .category-header h3 > i {
+  color: var(--accent-color);
+  font-size: 1.2rem;
+  opacity: 0.9;
+}
+
+/* 层级3: 分组 */
+.group-level-3,
+.category-level-3 {
+  margin-top: 0;
+  margin-bottom: 0;
+  padding-left: 1rem;
+  position: relative;
+}
+
+/* 层级3: 标题样式 */
+.group-level-3 .group-header,
+.category-level-3 .category-header {
+  margin: 0 0 0.8rem 0;
+  padding: 0.3rem 0;
+  background: none;
+}
+
+.group-level-3 .group-header h4,
+.category-level-3 .category-header h4 {
+  font-size: 1rem;
+  font-weight: 500;
+  color: var(--text-color);
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+}
+
+.group-level-3 .group-header h4 i,
+.category-level-3 .category-header h4 i {
+  color: var(--text-muted);
+  font-size: 1rem;
+}
+
+/* 层级4: 子分组 */
+.group-level-4,
+.category-level-4 {
+  margin-top: 0;
+  margin-bottom: 0;
+  padding-left: 1rem;
+  position: relative;
+}
+
+/* 嵌套层级间距：仅在同级相邻时增加间距，避免首项被额外下推 */
+.subcategories-container > .category-level-2 + .category-level-2 {
+  margin-top: 1rem;
+}
+
+.groups-container > .group-level-3 + .group-level-3,
+.groups-container > .category-level-3 + .category-level-3 {
+  margin-top: 0.8rem;
+}
+
+.subgroups-container > .group-level-4 + .group-level-4,
+.subcategories-container > .category-level-4 + .category-level-4 {
+  margin-top: 0.6rem;
+}
+
+/* 层级4: 标题样式 */
+.group-level-4 .group-header,
+.category-level-4 .category-header {
+  margin: 0 0 0.6rem 0;
+  padding: 0.2rem 0;
+  background: none;
+}
+
+.group-level-4 .group-header h5,
+.category-level-4 .category-header h5 {
+  font-size: 0.9rem;
+  font-weight: 500;
+  color: var(--text-muted);
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.group-level-4 .group-header h5 i,
+.category-level-4 .category-header h5 i {
+  font-size: 0.9rem;
+  opacity: 0.7;
+}
+
+/* 移除悬停时的缩放效果，保持简洁 */
+.category-level-2 .category-header:hover h3 > i,
+.group-level-3 .group-header:hover h4 i,
+.category-level-3 .category-header:hover h4 i,
+.group-level-4 .group-header:hover h5 i,
+.category-level-4 .category-header:hover h5 i {
+  transform: none;
+}
+
+/* 切换图标样式 */
+.category-header .toggle-icon,
+.group-header .toggle-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 20px;
+  height: 20px;
+  margin-left: auto;
+  color: var(--text-muted);
+  font-size: 0.9rem;
+}
+
+.category-header .toggle-icon i,
+.group-header .toggle-icon i {
+  transition:
+    transform 0.3s ease,
+    color 0.3s ease;
+  transform: rotate(0deg);
+}
+
+/* 展开态：图标旋转 180°（类似参考样式1） */
+.category:not(.collapsed) > .category-header .toggle-icon i,
+.group:not(.collapsed) > .group-header .toggle-icon i {
+  transform: rotate(180deg);
+  color: var(--text-bright);
+}
+
+.category-header[data-toggle='category']:hover .toggle-icon i,
+.group-header[data-toggle='group']:hover .toggle-icon i {
+  color: var(--accent-color);
+}
+
+/* 分类/分组折叠图标：桌面端默认隐藏，悬停/收起时显示，避免按钮过多 */
+@media (hover: hover) and (pointer: fine) {
+  .category-header .toggle-icon,
+  .group-header .toggle-icon {
+    opacity: 0;
+    transition: opacity 0.2s ease;
+  }
+
+  .category-header[data-toggle='category']:hover .toggle-icon,
+  .category.collapsed > .category-header .toggle-icon,
+  .group-header[data-toggle='group']:hover .toggle-icon,
+  .group.collapsed > .group-header .toggle-icon {
+    opacity: 1;
+  }
+}
+
+/* 展开/折叠动画 */
+.category-content,
+.group-content {
+  overflow: visible;
+  transition:
+    max-height 0.3s cubic-bezier(0.4, 0, 0.2, 1),
+    opacity 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+  max-height: 5000px;
+  opacity: 1;
+}
+
+.category.collapsed .category-content,
+.group.collapsed .group-content {
+  overflow: hidden;
+  max-height: 0;
+  opacity: 0;
+  margin-top: 0;
+}
+
+/* 收起状态下调整header的下边距 */
+.category.collapsed > .category-header {
+  margin-bottom: -0.5rem;
+}
+
+.category-level-2.collapsed > .category-header {
+  margin-bottom: 0;
+  border-bottom: none;
+}
+
+.group-level-3.collapsed > .group-header,
+.category-level-3.collapsed > .category-header {
+  margin-bottom: 0;
+}
+
+.group-level-4.collapsed > .group-header,
+.category-level-4.collapsed > .category-header {
+  margin-bottom: 0;
+}
+
+/* 收起态默认向下，无需额外旋转（保持 0deg） */
+
+/* 空内容提示 */
+.empty-content {
+  color: var(--text-muted);
+  font-style: italic;
+  text-align: center;
+  padding: 1rem;
+  font-size: 0.9rem;
+}
+
+/* 子容器样式 */
+.subcategories-container,
+.groups-container {
+  width: 100%;
+}
+
+/* 当分类同时包含子分类和站点时的样式优化 */
+.category-content .subcategories-container + .sites-grid {
+  margin-top: 1.2rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--border-color);
+}
+
+/* 当分类同时包含分组和站点时的样式优化 */
+.category-content .groups-container + .sites-grid {
+  margin-top: 1.2rem;
+  padding-top: 1rem;
+  border-top: 1px solid var(--border-color);
+}
+
+/* 子分类容器底部间距调整 */
+.category-content .subcategories-container:not(:last-child),
+.category-content .groups-container:not(:last-child) {
+  margin-bottom: 0.6rem;
+}
+
+/* 确保嵌套的网站网格正确显示 */
+.category-level-2 .sites-grid,
+.group-level-3 .sites-grid,
+.category-level-3 .sites-grid,
+.group-level-4 .sites-grid,
+.category-level-4 .sites-grid {
+  margin-top: 0;
+  gap: 0.75rem;
+  /* 保持与顶层一致的网格布局 */
+  grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+}
+
+/* 响应式设计 - 嵌套结构 */
+@media (max-width: 768px) {
+  .category-level-2 {
+    padding-left: 0.75rem;
+  }
+
+  .group-level-3,
+  .category-level-3 {
+    padding-left: 0.75rem;
+  }
+
+  .group-level-4,
+  .category-level-4 {
+    padding-left: 0.75rem;
+  }
+
+  .subcategories-container > .category-level-2 + .category-level-2 {
+    margin-top: 0.8rem;
+  }
+
+  .groups-container > .group-level-3 + .group-level-3,
+  .groups-container > .category-level-3 + .category-level-3 {
+    margin-top: 0.7rem;
+  }
+
+  .subgroups-container > .group-level-4 + .group-level-4,
+  .subcategories-container > .category-level-4 + .category-level-4 {
+    margin-top: 0.55rem;
+  }
+
+  .category-level-2 .sites-grid,
+  .group-level-3 .sites-grid,
+  .category-level-3 .sites-grid,
+  .group-level-4 .sites-grid,
+  .category-level-4 .sites-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: var(--spacing-sm);
+  }
+}
+
+@media (max-width: 480px) {
+  .category {
+    margin-left: 0.5rem;
+    margin-right: 0.5rem;
+    padding: 1rem;
+  }
+
+  .category-level-2,
+  .group-level-3,
+  .category-level-3 {
+    margin-left: 0;
+    padding-left: 0.75rem;
+    width: 100%;
+  }
+
+  .group-level-4,
+  .category-level-4 {
+    margin-left: 0;
+    padding-left: 0.75rem;
+    width: 100%;
+  }
+
+  .category-level-2 .sites-grid,
+  .group-level-3 .sites-grid,
+  .category-level-3 .sites-grid,
+  .group-level-4 .sites-grid,
+  .category-level-4 .sites-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 0.5rem;
+  }
+}
+
+/* projects：GitHub 热力图（github-calendar.js，底部展示） */
+.page-template-projects .gh-heatmap-category {
+  /* 外层已复用一级分类卡片（.category），这里仅保留热力图内部布局/色阶 */
+  --gh-text: var(--text-color);
+  --gh-text-muted: var(--text-muted);
+  --gh-level-0: rgba(255, 255, 255, 0.08);
+  --gh-level-1: rgba(55, 178, 77, 0.35);
+  --gh-level-2: rgba(55, 178, 77, 0.55);
+  --gh-level-3: rgba(55, 178, 77, 0.75);
+  --gh-level-4: rgba(55, 178, 77, 0.95);
+  --gh-radius: 3px;
+
+  margin: 0 auto 1.2rem auto;
+}
+
+.page-template-projects .gh-heatmap-wrapper {
+  margin-top: 0;
+}
+
+/* 浅色主题：更接近 GitHub 原色阶 */
+html.theme-preload .page-template-projects .gh-heatmap-category,
+body.light-theme .page-template-projects .gh-heatmap-category {
+  /* 浅色主题下，空格子需要比背景更明显一点 */
+  --gh-level-0: #d8dee4;
+  --gh-level-1: #9be9a8;
+  --gh-level-2: #40c463;
+  --gh-level-3: #30a14e;
+  --gh-level-4: #216e39;
+}
+
+/* 标题中的用户名（@xxx）更弱化一点，像副标题 */
+.page-template-projects .gh-heatmap-username {
+  color: var(--text-muted);
+  font-weight: 400;
+  margin-left: 0.35rem;
+}
+
+/* 使用一级分类标题的排版节奏，略收紧热力图区域 */
+.page-template-projects .gh-heatmap-category .category-header {
+  margin-bottom: 0.8rem;
+}
+
+/* 标题行：左侧标题 + 右侧 legend（不占内容区高度） */
+.page-template-projects .gh-heatmap-category .gh-heatmap-header {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 0.8rem;
+}
+
+.page-template-projects .gh-heatmap-category .gh-heatmap-header h2 {
+  margin: 0;
+}
+
+/* 让 legend 与标题体系保持一致：放在标题区右侧 */
+.page-template-projects .gh-heatmap-category .gh-legend {
+  justify-content: flex-end;
+  margin: 0;
+}
+
+.page-template-projects .gh-header {
+  display: none;
+}
+
+.page-template-projects .gh-legend {
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  font-size: 0.75rem;
+  color: var(--gh-text-muted);
+  white-space: nowrap;
+}
+
+/* heatmap：移动端标题/legend 文本简写 */
+.gh-text-mobile {
+  display: none;
+}
+
+@media (max-width: 480px) {
+  .gh-text-desktop {
+    display: none;
+  }
+
+  .gh-text-mobile {
+    display: inline;
+  }
+
+  .page-template-projects .gh-heatmap-category .gh-heatmap-header {
+    flex-wrap: wrap;
+  }
+
+  .page-template-projects .gh-heatmap-category .gh-legend {
+    gap: 2px;
+    font-size: 0.7rem;
+  }
+
+  .page-template-projects .gh-legend-item {
+    width: 8px;
+    height: 8px;
+  }
+}
+
+.page-template-projects .gh-legend-item {
+  width: 10px;
+  height: 10px;
+  border-radius: 2px;
+}
+
+.page-template-projects .gh-legend .level-0 {
+  background-color: var(--gh-level-0);
+}
+
+.page-template-projects .gh-legend .level-1 {
+  background-color: var(--gh-level-1);
+}
+
+.page-template-projects .gh-legend .level-2 {
+  background-color: var(--gh-level-2);
+}
+
+.page-template-projects .gh-legend .level-3 {
+  background-color: var(--gh-level-3);
+}
+
+.page-template-projects .gh-legend .level-4 {
+  background-color: var(--gh-level-4);
+}
+
+/* github-calendar 注入的内容容器 */
+.page-template-projects .gh-calendar {
+  border: none !important;
+  min-height: 0;
+  width: 100%;
+  /* 构建期注入：避免 flex 居中导致内容超宽“撑破卡片” */
+  display: block;
+}
+
+/* 顶部统计标题：XXX contributions in the last year */
+.page-template-projects .gh-calendar #js-contribution-activity-description {
+  /* 注意：全局 .category h2 会把 h2 设为 flex，导致“看起来左对齐”。这里强制回退为 block。 */
+  display: block;
+  width: 100%;
+  text-align: center;
+  margin: 0 0 12px 0;
+}
+
+/* 外层包裹：强制占满卡片宽度，滚动发生在内部 */
+.page-template-projects .gh-calendar .graph-before-activity-overview {
+  width: 100%;
+}
+
+/* 允许移动端横向滚动查看（GitHub 风格） */
+.page-template-projects .gh-calendar .js-calendar-graph {
+  width: 100%;
+  /* 构建期注入 GitHub 原生 table：滚动交给内层容器，避免裁剪 */
+  display: block;
+}
+
+/* GitHub 原生 markup：通常在 .js-calendar-graph 内有一个 div 设置 overflow-x */
+.page-template-projects .gh-calendar .js-calendar-graph > div {
+  width: 100%;
+  max-width: 100%;
+  overflow-x: auto;
+  overflow-y: hidden;
+  -webkit-overflow-scrolling: touch;
+  /* 由 table 的 margin:auto 来实现“可居中 + 可滚动时左对齐起始列” */
+  display: block;
+  padding-bottom: 10px;
+}
+
+.page-template-projects .gh-calendar .js-calendar-graph-svg {
+  width: 100%;
+  height: auto;
+}
+
+/* 覆盖每个方块的颜色（依赖 github-calendar 的 data-level） */
+.page-template-projects .gh-calendar .day {
+  rx: var(--gh-radius);
+  ry: var(--gh-radius);
+  outline: none;
+}
+
+.page-template-projects .gh-calendar .day[data-level='0'] {
+  fill: var(--gh-level-0);
+}
+
+.page-template-projects .gh-calendar .day[data-level='1'] {
+  fill: var(--gh-level-1);
+}
+
+.page-template-projects .gh-calendar .day[data-level='2'] {
+  fill: var(--gh-level-2);
+}
+
+.page-template-projects .gh-calendar .day[data-level='3'] {
+  fill: var(--gh-level-3);
+}
+
+.page-template-projects .gh-calendar .day[data-level='4'] {
+  fill: var(--gh-level-4);
+}
+
+.page-template-projects .gh-calendar text {
+  fill: var(--gh-text-muted);
+  font-size: 10px;
+}
+
+/* 去掉库自带 footer（更简洁） */
+.page-template-projects .gh-calendar .contrib-footer {
+  display: none !important;
+}
+
+.page-template-projects .gh-calendar.gh-calendar-error {
+  color: var(--gh-text-muted);
+  font-size: 0.85rem;
+}
+
+/* github-calendar（HTML table 版）：适配 ContributionCalendar-* 类名 */
+.page-template-projects .gh-calendar table {
+  /* 让热力图在卡片内尽量铺满宽度；需要时仍可横向滚动 */
+  /* 关键：避免 table 按列拉伸导致 day 变成长方形 */
+  display: table;
+  /* 不强制占满：保持自然宽度，并在容器内居中 */
+  width: max-content;
+  min-width: max-content;
+  max-width: none;
+  table-layout: auto;
+  border-collapse: separate;
+  border-spacing: 5px !important;
+  /* table 未超宽时居中；超宽时 margin auto 会退化为 0（滚动起始列左对齐） */
+  margin: 0 auto;
+}
+
+/* GitHub 原生 table：thead 行内写死 height:15px，需强制更高以避免月份 label 压到格子 */
+.page-template-projects .gh-calendar table thead tr {
+  height: 20px !important;
+}
+
+/* GitHub 原生 table 的月份 label 使用 absolute 定位，需要为 thead 行预留高度，避免与格子重叠 */
+.page-template-projects .gh-calendar .ContributionCalendar-label {
+  height: 16px;
+  position: relative;
+  padding-bottom: 4px;
+  font-size: 10px;
+  line-height: 10px;
+  font-weight: 400;
+  vertical-align: bottom;
+}
+
+@media (max-width: 600px) {
+  /* 移动端：格子更紧凑，减少横向滚动压力 */
+  .page-template-projects .gh-calendar table {
+    border-spacing: 3px !important;
+  }
+
+  .page-template-projects .gh-calendar .ContributionCalendar-day {
+    width: 12px;
+    height: 12px;
+    min-width: 12px;
+    min-height: 12px;
+  }
+
+  .page-template-projects .gh-calendar #js-contribution-activity-description {
+    font-size: 0.95rem;
+  }
+}
+
+/* GitHub 原生 footer：保留“Learn how we count contributions”，隐藏右侧自带 legend（避免与自定义 legend 重复） */
+.page-template-projects .gh-calendar .float-right.color-fg-muted.d-flex.flex-items-center {
+  display: none !important;
+}
+
+/* 按需求：去除 “Learn how we count contributions” */
+.page-template-projects .gh-calendar .float-left {
+  display: none !important;
+}
+
+/* Link--muted 目前不展示（float-left 已隐藏）；保留基础链接色由下方 a 规则兜底 */
+
+.page-template-projects .gh-calendar .ContributionCalendar-day {
+  /* 固定正方形，防止被 table 列宽拉伸 */
+  width: 15px;
+  height: 15px;
+  min-width: 15px;
+  min-height: 15px;
+  aspect-ratio: 1 / 1;
+  border-radius: var(--gh-radius);
+  background-color: var(--gh-level-0);
+}
+
+.page-template-projects .gh-calendar .ContributionCalendar-day[data-level='0'] {
+  background-color: var(--gh-level-0) !important;
+}
+
+.page-template-projects .gh-calendar .ContributionCalendar-day[data-level='1'] {
+  background-color: var(--gh-level-1) !important;
+}
+
+.page-template-projects .gh-calendar .ContributionCalendar-day[data-level='2'] {
+  background-color: var(--gh-level-2) !important;
+}
+
+.page-template-projects .gh-calendar .ContributionCalendar-day[data-level='3'] {
+  background-color: var(--gh-level-3) !important;
+}
+
+.page-template-projects .gh-calendar .ContributionCalendar-day[data-level='4'] {
+  background-color: var(--gh-level-4) !important;
+}
+
+/* a11y 跳转链接：视觉隐藏（保留可访问性） */
+.page-template-projects .gh-calendar a[href^='#year-list'],
+.page-template-projects .gh-calendar a[href*='year-list'],
+.page-template-projects .gh-calendar a[href*='contributions-year'] {
+  /* GitHub 注入的 "Skip to contributions year list"（常见为 show-on-focus） */
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0, 0, 0, 0);
+  white-space: nowrap;
+  border: 0;
+}
+
+/* 响应式设计 */
+@media (max-width: 1200px) {
+  .welcome-section {
+    padding: 0 var(--spacing-lg);
+    margin-bottom: 2rem;
+  }
+
+  .category {
+    max-width: 1100px;
+    margin: 0 auto 2.5rem auto;
+  }
+}
+
+@media (max-width: 768px) {
+  .mobile-buttons {
+    display: flex;
+  }
+
+  :root {
+    /* 与移动端搜索框高度更贴合（搜索框更高一些，菜单按钮同步放大） */
+    --mobile-top-button-size: 2.9rem;
+  }
+
+  .menu-toggle {
+    width: var(--mobile-top-button-size);
+    height: var(--mobile-top-button-size);
+    background: rgba(var(--card-bg-rgb), 0.65);
+    border: 1px solid var(--border-color);
+    border-radius: var(--radius-lg);
+    backdrop-filter: blur(12px);
+    -webkit-backdrop-filter: blur(12px);
+    box-shadow: 0 4px 16px var(--shadow-color);
+  }
+
+  /* 移动端：右下角磁贴与侧边栏按钮磁贴统一风格 */
+  .theme-toggle,
+  .category-toggle {
+    width: var(--mobile-top-button-size);
+    height: var(--mobile-top-button-size);
+    background: rgba(var(--card-bg-rgb), 0.65);
+    border: 1px solid var(--border-color);
+    border-radius: var(--radius-lg);
+    backdrop-filter: blur(12px);
+    -webkit-backdrop-filter: blur(12px);
+    box-shadow: 0 4px 16px var(--shadow-color);
+    transition: all var(--transition-normal);
+    transition-timing-function: var(--transition-bounce);
+  }
+
+  .theme-toggle:hover,
+  .category-toggle:hover {
+    transform: translateY(-2px);
+    background: rgba(var(--card-bg-rgb), 0.75);
+    box-shadow: 0 6px 20px var(--shadow-color);
+    color: var(--accent-color);
+  }
+
+  .theme-toggle:active,
+  .category-toggle:active {
+    transform: translateY(0);
+    box-shadow: 0 2px 8px var(--shadow-color);
+  }
+
+  main.content {
+    margin-left: 0;
+    width: 100vw;
+    max-width: 100vw;
+    padding-top: calc(var(--spacing-md) + var(--mobile-top-button-size) + var(--spacing-sm));
+    padding-top: calc(
+      env(safe-area-inset-top) + var(--spacing-md) + var(--mobile-top-button-size) +
+        var(--spacing-sm)
+    );
+    /* 缩短分类卡片与页面边缘的左右留白，扩大分类卡片可用宽度 */
+    padding-left: calc(var(--spacing-sm) + var(--spacing-xs));
+    padding-right: calc(var(--spacing-sm) + var(--spacing-xs));
+  }
+
+  .sidebar {
+    transform: translateX(-100%);
+    box-shadow: none;
+    transition: transform 0.3s cubic-bezier(0.4, 0, 0.2, 1);
+    max-width: 100vw;
+    overflow-x: hidden;
+  }
+
+  .sidebar .logo {
+    padding-top: 1.5rem;
+    display: flex;
+    align-items: center;
+    height: 60px;
+  }
+
+  /* 移动端下隐藏侧边栏折叠按钮 */
+  .sidebar-toggle {
+    display: none;
+  }
+
+  .sidebar.active {
+    transform: translateX(0);
+    box-shadow: 2px 0 10px var(--shadow-color);
+    z-index: 1000;
+    /* 增加侧边栏激活时的z-index，确保显示在按钮之上 */
+  }
+
+  /* 重置移动端下的侧边栏展开状态 */
+  .sidebar.collapsed {
+    width: var(--sidebar-width);
+  }
+
+  .sidebar.collapsed .logo h1,
+  .sidebar.collapsed .nav-item .nav-text,
+  .sidebar.collapsed .nav-item .external-icon {
+    opacity: 1;
+    transform: none;
+    width: auto;
+  }
+
+  .sidebar.collapsed .sidebar-footer {
+    height: auto;
+    padding: 1rem 1.2rem;
+    visibility: visible;
+    pointer-events: auto;
+    border-top: 1px solid var(--border-color);
+  }
+
+  .sidebar.collapsed .sidebar-social {
+    padding: 0.2rem 1.2rem 0.8rem;
+    flex-direction: row;
+  }
+
+  .sidebar.collapsed .nav-item {
+    padding: 0.6rem 0.8rem;
+    justify-content: flex-start;
+  }
+
+  .sidebar.collapsed .nav-item .icon-container {
+    margin-right: 1rem;
+  }
+
+  /* 移动端：搜索框常驻显示（与侧边栏按钮同一行，无需“悬浮磁贴”） */
+  .search-container {
+    position: fixed;
+    top: var(--spacing-md);
+    top: calc(env(safe-area-inset-top) + var(--spacing-md));
+    /* 给左侧菜单按钮留出空间 */
+    left: calc(var(--spacing-md) + var(--mobile-top-button-size) + var(--spacing-sm));
+    right: var(--spacing-md);
+    left: calc(
+      env(safe-area-inset-left) + var(--spacing-md) + var(--mobile-top-button-size) +
+        var(--spacing-sm)
+    );
+    right: calc(env(safe-area-inset-right) + var(--spacing-md));
+    width: auto;
+    padding: 0;
+    margin-bottom: 0;
+    box-shadow: none;
+    z-index: 900;
+  }
+
+  .search-box {
+    max-width: 100%;
+  }
+
+  .search-box input {
+    padding: 0.8rem 3rem 0.8rem 1rem;
+    font-size: 0.95rem;
+  }
+
+  .search-box::after {
+    right: 0.8rem;
+  }
+
+  .search-shortcut-hint {
+    right: 1.2rem;
+    font-size: 0.72rem;
+    padding: 0.1rem 0.35rem;
+  }
+
+  .search-engine-button {
+    width: 104px;
+    flex: 0 0 104px;
+    padding: 0 0.6rem;
+  }
+
+  .sidebar .logo h1,
+  .sidebar .nav-item span {
+    opacity: 1;
+    display: block;
+  }
+
+  /* 欢迎区域样式 */
+  .welcome-section {
+    padding: 0 1rem;
+    margin-top: 1rem;
+    /* 增加顶部间距 */
+  }
+
+  .page {
+    padding-left: 0.15rem;
+    padding-right: 0.15rem;
+  }
+
+  .welcome-section h2 {
+    font-size: 1.5rem;
+  }
+
+  .welcome-section h3 {
+    font-size: 1rem;
+    background: none;
+    -webkit-background-clip: border-box;
+    background-clip: border-box;
+    animation: none;
+    color: var(--text-muted);
+  }
+
+  /* 移动端分类切换按钮 */
+  .category-toggle {
+    bottom: 4rem;
+    bottom: calc(env(safe-area-inset-bottom) + 4rem);
+    right: 1rem;
+    right: calc(env(safe-area-inset-right) + 1rem);
+  }
+
+  /* 移动端：隐藏搜索按钮（未删除，仅隐藏；搜索框常驻） */
+  .search-toggle {
+    display: none;
+  }
+
+  /* 分类样式优化 */
+  .category {
+    margin: 0 auto var(--spacing-lg) auto;
+    padding: var(--spacing-md);
+    width: 100%;
+  }
+
+  .sites-grid {
+    gap: var(--spacing-sm);
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .site-card {
+    /* 移动端保持与客户端一致：横排卡片（图标在左，文本左对齐） */
+    flex-direction: row;
+    align-items: center;
+    text-align: left;
+    padding: 0.75rem 0.65rem;
+    gap: 0.6rem;
+  }
+
+  .site-card-icon {
+    width: 2.2rem;
+    height: 2.2rem;
+  }
+
+  .site-card .site-icon {
+    font-size: 1.5rem;
+  }
+
+  .site-card .favicon-icon,
+  .site-card .icon-placeholder,
+  .site-card .icon-fallback,
+  .site-card .icon-container {
+    width: 1.5rem;
+    height: 1.5rem;
+  }
+
+  .site-card .icon-placeholder,
+  .site-card .icon-fallback {
+    line-height: 1.5rem;
+    font-size: 1.3rem;
+  }
+
+  .site-card-content {
+    text-align: left;
+  }
+
+  .site-card h3 {
+    font-size: 1rem;
+    margin-bottom: 0.25rem;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    max-width: 100%;
+  }
+
+  .site-card p {
+    font-size: 0.9rem;
+    line-height: 1.4;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+
+  /* 在移动端的主题切换按钮 */
+  .theme-toggle {
+    bottom: 1rem;
+    bottom: calc(env(safe-area-inset-bottom) + 1rem);
+    right: 1rem;
+    right: calc(env(safe-area-inset-right) + 1rem);
+  }
+
+  .sidebar .submenu {
+    margin-left: 1rem;
+  }
+
+  .sidebar.active .submenu-item {
+    padding: 0.5rem 0.6rem;
+  }
+
+  /* 确保移动设备上子菜单不会出现漏出问题 */
+  .sidebar.collapsed .submenu {
+    display: none;
+  }
+}
+
+@media (max-width: 480px) {
+  .welcome-section {
+    padding: 0 1rem;
+    margin-bottom: 1rem;
+  }
+
+  .category {
+    margin: 0 auto 1.3rem auto;
+    padding: 0.95rem;
+    width: 100%;
+  }
+
+  .search-container {
+    left: calc(var(--spacing-md) + var(--mobile-top-button-size) + var(--spacing-sm));
+    right: var(--spacing-md);
+    left: calc(
+      env(safe-area-inset-left) + var(--spacing-md) + var(--mobile-top-button-size) +
+        var(--spacing-sm)
+    );
+    right: calc(env(safe-area-inset-right) + var(--spacing-md));
+  }
+
+  .page {
+    padding-top: 1rem;
+    padding-left: 0.1rem;
+    padding-right: 0.1rem;
+  }
+
+  .sites-grid {
+    gap: 0.5rem;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .site-card {
+    padding: 0.75rem 0.5rem;
+    gap: 0.5rem;
+  }
+
+  .site-card-icon {
+    width: 2rem;
+    height: 2rem;
+  }
+
+  .site-card .site-icon {
+    font-size: 1.3rem;
+  }
+
+  .site-card .favicon-icon,
+  .site-card .icon-placeholder,
+  .site-card .icon-fallback,
+  .site-card .icon-container {
+    width: 1.35rem;
+    height: 1.35rem;
+  }
+
+  .site-card .icon-placeholder,
+  .site-card .icon-fallback {
+    line-height: 1.35rem;
+    font-size: 1.2rem;
+  }
+
+  .site-card h3 {
+    font-size: 1rem;
+    margin-bottom: 0.3rem;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    max-width: 100%;
+  }
+
+  .site-card p {
+    font-size: 0.9rem;
+    line-height: 1.2;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+}
+
+@media (max-width: 400px) {
+  .category {
+    padding: 0.85rem;
+    margin: 0 0.05rem 1.2rem 0.05rem;
+    width: calc(100% - 0.1rem);
+  }
+
+  .sites-grid {
+    gap: 0.4rem;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .site-card {
+    padding: 0.6rem 0.4rem;
+    gap: 0.45rem;
+  }
+
+  .site-card-icon {
+    width: 1.9rem;
+    height: 1.9rem;
+  }
+
+  .site-card .site-icon {
+    font-size: 1.2rem;
+  }
+
+  .site-card .favicon-icon,
+  .site-card .icon-placeholder,
+  .site-card .icon-fallback,
+  .site-card .icon-container {
+    width: 1.25rem;
+    height: 1.25rem;
+  }
+
+  .site-card .icon-placeholder,
+  .site-card .icon-fallback {
+    line-height: 1.25rem;
+    font-size: 1.1rem;
+  }
+
+  .site-card h3 {
+    font-size: 1rem;
+    margin-bottom: 0.25rem;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    max-width: 100%;
+  }
+
+  .site-card p {
+    font-size: 0.9rem;
+    line-height: 1.15;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+  }
+}
+
+/* 搜索结果页面 */
+#search-results {
+  position: relative;
+  width: 100%;
+  display: none;
+  flex-direction: column;
+  align-items: center;
+  /* 保持在搜索框之下，避免滚动时覆盖 sticky 的搜索容器 */
+  z-index: 1;
+  transform: none !important;
+  /* 确保没有变换 */
+  min-height: 400px;
+  /* 确保最小高度，防止内容过少时的布局跳动 */
+}
+
+#search-results.active {
+  display: flex;
+  animation: fadeIn 0.3s ease-out forwards;
+}
+
+/* 搜索结果区域 */
+.search-section {
+  width: 100%;
+  max-width: var(--page-max-width);
+  margin: 0 auto 2.5rem auto;
+  position: relative;
+  z-index: 1;
+  transform: none !important;
+  opacity: 1 !important;
+}
+
+/* 确保搜索结果中的网格有正确的间距 */
+.search-section .sites-grid {
+  margin-top: 1rem;
+}
+
+/* 搜索结果页：按来源页面复用对应网格规则（方案 2：复用原卡片 DOM） */
+#search-results [data-section='projects'] .sites-grid {
+  grid-template-columns: repeat(auto-fill, minmax(320px, 1fr));
+  gap: 24px;
+}
+
+#search-results [data-section='articles'] .sites-grid {
+  grid-template-columns: repeat(4, minmax(0, 1fr));
+}
+
+@media (max-width: 1024px) {
+  #search-results [data-section='articles'] .sites-grid {
+    grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+  }
+}
+
+@media (max-width: 480px) {
+  #search-results [data-section='articles'] .sites-grid {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    gap: 0.5rem;
+  }
+}
+
+/* 确保搜索结果中的卡片样式一致 */
+.search-section .site-card {
+  max-width: 100%;
+}
+
+/* 加载中动画 */
+.page {
+  opacity: 0;
+  transition: opacity 0.3s ease;
+}
+
+.page.active {
+  opacity: 1;
+}
+
+/* 模态框动画 */
+@keyframes modalFadeIn {
+  from {
+    opacity: 0;
+  }
+
+  to {
+    opacity: 1;
+  }
+}
+
+@keyframes modalContentShow {
+  from {
+    opacity: 0;
+    transform: scale(0.9);
+  }
+
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+.sites-grid {
+  transition: gap 0.3s ease;
+}
+
+/* 侧边栏底部：社交图标（位于 sidebar-footer 上方） */
+.sidebar-social {
+  grid-area: social;
+  padding: 0.2rem 1.2rem 0.8rem;
+  display: flex;
+  justify-content: center;
+  flex-wrap: wrap;
+  gap: 0.9rem;
+}
+
+.social-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0.35rem;
+  border-radius: var(--radius-full);
+  color: var(--nav-item-color);
+  text-decoration: none;
+  transition:
+    color var(--transition-fast),
+    transform var(--transition-fast);
+}
+
+.social-icon:hover {
+  color: var(--accent-color);
+  transform: translateY(-1px);
+}
+
+.social-icon:active {
+  transform: translateY(0);
+}
+
+.social-icon:focus-visible {
+  outline: 2px solid rgba(118, 148, 185, 0.35);
+  outline-offset: 2px;
+}
+
+.social-icon i {
+  width: auto;
+  font-size: 1.2rem;
+}
+
+/* 侧边栏底部：版权信息 */
+.sidebar-footer {
+  grid-area: footer;
+  padding: 1rem 1.2rem;
+  padding-bottom: calc(1rem + env(safe-area-inset-bottom));
+  text-align: center;
+  color: var(--text-muted);
+  font-size: 0.85rem;
+  border-top: 1px solid var(--border-color);
+  background-color: var(--sidebar-bg);
+  /* 使用变量 */
+  transition:
+    background-color 0.3s ease,
+    color 0.3s ease,
+    opacity 0.3s ease;
+}
+
+.sidebar-footer .copyright {
+  margin: 0;
+}
+
+.sidebar.collapsed .sidebar-social {
+  padding: 0.2rem 0.5rem 0.8rem;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.6rem;
+}
+
+.copyright a {
+  color: var(--accent-color);
+  text-decoration: none;
+  transition: all 0.3s ease;
+}
+
+.copyright a:hover {
+  color: var(--accent-hover);
+  text-decoration: underline;
+}
+
+/* 导航项包装器 - 包含导航项和子菜单 */
+.nav-item-wrapper {
+  position: relative;
+  display: flex;
+  flex-direction: column;
+  width: 100%;
+}
+
+/* 子菜单容器 */
+.submenu {
+  max-height: 0;
+  overflow: hidden;
+  transition: max-height 0.3s ease;
+  margin-left: 1.5rem;
+  opacity: 0;
+  visibility: hidden;
+}
+
+/* 子菜单展开状态 */
+.nav-item-wrapper.expanded .submenu {
+  max-height: none;
+  overflow: visible;
+  opacity: 1;
+  visibility: visible;
+}
diff --git a/assets/styles/_modal.css b/assets/styles/_modal.css
new file mode 100644
index 0000000000000000000000000000000000000000..198e92796acce9ae2bd002581a7a09d869a19a4d
--- /dev/null
+++ b/assets/styles/_modal.css
@@ -0,0 +1,152 @@
+/* Modal & Forms */
+
+/* 模态框样式 */
+.modal {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background-color: rgba(0, 0, 0, 0.6);
+  display: none;
+  justify-content: center;
+  align-items: center;
+  z-index: 1000;
+}
+
+.modal.active {
+  display: flex;
+  animation: modalFadeIn 0.3s ease-out forwards;
+}
+
+.modal-content {
+  background-color: var(--sidebar-bg);
+  border-radius: var(--radius-xl);
+  padding: var(--spacing-xl);
+  width: 90%;
+  max-width: 520px;
+  position: relative;
+  box-shadow: 0 8px 32px var(--shadow-color);
+  transform: scale(0.95);
+  opacity: 0;
+  animation: modalContentShow 0.3s ease-out forwards;
+  transition: background-color 0.3s ease;
+}
+
+.modal-header {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  margin-bottom: 2rem;
+}
+
+.modal-header h3 {
+  color: var(--text-bright);
+  font-size: 1.3rem;
+  letter-spacing: 0.3px;
+  font-weight: 500;
+  transition: color 0.3s ease;
+}
+
+.close-modal {
+  background: none;
+  border: none;
+  color: var(--text-muted);
+  cursor: pointer;
+  font-size: 1.5rem;
+  padding: var(--spacing-sm);
+  transition: all var(--transition-normal);
+  border-radius: var(--radius-md);
+}
+
+.close-modal:hover {
+  color: var(--text-bright);
+  background-color: var(--secondary-bg);
+}
+
+/* 表单样式 */
+.site-form {
+  display: flex;
+  flex-direction: column;
+  gap: 1.2rem;
+}
+
+.form-group {
+  display: flex;
+  flex-direction: column;
+  gap: 0.6rem;
+}
+
+.form-group label {
+  color: var(--text-muted);
+  font-size: 0.95rem;
+  letter-spacing: 0.2px;
+  transition: color 0.3s ease;
+}
+
+.form-group input,
+.form-group select {
+  background-color: var(--secondary-bg);
+  border: 1px solid transparent;
+  border-radius: var(--radius-md);
+  padding: var(--spacing-md) var(--spacing-lg);
+  color: var(--text-color);
+  font-size: 1rem;
+  transition: all var(--transition-normal);
+  box-shadow: 0 2px 6px var(--shadow-color);
+}
+
+.form-group input:focus,
+.form-group select:focus {
+  outline: none;
+  background-color: var(--secondary-bg);
+  border-color: var(--accent-color);
+  box-shadow: 0 2px 8px rgba(118, 148, 185, 0.15);
+}
+
+.form-group input::placeholder {
+  color: var(--text-muted);
+}
+
+.form-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 1rem;
+  margin-top: 2rem;
+}
+
+.btn {
+  padding: var(--spacing-md) var(--spacing-xl);
+  border: none;
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  font-size: 1rem;
+  font-weight: 500;
+  letter-spacing: 0.3px;
+  transition: all var(--transition-normal);
+  transition-timing-function: var(--transition-bounce);
+  box-shadow: 0 2px 6px var(--shadow-color);
+}
+
+.btn-primary {
+  background-color: var(--accent-color);
+  color: var(--white-color);
+}
+
+.btn-primary:hover {
+  background-color: var(--accent-hover);
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px rgba(118, 148, 185, 0.2);
+}
+
+.btn-secondary {
+  background-color: var(--secondary-bg);
+  color: var(--text-muted);
+}
+
+.btn-secondary:hover {
+  background-color: var(--secondary-bg);
+  color: var(--text-bright);
+  transform: translateY(-2px);
+  box-shadow: 0 4px 12px var(--shadow-color);
+}
diff --git a/assets/styles/_search.css b/assets/styles/_search.css
new file mode 100644
index 0000000000000000000000000000000000000000..2bc9adf7c593b3293ea05a082b71b74bd619ab6d
--- /dev/null
+++ b/assets/styles/_search.css
@@ -0,0 +1,306 @@
+/* ============================================
+   Search Box Component
+   ============================================ */
+
+/* 搜索框容器 - 固定在顶部 */
+.search-container {
+  width: 100%;
+  display: flex;
+  justify-content: center;
+  padding: 0 2rem;
+  margin-bottom: 1rem;
+  position: sticky;
+  top: 0;
+  /* 搜索框必须始终位于页面内容之上，避免搜索结果卡片滚动时遮挡 */
+  z-index: 200;
+}
+
+/* 分类切换按钮 */
+.category-toggle {
+  position: fixed;
+  bottom: 5rem;
+  right: var(--spacing-xl);
+  width: 2.5rem;
+  height: 2.5rem;
+  border-radius: var(--radius-lg);
+  background: rgba(var(--card-bg-rgb), 0.65);
+  border: 1px solid var(--border-color);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+  color: var(--text-color);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  transition: all var(--transition-normal);
+  transition-timing-function: var(--transition-bounce);
+  z-index: 100;
+  box-shadow: 0 4px 16px var(--shadow-color);
+}
+
+.category-toggle:hover {
+  transform: translateY(-2px);
+  background: rgba(var(--card-bg-rgb), 0.75);
+  box-shadow: 0 6px 20px var(--shadow-color);
+  color: var(--accent-color);
+}
+
+.category-toggle:active {
+  transform: translateY(0);
+  box-shadow: 0 2px 8px var(--shadow-color);
+}
+
+.category-toggle i {
+  font-size: 18px;
+}
+
+/* 搜索框 */
+.search-box {
+  position: relative;
+  width: 100%;
+  max-width: 600px;
+  display: flex;
+  align-items: stretch;
+  --search-status-right: 0.9rem;
+  --search-hint-right: 1.6rem;
+  background: rgba(var(--card-bg-rgb), 0.65);
+  border: 1px solid var(--border-color);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+  border-radius: var(--radius-lg);
+  box-shadow: 0 4px 16px var(--shadow-color);
+  transition:
+    background var(--transition-normal),
+    border-color var(--transition-normal),
+    box-shadow var(--transition-normal);
+}
+
+.search-box:focus-within {
+  border-color: rgba(var(--accent-rgb), 0.55);
+  box-shadow:
+    0 0 0 1px rgba(var(--accent-rgb), 0.28),
+    0 0 18px rgba(var(--accent-rgb), 0.18),
+    0 6px 24px var(--shadow-color);
+}
+
+.search-box::after {
+  content: '';
+  position: absolute;
+  right: var(--search-status-right);
+  top: 50%;
+  transform: translateY(-50%);
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  opacity: 0;
+  transition: all var(--transition-normal);
+  pointer-events: none;
+}
+
+.search-box.has-results::after {
+  background-color: var(--success-color);
+  opacity: 1;
+}
+
+.search-box.no-results::after {
+  background-color: var(--error-color);
+  opacity: 1;
+}
+
+.search-box input {
+  flex: 1;
+  min-width: 0;
+  width: 100%;
+  padding: var(--spacing-md) calc(var(--spacing-lg) + 4.8rem) var(--spacing-md) var(--spacing-md);
+  border: none;
+  border-radius: 0 var(--radius-lg) var(--radius-lg) 0;
+  background-color: transparent;
+  color: var(--text-color);
+  font-family: inherit;
+  font-weight: inherit;
+  font-size: 1rem;
+  transition:
+    background-color var(--transition-normal),
+    color var(--transition-normal);
+  box-shadow: none;
+}
+
+.search-box input:focus {
+  outline: none;
+  background-color: rgba(var(--card-bg-rgb), 0.25);
+  box-shadow: none;
+}
+
+.search-box input::placeholder {
+  color: var(--text-muted);
+  font-family: inherit;
+  font-weight: inherit;
+}
+
+.search-shortcut-hint {
+  position: absolute;
+  top: 50%;
+  right: var(--search-hint-right);
+  transform: translateY(-50%);
+  padding: 0.1rem 0.4rem;
+  border: 1px solid var(--border-color);
+  border-radius: var(--radius-md);
+  background: rgba(var(--card-bg-rgb), 0.25);
+  font-size: 0.78rem;
+  line-height: 1.2;
+  color: var(--text-muted);
+  opacity: 0.65;
+  pointer-events: none;
+  user-select: none;
+}
+
+.search-box:focus-within .search-shortcut-hint {
+  opacity: 0.85;
+}
+
+/* 搜索引擎前缀按钮（方案B：输入框前缀一体化） */
+.search-engine-button {
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0 0.75rem;
+  width: 120px;
+  flex: 0 0 120px;
+  border: none;
+  border-right: 1px solid var(--border-color);
+  border-radius: var(--radius-lg) 0 0 var(--radius-lg);
+  background: transparent;
+  color: var(--text-muted);
+  cursor: pointer;
+  font: inherit;
+  transition:
+    background var(--transition-normal),
+    color var(--transition-normal),
+    transform var(--transition-normal);
+}
+
+.search-engine-button:hover {
+  background: rgba(var(--card-bg-rgb), 0.25);
+}
+
+.search-engine-button:focus-visible {
+  outline: 2px solid var(--accent-color);
+  outline-offset: 2px;
+}
+
+.search-box:focus-within .search-engine-button {
+  color: var(--accent-color);
+}
+
+.search-engine-icon {
+  display: grid;
+  place-items: center;
+  height: 1.2em;
+  width: 1.2em;
+  min-width: 1.2em;
+  font-size: 1.25rem;
+  line-height: 1;
+  text-align: center;
+  flex: 0 0 1.2em;
+}
+
+.search-engine-icon.search-engine-icon-svg {
+  font-size: 1.25rem;
+}
+
+.search-engine-icon.search-engine-icon-svg svg {
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+
+.search-engine-label {
+  flex: 1;
+  min-width: 0;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  font-size: 0.95rem;
+}
+
+.search-box.dropdown-open .search-engine-button {
+  background: rgba(var(--card-bg-rgb), 0.25);
+}
+
+/* 搜索引擎下拉菜单 */
+.search-engine-dropdown {
+  position: absolute;
+  top: calc(100% + 6px);
+  left: 0;
+  background: rgba(var(--card-bg-rgb), 0.9);
+  backdrop-filter: blur(12px);
+  -webkit-backdrop-filter: blur(12px);
+  border-radius: var(--radius-md);
+  box-shadow: 0 4px 15px var(--shadow-color);
+  display: none;
+  z-index: 100;
+  padding: 0.35rem;
+  border: 1px solid var(--border-color);
+  min-width: 190px;
+  flex-direction: column;
+  gap: 0.25rem;
+}
+
+.search-engine-dropdown.active {
+  display: flex;
+  animation: fadeIn 0.2s ease-out forwards;
+}
+
+.search-engine-option {
+  display: flex;
+  align-items: center;
+  justify-content: flex-start;
+  gap: 0.6rem;
+  width: 100%;
+  height: 40px;
+  padding: 0 0.75rem;
+  border: none;
+  border-radius: var(--radius-md);
+  cursor: pointer;
+  transition: all 0.2s ease;
+  background: transparent;
+  color: var(--text-color);
+  font: inherit;
+}
+
+.search-engine-option:hover {
+  background: rgba(var(--card-bg-rgb), 0.22);
+}
+
+.search-engine-option:focus-visible {
+  outline: 2px solid var(--accent-color);
+  outline-offset: 2px;
+}
+
+.search-engine-option.active {
+  background-color: var(--secondary-bg);
+  color: var(--text-bright);
+}
+
+.search-engine-option i {
+  display: grid;
+  place-items: center;
+  position: static;
+  transform: none;
+  font-size: 1.25rem;
+  width: 1.35em;
+  height: 1.35em;
+  line-height: 1;
+  text-align: center;
+  flex: 0 0 1.35em;
+}
+
+.search-engine-option i.search-engine-option-svg svg {
+  width: 100%;
+  height: 100%;
+  display: block;
+}
+
+.search-engine-option-label {
+  font-size: 0.95rem;
+}
diff --git a/assets/styles/_sidebar.css b/assets/styles/_sidebar.css
new file mode 100644
index 0000000000000000000000000000000000000000..f3710de895fd245e236c3cb186040b902fcc6948
--- /dev/null
+++ b/assets/styles/_sidebar.css
@@ -0,0 +1,633 @@
+/* ============================================
+   Sidebar Component
+   ============================================ */
+
+/* 侧边栏样式 */
+.sidebar {
+  width: var(--sidebar-width);
+  background-color: var(--sidebar-bg);
+  position: fixed;
+  top: 0;
+  left: 0;
+  bottom: 0;
+  box-shadow: 2px 0 10px var(--shadow-color);
+  z-index: 100;
+  -webkit-backface-visibility: hidden;
+  backface-visibility: hidden;
+  transform: translateZ(0);
+  height: var(--app-height, 100vh);
+  display: grid;
+  grid-template-rows: auto 1fr auto auto;
+  grid-template-areas:
+    'header'
+    'content'
+    'social'
+    'footer';
+  scrollbar-width: thin;
+  scrollbar-color: var(--scrollbar-color) transparent;
+  overflow-y: hidden;
+  transition: background-color var(--transition-normal);
+}
+
+/* 侧边栏折叠状态 */
+.sidebar.collapsed {
+  width: var(--sidebar-collapsed-width);
+  overflow-x: hidden;
+}
+
+/* 优化侧边栏折叠时的Logo部分 */
+.sidebar.collapsed .logo {
+  padding: 1.2rem 0.5rem 0.6rem;
+  justify-content: center;
+  display: flex;
+  align-items: center;
+  height: 3.75rem;
+  /* 确保与展开状态高度一致 */
+  margin-bottom: 0.8rem;
+  /* 收起态同样拉开与按钮的间距 */
+}
+
+/* 调整折叠侧边栏的部分元素间距 */
+.sidebar.collapsed .nav-section {
+  gap: 2px;
+}
+
+/* 折叠状态下隐藏底部版权区域（不占位） */
+.sidebar.collapsed .sidebar-footer {
+  padding: 0;
+  height: 0;
+  min-height: 0;
+  margin: 0;
+  overflow: hidden;
+  border: none;
+}
+
+/* 侧边栏头部区域 */
+.sidebar .logo {
+  grid-area: header;
+  padding: 1.2rem 1.2rem 0.6rem;
+  /* 调整上下padding更紧凑 */
+  display: flex;
+  align-items: center;
+  overflow: hidden;
+  /* 防止内容溢出 */
+  position: relative;
+  /* 添加相对定位，作为按钮的参考 */
+  height: 3.75rem;
+  /* 固定高度 60px */
+  margin-bottom: 0.8rem;
+  /* 与下方按钮区域拉开间距 */
+  transition: padding 0.3s ease;
+  /* 添加padding过渡，避免突变 */
+}
+
+.logo-brand {
+  display: flex;
+  align-items: center;
+  gap: 0.6rem;
+  min-width: 0;
+  flex: 1;
+  padding-right: 2.2rem;
+  /* 预留右侧折叠按钮空间 */
+}
+
+.logo-brand h1 {
+  padding-left: 0;
+}
+
+.logo-image {
+  width: 26px;
+  height: 26px;
+  flex-shrink: 0;
+}
+
+.sidebar.collapsed .logo-image {
+  display: none;
+}
+
+.logo h1 {
+  font-size: 1.4rem;
+  color: var(--text-bright);
+  margin-bottom: 0;
+  padding-left: 0.5rem;
+  letter-spacing: 0.5px;
+  transition:
+    opacity 0.3s ease,
+    transform 0.3s ease;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  flex: 1;
+}
+
+/* 侧边栏折叠按钮 */
+.sidebar-toggle {
+  background: transparent;
+  border: none;
+  color: var(--accent-color);
+  height: 28px;
+  width: 28px;
+  border-radius: 50%;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  transition: background 0.3s ease;
+  /* 只过渡背景色，移除all避免位置过渡 */
+  padding: 0;
+  flex-shrink: 0;
+  /* 防止按钮被压缩 */
+  position: absolute;
+  /* 在两种状态下都使用绝对定位 */
+  right: 1.2rem;
+  /* 展开状态下固定在右侧 */
+  top: 60%;
+  transform: translateY(-50%);
+  /* 垂直居中 */
+}
+
+.sidebar-toggle .toggle-icon {
+  font-size: 0.9rem;
+  transition: transform 0.3s ease;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+}
+
+.sidebar-toggle:hover {
+  background: var(--secondary-bg);
+}
+
+.sidebar-toggle:active {
+  background: var(--secondary-bg);
+}
+
+/* 收起状态下按钮居中 */
+.sidebar.collapsed .sidebar-toggle {
+  left: 50%;
+  /* 水平居中 */
+  right: auto;
+  /* 移除右侧定位 */
+  transform: translate(-50%, -50%);
+  /* 同时水平和垂直居中 */
+}
+
+.sidebar.collapsed .sidebar-toggle:hover {
+  background: var(--secondary-bg);
+}
+
+.sidebar.collapsed .sidebar-toggle:active {
+  background: var(--secondary-bg);
+}
+
+/* 侧边栏折叠状态下的按钮图标旋转180度 */
+.sidebar.collapsed .toggle-icon {
+  transform: rotate(180deg);
+}
+
+/* 侧边栏内容区域：导航项常驻显示，分类列表在独立面板内滚动 */
+.sidebar-content {
+  grid-area: content;
+  min-height: 0;
+  /* 允许在 CSS Grid 内正确收缩与滚动，避免把 footer 挤出可视区域 */
+  overflow: hidden;
+  /* 导航项常驻显示，分类列表在独立面板内滚动 */
+  padding: 0 1.2rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.6rem;
+  /* 从1rem减小到0.6rem */
+}
+
+.sidebar-content::-webkit-scrollbar {
+  display: none;
+  /* Webkit browsers（默认不滚动，保留兼容） */
+}
+
+/* 展开态：子菜单不在导航项内部展开，改在独立面板展示（避免把"页面列表"挤出首屏） */
+.sidebar:not(.collapsed) .nav-item-wrapper > .submenu {
+  display: none;
+}
+
+/* 侧边栏：页面分类面板（容器本身可滚动，隐藏滚动条） */
+.sidebar-submenu-panel {
+  flex: 1 1 auto;
+  min-height: 0;
+  overflow-y: auto;
+  padding: 0 0 0.6rem;
+  /* 移除顶部 padding，避免标题上方出现缝隙 */
+  scrollbar-width: none;
+  /* Firefox 隐藏滚动条 */
+  opacity: 0;
+  visibility: hidden;
+  pointer-events: none;
+  transition:
+    opacity 0.18s ease,
+    visibility 0s linear 0.18s;
+}
+
+.sidebar-submenu-panel:empty {
+  display: none;
+}
+
+.sidebar.submenu-panel-visible .sidebar-submenu-panel:not(:empty) {
+  opacity: 1;
+  visibility: visible;
+  pointer-events: auto;
+  transition:
+    opacity 0.18s ease,
+    visibility 0s linear 0s;
+}
+
+.sidebar-submenu-panel::-webkit-scrollbar {
+  display: none;
+  /* Webkit 浏览器隐藏滚动条 */
+}
+
+/* 面板内的 submenu 始终可见（不依赖 wrapper.expanded） */
+.sidebar-submenu-panel .submenu {
+  max-height: none;
+  overflow: visible;
+  opacity: 1;
+  visibility: visible;
+  margin-left: 0;
+  transition: none;
+}
+
+/* 折叠状态下的内容区域调整 */
+.sidebar.collapsed .sidebar-content {
+  padding: 0 0.5rem;
+  overflow-y: auto;
+  overflow-x: hidden;
+  scrollbar-width: none;
+  /* 隐藏滚动条 */
+}
+
+.sidebar.collapsed .sidebar-content::-webkit-scrollbar {
+  display: none;
+  /* 隐藏WebKit浏览器的滚动条 */
+}
+
+.sidebar.collapsed .sidebar-submenu-panel {
+  display: none;
+}
+
+/* 收起侧边栏时，禁止当前激活页面的目录直接显示在按钮下方 */
+.sidebar.collapsed .nav-item-wrapper > .submenu {
+  display: none;
+}
+
+/* 子菜单标题：默认隐藏（在导航栏内折叠时） */
+.submenu-header {
+  display: none;
+  font-size: 0.85rem;
+  font-weight: 500;
+  text-transform: uppercase;
+  color: var(--text-muted);
+  letter-spacing: 0.5px;
+  padding: 0.8rem 1rem 0.6rem;
+  margin-bottom: 0.2rem;
+  border-bottom: 1px solid var(--border-color);
+  transition:
+    color var(--transition-normal),
+    background-color var(--transition-normal),
+    border-bottom-color var(--transition-normal);
+  opacity: 0.8;
+}
+
+/* 当子菜单在面板中显示时：显示标题并固定在顶部 */
+.sidebar-submenu-panel .submenu-header {
+  display: block;
+  position: sticky;
+  top: 0;
+  margin-top: 0;
+  margin-bottom: 0.2rem;
+  /* 覆盖基础样式的 margin-bottom */
+  background-color: var(--sidebar-bg);
+  opacity: 1;
+  /* 覆盖基础样式的半透明，确保背景完全不透明 */
+  z-index: 1;
+  /* 确保标题在滚动时覆盖下方内容 */
+}
+
+/* 子菜单项样式优化 */
+.submenu-item {
+  display: flex;
+  align-items: center;
+  gap: 0.8rem;
+  padding: 0.6rem 1rem;
+  color: var(--nav-item-color);
+  text-decoration: none;
+  border-radius: var(--radius-md);
+  transition: all var(--transition-normal);
+  margin-bottom: 2px;
+  font-size: 0.95rem;
+  position: relative;
+  overflow: hidden;
+}
+
+.submenu-item i {
+  width: 1.4rem;
+  text-align: center;
+  font-size: 1rem;
+  opacity: 0.8;
+  transition: transform var(--transition-normal);
+}
+
+.submenu-item span {
+  flex: 1;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+}
+
+/* 悬浮状态 */
+.submenu-item:hover {
+  background-color: var(--secondary-bg);
+  color: var(--text-bright);
+  padding-left: 1.2rem;
+  /* 悬浮时轻微右移增加动感 */
+}
+
+.submenu-item:hover i {
+  transform: scale(1.1);
+  color: var(--accent-color);
+  opacity: 1;
+}
+
+/* 激活状态 */
+.submenu-item.active {
+  background-color: rgba(var(--accent-rgb), 0.15);
+  color: var(--accent-color);
+  font-weight: 500;
+}
+
+.submenu-item.active i {
+  color: var(--accent-color);
+  opacity: 1;
+}
+
+/* 在激活状态左侧添加指示条 */
+.submenu-item.active::before {
+  content: '';
+  position: absolute;
+  left: 0;
+  top: 50%;
+  transform: translateY(-50%);
+  height: 60%;
+  width: 3px;
+  background-color: var(--accent-color);
+  border-radius: 0 2px 2px 0;
+}
+
+/* 折叠状态下的Logo文本 */
+.sidebar.collapsed .logo h1 {
+  opacity: 0;
+  transform: translateX(-20px);
+  width: 0;
+  visibility: hidden;
+  /* 确保完全隐藏，防止干扰布局 */
+  pointer-events: none;
+  /* 禁用交互，避免影响布局 */
+}
+
+/* 导航区域样式 */
+.nav-section {
+  display: flex;
+  flex-direction: column;
+  gap: 0;
+  /* wrapper 之间不需要 gap，由 nav-item 的 margin 控制 */
+  flex: 0 0 auto;
+  /* 不伸缩，根据内容大小 */
+  overflow: visible;
+  /* 导航项不滚动，保持常驻显示 */
+}
+
+.section-title {
+  font-size: 1rem;
+  color: var(--accent-color);
+  padding: 0.4rem 0.5rem;
+  /* 减小上下padding */
+  margin-bottom: 0.2rem;
+  /* 增大与下方按钮组的间距 */
+  display: flex;
+  align-items: center;
+  gap: 0.5rem;
+  transition: color 0.3s ease;
+}
+
+.section-title i {
+  font-size: 1.2rem;
+}
+
+/* 调整侧边栏折叠状态下的章节标题 */
+.sidebar.collapsed .section-title {
+  justify-content: center;
+  /* 统一与展开态的垂直间距 */
+  padding: 0.4rem 0;
+  text-align: center;
+  margin-bottom: 0.2rem;
+  /* 与展开态保持一致且更大 */
+}
+
+.sidebar.collapsed .section-title i {
+  margin: 0 auto;
+  font-size: 1.2rem;
+}
+
+/* 折叠状态下的导航项布局优化 */
+.sidebar.collapsed .nav-section {
+  gap: 0.4rem;
+  align-items: center;
+}
+
+.sidebar.collapsed .nav-item {
+  padding: 0;
+  justify-content: center;
+  width: 2.75rem;
+  /* 增大按钮方块尺寸 44px */
+  height: 2.75rem;
+  /* 增大按钮方块尺寸 44px */
+  text-align: center;
+  margin-left: auto;
+  margin-right: auto;
+  border-radius: var(--radius-md);
+  /* 略增圆角 */
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+}
+
+.sidebar.collapsed .nav-item i {
+  font-size: 1.25rem;
+  width: auto;
+  margin: 0;
+  padding: 0;
+}
+
+.sidebar.collapsed .nav-item .icon-container {
+  margin: 0;
+  width: 100%;
+  height: 100%;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+}
+
+/* 折叠状态下的导航项文本 */
+.sidebar.collapsed .nav-item .nav-text,
+.sidebar.collapsed .nav-item .external-icon {
+  opacity: 0;
+  transform: translateX(-10px);
+  width: 0;
+  display: none;
+  /* 完全移除，防止干扰布局 */
+  visibility: hidden;
+}
+
+.nav-item {
+  display: flex;
+  align-items: center;
+  height: 44px;
+  padding: 0 0.9rem;
+  margin-bottom: 0.4rem;
+  /* 导航按钮之间的间距 */
+  color: var(--nav-item-color);
+  text-decoration: none;
+  border-radius: var(--radius-md);
+  transition:
+    background-color var(--transition-normal),
+    color var(--transition-normal),
+    box-shadow var(--transition-normal);
+  position: relative;
+}
+
+.nav-item-wrapper:last-child .nav-item {
+  margin-bottom: 0;
+  /* 最后一个导航按钮不需要底部间距 */
+}
+
+.nav-item .icon-container {
+  width: 24px;
+  height: 100%;
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  margin-right: var(--spacing-md);
+  transition: margin var(--transition-normal);
+}
+
+.nav-item .nav-text {
+  flex: 1;
+  transition:
+    opacity var(--transition-normal),
+    transform var(--transition-normal);
+  white-space: nowrap;
+  overflow: hidden;
+}
+
+.nav-item .external-icon {
+  font-size: 0.9rem;
+  opacity: 0.6;
+  margin-left: 0.5rem;
+  transition: all var(--transition-normal);
+}
+
+.nav-item:hover {
+  background-color: var(--secondary-bg);
+  color: var(--text-bright);
+}
+
+.nav-item:hover .external-icon {
+  opacity: 1;
+  transform: translateX(2px);
+}
+
+.nav-item.active {
+  background-color: var(--secondary-bg);
+  color: var(--text-bright);
+}
+
+.nav-item i {
+  width: 20px;
+  text-align: center;
+}
+
+/* 折叠状态下：底部区域不可见且不可交互 */
+.sidebar.collapsed .sidebar-footer {
+  visibility: hidden;
+  pointer-events: none;
+}
+
+/* 主内容区域 - 修复滚动条问题 */
+main.content {
+  flex: 1;
+  margin-left: var(--sidebar-width);
+  padding: 1.5rem 1rem;
+  background-color: var(--bg-color);
+  position: relative;
+  height: var(--app-height, 100vh);
+  /* 固定高度（移动端避免 100vh 问题） */
+  overflow-y: auto;
+  /* 使用auto替代scroll，只在需要时显示滚动条 */
+  overflow-x: hidden;
+  width: calc(100vw - var(--sidebar-width));
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  /* 防止"有无滚动条"导致内容横向平移（支持的浏览器会稳定预留滚动条槽位） */
+  scrollbar-gutter: stable;
+  /* 自定义滚动条颜色（Firefox） */
+  scrollbar-width: thin;
+  scrollbar-color: var(--scrollbar-color) transparent;
+}
+
+/* 自定义滚动条（Chromium / Safari） */
+main.content::-webkit-scrollbar {
+  width: 8px;
+}
+
+main.content::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+main.content::-webkit-scrollbar-thumb {
+  background-color: var(--scrollbar-color);
+  border-radius: var(--radius-full);
+  /* 用透明边框制造"内边距"，更贴合卡片阴影风格 */
+  border: 2px solid transparent;
+  background-clip: content-box;
+}
+
+main.content::-webkit-scrollbar-thumb:hover {
+  background-color: var(--scrollbar-hover-color);
+}
+
+/* 回退：不支持 scrollbar-gutter 的浏览器，强制始终显示滚动条以避免横向抖动 */
+@supports not (scrollbar-gutter: stable) {
+  main.content {
+    overflow-y: scroll;
+  }
+}
+
+/* 优化内容区域在侧边栏折叠状态下的边距 */
+body main.content.expanded {
+  margin-left: var(--sidebar-collapsed-width);
+  width: calc(100vw - var(--sidebar-collapsed-width));
+}
+
+/* 仅在交互时启用布局相关过渡，避免首帧闪烁 */
+.with-anim .sidebar {
+  transition:
+    width 0.3s ease,
+    background-color 0.3s ease;
+}
+
+.with-anim main.content {
+  transition:
+    background-color 0.3s ease,
+    margin-left 0.3s ease,
+    width 0.3s ease;
+}
diff --git a/assets/styles/_variables.css b/assets/styles/_variables.css
new file mode 100644
index 0000000000000000000000000000000000000000..7d6b6c2a6a07b0f4b388eb8e2dab059c309f1a8d
--- /dev/null
+++ b/assets/styles/_variables.css
@@ -0,0 +1,147 @@
+/* ============================================
+   CSS Variables & Theme System
+   ============================================ */
+
+/* 主题颜色变量 - Apple Design System */
+:root {
+  /* 深色主题 (iOS Dark Mode Inspired) */
+  --bg-color: #000000;
+  /* Pure Black background */
+  --sidebar-bg: #1c1c1e;
+  /* System Gray 6 */
+  --secondary-bg: #2c2c2e;
+  /* System Gray 5 */
+
+  /* 卡片背景 - 仪表盘卡片 */
+  --card-bg-gradient-1: #1c1c1e;
+  --card-bg-gradient-2: #1c1c1e;
+
+  /* 站点卡片 - 提升亮度以区分层级 (Optimize: Use System Gray 5 for cards on black bg) */
+  --site-card-bg-gradient-1: #2c2c2e;
+  --site-card-bg-gradient-2: #2c2c2e;
+  --site-card-hover-bg: #3a3a3c;
+  /* System Gray 4 for hover */
+
+  /* 文字颜色 */
+  --text-color: #ffffff;
+  --text-muted: #8e8e93;
+  /* System Gray */
+  --text-bright: #ffffff;
+
+  /* 边框与阴影 */
+  --border-color: rgba(255, 255, 255, 0.12);
+  --shadow-color: rgba(0, 0, 0, 0.3);
+
+  /* 功能色 */
+  --highlight-bg: rgba(118, 148, 185, 0.3);
+  /* Restore original Highlight */
+  --scrollbar-color: rgba(255, 255, 255, 0.2);
+  --scrollbar-hover-color: rgba(255, 255, 255, 0.3);
+
+  /* 恢复原有强调色 (Restore Original Accent) */
+  --accent-color: #7694b9;
+  --accent-hover: #6684a9;
+  --accent-rgb: 118, 148, 185;
+
+  --nav-item-color: #98989d;
+  --success-color: #30d158;
+  --error-color: #ff453a;
+  --white-color: #ffffff;
+
+  /* 恢复原有渐变 (Restore Original Gradient) */
+  --gradient-color: linear-gradient(135deg, #7694b9 0%, #a855f7 50%, #ff6b6b 100%);
+  --gradient-color-simple: linear-gradient(135deg, #7694b9 0%, #a855f7 100%);
+
+  --sidebar-width: 240px;
+  --sidebar-collapsed-width: 60px;
+  --app-height: 100vh;
+
+  /* Spacing System */
+  --spacing-xs: 0.25rem;
+  --spacing-sm: 0.5rem;
+  --spacing-md: 1rem;
+  --spacing-lg: 1.5rem;
+  --spacing-xl: 2rem;
+  --spacing-2xl: 3rem;
+
+  --page-max-width: 1300px;
+
+  /* UI Tuning - Apple Style (Kept) */
+  --radius-sm: 6px;
+  --radius-md: 10px;
+  --radius-lg: 14px;
+  --radius-xl: 20px;
+  --radius-full: 9999px;
+
+  /* Transitions - Kept iOS Spring */
+  --transition-fast: 0.2s ease;
+  --transition-normal: 0.35s cubic-bezier(0.25, 1, 0.5, 1);
+  --transition-slow: 0.5s cubic-bezier(0.25, 1, 0.5, 1);
+  --transition-bounce: cubic-bezier(0.175, 0.885, 0.32, 1.275);
+
+  --card-bg-rgb: 28, 28, 30;
+}
+
+/* 浅色主题 - 恢复原有配色 (Restored Morandi/Warm) */
+html.theme-preload,
+body.light-theme {
+  --bg-color: #e0e0d8;
+  --sidebar-bg: #f0f0eb;
+  --secondary-bg: #e6e6e1;
+  /* Slightly darker than sidebar for hover state */
+  --card-bg-gradient-1: #f0f0eb;
+  --card-bg-gradient-2: #e9e9e4;
+  --site-card-bg-gradient-1: #ffffff;
+  --site-card-bg-gradient-2: #f4f5f0;
+  --site-card-hover-bg: linear-gradient(145deg, #fafaf8, #eef0eb);
+
+  --text-color: #333333;
+  --text-muted: #666666;
+  --text-bright: #000000;
+
+  --border-color: rgba(0, 0, 0, 0.08);
+  --shadow-color: rgba(0, 0, 0, 0.1);
+
+  --highlight-bg: rgba(118, 148, 185, 0.15);
+  --scrollbar-color: rgba(0, 0, 0, 0.1);
+  --scrollbar-hover-color: rgba(0, 0, 0, 0.2);
+
+  --accent-color: #7694b9;
+  --accent-hover: #6684a9;
+  --accent-rgb: 118, 148, 185;
+
+  --nav-item-color: #666666;
+  --success-color: #4caf50;
+  --error-color: #f44336;
+  --white-color: #ffffff;
+
+  /* Restore original gradients */
+  --gradient-color: linear-gradient(135deg, #7694b9 0%, #a855f7 50%, #ff6b6b 100%);
+  --gradient-color-simple: linear-gradient(135deg, #7694b9 0%, #a855f7 100%);
+
+  --card-bg-rgb: 240, 240, 235;
+}
+
+/* 预加载主题 - 在JS完全加载前显示正确的主题 */
+html.theme-preload body {
+  background-color: #e0e0d8;
+  color: #333333;
+}
+
+/* 预加载侧边栏状态 - 在JS完全加载前显示正确的侧边栏宽度 */
+html.sidebar-collapsed-preload .sidebar {
+  width: var(--sidebar-collapsed-width);
+}
+
+html.sidebar-collapsed-preload main.content {
+  margin-left: var(--sidebar-collapsed-width);
+}
+
+/* 控制页面预加载状态 */
+html.preload .layout {
+  opacity: 0;
+}
+
+html.preload * {
+  transition: none !important;
+}
diff --git a/bookmarks/.gitkeep b/bookmarks/.gitkeep
new file mode 100644
index 0000000000000000000000000000000000000000..b71b9135293ba2aa67e8c32215289826773b8415
--- /dev/null
+++ b/bookmarks/.gitkeep
@@ -0,0 +1,2 @@
+# 此文件用于保持bookmarks目录在Git仓库中存在
+# 即使目录为空，也不会被删除 
\ No newline at end of file
diff --git a/bookmarks/README.md b/bookmarks/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..969d8403d2d0247e49bb4cd469c9228416764672
--- /dev/null
+++ b/bookmarks/README.md
@@ -0,0 +1,134 @@
+# MeNav 书签目录
+
+## 目录
+
+- [目录概述](#目录概述)
+- [书签导入功能](#书签导入功能)
+- [配置加载优先级（完全替换）](#配置加载优先级完全替换)
+- [MarksVault 扩展集成](#marksvault-扩展集成)
+- [书签导入流程](#书签导入流程)
+- [确定性输出](#确定性输出)
+- [支持的浏览器](#支持的浏览器)
+- [书签格式要求](#书签格式要求)
+- [文件处理机制](#文件处理机制)
+
+## 目录概述
+
+`bookmarks` 目录是 MeNav 项目中用于存放浏览器导出的书签文件的专用目录。该目录与书签导入功能直接关联，用于自动将浏览器书签转换为 MeNav 配置文件，从而快速生成个人导航站点。
+
+## 书签导入功能
+
+书签导入功能允许用户：
+
+- 从浏览器导出书签为 HTML 文件
+- 将书签文件放入此目录
+- 通过自动处理将书签转换为网站配置
+- 无需手动编辑即可批量导入网站链接
+
+这一功能极大简化了网站内容的初始设置过程，特别适合需要迁移大量书签的用户。
+
+## 配置加载优先级（完全替换）
+
+书签页配置同样遵循项目的“完全替换”策略：系统只会选择一套配置目录加载，不会把 `user` 与 `_default` 混合合并。
+
+- 若存在 `config/user/`：书签页配置应位于 `config/user/pages/bookmarks.yml`（通常由导入脚本生成）
+- 否则：使用 `config/_default/pages/bookmarks.yml`（默认示例）
+
+> 提示：一旦创建 `config/user/`，`config/_default/` 会被完全忽略，因此不要指望从默认配置“兜底补齐缺失项”。
+
+## MarksVault 扩展集成
+
+[MarksVault](https://github.com/rbetree/MarksVault) 浏览器扩展可与 MeNav 集成，实现书签自动同步：
+
+- **一键推送书签**：扩展将书签 HTML 文件推送到仓库的 `bookmarks/` 目录
+- **自动化处理**：GitHub Actions 检测到书签文件后自动运行导入脚本生成配置
+- **自动清理**：处理完成后会删除已导入的 HTML 文件，避免重复处理
+
+## 书签导入流程
+
+完整的书签导入流程如下：
+
+1. 在浏览器中导出书签为 HTML 文件
+2. 将导出的书签文件放入 `bookmarks` 目录
+3. 运行书签处理工具：
+   ```bash
+   npm run import-bookmarks
+   ```
+   - 若 `config/user/` 不存在，导入脚本会先从 `config/_default/` 初始化一份用户配置（因为配置采用“完全替换”策略，需要完整配置才能正常生成站点）。
+   （可选）若希望生成结果保持确定性（便于版本管理，减少时间戳导致的无意义 diff）：
+   ```bash
+   MENAV_BOOKMARKS_DETERMINISTIC=1 npm run import-bookmarks
+   ```
+4. 系统自动解析书签文件内容
+5. 根据书签文件夹结构生成分类
+6. 生成配置文件保存到 `config/user/pages/bookmarks.yml`
+7. 构建网站应用新配置：
+   ```bash
+   npm run build
+   ```
+
+> **重要说明**：在本地开发中，`npm run dev` 命令**不会**自动处理书签文件。您必须先手动运行 `npm run import-bookmarks` 命令处理书签，然后再运行 `npm run dev` 查看效果。这与 GitHub Actions 中的自动处理流程不同，请务必注意。
+
+## 确定性输出
+
+默认情况下，导入脚本会在生成的 `bookmarks.yml` 顶部写入时间戳注释，导致每次导入都会产生 diff。
+
+若你希望生成结果尽量稳定（只有书签内容变化才产生 diff），可使用环境变量开启确定性输出：
+
+```bash
+MENAV_BOOKMARKS_DETERMINISTIC=1 npm run import-bookmarks
+```
+
+## 支持的浏览器
+
+MeNav 书签导入功能支持从以下浏览器导出的书签文件：
+
+- **Chrome** - 通过书签管理器导出
+- **Firefox** - 通过书签库导出
+- **Edge** - 通过收藏夹导出
+- **Safari** - 通过书签菜单导出
+- 其他支持标准 HTML 书签格式的浏览器
+
+## 书签格式要求
+
+导入的书签文件需满足以下要求：
+
+- 文件格式：HTML（标准网络书签格式）
+- 文件编码：UTF-8
+- 文件结构：包含 `<DL>`、`<DT>` 和 `<A>` 标签的标准书签结构
+- 文件大小：建议不超过 5MB（约数千个书签）
+- 支持处理位于文件夹内的书签
+- 支持处理不在任何文件夹内的根路径书签（自动归入"根目录书签"分类）
+- 空文件夹会被忽略
+
+## 文件处理机制
+
+书签处理器 (`src/bookmark-processor.js`) 对书签文件进行以下处理：
+
+1. **解析文件结构**：
+   - 读取书签 HTML 文件
+   - 解析 DOM 结构获取书签层次
+   - 提取文件夹和链接信息
+
+2. **分类提取**：
+   - 将书签文件夹转换为网站分类
+   - 提取链接URL、标题和添加日期
+
+3. **根路径书签处理**：
+   - **自动分类**：根路径书签会被自动归入名为"根目录书签"的特殊分类
+   - **显示位置**：该分类始终位于所有其他分类之前（第一位）
+   - **图标标识**：使用星标图标（fas fa-star）
+   - **条件生成**：只有存在根路径书签时才会创建该分类
+   - **自动映射**：根路径书签同样支持基于URL的自动图标映射功能
+
+4. **图标分配**：
+   - 根据URL自动匹配合适的 Font Awesome 图标
+   - 为每个链接和分类分配图标
+   - 当 `icons.mode: favicon` 时，页面通常会优先显示站点 favicon；配置里的 `icon` 主要用于回退显示或在 `icons.mode: manual` 时使用（详见 `config/README.md`）
+
+5. **配置生成**：
+   - 创建符合 MeNav 配置格式的 YAML 文件
+   - 按层级组织分类和链接
+   - 应用自动生成的元数据
+
+将书签放入此目录后，您可以立即利用 MeNav 的书签处理功能，快速将书签转化为个性化导航站点。 
diff --git a/config/README.md b/config/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..0c1c106be4a9365264808e55131633c9b9d830e5
--- /dev/null
+++ b/config/README.md
@@ -0,0 +1,382 @@
+# MeNav 配置目录
+
+## 目录
+
+- [目录概述](#目录概述)
+- [配置目录结构](#配置目录结构)
+- [配置加载机制](#配置加载机制)
+- [推荐用法](#推荐用法)
+- [模块化配置文件](#模块化配置文件)
+  - [网站基础配置](#网站基础配置)
+  - [页面配置](#页面配置)
+- [配置详解](#配置详解)
+  - [site.yml 常用字段](#siteyml-常用字段)
+  - [pages/ 页面配置](#pages-页面配置)
+  - [多层级嵌套配置（2-4层）](#多层级嵌套配置2-4层)
+- [配置优先级](#配置优先级)
+- [配置示例](#配置示例)
+- [最佳实践](#最佳实践)
+
+## 目录概述
+
+`config` 目录包含 MeNav 项目的所有配置文件，采用模块化的 YAML 格式组织。这些配置文件定义了网站的内容、结构、布局和功能，是定制个人导航站的核心。
+
+## 配置目录结构
+
+配置系统采用分层结构，清晰分离默认配置和用户配置：
+
+```
+config/
+├── _default/           # 默认配置目录
+│   ├── site.yml        # 默认网站基础配置（含导航配置）
+│   └── pages/          # 默认页面配置
+│       ├── common.yml   # 示例：默认首页（navigation 第一项）
+│       ├── projects.yml # 项目页
+│       ├── articles.yml # 文章页
+│       └── bookmarks.yml # 书签页
+└── user/               # 用户配置目录（覆盖默认配置）
+    ├── site.yml        # 用户自定义网站配置（含导航配置）
+    └── pages/          # 用户自定义页面配置
+        ├── common.yml  # 示例：与 navigation 第一项对应
+        └── ...
+```
+
+## 配置加载机制
+
+MeNav 配置系统采用“完全替换”策略（不合并），按以下优先级选择**唯一**的一套配置目录：
+
+1. 若存在 `config/user/`，则只加载该目录下的配置，并**完全忽略** `config/_default/`
+2. 否则加载 `config/_default/` 作为默认配置
+
+也就是说：`config/user/` 一旦存在，就需要包含一套完整的配置（例如 `site.yml` 与必要的 `pages/*.yml`），系统不会把缺失部分从默认配置补齐。
+
+## 推荐用法
+
+为避免文档与配置字段长期不同步，建议按以下方式使用与维护：
+
+1. **首次使用**：完整复制 `config/_default/` 到 `config/user/`，再按需修改。
+2. **字段与结构的权威参考**：
+   - 全局配置：[`_default/site.yml`](_default/site.yml)
+   - 页面配置：[`_default/pages/`](_default/pages/)
+3. **多层级嵌套书签示例**：[`_default/pages/bookmarks.yml`](_default/pages/bookmarks.yml)（包含2层、3层、4层结构示例；`subgroups` 可参考下方说明或由导入脚本生成）
+
+## 模块化配置文件
+
+### 网站基础配置
+
+`site.yml` 定义网站的基本信息和全局设置：
+
+- 网站标题、描述和关键词
+- 作者信息和版权声明
+- 字体配置、图标模式等全局设置
+- 全局元数据和站点参数
+- 个人资料和社交媒体链接
+- 导航菜单配置（侧边栏导航项、页面标题和图标、页面顺序和可见性）
+
+> **注意**：导航配置仅支持写在 `site.yml` 的 `navigation` 字段中。
+
+### 页面配置
+
+`pages/` 目录下的配置文件定义各个页面的内容：
+
+- `common.yml`: 示例首页（本质上是普通页面；首页由 navigation 第一项决定，不要求必须叫 home）
+- `projects.yml`: 项目展示配置
+- `articles.yml`: 文章列表配置
+- `bookmarks.yml`: 书签页面配置
+- 其他自定义页面配置（可按需新增/删除；与 `site.yml -> navigation[].id` 对应）
+
+## 配置详解
+
+本章节用于补齐“怎么配才是对的”这类细节说明。为了避免示例长期过时，字段与结构的权威参考始终以默认配置为准：
+
+- 全局配置：[`_default/site.yml`](_default/site.yml)
+- 页面配置：[`_default/pages/`](_default/pages/)
+
+### site.yml 常用字段
+
+`site.yml` 中字段较多，以下是常用项的解释与注意点（完整字段请以默认配置为准）：
+
+1. **基础信息**
+   - `title`：站点标题
+   - `description`：站点描述（SEO/分享）
+   - `author`：作者/署名
+   - `favicon`、`logo_text`：站点图标与左上角 Logo 文本
+
+2. **图标模式（隐私相关）**
+   - `icons.mode: favicon | manual`
+   - `favicon`：会请求第三方服务（Google）获取站点 favicon，失败自动回退到 Font Awesome 图标
+   - `manual`：完全使用手动 Font Awesome 图标，不发起外部请求（适合内网/离线/隐私敏感场景）
+   - `icons.region: com | cn`（默认 `com`）
+     - `com`：优先使用 `gstatic.com`（国际版），失败后回退到 `gstatic.cn`（中国版）
+     - `cn`：优先使用 `gstatic.cn`（中国版），失败后回退到 `gstatic.com`（国际版）
+     - 说明：如果你在中国大陆且访问 gstatic.com 较慢，建议设置为 `cn` 以提升图标加载速度
+   - 站点级覆盖（可选，写在 `pages/*.yml` 的每个 `sites[]` 节点上）：
+     - `faviconUrl`：为单个站点指定图标链接（可远程或本地相对路径；本地建议以 `assets/` 开头，构建会复制到 `dist/` 同路径），优先级最高
+     - `forceIconMode: favicon | manual`：强制该站点使用指定模式（不设置则跟随全局 `icons.mode`）
+     - 优先级：`faviconUrl` > `forceIconMode` > 全局 `icons.mode`
+     - 示例：
+       ```yml
+       sites:
+         - name: 'Ant Design'
+           url: 'https://ant.design/'
+           icon: 'fas fa-th'
+           forceIconMode: manual # 强制使用手动图标，绕过 favicon 默认"地球"图标
+         - name: 'Example'
+           url: 'https://example.com/'
+           faviconUrl: 'https://example.com/favicon.png' # 单站点自定义 favicon
+       ```
+
+3. **安全策略（链接白名单）**
+   - `security.allowedSchemes`：允许在页面中渲染为可点击链接的 URL scheme 白名单
+   - 默认仅允许：`http/https/mailto/tel` + 所有相对链接（`#`、`/`、`./`、`../`、`?` 开头）
+   - 其他 scheme 会被安全降级为 `#` 并输出告警；如需支持 `obsidian://`、`vscode://` 等协议，可在此显式放行
+
+4. **字体**
+   - `fonts`：单一字体配置项，用于设置全站基础字体（`body` 等）
+   - 支持 `source: css | google | system`（分别表示第三方 CSS、Google Fonts、系统字体）
+   - 可选 `fonts.preload: true`：用 `preload + onload` 的方式非阻塞加载外链字体 CSS（更利于首屏性能）
+   - 首页副标题（渐变发光样式）使用全站基础字体（跟随 `fonts` 配置）
+
+5. **主题（默认明暗模式）**
+   - `theme.mode: dark | light | system`
+   - `dark/light`：首屏默认主题；用户点击按钮切换后会写入 localStorage 并覆盖该默认值
+   - `system`：跟随系统 `prefers-color-scheme`；用户手动切换后同样会写入 localStorage 并停止跟随
+
+6. **顶部欢迎信息与社交链接**
+   - `profile`：首页顶部欢迎信息
+   - `social`：侧边栏底部社交链接
+   - `profile.title` / `profile.subtitle`：分别对应首页顶部主标题与副标题
+
+7. **导航**
+   - `navigation[]`：页面入口列表，`id` 需唯一，并与 `pages/<id>.yml` 对应（例如 `id: common` 对应 `pages/common.yml`）
+   - 默认首页由 `navigation` 数组顺序决定：**第一项即为首页（默认打开页）**，不再使用 `active` 字段
+   - 图标使用 Font Awesome 类名字符串（例如 `fas fa-home`、`fab fa-github`）
+   - 导航显示顺序与数组顺序一致，可通过调整数组顺序改变导航顺序
+
+8. **RSS（articles Phase 2）**
+   - `rss.*`：仅用于 `npm run sync-articles`（联网抓取 RSS/Atom 并写入缓存）
+   - `npm run build` 默认不联网；无缓存时 `articles` 页面会回退到 Phase 1 的站点入口展示
+   - articles 页面会按 `articles.yml` 的分类进行聚合展示：某分类下配置的来源站点，其文章会显示在该分类下
+   - 抓取条数默认：每个来源站点抓取最新 8 篇（可通过 `site.yml -> rss.articles.perSite` 或 `RSS_ARTICLES_PER_SITE` 调整）
+   - 默认配置已将 `rss.cacheDir` 设为 `dev`（仓库默认 gitignore），避免误提交缓存文件；可按需改为自定义目录
+   - GitHub Pages 部署工作流会在构建前自动执行 `npm run sync-articles`，并支持定时触发（默认每天 UTC 02:00；可在 `.github/workflows/deploy.yml` 调整）
+
+9. **GitHub（projects 热力图，可选）**
+   - `github.username`：你的 GitHub 用户名（用于 projects 页面标题栏右侧贡献热力图）
+   - `github.heatmapColor`：热力图主题色（不带 `#`，例如 `339af0`）
+   - `github.cacheDir`：projects 仓库元信息缓存目录（默认 `dev`，仓库默认 gitignore）
+   - projects 仓库统计信息（language/stars/forks）由 `npm run sync-projects` 自动抓取并写入缓存；`npm run build` 默认不联网
+   - GitHub Pages 部署工作流会在构建前自动执行 `npm run sync-projects`，并支持定时触发（默认每天 UTC 02:00；可在 `.github/workflows/deploy.yml` 调整）
+
+### pages/ 页面配置
+
+页面配置位于 `pages/*.yml`，每个文件对应一个页面内容，文件名与导航 `id` 对应：
+
+- `pages/common.yml`：示例首页（通常是 `categories -> sites`）
+- `pages/projects.yml` / `articles.yml`：示例页面（可按需删改）
+- `pages/bookmarks.yml`：书签页（通常由导入脚本生成，也可以手动维护）
+
+> 提示：自定义页面时，先在 `site.yml` 的 `navigation` 中增加一个 `id`，再创建同名的 `pages/<id>.yml`。
+>
+> 支持“可删除”：如果 `navigation` 中存在某个页面 `id`，但 `pages/<id>.yml` 不存在，构建仍会生成该页面（标题回退为导航名称、分类为空、模板默认使用通用 `page`）。
+>
+> 站点描述建议简洁（例如不超过 30 个字符），以保证卡片展示更美观。
+
+#### 通用 page 页面配置（推荐，用于 friends 等普通页面）
+
+对不需要特殊渲染的页面（例如“友链/朋友”页），建议使用通用 `page` 模板，并保持 `categories -> sites`（可选更深层级）：
+
+```yaml
+title: 示例页面
+subtitle: 示例副标题
+template: page
+
+categories:
+  - name: 示例分类
+    icon: fas fa-folder
+    sites:
+      - name: 示例站点
+        url: https://example.com
+        icon: fas fa-link
+        description: 示例描述
+```
+
+兼容说明：
+
+- 若历史配置仍使用顶层 `sites`（旧结构），系统会自动映射为一个分类容器以保持页面结构一致（当前仅对 friends/articles 提供该兼容）。
+
+#### 内容页（template: content）
+
+内容页用于承载“关于 / 帮助 / 使用说明 / 更新日志 / 迁移指南 / 隐私说明”等纯文本内容。
+
+配置要点：
+
+- `template: content`
+- `content.file`：指向本地 Markdown 文件路径（推荐放在 `content/` 下）
+- Markdown 会在**构建期**渲染为 HTML（不是运行时 fetch）
+- 当前约束：
+  - 禁止 raw HTML（避免 XSS）
+  - 禁止图片（`![]()` 不会输出 `<img>`；本期不支持图片/附件）
+  - 链接会按 URL scheme 白名单策略处理：
+    - 默认允许：`http/https/mailto/tel` + 所有相对链接（`#`、`/`、`./`、`../`、`?` 开头）
+    - 其他 scheme 会被安全降级为 `#`（可用 `site.yml -> security.allowedSchemes` 显式放行）
+
+示例（以 about 页面为例）：
+
+```yml
+# config/user/pages/about.yml
+title: 关于
+subtitle: 项目说明
+template: content
+
+content:
+  file: content/about.md
+```
+
+对应内容文件：
+
+```text
+content/about.md
+```
+
+### 多层级嵌套配置（2-4层）
+
+书签与分类支持 2~4 层嵌套，用于更好组织大量站点。建议直接参考默认示例：
+
+- 多层级结构示例：[`_default/pages/bookmarks.yml`](_default/pages/bookmarks.yml)（包含2层、3层、4层结构示例）
+
+层级命名约定（自顶向下）：
+
+1. `categories`：顶层分类
+2. `subcategories`：子分类
+3. `groups`：分组
+4. `subgroups`：子分组
+5. `sites`：站点（叶子节点）
+
+若你需要第 4 层（`subgroups`），结构示例（片段）：
+
+```yaml
+categories:
+  - name: 示例分类
+    subcategories:
+      - name: 示例子分类
+        groups:
+          - name: 示例分组
+            subgroups:
+              - name: 示例子分组
+                sites:
+                  - name: 示例站点
+                    url: https://example.com
+```
+
+#### 向后兼容性
+
+- 原有二层结构（`categories -> sites`）无需修改即可继续使用
+- 系统会自动识别层级结构并匹配对应的模板/样式
+- 允许在同一份配置中混用不同层级（例如某些分类是二层，某些分类是三/四层）
+
+## 配置优先级
+
+MeNav 配置系统采用“完全替换”策略：只会选择一套目录加载，不会把 `user` 与 `_default` 混合合并。
+
+- 若存在 `config/user/`：只加载 `config/user/`，并**完全忽略** `config/_default/`
+- 否则：加载 `config/_default/`
+
+在“同一套目录”内，各文件的关系是：
+
+- `site.yml`：站点全局配置（包含 `navigation` 等）
+- `pages/*.yml`：各页面配置（文件名需与 `navigation.id` 对应）
+
+## 配置示例
+
+### 网站配置示例 (site.yml)
+
+```yaml
+# 网站基本信息
+title: '我的个人导航'
+description: '个人收藏的网站导航页'
+keywords: '导航,网址,书签,个人主页'
+
+# 个人资料配置
+profile:
+  title: '个人导航站'
+  subtitle: '我收藏的精选网站'
+
+# 字体：全站基础字体
+fonts:
+  source: css
+  cssUrl: 'https://fontsapi.zeoseven.com/292/main/result.css'
+  preload: true
+  family: 'LXGW WenKai'
+  weight: normal
+
+# 社交媒体链接
+social:
+  - name: 'GitHub'
+    url: 'https://github.com/username'
+    icon: 'fab fa-github'
+  - name: 'Twitter'
+    url: 'https://twitter.com/username'
+    icon: 'fab fa-twitter'
+
+# 导航配置
+navigation:
+  - name: '常用'
+    icon: 'fas fa-star'
+    id: 'common'
+  - name: '项目'
+    icon: 'fas fa-project-diagram'
+    id: 'projects'
+  - name: '文章'
+    icon: 'fas fa-book'
+    id: 'articles'
+  - name: '书签'
+    icon: 'fas fa-bookmark'
+    id: 'bookmarks'
+```
+
+### 通用页面配置示例（例如 common.yml）
+
+```yaml
+# 页面分类配置
+categories:
+  - name: '常用工具'
+    icon: 'fas fa-tools'
+    sites:
+      - name: 'Google'
+        url: 'https://www.google.com'
+        description: '全球最大的搜索引擎'
+        icon: 'fab fa-google'
+      - name: 'GitHub'
+        url: 'https://github.com'
+        description: '代码托管平台'
+        icon: 'fab fa-github'
+
+  - name: '学习资源'
+    icon: 'fas fa-graduation-cap'
+    sites:
+      - name: 'MDN Web Docs'
+        url: 'https://developer.mozilla.org'
+        description: 'Web开发技术文档'
+        icon: 'fab fa-firefox-browser'
+```
+
+## 最佳实践
+
+1. **目录结构**:
+   - 总是在 `user/` 目录下创建您的配置
+   - 不要直接修改 `_default/` 中的文件
+
+2. **文件命名**:
+   - 遵循现有的文件命名约定
+   - 自定义页面配置应使用有意义的名称
+
+3. **配置管理**:
+   - 利用模块化结构分类管理配置
+   - 首次使用建议先完整复制 `config/_default/` 到 `config/user/`，再按需修改
+   - 定期备份您的用户配置
+
+4. **配置验证**:
+   - 修改配置后运行 `npm run check`（语法检查 + 单测 + 构建）
+   - 需要本地预览时运行 `npm run dev`（命令入口见 [`../README.md#快速开始`](../README.md#快速开始)）
+   - 确保 YAML 语法正确无误
diff --git a/config/update-instructions-20251227.md b/config/update-instructions-20251227.md
new file mode 100644
index 0000000000000000000000000000000000000000..f4d6598ecce81ae5c306011589d70432fb51a11b
--- /dev/null
+++ b/config/update-instructions-20251227.md
@@ -0,0 +1,114 @@
+# 更新说明（2025-12-27）
+
+本文档用于说明“页面模板差异化改进”相关改动中，**配置层面的新增字段、减少字段与迁移要点**。内容与 [`README.md`](../README.md) 的“2025/12/27 更新记录”保持一致。
+
+最后更新：2025-12-27
+
+---
+
+## 1. 新增/扩展的配置字段
+
+### 1.1 `site.rss.*`（articles RSS 聚合 / 缓存）
+
+用途：为 `articles` 页面提供 RSS/Atom 文章聚合数据，供 `npm run sync-articles` 联网抓取并写入缓存；`npm run build` 默认不联网，只读取缓存渲染。
+
+关键字段（默认示例见 `config/_default/site.yml`）：
+
+- `site.rss.enabled`：是否启用 RSS 抓取能力
+- `site.rss.cacheDir`：缓存目录（建议 `dev/`，仓库默认 gitignore）
+- `site.rss.fetch.*`：抓取参数（超时、并发、重试、重定向等）
+- `site.rss.articles.*`：抓取条数与摘要长度（例如每站点最多 8 篇）
+
+说明：
+
+- RSS 抓取只影响 `articles` Phase 2（文章条目只读展示），不会影响扩展对“来源站点（sites）”的写回能力（构建会保留影子写回结构）。
+
+---
+
+### 1.2 `site.github.*`（projects 仓库元信息 + 热力图）
+
+用途：
+
+- projects 卡片可展示仓库元信息（language/stars/forks 等，只读），由 `npm run sync-projects` 联网抓取并写入缓存。
+- projects 标题区右侧可选展示 GitHub 贡献热力图。
+
+关键字段（默认示例见 `config/_default/site.yml`）：
+
+- `site.github.username`：GitHub 用户名；为空则不展示热力图
+- `site.github.heatmapColor`：热力图主题色（不带 `#`，如 `339af0`）
+- `site.github.cacheDir`：仓库元信息缓存目录（建议 `dev/`）
+
+说明：
+
+- 仓库元信息来自 GitHub API，属于“时效性数据”，不会写回到 `pages/projects.yml`。
+
+---
+
+### 1.3 `pages/<id>.yml -> template`（页面模板选择）
+
+用途：指定页面使用的模板（对应 `templates/pages/<template>.hbs`，不含扩展名）。
+
+行为规则：
+
+- 若 `template` 缺省：优先尝试同名模板（`templates/pages/<pageId>.hbs`），不存在则回退到通用 `page` 模板。
+- `bookmarks/projects/articles` 等特殊页建议显式配置 `template`，以减少误解。
+
+---
+
+## 2. 减少/不再支持的配置方式（Breaking）
+
+### 2.1 根目录单文件配置 `config.yml` / `config.yaml`
+
+当前版本不再回退读取根目录 `config.yml`/`config.yaml`。
+
+迁移要点：
+
+- 使用模块化配置目录：`config/user/`（优先级最高，完全替换）或 `config/_default/`（默认示例）。
+- 推荐迁移方式：复制 `config/_default/` → `config/user/`，再按需修改 `site.yml` 与 `pages/*.yml`。
+
+---
+
+### 2.2 独立 `navigation.yml`
+
+当前版本仅从 `site.yml -> navigation` 读取导航配置，不再读取 `navigation.yml`。
+
+迁移要点：
+
+- 将原 `navigation.yml` 的数组内容移动到 `config/user/site.yml` 的 `navigation:` 字段下。
+
+---
+
+### 2.3 `pages/home.yml -> 顶层 categories` 与 `home` 子菜单特例
+
+当前版本不再维护“首页固定叫 `home`”的遗留逻辑（例如把 `pages/home.yml` 的分类提升到顶层 `config.categories`）。
+
+迁移要点：
+
+- 不要依赖固定页面 id `home`。
+- 首页始终由 `site.yml -> navigation` 的**第一项**决定；其分类内容应写在对应的 `pages/<homePageId>.yml` 中。
+
+---
+
+### 2.4 `navigation[].active` 不再生效（首页不再靠 active 指定）
+
+历史版本可能通过 `navigation[].active` 指定“默认打开页/首页”。
+
+当前版本：
+
+- 首页/默认打开页始终由 `site.yml -> navigation` 的**第一项**决定
+- `active` 字段将被忽略（即使写了也不会生效）
+
+迁移要点：
+
+- 通过调整 `navigation` 数组顺序来设置首页（把希望作为首页的页面放到第一项）。
+
+---
+
+## 3. 与更新记录的对应关系（快速索引）
+
+- 首页判定规则：`site.yml -> navigation` 第一项
+- 模板体系：`pages/<id>.yml -> template`（缺省回退 `page`）
+- bookmarks 更新时间：构建期注入（不需要新增配置字段）
+- articles RSS：`site.rss.*` + `npm run sync-articles`
+- projects 元信息/热力图：`site.github.*` + `npm run sync-projects`
+- 兼容清理：移除 `config.yml/config.yaml`、`navigation.yml`、`home` 特例
diff --git a/config/update-instructions-20260102.md b/config/update-instructions-20260102.md
new file mode 100644
index 0000000000000000000000000000000000000000..b1f7737588c2efa186e4c723686efe2856697b35
--- /dev/null
+++ b/config/update-instructions-20260102.md
@@ -0,0 +1,102 @@
+# 更新说明（2026-01-02）
+
+本文档用于说明 Issue #30（外部资源/图标/嵌套交互）相关改动中，**配置层面的新增字段、行为变更与迁移要点**。
+
+关联 Issue：https://github.com/rbetree/menav/issues/30
+
+最后更新：2026-01-02
+
+---
+
+## 1. 新增/扩展的配置字段
+
+### 1.1 `site.yml -> icons.mode`（站点卡片图标模式 / 隐私）
+
+用途：控制“站点卡片图标”的全局渲染方式。
+
+取值：
+
+- `favicon`：根据站点 URL 通过第三方服务加载站点 favicon（失败时回退到 Font Awesome 图标）
+- `manual`：始终使用配置中的 Font Awesome 图标类名（不发起 favicon 外部请求）
+
+注意：
+
+- 该配置位于 `site.yml` 的 `icons:` 节点下（默认示例见 `config/_default/site.yml`）。
+- 配置目录采用“完全替换”策略：若启用 `config/user/`，需要在 `config/user/site.yml` 中设置该字段才会生效。
+- 切换后需要重新生成页面（`npm run build` / `npm run dev`）才能影响生成的 HTML。
+
+示例：
+
+```yml
+# config/user/site.yml
+icons:
+  mode: manual
+```
+
+---
+
+### 1.2 `pages/*.yml -> sites[].faviconUrl`（站点级自定义图标链接）
+
+用途：为单个站点指定图标链接（可远程或本地相对路径），用于兜底“favicon 服务返回默认图标/网络不可达”等情况。
+
+说明：
+
+- `faviconUrl` 优先级最高：一旦设置，将直接使用该图片链接渲染图标。
+- 本地路径建议以 `assets/` 开头；构建时会复制到 `dist/` 同路径，便于离线/内网使用。
+
+示例：
+
+```yml
+sites:
+  - name: '内部系统'
+    url: 'https://intranet.example/'
+    faviconUrl: 'assets/icons/intranet.png'
+```
+
+---
+
+### 1.3 `pages/*.yml -> sites[].forceIconMode`（站点级强制图标模式）
+
+用途：强制该站点使用指定模式（不设置则跟随全局 `icons.mode`）。
+
+取值：
+
+- `favicon`：强制走 favicon（外部请求）
+- `manual`：强制走手动图标（不发起 favicon 外部请求）
+
+优先级：
+
+- `faviconUrl` > `forceIconMode` > 全局 `icons.mode`
+
+示例：
+
+```yml
+sites:
+  - name: 'Ant Design'
+    url: 'https://ant.design/'
+    icon: 'fas fa-th'
+    forceIconMode: manual
+```
+
+---
+
+## 2. 行为变更与修复要点（无需迁移字段）
+
+### 2.1 `icons.mode` 全局切换修复
+
+修复点：此前 `site.yml` 中的 `icons` 没有被提升为顶层 `icons`，导致模板与运行时读取到的仍是默认 `favicon`。本次已修复，`site.yml -> icons.mode` 会被模板/运行时统一读取生效。
+
+### 2.2 favicon 双域名回退（`.com` → `.cn`）
+
+修复点：favicon 默认使用 `t3.gstatic.com`，失败时自动切换 `t3.gstatic.cn` 重试一次，提升国内网络可用性。
+
+### 2.3 多级结构站点新标签页打开一致性
+
+修复点：多级结构（`subcategories/groups/subgroups`）下站点默认值未递归补齐，导致 `external` 为 `undefined` 时不输出 `target="_blank"`。本次已在生成阶段递归补齐 `sites[].external` 默认 `true`（显式 `external: false` 保持同页打开）。
+
+---
+
+## 3. 迁移建议（从旧版本升级）
+
+1. 若使用 `config/user/`：请在 `config/user/site.yml` 中设置 `icons.mode`，然后执行 `npm run build` 重新生成页面。
+2. 若遇到某些站点 favicon 始终显示默认图标：建议对该站点配置 `forceIconMode: manual`（使用 Font Awesome）或提供 `faviconUrl` 指向可靠图片（远程或本地 `assets/`）。
diff --git a/config/user/pages/articles.yml b/config/user/pages/articles.yml
new file mode 100644
index 0000000000000000000000000000000000000000..de152914885b7e630f7c5f361bb53562dbd2477e
--- /dev/null
+++ b/config/user/pages/articles.yml
@@ -0,0 +1,43 @@
+# 默认页面配置（请勿直接修改）。
+# 建议复制到 config/user/pages/articles.yml 并按需调整。
+title: 技术文章 # 页面标题
+subtitle: RSS 聚合文章列表 # 页面副标题
+
+# 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
+template: articles
+
+# 当存在 RSS 缓存时，页面将优先渲染“文章条目卡片”（只读）。
+# - 本处的站点列表作为“来源站点”输入（url 填站点首页）
+# - 显示时会将“该分类下配置的站点”抓取到的文章聚合展示在该分类下
+# 重要：url 应填写“站点首页 URL”（不是某一篇文章链接），系统会自动发现 RSS/Atom。
+categories:
+  - name: 个人博客
+    icon: fas fa-rss
+    sites:
+      - name: 阮一峰的网络日志
+        icon: fas fa-pen
+        description: 技术文章与随笔
+        url: https://www.ruanyifeng.com/blog/
+      - name: Coolzr's Blog
+        icon: fas fa-pen
+        description: 偶尔会写点什么
+        url: https://blog.rzlnb.top/
+      - name: 天仙子
+        icon: fas fa-pen
+        description: tianxianzi
+        url: https://www.tianxianzi.me/
+      - name: pseudoyu
+        icon: fas fa-pen
+        description: pseudoyu
+        url: https://www.pseudoyu.com/
+  - name: 官方博客
+    icon: fas fa-rss
+    sites:
+      - name: GitHub Blog
+        icon: fab fa-github
+        description: GitHub 官方博客（工程/产品/安全）
+        url: https://github.blog/
+      - name: Cloudflare Blog
+        icon: fas fa-cloud
+        description: Cloudflare 工程与安全博客
+        url: https://blog.cloudflare.com/
diff --git a/config/user/pages/bookmarks.yml b/config/user/pages/bookmarks.yml
new file mode 100644
index 0000000000000000000000000000000000000000..23d72be39a3b18e12e3875033a4738631e131d71
--- /dev/null
+++ b/config/user/pages/bookmarks.yml
@@ -0,0 +1,251 @@
+# 默认页面配置（请勿直接修改）。
+# 建议复制到 config/user/pages/bookmarks.yml 并按需调整。
+# 说明：该页面通常由“书签导入工具”自动生成，手工修改时请保持字段结构一致。
+title: 书签
+subtitle: bookmarks
+
+# 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
+# 提示：bookmarks 模板页面标题区会自动显示“内容更新：YYYY-MM-DD（git|mtime）”，无需额外配置
+template: bookmarks
+
+categories:
+  - name: '常用网站'
+    icon: 'fas fa-star'
+    sites:
+      - name: 'GitHub'
+        url: 'https://github.com/'
+        icon: 'fab fa-github'
+        description: '代码托管平台'
+      - name: 'Stack Overflow'
+        url: 'https://stackoverflow.com/'
+        icon: 'fab fa-stack-overflow'
+        description: '程序员问答社区'
+      - name: 'MDN Web Docs'
+        url: 'https://developer.mozilla.org/'
+        icon: 'fas fa-book'
+        description: 'Web开发文档'
+
+  - name: '社交媒体'
+    icon: 'fas fa-share-alt'
+    groups:
+      - name: '国际平台'
+        icon: 'fas fa-globe'
+        sites:
+          - name: 'Twitter'
+            url: 'https://twitter.com/'
+            icon: 'fab fa-twitter'
+            description: '微博客社交平台'
+          - name: 'LinkedIn'
+            url: 'https://www.linkedin.com/'
+            icon: 'fab fa-linkedin'
+            description: '职业社交网络'
+          - name: 'Facebook'
+            url: 'https://www.facebook.com/'
+            icon: 'fab fa-facebook'
+            description: '社交网络服务'
+      - name: '国内平台'
+        icon: 'fas fa-map-marker-alt'
+        sites:
+          - name: '微博'
+            url: 'https://weibo.com/'
+            icon: 'fas fa-comment'
+            description: '中文社交媒体平台'
+          - name: '知乎'
+            url: 'https://www.zhihu.com/'
+            icon: 'fas fa-question-circle'
+            description: '中文问答社区'
+          - name: 'B站'
+            url: 'https://www.bilibili.com/'
+            icon: 'fas fa-video'
+            description: '弹幕视频网站'
+
+  - name: '技术资源'
+    icon: 'fas fa-laptop-code'
+    subcategories:
+      - name: '前端开发'
+        icon: 'fas fa-code'
+        groups:
+          - name: '框架库'
+            icon: 'fas fa-cube'
+            sites:
+              - name: 'React'
+                url: 'https://reactjs.org/'
+                icon: 'fab fa-react'
+                description: 'React官方文档'
+              - name: 'Vue.js'
+                url: 'https://vuejs.org/'
+                icon: 'fab fa-vuejs'
+                description: 'Vue.js官方文档'
+              - name: 'Angular'
+                url: 'https://angular.io/'
+                icon: 'fab fa-angular'
+                description: 'Angular官方文档'
+          - name: '状态管理'
+            icon: 'fas fa-database'
+            sites:
+              - name: 'Redux'
+                url: 'https://redux.js.org/'
+                icon: 'fas fa-database'
+                description: 'Redux状态管理'
+              - name: 'Vuex'
+                url: 'https://vuex.vuejs.org/'
+                icon: 'fas fa-database'
+                description: 'Vue状态管理'
+              - name: 'MobX'
+                url: 'https://mobx.js.org/'
+                icon: 'fas fa-react'
+                description: '响应式状态管理'
+          - name: '构建工具'
+            icon: 'fas fa-tools'
+            sites:
+              - name: 'Webpack'
+                url: 'https://webpack.js.org/'
+                icon: 'fas fa-cube'
+                description: '模块打包工具'
+              - name: 'Vite'
+                url: 'https://vitejs.dev/'
+                icon: 'fas fa-bolt'
+                description: '下一代前端构建工具'
+              - name: 'Rollup'
+                url: 'https://rollupjs.org/'
+                icon: 'fas fa-compress'
+                description: '模块打包器'
+      - name: '后端开发'
+        icon: 'fas fa-server'
+        groups:
+          - name: 'Node.js生态'
+            icon: 'fab fa-node-js'
+            sites:
+              - name: 'Express'
+                url: 'https://expressjs.com/'
+                icon: 'fas fa-server'
+                description: 'Node.js Web框架'
+              - name: 'Koa'
+                url: 'https://koajs.com/'
+                icon: 'fas fa-leaf'
+                forceIconMode: manual
+                description: '下一代Node.js框架'
+              - name: 'NestJS'
+                url: 'https://nestjs.com/'
+                icon: 'fas fa-home'
+                description: 'Node.js企业级框架'
+          - name: 'Python框架'
+            icon: 'fab fa-python'
+            sites:
+              - name: 'Django'
+                url: 'https://www.djangoproject.com/'
+                icon: 'fab fa-python'
+                description: 'Python Web框架'
+              - name: 'Flask'
+                url: 'https://flask.palletsprojects.com/'
+                icon: 'fas fa-flask'
+                description: 'Python微框架'
+              - name: 'FastAPI'
+                url: 'https://fastapi.tiangolo.com/'
+                icon: 'fas fa-bolt'
+                description: '现代Python Web框架'
+
+  - name: '设计资源'
+    icon: 'fas fa-palette'
+    subcategories:
+      - name: 'UI设计工具'
+        icon: 'fas fa-paint-brush'
+        groups:
+          - name: '原型设计'
+            icon: 'fas fa-drafting-compass'
+            sites:
+              - name: 'Figma'
+                url: 'https://www.figma.com/'
+                icon: 'fab fa-figma'
+                description: '协作式UI设计工具'
+              - name: 'Sketch'
+                url: 'https://www.sketch.com/'
+                icon: 'fab fa-sketch'
+                description: 'Mac平台UI设计工具'
+              - name: 'Adobe XD'
+                url: 'https://www.adobe.com/products/xd.html'
+                icon: 'fab fa-adobe'
+                description: 'Adobe UI设计工具'
+          - name: '设计系统'
+            icon: 'fas fa-th-large'
+            sites:
+              - name: 'Ant Design'
+                url: 'https://ant.design/'
+                icon: 'fas fa-th'
+                forceIconMode: manual
+                description: '企业级UI设计语言'
+              - name: 'Material Design'
+                url: 'https://material.io/design'
+                icon: 'fas fa-cube'
+                description: 'Google设计系统'
+              - name: 'Bootstrap'
+                url: 'https://getbootstrap.com/'
+                icon: 'fab fa-bootstrap'
+                description: '响应式CSS框架'
+      - name: '视觉资源'
+        icon: 'fas fa-image'
+        groups:
+          - name: '图标库'
+            icon: 'fas fa-icons'
+            sites:
+              - name: 'Font Awesome'
+                url: 'https://fontawesome.com/'
+                icon: 'fab fa-font-awesome'
+                description: '图标库'
+              - name: 'Iconfont'
+                url: 'https://www.iconfont.cn/'
+                icon: 'fas fa-icons'
+                description: '阿里巴巴图标库'
+              - name: 'Feather Icons'
+                url: 'https://feathericons.com/'
+                icon: 'fas fa-feather'
+                description: '简洁的图标库'
+          - name: '配色方案'
+            icon: 'fas fa-palette'
+            sites:
+              - name: 'Coolors'
+                url: 'https://coolors.co/'
+                icon: 'fas fa-palette'
+                description: '在线配色方案生成器'
+              - name: 'Adobe Color'
+                url: 'https://color.adobe.com/'
+                icon: 'fab fa-adobe'
+                description: 'Adobe配色工具'
+              - name: 'Paletton'
+                url: 'https://paletton.com/'
+                icon: 'fas fa-palette'
+                description: '配色方案设计工具'
+
+  - name: '开发工具'
+    icon: 'fas fa-tools'
+    groups:
+      - name: '代码编辑器'
+        icon: 'fas fa-code'
+        sites:
+          - name: 'Visual Studio Code'
+            url: 'https://code.visualstudio.com/'
+            icon: 'fas fa-code'
+            description: '微软代码编辑器'
+          - name: 'Sublime Text'
+            url: 'https://www.sublimetext.com/'
+            icon: 'fas fa-file-code'
+            description: '轻量级代码编辑器'
+          - name: 'WebStorm'
+            url: 'https://www.jetbrains.com/webstorm/'
+            icon: 'fab fa-js'
+            description: 'JetBrains前端IDE'
+      - name: '版本控制'
+        icon: 'fas fa-code-branch'
+        sites:
+          - name: 'GitHub'
+            url: 'https://github.com/'
+            icon: 'fab fa-github'
+            description: '代码托管平台'
+          - name: 'GitLab'
+            url: 'https://gitlab.com/'
+            icon: 'fab fa-gitlab'
+            description: 'Git代码管理平台'
+          - name: 'Bitbucket'
+            url: 'https://bitbucket.org/'
+            icon: 'fab fa-bitbucket'
+            description: 'Atlassian代码托管'
diff --git a/config/user/pages/common.yml b/config/user/pages/common.yml
new file mode 100644
index 0000000000000000000000000000000000000000..53da6c3ebe9b2282021d4e3f23016dd67dcc58c2
--- /dev/null
+++ b/config/user/pages/common.yml
@@ -0,0 +1,143 @@
+# 默认页面配置（请勿直接修改）。
+# 建议复制到 config/user/pages/common.yml 并按需调整。
+title: 常用网站 # 页面标题
+subtitle: Common website # 页面副标题
+
+# 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
+# 说明：推荐使用通用模板 page；首页由“导航第一项”决定
+template: page
+
+# 页面分类与站点列表
+categories:
+  - name: 置顶
+    icon: fas fa-star # 分类图标
+    sites:
+      - name: Linux.do # 站点名称
+        url: https://linux.do/ # http/https URL（favicon 模式将尝试加载站点图标）
+        icon: fab fa-linux # 手动图标：manual 模式使用；favicon 模式下作为回退
+        description: 新的理想型社区 # 站点描述
+      - name: Menav
+        url: https://rbetree.github.io/menav
+        icon: fas fa-star
+        description: 个人导航站
+        faviconUrl: assets/menav.svg
+      - name: Google
+        url: https://www.google.com
+        icon: fab fa-google
+        description: 全球最大的搜索引擎
+      - name: GitHub
+        url: https://www.github.com
+        icon: fab fa-github
+        description: 代码托管平台
+      - name: Stack Overflow
+        url: https://stackoverflow.com
+        icon: fab fa-stack-overflow
+        description: 程序员问答社区
+      - name: ChatGPT
+        url: https://chat.openai.com
+        icon: fas fa-robot
+        description: AI智能助手
+      - name: YouTube
+        url: https://www.youtube.com
+        icon: fab fa-youtube
+        description: 视频分享平台
+      - name: Twitter
+        url: https://twitter.com
+        icon: fab fa-twitter
+        description: 社交媒体平台
+      - name: Reddit
+        url: https://www.reddit.com
+        icon: fab fa-reddit
+        description: 社区讨论平台
+  - name: 学习资源
+    icon: fas fa-graduation-cap
+    sites:
+      - name: 哔哩哔哩
+        url: https://www.bilibili.com
+        icon: fas fa-play-circle
+        description: 视频学习平台
+      - name: 掘金
+        url: https://juejin.cn
+        icon: fas fa-book
+        description: 高质量技术社区
+      - name: LeetCode
+        url: https://leetcode.cn
+        icon: fas fa-code
+        description: 算法刷题平台
+  - name: 设计资源
+    icon: fas fa-palette
+    sites:
+      - name: Figma
+        url: https://www.figma.com
+        icon: fab fa-figma
+        description: 在线设计工具
+      - name: Dribbble
+        url: https://dribbble.com
+        icon: fab fa-dribbble
+        description: 设计师社区
+      - name: IconFont
+        url: https://www.iconfont.cn
+        icon: fas fa-icons
+        description: 图标资源库
+      - name: Adobe XD
+        url: https://www.adobe.com/products/xd.html
+        icon: fab fa-adobe
+        description: UI/UX设计工具
+      - name: Sketch
+        url: https://www.sketch.com
+        icon: fas fa-pencil-ruler
+        description: 矢量设计工具
+      - name: Canva
+        url: https://www.canva.com
+        icon: fas fa-paint-brush
+        description: 在线平面设计
+  - name: 在线工具
+    icon: fas fa-wrench
+    sites:
+      - name: JSON Editor
+        url: https://jsoneditoronline.org
+        icon: fas fa-code-branch
+        description: JSON在线编辑器
+      - name: Can I Use
+        url: https://caniuse.com
+        icon: fas fa-browser
+        description: 浏览器兼容性查询
+      - name: TinyPNG
+        url: https://tinypng.com
+        icon: fas fa-compress
+        description: 图片压缩工具
+      - name: Carbon
+        url: https://carbon.now.sh
+        icon: fas fa-code
+        description: 代码图片生成器
+      - name: Excalidraw
+        url: https://excalidraw.com
+        icon: fas fa-pencil-alt
+        description: 手绘风格图表工具
+  - name: 云服务平台
+    icon: fas fa-cloud
+    sites:
+      - name: Cloudflare
+        url: https://www.cloudflare.com
+        icon: fas fa-cloud
+        description: CDN与安全服务
+      - name: Vercel
+        url: https://vercel.com
+        icon: fas fa-server
+        description: 前端部署平台
+      - name: Netlify
+        url: https://www.netlify.com
+        icon: fas fa-globe
+        description: 静态网站托管
+      - name: AWS
+        url: https://aws.amazon.com
+        icon: fab fa-aws
+        description: 亚马逊云服务
+      - name: Azure
+        url: https://azure.microsoft.com
+        icon: fab fa-microsoft
+        description: 微软云平台
+      - name: Google Cloud
+        url: https://cloud.google.com
+        icon: fab fa-google
+        description: 谷歌云平台
diff --git a/config/user/pages/content.yml b/config/user/pages/content.yml
new file mode 100644
index 0000000000000000000000000000000000000000..f395f2e28aa98e14aa0c93db221b3e0143f49453
--- /dev/null
+++ b/config/user/pages/content.yml
@@ -0,0 +1,12 @@
+# 默认页面配置（请勿直接修改）。
+# 建议复制到 config/user/pages/content.yml 并按需调整。
+title: 关于
+subtitle: 项目说明
+
+# 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
+# 内容页模板（templates/pages/content.hbs）
+template: content
+
+# 本期仅支持文件模式：读取本地 markdown 文件
+content:
+  file: content/about.md
diff --git a/config/user/pages/projects.yml b/config/user/pages/projects.yml
new file mode 100644
index 0000000000000000000000000000000000000000..0791d0713e3352336379d17fa1b32ee282dbd6bd
--- /dev/null
+++ b/config/user/pages/projects.yml
@@ -0,0 +1,33 @@
+# 默认页面配置（请勿直接修改）。
+# 建议复制到 config/user/pages/projects.yml 并按需调整。
+title: 项目 # 页面标题
+subtitle: 项目展示 # 页面副标题
+
+# 指定使用的模板文件名，现有页面模板可见 templates/pages（不含 .hbs）
+template: projects
+
+# 页面分类与站点列表
+#
+# projects 模板采用“代码仓库风”卡片（repo 风格）。
+# 统计信息（language/stars/forks）为自动获取数据：
+# - 运行 `npm run sync-projects` 会联网抓取 GitHub 仓库信息，并写入 dev/ 缓存（仓库默认 gitignore）
+# - `npm run build` 默认不联网；缓存缺失时卡片仅展示标题与描述
+categories:
+  - name: 个人项目
+    icon: fas fa-code # 分类图标（Font Awesome）
+    sites:
+      - name: MeNav
+        icon: fab fa-github # 手动图标（manual 模式显示；favicon 模式下作为回退）
+        description: 一键部署的个人导航站生成器，支持书签导入与自动构建，轻松整理展示您的网络收藏 # 站点描述
+        url: https://github.com/rbetree/menav
+      - name: MarksVault
+        icon: fab fa-github
+        description: 一个强大的浏览器扩展，用于智能管理、整理和安全备份您的书签数据
+        url: 'https://github.com/rbetree/MarksVault'
+  - name: star
+    icon: fas fa-star
+    sites:
+      - name: CLIProxyAPI
+        icon: fab fa-github
+        description: Wrap Gemini CLI, Antigravity, ChatGPT Codex, Claude Code, Qwen Code, iFlow as an OpenAI/Gemini/Claude/Codex compatible API service, allowing you to enjoy the free Gemini 2.5 Pro, GPT 5, Claude, Qwen model through API
+        url: 'https://github.com/router-for-me/CLIProxyAPI'
diff --git a/config/user/site.yml b/config/user/site.yml
new file mode 100644
index 0000000000000000000000000000000000000000..8e4ec507da2885b961e72b5f5e5da0d4176fe6cf
--- /dev/null
+++ b/config/user/site.yml
@@ -0,0 +1,126 @@
+# 默认配置（请勿直接修改）。
+# 建议复制到 config/user/site.yml 并按需调整；用户配置采用“完全替换”策略，将覆盖默认配置。
+
+# 网站基本信息
+title: MeNav
+description: Personal Navigation Station
+author: rbetree
+favicon: menav.svg
+logo_text: MeNav
+
+icons:
+  # 站点卡片图标模式：
+  # - favicon：自动根据 URL 加载站点 favicon（失败时回退到 Font Awesome 图标）
+  # - manual：始终使用手动指定的 Font Awesome 图标（不发起外部请求）
+  # 隐私提示：启用 favicon 模式会请求第三方服务以获取图标，可能将站点 URL 发送给服务商（详见 README"隐私说明"）。
+  mode: favicon # 可选: favicon | manual（默认 favicon）
+
+  # favicon 服务区域选择（仅在 mode: favicon 时生效）：
+  # - com：优先使用 gstatic.com（国际版），失败后回退到 gstatic.cn（中国版）
+  # - cn：优先使用 gstatic.cn（中国版），失败后回退到 gstatic.com（国际版）
+  # 说明：如果你在中国大陆且访问 gstatic.com 较慢，建议设置为 cn 以提升图标加载速度
+  region: cn # 可选: com | cn（默认 com）
+
+# 安全策略（可选）：链接 URL scheme 白名单
+# - 默认允许：http/https/mailto/tel + 所有相对链接（# / ./ ../ ?）
+# - 其他 scheme 会在页面中安全降级为 # 并输出告警（避免 javascript: 等危险链接变成可点击）
+# - 如需支持 obsidian://、vscode:// 等自定义协议，可在此显式放行
+security:
+  allowedSchemes:
+    - http
+    - https
+    - mailto
+    - tel
+  # 示例：
+  # allowedSchemes: [http, https, mailto, tel, obsidian, vscode]
+
+# 主题设置：默认明暗模式（可选）
+# - mode: dark | light | system
+#   - dark/light：首屏默认主题；用户点击按钮切换后会写入 localStorage 并覆盖该默认值
+#   - system：跟随系统 prefers-color-scheme；用户手动切换后同样会写入 localStorage 并停止跟随
+theme:
+  mode: dark # 可选: dark | light | system（默认 dark）
+
+# 字体设置：全站基础字体
+# - source: css | google | system
+# - css: 通过 cssUrl 引入第三方字体 CSS
+# - google: 通过 Google Fonts 加载 family（weight 建议 100~900）
+# - system: 只使用本地/系统字体，不额外发起请求
+fonts:
+  source: css
+  cssUrl: 'https://fontsapi.zeoseven.com/292/main/result.css'
+  preload: true # 可选：使用 preload+onload 的方式非阻塞加载字体 CSS（更利于首屏性能）
+  family: LXGW WenKai
+  weight: normal
+
+# 示例：切换到 Google Fonts
+# fonts:
+#   source: google
+#   family: "Noto Sans SC"
+#   weight: 400
+
+# 个人资料：显示在首页顶部的欢迎信息
+profile:
+  # 注意：首页（导航第一项）标题区优先使用 profile.title/profile.subtitle
+  # 因此建议把首页希望展示的文案写在这里，避免“改了 pages/<首页id>.yml 但首页不生效”的误会
+  title: Hello,
+  subtitle: Welcome to My Navigation
+
+# RSS（Phase 2）：用于 articles 页面文章聚合
+# 说明：
+# - `npm run build` 默认不联网；仅 `npm run sync-articles` 会联网抓取并写入缓存
+# - 缓存目录建议放在 dev/（仓库默认 gitignore），避免误提交
+rss:
+  enabled: true
+  cacheDir: dev
+  fetch:
+    timeoutMs: 10000 # 单请求超时（毫秒）
+    totalTimeoutMs: 60000 # 全流程总超时（毫秒）
+    concurrency: 5 # 并发抓取站点数
+    maxRetries: 1 # 单站点重试次数（best-effort）
+    maxRedirects: 3 # 最大重定向次数
+  articles:
+    perSite: 8 # 单站点最多抓取条数
+    total: 50 # 全站聚合上限
+    summaryMaxLength: 200 # 摘要最大长度（字符）
+
+# GitHub：用于 projects 页面右侧“贡献热力图”（可选）
+# - username：你的 GitHub 用户名（例如 torvalds）
+# - heatmapColor：热力图主题色（不带 #，例如 339af0）
+github:
+  username: 'rbetree' # 你的 GitHub 用户名（例如 torvalds；为空则 projects 页不展示热力图）
+  heatmapColor: 37b24d
+  cacheDir: dev # projects 仓库元信息缓存目录（默认 dev，仓库默认 gitignore）
+
+# 社交媒体链接：显示在侧边栏底部；可按需增删
+social:
+  - name: GitHub
+    url: https://github.com
+    icon: fab fa-github
+  - name: Telegram
+    url: https://t.me
+    icon: fab fa-telegram
+  - name: Twitter
+    url: https://twitter.com
+    icon: fab fa-twitter
+  - name: Steam
+    url: https://steam.com
+    icon: fab fa-steam
+
+# 导航配置（顺序第一项即首页/默认打开页）
+navigation:
+  - name: 常用 # 菜单名称
+    icon: fas fa-star # Font Awesome 图标类
+    id: common # 页面标识符（唯一，需与 pages/<id>.yml 对应）
+  - name: 项目
+    icon: fas fa-project-diagram
+    id: projects
+  - name: 文章
+    icon: fas fa-book
+    id: articles
+  - name: 书签
+    icon: fas fa-bookmark
+    id: bookmarks
+  - name: 关于
+    icon: fas fa-file-alt
+    id: content
diff --git a/content/about.md b/content/about.md
new file mode 100644
index 0000000000000000000000000000000000000000..738d56a0ffb2106e49a03c52df9461fa86c707b0
--- /dev/null
+++ b/content/about.md
@@ -0,0 +1,65 @@
+# 关于 MeNav
+
+MeNav 是一个用于生成**个人导航站**的项目：
+
+- **构建期**：使用 Node.js 作为静态站点生成器（SSG），把配置与内容渲染为 `dist/`。
+- **运行时**：输出一份轻量的浏览器 runtime，用于页面交互与增强。
+
+这页用于放置项目的说明与使用要点（你也可以改成自己的“关于”页面）。
+
+## 适合谁
+
+- 想要一个**可自托管、可版本管理**的导航页/起始页
+- 希望用 **YAML + Markdown** 管理站点结构与内容
+- 更偏好“生成静态文件再部署”，而不是运行时依赖服务端
+
+## 快速开始
+
+```bash
+npm install
+npm run dev
+```
+
+- `npm run dev`：本地开发（生成站点并启动本地服务）
+- `npm run build`：生成生产构建（输出到 `dist/`）
+
+## 项目结构（常用）
+
+- `src/generator/`：构建期生成器（Node.js）
+- `src/runtime/`：浏览器 runtime（最终会被打包到 `dist/script.js`）
+- `templates/`：Handlebars 模板
+- `config/`：站点配置（YAML）
+- `content/`：内容页（Markdown），例如本文件
+- `dist/`：构建输出（可直接部署）
+- `dev/`：网络缓存（gitignored）
+
+## 配置说明（概念）
+
+- MeNav 的站点配置以 `config/` 下的 YAML 为主。
+- **注意**：如果存在 `config/user/`，它会**完全替换** `config/_default/`（不是 merge）。
+
+## 内容页（Markdown）说明
+
+- 内容页的 Markdown 会在**构建期**渲染为 HTML。
+- 内容页通常用于：关于、帮助、使用说明、更新记录等。
+
+## 安全与链接处理
+
+MeNav 对链接会做安全处理（例如限制危险的 URL scheme），以降低把不安全链接渲染到页面上的风险。
+
+如果你在导航数据或内容页里粘贴了外部链接，建议优先使用 `https://`。
+
+## 部署
+
+`npm run build` 后将生成的 `dist/` 部署到任意静态站点托管即可（例如 Nginx、GitHub Pages、Cloudflare Pages 等）。
+
+## 维护建议
+
+- 把你的配置、内容页都纳入 git 版本管理
+- 变更后跑一遍：
+
+```bash
+npm run check
+```
+
+（会依次执行语法检查、测试与构建）
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000000000000000000000000000000000000..fd83db590c8d0cb7851ed64dd7ee1683e0677ba5
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,14 @@
+services:
+  menav:
+    container_name: menav
+    image: ${MENAV_IMAGE:-ghcr.io/rbetree/menav:latest}
+    build: .
+    environment:
+      MENAV_ENABLE_SYNC: ${MENAV_ENABLE_SYNC:-false}
+      MENAV_IMPORT_BOOKMARKS: ${MENAV_IMPORT_BOOKMARKS:-false}
+    ports:
+      - '${MENAV_PORT:-8080}:80'
+    volumes:
+      - ./config:/app/config
+      - ./bookmarks:/app/bookmarks
+    restart: unless-stopped
diff --git a/docker/entrypoint-build-and-serve.sh b/docker/entrypoint-build-and-serve.sh
new file mode 100644
index 0000000000000000000000000000000000000000..425f67c41c7d957d6ab8a74646542c93ec645206
--- /dev/null
+++ b/docker/entrypoint-build-and-serve.sh
@@ -0,0 +1,25 @@
+#!/bin/sh
+set -eu
+
+echo "[menav] starting dynamic build mode"
+
+if [ "${MENAV_IMPORT_BOOKMARKS:-false}" = "true" ]; then
+  echo "[menav] importing bookmarks before build"
+  MENAV_BOOKMARKS_DETERMINISTIC=1 npm run import-bookmarks
+fi
+
+if [ "${MENAV_ENABLE_SYNC:-false}" = "true" ]; then
+  echo "[menav] building with sync enabled"
+  npm run build
+else
+  echo "[menav] building with sync disabled"
+  PROJECTS_ENABLED=false HEATMAP_ENABLED=false RSS_ENABLED=false npm run build
+fi
+
+echo "[menav] syncing dist to nginx web root"
+mkdir -p /usr/share/nginx/html
+rm -rf /usr/share/nginx/html/*
+cp -a /app/dist/. /usr/share/nginx/html/
+
+echo "[menav] serving dist with nginx"
+exec nginx -g 'daemon off;'
diff --git a/docker/nginx/default.conf b/docker/nginx/default.conf
new file mode 100644
index 0000000000000000000000000000000000000000..c8e12e70f9a2e3a3483e4cf685787aacc513c09e
--- /dev/null
+++ b/docker/nginx/default.conf
@@ -0,0 +1,30 @@
+server {
+    listen 80;
+    server_name _;
+
+    root /usr/share/nginx/html;
+    index index.html;
+
+    charset utf-8;
+
+    location = / {
+        try_files /index.html =404;
+        add_header Cache-Control "no-store";
+    }
+
+    location ~* \.(?:css|js|mjs|json|ico|png|jpe?g|gif|svg|webp|txt|xml|map)$ {
+        try_files $uri =404;
+        access_log off;
+        add_header Cache-Control "public, max-age=3600";
+    }
+
+    location ~* \.html$ {
+        try_files $uri =404;
+        add_header Cache-Control "no-store";
+    }
+
+    location / {
+        try_files $uri $uri/ /404.html;
+        add_header Cache-Control "no-store";
+    }
+}
diff --git a/licenses/pinyin-match.NOTICE.md b/licenses/pinyin-match.NOTICE.md
new file mode 100644
index 0000000000000000000000000000000000000000..c1fca38d278700f10d1be589bd9e23deb3a5b747
--- /dev/null
+++ b/licenses/pinyin-match.NOTICE.md
@@ -0,0 +1,7 @@
+Third-party notice: pinyin-match
+
+- File: assets/pinyin-match.js (minified vendor script)
+- Source: To be confirmed; replace with upstream repo URL and exact license.
+- License: To be added (likely MIT). Include the full license text once verified.
+
+Vendored to enable offline builds. This notice will be replaced with the exact license details once confirmed.
diff --git a/package-lock.json b/package-lock.json
new file mode 100644
index 0000000000000000000000000000000000000000..e2015fce1c7ac50fb040d55bf8b4129d0b6c9780
--- /dev/null
+++ b/package-lock.json
@@ -0,0 +1,2174 @@
+{
+  "name": "menav",
+  "version": "1.3.0",
+  "lockfileVersion": 3,
+  "requires": true,
+  "packages": {
+    "": {
+      "name": "menav",
+      "version": "1.3.0",
+      "license": "AGPL-3.0-only",
+      "dependencies": {
+        "handlebars": "^4.7.9",
+        "js-yaml": "^4.1.1",
+        "markdown-it": "^14.1.1",
+        "rss-parser": "^3.13.0"
+      },
+      "devDependencies": {
+        "esbuild": "^0.28.0",
+        "husky": "^9.1.7",
+        "lint-staged": "^16.4.0",
+        "prettier": "^3.8.3",
+        "serve": "^14.2.6"
+      }
+    },
+    "node_modules/@esbuild/aix-ppc64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/aix-ppc64/-/aix-ppc64-0.28.0.tgz",
+      "integrity": "sha512-lhRUCeuOyJQURhTxl4WkpFTjIsbDayJHih5kZC1giwE+MhIzAb7mEsQMqMf18rHLsrb5qI1tafG20mLxEWcWlA==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "aix"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm/-/android-arm-0.28.0.tgz",
+      "integrity": "sha512-wqh0ByljabXLKHeWXYLqoJ5jKC4XBaw6Hk08OfMrCRd2nP2ZQ5eleDZC41XHyCNgktBGYMbqnrJKq/K/lzPMSQ==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-arm64/-/android-arm64-0.28.0.tgz",
+      "integrity": "sha512-+WzIXQOSaGs33tLEgYPYe/yQHf0WTU0X42Jca3y8NWMbUVhp7rUnw+vAsRC/QiDrdD31IszMrZy+qwPOPjd+rw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/android-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/android-x64/-/android-x64-0.28.0.tgz",
+      "integrity": "sha512-+VJggoaKhk2VNNqVL7f6S189UzShHC/mR9EE8rDdSkdpN0KflSwWY/gWjDrNxxisg8Fp1ZCD9jLMo4m0OUfeUA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "android"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-arm64/-/darwin-arm64-0.28.0.tgz",
+      "integrity": "sha512-0T+A9WZm+bZ84nZBtk1ckYsOvyA3x7e2Acj1KdVfV4/2tdG4fzUp91YHx+GArWLtwqp77pBXVCPn2We7Letr0Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/darwin-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/darwin-x64/-/darwin-x64-0.28.0.tgz",
+      "integrity": "sha512-fyzLm/DLDl/84OCfp2f/XQ4flmORsjU7VKt8HLjvIXChJoFFOIL6pLJPH4Yhd1n1gGFF9mPwtlN5Wf82DZs+LQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "darwin"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-arm64/-/freebsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-l9GeW5UZBT9k9brBYI+0WDffcRxgHQD8ShN2Ur4xWq/NFzUKm3k5lsH4PdaRgb2w7mI9u61nr2gI2mLI27Nh3Q==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/freebsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/freebsd-x64/-/freebsd-x64-0.28.0.tgz",
+      "integrity": "sha512-BXoQai/A0wPO6Es3yFJ7APCiKGc1tdAEOgeTNy3SsB491S3aHn4S4r3e976eUnPdU+NbdtmBuLncYir2tMU9Nw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "freebsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm/-/linux-arm-0.28.0.tgz",
+      "integrity": "sha512-CjaaREJagqJp7iTaNQjjidaNbCKYcd4IDkzbwwxtSvjI7NZm79qiHc8HqciMddQ6CKvJT6aBd8lO9kN/ZudLlw==",
+      "cpu": [
+        "arm"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-arm64/-/linux-arm64-0.28.0.tgz",
+      "integrity": "sha512-RVyzfb3FWsGA55n6WY0MEIEPURL1FcbhFE6BffZEMEekfCzCIMtB5yyDcFnVbTnwk+CLAgTujmV/Lgvih56W+A==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ia32": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ia32/-/linux-ia32-0.28.0.tgz",
+      "integrity": "sha512-KBnSTt1kxl9x70q+ydterVdl+Cn0H18ngRMRCEQfrbqdUuntQQ0LoMZv47uB97NljZFzY6HcfqEZ2SAyIUTQBQ==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-loong64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-loong64/-/linux-loong64-0.28.0.tgz",
+      "integrity": "sha512-zpSlUce1mnxzgBADvxKXX5sl8aYQHo2ezvMNI8I0lbblJtp8V4odlm3Yzlj7gPyt3T8ReksE6bK+pT3WD+aJRg==",
+      "cpu": [
+        "loong64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-mips64el": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-mips64el/-/linux-mips64el-0.28.0.tgz",
+      "integrity": "sha512-2jIfP6mmjkdmeTlsX/9vmdmhBmKADrWqN7zcdtHIeNSCH1SqIoNI63cYsjQR8J+wGa4Y5izRcSHSm8K3QWmk3w==",
+      "cpu": [
+        "mips64el"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-ppc64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-ppc64/-/linux-ppc64-0.28.0.tgz",
+      "integrity": "sha512-bc0FE9wWeC0WBm49IQMPSPILRocGTQt3j5KPCA8os6VprfuJ7KD+5PzESSrJ6GmPIPJK965ZJHTUlSA6GNYEhg==",
+      "cpu": [
+        "ppc64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-riscv64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-riscv64/-/linux-riscv64-0.28.0.tgz",
+      "integrity": "sha512-SQPZOwoTTT/HXFXQJG/vBX8sOFagGqvZyXcgLA3NhIqcBv1BJU1d46c0rGcrij2B56Z2rNiSLaZOYW5cUk7yLQ==",
+      "cpu": [
+        "riscv64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-s390x": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-s390x/-/linux-s390x-0.28.0.tgz",
+      "integrity": "sha512-SCfR0HN8CEEjnYnySJTd2cw0k9OHB/YFzt5zgJEwa+wL/T/raGWYMBqwDNAC6dqFKmJYZoQBRfHjgwLHGSrn3Q==",
+      "cpu": [
+        "s390x"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/linux-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.28.0.tgz",
+      "integrity": "sha512-us0dSb9iFxIi8srnpl931Nvs65it/Jd2a2K3qs7fz2WfGPHqzfzZTfec7oxZJRNPXPnNYZtanmRc4AL/JwVzHQ==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "linux"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-arm64/-/netbsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-CR/RYotgtCKwtftMwJlUU7xCVNg3lMYZ0RzTmAHSfLCXw3NtZtNpswLEj/Kkf6kEL3Gw+BpOekRX0BYCtklhUw==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/netbsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/netbsd-x64/-/netbsd-x64-0.28.0.tgz",
+      "integrity": "sha512-nU1yhmYutL+fQ71Kxnhg8uEOdC0pwEW9entHykTgEbna2pw2dkbFSMeqjjyHZoCmt8SBkOSvV+yNmm94aUrrqw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "netbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-arm64/-/openbsd-arm64-0.28.0.tgz",
+      "integrity": "sha512-cXb5vApOsRsxsEl4mcZ1XY3D4DzcoMxR/nnc4IyqYs0rTI8ZKmW6kyyg+11Z8yvgMfAEldKzP7AdP64HnSC/6g==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openbsd-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openbsd-x64/-/openbsd-x64-0.28.0.tgz",
+      "integrity": "sha512-8wZM2qqtv9UP3mzy7HiGYNH/zjTA355mpeuA+859TyR+e+Tc08IHYpLJuMsfpDJwoLo1ikIJI8jC3GFjnRClzA==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openbsd"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/openharmony-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/openharmony-arm64/-/openharmony-arm64-0.28.0.tgz",
+      "integrity": "sha512-FLGfyizszcef5C3YtoyQDACyg95+dndv79i2EekILBofh5wpCa1KuBqOWKrEHZg3zrL3t5ouE5jgr94vA+Wb2w==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "openharmony"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/sunos-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/sunos-x64/-/sunos-x64-0.28.0.tgz",
+      "integrity": "sha512-1ZgjUoEdHZZl/YlV76TSCz9Hqj9h9YmMGAgAPYd+q4SicWNX3G5GCyx9uhQWSLcbvPW8Ni7lj4gDa1T40akdlw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "sunos"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-arm64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-arm64/-/win32-arm64-0.28.0.tgz",
+      "integrity": "sha512-Q9StnDmQ/enxnpxCCLSg0oo4+34B9TdXpuyPeTedN/6+iXBJ4J+zwfQI28u/Jl40nOYAxGoNi7mFP40RUtkmUA==",
+      "cpu": [
+        "arm64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-ia32": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-ia32/-/win32-ia32-0.28.0.tgz",
+      "integrity": "sha512-zF3ag/gfiCe6U2iczcRzSYJKH1DCI+ByzSENHlM2FcDbEeo5Zd2C86Aq0tKUYAJJ1obRP84ymxIAksZUcdztHA==",
+      "cpu": [
+        "ia32"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@esbuild/win32-x64": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/@esbuild/win32-x64/-/win32-x64-0.28.0.tgz",
+      "integrity": "sha512-pEl1bO9mfAmIC+tW5btTmrKaujg3zGtUmWNdCw/xs70FBjwAL3o9OEKNHvNmnyylD6ubxUERiEhdsL0xBQ9efw==",
+      "cpu": [
+        "x64"
+      ],
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "os": [
+        "win32"
+      ],
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/@zeit/schemas": {
+      "version": "2.36.0",
+      "resolved": "https://registry.npmjs.org/@zeit/schemas/-/schemas-2.36.0.tgz",
+      "integrity": "sha512-7kjMwcChYEzMKjeex9ZFXkt1AyNov9R5HZtjBKVsmVpw7pa7ZtlCGvCBC2vnnXctaYN+aRI61HjIqeetZW5ROg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/ajv": {
+      "version": "8.18.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz",
+      "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/ansi-align": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-align/-/ansi-align-3.0.1.tgz",
+      "integrity": "sha512-IOfwwBF5iczOjp/WeY4YxyjqAFMQoZufdQWDd19SEExbVLNXqvpzSJ/M7Za4/sCPmQ0+GRquoA7bGcINcxew6w==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^4.1.0"
+      }
+    },
+    "node_modules/ansi-align/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/ansi-align/node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/ansi-align/node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/ansi-align/node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/ansi-escapes": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/ansi-escapes/-/ansi-escapes-7.2.0.tgz",
+      "integrity": "sha512-g6LhBsl+GBPRWGWsBtutpzBYuIIdBkLEvad5C/va/74Db018+5TZiyA26cZJAr3Rft5lprVqOIPxf5Vid6tqAw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "environment": "^1.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/ansi-regex": {
+      "version": "6.1.0",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-6.1.0.tgz",
+      "integrity": "sha512-7HSX4QQb4CspciLpVFwyRe79O3xsIZDDLER21kERQ71oaPodF8jL725AgJMFAYbooIqolJoRLuM81SpeUkpkvA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-regex?sponsor=1"
+      }
+    },
+    "node_modules/ansi-styles": {
+      "version": "6.2.1",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.1.tgz",
+      "integrity": "sha512-bN798gFfQX+viw3R7yrGWRqnrN2oRkEkUjjl4JNn4E8GxxbjtG3FbrEIIY3l8/hrwUwIeCZvi4QuOTP4MErVug==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/arch": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/arch/-/arch-2.2.0.tgz",
+      "integrity": "sha512-Of/R0wqp83cgHozfIYLbBMnej79U/SVGOOyuB3VVFv1NRM/PSFMK12x9KVtiYzJqmnU5WR2qp0Z5rHb7sWGnFQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/arg": {
+      "version": "5.0.2",
+      "resolved": "https://registry.npmjs.org/arg/-/arg-5.0.2.tgz",
+      "integrity": "sha512-PYjyFOLKQ9y57JvQ6QLo8dAgNqswh8M1RMJYdQduT6xbWSgK36P/Z/v+p888pM69jMMfS8Xd8F6I1kQ/I9HUGg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/argparse": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz",
+      "integrity": "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q==",
+      "license": "Python-2.0"
+    },
+    "node_modules/balanced-match": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/boxen": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/boxen/-/boxen-7.0.0.tgz",
+      "integrity": "sha512-j//dBVuyacJbvW+tvZ9HuH03fZ46QcaKvvhZickZqtB271DxJ7SNRSNxrV/dZX0085m7hISRZWbzWlJvx/rHSg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-align": "^3.0.1",
+        "camelcase": "^7.0.0",
+        "chalk": "^5.0.1",
+        "cli-boxes": "^3.0.0",
+        "string-width": "^5.1.2",
+        "type-fest": "^2.13.0",
+        "widest-line": "^4.0.1",
+        "wrap-ansi": "^8.0.1"
+      },
+      "engines": {
+        "node": ">=14.16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/brace-expansion": {
+      "version": "1.1.12",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-1.1.12.tgz",
+      "integrity": "sha512-9T9UjW3r0UW5c1Q7GTwllptXwhvYmEzFhzMfZ9H7FQWt+uZePjZPjBP/W1ZEyZ1twGWom5/56TF4lPcqjnDHcg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^1.0.0",
+        "concat-map": "0.0.1"
+      }
+    },
+    "node_modules/bytes": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.0.0.tgz",
+      "integrity": "sha512-pMhOfFDPiv9t5jjIXkHosWmkSyQbvsgEVNkz0ERHbuLh2T/7j4Mqqpz523Fe8MVY89KC6Sh/QfS2sM+SjgFDcw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/camelcase": {
+      "version": "7.0.1",
+      "resolved": "https://registry.npmjs.org/camelcase/-/camelcase-7.0.1.tgz",
+      "integrity": "sha512-xlx1yCK2Oc1APsPXDL2LdlNP6+uu8OCDdhOBSVT279M/S+y75O30C2VuD8T2ogdePBBl7PfPF4504tnLgX3zfw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=14.16"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/chalk": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/chalk/-/chalk-5.0.1.tgz",
+      "integrity": "sha512-Fo07WOYGqMfCWHOzSXOt2CxDbC6skS/jO9ynEcmpANMoPrD+W1r1K6Vx7iNm+AQmETU1Xr2t+n8nzkV9t6xh3w==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^12.17.0 || ^14.13 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/chalk?sponsor=1"
+      }
+    },
+    "node_modules/chalk-template": {
+      "version": "0.4.0",
+      "resolved": "https://registry.npmjs.org/chalk-template/-/chalk-template-0.4.0.tgz",
+      "integrity": "sha512-/ghrgmhfY8RaSdeo43hNXxpoHAtxdbskUHjPpfqUWGttFgycUhYPGx3YZBCnUCvOa7Doivn1IZec3DEGFoMgLg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "chalk": "^4.1.2"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/chalk-template?sponsor=1"
+      }
+    },
+    "node_modules/chalk-template/node_modules/ansi-styles": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
+      "integrity": "sha512-zbB9rCJAT1rbjiVDb2hqKFHNYLxgtk8NURxZ3IZwD3F6NtxbXZQCnnSi1Lkx+IDohdPlFp222wVALIheZJQSEg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "color-convert": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/chalk-template/node_modules/chalk": {
+      "version": "4.1.2",
+      "resolved": "https://registry.npmjs.org/chalk/-/chalk-4.1.2.tgz",
+      "integrity": "sha512-oKnbhFyRIXpUuez8iBMmyEa4nbj4IOQyuhc/wy9kY7/WVPcwIO9VA668Pu8RkO7+0G76SLROeyw9CpQ061i4mA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.1.0",
+        "supports-color": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/chalk?sponsor=1"
+      }
+    },
+    "node_modules/chalk-template/node_modules/has-flag": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz",
+      "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/chalk-template/node_modules/supports-color": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-7.2.0.tgz",
+      "integrity": "sha512-qpCAvRl9stuOHveKsn7HncJRvv501qIacKzQlO/+Lwxc9+0q2wLyv4Dfvt80/DPn2pqOBsJdDiogXGR9+OvwRw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "has-flag": "^4.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/cli-boxes": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/cli-boxes/-/cli-boxes-3.0.0.tgz",
+      "integrity": "sha512-/lzGpEWL/8PfI0BmBOPRwp0c/wFNX1RdUML3jK/RcSBA9T8mZDdQpqYBKtCFTOfQbwPqWEOpjqW+Fnayc0969g==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/cli-cursor": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/cli-cursor/-/cli-cursor-5.0.0.tgz",
+      "integrity": "sha512-aCj4O5wKyszjMmDT4tZj93kxyydN/K5zPWSCe6/0AV/AA1pqe5ZBIw0a2ZfPQV7lL5/yb5HsUreJ6UFAF1tEQw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "restore-cursor": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/cli-truncate": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/cli-truncate/-/cli-truncate-5.1.1.tgz",
+      "integrity": "sha512-SroPvNHxUnk+vIW/dOSfNqdy1sPEFkrTk6TUtqLCnBlo3N7TNYYkzzN7uSD6+jVjrdO4+p8nH7JzH6cIvUem6A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "slice-ansi": "^7.1.0",
+        "string-width": "^8.0.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/cli-truncate/node_modules/string-width": {
+      "version": "8.1.0",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-8.1.0.tgz",
+      "integrity": "sha512-Kxl3KJGb/gxkaUMOjRsQ8IrXiGW75O4E3RPjFIINOVH8AMl2SQ/yWdTzWwF3FevIX9LcMAjJW+GRwAlAbTSXdg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "get-east-asian-width": "^1.3.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/clipboardy": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/clipboardy/-/clipboardy-3.0.0.tgz",
+      "integrity": "sha512-Su+uU5sr1jkUy1sGRpLKjKrvEOVXgSgiSInwa/qeID6aJ07yh+5NWc3h2QfjHjBnfX4LhtFcuAWKUsJ3r+fjbg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "arch": "^2.2.0",
+        "execa": "^5.1.1",
+        "is-wsl": "^2.2.0"
+      },
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/color-convert": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
+      "integrity": "sha512-RRECPsj7iu/xb5oKYcsFHSppFNnsj/52OVTRKb4zP5onXwVF3zVmmToNcOfGC+CRDpfK/U584fMg38ZHCaElKQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "color-name": "~1.1.4"
+      },
+      "engines": {
+        "node": ">=7.0.0"
+      }
+    },
+    "node_modules/color-convert/node_modules/color-name": {
+      "version": "1.1.4",
+      "resolved": "https://registry.npmjs.org/color-name/-/color-name-1.1.4.tgz",
+      "integrity": "sha512-dOy+3AuW3a2wNbZHIuMZpTcgjGuLU/uBL/ubcZF9OXbDo8ff4O8yVp5Bf0efS8uEoYo5q4Fx7dY9OgQGXgAsQA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/colorette": {
+      "version": "2.0.20",
+      "resolved": "https://registry.npmjs.org/colorette/-/colorette-2.0.20.tgz",
+      "integrity": "sha512-IfEDxwoWIjkeXL1eXcDiow4UbKjhLdq6/EuSVR9GMN7KVH3r9gQ83e73hsz1Nd1T3ijd5xv1wcWRYO+D6kCI2w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/commander": {
+      "version": "14.0.3",
+      "resolved": "https://registry.npmjs.org/commander/-/commander-14.0.3.tgz",
+      "integrity": "sha512-H+y0Jo/T1RZ9qPP4Eh1pkcQcLRglraJaSLoyOtHxu6AapkjWVCy2Sit1QQ4x3Dng8qDlSsZEet7g5Pq06MvTgw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      }
+    },
+    "node_modules/compressible": {
+      "version": "2.0.18",
+      "resolved": "https://registry.npmjs.org/compressible/-/compressible-2.0.18.tgz",
+      "integrity": "sha512-AF3r7P5dWxL8MxyITRMlORQNaOA2IkAFaTr4k7BUumjPtRpGDTZpl0Pb1XCO6JeDCBdp126Cgs9sMxqSjgYyRg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "mime-db": ">= 1.43.0 < 2"
+      },
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/compression": {
+      "version": "1.8.1",
+      "resolved": "https://registry.npmjs.org/compression/-/compression-1.8.1.tgz",
+      "integrity": "sha512-9mAqGPHLakhCLeNyxPkK4xVo746zQ/czLH1Ky+vkitMnWfWZps8r0qXuwhwizagCRttsL4lfG4pIOvaWLpAP0w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "bytes": "3.1.2",
+        "compressible": "~2.0.18",
+        "debug": "2.6.9",
+        "negotiator": "~0.6.4",
+        "on-headers": "~1.1.0",
+        "safe-buffer": "5.2.1",
+        "vary": "~1.1.2"
+      },
+      "engines": {
+        "node": ">= 0.8.0"
+      }
+    },
+    "node_modules/compression/node_modules/bytes": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
+      "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/concat-map": {
+      "version": "0.0.1",
+      "resolved": "https://registry.npmjs.org/concat-map/-/concat-map-0.0.1.tgz",
+      "integrity": "sha512-/Srv4dswyQNBfohGpz9o6Yb3Gz3SrUDqBH5rTuhGR7ahtlbYKnVxw2bCFMRljaA7EXHaXZ8wsHdodFvbkhKmqg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/content-disposition": {
+      "version": "0.5.2",
+      "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-0.5.2.tgz",
+      "integrity": "sha512-kRGRZw3bLlFISDBgwTSA1TMBFN6J6GWDeubmDE3AF+3+yXL8hTWv8r5rkLbqYXY4RjPk/EzHnClI3zQf1cFmHA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/cross-spawn": {
+      "version": "7.0.6",
+      "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
+      "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "path-key": "^3.1.0",
+        "shebang-command": "^2.0.0",
+        "which": "^2.0.1"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/debug": {
+      "version": "2.6.9",
+      "resolved": "https://registry.npmjs.org/debug/-/debug-2.6.9.tgz",
+      "integrity": "sha512-bC7ElrdJaJnPbAP+1EotYvqZsb3ecl5wi6Bfi6BJTUcNowp6cvspg0jXznRTKDjm/E7AdgFBVeAPVMNcKGsHMA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ms": "2.0.0"
+      }
+    },
+    "node_modules/deep-extend": {
+      "version": "0.6.0",
+      "resolved": "https://registry.npmjs.org/deep-extend/-/deep-extend-0.6.0.tgz",
+      "integrity": "sha512-LOHxIOaPYdHlJRtCQfDIVZtfw/ufM8+rVj649RIHzcm/vGwQRXFt6OPqIFWsm2XEMrNIEtWR64sY1LEKD2vAOA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/eastasianwidth": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/eastasianwidth/-/eastasianwidth-0.2.0.tgz",
+      "integrity": "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/emoji-regex": {
+      "version": "9.2.2",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz",
+      "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/entities": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-2.2.0.tgz",
+      "integrity": "sha512-p92if5Nz619I0w+akJrLZH0MX0Pb5DX39XOwQTtXSdQQOaYH03S1uIQp4mhOZtAXrxq4ViO67YTiLBo2638o9A==",
+      "license": "BSD-2-Clause",
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/environment": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/environment/-/environment-1.1.0.tgz",
+      "integrity": "sha512-xUtoPkMggbz0MPyPiIWr1Kp4aeWJjDZ6SMvURhimjdZgsRuDplF5/s9hcgGhyXMhs+6vpnuoiZ2kFiu3FMnS8Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/esbuild": {
+      "version": "0.28.0",
+      "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.28.0.tgz",
+      "integrity": "sha512-sNR9MHpXSUV/XB4zmsFKN+QgVG82Cc7+/aaxJ8Adi8hyOac+EXptIp45QBPaVyX3N70664wRbTcLTOemCAnyqw==",
+      "dev": true,
+      "hasInstallScript": true,
+      "license": "MIT",
+      "bin": {
+        "esbuild": "bin/esbuild"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "optionalDependencies": {
+        "@esbuild/aix-ppc64": "0.28.0",
+        "@esbuild/android-arm": "0.28.0",
+        "@esbuild/android-arm64": "0.28.0",
+        "@esbuild/android-x64": "0.28.0",
+        "@esbuild/darwin-arm64": "0.28.0",
+        "@esbuild/darwin-x64": "0.28.0",
+        "@esbuild/freebsd-arm64": "0.28.0",
+        "@esbuild/freebsd-x64": "0.28.0",
+        "@esbuild/linux-arm": "0.28.0",
+        "@esbuild/linux-arm64": "0.28.0",
+        "@esbuild/linux-ia32": "0.28.0",
+        "@esbuild/linux-loong64": "0.28.0",
+        "@esbuild/linux-mips64el": "0.28.0",
+        "@esbuild/linux-ppc64": "0.28.0",
+        "@esbuild/linux-riscv64": "0.28.0",
+        "@esbuild/linux-s390x": "0.28.0",
+        "@esbuild/linux-x64": "0.28.0",
+        "@esbuild/netbsd-arm64": "0.28.0",
+        "@esbuild/netbsd-x64": "0.28.0",
+        "@esbuild/openbsd-arm64": "0.28.0",
+        "@esbuild/openbsd-x64": "0.28.0",
+        "@esbuild/openharmony-arm64": "0.28.0",
+        "@esbuild/sunos-x64": "0.28.0",
+        "@esbuild/win32-arm64": "0.28.0",
+        "@esbuild/win32-ia32": "0.28.0",
+        "@esbuild/win32-x64": "0.28.0"
+      }
+    },
+    "node_modules/eventemitter3": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/eventemitter3/-/eventemitter3-5.0.1.tgz",
+      "integrity": "sha512-GWkBvjiSZK87ELrYOSESUYeVIc9mvLLf/nXalMOS5dYrgZq9o5OVkbZAVM06CVxYsCwH9BDZFPlQTlPA1j4ahA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/execa": {
+      "version": "5.1.1",
+      "resolved": "https://registry.npmjs.org/execa/-/execa-5.1.1.tgz",
+      "integrity": "sha512-8uSpZZocAZRBAPIEINJj3Lo9HyGitllczc27Eh5YYojjMFMn8yHMDMaUHE2Jqfq05D/wucwI4JGURyXt1vchyg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cross-spawn": "^7.0.3",
+        "get-stream": "^6.0.0",
+        "human-signals": "^2.1.0",
+        "is-stream": "^2.0.0",
+        "merge-stream": "^2.0.0",
+        "npm-run-path": "^4.0.1",
+        "onetime": "^5.1.2",
+        "signal-exit": "^3.0.3",
+        "strip-final-newline": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sindresorhus/execa?sponsor=1"
+      }
+    },
+    "node_modules/fast-deep-equal": {
+      "version": "3.1.3",
+      "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz",
+      "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/fast-uri": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
+      "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
+    "node_modules/get-east-asian-width": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.4.0.tgz",
+      "integrity": "sha512-QZjmEOC+IT1uk6Rx0sX22V6uHWVwbdbxf1faPqJ1QhLdGgsRGCZoyaQBm/piRdJy/D2um6hM1UP7ZEeQ4EkP+Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/get-stream": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/get-stream/-/get-stream-6.0.1.tgz",
+      "integrity": "sha512-ts6Wi+2j3jQjqi70w5AlN8DFnkSwC+MqmxEzdEALB2qXZYV3X/b1CTfgPLGJNMeAWxdPfU8FO1ms3NUfaHCPYg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/handlebars": {
+      "version": "4.7.9",
+      "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.9.tgz",
+      "integrity": "sha512-4E71E0rpOaQuJR2A3xDZ+GM1HyWYv1clR58tC8emQNeQe3RH7MAzSbat+V0wG78LQBo6m6bzSG/L4pBuCsgnUQ==",
+      "license": "MIT",
+      "dependencies": {
+        "minimist": "^1.2.5",
+        "neo-async": "^2.6.2",
+        "source-map": "^0.6.1",
+        "wordwrap": "^1.0.0"
+      },
+      "bin": {
+        "handlebars": "bin/handlebars"
+      },
+      "engines": {
+        "node": ">=0.4.7"
+      },
+      "optionalDependencies": {
+        "uglify-js": "^3.1.4"
+      }
+    },
+    "node_modules/human-signals": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/human-signals/-/human-signals-2.1.0.tgz",
+      "integrity": "sha512-B4FFZ6q/T2jhhksgkbEW3HBvWIfDW85snkQgawt07S7J5QXTk6BkNV+0yAeZrM5QpMAdYlocGoljn0sJ/WQkFw==",
+      "dev": true,
+      "license": "Apache-2.0",
+      "engines": {
+        "node": ">=10.17.0"
+      }
+    },
+    "node_modules/husky": {
+      "version": "9.1.7",
+      "resolved": "https://registry.npmjs.org/husky/-/husky-9.1.7.tgz",
+      "integrity": "sha512-5gs5ytaNjBrh5Ow3zrvdUUY+0VxIuWVL4i9irt6friV+BqdCfmV11CQTWMiBYWHbXhco+J1kHfTOUkePhCDvMA==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "husky": "bin.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/typicode"
+      }
+    },
+    "node_modules/ini": {
+      "version": "1.3.8",
+      "resolved": "https://registry.npmjs.org/ini/-/ini-1.3.8.tgz",
+      "integrity": "sha512-JV/yugV2uzW5iMRSiZAyDtQd+nxtUnjeLt0acNdw98kKLrvuRVyB80tsREOE7yvGVgalhZ6RNXCmEHkUKBKxew==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/is-docker": {
+      "version": "2.2.1",
+      "resolved": "https://registry.npmjs.org/is-docker/-/is-docker-2.2.1.tgz",
+      "integrity": "sha512-F+i2BKsFrH66iaUFc0woD8sLy8getkwTwtOBjvs56Cx4CgJDeKQeqfz8wAYiSb8JOprWhHH5p77PbmYCvvUuXQ==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "is-docker": "cli.js"
+      },
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/is-port-reachable": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/is-port-reachable/-/is-port-reachable-4.0.0.tgz",
+      "integrity": "sha512-9UoipoxYmSk6Xy7QFgRv2HDyaysmgSG75TFQs6S+3pDM7ZhKTF/bskZV+0UlABHzKjNVhPjYCLfeZUEg1wXxig==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "^12.20.0 || ^14.13.1 || >=16.0.0"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-stream": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/is-stream/-/is-stream-2.0.1.tgz",
+      "integrity": "sha512-hFoiJiTl63nn+kstHGBtewWSKnQLpyb155KHheA1l39uvtO9nWIop1p3udqPcUd/xbF1VLMO4n7OI6p7RbngDg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/is-wsl": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/is-wsl/-/is-wsl-2.2.0.tgz",
+      "integrity": "sha512-fKzAra0rGJUUBwGBgNkHZuToZcn+TtXHpeCgmkMJMMYx1sQDYaCSyjJBSCa2nH1DGm7s3n1oBnohoVTBaN7Lww==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "is-docker": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/isexe": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz",
+      "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/js-yaml": {
+      "version": "4.1.1",
+      "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
+      "integrity": "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA==",
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1"
+      },
+      "bin": {
+        "js-yaml": "bin/js-yaml.js"
+      }
+    },
+    "node_modules/json-schema-traverse": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/linkify-it": {
+      "version": "5.0.0",
+      "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz",
+      "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==",
+      "license": "MIT",
+      "dependencies": {
+        "uc.micro": "^2.0.0"
+      }
+    },
+    "node_modules/lint-staged": {
+      "version": "16.4.0",
+      "resolved": "https://registry.npmjs.org/lint-staged/-/lint-staged-16.4.0.tgz",
+      "integrity": "sha512-lBWt8hujh/Cjysw5GYVmZpFHXDCgZzhrOm8vbcUdobADZNOK/bRshr2kM3DfgrrtR1DQhfupW9gnIXOfiFi+bw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "commander": "^14.0.3",
+        "listr2": "^9.0.5",
+        "picomatch": "^4.0.3",
+        "string-argv": "^0.3.2",
+        "tinyexec": "^1.0.4",
+        "yaml": "^2.8.2"
+      },
+      "bin": {
+        "lint-staged": "bin/lint-staged.js"
+      },
+      "engines": {
+        "node": ">=20.17"
+      },
+      "funding": {
+        "url": "https://opencollective.com/lint-staged"
+      }
+    },
+    "node_modules/listr2": {
+      "version": "9.0.5",
+      "resolved": "https://registry.npmjs.org/listr2/-/listr2-9.0.5.tgz",
+      "integrity": "sha512-ME4Fb83LgEgwNw96RKNvKV4VTLuXfoKudAmm2lP8Kk87KaMK0/Xrx/aAkMWmT8mDb+3MlFDspfbCs7adjRxA2g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cli-truncate": "^5.0.0",
+        "colorette": "^2.0.20",
+        "eventemitter3": "^5.0.1",
+        "log-update": "^6.1.0",
+        "rfdc": "^1.4.1",
+        "wrap-ansi": "^9.0.0"
+      },
+      "engines": {
+        "node": ">=20.0.0"
+      }
+    },
+    "node_modules/listr2/node_modules/emoji-regex": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-10.6.0.tgz",
+      "integrity": "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/listr2/node_modules/string-width": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz",
+      "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^10.3.0",
+        "get-east-asian-width": "^1.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/listr2/node_modules/wrap-ansi": {
+      "version": "9.0.2",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-9.0.2.tgz",
+      "integrity": "sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.2.1",
+        "string-width": "^7.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/log-update": {
+      "version": "6.1.0",
+      "resolved": "https://registry.npmjs.org/log-update/-/log-update-6.1.0.tgz",
+      "integrity": "sha512-9ie8ItPR6tjY5uYJh8K/Zrv/RMZ5VOlOWvtZdEHYSTFKZfIBPQa9tOAEeAWhd+AnIneLJ22w5fjOYtoutpWq5w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-escapes": "^7.0.0",
+        "cli-cursor": "^5.0.0",
+        "slice-ansi": "^7.1.0",
+        "strip-ansi": "^7.1.0",
+        "wrap-ansi": "^9.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/log-update/node_modules/emoji-regex": {
+      "version": "10.6.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-10.6.0.tgz",
+      "integrity": "sha512-toUI84YS5YmxW219erniWD0CIVOo46xGKColeNQRgOzDorgBi1v4D71/OFzgD9GO2UGKIv1C3Sp8DAn0+j5w7A==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/log-update/node_modules/string-width": {
+      "version": "7.2.0",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz",
+      "integrity": "sha512-tsaTIkKW9b4N+AEj+SVA+WhJzV7/zMhcSu78mLKWSk7cXMOSHsBKFWUs0fWwq8QyK3MgJBQRX6Gbi4kYbdvGkQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^10.3.0",
+        "get-east-asian-width": "^1.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/log-update/node_modules/wrap-ansi": {
+      "version": "9.0.2",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-9.0.2.tgz",
+      "integrity": "sha512-42AtmgqjV+X1VpdOfyTGOYRi0/zsoLqtXQckTmqTeybT+BDIbM/Guxo7x3pE2vtpr1ok6xRqM9OpBe+Jyoqyww==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.2.1",
+        "string-width": "^7.0.0",
+        "strip-ansi": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/markdown-it": {
+      "version": "14.1.1",
+      "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.1.tgz",
+      "integrity": "sha512-BuU2qnTti9YKgK5N+IeMubp14ZUKUUw7yeJbkjtosvHiP0AZ5c8IAgEMk79D0eC8F23r4Ac/q8cAIFdm2FtyoA==",
+      "license": "MIT",
+      "dependencies": {
+        "argparse": "^2.0.1",
+        "entities": "^4.4.0",
+        "linkify-it": "^5.0.0",
+        "mdurl": "^2.0.0",
+        "punycode.js": "^2.3.1",
+        "uc.micro": "^2.1.0"
+      },
+      "bin": {
+        "markdown-it": "bin/markdown-it.mjs"
+      }
+    },
+    "node_modules/markdown-it/node_modules/entities": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
+      "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==",
+      "license": "BSD-2-Clause",
+      "engines": {
+        "node": ">=0.12"
+      },
+      "funding": {
+        "url": "https://github.com/fb55/entities?sponsor=1"
+      }
+    },
+    "node_modules/mdurl": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz",
+      "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==",
+      "license": "MIT"
+    },
+    "node_modules/merge-stream": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz",
+      "integrity": "sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/mime-db": {
+      "version": "1.54.0",
+      "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.54.0.tgz",
+      "integrity": "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/mime-types": {
+      "version": "2.1.18",
+      "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.18.tgz",
+      "integrity": "sha512-lc/aahn+t4/SWV/qcmumYjymLsWfN3ELhpmVuUFjgsORruuZPVSwAQryq+HHGvO/SI2KVX26bx+En+zhM8g8hQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "mime-db": "~1.33.0"
+      },
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/mime-types/node_modules/mime-db": {
+      "version": "1.33.0",
+      "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.33.0.tgz",
+      "integrity": "sha512-BHJ/EKruNIqJf/QahvxwQZXKygOQ256myeN/Ew+THcAa5q+PjyTTMMeNQC4DZw5AwfvelsUrA6B67NKMqXDbzQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/mimic-fn": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/mimic-fn/-/mimic-fn-2.1.0.tgz",
+      "integrity": "sha512-OqbOk5oEQeAZ8WXWydlu9HJjz9WVdEIvamMCcXmuqUYjTknH/sqsWvhQ3vgwKFRR1HpjvNBKQ37nbJgYzGqGcg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/mimic-function": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/mimic-function/-/mimic-function-5.0.1.tgz",
+      "integrity": "sha512-VP79XUPxV2CigYP3jWwAUFSku2aKqBH7uTAapFWCBqutsbmDo96KY5o8uh6U+/YSIn5OxJnXp73beVkpqMIGhA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/minimatch": {
+      "version": "3.1.5",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-3.1.5.tgz",
+      "integrity": "sha512-VgjWUsnnT6n+NUk6eZq77zeFdpW2LWDzP6zFGrCbHXiYNul5Dzqk2HHQ5uFH2DNW5Xbp8+jVzaeNt94ssEEl4w==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "brace-expansion": "^1.1.7"
+      },
+      "engines": {
+        "node": "*"
+      }
+    },
+    "node_modules/minimist": {
+      "version": "1.2.8",
+      "resolved": "https://registry.npmjs.org/minimist/-/minimist-1.2.8.tgz",
+      "integrity": "sha512-2yyAR8qBkN3YuheJanUpWC5U3bb5osDywNB8RzDVlDwDHbocAJveqqj1u8+SVD7jkWT4yvsHCpWqqWqAxb0zCA==",
+      "license": "MIT",
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
+    "node_modules/ms": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/ms/-/ms-2.0.0.tgz",
+      "integrity": "sha512-Tpp60P6IUJDTuOq/5Z8cdskzJujfwqfOTkrwIwj7IRISpnkJnT6SyJ4PCPnGMoFjC9ddhal5KVIYtAt97ix05A==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/negotiator": {
+      "version": "0.6.4",
+      "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-0.6.4.tgz",
+      "integrity": "sha512-myRT3DiWPHqho5PrJaIRyaMv2kgYf0mUVgBNOYMuCH5Ki1yEiQaf/ZJuQ62nvpc44wL5WDbTX7yGJi1Neevw8w==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/neo-async": {
+      "version": "2.6.2",
+      "resolved": "https://registry.npmmirror.com/neo-async/-/neo-async-2.6.2.tgz",
+      "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==",
+      "license": "MIT"
+    },
+    "node_modules/npm-run-path": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/npm-run-path/-/npm-run-path-4.0.1.tgz",
+      "integrity": "sha512-S48WzZW777zhNIrn7gxOlISNAqi9ZC/uQFnRdbeIHhZhCA6UqpkOT8T1G7BvfdgP4Er8gF4sUbaS0i7QvIfCWw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "path-key": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/on-headers": {
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/on-headers/-/on-headers-1.1.0.tgz",
+      "integrity": "sha512-737ZY3yNnXy37FHkQxPzt4UZ2UWPWiCZWLvFZ4fu5cueciegX0zGPnrlY6bwRg4FdQOe9YU8MkmJwGhoMybl8A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/onetime": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/onetime/-/onetime-5.1.2.tgz",
+      "integrity": "sha512-kbpaSSGJTWdAY5KPVeMOKXSrPtr8C8C7wodJbcsd51jRnmD+GZu8Y0VoU6Dm5Z4vWr0Ig/1NKuWRKf7j5aaYSg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "mimic-fn": "^2.1.0"
+      },
+      "engines": {
+        "node": ">=6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/path-is-inside": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/path-is-inside/-/path-is-inside-1.0.2.tgz",
+      "integrity": "sha512-DUWJr3+ULp4zXmol/SZkFf3JGsS9/SIv+Y3Rt93/UjPpDpklB5f1er4O3POIbUuUJ3FXgqte2Q7SrU6zAqwk8w==",
+      "dev": true,
+      "license": "(WTFPL OR MIT)"
+    },
+    "node_modules/path-key": {
+      "version": "3.1.1",
+      "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz",
+      "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/path-to-regexp": {
+      "version": "3.3.0",
+      "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-3.3.0.tgz",
+      "integrity": "sha512-qyCH421YQPS2WFDxDjftfc1ZR5WKQzVzqsp4n9M2kQhVOo/ByahFoUNJfl58kOcEGfQ//7weFTDhm+ss8Ecxgw==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/picomatch": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.4.tgz",
+      "integrity": "sha512-QP88BAKvMam/3NxH6vj2o21R6MjxZUAd6nlwAS/pnGvN9IVLocLHxGYIzFhg6fUQ+5th6P4dv4eW9jX3DSIj7A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/jonschlinkert"
+      }
+    },
+    "node_modules/prettier": {
+      "version": "3.8.3",
+      "resolved": "https://registry.npmjs.org/prettier/-/prettier-3.8.3.tgz",
+      "integrity": "sha512-7igPTM53cGHMW8xWuVTydi2KO233VFiTNyF5hLJqpilHfmn8C8gPf+PS7dUT64YcXFbiMGZxS9pCSxL/Dxm/Jw==",
+      "dev": true,
+      "license": "MIT",
+      "bin": {
+        "prettier": "bin/prettier.cjs"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/prettier/prettier?sponsor=1"
+      }
+    },
+    "node_modules/punycode.js": {
+      "version": "2.3.1",
+      "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz",
+      "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/range-parser": {
+      "version": "1.2.0",
+      "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.0.tgz",
+      "integrity": "sha512-kA5WQoNVo4t9lNx2kQNFCxKeBl5IbbSNBl1M/tLkw9WCn+hxNBAW5Qh8gdhs63CJnhjJ2zQWFoqPJP2sK1AV5A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.6"
+      }
+    },
+    "node_modules/rc": {
+      "version": "1.2.8",
+      "resolved": "https://registry.npmjs.org/rc/-/rc-1.2.8.tgz",
+      "integrity": "sha512-y3bGgqKj3QBdxLbLkomlohkvsA8gdAiUQlSBJnBhfn+BPxg4bc62d8TcBW15wavDfgexCgccckhcZvywyQYPOw==",
+      "dev": true,
+      "license": "(BSD-2-Clause OR MIT OR Apache-2.0)",
+      "dependencies": {
+        "deep-extend": "^0.6.0",
+        "ini": "~1.3.0",
+        "minimist": "^1.2.0",
+        "strip-json-comments": "~2.0.1"
+      },
+      "bin": {
+        "rc": "cli.js"
+      }
+    },
+    "node_modules/registry-auth-token": {
+      "version": "3.3.2",
+      "resolved": "https://registry.npmjs.org/registry-auth-token/-/registry-auth-token-3.3.2.tgz",
+      "integrity": "sha512-JL39c60XlzCVgNrO+qq68FoNb56w/m7JYvGR2jT5iR1xBrUA3Mfx5Twk5rqTThPmQKMWydGmq8oFtDlxfrmxnQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "rc": "^1.1.6",
+        "safe-buffer": "^5.0.1"
+      }
+    },
+    "node_modules/registry-url": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/registry-url/-/registry-url-3.1.0.tgz",
+      "integrity": "sha512-ZbgR5aZEdf4UKZVBPYIgaglBmSF2Hi94s2PcIHhRGFjKYu+chjJdYfHn4rt3hB6eCKLJ8giVIIfgMa1ehDfZKA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "rc": "^1.0.1"
+      },
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/restore-cursor": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/restore-cursor/-/restore-cursor-5.1.0.tgz",
+      "integrity": "sha512-oMA2dcrw6u0YfxJQXm342bFKX/E4sG9rbTzO9ptUcR/e8A33cHuvStiYOwH7fszkZlZ1z/ta9AAoPk2F4qIOHA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "onetime": "^7.0.0",
+        "signal-exit": "^4.1.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/restore-cursor/node_modules/onetime": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/onetime/-/onetime-7.0.0.tgz",
+      "integrity": "sha512-VXJjc87FScF88uafS3JllDgvAm+c/Slfz06lorj2uAY34rlUu0Nt+v8wreiImcrgAjjIHp1rXpTDlLOGw29WwQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "mimic-function": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/restore-cursor/node_modules/signal-exit": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
+      "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/rfdc": {
+      "version": "1.4.1",
+      "resolved": "https://registry.npmjs.org/rfdc/-/rfdc-1.4.1.tgz",
+      "integrity": "sha512-q1b3N5QkRUWUl7iyylaaj3kOpIT0N2i9MqIEQXP73GVsN9cw3fdx8X63cEmWhJGi2PPCF23Ijp7ktmd39rawIA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/rss-parser": {
+      "version": "3.13.0",
+      "resolved": "https://registry.npmjs.org/rss-parser/-/rss-parser-3.13.0.tgz",
+      "integrity": "sha512-7jWUBV5yGN3rqMMj7CZufl/291QAhvrrGpDNE4k/02ZchL0npisiYYqULF71jCEKoIiHvK/Q2e6IkDwPziT7+w==",
+      "license": "MIT",
+      "dependencies": {
+        "entities": "^2.0.3",
+        "xml2js": "^0.5.0"
+      }
+    },
+    "node_modules/safe-buffer": {
+      "version": "5.2.1",
+      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.2.1.tgz",
+      "integrity": "sha512-rp3So07KcdmmKbGvgaNxQSJr7bGVSVk5S9Eq1F+ppbRo70+YeaDxkw5Dd8NPN+GD6bjnYm2VuPuCXmpuYvmCXQ==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/feross"
+        },
+        {
+          "type": "patreon",
+          "url": "https://www.patreon.com/feross"
+        },
+        {
+          "type": "consulting",
+          "url": "https://feross.org/support"
+        }
+      ],
+      "license": "MIT"
+    },
+    "node_modules/sax": {
+      "version": "1.4.3",
+      "resolved": "https://registry.npmjs.org/sax/-/sax-1.4.3.tgz",
+      "integrity": "sha512-yqYn1JhPczigF94DMS+shiDMjDowYO6y9+wB/4WgO0Y19jWYk0lQ4tuG5KI7kj4FTp1wxPj5IFfcrz/s1c3jjQ==",
+      "license": "BlueOak-1.0.0"
+    },
+    "node_modules/serve": {
+      "version": "14.2.6",
+      "resolved": "https://registry.npmjs.org/serve/-/serve-14.2.6.tgz",
+      "integrity": "sha512-QEjUSA+sD4Rotm1znR8s50YqA3kYpRGPmtd5GlFxbaL9n/FdUNbqMhxClqdditSk0LlZyA/dhud6XNRTOC9x2Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@zeit/schemas": "2.36.0",
+        "ajv": "8.18.0",
+        "arg": "5.0.2",
+        "boxen": "7.0.0",
+        "chalk": "5.0.1",
+        "chalk-template": "0.4.0",
+        "clipboardy": "3.0.0",
+        "compression": "1.8.1",
+        "is-port-reachable": "4.0.0",
+        "serve-handler": "6.1.7",
+        "update-check": "1.5.4"
+      },
+      "bin": {
+        "serve": "build/main.js"
+      },
+      "engines": {
+        "node": ">= 14"
+      }
+    },
+    "node_modules/serve-handler": {
+      "version": "6.1.7",
+      "resolved": "https://registry.npmjs.org/serve-handler/-/serve-handler-6.1.7.tgz",
+      "integrity": "sha512-CinAq1xWb0vR3twAv9evEU8cNWkXCb9kd5ePAHUKJBkOsUpR1wt/CvGdeca7vqumL1U5cSaeVQ6zZMxiJ3yWsg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "bytes": "3.0.0",
+        "content-disposition": "0.5.2",
+        "mime-types": "2.1.18",
+        "minimatch": "3.1.5",
+        "path-is-inside": "1.0.2",
+        "path-to-regexp": "3.3.0",
+        "range-parser": "1.2.0"
+      }
+    },
+    "node_modules/shebang-command": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
+      "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "shebang-regex": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/shebang-regex": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz",
+      "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/signal-exit": {
+      "version": "3.0.7",
+      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-3.0.7.tgz",
+      "integrity": "sha512-wnD2ZE+l+SPC/uoS0vXeE9L1+0wuaMqKlfz9AMUo38JsyLSBWSFcHR1Rri62LZc12vLr1gb3jl7iwQhgwpAbGQ==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/slice-ansi": {
+      "version": "7.1.2",
+      "resolved": "https://registry.npmjs.org/slice-ansi/-/slice-ansi-7.1.2.tgz",
+      "integrity": "sha512-iOBWFgUX7caIZiuutICxVgX1SdxwAVFFKwt1EvMYYec/NWO5meOJ6K5uQxhrYBdQJne4KxiqZc+KptFOWFSI9w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.2.1",
+        "is-fullwidth-code-point": "^5.0.0"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/slice-ansi?sponsor=1"
+      }
+    },
+    "node_modules/slice-ansi/node_modules/is-fullwidth-code-point": {
+      "version": "5.1.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-5.1.0.tgz",
+      "integrity": "sha512-5XHYaSyiqADb4RnZ1Bdad6cPp8Toise4TzEjcOYDHZkTCbKgiUl7WTUCpNWHuxmDt91wnsZBc9xinNzopv3JMQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "get-east-asian-width": "^1.3.1"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/source-map": {
+      "version": "0.6.1",
+      "resolved": "https://registry.npmmirror.com/source-map/-/source-map-0.6.1.tgz",
+      "integrity": "sha512-UjgapumWlbMhkBgzT7Ykc5YXUT46F0iKu8SGXq0bcwP5dz/h0Plj6enJqjz1Zbq2l5WaqYnrVbwWOWMyF3F47g==",
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/string-argv": {
+      "version": "0.3.2",
+      "resolved": "https://registry.npmjs.org/string-argv/-/string-argv-0.3.2.tgz",
+      "integrity": "sha512-aqD2Q0144Z+/RqG52NeHEkZauTAUWJO8c6yTftGJKO3Tja5tUgIfmIl6kExvhtxSDP7fXB6DvzkfMpCd/F3G+Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.6.19"
+      }
+    },
+    "node_modules/string-width": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz",
+      "integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "eastasianwidth": "^0.2.0",
+        "emoji-regex": "^9.2.2",
+        "strip-ansi": "^7.0.1"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/strip-ansi": {
+      "version": "7.1.0",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.1.0.tgz",
+      "integrity": "sha512-iq6eVVI64nQQTRYq2KtEg2d2uU7LElhTJwsH4YzIHZshxlgZms/wIc4VoDQTlG/IvVIrBKG06CrZnp0qv7hkcQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/strip-ansi?sponsor=1"
+      }
+    },
+    "node_modules/strip-final-newline": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/strip-final-newline/-/strip-final-newline-2.0.0.tgz",
+      "integrity": "sha512-BrpvfNAE3dcvq7ll3xVumzjKjZQ5tI1sEUIKr3Uoks0XUl45St3FlatVqef9prk4jRDzhW6WZg+3bk93y6pLjA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
+    "node_modules/strip-json-comments": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-2.0.1.tgz",
+      "integrity": "sha512-4gB8na07fecVVkOI6Rs4e7T6NOTki5EmL7TUduTs6bu3EdnSycntVJ4re8kgZA+wx9IueI2Y11bfbgwtzuE0KQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/tinyexec": {
+      "version": "1.0.4",
+      "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.0.4.tgz",
+      "integrity": "sha512-u9r3uZC0bdpGOXtlxUIdwf9pkmvhqJdrVCH9fapQtgy/OeTTMZ1nqH7agtvEfmGui6e1XxjcdrlxvxJvc3sMqw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/type-fest": {
+      "version": "2.19.0",
+      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-2.19.0.tgz",
+      "integrity": "sha512-RAH822pAdBgcNMAfWnCBU3CFZcfZ/i1eZjwFU/dsLKumyuuP3niueg2UAukXYF0E2AAoc82ZSSf9J0WQBinzHA==",
+      "dev": true,
+      "license": "(MIT OR CC0-1.0)",
+      "engines": {
+        "node": ">=12.20"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/uc.micro": {
+      "version": "2.1.0",
+      "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz",
+      "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==",
+      "license": "MIT"
+    },
+    "node_modules/uglify-js": {
+      "version": "3.19.3",
+      "resolved": "https://registry.npmmirror.com/uglify-js/-/uglify-js-3.19.3.tgz",
+      "integrity": "sha512-v3Xu+yuwBXisp6QYTcH4UbH+xYJXqnq2m/LtQVWKWzYc1iehYnLixoQDN9FH6/j9/oybfd6W9Ghwkl8+UMKTKQ==",
+      "license": "BSD-2-Clause",
+      "optional": true,
+      "bin": {
+        "uglifyjs": "bin/uglifyjs"
+      },
+      "engines": {
+        "node": ">=0.8.0"
+      }
+    },
+    "node_modules/update-check": {
+      "version": "1.5.4",
+      "resolved": "https://registry.npmjs.org/update-check/-/update-check-1.5.4.tgz",
+      "integrity": "sha512-5YHsflzHP4t1G+8WGPlvKbJEbAJGCgw+Em+dGR1KmBUbr1J36SJBqlHLjR7oob7sco5hWHGQVcr9B2poIVDDTQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "registry-auth-token": "3.3.2",
+        "registry-url": "3.1.0"
+      }
+    },
+    "node_modules/vary": {
+      "version": "1.1.2",
+      "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz",
+      "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">= 0.8"
+      }
+    },
+    "node_modules/which": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
+      "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "isexe": "^2.0.0"
+      },
+      "bin": {
+        "node-which": "bin/node-which"
+      },
+      "engines": {
+        "node": ">= 8"
+      }
+    },
+    "node_modules/widest-line": {
+      "version": "4.0.1",
+      "resolved": "https://registry.npmjs.org/widest-line/-/widest-line-4.0.1.tgz",
+      "integrity": "sha512-o0cyEG0e8GPzT4iGHphIOh0cJOV8fivsXxddQasHPHfoZf1ZexrfeA21w2NaEN1RHE+fXlfISmOE8R9N3u3Qig==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "string-width": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/wordwrap": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmmirror.com/wordwrap/-/wordwrap-1.0.0.tgz",
+      "integrity": "sha512-gvVzJFlPycKc5dZN4yPkP8w7Dc37BtP1yczEneOb4uq34pXZcvrtRTmWV8W+Ume+XCxKgbjM+nevkyFPMybd4Q==",
+      "license": "MIT"
+    },
+    "node_modules/wrap-ansi": {
+      "version": "8.1.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-8.1.0.tgz",
+      "integrity": "sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.1.0",
+        "string-width": "^5.0.1",
+        "strip-ansi": "^7.0.1"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/xml2js": {
+      "version": "0.5.0",
+      "resolved": "https://registry.npmjs.org/xml2js/-/xml2js-0.5.0.tgz",
+      "integrity": "sha512-drPFnkQJik/O+uPKpqSgr22mpuFHqKdbS835iAQrUC73L2F5WkboIRd63ai/2Yg6I1jzifPFKH2NTK+cfglkIA==",
+      "license": "MIT",
+      "dependencies": {
+        "sax": ">=0.6.0",
+        "xmlbuilder": "~11.0.0"
+      },
+      "engines": {
+        "node": ">=4.0.0"
+      }
+    },
+    "node_modules/xmlbuilder": {
+      "version": "11.0.1",
+      "resolved": "https://registry.npmjs.org/xmlbuilder/-/xmlbuilder-11.0.1.tgz",
+      "integrity": "sha512-fDlsI/kFEx7gLvbecc0/ohLG50fugQp8ryHzMTuW9vSa1GJ0XYWKnhsUx7oie3G98+r56aTQIUB4kht42R3JvA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=4.0"
+      }
+    },
+    "node_modules/yaml": {
+      "version": "2.8.2",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.2.tgz",
+      "integrity": "sha512-mplynKqc1C2hTVYxd0PU2xQAc22TI1vShAYGksCCfxbn/dFwnHTNi1bvYsBTkhdUNtGIf5xNOg938rrSSYvS9A==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/eemeli"
+      }
+    }
+  }
+}
diff --git a/scripts/build-runtime.js b/scripts/build-runtime.js
new file mode 100644
index 0000000000000000000000000000000000000000..30b1a89a559a6cb49c2526f57c5b389136054c2b
--- /dev/null
+++ b/scripts/build-runtime.js
@@ -0,0 +1,72 @@
+const path = require('node:path');
+const fs = require('node:fs');
+
+const { createLogger, isVerbose, startTimer } = require('../src/generator/utils/logger');
+
+const log = createLogger('bundle');
+
+function ensureDir(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    fs.mkdirSync(dirPath, { recursive: true });
+  }
+}
+
+async function main() {
+  let esbuild;
+  try {
+    esbuild = require('esbuild');
+  } catch (error) {
+    log.error('未找到 esbuild，请先执行 npm install。');
+    process.exitCode = 1;
+    return;
+  }
+
+  const projectRoot = path.resolve(__dirname, '..');
+  const entry = path.join(projectRoot, 'src', 'runtime', 'index.js');
+  const outFile = path.join(projectRoot, 'dist', 'script.js');
+
+  if (!fs.existsSync(entry)) {
+    log.error('运行时入口不存在', { path: path.relative(projectRoot, entry) });
+    process.exitCode = 1;
+    return;
+  }
+
+  ensureDir(path.dirname(outFile));
+
+  try {
+    const elapsedMs = startTimer();
+    const result = await esbuild.build({
+      entryPoints: [entry],
+      outfile: outFile,
+      bundle: true,
+      platform: 'browser',
+      format: 'iife',
+      target: ['es2018'],
+      sourcemap: false,
+      minify: true,
+      legalComments: 'none',
+      metafile: true,
+      logLevel: 'silent',
+    });
+
+    const ms = elapsedMs();
+    const outputs =
+      result && result.metafile && result.metafile.outputs ? result.metafile.outputs : null;
+    const outKey = outputs ? Object.keys(outputs).find((k) => k.endsWith('dist/script.js')) : '';
+    const bytes = outKey && outputs && outputs[outKey] ? outputs[outKey].bytes : 0;
+
+    const meta = { ms };
+    if (bytes) meta.bytes = bytes;
+    log.ok('输出 dist/script.js', meta);
+  } catch (error) {
+    log.error('构建 dist/script.js 失败', {
+      message: error && error.message ? error.message : String(error),
+    });
+    if (isVerbose() && error && error.stack) {
+      console.error(error.stack);
+    }
+    process.exitCode = 1;
+  }
+}
+
+main();
diff --git a/scripts/build.js b/scripts/build.js
new file mode 100644
index 0000000000000000000000000000000000000000..9e69e238bd6b658e2765a70175256236642166fa
--- /dev/null
+++ b/scripts/build.js
@@ -0,0 +1,55 @@
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { createLogger, isVerbose, startTimer } = require('../src/generator/utils/logger');
+
+const log = createLogger('build');
+
+function runNode(scriptPath) {
+  const result = spawnSync(process.execPath, [scriptPath], { stdio: 'inherit' });
+  return result && Number.isFinite(result.status) ? result.status : 1;
+}
+
+async function main() {
+  const elapsedMs = startTimer();
+  log.info('开始', { version: process.env.npm_package_version });
+
+  const repoRoot = path.resolve(__dirname, '..');
+
+  const cleanExit = runNode(path.join(repoRoot, 'scripts', 'clean.js'));
+  if (cleanExit !== 0) {
+    log.error('clean 失败', { exit: cleanExit });
+    process.exitCode = cleanExit;
+    return;
+  }
+
+  // best-effort：同步失败不阻断 build
+  const syncProjectsExit = runNode(path.join(repoRoot, 'scripts', 'sync-projects.js'));
+  if (syncProjectsExit !== 0)
+    log.warn('sync-projects 异常退出，已继续（best-effort）', { exit: syncProjectsExit });
+
+  const syncHeatmapExit = runNode(path.join(repoRoot, 'scripts', 'sync-heatmap.js'));
+  if (syncHeatmapExit !== 0)
+    log.warn('sync-heatmap 异常退出，已继续（best-effort）', { exit: syncHeatmapExit });
+
+  const syncArticlesExit = runNode(path.join(repoRoot, 'scripts', 'sync-articles.js'));
+  if (syncArticlesExit !== 0)
+    log.warn('sync-articles 异常退出，已继续（best-effort）', { exit: syncArticlesExit });
+
+  const generatorExit = runNode(path.join(repoRoot, 'src', 'generator.js'));
+  if (generatorExit !== 0) {
+    log.error('generate 失败', { exit: generatorExit });
+    process.exitCode = generatorExit;
+    return;
+  }
+
+  log.ok('完成', { ms: elapsedMs(), dist: 'dist/' });
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    log.error('构建失败', { message: error && error.message ? error.message : String(error) });
+    if (isVerbose() && error && error.stack) console.error(error.stack);
+    process.exitCode = 1;
+  });
+}
diff --git a/scripts/check.js b/scripts/check.js
new file mode 100644
index 0000000000000000000000000000000000000000..6d1eb0cb5ae7a721b6b7b93b010bef8365734481
--- /dev/null
+++ b/scripts/check.js
@@ -0,0 +1,49 @@
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { createLogger, isVerbose, startTimer } = require('../src/generator/utils/logger');
+
+const log = createLogger('check');
+
+function runNode(scriptPath) {
+  const result = spawnSync(process.execPath, [scriptPath], { stdio: 'inherit' });
+  return result && Number.isFinite(result.status) ? result.status : 1;
+}
+
+async function main() {
+  const elapsedMs = startTimer();
+  log.info('开始', { version: process.env.npm_package_version });
+
+  const repoRoot = path.resolve(__dirname, '..');
+
+  const lintExit = runNode(path.join(repoRoot, 'scripts', 'lint.js'));
+  if (lintExit !== 0) {
+    log.error('lint 失败', { exit: lintExit });
+    process.exitCode = lintExit;
+    return;
+  }
+
+  const testExit = runNode(path.join(repoRoot, 'scripts', 'test.js'));
+  if (testExit !== 0) {
+    log.error('test 失败', { exit: testExit });
+    process.exitCode = testExit;
+    return;
+  }
+
+  const buildExit = runNode(path.join(repoRoot, 'scripts', 'build.js'));
+  if (buildExit !== 0) {
+    log.error('build 失败', { exit: buildExit });
+    process.exitCode = buildExit;
+    return;
+  }
+
+  log.ok('完成', { ms: elapsedMs() });
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    log.error('执行失败', { message: error && error.message ? error.message : String(error) });
+    if (isVerbose() && error && error.stack) console.error(error.stack);
+    process.exitCode = 1;
+  });
+}
diff --git a/scripts/clean.js b/scripts/clean.js
new file mode 100644
index 0000000000000000000000000000000000000000..86d466fff944739921515c715ae35c95dafc4e26
--- /dev/null
+++ b/scripts/clean.js
@@ -0,0 +1,19 @@
+const fs = require('fs');
+const path = require('path');
+
+const { createLogger } = require('../src/generator/utils/logger');
+
+const log = createLogger('clean');
+
+const distPath = path.resolve(__dirname, '..', 'dist');
+
+try {
+  fs.rmSync(distPath, { recursive: true, force: true });
+  log.ok('删除 dist 目录', { path: distPath });
+} catch (error) {
+  log.error('删除 dist 目录失败', {
+    path: distPath,
+    message: error && error.message ? error.message : String(error),
+  });
+  process.exitCode = 1;
+}
diff --git a/scripts/dev-offline.js b/scripts/dev-offline.js
new file mode 100644
index 0000000000000000000000000000000000000000..205a3437f84200af00b22055cc7f358336ff9c95
--- /dev/null
+++ b/scripts/dev-offline.js
@@ -0,0 +1,89 @@
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { createLogger, isVerbose, startTimer } = require('../src/generator/utils/logger');
+const { startServer } = require('./serve-dist');
+
+const log = createLogger('dev:offline');
+let serverRef = null;
+let shuttingDown = false;
+
+function runNode(scriptPath) {
+  const result = spawnSync(process.execPath, [scriptPath], { stdio: 'inherit' });
+  return result && Number.isFinite(result.status) ? result.status : 1;
+}
+
+function closeServer(server, exitCode) {
+  if (!server) {
+    process.exit(exitCode);
+    return;
+  }
+
+  try {
+    if (typeof server.closeIdleConnections === 'function') server.closeIdleConnections();
+    if (typeof server.closeAllConnections === 'function') server.closeAllConnections();
+  } catch {
+    // ignore
+  }
+
+  const forceTimer = setTimeout(() => process.exit(exitCode), 2000);
+  if (typeof forceTimer.unref === 'function') forceTimer.unref();
+
+  server.close(() => {
+    clearTimeout(forceTimer);
+    process.exit(exitCode);
+  });
+}
+
+async function main() {
+  const elapsedMs = startTimer();
+  log.info('开始', { version: process.env.npm_package_version });
+
+  const repoRoot = path.resolve(__dirname, '..');
+  const generatorPath = path.join(repoRoot, 'src', 'generator.js');
+
+  const exitCode = runNode(generatorPath);
+  if (exitCode !== 0) {
+    log.error('生成失败', { exit: exitCode });
+    process.exitCode = exitCode;
+    return;
+  }
+
+  const portRaw = process.env.PORT || process.env.MENAV_PORT || '5173';
+  const port = Number.parseInt(portRaw, 10) || 5173;
+  const { server, port: actualPort } = await startServer({
+    rootDir: path.join(repoRoot, 'dist'),
+    host: process.env.HOST || '0.0.0.0',
+    port,
+  });
+  serverRef = server;
+
+  log.ok('就绪', { ms: elapsedMs(), url: `http://localhost:${actualPort}` });
+
+  const shutdown = (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    // 让 Ctrl-C 的 ^C 与日志分行显示
+    process.stdout.write('\n');
+
+    log.info('正在关闭...', { signal });
+
+    // 再次 SIGINT：直接强制退出
+    process.once('SIGINT', () => process.exit(130));
+
+    const exit = signal === 'SIGINT' ? 130 : 0;
+    closeServer(serverRef, exit);
+  };
+
+  process.once('SIGINT', () => shutdown('SIGINT'));
+  process.once('SIGTERM', () => shutdown('SIGTERM'));
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    log.error('启动失败', { message: error && error.message ? error.message : String(error) });
+    if (isVerbose() && error && error.stack) console.error(error.stack);
+    process.exitCode = 1;
+  });
+}
diff --git a/scripts/dev.js b/scripts/dev.js
new file mode 100644
index 0000000000000000000000000000000000000000..13b53fe88c17c45f8c5d9a7193e817073c08daf7
--- /dev/null
+++ b/scripts/dev.js
@@ -0,0 +1,98 @@
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { createLogger, isVerbose, startTimer } = require('../src/generator/utils/logger');
+const { startServer } = require('./serve-dist');
+
+const log = createLogger('dev');
+let serverRef = null;
+let shuttingDown = false;
+
+function runNode(scriptPath) {
+  const result = spawnSync(process.execPath, [scriptPath], { stdio: 'inherit' });
+  return result && Number.isFinite(result.status) ? result.status : 1;
+}
+
+function closeServer(server, exitCode) {
+  if (!server) {
+    process.exit(exitCode);
+    return;
+  }
+
+  try {
+    if (typeof server.closeIdleConnections === 'function') server.closeIdleConnections();
+    if (typeof server.closeAllConnections === 'function') server.closeAllConnections();
+  } catch {
+    // ignore
+  }
+
+  const forceTimer = setTimeout(() => process.exit(exitCode), 2000);
+  if (typeof forceTimer.unref === 'function') forceTimer.unref();
+
+  server.close(() => {
+    clearTimeout(forceTimer);
+    process.exit(exitCode);
+  });
+}
+
+async function main() {
+  const elapsedMs = startTimer();
+  log.info('开始', { version: process.env.npm_package_version });
+
+  const repoRoot = path.resolve(__dirname, '..');
+
+  // best-effort：同步失败不阻断 dev
+  const syncProjectsExit = runNode(path.join(repoRoot, 'scripts', 'sync-projects.js'));
+  if (syncProjectsExit !== 0)
+    log.warn('sync-projects 异常退出，已继续（best-effort）', { exit: syncProjectsExit });
+
+  const syncHeatmapExit = runNode(path.join(repoRoot, 'scripts', 'sync-heatmap.js'));
+  if (syncHeatmapExit !== 0)
+    log.warn('sync-heatmap 异常退出，已继续（best-effort）', { exit: syncHeatmapExit });
+
+  const syncArticlesExit = runNode(path.join(repoRoot, 'scripts', 'sync-articles.js'));
+  if (syncArticlesExit !== 0)
+    log.warn('sync-articles 异常退出，已继续（best-effort）', { exit: syncArticlesExit });
+
+  const generatorExit = runNode(path.join(repoRoot, 'src', 'generator.js'));
+  if (generatorExit !== 0) {
+    log.error('生成失败', { exit: generatorExit });
+    process.exitCode = generatorExit;
+    return;
+  }
+
+  const portRaw = process.env.PORT || process.env.MENAV_PORT || '5173';
+  const port = Number.parseInt(portRaw, 10) || 5173;
+  const { server, port: actualPort } = await startServer({
+    rootDir: path.join(repoRoot, 'dist'),
+    host: process.env.HOST || '0.0.0.0',
+    port,
+  });
+  serverRef = server;
+
+  log.ok('就绪', { ms: elapsedMs(), url: `http://localhost:${actualPort}` });
+
+  const shutdown = (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    process.stdout.write('\n');
+    log.info('正在关闭...', { signal });
+
+    process.once('SIGINT', () => process.exit(130));
+
+    const exit = signal === 'SIGINT' ? 130 : 0;
+    closeServer(serverRef, exit);
+  };
+
+  process.once('SIGINT', () => shutdown('SIGINT'));
+  process.once('SIGTERM', () => shutdown('SIGTERM'));
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    log.error('启动失败', { message: error && error.message ? error.message : String(error) });
+    if (isVerbose() && error && error.stack) console.error(error.stack);
+    process.exitCode = 1;
+  });
+}
diff --git a/scripts/format-check-changed.js b/scripts/format-check-changed.js
new file mode 100644
index 0000000000000000000000000000000000000000..6818b2f86d17c0d362e9ec7f52b4daa06d4277ea
--- /dev/null
+++ b/scripts/format-check-changed.js
@@ -0,0 +1,221 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { createLogger, isVerbose, startTimer } = require('../src/generator/utils/logger');
+
+const log = createLogger('format:check:changed');
+
+function runGit(args, cwd, options = {}) {
+  const { allowFailure = false, stdio } = options;
+  try {
+    return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: stdio || 'pipe' }).trim();
+  } catch (error) {
+    if (allowFailure) return null;
+    throw error;
+  }
+}
+
+function tryReadGithubEvent(eventPath) {
+  if (!eventPath) return null;
+  try {
+    const raw = fs.readFileSync(eventPath, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+function isAllZerosSha(value) {
+  return typeof value === 'string' && /^0{40}$/.test(value);
+}
+
+function getDiffRangeFromGithubEvent(event) {
+  if (!event || typeof event !== 'object') return null;
+
+  if (event.pull_request && event.pull_request.base && event.pull_request.head) {
+    const base = event.pull_request.base.sha;
+    const head = event.pull_request.head.sha;
+    if (base && head) return { base, head };
+  }
+
+  if (event.before && (event.after || event.head_commit)) {
+    const base = event.before;
+    const head = event.after || (event.head_commit && event.head_commit.id);
+    if (base && head && !isAllZerosSha(base)) return { base, head };
+  }
+
+  return null;
+}
+
+function gitObjectExists(repoRoot, sha) {
+  if (!sha) return false;
+  const result = runGit(['cat-file', '-e', `${sha}^{commit}`], repoRoot, { allowFailure: true });
+  return result !== null;
+}
+
+function isShallowRepository(repoRoot) {
+  const result = runGit(['rev-parse', '--is-shallow-repository'], repoRoot, { allowFailure: true });
+  return result === 'true';
+}
+
+function tryFetchMoreHistory(repoRoot) {
+  // 仅在 CI 场景兜底：actions/checkout 若是浅克隆，可能缺少 base commit，导致 diff range 失败
+  try {
+    if (isShallowRepository(repoRoot)) {
+      execFileSync('git', ['fetch', '--prune', '--no-tags', '--unshallow'], {
+        cwd: repoRoot,
+        stdio: 'inherit',
+      });
+      return true;
+    }
+  } catch {
+    // ignore
+  }
+
+  try {
+    execFileSync('git', ['fetch', '--prune', '--no-tags', '--depth=200', 'origin'], {
+      cwd: repoRoot,
+      stdio: 'inherit',
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function collectHeadChangedFiles(repoRoot) {
+  const output = runGit(
+    ['show', '--name-only', '--diff-filter=ACMR', '--pretty=format:', 'HEAD'],
+    repoRoot,
+    { allowFailure: true }
+  );
+
+  if (!output) return [];
+
+  return output
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function collectChangedFiles(repoRoot, range) {
+  if (!range) return [];
+
+  const diffArgs = ['diff', '--name-only', '--diff-filter=ACMR', `${range.base}..${range.head}`];
+
+  const baseExists = gitObjectExists(repoRoot, range.base);
+  const headExists = gitObjectExists(repoRoot, range.head);
+  if (!baseExists || !headExists) {
+    log.warn('检测到 diff range 所需提交缺失，尝试补全 git 历史（避免浅克隆导致失败）');
+    tryFetchMoreHistory(repoRoot);
+  }
+
+  const output = runGit(diffArgs, repoRoot, { allowFailure: true });
+  if (!output) {
+    log.warn('无法计算 revision range，回退为 HEAD 变更文件（可能仅覆盖最后一次提交）');
+    return collectHeadChangedFiles(repoRoot);
+  }
+
+  return output
+    .split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean);
+}
+
+function collectWorkingTreeChangedFiles(repoRoot) {
+  const files = new Set();
+  const unstaged = runGit(['diff', '--name-only', '--diff-filter=ACMR', 'HEAD'], repoRoot, {
+    allowFailure: true,
+  });
+  const staged = runGit(['diff', '--cached', '--name-only', '--diff-filter=ACMR'], repoRoot, {
+    allowFailure: true,
+  });
+
+  [unstaged, staged].forEach((block) => {
+    if (!block) return;
+    block
+      .split('\n')
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .forEach((filePath) => files.add(filePath));
+  });
+
+  return Array.from(files).sort();
+}
+
+function shouldCheckFile(filePath) {
+  const normalized = filePath.split(path.sep).join('/');
+
+  if (normalized === 'package-lock.json') return false;
+
+  // 这些文件历史上未统一为 Prettier 风格；避免为了启用检查产生巨量格式化 diff
+  if (normalized === 'src/generator/main.js' || normalized === 'src/runtime/index.js') return false;
+
+  // 与现有 npm scripts 的检查范围对齐：不检查 docs/ 与 templates/
+  const allowedRoots = ['src/', 'scripts/', 'test/', '.github/', 'config/'];
+  const isRootFile = !normalized.includes('/');
+  const hasAllowedRoot = allowedRoots.some((prefix) => normalized.startsWith(prefix));
+
+  const isAllowedPath =
+    hasAllowedRoot || (isRootFile && (normalized.endsWith('.md') || normalized.endsWith('.json')));
+
+  if (!isAllowedPath) return false;
+
+  const ext = path.extname(normalized).toLowerCase();
+  return ['.js', '.json', '.md', '.yml', '.yaml'].includes(ext);
+}
+
+function resolvePrettierBin(repoRoot) {
+  const base = path.join(repoRoot, 'node_modules', '.bin', 'prettier');
+  if (fs.existsSync(base)) return base;
+  if (fs.existsSync(`${base}.cmd`)) return `${base}.cmd`;
+  return null;
+}
+
+function main() {
+  const repoRoot = path.resolve(__dirname, '..');
+  const elapsedMs = startTimer();
+
+  log.info('开始');
+
+  const event = tryReadGithubEvent(process.env.GITHUB_EVENT_PATH);
+  const range = getDiffRangeFromGithubEvent(event);
+
+  const candidateFiles = range
+    ? collectChangedFiles(repoRoot, range)
+    : collectWorkingTreeChangedFiles(repoRoot);
+
+  const filesToCheck = candidateFiles.filter(shouldCheckFile);
+
+  if (filesToCheck.length === 0) {
+    log.ok('未发现需要检查的文件，跳过');
+    return;
+  }
+
+  const prettierBin = resolvePrettierBin(repoRoot);
+  if (!prettierBin) {
+    log.error('未找到 prettier，可先运行 npm ci / npm install');
+    process.exitCode = 1;
+    return;
+  }
+
+  log.info('准备检查文件格式', { files: filesToCheck.length });
+  if (isVerbose()) {
+    filesToCheck.forEach((filePath) => log.info('待检查', { file: filePath }));
+  }
+
+  try {
+    execFileSync(prettierBin, ['--check', ...filesToCheck], { cwd: repoRoot, stdio: 'inherit' });
+    log.ok('通过', { ms: elapsedMs(), files: filesToCheck.length });
+  } catch (error) {
+    log.error('未通过', {
+      ms: elapsedMs(),
+      files: filesToCheck.length,
+      exit: error && error.status ? error.status : 1,
+    });
+    process.exitCode = error && error.status ? error.status : 1;
+  }
+}
+
+main();
diff --git a/scripts/format.js b/scripts/format.js
new file mode 100644
index 0000000000000000000000000000000000000000..2b208beb6800fe2ea157d580a32d71ef947329c1
--- /dev/null
+++ b/scripts/format.js
@@ -0,0 +1,67 @@
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { createLogger, isVerbose, startTimer } = require('../src/generator/utils/logger');
+
+const lifecycleEvent = process.env.npm_lifecycle_event
+  ? String(process.env.npm_lifecycle_event)
+  : '';
+const scope =
+  lifecycleEvent === 'format' || lifecycleEvent.startsWith('format:') ? lifecycleEvent : 'format';
+const log = createLogger(scope);
+
+const PATTERNS = [
+  'src/**/*.js',
+  'scripts/**/*.js',
+  'test/**/*.js',
+  '.github/**/*.yml',
+  '*.{md,json}',
+  'config/**/*.md',
+  'config/**/*.yml',
+];
+
+function parseMode(argv) {
+  if (argv.includes('--check')) return 'check';
+  if (argv.includes('--write')) return 'write';
+  return 'check';
+}
+
+async function main() {
+  const elapsedMs = startTimer();
+  const mode = parseMode(process.argv.slice(2));
+  log.info('开始', { mode, version: process.env.npm_package_version });
+
+  const repoRoot = path.resolve(__dirname, '..');
+  const prettierCli = path.join(repoRoot, 'node_modules', 'prettier', 'bin', 'prettier.cjs');
+
+  const args = [];
+  if (mode === 'write') args.push('--write');
+  else args.push('--check');
+
+  // Prettier 本身会根据 .prettierignore 过滤；这里不额外做 file list，保持输出简洁
+  if (isVerbose()) {
+    log.info('检查范围', { patterns: PATTERNS.join(' ') });
+  }
+
+  const result = spawnSync(process.execPath, [prettierCli, ...args, ...PATTERNS], {
+    cwd: repoRoot,
+    stdio: 'inherit',
+  });
+
+  const exitCode = result && Number.isFinite(result.status) ? result.status : 1;
+  if (exitCode !== 0) {
+    log.error('失败', { ms: elapsedMs(), exit: exitCode });
+    process.exitCode = exitCode;
+    return;
+  }
+
+  log.ok('完成', { ms: elapsedMs(), mode });
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    log.error('执行失败', { message: error && error.message ? error.message : String(error) });
+    if (isVerbose() && error && error.stack) console.error(error.stack);
+    process.exitCode = 1;
+  });
+}
diff --git a/scripts/lint.js b/scripts/lint.js
new file mode 100644
index 0000000000000000000000000000000000000000..1b464460d53be90a0943109fe84b337def25d2cd
--- /dev/null
+++ b/scripts/lint.js
@@ -0,0 +1,69 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+const { createLogger } = require('../src/generator/utils/logger');
+
+const log = createLogger('lint');
+
+function collectJsFiles(rootDir) {
+  const files = [];
+
+  const walk = (currentDir) => {
+    let entries;
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+
+    entries.forEach((entry) => {
+      const fullPath = path.join(currentDir, entry.name);
+
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === 'dist') return;
+        walk(fullPath);
+        return;
+      }
+
+      if (entry.isFile() && entry.name.endsWith('.js')) {
+        files.push(fullPath);
+      }
+    });
+  };
+
+  walk(rootDir);
+  return files;
+}
+
+function main() {
+  const projectRoot = path.resolve(__dirname, '..');
+  const targetDirs = ['src', 'scripts', 'test'].map((dir) => path.join(projectRoot, dir));
+
+  const jsFiles = targetDirs.flatMap((dir) => collectJsFiles(dir)).sort();
+
+  if (jsFiles.length === 0) {
+    log.ok('未发现需要检查的 .js 文件，跳过');
+    return;
+  }
+
+  let hasError = false;
+  jsFiles.forEach((filePath) => {
+    const relativePath = path.relative(projectRoot, filePath);
+    try {
+      execFileSync(process.execPath, ['--check', filePath], { stdio: 'inherit' });
+    } catch (error) {
+      hasError = true;
+      log.error('语法检查失败', { file: relativePath, exit: error && error.status });
+    }
+  });
+
+  if (hasError) {
+    log.error('语法检查未通过', { files: jsFiles.length });
+    process.exitCode = 1;
+  } else {
+    log.ok('语法检查通过', { files: jsFiles.length });
+  }
+}
+
+main();
diff --git a/scripts/serve-dist.js b/scripts/serve-dist.js
new file mode 100644
index 0000000000000000000000000000000000000000..62abcf2e77614932e96f126e84ac4ec331f2986d
--- /dev/null
+++ b/scripts/serve-dist.js
@@ -0,0 +1,212 @@
+const fs = require('node:fs');
+const http = require('node:http');
+const path = require('node:path');
+
+const { createLogger, isVerbose } = require('../src/generator/utils/logger');
+
+const log = createLogger('serve');
+
+function parseInteger(value, fallback) {
+  const n = Number.parseInt(String(value), 10);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function parseArgs(argv) {
+  const args = Array.isArray(argv) ? argv.slice() : [];
+
+  const getValue = (keys) => {
+    const idx = args.findIndex((a) => keys.includes(a));
+    if (idx === -1) return null;
+    const next = args[idx + 1];
+    return next ? String(next) : null;
+  };
+
+  const portArg = getValue(['--port', '-p']);
+  const hostArg = getValue(['--host', '-h']);
+  const rootArg = getValue(['--root']);
+
+  return {
+    port: portArg ? parseInteger(portArg, null) : null,
+    host: hostArg ? String(hostArg) : null,
+    root: rootArg ? String(rootArg) : null,
+  };
+}
+
+function getContentType(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.html') return 'text/html; charset=utf-8';
+  if (ext === '.js') return 'text/javascript; charset=utf-8';
+  if (ext === '.css') return 'text/css; charset=utf-8';
+  if (ext === '.json') return 'application/json; charset=utf-8';
+  if (ext === '.svg') return 'image/svg+xml';
+  if (ext === '.png') return 'image/png';
+  if (ext === '.jpg' || ext === '.jpeg') return 'image/jpeg';
+  if (ext === '.gif') return 'image/gif';
+  if (ext === '.webp') return 'image/webp';
+  if (ext === '.ico') return 'image/x-icon';
+  if (ext === '.txt') return 'text/plain; charset=utf-8';
+  if (ext === '.xml') return 'application/xml; charset=utf-8';
+  if (ext === '.map') return 'application/json; charset=utf-8';
+  return 'application/octet-stream';
+}
+
+function sendNotFound(res, rootDir) {
+  const fallback404 = path.join(rootDir, '404.html');
+  if (fs.existsSync(fallback404)) {
+    res.statusCode = 404;
+    res.setHeader('Content-Type', 'text/html; charset=utf-8');
+    fs.createReadStream(fallback404).pipe(res);
+    return;
+  }
+
+  res.statusCode = 404;
+  res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+  res.end('Not Found');
+}
+
+function sendFile(req, res, filePath, rootDir) {
+  try {
+    const stat = fs.statSync(filePath);
+    if (!stat.isFile()) return sendNotFound(res, rootDir);
+
+    res.statusCode = 200;
+    res.setHeader('Content-Type', getContentType(filePath));
+    res.setHeader('Content-Length', String(stat.size));
+
+    if (req.method === 'HEAD') {
+      res.end();
+      return;
+    }
+
+    fs.createReadStream(filePath).pipe(res);
+  } catch (error) {
+    log.warn('读取文件失败', {
+      path: filePath,
+      message: error && error.message ? error.message : String(error),
+    });
+    if (isVerbose() && error && error.stack) console.error(error.stack);
+    sendNotFound(res, rootDir);
+  }
+}
+
+function buildHandler(rootDir) {
+  const normalizedRoot = path.resolve(rootDir);
+
+  return (req, res) => {
+    const rawUrl = req.url || '/';
+    const rawPath = rawUrl.split('?')[0] || '/';
+
+    let decodedPath = '/';
+    try {
+      decodedPath = decodeURIComponent(rawPath);
+    } catch {
+      res.statusCode = 400;
+      res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+      res.end('Bad Request');
+      return;
+    }
+
+    const safePath = decodedPath.replace(/\\/g, '/');
+    const resolved = path.resolve(normalizedRoot, `.${safePath}`);
+    if (!resolved.startsWith(`${normalizedRoot}${path.sep}`) && resolved !== normalizedRoot) {
+      res.statusCode = 403;
+      res.setHeader('Content-Type', 'text/plain; charset=utf-8');
+      res.end('Forbidden');
+      return;
+    }
+
+    let target = resolved;
+    try {
+      if (fs.existsSync(target) && fs.statSync(target).isDirectory()) {
+        target = path.join(target, 'index.html');
+      }
+    } catch {
+      // ignore
+    }
+
+    if (!fs.existsSync(target)) {
+      sendNotFound(res, normalizedRoot);
+      return;
+    }
+
+    sendFile(req, res, target, normalizedRoot);
+  };
+}
+
+function startServer(options = {}) {
+  const { rootDir, host, port } = options;
+  const normalizedRoot = path.resolve(rootDir);
+
+  if (!fs.existsSync(normalizedRoot)) {
+    throw new Error(`dist 目录不存在：${normalizedRoot}`);
+  }
+
+  const handler = buildHandler(normalizedRoot);
+  const server = http.createServer(handler);
+
+  return new Promise((resolve, reject) => {
+    server.on('error', reject);
+    server.listen(port, host, () => {
+      const addr = server.address();
+      const actualPort = addr && typeof addr === 'object' ? addr.port : port;
+      resolve({ server, port: actualPort, host });
+    });
+  });
+}
+
+async function main() {
+  const repoRoot = path.resolve(__dirname, '..');
+  const defaultRoot = path.join(repoRoot, 'dist');
+  const args = parseArgs(process.argv.slice(2));
+
+  const port =
+    args.port ?? parseInteger(process.env.PORT || process.env.MENAV_PORT || '5173', 5173);
+  const host = args.host || process.env.HOST || '0.0.0.0';
+  const rootDir = args.root ? path.resolve(repoRoot, args.root) : defaultRoot;
+
+  log.info('启动静态服务', { root: path.relative(repoRoot, rootDir) || '.', host, port });
+
+  const { server, port: actualPort } = await startServer({ rootDir, host, port });
+
+  log.ok('就绪', { url: `http://localhost:${actualPort}` });
+
+  let shuttingDown = false;
+  const shutdown = (signal) => {
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    process.stdout.write('\n');
+    log.info('正在关闭...', { signal });
+
+    try {
+      if (typeof server.closeIdleConnections === 'function') server.closeIdleConnections();
+      if (typeof server.closeAllConnections === 'function') server.closeAllConnections();
+    } catch {
+      // ignore
+    }
+
+    const exit = signal === 'SIGINT' ? 130 : 0;
+    const forceTimer = setTimeout(() => process.exit(exit), 2000);
+    if (typeof forceTimer.unref === 'function') forceTimer.unref();
+
+    server.close(() => {
+      clearTimeout(forceTimer);
+      process.exit(exit);
+    });
+  };
+
+  process.once('SIGINT', () => shutdown('SIGINT'));
+  process.once('SIGTERM', () => shutdown('SIGTERM'));
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    log.error('启动失败', { message: error && error.message ? error.message : String(error) });
+    if (isVerbose() && error && error.stack) console.error(error.stack);
+    process.exitCode = 1;
+  });
+}
+
+module.exports = {
+  startServer,
+};
diff --git a/scripts/sync-articles.js b/scripts/sync-articles.js
new file mode 100644
index 0000000000000000000000000000000000000000..60b5cd566a08274b06104c68707f584e257452b8
--- /dev/null
+++ b/scripts/sync-articles.js
@@ -0,0 +1,746 @@
+/* eslint-disable no-console */
+const fs = require('fs');
+const path = require('path');
+const dns = require('node:dns').promises;
+const net = require('node:net');
+const Parser = require('rss-parser');
+
+const { loadConfig } = require('../src/generator.js');
+const { createLogger, isVerbose, startTimer } = require('../src/generator/utils/logger');
+
+const log = createLogger('sync:articles');
+
+const DEFAULT_RSS_SETTINGS = {
+  enabled: true,
+  cacheDir: 'dev',
+  fetch: {
+    timeoutMs: 10_000,
+    maxRetries: 1,
+    concurrency: 5,
+    totalTimeoutMs: 60_000,
+    maxRedirects: 3,
+    userAgent: 'MeNavRSSSync/1.0',
+    htmlMaxBytes: 512 * 1024,
+    feedMaxBytes: 1024 * 1024,
+  },
+  articles: {
+    perSite: 8,
+    total: 50,
+    summaryMaxLength: 200,
+  },
+};
+
+function parseBooleanEnv(value, fallback) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const v = String(value).trim().toLowerCase();
+  if (v === '1' || v === 'true' || v === 'yes' || v === 'y') return true;
+  if (v === '0' || v === 'false' || v === 'no' || v === 'n') return false;
+  return fallback;
+}
+
+function parseIntegerEnv(value, fallback) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const n = Number.parseInt(String(value), 10);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function getRssSettings(config) {
+  const fromConfig =
+    config && config.site && config.site.rss && typeof config.site.rss === 'object'
+      ? config.site.rss
+      : {};
+
+  const merged = {
+    ...DEFAULT_RSS_SETTINGS,
+    ...fromConfig,
+    fetch: {
+      ...DEFAULT_RSS_SETTINGS.fetch,
+      ...(fromConfig.fetch || {}),
+    },
+    articles: {
+      ...DEFAULT_RSS_SETTINGS.articles,
+      ...(fromConfig.articles || {}),
+    },
+  };
+
+  // 环境变量覆盖（主要给 CI 调试/降级用）
+  merged.enabled = parseBooleanEnv(process.env.RSS_ENABLED, merged.enabled);
+  merged.cacheDir = process.env.RSS_CACHE_DIR ? String(process.env.RSS_CACHE_DIR) : merged.cacheDir;
+
+  merged.fetch.timeoutMs = parseIntegerEnv(process.env.RSS_FETCH_TIMEOUT, merged.fetch.timeoutMs);
+  merged.fetch.maxRetries = parseIntegerEnv(
+    process.env.RSS_FETCH_MAX_RETRIES,
+    merged.fetch.maxRetries
+  );
+  merged.fetch.concurrency = parseIntegerEnv(
+    process.env.RSS_FETCH_CONCURRENCY,
+    merged.fetch.concurrency
+  );
+  merged.fetch.totalTimeoutMs = parseIntegerEnv(
+    process.env.RSS_TOTAL_TIMEOUT,
+    merged.fetch.totalTimeoutMs
+  );
+  merged.fetch.maxRedirects = parseIntegerEnv(
+    process.env.RSS_FETCH_MAX_REDIRECTS,
+    merged.fetch.maxRedirects
+  );
+
+  merged.articles.perSite = parseIntegerEnv(
+    process.env.RSS_ARTICLES_PER_SITE,
+    merged.articles.perSite
+  );
+  merged.articles.total = parseIntegerEnv(process.env.RSS_ARTICLES_TOTAL, merged.articles.total);
+  merged.articles.summaryMaxLength = parseIntegerEnv(
+    process.env.RSS_SUMMARY_MAX_LENGTH,
+    merged.articles.summaryMaxLength
+  );
+
+  // 兜底约束：避免奇怪配置导致卡死/爆内存
+  merged.fetch.timeoutMs = Math.max(1_000, merged.fetch.timeoutMs);
+  merged.fetch.totalTimeoutMs = Math.max(5_000, merged.fetch.totalTimeoutMs);
+  merged.fetch.concurrency = Math.max(1, Math.min(20, merged.fetch.concurrency));
+  merged.fetch.maxRetries = Math.max(0, Math.min(3, merged.fetch.maxRetries));
+  merged.fetch.maxRedirects = Math.max(0, Math.min(10, merged.fetch.maxRedirects));
+
+  merged.articles.perSite = Math.max(1, Math.min(50, merged.articles.perSite));
+  merged.articles.total = Math.max(1, Math.min(500, merged.articles.total));
+  merged.articles.summaryMaxLength = Math.max(0, Math.min(2_000, merged.articles.summaryMaxLength));
+
+  return merged;
+}
+
+function isHttpUrl(url) {
+  if (!url) return false;
+  try {
+    const u = new URL(String(url));
+    return u.protocol === 'http:' || u.protocol === 'https:';
+  } catch {
+    return false;
+  }
+}
+
+function isPrivateIp(ip) {
+  if (!ip) return true;
+
+  if (net.isIP(ip) === 4) {
+    const parts = ip.split('.').map((n) => Number.parseInt(n, 10));
+    if (parts.length !== 4 || parts.some((n) => !Number.isFinite(n) || n < 0 || n > 255))
+      return true;
+
+    const [a, b] = parts;
+    if (a === 10) return true;
+    if (a === 127) return true;
+    if (a === 0) return true;
+    if (a === 169 && b === 254) return true;
+    if (a === 172 && b >= 16 && b <= 31) return true;
+    if (a === 192 && b === 168) return true;
+    if (a >= 224) return true; // 组播/保留
+    return false;
+  }
+
+  if (net.isIP(ip) === 6) {
+    const normalized = String(ip).toLowerCase();
+    if (normalized === '::1') return true;
+    if (normalized.startsWith('fe80:')) return true; // link-local
+    if (normalized.startsWith('fc') || normalized.startsWith('fd')) return true; // ULA
+    return false;
+  }
+
+  return true;
+}
+
+async function withTimeout(promise, timeoutMs, label) {
+  let timer;
+  try {
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => reject(new Error(`${label} 超时（${timeoutMs}ms）`)), timeoutMs);
+    });
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+async function assertSafeToFetch(url, timeoutMs) {
+  const u = new URL(String(url));
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    throw new Error(`仅允许 http/https：${u.protocol}`);
+  }
+
+  if (u.username || u.password) {
+    throw new Error('禁止包含用户名/密码的 URL');
+  }
+
+  const hostname = u.hostname.toLowerCase();
+  if (
+    hostname === 'localhost' ||
+    hostname === '0.0.0.0' ||
+    hostname === '127.0.0.1' ||
+    hostname === '::1'
+  ) {
+    throw new Error('禁止访问本机地址');
+  }
+  if (hostname.endsWith('.local')) {
+    throw new Error('禁止访问 .local 域名');
+  }
+
+  if (net.isIP(hostname)) {
+    if (isPrivateIp(hostname)) throw new Error('禁止访问内网/保留 IP');
+    return;
+  }
+
+  // 解析域名，阻断解析到内网的情况（best-effort）
+  const records = await withTimeout(
+    dns.lookup(hostname, { all: true, verbatim: true }),
+    Math.min(2_000, timeoutMs),
+    `DNS 解析 ${hostname}`
+  );
+
+  if (!Array.isArray(records) || records.length === 0) {
+    throw new Error('DNS 解析失败或无结果');
+  }
+
+  const hasPrivate = records.some((r) => isPrivateIp(r.address));
+  if (hasPrivate) throw new Error('DNS 解析到内网/保留地址，已阻断');
+}
+
+function buildHeaders(userAgent) {
+  return {
+    'user-agent': userAgent,
+    accept: 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8',
+  };
+}
+
+async function fetchWithRedirects(url, { timeoutMs, maxRedirects, headers, maxBytes }) {
+  let current = String(url);
+  for (let i = 0; i <= maxRedirects; i += 1) {
+    await assertSafeToFetch(current, timeoutMs);
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+    let response;
+    try {
+      response = await fetch(current, {
+        method: 'GET',
+        redirect: 'manual',
+        headers,
+        signal: controller.signal,
+      });
+    } finally {
+      clearTimeout(timer);
+    }
+
+    const status = response.status;
+    if (status >= 300 && status < 400) {
+      const location = response.headers.get('location');
+      if (!location) throw new Error(`重定向缺少 Location（${status}）`);
+      current = new URL(location, current).toString();
+      continue;
+    }
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${status}`);
+    }
+
+    const text = await readResponseTextWithLimit(response, maxBytes);
+    return { url: current, response, text };
+  }
+
+  throw new Error(`重定向次数超过上限（${maxRedirects}）`);
+}
+
+async function readResponseTextWithLimit(response, maxBytes) {
+  if (!response.body || typeof response.body.getReader !== 'function') {
+    const text = await response.text();
+    if (Buffer.byteLength(text, 'utf8') > maxBytes) {
+      throw new Error('响应体过大');
+    }
+    return text;
+  }
+
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder('utf-8');
+  let received = 0;
+  let text = '';
+
+  while (true) {
+    // eslint-disable-next-line no-await-in-loop
+    const { done, value } = await reader.read();
+    if (done) break;
+    received += value.byteLength;
+    if (received > maxBytes) {
+      try {
+        reader.cancel();
+      } catch {
+        // ignore
+      }
+      throw new Error('响应体过大');
+    }
+    text += decoder.decode(value, { stream: true });
+  }
+  text += decoder.decode();
+  return text;
+}
+
+function extractFeedLinksFromHtml(html, baseUrl) {
+  const candidates = [];
+  if (!html) return candidates;
+
+  const linkTags = String(html).match(/<link\b[^>]*>/gi) || [];
+  for (const tag of linkTags) {
+    const rel = /rel\s*=\s*["']([^"']+)["']/i.exec(tag)?.[1] || '';
+    if (!/alternate/i.test(rel)) continue;
+
+    const type = /type\s*=\s*["']([^"']+)["']/i.exec(tag)?.[1] || '';
+    const isFeedType = /application\/(rss|atom)\+xml/i.test(type) || /(rss|atom)/i.test(type);
+    if (!isFeedType) continue;
+
+    const href = /href\s*=\s*["']([^"']+)["']/i.exec(tag)?.[1];
+    if (!href) continue;
+
+    try {
+      const resolved = new URL(href, baseUrl).toString();
+      if (isHttpUrl(resolved)) candidates.push(resolved);
+    } catch {
+      // ignore bad url
+    }
+  }
+
+  // 简单排序：优先 RSS，其次 Atom
+  const rank = (url) => (url.includes('atom') ? 2 : 1);
+  return [...new Set(candidates)].sort((a, b) => rank(a) - rank(b));
+}
+
+function buildCommonFeedUrls(siteUrl) {
+  const common = ['/feed', '/rss.xml', '/rss', '/atom.xml', '/atom', '/feed.xml'];
+  const out = [];
+  for (const p of common) {
+    try {
+      const u = new URL(p, siteUrl).toString();
+      out.push(u);
+    } catch {
+      // ignore
+    }
+  }
+  return out;
+}
+
+async function discoverFeedUrl(siteUrl, settings, deadlineTs) {
+  const timeRemaining = deadlineTs - Date.now();
+  if (timeRemaining <= 0) throw new Error('总超时：无法继续发现 RSS');
+
+  const homepage = await fetchWithRedirects(siteUrl, {
+    timeoutMs: Math.min(settings.fetch.timeoutMs, timeRemaining),
+    maxRedirects: settings.fetch.maxRedirects,
+    headers: buildHeaders(settings.fetch.userAgent),
+    maxBytes: settings.fetch.htmlMaxBytes,
+  });
+
+  const contentType = homepage.response.headers.get('content-type') || '';
+  if (
+    /text\/html/i.test(contentType) ||
+    /application\/xhtml\+xml/i.test(contentType) ||
+    !contentType
+  ) {
+    const candidates = extractFeedLinksFromHtml(homepage.text, homepage.url);
+    if (candidates.length > 0) {
+      return candidates[0];
+    }
+  }
+
+  return null;
+}
+
+function stripHtmlToText(input) {
+  const raw = String(input || '');
+  const withoutTags = raw
+    .replace(/<script[\s\S]*?<\/script>/gi, '')
+    .replace(/<style[\s\S]*?<\/style>/gi, '')
+    .replace(/<[^>]+>/g, ' ');
+
+  const decoded = withoutTags
+    .replace(/&nbsp;/gi, ' ')
+    .replace(/&amp;/gi, '&')
+    .replace(/&lt;/gi, '<')
+    .replace(/&gt;/gi, '>')
+    .replace(/&quot;/gi, '"')
+    .replace(/&#0?39;/g, "'")
+    .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(Number.parseInt(hex, 16)))
+    .replace(/&#(\d+);/g, (_, num) => String.fromCodePoint(Number.parseInt(num, 10)));
+
+  return decoded.replace(/\s+/g, ' ').trim();
+}
+
+function truncateText(text, maxLen) {
+  if (!maxLen || maxLen <= 0) return '';
+  const s = String(text || '');
+  if (s.length <= maxLen) return s;
+  return s.slice(0, maxLen) + '...';
+}
+
+function normalizePublishedAt(item) {
+  const iso = item && typeof item.isoDate === 'string' ? item.isoDate : '';
+  if (iso) return iso;
+
+  const pub = item && typeof item.pubDate === 'string' ? item.pubDate : '';
+  if (pub) {
+    const d = new Date(pub);
+    if (!Number.isNaN(d.getTime())) return d.toISOString();
+  }
+
+  return '';
+}
+
+function normalizeArticle(item, sourceSite, settings) {
+  const title = item && item.title !== undefined ? String(item.title).trim() : '';
+  if (!title) return null;
+
+  const link = item && item.link ? String(item.link).trim() : '';
+  if (!isHttpUrl(link)) return null;
+
+  const summaryRaw =
+    (item && item.contentSnippet) || (item && item.summary) || (item && item.content) || '';
+  const summaryText = stripHtmlToText(summaryRaw);
+  const summary = settings.articles.summaryMaxLength
+    ? truncateText(summaryText, settings.articles.summaryMaxLength)
+    : summaryText;
+
+  const publishedAt = normalizePublishedAt(item);
+
+  const source = sourceSite && sourceSite.name ? String(sourceSite.name) : '';
+  const sourceUrl = sourceSite && sourceSite.url ? String(sourceSite.url) : '';
+  const icon = sourceSite && sourceSite.icon ? String(sourceSite.icon) : 'fas fa-pen';
+
+  return {
+    title,
+    url: link,
+    summary,
+    publishedAt,
+    source,
+    // 站点首页 URL（用于生成端按分类聚合展示；文章 url 为具体文章链接）
+    sourceUrl,
+    icon,
+  };
+}
+
+async function fetchAndParseFeed(feedUrl, settings, parser, deadlineTs) {
+  const timeRemaining = deadlineTs - Date.now();
+  if (timeRemaining <= 0) throw new Error('总超时：无法继续抓取 Feed');
+
+  const feed = await fetchWithRedirects(feedUrl, {
+    timeoutMs: Math.min(settings.fetch.timeoutMs, timeRemaining),
+    maxRedirects: settings.fetch.maxRedirects,
+    headers: {
+      ...buildHeaders(settings.fetch.userAgent),
+      accept: 'application/rss+xml,application/atom+xml,application/xml,text/xml;q=0.9,*/*;q=0.8',
+    },
+    maxBytes: settings.fetch.feedMaxBytes,
+  });
+
+  const parsed = await parser.parseString(feed.text);
+  return {
+    feedUrl: feed.url,
+    feedTitle: parsed.title || '',
+    items: Array.isArray(parsed.items) ? parsed.items : [],
+  };
+}
+
+async function processSourceSite(sourceSite, settings, parser, deadlineTs) {
+  const url = sourceSite && sourceSite.url ? String(sourceSite.url) : '';
+  if (!isHttpUrl(url)) {
+    return {
+      site: {
+        name: sourceSite && sourceSite.name ? String(sourceSite.name) : '',
+        url,
+        feedUrl: '',
+        status: 'skipped',
+        error: '无效 URL（需为 http/https）',
+        fetchedAt: new Date().toISOString(),
+      },
+      articles: [],
+    };
+  }
+
+  let lastError = null;
+
+  const tryOnce = async (feedUrl) => {
+    const parsed = await fetchAndParseFeed(feedUrl, settings, parser, deadlineTs);
+    const normalized = parsed.items
+      .map((item) => normalizeArticle(item, sourceSite, settings))
+      .filter(Boolean)
+      .slice(0, settings.articles.perSite);
+    return { feedUrl: parsed.feedUrl, articles: normalized };
+  };
+
+  const attempt = async () => {
+    const discovered = await discoverFeedUrl(url, settings, deadlineTs);
+    const candidates = discovered
+      ? [discovered, ...buildCommonFeedUrls(url)]
+      : buildCommonFeedUrls(url);
+
+    for (const candidate of [...new Set(candidates)]) {
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        const res = await tryOnce(candidate);
+        return res;
+      } catch (e) {
+        lastError = e;
+      }
+    }
+    throw lastError || new Error('未找到可用 Feed');
+  };
+
+  const elapsedMs = startTimer();
+  for (let i = 0; i <= settings.fetch.maxRetries; i += 1) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const res = await attempt();
+      return {
+        site: {
+          name: sourceSite && sourceSite.name ? String(sourceSite.name) : '',
+          url,
+          feedUrl: res.feedUrl,
+          status: 'success',
+          error: '',
+          fetchedAt: new Date().toISOString(),
+          durationMs: elapsedMs(),
+        },
+        articles: res.articles,
+      };
+    } catch (e) {
+      lastError = e;
+    }
+  }
+
+  return {
+    site: {
+      name: sourceSite && sourceSite.name ? String(sourceSite.name) : '',
+      url,
+      feedUrl: '',
+      status: 'failed',
+      error: lastError ? String(lastError.message || lastError) : '未知错误',
+      fetchedAt: new Date().toISOString(),
+      durationMs: elapsedMs(),
+    },
+    articles: [],
+  };
+}
+
+async function mapWithConcurrency(items, concurrency, worker) {
+  const results = new Array(items.length);
+  let nextIndex = 0;
+
+  async function runOne() {
+    while (nextIndex < items.length) {
+      const currentIndex = nextIndex;
+      nextIndex += 1;
+
+      try {
+        // eslint-disable-next-line no-await-in-loop
+        results[currentIndex] = await worker(items[currentIndex], currentIndex);
+      } catch (e) {
+        results[currentIndex] = { error: e };
+      }
+    }
+  }
+
+  const runners = [];
+  const count = Math.max(1, Math.min(concurrency, items.length));
+  for (let i = 0; i < count; i += 1) {
+    runners.push(runOne());
+  }
+  await Promise.all(runners);
+  return results;
+}
+
+function collectSitesRecursively(node, output) {
+  if (!node || typeof node !== 'object') return;
+
+  if (Array.isArray(node.subcategories))
+    node.subcategories.forEach((child) => collectSitesRecursively(child, output));
+  if (Array.isArray(node.groups))
+    node.groups.forEach((child) => collectSitesRecursively(child, output));
+  if (Array.isArray(node.subgroups))
+    node.subgroups.forEach((child) => collectSitesRecursively(child, output));
+
+  if (Array.isArray(node.sites)) {
+    node.sites.forEach((site) => {
+      if (site && typeof site === 'object') output.push(site);
+    });
+  }
+}
+
+function buildFlatSitesFromCategories(categories) {
+  const out = [];
+  if (!Array.isArray(categories)) return out;
+  categories.forEach((category) => collectSitesRecursively(category, out));
+  return out;
+}
+
+async function syncArticlesForPage(pageId, pageConfig, config, settings) {
+  const sourceSites = Array.isArray(pageConfig && pageConfig.sites)
+    ? pageConfig.sites
+    : buildFlatSitesFromCategories(
+        pageConfig && Array.isArray(pageConfig.categories) ? pageConfig.categories : []
+      );
+
+  const elapsedMs = startTimer();
+  const startedAt = Date.now();
+  const deadlineTs = startedAt + settings.fetch.totalTimeoutMs;
+
+  const parser = new Parser({
+    timeout: settings.fetch.timeoutMs,
+  });
+
+  const results = await mapWithConcurrency(sourceSites, settings.fetch.concurrency, async (site) =>
+    processSourceSite(site, settings, parser, deadlineTs)
+  );
+
+  const sites = [];
+  const articles = [];
+  const seen = new Set();
+
+  for (const r of results) {
+    if (!r || r.error) continue;
+    if (r.site) sites.push(r.site);
+    if (Array.isArray(r.articles)) {
+      for (const a of r.articles) {
+        if (!a || !a.url) continue;
+        if (seen.has(a.url)) continue;
+        seen.add(a.url);
+        articles.push(a);
+      }
+    }
+  }
+
+  articles.sort((a, b) => {
+    const ta = a.publishedAt ? new Date(a.publishedAt).getTime() : 0;
+    const tb = b.publishedAt ? new Date(b.publishedAt).getTime() : 0;
+    return tb - ta;
+  });
+
+  const limitedArticles = articles.slice(0, settings.articles.total);
+
+  const successSites = sites.filter((s) => s.status === 'success').length;
+  const failedSites = sites.filter((s) => s.status === 'failed').length;
+  const skippedSites = sites.filter((s) => s.status === 'skipped').length;
+
+  const cache = {
+    version: '1.0',
+    pageId,
+    generatedAt: new Date().toISOString(),
+    title: pageConfig && pageConfig.title ? String(pageConfig.title) : '',
+    sites,
+    articles: limitedArticles,
+    stats: {
+      totalSites: sourceSites.length,
+      successSites,
+      failedSites,
+      skippedSites,
+      totalArticles: limitedArticles.length,
+      durationMs: elapsedMs(),
+    },
+  };
+
+  const cacheDir = path.resolve(process.cwd(), settings.cacheDir);
+  fs.mkdirSync(cacheDir, { recursive: true });
+
+  const cachePath = path.join(cacheDir, `${pageId}.feed-cache.json`);
+  fs.writeFileSync(cachePath, JSON.stringify(cache, null, 2));
+
+  return { cachePath, cache };
+}
+
+function pickArticlesPages(config, onlyPageId) {
+  const pages = [];
+  const nav = Array.isArray(config.navigation) ? config.navigation : [];
+
+  for (const item of nav) {
+    const pageId = item && item.id ? String(item.id) : '';
+    if (!pageId) continue;
+    if (onlyPageId && pageId !== onlyPageId) continue;
+
+    const pageConfig = config[pageId];
+    if (!pageConfig || typeof pageConfig !== 'object') continue;
+
+    const templateName = pageConfig.template ? String(pageConfig.template) : pageId;
+    if (templateName !== 'articles') continue;
+
+    pages.push({ pageId, pageConfig });
+  }
+
+  return pages;
+}
+
+async function main() {
+  const elapsedMs = startTimer();
+  const args = process.argv.slice(2);
+  const pageArgIndex = args.findIndex((a) => a === '--page');
+  const onlyPageId = pageArgIndex >= 0 ? args[pageArgIndex + 1] : null;
+
+  log.info('开始', { page: onlyPageId || '' });
+
+  const config = loadConfig();
+  const settings = getRssSettings(config);
+
+  if (!settings.enabled) {
+    log.ok('RSS 已禁用，跳过', { env: 'RSS_ENABLED=false' });
+    return;
+  }
+
+  const pages = pickArticlesPages(config, onlyPageId);
+  if (pages.length === 0) {
+    log.ok('未找到需要同步的 articles 页面，跳过');
+    return;
+  }
+
+  log.info('准备同步 articles 页面缓存', { pages: pages.length });
+
+  let success = 0;
+  let failed = 0;
+
+  for (const { pageId, pageConfig } of pages) {
+    try {
+      // eslint-disable-next-line no-await-in-loop
+      const { cachePath, cache } = await syncArticlesForPage(pageId, pageConfig, config, settings);
+      success += 1;
+      log.ok('已生成缓存', {
+        page: pageId,
+        cache: cachePath,
+        articles: cache && cache.stats ? cache.stats.totalArticles : '',
+        sites: cache && cache.stats ? cache.stats.totalSites : '',
+      });
+    } catch (e) {
+      failed += 1;
+      log.warn('页面同步失败，已跳过（best-effort）', {
+        page: pageId,
+        message: e && e.message ? e.message : String(e),
+      });
+      if (isVerbose() && e && e.stack) console.error(e.stack);
+      // best-effort：不阻断其他页面/后续 build
+    }
+  }
+
+  log.ok('完成', { ms: elapsedMs(), pages: pages.length, success, failed });
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    log.error('执行失败（best-effort，不阻断后续 build/deploy）', {
+      message: err && err.message ? err.message : String(err),
+    });
+    if (isVerbose() && err && err.stack) console.error(err.stack);
+    // best-effort：不阻断后续 build/deploy（错误已输出到日志，便于排查）
+    process.exitCode = 0;
+  });
+}
+
+module.exports = {
+  getRssSettings,
+  isPrivateIp,
+  extractFeedLinksFromHtml,
+  stripHtmlToText,
+  normalizeArticle,
+  buildFlatSitesFromCategories,
+};
diff --git a/scripts/sync-heatmap.js b/scripts/sync-heatmap.js
new file mode 100644
index 0000000000000000000000000000000000000000..c08b05cdf736c619566ac416051bff07dbbd3076
--- /dev/null
+++ b/scripts/sync-heatmap.js
@@ -0,0 +1,184 @@
+/* eslint-disable no-console */
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { loadConfig } = require('../src/generator.js');
+const {
+  extractYearlyContributionsInnerHtml,
+} = require('../src/generator/utils/githubContributions');
+const { createLogger, isVerbose, startTimer } = require('../src/generator/utils/logger');
+
+const log = createLogger('sync:heatmap');
+
+const DEFAULT_SETTINGS = {
+  enabled: true,
+  cacheDir: 'dev',
+  fetch: {
+    timeoutMs: 10_000,
+    userAgent: 'MeNavHeatmapSync/1.0',
+  },
+};
+
+function parseBooleanEnv(value, fallback) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const v = String(value).trim().toLowerCase();
+  if (v === '1' || v === 'true' || v === 'yes' || v === 'y') return true;
+  if (v === '0' || v === 'false' || v === 'no' || v === 'n') return false;
+  return fallback;
+}
+
+function parseIntegerEnv(value, fallback) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const n = Number.parseInt(String(value), 10);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function getSettings(config) {
+  const fromConfig =
+    config && config.site && config.site.github && typeof config.site.github === 'object'
+      ? config.site.github
+      : {};
+
+  const merged = {
+    ...DEFAULT_SETTINGS,
+    ...fromConfig,
+    fetch: {
+      ...DEFAULT_SETTINGS.fetch,
+      ...(fromConfig.fetch || {}),
+    },
+  };
+
+  merged.enabled = parseBooleanEnv(process.env.HEATMAP_ENABLED, merged.enabled);
+
+  // 复用 projects 的 cacheDir 逻辑，保持所有 dev 缓存在同一目录
+  merged.cacheDir = process.env.PROJECTS_CACHE_DIR
+    ? String(process.env.PROJECTS_CACHE_DIR)
+    : process.env.HEATMAP_CACHE_DIR
+      ? String(process.env.HEATMAP_CACHE_DIR)
+      : merged.cacheDir;
+
+  merged.fetch.timeoutMs = parseIntegerEnv(
+    process.env.HEATMAP_FETCH_TIMEOUT,
+    merged.fetch.timeoutMs
+  );
+  merged.fetch.timeoutMs = Math.max(1_000, merged.fetch.timeoutMs);
+
+  return merged;
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function findProjectsPages(config) {
+  const pages = [];
+  const nav = Array.isArray(config.navigation) ? config.navigation : [];
+  nav.forEach((item) => {
+    const pageId = item && item.id ? String(item.id) : '';
+    if (!pageId || !config[pageId]) return;
+    const page = config[pageId];
+    const templateName = page && page.template ? String(page.template) : pageId;
+    if (templateName !== 'projects') return;
+    pages.push({ pageId, page });
+  });
+  return pages;
+}
+
+function getGithubUsernameFromConfig(config) {
+  const username =
+    config && config.site && config.site.github && config.site.github.username
+      ? String(config.site.github.username).trim()
+      : '';
+  return username;
+}
+
+async function fetchTextWithTimeout(url, { timeoutMs, headers }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const response = await fetch(url, { method: 'GET', headers, signal: controller.signal });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return await response.text();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function main() {
+  const elapsedMs = startTimer();
+  const config = loadConfig();
+  const settings = getSettings(config);
+
+  log.info('开始');
+
+  if (!settings.enabled) {
+    log.ok('heatmap 同步已禁用，跳过', { env: 'HEATMAP_ENABLED=false' });
+    return;
+  }
+
+  const username = getGithubUsernameFromConfig(config);
+  if (!username) {
+    log.ok('未配置 site.github.username，跳过');
+    return;
+  }
+
+  const pages = findProjectsPages(config);
+  if (!pages.length) {
+    log.ok('未找到 template=projects 的页面，跳过同步');
+    return;
+  }
+
+  const cacheBaseDir = path.isAbsolute(settings.cacheDir)
+    ? settings.cacheDir
+    : path.join(process.cwd(), settings.cacheDir);
+  ensureDir(cacheBaseDir);
+
+  const url = `https://github.com/users/${encodeURIComponent(username)}/contributions`;
+  const headers = {
+    'user-agent': settings.fetch.userAgent,
+    accept: 'text/html',
+  };
+
+  let html;
+  try {
+    html = await fetchTextWithTimeout(url, { timeoutMs: settings.fetch.timeoutMs, headers });
+  } catch (error) {
+    log.warn('获取 GitHub contributions 失败（best-effort）', {
+      url,
+      message: String(error && error.message ? error.message : error),
+    });
+    return;
+  }
+
+  const innerHtml = extractYearlyContributionsInnerHtml(html);
+  if (!innerHtml) {
+    log.warn('解析 contributions HTML 失败（best-effort）', { url, username });
+    return;
+  }
+
+  for (const { pageId } of pages) {
+    const payload = {
+      version: '1.0',
+      pageId,
+      generatedAt: new Date().toISOString(),
+      username,
+      sourceUrl: url,
+      html: innerHtml,
+    };
+
+    const cachePath = path.join(cacheBaseDir, `${pageId}.heatmap-cache.json`);
+    fs.writeFileSync(cachePath, JSON.stringify(payload, null, 2), 'utf8');
+    log.ok('写入 heatmap 缓存', { page: pageId, cache: cachePath });
+  }
+
+  log.ok('完成', { ms: elapsedMs(), pages: pages.length, username });
+}
+
+main().catch((error) => {
+  log.error('执行异常（best-effort，不阻断后续 build）', {
+    message: error && error.message ? error.message : String(error),
+  });
+  if (isVerbose() && error && error.stack) console.error(error.stack);
+  process.exitCode = 0; // best-effort：不阻断后续 build
+});
diff --git a/scripts/sync-projects.js b/scripts/sync-projects.js
new file mode 100644
index 0000000000000000000000000000000000000000..965975e7c7bdf081a1cedb33fc06e8377d9d73b2
--- /dev/null
+++ b/scripts/sync-projects.js
@@ -0,0 +1,315 @@
+/* eslint-disable no-console */
+const fs = require('fs');
+const path = require('path');
+
+const { loadConfig } = require('../src/generator.js');
+const { createLogger, isVerbose, startTimer } = require('../src/generator/utils/logger');
+
+const log = createLogger('sync:projects');
+
+const DEFAULT_SETTINGS = {
+  enabled: true,
+  cacheDir: 'dev',
+  fetch: {
+    timeoutMs: 10_000,
+    concurrency: 4,
+    userAgent: 'MeNavProjectsSync/1.0',
+  },
+  colors: {
+    url: 'https://raw.githubusercontent.com/ozh/github-colors/master/colors.json',
+    maxAgeMs: 7 * 24 * 60 * 60 * 1000,
+  },
+};
+
+function parseBooleanEnv(value, fallback) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const v = String(value).trim().toLowerCase();
+  if (v === '1' || v === 'true' || v === 'yes' || v === 'y') return true;
+  if (v === '0' || v === 'false' || v === 'no' || v === 'n') return false;
+  return fallback;
+}
+
+function parseIntegerEnv(value, fallback) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const n = Number.parseInt(String(value), 10);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function getSettings(config) {
+  const fromConfig =
+    config && config.site && config.site.github && typeof config.site.github === 'object'
+      ? config.site.github
+      : {};
+
+  const merged = {
+    ...DEFAULT_SETTINGS,
+    ...fromConfig,
+    fetch: {
+      ...DEFAULT_SETTINGS.fetch,
+      ...(fromConfig.fetch || {}),
+    },
+    colors: {
+      ...DEFAULT_SETTINGS.colors,
+      ...(fromConfig.colors || {}),
+    },
+  };
+
+  merged.enabled = parseBooleanEnv(process.env.PROJECTS_ENABLED, merged.enabled);
+  merged.cacheDir = process.env.PROJECTS_CACHE_DIR
+    ? String(process.env.PROJECTS_CACHE_DIR)
+    : merged.cacheDir;
+  merged.fetch.timeoutMs = parseIntegerEnv(
+    process.env.PROJECTS_FETCH_TIMEOUT,
+    merged.fetch.timeoutMs
+  );
+  merged.fetch.concurrency = parseIntegerEnv(
+    process.env.PROJECTS_FETCH_CONCURRENCY,
+    merged.fetch.concurrency
+  );
+
+  merged.fetch.timeoutMs = Math.max(1_000, merged.fetch.timeoutMs);
+  merged.fetch.concurrency = Math.max(1, Math.min(10, merged.fetch.concurrency));
+
+  return merged;
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function isGithubRepoUrl(url) {
+  if (!url) return null;
+  try {
+    const u = new URL(String(url));
+    if (u.protocol !== 'https:' && u.protocol !== 'http:') return null;
+    if (u.hostname.toLowerCase() !== 'github.com') return null;
+    const parts = u.pathname.split('/').filter(Boolean);
+    if (parts.length < 2) return null;
+    const owner = parts[0];
+    const repo = parts[1].replace(/\.git$/i, '');
+    if (!owner || !repo) return null;
+    return { owner, repo, canonicalUrl: `https://github.com/${owner}/${repo}` };
+  } catch {
+    return null;
+  }
+}
+
+function collectSitesRecursively(node, output) {
+  if (!node || typeof node !== 'object') return;
+  if (Array.isArray(node.subcategories))
+    node.subcategories.forEach((child) => collectSitesRecursively(child, output));
+  if (Array.isArray(node.groups))
+    node.groups.forEach((child) => collectSitesRecursively(child, output));
+  if (Array.isArray(node.subgroups))
+    node.subgroups.forEach((child) => collectSitesRecursively(child, output));
+  if (Array.isArray(node.sites)) node.sites.forEach((site) => output.push(site));
+}
+
+function findProjectsPages(config) {
+  const pages = [];
+  const nav = Array.isArray(config.navigation) ? config.navigation : [];
+  nav.forEach((item) => {
+    const pageId = item && item.id ? String(item.id) : '';
+    if (!pageId || !config[pageId]) return;
+    const page = config[pageId];
+    const templateName = page && page.template ? String(page.template) : pageId;
+    if (templateName !== 'projects') return;
+    pages.push({ pageId, page });
+  });
+  return pages;
+}
+
+async function fetchJsonWithTimeout(url, { timeoutMs, headers }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(url, { method: 'GET', headers, signal: controller.signal });
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    return await response.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function loadLanguageColors(settings, cacheBaseDir) {
+  const cachePath = path.join(cacheBaseDir, 'github-colors.json');
+
+  try {
+    const stat = fs.existsSync(cachePath) ? fs.statSync(cachePath) : null;
+    if (stat && stat.mtimeMs && Date.now() - stat.mtimeMs < settings.colors.maxAgeMs) {
+      const raw = fs.readFileSync(cachePath, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === 'object') return parsed;
+    }
+  } catch {
+    // 继续联网抓取
+  }
+
+  try {
+    const headers = { 'user-agent': settings.fetch.userAgent, accept: 'application/json' };
+    const colors = await fetchJsonWithTimeout(settings.colors.url, {
+      timeoutMs: settings.fetch.timeoutMs,
+      headers,
+    });
+    if (colors && typeof colors === 'object') {
+      fs.writeFileSync(cachePath, JSON.stringify(colors, null, 2), 'utf8');
+      return colors;
+    }
+  } catch (error) {
+    log.warn('获取语言颜色表失败（将不输出 languageColor）', {
+      message: String(error && error.message ? error.message : error),
+    });
+  }
+
+  return {};
+}
+
+async function fetchRepoMeta(repo, settings, colors) {
+  const headers = {
+    'user-agent': settings.fetch.userAgent,
+    accept: 'application/vnd.github+json',
+  };
+
+  const apiUrl = `https://api.github.com/repos/${repo.owner}/${repo.repo}`;
+  const data = await fetchJsonWithTimeout(apiUrl, { timeoutMs: settings.fetch.timeoutMs, headers });
+
+  const language = data && data.language ? String(data.language) : '';
+  const stars = data && Number.isFinite(data.stargazers_count) ? data.stargazers_count : null;
+  const forks = data && Number.isFinite(data.forks_count) ? data.forks_count : null;
+
+  let languageColor = '';
+  if (language && colors && colors[language] && colors[language].color) {
+    languageColor = String(colors[language].color);
+  }
+
+  return {
+    url: repo.canonicalUrl,
+    fullName: data && data.full_name ? String(data.full_name) : `${repo.owner}/${repo.repo}`,
+    language,
+    languageColor,
+    stars,
+    forks,
+  };
+}
+
+async function runPool(items, concurrency, worker) {
+  const results = [];
+  let index = 0;
+
+  async function runOne() {
+    while (index < items.length) {
+      const current = items[index];
+      index += 1;
+      // eslint-disable-next-line no-await-in-loop
+      const result = await worker(current);
+      if (result) results.push(result);
+    }
+  }
+
+  const runners = Array.from({ length: Math.min(concurrency, items.length) }, () => runOne());
+  await Promise.all(runners);
+  return results;
+}
+
+async function main() {
+  const elapsedMs = startTimer();
+  const config = loadConfig();
+  const settings = getSettings(config);
+
+  log.info('开始');
+
+  if (!settings.enabled) {
+    log.ok('projects 仓库同步已禁用，跳过', { env: 'PROJECTS_ENABLED=false' });
+    return;
+  }
+
+  const cacheBaseDir = path.isAbsolute(settings.cacheDir)
+    ? settings.cacheDir
+    : path.join(process.cwd(), settings.cacheDir);
+  ensureDir(cacheBaseDir);
+
+  const colors = await loadLanguageColors(settings, cacheBaseDir);
+  const pages = findProjectsPages(config);
+
+  if (!pages.length) {
+    log.ok('未找到 template=projects 的页面，跳过同步');
+    return;
+  }
+
+  log.info('准备同步 projects 页面缓存', { pages: pages.length });
+
+  let pageSuccess = 0;
+  let pageFailed = 0;
+
+  for (const { pageId, page } of pages) {
+    const categories = Array.isArray(page.categories) ? page.categories : [];
+    const sites = [];
+    categories.forEach((category) => collectSitesRecursively(category, sites));
+
+    const repos = sites
+      .map((site) => (site && site.url ? isGithubRepoUrl(site.url) : null))
+      .filter(Boolean);
+
+    const unique = new Map();
+    repos.forEach((r) => unique.set(r.canonicalUrl, r));
+    const repoList = Array.from(unique.values());
+
+    if (!repoList.length) {
+      log.ok('页面未发现 GitHub 仓库链接，跳过', { page: pageId });
+      continue;
+    }
+
+    let success = 0;
+    let failed = 0;
+
+    const results = await runPool(repoList, settings.fetch.concurrency, async (repo) => {
+      try {
+        const meta = await fetchRepoMeta(repo, settings, colors);
+        success += 1;
+        return meta;
+      } catch (error) {
+        failed += 1;
+        log.warn('拉取仓库元信息失败（best-effort）', {
+          repo: repo.canonicalUrl,
+          message: String(error && error.message ? error.message : error),
+        });
+        return null;
+      }
+    });
+
+    const payload = {
+      version: '1.0',
+      pageId,
+      generatedAt: new Date().toISOString(),
+      repos: results,
+      stats: {
+        totalRepos: repoList.length,
+        success,
+        failed,
+      },
+    };
+
+    const cachePath = path.join(cacheBaseDir, `${pageId}.repo-cache.json`);
+    fs.writeFileSync(cachePath, JSON.stringify(payload, null, 2), 'utf8');
+
+    if (failed === 0) pageSuccess += 1;
+    else pageFailed += 1;
+
+    log.ok('页面同步完成', {
+      page: pageId,
+      success,
+      failed,
+      cache: cachePath,
+    });
+  }
+
+  log.ok('完成', { ms: elapsedMs(), pages: pages.length, pageSuccess, pageFailed });
+}
+
+main().catch((error) => {
+  log.error('执行异常（best-effort，不阻断后续 build）', {
+    message: error && error.message ? error.message : String(error),
+  });
+  if (isVerbose() && error && error.stack) console.error(error.stack);
+  process.exitCode = 0; // best-effort：不阻断后续 build
+});
diff --git a/scripts/test.js b/scripts/test.js
new file mode 100644
index 0000000000000000000000000000000000000000..a18d19583e2a216cb001ff0cb3081df1d44e7197
--- /dev/null
+++ b/scripts/test.js
@@ -0,0 +1,52 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+const { createLogger, isVerbose, startTimer } = require('../src/generator/utils/logger');
+
+const log = createLogger('test');
+
+function collectTestFiles(repoRoot) {
+  const testDir = path.join(repoRoot, 'test');
+  if (!fs.existsSync(testDir)) return [];
+
+  return fs
+    .readdirSync(testDir)
+    .filter((name) => name.endsWith('.js'))
+    .map((name) => path.join('test', name))
+    .sort();
+}
+
+async function main() {
+  const elapsedMs = startTimer();
+  log.info('开始', { version: process.env.npm_package_version });
+
+  const repoRoot = path.resolve(__dirname, '..');
+  const files = collectTestFiles(repoRoot);
+  if (files.length === 0) {
+    log.ok('未发现测试文件，跳过');
+    return;
+  }
+
+  const result = spawnSync(process.execPath, ['--test', ...files], {
+    cwd: repoRoot,
+    stdio: 'inherit',
+  });
+
+  const exitCode = result && Number.isFinite(result.status) ? result.status : 1;
+  if (exitCode !== 0) {
+    log.error('失败', { ms: elapsedMs(), exit: exitCode });
+    process.exitCode = exitCode;
+    return;
+  }
+
+  log.ok('完成', { ms: elapsedMs(), files: files.length });
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    log.error('执行失败', { message: error && error.message ? error.message : String(error) });
+    if (isVerbose() && error && error.stack) console.error(error.stack);
+    process.exitCode = 1;
+  });
+}
diff --git a/src/README.md b/src/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..81bebf6d29641e90893f308fd56cd7a45c79a840
--- /dev/null
+++ b/src/README.md
@@ -0,0 +1,488 @@
+# MeNav 源代码目录
+
+## 目录
+
+- [架构概述](#架构概述)
+- [目录结构](#目录结构)
+  - [生成端（generator）](#生成端generator)
+  - [运行时（runtime）](#运行时runtime)
+  - [辅助函数（helpers）](#辅助函数helpers)
+- [模块化开发规范](#模块化开发规范)
+  - [职责单一性原则](#职责单一性原则)
+  - [文件大小规范](#文件大小规范)
+  - [命名规范](#命名规范)
+  - [依赖管理](#依赖管理)
+- [开发指南](#开发指南)
+  - [添加新模块](#添加新模块)
+  - [修改现有模块](#修改现有模块)
+  - [测试要求](#测试要求)
+
+## 架构概述
+
+MeNav 采用**模块化架构**，将代码按职责拆分为独立的、可维护的模块。整体分为三个主要部分：
+
+1. **生成端（generator）**：构建期代码，负责将配置转换为静态 HTML
+2. **运行时（runtime）**：浏览器端代码，负责用户交互和动态功能
+3. **辅助函数（helpers）**：Handlebars 模板辅助函数
+
+### 架构原则
+
+- ✅ **职责单一**：每个模块只负责一件事
+- ✅ **高内聚低耦合**：模块内部紧密相关，模块间松散依赖
+- ✅ **可测试性**：每个模块都可以独立测试
+- ✅ **可维护性**：清晰的目录结构和命名规范
+
+## 目录结构
+
+```text
+src/
+├── generator.js              # 生成端薄入口（14行）
+├── generator/                # 生成端实现
+│   ├── main.js              # 主流程控制（301行）
+│   ├── cache/               # 缓存处理
+│   │   ├── articles.js      # 文章缓存（159行）
+│   │   └── projects.js      # 项目缓存（135行）
+│   ├── config/              # 配置管理
+│   │   ├── index.js         # 配置入口（61行）
+│   │   ├── loader.js        # 配置加载（89行）
+│   │   ├── validator.js     # 配置验证（90行）
+│   │   ├── resolver.js      # 配置解析（146行）
+│   │   └── slugs.js         # Slug 生成（43行）
+│   ├── html/                # HTML 生成
+│   │   ├── 404.js           # 404 页面（94行）
+│   │   ├── components.js    # 组件生成（208行）
+│   │   ├── fonts.js         # 字体处理（155行）
+│   │   └── page-data.js     # 页面数据准备（161行）
+│   ├── template/            # 模板引擎
+│   │   └── engine.js        # Handlebars 引擎（120行）
+│   └── utils/               # 工具函数
+│       ├── html.js          # HTML 工具（17行）
+│       ├── pageMeta.js      # 页面元信息（101行）
+│       └── sites.js         # 站点处理（35行）
+├── runtime/                 # 运行时实现
+│   ├── index.js             # 运行时入口（18行）
+│   ├── shared.js            # 共享工具（142行）
+│   ├── tooltip.js           # 提示框（115行）
+│   ├── app/                 # 应用逻辑
+│   │   ├── index.js         # 应用入口（112行）
+│   │   ├── routing.js       # 路由管理（403行）
+│   │   ├── search.js        # 搜索功能（440行）
+│   │   ├── searchEngines.js # 搜索引擎（25行）
+│   │   ├── ui.js            # UI 交互（181行）
+│   │   └── search/
+│   │       └── highlight.js # 搜索高亮（90行）
+│   ├── menav/               # 扩展 API
+│   │   ├── index.js         # API 入口（70行）
+│   │   ├── addElement.js    # 添加元素（351行）
+│   │   ├── updateElement.js # 更新元素（166行）
+│   │   ├── removeElement.js # 删除元素（26行）
+│   │   ├── getAllElements.js# 获取元素（11行）
+│   │   ├── getConfig.js     # 获取配置（25行）
+│   │   └── events.js        # 事件系统（34行）
+│   └── nested/              # 嵌套书签
+│       └── index.js         # 嵌套功能（230行）
+└── helpers/                 # Handlebars 辅助函数
+    ├── index.js             # 辅助函数注册
+    ├── formatters.js        # 格式化函数
+    ├── conditions.js        # 条件判断
+    └── utils.js             # 工具函数
+```
+
+## 生成端（generator）
+
+### 生成端职责
+
+将 YAML 配置文件转换为静态 HTML 网站。
+
+### 生成端核心模块
+
+#### config/ - 配置管理
+
+- **loader.js**：从文件系统加载 YAML 配置
+- **validator.js**：验证配置合法性，填充默认值
+- **resolver.js**：解析配置，准备渲染数据
+- **slugs.js**：为分类生成唯一标识符
+
+#### html/ - HTML 生成
+
+- **page-data.js**：准备页面渲染数据（处理 projects/articles/bookmarks 特殊逻辑）
+- **components.js**：生成导航、分类、社交链接等组件
+- **fonts.js**：处理字体链接和 CSS
+- **404.js**：生成 404 页面
+
+#### cache/ - 缓存处理
+
+- **articles.js**：处理 RSS 文章缓存
+- **projects.js**：处理 GitHub 项目缓存
+
+#### template/ - 模板引擎
+
+- **engine.js**：Handlebars 模板加载和渲染
+
+#### utils/ - 工具函数
+
+- **pageMeta.js**：获取页面元信息（git 时间戳等）
+- **sites.js**：递归收集站点数据
+- **html.js**：HTML 处理工具
+
+### 生成端入口文件
+
+- **generator.js**：薄入口，re-export `generator/main.js`
+- **main.js**：主流程控制，协调各模块完成构建
+
+## 运行时（runtime）
+
+### 运行时职责
+
+在浏览器中提供用户交互功能和扩展 API。
+
+### 运行时核心模块
+
+#### app/ - 应用逻辑
+
+- **routing.js**：页面路由、URL 处理、页面切换
+- **search.js**：搜索索引、搜索逻辑、搜索引擎切换
+- **ui.js**：UI 交互（侧边栏、主题切换、滚动等）
+- **searchEngines.js**：外部搜索引擎配置
+
+#### menav/ - 扩展 API
+
+提供 `window.MeNav` API，供浏览器扩展使用：
+
+- **addElement.js**：添加站点/分类/页面
+- **updateElement.js**：更新元素属性
+- **removeElement.js**：删除元素
+- **getAllElements.js**：获取所有元素
+- **getConfig.js**：获取配置
+- **events.js**：事件系统（on/off/emit）
+
+#### nested/ - 嵌套书签
+
+- **index.js**：嵌套书签功能（展开/折叠/结构管理）
+
+### 运行时入口文件
+
+- **index.js**：运行时入口，初始化所有模块
+- **shared.js**：共享工具函数（URL 校验、class 清洗等）
+- **tooltip.js**：站点卡片悬停提示
+
+### 构建流程
+
+运行时代码通过 `scripts/build-runtime.js` 打包：
+
+- 入口：`src/runtime/index.js`
+- 输出：`dist/script.js`（IIFE 格式，单文件）
+- 工具：esbuild
+
+## 辅助函数（helpers）
+
+### 辅助函数职责
+
+为 Handlebars 模板提供辅助函数。
+
+### 辅助函数模块
+
+- **formatters.js**：日期格式化、文本处理
+- **conditions.js**：条件判断、逻辑运算
+- **utils.js**：数组处理、对象操作、URL 校验
+- **index.js**：注册所有辅助函数到 Handlebars
+
+## 模块化开发规范
+
+### 职责单一性原则
+
+**定义**：一个模块应该只负责一件事情，只有一个改变的理由。
+
+**判断方法**：
+
+1. 能用一句话描述模块职责
+2. 只有一个理由会修改这个模块
+3. 函数/变量名清晰反映职责
+
+**示例**：
+
+✅ **好的拆分**：
+
+```javascript
+// config/loader.js - 只负责加载配置
+function loadModularConfig(dirPath) { /* ... */ }
+
+// config/validator.js - 只负责验证配置
+function validateConfig(config) { /* ... */ }
+
+// config/resolver.js - 只负责解析配置
+function prepareRenderData(config) { /* ... */ }
+```
+
+❌ **不好的拆分**：
+
+```javascript
+// config.js - 职责混杂
+function processConfig(config) {
+  // 加载、验证、解析、转换... 400 行代码
+}
+```
+
+### 文件大小规范
+
+**目标**：
+
+- 源码文件：≤ 500 行
+- 理想大小：100-300 行
+- 入口文件：≤ 100 行（薄入口）
+
+**超过 500 行时**：
+
+1. 检查是否职责混杂
+2. 拆分为多个子模块
+3. 提取可复用的工具函数
+
+**当前状态**：
+
+- 最大文件：440 行（search.js）
+- 平均文件：~130 行
+- 33 个模块文件
+
+### 命名规范
+
+#### 文件命名
+
+- 使用 kebab-case：`page-data.js`、`search-engine.js`
+- 名称反映职责：`loader.js`、`validator.js`、`resolver.js`
+- 入口文件：`index.js`
+
+#### 函数命名
+
+- 使用 camelCase：`loadConfig`、`validateConfig`
+- 动词开头：`get`、`set`、`load`、`validate`、`prepare`
+- 清晰描述功能：`preparePageData`、`assignCategorySlugs`
+
+#### 目录命名
+
+- 使用 kebab-case：`page-data/`、`search-engine/`
+- 名称反映功能域：`config/`、`cache/`、`html/`
+
+### 依赖管理
+
+#### 导入规范
+
+```javascript
+// 1. Node 内置模块
+const fs = require('node:fs');
+const path = require('node:path');
+
+// 2. 第三方依赖
+const yaml = require('js-yaml');
+
+// 3. 项目内部模块（相对路径）
+const { loadConfig } = require('./config');
+const { renderTemplate } = require('./template/engine');
+```
+
+#### 导出规范
+
+```javascript
+// 单个导出
+module.exports = function initSearch(state, dom) { /* ... */ };
+
+// 多个导出
+module.exports = {
+  loadConfig,
+  validateConfig,
+  prepareRenderData,
+};
+```
+
+#### 循环依赖
+
+- ❌ 避免循环依赖
+- ✅ 通过依赖注入解决
+- ✅ 提取共享代码到独立模块
+
+## 开发指南
+
+### 添加新模块
+
+#### 1. 确定模块位置
+
+**生成端**（构建期代码）：
+
+```text
+src/generator/
+├── cache/      # 缓存处理
+├── config/     # 配置管理
+├── html/       # HTML 生成
+├── template/   # 模板引擎
+└── utils/      # 工具函数
+```
+
+**运行时**（浏览器代码）：
+
+```text
+src/runtime/
+├── app/        # 应用逻辑
+├── menav/      # 扩展 API
+└── nested/     # 嵌套书签
+```
+
+#### 2. 创建模块文件
+
+```javascript
+// src/generator/config/new-module.js
+
+/**
+ * 模块描述
+ * @param {Object} param - 参数说明
+ * @returns {Object} 返回值说明
+ */
+function newFunction(param) {
+  // 实现逻辑
+}
+
+module.exports = {
+  newFunction,
+};
+```
+
+#### 3. 更新入口文件
+
+```javascript
+// src/generator/config/index.js
+const { newFunction } = require('./new-module');
+
+module.exports = {
+  // ... 其他导出
+  newFunction,
+};
+```
+
+#### 4. 添加测试
+
+```javascript
+// test/new-module.test.js
+const { newFunction } = require('../src/generator/config/new-module');
+
+test('newFunction 应该...', () => {
+  const result = newFunction(input);
+  expect(result).toBe(expected);
+});
+```
+
+### 修改现有模块
+
+#### 1. 理解模块职责
+
+- 阅读模块注释
+- 查看函数签名
+- 理解依赖关系
+
+#### 2. 保持职责单一
+
+- 不要在模块中添加无关功能
+- 如果功能不匹配，创建新模块
+
+#### 3. 运行测试
+
+```bash
+npm test                    # 运行所有测试
+npm run build              # 验证构建
+```
+
+#### 4. 更新文档
+
+- 更新函数注释
+- 更新 README（如有必要）
+
+### 测试要求
+
+#### 单元测试
+
+- 每个模块都应有对应的测试文件
+- 测试覆盖核心功能路径
+- 使用 Node.js 内置测试框架
+
+#### 集成测试
+
+- 测试模块间的协作
+- 验证构建产物
+- 检查扩展契约
+
+#### 测试命令
+
+```bash
+npm test                    # 运行所有测试
+npm run lint               # 代码检查
+npm run format:check       # 格式检查
+```
+
+## 最佳实践
+
+### 1. 先读后写
+
+- 修改代码前，先用 Read 工具读取文件
+- 理解现有逻辑再进行修改
+
+### 2. 小步迭代
+
+- 每次只改一个模块
+- 改完立即测试
+- 确认无误后再继续
+
+### 3. 保持一致性
+
+- 遵循现有的代码风格
+- 使用相同的命名规范
+- 保持目录结构一致
+
+### 4. 文档同步
+
+- 代码变更时更新注释
+- 重要改动更新 README
+- 保持文档与代码一致
+
+### 5. 测试先行
+
+- 修改前运行测试（确保基线）
+- 修改后运行测试（验证功能）
+- 新功能添加测试（保证质量）
+
+## 常见问题
+
+### Q: 如何判断代码应该放在哪个模块？
+
+**A**: 问自己三个问题：
+
+1. 这段代码的职责是什么？（加载/验证/解析/渲染...）
+2. 它属于哪个功能域？（配置/缓存/HTML/模板...）
+3. 它在构建期还是运行时执行？（generator/runtime）
+
+### Q: 模块太大了怎么办？
+
+**A**: 拆分步骤：
+
+1. 识别模块中的不同职责
+2. 为每个职责创建独立模块
+3. 更新入口文件的导入/导出
+4. 运行测试验证
+
+### Q: 如何避免循环依赖？
+
+**A**: 三种方法：
+
+1. 提取共享代码到独立模块
+2. 使用依赖注入
+3. 重新设计模块边界
+
+### Q: 什么时候应该创建新目录？
+
+**A**: 当满足以下条件时：
+
+1. 有 3 个以上相关模块
+2. 这些模块属于同一功能域
+3. 需要独立的入口文件（index.js）
+
+## 参考资料
+
+- [P2-1 模块化重构文档](../../docs/2025-12-29_修复清单.md#p2-1-文件过大)
+- [职责单一性原则](https://en.wikipedia.org/wiki/Single-responsibility_principle)
+- [Node.js 模块系统](https://nodejs.org/api/modules.html)
diff --git a/src/bookmark-processor.js b/src/bookmark-processor.js
new file mode 100644
index 0000000000000000000000000000000000000000..520ab7b2db3f37c8754838f452eed2050e3287bc
--- /dev/null
+++ b/src/bookmark-processor.js
@@ -0,0 +1,931 @@
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+const { FileError, wrapAsyncError } = require('./generator/utils/errors');
+const { createLogger, isVerbose, startTimer } = require('./generator/utils/logger');
+
+const log = createLogger('import-bookmarks');
+
+// 书签文件夹路径 - 使用相对路径
+const BOOKMARKS_DIR = 'bookmarks';
+// 模块化配置目录
+const CONFIG_USER_DIR = 'config/user';
+// 模块化默认配置目录
+const CONFIG_DEFAULT_DIR = 'config/_default';
+// 模块化页面配置目录
+const CONFIG_USER_PAGES_DIR = path.join(CONFIG_USER_DIR, 'pages');
+// 模块化输出配置文件路径
+const MODULAR_OUTPUT_FILE = path.join(CONFIG_USER_PAGES_DIR, 'bookmarks.yml');
+// 模块化默认书签配置文件路径
+const MODULAR_DEFAULT_BOOKMARKS_FILE = 'config/_default/pages/bookmarks.yml';
+
+const USER_SITE_YML = path.join(CONFIG_USER_DIR, 'site.yml');
+const DEFAULT_SITE_YML = path.join(CONFIG_DEFAULT_DIR, 'site.yml');
+
+function ensureUserConfigInitialized() {
+  if (fs.existsSync(CONFIG_USER_DIR)) {
+    return { initialized: false, source: 'existing' };
+  }
+
+  if (fs.existsSync(CONFIG_DEFAULT_DIR)) {
+    fs.cpSync(CONFIG_DEFAULT_DIR, CONFIG_USER_DIR, { recursive: true });
+    log.info('config/user 不存在，已从 config/_default 初始化用户配置（完全替换策略）');
+    return { initialized: true, source: '_default' };
+  }
+
+  fs.mkdirSync(CONFIG_USER_DIR, { recursive: true });
+  log.warn('未找到 config/_default，已创建空的 config/user；建议补齐 site.yml 与 pages/*.yml');
+  return { initialized: true, source: 'empty' };
+}
+
+function ensureUserSiteYmlExists() {
+  if (fs.existsSync(USER_SITE_YML)) {
+    return true;
+  }
+
+  if (fs.existsSync(DEFAULT_SITE_YML)) {
+    if (!fs.existsSync(CONFIG_USER_DIR)) {
+      fs.mkdirSync(CONFIG_USER_DIR, { recursive: true });
+    }
+    fs.copyFileSync(DEFAULT_SITE_YML, USER_SITE_YML);
+    log.info('未找到 config/user/site.yml，已从 config/_default/site.yml 复制');
+    return true;
+  }
+
+  log.warn(
+    '未找到可用的 site.yml，无法自动更新导航；请在 config/user/site.yml 添加 navigation（含 id: bookmarks）'
+  );
+  return false;
+}
+
+function upsertBookmarksNavInSiteYml(siteYmlPath) {
+  try {
+    const raw = fs.readFileSync(siteYmlPath, 'utf8');
+    const loaded = yaml.load(raw);
+
+    if (!loaded || typeof loaded !== 'object') {
+      return { updated: false, reason: 'site_yml_not_object' };
+    }
+
+    const navigation = loaded.navigation;
+
+    if (Array.isArray(navigation) && navigation.some((item) => item && item.id === 'bookmarks')) {
+      return { updated: false, reason: 'already_present' };
+    }
+
+    if (navigation !== undefined && !Array.isArray(navigation)) {
+      return { updated: false, reason: 'navigation_not_array' };
+    }
+
+    const lines = raw.split(/\r?\n/);
+    const navLineIndex = lines.findIndex((line) => /^navigation\s*:/.test(line));
+
+    const itemIndent = '  ';
+    const propIndent = `${itemIndent}  `;
+    const snippet = [
+      `${itemIndent}- name: 书签`,
+      `${propIndent}icon: fas fa-bookmark`,
+      `${propIndent}id: bookmarks`,
+    ];
+
+    if (navLineIndex === -1) {
+      // 不存在 navigation 段：直接追加一个新的块（尽量不破坏原文件结构）
+      const normalized = raw.endsWith('\n') ? raw : `${raw}\n`;
+      const spacer = normalized.trim().length === 0 ? '' : '\n';
+      const updatedRaw = `${normalized}${spacer}navigation:\n${snippet.join('\n')}\n`;
+      fs.writeFileSync(siteYmlPath, updatedRaw, 'utf8');
+      return { updated: true, reason: 'added_navigation_block' };
+    }
+
+    // 找到 navigation 块末尾（遇到下一个顶层 key 时结束）
+    let insertAt = lines.length;
+    for (let i = navLineIndex + 1; i < lines.length; i++) {
+      const line = lines[i];
+      if (line.trim() === '' || /^\s*#/.test(line)) continue;
+      if (/^[A-Za-z0-9_-]+\s*:/.test(line)) {
+        insertAt = i;
+        break;
+      }
+    }
+
+    const updatedLines = [...lines];
+    // 在块末尾插入，确保块内至少有一个空行分隔更易读
+    if (insertAt > 0 && updatedLines[insertAt - 1].trim() !== '') {
+      snippet.unshift('');
+    }
+    updatedLines.splice(insertAt, 0, ...snippet);
+
+    fs.writeFileSync(siteYmlPath, `${updatedLines.join('\n')}\n`, 'utf8');
+    return { updated: true, reason: 'updated_navigation_block' };
+  } catch (error) {
+    return { updated: false, reason: 'error', error };
+  }
+}
+
+// 图标映射，根据URL关键字匹配合适的图标
+const ICON_MAPPING = {
+  'github.com': 'fab fa-github',
+  'stackoverflow.com': 'fab fa-stack-overflow',
+  'youtube.com': 'fab fa-youtube',
+  'twitter.com': 'fab fa-twitter',
+  'facebook.com': 'fab fa-facebook',
+  'instagram.com': 'fab fa-instagram',
+  'linkedin.com': 'fab fa-linkedin',
+  'reddit.com': 'fab fa-reddit',
+  'amazon.com': 'fab fa-amazon',
+  'google.com': 'fab fa-google',
+  'gmail.com': 'fas fa-envelope',
+  'drive.google.com': 'fab fa-google-drive',
+  'docs.google.com': 'fas fa-file-alt',
+  'medium.com': 'fab fa-medium',
+  'dev.to': 'fab fa-dev',
+  'gitlab.com': 'fab fa-gitlab',
+  'bitbucket.org': 'fab fa-bitbucket',
+  'wikipedia.org': 'fab fa-wikipedia-w',
+  'discord.com': 'fab fa-discord',
+  'slack.com': 'fab fa-slack',
+  'apple.com': 'fab fa-apple',
+  'microsoft.com': 'fab fa-microsoft',
+  'android.com': 'fab fa-android',
+  'twitch.tv': 'fab fa-twitch',
+  'spotify.com': 'fab fa-spotify',
+  'pinterest.com': 'fab fa-pinterest',
+  'telegram.org': 'fab fa-telegram',
+  'whatsapp.com': 'fab fa-whatsapp',
+  'netflix.com': 'fas fa-film',
+  'trello.com': 'fab fa-trello',
+  'wordpress.com': 'fab fa-wordpress',
+  jira: 'fab fa-jira',
+  'atlassian.com': 'fab fa-atlassian',
+  'dropbox.com': 'fab fa-dropbox',
+  npm: 'fab fa-npm',
+  'docker.com': 'fab fa-docker',
+  'python.org': 'fab fa-python',
+  javascript: 'fab fa-js',
+  'php.net': 'fab fa-php',
+  java: 'fab fa-java',
+  'codepen.io': 'fab fa-codepen',
+  'behance.net': 'fab fa-behance',
+  'dribbble.com': 'fab fa-dribbble',
+  'tumblr.com': 'fab fa-tumblr',
+  'vimeo.com': 'fab fa-vimeo',
+  'flickr.com': 'fab fa-flickr',
+  'github.io': 'fab fa-github',
+  'airbnb.com': 'fab fa-airbnb',
+  bitcoin: 'fab fa-bitcoin',
+  'paypal.com': 'fab fa-paypal',
+  ethereum: 'fab fa-ethereum',
+  steam: 'fab fa-steam',
+};
+
+// 获取最新的书签文件
+function getLatestBookmarkFile() {
+  try {
+    // 确保书签目录存在
+    if (!fs.existsSync(BOOKMARKS_DIR)) {
+      fs.mkdirSync(BOOKMARKS_DIR, { recursive: true });
+      log.warn('bookmarks 目录不存在，已创建；未找到 HTML 书签文件', { dir: BOOKMARKS_DIR });
+      return null;
+    }
+
+    // 获取目录中的所有HTML文件
+    const files = fs
+      .readdirSync(BOOKMARKS_DIR)
+      .filter((file) => file.toLowerCase().endsWith('.html'));
+
+    if (files.length === 0) {
+      log.warn('未找到任何 HTML 书签文件', { dir: BOOKMARKS_DIR });
+      return null;
+    }
+
+    // GitHub Actions checkout 会导致文件 mtime 大量相同；改用文件名时间戳优先排序
+    const parseFilenameTimestamp = (filename) => {
+      const base = path.basename(filename);
+
+      // 格式1: selective-bookmarks-2026-01-24T07-31-00.html
+      const isoMatch = base.match(/(\d{4})-(\d{2})-(\d{2})T(\d{2})-(\d{2})-(\d{2})/);
+      if (isoMatch) {
+        const [, year, month, day, hour, minute, second] = isoMatch;
+        return Date.UTC(
+          Number(year),
+          Number(month) - 1,
+          Number(day),
+          Number(hour),
+          Number(minute),
+          Number(second)
+        );
+      }
+
+      // 格式2: bookmarks_20260124.html
+      const dateMatch = base.match(/(\d{4})(\d{2})(\d{2})/);
+      if (dateMatch) {
+        const [, year, month, day] = dateMatch;
+        return Date.UTC(Number(year), Number(month) - 1, Number(day));
+      }
+
+      return 0;
+    };
+
+    // 按文件名时间戳排序，无法解析的使用文件系统 mtime 作为回退
+    const fileStats = files.map((file) => {
+      const filenameTimestamp = parseFilenameTimestamp(file);
+      const mtime = fs.statSync(path.join(BOOKMARKS_DIR, file)).mtime.getTime();
+      return {
+        file,
+        timestamp: filenameTimestamp || mtime,
+      };
+    });
+
+    // 找出最新的文件（时间戳大的在前）；相等时用文件名做稳定排序
+    fileStats.sort((a, b) => b.timestamp - a.timestamp || a.file.localeCompare(b.file));
+
+    const latestFile = fileStats[0].file;
+    const latestFilePath = path.join(BOOKMARKS_DIR, latestFile);
+
+    log.info('选择最新的书签文件', { file: latestFile });
+
+    return latestFilePath;
+  } catch (error) {
+    log.error('查找书签文件时出错', { message: error && error.message ? error.message : error });
+    if (isVerbose() && error && error.stack) console.error(error.stack);
+    return null;
+  }
+}
+
+// 解析书签HTML内容，支持2-4层级嵌套结构
+function parseBookmarks(htmlContent) {
+  // 正则表达式匹配文件夹和书签
+  const folderRegex = /<DT><H3([^>]*)>(.*?)<\/H3>/g;
+  const bookmarkRegex = /<DT><A HREF="([^"]+)"[^>]*>(.*?)<\/A>/g;
+
+  // 储存解析结果
+  const bookmarks = {
+    categories: [],
+  };
+
+  // 提取根路径书签（书签栏容器内但不在任何子文件夹内的书签）
+  function extractRootBookmarks(htmlContent) {
+    // 找到书签栏文件夹标签
+    const bookmarkBarMatch = htmlContent.match(
+      /<DT><H3[^>]*PERSONAL_TOOLBAR_FOLDER[^>]*>([^<]+)<\/H3>/i
+    );
+    if (!bookmarkBarMatch) {
+      return [];
+    }
+    const bookmarkBarStart = bookmarkBarMatch.index + bookmarkBarMatch[0].length;
+
+    // 找到书签栏后面的 <DL><p> 标签
+    const remainingAfterBar = htmlContent.substring(bookmarkBarStart);
+    const dlMatch = remainingAfterBar.match(/<DL><p>/i);
+    if (!dlMatch) {
+      return [];
+    }
+
+    const bookmarkBarContentStart = bookmarkBarStart + dlMatch.index + dlMatch[0].length;
+
+    // 找到书签栏内容的结束位置
+    let depth = 1;
+    let pos = bookmarkBarContentStart;
+    let bookmarkBarContentEnd = htmlContent.length;
+
+    while (pos < htmlContent.length && depth > 0) {
+      const remaining = htmlContent.substring(pos);
+      const dlStartIndex = remaining.search(/<DL><p>/i);
+      const dlEndIndex = remaining.search(/<\/DL><p>/i);
+
+      if (dlStartIndex !== -1 && (dlEndIndex === -1 || dlStartIndex < dlEndIndex)) {
+        depth++;
+        pos += dlStartIndex + '<DL><p>'.length;
+      } else if (dlEndIndex !== -1) {
+        depth--;
+        pos += dlEndIndex;
+        if (depth === 0) {
+          bookmarkBarContentEnd = pos;
+        }
+        pos += '</DL><p>'.length;
+      } else {
+        break;
+      }
+    }
+
+    const bookmarkBarContent = htmlContent.substring(
+      bookmarkBarContentStart,
+      bookmarkBarContentEnd
+    );
+
+    // 现在提取书签栏内所有子文件夹的范围
+    const subfolderRanges = [];
+    const folderRegex = /<DT><H3[^>]*>([^<]+)<\/H3>/g;
+    let folderMatch;
+
+    while ((folderMatch = folderRegex.exec(bookmarkBarContent)) !== null) {
+      const folderName = folderMatch[1].trim();
+      const folderStart = folderMatch.index + folderMatch[0].length;
+
+      // 找到这个文件夹内容的结束位置
+      let folderDepth = 0;
+      let folderPos = folderStart;
+      let folderContentEnd = bookmarkBarContent.length;
+
+      // 跳过空白直到找到 <DL><p>
+      const afterFolder = bookmarkBarContent.substring(folderPos);
+      const folderDLMatch = afterFolder.match(/<DL><p>/i);
+      if (folderDLMatch) {
+        folderDepth = 1;
+        folderPos += folderDLMatch.index + folderDLMatch[0].length;
+
+        while (folderPos < bookmarkBarContent.length && folderDepth > 0) {
+          const remaining = bookmarkBarContent.substring(folderPos);
+          const dlStartIdx = remaining.search(/<DL><p>/i);
+          const dlEndIdx = remaining.search(/<\/DL><p>/i);
+
+          if (dlStartIdx !== -1 && (dlEndIdx === -1 || dlStartIdx < dlEndIdx)) {
+            folderDepth++;
+            folderPos += dlStartIdx + '<DL><p>'.length;
+          } else if (dlEndIdx !== -1) {
+            folderDepth--;
+            folderPos += dlEndIdx;
+            if (folderDepth === 0) {
+              folderContentEnd = folderPos + '</DL><p>'.length;
+            }
+            folderPos += '</DL><p>'.length;
+          } else {
+            break;
+          }
+        }
+
+        subfolderRanges.push({
+          name: folderName,
+          start: folderMatch.index,
+          end: folderContentEnd,
+        });
+      }
+    }
+
+    // 提取不在任何子文件夹范围内的书签
+    const rootSites = [];
+    const bookmarkRegex = /<DT><A HREF="([^"]+)"[^>]*>(.*?)<\/A>/g;
+    let bookmarkMatch;
+
+    while ((bookmarkMatch = bookmarkRegex.exec(bookmarkBarContent)) !== null) {
+      const bookmarkPos = bookmarkMatch.index;
+      const url = bookmarkMatch[1];
+      const name = bookmarkMatch[2].trim();
+
+      // 检查这个书签是否在任何子文件夹范围内
+      let inFolder = false;
+      for (const folder of subfolderRanges) {
+        if (bookmarkPos >= folder.start && bookmarkPos < folder.end) {
+          inFolder = true;
+          break;
+        }
+      }
+
+      if (!inFolder) {
+        // 基于URL选择适当的图标
+        let icon = 'fas fa-link';
+        for (const [keyword, iconClass] of Object.entries(ICON_MAPPING)) {
+          if (url.includes(keyword)) {
+            icon = iconClass;
+            break;
+          }
+        }
+
+        rootSites.push({
+          name: name,
+          url: url,
+          icon: icon,
+          description: '',
+        });
+      }
+    }
+
+    return rootSites;
+  }
+
+  // 递归解析嵌套文件夹
+  function parseNestedFolder(htmlContent, parentPath = [], level = 1) {
+    const folders = [];
+
+    // 第一步：扫描所有文件夹，记录它们的完整范围
+    const folderRanges = [];
+    const scanRegex = /<DT><H3([^>]*)>(.*?)<\/H3>/g;
+    let scanMatch;
+
+    while ((scanMatch = scanRegex.exec(htmlContent)) !== null) {
+      const folderName = scanMatch[2].trim();
+      const folderStart = scanMatch.index;
+      const folderHeaderEnd = scanMatch.index + scanMatch[0].length;
+
+      // 找到文件夹内容的结束位置
+      let depth = 0;
+      let pos = folderHeaderEnd;
+
+      // 跳过空白直到找到 <DL><p>
+      const afterFolder = htmlContent.substring(pos);
+      const folderDLMatch = afterFolder.match(/<DL><p>/i);
+      if (folderDLMatch) {
+        depth = 1;
+        pos += folderDLMatch.index + folderDLMatch[0].length;
+
+        while (pos < htmlContent.length && depth > 0) {
+          const remaining = htmlContent.substring(pos);
+          const dlStartIdx = remaining.search(/<DL><p>/i);
+          const dlEndIdx = remaining.search(/<\/DL><p>/i);
+
+          if (dlStartIdx !== -1 && (dlEndIdx === -1 || dlStartIdx < dlEndIdx)) {
+            depth++;
+            pos += dlStartIdx + '<DL><p>'.length;
+          } else if (dlEndIdx !== -1) {
+            depth--;
+            pos += dlEndIdx;
+            if (depth === 0) {
+              const folderEnd = pos + '</DL><p>'.length;
+              folderRanges.push({
+                name: folderName,
+                start: folderStart,
+                headerEnd: folderHeaderEnd,
+                end: folderEnd,
+              });
+            }
+            pos += '</DL><p>'.length;
+          } else {
+            break;
+          }
+        }
+      }
+    }
+
+    // 第二步：只处理当前层级的文件夹（不在其他文件夹内部的）
+    for (let i = 0; i < folderRanges.length; i++) {
+      const currentFolder = folderRanges[i];
+
+      // 检查这个文件夹是否在其他文件夹内部
+      let isNested = false;
+      for (let j = 0; j < folderRanges.length; j++) {
+        if (i === j) continue; // 跳过自己
+
+        const otherFolder = folderRanges[j];
+        // 如果当前文件夹的起始位置在另一个文件夹的范围内，说明它是嵌套的
+        if (currentFolder.start > otherFolder.start && currentFolder.end <= otherFolder.end) {
+          isNested = true;
+          break;
+        }
+      }
+
+      if (isNested) {
+        continue; // 跳过嵌套的文件夹，它们会被递归调用处理
+      }
+
+      const folderName = currentFolder.name;
+      const folderStart = currentFolder.start;
+      const folderHeaderEnd = currentFolder.headerEnd;
+      const folderEnd = currentFolder.end;
+
+      // 提取文件夹内容（保留完整的HTML结构供递归使用）
+      // 从headerEnd到end之间包含完整的<DL><p>...</DL><p>结构
+      const folderContent = htmlContent.substring(folderHeaderEnd, folderEnd);
+
+      // 验证是否有有效的容器结构
+      if (!/<DL><p>/i.test(folderContent)) {
+        continue;
+      }
+
+      // 解析文件夹内容
+      const folder = {
+        name: folderName,
+        icon: 'fas fa-folder',
+        path: [...parentPath, folderName],
+      };
+
+      // 检查是否包含子文件夹 - 创建新的正则实例避免干扰主循环
+      const testFolderRegex = /<DT><H3([^>]*)>(.*?)<\/H3>/;
+      const hasSubfolders = testFolderRegex.test(folderContent);
+
+      // 先解析当前层级的书签
+      const currentLevelSites = parseSitesInFolder(folderContent, folderName);
+
+      if (hasSubfolders && level < 4) {
+        // 递归解析子文件夹
+        const subfolders = parseNestedFolder(folderContent, folder.path, level + 1);
+
+        // 根据层级深度决定数据结构
+        if (level === 1) {
+          folder.subcategories = subfolders;
+        } else if (level === 2) {
+          folder.groups = subfolders;
+        } else if (level === 3) {
+          folder.subgroups = subfolders;
+        }
+
+        // 添加当前层级的书签（如果有）
+        if (currentLevelSites.length > 0) {
+          folder.sites = currentLevelSites;
+        }
+      } else {
+        // 解析书签
+        folder.sites = currentLevelSites;
+      }
+
+      // 只添加包含内容的文件夹
+      const hasContent =
+        (folder.sites && folder.sites.length > 0) ||
+        (folder.subcategories && folder.subcategories.length > 0) ||
+        (folder.groups && folder.groups.length > 0) ||
+        (folder.subgroups && folder.subgroups.length > 0);
+
+      if (hasContent) {
+        folders.push(folder);
+      }
+    }
+
+    return folders;
+  }
+
+  // 解析文件夹中的书签（仅当前层级，排除子文件夹内的书签）
+  function parseSitesInFolder(folderContent) {
+    const sites = [];
+    let siteCount = 0;
+
+    // 首先找到所有子文件夹的范围
+    const subfolderRanges = [];
+    const folderRegex = /<DT><H3[^>]*>([^<]+)<\/H3>/g;
+    let folderMatch;
+
+    while ((folderMatch = folderRegex.exec(folderContent)) !== null) {
+      const folderName = folderMatch[1].trim();
+      const folderStart = folderMatch.index;
+      const folderHeaderEnd = folderMatch.index + folderMatch[0].length;
+
+      // 找到这个文件夹内容的结束位置
+      let folderDepth = 0;
+      let folderPos = folderHeaderEnd;
+      let folderContentEnd = folderContent.length;
+
+      // 跳过空白直到找到 <DL><p>
+      const afterFolder = folderContent.substring(folderPos);
+      const folderDLMatch = afterFolder.match(/<DL><p>/i);
+      if (folderDLMatch) {
+        folderDepth = 1;
+        folderPos += folderDLMatch.index + folderDLMatch[0].length;
+
+        while (folderPos < folderContent.length && folderDepth > 0) {
+          const remaining = folderContent.substring(folderPos);
+          const dlStartIdx = remaining.search(/<DL><p>/i);
+          const dlEndIdx = remaining.search(/<\/DL><p>/i);
+
+          if (dlStartIdx !== -1 && (dlEndIdx === -1 || dlStartIdx < dlEndIdx)) {
+            folderDepth++;
+            folderPos += dlStartIdx + '<DL><p>'.length;
+          } else if (dlEndIdx !== -1) {
+            folderDepth--;
+            folderPos += dlEndIdx;
+            if (folderDepth === 0) {
+              folderContentEnd = folderPos + '</DL><p>'.length;
+            }
+            folderPos += '</DL><p>'.length;
+          } else {
+            break;
+          }
+        }
+
+        subfolderRanges.push({
+          name: folderName,
+          start: folderStart,
+          end: folderContentEnd,
+        });
+      }
+    }
+
+    // 现在提取不在任何子文件夹范围内的书签
+    const bookmarkRegex = /<DT><A HREF="([^"]+)"[^>]*>(.*?)<\/A>/g;
+    let bookmarkMatch;
+
+    while ((bookmarkMatch = bookmarkRegex.exec(folderContent)) !== null) {
+      const bookmarkPos = bookmarkMatch.index;
+      const url = bookmarkMatch[1];
+      const name = bookmarkMatch[2].trim();
+
+      // 检查这个书签是否在任何子文件夹范围内
+      let inSubfolder = false;
+      for (const folder of subfolderRanges) {
+        if (bookmarkPos >= folder.start && bookmarkPos < folder.end) {
+          inSubfolder = true;
+          break;
+        }
+      }
+
+      if (!inSubfolder) {
+        // 基于URL选择适当的图标
+        let icon = 'fas fa-link'; // 默认图标
+        for (const [keyword, iconClass] of Object.entries(ICON_MAPPING)) {
+          if (url.includes(keyword)) {
+            icon = iconClass;
+            break;
+          }
+        }
+
+        sites.push({
+          name: name,
+          url: url,
+          icon: icon,
+          description: '',
+        });
+      }
+    }
+
+    return sites;
+  }
+
+  // 开始解析
+  const rootSites = extractRootBookmarks(htmlContent);
+
+  // 找到书签栏文件夹（PERSONAL_TOOLBAR_FOLDER）
+  const bookmarkBarMatch = htmlContent.match(
+    /<DT><H3[^>]*PERSONAL_TOOLBAR_FOLDER[^>]*>([^<]+)<\/H3>/i
+  );
+  if (!bookmarkBarMatch) {
+    log.warn('未找到书签栏文件夹（PERSONAL_TOOLBAR_FOLDER），使用备用方案');
+    // 备用方案：使用第一个 <DL><p> 标签
+    const firstDLMatch = htmlContent.match(/<DL><p>/i);
+    if (!firstDLMatch) {
+      log.error('未找到任何书签容器');
+      bookmarks.categories = [];
+    } else {
+      const dlStart = firstDLMatch.index + firstDLMatch[0].length;
+      let dlEnd = htmlContent.length;
+      let depth = 1;
+      let pos = dlStart;
+
+      while (pos < htmlContent.length && depth > 0) {
+        const remainingContent = htmlContent.substring(pos);
+        const dlStartIndex = remainingContent.search(/<DL><p>/i);
+        const dlEndIndex = remainingContent.search(/<\/DL><p>/i);
+
+        if (dlStartIndex !== -1 && (dlEndIndex === -1 || dlStartIndex < dlEndIndex)) {
+          depth++;
+          pos += dlStartIndex + '<DL><p>'.length;
+        } else if (dlEndIndex !== -1) {
+          depth--;
+          pos += dlEndIndex + '</DL><p>'.length;
+        } else {
+          break;
+        }
+      }
+
+      dlEnd = pos - '</DL><p>'.length;
+      const bookmarksBarContent = htmlContent.substring(dlStart, dlEnd);
+      bookmarks.categories = parseNestedFolder(bookmarksBarContent);
+    }
+  } else {
+    const bookmarkBarStart = bookmarkBarMatch.index + bookmarkBarMatch[0].length;
+
+    // 找到书签栏后面的 <DL><p> 标签
+    const remainingAfterBar = htmlContent.substring(bookmarkBarStart);
+    const dlMatch = remainingAfterBar.match(/<DL><p>/i);
+    if (!dlMatch) {
+      log.error('未找到书签栏的内容容器 <DL><p>');
+      bookmarks.categories = [];
+    } else {
+      const bookmarkBarContentStart = bookmarkBarStart + dlMatch.index + dlMatch[0].length;
+
+      // 找到书签栏内容的结束位置
+      let depth = 1;
+      let pos = bookmarkBarContentStart;
+      let bookmarkBarContentEnd = htmlContent.length;
+
+      while (pos < htmlContent.length && depth > 0) {
+        const remaining = htmlContent.substring(pos);
+        const dlStartIndex = remaining.search(/<DL><p>/i);
+        const dlEndIndex = remaining.search(/<\/DL><p>/i);
+
+        if (dlStartIndex !== -1 && (dlEndIndex === -1 || dlStartIndex < dlEndIndex)) {
+          depth++;
+          pos += dlStartIndex + '<DL><p>'.length;
+        } else if (dlEndIndex !== -1) {
+          depth--;
+          pos += dlEndIndex;
+          if (depth === 0) {
+            bookmarkBarContentEnd = pos;
+          }
+          pos += '</DL><p>'.length;
+        } else {
+          break;
+        }
+      }
+
+      const bookmarkBarContent = htmlContent.substring(
+        bookmarkBarContentStart,
+        bookmarkBarContentEnd
+      );
+
+      // 解析书签栏内的子文件夹作为顶层分类（跳过书签栏本身）
+      bookmarks.categories = parseNestedFolder(bookmarkBarContent);
+    }
+  }
+
+  log.info('解析完成', { categories: bookmarks.categories.length });
+
+  // 如果存在根路径书签，创建"根目录书签"特殊分类并插入到首位
+  if (rootSites.length > 0) {
+    log.info('创建"根目录书签"特殊分类', { sites: rootSites.length });
+    const rootCategory = {
+      name: '根目录书签',
+      icon: 'fas fa-star',
+      path: ['根目录书签'],
+      sites: rootSites,
+    };
+
+    // 插入到数组首位
+    bookmarks.categories.unshift(rootCategory);
+    log.info('"根目录书签"已插入到分类列表首位');
+  }
+
+  return bookmarks;
+}
+
+// 生成YAML配置
+function generateBookmarksYaml(bookmarks) {
+  try {
+    // 创建书签页面配置
+    const bookmarksPage = {
+      title: '我的书签',
+      subtitle: '从浏览器导入的书签收藏',
+      categories: bookmarks.categories,
+    };
+
+    // 转换为YAML
+    const yamlString = yaml.dump(bookmarksPage, {
+      indent: 2,
+      lineWidth: -1,
+      quotingType: '"',
+    });
+
+    // 添加注释（可选确定性输出，方便版本管理）
+    const deterministic = process.env.MENAV_BOOKMARKS_DETERMINISTIC === '1';
+    const timestampLine = deterministic
+      ? ''
+      : `# 由bookmark-processor.js生成于 ${new Date().toISOString()}\n`;
+
+    const yamlWithComment = `# 自动生成的书签配置文件
+${timestampLine}# 若要更新，请将新的书签HTML文件放入bookmarks/目录
+# 此文件使用模块化配置格式，位于config/user/pages/目录下
+
+${yamlString}`;
+
+    return yamlWithComment;
+  } catch (error) {
+    log.error('生成 YAML 失败', {
+      message: error && error.message ? error.message : String(error),
+    });
+    if (isVerbose() && error && error.stack) console.error(error.stack);
+    return null;
+  }
+}
+
+// 更新导航以包含书签页面
+function updateNavigationWithBookmarks() {
+  // 1) 优先更新 site.yml（当前推荐方式）
+  if (ensureUserSiteYmlExists()) {
+    const result = upsertBookmarksNavInSiteYml(USER_SITE_YML);
+    if (result.updated) {
+      return { updated: true, target: 'site.yml', reason: result.reason };
+    }
+    if (result.reason === 'already_present') {
+      return { updated: false, target: 'site.yml', reason: 'already_present' };
+    }
+    if (result.reason === 'error') {
+      return { updated: false, target: 'site.yml', reason: 'error', error: result.error };
+    }
+    return { updated: false, target: 'site.yml', reason: result.reason };
+  }
+  return { updated: false, target: null, reason: 'no_site_yml' };
+}
+
+// 主函数
+async function main() {
+  const elapsedMs = startTimer();
+  log.info('开始', { version: process.env.npm_package_version });
+
+  // 获取最新的书签文件
+  log.info('查找书签文件', { dir: BOOKMARKS_DIR });
+  const bookmarkFile = getLatestBookmarkFile();
+  if (!bookmarkFile) {
+    log.ok('未找到书签文件，跳过', { dir: BOOKMARKS_DIR });
+    return;
+  }
+  log.ok('找到书签文件', { file: bookmarkFile });
+
+  try {
+    // 读取文件内容
+    log.info('读取书签文件', { file: bookmarkFile });
+    const htmlContent = fs.readFileSync(bookmarkFile, 'utf8');
+    log.ok('读取成功', { chars: htmlContent.length });
+
+    // 解析书签
+    log.info('解析书签结构');
+    const bookmarks = parseBookmarks(htmlContent);
+    if (bookmarks.categories.length === 0) {
+      log.error('HTML 文件中未找到书签分类，处理终止');
+      return;
+    }
+    log.ok('解析完成', { categories: bookmarks.categories.length });
+
+    // 生成YAML
+    log.info('生成 YAML 配置');
+    const yamlContent = generateBookmarksYaml(bookmarks);
+    if (!yamlContent) {
+      log.error('YAML 生成失败，处理终止');
+      return;
+    }
+    log.ok('YAML 生成成功');
+
+    // 保存文件
+    log.info('写入配置文件', { path: MODULAR_OUTPUT_FILE });
+    try {
+      // 完全替换策略：若尚未初始化用户配置，则先从默认配置初始化一份完整配置
+      ensureUserConfigInitialized();
+
+      // 确保目标目录存在
+      if (!fs.existsSync(CONFIG_USER_PAGES_DIR)) {
+        fs.mkdirSync(CONFIG_USER_PAGES_DIR, { recursive: true });
+      }
+
+      // 保存YAML到模块化位置
+      fs.writeFileSync(MODULAR_OUTPUT_FILE, yamlContent, 'utf8');
+
+      // 验证文件是否确实被创建
+      if (!fs.existsSync(MODULAR_OUTPUT_FILE)) {
+        throw new FileError('文件未能创建', MODULAR_OUTPUT_FILE, [
+          '检查目录权限是否正确',
+          '确认磁盘空间是否充足',
+          '尝试手动创建目录: mkdir -p config/user/pages',
+        ]);
+      }
+
+      log.ok('写入成功', { path: MODULAR_OUTPUT_FILE });
+
+      // 更新导航
+      log.info('更新导航配置（确保包含 bookmarks 入口）');
+      const navUpdateResult = updateNavigationWithBookmarks();
+      if (navUpdateResult.updated) {
+        log.ok('导航配置已更新', {
+          target: navUpdateResult.target,
+          reason: navUpdateResult.reason,
+        });
+      } else if (navUpdateResult.reason === 'already_present') {
+        log.ok('导航配置已包含书签入口，无需更新', { target: navUpdateResult.target });
+      } else if (navUpdateResult.reason === 'no_site_yml') {
+        log.warn('未找到可用的 site.yml，无法自动更新导航', { path: USER_SITE_YML });
+      } else if (navUpdateResult.reason === 'navigation_not_array') {
+        log.warn('site.yml 中 navigation 不是数组，无法自动更新导航', { path: USER_SITE_YML });
+      } else if (navUpdateResult.reason === 'error') {
+        log.warn('导航更新失败，请手动检查配置文件格式（详见错误信息）');
+        if (navUpdateResult.error) {
+          log.warn('导航更新错误详情', {
+            message: navUpdateResult.error.message
+              ? navUpdateResult.error.message
+              : String(navUpdateResult.error),
+          });
+          if (isVerbose() && navUpdateResult.error.stack)
+            console.error(navUpdateResult.error.stack);
+        }
+      } else {
+        log.info('导航配置无需更新', { reason: navUpdateResult.reason });
+      }
+    } catch (writeError) {
+      throw new FileError('写入文件时出错', MODULAR_OUTPUT_FILE, [
+        '检查文件路径是否正确',
+        '确认目录权限是否正确',
+        `错误详情: ${writeError.message}`,
+      ]);
+    }
+
+    log.ok('完成', { ms: elapsedMs(), output: MODULAR_OUTPUT_FILE });
+  } catch (error) {
+    // 如果是自定义错误，直接抛出
+    if (error instanceof FileError) {
+      throw error;
+    }
+    // 否则包装为 FileError
+    throw new FileError('处理书签文件时发生错误', null, [
+      '检查书签 HTML 文件格式是否正确',
+      '确认配置目录结构是否完整',
+      `错误详情: ${error.message}`,
+    ]);
+  }
+}
+
+// 启动处理
+if (require.main === module) {
+  wrapAsyncError(main)();
+}
+
+module.exports = {
+  ensureUserConfigInitialized,
+  ensureUserSiteYmlExists,
+  upsertBookmarksNavInSiteYml,
+  parseBookmarks,
+  generateBookmarksYaml,
+  updateNavigationWithBookmarks,
+};
diff --git a/src/generator.js b/src/generator.js
new file mode 100644
index 0000000000000000000000000000000000000000..7213ed1421255a2d6dc2fea24cef0742f25c4f02
--- /dev/null
+++ b/src/generator.js
@@ -0,0 +1,14 @@
+// 生成端薄入口：保持对外导出稳定，内部实现位于 src/generator/main.js
+const impl = require('./generator/main');
+const { wrapAsyncError } = require('./generator/utils/errors');
+
+module.exports = impl;
+
+if (require.main === module) {
+  if (typeof impl.main === 'function') {
+    wrapAsyncError(impl.main)();
+  } else {
+    console.error('generator main() 未导出，无法直接执行。');
+    process.exitCode = 1;
+  }
+}
diff --git a/src/generator/cache/articles.js b/src/generator/cache/articles.js
new file mode 100644
index 0000000000000000000000000000000000000000..bd328f7fe3bd4afea04577968d210bee661362f8
--- /dev/null
+++ b/src/generator/cache/articles.js
@@ -0,0 +1,161 @@
+const fs = require('fs');
+const path = require('path');
+
+const { collectSitesRecursively, normalizeUrlKey } = require('../utils/sites');
+const { createLogger } = require('../utils/logger');
+
+const log = createLogger('cache:articles');
+
+/**
+ * 读取 articles 页面 RSS 缓存（Phase 2）
+ * - 缓存默认放在 dev/（仓库默认 gitignore）
+ * - 构建端只读缓存：缓存缺失/损坏时回退到 Phase 1（渲染来源站点分类）
+ * @param {string} pageId 页面ID（用于支持多个 articles 页面的独立缓存）
+ * @param {Object} config 全站配置（用于读取 site.rss.cacheDir）
+ * @returns {{items: Array<Object>, meta: Object}|null}
+ */
+function tryLoadArticlesFeedCache(pageId, config) {
+  if (!pageId) return null;
+
+  const cacheDirFromEnv = process.env.RSS_CACHE_DIR ? String(process.env.RSS_CACHE_DIR) : '';
+  const cacheDirFromConfig =
+    config && config.site && config.site.rss && config.site.rss.cacheDir
+      ? String(config.site.rss.cacheDir)
+      : '';
+  const cacheDir = cacheDirFromEnv || cacheDirFromConfig || 'dev';
+
+  const cacheBaseDir = path.isAbsolute(cacheDir) ? cacheDir : path.join(process.cwd(), cacheDir);
+  const cachePath = path.join(cacheBaseDir, `${pageId}.feed-cache.json`);
+  if (!fs.existsSync(cachePath)) return null;
+
+  try {
+    const raw = fs.readFileSync(cachePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+
+    const articles = Array.isArray(parsed.articles) ? parsed.articles : [];
+    const items = articles
+      .map((a) => {
+        const title = a && a.title ? String(a.title) : '';
+        const url = a && a.url ? String(a.url) : '';
+        if (!title || !url) return null;
+
+        return {
+          // 兼容 site-card partial 字段
+          name: title,
+          url,
+          icon: a && a.icon ? String(a.icon) : 'fas fa-pen',
+          description: a && a.summary ? String(a.summary) : '',
+
+          // Phase 2 文章元信息（只读展示）
+          publishedAt: a && a.publishedAt ? String(a.publishedAt) : '',
+          source: a && a.source ? String(a.source) : '',
+          // 文章来源站点首页 URL（用于按分类聚合展示；旧缓存可能缺失）
+          sourceUrl: a && a.sourceUrl ? String(a.sourceUrl) : '',
+
+          // 文章链接通常应在新标签页打开
+          external: true,
+        };
+      })
+      .filter(Boolean);
+
+    return {
+      items,
+      meta: {
+        pageId: parsed.pageId || pageId,
+        generatedAt: parsed.generatedAt || '',
+        total:
+          parsed.stats && Number.isFinite(parsed.stats.totalArticles)
+            ? parsed.stats.totalArticles
+            : items.length,
+      },
+    };
+  } catch (e) {
+    log.warn('articles 缓存读取失败，将回退 Phase 1', { path: cachePath });
+    return null;
+  }
+}
+
+/**
+ * articles Phase 2：按页面配置的“分类”聚合文章展示
+ * - 规则：某篇文章的 sourceUrl/source 归属到其来源站点（pages/articles.yml 中配置的站点）所在的分类
+ * - 兼容：旧缓存缺少 sourceUrl 时回退使用 source（站点名称）匹配
+ * @param {Array<Object>} categories 页面配置 categories（可包含更深层级）
+ * @param {Array<Object>} articlesItems Phase 2 文章条目（来自缓存）
+ * @returns {Array<{name: string, icon: string, items: Array<Object>}>}
+ */
+function buildArticlesCategoriesByPageCategories(categories, articlesItems) {
+  const safeItems = Array.isArray(articlesItems) ? articlesItems : [];
+  const safeCategories = Array.isArray(categories) ? categories : [];
+
+  // 若页面未配置分类，则回退为单一分类容器
+  if (safeCategories.length === 0) {
+    return [
+      {
+        name: '最新文章',
+        icon: 'fas fa-rss',
+        items: safeItems,
+      },
+    ];
+  }
+
+  const categoryIndex = safeCategories.map((category) => {
+    const sites = [];
+    collectSitesRecursively(category, sites);
+
+    const siteUrlKeys = new Set();
+    const siteNameKeys = new Set();
+    sites.forEach((site) => {
+      const urlKey = normalizeUrlKey(site && site.url ? String(site.url) : '');
+      if (urlKey) siteUrlKeys.add(urlKey);
+      const nameKey = site && site.name ? String(site.name).trim().toLowerCase() : '';
+      if (nameKey) siteNameKeys.add(nameKey);
+    });
+
+    return { category, siteUrlKeys, siteNameKeys };
+  });
+
+  const buckets = categoryIndex.map(() => []);
+  const uncategorized = [];
+
+  safeItems.forEach((item) => {
+    const sourceUrlKey = normalizeUrlKey(item && item.sourceUrl ? String(item.sourceUrl) : '');
+    const sourceNameKey = item && item.source ? String(item.source).trim().toLowerCase() : '';
+
+    let matchedIndex = -1;
+    if (sourceUrlKey) {
+      matchedIndex = categoryIndex.findIndex((idx) => idx.siteUrlKeys.has(sourceUrlKey));
+    }
+    if (matchedIndex < 0 && sourceNameKey) {
+      matchedIndex = categoryIndex.findIndex((idx) => idx.siteNameKeys.has(sourceNameKey));
+    }
+
+    if (matchedIndex < 0) {
+      uncategorized.push(item);
+      return;
+    }
+
+    buckets[matchedIndex].push(item);
+  });
+
+  const displayCategories = categoryIndex.map((idx, i) => ({
+    name: idx.category && idx.category.name ? String(idx.category.name) : '未命名分类',
+    icon: idx.category && idx.category.icon ? String(idx.category.icon) : 'fas fa-rss',
+    items: buckets[i],
+  }));
+
+  if (uncategorized.length > 0) {
+    displayCategories.push({
+      name: '其他',
+      icon: 'fas fa-ellipsis-h',
+      items: uncategorized,
+    });
+  }
+
+  return displayCategories;
+}
+
+module.exports = {
+  tryLoadArticlesFeedCache,
+  buildArticlesCategoriesByPageCategories,
+};
diff --git a/src/generator/cache/projects.js b/src/generator/cache/projects.js
new file mode 100644
index 0000000000000000000000000000000000000000..86e36da7552b0398f8c03a2e59fec62abb93c0ee
--- /dev/null
+++ b/src/generator/cache/projects.js
@@ -0,0 +1,181 @@
+const fs = require('fs');
+const path = require('path');
+
+const { createLogger } = require('../utils/logger');
+
+const log = createLogger('cache:projects');
+
+function tryLoadProjectsHeatmapCache(pageId, config) {
+  if (!pageId) return null;
+
+  const cacheDirFromEnv = process.env.PROJECTS_CACHE_DIR
+    ? String(process.env.PROJECTS_CACHE_DIR)
+    : '';
+  const cacheDirFromConfig =
+    config && config.site && config.site.github && config.site.github.cacheDir
+      ? String(config.site.github.cacheDir)
+      : '';
+  const cacheDir = cacheDirFromEnv || cacheDirFromConfig || 'dev';
+
+  const cacheBaseDir = path.isAbsolute(cacheDir) ? cacheDir : path.join(process.cwd(), cacheDir);
+  const cachePath = path.join(cacheBaseDir, `${pageId}.heatmap-cache.json`);
+  if (!fs.existsSync(cachePath)) return null;
+
+  try {
+    const raw = fs.readFileSync(cachePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+
+    const username = parsed.username ? String(parsed.username).trim() : '';
+    const html = parsed.html ? String(parsed.html) : '';
+    if (!username || !html) return null;
+
+    return {
+      username,
+      html,
+      meta: {
+        pageId: parsed.pageId || pageId,
+        generatedAt: parsed.generatedAt || '',
+        sourceUrl: parsed.sourceUrl || '',
+      },
+    };
+  } catch (e) {
+    log.warn('heatmap 缓存读取失败，将降级为运行时加载', { path: cachePath });
+    return null;
+  }
+}
+
+function tryLoadProjectsRepoCache(pageId, config) {
+  if (!pageId) return null;
+
+  const cacheDirFromEnv = process.env.PROJECTS_CACHE_DIR
+    ? String(process.env.PROJECTS_CACHE_DIR)
+    : '';
+  const cacheDirFromConfig =
+    config && config.site && config.site.github && config.site.github.cacheDir
+      ? String(config.site.github.cacheDir)
+      : '';
+  const cacheDir = cacheDirFromEnv || cacheDirFromConfig || 'dev';
+
+  const cacheBaseDir = path.isAbsolute(cacheDir) ? cacheDir : path.join(process.cwd(), cacheDir);
+  const cachePath = path.join(cacheBaseDir, `${pageId}.repo-cache.json`);
+  if (!fs.existsSync(cachePath)) return null;
+
+  try {
+    const raw = fs.readFileSync(cachePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object') return null;
+
+    const repos = Array.isArray(parsed.repos) ? parsed.repos : [];
+    const map = new Map();
+    repos.forEach((r) => {
+      const url = r && r.url ? String(r.url) : '';
+      if (!url) return;
+      map.set(url, {
+        language: r && r.language ? String(r.language) : '',
+        languageColor: r && r.languageColor ? String(r.languageColor) : '',
+        stars: Number.isFinite(r && r.stars) ? r.stars : null,
+        forks: Number.isFinite(r && r.forks) ? r.forks : null,
+      });
+    });
+
+    return {
+      map,
+      meta: {
+        pageId: parsed.pageId || pageId,
+        generatedAt: parsed.generatedAt || '',
+      },
+    };
+  } catch (e) {
+    log.warn('projects 缓存读取失败，将仅展示标题与描述', { path: cachePath });
+    return null;
+  }
+}
+
+function normalizeGithubRepoUrl(url) {
+  if (!url) return '';
+  try {
+    const u = new URL(String(url));
+    if (u.hostname.toLowerCase() !== 'github.com') return '';
+    const parts = u.pathname.split('/').filter(Boolean);
+    if (parts.length < 2) return '';
+    const owner = parts[0];
+    const repo = parts[1].replace(/\\.git$/i, '');
+    if (!owner || !repo) return '';
+    return `https://github.com/${owner}/${repo}`;
+  } catch {
+    return '';
+  }
+}
+
+function applyRepoMetaToCategories(categories, repoMetaMap) {
+  if (!Array.isArray(categories) || !(repoMetaMap instanceof Map)) return;
+
+  const walk = (node) => {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node.subcategories)) node.subcategories.forEach(walk);
+    if (Array.isArray(node.groups)) node.groups.forEach(walk);
+    if (Array.isArray(node.subgroups)) node.subgroups.forEach(walk);
+
+    if (Array.isArray(node.sites)) {
+      node.sites.forEach((site) => {
+        if (!site || typeof site !== 'object' || !site.url) return;
+        const canonical = normalizeGithubRepoUrl(site.url);
+        if (!canonical) return;
+        const meta = repoMetaMap.get(canonical);
+        if (!meta) return;
+
+        site.language = meta.language || '';
+        site.languageColor = meta.languageColor || '';
+        site.stars = meta.stars;
+        site.forks = meta.forks;
+      });
+    }
+  };
+
+  categories.forEach(walk);
+}
+
+function normalizeGithubHeatmapColor(input) {
+  const raw = String(input || '')
+    .trim()
+    .replace(/^#/, '');
+  const color = raw.toLowerCase();
+  if (/^[0-9a-f]{6}$/.test(color)) return color;
+  if (/^[0-9a-f]{3}$/.test(color)) return color;
+  return '339af0';
+}
+
+function getGithubUsernameFromConfig(config) {
+  const username =
+    config && config.site && config.site.github && config.site.github.username
+      ? String(config.site.github.username).trim()
+      : '';
+  return username;
+}
+
+function buildProjectsMeta(config) {
+  const username = getGithubUsernameFromConfig(config);
+  if (!username) return null;
+
+  const color = normalizeGithubHeatmapColor(
+    config && config.site && config.site.github && config.site.github.heatmapColor
+      ? config.site.github.heatmapColor
+      : '339af0'
+  );
+
+  return {
+    heatmap: {
+      username,
+      profileUrl: `https://github.com/${username}`,
+      imageUrl: `https://ghchart.rshah.org/${color}/${username}`,
+    },
+  };
+}
+
+module.exports = {
+  tryLoadProjectsRepoCache,
+  tryLoadProjectsHeatmapCache,
+  applyRepoMetaToCategories,
+  buildProjectsMeta,
+};
diff --git a/src/generator/config/index.js b/src/generator/config/index.js
new file mode 100644
index 0000000000000000000000000000000000000000..46f35f2e9100a969633a32e902c1e8d41c150fee
--- /dev/null
+++ b/src/generator/config/index.js
@@ -0,0 +1,71 @@
+const fs = require('node:fs');
+const { loadModularConfig } = require('./loader');
+const { ensureConfigDefaults, validateConfig } = require('./validator');
+const {
+  prepareRenderData,
+  MENAV_EXTENSION_CONFIG_FILE,
+  getSubmenuForNavItem,
+  resolveTemplateNameForPage,
+  buildExtensionConfig,
+} = require('./resolver');
+const { assignCategorySlugs } = require('./slugs');
+const { ConfigError } = require('../utils/errors');
+const { createLogger } = require('../utils/logger');
+
+const log = createLogger('config');
+
+function loadConfig() {
+  let config = {
+    site: {},
+    navigation: [],
+    fonts: {},
+    profile: {},
+    social: [],
+  };
+
+  const hasUserModularConfig = fs.existsSync('config/user');
+  const hasDefaultModularConfig = fs.existsSync('config/_default');
+
+  if (hasUserModularConfig) {
+    if (!fs.existsSync('config/user/site.yml')) {
+      throw new ConfigError('检测到 config/user/ 目录，但缺少 config/user/site.yml', [
+        '由于配置采用"完全替换"策略，系统不会从 config/_default/ 补齐缺失配置',
+        '解决方法：先完整复制 config/_default/ 到 config/user/，再按需修改',
+        '参考文档: config/README.md',
+      ]);
+    }
+
+    if (!fs.existsSync('config/user/pages')) {
+      log.warn('检测到 config/user/pages/ 缺失，部分页面内容可能为空');
+      log.warn('建议复制 config/_default/pages/ 到 config/user/pages/，再按需修改');
+    }
+
+    config = loadModularConfig('config/user');
+  } else if (hasDefaultModularConfig) {
+    config = loadModularConfig('config/_default');
+  } else {
+    throw new ConfigError('未找到可用配置：缺少 config/user/ 或 config/_default/', [
+      '本版本已不再支持旧版单文件配置（config.yml / config.yaml）',
+      '解决方法：使用模块化配置目录（建议从 config/_default/ 复制到 config/user/ 再修改）',
+      '参考文档: config/README.md',
+    ]);
+  }
+
+  config = ensureConfigDefaults(config);
+
+  if (!validateConfig(config)) {
+    // 保留函数调用
+  }
+
+  return prepareRenderData(config);
+}
+
+module.exports = {
+  MENAV_EXTENSION_CONFIG_FILE,
+  loadConfig,
+  prepareRenderData,
+  resolveTemplateNameForPage,
+  buildExtensionConfig,
+  getSubmenuForNavItem,
+  assignCategorySlugs,
+};
diff --git a/src/generator/config/loader.js b/src/generator/config/loader.js
new file mode 100644
index 0000000000000000000000000000000000000000..9ce71c1b2b9fec482df66941fce98f12d4f02029
--- /dev/null
+++ b/src/generator/config/loader.js
@@ -0,0 +1,97 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const yaml = require('js-yaml');
+
+const { createLogger, isVerbose } = require('../utils/logger');
+
+const log = createLogger('config');
+
+function handleConfigLoadError(filePath, error) {
+  log.error('加载配置失败', {
+    path: filePath,
+    message: error && error.message ? error.message : String(error),
+  });
+  if (isVerbose() && error && error.stack) {
+    console.error(error.stack);
+  }
+}
+
+function safeLoadYamlConfig(filePath) {
+  if (!fs.existsSync(filePath)) {
+    return null;
+  }
+
+  try {
+    const fileContent = fs.readFileSync(filePath, 'utf8');
+    const docs = yaml.loadAll(fileContent);
+
+    if (docs.length === 1) {
+      return docs[0];
+    }
+
+    if (docs.length > 1) {
+      log.warn('检测到 YAML 多文档，仅使用第一个', { path: filePath });
+      return docs[0];
+    }
+
+    return null;
+  } catch (error) {
+    handleConfigLoadError(filePath, error);
+    return null;
+  }
+}
+
+function loadModularConfig(dirPath) {
+  if (!fs.existsSync(dirPath)) {
+    return null;
+  }
+
+  const config = {
+    site: {},
+    navigation: [],
+    fonts: {},
+    profile: {},
+    social: [],
+    categories: [],
+  };
+
+  const siteConfigPath = path.join(dirPath, 'site.yml');
+  const siteConfig = safeLoadYamlConfig(siteConfigPath);
+  if (siteConfig) {
+    config.site = siteConfig;
+
+    if (siteConfig.fonts) config.fonts = siteConfig.fonts;
+    if (siteConfig.profile) config.profile = siteConfig.profile;
+    if (siteConfig.social) config.social = siteConfig.social;
+    if (siteConfig.icons) config.icons = siteConfig.icons;
+
+    if (siteConfig.navigation) {
+      config.navigation = siteConfig.navigation;
+      if (isVerbose()) log.info('使用 site.yml 中的 navigation 配置');
+    }
+  }
+
+  const pagesPath = path.join(dirPath, 'pages');
+  if (fs.existsSync(pagesPath)) {
+    const files = fs
+      .readdirSync(pagesPath)
+      .filter((file) => file.endsWith('.yml') || file.endsWith('.yaml'));
+
+    files.forEach((file) => {
+      const filePath = path.join(pagesPath, file);
+      const fileConfig = safeLoadYamlConfig(filePath);
+
+      if (fileConfig) {
+        const configKey = path.basename(file, path.extname(file));
+        config[configKey] = fileConfig;
+      }
+    });
+  }
+
+  return config;
+}
+
+module.exports = {
+  safeLoadYamlConfig,
+  loadModularConfig,
+};
diff --git a/src/generator/config/resolver.js b/src/generator/config/resolver.js
new file mode 100644
index 0000000000000000000000000000000000000000..d19307c1404343e209db5c836dabe81e0c2ee919
--- /dev/null
+++ b/src/generator/config/resolver.js
@@ -0,0 +1,145 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const { assignCategorySlugs } = require('./slugs');
+
+const MENAV_EXTENSION_CONFIG_FILE = 'menav-config.json';
+
+function getSubmenuForNavItem(navItem, config) {
+  if (!navItem || !navItem.id || !config) {
+    return null;
+  }
+
+  if (config[navItem.id] && Array.isArray(config[navItem.id].categories))
+    return config[navItem.id].categories;
+
+  return null;
+}
+
+function makeJsonSafeForHtmlScript(jsonString) {
+  if (typeof jsonString !== 'string') {
+    return '';
+  }
+
+  return jsonString.replace(/<\/script/gi, '<\\/script');
+}
+
+function resolveTemplateNameForPage(pageId, config) {
+  if (!pageId) return 'page';
+
+  const pageConfig = config && config[pageId] ? config[pageId] : null;
+  const explicit = pageConfig && pageConfig.template ? String(pageConfig.template).trim() : '';
+  if (explicit) return explicit;
+
+  const candidatePath = path.join(process.cwd(), 'templates', 'pages', `${pageId}.hbs`);
+  if (fs.existsSync(candidatePath)) return pageId;
+
+  return 'page';
+}
+
+function buildExtensionConfig(renderData) {
+  const version =
+    renderData &&
+    renderData._meta &&
+    renderData._meta.version &&
+    String(renderData._meta.version).trim()
+      ? String(renderData._meta.version).trim()
+      : process.env.npm_package_version || '1.0.0';
+
+  const pageTemplates = {};
+  if (renderData && Array.isArray(renderData.navigation)) {
+    renderData.navigation.forEach((navItem) => {
+      const pageId = navItem && navItem.id ? String(navItem.id).trim() : '';
+      if (!pageId) return;
+      pageTemplates[pageId] = resolveTemplateNameForPage(pageId, renderData);
+    });
+  }
+
+  const allowedSchemes =
+    renderData &&
+    renderData.site &&
+    renderData.site.security &&
+    Array.isArray(renderData.site.security.allowedSchemes)
+      ? renderData.site.security.allowedSchemes
+      : null;
+
+  return {
+    version,
+    timestamp: new Date().toISOString(),
+    icons: renderData && renderData.icons ? renderData.icons : undefined,
+    data: {
+      homePageId: renderData && renderData.homePageId ? renderData.homePageId : null,
+      pageTemplates,
+      site: allowedSchemes ? { security: { allowedSchemes } } : undefined,
+    },
+  };
+}
+
+function prepareRenderData(config) {
+  const renderData = { ...config };
+
+  renderData._meta = {
+    generated_at: new Date(),
+    version: process.env.npm_package_version || '1.0.0',
+    generator: 'MeNav',
+  };
+
+  if (!Array.isArray(renderData.navigation)) {
+    renderData.navigation = [];
+  }
+
+  if (Array.isArray(renderData.navigation)) {
+    renderData.navigation = renderData.navigation.map((item, index) => {
+      const navItem = {
+        ...item,
+        isActive: index === 0,
+        id: item.id || `nav-${index}`,
+        active: index === 0,
+      };
+
+      const submenu = getSubmenuForNavItem(navItem, renderData);
+      if (submenu) {
+        navItem.submenu = submenu;
+      }
+
+      return navItem;
+    });
+  }
+
+  renderData.homePageId =
+    renderData.navigation && renderData.navigation[0] ? renderData.navigation[0].id : null;
+
+  if (Array.isArray(renderData.navigation)) {
+    renderData.navigation.forEach((navItem) => {
+      const pageConfig = renderData[navItem.id];
+      if (pageConfig && Array.isArray(pageConfig.categories)) {
+        assignCategorySlugs(pageConfig.categories, new Map());
+      }
+    });
+  }
+
+  const extensionConfig = buildExtensionConfig(renderData);
+  renderData.extensionConfig = extensionConfig;
+  renderData.extensionConfigUrl = `./${MENAV_EXTENSION_CONFIG_FILE}`;
+  renderData.configJSON = makeJsonSafeForHtmlScript(
+    JSON.stringify({
+      ...extensionConfig,
+      configUrl: renderData.extensionConfigUrl,
+    })
+  );
+
+  renderData.navigationData = renderData.navigation;
+
+  if (Array.isArray(renderData.social)) {
+    renderData.socialLinks = renderData.social;
+  }
+
+  return renderData;
+}
+
+module.exports = {
+  MENAV_EXTENSION_CONFIG_FILE,
+  getSubmenuForNavItem,
+  resolveTemplateNameForPage,
+  buildExtensionConfig,
+  prepareRenderData,
+};
diff --git a/src/generator/config/slugs.js b/src/generator/config/slugs.js
new file mode 100644
index 0000000000000000000000000000000000000000..c7d153ff3b5c551dc35483c69f1dbd2284b27d06
--- /dev/null
+++ b/src/generator/config/slugs.js
@@ -0,0 +1,43 @@
+function makeCategorySlugBase(name) {
+  const raw = typeof name === 'string' ? name : String(name ?? '');
+  const trimmed = raw.trim();
+  if (!trimmed) return 'category';
+
+  const normalized = trimmed
+    .replace(/\s+/g, '-')
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}_-]+/gu, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '');
+
+  return normalized || 'category';
+}
+
+function makeUniqueSlug(base, usedSlugs) {
+  const current = usedSlugs.get(base) || 0;
+  const next = current + 1;
+  usedSlugs.set(base, next);
+  return next === 1 ? base : `${base}-${next}`;
+}
+
+function assignCategorySlugs(categories, usedSlugs) {
+  if (!Array.isArray(categories)) return;
+
+  categories.forEach((category) => {
+    if (!category || typeof category !== 'object') return;
+
+    const base = makeCategorySlugBase(category.name);
+    const uniqueSlug = makeUniqueSlug(base, usedSlugs);
+    category.slug = uniqueSlug;
+
+    if (Array.isArray(category.subcategories)) {
+      assignCategorySlugs(category.subcategories, usedSlugs);
+    }
+  });
+}
+
+module.exports = {
+  makeCategorySlugBase,
+  makeUniqueSlug,
+  assignCategorySlugs,
+};
diff --git a/src/generator/config/validator.js b/src/generator/config/validator.js
new file mode 100644
index 0000000000000000000000000000000000000000..8215bc49091eaf40bda66001237b70e6047e3168
--- /dev/null
+++ b/src/generator/config/validator.js
@@ -0,0 +1,91 @@
+function ensureConfigDefaults(config) {
+  const result = { ...config };
+
+  result.site = result.site || {};
+  result.navigation = result.navigation || [];
+
+  result.fonts = result.fonts && typeof result.fonts === 'object' ? result.fonts : {};
+  result.fonts.source = result.fonts.source || 'css';
+  result.fonts.family = result.fonts.family || 'LXGW WenKai';
+  result.fonts.weight = result.fonts.weight || 'normal';
+  result.fonts.cssUrl = result.fonts.cssUrl || 'https://fontsapi.zeoseven.com/292/main/result.css';
+
+  result.profile = result.profile || {};
+  result.social = result.social || [];
+
+  result.icons = result.icons || {};
+  result.icons.mode = result.icons.mode || 'favicon';
+  result.icons.region = result.icons.region || 'com';
+
+  result.site.title = result.site.title || 'MeNav导航';
+  result.site.description = result.site.description || '个人网络导航站';
+  result.site.author = result.site.author || 'MeNav User';
+  result.site.logo_text = result.site.logo_text || '导航站';
+  result.site.favicon = result.site.favicon || 'menav.svg';
+  result.site.logo = result.site.logo || null;
+  result.site.footer = result.site.footer || '';
+  result.site.theme = result.site.theme || {
+    primary: '#4a89dc',
+    background: '#f5f7fa',
+    modeToggle: true,
+  };
+
+  result.profile.title = result.profile.title || '欢迎使用';
+  result.profile.subtitle = result.profile.subtitle || 'MeNav个人导航系统';
+
+  function processSiteDefaults(site) {
+    site.name = site.name || '未命名站点';
+    site.url = site.url || '#';
+    site.description = site.description || '';
+    site.icon = site.icon || 'fas fa-link';
+    site.external = typeof site.external === 'boolean' ? site.external : true;
+  }
+
+  function processNodeSitesRecursively(node) {
+    if (!node || typeof node !== 'object') return;
+
+    if (Array.isArray(node.sites)) {
+      node.sites.forEach(processSiteDefaults);
+    }
+
+    if (Array.isArray(node.subcategories)) node.subcategories.forEach(processNodeSitesRecursively);
+    if (Array.isArray(node.groups)) node.groups.forEach(processNodeSitesRecursively);
+    if (Array.isArray(node.subgroups)) node.subgroups.forEach(processNodeSitesRecursively);
+  }
+
+  function processCategoryDefaults(category) {
+    category.name = category.name || '未命名分类';
+    category.sites = category.sites || [];
+    processNodeSitesRecursively(category);
+  }
+
+  Object.keys(result).forEach((key) => {
+    const pageConfig = result[key];
+    if (!pageConfig || typeof pageConfig !== 'object') return;
+
+    if (Array.isArray(pageConfig.categories)) {
+      pageConfig.categories.forEach(processCategoryDefaults);
+    }
+
+    if (Array.isArray(pageConfig.sites)) {
+      pageConfig.sites.forEach(processSiteDefaults);
+    }
+  });
+
+  return result;
+}
+
+function validateConfig(config) {
+  if (!config || typeof config !== 'object') {
+    const { createLogger } = require('../utils/logger');
+    createLogger('config').error('配置无效：配置必须是对象');
+    return false;
+  }
+
+  return true;
+}
+
+module.exports = {
+  ensureConfigDefaults,
+  validateConfig,
+};
diff --git a/src/generator/html/404.js b/src/generator/html/404.js
new file mode 100644
index 0000000000000000000000000000000000000000..f5d61d3e0a7fb9182e442b1a69b845025835f72b
--- /dev/null
+++ b/src/generator/html/404.js
@@ -0,0 +1,95 @@
+const { escapeHtml } = require('../utils/html');
+
+// 生成 GitHub Pages 的 404 回跳页：将 /<id> 形式的路径深链接转换为 /?page=<id>
+function generate404Html(config) {
+  const siteTitle =
+    config && config.site && typeof config.site.title === 'string' ? config.site.title : 'MeNav';
+  const safeTitle = escapeHtml(siteTitle);
+
+  return `<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex" />
+    <title>${safeTitle} - 页面未找到</title>
+    <style>
+      body {
+        margin: 0;
+        padding: 40px 16px;
+        font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue',
+          Arial, 'Noto Sans', 'Liberation Sans', sans-serif;
+        background: #0b1020;
+        color: #e6e6e6;
+      }
+      .container {
+        max-width: 760px;
+        margin: 0 auto;
+      }
+      h1 {
+        margin: 0 0 12px;
+        font-size: 22px;
+      }
+      p {
+        margin: 8px 0;
+        line-height: 1.6;
+        color: rgba(230, 230, 230, 0.9);
+      }
+      a {
+        color: #74c0fc;
+      }
+      code {
+        background: rgba(255, 255, 255, 0.08);
+        padding: 2px 6px;
+        border-radius: 4px;
+      }
+    </style>
+    <script>
+      (function () {
+        try {
+          var l = window.location;
+          var pathname = l.pathname || '';
+          var segments = pathname.split('/').filter(Boolean);
+
+          // 用户站点：/<id>
+          // 仓库站点：/<repo>/<id>
+          var repoBase = '';
+          var pageId = '';
+          if (segments.length === 1) {
+            pageId = segments[0];
+          } else if (segments.length === 2) {
+            repoBase = '/' + segments[0];
+            pageId = segments[1];
+          } else {
+            repoBase = segments.length > 1 ? '/' + segments[0] : '';
+            pageId = segments.length ? segments[segments.length - 1] : '';
+          }
+
+          if (!pageId) {
+            l.replace(repoBase + '/');
+            return;
+          }
+
+          var target = repoBase + '/?page=' + encodeURIComponent(pageId) + (l.hash || '');
+          l.replace(target);
+        } catch (e) {
+          // 兜底：回到首页
+          window.location.replace('./');
+        }
+      })();
+    </script>
+  </head>
+  <body>
+    <div class="container">
+      <h1>页面未找到</h1>
+      <p>若你访问的是“页面路径深链接”，系统将自动回跳到 <code>?page=</code> 形式的可用地址。</p>
+      <p><a href="./">返回首页</a></p>
+    </div>
+  </body>
+</html>
+`;
+}
+
+module.exports = {
+  generate404Html,
+};
diff --git a/src/generator/html/components.js b/src/generator/html/components.js
new file mode 100644
index 0000000000000000000000000000000000000000..07bf05184e3ae29ad54a9784f502e06dc5e61d0a
--- /dev/null
+++ b/src/generator/html/components.js
@@ -0,0 +1,213 @@
+const fs = require('fs');
+const path = require('path');
+
+const { handlebars } = require('../template/engine');
+const { getSubmenuForNavItem } = require('../config');
+const { escapeHtml } = require('../utils/html');
+const { createLogger, isVerbose } = require('../utils/logger');
+
+const log = createLogger('render');
+
+// 生成导航菜单
+function generateNavigation(navigation, config) {
+  return navigation
+    .map((nav) => {
+      // 根据页面ID获取对应的子菜单项（分类）
+      let submenuItems = '';
+
+      // 使用辅助函数获取子菜单数据
+      const submenu = getSubmenuForNavItem(nav, config);
+
+      // 如果存在子菜单，生成HTML
+      if (submenu && Array.isArray(submenu)) {
+        submenuItems = `
+                <div class="submenu">
+                    ${submenu
+                      .map(
+                        (category) => `
+                        <a href="#${category.name}" class="submenu-item" data-page="${nav.id}" data-category="${category.name}">
+                            <i class="${escapeHtml(category.icon)}"></i>
+                            <span>${escapeHtml(category.name)}</span>
+                        </a>
+                    `
+                      )
+                      .join('')}
+                </div>`;
+      }
+
+      return `
+                <div class="nav-item-wrapper">
+                    <a href="#" class="nav-item${nav.active ? ' active' : ''}" data-page="${escapeHtml(nav.id)}">
+                        <div class="icon-container">
+                            <i class="${escapeHtml(nav.icon)}"></i>
+                        </div>
+                        <span class="nav-text">${escapeHtml(nav.name)}</span>
+                        ${submenuItems ? '<i class="fas fa-chevron-down submenu-toggle"></i>' : ''}
+                    </a>
+                    ${submenuItems}
+                </div>`;
+    })
+    .join('\n');
+}
+
+// 生成网站卡片HTML
+function generateSiteCards(sites) {
+  if (!sites || !Array.isArray(sites) || sites.length === 0) {
+    return `<p class="empty-sites">暂无网站</p>`;
+  }
+
+  return sites
+    .map(
+      (site) => `
+                        <a href="${escapeHtml(site.url)}" class="site-card" title="${escapeHtml(site.name)} - ${escapeHtml(site.description || '')}">
+                            <i class="${escapeHtml(site.icon || 'fas fa-link')}"></i>
+                            <h3>${escapeHtml(site.name || '未命名站点')}</h3>
+                            <p>${escapeHtml(site.description || '')}</p>
+                        </a>`
+    )
+    .join('\n');
+}
+
+// 生成分类板块
+function generateCategories(categories) {
+  if (!categories || !Array.isArray(categories) || categories.length === 0) {
+    return `
+                <section class="category">
+                    <h2><i class="fas fa-info-circle"></i> 暂无分类</h2>
+                    <p>请在配置文件中添加分类</p>
+                </section>`;
+  }
+
+  return categories
+    .map(
+      (category) => `
+                <section class="category" id="${escapeHtml(category.name)}">
+                    <h2><i class="${escapeHtml(category.icon)}"></i> ${escapeHtml(category.name)}</h2>
+                    <div class="sites-grid">
+                        ${generateSiteCards(category.sites)}
+                    </div>
+                </section>`
+    )
+    .join('\n');
+}
+
+// 生成社交链接HTML
+function generateSocialLinks(social) {
+  if (!social || !Array.isArray(social) || social.length === 0) {
+    return '';
+  }
+
+  // 尝试使用 Handlebars 模板
+  try {
+    const socialLinksPath = path.join(process.cwd(), 'templates', 'components', 'social-links.hbs');
+    if (fs.existsSync(socialLinksPath)) {
+      const templateContent = fs.readFileSync(socialLinksPath, 'utf8');
+      const template = handlebars.compile(templateContent);
+      // 确保数据格式正确
+      return template(social); // 社交链接模板直接接收数组
+    }
+  } catch (error) {
+    log.warn('渲染 social-links 模板失败，已回退到内置渲染', {
+      message: error && error.message ? error.message : String(error),
+    });
+    if (isVerbose() && error && error.stack) console.error(error.stack);
+    // 出错时回退到原始生成方法
+  }
+
+  // 回退到原始生成方法
+  return social
+    .map(
+      (link) => `
+                    <a href="${escapeHtml(link.url)}" class="social-icon" target="_blank" rel="noopener" title="${escapeHtml(link.name || '社交链接')}" aria-label="${escapeHtml(link.name || '社交链接')}" data-type="social-link" data-name="${escapeHtml(link.name || '社交链接')}" data-url="${escapeHtml(link.url)}" data-icon="${escapeHtml(link.icon || 'fas fa-link')}">
+                        <i class="${escapeHtml(link.icon || 'fas fa-link')}" aria-hidden="true"></i>
+                        <span class="nav-text visually-hidden" data-editable="social-link-name">${escapeHtml(link.name || '社交链接')}</span>
+                    </a>`
+    )
+    .join('\n');
+}
+
+// 生成页面内容（包括首页和其他页面）
+function generatePageContent(pageId, data) {
+  // 确保数据对象存在
+  if (!data) {
+    log.warn('页面数据缺失，已回退为占位页面', { page: pageId });
+    return `
+                <div class="welcome-section">
+                    <div class="welcome-section-main">
+                        <h2>页面未配置</h2>
+                        <p class="subtitle">请配置 ${pageId} 页面</p>
+                    </div>
+                </div>`;
+  }
+
+  // 首页使用 profile 数据，其他页面使用自身数据
+  if (pageId === 'home') {
+    const profile = data.profile || {};
+
+    return `
+                <div class="welcome-section">
+                    <div class="welcome-section-main">
+                        <h2>${escapeHtml(profile.title || '欢迎使用')}</h2>
+                        <h3>${escapeHtml(profile.subtitle || '个人导航站')}</h3>
+                    </div>
+                </div>
+${generateCategories(data.categories)}`;
+  } else {
+    // 其他页面使用通用结构
+    const title = data.title || `${pageId} 页面`;
+    const subtitle = data.subtitle || '';
+    const categories = data.categories || [];
+
+    return `
+                <div class="welcome-section">
+                    <div class="welcome-section-main">
+                        <h2>${escapeHtml(title)}</h2>
+                        <p class="subtitle">${escapeHtml(subtitle)}</p>
+                    </div>
+                </div>
+                ${generateCategories(categories)}`;
+  }
+}
+
+// 生成搜索结果页面
+function generateSearchResultsPage(config) {
+  // 获取所有导航页面ID
+  const pageIds = config.navigation.map((nav) => nav.id);
+
+  // 生成所有页面的搜索结果区域
+  const sections = pageIds
+    .map((pageId) => {
+      // 根据页面ID获取对应的图标和名称
+      const navItem = config.navigation.find((nav) => nav.id === pageId);
+      const icon = navItem ? navItem.icon : 'fas fa-file';
+      const name = navItem ? navItem.name : pageId;
+
+      return `
+                <section class="category search-section" data-section="${escapeHtml(pageId)}" style="display: none;">
+                    <h2><i class="${escapeHtml(icon)}"></i> ${escapeHtml(name)}匹配项</h2>
+                    <div class="sites-grid"></div>
+                </section>`;
+    })
+    .join('\n');
+
+  return `
+            <!-- 搜索结果页 -->
+            <div class="page" id="search-results">
+                <div class="welcome-section">
+                    <div class="welcome-section-main">
+                        <h2>搜索结果</h2>
+                        <p class="subtitle">在所有页面中找到的匹配项</p>
+                    </div>
+                </div>
+${sections}
+            </div>`;
+}
+
+module.exports = {
+  generateNavigation,
+  generateSiteCards,
+  generateCategories,
+  generateSocialLinks,
+  generatePageContent,
+  generateSearchResultsPage,
+};
diff --git a/src/generator/html/fonts.js b/src/generator/html/fonts.js
new file mode 100644
index 0000000000000000000000000000000000000000..bbea747bba878aba2516e8d17cf903a980af1748
--- /dev/null
+++ b/src/generator/html/fonts.js
@@ -0,0 +1,155 @@
+const { escapeHtml } = require('../utils/html');
+
+/**
+ * 将 CSS 文本安全嵌入到 <style> 中，避免出现 `</style>` 结束标签导致样式块被提前终止。
+ * @param {string} cssText CSS 文本
+ * @returns {string} 安全的 CSS 文本
+ */
+function makeCssSafeForHtmlStyleTag(cssText) {
+  if (typeof cssText !== 'string') {
+    return '';
+  }
+
+  return cssText.replace(/<\/style/gi, '<\\/style');
+}
+
+function normalizeFontWeight(input) {
+  if (input === undefined || input === null) return 'normal';
+
+  if (typeof input === 'number' && Number.isFinite(input)) {
+    return String(input);
+  }
+
+  const raw = String(input).trim();
+  if (!raw) return 'normal';
+
+  if (/^(normal|bold|bolder|lighter)$/i.test(raw)) return raw.toLowerCase();
+  if (/^[1-9]00$/.test(raw)) return raw;
+
+  return raw;
+}
+
+function normalizeFontFamilyForCss(input) {
+  const raw = String(input || '').trim();
+  if (!raw) return '';
+
+  const generics = new Set([
+    'serif',
+    'sans-serif',
+    'monospace',
+    'cursive',
+    'fantasy',
+    'system-ui',
+    'ui-serif',
+    'ui-sans-serif',
+    'ui-monospace',
+    'ui-rounded',
+    'emoji',
+    'math',
+    'fangsong',
+  ]);
+
+  return raw
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .map((part) => {
+      const unquoted = part.replace(/^['"]|['"]$/g, '').trim();
+      if (!unquoted) return '';
+      if (generics.has(unquoted)) return unquoted;
+
+      const needsQuotes = /\s/.test(unquoted);
+      if (!needsQuotes) return unquoted;
+
+      return `"${unquoted.replace(/"/g, '\\"')}"`;
+    })
+    .filter(Boolean)
+    .join(', ');
+}
+
+function normalizeFontSource(input) {
+  const raw = String(input || '')
+    .trim()
+    .toLowerCase();
+  if (raw === 'css' || raw === 'google' || raw === 'system') return raw;
+  return 'system';
+}
+
+function getNormalizedFontsConfig(config) {
+  const fonts = config && config.fonts && typeof config.fonts === 'object' ? config.fonts : {};
+
+  return {
+    source: normalizeFontSource(fonts.source),
+    family: normalizeFontFamilyForCss(fonts.family),
+    weight: normalizeFontWeight(fonts.weight),
+    cssUrl: String(fonts.cssUrl || fonts.href || '').trim(),
+    preload: Boolean(fonts.preload),
+  };
+}
+
+function tryGetUrlOrigin(input) {
+  const raw = String(input || '').trim();
+  if (!raw) return '';
+  try {
+    return new URL(raw).origin;
+  } catch {
+    return '';
+  }
+}
+
+function buildStylesheetLinkTag(href, preload) {
+  const safeHref = escapeHtml(href);
+  if (!preload) return `<link rel="stylesheet" href="${safeHref}">`;
+
+  return [
+    `<link rel="preload" href="${safeHref}" as="style" onload="this.onload=null;this.rel='stylesheet'">`,
+    `<noscript><link rel="stylesheet" href="${safeHref}"></noscript>`,
+  ].join('\n');
+}
+
+// 生成字体相关 <link>
+function generateFontLinks(config) {
+  const fonts = getNormalizedFontsConfig(config);
+  const links = [];
+
+  // 全站基础字体：按配置加载
+  if (fonts.source === 'css' && fonts.cssUrl) {
+    const origin = tryGetUrlOrigin(fonts.cssUrl);
+    if (origin) {
+      links.push(`<link rel="preconnect" href="${escapeHtml(origin)}" crossorigin>`);
+    }
+    links.push(buildStylesheetLinkTag(fonts.cssUrl, fonts.preload));
+  }
+
+  if (fonts.source === 'google' && fonts.family) {
+    links.push('<link rel="preconnect" href="https://fonts.googleapis.com">');
+    links.push('<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>');
+
+    const familyNoQuotes = fonts.family.replace(/[\"']/g, '').split(',')[0].trim();
+    const weight = /^[1-9]00$/.test(fonts.weight) ? fonts.weight : '400';
+    const familyParam = encodeURIComponent(familyNoQuotes).replace(/%20/g, '+');
+    links.push(
+      buildStylesheetLinkTag(
+        `https://fonts.googleapis.com/css2?family=${familyParam}:wght@${weight}&display=swap`,
+        fonts.preload
+      )
+    );
+  }
+
+  return links.join('\n');
+}
+
+// 生成字体 CSS 变量（单一字体配置）
+function generateFontCss(config) {
+  const fonts = getNormalizedFontsConfig(config);
+  const family = fonts.family || 'system-ui, sans-serif';
+  const weight = fonts.weight || 'normal';
+
+  const css = `:root {\n  --font-body: ${family};\n  --font-weight-body: ${weight};\n}\n`;
+  return makeCssSafeForHtmlStyleTag(css);
+}
+
+module.exports = {
+  generateFontLinks,
+  generateFontCss,
+};
diff --git a/src/generator/html/markdown.js b/src/generator/html/markdown.js
new file mode 100644
index 0000000000000000000000000000000000000000..4b7f8cc642e28f777330825692b04aeec5028736
--- /dev/null
+++ b/src/generator/html/markdown.js
@@ -0,0 +1,108 @@
+const MarkdownIt = require('markdown-it');
+
+/**
+ * 构建期 Markdown 渲染器（用于内容页 template: content）
+ *
+ * 约束：
+ * - 禁止 raw HTML（避免 XSS）
+ * - 禁止图片（本期不支持图片/附件）
+ * - 链接 href 必须通过安全策略校验（沿用 safeUrl 的 scheme 白名单思想）
+ */
+
+function normalizeAllowedSchemes(allowedSchemes) {
+  if (!Array.isArray(allowedSchemes) || allowedSchemes.length === 0) {
+    return ['http', 'https', 'mailto', 'tel'];
+  }
+  return allowedSchemes
+    .map((s) =>
+      String(s || '')
+        .trim()
+        .toLowerCase()
+        .replace(/:$/, '')
+    )
+    .filter(Boolean);
+}
+
+function isRelativeUrl(url) {
+  const s = String(url || '').trim();
+  return (
+    s.startsWith('#') ||
+    s.startsWith('/') ||
+    s.startsWith('./') ||
+    s.startsWith('../') ||
+    s.startsWith('?')
+  );
+}
+
+/**
+ * 将 href 按 MeNav 安全策略清洗为可点击链接
+ * @param {string} href 原始 href
+ * @param {string[]} allowedSchemes 允许的 scheme 列表（不含冒号）
+ * @returns {string} 安全 href（不安全时返回 '#'
+ */
+function sanitizeLinkHref(href, allowedSchemes) {
+  const raw = String(href || '').trim();
+  if (!raw) return '#';
+  if (isRelativeUrl(raw)) return raw;
+
+  // 明确拒绝协议相对 URL（//example.com），避免绕过策略
+  if (raw.startsWith('//')) return '#';
+
+  try {
+    const parsed = new URL(raw);
+    const scheme = String(parsed.protocol || '')
+      .toLowerCase()
+      .replace(/:$/, '');
+    return allowedSchemes.includes(scheme) ? raw : '#';
+  } catch {
+    return '#';
+  }
+}
+
+function createMarkdownIt({ allowedSchemes }) {
+  const md = new MarkdownIt({
+    html: false,
+    linkify: true,
+    typographer: true,
+  });
+
+  // markdown-it 默认会拒绝 javascript: 等链接，并导致其不被渲染为 <a>
+  // 我们这里统一“允许渲染，但在 renderer 层做 href 安全降级”。
+  md.validateLink = () => true;
+
+  // 本期明确不支持图片
+  md.disable('image');
+
+  const normalizedSchemes = normalizeAllowedSchemes(allowedSchemes);
+  const defaultRender = md.renderer.rules.link_open;
+
+  md.renderer.rules.link_open = function (tokens, idx, options, env, self) {
+    const token = tokens[idx];
+    const hrefIndex = token.attrIndex('href');
+    if (hrefIndex >= 0) {
+      const originalHref = token.attrs[hrefIndex][1];
+      token.attrs[hrefIndex][1] = sanitizeLinkHref(originalHref, normalizedSchemes);
+    }
+
+    return defaultRender
+      ? defaultRender(tokens, idx, options, env, self)
+      : self.renderToken(tokens, idx, options);
+  };
+
+  return md;
+}
+
+/**
+ * @param {string} markdownText markdown 原文
+ * @param {{allowedSchemes?: string[]}} opts
+ * @returns {string} HTML（不包含外层 layout）
+ */
+function renderMarkdownToHtml(markdownText, opts = {}) {
+  const md = createMarkdownIt({ allowedSchemes: opts.allowedSchemes });
+  return md.render(String(markdownText || ''));
+}
+
+module.exports = {
+  sanitizeLinkHref,
+  renderMarkdownToHtml,
+};
diff --git a/src/generator/html/page-data.js b/src/generator/html/page-data.js
new file mode 100644
index 0000000000000000000000000000000000000000..38e18950f86bb5463168311376072d905c333c2c
--- /dev/null
+++ b/src/generator/html/page-data.js
@@ -0,0 +1,236 @@
+const fs = require('fs');
+const path = require('path');
+const { getSubmenuForNavItem, assignCategorySlugs } = require('../config');
+const {
+  tryLoadArticlesFeedCache,
+  buildArticlesCategoriesByPageCategories,
+} = require('../cache/articles');
+const {
+  tryLoadProjectsRepoCache,
+  tryLoadProjectsHeatmapCache,
+  applyRepoMetaToCategories,
+  buildProjectsMeta,
+} = require('../cache/projects');
+const { getPageConfigUpdatedAtMeta } = require('../utils/pageMeta');
+const { createLogger, isVerbose } = require('../utils/logger');
+const { ConfigError } = require('../utils/errors');
+const { renderMarkdownToHtml } = require('./markdown');
+
+const log = createLogger('render');
+
+function prepareNavigationData(pageId, config) {
+  if (!Array.isArray(config.navigation)) {
+    log.warn('config.navigation 不是数组，已降级为空数组');
+    return [];
+  }
+
+  return config.navigation.map((nav) => {
+    const navItem = {
+      ...nav,
+      isActive: nav.id === pageId,
+      active: nav.id === pageId,
+    };
+
+    const submenu = getSubmenuForNavItem(navItem, config);
+    if (submenu) {
+      navItem.submenu = submenu;
+    }
+
+    return navItem;
+  });
+}
+
+function resolveTemplateName(pageId, data) {
+  const explicitTemplate = typeof data.template === 'string' ? data.template.trim() : '';
+  let templateName = explicitTemplate || pageId;
+
+  if (!explicitTemplate) {
+    const inferredTemplatePath = path.join(
+      process.cwd(),
+      'templates',
+      'pages',
+      `${templateName}.hbs`
+    );
+    if (!fs.existsSync(inferredTemplatePath)) {
+      templateName = 'page';
+    }
+  }
+
+  return templateName;
+}
+
+function applyProjectsData(data, pageId, config) {
+  data.siteCardStyle = 'repo';
+  data.projectsMeta = buildProjectsMeta(config);
+
+  const heatmapCache = tryLoadProjectsHeatmapCache(pageId, config);
+  if (data.projectsMeta && data.projectsMeta.heatmap && heatmapCache) {
+    data.projectsMeta.heatmap.html = heatmapCache.html;
+    data.projectsMeta.heatmap.generatedAt = heatmapCache.meta.generatedAt;
+    data.projectsMeta.heatmap.sourceUrl = heatmapCache.meta.sourceUrl;
+  }
+
+  if (Array.isArray(data.categories)) {
+    const repoCache = tryLoadProjectsRepoCache(pageId, config);
+    if (repoCache && repoCache.map) {
+      applyRepoMetaToCategories(data.categories, repoCache.map);
+    }
+  }
+}
+
+function applyArticlesData(data, pageId, config) {
+  const cache = tryLoadArticlesFeedCache(pageId, config);
+  data.articlesItems = cache && Array.isArray(cache.items) ? cache.items : [];
+  data.articlesMeta = cache ? cache.meta : null;
+  data.articlesCategories = data.articlesItems.length
+    ? buildArticlesCategoriesByPageCategories(data.categories, data.articlesItems)
+    : [];
+}
+
+function applyBookmarksData(data, pageId) {
+  const updatedAtMeta = getPageConfigUpdatedAtMeta(pageId);
+  if (updatedAtMeta) {
+    data.pageMeta = { ...updatedAtMeta };
+  }
+}
+
+function applyContentData(data, pageId, config) {
+  const content = data && data.content && typeof data.content === 'object' ? data.content : null;
+  const file = content && content.file ? String(content.file).trim() : '';
+  if (!file) {
+    throw new ConfigError(`内容页缺少 content.file：${pageId}`, [
+      `请在 config/*/pages/${pageId}.yml 中配置：`,
+      'template: content',
+      'content:',
+      '  file: path/to/file.md',
+    ]);
+  }
+
+  // 本期仅支持读取本地 markdown 文件
+  const fs = require('node:fs');
+  const path = require('node:path');
+
+  // 允许用户以相对 repo root 的路径引用（推荐约定：content/*.md）
+  // 同时允许绝对路径（便于本地调试/临时文件），但不会自动复制资源到 dist。
+  const normalized = file.replace(/\\/g, '/');
+  const absPath = path.isAbsolute(normalized)
+    ? path.normalize(normalized)
+    : path.join(process.cwd(), normalized.replace(/^\//, ''));
+  if (!fs.existsSync(absPath)) {
+    throw new ConfigError(`内容页 markdown 文件不存在：${pageId}`, [
+      `检查路径是否正确：${file}`,
+      '提示：路径相对于仓库根目录（process.cwd()）解析',
+    ]);
+  }
+
+  const markdownText = fs.readFileSync(absPath, 'utf8');
+  const allowedSchemes =
+    config &&
+    config.site &&
+    config.site.security &&
+    Array.isArray(config.site.security.allowedSchemes)
+      ? config.site.security.allowedSchemes
+      : null;
+
+  data.contentFile = normalized;
+  data.contentHtml = renderMarkdownToHtml(markdownText, { allowedSchemes });
+}
+
+function convertTopLevelSitesToCategory(data, pageId, templateName) {
+  const isFriendsPage = pageId === 'friends' || templateName === 'friends';
+  const isArticlesPage = pageId === 'articles' || templateName === 'articles';
+
+  if (
+    (isFriendsPage || isArticlesPage) &&
+    (!Array.isArray(data.categories) || data.categories.length === 0) &&
+    Array.isArray(data.sites) &&
+    data.sites.length > 0
+  ) {
+    const implicitName = isFriendsPage ? '全部友链' : '全部来源';
+    data.categories = [
+      {
+        name: implicitName,
+        icon: 'fas fa-link',
+        sites: data.sites,
+      },
+    ];
+  }
+}
+
+function applyHomePageTitles(data, pageId, config) {
+  const homePageId =
+    config.homePageId ||
+    (Array.isArray(config.navigation) && config.navigation[0] ? config.navigation[0].id : null) ||
+    'home';
+
+  data.homePageId = homePageId;
+
+  if (pageId === homePageId && config.profile) {
+    if (config.profile.title !== undefined) data.title = config.profile.title;
+    if (config.profile.subtitle !== undefined) data.subtitle = config.profile.subtitle;
+  }
+
+  data.isHome = pageId === homePageId;
+  data.homePageId = homePageId;
+}
+
+function preparePageData(pageId, config) {
+  const data = {
+    ...(config || {}),
+    currentPage: pageId,
+    pageId,
+  };
+
+  data.navigation = prepareNavigationData(pageId, config);
+  data.socialLinks = Array.isArray(config.social) ? config.social : [];
+  data.navigationData = data.navigation;
+
+  if (config[pageId]) {
+    Object.assign(data, config[pageId]);
+  }
+
+  if (data.title === undefined) {
+    const navItem = Array.isArray(config.navigation)
+      ? config.navigation.find((nav) => nav.id === pageId)
+      : null;
+    if (navItem && navItem.name !== undefined) data.title = navItem.name;
+  }
+  if (data.subtitle === undefined) data.subtitle = '';
+  if (!Array.isArray(data.categories)) data.categories = [];
+
+  const templateName = resolveTemplateName(pageId, data);
+
+  if (templateName === 'projects') {
+    applyProjectsData(data, pageId, config);
+  }
+
+  convertTopLevelSitesToCategory(data, pageId, templateName);
+
+  if (templateName === 'articles') {
+    applyArticlesData(data, pageId, config);
+  }
+
+  if (templateName === 'bookmarks') {
+    applyBookmarksData(data, pageId);
+  }
+
+  if (templateName === 'content') {
+    applyContentData(data, pageId, config);
+  }
+
+  applyHomePageTitles(data, pageId, config);
+
+  if (Array.isArray(data.categories) && data.categories.length > 0) {
+    assignCategorySlugs(data.categories, new Map());
+  }
+
+  if (config[pageId] && config[pageId].template) {
+    if (isVerbose()) log.info(`页面 ${pageId} 使用指定模板`, { template: templateName });
+  }
+
+  return { data, templateName };
+}
+
+module.exports = {
+  preparePageData,
+};
diff --git a/src/generator/main.js b/src/generator/main.js
new file mode 100644
index 0000000000000000000000000000000000000000..b94518c3791fe78ad6eda57c9fa6dfd6879358d6
--- /dev/null
+++ b/src/generator/main.js
@@ -0,0 +1,429 @@
+// 生成端主实现（由 src/generator.js 薄入口加载并 re-export）
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+const {
+  loadHandlebarsTemplates,
+  getDefaultLayoutTemplate,
+  renderTemplate,
+} = require('./template/engine');
+const { MENAV_EXTENSION_CONFIG_FILE, loadConfig, getSubmenuForNavItem } = require('./config');
+
+const {
+  generateNavigation,
+  generateCategories,
+  generateSocialLinks,
+} = require('./html/components');
+const { generate404Html } = require('./html/404');
+const { generateFontLinks, generateFontCss } = require('./html/fonts');
+const { preparePageData } = require('./html/page-data');
+const { collectSitesRecursively } = require('./utils/sites');
+const {
+  BuildError,
+  ConfigError,
+  FileError,
+  TemplateError,
+  wrapAsyncError,
+} = require('./utils/errors');
+const { createLogger, isVerbose, startTimer } = require('./utils/logger');
+
+/**
+ * 渲染单个页面
+ * @param {string} pageId 页面ID
+ * @param {Object} config 配置数据
+ * @returns {string} 渲染后的HTML
+ */
+function renderPage(pageId, config) {
+  const { data, templateName } = preparePageData(pageId, config);
+  return renderTemplate(templateName, data, false);
+}
+
+/**
+ * 生成所有页面的HTML内容
+ * @param {Object} config 配置对象
+ * @returns {Object} 包含所有页面HTML的对象
+ */
+function generateAllPagesHTML(config) {
+  // 页面内容集合
+  const pages = {};
+
+  // 渲染配置中定义的所有页面
+  if (Array.isArray(config.navigation)) {
+    config.navigation.forEach((navItem) => {
+      const pageId = navItem.id;
+
+      // 渲染页面内容
+      pages[pageId] = renderPage(pageId, config);
+    });
+  }
+
+  // 确保搜索结果页存在
+  if (!pages['search-results']) {
+    pages['search-results'] = renderPage('search-results', config);
+  }
+
+  return pages;
+}
+
+/**
+ * 生成完整的HTML
+ * @param {Object} config 配置对象
+ * @returns {string} 完整HTML
+ */
+function generateHTML(config) {
+  // 获取所有页面内容
+  const pages = generateAllPagesHTML(config);
+
+  // 获取当前年份
+  const currentYear = new Date().getFullYear();
+
+  // 准备导航数据，添加 submenu 字段
+  const navigationData = config.navigation.map((nav) => {
+    const navItem = { ...nav };
+
+    // 使用辅助函数获取子菜单
+    const submenu = getSubmenuForNavItem(navItem, config);
+    if (submenu) {
+      navItem.submenu = submenu;
+    }
+
+    return navItem;
+  });
+
+  // 准备字体链接与 CSS 变量
+  const fontLinks = generateFontLinks(config);
+  const fontCss = generateFontCss(config);
+
+  // 准备社交链接
+  const socialLinks = generateSocialLinks(config.social);
+
+  // 使用主布局模板
+  const layoutData = {
+    ...config,
+    pages,
+    fontLinks,
+    fontCss,
+    navigationData,
+    currentYear,
+    socialLinks,
+    navigation: generateNavigation(config.navigation, config), // 兼容旧版
+    social: Array.isArray(config.social) ? config.social : [], // 兼容旧版
+
+    // 确保配置数据可用于浏览器扩展
+    configJSON: config.configJSON, // 从 prepareRenderData 函数中获取的配置数据
+  };
+
+  try {
+    // 使用辅助函数获取默认布局模板
+    const { template: layoutTemplate } = getDefaultLayoutTemplate();
+
+    // 渲染模板
+    return layoutTemplate(layoutData);
+  } catch (error) {
+    throw error;
+  }
+}
+
+/**
+ * 使用 esbuild bundle 模式合并 CSS @import
+ * 注意：transformSync 不支持 bundle，必须用 buildSync
+ * @param {string} srcPath - 源 CSS 文件路径
+ * @param {string} destPath - 目标文件路径
+ * @returns {boolean} 是否成功
+ */
+function tryBundleCss(srcPath, destPath) {
+  let esbuild;
+  try {
+    esbuild = require('esbuild');
+  } catch {
+    return false;
+  }
+
+  try {
+    // buildSync 需要绝对路径
+    const absoluteSrc = path.resolve(srcPath);
+    const absoluteDest = path.resolve(destPath);
+
+    esbuild.buildSync({
+      entryPoints: [absoluteSrc],
+      outfile: absoluteDest,
+      bundle: true, // 关键：合并 @import
+      minify: true,
+      logLevel: 'silent',
+    });
+    return true;
+  } catch (error) {
+    const log = createLogger('assets');
+    log.warn('CSS bundle 失败，降级为复制', {
+      message: error && error.message ? error.message : String(error),
+    });
+    if (isVerbose() && error && error.stack) console.error(error.stack);
+    return false;
+  }
+}
+
+/**
+ * 递归复制目录（降级方案：当 esbuild 不可用时复制 styles 目录）
+ * @param {string} src - 源目录
+ * @param {string} dest - 目标目录
+ */
+function copyDirRecursive(src, dest) {
+  if (!fs.existsSync(src)) return;
+  fs.mkdirSync(dest, { recursive: true });
+
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function tryMinifyStaticAsset(srcPath, destPath, loader) {
+  let esbuild;
+  try {
+    esbuild = require('esbuild');
+  } catch {
+    return false;
+  }
+
+  try {
+    const source = fs.readFileSync(srcPath, 'utf8');
+    const result = esbuild.transformSync(source, {
+      loader,
+      minify: true,
+      charset: 'utf8',
+    });
+    fs.writeFileSync(destPath, result.code);
+    return true;
+  } catch (error) {
+    const log = createLogger('assets');
+    log.warn('压缩静态资源失败，已降级为原文件', {
+      path: srcPath,
+      message: error && error.message ? error.message : String(error),
+    });
+    if (isVerbose() && error && error.stack) console.error(error.stack);
+    return false;
+  }
+}
+
+// 复制静态文件
+function copyStaticFiles(config) {
+  const log = createLogger('assets');
+
+  // 确保 dist 目录存在
+  if (!fs.existsSync('dist')) {
+    fs.mkdirSync('dist', { recursive: true });
+  }
+
+  // 复制 CSS 文件（支持模块化 @import）
+  try {
+    if (!tryBundleCss('assets/style.css', 'dist/style.css')) {
+      // 降级：复制入口 + styles 目录
+      fs.copyFileSync('assets/style.css', 'dist/style.css');
+      copyDirRecursive('assets/styles', 'dist/styles');
+      log.warn('CSS 未合并，浏览器将发起多个请求');
+    }
+  } catch (e) {
+    log.error('复制 style.css 失败', { message: e && e.message ? e.message : String(e) });
+    if (isVerbose() && e && e.stack) console.error(e.stack);
+  }
+
+  try {
+    if (!tryMinifyStaticAsset('assets/pinyin-match.js', 'dist/pinyin-match.js', 'js')) {
+      fs.copyFileSync('assets/pinyin-match.js', 'dist/pinyin-match.js');
+    }
+  } catch (e) {
+    log.error('复制 pinyin-match.js 失败', { message: e && e.message ? e.message : String(e) });
+    if (isVerbose() && e && e.stack) console.error(e.stack);
+  }
+
+  // dist/script.js 由构建阶段 runtime bundle 产出（scripts/build-runtime.js），这里不再复制/覆盖
+
+  // faviconUrl（站点级自定义图标）：若使用本地路径（建议以 assets/ 开头），则复制到 dist 下同路径
+  try {
+    const copied = new Set();
+
+    const copyLocalAsset = (rawUrl) => {
+      const raw = String(rawUrl || '').trim();
+      if (!raw) return;
+      if (/^https?:\/\//i.test(raw)) return;
+
+      const rel = raw.replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\//, '');
+      if (!rel.startsWith('assets/')) return;
+
+      const normalized = path.posix.normalize(rel);
+      if (!normalized.startsWith('assets/')) return;
+      if (copied.has(normalized)) return;
+      copied.add(normalized);
+
+      const srcPath = path.join(process.cwd(), normalized);
+      const destPath = path.join(process.cwd(), 'dist', normalized);
+      if (!fs.existsSync(srcPath)) {
+        log.warn('faviconUrl 本地文件不存在', { path: normalized });
+        return;
+      }
+
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.copyFileSync(srcPath, destPath);
+    };
+
+    if (config && Array.isArray(config.navigation)) {
+      config.navigation.forEach((navItem) => {
+        const pageId = navItem && navItem.id ? String(navItem.id) : '';
+        if (!pageId) return;
+        const pageConfig = config[pageId];
+        if (!pageConfig || typeof pageConfig !== 'object') return;
+
+        if (Array.isArray(pageConfig.sites)) {
+          pageConfig.sites.forEach((site) => {
+            if (!site || typeof site !== 'object') return;
+            copyLocalAsset(site.faviconUrl);
+          });
+        }
+
+        if (Array.isArray(pageConfig.categories)) {
+          const sites = [];
+          pageConfig.categories.forEach((category) => collectSitesRecursively(category, sites));
+          sites.forEach((site) => {
+            if (!site || typeof site !== 'object') return;
+            copyLocalAsset(site.faviconUrl);
+          });
+        }
+      });
+    }
+  } catch (e) {
+    log.error('复制 faviconUrl 本地资源失败', { message: e && e.message ? e.message : String(e) });
+    if (isVerbose() && e && e.stack) console.error(e.stack);
+  }
+
+  // 如果配置了 favicon，确保文件存在并复制
+  if (config.site.favicon) {
+    try {
+      if (fs.existsSync(`assets/${config.site.favicon}`)) {
+        fs.copyFileSync(
+          `assets/${config.site.favicon}`,
+          `dist/${path.basename(config.site.favicon)}`
+        );
+      } else if (fs.existsSync(config.site.favicon)) {
+        fs.copyFileSync(config.site.favicon, `dist/${path.basename(config.site.favicon)}`);
+      } else {
+        log.warn('favicon 文件不存在', { path: config.site.favicon });
+      }
+    } catch (e) {
+      log.error('复制 favicon 失败', { message: e && e.message ? e.message : String(e) });
+      if (isVerbose() && e && e.stack) console.error(e.stack);
+    }
+  }
+}
+
+// 主函数
+function main() {
+  const cmdLog = createLogger('generate');
+  const configLog = createLogger('config');
+  const renderLog = createLogger('render');
+  const elapsedMs = startTimer();
+
+  cmdLog.info('开始', { version: process.env.npm_package_version });
+
+  let source = 'unknown';
+  if (fs.existsSync('config/user')) source = 'config/user';
+  else if (fs.existsSync('config/_default')) source = 'config/_default';
+  configLog.info('加载模块化配置', { source });
+
+  const config = loadConfig();
+
+  try {
+    // 确保 dist 目录存在
+    if (!fs.existsSync('dist')) {
+      fs.mkdirSync('dist', { recursive: true });
+    }
+
+    renderLog.info('生成页面', {
+      pages: Array.isArray(config.navigation) ? config.navigation.length : 0,
+    });
+
+    // 初始化 Handlebars 模板系统
+    loadHandlebarsTemplates();
+
+    // 使用 generateHTML 函数生成完整的 HTML
+    const htmlContent = generateHTML(config);
+
+    // 生成 HTML
+    fs.writeFileSync('dist/index.html', htmlContent);
+
+    // 扩展专用配置：独立静态文件（按需加载）
+    try {
+      const extensionConfig =
+        config && config.extensionConfig ? JSON.stringify(config.extensionConfig, null, 2) : '';
+      if (extensionConfig) {
+        fs.writeFileSync(path.join('dist', MENAV_EXTENSION_CONFIG_FILE), extensionConfig);
+      }
+    } catch (error) {
+      cmdLog.warn('写入扩展配置文件失败（不影响页面渲染）', {
+        message: error && error.message ? error.message : String(error),
+      });
+      if (isVerbose() && error && error.stack) console.error(error.stack);
+    }
+
+    // GitHub Pages 静态路由回退：用于支持 /<id> 形式的路径深链接
+    fs.writeFileSync('dist/404.html', generate404Html(config));
+
+    // 构建运行时脚本（bundle → dist/script.js）
+    try {
+      execFileSync(process.execPath, [path.join(process.cwd(), 'scripts', 'build-runtime.js')], {
+        stdio: 'inherit',
+      });
+    } catch (error) {
+      throw new BuildError('构建运行时脚本失败', {
+        脚本路径: 'scripts/build-runtime.js',
+        错误信息: error.message,
+      });
+    }
+
+    // 复制静态文件
+    copyStaticFiles(config);
+
+    cmdLog.ok('完成', { ms: elapsedMs(), dist: 'dist/' });
+  } catch (e) {
+    // 如果是自定义错误，直接抛出，保留上下文/路径信息
+    if (
+      e instanceof ConfigError ||
+      e instanceof TemplateError ||
+      e instanceof BuildError ||
+      e instanceof FileError
+    ) {
+      throw e;
+    }
+
+    // 否则包装为 BuildError（避免直接暴露底层异常）
+    throw new BuildError('构建过程中发生错误', {
+      错误类型: e.name || 'Error',
+      错误信息: e.message || '未知错误',
+    });
+  }
+}
+
+if (require.main === module) {
+  // 使用 wrapAsyncError 包装主函数，自动处理错误
+  wrapAsyncError(main)();
+}
+
+// 导出供测试使用的函数
+module.exports = {
+  main,
+  loadConfig,
+  generateHTML,
+  generate404Html,
+  copyStaticFiles,
+  generateNavigation,
+  generateCategories,
+  loadHandlebarsTemplates,
+  renderTemplate,
+  generateAllPagesHTML,
+};
diff --git a/src/generator/template/engine.js b/src/generator/template/engine.js
new file mode 100644
index 0000000000000000000000000000000000000000..100ffb6ba3c4e4fd18262c48a6f2ac73cc015555
--- /dev/null
+++ b/src/generator/template/engine.js
@@ -0,0 +1,127 @@
+const fs = require('node:fs');
+const path = require('node:path');
+const Handlebars = require('handlebars');
+
+const { registerAllHelpers } = require('../../helpers');
+const { createLogger, isVerbose } = require('../utils/logger');
+
+const log = createLogger('template');
+
+const handlebars = Handlebars.create();
+registerAllHelpers(handlebars);
+
+function loadHandlebarsTemplates() {
+  const templatesDir = path.join(process.cwd(), 'templates');
+
+  if (!fs.existsSync(templatesDir)) {
+    throw new Error('Templates directory not found. Cannot proceed without templates.');
+  }
+
+  const layoutsDir = path.join(templatesDir, 'layouts');
+  if (!fs.existsSync(layoutsDir)) {
+    throw new Error('Layouts directory not found. Cannot proceed without layout templates.');
+  }
+
+  fs.readdirSync(layoutsDir)
+    .filter((file) => file.endsWith('.hbs'))
+    .sort()
+    .forEach((file) => {
+      const layoutName = path.basename(file, '.hbs');
+      const layoutPath = path.join(layoutsDir, file);
+      const layoutContent = fs.readFileSync(layoutPath, 'utf8');
+      handlebars.registerPartial(layoutName, layoutContent);
+    });
+
+  const componentsDir = path.join(templatesDir, 'components');
+  if (!fs.existsSync(componentsDir)) {
+    throw new Error('Components directory not found. Cannot proceed without component templates.');
+  }
+
+  fs.readdirSync(componentsDir)
+    .filter((file) => file.endsWith('.hbs'))
+    .sort()
+    .forEach((file) => {
+      const componentName = path.basename(file, '.hbs');
+      const componentPath = path.join(componentsDir, file);
+      const componentContent = fs.readFileSync(componentPath, 'utf8');
+      handlebars.registerPartial(componentName, componentContent);
+    });
+
+  const defaultLayoutPath = path.join(layoutsDir, 'default.hbs');
+  if (!fs.existsSync(defaultLayoutPath)) {
+    throw new Error('Default layout template not found. Cannot proceed without default layout.');
+  }
+}
+
+function getDefaultLayoutTemplate() {
+  const defaultLayoutPath = path.join(process.cwd(), 'templates', 'layouts', 'default.hbs');
+
+  if (!fs.existsSync(defaultLayoutPath)) {
+    throw new Error('Default layout template not found. Cannot proceed without default layout.');
+  }
+
+  try {
+    const layoutContent = fs.readFileSync(defaultLayoutPath, 'utf8');
+    const layoutTemplate = handlebars.compile(layoutContent);
+
+    return {
+      path: defaultLayoutPath,
+      template: layoutTemplate,
+    };
+  } catch (error) {
+    throw new Error(`Error loading default layout template: ${error.message}`);
+  }
+}
+
+function renderTemplate(templateName, data, useLayout = true) {
+  const templatePath = path.join(process.cwd(), 'templates', 'pages', `${templateName}.hbs`);
+
+  if (!fs.existsSync(templatePath)) {
+    const genericTemplatePath = path.join(process.cwd(), 'templates', 'pages', 'page.hbs');
+
+    if (!fs.existsSync(genericTemplatePath)) {
+      throw new Error(
+        `Template ${templateName}.hbs not found and generic template page.hbs not found. Cannot proceed without template.`
+      );
+    }
+
+    if (isVerbose()) {
+      log.info('页面模板不存在，已回退到通用模板 page.hbs', { template: `${templateName}.hbs` });
+    } else {
+      log.warn('页面模板不存在，已回退到通用模板 page.hbs', { template: `${templateName}.hbs` });
+    }
+    const genericTemplateContent = fs.readFileSync(genericTemplatePath, 'utf8');
+    const genericTemplate = handlebars.compile(genericTemplateContent);
+
+    const enhancedData = {
+      ...data,
+      pageId: data && data.pageId ? data.pageId : templateName,
+    };
+
+    const pageContent = genericTemplate(enhancedData);
+    if (!useLayout) return pageContent;
+
+    const { template: layoutTemplate } = getDefaultLayoutTemplate();
+    return layoutTemplate({ ...enhancedData, body: pageContent });
+  }
+
+  try {
+    const templateContent = fs.readFileSync(templatePath, 'utf8');
+    const template = handlebars.compile(templateContent);
+
+    const pageContent = template(data);
+    if (!useLayout) return pageContent;
+
+    const { template: layoutTemplate } = getDefaultLayoutTemplate();
+    return layoutTemplate({ ...data, body: pageContent });
+  } catch (error) {
+    throw new Error(`Error rendering template ${templateName}: ${error.message}`);
+  }
+}
+
+module.exports = {
+  handlebars,
+  loadHandlebarsTemplates,
+  getDefaultLayoutTemplate,
+  renderTemplate,
+};
diff --git a/src/generator/utils/errors.js b/src/generator/utils/errors.js
new file mode 100644
index 0000000000000000000000000000000000000000..248bf509ba2e185dab29dc6ea9e901ac6eb3c767
--- /dev/null
+++ b/src/generator/utils/errors.js
@@ -0,0 +1,131 @@
+/**
+ * 自定义错误类 - 配置相关错误
+ */
+class ConfigError extends Error {
+  constructor(message, suggestions = []) {
+    super(message);
+    this.name = 'ConfigError';
+    this.suggestions = suggestions;
+  }
+}
+
+/**
+ * 自定义错误类 - 模板相关错误
+ */
+class TemplateError extends Error {
+  constructor(message, templatePath = null) {
+    super(message);
+    this.name = 'TemplateError';
+    this.templatePath = templatePath;
+  }
+}
+
+/**
+ * 自定义错误类 - 构建相关错误
+ */
+class BuildError extends Error {
+  constructor(message, context = {}) {
+    super(message);
+    this.name = 'BuildError';
+    this.context = context;
+  }
+}
+
+/**
+ * 自定义错误类 - 文件操作相关错误
+ */
+class FileError extends Error {
+  constructor(message, filePath = null, suggestions = []) {
+    super(message);
+    this.name = 'FileError';
+    this.filePath = filePath;
+    this.suggestions = suggestions;
+  }
+}
+
+/**
+ * 统一错误处理器 - 专业紧凑版（中文）
+ * @param {Error} error - 错误对象
+ * @param {number} exitCode - 退出码，默认为 1
+ */
+function handleError(error, exitCode = 1) {
+  const { formatPrefix, isVerbose } = require('./logger');
+
+  // 错误标题行
+  console.error(`\n${formatPrefix('ERROR')} ${error.name}: ${error.message}`);
+
+  // 文件路径（如果有）
+  if (error.filePath || error.templatePath) {
+    const path = error.filePath || error.templatePath;
+    console.error(`位置: ${path}`);
+  }
+
+  // 上下文信息（如果有）
+  if (error.context && Object.keys(error.context).length > 0) {
+    console.error('上下文:');
+    for (const [key, value] of Object.entries(error.context)) {
+      console.error(`  ${key}: ${value}`);
+    }
+  }
+
+  // 修复建议（如果有）
+  if (error.suggestions && error.suggestions.length > 0) {
+    console.error('建议:');
+    error.suggestions.forEach((suggestion, index) => {
+      console.error(`  ${index + 1}) ${suggestion}`);
+    });
+  }
+
+  // DEBUG 提示（仅在非 DEBUG 模式下显示）
+  if (process.env.DEBUG) {
+    console.error('\n堆栈:');
+    console.error(error.stack || String(error));
+  } else if (isVerbose() && error && error.stack) {
+    console.error('\n堆栈:');
+    console.error(error.stack);
+  } else {
+    console.error('\n提示: DEBUG=1 查看堆栈');
+  }
+
+  console.error(); // 空行结束
+  process.exit(exitCode);
+}
+
+/**
+ * 包装异步函数，自动处理未捕获的错误
+ * @param {Function} fn - 异步函数
+ * @returns {Function} 包装后的函数
+ */
+function wrapAsyncError(fn) {
+  return async (...args) => {
+    try {
+      return await fn(...args);
+    } catch (error) {
+      // 如果是自定义错误，直接使用 handleError
+      if (
+        error instanceof ConfigError ||
+        error instanceof TemplateError ||
+        error instanceof BuildError ||
+        error instanceof FileError
+      ) {
+        handleError(error);
+      } else {
+        // 否则包装为 BuildError
+        handleError(
+          new BuildError(error.message || '未知错误', {
+            原始错误类型: error.name || 'Error',
+          })
+        );
+      }
+    }
+  };
+}
+
+module.exports = {
+  ConfigError,
+  TemplateError,
+  BuildError,
+  FileError,
+  handleError,
+  wrapAsyncError,
+};
diff --git a/src/generator/utils/githubContributions.js b/src/generator/utils/githubContributions.js
new file mode 100644
index 0000000000000000000000000000000000000000..a8c17deaa94f097164bc5e23999fc8b1134f3f60
--- /dev/null
+++ b/src/generator/utils/githubContributions.js
@@ -0,0 +1,71 @@
+/**
+ * 从 GitHub contributions 页面 HTML 中提取 `.js-yearly-contributions` 的 innerHTML。
+ *
+ * 说明：
+ * - 该页面是 HTML（非稳定 API），结构可能变化；这里做 best-effort 解析。
+ * - 为避免引入额外依赖，使用轻量的 div 匹配算法。
+ *
+ * @param {string} html 完整 HTML 文本
+ * @returns {string|null} `.js-yearly-contributions` 的 innerHTML
+ */
+function extractYearlyContributionsInnerHtml(html) {
+  const source = String(html || '');
+  if (!source) return null;
+
+  const marker = 'js-yearly-contributions';
+  const markerIndex = source.indexOf(marker);
+  if (markerIndex < 0) return null;
+
+  // 找到包含该 class 的 <div ...> 起始位置
+  const openTagStart = source.lastIndexOf('<div', markerIndex);
+  if (openTagStart < 0) return null;
+
+  // 通过匹配 <div ...> 与 </div> 的嵌套层级，定位该 div 的结束位置
+  let depth = 0;
+  let cursor = openTagStart;
+  let endIndex = -1;
+
+  while (cursor < source.length) {
+    const nextOpen = source.indexOf('<div', cursor);
+    const nextClose = source.indexOf('</div', cursor);
+
+    if (nextOpen === -1 && nextClose === -1) break;
+
+    const isOpen = nextOpen !== -1 && (nextClose === -1 || nextOpen < nextClose);
+    const tagIndex = isOpen ? nextOpen : nextClose;
+    const tagEnd = source.indexOf('>', tagIndex);
+    if (tagEnd === -1) break;
+
+    if (isOpen) {
+      depth += 1;
+    } else {
+      depth -= 1;
+      if (depth === 0) {
+        endIndex = tagEnd + 1;
+        break;
+      }
+    }
+
+    cursor = tagEnd + 1;
+  }
+
+  if (endIndex === -1) return null;
+
+  const outerHtml = source.slice(openTagStart, endIndex);
+  if (!outerHtml.includes(marker)) return null;
+
+  const openEnd = outerHtml.indexOf('>');
+  const closeStart = outerHtml.lastIndexOf('</div');
+  if (openEnd === -1 || closeStart === -1 || closeStart <= openEnd) return null;
+
+  let inner = outerHtml.slice(openEnd + 1, closeStart);
+
+  // 防御性处理：移除潜在的 script 标签（理论上 GitHub 片段不包含）
+  inner = inner.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, '');
+
+  return inner.trim() ? inner : null;
+}
+
+module.exports = {
+  extractYearlyContributionsInnerHtml,
+};
diff --git a/src/generator/utils/html.js b/src/generator/utils/html.js
new file mode 100644
index 0000000000000000000000000000000000000000..ef2f8f5b4e0bb5752af084071a455382a488b9a6
--- /dev/null
+++ b/src/generator/utils/html.js
@@ -0,0 +1,16 @@
+// HTML 转义函数，防止 XSS 攻击
+function escapeHtml(unsafe) {
+  if (unsafe === undefined || unsafe === null) {
+    return '';
+  }
+  return String(unsafe)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/\"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+module.exports = {
+  escapeHtml,
+};
diff --git a/src/generator/utils/logger.js b/src/generator/utils/logger.js
new file mode 100644
index 0000000000000000000000000000000000000000..207e3e7df834fea76a9ba84cd95c8e5cac0de174
--- /dev/null
+++ b/src/generator/utils/logger.js
@@ -0,0 +1,78 @@
+function parseBooleanEnv(value) {
+  if (value === undefined || value === null || value === '') return false;
+  const v = String(value).trim().toLowerCase();
+  return v === '1' || v === 'true' || v === 'yes' || v === 'y' || v === 'on';
+}
+
+function isVerbose() {
+  return parseBooleanEnv(process.env.MENAV_VERBOSE) || parseBooleanEnv(process.env.DEBUG);
+}
+
+function isColorEnabled() {
+  if (process.env.NO_COLOR) return false;
+  if (parseBooleanEnv(process.env.FORCE_COLOR)) return true;
+  return Boolean(
+    (process.stdout && process.stdout.isTTY) || (process.stderr && process.stderr.isTTY)
+  );
+}
+
+function colorize(text, ansiCode) {
+  if (!ansiCode || !isColorEnabled()) return text;
+  return `\x1b[${ansiCode}m${text}\x1b[0m`;
+}
+
+function formatMeta(meta) {
+  if (!meta || typeof meta !== 'object') return '';
+  const entries = Object.entries(meta)
+    .filter(([, value]) => value !== undefined && value !== null && value !== '')
+    .map(([key, value]) => `${key}=${String(value)}`);
+  if (entries.length === 0) return '';
+  return ` (${entries.join(', ')})`;
+}
+
+function formatPrefix(level) {
+  const base = `[${level}]`;
+  if (level === 'ERROR') return colorize(base, 31);
+  if (level === 'WARN') return colorize(base, 33);
+  if (level === 'OK') return colorize(base, 32);
+  return base;
+}
+
+function writeLine(level, scope, message, meta) {
+  const prefix = formatPrefix(level);
+  const scopePart = scope ? ` ${scope}:` : '';
+  const line = `${prefix}${scopePart} ${message}${formatMeta(meta)}`;
+
+  if (level === 'ERROR') {
+    console.error(line);
+  } else if (level === 'WARN') {
+    console.warn(line);
+  } else {
+    console.log(line);
+  }
+}
+
+function createLogger(scope) {
+  const normalized = scope ? String(scope) : '';
+  return {
+    info: (message, meta) => writeLine('INFO', normalized, message, meta),
+    warn: (message, meta) => writeLine('WARN', normalized, message, meta),
+    error: (message, meta) => writeLine('ERROR', normalized, message, meta),
+    ok: (message, meta) => writeLine('OK', normalized, message, meta),
+  };
+}
+
+function startTimer() {
+  const startedAt = process.hrtime.bigint();
+  return () => Number((process.hrtime.bigint() - startedAt) / 1_000_000n);
+}
+
+module.exports = {
+  createLogger,
+  formatMeta,
+  formatPrefix,
+  isColorEnabled,
+  isVerbose,
+  parseBooleanEnv,
+  startTimer,
+};
diff --git a/src/generator/utils/pageMeta.js b/src/generator/utils/pageMeta.js
new file mode 100644
index 0000000000000000000000000000000000000000..3e79775f8b93afb106713e68effe43d8bbed403d
--- /dev/null
+++ b/src/generator/utils/pageMeta.js
@@ -0,0 +1,100 @@
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+/**
+ * 解析页面配置文件路径（优先 user，回退 _default）
+ * 注意：仅用于构建期读取文件元信息，不会把路径注入到页面/扩展配置中。
+ * @param {string} pageId 页面ID（与 pages/<id>.yml 文件名对应）
+ * @returns {string|null} 文件路径或 null
+ */
+function resolvePageConfigFilePath(pageId) {
+  if (!pageId) return null;
+
+  const candidates = [
+    path.join(process.cwd(), 'config', 'user', 'pages', `${pageId}.yml`),
+    path.join(process.cwd(), 'config', 'user', 'pages', `${pageId}.yaml`),
+    path.join(process.cwd(), 'config', '_default', 'pages', `${pageId}.yml`),
+    path.join(process.cwd(), 'config', '_default', 'pages', `${pageId}.yaml`),
+  ];
+
+  for (const filePath of candidates) {
+    try {
+      if (fs.existsSync(filePath)) return filePath;
+    } catch (e) {
+      // 忽略 IO 异常，继续尝试下一个候选
+    }
+  }
+
+  return null;
+}
+
+/**
+ * 尝试获取文件最后一次 git 提交时间（ISO 字符串）
+ * @param {string} filePath 文件路径
+ * @returns {string|null} ISO 字符串（UTC），失败返回 null
+ */
+function tryGetGitLastCommitIso(filePath) {
+  if (!filePath) return null;
+
+  try {
+    const relativePath = path.relative(process.cwd(), filePath).replace(/\\/g, '/');
+    const output = execFileSync('git', ['log', '-1', '--format=%cI', '--', relativePath], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    const raw = String(output || '').trim();
+    if (!raw) return null;
+
+    const date = new Date(raw);
+    if (Number.isNaN(date.getTime())) return null;
+
+    return date.toISOString();
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 获取文件 mtime（ISO 字符串）
+ * @param {string} filePath 文件路径
+ * @returns {string|null} ISO 字符串（UTC），失败返回 null
+ */
+function tryGetFileMtimeIso(filePath) {
+  if (!filePath) return null;
+
+  try {
+    const stats = fs.statSync(filePath);
+    const mtime = stats && stats.mtime ? stats.mtime : null;
+    if (!(mtime instanceof Date) || Number.isNaN(mtime.getTime())) return null;
+    return mtime.toISOString();
+  } catch (e) {
+    return null;
+  }
+}
+
+/**
+ * 计算页面配置文件“内容更新时间”（优先 git，回退 mtime）
+ * @param {string} pageId 页面ID
+ * @returns {{updatedAt: string, updatedAtSource: 'git'|'mtime'}|null}
+ */
+function getPageConfigUpdatedAtMeta(pageId) {
+  const filePath = resolvePageConfigFilePath(pageId);
+  if (!filePath) return null;
+
+  const gitIso = tryGetGitLastCommitIso(filePath);
+  if (gitIso) {
+    return { updatedAt: gitIso, updatedAtSource: 'git' };
+  }
+
+  const mtimeIso = tryGetFileMtimeIso(filePath);
+  if (mtimeIso) {
+    return { updatedAt: mtimeIso, updatedAtSource: 'mtime' };
+  }
+
+  return null;
+}
+
+module.exports = {
+  getPageConfigUpdatedAtMeta,
+};
diff --git a/src/generator/utils/sites.js b/src/generator/utils/sites.js
new file mode 100644
index 0000000000000000000000000000000000000000..a5eae3f530d62230a47a12df890c74b8bbb029d1
--- /dev/null
+++ b/src/generator/utils/sites.js
@@ -0,0 +1,35 @@
+function normalizeUrlKey(input) {
+  if (!input) return '';
+  try {
+    const u = new URL(String(input));
+    const origin = u.origin;
+    let pathname = u.pathname || '/';
+    // 统一去掉末尾斜杠（根路径除外），避免 https://a.com 与 https://a.com/ 不匹配
+    if (pathname !== '/' && pathname.endsWith('/')) pathname = pathname.slice(0, -1);
+    return `${origin}${pathname}`;
+  } catch {
+    return String(input).trim();
+  }
+}
+
+function collectSitesRecursively(node, output) {
+  if (!node || typeof node !== 'object') return;
+
+  if (Array.isArray(node.subcategories))
+    node.subcategories.forEach((child) => collectSitesRecursively(child, output));
+  if (Array.isArray(node.groups))
+    node.groups.forEach((child) => collectSitesRecursively(child, output));
+  if (Array.isArray(node.subgroups))
+    node.subgroups.forEach((child) => collectSitesRecursively(child, output));
+
+  if (Array.isArray(node.sites)) {
+    node.sites.forEach((site) => {
+      if (site && typeof site === 'object') output.push(site);
+    });
+  }
+}
+
+module.exports = {
+  normalizeUrlKey,
+  collectSitesRecursively,
+};
diff --git a/src/helpers/README.md b/src/helpers/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..92bdd2de612011cb0d92f749c969f9bd64c4cbbf
--- /dev/null
+++ b/src/helpers/README.md
@@ -0,0 +1,447 @@
+# MeNav Handlebars 助手函数说明文档
+
+## 目录
+
+- [助手函数概述](#助手函数概述)
+- [助手函数分类](#助手函数分类)
+  - [格式化函数](#格式化函数)
+  - [条件判断函数](#条件判断函数)
+  - [工具函数](#工具函数)
+  - [核心函数](#核心函数)
+- [使用方法](#使用方法)
+- [函数详解](#函数详解)
+- [扩展指南](#扩展指南)
+- [最佳实践](#最佳实践)
+
+## 助手函数概述
+
+MeNav 项目使用 Handlebars 助手函数扩展模板功能，使模板更加强大和灵活。助手函数可用于：
+
+- 数据格式化（日期、文本等）
+- 条件判断和逻辑控制
+- 数组与对象操作
+- HTML 安全处理
+
+所有助手函数都在 `src/helpers/` 目录下定义，并通过 `src/helpers/index.js` 统一注册到 Handlebars 实例。
+
+## 助手函数分类
+
+MeNav 的助手函数分为四类：
+
+### 格式化函数
+
+位置：`src/helpers/formatters.js`
+
+提供各种数据格式化功能，包括：
+
+- 日期格式化
+- 文本长度限制
+- 大小写转换
+- 调试数据显示
+
+### 条件判断函数
+
+位置：`src/helpers/conditions.js`
+
+提供条件判断与逻辑操作功能，包括：
+
+- 相等与不等判断
+- 通用比较操作
+- 空值检查
+- 逻辑运算（与、或、非）
+
+#### ifHttpUrl
+
+判断字符串是否为 http/https URL，用于在模板中分支渲染仅对外链生效的逻辑（如 favicon 加载）：
+
+```handlebars
+{{#ifHttpUrl url}}
+  {{! 只有 http/https 才尝试加载 favicon }}
+  <img
+    src='https://t3.gstatic.com/faviconV2?url={{encodeURIComponent url}}&size=32&drop_404_icon=true'
+    alt='{{name}} favicon'
+  />
+{{else}}
+  <i class='fas fa-link'></i>
+{{/ifHttpUrl}}
+```
+
+### 工具函数
+
+位置：`src/helpers/utils.js`
+
+提供各种实用工具功能，包括：
+
+- 数组与字符串操作
+- 集合长度计算
+- 范围数组生成
+- 对象属性选择
+
+#### encodeURIComponent
+
+对字符串进行 URL 组件编码（同名于浏览器 API，用作模板内联助手），适用于将动态 URL 参数安全拼接到查询串：
+
+```handlebars
+{{! 构造第三方 Favicon API 的 url 参数 }}
+<img
+  src='https://t3.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&url={{encodeURIComponent
+    url
+  }}&size=32&drop_404_icon=true'
+  alt='favicon'
+/>
+```
+
+### 核心函数
+
+位置：`src/helpers/index.js`
+
+提供基础的 HTML 处理功能：
+
+- HTML 转义
+- 安全输出 HTML
+
+## 使用方法
+
+在 Handlebars 模板中使用助手函数有多种方式：
+
+### 1. 内联表达式
+
+用于生成内容的助手函数：
+
+```handlebars
+{{formatDate created 'YYYY-MM-DD'}}
+{{limit description 100}}
+{{json data}}
+```
+
+### 2. 块级表达式
+
+用于控制结构的助手函数：
+
+```handlebars
+{{#ifEquals type 'article'}}
+  <span class='badge'>文章</span>
+{{else}}
+  <span class='badge'>页面</span>
+{{/ifEquals}}
+
+{{#each (range 1 5)}}
+  <span>{{this}}</span>
+{{/each}}
+```
+
+### 3. 助手函数组合
+
+多个助手函数可以组合使用：
+
+```handlebars
+{{#each (slice items 0 5)}}
+  <li>{{toUpperCase name}}</li>
+{{/each}}
+```
+
+## 函数详解
+
+### 格式化函数
+
+#### formatDate
+
+格式化日期：
+
+```handlebars
+{{formatDate date 'YYYY-MM-DD'}}
+{{! 2023-05-15 }}
+{{formatDate date 'YYYY年MM月DD日'}}
+{{! 2023年05月15日 }}
+{{formatDate date 'YYYY-MM-DD HH:mm:ss'}}
+{{! 2023-05-15 14:30:00 }}
+```
+
+支持的格式：
+
+- `YYYY`: 四位年份
+- `MM`: 两位月份
+- `DD`: 两位日期
+- `HH`: 两位小时（24小时制）
+- `mm`: 两位分钟
+- `ss`: 两位秒数
+
+#### limit
+
+限制文本长度，超出部分显示省略号：
+
+```handlebars
+{{limit '这是一段很长的文本内容' 5}} {{! 这是一段... }}
+```
+
+#### toLowerCase / toUpperCase
+
+转换文本大小写：
+
+```handlebars
+{{toLowerCase 'Hello'}}
+{{! hello }}
+{{toUpperCase 'world'}}
+{{! WORLD }}
+```
+
+#### json
+
+将对象转换为 JSON 字符串（用于调试）：
+
+```handlebars
+{{json this}}
+```
+
+#### extractDomain
+
+从 URL 中提取“干净的域名”（不包含协议、路径与查询串），常用于站点描述兜底显示：
+
+```handlebars
+{{extractDomain url}}
+```
+
+### 条件判断函数
+
+#### ifEquals / ifNotEquals
+
+比较两个值是否相等/不相等：
+
+```handlebars
+{{#ifEquals status 'active'}}
+  当前状态：活跃
+{{else}}
+  当前状态：非活跃
+{{/ifEquals}}
+```
+
+#### ifCond
+
+通用条件比较：
+
+```handlebars
+{{#ifCond count '>' 0}}
+  有
+  {{count}}
+  个项目
+{{else}}
+  没有项目
+{{/ifCond}}
+```
+
+支持的运算符：
+
+- `==`, `===`, `!=`, `!==`
+- `<`, `<=`, `>`, `>=`
+- `&&`, `||`
+
+#### isEmpty / isNotEmpty
+
+检查值是否为空：
+
+```handlebars
+{{#isEmpty items}}
+  <p>暂无数据</p>
+{{else}}
+  <ul>
+    {{#each items}}
+      <li>{{this}}</li>
+    {{/each}}
+  </ul>
+{{/isEmpty}}
+```
+
+#### and / or / not
+
+逻辑操作：
+
+```handlebars
+{{#and isPremium isActive}}
+  高级活跃用户
+{{/and}}
+
+{{#or isPremium isAdmin}}
+  有访问权限
+{{/or}}
+
+{{#not isDisabled}}
+  此功能可用
+{{/not}}
+```
+
+### 工具函数
+
+#### slice
+
+数组或字符串切片：
+
+```handlebars
+{{#each (slice array 0 3)}}
+  <li>{{this}}</li>
+{{/each}}
+```
+
+#### concat
+
+合并数组：
+
+```handlebars
+{{#each (concat array1 array2)}}
+  <li>{{this}}</li>
+{{/each}}
+```
+
+#### size
+
+获取数组、字符串或对象的长度/大小：
+
+```handlebars
+总共 {{size items}} 个项目
+```
+
+#### first / last
+
+获取数组的第一个/最后一个元素：
+
+```handlebars
+第一项:
+{{first items}}
+最后一项:
+{{last items}}
+```
+
+#### range
+
+创建一个连续范围的数组：
+
+```handlebars
+{{#each (range 1 5)}}
+  <span>{{this}}</span>
+{{/each}}
+```
+
+#### pick
+
+从对象中选择指定的属性：
+
+```handlebars
+{{json (pick user 'name' 'email')}}
+```
+
+#### keys
+
+将对象的所有键转换为数组：
+
+```handlebars
+{{#each (keys object)}}
+  <li>{{this}}</li>
+{{/each}}
+```
+
+#### encodeURIComponent
+
+对字符串做 URL 组件编码，常用于拼接第三方请求参数（例如 favicon 的 `url=` 参数）：
+
+```handlebars
+{{encodeURIComponent url}}
+```
+
+#### add
+
+数字加法，用于根据层级动态计算标题级别等场景：
+
+```handlebars
+<h{{add level 1}}>...</h{{add level 1}}>
+```
+
+### 核心函数
+
+#### escapeHtml
+
+转义 HTML 特殊字符：
+
+```handlebars
+{{escapeHtml content}}
+```
+
+#### safeHtml
+
+安全输出 HTML（不转义）：
+
+```handlebars
+{{safeHtml htmlContent}}
+```
+
+## 扩展指南
+
+### 添加新的助手函数
+
+1. 选择适当的分类文件（`formatters.js`、`conditions.js` 或 `utils.js`）
+2. 添加新的函数并导出
+3. 函数会自动通过 `index.js` 中的 `registerAllHelpers` 注册
+
+示例：添加一个新的格式化函数到 `formatters.js`：
+
+```javascript
+/**
+ * 将数字格式化为带千位分隔符的字符串
+ * @param {number} number 要格式化的数字
+ * @returns {string} 格式化后的字符串
+ * @example {{formatNumber 1000000}} -> 1,000,000
+ */
+function formatNumber(number) {
+  if (typeof number !== 'number') return '';
+  return number.toLocaleString();
+}
+
+// 在导出中添加新函数
+module.exports = {
+  formatDate,
+  limit,
+  toLowerCase,
+  toUpperCase,
+  json,
+  formatNumber, // 添加新函数
+};
+```
+
+### 添加新的分类
+
+如果需要添加新的分类：
+
+1. 在 `src/helpers/` 创建新的 JS 文件
+2. 在 `index.js` 中导入并注册新的助手函数集
+
+```javascript
+const newHelpers = require('./new-helpers');
+
+function registerAllHelpers(handlebars) {
+  // 现有注册代码...
+
+  // 注册新的助手函数
+  Object.entries(newHelpers).forEach(([name, helper]) => {
+    handlebars.registerHelper(name, helper);
+  });
+}
+```
+
+## 最佳实践
+
+1. **文档化函数** - 使用 JSDoc 风格为所有函数添加文档注释
+   - 描述函数功能
+   - 列出参数和返回值
+   - 提供使用示例
+
+2. **参数校验** - 增加参数类型和有效性检查
+   - 检查必要参数是否存在
+   - 验证参数类型
+   - 为无效输入提供默认值或空结果
+
+3. **命名规范**
+   - 使用描述性名称，清晰表达函数用途
+   - 遵循现有命名风格（如 `kebab-case`）
+   - 保持命名一致性（如条件判断函数以 `is` 或 `if` 开头）
+
+4. **避免副作用** - 助手函数应为纯函数，不修改传入的数据
+
+5. **保持简单** - 每个助手函数应只完成一个明确的任务
diff --git a/src/helpers/conditions.js b/src/helpers/conditions.js
new file mode 100644
index 0000000000000000000000000000000000000000..d02c0e3bebdf53fa17ca90634c5403143ba0a742
--- /dev/null
+++ b/src/helpers/conditions.js
@@ -0,0 +1,188 @@
+/**
+ * Handlebars条件判断助手函数
+ * 提供各种条件判断功能
+ */
+
+/**
+ * 比较两个值是否相等
+ * @param {any} v1 比较值1
+ * @param {any} v2 比较值2
+ * @param {object} options Handlebars选项
+ * @returns {string} 渲染结果
+ * @example {{#ifEquals type "article"}}文章{{else}}页面{{/ifEquals}}
+ */
+function ifEquals(v1, v2, options) {
+  return v1 === v2 ? options.fn(this) : options.inverse(this);
+}
+
+/**
+ * 比较两个值是否不相等
+ * @param {any} v1 比较值1
+ * @param {any} v2 比较值2
+ * @param {object} options Handlebars选项
+ * @returns {string} 渲染结果
+ * @example {{#ifNotEquals status "completed"}}进行中{{else}}已完成{{/ifNotEquals}}
+ */
+function ifNotEquals(v1, v2, options) {
+  return v1 !== v2 ? options.fn(this) : options.inverse(this);
+}
+
+/**
+ * 通用条件比较
+ * @param {any} v1 比较值1
+ * @param {string} operator 比较运算符 ('==', '===', '!=', '!==', '<', '<=', '>', '>=')
+ * @param {any} v2 比较值2
+ * @param {object} options Handlebars选项
+ * @returns {string} 渲染结果
+ * @example {{#ifCond count '>' 0}}有内容{{else}}无内容{{/ifCond}}
+ */
+function ifCond(v1, operator, v2, options) {
+  switch (operator) {
+    case '==':
+      return v1 == v2 ? options.fn(this) : options.inverse(this);
+    case '===':
+      return v1 === v2 ? options.fn(this) : options.inverse(this);
+    case '!=':
+      return v1 != v2 ? options.fn(this) : options.inverse(this);
+    case '!==':
+      return v1 !== v2 ? options.fn(this) : options.inverse(this);
+    case '<':
+      return v1 < v2 ? options.fn(this) : options.inverse(this);
+    case '<=':
+      return v1 <= v2 ? options.fn(this) : options.inverse(this);
+    case '>':
+      return v1 > v2 ? options.fn(this) : options.inverse(this);
+    case '>=':
+      return v1 >= v2 ? options.fn(this) : options.inverse(this);
+    case '&&':
+      return v1 && v2 ? options.fn(this) : options.inverse(this);
+    case '||':
+      return v1 || v2 ? options.fn(this) : options.inverse(this);
+    default:
+      return options.inverse(this);
+  }
+}
+
+/**
+ * 检查值是否为空（null、undefined、空字符串、空数组或空对象）
+ * @param {any} value 要检查的值
+ * @param {object} options Handlebars选项
+ * @returns {string} 渲染结果
+ * @example {{#isEmpty items}}无内容{{else}}有内容{{/isEmpty}}
+ */
+function isEmpty(value, options) {
+  if (value === null || value === undefined) {
+    return options.fn(this);
+  }
+
+  if (typeof value === 'string' && value.trim() === '') {
+    return options.fn(this);
+  }
+
+  if (Array.isArray(value) && value.length === 0) {
+    return options.fn(this);
+  }
+
+  if (typeof value === 'object' && Object.keys(value).length === 0) {
+    return options.fn(this);
+  }
+
+  return options.inverse(this);
+}
+
+/**
+ * 检查值是否非空
+ * @param {any} value 要检查的值
+ * @param {object} options Handlebars选项
+ * @returns {string} 渲染结果
+ * @example {{#isNotEmpty items}}有内容{{else}}无内容{{/isNotEmpty}}
+ */
+function isNotEmpty(value, options) {
+  return isEmpty(value, {
+    fn: options.inverse,
+    inverse: options.fn,
+  });
+}
+
+/**
+ * 条件与操作
+ * @param {any} a 条件A
+ * @param {any} b 条件B
+ * @param {object} options Handlebars选项
+ * @returns {string} 渲染结果
+ * @example {{#and isPremium isActive}}高级活跃用户{{else}}其他用户{{/and}}
+ */
+function and(a, b, options) {
+  return a && b ? options.fn(this) : options.inverse(this);
+}
+
+/**
+ * 条件或操作
+ * @param {any} a 条件A
+ * @param {any} b 条件B
+ * @param {object} options Handlebars选项
+ * @returns {string} 渲染结果
+ * @example {{#or isPremium isAdmin}}有权限{{else}}无权限{{/or}}
+ */
+function or(a, b, options) {
+  return a || b ? options.fn(this) : options.inverse(this);
+}
+
+/**
+ * 多个条件的或操作
+ * 使用方式：{{#or (ifEquals a b) (ifEquals c d)}}满足条件{{else}}不满足条件{{/or}}
+ * @param {...any} args 多个条件值
+ * @returns {boolean} 条件结果
+ */
+function orHelper() {
+  // 最后一个参数是options对象
+  const options = arguments[arguments.length - 1];
+
+  // 检查是否至少有一个为true的参数
+  for (let i = 0; i < arguments.length - 1; i++) {
+    if (arguments[i]) {
+      return options.fn(this);
+    }
+  }
+
+  return options.inverse(this);
+}
+
+/**
+ * 条件非操作
+ * @param {any} value 条件值
+ * @param {object} options Handlebars选项
+ * @returns {string} 渲染结果
+ * @example {{#not isDisabled}}启用{{else}}禁用{{/not}}
+ */
+function not(value, options) {
+  return !value ? options.fn(this) : options.inverse(this);
+}
+
+/**
+ * 判断URL是否为http/https
+ * @param {string} url 输入URL
+ * @param {object} options Handlebars选项
+ * @returns {string} 渲染结果
+ * @example {{#ifHttpUrl url}}...{{else}}...{{/ifHttpUrl}}
+ */
+function ifHttpUrl(url, options) {
+  if (typeof url === 'string' && /^https?:\/\//i.test(url)) {
+    return options.fn(this);
+  }
+  return options.inverse(this);
+}
+
+// 导出所有条件判断助手函数
+module.exports = {
+  ifEquals,
+  ifNotEquals,
+  ifCond,
+  isEmpty,
+  isNotEmpty,
+  and,
+  or,
+  orHelper,
+  not,
+  ifHttpUrl,
+};
diff --git a/src/helpers/formatters.js b/src/helpers/formatters.js
new file mode 100644
index 0000000000000000000000000000000000000000..af5cff93e4567d229092a43f4e096e0431c81d81
--- /dev/null
+++ b/src/helpers/formatters.js
@@ -0,0 +1,127 @@
+/**
+ * Handlebars格式化助手函数
+ * 提供日期、文本等格式化功能
+ */
+
+/**
+ * 格式化日期
+ * @param {Date|string} date 日期对象或日期字符串
+ * @param {string} format 格式化模式
+ * @returns {string} 格式化后的日期字符串
+ * @example {{formatDate date "YYYY-MM-DD"}}
+ */
+function formatDate(date, format) {
+  if (!date) return '';
+
+  // 将字符串转换为日期对象
+  const dateObj = typeof date === 'string' ? new Date(date) : date;
+
+  if (!(dateObj instanceof Date) || isNaN(dateObj)) {
+    return '';
+  }
+
+  // 获取日期组件
+  const year = dateObj.getFullYear();
+  const month = dateObj.getMonth() + 1;
+  const day = dateObj.getDate();
+  const hours = dateObj.getHours();
+  const minutes = dateObj.getMinutes();
+  const seconds = dateObj.getSeconds();
+
+  // 格式化日期字符串
+  if (!format) format = 'YYYY-MM-DD';
+
+  return format
+    .replace('YYYY', year)
+    .replace('MM', month.toString().padStart(2, '0'))
+    .replace('DD', day.toString().padStart(2, '0'))
+    .replace('HH', hours.toString().padStart(2, '0'))
+    .replace('mm', minutes.toString().padStart(2, '0'))
+    .replace('ss', seconds.toString().padStart(2, '0'));
+}
+
+/**
+ * 限制文本长度，超出部分显示省略号
+ * @param {string} text 输入文本
+ * @param {number} length 最大长度
+ * @returns {string} 处理后的文本
+ * @example {{limit description 100}}
+ */
+function limit(text, length) {
+  if (!text) return '';
+
+  text = String(text);
+
+  if (text.length <= length) {
+    return text;
+  }
+
+  return text.substring(0, length) + '...';
+}
+
+/**
+ * 转换文本为小写
+ * @param {string} text 输入文本
+ * @returns {string} 小写文本
+ * @example {{toLowerCase title}}
+ */
+function toLowerCase(text) {
+  if (!text) return '';
+  return String(text).toLowerCase();
+}
+
+/**
+ * 转换文本为大写
+ * @param {string} text 输入文本
+ * @returns {string} 大写文本
+ * @example {{toUpperCase code}}
+ */
+function toUpperCase(text) {
+  if (!text) return '';
+  return String(text).toUpperCase();
+}
+
+/**
+ * 将对象转换为JSON字符串（用于调试）
+ * @param {any} obj 要转换的对象
+ * @returns {string} JSON字符串
+ * @example {{json this}}
+ */
+function json(obj) {
+  return JSON.stringify(obj, null, 2);
+}
+
+/**
+ * 从URL中提取干净的域名
+ * @param {string} url 完整URL
+ * @returns {string} 提取的域名（不包含协议和尾部斜杠）
+ * @example {{extractDomain "https://app.follow.is/"}} => "app.follow.is"
+ */
+function extractDomain(url) {
+  if (!url) return '';
+
+  try {
+    // 移除协议部分 (http://, https://, etc.)
+    let domain = String(url).replace(/^[a-zA-Z]+:\/\//, '');
+
+    // 移除路径、查询参数和锚点
+    domain = domain.split('/')[0].split('?')[0].split('#')[0];
+
+    // 移除端口号（如果有）
+    domain = domain.split(':')[0];
+
+    return domain;
+  } catch (e) {
+    return String(url);
+  }
+}
+
+// 导出所有格式化助手函数
+module.exports = {
+  formatDate,
+  limit,
+  toLowerCase,
+  toUpperCase,
+  json,
+  extractDomain,
+};
diff --git a/src/helpers/index.js b/src/helpers/index.js
new file mode 100644
index 0000000000000000000000000000000000000000..90cbc97264ca4db3a975b6c6d427396b06db94d1
--- /dev/null
+++ b/src/helpers/index.js
@@ -0,0 +1,59 @@
+/**
+ * Handlebars助手函数中心
+ *
+ * 导入并重导出所有助手函数，方便在generator中统一注册
+ */
+
+const formatters = require('./formatters');
+const conditions = require('./conditions');
+const utils = require('./utils');
+
+/**
+ * 注册所有助手函数到Handlebars实例
+ * @param {Handlebars} handlebars Handlebars实例
+ */
+function registerAllHelpers(handlebars) {
+  // 注册格式化助手函数
+  Object.entries(formatters).forEach(([name, helper]) => {
+    handlebars.registerHelper(name, helper);
+  });
+
+  // 注册条件判断助手函数
+  Object.entries(conditions).forEach(([name, helper]) => {
+    handlebars.registerHelper(name, helper);
+  });
+
+  // 注册工具类助手函数
+  Object.entries(utils).forEach(([name, helper]) => {
+    handlebars.registerHelper(name, helper);
+  });
+
+  // 注册HTML转义函数（作为助手函数，方便在模板中调用）
+  handlebars.registerHelper('escapeHtml', function (text) {
+    if (text === undefined || text === null) {
+      return '';
+    }
+    return String(text)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#039;');
+  });
+
+  // 注册非转义助手函数（安全输出HTML）
+  handlebars.registerHelper('safeHtml', function (text) {
+    if (text === undefined || text === null) {
+      return '';
+    }
+    return new handlebars.SafeString(text);
+  });
+}
+
+// 导出所有助手函数和注册函数
+module.exports = {
+  formatters,
+  conditions,
+  utils,
+  registerAllHelpers,
+};
diff --git a/src/helpers/utils.js b/src/helpers/utils.js
new file mode 100644
index 0000000000000000000000000000000000000000..991d273ff4cf86cee0ea94b2bb544cf12d28c6b0
--- /dev/null
+++ b/src/helpers/utils.js
@@ -0,0 +1,320 @@
+/**
+ * Handlebars通用工具类助手函数
+ * 提供数组处理、字符串处理等实用功能
+ */
+
+/**
+ * 数组或字符串切片操作
+ * @param {Array|string} array 要处理的数组或字符串
+ * @param {number} start 起始索引
+ * @param {number} [end] 结束索引（可选）
+ * @returns {Array|string} 切片结果
+ * @example {{slice array 0 5}}
+ */
+function slice(array, start, end) {
+  if (!array) return [];
+
+  if (typeof array === 'string') {
+    return end ? array.slice(start, end) : array.slice(start);
+  }
+
+  if (Array.isArray(array)) {
+    return end ? array.slice(start, end) : array.slice(start);
+  }
+
+  return [];
+}
+
+/**
+ * 合并数组
+ * @param {...Array} arrays 要合并的数组
+ * @returns {Array} 合并后的数组
+ * @example {{concat array1 array2 array3}}
+ */
+function concat() {
+  const args = Array.from(arguments);
+  const options = args.pop(); // 最后一个参数是Handlebars的options对象
+
+  // 过滤掉非数组参数
+  const validArrays = args.filter((arg) => Array.isArray(arg));
+
+  if (validArrays.length === 0) {
+    return [];
+  }
+
+  return Array.prototype.concat.apply([], validArrays);
+}
+
+/**
+ * 获取数组或对象的长度/大小
+ * @param {Array|Object|string} value 要计算长度的值
+ * @returns {number} 长度或大小
+ * @example {{size array}}
+ */
+function size(value) {
+  if (!value) return 0;
+
+  if (Array.isArray(value) || typeof value === 'string') {
+    return value.length;
+  }
+
+  if (typeof value === 'object') {
+    return Object.keys(value).length;
+  }
+
+  return 0;
+}
+
+/**
+ * 获取数组的第一个元素
+ * @param {Array} array 数组
+ * @returns {any} 第一个元素
+ * @example {{first items}}
+ */
+function first(array) {
+  if (!array || !Array.isArray(array) || array.length === 0) {
+    return undefined;
+  }
+
+  return array[0];
+}
+
+/**
+ * 获取数组的最后一个元素
+ * @param {Array} array 数组
+ * @returns {any} 最后一个元素
+ * @example {{last items}}
+ */
+function last(array) {
+  if (!array || !Array.isArray(array) || array.length === 0) {
+    return undefined;
+  }
+
+  return array[array.length - 1];
+}
+
+/**
+ * 创建一个连续范围的数组（用于循环）
+ * @param {number} start 起始值
+ * @param {number} end 结束值
+ * @param {number} [step=1] 步长
+ * @returns {Array} 范围数组
+ * @example {{#each (range 1 5)}}{{this}}{{/each}}
+ */
+function range(start, end, step = 1) {
+  const result = [];
+
+  if (typeof start !== 'number' || typeof end !== 'number') {
+    return result;
+  }
+
+  if (step <= 0) {
+    step = 1;
+  }
+
+  for (let i = start; i <= end; i += step) {
+    result.push(i);
+  }
+
+  return result;
+}
+
+/**
+ * 从对象中选择指定的属性（创建新对象）
+ * @param {Object} object 源对象
+ * @param {...string} keys 要选择的属性键
+ * @returns {Object} 包含选定属性的新对象
+ * @example {{json (pick user "name" "email")}}
+ */
+function pick() {
+  const args = Array.from(arguments);
+  const options = args.pop(); // 最后一个参数是Handlebars的options对象
+
+  if (args.length < 1) {
+    return {};
+  }
+
+  const obj = args[0];
+  const keys = args.slice(1);
+
+  if (!obj || typeof obj !== 'object') {
+    return {};
+  }
+
+  const result = {};
+
+  keys.forEach((key) => {
+    if (obj.hasOwnProperty(key)) {
+      result[key] = obj[key];
+    }
+  });
+
+  return result;
+}
+
+/**
+ * 将对象的所有键转换为数组
+ * @param {Object} object 输入对象
+ * @returns {Array} 键数组
+ * @example {{#each (keys obj)}}{{this}}{{/each}}
+ */
+function keys(object) {
+  if (!object || typeof object !== 'object') {
+    return [];
+  }
+
+  return Object.keys(object);
+}
+
+/**
+ * 对字符串进行URL组件编码（encodeURIComponent）
+ * @param {string} text 输入文本
+ * @returns {string} 编码后的字符串
+ * @example {{encodeURIComponent url}}
+ */
+function encodeURIComponentHelper(text) {
+  if (text === undefined || text === null) return '';
+  try {
+    return encodeURIComponent(String(text));
+  } catch (e) {
+    return '';
+  }
+}
+
+/**
+ * 数学加法运算助手函数
+ * @param {number} a 第一个数
+ * @param {number} b 第二个数
+ * @returns {number} 两数之和
+ * @example {{add level 1}}
+ */
+function add(a, b) {
+  const numA = parseInt(a, 10) || 0;
+  const numB = parseInt(b, 10) || 0;
+  return numA + numB;
+}
+
+/**
+ * 根据 icons.region 配置生成 favicon URL
+ * @param {string} url 站点 URL
+ * @param {Object} options Handlebars options 对象
+ * @returns {string} favicon URL
+ * @example {{faviconV2Url url}}
+ */
+function faviconV2Url(url, options) {
+  if (!url) return '';
+
+  const region = options.data.root.icons?.region || 'com';
+  const domain = region === 'cn' ? 't3.gstatic.cn' : 't3.gstatic.com';
+
+  try {
+    const encodedUrl = encodeURIComponent(String(url));
+    // drop_404_icon=true：缺失 favicon 时返回空 404，避免“小地球”占位图并可靠触发 <img onerror> 回退
+    return `https://${domain}/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=${encodedUrl}&size=32&drop_404_icon=true`;
+  } catch (e) {
+    return '';
+  }
+}
+
+/**
+ * 根据 icons.region 配置生成 favicon 回退 URL
+ * @param {string} url 站点 URL
+ * @param {Object} options Handlebars options 对象
+ * @returns {string} favicon 回退 URL
+ * @example {{faviconFallbackUrl url}}
+ */
+function faviconFallbackUrl(url, options) {
+  if (!url) return '';
+
+  const region = options.data.root.icons?.region || 'com';
+  const domain = region === 'cn' ? 't3.gstatic.com' : 't3.gstatic.cn';
+
+  try {
+    const encodedUrl = encodeURIComponent(String(url));
+    // drop_404_icon=true：缺失 favicon 时返回空 404，避免“小地球”占位图并可靠触发 <img onerror> 回退
+    return `https://${domain}/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=${encodedUrl}&size=32&drop_404_icon=true`;
+  } catch (e) {
+    return '';
+  }
+}
+
+/**
+ * 安全 URL 输出：用于 href 等场景，防止 javascript: 等危险 scheme 变成可点击链接
+ * - 默认允许：http/https/mailto/tel + 相对链接（# / ./ ../ ?）
+ * - 允许通过 site.security.allowedSchemes 扩展白名单（例如 obsidian/vscode）
+ * @param {string} url 输入 URL
+ * @param {Object} options Handlebars options 对象
+ * @returns {string} 安全的 URL（不安全时返回 #）
+ * @example <a href="{{safeUrl url}}">...</a>
+ */
+function safeUrl(url, options) {
+  const raw = String(url || '').trim();
+  if (!raw) return '#';
+
+  // 允许相对链接
+  if (
+    raw.startsWith('#') ||
+    raw.startsWith('/') ||
+    raw.startsWith('./') ||
+    raw.startsWith('../') ||
+    raw.startsWith('?')
+  ) {
+    return raw;
+  }
+
+  // 拒绝协议相对 URL（//example.com），避免绕过策略
+  if (raw.startsWith('//')) {
+    console.warn(`[WARN] 已拦截不安全 URL（协议相对形式）：${raw}`);
+    return '#';
+  }
+
+  const allowedFromConfig =
+    options &&
+    options.data &&
+    options.data.root &&
+    options.data.root.site &&
+    options.data.root.site.security &&
+    options.data.root.site.security.allowedSchemes;
+
+  const allowedSchemes =
+    Array.isArray(allowedFromConfig) && allowedFromConfig.length > 0
+      ? allowedFromConfig
+          .map((s) =>
+            String(s || '')
+              .trim()
+              .toLowerCase()
+              .replace(/:$/, '')
+          )
+          .filter(Boolean)
+      : ['http', 'https', 'mailto', 'tel'];
+
+  try {
+    const parsed = new URL(raw);
+    const scheme = String(parsed.protocol || '')
+      .toLowerCase()
+      .replace(/:$/, '');
+    if (allowedSchemes.includes(scheme)) return raw;
+    console.warn(`[WARN] 已拦截不安全 URL scheme：${raw}`);
+    return '#';
+  } catch (e) {
+    console.warn(`[WARN] 已拦截无法解析的 URL：${raw}`);
+    return '#';
+  }
+}
+
+// 导出所有工具类助手函数
+module.exports = {
+  slice,
+  concat,
+  size,
+  first,
+  last,
+  range,
+  pick,
+  keys,
+  encodeURIComponent: encodeURIComponentHelper,
+  add,
+  faviconV2Url,
+  faviconFallbackUrl,
+  safeUrl,
+};
diff --git a/src/runtime/app/index.js b/src/runtime/app/index.js
new file mode 100644
index 0000000000000000000000000000000000000000..9e2ce99ec86a0be6e9ff37cd48cf7b1d5dfec06d
--- /dev/null
+++ b/src/runtime/app/index.js
@@ -0,0 +1,116 @@
+const initUi = require('./ui');
+const initSearch = require('./search');
+const initRouting = require('./routing');
+
+function detectHomePageId() {
+  // 首页不再固定为 "home"：以导航顺序第一项为准
+  // 1) 优先从生成端注入的配置数据读取（保持与实际导航顺序一致）
+  try {
+    const config =
+      window.MeNav && typeof window.MeNav.getConfig === 'function'
+        ? window.MeNav.getConfig()
+        : null;
+    const injectedHomePageId =
+      config && config.data && config.data.homePageId ? String(config.data.homePageId).trim() : '';
+    if (injectedHomePageId) return injectedHomePageId;
+    const nav =
+      config && config.data && Array.isArray(config.data.navigation)
+        ? config.data.navigation
+        : null;
+    const firstId = nav && nav[0] && nav[0].id ? String(nav[0].id).trim() : '';
+    if (firstId) return firstId;
+  } catch (error) {
+    // 忽略解析错误，继续使用 DOM 推断
+  }
+
+  // 2) 回退到 DOM：取首个导航项的 data-page
+  const firstNavItem = document.querySelector('.nav-item[data-page]');
+  if (firstNavItem) {
+    const id = String(firstNavItem.getAttribute('data-page') || '').trim();
+    if (id) return id;
+  }
+
+  // 3) 最后兜底：取首个页面容器 id
+  const firstPage = document.querySelector('.page[id]');
+  if (firstPage && firstPage.id) return firstPage.id;
+
+  return 'home';
+}
+
+document.addEventListener('DOMContentLoaded', () => {
+  const homePageId = detectHomePageId();
+
+  const state = {
+    homePageId,
+    currentPageId: homePageId,
+    isInitialLoad: true,
+    isSidebarOpen: false,
+    isLightTheme: false,
+    isSidebarCollapsed: false,
+    pages: null,
+    currentSearchEngine: 'local',
+    isSearchActive: false,
+    searchIndex: {
+      initialized: false,
+      items: [],
+    },
+  };
+
+  // 获取 DOM 元素 - 基本元素
+  const searchInput = document.getElementById('search');
+  const searchBox = document.querySelector('.search-box');
+  const searchResultsPage = document.getElementById('search-results');
+  const searchSections = searchResultsPage.querySelectorAll('.search-section');
+
+  // 搜索引擎相关元素
+  const searchEngineToggle = document.querySelector('.search-engine-toggle');
+  const searchEngineToggleIcon = searchEngineToggle
+    ? searchEngineToggle.querySelector('.search-engine-icon')
+    : null;
+  const searchEngineToggleLabel = searchEngineToggle
+    ? searchEngineToggle.querySelector('.search-engine-label')
+    : null;
+  const searchEngineDropdown = document.querySelector('.search-engine-dropdown');
+  const searchEngineOptions = document.querySelectorAll('.search-engine-option');
+
+  // 移动端元素
+  const menuToggle = document.querySelector('.menu-toggle');
+  const searchToggle = document.querySelector('.search-toggle');
+  const sidebar = document.querySelector('.sidebar');
+  const searchContainer = document.querySelector('.search-container');
+  const overlay = document.querySelector('.overlay');
+
+  // 侧边栏折叠功能
+  const sidebarToggle = document.querySelector('.sidebar-toggle');
+  const content = document.querySelector('.content');
+
+  // 主题切换元素
+  const themeToggle = document.querySelector('.theme-toggle');
+  const themeIcon = themeToggle.querySelector('i');
+
+  const dom = {
+    searchInput,
+    searchBox,
+    searchResultsPage,
+    searchSections,
+    searchEngineToggle,
+    searchEngineToggleIcon,
+    searchEngineToggleLabel,
+    searchEngineDropdown,
+    searchEngineOptions,
+    menuToggle,
+    searchToggle,
+    sidebar,
+    searchContainer,
+    overlay,
+    sidebarToggle,
+    content,
+    themeToggle,
+    themeIcon,
+  };
+
+  const ui = initUi(state, dom);
+  const search = initSearch(state, dom);
+
+  initRouting(state, dom, { ui, search });
+});
diff --git a/src/runtime/app/routing.js b/src/runtime/app/routing.js
new file mode 100644
index 0000000000000000000000000000000000000000..265d7c15155dc88e5225593a5b65293623333557
--- /dev/null
+++ b/src/runtime/app/routing.js
@@ -0,0 +1,474 @@
+const nested = require('../nested');
+
+module.exports = function initRouting(state, dom, api) {
+  const { ui, search } = api;
+  const { searchInput, content, sidebar } = dom;
+
+  function showPage(pageId, skipSearchReset = false) {
+    if (state.currentPageId === pageId && !skipSearchReset && !state.isInitialLoad) return;
+
+    state.currentPageId = pageId;
+
+    // 使用 RAF 确保动画流畅
+    requestAnimationFrame(() => {
+      if (!state.pages) {
+        state.pages = document.querySelectorAll('.page');
+      }
+
+      state.pages.forEach((page) => {
+        const shouldBeActive = page.id === pageId;
+        if (shouldBeActive !== page.classList.contains('active')) {
+          page.classList.toggle('active', shouldBeActive);
+        }
+      });
+
+      // 通知：页面已切换（供按需组件初始化，如 github-calendar）
+      // 注意：必须在 active class 切换之后触发，否则监听方可能认为页面仍不可见。
+      try {
+        document.dispatchEvent(
+          new CustomEvent('menav:pageChanged', {
+            detail: {
+              pageId,
+            },
+          })
+        );
+      } catch (error) {
+        // ignore
+      }
+
+      // 初始加载完成后设置标志
+      if (state.isInitialLoad) {
+        state.isInitialLoad = false;
+        document.body.classList.add('loaded');
+      }
+    });
+
+    // 重置滚动位置并更新进度条
+    content.scrollTop = 0;
+
+    // 只有在非搜索状态下才重置搜索
+    if (!skipSearchReset) {
+      searchInput.value = '';
+      search.resetSearch();
+    }
+  }
+
+  // 初始化（在 window load 时执行）
+  window.addEventListener('load', () => {
+    // 获取可能在 HTML 生成后才存在的 DOM 元素
+    const categories = document.querySelectorAll('.category');
+    const navItems = document.querySelectorAll('.nav-item');
+    const navItemWrappers = document.querySelectorAll('.nav-item-wrapper');
+    const submenuItems = document.querySelectorAll('.submenu-item');
+    state.pages = document.querySelectorAll('.page');
+
+    // 方案 A：用 ?page=<id> 作为页面深链接（兼容 GitHub Pages 静态托管）
+    const normalizeText = (value) =>
+      String(value === null || value === undefined ? '' : value).trim();
+
+    // 侧边栏子菜单面板：将“当前页面的分类列表”放到独立区域滚动，避免挤压“页面列表”
+    const submenuPanel = document.querySelector('.sidebar-submenu-panel');
+    const submenuByPageId = new Map();
+    let submenuPanelPageId = '';
+
+    navItemWrappers.forEach((wrapper) => {
+      const nav = wrapper.querySelector('.nav-item');
+      const pageId = nav ? normalizeText(nav.getAttribute('data-page')) : '';
+      const submenu = wrapper.querySelector('.submenu');
+      if (!pageId || !submenu) return;
+      submenuByPageId.set(pageId, { wrapper, submenu });
+    });
+
+    const isSidebarCollapsed = () => Boolean(sidebar && sidebar.classList.contains('collapsed'));
+
+    const clearSubmenuPanel = () => {
+      if (!submenuPanel) return;
+
+      const pageId = normalizeText(submenuPanelPageId);
+      if (pageId) {
+        const entry = submenuByPageId.get(pageId);
+        if (entry && entry.wrapper && entry.submenu) {
+          entry.wrapper.appendChild(entry.submenu);
+        }
+      }
+
+      submenuPanel.textContent = '';
+      submenuPanelPageId = '';
+    };
+
+    const renderSubmenuPanelForPage = (pageId) => {
+      if (!submenuPanel) return;
+
+      const id = normalizeText(pageId);
+      if (!id) {
+        clearSubmenuPanel();
+        return;
+      }
+
+      // 折叠态：子菜单使用 hover 弹出，不使用面板
+      if (isSidebarCollapsed()) {
+        clearSubmenuPanel();
+        return;
+      }
+
+      const entry = submenuByPageId.get(id);
+      if (!entry || !entry.wrapper || !entry.submenu) {
+        clearSubmenuPanel();
+        return;
+      }
+
+      // 仅当 wrapper 处于 expanded 时展示（与 UI 行为保持一致）
+      if (!entry.wrapper.classList.contains('expanded')) {
+        clearSubmenuPanel();
+        return;
+      }
+
+      if (normalizeText(submenuPanelPageId) === id && submenuPanel.contains(entry.submenu)) {
+        return;
+      }
+
+      clearSubmenuPanel();
+      submenuPanel.appendChild(entry.submenu);
+      submenuPanelPageId = id;
+    };
+
+    // 监听侧边栏折叠状态变化：折叠时归还子菜单；展开时渲染当前页子菜单
+    if (sidebar && typeof MutationObserver === 'function') {
+      const observer = new MutationObserver(() => {
+        const activeNav = document.querySelector('.nav-item.active');
+        const activePageId = activeNav ? normalizeText(activeNav.getAttribute('data-page')) : '';
+        renderSubmenuPanelForPage(activePageId);
+      });
+
+      observer.observe(sidebar, { attributes: true, attributeFilter: ['class'] });
+    }
+
+    const isValidPageId = (pageId) => {
+      const id = normalizeText(pageId);
+      if (!id) return false;
+      const el = document.getElementById(id);
+      return Boolean(el && el.classList && el.classList.contains('page'));
+    };
+
+    const getRawPageIdFromUrl = () => {
+      try {
+        const url = new URL(window.location.href);
+        return normalizeText(url.searchParams.get('page'));
+      } catch (error) {
+        return '';
+      }
+    };
+
+    const getPageIdFromUrl = () => {
+      try {
+        const url = new URL(window.location.href);
+        const pageId = normalizeText(url.searchParams.get('page'));
+        return isValidPageId(pageId) ? pageId : '';
+      } catch (error) {
+        return '';
+      }
+    };
+
+    const setUrlState = (next, options = {}) => {
+      const { replace = true } = options;
+      try {
+        const url = new URL(window.location.href);
+
+        if (next && typeof next.pageId === 'string') {
+          const pageId = normalizeText(next.pageId);
+          if (pageId) {
+            url.searchParams.set('page', pageId);
+          } else {
+            url.searchParams.delete('page');
+          }
+        }
+
+        if (next && Object.prototype.hasOwnProperty.call(next, 'hash')) {
+          const hash = normalizeText(next.hash);
+          url.hash = hash ? `#${hash}` : '';
+        }
+
+        const nextUrl = `${url.pathname}${url.search}${url.hash}`;
+        const fn = replace ? history.replaceState : history.pushState;
+        fn.call(history, null, '', nextUrl);
+      } catch (error) {
+        // 忽略 URL/History API 异常，避免影响主流程
+      }
+    };
+
+    const setActiveNavByPageId = (pageId) => {
+      const id = normalizeText(pageId);
+      let activeItem = null;
+
+      navItems.forEach((nav) => {
+        const isActive = nav.getAttribute('data-page') === id;
+        nav.classList.toggle('active', isActive);
+        if (isActive) activeItem = nav;
+      });
+
+      // 同步子菜单展开状态：只展开当前激活项
+      navItemWrappers.forEach((wrapper) => {
+        const nav = wrapper.querySelector('.nav-item');
+        if (!nav) return;
+        const pageId = normalizeText(nav.getAttribute('data-page'));
+        const hasSubmenu = pageId ? submenuByPageId.has(pageId) : false;
+        const shouldExpand = hasSubmenu && nav === activeItem;
+        wrapper.classList.toggle('expanded', shouldExpand);
+      });
+
+      renderSubmenuPanelForPage(id);
+    };
+
+    const escapeSelector = (value) => {
+      if (value === null || value === undefined) return '';
+      const text = String(value);
+      if (window.CSS && typeof window.CSS.escape === 'function') return window.CSS.escape(text);
+      // 回退：尽量避免打断选择器（不追求完全覆盖所有边界字符）
+      return text.replace(/[^a-zA-Z0-9_\u00A0-\uFFFF-]/g, '\\$&');
+    };
+
+    const escapeAttrValue = (value) => {
+      if (value === null || value === undefined) return '';
+      return String(value).replace(/\\/g, '\\\\').replace(/\"/g, '\\"');
+    };
+
+    const getHashFromUrl = () => {
+      const rawHash = window.location.hash ? String(window.location.hash).slice(1) : '';
+      if (!rawHash) return '';
+      try {
+        return decodeURIComponent(rawHash).trim();
+      } catch (error) {
+        return rawHash.trim();
+      }
+    };
+
+    const scrollToCategoryInPage = (pageId, options = {}) => {
+      const id = normalizeText(pageId);
+      if (!id) return false;
+
+      const targetPage = document.getElementById(id);
+      if (!targetPage) return false;
+
+      const categoryId = normalizeText(options.categoryId);
+      const categoryName = normalizeText(options.categoryName);
+
+      let targetCategory = null;
+
+      // 优先使用 slug/data-id 精准定位（解决重复命名始终命中第一个的问题）
+      if (categoryId) {
+        const escapedId = escapeSelector(categoryId);
+        targetCategory =
+          targetPage.querySelector(`#${escapedId}`) ||
+          targetPage.querySelector(
+            `[data-type="category"][data-id="${escapeAttrValue(categoryId)}"]`
+          );
+      }
+
+      // 回退：旧逻辑按文本包含匹配（兼容旧页面/旧数据）
+      if (!targetCategory && categoryName) {
+        targetCategory = Array.from(targetPage.querySelectorAll('.category h2')).find((heading) =>
+          heading.textContent.trim().includes(categoryName)
+        );
+      }
+
+      if (!targetCategory) return false;
+
+      // 优化的滚动实现：滚动到使目标分类位于视口 1/4 处（更靠近顶部位置）
+      try {
+        // 直接获取所需元素和属性，减少重复查询
+        const contentElement = document.querySelector('.content');
+
+        if (contentElement && contentElement.scrollHeight > contentElement.clientHeight) {
+          // 获取目标元素相对于内容区域的位置
+          const rect = targetCategory.getBoundingClientRect();
+          const containerRect = contentElement.getBoundingClientRect();
+
+          // 计算目标应该在视口中的位置（视口高度的 1/4 处）
+          const desiredPosition = containerRect.height / 4;
+
+          // 计算需要滚动的位置
+          const scrollPosition =
+            contentElement.scrollTop + rect.top - containerRect.top - desiredPosition;
+
+          // 执行滚动
+          contentElement.scrollTo({
+            top: scrollPosition,
+            behavior: 'smooth',
+          });
+        } else {
+          // 回退到基本滚动方式
+          targetCategory.scrollIntoView({ behavior: 'smooth', block: 'center' });
+        }
+      } catch (error) {
+        console.error('Error during scroll:', error);
+        // 回退到基本滚动方式
+        targetCategory.scrollIntoView({ behavior: 'smooth', block: 'center' });
+      }
+
+      return true;
+    };
+
+    // 初始化主题
+    ui.initTheme();
+
+    // 初始化侧边栏状态
+    ui.initSidebarState();
+
+    // 初始化搜索引擎选择
+    search.initSearchEngine();
+
+    // 初始化 MeNav 对象版本信息
+    try {
+      const config = window.MeNav.getConfig();
+      if (config && config.version) {
+        window.MeNav.version = config.version;
+        console.log('MeNav API initialized with version:', config.version);
+      }
+    } catch (error) {
+      console.error('Error initializing MeNav API:', error);
+    }
+
+    // 立即执行初始化，不再使用 requestAnimationFrame 延迟
+    // 支持 ?page=<id> 直接打开对应页面；无效时回退到首页
+    const rawPageIdFromUrl = getRawPageIdFromUrl();
+    const validatedPageIdFromUrl = getPageIdFromUrl();
+    const initialPageId =
+      validatedPageIdFromUrl || (isValidPageId(state.homePageId) ? state.homePageId : 'home');
+
+    setActiveNavByPageId(initialPageId);
+    showPage(initialPageId);
+
+    // 当输入了不存在的 page id 时，自动纠正 URL，避免“内容回退但地址栏仍错误”
+    if (rawPageIdFromUrl && !validatedPageIdFromUrl) {
+      setUrlState({ pageId: initialPageId }, { replace: true });
+    }
+
+    // 初始深链接：支持 ?page=<id>#<categorySlug>
+    const initialHash = getHashFromUrl();
+    if (initialHash) {
+      setTimeout(() => {
+        const found = scrollToCategoryInPage(initialPageId, {
+          categoryId: initialHash,
+          categoryName: initialHash,
+        });
+
+        // hash 存在但未命中时，不做强制修正，避免误伤其他用途的 hash
+        if (!found) return;
+      }, 50);
+    }
+
+    // 添加载入动画
+    categories.forEach((category, index) => {
+      setTimeout(() => {
+        category.style.opacity = '1';
+      }, index * 100);
+    });
+
+    // 导航项点击效果
+    navItems.forEach((item) => {
+      item.addEventListener('click', (e) => {
+        if (item.getAttribute('target') === '_blank') return;
+
+        e.preventDefault();
+
+        // 获取当前项的父级 wrapper
+        const wrapper = item.closest('.nav-item-wrapper');
+        const pageId = normalizeText(item.getAttribute('data-page'));
+        const hasSubmenu = Boolean(wrapper && pageId && submenuByPageId.has(pageId));
+
+        if (!pageId) return;
+
+        // 处理子菜单展开/折叠
+        if (hasSubmenu && item.classList.contains('active')) {
+          // 当前页：保持子菜单展开状态，不做任何操作
+          return;
+        } else {
+          // 切换页面：统一由 setActiveNavByPageId 管理 active/expanded
+          setActiveNavByPageId(pageId);
+        }
+
+        const prevPageId = state.currentPageId;
+        showPage(pageId);
+
+        // 切换页面时同步 URL（清空旧 hash，避免跨页残留）
+        if (normalizeText(prevPageId) !== normalizeText(pageId)) {
+          setUrlState({ pageId, hash: '' }, { replace: true });
+        }
+
+        // 在移动端视图下点击导航项后自动收起侧边栏
+        if (ui.isMobile() && state.isSidebarOpen && !hasSubmenu) {
+          ui.closeAllPanels();
+        }
+      });
+    });
+
+    // 子菜单项点击效果
+    submenuItems.forEach((item) => {
+      item.addEventListener('click', (e) => {
+        e.preventDefault();
+
+        // 获取页面 ID 和分类名称
+        const pageId = item.getAttribute('data-page');
+        const categoryName = item.getAttribute('data-category');
+        const categoryId = item.getAttribute('data-category-id');
+
+        if (pageId) {
+          // 清除所有子菜单项的激活状态
+          submenuItems.forEach((subItem) => {
+            subItem.classList.remove('active');
+          });
+
+          // 激活当前子菜单项
+          item.classList.add('active');
+
+          // 激活导航项并同步子菜单展开状态
+          setActiveNavByPageId(pageId);
+
+          // 显示对应页面
+          showPage(pageId);
+          // 先同步 page 参数并清空旧 hash，避免跨页残留；后续若找到分类再写入新的 hash
+          setUrlState({ pageId, hash: '' }, { replace: true });
+
+          // 等待页面切换完成后滚动到对应分类
+          setTimeout(() => {
+            const found = scrollToCategoryInPage(pageId, { categoryId, categoryName });
+            if (!found) return;
+
+            // 由于对子菜单 click 做了 preventDefault，这里手动同步 hash（不触发浏览器默认跳转）
+            const nextHash = normalizeText(categoryId) || normalizeText(categoryName);
+            if (nextHash) {
+              setUrlState({ pageId, hash: nextHash }, { replace: true });
+            }
+          }, 25); // 延迟时间
+
+          // 在移动端视图下点击子菜单项后自动收起侧边栏
+          if (ui.isMobile() && state.isSidebarOpen) {
+            ui.closeAllPanels();
+          }
+        }
+      });
+    });
+
+    // 初始化嵌套分类功能
+    nested.initializeNestedCategories();
+
+    // 初始化分类切换按钮
+    const categoryToggleBtn = document.getElementById('category-toggle');
+    if (categoryToggleBtn) {
+      categoryToggleBtn.addEventListener('click', function () {
+        window.MeNav.toggleCategories();
+      });
+    } else {
+      console.error('Category toggle button not found');
+    }
+
+    // 初始化搜索索引（使用 requestIdleCallback 或 setTimeout 延迟初始化，避免影响页面加载）
+    if ('requestIdleCallback' in window) {
+      requestIdleCallback(() => search.initSearchIndex());
+    } else {
+      setTimeout(search.initSearchIndex, 1000);
+    }
+  });
+
+  return { showPage };
+};
diff --git a/src/runtime/app/search.js b/src/runtime/app/search.js
new file mode 100644
index 0000000000000000000000000000000000000000..a63695a951aa18638dd8bd82804fd82b7879c972
--- /dev/null
+++ b/src/runtime/app/search.js
@@ -0,0 +1,449 @@
+const searchEngines = require('./searchEngines');
+const highlightSearchTerm = require('./search/highlight');
+
+module.exports = function initSearch(state, dom) {
+  const {
+    searchInput,
+    searchBox,
+    searchResultsPage,
+    searchSections,
+    searchEngineToggle,
+    searchEngineToggleIcon,
+    searchEngineToggleLabel,
+    searchEngineDropdown,
+    searchEngineOptions,
+  } = dom;
+
+  if (!state.searchIndex) {
+    state.searchIndex = { initialized: false, items: [] };
+  }
+  if (!state.currentSearchEngine) {
+    state.currentSearchEngine = 'local';
+  }
+  if (typeof state.isSearchActive !== 'boolean') {
+    state.isSearchActive = false;
+  }
+
+  // 初始化搜索索引
+  function initSearchIndex() {
+    if (state.searchIndex.initialized) return;
+
+    state.searchIndex.items = [];
+
+    try {
+      // 为每个页面创建索引
+      if (!state.pages) {
+        state.pages = document.querySelectorAll('.page');
+      }
+
+      state.pages.forEach((page) => {
+        if (page.id === 'search-results') return;
+
+        const pageId = page.id;
+
+        page.querySelectorAll('.site-card').forEach((card) => {
+          try {
+            // 排除“扩展写回影子结构”等不应参与搜索的卡片
+            if (card.closest('[data-search-exclude="true"]')) return;
+
+            // 兼容不同页面/卡片样式：优先取可见文本，其次回退到 data-*（确保 projects repo 卡片也能被搜索）
+            const dataTitle = card.dataset?.name || card.getAttribute('data-name') || '';
+            const dataDescription =
+              card.dataset?.description || card.getAttribute('data-description') || '';
+
+            const titleText =
+              card.querySelector('h3')?.textContent ||
+              card.querySelector('.repo-title')?.textContent ||
+              dataTitle;
+            const descriptionText =
+              card.querySelector('p')?.textContent ||
+              card.querySelector('.repo-desc')?.textContent ||
+              dataDescription;
+
+            const title = String(titleText || '').toLowerCase();
+            const description = String(descriptionText || '').toLowerCase();
+            const url = card.href || card.getAttribute('href') || '#';
+            const icon =
+              card.querySelector('i.icon-fallback')?.className ||
+              card.querySelector('i')?.className ||
+              '';
+
+            // 将卡片信息添加到索引中
+            state.searchIndex.items.push({
+              pageId,
+              title,
+              description,
+              url,
+              icon,
+              element: card,
+              // 预先计算搜索文本，提高搜索效率
+              searchText: (title + ' ' + description).toLowerCase(),
+            });
+          } catch (cardError) {
+            console.error('Error processing card:', cardError);
+          }
+        });
+      });
+
+      state.searchIndex.initialized = true;
+    } catch (error) {
+      console.error('Error initializing search index:', error);
+      state.searchIndex.initialized = true; // 防止反复尝试初始化
+    }
+  }
+
+  // 搜索功能
+  function performSearch(searchTerm) {
+    // 确保搜索索引已初始化
+    if (!state.searchIndex.initialized) {
+      initSearchIndex();
+    }
+
+    searchTerm = searchTerm.toLowerCase().trim();
+
+    // 如果搜索框为空，重置所有内容
+    if (!searchTerm) {
+      resetSearch();
+      return;
+    }
+
+    if (!state.isSearchActive) {
+      state.isSearchActive = true;
+    }
+
+    try {
+      // 使用搜索索引进行搜索
+      const searchResults = new Map();
+      let hasResults = false;
+
+      // 使用更高效的搜索算法
+      const matchedItems = state.searchIndex.items.filter((item) => {
+        return (
+          item.searchText.includes(searchTerm) || PinyinMatch.match(item.searchText, searchTerm)
+        );
+      });
+
+      // 按页面分组结果
+      matchedItems.forEach((item) => {
+        if (!searchResults.has(item.pageId)) {
+          searchResults.set(item.pageId, []);
+        }
+        // 克隆元素以避免修改原始 DOM
+        searchResults.get(item.pageId).push(item.element.cloneNode(true));
+        hasResults = true;
+      });
+
+      // 使用 requestAnimationFrame 批量更新 DOM，减少重排重绘
+      requestAnimationFrame(() => {
+        try {
+          // 清空并隐藏所有搜索区域
+          searchSections.forEach((section) => {
+            try {
+              const grid = section.querySelector('.sites-grid');
+              if (grid) {
+                grid.innerHTML = ''; // 使用 innerHTML 清空，比 removeChild 更高效
+              }
+              section.style.display = 'none';
+            } catch (sectionError) {
+              console.error('Error clearing search section');
+            }
+          });
+
+          // 使用 DocumentFragment 批量添加 DOM 元素，减少重排
+          searchResults.forEach((matches, pageId) => {
+            const section = searchResultsPage.querySelector(`[data-section="${pageId}"]`);
+            if (section) {
+              try {
+                const grid = section.querySelector('.sites-grid');
+                if (grid) {
+                  const fragment = document.createDocumentFragment();
+
+                  matches.forEach((card) => {
+                    // 高亮匹配文本
+                    highlightSearchTerm(card, searchTerm);
+                    fragment.appendChild(card);
+                  });
+
+                  grid.appendChild(fragment);
+                  section.style.display = 'block';
+                }
+              } catch (gridError) {
+                console.error('Error updating search results grid');
+              }
+            }
+          });
+
+          // 更新搜索结果页面状态
+          const subtitle = searchResultsPage.querySelector('.subtitle');
+          if (subtitle) {
+            subtitle.textContent = hasResults
+              ? `在所有页面中找到 ${matchedItems.length} 个匹配项`
+              : '未找到匹配的结果';
+          }
+
+          // 显示搜索结果页面
+          if (state.currentPageId !== 'search-results') {
+            state.currentPageId = 'search-results';
+            if (!state.pages) state.pages = document.querySelectorAll('.page');
+            state.pages.forEach((page) => {
+              page.classList.toggle('active', page.id === 'search-results');
+            });
+          }
+
+          // 更新搜索状态样式
+          searchBox.classList.toggle('has-results', hasResults);
+          searchBox.classList.toggle('no-results', !hasResults);
+        } catch (uiError) {
+          console.error('Error updating search UI');
+        }
+      });
+    } catch (searchError) {
+      console.error('Error performing search');
+    }
+  }
+
+  // 重置搜索状态
+  function resetSearch() {
+    if (!state.isSearchActive) return;
+
+    state.isSearchActive = false;
+
+    try {
+      requestAnimationFrame(() => {
+        try {
+          // 清空搜索结果
+          searchSections.forEach((section) => {
+            try {
+              const grid = section.querySelector('.sites-grid');
+              if (grid) {
+                while (grid.firstChild) {
+                  grid.removeChild(grid.firstChild);
+                }
+              }
+              section.style.display = 'none';
+            } catch (sectionError) {
+              console.error('Error clearing search section');
+            }
+          });
+
+          // 移除搜索状态样式
+          searchBox.classList.remove('has-results', 'no-results');
+
+          // 恢复到当前激活的页面
+          const currentActiveNav = document.querySelector('.nav-item.active');
+          if (currentActiveNav) {
+            const targetPageId = currentActiveNav.getAttribute('data-page');
+
+            if (targetPageId && state.currentPageId !== targetPageId) {
+              state.currentPageId = targetPageId;
+              if (!state.pages) state.pages = document.querySelectorAll('.page');
+              state.pages.forEach((page) => {
+                page.classList.toggle('active', page.id === targetPageId);
+              });
+            }
+          } else {
+            // 如果没有激活的导航项，默认显示首页
+            state.currentPageId = state.homePageId;
+            if (!state.pages) state.pages = document.querySelectorAll('.page');
+            state.pages.forEach((page) => {
+              page.classList.toggle('active', page.id === state.homePageId);
+            });
+          }
+        } catch (resetError) {
+          console.error('Error resetting search UI');
+        }
+      });
+    } catch (error) {
+      console.error('Error in resetSearch');
+    }
+  }
+
+  // 搜索输入事件（使用防抖）
+  const debounce = (fn, delay) => {
+    let timer = null;
+    return (...args) => {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(() => {
+        fn.apply(this, args);
+        timer = null;
+      }, delay);
+    };
+  };
+
+  const debouncedSearch = debounce(performSearch, 300);
+
+  searchInput.addEventListener('input', (e) => {
+    // 只有在选择了本地搜索时，才在输入时实时显示本地搜索结果
+    if (state.currentSearchEngine === 'local') {
+      debouncedSearch(e.target.value);
+    } else {
+      // 对于非本地搜索，重置之前的本地搜索结果（如果有）
+      if (state.isSearchActive) {
+        resetSearch();
+      }
+    }
+  });
+
+  // 更新搜索引擎 UI 显示
+  function updateSearchEngineUI() {
+    // 移除所有选项的激活状态
+    searchEngineOptions.forEach((option) => {
+      option.classList.remove('active');
+
+      // 如果是当前选中的搜索引擎，添加激活状态
+      if (option.getAttribute('data-engine') === state.currentSearchEngine) {
+        option.classList.add('active');
+      }
+    });
+
+    // 更新搜索引擎按钮（方案 B：前缀按钮显示当前引擎）
+    const engine = searchEngines[state.currentSearchEngine];
+    if (!engine) return;
+    const displayName = engine.shortName || engine.name.replace(/搜索$/, '');
+
+    if (searchEngineToggleIcon) {
+      if (engine.iconSvg) {
+        searchEngineToggleIcon.className = 'search-engine-icon search-engine-icon-svg';
+        searchEngineToggleIcon.innerHTML = engine.iconSvg;
+      } else {
+        searchEngineToggleIcon.innerHTML = '';
+        searchEngineToggleIcon.className = `search-engine-icon ${engine.icon}`;
+      }
+    }
+    if (searchEngineToggleLabel) {
+      searchEngineToggleLabel.textContent = displayName;
+    }
+    if (searchEngineToggle) {
+      searchEngineToggle.setAttribute('aria-label', `当前搜索引擎：${engine.name}，点击切换`);
+    }
+  }
+
+  // 初始化搜索引擎设置
+  function initSearchEngine() {
+    // 从本地存储获取上次选择的搜索引擎
+    const savedEngine = localStorage.getItem('searchEngine');
+    if (savedEngine && searchEngines[savedEngine]) {
+      state.currentSearchEngine = savedEngine;
+    }
+
+    // 设置当前搜索引擎的激活状态及图标
+    updateSearchEngineUI();
+
+    // 初始化搜索引擎下拉菜单事件
+    const toggleEngineDropdown = () => {
+      if (!searchEngineDropdown) return;
+      const next = !searchEngineDropdown.classList.contains('active');
+      searchEngineDropdown.classList.toggle('active', next);
+      if (searchBox) {
+        searchBox.classList.toggle('dropdown-open', next);
+      }
+      if (searchEngineToggle) {
+        searchEngineToggle.setAttribute('aria-expanded', String(next));
+      }
+    };
+
+    if (searchEngineToggle) {
+      searchEngineToggle.addEventListener('click', (e) => {
+        e.stopPropagation();
+        toggleEngineDropdown();
+      });
+
+      // 键盘可访问性：Enter/Space 触发
+      searchEngineToggle.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          e.stopPropagation();
+          toggleEngineDropdown();
+        }
+      });
+    }
+
+    // 点击搜索引擎选项
+    searchEngineOptions.forEach((option) => {
+      // 初始化激活状态
+      if (option.getAttribute('data-engine') === state.currentSearchEngine) {
+        option.classList.add('active');
+      }
+
+      option.addEventListener('click', (e) => {
+        e.stopPropagation();
+
+        // 获取选中的搜索引擎
+        const engine = option.getAttribute('data-engine');
+
+        // 更新当前搜索引擎
+        if (engine && searchEngines[engine]) {
+          // 如果搜索引擎变更，且之前有活跃的本地搜索结果，重置搜索状态
+          if (state.currentSearchEngine !== engine && state.isSearchActive) {
+            resetSearch();
+          }
+
+          state.currentSearchEngine = engine;
+          localStorage.setItem('searchEngine', engine);
+
+          // 更新 UI 显示
+          updateSearchEngineUI();
+
+          // 关闭下拉菜单
+          if (searchEngineDropdown) {
+            searchEngineDropdown.classList.remove('active');
+          }
+          if (searchBox) {
+            searchBox.classList.remove('dropdown-open');
+          }
+        }
+      });
+    });
+
+    // 点击页面其他位置关闭下拉菜单
+    document.addEventListener('click', () => {
+      if (!searchEngineDropdown) return;
+      searchEngineDropdown.classList.remove('active');
+      if (searchBox) {
+        searchBox.classList.remove('dropdown-open');
+      }
+    });
+  }
+
+  // 执行搜索（根据选择的搜索引擎）
+  function executeSearch(searchTerm) {
+    if (!searchTerm.trim()) return;
+
+    // 根据当前搜索引擎执行搜索
+    if (state.currentSearchEngine === 'local') {
+      // 执行本地搜索
+      performSearch(searchTerm);
+    } else {
+      // 使用外部搜索引擎
+      const engine = searchEngines[state.currentSearchEngine];
+      if (engine && engine.url) {
+        // 打开新窗口进行搜索
+        window.open(engine.url + encodeURIComponent(searchTerm), '_blank');
+      }
+    }
+  }
+
+  // 搜索框事件处理
+  searchInput.addEventListener('keyup', (e) => {
+    if (e.key === 'Escape') {
+      searchInput.value = '';
+      resetSearch();
+    } else if (e.key === 'Enter') {
+      executeSearch(searchInput.value);
+    }
+  });
+
+  // 阻止搜索框的回车默认行为
+  searchInput.addEventListener('keydown', (e) => {
+    if (e.key === 'Enter') {
+      e.preventDefault();
+    }
+  });
+
+  return {
+    initSearchIndex,
+    initSearchEngine,
+    resetSearch,
+    performSearch,
+  };
+};
diff --git a/src/runtime/app/search/highlight.js b/src/runtime/app/search/highlight.js
new file mode 100644
index 0000000000000000000000000000000000000000..dde08c138272849ca1ffbc5e42bc044516a45811
--- /dev/null
+++ b/src/runtime/app/search/highlight.js
@@ -0,0 +1,91 @@
+module.exports = function highlightSearchTerm(card, searchTerm) {
+  if (!card || !searchTerm) return;
+
+  const escapeRegExp = (string) => string.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+  try {
+    // 兼容 projects repo 卡片：title/desc 不一定是 h3/p
+    const titleElement = card.querySelector('h3') || card.querySelector('.repo-title');
+    const descriptionElement = card.querySelector('p') || card.querySelector('.repo-desc');
+
+    const hasPinyinMatch =
+      typeof PinyinMatch !== 'undefined' && PinyinMatch && typeof PinyinMatch.match === 'function';
+
+    const applyRangeHighlight = (element, start, end) => {
+      const text = element.textContent || '';
+      const safeStart = Math.max(0, Math.min(text.length, start));
+      const safeEnd = Math.max(safeStart, Math.min(text.length - 1, end));
+
+      const fragment = document.createDocumentFragment();
+      fragment.appendChild(document.createTextNode(text.slice(0, safeStart)));
+
+      const span = document.createElement('span');
+      span.className = 'highlight';
+      span.textContent = text.slice(safeStart, safeEnd + 1);
+      fragment.appendChild(span);
+
+      fragment.appendChild(document.createTextNode(text.slice(safeEnd + 1)));
+
+      while (element.firstChild) {
+        element.removeChild(element.firstChild);
+      }
+      element.appendChild(fragment);
+    };
+
+    const highlightInElement = (element) => {
+      if (!element) return;
+
+      const rawText = element.textContent || '';
+      const lowerText = rawText.toLowerCase();
+      if (!rawText) return;
+
+      if (lowerText.includes(searchTerm)) {
+        const regex = new RegExp(`(${escapeRegExp(searchTerm)})`, 'gi');
+        const fragment = document.createDocumentFragment();
+        let lastIndex = 0;
+        let match;
+
+        while ((match = regex.exec(rawText)) !== null) {
+          if (match.index > lastIndex) {
+            fragment.appendChild(
+              document.createTextNode(rawText.substring(lastIndex, match.index))
+            );
+          }
+
+          const span = document.createElement('span');
+          span.className = 'highlight';
+          span.textContent = match[0];
+          fragment.appendChild(span);
+
+          lastIndex = match.index + match[0].length;
+
+          // 防止无限循环
+          if (regex.lastIndex === 0) break;
+        }
+
+        if (lastIndex < rawText.length) {
+          fragment.appendChild(document.createTextNode(rawText.substring(lastIndex)));
+        }
+
+        while (element.firstChild) {
+          element.removeChild(element.firstChild);
+        }
+        element.appendChild(fragment);
+        return;
+      }
+
+      if (hasPinyinMatch) {
+        const arr = PinyinMatch.match(rawText, searchTerm);
+        if (Array.isArray(arr) && arr.length >= 2) {
+          const [start, end] = arr;
+          applyRangeHighlight(element, start, end);
+        }
+      }
+    };
+
+    highlightInElement(titleElement);
+    highlightInElement(descriptionElement);
+  } catch (error) {
+    console.error('Error highlighting search term');
+  }
+};
diff --git a/src/runtime/app/searchEngines.js b/src/runtime/app/searchEngines.js
new file mode 100644
index 0000000000000000000000000000000000000000..6a6338a6f1777f0b0764b19ed5f7b25b989389c8
--- /dev/null
+++ b/src/runtime/app/searchEngines.js
@@ -0,0 +1,24 @@
+module.exports = {
+  local: {
+    name: '本地搜索',
+    iconSvg: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" focusable="false"><path fill="#616161" d="M29.171,32.001L32,29.172l12.001,12l-2.828,2.828L29.171,32.001z"></path><path fill="#616161" d="M36,20c0,8.837-7.163,16-16,16S4,28.837,4,20S11.163,4,20,4S36,11.163,36,20"></path><path fill="#37474f" d="M32.476,35.307l2.828-2.828l8.693,8.693L41.17,44L32.476,35.307z"></path><path fill="#64b5f6" d="M7,20c0-7.18,5.82-13,13-13s13,5.82,13,13s-5.82,13-13,13S7,27.18,7,20"></path></svg>`,
+    url: null, // 本地搜索不需要URL
+  },
+  google: {
+    name: 'Google搜索',
+    iconSvg: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" focusable="false"><path fill="#FFC107" d="M43.611,20.083H42V20H24v8h11.303c-1.649,4.657-6.08,8-11.303,8c-6.627,0-12-5.373-12-12c0-6.627,5.373-12,12-12c3.059,0,5.842,1.154,7.961,3.039l5.657-5.657C34.046,6.053,29.268,4,24,4C12.955,4,4,12.955,4,24c0,11.045,8.955,20,20,20c11.045,0,20-8.955,20-20C44,22.659,43.862,21.35,43.611,20.083z"></path><path fill="#FF3D00" d="M6.306,14.691l6.571,4.819C14.655,15.108,18.961,12,24,12c3.059,0,5.842,1.154,7.961,3.039l5.657-5.657C34.046,6.053,29.268,4,24,4C16.318,4,9.656,8.337,6.306,14.691z"></path><path fill="#4CAF50" d="M24,44c5.166,0,9.86-1.977,13.409-5.192l-6.19-5.238C29.211,35.091,26.715,36,24,36c-5.202,0-9.619-3.317-11.283-7.946l-6.522,5.025C9.505,39.556,16.227,44,24,44z"></path><path fill="#1976D2" d="M43.611,20.083H42V20H24v8h11.303c-0.792,2.237-2.231,4.166-4.087,5.571c0.001-0.001,0.002-0.001,0.003-0.002l6.19,5.238C36.971,39.205,44,34,44,24C44,22.659,43.862,21.35,43.611,20.083z"></path></svg>`,
+    url: 'https://www.google.com/search?q=',
+  },
+  bing: {
+    name: 'Bing搜索',
+    iconSvg: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" focusable="false"><g fill="#2877fb" fill-rule="nonzero" stroke="none" stroke-width="1" stroke-linecap="butt" stroke-linejoin="miter" stroke-miterlimit="10" stroke-dasharray="" stroke-dashoffset="0" font-family="none" font-weight="none" font-size="none" text-anchor="none" style="mix-blend-mode: normal"><g transform="scale(5.12,5.12)"><path d="M45,26.10156v-5.10156c0,-0.89844 -0.60156,-1.69922 -1.39844,-1.89844l-4.60156,-1.40234c-5.30078,-1.59766 -10.30078,-3 -15.60156,-4.69922h-0.09766c-0.80078,-0.19922 -1.60156,0.69922 -1.19922,1.5c1.89844,3.89844 3.89844,9.5 3.89844,9.5l6.69922,2.60156c-0.30078,0 -21.69922,11.39844 -21.69922,11.39844l9,-8v-23c0,-0.89844 -0.60156,-1.80078 -1.39844,-2c0,0 -4.90234,-1.89844 -8,-2.89844c-0.20312,-0.10156 -0.40234,-0.10156 -0.60156,-0.10156c-0.39844,0 -0.80078,0.10156 -1.19922,0.39844c-0.5,0.40234 -0.80078,1 -0.80078,1.60156v34.69922c0,0.69922 0.30078,1.30078 0.89844,1.60156c2.10156,1.5 4.30078,3 6.40234,4.5l3,2.09766c0.30078,0.20313 0.69922,0.40234 1.09766,0.40234c0.40234,0 0.70313,-0.10156 1,-0.30078c4.30078,-2.60156 8.70313,-5.19922 13,-7.80078l10.60156,-6.30078c0.60156,-0.39844 1,-1 1,-1.69922z"></path></g></g></svg>`,
+    url: 'https://www.bing.com/search?q=',
+  },
+  duckduckgo: {
+    name: 'DuckDuckGo搜索',
+    shortName: 'duckgo',
+    // DuckDuckGo 使用内联 SVG，避免依赖不存在的 Font Awesome 品牌图标
+    iconSvg: `<svg xmlns="http://www.w3.org/2000/svg" viewBox="4 4 40 40" focusable="false"><path fill="#ff3d00" d="M44,24c0,11-9,20-20,20S4,35,4,24S13,4,24,4S44,13,44,24z"></path><path fill="#fff" d="M26,16.2c-0.6-0.6-1.5-0.9-2.5-1.1c-0.4-0.5-1-1-1.9-1.5c-1.6-0.8-3.5-1.2-5.3-0.9h-0.4 c-0.1,0-0.2,0.1-0.4,0.1c0.2,0,1,0.4,1.6,0.6c-0.3,0.2-0.8,0.2-1.1,0.4c0,0,0,0-0.1,0L15.7,14c-0.1,0.2-0.2,0.4-0.2,0.5 c1.3-0.1,3.2,0,4.6,0.4C19,15,18,15.3,17.3,15.7c-0.5,0.3-1,0.6-1.3,1.1c-1.2,1.3-1.7,3.5-1.3,5.9c0.5,2.7,2.4,11.4,3.4,16.3 l0.3,1.6c0,0,3.5,0.4,5.6,0.4c1.2,0,3.2,0.3,3.7-0.2c-0.1,0-0.6-0.6-0.8-1.1c-0.5-1-1-1.9-1.4-2.6c-1.2-2.5-2.5-5.9-1.9-8.1 c0.1-0.4,0.1-2.1,0.4-2.3c2.6-1.7,2.4-0.1,3.5-0.8c0.5-0.4,1-0.9,1.2-1.5C29.4,22.1,27.8,18,26,16.2z"></path><path fill="#fff" d="M24,42c-9.9,0-18-8.1-18-18c0-9.9,8.1-18,18-18c9.9,0,18,8.1,18,18C42,33.9,33.9,42,24,42z M24,8 C15.2,8,8,15.2,8,24s7.2,16,16,16s16-7.2,16-16S32.8,8,24,8z"></path><path fill="#0277bd" d="M19,21.1c-0.6,0-1.2,0.5-1.2,1.2c0,0.6,0.5,1.2,1.2,1.2c0.6,0,1.2-0.5,1.2-1.2 C20.1,21.7,19.6,21.1,19,21.1z M19.5,22.2c-0.2,0-0.3-0.1-0.3-0.3c0-0.2,0.1-0.3,0.3-0.3s0.3,0.1,0.3,0.3 C19.8,22.1,19.6,22.2,19.5,22.2z M26.8,20.6c-0.6,0-1,0.5-1,1c0,0.6,0.5,1,1,1c0.6,0,1-0.5,1-1S27.3,20.6,26.8,20.6z M27.2,21.5 c-0.1,0-0.3-0.1-0.3-0.3c0-0.1,0.1-0.3,0.3-0.3c0.1,0,0.3,0.1,0.3,0.3S27.4,21.5,27.2,21.5z M19.3,18.9c0,0-0.9-0.4-1.7,0.1 c-0.9,0.5-0.8,1.1-0.8,1.1s-0.5-1,0.8-1.5C18.7,18.1,19.3,18.9,19.3,18.9 M27.4,18.8c0,0-0.6-0.4-1.1-0.4c-1,0-1.3,0.5-1.3,0.5 s0.2-1.1,1.5-0.9C27.1,18.2,27.4,18.8,27.4,18.8"></path><path fill="#8bc34a" d="M23.3,35.7c0,0-4.3-2.3-4.4-1.4c-0.1,0.9,0,4.7,0.5,5s4.1-1.9,4.1-1.9L23.3,35.7z M25,35.6 c0,0,2.9-2.2,3.6-2.1c0.6,0.1,0.8,4.7,0.2,4.9c-0.6,0.2-3.9-1.2-3.9-1.2L25,35.6z"></path><path fill="#689f38" d="M22.5,35.7c0,1.5-0.2,2.1,0.4,2.3c0.6,0.1,1.9,0,2.3-0.3c0.4-0.3,0.1-2.2-0.1-2.6 C25,34.8,22.5,35.1,22.5,35.7"></path><path fill="#ffca28" d="M22.3,26.8c0.1-0.7,2-2.1,3.3-2.2c1.3-0.1,1.7-0.1,2.8-0.3c1.1-0.3,3.9-1,4.7-1.3 c0.8-0.4,4.1,0.2,1.8,1.5c-1,0.6-3.7,1.6-5.7,2.2c-1.9,0.6-3.1-0.6-3.8,0.4c-0.5,0.8-0.1,1.8,2.2,2c3.1,0.3,6.2-1.4,6.5-0.5 c0.3,0.9-2.7,2-4.6,2.1c-1.8,0-5.6-1.2-6.1-1.6C22.9,28.7,22.2,27.8,22.3,26.8"></path></svg>`,
+    url: 'https://duckduckgo.com/?q=',
+  },
+};
diff --git a/src/runtime/app/ui.js b/src/runtime/app/ui.js
new file mode 100644
index 0000000000000000000000000000000000000000..8203ed399d834b3d482f5f2fc29dd651f39a503f
--- /dev/null
+++ b/src/runtime/app/ui.js
@@ -0,0 +1,305 @@
+module.exports = function initUi(state, dom) {
+  const {
+    searchInput,
+    searchBox,
+    menuToggle,
+    searchToggle,
+    sidebar,
+    searchContainer,
+    overlay,
+    sidebarToggle,
+    content,
+    themeToggle,
+    themeIcon,
+  } = dom;
+
+  const SUBMENU_PANEL_VISIBLE_CLASS = 'submenu-panel-visible';
+  const SIDEBAR_LAYOUT_TRANSITION_MS = 300;
+  let submenuPanelRevealTimer = null;
+
+  // 移除预加载类，允许 CSS 过渡效果
+  document.documentElement.classList.remove('preload');
+
+  let systemThemeMql = null;
+  let systemThemeListener = null;
+
+  function setTheme(isLight) {
+    const nextIsLight = Boolean(isLight);
+    state.isLightTheme = nextIsLight;
+    document.body.classList.toggle('light-theme', nextIsLight);
+
+    if (nextIsLight) {
+      themeIcon.classList.remove('fa-moon');
+      themeIcon.classList.add('fa-sun');
+    } else {
+      themeIcon.classList.remove('fa-sun');
+      themeIcon.classList.add('fa-moon');
+    }
+  }
+
+  function stopSystemThemeFollow() {
+    if (systemThemeMql && systemThemeListener) {
+      if (typeof systemThemeMql.removeEventListener === 'function') {
+        systemThemeMql.removeEventListener('change', systemThemeListener);
+      } else if (typeof systemThemeMql.removeListener === 'function') {
+        systemThemeMql.removeListener(systemThemeListener);
+      }
+    }
+    systemThemeMql = null;
+    systemThemeListener = null;
+  }
+
+  function startSystemThemeFollow() {
+    stopSystemThemeFollow();
+
+    try {
+      systemThemeMql = window.matchMedia('(prefers-color-scheme: light)');
+    } catch (e) {
+      systemThemeMql = null;
+    }
+    if (!systemThemeMql) return;
+
+    systemThemeListener = (event) => {
+      const savedTheme = localStorage.getItem('theme');
+      if (savedTheme === 'light' || savedTheme === 'dark') {
+        stopSystemThemeFollow();
+        return;
+      }
+      setTheme(Boolean(event && event.matches));
+    };
+
+    if (typeof systemThemeMql.addEventListener === 'function') {
+      systemThemeMql.addEventListener('change', systemThemeListener);
+    } else if (typeof systemThemeMql.addListener === 'function') {
+      systemThemeMql.addListener(systemThemeListener);
+    }
+  }
+
+  function getThemeMode() {
+    const raw = document.documentElement.getAttribute('data-theme-mode');
+    return raw ? String(raw).trim().toLowerCase() : 'dark';
+  }
+
+  // 应用预加载阶段确定的主题（localStorage / site.theme.mode）
+  if (document.documentElement.classList.contains('theme-preload')) {
+    document.documentElement.classList.remove('theme-preload');
+    setTheme(true);
+  } else {
+    setTheme(false);
+  }
+
+  // 应用从 localStorage 读取的侧边栏状态（预加载阶段已写入 class）
+  if (document.documentElement.classList.contains('sidebar-collapsed-preload')) {
+    document.documentElement.classList.remove('sidebar-collapsed-preload');
+    sidebar.classList.add('collapsed');
+    content.classList.add('expanded');
+    state.isSidebarCollapsed = true;
+  }
+
+  // 即时移除 loading 类，确保侧边栏可见
+  document.body.classList.remove('loading');
+  document.body.classList.add('loaded');
+
+  function isMobile() {
+    return window.innerWidth <= 768;
+  }
+
+  function clearSubmenuPanelRevealTimer() {
+    if (submenuPanelRevealTimer) {
+      window.clearTimeout(submenuPanelRevealTimer);
+      submenuPanelRevealTimer = null;
+    }
+  }
+
+  function hideSubmenuPanelImmediately() {
+    clearSubmenuPanelRevealTimer();
+    sidebar.classList.remove(SUBMENU_PANEL_VISIBLE_CLASS);
+  }
+
+  function showSubmenuPanelImmediately() {
+    clearSubmenuPanelRevealTimer();
+    sidebar.classList.add(SUBMENU_PANEL_VISIBLE_CLASS);
+  }
+
+  function revealSubmenuPanelAfterSidebarTransition() {
+    clearSubmenuPanelRevealTimer();
+    submenuPanelRevealTimer = window.setTimeout(() => {
+      if (!state.isSidebarCollapsed && !sidebar.classList.contains('collapsed')) {
+        sidebar.classList.add(SUBMENU_PANEL_VISIBLE_CLASS);
+      }
+    }, SIDEBAR_LAYOUT_TRANSITION_MS);
+  }
+
+  // 侧边栏折叠功能
+  function toggleSidebarCollapse() {
+    // 仅在交互时启用布局相关动画，避免首屏闪烁
+    document.documentElement.classList.add('with-anim');
+
+    state.isSidebarCollapsed = !state.isSidebarCollapsed;
+
+    if (state.isSidebarCollapsed) {
+      // 收起时立即隐藏目录面板，避免在动画过程中残留。
+      hideSubmenuPanelImmediately();
+    }
+
+    // 使用 requestAnimationFrame 确保平滑过渡
+    requestAnimationFrame(() => {
+      sidebar.classList.toggle('collapsed', state.isSidebarCollapsed);
+      content.classList.toggle('expanded', state.isSidebarCollapsed);
+
+      // 保存折叠状态到 localStorage
+      localStorage.setItem('sidebarCollapsed', state.isSidebarCollapsed ? 'true' : 'false');
+
+      if (!state.isSidebarCollapsed) {
+        // 展开后再淡入目录面板，避免和宽度动画抢节奏。
+        revealSubmenuPanelAfterSidebarTransition();
+      }
+    });
+  }
+
+  // 初始化侧边栏折叠状态 - 已在页面加载前处理，此处仅完成图标状态初始化等次要任务
+  function initSidebarState() {
+    // 从 localStorage 获取侧边栏状态
+    const savedState = localStorage.getItem('sidebarCollapsed');
+
+    // 图标状态与折叠状态保持一致
+    if (savedState === 'true' && !isMobile()) {
+      state.isSidebarCollapsed = true;
+      hideSubmenuPanelImmediately();
+    } else {
+      state.isSidebarCollapsed = false;
+      showSubmenuPanelImmediately();
+    }
+  }
+
+  // 主题切换功能
+  function toggleTheme() {
+    setTheme(!state.isLightTheme);
+
+    // 用户手动切换后：写入 localStorage，并停止 system 跟随
+    localStorage.setItem('theme', state.isLightTheme ? 'light' : 'dark');
+    stopSystemThemeFollow();
+  }
+
+  // 初始化主题 - 已在页面加载前处理，此处仅完成图标状态初始化等次要任务
+  function initTheme() {
+    // 从 localStorage 获取主题偏好
+    const savedTheme = localStorage.getItem('theme');
+    if (savedTheme === 'light') {
+      stopSystemThemeFollow();
+      setTheme(true);
+      return;
+    }
+    if (savedTheme === 'dark') {
+      stopSystemThemeFollow();
+      setTheme(false);
+      return;
+    }
+
+    // 未写入 localStorage：按 site.theme.mode 决定默认值
+    const mode = getThemeMode();
+
+    if (mode === 'light') {
+      stopSystemThemeFollow();
+      setTheme(true);
+      return;
+    }
+
+    if (mode === 'system') {
+      let shouldUseLight = false;
+      try {
+        shouldUseLight =
+          window.matchMedia && window.matchMedia('(prefers-color-scheme: light)').matches;
+      } catch (e) {
+        shouldUseLight = false;
+      }
+      setTheme(shouldUseLight);
+      startSystemThemeFollow();
+      return;
+    }
+
+    // 默认 dark
+    stopSystemThemeFollow();
+    setTheme(false);
+  }
+
+  // 移动端菜单切换
+  function toggleSidebar() {
+    state.isSidebarOpen = !state.isSidebarOpen;
+    sidebar.classList.toggle('active', state.isSidebarOpen);
+    overlay.classList.toggle('active', state.isSidebarOpen);
+  }
+
+  // 移动端：搜索框常驻显示（CSS 控制），无需“搜索面板”开关；点击仅聚焦输入框
+  function toggleSearch() {
+    searchInput && searchInput.focus();
+  }
+
+  // 关闭所有移动端面板
+  function closeAllPanels() {
+    if (state.isSidebarOpen) {
+      toggleSidebar();
+    }
+  }
+
+  // 侧边栏折叠按钮点击事件
+  if (sidebarToggle) {
+    sidebarToggle.addEventListener('click', toggleSidebarCollapse);
+  }
+
+  // 主题切换按钮点击事件
+  themeToggle.addEventListener('click', toggleTheme);
+
+  // 移动端事件监听
+  menuToggle.addEventListener('click', toggleSidebar);
+  searchToggle.addEventListener('click', toggleSearch);
+  overlay.addEventListener('click', closeAllPanels);
+
+  // 全局快捷键：Ctrl/Cmd + K 聚焦搜索
+  document.addEventListener('keydown', (e) => {
+    const key = (e.key || '').toLowerCase();
+    if (key !== 'k') return;
+    if ((!e.ctrlKey && !e.metaKey) || e.altKey) return;
+
+    const target = e.target;
+    const isTypingTarget =
+      target &&
+      (target.tagName === 'INPUT' || target.tagName === 'TEXTAREA' || target.isContentEditable);
+
+    if (isTypingTarget && target !== searchInput) return;
+
+    e.preventDefault();
+
+    searchInput && searchInput.focus();
+  });
+
+  // 窗口大小改变时处理
+  window.addEventListener('resize', () => {
+    if (!isMobile()) {
+      sidebar.classList.remove('active');
+      searchContainer.classList.remove('active');
+      overlay.classList.remove('active');
+      state.isSidebarOpen = false;
+      if (state.isSidebarCollapsed) {
+        hideSubmenuPanelImmediately();
+      } else {
+        showSubmenuPanelImmediately();
+      }
+    } else {
+      // 在移动设备下，重置侧边栏折叠状态
+      sidebar.classList.remove('collapsed');
+      content.classList.remove('expanded');
+      showSubmenuPanelImmediately();
+    }
+  });
+
+  // 仅用于静态检查：确保未用变量不被 lint 报错（未来可用于搜索 UI 状态）
+  void searchBox;
+
+  return {
+    isMobile,
+    closeAllPanels,
+    initTheme,
+    initSidebarState,
+  };
+};
diff --git a/src/runtime/index.js b/src/runtime/index.js
new file mode 100644
index 0000000000000000000000000000000000000000..69f3549279384342d529332b1e3e4fa7546ea4c7
--- /dev/null
+++ b/src/runtime/index.js
@@ -0,0 +1,17 @@
+// 运行时入口（由构建阶段打包输出 dist/script.js）
+const { menavUpdateAppHeight } = require('./shared');
+
+// 让页面在不同视口（含移动端地址栏变化）下保持正确高度
+menavUpdateAppHeight();
+window.addEventListener('resize', menavUpdateAppHeight);
+if (window.visualViewport) {
+  window.visualViewport.addEventListener('resize', menavUpdateAppHeight);
+}
+
+// 扩展契约：先初始化 window.MeNav，再挂载 nested API 与应用逻辑
+require('./menav');
+require('./nested');
+require('./app');
+
+// tooltip 独立模块：内部会按需监听 DOMContentLoaded
+require('./tooltip');
diff --git a/src/runtime/menav/addElement.js b/src/runtime/menav/addElement.js
new file mode 100644
index 0000000000000000000000000000000000000000..769f29cb6224b2586574ceb7df2c316f9b5925c1
--- /dev/null
+++ b/src/runtime/menav/addElement.js
@@ -0,0 +1,370 @@
+const { menavExtractDomain, menavSanitizeClassList, menavSanitizeUrl } = require('../shared');
+
+// 添加新元素
+module.exports = function addElement(type, parentId, data) {
+  if (type === 'site') {
+    // 查找父级分类
+    const parent = document.querySelector(`[data-type="category"][data-name="${parentId}"]`);
+    if (!parent) return null;
+
+    // 添加站点卡片到分类
+    const sitesContainer = parent.querySelector('[data-container="sites"]');
+    if (!sitesContainer) return null;
+
+    // 站点卡片样式：根据“页面模板”决定（friends/articles/projects 等）
+    let siteCardStyle = '';
+    try {
+      const pageEl = parent.closest('.page');
+      const pageId = pageEl && pageEl.id ? String(pageEl.id).trim() : '';
+      const cfg =
+        window.MeNav && typeof window.MeNav.getConfig === 'function'
+          ? window.MeNav.getConfig()
+          : null;
+
+      let templateName = '';
+
+      const pageTemplates =
+        cfg && cfg.data && cfg.data.pageTemplates && typeof cfg.data.pageTemplates === 'object'
+          ? cfg.data.pageTemplates
+          : null;
+
+      const templateFromMap =
+        pageTemplates && pageId && pageTemplates[pageId]
+          ? String(pageTemplates[pageId]).trim()
+          : '';
+
+      // 兼容旧版：cfg.data[pageId].template
+      const legacyPageConfig = cfg && cfg.data && pageId ? cfg.data[pageId] : null;
+      const templateFromLegacy =
+        legacyPageConfig && legacyPageConfig.template
+          ? String(legacyPageConfig.template).trim()
+          : '';
+
+      if (templateFromMap) {
+        templateName = templateFromMap;
+      } else if (templateFromLegacy) {
+        templateName = templateFromLegacy;
+      }
+
+      // projects 模板使用代码仓库风格卡片（与生成端 templates/components/site-card.hbs 保持一致）
+      if (templateName === 'projects') siteCardStyle = 'repo';
+    } catch (e) {
+      siteCardStyle = '';
+    }
+
+    // 创建新的站点卡片
+    const newSite = document.createElement('a');
+    newSite.className = siteCardStyle ? `site-card site-card-${siteCardStyle}` : 'site-card';
+
+    const siteName = data.name || '未命名站点';
+    const siteUrl = data.url || '#';
+    const siteIcon = data.icon || 'fas fa-link';
+    const siteDescription = data.description || (data.url ? menavExtractDomain(data.url) : '');
+    const siteFaviconUrl = data && data.faviconUrl ? String(data.faviconUrl).trim() : '';
+    const siteForceIconModeRaw =
+      data && data.forceIconMode ? String(data.forceIconMode).trim() : '';
+    const siteForceIconMode =
+      siteForceIconModeRaw === 'manual' || siteForceIconModeRaw === 'favicon'
+        ? siteForceIconModeRaw
+        : '';
+
+    const safeSiteUrl = menavSanitizeUrl(siteUrl, 'addElement(site).url');
+    const safeSiteIcon = menavSanitizeClassList(siteIcon, 'addElement(site).icon');
+
+    newSite.setAttribute('href', safeSiteUrl);
+    newSite.title = siteName + (siteDescription ? ' - ' + siteDescription : '');
+    newSite.setAttribute(
+      'data-tooltip',
+      siteName + (siteDescription ? ' - ' + siteDescription : '')
+    );
+    if (/^https?:\/\//i.test(safeSiteUrl)) {
+      newSite.target = '_blank';
+      newSite.rel = 'noopener';
+    }
+
+    // 设置数据属性
+    newSite.setAttribute('data-type', 'site');
+    newSite.setAttribute('data-name', siteName);
+    // 保留原始 URL（data-url）供扩展/调试读取；href 仍会做安全降级
+    newSite.setAttribute('data-url', String(data.url || '').trim());
+    newSite.setAttribute('data-icon', safeSiteIcon);
+    if (siteFaviconUrl) newSite.setAttribute('data-favicon-url', siteFaviconUrl);
+    if (siteForceIconMode) newSite.setAttribute('data-force-icon-mode', siteForceIconMode);
+    newSite.setAttribute('data-description', siteDescription);
+
+    // projects repo 风格：与模板中的 repo 结构保持一致（不走 favicon 逻辑）
+    if (siteCardStyle === 'repo') {
+      const repoHeader = document.createElement('div');
+      repoHeader.className = 'repo-header';
+
+      const repoIcon = document.createElement('i');
+      repoIcon.className = `${safeSiteIcon || 'fas fa-code'} repo-icon`;
+      repoIcon.setAttribute('aria-hidden', 'true');
+
+      const repoTitle = document.createElement('div');
+      repoTitle.className = 'repo-title';
+      repoTitle.textContent = siteName;
+
+      repoHeader.appendChild(repoIcon);
+      repoHeader.appendChild(repoTitle);
+
+      const repoDesc = document.createElement('div');
+      repoDesc.className = 'repo-desc';
+      repoDesc.textContent = siteDescription;
+
+      newSite.appendChild(repoHeader);
+      newSite.appendChild(repoDesc);
+
+      const hasStats = data && (data.language || data.stars || data.forks || data.issues);
+
+      if (hasStats) {
+        const repoStats = document.createElement('div');
+        repoStats.className = 'repo-stats';
+
+        if (data.language) {
+          const languageItem = document.createElement('div');
+          languageItem.className = 'stat-item';
+
+          const langDot = document.createElement('span');
+          langDot.className = 'lang-dot';
+          langDot.style.backgroundColor = data.languageColor || '#909296';
+
+          languageItem.appendChild(langDot);
+          languageItem.appendChild(document.createTextNode(String(data.language)));
+          repoStats.appendChild(languageItem);
+        }
+
+        if (data.stars) {
+          const starsItem = document.createElement('div');
+          starsItem.className = 'stat-item';
+
+          const starIcon = document.createElement('i');
+          starIcon.className = 'far fa-star';
+          starIcon.setAttribute('aria-hidden', 'true');
+          starsItem.appendChild(starIcon);
+          starsItem.appendChild(document.createTextNode(String(data.stars)));
+          repoStats.appendChild(starsItem);
+        }
+
+        if (data.forks) {
+          const forksItem = document.createElement('div');
+          forksItem.className = 'stat-item';
+
+          const forkIcon = document.createElement('i');
+          forkIcon.className = 'fas fa-code-branch';
+          forkIcon.setAttribute('aria-hidden', 'true');
+          forksItem.appendChild(forkIcon);
+          forksItem.appendChild(document.createTextNode(String(data.forks)));
+          repoStats.appendChild(forksItem);
+        }
+
+        if (data.issues) {
+          const issuesItem = document.createElement('div');
+          issuesItem.className = 'stat-item';
+
+          const issueIcon = document.createElement('i');
+          issueIcon.className = 'fas fa-exclamation-circle';
+          issueIcon.setAttribute('aria-hidden', 'true');
+          issuesItem.appendChild(issueIcon);
+          issuesItem.appendChild(document.createTextNode(String(data.issues)));
+          repoStats.appendChild(issuesItem);
+        }
+
+        newSite.appendChild(repoStats);
+      }
+    } else {
+      // 普通站点卡片：复用现有结构（支持 favicon）
+      const siteCardIcon = document.createElement('div');
+      siteCardIcon.className = 'site-card-icon';
+
+      const iconEl = document.createElement('i');
+      iconEl.className = safeSiteIcon || 'fas fa-link';
+      iconEl.setAttribute('aria-hidden', 'true');
+
+      // 添加内容（根据图标模式渲染，避免 innerHTML 注入）
+      siteCardIcon.appendChild(iconEl);
+
+      const titleEl = document.createElement('h3');
+      titleEl.textContent = siteName;
+
+      const descEl = document.createElement('p');
+      descEl.textContent = siteDescription;
+
+      newSite.appendChild(siteCardIcon);
+      newSite.appendChild(titleEl);
+      newSite.appendChild(descEl);
+
+      // favicon 模式：优先加载 faviconUrl；否则按 url 生成
+      try {
+        const cfg =
+          window.MeNav && typeof window.MeNav.getConfig === 'function'
+            ? window.MeNav.getConfig()
+            : null;
+        const iconsMode =
+          cfg && cfg.icons && cfg.icons.mode ? String(cfg.icons.mode).trim() : 'favicon';
+        const iconsRegion =
+          cfg && cfg.icons && cfg.icons.region ? String(cfg.icons.region).trim() : 'com';
+
+        const forceMode = siteForceIconMode || '';
+        const shouldUseFavicon = forceMode ? forceMode === 'favicon' : iconsMode === 'favicon';
+
+        if (shouldUseFavicon) {
+          const faviconImg = document.createElement('img');
+          faviconImg.className = 'site-icon';
+          faviconImg.loading = 'lazy';
+          faviconImg.alt = siteName;
+
+          const fallbackToIcon = () => {
+            faviconImg.remove();
+            iconEl.classList.add('icon-fallback');
+          };
+
+          // 超时处理：5秒后如果还没加载成功，显示回退图标
+          const timeoutId = setTimeout(() => {
+            fallbackToIcon();
+          }, 5000);
+
+          faviconImg.onerror = () => {
+            clearTimeout(timeoutId);
+            fallbackToIcon();
+          };
+          faviconImg.onload = () => {
+            clearTimeout(timeoutId);
+            iconEl.remove();
+          };
+
+          if (siteFaviconUrl) {
+            faviconImg.src = siteFaviconUrl;
+          } else {
+            const urlToUse = String(data.url || '').trim();
+            if (urlToUse) {
+              // 根据 icons.region 配置决定优先使用哪个域名
+              const urls = [];
+              // drop_404_icon=true：缺失 favicon 时返回空 404，避免占位图导致 onerror 不触发，从而可靠走回退逻辑
+              const comUrl = `https://t3.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=${encodeURIComponent(
+                urlToUse
+              )}&size=32&drop_404_icon=true`;
+              const cnUrl = `https://t3.gstatic.cn/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=${encodeURIComponent(
+                urlToUse
+              )}&size=32&drop_404_icon=true`;
+              if (iconsRegion === 'cn') {
+                urls.push(cnUrl, comUrl);
+              } else {
+                urls.push(comUrl, cnUrl);
+              }
+
+              let idx = 0;
+              faviconImg.src = urls[idx];
+
+              // 超时处理：3秒后如果还没加载成功，尝试回退 URL 或显示 Font Awesome 图标
+              const fallbackTimeoutId = setTimeout(() => {
+                idx += 1;
+                if (idx < urls.length) {
+                  faviconImg.src = urls[idx];
+                } else {
+                  fallbackToIcon();
+                }
+              }, 3000);
+
+              const cleanup = () => clearTimeout(fallbackTimeoutId);
+              faviconImg.onload = () => {
+                clearTimeout(timeoutId);
+                cleanup();
+                iconEl.remove();
+              };
+              faviconImg.onerror = () => {
+                clearTimeout(timeoutId);
+                cleanup();
+                idx += 1;
+                if (idx < urls.length) {
+                  faviconImg.src = urls[idx];
+                } else {
+                  fallbackToIcon();
+                }
+              };
+            }
+          }
+
+          siteCardIcon.insertBefore(faviconImg, iconEl);
+        } else {
+          iconEl.classList.add('icon-fallback');
+        }
+      } catch (e) {
+        iconEl.classList.add('icon-fallback');
+      }
+    }
+
+    // 添加到 DOM
+    sitesContainer.appendChild(newSite);
+
+    // 移除“暂无网站”提示（如果存在）
+    const emptySites = sitesContainer.querySelector('.empty-sites');
+    if (emptySites) {
+      emptySites.remove();
+    }
+
+    // 触发元素添加事件
+    this.events.emit('elementAdded', {
+      id: siteName,
+      type: 'site',
+      parentId: parentId,
+      data: data,
+    });
+
+    return siteName;
+  } else if (type === 'category') {
+    // 查找父级页面容器
+    const parent = document.querySelector(`[data-page="${parentId}"]`);
+    if (!parent) return null;
+
+    // 创建新的分类
+    const newCategory = document.createElement('section');
+    newCategory.className = 'category';
+    newCategory.setAttribute('data-type', 'category');
+    newCategory.setAttribute('data-name', data.name || '未命名分类');
+    if (data.icon) {
+      newCategory.setAttribute(
+        'data-icon',
+        menavSanitizeClassList(data.icon, 'addElement(category).data-icon')
+      );
+    }
+
+    // 设置数据属性
+    newCategory.setAttribute('data-level', '1');
+
+    // 添加内容（用 DOM API 构建，避免 innerHTML 注入）
+    const titleEl = document.createElement('h2');
+    const iconEl = document.createElement('i');
+    iconEl.className = menavSanitizeClassList(
+      data.icon || 'fas fa-folder',
+      'addElement(category).icon'
+    );
+    titleEl.appendChild(iconEl);
+    titleEl.appendChild(document.createTextNode(' ' + String(data.name || '未命名分类')));
+
+    const sitesGrid = document.createElement('div');
+    sitesGrid.className = 'sites-grid';
+    sitesGrid.setAttribute('data-container', 'sites');
+    const emptyEl = document.createElement('p');
+    emptyEl.className = 'empty-sites';
+    emptyEl.textContent = '暂无网站';
+    sitesGrid.appendChild(emptyEl);
+
+    newCategory.appendChild(titleEl);
+    newCategory.appendChild(sitesGrid);
+
+    // 添加到 DOM
+    parent.appendChild(newCategory);
+
+    // 触发元素添加事件
+    this.events.emit('elementAdded', {
+      id: data.name,
+      type: 'category',
+      data: data,
+    });
+
+    return data.name;
+  }
+
+  return null;
+};
diff --git a/src/runtime/menav/events.js b/src/runtime/menav/events.js
new file mode 100644
index 0000000000000000000000000000000000000000..042bdce6627d9e766d625328c7bf1834f6d9247a
--- /dev/null
+++ b/src/runtime/menav/events.js
@@ -0,0 +1,34 @@
+module.exports = function createMenavEvents() {
+  return {
+    listeners: {},
+
+    // 添加事件监听器
+    on: function (event, callback) {
+      if (!this.listeners[event]) {
+        this.listeners[event] = [];
+      }
+      this.listeners[event].push(callback);
+      return this;
+    },
+
+    // 触发事件
+    emit: function (event, data) {
+      if (this.listeners[event]) {
+        this.listeners[event].forEach((callback) => callback(data));
+      }
+      return this;
+    },
+
+    // 移除事件监听器
+    off: function (event, callback) {
+      if (this.listeners[event]) {
+        if (callback) {
+          this.listeners[event] = this.listeners[event].filter((cb) => cb !== callback);
+        } else {
+          delete this.listeners[event];
+        }
+      }
+      return this;
+    },
+  };
+};
diff --git a/src/runtime/menav/getAllElements.js b/src/runtime/menav/getAllElements.js
new file mode 100644
index 0000000000000000000000000000000000000000..99cf5486224d1139794fd2c85bbfccfca3fa07ec
--- /dev/null
+++ b/src/runtime/menav/getAllElements.js
@@ -0,0 +1,11 @@
+// 获取所有元素
+module.exports = function getAllElements(type) {
+  return Array.from(document.querySelectorAll(`[data-type="${type}"]`)).map((el) => {
+    const id = this._getElementId(el);
+    return {
+      id: id,
+      type: type,
+      element: el,
+    };
+  });
+};
diff --git a/src/runtime/menav/getConfig.js b/src/runtime/menav/getConfig.js
new file mode 100644
index 0000000000000000000000000000000000000000..244b73e6a7bdfc25c2f63c0c1cd1d37d15d97bc5
--- /dev/null
+++ b/src/runtime/menav/getConfig.js
@@ -0,0 +1,25 @@
+// 配置数据缓存：避免浏览器扩展/站点脚本频繁 JSON.parse
+let menavConfigCacheReady = false;
+let menavConfigCacheRaw = null;
+let menavConfigCacheValue = null;
+
+module.exports = function getConfig(options) {
+  const configData = document.getElementById('menav-config-data');
+  if (!configData) return null;
+
+  const raw = configData.textContent || '';
+  if (!menavConfigCacheReady || menavConfigCacheRaw !== raw) {
+    menavConfigCacheValue = JSON.parse(raw);
+    menavConfigCacheRaw = raw;
+    menavConfigCacheReady = true;
+  }
+
+  if (options && options.clone) {
+    if (typeof structuredClone === 'function') {
+      return structuredClone(menavConfigCacheValue);
+    }
+    return JSON.parse(JSON.stringify(menavConfigCacheValue));
+  }
+
+  return menavConfigCacheValue;
+};
diff --git a/src/runtime/menav/index.js b/src/runtime/menav/index.js
new file mode 100644
index 0000000000000000000000000000000000000000..536ac0b5147a7299a37cae9dfa477456af0d9a1f
--- /dev/null
+++ b/src/runtime/menav/index.js
@@ -0,0 +1,71 @@
+const { menavDetectVersion } = require('../shared');
+
+const createMenavEvents = require('./events');
+const getConfig = require('./getConfig');
+const updateElement = require('./updateElement');
+const addElement = require('./addElement');
+const removeElement = require('./removeElement');
+const getAllElements = require('./getAllElements');
+
+function getDefaultElementId(element) {
+  const type = element.getAttribute('data-type');
+  if (type === 'nav-item') {
+    return element.getAttribute('data-id');
+  } else if (type === 'social-link') {
+    return element.getAttribute('data-url');
+  } else {
+    // 优先使用 data-id（例如分类 slug），回退 data-name（兼容旧扩展/旧页面）
+    return element.getAttribute('data-id') || element.getAttribute('data-name');
+  }
+}
+
+function findDefaultElement(type, id) {
+  let selector;
+  if (type === 'nav-item') {
+    selector = `[data-type="${type}"][data-id="${id}"]`;
+  } else if (type === 'social-link') {
+    selector = `[data-type="${type}"][data-url="${id}"]`;
+  } else if (type === 'site') {
+    // 站点：优先用 data-url（更稳定），回退 data-id/data-name
+    return (
+      document.querySelector(`[data-type="${type}"][data-url="${id}"]`) ||
+      document.querySelector(`[data-type="${type}"][data-id="${id}"]`) ||
+      document.querySelector(`[data-type="${type}"][data-name="${id}"]`)
+    );
+  } else {
+    // 其他：优先 data-id（例如分类 slug），回退 data-name（兼容旧扩展/旧页面）
+    return (
+      document.querySelector(`[data-type="${type}"][data-id="${id}"]`) ||
+      document.querySelector(`[data-type="${type}"][data-name="${id}"]`)
+    );
+  }
+  return document.querySelector(selector);
+}
+
+// 全局 MeNav 对象 - 用于浏览器扩展
+const existing = window.MeNav && typeof window.MeNav === 'object' ? window.MeNav : {};
+const events =
+  existing.events && typeof existing.events === 'object' ? existing.events : createMenavEvents();
+
+window.MeNav = Object.assign(existing, {
+  version: menavDetectVersion(),
+
+  getConfig: getConfig,
+
+  // 获取元素的唯一标识符
+  _getElementId: getDefaultElementId,
+
+  // 根据类型和ID查找元素
+  _findElement: findDefaultElement,
+
+  // 元素操作
+  updateElement: updateElement,
+  addElement: addElement,
+  removeElement: removeElement,
+  getAllElements: getAllElements,
+
+  // 事件系统
+  events: events,
+});
+
+module.exports = window.MeNav;
diff --git a/src/runtime/menav/removeElement.js b/src/runtime/menav/removeElement.js
new file mode 100644
index 0000000000000000000000000000000000000000..6692119a519d926b0d8c29c346579b46a6ddc53b
--- /dev/null
+++ b/src/runtime/menav/removeElement.js
@@ -0,0 +1,26 @@
+// 删除元素
+module.exports = function removeElement(type, id) {
+  const element = this._findElement(type, id);
+  if (!element) return false;
+
+  // 获取父级容器（如果是站点卡片）
+  let parentId = null;
+  if (type === 'site') {
+    const categoryElement = element.closest('[data-type="category"]');
+    if (categoryElement) {
+      parentId = categoryElement.getAttribute('data-name');
+    }
+  }
+
+  // 删除元素
+  element.remove();
+
+  // 触发元素删除事件
+  this.events.emit('elementRemoved', {
+    id: id,
+    type: type,
+    parentId: parentId,
+  });
+
+  return true;
+};
diff --git a/src/runtime/menav/updateElement.js b/src/runtime/menav/updateElement.js
new file mode 100644
index 0000000000000000000000000000000000000000..c714479fca0861893e1939f5781c1b6fc7653893
--- /dev/null
+++ b/src/runtime/menav/updateElement.js
@@ -0,0 +1,169 @@
+const { menavSanitizeClassList, menavSanitizeUrl } = require('../shared');
+
+// 更新 DOM 元素
+module.exports = function updateElement(type, id, newData) {
+  const element = this._findElement(type, id);
+  if (!element) return false;
+
+  if (type === 'site') {
+    // 更新站点卡片
+    if (newData.url) {
+      const safeUrl = menavSanitizeUrl(newData.url, 'updateElement(site).url');
+      element.setAttribute('href', safeUrl);
+      // 保留原始 URL 供扩展/调试读取，但点击行为以 href 的安全降级为准
+      element.setAttribute('data-url', String(newData.url).trim());
+    }
+    if (newData.name) {
+      element.querySelector('h3').textContent = newData.name;
+      element.setAttribute('data-name', newData.name);
+    }
+    if (newData.description) {
+      element.querySelector('p').textContent = newData.description;
+      element.setAttribute('data-description', newData.description);
+    }
+    if (newData.icon) {
+      const iconElement =
+        element.querySelector('i.icon-fallback') ||
+        element.querySelector('i.site-icon') ||
+        element.querySelector('.site-card-icon i') ||
+        element.querySelector('i');
+
+      if (iconElement) {
+        const nextIconClass = menavSanitizeClassList(newData.icon, 'updateElement(site).icon');
+        const preservedClasses = [];
+
+        if (iconElement.classList.contains('icon-fallback')) {
+          preservedClasses.push('icon-fallback');
+        }
+        if (iconElement.classList.contains('site-icon')) {
+          preservedClasses.push('site-icon');
+        }
+
+        if (nextIconClass) {
+          iconElement.className = nextIconClass;
+          preservedClasses.forEach((cls) => iconElement.classList.add(cls));
+        }
+      }
+      element.setAttribute(
+        'data-icon',
+        menavSanitizeClassList(newData.icon, 'updateElement(site).data-icon')
+      );
+    }
+    if (newData.title) element.title = newData.title;
+
+    // 触发元素更新事件
+    this.events.emit('elementUpdated', {
+      id: id,
+      type: 'site',
+      data: newData,
+    });
+
+    return true;
+  } else if (type === 'category') {
+    // 更新分类
+    if (newData.name) {
+      const titleElement = element.querySelector('h2');
+      if (titleElement) {
+        const iconElement = titleElement.querySelector('i');
+        const iconClass = iconElement ? iconElement.className : '';
+        const nextIcon = menavSanitizeClassList(
+          newData.icon || iconClass,
+          'updateElement(category).icon'
+        );
+
+        // 用 DOM API 重建标题，避免 innerHTML 注入
+        titleElement.textContent = '';
+        const nextIconEl = document.createElement('i');
+        if (nextIcon) nextIconEl.className = nextIcon;
+        titleElement.appendChild(nextIconEl);
+        titleElement.appendChild(document.createTextNode(' ' + String(newData.name)));
+      }
+      element.setAttribute('data-name', newData.name);
+    }
+    if (newData.icon) {
+      element.setAttribute(
+        'data-icon',
+        menavSanitizeClassList(newData.icon, 'updateElement(category).data-icon')
+      );
+    }
+
+    // 触发元素更新事件
+    this.events.emit('elementUpdated', {
+      id: id,
+      type: 'category',
+      data: newData,
+    });
+
+    return true;
+  } else if (type === 'nav-item') {
+    // 更新导航项
+    if (newData.name) {
+      const textElement = element.querySelector('.nav-text');
+      if (textElement) {
+        textElement.textContent = newData.name;
+      }
+      element.setAttribute('data-name', newData.name);
+    }
+    if (newData.icon) {
+      const iconElement = element.querySelector('i');
+      if (iconElement) {
+        iconElement.className = menavSanitizeClassList(
+          newData.icon,
+          'updateElement(nav-item).icon'
+        );
+      }
+      element.setAttribute(
+        'data-icon',
+        menavSanitizeClassList(newData.icon, 'updateElement(nav-item).data-icon')
+      );
+    }
+
+    // 触发元素更新事件
+    this.events.emit('elementUpdated', {
+      id: id,
+      type: 'nav-item',
+      data: newData,
+    });
+
+    return true;
+  } else if (type === 'social-link') {
+    // 更新社交链接
+    if (newData.url) {
+      const safeUrl = menavSanitizeUrl(newData.url, 'updateElement(social-link).url');
+      element.setAttribute('href', safeUrl);
+      // 保留原始 URL 供扩展/调试读取，但点击行为以 href 的安全降级为准
+      element.setAttribute('data-url', String(newData.url).trim());
+    }
+    if (newData.name) {
+      const textElement = element.querySelector('.nav-text');
+      if (textElement) {
+        textElement.textContent = newData.name;
+      }
+      element.setAttribute('data-name', newData.name);
+    }
+    if (newData.icon) {
+      const iconElement = element.querySelector('i');
+      if (iconElement) {
+        iconElement.className = menavSanitizeClassList(
+          newData.icon,
+          'updateElement(social-link).icon'
+        );
+      }
+      element.setAttribute(
+        'data-icon',
+        menavSanitizeClassList(newData.icon, 'updateElement(social-link).data-icon')
+      );
+    }
+
+    // 触发元素更新事件
+    this.events.emit('elementUpdated', {
+      id: id,
+      type: 'social-link',
+      data: newData,
+    });
+
+    return true;
+  }
+
+  return false;
+};
diff --git a/src/runtime/nested/index.js b/src/runtime/nested/index.js
new file mode 100644
index 0000000000000000000000000000000000000000..c6ee55830a9063c0033f181494210d2f8799b425
--- /dev/null
+++ b/src/runtime/nested/index.js
@@ -0,0 +1,232 @@
+// 多层级嵌套书签功能
+function getCollapsibleNestedContainers(root) {
+  if (!root) return [];
+  const headers = root.querySelectorAll(
+    '.category > .category-header[data-toggle="category"], .group > .group-header[data-toggle="group"]'
+  );
+  return Array.from(headers)
+    .map((header) => header.parentElement)
+    .filter(Boolean);
+}
+
+function isNestedContainerCollapsible(container) {
+  if (!container) return false;
+
+  if (container.classList.contains('category')) {
+    return Boolean(container.querySelector(':scope > .category-header[data-toggle="category"]'));
+  }
+
+  if (container.classList.contains('group')) {
+    return Boolean(container.querySelector(':scope > .group-header[data-toggle="group"]'));
+  }
+
+  return false;
+}
+
+// 更新分类切换按钮图标
+function updateCategoryToggleIcon(state) {
+  const toggleBtn = document.getElementById('category-toggle');
+  if (!toggleBtn) return;
+
+  const icon = toggleBtn.querySelector('i');
+  if (!icon) return;
+
+  if (state === 'up') {
+    icon.className = 'fas fa-angle-double-up';
+    toggleBtn.setAttribute('aria-label', '收起分类');
+  } else {
+    icon.className = 'fas fa-angle-double-down';
+    toggleBtn.setAttribute('aria-label', '展开分类');
+  }
+}
+
+// 切换嵌套元素
+function toggleNestedElement(container) {
+  if (!isNestedContainerCollapsible(container)) return;
+  const isCollapsed = container.classList.contains('collapsed');
+
+  if (isCollapsed) {
+    container.classList.remove('collapsed');
+    saveToggleState(container, 'expanded');
+  } else {
+    container.classList.add('collapsed');
+    saveToggleState(container, 'collapsed');
+  }
+
+  // 触发自定义事件
+  const event = new CustomEvent('nestedToggle', {
+    detail: {
+      element: container,
+      type: container.dataset.type,
+      name: container.dataset.name,
+      isCollapsed: !isCollapsed,
+    },
+  });
+  document.dispatchEvent(event);
+}
+
+// 保存切换状态
+function saveToggleState(element, state) {
+  const type = element.dataset.type;
+  const name = element.dataset.name;
+  const level = element.dataset.level || '1';
+  const key = `menav-toggle-${type}-${level}-${name}`;
+  localStorage.setItem(key, state);
+}
+
+// 恢复切换状态
+function restoreToggleState(element) {
+  const type = element.dataset.type;
+  const name = element.dataset.name;
+  const level = element.dataset.level || '1';
+  const key = `menav-toggle-${type}-${level}-${name}`;
+  const savedState = localStorage.getItem(key);
+
+  if (savedState === 'collapsed') {
+    element.classList.add('collapsed');
+  }
+}
+
+// 初始化嵌套分类
+function initializeNestedCategories() {
+  // 为所有可折叠元素添加切换功能
+  document.querySelectorAll('[data-toggle="category"], [data-toggle="group"]').forEach((header) => {
+    header.addEventListener('click', function (e) {
+      e.stopPropagation();
+      const container = this.parentElement;
+      toggleNestedElement(container);
+    });
+
+    // 恢复保存的状态
+    restoreToggleState(header.parentElement);
+  });
+}
+
+// 提取嵌套数据
+function extractNestedData(element) {
+  const data = {
+    name: element.dataset.name,
+    type: element.dataset.type,
+    level: element.dataset.level,
+    isCollapsed: element.classList.contains('collapsed'),
+  };
+
+  // 提取子元素数据
+  const subcategories = element.querySelectorAll(
+    ':scope > .category-content > .subcategories-container > .category'
+  );
+  if (subcategories.length > 0) {
+    data.subcategories = Array.from(subcategories).map((sub) => extractNestedData(sub));
+  }
+
+  const groups = element.querySelectorAll(
+    ':scope > .category-content > .groups-container > .group'
+  );
+  if (groups.length > 0) {
+    data.groups = Array.from(groups).map((group) => extractNestedData(group));
+  }
+
+  const subgroups = element.querySelectorAll(
+    ':scope > .group-content > .subgroups-container > .group'
+  );
+  if (subgroups.length > 0) {
+    data.subgroups = Array.from(subgroups).map((subgroup) => extractNestedData(subgroup));
+  }
+
+  const sites = element.querySelectorAll(
+    ':scope > .category-content > .sites-grid > .site-card, :scope > .group-content > .sites-grid > .site-card'
+  );
+  if (sites.length > 0) {
+    data.sites = Array.from(sites).map((site) => ({
+      name: site.dataset.name,
+      url: site.dataset.url,
+      icon: site.dataset.icon,
+      description: site.dataset.description,
+    }));
+  }
+
+  return data;
+}
+
+function registerNestedApi() {
+  if (!window.MeNav) {
+    // runtime 入口会先初始化 MeNav；这里兜底避免报错
+    window.MeNav = {};
+  }
+
+  window.MeNav.expandAll = function () {
+    const activePage = document.querySelector('.page.active');
+    if (activePage) {
+      getCollapsibleNestedContainers(activePage).forEach((element) => {
+        element.classList.remove('collapsed');
+        saveToggleState(element, 'expanded');
+      });
+    }
+  };
+
+  window.MeNav.collapseAll = function () {
+    const activePage = document.querySelector('.page.active');
+    if (activePage) {
+      getCollapsibleNestedContainers(activePage).forEach((element) => {
+        element.classList.add('collapsed');
+        saveToggleState(element, 'collapsed');
+      });
+    }
+  };
+
+  // 智能切换分类展开/收起状态
+  window.MeNav.toggleCategories = function () {
+    const activePage = document.querySelector('.page.active');
+    if (!activePage) return;
+
+    const allElements = getCollapsibleNestedContainers(activePage);
+    const collapsedElements = allElements.filter((element) =>
+      element.classList.contains('collapsed')
+    );
+    if (allElements.length === 0) return;
+
+    // 如果收起的数量 >= 总数的一半，执行展开；否则执行收起
+    if (collapsedElements.length >= allElements.length / 2) {
+      window.MeNav.expandAll();
+      updateCategoryToggleIcon('up');
+    } else {
+      window.MeNav.collapseAll();
+      updateCategoryToggleIcon('down');
+    }
+  };
+
+  window.MeNav.toggleCategory = function (
+    categoryName,
+    subcategoryName = null,
+    groupName = null,
+    subgroupName = null
+  ) {
+    let selector = `[data-name="${categoryName}"]`;
+
+    if (subcategoryName) selector += ` [data-name="${subcategoryName}"]`;
+    if (groupName) selector += ` [data-name="${groupName}"]`;
+    if (subgroupName) selector += ` [data-name="${subgroupName}"]`;
+
+    const element = document.querySelector(selector);
+    if (element) {
+      toggleNestedElement(element);
+    }
+  };
+
+  window.MeNav.getNestedStructure = function () {
+    // 返回完整的嵌套结构数据
+    const categories = [];
+    document.querySelectorAll('.category-level-1').forEach((cat) => {
+      categories.push(extractNestedData(cat));
+    });
+    return categories;
+  };
+}
+
+registerNestedApi();
+
+module.exports = {
+  initializeNestedCategories,
+  updateCategoryToggleIcon,
+  extractNestedData,
+};
diff --git a/src/runtime/shared.js b/src/runtime/shared.js
new file mode 100644
index 0000000000000000000000000000000000000000..47fba400aac4f03d3c06e19ff5a6dec518e79b41
--- /dev/null
+++ b/src/runtime/shared.js
@@ -0,0 +1,141 @@
+function menavExtractDomain(url) {
+  if (!url) return '';
+
+  try {
+    // 移除协议部分 (http://, https://, etc.)
+    let domain = String(url).replace(/^[a-zA-Z]+:\/\//, '');
+
+    // 移除路径、查询参数和锚点
+    domain = domain.split('/')[0].split('?')[0].split('#')[0];
+
+    // 移除端口号（如果有）
+    domain = domain.split(':')[0];
+
+    return domain;
+  } catch (e) {
+    return String(url);
+  }
+}
+
+// URL 安全策略：默认仅允许 http/https（可加 mailto/tel）与相对链接；其他 scheme 降级为 '#'
+function menavGetAllowedUrlSchemes() {
+  try {
+    const cfg =
+      window.MeNav && typeof window.MeNav.getConfig === 'function'
+        ? window.MeNav.getConfig()
+        : null;
+    const fromConfig =
+      cfg &&
+      cfg.data &&
+      cfg.data.site &&
+      cfg.data.site.security &&
+      cfg.data.site.security.allowedSchemes;
+    if (Array.isArray(fromConfig) && fromConfig.length > 0) {
+      return fromConfig
+        .map((s) =>
+          String(s || '')
+            .trim()
+            .toLowerCase()
+            .replace(/:$/, '')
+        )
+        .filter(Boolean);
+    }
+  } catch (e) {
+    // 忽略，回退默认
+  }
+  return ['http', 'https', 'mailto', 'tel'];
+}
+
+function menavIsRelativeUrl(url) {
+  const s = String(url || '').trim();
+  return (
+    s.startsWith('#') ||
+    s.startsWith('/') ||
+    s.startsWith('./') ||
+    s.startsWith('../') ||
+    s.startsWith('?')
+  );
+}
+
+function menavSanitizeUrl(rawUrl, contextLabel) {
+  if (rawUrl === undefined || rawUrl === null) return '#';
+  const url = String(rawUrl).trim();
+  if (!url) return '#';
+
+  if (menavIsRelativeUrl(url)) return url;
+
+  // 明确拒绝协议相对 URL（//example.com），避免意外绕过策略
+  if (url.startsWith('//')) {
+    console.warn(`[MeNav][安全] 已拦截不安全 URL（协议相对形式）：${contextLabel || ''}`, url);
+    return '#';
+  }
+
+  try {
+    const parsed = new URL(url);
+    const scheme = String(parsed.protocol || '')
+      .toLowerCase()
+      .replace(/:$/, '');
+    const allowed = menavGetAllowedUrlSchemes();
+    if (allowed.includes(scheme)) return url;
+    console.warn(`[MeNav][安全] 已拦截不安全 URL scheme：${contextLabel || ''}`, url);
+    return '#';
+  } catch (e) {
+    console.warn(`[MeNav][安全] 已拦截无法解析的 URL：${contextLabel || ''}`, url);
+    return '#';
+  }
+}
+
+// class token 清洗：仅允许字母/数字/下划线/中划线与空格分隔，避免属性/事件注入
+function menavSanitizeClassList(rawClassList, contextLabel) {
+  const input = String(rawClassList || '').trim();
+  if (!input) return '';
+
+  const tokens = input
+    .split(/\s+/g)
+    .map((t) => t.trim())
+    .filter(Boolean)
+    .map((t) => t.replace(/[^\w-]/g, ''))
+    .filter(Boolean);
+
+  const sanitized = tokens.join(' ');
+  if (sanitized !== input) {
+    console.warn(`[MeNav][安全] 已清洗不安全的 icon class：${contextLabel || ''}`, rawClassList);
+  }
+  return sanitized;
+}
+
+// 版本号统一来源：优先读取 meta[menav-version]，回退到 menav-config-data.version
+function menavDetectVersion() {
+  try {
+    const meta = document.querySelector('meta[name="menav-version"]');
+    const v = meta ? String(meta.getAttribute('content') || '').trim() : '';
+    if (v) return v;
+  } catch (e) {
+    // 忽略
+  }
+
+  try {
+    const configData = document.getElementById('menav-config-data');
+    const raw = configData ? String(configData.textContent || '').trim() : '';
+    if (!raw) return '1.0.0';
+    const parsed = JSON.parse(raw);
+    const v = parsed && parsed.version ? String(parsed.version).trim() : '';
+    return v || '1.0.0';
+  } catch (e) {
+    return '1.0.0';
+  }
+}
+
+// 修复移动端 `100vh` 视口高度问题：用实际可视高度驱动布局，避免侧边栏/内容区底部被浏览器 UI 遮挡
+function menavUpdateAppHeight() {
+  const viewportHeight = window.visualViewport ? window.visualViewport.height : window.innerHeight;
+  document.documentElement.style.setProperty('--app-height', `${Math.round(viewportHeight)}px`);
+}
+
+module.exports = {
+  menavExtractDomain,
+  menavSanitizeUrl,
+  menavSanitizeClassList,
+  menavDetectVersion,
+  menavUpdateAppHeight,
+};
diff --git a/src/runtime/tooltip.js b/src/runtime/tooltip.js
new file mode 100644
index 0000000000000000000000000000000000000000..940ccb61a1c80d4813e93d7170f50da54f26f83f
--- /dev/null
+++ b/src/runtime/tooltip.js
@@ -0,0 +1,114 @@
+// Tooltip functionality for truncated text（仅桌面端/支持悬停设备启用）
+document.addEventListener('DOMContentLoaded', () => {
+  const hoverMedia = window.matchMedia && window.matchMedia('(hover: hover) and (pointer: fine)');
+
+  if (!hoverMedia) {
+    return;
+  }
+
+  let cleanupTooltip = null;
+
+  function enableTooltip() {
+    if (cleanupTooltip) return;
+
+    // Create tooltip element
+    const tooltip = document.createElement('div');
+    tooltip.className = 'custom-tooltip';
+    document.body.appendChild(tooltip);
+
+    let activeElement = null;
+
+    function updateTooltipPosition() {
+      if (!activeElement) return;
+
+      const rect = activeElement.getBoundingClientRect();
+      const tooltipRect = tooltip.getBoundingClientRect();
+      const gap = 10; // 卡片与Tooltip的间距
+
+      // 默认显示在卡片下方
+      let top = rect.bottom + gap;
+      // 水平居中对齐
+      let left = rect.left + (rect.width - tooltipRect.width) / 2;
+
+      const winWidth = window.innerWidth;
+      const winHeight = window.innerHeight;
+
+      // 垂直边界检查：如果下方空间不足，尝试显示在上方
+      if (top + tooltipRect.height > winHeight - gap) {
+        top = rect.top - tooltipRect.height - gap;
+      }
+
+      // 水平边界检查：防止溢出屏幕左右边界
+      if (left < gap) {
+        left = gap;
+      } else if (left + tooltipRect.width > winWidth - gap) {
+        left = winWidth - tooltipRect.width - gap;
+      }
+
+      tooltip.style.left = left + 'px';
+      tooltip.style.top = top + 'px';
+    }
+
+    // Show tooltip on hover
+    function onMouseOver(e) {
+      const target = e.target.closest('[data-tooltip]');
+      if (!target) return;
+
+      const tooltipText = target.getAttribute('data-tooltip');
+      if (!tooltipText) return;
+
+      activeElement = target;
+      tooltip.textContent = tooltipText;
+      tooltip.classList.add('visible');
+      // 先显示元素让浏览器计算尺寸，然后立即更新位置
+      updateTooltipPosition();
+    }
+
+    // Hide tooltip on mouse out
+    function onMouseOut(e) {
+      const target = e.target.closest('[data-tooltip]');
+      if (!target || target !== activeElement) return;
+
+      // Check if we really left the element (not just went to a child)
+      if (target.contains(e.relatedTarget)) return;
+
+      activeElement = null;
+      tooltip.classList.remove('visible');
+    }
+
+    document.addEventListener('mouseover', onMouseOver);
+    document.addEventListener('mouseout', onMouseOut);
+
+    cleanupTooltip = () => {
+      document.removeEventListener('mouseover', onMouseOver);
+      document.removeEventListener('mouseout', onMouseOut);
+
+      activeElement = null;
+      tooltip.classList.remove('visible');
+      tooltip.remove();
+    };
+  }
+
+  function disableTooltip() {
+    if (!cleanupTooltip) return;
+    cleanupTooltip();
+    cleanupTooltip = null;
+  }
+
+  function syncTooltipEnabled() {
+    if (hoverMedia.matches) {
+      enableTooltip();
+    } else {
+      disableTooltip();
+    }
+  }
+
+  syncTooltipEnabled();
+
+  // 兼容旧版 Safari：addListener/removeListener
+  if (hoverMedia.addEventListener) {
+    hoverMedia.addEventListener('change', syncTooltipEnabled);
+  } else if (hoverMedia.addListener) {
+    hoverMedia.addListener(syncTooltipEnabled);
+  }
+});
diff --git a/templates/README.md b/templates/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..30a3df6da25e54c409e2ba18cada260050b8bf21
--- /dev/null
+++ b/templates/README.md
@@ -0,0 +1,554 @@
+# MeNav 模板目录
+
+## 目录
+
+- [模板系统概述](#模板系统概述)
+- [目录结构](#目录结构)
+- [模板类型](#模板类型)
+  - [布局模板](#布局模板)
+  - [页面模板](#页面模板)
+  - [组件模板](#组件模板)
+  - [多层级嵌套模板组件](#多层级嵌套模板组件)
+- [模板数据流](#模板数据流)
+- [模板使用示例](#模板使用示例)
+- [最佳实践](#最佳实践)
+- [扩展指南](#扩展指南)
+
+## 模板系统概述
+
+MeNav 项目使用 Handlebars 作为模板引擎，实现了组件化架构，将页面内容与逻辑分离。模板系统的核心优势：
+
+- **组件复用** - 通过组件拆分实现代码复用
+- **结构清晰** - 布局、页面、组件分离管理
+- **扩展灵活** - 易于添加新页面和组件
+- **维护简便** - 修改单个组件不影响其他部分
+
+## 目录结构
+
+```
+templates/
+├── layouts/      # 布局模板 - 定义页面整体结构
+│   └── default.hbs   # 默认布局
+├── pages/        # 页面模板 - 对应不同页面内容
+│   ├── page.hbs      # 通用页面模板（默认/回退模板；普通页面常用）
+│   ├── content.hbs    # 内容页（Markdown 内容页：构建期渲染）
+│   ├── projects.hbs  # 项目页（repo 风格卡片）
+│   ├── articles.hbs  # 文章页（RSS 聚合/只读文章条目）
+│   ├── bookmarks.hbs # 书签页
+│   └── search-results.hbs # 搜索结果页（内置）
+├── components/   # 组件模板 - 可复用的界面元素
+│   ├── page-header.hbs  # 统一标题区（首页/非首页/书签更新时间/项目热力图）
+│   ├── navigation.hbs   # 导航组件
+│   ├── site-card.hbs    # 站点卡片组件
+│   ├── category.hbs     # 分类组件
+│   └── ...
+└── README.md     # 本文档
+```
+
+## 模板类型
+
+### 布局模板
+
+布局模板定义了整个页面的HTML结构，包含头部、导航栏、内容区和底部等基本框架。
+
+**位置**: `templates/layouts/`
+
+**主要布局**:
+
+- `default.hbs` - 默认布局，定义整个页面框架
+
+**示例**:
+
+```handlebars
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+    <meta charset="UTF-8">
+    <title>{{site.title}}</title>
+    <!-- 其他头部元素 -->
+</head>
+<body>
+    <div class="layout">
+        <!-- 导航部分 -->
+        <nav class="sidebar">
+            {{> navigation navigationData}}
+        </nav>
+
+        <!-- 内容区域 -->
+        <main class="content">
+            {{#each pages}}
+            <div class="page {{@key}}{{#if @first}} active{{/if}}" id="{{@key}}">
+                {{{this}}}
+            </div>
+            {{/each}}
+        </main>
+    </div>
+</body>
+</html>
+```
+
+### 页面模板
+
+页面模板对应网站的不同页面，每个页面模板通常包含多个组件组合。
+
+**位置**: `templates/pages/`
+
+**主要页面**:
+
+- `page.hbs` - 通用页面模板（默认/回退模板；普通页面常用）
+- `content.hbs` - 内容页（从本地 Markdown 文件构建期渲染为 HTML）
+- `bookmarks.hbs` - 书签页
+- `projects.hbs` - 项目页
+- `articles.hbs` - 文章页
+- `search-results.hbs` - 搜索结果
+- 其他自定义页面
+
+> 说明：MeNav 不再依赖 `home.hbs` 作为首页模板。
+> “首页/默认打开页”由 `site.yml -> navigation` 的**第一项**决定；首页可使用任意页面模板，具体取决于该页面配置（`pages/<homePageId>.yml` 的 `template` 字段与回退规则）。
+
+#### 内容页（template: content）
+
+内容页用于承载“关于 / 帮助 / 使用说明 / 更新日志 / 迁移指南”等纯文本内容。
+
+- 内容来源：页面配置中的 `content.file` 指向本地 `.md` 文件（例如 `content/about.md`）
+- 渲染时机：**构建期** Markdown -> HTML（不是运行时 fetch）
+- 安全约束：
+  - 禁止 raw HTML
+  - 禁止图片（`![]()` 不会被渲染）
+  - 链接会按 `site.yml -> security.allowedSchemes` 白名单策略处理，不安全链接会被降级为 `#`
+
+对应模板文件：`templates/pages/content.hbs`
+
+> 配置写法示例见：`config/README.md` 的“内容页（template: content）”。
+
+**示例** (`page.hbs`):
+
+```handlebars
+<div class="page-template page-template-{{pageId}}">
+    {{> page-header}}
+    {{#each categories}}
+        {{> category}}
+    {{/each}}
+</div>
+```
+
+### 组件模板
+
+组件是可复用的UI元素，用于在不同页面中重复使用。
+
+**位置**: `templates/components/`
+
+> 说明：生成器启动时会自动扫描 `templates/components/` 下的所有 `.hbs` 并注册为 Handlebars partial（partial 名称=文件名去掉 `.hbs`）。因此新增组件后无需手动“注册步骤”，可直接通过 `{{> component-name}}` 引用。
+
+**主要组件**:
+
+- `page-header.hbs` - 统一页面标题区（首页/非首页/书签更新时间/项目热力图）
+- `home-dashboard.hbs` - 首页仪表盘（时钟卡片、TODO 待办卡片）
+- `navigation.hbs` - 导航菜单
+- `site-card.hbs` - 站点卡片
+- `category.hbs` - 分类容器（支持多层级嵌套）
+- `group.hbs` - 分组容器（支持多层级嵌套）
+- `social-links.hbs` - 社交链接
+
+**示例** (`site-card.hbs`，精简展示关键结构):
+
+```handlebars
+{{#if url}}
+<a href="{{url}}"
+   class="site-card{{#if style}} site-card-{{style}}{{/if}}"
+   {{#if external}}target="_blank" rel="noopener"{{/if}}
+   data-type="{{#if type}}{{type}}{{else}}site{{/if}}"
+   data-name="{{name}}"
+   data-url="{{url}}">
+    <div class="site-card-icon">...</div>
+    <div class="site-card-content">
+        <h3>{{#if name}}{{name}}{{else}}未命名站点{{/if}}</h3>
+        <p>{{description}}</p>
+    </div>
+</a>
+{{/if}}
+```
+
+说明：
+
+- `type=article`：用于 articles Phase 2 的只读文章条目卡片（仍保留 `data-*` 结构；扩展解析应以 `data-type="article"` 区分类型）
+- `style=repo`：用于 projects 的代码仓库风卡片（展示 language/stars/forks 等只读元信息）
+
+### 多层级嵌套模板组件
+
+#### category.hbs - 分类容器组件
+
+`category.hbs` 是多层级嵌套的核心组件，可渲染 `categories -> subcategories -> groups -> sites` 的结构；更深一层的 `subgroups` 由 `group.hbs` 负责渲染。
+
+**功能特性**:
+
+- 支持 2~4 层嵌套（`categories -> subcategories -> groups -> subgroups -> sites`，其中 `subgroups` 可选）
+- 自动计算标题层级（h2/h3/h4/h5）
+- 根据层级自动应用对应的 CSS 类（如 `category-level-2`、`group-level-4`）
+- 分类容器支持三种内容：子分类、分组、站点（分组内可继续包含子分组）
+
+**递归渲染原理**:
+通过在模板内部调用自身实现递归渲染：
+
+```handlebars
+{{#each subcategories}}
+    {{> category level=2}}
+{{/each}}
+```
+
+**level参数的作用**:
+
+- 用于跟踪当前嵌套层级
+- 控制标题标签的层级（h{{add level 1}}）
+- 应用对应的CSS类（category-level-{{level}}）
+- 传递给子组件以保持层级一致性
+
+**使用示例**:
+
+```handlebars
+<!-- 顶级分类 -->
+{{> category category}}
+
+<!-- 指定层级的分类 -->
+{{> category category level=2}}
+```
+
+#### group.hbs - 分组容器组件
+
+`group.hbs` 是用于在分类内组织站点的组件，同样支持层级参数。
+
+**功能特性**:
+
+- 支持在分类内创建站点分组
+- 支持子分组（`subgroups`，用于第 4 层结构）
+- 自动应用层级样式
+- 支持展开/折叠功能
+- 与category.hbs保持一致的层级系统
+
+**使用示例**:
+
+```handlebars
+<!-- 在分类模板中使用 -->
+{{#each groups}}
+    {{> group}}
+{{/each}}
+
+<!-- 指定层级的分组 -->
+{{> group group level=3}}
+```
+
+#### 多层级嵌套结构示例
+
+典型的（最多 4 层）结构：分类 → 子分类 → 分组 → 子分组 → 站点（`subgroups` 可选）
+
+```yaml
+# 配置示例
+categories:
+  - name: '技术'
+    icon: 'fas fa-code'
+    subcategories:
+      - name: '前端开发'
+        icon: 'fas fa-laptop-code'
+        groups:
+          - name: '框架'
+            icon: 'fas fa-cubes'
+            subgroups:
+              - name: 'React生态'
+                icon: 'fab fa-react'
+                sites:
+                  - name: 'React'
+                    url: 'https://reactjs.org'
+                    icon: 'fab fa-react'
+                  - name: 'Next.js'
+                    url: 'https://nextjs.org'
+                    icon: 'fas fa-triangle'
+```
+
+对应的模板渲染：
+
+```handlebars
+<!-- category.hbs 会递归渲染 -->
+<section class="category category-level-1" data-level="1">
+  <div class="category-header">
+    <h2><i class="fas fa-code"></i> 技术</h2>
+  </div>
+  <div class="category-content">
+    <div class="subcategories-container">
+      <!-- 递归调用 category.hbs，level=2 -->
+      <section class="category category-level-2" data-level="2">
+        <div class="category-header">
+          <h3><i class="fas fa-laptop-code"></i> 前端开发</h3>
+        </div>
+	        <div class="category-content">
+	          <div class="groups-container">
+	            <!-- 使用 group.hbs，默认 level=3 -->
+	            <div class="group group-level-3" data-level="3">
+	              <div class="group-header">
+	                <h4><i class="fas fa-cubes"></i> 框架</h4>
+	              </div>
+	              <div class="group-content">
+	                <div class="subgroups-container">
+	                  <!-- group.hbs 渲染 subgroups，level=4 -->
+	                  <div class="group group-level-4" data-level="4">
+	                    <div class="group-header">
+	                      <h5><i class="fab fa-react"></i> React生态</h5>
+	                    </div>
+	                    <div class="group-content">
+	                      <div class="sites-grid">
+	                        <!-- 渲染站点卡片 -->
+	                        {{> site-card site}}
+	                      </div>
+	                    </div>
+	                  </div>
+	                </div>
+	              </div>
+	            </div>
+	          </div>
+	        </div>
+      </section>
+    </div>
+  </div>
+</section>
+```
+
+#### 层级系统说明
+
+- **层级1 (level=1)**: 顶级分类，使用h2标题
+- **层级2 (level=2)**: 子分类，使用h3标题
+- **层级3 (level=3)**: 分组，使用h4标题
+- **层级4 (level=4)**: 子分组，使用h5标题（用于 4 层结构）
+
+每个层级都有对应的CSS类：
+
+- `category-level-1`, `category-level-2`
+- `group-level-3`, `group-level-4`
+
+这种设计确保了：
+
+1. 语义化的HTML结构
+2. 一致的视觉层级
+3. 可预测的嵌套深度（当前导入脚本与样式保证到 level=4）
+4. 灵活的样式定制
+
+### 站点图标渲染（favicon/manual）
+
+当启用 `icons.mode: favicon`（默认）时，站点卡片会优先显示站点 favicon；当 URL 非 http/https、加载失败或网络受限，则自动回退到 Font Awesome 图标。相关助手：`ifHttpUrl`（条件）与 `encodeURIComponent`（工具）。
+
+站点级覆盖（可选，写在每个 `sites[]` 节点上）：
+
+- `faviconUrl`：为单站点指定图标链接（优先级最高，失败回退到手动图标；本地路径建议以 `assets/` 开头，构建会复制到 `dist/` 同路径）
+- `forceIconMode: favicon | manual`：强制该站点使用指定模式（不设置则跟随全局 `icons.mode`）
+- 优先级：`faviconUrl` > `forceIconMode` > 全局 `icons.mode`
+
+> 注意：用于根据站点 URL 生成 faviconV2 地址的模板 helper 已更名为 `faviconV2Url`，从而避免与站点字段 `faviconUrl` 同名冲突；自定义模板如需生成 faviconV2 地址，请使用 `{{faviconV2Url url}}`。如需强制读取站点字段 `faviconUrl`，也可使用 `{{lookup . "faviconUrl"}}`（推荐在复杂上下文中显式读取字段）。
+
+示例（与内置组件实现保持一致）：
+
+```handlebars
+{{#if url}}
+<a href="{{url}}" class="site-card{{#if style}} site-card-{{style}}{{/if}}"
+   {{#if external}}target="_blank" rel="noopener"{{/if}}
+   data-type="site"
+   data-name="{{name}}"
+   data-url="{{url}}"
+   data-icon="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}}"
+   data-description="{{#if description}}{{description}}{{else}}{{extractDomain url}}{{/if}}">
+    {{#ifEquals @root.icons.mode "favicon"}}
+      {{#ifHttpUrl url}}
+        <div class="icon-container">
+          <i class="fas fa-circle-notch fa-spin icon-placeholder" aria-hidden="true"></i>
+          <img
+            class="favicon-icon"
+            src="https://t3.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url={{encodeURIComponent url}}&size=32&drop_404_icon=true"
+            alt="{{name}} favicon"
+            loading="lazy"
+            onload="this.classList.add('loaded'); this.previousElementSibling.classList.add('hidden');"
+            onerror="this.classList.add('error'); this.previousElementSibling.classList.add('hidden'); this.nextElementSibling.classList.add('visible');"
+          />
+          <i class="fas fa-link icon-fallback" aria-hidden="true"></i>
+        </div>
+      {{else}}
+        <i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}}"></i>
+      {{/ifHttpUrl}}
+    {{else}}
+      <i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}}"></i>
+    {{/ifEquals}}
+    <h3>{{#if name}}{{name}}{{else}}未命名站点{{/if}}</h3>
+    <p>{{#if description}}{{description}}{{else}}{{extractDomain url}}{{/if}}</p>
+</a>
+{{/if}}
+```
+
+提示：关于 `icons.mode` 的配置与隐私说明，请参见：
+
+- `config/README.md` 的 `site.yml 常用字段`：[`../config/README.md#siteyml-常用字段`](../config/README.md#siteyml-%E5%B8%B8%E7%94%A8%E5%AD%97%E6%AE%B5)
+- 根目录 `README.md` 的“近期更新”：[`../README.md#近期更新`](../README.md#%E8%BF%91%E6%9C%9F%E6%9B%B4%E6%96%B0)
+
+## 模板数据流
+
+MeNav 模板系统的数据流如下：
+
+1. `generator.js` 加载配置文件并处理数据
+2. 数据通过 Handlebars 上下文传递给模板
+3. 布局模板 (`layouts/default.hbs`) 作为外层容器
+4. 页面模板 (`pages/*.hbs`) 填充布局中的内容区域
+5. 组件模板 (`components/*.hbs`) 在页面中通过 `{{> component-name}}` 引用
+
+主要数据对象:
+
+- `site` - 网站配置信息
+- `navigationData` - 导航菜单数据
+- `categories` - 分类和站点数据
+- `profile` - 个人资料数据
+- `social` - 社交链接数据
+
+常见派生字段（由生成器注入，供模板差异化使用）：
+
+- `homePageId`：首页页面 ID（始终等于 `navigation` 第一项的 `id`）
+- `pageId`：当前页面 ID（用于 `.page-template-{{pageId}}` 等）
+- `pageMeta.updatedAt/updatedAtSource`：仅 bookmarks 模板页用于“update: YYYY-MM-DD | from: ...”展示
+- `projectsMeta.heatmap`：仅 projects 模板页用于右侧 GitHub 热力图展示（需要配置 `site.github.username`）
+- `articlesItems/articlesCategories`：仅 articles 模板页（Phase 2）用于渲染只读文章条目（RSS 缓存存在时）
+
+> 提示：页面模板是“页面内容片段”，不要包含 `<!DOCTYPE html>` 等整页骨架；整页骨架由 `layouts/default.hbs` 负责。
+
+## 模板使用示例
+
+### 布局模板使用
+
+布局模板通常只有一个 `default.hbs`，会自动被系统使用。
+
+### 页面模板使用
+
+页面模板对应导航中的各个页面，有两种使用方式：
+
+1. **自动匹配**：系统会尝试使用与页面ID同名的模板（例如：页面ID为 `projects` 时会使用 `projects.hbs`）
+2. **显式指定**：在页面配置中使用 `template` 字段指定要使用的模板
+
+#### 模板指定示例
+
+在 `config/user/pages/项目.yml` 中：
+
+```yaml
+title: '我的项目'
+subtitle: '这里展示我的所有项目'
+template: 'projects' # 使用 projects.hbs 模板而不是使用页面ID命名的模板
+categories:
+  - name: '网站项目'
+    icon: 'fas fa-globe'
+    sites:
+      - name: '个人博客'
+        # ... 其他字段
+```
+
+**注意**：当系统找不到指定的模板或与页面ID匹配的模板时，会自动使用通用模板 `page.hbs`。
+
+### 引用组件
+
+在页面或其他组件中引用组件：
+
+```handlebars
+{{> navigation navigationData}}
+{{> site-card}}
+```
+
+### 条件渲染
+
+根据条件显示内容：
+
+```handlebars
+{{#if profile.title}}
+  <h2>{{profile.title}}</h2>
+{{else}}
+  <h2>欢迎使用</h2>
+{{/if}}
+```
+
+### 循环渲染
+
+循环渲染数据列表：
+
+```handlebars
+{{#each categories}}
+    <section class="category" id="{{name}}">
+        <h2><i class="{{icon}}"></i> {{name}}</h2>
+        <div class="sites-grid">
+            {{#each sites}}
+                {{> site-card}}
+            {{/each}}
+        </div>
+    </section>
+{{/each}}
+```
+
+## 最佳实践
+
+1. **组件粒度** - 保持组件的适当粒度，既不过大也不过小
+   - 过大：难以复用和维护
+   - 过小：增加复杂性和引用管理难度
+
+2. **数据传递** - 使用合适的方式传递数据
+   - 直接上下文：`{{> component}}` (继承父上下文)
+   - 指定数据：`{{> component customData}}` (传递特定数据)
+
+3. **命名规范**
+   - 使用连字符命名：`site-card.hbs`、`search-results.hbs`
+   - 使用描述性名称，体现组件用途
+
+4. **注释**
+   - 对复杂逻辑添加注释说明
+   - 标注可选参数和默认行为
+
+## 扩展指南
+
+### 添加新页面
+
+1. 在 `templates/pages/` 创建新的 `.hbs` 文件
+2. 在 `config/user/site.yml` 的 `navigation` 部分添加页面配置（配置采用“完全替换”策略，推荐使用 user 配置）
+3. 页面内容可引用现有组件或创建新组件
+
+示例：
+
+```handlebars
+<!-- templates/pages/about.hbs -->
+<div class='about-page'>
+  <h2>关于我</h2>
+  <p>{{about.description}}</p>
+
+  {{#if about.skills}}
+    <div class='skills'>
+      <h3>技能</h3>
+      <ul>
+        {{#each about.skills}}
+          <li>{{this}}</li>
+        {{/each}}
+      </ul>
+    </div>
+  {{/if}}
+</div>
+```
+
+### 添加新组件
+
+1. 在 `templates/components/` 创建新的 `.hbs` 文件
+2. 在页面或其他组件中引用
+
+示例：
+
+```handlebars
+<!-- templates/components/skill-card.hbs -->
+<div class='skill-card'>
+  <h4>{{name}}</h4>
+  <div class='skill-level' data-level='{{level}}'>
+    <div class='skill-bar' style='width: {{level}}%'></div>
+  </div>
+</div>
+```
+
+使用新组件：
+
+```handlebars
+{{#each skills}}
+    {{> skill-card}}
+{{/each}}
+```
diff --git a/templates/components/category.hbs b/templates/components/category.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..a7aa9d84b0e4d385039a3b2108bfc41af51bf9f0
--- /dev/null
+++ b/templates/components/category.hbs
@@ -0,0 +1,75 @@
+<section class="category {{#if level}}category-level-{{level}}{{else}}category-level-1{{/if}}"
+         id="{{#if slug}}{{slug}}{{else}}{{name}}{{/if}}"
+         data-type="category"
+         data-id="{{#if slug}}{{slug}}{{else}}{{name}}{{/if}}"
+         data-name="{{name}}"
+         data-icon="{{icon}}"
+         data-level="{{#if level}}{{level}}{{else}}1{{/if}}"
+         data-container="categories">
+    
+    <div class="category-header"{{#if subcategories}} data-toggle="category"{{else}}{{#if groups}} data-toggle="category"{{else}}{{#if sites}} data-toggle="category"{{/if}}{{/if}}{{/if}}>
+        <h{{#if level}}{{add level 1}}{{else}}2{{/if}} data-editable="category-name">
+            <i class="{{icon}}"></i>
+            {{name}}
+            {{#if subcategories}}
+                <span class="toggle-icon">
+                    <i class="fas fa-chevron-down"></i>
+                </span>
+            {{else}}
+                {{#if groups}}
+                    <span class="toggle-icon">
+                        <i class="fas fa-chevron-down"></i>
+                    </span>
+                {{else}}
+                    {{#if sites}}
+                        <span class="toggle-icon">
+                            <i class="fas fa-chevron-down"></i>
+                        </span>
+                    {{/if}}
+                {{/if}}
+            {{/if}}
+        </h{{#if level}}{{add level 1}}{{else}}2{{/if}}>
+    </div>
+    
+    <div class="category-content">
+        {{#if subcategories}}
+            <div class="subcategories-container" data-container="subcategories">
+                {{#each subcategories}}
+                    {{#if ../level}}
+                        {{> category level=(add ../level 1)}}
+                    {{else}}
+                        {{> category level=2}}
+                    {{/if}}
+                {{/each}}
+            </div>
+        {{/if}}
+        
+        {{#if groups}}
+            <div class="groups-container" data-container="groups">
+                {{#each groups}}
+                    {{> group}}
+                {{/each}}
+            </div>
+        {{/if}}
+        
+        {{#if sites}}
+            <div class="sites-grid" data-container="sites">
+                {{#if sites.length}}
+                    {{#each sites}}
+                        {{> site-card style=@root.siteCardStyle}}
+                    {{/each}}
+                {{else}}
+                    <p class="empty-sites">暂无网站</p>
+                {{/if}}
+            </div>
+        {{/if}}
+        
+        {{#unless subcategories}}
+        {{#unless groups}}
+        {{#unless sites}}
+            <p class="empty-content">暂无内容</p>
+        {{/unless}}
+        {{/unless}}
+        {{/unless}}
+    </div>
+</section>
diff --git a/templates/components/github-heatmap.hbs b/templates/components/github-heatmap.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..bfe1cfb095f5600c9c7ca8ceb33f777c46d0ffba
--- /dev/null
+++ b/templates/components/github-heatmap.hbs
@@ -0,0 +1,40 @@
+<section class="category category-level-1 gh-heatmap-category" data-type="heatmap">
+    <div class="category-header">
+        <div class="gh-heatmap-header">
+            <h2>
+                <i class="fab fa-github"></i>
+                <span class="gh-text-desktop">GitHub Contributions</span>
+                <span class="gh-text-mobile">Contributions</span>
+                <span class="gh-heatmap-username">@{{username}}</span>
+            </h2>
+
+            <div class="gh-legend" aria-hidden="true">
+                <span>
+                    <span class="gh-text-desktop">Less</span>
+                    <span class="gh-text-mobile">L</span>
+                </span>
+                <div class="gh-legend-item level-0"></div>
+                <div class="gh-legend-item level-1"></div>
+                <div class="gh-legend-item level-2"></div>
+                <div class="gh-legend-item level-3"></div>
+                <div class="gh-legend-item level-4"></div>
+                <span>
+                    <span class="gh-text-desktop">More</span>
+                    <span class="gh-text-mobile">M</span>
+                </span>
+            </div>
+        </div>
+    </div>
+
+    <div class="category-content">
+        <div class="gh-heatmap-wrapper">
+            <div class="calendar gh-calendar" data-github-username="{{username}}" id="github-calendar-{{username}}">
+                {{#if html}}
+                    {{{html}}}
+                {{else}}
+                    Loading data...
+                {{/if}}
+            </div>
+        </div>
+    </div>
+</section>
diff --git a/templates/components/group.hbs b/templates/components/group.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..aafe4b504cb5e79d49c791eff9eb5247c05fe09a
--- /dev/null
+++ b/templates/components/group.hbs
@@ -0,0 +1,46 @@
+<div class="group {{#if level}}group-level-{{level}}{{else}}group-level-3{{/if}}" 
+     data-type="group" 
+     data-name="{{name}}" 
+     data-icon="{{icon}}"
+     data-level="{{#if level}}{{level}}{{else}}3{{/if}}">
+    
+    <div class="group-header"{{#ifCond subgroups '||' sites}} data-toggle="group"{{/ifCond}}>
+        <h{{#if level}}{{add level 1}}{{else}}4{{/if}} data-editable="group-name">
+            <i class="{{icon}}"></i> 
+            {{name}}
+            {{#ifCond subgroups '||' sites}}
+                <span class="toggle-icon">
+                    <i class="fas fa-chevron-down"></i>
+                </span>
+            {{/ifCond}}
+        </h{{#if level}}{{add level 1}}{{else}}4{{/if}}>
+    </div>
+    
+    <div class="group-content">
+        {{#if subgroups}}
+            <div class="subgroups-container" data-container="subgroups">
+                {{#each subgroups}}
+                    {{> group level=4}}
+                {{/each}}
+            </div>
+        {{/if}}
+
+        {{#if sites}}
+            <div class="sites-grid" data-container="sites">
+                {{#if sites.length}}
+                    {{#each sites}}
+                        {{> site-card style=@root.siteCardStyle}}
+                    {{/each}}
+                {{else}}
+                    <p class="empty-sites">暂无网站</p>
+                {{/if}}
+            </div>
+        {{/if}}
+
+        {{#unless subgroups}}
+        {{#unless sites}}
+            <p class="empty-content">暂无网站</p>
+        {{/unless}}
+        {{/unless}}
+    </div>
+</div>
diff --git a/templates/components/home-dashboard.hbs b/templates/components/home-dashboard.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..e896858fbfc7ea8d580b2d85ae8cc60a378778a4
--- /dev/null
+++ b/templates/components/home-dashboard.hbs
@@ -0,0 +1,211 @@
+{{!-- home-dashboard.hbs - 首页专用 Dashboard 布局 (Refined Layout) --}}
+<div class="dashboard-grid">
+    {{!-- 左侧：欢迎语 + 时钟 --}}
+    <div class="dashboard-intro">
+        <div class="dashboard-welcome">
+            <h1 class="welcome-title">{{title}}</h1>
+            <p class="welcome-subtitle">{{subtitle}}</p>
+        </div>
+
+        <div class="dashboard-clock-card">
+            <div class="clock-header">
+                <div class="clock-meta">
+                    <div class="clock-greeting" id="dashboard-greeting">Hello</div>
+                    <div class="clock-date" id="dashboard-date">Mon, Jan 01</div>
+                </div>
+                <div class="clock-week" id="dashboard-week">Week 1</div>
+            </div>
+
+            <div class="clock-main">
+                <div class="clock-time" id="dashboard-clock">00:00</div>
+            </div>
+        </div>
+    </div>
+
+    {{!-- 右侧：Todo 面板 --}}
+    <div class="dashboard-stats">
+        <div class="dashboard-panel">
+            <div class="panel-sidebar">
+                <div class="panel-static-icon">
+                    <span class="fas fa-bars"></span>
+                </div>
+                {{!-- 加号移至底部 --}}
+                <button class="panel-icon-btn add-btn" title="Add Todo" onclick="window.menavTodoApp.toggleInput()">
+                    <span class="fas fa-plus"></span>
+                </button>
+            </div>
+
+            <div class="panel-content-wrapper">
+                <div class="panel-content custom-scrollbar" id="todo-list">
+                    {{!-- Todo items will be rendered here via JS --}}
+                </div>
+
+                {{!-- 输入框默认隐藏 --}}
+                <div class="todo-input-container" id="todo-input-container"
+                    style="display: none; padding: var(--spacing-md);">
+                    <input type="text" class="todo-input" id="todo-input-field" placeholder="New task..."
+                        onkeypress="window.menavTodoApp.handleInputKey(event)"
+                        onblur="window.menavTodoApp.handleBlur()">
+                    <button class="todo-add-btn-small" onmousedown="window.menavTodoApp.preventBlur(event)"
+                        onclick="window.menavTodoApp.addFromInput()">
+                        <span class="fas fa-arrow-right"></span>
+                    </button>
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+
+<script>
+    (function () {
+        // --- Clock Logic ---
+        function getWeekNumber(d) {
+            d = new Date(Date.UTC(d.getFullYear(), d.getMonth(), d.getDate()));
+            d.setUTCDate(d.getUTCDate() + 4 - (d.getUTCDay() || 7));
+            var yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+            var weekNo = Math.ceil((((d - yearStart) / 86400000) + 1) / 7);
+            return weekNo;
+        }
+
+        function getGreeting(hour) {
+            if (hour < 5) return "Good Night";
+            if (hour < 12) return "Good Morning";
+            if (hour < 18) return "Good Afternoon";
+            return "Good Evening";
+        }
+
+        function updateDashboardClock() {
+            const clockEl = document.getElementById('dashboard-clock');
+            const dateEl = document.getElementById('dashboard-date');
+            const greetingEl = document.getElementById('dashboard-greeting');
+            const weekEl = document.getElementById('dashboard-week');
+
+            if (!clockEl || !dateEl) return;
+
+            const now = new Date();
+            clockEl.textContent = now.toLocaleTimeString('en-US', { hour12: false, hour: '2-digit', minute: '2-digit' });
+            dateEl.textContent = now.toLocaleDateString('en-US', { weekday: 'short', month: 'short', day: 'numeric' });
+            if (greetingEl) greetingEl.textContent = getGreeting(now.getHours());
+            if (weekEl) weekEl.textContent = `Week ${getWeekNumber(now)}`;
+        }
+
+        setInterval(updateDashboardClock, 1000);
+        updateDashboardClock();
+
+        // --- Todo App Logic ---
+        const TODO_STORAGE_KEY = 'menav_todos_v1';
+
+        window.menavTodoApp = {
+            todos: [],
+            isIgnoreBlur: false,
+
+            init() {
+                this.load();
+                this.render();
+            },
+
+            load() {
+                try {
+                    const raw = localStorage.getItem(TODO_STORAGE_KEY);
+                    this.todos = raw ? JSON.parse(raw) : [
+                        { text: 'Drink Water', done: false },
+                        { text: 'Explore MeNav', done: true }
+                    ];
+                } catch (e) { this.todos = []; }
+            },
+
+            save() {
+                try { localStorage.setItem(TODO_STORAGE_KEY, JSON.stringify(this.todos)); } catch (e) { }
+            },
+
+            toggleInput() {
+                const container = document.getElementById('todo-input-container');
+                const field = document.getElementById('todo-input-field');
+                if (container.style.display === 'none') {
+                    container.style.display = 'flex';
+                    field.focus();
+                } else {
+                    container.style.display = 'none';
+                }
+            },
+
+            handleBlur() {
+                // Delay to allow button click to process first
+                setTimeout(() => {
+                    if (this.isIgnoreBlur) {
+                        this.isIgnoreBlur = false;
+                        return;
+                    }
+                    const container = document.getElementById('todo-input-container');
+                    if (container) container.style.display = 'none';
+                }, 200);
+            },
+
+            preventBlur(e) {
+                // Prevent input blur when clicking the add button
+                this.isIgnoreBlur = true;
+            },
+
+            addFromInput() {
+                const input = document.getElementById('todo-input-field');
+                if (input && input.value.trim()) {
+                    this.todos.push({ text: input.value.trim(), done: false });
+                    input.value = '';
+                    this.save();
+                    this.render();
+
+                    // 保持底部可见
+                    const list = document.getElementById('todo-list');
+                    list.scrollTop = list.scrollHeight;
+
+                    // Keep input open and focused
+                    input.focus();
+                }
+            },
+
+            handleInputKey(e) { if (e.key === 'Enter') this.addFromInput(); },
+
+            toggle(index) {
+                this.todos[index].done = !this.todos[index].done;
+                this.save(); this.render();
+            },
+
+            remove(index, e) {
+                if (e) e.stopPropagation();
+                this.todos.splice(index, 1);
+                this.save(); this.render();
+            },
+
+            render() {
+                const container = document.getElementById('todo-list');
+                if (!container) return;
+
+                if (this.todos.length === 0) {
+                    container.innerHTML = '<div class="empty-todo-hint">No tasks.</div>';
+                    return;
+                }
+
+                container.innerHTML = this.todos.map((todo, index) => `
+                    <div class="todo-item ${todo.done ? 'done' : ''}" onclick="window.menavTodoApp.toggle(${index})">
+                        <div class="todo-checkbox ${todo.done ? 'checked' : ''}">
+                            ${todo.done ? '<span class="fas fa-check"></span>' : ''}
+                        </div>
+                        <div class="todo-text" title="${this.escapeHtml(todo.text)}">${this.escapeHtml(todo.text)}</div>
+                        <button class="todo-delete-btn" onclick="window.menavTodoApp.remove(${index}, event)" title="Delete">
+                            <span class="fas fa-trash-alt"></span>
+                        </button>
+                    </div>
+                `).join('');
+            },
+
+            escapeHtml(text) {
+                const div = document.createElement('div');
+                div.textContent = text;
+                return div.innerHTML;
+            }
+        };
+
+        window.menavTodoApp.init();
+
+    })();
+</script>
\ No newline at end of file
diff --git a/templates/components/navigation.hbs b/templates/components/navigation.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..f1a253adbdbf6483a9513ef9ecd8af3405b1f83a
--- /dev/null
+++ b/templates/components/navigation.hbs
@@ -0,0 +1,23 @@
+<div data-container="nav-items">
+{{#each this}}
+<div class="nav-item-wrapper">
+    <a href="?page={{id}}" class="nav-item{{#if isActive}} active{{/if}}{{#if active}} active{{/if}}" data-page="{{id}}" data-type="nav-item" data-id="{{id}}" data-name="{{name}}" data-icon="{{icon}}">
+        <div class="icon-container">
+            <i class="{{icon}}"></i>
+        </div>
+        <span class="nav-text" data-editable="nav-item-name">{{name}}</span>
+    </a>
+    {{#if submenu}}
+    <div class="submenu">
+        <div class="submenu-header">{{name}}</div>
+        {{#each submenu}}
+        <a href="?page={{../id}}#{{#if slug}}{{slug}}{{else}}{{name}}{{/if}}" class="submenu-item" data-page="{{../id}}" data-category="{{name}}" data-category-id="{{#if slug}}{{slug}}{{else}}{{name}}{{/if}}">
+            <i class="{{icon}}"></i>
+            <span>{{name}}</span>
+        </a>
+        {{/each}}
+    </div>
+    {{/if}}
+</div>
+{{/each}} 
+</div> 
diff --git a/templates/components/page-header.hbs b/templates/components/page-header.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..4ee9940bb0a5f5da9ab403cc99b46c9fd5145d75
--- /dev/null
+++ b/templates/components/page-header.hbs
@@ -0,0 +1,23 @@
+{{!-- page-header.hbs - 统一页面标题区（可选显示书签页内容更新时间） --}}
+<div class="welcome-section">
+    <div class="welcome-section-main">
+        {{#ifEquals pageId @root.homePageId}}
+            <h2 data-editable="profile-title">{{title}}</h2>
+            <h3 data-editable="profile-subtitle">{{subtitle}}</h3>
+        {{else}}
+            <div class="welcome-title-row">
+                <h2 data-editable="page-title">{{title}}</h2>
+                {{#if pageMeta}}
+                {{#if pageMeta.updatedAt}}
+                    <span class="page-updated-inline" title="{{pageMeta.updatedAt}}">
+                        update: {{formatDate pageMeta.updatedAt "YYYY-MM-DD"}} | from: {{pageMeta.updatedAtSource}}
+                    </span>
+                {{/if}}
+                {{/if}}
+            </div>
+            <p class="subtitle" data-editable="page-subtitle">{{subtitle}}</p>
+        {{/ifEquals}}
+    </div>
+
+
+</div>
diff --git a/templates/components/site-card.hbs b/templates/components/site-card.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..0a6989bee476b1cbb9cb14ce5266e1115e2039b0
--- /dev/null
+++ b/templates/components/site-card.hbs
@@ -0,0 +1,173 @@
+{{#if url}}
+<a href="{{safeUrl url}}" class="site-card{{#if style}} site-card-{{style}}{{/if}}" {{#if external}}target="_blank"
+		rel="noopener" {{/if}} data-type="{{#if type}}{{type}}{{else}}site{{/if}}" data-name="{{name}}" data-url="{{url}}"
+		data-icon="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}}" {{#if (lookup . "faviconUrl")}}data-favicon-url="{{lookup . "faviconUrl"}}"
+		{{/if}} {{#if forceIconMode}}data-force-icon-mode="{{forceIconMode}}" {{/if}}
+		data-description="{{#if description}}{{description}}{{else}}{{extractDomain url}}{{/if}}"
+	data-tooltip="{{#if name}}{{name}}{{else}}未命名站点{{/if}}{{#if description}} - {{description}}{{else}} - {{extractDomain url}}{{/if}}"
+	{{#if publishedAt}}data-published-at="{{publishedAt}}" {{/if}} {{#if source}}data-source="{{source}}" {{/if}}>
+	{{!-- articles：首行图标+标题；下方“时间/来源 + 简介”全宽对齐，不被图标列缩进 --}}
+	{{#ifEquals type "article"}}
+	<div class="article-card-header">
+		<div class="site-card-icon" aria-hidden="true">
+			{{!-- 站点图标优先级：faviconUrl > forceIconMode > 全局 icons.mode --}}
+			{{#if (lookup . "faviconUrl")}}
+			<div class="icon-container">
+				<i class="fas fa-circle-notch fa-spin icon-placeholder" aria-hidden="true"></i>
+				<img class="favicon-icon" src="{{lookup . "faviconUrl"}}" alt="{{name}} favicon" loading="lazy"
+					onload="this.classList.add('loaded'); this.previousElementSibling.classList.add('hidden');"
+					onerror="this.classList.add('error'); this.previousElementSibling.classList.add('hidden'); this.nextElementSibling.classList.add('visible');" />
+				<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}} icon-fallback" aria-hidden="true"></i>
+			</div>
+			{{else}}
+			{{#ifEquals forceIconMode "manual"}}
+			<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}} site-icon" aria-hidden="true"></i>
+			{{else}}
+			{{#ifEquals forceIconMode "favicon"}}
+			{{#ifHttpUrl url}}
+			<div class="icon-container">
+				<i class="fas fa-circle-notch fa-spin icon-placeholder" aria-hidden="true"></i>
+				<img class="favicon-icon" src="{{faviconV2Url url}}" alt="{{name}} favicon" loading="lazy"
+					onload="this.classList.add('loaded'); this.previousElementSibling.classList.add('hidden');"
+					onerror="if (!this.dataset.faviconFallbackTried) { this.dataset.faviconFallbackTried = '1'; this.src = '{{faviconFallbackUrl url}}'; return; } this.classList.add('error'); this.previousElementSibling.classList.add('hidden'); this.nextElementSibling.classList.add('visible');" />
+				<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}} icon-fallback" aria-hidden="true"></i>
+			</div>
+			{{else}}
+			<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}} site-icon" aria-hidden="true"></i>
+			{{/ifHttpUrl}}
+			{{else}}
+			{{#ifEquals @root.icons.mode "favicon"}}
+			{{#ifHttpUrl url}}
+			<div class="icon-container">
+				<i class="fas fa-circle-notch fa-spin icon-placeholder" aria-hidden="true"></i>
+				<img class="favicon-icon" src="{{faviconV2Url url}}" alt="{{name}} favicon" loading="lazy"
+					onload="this.classList.add('loaded'); this.previousElementSibling.classList.add('hidden');"
+					onerror="if (!this.dataset.faviconFallbackTried) { this.dataset.faviconFallbackTried = '1'; this.src = '{{faviconFallbackUrl url}}'; return; } this.classList.add('error'); this.previousElementSibling.classList.add('hidden'); this.nextElementSibling.classList.add('visible');" />
+				<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}} icon-fallback" aria-hidden="true"></i>
+			</div>
+			{{else}}
+			<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}} site-icon" aria-hidden="true"></i>
+			{{/ifHttpUrl}}
+			{{else}}
+			<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}} site-icon" aria-hidden="true"></i>
+			{{/ifEquals}}
+			{{/ifEquals}}
+			{{/ifEquals}}
+			{{/if}}
+		</div>
+		<div class="article-card-title">
+			<h3>{{#if name}}{{name}}{{else}}未命名站点{{/if}}</h3>
+		</div>
+	</div>
+
+	<div class="article-card-body">
+		{{#ifCond publishedAt '||' source}}
+		<div class="site-card-meta">
+			{{#if publishedAt}}
+			<span class="site-card-meta-date">{{formatDate publishedAt "YYYY-MM-DD"}}</span>
+			{{/if}}
+			{{#ifCond publishedAt '&&' source}}
+			<span class="site-card-meta-sep">·</span>
+			{{/ifCond}}
+			{{#if source}}
+			<span class="site-card-meta-source">{{source}}</span>
+			{{/if}}
+		</div>
+		{{/ifCond}}
+		<p>{{#if
+			description}}{{description}}{{else}}{{extractDomain url}}{{/if}}</p>
+	</div>
+	{{else}}
+	{{!-- projects：代码仓库风格卡片（保留 data-* 结构，便于扩展识别与写回） --}}
+	{{#ifEquals style "repo"}}
+	<div class="repo-header">
+		<i class="{{#if icon}}{{icon}}{{else}}fas fa-code{{/if}} repo-icon" aria-hidden="true"></i>
+		<div class="repo-title">{{#if name}}{{name}}{{else}}未命名项目{{/if}}</div>
+	</div>
+
+	<div class="repo-desc">{{#if
+		description}}{{description}}{{else}}{{extractDomain url}}{{/if}}</div>
+
+	{{#ifCond language '||' stars}}
+	<div class="repo-stats">
+		{{#if language}}
+		<div class="stat-item">
+			<span class="lang-dot"
+				style="background-color: {{#if languageColor}}{{languageColor}}{{else}}#909296{{/if}};"></span>
+			{{language}}
+		</div>
+		{{/if}}
+		{{#if stars}}
+		<div class="stat-item">
+			<i class="far fa-star" aria-hidden="true"></i> {{stars}}
+		</div>
+		{{/if}}
+		{{#if forks}}
+		<div class="stat-item">
+			<i class="fas fa-code-branch" aria-hidden="true"></i> {{forks}}
+		</div>
+		{{/if}}
+		{{#if issues}}
+		<div class="stat-item">
+			<i class="fas fa-exclamation-circle" aria-hidden="true"></i> {{issues}}
+		</div>
+		{{/if}}
+	</div>
+	{{/ifCond}}
+	{{else}}
+	<div class="site-card-icon" aria-hidden="true">
+		{{!-- 站点图标优先级：faviconUrl > forceIconMode > 全局 icons.mode --}}
+		{{#if (lookup . "faviconUrl")}}
+		<div class="icon-container">
+			<i class="fas fa-circle-notch fa-spin icon-placeholder" aria-hidden="true"></i>
+			<img class="favicon-icon" src="{{lookup . "faviconUrl"}}" alt="{{name}} favicon" loading="lazy"
+				onload="this.classList.add('loaded'); this.previousElementSibling.classList.add('hidden');"
+				onerror="this.classList.add('error'); this.previousElementSibling.classList.add('hidden'); this.nextElementSibling.classList.add('visible');" />
+			<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}} icon-fallback" aria-hidden="true"></i>
+		</div>
+		{{else}}
+		{{#ifEquals forceIconMode "manual"}}
+		<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}} site-icon" aria-hidden="true"></i>
+		{{else}}
+		{{#ifEquals forceIconMode "favicon"}}
+		{{#ifHttpUrl url}}
+		<div class="icon-container">
+			<i class="fas fa-circle-notch fa-spin icon-placeholder" aria-hidden="true"></i>
+			<img class="favicon-icon" src="{{faviconV2Url url}}" alt="{{name}} favicon" loading="lazy"
+				onload="this.classList.add('loaded'); this.previousElementSibling.classList.add('hidden');"
+				onerror="if (!this.dataset.faviconFallbackTried) { this.dataset.faviconFallbackTried = '1'; this.src = '{{faviconFallbackUrl url}}'; return; } this.classList.add('error'); this.previousElementSibling.classList.add('hidden'); this.nextElementSibling.classList.add('visible');" />
+			<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}} icon-fallback" aria-hidden="true"></i>
+		</div>
+		{{else}}
+		<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}} site-icon" aria-hidden="true"></i>
+		{{/ifHttpUrl}}
+		{{else}}
+		{{#ifEquals @root.icons.mode "favicon"}}
+		{{#ifHttpUrl url}}
+		<div class="icon-container">
+			<i class="fas fa-circle-notch fa-spin icon-placeholder" aria-hidden="true"></i>
+			<img class="favicon-icon" src="{{faviconV2Url url}}" alt="{{name}} favicon" loading="lazy"
+				onload="this.classList.add('loaded'); this.previousElementSibling.classList.add('hidden');"
+				onerror="if (!this.dataset.faviconFallbackTried) { this.dataset.faviconFallbackTried = '1'; this.src = '{{faviconFallbackUrl url}}'; return; } this.classList.add('error'); this.previousElementSibling.classList.add('hidden'); this.nextElementSibling.classList.add('visible');" />
+			<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}} icon-fallback" aria-hidden="true"></i>
+		</div>
+		{{else}}
+		<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}} site-icon" aria-hidden="true"></i>
+		{{/ifHttpUrl}}
+		{{else}}
+		<i class="{{#if icon}}{{icon}}{{else}}fas fa-link{{/if}} site-icon" aria-hidden="true"></i>
+		{{/ifEquals}}
+		{{/ifEquals}}
+		{{/ifEquals}}
+		{{/if}}
+	</div>
+
+	<div class="site-card-content">
+		<h3>{{#if name}}{{name}}{{else}}未命名站点{{/if}}</h3>
+		<p>{{#if
+			description}}{{description}}{{else}}{{extractDomain url}}{{/if}}</p>
+	</div>
+	{{/ifEquals}}
+	{{/ifEquals}}
+</a>
+{{/if}}
diff --git a/templates/components/social-links.hbs b/templates/components/social-links.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..c783b6f638c1db3df046d2afe39fe2ebf65b9bb3
--- /dev/null
+++ b/templates/components/social-links.hbs
@@ -0,0 +1,8 @@
+{{#if this}}
+{{#each this}}
+<a href="{{safeUrl url}}" class="social-icon" target="_blank" rel="noopener" title="{{name}}" aria-label="{{name}}" data-type="social-link" data-name="{{name}}" data-url="{{url}}" data-icon="{{icon}}">
+	    <i class="{{icon}}" aria-hidden="true"></i>
+	    <span class="nav-text visually-hidden" data-editable="social-link-name">{{name}}</span>
+</a>
+{{/each}}
+{{/if}} 
diff --git a/templates/layouts/default.hbs b/templates/layouts/default.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..088a49ff197bb229c897b0169f51d3e6d4b9c564
--- /dev/null
+++ b/templates/layouts/default.hbs
@@ -0,0 +1,223 @@
+<!DOCTYPE html>
+<html lang="zh-CN" data-theme-mode="{{#if site.theme.mode}}{{site.theme.mode}}{{else}}dark{{/if}}">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="menav-version" content="{{_meta.version}}">
+    <title data-editable="site-title">{{site.title}}</title>
+    <meta name="description" content="{{site.description}}" data-editable="site-description">
+    <meta name="author" content="{{site.author}}" data-editable="site-author">
+    <link rel="icon" href="./{{site.favicon}}" type="image/x-icon">
+    <link rel="shortcut icon" href="./{{site.favicon}}" type="image/x-icon">
+    {{{fontLinks}}}
+    <style>
+{{{fontCss}}}
+    </style>
+    <!-- 预设主题和侧边栏状态，避免闪烁 -->
+    <script>
+        (function() {
+            // 读取并应用主题设置
+            var savedTheme = localStorage.getItem('theme');
+            var defaultThemeMode = document.documentElement.getAttribute('data-theme-mode') || 'dark';
+            defaultThemeMode = String(defaultThemeMode).trim().toLowerCase();
+            var shouldUseLight = false;
+
+            if (savedTheme === 'light') {
+                shouldUseLight = true;
+            } else if (savedTheme === 'dark') {
+                shouldUseLight = false;
+            } else if (defaultThemeMode === 'light') {
+                shouldUseLight = true;
+            } else if (defaultThemeMode === 'system') {
+                try {
+                    shouldUseLight =
+                        window.matchMedia && window.matchMedia('(prefers-color-scheme: light)').matches;
+                } catch (e) {
+                    shouldUseLight = false;
+                }
+            }
+
+            if (shouldUseLight) {
+                document.documentElement.classList.add('theme-preload');
+            }
+
+            // 读取并应用侧边栏状态
+            var sidebarCollapsed = localStorage.getItem('sidebarCollapsed') === 'true';
+            var isMobile = window.innerWidth <= 768;
+            if (sidebarCollapsed && !isMobile) {
+                document.documentElement.classList.add('sidebar-collapsed-preload');
+            }
+
+            // 添加这个类用于控制初始渲染
+            document.documentElement.classList.add('preload');
+        })();
+    </script>
+    <link rel="stylesheet" href="style.css">
+  {{!-- github-calendar 已迁移为构建期抓取并注入（避免 runtime 依赖 unpkg + 代理服务） --}}
+    <link rel="preconnect" href="https://cdnjs.cloudflare.com" crossorigin>
+
+    <link rel="preload" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
+    <noscript><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.2/css/all.min.css"></noscript>
+</head>
+<body class="loading">
+    <div class="layout">
+        <!-- 移动端按钮 -->
+        <div class="mobile-buttons">
+            <button class="menu-toggle" aria-label="切换菜单">
+                <i class="fas fa-bars"></i>
+            </button>
+            <button class="search-toggle" aria-label="切换搜索">
+                <i class="fas fa-search"></i>
+            </button>
+        </div>
+
+        <!-- 遮罩层 -->
+        <div class="overlay"></div>
+
+        <!-- 左侧导航 -->
+        <nav class="sidebar">
+            <div class="logo">
+                <div class="logo-brand">
+                    {{#if site.favicon}}
+                    <img class="logo-image" src="./{{site.favicon}}" alt="{{site.title}} logo" width="26" height="26">
+                    {{/if}}
+                    <h1 data-editable="logo-text">{{site.logo_text}}</h1>
+                </div>
+                <button class="sidebar-toggle" aria-label="收起/展开侧边栏">
+                    <i class="fas fa-chevron-left toggle-icon"></i>
+                </button>
+            </div>
+
+            <div class="sidebar-content">
+                <div class="nav-section">
+                    {{#if navigationData}}
+                    {{> navigation navigationData}}
+                    {{else}}
+                    {{{navigation}}}
+                    {{/if}}
+                </div>
+                <div class="sidebar-submenu-panel" aria-label="页面分类" data-container="sidebar-submenu"></div>
+            </div>
+
+	            <div class="sidebar-social" data-container="social-links">
+	                {{#if social}}
+	                {{> social-links social}}
+	                {{else}}
+	                {{{socialLinks}}}
+	                {{/if}}
+	            </div>
+
+	            <div class="sidebar-footer">
+	                <div class="copyright">
+	                    <p>© {{currentYear}} <a href="https://github.com/rbetree/menav" target="_blank" rel="noopener">MeNav</a></p>
+	                    <p>by <a href="https://github.com/rbetree" target="_blank" rel="noopener">rbetree</a></p>
+	                </div>
+	            </div>
+	        </nav>
+
+        <!-- 右侧内容区 -->
+        <main class="content">
+            <!-- 搜索框容器 -->
+            <div class="search-container">
+                <div class="search-box">
+		                    <button class="search-engine-button search-engine-toggle"
+		                            type="button"
+		                            title="选择搜索引擎"
+		                            aria-label="选择搜索引擎"
+		                            aria-haspopup="menu"
+		                            aria-controls="search-engine-dropdown"
+		                            aria-expanded="false">
+		                        <i class="search-engine-icon search-engine-icon-svg" aria-hidden="true">
+		                            <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" focusable="false">
+		                                <path fill="#616161" d="M29.171,32.001L32,29.172l12.001,12l-2.828,2.828L29.171,32.001z"></path>
+		                                <path fill="#616161" d="M36,20c0,8.837-7.163,16-16,16S4,28.837,4,20S11.163,4,20,4S36,11.163,36,20"></path>
+		                                <path fill="#37474f" d="M32.476,35.307l2.828-2.828l8.693,8.693L41.17,44L32.476,35.307z"></path>
+		                                <path fill="#64b5f6" d="M7,20c0-7.18,5.82-13,13-13s13,5.82,13,13s-5.82,13-13,13S7,27.18,7,20"></path>
+		                            </svg>
+		                        </i>
+		                        <span class="search-engine-label">本地</span>
+		                    </button>
+
+	                    <input type="text" id="search" placeholder="Search" aria-label="搜索" aria-keyshortcuts="Control+K Meta+K">
+	                    <span class="search-shortcut-hint" aria-hidden="true">Ctrl+K</span>
+
+	                    <div class="search-engine-dropdown" id="search-engine-dropdown" role="menu" aria-label="搜索引擎列表">
+	                        <button class="search-engine-option" type="button" role="menuitem" data-engine="local" title="本地搜索">
+	                            <i class="search-engine-option-svg" aria-hidden="true">
+	                                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" focusable="false">
+	                                    <path fill="#616161" d="M29.171,32.001L32,29.172l12.001,12l-2.828,2.828L29.171,32.001z"></path>
+	                                    <path fill="#616161" d="M36,20c0,8.837-7.163,16-16,16S4,28.837,4,20S11.163,4,20,4S36,11.163,36,20"></path>
+	                                    <path fill="#37474f" d="M32.476,35.307l2.828-2.828l8.693,8.693L41.17,44L32.476,35.307z"></path>
+	                                    <path fill="#64b5f6" d="M7,20c0-7.18,5.82-13,13-13s13,5.82,13,13s-5.82,13-13,13S7,27.18,7,20"></path>
+	                                </svg>
+	                            </i>
+	                            <span class="search-engine-option-label">本地搜索</span>
+	                        </button>
+	                        <button class="search-engine-option" type="button" role="menuitem" data-engine="google" title="Google搜索">
+	                            <i class="search-engine-option-svg" aria-hidden="true">
+	                                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48" focusable="false">
+	                                    <path fill="#FFC107" d="M43.611,20.083H42V20H24v8h11.303c-1.649,4.657-6.08,8-11.303,8c-6.627,0-12-5.373-12-12c0-6.627,5.373-12,12-12c3.059,0,5.842,1.154,7.961,3.039l5.657-5.657C34.046,6.053,29.268,4,24,4C12.955,4,4,12.955,4,24c0,11.045,8.955,20,20,20c11.045,0,20-8.955,20-20C44,22.659,43.862,21.35,43.611,20.083z"></path>
+	                                    <path fill="#FF3D00" d="M6.306,14.691l6.571,4.819C14.655,15.108,18.961,12,24,12c3.059,0,5.842,1.154,7.961,3.039l5.657-5.657C34.046,6.053,29.268,4,24,4C16.318,4,9.656,8.337,6.306,14.691z"></path>
+	                                    <path fill="#4CAF50" d="M24,44c5.166,0,9.86-1.977,13.409-5.192l-6.19-5.238C29.211,35.091,26.715,36,24,36c-5.202,0-9.619-3.317-11.283-7.946l-6.522,5.025C9.505,39.556,16.227,44,24,44z"></path>
+	                                    <path fill="#1976D2" d="M43.611,20.083H42V20H24v8h11.303c-0.792,2.237-2.231,4.166-4.087,5.571c0.001-0.001,0.002-0.001,0.003-0.002l6.19,5.238C36.971,39.205,44,34,44,24C44,22.659,43.862,21.35,43.611,20.083z"></path>
+	                                </svg>
+	                            </i>
+	                            <span class="search-engine-option-label">Google</span>
+	                        </button>
+	                        <button class="search-engine-option" type="button" role="menuitem" data-engine="bing" title="Bing搜索">
+	                            <i class="search-engine-option-svg" aria-hidden="true">
+	                                <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 256 256" focusable="false">
+	                                    <g fill="#2877fb" fill-rule="nonzero" stroke="none" stroke-width="1" stroke-linecap="butt" stroke-linejoin="miter" stroke-miterlimit="10" stroke-dasharray="" stroke-dashoffset="0" font-family="none" font-weight="none" font-size="none" text-anchor="none" style="mix-blend-mode: normal">
+	                                        <g transform="scale(5.12,5.12)">
+	                                            <path d="M45,26.10156v-5.10156c0,-0.89844 -0.60156,-1.69922 -1.39844,-1.89844l-4.60156,-1.40234c-5.30078,-1.59766 -10.30078,-3 -15.60156,-4.69922h-0.09766c-0.80078,-0.19922 -1.60156,0.69922 -1.19922,1.5c1.89844,3.89844 3.89844,9.5 3.89844,9.5l6.69922,2.60156c-0.30078,0 -21.69922,11.39844 -21.69922,11.39844l9,-8v-23c0,-0.89844 -0.60156,-1.80078 -1.39844,-2c0,0 -4.90234,-1.89844 -8,-2.89844c-0.20312,-0.10156 -0.40234,-0.10156 -0.60156,-0.10156c-0.39844,0 -0.80078,0.10156 -1.19922,0.39844c-0.5,0.40234 -0.80078,1 -0.80078,1.60156v34.69922c0,0.69922 0.30078,1.30078 0.89844,1.60156c2.10156,1.5 4.30078,3 6.40234,4.5l3,2.09766c0.30078,0.20313 0.69922,0.40234 1.09766,0.40234c0.40234,0 0.70313,-0.10156 1,-0.30078c4.30078,-2.60156 8.70313,-5.19922 13,-7.80078l10.60156,-6.30078c0.60156,-0.39844 1,-1 1,-1.69922z"></path>
+	                                        </g>
+	                                    </g>
+	                                </svg>
+	                            </i>
+	                            <span class="search-engine-option-label">Bing</span>
+	                        </button>
+	                        <button class="search-engine-option" type="button" role="menuitem" data-engine="duckduckgo" title="DuckDuckGo搜索">
+	                            <i class="search-engine-option-svg" aria-hidden="true">
+	                                <svg xmlns="http://www.w3.org/2000/svg" viewBox="4 4 40 40" focusable="false">
+	                                    <path fill="#ff3d00" d="M44,24c0,11-9,20-20,20S4,35,4,24S13,4,24,4S44,13,44,24z"></path>
+	                                    <path fill="#fff" d="M26,16.2c-0.6-0.6-1.5-0.9-2.5-1.1c-0.4-0.5-1-1-1.9-1.5c-1.6-0.8-3.5-1.2-5.3-0.9h-0.4 c-0.1,0-0.2,0.1-0.4,0.1c0.2,0,1,0.4,1.6,0.6c-0.3,0.2-0.8,0.2-1.1,0.4c0,0,0,0-0.1,0L15.7,14c-0.1,0.2-0.2,0.4-0.2,0.5 c1.3-0.1,3.2,0,4.6,0.4C19,15,18,15.3,17.3,15.7c-0.5,0.3-1,0.6-1.3,1.1c-1.2,1.3-1.7,3.5-1.3,5.9c0.5,2.7,2.4,11.4,3.4,16.3 l0.3,1.6c0,0,3.5,0.4,5.6,0.4c1.2,0,3.2,0.3,3.7-0.2c-0.1,0-0.6-0.6-0.8-1.1c-0.5-1-1-1.9-1.4-2.6c-1.2-2.5-2.5-5.9-1.9-8.1 c0.1-0.4,0.1-2.1,0.4-2.3c2.6-1.7,2.4-0.1,3.5-0.8c0.5-0.4,1-0.9,1.2-1.5C29.4,22.1,27.8,18,26,16.2z"></path>
+	                                    <path fill="#fff" d="M24,42c-9.9,0-18-8.1-18-18c0-9.9,8.1-18,18-18c9.9,0,18,8.1,18,18C42,33.9,33.9,42,24,42z M24,8 C15.2,8,8,15.2,8,24s7.2,16,16,16s16-7.2,16-16S32.8,8,24,8z"></path>
+	                                    <path fill="#0277bd" d="M19,21.1c-0.6,0-1.2,0.5-1.2,1.2c0,0.6,0.5,1.2,1.2,1.2c0.6,0,1.2-0.5,1.2-1.2 C20.1,21.7,19.6,21.1,19,21.1z M19.5,22.2c-0.2,0-0.3-0.1-0.3-0.3c0-0.2,0.1-0.3,0.3-0.3s0.3,0.1,0.3,0.3 C19.8,22.1,19.6,22.2,19.5,22.2z M26.8,20.6c-0.6,0-1,0.5-1,1c0,0.6,0.5,1,1,1c0.6,0,1-0.5,1-1S27.3,20.6,26.8,20.6z M27.2,21.5 c-0.1,0-0.3-0.1-0.3-0.3c0-0.1,0.1-0.3,0.3-0.3c0.1,0,0.3,0.1,0.3,0.3S27.4,21.5,27.2,21.5z M19.3,18.9c0,0-0.9-0.4-1.7,0.1 c-0.9,0.5-0.8,1.1-0.8,1.1s-0.5-1,0.8-1.5C18.7,18.1,19.3,18.9,19.3,18.9 M27.4,18.8c0,0-0.6-0.4-1.1-0.4c-1,0-1.3,0.5-1.3,0.5 s0.2-1.1,1.5-0.9C27.1,18.2,27.4,18.8,27.4,18.8"></path>
+	                                    <path fill="#8bc34a" d="M23.3,35.7c0,0-4.3-2.3-4.4-1.4c-0.1,0.9,0,4.7,0.5,5s4.1-1.9,4.1-1.9L23.3,35.7z M25,35.6 c0,0,2.9-2.2,3.6-2.1c0.6,0.1,0.8,4.7,0.2,4.9c-0.6,0.2-3.9-1.2-3.9-1.2L25,35.6z"></path>
+	                                    <path fill="#689f38" d="M22.5,35.7c0,1.5-0.2,2.1,0.4,2.3c0.6,0.1,1.9,0,2.3-0.3c0.4-0.3,0.1-2.2-0.1-2.6 C25,34.8,22.5,35.1,22.5,35.7"></path>
+	                                    <path fill="#ffca28" d="M22.3,26.8c0.1-0.7,2-2.1,3.3-2.2c1.3-0.1,1.7-0.1,2.8-0.3c1.1-0.3,3.9-1,4.7-1.3 c0.8-0.4,4.1,0.2,1.8,1.5c-1,0.6-3.7,1.6-5.7,2.2c-1.9,0.6-3.1-0.6-3.8,0.4c-0.5,0.8-0.1,1.8,2.2,2c3.1,0.3,6.2-1.4,6.5-0.5 c0.3,0.9-2.7,2-4.6,2.1c-1.8,0-5.6-1.2-6.1-1.6C22.9,28.7,22.2,27.8,22.3,26.8"></path>
+	                                </svg>
+	                            </i>
+	                            <span class="search-engine-option-label">DuckDuckGo</span>
+	                        </button>
+                    </div>
+                </div>
+            </div>
+
+            <!-- 页面容器 -->
+            {{#each pages}}
+            <div class="page {{@key}}{{#if @first}} active{{/if}}" id="{{@key}}">
+                {{{this}}}
+            </div>
+            {{/each}}
+        </main>
+
+        <!-- 分类切换按钮 -->
+        <button class="category-toggle" id="category-toggle" aria-label="展开/收起分类">
+            <i class="fas fa-angle-double-down"></i>
+        </button>
+
+        <!-- 主题切换按钮 -->
+        <button class="theme-toggle" aria-label="切换主题">
+            <i class="fas fa-moon"></i>
+        </button>
+    </div>
+    <!-- 配置元信息（版本/配置URL/少量运行时参数）- 用于浏览器扩展按需加载 -->
+    <script id="menav-config-data" type="application/json" style="display: none;">
+        {{{configJSON}}}
+    </script>
+    <script src="pinyin-match.js"></script>
+  {{!-- github-calendar 已迁移为构建期抓取并注入（避免 runtime 依赖 unpkg + 代理服务） --}}
+    <script src="script.js"></script>
+</body>
+</html>
diff --git a/templates/pages/articles.hbs b/templates/pages/articles.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..5658a3f7a3450735abbb11ce953c3e387c41e373
--- /dev/null
+++ b/templates/pages/articles.hbs
@@ -0,0 +1,66 @@
+{{!-- articles.hbs - 文章页面：恢复分类展示；Phase 2 优先展示文章条目（只读） --}}
+<div class="page-template page-template-articles">
+    {{> page-header}}
+
+    {{#if articlesItems.length}}
+        {{!-- Phase 2：按配置分类聚合展示文章条目（只读），保持与页面分类结构一致 --}}
+        {{#if articlesCategories.length}}
+            {{#each articlesCategories}}
+                <section class="category category-level-1 category-readonly">
+                    <div class="category-header" data-toggle="category">
+                        <h2>
+                            <i class="{{#if icon}}{{icon}}{{else}}fas fa-rss{{/if}}"></i>
+                            {{name}}
+                            <span class="toggle-icon">
+                                <i class="fas fa-chevron-down"></i>
+                            </span>
+                        </h2>
+                    </div>
+                    <div class="category-content">
+                        {{#if items.length}}
+                            <div class="sites-grid">
+                                {{#each items}}
+                                    {{> site-card type="article" style=@root.siteCardStyle}}
+                                {{/each}}
+                            </div>
+                        {{else}}
+                            <p class="empty-content">暂无文章</p>
+                        {{/if}}
+                    </div>
+                </section>
+            {{/each}}
+        {{else}}
+            {{!-- 兜底：无分类映射时展示为单一“最新文章”列表 --}}
+            <section class="category category-level-1 category-readonly">
+                <div class="category-header" data-toggle="category">
+                    <h2>
+                        <i class="fas fa-rss"></i>
+                        最新文章
+                        <span class="toggle-icon">
+                            <i class="fas fa-chevron-down"></i>
+                        </span>
+                    </h2>
+                </div>
+                <div class="category-content">
+                    <div class="sites-grid">
+                        {{#each articlesItems}}
+                            {{> site-card type="article" style=@root.siteCardStyle}}
+                        {{/each}}
+                    </div>
+                </div>
+            </section>
+        {{/if}}
+
+        {{!-- 保留扩展可写回结构（隐藏），避免文章条目影响 DOM → IR → YAML --}}
+        <div class="menav-extension-shadow" data-extension-shadow="true" data-search-exclude="true" aria-hidden="true">
+            {{#each categories}}
+                {{> category}}
+            {{/each}}
+        </div>
+    {{else}}
+        {{!-- Phase 1：来源站点入口（可写回） --}}
+        {{#each categories}}
+            {{> category}}
+        {{/each}}
+    {{/if}}
+</div>
diff --git a/templates/pages/bookmarks.hbs b/templates/pages/bookmarks.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..1f88cf0c3ddcb18d93c20dac381255de4ca6a458
--- /dev/null
+++ b/templates/pages/bookmarks.hbs
@@ -0,0 +1,4 @@
+{{> page-header}}
+{{#each categories}}
+    {{> category}}
+{{/each}} 
diff --git a/templates/pages/content.hbs b/templates/pages/content.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..e02c4a8676ad6b0161e26bb739b75e67225b9aaf
--- /dev/null
+++ b/templates/pages/content.hbs
@@ -0,0 +1,10 @@
+{{!-- content.hbs - 内容页（Markdown -> HTML，构建期渲染） --}}
+<div class="page-template page-template-{{pageId}} page-template-content">
+    {{> page-header}}
+
+    <div class="category content-category">
+        <article class="content-page" data-content-file="{{contentFile}}">
+            {{{contentHtml}}}
+        </article>
+    </div>
+</div>
diff --git a/templates/pages/page.hbs b/templates/pages/page.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..28d1d7853cc2ac30924688ce809eb48962405402
--- /dev/null
+++ b/templates/pages/page.hbs
@@ -0,0 +1,11 @@
+{{!-- page.hbs - 通用页面模板：结构与其他页面一致（标题区 + 分类内容） --}}
+<div class="page-template page-template-{{pageId}}">
+    {{#if isHome}}
+    {{> home-dashboard}}
+    {{else}}
+    {{> page-header}}
+    {{/if}}
+    {{#each categories}}
+    {{> category}}
+    {{/each}}
+</div>
\ No newline at end of file
diff --git a/templates/pages/projects.hbs b/templates/pages/projects.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..7399920db199220c0b3c7278d019af1ccad9d5f3
--- /dev/null
+++ b/templates/pages/projects.hbs
@@ -0,0 +1,14 @@
+{{!-- projects.hbs - 项目页：风格 A（代码仓库风），标题栏右侧展示 GitHub 热力图（可选） --}}
+<div class="page-template page-template-projects">
+    {{> page-header}}
+
+    {{#if projectsMeta}}
+    {{#if projectsMeta.heatmap}}
+        {{> github-heatmap username=projectsMeta.heatmap.username html=projectsMeta.heatmap.html}}
+    {{/if}}
+    {{/if}}
+
+    {{#each categories}}
+        {{> category}}
+    {{/each}}
+</div>
diff --git a/templates/pages/search-results.hbs b/templates/pages/search-results.hbs
new file mode 100644
index 0000000000000000000000000000000000000000..170f72601480dc4d4e9ce720f6cadad5b2e40e3e
--- /dev/null
+++ b/templates/pages/search-results.hbs
@@ -0,0 +1,13 @@
+<!-- 搜索结果页 -->
+<div class="welcome-section">
+    <div class="welcome-section-main">
+        <h2 data-editable="page-title">搜索结果</h2>
+        <p class="subtitle" data-editable="page-subtitle">在所有页面中找到的匹配项</p>
+    </div>
+</div>
+{{#each navigation}}
+<section class="category search-section" data-section="{{id}}" data-type="category" data-name="{{name}}" data-icon="{{icon}}" style="display: none;">
+    <h2 data-editable="category-name"><i class="{{icon}}"></i> {{name}}匹配项</h2>
+    <div class="sites-grid" data-container="sites"></div>
+</section>
+{{/each}} 
diff --git a/test/404-fallback.node-test.js b/test/404-fallback.node-test.js
new file mode 100644
index 0000000000000000000000000000000000000000..34f26d94684bea498559f36a1fbc6a8e4d73527c
--- /dev/null
+++ b/test/404-fallback.node-test.js
@@ -0,0 +1,15 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const { generate404Html } = require('../src/generator.js');
+
+test('P1-5：404.html 回跳应将 /<id> 转为 ?page=<id>（并支持仓库前缀）', () => {
+  const html = generate404Html({ site: { title: 'Test Site' } });
+
+  assert.ok(typeof html === 'string' && html.length > 0);
+  assert.ok(html.includes('?page='), '应包含 ?page= 形态');
+  assert.ok(html.includes('encodeURIComponent(pageId)'), '应对 pageId 做 URL 编码');
+  assert.ok(html.includes('segments.length === 1'), '应支持用户站点 /<id>');
+  assert.ok(html.includes('segments.length === 2'), '应支持仓库站点 /<repo>/<id>');
+  assert.ok(html.includes('l.replace(target)'), '应使用 location.replace 执行回跳');
+});
diff --git a/test/bookmark-processor.node-test.js b/test/bookmark-processor.node-test.js
new file mode 100644
index 0000000000000000000000000000000000000000..721623fac59be62306388f85d8f014fb725abc59
--- /dev/null
+++ b/test/bookmark-processor.node-test.js
@@ -0,0 +1,200 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const {
+  ensureUserConfigInitialized,
+  ensureUserSiteYmlExists,
+  upsertBookmarksNavInSiteYml,
+  parseBookmarks,
+  generateBookmarksYaml,
+} = require('../src/bookmark-processor.js');
+
+function stripYamlComments(yamlText) {
+  return yamlText
+    .split(/\r?\n/)
+    .filter((line) => !/^\s*#/.test(line))
+    .join('\n')
+    .trim();
+}
+
+test('parseBookmarks：解析书签栏、根目录书签与图标映射', () => {
+  const html = `
+<!DOCTYPE NETSCAPE-Bookmark-file-1>
+<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=UTF-8">
+<TITLE>Bookmarks</TITLE>
+<H1>Bookmarks</H1>
+<DL><p>
+  <DT><H3 PERSONAL_TOOLBAR_FOLDER="true">书签栏</H3>
+  <DL><p>
+    <DT><A HREF="https://github.com/">GitHub</A>
+    <DT><H3>工具</H3>
+    <DL><p>
+      <DT><A HREF="https://www.google.com/">Google</A>
+    </DL><p>
+  </DL><p>
+</DL><p>
+`;
+
+  const bookmarks = parseBookmarks(html);
+  assert.ok(bookmarks);
+  assert.ok(Array.isArray(bookmarks.categories));
+  assert.ok(bookmarks.categories.length >= 2);
+
+  // 根目录书签应该插入到首位
+  assert.equal(bookmarks.categories[0].name, '根目录书签');
+  assert.ok(Array.isArray(bookmarks.categories[0].sites));
+  assert.equal(bookmarks.categories[0].sites[0].name, 'GitHub');
+  assert.equal(bookmarks.categories[0].sites[0].icon, 'fab fa-github');
+
+  const tools = bookmarks.categories.find((c) => c.name === '工具');
+  assert.ok(tools, '应解析出“工具”分类');
+  assert.ok(Array.isArray(tools.sites));
+  assert.equal(tools.sites[0].name, 'Google');
+});
+
+test('templates：subgroups（第4层）应可渲染到页面', () => {
+  const Handlebars = require('handlebars');
+  const { registerAllHelpers } = require('../src/helpers');
+
+  const hbs = Handlebars.create();
+  registerAllHelpers(hbs);
+
+  const category = fs.readFileSync(
+    path.join(__dirname, '..', 'templates', 'components', 'category.hbs'),
+    'utf8'
+  );
+  const group = fs.readFileSync(
+    path.join(__dirname, '..', 'templates', 'components', 'group.hbs'),
+    'utf8'
+  );
+  const pageHeader = fs.readFileSync(
+    path.join(__dirname, '..', 'templates', 'components', 'page-header.hbs'),
+    'utf8'
+  );
+  const siteCard = fs.readFileSync(
+    path.join(__dirname, '..', 'templates', 'components', 'site-card.hbs'),
+    'utf8'
+  );
+  const page = fs.readFileSync(
+    path.join(__dirname, '..', 'templates', 'pages', 'bookmarks.hbs'),
+    'utf8'
+  );
+
+  hbs.registerPartial('category', category);
+  hbs.registerPartial('group', group);
+  hbs.registerPartial('page-header', pageHeader);
+  hbs.registerPartial('site-card', siteCard);
+
+  const tpl = hbs.compile(page);
+
+  const html = tpl({
+    title: '我的书签',
+    subtitle: '测试 subgroups 渲染',
+    icons: { mode: 'manual' },
+    categories: [
+      {
+        name: '技术',
+        icon: 'fas fa-code',
+        subcategories: [
+          {
+            name: '前端',
+            icon: 'fas fa-laptop-code',
+            groups: [
+              {
+                name: '框架',
+                icon: 'fas fa-cubes',
+                subgroups: [
+                  {
+                    name: 'React生态',
+                    icon: 'fab fa-react',
+                    sites: [
+                      {
+                        name: 'React',
+                        url: 'https://reactjs.org/',
+                        icon: 'fab fa-react',
+                        description: 'React官方',
+                      },
+                    ],
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  });
+
+  assert.ok(html.includes('subgroups-container'), '应输出 subgroups-container 容器');
+  assert.ok(html.includes('group-level-4'), '应输出 level=4 的 group 样式类');
+  assert.ok(html.includes('React生态'), '应渲染子分组标题文本');
+});
+
+test('generateBookmarksYaml：生成 YAML 且可被解析', () => {
+  const bookmarks = {
+    categories: [
+      {
+        name: '示例分类',
+        icon: 'fas fa-folder',
+        sites: [
+          { name: 'Example', url: 'https://example.com', icon: 'fas fa-link', description: '' },
+        ],
+      },
+    ],
+  };
+
+  const yamlText = generateBookmarksYaml(bookmarks);
+  assert.ok(typeof yamlText === 'string');
+  assert.ok(yamlText.includes('# 自动生成的书签配置文件'));
+  assert.ok(yamlText.includes('categories:'));
+
+  const yaml = require('js-yaml');
+  const parsed = yaml.load(stripYamlComments(yamlText));
+  assert.equal(parsed.title, '我的书签');
+  assert.ok(Array.isArray(parsed.categories));
+  assert.equal(parsed.categories[0].name, '示例分类');
+});
+
+test('upsertBookmarksNavInSiteYml：无 navigation 时追加并幂等', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'menav-test-'));
+  const filePath = path.join(tmp, 'site.yml');
+
+  fs.writeFileSync(filePath, `title: Test Site\n`, 'utf8');
+
+  const r1 = upsertBookmarksNavInSiteYml(filePath);
+  assert.equal(r1.updated, true);
+
+  const updated1 = fs.readFileSync(filePath, 'utf8');
+  assert.ok(updated1.includes('navigation:'));
+  assert.ok(updated1.includes('- name: 书签'));
+  assert.ok(updated1.includes('id: bookmarks'));
+
+  const r2 = upsertBookmarksNavInSiteYml(filePath);
+  assert.equal(r2.updated, false);
+  assert.equal(r2.reason, 'already_present');
+});
+
+test('ensureUserConfigInitialized/ensureUserSiteYmlExists：可在空目录初始化用户配置', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'menav-test-'));
+  const originalCwd = process.cwd();
+  process.chdir(tmp);
+
+  try {
+    fs.mkdirSync('config/_default/pages', { recursive: true });
+    fs.writeFileSync('config/_default/site.yml', 'title: Default\n', 'utf8');
+    fs.writeFileSync('config/_default/pages/common.yml', 'categories: []\n', 'utf8');
+
+    const init = ensureUserConfigInitialized();
+    assert.equal(init.initialized, true);
+    assert.ok(fs.existsSync('config/user/site.yml'));
+    assert.ok(fs.existsSync('config/user/pages/common.yml'));
+
+    // 若 site.yml 已存在，应直接返回 true
+    assert.equal(ensureUserSiteYmlExists(), true);
+  } finally {
+    process.chdir(originalCwd);
+  }
+});
diff --git a/test/category-slug-dedup.node-test.js b/test/category-slug-dedup.node-test.js
new file mode 100644
index 0000000000000000000000000000000000000000..be064213c22f35429a37f10dfef488c6affd94ad
--- /dev/null
+++ b/test/category-slug-dedup.node-test.js
@@ -0,0 +1,48 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const { loadHandlebarsTemplates, generateAllPagesHTML } = require('../src/generator.js');
+
+function withRepoRoot(fn) {
+  const originalCwd = process.cwd();
+  process.chdir(path.join(__dirname, '..'));
+  try {
+    return fn();
+  } finally {
+    process.chdir(originalCwd);
+  }
+}
+
+test('P1-2：分类 slug 应稳定且可去重', () => {
+  withRepoRoot(() => {
+    loadHandlebarsTemplates();
+
+    const config = {
+      site: { title: 'Test Site', description: '', author: '', favicon: '', logo_text: 'Test' },
+      profile: { title: 'PROFILE_TITLE', subtitle: 'PROFILE_SUBTITLE' },
+      social: [],
+      navigation: [{ id: 'home', name: '首页', icon: 'fas fa-home' }],
+      home: {
+        title: 'HOME',
+        subtitle: 'HOME_SUB',
+        template: 'page',
+        categories: [
+          { name: '重复 分类', icon: 'fas fa-tag', sites: [] },
+          { name: '重复 分类', icon: 'fas fa-tag', sites: [] },
+          { name: '含 空格/特殊#字符', icon: 'fas fa-tag', sites: [] },
+        ],
+      },
+    };
+
+    const pages = generateAllPagesHTML(config);
+    assert.ok(typeof pages.home === 'string' && pages.home.length > 0);
+
+    assert.ok(pages.home.includes('id="重复-分类"'), '首个重复分类应生成稳定 slug');
+    assert.ok(pages.home.includes('id="重复-分类-2"'), '重复分类应通过后缀去重');
+    assert.ok(pages.home.includes('id="含-空格-特殊-字符"'), '空格/特殊字符应被规范化为可用 slug');
+
+    assert.ok(pages.home.includes('data-id="重复-分类"'));
+    assert.ok(pages.home.includes('data-id="重复-分类-2"'));
+  });
+});
diff --git a/test/content-page-markdown.node-test.js b/test/content-page-markdown.node-test.js
new file mode 100644
index 0000000000000000000000000000000000000000..849d8508fbd441c9ec2d7215b7bae75cbb561308
--- /dev/null
+++ b/test/content-page-markdown.node-test.js
@@ -0,0 +1,91 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { loadHandlebarsTemplates, generateAllPagesHTML } = require('../src/generator.js');
+
+function withRepoRoot(fn) {
+  const originalCwd = process.cwd();
+  process.chdir(path.join(__dirname, '..'));
+  try {
+    return fn();
+  } finally {
+    process.chdir(originalCwd);
+  }
+}
+
+test('content：构建期渲染 markdown 文件，并对链接做 scheme 安全降级', () => {
+  withRepoRoot(() => {
+    loadHandlebarsTemplates();
+
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'menav-content-page-'));
+    const mdPath = path.join(tmpDir, 'about.md');
+    fs.writeFileSync(
+      mdPath,
+      [
+        '# About',
+        '',
+        'A normal link: [ok](https://example.com)',
+        '',
+        'A bad link: [bad](javascript:alert(1))',
+        '',
+        'Protocol-relative should be blocked: [pr](//example.com)',
+        '',
+        'Image should be disabled: ![x](https://example.com/x.png)',
+      ].join('\n'),
+      'utf8'
+    );
+
+    try {
+      const config = {
+        site: {
+          title: 'Test Site',
+          description: '',
+          author: '',
+          favicon: '',
+          logo_text: 'Test',
+          security: { allowedSchemes: ['http', 'https', 'mailto', 'tel'] },
+        },
+        profile: { title: 'PROFILE_TITLE', subtitle: 'PROFILE_SUBTITLE' },
+        social: [],
+        navigation: [{ id: 'about', name: '关于', icon: 'fas fa-info' }],
+        about: {
+          title: '关于',
+          subtitle: '说明',
+          template: 'content',
+          content: {
+            file: mdPath,
+          },
+        },
+      };
+
+      const pages = generateAllPagesHTML(config);
+      const html = pages.about;
+
+      assert.ok(typeof html === 'string' && html.length > 0);
+      assert.ok(html.includes('page-template-about'));
+      assert.ok(html.includes('page-template-content'));
+      assert.ok(html.includes('<h1>About</h1>'));
+      assert.ok(html.includes('A normal link'));
+      assert.ok(html.includes('href="https://example.com"'));
+
+      // javascript: should be blocked
+      assert.ok(html.includes('A bad link'));
+      assert.ok(/href=['"]#['"]/.test(html), '不安全链接应降级为 href="#"');
+
+      // protocol-relative should be blocked
+      assert.ok(html.includes('Protocol-relative should be blocked'));
+
+      // image should be disabled
+      assert.ok(!html.includes('<img'), '本期不支持图片：markdown 渲染不应输出 <img>');
+    } finally {
+      try {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+      } catch {
+        // ignore
+      }
+    }
+  });
+});
diff --git a/test/favicon-url-field-render.node-test.js b/test/favicon-url-field-render.node-test.js
new file mode 100644
index 0000000000000000000000000000000000000000..3d8629cafc4e5359b988ebd915f71285709fecae
--- /dev/null
+++ b/test/favicon-url-field-render.node-test.js
@@ -0,0 +1,75 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const { loadHandlebarsTemplates, renderTemplate } = require('../src/generator.js');
+
+function withRepoCwd(callback) {
+  const originalCwd = process.cwd();
+  const repoRoot = path.join(__dirname, '..');
+  try {
+    process.chdir(repoRoot);
+    callback();
+  } finally {
+    process.chdir(originalCwd);
+  }
+}
+
+function renderBookmarksWithSite(site) {
+  loadHandlebarsTemplates();
+  return renderTemplate(
+    'bookmarks',
+    {
+      pageId: 'bookmarks',
+      homePageId: 'bookmarks',
+      title: '书签',
+      subtitle: '测试',
+      siteCardStyle: '',
+      icons: { mode: 'favicon', region: 'com' },
+      categories: [
+        {
+          name: '分类',
+          icon: 'fas fa-folder',
+          sites: [site],
+        },
+      ],
+    },
+    false
+  );
+}
+
+test('站点配置包含 faviconUrl（本地 assets 路径）时，渲染 bookmarks 不应崩溃', () => {
+  withRepoCwd(() => {
+    const html = renderBookmarksWithSite({
+      name: '内部系统',
+      url: 'https://intranet.example/',
+      faviconUrl: 'assets/menav.svg',
+      icon: 'fas fa-link',
+      external: true,
+    });
+
+    assert.match(html, /data-favicon-url="assets\/menav\.svg"/);
+    assert.match(html, /src="assets\/menav\.svg"/);
+  });
+});
+
+test('站点配置包含 faviconUrl（在线 ico）时，渲染 bookmarks 不应崩溃', () => {
+  withRepoCwd(() => {
+    const html = renderBookmarksWithSite({
+      name: 'WebCull',
+      url: 'https://example.com/',
+      faviconUrl: 'https://content.webcull.com/images/websites/icons/470/695/b788b0.ico',
+      icon: 'fas fa-link',
+      external: true,
+    });
+
+    assert.match(
+      html,
+      /data-favicon-url="https:\/\/content\.webcull\.com\/images\/websites\/icons\/470\/695\/b788b0\.ico"/
+    );
+    assert.match(
+      html,
+      /src="https:\/\/content\.webcull\.com\/images\/websites\/icons\/470\/695\/b788b0\.ico"/
+    );
+  });
+});
diff --git a/test/favicon-v2-drop-404-icon.node-test.js b/test/favicon-v2-drop-404-icon.node-test.js
new file mode 100644
index 0000000000000000000000000000000000000000..c280cdf62e3132bac35f5e2d9d098ce9d92432de
--- /dev/null
+++ b/test/favicon-v2-drop-404-icon.node-test.js
@@ -0,0 +1,32 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { faviconV2Url, faviconFallbackUrl } = require('../src/helpers/utils');
+
+test('faviconV2：应追加 drop_404_icon=true 以避免返回占位图', () => {
+  const optionsCom = { data: { root: { icons: { region: 'com' } } } };
+  const optionsCn = { data: { root: { icons: { region: 'cn' } } } };
+
+  const url = 'https://example.com';
+
+  const com = faviconV2Url(url, optionsCom);
+  const cn = faviconV2Url(url, optionsCn);
+  const fallbackCom = faviconFallbackUrl(url, optionsCom);
+  const fallbackCn = faviconFallbackUrl(url, optionsCn);
+
+  for (const out of [com, cn, fallbackCom, fallbackCn]) {
+    assert.ok(out.includes('drop_404_icon=true'), '生成的 URL 应包含 drop_404_icon=true');
+  }
+});
+
+test('运行时新增站点：faviconV2 URL 也应包含 drop_404_icon=true', () => {
+  const repoRoot = path.resolve(__dirname, '..');
+  const runtimePath = path.join(repoRoot, 'src', 'runtime', 'menav', 'addElement.js');
+  const content = fs.readFileSync(runtimePath, 'utf8');
+  assert.ok(
+    content.includes('drop_404_icon=true'),
+    'src/runtime/menav/addElement.js 应追加 drop_404_icon=true'
+  );
+});
diff --git a/test/home-page-profile-override.node-test.js b/test/home-page-profile-override.node-test.js
new file mode 100644
index 0000000000000000000000000000000000000000..032b5eb7ba48157da3ab076684d8a40f95d109ba
--- /dev/null
+++ b/test/home-page-profile-override.node-test.js
@@ -0,0 +1,70 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const { loadHandlebarsTemplates, generateAllPagesHTML } = require('../src/generator.js');
+
+test('首页（navigation 第一项）应使用 profile 覆盖 title/subtitle 显示', () => {
+  const originalCwd = process.cwd();
+  process.chdir(path.join(__dirname, '..'));
+
+  try {
+    loadHandlebarsTemplates();
+
+    const config = {
+      site: { title: 'Test Site', description: '', author: '', favicon: '', logo_text: 'Test' },
+      profile: { title: 'PROFILE_TITLE', subtitle: 'PROFILE_SUBTITLE' },
+      social: [],
+      navigation: [
+        { id: 'bookmarks', name: '书签', icon: 'fas fa-bookmark' },
+        { id: 'home', name: '首页', icon: 'fas fa-home' },
+        { id: 'projects', name: '项目', icon: 'fas fa-project-diagram' },
+      ],
+      bookmarks: {
+        title: '书签页标题',
+        subtitle: '书签页副标题',
+        template: 'bookmarks',
+        categories: [],
+      },
+      home: {
+        title: 'HOME_PAGE_TITLE',
+        subtitle: 'HOME_PAGE_SUBTITLE',
+        template: 'page',
+        categories: [],
+      },
+      projects: {
+        title: '项目页标题',
+        subtitle: '项目页副标题',
+        template: 'projects',
+        categories: [],
+      },
+    };
+
+    const pages = generateAllPagesHTML(config);
+
+    assert.ok(typeof pages.bookmarks === 'string' && pages.bookmarks.length > 0);
+    assert.ok(pages.bookmarks.includes('PROFILE_TITLE'));
+    assert.ok(pages.bookmarks.includes('PROFILE_SUBTITLE'));
+    assert.ok(pages.bookmarks.includes('data-editable="profile-title"'));
+    assert.ok(pages.bookmarks.includes('data-editable="profile-subtitle"'));
+    assert.ok(pages.bookmarks.includes('<h3'));
+    assert.ok(!pages.bookmarks.includes('书签页标题'));
+    assert.ok(!pages.bookmarks.includes('书签页副标题'));
+    assert.ok(!pages.bookmarks.includes('data-editable="page-title"'));
+
+    assert.ok(typeof pages.home === 'string' && pages.home.length > 0);
+    assert.ok(pages.home.includes('HOME_PAGE_TITLE'));
+    assert.ok(pages.home.includes('HOME_PAGE_SUBTITLE'));
+    assert.ok(pages.home.includes('data-editable="page-title"'));
+    assert.ok(pages.home.includes('data-editable="page-subtitle"'));
+    assert.ok(pages.home.includes('<p class="subtitle"'));
+    assert.ok(!pages.home.includes('PROFILE_TITLE'));
+
+    assert.ok(typeof pages.projects === 'string' && pages.projects.length > 0);
+    assert.ok(pages.projects.includes('项目页标题'));
+    assert.ok(pages.projects.includes('项目页副标题'));
+    assert.ok(pages.projects.includes('<p class="subtitle"'));
+  } finally {
+    process.chdir(originalCwd);
+  }
+});
diff --git a/test/icons-mode-from-site-yml.node-test.js b/test/icons-mode-from-site-yml.node-test.js
new file mode 100644
index 0000000000000000000000000000000000000000..f2bb64a8a63e84e9c95d8847787d639890c1c564
--- /dev/null
+++ b/test/icons-mode-from-site-yml.node-test.js
@@ -0,0 +1,48 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { loadConfig } = require('../src/generator.js');
+
+function withTempCwd(callback) {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'menav-icons-mode-test-'));
+  const originalCwd = process.cwd();
+
+  try {
+    process.chdir(tmpDir);
+    callback(tmpDir);
+  } finally {
+    process.chdir(originalCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+test('site.yml 的 icons.mode 应提升为顶层 icons.mode（manual 不应被默认 favicon 覆盖）', () => {
+  withTempCwd((tmpDir) => {
+    const defaultConfigDir = path.join(tmpDir, 'config', '_default');
+    fs.mkdirSync(defaultConfigDir, { recursive: true });
+
+    fs.writeFileSync(
+      path.join(defaultConfigDir, 'site.yml'),
+      ['title: Test', 'icons:', '  mode: manual', ''].join('\n'),
+      'utf8'
+    );
+
+    const config = loadConfig();
+    assert.equal(config.icons.mode, 'manual');
+  });
+});
+
+test('未配置 icons.mode 时应回退为默认 favicon', () => {
+  withTempCwd((tmpDir) => {
+    const defaultConfigDir = path.join(tmpDir, 'config', '_default');
+    fs.mkdirSync(defaultConfigDir, { recursive: true });
+
+    fs.writeFileSync(path.join(defaultConfigDir, 'site.yml'), 'title: Test\n', 'utf8');
+
+    const config = loadConfig();
+    assert.equal(config.icons.mode, 'favicon');
+  });
+});
diff --git a/test/multi-level-sites-external-default.node-test.js b/test/multi-level-sites-external-default.node-test.js
new file mode 100644
index 0000000000000000000000000000000000000000..e45807b57d3e398be9e3cebf7406e8d7de407e76
--- /dev/null
+++ b/test/multi-level-sites-external-default.node-test.js
@@ -0,0 +1,69 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { loadConfig } = require('../src/generator.js');
+
+function withTempCwd(callback) {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'menav-multilevel-external-test-'));
+  const originalCwd = process.cwd();
+
+  try {
+    process.chdir(tmpDir);
+    callback(tmpDir);
+  } finally {
+    process.chdir(originalCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  }
+}
+
+test('多级结构下 sites.external 未配置时应默认 true，且 external:false 不应被覆盖', () => {
+  withTempCwd((tmpDir) => {
+    const defaultConfigDir = path.join(tmpDir, 'config', '_default');
+    const defaultPagesDir = path.join(defaultConfigDir, 'pages');
+    fs.mkdirSync(defaultPagesDir, { recursive: true });
+
+    fs.writeFileSync(path.join(defaultConfigDir, 'site.yml'), 'title: Test\n', 'utf8');
+
+    fs.writeFileSync(
+      path.join(defaultPagesDir, 'bookmarks.yml'),
+      [
+        'title: 书签',
+        'subtitle: bookmarks',
+        'template: bookmarks',
+        'categories:',
+        '  - name: 技术资源',
+        '    groups:',
+        '      - name: 组内站点',
+        '        sites:',
+        '          - name: GroupSite',
+        '            url: https://example.com/group',
+        '    subcategories:',
+        '      - name: 前端开发',
+        '        groups:',
+        '          - name: 框架库',
+        '            subgroups:',
+        '              - name: 深层分组',
+        '                sites:',
+        '                  - name: DeepDefaultExternal',
+        '                    url: https://example.com/deep-default',
+        '                  - name: DeepExternalFalse',
+        '                    url: https://example.com/deep-false',
+        '                    external: false',
+        '',
+      ].join('\n'),
+      'utf8'
+    );
+
+    const config = loadConfig();
+
+    const groupSite = config.bookmarks.categories[0].groups[0].sites[0];
+    assert.equal(groupSite.external, true);
+
+    const deepSites = config.bookmarks.categories[0].subcategories[0].groups[0].subgroups[0].sites;
+    assert.equal(deepSites[0].external, true);
+    assert.equal(deepSites[1].external, false);
+  });
+});
diff --git a/test/navigation-submenu-uses-category-slug.node-test.js b/test/navigation-submenu-uses-category-slug.node-test.js
new file mode 100644
index 0000000000000000000000000000000000000000..d5996c0d36005d76990f74e4c56a5a30b2e7d8c4
--- /dev/null
+++ b/test/navigation-submenu-uses-category-slug.node-test.js
@@ -0,0 +1,45 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const { loadHandlebarsTemplates, generateHTML } = require('../src/generator.js');
+
+function withRepoRoot(fn) {
+  const originalCwd = process.cwd();
+  process.chdir(path.join(__dirname, '..'));
+  try {
+    return fn();
+  } finally {
+    process.chdir(originalCwd);
+  }
+}
+
+test('P1-2：子菜单锚点应使用分类 slug（href + data-category-id）', () => {
+  withRepoRoot(() => {
+    loadHandlebarsTemplates();
+
+    const config = {
+      site: { title: 'Test Site', description: '', author: '', favicon: '', logo_text: 'Test' },
+      profile: { title: 'PROFILE_TITLE', subtitle: 'PROFILE_SUBTITLE' },
+      social: [],
+      navigation: [{ id: 'home', name: '首页', icon: 'fas fa-home' }],
+      home: {
+        title: 'HOME',
+        subtitle: 'HOME_SUB',
+        template: 'page',
+        categories: [
+          { name: '重复 分类', icon: 'fas fa-tag', sites: [] },
+          { name: '重复 分类', icon: 'fas fa-tag', sites: [] },
+        ],
+      },
+    };
+
+    const html = generateHTML(config);
+
+    assert.ok(html.includes('class="submenu-item"'), '应输出子菜单项');
+    assert.ok(html.includes('href="?page=home#重复-分类"'), '子菜单 href 应支持 ?page=<id>#<slug>');
+    assert.ok(html.includes('data-category-id="重复-分类"'), '子菜单应携带 data-category-id');
+    assert.ok(html.includes('class="nav-item'), '应输出导航项');
+    assert.ok(html.includes('href="?page=home"'), '导航项 href 应支持 ?page=<id> 深链接');
+  });
+});
diff --git a/test/p1-7-extension-config-minimal.node-test.js b/test/p1-7-extension-config-minimal.node-test.js
new file mode 100644
index 0000000000000000000000000000000000000000..81c4ee3a9a71b5e4086fd2d0c273fb1b076e9e0b
--- /dev/null
+++ b/test/p1-7-extension-config-minimal.node-test.js
@@ -0,0 +1,53 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const { loadHandlebarsTemplates, loadConfig, generateHTML } = require('../src/generator.js');
+
+function withRepoRoot(fn) {
+  const originalCwd = process.cwd();
+  process.chdir(path.join(__dirname, '..'));
+  try {
+    return fn();
+  } finally {
+    process.chdir(originalCwd);
+  }
+}
+
+test('P1-7：页面内不应注入整站 configJSON，应仅保留扩展元信息与最小运行时参数', () => {
+  withRepoRoot(() => {
+    loadHandlebarsTemplates();
+    const config = loadConfig();
+    const html = generateHTML(config);
+
+    const match = html.match(/<script id="menav-config-data"[^>]*>([\s\S]*?)<\/script>/m);
+    assert.ok(match, '应输出 menav-config-data 脚本块');
+
+    const raw = String(match[1] || '').trim();
+    assert.ok(raw.length > 0, 'menav-config-data 内容不应为空');
+
+    const parsed = JSON.parse(raw);
+
+    assert.ok(parsed && typeof parsed === 'object');
+    assert.equal(parsed.configUrl, './menav-config.json');
+    assert.ok(parsed.version, '应包含 version');
+    assert.ok(parsed.timestamp, '应包含 timestamp');
+
+    assert.ok(parsed.icons && typeof parsed.icons === 'object', '应包含 icons 配置（用于运行时）');
+
+    assert.ok(parsed.data && typeof parsed.data === 'object', '应包含 data 对象');
+    assert.ok(parsed.data.homePageId, '应包含 homePageId');
+    assert.ok(
+      parsed.data.pageTemplates && typeof parsed.data.pageTemplates === 'object',
+      '应包含 pageTemplates'
+    );
+
+    // 不应再把 pages/<id>.yml 的完整结构（categories/sites 等）注入到页面中
+    assert.equal(parsed.data.common, undefined);
+    assert.equal(parsed.data.projects, undefined);
+    assert.equal(parsed.data.articles, undefined);
+    assert.equal(parsed.data.bookmarks, undefined);
+    assert.ok(!/"categories"\s*:/.test(raw), '不应包含 categories 字段');
+    assert.ok(!/"sites"\s*:/.test(raw), '不应包含 sites 字段');
+  });
+});
diff --git a/test/sidebar-submenu-panel-and-theme-mode.node-test.js b/test/sidebar-submenu-panel-and-theme-mode.node-test.js
new file mode 100644
index 0000000000000000000000000000000000000000..a8a5c1b91fd5bc303b65729c6891ef5763dd76fb
--- /dev/null
+++ b/test/sidebar-submenu-panel-and-theme-mode.node-test.js
@@ -0,0 +1,69 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+test('默认布局：应包含侧边栏分类面板容器（避免子菜单过长挤压页面列表）', () => {
+  const repoRoot = path.resolve(__dirname, '..');
+  const layoutPath = path.join(repoRoot, 'templates', 'layouts', 'default.hbs');
+  const content = fs.readFileSync(layoutPath, 'utf8');
+
+  assert.ok(
+    content.includes('sidebar-submenu-panel'),
+    'templates/layouts/default.hbs 应包含 sidebar-submenu-panel 容器'
+  );
+  assert.ok(
+    content.includes('data-container="sidebar-submenu"'),
+    'sidebar-submenu-panel 容器应包含 data-container="sidebar-submenu"'
+  );
+});
+
+test('默认布局：应输出 data-theme-mode，支持 dark/light/system 默认模式', () => {
+  const repoRoot = path.resolve(__dirname, '..');
+  const layoutPath = path.join(repoRoot, 'templates', 'layouts', 'default.hbs');
+  const content = fs.readFileSync(layoutPath, 'utf8');
+
+  assert.ok(
+    content.includes('data-theme-mode='),
+    'templates/layouts/default.hbs 应输出 data-theme-mode 属性'
+  );
+});
+
+test('侧边栏样式：收起时不应在页面按钮下方显示目录子菜单', () => {
+  const repoRoot = path.resolve(__dirname, '..');
+  const sidebarStylePath = path.join(repoRoot, 'assets', 'styles', '_sidebar.css');
+  const content = fs.readFileSync(sidebarStylePath, 'utf8');
+
+  assert.ok(
+    content.includes('.sidebar.collapsed .nav-item-wrapper > .submenu'),
+    'assets/styles/_sidebar.css 应在收起态隐藏 nav-item-wrapper 下的 submenu'
+  );
+  assert.match(
+    content,
+    /\.sidebar\.collapsed \.nav-item-wrapper > \.submenu\s*\{[^}]*display:\s*none;/m,
+    '收起态的 submenu 应明确设置为 display: none'
+  );
+});
+
+test('侧边栏目录面板：应默认隐藏，并通过独立状态类延后淡入', () => {
+  const repoRoot = path.resolve(__dirname, '..');
+  const sidebarStylePath = path.join(repoRoot, 'assets', 'styles', '_sidebar.css');
+  const uiPath = path.join(repoRoot, 'src', 'runtime', 'app', 'ui.js');
+  const styleContent = fs.readFileSync(sidebarStylePath, 'utf8');
+  const uiContent = fs.readFileSync(uiPath, 'utf8');
+
+  assert.match(
+    styleContent,
+    /\.sidebar-submenu-panel\s*\{[\s\S]*opacity:\s*0;[\s\S]*visibility:\s*hidden;/m,
+    '目录面板默认应处于隐藏状态'
+  );
+  assert.match(
+    styleContent,
+    /\.sidebar\.submenu-panel-visible \.sidebar-submenu-panel:not\(:empty\)\s*\{[\s\S]*opacity:\s*1;[\s\S]*visibility:\s*visible;/m,
+    '目录面板应通过 submenu-panel-visible 状态类显现'
+  );
+  assert.ok(
+    uiContent.includes('submenu-panel-visible'),
+    'src/runtime/app/ui.js 应控制 submenu-panel-visible 状态类'
+  );
+});
diff --git a/test/template-diff-phase1.node-test.js b/test/template-diff-phase1.node-test.js
new file mode 100644
index 0000000000000000000000000000000000000000..759fc2c66a77e54ea415ec09d23231758797d753
--- /dev/null
+++ b/test/template-diff-phase1.node-test.js
@@ -0,0 +1,359 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const { loadHandlebarsTemplates, generateAllPagesHTML } = require('../src/generator.js');
+
+function withRepoRoot(fn) {
+  const originalCwd = process.cwd();
+  process.chdir(path.join(__dirname, '..'));
+  try {
+    return fn();
+  } finally {
+    process.chdir(originalCwd);
+  }
+}
+
+test('friends/articles：应恢复分类展示（扩展仍以 data-* 结构为准）', () => {
+  withRepoRoot(() => {
+    loadHandlebarsTemplates();
+
+    const config = {
+      site: { title: 'Test Site', description: '', author: '', favicon: '', logo_text: 'Test' },
+      profile: { title: 'PROFILE_TITLE', subtitle: 'PROFILE_SUBTITLE' },
+      social: [],
+      navigation: [
+        { id: 'home', name: '首页', icon: 'fas fa-home' },
+        { id: 'friends', name: '朋友', icon: 'fas fa-users' },
+        { id: 'articles', name: '文章', icon: 'fas fa-book' },
+      ],
+      home: { title: 'HOME', subtitle: 'HOME_SUB', template: 'page', categories: [] },
+      friends: {
+        title: '友情链接',
+        subtitle: '朋友们',
+        template: 'page',
+        categories: [
+          {
+            name: '技术博主',
+            icon: 'fas fa-user-friends',
+            sites: [
+              {
+                name: 'Example',
+                url: 'https://example.com',
+                icon: 'fas fa-link',
+                description: 'desc',
+              },
+            ],
+          },
+        ],
+      },
+      articles: {
+        title: '文章',
+        subtitle: '文章入口',
+        template: 'articles',
+        categories: [
+          {
+            name: '最新文章',
+            icon: 'fas fa-pen',
+            sites: [
+              {
+                name: 'Article A',
+                url: 'https://example.com/a',
+                icon: 'fas fa-link',
+                description: 'summary',
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    const pages = generateAllPagesHTML(config);
+
+    assert.ok(typeof pages.friends === 'string' && pages.friends.length > 0);
+    assert.ok(pages.friends.includes('page-template-friends'));
+    assert.ok(pages.friends.includes('sites-grid'));
+    assert.ok(
+      pages.friends.includes('class="site-card'),
+      'friends 应使用普通 site-card 样式（图标在左，标题在右）'
+    );
+    assert.ok(
+      !pages.friends.includes('site-card-friend'),
+      'friends 不应使用 site-card-friend 变体样式'
+    );
+    assert.ok(pages.friends.includes('category-header'), 'friends 应输出分类标题结构');
+
+    assert.ok(typeof pages.articles === 'string' && pages.articles.length > 0);
+    assert.ok(pages.articles.includes('page-template-articles'));
+    assert.ok(pages.articles.includes('sites-grid'));
+    assert.ok(
+      pages.articles.includes('class="site-card'),
+      'articles 应使用普通 site-card 样式（图标在左，标题在右）'
+    );
+    assert.ok(
+      !pages.articles.includes('site-card-article'),
+      'articles 不应使用 site-card-article 变体样式'
+    );
+    assert.ok(pages.articles.includes('category-header'), 'articles 应输出分类标题结构');
+  });
+});
+
+test('friends/articles：页面配置使用顶层 sites 时应自动映射为分类容器', () => {
+  withRepoRoot(() => {
+    loadHandlebarsTemplates();
+
+    const config = {
+      site: { title: 'Test Site', description: '', author: '', favicon: '', logo_text: 'Test' },
+      profile: { title: 'PROFILE_TITLE', subtitle: 'PROFILE_SUBTITLE' },
+      social: [],
+      navigation: [
+        { id: 'home', name: '首页', icon: 'fas fa-home' },
+        { id: 'friends', name: '朋友', icon: 'fas fa-users' },
+        { id: 'articles', name: '文章', icon: 'fas fa-book' },
+      ],
+      home: { title: 'HOME', subtitle: 'HOME_SUB', template: 'page', categories: [] },
+      friends: {
+        title: '友情链接',
+        subtitle: '朋友们',
+        template: 'page',
+        sites: [
+          { name: 'Example', url: 'https://example.com', icon: 'fas fa-link', description: 'desc' },
+        ],
+      },
+      articles: {
+        title: '文章',
+        subtitle: '文章入口',
+        template: 'articles',
+        sites: [
+          {
+            name: 'Article A',
+            url: 'https://example.com/a',
+            icon: 'fas fa-link',
+            description: 'summary',
+          },
+        ],
+      },
+    };
+
+    const pages = generateAllPagesHTML(config);
+
+    assert.ok(typeof pages.friends === 'string' && pages.friends.length > 0);
+    assert.ok(pages.friends.includes('page-template-friends'));
+    assert.ok(pages.friends.includes('sites-grid'));
+    assert.ok(
+      pages.friends.includes('class="site-card'),
+      'friends 应使用普通 site-card 样式（图标在左，标题在右）'
+    );
+    assert.ok(
+      !pages.friends.includes('site-card-friend'),
+      'friends 不应使用 site-card-friend 变体样式'
+    );
+    assert.ok(pages.friends.includes('category-header'), 'friends 应输出分类标题结构');
+
+    assert.ok(typeof pages.articles === 'string' && pages.articles.length > 0);
+    assert.ok(pages.articles.includes('page-template-articles'));
+    assert.ok(pages.articles.includes('sites-grid'));
+    assert.ok(
+      pages.articles.includes('class="site-card'),
+      'articles 应使用普通 site-card 样式（图标在左，标题在右）'
+    );
+    assert.ok(
+      !pages.articles.includes('site-card-article'),
+      'articles 不应使用 site-card-article 变体样式'
+    );
+    assert.ok(pages.articles.includes('category-header'), 'articles 应输出分类标题结构');
+  });
+});
+
+test('缺少 friends 页面配置时：仍应渲染页面（标题回退为导航名称）', () => {
+  withRepoRoot(() => {
+    loadHandlebarsTemplates();
+
+    const config = {
+      site: { title: 'Test Site', description: '', author: '', favicon: '', logo_text: 'Test' },
+      profile: { title: 'PROFILE_TITLE', subtitle: 'PROFILE_SUBTITLE' },
+      social: [],
+      navigation: [
+        { id: 'home', name: '首页', icon: 'fas fa-home' },
+        { id: 'friends', name: '朋友', icon: 'fas fa-users' },
+      ],
+      home: { title: 'HOME', subtitle: 'HOME_SUB', template: 'page', categories: [] },
+      // 刻意不提供 friends 配置
+    };
+
+    const pages = generateAllPagesHTML(config);
+    const html = pages.friends;
+
+    assert.ok(typeof html === 'string' && html.length > 0);
+    assert.ok(html.includes('page-template-friends'));
+    assert.ok(html.includes('data-editable="page-title"'));
+    assert.ok(html.includes('朋友'));
+  });
+});
+
+test('bookmarks：标题区应显示内容更新时间（日期 + 来源）', () => {
+  withRepoRoot(() => {
+    loadHandlebarsTemplates();
+
+    const config = {
+      site: { title: 'Test Site', description: '', author: '', favicon: '', logo_text: 'Test' },
+      profile: { title: 'PROFILE_TITLE', subtitle: 'PROFILE_SUBTITLE' },
+      social: [],
+      navigation: [
+        { id: 'home', name: '首页', icon: 'fas fa-home' },
+        { id: 'bookmarks', name: '书签', icon: 'fas fa-bookmark' },
+      ],
+      home: { title: 'HOME', subtitle: 'HOME_SUB', template: 'page', categories: [] },
+      bookmarks: { title: '书签', subtitle: '书签页', template: 'bookmarks', categories: [] },
+    };
+
+    const pages = generateAllPagesHTML(config);
+    const html = pages.bookmarks;
+
+    assert.ok(typeof html === 'string' && html.length > 0);
+    assert.ok(html.includes('page-updated-inline'));
+    assert.ok(html.includes('update:'), '应显示 update: 前缀');
+    assert.ok(html.includes('from:'), '应显示 from: 前缀');
+    assert.ok(/update:\s*\d{4}-\d{2}-\d{2}/.test(html), '应显示 YYYY-MM-DD 日期');
+    assert.ok(/from:\s*(git|mtime)/.test(html), '应显示来源（git|mtime）');
+  });
+});
+
+test('projects：应输出代码仓库风格卡片（site-card-repo）', () => {
+  withRepoRoot(() => {
+    loadHandlebarsTemplates();
+
+    const config = {
+      site: { title: 'Test Site', description: '', author: '', favicon: '', logo_text: 'Test' },
+      profile: { title: 'PROFILE_TITLE', subtitle: 'PROFILE_SUBTITLE' },
+      social: [],
+      navigation: [{ id: 'projects', name: '项目', icon: 'fas fa-project-diagram' }],
+      projects: {
+        title: '项目',
+        subtitle: '项目页',
+        template: 'projects',
+        categories: [
+          {
+            name: '项目',
+            icon: 'fas fa-code',
+            sites: [
+              {
+                name: 'Proj',
+                url: 'https://example.com',
+                icon: 'fas fa-link',
+                description: 'desc',
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    const pages = generateAllPagesHTML(config);
+    const html = pages.projects;
+
+    assert.ok(typeof html === 'string' && html.length > 0);
+    assert.ok(html.includes('page-template-projects'), 'projects 应包含模板容器 class');
+    assert.ok(html.includes('sites-grid'), 'projects 应包含网格容器（sites-grid）');
+    assert.ok(html.includes('site-card-repo'), 'projects 应包含代码仓库风格卡片类');
+  });
+});
+
+test('articles Phase 2：存在 RSS 缓存时渲染文章条目，并隐藏扩展写回结构', () => {
+  withRepoRoot(() => {
+    loadHandlebarsTemplates();
+
+    const previousCacheDir = process.env.RSS_CACHE_DIR;
+    const tmpCacheDir = fs.mkdtempSync(path.join(os.tmpdir(), 'menav-rss-cache-'));
+    process.env.RSS_CACHE_DIR = tmpCacheDir;
+
+    const cachePath = path.join(tmpCacheDir, 'articles.feed-cache.json');
+    fs.writeFileSync(
+      cachePath,
+      JSON.stringify(
+        {
+          version: '1.0',
+          pageId: 'articles',
+          generatedAt: '2025-12-26T00:00:00.000Z',
+          articles: [
+            {
+              title: 'Article A',
+              url: 'https://example.com/a',
+              summary: 'summary',
+              publishedAt: '2025-12-25T12:00:00.000Z',
+              source: 'Example Blog',
+              sourceUrl: 'https://example.com',
+              icon: 'fas fa-pen',
+            },
+          ],
+          stats: { totalArticles: 1 },
+        },
+        null,
+        2
+      )
+    );
+
+    try {
+      const config = {
+        site: { title: 'Test Site', description: '', author: '', favicon: '', logo_text: 'Test' },
+        profile: { title: 'PROFILE_TITLE', subtitle: 'PROFILE_SUBTITLE' },
+        social: [],
+        navigation: [
+          { id: 'home', name: '首页', icon: 'fas fa-home' },
+          { id: 'articles', name: '文章', icon: 'fas fa-book' },
+        ],
+        home: { title: 'HOME', subtitle: 'HOME_SUB', template: 'page', categories: [] },
+        articles: {
+          title: '文章',
+          subtitle: '文章入口',
+          template: 'articles',
+          categories: [
+            {
+              name: '来源',
+              icon: 'fas fa-pen',
+              sites: [
+                {
+                  name: 'Source A',
+                  url: 'https://example.com',
+                  icon: 'fas fa-link',
+                  description: 'desc',
+                },
+              ],
+            },
+          ],
+        },
+      };
+
+      const pages = generateAllPagesHTML(config);
+      const html = pages.articles;
+
+      assert.ok(typeof html === 'string' && html.length > 0);
+      assert.ok(
+        html.includes('data-type="article"'),
+        '文章条目卡片应为 data-type="article"（只读）'
+      );
+      assert.ok(html.includes('site-card-meta'), '文章条目应展示日期/来源元信息');
+      assert.ok(html.includes('Example Blog'));
+      assert.ok(html.includes('2025-12-25'));
+      assert.match(
+        html,
+        /<section class="category category-level-1 category-readonly">[\s\S]*?来源[\s\S]*?Article A[\s\S]*?<\/section>/,
+        '文章条目应按页面配置分类聚合展示'
+      );
+      assert.ok(html.includes('data-extension-shadow="true"'), '应保留隐藏的扩展写回结构');
+      assert.ok(html.includes('data-search-exclude="true"'), '扩展影子结构应排除搜索索引');
+    } finally {
+      try {
+        fs.rmSync(tmpCacheDir, { recursive: true, force: true });
+      } finally {
+        if (previousCacheDir === undefined) {
+          delete process.env.RSS_CACHE_DIR;
+        } else {
+          process.env.RSS_CACHE_DIR = previousCacheDir;
+        }
+      }
+    }
+  });
+});