From 6126430a3ea010eda156fc78305db6031130bceb Mon Sep 17 00:00:00 2001 From: yiekheng Date: Sat, 2 May 2026 17:03:33 +0800 Subject: [PATCH] docs(agents): document the local-as-dev tier and bot CLI --- AGENTS.md | 52 +++++++++++++++++++++------------------------------- 1 file changed, 21 insertions(+), 31 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a2a0061..3c7bd8a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,38 +30,28 @@ TELEGRAM_ALERT_BOT_TOKEN= CM_TRANSFER_MAX_THREADS=1 ``` -4. Prepare MySQL schema (minimum required): - ```sql - CREATE DATABASE rex_cm CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; - USE rex_cm; - - CREATE TABLE acc ( - username VARCHAR(64) PRIMARY KEY, - password VARCHAR(128) NOT NULL, - status VARCHAR(32) DEFAULT '', - link VARCHAR(512) DEFAULT '' - ); - - CREATE TABLE user ( - f_username VARCHAR(64) PRIMARY KEY, - f_password VARCHAR(128) NOT NULL, - t_username VARCHAR(64) NOT NULL, - t_password VARCHAR(128) NOT NULL, - last_update_time TIMESTAMP NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP - ); - ``` -5. Seed at least one `acc.username` matching prefix `13c...` (required by `CM_BOT_HAL.get_next_username()`), for example: - ```sql - INSERT INTO acc (username, password, status, link) VALUES ('13c1000', 'seed', '', ''); - ``` -6. Configure DB connection values: - - Default fallback is hardcoded in `app/db.py` (`DB_HOST=192.168.0.210`, etc.). - - For reliable reproduction, add `DB_HOST`, `DB_USER`, `DB_PASSWORD`, `DB_NAME`, `DB_PORT` to service `environment:` in compose files (at minimum `api-server`, `telegram-bot`, `transfer-bot`). -7. Start services locally: +4. Prepare the local dev DB and stack: ```bash - docker compose -f docker-compose.yml -f docker-compose.override.yml up --build + cp envs/dev/.env.example .env + # Edit .env if you want the bot CLI to actually call cm99.net + # (CM_AGENT_ID / CM_AGENT_PASSWORD / CM_SECURITY_PIN). + bash scripts/dev.sh up ``` - Or run `bash scripts/local_build.sh` (uses `sudo` by default). + This brings up `mysql` (port `127.0.0.1:3306`), `api-server`, and + `web-view`. The schema and a 4-row seed are applied automatically + from `docker/mysql/init.d/`. Bots (`telegram-bot`, `transfer-bot`) + are gated behind a compose `bots` profile and do not start in dev. + +## Dev Tier (Local Development) +- Lifecycle: `bash scripts/dev.sh {up,down,reset-db,logs,status}`. +- Bot CLI: `bash scripts/bot_cli.sh` (drops into the TUI menu) or + `bash scripts/bot_cli.sh ` (e.g., `register`, `set-pin `, + `monitor-once --target 5`). The CLI runs in your local `.venv` and + connects to the dev mysql at `127.0.0.1:3306`. +- The auto-create monitor does NOT run in dev (it lives in `telegram-bot`, + which is gated by the `bots` profile). Use `bot_cli.sh monitor-once` to + exercise the same code path manually. +- Tests: `.venv/bin/python -m unittest tests.test_debug_enabled tests.test_bot_cli -v`. ## Build, Test, and Development Commands - `python3 -m venv .venv && source .venv/bin/activate && pip install -r requirements.txt`: optional non-Docker local env. @@ -71,7 +61,7 @@ ## Verification Checklist - API responds: `curl http://localhost:3000/acc/` -- Web UI loads: open `http://localhost:8001` +- Web UI loads: open `http://localhost:8000` (dev) or `http://localhost:8001` (rex prod) / `http://localhost:8005` (siong prod). - Service logs are clean: ```bash docker compose logs -f api-server web-view telegram-bot transfer-bot