stigmergy 1.0.57

package/src/core/md_generator.py

@@ -0,0 +1,619 @@
+"""
+MD Document Generator - MD文档生成器
+为新项目生成包含协作感知的完整MD文档
+"""
+import asyncio
+from pathlib import Path
+from datetime import datetime
+from typing import Dict, List, Optional
+
+from .models import (
+    CLIInfo, AIEnvironmentInfo, GeneratedDocument, CLI_CONFIG_MAPPING
+)
+
+import logging
+logger = logging.getLogger(__name__)
+
+
+class MDDocumentGenerator:
+    """MD文档生成器 - 为新项目生成完整MD文档"""
+
+    def __init__(self):
+        self.template_cache = {}
+
+    async def generate_complete_md(self,
+                                 cli_name: str,
+                                 cli_info: CLIInfo,
+                                 ai_environment: AIEnvironmentInfo,
+                                 current_cli: str) -> str:
+        """为新项目生成完整的MD文档"""
+        try:
+            logger.info(f"为CLI工具 {cli_name} 生成完整MD文档")
+
+            # 生成基础文档结构
+            md_content = f"""# {cli_info.display_name} 项目配置
+
+> 🆕 新项目初始化
+> 📅 生成时间: {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}
+> 🔧 由 {current_cli.upper()} 工具初始化
+
+## 📋 项目概览
+
+本项目已启用 **AI CLI Router 跨工具协作系统**，支持多个AI CLI工具的无缝协作。
+
+### 🎯 主要特性
+
+- ✅ **跨工具协作**: 支持多个AI CLI工具的协作开发
+- ✅ **智能路由**: 自动识别和路由跨AI工具调用
+- ✅ **配置管理**: 统一的AI环境配置管理
+- ✅ **上下文保持**: 跨工具的上下文信息保持
+- ✅ **错误恢复**: 智能的错误处理和恢复机制
+
+"""
+
+            # 添加CLI工具基本信息
+            md_content += await self._generate_cli_info_section(cli_info)
+
+            # 添加协作环境章节
+            collaboration_content = await self._generate_collaboration_section(cli_name, ai_environment, current_cli)
+            md_content += collaboration_content
+
+            # 添加项目特定配置
+            project_specific_content = await self._generate_project_specific_section(cli_name, ai_environment)
+            md_content += project_specific_content
+
+            # 添加快速开始指南
+            quick_start_content = await self._generate_quick_start_section(cli_name, ai_environment)
+            md_content += quick_start_content
+
+            # 添加配置参考
+            config_reference = await self._generate_config_reference_section(cli_name, ai_environment)
+            md_content += config_reference
+
+            # 添加故障排除指南
+            troubleshooting_content = await self._generate_troubleshooting_section(cli_name, ai_environment)
+            md_content += troubleshooting_content
+
+            logger.info(f"成功生成 {cli_name}.md 文档，包含完整的协作感知")
+            return md_content
+
+        except Exception as e:
+            logger.error(f"生成MD文档失败: {e}")
+            raise
+
+    async def _generate_cli_info_section(self, cli_info: CLIInfo) -> str:
+        """生成CLI工具信息章节"""
+        return f"""
+## 🤖 当前CLI工具信息
+
+**{cli_info.display_name}** v{cli_info.version}
+
+### 📊 基本信息
+- **集成类型**: {self._get_integration_type_display(cli_info.integration_type)}
+- **配置文件**: `{cli_info.config_file}`
+- **状态**: {self._get_status_display(cli_info.status)}
+- **全局记忆文档**: `{cli_info.global_doc}`
+
+### ⚡ 核心能力
+{self._format_capabilities(cli_info.capabilities)}
+
+### 🔧 技术规格
+- **协议支持**: 跨CLI协作协议、中英文自然语言处理
+- **错误处理**: 优雅降级、自动重试、错误隔离
+- **性能优化**: 异步执行、并发处理、智能缓存
+"""
+
+    async def _generate_collaboration_section(self,
+                                             cli_name: str,
+                                             ai_environment: AIEnvironmentInfo,
+                                             current_cli: str) -> str:
+        """生成协作环境章节"""
+        current_cli_info = ai_environment.available_clis.get(cli_name)
+        peer_clis = ai_environment.collaboration_guide.available_peers
+
+        collaboration_section = f"""
+
+## 🤝 AI工具协作环境
+
+### 🎯 本项目AI工具生态系统
+
+**当前激活工具**: **{current_cli_info.display_name}** v{current_cli_info.version}
+
+**🔄 可协作工具生态系统**:
+"""
+
+        # 添加协作工具列表
+        for peer_name, peer_info in peer_clis.items():
+            status_emoji = "✅" if peer_info.status.value == "available" else "❌"
+            capabilities_text = ", ".join(peer_info.capabilities[:2])
+            if len(peer_info.capabilities) > 2:
+                capabilities_text += f" 等{len(peer_info.capabilities)}项"
+
+            collaboration_section += f"""
+- **{peer_info.display_name}** v{peer_info.version}
+  - {status_emoji} 状态: {self._get_status_display(peer_info.status)}
+  - 🛠️ 类型: {self._get_integration_type_display(peer_info.integration_type)}
+  - ⚡ 能力: {capabilities_text}
+  - 📁 配置: `{peer_info.config_file}`
+"""
+
+        # 添加协作协议
+        collaboration_section += f"""
+
+### 📝 跨AI协作协议
+
+**中文协作指令模式**:
+"""
+        chinese_protocols = ai_environment.collaboration_guide.protocols.get("chinese", [])[:6]
+        for protocol in chinese_protocols:
+            examples = self._generate_protocol_examples(protocol, list(peer_clis.keys())[:2])
+            collaboration_section += f"- `{protocol}`\n"
+            for example in examples[:2]:  # 每个协议最多2个示例
+                collaboration_section += f"  - 示例: `{example}`\n"
+
+        collaboration_section += """
+**英文协作指令模式**:
+"""
+        english_protocols = ai_environment.collaboration_guide.protocols.get("english", [])[:6]
+        for protocol in english_protocols:
+            examples = self._generate_protocol_examples(protocol, list(peer_clis.keys())[:2])
+            collaboration_section += f"- `{protocol}`\n"
+            for example in examples[:2]:  # 每个协议最多2个示例
+                collaboration_section += f"  - 示例: `{example}`\n"
+
+        # 添加协作场景
+        collaboration_section += f"""
+
+### 🎨 典型协作场景
+
+#### 1. 代码开发协作流程
+```bash
+# 开发新功能
+> 请用qwen帮我实现用户认证模块
+> 调用gemini分析安全漏洞
+> 用claude审查代码架构
+> 让iflow创建测试工作流
+```
+
+#### 2. 问题解决协作
+```bash
+# 解决复杂技术问题
+> 用claude分析这个性能问题
+> 调用gemini提供优化方案
+> 请用qwen实现性能优化
+```
+
+#### 3. 项目维护协作
+```bash
+# 项目维护和更新
+> 用iflow创建维护工作流
+> 请用qwen重构老旧代码
+> 调用gemini进行性能分析
+> 让claude生成技术文档
+```
+
+#### 4. 数据处理协作
+```bash
+# 数据分析和处理
+> 请用qwen处理这个数据集
+> 用gemini进行统计分析
+> 调用claude生成可视化报告
+```
+
+### 🎯 协作最佳实践
+
+1. **上下文传递**: 在跨工具调用时保持充分的上下文信息
+2. **任务分解**: 将复杂任务分解为不同工具的专长领域
+3. **结果验证**: 使用不同工具交叉验证重要结果
+4. **版本管理**: 为重要的协作结果建立版本控制
+5. **错误处理**: 优雅处理跨工具调用中的错误情况
+
+### 🔄 工具切换策略
+
+| 任务类型 | 推荐工具 | 备用工具 |
+|---------|---------|---------|
+| 代码生成 | QwenCode | Claude |
+| 性能优化 | Gemini | Claude |
+| 架构设计 | Claude | Gemini |
+| 工作流自动化 | iFlow | Claude |
+| 代码审查 | Claude | Gemini |
+| 数据分析 | Gemini | QwenCode |
+"""
+
+        return collaboration_section
+
+    async def _generate_project_specific_section(self,
+                                                cli_name: str,
+                                                ai_environment: AIEnvironmentInfo) -> str:
+        """生成项目特定配置章节"""
+
+        return f"""
+
+## ⚙️ 项目特定配置
+
+### 📁 项目结构
+
+建议的项目目录结构:
+```
+project-root/
+├── {cli_name}.md              # 当前工具的项目配置 (本文件)
+├── claude.md                  # Claude CLI配置
+├── gemini.md                  # Gemini CLI配置
+├── qwen.md                    # QwenCode CLI配置
+├── iflow.md                   # iFlow CLI配置
+├── .ai-cli-project/           # AI项目配置目录
+│   ├── project-config.json    # 项目级AI配置
+│   ├── collaboration-log.json # 协作历史记录
+│   └── tool-preferences.json  # 工具使用偏好
+├── src/                       # 源代码目录
+├── tests/                     # 测试目录
+└── docs/                      # 文档目录
+```
+
+### 🔧 AI配置管理
+
+#### 全局配置
+- **位置**: `~/.ai-cli-unified/global-config.json`
+- **作用**: 存储所有AI CLI工具的全局配置
+- **更新方式**: 通过 `ai-cli-router scan` 命令
+
+#### 项目配置
+- **位置**: `.ai-cli-project/project-config.json`
+- **作用**: 项目特定的AI工具配置和偏好
+- **更新方式**: 通过各CLI工具的配置功能
+
+### 📊 协作统计
+
+项目AI工具使用情况将自动记录在 `.ai-cli-project/collaboration-log.json` 中，包括:
+- 跨工具调用次数
+- 协作成功率
+- 常用协作模式
+- 性能指标统计
+"""
+
+    async def _generate_quick_start_section(self,
+                                           cli_name: str,
+                                           ai_environment: AIEnvironmentInfo) -> str:
+        """生成快速开始指南"""
+        peer_clis = list(ai_environment.collaboration_guide.available_peers.keys())
+
+        quick_start = f"""
+
+## 🚀 快速开始
+
+### 1. 立即开始协作
+
+```bash
+# 检查可用AI工具
+> /init
+
+# 开始跨工具协作
+> 请用{peer_clis[0] if peer_clis else 'qwen'}帮我生成一个Python函数
+> 调用{peer_clis[1] if len(peer_clis) > 1 else 'claude'}审查这段代码
+```
+
+### 2. 常用协作模式
+
+#### 🔗 代码生成 → 审查 → 优化
+```bash
+> 请用qwen生成用户认证代码
+> 调用gemini分析性能
+> 用claude审查架构设计
+```
+
+#### 🔄 问题分析 → 解决方案 → 实现
+```bash
+> 用claude分析这个bug
+> 调用gemini提供解决方案
+> 请用qwen实现修复代码
+```
+
+#### 📊 数据处理 → 分析 → 报告
+```bash
+> 请用qwen处理CSV数据
+> 用gemini统计分析结果
+> 调用claude生成分析报告
+```
+
+### 3. 工具特定功能
+
+"""
+
+        # 添加工具特定的快速开始内容
+        tool_specific_content = await self._generate_tool_specific_quick_start(cli_name, peer_clis)
+        quick_start += tool_specific_content
+
+        return quick_start
+
+    async def _generate_tool_specific_quick_start(self, cli_name: str, peer_clis: List[str]) -> str:
+        """生成工具特定的快速开始内容"""
+
+        tool_guides = {
+            "claude": """
+#### Claude CLI 特有功能
+- **智能分析**: 深度语义理解和智能分析
+- **学习优化**: 持续学习和性能优化
+- **错误恢复**: 智能错误分析和自动恢复
+
+推荐协作模式:
+```bash
+> 用claude分析这个需求的复杂性
+> 请用qwen基于分析结果生成代码
+> 调用gemini优化生成的代码性能
+```
+""",
+            "gemini": """
+#### Gemini CLI 特有功能
+- **智能匹配**: 高级模式匹配和任务识别
+- **多处理器**: 支持多种Extension处理器
+- **数据分析**: 强大的数据处理和分析能力
+
+推荐协作模式:
+```bash
+> 用gemini分析这个数据集的模式
+> 请用qwen生成数据可视化代码
+> 调用claude生成分析报告
+```
+""",
+            "qwen": """
+#### QwenCode CLI 特有功能
+- **代码生成**: 高质量代码生成和重构
+- **插件系统**: 丰富的插件和扩展能力
+- **代码审查**: 智能代码质量检查
+
+推荐协作模式:
+```bash
+> 请用qwen生成完整的CRUD API
+> 调用gemini分析API性能
+> 用claude审查代码架构
+```
+""",
+            "iflow": """
+#### iFlow CLI 特有功能
+- **工作流引擎**: 强大的工作流编排能力
+- **流水线处理**: 自动化流水线管理
+- **任务队列**: 高效的任务调度和执行
+
+推荐协作模式:
+```bash
+> 用iflow创建CI/CD工作流
+> 请用qwen生成部署脚本
+> 调用gemini优化工作流性能
+```
+"""
+        }
+
+        return tool_guides.get(cli_name, f"""
+#### {cli_name.upper()} CLI
+使用 {cli_name.upper()} CLI 开始你的AI协作之旅。查看工具文档了解更多功能。
+""")
+
+    async def _generate_config_reference_section(self,
+                                                 cli_name: str,
+                                                 ai_environment: AIEnvironmentInfo) -> str:
+        """生成配置参考章节"""
+
+        return f"""
+
+## 📚 配置参考
+
+### 🔧 环境变量
+
+| 变量名 | 描述 | 默认值 |
+|--------|------|--------|
+| AI_CLI_ROUTER_ENABLED | 启用AI CLI Router | true |
+| AI_CLI_LOG_LEVEL | 日志级别 | INFO |
+| AI_CLI_TIMEOUT | 超时时间(秒) | 30 |
+| AI_CLI_RETRY_COUNT | 重试次数 | 3 |
+
+### 📁 配置文件路径
+
+- **全局配置**: `~/.ai-cli-unified/global-config.json`
+- **项目配置**: `.ai-cli-project/project-config.json`
+- **工具配置**: `~/.config/{cli_name}/config.yml`
+- **日志文件**: `~/.config/{cli_name}/logs/`
+
+### 🎯 协作配置选项
+
+```json
+{{
+  "collaboration": {{
+    "enabled": true,
+    "auto_detect": true,
+    "timeout": 30,
+    "retry_count": 3,
+    "preferred_tools": ["claude", "qwen", "gemini"],
+    "fallback_strategy": "sequential"
+  }},
+  "protocols": {{
+    "chinese": true,
+    "english": true,
+    "mixed_language": true
+  }}
+}}
+```
+
+### 🔌 插件配置
+
+支持的插件类型:
+- **Hook插件**: 用于事件驱动的扩展
+- **Extension插件**: 用于功能增强
+- **Workflow插件**: 用于工作流集成
+"""
+
+    async def _generate_troubleshooting_section(self,
+                                                cli_name: str,
+                                                ai_environment: AIEnvironmentInfo) -> str:
+        """生成故障排除指南"""
+
+        return f"""
+
+## 🔧 故障排除
+
+### ❌ 常见问题
+
+#### 1. 跨工具调用失败
+**症状**: 跨AI工具调用时出现错误或超时
+
+**解决方案**:
+- 检查目标CLI工具是否正确安装
+- 验证配置文件是否存在且格式正确
+- 检查网络连接状态
+- 查看各工具的日志文件
+
+```bash
+# 检查工具状态
+> ai-cli-router status
+
+# 重新扫描环境
+> ai-cli-router scan
+```
+
+#### 2. 协作协议识别失败
+**症状**: 无法识别跨AI工具调用意图
+
+**解决方案**:
+- 确保使用标准协作协议格式
+- 检查协议中的CLI工具名称是否正确
+- 使用完整的任务描述
+- 避免使用模糊的指令
+
+#### 3. 配置文件冲突
+**症状**: 配置文件格式错误或内容冲突
+
+**解决方案**:
+- 备份现有配置文件
+- 使用 `ai-cli-router init` 重新生成配置
+- 手动检查配置文件格式
+- 查看配置验证日志
+
+#### 4. 性能问题
+**症状**: 跨工具调用响应缓慢
+
+**解决方案**:
+- 检查系统资源使用情况
+- 调整超时和重试设置
+- 使用并行处理模式
+- 优化任务描述的清晰度
+
+### 🔍 调试工具
+
+#### 日志查看
+```bash
+# 查看全局日志
+tail -f ~/.ai-cli-unified/logs/router.log
+
+# 查看工具特定日志
+tail -f ~/.config/{cli_name}/logs/collaboration.log
+```
+
+#### 状态检查
+```bash
+# 检查所有工具状态
+ai-cli-router status --verbose
+
+# 检查项目配置
+ai-cli-router check-project
+```
+
+#### 配置验证
+```bash
+# 验证全局配置
+ai-cli-router validate --global
+
+# 验证项目配置
+ai-cli-router validate --project
+```
+
+### 📞 获取帮助
+
+如果遇到无法解决的问题:
+
+1. **查看文档**: 访问项目的完整文档
+2. **社区支持**: 在社区论坛寻求帮助
+3. **问题报告**: 在GitHub上提交issue
+4. **日志分析**: 提供详细的错误日志
+
+### 🔄 重置和恢复
+
+```bash
+# 重置项目配置
+ai-cli-router reset --project
+
+# 重置全局配置
+ai-cli-router reset --global
+
+# 完全重置
+ai-cli-router reset --all
+```
+
+---
+
+*💡 提示: 定期更新AI CLI Router以获得最新功能和修复*
+"""
+
+    def _get_integration_type_display(self, integration_type) -> str:
+        """获取集成类型的显示名称"""
+        type_names = {
+            "hook_system": "钩子系统",
+            "extension_system": "扩展系统",
+            "class_inheritance": "类继承",
+            "workflow_pipeline": "工作流流水线",
+            "notification_hook": "通知钩子",
+            "mcp_server": "MCP服务器",
+            "slash_command": "斜杠命令"
+        }
+        return type_names.get(integration_type.value, integration_type.value)
+
+    def _get_status_display(self, status) -> str:
+        """获取状态的显示名称"""
+        status_names = {
+            "available": "✅ 可用",
+            "unavailable": "❌ 不可用",
+            "version_incompatible": "⚠️ 版本不兼容",
+            "config_missing": "⚠️ 配置缺失"
+        }
+        return status_names.get(status.value, status.value)
+
+    def _format_capabilities(self, capabilities: List[str]) -> str:
+        """格式化能力列表"""
+        if not capabilities:
+            return "- 基础AI助手功能"
+
+        formatted = []
+        for capability in capabilities:
+            formatted.append(f"- {capability}")
+
+        return "\n".join(formatted)
+
+    def _generate_protocol_examples(self, protocol: str, peer_clis: List[str]) -> List[str]:
+        """生成协议示例"""
+        if not peer_clis:
+            return [protocol.replace('{cli}', '工具名').replace('{task}', '任务')]
+
+        examples = []
+        for peer_cli in peer_clis[:3]:  # 最多3个示例
+            example_tasks = {
+                "qwen": ["生成代码", "重构函数", "编写测试"],
+                "gemini": ["分析性能", "优化查询", "数据可视化"],
+                "claude": ["架构设计", "代码审查", "需求分析"],
+                "iflow": ["创建工作流", "自动化部署", "流程优化"]
+            }
+
+            tasks = example_tasks.get(peer_cli, ["执行任务"])
+            for task in tasks[:2]:  # 每个工具最多2个任务
+                example = protocol.replace('{cli}', peer_cli).replace('{task}', task)
+                examples.append(example)
+
+        return examples
+
+    def _extract_sections(self, content: str) -> int:
+        """提取文档中的章节数量"""
+        sections = []
+        lines = content.split('\n')
+
+        for line in lines:
+            if line.strip().startswith('#'):
+                sections.append(line.strip())
+
+        return len(sections)