feat(docs, api): Add Projects Discovery API, deploymentcenter project seed, public web docs endpoint, and minimal agent prompt template
This commit is contained in:
Deploymentcenter Bot
@@ -0,0 +1,258 @@
|
||||
# 🤖 AI Agent Integration Guide: Deployment Center Bugtracker & Provisioning API
|
||||
|
||||
This guide defines the standardized protocol and API specifications for autonomous AI Developer Agents interacting with the **Deployment Center Bugtracker & Token Provisioning System**.
|
||||
|
||||
---
|
||||
|
||||
## 📌 Executive Overview for AI Agents
|
||||
|
||||
As an autonomous AI agent working on software repositories, you MUST actively track all runtime errors, stack traces, planned features, and backlog items in the central Deployment Center.
|
||||
|
||||
### Core Capabilities:
|
||||
1. **Sub-Token Auto-Provisioning**: Generate restricted sub-tokens for scoped agent tasks.
|
||||
2. **Automated Error Ingestion**: Report unhandled exceptions with stack traces & automatic SHA-256 deduplication.
|
||||
3. **Feature & Idea Backlog**: Submit roadmap ideas (`severity: "idea"`) or backlog items (`severity: "wishlist"`).
|
||||
4. **Active Workflow Management**: Fetch active bugs assigned to your agent ID, update status (`in_progress`, `resolved`), and append diagnostic comments.
|
||||
|
||||
---
|
||||
|
||||
## 🔑 1. Token Provisioning API
|
||||
|
||||
Agents authenticate using a **Master Token** or auto-provisioned **Sub-Token**.
|
||||
|
||||
### Endpoint: `POST /api/tokens/v1/provision`
|
||||
|
||||
Header: `Authorization: Bearer <MASTER_TOKEN>`
|
||||
|
||||
#### Request Payload:
|
||||
```json
|
||||
{
|
||||
"parent_token": "dc_master_myapp_dev_agent_001",
|
||||
"name": "Codebase Refactoring Agent Token",
|
||||
"environment": "development",
|
||||
"scopes": ["bugtracker:report", "bugtracker:manage"],
|
||||
"expires_in_hours": 24
|
||||
}
|
||||
```
|
||||
|
||||
#### Response:
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"token_id": "tok_s_8912ab",
|
||||
"raw_token": "dc_sub_myapp_refactor_agent_991",
|
||||
"scopes": ["bugtracker:report", "bugtracker:manage"],
|
||||
"environment": "development",
|
||||
"expires_at": "2026-08-07 21:00:00"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📂 1.5. Discovering Monitored Projects API
|
||||
|
||||
Before reporting a bug or feature request, an agent can dynamically query all registered projects monitored by the Deployment Center.
|
||||
|
||||
### Endpoint: `GET /api/bugtracker/v1/projects.php`
|
||||
|
||||
#### Response:
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"count": 4,
|
||||
"projects": [
|
||||
{
|
||||
"id": 1,
|
||||
"slug": "myapp",
|
||||
"name": "My Application Deluxe",
|
||||
"notes": "Hauptanwendung für Desktop und Server"
|
||||
},
|
||||
{
|
||||
"id": 2,
|
||||
"slug": "polytrader",
|
||||
"name": "PolyTrader Suite Pro",
|
||||
"notes": "Trading- und Handelssystem Client"
|
||||
},
|
||||
{
|
||||
"id": 3,
|
||||
"slug": "predictalytics",
|
||||
"name": "Predictalytics Engine",
|
||||
"notes": "Datenanalyse und Vorhersage Dienst"
|
||||
},
|
||||
{
|
||||
"id": 4,
|
||||
"slug": "deploymentcenter",
|
||||
"name": "Deployment Center",
|
||||
"notes": "Zentrale Verwaltungs- & Update-Plattform"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
If an agent discovers an issue or refactoring opportunity in any monitored system (including `deploymentcenter` itself or external dependencies), it can fetch this project list and map the issue to the appropriate `project_slug`.
|
||||
|
||||
---
|
||||
|
||||
## 🐛 2. Reporting Bugs, Features & Ideas
|
||||
|
||||
### Endpoint: `POST /api/bugtracker/v1/report.php`
|
||||
|
||||
Header: `Authorization: Bearer <AGENT_TOKEN>`
|
||||
|
||||
### A. Reporting an Unhandled Exception / Bug
|
||||
```json
|
||||
{
|
||||
"project_slug": "myapp",
|
||||
"type": "bug",
|
||||
"title": "NullReferenceException in UserAuthService.cs line 42",
|
||||
"description": "Triggered when user logs in without an active session object.",
|
||||
"error_message": "NullReferenceException: Object reference not set to an instance of an object.",
|
||||
"stack_trace": "at MyApp.Core.UserAuthService.ValidateToken(String token) in UserAuthService.cs:line 42\nat MyApp.Controllers.AuthController.Login() in AuthController.cs:line 18",
|
||||
"build_version": "v1.4.2-dev",
|
||||
"environment": "development",
|
||||
"severity": "high",
|
||||
"push_id": "push_wf_8912",
|
||||
"target_agent": "agent:code-fixer-01",
|
||||
"tags": "auth, security, csharp",
|
||||
"created_by": "agent:watchdog-monitor"
|
||||
}
|
||||
```
|
||||
|
||||
### B. Submitting a Feature Request or Quick Reminder Idea (`severity: "idea"`)
|
||||
```json
|
||||
{
|
||||
"project_slug": "myapp",
|
||||
"type": "feature_request",
|
||||
"title": "Automatische Datenbank-Backups vor FTP Deployments",
|
||||
"description": "Gedanke für später: Vor jedem FTP-Deployment automatisch mysqldump ausführen und im Server-Archiv ablegen.",
|
||||
"build_version": "v1.6.0-roadmap",
|
||||
"environment": "development",
|
||||
"severity": "idea",
|
||||
"push_id": "push_wf_9910",
|
||||
"target_agent": "agent:db-optimizer",
|
||||
"tags": "database, automation, backup",
|
||||
"created_by": "agent:planner"
|
||||
}
|
||||
```
|
||||
|
||||
#### Response:
|
||||
```json
|
||||
{
|
||||
"status": "success",
|
||||
"item_id": 4,
|
||||
"is_new": true,
|
||||
"occurrence_count": 1,
|
||||
"error_hash": "e2c918a514d89a42f",
|
||||
"type": "bug",
|
||||
"environment": "development",
|
||||
"push_id": "push_wf_8912",
|
||||
"message": "New bug reported successfully."
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📌 3. Managing Items (Fetching, Updating & Commenting)
|
||||
|
||||
### Base Endpoint: `/api/bugtracker/v1/manage/index.php`
|
||||
|
||||
Header: `Authorization: Bearer <AGENT_TOKEN>`
|
||||
|
||||
### A. Fetching Open Items Assigned to an Agent
|
||||
```http
|
||||
GET /api/bugtracker/v1/manage/index.php?project_slug=myapp&status=open&agent=agent:code-fixer-01
|
||||
```
|
||||
|
||||
### B. Updating Status & Details (`POST ?action=update`)
|
||||
```json
|
||||
{
|
||||
"id": 4,
|
||||
"status": "in_progress",
|
||||
"severity": "high",
|
||||
"push_id": "push_wf_8912",
|
||||
"target_agent": "agent:code-fixer-01",
|
||||
"tags": "auth, fixed_pending_test",
|
||||
"author": "agent:code-fixer-01"
|
||||
}
|
||||
```
|
||||
|
||||
### C. Appending Diagnostic Timeline Comments (`POST ?action=comment`)
|
||||
```json
|
||||
{
|
||||
"id": 4,
|
||||
"comment": "Ursache identifiziert: $_SESSION['user'] war Null in line 42. Null-Check und Safe Navigation Operator wurden hinzugefügt.",
|
||||
"action_taken": "code_patched",
|
||||
"author": "agent:code-fixer-01"
|
||||
}
|
||||
```
|
||||
|
||||
### D. Marking as Resolved (`POST ?action=resolve`)
|
||||
```json
|
||||
{
|
||||
"id": 4,
|
||||
"resolved_in_build": "v1.4.3-dev",
|
||||
"resolution_notes": "Unit tests hinzugefügt und Null-Check in ValidateToken() integriert.",
|
||||
"author": "agent:code-fixer-01"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 💻 4. Code Implementation Examples for Agents
|
||||
|
||||
### Python Example: Automatic Error Reporter Decorator
|
||||
```python
|
||||
import requests
|
||||
import traceback
|
||||
import sys
|
||||
|
||||
DC_API_URL = "https://dc.mhdf.de/api/bugtracker/v1/report.php"
|
||||
AGENT_TOKEN = "dc_sub_myapp_agent_live_001"
|
||||
|
||||
def report_exception_to_dc(project_slug: str, exc: Exception, env: str = "production", push_id: str = None):
|
||||
payload = {
|
||||
"project_slug": project_slug,
|
||||
"type": "bug",
|
||||
"title": f"{type(exc).__name__}: {str(exc)}",
|
||||
"error_message": str(exc),
|
||||
"stack_trace": traceback.format_exc(),
|
||||
"build_version": "v1.4.2",
|
||||
"environment": env,
|
||||
"severity": "high",
|
||||
"push_id": push_id,
|
||||
"created_by": "agent:python-runner"
|
||||
}
|
||||
headers = {
|
||||
"Content-Type": "application/json",
|
||||
"Authorization": f"Bearer {AGENT_TOKEN}"
|
||||
}
|
||||
try:
|
||||
r = requests.post(DC_API_URL, json=payload, headers=headers, timeout=5)
|
||||
return r.json()
|
||||
except Exception as e:
|
||||
print(f"Failed to report to Deployment Center: {e}", file=sys.stderr)
|
||||
```
|
||||
|
||||
### cURL Example: Submit Feature Request / Idea
|
||||
```bash
|
||||
curl -X POST "https://dc.mhdf.de/api/bugtracker/v1/report.php" \
|
||||
-H "Authorization: Bearer dc_sub_myapp_agent_live_001" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"project_slug": "myapp",
|
||||
"type": "feature_request",
|
||||
"title": "Erweiterte Filterung im WebUI Dashboard",
|
||||
"severity": "idea",
|
||||
"push_id": "push_task_1029",
|
||||
"tags": "ui, dashboard",
|
||||
"created_by": "agent:dev-assistant"
|
||||
}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🎯 Best Practices for Developer Agents
|
||||
|
||||
1. **Always set `push_id`**: When executing automated pipelines, pass a `push_id` so all updates can be traced back to the specific execution run.
|
||||
2. **Use `severity: "idea"` for thoughts**: When noticing potential refactorings or future improvements during coding, log them immediately as ideas.
|
||||
3. **Comment before resolving**: Before calling `action=resolve`, write a diagnostic comment explaining **why** and **how** the fix was performed.
|
||||
Reference in New Issue
Block a user