40 lines
2.9 KiB
Markdown
40 lines
2.9 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.
|
||
- 前端：`static/src/components/chat/monitor` 是虚拟显示器动画层；涉及新场景请在 `MonitorDirector`/`monitor store` 内对齐数据与动画的状态同步。
|
||
|
||
## 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.
|
||
- `npm install` then `npm run build` builds the Vue frontend to `static/dist`; `npm run dev` watches; `npm run lint` for TS/Vue linting.
|
||
|
||
## Coding Style & Naming Conventions
|
||
- Target Python 3.11+, 4-space indentation, `snake_case` functions, and `PascalCase` classes.
|
||
- TypeScript 5 / Vue 3 单文件组件，保持 `<script setup lang="ts">` 风格；新增资源放入 `static/src` 对应子目录。
|
||
- Add type hints和简短双语 docstring；日志统一用 `utils.logger.setup_logger`，仅在需要时使用 `print`。
|
||
- 模块聚焦：新增能力优先放 `modules/`（或 `static/src/components/chat/monitor` 对应区域）而非入口脚本。
|
||
|
||
## 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.
|