news-site-test 升级计划（去共化）

本文件是跨 session / 跨 agent 的权威计划文档。Opus（架构阶段）、Fable（界面阶段）、以及未来的会话都以此为准。 Claude 的自动记忆（~/.claude/.../memory/）只保留指向本文件的简短指针，实质内容在这里。 配套文件：OPUS_CHECKLIST.md（架构阶段落地清单）。

最后更新：2026-07-03

1. 总体方针

两阶段，结构先于皮肤：

  1. 阶段一 · Opus（架构/结构） —— 见 OPUS_CHECKLIST.md。
  2. 阶段二 · Fable（视觉皮肤） —— 方向 = 精修水墨风：铜金 #8f6a2e + 印章朱红作第二强调色、毛笔字报头、宋体标题、暖宣纸底。只动 token 值与组件皮肤，不动结构与 class 名。

news-site-test 与 JSM（jekyll-sites-manager）强耦合：JSM 管理 taxonomy、文章版本身份、子站协调、以及（本计划新增）主页板块组合。很多”单站看像缺陷”的地方其实是 JSM 的职责，属于契约而非可自由重设计的代码（见 §5）。

2. 关键架构决策

  • 留在 GitHub Pages + 靠 JSM（不迁 GitHub Actions）。动态板块全是客户端读 JSON，无需自定义插件；构建期 taxonomy / 版本去重本就是 JSM 的活。
  • 配置驱动、JSM 管理的主页板块：Jekyll 读 _data/home_blocks.yml 逐块渲染，不把板块写死在模板里。JSM 写这个文件，并把每个子站的 Latest Posts JSON 注册为可选 source；加一个子站 = 首页多一个可放置的板块，模板一行不改。
    • 板块类型：featured-swiper、subsite-feed（变体 focus-list / cards / compact / ticker）、post-list、taxonomy-tags、taxonomy-cats
    • 槽位（slot）：nav / hero-left / hero-right / main-top / main / sidebar / footer
    • 分期：Opus 先建渲染器 + 板块组件 + 手写默认 home_blocks.yml（即 §3）；JSM 的编辑器与 source 注册后做。JSM 未就绪前，首页照常按手写文件跑。
    • Opus ↔ JSM 契约：home_blocks.yml schema（§4.1）+ subsite-feed JSON 形状（§4.2）。
  • EN = 方案 A 先行 / B 后备（2026-07-03 改，原为 B；依据 _bk/CN-EN.txt）：逐篇翻译——中文永远在页面，英文放 assets/i18n/<c_id>.en.json，JS 按需加载、作为副本插到中文块后（不覆盖），CSS 控 中/英/双语 三态（front matter translations.{lang}；正文块带稳定 data-i18n id）。JSM 负责注入稳定 id + 生成 JSON + 对齐 build-check。导航 EN⇄中 = 站点级语言偏好（localStorage + chrome 文案），非跳转；可分享用 ?lang=en。B（独立 EN 页 for SEO）= backlog，届时用同一 JSON 生成（hreflang 那时才有意义）。Formal News/新闻速览 是中文内容（从英语新闻转述翻译而来的中文新闻，非英文），与其他中文子站 feed 同类——要首页英文 feed 需 JSM 逐条翻译。SEO 取舍：英文短期不独立收录。
  • 主题可切换（不写死单一主题）：三层分离 —— 结构 CSS 只引用语义 token（CSS 自定义属性，非 SCSS $ 变量），主题 = 一组 token 值（_sass/themes/_<name>.scss），加主题只加一个文件、结构不改。默认 theme① = 中性 neutral（Fable 配方见 §6），水墨风存为 theme②，二者都落 CSS 变量。<html data-theme="neutral">——用 ui_theme: 而非 Jekyll 保留键 theme:（后者会触发 gem 主题查找、炸构建）。同一机制免费支持以后运行时切换 / 深色模式。Opus 搭契约+机制+两个主题空壳，Fable 填 theme① 的 token 值与组件皮肤。

3. 首页默认组合（板块 v4）

