Files
witcher ca00daddf6 feat: release Terminal-Witcher 3.1.17 and project handoff
Ship responsive navigation, configurable profile and four-section homepage, article/life category separation, natural-ratio book covers, and independent border settings. Include release history and complete context handoff documentation.
2026-11-16 18:30:36 +08:00

131 lines
12 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Halo 主题交接指南
> 整理日期:2026-11-16(Asia/Shanghai)
>
> 项目:`C:\Users\11789\Documents\Projects\Codex_ws\halo-theme-terminal`
>
> 当前主题:Terminal-Witcher,版本 **3.1.17**
>
> 阅读顺序:本文件 → [PROJECT_CONTEXT.md](PROJECT_CONTEXT.md) → 按任务查看源码。
>
> 本文依据当前会话与工作区整理,不要求接手模型能访问旧聊天或任何记忆插件。
## 目标
继续维护用户的 Halo 博客主题,以现有 Terminal 风格为基础迭代,而不是重新设计成另一套网站。用户希望简洁、方角、有边框、可配置;首页展示个人名片、欢迎语,以及错开的文章、生活、阅读、作品集四个区域。此前主题需求均已实现。用户要求保存 Markdown 交接后,又明确要求把源码、文档与版本同步到 Git;此次同步仍使用 **3.1.17**,没有新增待实现的界面需求。
## 当前状态
- 最新源码和安装包都是 **3.1.17**;最新改动是文章页右侧目录的独立浅色细边框设置。
- 目录外框默认 **1px**;颜色由主题边框色与背景色按 **25% / 75%** 混合,内层级辅助线也使用这个颜色。
- 设置入口:`主题设置 → 文章页 → 目录边框粗细(px) / 目录边框颜色`。
- 全站主边框是另一套配置,默认 **2px**,入口为 `全局样式 → 边线宽度(px)`;不要再让目录外框跟随这个粗细。
- 首页名片在**左侧 30%**,欢迎内容在**右侧 70%**;手机端先名片、后欢迎语。不是最初的“左欢迎、右名片”。
- 首页上排是**文章 70% / 生活 30%**;下排是**阅读 30% / 作品集 70%**。窄屏变成单列。
- 生活分类及其子分类的文章从首页“文章”区排除,只放在“生活”区;同时属于技术和生活分类时,**生活优先**。
- 生活列表是**左侧小封面、右侧标题/日期/摘要**,没有封面时不保留空图片框。用户已纠正过方向,不要改回右侧封面。
- 图片、卡片、目录、菜单等使用**方角**。此前的 8px 圆角和默认约 3px 粗边框都是历史设计,已被替换。
- 书籍封面按原图比例显示:宽度铺满,高度自动,不用固定 2:3 框产生上下空白,悬停时不放大裁切。
- 没有已知的未解决功能报错;但验证是本地模板渲染和浏览器验证,**不等于已在用户的线上 Halo 后台部署或验收**。
### 当前可用安装包
| 文件 | 状态 |
| --- | --- |
| `dist/theme-terminal-witcher-3.1.17.zip` | 最新安装包,2,636,011 字节;Git 同步前重新构建 |
| `dist/theme-terminal-witcher-3.1.16.zip` | 上一版本安装包 |
最新包 SHA-256:
```text
fc1f0ab2dc7bf875cfb2b9d5ba1dfc397a41c771c0c051ae21eca722016d1e73
```
2026-11-16 Git 同步前已重新执行 `pnpm build`,核对最新包内的 `theme.yaml`、`settings.yaml`、README、首页模板、布局模板和编译 CSS/JS 与工作区一致,ZIP 完整性检查通过,并生成 `dist/SHA256SUMS.txt`。此前聊天中的其他旧 ZIP、预览 PNG 在本次检查时已不在 `dist` 中,不要把历史链接当作当前存在的文件。
## 文件导航
| 文件 | 作用 |
| --- | --- |
| `AGENTS.md` | 用户的版本递增、构建交付约定;新会话阅读入口 |
| `CHANGELOG.md` | 3.1.17 集中发布说明与此前本地版本记录 |
| `PROJECT_CONTEXT.md` | 完整需求、设置字段、版本演进、回归场景、历史踩坑 |
| `theme.yaml` | 主题身份、Halo 最低版本、唯一需要递增的主题版本号 |
| `settings.yaml` | Halo 主题设置表单;首页、配色、全局边框、目录设置都在这里 |
| `templates/index.html` | 首页入口,调用首页模块 |
| `templates/modules/home.html` | 首页数据读取、分类分流、名片/欢迎语、四块内容及卡片片段 |
| `src/styles/home.scss` | 首页布局、卡片、书封、生活缩略图;首页专用宽度与 PJAX 恢复 |
| `templates/layout.html` | 全站布局及把配置转换成 CSS 变量的内联样式 |
| `templates/modules/header.html` | Logo/网站标题、菜单、手机菜单按钮;顶层“文章”链接修正 |
| `src/module/navigation.js` | 桌面子菜单、手机全屏导航、关闭/焦点处理、滚动状态 |
| `src/module/header.js` | 页头初始化;接入导航模块 |
| `src/styles/header.scss` | 固定页头、透明毛玻璃、滚动后细分隔线、品牌和按钮 |
| `src/styles/menu.scss` | 桌面下拉、手机全屏菜单、左对齐及子分类缩进 |
| `src/styles/scheme.scss` | 内置配色与语义颜色变量,含导航背景变量 |
| `src/styles/main.scss` | 全站默认变量;主边框默认 2px、方角默认 0 |
| `src/styles/toc.scss` | 文章目录外框、目录层级线、尺寸和滚动;独立细边框变量 |
| `src/module/post.js` | tocbot 目录生成、显示/收起、定位与窗口变化处理 |
| `templates/post.html` | 真实文章内容和目录 DOM |
| `templates/category.html` | 分类文章列表;空分类保留“查看全部文章”入口 |
| `src/styles/post.scss` | 文章与旧文章列表样式;封面方角 |
| `src/styles/portfolio.scss` | 作品集页面;主边框已统一 |
| `src/styles/moment.scss` | 动态媒体样式;方角和主题边框 |
| `src/styles/variables.scss` | Sass 断点;手机导航边界与 JS 的 899px 保持同步 |
| `src/styles/style.scss` | 样式入口;首页样式最后导入 |
| `i18n/default.properties`、`en.properties`、`es.properties`、`zh_CN.properties`、`zh_TW.properties` | 新增首页、导航、简介等文案;注意五套语言同步 |
| `README.md` | 使用说明、配置说明、CSS 变量和构建文档 |
| `build.js`、`package.json`、`pnpm-lock.yaml` | esbuild/Sass 构建、主题打包;不是 React/Vue 项目 |
| `templates/assets/dist/` | 编译资源,修改源文件后由构建生成,不要只改这里 |
## Git 与工作区
- 实际 Git 远程 `origin`:`https://gitea.witchercheung.cn/witcher/halo_theme_terminal.git`,主分支 `main`。不要因为主题元数据中保留了 GitHub 链接,就擅自推到另一个服务。
- 同步前源码基线是 `0859e49`(`Update README with theme description and links`),主题为 3.1.1;本次集中纳入其后开发至 3.1.17 的源码和文档。历史未提交状态不再作为新会话的当前状态依据。
- `src/module/navigation.js`、`src/styles/home.scss`、`templates/modules/home.html` 和交接 Markdown 均属于需要纳入版本控制的成果;不要漏掉这些过去未跟踪的文件。接手时以实际 `git status --short` 为准。
- 此次发布基准为 `main` 和标签 `3.1.17`,可用 `git rev-parse 3.1.17^{commit}` 查询确切提交。原有真实标签 `3.1.0`、`3.1.1` 保留原提交;不为中间本地版本补造历史。
- [3.1.17 发布页](https://gitea.witchercheung.cn/witcher/halo_theme_terminal/releases/tag/3.1.17) 用于分发安装 ZIP 与 SHA-256 校验文件。具体同步结果可用远程 refs 与发布页复核。
- 其余已修改文件主要就是上表中的模板、样式、设置、翻译、README 与 `theme.yaml`。
- `.gitignore` 忽略 `dist` 和 `node_modules`;交付 ZIP 不会自动进入版本控制。
- 本次交接文档应保留在项目中,方便用户长期给其他模型阅读;不要因为技能模板称其为“scratch file”而擅自删除或忽略。
## 关键历史错误与不要重复的做法
1. **按名为“文章”的分类自动筛选,曾让首页文章消失。** 用户菜单中的“嵌入式、STM32F407、机器人、ROS2、Web、前端、后端”等链接缩进,不代表后台分类已经建立同样的父子关系。3.1.8 修复为默认不要求归入“文章”分类。当前只增加了用户明确要求的“排除生活文章”,不要再次要求用户搬迁技术文章。
2. **不能先取最新 6 篇再排除生活文章。** 这会在近期生活文章很多时让普通文章卡片不足或为空。当前存在生活分类时先读取公开文章列表、排除隐藏和生活文章,再限制展示数量。
3. **Halo 2.22 的 `postFinder.list({...})` 没有可随意添加的排除分类参数。** 源码核对过该版本支持的字段。`size: 0` 也不是无限读取,会被重置为最多 1000。当前用官方 `listAll()` 避免任意截断,再在模板中过滤。
4. **不要依赖旧版分类 `spec.children`。** 当前用 `categoryFinder.getBreadcrumbs()` 判断后代关系,避免旧字段在新 Halo 版本中不再更新的问题。
5. **Thymeleaf 的 `#lists.containsAny` 不存在。** 实测报错为 `EL1004E: Method call: Method containsAny(...) cannot be found on type org.thymeleaf.expression.Lists`。当前使用嵌套集合选择和 `#lists.contains`。嵌套选择中访问外部变量用 `#vars`。
6. **书封固定比例 + `object-fit: contain` 会留白。** 必须一起取消书封外框固定比例,令图片 `height: auto; aspect-ratio: auto`;书封悬停缩放也已经取消。
7. **全屏正文媒体宽度会误伤首页图片。** `.content img` 的正文最大宽度限制不能套到首页各类封面;`home.scss` 顶部已有更具体的覆盖,包含生活缩略图。
8. **目录边框不能只写在全屏或小于 1400px 的媒体规则里。** 过去会导致普通大屏没有外框。现在外框直接写在 `.toc.toc-visible`,折叠时不显示框。
9. **不要让目录重新跟随全局 2px 主边框。** 用户明确认为太粗、太深;3.1.17 已分成独立 1px 浅色边框,设置在“文章页”。
10. **不要恢复旧设计方向。** 手机菜单最终左对齐;名片最终在欢迎语左侧;生活缩略图最终在文字左侧;图片最终为方角。用户确实曾提出过相反方向,后续消息已经覆盖。
## 验证状态与环境限制
- 之前已执行成功的 `pnpm build` 和验证场景见 [PROJECT_CONTEXT.md](PROJECT_CONTEXT.md)。3.1.17 已打包成功。
- 历史验证使用了真实 Thymeleaf Spring6 模板引擎和 Edge/Playwright,但通过假 Finder 数据渲染,不是用户线上 Halo 的直接会话。
- 历史脚本放在 `C:\Users\11789\AppData\Local\Temp\halo-home-template-check`。**2026-11-16 检查时这个目录存在但为空**;Java 类、classpath、浏览器脚本和渲染 HTML 均不能假定还在。
- 本次未重建已丢失的测试工具,未重新运行整套历史浏览器/模板回归;Git 同步前另外重跑了构建、YAML/设置身份与字段检查、关键文件/ZIP 一致性及完整性检查。
- 项目没有 `pnpm test` 脚本。不要捏造测试命令或声称临时脚本已随源码保留。
- 当前会话可见的记忆工具检索失败:`The worker could not complete this request. Retry after checking the worker connection.` 未获得可引用的观察 ID,交接内容不依赖记忆服务。
## 接手后的具体步骤
1. 阅读 `AGENTS.md` 和这两份交接文档;运行 `git status --short`、检查 `theme.yaml` 的实际版本,防止文档在后续协作中滞后。
2. 等待或理解用户的新需求。目前没有未完成的主题功能,不要自动改动 UI、重构分类逻辑或升级发布。
3. 修改时按上表定位源文件。配置功能通常需要同时修改 `settings.yaml`、`templates/layout.html` 和对应 SCSS;界面文案变更注意五套 i18n。
4. 做与修改相称的验证。涉及分类时保留技术/未分类文章,并验证生活子分类、多分类、隐藏文章及“先过滤再限制”;涉及目录时验证粗细/颜色独立、旧配置、0 值、手机与折叠。
5. 每完成一项新的**主题修改需求**,只将 `theme.yaml` 的 `spec.version` 末位数字加 1;当前基线为 3.1.17,下一项主题需求应是 **3.1.18**。本次上下文保存与 Git 同步没有新增主题功能版本。
6. 执行 `pnpm build` 和 `git diff --check`,检查 `dist/theme-terminal-witcher-<版本>.zip`,然后用中文提供安装包路径。中间验证构建不再重复加版本。
7. 本轮用户已明确授权提交、推送和整理版本;后续新的任务仍按用户当时的授权范围执行,不把 Git 发布误称为已部署到用户的 Halo。
## 给新窗口的开场提示
```text
请先阅读项目根目录的 AGENTS.md、HANDOFF.md 和 PROJECT_CONTEXT.md,
检查当前源码与版本,然后基于这些上下文继续。
最新已完成版本是 3.1.17;先核对 main、版本标签及工作区状态,保留已有修改,
以我接下来发送的新需求为准。
```