agent-collaboration-guide

name	agent-collaboration-guide
description	Agent协作指导者 - 基于项目分析与优化Agent协作框架v2.0，提供大型复杂项目系统性分析与优化的Agent协作指导。包含协调者、分析组、优化执行组、验证组等8个Agent角色的定义、协作流程、并行策略、状态管理和异常处理机制。

Agent协作指导框架

版本: v2.0 适用场景: 大型复杂项目的系统性分析与优化

框架概述

本技能基于项目分析与优化Agent协作框架v2.0，提供标准化的Agent协作模式，用于高效完成复杂项目的分析、优化和验证任务。

核心架构

• 1个协调者 (ProjectCoordinator): 负责整体流程统筹和任务调度
• 4个分析Agent: 并行执行项目扫描、架构分析、业务逻辑分析和问题识别
• 2个优化执行Agent: 端到端完成重构和性能优化的代码实现
• 1个验证Agent: 执行测试验证确保优化质量

关键特性

✅ 完整的协作流程: AGENT_COLLABORATION_FRAMEWORK.md ✅ 精简的角色分工: 7+1 Agent架构，减少22%协调复杂度 ✅ 真正的并行策略: 分析阶段2波并行，优化阶段按模块并行 ✅ 人工审核门禁: 分析后、优化后、执行后三道审核关卡 ✅ 端到端优化Agent: 优化专家自己完成代码实现，减少交接 ✅ 可靠的状态管理: 统一状态存储和同步机制 ✅ 健壮的异常处理: 多种异常类型和恢复策略

Agent角色定义

协调者 Agent (ProjectCoordinator)

• 核心职责: 流程统筹、任务调度、资源管理、状态同步、决策制定、人工协调
• 能力要求: 流程编排、依赖分析、资源调度、状态管理、决策支持
• 完整协作流程: AGENT_COLLABORATION_FRAMEWORK.md
• 输入输出: 项目路径/优化目标 → 优化计划/执行报告/状态日志

分析组 Agent (4个)

ProjectScanner (项目扫描器)

• 职责: 快速建立项目全貌认知
• 能力: 代码统计、Git历史分析、热点代码识别、依赖扫描
• 输出: 项目概览报告、初步风险识别、模块依赖图
  • 完整模板仅参考:01-project-overview-template.md
• 并行性: ✅ 可与ArchitectureAnalyzer并行

ArchitectureAnalyzer (架构分析器)

• 职责: 深入分析技术架构和依赖关系
• 能力: 依赖树分析、配置文件解析、入口点识别、分层结构分析
• 输出: 架构分析报告、技术债务清单、架构图
  • 完整模板仅参考:02-architecture-analysis-template.md
• 并行性: ✅ 可与ProjectScanner并行

BusinessLogicAnalyzer (业务逻辑分析器)

• 职责: 理解核心业务流程和领域模型
• 能力: 调用链追踪、状态机分析、数据模型构建、API分析
• 输出: 业务逻辑报告、领域模型文档、业务流程图
  • 完整模板仅参考:03-business-logic-analysis-template.md
• 依赖: 需要ProjectScanner和ArchitectureAnalyzer的输出

IssueIdentifier (问题识别器)

• 职责: 系统化识别各类问题并分类，包含代码质量检查
• 能力: 代码异味检测、性能问题识别、安全漏洞扫描、代码规范检查、测试覆盖分析
• 输出: 问题清单、优先级矩阵、技术债务评估、质量报告
  • 完整模板仅参考:04-issue-list-template.md
• 依赖: 需要ProjectScanner和ArchitectureAnalyzer的输出

优化执行组 Agent (2个)

RefactoringSpecialist (重构专家)

• 职责: 针对代码质量问题进行重构优化，端到端完成代码修改
• 能力: 重构手法应用、代码编辑修改、版本控制操作、小步验证、兼容性保障
• 输出: 重构方案、已修改的代码、提交记录、变更说明
• 工作模式: 分析→设计→实现→自验证 (闭环)

PerformanceOptimizer (性能优化专家)

• 职责: 解决性能瓶颈和资源消耗问题，端到端完成代码修改
• 能力: 性能分析定位、SQL优化、缓存策略实现、异步处理改造、基准测试执行
• 输出: 性能优化方案、已修改的代码、基准测试对比报告
  • 完整模板仅参考:optimization-plan-template.md
