ErisPulse 2.1.0__tar.gz → 2.1.2__tar.gz

erispulse-2.1.2/.github/tools/merge_md.py

@@ -0,0 +1,141 @@
+import os
+
+def merge_md_files(output_file, files_to_merge, title="文档合集"):
+    """
+    合并多个Markdown文件
+    
+    :param output_file: 输出文件路径
+    :param files_to_merge: 要合并的文件列表，包含文件路径和描述
+    :param title: 文档标题
+    """
+    with open(output_file, 'w', encoding='utf-8') as outfile:
+        # 写入头部说明
+        outfile.write(f"# ErisPulse {title}\n\n")
+        outfile.write("本文件由多个开发文档合并而成，用于辅助 AI 理解 ErisPulse 的相关功能。\n\n")
+
+        outfile.write("## 各文件对应内容说明\n\n")
+        outfile.write("| 文件名 | 作用 |\n")
+        outfile.write("|--------|------|\n")
+        
+        # 写入文件说明
+        for file_info in files_to_merge:
+            outfile.write(f"| {os.path.basename(file_info['path'])} | {file_info.get('description', '')} |\n")
+        
+        outfile.write("\n## 合并内容开始\n\n")
+
+        # 合并文件内容
+        for file_info in files_to_merge:
+            file_path = file_info['path']
+            if os.path.exists(file_path):
+                filename = os.path.basename(file_path)
+                with open(file_path, 'r', encoding='utf-8') as infile:
+                    content = infile.read()
+                    outfile.write(f"<!-- {filename} -->\n\n")
+                    outfile.write(content)
+                    outfile.write(f"\n\n<!--- End of {filename} -->\n\n")
+            else:
+                print(f"⚠️ 文件不存在，跳过: {file_path}")
+
+def merge_api_docs(api_dir, output_file):
+    """
+    合并API文档
+    
+    :param api_dir: API文档目录
+    :param output_file: 输出文件路径
+    """
+    with open(output_file, 'a', encoding='utf-8') as outfile:
+        outfile.write("<!-- API文档 -->\n\n")
+        outfile.write("# API参考\n\n")
+
+        # 递归遍历API目录
+        for root, _, files in os.walk(api_dir):
+            for file in files:
+                if file.endswith('.md'):
+                    file_path = os.path.join(root, file)
+                    rel_path = os.path.relpath(file_path, api_dir)
+                    
+                    with open(file_path, 'r', encoding='utf-8') as infile:
+                        content = infile.read()
+                        outfile.write(f"## {rel_path}\n\n")
+                        outfile.write(content)
+                        outfile.write("\n\n")
+        
+        outfile.write("<!--- End of API文档 -->\n")
+
+def generate_full_document():
+    """生成完整文档"""
+    print("⏳ 正在生成完整文档...")
+    
+    # 定义要合并的文件
+    files_to_merge = [
+        {"path": "docs/quick-start.md", "description": "快速开始指南"},
+        {"path": "docs/UseCore.md", "description": "核心功能使用说明"},
+        {"path": "docs/PlatformFeatures.md", "description": "平台功能说明"},
+        {"path": "docs/Development/Module.md", "description": "模块开发指南"},
+        {"path": "docs/Development/Adapter.md", "description": "适配器开发指南"},
+        {"path": "docs/AdapterStandards/APIResponse.md", "description": "API响应标准"},
+        {"path": "docs/AdapterStandards/EventConversion.md", "description": "事件转换标准"},
+    ]
+    
+    output_file = "docs/AIDocs/ErisPulse-Full.md"
+    os.makedirs(os.path.dirname(output_file), exist_ok=True)
+    
+    merge_md_files(output_file, files_to_merge, "完整开发文档")
+    merge_api_docs("docs/api", output_file)
+    
+    print(f"🎉 完整文档生成完成，已保存到: {output_file}")
+
+def generate_core_document():
+    """生成核心功能文档"""
+    print("⏳ 正在生成核心功能文档...")
+    
+    files_to_merge = [
+        {"path": "docs/quick-start.md", "description": "快速开始指南"},
+        {"path": "docs/UseCore.md", "description": "核心功能使用说明"},
+        {"path": "docs/PlatformFeatures.md", "description": "平台功能说明"},
+    ]
+    
+    output_file = "docs/AIDocs/ErisPulse-Core.md"
+    os.makedirs(os.path.dirname(output_file), exist_ok=True)
+    
+    merge_md_files(output_file, files_to_merge, "核心功能文档")
+    merge_api_docs("docs/api/ErisPulse/Core", output_file)
+    
+    print(f"🎉 核心功能文档生成完成，已保存到: {output_file}")
+
+def generate_dev_documents():
+    """生成开发文档（模块和适配器）"""
+    print("⏳ 正在生成开发文档...")
+    
+    # 模块开发文档
+    module_files = [
+        {"path": "docs/UseCore.md", "description": "核心功能使用说明"},
+        {"path": "docs/PlatformFeatures.md", "description": "平台支持的发送类型及差异性说明"},
+        {"path": "docs/Development/Module.md", "description": "模块开发指南"}
+    ]
+    
+    module_output = "docs/AIDocs/ErisPulse-ModuleDev.md"
+    merge_md_files(module_output, module_files, "模块开发文档")
+    merge_api_docs("docs/api/", module_output)
+    print(f"🎉 模块开发文档生成完成，已保存到: {module_output}")
+    
+    # 适配器开发文档
+    adapter_files = [
+        {"path": "docs/UseCore.md", "description": "核心功能使用说明"},
+        {"path": "docs/Development/Adapter.md", "description": "适配器开发指南"},
+        {"path": "docs/AdapterStandards/APIResponse.md", "description": "API响应标准"},
+        {"path": "docs/AdapterStandards/EventConversion.md", "description": "事件转换标准"},
+    ]
+    
+    adapter_output = "docs/AIDocs/ErisPulse-AdapterDev.md"
+    merge_md_files(adapter_output, adapter_files, "适配器开发文档")
+    merge_api_docs("docs/api", adapter_output)
+    print(f"🎉 适配器开发文档生成完成，已保存到: {adapter_output}")
+
+if __name__ == "__main__":
+    # 生成所有文档
+    generate_full_document()
+    generate_core_document()
+    generate_dev_documents()
+    
+    print("✅ 所有文档生成完成")

