docs(admin): 后台文档与 hint 补齐 + 修复 config.yml 重复键结构缺陷（5g T6）

- docs/管理台.md 扩写 25→156 行（原文要点全保留，131 增 0 删）：四集合总表、块编辑九类（字段+示例 yaml+预览限制）、页面排版覆盖（含整页换字体的体积成本提醒）、theme 17 旋钮分组约束、首页三字段、开源页六字段 + include 未命中排查 + README 回落矩阵四级（把 T5 的"相对链接不重写/ 徽章不阻断"两条限制落到用户文档） - docs/写作指南.md：首页可配项补三行、新增「页面块」字段速查节（含 ≤24 块/≤4000 字/未知块跳过/空则回落 intro 的边界）、字体子集化段（694KB→420KB −40% + subset-fonts.py 命令）、加字流程第④步挂子集化 - 后台 hint 49→64：九类块型说明、tagline/blurb、font 下拉体积提醒、scale 取值范围 - **修 config.yml 结构缺陷（重要）**：typography 对象被插进双语字段的 name: 与 widget: object 之间，导致重复键 widget/fields（后者覆盖前者）→ 后台 tagline/blurb 退化成字符串写入、排版选择器字段被劫持。已挪到双语字段之后，恢复 object+zh/en 结构（重复键检测：修前 4 处 → 修后 0） - 新增 scripts/build-perf/config-check.py：用自定义 StrictLoader 在解析阶段对重复键报错（Python 默认 safe_load 静默覆盖是本次漏检根因）+ hint 覆盖率体检；build.sh 守卫挂载（[ -f ] 先行，与既有闸门同级）验证: 构建 48 页 exit 0；E2E 37/37；content-lint 49 页 0/0/0；对比度闸门 4 项 PASS；config-check 五文件全 OK + 206 字段/64 hint Spec: 2026-11-02_blog-5g-pages (T6) Co-authored-by: GLM-5.3
2026-11-02 19:16:43 +08:00
1 parent 3e09a362cc
commit 8274180f81
@@ -153,6 +153,18 @@ https://astro.build/

 体积账结论（2026-11-02 实测，本地无 gzip 的相对值）：**未使用某字体的页面，字体字节增量恒为 0**（构建期按页子集化 + unicode-range 按需拉取）。汇文采用文风开源的 cn-font-split 切片包（339 片），实测只拉用到字符的 19 片。

+**再裁一刀（按本站实际用字子集化）**：切片包本身粒度粗（一片含数百字），只做标题/短句的艺术字体往往只用到几十个字符。`scripts/build-perf/subset-fonts.py` 读字体 CSS 的 `@font-face`、收集内容里真实出现的字符、逐片求交集后用 `pyftsubset` 重写——实测汇文整页 **694KB → 420KB**（约 −40%）。命令：
+
+```bash
+python3 scripts/build-perf/subset-fonts.py \
+  --css node_modules/@fontsource/huiwen-mincho/index.css \
+  --out public/fonts/subset/huiwen \
+  --chars-from content/posts content/moments content/site/*.yaml
+# 可选：--chars-mode all|headings（只统计标题字）、--min-bytes 4096（小于该值的片不裁）
+```
+
+子集化产物输出到 `--out` 指定目录（如 `public/fonts/subset/`）；把它接进站点（构建链挂守卫 + 字体 CSS 指向子集）是独立一步，接线后随构建自动生成，未接线前需手动跑。**换字/加字后重跑一次**，否则新字会回落到下一个切片或系统字体。
+
 ### 候补字体清单（未落地，加一款约"一条命令 + 一次体积账"）

 | 字体 | 许可证 | 允许 webfont 嵌入 | 未落地原因 |
@@ -168,7 +180,7 @@ https://astro.build/
 | 阿里妈妈东方大楷 / 演示悠然小楷 | 免费商用 / 个人免费 | ⚠️ 需逐款核嵌入条款 | 无包；"个人免费"字体常禁 @font-face |
 | 霞鹜文楷 Light/Bright | OFL-1.1 | ✅ | 实测 **+8605KB**（CJK 切片粒度所致） |