• 工作模式: 分析→设计→实现→测量 (闭环)

验证组 Agent (1个)

TestingAgent (测试代理)

• 职责: 验证优化效果和回归测试
• 能力: 测试用例生成、自动化测试执行、性能基准测试、回归测试、覆盖率分析
• 输出: 测试报告、验证结果、覆盖率报告
• 触发时机: 每个优化任务完成后自动触发

协作流程

主流程状态机

1. 初始化 → 分析阶段 → 人工审核1 → 优化阶段 → 人工审核2 → 执行阶段 → 人工审核3 → 完成

详细协作流程

阶段一：分析阶段 (真正并行)

• 第一波并行: ProjectScanner (无依赖)
• 第二波并行: ArchitectureAnalyzer + BusinessLogicAnalyzer (依赖第一波结果)
• 第三波并行: IssueIdentifier (依赖第二波结果)
• 人工审核门禁: 提交分析报告请求审核，确认或补充

阶段二：优化阶段 (并行+人工确认)

• 并行制定方案: RefactoringSpecialist + PerformanceOptimizer
• 冲突检测: 协调者检测方案冲突并整合
• 人工审核门禁: 提交优化方案请求审核，确认执行或修改

阶段三：执行阶段 (实现+验证闭环)

• 按优先级执行: 每个优化任务执行(分析→设计→实现) + 测试验证
• 失败处理: 测试失败时触发回滚，标记需人工处理
• 人工验收门禁: 提交执行结果请求验收，通过或修复

并行处理策略

并行维度

• 阶段内并行: 同阶段无依赖任务并行
• 模块级并行: 不同业务模块独立处理
• 问题类型并行: 不同问题类型同时处理

分析阶段并行策略

第一波 (并行): ProjectScanner 
第二波 (并行): ArchitectureAnalyzer + BusinessLogicAnalyzer
第三波 (并行): IssueIdentifier

理论加速比: 从4个串行 → 2波并行，提速约50%

动态资源分配

• 分析组: 4个Agent，分2波并行
• 优化执行组: 最多4个并发(2个重构+2个性能)，按模块分配
• 验证组: 最多2个并发，可并行测试不同模块

状态管理与同步

全局状态结构

• 基本信息: 项目ID、当前阶段、完成进度
• 分析结果: 项目概览、架构分析、业务逻辑、问题清单
• 优化计划: 重构任务、性能优化任务、质量改进任务
• 执行状态: 已完成/进行中/失败任务
• 度量指标: 基线/当前/目标指标
• Agent状态: 活跃/已完成/失败Agent数量

知识库设计

knowledge_base/
├── project_state.md            # 全局状态
├── analysis_results/           # 分析结果
├── optimization_plans/         # 优化方案
└── execution_logs/             # 执行日志

异常处理与恢复

异常类型分类

• Agent超时: 重试+降级，重新分配任务
• Agent失败: 故障转移，启动备用Agent
• 数据不一致: 回滚+修复，从快照恢复
• 资源不足: 限流+排队，动态扩容
• 网络中断: 重连+缓存，本地缓存+重试

监控与告警

• Agent健康: 在线率<95%、响应时间>5s、错误率>1%
• 任务执行: 完成率<90%、执行时间>预期2倍
• 数据质量: 状态不一致、数据缺失>5%

使用指南

何时使用此技能

• 需要对大型复杂项目进行系统性分析和优化
• 需要多Agent协作完成复杂的软件工程任务
• 需要标准化的Agent角色定义和协作流程
• 需要并行处理策略提升任务执行效率
• 需要可靠的状态管理和异常处理机制

如何应用此框架

1. 识别任务类型: 确定是否属于大型复杂项目分析优化场景
2. 选择Agent组合: 根据具体需求选择所需的Agent角色
3. 配置协作流程: 按照三阶段流程设计具体的协作步骤
4. 设置并行策略: 根据项目特点配置合适的并行处理方式
5. 实施状态管理: 建立统一的状态存储和同步机制
6. 配置异常处理: 设置适当的异常检测和恢复策略

自定义扩展

• 添加新Agent: 通过插件化架构动态添加新的专业Agent
• 调整并行策略: 根据项目规模和复杂度调整并行维度
• 修改审核门禁: 根据安全要求调整人工审核点
• 扩展监控指标: 根据运维需求添加新的监控维度