feat: 添加新旧对比文档，详细说明各模块结构变化及功能缺失

src-new/astrbot_sdk/__init__.py

@@ -1,3 +1,36 @@
+# =============================================================================
+# 新旧对比 - 第一层模块
+# =============================================================================
+#
+# 【旧版 src/astrbot_sdk/ 第一层结构】
+# - 文件夹: api/, cli/, runtime/, tests/
+# - 文件: __main__.py (仅入口)
+#
+# 【新版 src-new/astrbot_sdk/ 第一层结构】
+# - 文件夹: api/, clients/, protocol/, runtime/
+# - 文件: __init__.py, __main__.py, cli.py, compat.py, context.py,
+#         decorators.py, errors.py, events.py, star.py, _legacy_api.py
+#
+# 【结构变化说明】
+# 新版将多个核心概念从子模块提升到第一层，便于导入和使用：
+# - decorators.py: 装饰器（旧版在 api/star/decorators.py 或 api/event/filter.py）
+# - errors.py: 错误类（旧版在 api/star/ 下）
+# - events.py: 事件类（旧版在 api/event/ 下）
+# - star.py: Star 基类（旧版在 api/star/ 下）
+# - context.py: Context 上下文（旧版在 api/star/context.py）
+# - _legacy_api.py: 旧版兼容层（提供 LegacyContext、CommandComponent 等）
+#
+# =============================================================================
+# TODO: 缺失模块
+# =============================================================================
+#
+# 1. tests/ 文件夹
+#    - 旧版有 src/astrbot_sdk/tests/ 测试目录
+#    - 新版缺失，测试代码已移至 tests_v4/ 目录
+#    - 考虑是否需要保留 SDK 内置测试工具
+#
+# =============================================================================
+
 from .context import Context
 from .decorators import on_command, on_event, on_message, on_schedule, require_admin
 from .errors import AstrBotError

src-new/astrbot_sdk/__main__.py

@@ -1,3 +1,24 @@
+# =============================================================================
+# 新旧对比 - __main__.py
+# =============================================================================
+#
+# 【旧版 src/astrbot_sdk/__main__.py】
+# from .cli.main import cli
+# if __name__ == "__main__":
+#     cli()
+#
+# 【新版 src-new/astrbot_sdk/__main__.py】
+# from .cli import cli
+# if __name__ == "__main__":
+#     cli()
+#
+# 【差异】
+# - 旧版导入路径: .cli.main (cli/ 文件夹结构)
+# - 新版导入路径: .cli (cli.py 单文件)
+# - 功能等效，仅模块结构变化
+#
+# =============================================================================
+
 from .cli import cli
 
 

src-new/astrbot_sdk/cli.py

@@ -1,3 +1,44 @@
+# =============================================================================
+# 新旧对比 - cli.py
+# =============================================================================
+#
+# 【旧版 src/astrbot_sdk/cli/main.py】
+# - 位于 cli/ 文件夹中
+# - 有 setup_logger() 函数带 docstring
+# - run 命令有 @click.pass_context 装饰器
+# - plugins-dir 参数类型为 str
+# - run 命令有 logger.info 输出
+# - websocket 命令有 help 参数和 logger.info 输出
+#
+# 【新版 src-new/astrbot_sdk/cli.py】
+# - 位于第一层，单文件
+# - setup_logger() 无 docstring
+# - run 命令无 @click.pass_context
+# - plugins-dir 参数类型为 Path
+# - 无日志输出
+#
+# =============================================================================
+# TODO: 功能缺失
+# =============================================================================
+#
+# 1. CLI 命令缺少 docstring
+#    - 旧版 cli() 有 """AstrBot SDK CLI""" docstring
+#    - 旧版 run() 有 """Start the plugin supervisor over stdio.""" docstring
+#    - 旧版 worker() 有 """Internal command used by the supervisor to start a worker.""" docstring
+#    - 旧版 websocket() 有 """Legacy websocket runtime entrypoint.""" docstring
+#    - 新版所有命令都缺少 docstring
+#
+# 2. 缺少日志输出
+#    - 旧版 run() 有 logger.info(f"Starting plugin supervisor with plugins dir: {plugins_dir}")
+#    - 旧版 websocket() 有 logger.info(f"Starting WebSocket server on port {port}...")
+#    - 新版无对应日志输出
+#
+# 3. websocket 命令缺少 help 参数
+#    - 旧版: @click.option("--port", default=8765, help="WebSocket server port", type=int)
+#    - 新版: @click.option("--port", default=8765, type=int)
+#
+# =============================================================================
+
 from __future__ import annotations
 
 import asyncio

