Imported from roketskiy/astrbot_plugin_rocomerchant (AGENTS.md). Install upstream with npx skills add roketskiy/astrbot_plugin_rocomerchant. Copyright stays with the author.

Repository Guidelines

Project Structure & Module Organization

This repository is an AstrBot plugin for merchant queries and scheduled notifications. main.py contains the plugin entry point, command handlers, persistence, HTTP requests, and scheduling. Keep data normalization, Beijing-time calculations, snapshot I/O, and message rendering in merchant_data.py. Use fetch_merchant.py for standalone source verification without AstrBot. Configuration is declared in _conf_schema.json; plugin metadata and compatibility live in metadata.yaml. Generated snapshots belong under data/ and are ignored by Git. Design and audit material is under docs/.

Build, Test, and Development Commands

Use Python 3.12, matching the supported runtime.

python -m pip install -r requirements.txt
python -m compileall main.py merchant_data.py fetch_merchant.py
python fetch_merchant.py --timeout 10

The first command installs httpx; the second catches syntax errors; the third fetches and normalizes live data into data/latest.json. Full plugin behavior must also be checked by loading the repository as AstrBot/data/plugins/astrbot_plugin_rocomerchant in AstrBot 4.9.2 or newer (but below 5).

Coding Style & Naming Conventions

Follow PEP 8 with four-space indentation and type hints. Use snake_case for modules, functions, variables, and configuration keys; PascalCase for classes; and UPPER_SNAKE_CASE for constants. Keep asynchronous I/O explicit with async/await. Prefer standard-library utilities and existing helpers in merchant_data.py over new abstractions. Preserve concise Chinese user-facing messages and log context. No formatter or linter is configured, so keep imports grouped as standard library, third-party, then AstrBot/local modules.

Testing Guidelines

There is currently no automated test suite or coverage threshold. Run both compilation and the standalone fetch check for every change. For new branching normalization or scheduling logic, add focused standard-library tests under tests/test_<module>.py, name methods test_<behavior>, and run:

python -m unittest discover -s tests -p "test_*.py"

Mock network and time boundaries; do not make unit tests depend on the live API.

Commit & Pull Request Guidelines

Recent commits use short imperative subjects such as Harden merchant fetches and sanitize payloads; releases use Release vX.Y.Z. Keep each commit scoped to one behavior. Pull requests should explain the user-visible change, list verification commands, and link relevant issues. Include sample output or screenshots when commands or rendered messages change. When adding configuration, update _conf_schema.json, runtime parsing, defaults, and README documentation together.

Security & Configuration Tips

Treat API payloads and saved session identifiers as untrusted. Preserve response-size limits, text sanitization, timeouts, and fallback handling. Never commit generated snapshots, credentials, tokens, or production conversation identifiers.