# RFC 0001: 文档体系与 RFC 流程

地址: https://nowa.im/cotty/zh/rfcs/0001-documentation-system/  
状态: 讨论中  
创建: 2026-11-22

## 摘要

把 cotty 的文档分成状态文档和事件文档，用折叠规则把两者连起来。技术决定用写得薄的 RFC 记录。每个页面都以英文和中文发布。站点用 Hugo 构建，模板和检查脚本由项目自己维护，不依赖 JavaScript 的包生态。

## 动机

cotty 先设计再实现，设计包括产品设计和技术设计。它的协议是要让其他终端和其他 agent 也来实现的，所以别人会照着这些文档去做。文档是产品的一部分。

由此有三个需求：

- 产品设计会按版本逐步累积。但任何时候都要有一份完整的、描述当前设计的文档，产品和技术都是如此。
- 技术决定需要一份带日期、别人能读的记录。
- 调研需要有地方放，并带上日期和来源。

在这篇 RFC 之前，只有一个目录里的五篇笔记。它们把带日期的发现和希望一直成立的论断混在一起，没有任何标记区分两者。如果什么都不做，决定会留在聊天记录里，笔记会在没人察觉的情况下过时。

## 目标与非目标

目标：

- 任何时候都有一份完整的、当前的产品设计描述和技术设计描述。
- 每个技术决定有一份带日期的记录，包含理由和被否决的备选方案。
- 调研有归属，带日期和来源。
- 一个英文和中文的站点。
- 凡是程序能检查的规则，都由程序检查。
- 构建链小到可以审计。

非目标：

- 用户手册。现在还没有产品。
- 每次发布保留一份站点副本。在不够用之前，版本历史就是快照。
- 面向外部贡献者的流程。

## 已有做法

证据在两篇调研里：

