# 文档体系

地址: https://nowa.im/cotty/zh/handbook/documentation/  
状态: 草稿  
创建: 2026-11-22

本页规定 cotty 的文档如何组织、每类文档包含什么，以及让文档保持最新的规则。本页是规范性描述，为什么这样定见 [RFC 0001](https://nowa.im/cotty/zh/rfcs/0001-documentation-system/)。

## 两类文档

文档会过时失效，是因为一页里混了两种时间语义。这里的每篇文档都属于下面两类之一：

- **状态文档**描述现在是什么。它只有一份，永远是当前的，可以随时重写。
- **事件文档**记录某个时点提出、决定或发现了什么。它带日期。被接受或写完之后不再改写，后来的事件另写一篇放在旁边。

文档还分属两个空间：问题空间（为什么、做什么）和方案空间（怎么做）。

| | 状态：一份，永远当前 | 事件：带日期，只追加 |
|---|---|---|
| 问题空间 | 产品设计 | 版本设计、调研 |
| 方案空间 | 架构、规范 | RFC |
| 面向外部读者 | 规范 | 文章 |

## 规则

1. **折叠。** 事件文档讲为什么改。改动本身写进状态文档，并且在同一次提交里。一篇 RFC 或版本设计，只有在它影响的状态文档都更新之后，才算被接受。
2. **一个归属。** 每个事实只在一页里陈述。其他页面链接过去，不复述。
3. **事件不改写，状态不写历史。** 事件文档被接受后，只改状态和明显的笔误。状态文档描述现在。它的元数据列出影响过它的 RFC，除此之外不谈过去。
4. **已设计不等于已实现。** 状态文档描述已接受的设计。页面记录实现它的版本。在那之前它只是设计。

## 文档放在哪里

```text
docs/
├── en/                 英文，规范文本
│   ├── product/        产品设计                              状态
│   ├── versions/       每个版本一篇设计                      事件
│   ├── architecture/   内部技术设计                          状态
│   ├── specs/          协议、格式、API                       状态
│   ├── rfcs/           技术决定                              事件
│   ├── research/       landscape/、studies/、field-notes/    事件
│   ├── posts/          文章                                  事件
│   └── handbook/       项目如何运作                          状态
└── zh/                 中文译文，路径相同
site/                   Hugo 项目：配置和模板
tools/                  检查脚本
```

文档的类别由所在目录决定。页面不自己声明类别。

`docs/` 里的所有内容都发布到站点上。

## 各类文档

每类文档的骨架见[模板](https://nowa.im/cotty/zh/handbook/templates/)。

### 产品设计

产品设计回答产品为什么存在、做什么。它放在 `product/`，由一组页面构成：

| 页面 | 内容 |
|---|---|
| 定位 | 要解决的问题、谁有这个问题、为什么是现在、cotty 是什么、为什么它的几部分是一个设计、它坚持什么、不做什么。讲问题和产品，不讲市场和竞争。只写我们自己的思考，不点名其他产品。对其他产品的分析放在调研里。 |
| 场景 | 少量用户角色和核心场景，写成具体的故事。每个场景有编号，并链接到证据。版本设计和 RFC 引用场景编号。 |
| 原则 | 遇到取舍时怎么选。每条原则配一个例子。 |
| 概念模型 | 用户看得见的对象，以及它们的关系和状态。产品文档和技术文档共用这套词。 |
| 能力页 | 每个能力一页：问题、写成可检验陈述的行为、状态、界面、不在范围内的事。 |
| 质量标准 | 延迟预算、兼容性、隐私承诺。 |
| 路线图 | 现在、下一步、以后。 |

一个页面在内容设计出来之后才添加。设计达成一致之前状态是 `draft`，之后是 `accepted`。

### 版本设计

版本设计说明下一个版本在产品上改什么、为什么改。它放在 `versions/`，文件名是 `vX.Y.md`。它列出的场景同时是验收脚本。状态依次是 `planning`、`active`、`shipped`。已发布的版本设计冻结不改。

产品设计通过版本设计来改。技术设计通过 RFC 来改。

### 架构

架构页描述 cotty 内部怎么构成：组件、数据、不变量、故障与恢复。它们放在 `architecture/`。项目之外没有东西依赖它们，所以只要有 RFC 就可以改。

### 规范

规范是 cotty 和其他程序之间的约定：协议、格式、API。它们放在 `specs/`。读者是在别处实现它们的人，比如 agent CLI 和其他终端的作者。

### RFC

一篇 RFC 记录一个技术决定。见 [RFC 流程](https://nowa.im/cotty/zh/handbook/rfc-process/)。

### 调研

调研记录截至某个日期关于外部世界的事实。它放在 `research/`，分三个目录：

- `landscape/`：这个领域里的产品和项目。
- `studies/`：一个问题，调查一次。
- `field-notes/`：真实使用中发生了什么。

调研从不具有规范效力。每篇都写明事实的核对日期，列出来源，并标注每条说法的可靠性：官方、厂商或第三方。结尾写这些发现对 cotty 意味着什么。更新时写一篇新的。旧的保留，并加一行指向新的那篇。

调研是发布的，这样读者可以核对状态文档的依据。由此有两条规则：

- 写其他项目的笔记只做描述，并写明来源。下判断的地方，要说明这是判断。
- 实地记录里的机器和人用代称。不写地址，不写密钥。

### 文章

文章是写给外部读者的。它们放在 `posts/`。文章解释我们怎么想，不做决定。决定留在状态文档和 RFC 里。

调研和文章的区别在于价值来自哪里。价值在事实的，是调研：事实带日期和来源，由更新的一篇笔记来刷新。价值在论证的，是文章：它用我们自己的口吻写，事实部分引用调研。

### 手册

手册说明项目如何运作。本页属于手册。

## 语言

- 每个页面都有英文和中文两版，分别在 `docs/en` 和 `docs/zh` 下的相同路径。两版在同一次提交里添加和修改。
- 英文是规范文本。中文是它的译文。两者不一致时以英文为准，并把不一致当作缺陷修掉。
- 同一页面的两版，除 `title` 外元数据相同，标题结构相同，代码块数量相同，链接指向相同的页面。

## 约定

### 语气

每个页面都会发布，所以每个页面都是写给项目之外的读者的。

- 说清楚这个东西是什么、怎么工作、为什么这样做。写明它的限制，也写明哪些还没有决定。
- 用平实的词。不用销售和竞争的话术：卖点、护城河、赢、谁抄谁。
- 写 cotty 的页面讲的是问题和产品。其他产品放在调研里如实描述。

### 元数据

每个页面以一个元数据块开头。它只用 YAML 的一个小子集：`key: value` 行，以及由普通值构成的列表。

| 字段 | 用在哪里 | 含义 |
|---|---|---|
| `title` | 所有页面 | 页面标题。 |
| `created` | 除目录页外的所有页面 | 页面首次写成的日期，格式 `YYYY-MM-DD`。 |
| `status` | product、architecture、specs、handbook | `draft` 或 `accepted`。 |
| `status` | versions | `planning`、`active` 或 `shipped`。 |
| `status` | rfcs | 见 [RFC 流程](https://nowa.im/cotty/zh/handbook/rfc-process/#生命周期)。 |
| `rfc` | rfcs | RFC 编号。 |
| `affects` | rfcs | 这篇 RFC 改动的状态页面，写语言目录之下的路径。 |
| `rfcs` | 状态页面 | 改动过本页的 RFC 的编号。 |
| `implemented` | 状态页面，可选 | 实现本页的版本。 |
| `as_of` | research | 事实的核对日期。 |
| `supersedes`、`superseded_by` | rfcs，可选 | 被取代的、或取代它的 RFC 的编号。 |
| `authors` | 可选 | 姓名列表。 |
| `weight` | 可选 | 页面在所属目录里的排序位置。 |

页面最后修改的日期不存在页面里，它来自版本历史。

### 标题

标题写在元数据里。正文没有一级标题，直接以文字或二级标题开始。

### 链接

页面之间的链接写成指向 `.md` 文件的相对路径，用行内形式。这样的链接在代码仓库的浏览界面里和在站点上都能用。锚点用同一语言里标题的锚点。

### 目录页

每个目录有一个名为 `_index.md` 的入口页。这个名字是站点生成器要求的。

### 文件名

文件名用小写字母和连字符。

| 类别 | 名称 |
|---|---|
| RFC | `NNNN-slug.md`，四位数字 |
| 调研 | `YYYY-MM-slug.md` |
| 版本设计 | `vX.Y.md` |

### 图

图用 mermaid 写，放在 `mermaid` 代码块里。代码仓库的浏览界面会把它画出来，站点也会。mermaid 表达不了的图，用放在 `text` 代码块里的纯文本，或者一个 SVG 文件，并和生成它的源文件一起提交。

## 检查

`tools/check.py` 只使用 Python 标准库。`make check` 运行对源文件和样式表的检查。`make verify` 还会构建站点并检查结果。

对源文件的检查：

- 每个页面两种语言都有。
- 元数据格式正确，每类文档具备它要求的字段和状态值。
- RFC 编号唯一，并且和文件名一致。
- 同一页面的两版在元数据、标题结构、代码块和链接目标上一致。
- 页面之间的每个链接都指向存在的文件。
- 正文里没有一级标题。
- 已接受的 RFC 列出它影响的页面，这些页面也都列出这篇 RFC。

对构建出的站点的检查：

- 页面之间的每个链接都能解析到一个页面。
- 这些链接里的每个锚点在目标页面上都存在。
- 没有页面从其他主机加载脚本、样式表或图片。
- 每个脚本都是由站点自己提供的文件。每个页面里的结构化数据是数据而不是脚本，它必须格式正确。

对样式表的检查：

- 每个颜色在两个主题里都达到[站点设计](https://nowa.im/cotty/zh/handbook/site-design/)对它要求的对比度。
- 样式表里的颜色和那一页色板表里的颜色一致。

## 站点

站点用 Hugo 构建。Hugo 是单个程序，版本固定在 `mise.toml` 里。模板、样式表和搜索脚本都在 `site/` 里，是为本项目写的。没有第三方主题。站点的样子由[站点设计](https://nowa.im/cotty/zh/handbook/site-design/)规定。

站点由 GitHub Pages 发布在 `https://nowa.im/cotty/`，英文在根路径，中文在 `/zh/` 下。每次推送都有一个工作流运行检查，并发布 main 分支。一个栏目在有了页面之后才出现在导航里。

三条规则让构建链保持很小：

- 构建不通过包管理器安装任何东西。
- 页面不从其他主机加载任何东西。
- 页面上可以用 JavaScript，并且由本项目自己编写。来自别处的代码，只能以保存在仓库里的副本形式加入，它的版本和来源记录在 `site/VENDORED.md` 里。每一份这样的副本都是由维护者批准的例外。目前有一份：用来画图的 mermaid。

搜索在浏览器里运行。Hugo 为每种语言生成一份所有页面的索引，`site/assets/js/search.js` 用查询去匹配它。

面向搜索引擎，每个页面都带有描述、规范地址、指向另一种语言的链接和结构化数据，站点有站点地图。面向语言模型，站点有 `llms.txt`（页面索引）和 `llms-full.txt`（全文）。每个页面还以 Markdown 形式发布，地址是页面地址后面加 `index.md`。

## 尚未决定

- 文档的许可协议。
