# 读书笔记书架 · 可执行规格（v1）

状态：示意已对齐。2026-10-27：立书搁板 + 抽书/放回；豆瓣卡无封面（封面独立英雄区）；正文同渲染（实现挂 MarkdownArticle）。
视觉稿：`/workspace/dev/bookshelf-design/`（浅/深色书架、书详情、笔记阅读态）。

---

## 0. 目标与非目标

**目标**  
专栏「读书笔记」从「编号文章清单」升级为：书架 → 书 → 出处（PDF / 豆瓣等）→ 笔记。入口仍在专栏，不新开 Tab。豆瓣信息卡抽成通用组件，博文也可引用；登记/拉数用 Skill 减作者负担。

**非目标（v1）**  
- 站点一级导航「书架」  
- 想读 / 在读 / 已读状态机、进度条、年度统计、社交  
- 微信读书 / 豆瓣 API 自动同步（手写 front matter）  
- 把 Go / Rust 专栏改成封面墙  
- 浏览器运行时爬豆瓣；复制豆瓣「想读/在读」交互  
- 把按章博文并进读书笔记书页  

---

## 1. 品味约束（Hedon Garden）

| Token / 规则 | 值 |
| --- | --- |
| 浅色纸 | `#FAF9F5`（`--paper`） |
| 芯片 / 井 | `#F0EEE6`（`--paper-deep`） |
| 悬停 | `#F5F4ED`，极轻阴影，**不位移** |
| 墨色 | 浅 `#30302E` / 深 `#ededeb`；深色纸 `#1f1e1d` |
| 圆角 | 封面 ~10–12px；卡片 ~12–14px |
| 禁止 | 品牌蓝、木纹层板、厚拟物书墙、强 CTA |
| 参考 | Claude 安静卡片；出处语感对齐现有 source / link-card |
| **正文一致性（hedon 2026-10-27）** | 笔记正文必须**直接调用**现网同一组件（`MarkdownArticle` → `.markdown-body`），**禁止复制/另开一套文章 CSS**。hedon 要求 **demo 也引用 `hd-garden` 真渲染**（静态 HTML 近似作废）；demo 应收成依赖 `hd-garden` 的小站点。**书页笔记区必须当场渲染正文，禁止再跳对照站二跳**（「打开这篇笔记 →」作废）。实现/示意验收都以真组件为准。书架与书页外壳可新。 |

---

## 2. 信息架构与路由

```
/columns/                      专栏总览（三卡，读书笔记卡仍在）
/columns/#book-note            现网锚点；保留兼容
/columns/book-note/            【改】书架落地（现为跳转到 #book-note）
/columns/book-note/books/<slug>/   【新】书详情
/columns/book-note/<post-path>/    现有专栏文章路径（笔记阅读态）
/blog/<post-path>/                 博客路径不变；面包屑可链回书
```

**接现网**  
- 首页 / 专栏卡：链到 `/columns/book-note/`（书架），不再只锚到列表。  
- `/columns/book-note/` 取消「页面已移动」软跳，改为书架页。  
- 旧列表锚点与外链：301 或等价静态重定向到书架。  
- Go / Rust：`/columns/` 上仍用编号阅读清单；系列文章页 series-nav 不变。

---

## 3. 内容模型

### 3.1 书实体（新）

建议文件：`content/books.yaml`（或仅挂在 `columns.yaml` 的 `book-note.books`）。

```yaml
- slug: fosa
  doubanId: "12345678"           # 缓存键；构建脚本按此拉元数据+封面
  title: Fundamentals of Software Architecture   # 本地底稿（拉失败用）
  author: Mark Richards · Neal Ford
  cover: note-fosa.jpg           # 本地封面底稿；构建成功则换缓存图
  # 构建产物（勿手写依赖）：.cache/douban/<id>.json + 封面文件，TTL 48h
  sources:
    - label: 豆瓣
      href: https://book.douban.com/subject/12345678/
    - label: PDF                 # 可选；有才渲染
      href: /assets/pdf/fosa.pdf # garden-blog 仓库内；点击下载
  notes:                         # 仅读书笔记；不挂 chapter / 按章博文
    - path: note/note-fosa
```

### 3.2 与 posts 关系

- 正文仍只在 `content/posts/**` 维护一份。  
- `columns.yaml` 的 `book-note.posts`：v1 可由 books[].notes 推导，或保留扁平列表作校验。  
- Unit Testing 的笔记 + 摘抄 → 同一 `slug`（多笔记 → 卡片列表）。  
- **FOSA 等按章博文不纳入读书笔记 / 不进书页**（仍是普通博文）。  
- PDF 放 `garden-blog` 的 `assets/pdf/`，公开才进 `sources`。
- **豆瓣**：构建时按 `doubanId` 拉元数据+封面，本地缓存 **48h**；失败静默用 yaml 底稿+本地 cover。页面/浏览器不直连豆瓣、不热链豆瓣 CDN。

