feat: 添加新版 API 模块文档，详细说明与旧版的差异及缺失内容

src-new/astrbot_sdk/api/__init__.py

@@ -7,6 +7,118 @@
 
 注意：大部分 API 是为了兼容旧版插件而保留的兼容层。
 新版 API 请参考 astrbot_sdk.context.Context 和 astrbot_sdk.decorators 模块。
+
+# TODO: 相比旧版 API (src/astrbot_sdk/api)，新版缺少以下模块：
+
+## 1. basic/ 模块 (完全缺失)
+旧版路径: src/astrbot_sdk/api/basic/
+- AstrBotConfig: AstrBot 配置类，继承自 dict
+- BaseConversationManager: 会话管理基类，提供以下方法：
+  - new_conversation(): 新建对话
+  - switch_conversation(): 切换对话
+  - delete_conversation(): 删除对话
+  - get_curr_conversation_id(): 获取当前对话 ID
+  - get_conversation(): 获取对话
+  - get_conversations(): 获取对话列表
+  - get_filtered_conversations(): 获取过滤后的对话列表
+  - update_conversation(): 更新对话
+  - add_message_pair(): 添加消息对
+  - get_human_readable_context(): 获取人类可读上下文
+- Conversation: 对话实体数据类 (platform_id, user_id, cid, history, title, persona_id, created_at, updated_at)
+
+## 2. message/ 模块 (完全缺失)
+旧版路径: src/astrbot_sdk/api/message/
+- MessageChain: 消息链类，提供链式 API：
+  - message(): 添加文本
+  - at(): 添加 @ 提及
+  - at_all(): 添加 @ 全体成员
+  - url_image(): 添加网络图片
+  - file_image(): 添加本地图片
+  - base64_image(): 添加 base64 图片
+  - use_t2i(): 设置文本转图片
+  - get_plain_text(): 获取纯文本
+  - squash_plain(): 合并文本段
+- 消息组件类 (components.py):
+  - Plain, Image, Record, Video, File (基础类型)
+  - At, AtAll, Reply, Face, Node, Nodes (IM 类型)
+  - Share, Contact, Location, Music, Poke, Forward, Json, WechatEmoji 等
+  - ComponentType 枚举, BaseMessageComponent 基类
+
+## 3. event/ 模块 (部分缺失)
+旧版路径: src/astrbot_sdk/api/event/
+已有:
+- filter.py (简化版): command, regex, permission 装饰器
+缺失:
+- astrbot_message.py:
+  - MessageMember: 消息成员数据类 (user_id, nickname)
+  - Group: 群组数据类 (group_id, group_name, group_avatar, group_owner, group_admins, members)
+  - AstrBotMessage: AstrBot 消息对象 (type, self_id, session_id, message_id, sender, message, message_str, raw_message, timestamp, group)
+- astr_message_event.py:
+  - AstrMessageEvent: 消息事件类，核心方法：
+    - get_platform_name/id(), get_message_str/messages/type()
+    - get_session_id/group_id/self_id/sender_id/sender_name()
+    - set_extra/get_extra/clear_extra()
+    - is_private_chat/is_wake_up/is_admin()
+    - set_result/stop_event/continue_event/is_stopped()
+    - make_result/plain_result/image_result/chain_result()
+    - send(), react(), get_group()
+  - AstrMessageEventModel: Pydantic 模型版本
+- event_result.py:
+  - EventResultType: 事件结果类型枚举 (CONTINUE, STOP)
+  - ResultContentType: 结果内容类型枚举 (LLM_RESULT, GENERAL_RESULT, STREAMING_RESULT, STREAMING_FINISH)
+  - MessageEventResult: 消息事件结果类，继承 MessageChain
+- event_type.py:
+  - EventType: 内部事件类型枚举 (OnAstrBotLoadedEvent, OnPlatformLoadedEvent, AdapterMessageEvent, OnLLMRequestEvent, OnLLMResponseEvent, OnDecoratingResultEvent, OnCallingFuncToolEvent, OnAfterMessageSentEvent)
+- message_session.py:
+  - MessageSession: 消息会话标识类 (platform_name, message_type, session_id)
+- message_type.py:
+  - MessageType: 消息类型枚举 (GROUP_MESSAGE, FRIEND_MESSAGE, OTHER_MESSAGE)
+
+## 4. platform/ 模块 (完全缺失)
+旧版路径: src/astrbot_sdk/api/platform/
+- PlatformMetadata: 平台元数据类 (name, description, id, default_config_tmpl, adapter_display_name, logo_path)
+
+## 5. provider/ 模块 (完全缺失)
+旧版路径: src/astrbot_sdk/api/provider/
+- LLMResponse: LLM 响应数据类
+  - role, result_chain, tools_call_args/tools_call_name/tools_call_ids
+  - raw_completion (支持 OpenAI/Anthropic/Google 格式)
+  - to_openai_tool_calls(), to_openai_to_calls_model()
+
+## 6. star/ 模块 (部分缺失)
+旧版路径: src/astrbot_sdk/api/star/
+已有:
+- context.py (兼容层): Context 类
+缺失:
+- star.py:
+  - StarMetadata: 插件元数据类 (name, author, desc, version, repo, module_path, root_dir_name, reserved, activated, config, star_handler_full_names, display_name, logo_path)
+
+## 7. components/ 模块 (部分缺失)
+旧版路径: src/astrbot_sdk/api/components/
+已有:
+- command.py: CommandComponent 兼容层
+缺失: (无其他文件，旧版也只有 command.py)
+
+## 8. filter.py 装饰器 (部分缺失)
+旧版 filter.py 导出的装饰器:
+已有: command, regex, permission
+缺失:
+- custom_filter: 自定义过滤器
+- event_message_type: 事件消息类型
+- platform_adapter_type: 平台适配器类型
+- after_message_sent: 消息发送后钩子
+- on_astrbot_loaded: AstrBot 加载完成钩子
+- on_platform_loaded: 平台加载完成钩子
+- on_decorating_result: 结果装饰钩子
+- on_llm_request: LLM 请求钩子
+- on_llm_response: LLM 响应钩子
+- command_group: 命令组
+- llm_tool: LLM 工具注册 (已注释)
+
+旧版还导出:
+- CustomFilter, EventMessageType, EventMessageTypeFilter
+- PermissionType, PermissionTypeFilter
+- PlatformAdapterType, PlatformAdapterTypeFilter
 """
 
 __all__: list[str] = []

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

@@ -4,6 +4,16 @@
 CommandComponent 是旧版 Star 基类的别名，用于向后兼容。
 
 新版插件建议直接使用 astrbot_sdk.star.Star 和装饰器模式。
+
+# TODO: 新旧版 components 模块对比：
+
+## 旧版 components 模块结构：
+- command.py: CommandComponent 基类
+
+## 新版与旧版基本一致：
+此模块功能完整，与旧版保持兼容。
+
+## 无缺失内容
 """
 
 from .command import CommandComponent

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

