数据层
  ↓
派生层
  ↓
展示层

apps/web/src/data/
  github-overview.emptyinkpot.json
  books.ts
  music.ts
  profile.ts
 
apps/web/src/lib/
  github.ts
  home.ts
  showcase.ts
  analytics.ts
 
apps/web/src/components/
  visualizations/
  showcase/
  home/

index.astro 只负责排版和喂数据
lib/analytics.ts 负责把原始数据转成图表数据
components/visualizations/* 负责画图
components/showcase/* 负责书架、歌曲、账号展示

components/visualizations/
├─ GitHubHeatmap.astro
├─ GitHubLineChart.astro
├─ GitHubLanguageDonut.astro
├─ TeamSignalGraph.astro
├─ RepoMatrix.astro
└─ ChartCard.astro

热力图：自己用 div grid 画，不引库
donut：自己用 conic-gradient 画，不引库
团队图：先用静态节点图，不引库
折线图：可以先 SVG 手写；复杂后再用 Recharts

首页左栏：只放摘要
Feed：放小型图表卡片
/github 页面：放完整仪表盘

首页左栏
- 年度贡献数
- 当前主语言
- 最近活跃仓库
- GitHub / Bilibili / 书架入口
 
Feed 图表卡片
- GitHub 热力图 mini
- 月度更新折线图 mini
- 语言占比 donut mini
- 团队信号 mini
 
/github 详情页
- 完整热力图
- 完整折线图
- 语言饼图
- 仓库矩阵
- 团队图
- 自动化信号

ChartCard.astro
MetricBadge.astro
MiniLegend.astro
Sparkline.astro
EmptyChartState.astro

ChartCard：所有图表统一壳
MetricBadge：显示 total / last updated / active days
MiniLegend：颜色说明
Sparkline：小折线
EmptyChartState：没数据时不要空白

GitHubHeatmap.astro
GitHubMonthlyLine.astro
GitHubLanguageDonut.astro
GitHubRepoMatrix.astro
GitHubDashboardCard.astro

GitHubDashboardCard
  ├─ mini heatmap
  ├─ mini line
  └─ mini donut

TeamSignalGraph.astro
TeamMemberNode.astro
RepoTeamRelationCard.astro

你
├─ repo A
├─ repo B
├─ automation
└─ collaborator / signal

BookshelfCard.astro
BookCover.astro
BookGrid.astro
BookDrawer.astro
ReadingStatusBadge.astro

export const books = [
  {
    id: "ddia",
    title: "Designing Data-Intensive Applications",
    author: "Martin Kleppmann",
    cover: "/images/books/ddia.jpg",
    status: "reading",
    rating: 5,
    tags: ["distributed-system", "database"],
    note: "分布式系统基础书。",
  },
];

apps/web/public/images/books/

MusicCard.astro
AlbumCover.astro
PlaylistGrid.astro
NowPlayingCard.astro
MusicDrawer.astro

export const songs = [
  {
    id: "song-id",
    title: "歌曲名",
    artist: "歌手",
    album: "专辑",
    cover: "/images/music/album.jpg",
    platform: "netease" | "spotify" | "bilibili" | "local",
    href: "https://...",
    mood: ["night", "writing"],
  },
];

apps/web/public/images/music/

apps/web/src/data/books.ts
apps/web/src/data/music.ts
apps/web/src/data/social.ts
apps/web/src/data/showcase.ts

apps/web/src/content/books/
apps/web/src/content/music/
apps/web/src/content/shelf/

post | note | project | book | github | bilibili | update

type FeedItem =
  | { type: "post"; drawerId: string }
  | { type: "note"; drawerId: string }
  | { type: "project"; drawerId: string }
  | { type: "book"; id: string }
  | { type: "music"; id: string }
  | { type: "github"; variant: "repo" | "heatmap" | "line" | "language" | "team" }
  | { type: "bilibili"; href: string }
  | { type: "update"; href: string };

/github/
  完整 GitHub 仪表盘
 
/books/
  完整书架
 
/music/
  歌曲 / 歌单 / 专辑墙
 
/social/
  GitHub / Bilibili / 其他账号聚合

首页 = 展示流
/github = GitHub 数据详情
/books = 书架详情
/music = 音乐详情
/posts/[slug] = 文章完整阅读
右侧 drawer = 快速阅读模式

P0：8 个
- ChartCard
- GitHubHeatmap
- GitHubLanguageDonut
- GitHubMonthlyLine
- BookshelfCard
- BookCover
- MusicCard
- AlbumCover
 
P1：6 个
- GitHubDashboardCard
- GitHubRepoMatrix
- TeamSignalGraph
- BookGrid
- PlaylistGrid
- ShowcaseDrawer
 
P2：4+ 个
- GitHubFullDashboard
- BookshelfPageSection
- MusicPageSection
- SocialProfilePanel

首页：
- 左栏显示 GitHub 总贡献、书架入口、音乐入口、Bilibili 入口
- Feed 混排文章、书籍、歌曲、GitHub 小图表
- 点击文章开右侧 drawer
- 点击书籍/歌曲开小 drawer 或跳详情页
 
/github：
- 展开热力图、折线图、语言 donut、仓库矩阵、团队图

Astro（静态 + 少量交互）
+ CSS columns 瀑布流
+ 原生 JS drawer

Content OS UI（内容操作系统界面）

当前问题：
- drawer 状态分散
- filter 状态是 DOM 级
- 没有统一 store

组件 = UI块

模式 = 行为 + 状态 + UI

Drawer Pattern
Feed Pattern
Dashboard Pattern

heatmap / donut / line / team

零散组件 ❌

Analytics System ✔

Astro（外壳）
+ React Island（交互层）
+ Visualization System（图表层）
+ State Store（状态层）

npx shadcn@latest init

原生 JS ❌ → Radix Dialog ✔

npm i zustand

个人项目 + UI状态多 + 不复杂业务逻辑

import { create } from "zustand";
 
export const useUIStore = create((set) => ({
  activePost: null,
  filter: "all",
  isDrawerOpen: false,
 
  openPost: (post) =>
    set({ activePost: post, isDrawerOpen: true }),
 
  closeDrawer: () =>
    set({ isDrawerOpen: false }),
 
  setFilter: (filter) =>
    set({ filter }),
}));

npm i recharts
npm i react-force-graph
npm i react-github-calendar

ChartCard（统一壳）✔

grid + columns 混乱
间距不统一
信息碎

→ CSS Grid 主布局
→ Masonry 用 @egjs/react-grid（成熟）

npm i @egjs/react-grid

npm i framer-motion

drawer 滑出
卡片 hover
filter 切换
图表加载

JSON snapshot（github-overview）

GitHub GraphQL API

modules/analytics

Astro (页面)
└── React Island
    ├── Feed
    ├── Drawer
    ├── Charts
    ├── Bookshelf
    └── Music
 
State (Zustand)
└── UIStore
 
Data
├── content collections
├── github snapshot
├── books.ts
└── music.ts
 
Components
├── ui/ (shadcn)
├── charts/
├── feed/
└── showcase/

所有 UI 行为都能解释

用户不迷路

ChartCard 可以装任何图

点击 → 动画 → 状态变化

70% 工程能力 ✔
30% 系统设计 ❌

系统设计 > 框架选择

个人内容平台 / 内容操作系统

一个连续浏览、可快速阅读、可展示个人知识资产和创作信号的个人内容操作系统首页。

Profile Rail
+ Masonry-like Feed
+ Right Article Drawer

┌──────────────────────────────────────────────────────────────┐
│ System Top Bar                                                │
│ 搜索 / 当前状态 / 设置 / 快速入口                              │
├───────────────┬───────────────────────────────┬──────────────┤
│ Profile Rail  │ Main Content Feed             │ Context Dock │
│               │                               │ 可选隐藏      │
│ 个人信息       │ Hero Signal Card              │ 当前筛选      │
│ GitHub摘要     │ Masonry Feed                  │ 当前文章目录  │
│ 书架摘要       │ posts / notes / books / music │ 阅读队列      │
│ 音乐摘要       │ github charts / updates       │              │
│ Bilibili入口   │                               │              │
└───────────────┴───────────────────────────────┴──────────────┘
 
点击文章 / 札记 / 项目：
→ 右侧 Article Drawer 滑出
→ 背景 Feed 保持原位置
→ 点击空白关闭

左栏 280px + 中间 Feed + 右侧 Drawer

L0 Shell Layer
页面骨架、滚动容器、响应式
 
L1 Identity Layer
头像、介绍、GitHub、Bilibili、书架、音乐入口
 
L2 Feed Layer
文章、笔记、项目、书籍、歌曲、GitHub 图表、更新卡片
 
L3 Action / Context Layer
搜索、筛选、阅读抽屉、文章 TOC、复制链接、打开完整页

apps/web/src/pages/
├─ index.astro
├─ github/index.astro
├─ books/index.astro
├─ music/index.astro
└─ social/index.astro
 
apps/web/src/components/home/
├─ HomeShell.astro
├─ HomeTopBar.astro
├─ HomeProfileRail.astro
├─ HomeFeed.astro
├─ HomeFeedToolbar.astro
├─ HomeArticleDrawer.astro
├─ HomeArticleToc.astro
└─ HomeEmptyState.astro
 
apps/web/src/components/feed/
├─ FeedCard.astro
├─ PostFeedCard.astro
├─ NoteFeedCard.astro
├─ ProjectFeedCard.astro
├─ BookFeedCard.astro
├─ MusicFeedCard.astro
├─ GitHubFeedCard.astro
├─ BilibiliFeedCard.astro
└─ UpdateFeedCard.astro
 
apps/web/src/components/charts/
├─ ChartCard.astro
├─ GitHubHeatmap.astro
├─ GitHubMonthlyLine.astro
├─ GitHubLanguageDonut.astro
├─ GitHubRepoMatrix.astro
└─ TeamSignalGraph.astro
 
apps/web/src/components/showcase/
├─ BookCover.astro
├─ BookshelfPreview.astro
├─ MusicPreview.astro
├─ AlbumCover.astro
├─ SocialProfileCard.astro
└─ ExternalAccountCard.astro
 
apps/web/src/lib/
├─ feed.ts
├─ analytics.ts
├─ showcase.ts
├─ github.ts
└─ profile.ts
 
apps/web/src/data/
├─ books.ts
├─ music.ts
├─ socials.ts
└─ github-overview.emptyinkpot.json

index.astro
└─ HomeShell
   ├─ HomeTopBar
   ├─ HomeProfileRail
   │  ├─ ProfileCard
   │  ├─ GitHubMiniStatus
   │  ├─ BookshelfPreview
   │  ├─ MusicPreview
   │  └─ SocialLinks
   │
   ├─ HomeFeed
   │  ├─ HomeFeedToolbar
   │  ├─ HeroSignalCard
   │  ├─ MasonryFeed
   │  │  ├─ PostFeedCard
   │  │  ├─ NoteFeedCard
   │  │  ├─ ProjectFeedCard
   │  │  ├─ BookFeedCard
   │  │  ├─ MusicFeedCard
   │  │  ├─ GitHubFeedCard
   │  │  ├─ BilibiliFeedCard
   │  │  └─ UpdateFeedCard
   │
   └─ HomeArticleDrawer
      ├─ DrawerHeader
      ├─ ArticleMeta
      ├─ HomeArticleToc
      └─ ArticleBody

export type FeedItem =
  | {
      type: "post";
      id: string;
      title: string;
      summary: string;
      date: string;
      tags: string[];
      href: string;
      drawerId: string;
      cover?: string;
      weight?: number;
    }
  | {
      type: "note";
      id: string;
      title: string;
      summary: string;
      date: string;
      tags: string[];
      href: string;
      drawerId: string;
    }
  | {
      type: "project";
      id: string;
      title: string;
      summary: string;
      status: "active" | "paused" | "archived";
      href: string;
      drawerId?: string;
    }
  | {
      type: "book";
      id: string;
      title: string;
      author: string;
      cover: string;
      status: "reading" | "finished" | "planned";
      note?: string;
      href?: string;
    }
  | {
      type: "music";
      id: string;
      title: string;
      artist: string;
      cover?: string;
      platform?: "netease" | "spotify" | "bilibili" | "local";
      href?: string;
      mood?: string[];
    }
  | {
      type: "github";
      id: string;
      variant: "repo" | "heatmap" | "line" | "language" | "team";
      title: string;
      href?: string;
    }
  | {
      type: "bilibili";
      id: string;
      title: string;
      href: string;
      cover?: string;
      summary?: string;
    }
  | {
      type: "update";
      id: string;
      title: string;
      date: string;
      summary: string;
      href: string;
    };

.home-os {
  min-height: 100vh;
  display: grid;
  grid-template-rows: auto minmax(0, 1fr);
}
 
.home-os__topbar {
  position: sticky;
  top: 0;
  z-index: 50;
  backdrop-filter: blur(18px) saturate(1.4);
}
 
.home-os__shell {
  width: min(1520px, 100% - 40px);
  margin: 0 auto;
  display: grid;
  grid-template-columns: 280px minmax(0, 1fr);
  gap: 20px;
  min-height: 0;
}
 
.home-os__rail {
  position: sticky;
  top: 76px;
  align-self: start;
  max-height: calc(100vh - 96px);
  overflow: auto;
}
 
.home-os__main {
  min-width: 0;
  min-height: 0;
  overflow-y: auto;
  padding-bottom: 32px;
}
 
.home-feed-grid {
  column-count: 3;
  column-gap: 16px;
}
 
.home-feed-card {
  display: inline-block;
  width: 100%;
  margin: 0 0 16px;
  break-inside: avoid;
  min-width: 0;
}
 
@media (max-width: 1240px) {
  .home-feed-grid {
    column-count: 2;
  }
}
 
@media (max-width: 900px) {
  .home-os__shell {
    display: block;
    width: min(100% - 24px, 720px);
  }
 
  .home-os__rail {
    position: static;
    max-height: none;
    overflow: visible;
    margin-bottom: 16px;
  }
 
  .home-os__main {
    overflow: visible;
  }
 
  .home-feed-grid {
    column-count: 1;
  }
}

1. 全站搜索
2. Feed 筛选
3. 当前系统状态
4. 设置入口

[MyBlog / Content OS] [Search...] [All Posts Notes Books Music GitHub] [Settings]

输入搜索：实时过滤 Feed
点击分类：只隐藏/显示，不重建 DOM
点击 Settings：进入 /settings/
移动端：搜索折叠为按钮

ProfileCard
- avatar
- name
- tagline
- 当前正在做什么
 
GitHubMiniStatus
- total contributions
- active repos
- top language
- 进入 /github
 
BookshelfPreview
- 最近在读 3 本
- 进入 /books
 
MusicPreview
- 最近喜欢 / 正在听
- 进入 /music
 
SocialLinks
- GitHub
- Bilibili
- RSS
- About

只放摘要，不放完整图表。
完整图表去 /github。
完整书架去 /books。
完整音乐去 /music。

1. Hero Signal Card
2. 最新文章
3. GitHub mini heatmap
4. 书架卡片
5. 项目卡片
6. 音乐卡片
7. 月度折线图
8. 笔记
9. Bilibili 卡片
10. 更新日志

function scoreFeedItem(item: FeedItem) {
  const typeWeight = {
    post: 100,
    note: 82,
    project: 76,
    github: 70,
    book: 64,
    music: 58,
    bilibili: 52,
    update: 48,
  };
 
  return typeWeight[item.type] ?? 0;
}

点击 post / note / project 卡片
→ 阻止默认跳转
→ 打开右侧 drawer
→ 记录触发卡片
→ Feed 滚动位置保持

点击空白
按 Esc
点击关闭按钮
移动端关闭按钮

focus 回到触发卡片
不滚动页面
筛选状态保留

Header
- 关闭
- 打开完整页
- 复制链接
 
Body
- title
- meta
- tags
- TOC
- article body

.home-article-backdrop {
  position: fixed;
  inset: 0;
  z-index: 80;
  background: rgba(15, 15, 20, 0.36);
  backdrop-filter: blur(4px);
}
 
.home-article-drawer {
  position: fixed;
  top: 0;
  right: 0;
  z-index: 90;
  width: min(760px, 100vw);
  height: 100vh;
  display: grid;
  grid-template-rows: auto minmax(0, 1fr);
}
 
.home-article-drawer__body {
  overflow-y: auto;
  padding: 24px;
}
 
.home-article-reader {
  display: grid;
  grid-template-columns: 180px minmax(0, 1fr);
  gap: 24px;
}
 
.home-article-toc {
  position: sticky;
  top: 20px;
  align-self: start;
  max-height: calc(100vh - 120px);
  overflow: auto;
}
 
@media (max-width: 760px) {
  .home-article-drawer {
    width: 100vw;
  }
 
  .home-article-reader {
    display: block;
  }
 
  .home-article-toc {
    position: static;
    max-height: none;
    margin-bottom: 20px;
  }
}

ChartCard
├─ title
├─ description
├─ primary metric
├─ chart body
├─ legend
└─ action link

展示长期活跃度

最近 12 周 mini heatmap

全年 heatmap + 月份标签 + 总贡献数

GitHubHeatmap.astro

展示月度提交 / 发布 / 更新趋势

mini sparkline

完整坐标轴 + 月份 + tooltip

GitHubMonthlyLine.astro
ContentPublishLine.astro

展示 GitHub language distribution
或者内容类型占比：posts / notes / projects / books / music

GitHubLanguageDonut.astro
ContentTypeDonut.astro

展示你、仓库、自动化、协作信号之间的关系

emptyinkpot
├─ MyBlog
├─ OpenClaw
├─ AI Writer
├─ Publish Pipeline
└─ Automation

TeamSignalGraph.astro

export type BookItem = {
  id: string;
  title: string;
  author: string;
  cover: string;
  status: "reading" | "finished" | "planned";
  rating?: number;
  tags?: string[];
  note?: string;
  href?: string;
};

BookFeedCard
- 封面
- 书名
- 作者
- 状态
- 一句话笔记

Books Page
├─ Reading Now
├─ Finished
├─ Planned
├─ Tags
└─ Book Grid

apps/web/public/images/books/

export type MusicItem = {
  id: string;
  title: string;
  artist: string;
  album?: string;
  cover?: string;
  platform: "netease" | "spotify" | "bilibili" | "local";
  href?: string;
  mood?: string[];
  note?: string;
};

MusicFeedCard
- 专辑封面
- 歌名
- artist
- mood 标签
- 外链

Music Page
├─ Now Playing / 最近喜欢
├─ Playlists
├─ Albums
├─ Mood Tags
└─ Song Grid

apps/web/public/images/music/

BilibiliFeedCard.astro
BilibiliProfileCard.astro

configured：展示主页、视频、简介
empty：显示“待配置 Bilibili 主页”
error：显示“暂时无法加载”

loading
empty
error
ready

type ViewState = "loading" | "empty" | "error" | "ready";

loading：skeleton
empty：解释为什么空
error：显示可恢复操作
ready：正常展示

All
Writing
Projects
Books
Music
GitHub
Bilibili
Updates

const filterMap = {
  all: ["post", "note", "project", "book", "music", "github", "bilibili", "update"],
  writing: ["post", "note"],
  projects: ["project"],
  books: ["book"],
  music: ["music"],
  github: ["github"],
  bilibili: ["bilibili"],
  updates: ["update"],
};

筛选只改变可见性，不重建 Feed。
筛选不重置 scrollTop。
筛选后如果无结果，显示 EmptyState。

1. Drawer slide in/out
2. Feed card hover lift
3. Filter fade/scale

不要大面积视差
不要让 hover 改变卡片尺寸
不要为了动效改变布局流
不要给图表加过度复杂动画

HomeShell.astro
HomeTopBar.astro
HomeProfileRail.astro
HomeFeed.astro
HomeFeedToolbar.astro
HomeArticleDrawer.astro
PostFeedCard.astro
BookFeedCard.astro
MusicFeedCard.astro
GitHubFeedCard.astro
ChartCard.astro
GitHubHeatmap.astro

左栏身份展示
瀑布流 Feed
文章 Drawer
书架卡片
音乐卡片
GitHub mini 图表
筛选不重置滚动
移动端可用

GitHubMonthlyLine.astro
GitHubLanguageDonut.astro
GitHubRepoMatrix.astro
TeamSignalGraph.astro
BookshelfPreview.astro
MusicPreview.astro
/github/index.astro
/books/index.astro
/music/index.astro

GitHub 仪表盘恢复
书架有完整页面
音乐有完整页面
首页不臃肿

SearchOverlay.astro
ContentTypeDonut.astro
RelatedContentRail.astro
ReadingQueue.astro
ShowcaseDrawer.astro
SocialProfilePage.astro

首页接近完整 Content OS
具备搜索、关系、阅读队列、完整社交展示

我先看到这个人是谁、最近在做什么。
然后我可以一直往下滑，看文章、项目、书、音乐、GitHub 活跃度。
看到文章不用跳走，点开右侧抽屉就能读。
读完点空白回到原位置。
想深入看 GitHub / 书架 / 音乐，可以进独立详情页。
整个首页像一个人的内容系统，而不是一堆博客模块。

1. 首页只保留一个主 Feed。
2. 文章阅读走 Drawer，不强制跳页。
3. 图表统一走 ChartCard。
4. 书架、音乐、GitHub 都是 FeedItem。
5. 左栏只放摘要，详情页放完整内容。
6. 筛选不重建 DOM，不重置滚动。
7. 不再恢复旧的多模块堆叠首页。

你从“组件设计” → 进入“隐喻设计（metaphor design）”

标签 = UI元素

书签 = 现实世界的物件

一本书里插着不同颜色的书签

✔ 从卡片“顶部插进去”
✔ 有一个“露出部分”
✔ 有颜色区分
✔ 有形状（不是纯矩形）
✔ 有轻微不对称（更真实）

<div class="card">
  <div class="bookmark bookmark--post">
    <span>POST</span>
  </div>
 
  <h2>标题</h2>
  <p>摘要...</p>
</div>

“从卡片里面伸出来”

.bookmark {
  position: absolute;
  top: -6px;
  left: 16px;
 
  padding: 6px 10px 8px;
  font-size: 11px;
  letter-spacing: 0.12em;
 
  font-family: var(--font-ui);
  text-transform: uppercase;
 
  background: var(--bookmark-color);
  color: #fff;
 
  border-radius: 2px;
 
  clip-path: polygon(
    0 0,
    100% 0,
    100% 100%,
    50% 85%,
    0 100%
  );
}

模拟“书签底部折角”

.card {
  position: relative;
  overflow: visible;
}

.bookmark {
  box-shadow: 0 2px 4px rgba(0,0,0,0.08);
}

.bookmark--post {
  --bookmark-color: #6B2D5C; /* 清华紫 */
}
 
