审查修复，2026-11-06
本文记录 v1.5.0 之后的本地修改，不代表新版本已发布、消费者已升级或站点已部署。原报告约 170 项意见并未全部确认或修复。
输入与方法
本次审查以主题 84b93e4 与文档站 a8eeb92 为起点。候选修改保留 Hugo
Extended 0.168.0 与内置 LibSass；本机环境为 macOS ARM64、Go 1.27.3、Node
26.12.0、npm 11.20.0、Python 3.14.8。普通系统路径上的 Hugo 0.169.0 不属于
本轮验证基线，它产生的快照差异不能直接证明 0.168.0 上存在缺陷。
构建与输出判断使用主题归属检查器中的合成输入验证；交互判断使用同级文档站
的 Playwright 回归验证。浏览器预览采用本地主题替换及
hugo.yml,tests/fixtures/browser.yml，关闭两种 workspace 机制、文件监听和
自动刷新。记录有意的输出变化前，先审核已有快照的差异。
已确认的缺陷与修复
| 领域 | 已确认行为与修复 | 可复现证据 |
|---|---|---|
| 无效输入 | 位置参数进入仅支持 map 的短代码操作，导致构建失败。现在先保护命名参数，警告后安全省略或回退；负例必须以零退出码结束。 | check-content-primitives.py、check-book.py |
| Book 编号 | 无效编号生成 fig- 等空目标。现在保留可读的无编号内容，不注册目标。 |
check-book.py：HTML、打印、Markdown、BookManifest 和索引条目，并用有效编号作对照 |
| 嵌套组件 | 独立 Markdown 文档与同级短代码容器重复使用局部序号。自动 ID 及引用现在包含所属容器作用域；作者显式指定的代码 ID 保留。 | check-code-blocks.py：重复嵌套代码、字段、图表与 FileTree 的 HTML／打印输出 |
| Feed | 按权重排列的页面先被截断，随后才处理日期；无日期条目输出公元元年；部分组件输出原始 Markdown。两种 Feed 现在先排序再限量，省略缺失日期，组件使用静态 HTML 或约定的省略行为。 | check-content-primitives.py、check-book.py、RSS 快照 |
| 引用与版本 | 缺失手册引用可能让 Hugo 失败，版本链接可能重复部署前缀。共享解析器现在提供警告回退，并只拼接一次版本路径。 | check-agent-indexes.py、check-actions.py |
| 子路径导航 | 语言中立的导航 ID 与分区索引查找键保留了部署前缀。共享解析器现在移除部署及语言前缀，对外链接仍保留两个前缀。 | check-agent-indexes.py：根路径／子路径、中英双语，以及默认语言有／无独立目录的组合 |
| Landing | 错误记录结构与可选字段可能破坏 Markdown 输出。HTML 与 Markdown 现在共享记录及 URL 校验，保留片段与查询参数，补齐单独 CTA 链接；危险目标不会变成空链接。 | check-landing.py |
| 博客导航 | 列表页继承文章阅读顺序的导航，并使用英文分页。现在由本地化的语义分页统一管理列表导航与 head 链接。 | check-reading.py、check-shell.py、浏览器分页回归 |
| 焦点与菜单 | 原生禁用会移除控件焦点；隐藏锚点无法到达；由焦点打开的菜单在 Escape 后重新打开。带操作保护的 aria-disabled 控件保留焦点，锚点可达，Escape 先恢复焦点再关闭菜单。 |
JS 单测及浏览器代码块、外壳、对照视图和 Expo 套件 |
| 移动外壳 | 仅有导航栏的文章缺少移动工具入口，关闭的侧栏抽屉泄漏阴影。站点抽屉现在提供语言、版本和仓库链接；阴影仅在打开时出现。 | check-shell.py、响应式浏览器回归 |
| 布局 | Book 目录重复编号，正文间距污染组件列表，Landing 内边距被覆盖，全局链接规则压掉打印下划线。现在收窄各自规则的作用范围。 | 浏览器审查回归及 SCSS 检查 |
| 语言与 schema | 分页及面包屑缺少翻译，部分语言文案与外观分组标题有误，schema 拒绝语言代码形式的译文提示。现在全部 32 种语言包含相应标签，生成的 schema 与解析器一致。 | check-i18n.py、generate-config-schema.py --check |
| 预设及替代呈现 | Terminal 当前行箭头选择器错误，焦点环半透明或被裁切，强制颜色丢失当前项标记，RTL 样式覆盖字体角色。定向规则现在保留这些状态；Marquee 重复行对辅助技术隐藏。 | 预设／SCSS 检查及浏览器无障碍覆盖 |
原审查需要限定的判断
原报告的优先级将构建失败、无障碍缺陷、文案和设计偏好放在同一组，不能全部 视为阻塞发布的问题。可复现的构建与输出缺陷应优先修复；外观一致性需要另行 确定验收标准。
“没有 TOC”不等于“右栏为空”。博客索引仍可能包含作者、分类、系列和标签云。 直接删除备用控件会让右栏无法收起，并使既有 RSS 浏览器回归失败。最终修复 只省略真正空的右栏；有内容但无 TOC 的右栏保留控件，标签改为侧栏操作，保留 收起、焦点恢复与 RSS 访问。
RSS 修复不要求每种组件都出现在 Feed 中。发布资产仍明确省略。Book 检查器
现在验证真实的分区 Feed，不再将原始 RenderShortcodes 输出当作 RSS 契约。
圆角不同、外壳模板重复、原生与短代码布局有差异，在确认具体契约或使用故障前， 属于维护或设计议题。仅因文件逐字节相同而合并 base 模板，可能改变 Hugo 模板 查找优先级。本轮不包含这类大范围合并。
验证
主题归属检查器、schema 一致性、32 种语言键一致性、80 个 JavaScript 单测和 90 个迁移单测均使用固定工具链执行。输出变化覆盖 52 个 HTML、打印、Markdown、 RSS 与 LLMS 快照。它们属于本地单元与输出证据，不宣称执行了独立 CI 的 PDF／EPUB 出版任务。
文档站最后一轮完整 make check 已通过，包含全部 64 个非浏览器测试；渲染链接
扫描使用了更大的 Node 堆。本地生产构建也已通过，每种语言生成 462 页，只有
约定接受的上游 LibSass 弃用警告。首轮浏览器验证完成全部 30 个无障碍测试；
保留分类右栏控件后，响应式分组的 117 个测试
通过。其余标准浏览器分组也分别通过：键盘 16、内容组件 70、代码块与 Landing
37、PRD5 8、主题颜色 10、社区反馈 42、外观 53、Expo 50、画廊 8、PlantUML
8、图表 19、表格查看器 15、标准对照 19，以及八语言／RTL 对照 6。标准浏览器
套件在这些运行中合计通过 508 个用例。后续针对新研究页及博客页的无障碍检查
通过全部 30 个用例。Escape 修复后，新预览上的外壳、博客与菜单回归为 56/56；
metrics 链接接入统一 URL 策略后的 Landing 检查也已通过。
上述浏览器计数对应本轮修复候选版本；共享工作树随后出现的独立对照界面改动 不包含在本记录的浏览器验收范围中。完成审计另行验证了语言及部署前缀下的导航 查找键，以及 Book 无效编号在 HTML、打印、Markdown、BookManifest 和生成索引 中的回退行为。
剩余工作与顺序
本轮是有范围的修复，以下事项尚未纳入验收：
- 单字符快捷键的读者开关、命令面板交接与错误信息本地化，以及贡献者、搜索、 代码行数的多语言复数规则。
- 非默认语言 Google 搜索目的地，以及内容相对 URL 的文档语义。
- 其余对比度用例与历史记录中的窄屏、大字号页脚溢出，需要各自的渲染复现和 浏览器检查。
- 几何、交互状态及弹层令牌、其余手册链接实现、共享外壳结构和样式表体积。 这些需要有范围的设计决策与测量，不适合一次性替换所有字面量。
本轮开发行为记录在组件、 外壳、 架构与 Landing契约中，历史发布 声明保持原状。