-> 加新字体的流程：①核许可证与 **web 嵌入条款**（很多"个人免费"字体明文禁 @font-face，只能进系统回退）②npm 装或放入 `public/fonts/<family>/`（优选 cn-font-split 类切片包）③`global.css` 加类 + `rehype-class-whitelist` 放行 + `public/admin/typography-classes.js` 加一项 ④跑体积账，超 150KB/页 的要评估是否值得。
+> 加新字体的流程：①核许可证与 **web 嵌入条款**（很多"个人免费"字体明文禁 @font-face，只能进系统回退）②npm 装或放入 `public/fonts/<family>/`（优选 cn-font-split 类切片包）③`global.css` 加类 + `rehype-class-whitelist` 放行 + `public/admin/typography-classes.js` 加一项 ④跑体积账，超 150KB/页 的要评估是否值得；展示类字体再跑一次 `scripts/build-perf/subset-fonts.py` 按实际用字裁切（命令见上节）。

 ```markdown
 <span class="ink-muted">次要说明</span>
@@ -211,6 +223,34 @@ typography:

 **层 3 · 艺术字体**：`font-art-kuaile`（站酷快乐体，艺术字专用类）。⚠️ **仅用于标题/短句**：艺术字字形大，CJK 切片体积高（实测用到页 +163KB），长段使用会显著抬高单页字体成本。

+## 页面块（关于页 blocks，字段速查）
+
+关于页正文可由九个块拼成（后台拖拽排序，每块有「显示」开关）。完整操作见 [管理台](./管理台.md)；这里是写内容时对照的字段表——文本字段一律 `{zh, en}`。
+
+| 块型 | 必填 | 可选 | 一句话 |
+|---|---|---|---|
+| `prose` | `body` | `title`、`width`（narrow/full） | markdown 长文 |
+| `tracks` | `title`、`items[].name` | `items[].icon`、`items[].desc` | 主线/能力面 |
+| `cards` | `items[].title` | `title`、`columns`(2/3)、`items[].desc/href/tag` | 并列卡片墙 |
+| `timeline` | `items[].time`、`items[].title` | `title`、`items[].desc` | 时间线（时间可自由文本） |
+| `quote` | `text` | `cite` | 单句引文 |
+| `figure` | `image` | `alt`、`caption` | 单图（必须上传，禁外链） |
+| `linklist` | `items[].label`、`items[].href` | `title`、`items[].note` | 链接清单 |
+| `cta` | `text`、`href`、`label` | — | 行动按钮 |
+| `divider` | — | `style`（line/space） | 分隔 |
+
+```yaml
+blocks:
+  - type: prose
+    body: { zh: 正文 markdown，可含排版类 span, en: Body markdown }
+  - type: cards
+    columns: 3
+    items:
+      - { title: { zh: 写作, en: Writing }, desc: { zh: 书评与技术文, en: Reviews & tech } }
+```
+
+边界：块数 ≤24、单块文本 ≤4000 字（超限截断并 WARN）；未知块型跳过 + WARN；`blocks` 为空时回落 `intro` markdown，再空回落内置文案。图片字段走 `image()`，只能后台上传进 `content/site/assets/`。
+
 ## 发布提醒

 - push main → webhook 自动构建发布（约 10 秒）
@@ -303,6 +343,9 @@ markdown 原生语法，无需任何配置：
 | `latestPhotos` | 0-6 | 4 | 「最新影像」张数；**0 = 隐藏该区块** |
 | `perTrackLimit` | 4-8 | 6 | 首页阅读/技术两轨各显示条数 |
 | `sections` | `{tracks, photos, heatmap, projects}` 布尔 | 全开 | 区块开关，关掉即不渲染 |
+| `projectsLimit` | 1-99 | 6 | 首页项目墙条数（越界夹取） |
+| `announcement` | `{zh, en}`（markdown 富文本） | 空 | 名片区下方公告；空 = 不渲染 |
+| `postsTracks` | `{reading, tech, photo}` 布尔 | 全开 | 关掉某轨则该轨文章不在首页列出（归档页仍可见） |

 越界值会被夹取（如 perTrackLimit=20 按 8 处理），不报错；**全部留空 = 现有形态不变**。

@@ -1,17 +1,148 @@
 # 管理台（Sveltia CMS）使用指南

 > 地址：`https://wait4x.online/admin/`（页脚「管理」入口）｜ 用途：照片上传与 sidecar 编辑的图形界面 ｜ 保存即 commit 到 main → webhook 自动构建发布（约 10 秒上线）