.bookmark--project {
  --bookmark-color: #2F5D50; /* 高级绿 */
}
 
.bookmark--book {
  --bookmark-color: #9E2A2B; /* 高级红 */
}
 
.bookmark--music {
  --bookmark-color: #C9A227; /* 王室黄 */
}
 
.bookmark--github {
  --bookmark-color: #3A3A3A;
}

.bookmark {
  transform: rotate(-1.5deg);
}

element.style.transform = `rotate(${Math.random() * 2 - 1}deg)`

从 UI → 手工感

.bookmark--post {
  padding-right: 14px;
}
 
.bookmark--book {
  padding-right: 18px;
}

.bookmark::before {
  content: "";
  position: absolute;
  top: 0;
  left: 0;
  right: 0;
  height: 2px;
  background: rgba(0,0,0,0.15);
}

纸张压住的阴影

书签颜色 = 标题颜色

.card--post h2 {
  color: #6B2D5C;
}
 
.card--project h2 {
  color: #2F5D50;
}

视觉识别 = 秒级完成

<div class="bookmark bookmark--post"></div>
<div class="bookmark bookmark--highlight"></div>

像一本被重点标记的书

.bookmark {
  left: 12px;
  top: -10px;
}

.card:hover .bookmark {
  transform: rotate(0deg) translateY(-1px);
}