@@ -20,6 +20,17 @@ CommandComponent 是插件命令处理器的基类。
         @on_command("hello")
         async def handle_hello(self, ctx: Context):
             ...
+
+# TODO: 新旧版 components 模块对比：
+
+## 旧版 components 模块结构：
+- command.py: CommandComponent 基类（已有兼容层）
+
+## 新版与旧版基本一致：
+旧版 components 模块仅包含 command.py，新版已提供兼容层。
+
+## 无缺失内容
+此模块功能完整，与旧版保持兼容。
 """
 
 from ..._legacy_api import CommandComponent

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

@@ -7,6 +7,42 @@
 
 此模块是旧版 astrbot_sdk.api.event 的兼容层。
 新版 API 建议直接使用 astrbot_sdk.events.MessageEvent 和 astrbot_sdk.decorators。
+
+# TODO: 相比旧版 event 模块，新版缺少以下内容：
+
+## 缺失的文件：
+1. astrbot_message.py:
+   - MessageMember: 消息成员数据类
+   - Group: 群组数据类
+   - AstrBotMessage: AstrBot 消息对象
+
+2. astr_message_event.py:
+   - AstrMessageEvent: 完整的消息事件类（当前只有 MessageEvent 别名）
+   - AstrMessageEventModel: Pydantic 模型版本
+
+3. event_result.py:
+   - EventResultType: 事件结果类型枚举
+   - ResultContentType: 结果内容类型枚举
+   - MessageEventResult: 消息事件结果类
+
+4. event_type.py:
+   - EventType: 内部事件类型枚举
+
+5. message_session.py:
+   - MessageSession: 消息会话标识类
+
+6. message_type.py:
+   - MessageType: 消息类型枚举
+
+## 缺失的功能：
+旧版 AstrMessageEvent 提供的便捷方法：
+- get_platform_name/id(), get_message_str/messages/type()
+- get_session_id/group_id/self_id/sender_id/sender_name()
+- set_extra/get_extra/clear_extra() 额外信息存储
+- is_private_chat/is_wake_up/is_admin() 状态检查
+- set_result/stop_event/continue_event/is_stopped() 事件控制
+- make_result/plain_result/image_result/chain_result() 结果构建
+- send(), react(), get_group() 消息操作
 """
 
 from ...events import MessageEvent as AstrMessageEvent

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

