Merge pull request #4 from lihq1403/refactor

refactor: Comprehensive codebase overhaul with improved architecture and enhanced functionality

Author: huangzhhui

.cursor/rules/odin.mdc

@@ -0,0 +1,148 @@
+---
+description: 项目规范
+globs: 
+alwaysApply: false
+---
+# Odin 项目规范
+
+## 项目概述
+
+Odin 是一个基于 PHP 的 LLM 应用开发框架，其命名灵感来自于北欧神话中的主神 Odin（奥丁）和他的两只乌鸦 Huginn 和 Muninn，Huginn 和 Muninn 分别代表的 **思想** 和 **记忆**，它们两个每天早上一破晓就飞到人间，到了晚上再将所见所闻带回给 Odin。
+
+此项目旨在帮助开发人员利用 LLM 技术创建更加智能和灵活的应用程序，通过提供一系列强大而易用的功能，为 LLM 技术落地提供了更多的可能性。项目提供一系列便捷的工具和API，简化与各种LLM提供商（如OpenAI、Azure OpenAI等）的集成过程。
+
+### 核心特性
+
+- 统一的API接口设计，支持多种LLM提供商
+- 强大的工具调用功能，支持函数调用和参数验证
+- 流式响应处理，支持实时交互
+- 灵活的请求和响应处理机制
+- 完善的错误处理和异常管理
+
+## 编码标准
+
+### 基本要求
+
+- 语言版本：PHP 8.0+
+- 框架：Hyperf
+- 代码规范：PSR-12 + Hyperf规范
+- 文档要求：复杂逻辑必须有PHPDoc注释
+
+### 代码风格
+
+- 缩进：4空格
+- 行长度：120字符
+- 命名规范：
+  - 类名：PascalCase
+  - 方法名：camelCase
+  - 属性：camelCase
+  - 常量：UPPER_SNAKE_CASE
+  - 变量：camelCase
+- 类型提示：所有方法参数和返回值必须使用类型声明
+- 注释：使用中文注释，保持简洁明了
+
+### 文件组织
+
+- 源码结构：遵循PSR-4自动加载规范
+- 命名空间：Hyperf\Odin
+
+### 静态分析
+
+### 静态分析
+
+- 工具：PHPStan
+- 级别：Level 5
+- 覆盖范围：所有源代码(src)和测试代码(tests)必须通过 phpstan level 5 检查
+- 执行命令：vendor/bin/phpstan analyse src tests --level=5
+- 类型声明：所有类型必须明确定义，避免使用混合类型(mixed)，除非绝对必要
+
+### 最佳实践
+
+- 使用依赖注入而非直接实例化
+- 遵循单一职责原则，每个类只负责一个功能
+- 优先使用组合而非继承
+- 使用接口定义行为，提高代码灵活性
+- 使用强类型，避免隐式类型转换
+- 异常必须被妥善处理或向上抛出
+- 避免使用魔术方法和魔术常量
+
+## 测试标准
+
+### 基本要求
+
+- 测试框架：PHPUnit
+- 覆盖率要求：关键业务逻辑覆盖率目标 >= 80%
+- 静态分析：所有测试必须通过 phpstan level 5
+
+### 单元测试规范
+
+- 命名规则：test{测试功能}方法名
+- 结构要求：每个源代码类应有对应的测试类
+- 隔离性：测试应该相互独立，不依赖执行顺序
+- 断言要求：每个测试应包含至少一个断言
+- Mock框架：使用Mockery框架模拟外部依赖
+
+### 测试数据管理
+
+- 数据创建：使用工厂方法或数据提供者创建测试数据
+- 数据分离：测试数据应与测试逻辑分离
+
+### 测试代码组织
+
+- 目录结构：tests/Cases/{对应源码路径}
+- 命名空间：HyperfTest\Odin
+
+### 测试最佳实践
+
+- 每个测试方法只测试一个功能点
+- 使用数据提供者测试边界条件
+- 为复杂测试提供详细注释说明测试目的
+- 测试失败抛出的异常类型和消息
+- 使用setUp和tearDown方法处理重复的测试准备和清理工作
+- 为模拟对象提供准确的类型注释
+
+## Git 工作流
+
+### 分支管理
+
+- main：稳定发布分支
+- develop：开发集成分支
+- refactor：重构分支（重构完成后将合并到 main）
+- feature：feature/{功能名称}
+- bugfix：bugfix/{问题简述}
+- release：release/v{版本号}
+
+### 提交规范
+
+提交信息格式：{类型}: {简短描述}
+
+类型包括：
+- feat：新功能
+- fix：修复
+- docs：文档
+- style：格式
+- refactor：重构
+- test：测试
+- chore：其他
+
+### 代码审查
+
+必须进行代码审查，检查清单：
+- 代码符合项目规范
+- 新功能有对应单元测试
+- 通过所有CI检查
+- 无重复代码
+- 良好的性能表现
+
+## Cursor 编辑器设置
+
+### AI 建议
+
+- 启用 AI 建议
+- 重点关注代码质量和测试覆盖
+
+### 编辑器配置
+
+- Tab 大小：4
+- 自动换行：关闭
+- 保存时格式化：开启