Notion / AI dashboard

📖 一本带书签的研究笔记
📚 一面知识展墙
📜 有人使用过的内容系统

你不是在“给卡片加标签”
你是在“让内容变成可触摸的对象”

首页 = 展墙
阅读 = 书页

像一本排版精良的书，而不是网页

1. 行宽固定（不是铺满）
2. 边距有“书页比例”
3. 内容有“版心”
4. 左右留白是设计的一部分
5. 所有元素对齐“基线系统”

:root[data-theme="heritage"] {
  --page-max-width: 760px;
  --page-padding-x: clamp(20px, 6vw, 80px);
  --page-padding-y: clamp(24px, 5vh, 64px);
}

.page {
  display: grid;
  grid-template-columns:
    1fr
    minmax(0, var(--page-max-width))
    1fr;
}
 
.page__inner {
  grid-column: 2;
  padding:
    var(--page-padding-y)
    var(--page-padding-x);
}

不是居中，而是“有版心”

.prose {
  max-width: 66ch;
}

这是阅读最舒适的行宽（书籍标准）

.prose {
  font-family: var(--font-body);
  font-size: 18px;
  line-height: 1.9;
  letter-spacing: 0.01em;
}

.prose p {
  margin: 1.2em 0;
  text-align: justify;
}

text-justify: inter-ideograph;

