# Phase 5h：内容表达能力与社交反馈 - 项目范围

<!-- spec-format: 2 -->

## 1. 问题定义
- **项目目标**：①文章支持置顶（作者指定优先）②瞬间的文字与文章同级表达力（字体可换、颜色可换、多段落/列表/强调）③瞬间每条可独立评论 ④浏览量与评论数用统一的「眼睛/气泡」计数徽标呈现（对齐开源页 GitHub 档案的眼图标语汇）⑤开源页开篇从 GitHub README 直接移植导致：`<div align="center">` 内联对齐失效、shields/vercel/snake/komarev 等外链图在慢网下空白破版、README 的「About Me」与开源页主题无关——重构为原生组件并从 README 解耦 ⑥关于页承接读完 README 后仍想保留的个人叙述 ⑦新增一篇「写作模板」示例文章，把可用排版能力一次演示完
- **目标用户**：站长（写得更自由，少打字面 HTML）、读者（读到更丰富且不破版的页）
- **核心价值**：内容表达力与后台编辑力对上，同时把外链依赖与版式事故面砍掉；社交反馈（浏览/评论）在灰阶体系内可量化可见

## 2. 假设与待确认

### 2.1 已确认事实
- Artalk v2 匿名可读：`GET /artalk/api/v2/comments?site_name=…&page_key=…&limit=1` 返回 `{count, roots_count, page:{pv}}`（生产实测，2026-11-02）；`POST /artalk/api/v2/pages/pv` 返回 `{pv}`（现有组件在用）
- 富文本管线已存在且已净化：`renderRich`（markdown + rehype-content-sanitize 标签/属性/协议三层白名单）与 `rehype-class-whitelist`（35 项排版类，单一事实源 `public/admin/typography-classes.js`）
- 现有 6 自托管字族（含 font-huiwen 子集化 420KB 单页）与 16 彩色语义类 + 4 灰阶语义类
- 开源页 README 现由 `intro_from: "off"` 关闭，缓存文件 `content/.github-readme.md`（3138B）含 6 类外链图（readme-typing-svg / shields.io / github-readme-stats / streak-stats / activity-graph / snake / komarev）
- 首页/归档/书架三处列表排序均为 `pubDate` 降序，无置顶概念（`grep pinned` 只命中开源页仓库白名单）

### 2.2 关键假设
- 瞬间富文本走与全站文案同一条净化管线即可满足「字体/颜色可换」且不引入 XSS 面（危险标签整棵丢弃、协议白名单 http/https/mailto）
- 每条瞬间一个 Artalk page_key（`/moments/#<slug>`）不会与页面级 pv 冲突；Artalk 实例按需挂载（展开才 init）可避免 "one page one Artalk" 的全局实例冲突
- 开源页可用本地数据（已有 repo 元数据 + GitHub GraphQL 拉取）自绘 followers/stars/语言占比，无需任何第三方徽章服务

### 2.3 待确认问题
- [x] 瞬间文字是否允许 HTML 类名（字体/颜色）→ 用户原话「字体可换、颜色可换等」，按富文本管线放行 35 项白名单类
- [x] 开源页要不要与 README 完全一致 → 用户原话「可以自行进行美化，无需完全一致」，按原生组件重构
- [x] About Me 类内容放哪 → 用户原话「有些可以直接移植到关于页面中」，迁到 about.yaml blocks

### 2.4 可选解释与取舍
- 置顶只作用于列表排序与视觉标记，不改 URL / 不改 pubDate 语义（订阅源按时间仍正确）
- 计数徽标一次只拉当前页的 pv（POST 计一次）与评论数（GET 读）；瞬间列表按可视区懒拉，避免 N 次请求把首屏拖慢
- 开源页保留 `intro_from` 开关作为 compat，但默认 off 且文档标注「不推荐」；README 渲染通道不删除（后台仍可切回）

### 2.5 已证伪路径
- 直接渲染 README HTML 并试图用 CSS 修 `align="center"`：内联属性与 sanitize 的交互不可控，且外链图仍会空白破版 → 弃，改原生组件
- 每条瞬间都 init 一个 Artalk 实例常驻：内存与请求成本高、且 Artalk 对多实例的支持未验证 → 改为展开时挂载
- 用第三方徽章服务显示访客数（komarev 等）：外链依赖 + 灰阶体系外颜色 → 弃，用 Artalk pv 自绘

## 3. 功能范围

### 3.1 核心功能（MVP）
- [x] T1 文章置顶：posts/postsEn schema `pinned`、四处列表排序（首页双轨/归档/书架）、视觉标记（灰阶 pin）、后台开关
- [x] T2 瞬间富文本：moments `text` 支持 markdown + 白名单排版类（字体/颜色/强调/多段/列表）、净化管线复用、后台改 markdown 编辑器、旧纯文本零回归
- [x] T3 瞬间逐条评论：每条 moment 独立 page_key 的 Artalk 评论区（折叠、展开时挂载）、评论数联动、双语页共用同一 key
- [x] T4 计数徽标：新增 `ViewMeta` 组件（眼睛图标 = 浏览数、气泡图标 = 评论数），接入文章页/瞬间页/关于页/开源页
- [x] T5 开源页重构：原生 GitHub 档案卡（头像/名字/关注者/星标/语言占比，本地数据自绘）替换 README 外链图；`align` 失效与破图问题消失；README 通道降级为可选
- [x] T6 关于页承接：把 README 的 About Me / Find Me 迁为 about.yaml blocks（prose + linklist），开源页只留开源相关
- [x] T7 写作模板示例：中英双语示例文章，演示标题层级/彩色强调/字族/引用/代码/图/表/链接卡片/折叠，并作为置顶功能的活样本；docs 与后台 hint 同步

