# 发布规范的项目如何管理文档

地址: https://nowa.im/cotty/zh/research/studies/2026-11-documentation-practices/  
创建: 2026-11-22

发布协议和提案的项目，是怎么让文档保持可用的？文档保持可读的那些项目，都维护一份现行规范，并把已接受的提案折叠进去。深度在现行文档里。提案要么很短，要么在接受后冻结。

## 发现

下面的说法除另有标注外都是 [官方]：是 2026-11-22 在项目自己的站点或仓库里读到的。

### kitty

- 站点是一份用户手册（快速上手、概览、FAQ、更新日志等），外加一个叫 "Terminal protocol extensions" 的部分。这部分有 14 页。每页规定一个协议，读者是其他终端和程序的作者。
- 键盘协议那一页从现状的问题讲起。然后是快速上手、概览、渐进增强、支持探测和旧式编码。它列出了实现该协议的终端、库和程序。
- 要求用小写的 "must" 和 "should" 表述。页面上有一条 "Added in version 0.20.0" 的说明，没有修订历史。
- 站点用 Sphinx 和 Furo 主题构建。
- 看不到提案流程。这些页面似乎是直接修改的（未核实）。

### pi，Earendil 出品

- pi-durable 这个包的文档分三层：
  - 一份当作指南的 README：概念表、明确的规则，以及四十多个可运行的例子。
  - 规范 `docs/spec.md`。它有 7303 行，开头是 "This document is normative"。第一章是术语和不变量，最后一章是非目标。
  - 另外的设计文档。
- `packages/agent/docs/harness-v2.md` 是一篇 1655 行的设计文档。它是整篇重写的，提交说明里写了它取代之前的文档，以及改了什么。它的结构：
  - 开头是兼容性政策；
  - 目标与非目标；
  - 概念与不变量；
  - 记录，以及标出可能崩溃位置的执行轨迹；
  - 恢复；
  - API 和实现；
  - 待决问题、测试策略、实施顺序；
  - 必读清单：一份"给全新的实现会话"的、按顺序排列的文件列表。

### Earendil 的 RFC

- Earendil 在 rfc.earendil.com 发布 RFC，四位编号。它的 RFC 0001 定义了 draft、discussion、published、accepted 和 abandoned 这几个状态。被取代的 RFC 会写明取代它的是哪篇。
- 这些 RFC 很短。量了其中八篇，每篇约 300 到 1900 个英文词，没有共同的固定章节。
- 这个序列里除了技术决定，还有公司原则和调查。

### MCP

- 提案叫 SEP。模板有摘要、动机、规范、理由、向后兼容、安全影响和参考实现。
- SEP 被接受时，同一个 pull request 必须补上规范正文、schema 改动和一条更新日志。要成为定稿，SEP 还需要参考实现，以及一个把每条要求对应到检查项的一致性测试。
- 定稿的 SEP 冻结不改。规范后来与它不一致时，以规范为准。
- 一个脚本把 SEP 文件渲染进文档，渲染结果过期时自动检查会失败。
- 站点托管在 Mintlify，这是一项商业服务。

### ACP

- 提案叫 RFD。它们依次经过 Draft、Preview 和 Completed。只有 Completed 有稳定性承诺。
- 实验性的工作放在以 RFD 命名的功能开关后面。
- 站点托管在 Mintlify。

### Matrix

- 提案叫 MSC。最终评议期之后，提案会停在一个叫 "spec PR missing" 的状态，直到改动被写进规范。这个改动必须链接到一个可用的实现。
- 在一个功能进入规范的正式版本之前，各实现使用不稳定前缀。
- 规范有正式版本，从 v1.1 到 v1.19，每个版本有更新日志。

### 凭一般了解

下面这些这次没有核实。

- Rust 维护 RFC，另外单独维护 Reference。
- TC39 的提案自带规范条文，并入 ECMA-262。
- IETF 只追加。TCP 的定义最后散在很多篇 RFC 里，于是写了 RFC 9293 来汇总。

## 对 cotty 的含义

- 维护现行文档，并把已接受的提案折叠进去。这就是[文档体系](https://nowa.im/cotty/zh/handbook/documentation/)里的折叠规则。
- 把深度放在规范和架构页里。规范页的标准是 kitty 的协议页。架构页的标准是 pi 的 harness 设计文档。
- RFC 写薄：只写决定和理由。
- 从别人那里拿三条做法：只有标为稳定的部分才有兼容性承诺；规范的效力高于提案；有代码之后，每条要求对应一个测试。
- 为实现者和 coding agent 而写。一份必读清单告诉新的会话从哪里开始。

## 来源

- kitty：[文档](https://sw.kovidgoyal.net/kitty/)、[键盘协议](https://sw.kovidgoyal.net/kitty/keyboard-protocol/)
- pi：[pi-durable README](https://github.com/earendil-works/pi/blob/main/packages/durable/README.md)、[harness-v2 提交](https://github.com/earendil-works/pi/commit/4f0437e2d58d651dd934119ecabea2893975f62f)
- Earendil：[文章](https://earendil.com/posts/)、[RFC 归档](https://rfc.earendil.com)
- MCP：[SEP 指南](https://modelcontextprotocol.io/community/sep-guidelines)
- ACP：[RFD 流程](https://agentclientprotocol.com/rfds/about)
- Matrix：[规范提案](https://spec.matrix.org/proposals/)

## 没有覆盖

- Rust、TC39 和 IETF 的流程细节。
- Python PEP、Kubernetes KEP、Wayland 协议和 Tor 提案。
