blog/docs/博客重设计调研报告.md

# 博客重设计 · 调研报告（供审阅）

> 2026-10-24 ｜ 主会话综合三路侦察（子 agent：现状诊断+极简标杆 / 获奖创意站 / 中文排版）+ 主会话架构调研
> 原始报告：`docs/research/01-现状诊断与极简开发者风标杆.md`、`02-获奖创意站研究.md`、`03-中文排版与阅读体验.md`（所有结论基于实抓 HTML/CSS/截图，非印象推测）

---

## 0. TL;DR

1. **不喜欢 higan 的原因找到了，且可量化**：它根本不是为中文长文设计的——版心 1024px（每行 60+ 汉字，远超 35–45 舒适区）、16px 小字、中文零字体设计（系统黑体兜底）、引文整段加粗、出厂蓝紫配色未定制、10 项平级导航过载。
2. **内容决定气质**：博客是「阅读（书评）× 技术（Linux · coding · 技术分享）× 摄影」三内容线 + 瞬间生活流（2026-10-24 确认）。视觉主推 **丙：极简灰阶骨架 × 分轨正文**（已审阅样板认可）。
3. **设计哲学升级（2026-10-24 用户定调）**：**「既要有艺术文学的美观，又要有极客的精神蕴含其中」**——丙的灰阶骨架×分轨正文提供艺术层，新增「开源极客层」：命令面板、键盘导航、终端彩蛋、贡献热力图、构建透明化、开源项目墙（详见 §4c）；博客本身在 gitea 开源。
4. **照片模块新需求**：要有上传管理界面 + 图库按照片宽高比自适应——管线方案见 §4b，组件方案 = CSS Grid + 构建时 aspect-ratio 驱动的 masonry（零运行时 JS）。
3. **架构推荐 A 或 B**（都保留 Halo）：A = 给 Halo 写全新自定义主题（写作流不变、发布即生效）；B = Halo 当 headless CMS + Astro 前端（设计自由度最大、性能最好，代价是多一条构建链）。C（弃 Halo 纯静态）不推荐——会毁掉你现有的 Console 写作流和评论/瞬间/图库数据。
4. **红线先立好**：ICP 页脚保留、URL 结构不变、生产容器与数据不动（开发用独立实例）、切换前备份、动效全部包 `prefers-reduced-motion`、中文不上全量 webfont。

---

## 1. 现状诊断：为什么不喜欢它

实测（截图 + CSS 源码双重验证，higan v1.64.1）：

| # | 问题 | 实测证据 |
|---|------|---------|
| 1 | **版心过宽，行长失控** | `.max-width: 64rem`（1024px）× 16px 字号 → 桌面每行约 60–64 汉字，舒适区是 35–45 字（KAIX.IN 36 字 / 太隐 42 字） |
| 2 | **中文零字体设计** | CSS 无任何中文 @font-face，`Meslo LG S` 只覆盖拉丁分片，汉字全靠系统抽奖（苹方/雅黑/文泉驿），文学气质为零 |
| 3 | **字号偏小** | 正文 16px；标杆站阅读模式 18–20px（CRIVU 20px / 太隐 18px / KAIX 大屏 18px） |
| 4 | **出厂配色未定制** | `#66ccff` 天蓝 + `#c5b6ff` 淡紫就是主题默认值（theme 名 `auto-blue`），一屏 ≥4 种强调色平铺，无主次 |
| 5 | **导航过载** | 10 个平级入口 + 竖线分隔（2010 年代范式），「登录」外露破坏作品感；标杆站全部 ≤4 项或 icon 化 |
| 6 | **引文样式反文学** | blockquote 整段加粗——长书摘可读性差，higan 的 cite 方案可用但要去掉加粗 |
| 7 | **布局重心失衡** | 内容列偏左（起于 19% 处），右侧空白无设计承接；标杆站全部是真正居中的 640–720px 窄栏 |
| 8 | **列表信息过载** | 日期/分类/标签/浏览量/摘要/阅读全文六类信息平铺，浏览量「42」外露是后台思维 |
| 9 | **字体质感与内容错位** | 摘要呈等宽字体观感（CJK 回退 + latin mono 混排），节奏生硬；书评和 Linux 笔记视觉上零区分 |
| 10 | **品牌感弱** | 黑底方块头像与 #fafafa 硬冲突，首屏没有一句有性格的自我介绍 |

**结论**：问题不在工程实现（higan 工程质量不差），在于它不是为「中文长文阅读」设计的。重设计第一决策 = **字号–行高–行长三角**，不是配色。

---

## 2. 设计方向：三选一（或推荐混搭）

