diff --git a/src-new/astrbot_sdk/__init__.py b/src-new/astrbot_sdk/__init__.py index b9e2d98df..9cd3894e2 100644 --- a/src-new/astrbot_sdk/__init__.py +++ b/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 diff --git a/src-new/astrbot_sdk/__main__.py b/src-new/astrbot_sdk/__main__.py index 491a4d136..577ab1386 100644 --- a/src-new/astrbot_sdk/__main__.py +++ b/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 diff --git a/src-new/astrbot_sdk/cli.py b/src-new/astrbot_sdk/cli.py index 01748a64d..a47f53481 100644 --- a/src-new/astrbot_sdk/cli.py +++ b/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 diff --git a/src-new/astrbot_sdk/compat.py b/src-new/astrbot_sdk/compat.py index 8632db153..69cd43231 100644 --- a/src-new/astrbot_sdk/compat.py +++ b/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, diff --git a/src-new/astrbot_sdk/context.py b/src-new/astrbot_sdk/context.py index 216caec23..ec9513134 100644 --- a/src-new/astrbot_sdk/context.py +++ b/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 diff --git a/src-new/astrbot_sdk/decorators.py b/src-new/astrbot_sdk/decorators.py index 4b783f96f..0e0e733dd 100644 --- a/src-new/astrbot_sdk/decorators.py +++ b/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 diff --git a/src-new/astrbot_sdk/errors.py b/src-new/astrbot_sdk/errors.py index a8629d722..98a0443e5 100644 --- a/src-new/astrbot_sdk/errors.py +++ b/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 diff --git a/src-new/astrbot_sdk/events.py b/src-new/astrbot_sdk/events.py index 6c3c77c7e..d2f25b273 100644 --- a/src-new/astrbot_sdk/events.py +++ b/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 diff --git a/src-new/astrbot_sdk/star.py b/src-new/astrbot_sdk/star.py index 82993d914..d8a20f52d 100644 --- a/src-new/astrbot_sdk/star.py +++ b/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