## 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.

## Dev environment tips

1. When modifying the WebUI, be sure to maintain componentization and clean code. Avoid duplicate code.
2. Do not add any report files such as xxx_SUMMARY.md.
3. After finishing, use `ruff format .` and `ruff check .` to format and check the code.
4. When committing, ensure to use conventional commits messages, such as `feat: add new agent for data analysis` or `fix: resolve bug in provider manager`.
5. Use English for all new comments.
6. For path handling, use `pathlib.Path` instead of string paths, and use `astrbot.core.utils.path_utils` to get the AstrBot data and temp directory.
7. Use Python 3.12+ type hinting syntax (e.g., `list[str]` over `List[str]`, `int | None` over `Optional[int]`). Avoid using `Any` and `cast()` - use proper TypedDict, dataclass, or Protocol instead. When encountering dict access issues (e.g., `msg.get("key")` where ty infers wrong type), define a TypedDict with `total=False` to explicitly declare allowed keys.

   Good example:
   ```python
   class MessageComponent(TypedDict, total=False):
       type: str
       text: str
       path: str
   ```

   Bad example (avoid):
   ```python
   msg: Any = something
   msg = cast(dict, msg)
   ```
8. When introducing new environment variables:
   - Use the `ASTRBOT_` prefix for naming (e.g., `ASTRBOT_ENABLE_FEATURE`).
   - Add the variable and description to `.env.example`.
   - Update `astrbot/cli/commands/cmd_run.py`:
     - Add to the module docstring under "Environment Variables Used in Project".
     - Add to the `keys_to_print` list in the `run` function for debug output.
9. To check all available CLI commands and their usage recursively, run `astrbot help --all`.
10. uv sync --group dev && uv run pytest --cov=astrbot tests/

## PR instructions

1. Title format: use conventional commit messages
2. Use English to write PR title and descriptions.

---

Agent reminder (important)
- When implementing or modifying frontend/dashboard code, always use the project's custom request module `@/utils/request` for HTTP calls (import it as `import axios, { resolveApiUrl } from '@/utils/request'`).
- 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 — using the custom request wrapper ensures baseURL normalization, Authorization and Accept-Language headers, and consistent timeout/interceptors across the app.