### 3.3 Front matter（帖）

现有字段保留。v1 **不强制**帖上写 book；归属以 `books.yaml` 为准。可选加 `book: fosa` 便于校验。

---

## 4. 页面规格

### 4.1 书架页 `/columns/book-note/`

| 区块 | 规格 |
| --- | --- |
| 路径 | `专栏 · 读书笔记` |
| 标题 | `读书笔记` |
| 导语 | 见 §7 文案 |
| 芯片 | `N 本书` · 专栏 `status` · 「近读在前」（v1 固定文案，不做控件） |
| **沉浸目标（hedon 2026-10-27）** | 要有**书架**感，不是扁平封面墙。交互隐喻：**抽书出来 / 展开进书的世界 / 合上放回**（直观、沉浸）。可参考 Claude articles 的创意启发，**禁止直接抄**其竖脊轮播。 |
| **电脑端交互示意（hedon 手绘 2026-10-27）** | 见 `hedon-书架交互示意-电脑端.png`。① 书可**归类**（像图书馆，类目/排架可见）。② 每一搁板行可**横向滑动**看更多。③ 点书：**从架子抽出 → 展开**进入本书世界，背景虚化过渡到笔记页（博文样式渲染）。④ 笔记页有「返回书架」；点返回：**合上书 → 放回原位**，与打开对称。 |
| 布局方向（随 hedon 示意更新） | ① 横排搁板 + **站立封面**（封面贴板、题注板下）。② 打开/返回走抽出展开 / 合上放回动画（View Transition 可作底，示意级 demo 也要看得出对称）。③ 不做写实 3D 木纹、不抄 Claude 书脊轮播。④ 归类与横滑是 hedon 示意新增，优先于「仅悬停抬起」。 ⑤ **悬停 = 横向撑开**（加宽推邻书 + 全名），不是只 translateY；默认展开第一类第一本；点击抽出再导航。封面 `view-transition-name`（`book-*-cover`）供返回对称。⑤ **悬停横向展开**该本（示意：鼠标放上去变宽）；**默认展开第一排第一本**。⑥ 四帧示意：`hedon-示意-1…4-*.png`。 |
| **立书形态纠偏（hedon 2026-10-27 晚）** | 未展开 = **竖立窄条**（书脊感，侧立在搁板上），不是正面 2:3 封面墙。悬停/默认展开 = 横向撑开露出封面/全名。参考：hedon 示意竖条 + `ref-spine-*.png`（密排书脊）；**仍禁止照抄 Claude 竖脊轮播**。木纹厚拟物非必须，书架感靠立姿+抽插动画。 |
| **开合动画（hedon 硬性）** | 取下 → 打开 → 展示正文 → 返回时合上 → 放回原槽；必须看得出完整对称，不能「抬一下就跳页」。跨域无法共享 VT：**demo 书架与书页必须同站**，否则动画验收不过。 |

| 旧网格稿 | 桌面封面栅格仅作过渡参考；**不以现网封面墙为终态**。 |
| 缺封面 | 暖灰布面 + 书名排版兜底（浅/深色各一套） |
| 禁止 | 木纹厚拟物书墙、品牌蓝、强 CTA、3D 厚拟物（品味约束仍在） |
| 空态 | 「架上还没有书。」；链到内容编写文档（实现期再补） |

### 4.2 书详情 `/columns/book-note/books/<slug>/`

| 区块 | 规格 |
| --- | --- |
| 路径 | `专栏 · 读书笔记 · 本书` |
| 英雄区 | **独立封面块**（约 148px，优先豆瓣缓存）在卡左侧（手机在卡上方）；与信息卡分离，不嵌进卡内。 |
| 豆瓣信息卡 | **无封面**。安静 Garden 卡：书名/副标题 + 元信息 + 评分列（大分+星+人数，**无**「豆瓣 x.x」芯片）。有构建缓存则丰满；仅底稿则简卡。**不**搬想读/在读/星条。 |
| 出处动作 | 安静**文字链**（「在豆瓣打开」「PDF」），非按钮塔。PDF：`sources` 有才显示；文案 `PDF` + 浅小字 `(仅分享，侵权删)`。 |
| 去掉 | **原书站点**；**按章问答 / 章节列表**整区删除 |
| 笔记 · 仅 1 篇 | **仍进书页**；英雄区（封面 + 豆瓣/PDF）下面**直接铺正文**，不再套「总览」卡片 |
| 笔记 · 多篇 | 区标题「笔记」；卡片列表（kicker / 标题 / description / 日期），点击进现有笔记 URL |

