开源协议文档结构研究报告

研究范围: Model Context Protocol (MCP) · Stripe API · Matrix Protocol · IPFS · OpenAI API · IETF RFC · OAuth 2.0

目标: 为 ItPay Protocol 文档站（docs.itpay.ai）提供可执行的结构优化建议

一、调研概述

1.1 为什么研究协议文档结构

开源协议文档不同于普通的技术文档或产品文档——它同时服务于四类读者：

读者类型	阅读目的	需要什么
协议实现者	理解协议规范，实现服务端	精确的规范（RFC2119 关键词）
集成开发者	调用 API 接入支付	完整的 API 参考 + 代码示例
AI Agent	自动化发现、理解、调用协议	机器可读的索引 + 结构化描述
商业决策者	评估协议是否适合业务	架构概览 + 安全合规证明

1.2 研究对象

协议	类型	文档风格	核心特点
MCP	AI 协议	规范+指南分离	llms.txt, 日期版本, 泳道图
Stripe	支付 API	一体化参考	多语言示例, 属性表格, 错误码
Matrix	通信协议	严格的版本化规范	多重API拆分, 深度编号, 错误码体系
IPFS	去中心化协议	概念+指南+参考三层	CLI-RPC 映射, 安全警告
OpenAI	AI API	端点分组参考	语言切换, 速率限制
IETF RFC	互联网标准	线性规范文档	编号章节, 安全考量, RFC2119
OAuth 2.0	授权协议	标准RFC + 实现指南	授权流程, 扩展点, 安全考量

二、深度分析

2.1 Model Context Protocol (MCP) — 最佳参考风格

文档地址: modelcontextprotocol.io

1) 信息架构（四层）

左侧边栏按功能分组:

Get Started (What is MCP, Quick Start)
About MCP (Architecture, Core Model)
Develop with MCP
Developer Tools
Examples

规格页面有独立的侧边栏:

Specification
- Key Changes
- Architecture
- Base Protocol (Lifecycle, Transports, Authorization, Utilities)
- Client Features
- Server Features
- Schema Reference

右侧边栏: "On this page" 链接

2) Specification vs Documentation 的明确分离

MCP 做的最好的一个设计决策——在协议层面就区分了"规范"和"指南"：

Specification 页面顶部声明：

This specification defines the authoritative protocol requirements. For implementation guides and examples, visit modelcontextprotocol.io

规范 (Spec)：使用 RFC2119 关键词（MUST/SHOULD/MAY），引用正式 TypeScript Schema
文档 (Docs)：使用自然语言，提供教程和示例代码
两者共享相同的左侧导航，但内容完全不同

3) 版本管理

日期版本号（2025-11-25），非语义化版本号
Version picker 位于 spec 页面顶部
文档页面为 evergreen（无版本），spec 页面有版本

4) Agent-friendly 设计

提供 llms.txt
这是 AI 可读的完整站点索引
每个页面有独立的 llms-full.txt 入口

5) 安全架构

Spec 中的安全章节分为两层：

原则层（Key Principles）：User Consent and Control, Data Safety
实现层（Implementation Guidelines）

2.2 Stripe API 参考 — 支付 API 文档的行业标杆

文档地址: docs.stripe.com/api

1) 页面结构（长表单页 + 左侧导航）

Stripe 的 API 参考是一个超长单页，而非多个独立页面。

左侧边栏固定显示：

基础概念：Introduction, Authentication, Errors, Expanding Responses, Idempotent Requests, Metadata, Pagination, Request IDs, Connected Accounts, Versioning
资源分组：Core Resources, Payment Methods, Products, Commerce, Checkout, Billing 等

2) API Endpoint 文档格式（每类操作的标准模板）

每个资源的文档遵循固定模板：

### Create a Charge

POST /v1/charges

Parameters:
  amount (integer, required): Amount in cents
  currency (string, required): Three-letter ISO code
  description (string, optional): Description

Returns: A Charge object

cURL Example:
  curl https://api.stripe.com/v1/charges \
    -u sk_test_...: \
    -d amount=2000 \
    -d currency=usd

3) 多语言支持

7 种语言切换标签（cURL, Ruby, Python, PHP, Java, Node.js, Go, .NET）
每种语言显示对应的 SDK 示例
默认显示 cURL（协议级示例）

4) 错误处理体系

Stripe 的错误响应结构：

{
  "error": {
    "type": "invalid_request_error",
    "code": "amount_too_large",
    "message": "Amount must be at most 99999999",
    "param": "amount",
    "decline_code": null
  }
}

错误类型：

api_error (500)
invalid_request_error (400)
authentication_error (401)
rate_limit_error (429)

模式: 错误响应分三层——type（大类）-> code（具体错误）-> decline_code（银行卡特有）

5) 版本管理

API 版本通过 Stripe-Version 请求头控制
日期版本号
v2 资源有 badge 标识
弃用策略有专门文档

2.3 Matrix Protocol 规范 — 严格的版本化协议规范