.gitignore

@@ -11,4 +11,10 @@ output/
 .env
 .DS_Store
 *.lock
-.phpunit*
+.phpunit*
+todo/
+.vscode/
+bin/
+publish/
+config/
+.obsidian/

.php-cs-fixer.php

@@ -1,5 +1,17 @@
 <?php
 
+declare(strict_types=1);
+/**
+ * This file is part of Hyperf.
+ *
+ * @link     https://www.hyperf.io
+ * @document https://hyperf.wiki
+ * @contact  group@hyperf.io
+ * @license  https://github.com/hyperf/hyperf/blob/master/LICENSE
+ */
+use PhpCsFixer\Config;
+use PhpCsFixer\Finder;
+
 $header = <<<'EOF'
 This file is part of Hyperf.
 
@@ -9,7 +21,7 @@
 @license  https://github.com/hyperf/hyperf/blob/master/LICENSE
 EOF;
 
-return (new PhpCsFixer\Config())
+return (new Config())
     ->setRiskyAllowed(true)
     ->setRules([
         '@PSR2' => true,
@@ -23,13 +35,13 @@
             'location' => 'after_declare_strict',
         ],
         'array_syntax' => [
-            'syntax' => 'short'
+            'syntax' => 'short',
         ],
         'list_syntax' => [
-            'syntax' => 'short'
+            'syntax' => 'short',
         ],
         'concat_space' => [
-            'spacing' => 'one'
+            'spacing' => 'one',
         ],
         'blank_line_before_statement' => [
             'statements' => [
@@ -38,7 +50,7 @@
         ],
         'general_phpdoc_annotation_remove' => [
             'annotations' => [
-                'author'
+                'author',
             ],
         ],
         'ordered_imports' => [
@@ -88,7 +100,7 @@
         'multiline_comment_opening_closing' => true,
     ])
     ->setFinder(
-        PhpCsFixer\Finder::create()
+        Finder::create()
             ->exclude('vendor')
             ->in(__DIR__)
     )

.vscode/settings.json

@@ -5,12 +5,67 @@
 Odin 是一个基于 PHP 的 LLM 应用开发框架，其命名灵感来自于北欧神话中的主神 Odin（奥丁）和他的两只乌鸦 Huginn 和 Muninn，Huginn 和 Muninn 分别代表的 **思想** 和 **记忆**，它们两个每天早上一破晓就飞到人间，到了晚上再将所见所闻带回给 Odin。    
 此项目旨在帮助开发人员利用 LLM 技术创建更加智能和灵活的应用程序，通过提供一系列强大而易用的功能，为 LLM 技术落地提供了更多的可能性。
 
-# 安装
+## 核心特性
+
+- **多模型支持**：支持 OpenAI、Azure OpenAI、AWS Bedrock、Doubao、ChatGLM 等多种大语言模型
+- **统一接口**：提供一致的 API 接口，简化与不同 LLM 提供商的集成
+- **工具调用**：支持 Function Calling，允许模型调用自定义工具和函数
+- **记忆管理**：提供灵活的记忆管理系统，支持会话上下文保持
+- **向量存储**：集成 Qdrant 向量数据库，支持知识检索和语义搜索
+- **Agent 开发**：内置 Agent 框架，支持智能代理开发
+- **高性能**：优化的实现，支持流式响应和高效处理
+
+## 系统要求
+
+- PHP >= 8.0
+- PHP 扩展：bcmath、curl、mbstring
+- Composer >= 2.0
+- Hyperf 框架 (2.2.x, 3.0.x 或 3.1.x)
+
+## 安装
 
 ```bash
 composer require hyperf/odin
 ```
 
-# License
+## 快速开始
+
+1. 安装完成后，发布配置文件：
+
+```bash
+php bin/hyperf.php vendor:publish hyperf/odin
+```
+
+2. 在 `.env` 文件中配置你的 API 密钥：
+
+```
+OPENAI_API_KEY=your_openai_api_key
+```
+
+3. 在 `config/autoload/odin.php` 中设置默认模型：
+
+```php
+return [
+    'llm' => [
+        'default' => 'gpt-4o', // 设置你的默认模型
+        // ... 其他配置
+    ],
+];
+```
+
+## 文档
+
+详细的文档可在 `doc/user-guide` 目录中找到，包括：
+- 安装和配置
+- 核心概念
+- API 参考
+- 模型提供商
+- 工具开发
+- 记忆管理
+- Agent 开发
+- 示例项目
+- 常见问题解答
+
+## License
 
 Odin is open-sourced software licensed under the [MIT license](https://github.com/hyperf/odin/blob/master/LICENSE).