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

25 KiB
Raw Permalink Blame History

Terminal-Witcher 完整上下文与维护记录

整理于 2026-11-16(Asia/Shanghai)。这是对本次长会话的结构化记录,不是逐字聊天转录。

快速接手先看 HANDOFF.md。需求发生冲突时,按下文“最终状态”和用户后续新消息执行,不要回退到历史方案。

一、项目与协作方式

  • 工作目录:C:\Users\11789\Documents\Projects\Codex_ws\halo-theme-terminal。
  • 主题:Terminal-Witcher;metadata.name: theme-terminal-witcher。
  • Halo 最低版本:>=2.22.0;当前 spec.version: 3.1.17。
  • 作者与站点来自现有配置:WitcherCheung,https://witchercheung.cn。
  • 用户要求直接在这套 Halo 主题上修改,维持现有风格,中文沟通。用户会根据实际安装后的截图逐步调整。
  • 当前前端为原生 JS ES 模块 + SCSS + Thymeleaf;pnpm 管理依赖,esbuild 构建,@halo-dev/theme-package-cli 打 ZIP。
  • 用户希望每完成一个主题需求,版本末位自动 +1,并执行 pnpm build 提供对应 ZIP;同一需求内只递增一次。
  • 任务只需文档时不新增主题版本。本次交接整理没有执行新的主题发布。
  • 随后用户明确要求“推到 git 上,版本啥的都弄清楚,该推的都推了”。本轮已授权集中提交和同步现有 3.1.17 成果、真实版本标签与安装包发布;不把这次同步算作新主题功能版本。
  • 不需要每个可逆编辑都重新请求许可;不要只说“能改”或给计划而不完成用户授权的修改。
  • 没有线上 Halo 后台授权/会话、没有生产部署结果;不要把本地浏览器样例当线上真实文章内容。

二、用户最终确认的视觉与交互方向

顶部导航

  1. 原来的顶部条(站名黑块、斜纹、搜索/配色等按钮那一行)已移除,保留下方导航并重做。
  2. Logo 与网站标题放左侧,导航文字整体放右侧;“首页”菜单项去掉,品牌仍可回首页。
  3. 导航保持在顶部。实际实现是 position: sticky; top: 0。
  4. 当前页头高度默认桌面 64px,手机 56px;以 SCSS 为准,不要根据早期截图擅自改数值。
  5. 页面位于最上方时不显示底部浅分隔线;滚动超过 8px 后加 is-scrolled,才显示浅分隔线与半透明毛玻璃。
  6. 毛玻璃为基于导航背景色的 72% 混色,blur(14px) saturate(140%),用户曾要求更透一些。
  7. 桌面可展开项使用紧凑箭头,鼠标移入或键盘操作可展开。菜单文字与箭头间隙已经缩小。
  8. 手机宽度边界为 899px:导航文字折叠为三横线;点击立即响应,从右侧进入覆盖全页面的导航,按钮动画变 X。菜单入场动画约 240ms,没有额外等待延时。
  9. 手机展开内容最终为左对齐,子分类缩进 2em。早期“右对齐”被用户纠正。
  10. 手机菜单有关闭、Escape、焦点/背景 inert 等行为;继续修改时保留这些功能。
  11. 用户最新偏好是整个站点方角,因此桌面下拉菜单也已从早期圆角改为方角。

欢迎区和名片

  1. 用户拒绝过一张改变整体风格的 AI 设计图。后续以现有 Terminal 字体、色彩、虚线分隔和排版为基础实现,不再整套换风格。
  2. 欢迎标题沿用“欢迎参观我的博客”及终端光标效果;欢迎区本身没有完整外框。
  3. 欢迎标题靠左,说明文字在欢迎内容自身的区域内靠右。
  4. 最终顺序:左名片、右欢迎。默认名片占 30%、欢迎占 70%,可配置为 50% / 50%。
  5. 手机端先名片,再欢迎语。
  6. 名片文字左对齐,照片位于名片内部右侧;照片可选,也可以只显示照片。
  7. 名片配置包括姓名/昵称、身份方向、简介、照片、关于我或简历链接。没有预设虚构简介或真实人物照片。
  8. 简介按纯文本转义输出并保留换行;欢迎公告内容仍支持可信 HTML。
  9. 简历链接可能是 PDF,因此名片链接没有强行加 data-pjax。
  10. 名片当前有完整主题主边框,方角、浅底色。不要退回只有一侧的细分隔线。
  11. intro_style: detailed 为默认细节版:淡电路走线装饰、简介浅底色、欢迎内容底部细分隔,以及文章归档/作品集快捷入口。社交图标也收在欢迎内容底部。
  12. intro_style: plain 为简洁版;关闭名片后欢迎区恢复全宽。仅名片字段为空时不显示虚构占位内容。

