{%- set md = multi_developer if multi_developer else {} -%}
{%- set identity_cfg = md.get('identity', {}) -%}
{%- set context_cfg = md.get('context', {}) -%}
{%- set collab_cfg = md.get('collaboration', {}) -%}
{%- set dialogue_cfg = md.get('dialogue_protocol', {}) -%}
{%- set primary = identity_cfg.get('primary', 'git_username') -%}
{%- set fallback = identity_cfg.get('fallback', 'system_user') -%}
{%- set normalize = identity_cfg.get('normalize', True) -%}
{%- set agg_file = context_cfg.get('aggregation_file', 'docs/CONTEXT.md') -%}
{%- set auto_sync = context_cfg.get('auto_sync', True) -%}
{%- set collab_file = collab_cfg.get('file', 'docs/developers/COLLABORATION.md') -%}
# 十、多开发者/Agent 协作协议

> **v0.5.0+ 支持多个开发者或多个 AI Agent 在同一项目中协同开发**

## 10.1 协作模式概述

VibeCollab 支持以下协作场景：
- 👥 **多人协作**: 多个开发者在同一项目上工作
- 🤖 **多 Agent 协作**: 多个 AI Agent 分工完成不同任务
- 🔀 **混合协作**: 人类开发者 + AI Agent 混合团队

### 核心原则

1. **独立工作空间**: 每个开发者维护自己的 `CONTEXT.md`，互不干扰
2. **智能聚合**: 系统自动聚合生成全局视图，提供整体状态
3. **明确协作关系**: 通过 `COLLABORATION.md` 记录任务依赖和交接
4. **自动身份识别**: 基于 Git 配置自动识别当前开发者
5. **冲突预防**: 提前检测潜在的跨开发者工作冲突

## 10.2 目录结构

多开发者模式下的项目结构：

```
project/
├── CONTRIBUTING_AI.md
├── project.yaml
└── docs/
    ├── CONTEXT.md            # 全局聚合视图（自动生成，只读）
    ├── CHANGELOG.md          # 全局变更日志
    ├── DECISIONS.md          # 全局决策记录
    └── developers/           # 开发者工作空间
        ├── COLLABORATION.md  # 协作关系文档
        ├── alice/            # 开发者 alice 的目录
        │   ├── CONTEXT.md    # alice 的工作上下文
        │   └── .metadata.yaml # 元数据（更新时间等）
        └── bob/              # 开发者 bob 的目录
            ├── CONTEXT.md
            └── .metadata.yaml
```

## 10.3 开发者身份识别

系统通过以下策略自动识别开发者身份：

**识别策略**:
- **主策略**: `{{ primary }}` 
  - `git_username`: 使用 `git config user.name`
  - `system_user`: 使用系统用户名（$USER / $USERNAME）
  - `manual`: 手动指定（通过环境变量 `VIBECOLLAB_DEVELOPER`）
- **降级策略**: `{{ fallback }}` (主策略失败时使用)
- **名称标准化**: {{ '开启' if normalize else '关闭' }} (小写、空格转下划线、移除特殊字符)

**使用 CLI 命令查看当前身份**:
```bash
vibecollab dev whoami
```

## 10.4 上下文管理

### 10.4.1 独立上下文

每个开发者维护自己的 `CONTEXT.md`，记录：
- 当前正在进行的任务
- 最近完成的工作
- 待解决的问题
- 技术债务

**更新命令**:
```bash
# 手动更新时间戳（通常在对话结束时自动执行）
vibecollab dev sync
```

### 10.4.2 全局上下文聚合

系统自动聚合所有开发者的上下文，生成全局视图（`{{ agg_file }}`）：

- ⚠️ **只读文件**: 不要手动编辑全局 CONTEXT.md
- 📊 **聚合内容**: 
  - 项目整体状态
  - 各开发者工作进展
  - 跨开发者依赖关系
  - 全局技术债务
- 🔄 **更新时机**: {{ '对话结束时自动更新' if auto_sync else '手动执行 `vibecollab dev sync`' }}

**手动触发聚合**:
```bash
vibecollab dev sync --aggregate
```

## 10.5 协作文档管理

### 10.5.1 COLLABORATION.md

`{{ collab_file }}` 记录跨开发者的协作关系：

**包含内容**:
1. **任务分配矩阵**: 谁负责什么任务，谁是协作者
2. **依赖关系**: 任务之间的依赖关系
3. **交接记录**: 任务从一个开发者移交给另一个开发者
4. **协作约定**: 团队的协作惯例和规则

