| name | protocol-document-authoring |
| description | Author and audit strict external protocol specifications for ZerOS-System-Pro (and similar systems). Use when writing, revising, reviewing, or hardening protocol docs under Documents/Protocol; when defining ZMP/compatibility contracts; when splitting Registry/Index companion docs; when the user mentions 协议文档, 兼容性, 符合性, 登记表, 专一索引, MUST/禁止, or third-party implementers who will not read source code. |
协议文档编写（严格 · 通用）
何时启用
- 新建或大幅修订
Documents/Protocol/** 下的协议 Markdown
- 用户要求「兼容 / 符合 / 对外契约 / 防止语言漏洞」
- 主机侧声明「只支持某协议修订」，需把责任边界写进文档
- 出现可枚举编码表（异常标号、状态档、类别档等）需要登记或索引时
核心原则（不可妥协）
- 读者不看代码：第三方只读协议文本即可判定是否兼容；禁止把「去看参考实现」当作理解前提。
- 人称与对象：约束对象是「声称兼容本协议的实现」，不是「我们正在实现某某」。禁止「ZMP 必须实现…」这类把协议主体说成实现方的表述。
- 主机只认本文：后续产品只按协议支持；声称兼容却因偏离本文而无法运行 → 协议层判定为实现不符合，前提是本文已写清、无漏洞。
- 规范名不可替换：字段名、协议标识字符串大小写敏感、逐字固定。禁止「等价命名也可兼容」。
- 写死 vs 可标定：协议固定常量必须存在且取值不可变；可标定字段必须存在但值域内可选值。二者必须分开写清。
- 值域必须可裁决：每个必选字段写明类型、下限/上限、单位、字符集、长度计量方式；禁止只写「确定的数字 / 字符串」。
- 明确不规定：凡主机不会保证、也不应被第三方当成隐含要求的内容，必须单列「本协议不规定」，并禁止将其宣称为协议要求。
- 参考实现非规范：可挂链接，但冲突时以协议正文为准；参考实现里的标定样例值默认不强制第三方。
- 可枚举编码必须拆分专一文档：凡「已遇到 / 已采纳」的编码表、状态档、标号表等，禁止只堆在协议正文里长期膨胀；必须拆成 Registry（登记）+ Index（索引） 两份专一 Markdown，正文只留摘要与链接。
规范性用语
全文统一使用：
| 用语 | 含义 |
|---|
| 必须（MUST） | 违反即不符合 |
| 禁止（MUST NOT） | 违反即不符合 |
| 应（SHOULD） | 强烈建议 |
| 可以（MAY） | 可选 |
规范正文中的定义、判定、约束，即使未反复出现「必须」，仍按 MUST 理解。
专一拆分：Registry + Index（强制）
何时必须拆分
出现下列任一「可枚举、可追加、需检索」的信息集时，必须拆分，不得仅写在协议正文：
- 异常标号 / 错误码登记
- 初始化或生命周期状态档
- 严重度 / 类别档的专一检索需求（若正文已有简表，索引仍可独立）
- 其它「已遇到项」会持续增长的编码表
文件命名与位置
- 与所属协议同目录（例如
Documents/Protocol/PhysicalHardware/Memory/）
- PascalCase 文件名，成对出现：
{Topic}Registry.md — 编码与语义的权威登记表{Topic}Index.md — 专一多维索引（按取值 / 短名 / 主题词 / 生命周期等）
- 该协议子目录应有
README.md，列出正文 + 全部 Registry/Index，并写明冲突优先级
权威优先级（必须写进各文档页眉或目录 README）
登记表（Registry） > 索引（Index） > 协议正文中的摘要表
职责划分
| 文档 | 职责 | 禁止 |
|---|
| 协议正文 | 字段存在性、默认值、与其它契约的关系；链接到 Registry/Index；可保留一行级摘要 | 禁止把完整可增长编码长表只放在正文 |
| Registry | 编码规则、完整登记行、预留号段、追加流程、修订记录 | 禁止只写检索视图而无权威语义 |
| Index | 多维检索、快速核对清单；每一项能跳回 Registry | 禁止发明 Registry 未登记的取值或含义 |
追加「已遇到」项时的强制流程
- 先改对应 Registry（新标号/新档 + 语义 + 状态=已登记）
- 再改对应 Index（所有检索维同步）
- 若正文摘要或符合性条款受影响，再改协议正文与修订记录
- 更新该子目录
README.md（若新增了成对文档）
模板与范例
- 成对文档骨架见 registry-index-split.md
- 范例：
- 异常：
ExceptionCodeRegistry.md + ExceptionIndex.md
- 单元状态：
InitStateRegistry.md + InitStateIndex.md
- 目录索引：
Documents/Protocol/PhysicalHardware/Memory/README.md
标准文档结构（协议正文模板）
按需裁剪章节，但下列块在「对外兼容契约」类协议中默认齐备：
# {协议名} · 第 N 版
> 文档路径 / 规范状态：规范性 / 协议标识字符串：`{ID}` / 参考实现（非规范）：…
## 0. 文档定位与符合性
### 0.1 目的
### 0.2 规范性用语
### 0.3 符合性声明（何时可声称「完全兼容」）
### 0.4 字段名与标识的规范性（禁止等价替换）
### 0.5 本文与参考实现的关系
## 1. 概述（协议规定什么，一句话级）
## 2. 契约范围
### 2.1 本协议规定
### 2.2 本协议明确不规定（堵住隐含约定）
## 3. 术语（含正整数、字符集、长度计量等可复用定义）
## 4. 规范正文
### 4.0 协议固定常量（名 + 固定取值 + 违规即不符合）
### 4.x 各必选字段（名 / 类型 / 值域 / 单位 / 字符集 / 语义 / 判定规则）
### 4.y 可枚举编码：仅摘要 + 链接 Registry/Index（完整表禁止只放此处）
### 4.z 必选成员总表（机器核对清单）
### 4.w 可选成员（明确「非符合性条件」）
## 5. 不符合示例（非穷尽，专打常见钻空子）
## 6. 修订记录
编写工作流
复制并跟踪：
协议文档进度：
- [ ] 1. 锁定协议标识字符串与文档定位（读者 / 约束对象 / 主机支持边界）
- [ ] 2. 列出必选字段与协议固定常量（名称最终确定，禁止事后「等价」）
- [ ] 3. 为每个字段写类型、值域、单位、字符集、长度计量
- [ ] 4. 写清语义；凡无算术/行为公式的，写入「不规定」
- [ ] 5. 写启用/禁用等判定规则（避免另设布尔却双标准）
- [ ] 6. 识别可枚举编码集 → 创建/更新 Registry + Index + 目录 README
- [ ] 7. 正文只留摘要与链接；符合性声明 + 不符合示例（≥5 条常见钻空）
- [ ] 8. 对照参考实现：冲突以协议为准；样例值标成非强制（除非写死）
- [ ] 9. 执行符合性审查清单（见 conformance-checklist.md）
- [ ] 10. 人称与漏洞终审通过后再交付
人称与措辞（正误）
| 禁止 | 必须改成 |
|---|
| 我们 / 本仓库必须实现… | 符合本协议的实现必须… |
| ZMP1 必须提供字段…（协议自己当主语） | 配置面必须提供字段… / 符合本协议的实现必须提供… |
| 当前阶段我们还没做初始化… | 未初始化状态下字段必须为…（状态机语言） |
| 其它实现可用等价字段名 | 规范字段名必须逐字一致 |
| 具体见源码 | 以本文为准；参考实现非规范 |
| 把完整异常/状态长表只写在正文 | 拆分 Registry + Index，正文摘要并链接 |
值域写作最低标准
每个必选标量 / 字符串字段至少回答：
- 类型（正整数 / 字符串 / 枚举字符串…）
- 值域（如 ≥ 1；长度 1–16）
- 单位（若有；写死还是可标定）
- 字符集与长度计量（ASCII / 可打印 ASCII；码点 vs UTF-8 字节）
- 非法值示例（0、负数、空串、大小写变体…）
交付前强制自审
完整勾选 conformance-checklist.md。任一未通过 → 禁止声称协议已可对外约束第三方。
附加资源
