feat: 添加 API 模块的兼容层文档，提供旧版接口的说明和迁移指南

src-new/astrbot_sdk/api/__init__.py

@@ -1 +1,12 @@
+"""AstrBot SDK 公共 API 模块。
+
+此模块提供插件开发所需的公共接口，包括：
+- components: 命令组件基类
+- event: 事件处理相关工具（过滤器、事件类）
+- star: 插件上下文
+
+注意：大部分 API 是为了兼容旧版插件而保留的兼容层。
+新版 API 请参考 astrbot_sdk.context.Context 和 astrbot_sdk.decorators 模块。
+"""
+
 __all__: list[str] = []

src-new/astrbot_sdk/api/components/__init__.py

@@ -1,3 +1,11 @@
+"""命令组件模块。
+
+提供 CommandComponent 基类，用于定义命令处理器。
+CommandComponent 是旧版 Star 基类的别名，用于向后兼容。
+
+新版插件建议直接使用 astrbot_sdk.star.Star 和装饰器模式。
+"""
+
 from .command import CommandComponent
 
 __all__ = ["CommandComponent"]

src-new/astrbot_sdk/api/components/command.py

@@ -1,3 +1,27 @@
+"""命令组件兼容层。
+
+此模块提供旧版 CommandComponent 的向后兼容导入。
+CommandComponent 是插件命令处理器的基类。
+
+迁移说明：
+- 旧版: 继承 CommandComponent，实现 command() 方法
+- 新版: 继承 astrbot_sdk.star.Star，使用 @on_command 装饰器
+
+示例:
+    # 旧版写法
+    class MyCommand(CommandComponent):
+        async def command(self, ctx: Context):
+            ...
+
+    # 新版写法
+    from astrbot_sdk import Star, on_command
+
+    class MyPlugin(Star):
+        @on_command("hello")
+        async def handle_hello(self, ctx: Context):
+            ...
+"""
+
 from ..._legacy_api import CommandComponent
 
 __all__ = ["CommandComponent"]

src-new/astrbot_sdk/api/event/__init__.py

@@ -1,3 +1,14 @@
+"""事件处理 API 模块。
+
+提供事件相关的公共接口：
+- AstrMessageEvent: 消息事件类，包含消息文本、用户信息、平台信息等
+- filter: 事件过滤器命名空间，提供命令、正则、权限等装饰器
+- ADMIN: 管理员权限常量
+
+此模块是旧版 astrbot_sdk.api.event 的兼容层。
+新版 API 建议直接使用 astrbot_sdk.events.MessageEvent 和 astrbot_sdk.decorators。
+"""
+
 from ...events import MessageEvent as AstrMessageEvent
 from .filter import ADMIN, filter
 

src-new/astrbot_sdk/api/event/filter.py

@@ -1,19 +1,80 @@
+"""事件过滤器模块。
+
+提供事件处理器的注册装饰器，用于声明式地定义事件触发条件。
+此模块是旧版 filter API 的兼容层。
+
+使用方式：
+    # 方式一：直接使用函数
+    @command("hello")
+    async def handle_hello(ctx):
+        ...
+
+    # 方式二：使用 filter 命名空间（旧版风格）
+    @filter.command("hello")
+    async def handle_hello(ctx):
+        ...
+
+新版建议直接使用 astrbot_sdk.decorators 模块中的装饰器。
+"""
+
 from __future__ import annotations
 
 from ...decorators import on_command, on_message, require_admin
 
+# 管理员权限级别常量
 ADMIN = "admin"
 
 
 def command(name: str):
+    """注册命令处理器装饰器。
+
+    Args:
+        name: 命令名称，用户发送以此开头的消息时触发
+
+    Returns:
+        装饰器函数
+
+    示例:
+        @command("hello")
+        async def handle_hello(ctx):
+            await ctx.reply("Hello!")
+    """
     return on_command(name)
 
 
 def regex(pattern: str):
+    """注册正则匹配处理器装饰器。
+
+    Args:
+        pattern: 正则表达式模式，匹配的消息将触发处理器
+
+    Returns:
+        装饰器函数
+
+    示例:
+        @regex(r"hello\\s+(\\w+)")
+        async def handle_hello(ctx, match):
+            name = match.group(1)
+            await ctx.reply(f"Hello, {name}!")
+    """
     return on_message(regex=pattern)
 
 
 def permission(level):
+    """权限检查装饰器。
+
+    Args:
+        level: 权限级别，目前仅支持 ADMIN
+
+    Returns:
+        装饰器函数，仅当用户具有指定权限时才执行处理器
+
+    示例:
+        @command("admin_cmd")
+        @permission(ADMIN)
+        async def admin_only(ctx):
+            await ctx.reply("管理员命令已执行")
+    """
     if level == ADMIN:
         return require_admin
 
@@ -24,11 +85,23 @@ def permission(level):
 
 
 class _FilterNamespace:
+    """过滤器命名空间，提供旧版风格的方法调用。
+
+    用于支持 filter.command()、filter.regex() 等调用方式，
+    保持与旧版 API 的兼容性。
+
+    示例:
+        @filter.command("hello")
+        async def handle_hello(ctx):
+            ...
+    """
+
     command = staticmethod(command)
     regex = staticmethod(regex)
     permission = staticmethod(permission)
 
 
+# 过滤器命名空间实例，支持 filter.command() 等调用方式
 filter = _FilterNamespace()
 
 __all__ = ["ADMIN", "command", "regex", "permission", "filter"]

src-new/astrbot_sdk/api/star/__init__.py

@@ -1,3 +1,17 @@
+"""插件上下文 API 模块。
+
+提供插件运行时上下文 Context 类，用于：
+- 调用 LLM 生成文本
+- 发送消息
+- 管理会话
+- 存储键值数据
+
+此模块是旧版 astrbot_sdk.api.star 的兼容层。
+Context 实际上是 LegacyContext 的别名，用于向后兼容旧版插件。
+
+新版插件建议使用 astrbot_sdk.context.Context。
+"""
+
 from .context import Context
 
 __all__ = ["Context"]

src-new/astrbot_sdk/api/star/context.py

@@ -1,3 +1,26 @@
+"""插件上下文兼容层。
+
+此模块提供旧版 Context 类的向后兼容导入。
+Context 是插件运行时的核心接口，提供：
+
+- llm_generate(): 调用 LLM 生成文本
+- tool_loop_agent(): 运行 LLM Agent 循环
+- send_message(): 发送消息到会话
+- conversation_manager: 会话管理器
+- put_kv_data()/get_kv_data()/delete_kv_data(): 键值存储
+
+迁移说明：
+- 旧版: from astrbot_sdk.api.star import Context
+- 新版: from astrbot_sdk import Context (astrbot_sdk.context.Context)
+
+新版 Context 提供更丰富的接口：
+- ctx.llm.chat_raw(): LLM 调用
+- ctx.platform.send(): 发送消息
+- ctx.db.set()/get()/delete(): 数据存储
+
+注意：使用旧版 API 会触发弃用警告。
+"""
+
 from ..._legacy_api import Context
 
 __all__ = ["Context"]