15 KiB
15 KiB
灵隙协议协作工作流程
版本: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 状态标签
每个文档元信息头必须有版本和状态:
> 版本:0.3
> 状态:草案
> 版本:1.0.0
> 状态:生效
> 版本: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 会议记录模板
# 会议记录:{主题}
> 日期:{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 |
版本号变更必须与你确认一致 |
本文件本身遵循上述规范,如内容与实际操作不一致,以实际操作为准并及时修正本文件。