{erispulse-2.1.0 → erispulse-2.1.2}/.github/tools/update-api-docs.py

@@ -3,6 +3,7 @@ import ast
 import re
 import argparse
 from typing import List, Dict, Tuple, Optional, Set
+from datetime import datetime
 
 def process_docstring(docstring: str) -> Optional[str]:
     """
@@ -15,30 +16,69 @@ def process_docstring(docstring: str) -> Optional[str]:
         return None
     
     # 检查忽略标签
-    if "{!--< internal-use >!--}" in docstring or "{!--< ignore >!--}" in docstring:
+    if "{!--< ignore >!--}" in docstring:
         return None
     
+    # 替换 {!--< internal-use >!--} 
+    docstring = re.sub(
+        r"{!--< internal-use >!--}(.*)",
+        lambda m: f"⚠️ **内部方法**：{m.group(1).strip()}\n\n",
+        docstring
+    )
+
     # 替换过时标签
-    docstring = docstring.replace("{!--< deprecated >!--}", "**过时**：")
+    docstring = re.sub(
+        r"\{!--< deprecated >!--\}(.*)",
+        lambda m: f"⚠️ **已弃用**：{m.group(1).strip()}\n\n",
+        docstring
+    )
     
     # 替换实验性标签
-    docstring = docstring.replace("{!--< experimental >!--}", "**实验性**：")
+    docstring = re.sub(
+        r"\{!--< experimental >!--\}(.*)",
+        lambda m: f"🔬 **实验性功能**：{m.group(1).strip()}\n\n",
+        docstring
+    )
     
-    # 处理提示标签（单行）
+    # 处理提示标签（多行）
     docstring = re.sub(
         r"\{!--< tips >!--\}(.*?)\{!--< /tips >!--\}",
-        lambda m: f"> **提示**：{m.group(1)}\n\n",
+        lambda m: f"💡 **提示**：\n\n{m.group(1).strip()}\n\n",
         docstring,
         flags=re.DOTALL
     )
     
-    # 处理单行提示标签（没有结束标签）
+    # 处理单行提示标签
     docstring = re.sub(
         r"\{!--< tips >!--\}([^\n]*)",
-        lambda m: f"> **提示**：{m.group(1)}\n\n",
+        lambda m: f"💡 **提示**：{m.group(1).strip()}\n\n",
+        docstring
+    )
+    
+    # 参数说明
+    docstring = re.sub(
+        r":param (\w+):\s*\[([^\]]+)\]\s*(.*)",
+        lambda m: f"- `{m.group(1)}` ({m.group(2)}): {m.group(3).strip()}",
         docstring
     )
     
+    # 返回值说明
+    docstring = re.sub(
+        r":return:\s*\[([^\]]+)\]\s*(.*)",
+        lambda m: f"**返回**: \n\n- 类型: `{m.group(1)}`\n- 描述: {m.group(2).strip()}",
+        docstring
+    )
+    
+    # 异常说明
+    docstring = re.sub(
+        r":raises (\w+):\s*(.*)",
+        lambda m: f"⚠️ **可能抛出**: `{m.group(1)}` - {m.group(2).strip()}",
+        docstring
+    )
+    
+    # 统一换行符为两个换行
+    docstring = re.sub(r"\n{2,}", "\n\n", docstring.strip())
+    
     return docstring.strip()
 
 def parse_python_file(file_path: str) -> Tuple[Optional[str], List[Dict], List[Dict]]:
@@ -84,7 +124,8 @@ def parse_python_file(file_path: str) -> Tuple[Optional[str], List[Dict], List[D
                     if processed_method_doc:
                         methods.append({
                             "name": item.name,
-                            "doc": processed_method_doc
+                            "doc": processed_method_doc,
+                            "is_async": isinstance(item, ast.AsyncFunctionDef)
                         })
             
             classes.append({
@@ -101,7 +142,8 @@ def parse_python_file(file_path: str) -> Tuple[Optional[str], List[Dict], List[D
             if processed_func_doc:
                 functions.append({
                     "name": node.name,
-                    "doc": processed_func_doc
+                    "doc": processed_func_doc,
+                    "is_async": isinstance(node, ast.AsyncFunctionDef)
                 })
     
     return processed_module_doc, classes, functions
@@ -109,7 +151,7 @@ def parse_python_file(file_path: str) -> Tuple[Optional[str], List[Dict], List[D
 def generate_markdown(module_path: str, module_doc: Optional[str], 
                      classes: List[Dict], functions: List[Dict]) -> str:
     """