首页四块布局

┌────────────────┬────────────────────────────────┐
│ 个人名片 30%    │ 欢迎内容 70%                    │
└────────────────┴────────────────────────────────┘

┌────────────────────────────────┬────────────────┐
│ 文章 70%                        │ 生活 30%        │
└────────────────────────────────┴────────────────┘

┌────────────────┬────────────────────────────────┐
│ 阅读 30%        │ 作品集 70%                      │
└────────────────┴────────────────────────────────┘
  • 不是贯穿整页的固定两列侧栏;是上下两排比例错开的布局。
  • 首页默认最大宽度 1440px,页头在首页与内容对齐。离开首页后恢复普通页面宽度。
  • 实现依靠 .homepage 标记与 :has(),适应 PJAX 替换 .content 后的页面变化,不依赖只在初始页面执行的 body class。
  • 上排文章/生活保持近似高度;窄屏按文章、生活、阅读、作品集顺序堆叠。
  • 四块区域的右侧入口统一为**“更多”**,不要混用“全部笔记”“全部作品”。

文章卡片

  • 区块名是“文章”,不是 Note。
  • 竖向卡片,上方正方形封面,下方标题、摘要、日期,可显示置顶与标签。
  • 自动模式按文章区实际宽度显示两列或三列;窄屏一列,可手动指定 2/3 列。
  • 默认 6 篇,支持设置 1–12 篇。不是强制所有文章都在首页一次显示;完整列表走“更多”或导航“文章”。
  • 标题最多两行、摘要最多三行;完整标题仍在链接 title 和文章页中,不丢内容。
  • 没封面时用 >_ 等终端字符占位,保留卡片比例。
  • 悬停有轻微上移和图片缩放,键盘聚焦有反馈;减少动态效果时关闭位移/缩放。
  • 最终使用方角与可配置的主边框,默认 2px。

生活列表

  • 以实际文章分类读取,包含子分类。
  • 自动匹配分类显示名 生活 或 slug life;也能在设置中明确选择分类。
  • 首页“文章”排除这个生活根分类及其所有后代。文章同时勾选技术和生活时,生活优先。
  • 生活行是左图、右文;右侧显示标题、日期和摘要,图文之间有小间距。
  • 缩略图是约 64–88px 的方形图,使用原文章封面,点击可进入文章;没有封面时整行纯文字,不留空框。
  • 生活标题最多两行,保留完整链接标题提示;摘要最多三行。
  • 默认最多显示 6 条;“更多”进入实际生活分类的永久链接。
  • 用户只需在文章编辑页选择生活分类并填写封面。主题不迁移后台分类、不修改文章内容。

阅读与作品

  • 阅读手动维护书名、封面、一句话点评、可选阅读笔记链接,每行两本,默认首页 4 本,可配置。
  • 书封采用原图比例:宽度铺满、高度自然变化,不固定 2:3 框、不变形、不额外留上下空白。
  • 书封悬停只提供边框颜色反馈,不缩放裁切。未配封面才显示书名占位。
  • 点评保持一行省略并保留完整提示;不要误认为这是书封没显示全的同一个问题。
  • 阅读“更多”默认 /read。用户尚未创建独立页面时,主题只提供链接,不会代为创建后台页面;创建别名为 read 的页面后可访问,也可自定义链接。
  • 作品类似产品图 + 产品介绍,可配置手动列表。
  • 自动模式可读取已启用的 portfolio 项目集插件;没有插件时走手动数据,不要在插件可用性判断外直接调用 projectFinder。
  • 作品可显示 GitHub/开源仓库链接;“更多”默认 /portfolio,允许修改。

