refactor(home): 首页三字段默认值收敛到 SITE_DEFAULTS（5g T4 补）

- SITE_DEFAULTS 新增 homeProjectsLimit=6 / homeAnnouncement(空) / homePostsTracks(全开)，访问器改为引用默认常量而非散落字面量 - 旧 yaml（无三字段）零回归实测：公告不渲染、项目墙默认 6 条、三轨全开验证: 构建 48 页 exit 0；E2E 37/37（快照口径） Spec: 2026-11-02_blog-5g-pages (T3/T4 补充) Co-authored-by: GLM-5.3
feat(theme-home): 样式即数据 + 首页抽组件去重（5g T3/T4）
2026-11-02 19:02:41 +08:00 · 2026-11-02 18:58:11 +08:00 · 2026-11-02 18:42:36 +08:00 · 2026-11-02 18:40:32 +08:00 · 2026-11-02 18:21:33 +08:00 · 2026-11-02 18:13:47 +08:00
572 changed files with 10654 additions and 698 deletions
@@ -0,0 +1,84 @@
+# Phase 5g：页面后台化（blocks 模型）与字体子集化 - 项目范围
+
+<!-- spec-format: 2 -->
+
+## 1. 问题定义
+- **项目目标**：①按 docs/research/10 方案 E 把关于页改造成「块式页面构建器」（结构可增删排序）②样式即数据（theme.yaml → 构建期 CSS 变量，含对比度闸门）③首页字段细化并抽 HomePage 消 zh/en 双份 ④开源页收尾（README 缓存/回落/告警）⑤后台文档与 hint 补齐 ⑥字体子集化工具（把艺术字体单页增量从数百 KB 降到数十 KB）
+- **目标用户**：站长（希望整页可编辑、能上更多艺术字体）与读者（版式与可读性不退化）
+- **核心价值**：内容与结构的编辑权交回后台，同时守住灰阶体系/双语/SEO/构建期零运行时四条红线
+
+## 2. 假设与待确认
+
+### 2.1 已确认事实
+- Sveltia 0.252 支持 list 的 types + typeKey（方案 10 §3.4 从本仓 bundle 取证），块模型可行
+- 页面文案 markdown 净化（D1/D2）已在 2cab243 落地（P0 完成）
+- 字体实测：@fontsource CJK 切片粒度导致单页 +163KB~+8605KB；现有 6 自托管族为基线
+
+### 2.2 关键假设
+- 块渲染器受控，破版风险低于整页 HTML 直编（方案 10 §2 对比表）
+- 字体子集化（pyftsubset 按页实际用字）能把艺术字体单页增量压到 ≤150KB 阈值内
+
+### 2.3 待确认问题
+- [x] 关于页整页可编辑路线 → 用户 2026-11-02 批准方案 E（blocks + theme.yaml + 局部自由区）
+- [x] 字体扩充路线 → 先落 6 族，其余按子集化工具就绪后再评估（本包 T7 交付工具）
+
+### 2.4 可选解释与取舍
+- 关于页保留 intro markdown 通道作为 compat（blocks 为空时三级回落：blocks → intro → 默认文案）
+- 样式即数据只开放白名单旋钮（约 12 项），不开放整份 tokens.css
+- 图片只走 Astro image() 管线，禁止块内填外链/绝对路径（schema 层拦）
+
+### 2.5 已证伪路径
+- 整页富文本直编（C 方案）：XSS 面大、无设计兜底，弃
+- 新增 webfont 直接上（不子集化）：单页 +535KB~+8605KB，超阈值，弃（改走 T7 工具）
+
+## 3. 功能范围
+
+### 3.1 核心功能（MVP）
+- [ ] T1 blocks 骨架：schema（discriminatedUnion）+ page-blocks.ts + BlockRenderer + prose/tracks/divider 三块 + 后台 types 声明
+- [ ] T2 块型扩充：cards/timeline/quote/figure/linklist/cta + 图标键白名单 + 图片 image() 管线
+- [ ] T3 样式即数据：theme.yaml + theme.ts + BaseLayout 内联变量 + 对比度闸门脚本
+- [ ] T4 首页细化与去重：抽 HomePage.astro 消 zh/en 双份 + 字段细化（projectsLimit/announcement 等）
+- [ ] T5 开源页收尾：README 缓存策略/超时/回落矩阵 + fallback JSON 回填 + include 未命中 WARN
+- [ ] T6 文档与 hint：docs/管理台.md（块编辑用法）+ 写作指南扩充 + admin 全字段中文 hint
+- [ ] T7 字体子集化工具：按页用字裁剪艺术字体为小切片 + build.sh 守卫挂载 + 实测对比
+
+### 3.2 扩展功能
+- 无
+
+### 3.3 不在范围内
+- 换 CMS、页面布局的任意拖拽网格、运行时编辑器
+
+## 4. 最小实现路径
+- 最简单可行方案：块类型先用 3 类跑通闭环（prose/tracks/divider），再扩到 9 类；theme 只做 12 个白名单旋钮
+- 暂不引入：可视化块预览、块级动画配置
+- 不做的抽象：通用页面 DSL（只服务现有页面）
+
+## 5. 技术决策
+- 技术栈：Astro 7.4.4 + zod discriminatedUnion + Sveltia list/types + pyftsubset（fonttools）
+- 证据协议：evidence: runs
+- 本轮允许改动：src/content.config.ts、src/lib/{page-blocks,theme,site-content}.ts、src/components/blocks/*、src/components/pages/{AboutPage,HomePage}.astro、src/pages/{index,en/index,opensource,en/opensource}.astro、src/layouts/BaseLayout.astro、public/admin/*、content/site/*.yaml、scripts/build-perf/*、infra/deploy/build.sh、docs/*、tests/e2e.mjs
+- 本轮不应触碰：nginx/ESA、图库灯箱（GalleryPage/PhotoZoom）、Header/Footer 结构
+- Git integration branch：`spec/2026-11-02_blog-5g-pages`
+
+### 5.1 验证策略
+- 范围级别：package
+- 变更对象：页面数据模型与渲染器、后台配置、样式变量生成、字体产物、文档
+- 快速检查：`pnpm astro build`（node26）
+- 集成检查：`node tests/e2e.mjs`（37 项，本包预期新增块/主题断言）+ content-lint 0/0/0
+- 全项目检查：字体体积账（三页增量）+ 视觉复核（glm-5.3-flash:max，块版式与主题变量双态）；仅在构建链或 BaseLayout 结构再变更时升级范围
+- 升级触发：若 theme 变量波及全局排版（字体字号全站变化）或 blocks 改动触及首页/文章页结构，升级为全站视觉复核与 E2E 全量并记录理由
+
+## 6. 成功标准与验证方式
+- [ ] 关于页整页由 yaml blocks 驱动，增删排序生效 -> verify: task_0001
+- [ ] 九类块全部可渲染且旧内容零回归（三级回落） -> verify: task_0002
+- [ ] theme.yaml 改值 → 产物 CSS 变量变化，对比度闸门拦截不达标 -> verify: task_0003
+- [ ] 首页 zh/en 由同一组件渲染且字段可配 -> verify: task_0004
+- [ ] 开源页 README 失败矩阵与 fallback 告警可用 -> verify: task_0005
+- [ ] 后台文档与 hint 完整 -> verify: task_0006
+- [ ] 字体子集化工具把指定字体单页增量压到 ≤150KB -> verify: task_0007
+
+## 7. 风险与约束
+- 灰阶体系与双语红线不变；彩色仅正文强调
+- 块渲染器未知类型跳过 + WARN，绝不炸构建
+- 字体子集化需保证字形覆盖（裁错字会出现豆腐块）→ 断言：子集后页面文本逐字命中
+- 多车道并行：共享文件（content.config.ts/admin config/docs）按 boundary 划界，tokens/global 由 orchestrator 或指定单车道
@@ -0,0 +1,42 @@
+# Phase 5g：页面后台化（blocks 模型）与字体子集化 - 任务拆解
+
+## 使用规则
+- boundary/verify 齐备；verify 只读断言；车道工作树开发禁 git，收编由 orchestrator 统一提交
+- 构建一律 `export PATH="$HOME/.local/node/bin:$PATH"`（Node 26）
+
+## 阶段一：实现
+
+- [x] T1 blocks 骨架（关于页块式页面构建器）
+  - claim: op-gitea
+  - boundary: src/content.config.ts（siteAbout 加 blocks: z.array(discriminatedUnion)）、新增 src/lib/page-blocks.ts（getAboutBlocks：过滤 enabled、未知 type 跳过+WARN、文本 pickBi 回落、块数≤24/单块≤4000 字）、新增 src/components/blocks/{BlockRenderer,Prose,Tracks,Divider}.astro、AboutPage.astro 改由 blocks 驱动（blocks 空→intro markdown→默认文案三级回落）、public/admin/config.yml 加 list+types（typeKey: type）
+  - verify: `E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q "37/37 PASS" && grep -q "discriminatedUnion" src/content.config.ts && grep -q "BlockRenderer" src/components/pages/AboutPage.astro && grep -q "typeKey" public/admin/config.yml`
+
+- [x] T2 块型扩充与图片管线
+  - claim: op-gitea
+  - boundary: 新增 src/components/blocks/{Cards,Timeline,Quote,Figure,LinkList,Cta}.astro + 图标键白名单（复用 SocialLinks 注册表或新建 icons 注册表）、schema 块型补全（图片字段用 image()，禁止外链字符串）、content/site/assets/ 目录、near docs 图表说明
+  - verify: `E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q "37/37 PASS" && ls src/components/blocks/ | grep -qC1 "Cards\|Timeline" && grep -q "image()" src/content.config.ts`
+
+- [x] T3 样式即数据（theme.yaml + 对比度闸门）
+  - claim: op-artalk
+  - boundary: 新增 content/site/theme.yaml（12 个白名单旋钮：prose-size/measure/radius/accent/leading 等）、新增 src/lib/theme.ts（getTheme + themeVarsCss 生成 :root:root{…}）、BaseLayout.astro head 内联 theme 变量（构建期静态）、新增 scripts/build-perf/contrast-check.mjs（断言 theme 结果下正文对比度 ≥4.5）、public/admin/config.yml 加 theme 单例、build.sh 守卫挂载
+  - verify: `E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q "37/37 PASS" && test -f content/site/theme.yaml && node scripts/build-perf/contrast-check.mjs dist`
+
+- [ ] T4 首页细化与去重
+  - claim: op-artalk
+  - boundary: 新增 src/components/pages/HomePage.astro（承接现 index.astro 区块逻辑，locale prop）、src/pages/{index,en/index}.astro 改为薄壳、home.yaml 增 projectsLimit / announcement（markdown）/ postsTracks（轨开关细分），site-content 访问器同步
+  - verify: `E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q "37/37 PASS" && test -f src/components/pages/HomePage.astro && grep -q "HomePage" src/pages/en/index.astro`
+
+- [x] T5 开源页收尾（缓存/回落/告警）
+  - claim: worker-one
+  - boundary: src/lib/site-content.ts（README 缓存策略与超时、回落矩阵）、content/.github-readme.md 与 README HTML 剥离策略（复用 rehype-content-sanitize 已挡危险标签；补: 外链徽章不阻断）、src/data/projects-fallback.json 回填 5-8 条真实仓、projects.ts include 未命中 console.warn
+  - verify: `E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q "37/37 PASS" && python3 -c "import json;d=json.load(open('src/data/projects-fallback.json'));assert len(d)>=5"`
+
+- [ ] T6 文档与后台 hint 补齐
+  - claim: worker-one
+  - boundary: docs/管理台.md（块编辑怎么用、增删排序、预览限制）、docs/写作指南.md（块字段表/受限类/主题项）、public/admin/config.yml 全字段中文 hint（含 T1-T4 新增字段）
+  - verify: `test -f docs/管理台.md && grep -q "blocks\|区块" docs/管理台.md && grep -c "hint" public/admin/config.yml | awk '$1>=20'`
+
+- [x] T7 字体子集化工具
+  - claim: orchestrator
+  - boundary: 新增 scripts/build-perf/subset-fonts.py（pyftsubset 按指定字体 + 页面实际用字生成子集 woff2 + 重写 fonts.css 指向子集文件）、infra/deploy/build.sh 守卫挂载、docs/写作指南加字流程补"子集化"一节
+  - verify: `test -f scripts/build-perf/subset-fonts.py && python3 -c "import fontTools; print('fonttools ok')" && E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q "37/37 PASS"`
@@ -0,0 +1,95 @@
+# Phase 5f：SEO 解封与功能优化批 + 美化首批 - 完成总结
+
+## 交付结论
+- 结果：完成
+- 完成时间：2026-11-01 09:51
+
+## 假设回顾
+### 已验证假设
+- nginx sudo 与 ESA 控制台由用户操作（本包只备好仓库侧与操作单）
+- 视觉裁定为终态依据；实现与裁定冲突时以裁定为准并在完成总结记录
+
+### 仍未完全验证的假设
+- 无
+
+## 交付范围
+### 已交付
+- T1 SEO 仓库侧三件（robots.txt + admin noindex 预案 + 用户操作单）
+- T2 localePath 双 en 修复 + 自指 canonical + 尾斜杠归一
+- T3 构建期内容 lint + 生产冒烟 + build.sh 守卫挂载
+- T4 reader 纯文本模式（html.reader + 命令面板 + r 键 + 持久化）
+- T5 代码块窗条（P 卡：≥4 行灰阶窗+mono 标题+灰阶三点）
+- T6 书评纸面板（Q 卡：圆角米灰纸卡+暗色暖棕+hairline 边框）
+- T7 版式基底（K/L/O 卡：流距 token+灰阶补档+暗色 hairline 降档+微交互曲线+focus ring）
+- T8 首屏 tagline + 图库质感（M/N 卡：身份语+圆角统一+暗色衬底）
+
+### 未交付
+- 无
+
+### 偏差说明
+- 无
+
+## 简化决策
+### 保持简单的关键选择
+- 最简单可行方案：token 值级 CSS 改动为主 + locale.ts 单函数修 + 两个构建脚本；无新依赖
+- 暂不引入：blur-up 占位（需管线）、独立设置面板
+- 不做的抽象：主题引擎化/样式体系重构（tokens 增量演化）
+
+### 本轮明确不做的内容
+- nginx/ESA 实际操作（用户侧）；draft 路由 D、评论数 F、EXIF 卡 G、title H（本月批后续包）
+
+## 变更边界
+### 本轮主要改动模块
+- 见 tasks.md 的 boundary 记录
+
+### 明确未触碰的区域
+- nginx/ESA 实际操作（用户侧）；draft 路由 D、评论数 F、EXIF 卡 G、title H（本月批后续包）
+
+## 验证证据
+### 备注
+- 机器证据：runs.jsonl（见验证范围的机器验证率）
+
+## 验证范围
+- 级别：package
+- 机器验证率：8/8
+- 规则：check 与 done 复用该范围；只有记录升级触发时才执行全项目检查
+
+## 哲学生效证据
+### 行为成效回填
+- Development Record 行为门禁通过
+
+### 一致性门禁回顾
+- 验收面（checklist 或成功标准）已通过
+
+## Git 记录
+- 日期时间：2026-11-01 09:51
+- 范围：Phase 5f：SEO 解封与功能优化批 + 美化首批
+- 功能：T1 SEO 仓库侧三件（robots.txt + admin noindex 预案 + 用户操作单）；T2 localePath 双 en 修复 + 自指 canonical + 尾斜杠归一；T3 构建期内容 lint + 生产冒烟 + build.sh 守卫挂载；T4 reader 纯文本模式（html.reader + 命令面板 + r 键 + 持久化）；T5 代码块窗条（P 卡：≥4 行灰阶窗+mono 标题+灰阶三点）；T6 书评纸面板（Q 卡：圆角米灰纸卡+暗色暖棕+hairline 边框）；T7 版式基底（K/L/O 卡：流距 token+灰阶补档+暗色 hairline 降档+微交互曲线+focus ring）；T8 首屏 tagline + 图库质感（M/N 卡：身份语+圆角统一+暗色衬底）
+- 操作：提交 / 推送
+- 成效：Development Record 行为门禁通过
+- 提交：pending local commit
+- 提交区间：975cf5e58bf2846fc0c1e34a600725bcfe915f0e..23ea8e5a555a984cf0e8be46efecb718d26d3cdc
+- 推送：not-run (push stage follows commit)
+
+## AGENTS.md 增量提议
+```diff
+Phase 5f 教训与资产：①收官门禁代码化（spec_gate.py 首秀连环拦下五宗——E2E 口径错配/竞态雷/verify 管道笔误/5.1 双字段措辞/字段改名丢失，每次给出可执行下一步）；②E2E_BASE 覆写为 spec 验收标准姿势；③视觉双轨闭环（token 方案→flash:max 像素验收）；④? 浮层焦点竞态根治；⑤车道 verify 落点偏差随回执报告；⑥add -A 卷入在途车道第四次变体秒拆；⑦verify 断言禁用 -q 接管道；⑧spec 模板字段名不可创意改写（升级触发≠升级条件）。
+```
+
+## 被拒绝的扩展提议
+- 无
+
+## 门禁证据
+- check_spec_package.py exit 0
+
+## 遗留事项
+- 无；问题处置见下方结构化区块
+
+## 问题处置
+
+```json
+{
+  "issues": [],
+  "version": 1
+}
+```
@@ -0,0 +1,48 @@
+{"task": "task_0001", "cmd": "test -f public/robots.txt && grep -q \"Sitemap: https://wait4x.online/sitemap-index.xml\" public/robots.txt && grep -q \"Disallow: /admin\" public/robots.txt && grep -q \"SEO 解封操作单\" docs/上线检查单.md", "exit": 0, "duration_s": 0.005, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "b8b3033256d8436e1994365e0a4d843de899a400abcd303c4a3f8703bf7236ec", "at": "2026-11-01T01:31:23+00:00"}
+{"task": "task_0002", "cmd": "! grep -r \"/en/en/\" dist/ && grep -q 'rel=\"canonical\"' dist/en/archives/mian-sha/index.html && node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\"", "exit": 1, "duration_s": 0.669, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "b8b3033256d8436e1994365e0a4d843de899a400abcd303c4a3f8703bf7236ec", "at": "2026-11-01T01:31:23+00:00"}
+{"task": "task_0003", "cmd": "node scripts/build-perf/content-lint.mjs dist && bash -n infra/deploy/build.sh && test -x scripts/build-perf/prod-smoke.sh", "exit": 0, "duration_s": 0.06, "stdout_tail_sha256": "209fba8e31f47e3c0984b06e53b6dec06a74dcc59311dae22cca8323af4ad09f", "tree_fp": "b8b3033256d8436e1994365e0a4d843de899a400abcd303c4a3f8703bf7236ec", "at": "2026-11-01T01:31:23+00:00"}
+{"task": "task_0004", "cmd": "node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -q 'data-cmd=\"reader\"' src/components/CommandPalette.astro && grep -q \"html.reader\" src/styles/global.css", "exit": 1, "duration_s": 0.637, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "b8b3033256d8436e1994365e0a4d843de899a400abcd303c4a3f8703bf7236ec", "at": "2026-11-01T01:31:24+00:00"}
+{"task": "task_0005", "cmd": "node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rqE \"code-win|codebar|窗条\" src/pages/archives/", "exit": 1, "duration_s": 0.675, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "b8b3033256d8436e1994365e0a4d843de899a400abcd303c4a3f8703bf7236ec", "at": "2026-11-01T01:31:25+00:00"}
+{"task": "task_0006", "cmd": "node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rq \"paper\" src/components/ | grep -v node_modules", "exit": 1, "duration_s": 0.638, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "b8b3033256d8436e1994365e0a4d843de899a400abcd303c4a3f8703bf7236ec", "at": "2026-11-01T01:31:25+00:00"}
+{"task": "task_0007", "cmd": "node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -q \"flow-h2-pre\" src/styles/tokens.css && grep -q \"focus-visible\" src/styles/global.css", "exit": 1, "duration_s": 0.656, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "b8b3033256d8436e1994365e0a4d843de899a400abcd303c4a3f8703bf7236ec", "at": "2026-11-01T01:31:26+00:00"}
+{"task": "task_0008", "cmd": "node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rq \"tagline\" src/pages/index.astro src/components/ && grep -q \"radius-img\" src/styles/tokens.css", "exit": 1, "duration_s": 0.66, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "b8b3033256d8436e1994365e0a4d843de899a400abcd303c4a3f8703bf7236ec", "at": "2026-11-01T01:31:27+00:00"}
+{"task": "task_0001", "cmd": "test -f public/robots.txt && grep -q \"Sitemap: https://wait4x.online/sitemap-index.xml\" public/robots.txt && grep -q \"Disallow: /admin\" public/robots.txt && grep -q \"SEO 解封操作单\" docs/上线检查单.md", "exit": 0, "duration_s": 0.005, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "7c6557e6c8bfbe5baff62bc1881f03fd8d53750b60ad5fd843888b0db2932995", "at": "2026-11-01T01:31:48+00:00"}
+{"task": "task_0002", "cmd": "! grep -r \"/en/en/\" dist/ && grep -q 'rel=\"canonical\"' dist/en/archives/mian-sha/index.html && E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\"", "exit": 0, "duration_s": 15.103, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "7c6557e6c8bfbe5baff62bc1881f03fd8d53750b60ad5fd843888b0db2932995", "at": "2026-11-01T01:32:03+00:00"}
+{"task": "task_0003", "cmd": "node scripts/build-perf/content-lint.mjs dist && bash -n infra/deploy/build.sh && test -x scripts/build-perf/prod-smoke.sh", "exit": 0, "duration_s": 0.073, "stdout_tail_sha256": "209fba8e31f47e3c0984b06e53b6dec06a74dcc59311dae22cca8323af4ad09f", "tree_fp": "7c6557e6c8bfbe5baff62bc1881f03fd8d53750b60ad5fd843888b0db2932995", "at": "2026-11-01T01:32:04+00:00"}
+{"task": "task_0004", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -q 'data-cmd=\"reader\"' src/components/CommandPalette.astro && grep -q \"html.reader\" src/styles/global.css", "exit": 1, "duration_s": 14.313, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "7c6557e6c8bfbe5baff62bc1881f03fd8d53750b60ad5fd843888b0db2932995", "at": "2026-11-01T01:32:18+00:00"}
+{"task": "task_0005", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rqE \"code-win|codebar|窗条\" src/pages/archives/", "exit": 0, "duration_s": 14.413, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "7c6557e6c8bfbe5baff62bc1881f03fd8d53750b60ad5fd843888b0db2932995", "at": "2026-11-01T01:32:32+00:00"}
+{"task": "task_0006", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rq \"paper\" src/components/ | grep -v node_modules", "exit": 1, "duration_s": 14.48, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "7c6557e6c8bfbe5baff62bc1881f03fd8d53750b60ad5fd843888b0db2932995", "at": "2026-11-01T01:32:47+00:00"}
+{"task": "task_0007", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -q \"flow-h2-pre\" src/styles/tokens.css && grep -q \"focus-visible\" src/styles/global.css", "exit": 1, "duration_s": 14.192, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "7c6557e6c8bfbe5baff62bc1881f03fd8d53750b60ad5fd843888b0db2932995", "at": "2026-11-01T01:33:01+00:00"}
+{"task": "task_0008", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rq \"tagline\" src/pages/index.astro src/components/ && grep -q \"radius-img\" src/styles/tokens.css", "exit": 0, "duration_s": 14.446, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "7c6557e6c8bfbe5baff62bc1881f03fd8d53750b60ad5fd843888b0db2932995", "at": "2026-11-01T01:33:15+00:00"}
+{"task": "task_0001", "cmd": "test -f public/robots.txt && grep -q \"Sitemap: https://wait4x.online/sitemap-index.xml\" public/robots.txt && grep -q \"Disallow: /admin\" public/robots.txt && grep -q \"SEO 解封操作单\" docs/上线检查单.md", "exit": 0, "duration_s": 0.005, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "a7774fa671522fb695d781169a132c4dfe108f5de2a8fd911e8e2993f16f10e6", "at": "2026-11-01T01:34:48+00:00"}
+{"task": "task_0002", "cmd": "! grep -r \"/en/en/\" dist/ && grep -q 'rel=\"canonical\"' dist/en/archives/mian-sha/index.html && E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\"", "exit": 0, "duration_s": 14.521, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "a7774fa671522fb695d781169a132c4dfe108f5de2a8fd911e8e2993f16f10e6", "at": "2026-11-01T01:35:02+00:00"}
+{"task": "task_0003", "cmd": "node scripts/build-perf/content-lint.mjs dist && bash -n infra/deploy/build.sh && test -x scripts/build-perf/prod-smoke.sh", "exit": 0, "duration_s": 0.056, "stdout_tail_sha256": "209fba8e31f47e3c0984b06e53b6dec06a74dcc59311dae22cca8323af4ad09f", "tree_fp": "a7774fa671522fb695d781169a132c4dfe108f5de2a8fd911e8e2993f16f10e6", "at": "2026-11-01T01:35:02+00:00"}
+{"task": "task_0004", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -q 'data-cmd=\"reader\"' src/components/CommandPalette.astro && grep -q \"html.reader\" src/styles/global.css", "exit": 0, "duration_s": 14.398, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "a7774fa671522fb695d781169a132c4dfe108f5de2a8fd911e8e2993f16f10e6", "at": "2026-11-01T01:35:17+00:00"}
+{"task": "task_0005", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rqE \"code-win|codebar|窗条\" src/pages/archives/", "exit": 0, "duration_s": 14.495, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "a7774fa671522fb695d781169a132c4dfe108f5de2a8fd911e8e2993f16f10e6", "at": "2026-11-01T01:35:31+00:00"}
+{"task": "task_0006", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rq \"paper\" src/components/ | grep -v node_modules", "exit": 1, "duration_s": 14.653, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "a7774fa671522fb695d781169a132c4dfe108f5de2a8fd911e8e2993f16f10e6", "at": "2026-11-01T01:35:46+00:00"}
+{"task": "task_0007", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -q \"flow-h2-pre\" src/styles/tokens.css && grep -q \"focus-visible\" src/styles/global.css", "exit": 0, "duration_s": 14.506, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "a7774fa671522fb695d781169a132c4dfe108f5de2a8fd911e8e2993f16f10e6", "at": "2026-11-01T01:36:00+00:00"}
+{"task": "task_0008", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rq \"tagline\" src/pages/index.astro src/components/ && grep -q \"radius-img\" src/styles/tokens.css", "exit": 0, "duration_s": 14.668, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "a7774fa671522fb695d781169a132c4dfe108f5de2a8fd911e8e2993f16f10e6", "at": "2026-11-01T01:36:15+00:00"}
+{"task": "task_0001", "cmd": "test -f public/robots.txt && grep -q \"Sitemap: https://wait4x.online/sitemap-index.xml\" public/robots.txt && grep -q \"Disallow: /admin\" public/robots.txt && grep -q \"SEO 解封操作单\" docs/上线检查单.md", "exit": 0, "duration_s": 0.005, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "59aaab217ae63cfe6ec2718684c60490ecb25a65c0f1a3dd89920e9b7a6795a7", "at": "2026-11-01T01:40:05+00:00"}
+{"task": "task_0002", "cmd": "! grep -r \"/en/en/\" dist/ && grep -q 'rel=\"canonical\"' dist/en/archives/mian-sha/index.html && E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\"", "exit": 0, "duration_s": 14.603, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "59aaab217ae63cfe6ec2718684c60490ecb25a65c0f1a3dd89920e9b7a6795a7", "at": "2026-11-01T01:40:19+00:00"}
+{"task": "task_0003", "cmd": "node scripts/build-perf/content-lint.mjs dist && bash -n infra/deploy/build.sh && test -x scripts/build-perf/prod-smoke.sh", "exit": 0, "duration_s": 0.071, "stdout_tail_sha256": "209fba8e31f47e3c0984b06e53b6dec06a74dcc59311dae22cca8323af4ad09f", "tree_fp": "59aaab217ae63cfe6ec2718684c60490ecb25a65c0f1a3dd89920e9b7a6795a7", "at": "2026-11-01T01:40:19+00:00"}
+{"task": "task_0004", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -q 'data-cmd=\"reader\"' src/components/CommandPalette.astro && grep -q \"html.reader\" src/styles/global.css", "exit": 0, "duration_s": 14.487, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "59aaab217ae63cfe6ec2718684c60490ecb25a65c0f1a3dd89920e9b7a6795a7", "at": "2026-11-01T01:40:34+00:00"}
+{"task": "task_0005", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rqE \"code-win|codebar|窗条\" src/pages/archives/", "exit": 0, "duration_s": 14.324, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "59aaab217ae63cfe6ec2718684c60490ecb25a65c0f1a3dd89920e9b7a6795a7", "at": "2026-11-01T01:40:48+00:00"}
+{"task": "task_0006", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rq \"paper\" src/components/", "exit": 0, "duration_s": 14.598, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "59aaab217ae63cfe6ec2718684c60490ecb25a65c0f1a3dd89920e9b7a6795a7", "at": "2026-11-01T01:41:03+00:00"}
+{"task": "task_0007", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -q \"flow-h2-pre\" src/styles/tokens.css && grep -q \"focus-visible\" src/styles/global.css", "exit": 0, "duration_s": 15.156, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "59aaab217ae63cfe6ec2718684c60490ecb25a65c0f1a3dd89920e9b7a6795a7", "at": "2026-11-01T01:41:18+00:00"}
+{"task": "task_0008", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rq \"tagline\" src/pages/index.astro src/components/ && grep -q \"radius-img\" src/styles/tokens.css", "exit": 0, "duration_s": 14.487, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "59aaab217ae63cfe6ec2718684c60490ecb25a65c0f1a3dd89920e9b7a6795a7", "at": "2026-11-01T01:41:32+00:00"}
+{"task": "task_0001", "cmd": "test -f public/robots.txt && grep -q \"Sitemap: https://wait4x.online/sitemap-index.xml\" public/robots.txt && grep -q \"Disallow: /admin\" public/robots.txt && grep -q \"SEO 解封操作单\" docs/上线检查单.md", "exit": 0, "duration_s": 0.005, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "5e3805453ecab02ecf7d7db336ac16e05fa30d2b497ba655209e410c8c527dfd", "at": "2026-11-01T01:42:01+00:00"}
+{"task": "task_0002", "cmd": "! grep -r \"/en/en/\" dist/ && grep -q 'rel=\"canonical\"' dist/en/archives/mian-sha/index.html && E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\"", "exit": 0, "duration_s": 14.593, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "5e3805453ecab02ecf7d7db336ac16e05fa30d2b497ba655209e410c8c527dfd", "at": "2026-11-01T01:42:16+00:00"}
+{"task": "task_0003", "cmd": "node scripts/build-perf/content-lint.mjs dist && bash -n infra/deploy/build.sh && test -x scripts/build-perf/prod-smoke.sh", "exit": 0, "duration_s": 0.058, "stdout_tail_sha256": "209fba8e31f47e3c0984b06e53b6dec06a74dcc59311dae22cca8323af4ad09f", "tree_fp": "5e3805453ecab02ecf7d7db336ac16e05fa30d2b497ba655209e410c8c527dfd", "at": "2026-11-01T01:42:16+00:00"}
+{"task": "task_0004", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -q 'data-cmd=\"reader\"' src/components/CommandPalette.astro && grep -q \"html.reader\" src/styles/global.css", "exit": 0, "duration_s": 14.429, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "5e3805453ecab02ecf7d7db336ac16e05fa30d2b497ba655209e410c8c527dfd", "at": "2026-11-01T01:42:31+00:00"}
+{"task": "task_0005", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rqE \"code-win|codebar|窗条\" src/pages/archives/", "exit": 0, "duration_s": 14.396, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "5e3805453ecab02ecf7d7db336ac16e05fa30d2b497ba655209e410c8c527dfd", "at": "2026-11-01T01:42:45+00:00"}
+{"task": "task_0006", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rq \"paper\" src/components/", "exit": 0, "duration_s": 14.486, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "5e3805453ecab02ecf7d7db336ac16e05fa30d2b497ba655209e410c8c527dfd", "at": "2026-11-01T01:42:59+00:00"}
+{"task": "task_0007", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -q \"flow-h2-pre\" src/styles/tokens.css && grep -q \"focus-visible\" src/styles/global.css", "exit": 0, "duration_s": 14.479, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "5e3805453ecab02ecf7d7db336ac16e05fa30d2b497ba655209e410c8c527dfd", "at": "2026-11-01T01:43:14+00:00"}
+{"task": "task_0008", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rq \"tagline\" src/pages/index.astro src/components/ && grep -q \"radius-img\" src/styles/tokens.css", "exit": 0, "duration_s": 14.333, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "5e3805453ecab02ecf7d7db336ac16e05fa30d2b497ba655209e410c8c527dfd", "at": "2026-11-01T01:43:28+00:00"}
+{"task": "task_0001", "cmd": "test -f public/robots.txt && grep -q \"Sitemap: https://wait4x.online/sitemap-index.xml\" public/robots.txt && grep -q \"Disallow: /admin\" public/robots.txt && grep -q \"SEO 解封操作单\" docs/上线检查单.md", "exit": 0, "duration_s": 0.005, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "a0b992acff0e1c843f7cb94470f4c1304b5e8747a0fa18dea2a93e69200f3de7", "at": "2026-11-01T01:49:52+00:00"}
+{"task": "task_0002", "cmd": "! grep -r \"/en/en/\" dist/ && grep -q 'rel=\"canonical\"' dist/en/archives/mian-sha/index.html && E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\"", "exit": 0, "duration_s": 14.485, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "a0b992acff0e1c843f7cb94470f4c1304b5e8747a0fa18dea2a93e69200f3de7", "at": "2026-11-01T01:50:06+00:00"}
+{"task": "task_0003", "cmd": "node scripts/build-perf/content-lint.mjs dist && bash -n infra/deploy/build.sh && test -x scripts/build-perf/prod-smoke.sh", "exit": 0, "duration_s": 0.062, "stdout_tail_sha256": "209fba8e31f47e3c0984b06e53b6dec06a74dcc59311dae22cca8323af4ad09f", "tree_fp": "a0b992acff0e1c843f7cb94470f4c1304b5e8747a0fa18dea2a93e69200f3de7", "at": "2026-11-01T01:50:06+00:00"}
+{"task": "task_0004", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -q 'data-cmd=\"reader\"' src/components/CommandPalette.astro && grep -q \"html.reader\" src/styles/global.css", "exit": 0, "duration_s": 14.474, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "a0b992acff0e1c843f7cb94470f4c1304b5e8747a0fa18dea2a93e69200f3de7", "at": "2026-11-01T01:50:21+00:00"}
+{"task": "task_0005", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rqE \"code-win|codebar|窗条\" src/pages/archives/", "exit": 0, "duration_s": 14.495, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "a0b992acff0e1c843f7cb94470f4c1304b5e8747a0fa18dea2a93e69200f3de7", "at": "2026-11-01T01:50:35+00:00"}
+{"task": "task_0006", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rq \"paper\" src/components/", "exit": 0, "duration_s": 14.482, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "a0b992acff0e1c843f7cb94470f4c1304b5e8747a0fa18dea2a93e69200f3de7", "at": "2026-11-01T01:50:50+00:00"}
+{"task": "task_0007", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -q \"flow-h2-pre\" src/styles/tokens.css && grep -q \"focus-visible\" src/styles/global.css", "exit": 0, "duration_s": 14.59, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "a0b992acff0e1c843f7cb94470f4c1304b5e8747a0fa18dea2a93e69200f3de7", "at": "2026-11-01T01:51:04+00:00"}
+{"task": "task_0008", "cmd": "E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q \"34/34 PASS\" && grep -rq \"tagline\" src/pages/index.astro src/components/ && grep -q \"radius-img\" src/styles/tokens.css", "exit": 0, "duration_s": 14.452, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "a0b992acff0e1c843f7cb94470f4c1304b5e8747a0fa18dea2a93e69200f3de7", "at": "2026-11-01T01:51:19+00:00"}
@@ -0,0 +1,87 @@
+# Phase 5f：SEO 解封与功能优化批 + 美化首批 - 项目范围
+
+<!-- spec-format: 2 -->
+
+## 1. 问题定义
+- **项目目标**：①解除生产全站 noindex 封印并补齐 SEO 基建（事故级：上线至今搜索引擎不可见）②修双语暗伤（localePath 双 en/canonical/尾斜杠）③构建期内容 lint+生产冒烟防线 ④reader 纯文本模式 ⑤美化首批 K-Q（流距 token 化/灰阶补档/首屏 tagline/图库质感/微交互/代码块窗条/书评纸面板，全部经视觉模型裁定定案）
+- **目标用户**：站长（写作/发布/被搜索到）与读者（阅读质感/双语导航正确性）
+- **核心价值**：站点从"隐身可用"到"可被发现+有质感"；发布链自带质检
+
+## 2. 假设与待确认
+
+### 2.1 已确认事实
+- noindex 来源=/etc/nginx/snippets/esa-origin-ssl.conf:11（我已 curl+grep 实锤）；robots.txt 生产 404；ESA 头缓存 30 天
+- localePath 在 en→en 场景产出 /en/en/...（404）
+- Artalk 评论数端点已实测（GET /api/v2/comments?site_name=wait4x.online&limit=0 → count）
+- 美化七问已由 glm-5.3-flash:max 逐图裁定（docs/research/08 §6）
+
+### 2.2 关键假设
+- nginx sudo 与 ESA 控制台由用户操作（本包只备好仓库侧与操作单）
+- 视觉裁定为终态依据；实现与裁定冲突时以裁定为准并在完成总结记录
+
+### 2.3 待确认问题
+- [x] 美化两案之争 → 视觉模型裁定完成（08 文档 §6），无悬案
+- [x] 本批范围 → 用户 2026-10-26 全批（A/B/C/E+K-Q；R 热力图暗色与 S 并入 N 后的下一批）
+
+### 2.4 可选解释与取舍
+- 纸面板=全边框圆角卡（裁定）优于通栏 hairline——保留标题区外置结构
+- 代码块窗条仅 ≥4 行块；三点换灰阶（红线优先于 macOS 梗）
+- 图库亮色直贴/暗色 4% 衬底（双模式分判）
+
+### 2.5 已证伪路径
+- 首屏 banner 化/大字标语（视觉裁定否决——克制红线）
+- 热力图亮色换绿（裁定否决——全页最大色块压灰阶骨架）
+- 页面标题 27→22px（裁定否决——层级锚点，要轻减字重不减号）
+
+## 3. 功能范围
+
+### 3.1 核心功能（MVP）
+- [x] T1 SEO 仓库侧三件：robots.txt 新建 + /admin 局部 noindex 预案 + 用户操作单（nginx/ESA）
+- [x] T2 localePath 双 en 修复 + 自指 canonical + 尾斜杠归一
+- [x] T3 构建期内容 lint（断链/图片/frontmatter/双语配对）+ 生产冒烟脚本 + build.sh 守卫挂载
+- [x] T4 reader 纯文本模式（html.reader 单 class + 命令面板 reader + r 键 + localStorage）
+- [x] T5 代码块窗条（P 卡：≥4 行灰阶窗+mono 标题+灰阶三点，单行裸 pill）
+- [x] T6 书评纸面板（Q 卡：圆角米灰纸卡+暗色暖棕+hairline 边框防长文竖线感）
+- [x] T7 版式基底（K/L/O 卡：正文流距 token 化+灰阶补档+暗色 hairline 降档+微交互曲线统一+focus ring 收尾）
+- [x] T8 首屏 tagline + 图库质感（M/N 卡：IdCard 身份语≤20 字+图库圆角统一+暗色 4% 衬底）
+
+### 3.2 扩展功能
+- 无（R 热力图暗色补救列下一批）
+
+### 3.3 不在范围内
+- nginx/ESA 实际操作（用户侧）；draft 路由 D、评论数 F、EXIF 卡 G、title H（本月批后续包）
+
+## 4. 最小实现路径
+- 最简单可行方案：token 值级 CSS 改动为主 + locale.ts 单函数修 + 两个构建脚本；无新依赖
+- 暂不引入：blur-up 占位（需管线）、独立设置面板
+- 不做的抽象：主题引擎化/样式体系重构（tokens 增量演化）
+
+## 5. 技术决策
+- 技术栈：既有 Astro+tokens 体系；lint 用 node 脚本（复用 build-perf 目录与守卫模式）
+- 证据协议：evidence: runs
+- 本轮允许改动：src/lib/locale.ts、src/layouts/BaseLayout.astro、src/styles/{tokens,global}.css、src/components/{CommandPalette,IdCard*}.astro、src/components/geek/Keyboard.astro、GalleryPage.astro、prose 相关组件、public/robots.txt、scripts/build-perf/、infra/deploy/build.sh、tests/e2e.mjs
+- 本轮不应触碰：nginx/ESA（用户）、Header/Footer 结构、sw.js（无涉）、热力图组件
+- Git integration branch：`spec/2026-10-26_blog-5f`
+
+### 5.1 验证策略
+- 范围级别：package
+- 变更对象：SEO 基建文件、locale 工具、构建链 lint 挂载、reader/美化涉及的样式与组件
+- 快速检查：`pnpm astro build`
+- 集成检查：`node tests/e2e.mjs`（33 项）+ 本包新增断言（canonical/localePath/reader/窗条/纸面板 computed-style）
+- 全项目检查：生产 Lighthouse SEO≥95 复测（依赖用户 nginx/ESA 操作单完成）+ 移动溢出密集扫描；仅在 nginx/ESA 面、构建链或 Header 布局再变更时升级范围
+- 升级触发：T7 灰阶补档若波及 Header/导航布局，或用户操作单完成后生产复测不达标，升级为全站密集扫描与 LH 多轮中位并记录理由
+
+## 6. 成功标准与验证方式
+- [x] dist 每页含自指 canonical 且 en 页无 /en/en/ -> verify: task_0002
+- [x] robots.txt 产物存在且含 Sitemap 行 -> verify: task_0001
+- [x] 人为断链能让 build 输出 FAIL 清单（warn 一周策略首版即 fail 可议） -> verify: task_0003
+- [x] reader 触发后 .bg-glow 隐藏/ICP 可见/刷新保持 -> verify: task_0004
+- [x] 多行代码块有窗条与灰阶三点、单行无 -> verify: task_0005
+- [x] 书评正文为圆角纸卡（computed border-radius+背景） -> verify: task_0006
+- [x] 流距 token 生效（h2 前后距为变量值）+focus ring 统一 -> verify: task_0007
+- [x] 首屏 tagline 渲染≤20 字+图库圆角统一 -> verify: task_0008
+
+## 7. 风险与约束
+- 灰阶红线：所有美化以 08 §6 裁定为终态依据
+- build.sh 引用新脚本守卫先行（车道纪律）；lint 首版 fail 可降 warn 一周（发布链安全优先）
+- 多车道并行：T2/T3（op-gitea）、T5/T6（op-artalk）、T1/T4/T7/T8（orchestrator）；共享文件按 boundary 划界，global.css/tokens 仅 orchestrator 动
@@ -0,0 +1,46 @@
+# Phase 5f：SEO 解封与功能优化批 + 美化首批 - 任务拆解
+
+## 使用规则
+- boundary/verify 齐备；verify 只读断言；车道工作树开发禁 git，收编由 orchestrator 统一提交
+
+## 阶段一：实现
+
+- [x] T1 SEO 仓库侧三件（robots.txt + admin noindex 预案 + 用户操作单）
+  - claim: orchestrator
+  - boundary: 新建 public/robots.txt（Allow 全站；Disallow /admin/ /draft/；Sitemap 行）；docs/上线检查单.md 追加「SEO 解封操作单」节（nginx snippet 行号/内部 vhost 补回清单/ESA purge+TTL+绕缓存三动作）；nginx/ESA 实操归用户
+  - verify: `test -f public/robots.txt && grep -q "Sitemap: https://wait4x.online/sitemap-index.xml" public/robots.txt && grep -q "Disallow: /admin" public/robots.txt && grep -q "SEO 解封操作单" docs/上线检查单.md`
+
+- [x] T2 localePath 双 en 修复 + 自指 canonical + 尾斜杠归一
+  - claim: op-gitea（mesh 车道）
+  - boundary: src/lib/locale.ts（先归一 zh 再拼前缀）；BaseLayout.astro 加自指 canonical（Astro.site+withSlash）；Header.astro nav-lang href 尾斜杠补齐；E2E 可加断言
+  - verify: `! grep -r "/en/en/" dist/ && grep -q 'rel="canonical"' dist/en/archives/mian-sha/index.html && E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q "34/34 PASS"`
+
+- [x] T3 构建期内容 lint + 生产冒烟 + build.sh 守卫挂载
+  - claim: op-gitea（mesh 车道）
+  - boundary: 新建 scripts/build-perf/content-lint.mjs（dist 断链：站内 a[href] 逐一对产物；图片存在性；zh/en 配对警告）+ scripts/build-perf/prod-smoke.sh（curl robots/sitemap/首页头三断言）；build.sh 守卫行（存在性守卫铁律）；首版 fail 但提供 SKIP 环境变量逃生门
+  - verify: `node scripts/build-perf/content-lint.mjs dist && bash -n infra/deploy/build.sh && test -x scripts/build-perf/prod-smoke.sh`
+
+- [x] T4 reader 纯文本模式（html.reader + 命令面板 + r 键 + 持久化）
+  - claim: orchestrator
+  - boundary: global.css 尾部集中 html.reader 段（按 08 文档 §4.4 清单：隐 bg-glow/进度条/收 Header 尾部钮/Footer 收单行 ICP 必留；正文字号微升行宽收窄）；CommandPalette data-cmd="reader" + ui.ts cmd_reader 双语键；Keyboard r 单键；localStorage 持久化；reduced-motion/无 JS 天然兼容（纯 class）
+  - verify: `E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q "34/34 PASS" && grep -q 'data-cmd="reader"' src/components/CommandPalette.astro && grep -q "html.reader" src/styles/global.css`
+
+- [x] T5 代码块窗条（P 卡：≥4 行灰阶窗+mono 标题+灰阶三点）
+  - claim: op-artalk（mesh 车道）
+  - boundary: 技术轨代码块渲染层（自查源码定落点：prose-tech 容器/全局 pre 样式）；≥4 行块加窗条（灰阶三点非红黄绿+mono 语言/文件标签），单行块裸 pill；亮暗双态；scoped 样式优先不动 global.css（与 T7 划界）
+  - verify: `E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q "34/34 PASS" && grep -rqE "code-win|codebar|窗条" src/pages/archives/`
+
+- [x] T6 书评纸面板（Q 卡：圆角米灰纸卡+暗色暖棕+hairline 边框）
+  - claim: op-artalk（mesh 车道）
+  - boundary: 书评正文容器（prose-reading 所在组件 scoped 样式）：圆角纸卡+米灰 #f4f4f2 系亮/暖棕暗态；边框 hairline 级防长文竖线感（08 裁定 §6-2）；标题区外置结构不动；--paper 变量需求提给 orchestrator 入 tokens（T7 协同），不直接改 tokens.css
+  - verify: `E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q "34/34 PASS" && grep -rq "paper" src/components/`
+
+- [x] T7 版式基底（K/L/O 卡：流距 token+灰阶补档+暗色 hairline 降档+微交互曲线+focus ring）
+  - claim: orchestrator（tokens/global 专属车道）
+  - boundary: tokens.css（--flow-* 流距五变量+灰阶补档评估+--paper 纸色变量）；global.css（h2/h3/p+p 改用流距变量、暗色 hairline 降一档、过渡曲线统一 token :where 一段、focus-visible ring 统一）；标题字重 700→600（裁定 #6）；行距 +2~4px（裁定 #7）；移动端密集扫描复测（涉布局面）
+  - verify: `E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q "34/34 PASS" && grep -q "flow-h2-pre" src/styles/tokens.css && grep -q "focus-visible" src/styles/global.css`
+
+- [x] T8 首屏 tagline + 图库质感（M/N 卡：身份语+圆角统一+暗色衬底）
+  - claim: orchestrator
+  - boundary: 首页身份区（IdCard 或等位组件）加 tagline ≤20 字（措辞备两案入完成总结供用户选，默认「写作者 · 读者 · 快门按压者」）；GalleryPage 圆角统一 --radius-img 暗色 4% 衬底（裁定 §6-4 双模式分判；衬底圆角≤照片圆角防框中框）；亮色直贴不动
+  - verify: `E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs 2>&1 | grep -q "34/34 PASS" && grep -rq "tagline" src/pages/index.astro src/components/ && grep -q "radius-img" src/styles/tokens.css`
@@ -3,6 +3,9 @@ import { defineConfig } from 'astro/config';
 import pagefind from 'astro-pagefind';
 import sitemap from '@astrojs/sitemap';
 import { execSync } from 'node:child_process';
+import rehypeLinkCards, { linkCardsReport } from './src/lib/rehype-link-cards';
+import rehypeClassWhitelist from './src/lib/rehype-class-whitelist';
+import rehypeRaw from 'rehype-raw';

 // 构建透明（T7）：commit/时间经 vite.define 注入，页脚与 /about 引用。
 // 四重回退：CI 环境变量优先（GITEA_ACTIONS/GITHUB_SHA）→ 本地 git → dev 占位。
@@ -17,7 +20,13 @@ const date =

 export default defineConfig({
  site: 'https://wait4x.online',
-  integrations: [pagefind(), sitemap()],
+  integrations: [pagefind(), sitemap(), linkCardsReport()],
+  markdown: {
+    // 独立成段的裸链接 → OG 预览卡（构建期抓取，失败回落普通链接；见 src/lib/rehype-link-cards.ts）
+    // 顺序：rehypeRaw 先把 markdown 里的 raw HTML 解析成 hast element（否则白名单看不到 span），
+    // 再白名单净化（剥 style/on*/非白名单类），最后链接卡片（节点由插件自建，不经净化）
+    rehypePlugins: [rehypeRaw, rehypeClassWhitelist, rehypeLinkCards],
+  },
  i18n: {
    defaultLocale: 'zh',
    locales: ['zh', 'en'],
@@ -0,0 +1,66 @@
+<div align="center">
+<img src="https://readme-typing-svg.demolab.com?font=Fira+Code&weight=600&size=26&duration=3000&pause=1000&color=00D9FF&center=true&vCenter=true&random=false&width=620&lines=Hi+there+%F0%9F%91%8B+I'm+wait4x;Open+Source+Enthusiast+%E2%9D%A4%EF%B8%8F;Meteorology+%E2%9B%85" alt="Typing SVG" />
+<br>
+<a href="https://github.com/wait4xx?tab=followers"><img src="https://img.shields.io/github/followers/wait4xx?label=Followers&style=for-the-badge&color=00D9FF&labelColor=0D1117" /></a>
+<a href="https://github.com/wait4xx?tab=stars"><img src="https://img.shields.io/github/stars/wait4xx?label=Stars&style=for-the-badge&color=00D9FF&labelColor=0D1117" /></a>
+<a href="https://github.com/wait4xx"><img src="https://img.shields.io/badge/Open%20Source-%E2%9D%A4%EF%B8%8F-00D9FF?style=for-the-badge&labelColor=0D1117" /></a>
+</div>
+
+---
+
+### 👋 About Me
+
+- ⛅ An aspiring forecaster rooted in **meteorology**.
+- 💻 Passionate about **computer science** and coding.
+- 🌐 My web: **[wait4x.online](https://wait4x.online/)**
+- ⚡ *"Embrace open source, love open source."*
+
+---
+
+### 📊 GitHub Stats
+
+<div align="center">
+  <img height="170" src="https://github-readme-stats.vercel.app/api?username=wait4xx&show_icons=true&hide_border=true&bg_color=0D1117&title_color=00D9FF&icon_color=00D9FF&text_color=C9D1D9&include_all_commits=true&count_private=true&line_height=28" alt="stats" />
+  <img height="170" src="https://github-readme-stats.vercel.app/api/top-langs/?username=wait4xx&layout=compact&hide_border=true&bg_color=0D1117&title_color=00D9FF&text_color=C9D1D9&langs_count=8" alt="top-langs" />
+</div>
+
+<br>
+
+<div align="center">
+  <img src="https://streak-stats.demolab.com?user=wait4xx&hide_border=true&background=0D1117&ring=00D9FF&fire=00D9FF&currStreakLabel=00D9FF&sideLabels=C9D1D9&dates=C9D1D9&currStreakNum=C9D1D9" alt="streak" />
+</div>
+
+---
+
+### 📈 Activity Graph
+
+<div align="center">
+  <img src="https://github-readme-activity-graph.vercel.app/graph?username=wait4xx&bg_color=0D1117&color=C9D1D9&line=00D9FF&point=00D9FF&area=true&area_color=00D9FF&hide_border=true" alt="activity-graph" />
+</div>
+
+---
+
+### 🐍 Contribution Snake
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/wait4xx/wait4xx/output/github-contribution-grid-snake.svg" alt="snake" />
+</div>
+
+> *This snake is auto-fed every day by a GitHub Action in this repo 🍎*
+
+---
+
+### 📫 Find Me
+
+<div align="center">
+<a href="https://github.com/wait4xx"><img src="https://img.shields.io/badge/GitHub-181717?style=for-the-badge&logo=github&logoColor=white" /></a>
+<a href="mailto:X@alumni.nudt.edu.cn"><img src="https://img.shields.io/badge/Email-D14836?style=for-the-badge&logo=gmail&logoColor=white" /></a>
+</div>
+
+---
+
+<div align="center">
+  <img src="https://komarev.com/ghpvc/?username=wait4xx&color=00D9FF&style=flat-square&label=%F0%9F%91%80+Visitors" />
+  <br><br>
+  <img src="https://readme-typing-svg.demolab.com?font=Fira+Code&size=14&duration=2000&pause=500&color=8B949E&center=true&vCenter=true&random=false&width=300&lines=Thanks+for+visiting!;See+you+in+the+commits+%F0%9F%8C%BF" alt="footer" />
+</div>
@@ -0,0 +1,31 @@
+{
+  "_readme": "链接卡片抓取缓存（构建确定性需求，入仓）。键=URL，值={title,desc,image,favicon,ts}；ts 超 30 天刷新。手工改动安全：删条目即下次构建重抓。",
+  "https://www.cnblogs.com/Lenbrother/p/18673403": {
+    "title": "Debian 安装 Docker - 神奇小宝 - 博客园",
+    "desc": "卸载已有 Docker 如果你之前安装过 Docker Engine 之前，你需要卸载旧版本，避免冲突： for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do sudo apt-get rem",
+    "image": "https://assets.cnblogs.com/images/wechat-share.jpg",
+    "favicon": "https://assets.cnblogs.com/favicon_v3_3.ico",
+    "ts": 1793593758751
+  },
+  "https://wait4x.online/": {
+    "title": "wait4x",
+    "desc": "wait4x 的博客：阅读 · 技术 · 摄影",
+    "image": "",
+    "favicon": "https://wait4x.online/favicon.svg",
+    "ts": 1793593759184
+  },
+  "https://blog.csdn.net/qq_40605167/article/details/122888580": {
+    "title": "Docker版 E5续订的E5调用API续订服务：Microsoft 365 E5 Renew X_e5 docker",
+    "desc": "文章浏览阅读2.7w次，点赞10次，收藏43次。本文介绍了如何使用Docker轻松部署Microsoft365E5续订服务，包括提供小巧的镜像、一键部署命令及邮箱通知功能。用户需要具备Docker基础，并按照步骤修改邮箱和密码等参数。此外，还提供了不同CPU架构的支持。注意，已有部分账号出现被关停的情况。文章附带了Docker环境搭建教程和相关资源链接。",
+    "image": "https://i-blog.csdnimg.cn/blog_migrate/cover/dc9f6540d4d4330e797f1ebd0261f736.png",
+    "favicon": "https://g.csdnimg.cn/static/logo/favicon32.ico",
+    "ts": 1793593759739
+  },
+  "https://astro.build/": {
+    "title": "Astro",
+    "desc": "Astro builds fast content sites, powerful web applications, dynamic server APIs, and everything in-between.",
+    "image": "https://astro.build/og/astro.jpg",
+    "favicon": "https://astro.build/favicon.svg",
+    "ts": 1793593759816
+  }
+}
@@ -1,5 +0,0 @@
---
-pubDate: 2026-04-29
-tags: []
-text: "@wait4x"
---
@@ -1,5 +0,0 @@
---
-pubDate: 2026-04-29
-tags: []
-text: "@wait4x"
---
@@ -1,6 +1,7 @@
 {
-  "title": "防波堤暮色",
-  "image": "./1766156983093.jpg",
-  "group": "landscape",
-  "alt": "暮色海岸与远处防波堤（T3 冒烟补写）。"
+ "title": "防波堤暮色",
+ "image": "./1766156983093.jpg",
+ "group": "landscape",
+ "alt": "暮色海岸与远处防波堤（T3 冒烟补写）。",
+ "caption": "落日把海与城一齐烫成金箔，海鸟的剪影恰好掠过日轮"
 }
@@ -3,5 +3,6 @@
 "image": "./1766156992123.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "书架暗处，那本宫崎骏分镜集被灯光单独打亮"
+}
@@ -3,5 +3,6 @@
 "image": "./1766156992265.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "一面白墙只问一个问题，笔锋落下处是想活出的人生"
+}
@@ -3,5 +3,6 @@
 "image": "./1766156992559.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "黑暗中独一句发光的话，像有人在夜里旋起一阵热风"