.prose h1 {
  font-size: clamp(32px, 5vw, 48px);
  line-height: 1.2;
  margin-bottom: 0.8em;
}
 
.prose h2 {
  font-size: 24px;
  margin-top: 2.5em;
  padding-top: 1em;
  border-top: 1px solid var(--heritage-line);
}
 
.prose h3 {
  font-size: 20px;
  margin-top: 2em;
}

.prose p:first-of-type::first-letter {
  float: left;
  font-size: 3em;
  line-height: 1;
  margin-right: 8px;
  font-family: var(--font-display);
}

.prose * {
  margin-top: 0;
  margin-bottom: 0;
}
 
.prose > * + * {
  margin-top: 1.2em;
}

.prose img {
  display: block;
  margin: 2em auto;
  max-width: 100%;
}
 
.prose figure {
  margin: 2em 0;
  text-align: center;
}
 
.prose figcaption {
  font-size: 13px;
  color: var(--heritage-muted);
}

.prose blockquote {
  border-left: 4px solid var(--heritage-purple);
  padding-left: 1em;
  margin: 2em 0;
  color: var(--heritage-muted);
}

.page__inner {
  background: var(--heritage-bg);
}

box-shadow: 0 0 0 1px var(--heritage-line);

不是“侧边栏”，而是“阅读空间”

