AstrBot/AGENTS.md at 987099d4cb67a7ba3dc36605b4378bb77bd7dee3

fz-mirrors/AstrBot

Fork 0

mirror of https://github.com/AstrBotDevs/AstrBot synced 2026-07-16 01:40:15 +08:00

Files

LIghtJUNction 987099d4cb chore: merge origin/master into dev

2026-05-19 21:15:22 +08:00

8.2 KiB

Raw Blame History

Setup commands

Core

uv tool install -e . --force
astrbot init
astrbot run # start the bot 
astrbot run --backend-only # start the backend only

Exposed an API server on http://localhost:6185 by default.

Dashboard(WebUI)

cd dashboard
bun install # First time only.
bun dev

Runs on http://localhost:3000 by default.

Pre-commit setup

AstrBot uses pre-commit hooks to automatically format and lint Python code before each commit. The hooks run ruff check, ruff format, and pyupgrade (see .pre-commit-config.yaml for details).

To set it up:

pip install pre-commit
pre-commit install

After installation, the hooks will run automatically on git commit. You can also run them manually at any time:

ruff format .
ruff check .

Note: If you use VSCode, install the Ruff extension for real-time formatting and linting in the editor.

Dev environment tips

Main entry: astrbot/__main__.py or via 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 frontend)

File Organization

astrbot/
├── __main__.py          # Main entry point
├── __init__.py          # Package init, exports
├── cli/                 # CLI commands
│   └── commands/        # Individual command modules
├── 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

Architecture

Core Components

astrbot/core/ - Core bot functionality
astrbot/core/platform/ - Platform adapter system
astrbot/core/agent/ - Agent execution logic
astrbot/core/star/ - Plugin/Star handler system
astrbot/core/pipeline/ - Message processing pipeline
astrbot/cli/ - Command-line interface

Important Utilities

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
)

Platform Adapters

Platform adapters are in astrbot/core/platform/sources/:

Each adapter extends base platform classes
Use @register_platform_adapter decorator
Events flow through commit_event() to message queue

Star (Plugin) System

Stars are plugins in astrbot/builtin_stars/:

Extend Star base class
Use decorators for command handlers: @star.on_command, @star.on_message, etc.
Access via context object

Code Style

Type hints required - Use Python 3.12+ syntax:
- list[str] not List[str]
- int | None not Optional[int]
- Avoid Any when possible. Use proper TypedDict, dataclass, or Protocol instead.
- When encountering dict access issues (e.g., msg.get("key") where type inference is wrong), define a TypedDict with total=False to explicitly declare allowed keys.
Good example:
```
class MessageComponent(TypedDict, total=False):
    type: str
    text: str
    path: str
```
Bad example (avoid):
```
msg: Any = something
msg = cast(dict, msg)
```

Path handling - Always use pathlib.Path:

from pathlib import Path
# Use astrbot.core.utils.path_utils for data/temp directories
from astrbot.core.utils.path_utils import get_astrbot_data_path

Formatting - Run before committing:
```
ruff format .
ruff check .
```
Comments - Use English for all comments and docstrings
Imports - Use absolute imports via astrbot. prefix

Environment Variables

When adding new environment variables:

Use ASTRBOT_ prefix: ASTRBOT_ENABLE_FEATURE
Add to .env.example with description
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

Testing

Tests go in tests/ directory
Use pytest with pytest-asyncio
Run: uv sync --group dev && uv run pytest --cov=astrbot tests/
Test files: test_*.py or *_test.py

Code Quality Scoring Test

The project enforces a code quality score via tests/test_code_quality_typing.py. All agents must treat this as a hard constraint when modifying code.

Run the test:

uv run pytest tests/test_code_quality_typing.py -v

Scoring rules (target: 100/100, threshold for PASS: 80/100):

Pattern	Cost
`cast(Any, ...)`	-1 pt each
`# type: ignore`	-0.5 pt each
BAD `# type: ignore[...]` (unresolved-import, class-alias, no-name-module, attr-defined, etc.)	-3 pt each
`bare except:` (no exception type)	-0.5 pt each
Duplicate code block (5+ identical lines, ≥2 occurrences)	-2 pt each

Why bad type: ignore is heavily penalized:

# type: ignore[unresolved-import] — hides missing module/stub issues
# type: ignore[class-alias] — hides improper type alias patterns
# type: ignore[attr-defined] — hides missing attribute errors
These are workarounds, not fixes — they paper over real type errors

Scoring formula:

score = max(0, 100 - cast_any - type_ignore*0.5 - bad_type_ignore*3 - bare_except*0.5 - dup_blocks*2)

Agent rules when modifying code:

Do not add # type: ignore[unresolved-import] or # type: ignore[class-alias] — fix the underlying issue instead
Do not use cast(Any, ...) to suppress type errors — use proper type annotations
Do not add bare except: clauses — use except SomeSpecificException:
Do not copy-paste 5+ line blocks — extract to a shared helper function
Before committing, run the scoring test and ensure score ≥ 80

Git Conventions

Commit Messages

Use conventional commits:

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

PR Guidelines

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

Project-Specific Guidelines

No report files - Do not add xxx_SUMMARY.md or similar
Componentization - Maintain clean code, avoid duplication in WebUI
Backward compatibility - When deprecating, add warnings
CLI help - Run astrbot help --all to see all commands
When modifying frontend/dashboard code, use the project's custom request module @/utils/request for HTTP calls
For fetch or SSE URLs, use resolveApiUrl('/api/your-path') so the configured VITE_API_BASE and dev proxy rules are respected
Do not import the plain axios package directly in dashboard source files

Common Tasks

Adding a new platform adapter

Create adapter in astrbot/core/platform/sources/
Extend Platform base class
Use @register_platform_adapter decorator
Implement required methods: run(), convert_message(), meta()

Adding a new command

Add to appropriate module in cli/commands/
Register with @click.command()
Update astrbot/cli/__main__.py to add command

Adding a new Star handler

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

Release versions

Replace current version name to specific version name.
Write changelog in changelogs/, you can refer to the full commit messages between the latest tag to the latest commit.
Make and push a commit into master branch with message format like: chore: bump version to 4.25.0
Create a tag and push the tag. For example: git tag v4.25.0 && git push origin v4.25.0

8.2 KiB Raw Blame History