# 智能体协作规范

智能体间协作的通信协议、数据流转标准和协作规范。

## 1. 通信协议规范

### 1.1 智能体间通信方式

| 通信方式 | 适用场景 | 说明 |
|---------|---------|------|
| call_agent | 一对一协作 | 向指定智能体发送消息，等待回复 |
| call_agents | 一对多广播 | 同时向多个智能体发送消息，并行执行 |
| assign_agent_work | 分配任务 | master向智能体分配具体工作 |

### 1.2 消息格式规范

- sender: 发送者名称（英文名）
- receiver: 接收者名称（英文名）
- content: 消息内容，支持Markdown格式
- project_name: 项目名称（可选）
- task_name: 任务名称（可选）
- files: 文件清单（可选）

### 1.3 通信原则

- 不能呼叫master智能体
- 不能呼叫当前对话的智能体
- 消息内容清晰明确，避免歧义
- 文件路径使用绝对路径

## 2. 数据流转标准

### 2.1 文件传递规范

- 所有项目文件统一存放在 ./project/{project_name}/ 路径下
- 文件路径需使用绝对路径
- 文档类文件优先使用Markdown格式
- 代码类文件使用对应语言的源文件格式

### 2.2 数据一致性要求

- 多智能体协作时，共享数据必须保持版本一致
- 文件更新后需通知相关智能体
- 避免多个智能体同时修改同一文件

## 3. 协作流程规范

### 3.1 任务发起涉及的关键环节

| 环节 | 负责角色 | 说明 |
|------|---------|------|
| 需求分析 | master | 理解用户需求，评估工作量等级 |
| 分级策略选择 | master | 根据工作量选择处理策略 |
| 智能体调度 | master | 匹配合适的专业智能体执行 |
| 进度监控 | master | 跟踪执行进度，协调资源 |
| 质量验收 | master | 验证交付成果质量 |

### 3.2 协作优先级原则

- 找人优先：能委托专业智能体的任务优先委托
- 工具其次：有现成工具的优先使用工具
- 自己最后：以上两者都不满足时自己处理

### 3.3 冲突处理

- 内容冲突时，以master的协调结果为准
- 多智能体产出冲突，升级给master协调
- 资源竞争时，按任务优先级分配


## 4. 角色权限对照表

### 4.1 智能体角色与权限矩阵

| 智能体角色 | 核心权限 | 可调用工具 | 可操作资源 | 约束边界 |
|-----------|---------|-----------|-----------|---------|
| master（行动指导员） | 项目决策、任务分配、质量验收 | 全部工具 | 所有项目文件 | 不直接执行技术任务 |
| project_manager（项目经理） | 计划制定、进度跟踪、资源协调 | get_agent_*、set_task_*、call_agent | 项目文档、任务列表 | 不修改系统配置 |
| task_manager（任务管理大师） | 任务分解、任务分配、状态跟踪 | set_task_status、assign_agent_work | 任务看板 | 不修改技能配置 |
| skill_teacher（技能导师） | 技能创建、技能修改、技能赋予 | create_skill、set_skill、endow_skills | 技能文件、提示词文件 | 不修改系统核心配置 |
| tool_maker（工具匠人） | 工具开发、工具维护、工具注册 | 开发工具相关 | 工具代码库 | 不修改智能体配置 |
| hr_manager（人力资源管理师） | 智能体管理、能力评估、资源调配 | get_agent_*、set_agent_* | 智能体配置 | 不修改技能内容 |

### 4.2 权限等级划分

| 等级 | 描述 | 包含角色 |
|------|------|---------|
| L1-系统管理 | 系统级配置和决策权限 | master |
| L2-项目管理 | 项目级管理和资源调配权限 | project_manager、hr_manager |
| L3-专业执行 | 专业技能执行和工具使用权限 | skill_teacher、tool_maker、task_manager |
| L4-协作参与 | 基础协作和信息获取权限 | 所有智能体 |

### 4.3 敏感操作审批机制

| 操作类型 | 需要审批 | 审批人 |
|---------|---------|--------|
| 删除已有技能 | 是 | master |
| 修改系统核心配置 | 是 | master |
| 删除智能体 | 是 | master |
| 创建高风险技能 | 是 | master |
| 修改普通技能 | 否 | skill_teacher自行决定 |
| 创建普通工具 | 否 | tool_maker自行决定 |

## 5. 异常处理机制

### 5.1 异常分类与响应

