aiecs 1.0.7__py3-none-any.whl → 1.1.0__py3-none-any.whl

aiecs/scripts/tools_develop/README.md

@@ -0,0 +1,340 @@
+# 工具开发辅助脚本
+
+本目录包含用于 AIECS 工具开发和维护的验证脚本，帮助开发者确保工具质量和 Schema 自动生成的有效性。
+
+## 📋 脚本列表
+
+### 1. 类型注解检查器 (`check_type_annotations.py`)
+
+检查工具方法的类型注解完整性，确保所有方法都有完整的类型注解（参数类型 + 返回类型）。
+
+**用途**：
+- 验证新开发的工具是否有完整的类型注解
+- 检查现有工具的类型注解覆盖率
+- 为自动 Schema 生成提供基础保障
+
+**命令**：
+```bash
+# 检查所有工具
+aiecs-tools-check-annotations
+
+# 检查特定工具
+aiecs-tools-check-annotations pandas
+
+# 检查多个工具
+aiecs-tools-check-annotations pandas chart image
+
+# 显示详细的改进建议
+aiecs-tools-check-annotations pandas --verbose
+```
+
+**输出示例**：
+```
+====================================================================================================
+工具类型注解检查器
+====================================================================================================
+
+✅ pandas: 38/38 方法有完整类型注解 (100.0%)
+
+⚠️ my_tool: 5/10 方法有完整类型注解 (50.0%)
+
+  需要改进的方法:
+    ✗ process_data: 无类型注解
+    ⚠ filter_records: 部分类型注解
+      → 为参数 'condition' 添加类型注解
+      → 添加返回类型注解
+
+====================================================================================================
+总体统计: 43/48 方法有完整类型注解 (89.6%)
+====================================================================================================
+```
+
+### 2. Schema 质量验证器 (`validate_tool_schemas.py`)
+
+验证自动生成的 Schema 质量，识别需要改进的文档字符串。
+
+**用途**：
+- 验证 Schema 自动生成是否成功
+- 评估生成的 Schema 描述质量
+- 指导开发者改进文档字符串
+
+**命令**：
+```bash
+# 验证所有工具
+aiecs-tools-validate-schemas
+
+# 验证特定工具
+aiecs-tools-validate-schemas pandas
+
+# 显示详细的改进建议
+aiecs-tools-validate-schemas pandas --verbose
+
+# 显示示例 Schema
+aiecs-tools-validate-schemas pandas --show-examples
+```
+
+**输出示例**：
+```
+====================================================================================================
+工具 Schema 质量验证器
+====================================================================================================
+
+✅ chart
+  方法数: 3
+  成功生成 Schema: 3 (100.0%)
+  描述质量: 100.0%
+  综合评分: 100.0% (A (优秀))
+
+❌ pandas
+  方法数: 38
+  成功生成 Schema: 38 (100.0%)
+  描述质量: 0.0%
+  综合评分: 66.7% (D (需改进))
+
+  需要改进的方法 (38 个):
+
+    filter:
+      💡 在文档字符串的 Args 部分为参数 'records' 添加描述
+      💡 在文档字符串的 Args 部分为参数 'condition' 添加描述
+
+====================================================================================================
+总体统计:
+  方法数: 41
+  Schema 生成率: 41/41 (100.0%)
+  描述质量: 7.3%
+====================================================================================================
+```
+
+## 🚀 工具开发工作流
+
+### 新工具开发流程
+
+1. **编写工具类**
+   ```python
+   from aiecs.tools.base_tool import BaseTool
+   from typing import List, Dict
+   
+   class MyTool(BaseTool):
+       """My custom tool"""
+       
+       def process(self, data: List[Dict], threshold: float = 0.5) -> Dict:
+           """
+           Process data with threshold.
+           
+           Args:
+               data: Input data to process
+               threshold: Processing threshold (0.0 to 1.0)
+           
+           Returns:
+               Processing results
+           """
+           pass
+   ```
+
+2. **检查类型注解**
+   ```bash
+   aiecs-tools-check-annotations my_tool --verbose
+   ```
+   
+   确保所有方法都有 ✅ 标记。
+
+3. **验证 Schema 质量**
+   ```bash
+   aiecs-tools-validate-schemas my_tool --show-examples
+   ```
+   
+   目标：综合评分 ≥ 80% (B 良好)
+
+4. **改进文档字符串**
+   
+   根据验证器的建议，改进文档字符串：
+   ```python
+   def process(self, data: List[Dict], threshold: float = 0.5) -> Dict:
+       """
+       Process data with threshold filtering.
+       
+       Args:
+           data: List of data records to process (each record is a dict)
+           threshold: Minimum confidence threshold for filtering (0.0 to 1.0, default: 0.5)
+       
+       Returns:
+           Dictionary containing processed results and statistics
+       """
+       pass
+   ```
+
+5. **重新验证**
+   ```bash
+   aiecs-tools-validate-schemas my_tool
+   ```
+
+### 现有工具维护流程
+
+1. **定期检查**
+   ```bash
+   # 每次修改工具后运行
+   aiecs-tools-check-annotations my_tool
+   aiecs-tools-validate-schemas my_tool
+   ```
+
+2. **批量检查**
+   ```bash
+   # 检查所有工具
+   aiecs-tools-check-annotations
+   aiecs-tools-validate-schemas
+   ```
+
+3. **持续改进**
+   - 优先改进评分 < 80% 的工具
+   - 为通用描述（如 "Parameter xxx"）添加有意义的说明
+
+## 📊 质量标准
+
+### 类型注解标准
+
+- ✅ **优秀 (100%)**：所有方法都有完整类型注解
+- ⚠️ **良好 (80-99%)**：大部分方法有完整类型注解
+- ❌ **需改进 (<80%)**：缺少大量类型注解
+
+### Schema 质量标准
+
+- ✅ **A (优秀) ≥90%**：Schema 生成成功，描述质量高
+- ⚠️ **B (良好) 80-89%**：Schema 生成成功，描述质量中等
+- ⚠️ **C (中等) 70-79%**：Schema 生成成功，描述质量较低
+- ❌ **D (需改进) <70%**：Schema 生成失败或描述质量差
+
+## 💡 最佳实践
+
+### 1. 完整的类型注解
+
+```python
+# ✅ 好的示例
+def filter(self, records: List[Dict], condition: str) -> List[Dict]:
+    pass
+
+# ❌ 不好的示例
+def filter(self, records, condition):  # 缺少类型注解
+    pass
+
+def filter(self, records: List[Dict], condition):  # 部分缺失
+    pass
+```
+
+### 2. 详细的文档字符串
+
+使用 Google 或 NumPy 风格：
+
+```python
+# ✅ Google 风格（推荐）
+def filter(self, records: List[Dict], condition: str) -> List[Dict]:
+    """
+    Filter DataFrame based on a condition.
+    
+    Args:
+        records: List of records to filter (each record is a dict)
+        condition: Filter condition using pandas query syntax (e.g., 'age > 30')
+    
+    Returns:
+        Filtered list of records
+    """
+    pass
+
+# ✅ NumPy 风格
+def filter(self, records: List[Dict], condition: str) -> List[Dict]:
+    """
+    Filter DataFrame based on a condition.
+    
+    Parameters
+    ----------
+    records : List[Dict]
+        List of records to filter (each record is a dict)
+    condition : str
+        Filter condition using pandas query syntax (e.g., 'age > 30')
+    
+    Returns
+    -------
+    List[Dict]
+        Filtered list of records
+    """
+    pass
+```
+
+### 3. 有意义的描述
+
+```python
+# ❌ 不好的描述
+"""
+Args:
+    records: Parameter records
+    condition: Parameter condition
+"""
+
+# ✅ 好的描述
+"""
+Args:
+    records: List of data records to filter (each record contains fields like 'name', 'age', etc.)
+    condition: Filter condition using pandas query syntax (e.g., 'age > 30 and status == "active"')
+"""
+```
+
+### 4. 处理复杂类型
+
+```python
+from typing import List, Dict, Optional, Union
+import pandas as pd
+
+# ✅ 使用标准类型
+def process(self, data: List[Dict]) -> Dict:
+    pass
+
+# ✅ pandas 类型会自动映射为 Any
+def process(self, df: pd.DataFrame) -> pd.DataFrame:
+    pass
+
+# ✅ 可选参数
+def process(self, data: List[Dict], config: Optional[Dict] = None) -> Dict:
+    pass
+```
+
+## 🔧 故障排查
+
+### 问题：类型注解检查失败
+
+**原因**：缺少类型注解或使用了不支持的类型
+
+**解决**：
+1. 为所有参数添加类型注解
+2. 添加返回类型注解
+3. 使用标准类型（List, Dict, str, int, float, bool 等）
+
+### 问题：Schema 生成失败
+
+**原因**：
+- 方法没有参数（除了 self）→ 这是正常的，无需 Schema
+- 类型注解不完整 → 运行类型注解检查器
+- 使用了不支持的类型 → 会自动映射为 Any
+
+### 问题：描述质量低
+
+**原因**：文档字符串缺少 Args 部分或描述不详细
+
+**解决**：
+1. 添加文档字符串的 Args 部分
+2. 为每个参数添加详细描述
+3. 使用 Google 或 NumPy 风格
+
+## 📚 相关文档
+
+- [Schema Generator 技术文档](../../../docs/TOOLS/TOOLS_SCHEMA_GENERATOR.md)
+- [LangChain Adapter 技术文档](../../../docs/TOOLS/TOOLS_LANGCHAIN_ADAPTER.md)
+- [BaseTool 开发指南](../../../docs/TOOLS/TOOLS_BASE_TOOL.md)
+
+## 🤝 贡献
+
+如果你发现这些工具有改进空间，欢迎提交 PR 或 Issue！
+
+---
+
+**维护者**: AIECS Tools Team  
+**最后更新**: 2025-10-02
+

