┌─────────────────────────────────────────────────────────┐
│              Input: Code / Diff / Multi-file / PR URL     │
└───────────────┬─────────────────────────────────────────┘
                ▼
┌──────────────────────────┐   ┌─────────────────────────────┐
│  ① Rule Engine (regex)    │   │  ② AST Analysis (Python)     │
│  · 40 cross-language rules │   │  · Syntax errors (exact)     │
│  · Python/JS/TS/Java/Go/  │   │  · Undefined variables       │
│    Rust/C/C++/Shell        │   │  · Unused imports            │
│  · Security/Perf/AI/style  │   │  · Duplicate definitions     │
│  · Zero-cost, ms-level     │   │  · Empty stub functions      │
└──────────┬───────────────┘   └──────────┬──────────────────┘
           ▔▔▔▔▔▔▔▔┬────────────────────▘
                     ▼
┌──────────────────────────┐
│  ③ LLM Semantic Analysis  │
│  · Receives rule + AST    │
│    pre-scan results       │
│  · Confirms/denies hits   │
│  · Semantic issues        │
│  · Scores & fix_code      │
└──────────┬───────────────┘
           ▼
┌───────────────────────────────────────────────────────────┐
│  ④ Cross-Validation Merge (merge_findings)                  │
│  · rule / ast / llm / confirmed (both agree → +0.3 conf)   │
└───────────────────────────────┬───────────────────────────┘
                                ▼
┌───────────────────────────────────────────────────────────┐
│  ⑤ Output: 5-dimension scores + metrics + SARIF + fixes     │
│  · correctness/security/performance/maintainability/best    │
│  · quality metrics (cyclomatic complexity, function length)  │
│  · SARIF 2.1.0 export (VS Code / GitHub Code Scanning)      │
│  · each issue includes fix_code (copy-paste ready)           │
└───────────────────────────────────────────────────────────┘

python cli.py                    # Review uncommitted changes (git diff)
python cli.py --staged           # Review staged changes (git diff --cached)
python cli.py --commit HEAD~1    # Review the last commit
python cli.py src/utils.py       # Review a single file
python cli.py --remote           # Use remote Vercel deployment (no local server needed)
python cli.py --format json      # Output JSON (machine-readable, for pipes/CI)
python cli.py --sarif out.sarif  # Export SARIF (GitHub Code Scanning format)

# .git/hooks/pre-commit
python cli.py --staged --remote || exit 1   # Blocks commit if critical/major found

python cli.py --sarif results.sarif --remote
# Then upload in GitHub Action with github/codeql-action/upload-sarif@v3

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env             # Fill in LLM_API_KEY
uvicorn app.main:app --reload

curl -X POST http://127.0.0.1:8000/v1/review \
  -H "Content-Type: application/json" \
  -d '{"code": "result = eval(user_input)", "language": "python"}'

{
  "report": {
    "score": 68,
    "grade": "C",
    "dimension_scores": {
      "correctness": 88, "security": 35,
      "performance": 90, "maintainability": 80, "best_practice": 75
    },
    "issues": [
      {
        "severity": "critical",
        "category": "security",
        "line": 1,
        "title": "Using eval() to execute arbitrary code",
        "description": "eval() executes arbitrary strings as code, posing a severe injection risk.",
        "suggestion": "Use ast.literal_eval() or a dedicated parser.",
        "fix_code": "result = ast.literal_eval(user_input)",
        "source": "confirmed",
        "rule_id": "PY-S001",
        "confidence": 1.0
      }
    ],
    "engine_info": {
      "rule_count": 0, "llm_count": 0, "confirmed_count": 1,
      "total_rules_run": 3, "engines": ["rule", "llm"]
    }
  }
}

curl -X POST http://127.0.0.1:8000/v1/review_diff \
  -H "Content-Type: application/json" \
  -d '{"diff": "--- a/x.py\n+++ b/x.py\n@@ -1,3 +1,4 @@\n def f():\n-    return 1\n+    return eval(data)", "language": "python"}'

