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 内对齐数据与动画的状态同步。

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.

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 对应区域）而非入口脚本。

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.