# 此间札记

> 一个把排版当回事、同时写给人和 AI 读的博客。

本站以 zh-CN 为主。

首次全量导入可读取 [content.ndjson](https://xiaoxusop.github.io/letterpress/content.ndjson)：一行一篇，包含完整原文。

后续读取 [content-manifest.json](https://xiaoxusop.github.io/letterpress/content-manifest.json)，按 sha256 只抓取变化的 .md 文件。

<doc title="构建探针" path="wiki/build-probe.md">

> 对「构建产物」本身做的断言——问的不是「代码写对没有」，而是「生成出来的东西对不对」。

一类检查：不看源码，只看**构建出来的产物**。

它和单元测试的分工很清楚：

| | 问的问题 | 够不着的地方 |
|---|---|---|
| 单元测试 | 这个函数算得对吗 | 它有没有被接进管线 |
| 构建探针 | 产物里真的是这样吗 | 为什么 |

## 为什么需要它

因为有一整类 bug，**单元测试永远抓不到**：

- 配置写了但没接线（`@astrojs/mdx` 装了却没注册进 `integrations`）
- 文件写好了但没人引用（`fonts.css` 从头到尾没被 import）
- 处理器换了 API（老写法被接受但**不执行**，只发一条弃用警告）
- 元素渲染了两遍（所有断言都问「存在吗」，没有一条问「出现几次」）

它们的共同点是：**不报错、构建成功、测试全绿，只是没效果。**

## 这个项目里的几条

- **内容发布探针**：真的放一个 `.md` 与 `.mdx` 进去，构建，看能不能产出页面；
  再放入草稿与占用 `/about/` 的文章，确认前者不会泄漏、后者会明确阻断构建。
  **读配置不够**——配置可以是对的而接线是断的
- **链接渲染契约**：正文里的 `[[方括号]]` 是不是真的变成了链接
- **字体加载契约**：`@font-face` 有没有进产物、字体总量有没有失控
- **区块唯一性**：同一区块在一页里不得出现两次
- **子路径契约**：六类载体（属性 / 脚本内路径 / 绝对 URL / 纯文本产物 / 内容清单 / NDJSON 全量导出）的
  前缀是否都正确

## 一条纪律：新检查必须反向验证

**把 bug 放回去，确认它真的报错、退出码为 1。**

这不是形式主义。这个项目里出现过三次「检查本身是坏的」，
而且**失效方向是相反的**：

- **漏检**：一条检查因为 `readdir` 在别的作用域、抛异常被 catch 吞掉，
  **扫了 0 个文件却报告「通过」**
- **漏检**：一条检查只匹配 `href="/x"` 形式的相对绝对路径，
  产物里 `https://` 开头的 URL 全部**不进正则**——于是「前缀翻倍」
  这个致命问题在它的注视下安然通过
- **误报**：还是那条检查。它后来改成对整段 HTML 跑正则来找属性，
  于是**正文里的代码示例也被当成链接**——就是上一段里 `href="/x"`
  那个写法（它此刻正作为一个反例出现在这里）。修法是把正则锚定到
  标签上，只认真正的属性：`<[^>]*\s(?:href|src)="…"`

**误报和漏检一样有害**：一条会红的检查，人第一反应是关掉它。
对模板尤其致命——使用者写一篇提到 `href="/foo"` 的文章，构建就失败，
而失败原因和他的文章毫无关系。

**一条从没失败过的检查不值得信任；
一条会无缘无故变红的检查，同样不值得信任。**

## 覆盖面要跟着「载体」走

同一个地址可能出现在六类地方，而每类的写法不同：

1. `href` / `src` **属性**中的相对绝对路径
2. `<script>` 块里**拼出来的**路径（模板字符串拼的 `import()` 参数）
3. `https://` 开头的**绝对 URL**（`og:image`、RSS 发现、JSON-LD）
4. **纯文本产物**里的链接（`llms.txt`、`robots.txt`）
5. **JSON 内容清单**里的结构化 URL
6. **NDJSON 全量导出**里每条记录的站点地址与内容 URL

**每漏一类，就漏掉一整类 bug。** 这些覆盖不是预先画出来的清单，
而是每次遇到真实漏检后补进契约的。

相关条目：[reproducible-builds](https://xiaoxusop.github.io/letterpress/reproducible-builds/)、[letterpress](https://xiaoxusop.github.io/letterpress/wiki/letterpress/)。

</doc>

<doc title="中文排版" path="wiki/cjk-typography.md">

> 行高、字重、行宽、中西文间距——四个参数直接套西文的值，中文读者看到的是「能读但别扭」的页面。

中文网页排版最常见的病因：**参数沿用了西文的值。**

| 参数 | 西文常用 | 中文应用 | 为什么 |
|---|---|---|---|
| 行高 | 1.4–1.5 | **1.6–1.8** | 方块字笔画铺满字面，没有升降部带来的天然空隙 |
| 标题字重 | 600–700 | **600** | 伪合成的开关是 `font-synthesis-weight`，不是字重数值；关掉后由字体挑真实字重——请求 >500 时**先向上找**（600→700→800），故有真 600 的字体直接命中 600 |
| 行宽 | 66ch | **34em** | `ch` 按渲染字体的「0」字形算、随字体浮动；`em` 等于计算后的 font-size，**容器宽度**跨字体可预测 |
| 中西文间距 | 手动加 | **`text-autospace`** | 2025 起浏览器原生支持，pangu.js 时代结束 |
| 强调 | 斜体 | **加粗** | 中文无斜体字形，强制倾斜即笔画变形 |

## `34em` 这个数字

它大致同时覆盖两种文字的舒适区，因为：

- 一个汉字 ≈ 1em 宽 → 34em 排**约** 34 个汉字（理想 30–40）
- 一个西文字母平均 ≈ 0.5em 宽 → 34em 排**约** 68 个字符（理想 45–75）

⚠️ **保证的是容器宽度，不是字数。** `em` 等于**计算后的 font-size**，
规范保证且与字体无关；但**汉字 advance 是否恰好 1em，规范并不保证**——
它为此定义了 `ic`（全角字形的典型 advance，无法确定时假设 1em，见
[CSS Values 4 §ic](https://www.w3.org/TR/2024/WD-css-values-4-20240312/#ic)）。
**如果两者相等就不必再定义 `ic`**——这正是那句话存在的理由。

用 `ch` 连容器宽度都不稳：它按**渲染字体的「0」字形**计算
（[CSS Values 4](https://www.w3.org/TR/2024/WD-css-values-4-20240312/#ch) 原文是
"the used advance measure of the "0" (ZERO, U+0030) glyph in the font used to render it"），
所以「66ch 排几个汉字」**随字体变**。粗估一个汉字约 2 `ch`，66ch ≈ 33 字——
其实也不差，但它多了一层未实测的假设（「0 字形约 0.5em」），且容器宽度本身也随字体浮动。

> **勘误（2026-09-22）**：这里原先写「`66ch` 排中文会变成约 **130 字**一行」。
> 按它自己的前提（1 汉字 ≈ 2 `ch`）应当除以 2 得 33，而不是乘以 2。
> 而且 33 落在舒适的 30–40 里——原句想说的「太宽」并不成立。
> 顺带：66ch ≈ 33em，与本站的 34em **宽度几乎相同**，这个改动换的是容器宽度的可预测性而非行宽。
>
> **勘误（2026-09-24）**：上一条之后本页仍写着「**`em` 不是估算**」。
> **这句话是错的，而且错得最彻底**——它把「容器宽度不随字体变」推广成了
> 「字数可确定」。`em` 的定义里根本没有「汉字宽度」这一项；
> 上面那段 `ic` 的原文就是规范自己承认这件事无法从 `em` 推出。已改写。

## 2026 年的两个原生属性

```css
html { text-autospace: normal; text-spacing-trim: trim-start; }
pre, code, kbd, samp { text-autospace: no-autospace; }
```

- `text-autospace`：中西文之间自动插入约 1/4 空格。2025 进入 Baseline。
- `text-spacing-trim`：中文标点字距调整，行首标点不再占满一格。
  按 MDN 浏览器兼容数据（2026-09-24 查）自 **Chrome 123** 起支持，
  **Safari 与 Firefox 均不支持**。

**前提是 `<html lang>` 正确。** 语言标签不对，浏览器不应用对应语言的断行
与标点规则。代码块里必须关掉——代码里的空格是有意义的。

Safari / Firefox 尚不支持，属渐进增强，不支持时版式不坏。

## 字重伪合成的识别

**先看 `font-synthesis-weight` 是不是 `none`。** 是 `none` 的话浏览器不会合成，
写 600 而字体没有 600 时它会去挑最近的真实字重（规范 §2.2.2：*a face with a
nearby weight is used*）——本站就是这一档。

若合成开着，表现才是笔画边缘发虚、与相邻字号比粗细不自然；
在 DevTools 的 `Rendered Fonts` 里能看到实际用到的字体与字重。

## 字体栈顺序

```css
font-family: 'Archivo', -apple-system, 'PingFang SC', 'Microsoft YaHei', sans-serif;
```

**拉丁字体必须在前。** 反了的话英文也会用中文字体渲染，
而中文字体里的拉丁字母是等宽的（为与汉字对齐），排版很难看。

配合 `unicode-range` 限定 webfont 只覆盖拉丁区，中文字符就不会触发
webfont 下载——**这不是回退，是分工。**

## 相关

- 完整论述与实测：[cjk-web-typography](https://xiaoxusop.github.io/letterpress/cjk-web-typography/)
- 本站的具体取值：[设计令牌](https://xiaoxusop.github.io/letterpress/wiki/design-tokens/)

## 参考

- [CSS Values and Units Level 4 §ch](https://www.w3.org/TR/2024/WD-css-values-4-20240312/#ch)
- [CSS Fonts Level 4 §2.2.2 Missing weights](https://www.w3.org/TR/2026/WD-css-fonts-4-20260913/#font-style-matching)

</doc>

<doc title="内容协商" path="wiki/content-negotiation.md">

> 用 HTTP 的 Accept 头决定返回 HTML 还是 markdown。算法只有四十行，难的是静态托管不解析请求头。

同一个 URL，对人和对 agent 返回不同格式的同一份内容。

标准依据是 RFC 9110 §12.5.1（Accept 头）与 RFC 7763（`text/markdown`）。
**这是 HTTP 从 1.1 就有的能力，不是新发明。**

## 判定算法

```
markdown = Accept 里显式声明的 text/markdown 或 text/x-markdown 中最优的
html     = Accept 里 text/html、application/xhtml+xml 或通配符中最优的

每个表示先按「具体类型 > 类型通配符 > 全局通配符」确定有效 q

若 markdown 不存在          → 返回 HTML
若 markdown 的 q 为 0       → 返回 HTML（q=0 是明确拒绝）
若 html 不存在              → 返回 markdown
若两者 q 不同               → 返回 q 大的那个
若 q 相同                   → 返回在头里排得更靠前的那个
```

## 三个会把实现写错的地方

**一、q 缺省为 1.0，平局比顺序。**

Claude Code 发 `text/markdown, text/html, <通配符>`，**不写 q 值**。
两者都是 q=1.0。用严格 `>` 比较会判定为「无偏好」从而返回 HTML——
不报错、不警告、日志干净，只是永远不生效。

**二、通配符不算「想要 markdown」。**

只发通配符的客户端（Gemini CLI、Windsurf）意思是「给什么都行」。
若把通配符算作 markdown 偏好，它们会被塞 markdown。
所以 markdown 一侧**只认显式声明**。

**三、`text/plain` 不是 markdown 请求。**

OpenCode 会带 `text/plain;q=0.8`，那是它的降级选项。
宁可漏给（客户端仍拿到可用的 HTML），不可错给。

**四、具体类型先于通配符。**

如果 HTML 被具体类型明确降权或拒绝，不能再用一个 q 更高的宽泛通配符把它放行。
RFC 9110 要求先选匹配该表示的最具体媒体范围，再比较不同表示的 q。

## 在静态托管上怎么实现

静态托管只吐文件，不解析请求头。所以需要两层：

1. **构建期**：为每个页面生成 `.md` 孪生文件（零运行时成本）
2. **边缘函数**：读 `Accept`，决定回哪个文件

项目里带了三个平台的实现：Cloudflare Pages Functions、Netlify Edge Functions、
Vercel Middleware。不用这一层站点照常工作，只是 agent 拿到 HTML。

## 必须做的两件事

- **`Vary: Accept`**——否则 CDN 会把 markdown 缓存下来发给浏览器。
  这个 bug 只在缓存命中时出现，会让人以为「有时候网站会坏」。
- **只在 markdown 是显式偏好时才返回**——见上面第二点。
- **声明表示关系**——`Content-Location` 指向 `.md` 孪生文件，`Link` 同时声明
  HTML canonical 与 markdown alternate，避免两种表示成为信息孤岛。

## 效果数据

| 来源 | 结果 |
|---|---|
| Cloudflare（自己的文档） | 80% token 减少 |
| Vercel（自己的博客） | 500 KB → 2 KB，99.6% |

## 回到本项目的代码

`src/lib/negotiate/accept.ts`。真值表用七个 agent 的**真实 Accept 原文**做回归，
固件在 `accept.test.ts` 里，注释写明了每一条的判定理由。

</doc>

<doc title="设计令牌" path="wiki/design-tokens.md">

> 三层 token 结构，命名描述用途而非外观。换配色时只动原始值，换暗色模式时只动语义映射。

`src/styles/tokens.css`。三层结构：

```
primitive  → 原始值。组件永不直接引用
semantic   → 按用途引用 primitive。组件只引用这一层
component  → 只在某个组件内有意义的派生值
```

**为什么分三层**：要换配色时只动 primitive；要换暗色模式时只动 semantic 的映射。
如果组件里直接写 `color: #002FA7`，上面两件事都得全库搜索替换，
而且一定会漏掉几处，于是暗色模式下出现一块刺眼的亮蓝。

命名描述**用途**而非外观：`--color-accent` 而不是 `--color-blue`。
这样把强调色从克莱因蓝换成别的时，名字不用改。

## 配色怎么定的

**一个强调色，其余全是中性灰。**

强调色取 International Klein Blue（`#002FA7`）——它是那个年代的产物，
与国际主义风格同源，不是随手挑的「好看的蓝」。

刻意避开的两个配色族：

- **紫蓝渐变**——AI 生成页面的第一识别特征
- **米色/奶油底 + 黄铜/陶土 + 浓咖啡近黑**——这个更隐蔽，
  因为它看起来「有品味」。但它已经成了 2026 年可识别的默认值，
  换成它只是把默认值换了个届，不是去 AI 味

## 亮暗不是反转

暗色模式**不是把亮色反过来**：反转会让层级关系也翻过来
（原本的「抬升」变成「下沉」）。这里按**表面亮度表达层级**重新排：
画布最暗（`#09090B`）、卡片略亮（`#131316`），靠亮度差而非阴影建立纵深。

强调色在暗色下也不是同一个值：`#002FA7` 放到深色底上对比度只有约 2:1，
读不了。暗色下用提亮版 `#6B91FF`。

## 间距用 4 单位基数

不是只用 8。因为 **8 的刻度缺少中间步**——想做「比 16 紧一点、但比 8 松」
的节奏时没有可用值，于是只能写一次性数值，节奏就散了。

## 圆角：全直角

瑞士风格的一致性锁：**要么全用一套，要么不用。**
混用（胶囊按钮 + 方卡片）是坏设计，除非有写下来的规则说明为什么。

## 相关

- 中文字号与行高的取值理由：[中文排版](https://xiaoxusop.github.io/letterpress/wiki/cjk-typography/)
- 项目本身：[letterpress](https://xiaoxusop.github.io/letterpress/wiki/letterpress/)

</doc>

<doc title="letterpress" path="wiki/letterpress.md">

> 本站所属的开源项目。一个把中文排版做对、同时写给人和 AI 读的静态博客主题。

一个开源个人博客主题。Astro 7 + TypeScript，纯静态，零后端，MIT。

## 它想解决的三件事

**一、中文排版普遍做错。** 行高、字重、行宽直接套西文的值，
[中文排版](https://xiaoxusop.github.io/letterpress/wiki/cjk-typography/) 里有完整的对照表。

**二、对 AI agent 不友好。** 静态博客没法做 [内容协商](https://xiaoxusop.github.io/letterpress/wiki/content-negotiation/)，
因为托管平台不解析请求头。项目带了三个平台的边缘函数实现。

**三、知识会腐烂。** 加一层 [LLM 知识库](https://xiaoxusop.github.io/letterpress/wiki/llm-wiki/)，把文章从「流」变成「网」，
并且把机械可判定的检查做成能进 CI 的 lint。

同一原则也用于构建本身：`npm run verify:reproducible` 会禁止生产源码读取构建时钟，
并在两个时区完整构建，逐文件比较 Astro 与 Pagefind 的全部产物，
而不是靠「代码看起来确定」来判断。

## 不做什么

- **不做生成器**。生成器赛道拥挤且被托管平台生态锁死。
- **不做数据库**。内容就是文件，躺在你的仓库里。
- **不用 Tailwind**。瑞士风格需要精确的网格与字体控制，
  手写 CSS + 自定义属性 + `@layer` 更直接，依赖面也更小。
  一个博客模板要活十年，这是优势。
- **不把 llms.txt 当卖点**。它的实际效果被严重高估，数据见 [内容协商](https://xiaoxusop.github.io/letterpress/wiki/content-negotiation/)。

## 技术选择

| 项 | 选择 | 理由 |
|---|---|---|
| 框架 | Astro 7 | 内容优先，默认零 JS，AI 爬虫不执行 JS |
| 样式 | 手写 CSS + `@layer` | 精确控制，零依赖，见 [设计令牌](https://xiaoxusop.github.io/letterpress/wiki/design-tokens/) |
| 字体 | 自托管拉丁子集 + 系统中文字体 | 中文字体 5–20 MB，不值得 |
| 内容协商 | 构建期孪生 + 边缘函数 | 转换零运行时成本 |

## 相关

- 写作与使用：`how-this-works`
- 排版细节：[中文排版](https://xiaoxusop.github.io/letterpress/wiki/cjk-typography/)、[设计令牌](https://xiaoxusop.github.io/letterpress/wiki/design-tokens/)

</doc>

<doc title="LLM 知识库" path="wiki/llm-wiki.md">

> Karpathy 2026 年 4 月提出的模式——让 agent 主动读写并维护一层知识库，新素材进来时做的是「重构」而不是「追加」。

一份由 AI 持续读写的结构化知识库，通常就是一堆 markdown 文件。

与**基础 RAG 用法**的区别：那种做法里新文档进来只是被**加进索引**，
已经索引的内容不会被改写；而 LLM 知识库里新素材进来会触发一次**编译**——
更新既有页面、建新页、加链接、标记矛盾。有人的说法是
「摄取是一次重构，不是一次追加」。

> **补一句分寸（2026-09-22）**：这里原先写的是「RAG 里新文档只会被索引，
> **永不改变、永不连接**」。**「RAG 都这样」是错的**——比如
> [GraphRAG](https://microsoft.github.io/graphrag/) 就会从资料里抽出实体与关系、
> 组织成图并预计算摘要。所以本项目的取舍应当表述为
> **「我们选择保存可编辑、可审阅的综合页面」**，而不是「所有 RAG 都不积累知识」。
> 检索与知识整理可以共存，不是互斥的两条路。

> **关于「一份来源可能改动 10 到 15 个页面」这个数**（勘误，2026-09-24）：
> **它是有出处的**——Karpathy 的原始 gist 在 Ingest 段落里写着
> `A single source might touch 10-15 wiki pages.` 本页此前写「没有出处」，
> **那是错的**，现已逐字核对原文并补上链接。
>
> 该修的仍然要修：那句话是**作者描述自己工作流时的经验性例子**，
> 不是普遍规律，所以**不能泛化、也不该当本项目的 KPI**。
> 「有出处」与「可泛化」是两件事——**前者这次补上了，后者仍然不成立。**
> 把页面改动数当指标会催生为了改而改。

## 三层结构

| 层 | 作用 | 本项目里对应 |
|---|---|---|
| 原始素材 | 原则上不可变的输入 | **尚无独立登记**。文章（`src/content/posts/`）可充当素材，但它们**会被修订**，引用时需钉具体版本 |
| 知识层 | agent 维护的结构化页面 | `src/content/wiki/` |
| schema | 告诉 agent 怎么维护 | `AGENTS.md` |

## 三个操作

- **摄取（Ingest）**：读入来源，写摘要页，更新索引与相关条目页
- **查询（Query）**：从相关页面综合出答案，并给出处
- **体检（Lint）**：检查矛盾、过时、孤儿页、断链

## 已实现 / 计划实现

| 能力 | 状态 |
|---|---|
| 知识层页面（`src/content/wiki/`）与互链 | **已实现** |
| 机械检查（`src/lib/wiki/lint.ts`）进 CI | **已实现** |
| 文章 → 知识页的人工综合 | **已实现**（本页就是） |
| 来源登记与版本固定 | **已实现**（`knowledge/sources/`） |
| 页面级的引用与复核字段 | **已实现**（`Doc.sources` / `Doc.review`） |
| 摄取 / 影响分析的工作流脚本 | **已实现**（`scripts/wiki-impact.mjs`） |
| 面向 agent 的检索与问题金标 | **已实现**（`knowledge/questions.md`） |
| 语义级的矛盾检测（「这两页说法冲突」） | 计划中，尚未实现 |

> 这张表是 2026-09-22 补的。此前本页通篇以「本项目怎么做」的口吻描述这套模式，
> 而其中大半尚未落地——**读者无从分辨哪些是真的、哪些是打算做的**。
>
> **勘误（2026-09-23）**：这张表自己就出过这个毛病。上面三行原先写着
> 「计划中，尚未实现」，而它们**在写下那句话的时候就已经落地了**——
> 来源登记（`knowledge/sources/`）、引用与复核字段（`Doc.sources` / `Doc.review`）、
> 影响分析脚本（`scripts/wiki-impact.mjs`）全都存在。
> **没有任何检查会发现这件事**：lint 管的是断链、重复 slug、孤儿页，
> 那些都是**页与页之间**的问题；而这一条是**页与仓库之间**的问题。
>
> 现在这张表的每一行都带一条 `verify:` 声明（见本页 frontmatter）：
> 检查同时核对**那句话还在不在页面上**、以及**它对应的文件在不在**。
> 只查文件是不够的——正文改了、声明没改的话，声明还在验一句没人说过的话。

## 本项目的取舍：把 lint 做成确定性的

Karpathy 那套的体检是「让 agent 定期看看」。这**不是工程方案**——
它不可复现、不可回归、进不了 CI。

所以本项目只把**机械可判定的那部分**做成代码（`src/lib/wiki/lint.ts`）：

- 断链、重复 slug → 错误级，构建失败
- 孤儿页、缺摘要、空正文 → 警告级
- 摘要过长 → 提示级

**语义级的检查仍然留给 agent**（「这两页说法矛盾」「这条结论已被推翻」），
但地基是机械的。没有地基的话，agent 每次检查的结论都不一样，
你没法判断「这次多了三条告警」是内容变了还是模型心情变了。

## 与「数字花园」的关系

数字花园（digital garden）强调**公开的、持续演化的笔记**，
不按时间排列，靠链接组织。LLM 知识库是它的一个变体：
区别在于**维护者从人换成了 agent**。

两者面对同一个问题：**怎么防止腐烂**。花园派的做法是「定期打理」，
LLM 知识库派的做法是「让 agent 定期重构」。本项目认为两者都不够，
**机械检查必须先进 CI**。

## 为什么博客适合这个模式

博客天生是**流**——按时间排，读过就沉底。
但知识是**网**：你写过三篇关于排版的文章，它们之间的共性不会自动浮现。

加一层知识库，文章仍然是流（读者的入口），但知识层把散落各篇的东西
连起来。读者（和人以外的读者）不必读完所有文章才能拼出全貌。

## 参考

- [Andrej Karpathy 的 `llm-wiki` gist](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f)，2026-04
  —— 本文的模式取自它；注意它是**抽象模式**，不是框架或 npm 包。
  上面「10–15 个页面」那句即出自它的 Ingest 段落，原文为
  `A single source might touch 10-15 wiki pages.`
- DeepWiki（2025-05）、LangChain OpenWiki（2026-07）、微软 deep-wiki 插件
- llmstxt.org 提案——注意其实际效果数据见 [内容协商](https://xiaoxusop.github.io/letterpress/wiki/content-negotiation/) 末尾

</doc>

<doc title="中文网页排版，多数主题都做错了" path="cjk-web-typography.md">

> 行高、字重、行宽、中西文间距——这四个参数直接套西文的值，中文读者看到的是一份「能读但别扭」的页面。2026 年有三个原生 CSS 属性可以修好其中一半。

中文网页排版有个奇怪的现象：**大家都觉得别扭，但很少有人能指出哪里别扭。**

原因多半是这四个参数被直接沿用了西文的值。它们单独看都不致命，
叠在一起就是那种说不清的「不对劲」。

## 一、行高

西文正文的常用行高是 1.4 到 1.5。这个值搬到中文上会显得挤。

因为汉字是**方块字**：笔画在字面内铺得很满，字与字之间没有西文那种
由升降部带来的天然空隙。同样行高下，中文的行间留白视觉上更少。

中文正文的行高应当在 **1.6 到 1.8** 之间。本站用的是 1.75。

还有个细节：行高要用**无单位数值**（`line-height: 1.75`），不要用 `px` 或 `em`。
无单位值是相对于元素自身字号计算的，继承时不会出乱子。

## 二、字重

这条最容易被忽略，但效果立竿见影。

**很多中文字体只有两个真实字重：400 和 700。** 苹方有 Ultralight 到 Semibold，
思源黑体有 300 到 900 的完整字重；微软雅黑主要就是 400 和 700。
（Apple 官方系统字体清单里列有 `PingFang SC Semibold`，
见 [System Fonts](https://developer.apple.com/fonts/system-fonts/)。）

这里的通行说法是「写 600 会触发伪合成，所以只能写 500」。**这话只说对了一半。**

伪合成的开关不是字重数值，而是 **`font-synthesis-weight`**。至于字重本身——
写一个字体没有的字重时，规范要求的是**去找最接近的真实字重**，不是伪造一个：

> When a weight is specified for which no face exists, a face with a
> nearby weight is used.
> —— [CSS Fonts Level 4 §2.2.2](https://www.w3.org/TR/2026/WD-css-fonts-4-20260913/#font-style-matching)

**「最接近」具体朝哪边找，规范给了确定规则**（§5 字重匹配）：
请求的字重**大于 500** 时，先按升序检查**不小于**目标的字重
（600 → 700 → 800 → 900），都找不到再向下找。于是：

- 苹方这类**确有 600** 的字体 → 请求 600 **直接命中 600**，不会跳到 700；
- 微软雅黑这类**只有 400/700** 的字体 → 请求 600 先查 700，**落到 700**。

两条路径**都不会伪造粗体**（前提是没开伪合成）：开着合成时它才会把 400
算法加粗——笔画发虚、字形走样，而且每个浏览器合成得还不一样。

本站的做法是把合成直接关掉：

```css
html {
  font-synthesis-weight: none;
}
```

于是标题可以写 `font-weight: 600`：拉丁部分拿到 Archivo 的真实 600，
中文部分落到**自己字体里最接近 600 的真实字重**（苹方约 600、雅黑 700），
两者视觉重量相当。
（反过来，写 500 的话中文更容易掉到 **400**——比正文还轻，标题反而立不住。）

更重要的是：**层级主要靠字号和颜色建立，不要靠字重硬拉。**
一段 17px/400 的正文和一段 21px/600 的小标题，层级已经足够了。

> **勘误（2026-09-22）**：这一节原先写的是「正确做法：标题字重写 500，
> 让字体自己去挑最接近的真实字重」。**结论和建议都改掉了**：把伪合成归因到
> 字重数值本身是错的——开关是 `font-synthesis-weight`；而在关掉合成的实现里，
> 写 500 会让中文落到 400，比 600 更糟。
> 依据见 [CSS Fonts Level 4 的字重匹配](https://www.w3.org/TR/2026/WD-css-fonts-4-20260913/#font-style-matching)
> 与本站 `src/styles/base.css` 的 `font-synthesis-weight`。

## 三、行宽

这是四个里最麻烦的一个，因为中西文的最优值**在同一个单位下对不齐**。

西文的理想行宽是 45 到 75 个字符，66 是经典值。而 `ch` 这个单位
是为西文设计的——按规范，它等于**渲染所用字体**里「0」字形的宽度：

> `ch` — Represents the typical advance measure of **European** alphanumeric
> characters, and measured as the used advance measure of the "0" (ZERO,
> U+0030) glyph **in the font used to render it**.
> —— [CSS Values and Units Level 4](https://www.w3.org/TR/2024/WD-css-values-4-20240312/#ch)

两个要点：它是**欧洲字符**的度量，而且**取决于字体**。所以 `ch` 换算不出一个
跨字体稳定的汉字数——换个字体，「66ch 能排几个汉字」这个数就变了。

粗估的话，一个汉字约等于两个 `ch`，66ch 大约排 **33 个汉字**。
（顺带一提，这个数其实落在中文舒适的 30–40 字里——但它是粗估，且随字体浮动。）

本站改用 `em`，图的是**可预测**：

```css
.prose {
  max-width: 34em;
}
```

`em` 等于元素的字号，这是规范保证的，且**不依赖字体**。
但「一个汉字正好 1em 宽」**不是规范保证**——汉字的 advance 取决于具体字体，
规范为此专门定义了一个 `ic` 单位来表示「字体中全角字形的典型 advance」，
并规定在无法确定时**假设为 1em**：

> The `ic` unit is … a typically exact measure (in the few fonts with proportional
> fullwidth glyphs, an approximation) of a single fullwidth glyph's advance measure.
> In the cases where it is impossible or impractical to determine the ideographic
> advance measure, it must be assumed to be `1em`.
> —— [CSS Values and Units Level 4 §5.1.1](https://www.w3.org/TR/2024/WD-css-values-4-20240312/#ic)

**这一句本身就说明「容器宽度单位」和「实际字形宽度」不能混为一谈**——
如果规范能保证两者相等，就不必再定义 `ic` 了。

所以准确的说法是：34em 让内容栏宽度**稳定地跟随字号**；
对常见全角汉字可**近似**理解为约 34 字，但**实际每行字数仍受字体、标点、
字距和混排影响**。于是：

- 中文：约 34 个字（近似，落在 30–40 的理想区间）✅
- 西文：约 68 个字符（近似，落在 45–75 的理想区间）✅

**一个值同时覆盖两种文字的舒适区，而且容器宽度不随字体变。** 这是
`--measure: 34em` 的由来。**注意被保证的是「宽度稳定」，不是「字数确定」。**

> **勘误（2026-09-22）**：这一节原先写的是「一个汉字大约等于两个 `ch`，
> 所以按 66ch 排中文，每行会排出约 130 个汉字——远超出中文舒适的 30 到 40 字」。
> **两处都错**：按它自己的前提应当除以 2 得 33，而不是乘以 2 得 130；
> 而 33 本来就落在它自己说的舒适区间内，所以「远超」这个结论也不成立。
>
> 这句话还遮住了一个更关键的事实：**66ch ≈ 33em，与本题采用的 34em 宽度几乎相同**
> （这一步依赖「0 字形约 0.5em」这个假设，是推算而非实测）。
> 也就是说这个改动换来的是**容器宽度的可预测性**，不是行宽。
> **结论（用 em）不变，论证方式改了。**
>
> 依据：[CSS Values and Units Level 4 §ch](https://www.w3.org/TR/2024/WD-css-values-4-20240312/#ch)、
> [§ic](https://www.w3.org/TR/2024/WD-css-values-4-20240312/#ic)。
>
> **勘误（2026-09-24）**：上一条勘误之后，本节仍留着
> 「`em` 等于字号、与字体无关。一个汉字约 1em 宽……**而且不随字体变**」，
> 并据此把 `34em` 说成确定的字数换算。**前半句对，后半句越界了**：
> 规范保证的是 `em` 等于**计算后的 font-size**，
> 不保证**每个汉字的 advance 恒等于 1em**——所以「34em ≈ 34 字」是近似，
> 而「**每行字数确定**」这句话是不成立的。详见上面引的 `ic` 那段。

## 四、中西文间距与标点

中文和英文、数字之间应该有一个小间隙：「共 500 条记录」比「共500条记录」好读。

过去这件事要靠 [pangu.js](https://github.com/vinta/pangu.js) 之类的库在
客户端跑一遍正则，找到边界然后插空格。它有一堆边缘情况（全角标点前后不加、
`90°` 不加、`15%` 不加），而且要在 DOM 加载后重写文本。

**2026 年浏览器原生做了这件事：**

```css
html {
  text-autospace: normal;
  text-spacing-trim: trim-start;
}
```

- `text-autospace: normal` 自动在中西文之间插入约 1/4 个空格。2025 年进入 Baseline。
- `text-spacing-trim: trim-start` 做中文标点的字距调整——行首的逗号句号
  之类不再占满一格。Chrome / Edge 123+ 已默认开启。

两个前提：**`<html lang>` 必须设置正确**，否则浏览器不会应用对应语言的规则；
代码块里要关掉自动间距，因为代码里的空格是有意义的：

```css
pre, code, kbd, samp { text-autospace: no-autospace; }
```

**只有 Chromium 系支持**：MDN 的浏览器兼容数据（2026-09-24 查）
记 Chrome 自 123 起支持，**Safari 与 Firefox 均为「不支持」**——
`caniuse` 上还没有这个特性（太新）。
所以它是**渐进增强**——不支持的浏览器只是少了那一点调整，版式不会坏。

> **本项目此前在这里写的是「全球覆盖约 72%」，现已删除。**
> 那个数字**没有任何来源**（caniuse 抓不到、本项目也没实测过），
> 而它写在一个「实测」味道很重的段落里。
> **一个查不到来源的覆盖率，比不写更糟**——读者会以为它是量出来的。

## 五、一条容易漏的：中文没有斜体

中文字体不提供斜体字形。`font-style: italic` 对中文的结果是浏览器
**合成倾斜**——把笔画整体拉斜，字形变形、笔画糊在一起。

而 CSS 没法问「这段 `<em>` 里是中文还是西文」。所以务实的选择是：
**统一把强调处理成加粗**，这也是中文排版的通行做法。

```css
em, i {
  font-style: normal;
  font-weight: 600;
}
```

## 六、字体栈的顺序

最后一条，顺序不能反：

```css
font-family: 'Archivo', -apple-system, 'PingFang SC', 'Microsoft YaHei', sans-serif;
```

**拉丁字体必须排在前面。** 如果中文字体排在前面，英文也会用中文字体渲染——
而中文字体里的拉丁字母是等宽的（为了和汉字对齐），排版上很难看。

顺序对了之后，英文用 Archivo 渲染，汉字自动落到苹方/雅黑，各取所长。

## 那要不要自托管中文字体

**默认不要。** 中文字体单文件 5–20 MB，哪怕做了子集化，一个博客站也不该
为此付出首屏时间。而中文系统字体（苹方、微软雅黑、思源黑体）质量本身就很好——
知乎、Medium 中文版这类大站的内文都用系统字体。

实在需要自定义时，用 [cn-font-split](https://github.com/KonghaYao/cn-font-split)
做子集化，并且务必用 `unicode-range` 限定覆盖面。

## 小结

| 参数 | 西文常用 | 中文应用 |
|---|---|---|
| 行高 | 1.4–1.5 | **1.6–1.8** |
| 标题字重 | 600–700 | **600**（配 `font-synthesis-weight: none`） |
| 行宽 | 66ch | **34em**（≈34 汉字 / ≈68 西文字符，**均为近似**） |
| 中西文间距 | 手动加 | **`text-autospace`** |
| 强调 | 斜体 | **加粗** |

这些细节单独看都很小。但它们同时出现时，读者的感受就是「这个站读起来舒服」
而说不出为什么——那正是排版该有的样子。

相关条目：[中文排版](https://xiaoxusop.github.io/letterpress/wiki/cjk-typography/)、[内容协商](https://xiaoxusop.github.io/letterpress/wiki/content-negotiation/)。

## 参考

- [CSS Values and Units Level 4 §ch](https://www.w3.org/TR/2024/WD-css-values-4-20240312/#ch) —— `ch` 的定义
  （W3C Working Draft, 12 March 2024）
- [CSS Fonts Level 4 §2.2.2 Missing weights](https://www.w3.org/TR/2026/WD-css-fonts-4-20260913/#font-style-matching) —— 缺少字重时如何匹配
- [CSS Fonts Level 4 §font-synthesis-weight](https://www.w3.org/TR/2026/WD-css-fonts-4-20260913/#font-synthesis-weight) —— 伪合成的开关
  （W3C Working Draft, 13 September 2026）

> **为什么链接带日期而不是 `/TR/css-values-4/`**：后者是"最新版"，
> 会随规范修订移动——半年后回看，不知道当时引的是哪一版。
> W3C 自己推荐的引用方式就是带日期的固定 URL。

---

**修订记录**

- **2026-09-12** 发布。
- **2026-09-22** 勘误：行宽一节把「一个汉字 ≈ 2 `ch`」算反了（应除以 2 得 33，
  原写作乘以 2 得 130），连带「远超舒适区」的结论也不成立；字重一节把伪合成
  归因到字重数值上，而开关其实是 `font-synthesis-weight`，且在关掉合成的实现里
  写 500 会让中文落到 400。两处的**结论都保持不变**（用 `em`、标题用 600），
  改的是论证与依据。同步修订了 [中文排版](https://xiaoxusop.github.io/letterpress/wiki/cjk-typography/)。
- **2026-09-24** 勘误：上一轮只改了那句算错的算式，**却留下了更大的越界**——
  「`em` 等于字号、与字体无关」被推广成「一个汉字正好 1em 宽、每行字数确定」。
  规范保证的只是 `em` 等于**计算后的 font-size**；它为此专门定义了 `ic`
  来表示全角字形的典型 advance，无法确定时假设 1em。
  同时**苹方字重结论与 Apple 官方清单冲突**（清单里确有 `PingFang SC Semibold`），
  且「请求 600 必落 700」是条件句：匹配算法对 >500 的请求**先向上找**，
  有真 600 的字体直接命中 600。

</doc>

<doc title="这个博客是怎么搭的" path="how-this-works.md">

> 改一个配置文件就能上线，文章放在一个目录里，知识层会自动长出链接图。这一篇解释目录结构、写作流程，以及怎么把它换成你自己的。

这一篇是写给你的——如果你 clone 了这个项目，它会告诉你东西都在哪。

## 你只需要改一个文件

`src/config.ts`。里面的 `site`、`author`、`nav` 三项改完就能上线：

```ts
export const site: SiteConfig = {
  title: '你的站名',
  tagline: '一句话说清这个站是什么。',
  url: 'https://example.com',   // 部署前填，不留斜杠
  lang: 'zh-CN',                // 别改错——浏览器的中文标点规则依赖它
  author: { name: '你的名字', bio: '一句话介绍自己。' },
  // …
};
```

**其余全部有可用的默认值，而且默认值本身就是完整站点，不是占位符。**
你现在看到的这些文章和知识库条目就是示例内容——它们是真的能读的，
不是 `lorem ipsum`。删掉它们换成你自己的即可。

## 东西都在哪

```
src/
├── config.ts            你唯一必须改的文件
├── content/
│   ├── posts/           文章。按时间排
│   └── wiki/            知识层。按主题互链
├── layouts/             页面骨架
├── components/          组件
├── pages/               路由
├── lib/                 纯逻辑（可测试，不依赖 Astro）
│   ├── negotiate/       Accept 头解析——[[内容协商]] 的实现
│   └── wiki/            链接图、体检、llms.txt 生成
└── styles/
    ├── tokens.css       设计令牌
    ├── base.css         基线排版（含 [[中文排版]] 的那些修正）
    └── site.css         布局与组件
```

## 两种内容，两种组织方式

**文章**放在 `src/content/posts/`，按时间排列，是「流」。

**知识库条目**放在 `src/content/wiki/`，按主题互链，是「网」。

它们的区别不是格式，是**读者找东西的方式**：想看你最近写了什么就翻文章，
想搞清某个概念就查知识层。两边的条目地位相同，可以互相引用。

## 用 `[[方括号]]` 连起来

在任何地方写 `[[目标]]`，就会生成一条链接：

```markdown
见 [[内容协商]] 一节。
```

支持三种写法：

| 写法 | 效果 |
|---|---|
| `[[内容协商]]` | 链接，显示文本即目标名 |
| `[[内容协商\|那篇]]` | 自定义显示文本 |
| `[[内容协商#为什么]]` | 指向页内某小节 |

目标可以写 slug，也可以写标题——你大概不会记得每篇的 slug 是什么。
解析时**大小写和空格都不敏感**。

写错了不会静默失败：构建时会报一条 `broken-wikilink` 错误，
并告诉你**哪个页面引用了什么**。

## 构建时会做体检

每次构建会跑一遍知识库体检，输出在控制台。分三级：

- **错误**：断链、两个页面抢同一个 URL、文章占用 `/about/` 等系统路由、
  引用了没登记的来源、复核状态与正文对不上。
  **会让构建失败**（可在配置里关掉）
- **警告**：孤儿页（没有任何页面指向它）、缺摘要、空正文、
  同一关系在正文与 `related` 里各写了一次
- **提示**：摘要过长之类的建议

**这不是可选的装饰。** 一个由人（或 agent）持续维护的知识库，
最容易的结局是慢慢烂掉——改了标题没改引用、删了页面留下断链。
机械的检查必须能进 CI，否则「知识库」会退化成「一堆文件」。

完整的规则表在 `AGENTS.md`——那份是**写给 agent 看的**，改规则时两边要一起改。

## 给 AI 读者那一份

这一站有两个出口，服务两类读者：

**Markdown 孪生文件。** 每篇文章和知识页都有可直接访问的 `.md` URL。
在支持内容协商的部署平台上，请求页面 URL 时带上 `Accept: text/markdown`
也会得到 markdown；本站使用 GitHub Pages，因此应直接访问 `.md` 链接。
原理和托管限制见 [内容协商](https://xiaoxusop.github.io/letterpress/wiki/content-negotiation/)。

**目录与全文。** `/llms.txt` 是给 agent 看的目录（标题 + 一句话说明），
`/llms-full.txt` 是全文内联版。每个页面还有 `.md` 孪生文件，
比如 `/how-this-works.md`。

需要说明的是：**`llms.txt` 的实际效果被高估了**——
Ahrefs 实测 13.7 万个域名里 97% 的 llms.txt 从未被请求过。
本站生成它是因为零成本，但主要依靠显式 `.md` 链接、内容清单和干净的 HTML。

## 部署

静态产物，任何静态托管都能跑。但**内容协商需要一层边缘函数**——
因为静态托管不解析请求头，它只会把文件原样吐出来。

项目里带了三个平台的现成实现，**选你用的那个**：

| 平台 | 边缘函数 | 平台配置 |
|---|---|---|
| Cloudflare Pages | `functions/[[path]].ts` | `public/_headers`（会被拷进产物） |
| Netlify | `netlify/edge-functions/negotiate.ts` | 无额外配置 |
| Vercel | `middleware.ts` | `vercel.json` |

不想要这一层也没关系，站点照常工作，只是 agent 拿到的是 HTML 而不是 markdown。

## 详细说明

- 排版与设计决策：[中文排版](https://xiaoxusop.github.io/letterpress/wiki/cjk-typography/)、[设计令牌](https://xiaoxusop.github.io/letterpress/wiki/design-tokens/)
- 知识层的设计取舍：[LLM 知识库](https://xiaoxusop.github.io/letterpress/wiki/llm-wiki/)

</doc>

<doc title="你的博客该不该给 AI 一份 markdown" path="markdown-for-agents.md">

> 内容协商是 HTTP 自带的能力，但博客圈几乎没人用。三个 agent 会主动要 markdown，四个不会——而现有工具都跳过了最难的那一步。

一个 AI agent 抓取你的网页时，看到的东西和你看到的不一样。它看到的是两万个
token 的导航栏、页脚和 `<div>` 嵌套，而正文可能只占其中百分之几。

这不是比喻。Cloudflare 实测自己的文档：同一页 HTML 要 16,180 token，
markdown 版只要 3,150 token——**省 80%，内容一模一样**。

HTTP 从 1.1 起就有解决这个问题的机制：内容协商。客户端在 `Accept` 头里说
「我更想要 markdown，不行的话 HTML 也行」，服务端照办。

问题是：**博客圈几乎没人用。**

## 谁在要 markdown

拿七个常见 agent 去请求 `httpbin.org/headers`，
看它们各自发出的 `Accept` 头。结果是这样的：

| Agent | 要 markdown 吗 | Accept 头 |
|---|---|---|
| Claude Code | 是 | `text/markdown, text/html, */*` |
| Cursor | 是 | `text/markdown`, `text/html;q=0.9`, … |
| OpenCode | 是 | `text/markdown;q=1.0`, `text/x-markdown;q=0.9`, … |
| OpenAI Codex | 否 | `text/html`, `application/xhtml+xml`, … |
| GitHub Copilot | 否 | `text/html`, `application/xhtml+xml`, … |
| Gemini CLI | 否 | 通配符 |
| Windsurf | 否 | 通配符 |

七个里三个主动要。**而这七行数据本身就是一份测试用例**——见
[内容协商](https://xiaoxusop.github.io/letterpress/wiki/content-negotiation/) 里关于怎么把它钉成回归测试的部分。

## 一个安静失败的实现细节

Claude Code 那一行值得单独说。

它发的是 `text/markdown, text/html, */*`——**没有 q 值**。在 HTTP 里，
缺省 q 值等于 1.0，于是 markdown 和 html 两个媒体范围并列。

**这里要说清楚：RFC 并没有规定并列时怎么打破平局。**
[RFC 9110 §12.5.1](https://www.rfc-editor.org/rfc/rfc9110.html#section-12.5.1)
规定的是「媒体范围可以被更具体的范围覆盖，**更具体的优先**」——
它按*具体程度*排序（`text/plain;format=flowed` → `text/plain` → `text/*` → `*/*`），
而对 q 值相同的两个类型，规范只说它们是 *equally preferred*，没有给顺序。

所以「靠前的优先」是**本项目的实现选择**，不是规范要求。

但如果实现里写的是严格的 `>` 比较：

```js
if (markdown.q > html.q) return 'markdown';
return 'html';
```

那么 `1.0 > 1.0` 为假，判定落到 HTML 上。**Claude Code 永远拿不到 markdown，
而服务端不报错、不警告、日志里什么都没有。** 你只会觉得「这功能好像没用」。

本项目的做法是**并列时比顺序**（如上所述，这是选择而非规范要求）：

```js
if (markdown.q !== html.q) return markdown.q > html.q;
return markdown.index < html.index;
```

这类 bug 的可怕之处在于它**不会以错误的形式出现，只会以「没效果」的形式出现**。

## 为什么现成的工具都不太行

Astro 生态里已经有两个包在做这件事，但都停在半路：

- **astro-markdown-for-agents**：在构建期生成 `.md` 文件，但协商**只在 dev server 里生效**。
  它的 README 直说：「不包含托管平台运行时垫片；静态托管环境下的服务时协商
  应由使用方自行实现。」也就是说**上生产就没了**。
- **astro-markdown-export**：把源 `.md` 复制进产物目录，**完全不做协商**。
  要访问 `/slug/index.md` 才拿得到，而且导出的是未渲染的源文件。

两者的周下载量分别是 106 和 17。而主流 Astro 集成是三十万到两百万。
**这不是「已经解决了只是没人知道」，是「有人碰过就放弃了」。**

## 难在哪

难的不是算法——算法上面已经写完了，四十行。

难的是**静态托管不解析请求头**。静态站就是一堆文件，CDN 把文件原样吐出来，
它不会因为你 `Accept` 写了什么就换一个文件给你。所以你需要一层边缘函数。

这也是为什么 Cloudflare 的 Markdown for Agents 要 Pro 及以上套餐——
它是在边缘替你做了转换。而 Vercel 的实现只在自己的平台内生效。
**跑在免费静态托管上的博客，两头都够不着。**

出路是：构建期生成 `.md` 孪生文件，再用一层几十行的边缘函数做选择。
转换在构建期完成（零运行时成本），边缘只负责「给哪个」。
Cloudflare Pages Functions、Netlify Edge Functions、Vercel Middleware
的免费额度都够用。

## 两件必须做对的事

**一、`Vary: Accept` 不能省。** 少了它，CDN 会把 markdown 版本缓存下来
发给浏览器——用户打开博客看到一坨纯文本。这是个会让人当场关掉标签页的 bug，
而它只在缓存命中时出现。

**二、`*/*` 不算「想要 markdown」。** Gemini CLI 和 Windsurf 只发通配符，
意思是「给什么都行」。如果把通配符也算作 markdown 偏好，这两家会被塞
markdown——它们本来接受 HTML，你硬给别的格式，属于自找麻烦。

## 顺带说一句 llms.txt

你可能想问为什么不提 `llms.txt`。因为它的实际效果被严重高估了：

- **Google 明说不需要。** Search Central 的 AI 功能文档里写着：

  > You don't need to create new machine readable files, AI text files,
  > or markup to appear in these features.

  注意原文说的是「**不需要**」而不是「不支持」——不做也不会因此缺席，
  但 Google 也没说它有害。
  （[原文](https://developers.google.com/search/docs/appearance/ai-features)）
- 多个独立实验都没测到可归因的效果。

> **这组数字曾经被删掉过，2026-09-24 找回来了。** 这里原先写
> 「Ahrefs 2026 年 5 月实测 137,210 个域名：97% 的 llms.txt 从未被请求过」。
> 上一轮我按几种常见路径试 `ahrefs.com/blog/*` 全部 404、Ahrefs 自己的
> sitemap 里没有收录博客，于是**把整组数字删了**，并写明「查不到就不该留着」。
>
> 那个删除是**对的推理、错的结论**：原文确实存在，地址是
> <https://ahrefs.com/blog/llmstxt-study/>，此前只是没试中路径。
> 2026-09-24 重新抓取原文逐字核对，数据全部对得上：
>
> - 样本：Ahrefs Web Analytics 中**2026 年 5 月**获得流量的全部 **137,210** 个域名
>   （方法学章节原文：`all 137,210 domains ... that received traffic in May 2026`）；
> - 其中 28% 发布了 `llms.txt`；
> - 这些文件的 **97% 在 2026 年 5 月零请求**——`97% of those files received zero traffic in May 2026`；
> - 有请求的那 3% 里，**96% 的请求来自 bots**。
>
> **发布日期与数据窗口是两件事**：原文发布于 **2026-06-15**，
> 统计的是 **2026 年 5 月**。先前的写法把两者混成了「2026 年 5 月实测」。
>
> 留着一个可点开的来源，比留着一句「查不到」更有用；
> 但**边界也要跟着一起写**：这是对 `llms.txt` 根文件的 HTTP 200 探测，
> 不是对「AI 有没有读到内容」的观测——**被请求的 3% 里，77% 的 bots 并不是 AI 工具**。

它**零成本、无下行风险**，而且确实有 agent 会抓（Claude Code 抓取 llms.txt
的频率高于任何 AI 搜索机器人），所以本站在生成它。但把它当卖点是误导。

真正的杠杆是**干净的内容协商**和**语义化的 HTML**——后者对静态站来说是白送的。

## 参考文献

- [RFC 9110 §12.5.1（Accept 头）](https://www.rfc-editor.org/rfc/rfc9110.html#section-12.5.1)、
  [RFC 7763（`text/markdown` 媒体类型）](https://www.rfc-editor.org/rfc/rfc7763.html)
- [Cloudflare, *Markdown for Agents*](https://blog.cloudflare.com/markdown-for-agents/)
  —— 正文里「16,180 → 3,150 token、省 80%」那组数字出自这里。
  **测量条件是 Cloudflare 拿自己的文档做的，本项目没有复现它**；
  它说明的是「干净 HTML 转 markdown 能省多少」，不是本站的节省率
  （本站自己的数字在 [内容协商](https://xiaoxusop.github.io/letterpress/wiki/content-negotiation/) 末尾，且是**启发式估算**，那里附了真实词表的对照）
- [Google Search Central, *AI features and your website*](https://developers.google.com/search/docs/appearance/ai-features)
  —— 正文里「Google 明说不需要」那段引文出自这里
- [Ahrefs, *We Analyzed 137K Sites: 97% of llms.txt Files Never Get Read*](https://ahrefs.com/blog/llmstxt-study/)，
  2026-06-15 发布、数据窗口为 2026 年 5 月
  —— 正文里 137,210 / 97% / 96% 那组数字出自这里。
  **测量条件是 Ahrefs 拿自己的流量数据做的，本项目没有复现它**；
  它观测的是「根文件有没有被请求」，**不是**「AI 有没有读到内容」——
  被请求的那 3% 里 77% 的 bots 并不是 AI 工具
- ~~Ahrefs 那组数字原先作为一条独立引用，2026-09-23 被移除。~~
  **2026-09-24 找到了原始地址并已恢复**（见上一条）——
  那一轮的删除是**对的推理、错的结论**：`ahrefs.com/blog/*` 几个常见路径全 404
  只证明了「我按这几个路径没找到」，不等于「原文不存在」。
  **一个找不到的路径不是不存在的证据。**

> **勘误（2026-09-22 / 09-23 / 09-24）**：这几条原先都是纯文本、点不开，已核实的补了链接；
> **09-23 那一轮把 Ahrefs 那条当作「核实不到」移除了，09-24 又找回来了**——
> 因为原文一直存在，只是当时试的路径没命中。
> 三轮下来值得记住的是：**「我没找到」和「它不存在」之间隔着一整条推理链**，
> 跳过那条链就会把一次失败的检索固化成一条结论。

</doc>

<doc title="构建可复现比你想的难，而且它值得" path="reproducible-builds.md">

> 同一份源码在两台机器上构建出不同的产物——这件事的代价不是洁癖，是你没法用 diff 判断"这次改动干了什么"。

「同一份源码应该构建出同一个产物」听起来像句废话。

但它在大多数项目里**并不成立**，而且失败方式全都极其安静：
构建照常成功，产物照常能用，只是**每次都不一样**。

代价在后面才显现：你没法用 diff 判断「这次改动到底改了什么」，
因为产物里全是无关噪声。

## 那些让构建不可复现的东西

按我实际踩到的顺序：

**一、时间戳。** 最容易想到，也最容易修。但它的变体很多：产物里嵌构建时间、
日志文件带时间、`Date.now()` 漏进某个 ID 的计算。

**二、文件系统的枚举顺序。** 目录里读文件不会保证顺序。你在本地按 A、B、C 遍历，
CI 上可能是 C、A、B——于是拼接出的产物顺序不同。

修法是**显式排序**：

```js
const files = await readdir(dir);
files.sort();   // 这一行不是可选的
```

**三、哈希的输入里混进了路径。** `哈希(绝对路径 + 内容)` 会让产物随 checkout 目录变化。
看起来低级，但在「把目录结构也算进去」时很容易顺手写出来。

**四、依赖的解析顺序。** 锁文件解决了一部分，但 `^1.2.3` 这类范围在锁文件被删后
仍会解析到不同版本。

**五、当前时区。** 这条最阴——见下文。

## 时区那条：一次真实的 CI 失败

我给站点加了「定时发布」：frontmatter 里写 `date`，到点之前不发布。

实现很简单：比较文章日期与当前时刻。

本地全绿。推上去，**CI 红了**。

```
UTC+8 的机器：此刻是 9 月 12 日 01:57
CI（UTC）：  此刻是 9 月 11 日 17:57
```

`new Date('2026-09-12')` 在两种情况下都解析成 **UTC 午夜**，
但「今天」取决于机器时区。于是**同一篇文章在两地判定相反**：
本地认为该发布，CI 认为还没到点——而失败形态是「文章静默消失 →
引用它的 `[[链接]]` 变成断链」。

**根子不在比较逻辑写错了，在于「是否发布」依赖了构建时刻。**
只要依赖构建时刻，就必然破坏两件事：

1. **构建可复现**：9 月 11 日与 9 月 12 日构建出的产物不同
2. **跨机器一致**：作者本地能看到、CI 看不到，或反过来

我最后**把这个功能删掉了**。不是修不好，是代价算不过来：
`draft: true` 已经覆盖了「还没写完」这个主要场景，
而定时发布多出来的那点便利，换的是两个更重要的契约。

**做不到的事不该留着。**

## 怎么验

「可复现」是个可以被证明的性质，不用靠信念。

最直接的做法：**改变一个本不该影响内容的环境输入，再比哈希**。仓库已经把这条
做成命令：

```bash
npm run verify:reproducible
```

它会先扫描生产源码，禁止无参数 `new Date()` 与 `Date.now()` 直接读取构建时钟；
再清空 `.astro` 与 `dist`，分别在 UTC 与 America/Los_Angeles 跑完整的
Astro + Pagefind，逐文件比较 SHA-256。当前 93 个产物跨时区逐字节一致；
任一文件不同都会列出路径并以非零状态退出。

这里两层检查缺一不可：跨时区构建能抓出日期显示偏移，但抓不出一年才变化一次的
页脚年份；源码时钟检查能在跨年之前就拦住后者。内容里的日期则统一按 UTC 日历显示，
不会因为构建机位于负时区而退到前一天。

更有价值的一种是**换一种无关输入再比**。比如换行符：

```bash
# CRLF 工作区构建一次，LF 工作区构建一次，比对产物
```

我在这个站上做过这个实验：**CRLF 与 LF 两种工作区，产物 sha256 完全一致**
（87 个文件）。结论是换行符不影响产物——但这个结论**是测出来的，不是想出来的**。

## 为什么值得

有人会说这是洁癖。不是。

**可复现是「用 diff 做判断」的前提。** 如果每次构建产物都在抖，
那「这次提交改了什么」就只能靠读代码——而读代码是会漏的。

它也是**缓存正确性**的前提。构建产物不稳定，内容寻址的缓存就永远不命中，
或者更糟：命中了不该命中的。

而代价通常很小。上面那些来源，每一个的修法都是几行：
排序一下、固定一下、把时间从哈希输入里拿掉。

**花的这几行，换来的是「diff 可信」。** 这笔账很好算。

相关条目：[构建探针](https://xiaoxusop.github.io/letterpress/wiki/build-probe/)。

## 参考

- reproducible-builds.org（这个概念的系统性整理）
- 本站的实测：`npm run verify:reproducible` 会在两个时区完整构建并逐文件比对，
  同时禁止构建时钟泄漏；`.gitattributes` 统一换行符，内容层的排序全部显式化

</doc>

<doc title="静态站搜索的三种做法，以及它们各自真实的上限" path="static-site-search.md">

> 前端过滤、构建期索引、外挂服务——三种方案的取舍不在功能多少，在「索引存在哪」这一件事上。

静态站没有后端，所以搜索必须换个地方放。只有三个位置：

**放进浏览器**、**放进构建产物**、**放到另一台服务器上**。

选哪种，取决于你愿意接受哪一种上限。

## 一、放进浏览器：把内容全量打到前端

最简单：构建时把全部文章导成一个 JSON，页面加载后在前端过滤。

```js
const results = all.filter(p => p.title.includes(q) || p.body.includes(q));
```

**上限在「全量」两个字上。** 索引就是全部正文，文章一多，用户为了搜一个词要下载整站内容。

50 篇中等长度的文章大约 1–2 MB。1000 篇就是几十 MB——搜索框还没用上，
流量已经烧完了。

它适合**几十篇以内**的站点。超过这个量级，你会开始想「能不能只加载摘要」，
而那正是第二种方案。

## 二、放进构建产物：只下载倒排索引

构建时切词、建倒排索引，把索引作为静态资源发布。用户只下载索引，不下载正文；
命中之后再按需取片段。

这一类的代表是 [Pagefind](https://pagefind.app/) 和 [Fuse.js](https://www.fusejs.io/)：

- **Fuse.js** 是纯前端模糊匹配，仍然需要你把待搜内容喂给它——所以它解决的是
  「怎么匹配」，没解决「内容放哪」
- **Pagefind** 是构建后跑的索引器，直接读你的 HTML 产物。它把索引切成小块，
  搜索时只加载相关分片——**这才是真正的「索引比正文小」**

Pages/Netlify 这类托管上，Pagefind 是当前最省事的选择：一条命令，
零后端，还能按语言分别处理。

**上限在分词上。**

Pagefind 对中文不做词干提取——中文本来也没有词形变化，所以这不影响正确性。
真正的影响是**召回**：它按字/词切分建索引，你搜「排版」能命中包含「排版」的段落，
但搜「网页排版」不一定能命中只写了「排版」的地方。

英文靠词干回退（running ↔ run）缓解这类问题，中文没有对应机制。
**这是静态站搜索的固有限制，不是某个库的缺陷。**

## 三、外挂服务：Algolia、Meilisearch 这类

把索引放到一台真的服务器上，查询走网络。

功能上限最高：分词器可换、同义词、拼写纠错、按字段加权、结果高亮、
搜索分析——都能做。

代价也很清楚：

- **多了一个要运维的东西。** 静态站的全部好处就是「没有服务器」，
  为了搜索把它加回来，这笔账要自己算
- **多了一个会挂的东西。** 搜索服务挂了，站还在，但搜索框废了
- **多了一个花钱的地方。** 免费额度通常按「记录数 × 查询次数」计

**它适合「搜索是核心功能」的站点**——文档站、电商、知识库。
对个人博客，通常是过度配置。

## 怎么选

| 文章数 | 建议 | 理由 |
|---|---|---|
| < 50 | 第一种就够 | 全量 JSON 也就几百 KB，省一套索引流程 |
| 50 – 几千 | 第二种 | 索引与正文分离，零运维 |
| 搜索本身是产品 | 第三种 | 只有它能在**分词**这一层做文章 |

**判断的关键不是功能表，是「索引存在哪」**：在用户浏览器里、在构建产物里、
还是在别人的服务器上。三种位置对应三种上限，没有例外。

## 顺带一句：搜索需要 JavaScript，这是要认的

前两种方案都跑在浏览器里，所以**没有 JS 就没有搜索**。

这不是可以糊弄过去的——正确的做法是给一个 `<noscript>` 出口，
让关掉 JS 的读者至少能走到归档页，而不是对着一个永远转圈的输入框。

相关条目：[内容协商](https://xiaoxusop.github.io/letterpress/wiki/content-negotiation/)。

## 参考

- Pagefind 官方文档（索引分片与多语言处理）
- Fuse.js 官方文档（模糊匹配算法与阈值）
- 本文提到的中文召回限制来自本站在 2026-09 的实测：搜「排版」7 条命中，
  搜「行高」6 条命中，而搜「网页排版」只有 4 条——少掉的那几条正是
  正文里只写了「排版」、没写完整四个字的地方

> 复现方式：`npm run build` 之后到 `/search/` 搜这三个词。
> **`npm run dev` 里搜不到任何东西**——索引是构建期（Pagefind）生成的，
> 开发服务器没有它。这个数字也会随内容增删而变化，上面记的是当时的快照。

</doc>