| 异常类型 | 典型场景 | 响应策略 | 升级条件 |
|---------|---------|---------|---------|
| 工具调用失败 | 工具不存在、参数错误、权限不足 | 重试1次，失败后切换备用方案 | 重试失败后通知master |
| 文件操作异常 | 文件不存在、路径错误、权限拒绝 | 确认路径后重新操作 | 连续3次失败通知master |
| 通信超时 | 智能体无响应、网络延迟 | 等待30秒后重试 | 重试2次仍超时通知master |
| 数据不一致 | 版本冲突、数据丢失 | 回滚到上一个稳定版本 | 无法回滚时通知master |
| 技能执行异常 | 技能提示词错误、依赖缺失 | 记录错误日志，尝试降级处理 | 降级失败通知master |

### 5.2 异常处理路径说明

| 处理阶段 | 操作内容 | 适用条件 |
|---------|---------|---------|
| 异常记录 | 记录异常信息到日志 | 所有异常 |
| 类型判断 | 判断异常类型和可恢复性 | 所有异常 |
| 自动恢复 | 执行预设的恢复策略 | 可自动恢复的异常 |
| 恢复验证 | 验证恢复操作是否成功 | 自动恢复后 |
| 降级处理 | 切换为备用方案继续执行 | 自动恢复成功 |
| 升级上报 | 记录详细错误并通知master | 无法自动恢复或恢复失败 |
| 等待指令 | 暂停当前操作，等待master协调 | 已升级上报 |

### 5.3 降级处理策略

| 场景 | 正常方案 | 降级方案 |
|------|---------|---------|
| 技能缺失 | 调用专业技能执行 | 使用基础能力手动处理 |
| 工具不可用 | 使用专用工具 | 使用通用工具或手动替代 |
| 数据源不可达 | 读取实时数据 | 使用缓存数据或默认值 |
| 协作对象离线 | 请求协作智能体 | 自行处理或排队等待 |

### 5.4 异常恢复检查清单

- [ ] 异常是否已记录到日志
- [ ] 是否已尝试自动恢复
- [ ] 是否需要通知干系人
- [ ] 数据一致性是否已验证
- [ ] 恢复后功能是否正常
- [ ] 是否需要总结经验形成预案

## 6. 协作日志规范

### 6.1 日志记录要求

| 记录项 | 说明 | 格式要求 |
|-------|------|---------|
| 时间戳 | 事件发生时间 | YYYY-MM-DD HH:mm:ss |
| 发起者 | 触发操作的智能体 | 英文名 |
| 接收者 | 被操作的智能体/系统 | 英文名 |
| 操作类型 | 执行的操作分类 | call/task/file/tool |
| 操作内容 | 具体操作描述 | 简洁明确的文本 |
| 执行结果 | 操作是否成功 | success/failed/partial |
| 异常信息 | 失败时的错误详情 | 错误码+错误描述 |

### 6.2 日志存储规范

| 属性 | 规范 |
|------|------|
| 存储位置 | ./project/{project_name}/logs/ |
| 文件命名 | {date}_{project_name}_collaboration.log |
| 文件格式 | 纯文本（.log）或 Markdown（.md） |
| 编码格式 | UTF-8 |
| 日志轮转 | 按天分割，保留最近30天 |
| 归档策略 | 月度打包压缩，保存6个月 |

### 6.3 日志内容标准格式

```
[YYYY-MM-DD HH:mm:ss] [发起者] → [接收者] | [操作类型] | [操作内容] | [结果] | [异常信息]
```

日志示例：

```
[2026-07-06 10:30:00] [master] → [task_manager] | task | 分配任务"需求分析" | success | -
[2026-07-06 10:31:00] [task_manager] → [skill_teacher] | call | 请求创建"需求分析"技能 | success | -
[2026-07-06 10:35:00] [skill_teacher] → [tool_maker] | call | 请求开发需求分析模板工具 | failed | 工具已存在
[2026-07-06 10:36:00] [skill_teacher] → [master] | call | 汇报：工具已存在，无需新建 | success | -
```

### 6.4 日志级别定义

| 级别 | 标签 | 说明 | 示例 |
|------|------|------|------|
| INFO | [信息] | 常规操作记录 | 任务分配、状态变更 |
| WARN | [警告] | 潜在问题提示 | 资源接近上限、重试操作 |
| ERROR | [错误] | 操作失败需关注 | 工具调用失败、通信异常 |
| CRITICAL | [严重] | 系统级严重问题 | 数据丢失、配置损坏 |

### 6.5 日志分析要点

- 统计各智能体的协作频率和成功率
- 识别频繁失败的协作模式
- 追踪异常事件的根因和恢复时间
- 评估协作效率，优化协作流程
- 定期生成协作质量报告

### 6.6 日志安全要求

- 日志中不得记录敏感信息（密码、Token、密钥等）
- 敏感信息需脱敏处理后再记录
- 日志文件设置合理的访问权限
- 日志传输过程使用加密通道