右侧 panel ❌

沉浸式阅读层 ✔

.home-article-drawer {
  width: min(860px, 100vw);
}

.drawer-content {
  max-width: 760px;
  margin: 0 auto;
  padding: 48px 32px;
}

.home-article-drawer {
  background: var(--heritage-bg);
}

.home-article-backdrop {
  background: rgba(0,0,0,0.15);
}

┌──────────────┐
│ header       │
├──────────────┤
│              │
│   article    │
│   (居中)     │
│              │
└──────────────┘

浮动 TOC（右上角）

.toc {
  position: fixed;
  right: 40px;
  top: 120px;
  width: 200px;
  font-size: 13px;
}

.reading-progress {
  position: fixed;
  top: 0;
  left: 0;
  height: 2px;
  background: var(--heritage-purple);
}

.toc a.active {
  color: var(--heritage-purple);
}

.drawer-content {
  line-height: 1.9;
}

[窄] [标准] [宽]

→ 页面不跳
→ drawer 展开
→ 内容居中
→ 背景弱化

→ 回到原位置
→ 无滚动跳动

→ 不被 UI 打扰
→ 像读书

一个右侧 panel

一个“临时展开的书页”

UI设计 → 阅读体验设计

个人知识操作系统（PKOS）
```很好，这一步已经不是 UI 设计了，而是**真正的“阅读系统 / 知识系统”设计**。我给你一套**可以直接实现的完整方案**，而且是互相联动的三块，而不是零散功能。
 
---
 
# 🧠 总体结构（先理解这个）
 
你要做的是一个“阅读子系统”，而不是零散 feature：
 
```text
Reader System
├─ Theme Engine（Kindle 模式）
├─ Navigation Engine（快捷键 / 跳转）
├─ Memory Engine（阅读历史 / 书签 / 标记）

ReaderState

阅读环境切换系统

type ReaderTheme =
  | "light"   // 当前
  | "sepia"   // 护眼（Kindle风）
  | "dark";   // 夜间

:root[data-reader-theme="light"] {
  --reader-bg: #F5F1E8;
  --reader-text: #1E1B18;
}
 
:root[data-reader-theme="sepia"] {
  --reader-bg: #EFE6D6;
  --reader-text: #2A241E;
}
 
:root[data-reader-theme="dark"] {
  --reader-bg: #1C1A18;
  --reader-text: #E8E4DD;
}

.home-article-drawer {
  background: var(--reader-bg);
  color: var(--reader-text);
}

<div class="reader-theme-switch">
  <button data-theme="light">☀</button>
  <button data-theme="sepia">📜</button>
  <button data-theme="dark">🌙</button>
</div>

const key = "reader-theme";
 
function setTheme(theme) {
  document.documentElement.dataset.readerTheme = theme;
  localStorage.setItem(key, theme);
}
 
function initTheme() {
  const saved = localStorage.getItem(key) || "light";
  setTheme(saved);
}

不用鼠标也能完整浏览内容

J → 下一个卡片
K → 上一个卡片
Enter → 打开文章
Esc → 关闭 Drawer
H → 回首页顶部
G G → 跳顶部（Obsidian习惯）

let activeIndex = 0;
let cards = [];

cards = Array.from(document.querySelectorAll("[data-feed-card]"));

.feed-card--active {
  outline: 2px solid var(--heritage-purple);
}

function setActive(index) {
  cards[activeIndex]?.classList.remove("feed-card--active");
 
  activeIndex = Math.max(0, Math.min(index, cards.length - 1));
 
  const el = cards[activeIndex];
  el.classList.add("feed-card--active");
 
  el.scrollIntoView({
    block: "center",
    behavior: "smooth",
  });
}

document.addEventListener("keydown", (e) => {
  if (document.documentElement.classList.contains("drawer-open")) return;
 
  if (e.key === "j") setActive(activeIndex + 1);
  if (e.key === "k") setActive(activeIndex - 1);
 
  if (e.key === "Enter") {
    const btn = cards[activeIndex].querySelector("[data-open-drawer]");
    btn?.click();
  }
 
  if (e.key === "g") {
    if (window._gPressed) {
      window.scrollTo({ top: 0, behavior: "smooth" });
      window._gPressed = false;
    } else {
      window._gPressed = true;
      setTimeout(() => (window._gPressed = false), 300);
    }
  }
});

