Initial commit: jaspersoft-agent-learn teaching project

2026-05-29 23:22:18 +08:00
commit 05bb511aab
20 changed files with 4476 additions and 0 deletions
@@ -0,0 +1,223 @@
+"""
+Step 01 练习题：设计你的第一个 Tool
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+🎯 练习目标：
+    1. 巩固 Tool 的基本结构
+    2. 设计一个业务相关的 Tool
+    3. 理解 Tool 注册系统
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+"""
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 练习 1：完善 TextProcessorTool
+# ═══════════════════════════════════════════════════════════════════════════════
+
+"""
+任务：
+    完善 TextProcessorTool，这个工具用于处理文本。
+
+要求：
+    1. 实现 word_count 方法：统计单词数量
+    2. 实现 character_count 方法：统计字符数量（不包括空格）
+    3. 实现 sentence_count 方法：统计句子数量（按句号、问号、感叹号分割）
+
+提示：
+    - text 可能包含多行
+    - 句子分割要考虑常见的句子结束符：. ! ?
+    - 单词分割可以考虑按空格分割
+
+完成后测试：
+    text = "Hello, world! This is a test. How are you?"
+    预期结果：
+        - word_count: 9
+        - character_count: 38 (不包括空格)
+        - sentence_count: 3
+"""
+
+from step_01_tools.concept import BaseTool, ToolResult
+
+
+class TextProcessorTool(BaseTool):
+    """文本处理工具"""
+
+    @property
+    def name(self) -> str:
+        return "text_processor"
+
+    @property
+    def description(self) -> str:
+        return "文本处理工具，统计文本的各种特征"
+
+    def execute(self, **kwargs) -> ToolResult:
+        """处理文本请求"""
+        text = kwargs.get("text", "")
+        operation = kwargs.get("operation", "word_count")  # 默认操作
+
+        if not text:
+            return ToolResult(success=False, error="文本不能为空")
+
+        if operation == "word_count":
+            # TODO: 实现单词统计
+            result = self.word_count(text)
+        elif operation == "character_count":
+            # TODO: 实现字符统计
+            result = self.character_count(text)
+        elif operation == "sentence_count":
+            # TODO: 实现句子统计
+            result = self.sentence_count(text)
+        else:
+            return ToolResult(success=False, error=f"不支持的操作: {operation}")
+
+        return ToolResult(success=True, result=result)
+
+    def word_count(self, text: str) -> int:
+        """统计单词数量"""
+        # 提示：按空格分割，过滤空字符串
+        # 你的代码：
+        pass
+
+    def character_count(self, text: str) -> int:
+        """统计字符数量（不包括空格）"""
+        # 提示：去除所有空白字符后统计长度
+        # 你的代码：
+        pass
+
+    def sentence_count(self, text: str) -> int:
+        """统计句子数量"""
+        # 提示：按 . ! ? 分割
+        # 你的代码：
+        pass
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 练习 2：设计一个 EmailTool
+# ═══════════════════════════════════════════════════════════════════════════════
+
+"""
+任务：
+    设计一个 EmailTool，用于处理邮件相关操作。
+
+功能要求：
+    1. send_email: 发送邮件（收件人、主题、正文）
+    2. search_emails: 搜索邮件（关键词）
+    3. get_unread_count: 获取未读邮件数量
+
+设计提示：
+    - 工具名称要简洁明了
+    - 描述要告诉 LLM 这个工具能做什么
+    - execute 方法要处理不同的 operation
+
+这个练习的目的是让你学会：
+    - 如何设计多功能的 Tool
+    - 如何用 operation 参数区分不同功能
+    - 如何返回结构化的结果
+"""
+
+
+class EmailTool(BaseTool):
+    """邮件处理工具"""
+
+    # TODO: 实现属性和方法
+    pass
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 练习 3：改进工具注册表
+# ═══════════════════════════════════════════════════════════════════════════════
+
+"""
+任务：
+    给 ToolRegistry 添加一个新功能：根据描述关键词搜索工具
+
+方法签名：
+    def search_tools(self, keyword: str) -> list[dict]:
+        '''
+        根据关键词搜索工具
+
+        参数：
+            keyword: str - 搜索关键词
+
+        返回：
+            匹配的工具列表，格式同 list_tools()
+
+        匹配规则：
+            如果关键词出现在工具名称或描述中，就算匹配
+            匹配应该不区分大小写
+        '''
+
+预期行为：
+    registry = ToolRegistry()
+    registry.register(CalculatorTool())
+    registry.register(SearchTool())
+    registry.register(TextProcessorTool())  # 用你刚完成的
+
+    results = registry.search_tools("text")
+    # 应该返回 text_processor
+
+    results = registry.search_tools("calculate")
+    # 应该返回 calculator
+
+    results = registry.search_tools("web")
+    # 应该返回 web_search
+"""
+
+# 从 step_01_tools.concept 导入已有的类
+from step_01_tools.concept import ToolRegistry, CalculatorTool, SearchTool
+
+
+def add_search_to_registry():
+    """
+    在这里实现 search_tools 方法
+
+    提示：
+        1. 遍历所有已注册的工具
+        2. 检查 name 或 description 中是否包含 keyword
+        3. 收集匹配的工具
+        4. 返回列表
+
+    完成后，在 main.py 中测试
+    """
+    # 你的代码：
+
+    pass
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# 运行测试
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def test_exercises():
+    """测试所有练习"""
+    print("\n" + "=" * 60)
+    print("测试练习答案")
+    print("=" * 60)
+
+    # 测试练习 1
+    print("\n📝 练习 1: TextProcessorTool")
+    tool = TextProcessorTool()
+    test_text = "Hello, world! This is a test. How are you?"
+
+    print(f"测试文本: {test_text}")
+    print(f"单词数量: {tool.word_count(test_text)}")  # 应该是 9
+    print(f"字符数量: {tool.character_count(test_text)}")  # 应该是 38
+    print(f"句子数量: {tool.sentence_count(test_text)}")  # 应该是 3
+
+    # 测试练习 2
+    print("\n📝 练习 2: EmailTool")
+    # 运行看看你完成了多少
+
+    # 测试练习 3
+    print("\n📝 练习 3: search_tools")
+    registry = ToolRegistry()
+    registry.register(CalculatorTool())
+    registry.register(SearchTool())
+    registry.register(tool)
+
+    # 你的测试代码：
+
+
+if __name__ == "__main__":
+    test_exercises()