MaiBot/src/plugin_system/apis/API使用指南.md

API使用指南

插件系统提供了多种API访问方式，根据使用场景选择合适的API类。

📊 API分类

🔗 ActionAPI - 需要Action依赖

适用场景：在Action组件中使用，需要访问聊天上下文

from src.plugin_system.apis import ActionAPI

class MyAction(BaseAction):
    async def execute(self):
        # Action已内置ActionAPI，可以直接使用
        await self.api.send_message("text", "Hello")
        await self.api.store_action_info(action_prompt_display="执行了动作")

包含功能：

• ✅ 发送消息（需要chat_stream、expressor等）
• ✅ 数据库操作（需要thinking_id、action_data等）

🔧 IndependentAPI - 独立功能

适用场景：在Command组件中使用，或需要独立工具功能

from src.plugin_system.apis import IndependentAPI

class MyCommand(BaseCommand):
    async def execute(self):
        # 创建独立API实例
        api = IndependentAPI(log_prefix="[MyCommand]")
        
        # 使用独立功能
        models = api.get_available_models()
        config = api.get_global_config("some_key")
        timestamp = api.get_timestamp()

包含功能：

• ✅ LLM模型调用
• ✅ 配置读取
• ✅ 工具函数（时间、文件、ID生成等）
• ✅ 聊天流查询
• ✅ 心流状态控制

⚡ StaticAPI - 静态访问

适用场景：简单工具调用，不需要实例化

from src.plugin_system.apis import StaticAPI

# 直接调用静态方法
models = StaticAPI.get_available_models()
config = StaticAPI.get_global_config("bot.nickname")
timestamp = StaticAPI.get_timestamp()
unique_id = StaticAPI.generate_unique_id()

# 异步方法
result = await StaticAPI.generate_with_model(prompt, model_config)
chat_stream = StaticAPI.get_chat_stream_by_group_id("123456")

🎯 使用建议

Action组件开发

class MyAction(BaseAction):
    # 激活条件直接在类中定义
    focus_activation_type = ActionActivationType.KEYWORD
    activation_keywords = ["测试"]
    
    async def execute(self):
        # 使用内置的ActionAPI
        success = await self.api.send_message("text", "处理中...")
        
        # 存储执行记录
        await self.api.store_action_info(
            action_prompt_display="执行了测试动作"
        )
        
        return True, "完成"

Command组件开发

class MyCommand(BaseCommand):
    # 命令模式直接在类中定义
    command_pattern = r"^/test\s+(?P<param>\w+)$"
    command_help = "测试命令"
    
    async def execute(self):
        # 使用独立API
        api = IndependentAPI(log_prefix="[TestCommand]")
        
        # 获取配置
        max_length = api.get_global_config("test.max_length", 100)
        
        # 生成内容（如果需要）
        if api.get_available_models():
            models = api.get_available_models()
            first_model = list(models.values())[0]
            
            success, response, _, _ = await api.generate_with_model(
                "生成测试回复", first_model
            )
            
            if success:
                await self.send_reply(response)

独立工具使用

# 不在插件环境中的独立使用
from src.plugin_system.apis import StaticAPI

def some_utility_function():
    # 获取配置
    bot_name = StaticAPI.get_global_config("bot.nickname", "Bot")
    
    # 生成ID
    request_id = StaticAPI.generate_unique_id()
    
    # 格式化时间
    current_time = StaticAPI.format_time()
    
    return f"{bot_name}_{request_id}_{current_time}"

🔄 迁移指南

从原PluginAPI迁移

原来的用法：

# 原来需要导入完整PluginAPI
from src.plugin_system.apis import PluginAPI

api = PluginAPI(chat_stream=..., expressor=...)
await api.send_message("text", "Hello")
config = api.get_global_config("key")

新的用法：

# 方式1：继续使用原PluginAPI（不变）
from src.plugin_system.apis import PluginAPI

# 方式2：使用分类API（推荐）
from src.plugin_system.apis import ActionAPI, IndependentAPI

# Action相关功能
action_api = ActionAPI(chat_stream=..., expressor=...)
await action_api.send_message("text", "Hello")

# 独立功能
config = IndependentAPI().get_global_config("key")
# 或者
config = StaticAPI.get_global_config("key")

📋 API对照表

功能类别	原PluginAPI	ActionAPI	IndependentAPI	StaticAPI
发送消息	✅	✅	❌	❌
数据库操作	✅	✅	❌	❌
LLM调用	✅	❌	✅	✅
配置读取	✅	❌	✅	✅
工具函数	✅	❌	✅	✅
聊天流查询	✅	❌	✅	✅
心流控制	✅	❌	✅	✅

这样的分类让插件开发者可以更明确地知道需要什么样的API，避免不必要的依赖注入。