方角、主边框与目录的例外

  • 用户最初喜欢轻圆角,但后续明确要求“整个网站四四方方、有边框”。最终方角为准。
  • --radius-theme-border: 0;首页的 --radius-home-image 引用它,不再固定 8px。
  • 主边框曾调粗至约 3px,用户认为过粗;3.1.14 已恢复默认 2px。
  • global_style.border_width_px 为直观数字输入,0–12,步长 0.5;填写后优先于旧的 CSS 文本配置。
  • global_style.border_width 作为高级 CSS 兼容值仍保留。像素值留空时使用它,两项都空则使用 2px。
  • 文章目录最终独立配置:默认 1px 浅色,不再继承全局主边框粗细;这是用户 3.1.17 的最新要求。
  • 目录颜色留空时按主题边框色 25% 与背景色 75% 混合,随明暗模式切换;目录内部层级线也用该颜色。
  • 目录颜色手动选择后是固定色;宽度为 0 时只隐藏外框,收起时始终不显示目录面板边框。

三、设置字段速查

首页 index_page

字段 用途/当前默认
intro_style detailed / plain,默认细节版
notice_title、notice_content 欢迎标题与公告 HTML;实际用户内容由 Halo 保存
profile_enable 显示左侧名片,默认 true
profile_split aligned 为左 30% / 右 70%;equal 为左右等宽
profile_name、profile_role、profile_bio 姓名、身份、纯文本简介;默认空
profile_photo、profile_url 可选照片与简历/关于我链接;默认空
show_sns 显示配置的社交入口
article_source all 默认:所有非生活的已发布文章;category 才启用文章分类选择
note_category 主动选择分类模式时读取,不能因名字为“文章”自动生效
article_columns auto / 2 / 3
note_limit 默认 6,范围 1–12
life_category 留空自动匹配生活;手动选择优先
life_limit 默认 6,范围 1–6
books、book_limit 书架条目和首页书籍数量
books_more_url 默认 /read
project_source、projects、project_limit 作品来源、手动作品、首页数量
projects_more_url 默认 /portfolio

配色 color_scheme.custom_color_schemes[]

字段 用途
id、background、text、accent 自定义配色基本字段
advanced 打开高级颜色设置
navigation 导航文字、网站标题、手机菜单按钮颜色
navigation_background 导航栏背景;同时应用于桌面下拉和手机菜单;空则继承页面背景
border、border_accent、border_emphasis 普通、交互、强调边框语义颜色
  • 设置自定义方案后,还需选择对应浅色或深色方案为 custom,填写 custom_light_scheme / custom_dark_scheme 为该 ID。
  • 导航下拉 hover 背景用导航文字色、文字用导航背景色,不能继续套用页面的反色变量,否则独立背景配色可能出现同色文字。
  • 不要为所有内置配色硬编码导航背景;默认变量引用页面背景即可,保证旧自定义方案兼容。

全局样式 global_style

字段 用途
border_width_px 数字像素输入,优先级高;允许 0
border_width 兼容既有的 1px / calc(...) 等 CSS 值
border_style 主边线样式
table_border_width、table_border_style 表格独立设置,仍保留
title_divider_style 标题分隔线样式

文章页 post_page

字段 用途/默认
show_toc 显示文章目录
toc_default_open auto / open / closed
toc_border_width_px 默认 1,范围 0–6,步长 0.5;留空按 1px 回退
toc_border_color 默认空,自动浅色;可选择固定颜色

关键 CSS 变量

变量 当前意义
--width-theme-border 全站主边框,默认 2px
--radius-theme-border 方角,默认 0
--color-theme-border 主边框颜色,默认从主题文字色派生
--color-theme-navigation 导航文字
--color-theme-navigation-background 导航与菜单背景,默认引用页面背景
--width-theme-toc-border 目录独立宽度,默认 1px
--color-theme-toc-border 目录独立浅色,默认 color-mix(in srgb, var(--color-theme-border) 25%, var(--color-theme-background))

