RFC 0001: 文档体系与 RFC 流程
摘要
把 cotty 的文档分成状态文档和事件文档,用折叠规则把两者连起来。技术决定用写得薄的 RFC 记录。每个页面都以英文和中文发布。站点用 Hugo 构建,模板和检查脚本由项目自己维护,不依赖 JavaScript 的包生态。
动机
cotty 先设计再实现,设计包括产品设计和技术设计。它的协议是要让其他终端和其他 agent 也来实现的,所以别人会照着这些文档去做。文档是产品的一部分。
由此有三个需求:
- 产品设计会按版本逐步累积。但任何时候都要有一份完整的、描述当前设计的文档,产品和技术都是如此。
- 技术决定需要一份带日期、别人能读的记录。
- 调研需要有地方放,并带上日期和来源。
在这篇 RFC 之前,只有一个目录里的五篇笔记。它们把带日期的发现和希望一直成立的论断混在一起,没有任何标记区分两者。如果什么都不做,决定会留在聊天记录里,笔记会在没人察觉的情况下过时。
目标与非目标
目标:
- 任何时候都有一份完整的、当前的产品设计描述和技术设计描述。
- 每个技术决定有一份带日期的记录,包含理由和被否决的备选方案。
- 调研有归属,带日期和来源。
- 一个英文和中文的站点。
- 凡是程序能检查的规则,都由程序检查。
- 构建链小到可以审计。
非目标:
- 用户手册。现在还没有产品。
- 每次发布保留一份站点副本。在不够用之前,版本历史就是快照。
- 面向外部贡献者的流程。
已有做法
证据在两篇调研里:
简单说:把已接受的提案折叠进现行规范的项目,文档保持可读;只追加不汇总的项目做不到。值得学的深度在现行文档里,不在提案里。
方案
- 两类文档。 状态文档描述现在,只有一份。事件文档带日期,只追加。
- 折叠。 事件文档讲为什么改。改动在同一次提交里写进状态文档。
- 薄 RFC。 RFC 里放决定和理由。规范性条文只放在 RFC 所改动的状态文档里。
- 目录决定类别。 产品设计、版本设计、架构、规范、RFC、调研、文章和手册各有一个目录。
- 两种语言。 每个页面都有英文和中文,路径相同,在同一次提交里修改。英文是规范文本。
- 小的构建链。 Hugo 作为单个固定版本的程序,模板和搜索脚本为本项目而写,页面不从其他主机加载任何东西,检查用 Python 标准库写。
- 发布。 站点由 GitHub Pages 发布在
https://nowa.im/cotty/。每一类文档都发布,包括调研。
考虑过的备选方案
- 所有内容用一个编号序列。 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 所影响的页面没有列出它、页面从其他主机加载脚本。
待决问题
有一个问题延期处理,它不妨碍做出决定。
- 文档的许可协议。 延期到项目的许可协议确定时一并决定。
实施
- 建立目录和手册页。
- 迁移五篇笔记,并补上英文版。
- 编写
tools/check.py。 - 编写站点配置、模板和搜索。
- 构建,并用故意制造的错误逐项试验每个检查。
- 发布站点,并在每次推送时运行检查。
先读:文档体系。