Files
synapse/docs/00-record/00-meeting-workflow.md
2026-06-29 02:12:44 +08:00

15 KiB
Raw Blame History

灵隙协议协作工作流程

版本: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 版本号变更必须与你确认一致

本文件本身遵循上述规范,如内容与实际操作不一致,以实际操作为准并及时修正本文件。