blog/.spec/specs/archive/2026-11-03_blog-5j-content-refine/spec.md

Phase 5j：内容表达去重与页面文案可编辑 - 项目范围

1. 问题定义

• 项目目标：①开源页叙述合一（blurb + blurb_after 两个字段夹一个链接的历史包袱，改为单段 markdown 富文本）②贡献数据去重与时效（贡献蛇是静态快照且与热力图重复→删；「连续贡献」非实时→改用热力图同一份 GraphQL 数据本地计算并标注更新时间）③瞬间页与书架页「标题下的话语」从硬编码改为后台可编辑，且字号/颜色/字体可调 ④关于页探索更自由的编辑方式（3–5 个方案供用户选）
• 目标用户：站长（少记字段、能改每页的说明文字与样式）与读者（不看到重复、不看到过期数据）
• 核心价值：把「为历史实现留下的人工约束」（字段拆两半、静态快照当实时数据）清掉，同时让页面文案回到后台手里

2. 假设与待确认

2.1 已确认事实

• content/site/opensource.yaml 的 blurb / blurb_after 只为把 repo_url 链接夹在中间（GithubProfile.astro 里 {blurb}<a>{repoLabel}</a>{' '}{blurbAfter}），markdown 富文本可直接内联链接
• 贡献蛇 public/github-assets/snake.svg 是 GitHub Action 每日生成的静态 SVG 快照（抓取时已剥掉动画）；Heatmap.astro 展示的是同一份 GitHub 贡献数据 → 信息重复
• streak.svg（当前/最长连续贡献）同为构建期抓取的快照，public/github-assets/manifest.json 记录抓取时间，构建不跑不更新
• src/lib/heatmap.ts 已能用 token 拉 contributionsCollection.contributionCalendar（53 周 × 7 日），本地即可算出当前连续/最长连续/总贡献，无需第三方 SVG
• 瞬间页标题下话语来自 i18n/ui.ts 的 moments_note；书架页来自 BooksPage.astro 里的字面量 L.note → 均不可后台编辑

2.2 关键假设

• 用热力图数据本地算连续贡献，与 GitHub 页面口径可能有 ±1 天差异（跨时区/当天未计），需在界面上标注「数据更新于 X（构建期）」
• 关于页改为单字段 markdown 富文本后，现有 blocks 能力仍保留为可选（blocks 非空优先渲染）

2.3 待确认问题

• 关于页形态：→ 已拆分为独立包 2026-11-03_blog-5k-about-designs（含纯 markdown 直编在内的 5 案预览，供用户选型）
• 连续贡献：采用「构建期计算 + 更新时间标注」（与热力图同源，不引入定时任务；如将来需要每日刷新再立项）

2.4 可选解释与取舍

• 旧字段保留为兼容回落（story 为空时仍拼 blurb + 链接 + blurb_after），避免后台旧值突然消失
• 页面文案排版只开放三档（字号/颜色 token/字体类），不开放任意 CSS

2.5 已证伪路径

• 继续用 streak.svg：无法实时、暗色需滤镜、与热力图数据源重复 → 弃

3. 功能范围

3.1 核心功能（MVP）

• T1 开源页叙述合一：story 单字段 markdown（内联链接），旧 blurb/blurb_after 作为兼容回落
• T2 贡献数据去重与时效：删除贡献蛇块与抓取；连续贡献改为热力图同源本地计算（当前/最长/总计）+ 数据时间标注
• T3 页面文案可编辑：新增 content/site/pages.yaml 单例（瞬间/书架 note 双语 + 字号/颜色/字体），两页消费，后台可改
• T4 关于页形态探索 → 拆分为独立包 2026-11-03_blog-5k-about-designs（2026-11-04 重划：关于页是内容选型决策，需用户在预览页里选，与本包工程主线不同节奏，独立成包避免阻塞上线）
• T5 文档与后台 hint 同步

3.2 扩展功能（已决策）

• 连续贡献每日刷新：本包不做（标注「数据更新于」已满足知情）；将来如需要，另行立项 systemd timer

3.3 不在范围内

• 换 GitHub 数据源、Artalk/灯箱改造、书架与开源页版式重做

4. 最小实现路径

• 最简可行：story 先做兼容（新字段空则走旧逻辑）；连续贡献先用现有 heatmap 数据算三个数；页面文案先只开放「文本 + 字号 + 颜色 + 字体」四项
• 暂不引入：页面文案的可视化编辑器、关于页拖拽布局
• 不做的抽象：通用「页面文案样式」DSL（只开放字号/颜色/字体三档白名单）

5. 技术决策

• 技术栈：Astro 7.4.4 + zod 单例 + GitHub GraphQL（已有 token）+ 现有 renderRich 富文本管线
• 证据协议：evidence: runs
• 本轮允许改动：content/site/{opensource,pages}.yaml、src/content.config.ts、src/lib/{site-content,heatmap,projects}.ts、src/components/geek/{GithubProfile,Heatmap}.astro、src/components/pages/{MomentsPage,BooksPage,AboutPage}.astro、src/pages/{about,en/about,about-preview}.astro（新）、public/admin/config.yml、public/github-assets/（删蛇）、scripts/build-perf/fetch-readme-assets.mjs、docs/*、tests/e2e.mjs
• 本轮不应触碰：构建发布链主干、Artalk、灯箱、字体切片
• Git integration branch：spec/2026-11-03_blog-5j-content-refine

5.1 验证策略

• 范围级别：package
• 变更对象：开源页文案模型与贡献数据、页面文案单例、关于页渲染通道
• 快速检查：pnpm astro build + python3 scripts/build-perf/config-check.py .
• 集成检查：E2E_BASE=… node tests/e2e.mjs（55 项）+ content-lint 0/0/0
• 全项目检查：生产实测四条（开源页无蛇、连续贡献与 GitHub 页面对账、页面文案改动生效、关于页预览 5 案可达）；升级条件——仅当改动触及 BaseLayout/全局样式/Artalk 接管层时升级为全站视觉复核，本包均未触及，适用外
• 升级触发：若改动触及 BaseLayout、全局样式或 Artalk 接管层，升级为全站视觉复核；本包因新增页面级排版变量，需一轮关于页预览视觉复核

6. 成功标准与验证方式

• 开源页叙述为单段富文本且可内联链接，旧 yaml 零回归 -> verify: task_0001
• 贡献蛇消失、连续贡献由本地计算并显示更新时间 -> verify: task_0002
• 瞬间/书架标题下话语可从后台改，字号/颜色/字体生效 -> verify: task_0003
• 关于页形态探索拆分为独立包 5k，不阻塞本包 -> （重划说明，无独立验证）
• 文档与后台 hint 同步（无过时字段说明） -> verify: task_0005

7. 风险与约束

• 灰阶外壳红线不变；页面文案排版只开放白名单三档
• 连续贡献口径与 GitHub 可能有 ±1 天差异 → 必须标注更新时间，禁止宣称实时
• 删除贡献蛇要同步删抓取逻辑与 build.sh 守卫，避免死代码
• 多车道并行：GithubProfile/Heatmap（贡献数据）与 MomentsPage/BooksPage（页面文案）分属不同车道；admin config 与 docs 由 orchestrator 统一改