fz-mirrors/AstrBot
1
0
Fork 0
mirror of https://github.com/AstrBotDevs/AstrBot synced 2026-07-15 17:30:13 +08:00
Code Issues Packages Projects Releases Wiki Activity

chore: update protocol clients and add architecture compliance tests

Browse Source
This commit is contained in:
LIghtJUNction
2026-03-23 22:01:02 +08:00
parent 225ef79337
commit 20b7f60330
8 changed files with 525 additions and 51 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
astrbot/_internal/geteway/server.py
View File

@@ -74,7 +74,7 @@ class AstrbotGateway(BaseAstrbotGateway):
# CORS middleware
self._app.add_middleware(
CORSMiddleware,
CORSMiddleware, # type: ignore[misc]
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],

40
astrbot/_internal/protocols/acp/client.py
View File

@@ -7,13 +7,12 @@ similar to MCP but designed specifically for AstrBot's architecture.
from __future__ import annotations
import asyncio
import json
from typing import Any
import anyio
from astrbot import logger
from astrbot._internal.abc.acp.base_astrbot_acp_client import BaseAstrbotAcpClient
from astrbot.core.utils.astrbot_path import logger
log = logger
@@ -28,12 +27,12 @@ class AstrbotAcpClient(BaseAstrbotAcpClient):
def __init__(self) -> None:
self._connected = False
self._reader: anyio.AsyncFile | None = None
self._writer: anyio.AsyncFile | None = None
self._reader: asyncio.StreamReader | None = None
self._writer: asyncio.StreamWriter | None = None
self._server_url: str | None = None
self._pending_requests: dict[str, anyio.Future[dict[str, Any]]] = {}
self._pending_requests: dict[str, asyncio.Future[dict[str, Any]]] = {}
self._request_id = 0
self._reader_task: anyio.Task[None] | None = None
self._reader_task: asyncio.Task[None] | None = None
@property
def connected(self) -> bool:
@@ -60,11 +59,11 @@ class AstrbotAcpClient(BaseAstrbotAcpClient):
port: Server port
"""
self._server_url = f"{host}:{port}"
self._reader, self._writer = await anyio.connect_tcp(host, port)
self._reader, self._writer = await asyncio.open_connection(host, port)
self._connected = True
# Start reading responses
self._reader_task = anyio.create_task(self._read_messages())
self._reader_task = asyncio.create_task(self._read_messages())
log.info(f"ACP client connected to {self._server_url}")
@@ -76,10 +75,10 @@ class AstrbotAcpClient(BaseAstrbotAcpClient):
socket_path: Path to the Unix socket
"""
self._server_url = f"unix://{socket_path}"
self._reader, self._writer = await anyio.connect_unix(socket_path)
self._reader, self._writer = await asyncio.open_unix_connection(socket_path)
self._connected = True
self._reader_task = anyio.create_task(self._read_messages())
self._reader_task = asyncio.create_task(self._read_messages())
log.info(f"ACP client connected to {self._server_url}")
@@ -108,10 +107,7 @@ class AstrbotAcpClient(BaseAstrbotAcpClient):
continue
content_length = header.get("content-length", 0)
if (
content_length == 0
or len(buffer) < header_end + 1 + content_length
):
if content_length == 0 or len(buffer) < header_end + 1 + content_length:
break
content = buffer[header_end + 1 : header_end + 1 + content_length]
@@ -167,7 +163,7 @@ class AstrbotAcpClient(BaseAstrbotAcpClient):
"params": arguments,
}
future: anyio.Future[dict[str, Any]] = anyio.Future()
future: asyncio.Future[dict[str, Any]] = asyncio.Future()
self._pending_requests[request_id] = future
await self._send_message(message)
@@ -181,15 +177,17 @@ class AstrbotAcpClient(BaseAstrbotAcpClient):
content = json.dumps(message)
header = json.dumps({"content-length": len(content)}) + "\n"
await self._writer.write((header + content).encode())
await self._writer.flush()
self._writer.write((header + content).encode())
await self._writer.drain()
async def send_notification(self, method: str, params: dict[str, Any]) -> None:
async def send_notification(
self, method: str, params: dict[str, Any] | None = None
) -> None:
"""Send a one-way notification to the server."""
message = {
"jsonrpc": "2.0",
"method": method,
"params": params,
"params": params or {},
}
await self._send_message(message)
@@ -201,7 +199,7 @@ class AstrbotAcpClient(BaseAstrbotAcpClient):
self._reader_task.cancel()
try:
await self._reader_task
except (anyio.ExceptionGroup, BaseException):
except asyncio.CancelledError:
pass
if self._writer:

