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.
25 KiB
25 KiB
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 后台授权/会话、没有生产部署结果;不要把本地浏览器样例当线上真实文章内容。
二、用户最终确认的视觉与交互方向
顶部导航
- 原来的顶部条(站名黑块、斜纹、搜索/配色等按钮那一行)已移除,保留下方导航并重做。
- Logo 与网站标题放左侧,导航文字整体放右侧;“首页”菜单项去掉,品牌仍可回首页。
- 导航保持在顶部。实际实现是
position: sticky; top: 0。 - 当前页头高度默认桌面 64px,手机 56px;以 SCSS 为准,不要根据早期截图擅自改数值。
- 页面位于最上方时不显示底部浅分隔线;滚动超过 8px 后加
is-scrolled,才显示浅分隔线与半透明毛玻璃。 - 毛玻璃为基于导航背景色的 72% 混色,
blur(14px) saturate(140%),用户曾要求更透一些。 - 桌面可展开项使用紧凑箭头,鼠标移入或键盘操作可展开。菜单文字与箭头间隙已经缩小。
- 手机宽度边界为 899px:导航文字折叠为三横线;点击立即响应,从右侧进入覆盖全页面的导航,按钮动画变 X。菜单入场动画约 240ms,没有额外等待延时。
- 手机展开内容最终为左对齐,子分类缩进
2em。早期“右对齐”被用户纠正。 - 手机菜单有关闭、Escape、焦点/背景 inert 等行为;继续修改时保留这些功能。
- 用户最新偏好是整个站点方角,因此桌面下拉菜单也已从早期圆角改为方角。
欢迎区和名片
- 用户拒绝过一张改变整体风格的 AI 设计图。后续以现有 Terminal 字体、色彩、虚线分隔和排版为基础实现,不再整套换风格。
- 欢迎标题沿用“欢迎参观我的博客”及终端光标效果;欢迎区本身没有完整外框。
- 欢迎标题靠左,说明文字在欢迎内容自身的区域内靠右。
- 最终顺序:左名片、右欢迎。默认名片占 30%、欢迎占 70%,可配置为 50% / 50%。
- 手机端先名片,再欢迎语。
- 名片文字左对齐,照片位于名片内部右侧;照片可选,也可以只显示照片。
- 名片配置包括姓名/昵称、身份方向、简介、照片、关于我或简历链接。没有预设虚构简介或真实人物照片。
- 简介按纯文本转义输出并保留换行;欢迎公告内容仍支持可信 HTML。
- 简历链接可能是 PDF,因此名片链接没有强行加
data-pjax。 - 名片当前有完整主题主边框,方角、浅底色。不要退回只有一侧的细分隔线。
intro_style: detailed为默认细节版:淡电路走线装饰、简介浅底色、欢迎内容底部细分隔,以及文章归档/作品集快捷入口。社交图标也收在欢迎内容底部。intro_style: plain为简洁版;关闭名片后欢迎区恢复全宽。仅名片字段为空时不显示虚构占位内容。
首页四块布局
┌────────────────┬────────────────────────────────┐
│ 个人名片 30% │ 欢迎内容 70% │
└────────────────┴────────────────────────────────┘
┌────────────────────────────────┬────────────────┐
│ 文章 70% │ 生活 30% │
└────────────────────────────────┴────────────────┘
┌────────────────┬────────────────────────────────┐
│ 阅读 30% │ 作品集 70% │
└────────────────┴────────────────────────────────┘
- 不是贯穿整页的固定两列侧栏;是上下两排比例错开的布局。
- 首页默认最大宽度 1440px,页头在首页与内容对齐。离开首页后恢复普通页面宽度。
- 实现依靠
.homepage标记与:has(),适应 PJAX 替换.content后的页面变化,不依赖只在初始页面执行的 body class。 - 上排文章/生活保持近似高度;窄屏按文章、生活、阅读、作品集顺序堆叠。
- 四块区域的右侧入口统一为**“更多”**,不要混用“全部笔记”“全部作品”。
文章卡片
- 区块名是“文章”,不是 Note。
- 竖向卡片,上方正方形封面,下方标题、摘要、日期,可显示置顶与标签。
- 自动模式按文章区实际宽度显示两列或三列;窄屏一列,可手动指定 2/3 列。
- 默认 6 篇,支持设置 1–12 篇。不是强制所有文章都在首页一次显示;完整列表走“更多”或导航“文章”。
- 标题最多两行、摘要最多三行;完整标题仍在链接
title和文章页中,不丢内容。 - 没封面时用
>_等终端字符占位,保留卡片比例。 - 悬停有轻微上移和图片缩放,键盘聚焦有反馈;减少动态效果时关闭位移/缩放。
- 最终使用方角与可配置的主边框,默认 2px。
生活列表
- 以实际文章分类读取,包含子分类。
- 自动匹配分类显示名
生活或 sluglife;也能在设置中明确选择分类。 - 首页“文章”排除这个生活根分类及其所有后代。文章同时勾选技术和生活时,生活优先。
- 生活行是左图、右文;右侧显示标题、日期和摘要,图文之间有小间距。
- 缩略图是约 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:
- 读取所有分类,自动或按设置找到生活根分类和可选文章根分类。
- 用
categoryFinder.getBreadcrumbs(metadata.name)判断分类是否属于根分类的后代,投影为分类 ID 列表。 - 没找到生活分类时沿用原来的分页文章查询,避免升级后隐藏原有文章。
- 找到生活分类时用
postFinder.listAll()获取公开文章列表;过滤status.hideFromList == true,按需应用文章分类筛选,再排除任一分类属于生活树的文章。 - 在过滤后的结果上按
note_limit渲染卡片,保持原始 Finder 排序,不先截断最近 6 条。 - 生活区另用
postFinder.list({page: 1, size: lifeLimit, categoryName: ..., sort: {'spec.publishTime,desc'}}),该接口会包含子分类。 - 未分类文章仍保留在默认文章区;仅主动选择文章分类模式时才按指定技术分类限制。
- 首页排除生活不意味着归档或导航“文章”入口排除生活,完整归档仍是
/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、旧配置与明暗切换 |
必须保留的回归场景
- 旧配置没有新字段时仍可渲染。
- 名为“文章”的空分类存在,技术文章在独立分类或未分类时仍显示;无需迁移到“文章”分类。
- 自动/手动生活分类、生效根分类的二级和三级后代。
- 一篇文章同时属于生活后代和技术分类时,只出现在首页生活区。
- 最近连续超过 1000 篇生活文章时,排除后仍能补足六篇普通文章。历史测试构造过 1005 篇生活文章。
- 未分类文章保留;
hideFromList的文章不出现在普通文章区。 - 全部都是生活文章时,文章区显示空状态,生活区仍正常显示。
- 主动选择技术分类时包含其后代,并继续排除生活。
- 没有生活分类或配置的分类被删除时,不隐藏原有普通文章。
- 生活封面在左、间距正常、文字在右;无封面不留占位;封面/标题链接一致,方角和配置粗细生效。
- 阅读封面不同比例时无图片框额外留白,未发生变形;全屏正文媒体限制不影响首页封面。
- 自定义导航色应用于页头、下拉、手机全屏菜单;hover 文字可见;滚动有毛玻璃,页顶无底部分隔线;旧方案无导航背景字段时跟随页面背景。
- 主边框数字 1.5、0、清空、旧 CSS 值;0 不能被错误当作“没有配置”。
- 目录外框独立于全局主边框;默认 1px 浅色;自定义宽度/色、0、清空、旧配置、明暗切换;收起不显示外框。
- 未启用 portfolio 插件不调用不存在的
projectFinder;手动模式在插件启用时仍可优先使用手动数据。 - 手机菜单的全屏、三横线/X、左对齐、子分类缩进、焦点、关闭和 reduced-motion 行为。
- 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 实例。
版本规则:
- 本次保存上下文及其后获授权的 Git 同步,都继续使用现有 3.1.17。
- 下一次真正完成用户提出的主题修改时才升到 3.1.18。
- 同一需求只升一次;不要每次验证构建都递增。
- 用户收到的是
dist/theme-terminal-witcher-<版本>.zip。核对 ZIP 中theme.yaml版本及编译资源,必要时跑 ZIP 完整性检查。 - 本轮用户已授权提交、打标签、推送并整理现有版本;后续操作按新任务的授权范围执行。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;完整接手依据就是这些文件和工作区。