type HistoryItem = {
  id: string;
  title: string;
  timestamp: number;
};

function saveHistory(item) {
  const key = "reading-history";
  const list = JSON.parse(localStorage.getItem(key) || "[]");
 
  const updated = [item, ...list.filter(i => i.id !== item.id)].slice(0, 50);
 
  localStorage.setItem(key, JSON.stringify(updated));
}

saveHistory({
  id: articleId,
  title: articleTitle,
  timestamp: Date.now(),
});

type Bookmark = {
  id: string;
  note?: string;
  createdAt: number;
};

<button data-bookmark>🔖</button>

function toggleBookmark(id) {
  const key = "bookmarks";
  const list = JSON.parse(localStorage.getItem(key) || "[]");
 
  const exists = list.find(b => b.id === id);
 
  const updated = exists
    ? list.filter(b => b.id !== id)
    : [...list, { id, createdAt: Date.now() }];
 
  localStorage.setItem(key, JSON.stringify(updated));
}

function isBookmarked(id) {
  const list = JSON.parse(localStorage.getItem("bookmarks") || "[]");
  return list.some(b => b.id === id);
}

选中文本 → 保存 range → 渲染为高亮

type Highlight = {
  articleId: string;
  text: string;
  offset: number;
};

document.addEventListener("mouseup", () => {
  const selection = window.getSelection();
  const text = selection.toString();
 
  if (text.length > 10) {
    console.log("highlight:", text);
    // 存储
  }
});

Reading Panel

📖 最近阅读
🔖 收藏
📝 标记

<aside class="reading-panel">
  <section>History</section>
  <section>Bookmarks</section>
</aside>

J/K 浏览 → Enter 打开 → 阅读 → 标记 → 收藏 → Esc 返回

☀ 白天
📜 护眼
🌙 夜间

文章不是“读完就结束”
而是：
→ 被记录
→ 被收藏
→ 被标记
→ 被回访

你不再是在做博客
你在做一个「个人知识操作系统（PKOS）」

作品级 + 产品级
```很好，这一段开始就进入**真正困难但最有价值的部分**了。我先直接说一句现实判断：
 
👉 这三件事里  
**Highlight 精准定位 = 最难（但最核心）**  
Graph View = 最炫（但可以后做）  
全局搜索 = 最实用（应该先做）
 
我会按**可落地顺序 + 技术难度**帮你设计👇
 
---
 
# 🧠 总架构（你必须先有这个认知）
 
这三块其实共享一个数据核心：
 
```ts
type KnowledgeNode = {
  id: string;          // post/note/book
  title: string;
  type: "post" | "note" | "book";
  content?: string;
  tags?: string[];
};
 
type Highlight = {
  id: string;
  articleId: string;
  text: string;
  anchor: Anchor;      // 关键！
};
 
type Bookmark = {
  id: string;
  articleId: string;
};
 
type GraphEdge = {
  from: string;
  to: string;
  type: "tag" | "link" | "reference";
};

搜索 → 查 node + highlight
Graph → node + edge
Highlight → node 内定位

❌ 保存文本内容
❌ 保存 index

type Anchor = {
  path: string[];     // DOM路径
  offset: number;     // 文本偏移
  length: number;     // 高亮长度
  context: string;    // 前后文本（容错）
};

function getAnchor(selection) {
  const range = selection.getRangeAt(0);
  const node = range.startContainer;
 
  return {
    path: getNodePath(node),
    offset: range.startOffset,
    length: range.toString().length,
    context: range.toString().slice(0, 30),
  };
}

function getNodePath(node) {
  const path = [];
  while (node && node.parentNode) {
    const index = Array.from(node.parentNode.childNodes).indexOf(node);
    path.unshift(index);
    node = node.parentNode;
  }
  return path;
}

function resolveAnchor(anchor, root) {
  let node = root;
 
  for (const i of anchor.path) {
    node = node.childNodes[i];
    if (!node) break;
  }
 
  if (!node) return null;
 
  return {
    node,
    offset: anchor.offset,
  };
}

function highlight(anchor) {
  const { node, offset } = resolveAnchor(anchor, document);
 
  const range = document.createRange();
  range.setStart(node, offset);
  range.setEnd(node, offset + anchor.length);
 
  const span = document.createElement("mark");
  span.className = "highlight";
 
  range.surroundContents(span);
}

.highlight {
  background: rgba(201,162,39,0.35);
  padding: 2px 0;
}

function fuzzyFind(anchor, root) {
  const text = root.innerText;
  const index = text.indexOf(anchor.context);
 
  if (index === -1) return null;
 
  // approximate mapping
}

✔ 文章标题
✔ 正文
✔ 标签
✔ 高亮内容
✔ 笔记

npm i flexsearch

import FlexSearch from "flexsearch";
 
const index = new FlexSearch.Document({
  document: {
    id: "id",
    index: ["title", "content", "tags"],
  },
});

nodes.forEach(node => {
  index.add(node);
});

const results = index.search("MCP");

highlights.forEach(h => {
  index.add({
    id: h.id,
    content: h.text,
    articleId: h.articleId,
  });
});

Search Overlay
├─ 输入框
├─ 分类
│  ├─ Articles
│  ├─ Highlights
│  ├─ Books
├─ 结果列表

Cmd + K → 打开搜索
↑ ↓ → 选择
Enter → 打开

Graph View 很炫，但如果数据弱 → 没意义

节点：
- 文章
- 标签
- 高亮
 
边：
- 文章 ↔ 标签
- 文章 ↔ 文章（链接）
- 高亮 → 文章

npm i react-force-graph

const data = {
  nodes: [
    { id: "post1" },
    { id: "tag:AI" },
  ],
  links: [
    { source: "post1", target: "tag:AI" },
  ],
};

nodeCanvasObject={(node, ctx) => {
  ctx.fillStyle = "#6B2D5C";
  ctx.beginPath();
  ctx.arc(node.x, node.y, 4, 0, 2 * Math.PI);
  ctx.fill();
}}

hover → 高亮邻居
click → 打开文章 drawer
filter → 按 tag / 类型