+}
@@ -3,5 +3,6 @@
 "image": "./1766156992840.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "一抹红墙，几笔白线，龙猫的轮廓就是吉卜力的门牌"
+}
@@ -3,5 +3,6 @@
 "image": "./1766156997939.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "夜游船驮着绿光驶过，东方明珠在它身后蓝得像天外来物"
+}
@@ -3,5 +3,6 @@
 "image": "./1766156998072.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "对岸灯火压得很低，渡轮拖着一线亮色划开墨色的江面"
+}
@@ -3,5 +3,6 @@
 "image": "./1766156998205.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "海关大楼的钟面亮成金色，人群在灯下攒动成剪影"
+}
@@ -3,5 +3,6 @@
 "image": "./1766156998344.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "旗在风里翻卷，塔身亮得像一支随时点火的火箭"
+}
@@ -3,5 +3,6 @@
 "image": "./1766156998590.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "大楼只占一个角落，剩下的天空都交给云慢慢写"
+}
@@ -3,5 +3,6 @@
 "image": "./1766157003595.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "草坡绿得发暗，牦牛散落其间，低头啃食高原的安静"
+}
@@ -3,5 +3,6 @@
 "image": "./1766157003732.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "灰白天色下，雪与黑岩互相渗透，山脊线细得像一笔勾勒"
+}
@@ -3,5 +3,6 @@
 "image": "./1766157003865.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "雾把山谷对折，只留下碎石和雪在白茫茫里彼此确认"
+}
@@ -3,5 +3,6 @@
 "image": "./1766157003992.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "一队人影在乱石坡上缓缓上移，雪山在他们头顶沉默俯视"
+}
@@ -3,5 +3,6 @@
 "image": "./1766157004116.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "雪原中央蹲着两团颜色，出发前把装备一件件理顺"
+}
@@ -3,5 +3,6 @@
 "image": "./1766157012003.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "太阳缩成一粒橘色的句点，悬在灰橙色的茫茫天幕上"
+}
@@ -3,5 +3,6 @@
 "image": "./mmexport1771816358254.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "成群海鸥同时起飞，蓝海与红屋顶都被翅膀搅动"
+}
@@ -3,5 +3,6 @@
 "image": "./mmexport1771816377628.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "垂钓的人立在礁石上，几根鱼竿替他守着整片海"
+}
@@ -3,5 +3,6 @@
 "image": "./mmexport1771816382115.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "长堤探进海里，堤上的人站成一小排，各自望着各自的远方"
+}
@@ -3,5 +3,6 @@
 "image": "./mmexport1776564084994.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "海鸥飞过之处，玻璃高塔与红瓦老城在同一帧里相遇"
+}
@@ -3,5 +3,6 @@
 "image": "./mmexport1776564092433.jpg",
 "group": "landscape",
 "alt": "",
