devsquad 3.6.0__py3-none-any.whl

scripts/collaboration/usage_tracker.py

@@ -0,0 +1,309 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""
+UsageTracker - 轻量级功能使用追踪系统
+
+用于追踪 DevSquad 各组件的使用情况，为优化决策提供数据支持。
+"""
+
+import json
+import threading
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, Any, Optional, List, Tuple
+from collections import defaultdict
+
+
+class UsageTracker:
+    """轻量级功能使用追踪器
+    
+    特性：
+    - 线程安全的使用统计
+    - 自动持久化到文件
+    - 支持错误追踪
+    - 生成使用报告
+    """
+    
+    def __init__(self, persist_file: Optional[str] = None):
+        """初始化追踪器
+        
+        Args:
+            persist_file: 持久化文件路径，默认为 .usage_stats.json
+        """
+        self.stats: Dict[str, Dict[str, Any]] = defaultdict(lambda: {
+            "count": 0,
+            "first_used": None,
+            "last_used": None,
+            "errors": 0,
+        })
+        self.persist_file = persist_file or ".usage_stats.json"
+        self._lock = threading.RLock()
+        self._load_stats()
+    
+    def track(self, feature_name: str, success: bool = True, 
+              metadata: Optional[Dict] = None) -> None:
+        """追踪功能使用
+        
+        Args:
+            feature_name: 功能名称，格式如 "dispatcher.dispatch"
+            success: 是否成功执行
+            metadata: 额外的元数据（可选）
+        """
+        with self._lock:
+            stat = self.stats[feature_name]
+            stat["count"] += 1
+            
+            now = datetime.now().isoformat()
+            if stat["first_used"] is None:
+                stat["first_used"] = now
+            stat["last_used"] = now
+            
+            if not success:
+                stat["errors"] += 1
+            
+            if metadata:
+                if "metadata" not in stat:
+                    stat["metadata"] = []
+                stat["metadata"].append(metadata)
+                # 只保留最近 10 条元数据
+                stat["metadata"] = stat["metadata"][-10:]
+    
+    def get_stats(self, feature_name: Optional[str] = None) -> Dict:
+        """获取统计数据
+        
+        Args:
+            feature_name: 功能名称，None 表示获取所有统计
+            
+        Returns:
+            统计数据字典
+        """
+        with self._lock:
+            if feature_name:
+                return dict(self.stats.get(feature_name, {}))
+            return {k: dict(v) for k, v in self.stats.items()}
+    
+    def get_top_features(self, limit: int = 10) -> List[Tuple[str, int]]:
+        """获取使用最多的功能
+        
+        Args:
+            limit: 返回的功能数量
+            
+        Returns:
+            [(功能名, 调用次数), ...] 列表
+        """
+        with self._lock:
+            sorted_features = sorted(
+                self.stats.items(),
+                key=lambda x: x[1]["count"],
+                reverse=True
+            )
+            return [(name, stats["count"]) for name, stats in sorted_features[:limit]]
+    
+    def get_unused_features(self, all_features: List[str]) -> List[str]:
+        """获取从未使用的功能
+        
+        Args:
+            all_features: 所有功能名称列表
+            
+        Returns:
+            未使用的功能名称列表
+        """
+        with self._lock:
+            used = set(self.stats.keys())
+            return [f for f in all_features if f not in used]
+    
+    def get_error_prone_features(self, min_calls: int = 5, 
+                                  error_threshold: float = 0.1) -> List[Tuple[str, float]]:
+        """获取高错误率的功能
+        
+        Args:
+            min_calls: 最小调用次数阈值
+            error_threshold: 错误率阈值（0.1 = 10%）
+            
+        Returns:
+            [(功能名] 列表
+        """
+        with self._lock:
+            error_prone = []
+            for name, stat in self.stats.items():
+                if stat["count"] >= min_calls:
+                    error_rate = stat["errors"] / stat["count"]
+                    if error_rate >= error_threshold:
+                        error_prone.append((name, error_rate))
+            return sorted(error_prone, key=lambda x: x[1], reverse=True)
+    
+    def generate_report(self) -> str:
+        """生成使用报告
+        
+        Returns:
+            Markdown 格式的报告文本
+        """
+        with self._lock:
+            total_calls = sum(s["count"] for s in self.stats.values())
+            total_errors = sum(s["errors"] for s in self.stats.values())
+            
+            lines = [
+                "# DevSquad 功能使用报告",
+                f"\n**生成时间**: {datetime.now().isoformat()}",
+                f"**追踪功能数**: {len(self.stats)}",
+                f"**总调用次数**: {total_calls:,}",
+                f"**总错误次数**: {total_errors}",
+                f"**总体错误率**: {(total_errors/max(1,total_calls)*100):.2f}%",
+                "\n## Top 10 最常用功能\n",
+            ]
+            
+            for name, count in self.get_top_features(10):
+                stat = self.stats[name]
+                error_rate = (stat["errors"] / max(1, stat["count"])) * 100
+                lines.append(f"- **{name}**: {count:,} 次调用, 错误率 {error_rate:.1f}%")
+            
+            # 按组件分类
+            lines.append("\n## 按组件分类\n")
+            by_component = defaultdict(int)
+            for name, stat in self.stats.items():
+                component = name.split(".")[0] if "." in name else "other"
+                by_component[component] += stat["count"]
+            
+            for component, count in sorted(by_component.items(), 
+                                          key=lambda x: x[1], reverse=True):
+                pct = (count / max(1, total_calls)) * 100
+                lines.append(f"- **{component}**: {count:,} 次调用 ({pct:.1f}%)")
+            
+            # 高错误率功能
+            error_prone = self.get_error_prone_features()
+            if error_prone:
+                lines.append("\n## ⚠️ 高错误率功能\n")
+                for name, error_rate in error_prone[:5]:
+                    stat = self.stats[name]
+                    lines.append(
+                        f"- **{name}**: 错误率 {error_rate*100:.1f}% "
+                        f"({stat['errors']}/{stat['count']} 次调用)"
+                    )
+            
+            # 使用频率分布
+            lines.append("\n## 使用频率分布\n")
+            freq_buckets = {
+                "高频 (>100次)": 0,
+                "中频 (10-100次)": 0,
+                "低频 (1-10次)": 0,
+            }
+            for stat in self.stats.values():
+                count = stat["count"]
+                if count > 100:
+                    freq_buckets["高频 (>100次)"] += 1
+                elif count >= 10:
+                    freq_buckets["中频 (10-100次)"] += 1
+                else:
+                    freq_buckets["低频 (1-10次)"] += 1
+            
+            for bucket, num in freq_buckets.items():
+                pct = (num / max(1, len(self.stats))) * 100
+                lines.append(f"- {bucket}: {num} 个功能 ({pct:.1f}%)")
+            
+            return "\n".join(lines)
+    
+    def save(self) -> bool:
+        """保存统计数据到文件
+        
+        Returns:
+            是否保存成功
+        """
+        with self._lock:
+            try:
+                with open(self.persist_file, 'w', encoding='utf-8') as f:
+                    json.dump(dict(self.stats), f, indent=2, ensure_ascii=False)
+                return True
+            except Exception as e:
+                print(f"Failed to save usage stats: {e}")
+                return False
+    
+    def _load_stats(self) -> None:
+        """从文件加载统计数据"""
+        try:
+            if Path(self.persist_file).exists():
+                with open(self.persist_file, 'r', encoding='utf-8') as f:
+                    loaded = json.load(f)
+                    self.stats.update(loaded)
+        except Exception as e:
+            print(f"Failed to load usage stats: {e}")
+    
+    def clear(self) -> int:
+        """清空所有统计数据
+        
+        Returns:
+            清空的功能数量
+        """
+        with self._lock:
+            count = len(self.stats)
+            self.stats.clear()
+            return count
+    
+    def export_json(self) -> str:
+        """导出为 JSON 字符串
+        
+        Returns:
+            JSON 格式的统计数据
+        """
+        with self._lock:
+            return json.dumps(dict(self.stats), indent=2, ensure_ascii=False)
+
+
+# 全局单例
+_global_tracker: Optional[UsageTracker] = None
+_tracker_lock = threading.Lock()
+
+
+def get_tracker() -> UsageTracker:
+    """获取全局追踪器实例（线程安全）
+    
+    Returns:
+        全局 UsageTracker 实例
+    """
+    global _global_tracker
+    if _global_tracker is None:
+        with _tracker_lock:
+            if _global_tracker is None:
+                _global_tracker = UsageTracker()
+    return _global_tracker
+
+
+def track_usage(feature_name: str, success: bool = True, 
+                metadata: Optional[Dict] = None) -> None:
+    """便捷函数：追踪功能使用
+    
+    Args:
+        feature_name: 功能名称
+        success: 是否成功
+        metadata: 元数据
+    """
+    get_tracker().track(feature_name, success, metadata)
+
+
+def get_usage_stats(feature_name: Optional[str] = None) -> Dict:
+    """便捷函数：获取统计数据
+    
+    Args:
+        feature_name: 功能名称，None 表示获取所有
+        
+    Returns:
+        统计数据字典
+    """
+    return get_tracker().get_stats(feature_name)
+
+
+def generate_usage_report() -> str:
+    """便捷函数：生成使用报告
+    
+    Returns:
+        Markdown 格式的报告
+    """
+    return get_tracker().generate_report()
+
+
+def save_usage_stats() -> bool:
+    """便捷函数：保存统计数据
+    
+    Returns:
+        是否保存成功
+    """
+    return get_tracker().save()

scripts/collaboration/user_friendly_error.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""
+User-Friendly Error System — 用户友好的错误提示
+
+将技术性错误信息翻译为人类可读的提示，包含：
+- 友好的错误描述
+- 修复建议
+- 使用示例
+
+Author: DevSquad Team
+Version: 1.0
+"""
+
+from typing import Optional
+
+
+class UserFriendlyError(Exception):
+    """
+    用户友好的错误提示
+
+    Attributes:
+        message: 人类可读的错误描述
+        suggestion: 修复建议
+        example: 使用示例
+        original_error: 原始技术错误（可选）
+    """
+
+    def __init__(
+        self,
+        message: str,
+        suggestion: Optional[str] = None,
+        example: Optional[str] = None,
+        original_error: Optional[Exception] = None,
+    ):
+        self.message = message
+        self.suggestion = suggestion
+        self.example = example
+        self.original_error = original_error
+        super().__init__(self.format())
+
+    def format(self) -> str:
+        parts = [f"❌ {self.message}"]
+        if self.suggestion:
+            parts.append(f"💡 {self.suggestion}")
+        if self.example:
+            parts.append(f"📝 示例: {self.example}")
+        return "\n".join(parts)
+
+    def to_dict(self) -> dict:
+        return {
+            "error": self.message,
+            "suggestion": self.suggestion,
+            "example": self.example,
+        }
+
+
+ERROR_TEMPLATES = {
+    "task_too_short": {
+        "message": "任务描述太短了，请详细说明你想做什么",
+        "suggestion": "好的任务描述应该包含：做什么 + 为什么 + 有什么特殊要求",
+        "example": "devsquad dispatch -t '设计一个支持手机号和邮箱登录的用户认证系统'",
+    },
+    "task_too_long": {
+        "message": "任务描述太长了，请精简到10000字以内",
+        "suggestion": "把核心需求说清楚即可，细节可以在后续对话中补充",
+        "example": "devsquad dispatch -t '优化数据库查询性能，重点关注慢查询和索引'",
+    },
+    "task_empty": {
+        "message": "请输入任务描述",
+        "suggestion": "告诉 DevSquad 你想做什么，它会自动匹配合适的AI角色来帮你",
+        "example": "devsquad dispatch -t '设计用户权限系统'",
+    },
+    "task_invalid_type": {
+        "message": "任务描述需要是文字内容",
+        "suggestion": "请用自然语言描述你的任务，中文或英文都可以",
+        "example": "devsquad dispatch -t 'Review the authentication module for security issues'",
+    },
+    "task_forbidden_content": {
+        "message": "任务描述包含不允许的内容",
+        "suggestion": "请移除HTML标签、脚本代码或SQL语句，使用纯文本描述任务",
+        "example": "devsquad dispatch -t '实现用户注册功能'",
+    },
+    "task_injection_detected": {
+        "message": "检测到异常的指令模式，请正常描述你的任务",
+        "suggestion": "直接描述你想完成的项目任务即可，不需要特殊的指令格式",
+        "example": "devsquad dispatch -t '搭建微服务架构的订单系统'",
+    },
+    "role_not_found": {
+        "message": "找不到指定的角色",
+        "suggestion": "使用 'devsquad roles' 查看所有可用角色，或省略 -r 参数让系统自动匹配",
+        "example": "devsquad dispatch -t '设计系统架构' -r architect security",
+    },
+    "too_many_roles": {
+        "message": "角色数量太多了（最多10个）",
+        "suggestion": "精选最核心的2-4个角色，或省略 -r 让系统自动匹配",
+        "example": "devsquad dispatch -t '设计安全系统' -r arch sec",
+    },
+    "backend_unavailable": {
+        "message": "AI后端不可用",
+        "suggestion": "检查API Key是否设置正确，或使用Mock模式测试",
+        "example": "export OPENAI_API_KEY='your-key' && devsquad dispatch -t '...'",
+    },
+    "config_invalid": {
+        "message": "配置文件格式有误",
+        "suggestion": "运行 'devsquad init' 重新生成配置文件",
+        "example": "devsquad init",
+    },
+    "dispatch_failed": {
+        "message": "任务调度失败",
+        "suggestion": "请检查任务描述是否清晰，或尝试简化任务后重试",
+        "example": "devsquad dispatch -t '实现用户登录功能'",
+    },
+    "path_traversal": {
+        "message": "检测到非法路径",
+        "suggestion": "请使用正常的标识符，不要包含路径分隔符",
+        "example": "devsquad dispatch -t '查看项目状态'",
+    },
+    "unknown_template": {
+        "message": "找不到指定的生命周期模板",
+        "suggestion": "使用 'devsquad lifecycle list' 查看可用模板",
+        "example": "devsquad spec -t '需求分析'",
+    },
+}
+
+
+def make_user_friendly_error(error_key: str, **kwargs) -> UserFriendlyError:
+    """
+    根据错误键创建用户友好的错误
+
+    Args:
+        error_key: 错误模板键
+        **kwargs: 额外参数（如 original_error）
+
+    Returns:
+        UserFriendlyError 实例
+    """
+    template = ERROR_TEMPLATES.get(error_key, {})
+    return UserFriendlyError(
+        message=template.get("message", f"操作失败 ({error_key})"),
+        suggestion=template.get("suggestion"),
+        example=template.get("example"),
+        original_error=kwargs.get("original_error"),
+    )
+
+
+def translate_validation_result(reason: str, original: Optional[Exception] = None) -> UserFriendlyError:
+    """
+    将 InputValidator 的 ValidationResult.reason 翻译为用户友好的错误
+
+    Args:
+        reason: InputValidator 返回的原始原因
+        original: 原始异常
+
+    Returns:
+        UserFriendlyError 实例
+    """
+    reason_lower = reason.lower() if reason else ""
+
+    if "too short" in reason_lower or "min" in reason_lower:
+        return make_user_friendly_error("task_too_short", original_error=original)
+    elif "too long" in reason_lower or "max" in reason_lower:
+        return make_user_friendly_error("task_too_long", original_error=original)
+    elif "empty" in reason_lower or "whitespace" in reason_lower:
+        return make_user_friendly_error("task_empty", original_error=original)
+    elif "string" in reason_lower or "type" in reason_lower:
+        return make_user_friendly_error("task_invalid_type", original_error=original)
+    elif "forbidden" in reason_lower:
+        return make_user_friendly_error("task_forbidden_content", original_error=original)
+    elif "injection" in reason_lower or "prompt" in reason_lower:
+        return make_user_friendly_error("task_injection_detected", original_error=original)
+    else:
+        return UserFriendlyError(
+            message=f"输入验证失败: {reason}",
+            suggestion="请检查输入内容后重试",
+            original_error=original,
+        )