{"owner":"AstrBotDevs","repo":"AstrBot","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":[".github/copilot-instructions.md","AGENTS.md"],"files":{".github/copilot-instructions.md":"# AstrBot Development Instructions\n\nAstrBot is a multi-platform LLM chatbot and development framework written in Python with a Vue.js dashboard. It supports multiple messaging platforms (QQ, Telegram, Discord, etc.) and various LLM providers (OpenAI, Anthropic, Google Gemini, etc.).\n\nAlways reference these instructions first and fallback to search or bash commands only when you encounter unexpected information that does not match the info here.\n\n## Working Effectively\n\n### Bootstrap and Install Dependencies\n- **Python 3.10+ required** - Check `.python-version` file\n- Install UV package manager: `pip install uv`\n- Install project dependencies: `uv sync` -- takes 6-7 minutes. NEVER CANCEL. Set timeout to 10+ minutes.\n- Create required directories: `mkdir -p data/plugins data/config data/temp`\n\n### Running the Application\n- Run main application: `uv run main.py` -- starts in ~3 seconds\n- Application creates WebUI on http://localhost:6185 (default credentials: `astrbot`/`astrbot`)\n\n### Dashboard Build (Vue.js/Node.js)\n- **Prerequisites**: Node.js 20+ and npm 10+ required\n- Navigate to dashboard: `cd dashboard`\n- Install dashboard dependencies: `npm install` -- takes 2-3 minutes. NEVER CANCEL. Set timeout to 5+ minutes.\n- Build dashboard: `npm run build` -- takes 25-30 seconds. NEVER CANCEL.\n- Dashboard creates optimized production build in `dashboard/dist/`\n\n### Testing\n- Do not generate test files for now.\n\n### Code Quality and Linting\n- Install ruff linter: `uv add --dev ruff`\n- Check code style: `uv run ruff check .` -- takes <1 second\n- Check formatting: `uv run ruff format --check .` -- takes <1 second\n- Fix formatting: `uv run ruff format .`\n- **ALWAYS** run `uv run ruff check .` and `uv run ruff format .` before committing changes\n\n### Plugin Development\n- Plugins load from `astrbot/builtin_stars/` (built-in) and `data/plugins/` (user-installed)\n- Plugin system supports function tools and message handlers\n- Key plugins: python_interpreter, web_searcher, astrbot, reminder, session_controller\n\n### Common Issues and Workarounds\n- **Dashboard download fails**: Known issue with \"division by zero\" error - application still works\n- **Import errors in tests**: Ensure `uv run` is used to run tests in proper environment\n=- **Build timeouts**: Always set appropriate timeouts (10+ minutes for uv sync, 5+ minutes for npm install)\n\n## CI/CD Integration\n- GitHub Actions workflows in `.github/workflows/`\n- Docker builds supported via `Dockerfile`\n- Pre-commit hooks enforce ruff formatting and linting\n\n## Docker Support\n- Primary deployment method: `docker run soulter/astrbot:latest`\n- Compose file available: `compose.yml`\n- Exposes ports: 6185 (WebUI), 6195 (WeChat), 6199 (QQ), etc.\n- Volume mount required: `./data:/AstrBot/data`\n\n## Multi-language Support\n- Documentation in Chinese (README.md), English (README_en.md), Japanese (README_ja.md)\n- UI supports internationalization\n- Default language is Chinese\n\nRemember: This is a production chatbot framework with real users. Always test thoroughly and ensure changes don't break existing functionality.\n","AGENTS.md":"## Setup commands\n\n### Core\n\n```\nuv sync\nuv run main.py\n```\n\nExposed an API server on `http://localhost:6185` by default.\n\n### Dashboard(WebUI)\n\n```\ncd dashboard\npnpm install # First time only. Use npm install -g pnpm if pnpm is not installed.\npnpm dev\n```\n\nRuns on `http://localhost:3000` by default.\n\n## Pre-commit setup\n\nAstrBot uses [pre-commit](https://pre-commit.com/) 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`](.pre-commit-config.yaml) for details).\n\nTo set it up:\n\n```bash\npip install pre-commit\npre-commit install\n```\n\nAfter installation, the hooks will run automatically on `git commit`. You can also run them manually at any time:\n\n```bash\nruff format .\nruff check .\n```\n\n> **Note:** If you use VSCode, install the `Ruff` extension for real-time formatting and linting in the editor.\n\n## Dev environment tips\n\n### Basic\n\n1. When modifying the WebUI, be sure to maintain componentization and clean code. Avoid duplicate code.\n2. Do not add any report files such as xxx_SUMMARY.md.\n3. After finishing, use `ruff format .` and `ruff check .` to format and check the code.\n4. When committing, ensure to use conventional commits messages, such as `feat: add new agent for data analysis` or `fix: resolve bug in provider manager`.\n5. Use **English** for all comments and logs.\n6. 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.\n7. When backend API routes, request/response schemas, or OpenAPI definitions change, regenerate the frontend API client by running `cd dashboard && pnpm generate:api`.\n8. When updating the project version, keep `[project].version` in `pyproject.toml` and `__version__` in `astrbot/__init__.py` in sync. `VERSION` in `astrbot/core/config/default.py` should derive from `astrbot.__version__` instead of hardcoding a separate version string.\n9. When designing WebUI dialogs, use `text-h3 pa-4 pb-0 pl-6` as the base class for dialog titles, and use `variant=\"text\"` or `variant=\"tonal\"` for dialog buttons.\n10. Consider cross-platform compatibility (e.g., Windows, macOS, and Linux, as well as Arm64 and x86 CPU architectures) and compatibility with Python 3.10+.\n\n### KISS and First Principles\n\nFollow the KISS principle and reason from first principles during development. Start by identifying the real problem, required behavior, and smallest useful change before adding code. Do not pile on features, configuration switches, abstractions, dependencies, or compatibility layers unless they directly solve the current problem and have clear evidence of need.\n\nPrefer the simplest implementation that is correct, maintainable, and consistent with the existing codebase. If a broader design seems attractive, reduce it to the essential behavior needed now and leave optional expansion for a later, explicit requirement.\n\n### No Unnecessary Helpers\n\nPrioritize inline implementation over abstraction. Avoid over-engineering and do not create helper functions unless absolutely necessary.\n\n1. **Inline-First Rule**: If a logic block can be implemented directly within the main function without breaking overall readability, **do not** extract it into a new helper function.\n2. **Strict Justification for Helpers**: You may only create a separate helper function if it meets at least one of these criteria:\n   - **High Reuse**: The exact same logic is repeated across **3 or more** different locations.\n   - **Extreme Complexity**: Inlining the logic makes the main function too long (e.g., >50 lines) or severely derails the main execution flow.\n3. **No Fragmentation**: Do not split continuous linear logic (e.g., a single API call, simple form validation, or one-time data formatting) into tiny functions just for the sake of \"clean code.\"\n4. **Keep Context Compact**: Handle edge cases, error catching, and logging directly inside the main function block instead of offloading them.\n5. **Refactoring Constraint**: When modifying existing code, do not alter the current function structure or extract code into new helpers unless the existing code already violates the complexity or reuse rules above.\n\n### Mandatory Google-Style Docstrings\n* **Comment the complex**: Add clear comments to any non-obvious function, method, or parameter.\n* **Google Format**: All docstrings must strictly use the Google format (`Args:`, `Returns:`, `Raises:`).\n\n#### Example:\n\n```py\ndef calculate_metrics(user_id: int, force_refresh: bool = False) -> dict:\n    \"\"\"Brief description of the function.\n\n    Args:\n        user_id: Description of the ID.\n        force_refresh: Description of the flag.\n\n    Returns:\n        Description of the returned dict.\n\n    Raises:\n        ValueError: Description of when this occurs.\n    \"\"\"\n    # Inline implementation here...\n```\n\n\n## PR instructions\n\n1. Title format: use conventional commit messages\n2. Use English to write PR title and descriptions.\n\n## Release versions\n\nUse a short-lived `release/*` branch for each release. The release branch is the stabilization area for version bumps, changelog updates, release-blocking fixes, and final validation only. Do not add unrelated features or broad refactors to a release branch.\n\nPrepare a release from a clean worktree with:\n\n```bash\nuv run python scripts/prepare_release.py 4.25.0\n```\n\nThe script updates `pyproject.toml` and `astrbot/__init__.py`, creates `changelogs/v4.25.0.md`, runs the required Python checks, and prints the remaining steps. Use these flags when needed:\n\n```bash\nuv run python scripts/prepare_release.py 4.25.0 --generate-api-client\nuv run python scripts/prepare_release.py 4.25.0 --dashboard-build\nuv run python scripts/prepare_release.py 4.25.0 --commit --push\n```\n\nOpen a PR from `release/4.25.0` to `master`. The PR title must use the conventional commit format, for example `chore: bump version to 4.25.0`. After the release PR is merged, create and push the tag from the updated `master` branch so the tag points to the exact code that was merged:\n\n```bash\ngit checkout master\ngit pull --ff-only origin master\ngit tag v4.25.0\ngit push origin v4.25.0\n```\n\nFor one-off release candidate branches, delete the release branch after the tag is pushed and verified. For maintained release lines, use a branch such as `release/4.25` and keep it until that line reaches EOL.\n\n```bash\ngit branch -d release/4.25.0\ngit push origin --delete release/4.25.0\n```\n"}}