四、文章分类数据读取的维护要点

实现位置为 templates/modules/home.html 根节点的 th:with:

  1. 读取所有分类,自动或按设置找到生活根分类和可选文章根分类。
  2. 用 categoryFinder.getBreadcrumbs(metadata.name) 判断分类是否属于根分类的后代,投影为分类 ID 列表。
  3. 没找到生活分类时沿用原来的分页文章查询,避免升级后隐藏原有文章。
  4. 找到生活分类时用 postFinder.listAll() 获取公开文章列表;过滤 status.hideFromList == true,按需应用文章分类筛选,再排除任一分类属于生活树的文章。
  5. 在过滤后的结果上按 note_limit 渲染卡片,保持原始 Finder 排序,不先截断最近 6 条。
  6. 生活区另用 postFinder.list({page: 1, size: lifeLimit, categoryName: ..., sort: {'spec.publishTime,desc'}}),该接口会包含子分类。
  7. 未分类文章仍保留在默认文章区;仅主动选择文章分类模式时才按指定技术分类限制。
  8. 首页排除生活不意味着归档或导航“文章”入口排除生活,完整归档仍是 /archives。

已核对的官方资料,便于接手者复查(不要凭空添加 API 参数):

listAll() 比只取少量文章的数据量大。以后若确实需要针对大站点做性能优化,应保留现有的正确性:生活后代分类、多分类优先级、公开/隐藏状态、排序和排除后补足数量。当前没有待办性能修复,不要以优化为由擅自改回会漏文章的方案。

五、版本演进记录

早期导航/四块首页迭代与 3.1.5–3.1.7 的具体逐项对应无法从现存文件完整确认,因此不虚构精确版本归属。以下 3.1.8 起的对应来自当前会话的实际交付记录。

版本/阶段 主要内容
早期导航改版 删除顶部条;品牌左、菜单右;去首页菜单;固定页头、桌面展开、手机全屏菜单与 X 动画;手机最终左对齐;滚动后浅分隔线与更透的毛玻璃
早期首页改版 去掉欢迎外框、标题左说明右;四块错开布局;Note 改为文章;竖卡、方封面、标题/摘要截断;统一“更多”;阅读 /read、作品 /portfolio 与 GitHub 入口
3.1.8 修复“文章分类”误筛选造成技术文章消失;默认读取所有已发布文章;导航“文章”进入 /archives;空分类提供完整文章入口
3.1.9 欢迎区与可配置个人简介左右分块;可选照片/简历链接、比例选择和手机布局
3.1.10 细节版/简洁版欢迎区;淡电路纹理、简介底色、归档和作品集快捷入口、社交入口整合
3.1.11 左右交换:名片左 30%、欢迎右 70%;手机先名片再欢迎
3.1.12 名片加完整主题边框
3.1.13 导航背景/文字独立配色;书封按原比例铺满;全站方角;边框一度加粗至约 3px
3.1.14 增加全局边线数字像素输入;兼容旧 CSS 值;默认主边框调回 2px
3.1.15 文章页右侧目录在所有布局/宽度下显示外框,使用主题边框与内边距
3.1.16 首页文章/生活分流,生活子分类与多分类处理;生活列表左侧小封面、右侧文字
3.1.17 目录边框独立粗细和颜色设置;默认 1px 浅色,内部层级线同步调浅
本次文档整理 保存这两份 Markdown 并增加 AGENTS 阅读入口;不新增主题版本
本轮 Git 同步 使用已有 3.1.17 集中提交源码与交接说明,维护真实标签,补充 CHANGELOG 并分发安装包

六、历史验证记录

哪些是历史已验证,哪些是当前实查

  • 以下自动化场景是在此前实现过程中通过的,不能因为写在这里就声称 2026-11-16 又重跑了一遍。
  • 2026-11-16 Git 同步前重新执行 pnpm build,确认源码版本、Git 状态、主题/设置 YAML 身份及字段、现存产物、关键 ZIP 文件一致性与 ZIP 完整性;生成了 dist/SHA256SUMS.txt。没有重跑已丢失的历史回归工具。
  • 临时测试目录现在为空,预览图片现在也不在 dist 中。要重新验证或截图,需要重建工具或使用可访问的 Halo 环境。

