# 灵隙协议协作工作流程 > 版本:1.0.0 > 状态:生效 > 适用范围:docs/ 下所有协议文档的评审与修订 --- ## 1. 文档角色体系 docs/ 下的文档按 **内容成熟度** 分为以下目录,每个目录有明确的角色边界: ``` docs/ ├── v{数字}/ 协议规范 — 已定稿的协议定义,只增不改 ├── 00-record/ 会议记录 — 协作过程中的决策记录 ├── 01-draft/ 草案 — 待评审的技术方案提议 ├── 02-guide/ 实现指南 — 已确认的实现参考和示例 └── 03-asset/ 资源附件 — 海报、图表等非文本资产 ``` | 角色 | 目录 | 内容定位 | 可修改性 | |------|------|---------|:--------:| | **协议规范** | `v{数字}/` | 已确认的协议定义 | ❌ 锁定(仅通过新版本覆盖) | | **会议记录** | `00-record/` | 协作中的决策记录 | ✅ 补充(不可推翻已确认条目) | | **草案** | `01-draft/` | 待评审的技术提案 | ✅ 自由编辑 | | **实现指南** | `02-guide/` | 参考实现的技术指南 | ✅ 更新 | | **资源附件** | `03-asset/` | 海报、图表、图片等 | ✅ 更新 | | **索引** | 各目录的 `00_index.md` | 目录清单和版本说明 | ✅ 同步更新 | --- ## 2. 文档版本独立规则 每一份文档独立维护版本号,不依赖目录版本: ### 2.1 版本号格式 ``` {v1}.{v2}.{v3} 示例: 0.1 = 初始草案 0.2 = 草案修订 1.0.0 = 首次定稿 1.1.0 = 兼容性修订 2.0.0 = 不兼容修订 ``` ### 2.2 版本段含义 | 段位 | 含义 | 变更条件 | |:---:|------|---------| | **v1** | 主版本 | 不兼容的协议变更(如签名算法替换) | | **v2** | 次版本 | 兼容的功能增补(如新增消息类型) | | **v3** | 补丁 | 勘误、措辞澄清、格式调整 | ### 2.3 状态标签 每个文档元信息头必须有版本和状态: ```markdown > 版本:0.3 > 状态:草案 ``` ```markdown > 版本:1.0.0 > 状态:生效 ``` ```markdown > 版本:1.0.0 > 状态:作废 > 作废原因:被 v2.0.0 替代 ``` | 状态 | 说明 | 出现位置 | |------|------|---------| | `草案` | 待评审的内容 | `01-draft/` | | `生效` | 已确认的规范 | `v{数字}/` | | `作废` | 已被替代的旧版本 | `v{数字}/`(保留历史) | ### 2.4 版本与目录的对应关系 | 目录 | 文档版本范围 | 说明 | |:----:|------------|------| | `01-draft/` | `0.x` | 草案阶段,版本号从 0.1 起跳 | | `v{数字}/` | `>= 1.0.0` | 定稿后从 1.0.0 开始,移入 v{数字} 目录 | | `00-record/` | `1.0.0`(固定) | 会议记录不增量版本,日期区分 | | `02-guide/` | `>= 1.0.0` | 实现指南跟随对应的协议版本 | --- ## 3. 协作场景 定义三种协作场景,覆盖不同粒度的决策: ### 3.1 方案讨论 | 项目 | 内容 | |------|------| | **触发条件** | 你对某个技术方向有想法,想讨论可行性 | | **你的输入** | 一句话想法、一个疑问、一个未解决的问题 | | **AI 产出** | 结构化分析(影响范围、可行方案、利弊对比) | | **你的输出** | 决定方向:继续、换方案、搁置 | ### 3.2 草案评审 | 项目 | 内容 | |------|------| | **触发条件** | `01-draft/` 下有草案需要评审 | | **AI 准备** | 提取草案的变更摘要、与现有规范的冲突点、待决议问题列表 | | **你的输入** | 逐条拍板:通过 / 驳回(说明方向)/ 搁置 | | **AI 产出** | 按决议更新草案、生成会议记录、更新索引 | ### 3.3 快速裁定 | 项目 | 内容 | |------|------| | **触发条件** | 发现现有规范中的歧义、矛盾或遗漏 | | **AI 分析** | 指出问题所在、给出修正提案、标注影响范围 | | **你的输入** | 一分钟内拍板 | | **AI 产出** | 记录裁定到 `00-record/`,更新关联文档 | --- ## 4. 协作前准备 ### 4.1 你需要准备的 | 场景 | 你需要提供 | |------|-----------| | **方案讨论** | 一句话描述你想讨论的方向或问题 | | **草案评审** | 指定要评审的草案文件路径(`01-draft/` 下) | | **快速裁定** | 指出有疑问的协议条款(文件+行号/章节) | 你不需要准备格式化的文档——AI 会将你的口语化表达转化为结构化内容。 ### 4.2 AI 会准备的 根据你的输入,AI 自动准备以下内容: | 场景 | AI 准备的内容 | |------|-------------| | **方案讨论** | 关联文档引用、影响范围分析、多个可选方案对比 | | **草案评审** | 变更摘要(如是修订版)、与现有规范的冲突矩阵、待决议问题列表 | | **快速裁定** | 问题定位、修正提案、受影响的文档列表 | --- ## 5. 协作流程 ### 5.1 角色定义 整个协作中只有两个角色: | 角色 | 你是谁 | 你的职责 | |------|--------|---------| | **你** | 决策者 | 提出方向、拍板决议、确认产出 | | **AI 助理** | 执行者 | 分析方案、生成文档、记录决策、管理文件 | AI 不做决策,只做**分析、建议和执行**。所有决议由你最终拍板。 ### 5.2 标准交互流程 一次协作的通用交互步骤: ``` 步骤 1 — 你提出问题 你说出想法、疑问或需求(可以是口语化的) 步骤 2 — AI 结构化回应 AI 提取关键信息,形成结构化内容供你评判: ├── □ 问题重述(确认理解正确) ├── □ 关联文档引用 ├── □ 可选方案(如有) ├── □ 影响范围评估 └── □ 待确认事项(你需要拍板的问题) 步骤 3 — 你给出决议 你对 AI 提出的选项拍板,或提出修改方向 步骤 4 — AI 执行 AI 根据决议: ├── □ 更新或创建文档 ├── □ 生成会议记录 └── □ 更新索引文件 步骤 5 — 你确认(可选) 你可以要求 AI 展示变更摘要,确认无误后结束 ``` ### 5.3 决议输入方式 你通过以下方式给出决议,AI 根据不同的输入方式执行相应操作: | 你的输入 | AI 理解方式 | AI 执行 | |---------|-----------|---------| | 直接说结论(如"用方案一") | 明确选择 | 按选定方案执行 | | 给出修改方向(如"把 X 改为 Y") | 指令式修改 | 执行具体修改 | | 提供替代方案(如"试试这样...") | 新提议 | 分析后返回步骤 2 | | 保留意见(如"先放一放") | 搁置 | 记录到待决议问题列表,不生成文件 | | 要求更多信息(如"展开说说 DHT 的缺点") | 追问 | 深入分析后返回步骤 2 | ### 5.4 记录方式 每一轮交互结束后,AI 自动将决议记录到会议文件 `00-record/`,你不需要手动记录。 | AI 自动记录的内容 | 存放位置 | |-------------------|---------| | 决议结论 | `00-record/{日期}-{主题}.md` 的"决议事项"章节 | | 决议理由 | 同上 | | 影响范围 | 同上 | | 后续行动项 | 同上 | | 新生成/更新的草案 | `01-draft/{日期}-{草案名}-v{次}.md` | ### 5.5 一次协作中允许的操作 | 操作 | 规则 | 示例 | |------|------|------| | 切换话题 | 随时可以 | "不说签名了,聊聊 DHT" | | 推翻之前的决议 | 可以,但需说明理由 | "刚才说的方案一我想了想还是不行,因为..." | | 要求回滚 | 可以,AI 会从 git 历史恢复 | "把刚才生成的 draft 删掉" | | 问多个问题 | 一个一个来,AI 会逐个回应 | 建议一个问题讨论完再提下一个 | | 中途中断 | 随时可以,AI 会保存当前进度 | 下次继续时会提供断点摘要 | --- ## 6. 协作产出 ### 6.1 AI 实时产出的文件 协作过程中,AI 实时生成以下文件,你无需等待: ``` 产出文件清单: ├── □ 会议记录 → 00-record/{日期}-{主题}.md ├── □ 更新后的草案 → 01-draft/{日期}-{草案名}-v{次}.md └── □ 索引更新 → 各目录的 00_index.md(如有变动) ``` ### 6.2 会议记录模板 ```markdown # 会议记录:{主题} > 日期:{YYYY-MM-DD} > 类型:方案讨论 / 草案评审 / 快速裁定 --- ## 议题 {一句话描述本次讨论的内容} --- ## 决议事项 ### 决议一:{决议标题} | 项目 | 内容 | |------|------| | **结论** | {结论简述} | | **理由** | {决策理由} | | **影响范围** | {影响的文档/模块列表} | ### 决议二:{决议标题} ... --- ## 补充讨论要点 {讨论中出现的值得记录的信息} --- ## 附录:关联文档 | 文档 | 说明 | 关系 | |------|------|------| | [{文档路径}](../path/to/doc.md) | {文档简述} | 本次讨论的基础/产出 | --- ## 后续行动 | 事项 | 目标版本 | 状态 | |------|---------|:----:| | {事项} | v{数字} | 待办 / 进行中 / 完成 | ``` ### 6.3 文件命名规范 ``` 会议记录: {YYYY-MM-DD}-{英文短名}.md → 00-record/ 草案: {YYYY-MM-DD}-{草案名}-v{次}.md → 01-draft/ 协议规范文档: {编号}_{英文短名}.md → v{数字}/ 实现指南文档: {英文短名}.md → 02-guide/ 索引文件: 00_index.md → 各目录根目录 资源文件: {英文短名}.{后缀} → 03-asset/ ``` --- ## 7. 决议覆盖范围 在一次协作中,决议的影响范围按以下层次递进: ``` ┌─────────────────────────────────────────┐ │ 单文件内的问题 │ │ 范围:措辞澄清 / 勘误 / 歧义裁定 │ │ 你的输入:一句拍板 │ │ AI 产出:修改文件 + 记录到 00-record │ └────────────────┬────────────────────────┘ │ 涉及跨文件/跨协议 ▼ ┌─────────────────────────────────────────┐ │ 跨文件的方案变更 │ │ 范围:涉及多个协议文档的技术决策 │ │ 你的输入:选择方案 + 确认影响范围 │ │ AI 产出:更新多份文档 + 更新/生成草案 │ └────────────────┬────────────────────────┘ │ 涉及版本范围/兼容性 ▼ ┌─────────────────────────────────────────┐ │ 版本级规划变更 │ │ 范围:决定 v1.0 / v1.1 / v2.0 的内容 │ │ 你的输入:指定版本范围和分工 │ │ AI 产出:更新 00_index.md + 记录到 00-record │ └─────────────────────────────────────────┘ ``` 你可以在任何层次上拍板,AI 会自动跟进所有下游影响。 --- ## 8. 草案晋升路径 一份草案从创建到定稿的标准路径: ``` ┌──────────┐ │ 想法 │ └────┬─────┘ │ 你说出想法,AI 写出草案 ▼ ┌───────────┐ │ 01-draft/ │ ←── 可任意修改 │ v0.1 │ └─────┬─────┘ │ 你评审 + 拍板修改方向 ▼ ┌───────────┐ │ 01-draft/ │ ←── 可修改 │ v0.2 │ └─────┬─────┘ │ 你确认定稿 ▼ ┌───────────┐ │ v{数字}/ │ ←── 锁定,只增不改 │ v1.0.0 │ └───────────┘ │ 后续修订 ▼ ┌───────────┐ │ v{数字}/ │ │ v2.0.0 │ ←── 不兼容修订另开新版本 └───────────┘ ``` | 阶段 | 版本号范围 | 目录 | 修改权限 | |:----:|:----------:|:----:|:--------:| | 初始创建 | 0.1 | `01-draft/` | 自由编辑 | | 修订中 | 0.2, 0.3... | `01-draft/` | 自由编辑 | | 评审通过 | 1.0.0 | 移入 `v{数字}/` | 锁定 | | 兼容修订 | 1.1.0, 1.2.0... | `v{数字}/` | 仅追加,不修改已有内容 | | 不兼容修订 | 2.0.0 | 新建 `v{数字+1}/` | 旧版本作废,新版本重新锁定 | --- ## 9. 目录与文件命名规范 ### 9.1 目录命名规则 | 规则 | 说明 | |------|------| | 协议规范目录 | 固定格式 `v{数字}`,数字表示协议主版本 | | 其他内容目录 | 格式 `{两位数字}-{英文短名}`,数字按内容成熟度/使用频率排序 | **已定义目录**: ``` docs/ ├── v0/ v0 协议规范 ├── v1/ v1 协议规范 ├── 00-record/ 会议与决策记录 ├── 01-draft/ 草案与方案提议 ├── 02-guide/ 实现指南参考 └── 03-asset/ 资源附件(海报、图表等) ``` 如需新增目录,新目录的编号插在末尾(当前为 03),待下次整理时统一重排。 ### 9.2 文件命名规则 ``` 协议规范层(v{数字}/): {两位数字}_{英文短名}.md 示例:01_raw-protocol.md 会议记录层(00-record/): {YYYY-MM-DD}-{英文短名}.md 示例:2026-06-29-v1-draft-discussion.md 草案层(01-draft/): {YYYY-MM-DD}-{草案名}-v{次}.md 示例:2026-06-29-identity-protocol-v2.md 实现指南层(02-guide/): {英文短名}.md 示例:components.md 资源附件层(03-asset/): {英文短名}.{后缀} 示例:poster.svg 索引文件: 00_index.md(各目录的根目录) ``` --- ## 10. 免交互操作 以下情况不需要你开口,AI 直接执行: | 场景 | AI 自行操作 | 例外 | |------|-----------|------| | 草案内的措辞修正 | 直接修改 `01-draft/` 文件 | 涉及技术含义的措辞变化需先问你 | | 漏洞/矛盾自查 | 发现后指出并给出修复提案,等你确认后执行 | - | | 会议记录遗漏补充 | 直接追加,标注 `[后补]` | 不能推翻已记录的决议 | | 实现指南更新 | 直接修改 `02-guide/` 文件 | 引用到协议层规范时需通知你 | | 索引文件同步 | 直接修改 `00_index.md` | 版本号变更必须与你确认一致 | --- > *本文件本身遵循上述规范,如内容与实际操作不一致,以实际操作为准并及时修正本文件。*