-    生成Markdown格式的API文档
+    生成Markdown格式API文档
     
     :param module_path: 模块路径（点分隔）
     :param module_doc: 模块文档
@@ -119,33 +161,54 @@ def generate_markdown(module_path: str, module_doc: Optional[str],
     """
     content = []
     
-    # 模块标题
-    content.append(f"# `{module_path}` 模块\n")
+    # 文档头部
+    content.append(f"""# 📦 `{module_path}` 模块
+
+*自动生成于 {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}*
+
+---
+""")
     
     # 模块文档
     if module_doc:
-        content.append(f"{module_doc}\n")
+        content.append(f"## 模块概述\n\n{module_doc}\n\n---\n")
     
     # 函数部分
     if functions:
-        content.append("## 函数\n")
+        content.append("## 🛠️ 函数\n")
         for func in functions:
-            content.append(f"### `{func['name']}`\n")
-            content.append(f"{func['doc']}\n\n")
+            async_marker = "🔹 `async` " if func["is_async"] else ""
+            content.append(f"""### {async_marker}`{func['name']}`
+
+{func['doc']}
+
+---
+""")
     
     # 类部分
     if classes:
-        content.append("## 类\n")
+        content.append("## 🏛️ 类\n")
         for cls in classes:
-            content.append(f"### `{cls['name']}`\n")
-            content.append(f"{cls['doc']}\n\n")
+            content.append(f"""### `{cls['name']}`
+
+{cls['doc']}
+
+""")
             
             # 类方法
             if cls["methods"]:
-                content.append("#### 方法\n")
+                content.append("#### 🧰 方法\n")
                 for method in cls["methods"]:
-                    content.append(f"##### `{method['name']}`\n")
-                    content.append(f"{method['doc']}\n\n")
+                    async_marker = "🔹 `async` " if method["is_async"] else ""
+                    content.append(f"""##### {async_marker}`{method['name']}`
+
+{method['doc']}
+
+---
+""")
+    
+    # 文档尾部
+    content.append(f"\n*文档最后更新于 {datetime.now().strftime('%Y-%m-%d %H:%M:%S')}*")
     
     return "\n".join(content)
 
@@ -167,20 +230,21 @@ def generate_api_docs(src_dir: str, output_dir: str):
                 
                 # 计算模块路径
                 rel_path = os.path.relpath(file_path, src_dir)
-                module_path = rel_path.replace(".py", "").replace(os.sep, "/")
+                module_path = rel_path.replace(".py", "").replace(os.sep, ".")
                 
                 # 解析Python文件
                 module_doc, classes, functions = parse_python_file(file_path)
                 
                 # 跳过没有文档的文件
                 if not module_doc and not classes and not functions:
+                    print(f"⏭️ 跳过无文档文件: {file_path}")
                     continue
                 
                 # 生成Markdown内容
                 md_content = generate_markdown(module_path, module_doc, classes, functions)
                 
                 # 写入文件
-                output_path = os.path.join(output_dir, f"{module_path}.md")
+                output_path = os.path.join(output_dir, f"{module_path.replace('.', '/')}.md")
                 os.makedirs(os.path.dirname(output_path), exist_ok=True)
                 
                 with open(output_path, "w", encoding="utf-8") as f:
@@ -192,13 +256,21 @@ if __name__ == "__main__":
     parser = argparse.ArgumentParser(description="API文档生成器")
     parser.add_argument("--src", default="src", help="源代码目录 (默认: src)")
     parser.add_argument("--output", default="docs/api", help="输出目录 (默认: docs/api)")
+    parser.add_argument("--version", action="version", version="API文档生成器 2.0")
     
     args = parser.parse_args()
     
-    print(f"📁 源代码目录: {args.src}")
-    print(f"📂 输出目录: {args.output}")
-    print("⏳ 正在生成API文档...")
+    print(f"""📁 源代码目录: {args.src}
+📂 输出目录: {args.output}
+⏳ 正在生成API文档...""")
     
     generate_api_docs(args.src, args.output)
     
-    print("🎉 API文档生成完成！")
+    print("""🎉 API文档生成完成！
+
+生成文档包含以下改进:
+✨ 更美观的排版和格式
+📅 自动添加生成时间戳
+🔖 使用emoji图标提高可读性
+📝 优化了参数和返回值的显示方式
+""")

{erispulse-2.1.0 → erispulse-2.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ErisPulse
-Version: 2.1.0
+Version: 2.1.2
 Summary: ErisPulse 是一个模块化、可扩展的异步 Python SDK 框架，主要用于构建高效、可维护的机器人应用程序。
 Author-email: "艾莉丝·格雷拉特(WSu2059)" <wsu2059@qq.com>, runoneall <runoobsteve@gmail.com>
 License: MIT License

erispulse-2.1.2/docs/AI-Module-Generation.md

@@ -0,0 +1,43 @@
+# AI 模块生成指南
+
+使用本指南，你可以通过AI快速生成符合ErisPulse规范的模块代码，无需从零开始编写。
+
+## 快速开始
+
+1. **获取开发文档**  
+   下载 `docs/ForAIDocs/ErisPulseDevelop.md` - 它包含了所有AI需要的开发规范、适配器接口和SDK参考。
+
+2. **明确你的需求**  
+   确定模块功能、使用的适配器、依赖关系等核心要素。
+
+3. **向AI描述需求**  
+   使用下面的标准格式清晰地描述你的模块需求。
+
+## 需求描述规范
+
+请按照以下格式描述你的模块需求：
+
+```
+我需要一个天气查询模块 WeatherBot，当用户在群聊中发送“/weather 上海”时，机器人会调用 OpenWeatherMap API 查询天气，并返回中文格式的天气信息。  
+
+请根据 ErisPulse 的模块规范和文档，为我生成完整的模块文件结构和代码
+```
+
+并且将刚刚下载的 `ErisPulseDevelop.md` 作为附件发送给 AI。
+
+## 常见问题
+
+Q: 推荐如何生成模块？  
+A: 使用你的 `IDE` 寻找一个AICoder，确保这个AICoder可以直接操作文件（当然，这只是推荐做法，你也可以直接按照AI给出的结构手动创建项目）。并且确保您的模型有足够的能力。
+
+Q: 如何测试生成的模块？   
+A: 使用 pypi 包的形式安装到python环境，确保AI为你生成了包括 `pyproject.toml` 在内的python包配置文件和相应的代码。然后使用 `pip install -e .` 安装到python环境。
+
+Q: 生成的代码不符合我的需求怎么办？   
+A: 可以调整需求描述后重新生成，或直接在生成代码基础上进行修改。
+
+Q: 需要更复杂的功能怎么办？   
+A: 可以将复杂功能拆分为多个简单模块，或分阶段实现。
+
+Q: 我可以把这个模块发布到ErisPulse吗？ 
+A: 当然可以！但是我们会审查你的代码，确保它符合我们的规范。