# 多Agent实时协作使用指南

> 本文档指导用户如何使用多agent实时协作方案
> 最后更新：2026-07-01

---

## 快速开始

### 第一步：查看协作方案

```bash
# 查看协作方案总览
cat docs/ai-collab/COLLAB-README.md

# 查看加入指南
cat docs/ai-collab/JOIN-GUIDE.md

# 查看任务分配
cat docs/ai-collab/TASK-ASSIGN.md
```

### 第二步：启动文件监控（可选）

```bash
# 给脚本执行权限
chmod +x docs/ai-collab/WATCHDOG.sh

# 启动监控
./docs/ai-collab/WATCHDOG.sh

# 查看监控状态
./docs/ai-collab/WATCHDOG.sh --status
```

### 第三步：邀请其他agent

查看邀请指令模板：
```bash
cat docs/ai-collab/AGENT-INVITATION.md
```

选择合适的指令发送给其他agent。

---

## 日常使用

### 1. 查看当前状态

```bash
# 查看实时状态
cat docs/ai-collab/SYNC.md

# 查看任务分配
cat docs/ai-collab/TASK-ASSIGN.md

# 查看消息板
cat docs/ai-collab/BOARD.md
```

### 2. 更新状态

在SYNC.md中添加状态更新：

```
[Agent名 时间戳] 状态描述
```

示例：
```
[Claude 2026-07-01 18:00] 🟢 上线，准备开始工作
[Claude 2026-07-01 18:05] 📋 认领任务 T001 境界体系修仙对齐
[Claude 2026-07-01 18:10] 🔒 锁定 docs/设计文档/GDD-02-底层核心机制.md
[Claude 2026-07-01 18:30] 🔄 进行中 T001，进度 30%
[Claude 2026-07-01 19:00] ✅ 完成 T001
[Claude 2026-07-01 19:00] 🔓 释放 docs/设计文档/GDD-02-底层核心机制.md
```

### 3. 认领任务

在SYNC.md中添加认领记录：

```
[Agent名 时间戳] 📋 认领任务 TXXX 任务名称
```

示例：
```
[Claude 2026-07-01 18:05] 📋 认领任务 T001 境界体系修仙对齐
```

### 4. 锁定文件

在SYNC.md的"文件锁状态"部分添加：

```
| 文件路径 | Agent名 | 当前时间 | 预计释放时间 |
```

示例：
```
| docs/设计文档/GDD-02-底层核心机制.md | Claude | 2026-07-01 18:10 | 2026-07-01 19:00 |
```

### 5. 释放文件锁

在SYNC.md的"文件锁状态"部分修改：

```
| 文件路径 | - | - | - |
```

### 6. 更新进度

在SYNC.md中更新任务进度：

```
[Agent名 时间戳] 🔄 进行中 TXXX，进度 XX%
```

示例：
```
[Claude 2026-07-01 18:30] 🔄 进行中 T001，进度 30%
```

### 7. 完成任务

在SYNC.md中添加完成记录：

```
[Agent名 时间戳] ✅ 完成 TXXX
```

示例：
```
[Claude 2026-07-01 19:00] ✅ 完成 T001
```

### 8. 沟通问题

在SYNC.md中添加问题标记：

```
[Agent名 时间戳] ⚠️ 问题：问题描述
```

示例：
```
[Claude 2026-07-01 18:30] ⚠️ 问题：GDD-02境界体系与修仙小说不一致，需要讨论
```

### 9. 紧急沟通

在SYNC.md中添加紧急标记：

```
[紧急][Agent名 时间戳] 紧急问题描述
```

示例：
```
[紧急][Claude 2026-07-01 18:30] GDD-02文件被锁定，无法修改
```

---

## 协作流程

### 完整流程示例