### 路线甲：纸墨书卷风（KAIX.IN / CRIVU 系）
- 米白纸底 `#F6F5F3`、正文衬线（宋体栈）、墨线/墨绿点缀、两端对齐、36 字窄版心
- 最贴文学书评气质；缺点：默认无暗色、现代感弱、Linux 技术内容会显得「穿越」

### 路线乙：极简灰阶风（antfu / brianlovin / paco 系）
- 白/蓝黑双底、四级灰阶层级、icon-only 导航、按年分组纯文字流、衬线正文 + 无衬线 UI 双字体制
- 现代工程师气质；缺点：直接用会丢掉书卷气，书评内容显得冷

### 路线丙（**推荐**）：骨架乙 × 正文分轨 的混搭（三内容线版）
- **UI 骨架**（导航/列表/页脚）：极简灰阶 + 单强调色 + ≤4 项导航（文章/图库/关于/搜索 + icon 社交），登录/瞬间收进角落
- **正文按内容线分轨**：
  - 书评 = 衬线宋体栈、20px/1.75/720px 版心、纸色底、**每篇一个情绪色**（overreacted 每文一色，列表即画廊）+ 虚线批注框引文（julesforrest 批注气质）
  - 技术文（Linux/coding/分享）= 无衬线正文 + 暗色终端风代码块（黑底等宽 + `>` 前缀，cassie.codes 手法）+ Shiki 双主题高亮
  - 摄影图文 = image-first 版式（大图/双图并排/全幅断点图），图片优先排版，文字为图服务
- **列表页**：leerob 式「标题 + 日期」两栏对齐 + 按年分组（antfu）+ 按内容线内部分节（阅读/技术/摄影），书评行带情绪色小标、技术行带 mono 标签、摄影行带缩略图
- **图库页**（摄影主场）：影像墙（masonry 或规整网格）+ 分组 + EXIF（Halo 图库插件自动读取）+ lightbox 大图浏览
- **首页**：brianlovin 名片式开场（头像 + 一句身份陈述）+ 分节：最近写作 / 最新影像一格（图库入口）

### 获奖站的「降维」点缀（按性价比，全部 Tier 1/2）
1. 阅读进度条 + 章节导航（阅读增强）
2. 全站一支缓动曲线 + 一个时长（0.35s + easeOutExpo 系）——动效纪律
3. CSS marquee「最近更新」横条（The Lookback，可暂停）
4. noise 噪点纸纹覆盖层（`steps(2)` keyframes，纸质颗粒感，近零成本）
5. 入场错峰滑入（antfu slide-enter，纯 CSS）
6. 彩蛋页（终端风 `/terminal` 或 90s 皮肤，pedro 时间机器降维）
7. **明确不做**：3D/WebGL 世界（bruno 路线，判定：不适合读字）、纯 CSR 壳（SEO 自杀）、逐字母大字标、自动播放视频、自定义正文光标

---

## 3. 中文排版参数（可直接开工，全部有实测依据）

```
书评正文：    20px / 1.75 / max-width 720px（≈36 汉字）
技术文正文：  19px / 1.7 / 同版心；内联 code 等宽 0.875em
代码块：      16px / 1.6 / overflow-x: auto / 禁 break-all / Shiki 双主题变量
衬线栈：      Georgia, "Iowan Old Style", "Songti SC", STSong,
              "Noto Serif CJK SC", "Source Han Serif SC", SimSun, serif
              （思源宋必须排在 Windows 老宋体前面）
sans 栈：     system-ui, -apple-system, "PingFang SC", "Hiragino Sans GB",
              "Microsoft YaHei", "Noto Sans SC", sans-serif
段落：        无首行缩进 + 段间距 0.9em；标题 text-wrap: balance，中文零字距
标题字阶：    文章题 27px / 章节 22px / h3 19px / 行高 1.3
暗色：        底 #191d23 蓝黑系 / 字 #f0f0ef 系 / color-scheme: dark 声明
              图片降亮度、::selection 半透明、代码双主题免重排
引文组件：    长书摘 = 1px 墨线左框 + muted 色（学术极简）；
              金句 = 62px 巨型 " 水印 + 0.96em；
              出处行 0.875rem muted + "——" 前缀 + 《》
混排：        中英文/数字间手敲空格（写作规范）+ text-autospace 渐进增强
标点：        弯引号 "" ''；避头尾靠浏览器默认（禁用 break-all 即可）；行尾点号悬挂不必做
```

**字体策略（2026-10-24 定案：自托管分片 webfont，响应「跨平台一致 + 艺术美观」需求）**：