1️⃣ 全局搜索（立刻有价值）
2️⃣ Highlight（难但核心）
3️⃣ Graph（最后做）

先做 Graph → 看起来很炫 → 实际没用

读 → 走

读 → 标记 → 搜索 → 再读 → 连接 → 形成网络

Highlight 是“记忆”
Search 是“入口”
Graph 是“结构”

不是博客，是 Obsidian + Kindle + GitHub 的融合体
```下面这版是“工程级方案”，不是概念稿。三件事要统一成一个 **Knowledge Layer**，否则 Highlight、Search、Graph 会各做各的，最后变成三套孤岛。
 
你的当前工程已经有 `apps/web`、静态内容集合、首页 Drawer、FeedItem 和本地设置系统，所以第一版建议仍然走 **Astro 静态构建 + 客户端本地知识层 localStorage/IndexedDB**，不要一上来就做后端。README 里也明确了当前内容系统是文件型 content collections，正式内容真源是 `apps/web/src/content/`。
 
---
 
# 0. 总体目标
 
```text
Highlight = 记忆点
Search = 入口
Graph = 结构

posts / notes / projects / books / music
        ↓ build
knowledge-index.json
        ↓ client
Search Overlay + Reader Drawer + Graph View
        ↓ user actions
localStorage / IndexedDB
        ↓
highlights / bookmarks / reading history

apps/web/src/lib/knowledge/
├─ anchors.ts
├─ highlights.ts
├─ search.ts
├─ graph.ts
├─ storage.ts
└─ types.ts
 
apps/web/src/components/knowledge/
├─ SearchOverlay.tsx
├─ GraphView.tsx
├─ HighlightToolbar.tsx
├─ ReadingMemoryPanel.astro
└─ ReaderCommandHint.astro
 
apps/web/public/data/
└─ knowledge-index.json

Primary：TextQuoteSelector
Secondary：TextPositionSelector
Fallback：DOM Path Selector

export type HighlightColor =
  | "gold"
  | "purple"
  | "red"
  | "green"
  | "blue";
 
export type TextQuoteSelector = {
  type: "TextQuoteSelector";
  exact: string;
  prefix: string;
  suffix: string;
};
 
export type TextPositionSelector = {
  type: "TextPositionSelector";
  start: number;
  end: number;
};
 
export type DomPathSelector = {
  type: "DomPathSelector";
  startPath: number[];
  startOffset: number;
  endPath: number[];
  endOffset: number;
};
 
export type HighlightAnchor = {
  quote: TextQuoteSelector;
  position: TextPositionSelector;
  dom: DomPathSelector;
  contentHash: string;
};
 
export type HighlightRecord = {
  id: string;
  articleId: string;
  title: string;
  color: HighlightColor;
  note?: string;
  anchor: HighlightAnchor;
  createdAt: number;
  updatedAt: number;
};

1. 获取用户选中的 Range
2. 在 article root 中生成全文 textContent
3. 算出选区在全文里的 start/end
4. 保存 exact + prefix + suffix
5. 同时保存 DOM path

export function createHighlightAnchor(root: HTMLElement, range: Range): HighlightAnchor {
  const exact = range.toString();
  const fullText = normalizeText(root.textContent || "");
 
  const start = findRangeTextOffset(root, range.startContainer, range.startOffset);
  const end = start + normalizeText(exact).length;
 
  const prefixStart = Math.max(0, start - 48);
  const suffixEnd = Math.min(fullText.length, end + 48);
 
  return {
    quote: {
      type: "TextQuoteSelector",
      exact: normalizeText(exact),
      prefix: fullText.slice(prefixStart, start),
      suffix: fullText.slice(end, suffixEnd),
    },
    position: {
      type: "TextPositionSelector",
      start,
      end,
    },
    dom: {
      type: "DomPathSelector",
      startPath: getNodePath(root, range.startContainer),
      startOffset: range.startOffset,
      endPath: getNodePath(root, range.endContainer),
      endOffset: range.endOffset,
    },
    contentHash: hashText(fullText),
  };
}
 
function normalizeText(input: string) {
  return input.replace(/\s+/g, " ").trim();
}

1. contentHash 相同 → 优先 TextPositionSelector
2. exact + prefix + suffix 能匹配 → 使用 TextQuoteSelector
3. exact 多处出现 → prefix/suffix 消歧
4. 仍失败 → DOM path
5. 仍失败 → fuzzy exact
6. 全失败 → 标记为 orphan highlight

export function resolveHighlight(root: HTMLElement, anchor: HighlightAnchor): Range | null {
  const fullText = normalizeText(root.textContent || "");
  const currentHash = hashText(fullText);
 
  if (currentHash === anchor.contentHash) {
    const byPosition = resolveByTextPosition(root, anchor.position);
    if (byPosition) return byPosition;
  }
 
  const byQuote = resolveByQuote(root, anchor.quote);
  if (byQuote) return byQuote;
 
  const byDom = resolveByDomPath(root, anchor.dom);
  if (byDom) return byDom;
 
  return resolveByFuzzyQuote(root, anchor.quote);
}

function resolveByQuote(root: HTMLElement, quote: TextQuoteSelector): Range | null {
  const textNodes = collectTextNodes(root);
  const fullText = textNodes.map((n) => n.nodeValue || "").join("");
 
  const candidates = findAllIndexes(fullText, quote.exact);
 
  if (candidates.length === 0) return null;
 
  const best = candidates
    .map((start) => {
      const end = start + quote.exact.length;
      const prefix = fullText.slice(Math.max(0, start - quote.prefix.length), start);
      const suffix = fullText.slice(end, end + quote.suffix.length);
 
      return {
        start,
        end,
        score:
          similarity(prefix, quote.prefix) * 0.45 +
          similarity(suffix, quote.suffix) * 0.45 +
          0.1,
      };
    })
    .sort((a, b) => b.score - a.score)[0];
 
  if (!best || best.score < 0.65) return null;
 
  return createRangeFromTextOffsets(textNodes, best.start, best.end);
}

拆文本节点 → 插入 mark → 保留原结构

export function applyHighlight(root: HTMLElement, record: HighlightRecord) {
  const range = resolveHighlight(root, record.anchor);
  if (!range) return { status: "orphan" as const };
 
  const wrapperClass = `reader-highlight reader-highlight--${record.color}`;
 
  try {
    wrapRangeWithMarks(range, wrapperClass, record.id);
    return { status: "applied" as const };
  } catch {
    return { status: "failed" as const };
  }
}

