aiecs 1.5.1__py3-none-any.whl

aiecs/scripts/tools_develop/TOOL_AUTO_DISCOVERY.md

@@ -0,0 +1,234 @@
+# 工具自动发现机制
+
+## 📋 概述
+
+从现在开始，**无需手动维护工具列表**！系统会自动发现所有使用 `@register_tool` 装饰器注册的工具。
+
+## ✨ 特性
+
+### 1. 自动工具发现
+- ✅ 自动扫描 `aiecs/tools/task_tools/`、`aiecs/tools/docs/`、`aiecs/tools/statistics/` 目录
+- ✅ 自动识别所有 `@register_tool` 装饰器
+- ✅ 自动提取工具名称和描述
+- ✅ 自动分类（task/docs/statistics）
+
+### 2. 零维护成本
+- ✅ 添加新工具：只需在工具类上添加 `@register_tool("tool_name")` 装饰器
+- ✅ 删除工具：直接删除文件或移除装饰器
+- ✅ 重命名工具：修改装饰器参数即可
+- ✅ 无需修改任何配置文件
+
+## 🔧 工作原理
+
+### aiecs/tools/__init__.py
+
+```python
+def _auto_discover_tools():
+    """自动发现所有工具"""
+    # 扫描工具目录
+    for dir_name, category in [('task_tools', 'task'), ('docs', 'docs'), ('statistics', 'statistics')]:
+        # 查找所有 Python 文件
+        for filename in os.listdir(dir_path):
+            # 读取文件内容
+            # 使用正则表达式查找 @register_tool 装饰器
+            pattern = r'@register_tool\([\'"]([^\'"]+)[\'"]\)'
+            matches = re.findall(pattern, content)
+            # 提取工具名称和描述
+            # 注册为占位符，等待懒加载
+```
+
+### verify_tools.py
+
+```python
+def auto_discover_tool_modules():
+    """自动发现工具模块映射"""
+    # 扫描工具目录
+    # 查找 @register_tool 装饰器
+    # 建立工具名称到模块路径的映射
+    # 返回映射表供动态加载使用
+```
+
+## 📝 如何添加新工具
+
+### 步骤 1: 创建工具文件
+
+在合适的目录创建工具文件（例如：`aiecs/tools/task_tools/my_new_tool.py`）
+
+### 步骤 2: 添加装饰器
+
+```python
+from aiecs.tools import register_tool
+from aiecs.tools.base_tool import BaseTool
+
+@register_tool("my_new_tool")
+class MyNewTool(BaseTool):
+    """
+    这是一个新工具的简短描述。
+    
+    这个描述会被自动提取并显示在工具列表中。
+    """
+    
+    def my_method(self, param: str) -> str:
+        """执行某个操作"""
+        return f"Result: {param}"
+```
+
+### 步骤 3: 验证
+
+运行验证脚本查看新工具是否被发现：
+
+```bash
+poetry run python -m aiecs.scripts.tools_develop.verify_tools
+```
+
+就这样！**无需修改任何其他文件**！
+
+## 🎯 支持的目录结构
+
+```
+aiecs/tools/
+├── task_tools/          # 任务工具 (category: task)
+│   ├── chart_tool.py    # @register_tool("chart")
+│   ├── pandas_tool.py   # @register_tool("pandas")
+│   └── ...
+├── docs/                # 文档工具 (category: docs)
+│   ├── document_parser_tool.py    # @register_tool("document_parser")
+│   ├── document_writer_tool.py    # @register_tool("document_writer")
+│   └── ...
+└── statistics/          # 统计工具 (category: statistics)
+    ├── data_loader_tool.py        # @register_tool("data_loader")
+    ├── data_profiler_tool.py      # @register_tool("data_profiler")
+    └── ...
+```
+
+## 🔍 描述提取规则
+
+系统会自动提取类文档字符串的**第一行**作为工具描述：
+
+```python
+@register_tool("example")
+class ExampleTool(BaseTool):
+    """
+    这一行会被用作工具描述 ✅
+    
+    下面的内容不会被提取。
+    可以写详细的文档说明。
+    """
+```
+
+**建议**：
+- 第一行保持简短（< 200 字符）
+- 清晰描述工具的主要功能
+- 避免使用多行描述
+
+## 📊 当前发现的工具统计
+
+截至最后扫描，系统发现了 **26 个工具**：
+
+- **任务工具** (10个)：chart, classifier, image, office, pandas, report, research, scraper, search, stats
+- **文档工具** (7个)：document_parser, document_writer, document_creator, document_layout, content_insertion, ai_document_orchestrator, ai_document_writer_orchestrator
+- **数据统计工具** (9个)：data_loader, data_profiler, data_transformer, data_visualizer, model_trainer, statistical_analyzer, ai_data_analysis_orchestrator, ai_insight_generator, ai_report_orchestrator
+
+## ⚡ 性能优化
+
+### 占位符机制
+- 工具发现时创建轻量级占位符
+- 不导入实际工具模块（避免重依赖）
+- 只在实际使用时才加载工具
+
+### 懒加载
+- `verify_tools.py` 只在用户选择工具时才加载模块
+- 避免启动时加载所有工具
+- 提高响应速度
+
+## 🧪 测试验证
+
+### 验证工具发现
+```bash
+poetry run python -m aiecs.scripts.tools_develop.verify_tools
+```
+
+### 验证特定工具
+在交互模式中输入工具名称或序号：
+```
+👉 请选择工具 > pandas
+👉 请选择工具 > 7
+```
+
+### 验证描述提取
+检查工具列表中的描述是否正确提取自类文档字符串。
+
+## 🔄 兼容性
+
+### 向后兼容
+- 现有工具无需修改
+- 只要有 `@register_tool` 装饰器即可被发现
+- 保持与现有代码的兼容性
+
+### 新增目录支持
+如果未来需要添加新的工具目录（如 `aiecs/tools/ml_tools/`），只需修改两处：
+
+1. **aiecs/tools/__init__.py**
+```python
+tool_dirs = [
+    ('task_tools', 'task'),
+    ('docs', 'docs'),
+    ('statistics', 'statistics'),
+    ('ml_tools', 'ml'),  # 新增
+]
+```
+
+2. **verify_tools.py**
+```python
+tool_dirs = {
+    'task_tools': 'aiecs.tools.task_tools',
+    'docs': 'aiecs.tools.docs',
+    'statistics': 'aiecs.tools.statistics',
+    'ml_tools': 'aiecs.tools.ml_tools',  # 新增
+}
+```
+
+## ❓ 常见问题
+
+### Q: 工具没有被发现？
+**A:** 检查以下几点：
+1. 文件是否在支持的目录中（task_tools/docs/statistics）
+2. 是否使用了 `@register_tool("name")` 装饰器
+3. 文件名是否以 `.py` 结尾且不是 `__init__.py`
+
+### Q: 描述显示不正确？
+**A:** 检查类文档字符串：
+1. 文档字符串必须紧跟类定义
+2. 使用三引号 `"""`
+3. 确保第一行是简短描述
+
+### Q: 如何重命名工具？
+**A:** 只需修改装饰器参数：
+```python
+# 旧
+@register_tool("old_name")
+
+# 新
+@register_tool("new_name")
+```
+
+### Q: 如何临时禁用工具？
+**A:** 两种方法：
+1. 注释掉 `@register_tool` 装饰器
+2. 移动文件到其他目录
+
+## 🎉 优势总结
+
+| 特性 | 手动维护 | 自动发现 |
+|------|---------|---------|
+| 添加工具 | 需修改配置文件 | 只需添加装饰器 ✅ |
+| 删除工具 | 需修改配置文件 | 直接删除文件 ✅ |
+| 维护成本 | 高 | 零 ✅ |
+| 出错风险 | 容易遗漏 | 自动同步 ✅ |
+| 描述准确性 | 可能不一致 | 直接提取 ✅ |
+
+---
+
+**维护者**: AIECS Tools Team  
+**最后更新**: 2025-10-14
+

aiecs/scripts/tools_develop/__init__.py

@@ -0,0 +1,21 @@
+"""
+工具开发辅助脚本
+
+提供工具开发和维护所需的验证和检查功能。
+"""
+
+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,259 @@
+#!/usr/bin/env python3
+"""
+工具类型注解检查器
+
+用于工具开发和维护，检查工具方法的类型注解完整性。
+帮助开发者确保工具方法有完整的类型注解，为自动 Schema 生成提供基础。
+
+使用方法:
+    # 检查所有工具
+    aiecs tools check-annotations
+
+    # 检查特定工具
+    aiecs tools check-annotations pandas
+
+    # 检查多个工具
+    aiecs tools check-annotations pandas chart image
+"""
+
+from aiecs.tools import discover_tools, TOOL_CLASSES
+import sys
+import inspect
+from typing import get_type_hints, Optional, List, Dict
+
+# 确保可以导入 aiecs
+import os
+
+sys.path.insert(
+    0,
+    os.path.dirname(os.path.dirname(os.path.dirname(os.path.dirname(__file__)))),
+)
+
+
+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"])
+    sum(1 for m in methods_info if m["has_annotations"] and not m["complete"])
+    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("\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()