文档地址: spec.matrix.org/latest

1) 多 API 拆分

Matrix 将协议拆分为多个子规范，每个独立版本化：

Client-Server API     -> v1.18   客户端-服务器
Server-Server API     -> v1.18   服务器-服务器
Application Service   -> v1.18   应用服务
Identity Service      -> v1.18   身份服务
Push Gateway API      -> v1.18   推送网关
Room Versions         -> v1.18   房间版本演进
Olm and Megolm        -> v1.18   端到端加密

2) 深度编号导航

左侧导航使用深度编号（最多 5 层）：

7.3. POST /_matrix/client/v3/account/whoami
7.3.1. Rate-limited
7.3.2. Authentication required
7.3.3. Request parameters
7.3.4. Response
7.3.5. Errors

3) 错误码体系

Matrix 的错误码使用 errcode + error 结构：

{
  "errcode": "M_FORBIDDEN",
  "error": "You are not allowed to perform this operation"
}

通用错误码：

M_FORBIDDEN (403) - 无权访问
M_UNKNOWN (400) - 未知错误
M_LIMIT_EXCEEDED (429) - 速率限制
M_NOT_FOUND (404) - 资源不存在
M_BAD_JSON (400) - 无效 JSON

4) 端点版本化

URL 路径嵌入版本号：/v3/, /v1/
专门的 Endpoint versioning 章节
明确的 Deprecation policy 章节
遗留版本的迁移指南

2.4 IPFS Docs — 概念+指南+参考三层架构

文档地址: docs.ipfs.tech

1) 信息架构

Get Started -> Quick start, Installation
Concepts   -> Basics, How IPFS works, FAQ, Glossary
Guides     -> How-to organized by use case
Reference  -> Kubo CLI, RPC API, HTTP Gateway, Client libraries
Project    -> Community, Ecosystem, Case studies

2) CLI-RPC 映射模式

IPFS 的一个独特设计：每个 CLI 命令都精确对应一个 RPC API 端点。这种映射模式在文档中体现为 CLI 和 HTTP 两种方式的完整参考。

3) 安全警告模式

IPFS 使用粗体警告框强调关键安全约束，而非安全章节中的一般性描述。例如 "NEVER EXPOSE THE RPC API TO THE PUBLIC INTERNET" 的醒目警告。

2.5 IETF RFC / OAuth 2.0 — 正式标准文档

模式: 线性编号文档，非网页式导航

核心特征：

前导页：Status of This Memo, Copyright, Abstract
编号章节（1., 1.1, 1.1.1）
RFC2119 关键词（MUST, SHOULD, MAY, REQUIRED, OPTIONAL）
ASCII 艺术图（纯文本图，非 Mermaid）
必选安全考量章节（Security Considerations）
规范性/信息性引用分离
IANA 考量（标准注册表）

三、跨界模式对比

3.1 信息架构模式

模式	MCP	Stripe	Matrix	IPFS	推荐
三栏布局（左+中+右）	是	是（无右栏）	否	是（左副栏）	MCP
概念/指南/参考分离	是	否（混合）	否（全spec）	是	IPFS/MCP
Spec/Doc 分离	是	否	是	否	MCP
快速入门	是	是	否	是	必需
术语表	否	否	是	是	推荐
变更日志	否	是	是	否	推荐

3.2 API 文档模式

特性	Stripe	Matrix	IPFS	OpenAI
端点表格展示	属性+类型+必填+描述	参数表	参数+Body+响应	参数表
多语言示例	7种语言	仅JSON	cURL	3种语言
错误码表	完整+每端点	通用+每端点	HTTP状态码	错误码
速率限制	专用章节	Retry-After	无	专用章节
幂等性	专用章节	无	无	无

3.3 Agent-friendly 模式

特性	MCP	Stripe	Matrix	IPFS
llms.txt	是	否	否	否
结构化 Schema	TypeScript	无	无	无
JSON Schema	否	OpenAPI	OpenAPI	无
Copy-for-LLM 按钮	否	是	否	否

四、ItPay Protocol 文档优化方案

4.1 推荐信息架构

docs.itpay.ai
  |
  +-- Get Started (快速开始 SDK 安装 沙箱环境)
  +-- Concepts (架构 核心模型 支付流程)
  +-- Guides (商户接入 买家集成 Webhook)
  +-- API Reference (所有端点 参数 示例)
  +-- Errors (错误码表 错误处理)
  +-- SDK Reference (各语言 SDK)
  +-- Specification (正式协议规范 RFC2119)
  +-- Security (认证 加密 合规)
  +-- Changelog (版本历史 迁移指南)

4.2 端点文档模板（Stripe 风格）

每个端点文档应包括：

## Create a Payment

POST /v1/payments

Creates a new payment and returns the payment object.

Parameters:
  amount (integer, required): Amount in smallest currency unit
  currency (string, required): ISO 4217 currency code
  source (string, conditional): Payment source ID or token
  idempotency_key (string, optional): Unique idempotency key