历史工具结构

  • 临时目录:C:\Users\11789\AppData\Local\Temp\halo-home-template-check。
  • 模板测试:HomeTemplateCheck.java,Thymeleaf Spring6 3.1.3 + SpringEL、Jsoup、SnakeYAML;假 Halo Finder/插件数据,实际渲染项目 index.html、布局、首页模块及部分分类/归档。
  • 曾有 pom.xml、classpath.txt、rendered/。依赖版本细节未完整保留,重建时重新核实,不要编造。
  • 浏览器测试:本地 HTTP 服务提供渲染结果和实际 templates/assets/dist 资源;使用 Playwright 驱动 Edge。
  • 当时的 Playwright 模块路径:C:/Users/11789/AppData/Local/npm-cache/_npx/e41f203b7505f1fb/node_modules/playwright。
  • Edge:C:/Program Files (x86)/Microsoft/Edge/Application/msedge.exe。
  • Java 编译器:C:/Program Files/Java/jdk-21.0.12.1/bin/javac.exe。
  • 本次实查上述三个软件路径仍存在;测试脚本本身已经不在临时目录中。

历史脚本名称供重建时理解用途,不代表当前存在:

脚本 验证内容
HomeTemplateCheck.java 完整 Thymeleaf 渲染和分类/旧设置/插件/独立边框回归
data-review.cjs 空“文章”父分类、独立技术分类、完整归档和导航链接
cards-review.cjs 卡片布局、标题截断、封面、悬停/焦点、明暗主题、PJAX 宽度恢复
intro-review.cjs、intro-swap-review.cjs 名片/欢迎顺序、比例、手机布局、空/纯图/纯文状态
square-nav-books-review.cjs 导航独立配色、滚动毛玻璃、手机菜单、方角粗细与自然比例书封
border-width-review.cjs 主边框 2px 默认、数字 1.5、0、旧 CSS 与清空回退
toc-frame-review.cjs 目录外框、全屏、宽窄屏、折叠行为
life-split-review.cjs 生活分流、左图右文、无封面回退、手机、显式分类和自定义生活分类
toc-soft-border-review.cjs 目录默认 1px 浅色、独立自定义色/宽度、0、旧配置与明暗切换

必须保留的回归场景

  1. 旧配置没有新字段时仍可渲染。
  2. 名为“文章”的空分类存在,技术文章在独立分类或未分类时仍显示;无需迁移到“文章”分类。
  3. 自动/手动生活分类、生效根分类的二级和三级后代。
  4. 一篇文章同时属于生活后代和技术分类时,只出现在首页生活区。
  5. 最近连续超过 1000 篇生活文章时,排除后仍能补足六篇普通文章。历史测试构造过 1005 篇生活文章。
  6. 未分类文章保留;hideFromList 的文章不出现在普通文章区。
  7. 全部都是生活文章时,文章区显示空状态,生活区仍正常显示。
  8. 主动选择技术分类时包含其后代,并继续排除生活。
  9. 没有生活分类或配置的分类被删除时,不隐藏原有普通文章。
  10. 生活封面在左、间距正常、文字在右;无封面不留占位;封面/标题链接一致,方角和配置粗细生效。
  11. 阅读封面不同比例时无图片框额外留白,未发生变形;全屏正文媒体限制不影响首页封面。
  12. 自定义导航色应用于页头、下拉、手机全屏菜单;hover 文字可见;滚动有毛玻璃,页顶无底部分隔线;旧方案无导航背景字段时跟随页面背景。
  13. 主边框数字 1.5、0、清空、旧 CSS 值;0 不能被错误当作“没有配置”。
  14. 目录外框独立于全局主边框;默认 1px 浅色;自定义宽度/色、0、清空、旧配置、明暗切换;收起不显示外框。
  15. 未启用 portfolio 插件不调用不存在的 projectFinder;手动模式在插件启用时仍可优先使用手动数据。
  16. 手机菜单的全屏、三横线/X、左对齐、子分类缩进、焦点、关闭和 reduced-motion 行为。
  17. PJAX 离开首页后恢复普通内容宽度,页头宽度也恢复。

