wait4x/blog
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
Spec: 2026-10-25_fix-site-polish

Co-authored-by: GLM-5.3
This commit is contained in:
wait4xandGLM-5.3 committed 2026-10-25 11:30:40 +08:00
1 parent 86e8009f34
commit 59b7baae51
8 files changed
+221 -92
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

.spec/specs/2026-10-25_fix-site-polish/spec.md
-63
View File
@@ -1,63 +0,0 @@
# 上线四缺陷修复 + E2E 全功能测试与视觉复核 - 项目范围
<!-- spec-format: 2 -->
## 1. 问题定义
- **项目目标**：一句话描述项目要解决什么问题
- **目标用户**：谁会使用这个产品或系统
- **核心价值**：完成后能持续提供什么价值
## 2. 假设与待确认
### 2.1 已确认事实
- 事实 A
### 2.2 关键假设
- 假设 A
### 2.3 待确认问题
- [ ] 问题 A
### 2.4 可选解释与取舍
- 当前选择：xxx -> 理由
### 2.5 已证伪路径
- 无（暂无证伪记录；条目写：方案概述 + 证伪依据出处 + 日期）
## 3. 功能范围
### 3.1 核心功能（MVP）
- [ ] 功能 A：描述
### 3.2 扩展功能
- 无
### 3.3 不在范围内
- 明确列出本轮不做的内容
## 4. 最小实现路径
- 最简单可行方案：xxx
- 暂不引入：xxx
- 不做的抽象/配置化：xxx
## 5. 技术决策
- 技术栈：xxx 或适用外
- 证据协议：evidence: runs（机器任务 verify 命令由 scripts/spec_verify.py run 真实执行并记录 runs.jsonl；无命令任务写 `verify: manual: <理由>`；verify 命令不得自引用本包 check 门禁）
- 本轮允许改动：xxx
- 本轮不应触碰：xxx
- Git integration branch：`spec/2026-10-25_fix-site-polish`
### 5.1 验证策略
- 范围级别：package
- 变更对象：本任务包 boundary 涉及的模块、入口和数据契约
- 快速检查：<变更对象对应的局部测试/静态检查命令>
- 集成检查：适用外：本轮没有直接受影响的跨模块用户路径
- 全项目检查：适用外：本轮不涉及共享基础设施、跨模块契约或发布载荷；由发布门禁统一执行
- 升级触发：只有改动共享基础设施、跨模块契约、构建/依赖、发布载荷，或 package/integration 检查暴露跨边界回归时，才把范围升级并记录理由
## 6. 成功标准与验证方式
- [ ] 标准 A 达成 -> verify: task_0001
- [ ] 标准 B 达成 -> verify: task_0002
## 7. 风险与约束
- 风险点：xxx -> 缓解措施
.spec/specs/2026-10-25_fix-site-polish/tasks.md
-26
View File
@@ -1,26 +0,0 @@
# 上线四缺陷修复 + E2E 全功能测试与视觉复核 - 任务拆解
## 使用规则
- 每个任务都要写清楚 `boundary` 和 `verify`；机器任务的 verify 以首个反引号 span 为执行的命令
- 如果一个任务没有验证方式，就不能开始；确无命令可执行的任务写 `verify: manual: <理由>`
- 发现的可执行问题必须回写本包，并在本轮做完
- 新任务包使用 `YYYY-MM-DD_<verb>-<object>`，详见 `references/naming-and-commits.md`
- verify 命令不得自引用本包 check 门禁（自指命令在「最近一条」语义下不可满足）
- 多会话/多 agent 共享时，任务可选加一行 `claim: <认领者> <ISO 时间>` 声明在做者；纯信息约定，非锁、无机器键、不进门禁，勾选即失效，归档保留
## 阶段一：实现
- [ ] 初始化最小项目骨架
- boundary: 只创建必须目录、依赖和启动骨架
- verify: `python3 -m pytest -q tests/test_skeleton.py`（替换为本项目真实初始化验证命令）
- [ ] 实现核心功能 A 的最小闭环
- depends-on: task_0001
- boundary: 只改该功能主链路所需模块
- verify: `python3 -m pytest -q tests/test_core_feature_a.py`（替换为本项目真实测试命令）
- [ ] 打通关键链路
- depends-on: task_0002
- boundary: 只补集成所需粘合代码，不顺手重构
- verify: `python3 -m pytest -q tests/test_critical_path.py`（替换为本项目真实集成验证命令）
---
**当前进度**：由脚本计算，无需手动维护
.spec/specs/archive/2026-10-25_fix-site-polish/completion-summary.md
+92
View File
@@ -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
}
```
.spec/specs/archive/2026-10-25_fix-site-polish/runs.jsonl
+6
View File
@@ -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"}
.spec/specs/archive/2026-10-25_fix-site-polish/spec.md
+72
View File
@@ -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 需上线后同源实测
.spec/specs/archive/2026-10-25_fix-site-polish/tasks.md
+42
View File
@@ -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`
---
**当前进度**：由脚本计算，无需手动维护