wait4x/blog
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
a868bf94fd94ce6ab3ad4ad5d5d1ed61b0b46f28
blog/.spec/specs/archive/2026-11-02_blog-5h-content-social/spec.md
T
wait4xandGLM-5.3 fef2de1d37 chore(spec): 归档 blog-5h——七任务收敛 
Spec: 2026-11-02_blog-5h-content-social

Co-authored-by: GLM-5.3
2026-11-02 21:16:42 +08:00

9.2 KiB
Raw Blame History

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

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 待确认问题

  • 瞬间文字是否允许 HTML 类名（字体/颜色）→ 用户原话「字体可换、颜色可换等」，按富文本管线放行 35 项白名单类
  • 开源页要不要与 README 完全一致 → 用户原话「可以自行进行美化，无需完全一致」，按原生组件重构
  • 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）

  • T1 文章置顶：posts/postsEn schema pinned、四处列表排序（首页双轨/归档/书架）、视觉标记（灰阶 pin）、后台开关
  • T2 瞬间富文本：moments text 支持 markdown + 白名单排版类（字体/颜色/强调/多段/列表）、净化管线复用、后台改 markdown 编辑器、旧纯文本零回归
  • T3 瞬间逐条评论：每条 moment 独立 page_key 的 Artalk 评论区（折叠、展开时挂载）、评论数联动、双语页共用同一 key
  • T4 计数徽标：新增 ViewMeta 组件（眼睛图标 = 浏览数、气泡图标 = 评论数），接入文章页/瞬间页/关于页/开源页
  • T5 开源页重构：原生 GitHub 档案卡（头像/名字/关注者/星标/语言占比，本地数据自绘）替换 README 外链图；align 失效与破图问题消失；README 通道降级为可选
  • T6 关于页承接：把 README 的 About Me / Find Me 迁为 about.yaml blocks（prose + linklist），开源页只留开源相关
  • 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. 成功标准与验证方式

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