历史浏览器宽度覆盖包含 1910、1440、1280、1024、900、899、768、430、375、320px;不要为小改动机械重复所有场景,按受影响功能选择适当检查。

测试与截图的已知陷阱

  • Playwright 对不存在的可选元素调用 boundingBox() 会等待 30 秒后失败。应先查 count();缺照片/缺欢迎语是支持的合法状态。
  • 导航颜色有约 160ms 过渡;切换配色或滚动后立刻读颜色可能得到上一帧。历史检查会等待约 240ms。
  • 桌面三横线按钮是隐藏的,其手机专用文字色不必在桌面断言。
  • 编译 CSS 可能保留自定义属性冒号后的空格,不能用过于脆弱的完整子串断言判断构建失败。
  • 全页截图前将图片 loading 改为 eager 并等 decode(),否则懒加载图片可能空白。
  • 等字体加载及欢迎光标标题动画完成再截屏。
  • 对已滚动到的生活区域截图时,sticky 页头可能遮住区块标题。可仅在截图样式里隐藏页头,不要为了截图改生产导航行为。
  • PowerShell 默认输出编码可能把中文显示成乱码;读取用 -Encoding utf8。不要把含中文的 here-string 随意传给 Python 导致源码变成问号。
  • Java 源码不要带 UTF-8 BOM;Set-Content -Encoding utf8 在某些 PowerShell 版本会加 BOM。可用 apply_patch 写入,或通过 utf-8-sig 读取后另存 UTF-8。

七、构建与后续交付

正常命令:

pnpm build
git diff --check

构建脚本等价于 node build.js && theme-package。build.js 会重建 templates/assets/dist,主 JS/CSS、像素样式、库和字体均由构建生成。

仅检查中间编译可用:

node build.js

项目没有通用 pnpm test,也没有把历史临时测试脚本提交到仓库。需要重新做模板级验证时,应重建上文的假 Finder 渲染工具或连接明确授权的测试 Halo 实例。

版本规则:

  1. 本次保存上下文及其后获授权的 Git 同步,都继续使用现有 3.1.17。
  2. 下一次真正完成用户提出的主题修改时才升到 3.1.18。
  3. 同一需求只升一次;不要每次验证构建都递增。
  4. 用户收到的是 dist/theme-terminal-witcher-<版本>.zip。核对 ZIP 中 theme.yaml 版本及编译资源,必要时跑 ZIP 完整性检查。
  5. 本轮用户已授权提交、打标签、推送并整理现有版本;后续操作按新任务的授权范围执行。Git 仓库发布不表示已经安装到用户网站。

本轮实际 Git 目标

  • origin 为 https://gitea.witchercheung.cn/witcher/halo_theme_terminal.git,只有这个配置的远程,默认分支为 main。
  • 同步前 main 指向 0859e49,其中 theme.yaml 是 3.1.1;本次把现有开发成果集中作为 3.1.17 提交。
  • Git 标签采用已有的无 v 前缀格式:保留并同步真实的 3.1.0、3.1.1,新交付标签为 3.1.17。
  • 不根据聊天版本号伪造 3.1.2–3.1.16 的历史提交或标签。版本开发记录在 CHANGELOG.md 和本文件中保留。
  • 当前发布页 分发 theme-terminal-witcher-3.1.17.zip 与 SHA256SUMS.txt;dist 继续按原有规则忽略,不将构建产物强行加入 Git 历史。

八、这份上下文如何继续使用

  • AGENTS.md 保留用户原有的两条约定,并指向这两份交接文档。
  • 新模型应以实际源码/设置和用户的新消息为准;本文记录的是截至 3.1.17 的状态。
  • 目前没有需要它自动继续执行的界面修改。用户要求上下文长期保存在项目 Markdown 中,随后又明确授权将源码、交接文件和现有版本同步到自建 Git 仓库。
  • 不依赖 claude-mem 自动注入。此次记忆检索返回 worker 连接错误,未读取到可引用的观察 ID;完整接手依据就是这些文件和工作区。