42
astrbot/_internal/protocols/lsp/client.py
View File

@@ -2,18 +2,17 @@
LSP (Language Server Protocol) client implementation.
The orchestrator acts as an LSP client, connecting to LSP servers
that provide language intelligence features (completions, diagnostics, etc.)
that provide language intelligence features (completions, diagnostics, etc.).
"""
from __future__ import annotations
import asyncio
import json
from typing import Any
import anyio
from astrbot import logger
from astrbot._internal.abc.lsp.base_astrbot_lsp_client import BaseAstrbotLspClient
from astrbot.core.utils.astrbot_path import logger
log = logger
@@ -28,13 +27,13 @@ class AstrbotLspClient(BaseAstrbotLspClient):
def __init__(self) -> None:
self._connected = False
self._reader: Any = None
self._writer: Any = None
self._server_process: Any = None
self._pending_requests: dict[int, anyio.abc.TaskGroup] = {}
self._reader: asyncio.StreamReader | None = None
self._writer: asyncio.StreamWriter | None = None
self._server_process: asyncio.subprocess.Process | None = None
self._pending_requests: dict[int, asyncio.Future[dict[str, Any]]] = {}
self._request_id = 0
self._server_command: list[str] | None = None
self._read_task: anyio.abc.Task | None = None
self._read_task: asyncio.Task[None] | None = None
@property
def connected(self) -> bool:
@@ -64,11 +63,11 @@ class AstrbotLspClient(BaseAstrbotLspClient):
"""
log.debug(f"Starting LSP server: {' '.join(command)}")
self._server_process = await anyio.open_process(
command,
stdin=anyio.PIPE,
stdout=anyio.PIPE,
stderr=anyio.PIPE,
self._server_process = await asyncio.create_subprocess_exec(
*command,
stdin=asyncio.subprocess.PIPE,
stdout=asyncio.subprocess.PIPE,
stderr=asyncio.subprocess.PIPE,
)
self._reader = self._server_process.stdout
self._writer = self._server_process.stdin
@@ -76,10 +75,10 @@ class AstrbotLspClient(BaseAstrbotLspClient):
self._connected = True
# Start reading responses in background
self._read_task = anyio.create_task(self._read_responses())
self._read_task = asyncio.create_task(self._read_responses())
# Send initialize request
await self._send_request(
await self.send_request(
"initialize",
{
"processId": None,
@@ -110,7 +109,7 @@ class AstrbotLspClient(BaseAstrbotLspClient):
"params": params or {},
}
future: anyio.Future[dict[str, Any]] = anyio.Future()
future: asyncio.Future[dict[str, Any]] = asyncio.Future()
self._pending_requests[request_id] = future
content = json.dumps(message)
@@ -120,7 +119,9 @@ class AstrbotLspClient(BaseAstrbotLspClient):
return await future
async def send_notification(self, method: str, params: dict[str, Any] | None = None) -> None:
async def send_notification(
self, method: str, params: dict[str, Any] | None = None
) -> None:
"""Send an LSP notification (no response expected)."""
if not self._writer:
raise RuntimeError("LSP client not connected")
@@ -207,9 +208,8 @@ class AstrbotLspClient(BaseAstrbotLspClient):
if self._server_process:
self._server_process.terminate()
try:
with anyio.move_on_after(5.0):
await self._server_process.wait()
except Exception:
await asyncio.wait_for(self._server_process.wait(), timeout=5.0)
except asyncio.TimeoutError:
self._server_process.kill()
self._server_process = None

14
astrbot/_internal/protocols/mcp/client.py
View File

@@ -17,7 +17,11 @@ from tenacity import (
)
from astrbot import logger
from astrbot._internal.abc.mcp.base_astrbot_mcp_client import BaseAstrbotMcpClient
from astrbot._internal.abc.mcp.base_astrbot_mcp_client import (
BaseAstrbotMcpClient,
McpServerConfig,
McpToolInfo,
)
from astrbot.core.utils.log_pipe import LogPipe
log = logger
@@ -207,7 +211,7 @@ class McpClient(BaseAstrbotMcpClient):
except (TypeError, ValueError):
return None
async def connect_to_server(self, mcp_server_config: dict, name: str) -> None:
async def connect_to_server(self, config: McpServerConfig, name: str) -> None:
"""Connect to MCP server
If `url` parameter exists:
@@ -216,15 +220,15 @@ class McpClient(BaseAstrbotMcpClient):
3. If not specified, default to SSE connection to MCP service.
Args:
mcp_server_config (dict): Configuration for the MCP server. See https://modelcontextprotocol.io/quickstart/server
config: Configuration for the MCP server. See https://modelcontextprotocol.io/quickstart/server
"""
# Store config for reconnection
self._mcp_server_config = mcp_server_config
self._mcp_server_config = config
self._server_name = name
self.process_pid = None
cfg = _prepare_config(mcp_server_config.copy())
cfg = _prepare_config(dict(config))
def logging_callback(
msg: str | mcp.types.LoggingMessageNotificationParams,

154
openspec/SPEC.md Normal file
View File

@@ -0,0 +1,154 @@
# AstrBot 架构规范
## 核心原则
1. **anyio 优先**: 所有异步代码必须使用 anyio，不是 asyncio
2. **类型安全**: 必须通过 `uvx ty check`，避免 Any 和 cast
3. **代码美观**: 必须通过 `ruff check .` 和 `ruff format .`
4. **测试完整**: 新功能必须有对应测试
## 协议系统
```
┌─────────────────────────────────────────────────────────┐
│ Orchestrator (Runtime) │
│ 协调 LSP, MCP, ACP, ABP 协议客户端 │
└─────────────────────────────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ LSP │ │ MCP │ │ ACP │
│ Client │ │ Client │ │ Client │
└─────────┘ └─────────┘ └─────────┘
│ │ │
▼ ▼ ▼
LSP Servers MCP Servers ACP Services
┌─────────────────────────────────────────────────┐
│ ABP Client │
│ (进程内 Star (插件) 通信) │
└─────────────────────────────────────────────────┘
│
▼
┌─────────┐
│ Stars │
│ (插件) │
└─────────┘
```
## ABP 协议 (AstrBot Protocol)
**目标**: 最终实现 ABP 协议
### 已完成
```python
class BaseAstrbotAbpClient(ABC):
connected: bool
async def connect() -> None
def register_star(name: str, instance: Any) -> None
def unregister_star(name: str) -> None
async def call_star_tool(star, tool, args) -> Any
async def shutdown() -> None
```
### 待完成
- ABP 服务端实现
- 完整的 JSON-RPC 2.0 消息格式
- star 心跳和健康检查
- 批量调用支持
## 文件结构
```
astrbot/_internal/
├── abc/ # 抽象基类
│ ├── base_astrbot_gateway.py
│ ├── base_astrbot_orchestrator.py
│ ├── abp/
│ ├── acp/
│ ├── lsp/
│ └── mcp/
├── protocols/ # 协议实现
│ ├── abp/client.py
│ ├── acp/client.py
│ ├── lsp/client.py
│ └── mcp/client.py
├── runtime/
│ └── orchestrator.py # 核心运行时
├── geteway/ # FastAPI 网关
│ ├── server.py
│ └── ws_manager.py
└── tools/
├── base.py
├── builtin.py
└── registry.py
```
## 异步库要求
### 正确 ✓
```python
import anyio
async def run():
async with anyio.create_task_group() as tg:
tg.start_soon(coro1)
tg.start_soon(coro2)
# 等待事件
event = anyio.Event()
await event.wait()
# 锁
lock = anyio.Lock()
async with lock:
...
```
### 错误 ✗
```python
import asyncio # 禁止使用!
# 错误
await asyncio.sleep(1)
asyncio.Lock()
asyncio.CancelledError
```
## 测试要求
测试文件位置: `tests/unit/test_internal/`
必须测试:
1. 每个协议客户端的 connect/disconnect
2. star 注册/注销
3. 工具调用
4. 错误处理
5. 生命周期管理
## 类型标注规范
```python
# Good ✓
async def call_star_tool(
self,
star_name: str,
tool_name: str,
arguments: dict[str, Any],
) -> Any:
...
# Bad ✗
async def call_star_tool(self, star, tool, args): # 没有类型
...
# Acceptable (必要时使用 Any)
async def call_star_tool(
self,
star_name: str,
tool_name: str,
arguments: dict[str, Any], # Any 是允许的因为参数结构可变
) -> Any: # Any 是允许的因为返回类型可变
...
```

74
openspec/TASKS.md Normal file
View File

@@ -0,0 +1,74 @@
# AstrBot 开发任务
## 当前最高优先级
### 1. 修复 anyio 违规 (P0)
**问题**: 代码使用 asyncio 但 openspec 要求使用 anyio
需要修改的文件:
- `astrbot/_internal/runtime/orchestrator.py`:
- `asyncio.sleep` → `anyio.sleep`
- `asyncio.CancelledError` → `anyio.CancelledError`
- `astrbot/_internal/protocols/mcp/client.py`:
- `asyncio.Lock` → `anyio.Lock`
- `astrbot/_internal/protocols/abp/client.py`:
- `asyncio.Future` → `anyio.Future`
### 2. 实现 ABP 协议完整功能 (P0)
ABP (AstrBot Protocol) 是最终目标
已完成:
- ABPClient 基础实现
- star 注册/注销
- call_star_tool 调用
待完成:
- ABP 服务端实现
- 完整的协议序列化
- 错误处理和重连机制
### 3. 测试覆盖提升 (P1)
当前测试: 81 passed, 3 failed (anyio 违规)
目标:
- 增加 _internal 模块测试覆盖率
- 修复 anyio 违规测试
- 添加协议集成测试
### 4. 类型标注完善 (P1)
执行: `uvx ty check astrbot/_internal/`
当前问题:
- 避免使用 Any
- 避免使用 cast
- 完善 return type annotations
---
## 进行中的任务
### 迁移现有功能到 _internal
状态: 部分完成
已迁移:
- MCP client → `astrbot/_internal/protocols/mcp/`
- ABP client → `astrbot/_internal/protocols/abp/`
- ACP client → `astrbot/_internal/protocols/acp/`
- LSP client → `astrbot/_internal/protocols/lsp/`
- Tools → `astrbot/_internal/tools/`
待迁移:
- 完整的 star 系统
- Gateway 服务端
- Orchestrator 核心
---
## 技术债务
1. **测试**: `tests/test_dashboard.py::test_auth_login` 失败
- 错误: `AttributeError: 'FuncCall' object has no attribute 'register_internal_tools'`
- 需要在 FuncCall 添加 register_internal_tools 方法或修复引用
2. **代码风格**: ruff ASYNC110 警告
- orchestrator run_loop 使用 asyncio.sleep 而非 anyio

8
tests/unit/test_internal/test_abp_protocol.py
View File

@@ -197,11 +197,13 @@ class TestAbpCodeQuality:
"""验证返回类型标注存在"""
import inspect
# connect 返回 None
assert inspect.signature(abp_client.connect).return_annotation is None
# connect 返回 None (annotation is 'None' string in Python 3.12)
connect_ann = inspect.signature(abp_client.connect).return_annotation
assert connect_ann in (None, "None")
# shutdown 返回 None
assert inspect.signature(abp_client.shutdown).return_annotation is None
shutdown_ann = inspect.signature(abp_client.shutdown).return_annotation
assert shutdown_ann in (None, "None")
@pytest.mark.asyncio
async def test_error_handling_has_type_hints(self, abp_client):

242
tests/unit/test_internal/test_architecture_compliance.py Normal file
View File

@@ -0,0 +1,242 @@
"""
新架构合规性测试套件
根据 openspec 最高旨意:
1. 使用 anyio 作为异步库（不是 asyncio）
2. 类型标注完整
3. 代码美观
4. 最终目标：实现 ABP 协议
"""
from __future__ import annotations
import ast
import inspect
from unittest.mock import AsyncMock, MagicMock
import pytest
class TestAnyioCompliance:
"""测试是否遵守 anyio 异步库指令
根据 openspec:
- 异步库使用 anyio
- 不是 asyncio
注意: 这些测试验证是否使用 anyio，当发现使用 asyncio 时会失败。
这正是我们想要的行为 - 测试驱动开发。
"""
def test_orchestrator_run_loop_documents_asyncio_violation(self):
"""记录: orchestrator 使用 asyncio.sleep 而不是 anyio.sleep
VIOLATION: 当前代码使用 asyncio.sleep
需要修改为 anyio.sleep
"""
from astrbot._internal.runtime.orchestrator import AstrbotOrchestrator
source = inspect.getsource(AstrbotOrchestrator.run_loop)
# 检查是否使用了 asyncio
uses_asyncio = "asyncio.sleep" in source
if uses_asyncio:
pytest.fail(
"orchestrator.run_loop 使用了 asyncio.sleep，违反 openspec 指令\n"
"应该使用 anyio.sleep\n"
"per openspec directive: '异步库使用anyio'"
)
def test_orchestrator_documents_asyncio_cancelled_error_violation(self):
"""记录: orchestrator 捕获 asyncio.CancelledError
VIOLATION: 当前代码捕获 asyncio.CancelledError
需要修改为 anyio.CancelledError
"""
from astrbot._internal.runtime.orchestrator import AstrbotOrchestrator
source = inspect.getsource(AstrbotOrchestrator.run_loop)
uses_asyncio_cancelled = "asyncio.CancelledError" in source
if uses_asyncio_cancelled:
pytest.fail(
"orchestrator 捕获了 asyncio.CancelledError，违反 openspec 指令\n"
"应该捕获 anyio.CancelledError\n"
"per openspec directive: '异步库使用anyio'"
)
def test_mcp_client_documents_asyncio_lock_violation(self):
"""记录: MCP 客户端使用 asyncio.Lock
VIOLATION: 当前代码使用 asyncio.Lock
需要修改为 anyio.Lock
"""
from astrbot._internal.protocols.mcp.client import McpClient
import asyncio
client = McpClient()
uses_asyncio_lock = isinstance(client._reconnect_lock, asyncio.Lock)
if uses_asyncio_lock:
pytest.fail(
"MCP 客户端使用了 asyncio.Lock，违反 openspec 指令\n"
"应该使用 anyio.Lock\n"
"per openspec directive: '异步库使用anyio'"
)
class TestTypeAnnotations:
"""测试类型标注完整性
根据 openspec:
- 代码必须通过 ty check
- 避免使用 Any 和 cast
"""
def test_abp_client_has_type_annotations(self):
"""ABP 客户端应该有类型标注"""
from astrbot._internal.protocols.abp.client import AstrbotAbpClient
client = AstrbotAbpClient()
# 检查主要方法是否有返回类型
connect_ann = inspect.signature(client.connect).return_annotation
assert connect_ann in (None, "None")
shutdown_ann = inspect.signature(client.shutdown).return_annotation
assert shutdown_ann in (None, "None")
def test_abp_client_connected_property_has_type(self):
"""connected 属性应该有类型标注"""
from astrbot._internal.protocols.abp.client import AstrbotAbpClient
client = AstrbotAbpClient()
assert isinstance(client.connected, bool)
class TestCodeStyle:
"""测试代码风格
根据 openspec:
- 代码必须通过 ruff check
- 代码必须通过 ruff format
"""
def test_abp_client_noobvious_style_issues(self):
"""ABP 客户端没有明显的风格问题"""
from astrbot._internal.protocols.abp.client import AstrbotAbpClient
import ast
source = inspect.getsource(AstrbotAbpClient)
try:
ast.parse(source)
except SyntaxError as e:
pytest.fail(f"ABP client has syntax error: {e}")
def test_orchestrator_noobvious_style_issues(self):
"""Orchestrator 没有明显的风格问题"""
from astrbot._internal.runtime.orchestrator import AstrbotOrchestrator
import ast
source = inspect.getsource(AstrbotOrchestrator)
try:
ast.parse(source)
except SyntaxError as e:
pytest.fail(f"Orchestrator has syntax error: {e}")
class TestArchitectureGoals:
"""测试架构目标
根据 openspec:
- 最终目标：实现 ABP 协议
- 代码美观
- 类型标注完美
- 将现有功能迁移到新架构
"""
@pytest.fixture
def abp_client(self):
from astrbot._internal.protocols.abp.client import AstrbotAbpClient
return AstrbotAbpClient()
@pytest.mark.asyncio
async def test_abp_client_meets_basic_protocol_requirements(self, abp_client):
"""ABP 客户端满足基本协议要求
根据 base_astrbot_abp_client.py ABC 定义:
- connect() -> None
- register_star(name, instance) -> None
- unregister_star(name) -> None
- call_star_tool(star, tool, args) -> Any
- shutdown() -> None
"""
await abp_client.connect()
assert abp_client.connected is True
# Test star registration
star = MagicMock()
star.call_tool = AsyncMock(return_value="ok")
abp_client.register_star("test-star", star)
# Test tool calling
result = await abp_client.call_star_tool("test-star", "test-tool", {})
assert result == "ok"
# Test unregistration
abp_client.unregister_star("test-star")
assert "test-star" not in abp_client._stars
# Test shutdown
await abp_client.shutdown()
assert abp_client.connected is False
def test_abp_client_has_abc_compliance(self):
"""ABP 客户端继承自 ABC"""
from astrbot._internal.protocols.abp.client import AstrbotAbpClient
from astrbot._internal.abc.abp.base_astrbot_abp_client import BaseAstrbotAbpClient
assert issubclass(AstrbotAbpClient, BaseAstrbotAbpClient)
class TestMigrationGuidance:
"""迁移指导测试
为将现有功能迁移到新架构提供测试支持
"""
@pytest.fixture
def orchestrator(self):
from astrbot._internal.runtime.orchestrator import AstrbotOrchestrator
return AstrbotOrchestrator()
@pytest.mark.asyncio
async def test_orchestrator_provides_star_management(self, orchestrator):
"""Orchestrator 提供 star 管理功能"""
star = MagicMock()
star.call_tool = AsyncMock(return_value="ok")
# Register
await orchestrator.register_star("test-star", star)
assert await orchestrator.get_star("test-star") is star
# List
stars = await orchestrator.list_stars()
assert "test-star" in stars
# Unregister
await orchestrator.unregister_star("test-star")
assert await orchestrator.get_star("test-star") is None
@pytest.mark.asyncio
async def test_orchestrator_manages_all_protocol_clients(self, orchestrator):
"""Orchestrator 管理所有协议客户端"""
assert hasattr(orchestrator, "lsp")
assert hasattr(orchestrator, "mcp")
assert hasattr(orchestrator, "acp")
assert hasattr(orchestrator, "abp")