diff --git a/src-new/astrbot_sdk/_legacy_api.py b/src-new/astrbot_sdk/_legacy_api.py
index 53b4e9624..cfab0aaa5 100644
--- a/src-new/astrbot_sdk/_legacy_api.py
+++ b/src-new/astrbot_sdk/_legacy_api.py
@@ -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
diff --git a/src-new/astrbot_sdk/runtime/__init__.py b/src-new/astrbot_sdk/runtime/__init__.py
index c9c2ef67b..0a8b2b6b6 100644
--- a/src-new/astrbot_sdk/runtime/__init__.py
+++ b/src-new/astrbot_sdk/runtime/__init__.py
@@ -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",
+]
diff --git a/src-new/astrbot_sdk/runtime/bootstrap.py b/src-new/astrbot_sdk/runtime/bootstrap.py
index dd0572cd8..72a9fc713 100644
--- a/src-new/astrbot_sdk/runtime/bootstrap.py
+++ b/src-new/astrbot_sdk/runtime/bootstrap.py
@@ -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
diff --git a/src-new/astrbot_sdk/runtime/capability_router.py b/src-new/astrbot_sdk/runtime/capability_router.py
index 5470f4c34..36bfd59fb 100644
--- a/src-new/astrbot_sdk/runtime/capability_router.py
+++ b/src-new/astrbot_sdk/runtime/capability_router.py
@@ -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
diff --git a/src-new/astrbot_sdk/runtime/handler_dispatcher.py b/src-new/astrbot_sdk/runtime/handler_dispatcher.py
index 91e6aa0aa..235266111 100644
--- a/src-new/astrbot_sdk/runtime/handler_dispatcher.py
+++ b/src-new/astrbot_sdk/runtime/handler_dispatcher.py
@@ -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
diff --git a/src-new/astrbot_sdk/runtime/loader.py b/src-new/astrbot_sdk/runtime/loader.py
index de0737275..4f3b208d6 100644
--- a/src-new/astrbot_sdk/runtime/loader.py
+++ b/src-new/astrbot_sdk/runtime/loader.py
@@ -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
diff --git a/src-new/astrbot_sdk/runtime/peer.py b/src-new/astrbot_sdk/runtime/peer.py
index 199d8f6b2..ebf3d34c4 100644
--- a/src-new/astrbot_sdk/runtime/peer.py
+++ b/src-new/astrbot_sdk/runtime/peer.py
@@ -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
diff --git a/src-new/astrbot_sdk/runtime/transport.py b/src-new/astrbot_sdk/runtime/transport.py
index 0a24b15d0..697531815 100644
--- a/src-new/astrbot_sdk/runtime/transport.py
+++ b/src-new/astrbot_sdk/runtime/transport.py
@@ -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