# 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.