Repository Guidelines

Project Structure & Module Organization

main.py runs the CLI agent; web_server.py serves the Flask/SocketIO UI from static/.
core/ contains terminal orchestration (main_terminal.py, web_terminal.py) and should stay I/O-light.
modules/ collects reusable capabilities (file/search/memory/terminal); extend here before touching entrypoints.
utils/ provides API clients, context helpers, and logging; import from here instead of adding globals.
prompts/, data/, and project/ bundle prompt templates, fixtures, and demos used primarily for reference.
test/ stores integration helpers (api_interceptor_server.py, test_deepseek_output.py); add new suites alongside them.

pip install -r requirements.txt installs Python dependencies.
python main.py launches the CLI agent loop.
python web_server.py serves the web UI at http://localhost:8091.
python test/api_interceptor_server.py starts the mock proxy that logs traffic to api_logs/.
python test_deepseek_output.py exercises streaming tool-calls; populate config.py with valid API credentials first.

Target Python 3.8+, 4-space indentation, snake_case functions, and PascalCase classes.
Add type hints and concise docstrings that follow the existing bilingual tone.
Use utils.logger.setup_logger for diagnostics; reserve print for intentional terminal output.
Keep modules focused: add new features in dedicated modules/ files with descriptive names.

Prefer pytest for automation and name files test/test_<feature>.py, reusing assets in data/ when relevant.
For network flows, run python test/api_interceptor_server.py and point the app to the proxy to avoid external calls.
Capture manual verification steps in PRs and add replay scripts under test/ for repeated workflows.

With no history yet, adopt Conventional Commits (feat:, fix:, refactor:) and keep summaries under 72 characters.
Squash iterative commits; PRs should outline changes, touched modules, and validation.
Link issues and attach UI captures or log snippets when behavior shifts.

Keep real API keys out of git; override defaults via environment variables.
Clean sensitive data from api_logs/, logs/, and experiment_outputs/ before sharing.
Extend .gitignore when new tooling produces temporary artifacts.