槽位 板块 数据源 说明
nav taxonomy-cats 分类下拉 JSM 10 个分类收进导航 分类 ▾
nav EN ⇄ 中 切换 — 跳转 EN 子站（方案 B）
hero-left featured-swiper 头条 + 精选 自有（置顶 + featured） 手动 swiper，不强制自动播，可单条 / 手动多条
hero-right subsite-feed 焦点头条 子站 JSON top-news.json focus-list 变体
main-top subsite-feed 社媒快讯（上浮） 子站 JSON social-pulse cards 变体，最新 3 条，占主栏宽
main post-list 最新文章 自有 posts/news 列表 + 分页，版本去重取最新版
sidebar subsite-feed 新闻速览 子站 JSON formal-news compact 变体（原「英文速览」，2026-07-03 改名）
sidebar taxonomy-tags 热门标签 JSM 只列热门 N 个 + 「全部标签 →」入口
footer 品牌 + 印章 + 社交 自有  

已撤除：底部「分类带 + 标签带」（分类进导航、标签进侧栏）、空的 sidebar-reserved 占位、swiper 强制自动轮播。

4. 契约 Schema

4.1 _data/home_blocks.yml

- { type: featured-swiper, slot: hero-left,  source: own,                autoplay: false, title: 头条 }
- { type: subsite-feed,    slot: hero-right, source: daily/top-news.json, variant: focus-list, count: 9, title: 焦点头条 }
- { type: subsite-feed,    slot: main-top,   source: social-pulse,        variant: cards,   count: 3, title: 社媒快讯 }
- { type: post-list,       slot: main,       source: own,                 variant: list,    paginate: 6, title: 最新文章 }
- { type: subsite-feed,    slot: sidebar,    source: formal-news,         variant: compact, count: 6, title: 新闻速览 }
- { type: taxonomy-tags,   slot: sidebar,    source: jsm,                 variant: hot+all, count: 12, title: 热门标签 }
- { type: taxonomy-cats,   slot: nav,        source: jsm }

source 可为子站 JSON 的 URL / 相对路径，或子站标识（由 JSM source 注册表解析成 URL）。

4.2 subsite-feed JSON 形状（已核对 JSM latest_posts.py，2026-07-03）

JSM latest_posts.json 每条 item 的实际字段：

[
  {
    "title":     "标题",
    "link":      "https://…",   // 目标链接
    "pubDate":   "2026-07-02…", // 发布时间
    "cover_img": "https://…",   // 封面图（已解析为公开 URL）
    "weight":    10             // 排序权重（默认 sort = weight_desc_date_desc）
  }
]

映射到组件：title→标题、link→href、pubDate→日期、cover_img→图、weight→排序。 JSM 不输出 category / excerpt。

  • focus-list（焦点头条）：title / link（weight 排序）。首条做大标题，其余列表。
  • cards（社媒快讯）：cover_img + title + pubDate。先不放分类（feed 不含 category；要就得扩 JSM 输出）；cover_img 缺失时降级为纯文字卡。
  • compact（新闻速览）：title + link + pubDate。
  • ticker：title + link。

两种 feed 形状：JSM latest_posts.json（上表，含 pubDate/cover_img）与旧 picked top-news.json（仅 title/link/weight）。组件须对缺失字段优雅降级。 JSM 端可配 latest_posts：enabled / output_dir（默认 assets/data）/ filename（默认 latest_posts.json）/ limit（默认 10，上限 100）/ sort；并有手动 overrides 层（title/link/cover_img/weight/include，可人工置顶/编辑，且不被自动重生成覆盖）。

5. 要冻结的 JSM 契约（重写时保持兼容，勿重设计）

面向 JSM 开发的完整对接契约（home_blocks / 子站 feed JSON / i18n block id + 翻译 JSON / taxonomy / 版本身份 / config 键 / 行动清单）见 JSM_CONTRACTS.md。下面是精简冻结清单：

  • Taxonomy：_tag / _category 目录 + front-matter（layout: tagpage/categorypage、tag:/category:、title: "标签: X"）；config 键 tags_dir / categories_dir。
  • 文章身份/版本：c_id / version_of / base_c_id / update_date；版本去重 Liquid 比较 update_date | date: "%Y-%m-%d %H:%M:%S"（JSM 按此格式写时间戳）。
  • URL：url / test_url（JSM v0.31.19 public_url_resolver）。
  • 新增契约：_data/home_blocks.yml（§4.1，含 schema: home-blocks.v1）与 subsite-feed JSON（§4.2）——Opus 定义，JSM 后续照此写入。
  • EN i18n 契约：front matter translations.{lang}: <json-url>；翻译 JSON 于 assets/i18n/<c_id>.<lang>.json；正文块的稳定 data-i18n id（JSM 分配/维护，非位置序号）；JSON blocks 与正文 id 必须对齐（JSM check-script 校验）。

