refactor: 更新文档和代码注释，优化兼容性描述，增强可读性

src-new/astrbot_sdk/cli.py

@@ -561,7 +561,7 @@ def build(plugin_dir: Path, output_dir: Path | None) -> None:
     "--standalone",
     "standalone_mode",
     is_flag=True,
-    help="Alias of --local for compatibility",
+    help="Deprecated alias of --local",
 )
 @click.option("--event-text", type=str, help="Single message text to dispatch")
 @click.option("--interactive", is_flag=True, help="Read follow-up messages from stdin")
@@ -646,7 +646,7 @@ def worker(plugin_dir: Path | None, group_metadata: Path | None) -> None:
 @cli.command(hidden=True)
 @click.option("--port", default=8765, type=int, help="WebSocket server port")
 def websocket(port: int) -> None:
-    """Legacy websocket runtime entrypoint."""
+    """WebSocket runtime entrypoint kept for standalone bridge scenarios."""
     _run_async_entrypoint(
         run_websocket_server(port=port),
         log_message=f"启动 WebSocket 服务器，端口：{port}",

src-new/astrbot_sdk/decorators.py

@@ -1,7 +1,6 @@
 """v4 原生装饰器。
 
-旧版 ``astrbot_sdk.api.event.filter`` 的兼容与降级边界由 compat 模块处理，
-这里仅保留 v4 原生 trigger/permission 元数据建模。
+迁移期适配入口位于独立模块；这里仅保留 v4 原生 trigger/permission 元数据建模。
 """
 
 from __future__ import annotations

src-new/astrbot_sdk/events.py

@@ -1,8 +1,7 @@
 """v4 原生事件对象。
 
 顶层 ``MessageEvent`` 保持精简，只承载 v4 运行时真正需要的基础能力。
-旧版 ``AstrMessageEvent`` 的便捷方法与结果对象由
-``astrbot_sdk.api.event`` 兼容层承接，而不是继续塞回顶层事件类型。
+迁移期扩展事件能力放在独立模块中，而不是继续塞回顶层事件类型。
 """
 
 from __future__ import annotations

src-new/astrbot_sdk/runtime/transport.py

@@ -62,7 +62,7 @@
     await transport.stop()
 
 `Transport` 只处理“字符串发出去 / 字符串收进来”这件事，不做协议解析，也不关心
-能力、handler 或 legacy 兼容。当前实现包括：
+能力、handler 或迁移适配策略。当前实现包括：
 
 - `StdioTransport`: 子进程或文件对象上的按行文本传输
 - `WebSocketServerTransport`: 单连接 WebSocket 服务端

src-new/astrbot_sdk/star.py

@@ -1,7 +1,6 @@
 """v4 原生插件基类。
 
-旧版 ``StarMetadata`` 等兼容数据类型保留在 ``astrbot_sdk.api.star``，
-这里仅承载新版插件生命周期与 handler 收集逻辑。
+迁移期补充类型位于独立模块；这里仅承载 v4 插件生命周期与 handler 收集逻辑。
 """
 
 from __future__ import annotations

tests_v4/README.md

@@ -1,25 +1,36 @@
-# AstrBot SDK Test Framework
+# AstrBot SDK Tests
 
 ## Overview
 
-This test suite uses **pytest** with `pytest-asyncio` for testing the AstrBot SDK v4 implementation.
+当前测试集使用 `pytest` + `pytest-asyncio`，覆盖 v4 原生协议、运行时、客户端和本地开发入口。
 
 ## Test Structure
 
 ```
 tests_v4/
-├── conftest.py              # Shared fixtures and path bootstrap
-├── test_api_contract.py     # API contract tests
-├── test_api_decorators.py   # Decorator and Star class tests
-├── test_context.py          # Context and CancelToken tests
-├── test_entrypoints.py      # CLI entrypoint tests (requires installation)
-├── test_events.py           # MessageEvent and PlainTextResult tests
-├── test_legacy_adapter.py   # Legacy API compatibility tests
-├── test_peer.py             # Peer communication tests
-├── test_protocol.py         # Protocol message tests
-├── test_runtime.py          # Supervisor/Worker runtime tests
-├── test_script_migrations.py # Migration script tests
-└── test_supervisor_migration.py # Supervisor migration tests
+├── conftest.py                  # 共享 fixtures 和路径引导
+├── helpers.py                   # 内存传输等测试辅助
+├── test_api_decorators.py       # 装饰器元数据与 API 入口
+├── test_capability_proxy.py     # CapabilityProxy 调用与校验
+├── test_capability_router.py    # 内建 capability 与 schema 验证
+├── test_clients_module.py       # clients 包导出
+├── test_conftest_fixtures.py    # conftest fixtures 行为
+├── test_context.py              # Context 与 CancelToken
+├── test_db_client.py            # DBClient
+├── test_decorators.py           # 顶层 decorators 模块
+├── test_entrypoints.py          # 已安装环境下的 CLI 入口
+├── test_events.py               # MessageEvent
+├── test_handler_dispatcher.py   # handler/capability 参数注入与分发
+├── test_http_metadata_clients.py # HTTPClient 与 MetadataClient
+├── test_llm_client.py           # LLMClient
+├── test_memory_client.py        # MemoryClient
+├── test_peer.py                 # Peer 握手、调用、取消、连接失败
+├── test_platform_client.py      # PlatformClient
+├── test_protocol.py             # 协议级冒烟测试
+├── test_protocol_descriptors.py # 描述符与 schema 模型
+├── test_protocol_messages.py    # 协议消息模型
+├── test_testing_module.py       # 本地 harness / testing 入口
+└── test_transport.py            # stdio / websocket transport
 ```
 
 ## Running Tests
@@ -153,18 +164,9 @@ Or use the optional dependency group:
 pip install -e ".[test]"
 ```
 
-## Test Categories
+## Coverage Focus
 
-### Unit Tests (Fast)
-
-- `test_context.py` - CancelToken and Context tests
-- `test_events.py` - MessageEvent and PlainTextResult tests
-- `test_api_decorators.py` - Decorator tests
-- `test_protocol.py` - Protocol message tests
-
-### Integration Tests (Slower)
-
-- `test_peer.py` - Peer communication with real transports
-- `test_runtime.py` - Supervisor/Worker process tests
-- `test_legacy_adapter.py` - Legacy API compatibility
-- `test_script_migrations.py` - Migration script tests
+- 协议层：`test_protocol_messages.py`、`test_protocol_descriptors.py`、`test_peer.py`
+- 运行时调度：`test_capability_router.py`、`test_handler_dispatcher.py`
+- 客户端 facade：`test_llm_client.py`、`test_db_client.py`、`test_memory_client.py`、`test_platform_client.py`、`test_http_metadata_clients.py`
+- 本地开发入口：`test_testing_module.py`、`test_entrypoints.py`