### 4.2.1 通用 BookCard（hedon + GB 2026-10-27）

做成 **hd-garden 通用组件**（fence 名 `douban-book`，对齐 link-card；手册「豆瓣书卡」）。书详情英雄区是调用方；**普通博文也可嵌**。进 shared，不是书页私有块。

| 项 | 规格 |
| --- | --- |
| 数据 | 优先 `doubanId` → 构建缓存（48h）；否则用调用处传入的本地底稿字段 |
| 丰满 / 简 | 有评分等则丰满卡；缺字段收成简卡，不留空行 |
| 视觉 | **书页英雄区**：左侧独立大封面（不塞进信息卡）。信息卡 = 标题 + 元信息 + 评分；出处为安静文字链。**博文内嵌 `douban-book` 默认无封面**（封面只在架上 / 书页英雄区）。hedon+FD 2026-10-27 锁死：封面出卡。 |
| 禁止 | 想读/在读、热链豆瓣图、前端运行时爬豆瓣 |
| 手册 | 组件页只放用途 + 1～2 个例子；字段细节进 API reference |
| 博文 fence（最少参数 · FD 定） | 只认豆瓣链接或纯 `doubanId`；标题/封面/评分全走构建缓存 |

````md
```douban-book
https://book.douban.com/subject/12345678/
```
````

书页英雄区同组件，**多传** `pdf` / `showPdf` 才出 PDF 胶囊（博文默认关）。

### 4.2.2 作者路径 + 手册 / Skill（hedon + GB 2026-10-27）

原则：**作者心智压到最低**。组件只渲染；脏活全部进 Garden Skill，不靠人口述。

**人只给**
- 豆瓣链接（或 `doubanId`）+ 笔记正文
- 有公开 PDF 时，再把文件丢进 `assets/pdf/`

**AI / Skill 干**
- 建/改 `books.yaml` 底稿与 `sources`
- 跑构建缓存拉封面和元数据（48h；失败用底稿 → 简卡）
- 挂上 `notes`；博文插入 `douban-book` fence（正文仅一行豆瓣 URL 或 `doubanId`）
- 可选登记 PDF 胶囊（仅书页调用打开）

**作者不碰**
- 缓存目录、TTL、封面哈希、路由拼装、字段表

**手册条目（实现期同步）**
1. 「如何登记一本书」——以 Skill 步骤为主（粘贴链接 → 确认是这本书 → 完成）
2. 「博文嵌豆瓣书卡」——fence 最少参数示例
3. 组件页 `douban-book`：用途 + 1～2 例；API reference 另页

Skill 名建议：`register-book` / `embed-douban-book`（可合并为一条「登记一书」含两种出口）。须可重复、失败可解释。

### 4.3 笔记阅读态（专栏路径）

| 区块 | 规格 |
| --- | --- |
| 版式 | 保持现有三栏：series-nav · 正文 · TOC |
| series-nav 改 | 顶：`← 回到本书` + 本书迷你封面/书名；多笔记时下列本书 notes（当前高亮）；单笔记可仅返回链。不再列「全专栏扁平」或按章博文 |
| 面包屑 | `专栏 · 读书笔记 · 《书名》` |
| 正文 | **实现必须复用共享 `MarkdownArticle` / `.markdown-body`**（字体、字号、行高、标题层级、代码块、callout、组件），**禁止另拷文章 CSS**；组件 / 封面 / TOC 行为不变；**不**在文首重复堆出处；**不要**发明「笔记」kicker（现网 article-header 只有标题 + meta + lead + 正文） |
| 博客路径 | 可选轻链「在书架中查看」→ 书页 |

浅色 / 深色均走现有 `data-theme` token，不另开色板。单笔记书页「英雄区下直出正文」时挂 `MarkdownArticle`。**静态 demo 书页正文已改为占位**（不手抄 `.markdown-body`）；真渲染由后续 hd-garden 迷你站 `/article/` 承担。

---

## 5. 调研小结（给 GB 对方向）

