77 lines
3.3 KiB
Markdown
77 lines
3.3 KiB
Markdown
|
# DeepAudit Agent Instructions
|
||
|
|
|
||
|
|
This guide provides essential technical information for agentic coding tools operating within the DeepAudit repository.
|
||
|
|
|
||
|
|
## 🛠 Development Commands
|
||
|
|
|
||
|
|
### Backend (Python/FastAPI)
|
||
|
|
Located in `/backend`. Uses `uv` for environment management and `pytest` for testing.
|
||
|
|
|
||
|
|
- **Sync Environment:** `uv sync`
|
||
|
|
- **Start Server:** `uvicorn app.main:app --reload`
|
||
|
|
- **Run All Tests:** `pytest`
|
||
|
|
- **Run Agent Tests:** `python tests/agent/run_tests.py`
|
||
|
|
- **Run Single Test:** `pytest tests/agent/test_agents.py::test_name`
|
||
|
|
- **Linting:** `ruff check .`
|
||
|
|
- **Formatting:** `black .`
|
||
|
|
- **Type Checking:** `mypy .`
|
||
|
|
- **Database Migrations:** `alembic upgrade head`
|
||
|
|
|
||
|
|
### Frontend (React/TypeScript)
|
||
|
|
Located in `/frontend`. Uses `pnpm` and `Vite`.
|
||
|
|
|
||
|
|
- **Install Dependencies:** `pnpm install`
|
||
|
|
- **Start Dev Server:** `pnpm dev`
|
||
|
|
- **Build Project:** `pnpm build`
|
||
|
|
- **Linting:** `pnpm lint`
|
||
|
|
- **Format:** `pnpm format`
|
||
|
|
- **Type Checking:** `pnpm type-check`
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🎨 Code Style & Conventions
|
||
|
|
|
||
|
|
### General
|
||
|
|
- **Language:** English for code (variables, functions, comments), though some documentation/logs may be in Chinese.
|
||
|
|
- **Architecture:** Follow the Multi-Agent architecture. Backend logic for agents is in `backend/app/agents/`.
|
||
|
|
|
||
|
|
### Backend (Python)
|
||
|
|
- **Style:** PEP 8 via `black` (100 char limit) and `ruff`.
|
||
|
|
- **Typing:** Strict type hinting is required. Use Pydantic models for data validation in `backend/app/schemas/`.
|
||
|
|
- **Imports:**
|
||
|
|
- Standard library first.
|
||
|
|
- Third-party libraries second.
|
||
|
|
- Local application imports last (using `app.xxx` absolute paths).
|
||
|
|
- **Naming:** `snake_case` for variables/functions, `PascalCase` for classes.
|
||
|
|
- **Error Handling:** Use custom exceptions where appropriate. FastAPI's `HTTPException` for API responses. Prefer `logger.error` over `print`.
|
||
|
|
- **Database:** SQLAlchemy 2.0 (async). Models in `backend/app/models/`.
|
||
|
|
|
||
|
|
### Frontend (React/TypeScript)
|
||
|
|
- **Framework:** React 18+ with Vite and TypeScript.
|
||
|
|
- **State Management:** Zustand for stores.
|
||
|
|
- **UI Components:** Shadcn/UI (Radix UI) + Tailwind CSS.
|
||
|
|
- **Structure:**
|
||
|
|
- `src/features/`: Domain-specific components and logic.
|
||
|
|
- `src/components/ui/`: Shared low-level components.
|
||
|
|
- `src/shared/`: Cross-cutting concerns (hooks, types, utils, api).
|
||
|
|
- **Types:** Define interfaces in `src/shared/types/index.ts`. Avoid `any`.
|
||
|
|
- **Imports:** Use absolute paths (e.g., `@/components/...` if configured, otherwise relative to `src`).
|
||
|
|
- **Naming:** `PascalCase` for components, `camelCase` for hooks and utilities.
|
||
|
|
- **Formatting:** Use Biome for linting and formatting.
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 🤖 Agent Framework specifics
|
||
|
|
- **Core Agents:** Orchestrator, Recon, Analysis, Verification.
|
||
|
|
- **Tools:** Agents use specialized tools (e.g., `sandbox_exec` for PoC verification, `semgrep_scan`, `rag_query`).
|
||
|
|
- **Sandbox:** PoC execution happens in isolated Docker containers (`docker/sandbox`).
|
||
|
|
- **RAG:** Uses ChromaDB for vector storage and Tree-sitter for intelligent code chunking.
|
||
|
|
- **Agent Logic:** Implementation resides in `backend/app/services/agent/agents/` and tools in `backend/app/services/agent/tools/`.
|
||
|
|
|
||
|
|
## 📁 Repository Structure
|
||
|
|
- `backend/app/agents/`: Agent logic.
|
||
|
|
- `backend/app/api/`: API endpoints.
|
||
|
|
- `frontend/src/features/`: Frontend modules.
|
||
|
|
- `docker/`: Deployment and sandbox configurations.
|
||
|
|
- `rules/`: Custom audit rules.
|