add README

Author: jayscoder

README.md

@@ -2,6 +2,10 @@
 
 Pydify 是一个用于与 Dify API 交互的 Python 客户端库。
 
+[![PyPI version](https://badge.fury.io/py/pydify.svg)](https://badge.fury.io/py/pydify)
+[![Python Versions](https://img.shields.io/pypi/pyversions/pydify.svg)](https://pypi.org/project/pydify)
+[![Downloads](https://pepy.tech/badge/pydify)](https://pepy.tech/project/pydify)
+
 ## 关于 Dify
 
 [Dify](https://github.com/langgenius/dify) 是一个开源的 LLM 应用开发平台，提供直观的界面将 AI 工作流、RAG 管道、代理能力、模型管理、可观察性功能等结合在一起，使您能够快速从原型转向生产环境。

examples/utils.py

@@ -344,7 +344,7 @@ def run_example(example_fn: Callable, *args, **kwargs):
             print(f"{example_fn.__doc__.strip()}\n")
 
         return example_fn(*args, **kwargs)
-    
+
     except Exception as e:
         print(f"\n示例运行过程中发生错误: {e}")
         import traceback

pydify/__init__.py

@@ -8,9 +8,10 @@
 from .agent import AgentClient
 from .chatbot import ChatbotClient
 from .chatflow import ChatflowClient
+from .common import DifyBaseClient, DifyType
 from .text_generation import TextGenerationClient
 from .workflow import WorkflowClient
-from .common import DifyType, DifyBaseClient
+
 
 def create_client(type: str, base_url: str, api_key: str) -> DifyBaseClient:
     if type == DifyType.Workflow:

pydify/agent.py

@@ -18,7 +18,8 @@ class AgentClient(DifyBaseClient):
 
     提供与Dify Agent应用API交互的方法，包括发送消息、获取历史消息、管理会话、
     上传文件、语音转文字、文字转语音等功能。Agent应用支持迭代式规划推理和自主工具调用。
-    """ 
+    """
+
     type = DifyType.Agent
 
     def send_message(
@@ -72,7 +73,7 @@ def send_message(
         endpoint = "chat-messages"
 
         return self.post_stream(endpoint, json_data=payload, **kwargs)  # 传递额外参数
-    
+
     def stop_response(self, task_id: str, user: str) -> Dict[str, Any]:
         """
         停止正在进行的响应流。此方法仅在流式模式下有效。
@@ -95,8 +96,6 @@ def stop_response(self, task_id: str, user: str) -> Dict[str, Any]:
         payload = {"user": user}
         return self.post(endpoint, json_data=payload)
 
-    
-
     def get_meta(self) -> Dict[str, Any]:
         """
         获取应用Meta信息，用于获取工具icon等。

pydify/chatbot.py

@@ -18,7 +18,9 @@ class ChatbotClient(DifyBaseClient):
     提供与Dify Chatbot应用API交互的方法，包括发送消息、获取历史消息、管理会话、
     上传文件、语音转文字、文字转语音等功能。
     """
+
     type = DifyType.Chatbot
+
     def send_message(
         self,
         query: str,
@@ -81,7 +83,7 @@ def send_message(
             return self.post_stream(endpoint, json_data=payload, **kwargs)
         else:
             return self.post(endpoint, json_data=payload, **kwargs)
-    
+
     def stop_response(self, task_id: str, user: str) -> Dict[str, Any]:
         """
         停止正在进行的响应，仅支持流式模式。

pydify/chatflow.py

@@ -19,7 +19,9 @@ class ChatflowClient(DifyBaseClient):
     提供与Dify Chatflow应用API交互的方法，包括发送消息、获取历史消息、管理会话、
     上传文件、语音转文字、文字转语音等功能。Chatflow应用基于工作流编排，适用于定义复杂流程的多轮对话场景。
     """
+
     type = DifyType.Chatflow
+
     def send_message(
         self,
         query: str,
@@ -97,7 +99,9 @@ def stop_response(self, task_id: str, user: str) -> Dict[str, Any]:
         payload = {"user": user}
         return self.post(endpoint, json_data=payload)
 
-    def get_suggested_questions(self, message_id: str, user: str, **kwargs) -> Dict[str, Any]:
+    def get_suggested_questions(
+        self, message_id: str, user: str, **kwargs
+    ) -> Dict[str, Any]:
         """
         获取下一轮建议问题列表。
 

pydify/common.py

@@ -26,35 +26,36 @@
 
 class DifyType:
     """Dify应用类型枚举
-    
+
     Dify平台支持多种类型的应用，每种类型有不同的API端点和功能。
     此类定义了所有支持的应用类型常量，用于客户端类型标识。
     """
-    Workflow = 'workflow'
-    Chatbot = 'chatbot'
-    Chatflow = 'chatflow'
-    Agent = 'agent'
-    TextGeneration = 'text_generation'
-    
+
+    Workflow = "workflow"
+    Chatbot = "chatbot"
+    Chatflow = "chatflow"
+    Agent = "agent"
+    TextGeneration = "text_generation"
+
 
 class DifyBaseClient:
     """Dify API 基础客户端类。
 
     提供与Dify API进行交互的基本功能，包括身份验证、HTTP请求和通用方法。
     各种特定应用类型的客户端都继承自此类，以重用共同的功能。
-    
+
     主要功能:
     - HTTP请求处理 (GET/POST/流式请求)
     - 错误处理和重试机制
     - 文件上传
     - 用户会话管理
     - 消息反馈功能
-    
+
     子类应设置适当的type属性，并根据需要实现特定的API方法。
     """
 
     type = None
-    
+
     def __init__(self, api_key: str, base_url: str = None):
         """
         初始化Dify API客户端。
@@ -65,13 +66,15 @@ def __init__(self, api_key: str, base_url: str = None):
             base_url (str, optional): API基础URL。如果未提供，则使用默认的Dify API地址。
                                     可以设置为自托管Dify实例的URL。
                                     也可以通过DIFY_BASE_URL环境变量设置。
-        
+
         注意:
             - API密钥应当保密，不要在客户端代码中硬编码
             - 对于自托管实例，确保base_url格式正确，通常以/v1结尾
         """
         self.api_key = api_key
-        self.base_url = base_url or os.environ.get("DIFY_BASE_URL") or "https://api.dify.ai/v1"
+        self.base_url = (
+            base_url or os.environ.get("DIFY_BASE_URL") or "https://api.dify.ai/v1"
+        )
 
         # 如果base_url不以斜杠结尾，则添加斜杠
         if not self.base_url.endswith("/"):
@@ -115,7 +118,7 @@ def _request(self, method: str, endpoint: str, **kwargs) -> requests.Response:
                 - status_code: HTTP状态码
                 - error_data: 服务器返回的错误数据
                 - 常见错误包括认证错误(401)、参数错误(400)、资源不存在(404)等
-            连接错误: 
+            连接错误:
                 - 网络连接问题
                 - SSL证书错误
                 - 超时
@@ -227,12 +230,12 @@ def get(self, endpoint: str, **kwargs) -> Dict[str, Any]:
 
         Raises:
             DifyAPIError: 当API请求失败时，包含详细的错误信息
-        
+
         示例:
             ```python
             # 获取应用信息
             app_info = client.get("app-info")
-            
+
             # 带参数的请求
             messages = client.get("messages", params={"conversation_id": "conv_123", "limit": 10})
             ```
@@ -272,7 +275,7 @@ def post(
 
         Raises:
             DifyAPIError: 当API请求失败时，包含详细的错误信息
-        
+
         示例:
             ```python
             # 发送消息
@@ -317,7 +320,7 @@ def post_stream(
         Raises:
             DifyAPIError: 当API请求失败时
             网络错误: 连接问题、超时等
-        
+
         示例:
             ```python
             # 流式生成文本
@@ -326,7 +329,7 @@ def post_stream(
                 "user": "user_123",
                 "response_mode": "streaming"
             })
-            
+
             # 处理每个事件块
             for chunk in stream:
                 if "answer" in chunk:

pydify/text_generation.py

@@ -18,8 +18,8 @@ class TextGenerationClient(DifyBaseClient):
     上传文件、文字转语音等功能。Text Generation应用无会话支持，
     适合用于翻译、文章写作、总结等AI任务。
     """
+
     type = DifyType.TextGeneration
-    
 
     def completion(
         self,

pydify/workflow.py

@@ -16,9 +16,9 @@ class WorkflowClient(DifyBaseClient):
 
     提供与Dify Workflow应用API交互的方法，包括执行工作流、停止响应、上传文件和获取日志等功能。
     """
-    
+
     type = DifyType.Workflow
-    
+
     def run(
         self,
         inputs: Dict[str, Any],
@@ -29,24 +29,24 @@ def run(
     ) -> Union[Dict[str, Any], Generator[Dict[str, Any], None, None]]:
         """
         执行工作流。
-        
+
         Args:
             inputs (Dict[str, Any]): 必需参数。包含工作流所需的输入变量键值对。
                                    每个键对应一个工作流定义中的变量名称，值为该变量的具体内容。
-                                   
+
                                    注意：根据API版本的不同，Dify API可能期望不同的参数格式：
                                    - 有些API版本要求使用 "inputs" 作为键
                                    - 有些API版本要求使用 "input" 作为键
                                    - 有些API版本期望直接提供扁平的输入结构
-                                   
+
                                    常见输入示例：
                                    ```
                                    # 简单文本输入
                                    inputs = {
                                        "prompt": "请给我写一首诗",
                                        "topic": "人工智能"
                                    }
-                                   
+
                                    # 包含更复杂结构的输入
                                    inputs = {
                                        "text_to_analyze": "这是一段需要分析的文本",
@@ -57,14 +57,14 @@ def run(
                                        }
                                    }
                                    ```
-                                   
+
             user (str): 用户标识，用于跟踪和区分不同用户的请求
-            
+
             response_mode (str, optional): 响应模式:
                 - 'streaming'（流式）: 实时获取工作流执行过程和结果，适合长时间运行的任务
                 - 'blocking'（阻塞）: 等待工作流完全执行完毕后返回结果，适合简短任务
                 默认为'streaming'。
-                
+
             files (List[Dict[str, Any]], optional): 文件列表，每个文件为一个字典，包含以下字段：
                 - type (str): 文件类型，支持:
                     - document: 支持'TXT', 'MD', 'MARKDOWN', 'PDF', 'HTML', 'XLSX', 'XLS',
@@ -78,7 +78,7 @@ def run(
                     - 'local_file': 使用之前通过upload_file上传的文件ID
                 - url (str): 文件的URL地址（仅当transfer_method为'remote_url'时需要）
                 - upload_file_id (str): 上传文件ID（仅当transfer_method为'local_file'时需要）
-                
+
                 示例:
                 ```
                 [
@@ -94,7 +94,7 @@ def run(
                     }
                 ]
                 ```
-                
+
             **kwargs: 额外的请求参数:
                 - timeout (int): 请求超时时间(秒)，默认为30秒
                 - max_retries (int): 网络错误时的最大重试次数，默认为2次
@@ -103,7 +103,7 @@ def run(
             Union[Dict[str, Any], Generator[Dict[str, Any], None, None]]:
                 如果response_mode为'blocking'，返回完整响应字典，包含工作流执行结果;
                 如果response_mode为'streaming'，返回一个字典生成器，实时提供工作流执行状态。
-                
+
                 阻塞模式返回示例:
                 ```
                 {
@@ -117,7 +117,7 @@ def run(
                     "ended_at": 1617979575
                 }
                 ```
-                
+
                 流式模式返回的每个事件示例:
                 ```
                 {