(feated) GitHub Issue auto debug script and guidelines for use

README.md

@@ -212,6 +212,26 @@ Verify Neo4J at: [http://localhost:7474](http://localhost:7474)
 
 ---
 
+## 🛠️ Scripts
+- **Generate JWT Token**:  
+  ```bash
+  python -m prometheus.script.generate_jwt_token
+  ```
+- **GitHub Issue Debug Guide**:  
+  A script to help debug GitHub issues using Prometheus.  
+  See the full guide in [docs/GitHub-Issue-Debug-Guide.md](docs/GitHub-Issue-Debug-Guide.md).
+
+- **Create Superuser**:  
+  ```bash
+  python -m prometheus.script.create_superuser --username <username> --email <email> --password <password> --github_token <your_github_token>
+  ```
+- **Test LLM Service**:
+- ```bash
+  python -m prometheus.script.test_llm_service
+  ```
+
+---
+
 ## 📄 License
 
 This project is dual-licensed:

docs/GitHub-Issue-Debug-Guide.md

@@ -0,0 +1,185 @@
+# GitHub Issue Auto Debug Script Usage Guide
+
+## Overview
+
+`prometheus/script/github_issue_debug.py` is an automated script for:
+1. Retrieving detailed information (title, body, comments, etc.) of a specified issue from the GitHub API.
+2. Automatically uploading the GitHub repository to Prometheus.
+3. Using Prometheus's AI analysis capabilities to debug the issue.
+4. Returning analysis results, fix patches, etc.
+
+## Prerequisites
+
+### 1. Start Prometheus Service
+Ensure the Prometheus service is running:
+```bash
+# Start using docker-compose
+docker-compose up --build
+```
+
+### 2. Obtain GitHub Personal Access Token
+1. Visit https://github.com/settings/tokens
+2. Click "Generate new token (classic)"
+3. Select the appropriate permission scope:
+   - `repo` (access private repositories)
+   - `public_repo` (access public repositories)
+4. Generate and save the token.
+
+### 3. Install Python Dependencies
+```bash
+pip install requests
+```
+
+## Basic Usage
+
+### Simple Example
+```bash
+python github_issue_debug.py \
+    --github-token "your_token_here" \
+    --repo "owner/repository" \
+    --issue-number 42
+```
+
+### Full Parameter Example
+```bash
+python github_issue_debug.py \
+    --github-token "ghp_xxxxxxxxxxxxxxxxxxxx" \
+    --repo "microsoft/vscode" \
+    --issue-number 123 \
+    --prometheus-url "http://localhost:9002/v1.2" \
+    --output-file "debug_result.json" \
+    --run-build \
+    --run-test \
+    --run-reproduction-test \
+    --run-regression-test \
+    --push-to-remote \
+    --image-name "python:3.11-slim" \
+    --workdir "/app" \
+    --build-commands "pip install -r requirements.txt" "python setup.py build" \
+    --test-commands "pytest tests/" \
+    --candidate-patches 3
+```
+
+## Parameter Details
+
+### Required Parameters
+- `--github-token`: GitHub Personal Access Token
+- `--repo`: GitHub repository name in the format `owner/repo`
+- `--issue-number`: Issue number to process
+
+### Optional Parameters
+- `--prometheus-url`: Prometheus service address (default: http://localhost:8000)
+- `--output-file`: Path to the result output file (if not specified, output to console)
+
+### Validation Options
+- `--run-build`: Run build validation for the generated patch
+- `--run-test`: Run test validation for the generated patch
+- `--run-reproduction-test`: Run reproduction test to verify if the issue can be reproduced
+- `--run-regression-test`: Run regression test to ensure existing functionality is not broken
+- `--push-to-remote`: Push the fix to a remote Git branch
+
+### Docker Environment Configuration
+- `--dockerfile-content`: Specify Dockerfile content directly
+- `--image-name`: Use a predefined Docker image
+- `--workdir`: Working directory inside the container (default: /app)
+- `--build-commands`: List of build commands
+- `--test-commands`: List of test commands
+
+### Other Options
+- `--candidate-patches`: Number of candidate patches (default: 6)
+
+## Usage Scenarios
+
+### Scenario 1: Simple Bug Report Analysis
+```bash
+# Analyze a simple bug report without running any validation
+python github_issue_debug.py \
+    --github-token "your_token" \
+    --repo "pytorch/pytorch" \
+    --issue-number 89123
+```
+
+### Scenario 2: Python Project with Test Validation
+```bash
+# Perform a complete debug for a Python project, including build and test validation
+python github_issue_debug.py \
+    --github-token "your_token" \
+    --repo "requests/requests" \
+    --issue-number 5678 \
+    --run-build \
+    --run-test \
+    --run-reproduction-test \
+    --run-regression-test \
+    --image-name "python:3.11-slim" \
+    --build-commands "pip install -e ." \
+    --test-commands "pytest tests/test_requests.py"
+```
+
+### Scenario 3: Node.js Project with Auto Push
+```bash
+# Process an issue for a Node.js project and automatically push the fix to a remote branch
+python github_issue_debug.py \
+    --github-token "your_token" \
+    --repo "facebook/react" \
+    --issue-number 9876 \
+    --run-build \
+    --run-test \
+    --run-reproduction-test \
+    --run-regression-test \
+    --push-to-remote \
+    --image-name "node:18-slim" \
+    --build-commands "npm ci" "npm run build" \
+    --test-commands "npm test"
+```
+
+### Scenario 4: Custom Docker Environment
+```bash
+# Use a custom Dockerfile for debugging
+python github_issue_debug.py \
+    --github-token "your_token" \
+    --repo "tensorflow/tensorflow" \
+    --issue-number 4321 \
+    --run-build \
+    --dockerfile-content "FROM tensorflow/tensorflow:latest-gpu
+WORKDIR /app
+COPY . /app
+RUN pip install -r requirements.txt" \
+    --workdir "/app" \
+    --build-commands "python setup.py build_ext --inplace" \
+    --test-commands "python -m pytest tests/unit/"
+```
+
+## Output Result Explanation
+
+After execution, the script outputs results in JSON format, including the following fields:
+
+```json
+{
+  "success": true,
+  "issue_info": {
+    "repo": "owner/repo",
+    "number": 123,
+    "title": "Issue Title",
+    "url": "https://github.com/owner/repo/issues/123",
+    "state": "open"
+  },
+  "prometheus_result": {
+    "patch": "Generated code patch",
+    "passed_reproducing_test": true,
+    "passed_build": true,
+    "passed_existing_test": false,
+    "passed_regression_test": true, 
+    "passed_reproduction_test": true,
+    "issue_response": "AI-generated issue response"
+  },
+   "created_branch_and_pushed": true,
+   "branch_name": "fix-issue-123"
+}
+```
+
+### Result Field Description
+- `success`: Whether the process was successful
+- `issue_info`: Basic information about the GitHub issue
+- `prometheus_result.patch`: Code fix patch generated by Prometheus
+- `prometheus_result.passed_*`: Status of various validations
+- `prometheus_result.issue_response`: AI-generated issue analysis and response