| 轨道 | 字体 | 许可 |
|---|---|---|
| 书评正文 | **霞鹜文楷 LXGW WenKai（Screen 屏读优化版）**，楷体气质、文学感最强；若实际长读偏软，备选思源宋体 Noto Serif SC | OFL |
| UI / 技术文 | **思源黑体 Noto Sans SC**，现代中性 | OFL |
| 代码 | **JetBrains Mono**（仅拉丁子集，极小） | OFL |

- **分发**：`cn-font-split`（中文网字计划）→ **官方支持 Astro/Vite**（vite-plugin-font，实抓：按需加载、按实际用字优化首屏、纯 CSS 零运行时、自动减 CLSS）→ 分片 woff2 **自托管**于 /fonts/（哈希名 + immutable + ESA 缓存），零第三方依赖，与 gitea/Artalk 同一数据自控哲学
- 体积事实：中文原字 5-10MB，分片后按 unicode-range 按需拉，首屏典型几百 KB，后续命中缓存；`font-display: swap` 防白屏
- 样板 v2 用的是系统字体（零依赖约束），文楷/思源的真实笔触要到真实构建时才能感受到

---

## 4. 功能清单

### P0（必须有）
- 明暗模式：自动跟随系统 + 手动切换 + 不闪烁（paco 的 `prefers-color-scheme` 是底线，antfu 的 class 切换+记忆是增强）
- 文章页：目录 TOC、阅读进度条、阅读时长、代码高亮（Shiki 双主题）、引文组件、脚注支持
- 列表页：按年分组、按内容线（阅读/技术/摄影）分轨呈现、去掉浏览量外露
- **图库页**（摄影是核心兴趣，从 P1 提升）：影像墙 + 分组 + EXIF + lightbox；Halo 图库插件有公共 REST API 且自动读 EXIF
- 归档 / 分类 / 标签页、RSS（Halo 自带）、搜索（Halo 搜索插件，匿名 API）
- 移动端适配（中文读者主力是手机）
- ICP 备案页脚（陕ICP备2026014860号-1 → beian.miit.gov.cn）
- 性能：Lighthouse ≥90；图片懒加载 + 缩略图（Halo thumbnail Finder）+ blur-up 占位；不上全量中文字体

### 4c-旧框架占位（内容已并入下方正式版）

<!-- 旧框架版已删除：交互项并入正式版表格；内容丰富化独有条目：关于页 /now+/stack+/colophon、书评索引页（二期：书封+情绪色+一句话画廊网格）、摄影图文模板（image-first 大图/并排/全幅断点图） -->

### P1（最好有）
- 瞬间页（现有 1 条，公共 REST API；摄影快照 + 生活流，可做瀑布流时间线）
- 摄影文章模板：image-first 图文志版式（大图/并排/全幅断点图组件）
- 关于页：名片式重写（一句身份陈述 + 兴趣版图时间线）
- 阅读字号切换 dock（CRIVU reading-dock 模式）
- 相关文章、OG 图自动生成、404 彩蛋

### P2（锦上添花，可砍）
- marquee 最近更新、噪点纸纹、终端彩蛋页、书评索引网格页（年代/分类筛选）

### 功能红线
- 评论：详见 §4a 论证——**结论：Artalk 首选**（完全自托管、Go 单二进制+sqlite、管理后台三强最完善、维护活跃）；Waline 备选（生态最大）；Giscus 需 GitHub 登录排除；Twikoo 维护放缓淘汰
- 瞬间/相册/链接：视为可选增强设计，未启用时不留死导航（随架构 C''，这三项改为自建 collection 实现）

### 4a. 评论系统论证（2026-10-24，基于实测评价源交叉验证）

选型轴 = 你拍 gitea 的同一价值观：**数据可控、全自托管、最少外部依赖**。

| 维度 | **Artalk（首选）** | Waline（备选） | Twikoo（淘汰） |
|---|---|---|---|
| 技术形态 | Go 单二进制服务端 + 40KB 原生 JS 客户端（无框架） | Node.js 服务端 | Node.js 服务端 |
| 存储 | SQLite（最省）/MySQL/PG，站点隔离 | SQLite/PG/MySQL | **json 文件**（默认），查询/关联弱 |
| 数据自控 | ★★★ 完全自托管，导出完善，多站点隔离（未来可扩第二个站） | ★★ 自托管但后台账户管理弱（实测吐槽：邮箱改不了、空账户删不掉） | ★★ 文件备份直观 |
| 管理后台 | 三强最完善：现代 UI + 多站点 + **通知中心**（邮件之外多一层站内提醒） | 有但简单 | 中规中矩（评论区登录进面板） |
| 匿名中文读者 | ✅ 匿名+昵称邮箱+Gravatar；IP 属地显示需自下 GeoIP 库（可选项） | ✅ 匿名+表情；图片上传转 base64 存库是实测痛点 | ✅ 且有 QQ 号自动补全昵称头像（唯一亮点） |
| 防垃圾 | 验证码/频控/敏感词/审核 | 内置反垃圾 + IP 限速（这块最成熟） | 基础 |
| 维护活跃 | 持续发版（GitHub ArtalkJS/Artalk） | 活跃（lizheming） | 近年放缓 |
| 迁移双向 | 支持导入 Waline/Twikoo（将来退出成本低） | 支持导入 | 支持导入 |

