From ce41c800ba61d6ff2f4fc670b314bd8be0c5cf41 Mon Sep 17 00:00:00 2001 From: wait4xx Date: Sat, 24 Oct 2026 23:00:20 +0800 Subject: [PATCH] =?UTF-8?q?chore(spec):=20=E5=88=9B=E5=BB=BA=20add-blog-sk?= =?UTF-8?q?eleton=20=E4=BB=BB=E5=8A=A1=E5=8C=85=EF=BC=88Phase=201=20?= =?UTF-8?q?=E5=8D=81=E4=BB=BB=E5=8A=A1=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Spec: 2026-10-24_add-blog-skeleton --- .../2026-10-24_add-blog-skeleton/spec.md | 83 +++++++++++++++++++ .../2026-10-24_add-blog-skeleton/tasks.md | 69 +++++++++++++++ 2 files changed, 152 insertions(+) create mode 100644 .spec/specs/2026-10-24_add-blog-skeleton/spec.md create mode 100644 .spec/specs/2026-10-24_add-blog-skeleton/tasks.md diff --git a/.spec/specs/2026-10-24_add-blog-skeleton/spec.md b/.spec/specs/2026-10-24_add-blog-skeleton/spec.md new file mode 100644 index 0000000..9f18543 --- /dev/null +++ b/.spec/specs/2026-10-24_add-blog-skeleton/spec.md @@ -0,0 +1,83 @@ +# Phase 1：Astro 骨架+设计系统+五页型+极客层 P0 - 项目范围 + + + +## 1. 问题定义 +- **项目目标**：在 Astro 5 上实现博客前端全骨架——设计 tokens、自托管分片字体、三轨内容集合、五类页面、明暗模式、极客层 P0、搜索/RSS，可在 staging 演练部署 +- **目标用户**：站长（Phase 2 迁入真实内容即可上线） +- **核心价值**：丙路线「灰阶骨架×分轨正文」从样板变成可构建可部署的真实代码 + +## 2. 假设与待确认 + +### 2.1 已确认事实 +- Node v22.22.3 + pnpm 11.3.0 可用；remote origin = https://git.wait4x.online/wait4x/blog.git（Phase 0 已推 main） +- 设计规格全部定稿（docs/博客重设计调研报告.md v1.8 §2 丙路线/§3 排版参数/§4c 极客层/§4e 多端） +- 样板参考 design/mockup.html（v2，1050 行，三属性驱动：route/scheme/page） +- 预字体包：lxgw-wenkai-screen-webfont / @fontsource/noto-sans-sc / @fontsource/jetbrains-mono（npm 预分片自托管，替代 cn-font-split 构建步） + +### 2.2 关键假设 +- 上述 npm 预分片字体包的 unicode-range 切片质量满足按需加载（若不满足，回退 vite-plugin-font 方案） +- 样例内容（等待戈多等）可先行入库 content/，Phase 2 再被真实迁移覆盖 + +### 2.3 待确认问题 +- [x] Lighthouse 移动端 ≥90 需真实域名（Phase 4 预发布验收执行；本包只做结构自查）→ 结论：按此执行 + +### 2.4 可选解释与取舍 +- 预分片 npm 字体包 > cn-font-split 构建：零构建工具、社区维护切片、同样自托管；代价是包体切片策略不可定制 → 接受 +- 样例内容先行 > 空集合：页面开发需要真实排版观感（书评长文/代码块/照片比例）→ 接受 + +### 2.5 已证伪路径 +- 无 + +## 3. 功能范围 + +### 3.1 核心功能（MVP） +- [ ] T1 Astro 5 初始化（pnpm+TS strict） +- [ ] T2 设计 tokens + 全局样式（丙路线参数） +- [ ] T3 自托管分片字体三轨接入 +- [ ] T4 内容集合（posts/moments/photos + EXIF loader） +- [ ] T5 布局/导航/页脚/明暗不闪烁 +- [ ] T6 五页型（首页/文章双模板/图库/瞬间/关于） +- [ ] T7 极客层 P0（键盘+帮助/build-info/View Transitions/项目墙） +- [ ] T8 Artalk 占位 + Pagefind + RSS + sitemap +- [ ] T9 响应式结构自查（§4e 断点全覆盖） +- [ ] T10 staging 部署演练（build.sh 填实） + +### 3.2 扩展功能 +- 书评索引画廊页、/now·/stack·/colophon（Phase 4+ 二期） + +### 3.3 不在范围内 +- 真实内容迁移（Phase 2）、双语管线（Phase 3）、上线切换与 Lighthouse 实测（Phase 4）、Halo 退役（Phase 5） + +## 4. 最小实现路径 +- 单 Astro 项目根目录 src/{layouts,components,pages,styles,content}，无多余工作区 +- 暂不引入：React/Vue 框架、tailwind（原生 CSS + tokens 足够且更快）、CMS 适配层 +- 项目墙构建时 fetch 失败用仓内缓存 JSON 兜底（src/data/projects-fallback.json） + +## 5. 技术决策 +- 技术栈：Astro 5 + 原生 TS/CSS；包管理 pnpm +- 证据协议：evidence: runs（verify 由 spec_verify 真实执行） +- 本轮允许改动：仓库 src/、public/、package.json、pnpm-lock.yaml、astro.config.*、tsconfig.json、content/、infra/deploy/build.sh、.spec/ +- 本轮不应触碰：infra/{gitea,artalk}/、~/docker_apps/ 运行实例、nginx、生产 Halo +- Git integration branch：`spec/2026-10-24_add-blog-skeleton` + +### 5.1 验证策略 +- 范围级别：package +- 变更对象：src/ 全部源码、content/ 样例集合、public/ 静态资产、构建配置、build.sh +- 快速检查：`pnpm astro build`（全包 verify 的基座命令） +- 集成检查：dist/ 路由产物断言（五页型 HTML 存在、字体分片计数、pagefind/rss/sitemap 产出） +- 全项目检查：staging 部署演练 + rollback-dryrun 仍绿；仅在 src 构建链/部署脚本/共享基础设施变更时升级范围重跑 +- 升级触发：只有改动构建链（astro/字体/搜索集成）、build.sh 或暴露公网入口时，才升级验证范围并记录理由 + +## 6. 成功标准与验证方式 +- [ ] `pnpm astro build` exit 0 且零框架 JS 依赖（仅原生脚本） -> verify: task_0001 +- [ ] 五页型路由 HTML 全部生成于 dist/ -> verify: task_0006 +- [ ] 字体分片自托管产出（woff2 切片 >50 个文件） -> verify: task_0003 +- [ ] 极客层 P0 标记齐全（键盘脚本/帮助浮层/built-from/ClientRouter/项目墙区块） -> verify: task_0007 +- [ ] Pagefind 索引 + rss.xml + sitemap 产出 -> verify: task_0008 +- [ ] staging 目录更新 + 回滚干跑仍绿 -> verify: task_0010 + +## 7. 风险与约束 +- 预分片字体包若含 latin-only 假冒 CJK 切片 → 构建后抽查切片数与体积 -> 验证步覆盖 +- exifr 对样例占位图无 EXIF → loader 需容错空值 -> schema 可选字段 +- View Transitions 三引擎兼容（caniuse 已核）→ 降级 CSS 直切，无破坏 diff --git a/.spec/specs/2026-10-24_add-blog-skeleton/tasks.md b/.spec/specs/2026-10-24_add-blog-skeleton/tasks.md new file mode 100644 index 0000000..5019867 --- /dev/null +++ b/.spec/specs/2026-10-24_add-blog-skeleton/tasks.md @@ -0,0 +1,69 @@ +# Phase 1：Astro 骨架+设计系统+五页型+极客层 P0 - 任务拆解 + +## 使用规则 +- 每个任务都要写清楚 `boundary` 和 `verify`；机器任务的 verify 以首个反引号 span 为执行的命令 +- verify 命令不得自引用本包 check 门禁 +- 多 agent 协作：任务可加 `claim:` 行（信息约定）；子代理车道须先 mesh_reserve 各自路径 + +## 阶段一：实现 + +- [ ] T1 Astro 5 项目初始化（pnpm + TS strict + minimal） + - claim: orchestrator + - boundary: 只新建 package.json/pnpm-lock/astro.config.mjs/tsconfig.json/src/pages/index 占位；不装 UI 框架 + - verify: `pnpm astro build` + +- [ ] T2 设计 tokens 与全局样式（丙路线） + - depends-on: task_0001 + - claim: orchestrator + - boundary: 只写 src/styles/{tokens.css,global.css}；变量命名与 docs/博客重设计调研报告.md §3 参数一一对应 + - verify: `pnpm astro build && test -f dist/index.html` + +- [ ] T3 字体三轨自托管分片（文楷/思源黑/JBMono） + - depends-on: task_0002 + - boundary: 只加字体 npm 依赖与 src/styles/fonts.css 引入；不引入 cn-font-split 构建步（预分片包方案，证伪则回退并记 2.5） + - verify: `pnpm astro build && test $(find dist -name "*.woff2" | wc -l) -gt 50` + +- [ ] T4 内容集合与 EXIF loader（posts/moments/photos） + - depends-on: task_0001 + - claim: lane-content（子代理，预留 src/content 与 src/lib） + - boundary: 只写 src/content/config.ts、src/lib/{exif.ts,collections 辅助}、content/ 样例（书评/技术/瞬间各 1+、照片 3 张占位图含两种比例）；EXIF 空值容错 + - verify: `pnpm astro build` + +- [ ] T5 布局/导航/页脚/明暗不闪烁 + - depends-on: task_0002 + - claim: orchestrator + - boundary: 只写 src/layouts/BaseLayout.astro 与 src/components/{Header,Footer,ThemeScript}.astro；导航 ≤4 项；页脚 ICP+built-from 槽位；inline 防闪烁脚本 + - verify: `pnpm astro build && grep -q "陕ICP备2026014860号" dist/index.html` + +- [ ] T6 五页型（首页/文章双模板/图库/瞬间/关于） + - depends-on: task_0004, task_0005 + - claim: lane-pages（子代理，预留 src/components 与 src/pages 除 index 外路由） + - boundary: 只写页面与页面级组件（名片开场/分轨列表/书评衬线模板+引文组件/技术模板+TOC+进度条/图库 masonry+lightbox/瞬间时间线/关于含身份陈述空槽位）；排版参数按报告 §3 + - verify: `pnpm astro build && test -f dist/archives/deng-dai-ge-duo/index.html -a -f dist/gallery/index.html -a -f dist/moments/index.html -a -f dist/about/index.html` + +- [ ] T7 极客层 P0（键盘+帮助/build-info/View Transitions/项目墙） + - depends-on: task_0005 + - claim: lane-geek（子代理，预留 src/components/geek 与 src/data） + - boundary: 只写 geek 组件（keyboard+? 帮助浮层、built-from 注入 vite define、ClientRouter、项目墙构建时 fetch 双源+缓存兜底 JSON）；不改页面结构 + - verify: `pnpm astro build && grep -q "built from" dist/index.html -i && grep -q "ClientRouter\|view-transition" dist/index.html` + +- [ ] T8 Pagefind + RSS + sitemap + Artalk 占位 + - depends-on: task_0006 + - claim: orchestrator + - boundary: 只加 astro-pagefind/@astrojs-rss/@astrojs-sitemap 集成与文章模板 Artalk 容器组件（无凭据占位）；astro.config 修改限集成段 + - verify: `pnpm astro build && test -d dist/pagefind -a -f dist/rss.xml -a -f dist/sitemap-index.xml` + +- [ ] T9 响应式结构自查（§4e 断点全覆盖） + - depends-on: task_0006 + - boundary: 只做断点/容器查询与触屏属性的静态断言脚本 scripts/check-responsive.sh（1120/820/760/560 四档 + 44px 触点 + safe-area + 100dvh），不改样式本体（缺陷回写对应组件修复） + - verify: `bash scripts/check-responsive.sh` + +- [ ] T10 staging 部署演练（build.sh 填实） + - depends-on: task_0008, task_0009 + - claim: orchestrator + - boundary: 只改 infra/deploy/build.sh 为真实 astro build+rsync；staging 产物断言；不碰 nginx/生产 + - verify: `bash infra/deploy/build.sh && test -f ~/docker_apps/blog/www-staging/index.html && bash infra/deploy/rollback-dryrun.sh` + +--- + +**当前进度**：由脚本计算，无需手动维护