+>
+> 这份是**操作手册**：每个入口能改什么、字段怎么填、改完会发生什么。写文章正文的排版技巧见 [写作指南](./写作指南.md)——两份分工：这里讲"后台怎么用"，那里讲"正文怎么写"。

 ## 登录

 选 **Sign In with Token** → 用 gitea 的 access token（宿主 `~/docker_apps/gitea/init-templates.txt` 里的 api-token，或 gitea 网页新建 scope=read/write:repository）。token 存浏览器 localStorage，下次免登。

+## 四类内容集合
+
+| 入口 | 文件位置 | 用来放什么 | 关键约束 |
+|---|---|---|---|
+| 文章 | `content/posts/<slug>.md` | 书评 / 技术文 / 摄影札记三轨 | `category` 三选一（`reading` / `tech` / `photo`），首页分轨由它派生 |
+| 瞬间 | `content/moments/*.md` | 一句话 + 一张图的时间线 | `text` 与 `image` **至少填一项**（后台无法表达条件必填，保存前自查） |
+| 照片 | `content/photos/*.json` + 图 | 图库（街拍 / 风景两组） | 标题**必填**（空标题会让构建炸，实测坑）；EXIF 由构建期 loader 自动补全 |
+| 站点页面 | `content/site/*.yaml` | 首页、关于页、开源页、主题 | 后台改的是**单例文件**，没有"新建" |
+
+几条通用规则：
+
+- **双语字段成对出现**：中文 / 英文两个输入框。英文留空不是错误——构建期回落中文并在日志里打 WARN（`[blocks] 缺译…`），页面不会破版。
+- **留空 = 用默认**：任何字段清空都回到仓库自带的默认文案 / 默认值，构建永远成功。想让某段彻底消失，请看字段自带的"留空则不渲染"提示。
+- **文章英文版**：不在后台写。跑 `python3 scripts/translate/translate_posts.py` 生成 `content/posts-en/` 同名文件；手写润色过的译文在 frontmatter 写 `locked: true`，翻译脚本会无条件跳过它。
+- **保存即提交**：后台保存等于向仓库提交，push 后约 10 秒自动构建上线。
+
 ## 照片上传流

 1. 图库照片 → New Entry：填标题（**必填**，空标题会让构建炸——实测坑）、选分组（street/landscape）、可写 alt
 2. 图片字段 → 资产库上传 jpg（与 sidecar 同目录落位，零重压缩）
 3. Save → 自动 commit + 构建 → 画廊出现（EXIF 构建期自动提取，exif 字段留空即可）