**判定**：Artalk 与 gitea 同价值观（单容器 + sqlite 卷挂载 + nginx 反代一个路径，与现有基建零冲突）；Waline 在「生态最大/反垃圾最成熟」上占优，若你更看重社区规模可换；Twikoo 的 json 存储与维护状态不推荐。风险对冲：Artalk 若停更，数据可导出迁往 Waline，锁死风险低。（2026-10-24 用户已确认按此建议执行 ✅）

### 4b. 照片上传与管理管线（2026-10-24，证据见 docs/research/04，全部实抓源码/API spec）

用户需求：照片要有上传**管理界面**，且图库组件按照片宽高比自适应。

**关键实测发现**：
- gitea web 上传页实存（dropzone 拖拽+多文件，源码 `templates/repo/editor/upload.tmpl` 实抓）；默认限单次 5 文件/50MB，`[repository.upload]` 可调；API 侧 `POST /repos/{owner}/{repo}/contents` 支持**多文件一次 commit**（swagger 实抓）
- Astro `astro:assets` 默认 sharp，构建时自动出多尺寸缩略图 + srcset，**ImageMetadata 含 width/height，orientation≥5 时自动交换**（竖片宽高比正确，源码实抓）——masonry 的 aspect-ratio 数据源零成本；但相机/镜头/光圈等 EXIF 需 `exifr`（零依赖 npm 包）补 ~20 行
- **Sveltia CMS**（★2990，2026-10 仍活跃）：Netlify/Decap 后继，纯前端零运维，**Gitea 后端是一等公民**（源码目录 gitea/github/gitlab 并列实锤）——媒体库上传 + frontmatter 编辑开箱即用；风险：Gitea 后端较新（10-01 刚修过兼容 bug），需真机验收
- Immich API 直出全套 EXIF（含镜头/GPS），但数据不在 git + 全家桶运维重——仅当本来就部署 Immich 才值
- 自托管图床（Lychee/Chevereto/EasyImages）：版本控制缺失、图床误删→博客静默坏图，不推荐

**定案分阶段路径**：
1. **阶段 0（当天可用）**：照片入 git 仓（gitea web 拖拽，MAX_FILES 调 20+）→ 构建时 exifr 提 EXIF + sharp 出缩略图 + 宽高比驱动 masonry（零运行时 JS）
2. **阶段 1（要管理界面时）**：先试 **Sveltia CMS**（零新运维组件）→ 不合手再自写 **photo-pipe** 小服务（上传→EXIF+缩略图→元数据表单→gitea contents API 一次 commit→webhook 构建，PWA 手机可拍照直传；**作为独立开源项目发布**——热爱开源的最自然表达，且任何时刻可退回纯手工流程）

**图库自适应（masonry）**：CSS Grid + `grid-auto-rows: 8px` + 构建时由照片 width/height（含 orientation 修正）算 aspect-ratio + row-span → 零运行时 JS 的真·按片自适应；lightbox 用原生 `<dialog>` + 键盘导航（样板 v2 已可预览）。

### 4c. 开源极客层：案例与实现（2026-10-24，证据见 docs/research/05，全部实抓验证）

设计哲学：**艺术层（丙视觉+分轨正文）打底，极客层由「等宽字神经系统」承担**——两者不抢戏。样板 v2 已全部可交互预览。