src-new/astrbot_sdk/compat.py

@@ -1,3 +1,24 @@
+# =============================================================================
+# 新旧对比 - compat.py
+# =============================================================================
+#
+# 【说明】
+# compat.py 是新版新增的兼容层模块，用于导出旧版 API。
+#
+# 【旧版】
+# 旧版没有独立的 compat.py 文件。
+# 旧版的 Context、CommandComponent 等类型定义在 api/star/ 目录下。
+#
+# 【新版】
+# 新版通过此兼容层重新导出 _legacy_api.py 中的旧版类型，
+# 使得旧代码可以通过 `from astrbot_sdk.compat import Context` 方式导入。
+#
+# 【设计目的】
+# 提供平滑的迁移路径，让旧版插件可以在新版 SDK 下继续工作，
+# 同时逐步引导开发者使用新版 API。
+#
+# =============================================================================
+
 from ._legacy_api import (
     CommandComponent,
     Context,

src-new/astrbot_sdk/context.py

@@ -1,3 +1,51 @@
+# =============================================================================
+# 新旧对比 - context.py
+# =============================================================================
+#
+# 【旧版 src/astrbot_sdk/api/star/context.py】
+# - Context 是抽象类 (ABC)
+# - 包含 conversation_manager、persona_manager 属性
+# - 提供方法: llm_generate(), tool_loop_agent(), send_message(),
+#            add_llm_tools(), put_kv_data(), get_kv_data(), delete_kv_data()
+# - 所有方法都是抽象方法 (...)
+# - 依赖: BaseConversationManager, ToolSet, FunctionTool, Message, LLMResponse, MessageChain
+#
+# 【新版 src-new/astrbot_sdk/context.py】
+# - Context 是具体类，直接实例化
+# - 包含客户端属性: llm, memory, db, platform
+# - 包含: plugin_id, logger, cancel_token
+# - 新增 CancelToken 数据类用于取消控制
+# - 通过 CapabilityProxy 代理实现跨进程调用
+#
+# 【架构差异】
+# - 旧版: 抽象基类，由 AstrBot Core 实现具体逻辑
+# - 新版: 具体类，通过 CapabilityProxy 代理调用远程能力
+#
+# =============================================================================
+# TODO: 功能缺失
+# =============================================================================
+#
+# 1. 缺少 conversation_manager 属性
+#    - 旧版: conversation_manager: BaseConversationManager
+#    - 新版: 已移至 _legacy_api.py 的 LegacyConversationManager
+#    - 迁移: 使用 ctx.db 直接操作会话数据，或使用 compat.LegacyConversationManager
+#
+# 2. 缺少 persona_manager 属性
+#    - 旧版: persona_manager: Any
+#    - 新版: 无对应实现
+#    - TODO: 需要确定是否需要在 clients/ 中添加 PersonaClient
+#
+# 3. 缺少 _register_component() 方法
+#    - 旧版: 用于注册组件实例及其公共方法
+#    - 新版: 架构变化，不再需要此方法
+#
+# 4. 方法签名变化
+#    - 旧版 llm_generate(chat_provider_id, ...): 需要 chat_provider_id
+#    - 新版 LLMClient.chat_raw(prompt, ...): 不需要 chat_provider_id
+#    - 迁移: 使用 ctx.llm.chat_raw() 替代 ctx.llm_generate()
+#
+# =============================================================================
+
 from __future__ import annotations
 
 import asyncio

src-new/astrbot_sdk/decorators.py

@@ -1,3 +1,59 @@
+# =============================================================================
+# 新旧对比 - decorators.py
+# =============================================================================
+#
+# 【旧版 src/astrbot_sdk/api/event/filter.py】
+# 导出的装饰器和类型:
+# - 装饰器: command, regex, custom_filter, event_message_type, permission_type,
+#          platform_adapter_type, after_message_sent, on_astrbot_loaded,
+#          on_platform_loaded, on_decorating_result, on_llm_request, on_llm_response,
+#          command_group, llm_tool (注释掉)
+# - 类型: CustomFilter, EventMessageType, EventMessageTypeFilter,
+#         PermissionType, PermissionTypeFilter, PlatformAdapterType, PlatformAdapterTypeFilter
+#
+# 【新版 src-new/astrbot_sdk/decorators.py】
+# 提供的装饰器:
+# - on_command, on_message, on_event, on_schedule, require_admin
+# - 内部类型: HandlerMeta, HandlerCallable
+#
+# =============================================================================
+# TODO: 功能缺失
+# =============================================================================
+#
+# 1. 缺少装饰器
+#    - custom_filter: 自定义过滤器装饰器
+#    - event_message_type: 消息类型过滤器
+#    - permission_type: 权限类型过滤器 (有 require_admin 但更通用)
+#    - 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 工具装饰器 (旧版已注释)
+#
+# 2. 缺少类型定义
+#    - CustomFilter: 自定义过滤器基类
+#    - EventMessageType: 消息类型枚举
+#    - EventMessageTypeFilter: 消息类型过滤器
+#    - PermissionType: 权限类型枚举
+#    - PermissionTypeFilter: 权限类型过滤器
+#    - PlatformAdapterType: 平台适配器类型枚举
+#    - PlatformAdapterTypeFilter: 平台适配器类型过滤器
+#
+# 3. 命名差异
+#    - 旧版 command -> 新版 on_command
+#    - 旧版 regex -> 新版 on_message(regex=...)
+#    - 新版 on_message 支持关键词和平台过滤
+#
+# 4. 新增功能
+#    - on_schedule: 定时任务装饰器 (旧版无)
+#    - require_admin: 管理员权限快捷装饰器 (旧版用 permission_type)
+#
+# =============================================================================
+
 from __future__ import annotations
 
 from dataclasses import dataclass, field

src-new/astrbot_sdk/errors.py

@@ -1,3 +1,36 @@
+# =============================================================================
+# 新旧对比 - errors.py
+# =============================================================================
+#
+# 【旧版】
+# 旧版 SDK 没有专门的 errors.py 文件。
+# 只有 runtime/rpc/jsonrpc.py 中定义了 JSONRPCErrorData 用于内部通信。
+#
+# 【新版】
+# 新增 errors.py，定义统一的 AstrBotError 异常类：
+# - 包含 code, message, hint, retryable 字段
+# - 提供工厂方法: cancelled(), capability_not_found(), invalid_input(),
+#                protocol_version_mismatch(), protocol_error(), internal_error()
+# - 支持序列化/反序列化: to_payload(), from_payload()
+#
+# 【设计目的】
+# 新版采用分布式架构，插件与核心通过 RPC 通信。
+# AstrBotError 提供统一的错误表示，便于跨进程传递错误信息。
+#
+# =============================================================================
+# TODO: 功能缺失
+# =============================================================================
+#
+# 1. 缺少旧版异常类兼容
+#    - 如果旧版有其他异常类（如 ChatProviderNotFoundError），需要考虑兼容
+#    - 当前 AstrBotError 可覆盖大部分场景
+#
+# 2. 缺少错误码常量定义
+#    - 建议添加错误码枚举或常量，便于错误匹配
+#    - 例如: ERROR_CODE_CANCELLED = "cancelled"
+#
+# =============================================================================
+
 from __future__ import annotations
 
 from dataclasses import dataclass

src-new/astrbot_sdk/events.py

@@ -1,3 +1,60 @@
+# =============================================================================
+# 新旧对比 - events.py
+# =============================================================================
+#
+# 【旧版 src/astrbot_sdk/api/event/】
+# 包含多个文件：
+# - astr_message_event.py: AstrMessageEvent 类（约 370 行）
+# - astrbot_message.py: AstrBotMessage 消息对象
+# - event_result.py: MessageEventResult 事件结果
+# - event_type.py: EventType 枚举
+# - message_session.py: MessageSession 会话
+# - message_type.py: MessageType 枚举
+#
+# 【新版 src-new/astrbot_sdk/events.py】
+# 仅包含:
+# - MessageEvent: 简化的消息事件类
+# - PlainTextResult: 纯文本结果数据类
+#
+# =============================================================================
+# TODO: 功能缺失
+# =============================================================================
+#
+# 1. AstrMessageEvent 大量功能缺失
+#    - 属性缺失:
+#      - message_obj: AstrBotMessage 消息对象
+#      - platform_meta: PlatformMetadata 平台元信息
+#      - role: "admin" | "member" 角色
+#      - is_wake, is_at_or_wake_command: 唤醒状态
+#      - session, unified_msg_origin: 会话标识
+#
+#    - 方法缺失:
+#      - get_platform_name(), get_platform_id(): 平台信息
+#      - get_messages(): 获取消息链
+#      - get_message_type(): 获取消息类型
+#      - get_group_id(), get_self_id(), get_sender_id(), get_sender_name(): ID 获取
+#      - set_extra(), get_extra(), clear_extra(): 额外信息存储
+#      - is_private_chat(), is_wake_up(), is_admin(): 状态判断
+#      - set_result(), stop_event(), continue_event(), is_stopped(): 事件控制
+#      - should_call_llm(), get_result(), clear_result(): LLM 控制
+#      - make_result(), plain_result(), image_result(), chain_result(): 结果构建
+#      - send(), react(), get_group(): 消息操作
+#
+# 2. 缺少关联类型
+#    - AstrBotMessage: 消息对象（包含 sender, message, type 等）
+#    - MessageEventResult: 事件结果（包含 chain, result_type 等）
+#    - MessageSession: 会话标识
+#    - MessageType: 消息类型枚举 (FRIEND_MESSAGE, GROUP_MESSAGE 等)
+#    - PlatformMetadata: 平台元信息
+#
+# 3. 新版 MessageEvent 特性
+#    - 简化设计，仅包含核心属性: text, user_id, group_id, platform, session_id
+#    - 通过 reply_handler 实现回复功能
+#    - 支持从 payload 构建: from_payload()
+#    - 支持序列化: to_payload()
+#
+# =============================================================================
+
 from __future__ import annotations
 
 from collections.abc import Awaitable, Callable

src-new/astrbot_sdk/star.py

@@ -1,3 +1,44 @@
+# =============================================================================
+# 新旧对比 - star.py
+# =============================================================================
+#
+# 【旧版 src/astrbot_sdk/api/star/star.py】
+# - StarMetadata: 插件元数据类（dataclass）
+#   - 属性: name, author, desc, version, repo, module_path, root_dir_name,
+#          reserved, activated, config, star_handler_full_names, display_name, logo_path
+# - 旧版没有 Star 基类定义（定义在其他文件中）
+#
+# 【新版 src-new/astrbot_sdk/star.py】
+# - Star: 插件基类
+#   - __handlers__: 处理器方法名元组
+#   - __init_subclass__(): 自动收集装饰器标记的方法
+#   - on_start(), on_stop(), on_error(): 生命周期钩子
+#   - __astrbot_is_new_star__(): 标识新版 Star
+#
+# 【架构差异】
+# - 旧版: StarMetadata 独立定义，Star 类在其他地方
+# - 新版: Star 基类在此文件，元数据通过装饰器自动收集
+#
+# =============================================================================
+# TODO: 功能缺失
+# =============================================================================
+#
+# 1. 缺少 StarMetadata 类
+#    - 旧版: @dataclass class StarMetadata
+#    - 新版: 无对应实现
+#    - 属性: name, author, desc, version, repo, module_path, root_dir_name,
+#           reserved, activated, config, star_handler_full_names, display_name, logo_path
+#    - 迁移: 可能需要在 api/star/__init__.py 或单独文件中实现
+#
+# 2. 生命周期方法差异
+#    - 新版 on_start/on_stop 参数类型为 Any | None
+#    - 应该使用更精确的类型注解
+#
+# 3. 缺少旧版 Star 接口方法（如果有的话）
+#    - 需要确认旧版 Star 是否有其他必须实现的接口方法
+#
+# =============================================================================
+
 from __future__ import annotations
 
 import traceback