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
@@ -69,6 +69,11 @@ try {
|
||||
}
|
||||
|
||||
// Sub-actions
|
||||
if ($action === 'projects' || str_contains($path, '/projects')) {
|
||||
echo json_encode(['status' => 'success', 'projects' => $repo->getProjects()], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
|
||||
exit;
|
||||
}
|
||||
|
||||
if ($action === 'stats' || str_ends_with($path, '/stats')) {
|
||||
echo json_encode(['status' => 'success', 'stats' => $repo->getStats()], JSON_PRETTY_PRINT);
|
||||
exit;
|
||||
|
||||
@@ -0,0 +1,44 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
require_once __DIR__ . '/../../../../src/Core/Db.php';
|
||||
require_once __DIR__ . '/../../../../src/Modules/Bugtracker/BugRepo.php';
|
||||
|
||||
use Deploymentcenter\Core\Db;
|
||||
use Deploymentcenter\Modules\Bugtracker\BugRepo;
|
||||
|
||||
header('Content-Type: application/json; charset=utf-8');
|
||||
header('Access-Control-Allow-Origin: *');
|
||||
header('Access-Control-Allow-Headers: Content-Type, Authorization, X-Agent-Token');
|
||||
header('Access-Control-Allow-Methods: GET, OPTIONS');
|
||||
|
||||
if ($_SERVER['REQUEST_METHOD'] === 'OPTIONS') {
|
||||
http_response_code(200);
|
||||
exit;
|
||||
}
|
||||
|
||||
try {
|
||||
$config = require __DIR__ . '/../../../../config/config.php';
|
||||
$db = Db::connect($config['db']);
|
||||
|
||||
$repo = new BugRepo($db);
|
||||
$projects = $repo->getProjects();
|
||||
|
||||
echo json_encode([
|
||||
'status' => 'success',
|
||||
'count' => count($projects),
|
||||
'projects' => array_map(function($p) {
|
||||
return [
|
||||
'id' => (int)$p['id'],
|
||||
'slug' => $p['slug'],
|
||||
'name' => $p['name'],
|
||||
'notes' => $p['notes'] ?? null,
|
||||
];
|
||||
}, $projects),
|
||||
], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES);
|
||||
|
||||
} catch (Throwable $t) {
|
||||
http_response_code(500);
|
||||
echo json_encode(['status' => 'error', 'message' => 'Failed to fetch projects: ' . $t->getMessage()]);
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
# Documentation Public Access
|
||||
Satisfy Any
|
||||
Allow from all
|
||||
|
||||
# Apache 2.4+ compatibility
|
||||
<IfModule mod_authz_core.c>
|
||||
Require all granted
|
||||
</IfModule>
|
||||
@@ -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.
|
||||
@@ -0,0 +1,156 @@
|
||||
<?php
|
||||
|
||||
declare(strict_types=1);
|
||||
|
||||
$mdPath = __DIR__ . '/bugtracker.md';
|
||||
$markdownContent = file_exists($mdPath) ? file_get_contents($mdPath) : '# Documentation Not Found';
|
||||
|
||||
// If requested as raw text / markdown
|
||||
if (isset($_GET['raw']) || (isset($_SERVER['HTTP_ACCEPT']) && str_contains($_SERVER['HTTP_ACCEPT'], 'text/plain'))) {
|
||||
header('Content-Type: text/plain; charset=utf-8');
|
||||
echo $markdownContent;
|
||||
exit;
|
||||
}
|
||||
|
||||
?>
|
||||
<!DOCTYPE html>
|
||||
<html lang="de">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>Deployment Center - Developer & Agent Documentation</title>
|
||||
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Fira+Code:wght@400;600&display=swap" rel="stylesheet">
|
||||
<script src="https://cdn.jsdelivr.net/npm/marked/marked.min.js"></script>
|
||||
<style>
|
||||
:root {
|
||||
--bg: #0b0f19;
|
||||
--card-bg: #141b2d;
|
||||
--accent: #5b9dff;
|
||||
--text: #e2e8f0;
|
||||
--text-muted: #94a3b8;
|
||||
--border: rgba(255, 255, 255, 0.08);
|
||||
--code-bg: #080c14;
|
||||
}
|
||||
|
||||
* { box-sizing: border-box; margin: 0; padding: 0; }
|
||||
body {
|
||||
font-family: 'Inter', system-ui, sans-serif;
|
||||
background: var(--bg);
|
||||
color: var(--text);
|
||||
line-height: 1.6;
|
||||
padding: 2rem 1rem;
|
||||
}
|
||||
|
||||
.container {
|
||||
max-width: 900px;
|
||||
margin: 0 auto;
|
||||
background: var(--card-bg);
|
||||
border: 1px solid var(--border);
|
||||
border-radius: 12px;
|
||||
padding: 2.5rem;
|
||||
box-shadow: 0 20px 40px rgba(0,0,0,0.5);
|
||||
}
|
||||
|
||||
.header-bar {
|
||||
display: flex;
|
||||
justify-content: space-between;
|
||||
align-items: center;
|
||||
border-bottom: 1px solid var(--border);
|
||||
padding-bottom: 1.5rem;
|
||||
margin-bottom: 2rem;
|
||||
}
|
||||
|
||||
.header-bar h1 {
|
||||
font-size: 1.4rem;
|
||||
color: #fff;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
gap: 0.5rem;
|
||||
}
|
||||
|
||||
.btn {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
gap: 0.4rem;
|
||||
padding: 0.5rem 1rem;
|
||||
background: rgba(91, 157, 255, 0.15);
|
||||
color: var(--accent);
|
||||
border: 1px solid var(--accent);
|
||||
border-radius: 6px;
|
||||
text-decoration: none;
|
||||
font-size: 0.85rem;
|
||||
font-weight: 600;
|
||||
transition: all 0.2s;
|
||||
}
|
||||
|
||||
.btn:hover {
|
||||
background: var(--accent);
|
||||
color: #fff;
|
||||
}
|
||||
|
||||
#docContent h1, #docContent h2, #docContent h3 {
|
||||
color: #fff;
|
||||
margin-top: 1.8rem;
|
||||
margin-bottom: 0.8rem;
|
||||
}
|
||||
|
||||
#docContent h1 { font-size: 1.8rem; border-bottom: 1px solid var(--border); padding-bottom: 0.5rem; }
|
||||
#docContent h2 { font-size: 1.4rem; color: var(--accent); }
|
||||
#docContent h3 { font-size: 1.1rem; }
|
||||
|
||||
#docContent p { margin-bottom: 1rem; color: #cbd5e1; }
|
||||
#docContent ul, #docContent ol { margin-left: 1.5rem; margin-bottom: 1rem; color: #cbd5e1; }
|
||||
#docContent li { margin-bottom: 0.4rem; }
|
||||
|
||||
#docContent code {
|
||||
font-family: 'Fira Code', monospace;
|
||||
background: rgba(255, 255, 255, 0.08);
|
||||
padding: 0.2rem 0.4rem;
|
||||
border-radius: 4px;
|
||||
font-size: 0.88rem;
|
||||
color: #38bdf8;
|
||||
}
|
||||
|
||||
#docContent pre {
|
||||
background: var(--code-bg);
|
||||
border: 1px solid var(--border);
|
||||
border-radius: 8px;
|
||||
padding: 1.25rem;
|
||||
overflow-x: auto;
|
||||
margin: 1rem 0 1.5rem 0;
|
||||
}
|
||||
|
||||
#docContent pre code {
|
||||
background: transparent;
|
||||
padding: 0;
|
||||
color: #e2e8f0;
|
||||
font-size: 0.85rem;
|
||||
}
|
||||
|
||||
#docContent blockquote {
|
||||
border-left: 4px solid var(--accent);
|
||||
background: rgba(91, 157, 255, 0.05);
|
||||
padding: 0.75rem 1rem;
|
||||
margin: 1rem 0;
|
||||
border-radius: 0 6px 6px 0;
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<div class="header-bar">
|
||||
<h1>🚀 Deployment Center API & Agent Documentation</h1>
|
||||
<div>
|
||||
<a href="bugtracker.md" target="_blank" class="btn">📄 Raw Markdown (.md)</a>
|
||||
<a href="../api/bugtracker/v1/projects.php" target="_blank" class="btn">📂 Projects API</a>
|
||||
</div>
|
||||
</div>
|
||||
<div id="docContent">Loading documentation...</div>
|
||||
</div>
|
||||
|
||||
<script>
|
||||
const rawMarkdown = <?= json_encode($markdownContent) ?>;
|
||||
document.getElementById('docContent').innerHTML = marked.parse(rawMarkdown);
|
||||
</script>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user