Argus

# Argus — AI Code Review Agent <img width="1536" height="1024" alt="image" src="https://github.com/user-attachments/assets/5bfe4c95-28ac-454d-b7ae-bce1ae1bcbec" /> AI code review platform based on Spring Boot 3 + Spring AI + Vue 3. Supports manual submission of diff, local repository review, and **GitLab / GitHub / Gitee Webhook automatic trigger + PR line-level comment writeback** (unified VcsProvider adaptation layer). Built-in Finder-Verifier two-stage false positive governance, JavaParser context enhancement, AI scoring and commenting, **developer profile (including AI growth suggestions)**, evaluation set quality quantification, statistical dashboard, MCP Server and IM notification. > Roadmap fully landed, single command can run (embedded H2, no external middleware dependency). > Real model test: evaluation set recall rate 100%, accuracy 75% (Verifier not enabled baseline). ## System Architecture  ## Functional Overview and Core Architecture ### 1. End-to-End Workflow ``` ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ 1. Triggers │ │ ┌───────────────────────┐ ┌─────────────────────────────────────────┐ ┌──────────────────┐ │ │ │ Manual diff submission / │ │ GitLab / GitHub / Gitee Webhook │ │ MCP Server │ │ │ │ Local Git repository reference │ │ (verification ➔ asynchronous queue ➔ task merging ➔ idempotent deduplication) │ │ (Claude/Cursor) │ │ │ └───────────┬───────────┘ └────────────────────┬────────────────────┘ └────────┬─────────┘ │ └──────────────┼────────────────────────────────────┼─────────────────────────────────┼────────────┘ │ │ │ └────────────────────────────────────┼─────────────────────────────────┘ ▼ ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ 2. Core Review Engine (Pipeline) │ │ │ │ ┌────────────────────────┐ ┌────────────────────────┐ ┌────────────────────────────────┐ │ │ │ UnifiedDiffParser │ ➔ │ ReviewFileFilter │ ➔ │ ContextEnhancer │ │ │ │ (diff/line number double coordinate parsing) │ │ (large file/type whitelist/blacklist) │ │ (JavaParser AST complete method extraction) │ │ │ └────────────────────────┘ └────────────────────────┘ └────────────────────────────────┘ │ │ │ │ │ ┌────────────────────────┐ ┌────────────────────────┐ ┌────────────────┘ │ │ │ Finder (main AI model) │ ➔ │ Verifier (review AI) │ ➔ │ Line Number Verifier │ │ │ │ (file parallel ×4 issue extraction) │ │ (rebuttal-based quality inspection/false positive elimination) │ │ (line number verification)│ │ │ └────────────────────────┘ └────────────────────────┘ └────────────────────────────────┘ │ └───────────────────────────────────────────────────┬──────────────────────────────────────────────┘ │ ▼ ┌──────────────────────────────────────────────────────────────────────────────────────────────────┐ │ 3. Output and Writeback (Outputs) │ │ ┌───────────────────────┐ ┌─────────────────────────────────────────┐ ┌──────────────────┐ │ │ │ Web management dashboard │ │ Code hosting platform writeback │ │ Instant messaging notification │ │ │ │ (score/records/developer profile)│ │ (MR/PR line-level comment Inline + Markdown summary) │ │ (DingTalk/Enterprise WeChat) │ │ │ └───────────────────────┘ └─────────────────────────────────────────┘ └──────────────────┘ │ └──────────────────────────────────────────────────────────────────────────────────────────────────┘ ``` ### 2. Capability Matrix | Core Module | Functional Characteristics | Technical Implementation and Engineering Highlights | |---|---|---| | **Multi-channel access** | Platform adaptation and protocol proxy | Supports **Web UI manual diff submission/local repository path**; supports **GitLab / GitHub / Gitee** three-platform Webhook; built-in **MCP Server (`/sse`)**, directly connects to Claude Code / Cursor. | | **Asynchronous reliability** | High concurrency and storm protection | Webhook receiving end responds within 1 second, decouples background task queue; has **same commit idempotent deduplication** and **high-frequency push automatic task merging**; built-in **daily token budget gate**. | | **Context engineering** | AST syntax tree enhancement | Based on **JavaParser**, extracts the complete method context of changed lines, solving the problem of "out of context" caused by traditional diff fragment review; self-developed **UnifiedDiffParser** maintains new and old double coordinate line numbers. | | **False positive governance system** | Finder-Verifier two-stage mechanism | **Finder (main model)** parallel (×4) extracts potential defects ➔ **Verifier (review model)** performs "rebuttal-based" quality inspection to reduce false positives ➔ **LineVerified verification** ensures accurate line number anchoring. | | **Evaluation and statistics** | Quality quantification and indicator assessment | Generates **AI code quality score (0-100 points)** and Markdown summary based on changed line number weighted algorithm; built-in **evaluation set (`samples/eval/`) scoring engine**, automatically evaluates recall rate and precision. | | **Developer profile** | AI growth assistant and quality archive | Aggregates historical review data by submitter dimension, generates **code score trend, problem type distribution, neutral ability label, and AI growth suggestions** (focusing on guiding growth, not performance appraisal tools). | | **System control** | Runtime configuration and security | Supports **graphical runtime configuration center** (API Key/model changes take effect immediately); **secret field masking + read-only**; supports `ARGUS_ACCESS_TOKEN` access authentication. | ## Quick Start and Deployment Guide ### 1. Environmental Dependency Description Before starting Argus, ensure your development and runtime environment meets the following requirements: - **Java JDK**: JDK 17 or above (recommended OpenJDK 17 / Eclipse Temurin 17 / Amazon Corretto 17). - **Build Tool**: Maven 3.6+. - **Node.js**: Node 18.x+ / 20.x+ (with npm 9+, only required for building or secondary development of Vue3 frontend). - **Database**: **Zero additional installation dependencies**! Built-in H2 file mode database (data stored in `./data/argus.mv.db`, automatically creates table structure at startup). ### 2. Quick Start (Three Experience Modes) #### Mode A: One-click Start (Recommended for Production/Daily Experience) Frontend Vue3 build output will be directly output to Spring Boot's `static` directory, achieving one-port ( `18080` ) one-stop deployment: ```powershell # 1. Clone/enter project root directory cd D:\Project\argus # 2. Compile frontend static resources (output automatically placed in src/main/resources/static/) cd web npm install npm run build cd .. # 3. Start backend application mvn spring-boot:run # 4. Browser access # Open http://localhost:18080 ``` #### Mode B: Jar Package Deployment Supports packaging as an independently runnable flat Jar package, suitable for server deployment: ```powershell # Package application (skip unit test) mvn clean package -DskipTests # Start and run Jar java -jar target/argus-0.1.0-SNAPSHOT.jar ``` #### Mode C: Mock Rapid Experience Mode (No LLM Key Quick Pass) If you temporarily do not have an OpenAI compatible API Key, you can also enable Mock mode to run through the entire process: 1. After starting the application, open `http://localhost:18080` and enter the **"System Configuration"** page. 2. Switch the **Mock mode** switch to `Enabled` and save. 3. Submit any diff or local repository reference, and the system will return a sample review report for you to quickly evaluate the interaction process. ### 3. Frontend and Backend Separation Secondary Development Mode If you need to modify the frontend page or extend UI functionality, it is recommended to use Vite's hot reload development mode: 1. **Start backend service**: ```powershell mvn spring-boot:run ``` *Backend service listening port: `18080`* 2. **Start frontend development service**: ```powershell cd web npm install npm run dev ``` *Frontend service listening port: `5173`, all requests starting with `/api` will be automatically proxied to `http://localhost:18080`* 3. **Access development environment**: Open `http://localhost:5173`, modify `web/src/` code to achieve second-level HMR real-time hot update. ### 4. System Configuration and Environment Variable Description After system startup, configuration takes effect in two ways: #### Method 1: Web Graphical Configuration Center (Recommended) Access `http://localhost:18080` -> Left sidebar **"System Configuration"**, modify and save online **take effect in real-time** (persistently written to root directory `data/argus-config.json`, no need to restart service). #### Method 2: Environment Variable Override (Suitable for Docker / K8s / CI/CD Automation) Can pass the following environment variables at startup to override default seed configuration: | Environment Variable | Default Value / Example | Description | |---|---|---| | `ARGUS_LLM_BASE_URL` | `https://api.deepseek.com` | OpenAI compatible interface address (**Warning**: do not bring `/v1` at the end, Spring AI will automatically append) | | `ARGUS_LLM_API_KEY` | `sk-xxxxxxxx` | LLM API key (secret field, log full masking) | | `ARGUS_LLM_MODEL` | `deepseek-chat` | Main review AI model name | | `ARGUS_LLM_VERIFIER_MODEL` | *(empty)* | Review model (cascade rebuttal-based false positive elimination, leave blank to use main model) | | `ARGUS_ACCESS_TOKEN` | *(empty)* | Access authentication token (leave blank for open mode; configure to bring `X-Argus-Token` header for interface and `/sse`) | | `ARGUS_NOTIFY_WEBHOOK_URL` | *(empty)* | DingTalk / Enterprise WeChat robot Webhook push address | | `ARGUS_GITLAB_BASE_URL` | `https://gitlab.example.com` | GitLab self-built instance Base URL | | `ARGUS_GITLAB_TOKEN` | `glpat-xxxxxxxx` | GitLab API Access Token (need `api` permission for writing back MR line-level comments) | | `ARGUS_GITLAB_WEBHOOK_SECRET`| `secret-key` | GitLab Webhook verification Token | | `ARGUS_GITHUB_TOKEN` | `ghp_xxxxxxxx` | GitHub Personal Access Token (for PR writeback) | | `ARGUS_GITHUB_WEBHOOK_SECRET`| `secret-key` | GitHub Webhook Secret (HMAC-SHA256 verification) | ### 5. Platform Integration and MCP Extension #### (1) Code Hosting Platform Automatic Review (GitLab / GitHub / Gitee Webhook) System provides unified Webhook entrance: `http://<deployment machine IP>:18080/api/webhook/{platform}`: | Platform | Webhook Configuration Path | Verification Mechanism | Automatic Writeback Capability | |---|---|---|---| | **GitLab** | Repository -> Settings -> Webhooks (select `Merge request events`) | `X-Gitlab-Token` plain text comparison | Line-level comment (Diff position anchoring) + Markdown summary | | **GitHub** | Repository -> Settings -> Webhooks (Content type select `json`, select `Pull requests`) | **HMAC-SHA256** (`X-Hub-Signature-256`) | Line-level comment (line + side mapping) + Markdown summary | | **Gitee** | Repository -> Repository management -> WebHooks (select password method, select `Pull Request`) | `X-Gitee-Token` password comparison | PR summary comment (line-level temporarily downgraded) | Submit/update PR automatically reviews; same commit has idempotent deduplication, high-frequency push automatically merges tasks to review only the latest commit. #### (2) MCP Server Access (Let Cursor / Claude Code Call Review) Argus built-in MCP Server, exposes SSE endpoint `http://localhost:18080/sse`. Add in your MCP client (such as Cursor's `mcp.json` or Claude Desktop configuration file): ```json { "mcpServers": { "argus": { "url": "http://localhost:18080/sse" } } } ``` After configuration, you can directly call the tool `argus_review_diff` in the conversation. ### 6. Frequently Asked Questions (FAQs) - ❓ **Q: Why does the LLM request return a 404 error, or indicate that it cannot resolve `/v1/v1/chat/completions`?** - **Cause**: The Spring AI OpenAI module automatically appends `/v1/chat/completions` after the `base-url`. - **Solution**: When filling in the Base URL in the configuration page or environment variables, **do not end with `/v1`**. For example, for DeepSeek, fill in `https://api.deepseek.com`. - ❓ **Q: Why does the Chinese display garbled characters when testing with curl/interface in PowerShell?** - **Cause**: PowerShell 5.1's default encoding format is not forced to use UTF-8. - **Solution**: Refer to the script [scripts/review-sample.ps1](file:///D:/Project/argus/scripts/review-sample.ps1) and use `[System.Text.Encoding]::UTF8` to convert the stream; or use Git Bash / Linux / Postman for interface debugging. - ❓ **Q: How to visually view the data of the embedded H2 database?** - **Solution**: Modify `src/main/resources/application.yml` to enable `spring.h2.console.enabled: true`, then access `http://localhost:18080/h2-console`. Fill in the JDBC URL as `jdbc:h2:file:./data/argus`, username `sa`, and leave the password blank. - ❓ **Q: How to ensure security when deploying on the public network or local area network?** - **Solution**: Configure the environment variable `ARGUS_ACCESS_TOKEN=your_custom_token` when starting. After the system enables authentication mode, all `/api/**` interfaces and `/sse` must be accompanied by the `X-Argus-Token: your_custom_token` request header. ## Pages | Page | Function | |---|---| | New Review | Paste diff/local repository two references, submit and jump to result page | | Review Records | Historical list (source label/problem distribution/token), click to view details | | Review Details | **AI quality score (0~100)** + AI summary + problem table (expand to view description and suggestions) + Verifier filter number + skip file | | Statistics Board | Review times/problem total/token cost/severity distribution + **one-click run evaluation set** (recall rate/precision rate) | | Developer Portrait | Quality profile aggregated by submitter: average score/score trend/problem classification distribution/neutral label + **AI growth portrait** (advantages/problem mode/improvement suggestions, result cache) | | System Configuration | LLM/review parameters/Verifier/GitLab/GitHub/Gitee/IM notification, all take effect immediately; confidential fields only write not read | ## API | Method | Path | Description | |---|---|---| | POST | `/api/review/jobs` | **Asynchronous submission review** (diff or local repository), seconds return jobId | | GET | `/api/review/jobs/{id}` | Check task progress (reviewing which file) and results | | POST | `/api/review/diff` | Synchronous review unified diff (for script/MCP) | | POST | `/api/review/local` | Synchronous review local repository (with JavaParser context enhancement) | | POST | `/api/webhook/{platform}` | GitLab/GitHub/Gitee Webhook unified entrance (各自验签, seconds return 202) | | GET | `/api/reviews` / `/api/reviews/{id}` | Review record list/details | | GET | `/api/authors` / `/api/authors/{author}` | Developer list / complete portrait | | POST | `/api/authors/{author}/ai-summary` | Generate/refresh AI growth portrait (cache) | | GET | `/api/stats` | Board aggregated data | | POST | `/api/eval/run` | Run evaluation set, return recall rate/precision rate | | GET/PUT | `/api/config` | Runtime configuration (confidential fields mask/only write) | | GET | `/sse` | MCP Server SSE endpoint | ## Design Key Points - **Line number dual coordinate tracking**: When parsing diff, maintain old/new line numbers for each line, and GitLab line-level comment position anchoring relies on it; LLM report line numbers also need to verify whether they actually fall on the new line (lineVerified), and those that cannot be anchored will degrade to summary comments. - **False positive governance**: Prompt constraints (宁可漏报) + confidence threshold + **Finder-Verifier two-stage**—— The review model does a "rebuttable" quality inspection for each finding, and those that cannot stand are eliminated; the review model can be configured as different models (cascading). - **Context engineering**: When reviewing local repositories, use JavaParser to extract the "complete method where the changed line is located" to feed the model, solving the problem of "only seeing diff fragments leading to disconnection"; parsing failures are quietly degraded. - **Asynchronous reliability**: Webhook seconds return 202 (GitLab 10s timeout will push again) → process queue asynchronous review; Same MR high-frequency push tasks are merged and only the latest commit is reviewed; same commit is idempotent (DB uniqueness judgment). Front-end manual review is also asynchronous (job + polling progress), and large MRs no longer wait synchronously for timeout. The queue interface intentionally converges and can be horizontally expanded to RabbitMQ when needed. - **Cost and fault tolerance**: LLM call explicit retry (3 times exponential backoff); daily token budget gate (超预算拒绝新审查, 防 webhook 风暴烧钱); access token authentication (confidential fields only write not read + h2-console default off). - **Effect evaluation**: Samples/eval/埋点用例 + `/api/eval/run` quantify recall/precision rate, prompt/model/context strategy each adjustment run once to prevent degradation. Actual measurement recall=1.0 / precision=0.75. - **Runtime configuration**: All configurations take effect immediately after modification (client lazily rebuilds according to version number), confidential fields only write not read, mask display, persistent files gitignore, and logs do not fall Key throughout the process. - **Storage hierarchy**: H2 two tables (record redundant JSON column免联查 + finding details), access converges in ReviewStore, and switching to MySQL only changes the datasource. ## Configuration Items (seed values, runtime configuration pages为准) | Environment Variable | Description | |---|---| | `ARGUS_LLM_BASE_URL` / `ARGUS_LLM_API_KEY` / `ARGUS_LLM_MODEL` | OpenAI compatible LLM (address does not bring /v1) | | `ARGUS_LLM_VERIFIER_MODEL` | Verifier review model, empty=same as main model | | `ARGUS_GITLAB_BASE_URL` / `ARGUS_GITLAB_TOKEN` / `ARGUS_GITLAB_WEBHOOK_SECRET` | GitLab integration | | `ARGUS_GITHUB_TOKEN` / `ARGUS_GITHUB_WEBHOOK_SECRET` | GitHub integration | | `ARGUS_GITEE_TOKEN` / `ARGUS_GITEE_WEBHOOK_SECRET` | Gitee integration | | `ARGUS_NOTIFY_WEBHOOK_URL` | DingTalk/Enterprise WeChat robot | ## Roadmap - [x] **Week 1**: Monolithic MVP——diff parsing, file filtering, LLM review, line number verification, Markdown report - [x] **Week 1.5**: Vue3 front-end, runtime configuration center, review record persistence and query - [x] **Week 1.6**: Embedded H2 database (Spring Data JPA, record+finding two tables) - [x] **Week 1.7**: Front-end UI modernization (global design system, indigo theme, self-drawn sidebar, detail page statistics, severity degree pill label) - [x] **Week 2**: GitLab Webhook automatic trigger + MR line-level comment writeback + idempotent deduplication + task merging - [x] **Week 3-4**: JavaParser context enhancement, file-level parallel review, Finder-Verifier false positive reduction (supporting cascading models) - [x] **Week 5-6**: Evaluation set quantitative recall/precision rate, statistics board, asynchronous task queue (MQ-ready interface) - [x] **Additional points**: MCP Server (/sse), cascading models, DingTalk/Enterprise WeChat IM notification - [x] **Productization reinforcement**: AI score + summary, access token authentication, manual review asynchronous + real-time progress, LLM retry, daily token budget - [x] **Multi-platform and portrait**: VcsProvider adaptation layer (GitLab/GitHub/Gitee three-platform Webhook+writeback), submitter automatic collection, developer portrait (trend/classification distribution/neutral label/AI growth suggestions) - [ ] Subsequent evolution: queue migration RabbitMQ, microservice splitting, feedback loop (👍👎 sedimentation false positive library), evaluation set expansion to 30+ use cases, Gitee line-level comment