AstrBot/docs/skills/astrbot-dev-guide.md

name, description

name	description
astrbot-dev-guide	Guide for AI assistants developing AstrBot - project conventions, code style, and common patterns

AstrBot Developer Guide

This skill provides guidance for AI assistants working on AstrBot development.

Project Overview

AstrBot is an open-source, all-in-one Agentic chat assistant supporting multiple IM platforms (QQ, Telegram, Discord, Lark, DingTalk, Slack, etc.) and LLM providers.

• Main entry: astrbot/__main__.py or CLI astrbot run
• CLI commands: astrbot/cli/commands/
• Core modules: astrbot/core/
• Platform adapters: astrbot/core/platform/sources/
• Star plugins: astrbot/builtin_stars/
• Dashboard: dashboard/ (Vue.js)

Quick Start Commands

# Install
uv tool install -e . --force

# Initialize
astrbot init

# Run
astrbot run

# Backend only (no WebUI)
astrbot run --backend-only

# Frontend
cd dashboard && bun dev

# Tests
uv sync --group dev && uv run pytest --cov=astrbot tests/

Code Style Rules

Type Hints (Required)

Use Python 3.12+ syntax:

• list[str] not List[str]
• int | None not Optional[int]
• Avoid Any when possible

Path Handling

Always use pathlib.Path:

from pathlib import Path
from astrbot.core.utils.astrbot_path import get_astrbot_data_path

Formatting

Run before every commit:

ruff format .
ruff check .

Comments

Write all comments in English.

Environment Variables

When adding new environment variables:

1. Prefix with ASTRBOT_ (e.g., ASTRBOT_ENABLE_FEATURE)
2. Add to .env.example with description
3. Update astrbot/cli/commands/cmd_run.py:
   • Add to module docstring under "Environment Variables Used in Project"
   • Add to keys_to_print list for debug output

Core Paths Utility

from astrbot.core.utils.astrbot_path import (
    get_astrbot_root,       # AstrBot root directory
    get_astrbot_data_path,  # Data directory
    get_astrbot_config_path, # Config directory
    get_astrbot_plugin_path, # Plugin directory
    get_astrbot_temp_path,   # Temp directory
    get_astrbot_skills_path, # Skills directory
)

Architecture Patterns

Adding a Platform Adapter

1. Create in astrbot/core/platform/sources/
2. Extend Platform base class
3. Use @register_platform_adapter decorator
4. Implement: run(), convert_message(), meta()

Adding a CLI Command

1. Create in astrbot/cli/commands/
2. Use @click.command()
3. Update astrbot/cli/__main__.py to add command

Adding a Star Handler

1. Create in astrbot/builtin_stars/ or as plugin
2. Extend Star class
3. Use decorators: @star.on_command(), @star.on_schedule(), etc.

Testing

• Test location: tests/ directory
• Framework: pytest with pytest-asyncio
• Run: uv run pytest --cov=astrbot tests/

Git Conventions

Commit Messages (Conventional Commits)

feat: add new feature
fix: resolve bug
docs: update documentation
refactor: restructure code
test: add tests
chore: maintenance

PR Guidelines

• Title: conventional commit format in English
• Target branch: dev
• Keep changes atomic and focused

Important Guidelines

1. No report files - Do not add xxx_SUMMARY.md
2. Componentization - Keep WebUI code clean, avoid duplication
3. Backward compatibility - Add deprecation warnings when changing APIs
4. CLI help - Run astrbot help --all to see all commands

Directory Structure

astrbot/
├── __main__.py          # Main entry point
├── __init__.py          # Package init, exports
├── cli/                 # CLI commands
│   └── commands/        # Individual commands
├── core/                # Core functionality
│   ├── agent/           # Agent execution
│   ├── platform/        # Platform adapters
│   ├── pipeline/        # Message processing
│   ├── star/            # Plugin system
│   └── config/          # Configuration
├── builtin_stars/       # Built-in plugins
├── dashboard/           # Vue.js frontend
└── utils/              # Utilities