| 参考 | 借 | 不借 |
| --- | --- | --- |
| [Kyle Johnston Bookshelf](https://books.kyleio.com/) | 封面架 → 书 → 章节笔记；最接近个人站 | 购书外链堆 |
| [Literal](https://literal.club/) | 书为一等对象；划线+想法+页码 | 社交 / 书友会 |
| [微信读书](https://weread.qq.com/) | 封面朝前、安静徽章 | 排行 / 时长竞赛、蓝 |
| [豆瓣读书](https://book.douban.com/) | 书身份 + 笔记挂书下 + 章节引用 | 社区投票墙 |
| [Readwise Reader](https://docs.readwise.io/reader) | 笔记长在源上、可导出 | Inbox 分拣 UI |
| Cubox | （文章稍后读，非书架） | 不作书架范式 |
| Are.na | 块状收藏气质 | 频道模型过散，不作主 IA |

**五原则**  
1. 书是房间，笔记是家具  
2. 封面朝前，状态最多轻徽章  
3. 出处胶囊在书上  
4. 笔记 =（可选摘录）+ 自己的话 + 位置  
5. 个人花园，不是社交 tracker  

---

## 6. 实现注意（给 FD）

1. **路由**：`book-note` 根路径今日软跳 `#book-note`，要改成真实书架页；注意 sitemap / RSS / 旧外链。  
2. **封面**：沿用本地 cover 流水线；书架要竖图 2:3 crop 或独立 `bookCover`，避免文章横图英雄直接当书脊。  
3. **豆瓣 / PDF（定稿 2026-10-27）**：去掉原书站点。`doubanId` → 构建脚本拉元数据+封面，缓存 48h，失败用本地底稿；页面不直连豆瓣。PDF 仅公开文件进 `assets/pdf/`，胶囊 `PDF` + 浅小字 `(仅分享，侵权删)`。  
4. **书↔笔记**：一对多；列表排序 = 书的 `updated`（其下笔记最新 `date`）或显式 `order`。  
5. **series-nav**：多笔记时左栏「本书上下文」；单笔记以书页直出正文为主。与 Go 专栏「全系列列表」分支。按章博文不进此上下文。  
6. **深色**：只用现有 CSS 变量；封面缺图兜底需深色变体。  
7. **性能**：封面 webp；网格勿上重阴影动画。  

---

## 7. 文案（v1 定稿 · Gemini 润色 2026-10-27）

| 位置 | 文案 |
| --- | --- |
| 书架导语 | 读过的书收在这里。出处和笔记，都在每一本下面。 |
| 排序芯片 | 近读在前 |
| 册数芯片 | `{n} 本书`（与专栏 `status` 并列） |
| 书页笔记区标题（多篇时） | 笔记 |
| PDF 胶囊 | `PDF` + `(仅分享，侵权删)`（后半浅色更小字） |
| 豆瓣打开 | 在豆瓣打开 |
| 阅读态返回 | ← 回到本书 |
| 首页/专栏卡副文案 | `{n} 本书，还在记` |
| 空书架 | 架上还没有书。 |

---

## 8. 验收清单

- [ ] `/columns/book-note/` 为立书搁板（非封面墙），浅/深色可读；悬停有抽出感  
- [ ] 点书进入书页：独立封面英雄区 + 无封面豆瓣卡 +（可选）PDF 文字链；单笔记直出正文，多笔记卡片列表；无按章区
- [ ] `douban-book` 可在博文中嵌；缺字段简卡、有缓存丰满卡  
- [ ] 专栏笔记页左栏回书 + 本书目录；正文组件无回归  
- [ ] Go / Rust 专栏视觉与路由无变化  
- [ ] 首页专栏卡进入书架而非旧锚点列表  
- [ ] 390 / 1440 可读；书架悬停为抬起（抽书），非卡片位移；返回可用 View Transition 放回  

## 9. 建议落地顺序

1. `books.yaml` + 现有书数据（Unit Testing 两篇合并；FOSA 仅总览笔记，不含按章帖）  
2. `assets/pdf/` 目录约定 + 公开 PDF 登记  
3. `douban-book` 组件进 hd-garden shared（书页复用；博文可嵌）
4. 构建脚本：按 `doubanId` 拉豆瓣，48h 缓存，失败用底稿  
5. 书架页 + 取消软跳  
6. 书详情页（单笔记直出 / 多笔记列表；英雄区用组件）  
7. 多笔记时的 series-nav  
8. 「登记一书」Skill（解析豆瓣链接 → 写配置/触发缓存）
9. 手册组件页 +「如何登记一本书」→ 发版  

---

## 10. 设计稿索引

| 文件 | 内容 |
| --- | --- |
| `shelf.html` / `shelf-dark.html` / `shelf-mobile.html` | 立书搁板 · 浅 / 深 / 手机（以 HTML 为准） |
| `book-desktop.png` / `book-dark.png` | 书详情 · 单笔记直出 · 浅 / 深 |
| `book-multi.png` / `book-multi-dark.png` | 书详情 · 多笔记列表 · 浅 / 深 |
| `note-light.png` / `note-dark.png` | 笔记阅读态浅 / 深 |
| `book.html` / `book-multi.html` (+ dark) | 书详情高保真 HTML |
| `blog-embed.html` / `blog-embed.png` | 普通博文内嵌 douban-book 示意 |