Content
# AstrBot Orchestrator V5
`astrbot_plugin_orchestrator` is a chat-driven intelligent agent orchestration plugin running on `AstrBot >= 4.25` hosts.
It no longer develops its own Agent framework but is entirely built on top of AstrBot's official Agent system: the `/agent` command is driven by the official `tool_loop_agent`, and plugin/skill/MCP management, sandbox code execution, self-debugging, and YAML workflow are all encapsulated as official `FunctionTool` registered to the host. Sub-agents connect to the official `SubAgentOrchestrator` (HandoffTool). The default chat Agent and `/agent` command share the same set of tools.
## Version Requirements
- AstrBot `>= 4.25, < 5`
- Python `>= 3.10`
## Quality Snapshot
- `379+` unit tests passed (Linux full green; Windows native has a small number of dependency WSL/POSIX semantic sandbox test noise)
- `ruff` (full), `mypy`, `bandit` passed
- Tests do not depend on a real host: `_astrbot_stub/` aligns with all required API signatures according to AstrBot v4.25.5 tag source code
## Core Capabilities
- `Official Agent Drive`: `/agent <task>` = `context.tool_loop_agent` + plugin-registered FunctionTool + host existing tools, progress pushed via `event.send()`
- `Capability as Tool`: The following capabilities are registered as official `FunctionTool`, and can be directly called by LLM in default chat (high-risk tools have built-in administrator gate control):
- `plugin_search / plugin_list / plugin_install / plugin_uninstall / plugin_update`
- `skill_list / skill_read / skill_create / skill_delete`
- `mcp_list / mcp_add / mcp_remove / mcp_test / mcp_list_tools`
- `sandbox_exec_python / sandbox_exec_bash / sandbox_file_read / sandbox_file_write / sandbox_install_packages`
- `debug_status / debug_recent_errors`
- `workflow_list / workflow_run`
- `Official Sub-agent`: Predefined agent templates (research/code/test/debug, etc.) are written to the host's `subagent_orchestrator` configuration and hot-loaded, routed by the official HandoffTool.
- `Sandbox Execution Stack`: Local/Shipyard dual runtime, mode follows host `provider_settings.computer_use_runtime`, with health checks and controlled fallback.
- `Artifact Persistence`: `ArtifactService` uniformly handles code extraction, workspace writing, and export.
- `Workflow Engine`: YAML declarative workflow (start/agent/skill/mcp/condition/parallel/end).
- `Audit and Rate Limiting`: Command layer unified security audit log and trigger frequency limit.
## System Overview
```mermaid
flowchart TB
Chat[Ordinary Chat] --> DefaultAgent[AstrBot Default Agent]
Cmd["/agent Command"] --> Runner["AgentRunner (thin layer)"]
Runner --> TLA["context.tool_loop_agent"]
DefaultAgent --> Tools["Plugin-registered FunctionTools"]
TLA --> Tools
DefaultAgent --> Handoff["Official HandoffTool Sub-agent"]
Tools --> Caps["autonomous/* capability implementation"]
Caps --> Sandbox["sandbox/* execution stack"]
Caps --> Artifact["ArtifactService"]
Tools --> WF["WorkflowEngine YAML"]
```
Key points:
- The plugin no longer has its own research and development planning loop/meta-orchestrator/task analyzer, and orchestration is completely handed over to the host's official Agent.
- The difference between `/agent` and default chat is only the entrance and system prompt words, and both use the same set of tools.
## Command Entrance
| Command | Effect | Permission |
| --- | --- | --- |
| `/agent <task>` | Official tool_loop_agent-driven comprehensive task entrance | All (limited by rate limiting) |
| `/agent status` | View official sub-agent (handoffs) current status | All |
| `/agent templates` | View predefined sub-agent templates | All |
| `/agent sync` | Synchronize templates to host subagent configuration and hot-load | Administrator |
| `/plugin search/list/install/uninstall/update` | Plugin market maintenance | Write operations only for administrators |
| `/skill list/read/create/delete` | Skill management | Administrator |
| `/mcp list/add/remove/test/tools` | MCP server management | Administrator |
| `/exec <code>` | Unified executor execute code | Administrator |
| `/sandbox exec/files/read/install` | Bottom-level sandbox interface | Administrator |
| `/debug status/errors` | System status and recent errors | Administrator |
Command permissions are controlled by the official `@filter.permission_type(ADMIN)` decorator; FunctionTool high-risk operations are second-gated by `event.is_admin()` (non-administrators trigger LLM to receive rejection text).
## Configuration Points
Configuration items are defined by [_conf_schema.json](_conf_schema.json):
- `LLM and Orchestration`: `llm_provider` (empty follows session provider), `max_iterations`, `task_timeout`
- `Sub-agent`: `enable_dynamic_agents` (whether to synchronize templates to host subagent configuration at startup)
- `Capability Switches` (control whether corresponding FunctionTool groups are registered):
`enable_plugin_management`, `enable_skill_creation`, `enable_mcp_config`, `enable_code_execution`, `enable_self_debug`, `enable_workflows`
- `Execution and Security`: `auto_fix_sandbox`, `allow_local_fallback`
## Project Structure
| Path | Description |
| --- | --- |
| `main.py` | Plugin registration, command group definition, initialization (register tools + synchronize sub-agents) |
| `tools/` | Official FunctionTool encapsulation (plugin/skill/MCP/sandbox/debug/workflow) |
| `entrypoints/` | Command processing layer: rate limiting, audit, parameter verification |
| `runtime/` | `RuntimeContainer` assembly, `RequestContext`, execution strategy |
| `orchestrator/` | `AgentRunner` (tool_loop_agent thin layer), sub-agent configuration adapter, MCP/skill adaptation, code extraction |
| `autonomous/` | Plugin, skill, MCP, executor, debugging, and other capability implementations |
| `sandbox/` | Local and Shipyard execution environment abstraction |
| `artifacts/` | Artifact extraction and landing boundary |
| `workflow/` + `workflows/` | Workflow engine and YAML examples |
| `shared/` | Conditional evaluation, path safety, and other general capabilities |
| `_astrbot_stub/` | Host API test stub aligned with v4.25.5 (only for testing, not loaded with plugin) |
| `tests/unit/` | Unit tests |
## Coupling Points with Host
- Public API: `context.tool_loop_agent`, `context.add_llm_tools`, `context.get_config`, `context.get_llm_tool_manager`, `context.get_all_stars`, `context.get_all_providers`, `StarTools.get_data_dir()`, `astrbot.api.logger`.
- **Unique internal dependency**: plugin installation/uninstallation/update uses `context._star_manager` (AstrBot has no public plugin management API). This access point is concentrated in `autonomous/plugin_manager.py`, and if the host is upgraded and the interface changes, only one place needs to be modified.
## Development and Verification
```bash
cd astrbot_plugin_orchestrator
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
uv run pytest tests/unit
uv run ruff format --check . && uv run ruff check .
uv run mypy --follow-imports=skip shared/conditions.py shared/path_safety.py \
runtime/request_context.py runtime/container.py entrypoints/command_handlers.py \
artifacts/service.py orchestrator/agent_runner.py orchestrator/dynamic_agent_manager.py tools
uv run bandit -q -r artifacts entrypoints runtime shared sandbox tools workflow
```
Description:
- `AstrBot` is provided by the host and is not declared as an installation dependency; testing is injected with `_astrbot_stub` via `tests/conftest.py`.
- Directly declared runtime dependencies are only `aiohttp` and `PyYAML`.
## Document Index
- [docs/architecture.md](docs/architecture.md): Architecture description
- [docs/commands.md](docs/commands.md): Command description
- [docs/configuration.md](docs/configuration.md): Configuration description
- [SECURITY.md](SECURITY.md): Security principles and risk boundaries
## Security Boundary
- Default rejection of unsafe condition expressions, path traversal, and dangerous file names
- High-risk FunctionTool (installation/write file/execute code, etc.) requires the trigger to be an AstrBot administrator
- MCP server address only allows public network HTTPS, sensitive request headers force environment variable reference
- Sandbox local fallback is disabled by default (`allow_local_fallback: false`)
- Command layer unified audit log and rate limiting
