feat: add pool editing UI and agent guidance
This commit is contained in:
271
AGENTS.md
Normal file
271
AGENTS.md
Normal file
@@ -0,0 +1,271 @@
|
||||
# AGENTS.md
|
||||
|
||||
## Purpose
|
||||
|
||||
This repo is a small Python Flask service that converts subscription links (`vmess`, `vless`, `trojan`, `ss`) into local SOCKS5 proxies via `xray-core`.
|
||||
Almost all backend logic, API routes, and the inline web UI live in `main.py`.
|
||||
Agents should prefer minimal, in-place changes over architectural rewrites.
|
||||
|
||||
## Repository Layout
|
||||
|
||||
- `main.py`: app entrypoint, dataclasses, parsers, proxy manager, schedulers, Flask routes, and embedded HTML/CSS/JS.
|
||||
- `requirements.txt`: runtime dependencies.
|
||||
- `start.sh`: local bootstrap script.
|
||||
- `Dockerfile`: image build.
|
||||
- `docker-compose.yml`: recommended container run path.
|
||||
- `config.yaml.example`: optional config sample.
|
||||
- `config/`: persisted JSON state.
|
||||
- `data/`: runtime files such as generated xray configs.
|
||||
- `bin/`: xray binary/assets.
|
||||
|
||||
## Extra Agent Rules
|
||||
|
||||
I checked for repo-specific agent instruction files:
|
||||
|
||||
- `.cursor/rules/`: not present.
|
||||
- `.cursorrules`: not present.
|
||||
- `.github/copilot-instructions.md`: not present.
|
||||
|
||||
There are no Cursor or Copilot rules to merge into this file right now.
|
||||
|
||||
## Environment
|
||||
|
||||
- Python: README says `3.10+`.
|
||||
- Docker image: `python:3.13-slim`.
|
||||
- Default web port: `8080`.
|
||||
- App downloads `xray-core` on startup if `bin/xray` is missing.
|
||||
- Runtime state is persisted under `config/` and `data/`.
|
||||
|
||||
## Setup Commands
|
||||
|
||||
### Local environment
|
||||
|
||||
```bash
|
||||
python3 -m venv venv
|
||||
source venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
### Run locally
|
||||
|
||||
```bash
|
||||
python3 main.py
|
||||
```
|
||||
|
||||
### Run via helper script
|
||||
|
||||
```bash
|
||||
chmod +x start.sh
|
||||
./start.sh
|
||||
```
|
||||
|
||||
### Build Docker image
|
||||
|
||||
```bash
|
||||
docker build -t airtosocks .
|
||||
```
|
||||
|
||||
### Run with Docker Compose
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
docker-compose logs -f
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
## Build, Lint, And Test Reality
|
||||
|
||||
This repository currently has no formal lint or test setup.
|
||||
|
||||
- No `tests/` directory was found.
|
||||
- No `pytest` or `unittest` test files were found.
|
||||
- No `ruff`, `black`, `isort`, `flake8`, `pylint`, `mypy`, `tox`, or `nox` config was found.
|
||||
|
||||
Agents should say this explicitly instead of pretending a missing command exists.
|
||||
|
||||
## Verification Commands That Work Today
|
||||
|
||||
### Syntax check
|
||||
|
||||
```bash
|
||||
python3 -m py_compile main.py
|
||||
```
|
||||
|
||||
### Compile Python files
|
||||
|
||||
```bash
|
||||
python3 -m compileall .
|
||||
```
|
||||
|
||||
### Manual app run
|
||||
|
||||
```bash
|
||||
python3 main.py
|
||||
```
|
||||
|
||||
### HTTP smoke checks
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8080/api/links
|
||||
curl http://127.0.0.1:8080/api/subscriptions
|
||||
curl http://127.0.0.1:8080/api/random
|
||||
```
|
||||
|
||||
### Container smoke checks
|
||||
|
||||
```bash
|
||||
docker-compose up -d
|
||||
curl http://127.0.0.1:8080/api/links
|
||||
docker-compose logs --tail=200
|
||||
docker-compose down
|
||||
```
|
||||
|
||||
## Single-Test Guidance
|
||||
|
||||
There is no real single-test command yet because there is no test suite.
|
||||
|
||||
If tests are added later, prefer `pytest` and document commands like:
|
||||
|
||||
```bash
|
||||
pytest
|
||||
pytest tests/test_parser.py
|
||||
pytest tests/test_parser.py::test_parse_vmess
|
||||
```
|
||||
|
||||
Until then, a “single test” means a targeted manual verification of the exact parser, route, or runtime behavior touched by the change.
|
||||
|
||||
## Config Notes
|
||||
|
||||
Optional runtime config lives in `config.yaml` and currently supports:
|
||||
|
||||
```yaml
|
||||
port: 8080
|
||||
check_interval: 600
|
||||
```
|
||||
|
||||
When changing config behavior:
|
||||
|
||||
- Preserve compatibility for missing keys.
|
||||
- Keep defaults aligned across code, `README.md`, and `config.yaml.example`.
|
||||
- Do not silently rename config fields.
|
||||
|
||||
## Code Style
|
||||
|
||||
The repo does not use an autoformatter today. Match the existing style unless the user asks for cleanup.
|
||||
|
||||
### Imports
|
||||
|
||||
- Keep standard library imports before third-party imports.
|
||||
- Do not reorder the whole import block for cosmetic reasons.
|
||||
- Add new imports near related imports.
|
||||
- Prefer explicit imports over wildcard imports.
|
||||
|
||||
### Formatting
|
||||
|
||||
- Follow normal Python/PEP 8 conventions without broad reformatting.
|
||||
- Use 4-space indentation.
|
||||
- Preserve surrounding quote style; Python code here mostly uses single quotes.
|
||||
- Avoid reflowing large inline HTML, CSS, or JS unless required.
|
||||
- Keep diffs small and local.
|
||||
|
||||
### Types
|
||||
|
||||
- Continue the existing `typing` style: `Optional`, `List`, `Dict`, `Tuple`, `Any`.
|
||||
- Add type hints for new helpers when practical.
|
||||
- Use `@dataclass` for record-like state models.
|
||||
- Do not introduce a new validation or typing framework without a concrete need.
|
||||
|
||||
### Naming
|
||||
|
||||
- `snake_case` for variables, functions, and methods.
|
||||
- `PascalCase` for classes.
|
||||
- `UPPER_SNAKE_CASE` for module constants.
|
||||
- Use descriptive domain names like `subscription_id`, `socks_port`, `last_check`, `available_count`.
|
||||
|
||||
### Data Modeling And Persistence
|
||||
|
||||
- Persist structured state through dataclasses and `asdict(...)`.
|
||||
- New persisted fields need safe defaults so old JSON continues to load.
|
||||
- Consider compatibility with existing files in `config/`.
|
||||
- Do not casually rename persisted fields.
|
||||
|
||||
### Error Handling
|
||||
|
||||
- Follow the existing pattern: catch failures near parsing, file I/O, network calls, and subprocess operations.
|
||||
- Use `logger.error(...)` or `logger.warning(...)`, then return a safe fallback or JSON error.
|
||||
- Avoid crashing daemon threads for recoverable problems.
|
||||
- Prefer specific exceptions when obvious, but broad `except Exception as e` is already common here.
|
||||
- API handlers should return meaningful JSON error payloads with sensible HTTP status codes.
|
||||
|
||||
### Logging
|
||||
|
||||
- Use the module-level `logger`, not `print`.
|
||||
- Keep log messages short and operational.
|
||||
- Include useful identifiers such as node name, subscription name, or port.
|
||||
- Do not log secrets or full credentials from proxy links unless absolutely necessary.
|
||||
|
||||
### Concurrency And Shared State
|
||||
|
||||
- `ProxyManager` protects mutable state with `threading.RLock`; preserve that discipline.
|
||||
- Be careful when changing `nodes`, `subscriptions`, `pools`, `used_ports`, or `xray_processes`.
|
||||
- Keep background threads daemonized when matching the current pattern.
|
||||
- Do not introduce async or heavier concurrency models for small tasks.
|
||||
|
||||
### Files, Processes, And Runtime Data
|
||||
|
||||
- Runtime files belong under `config/` or `data/`.
|
||||
- Keep xray config generation deterministic and JSON-serializable.
|
||||
- Follow the existing `subprocess.Popen(...)` pattern for xray processes.
|
||||
- Release ports and clean up subprocess state on failure paths.
|
||||
|
||||
### Flask And API Conventions
|
||||
|
||||
- Keep Flask route handlers thin.
|
||||
- Put behavior in `ProxyManager` or small helpers rather than in the route body.
|
||||
- Return `jsonify(...)` for API responses.
|
||||
- Validate request JSON defensively.
|
||||
- Keep API response shapes stable unless a breaking change is explicitly requested.
|
||||
|
||||
### Frontend Conventions
|
||||
|
||||
- The frontend is intentionally inline inside the `/` route.
|
||||
- For small UI changes, edit the embedded HTML/JS directly instead of adding a frontend build system.
|
||||
- Preserve the current fetch-based interaction pattern.
|
||||
- Keep the existing visual language unless the task asks for redesign work.
|
||||
|
||||
### Comments And Docs
|
||||
|
||||
- Existing comments/docstrings are short and often Chinese; match the surrounding language in touched code.
|
||||
- Add comments only when behavior is not obvious from the code.
|
||||
- Update `README.md`, `config.yaml.example`, and this file when commands or behavior change.
|
||||
|
||||
## Change Strategy For Agents
|
||||
|
||||
- Prefer surgical edits.
|
||||
- Avoid splitting `main.py` into modules unless explicitly requested.
|
||||
- Respect persisted data compatibility.
|
||||
- Ignore unrelated runtime files unless the task specifically involves them.
|
||||
- If you add tests or lint tooling, immediately document the new commands here.
|
||||
|
||||
## Recommended Post-Change Checks
|
||||
|
||||
For most Python-only changes:
|
||||
|
||||
```bash
|
||||
python3 -m py_compile main.py
|
||||
```
|
||||
|
||||
For API behavior changes:
|
||||
|
||||
1. Start the app with `python3 main.py`.
|
||||
2. Hit the affected endpoint with `curl`.
|
||||
3. Confirm there is no traceback and the response shape is correct.
|
||||
|
||||
For Docker-related changes:
|
||||
|
||||
```bash
|
||||
docker build -t airtosocks .
|
||||
docker-compose up -d
|
||||
curl http://127.0.0.1:8080/api/links
|
||||
docker-compose down
|
||||
```
|
||||
Reference in New Issue
Block a user