- "exif": {}
-}
+ "exif": {},
+ "caption": "画面只留一圈亮处：老楼、松树、栏杆边与海鸥相伴的人群"
+}
@@ -0,0 +1,55 @@
+---
+title: "Agensh: Scaling Organizational Intelligence to 1,024 Agents"
+pubDate: 2026-11-01
+category: tech
+tags: [Paper Notes, AI Collaboration]
+locked: true
+---
+
+Multi-agent systems compress the latency of complex tasks through concurrency, but mainstream frameworks share one ceiling: the central orchestrator. Task allocation, progress aggregation, and result adjudication all squeeze through a single context — the bigger the scale, the sooner the orchestrator dies. In October 2026, Microsoft Research open-sourced [Agensh](https://github.com/microsoft/Agensh) — a self-organized multi-agent harness **with no central orchestrator**, and the paper [*Scaling Organizational Intelligence to 1,024 Agents*](https://arxiv.org/abs/2609.26781) pushed it to a thousand and twenty-four agents.
+
+Its answer is disarmingly simple: instead of building a smarter scheduling brain, hand the agents the coordination infrastructure of a human organization, as is.
+
+> 📄 **[Read the full paper PDF online →](/en/papers/agensh/)**　·　arXiv 2609.26781　·　Microsoft Research
+
+## 1. Three pillars: an organization's coordination infrastructure
+
+![From central orchestration to self-organization](../posts/assets/agensh/pillars.svg)
+
+Agensh provides exactly three pieces of infrastructure; everything else self-organizes:
+
+- **Shared workspace**: a git platform carries the organization's in-progress and integrated work — branches, PRs, and merge conflicts, twenty years of human machinery reused as-is;
+- **Message interface**: a team channel plus direct messages with priority delivery — organization-wide broadcasts and urgent collision resolution each take their own lane;
+- **Shared context**: a typed-entry board holding the organization's findings and work intentions.
+
+The open-source reference implementation runs Gitea for the workspace and Mattermost for channel and DMs — a fully self-hosted "office" with no proprietary services. No orchestrator assigns tasks: workers find work themselves in the workspace and the context board, claim it, verify it, and merge it. The natural bottleneck of scaling — that ever-busier hub — simply does not exist.
+
+## 2. The cooperation loop: every worker runs their own lap
+
+![The multi-agent cooperation loop](../posts/assets/agensh/loop.svg)
+
+Every worker concurrently and asynchronously runs the same loop: **gather context → claim a sub-task → take action → verify → merge progress**. Gathering context means reading the shared workspace and the board's accumulated knowledge; claiming is a CLAIM declaration, with collisions resolved over direct messages; verification is running the tests yourself — evidence talks; merging goes through PRs.
+
+The most interesting design is the **economy** of the shared context: entries are deliberately tiny (about 100 characters, 300 for PATCH_SUMMARY), with the long version in a `detail` field fetched on demand; `board_read` serves only the latest 2,000 entries, and anything older is reachable only through boolean search (`,` = OR, `&` = AND) — recent memory stays small, the long tail is searched. The paper calls **FAIL the highest-value entry**: one documented falsified path stops the whole team from re-burning budget on the same dead end. New entries are pushed to peers as higher-priority updates at their next tool-call boundary.
+
+This shared context is not Agensh's invention — §2.3 of the paper states plainly that "the shared context follows the core idea of DeLM". [DeLM](https://github.com/yuzhenmao/DeLM) ([arXiv:2606.10662](https://arxiv.org/abs/2606.10662)) ran decentralized multi-agent coordination through a shared context and task queue: its board is an append-only event log (items, claims, completions, FACT/FAIL notes, status) with bodies stored in a separate database beside the log, hard limits (≤40 files, ≤400 KB total), and a blocking `read --wait` that wakes when a peer posts. On a 10-task Terminal-Bench 4.0 subset, two agents coordinating through the shared context averaged +12.5 percentage points accuracy and a 1.78× speedup. Agensh scaled that thread to a thousand agents.
+
+## 3. The numbers: does scaling actually help?
+
+![Scaling gains](../posts/assets/agensh/scale.svg)
+
+Two datasets answer "do more agents actually move the needle": on the five hardest ProgramBench tasks, 1 → 128 agents raised the pass rate from 19.31% to 28.78% (~49% relative); on building pandoc from scratch (6-hour budget, no Internet), 1 → 1,024 agents raised it from 33.89% to 55.06%. For problems where raw compute has hit diminishing returns, **the marginal return of organization is still there**.
+
+Engineering readiness arrived too: v1.0 shipped on 2026-10-23, and v1.0.1 six days later supports Copilot, Codex, Claude Code, and Pi as the underlying single-agent harness — use whatever mainline model you like underneath. The open-source release is a single-node harness, and the v1.0 package ships with a reproduction guide, the paper, and a demo — from paper to runnable repository with no "coming soon" in between.
+
+## 4. From paper to desktop: the story of one issue
+
+For us this paper was never just on paper. After digesting it, on 2026-10-23 I filed [issue #13](https://github.com/cgarrot/pi-mesh/issues/13) on the pi-mesh repository: pi-mesh already had the message interface (`mesh_send`, rooms, priorities) and the shared workspace (git + `mesh_reserve`), but lacked the third pillar, shared context — proposing `board_write / board_read / board_grep` in exactly the Agensh/DeLM shape.
+
+The maintainer cgarrot's reply is the most instructive part of the story: the direction was right, but **the hash-only ledger makes pi-mesh structurally incapable of being that board** — embedding persistence in the broker would turn a router into a database. The right shape was a separate package: join the room as a normal peer, own your storage, and let the mesh keep routing. Thus [pi-board](https://github.com/wait4xx/pi-board): v0.1 landed within a day — 55 tests, zero failures, a nine-step smoke run on a real broker — and when the issue finally closed, the official pointer landed on it. The memory layer of the [four-piece toolkit](/en/archives/pi-mesh-stack/) introduced in the previous post grew straight out of this paper.
+
+## 5. Closing
+
+Agensh's insight is not the number "1024" but its decomposition of organizational intelligence: workspace, messages, shared context — three pillars holding up self-organization, none of which needs a smarter brain. The decomposition holds at thousand-agent scale, holds for a local four-piece toolkit, and holds for a one-person shop with a few agent terminals. Scale changes; the pillars stay.
+
+Related reading: [Spec Harness in Depth](/en/archives/spec-harness/) · [The pi-mesh Tool Family](/en/archives/pi-mesh-stack/)
@@ -0,0 +1,63 @@
+---
+title: "The pi-mesh Tool Family: A Four-Piece Toolkit for Local Multi-Agent Coordination"
+pubDate: 2026-11-01
+category: tech
+tags: [Engineering, AI Collaboration]
+locked: true
+---
+
+[pi](https://github.com/earendil-works/pi) is the coding-agent harness we use daily. With a single terminal it is a quiet assistant; with three or four terminals open at once, each running an agent over the same repository, questions pile up: who is online? Who is editing which file? Was that message actually seen? Who has the right to stop the build running at midnight?
+
+A family of small tools grew around [pi-mesh](https://github.com/cgarrot/pi-mesh) to turn that coordination layer into infrastructure. Each owns one concern, and they interlock:
+
+![The pi-mesh tool family](../posts/assets/pi-mesh-stack/stack.svg)
+
+## 1. pi-mesh: the communication backbone
+
+pi-mesh is a local bus: a broker detached from any session (NDJSON frames over a unix socket), each pi terminal a peer with an alias, organized into rooms. Messages arrive in under 50 ms; zero runtime dependencies, Node ≥ 20.
+
+Its most admirable trait is the **honest status model**: `delivered` (written to the recipient's socket) ≠ `read` (injected into the recipient's session) ≠ `answered` (an explicit reply came back) — three states never conflated, none of them meaning "done". The companion **durable ledger is hash-only**: message bodies are never persisted; after a restart you can audit who sent what to whom and when, but never read the content. This self-restraint later became the family's design axiom: **the mesh stays a router, never a database.**
+
+Three coordination needs live in the backbone:
+
+- **`mesh_reserve` path reservations**: reserve before editing; other peers' `edit`/`write` tools get blocked on those paths — concurrent editing is prevented by mechanism, not by shouting.
+- **`mesh_claim` task leases**: a single-writer lock with an `epoch:fence` (a broker restart invalidates old fences); commits carry `Mesh-Lease: task#leaseId#epoch:fence`, and the bundled commit-msg hook rejects stale-fence commits outright.
+- **Capability routing `cap:`**: `mesh_send({ "to": "cap:deploy", ... })` routes the task to any idle peer advertising that capability instead of waiting for a busy teammate. Three message priorities: normal queues, urgent interrupts, force aborts the recipient's current turn and delivers once it settles (force is a control class and requires a reason).
+
+Add `mesh_wait_all` for group verdicts (one call returns who answered and who is missing), `mesh_status` for peer activity (● working / ○ idle / ✕ stuck), and a `pimesh` CLI for session-less access (`pimesh attach` can adopt a dead session's identity). Multi-machine deployment is supported: one machine runs the broker, the rest connect as clients.
+
+The honesty reaches down to exit codes: in the CLI, 3 means `expired` — a late reply is still delivered, you just stopped waiting; 5 means a stale lease, and the `commit-msg` hook rejects the commit on that basis. Even the host-specific edge of ESC purging the message queue is covered: a batch injected just as a turn aborts is re-delivered through an abort-safe channel once the turn settles (bounded retries), with a re-delivery counter visible in status.
+
+## 2. pi-board: the shared context board
+
+Messages are ephemeral; the ledger is hash-only. Where does "what we learned" live? [pi-board](https://github.com/wait4xx/pi-board) fills that layer. Five typed entries:
+
+- **OBSERVED** — something seen, no commitment
+- **FACT** — a verified truth
+- **FAIL** — a falsified path (the highest-value kind: the whole team stops re-burning budget on it)
+- **CLAIM** — an ownership note, paired with a `mesh_claim` lease (the board records; it never enforces)
+- **PATCH_SUMMARY** — what a landed change did
+
+The design is bounded and honest throughout: append-only local storage, refuse-not-evict (over-limit writes are refused, never silently evicted), short entries by default with a `detail` field unfolded only by id, boolean search (`,` = OR, `&` = AND) across the full history while `board_read` serves only the recent window; a search miss returns an honest empty, never a guess. Writes go to the room as ordinary broadcast frames; a new-FAIL digest line rides every turn boundary; the room's member / observer roles follow mesh semantics, so a read-only peer is never re-admitted as a writer after a reconnect. It joins the room as a normal peer — **all storage stays at the board's home; zero persistence in the broker**. A bundled `piboard` CLI does it in five verbs — join (member / observer) / watch / write / read / grep, one verb per action — so even a session-less terminal can join a room read-only and observe. The typology and the "small entries + on-demand detail + recent memory / full-history search" split come straight from the research literature (the lineage story is in [the next post](/en/archives/agensh/)).
+
+## 3. pi-jobd: the background job daemon
+
+`bash` blocks the current turn; `/reload` kills the process. [pi-jobd](https://github.com/cgarrot/pi-jobd) runs long commands in their own process group supervised by a per-user daemon: it returns in ~150 ms, and the job outlives the session. When to use it? Three criteria: the command will run longer than 60–90 seconds; you must keep working while it runs; or it must survive `/reload` and session end — plus "another agent should be able to stop it": `mesh_job_control` lets any authorized peer remotely stop/pause/resume someone else's background job.
+
+The state machine is equally honest: `running / paused / stopped / exited / failed`, plus `lost` — when the daemon restarts and cannot prove pid ownership, it refuses to stop rather than signal an unproven process. One more clever touch: installing the package is not enough — the model must *know when* to use it. Three layers feed the model the decision rule: a prompt snippet, guidelines on all seven tools, and an on-demand skill.
+
+## 4. pi-subagents: worker control
+
+[pi-subagents](https://github.com/nicobailon/pi-subagents) manages in-process child agents: foreground children stream inside the conversation; background children live in a detached runner process you can check later. It works right after install with no slash commands to learn — just say "use reviewer to review this diff". It ships common roles like scout and reviewer, and supports saved workflows and parallel reviews. Its mesh interface is `mesh_run_control`: remotely stop or steer a peer's RPC worker.
+
+## 5. One rehearsal of the four-piece suite
+
+![The collaboration loop](../posts/assets/pi-mesh-stack/loop.svg)
+
+## 6. Five minutes to onboard
+
+One line each: mesh and subagents install as pi packages — `pi install npm:pi-mesh-extension`, `pi install npm:pi-subagents`; pi-board is not on npm yet — clone, `npm ci`, `npm run build` — and it works CLI-only (reading and writing the local board needs no mesh at all); pi-jobd builds from source the same way, with `pijob run / list / log / stop` working out of the box. Open two pi sessions in one directory and you have two peers visible to each other in `mesh_status` — "zero config" is not a slogan here.
+
+Conversation over mesh, memory on the board, long work to jobd, exclusivity by lease — four packages, each doing its job, none overstepping. This blog's redesign was their proving ground: two mesh terminals (op-gitea, op-artalk) ran in parallel with the mainline, nineteen commits in one day; during the publish-chain outage, one lane reserved build.sh for emergency repair while an incoming hotfix edit was correctly blocked by the reservation — collisions are prevented by rule, not by reflex.
+
+Together the four pieces contain no database and no central brain, yet pin down all four questions: who is online, who is doing what, what was learned, and who watches the long jobs. Small tools, hard boundaries, honest states — that philosophy is worth copying more than any individual package.
@@ -0,0 +1,60 @@
+---
+title: "Spec Harness in Depth: Packaging Long-Horizon Development into Verifiable Task Packages"
+pubDate: 2026-11-01
+category: tech
+tags: [Engineering, AI Collaboration]
+locked: true
+---
+
+What AI coding agents lack is not bandwidth for writing code — it is memory. A task that spans several sessions accumulates half-finished plans, already-falsified approaches, and acceptance criteria that get lost in chat history; restart the terminal and the context resets to zero. [Spec Harness](https://github.com/MicTx/spec-harness) targets exactly this: a task-package workflow tool for AI coding agents that persists long-horizon changes as a **recoverable, verifiable Development Record**, governed by scope, evidence, and Git gates. It provides no model and makes no product decisions for you.
+
+Its worldview in one sentence: **when a coding task outlives one conversation, the missing tool is not a smarter model — it is a contract that everyone (including your future self) can read.**
+
+## 1. The core abstraction: the task package
+
+All work lives in a `.spec/specs/YYYY-MM-DD_slug/` directory with two core files: `spec.md` records scope, assumptions, and trade-offs (including a remarkable "falsified paths" section, more on that below), while `tasks.md` holds the task list. After closeout the whole package is archived under `.spec/specs/archive/` — the archive directory is the project's engineering log.
+
+Every task must carry a two-line contract: **boundary** (which files this task may touch) and **verify** (how completion is proven). The verify is a read-only assertion that must exit 0 before the checkbox goes on. A real example from this blog's archived `2026-10-26_blog-5f` package, task T3:
+
+![Task package anatomy](../posts/assets/spec-harness/package-anatomy.svg)
+
+Boundary delimits "what may change"; verify delimits "how completion is proven" — both lines present, or the task stays unchecked. This is not formalism: with multiple agents running in parallel, boundary is the guardrail between lanes (in our practice, global style files are mainline-only; lanes request new variables instead of reaching in). Verify separates "looks done" from "proven done" — a verbal "passed" never counts.
+
+The most interesting section of `spec.md` is **falsified paths**: rejected proposals go into the archive together with the reason for rejection. Our blog-5f package records three — hero banner treatment (rejected by visual adjudication), a green heatmap (broke the grayscale skeleton), and shrinking the title from 27px to 22px (a hierarchy anchor; reduce weight, not size). Whoever wants to try again reads the file first and saves a round of budget.
+
+## 2. The stage pipeline: five core commands and the gates they keep
+
+![Stage pipeline](../posts/assets/spec-harness/pipeline.svg)
+
+Five core commands form one verifiable chain: **goal → scope → tasks → verification → archive → commit → push**. Gates stand between stages: `run` refuses while `spec.md` still has template placeholders; `done` requires every task to have boundary/verify, a fully green acceptance surface, and at least one non-placeholder piece of evidence (script output, test results); `push` merges only `spec/`-prefixed integration branches, never combines file changes with a commit, and forbids `--no-verify`.
+
+A blocked task gets a `!` marker and surfaces to the user — never a silent skip. Actionable issues found during `check` must be written back into the package and fixed in the same round; "to-dos" are not deliverables.
+
+**Interruption recovery is a designed norm** — the most direct answer to "tasks outlive conversations": re-run `/spec:run` at any moment and it resumes from the checked state in `tasks.md`, depending on no chat memory. Going further, `/spec:autoplan` runs interactive planning (clarify the goal, then framework, detail, and review passes; it stops when planning is ready — no auto-start), and `/spec:autorun` executes package by package, capped at 5 auto rounds by default (`--max-rounds` adjustable), resuming from the same step after a pause; the one-shot entry `/spec:goal` runs planning, execution, review, archiving, and the commit in a single pass.
+
+The command surface totals 12 stage commands: the core profile installs the five core commands, and full adds the seven extensions — goal / autoplan / autorun / update / status / doctor / organize — where `doctor` self-checks and repairs the environment and `organize` audits structure. One easily-missed detail: installing only lays down files; it never auto-evaluates every task. If you want it to proactively ask "should this get a package?" before you start, wire the activation hooks once with `install_activation_hooks.py --mode on`. The criterion is delivery shape — an independent acceptance surface, actual implementers, a recoverable in-flight task; small fixes, read-only investigations, and one-off experiments just get done. It guards against "forgot to evaluate", not against deliberate under-reporting — the documentation is refreshingly candid about this.
+
+## 3. Multi-agent orchestration: one orchestrator, bounded helpers
+
+Spec Harness is deliberately conservative about multi-agent work: **the main session is the single orchestrator** — routing, integration, acceptance, and the `done`/`push` gates never leave the mainline. Sidecar work (exploration, building, reviewing — context-independent slices) may be delegated, but only after a machine route decision (`scripts/route_decision.py`) and a written assignment contract: goal, scope, excluded areas, output, and verification method, all five present. An optional `handoff.md` covers cross-session boundaries — a generative snapshot header plus an append-only entry log, with required sections that adapt to solo / multi-person / agent / cluster collaboration modes.
+
+Extension slots plug other team processes in: `team-loop` for team cycles and `workflow-runner` for workflow fan-out, each with its README protocol and tests. The source repo also ships four orchestration agent definitions: orchestrator, planner, reviewer, confirmer.
+
+## 4. Installation: one installer, a dozen-plus hosts
+
+Spec Harness is a Python 3.9+ standard-library implementation (PolyForm Noncommercial license), installed in three steps:
+
+```bash
+git clone https://github.com/MicTx/spec-harness.git /tmp/spec-harness
+cd /tmp/spec-harness
+git checkout v0.22.2
+bash install.sh
+```
+
+The installer supports a dozen-plus hosts: Claude Code, Codex, Gemini CLI, Grok, OpenCode, OpenClaw, Hermes, Pi, ZCode, DeepSeek Harness, Devin, Cursor… auto-detecting installed hosts when unspecified. Install profiles come in core / full: core ships the five core stage commands plus Git hooks; full adds all 12 stage commands and the slots/agents extensions. We use `INSTALL_HOSTS=pi bash install.sh` on Pi — the `/spec` commands work right after installation.
+
+## 5. Running on a real blog
+
+This blog is a user. The archive directory holds a chain of packages — from the bare-clone build rework and mobile layout fixes to the SEO unblocking: blog-5f packed eight tasks on three lanes (two mesh terminals plus the mainline) running in parallel, every task's verify a command-line assertion, page tasks wired to E2E — `E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs`, all 34 passing. Packages relayed one after another; nineteen green commits landed in a single day.
+
+Tools iterate, but the idea does not expire: **write "what to do" as a contract, write "done" as evidence, archive the process as a log.** Whether the collaborators are humans or agents, those three things are the foundation of long-horizon engineering.
@@ -0,0 +1,54 @@
+---
+title: "Agensh：把组织智能扩展到 1,024 个智能体"
+pubDate: 2026-11-01
+category: tech
+tags: [论文笔记, AI 协作]
+---
+
+多智能体系统能靠并发压缩复杂任务的时延，但主流框架有一个共同的天花板：中心编排器。任务分配、进度汇总、结果裁决全部挤过同一个上下文，规模越大，编排器先死。2026 年 10 月，微软研究院开源了 [Agensh](https://github.com/microsoft/Agensh)——一个**没有中心编排器**的自组织多智能体 harness，论文[《Scaling Organizational Intelligence to 1,024 Agents》](https://arxiv.org/abs/2609.26781)把它推到了一千零二十四个 agent 的规模。
+
+它的答案出人意料地朴素：与其造一个更聪明的调度大脑，不如把一个人类组织的协同基建原样搬给 agent 们。
+
+> 📄 **[在线研读全文 PDF →](/papers/agensh/)**　·　arXiv 2609.26781　·　微软研究院
+
+## 一、三支柱：组织的协同基建
+
+![从中心编排到自组织](./assets/agensh/pillars.svg)
+
+Agensh 只给三样基础设施，其余全部自组织：
+
+- **共享工作区**：git 平台承载组织的进行中工作与集成结果，分支、PR、合并冲突这些人类用了二十年的机制原样复用；
+- **消息接口**：团队频道加私信，带优先级送达——组织级广播与紧急碰撞调解各走各的道；
+- **共享上下文**：一块类型化条目板，存组织的发现与工作意图。
+
+开源参考实现用的是 Gitea 承载工作区、Mattermost 承载频道与私信——一套完全开源自接的“办公室”，没有任何私有服务。没有编排器分配任务：worker 自己从工作区和上下文里找活、认领、验证、合并。规模化时天生的瓶颈（那个越来越忙的中枢）根本不存在。
+
+## 二、协作环：每个 worker 各跑一圈
+
+![多智能体协作环](./assets/agensh/loop.svg)
+
+每个 worker 并发、异步地执行同一个协作环：**收集上下文 → 认领子任务 → 执行 → 验证 → 合并进度**。收集上下文时读共享工作区和条目板的存量知识；认领靠 CLAIM 声明，撞车了私聊解决；验证自己跑测试，证据说话；合并走 PR。
+
+最有意思的设计在共享上下文的**经济学**：条目刻意短小（约 100 字符，PATCH_SUMMARY 放宽到 300），长版本放 `detail` 字段按需展开；`board_read` 只服务最近 2000 条，更早的历史只能靠布尔检索（`,` = OR，`&` = AND）翻出来——近期记忆保持小，长尾靠搜索。论文称 **FAIL 是价值最高的条目**：一条被证伪的路径写下来，就能止住全队在同一个死胡同里重复烧预算。新条目会作为较高优先级的更新，在同伴的下一个工具调用边界推送过去。
+
+这套共享上下文不是 Agensh 的发明——论文 §2.3 明说“共享上下文遵循 DeLM 的核心思想”。[DeLM](https://github.com/yuzhenmao/DeLM)（[arXiv:2606.10662](https://arxiv.org/abs/2606.10662)）用共享上下文加任务队列跑去中心化多智能体：它的板是一张 append-only 事件日志（条目、认领、完成、FACT/FAIL 笔记、状态），正文存在日志旁的独立数据库，带硬上限（≤40 个文件、≤400KB 总量），还有一个阻塞式的 `read --wait`——同伴发帖即唤醒等待者。在 Terminal-Bench 4.0 的 10 项子集上，两个 agent 通过共享上下文协同，平均提升 12.5 个百分点准确率、1.78 倍加速。Agensh 把这条线索放大到了千级规模。
+
+## 三、数字：扩容真的有用吗
+
+![规模收益](./assets/agensh/scale.svg)
+
+两组数据回答"加 agent 到底加不加得动"：ProgramBench 最难 5 题，1 → 128 个 agent，通过率 19.31% → 28.78%（相对提升约 49%）；从零构建 pandoc（6 小时预算、无外网），1 → 1,024 个 agent，通过率 33.89% → 55.06%。对纯堆算力已经边际递减的难题，**组织化的边际收益还在**。
+
+工程可用性也到位了：v1.0 于 2026-10-23 发布，六天后的 v1.0.1 已支持 Copilot、Codex、Claude Code、Pi 作为底层单智能体 harness——单 agent 侧你可以用任何顺手的主力模型。开源版是单节点 harness，v1.0 发布包里就带着复现指南、论文与演示——从论文到可跑的仓库，中间没有隔着一句“敬请期待”。
+
+## 四、从论文到桌面：一个 issue 的故事
+
+这篇论文对我们不只在纸上。把它读透之后，2026-10-23 我在 pi-mesh 仓库提了[第 13 号 issue](https://github.com/cgarrot/pi-mesh/issues/13)：pi-mesh 已有消息接口（`mesh_send`/房间/优先级）和共享工作区（git + `mesh_reserve` 预约），独缺第三支柱共享上下文——提议按 Agensh/DeLM 的形状加 `board_write / board_read / board_grep`。
+
+维护者 cgarrot 的回复是整个故事里最值得学的一课：方向对，但**hash-only 台账让 pi-mesh 结构上当不了这块板**——把持久化塞进 broker 等于把路由器改造成数据库。正确的形状是独立包：以普通 peer 入房、自有存储、mesh 继续只做路由。于是有了 [pi-board](https://github.com/wait4xx/pi-board)：一天内出 v0.1，55 个测试零失败、真实 broker 上九步冒烟，issue 最终关闭时官方指针就落在它身上。上一篇文章介绍的[四件套](/archives/pi-mesh-stack/)，其记忆层就是从这篇论文长出来的。
+
+## 五、结语
+
+Agensh 的启示不是"1024"这个数字，而是它对"组织智能"的拆解：工作区、消息、共享上下文——三根支柱撑起自组织，任何一根都不需要一个更聪明的大脑。这个拆解在千级规模成立，在单机四件套成立，在单人加几个 agent 终端的小作坊同样成立。规模会变，支柱不变。
+
+相关阅读：[Spec Harness 详解](/archives/spec-harness/) · [pi-mesh 全家桶详解](/archives/pi-mesh-stack/)
@@ -0,0 +1,45 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="330" viewBox="0 0 960 330" font-family="ui-sans-serif, system-ui, 'Noto Sans SC', 'PingFang SC', sans-serif">
+  <rect width="960" height="330" fill="#ffffff"/>
+  <text x="480" y="40" text-anchor="middle" font-size="19" font-weight="600" fill="#111113">多智能体协作环：每个 worker 并发、异步地各跑一圈</text>
+
+  <!-- 环上 5 步 -->
+  <g font-size="12.5" fill="#33343a">
+    <rect x="46" y="150" width="150" height="76" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+    <text x="121" y="182" text-anchor="middle" font-weight="600" fill="#111113">① 收集上下文</text>
+    <text x="121" y="204" text-anchor="middle">读工作区 + 检索条目板</text>
+
+    <rect x="226" y="150" width="150" height="76" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+    <text x="301" y="182" text-anchor="middle" font-weight="600" fill="#111113">② 认领子任务</text>
+    <text x="301" y="204" text-anchor="middle">声明 CLAIM，冲突私聊解</text>
+
+    <rect x="406" y="150" width="150" height="76" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+    <text x="481" y="182" text-anchor="middle" font-weight="600" fill="#111113">③ 执行</text>
+    <text x="481" y="204" text-anchor="middle">本地改动推送分支</text>
+
+    <rect x="586" y="150" width="150" height="76" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+    <text x="661" y="182" text-anchor="middle" font-weight="600" fill="#111113">④ 验证</text>
+    <text x="661" y="204" text-anchor="middle">跑测试，证据说话</text>
+
+    <rect x="766" y="150" width="150" height="76" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+    <text x="841" y="182" text-anchor="middle" font-weight="600" fill="#111113">⑤ 合并进度</text>
+    <text x="841" y="204" text-anchor="middle">PR 合入共享工作区</text>
+  </g>
+
+  <g stroke="#6b6e78" stroke-width="1.5">
+    <line x1="196" y1="188" x2="224" y2="188"/><polygon points="224,188 215,183.5 215,192.5" fill="#6b6e78"/>
+    <line x1="376" y1="188" x2="404" y2="188"/><polygon points="404,188 395,183.5 395,192.5" fill="#6b6e78"/>
+    <line x1="556" y1="188" x2="584" y2="188"/><polygon points="584,188 575,183.5 575,192.5" fill="#6b6e78"/>
+    <line x1="736" y1="188" x2="764" y2="188"/><polygon points="764,188 755,183.5 755,192.5" fill="#6b6e78"/>
+  </g>
+  <path d="M 841 226 L 841 262 L 121 262 L 121 228" fill="none" stroke="#6b6e78" stroke-width="1.5"/>
+  <polygon points="121,228 116,237 126,237" fill="#6b6e78"/>
+  <text x="481" y="256" text-anchor="middle" font-size="12" fill="#6b6e78" dy="-6">下一圈</text>
+
+  <!-- 共享上下文条 -->
+  <rect x="120" y="70" width="720" height="52" rx="10" fill="rgba(52,84,209,0.05)" stroke="#3454d1" stroke-dasharray="6 4" stroke-width="1.2"/>
+  <text x="480" y="92" text-anchor="middle" font-size="13" font-weight="600" fill="#3454d1">共享上下文（类型化条目：OBSERVED / FACT / FAIL / CLAIM / PATCH_SUMMARY）</text>
+  <text x="480" y="112" text-anchor="middle" font-size="11.5" fill="#6b6e78">全程发布发现；条目刻意短小（约 100 字符），长文 detail 按需展开；近 2000 条常驻，全史靠布尔检索</text>
+  <line x1="200" y1="122" x2="150" y2="148" stroke="#a0a3ad" stroke-dasharray="4 3"/>
+  <line x1="760" y1="122" x2="820" y2="148" stroke="#a0a3ad" stroke-dasharray="4 3"/>
+  <text x="480" y="308" text-anchor="middle" font-size="12.5" fill="#6b6e78">论文称 FAIL 是"价值最高的条目"：一条被证伪的路，能止住全队的重复预算</text>
+</svg>
@@ -0,0 +1,64 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="420" viewBox="0 0 960 420" font-family="ui-sans-serif, system-ui, 'Noto Sans SC', 'PingFang SC', sans-serif">
+  <rect width="960" height="420" fill="#ffffff"/>
+  <text x="480" y="38" text-anchor="middle" font-size="19" font-weight="600" fill="#111113">从中心编排到自组织：Agensh 的三支柱</text>
+
+  <!-- 左：中心编排器 -->
+  <rect x="40" y="70" width="360" height="290" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="220" y="98" text-anchor="middle" font-size="13.5" font-weight="600" fill="#6b6e78">传统多智能体：中心编排器瓶颈</text>
+  <rect x="150" y="116" width="140" height="40" rx="8" fill="#ffffff" stroke="#6b6e78"/>
+  <text x="220" y="141" text-anchor="middle" font-size="12.5" fill="#33343a">orchestrator</text>
+  <g stroke="#a0a3ad">
+    <line x1="220" y1="156" x2="100" y2="230"/>
+    <line x1="220" y1="156" x2="180" y2="230"/>
+    <line x1="220" y1="156" x2="260" y2="230"/>
+    <line x1="220" y1="156" x2="340" y2="230"/>
+  </g>
+  <g font-size="11.5" fill="#6b6e78">
+    <rect x="72" y="230" width="56" height="30" rx="6" fill="#ffffff" stroke="#d0d4da"/><text x="100" y="249" text-anchor="middle">w1</text>
+    <rect x="152" y="230" width="56" height="30" rx="6" fill="#ffffff" stroke="#d0d4da"/><text x="180" y="249" text-anchor="middle">w2</text>
+    <rect x="232" y="230" width="56" height="30" rx="6" fill="#ffffff" stroke="#d0d4da"/><text x="260" y="249" text-anchor="middle">w3</text>
+    <rect x="312" y="230" width="56" height="30" rx="6" fill="#ffffff" stroke="#d0d4da"/><text x="340" y="249" text-anchor="middle">…</text>
+  </g>
+  <text x="220" y="300" text-anchor="middle" font-size="12" fill="#6b6e78">任务分配、进度汇总、结果裁决</text>
+  <text x="220" y="320" text-anchor="middle" font-size="12" fill="#6b6e78">全部挤过同一个上下文——</text>
+  <text x="220" y="340" text-anchor="middle" font-size="12" fill="#6b6e78">规模越大，编排器先成为天花板</text>
+
+  <!-- 中间箭头 -->
+  <line x1="410" y1="215" x2="460" y2="215" stroke="#6b6e78" stroke-width="1.6"/>
+  <polygon points="460,215 450,210 450,220" fill="#6b6e78"/>
+
+  <!-- 右：自组织三支柱 -->
+  <rect x="470" y="70" width="450" height="290" rx="10" fill="#ffffff" stroke="#3454d1" stroke-width="1.4"/>
+  <text x="695" y="98" text-anchor="middle" font-size="13.5" font-weight="600" fill="#3454d1">Agensh：无中心编排，三支柱基础设施</text>
+  <g font-size="12" fill="#33343a">
+    <rect x="490" y="114" width="130" height="86" rx="8" fill="#f6f7f9" stroke="#d0d4da"/>
+    <text x="555" y="140" text-anchor="middle" font-weight="600" fill="#111113">共享工作区</text>
+    <text x="555" y="160" text-anchor="middle">git 平台</text>
+    <text x="555" y="178" text-anchor="middle">分支 / PR / 合并</text>
+    <rect x="630" y="114" width="130" height="86" rx="8" fill="#f6f7f9" stroke="#d0d4da"/>
+    <text x="695" y="140" text-anchor="middle" font-weight="600" fill="#111113">消息接口</text>
+    <text x="695" y="160" text-anchor="middle">团队频道 + 私信</text>
+    <text x="695" y="178" text-anchor="middle">优先级送达</text>
+    <rect x="770" y="114" width="130" height="86" rx="8" fill="#f6f7f9" stroke="#d0d4da"/>
+    <text x="835" y="140" text-anchor="middle" font-weight="600" fill="#111113">共享上下文</text>
+    <text x="835" y="160" text-anchor="middle">类型化条目板</text>
+    <text x="835" y="178" text-anchor="middle">近期记忆 + 全史检索</text>
+  </g>
+  <g stroke="#a0a3ad">
+    <line x1="555" y1="200" x2="520" y2="240"/>
+    <line x1="695" y1="200" x2="660" y2="240"/>
+    <line x1="835" y1="200" x2="800" y2="240"/>
+    <line x1="555" y1="200" x2="620" y2="240"/>
+    <line x1="695" y1="200" x2="740" y2="240"/>
+    <line x1="835" y1="200" x2="880" y2="240"/>
+  </g>
+  <g font-size="11.5" fill="#6b6e78">
+    <rect x="492" y="240" width="56" height="30" rx="6" fill="#ffffff" stroke="#d0d4da"/><text x="520" y="259" text-anchor="middle">w1</text>
+    <rect x="592" y="240" width="56" height="30" rx="6" fill="#ffffff" stroke="#d0d4da"/><text x="620" y="259" text-anchor="middle">w2</text>
+    <rect x="692" y="240" width="56" height="30" rx="6" fill="#ffffff" stroke="#d0d4da"/><text x="740" y="259" text-anchor="middle">w3</text>
+    <rect x="792" y="240" width="56" height="30" rx="6" fill="#ffffff" stroke="#d0d4da"/><text x="820" y="259" text-anchor="middle">w4</text>
+    <rect x="852" y="240" width="56" height="30" rx="6" fill="#ffffff" stroke="#d0d4da"/><text x="880" y="259" text-anchor="middle">…</text>
+  </g>
+  <text x="695" y="308" text-anchor="middle" font-size="12" fill="#6b6e78">worker 自己跑协作环：收集上下文 → 认领 → 执行 → 验证 → 合并</text>
+  <text x="695" y="330" text-anchor="middle" font-size="12" fill="#6b6e78">发现发布到共享上下文，同伴在下一个工具调用边界收到广播</text>
+</svg>
@@ -0,0 +1,34 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="380" viewBox="0 0 960 380" font-family="ui-sans-serif, system-ui, 'Noto Sans SC', 'PingFang SC', sans-serif">
+  <rect width="960" height="380" fill="#ffffff"/>
+  <text x="480" y="38" text-anchor="middle" font-size="19" font-weight="600" fill="#111113">规模收益：扩容 agent 带来的通过率提升</text>
+  <text x="480" y="58" text-anchor="middle" font-size="11.5" fill="#a0a3ad">数据：arXiv:2609.26781</text>
+
+  <!-- 组 1：ProgramBench -->
+  <text x="235" y="92" text-anchor="middle" font-size="13.5" font-weight="600" fill="#111113">ProgramBench 最难 5 题</text>
+  <text x="235" y="112" text-anchor="middle" font-size="12" fill="#6b6e78">1 → 128 agents</text>
+  <g>
+    <!-- 柱底 y=300，柱顶 = 300 - 值*3.4 -->
+    <rect x="115" y="235" width="100" height="65" fill="#a0a3ad"/>
+    <rect x="255" y="202" width="100" height="98" fill="#3454d1"/>
+    <text x="165" y="227" text-anchor="middle" font-size="14" font-weight="600" fill="#33343a">19.31%</text>
+    <text x="165" y="322" text-anchor="middle" font-size="12" fill="#6b6e78">1 agent</text>
+    <text x="305" y="194" text-anchor="middle" font-size="14" font-weight="600" fill="#3454d1">28.78%</text>
+    <text x="305" y="322" text-anchor="middle" font-size="12" fill="#6b6e78">128 agents</text>
+  </g>
+  <text x="235" y="352" text-anchor="middle" font-size="12" fill="#33343a">相对提升约 49%</text>
+
+  <!-- 组 2：pandoc -->
+  <text x="645" y="92" text-anchor="middle" font-size="13.5" font-weight="600" fill="#111113">从零构建 pandoc（6h 预算 · 无外网）</text>
+  <text x="645" y="112" text-anchor="middle" font-size="12" fill="#6b6e78">1 → 1,024 agents</text>
+  <g>
+    <rect x="525" y="187" width="100" height="113" fill="#a0a3ad"/>
+    <rect x="665" y="113" width="100" height="187" fill="#3454d1"/>
+    <text x="575" y="179" text-anchor="middle" font-size="14" font-weight="600" fill="#33343a">33.89%</text>
+    <text x="575" y="322" text-anchor="middle" font-size="12" fill="#6b6e78">1 agent</text>
+    <text x="715" y="105" text-anchor="middle" font-size="14" font-weight="600" fill="#3454d1">55.06%</text>
+    <text x="715" y="322" text-anchor="middle" font-size="12" fill="#6b6e78">1,024 agents</text>
+  </g>
+  <text x="645" y="352" text-anchor="middle" font-size="12" fill="#33343a">+21.2 个百分点</text>
+
+  <line x1="480" y1="84" x2="480" y2="330" stroke="#e3e5ea"/>
+</svg>
@@ -0,0 +1,47 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="980" height="330" viewBox="0 0 980 330" font-family="ui-sans-serif, system-ui, 'Noto Sans SC', 'PingFang SC', sans-serif">
+  <rect width="980" height="330" fill="#ffffff"/>
+  <text x="490" y="40" text-anchor="middle" font-size="19" font-weight="600" fill="#111113">一次典型合奏：四件套怎么咬合</text>
+
+  <!-- 5 nodes -->
+  <rect x="30" y="80" width="158" height="96" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="109" y="108" text-anchor="middle" font-size="14" font-weight="600" fill="#3454d1" font-family="ui-monospace, monospace">mesh_send</text>
+  <text x="109" y="132" text-anchor="middle" font-size="12" fill="#33343a">契约式派单 / 对话</text>
+  <text x="109" y="152" text-anchor="middle" font-size="11.5" fill="#6b6e78">五字段任务包 + 期限</text>
+
+  <rect x="216" y="80" width="158" height="96" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="295" y="108" text-anchor="middle" font-size="14" font-weight="600" fill="#3454d1" font-family="ui-monospace, monospace">board_grep</text>
+  <text x="295" y="132" text-anchor="middle" font-size="12" fill="#33343a">先查团队记忆</text>
+  <text x="295" y="152" text-anchor="middle" font-size="11.5" fill="#6b6e78">FAIL 可检索不重烧</text>
+
+  <rect x="402" y="80" width="158" height="96" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="481" y="108" text-anchor="middle" font-size="14" font-weight="600" fill="#3454d1" font-family="ui-monospace, monospace">job_run</text>
+  <text x="481" y="132" text-anchor="middle" font-size="12" fill="#33343a">长活交后台</text>
+  <text x="481" y="152" text-anchor="middle" font-size="11.5" fill="#6b6e78">turn 不阻塞</text>
+
+  <rect x="588" y="80" width="158" height="96" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="667" y="108" text-anchor="middle" font-size="14" font-weight="600" fill="#3454d1" font-family="ui-monospace, monospace">mesh_claim</text>
+  <text x="667" y="132" text-anchor="middle" font-size="12" fill="#33343a">单写者租约</text>
+  <text x="667" y="152" text-anchor="middle" font-size="11.5" fill="#6b6e78">epoch:fence 围栏</text>
+
+  <rect x="774" y="80" width="158" height="96" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="853" y="108" text-anchor="middle" font-size="14" font-weight="600" fill="#3454d1" font-family="ui-monospace, monospace">board_write</text>
+  <text x="853" y="132" text-anchor="middle" font-size="12" fill="#33343a">留痕</text>
+  <text x="853" y="152" text-anchor="middle" font-size="11.5" fill="#6b6e78">CLAIM 带租约号</text>
+
+  <!-- 正向箭头 -->
+  <line x1="188" y1="128" x2="214" y2="128" stroke="#6b6e78" stroke-width="1.5"/>
+  <polygon points="214,128 205,123.5 205,132.5" fill="#6b6e78"/>
+  <line x1="374" y1="128" x2="400" y2="128" stroke="#6b6e78" stroke-width="1.5"/>
+  <polygon points="400,128 391,123.5 391,132.5" fill="#6b6e78"/>
+  <line x1="560" y1="128" x2="586" y2="128" stroke="#6b6e78" stroke-width="1.5"/>
+  <polygon points="586,128 577,123.5 577,132.5" fill="#6b6e78"/>
+  <line x1="746" y1="128" x2="772" y2="128" stroke="#6b6e78" stroke-width="1.5"/>
+  <polygon points="772,128 763,123.5 763,132.5" fill="#6b6e78"/>
+
+  <!-- 回环箭头 -->
+  <path d="M 853 176 L 853 216 L 109 216 L 109 178" fill="none" stroke="#a0a3ad" stroke-width="1.4" stroke-dasharray="5 4"/>
+  <polygon points="109,178 104,187 114,187" fill="#a0a3ad"/>
+  <text x="481" y="238" text-anchor="middle" font-size="12" fill="#6b6e78">发现与结论回写团队记忆，下一轮派单从存量知识起步</text>
+
+  <text x="490" y="290" text-anchor="middle" font-size="13.5" fill="#33343a">对话走 mesh · 记忆上 board · 长活交 jobd · 排他靠租约</text>
+</svg>
@@ -0,0 +1,47 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="470" viewBox="0 0 960 470" font-family="ui-sans-serif, system-ui, 'Noto Sans SC', 'PingFang SC', sans-serif">
+  <rect width="960" height="470" fill="#ffffff"/>
+  <text x="480" y="38" text-anchor="middle" font-size="19" font-weight="600" fill="#111113">pi-mesh 工具族：一个路由器，三个卫星</text>
+
+  <!-- 顶部：pi 终端 -->
+  <rect x="80" y="62" width="200" height="58" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="180" y="86" text-anchor="middle" font-size="13.5" font-weight="600" fill="#111113">pi 终端 @op-gitea</text>
+  <text x="180" y="106" text-anchor="middle" font-size="11.5" fill="#6b6e78">edit/write 受预约拦截</text>
+  <rect x="380" y="62" width="200" height="58" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="480" y="86" text-anchor="middle" font-size="13.5" font-weight="600" fill="#111113">pi 终端 @op-artalk</text>
+  <text x="480" y="106" text-anchor="middle" font-size="11.5" fill="#6b6e78">读回执 · 忙闲状态</text>
+  <rect x="680" y="62" width="200" height="58" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="780" y="86" text-anchor="middle" font-size="13.5" font-weight="600" fill="#111113">pimesh attach / CLI</text>
+  <text x="780" y="106" text-anchor="middle" font-size="11.5" fill="#6b6e78">无会话独立 peer</text>
+
+  <line x1="180" y1="120" x2="180" y2="150" stroke="#a0a3ad"/>
+  <line x1="480" y1="120" x2="480" y2="150" stroke="#a0a3ad"/>
+  <line x1="780" y1="120" x2="780" y2="150" stroke="#a0a3ad"/>
+
+  <!-- mesh 骨干 -->
+  <rect x="60" y="150" width="840" height="110" rx="12" fill="#ffffff" stroke="#3454d1" stroke-width="1.6"/>
+  <text x="90" y="180" font-size="15" font-weight="600" fill="#3454d1">pi-mesh —— 通信骨干（github.com/cgarrot/pi-mesh）</text>
+  <text x="90" y="206" font-size="12.5" fill="#33343a">broker（内存态：peers / rooms / 邮箱 / 限速）· 房间与角色 member/observer</text>
+  <text x="90" y="228" font-size="12.5" fill="#33343a">mesh_reserve 路径预约 · mesh_claim 单写者租约（epoch:fence，commit-msg 钩子拒过期围栏）</text>
+  <text x="90" y="250" font-size="12.5" fill="#33343a">优先级 normal / urgent / force · 状态诚实三档 delivered ≠ read ≠ answered · 台账 hash-only</text>
+
+  <!-- 连接线到卫星 -->
+  <line x1="240" y1="260" x2="240" y2="300" stroke="#a0a3ad"/>
+  <line x1="480" y1="260" x2="480" y2="300" stroke="#a0a3ad"/>
+  <line x1="720" y1="260" x2="720" y2="300" stroke="#a0a3ad"/>
+
+  <!-- 三个卫星 -->
+  <rect x="70" y="300" width="330" height="110" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="90" y="328" font-size="14" font-weight="600" fill="#111113">pi-board —— 团队记忆板</text>
+  <text x="90" y="350" font-size="12" fill="#33343a">OBSERVED/FACT/FAIL/CLAIM/PATCH_SUMMARY</text>
+  <text x="90" y="370" font-size="12" fill="#33343a">有界 append-only 存储 · 布尔检索 board_grep</text>
+  <text x="90" y="390" font-size="11.5" fill="#6b6e78">以普通 peer 入房；自有存储，broker 零持久化</text>
+
+  <rect x="430" y="300" width="330" height="110" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="450" y="328" font-size="14" font-weight="600" fill="#111113">pi-jobd —— 后台作业守护</text>
+  <text x="450" y="350" font-size="12" fill="#33343a">脱离 turn 的进程组 · 存活于 /reload 与会话之外</text>
+  <text x="450" y="370" font-size="12" fill="#33343a">诚实状态机（lost = 无法证明归属则拒操作）</text>
+  <text x="450" y="390" font-size="11.5" fill="#6b6e78">mesh_job_control 跨 peer 远程 stop/pause/resume</text>
+
+  <rect x="70" y="424" width="690" height="38" rx="8" fill="rgba(52,84,209,0.05)" stroke="#3454d1" stroke-dasharray="6 4" stroke-width="1.1"/>
+  <text x="415" y="448" text-anchor="middle" font-size="12" fill="#33343a">pi-subagents（worker 控制：spawn/steer/abort，mesh_run_control）与上面三者同族协作</text>
+</svg>
@@ -0,0 +1,37 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="440" viewBox="0 0 960 440" font-family="ui-sans-serif, system-ui, 'Noto Sans SC', 'PingFang SC', sans-serif">
+  <rect width="960" height="440" fill="#ffffff"/>
+  <text x="480" y="40" text-anchor="middle" font-size="19" font-weight="600" fill="#111113">任务包解剖：.spec/specs/YYYY-MM-DD_slug/</text>
+
+  <!-- 左：目录树 -->
+  <rect x="40" y="70" width="400" height="250" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="60" y="102" font-size="15" font-weight="600" fill="#111113" font-family="ui-monospace, monospace">2026-10-26_blog-5f/</text>
+  <text x="80" y="140" font-size="14" fill="#33343a" font-family="ui-monospace, monospace">├── spec.md</text>
+  <text x="240" y="140" font-size="13" fill="#6b6e78">范围 · 假设 · 已证伪</text>
+  <text x="80" y="180" font-size="14" fill="#33343a" font-family="ui-monospace, monospace">├── tasks.md</text>
+  <text x="240" y="180" font-size="13" fill="#6b6e78">boundary + verify</text>
+  <text x="80" y="220" font-size="14" fill="#33343a" font-family="ui-monospace, monospace">└── handoff.md</text>
+  <text x="240" y="220" font-size="13" fill="#6b6e78">跨会话交接（可选）</text>
+  <line x1="80" y1="248" x2="400" y2="248" stroke="#e3e5ea"/>
+  <text x="80" y="278" font-size="13" fill="#6b6e78">收尾后整包归档至 .spec/specs/archive/，</text>
+  <text x="80" y="300" font-size="13" fill="#6b6e78">归档目录就是项目的工程日志。</text>
+
+  <!-- 箭头 -->
+  <line x1="440" y1="195" x2="500" y2="195" stroke="#6b6e78" stroke-width="1.5"/>
+  <polygon points="500,195 490,190 490,200" fill="#6b6e78"/>
+  <text x="470" y="180" text-anchor="middle" font-size="12" fill="#6b6e78">每个任务</text>
+
+  <!-- 右：任务卡片 -->
+  <rect x="500" y="70" width="420" height="250" rx="10" fill="#ffffff" stroke="#3454d1" stroke-width="1.5"/>
+  <rect x="500" y="70" width="420" height="40" rx="10" fill="rgba(52,84,209,0.06)"/>
+  <text x="520" y="96" font-size="13.5" font-weight="600" fill="#111113">- [x] T3 构建期内容 lint + build.sh 守卫</text>
+  <text x="520" y="136" font-size="12.5" fill="#33343a" font-family="ui-monospace, monospace">claim: op-gitea（mesh 车道）</text>
+  <text x="520" y="164" font-size="12" fill="#33343a" font-family="ui-monospace, monospace">boundary: 新建 content-lint.mjs + 守卫挂载</text>
+  <text x="520" y="200" font-size="12.5" font-weight="600" fill="#3454d1" font-family="ui-monospace, monospace">verify:</text>
+  <text x="540" y="224" font-size="12" fill="#33343a" font-family="ui-monospace, monospace">node scripts/build-perf/content-lint.mjs dist</text>
+  <text x="540" y="246" font-size="12" fill="#33343a" font-family="ui-monospace, monospace">&amp;&amp; bash -n infra/deploy/build.sh</text>
+  <text x="520" y="290" font-size="12.5" fill="#6b6e78">verify 是只读断言：跑出退出码 0 才许勾选，</text>
+  <text x="520" y="310" font-size="12.5" fill="#6b6e78">口头"过了"永远不算数。</text>
+
+  <text x="480" y="372" text-anchor="middle" font-size="13.5" fill="#6b6e78">boundary 划定"能动什么"，verify 划定"怎么证明做完"——两行合同，缺一不勾</text>
+  <line x1="360" y1="392" x2="600" y2="392" stroke="#e3e5ea"/>
+</svg>
@@ -0,0 +1,51 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="960" height="350" viewBox="0 0 960 350" font-family="ui-sans-serif, system-ui, 'Noto Sans SC', 'PingFang SC', sans-serif">
+  <rect width="960" height="350" fill="#ffffff"/>
+  <text x="480" y="38" text-anchor="middle" font-size="19" font-weight="600" fill="#111113">阶段流水线：五个核心命令与它们把守的门</text>
+
+  <!-- 5 个节点 -->
+  <!-- new -->
+  <rect x="36" y="72" width="152" height="120" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="112" y="100" text-anchor="middle" font-size="14" font-weight="600" fill="#3454d1" font-family="ui-monospace, monospace">/spec:new</text>
+  <text x="112" y="126" text-anchor="middle" font-size="12.5" fill="#33343a">建任务包</text>
+  <text x="112" y="146" text-anchor="middle" font-size="12.5" fill="#33343a">spec.md + tasks.md</text>
+  <text x="112" y="172" text-anchor="middle" font-size="11.5" fill="#6b6e78">模板占位未填 → 拒 run</text>
+  <!-- run -->
+  <rect x="220" y="72" width="152" height="120" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="296" y="100" text-anchor="middle" font-size="14" font-weight="600" fill="#3454d1" font-family="ui-monospace, monospace">/spec:run</text>
+  <text x="296" y="126" text-anchor="middle" font-size="12.5" fill="#33343a">逐任务执行</text>
+  <text x="296" y="146" text-anchor="middle" font-size="12.5" fill="#33343a">verify 跑通才勾选</text>
+  <text x="296" y="172" text-anchor="middle" font-size="11.5" fill="#6b6e78">阻塞任务打 ! 上浮</text>
+  <!-- check -->
+  <rect x="404" y="72" width="152" height="120" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="480" y="100" text-anchor="middle" font-size="14" font-weight="600" fill="#3454d1" font-family="ui-monospace, monospace">/spec:check</text>
+  <text x="480" y="126" text-anchor="middle" font-size="12.5" fill="#33343a">复核轮</text>
+  <text x="480" y="146" text-anchor="middle" font-size="12.5" fill="#33343a">问题当轮回写修复</text>
+  <text x="480" y="172" text-anchor="middle" font-size="11.5" fill="#6b6e78">闭环项五选一登记</text>
+  <!-- done -->
+  <rect x="588" y="72" width="152" height="120" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="664" y="100" text-anchor="middle" font-size="14" font-weight="600" fill="#3454d1" font-family="ui-monospace, monospace">/spec:done</text>
+  <text x="664" y="126" text-anchor="middle" font-size="12.5" fill="#33343a">归档 + 包提交</text>
+  <text x="664" y="146" text-anchor="middle" font-size="12.5" fill="#33343a">证据随包入档</text>
+  <text x="664" y="172" text-anchor="middle" font-size="11.5" fill="#6b6e78">验收面证据必须真实</text>
+  <!-- push -->
+  <rect x="772" y="72" width="152" height="120" rx="10" fill="#f6f7f9" stroke="#d0d4da"/>
+  <text x="848" y="100" text-anchor="middle" font-size="14" font-weight="600" fill="#3454d1" font-family="ui-monospace, monospace">/spec:push</text>
+  <text x="848" y="126" text-anchor="middle" font-size="12.5" fill="#33343a">合并 + 推送</text>
+  <text x="848" y="146" text-anchor="middle" font-size="12.5" fill="#33343a">删已并分支</text>
+  <text x="848" y="172" text-anchor="middle" font-size="11.5" fill="#6b6e78">只认 spec/ 前缀分支</text>
+
+  <!-- 箭头 -->
+  <line x1="188" y1="132" x2="218" y2="132" stroke="#6b6e78" stroke-width="1.5"/>
+  <polygon points="218,132 209,127.5 209,136.5" fill="#6b6e78"/>
+  <line x1="372" y1="132" x2="402" y2="132" stroke="#6b6e78" stroke-width="1.5"/>
+  <polygon points="402,132 393,127.5 393,136.5" fill="#6b6e78"/>
+  <line x1="556" y1="132" x2="586" y2="132" stroke="#6b6e78" stroke-width="1.5"/>
+  <polygon points="586,132 577,127.5 577,136.5" fill="#6b6e78"/>
+  <line x1="740" y1="132" x2="770" y2="132" stroke="#6b6e78" stroke-width="1.5"/>
+  <polygon points="770,132 761,127.5 761,136.5" fill="#6b6e78"/>
+
+  <!-- 恢复车道 -->
+  <rect x="36" y="228" width="888" height="76" rx="10" fill="rgba(52,84,209,0.05)" stroke="#3454d1" stroke-dasharray="6 4" stroke-width="1.2"/>
+  <text x="480" y="258" text-anchor="middle" font-size="13.5" font-weight="600" fill="#111113">中断恢复是常态设计</text>
+  <text x="480" y="284" text-anchor="middle" font-size="12.5" fill="#33343a">任意时刻重跑 /spec:run，从 tasks.md 勾选状态续跑；/spec:autorun 可续自动链（默认 5 轮上限，--max-rounds 可调）</text>
+</svg>
@@ -0,0 +1,34 @@
+---
+title: "排版能力样例"
+pubDate: 2026-11-02
+category: tech
+tags: [test, hidden]
+# 排版/斜体/白名单测试样张（fix3 车道）：hidden 不列出，构建与 E2E 验证用
+draft: false
+---
+
+本篇验证三件事：斜体行内渲染、受限排版类白名单、图注类。
+
+## 斜体（应为行内，不换行不居中）
+
+这一句里有 *行内斜体强调* 夹在文字中间，它必须与正文同处一行。
+
+*这一整段是斜体独占段，它不该变成块级居中。*
+
+## 受限排版类（白名单）
+
+<span class="ink-muted">这一段是 ink-muted 灰字。</span>
+<span class="font-kai">这一段是霞鹜文楷字族。</span>
+<span class="font-mono">这一段是等宽字族 mono。</span>
+
+<p class="drop-cap">首字下沉段落：秋天的海面像一块被风抚平的铁皮，落日把它的边缘烧红了一圈。</p>
+
+<p class="quote-line">所谓暮色，就是光慢慢地承认自己要走。</p>
+
+## 白名单剔除（非法类与内联样式必须被剥离）
+
+<span class="evil-class ink-2" style="color:#ff0000" onclick="alert(1)">这一段同时带了非法类、内联颜色与 onclick，构建后应只剩 ink-2 且 style/onclick 消失。</span>
+
+## 图注（类驱动）
+
+<p class="fig-cap">这是显式图注样式（fig-cap），居中灰字。</p>
@@ -0,0 +1,33 @@
+---
+title: "字体族样例"
+pubDate: 2026-11-02
+category: reading
+tags: [test, hidden]
+draft: false
+---
+
+字体测试样张（hidden）：验证系统回退字族的渲染。
+
+<p class="font-song">宋体族（系统回退）：秋天的海面像一块被风抚平的铁皮。</p>
+
+<p class="font-kai-sys">楷体族（系统回退）：秋天的海面像一块被风抚平的铁皮。</p>
+
+<p class="font-hei-sys">黑体族（系统回退）：秋天的海面像一块被风抚平的铁皮。</p>
+
+<p class="font-fangsong">仿宋族（系统回退）：秋天的海面像一块被风抚平的铁皮。</p>
+
+<p class="ink-warm">暖调正文：秋天的海面像一块被风抚平的铁皮。</p>
+
+<p class="ink-cool">冷调正文：秋天的海面像一块被风抚平的铁皮。</p>
+
+<p class="ink-faint">最淡可读档：秋天的海面像一块被风抚平的铁皮。</p>
+
+<p class="ink-accent-soft">弱强调：秋天的海面像一块被风抚平的铁皮。</p>
+
+<p class="c-blue">蓝色标准：秋天的海面像一块被风抚平的铁皮。</p>
+<p class="c-yellow">黄色标准（已压暗）：秋天的海面像一块被风抚平的铁皮。</p>
+<p class="c-red-soft">红色 soft：秋天的海面像一块被风抚平的铁皮。</p>
+
+<p class="font-huiwen">汇文明朝体（OFL，切片自托管）：秋天的海面像一块被风抚平的铁皮。</p>
+
+<p class="font-kuaile">站酷快乐体（OFL，艺术字）：秋天的海面像一块被风抚平的铁皮。</p>
@@ -1,11 +1,15 @@
 ---
-title: "海风中失落的血色馈赠"
+title: 海风中失落的血色馈赠
 pubDate: 2026-03-25
 category: reading
-tags: [read]
+tags:
+  - read
 mood: '#0f766e'
-bookAuthor: '阿利斯泰尔·麦克劳德'
-description: '秋是萧瑟之感：父亲、老马与少年，在失落后各自直面现实。'
+bookAuthor: 阿利斯泰尔·麦克劳德
+description: 秋是萧瑟之感：父亲、老马与少年，在失落后各自直面现实。
+cover: ./assets/海风中失落的血色馈赠.png
+hiddenTag: false
+draft: false
 ---

 ### 秋-斯科特之秋、父亲之秋、少年之秋（冬的预演）
@@ -0,0 +1,30 @@
+---
+title: "链接卡片样例"
+pubDate: 2026-11-02
+category: tech
+tags: [test, hidden]
+# 链接卡片（OG 预览）测试样张：hidden 不列出，构建验证用；保留为活样例
+draft: false
+---
+
+本篇验证链接卡片：独立成段的裸链接转 OG 预览卡，内联链接保持普通样式。
+
+## 正例：有 OG 的站点
+
+https://wait4x.online/
+
+https://astro.build/
+
+## 反例：404 与无 OG 站点（应回落普通链接，构建不报错）
+
+https://wait4x.online/definitely-not-a-real-page-404/
+
+https://example.com/
+
+## 内联链接保持普通样式（不应变卡）
+
+这里有一个内联链接 [Astro 官网](https://astro.build/) 夹在句子中间，它必须保持普通链接样式，不能整篇变卡片墙。
+
+## 卡片首行文字（markdown 链接形态同样触发）
+
+[wait4x.online 首页](https://wait4x.online/)
@@ -14,7 +14,7 @@ draft: false

 ![样例照片](./assets/media-sample/sample-photo.jpg)

-*图注写法：斜体单独成段，photos 目录样片副本（1600×2400 竖幅）。*
+<p class="fig-cap">图注新写法：fig-cap 类，photos 目录样片副本（1600×2400 竖幅）。</p>

 ## 视频（raw HTML，H.264 320×240，ffmpeg testsrc2 生成）

@@ -0,0 +1,62 @@
+---
+title: "pi-mesh 全家桶详解：单机多智能体协同的四件套"
+pubDate: 2026-11-01
+category: tech
+tags: [工程实践, AI 协作]
+---
+
+[pi](https://github.com/earendil-works/pi) 是我们日常用的编码智能体宿主。单开一个终端时它是个安静的助手；但同时开三四个终端、每个里面一个 agent 抢同一个仓库时，问题就来了：谁在线？谁在改哪个文件？消息发出去了对方到底看没看见？半夜跑着的构建谁有权停？
+
+围绕 [pi-mesh](https://github.com/cgarrot/pi-mesh) 长出来的一族小工具把这层协同做成了基建。它们各管一摊，咬合成套：
+
+![pi-mesh 工具族](./assets/pi-mesh-stack/stack.svg)
+
+## 一、pi-mesh：通信骨干
+
+pi-mesh 是一条本机总线：一个脱离会话存活的 broker（NDJSON 帧走 unix socket），每个 pi 终端以别名成为 peer，加入房间（room）。消息 < 50ms 到达，零运行时依赖，Node ≥ 20。
+
+它最值得称道的是**诚实状态模型**：`delivered`（写进了对方套接字）≠ `read`（注入了对方会话）≠ `answered`（拿到了显式回复）——三者永不混淆，没有一个是"完成"的意思。配套的**持久台账是 hash-only 的**：消息正文永不落盘，重启后能审计"谁在何时给谁发过什么"，但看不到内容。这个自我约束后来成了整个工具族的设计公理：**mesh 只做路由器，永不做数据库。**
+
+协同刚需有三个都在骨干里：
+
+- **`mesh_reserve` 路径预约**：改文件前先预约，其他 peer 的 `edit`/`write` 工具在该路径上直接被拦——并发编辑靠机制防，不靠喊话。
+- **`mesh_claim` 任务租约**：单写者锁，带 `epoch:fence`（broker 重启即作废旧围栏）；提交信息里写 `Mesh-Lease: task#leaseId#epoch:fence`，配套 commit-msg 钩子直接拒绝过期围栏的提交。
+- **能力路由 `cap:`**：`mesh_send({ "to": "cap:deploy", ... })` 把任务发给任意一个空闲且自报该能力的 peer，而不是等忙着的队友。消息优先级三档：normal 排队、urgent 插队、force 先中止对方当前回合再送达（force 属管控类，必须带 reason）。
+
+另有 `mesh_wait_all` 做群裁（一次收回“谁答了、谁没答”的名单）、`mesh_status` 看 peer 忙闲（● 干活 / ○ 空闲 / ✕ 卡死）、`pimesh` CLI 支持无会话接入（`pimesh attach` 能收养死掉会话的身份）。跨机部署也支持：一台起 broker，其余机器做客户端。
+
+诚实的颗粒度细到退出码：CLI 里 3 表示 `expired`——晚到的答复仍会送达，只是你等起见超时了；5 表示租约已过期，`commit-msg` 钩子据此把提交拒之门外。甚至 ESC 清空消息队列这种宿主边界也考虑到了：批量注入若撞上回合中止，broker 会在该回合结束后经中止安全通道重投（有界重试），状态页能看到“中止清除恢复重投”计数。
+
+## 二、pi-board：团队记忆板
+
+消息是易逝的，台账是 hash-only 的，那"我们学到了什么"存哪？[pi-board](https://github.com/wait4xx/pi-board) 补上这层。五种类型化条目：
+
+- **OBSERVED**——看到了什么（不承诺）
+- **FACT**——验证过的事实
+- **FAIL**——一条被证伪的路（价值最高：全队不必再烧第二次预算）
+- **CLAIM**——认领声明，与 `mesh_claim` 租约配对（板只记录，从不执行）
+- **PATCH_SUMMARY**——落了什么改动
+
+设计上处处是“有界与诚实”：append-only 本地存储、refuse-not-evict（超限拒绝写入而非静默淘汰）、条目默认短小、长文 `detail` 只能按 id 展开、布尔检索（`,` = OR，`&` = AND）覆盖全史而 `board_read` 只看近期窗口；检索无果时返回诚实的空，绝不猜一条充数。写入以普通广播帧发进房间，turn 边界有新 FAIL 摘要行；房间角色 member / observer 沿用 mesh 语义，只读 peer 永远不会在重连后被误升为写者。它以普通 peer 身份入房——**存储全在板自己家里，broker 里零持久化**。附带的 `piboard` CLI 五个动词一把梭：join（member / observer）/ watch / write / read / grep，一动词一动作，无会话的终端也能进房只读围观。这套类型学与"小条目+按需展开+近期记忆/全史检索"的分工直接来自学术论文(血统故事见[下一篇](/archives/agensh/))。
+
+## 三、pi-jobd：后台作业守护
+
+`bash` 会阻塞当前回合，`/reload` 会杀进程。[pi-jobd](https://github.com/cgarrot/pi-jobd) 把长命令放进独立进程组，由 per-user 守护监管：~150ms 返回，作业存活于会话之外。什么时候用它？三条判据：命令预计超过 60-90 秒；你必须边跑边干别的；或者它得扛过 `/reload` 和会话结束——以及"别的 agent 应该能停它"这一条：`mesh_job_control` 让任一授权 peer 远程 stop/pause/resume 别人的后台作业。
+
+状态机同样诚实：`running / paused / stopped / exited / failed`，外加一个 `lost`——守护重启后无法证明 pid 归属时，宁可拒绝 stop 也绝不信号一个来路不明的进程。这个包还有个巧思：装包不够，模型还得**知道什么时候用**——它靠 prompt 快照、七个工具上的决策守则和一份按需加载的 skill 三层把使用时机喂给模型。
+
+## 四、pi-subagents：worker 控制
+
+[pi-subagents](https://github.com/nicobailon/pi-subagents) 管的是进程内子代理：前台子代理流式跑在对话里，后台子代理活在独立的 runner 进程中随时可查。装完即用，不需要学斜杠命令——直接说"用 reviewer 审这个 diff"就行。它预置了 scout（侦察）、reviewer（审查）这类常用角色，也支持保存的工作流和并行审查。与 mesh 的接口是 `mesh_run_control`：远程 stop 或 steer 一个 peer 的 RPC worker。
+
+## 五、四件套的一次合奏
+
+![协作循环](./assets/pi-mesh-stack/loop.svg)
+
+## 六、上手五分钟
+
+安装各一行：mesh 与 subagents 走 pi 包管理——`pi install npm:pi-mesh-extension`、`pi install npm:pi-subagents`；pi-board 还没发 npm，源码三步（clone、`npm ci`、`npm run build`），且可 CLI 独立用（不需要 mesh 也能读写本地板）；pi-jobd 同样源码构建，`pijob run / list / log / stop` 开箱即用。装完在同一目录开两个 pi 会话，就是两个 peer，`mesh_status` 互相可见——协同基建的“零配置”不是口号。
+
+对话走 mesh，记忆上 board，长活交 jobd，排他靠租约——四个包各司其职，没有任何一个越界。这个博客的重设计期就是这套东西的实战场：两个 mesh 终端（op-gitea、op-artalk）与主线并行，一天 19 连发；发布链中断的修复窗口里，主线预约了 build.sh 紧急处置，另一边赶去补刀的编辑被预约机制正确拦下——撞车靠规则防住，不靠谁手快。
+
+四件套加起来没有一个数据库、没有一个中心大脑，却把"谁在线、谁在干啥、学到过啥、长活谁看着"四件事全部钉死。小工具、硬边界、诚实状态——这套哲学比任何一个具体包都值得抄。
@@ -0,0 +1,61 @@
+---
+title: "Spec Harness 详解：把长程开发装进可验收的任务包"
+pubDate: 2026-11-01
+category: tech
+tags: [工程实践, AI 协作]
+---
+
+AI 编程智能体最不缺的是写代码的带宽，最缺的是记忆。一个跨了好几轮会话的任务，改到一半的方案、已经否决的路线、验收口径，散落在聊天记录里就等于丢了——换一个会话、重启一次终端，上下文归零。[Spec Harness](https://github.com/MicTx/spec-harness) 解决的就是这个问题：它是一个面向 AI 编程智能体的任务包工作流工具，把长程改动保存为**可恢复、可验证的 Development Record**，用范围、证据和 Git 门禁管住全程。它不提供模型，也不替你做产品决策。
+
+一句话概括它的世界观：**当一个编码任务的寿命超过一段对话，缺的不是更聪明的模型，而是一份大家（包括未来的你）都能读的合同。**
+
+## 一、核心抽象：任务包
+
+所有工作装进 `.spec/specs/YYYY-MM-DD_slug/` 目录，核心是两个文件：`spec.md` 写范围、假设与取舍（还有一节很特别的"已证伪路径"，后面细说），`tasks.md` 写任务清单。收尾后整包归档到 `.spec/specs/archive/`，归档目录本身就是项目的工程日志。
+
+每个任务必须带两行合同——**boundary**（这个任务能动哪些文件）和 **verify**（怎么证明做完了）。verify 是只读断言，跑出退出码 0 才许勾选。拿这个博客真实归档的 `2026-10-26_blog-5f` 包里 T3 任务举例：
+
+![任务包解剖](./assets/spec-harness/package-anatomy.svg)
+
+boundary 划定"能动什么"，verify 划定"怎么证明做完"——两行齐备，缺一不勾。这不是形式主义：多 agent 并行时，boundary 就是车道之间的护栏（我们的实践里，全局样式文件只许主线动，车道要新变量走申请）；verify 则把"看起来好了"和"证明做完了"区分开，口头"过了"永远不算数。
+
+`spec.md` 里最有味道的一节是**已证伪路径**：被否决的方案连否定理由一起入库。我们的 blog-5f 包里记着三条——首屏 banner 化（视觉裁定否决）、热力图换绿（破坏灰阶骨架）、标题 27px 收到 22px（层级锚点，要轻减字重不减号）。下次谁想再试一遍，先读档案，少烧一轮预算。
+
+## 二、阶段流水线：五个核心命令与它们把守的门
+
+![阶段流水线](./assets/spec-harness/pipeline.svg)
+
+五个核心命令串起一条可验证链：**目标 → 范围 → 任务 → 验证 → 归档 → 提交 → 推送**。每个阶段之间都有门把守：`spec.md` 有模板占位符就拒绝进入 run；`done` 要求每个任务 boundary/verify 齐备、验收面全绿且至少有一条非占位证据（脚本输出、测试结果）；`push` 只合并 `spec/` 前缀的集成分支，文件改动与提交永远分开做，禁用 `--no-verify`。
+
+被阻塞的任务会打 `!` 标记上浮给用户，绝不静默跳过；复核轮（check）发现的可执行问题必须当轮写回任务包并修复，不允许把"待办"当交付物甩给用户。
+
+**中断恢复是常态设计**——这是它对“任务寿命超过对话”最直接的回答：任意时刻重跑 `/spec:run`，从 `tasks.md` 的勾选状态续跑，不依赖任何对话记忆。更进一步，`/spec:autoplan` 做交互式规划（澄清目标后过框架、细节、复核三轮，规划就绪即停，不自动开工），`/spec:autorun` 按规划逐包执行，默认最多 5 轮自动链（`--max-rounds` 可调），暂停后从同一步恢复；一键式入口 `/spec:goal` 则把规划、执行、复核、归档、提交一次跑完。
+
+命令面共 12 个阶段命令：core 档装五个核心命令，full 档补齐 goal / autoplan / autorun / update / status / doctor / organize 七个扩展件——`doctor` 做环境自检与修复，`organize` 做结构审计。还有一个容易被忽略的细节：安装只是放文件，不会主动逐任务评估；想让它在你动手前主动问一句“这事要不要开包”，需要显式接线一次 `install_activation_hooks.py --mode on`。判据看交付形状——独立验收面、实际实施者、可恢复的在途任务；小修、只读调查、一次性实验都直接做。它防的是“忘了评估”，不防刻意瞒报——文档里对此毫不讳言。
+
+## 三、多 agent 编排：一个编排者，有边界的帮工
+
+Spec Harness 对多 agent 的态度很克制：**主会话是唯一的编排者**，路由、集成、验收和 `done`/`push` 门禁永远不出主线。旁支工作（探索、构建、审查这类上下文无关的活）可以委托，但要先过机器路由决策（`scripts/route_decision.py`）并写下任务合同：目标、范围、排除区、产出、验证方式五项齐备才许派。它甚至为"跨会话交接"准备了可选的 `handoff.md`——生成式快照头加 append-only 条目日志，单人、多人、agent、集群四种协作模式各有一套必填小节。
+
+扩展位（slots）机制则把"别的团队流程"插进来：`team-loop` 管团队循环、`workflow-runner` 管工作流扇出，各自带 README 协议和测试。源码库里还附了 orchestrator/planner/reviewer/confirmer 四个编排代理定义。
+
+## 四、安装：一个安装器，十余个宿主
+
+Spec Harness 是 Python 3.9+ 的标准库实现（PolyForm Noncommercial 许可），安装就三步：
+
+```bash
+git clone https://github.com/MicTx/spec-harness.git /tmp/spec-harness
+cd /tmp/spec-harness
+git checkout v0.22.2
+bash install.sh
+```
+
+安装器支持十余个宿主：Claude Code、Codex、Gemini CLI、Grok、OpenCode、OpenClaw、Hermes、Pi、ZCode、DeepSeek Harness、Devin、Cursor……不指定时自动探测已装的宿主。安装档位分 core / full：core 只装五个核心阶段命令加 Git 钩子；full 补齐全部 12 个阶段命令和 slots、agents 扩展组件。我们在 Pi 上用 `INSTALL_HOSTS=pi bash install.sh`，装完 `/spec` 系列命令直接可用。
+
+## 五、跑在一个真实博客上
+
+这个博客就是它的用户。归档目录里躺着从裸 clone 构建改造、移动端布局修复到 SEO 解封的一串任务包：blog-5f 一个包八个任务、三条车道（两条 mesh 终端加主线）并行，每个任务的 verify 都是能在命令行跑出退出码的断言，页面类任务统一挂 E2E——`E2E_BASE=http://127.0.0.1:18924 node tests/e2e.mjs`，34 项全过才算数。包与包接力，一天 19 个提交全绿落地。
+
+门禁也真的拦过烂账：一次一个全 manual、从未执行的任务包混进了 `.spec/specs/`，check 门禁直接判 blocked，连带拦下所有携带归档路径的提交——直到把它移出。门禁防的不只是烂尾，还有“看起来有规划”的空包。
+
+工具会迭代，但这套思路不会过期：**把"要干什么"写成合同，把"做完了"写成证据，把过程归档成日志。** 无论协作方是人还是 agent，这三件事都是长程工程的地基。
@@ -0,0 +1,90 @@
+# 关于页（后台「页面文案 → 关于页」可改）
+# ── 一级：blocks 块式正文（按顺序渲染，可拖拽排序；某块 enabled: false 即隐藏）
+# ── 二级：intro 多段 markdown（仅在 blocks 为空时使用）
+# ── 三级：内置默认文案（两者都空时兜底，构建永不炸）
+layout:
+  # 名片区（头像/名字/身份语/社交）开关：头像等数据事实源在「主页设置」
+  showIdCard: true
+
+blocks:
+  - type: prose
+    width: narrow
+    body:
+      zh: |
+        <span class="font-huiwen c-red">写作者</span> · 读者 · 快门按压者，拥抱开源。
+
+        这里是我三条轨道的公开工作台：**读过的书**留下评注，**写过的代码**进项目墙，**按下的快门**收入图库。
+
+        所有内容都有一个明确去处：
+
+        - 长文沉淀在文章与书架
+        - 短句与随手拍落在瞬间
+        - 影像收进图库，配一点 EXIF 与一句策展
+
+        本站本身即开源，构建与发布全链都在仓里。
+      en: |
+        <span class="font-huiwen c-red">Writer</span> · Reader · Shutter-presser, embracing open source.
+
+        This is the public workbench of my three tracks: **books** that left notes, **code** that reaches the project wall, and **shutters** I pressed that land in the gallery.
+
+        Everything has a clear destination:
+
+        - Long-form writing goes to posts and the bookshelf
+        - Short lines and snapshots land in moments
+        - Images go to the gallery, with a bit of EXIF and one line of curation
+
+        This site is itself open source — the full build and deploy pipeline lives in the repo.
+
+  - type: tracks
+    title:
+      zh: 兴趣版图
+      en: Interests
+    items:
+      - icon: book
+        name:
+          zh: 阅读
+          en: Reading
+        desc:
+          zh: 文学与戏剧为主，读到哪写到哪。
+          en: Mostly literature and drama; I write as I read.
+      - icon: terminal
+        name:
+          zh: 技术
+          en: Tech
+        desc:
+          zh: Linux、容器与自托管，把家里的小机器折腾成顺手的工具。
+          en: Linux, containers, and self-hosting — turning the little machines at home into handy tools.
+      - icon: camera
+        name:
+          zh: 摄影
+          en: Photography
+        desc:
+          zh: 街拍与山野，随身一台无反，在等光的间隙按快门。
+          en: Street and landscapes with a mirrorless camera, pressing the shutter while waiting for the light.
+
+  - type: prose
+    title:
+      zh: 本站如何构建
+      en: How this site is built
+    body:
+      zh: 页面由 Astro 静态生成，不含运行时框架 JS；内容住在自托管 gitea——本地编辑器与 gitea 网页写的是同一个 git 仓库，push 之后由 homelab 自动构建发布；评论走自托管 Artalk。页脚 built from 一行链到本次构建对应的 commit，构建过程透明可追溯。
+      en: Pages are statically generated by Astro with no runtime framework JS. Content lives on a self-hosted gitea — my local editor and the gitea web UI write to the same git repository, and each push is built and published automatically by the homelab. Comments run on self-hosted Artalk. The built-from line in the footer links to the commit behind this build, keeping the process transparent and traceable.
+
+# ---- 二级回退（blocks 为空时使用）----
+intro:
+  zh: |
+    写作者 · 读者 · 快门按压者，拥抱开源。
+
+    这里是我三条轨道的公开工作台：**读过的书**留下评注，**写过的代码**进项目墙，**按下的快门**收入图库。
+  en: |
+    Writer · Reader · Shutter-presser, embracing open source.
+
+    This is the public workbench of my three tracks: **books** that left notes, **code** that reaches the project wall, and **shutters** I pressed that land in the gallery.
+
+# 页面级排版覆盖（层 2）
+# 页面级排版覆盖（后台「关于页 → 页面排版覆盖」可改）：
+# 整页换字族会带来字体体积成本（如 font-huiwen 整页 ≈694KB），默认留空=全站默认排版
+# typography:
+#   font: font-huiwen   # 字族：font-serif/font-sans/font-kai/font-huiwen/font-kuaile…
+#   accent: c-red       # 强调色类：c-blue/c-red/…（外壳仍灰阶）
+#   scale: 1.05         # 字号缩放 0.8–1.25
@@ -0,0 +1,44 @@
+# 主页身份语（后台「页面文案 → 主页设置」可改）
+# 全部字段留空 = 现有形态（字段级回落默认值，零配置零变化）
+tagline:
+  zh: 写作者 · 读者 · 快门按压者，拥抱开源。
+  en: Writer · Reader · Shutter-presser — embracing open source.
+
+# 副标题（可选，markdown 短文本）：渲染在身份语下方，留空不渲染
+# subtitle:
+#   zh: '正在把**阅读、代码与影像**收进同一个工作台'
+#   en: 'Collecting **reading, code and images** into one workbench'
+
+# 头像（可选）：上传后自动写入 ./assets/avatar-xxx.jpg（走 Astro 图片管线）
+# 留空 = 回退内置渐变占位
+# avatar: ./assets/avatar.jpg
+
+# 站点图标（favicon，全局生效）：public 下的路径；留空回退 /favicon.svg
+# 上传走 public/icons/（后台媒体库），可填 /icons/my.ico、/icons/my.svg
+favicon: /favicon.svg
+
+# 社交链接（顺序即展示顺序，后台可增删拖动排序）
+# icon 取值：github / rss / email / bilibili / x / 留空（留空按 label 显示纯文字）
+socials:
+  - label: GitHub
+    url: https://github.com/wait4xx
+    icon: github
+  - label: RSS
+    url: /rss.xml
+    icon: rss
+  - label: 邮件
+    url: mailto:admin@wait4x.online
+    icon: email
+
+# 最新影像张数（1-6，默认 4；填 0 = 隐藏该区块）
+latestPhotos: 4
+
+# 首页每轨文章条数（4-8，默认 6）
+perTrackLimit: 6
+
+# 区块开关（默认全开；关掉的区块不渲染）
+sections:
+  tracks: true
+  photos: true
+  heatmap: true
+  projects: true
@@ -0,0 +1,22 @@
+blurb:
+  zh: 本站本身即开源：
+  en: 'This site is itself open source:'
+repo_url: https://git.wait4x.online/wait4x/blog
+repo_label: git.wait4x.online/wait4x/blog
+blurb_after:
+  zh: —— Astro SSG、双写作流、构建发布全链皆在仓中。以下是我在自托管 gitea 与 GitHub 上的全部公开仓库，以及最近一年的贡献活动。
+  en: — the Astro SSG, dual-writing workflow, and the full build & deploy pipeline live in the repo. Below are all my public repositories on self-hosted gitea and GitHub, plus contributions from the past year.
+
+# ---- 项目墙可见性与排序（后台「开源页」可改；留空/缺省 = 现状） ----
+# mode: all=全部（默认） | only=仅 include 列出 | exclude=排除 exclude 列出
+mode: all
+# 白名单（mode=only 时生效）
+include: []
+# 黑名单（mode=exclude 时生效）
+exclude: []
+# 排序：pinned-first=置顶优先（默认） | stars=星数降序 | updated=最近更新
+sort: pinned-first
+# 来源过滤：both=双源合并（默认） | github | gitea
+perSource: both
+# 开篇文案来源：off=用本文件 blurb（默认） | github-readme=构建期取 wait4xx/wait4xx 的 README 渲染
+intro_from: "off"
@@ -0,0 +1,37 @@
+# 主题旋钮（样式即数据 · 层 4）：只放白名单内的 9 组旋钮。
+# 红线：--measure（版心）与断点/纸墨/code 配色不在此列——它们牵动版面结构与分轨身份。
+# 全部留空 = 沿用 src/styles/tokens.css 的既有值（零配置零变化）。
+# 钳制与单调性在 src/lib/theme.ts 里做：越界值被夹取而非报错，构建不会因主题配置失败。
+
+# ① 强调色（明/暗两值；构建期闸门校验正文对比度 ≥4.5，不达标回落默认）
+accent_light: '#3454d1'
+accent_dark: '#8ea2ff'
+
+# ② 图片圆角（4–16；08 文档裁定上限 14）
+radius_img: 10
+
+# ③ 标题字号（22–32；必须 h1 > h2 > h3，否则整体回落默认）
+text_h1: 27
+text_h2: 22
+text_h3: 19
+
+# ④ 正文字号（16–22）
+prose_size_reading: 20
+prose_size_tech: 19
+
+# ⑤ 正文行高（1.5–2.0）
+leading_reading: 1.75
+leading_tech: 1.7
+
+# ⑥ 间距梯度（8–80；必须严格递增 3 < 4 < 5 < 6，否则回落默认）
+space_3: 16
+space_4: 24
+space_5: 40
+space_6: 64
+
+# ⑦ 段落流距（0–2em）
+flow_p: 0.9
+flow_h2_post: 0.6
+
+# ⑧ 过渡时长（150–600ms）
+dur: 350
@@ -0,0 +1,314 @@
+<!doctype html>
+<html lang="zh-CN">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>灯箱 v2.1 提案预览 · wait4x</title>
+<style>
+  /* ===== 灰阶基底（对齐站 tokens.css：四档灰 + 唯一曲线族） ===== */
+  :root{
+    --bg:#fff; --bg-soft:#f7f7f8; --ink-1:#111113; --ink-2:#33343a; --ink-3:#6b6e78;
+    --ink-4:#a0a3ad; --line:#e6e7eb; --radius-img:10px;
+    --mono:"JetBrains Mono",ui-monospace,Consolas,monospace;
+    --sans:"Noto Sans SC Variable","Noto Sans SC",system-ui,-apple-system,"PingFang SC",sans-serif;
+    --ez:cubic-bezier(.4,0,.22,1); /* PhotoSwipe 333ms 节奏同族曲线 */
+  }
+  *{box-sizing:border-box}
+  body{margin:0;background:var(--bg);color:var(--ink-2);font-family:var(--sans);}
+  body.locked{overflow:hidden}
+  .wrap{max-width:896px;margin:0 auto;padding:28px 20px 72px}
+  kbd{font-family:var(--mono);font-size:11.5px;border:1px solid var(--line);background:#fff;
+      border-radius:4px;padding:1px 6px;color:var(--ink-3)}
+
+  /* ===== 顶部说明：这是提案预览稿 ===== */
+  .note{background:var(--bg-soft);border:1px solid var(--line);border-radius:10px;
+        padding:14px 18px;font-size:13.5px;line-height:1.7;color:var(--ink-2);margin:18px 0 30px}
+  .note strong{color:var(--ink-1)}
+  .note ul{margin:6px 0 0;padding-left:18px}
+  .note li{margin:2px 0}
+  h1{font-size:27px;color:var(--ink-1);margin:8px 0 2px;font-weight:600}
+  .sub{font-family:var(--mono);font-size:12.5px;color:var(--ink-4)}
+
+  /* ===== 影像墙：cover 裁切（与线上一致，起飞动画的前提） ===== */
+  .stage{background:rgba(255,255,255,.04);border-radius:6px;padding:14px}
+  .wall{list-style:none;margin:0;padding:0;display:grid;grid-template-columns:repeat(3,1fr);
+        grid-auto-rows:8px;grid-auto-flow:dense;gap:14px}
+  .shot{position:relative;overflow:hidden;border-radius:var(--radius-img);grid-row-end:span var(--sp,13)}
+  .shot button{display:block;width:100%;height:100%;padding:0;border:none;background:none;cursor:zoom-in}
+  .shot img{display:block;width:100%;height:100%;object-fit:cover}
+  @media (max-width:820px){.wall{grid-template-columns:repeat(2,1fr)}}
+  @media (max-width:560px){.wall{grid-template-columns:1fr 1fr;gap:10px}}
+
+  /* ===== 灯箱：fixed 覆盖层（生产将等价几何搬回原生 <dialog>） ===== */
+  .lbx{position:fixed;inset:0;z-index:80}
+  .lbx[hidden]{display:none}
+  .lbx-bg{position:absolute;inset:0;background:rgba(8,10,14,.96);opacity:0;
+          transition:opacity 300ms var(--ez)}
+  .lbx.on .lbx-bg{opacity:1}
+  /* 双盒：win=裁切窗（动画 left/top/w/h），pic=内图（动画几何 + 缩放 transform） */
+  .lbx-win{position:fixed;overflow:hidden;border-radius:6px;transform-origin:0 0;
+           box-shadow:0 12px 48px rgba(0,0,0,.5);touch-action:none}
+  .lbx-pic{position:absolute;transform-origin:50% 50%;user-select:none;-webkit-user-drag:none;
+           transition:transform 90ms linear;cursor:zoom-in;display:block}
+  .lbx.landing .lbx-win,.lbx.landing .lbx-pic{
+    transition:left 300ms var(--ez),top 300ms var(--ez),width 300ms var(--ez),
+               height 300ms var(--ez),transform 300ms var(--ez),opacity 300ms var(--ez)}
+  .lbx-pic.zoomed{cursor:grab}.lbx-pic.grabbing{cursor:grabbing}
+  .lbx-pic.swap{opacity:0}
+
+  /* chrome 层 1：关闭/箭头/计数（+140ms 淡入） */
+  .c1{opacity:0;transition:opacity 220ms var(--ez)}
+  .lbx.on .c1{opacity:1;transition-delay:140ms}
+  .lbx-btn{position:fixed;width:44px;height:44px;border-radius:10px;cursor:pointer;
+    border:1px solid rgba(255,255,255,.22);background:rgba(20,24,30,.55);color:#e6e9ee;
+    backdrop-filter:blur(4px);box-shadow:0 2px 10px rgba(0,0,0,.35);display:grid;place-items:center}
+  .lbx-btn:hover{background:rgba(255,255,255,.12)}
+  .lbx-close{top:16px;right:16px}
+  .lbx-prev{left:14px;top:50%;translate:0 -50%}
+  .lbx-next{right:14px;top:50%;translate:0 -50%}
+  .lbx-count{position:fixed;top:26px;left:20px;font-family:var(--mono);font-size:12.5px;color:#98a2b3}
+
+  /* chrome 层 2：caption / title+EXIF / 动作（+300ms 淡入） */
+  .c2{opacity:0;transition:opacity 260ms var(--ez)}
+  .lbx.on .c2{opacity:1;transition-delay:300ms}
+  .lbx-meta{position:fixed;left:0;right:0;bottom:0;display:flex;flex-direction:column;align-items:center;
+    gap:3px;padding:14px 72px 20px;text-align:center;text-shadow:0 1px 4px rgba(0,0,0,.6)}
+  .lbx-caption{margin:0;font-family:var(--sans);font-size:13.5px;line-height:1.6;color:#dfe6f3;max-width:640px}
+  .lbx-row{display:flex;align-items:center;flex-wrap:wrap;justify-content:center;gap:14px;
+    font-family:var(--mono);font-size:12.5px}
+  .lbx-title{color:#fff;font-family:var(--sans);font-size:13px;font-weight:600}
+  .lbx-exif{color:#98a2b3}
+  .lbx-acts{display:inline-flex;gap:10px}
+  .lbx-act{display:inline-flex;align-items:center;gap:5px;padding:6px 11px;border-radius:10px;
+    border:1px solid rgba(255,255,255,.22);background:rgba(20,24,30,.55);color:#dfe6f3;
+    font-family:var(--mono);font-size:12px;text-decoration:none;backdrop-filter:blur(4px)}
+  .lbx-act:hover{background:rgba(40,48,60,.75);color:#fff}
+
+  /* 沉浸态：zoom>1 或按 i —— chrome 全隐，舞台纯净 */
+  .lbx.clean .c1,.lbx.clean .c2,.lbx.noui .c1,.lbx.noui .c2{opacity:0;transition-delay:0ms}
+
+  /* 首开提示 + 缩放指示 */
+  .lbx-hint{position:fixed;left:50%;bottom:128px;translate:-50% 0;padding:7px 13px;border-radius:10px;
+    border:1px solid rgba(255,255,255,.22);background:rgba(20,24,30,.55);backdrop-filter:blur(4px);
+    font-family:var(--mono);font-size:12px;color:#dfe6f3;opacity:0;transition:opacity 400ms var(--ez);
+    pointer-events:none}
+  .lbx-hint.show{opacity:1}
+  .lbx-zind{position:fixed;right:20px;bottom:128px;font-family:var(--mono);font-size:12px;color:#98a2b3;
+    opacity:0;transition:opacity 300ms var(--ez);pointer-events:none}
+  .lbx-zind.show{opacity:1}
+
+  @media (max-width:560px){
+    .lbx-prev{left:6px}.lbx-next{right:6px}
+    .lbx-meta{padding:12px 16px 16px}
+    .lbx-hint{bottom:150px}
+  }
+  @media (prefers-reduced-motion:reduce){
+    .lbx-bg,.c1,.c2,.lbx-pic,.lbx-win,.lbx-hint,.lbx-zind{transition:none!important}
+  }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <h1>图库 · 灯箱 v2.1 提案预览</h1>
+  <p class="sub">预览稿 —— 交互为提案演示（非线上行为）· 图片为 content/photos 实拍，EXIF 为示例数据</p>
+  <div class="note">
+    <strong>这是给浏览器直接打开的交互演示</strong>，对应《09-灯箱美化探索》提案 #1/#2/#3/#6/#7：
+    <ul>
+      <li><strong>原位起飞开合</strong>：点击缩略图，照片从原位放大入舞台；关闭回落原位（<kbd>Esc</kbd> / 背景点击 / 关闭钮）</li>
+      <li><strong>chrome 双层淡入</strong>：开箱后层 1（箭头/计数）先入、层 2（caption/EXIF）随入；<kbd>i</kbd> 隐藏全部；放大后自动隐层</li>
+      <li><strong>连拍导航</strong>：<kbd>←</kbd> <kbd>→</kbd> / 边缘箭头 / 触屏快滑；计数 n / N</li>
+      <li><strong>缩放</strong>：滚轮锚点缩放 1–4x、<kbd>双击</kbd> 1x↔2.5x、放大后拖拽、双指缩放；右下角缩放指示</li>
+    </ul>
+  </div>
+  <div class="stage"><ul class="wall" id="wall"></ul></div>
+</div>
+
+<!-- 灯箱：fixed 覆盖层（生产等价搬回原生 <dialog>，focus-trap 由 dialog 免费提供） -->
+<div class="lbx" id="lbx" hidden>
+  <div class="lbx-bg"></div>
+  <div class="lbx-win" id="win"><img class="lbx-pic" id="pic" alt=""></div>
+  <button class="lbx-btn lbx-close c1" id="bClose" aria-label="关闭（Esc）">
+    <svg viewBox="0 0 24 24" width="14" height="14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round"><path d="m5 5 14 14M19 5 5 19"/></svg></button>
+  <button class="lbx-btn lbx-prev c1" id="bPrev" aria-label="上一张（←）">
+    <svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m14.5 5.5-6.5 6.5 6.5 6.5"/></svg></button>
+  <button class="lbx-btn lbx-next c1" id="bNext" aria-label="下一张（→）">
+    <svg viewBox="0 0 24 24" width="15" height="15" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="m9.5 5.5 6.5 6.5-6.5 6.5"/></svg></button>
+  <div class="lbx-count c1" id="count">1 / 5</div>
+  <div class="lbx-meta c2">
+    <p class="lbx-caption" id="cap"></p>
+    <div class="lbx-row"><strong class="lbx-title" id="ttl"></strong><span class="lbx-exif" id="exif"></span>
+      <span class="lbx-acts"><a class="lbx-act" id="aOrig" href="#" target="_blank" rel="noopener">原图 ↗</a><a class="lbx-act" id="aDl" href="#" download>下载 ↓</a></span></div>
+  </div>
+  <div class="lbx-hint" id="hint">滚轮缩放 · 双击放大 · Esc 关闭 · i 隐藏界面</div>
+  <div class="lbx-zind" id="zind">100%</div>
+</div>
+
+<script>
+/* ===== 数据：仓内实拍（含 2.36:1 长横幅与 2:3 竖图两种 letterbox 形态） ===== */
+const PHOTOS=[
+ {src:'../content/photos/1766156983093.jpg',w:2400,h:1600,sp:13,title:'防波堤暮色',
+  cap:'落日把海与城一齐烫成金箔，海鸟的剪影恰好掠过日轮',exif:'X-T5 · XF35mmF1.4 · f/5.6 · 1/500s · ISO 200'},
+ {src:'../content/photos/mmexport1771816382115.jpg',w:2400,h:1018,sp:6,title:'长滩低云',
+  cap:'涨潮前的长滩，云层压得很低',exif:'X100VI · f/8 · 1/1000s · ISO 160'},
+ {src:'../content/photos/1766156998344.jpg',w:1600,h:2400,sp:20,title:'旗与塔',
+  cap:'旗在风里翻卷，塔身亮得像一支随时点火的火箭',exif:'GR III · f/2.8 · 1/250s · ISO 400'},
+ {src:'../content/photos/1766157004116.jpg',w:2400,h:1536,sp:9,title:'暮色撤离',
+  cap:'灯柱次第亮起，暮色像退潮一样撤离',exif:'X-T5 · XF56mmF1.2 · f/1.4 · 1/120s · ISO 800'},
+ {src:'../content/photos/mmexport1776564092433.jpg',w:2400,h:1600,sp:13,title:'夜航',
+  cap:'货轮的灯在雾里连成一条迟疑的线',exif:'X-T5 · XF70-300mm · f/4 · 1/60s · ISO 1250'}];
+const N=PHOTOS.length;
+
+const $=id=>document.getElementById(id);
+const lbx=$('lbx'),win=$('win'),pic=$('pic'),wall=$('wall');
+const reduced=matchMedia('(prefers-reduced-motion: reduce)').matches;
+let idx=0,open_=false,hintShown=false;
+let zoom={s:1,tx:0,ty:0};
+
+/* ===== 影像墙 ===== */
+PHOTOS.forEach((p,i)=>{
+  const li=document.createElement('li');
+  li.className='shot'; li.style.setProperty('--sp',p.sp);
+  const b=document.createElement('button'); b.type='button'; b.setAttribute('aria-label',p.title);
+  b.dataset.i=i;
+  const im=document.createElement('img'); im.src=p.src; im.alt=p.title; im.loading=i<3?'eager':'lazy';
+  b.appendChild(im); li.appendChild(b); wall.appendChild(li);
+  b.addEventListener('click',()=>openLbx(i));
+});
+const thumbImg=i=>wall.querySelector(`button[data-i="${i}"] img`);
+
+/* ===== 几何：舞台 fit 矩形 / cover-contain 双盒（PhotoSwipe data-cropped 路线） ===== */
+function stageBox(){const W=innerWidth,H=innerHeight;
+  const side=W>760?56:12,top=64,bot=innerWidth>560?124:150;
+  return{x:side,y:top,w:W-side*2,h:H-top-bot};}
+function fitRect(p,box){const r=p.w/p.h,br=box.w/box.h;let w,h;
+  if(r>br){w=box.w;h=w/r;}else{h=box.h;w=h*r;}
+  return{x:box.x+(box.w-w)/2,y:box.y+(box.h-h)/2,w,h};}
+function coverIn(p,winR){const r=p.w/p.h,wr=winR.w/winR.h;let w,h;
+  if(wr>r){h=winR.h;w=h*r;}else{w=winR.w;h=w/r;}
+  return{x:(winR.w-w)/2,y:(winR.h-h)/2,w,h};} /* 相对 win 的坐标 */
+const setBox=(el,g)=>{el.style.left=g.x+'px';el.style.top=g.y+'px';
+  el.style.width=g.w+'px';el.style.height=g.h+'px';};
+
+/* ===== 开箱：从缩略图原位起飞 ===== */
+function fillMeta(p){$('cap').textContent=p.cap;$('ttl').textContent=p.title;
+  $('exif').textContent=p.exif;$('count').textContent=`${idx+1} / ${N}`;
+  $('aOrig').href=p.src;$('aDl').href=p.src;$('aDl').setAttribute('download',p.title+'.jpg');}
+function openLbx(i){
+  idx=i;const p=PHOTOS[idx];pic.src=p.src;pic.alt=p.title;fillMeta(p);
+  const t=thumbImg(i).getBoundingClientRect();
+  const tr=fitRect(p,stageBox());
+  zoom={s:1,tx:0,ty:0};pic.style.transform='none';pic.classList.remove('zoomed','grabbing','swap');
+  lbx.hidden=false;open_=true;document.body.classList.add('locked');
+  lbx.classList.add('landing');
+  setBox(win,t);setBox(pic,coverIn(p,t));       /* 起点：与缩略图逐像素同框（cover 裁切） */
+  if(reduced){lbx.classList.add('on');lbx.classList.remove('landing');setBox(win,tr);setBox(pic,{x:0,y:0,w:tr.w,h:tr.h});}
+  else{
+    void win.offsetWidth;                        /* 强制 reflow，起点先落定 */
+    lbx.classList.add('on');
+    setBox(win,tr);setBox(pic,{x:0,y:0,w:tr.w,h:tr.h}); /* 终点：舞台 contain */
+    setTimeout(()=>lbx.classList.remove('landing'),330);
+  }
+  if(!hintShown){hintShown=true;const h=$('hint');h.classList.add('show');
+    setTimeout(()=>h.classList.remove('show'),2600);}
+}
+
+/* ===== 关闭：回落到缩略图原位 ===== */
+function closeLbx(){
+  if(!open_)return;
+  const p=PHOTOS[idx],t=thumbImg(idx)?.getBoundingClientRect();
+  instantResetZoom();
+  if(reduced||!t){lbx.hidden=true;lbx.classList.remove('on','clean','noui');open_=false;
+    document.body.classList.remove('locked');return;}
+  lbx.classList.add('landing');
+  setBox(win,t);setBox(pic,coverIn(p,t));
+  lbx.classList.remove('on','clean','noui');
+  setTimeout(()=>{lbx.hidden=true;lbx.classList.remove('landing');open_=false;
+    document.body.classList.remove('locked');},320);
+}
+
+/* ===== 换片：旧图淡出、新图自侧向 10% 淡入（spacing 节奏） ===== */
+function show(i,dir){
+  idx=((i%N)+N)%N;const p=PHOTOS[idx];instantResetZoom();fillMeta(p);
+  pic.src=p.src;pic.alt=p.title;
+  const tr=fitRect(p,stageBox());setBox(win,tr);setBox(pic,{x:0,y:0,w:tr.w,h:tr.h});
+  if(!reduced){pic.classList.add('swap');
+    pic.style.transform=`translateX(${dir*-10}%)`;
+    void pic.offsetWidth;pic.classList.remove('swap');
+    pic.style.transform='none';}
+}
+
+/* ===== 缩放：滚轮锚点 / 双击 / 双指 / 拖拽（复用线上 v2 数学） ===== */
+function clampPan(){const mx=Math.max(0,pic.clientWidth*(zoom.s-1)/2),
+  my=Math.max(0,pic.clientHeight*(zoom.s-1)/2);
+  zoom.tx=Math.min(mx,Math.max(-mx,zoom.tx));zoom.ty=Math.min(my,Math.max(-my,zoom.ty));}
+function applyZoom(){clampPan();
+  pic.style.transform=zoom.s===1?'none':`translate(${zoom.tx}px,${zoom.ty}px) scale(${zoom.s})`;
+  pic.classList.toggle('zoomed',zoom.s!==1);
+  lbx.classList.toggle('clean',zoom.s!==1);}
+function instantResetZoom(){const keep=pic.style.transition;pic.style.transition='none';
+  zoom={s:1,tx:0,ty:0};pic.style.transform='none';pic.classList.remove('zoomed');
+  lbx.classList.remove('clean');void pic.offsetWidth;pic.style.transition=keep||'';}
+function zoomAt(next,cx,cy){const r=pic.getBoundingClientRect();
+  const ax=cx-r.left-r.width/2-zoom.tx,ay=cy-r.top-r.height/2-zoom.ty;
+  if(next<=1){zoom={s:1,tx:0,ty:0};applyZoom();zindShow();return;}const k=next/zoom.s;zoom.tx-=ax*(k-1);zoom.ty-=ay*(k-1);zoom.s=next;applyZoom();zindShow();}
+let zt;function zindShow(){const z=$('zind');z.textContent=Math.round(zoom.s*100)+'%';
+  z.classList.add('show');clearTimeout(zt);zt=setTimeout(()=>z.classList.remove('show'),900);}
+lbx.addEventListener('wheel',e=>{if(!open_)return;e.preventDefault();
+  const f=Math.exp(-e.deltaY*0.0015);
+  const next=Math.min(4,Math.max(1,zoom.s*f));
+  if(next!==zoom.s)zoomAt(next,e.clientX,e.clientY);},{passive:false});
+win.addEventListener('dblclick',e=>{if(zoom.s===1)zoomAt(2.5,e.clientX,e.clientY);
+  else instantResetZoom();}); /* 挂 win：放大态 setPointerCapture 会把 click 派发给 win，pic 收不到 */
+
+/* 拖拽平移（放大态）+ 双指缩放：pointer 事件统一 */
+const pts=new Map();let drag=null,pinch=null;
+win.addEventListener('pointerdown',e=>{
+  pts.set(e.pointerId,{x:e.clientX,y:e.clientY});
+  if(pts.size===2){const a=[...pts.values()];
+    pinch={d0:Math.hypot(a[0].x-a[1].x,a[0].y-a[1].y),s0:zoom.s,
+      mx:(a[0].x+a[1].x)/2,my:(a[0].y+a[1].y)/2};drag=null;return;}
+  if(zoom.s>1){win.setPointerCapture(e.pointerId);
+    drag={x:e.clientX,y:e.clientY,tx:zoom.tx,ty:zoom.ty};pic.classList.add('grabbing');}
+});
+win.addEventListener('pointermove',e=>{
+  if(pts.has(e.pointerId))pts.set(e.pointerId,{x:e.clientX,y:e.clientY});
+  if(pinch&&pts.size===2){const a=[...pts.values()];
+    const d=Math.hypot(a[0].x-a[1].x,a[0].y-a[1].y);
+    const next=Math.min(4,Math.max(1,pinch.s0*d/pinch.d0));
+    if(next!==zoom.s)zoomAt(next,pinch.mx,pinch.my);return;}
+  if(drag){zoom.tx=drag.tx+e.clientX-drag.x;zoom.ty=drag.ty+e.clientY-drag.y;applyZoom();}
+});
+const endPt=e=>{pts.delete(e.pointerId);if(pts.size<2)pinch=null;
+  if(drag){drag=null;pic.classList.remove('grabbing');}};
+win.addEventListener('pointerup',endPt);win.addEventListener('pointercancel',endPt);
+
+/* 触屏快滑翻页（zoom=1 时） */
+let x0=null;lbx.addEventListener('touchstart',e=>{x0=e.touches[0].clientX;},{passive:true});
+lbx.addEventListener('touchend',e=>{if(x0===null||zoom.s!==1){x0=null;return;}
+  const dx=e.changedTouches[0].clientX-x0;
+  if(Math.abs(dx)>40)show(idx+(dx<0?1:-1),dx<0?1:-1);x0=null;},{passive:true});
+
+/* ===== 键盘 / 背景点击 / chrome 召唤 ===== */
+document.addEventListener('keydown',e=>{
+  if(!open_)return;
+  if(e.key==='Escape')closeLbx();
+  else if(e.key==='ArrowLeft')show(idx-1,-1);
+  else if(e.key==='ArrowRight')show(idx+1,1);
+  else if(e.key==='i'||e.key==='I')lbx.classList.toggle('noui');
+});
+lbx.addEventListener('click',e=>{
+  if(e.target.closest('.lbx-win')||e.target.closest('.lbx-btn')||
+     e.target.closest('.lbx-meta')||e.target.closest('a'))return;
+  closeLbx(); /* 背景点击关闭（bgClickAction:'close' 同款） */
+});
+$('bClose').addEventListener('click',closeLbx);
+$('bPrev').addEventListener('click',()=>show(idx-1,-1));
+$('bNext').addEventListener('click',()=>show(idx+1,1));
+
+/* 开箱中窗口变化：舞台即时重排（不做动画，避免与缩放打架） */
+addEventListener('resize',()=>{if(!open_||lbx.classList.contains('landing'))return;
+  const p=PHOTOS[idx];const tr=fitRect(p,stageBox());
+  setBox(win,tr);setBox(pic,{x:0,y:0,w:tr.w,h:tr.h});});
+</script>
+</body>
+</html>
@@ -0,0 +1,119 @@
+# 灯箱美化探索：图片查看体验天花板五站研究（v2.1 输入）
+
+> 只读调研 + 提案，不动代码。基线 = 灯箱 v2 车道（fit-contain / 滚轮锚点缩放 0.5–5x / 拖拽平移 /
+> 双击 1x↔2.5x / caption+EXIF 分层 / ←→ 与触摸快滑），提案全部**叠加在 v2 之上，不推翻缩放引擎**。
+> 配套可交互演示：`design/lightbox-mockup.html`（浏览器直接打开，交互为提案演示）。
+> 标记：✅ = 静态抓取并核对源码/文档；◐ = 站点可达但查看器 JS 渲染，基于已知稳定形态记录。
+
+## 一、五站笔记
+
+### 1. PhotoSwipe（photoswipe.com）✅ 业界标杆 lightbox
+
+- **A 开合过渡**：`showHideAnimationType: zoom`（默认）= 从缩略图原位起飞到舞台、关闭回落原位；
+  无缩略图时降级 fade；`prefers-reduced-motion` 自动 none。时长 333ms ×3（show/hide/zoom 同拍），
+  曲线 `cubic-bezier(.4,0,.22,1)`，双击缩放共用同曲线（节奏统一的关键）。
+  **cover 裁切缩略图路线**：`object-fit:cover` + `data-cropped` —— 我们的 masonry 正是这种缩略图。
+- **B 舞台纯净度**：底色实色 + `bgOpacity`（默认 .8，透明度走 JS 合成不走 rgba，性能纪律）；
+  文档明示**禁止 backdrop blur**（重性能坑）。`tapAction:'toggle-controls'`：单击即隐全部 chrome，纯看图。
+- **C 信息层**：核心无 caption（a11y 原因删出 v5），官方 dynamic-caption 插件——"依剩余空放置于
+  图下或图侧"：竖图自动把 caption 挪进侧边 letterbox，横图回底部。计数器 `n / N` 极简。
+- **D 导航**：边缘箭头 + loop + `arrowKeys`；幻灯片间距 `spacing:.1`（10% 视口，换片有"路过"感）；
+  `allowPanToNext`：放大态继续滑 = 翻页（先耗尽平移余量再走片）。
+- **E 微交互**：`preload:[1,2]` 相邻预载；`preloaderDelay:2000`——加载指示 2s 后才出现（快图不打扰）；
+  `maxWidthToAnimate:4000` 超宽图不做起飞动画（防掉帧）。图标自带描边阴影，深浅底通吃。
+- **F 移动端**：`pinchToClose`（捏合关闭）、`closeOnVerticalDrag`（竖拖关闭）、双指缩放到 max 档；
+  `trapFocus + returnFocus`（焦点圈与归还，原生 `<dialog>` 免费同款）。
+
+### 2. medium-zoom（francoischalifour.com）✅ Medium 的克制哲学
+
+- **A**：点击 = 从缩略图位置 FLIP 放大到视口居中（margin 默认 0 贴边），关闭回落原位。
+  与 PhotoSwipe 同为"原位起飞"，但它只有这一种动画——整库只做一件事。
+- **B**：默认底色 `#fff`（Medium 白，页面即舞台）；无任何 chrome、无 caption、无导航。
+  **克制到"查看器不存在"**：这就是它的设计立场。
+- **C**：零信息层；`template` 选项可注入自定义布局（Facebook / Dropbox Paper 官方范例）——
+  证明"纯放大内核 + 自定义信息壳"是可行分层。
+- **D**：无连拍导航（单图语义）；`scrollOffset:40`：**滚动页面即关闭**，把"关"交给最顺手的手势。
+- **E**：HD 模式 `data-zoom-src`：页内小图、开箱瞬间换高清（同宽高比前提），预览零等待。
+- **F**：移动端点按开/点按关，无多余手势；无缩放（一档即满）。
+
+### 3. Unsplash 照片页 ◐（curl 被 bot 墙拦截，未逐项复核）
+
+- **A**：列表→详情是页面跳转非灯箱；大图页首屏即图主体，顶部细导航浮层滚动隐现。
+- **B**：图外留白极小，信息全靠**悬浮层**：右侧竖排操作列（下载/尺寸选择/点赞/加合集/ⓘ），
+  不占图也不占底。
+- **C**：ⓘ 召唤 Info 面板：相机/镜头/光圈/快门/ISO/焦距/发布时间/浏览数全量 EXIF；
+  平时全隐——"轻常驻 + 重召唤"的范本。下载默认给适配尺寸，原图藏在尺寸菜单。
+- **D**：集合/相册内 ←→ 键连续浏览；相关照片网格殿后（发现回路）。
+- **E**：渐进加载 + blur-up 占位是全站基建；L 键点赞的快捷键 affordance。
+- **F**：移动端操作列收进底部栏，Info 面板变全屏抽屉。
+
+### 4. 图虫 ◐（主站可达，查看器 JS 渲染未复核）
+
+- **A**：信息流点击 → 全屏查看器直开（社区产品重内容直达，弱化过渡本身）。
+- **B**：舞台全黑，chrome 依赖手势（边缘滑动）而非常驻按钮。
+- **C**：摄影师视角分层：caption/描述 + **醒目完整 EXIF（机身/镜头/参数条）** + 作者卡（头像/
+  关注）+ 标签 + 社区数据（赞/藏）——信息密度最高，但靠 JS 分层收纳（常驻只留作者卡）。
+- **D**：同组连拍左右滑 + 组内缩略导航；键盘支持弱于 PhotoSwipe/Flickr。
+- **E**：加载有占位图（信息流即高清小图，开箱升级）。
+- **F**：App 化手势（快滑翻页带跟手位移）；双指缩放齐全。
+- 教训面：信息全堆常驻会让暗房变"仪表盘"——我们只取它的 **EXIF 完整度**，不取密度。
+
+### 5. Flickr（自选）✅ SSR 复核 + ◐ 视觉层
+
+- **A**：照片 URL **直接开进 lightbox**（无中间页）：暗房全屏沉浸，从网格进入有原位起飞感。
+- **B**：舞台近纯黑（#212121 系）；chrome 默认轻常驻：底部左侧 title/作者小卡（可隐），
+  其余全靠召唤。
+- **C**：三段式：常驻小卡（title+作者）→ 右缘动作列（收藏/加画册/分享/下载尺寸/ⓘ）→
+  ⓘ 滑出右侧 EXIF 全量面板（机身/镜头/参数/软件/日期）。20 年沉淀的"常驻最轻、重的全召唤"。
+- **D**：边缘 hover 箭头 + ←→/Esc/f/i 全键盘；f=收藏的键位文化。
+- **E**：大图渐进加载；浏览数/评论在下折区（不抢舞台）。
+- **F**：移动端 swipe 翻页、双指缩放、上滑收 chrome——三手势覆盖 95% 操作。
+- 选它的理由：唯一同时满足"成熟产品 + SSR 可复核 + 键盘流 + 信息分层范本"。
+
+## 二、差距矩阵（现状 v2 vs 天花板）
+
+| 维度 | 我们现状（v2） | 天花板做法（出处） | 差距 |
+|---|---|---|---|
+| A 开合 | dialog 直开直关，零过渡 | 原位起飞+回落 333ms 单曲线（PS/MZ） | **大** |
+| B 舞台 | backdrop .95 常驻；meta 恒占底条 | toggle-controls 沉浸（PS）；轻常驻重召唤 | 中 |
+| C 信息层 | 一层底条：caption+title+EXIF+动作平铺 | 双层：常驻轻卡 + 召唤 EXIF（FL/US）；caption 就空放置（PS 插件） | 中 |
+| D 导航 | ←→ 键/两侧钮/触摸滑动/loop ✅ | 同款 + spacing 换片节奏 + 放大态滑透翻页（PS） | 小 |
+| E 微交互 | 切图 160ms 淡入；光标三态 ✅ | 相邻预载 [1,2]、2s 延迟加载指示、缩放档位语义（PS）；HD 交换（MZ） | 中 |
+| F 移动端 | 快滑翻页 + 双击缩放；**无双指缩放** | pinch 缩放/捏合关/竖拖关（PS）三件套 | **大** |
+
+## 三、v2.1 增强提案（叠加式，不动 v2 引擎）
+
+| # | 提案 | 做法 | 灰阶适配 | 工作量 | 优先级 |
+|---|---|---|---|---|---|
+| 1 | **原位起飞开合** | 点击缩略图：FLIP 动画双盒（外盒=裁切窗从缩略图矩形→舞台矩形，内图=cover 几何→contain 几何同步过渡，等价 PS `data-cropped` 路线）；300ms `cubic-bezier(.4,0,.22,1)`（与站 `--ease` 同族）；关闭回落到当前缩略图位置；reduced-motion 直开直关 | 起飞的是图不是 chrome；backdrop 照旧恒深 | 0.5–1 天 | **P0** |
+| 2 | **背景点击关闭** | 点击落在图外区域即关（PS `bgClickAction:'close'` 同款），Esc 保留 | 无新增视觉 | 0.5h | **P0** |
+| 3 | **chrome 双层淡入 + 召唤** | 开箱：层1（关闭/箭头/计数）+140ms、层2（caption/EXIF/动作）+300ms 淡入；`i` 键或图上单击 toggle 全隐（toggle-controls）；zoom>1 自动隐、回 1x 淡回 | 淡入只有 opacity，无位移无色彩 | 0.5 天 | P1 |
+| 4 | **相邻预载** | 开箱后 idle 预载 ±1 张 fullSrc（PS `preload` 精神，我们取 [1,1] 克制档） | 纯网络层 | 数行 | P1 |
+| 5 | **双指缩放（移动端）** | pointer events 双指距离比→锚点缩放（复用 v2 `zoomAt` 数学）；v2 已有 `touch-action:none` 地基 | 同 v2 | 0.5 天 | P1 |
+| 6 | **换片过渡** | 切片：旧图 140ms 淡出、新图自侧向 10% 位移淡入（PS `spacing:.1` 节奏）；v2 换图已回正缩放，天然兼容 | 仅 opacity/transform | 0.5 天 | P2 |
+| 7 | **缩放指示 + 首开提示** | 缩放停稳后右下 90% 淡入 `168%` 900ms 淡出；首开箱 hint 胶囊"滚轮缩放 · 双击放大 · Esc 关闭"2.6s 自隐 | mono 小字，与 EXIF 同语言 | 数行 | P2 |
+| 8 | **长图侧置 meta** | 竖图（ratio<0.9）且视口 ≥820px：caption+EXIF 移入侧 letterbox（PS dynamic-caption"就空放置"）；横图维持底部条 | 文字色不变，只挪位 | 0.5–1 天 | P2 |
+| 9 | **HD 交换** | zoom>1.5x 懒换 `/photos-originals/` 原图，<1.5x 回 1440（MZ `data-zoom-src` 模式）；404 兜底留 1440 | 纯数据层 | 0.5 天 | P2 |
+| 10 | **移动竖拖关闭** | zoom=1 时竖向拖 >80px 关闭并回落缩略图（PS `closeOnVerticalDrag`） | 同关闭回落 | 0.5 天 | P2 |
+
+落地注：生产保持原生 `<dialog>`（免费 focus-trap/returnFocus，PS 同款能力）；起飞动画在 dialog 内
+用 fixed 双盒实现，mockup 用 fixed 覆盖层纯为演示等价几何。
+
+## 四、明确不做清单（与灰阶克制冲突）
+
+- 粒子/彩光/视差/自动播放/轮播——舞台只属于照片
+- backdrop blur——PhotoSwipe 文档明示重性能坑，且暗底已够沉浸
+- 缩略图条（thumbstrip）——21 张规模用不上，常驻 chrome +1 与克制冲突（>50 张再议）
+- 社交分享按钮——PS v5 自己都删了；博客无此回路
+- tile deep-zoom / 万像素级缩放——仓内照片 2400px 封顶，用不到
+- 全屏按钮——PS v5 已删（浏览器 F11 更顺）；Esc + 沉浸足够
+- 音效、进度条、弹跳物理回弹——动效纪律：全站唯一曲线
+- chrome 染 accent 色——灯箱恒深恒灰，强调色止于站内链接
+
+## 五、验证记录
+
+- PhotoSwipe：photoswipe.com 七页 + unpkg v5.4.4 `photoswipe.esm.js` defaultOptions 源码核对（✅）
+- medium-zoom：francoischalifour.com options/HD 指南 + GitHub README（✅）
+- Unsplash：curl 被 bot 检测墙拦截，标记 ◐；图虫：详情页 JS 渲染不可静态复核，标记 ◐
+- Flickr：照片页 SSR 抓取成功（photo-model/person-model JSON 在源码中），视觉层标 ◐
+- mockup：单文件无依赖；图片引用 `../content/photos/` 仓内实拍（相对路径，需与仓库同置打开）
@@ -0,0 +1,394 @@
+# 页面后台化方案：内容 / 布局 / 样式的可编辑边界
+
+> 调研 + 提案，不改代码。基线 = 工作树 2026-11-02（含在途未提交改动）。
+> 口径：所有结论落到本仓文件/字段；"能编辑什么"和"不能编辑什么"同等重要。
+> **在途关系**：工作树里另有一条未提交车道（`git diff --stat`：home.yaml / opensource.yaml / projects.ts / site-content.ts / content.config.ts / ProjectWall.astro / index.astro / en-index / tokens.css / global.css，共 306 增）已落地「首页区块开关 + 开源页可见性 + README 开篇」。本文把它当**既有事实**评估，只补缺口与验收，不重复设计。
+
+---
+
+## 0. 现状盘点（文件级锚点）
+
+| 关注点 | 现有实现 | 位置 |
+|---|---|---|
+| 集合/单例 schema | `siteHome` / `siteAbout` / `siteOpenSource` 三个 `glob(pattern 精确到单文件)` 单例 | `src/content.config.ts:78,114,119` |
+| 后台字段 | `site_pages` 一集合三 files，字段与 schema 一一对应 | `public/admin/config.yml:110-260` |
+| 文案访问层（含字段级回落） | `pick()/pickBi()` + `SITE_DEFAULTS` 逐字对齐历史文案 | `src/lib/site-content.ts:18-62` |
+| markdown 渲染 | `createMarkdownProcessor()` **无参**（关键，见 §7） | `src/lib/site-content.ts:122-127` |
+| 关于页结构 | h1 → intro(markdown) → `IdCard` → tracks(3 条硬编码) → build 段 | `src/components/pages/AboutPage.astro:1-70` |
+| 关于页可变文案 | tracks/build 段全部来自 `t()` 字典（**非后台可改**） | `src/i18n/ui.ts:73-84` |
+| 首页 | 结构化区块：IdCard/PostList/最新影像/Heatmap/ProjectWall/心跳 | `src/pages/index.astro`（zh/en 两份重复） |
+| 开源页 | blurb + Heatmap + ProjectWall(limit 99) | `src/pages/opensource.astro` |
+| 项目数据 | 构建期双源 fetch + 去重 + 过滤/排序 + 仓内 fallback JSON（现仅 1 条 `blog`） | `src/lib/projects.ts:24-134`、`src/data/projects-fallback.json` |
+| README 开篇 | `GET /repos/wait4xx/wait4xx/readme`（Accept raw）+ `content/.github-readme.md` 缓存 | `src/lib/site-content.ts:204-256` |
+| markdown 净化 | 仅文章管线挂了白名单（class/style/on*） | `astro.config.mjs:28`、`src/lib/rehype-class-whitelist.ts` |
+| 设计 tokens | 全部 CSS 变量，明暗双套 | `src/styles/tokens.css`（124 行，含 dark 覆盖） |
+
+**结论**：后台能力当前是「**平铺标量字段**」形态——能改文案与几个开关，不能改**结构、顺序、字段种类**。关于页的骨架（tracks/build 两段）完全在代码与 i18n 字典里，这正是用户"整页可编辑"诉求的断点。
+
+---
+
+## 1. 需求拆解（可验收能力清单）
+
+| 编号 | 能力 | 现状 | 缺口 |
+|---|---|---|---|
+| C1 | 关于页**所有文案**可改（含 tracks/build 段） | intro 可改，其余在 `ui.ts` | 全部结构化区块未入 CMS |
+| C2 | 关于页**结构可改**（增删段、调顺序、开关名片区） | 硬编码 | 无块模型 |
+| C3 | 首页区块开关 / 条数 / 副标题 | 在途已实现（`sections.*`、`perTrackLimit`、`latestPhotos`、`subtitle`） | 缺"展示策略"类字段（见 §6） |
+| C4 | 开源页"展示哪些项目" | 在途已实现（`mode/include/exclude/sort/perSource`） | 语义定稿 + 断言 + 现有 6 条截断副作用（见 §4） |
+| C5 | 开源页开篇 = GitHub profile README | 在途已实现（`intro_from: github-readme`） | 缓存位置被 `git clean` 抹掉（见 §4.4） |
+| C6 | **样式**可调（字体/字号/间距/灰阶/圆角） | 全在 `tokens.css` | 无数据层 |
+| C7 | 双语 en 轨保真 | 字段级 `{zh,en}` + 回落 | 块模型需延续同规矩 |
+| C8 | 构建期零运行时 + SEO/灰阶不回归 | 现状成立 | 需把"不回归"写成断言 |
+
+---
+
+## 2. 五方案对比
+
+| | A 结构化单例字段扩展 | B 块构建器 | C 富文本整页 | D 样式即数据 | E 混合（推荐） |
+|---|---|---|---|---|---|
+| 能力上限 | 低：只能改预定义字段的值 | 高：增删/排序/差异化结构 | 最高：任意内容 | 中：只动感官参数 | 高（结构）+ 中（局部自由） |
+| 破版风险 | 极低 | 低（渲染器受控） | **高**：作者可写出非设计语言结构 | 中（对比度/尺度） | 低-中 |
+| XSS 面 | 0（无 HTML） | 小（组件渲染，URL/图片字段受控） | **大**：`set:html` 直通 | 0 | 小（唯一自由区走净化管线） |
+| 编辑体验 | 顺手但僵硬；20 字段后 config.yml 成清单墙 | 顺手（新增时选块型、拖拽排序） | 最自由但无护栏 | 顺手（几个 color/number） | 顺手（块为主，自由区为辅） |
+| 工作量 | 0.5d/页 | 3-4d（渲染器 + 9 类块 + 后台 types） | 0.5d（已有 intro 通道）但治不住质量 | 1d | 4-5d（含 B+D+净化） |
+| 维护成本 | 每加一项改两处（yml+schema） | 每加块型改三处（yml+schema+组件），但**互不干扰** | 内容问题无代码兜底，靠人审 | 用户改坏颜色需回滚 git | 同 B，另加 token 白名单 |
+| 对我们仓的结论 | **只适合开关/条数**（首页现状即其上限形态），**不作为关于页主路线** | 关于页主力 | **不作为主路线**（灰阶/双语/SEO 三条红线都靠人守） | 采纳为**独立一层**（受限白名单） | **采纳** |
+
+补充结论（逐条）：
+- **A 的极限量化**：`public/admin/config.yml` 现已 260 行、覆盖 4 集合。关于页若走 A（名片/技能卡/时间线各 4-6 字段），预估 +60 行 yml、+40 行 schema、+30 行组件分支；且"某段删掉"只能靠 `enabled: false` 假装，顺序固定。→ 只保留给首页（首页是聚合页，区块种类稳定）。
+- **B 的关键前提**：Sveltia 0.252 支持 **`list` 的 `types` + `typeKey`**（异构块），证据见 §3.4；无此能力则 B 退化成"同构对象列表"（每块字段全冗）。
+- **C 的现实定位**：`about.yaml` 已有 markdown 整块通道（`intro`），可立刻扩成"多段 markdown 长文"。问题：长文无法表达 tracks 卡片（图标+双行）、无法控制段间节奏，且 raw HTML 通道当前**未净化**（§7.1）——直接放开等于开洞。
+- **D 的边界**：可调项必须白名单化（约 12 个），不是整份 tokens.css；`--measure`（9 处引用）、`--accent`（38 处）属高放大倍率旋钮，见 §3.6。
+
+---
+
+## 3. 推荐方案 E：结构与落点
+
+### 3.1 四层数据分层
+
+| 层 | 载体 | 谁能改 | 例子 |
+|---|---|---|---|
+| L1 页面骨架 | `content/site/*.yaml` 的 `blocks: []` | 后台（增删排序） | 关于页整页 |
+| L2 区块字段 | 每块 `type` 决定字段集（zod discriminatedUnion） | 后台 | prose / tracks / cards / timeline / quote / figure / linklist / cta / divider |
+| L3 局部自由区 | `prose` / `richtext` 块内的 markdown（受白名单类 + tag 白名单） | 后台 | 一段带列表的说明 |
+| L4 感官参数 | `content/site/theme.yaml` → 构建期生成 CSS 变量 | 后台（白名单旋钮） | 正文字号、圆角、强调色 |
+
+### 3.2 yaml 结构总览（一眼看全）
+
+```
+content/site/
+├── home.yaml          # 已有：tagline/avatar/favicon/socials/subtitle/latestPhotos/perTrackLimit/sections/*
+│                      # 新增：heroStyle / projectsLimit / photosSource / postsTracks / announcement(markdown)
+├── about.yaml         # 已有：intro{zh,en}（保留为兼容字段，见 §5.5）
+│                      # 新增：layout{showIdCard,container} + blocks:[]
+├── opensource.yaml    # 已有（在途）：blurb/blurb_after/repo_url/repo_label/pinned/mode/include/exclude/sort/perSource/intro_from
+│                      # 新增：projectsTitle / showHeatmap / intro_fallback_blurb（README 取不到时的专用文案）
+└── theme.yaml         # 新增：白名单感官参数（§3.6）
+```
+
+### 3.3 组件与读取层落点（写代码时照此建文件）
+
+| 落点 | 职责 |
+|---|---|
+| `src/lib/page-blocks.ts`（新） | `getAboutBlocks(locale)`：读 `siteAbout` → 过滤 `enabled:false` → 未知 `type` 跳过 + `console.warn` → 文本字段 `pickBi` 回落 zh → 长度上限（块数 ≤ 24、单块文本 ≤ 4000 字） |
+| `src/components/blocks/BlockRenderer.astro`（新） | `switch (block.type)` → 渲染子组件；统一外壳 `<section class="blk" data-block={block.type}>`（**data 属性是 E2E 断言的抓手**） |
+| `src/components/blocks/{Prose,Tracks,Cards,Timeline,Quote,Figure,LinkList,Cta,Divider}.astro`（新） | 每类一个组件，样式从 `AboutPage.astro` 现状 `<style>` 段搬迁（`.sec-title`/`.track-row`/`.track-icon` 原样保留） |
+| `src/components/pages/AboutPage.astro`（改） | 保留 `h1` + 可选 `IdCard`；`blocks` 为空 → `intro` markdown → 若再空则 `SITE_DEFAULTS.aboutIntro`（**零回归三级回落**） |
+| `src/content.config.ts`（改） | `siteAbout` schema 扩展：`blocks` 用 `z.array(z.discriminatedUnion('type',[...]))`，图片字段用 `image()` |
+| `public/admin/config.yml`（改） | `site_pages → about` 加 `blocks` 的 `list`+`types` 声明，`typeKey: type` |
+| `src/lib/site-content.ts`（改） | `renderMarkdown` 补 rehype 插件（§7.2 一笔修两洞） |
+| `src/lib/theme.ts`（新） | `getTheme()` + `themeVarsCss()` 生成 `:root:root{…}` 字符串 |
+| `src/layouts/BaseLayout.astro`（改） | head 内联 `<style set:html={themeVarsCss()}>`（构建期静态，零运行时）；`main` 容器档位由页面 `layout.container` 决定（`.container` / `.container-wide`，`global.css:43-44`） |
+
+### 3.4 Sveltia 0.252 能力边界（本仓 bundle 实测取证）
+
+证据文件：`public/admin/index.html`（pinned 本地 bundle 0.252.0，2.5MB）。
+
+| 能力 | 结论 | 取证 |
+|---|---|---|
+| `list` 异构块（`types` + `typeKey`） | **支持**：新增条目时弹「Select List Type」，按 `name` 选型 | bundle 内 i18n 键 `select_list_type`、`list_type` 组件、`{types, typeKey='type'}` 解析路径 |
+| 内建 widget 全集 | `boolean/color/code/compute/datetime/file/hidden/image/keyvalue/list/map/markdown/number/object/relation/richtext/select/string/text/uuid` | bundle 中 `ok=[…]` 常量 |
+| `richtext`（所见即所得） | 支持，**落盘默认 markdown**（`field_defaults.richtext.format`，非 html） | bundle 中 `t===\`html\`?\`html\`:\`markdown\`` |
+| 嵌套深度硬限制 | **未发现**：bundle 里唯一 `nestedDepth` 属 folder 集合路径深度，与字段嵌套无关 | 全量 grep |
+| `list` 内再放 `list` | 类型表未排除，但**无保证** → 必须做一次 10 分钟后台实测冒烟（见 §8 P1 验收） | — |
+| 拖拽排序 / 每块 summary | 支持（`summary` 模板 + reorder） | 现网 posts/moments 已在用 |
+
+编辑体验判断：`blocks` 用 `types` 后，后台表现为「+ 添加 → 选块型 → 填该块字段」，列表可拖拽，每块可折叠。**代价**：字段标签必须写成中文短标签，否则块型选择弹窗会退化成英文 key。
+
+### 3.5 双语策略（三条路线，选 A）
+
+| 方案 | 做法 | 判断 |
+|---|---|---|
+| **A 字段级 `{zh,en}`（选）** | 每个文本字段仍是 `{zh,en}`，`en` 留空回落 `zh` | 与现状全站一致（`bilingual` schema + `pickBi`），后台一屏可见双语对照；缺点是块内字段数 ×2 |
+| B 两套块数组（`blocks_zh`/`blocks_en`） | 结构可漂移 | **否决**：块数与顺序会分叉，维护地狱 |
+| C en 构建期自动翻译 | 复用 `scripts/translate/` | **否决**：违反构建确定性（产物含未提交内容），且页面级译文无人校对 |
+
+配套：`pickBi` 之外新增构建期**缺译清单**（§7.3 断言 #8），把"哪些 en 字段回落成了 zh"打成 WARN，避免静默全英文页变中文。
+
+### 3.6 样式即数据（L4）边界表
+
+| 允许（12 项） | 形态 | 风险控制 |
+|---|---|---|
+| `--accent` | color（明/暗两值） | 构建期算对比度（对 `--bg`）< 4.5 → 报警并回落默认（红线"全站唯一强调色"只能调色相，不能变多色） |
+| `--radius-img` | number 4-16 | 钳制（08 文档裁定圆角上限 14） |
+| `--text-h1/h2/h3` | number 22-32 | 单调性校验 h1>h2>h3，否则回落 |
+| `--prose-size-reading/tech` | number 16-22 | 钳制 |
+| `--leading-reading/leading-tech` | number 1.5-2.0 | 钳制 |
+| `--space-3/4/5/6` | number 8-80 | 单调递增校验 |
+| `--flow-p` / `--flow-h2-post` | number 0-2（em） | 钳制 |
+| `--dur` | number 150-600（ms） | 钳制 |
+| `--font-*` | select（内置四族，不含任意字体名） | **必须**枚举：任意字体名会让 614 个 @font-face 瘦身成果失效 |
+
+**禁止**：`--measure`（9 处引用，改版心会连带 TOC/图库/首页栅格）、`--bp-*`（断点是媒体查询字面量）、`--code-bg/--code-ink`（Shiki `css-variables` 主题在 `astro.config.mjs` 之外耦合）、`--paper*`（书评纸墨是分轨身份）。
+**注入方式**：`BaseLayout` head 内联 `<style>`，选择器用 `:root:root{…}`（0,2,0）与 `[data-theme="dark"]:root:root{…}`（0,3,0）压过 `tokens.css` 的 `:root`（0,1,0）/`[data-theme="dark"]`（0,1,0）——**不能靠 DOM 顺序**（`global.css` 的 `<link>` 注入位置与 inline `<style>` 的相对次序不可控）。断言：明暗两态 `getComputedStyle(html).getPropertyValue('--accent')` 都等于 yaml 值。
+
+---
+
+## 4. 开源页：项目可见性 + GitHub README
+
+### 4.1 在途现状（已实现，不再设计，只定稿语义）
+
+- 字段：`mode(all|only|exclude)` / `include[]` / `exclude[]` / `sort(pinned-first|stars|updated)` / `perSource(both|github|gitea)` / `pinned[]` / `intro_from(off|github-readme)`（`content/site/opensource.yaml`、`src/content.config.ts:128-138`、`src/lib/site-content.ts:180-201`）。
+- 过滤实现：`perSource` → `mode` → `sort`，**不截断**，上限交给调用方（`src/lib/projects.ts:99-134`；这修掉了旧 `orderPinned` 内 `.slice(0,6)` 导致 `/opensource` 文案说"全部仓库"实际只显示 6 条的旧账）。
+- 匹配键 = **仓库短名**（`name`），跨源同名先去重（同名优先 gitea 叙事，star 取 GitHub 真值，`src/lib/projects.ts:76-88`）。
+
+### 4.2 语义定稿（必须写进后台 hint，否则用户会填错）
+
+1. `mode: only` 时 **忽略** `exclude`；`mode: exclude` 时**忽略** `include`（v1 不做两者求交）。
+2. `include/exclude` 填不存在的名字 = 静默无效（后台无下拉可选，因为仓库清单是构建期才拿到）；→ 建议 P2 阶段把 `widget: string` 改成 `widget: select, options` 的**静态镜像**（yml 里手抄一份当前仓名）不划算，**v1 保持手填 + 构建期 WARN 打印未命中的名字**。
+3. `sort: pinned-first` 仍是默认（首页要"置顶在前"叙事），`sort: stars|updated` 时 `pinned` 让位（现实现如此：`arrange` 里 stars/updated 分支直接 sort，不看 pinned）。
+4. 首页固定 `limit=6`，开源页 `limit=99`（`ProjectWall.astro` props）。若仓库总数 >99 需调大，非阻塞。
+
+### 4.3 是否用 GitHub profile README 作为开源页开篇 —— **可行，推荐按"默认关、用户开"上线**
+
+| 评估项 | 结论 |
+|---|---|
+| 接口 | `GET /repos/wait4xx/wait4xx/readme` + `Accept: application/vnd.github.raw` = 一次请求返回 markdown 原文（现实现已如此，`site-content.ts:235-238`） |
+| 限流 | 认证 5000 req/h；构建按 push 触发（webhook ~10 秒级），每天最多几十次 → 无压力。匿名 60 req/h 会更紧张，**必须走 token** |
+| token | 复用 `~/docker_apps/blog/github-token.txt`（`src/lib/heatmap.ts:21` 同一份，0600，read 权限足够）；**缺位是合法降级路径**，不报错只 WARN |
+| CORS | **不涉及**：node 侧构建期 fetch，不是浏览器请求。（若哪天想做成客户端拉取，CORS 会直接堵死，且违反"构建期零运行时"） |
+| 许可 | 内容属本人 profile 仓（`wait4xx/wait4xx`），无第三方版权问题；README 若嵌第三方徽章图 = 外链图片，**构建期不下载、浏览器直连**，需接受 |
+| 渲染质量 | README 常见 `<p align="center">`、徽章 `<img>`、`<details>`、表格、外链图片的**相对路径**（渲染到 `/opensource/` 下会 404）。现状只做了基础排版类（`opensource.astro` 的 `.readme-intro :global(...)` 段） |
+| 破版风险 | 中：README 常含居中对齐/大标题/emoji 徽章，与"灰阶克制 + 版心 720px"张力大。→ 建议 **P5 做一次视觉复核**，必要时给 `.readme-intro` 加 `img{max-height}`、`h1{display:none}` 折叠 |
+
+**缓存实现缺陷（必改）**：`README_CACHE = 'content/.github-readme.md'`（`site-content.ts:204`）写在仓内，而构建仓每次 `git fetch && reset --hard && git clean -fd`（`infra/deploy/build.sh:26`）会**抹掉未入仓缓存**——即"网络失败回落缓存"这层在生产构建里**永远命中不了**，实际回落链退化为"网络 → 无 → yaml blurb"。
+修法（二选一，推荐后者）：
+- (a) 把缓存文件提交入仓，靠人工/定时提交更新 —— 引入"构建机写仓"脏状态，与"构建仓硬跟 origin/main"纪律冲突；
+- (b) **移到仓外**：`~/docker_apps/blog/github-readme-cache.md`（与 token 同目录，天然持久，不被 clean 波及），TTL 24h（符合 GitHub API 缓存建议），并在 `writeFileSync` 失败时只 WARN。
+
+### 4.4 失败回落矩阵（开源页）
+
+| 失败点 | 现状行为 | 目标 |
+|---|---|---|
+| token 缺位 | WARN → 缓存 → null → 用 yaml blurb | 同（缓存改仓外后才有意义） |
+| README 404 / 仓不存在 | WARN → 缓存 → blurb | 同 |
+| 网络超时 | 现实现**无 AbortSignal 超时**（`projects.ts` 有 10s，README 没有）→ 挂起风险 | 补 `AbortSignal.timeout(8000)` |
+| README 为空 | WARN → 缓存 → blurb | 同 |
+| gitea 源整站 522（历史事故） | `Promise.allSettled` 单源失败不影响另一源 | 保持 |
+| 双源全失败 | 仓内 `projects-fallback.json`（**现仅 1 条**） | 建议 P5 用一次真实构建产物回填 5-8 条 |
+
+---
+
+## 5. 关于页整页化
+
+### 5.1 现有结构 → 区块映射（逐元素，无遗漏）
+
+| 现有元素 | 文案来源 | 现状可否后台改 | 对应块型 |
+|---|---|---|---|
+| `<h1>关于` | `ui.ts:73` | ✗ | 页面 `title` 字段（或沿用字典） |
+| intro 多段 markdown | `about.yaml intro.{zh,en}` | ✓ | **prose 块**（`intro` 字段保留为兼容回退） |
+| 名片区（头像+名字+tagline+社交） | `IdCard` + `home.yaml` | 部分 ✓（tagline/socials 来自 home） | **layout.showIdCard 开关**（不拆成块：头像数据单一事实源在 home.yaml） |
+| 「兴趣版图」标题 | `ui.ts:74` | ✗ | tracks 块的 `title` |
+| 3 条 track（图标+名称+描述） | `ui.ts:75-80` | ✗ | tracks 块的 `items[]`（icon 键 + name/desc 双语） |
+| 「本站如何构建」标题+正文 | `ui.ts:81-83` | ✗ | prose 块的 `title` + `body` |
+
+→ **覆盖现有 About 只需 3 个块**（prose + tracks + prose）。其余块型是为"用户以后想加东西"准备的（§5.2）。
+
+### 5.2 区块类型清单（v1 九类，够用且不失控）
+
+| type | 字段（* = `{zh,en}`） | 说明 |
+|---|---|---|
+| `prose` | `title*?` `body*`(richtext/markdown) `width(narrow|full)` | 主力自由区（受 §7 净化） |
+| `tracks` | `title*` `items[]{icon, name*, desc*}` | 覆盖现有兴趣版图；`icon` 走内置键白名单 |
+| `cards` | `title*?` `columns(2|3)` `items[]{title*, desc*, href?, tag?}` | 技能/资源卡（复用 `.track-row` 视觉语言） |
+| `timeline` | `title*?` `items[]{time, title*, desc*?}` | 经历/项目时间线（复用 `MomentsPage` 的 `.tl-*` 竖线语言） |
+| `quote` | `text*` `cite?` | 复用 `.quote-line` + `--font-kai`（08 文档 D 金卡） |
+| `figure` | `image`(image()) `caption*?` `alt` | 必须走 Astro 图片管线 |
+| `linklist` | `title*?` `items[]{label*, href, note*?}` | 外链清单（比 markdown 裸链接可控） |
+| `cta` | `text*` `href` `label*` | 单按钮行动点（克制：同屏最多 1 个） |
+| `divider` | `style(line|space)` | 节奏控制（非装饰色彩） |
+
+**不做**（放进 §9）：`html` 块、`style` 块、`columns[grid]` 栅格构建器、任意 svg 块。
+
+### 5.3 示例 yaml（直接照抄可跑通现有关于页）
+
+```yaml
+# content/site/about.yaml
+layout:
+  showIdCard: true
+  container: narrow          # narrow=.container(720) / wide=.container-wide(+200px)
+  # 以下为可选：不填则沿用标题「关于」
+  # title: { zh: 关于, en: About }
+blocks:
+  - type: prose
+    title: { zh: '', en: '' }        # 留空不渲染标题
+    width: narrow
+    body:
+      zh: |
+        写作者 · 读者 · 快门按压者，拥抱开源。
+
+        这里是我三条轨道的公开工作台：**读过的书**留下评注，**写过的代码**进项目墙，**按下的快门**收入图库。
+      en: |
+        Writer · Reader · Shutter-presser, embracing open source.
+  - type: tracks
+    title: { zh: 兴趣版图, en: Interests }
+    items:
+      - icon: book
+        name: { zh: 阅读, en: Reading }
+        desc: { zh: 文学与戏剧为主，读到哪写到哪。, en: 'Mostly literature and drama; I write as I read.' }
+      - icon: terminal
+        name: { zh: 技术, en: Tech }
+        desc: { zh: Linux、容器与自托管……, en: 'Linux, containers, and self-hosting — …' }
+      - icon: camera
+        name: { zh: 摄影, en: Photography }
+        desc: { zh: 街拍与山野……, en: 'Street and landscapes with a mirrorless camera, …' }
+  - type: prose
+    title: { zh: 本站如何构建, en: How this site is built }
+    body:
+      zh: 静态生成，构建即发布；字体自托管，评论自托管，全文索引在构建期生成。
+      en: Statically generated, publish-on-build; self-hosted fonts, comments, and a build-time search index.
+```
+
+`icon` 键白名单（代码侧注册，同 `SocialLinks` 纪律 `src/components/SocialLinks.astro:7-19`）：`book / terminal / camera / code / git / rss / email / github / bilibili / x / star / link`。后台填表外的键 → 渲染纯文字（不破版）。
+
+### 5.4 视觉保留（不动设计体系）
+
+- 类名与样式从 `AboutPage.astro:70-143` **原样搬迁**到 `src/components/blocks/*.astro`：`.sec-title`（mono 14px/ink-3/0.08em）、`.track-row`（1px `--line` + radius 10px + `--space-3/4` 内距）、`.track-icon`（36×36 / `--bg-soft`）。
+- 新增块**只允许**用既有 token；新组件不得引入新颜色字面量（用 `--ink-*`/`--line`/`--bg-soft`）。这条要在评审时按 `grep '#[0-9a-fA-F]\{6\}' src/components/blocks/` 结果把关（`ProjectWall` 的语言色点是既存例外，不得扩散）。
+- 关于页 `--measure` 版心不变（prose 块 `max-width: var(--measure)`，`AboutPage.astro:85`）。
+
+### 5.5 兼容与零回归
+
+- `intro` 字段**不删**：`getAboutBlocks()` 见 `blocks` 缺省/空数组 → 走旧路径（`intro` markdown → 默认文案）。这样 Sveltia 里手滑清空 blocks 不会白页。
+- `t('about_track_*')` 等字典键**不删**：作为 `SITE_DEFAULTS` 的英文默认源；字典继续服务"没有 blocks 的旧数据"。
+- zh/en 双路由共用 `AboutPage.astro`（`src/pages/about.astro`、`src/pages/en/about.astro`），**块数据只存一份**，locale 在读取层选字段 —— 这是 en 轨不漂移的结构保证。
+
+---
+
+## 6. 首页扩展（结构化，不上 blocks）
+
+理由：首页是**聚合页**（列表/影像/热力图/项目墙都是"取集合切片"），块构建器在这里只会增加"选块型 → 填聚合配置"的绕路，且首页 zh/en 是两份重复文件（`src/pages/index.astro` vs `src/pages/en/index.astro`），更适合"字段少而稳"。
+
+| 已有（在途） | 建议补 | 字段形态 | 落地 |
+|---|---|---|---|
+| `tagline` `subtitle` | — | `{zh,en}` | `site-content.ts:160-175` |
+| `sections{tracks,photos,heatmap,projects}` | `heartbeat`（心跳行开关） | boolean | 同上 |
+| `perTrackLimit`(4-8) | `postsTracks`（显示哪几条轨，默认 reading+tech） | select multiple | 需给 `PostList` 加 `tracks` prop |
+| `latestPhotos`(0-6) | `photosSource(curated|latest)`：curated 读 `photos` 集合的 `pinned` 标记 | select | 需给 photos schema 加 `pinned` |
+| — | `heroStyle(idcard|plain)` | select | `IdCard` 加 variant |
+| — | `projectsLimit`(0-8，0=隐藏) | number | 传给 `ProjectWall limit` |
+| — | `announcement`（一段 markdown 短公告，渲染在 tagline 下） | `{zh,en}` markdown | 复用 `renderMarkdown`（须走净化） |
+
+**风险**：`index.astro` 与 `en/index.astro` 是**手抄双份**，任何新字段必须在两处同时接；建议 P4 顺手抽出 `src/components/pages/HomePage.astro`（吃 `locale` prop），双页变薄壳 —— 这是"双语不漂移"的结构性修法，先于新字段做。
+
+---
+
+## 7. 安全与构建可靠性
+
+### 7.1 现状漏洞（三条，均已定位到行）
+
+1. **白名单对页面文案不生效**：`renderMarkdown()` 调 `createMarkdownProcessor()` **无参**（`src/lib/site-content.ts:124`），`@astrojs/markdown-remark` 用默认 `rehypePlugins: []`（`node_modules/.pnpm/@astrojs+internal-helpers@0.13.0/.../markdown.js:21`），且默认 `allowDangerousHtml: true` + 结尾无条件挂 `rehype-raw`（`@astrojs/markdown-remark/dist/index.js:53-56,80`）。→ **`about.yaml` 的 raw HTML 直通 `set:html`**（`AboutPage.astro:20`），`<script>`/`style`/`on*` 全不被剥。文章管线有白名单（`astro.config.mjs:28`），页面文案管线**没有**。
+2. **README 是远程内容**：`githubReadmeMarkdown()` 把网上下来的 markdown 直接进 `set:html`（`src/pages/opensource.astro:17`）。即便 README 属本人仓，也等于把"远程内容"当可信 HTML 处理。
+3. **`style` 属性会用内联样式破灰阶**：现白名单剥 `style`，但只对文章生效；块模型若不统一走净化管线，同样的洞会出现在关于页。
+
+### 7.2 三道防线（按顺序实施）
+
+**D1 修管线（一处修两洞，P0）**
+```ts
+// src/lib/site-content.ts
+const { createMarkdownProcessor } = await import('@astrojs/markdown-remark');
+mdProcessor ??= createMarkdownProcessor({
+  rehypePlugins: [rehypeRaw, rehypeClassWhitelist, rehypeLinkCards], // 与 astro.config.mjs:28 同序
+});
+```
+副作用（正向）：页面 markdown 里的独立成段链接**也会变成 OG 卡片**（`rehypeLinkCards` 现已带 `content/.link-cache.json` 缓存），这是"免费能力"，需在写作指南里说明。
+
+**D2 加 tag 级允许清单（P0，扩展 `src/lib/rehype-class-whitelist.ts` 或新建 `rehype-content-sanitize.ts`）**
+- 允许标签：`p br strong em del code pre blockquote ul ol li a img h2 h3 h4 hr table thead tbody tr th td figure figcaption span div`（**不含** `script style iframe object embed form input link meta svg`）。
+- 属性允许：`a[href,title,rel]`、`img[src,alt,width,height,loading]`、其余仅 `class`（白名单）+ `id`（heading 锚）。
+- 协议允许：`http: https: mailto:` + 站内相对路径；`javascript:`/`data:`（除 `image/*` 小图外）一律剥。
+- 未知块 `type` → 跳过 + WARN，**不炸构建**。
+
+**D3 图片必须走管线（P1，随块模型）**
+- 块内 `image` 字段声明为 `image()`（Astro helper），媒体目录 `content/site/assets`（`public_folder: ./assets`，与 avatar 现状一致，`config.yml:117-118`）。
+- 禁止在块里填 `/media/...` 或外链图（**schema 层拦**：`z.string().refine(s => !/^https?:/.test(s))`，只放行 `image()` 类型）。体积纪律沿用写作指南（单张 ≤1MB）。
+
+### 7.3 验收断言清单（可直接写成 Playwright / grep 断言）
+
+| # | 断言 | 手段 |
+|---|---|---|
+| 1 | 关于页块数与顺序 == yaml（含 `enabled:false` 被滤掉） | `page.locator('[data-block]')` 逐个取 `data-block` 属性拼串比对 |
+| 2 | 零配置零回归：`about.yaml` 只有 `intro` 时，`/about/` 与改动前快照一致 | 旧产物 dist 对比（`diff <(grep -o 'class="[^"]*"' old) new`） |
+| 3 | 注入负向测试：`intro` 写 `<script>alert(1)</script>` 与 `<span style="color:red">` → 构建后 dist 不含 `alert(1)`、不含 `style="color` | `grep -c` 必须为 0 |
+| 4 | 类白名单：`<span class="font-kai foo">` → 只留 `font-kai` | 同上 grep |
+| 5 | 未知块型不炸：yaml 写 `type: not-a-block` → 构建成功 + stderr 含 WARN + 页面无该块 | 手跑一次 build |
+| 6 | 缺译可见：`en` 全空的页面 → 渲染 zh 文案 + 构建 WARN 列出字段路径 | 静态检查 build 输出 |
+| 7 | tokens 生效与压过：明暗两态 `--accent` == yaml 值；`--radius-img` 同 | `getComputedStyle(document.documentElement).getPropertyValue('--accent')` |
+| 8 | 对比度闸门：token 化颜色对 `--bg` ≥4.5:1（含暗色态） | 构建期脚本 `scripts/build-perf/contrast-check.mjs`（相对亮度公式，08 文档同口径） |
+| 9 | 图片走管线：dist 中关于页图片 `src` 含 `/_astro/` 且带 `width/height` | grep |
+| 10 | 项目墙可见性：`mode: only, include: [blog, pi-board]` → dist `/opensource/` 的 `.repo-name` 恰 2 条；`mode: exclude` 同理 | Playwright 计数 |
+| 11 | README 回落：把 token 文件改名后构建 → `/opensource/` 仍出开篇（缓存或 blurb），构建 exit 0 | 手工一次 |
+| 12 | 构建期零运行时：`dist/about/index.html` 新增 inline `<script>` 数为 0（相对基线） | grep 计数对比 |
+
+### 7.4 失败回落纪律（写进读取层，不散在组件里）
+
+| 数据 | 缺省/损坏时 | 目标 |
+|---|---|---|
+| `blocks` 空/缺 | → `intro` → `SITE_DEFAULTS.aboutIntro` | 页面永不空 |
+| 某块缺必填字段 | zod 报错即构建失败（**块内必填**要谨慎：`title` 设 optional，`body` 必填） | 宁可构建失败也不出半块 |
+| 块文本超长 | 读取层截断 + WARN | 防"一顿贴整篇长文" |
+| theme.yaml 非法值 | 钳制/回落默认 + WARN | 绝不让一个 `#zzz` 拖垮构建 |
+| 项目 API 全挂 | fallback JSON | 已有 |
+| README 全挂 | 仓外缓存 → yaml blurb | §4.4 |
+
+---
+
+## 8. 分阶段实施清单
+
+| 阶段 | 内容 | 工作量 | 依赖 | 落地文件 | 验收 |
+|---|---|---|---|---|---|
+| **P0** | 修 markdown 管线（D1）+ tag 白名单（D2）+ 负向断言 #3/#4 | 0.5d | 无 | `src/lib/site-content.ts`、`src/lib/rehype-content-sanitize.ts`(新)、`tests/e2e.mjs` 或 `scripts/build-perf/content-lint.mjs` | 断言 3/4 绿，现有文章渲染零回归 |
+| **P0.5** | 后台实测冒烟：`list` 内嵌 `list`、`richtext` 嵌套在 `object` 内是否可用 | 0.2d | 无（需 token 登录一次） | 无代码，结论回写本文 §3.4 | 能新增/拖拽/保存并构建通过 |
+| **P1** | blocks 骨架：schema + `page-blocks.ts` + `BlockRenderer` + prose/tracks/divider 三块 + 后台 `types` 声明 | 2d | P0、P0.5 | `src/content.config.ts`、`src/lib/page-blocks.ts`、`src/components/blocks/*`、`src/components/pages/AboutPage.astro`、`public/admin/config.yml` | 断言 1/2/5/6 |
+| **P2** | 块型扩充（cards/timeline/quote/figure/linklist/cta）+ 图标键白名单 + 图片走管线（D3） | 1.5d | P1 | 同上 + `content/site/assets/` | 断言 9；视觉复核一轮（glm-5.3-flash） |
+| **P3** | theme.yaml + `theme.ts` + BaseLayout 内联变量 + 对比度闸门脚本 | 1d | P0（净化不相关，可并行） | `content/site/theme.yaml`、`src/lib/theme.ts`、`src/layouts/BaseLayout.astro`、`scripts/build-perf/contrast-check.mjs`、`public/admin/config.yml` | 断言 7/8 |
+| **P4** | 首页字段细化 + 抽 `HomePage.astro` 消双份 | 1d | P0 | `src/components/pages/HomePage.astro`(新)、`src/pages/index.astro`、`src/pages/en/index.astro`、`site-content.ts` | zh/en 区块数一致；开关组合抽测 |
+| **P5** | 开源页收尾：README 缓存移仓外 + 超时 + fallback JSON 回填 5-8 条 + `include` 未命中 WARN | 0.5d | 在途车道合并 | `src/lib/site-content.ts`、`src/data/projects-fallback.json` | 断言 10/11 |
+| **P6** | 文档：`docs/管理台.md`（块编辑怎么用）、`docs/写作指南.md`（受限类 + 块字段）、`public/admin/config.yml` hint 全量中文 | 0.5d | P1-P4 | 三文件 | 后台每字段都有中文 hint |
+
+合计 ≈7.2d（不含视觉复核排队）。**建议顺序**：P0 → P0.5 →（P1 与 P3 可并行）→ P2 → P5 → P4 → P6。P5 最便宜且能立刻消掉在途车道的生产隐患，可提前插队。
+
+---
+
+## 9. 明确不做（附理由）
+
+1. **任意 HTML/`style` 块**：等于把灰阶骨架与 XSS 面交给后台输入；08 文档红线（禁渐变/玻璃/大圆角）无法用代码守住。
+2. **可视化栅格/自由拖拽布局（columns、grid 编辑器）**：Astro 侧要一套运行时布局引擎，违"构建期零运行时"；且移动端塌陷规则无法交给后台。
+3. **可编辑颜色集（多个强调色/任意 hex 用于文本）**：全站唯一强调色是丙路线根基（`tokens.css:21-22`），只允许 `--accent` 一个旋钮并过对比度闸门。
+4. **`--measure` / 断点可调**：`--measure` 9 处引用、断点写死在媒体查询里；改版心会连带 TOC/栅格/图库。
+5. **任意字体名输入**：字体子集化（`scripts/build-perf/subset-font-css.mjs`）依赖固定四族，自由输入会静默失效或拖大 CSS。
+6. **块模型用于首页**：首页是聚合页（§6），结构化字段更稳、更好审。
+7. **`blocks_zh`/`blocks_en` 双数组**：结构会分叉。
+8. **构建期自动翻译页面文案**：破坏构建确定性（产物含未提交内容），且无人校对。译文必须入仓（沿用 `posts-en` 的 `locked: true` 纪律）。
+9. **运行时/客户端渲染页面内容**（含客户端拉 GitHub README）：CORS、SEO、性能三杀。
+10. **后台新建任意页面路由（v1 不做）**：需 `[...slug].astro` + 导航/站点地图/双语配对/`hidden` 语义，收益低于成本；等关于页验证过一轮再议（那时复用同一套 BlockRenderer，成本会低很多）。
+11. **换 CMS / 上 Netlify 式可视化编辑器**：现有 Sveltia 0.252 已支持 `types` 异构列表（§3.4），够用；迁移成本远高于收益。
+12. **每页独立 tokens**（页面级主题覆盖）：双层变量来源会让"某页为什么和别的页不一样"变成排查噩梦；v1 只有全局一套。
+
+---
+
+## 附：待用户拍板的三个岔路
+
+1. **关于页块模型 vs 长文**：块模型（本文推荐，结构可控、视觉一致）vs 单一 markdown 长文（改起来最快，但 tracks 卡片做不出来）。
+2. **README 开篇是否开**：开（省手工维护，但版式受 GitHub README 影响）vs 关（`intro_from: "off"`，全手控）。
+3. **样式旋钮范围**：只给 3 个（accent/radius/字号）还是一整套 12 个（§3.6）——旋钮越多越需要对比度闸门与视觉复核，建议先给 3 个、跑稳一版再扩。
@@ -36,3 +36,28 @@ sudo bash infra/deploy/rollback.sh --exec   # 秒级回 Halo
 - 新文章工作流：本地或 gitea web 写 md → push main → webhook 自动构建发布
 - 新照片：上传 content/photos/ 后跑 `python3 scripts/photos_ingest.py` 再 commit
 - 翻译：新文章 push 后跑 `python3 scripts/translate/translate_posts.py`（幂等）
+
+---
+
+## SEO 解封操作单（Phase 5f T1，2026-10-26 立案）
+
+**背景**：生产全站自上线起带 `X-Robots-Tag: noindex`（/etc/nginx/snippets/esa-origin-ssl.conf:11 共享片段误伤博客 vhost）+ robots.txt 404 + ESA 将带 noindex 的响应头缓存 30 天——搜索引擎全站不可见。
+
+**第一步：nginx（需 sudo）**
+1. 编辑 `/etc/nginx/snippets/esa-origin-ssl.conf`：删除第 11 行 `add_header X-Robots-Tag noindex always;`（改前备份 .bak）
+2. 给确实需要 noindex 的内部服务 vhost（api/oj/token/fc/latex/cpa/git）各 server 块补回该行
+3. 博客 vhost 补局部：`location /admin/ { add_header X-Robots-Tag noindex always; }`
+4. `sudo nginx -t && sudo systemctl reload nginx`
+
+**第二步：ESA 控制台（不做则 noindex 再活 30 天）**
+1. 全站 purge `wait4x.online`
+2. HTML 边缘 TTL 调 ≤1h（当前 2592000s，靠回源重验证更新——头会固化）
+3. 加规则：`/artalk/api/*` 绕过缓存（GET stats 有 Age 头实锤，pv 数字会冻）
+
+**第三步：验证**
+```bash
+curl -sI https://wait4x.online/ | grep -ci x-robots-tag        # 期望 0
+curl -s https://wait4x.online/robots.txt | head -3             # 期望 User-agent + Sitemap
+curl -sI https://wait4x.online/admin/ | grep -ci noindex       # 期望 1（局部保留）
+```
+仓库侧已就绪：public/robots.txt（本提交）；生产 Lighthouse SEO≥95 复测随后入档。
@@ -22,10 +22,11 @@ content/posts/

 ```markdown
 ![外滩夜景](./assets/my-post/bund.jpg)
-*图：外滩的傍晚*            ← 紧跟媒体的斜体独立段 = 图注（居中小字）
+<p class="fig-cap">图：外滩的傍晚</p>   ← 显式图注类（居中小字）
 ```

- 图注可选；写法固定为 `*…*` 单独成段，紧跟图片
+- 图注可选；**必须用 `<p class="fig-cap">…</p>`**（2026-11-02 起）
+- ⚠️ 旧写法 `*斜体独立段*` 已不再自动当图注：此前它会把正文里所有独占成段的斜体都变成块级居中（用户实测的排版 bug），现在斜体恢复为正常行内强调
 - 压缩纪律：入仓前长边 ≤2400px（可跑 `python3 scripts/photos_ingest.py`，对 posts 资产同样有效的思路，图片请自行用同规格压缩）

 ## 视频 / 音频
@@ -65,7 +66,266 @@ public/media/my-post/clip.mp4      ← 文件放这里

 见 `content/posts/media-sample.md`（draft 文章，仅构建验证用，不上线）。

+## 链接卡片（OG 预览卡）
+
+**一行只放一个链接、且它独立成段**时，构建期会抓取该页的 OG 信息渲染成卡片（标题 / 描述 / 站点图标 / 可选缩略图）：
+
+```markdown
+https://astro.build/
+
+[也可以是 markdown 链接形态](https://astro.build/)
+```
+
+规则与边界：
+
+- **内联链接不变**：夹在句子里的链接保持普通样式（`这是一句带 [链接](https://example.com) 的话` → 不会变卡），所以不会把整篇变成卡片墙
+- **抓取失败一律回落普通链接**：404、无 OG、超时（4s）、站点拒爬都不影响构建
+- **每篇最多 10 张卡**，超出的回落普通链接（防止文章变卡片流）
+- **缓存**：结果存 `content/.link-cache.json`（入仓，保证构建确定性）；条目 30 天后自动重抓。想强制刷新某条——删掉该 URL 的条目即可
+- 缩略图取 `og:image`，无图不占位；图标取站点而非第三方 favicon 服务
+
+## 文章排版类（受限白名单）
+
+正文里可用 `<span class="…">` / `<p class="…">` 做**受限**排版。构建期有白名单过滤：**只放行下表类名，其它 class 与 `style`、`on*` 属性一律被剥离**（防注入 + 保护灰阶骨架）。
+
+### 灰阶层级类（全部实测亮暗对比度 ≥4.5:1）
+
+| 类名 | 作用 |
+|---|---|
+| `ink-1` / `ink-2` / `ink-3` | 指定灰阶层（标题/正文/次要） |
+| `ink-muted` | 最淡灰（注释感） |
+| `ink-faint` | 最淡**可读**档（再淡即不达 AA） |
+| `ink-warm` | 暖调正文（书评气质） |
+| `ink-cool` | 冷调正文（技术气质） |
+| `ink-accent` | 强调（链接色，少量点缀） |
+| `ink-accent-soft` | 弱强调（比强调淡一档） |
+
+### 语义色板（8 色相 × 标准/soft；亮暗各自取值，实测全部 ≥4.5:1）
+
+| 色相 | 标准类 | soft 类 | 亮态对比度（标准 / soft） | 暗态（标准 / soft） |
+|---|---|---|---|---|
+| 蓝 | `c-blue` | `c-blue-soft` | 6.46 / 4.58 | 7.70 / 4.61 |
+| 青 | `c-teal` | `c-teal-soft` | 5.00 / 4.57 | 9.77 / 4.52 |
+| 绿 | `c-green` | `c-green-soft` | 5.38 / 4.67 | 10.38 / 4.67 |
+| 黄 | `c-yellow` | `c-yellow-soft` | 6.45 / 4.57 | 11.73 / 4.52 |
+| 橙 | `c-orange` | `c-orange-soft` | 6.26 / 4.65 | 9.44 / 4.58 |
+| 红 | `c-red` | `c-red-soft` | 6.68 / 4.55 | 7.51 / 4.50 |
+| 粉 | `c-pink` | `c-pink-soft` | 6.96 / 4.73 | 8.87 / 4.52 |
+| 紫 | `c-purple` | `c-purple-soft` | 7.46 / 4.53 | 8.25 / 4.64 |
+
+- 黄色在亮态被压暗到 `#7a5900`（原色在白底只有 ~1.8:1），这是**必须**的：彩色文字要能读
+- `soft` 档是"阈值内最淡值"，适合次要强调；标准档用于关键强调
+
+> **使用纪律（重要）**：彩色**只作用于文章正文的强调文字**。站点外壳（导航、页脚、按钮、背景、卡片边框）一律保持灰阶——整站不因正文用色而花掉。写作时一个页面里的彩色强调建议不超过 3 处。
+
+### 字体类
+
+| 类名 | 作用 | 字体 | 许可证 | 加载 |
+|---|---|---|---|---|
+| `font-serif` | 书评正文族 | Noto Serif SC | OFL-1.1 | 自托管 |
+| `font-kai` | 金句族 | 霞鹜文楷 Screen | OFL-1.1 | 自托管 |
+| `font-sans` | UI/技术族 | Noto Sans SC | OFL-1.1 | 自托管 |
+| `font-mono` | 标签/数值 | JetBrains Mono | OFL-1.1 | 自托管 |
+| `font-song` | 宋体族 | Noto Serif SC 优先，系统宋体兜底 | OFL-1.1 | **自托管优先** |
+| `font-kai-sys` | 楷体族 | 霞鹜文楷优先，系统楷体兜底 | OFL-1.1 | **自托管优先** |
+| `font-hei-sys` | 黑体族 | Noto Sans SC 优先，系统黑体兜底 | OFL-1.1 | **自托管优先** |
+| `font-fangsong` | 仿宋族 | FangSong/STFangsong | — | ⚠️ **纯系统回退**（暂无 OFL 自托管仿宋包） |
+
+### 文学排版类（段落级）
+
+| 类名 | 作用 |
+|---|---|
+| `drop-cap` | 段落首字下沉（书评开篇） |
+| `quote-line` | 金句块（左侧竖线 + 文楷） |
+| `fig-cap` | 图注（居中小字） |
+
+### 首批字体（已落地，6 族 + 3 档自托管优先）
+
+| 类名 | 字体 | 许可证 | webfont 嵌入 | 用到该字体的页面增量 |
+|---|---|---|---|---|
+| `font-serif` | Noto Serif SC | OFL-1.1 | ✅ OFL 允许 | 基线内 |
+| `font-sans` | Noto Sans SC | OFL-1.1 | ✅ | 基线内 |
+| `font-kai` | 霞鹜文楷 Screen | OFL-1.1 | ✅ | 基线内 |
+| `font-mono` | JetBrains Mono | OFL-1.1 | ✅ | 基线内 |
+| `font-huiwen` | 汇文明朝体（文风切片包 339 片） | OFL-1.1 | ✅ | **535KB** |
+| `font-kuaile` | 站酷快乐体 | OFL-1.1 | ✅ | **163KB** |
+| `font-song` / `font-kai-sys` / `font-hei-sys` | 上述自托管字体优先，系统字族兜底 | OFL-1.1 | ✅ | **+0KB** |
+
+体积账结论（2026-11-02 实测，本地无 gzip 的相对值）：**未使用某字体的页面，字体字节增量恒为 0**（构建期按页子集化 + unicode-range 按需拉取）。汇文采用文风开源的 cn-font-split 切片包（339 片），实测只拉用到字符的 19 片。
+
+### 候补字体清单（未落地，加一款约"一条命令 + 一次体积账"）
+
+| 字体 | 许可证 | 允许 webfont 嵌入 | 未落地原因 |
+|---|---|---|---|
+| HarmonyOS Sans | 华为字体许可（免费商用） | ✅ 明文允许"嵌入、捆绑、重新分发"，需标注 | npm 无包，官网整包 52MB |
+| MiSans | 小米字体许可（免费商用） | ✅ 官方 FAQ 明确 "embedded fonts: Yes"，需注明 | npm 无包 |
+| OPPO Sans | 免费授权（含商用） | ✅（附带"不向他方提供下载渠道"限制） | npm 无包 |
+| 阿里巴巴普惠体 | 免费商用全场景 | ✅ | npm 无包，9 字重体积巨大 |
+| 得意黑 Smiley Sans | OFL-1.1 | ✅ | 仅 GitHub release 整包，直链在当前网络不可达 |
+| 更纱黑体 Sarasa Gothic / Sarasa Mono | OFL-1.1 | ✅ | npm 包为空壳（需 cli 自生成切片） |
+| 花园明朝 HanaMinA/B | IPA Font License | ✅（允许嵌入） | 无 npm 包，仅兜底用 |
+| 站酷高端黑 / 站酷快乐体（已落） | OFL-1.1 | ✅ | 高端黑无 @fontsource 版本 |
+| 阿里妈妈东方大楷 / 演示悠然小楷 | 免费商用 / 个人免费 | ⚠️ 需逐款核嵌入条款 | 无包；"个人免费"字体常禁 @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/页 的要评估是否值得。
+
+```markdown
+<span class="ink-muted">次要说明</span>
+<span class="font-kai">金句可以换文楷</span>
+<p class="drop-cap">开篇段落，首字会下沉。</p>
+<p class="quote-line">所谓暮色，就是光慢慢地承认自己要走。</p>
+```
+
+- **颜色只能走上面这些类**（内部用 tokens，亮暗双态都可读）；写 `style="color:red"` 会被构建期剔除
+- 斜体就用普通 markdown `*斜体*`——行内强调，不会换行也不会居中
+
+### 后台可视化选择（推荐，不用写 HTML）
+
+后台编辑器里：**选中文字 → Insert 菜单 → 「排版（字体/颜色）」→ 面板里点一个类**，文字即被 `<span class="…">` 包住；点已套用的片段可改类，Backspace 可整体删除。
+面板里的两类与上表一一对应（字体 8 / 颜色 9），类清单单一事实源在 `public/admin/typography-classes.js`。
+
+## 三层排版架构（全站，不只文章正文）
+
+**层 1 · 页面文案富文本**：后台「页面文案」里的 tagline / subtitle / blurb / blurb_after / intro / 关于页 blocks 的 prose 块，全部走同一条富文本管线（markdown + raw + 内容净化 + class 白名单 + 链接卡片）。可以直接写：
+
+```yaml
+tagline:
+  zh: '<span class="font-kai c-blue">写作者</span> · 读者 · 快门按压者，拥抱开源。'
+```
+
+渲染入口唯一：`src/lib/site-content.ts` 的 `renderRich()`（行内场景传 `{ inline: true }` 自动剥外层 `<p>`，否则 `<p>` 套 `<p>` 会被浏览器拆散）。
+**不开放**：导航/页脚/按钮等硬编码界面外壳——那是 UI 不是内容。
+
+**层 2 · 页面级排版覆盖**：每个页面单例（`content/site/*.yaml`）可加：
+
+```yaml
+typography:
+  font: font-kai        # 本页正文默认字体类（可选）
+  accent: c-blue        # 本页强调色类（可选）
+  scale: 1.1            # 字号缩放 0.8–1.25（可选）
+```
+
+实现是在该页内容容器上挂 `.page-typo` + CSS 变量（`--page-font / --page-accent / --page-scale`），**不写全站 tokens**——其它页面零影响（已在图库/书架/文章/装备页验证隔离）。白名单外的类名会被忽略。
+后台入口：「页面文案 → 各自页面 → 页面排版覆盖」。
+
+**层 3 · 艺术字体**：`font-art-kuaile`（站酷快乐体，艺术字专用类）。⚠️ **仅用于标题/短句**：艺术字字形大，CJK 切片体积高（实测用到页 +163KB），长段使用会显著抬高单页字体成本。
+
 ## 发布提醒

 - push main → webhook 自动构建发布（约 10 秒）
 - 新文章要英文版：跑 `python3 scripts/translate/translate_posts.py`（幂等，代码块不会被翻译破坏的风险见其 README 注释；锁定润色用 frontmatter `locked: true`）
+
+
+## 书封图（/books 书架）
+
+阅读轨文章可选加书封：
+
+1. 图片放 `content/posts/assets/books/<slug>.jpg`（建议宽 480px、高宽比约 2:3）
+2. 对应文章 frontmatter 加一行：`cover: ./assets/books/<slug>.jpg`
+3. 构建自动优化出 96/192 两档；**没有 cover 的文章优雅回退现有色脊卡设计**，无需改任何代码
+
+示例 frontmatter：
+```yaml
+---
+title: "面纱"
+pubDate: 2024-06-01
+category: reading
+bookAuthor: "毛姆"
+mood: "#8a6f4a"
+cover: ./assets/books/mian-sha.jpg
+---
+```
+
+## 后台上传（Sveltia 后台，推荐路径）
+
+后台地址 `/admin/`（gitea 账号登录）。三类媒体都有后台入口，不必手写路径：
+
+### 图片
+
+文章编辑器里插入图片 → 自动上传到 `content/posts/assets/` 并写入 `./assets/...`
+相对路径（走 Astro 图片管线，自动优化）。**不要手改成 `/assets/...` 绝对路径**。
+
+### 视频（frontmatter 字段，正文后自动渲染）
+
+1. 文章编辑页「附视频」字段上传（自动落 `public/media/`，路径写 `/media/<name>.mp4`）
+2. 正文读完后自动出现 `<video controls preload="metadata" playsinline>`，全宽圆角黑底
+3. 「视频封面」填 `/media/xxx.jpg` 可自定首帧；留空浏览器自取
+4. 无视频字段 → 该区块不渲染（零占位）
+
+体积纪律：mp4/webm ≤50MB 走 `public/media/`（构建原样拷贝，不转码）；
+更大的请按上文「体积纪律」放仓外 store（该场景 build.sh 同步段待首次出现时补）。
+
+### 后台列表日期
+
+文章/瞬间列表显示「日期 · 标题」，可按日期排序；图库照片没有 frontmatter 日期
+（时间在 EXIF/文件侧），列表按「分组 · 标题」展示、按标题/分组排序。
+
+### 链接
+
+markdown 原生语法，无需任何配置：
+
+```markdown
+[文字](https://example.com)
+```
+
+想让链接显示成 OG 预览卡（带标题/描述/图标），把它**单独放一行**即可——规则见上文「链接卡片（OG 预览卡）」。
+
+### 页面文案（主页/关于/开源）
+
+后台「页面文案」下三个入口：
+
+| 入口 | 文件 | 可改内容 |
+|---|---|---|
+| 主页设置 | `content/site/home.yaml` | 身份语 tagline、**头像 avatar**、**站点图标 favicon**、**社交链接 socials** |
+| 关于页 | `content/site/about.yaml` | **markdown 正文 intro**（多段/列表/粗斜体/链接） |
+| 开源页 | `content/site/opensource.yaml` | 叙述 blurb/blurb_after、仓链接、置顶项目 pinned |
+
+#### 头像与站点图标
+
+- **头像**：主页设置里「头像」上传 → 落 `content/site/assets/`，构建期优化成 60px WebP；
+  留空则显示内置渐变占位（w4 徽标）
+- **站点图标 favicon**：先经「图标」媒体库上传（`public/icons/`），再把路径粘到
+  「站点图标」字段（如 `/icons/my.ico`、`/icons/my.svg`）；留空回退 `/favicon.svg`。
+  支持 `.svg` / `.ico` / `.png`（直出，不经图片优化）
+
+#### 社交链接
+
+主页设置里「社交链接」是列表：可增删、拖动排序。每条 = 名称（无障碍文字）+ 链接 + 图标。
+图标可选 `github / rss / email / bilibili / x`，**留空则显示纯文字按钮**。
+首页名片区、以及任何引用该组件的页面都吃同一份数据（单一事实源，改一次全站生效）。
+
+#### 首页可配项（home.yaml）
+
+| 字段 | 取值 | 默认 | 作用 |
+|---|---|---|---|
+| `subtitle` | `{zh, en}`（markdown 短文本） | 空 | 身份语下方的副标题；留空不渲染 |
+| `latestPhotos` | 0-6 | 4 | 「最新影像」张数；**0 = 隐藏该区块** |
+| `perTrackLimit` | 4-8 | 6 | 首页阅读/技术两轨各显示条数 |
+| `sections` | `{tracks, photos, heatmap, projects}` 布尔 | 全开 | 区块开关，关掉即不渲染 |
+
+越界值会被夹取（如 perTrackLimit=20 按 8 处理），不报错；**全部留空 = 现有形态不变**。
+
+#### 开源页项目墙（opensource.yaml）
+
+| 字段 | 取值 | 默认 | 作用 |
+|---|---|---|---|
+| `mode` | `all` / `only` / `exclude` | all | 可见性模式 |
+| `include` | 仓短名数组 | 空 | mode=only 时的白名单 |
+| `exclude` | 仓短名数组 | 空 | mode=exclude 时的黑名单 |
+| `sort` | `pinned-first` / `stars` / `updated` | pinned-first | 排序方式 |
+| `perSource` | `both` / `github` / `gitea` | both | 来源过滤 |
+| `intro_from` | `"off"` / `github-readme` | off | 开篇文案来源 |
+
+> `intro_from` 建议**带引号写**：YAML 1.1 里裸 `off` 会被解析成布尔 false。
+> 选 `github-readme` 时构建期取 `wait4xx/wait4xx` 的 README 渲染为开篇，
+> 成功后缓存到 `content/.github-readme.md`（入仓）；token 缺位/取失败/仓无 README
+> 都会打印日志并回落 yaml 的 blurb。注意 README 里的相对链接与外部徽章会原样输出。
+
+#### 首页文章列表
+
+首页现在分两段：**阅读轨 6 条 + 技术轨 6 条**（各自带「全部文章」出口：阅读→书架、技术→归档）。
+照片轨文章不进首页（在图库看）。完整列表见 `/archives/`。
+
+- 中文/英文各一个字段，页面按语言取；**留空则该字段回落默认文案**（构建不会炸）
+- `pinned` 填仓库短名（如 `blog`、`pi-board`），**顺序即展示顺序**；留空回落 `blog`
@@ -6,15 +6,21 @@
 # 发布。改为独立构建仓 fetch+reset 硬跟 main：线上=远端 main，确定性闭环。
 # blog 仓已公开，匿名 fetch 无需凭据。
 set -e
+# 抓取 URL：默认公网；同机构建可由宿主环境变量覆盖为内网
+# （2026-10-26 事故：ESA 边缘对 git.wait4x.online 522 时公网 fetch 失败，
+#  set -e 下静默死、staging 冻结——内网通道必须可用）
+BLOG_GIT_URL="${BLOG_GIT_URL:-https://git.wait4x.online/wait4x/blog.git}"
 BUILD_REPO="$HOME/docker_apps/blog/build-repo"
 STAGING="$HOME/docker_apps/blog/www-staging"

 if [ ! -d "$BUILD_REPO/.git" ]; then
  echo "[build] 首次克隆构建仓"
-  git clone https://git.wait4x.online/wait4x/blog.git "$BUILD_REPO"
+  git clone "$BLOG_GIT_URL" "$BUILD_REPO"
 fi

 cd "$BUILD_REPO"
+# 每次构建把 origin 指向配置的 URL（同机构建走内网通道；公网 522 时仍可发布）
+git remote set-url origin "$BLOG_GIT_URL"
 git fetch origin main
 git reset --hard origin/main
 git clean -fd --exclude node_modules
@@ -27,10 +33,14 @@ pnpm astro build
 # 按页字体 CSS 子集化（车道 A 任务 1）：裁 @font-face 声明数，构建仓与本地同链；
 # 存在性守卫：新文件未推送到 main 前构建仓无此脚本，绝不让发布链因车道在途文件断掉
 [ -f scripts/build-perf/subset-font-css.mjs ] && node scripts/build-perf/subset-font-css.mjs dist || echo "[build] subset 脚本未就绪，跳过"
+[ -f scripts/build-perf/contrast-check.mjs ] && node scripts/build-perf/contrast-check.mjs dist || echo "[build] contrast 脚本未就绪，跳过"
 # 首页阻塞 CSS 内联（车道 D）：守卫先行同上——脚本未到 main 前绝不炸链
 [ -f scripts/build-perf/gen-sw-precache.mjs ] && node scripts/build-perf/gen-sw-precache.mjs dist || echo "[build] sw-precache 生成器未就绪，跳过"
 [ -f scripts/build-perf/inline-home-css.mjs ] && node scripts/build-perf/inline-home-css.mjs || echo "[build] inline-home 脚本未就绪，跳过"

+# 内容 lint（T3）：断链/缺图在部署前拦截；CONTENT_LINT=skip|warn 逃生门见脚本头注
+[ -f scripts/build-perf/content-lint.mjs ] && node scripts/build-perf/content-lint.mjs dist || echo "[build] content-lint 未就绪，跳过"
+
 echo "[build] rsync -> $STAGING"
 mkdir -p "$STAGING"
 rsync -a --delete "$BUILD_REPO/dist/" "$STAGING/"
@@ -38,3 +48,9 @@ ORIG="$HOME/docker_apps/blog/photos-originals"
 if [ -d "$ORIG" ]; then rsync -a "$ORIG/" "$STAGING/photos-originals/"; fi
 printf 'built %s at %s\n' "$SHA" "$(date -Is)" > "$STAGING/.build-stamp"
 echo "[build] done: $(find "$STAGING" -name '*.html' | wc -l) html files @ $SHA"
+
+# 生产冒烟（T3）：staging 三断言。首版容忍失败（robots 待 T1 落地，smoke FAIL 属预期），
+# T1 收编后改硬门：去掉 `|| echo` 让断言失败直接炸构建
+if [ -f scripts/build-perf/prod-smoke.sh ] && [ "${SMOKE_BASE:-http://127.0.0.1:18743}" != "off" ]; then
+  bash scripts/build-perf/prod-smoke.sh "${SMOKE_BASE:-http://127.0.0.1:18743}" || echo "[build] prod-smoke 未过（见上；T1 robots 落地后转硬门）"
+fi
@@ -85,11 +85,15 @@ class Handler(BaseHTTPRequestHandler):

    def _run_build(self) -> None:
        with BUILD_LOCK:
-            subprocess.run(
-                ["bash", str(build_script())],
-                capture_output=True, timeout=1200,
-                cwd=str(BUILD_REPO),
-            )
+            # 输出落盘：capture_output 丢弃是调试黑洞（2026-10-26 ESA 522
+            # 事件中构建静默死、staging 冻结无任何可见痕迹）
+            log = Path.home() / "docker_apps/blog/build.log"
+            with open(log, "wb") as fh:
+                subprocess.run(
+                    ["bash", str(build_script())],
+                    stdout=fh, stderr=subprocess.STDOUT, timeout=1200,
+                    cwd=str(BUILD_REPO),
+                )

    def log_message(self, fmt: str, *args: object) -> None:
        # 静默常规访问日志（健康探针会刷屏）；错误仍走默认 stderr
@@ -16,13 +16,17 @@
    "@fontsource-variable/noto-serif-sc": "^5.3.1",
    "@fontsource/jetbrains-mono": "^5.3.0",
    "@fontsource/noto-sans-sc": "^5.3.1",
-    "astro": "^7.3.8",
+    "@fontsource/zcool-kuaile": "^5.3.0",
+    "astro": "^7.4.4",
    "astro-pagefind": "^2.0.1",
    "exifr": "^7.1.3",
    "lxgw-wenkai-screen-webfont": "^1.7.0",
+    "pdfjs-dist": "^6.4.299",
+    "rehype-raw": "^7.0.0",
    "sharp": "^0.35.5"
  },
  "devDependencies": {
+    "@astrojs/markdown-remark": "^7.3.5",
    "@fontsource/noto-serif-sc": "^5.3.1",
    "playwright": "^1.64.1"
  }
@@ -5,8 +5,10 @@ backend:
  name: gitea
  repo: wait4x/blog
  branch: main
-  base_url: https://git.wait4x.online
-  api_root: https://git.wait4x.online/api/v1
+  # 走博客域同源反代（nginx /gitea/ → 127.0.0.1:13020）：
+  # ①绕开 git.wait4x.online 的 ESA 522 ②同源无 CORS ③ESA 缓存规则已排除 /artalk/api
+  base_url: https://wait4x.online/gitea
+  api_root: https://wait4x.online/gitea/api/v1

 media_folder: content/photos
 site_url: https://wait4x.online
@@ -16,6 +18,69 @@ output:
  omit_empty_optional_fields: true

 collections:
+  # 文章（含书评/技术/照片三轨；书=category:reading 的文章，同一集合管理）
+  - name: posts
+    label: 文章
+    label_singular: 文章
+    folder: content/posts
+    create: true
+    # 中文主稿；英文为 TMT 预翻译入仓的 .en.md（posts-en 集合不在后台，防误改译文）
+    slug: '{{slug}}'
+    summary: '{{pubDate}} · {{title}}'
+    sortable_fields: [pubDate, title]
+    # 注意：Sveltia 对 folder 集合的 media_folder 按"相对集合目录"解析
+    # （写成 content/posts/assets 会二次嵌套成 content/posts/content/posts/assets，
+    # 实测 2026-11-02 首上传即踩），故这里必须写 assets
+    media_folder: assets
+    public_folder: ./assets
+    fields:
+      - { label: 标题, name: title, widget: string }
+      - { label: 日期, name: pubDate, widget: datetime, date_format: 'YYYY-MM-DD', time_format: false, format: 'YYYY-MM-DD' }
+      - { label: 分轨, name: category, widget: select, options: [{label: 阅读, value: reading}, {label: 技术, value: tech}, {label: 照片, value: photo}] }
+      - { label: 标签, name: tags, widget: list, required: false }
+      - { label: 情绪色（书评色脊）, name: mood, widget: color, required: false, hint: '#RRGGBB，仅阅读轨使用' }
+      - { label: 原书作者, name: bookAuthor, widget: string, required: false }
+      - { label: 一句话描述（书架策展语）, name: description, widget: text, required: false }
+      - { label: 书封图, name: cover, widget: image, required: false, hint: '上传后自动生成，无需手填路径；仅阅读轨展示' }
+      - label: 附视频（可选）
+        name: video
+        widget: file
+        required: false
+        media_folder: public/media
+        public_folder: /media
+        hint: '展示在正文之后；mp4/webm ≤50MB（走 public/media，构建时原样拷贝，不做转码）'
+      - label: 视频封面（可选）
+        name: poster
+        widget: string
+        required: false
+        hint: '填 /media/xxx.jpg（先上传到 public/media 取路径）；缺省浏览器自取首帧'
+      - { label: 隐藏（不进列表/sitemap）, name: hiddenTag, widget: boolean, required: false, hint: '对应 tags 含 hidden；保存后请人工核对' }
+      - { label: 草稿, name: draft, widget: boolean, required: false, default: false }
+      - { label: 正文, name: body, widget: markdown }
+
+  # 主题旋钮（样式即数据 · 层 4）：只放白名单内的 9 组，越界值会被构建期钳制
+  - name: site_theme
+    label: 主题设置
+    file: content/site/theme.yaml
+    fields:
+      - { label: 强调色（亮）, name: accent_light, widget: color, required: false, hint: '亮色模式强调色，如 #3454d1；构建期校验正文对比度 ≥4.5' }
+      - { label: 强调色（暗）, name: accent_dark, widget: color, required: false, hint: '暗色模式强调色，如 #8ea2ff' }
+      - { label: 图片圆角, name: radius_img, widget: number, required: false, value_type: int, min: 4, max: 16, hint: '范围 4–16（建议 ≤14）' }
+      - { label: 一级标题字号, name: text_h1, widget: number, required: false, value_type: int, min: 22, max: 32, hint: '22–32，且必须大于 h2' }
+      - { label: 二级标题字号, name: text_h2, widget: number, required: false, value_type: int, min: 22, max: 32, hint: '22–32，必须小于 h1、大于 h3' }
+      - { label: 三级标题字号, name: text_h3, widget: number, required: false, value_type: int, min: 16, max: 32, hint: '16–32，必须小于 h2' }
+      - { label: 书评正文字号, name: prose_size_reading, widget: number, required: false, value_type: int, min: 16, max: 22, hint: '16–22' }
+      - { label: 技术文正文字号, name: prose_size_tech, widget: number, required: false, value_type: int, min: 16, max: 22, hint: '16–22' }
+      - { label: 书评行高, name: leading_reading, widget: number, required: false, value_type: float, min: 1.5, max: 2.0, step: 0.05, hint: '1.5–2.0' }
+      - { label: 技术文行高, name: leading_tech, widget: number, required: false, value_type: float, min: 1.5, max: 2.0, step: 0.05, hint: '1.5–2.0' }
+      - { label: 间距 3, name: space_3, widget: number, required: false, value_type: int, min: 8, max: 80, hint: '8–80，必须 < 间距 4' }
+      - { label: 间距 4, name: space_4, widget: number, required: false, value_type: int, min: 8, max: 80, hint: '8–80，必须 > 间距 3 且 < 间距 5' }
+      - { label: 间距 5, name: space_5, widget: number, required: false, value_type: int, min: 8, max: 80, hint: '8–80，必须 > 间距 4 且 < 间距 6' }
+      - { label: 间距 6, name: space_6, widget: number, required: false, value_type: int, min: 8, max: 80, hint: '8–80，必须 > 间距 5' }
+      - { label: 段间距, name: flow_p, widget: number, required: false, value_type: float, min: 0, max: 2, step: 0.05, hint: '0–2（em）' }
+      - { label: 标题下间距, name: flow_h2_post, widget: number, required: false, value_type: float, min: 0, max: 2, step: 0.05, hint: '0–2（em）' }
+      - { label: 过渡时长, name: dur, widget: number, required: false, value_type: int, min: 150, max: 600, hint: '150–600（毫秒）' }
+
  # 瞬间：随手发（text/image 至少其一——Sveltia 无法表达条件必填，两者都设可选，
  # 保存前自查；pubDate 必填）。图片走图库媒体库（content/photos 同源可复用）
  - name: moments
@@ -24,6 +89,7 @@ collections:
    create: true
    slug: '{{year}}-{{month}}-{{day}}-{{slug}}'
    summary: '{{fields.pubDate}} · {{fields.text}}'
+    sortable_fields: [pubDate, text]
    fields:
      - { label: 时间, name: pubDate, widget: datetime, date_format: 'YYYY-MM-DD', time_format: false, format: 'YYYY-MM-DD' }
      - { label: 文字, name: text, widget: text, required: false, hint: '一句话（与图片至少填一项）' }
@@ -42,12 +108,15 @@ collections:
    media_folder: ''
    public_folder: ''
    summary: '{{fields.group}} · {{fields.title}}'
+    # 照片无 frontmatter 日期（JSON sidecar，时间在 exif/文件侧）——列表按标题/分组排序
+    sortable_fields: [title, group]
    fields:
      # title 必填：Astro schema z.string() 无 .optional()，omit 纪律下必需且有值才会落键（空 title 会让 main 不可构建）
      - { label: 标题, name: title, widget: string, required: true }
      - { label: 图片, name: image, widget: image }
      - { label: 分组, name: group, widget: select, options: [street, landscape] }
      - { label: 替代文本, name: alt, widget: string, required: false }
+      - { label: 人为描述, name: caption, widget: text, required: false, hint: 展示在灯箱里的人为描述（一句话策展文案） }
      - label: EXIF 覆盖（一般留空，构建期自动从图提取）
        name: exif
        widget: object
@@ -58,3 +127,463 @@ collections:
          - { label: 光圈值, name: fNumber, widget: number, required: false }
          - { label: 曝光秒, name: exposureTime, widget: number, required: false }
          - { label: ISO, name: iso, widget: number, required: false }
+
+  # 页面文案单例（cms 车道 A）：三个文件型入口，保存即写 content/site/*.yaml，
+  # 字段与 Astro siteHome/siteAbout/siteOpenSource 的 schema 一一对应（zh/en 双字段，留空回落默认）
+  - name: site_pages
+    label: 页面文案
+    files:
+      - name: home
+        label: 主页设置
+        file: content/site/home.yaml
+        # 头像上传落 content/site/assets/，yaml 写 ./assets/xxx（Astro 图片管线优化）
+        media_folder: content/site/assets
+        public_folder: ./assets
+        fields:
+          - label: 身份语
+            name: tagline
+          - label: 页面排版覆盖（可选）
+            name: typography
+            widget: object
+            required: false
+            hint: 本页正文默认字体 / 强调色 / 字号缩放（0.8–1.25）；不填用全站默认，只影响本页
+            fields:
+              - label: 正文字体类
+                name: font
+                widget: select
+                required: false
+                options: [font-serif, font-kai, font-sans, font-mono, font-song, font-kai-sys, font-hei-sys, font-fangsong, font-huiwen, font-kuaile]
+              - label: 强调色类
+                name: accent
+                widget: select
+                required: false
+                options: [ink-accent, ink-accent-soft, c-blue, c-blue-soft, c-teal, c-teal-soft, c-green, c-green-soft, c-yellow, c-yellow-soft, c-orange, c-orange-soft, c-red, c-red-soft, c-pink, c-pink-soft, c-purple, c-purple-soft]
+              - { label: 字号缩放, name: scale, widget: number, required: false, value_type: float, min: 0.8, max: 1.25, step: 0.05 }
+            widget: object
+            fields:
+              - { label: 中文, name: zh, widget: string, required: false }
+              - { label: 英文, name: en, widget: string, required: false }
+          - label: 公告（可选，markdown）
+            name: announcement
+            widget: object
+            required: false
+            hint: 渲染在名片区下方；留空则不显示公告块
+            fields:
+              - { label: 中文, name: zh, widget: markdown, required: false }
+              - { label: 英文, name: en, widget: markdown, required: false }
+          - { label: 项目墙条数, name: projectsLimit, widget: number, required: false, value_type: int, min: 1, max: 99, hint: '首页项目墙显示几条（1–99，缺省 6）' }
+          - label: 轨细分开关（首页文章列表）
+            name: postsTracks
+            widget: object
+            required: false
+            hint: 关掉某轨则该轨文章不在首页列出（全开=现状）
+            fields:
+              - { label: 阅读轨, name: reading, widget: boolean, required: false, default: true }
+              - { label: 技术轨, name: tech, widget: boolean, required: false, default: true }
+              - { label: 照片轨, name: photo, widget: boolean, required: false, default: true }
+          - label: 副标题（可选，markdown 短文本）
+            name: subtitle
+            widget: object
+            hint: 渲染在身份语下方；留空不渲染
+            fields:
+              - { label: 中文, name: zh, widget: string, required: false }
+              - { label: 英文, name: en, widget: string, required: false }
+          - label: 最新影像张数
+            name: latestPhotos
+            widget: number
+            required: false
+            default: 4
+            min: 0
+            max: 6
+            hint: '1-6；填 0 = 隐藏「最新影像」区块。留空默认 4'
+          - label: 首页每轨文章条数
+            name: perTrackLimit
+            widget: number
+            required: false
+            default: 6
+            min: 4
+            max: 8
+            hint: 阅读轨/技术轨各显示条数，留空默认 6
+          - label: 区块开关
+            name: sections
+            widget: object
+            required: false
+            hint: 关掉的区块不渲染（默认全开）
+            fields:
+              - { label: 文章列表, name: tracks, widget: boolean, required: false, default: true }
+              - { label: 最新影像, name: photos, widget: boolean, required: false, default: true }
+              - { label: 贡献热力图, name: heatmap, widget: boolean, required: false, default: true }
+              - { label: 项目墙, name: projects, widget: boolean, required: false, default: true }
+          - label: 头像（可选）
+            name: avatar
+            widget: image
+            required: false
+            hint: '留空 = 内置渐变占位；上传后自动优化为 60px WebP'
+          - label: 站点图标 favicon
+            name: favicon
+            widget: string
+            required: false
+            hint: 'public 下的路径，如 /icons/my.ico 或 /icons/my.svg；留空回退 /favicon.svg。经「图标」媒体库上传'
+          - label: 社交链接（顺序即展示顺序）
+            name: socials
+            widget: list
+            required: false
+            summary: '{{fields.label}} → {{fields.url}}'
+            fields:
+              - { label: 名称（无障碍文字）, name: label, widget: string }
+              - { label: 链接, name: url, widget: string }
+              - label: 图标
+                name: icon
+                widget: select
+                required: false
+                options: [github, rss, email, bilibili, x]
+                hint: '不在列表里的留空 → 显示纯文字按钮'
+      - name: about
+        label: 关于页
+        file: content/site/about.yaml
+        # 块内图片上传落 content/site/assets/，yaml 写 ./assets/xxx（Astro 图片管线）
+        media_folder: content/site/assets
+        public_folder: ./assets
+        fields:
+          - label: 页面块（拖拽排序；每块可折叠）
+            name: blocks
+            widget: list
+            typeKey: type
+            required: false
+            summary: '{{fields.type}}'
+            hint: '点「+ 添加」选块型。关掉某块用该块内的「显示」开关'
+            types:
+              - label: 正文（markdown）
+                name: prose
+                widget: object
+                fields:
+                  - { label: 显示, name: enabled, widget: boolean, required: false, default: true }
+                  - label: 小标题（可选）
+                    name: title
+                    widget: object
+                    required: false
+                    fields:
+                      - { label: 中文, name: zh, widget: string, required: false }
+                      - { label: 英文, name: en, widget: string, required: false }
+                  - label: 正文（markdown）
+                    name: body
+                    widget: object
+                    fields:
+                      - { label: 中文, name: zh, widget: markdown, required: false }
+                      - { label: 英文, name: en, widget: markdown, required: false }
+                  - label: 宽度
+                    name: width
+                    widget: select
+                    required: false
+                    default: narrow
+                    options: [{ label: 版心宽度, value: narrow }, { label: 通栏, value: full }]
+              - label: 版图（图标+名称+描述）
+                name: tracks
+                widget: object
+                fields:
+                  - { label: 显示, name: enabled, widget: boolean, required: false, default: true }
+                  - label: 标题
+                    name: title
+                    widget: object
+                    fields:
+                      - { label: 中文, name: zh, widget: string, required: false }
+                      - { label: 英文, name: en, widget: string, required: false }
+                  - label: 条目
+                    name: items
+                    widget: list
+                    summary: '{{fields.name.zh}}'
+                    fields:
+                      - label: 图标
+                        name: icon
+                        widget: select
+                        required: false
+                        options: [book, terminal, camera, code, git, rss, email, github, bilibili, x, star, link]
+                        hint: 白名单外或留空 → 显示首字占位
+                      - label: 名称
+                        name: name
+                        widget: object
+                        fields:
+                          - { label: 中文, name: zh, widget: string, required: false }
+                          - { label: 英文, name: en, widget: string, required: false }
+                      - label: 描述
+                        name: desc
+                        widget: object
+                        required: false
+                        fields:
+                          - { label: 中文, name: zh, widget: text, required: false }
+                          - { label: 英文, name: en, widget: text, required: false }
+              - label: 卡片（2/3 列）
+                name: cards
+                widget: object
+                fields:
+                  - { label: 显示, name: enabled, widget: boolean, required: false, default: true }
+                  - label: 标题（可选）
+                    name: title
+                    widget: object
+                    required: false
+                    fields:
+                      - { label: 中文, name: zh, widget: string, required: false }
+                      - { label: 英文, name: en, widget: string, required: false }
+                  - { label: 列数, name: columns, widget: number, required: false, default: 3, min: 2, max: 3, value_type: int }
+                  - label: 卡片条目
+                    name: items
+                    widget: list
+                    summary: '{{fields.title.zh}}'
+                    fields:
+                      - label: 标题
+                        name: title
+                        widget: object
+                        fields:
+                          - { label: 中文, name: zh, widget: string, required: false }
+                          - { label: 英文, name: en, widget: string, required: false }
+                      - label: 描述
+                        name: desc
+                        widget: object
+                        required: false
+                        fields:
+                          - { label: 中文, name: zh, widget: text, required: false }
+                          - { label: 英文, name: en, widget: text, required: false }
+                      - { label: 链接（可选）, name: href, widget: string, required: false }
+                      - label: 角标（可选）
+                        name: tag
+                        widget: object
+                        required: false
+                        fields:
+                          - { label: 中文, name: zh, widget: string, required: false }
+                          - { label: 英文, name: en, widget: string, required: false }
+              - label: 时间线
+                name: timeline
+                widget: object
+                fields:
+                  - { label: 显示, name: enabled, widget: boolean, required: false, default: true }
+                  - label: 标题（可选）
+                    name: title
+                    widget: object
+                    required: false
+                    fields:
+                      - { label: 中文, name: zh, widget: string, required: false }
+                      - { label: 英文, name: en, widget: string, required: false }
+                  - label: 条目
+                    name: items
+                    widget: list
+                    summary: '{{fields.time}} · {{fields.title.zh}}'
+                    fields:
+                      - { label: 时间, name: time, widget: string, hint: '自由文本，如 2024 — 2026' }
+                      - label: 标题
+                        name: title
+                        widget: object
+                        fields:
+                          - { label: 中文, name: zh, widget: string, required: false }
+                          - { label: 英文, name: en, widget: string, required: false }
+                      - label: 描述（可选）
+                        name: desc
+                        widget: object
+                        required: false
+                        fields:
+                          - { label: 中文, name: zh, widget: text, required: false }
+                          - { label: 英文, name: en, widget: text, required: false }
+              - label: 引文
+                name: quote
+                widget: object
+                fields:
+                  - { label: 显示, name: enabled, widget: boolean, required: false, default: true }
+                  - label: 引文
+                    name: text
+                    widget: object
+                    fields:
+                      - { label: 中文, name: zh, widget: text, required: false }
+                      - { label: 英文, name: en, widget: text, required: false }
+                  - label: 出处（可选）
+                    name: cite
+                    widget: object
+                    required: false
+                    fields:
+                      - { label: 中文, name: zh, widget: string, required: false }
+                      - { label: 英文, name: en, widget: string, required: false }
+              - label: 图片
+                name: figure
+                widget: object
+                fields:
+                  - { label: 显示, name: enabled, widget: boolean, required: false, default: true }
+                  - { label: 图片（必填，请用后台上传）, name: image, widget: image, hint: '禁止填外链：只能上传（落 content/site/assets/），走 Astro 图片管线' }
+                  - { label: 替代文本（无障碍）, name: alt, widget: string, required: false }
+                  - label: 图注（可选）
+                    name: caption
+                    widget: object
+                    required: false
+                    fields:
+                      - { label: 中文, name: zh, widget: string, required: false }
+                      - { label: 英文, name: en, widget: string, required: false }
+              - label: 链接清单
+                name: linklist
+                widget: object
+                fields:
+                  - { label: 显示, name: enabled, widget: boolean, required: false, default: true }
+                  - label: 标题（可选）
+                    name: title
+                    widget: object
+                    required: false
+                    fields:
+                      - { label: 中文, name: zh, widget: string, required: false }
+                      - { label: 英文, name: en, widget: string, required: false }
+                  - label: 链接条目
+                    name: items
+                    widget: list
+                    summary: '{{fields.label.zh}} → {{fields.href}}'
+                    fields:
+                      - label: 名称
+                        name: label
+                        widget: object
+                        fields:
+                          - { label: 中文, name: zh, widget: string, required: false }
+                          - { label: 英文, name: en, widget: string, required: false }
+                      - { label: 链接, name: href, widget: string }
+                      - label: 备注（可选）
+                        name: note
+                        widget: object
+                        required: false
+                        fields:
+                          - { label: 中文, name: zh, widget: string, required: false }
+                          - { label: 英文, name: en, widget: string, required: false }
+              - label: 行动按钮
+                name: cta
+                widget: object
+                fields:
+                  - { label: 显示, name: enabled, widget: boolean, required: false, default: true }
+                  - label: 说明文字
+                    name: text
+                    widget: object
+                    fields:
+                      - { label: 中文, name: zh, widget: string, required: false }
+                      - { label: 英文, name: en, widget: string, required: false }
+                  - { label: 按钮链接, name: href, widget: string }
+                  - label: 按钮文字
+                    name: label
+                    widget: object
+                    fields:
+                      - { label: 中文, name: zh, widget: string, required: false }
+                      - { label: 英文, name: en, widget: string, required: false }
+              - label: 分隔
+                name: divider
+                widget: object
+                fields:
+                  - { label: 显示, name: enabled, widget: boolean, required: false, default: true }
+                  - label: 样式
+                    name: style
+                    widget: select
+                    required: false
+                    default: line
+                    options: [{ label: 细分隔线, value: line }, { label: 纯留白, value: space }]
+          - label: 名片区开关
+            name: layout
+            widget: object
+            required: false
+            hint: 关掉则不显示头像/名字/社交（它们的数据在「主页设置」）
+            fields:
+              - { label: 显示名片区, name: showIdCard, widget: boolean, required: false, default: true }
+          - label: 正文回退（blocks 为空时用，markdown，多段）
+            name: intro
+            widget: object
+            required: false
+            hint: 仅在「页面块」为空时渲染；与块同时存在时以块为准
+            fields:
+              - { label: 中文, name: zh, widget: markdown, required: false }
+              - { label: 英文, name: en, widget: markdown, required: false }
+          - label: 页面排版覆盖（可选）
+            name: typography
+            widget: object
+            required: false
+            hint: 本页正文默认字体 / 强调色 / 字号缩放（0.8–1.25）；不填用全站默认，只影响本页
+            fields:
+              - label: 正文字体类
+                name: font
+                widget: select
+                required: false
+                options: [font-serif, font-kai, font-sans, font-mono, font-song, font-kai-sys, font-hei-sys, font-fangsong, font-huiwen, font-kuaile]
+              - label: 强调色类
+                name: accent
+                widget: select
+                required: false
+                options: [ink-accent, ink-accent-soft, c-blue, c-blue-soft, c-teal, c-teal-soft, c-green, c-green-soft, c-yellow, c-yellow-soft, c-orange, c-orange-soft, c-red, c-red-soft, c-pink, c-pink-soft, c-purple, c-purple-soft]
+              - { label: 字号缩放, name: scale, widget: number, required: false, value_type: float, min: 0.8, max: 1.25, step: 0.05 }
+      - name: opensource
+        label: 开源页
+        file: content/site/opensource.yaml
+        fields:
+          - label: 叙述（链接前）
+            name: blurb
+          - label: 页面排版覆盖（可选）
+            name: typography
+            widget: object
+            required: false
+            hint: 本页正文默认字体 / 强调色 / 字号缩放（0.8–1.25）；不填用全站默认，只影响本页
+            fields:
+              - label: 正文字体类
+                name: font
+                widget: select
+                required: false
+                options: [font-serif, font-kai, font-sans, font-mono, font-song, font-kai-sys, font-hei-sys, font-fangsong, font-huiwen, font-kuaile]
+              - label: 强调色类
+                name: accent
+                widget: select
+                required: false
+                options: [ink-accent, ink-accent-soft, c-blue, c-blue-soft, c-teal, c-teal-soft, c-green, c-green-soft, c-yellow, c-yellow-soft, c-orange, c-orange-soft, c-red, c-red-soft, c-pink, c-pink-soft, c-purple, c-purple-soft]
+              - { label: 字号缩放, name: scale, widget: number, required: false, value_type: float, min: 0.8, max: 1.25, step: 0.05 }
+            widget: object
+            fields:
+              - { label: 中文, name: zh, widget: string, required: false }
+              - { label: 英文, name: en, widget: string, required: false }
+          - { label: 仓库链接地址, name: repo_url, widget: string, required: false }
+          - { label: 仓库链接文字, name: repo_label, widget: string, required: false }
+          - label: 叙述（链接后）
+            name: blurb_after
+            widget: object
+            fields:
+              - { label: 中文, name: zh, widget: text, required: false }
+              - { label: 英文, name: en, widget: text, required: false }
+          - label: 置顶项目（仓库短名，顺序即展示顺序）
+            name: pinned
+            widget: list
+            required: false
+            hint: '如 blog；留空则回落默认 blog。填写的名字须与仓库短名一致'
+          - label: 项目墙模式
+            name: mode
+            widget: select
+            required: false
+            default: all
+            options: [{ label: 全部, value: all }, { label: 仅白名单, value: only }, { label: 排除黑名单, value: exclude }]
+            hint: only/exclude 需配合下面的名单
+          - label: 白名单（仓库短名）
+            name: include
+            widget: list
+            required: false
+            hint: 'mode=仅白名单时生效，如 pi-board'
+          - label: 黑名单（仓库短名）
+            name: exclude
+            widget: list
+            required: false
+            hint: 'mode=排除黑名单时生效，如 blog'
+          - label: 排序
+            name: sort
+            widget: select
+            required: false
+            default: pinned-first
+            options:
+              - { label: 置顶优先，其余按星数, value: pinned-first }
+              - { label: 星数降序, value: stars }
+              - { label: 最近更新, value: updated }
+          - label: 来源过滤
+            name: perSource
+            widget: select
+            required: false
+            default: both
+            options: [{ label: 双源合并, value: both }, { label: 仅 GitHub, value: github }, { label: 仅自托管 gitea, value: gitea }]
+          - label: 开篇文案来源
+            name: intro_from
+            widget: select
+            required: false
+            default: 'off'
+            options:
+              - { label: 用本页叙述（默认）, value: 'off' }
+              - { label: GitHub profile README, value: github-readme }
+            hint: 'github-readme = 构建期取 wait4xx/wait4xx 的 README 渲染为开篇；缓存入仓 content/.github-readme.md，取不到自动回落叙述'
@@ -8,5 +8,8 @@
  <body>
    <!-- pinned 本地 bundle（0.252.0）：官方模板仅此一个 script，无 CSS link、无 type=module -->
    <script src="./sveltia-cms.js"></script>
+    <!-- 可视化排版选择：类清单（单一数据源）→ 编辑器组件注册（须在 CMS 之后、init 之前注册） -->
+    <script src="./typography-classes.js"></script>
+    <script src="./typography-editor.js"></script>
  </body>
 </html>
@@ -0,0 +1,50 @@
+/**
+ * 排版类清单 —— 单一事实源（后台编辑器面板与文档共用）。
+ * 与 src/styles/global.css 的「受限排版类/语义色板」段、src/lib/rehype-class-whitelist.ts 的白名单三处保持一致：
+ * 加类时三处同改，否则构建期白名单会把新类剥掉。
+ *
+ * swatch / family 仅供**后台面板预览**使用（后台无站点 CSS 变量，故给具体值）：
+ * swatch 取亮态值（后台是浅色 UI），family 为该类的真实字体栈。
+ */
+window.TYPOGRAPHY_CLASSES = {
+  font: [
+    { cls: 'font-serif', label: '思源宋（书评正文）', family: '"Noto Serif SC", Georgia, serif', kind: '自托管' },
+    { cls: 'font-kai', label: '霞鹜文楷（金句）', family: '"LXGW WenKai Screen", "Songti SC", serif', kind: '自托管' },
+    { cls: 'font-sans', label: '思源黑（UI/技术）', family: '"Noto Sans SC", system-ui, sans-serif', kind: '自托管' },
+    { cls: 'font-mono', label: 'JetBrains Mono（等宽）', family: '"JetBrains Mono", ui-monospace, monospace', kind: '自托管' },
+    { cls: 'font-song', label: '宋体族', family: '"Noto Serif SC", "Songti SC", SimSun, serif', kind: '自托管优先' },
+    { cls: 'font-kai-sys', label: '楷体族', family: '"LXGW WenKai Screen", "Kaiti SC", STKaiti, serif', kind: '自托管优先' },
+    { cls: 'font-hei-sys', label: '黑体族', family: '"Noto Sans SC", "PingFang SC", "Microsoft YaHei", sans-serif', kind: '自托管优先' },
+    { cls: 'font-fangsong', label: '仿宋族', family: 'FangSong, STFangsong, serif', kind: '系统回退' },
+    { cls: 'font-huiwen', label: '汇文明朝体', family: '"WF-Hwmc", serif', kind: '自托管' },
+    { cls: 'font-kuaile', label: '站酷快乐体', family: '"ZCOOL KuaiLe", serif', kind: '自托管' },
+    { cls: 'font-art-kuaile', label: '快乐体（艺术·仅标题）', family: '"ZCOOL KuaiLe", serif', kind: '艺术字' },
+  ],
+  color: [
+    { cls: 'ink-1', label: '最重（标题级）', swatch: '#111113' },
+    { cls: 'ink-2', label: '正文', swatch: '#33343a' },
+    { cls: 'ink-3', label: '次要（日期/元信息）', swatch: '#6b6e78' },
+    { cls: 'ink-muted', label: '最淡（注释感）', swatch: '#70747c' },
+    { cls: 'ink-warm', label: '暖调正文', swatch: '#3f362e' },
+    { cls: 'ink-cool', label: '冷调正文', swatch: '#2f3742' },
+    { cls: 'ink-faint', label: '最淡可读档', swatch: '#70747c' },
+    { cls: 'ink-accent', label: '强调（链接色）', swatch: '#3454d1' },
+    { cls: 'ink-accent-soft', label: '弱强调', swatch: '#4f66c2' },
+    { cls: 'c-blue', label: '蓝', swatch: '#2456c9' },
+    { cls: 'c-blue-soft', label: '蓝（soft）', swatch: '#4170dd' },
+    { cls: 'c-teal', label: '青', swatch: '#0d7d74' },
+    { cls: 'c-teal-soft', label: '青（soft）', swatch: '#0e847a' },
+    { cls: 'c-green', label: '绿', swatch: '#1f7a3a' },
+    { cls: 'c-green-soft', label: '绿（soft）', swatch: '#22853f' },
+    { cls: 'c-yellow', label: '黄（已压暗）', swatch: '#7a5900' },
+    { cls: 'c-yellow-soft', label: '黄（soft）', swatch: '#926a00' },
+    { cls: 'c-orange', label: '橙', swatch: '#9a4a00' },
+    { cls: 'c-orange-soft', label: '橙（soft）', swatch: '#ba5900' },
+    { cls: 'c-red', label: '红', swatch: '#b32020' },
+    { cls: 'c-red-soft', label: '红（soft）', swatch: '#db3737' },
+    { cls: 'c-pink', label: '粉', swatch: '#a3246a' },
+    { cls: 'c-pink-soft', label: '粉（soft）', swatch: '#ce3386' },
+    { cls: 'c-purple', label: '紫', swatch: '#6a35b8' },
+    { cls: 'c-purple-soft', label: '紫（soft）', swatch: '#8c5ed1' },
+  ],
+};
@@ -0,0 +1,153 @@
+/**
+ * 后台可视化排版选择（Sveltia CMS 自定义编辑器组件）。
+ *
+ * 能力依据（sveltiacms.app/en/docs/api/editor-components，2026-11 核实）：
+ *  - inline 型组件（type:'inline'）在段落内以 pattern 匹配，可与选中文字互转；
+ *  - onInsert({ selectedText }) 拿到编辑器当前选中的文字，返回值经 toInline 生成 Markdown；
+ *  - inline 组件固定在 Insert 菜单下（trigger 对 inline 是文本触发，不能上工具栏）。
+ *
+ * 因此「选中文字 → 套字体/颜色」由**一个「排版」组件 + 自建分组面板**实现：
+ * 两个独立工具栏下拉（字体/颜色）会共用同一 span pattern 互相抢匹配，这里收成一个入口分两组，
+ * 交互上等价（选中 → Insert ▸ 排版 → 选类 → 文字被 <span class> 包住）。
+ * onEdit 支持点开已套用的片段改类。
+ */
+(function () {
+  const CLASSES = window.TYPOGRAPHY_CLASSES;
+  if (!CLASSES || !window.CMS) return;
+
+  /** 自建选择面板：返回 Promise<选中类名 | null>；无依赖、可键盘操作 */
+  function pickClass(current) {
+    return new Promise((resolve) => {
+      const wrap = document.createElement('div');
+      wrap.setAttribute('role', 'dialog');
+      wrap.setAttribute('aria-label', '选择排版');
+      Object.assign(wrap.style, {
+        position: 'fixed', inset: '0', zIndex: '99999', display: 'flex',
+        alignItems: 'center', justifyContent: 'center', background: 'rgba(8,10,14,.55)',
+      });
+      const card = document.createElement('div');
+      Object.assign(card.style, {
+        background: '#fff', color: '#111113', borderRadius: '12px', padding: '18px 20px',
+        width: 'min(560px, 92vw)', maxHeight: '80vh', overflowY: 'auto',
+        boxShadow: '0 8px 32px rgba(0,0,0,.28)', font: '14px/1.5 system-ui, sans-serif',
+      });
+      const title = document.createElement('p');
+      title.textContent = '选择排版（作用于选中文字）';
+      Object.assign(title.style, { margin: '0 0 12px', fontWeight: '600' });
+      card.appendChild(title);
+
+      const buttons = [];
+      const addGroup = (name, list, withSwatch) => {
+        const h = document.createElement('p');
+        h.textContent = name;
+        Object.assign(h.style, { margin: '12px 0 6px', fontSize: '12px', color: '#6b6e78' });
+        card.appendChild(h);
+        const row = document.createElement('div');
+        Object.assign(row.style, { display: 'flex', flexWrap: 'wrap', gap: '8px' });
+        for (const item of list) {
+          const b = document.createElement('button');
+          b.type = 'button';
+          b.dataset.cls = item.cls;
+          b.className = item.cls === current ? 'active' : '';
+          Object.assign(b.style, {
+            display: 'inline-flex', alignItems: 'center', gap: '8px',
+            padding: '6px 12px', borderRadius: '8px', cursor: 'pointer',
+            border: '1px solid ' + (item.cls === current ? '#3454d1' : '#e6e7eb'),
+            background: item.cls === current ? '#eef1fd' : '#fff',
+            color: '#111113', fontSize: '13px',
+          });
+          if (withSwatch) {
+            // 色块预览：直接展示该类在亮态下的实际颜色
+            const chip = document.createElement('span');
+            Object.assign(chip.style, {
+              width: '16px', height: '16px', borderRadius: '4px', flex: 'none',
+              background: item.swatch || '#ccc',
+              border: '1px solid rgba(0,0,0,.12)',
+            });
+            chip.setAttribute('aria-hidden', 'true');
+            b.appendChild(chip);
+          } else {
+            // 字体项：名称 + 用该字体栈渲染的示例字形
+            const sample = document.createElement('span');
+            sample.textContent = '秋海';
+            Object.assign(sample.style, {
+              fontFamily: item.family || 'inherit', fontSize: '15px', lineHeight: '1',
+              padding: '0 4px', borderLeft: '1px solid #e6e7eb', color: '#33343a',
+            });
+            b.appendChild(sample);
+          }
+          const label = document.createElement('span');
+          label.textContent = item.label + (item.kind ? `（${item.kind}）` : '');
+          b.appendChild(label);
+          row.appendChild(b);
+          buttons.push(b);
+        }
+        card.appendChild(row);
+      };
+      addGroup('字体', CLASSES.font, false);
+      addGroup('颜色', CLASSES.color, true);
+
+      const foot = document.createElement('div');
+      Object.assign(foot.style, { marginTop: '16px', display: 'flex', justifyContent: 'flex-end', gap: '8px' });
+      const cancel = document.createElement('button');
+      cancel.type = 'button';
+      cancel.textContent = '取消（Esc）';
+      Object.assign(cancel.style, { padding: '6px 12px', borderRadius: '8px', border: '1px solid #e6e7eb', background: '#fff', cursor: 'pointer' });
+      foot.appendChild(cancel);
+      card.appendChild(foot);
+      wrap.appendChild(card);
+
+      const prevFocus = document.activeElement;
+      const close = (val) => {
+        document.removeEventListener('keydown', onKey, true);
+        wrap.remove();
+        if (prevFocus && prevFocus.focus) prevFocus.focus();
+        resolve(val);
+      };
+      const onKey = (e) => {
+        if (e.key === 'Escape') {
+          e.preventDefault();
+          close(null);
+        } else if (e.key === 'Tab') {
+          // 焦点循环留在面板内
+          const list = [...wrap.querySelectorAll('button')];
+          const first = list[0], last = list[list.length - 1];
+          if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
+          else if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
+        }
+      };
+      wrap.addEventListener('click', (e) => {
+        const t = e.target;
+        if (t === wrap) return close(null);
+        if (t.dataset && t.dataset.cls) close(t.dataset.cls);
+        if (t === cancel) close(null);
+      });
+      document.addEventListener('keydown', onKey, true);
+      document.body.appendChild(wrap);
+      (buttons[0] || cancel).focus();
+    });
+  }
+
+  window.CMS.registerEditorComponent({
+    id: 'typography',
+    label: '排版（字体/颜色）',
+    icon: 'format_paint',
+    type: 'inline',
+    pattern: /<span class="(?<cls>[a-z0-9-]+)">(?<text>[^<]*?)<\/span>/,
+    toInline: ({ cls = '', text = '' }) => `<span class="${cls}">${text}</span>`,
+    toPreview: ({ cls = '', text = '' }) => {
+      const span = document.createElement('span');
+      span.className = cls;
+      span.textContent = text; // DOM 预览：textContent 天然转义
+      return span;
+    },
+    onInsert: async ({ selectedText = '' }) => {
+      const cls = await pickClass(null);
+      return cls ? { cls, text: selectedText } : null;
+    },
+    onEdit: async ({ data }) => {
+      const cls = await pickClass(data.cls);
+      return cls ? { ...data, cls } : null;
+    },
+  });
+})();