Initial commit: jaspersoft-agent-learn teaching project

step_01_tools/main.py

@@ -0,0 +1,169 @@
+"""
+Step 01: 工具系统基础 - 主程序
+
+运行方式：
+    cd step_01_tools
+    python main.py
+"""
+
+from concept import (
+    ToolRegistry,
+    CalculatorTool,
+    SearchTool,
+    JaspersoftCodeGeneratorTool
+)
+
+
+def main():
+    """演示工具系统的完整使用流程"""
+
+    print("=" * 70)
+    print(" Step 01: 理解 Tool - 工具系统基础")
+    print("=" * 70)
+    print()
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # 场景：构建一个 Jaspersoft 报表助手的工具集
+    # ═══════════════════════════════════════════════════════════════════════
+
+    print("📦 场景：构建 Jaspersoft 报表助手")
+    print("-" * 70)
+    print("""
+假设我们要构建一个 AI 助手，帮助用户：
+    1. 根据需求生成 JRXML 代码
+    2. 验证生成的代码是否正确
+    3. 计算报表的统计数据
+    4. 搜索相关的报表模板
+
+我们可以设计以下工具：
+    - jrxml_generator: 生成 JRXML 代码
+    - jrxml_validator: 验证 JRXML 语法
+    - calculator: 计算统计数据
+    - web_search: 搜索报表模板
+""")
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # 步骤 1：创建工具注册表
+    # ═══════════════════════════════════════════════════════════════════════
+
+    print("\n📋 步骤 1: 创建工具注册表")
+    print("-" * 40)
+
+    registry = ToolRegistry()
+    print("✓ 创建了空的工具注册表")
+    print(f"  当前注册工具数量: {len(registry.list_tools())}")
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # 步骤 2：注册工具
+    # ═══════════════════════════════════════════════════════════════════════
+
+    print("\n🔧 步骤 2: 注册工具")
+    print("-" * 40)
+
+    # 注册各种工具
+    registry.register(CalculatorTool())
+    print("✓ 注册计算器工具")
+
+    registry.register(SearchTool())
+    print("✓ 注册搜索工具")
+
+    registry.register(JaspersoftCodeGeneratorTool())
+    print("✓ 注册 JRXML 生成工具")
+
+    print(f"\n  当前注册工具数量: {len(registry.list_tools())}")
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # 步骤 3：查看可用工具
+    # ═══════════════════════════════════════════════════════════════════════
+
+    print("\n📜 步骤 3: 查看可用工具")
+    print("-" * 40)
+
+    for tool_info in registry.list_tools():
+        print(f"\n  [{tool_info['name']}]")
+        # 截取描述的前100个字符
+        desc = tool_info['description'].strip().replace('\n', ' ')[:100]
+        print(f"      {desc}...")
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # 步骤 4：执行工具
+    # ═══════════════════════════════════════════════════════════════════════
+
+    print("\n\n⚡ 步骤 4: 执行工具")
+    print("-" * 40)
+
+    # 场景：用户想要生成一个销售报表
+    user_requirement = "生成一个销售报表，显示月度汇总"
+
+    print(f"\n  用户需求: {user_requirement}")
+
+    # 4.1 先搜索相关的模板
+    print("\n  4.1 搜索相关模板...")
+    search_result = registry.execute("web_search", query="JasperReports 销售报表模板")
+    if search_result.success:
+        print(f"      找到 {len(search_result.result)} 个相关模板")
+        for i, item in enumerate(search_result.result[:2], 1):
+            print(f"        {i}. {item['title']}")
+
+    # 4.2 生成 JRXML
+    print("\n  4.2 生成 JRXML 代码...")
+    generate_result = registry.execute(
+        "jrxml_generator",
+        requirement=user_requirement,
+        context="参考销售报表模板"
+    )
+    if generate_result.success:
+        print(f"      ✓ 生成成功!")
+        print(f"      代码长度: {len(generate_result.result)} 字符")
+        print(f"      代码预览:")
+        print("      " + "-" * 30)
+        for line in generate_result.result.split('\n')[:5]:
+            print(f"      {line}")
+        print("      ...")
+
+    # 4.3 计算统计
+    print("\n  4.3 计算统计...")
+    calc_result = registry.execute("calculator", expression="10 + 20 + 30")
+    if calc_result.success:
+        print(f"      10 + 20 + 30 = {calc_result.result}")
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # 步骤 5：错误处理
+    # ═══════════════════════════════════════════════════════════════════════
+
+    print("\n\n⚠️  步骤 5: 错误处理演示")
+    print("-" * 40)
+
+    # 场景：用户尝试除以零
+    print("\n  尝试执行: calculator(expression='10 / 0')")
+    error_result = registry.execute("calculator", expression="10 / 0")
+    if not error_result.success:
+        print(f"      ✓ 错误被正确捕获: {error_result.error}")
+
+    # 尝试调用不存在的工具
+    print("\n  尝试执行: nonexistent_tool()")
+    error_result = registry.execute("nonexistent_tool")
+    if not error_result.success:
+        print(f"      ✓ 错误被正确捕获: {error_result.error}")
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # 总结
+    # ═══════════════════════════════════════════════════════════════════════
+
+    print("\n\n" + "=" * 70)
+    print(" ✅ Step 01 完成!")
+    print("=" * 70)
+    print("""
+学到的关键概念：
+    1. Tool = name + description + execute
+    2. BaseTool 是所有工具的基类
+    3. ToolRegistry 统一管理所有工具
+    4. ToolResult 统一返回结果格式
+
+下一步：
+    继续 Step 02，学习如何管理 Agent 的状态
+""")
+
+
+if __name__ == "__main__":
+    main()