### 3.2 扩展功能
- 无

### 3.3 不在范围内
- 评论回复通知/邮件推送、点赞/投票、阅读进度、站点级总访问量统计（Artalk 无匿名聚合端点）

## 4. 最小实现路径
- 最简单可行方案：置顶先用 boolean + 排序键；瞬间富文本直接把 `text` 交给既有 `renderRich`；评论用现有 Artalk 组件克隆一份带折叠的；计数徽标只做 pv + count 两个数
- 暂不引入：置顶权重/多级置顶、瞬间的图片轮播、评论楼中楼定制、开源页的实时 Star 曲线
- 不做的抽象：通用「内容社交层」框架（只服务现有页面）

## 5. 技术决策
- 技术栈：Astro 7.4.4 + zod schema + Artalk v2 HTTP API + GitHub GraphQL（已有 token）
- 证据协议：evidence: runs
- 本轮允许改动：src/content.config.ts、src/components/{PostList,ArtalkComments}.astro、src/components/pages/{HomePage,MomentsPage,BooksPage}.astro、src/components/geek/{ViewMeta,GithubProfile}.astro（新）、src/pages/archives/[...slug].astro、src/pages/en/archives/[...slug].astro、src/pages/{about,opensource,en/about,en/opensource}.astro、src/lib/{projects,site-content,heatmap}.ts、content/site/{about,opensource}.yaml、content/posts/*（新增示例文章）、content/posts-en/*、public/admin/{config.yml,typography-classes.js}、docs/*、tests/e2e.mjs
- 本轮不应触碰：nginx/ESA、灯箱与图库（GalleryPage/PhotoZoom）、Header/Footer 结构、构建链顺序、tokens.css/global.css 基础尺度
- Git integration branch：`spec/2026-11-02_blog-5h-content-social`

### 5.1 验证策略
- 范围级别：package
- 变更对象：内容模型（置顶/瞬间富文本）、渲染组件（计数/评论/档案卡）、后台配置、示例内容
- 快速检查：`pnpm astro build`（node26）+ `python3 scripts/build-perf/config-check.py .`
- 集成检查：`E2E_BASE=http://127.0.0.1:18925 node tests/e2e.mjs`（37 项，本包新增置顶顺序/徽标存在/瞬间富文本断言）+ content-lint 0/0/0
- 全项目检查：生产实测四条（开源页零第三方外链图、瞬间评论可发可见、徽标数值与 Artalk 端点对账一致、关于页承接内容渲染）；**升级条件**——仅当改动触及 BaseLayout/全局样式（tokens/字体栈）或 Artalk 主题接管层时才执行，本包因往 tokens 补 emoji 回退链已触发一次并记录了理由
- 升级触发：若动到 BaseLayout/全局样式或 Artalk 主题接管层，升级为全站视觉复核（glm-5.3-flash:max，≤6 图/轮）

## 6. 成功标准与验证方式
- [x] 置顶文章排在列表首位且带可见标记，取消置顶后恢复时间序 -> verify: task_0001
- [x] 瞬间文字可用字体类与彩色强调，危险标签被净化丢弃，旧纯文本渲染不变 -> verify: task_0002
- [x] 每条瞬间可展开评论区并成功发帖，双语页共用同一评论流 -> verify: task_0003
- [x] 文章/瞬间/关于/开源四页显示「浏览数 + 评论数」徽标且数值与 Artalk 一致 -> verify: task_0004
- [x] 开源页零第三方图片请求，档案卡数据来自本地/GraphQL，居中与破图问题不再出现 -> verify: task_0005
- [x] README 的个人叙述出现在关于页，开源页只保留开源相关内容 -> verify: task_0006
- [x] 示例文章渲染全部演示能力且构建通过，docs/hint 同步 -> verify: task_0007

## 7. 风险与约束
- 灰阶外壳红线不变：徽标图标与数字用 tokens（`--ink-*`/`--line`），不引入第三方彩色徽章
- 彩色仅正文强调（≤3 处/页）——示例文章本身要守纪律，成为正面样本而非反例
- 瞬间富文本必须复用 `renderRich` 净化链，禁止新增 set:html 直通路径
- Artalk 多实例风险：评论区折叠 + 展开挂载，若实测冲突则退回「逐条跳转到锚点页」
- 双语链路：所有新文案走 `t()`/`pickBi`，en 轨不得出现中文硬编码
- 多车道并行：content.config.ts / public/admin/config.yml 由 orchestrator 先落契约再放行，车道只改各自 boundary 内文件