**示例格式**:
```markdown
## 任务分配矩阵

| 任务 | 负责人 | 协作者 | 状态 | 依赖 |
|------|--------|--------|------|------|
| TASK-DEV-001: 用户认证 | alice | bob | IN_PROGRESS | - |
| TASK-DEV-002: 数据库设计 | bob | - | DONE | - |
| TASK-DEV-003: API 开发 | alice | - | TODO | TASK-DEV-002 |

## 交接记录

### TASK-DEV-001: 用户认证
- **交接时间**: 2026-02-10 14:30
- **交接人**: bob
- **接收人**: alice
- **交接原因**: bob 完成数据库设计，alice 接手前端集成
- **交接说明**: API 接口已完成，文档见 docs/api.md
```

### 10.5.2 查看协作状态

```bash
# 查看所有开发者状态
vibecollab dev list

# 查看特定开发者状态
vibecollab dev status alice

# 初始化新开发者上下文
vibecollab dev init --developer bob
```

## 10.6 对话流程适配

### 10.6.1 对话开始时

多开发者模式下，AI 在对话开始时应：

```
1. 读取全局聚合 CONTEXT.md（了解整体状态）
2. 读取当前开发者的 CONTEXT.md（了解自己的进度）
3. 读取 COLLABORATION.md（了解协作关系）
4. 识别当前开发者身份（vibecollab dev whoami）
5. 确认本次对话目标
```

### 10.6.2 对话结束时

```
1. 更新当前开发者的 CONTEXT.md
2. 更新全局 CHANGELOG.md
3. 如有跨开发者协作，更新 COLLABORATION.md
4. 自动触发上下文聚合（生成新的全局 CONTEXT.md）
5. Git commit（记录当前开发者的提交）
```

### 10.6.3 多开发者场景的特殊考虑

**场景一：任务依赖**
- Alice 的任务依赖 Bob 的任务完成
- AI 应在 COLLABORATION.md 中标注依赖关系
- Alice 开始工作前检查依赖任务状态

**场景二：任务交接**
- Bob 完成阶段性工作，交接给 Alice
- 在 COLLABORATION.md 记录交接信息
- Alice 接手时读取交接说明

**场景三：并行开发**
- Alice 和 Bob 同时开发不同模块
- 各自维护独立的 CONTEXT.md
- 通过全局聚合了解对方进展

## 10.7 冲突检测与预防 (v0.5.1+)

> **新特性：自动检测跨开发者的潜在工作冲突**

### 10.7.1 冲突类型

系统会检测以下类型的冲突：

1. **文件冲突**: 多个开发者同时修改同一文件
2. **任务冲突**: 多个开发者负责相同或重叠的任务
3. **依赖冲突**: 任务依赖关系不一致或循环依赖
4. **命名冲突**: 多个开发者创建同名的函数/类/模块

### 10.7.2 冲突检测命令

```bash
# 检测当前开发者与其他开发者的冲突
vibecollab dev conflicts

# 详细模式（显示冲突详情）
vibecollab dev conflicts --verbose

# 检测特定开发者之间的冲突
vibecollab dev conflicts --between alice bob
```

### 10.7.3 冲突处理流程

```
1. [AI] 检测到潜在冲突
2. [AI] 在 CONTEXT.md 中标注冲突提醒
3. [AI] 提示用户检查冲突详情
4. [人] 决定处理方式：
   - 协调分工
   - 合并工作
   - 重新分配任务
5. [AI] 更新 COLLABORATION.md 记录解决方案
```

### 10.7.4 冲突预防建议

- ✅ 明确任务边界，避免职责重叠
- ✅ 及时更新 COLLABORATION.md 的任务分配
- ✅ 使用任务依赖标注避免循环依赖
- ✅ 定期执行 `vibecollab dev conflicts` 检查
- ✅ 重要修改前查看全局 CONTEXT.md 了解他人进展

## 10.8 CLI 命令参考