+## 块编辑：关于页的块式页面构建器
+
+关于页（`content/site/about.yaml`）的正文由 **blocks 列表**构成，后台里是一串可拖拽排序的卡片。每个块都有「显示」开关；关掉只是不渲染，块本身留在数据里。
+
+两条渲染纪律：
+
+- 列表为空（或全关）时，页面回落到 `intro` 字段的 markdown 正文；`intro` 也空则用内置默认文案。三级回落，任何一级为空都不会出白页。
+- 未知块型（手工编辑 yaml 写错的 `type`）会被**跳过并打印 `[blocks]` 警告**，不会炸构建；块数上限 24，单块文本上限 4000 字，超限截断并 WARN。
+
+九类块与字段（文本字段一律 `{zh, en}` 双语对象）：
+
+| 块型 | 必填 | 可选 | 用途 |
+|---|---|---|---|
+| `prose` 正文 | `body` | `title`、`width`（`narrow` 版心 / `full` 通栏） | markdown 长文，最常用 |
+| `tracks` 版图 | `title`、`items[].name` | `items[].icon`、`items[].desc` | 几条主线 / 能力面，图标白名单外或留空显示首字占位 |
+| `cards` 卡片墙 | `items[].title` | `title`、`columns`（2 或 3，默认 3）、`items[].desc/href/tag` | 并列展示若干条目 |
+| `timeline` 时间线 | `items[].time`、`items[].title` | `title`、`items[].desc` | 时间列是自由文本（`2024 — 2026` 也行） |
+| `quote` 引文 | `text` | `cite` | 单句金句，配 `font-kai` 更出效果 |
+| `figure` 图片 | `image` | `alt`、`caption` | **只能后台上传**（落 `content/site/assets/`，走图片管线），禁止外链 |
+| `linklist` 链接清单 | `items[].label`、`items[].href` | `title`、`items[].note` | 相关阅读 / 外部资源 |
+| `cta` 行动按钮 | `text`、`href`、`label` | — | 一页建议不超过一个 |
+| `divider` 分隔 | — | `style`（`line` 细线 / `space` 纯留白） | 长页分段 |
+
+yaml 形态示例（手工编辑时照此写）：
+
+```yaml
+blocks:
+  - type: prose
+    title: { zh: 关于这个站点, en: About this site }
+    body:
+      zh: 这里写 markdown 正文，支持列表、粗斜体、链接与排版类。
+      en: Markdown body here.
+    width: narrow
+  - type: quote
+    text: { zh: 所谓暮色，就是光慢慢地承认自己要走。, en: Dusk is light admitting it has to go. }
+    cite: { zh: 本站, en: this site }
+  - type: figure
+    image: ./assets/desk.jpg   # 后台会替你写成这个相对路径
+    caption: { zh: 工作台一角, en: A corner of the desk }
+```
+
+其它可用字段：`layout.showIdCard`（关掉则不渲染名片区，默认开）、`typography`（见下一节）。
+
+**预览限制**：后台只提供字段编辑与列表摘要（摘要显示块型名），块的真实排版以下次构建后的页面为准——想调间距 / 字号，请用「主题设置」而不是在块里硬凑空行。
+
+## 页面排版覆盖（每页一处）
+
+首页 / 关于页 / 开源页各自有一个「页面排版覆盖（可选）」对象：
+
+| 字段 | 取值 | 说明 |
+|---|---|---|
+| `font` | 字族下拉（10 项） | 本页**正文**默认字体类 |
+| `accent` | 颜色下拉（18 项） | 本页强调色类 |
+| `scale` | 0.8–1.25 | 字号缩放，1 = 全站默认 |
+
+- 只作用于**该页内容容器**（挂 `.page-typo` + CSS 变量），不写全站 tokens，其它页面零影响。
+- **体积成本提醒**：整页换艺术/展示字族（`font-huiwen` 汇文、`font-kuaile` 快乐体）意味着整页正文都要下载对应切片——单页字体成本会明显抬升，见写作指南的体积账。
+- 白名单外的类名会被忽略（构建期过滤），写错不报错、也不生效。
+
+## 主题设置（全站 17 个旋钮）
+
+「主题设置」入口写 `content/site/theme.yaml`，17 项全部可选，留空 = 仓库默认值。**配错不会炸站**：越界值回落默认，组内单调性被破坏则整组回落。
+
+| 组 | 字段 | 范围 | 约束语义 |
+|---|---|---|---|
+| 强调色 | `accent_light` / `accent_dark` | `#rrggbb` | 明暗各一份；构建期对比度闸门断言正文 ≥4.5:1，不达标构建失败 |
+| 圆角 | `radius_img` | 4–16 | 图片圆角，建议 ≤14 |
+| 标题字号 | `text_h1` / `text_h2` / `text_h3` | h1/h2：22–32，h3：16–32 | **必须严格递减**（h1 > h2 > h3），否则三档一起回落默认 |
+| 正文字号 | `prose_size_reading` / `prose_size_tech` | 16–22 | 书评 / 技术文分轨独立 |
+| 行高 | `leading_reading` / `leading_tech` | 1.5–2.0 | 同上分轨 |
+| 间距梯度 | `space_3` / `space_4` / `space_5` / `space_6` | 8–80 | **必须严格递增**，否则整组回落 |
+| 流距 | `flow_p` / `flow_h2_post` | 0–2（em） | 段间距 / 标题下间距 |
+| 动效 | `dur` | 150–600（ms） | 过渡时长；`prefers-reduced-motion` 下自动归零 |
+
+不能配的东西（有意为止）：版心宽度、断点、纸墨色、代码配色——它们牵动版面结构与分轨身份，属于设计红线。注入方式是构建期内联 `:root:root{…}`，运行时零 JS、零请求。
+
+## 首页与开源页的其余旋钮
+
+### 首页三字段（5g 新增）
+
+| 字段 | 取值 | 默认 | 作用 |
+|---|---|---|---|
+| `projectsLimit` | 1–99 | 6 | 首页项目墙条数（越界夹取） |
+| `announcement` | `{zh, en}` markdown | 空 | 名片区下方公告；**空 = 不渲染**，走富文本管线（可写排版类 span） |
+| `postsTracks` | `{reading, tech, photo}` 布尔 | 全开 | 关掉某轨，该轨文章不在首页列出（归档页仍可见） |
+
+### 开源页（opensource.yaml）
+
+| 字段 | 取值 | 说明 |
+|---|---|---|
+| `pinned` | 仓短名数组 | 置顶顺序即展示顺序 |
+| `mode` | `all` / `only` / `exclude` | 可见性模式 |
+| `include` / `exclude` | 仓短名数组 | 对应模式的白 / 黑名单 |
+| `sort` | `pinned-first` / `stars` / `updated` | 排序 |
+| `perSource` | `both` / `github` / `gitea` | 来源过滤 |
+| `intro_from` | `"off"` / `"github-readme"` | 开篇文案来源（**带引号写**，YAML 1.1 里裸 `off` 是布尔 false） |
+
+**`mode: only` 的"看不见"排查**：构建日志会给每个没显示出来的 include 项打一行 `[opensource] projects：include 里的「X」…`，并区分两种原因——双源结果里根本没有这个仓（拼写 / 私有仓 / 该源刚失败），或者命中了但被 `perSource` 过滤掉。看到哪一行就知道该改什么。
+
+**README 开篇（`intro_from: "github-readme"`）的回落矩阵**，构建日志逐级点名：
+
+1. 取到 → 内容有变化才刷新缓存 `content/.github-readme.md`（入仓，保证构建确定性）
+2. token 缺位 / HTTP 非 2xx / 内容为空 / 超时（10 秒）/ 网络异常 → 改用缓存（日志标注"可能陈旧"）
+3. 缓存也不在 → 回落本文件 `blurb` 的叙述文案
+4. 缓存回写失败（构建仓只读挂载等）→ 只告警，本次渲染照常
+
+token 位在 `~/docker_apps/blog/github-token.txt`（本机，0600）。
+
+**两条已知限制**：
+
+- **README 里的相对链接不重写**（如 `./img/x.png`、`docs/foo.md`）：它们相对 GitHub 仓根解析，在本站没有对应产物，点了多半 404。保原样比猜一个基址可信，所以不做改写。
+- **外部徽章图片加固但不参与构建**：shields.io、readme-typing-svg 这类第三方徽章在构建期**不抓取**，渲染时统一补 `loading="lazy"`（缺 alt 补空），它们慢、被墙或 404 都不影响页面渲染；尺寸已由样式限制在内容宽度内。
+
 ## 纪律（与写作指南同源）

 - **图片体积**：上传前自行压缩（长边 ≤2400px）——Sveltia 内建优化**刻意关闭**（会抹 EXIF 断构建期提取管线）