{
  "context": "User service module",
  "files": [
    {"filename": "utils.py", "content": "import os\napi_key = os.environ['KEY']", "language": "python"},
    {"filename": "main.py", "content": "from utils import *\nresult = eval(req.body)", "language": "python"}
  ]
}

python -m app.mcp_server          # stdio transport

{
  "mcpServers": {
    "code-review-agent": {
      "command": "python",
      "args": ["-m", "app.mcp_server"]
    }
  }
}

{
  "mcpServers": {
    "code-review-agent": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-client", "https://<your-host>/mcp"]
    }
  }
}

Agent: detect_security(code="import os\napi_key='sk-1234567890abcdef'\nresult = eval(user_input)\nos.system('rm -rf /tmp/x')\ndata = pickle.loads(raw_data)", language="python")

Tool → {"ok": true, "total_findings": 3, "findings": [
  {"rule_id": "PY-S001", "severity": "critical", "line": 3,
   "title": "使用 eval() 执行任意代码",
   "suggestion": "避免使用 eval()。如需解析表达式，使用 ast.literal_eval() 或专用解析器。",
   "confidence": 0.95},
  {"rule_id": "PY-S004", "severity": "major", "line": 2,
   "title": "硬编码密钥/密码",
   "suggestion": "使用环境变量或密钥管理服务：api_key = os.environ['API_KEY']",
   "confidence": 0.8},
  {"rule_id": "PY-S005", "severity": "major", "line": 5,
   "title": "使用 pickle 反序列化不可信数据",
   "suggestion": "使用 JSON 等安全格式序列化数据",
   "confidence": 0.9}
]}

Agent: analyze_metrics(code="def process_data(items):\n    result = []\n    for i in range(len(items)):\n        for j in range(len(items)):\n            ...", language="python")

Tool → {"ok": true, "metrics": {
  "complexity": {"average": 4.0, "max": 4,
    "most_complex": [{"name": "process_data", "line": 1, "complexity": 4}]},
  "functions": {"count": 1, "average_length": 7.0, "max_length": 7},
  "lines": {"total": 7, "code": 7, "comment": 0, "blank": 0}
}}

Agent: list_rules()

Tool → {"total": 40, "rules": [
  {"id": "PY-S001", "severity": "critical", "category": "security", "title": "使用 eval() 执行任意代码"},
  {"id": "PY-S002", "severity": "critical", "category": "security", "title": "使用 exec() 执行任意代码"},
  {"id": "PY-S003", "severity": "critical", "category": "security", "title": "命令注入风险"},
  {"id": "PY-S004", "severity": "major", "category": "security", "title": "硬编码密钥/密码"},
  {"id": "PY-S005", "severity": "major", "category": "security", "title": "使用 pickle 反序列化不可信数据"},
  ... (35 more)
]}

Agent: review_pr(url="https://github.com/kestarsheng/code-review-agent/commit/952fa21", language="python")

Tool → {"ok": true, "files_changed": 5, "added_lines": 240, "model": "deepseek-chat",
  "report": {
    "score": 46, "grade": "D",
    "dimension_scores": {"correctness": 36, "security": 9, "performance": 85,
                         "maintainability": 88, "best_practice": 54},
    "issues": [
      {"severity": "critical", "source": "rule", "rule_id": "PY-AST-S001",
       "line": 104, "title": "Python 语法错误，代码无法解析"},
      {"severity": "critical", "source": "rule", "rule_id": "PY-S001",
       "line": 229, "title": "使用 eval() 执行任意代码",
       "fix_code": "result = ast.literal_eval(x)"},
      {"severity": "major", "source": "llm",
       "line": 78, "title": "fetch_diff 跟随重定向且未校验最终主机，存在 SSRF 风险"},
      ... (9 more)
    ],
    "engine_info": {"rule_count": 8, "llm_count": 4, "confirmed_count": 0,
                    "engines": ["rule", "ast", "llm"]}
  }
}

curl https://<your-host>/health
curl https://<your-host>/.well-known/xagent-verification.json

python -m pytest tests/ -v