@@ -15,6 +15,55 @@
         ...
 
 新版建议直接使用 astrbot_sdk.decorators 模块中的装饰器。
+
+# TODO: 相比旧版 filter.py，新版缺少以下装饰器和类型：
+
+## 缺失的装饰器：
+1. custom_filter: 自定义过滤器装饰器
+2. event_message_type: 事件消息类型过滤器
+3. platform_adapter_type: 平台适配器类型过滤器
+4. after_message_sent: 消息发送后钩子
+5. on_astrbot_loaded: AstrBot 加载完成钩子
+6. on_platform_loaded: 平台加载完成钩子
+7. on_decorating_result: 结果装饰钩子
+8. on_llm_request: LLM 请求钩子
+9. on_llm_response: LLM 响应钩子
+10. command_group: 命令组装饰器
+11. llm_tool: LLM 工具注册 (旧版已注释)
+
+## 缺失的类型导出：
+1. CustomFilter: 自定义过滤器基类
+2. EventMessageType: 事件消息类型枚举
+3. EventMessageTypeFilter: 事件消息类型过滤器类
+4. PermissionType: 权限类型枚举
+5. PermissionTypeFilter: 权限类型过滤器类
+6. PlatformAdapterType: 平台适配器类型枚举
+7. PlatformAdapterTypeFilter: 平台适配器类型过滤器类
+
+## 旧版导出列表 (参考):
+__all__ = [
+    "CustomFilter",
+    "EventMessageType",
+    "EventMessageTypeFilter",
+    "PermissionType",
+    "PermissionTypeFilter",
+    "PlatformAdapterType",
+    "PlatformAdapterTypeFilter",
+    "after_message_sent",
+    "command",
+    "command_group",
+    "custom_filter",
+    "event_message_type",
+    # "llm_tool",
+    "on_astrbot_loaded",
+    "on_decorating_result",
+    "on_llm_request",
+    "on_llm_response",
+    "on_platform_loaded",
+    "permission_type",
+    "platform_adapter_type",
+    "regex",
+]
 """
 
 from __future__ import annotations

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

@@ -10,6 +10,25 @@
 Context 实际上是 LegacyContext 的别名，用于向后兼容旧版插件。
 
 新版插件建议使用 astrbot_sdk.context.Context。
+
+# TODO: 相比旧版 star 模块，新版缺少以下内容：
+
+## 缺失的文件：
+- star.py: StarMetadata 插件元数据类
+
+## 旧版 star 模块结构：
+1. context.py - Context 抽象类（已有兼容层）
+2. star.py - StarMetadata 数据类（缺失）
+
+StarMetadata 用于描述插件的元信息，包括：
+- 基础信息: name, author, desc, version, repo
+- 模块路径: module_path, root_dir_name
+- 状态标志: reserved, activated
+- 配置: config (AstrBotConfig)
+- Handler 信息: star_handler_full_names
+- 展示信息: display_name, logo_path
+
+建议在新版中提供等效的插件元数据访问接口。
 """
 
 from .context import Context

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

@@ -19,6 +19,22 @@ Context 是插件运行时的核心接口，提供：
 - ctx.db.set()/get()/delete(): 数据存储
 
 注意：使用旧版 API 会触发弃用警告。
+
+# TODO: 相比旧版 star 模块，新版缺少以下内容：
+
+## 缺失的文件：
+1. star.py:
+   - StarMetadata: 插件元数据类
+     - name, author, desc, version, repo: 基础信息
+     - module_path, root_dir_name: 模块路径信息
+     - reserved, activated: 状态标志
+     - config: AstrBotConfig 插件配置
+     - star_handler_full_names: Handler 全名列表
+     - display_name, logo_path: 展示信息
+
+## 缺失的导入（旧版 star/__init__.py 为空）：
+旧版 star 模块主要通过 context.py 提供 Context 类，
+新版通过兼容层导入，但缺少 StarMetadata 的公开导出。
 """
 
 from ..._legacy_api import Context