| 级别 | 项 | 实现 | 工作量 | 关键实证 |
|---|---|---|---|---|
| P0 | 键盘基础集：`/` 搜索、`?` 帮助、`t` 主题、`g h/e/t/g` 导航 | 自写 vanilla（chord buffer） | ~120 行，半天 | GitHub 键位表逐字实抓 |
| P0 | 页脚构建信息（hash+时间→链 gitea commit） | vite.define 注入（CI 环境变量四重回退） | ~20 行，半小时 | sreetamdas/mldangelo 源码实抓 |
| P0 | View Transitions 页面转场 | `<ClientRouter />` + reduced-motion CSS | 半小时 | 三引擎全绿（caniuse 实抓） |
| P0 | 开源项目墙（**双源**：GitHub wait4xx + 自家 gitea，构建时并行 fetch 合并去重；pinned 手选 + star/语言/描述自动刷新，见下方分工说明） | 构建时 fetch 两家 GitHub 风格 API | ~80–120 行，半天 | gitea API 字段/CORS 实测；GitHub REST /users/{u}/repos 同构 |
| P1 | Ctrl+K 命令面板（搜索+动作聚合） | 自写 vanilla 模态 + Pagefind JS API（首次打开才懒加载） | ~200 行，一天 | Starlight Search.astro / spectre 模式实抓 |
| P1 | 贡献热力图 | **Gitea 原生 `/api/v1/users/{user}/heatmap` 端点**（双站 200 实测，CORS `*`）→ 构建时聚合 53×7 灰阶格 | ~120 行，一天 | 意外发现：原假设无此端点，实测坐实 |
| P2 | `/terminal` 终端彩蛋 | 自写命令 switch（codenerve 3KB 实证下限） | ~200 行，一天 | satnaing 824★ 同类 |
| P2 | 全 g-chords 体系扩展 | 扩 chord 表 | +30 行 | GitHub G+N/C/P 模式移植 |

**协同叙事闭环**：页脚 hash 与项目墙共享同一自托管 gitea 源；热力图数据也来自它——「这个博客本身是开源的」由三层元素互相印证；博客源码仓在 gitea 公开。

### 4d. 中英双语：全站实时切换（2026-10-24 新增需求，方案待认可）

需求：读者一键切换，全站内容（文章/瞬间/图库 caption/关于页/UI）即时变英文。

**推荐方案：构建时 LLM 预翻译 + 双语预构建**（「实时」由预构建达成——切换是毫秒级的 URL 跳转，无运行时翻译延迟、无运行时成本）

```
写作（中文）→ git push → 翻译管线（检测变更的 .zh.md → LLM 译出 .en.md 入仓）
→ astro build 双语全站（/ 原文 + /en/ 译文）→ 读者切语言 = 瞬时切 URL
```

| 关注点 | 方案 |
|---|---|
| 翻译执行器 | 你 homelab 已跑 **new-api 网关**（LLM API 中转）——翻译脚本走它调 GLM 等，**零新增服务** |
| 成本控制 | 译文以文件入仓：未改动的文章永不重译；一篇长文翻译成本分币级 |
| 质量策略 | AI 译稿 git 化 → 可随时人工润色（下次构建生效）；文学内容可选标注「AI 译文，欢迎指正」；润色过的段落可锁定不重译（frontmatter 标记） |
| 路由与 SEO | Astro 内置 i18n 路由（defaultLocale zh + /en/ 前缀）；hreflang 双向声明；双语 RSS/sitemap |
| UI 文案 | 中英字典（导航/页脚/按钮/阅读时长文案），Astro i18n 原生 |
| 评论 | Artalk 页面键设为同一 slug——中英页面共用一条评论流，不分裂 |
| 先例 | Astro 官方 i18n + content collections 双语配方；jangwoook.net 用 AI 辅助管线给 40 篇存量文章加中/英/日/韩多语（2025-11 实例） |

**为何不用运行时翻译**：第三方翻译挂件（translate.zvo.cn 类）质量不可控且引入外部依赖；运行时 LLM 翻译对公网访客开放 = 成本与滥用风险。预翻译两者皆无。

**降级容忍**：某篇未译（新建/失败）→ /en/ 侧回退中文原文并标注（Astro fallbackLocale），全站不因单篇失败阻塞构建。（2026-10-24 用户已认可方案 + AI 译文小标注 ✅）

### 4e. 多端适配规格（2026-10-24 新增硬性需求：桌面/平板/手机显示均无问题）

**原则：每个键盘能力都有触屏等价物**（快捷键是增强不是唯一入口）；移动端不是缩小版而是同一设计系统的响应式重排。

