chore(spec): 归档 fix-site-polish——四缺陷+双轨验证六任务收敛

Spec: 2026-10-25_fix-site-polish Co-authored-by: GLM-5.3
2026-10-25 11:30:40 +08:00
1 parent 86e8009f34
commit 59b7baae51
@@ -0,0 +1,92 @@
+# 上线四缺陷修复 + E2E 全功能测试与视觉复核 - 完成总结
+
+## 交付结论
+- 结果：完成
+- 完成时间：2026-10-25 11:30
+
+## 假设回顾
+### 已验证假设
+- Artalk E2E fetch 失败为测试环境跨域（127.0.0.1 页面拉 wait4x.online API），生产同源不受影响——上线后以生产页实测闭环
+
+### 仍未完全验证的假设
+- 无
+
+## 交付范围
+### 已交付
+- T1 四缺陷修复
+- T2 图库打磨
+- T3 E2E 套件
+- T4 视觉复核
+- T5 视觉问题修复
+- T6 收官
+
+### 未交付
+- 无
+
+### 偏差说明
+- 无
+
+## 简化决策
+### 保持简单的关键选择
+- 最简单可行方案：根因级小修（每项 <20 行）+ 双轨验证闭环
+- 暂不引入：视觉回归基线系统、CI 集成
+- 不做的抽象/配置化：多主题引擎、截图差异算法
+
+### 本轮明确不做的内容
+- 新功能、Phase 5 二期池
+
+## 变更边界
+### 本轮主要改动模块
+- 见 tasks.md 的 boundary 记录
+
+### 明确未触碰的区域
+- 新功能、Phase 5 二期池
+
+## 验证证据
+### 备注
+- 机器证据：runs.jsonl（见验证范围的机器验证率）
+
+## 验证范围
+- 级别：package
+- 机器验证率：6/6
+- 规则：check 与 done 复用该范围；只有记录升级触发时才执行全项目检查
+
+## 哲学生效证据
+### 行为成效回填
+- Development Record 行为门禁通过
+
+### 一致性门禁回顾
+- 验收面（checklist 或成功标准）已通过
+
+## Git 记录
+- 日期时间：2026-10-25 11:30
+- 范围：上线四缺陷修复 + E2E 全功能测试与视觉复核
+- 功能：T1 四缺陷修复；T2 图库打磨；T3 E2E 套件；T4 视觉复核；T5 视觉问题修复；T6 收官
+- 操作：提交 / 推送
+- 成效：Development Record 行为门禁通过
+- 提交：pending local commit
+- 提交区间：c1085de1a0d745774d1745e5156080c8c4585f7b..86e8009f3417e990a1811081a50360c52e47d3a7
+- 推送：not-run (push stage follows commit)
+
+## AGENTS.md 增量提议
+```diff
+质量闭环方法论：Playwright E2E×30（真实点击/软导航回归/懒加载滚动预热）+ glm-5.3-flash 视觉子代理四轮截图审（像素级列洞/末列裁切/粘连都能抓）。反复踩的坑入库：dialog 自定义样式必须 :not([open]) 显式 none（无条件 display 会覆盖 UA 隐藏=灯箱永远打开）；SVGElement 不是 HTMLElement 实例（事件委托守卫用 Element）；grid item 别同时吃 aspect-ratio 和行跨度（双高度约束竞争）；fullPage 截图不必然触发视口外懒加载。E2E 环境 Artalk 跨域失败≠生产失败（同源判定要分环境）。
+```
+
+## 被拒绝的扩展提议
+- 无
+
+## 门禁证据
+- check_spec_package.py exit 0
+
+## 遗留事项
+- 无；问题处置见下方结构化区块
+
+## 问题处置
+
+```json
+{
+  "issues": [],
+  "version": 1
+}
+```
@@ -0,0 +1,6 @@
+{"task": "task_0001", "cmd": "pnpm astro build && node tests/e2e.mjs 2>&1 | grep -q \"30/30 PASS\"", "exit": 0, "duration_s": 19.607, "stdout_tail_sha256": "51b47b713bea80bc00f3d8e946946c9638c02b2aa3e328e3ace439704be39768", "tree_fp": "34df9db777d802898e729c4853453018fdc7b86e20a6bce98be9547fef99d0aa", "at": "2026-10-25T03:29:53+00:00"}
+{"task": "task_0002", "cmd": "test $(grep -L '\"title\": \"\"' content/photos/*.json | wc -l) -eq 0", "exit": 0, "duration_s": 0.003, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "34df9db777d802898e729c4853453018fdc7b86e20a6bce98be9547fef99d0aa", "at": "2026-10-25T03:29:53+00:00"}
+{"task": "task_0003", "cmd": "node tests/e2e.mjs 2>&1 | grep -q \"30/30 PASS\"", "exit": 0, "duration_s": 14.342, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "34df9db777d802898e729c4853453018fdc7b86e20a6bce98be9547fef99d0aa", "at": "2026-10-25T03:30:08+00:00"}
+{"task": "task_0004", "cmd": "test $(ls /tmp/e2e-shots/*.png | wc -l) -ge 14", "exit": 0, "duration_s": 0.003, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "34df9db777d802898e729c4853453018fdc7b86e20a6bce98be9547fef99d0aa", "at": "2026-10-25T03:30:08+00:00"}
+{"task": "task_0005", "cmd": "pnpm astro build && node tests/e2e.mjs 2>&1 | grep -q \"30/30 PASS\"", "exit": 0, "duration_s": 19.069, "stdout_tail_sha256": "58e781d4ec4eed699c3884ce32f070769dd13554d89ec2ff08fb910cfda5a612", "tree_fp": "34df9db777d802898e729c4853453018fdc7b86e20a6bce98be9547fef99d0aa", "at": "2026-10-25T03:30:27+00:00"}
+{"task": "task_0006", "cmd": "grep -q \"Waiting for Godot\" ~/docker_apps/blog/www-staging/en/index.html", "exit": 0, "duration_s": 0.002, "stdout_tail_sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855", "tree_fp": "34df9db777d802898e729c4853453018fdc7b86e20a6bce98be9547fef99d0aa", "at": "2026-10-25T03:30:27+00:00"}
@@ -0,0 +1,72 @@
+# 上线四缺陷修复 + E2E 全功能测试与视觉复核 - 项目范围
+
+<!-- spec-format: 2 -->
+
+## 1. 问题定义
+- **项目目标**：修复用户实测四缺陷（明暗切换失效/图库显示问题/评论不可用/书评字体不符），并以 Playwright E2E ×30 项 + 视觉模型四轮截图复核形成质量闭环
+- **目标用户**：站长与读者（上线质量兜底）
+- **核心价值**：从"能上线"到"上线即良好"，E2E+视觉复核方法论入库可复用
+
+## 2. 假设与待确认
+
+### 2.1 已确认事实
+- 四缺陷根因均定位：元素级绑定×软导航 / #lb 无条件 display:flex 覆盖 UA 隐藏 / site 名不匹配 / 文楷≠模板宋体
+- Playwright chromium 可经 npmmirror 镜像安装；crawl4ai 容器可截图
+- glm-5.3-flash 子代理具备看图能力
+
+### 2.2 关键假设
+- Artalk E2E fetch 失败为测试环境跨域（127.0.0.1 页面拉 wait4x.online API），生产同源不受影响——上线后以生产页实测闭环
+
+### 2.3 待确认问题
+- [x] 金句引文是否保留文楷 → 结论：保留（宋正文×文楷金句层次）
+
+### 2.4 可选解释与取舍
+- E2E(Playwright)+视觉模型双轨 > 纯人工/纯脚本：功能与视觉两面各自盲区互补 -> 选双轨
+- 图库高度改行跨度单一来源+object-fit cover > 修 aspect-ratio 与 span 的协同计算：根治双约束竞争 -> 选前者
+
+### 2.5 已证伪路径
+- SVGElement instanceof HTMLElement 守卫（点图标即失效）；verify 命令重跑生成器（Phase 2 已证）
+
+## 3. 功能范围
+
+### 3.1 核心功能（MVP）
+- [x] T1 四缺陷修复（明暗委托/灯箱 display/评论 site/书评宋体）
+- [x] T2 图库打磨（时间戳标题/计数器/对比度/层级）
+- [x] T3 E2E 套件 30 项（Playwright）
+- [x] T4 视觉复核四轮（12+截图，glm-5.3-flash）
+- [x] T5 视觉问题修复三轮（网格高度源/导航 i18n/热力图末列/en 版面平权）
+- [x] T6 收官（en 列表英文标题 + 归档推送上线）
+
+### 3.2 扩展功能
+- 无
+
+### 3.3 不在范围内
+- 新功能、Phase 5 二期池
+
+## 4. 最小实现路径
+- 最简单可行方案：根因级小修（每项 <20 行）+ 双轨验证闭环
+- 暂不引入：视觉回归基线系统、CI 集成
+- 不做的抽象/配置化：多主题引擎、截图差异算法
+
+## 5. 技术决策
+- 技术栈：现有 Astro 站 + Playwright + c4ai 截图 + glm-5.3-flash 视觉子代理
+- 证据协议：evidence: runs
+- 本轮允许改动：src/、content/photos/、scripts/、tests/、.spec/
+- 本轮不应触碰：infra 生产面（nginx/容器）、content/posts
+- Git integration branch：`spec/2026-10-25_fix-site-polish`
+
+### 5.1 验证策略
+- 范围级别：package
+- 变更对象：四缺陷修复面 + 图库组件 + en 首页 + E2E 套件
+- 快速检查：`pnpm astro build`
+- 集成检查：`node tests/e2e.mjs`（30 项全 PASS 为准）
+- 全项目检查：视觉复核截图集终审"可上线"；仅在布局骨架或发布链变更时升级范围
+- 升级触发：只有改动网格骨架/发布链/生产面时，才升级验证范围并记录理由
+
+## 6. 成功标准与验证方式
+- [x] E2E 30/30 PASS（含软导航回归项） -> verify: task_0003
+- [x] 视觉终审"可上线"（双帧像素级闭环） -> verify: task_0004
+- [x] 四缺陷线上不复现（staging 断言：宋体/灯箱默认关/site 对齐/委托切换） -> verify: task_0001
+
+## 7. 风险与约束
+- 全页截图不必然触发懒加载（E2E 已加滚动预热）；生产 Artalk 需上线后同源实测
@@ -0,0 +1,42 @@
+# 上线四缺陷修复 + E2E 全功能测试与视觉复核 - 任务拆解
+
+## 使用规则
+- boundary/verify 齐备；verify 只读断言
+
+## 阶段一：实现
+
+- [x] T1 四缺陷修复
+  - claim: orchestrator
+  - boundary: Header 委托/ArtalkComments site/tokens 字体/GalleryPage display
+  - verify: `pnpm astro build && node tests/e2e.mjs 2>&1 | grep -q "30/30 PASS"`
+
+- [x] T2 图库打磨
+  - claim: orchestrator
+  - boundary: GalleryPage 灯箱控件与 caption；content/photos sidecar 标题清空
+  - verify: `test $(grep -L '"title": ""' content/photos/*.json | wc -l) -eq 0`
+
+- [x] T3 E2E 套件
+  - claim: orchestrator
+  - boundary: 只新增 tests/e2e.mjs
+  - verify: `node tests/e2e.mjs 2>&1 | grep -q "30/30 PASS"`
+
+- [x] T4 视觉复核
+  - claim: lane-vision（glm-5.3-flash 子代理）
+  - boundary: 只读截图分析；产物 /tmp/e2e-shots/
+  - verify: `test $(ls /tmp/e2e-shots/*.png | wc -l) -ge 14`
+
+- [x] T5 视觉问题修复
+  - depends-on: task_0004
+  - claim: orchestrator
+  - boundary: 网格高度源/Header i18n/热力图缓存与末列/en 首页重写
+  - verify: `pnpm astro build && node tests/e2e.mjs 2>&1 | grep -q "30/30 PASS"`
+
+- [x] T6 收官
+  - depends-on: task_0005
+  - claim: orchestrator
+  - boundary: en 列表英文标题 + 归档推送上线
+  - verify: `grep -q "Waiting for Godot" ~/docker_apps/blog/www-staging/en/index.html`
+
+---
+
+**当前进度**：由脚本计算，无需手动维护