```
1. [Claude 18:00] 🟢 上线，准备开始工作
2. [Claude 18:05] 📋 认领任务 T001 境界体系修仙对齐
3. [Claude 18:10] 🔒 锁定 docs/设计文档/GDD-02-底层核心机制.md
4. [Claude 18:15] 🔄 进行中 T001，开始审阅
5. [Claude 18:30] 🔄 进行中 T001，进度 30%
6. [Claude 18:45] 🔄 进行中 T001，进度 60%
7. [Claude 19:00] 🔄 进行中 T001，进度 90%
8. [Claude 19:15] ✅ 完成 T001
9. [Claude 19:15] 🔓 释放 docs/设计文档/GDD-02-底层核心机制.md
10. [Claude 19:20] 📋 认领下一个任务
```

### 多agent并行流程

```
# Agent A
[Claude 18:00] 🟢 上线
[Claude 18:05] 📋 认领任务 T001 境界体系修仙对齐
[Claude 18:10] 🔒 锁定 GDD-02

# Agent B
[Kimi 18:00] 🟢 上线
[Kimi 18:05] 📋 认领任务 T002 功法体系细化
[Kimi 18:10] 🔒 锁定 GDD-04

# Agent C
[MiMo 18:00] 🟢 上线
[MiMo 18:05] 📋 认领任务 T003 天道系统扩展
[MiMo 18:10] 🔒 锁定 GDD-12
```

---

## 文件锁使用

### 何时需要文件锁

- 修改GDD文档时
- 修改SYNC.md时
- 修改TASK-ASSIGN.md时

### 如何使用文件锁

1. **检查锁状态**：
   ```bash
   cat docs/ai-collab/SYNC.md | grep -A 10 "文件锁状态"
   ```

2. **添加锁**：
   ```
   | 文件路径 | Agent名 | 当前时间 | 预计释放时间 |
   ```

3. **释放锁**：
   ```
   | 文件路径 | - | - | - |
   ```

### 锁冲突处理

如果文件已被锁定：

1. 等待锁释放
2. 选择其他任务
3. 与锁定agent沟通

---

## 问题处理

### 常见问题

**Q1: 如何查看其他agent的状态？**
A1: 查看SYNC.md的"当前在线Agent"部分。

**Q2: 如何查看任务进度？**
A2: 查看SYNC.md的"实时任务状态"部分。

**Q3: 如何避免文件冲突？**
A3: 修改文件前在SYNC.md中登记文件锁。

**Q4: 如何与其他agent沟通？**
A4: 通过SYNC.md更新日志，或在BOARD.md中添加讨论内容。

**Q5: 遇到问题怎么办？**
A5: 在SYNC.md中标记`⚠️ 问题`，并描述问题内容。

### 紧急问题处理

1. 在SYNC.md中标记`[紧急]`
2. 在BOARD.md中添加详细描述
3. 等待其他agent响应

---

## 最佳实践

### 1. 定期同步

- 每5-10分钟检查一次SYNC.md
- 状态变化时立即更新
- 完成任务后立即释放文件锁

### 2. 清晰沟通

- 使用统一的状态标记
- 描述清晰明了
- 及时响应问题

### 3. 任务管理

- 一次只认领一个任务
- 完成后再认领新任务
- 按时完成任务

### 4. 文件管理

- 修改前检查锁状态
- 修改后及时释放锁
- 记录变更内容

---

## 工具命令

### 查看文件

```bash
# 查看协作方案
cat docs/ai-collab/COLLAB-README.md

# 查看加入指南
cat docs/ai-collab/JOIN-GUIDE.md

# 查看任务分配
cat docs/ai-collab/TASK-ASSIGN.md

# 查看实时状态
cat docs/ai-collab/SYNC.md

# 查看邀请指令
cat docs/ai-collab/AGENT-INVITATION.md
```

### 启动监控

```bash
# 启动文件监控
./docs/ai-collab/WATCHDOG.sh

# 查看监控状态
./docs/ai-collab/WATCHDOG.sh --status

# 查看帮助
./docs/ai-collab/WATCHDOG.sh --help
```

### 搜索内容

```bash
# 搜索任务
grep "T001" docs/ai-collab/TASK-ASSIGN.md

# 搜索agent状态
grep "Claude" docs/ai-collab/SYNC.md

# 搜索文件锁
grep "🔒" docs/ai-collab/SYNC.md
```

---

## 更新日志

- 2026-07-01：创建使用指南