| 维度 | 规格 |
|---|---|
| 断点体系 | 与样板一致：≥1120 宽屏（TOC 侧栏常驻）/ 820 笔电/横屏（TOC 收起）/ 760 平板竖屏 / 560 手机；容器查询优先，媒体查询兜底 |
| 排版 | 桌面阅读 20px → 手机 18px（§3 已定）；版心随断点收缩；正文永不横向滚动（代码块独立 overflow-x） |
| 导航 | 桌面 ≤4 项横排 + icon 社交；手机同行紧凑排（不 hamburger 化——项少到不需要抽屉）；命令面板手机可见（浮层自适应软键盘） |
| 图库 masonry | 3 列 → 2 列（平板/手机）；lightbox 手机加左右滑动手势（桌面键盘 ←→） |
| 触屏 | 可点目标 ≥44×44px；safe-area-inset（刘海屏）；100dvh 代替 100vh（地址栏收缩 bug） |
| 明暗 | 跟随系统 + 手动切换；theme-color 双套 meta |
| 性能 | **Lighthouse 移动端 ≥90 同为验收线**；字体分片对手机流量友好；srcset + lazy + blur-up；JS 总量目标 <30KB |
| 实测矩阵 | Chrome/Firefox/Safari 桌面 + iOS Safari 真机 / Android Chrome 真机 / **微信内置浏览器**（中文读者主要入口：OG 卡片、字体分片、暗色逐项验）+ iPad Safari |
| 验收方式 | 每页型×每断点结构走查 + 真机抽检；上线前预发布域名全矩阵过一遍 |

---

## 5. 架构选项（2026-10-24 v1.2 重写：写作流是第一分叉变量）

> 用户实测反馈推翻了「Console 不动」前提：Halo 管理不够好用，**Markdown 支持不完善、中途不能换编辑器扩展**。这是结构性问题：Halo 文章创建时绑定编辑器，默认富文本存 HTML、插件编辑器各存各的格式，旧文换编辑器打开就乱——编辑器锁定是格式层的，不是设置能解决的。

### 第一分叉：你的理想写作流是哪种？

**（2026-10-24 用户已拍板：本地与浏览器都要能写）** → 架构定为 **C''：Astro SSG + git 仓为唯一事实源 + 双编辑入口**（见下节）

原分叉保留备查：
- 流 a（仅本地 markdown）→ C' Astro SSG
- 流 b（仅网页写作）→ A（Halo+自写主题，接受编辑器终身锁定）或 Ghost 二选一

### C''：双写作流方案（本地 + 浏览器都最优，2026-10-24 定案）

**核心思想：git 仓里的 markdown 文件是唯一事实源，两个编辑入口都写它。**

```
入口 1（本地）: VS Code / Obsidian / Cursor ──┐
                                              ├─→ git push → 构建 → 静态输出 → nginx → ESA → 读者
入口 2（浏览器）: GitHub web 编辑 / gitea web ──┘   （webhook/Actions，秒级完成）
```

| 需求 | 方案 |
|---|---|
| 本地写作 | 任意编辑器写 markdown + frontmatter，git push |
| 浏览器写作 | **GitHub 私库 web 编辑器**（github.dev 按 `.` 进入 VS Code Web，体验最佳，手机可用）或 **homelab 自建 gitea**（全自主、国内访问稳，web 编辑 + commit 够用） |
| 手机改错字 | GitHub mobile app / gitea 移动页编辑 md + commit |
| 发布链 | push → webhook/Actions → `astro build` → rsync 到 nginx 静态目录 → ESA 全站缓存 |
| 图库（21 张+EXIF） | content collection + 脚本批提 EXIF 进 frontmatter |
| 瞬间 | 短 markdown collection；可选 P2：homelab 上一个 mini 发布端点（手机 PWA 表单 → 服务端 commit + 触发构建），补齐「随手发」 |
| 评论 | **Artalk**（docker + sqlite 卷挂载，nginx 反代 /artalk；现有评论数=0，迁移成本≈0；论证见 §4a） |
| 搜索 | Pagefind（构建时索引） |
| RSS/OG/sitemap | Astro 官方集成 |

**为什么 Ghost 出局**：Ghost 的浏览器编辑器确实最佳，但它的真相源是自家数据库——本地 markdown 流只能靠 Admin API 脚本单向推，Ghost 里改的内容不回写 md 文件，**本地流是二等公民**，不满足「双流都最优」。

**诚实代价**：
1. 浏览器编辑体验是「够用」而非「最佳」（GitHub web 编辑 ≈ VS Code Web，比 Halo Console 略筒但比它可控）
2. 瞬间「随手发」默认要过 git（低频可忍；重度可用 P2 mini 端点补）
3. 图片进 git 仓库会变胖（git-lfs 或目录外挂可解）
4. 迁移工作量：6 文导出转 md、21 图搬目录、URL 保持/301

**Halo 优雅退役路径**：迁移验收后，Halo 容器停用、`~/docker_apps/halo/halo2` 归档备份（不舍得删就先停）；评论用 Artalk 独立存储，与 Halo 彻底解耦；postgres 可继续服务其它容器。

**窗口期事实**：6 文 + 21 图 + 1 瞬间 + 0 评论——数据量处在迁移成本最低点。

