38 lines
2.5 KiB
Markdown
38 lines
2.5 KiB
Markdown
# 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.
|
|
|
|
## Build, Test, and Development Commands
|
|
- `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.
|
|
|
|
## Coding Style & Naming Conventions
|
|
- 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.
|
|
|
|
## Testing Guidelines
|
|
- 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.
|
|
|
|
## Commit & Pull Request Guidelines
|
|
- 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.
|
|
|
|
## Security & Configuration Tips
|
|
- 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.
|