mirror of
https://github.com/AstrBotDevs/AstrBot
synced 2026-07-16 01:40:15 +08:00
feat: 添加新旧架构对比文档，详细说明各模块的功能和结构变化
This commit is contained in:
whatevertogo
@@ -1,3 +1,54 @@
|
||||
# =============================================================================
|
||||
# 新旧对比 - _legacy_api.py
|
||||
# =============================================================================
|
||||
#
|
||||
# 【说明】
|
||||
# _legacy_api.py 是新版新增的兼容层，提供旧版 API 的兼容实现。
|
||||
# 旧版没有这个文件，相关功能分散在 api/star/ 目录下。
|
||||
#
|
||||
# 【提供的兼容类型】
|
||||
# - LegacyContext: 旧版 Context 兼容实现
|
||||
# - 提供 llm_generate(), tool_loop_agent(), send_message() 等方法
|
||||
# - 内部委托给新版 Context 的客户端
|
||||
#
|
||||
# - LegacyConversationManager: 旧版会话管理器兼容实现
|
||||
# - 提供 new_conversation(), switch_conversation(), delete_conversation() 等方法
|
||||
# - 使用 db 客户端存储会话数据
|
||||
#
|
||||
# - CommandComponent: 旧版命令组件基类
|
||||
# - 继承自 Star，标记为旧版 (__astrbot_is_new_star__ = False)
|
||||
#
|
||||
# - Context: 别名指向 LegacyContext
|
||||
#
|
||||
# 【旧版对应位置】
|
||||
# - Context: src/astrbot_sdk/api/star/context.py
|
||||
# - BaseConversationManager: src/astrbot_sdk/api/basic/conversation_mgr.py
|
||||
# - CommandComponent: 旧版可能是 Star 的别名或独立类
|
||||
#
|
||||
# =============================================================================
|
||||
# TODO: 功能缺失
|
||||
# =============================================================================
|
||||
#
|
||||
# 1. LegacyContext 方法不完整
|
||||
# - 缺少 _register_component() 方法（旧版有）
|
||||
# - add_llm_tools() 抛出 NotImplementedError（旧版支持）
|
||||
#
|
||||
# 2. LegacyConversationManager 方法不完整
|
||||
# - get_filtered_conversations(): 抛出 NotImplementedError
|
||||
# - get_human_readable_context(): 抛出 NotImplementedError
|
||||
# - 这些方法在旧版存在但新版不支持
|
||||
#
|
||||
# 3. 缺少旧版依赖类型的兼容
|
||||
# - ToolSet, FunctionTool: 旧版从 astr_agent_sdk 导入
|
||||
# - Message: 旧版从 astr_agent_sdk 导入
|
||||
# - MessageChain: 旧版从 api/message/chain.py 导入
|
||||
# - 新版需要考虑是否提供兼容导入路径
|
||||
#
|
||||
# 4. 迁移文档链接
|
||||
# - MIGRATION_DOC_URL 需要更新为实际迁移文档地址
|
||||
#
|
||||
# =============================================================================
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
from collections import defaultdict
|
||||
|
||||
@@ -1 +1,203 @@
|
||||
__all__: list[str] = []
|
||||
"""运行时模块。
|
||||
|
||||
定义 AstrBot SDK 的运行时架构，包括插件加载、能力路由、处理器分发和通信抽象。
|
||||
|
||||
架构说明：
|
||||
旧版:
|
||||
- 目录结构复杂：api/, rpc/, stars/ 等多个子目录
|
||||
- 使用 JSON-RPC 2.0 协议进行通信
|
||||
- StarManager 负责插件发现和加载
|
||||
- StarRunner 负责处理器执行
|
||||
- Galaxy 负责虚拟星层管理
|
||||
- 传输层分离为 client/server 两套实现
|
||||
|
||||
新版:
|
||||
- 目录结构精简：仅 6 个核心文件
|
||||
- 使用自描述协议进行通信
|
||||
- Peer 统一处理协议层消息收发
|
||||
- Transport 抽象传输层，支持多种实现
|
||||
- CapabilityRouter 注册和路由能力调用
|
||||
- HandlerDispatcher 分发处理器调用
|
||||
- SupervisorRuntime 管理多 Worker 会话
|
||||
|
||||
核心概念对比：
|
||||
旧版概念:
|
||||
- StarManager: 插件发现和加载
|
||||
- StarRunner: 处理器执行
|
||||
- Galaxy: 虚拟星层管理
|
||||
- JSONRPCServer/Client: JSON-RPC 通信
|
||||
- HandshakeHandler: 握手处理
|
||||
- HandlerExecutor: 处理器执行
|
||||
|
||||
新版概念:
|
||||
- Peer: 协议对等端，统一处理消息
|
||||
- Transport: 传输层抽象
|
||||
- CapabilityRouter: 能力路由
|
||||
- HandlerDispatcher: 处理器分发
|
||||
- SupervisorRuntime: 多 Worker 管理
|
||||
- WorkerSession: 单个 Worker 会话
|
||||
- PluginWorkerRuntime: 插件 Worker 运行时
|
||||
|
||||
通信流程对比：
|
||||
旧版 JSON-RPC 流程:
|
||||
1. Core -> Plugin: {"method": "handshake", ...}
|
||||
2. Plugin -> Core: {"result": {"handlers": [...]}}
|
||||
3. Core -> Plugin: {"method": "call_handler", "params": {...}}
|
||||
4. Plugin -> Core: {"method": "handler_stream_start", ...}
|
||||
5. Plugin -> Core: {"method": "handler_stream_update", ...}
|
||||
6. Plugin -> Core: {"method": "handler_stream_end", ...}
|
||||
|
||||
新版协议流程:
|
||||
1. Plugin -> Core: {"type": "initialize", "handlers": [...]}
|
||||
2. Core -> Plugin: {"type": "result", "kind": "initialize_result", ...}
|
||||
3. Core -> Plugin: {"type": "invoke", "capability": "handler.invoke", ...}
|
||||
4. Plugin -> Core: {"type": "event", "phase": "started"}
|
||||
5. Plugin -> Core: {"type": "event", "phase": "delta", "data": {...}}
|
||||
6. Plugin -> Core: {"type": "event", "phase": "completed", "output": {...}}
|
||||
|
||||
插件加载对比：
|
||||
旧版 StarManager:
|
||||
- 通过 plugin.yaml 发现插件
|
||||
- 动态导入组件类并实例化
|
||||
- 注册到 star_handlers_registry
|
||||
- 使用 functools.partial 绑定实例
|
||||
|
||||
新版 loader.py:
|
||||
- PluginSpec 描述插件规范
|
||||
- PluginEnvironmentManager 管理虚拟环境
|
||||
- load_plugin() 加载并解析组件
|
||||
- LoadedHandler 封装处理器和描述符
|
||||
- 支持新旧 Star 组件兼容
|
||||
|
||||
传输层对比：
|
||||
旧版传输层:
|
||||
- 分离的 client/ 和 server/ 目录
|
||||
- JSONRPCClient 基类 + StdioClient/WebSocketClient
|
||||
- JSONRPCServer 基类 + StdioServer/WebSocketServer
|
||||
- 通过 set_message_handler 设置回调
|
||||
|
||||
新版传输层:
|
||||
- 统一的 Transport 抽象基类
|
||||
- StdioTransport: 支持进程模式和文件模式
|
||||
- WebSocketServerTransport: WebSocket 服务端
|
||||
- WebSocketClientTransport: WebSocket 客户端
|
||||
- 通过 set_message_handler 设置回调
|
||||
|
||||
处理器执行对比：
|
||||
旧版 HandlerExecutor:
|
||||
- 从 star_handlers_registry 获取处理器
|
||||
- 调用 handler(event, **args)
|
||||
- 通过 JSON-RPC notification 发送流式结果
|
||||
- 无参数注入支持
|
||||
|
||||
新版 HandlerDispatcher:
|
||||
- 从 LoadedHandler 映射获取处理器
|
||||
- 支持类型注解注入 (MessageEvent, Context)
|
||||
- 支持参数名注入 (event, ctx, context)
|
||||
- 支持 legacy_args 注入 (命令参数等)
|
||||
- 支持 Optional[Type] 类型
|
||||
- 统一的错误处理和生命周期回调
|
||||
|
||||
能力系统对比：
|
||||
旧版:
|
||||
- 无显式的能力声明系统
|
||||
- 通过 call_context_function 调用核心功能
|
||||
- 上下文函数硬编码在核心侧
|
||||
|
||||
新版 CapabilityRouter:
|
||||
- CapabilityDescriptor 声明能力
|
||||
- JSON Schema 验证输入输出
|
||||
- 支持流式能力 (stream_handler)
|
||||
- 内置能力：llm.chat, memory.*, db.*, platform.*
|
||||
- 支持自定义能力注册
|
||||
|
||||
TODO: (架构完善):
|
||||
- Transport 缺少 TCP Socket 传输实现
|
||||
- Transport 缺少 Unix Domain Socket 传输实现
|
||||
- Transport 缺少共享内存传输实现（高性能场景）
|
||||
- Peer 缺少消息压缩支持（大数据传输）
|
||||
- Peer 缺少消息签名验证（安全通信）
|
||||
- CapabilityRouter 缺少能力版本控制
|
||||
- CapabilityRouter 缺少能力权限控制
|
||||
- CapabilityRouter 缺少能力调用计数/限流
|
||||
- HandlerDispatcher 缺少处理器超时控制
|
||||
- HandlerDispatcher 缺少处理器重试机制
|
||||
- HandlerDispatcher 缺少处理器依赖注入容器
|
||||
- loader.py 缺少插件热重载支持
|
||||
- loader.py 缺少插件依赖解析
|
||||
- loader.py 缺少插件沙箱隔离
|
||||
- bootstrap.py 缺少优雅关闭的超时机制
|
||||
- bootstrap.py 缺少健康检查端点
|
||||
- 缺少分布式部署支持（多节点 Supervisor）
|
||||
- 缺少插件状态持久化和恢复
|
||||
|
||||
TODO: (功能迁移):
|
||||
- 旧版 api/context.py 的功能需要迁移到新版 Context
|
||||
- 旧版 api/conversation_mgr.py 的会话管理需要迁移
|
||||
- 旧版 stars/filter/ 的过滤器需要评估迁移必要性
|
||||
- 旧版 stars/registry/ 的注册表功能已被 loader.py 替代
|
||||
- 旧版 galaxy.py 的虚拟星层管理已被 bootstrap.py 替代
|
||||
"""
|
||||
|
||||
from .bootstrap import (
|
||||
PluginWorkerRuntime,
|
||||
SupervisorRuntime,
|
||||
WorkerSession,
|
||||
run_plugin_worker,
|
||||
run_supervisor,
|
||||
run_websocket_server,
|
||||
)
|
||||
from .capability_router import CapabilityRouter, StreamExecution
|
||||
from .handler_dispatcher import HandlerDispatcher
|
||||
from .loader import (
|
||||
LoadedHandler,
|
||||
LoadedPlugin,
|
||||
PluginDiscoveryResult,
|
||||
PluginEnvironmentManager,
|
||||
PluginSpec,
|
||||
discover_plugins,
|
||||
load_plugin,
|
||||
load_plugin_spec,
|
||||
)
|
||||
from .peer import (
|
||||
CancelHandler,
|
||||
InitializeHandler,
|
||||
InvokeHandler,
|
||||
Peer,
|
||||
)
|
||||
from .transport import (
|
||||
MessageHandler,
|
||||
StdioTransport,
|
||||
Transport,
|
||||
WebSocketClientTransport,
|
||||
WebSocketServerTransport,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
"CancelHandler",
|
||||
"CapabilityRouter",
|
||||
"HandlerDispatcher",
|
||||
"InitializeHandler",
|
||||
"InvokeHandler",
|
||||
"LoadedHandler",
|
||||
"LoadedPlugin",
|
||||
"MessageHandler",
|
||||
"Peer",
|
||||
"PluginDiscoveryResult",
|
||||
"PluginEnvironmentManager",
|
||||
"PluginSpec",
|
||||
"PluginWorkerRuntime",
|
||||
"StdioTransport",
|
||||
"StreamExecution",
|
||||
"SupervisorRuntime",
|
||||
"Transport",
|
||||
"WebSocketClientTransport",
|
||||
"WebSocketServerTransport",
|
||||
"WorkerSession",
|
||||
"discover_plugins",
|
||||
"load_plugin",
|
||||
"load_plugin_spec",
|
||||
"run_plugin_worker",
|
||||
"run_supervisor",
|
||||
"run_websocket_server",
|
||||
]
|
||||
|
||||
@@ -1,3 +1,87 @@
|
||||
"""启动引导模块。
|
||||
|
||||
定义 SupervisorRuntime 和 PluginWorkerRuntime 的启动逻辑。
|
||||
Supervisor 管理多个 Worker 进程，Worker 运行单个插件。
|
||||
|
||||
架构层次：
|
||||
AstrBot Core (Python)
|
||||
|
|
||||
v
|
||||
SupervisorRuntime (管理多插件)
|
||||
|
|
||||
+-- WorkerSession (插件 A) -- StdioTransport -- PluginWorkerRuntime (子进程)
|
||||
|
|
||||
+-- WorkerSession (插件 B) -- StdioTransport -- PluginWorkerRuntime (子进程)
|
||||
|
|
||||
+-- WorkerSession (插件 C) -- StdioTransport -- PluginWorkerRuntime (子进程)
|
||||
|
||||
核心类：
|
||||
SupervisorRuntime: 监管者运行时
|
||||
- 发现并加载所有插件
|
||||
- 为每个插件启动 Worker 进程
|
||||
- 聚合所有 handler 并向 Core 注册
|
||||
- 路由 Core 的调用请求到对应 Worker
|
||||
- 处理 Worker 进程崩溃和重连
|
||||
|
||||
WorkerSession: Worker 会话
|
||||
- 管理单个插件 Worker 进程
|
||||
- 通过 Peer 与 Worker 通信
|
||||
- 提供 invoke_handler 和 cancel 方法
|
||||
- 处理连接关闭回调
|
||||
|
||||
PluginWorkerRuntime: 插件 Worker 运行时
|
||||
- 加载单个插件
|
||||
- 通过 Peer 与 Supervisor 通信
|
||||
- 分发 handler 调用
|
||||
- 处理生命周期回调 (on_start, on_stop)
|
||||
|
||||
与旧版对比：
|
||||
旧版 supervisor.py:
|
||||
- WorkerRuntime 管理单个插件进程
|
||||
- SupervisorRuntime 管理所有 Worker
|
||||
- 使用 JSON-RPC 协议通信
|
||||
- call_context_function 调用核心功能
|
||||
- 使用 RPCRequestHelper 管理请求
|
||||
|
||||
新版 bootstrap.py:
|
||||
- WorkerSession 封装 Worker 会话
|
||||
- SupervisorRuntime 使用 Peer 通信
|
||||
- 使用新协议 (initialize/invoke/event/cancel)
|
||||
- 通过 CapabilityRouter 路由能力调用
|
||||
- 支持 Worker 连接关闭回调
|
||||
- 支持 handler 冲突检测和警告
|
||||
|
||||
启动流程：
|
||||
Supervisor 启动:
|
||||
1. discover_plugins() 发现所有插件
|
||||
2. 为每个插件创建 WorkerSession
|
||||
3. 调用 session.start() 启动 Worker 进程
|
||||
4. 等待 Worker 初始化完成
|
||||
5. 聚合所有 handler 并向 Core 发送 initialize
|
||||
6. 等待 Core 的 initialize_result
|
||||
|
||||
Worker 启动:
|
||||
1. load_plugin_spec() 加载插件规范
|
||||
2. load_plugin() 加载插件组件
|
||||
3. 创建 Peer 并设置处理器
|
||||
4. 向 Supervisor 发送 initialize
|
||||
5. 等待 Supervisor 的 initialize_result
|
||||
6. 执行 on_start 生命周期回调
|
||||
|
||||
信号处理：
|
||||
- SIGTERM: 设置 stop_event，触发优雅关闭
|
||||
- SIGINT: 设置 stop_event，触发优雅关闭
|
||||
|
||||
TODO:
|
||||
- 添加 Worker 进程健康检查
|
||||
- 添加 Worker 进程自动重启
|
||||
- 添加优雅关闭的超时机制
|
||||
- 添加插件启动超时配置
|
||||
- 添加分布式部署支持（多节点 Supervisor）
|
||||
- 添加插件状态持久化和恢复
|
||||
- 添加 WebSocket 传输的 Supervisor 模式
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
|
||||
@@ -1,3 +1,93 @@
|
||||
"""能力路由模块。
|
||||
|
||||
定义 CapabilityRouter 类，负责能力的注册、发现和执行路由。
|
||||
能力是核心侧提供给插件侧调用的功能，如 LLM 聊天、存储、消息发送等。
|
||||
|
||||
核心概念：
|
||||
CapabilityDescriptor: 能力描述符，声明能力名称、输入输出 Schema 等
|
||||
CallHandler: 同步调用处理器，返回单次结果
|
||||
StreamHandler: 流式调用处理器，返回异步迭代器
|
||||
FinalizeHandler: 流式结果聚合器
|
||||
|
||||
内置能力：
|
||||
llm.chat: 同步 LLM 聊天
|
||||
llm.chat_raw: 同步 LLM 聊天（完整响应）
|
||||
llm.stream_chat: 流式 LLM 聊天
|
||||
memory.search: 搜索记忆
|
||||
memory.save: 保存记忆
|
||||
memory.delete: 删除记忆
|
||||
db.get: 读取 KV 存储
|
||||
db.set: 写入 KV 存储
|
||||
db.delete: 删除 KV 存储
|
||||
db.list: 列出 KV 键
|
||||
platform.send: 发送消息
|
||||
platform.send_image: 发送图片
|
||||
platform.get_members: 获取群成员
|
||||
|
||||
与旧版对比：
|
||||
旧版:
|
||||
- 无显式的能力声明系统
|
||||
- 通过 call_context_function 调用核心功能
|
||||
- 上下文函数名硬编码
|
||||
- 无输入输出 Schema 验证
|
||||
- 不支持流式能力
|
||||
|
||||
新版 CapabilityRouter:
|
||||
- 使用 CapabilityDescriptor 声明能力
|
||||
- JSON Schema 验证输入输出
|
||||
- 支持同步和流式两种调用模式
|
||||
- 统一的错误处理
|
||||
- 能力命名规范: namespace.action
|
||||
|
||||
能力命名规范：
|
||||
- 格式: {namespace}.{action}
|
||||
- 内置能力命名空间: llm, memory, db, platform
|
||||
- 保留命名空间前缀: handler., system., internal.
|
||||
|
||||
使用示例：
|
||||
router = CapabilityRouter()
|
||||
|
||||
# 注册同步能力
|
||||
router.register(
|
||||
CapabilityDescriptor(
|
||||
name="my_plugin.calculate",
|
||||
description="执行计算",
|
||||
input_schema={"type": "object", "properties": {"x": {"type": "number"}}},
|
||||
output_schema={"type": "object", "properties": {"result": {"type": "number"}}},
|
||||
),
|
||||
call_handler=my_calculate,
|
||||
)
|
||||
|
||||
# 注册流式能力
|
||||
async def stream_data(request_id, payload, token):
|
||||
for i in range(10):
|
||||
yield {"index": i}
|
||||
|
||||
router.register(
|
||||
CapabilityDescriptor(
|
||||
name="my_plugin.stream",
|
||||
description="流式数据",
|
||||
supports_stream=True,
|
||||
cancelable=True,
|
||||
),
|
||||
stream_handler=stream_data,
|
||||
finalize=lambda chunks: {"count": len(chunks)},
|
||||
)
|
||||
|
||||
# 执行能力
|
||||
result = await router.execute("my_plugin.calculate", {"x": 42}, stream=False, ...)
|
||||
stream_result = await router.execute("my_plugin.stream", {}, stream=True, ...)
|
||||
|
||||
TODO:
|
||||
- 添加能力版本控制
|
||||
- 添加能力权限控制
|
||||
- 添加能力调用计数/限流
|
||||
- 添加能力调用超时配置
|
||||
- 添加能力健康检查
|
||||
- 添加能力缓存支持
|
||||
- 添加能力熔断机制
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
|
||||
@@ -1,3 +1,72 @@
|
||||
"""处理器分发模块。
|
||||
|
||||
定义 HandlerDispatcher 类，负责将能力调用分发到具体的处理器函数。
|
||||
支持参数注入、流式执行、错误处理和生命周期回调。
|
||||
|
||||
核心职责：
|
||||
- 根据处理器 ID 查找处理器
|
||||
- 构建处理器参数（支持类型注解注入）
|
||||
- 执行处理器并处理结果
|
||||
- 处理异步生成器流式结果
|
||||
- 统一的错误处理
|
||||
|
||||
参数注入优先级：
|
||||
1. 按类型注解注入（支持 Optional[Type]）
|
||||
2. 按参数名注入（兼容无类型注解）
|
||||
3. 从 legacy_args 注入（命令参数等）
|
||||
|
||||
支持的注入类型：
|
||||
- MessageEvent: 消息事件
|
||||
- Context: 运行时上下文
|
||||
|
||||
与旧版对比：
|
||||
旧版 HandlerExecutor:
|
||||
- 从 star_handlers_registry 获取处理器
|
||||
- 直接调用 handler(event, **args)
|
||||
- 无参数注入支持
|
||||
- 通过 JSON-RPC notification 发送流式结果
|
||||
- 错误通过 JSON-RPC error 响应
|
||||
|
||||
新版 HandlerDispatcher:
|
||||
- 从 LoadedHandler 映射获取处理器
|
||||
- 支持类型注解注入 (MessageEvent, Context)
|
||||
- 支持参数名注入 (event, ctx, context)
|
||||
- 支持 legacy_args 注入
|
||||
- 支持 Optional[Type] 类型
|
||||
- 支持默认值
|
||||
- 统一的错误处理和 on_error 回调
|
||||
|
||||
处理器签名兼容：
|
||||
# 旧版签名
|
||||
def handler(event: AstrMessageEvent) -> str:
|
||||
return "result"
|
||||
|
||||
# 新版签名（类型注入）
|
||||
async def handler(event: MessageEvent, ctx: Context) -> None:
|
||||
await event.reply("result")
|
||||
|
||||
# 新版签名（名字注入）
|
||||
async def handler(event, ctx) -> None:
|
||||
await ctx.platform.send(event.session_id, "result")
|
||||
|
||||
# 流式处理器
|
||||
async def streaming_handler(event: MessageEvent):
|
||||
yield "chunk 1"
|
||||
yield "chunk 2"
|
||||
|
||||
结果处理：
|
||||
- PlainTextResult: 调用 event.reply()
|
||||
- str: 调用 event.reply()
|
||||
- dict with "text": 调用 event.reply(str(item["text"]))
|
||||
|
||||
TODO:
|
||||
- 添加处理器超时控制
|
||||
- 添加处理器重试机制
|
||||
- 添加处理器依赖注入容器
|
||||
- 添加处理器中间件支持
|
||||
- 添加处理器调用链追踪
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
|
||||
@@ -1,3 +1,88 @@
|
||||
"""插件加载模块。
|
||||
|
||||
定义插件发现、环境管理和加载的核心逻辑。
|
||||
支持新旧两种 Star 组件的兼容加载。
|
||||
|
||||
核心概念：
|
||||
PluginSpec: 插件规范，描述插件的基本信息
|
||||
PluginDiscoveryResult: 插件发现结果，包含成功和跳过的插件
|
||||
PluginEnvironmentManager: 插件虚拟环境管理器
|
||||
LoadedHandler: 加载后的处理器，包含描述符和可调用对象
|
||||
LoadedPlugin: 加载后的插件，包含处理器和实例
|
||||
|
||||
插件发现流程：
|
||||
1. 扫描 plugins_dir 下的子目录
|
||||
2. 检查 plugin.yaml 和 requirements.txt
|
||||
3. 解析 manifest_data 获取插件信息
|
||||
4. 验证必要字段（name, components, runtime.python）
|
||||
5. 返回 PluginDiscoveryResult
|
||||
|
||||
环境管理流程：
|
||||
1. 检查 .venv 目录是否存在
|
||||
2. 检查 Python 版本是否匹配
|
||||
3. 检查指纹是否变化（requirements 内容）
|
||||
4. 必要时重建虚拟环境
|
||||
5. 使用 uv 安装依赖
|
||||
|
||||
插件加载流程：
|
||||
1. 将插件目录添加到 sys.path
|
||||
2. 遍历 components 列表
|
||||
3. 动态导入组件类
|
||||
4. 判断是否为新版 Star
|
||||
5. 创建实例（新版直接实例化，旧版传入 legacy_context）
|
||||
6. 扫描处理器方法
|
||||
7. 构建 HandlerDescriptor
|
||||
|
||||
新旧 Star 组件兼容：
|
||||
新版 Star:
|
||||
- 继承自 Star 基类
|
||||
- __astrbot_is_new_star__ 返回 True
|
||||
- 无参构造函数
|
||||
- 通过 @handler 装饰器注册处理器
|
||||
|
||||
旧版 Star:
|
||||
- 不继承或 __astrbot_is_new_star__ 返回 False
|
||||
- 需要 legacy_context 参数
|
||||
- 通过 @xxx_handler 装饰器注册处理器
|
||||
- 使用 extras_configs 传递配置
|
||||
|
||||
与旧版对比：
|
||||
旧版 StarManager:
|
||||
- 通过 plugin.yaml 发现插件
|
||||
- 动态导入组件类并实例化
|
||||
- 注册到 star_handlers_registry
|
||||
- 使用 functools.partial 绑定实例
|
||||
- 无环境管理
|
||||
- 无指纹缓存
|
||||
|
||||
新版 loader.py:
|
||||
- PluginSpec 描述插件规范
|
||||
- PluginEnvironmentManager 管理虚拟环境
|
||||
- load_plugin() 加载并解析组件
|
||||
- LoadedHandler 封装处理器和描述符
|
||||
- 支持新旧 Star 组件兼容
|
||||
- 支持环境指纹缓存
|
||||
|
||||
plugin.yaml 格式：
|
||||
name: my_plugin
|
||||
author: author_name
|
||||
desc: Plugin description
|
||||
version: 1.0.0
|
||||
runtime:
|
||||
python: "3.11"
|
||||
components:
|
||||
- class: my_plugin.main:MyComponent
|
||||
|
||||
TODO:
|
||||
- 添加插件热重载支持
|
||||
- 添加插件依赖解析
|
||||
- 添加插件沙箱隔离
|
||||
- 添加插件签名验证
|
||||
- 添加插件版本约束
|
||||
- 添加插件仓库支持
|
||||
- 添加插件配置 Schema 验证
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
|
||||
@@ -1,3 +1,65 @@
|
||||
"""协议对等端模块。
|
||||
|
||||
定义 Peer 类，封装双向传输通道上的消息收发、初始化握手、能力调用、
|
||||
流式事件转发与取消处理。这里的 peer 指"通信对端/本端"这一网络协议概念，
|
||||
而不是业务上的用户、群聊或会话对象。
|
||||
|
||||
核心职责：
|
||||
- 消息序列化/反序列化
|
||||
- 初始化握手协议
|
||||
- 能力调用（同步/流式）
|
||||
- 取消处理
|
||||
- 连接生命周期管理
|
||||
|
||||
与旧版对比：
|
||||
旧版 JSON-RPC:
|
||||
- 分离的 JSONRPCClient 和 JSONRPCServer
|
||||
- 通过 method 字段区分操作类型
|
||||
- 使用 JSONRPCRequest/Response 消息类型
|
||||
- 流式通过独立的 notification 实现
|
||||
- 无统一的取消机制
|
||||
|
||||
新版 Peer:
|
||||
- 统一的 Peer 抽象，既是客户端也是服务端
|
||||
- 通过 type 字段区分消息类型
|
||||
- 使用 InitializeMessage/InvokeMessage/EventMessage 等
|
||||
- 流式通过 EventMessage(phase=delta) 实现
|
||||
- 统一的 CancelMessage 取消机制
|
||||
|
||||
使用示例：
|
||||
# 作为客户端发起调用
|
||||
peer = Peer(transport=transport, peer_info=PeerInfo(...))
|
||||
await peer.start()
|
||||
output = await peer.initialize(handlers)
|
||||
result = await peer.invoke("llm.chat", {"prompt": "hello"})
|
||||
|
||||
# 作为服务端处理调用
|
||||
peer.set_invoke_handler(my_handler)
|
||||
await peer.start()
|
||||
|
||||
消息处理流程：
|
||||
入站消息:
|
||||
ResultMessage -> 唤醒等待的 Future
|
||||
EventMessage -> 投递到流式队列
|
||||
InitializeMessage -> 调用 _initialize_handler
|
||||
InvokeMessage -> 创建任务调用 _invoke_handler
|
||||
CancelMessage -> 取消对应的任务
|
||||
|
||||
出站消息:
|
||||
initialize() -> InitializeMessage
|
||||
invoke() -> InvokeMessage(stream=False)
|
||||
invoke_stream() -> InvokeMessage(stream=True)
|
||||
cancel() -> CancelMessage
|
||||
|
||||
TODO:
|
||||
- 添加消息优先级支持
|
||||
- 添加消息过期时间支持
|
||||
- 添加消息重试计数支持
|
||||
- 添加消息追踪 ID (trace_id) 支持
|
||||
- 添加连接状态变更回调
|
||||
- 添加心跳检测机制
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
|
||||
@@ -1,3 +1,69 @@
|
||||
"""传输层抽象模块。
|
||||
|
||||
定义 Transport 抽象基类及其实现，负责底层的消息传输。
|
||||
传输层只关心"发送字符串"和"接收字符串"，不处理协议细节。
|
||||
|
||||
传输类型：
|
||||
Transport: 抽象基类，定义 start/stop/send 接口
|
||||
StdioTransport: 标准输入输出传输，支持进程模式和文件模式
|
||||
WebSocketServerTransport: WebSocket 服务端传输
|
||||
WebSocketClientTransport: WebSocket 客户端传输
|
||||
|
||||
与旧版对比：
|
||||
旧版传输层:
|
||||
- 分离的 client/ 和 server/ 目录
|
||||
- JSONRPCClient 基类
|
||||
- StdioClient: 子进程通信
|
||||
- WebSocketClient: WebSocket 客户端
|
||||
- JSONRPCServer 基类
|
||||
- StdioServer: 标准输入输出
|
||||
- WebSocketServer: WebSocket 服务端
|
||||
- 每个实现都处理 JSON-RPC 消息序列化
|
||||
|
||||
新版传输层:
|
||||
- 统一的 Transport 抽象
|
||||
- StdioTransport:
|
||||
- 支持启动子进程模式 (command 参数)
|
||||
- 支持文件描述符模式 (stdin/stdout 参数)
|
||||
- WebSocketServerTransport:
|
||||
- 单连接限制
|
||||
- 支持心跳配置
|
||||
- WebSocketClientTransport:
|
||||
- 自动重连需要外部实现
|
||||
- 传输层只处理字符串，协议由 Peer 层处理
|
||||
|
||||
使用示例：
|
||||
# 子进程模式
|
||||
transport = StdioTransport(
|
||||
command=["python", "-m", "my_plugin"],
|
||||
cwd="/path/to/plugin",
|
||||
)
|
||||
|
||||
# 标准输入输出模式
|
||||
transport = StdioTransport(stdin=sys.stdin, stdout=sys.stdout)
|
||||
|
||||
# WebSocket 服务端
|
||||
transport = WebSocketServerTransport(host="0.0.0.0", port=8765)
|
||||
|
||||
# WebSocket 客户端
|
||||
transport = WebSocketClientTransport(url="ws://localhost:8765")
|
||||
|
||||
# 统一接口
|
||||
transport.set_message_handler(my_handler)
|
||||
await transport.start()
|
||||
await transport.send(json_string)
|
||||
await transport.stop()
|
||||
|
||||
TODO:
|
||||
- 添加 TCP Socket 传输实现
|
||||
- 添加 Unix Domain Socket 传输实现
|
||||
- 添加共享内存传输实现（高性能场景）
|
||||
- 添加消息压缩支持
|
||||
- 添加断线重连机制（WebSocketClientTransport）
|
||||
- 添加连接状态变更回调
|
||||
- 添加带宽限制支持
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
|
||||
Reference in New Issue
Block a user