.reader-highlight {
  border-radius: 2px;
  padding: 0.04em 0;
  cursor: pointer;
}
 
.reader-highlight--gold {
  background: rgba(201, 162, 39, 0.34);
}
 
.reader-highlight--purple {
  background: rgba(107, 45, 92, 0.22);
}
 
.reader-highlight--red {
  background: rgba(158, 42, 43, 0.22);
}
 
.reader-highlight--green {
  background: rgba(47, 93, 80, 0.22);
}

这个标记暂时无法定位
原文摘录：xxxx
操作：重新定位 / 删除 / 保留

type HighlightRenderState = "applied" | "orphan" | "failed";

npm i flexsearch

export type KnowledgeSearchDoc = {
  id: string;
  type: "post" | "note" | "project" | "book" | "music" | "highlight";
  title: string;
  content: string;
  tags: string[];
  href?: string;
  drawerId?: string;
  sourceId?: string;
  updatedAt?: string;
};

apps/web/public/data/knowledge-index.json

Cmd/Ctrl + K：打开搜索
Esc：关闭
↑/↓：移动结果
Enter：打开
Tab：切换分组

All
Articles
Notes
Projects
Books
Music
Highlights

┌────────────────────────────────────┐
│ Search everything...        ⌘K     │
├────────────────────────────────────┤
│ All Articles Notes Books Highlights│
├────────────────────────────────────┤
│ result title                       │
│ excerpt with matched text          │
│ tag tag tag                        │
└────────────────────────────────────┘

import { useEffect, useMemo, useState } from "react";
import FlexSearch from "flexsearch";
 
type SearchDoc = {
  id: string;
  type: string;
  title: string;
  content: string;
  tags: string[];
  href?: string;
  drawerId?: string;
};
 
type Props = {
  docs: SearchDoc[];
  onOpenDrawer?: (drawerId: string) => void;
};
 
export function SearchOverlay({ docs, onOpenDrawer }: Props) {
  const [open, setOpen] = useState(false);
  const [query, setQuery] = useState("");
  const [group, setGroup] = useState("all");
  const [activeIndex, setActiveIndex] = useState(0);
 
  const index = useMemo(() => {
    const idx = new FlexSearch.Document({
      document: {
        id: "id",
        index: ["title", "content", "tags"],
        store: ["id", "type", "title", "content", "tags", "href", "drawerId"],
      },
      tokenize: "forward",
    });
 
    docs.forEach((doc) => idx.add(doc));
    return idx;
  }, [docs]);
 
  const results = useMemo(() => {
    if (!query.trim()) return [];
 
    const raw = index.search(query, { enrich: true, limit: 20 });
    const map = new Map<string, SearchDoc>();
 
    raw.forEach((fieldResult: any) => {
      fieldResult.result.forEach((item: any) => {
        const doc = item.doc as SearchDoc;
        if (group === "all" || doc.type === group) {
          map.set(doc.id, doc);
        }
      });
    });
 
    return Array.from(map.values());
  }, [index, query, group]);
 
  useEffect(() => {
    const onKey = (event: KeyboardEvent) => {
      const isCommandK = (event.metaKey || event.ctrlKey) && event.key.toLowerCase() === "k";
 
      if (isCommandK) {
        event.preventDefault();
        setOpen(true);
      }
 
      if (!open) return;
 
      if (event.key === "Escape") setOpen(false);
      if (event.key === "ArrowDown") {
        event.preventDefault();
        setActiveIndex((value) => Math.min(value + 1, results.length - 1));
      }
      if (event.key === "ArrowUp") {
        event.preventDefault();
        setActiveIndex((value) => Math.max(value - 1, 0));
      }
      if (event.key === "Enter") {
        event.preventDefault();
        const doc = results[activeIndex];
        if (!doc) return;
 
        if (doc.drawerId && onOpenDrawer) {
          onOpenDrawer(doc.drawerId);
          setOpen(false);
        } else if (doc.href) {
          window.location.href = doc.href;
        }
      }
    };
 
    window.addEventListener("keydown", onKey);
    return () => window.removeEventListener("keydown", onKey);
  }, [open, results, activeIndex, onOpenDrawer]);
 
  if (!open) return null;
 
  return (
    <div className="search-shell" role="dialog" aria-modal="true">
      <button className="search-backdrop" onClick={() => setOpen(false)} />
 
      <section className="search-panel">
        <div className="search-input-row">
          <input
            autoFocus
            value={query}
            onChange={(event) => {
              setQuery(event.target.value);
              setActiveIndex(0);
            }}
            placeholder="Search posts, notes, books, highlights..."
          />
          <kbd>Esc</kbd>
        </div>
 
        <nav className="search-tabs">
          {["all", "post", "note", "project", "book", "music", "highlight"].map((item) => (
            <button
              key={item}
              className={group === item ? "is-active" : ""}
              onClick={() => {
                setGroup(item);
                setActiveIndex(0);
              }}
            >
              {item}
            </button>
          ))}
        </nav>
 
        <div className="search-results">
          {results.length === 0 ? (
            <p className="search-empty">输入关键词，搜索文章、笔记、书架、音乐和标记。</p>
          ) : (
            results.map((doc, index) => (
              <button
                key={doc.id}
                className={`search-result ${index === activeIndex ? "is-active" : ""}`}
                onMouseEnter={() => setActiveIndex(index)}
                onClick={() => {
                  if (doc.drawerId && onOpenDrawer) {
                    onOpenDrawer(doc.drawerId);
                    setOpen(false);
                  } else if (doc.href) {
                    window.location.href = doc.href;
                  }
                }}
              >
                <span className={`search-result__type search-result__type--${doc.type}`}>
                  {doc.type}
                </span>
                <strong>{doc.title}</strong>
                <small>{makeExcerpt(doc.content, query)}</small>
              </button>
            ))
          )}
        </div>
      </section>
    </div>
  );
}
 
function makeExcerpt(content: string, query: string) {
  const index = content.toLowerCase().indexOf(query.toLowerCase());
  if (index < 0) return content.slice(0, 120);
  return content.slice(Math.max(0, index - 40), index + 100);
}