```bash
# 开发者身份
vibecollab dev whoami                    # 查看当前开发者身份
vibecollab dev switch <developer>        # 切换到指定开发者 (v0.5.4+)
vibecollab dev switch                    # 交互式选择开发者 (v0.5.4+)
vibecollab dev switch --clear            # 清除切换，恢复默认识别 (v0.5.4+)

# 开发者管理
vibecollab dev list                      # 列出所有开发者
vibecollab dev status <developer>        # 查看开发者状态
vibecollab dev init --developer <name>   # 初始化新开发者

# 上下文同步
vibecollab dev sync                      # 更新元数据时间戳
vibecollab dev sync --aggregate          # 重新生成全局聚合

# 冲突检测 (v0.5.1+)
vibecollab dev conflicts                 # 检测冲突
vibecollab dev conflicts --verbose       # 详细冲突报告

# AI 人机交互 (v0.5.8+)
vibecollab ai ask "问题"                 # 单轮 AI 提问 (自动注入项目上下文)
vibecollab ai ask "问题" --no-context    # 不注入项目上下文
vibecollab ai ask "问题" -v              # 显示详细信息
vibecollab ai chat                       # 多轮对话模式 (exit/quit/bye 退出)

# Agent 自主模式 (v0.5.8+)
vibecollab ai agent plan                 # 只读分析，生成行动计划
vibecollab ai agent run                  # 单次 Plan→Execute→Solidify 周期
vibecollab ai agent run --dry-run        # 干运行，只输出计划不执行
vibecollab ai agent serve                # 长运行 Agent 服务 (默认 50 周期)
vibecollab ai agent serve -n 10          # 指定最大周期数
vibecollab ai agent status               # 查看 Agent 运行状态

# Agent 引导 (v0.7.0+)
vibecollab onboard                       # AI 接入引导 (项目概况/进度/待办)
vibecollab onboard -d <developer>        # 指定开发者视角
vibecollab onboard --json                # JSON 输出 (便于 Agent 消费)
vibecollab next                          # 行动建议 (优先级化的下一步)
vibecollab next --json                   # JSON 输出

# Insight 沉淀 (v0.7.0+)
vibecollab insight list [--active-only]  # 列出所有沉淀
vibecollab insight show <id>             # 查看沉淀详情
vibecollab insight add --title ...       # 创建沉淀
vibecollab insight search --tags t1,t2   # 按标签搜索
vibecollab insight use <id>              # 记录使用，奖励权重
vibecollab insight decay [--dry-run]     # 执行权重衰减
vibecollab insight check [--json]        # 一致性校验
vibecollab insight delete <id> [-y]      # 删除沉淀
vibecollab insight bookmark <id>         # 收藏沉淀
vibecollab insight trace <id>            # 溯源树可视化
vibecollab insight who <id>              # 跨开发者使用信息
vibecollab insight stats                 # 跨开发者共享统计

# Task 管理 + Insight 自动关联 (v0.7.1+)
vibecollab task create --id TASK-DEV-001 --role DEV --feature "..."  # 创建任务(自动关联 Insight)
vibecollab task list [--status TODO] [--assignee x]                  # 列出任务
vibecollab task show <id>                # 查看任务详情(含关联 Insight)
vibecollab task suggest <id> [-n 5]      # 为已有任务推荐 Insight

# 协议自检 + 健康
vibecollab check                         # 协议遵循检查
vibecollab check --strict                # 严格模式
vibecollab check --insights              # 含 Insight 一致性校验
vibecollab health [--json]               # 项目健康信号 (v0.5.9+)
```

## 10.9 最佳实践

### 对于 AI Agent

1. **对话开始时**: 运行 `vibecollab onboard -d <name>` 全面了解项目状态
2. **上下文恢复**: 同时读取全局和个人 CONTEXT.md
3. **协作意识**: 修改共享资源前检查 COLLABORATION.md
4. **及时同步**: 对话结束时更新上下文并触发聚合
5. **冲突敏感**: 发现潜在冲突立即提醒用户
6. **三步闭环**: `onboard`（我在哪）→ 做事 → `next`（下一步）→ `check`（自检）

### 对于人类开发者

1. **明确分工**: 在 COLLABORATION.md 中清晰记录任务分配
2. **定期同步**: 经常查看全局 CONTEXT.md 了解团队进展
3. **交接规范**: 任务交接时详细记录背景和状态
4. **冲突检查**: 重大变更前执行冲突检测
5. **文档及时性**: 完成阶段性工作及时更新个人 CONTEXT.md

### 迁移单开发者项目

如果项目原本是单开发者模式，可以平滑迁移：

```bash
# 方式一：使用 CLI 命令
vibecollab dev migrate

# 方式二：在 project.yaml 中启用
multi_developer:
  enabled: true

# 然后重新生成协议文档
vibecollab generate
```

迁移后：
- 原 `docs/CONTEXT.md` 会备份为 `docs/CONTEXT.md.backup`
- 创建 `docs/developers/{developer}/CONTEXT.md`
- 自动生成新的全局聚合 `docs/CONTEXT.md`

---
