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

12 KiB
Raw Permalink Blame History

Halo 主题交接指南

整理日期:2026-11-16(Asia/Shanghai)

项目:C:\Users\11789\Documents\Projects\Codex_ws\halo-theme-terminal

当前主题:Terminal-Witcher,版本 3.1.17

阅读顺序:本文件 → 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:

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 发布页 用于分发安装 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。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。

给新窗口的开场提示

请先阅读项目根目录的 AGENTS.md、HANDOFF.md 和 PROJECT_CONTEXT.md,
检查当前源码与版本,然后基于这些上下文继续。
最新已完成版本是 3.1.17;先核对 main、版本标签及工作区状态,保留已有修改,
以我接下来发送的新需求为准。