- [文档实践](https://nowa.im/cotty/zh/research/studies/2026-11-documentation-practices/)：kitty、pi、Earendil、MCP、ACP 和 Matrix 如何组织规范和提案。
- [站点生成器](https://nowa.im/cotty/zh/research/studies/2026-11-docs-site-generators/)：四个生成器的实测对比。

简单说：把已接受的提案折叠进现行规范的项目，文档保持可读；只追加不汇总的项目做不到。值得学的深度在现行文档里，不在提案里。

## 方案

1. **两类文档。** 状态文档描述现在，只有一份。事件文档带日期，只追加。
2. **折叠。** 事件文档讲为什么改。改动在同一次提交里写进状态文档。
3. **薄 RFC。** RFC 里放决定和理由。规范性条文只放在 RFC 所改动的状态文档里。
4. **目录决定类别。** 产品设计、版本设计、架构、规范、RFC、调研、文章和手册各有一个目录。
5. **两种语言。** 每个页面都有英文和中文，路径相同，在同一次提交里修改。英文是规范文本。
6. **小的构建链。** Hugo 作为单个固定版本的程序，模板和搜索脚本为本项目而写，页面不从其他主机加载任何东西，检查用 Python 标准库写。
7. **发布。** 站点由 GitHub Pages 发布在 `https://nowa.im/cotty/`。每一类文档都发布，包括调研。

规范性条文在[文档体系](https://nowa.im/cotty/zh/handbook/documentation/)、[RFC 流程](https://nowa.im/cotty/zh/handbook/rfc-process/)和[模板](https://nowa.im/cotty/zh/handbook/templates/)里。

## 考虑过的备选方案

- **所有内容用一个编号序列。** Oxide 和 Earendil 把决定、调查和原则放在同一个序列里。流程简单。但调研从来不会"被接受"，它只有日期；产品的增量是按版本成批出现的。分成不同类别，每类才能有自己的生命周期和检查。
- **写得厚的 RFC，自带完整的规范条文。** Rust 和 MCP 是这样做的。评审时只读一篇。但接受之后条文要再抄进规范，两份会逐渐不一致。薄 RFC 只有一份条文。
- **以中文为规范文本，或者只用一种语言。** 将来实现这些协议的人读英文，所以英文必须准确。设计讨论用中文进行，所以先被评审的是中文版。两者都需要。
- **译文作为相邻文件，`page.md` 和 `page.zh.md`。** 两版放在一起。但两种语言里的链接会不同，英文目录也不再干净。每种语言一个目录时，链接完全相同。
- **JavaScript 生态里的生成器。** 实测了 Starlight、Docusaurus 和 VitePress。按功能看 Starlight 最合适。但它们各自会把 250 到 1200 个包带进构建。对一个要用户把密钥托付给它的项目来说，这条供应链太大了。
- **Sphinx。** 它的翻译机制把中文存成按段落切开的目录文件，无法当作页面来评审。这一项没有实测。
- **第三方 Hugo 主题。** 实测了 Hextra，可以用。但它是又一个需要审计的依赖：它自带用于搜索和画图的库，并且依赖单个维护者。本项目需要的模板只有几百行。
- **页面上完全不用第三方代码。** 那样图只能是纯文本或手工做的 SVG。代码仓库的浏览界面本来就能画 mermaid，架构页也需要图。所以开一个例外：mermaid 的一份副本，保存在仓库里，只在有图的页面上加载。
- **在元数据里写最后修改日期。** 没有人能靠手工把它保持正确。版本历史本来就知道。

## 兼容性与迁移

原有的五篇笔记按下表迁移。

| 之前 | 之后 |
|---|---|
| `docs/01-terminal-essence.md` | `posts/what-a-terminal-is.md` and `research/studies/2026-11-terminal-emulators.md` |
| `docs/02-landscape.md` | `research/landscape/2026-11-agent-terminals.md` |
| `docs/03-strategy.md` | `product/positioning.md` 和 `product/capabilities.md` |
| `docs/04-attention-cards.md` | `product/attention-cards.md` |
| `docs/05-field-notes.md` | `research/field-notes/2026-11-remote-spark-operations.md` |

`03-strategy.md` 里关于思路如何演变的叙述，不作为历史保留。其中的论证留在定位页里，作为前后端都要做的理由。

## 安全与隐私

- 构建只需要一个固定版本的程序和 Python 标准库。没有包管理器安装任何东西。
- 页面不从其他主机加载任何东西。搜索脚本由本项目自己编写。有一个第三方库 mermaid，以副本形式保存，它的来源记录在 `site/VENDORED.md` 里。JavaScript 本身并不排除。排除的是通过包管理器安装的代码。
- 调研是发布的。实地记录里的内部机器名用的是代称，不写地址，也不写密钥。

## 缺点与风险

- 两种语言让写作量翻倍。程序能检查两版结构相同，但检查不了它们说的是不是同一件事。
- 模板和搜索脚本要我们自己维护。
- `_index.md` 是只有 Hugo 才要求的名字。
- 已发布的页面会提到调研笔记，而站点的读者打不开它们。
- mermaid 的副本是一个很大的打包文件。它的来源核实过，但没有逐行读过。
- 评审一篇薄 RFC，需要同时读 RFC 和它改动的页面。
- 折叠规则只能通过痕迹来检查：页面列表和 RFC 编号。改动是否真的做了，要靠评审。

## 验证

`make check` 运行对源文件的检查，`make verify` 再加上对构建出的站点的检查。每项检查都用它应该拦住的错误试过：某个页面缺一种语言、两种语言的状态不同、非法的状态值、链接指向不存在的文件、链接指向不存在的锚点、正文里有一级标题、已接受的 RFC 所影响的页面没有列出它、页面从其他主机加载脚本。

## 待决问题

有一个问题延期处理，它不妨碍做出决定。

1. **文档的许可协议。** 延期到项目的许可协议确定时一并决定。

## 实施

1. 建立目录和手册页。
2. 迁移五篇笔记，并补上英文版。
3. 编写 `tools/check.py`。
4. 编写站点配置、模板和搜索。
5. 构建，并用故意制造的错误逐项试验每个检查。
6. 发布站点，并在每次推送时运行检查。

先读：[文档体系](https://nowa.im/cotty/zh/handbook/documentation/)。
