本页内容
  1. 发现
  2. kitty
  3. pi,Earendil 出品
  4. Earendil 的 RFC
  5. MCP
  6. ACP
  7. Matrix
  8. 凭一般了解
  9. 对 cotty 的含义
  10. 来源
  11. 没有覆盖

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

发现

下面的说法除另有标注外都是 [官方]:是 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 的含义

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

来源

没有覆盖

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