本页内容
  1. 摘要
  2. 动机
  3. 目标与非目标
  4. 已有做法
  5. 方案
  6. 考虑过的备选方案
  7. 兼容性与迁移
  8. 安全与隐私
  9. 缺点与风险
  10. 验证
  11. 待决问题
  12. 实施

摘要

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

动机

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

由此有三个需求:

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

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

目标与非目标

目标:

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

非目标:

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

已有做法

证据在两篇调研里:

  • 文档实践:kitty、pi、Earendil、MCP、ACP 和 Matrix 如何组织规范和提案。
  • 站点生成器:四个生成器的实测对比。

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

方案

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

规范性条文在文档体系、RFC 流程和模板里。

考虑过的备选方案

  • 所有内容用一个编号序列。 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. 发布站点,并在每次推送时运行检查。

先读:文档体系。