6. 变更 / 决策记录

  • 2026-07-03 初版计划：两阶段（Opus→Fable）、GH Pages+JSM、EN=方案 B、板块 v1→v4 迭代定稿。
  • 2026-07-03 板块 v3：砍 swiper 强制轮播、分类进导航、标签并侧栏、撤底部 taxonomy 带、新增新闻卡片。
  • 2026-07-03 板块 v4：头条+精选合并为手动 swiper；社媒快讯上浮为主栏顶部 3 张卡片（= Social Pulse 最新 3 条）；确立配置驱动 / JSM 管板块架构。
  • 2026-07-03 「英文速览」→「新闻速览」（源仍是 formal-news 子站）。
  • 2026-07-03 主题架构：不写死单一主题，改三层分离（结构 / 语义 token 契约 / 主题值），CSS 自定义属性 + data-theme，为未来多主题 / 深色模式 / 运行时切换留口。
  • 2026-07-03 主题切换 = config 默认选（site.theme），暂不放前台切换按钮（机制预留）。
  • 2026-07-03 核对 JSM latest_posts.json 字段：{title, link, pubDate, cover_img, weight}，有图有日期、无 category/excerpt（社媒卡片先不放分类）。见 §4.2。
  • 2026-07-03 theme① = 中性默认（Fable 配方：暖白 #faf9f7 / 近黑 #1d1c1a / 铜金唯一 accent（与 logo 同源，用于链接 hover·活跃态·kicker）/ 朱红仅头条徽标 / 宋体大标题 + 黑体 UI / 8px 间距刻度·板块间 48–64px / 3:2 图片纪律 object-fit:cover / 文字对比 ≥4.5:1）；精修水墨风 = theme②。
  • 2026-07-03 EN 方案 B→A 先行 / B 后备（依据 _bk/CN-EN.txt 的 ChatGPT 设计）：JSON+JS 逐篇翻译、中文原文保留、英文副本插入、中/英/双语三态。双语对照是 B 给不了的差异化功能；A/B 是先后而非二选一。补强：block id 必须稳定非位置式、正文↔JSON 对齐 build-check、block 模型待定、?lang=en 代替 hreflang。SEO：英文短期不独立收录（待 B）。
  • 2026-07-03 接受 Fable 审查全部要点：theme:→ui_theme:、Sass 3.7.4 只能 @import、feed 三态+CLS 骨架、分页页 first_page_only、home_blocks 加 schema 版本+未知类型跳过+block id、feed 协议校验(+escapeHtml)、permalink 尾斜杠保持原样。见清单 H 段。
  • 2026-07-03 预览后用户定板（config-driven 首页）：右侧 sidebar 竖条专用于”子站板块栈”——每加子站 = 一个 slot: sidebar 的 subsite-feed 块从上往下叠；count 控条目多寡（子站少→count 大/长列表，子站多→多块各 count 小）。将来 JSM 写 home_blocks.yml。社媒快讯只在 main-top（最新文章上方）；焦点头条留 hero。热门标签不进右侧栏（右侧栏留给子站），改留底部带；分类进导航下拉。
  • 2026-07-03 / 更正 2026-07-04 报头字体：原 汉呈水墨中国风（assets/fonts/HC-subset.woff2）是当前识别；Fable 若有更契合”专业精致”的显示字体可换（勿用 mock 的 Ma Shan Zheng 替身）。方向更正：不是”照片优先/让照片提供颜色”（早先过度解读），就是喜欢干净、专业、精致的风格本身。宋体标题/配色浓淡等细节 Fable 阶段精修。
  • 2026-07-03 确认 中文 SEO 优先、英文不追求收录 → EN 方案 A 冻结（B 长期 backlog）。方案 A 天然契合：中文是真实 HTML、英文 JS 注入，搜索引擎只见中文（比 B 更利于中文收录）。据此收紧 SEO 项：_config.yml description 改中文、加 lang: zh_CN、sitemap/canonical 统一到规范域、?lang=en 变体 rel=canonical 回干净中文 URL、单一 <title>。