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

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

No files matched your search

@@ -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 -> 缓解措施
@@ -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`(替换为本项目真实集成验证命令)
---
**当前进度**:由脚本计算,无需手动维护
@@ -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`
---
**当前进度**:由脚本计算,无需手动维护
+4 -2
View File
@@ -9,8 +9,10 @@ interface Props {
/** 调用方已完成 draft 过滤与 pubDate 倒序 */ /** 调用方已完成 draft 过滤与 pubDate 倒序 */
posts: CollectionEntry<'posts'>[]; posts: CollectionEntry<'posts'>[];
locale?: 'zh' | 'en'; locale?: 'zh' | 'en';
/** slug → 译题(en 列表显示英文标题,视觉复核范围外观察) */
titleOverrides?: Record<string, string>;
} }
const { posts, locale = 'zh' } = Astro.props; const { posts, locale = 'zh', titleOverrides } = Astro.props;
// 轨道标签走字典(en 首页复用本组件时的双语位);zh 保持原词表语义 // 轨道标签走字典(en 首页复用本组件时的双语位);zh 保持原词表语义
const TRACK_LABEL: Record<PostCategory, string> = { const TRACK_LABEL: Record<PostCategory, string> = {
reading: t('category_reading', locale), reading: t('category_reading', locale),
@@ -52,7 +54,7 @@ const mmdd = (d: Date) =>
aria-hidden="true" aria-hidden="true"
/> />
)} )}
<span class="row-title">{post.data.title}</span> <span class="row-title">{titleOverrides?.[post.id] ?? post.data.title}</span>
{cat !== 'reading' && {cat !== 'reading' &&
post.data.tags.map((tag) => <code class="tag">{`#${tag}`}</code>)} post.data.tags.map((tag) => <code class="tag">{`#${tag}`}</code>)}
<time class="row-date" datetime={post.data.pubDate.toISOString()}> <time class="row-date" datetime={post.data.pubDate.toISOString()}>
+5 -1
View File
@@ -12,6 +12,10 @@ import { t } from '../../i18n/ui';
const posts = (await getCollection('posts', ({ data }) => !data.draft)).sort( const posts = (await getCollection('posts', ({ data }) => !data.draft)).sort(
(a, b) => b.data.pubDate.getTime() - a.data.pubDate.getTime(), (a, b) => b.data.pubDate.getTime() - a.data.pubDate.getTime(),
); );
// 列表标题吃 postsEn 译题(缺译回退 zh,与 /en/archives 同策略)
const enTitle = Object.fromEntries(
(await getCollection('postsEn')).map((e) => [e.id, e.data.title]),
);
const photos = (await getCollection('photos')).slice(0, 4); const photos = (await getCollection('photos')).slice(0, 4);
--- ---
@@ -65,7 +69,7 @@ const photos = (await getCollection('photos')).slice(0, 4);
</div> </div>
</IdCard> </IdCard>
<PostList {posts} locale="en" /> <PostList {posts} locale="en" titleOverrides={enTitle} />
<section class="latest" aria-label={t('latest_photos', 'en')}> <section class="latest" aria-label={t('latest_photos', 'en')}>
<div class="latest-head"> <div class="latest-head">