453 lines
15 KiB
Markdown
453 lines
15 KiB
Markdown
# 灵隙协议协作工作流程
|
||
|
||
> 版本: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` | 版本号变更必须与你确认一致 |
|
||
|
||
---
|
||
|
||
> *本文件本身遵循上述规范,如内容与实际操作不一致,以实际操作为准并及时修正本文件。*
|