aiecs/scripts/tools_develop/__init__.py

@@ -0,0 +1,16 @@
+"""
+工具开发辅助脚本
+
+提供工具开发和维护所需的验证和检查功能。
+"""
+
+from .check_type_annotations import check_annotations, main as check_annotations_main
+from .validate_tool_schemas import validate_schemas, main as validate_schemas_main
+
+__all__ = [
+    'check_annotations',
+    'check_annotations_main',
+    'validate_schemas',
+    'validate_schemas_main',
+]
+

aiecs/scripts/tools_develop/check_type_annotations.py

@@ -0,0 +1,263 @@
+#!/usr/bin/env python3
+"""
+工具类型注解检查器
+
+用于工具开发和维护，检查工具方法的类型注解完整性。
+帮助开发者确保工具方法有完整的类型注解，为自动 Schema 生成提供基础。
+
+使用方法:
+    # 检查所有工具
+    aiecs tools check-annotations
+    
+    # 检查特定工具
+    aiecs tools check-annotations pandas
+    
+    # 检查多个工具
+    aiecs tools check-annotations pandas chart image
+"""
+
+import sys
+import inspect
+from typing import get_type_hints, Optional, List, Dict, Any
+
+# 确保可以导入 aiecs
+import os
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(__file__)))))
+
+from aiecs.tools import discover_tools, TOOL_CLASSES
+
+
+def check_method_type_annotations(method, method_name):
+    """
+    检查方法的类型注解完整性
+    
+    Returns:
+        dict: {
+            'has_annotations': bool,
+            'complete': bool,
+            'params_with_types': list,
+            'params_without_types': list,
+            'has_return_type': bool,
+            'suggestions': list  # 改进建议
+        }
+    """
+    try:
+        sig = inspect.signature(method)
+        type_hints = get_type_hints(method)
+    except Exception:
+        return {
+            'has_annotations': False,
+            'complete': False,
+            'params_with_types': [],
+            'params_without_types': [],
+            'has_return_type': False,
+            'error': True,
+            'suggestions': ['无法获取类型信息，请检查方法定义']
+        }
+    
+    params_with_types = []
+    params_without_types = []
+    suggestions = []
+    
+    for param_name, param in sig.parameters.items():
+        if param_name == 'self':
+            continue
+        
+        if param_name in type_hints:
+            params_with_types.append(param_name)
+        else:
+            params_without_types.append(param_name)
+            suggestions.append(f"为参数 '{param_name}' 添加类型注解")
+    
+    has_return_type = 'return' in type_hints
+    if not has_return_type:
+        suggestions.append("添加返回类型注解")
+    
+    has_any_annotations = len(params_with_types) > 0 or has_return_type
+    is_complete = len(params_without_types) == 0 and has_return_type
+    
+    return {
+        'has_annotations': has_any_annotations,
+        'complete': is_complete,
+        'params_with_types': params_with_types,
+        'params_without_types': params_without_types,
+        'has_return_type': has_return_type,
+        'error': False,
+        'suggestions': suggestions
+    }
+
+
+def analyze_tool(tool_name, tool_class):
+    """分析单个工具的类型注解情况"""
+    methods_info = []
+    
+    for method_name in dir(tool_class):
+        # 跳过私有方法和特殊方法
+        if method_name.startswith('_'):
+            continue
+        
+        # 跳过基类方法
+        if method_name in ['run', 'run_async', 'run_batch']:
+            continue
+        
+        method = getattr(tool_class, method_name)
+        
+        # 跳过非方法属性
+        if not callable(method):
+            continue
+        
+        # 跳过类（如 Config, Schema 等）
+        if isinstance(method, type):
+            continue
+        
+        # 检查类型注解
+        annotation_info = check_method_type_annotations(method, method_name)
+        annotation_info['method_name'] = method_name
+        
+        methods_info.append(annotation_info)
+    
+    return methods_info
+
+
+def print_tool_report(tool_name: str, methods_info: List[Dict], verbose: bool = False):
+    """打印单个工具的报告"""
+    
+    total = len(methods_info)
+    complete = sum(1 for m in methods_info if m['complete'])
+    partial = sum(1 for m in methods_info if m['has_annotations'] and not m['complete'])
+    none = sum(1 for m in methods_info if not m['has_annotations'])
+    
+    # 计算覆盖率
+    coverage = (complete / total * 100) if total > 0 else 0
+    
+    # 状态图标
+    if coverage == 100:
+        status = "✅"
+    elif coverage >= 80:
+        status = "⚠️"
+    else:
+        status = "❌"
+    
+    print(f"\n{status} {tool_name}: {complete}/{total} 方法有完整类型注解 ({coverage:.1f}%)")
+    
+    if verbose or coverage < 100:
+        # 显示不完整的方法
+        incomplete = [m for m in methods_info if not m['complete']]
+        if incomplete:
+            print(f"\n  需要改进的方法:")
+            for method_info in incomplete:
+                method_name = method_info['method_name']
+                suggestions = method_info.get('suggestions', [])
+                
+                if method_info['error']:
+                    print(f"    ✗ {method_name}: 无法获取类型信息")
+                elif not method_info['has_annotations']:
+                    print(f"    ✗ {method_name}: 无类型注解")
+                else:
+                    print(f"    ⚠ {method_name}: 部分类型注解")
+                
+                # 显示改进建议
+                if suggestions and verbose:
+                    for suggestion in suggestions:
+                        print(f"        → {suggestion}")
+
+
+def check_annotations(tool_names: Optional[List[str]] = None, verbose: bool = False):
+    """
+    检查工具的类型注解
+    
+    Args:
+        tool_names: 要检查的工具名称列表，None 表示检查所有工具
+        verbose: 是否显示详细信息
+    """
+    print("=" * 100)
+    print("工具类型注解检查器")
+    print("=" * 100)
+    
+    discover_tools()
+    
+    # 确定要检查的工具
+    if tool_names:
+        tools_to_check = {}
+        for name in tool_names:
+            if name in TOOL_CLASSES:
+                tools_to_check[name] = TOOL_CLASSES[name]
+            else:
+                print(f"\n❌ 工具 '{name}' 不存在")
+        
+        if not tools_to_check:
+            print("\n没有找到要检查的工具")
+            return
+    else:
+        tools_to_check = TOOL_CLASSES
+    
+    # 检查每个工具
+    all_stats = []
+    for tool_name in sorted(tools_to_check.keys()):
+        tool_class = tools_to_check[tool_name]
+        methods_info = analyze_tool(tool_name, tool_class)
+        
+        if methods_info:
+            print_tool_report(tool_name, methods_info, verbose)
+            
+            total = len(methods_info)
+            complete = sum(1 for m in methods_info if m['complete'])
+            all_stats.append((tool_name, total, complete))
+    
+    # 总体统计
+    if len(all_stats) > 1:
+        total_methods = sum(s[1] for s in all_stats)
+        total_complete = sum(s[2] for s in all_stats)
+        overall_coverage = (total_complete / total_methods * 100) if total_methods > 0 else 0
+        
+        print("\n" + "=" * 100)
+        print(f"总体统计: {total_complete}/{total_methods} 方法有完整类型注解 ({overall_coverage:.1f}%)")
+        print("=" * 100)
+    
+    print("\n💡 提示:")
+    print("  - 完整类型注解包括：所有参数的类型 + 返回类型")
+    print("  - 使用 --verbose 查看详细的改进建议")
+    print("  - 完整的类型注解是自动 Schema 生成的基础")
+
+
+def main():
+    """命令行入口"""
+    import argparse
+    
+    parser = argparse.ArgumentParser(
+        description='检查工具方法的类型注解完整性',
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+示例:
+  # 检查所有工具
+  aiecs tools check-annotations
+  
+  # 检查特定工具
+  aiecs tools check-annotations pandas
+  
+  # 检查多个工具并显示详细信息
+  aiecs tools check-annotations pandas chart --verbose
+        """
+    )
+    
+    parser.add_argument(
+        'tools',
+        nargs='*',
+        help='要检查的工具名称（不指定则检查所有工具）'
+    )
+    
+    parser.add_argument(
+        '-v', '--verbose',
+        action='store_true',
+        help='显示详细的改进建议'
+    )
+    
+    args = parser.parse_args()
+    
+    tool_names = args.tools if args.tools else None
+    check_annotations(tool_names, args.verbose)
+
+
+if __name__ == '__main__':
+    main()
+