### 管理界面横向对比（保留备查）

| 方案 | 管理界面/写作 | Markdown 完整性 | 编辑器锁定 | 三轨功能面 | 判定 |
|---|---|---|---|---|---|
| **C'：Astro SSG + git** | 本地编辑器（自由） | ✅ 文件即真相 | ✅ 永久免疫 | 图库/瞬间自建 | 流 a 首推 |
| **A：Halo + 自写主题** | Console | ⚠️ 插件级支持 | ❌ 锁定（选定即终身） | ✅ 官方插件全有 | 流 b 备选 |
| **B：Halo headless + Astro** | Console 写作 | ⚠️ 同上 | ❌ 同上 | ✅ | 编辑器痛点未解，降位 |
| Ghost | 业界最佳编辑器 | ✅ 原生 | ⚠️ 单一编辑器 | ❌ 无瞬间/图库 | 流 b 备选 |
| WordPress | 生态最大 | 插件支持 | ⚠️ Classic/Block 割裂 | ✅ | ❌ PHP 世界 |
| Typecho | 极简 | ✅ 原生 | 单一 | ❌ 功能少于 Halo | ❌ 降级 |
| Notion/飞书 CMS | SaaS 编辑器 | ✅ | ✅ | ❌ | ❌ 所有权风险 |
| 全自研 | 自己造轮子 | — | — | — | ❌ 过度工程 |

### 5.1 若流 b 选 A：重写范围详解（备查）

Halo 架构事实：**Console（管理界面）与主题（访客前端）是解耦的部署物**——重写主题对 Console 零影响。

**复用（不动）**：Halo 服务端 + postgres + 部署链；Console 全部管理功能；公共 API、RSS、搜索、评论组件、URL 结构。

**重写（仅主题层）**：`theme.yaml` + ~10 个 Thymeleaf 模板（index/post/category/tag/archive/author/404 + moments/photos 集成）；设计系统 tokens（独立 CSS 变量层，可平移到未来任何架构）；Vite + TS 构建链；前端交互 JS（明暗切换、TOC、进度条、lightbox）。

**版本注**：生产 Halo 为 2.24，Finder API 自 2.0 起稳定；升级 Halo 与主题工作解耦，可独立进行（升级前照例备份）。

---

## 6. 执行约束（红线清单）

1. **合规**：ICP 备案页脚与工信部链接永久保留；不引入第三方追踪/统计需用户同意
2. **数据安全**：生产 Halo 容器（18090）与 postgres 不动；开发用独立实例（新容器 + 独立端口 + 独立数据卷）；任何对生产的操作前先 `pg_dump` + 备份 `~/docker_apps/halo/halo2`
3. **URL 与 SEO**：保留 `/archives/{slug}` 结构；若变更必须 301；ESA（阿里云）切换后刷新缓存
4. **切换策略**：Halo 支持多主题并存——新主题在独立实例验收后再生产切换，可秒级回滚（换回 higan）
5. **可访问性**：对比度 WCAG AA（higan 作者自己也倡议）；所有动效包 `prefers-reduced-motion`；marquee/噪点可暂停；正文光标保持标准 I-beam
6. **性能预算**：Lighthouse **桌面与移动端均 ≥90**；首屏无阻塞 JS；图片懒加载 + 缩略图 + blur-up 占位；中文字体分片自托管（见 §3）
6a. **图片暗色策略分场景**：正文插图暗色下降亮度/降饱和；**图库与摄影图文页暗色下保持原图亮度、底色可加深至近黑**（摄影社区共识：黑底看片）——两者规则不同，实现时区分
7. **动效纪律**：全站一支缓动曲线 + 统一时长；动效不进正文阅读区
8. **基建寿命**（julesforrest 域名被赌博站劫持的教训）：域名自动续费、证书自动化、内容定期导出 markdown 留档
9. **安全头**：Halo 现有 CSP（upgrade-insecure-requests）不破坏；不内联第三方脚本

---

## 7. 待你拍板的决策清单

