diff --git a/.spec/specs/2026-10-26_blog-5f/spec.md b/.spec/specs/2026-10-26_blog-5f/spec.md new file mode 100644 index 0000000..274ba67 --- /dev/null +++ b/.spec/specs/2026-10-26_blog-5f/spec.md @@ -0,0 +1,87 @@ +# Phase 5f:SEO 解封与功能优化批 + 美化首批 - 项目范围 + + + +## 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) +- [ ] T1 SEO 仓库侧三件:robots.txt 新建 + /admin 局部 noindex 预案 + 用户操作单(nginx/ESA) +- [ ] T2 localePath 双 en 修复 + 自指 canonical + 尾斜杠归一 +- [ ] T3 构建期内容 lint(断链/图片/frontmatter/双语配对)+ 生产冒烟脚本 + build.sh 守卫挂载 +- [ ] T4 reader 纯文本模式(html.reader 单 class + 命令面板 reader + r 键 + localStorage) +- [ ] T5 代码块窗条(P 卡:≥4 行灰阶窗+mono 标题+灰阶三点,单行裸 pill) +- [ ] T6 书评纸面板(Q 卡:圆角米灰纸卡+暗色暖棕+hairline 边框防长文竖线感) +- [ ] T7 版式基底(K/L/O 卡:正文流距 token 化+灰阶补档+暗色 hairline 降档+微交互曲线统一+focus ring 收尾) +- [ ] 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 完成后复测入档);移动溢出密集扫描(美化改动面涉及布局 token 时) +- 升级触发:若 T7 灰阶补档波及 Header/导航布局,升级为全站密集扫描并记录 + +## 6. 成功标准与验证方式 +- [ ] dist 每页含自指 canonical 且 en 页无 /en/en/ -> verify: task_0002 +- [ ] robots.txt 产物存在且含 Sitemap 行 -> verify: task_0001 +- [ ] 人为断链能让 build 输出 FAIL 清单(warn 一周策略首版即 fail 可议) -> verify: task_0003 +- [ ] reader 触发后 .bg-glow 隐藏/ICP 可见/刷新保持 -> verify: task_0004 +- [ ] 多行代码块有窗条与灰阶三点、单行无 -> verify: task_0005 +- [ ] 书评正文为圆角纸卡(computed border-radius+背景) -> verify: task_0006 +- [ ] 流距 token 生效(h2 前后距为变量值)+focus ring 统一 -> verify: task_0007 +- [ ] 首屏 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 动 diff --git a/.spec/specs/2026-10-26_blog-5f/tasks.md b/.spec/specs/2026-10-26_blog-5f/tasks.md new file mode 100644 index 0000000..1dd208c --- /dev/null +++ b/.spec/specs/2026-10-26_blog-5f/tasks.md @@ -0,0 +1,51 @@ +# 任务清单:Phase 5f(SEO 解封与功能优化批 + 美化首批) + +说明:verify 命令均在仓库根执行;车道工作树开发禁 git,收编由 orchestrator 统一提交。 + +- [ ] T1 + - id: task_0001 + - title: SEO 仓库侧三件(robots.txt + admin noindex 预案 + 用户操作单) + - boundary: public/robots.txt(新建)、docs/上线检查单.md(追加操作单节) + - 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 && test -f dist/robots.txt` + +- [ ] T2 + - id: task_0002 + - title: localePath 双 en 修复 + 自指 canonical + 尾斜杠归一 + - boundary: src/lib/locale.ts、src/layouts/BaseLayout.astro(canonical 行)、src/components/Header.astro(nav-lang href 尾斜杠) + - verify: `! grep -r "/en/en/" dist/ && grep -q 'rel="canonical"' dist/en/archives/mian-sha/index.html && node tests/e2e.mjs 2>&1 | grep -q "33/33 PASS"` + +- [ ] T3 + - id: task_0003 + - title: 构建期内容 lint + 生产冒烟 + build.sh 守卫挂载 + - boundary: scripts/build-perf/content-lint.mjs(新)、scripts/build-perf/prod-smoke.sh(新)、infra/deploy/build.sh(守卫行) + - verify: `node scripts/build-perf/content-lint.mjs dist && bash -n infra/deploy/build.sh && test -x scripts/build-perf/prod-smoke.sh` + +- [ ] T4 + - id: task_0004 + - title: reader 纯文本模式(html.reader + 命令面板 + r 键 + 持久化) + - boundary: src/styles/global.css(reader 段)、src/components/CommandPalette.astro、src/components/geek/Keyboard.astro、src/i18n/ui.ts(cmd_reader 键) + - verify: `node tests/e2e.mjs 2>&1 | grep -q "33/33 PASS" && grep -q "reader" src/components/CommandPalette.astro && grep -q "html.reader" src/styles/global.css` + +- [ ] T5 + - id: task_0005 + - title: 代码块窗条(P 卡:≥4 行灰阶窗+mono 标题+灰阶三点) + - boundary: 技术轨正文组件的代码块样式(GalleryPage 之外;具体落点车道自查源码定)+ global.css 如需 + - verify: `node tests/e2e.mjs 2>&1 | grep -q "33/33 PASS" && grep -qE "code-win|codewin" src/styles/global.css src/components/ -r` + +- [ ] T6 + - id: task_0006 + - title: 书评纸面板(Q 卡:圆角米灰纸卡+暗色暖棕+hairline 边框) + - boundary: 书评轨正文容器样式(prose-reading 相关组件/tokens.css 新增 --paper 变量可与 T7 协同由 orchestrator 统一入 tokens) + - verify: `node tests/e2e.mjs 2>&1 | grep -q "33/33 PASS" && grep -qE "paper" src/styles/tokens.css src/styles/global.css -r` + +- [ ] T7 + - id: task_0007 + - title: 版式基底(K/L/O 卡:流距 token+灰阶补档+暗色 hairline 降档+微交互曲线+focus ring) + - boundary: src/styles/tokens.css、src/styles/global.css(本卡为 orchestrator 专属车道,他人不并改动两文件) + - verify: `node tests/e2e.mjs 2>&1 | grep -q "33/33 PASS" && grep -q "flow-h2-pre" src/styles/tokens.css && grep -q "focus-ring\|focus-visible" src/styles/global.css` + +- [ ] T8 + - id: task_0008 + - title: 首屏 tagline + 图库质感(M/N 卡:身份语+圆角统一+暗色 4% 衬底) + - boundary: src/components/IdCard.astro 或首页身份区、src/components/pages/GalleryPage.astro(stage 暗色衬底+radius 统一) + - verify: `node tests/e2e.mjs 2>&1 | grep -q "33/33 PASS" && grep -q "tagline\|身份" src/pages/index.astro src/components/ -r | head -1`