mirror of
https://github.com/AstrBotDevs/AstrBot
synced 2026-07-17 01:49:15 +08:00
114 lines
2.6 KiB
Markdown
114 lines
2.6 KiB
Markdown
# RuntimeStatusStar Specification
|
|
|
|
## Overview
|
|
|
|
RuntimeStatusStar is an internal ABP (AstrBot Protocol) star plugin that exposes runtime state information via callable tools. It provides diagnostic capabilities for monitoring the AstrBot core runtime health.
|
|
|
|
## Tool Interface
|
|
|
|
### Tools Exposed
|
|
|
|
All tools follow the ABP tool calling convention via `call_tool(tool_name, arguments)`.
|
|
|
|
#### 1. get_runtime_status
|
|
|
|
Returns the current runtime state.
|
|
|
|
**Arguments:** None
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"running": true,
|
|
"uptime_seconds": 12345.67
|
|
}
|
|
```
|
|
|
|
#### 2. get_protocol_status
|
|
|
|
Returns the connection state of each protocol client.
|
|
|
|
**Arguments:** None
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"lsp": {"connected": true, "name": "lsp-client"},
|
|
"mcp": {"connected": false, "name": "mcp-client"},
|
|
"acp": {"connected": true, "name": "acp-client"},
|
|
"abp": {"connected": true, "name": "abp-client"}
|
|
}
|
|
```
|
|
|
|
#### 3. get_star_registry
|
|
|
|
Returns the list of registered star names.
|
|
|
|
**Arguments:** None
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"stars": ["runtime-status-star", "star-1", "star-2"]
|
|
}
|
|
```
|
|
|
|
#### 4. get_stats
|
|
|
|
Returns runtime statistics and metrics.
|
|
|
|
**Arguments:** None
|
|
|
|
**Returns:**
|
|
```json
|
|
{
|
|
"total_messages": 100,
|
|
"last_activity": "2024-01-01T00:00:00Z"
|
|
}
|
|
```
|
|
|
|
## Architecture
|
|
|
|
### Component Hierarchy
|
|
|
|
```
|
|
AstrbotOrchestrator
|
|
└── RuntimeStatusStar (auto-registered)
|
|
└── Tools: get_runtime_status, get_protocol_status, get_star_registry, get_stats
|
|
```
|
|
|
|
### Auto-Registration
|
|
|
|
RuntimeStatusStar is instantiated and registered in `AstrbotOrchestrator.__init__()`:
|
|
|
|
```python
|
|
from astrbot._internal.stars.runtime_status_star import RuntimeStatusStar
|
|
|
|
class AstrbotOrchestrator:
|
|
def __init__(self):
|
|
self._stars: dict[str, Star] = {}
|
|
# Auto-register RuntimeStatusStar
|
|
self._runtime_status_star = RuntimeStatusStar(self)
|
|
self._stars["runtime-status-star"] = self._runtime_status_star
|
|
```
|
|
|
|
### Orchestrator Reference
|
|
|
|
RuntimeStatusStar holds a reference to the orchestrator to query state:
|
|
|
|
```python
|
|
class RuntimeStatusStar(Star):
|
|
def __init__(self, orchestrator: AstrbotOrchestrator):
|
|
self._orchestrator = orchestrator
|
|
```
|
|
|
|
## Implementation Notes
|
|
|
|
1. **Thread Safety:** The orchestrator may be accessed from multiple contexts. All state queries should be read-only.
|
|
|
|
2. **Latency:** Tool calls should return immediately without blocking. No polling or long-running operations.
|
|
|
|
3. **Error Handling:** If any status query fails, return an error message rather than raising an exception.
|
|
|
|
4. **Future Extensibility:** Additional stats can be added by extending the `get_stats` tool response structure.
|