0. **内容分轨确认**：三轨 = 阅读 / 技术（Linux·coding·技术分享合并）/ 摄影 + 瞬间生活流——待确认
1. ~~视觉路线~~ ✅ 已拍板：**丙（灰阶骨架×分轨正文）**，并叠加「开源极客层」（命令面板/键盘/终端彩蛋/贡献图/构建透明，见 §4c）；样板 v2 交互升级版预览中
2a. ~~写作流分叉~~ ✅ 已拍板：本地 + 浏览器双流 → 架构定 **C''**（Astro SSG + git 唯一事实源）
2b. ~~浏览器入口~~ ✅ 已拍板：**gitea**（数据可控全在自己手里）；发布链 = push → webhook → homelab 构建 → nginx 静态目录
2c. ~~Halo 编辑器锁定~~ 随架构 C'' 作废；Halo 迁移验收后停用归档，双跑期长短待定
3. ~~评论~~ ✅ 已拍板：**Artalk**（§4a）
4. **照片管线**：推荐 **阶段 0 = gitea 上传+构建时处理（当天可用）→ 阶段 1 = 先试 Sveltia CMS（零新运维）→ 不合手再自写 photo-pipe（可开源）**（§4b，证据已实抓坐实）——认可分阶段，还是直接上 Sveltia/自写？
5. ~~书评情绪色~~ ✅ 样板已预览（待最终确认，不阻塞）
6. ~~中文字体~~ ✅ 已拍板：**自托管分片 webfont**（霞鹜文楷 + 思源黑 + JetBrains Mono，cn-font-split 官方支持 Astro，详见 §3 字体策略）
6a. ~~中英切换~~ ✅ 已认可：构建时预翻译方案 + AI 译文小标注（文学内容标「机器翻译，欢迎指正」）
6b. ~~多端适配~~ ✅ 新增硬性需求已入规格（§4e）与红线（§6-6）
7. ~~首屏身份陈述~~ ✅ 定案：留空待用户后续撰写（组件预留槽位）
8. ~~内容三轨~~ ✅ 已确认：阅读 / 技术 / 摄影 + 瞬间生活流

**调研阶段收官（2026-10-24）：全部决策已定，进入实施（见 §8）。**

## 8. 实施规划（2026-10-24，按红线分期、每期可验收可回滚）

> 工作量按 agent 主执行、你只做关键验收估算；日历时间合 1–2 周。

**Phase 0 · 基建与备份（半天–1 天，不动生产）**
- [ ] 红线备份：pg_dump + ~/docker_apps/halo/halo2 归档
- [ ] gitea 容器部署（独立数据卷；git.wait4x.online，nginx 反代+TLS）
- [ ] Artalk 容器部署（sqlite 卷，nginx /artalk 反代）
- [ ] new-api 网关确认可用模型（翻译引擎就绪）
- 验收点：gitea 建仓/上传可用；Artalk 评论页可达

**Phase 1 · Astro 项目骨架 + 设计系统（2–4 天）**
- [ ] repo 结构（content/{posts,moments,photos}，i18n 配置，tokens.css）
- [ ] vite-plugin-font 字体分片管线（文楷+思源黑+JBMono 自托管）
- [ ] 核心页：首页（名片+分轨列表）/ 书评、技术文双模板（排版按 §3）/ 图库 masonry+lightbox / 瞬间时间线 / 关于（身份陈述槽位留空）
- [ ] 明暗模式、Pagefind、RSS、sitemap、Artalk 集成、ICP 页脚
- [ ] 响应式按 §4e 全断点实现
- [ ] 极客层 P0 四件套：键盘+? 帮助、页脚构建信息、View Transitions、项目墙双源
- 验收点：样板 v2 能力在真实构建全部复现，多端走查过

**Phase 2 · 内容迁移（半天–1 天）**
- [ ] Halo API 导出 6 文 → md（frontmatter 含分类/标签/情绪色/slug）
- [ ] 21 图迁移 + EXIF 构建验证；1 瞬间迁移
- [ ] URL 1:1（/archives/{slug} 路由直接实现，零 301）
- 验收点：逐篇人工比对清单

**Phase 3 · 双语管线（1 天）**
- [ ] 翻译脚本（走 new-api）+ .en.md 入仓约定 + 润色锁定机制 + AI 标注组件
- [ ] hreflang / 双语 RSS
- 验收点：存量 6 文英文版人工抽检

**Phase 4 · 极客层 P1 + 上线切换（1–2 天）**
- [ ] Ctrl+K 命令面板、gitea 热力图
- [ ] 发布链闭环：gitea webhook → homelab 构建 → rsync → nginx
- [ ] 预发布域名全端验收（§4e 实测矩阵）
- [ ] 切换：nginx upstream 改静态目录 → ESA 刷新 → 观察（秒级可回滚：改回 18090）
- 验收点：线上全功能 + Core Web Vitals 绿

**Phase 5 · 退役与二期（按需）**
- [ ] Halo 停用归档（双跑期由你定）
- [ ] 二期候选：Sveltia 试装/photo-pipe 自建、/terminal 彩蛋、书评索引画廊、瞬间 PWA 上传端点、/stack·/colophon 页