# 多智能体协作约定（CONTRIBUTING）

> 类型：协作流程规范
> 版本：1.0
> 日期：2026-06-29
> 适用：本项目所有参与协作的 AI 智能体（Claude / MiMo / Kimi / Sonnet 等）与人类负责人

> **目的**：本项目采用**多模型异步文件级协作**——多个 AI 各自编辑同一批 GDD 文档，通过共享文件 + 决策注册表协调。本约定用于**消除并行编辑冲突、统一决策编号、明确合并裁决**，让多个智能体可安全并行推进。

---

## 一、协作模式

- **异步并行**：各智能体在各自会话/进程中工作，不要求实时同步。
- **文件即接口**：协作通过 `docs/` 下的共享文档进行；不存在跨会话的内存共享。
- **单一事实源**：
  - 决策编号与裁决 → **GDD-00 决策总索引**
  - 文档状态总览 → **README.md** 的 GDD 表
  - 本协作流程 → 本文档

---

## 二、文档归属与认领（防止同文件并写）

**核心规则：同一文档在同一时段只允许一个智能体主写（持有"写锁"）。**

| 模块 | 文档 | 当前主写（建议，可调整） |
|------|------|-------------------------|
| 决策注册/一致性维护 | **GDD-00** | Claude（注册表维护者） |
| 核心机制 | GDD-02 | 仅追加决策，任何人改前先认领 |
| 种族/天赋 | GDD-01、GDD-10、GDD-11 | Claude |
| 战斗/功法/职业 | GDD-03、GDD-04、GDD-05 | Claude |
| 经济/数值平衡 | GDD-06、GDD-08-附录A | MiMo |
| 地图/出生地 | GDD-08、GDD-08-附录B、GDD-09 | MiMo |
| 社交/佣兵/拍卖 | GDD-07、GDD-13、GDD-14 | Kimi |
| 渡劫/成长经济 | GDD-12、GDD-15 | Kimi |
| 审查/跨文档整合 | 全部（只读+评审） | Sonnet |

> 归属表由人类负责人最终裁定，可随时调整。**未持锁的文档只读，不直接改**；如需改他人文档的内容，提出"变更请求"由该文档主写执行，或经负责人重新分配。

### 认领约定（轻量"锁"）

由于无实时锁机制，用**文档头部状态行**充当软锁：

```
> 🔒 写锁：<智能体名> | 认领时间 <时间> | 预计完成 <范围>
```

- 开工前：在目标文档头部加上 🔒 写锁行；完成后删除。
- 看到他人 🔒 写锁未释放 → 不动该文档，改做自己认领的模块。

---

## 三、开工前必读（每次编辑前）

1. 读 **GDD-00 决策总索引**：确认最新核心决策号（当前至 ✅98）与约定。
2. 读 **目标文档头部 + 决策表 + 页脚 changelog**：确认最新版本与是否被他人持锁。
3. 读 **README GDD 表**：确认目标文档当前状态。

> 本项目已多次发生"编辑中途文件被改"的冲突，开工前读最新状态是硬性要求。

---

## 四、决策编号规则（沿用 GDD-00）

| 类型 | 规则 |
|------|------|
| 全局核心决策 | 在 GDD-02 决策表末尾**只追加**（✅99, ✅100…），**严禁重排已有号**；同步在 GDD-00 第二节登记一行 |
| 地图域决策 | 写入 GDD-08，沿用 `✅D##` / `✅Q##` |
| 文档本地决策 | 写入对应文档本地表；**跨文档引用必须带前缀**（如 `GDD-05 ✅8`），禁止裸写本地号 |
| 反转/取代旧决策 | 旧条目加删除线 + 指向新号；在 GDD-00 第五节登记 |
| 禁止 | 字母后缀（如 ✅99b）；占用他人命名空间 |

---

## 五、合并与冲突裁决

1. **决策冲突**：以 GDD-00 注册表为权威；若两条决策矛盾，按 ✅日志先后 + 人类负责人裁定，败者标注反转。
2. **同文档并发改**：若发现自己的改动与他人冲突（文件已变更），**放弃覆盖、重读、在最新版本上重做**，绝不强行回退他人内容。
3. **跨文档不一致**：发现后不擅自改他人主写文档，而是：①在 GDD-00 或本文档登记"待对齐项"；②通知对应主写或负责人。
4. **数值 vs 框架**：框架性决策（核心机制）优先级高于本地数值；本地数值调整不得违反核心决策。

---

## 六、文档维护规范

每次提交（编辑完成）必须：

1. **更新文档页脚 changelog**：`*GDD-XX vN.N | 日期 | 本次变更摘要*`
2. **更新版本号**：框架级改动升次版本，小修订升小版本
3. **同步 README GDD 表状态**（状态/版本/最后更新）
4. 若涉及核心决策 → **同步 GDD-00 第二节**
5. **释放写锁**（删除 🔒 行）

### 状态标记约定

| 标记 | 含义 |
|------|------|
| ✅ | 已定稿/已确认（无待确认项） |
| ⚠️ | 草案/含待确认项（❓） |
| 🔲 | 待创建 |
| ❓ | 待确认事项（在文档内待确认表登记） |

---

## 七、标准工作流（单个智能体一次任务）

```
1. 读 GDD-00 + 目标文档头/页脚 + README 状态   （了解最新）
2. 在目标文档头加 🔒 写锁行                      （认领）
3. 编辑内容；新决策只追加、带前缀引用            （执行）
4. 更新页脚 changelog + 版本号                   （记录）
5. 同步 GDD-00（若有核心决策）+ README 状态       （注册）
6. 删除 🔒 写锁行                                （释放）
7. 向负责人汇报：改了什么、新增哪些决策、待对齐项  （交接）
```

---

## 八、当前并行分工建议（首批认领）

> 基于现有文档的缺口与成熟度，建议首批并行任务如下（人类负责人可调整）：

| 智能体 | 首批认领 | 任务 |
|--------|----------|------|
| **Claude** | GDD-10、GDD-03 | 隐藏天赋数值化 + 补第3候选；战斗公式收尾 |
| **MiMo** | GDD-08-附录A、GDD-06 | 各层挂机资源数值表；经济数值平衡表 |
| **Kimi** | GDD-14、GDD-07 | 稀有宝物拍卖收尾；门派/家族细节 |
| **Sonnet** | 全局 | 跨文档一致性审查，产出"待对齐项"清单 |

> Claude 兼任 **GDD-00 决策注册表维护者**：负责归一新决策编号、登记反转/取代、定期核查跨文档一致性。

---

*协作约定 v1.0 | 2026-06-29 | 确立多模型异步文件级协作：文档归属软锁、开工前必读、决策编号沿用GDD-00、合并裁决、维护规范、首批并行分工*