Returns: A Payment object

cURL Example:
  curl -X POST https://api.itpay.ai/v1/payments \
    -H "Authorization: Bearer sk_test_..." \
    -H "Content-Type: application/json" \
    -d '{"amount": 1000, "currency": "usd", "source": "src_card_abc"}'

Response:
  {"id": "pay_abc123", "status": "succeeded", "amount": 1000}

Errors:
  400 invalid_amount - Amount must be positive
  402 payment_failed - Payment was declined
  429 rate_limit_exceeded - Too many requests

4.3 安全章节结构

1. Key Security Principles
   - User Consent and Control
   - Data Minimization
   - Encryption at Rest and in Transit

2. Authentication
   - API Key-based (server-side)
   - OAuth 2.0 (user-facing)
   - Webhook Signature Verification

3. Encryption
   - TLS 1.3 requirements
   - Payload encryption
   - Key management and rotation

4. Implementation Checklist
   - Production readiness
   - Common pitfalls
   - Compliance notes

4.4 Spec vs Docs 分离策略

借鉴 MCP 的做法：

规范（Spec）页面：

使用 RFC2119 关键词：MUST, SHOULD, MAY, MUST NOT
引用正式的 Schema 定义（JSON Schema 或 TypeScript 类型）
定义协议生命周期：创建 -> 授权 -> 捕获 -> 退款
定义所有状态机转换
版本化（日期格式）

文档（Docs）页面：

使用自然语言
提供具体的实现步骤和代码示例
故障排除指南
最佳实践

规范页面顶部声明：

This specification defines the authoritative protocol requirements. For implementation guides and examples, visit the Guides section.

4.5 Agent-friendly 基础设施

提供 llms.txt：完整的可发现性索引
提供结构化 Schema：JSON Schema 或 OpenAPI 3.0 规范
为关键页面提供 Copy-for-LLM 按钮
每个 API 端点提供机器可读的描述
错误码表附带程序化可识别的常量名称

4.6 版本管理策略

spec_version: "2025-06-01"
api_version_header: "ItPay-Version: 2025-06-01"
version_lifecycle:
  current: "2025-06-01 (active)"
  previous: "2025-05-01 (12-month transition)"
  deprecated: "2025-01-01 (read-only archive)"

4.7 错误处理体系

标准化错误响应：

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_amount",
    "message": "Amount must be at least 1",
    "param": "amount",
    "request_id": "req_abc123"
  }
}

错误分类：

Type	HTTP Status	Description
api_error	500	服务器内部错误
invalid_request_error	400	请求参数错误
authentication_error	401	API Key 无效或过期
authorization_error	403	权限不足
not_found_error	404	资源不存在
payment_error	402	支付处理失败
rate_limit_error	429	请求频率超限

五、总结与行动项

5.1 优先行动项（按影响排序）

优先级	行动	参考来源	预计工作量
P0	实现 Spec/Doc 分离	MCP	2-3天
P0	添加 llms.txt	MCP	1小时
P0	统一错误码体系	Stripe + Matrix	1天
P1	重构 API 端点文档格式	Stripe	2天
P1	添加 RFC2119 关键词	MCP + RFC	1天
P1	添加安全章节	MCP + OAuth	2天
P2	版本管理机制	Stripe	1天
P2	Copy-for-LLM 按钮	Stripe	0.5天
P3	多语言 SDK 示例	Stripe	3天
P3	交互式 Playground	Stripe	5天

5.2 推荐立即实施的快速胜利

添加 llms.txt -- 让 AI Agent 自动发现整个文档站
统一错误码表 -- 所有 API 返回一致的错误结构
Spec 页面添加 RFC2119 声明 -- 区分规范和指南
安全章节模板 -- 参考 MCP 的 Key Principles + Implementation 模式
API 端点文档模板 -- 每一个端点都包含 Parameters / Response / Example / Errors 四部分

一、调研概述​

1.1 为什么研究协议文档结构​

1.2 研究对象​

二、深度分析​

2.1 Model Context Protocol (MCP) — 最佳参考风格​

2.2 Stripe API 参考 — 支付 API 文档的行业标杆​

2.3 Matrix Protocol 规范 — 严格的版本化协议规范​

2.4 IPFS Docs — 概念+指南+参考三层架构​

2.5 IETF RFC / OAuth 2.0 — 正式标准文档​

三、跨界模式对比​

3.1 信息架构模式​

3.2 API 文档模式​

3.3 Agent-friendly 模式​

四、ItPay Protocol 文档优化方案​

4.1 推荐信息架构​

4.2 端点文档模板（Stripe 风格）​

4.3 安全章节结构​

4.4 Spec vs Docs 分离策略​

4.5 Agent-friendly 基础设施​

4.6 版本管理策略​

4.7 错误处理体系​

五、总结与行动项​

5.1 优先行动项（按影响排序）​

5.2 推荐立即实施的快速胜利​