API-Referenz

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-31

REST-API für das KI-Task-Management System.

Endpoints

Tasks

Zuweisungen & Ergebnisse

GET /api/v1/tasks

Listet alle Tasks mit optionalen Filtern.

Query-Parameter

Beispiel

curl "https://dev.campus.systemische-tools.de/api/v1/tasks?status=pending&limit=10"

Response

{
  "success": true,
  "data": [
    {
      "id": 1,
      "uuid": "abc-123-...",
      "title": "Analyse durchführen",
      "type": "ai_task",
      "status": "pending",
      "created_by": "root",
      "created_at": "2025-12-20 10:00:00"
    }
  ],
  "meta": {
    "total": 42,
    "limit": 10,
    "offset": 0
  }
}

POST /api/v1/tasks

Erstellt einen neuen Task.

Request-Body

{
  "title": "Analyse durchführen",        // required
  "description": "Details...",           // optional
  "type": "ai_task",                     // optional: human_task, ai_task, mixed
  "created_by": "user",                  // optional
  "created_by_type": "human",            // optional: human, ai
  "due_date": "2025-12-31 23:59:59",    // optional
  "parent_task_id": 1,                   // optional
  "metadata": {"key": "value"}           // optional
}

Beispiel

curl -X POST https://dev.campus.systemische-tools.de/api/v1/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Daten analysieren",
    "type": "ai_task"
  }'

Response (201 Created)

{
  "success": true,
  "data": {
    "id": 2,
    "uuid": "def-456-...",
    "title": "Daten analysieren",
    "status": "pending",
    ...
  }
}

GET /api/v1/tasks/{id}

Gibt Task-Details inkl. Zuweisungen, Ergebnisse und Subtasks zurück.

Response

{
  "success": true,
  "data": {
    "task": { ... },
    "assignments": [ ... ],
    "results": [ ... ],
    "subtasks": [ ... ]
  }
}

POST /api/v1/tasks/{id}/assign

Weist einen Task einem Bearbeiter zu.

Request-Body

{
  "assignee": "ollama",                  // required
  "assignee_type": "ollama",             // required: human, ollama, claude, anthropic_api
  "model_name": "mistral",               // optional
  "assigned_by": "user",                 // optional
  "notes": "Bitte priorisieren"          // optional
}

PUT /api/v1/tasks/{id}/status

Ändert den Task-Status.

Request-Body

{
  "status": "in_progress",               // required
  "updated_by": "user",                  // optional
  "updated_by_type": "human"             // optional
}

Erlaubte Übergänge

POST /api/v1/tasks/{id}/execute

Führt einen Task mit KI aus.

Request-Body

{
  "executor_type": "ollama",             // optional: ollama, anthropic_api
  "model": "mistral",                    // optional
  "auto_complete": true,                 // optional: Task nach Erfolg abschließen
  "additional_context": "..."            // optional: Zusätzlicher Kontext
}

Response

{
  "success": true,
  "data": {
    "id": 1,
    "task_id": 2,
    "executor": "ollama",
    "model_name": "mistral",
    "response": "Die Analyse ergab...",
    "tokens_input": 150,
    "tokens_output": 420,
    "tokens_total": 570,
    "duration_ms": 12500,
    "status": "success"
  }
}

Error-Responses

// 400 Bad Request
{
  "success": false,
  "error": "Title is required"
}

// 404 Not Found
{
  "success": false,
  "error": "Task not found"
}

// 500 Internal Server Error
{
  "success": false,
  "error": "Database connection failed"
}

Vergleich: PHP API vs MCP-Tasks

Änderungshistorie

CLI-Befehle

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-20

Kommandozeilen-Interface für das KI-Task-Management System.

Befehle

create

Erstellt einen neuen Task.

php cli.php create --title="Aufgabe" [options]

Optionen:
  --title="..."       Titel (required)
  --description="..." Beschreibung
  --type=...          human_task, ai_task, mixed (default: human_task)
  --created-by=...    Ersteller (default: $USER)

Beispiele

# Einfacher Task
php cli.php create --title="Code Review durchführen"

# KI-Task
php cli.php create --title="Analyse" --type=ai_task

# Task mit Beschreibung
php cli.php create \
  --title="Dokumentation aktualisieren" \
  --description="README.md mit neuen Features aktualisieren" \
  --type=human_task

list

Listet Tasks auf.

php cli.php list [options]

Optionen:
  --status=...   Filter nach Status
  --type=...     Filter nach Typ
  --limit=...    Max. Anzahl (default: 20)

Beispiele

# Alle Tasks
php cli.php list

# Nur offene Tasks
php cli.php list --status=pending

# KI-Tasks
php cli.php list --type=ai_task --limit=10

Ausgabe

ID    Titel                               Typ          Status       Erstellt
---------------------------------------------------------------------------------
1     Test-Task für KI-Analyse            ai_task      in_progress  2025-12-20 10:00
2     Code Review                         human_task   pending      2025-12-20 11:00

show

Zeigt Task-Details an.

php cli.php show <id>

Beispiel

php cli.php show 1

Task #1: Test-Task für KI-Analyse
============================================================
Status:      in_progress
Typ:         ai_task
Erstellt:    2025-12-20 10:00:00 von root

Beschreibung:
Dies ist ein Test-Task

Zuweisungen:
  - ollama (ollama) - completed

Ergebnisse:
  - ollama (mistral) - success - 686 tokens

assign

Weist einen Task zu.

php cli.php assign <id> --to=<name> --type=<type> [options]

Optionen:
  --to=...      Bearbeiter-Name (required)
  --type=...    human, ollama, claude, anthropic_api (required)
  --model=...   Model-Name (optional)

Beispiele

# An Ollama zuweisen
php cli.php assign 1 --to=ollama --type=ollama --model=mistral

# An Mensch zuweisen
php cli.php assign 2 --to=max --type=human

# An Anthropic API zuweisen
php cli.php assign 3 --to=anthropic --type=anthropic_api --model=claude-sonnet-4

execute

Führt einen Task mit KI aus.

php cli.php execute <id> [options]

Optionen:
  --executor=...      ollama, anthropic_api (default: ollama)
  --model=...         Model-Name (default: mistral)
  --auto-complete     Task nach Erfolg abschließen

Beispiele

# Mit Ollama (Mistral)
php cli.php execute 1 --executor=ollama --model=mistral

# Mit llama3.2
php cli.php execute 1 --model=llama3.2

# Mit Anthropic API
php cli.php execute 1 --executor=anthropic_api --model=claude-sonnet-4

# Mit Auto-Complete
php cli.php execute 1 --auto-complete

Ausgabe

ℹ Führe Task #1 mit ollama (mistral) aus...
✓ Erfolgreich ausgeführt!
Tokens: 686 | Dauer: 13043ms

Antwort:
----------------------------------------
Die Analyse ergab folgende Ergebnisse...

status

Ändert den Task-Status.

php cli.php status <id> <new_status>

Status-Werte:
  pending       Offen
  in_progress   In Arbeit
  completed     Abgeschlossen
  failed        Fehlgeschlagen
  cancelled     Abgebrochen

Beispiele

# Task starten
php cli.php status 1 in_progress

# Task abschließen
php cli.php status 1 completed

# Task abbrechen
php cli.php status 1 cancelled

complete

Schließt einen Task ab (Shortcut für status + result).

php cli.php complete <id> [options]

Optionen:
  --result="..."   Ergebnis-Text speichern

Beispiele

# Einfach abschließen
php cli.php complete 1

# Mit Ergebnis
php cli.php complete 1 --result="Alle Tests bestanden"

delete

Löscht einen Task.

php cli.php delete <id>

stats

Zeigt Statistiken an.

php cli.php stats

Ausgabe

Task-Statistiken
========================================
Gesamt:        42
Offen:         15
In Arbeit:     5
Abgeschlossen: 20
Fehlgeschlagen:1
Abgebrochen:   1

Nach Typ:
  Mensch:      10
  KI:          30
  Gemischt:    2

Token-Statistiken
========================================
Ergebnisse:    25
Tokens gesamt: 15420
Kosten (USD):  0.0350
Avg. Dauer:    8500ms

help

Zeigt die Hilfe an.

php cli.php help

Exit-Codes

Umgebungsvariablen

Datenbank-Schema

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-31

Tabellenstruktur des KI-Task-Management Systems in der Datenbank ki_dev.

tasks

Haupttabelle für alle Tasks.

Indizes

PRIMARY KEY (id)
UNIQUE KEY uk_uuid (uuid)
KEY idx_status (status)
KEY idx_created_by (created_by)
KEY idx_type (type)
KEY idx_parent_task (parent_task_id)
KEY idx_created_at (created_at)
KEY idx_status_created (status, created_at)

task_assignments

Zuweisungen von Tasks an Bearbeiter.

task_results

Ergebnisse von Task-Ausführungen mit Token-Tracking.

task_comments

Kommentare und Protokoll-Einträge zu Tasks.

Abfragen

Letzte 10 Tasks

SELECT id, title, status, created_at
FROM tasks
ORDER BY id DESC
LIMIT 10;

Tasks nach Status

SELECT status, COUNT(*) as count
FROM tasks
GROUP BY status;

Token-Verbrauch pro Model

SELECT model_name,
       SUM(tokens_total) as total_tokens,
       SUM(cost_usd) as total_cost,
       COUNT(*) as executions
FROM task_results
WHERE model_name IS NOT NULL
GROUP BY model_name
ORDER BY total_tokens DESC;

Änderungshistorie

Hook-Integration

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-31

Automatische Task-Erstellung aus Claude Code Prompts via Hook-System.

Erkannte Patterns (geplant)

Bei Aktivierung würde der Hook folgende Patterns in User-Prompts erkennen und automatisch Tasks erstellen:

Funktionsweise (bei Aktivierung)

User-Prompt: "Bitte TODO: Logging implementieren und den Code reviewen"
                    ↓
            Hook erkennt Pattern
                    ↓
        Task erstellt: "Logging implementieren"
                    ↓
            type: ai_task
            status: pending
            created_by: $USER
            created_by_type: ai

Aktivierung

Um den Hook zu aktivieren, muss er in der Hook-Konfiguration registriert werden:

Datei: /root/.claude/settings.json oder .claude/settings.local.json

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/var/www/tools/ki-protokoll/claude-hook/log_to_db.py",
            "timeout": 5
          },
          {
            "type": "command",
            "command": "/var/www/tools/ki-protokoll/claude-hook/task_hook.py",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Aktive Hooks (aktueller Stand)

Derzeit sind folgende Hooks für UserPromptSubmit aktiv:

Hook-Script

Konfiguration

# Datenbankverbindung - verwendet Umgebungsvariablen
DB_CONFIG = {
    'host': os.environ.get('CLAUDE_DB_HOST', 'localhost'),
    'port': int(os.environ.get('CLAUDE_DB_PORT', '3306')),
    'user': os.environ.get('CLAUDE_DB_USER', 'claude_code'),
    'password': os.environ.get('CLAUDE_DB_PASSWORD'),
    'database': os.environ.get('CLAUDE_DB_NAME', 'ki_dev'),
    'charset': 'utf8mb4'
}

# Erkennungsmuster
TASK_PATTERNS = [
    (r'TODO:\s*(.+?)(?:\n|$)', 'todo'),
    (r'TASK:\s*(.+?)(?:\n|$)', 'task'),
    (r'@task\s+(.+?)(?:\n|$)', 'mention'),
    (r'#task\s+(.+?)(?:\n|$)', 'hashtag'),
]

Erstellte Task-Eigenschaften

Installation (falls gewünscht)

1. Hook ausführbar machen

chmod +x /var/www/tools/ki-protokoll/claude-hook/task_hook.py

2. Python-Abhängigkeiten

pip3 install pymysql

3. Hook in settings.json registrieren

# Füge den task_hook.py zu den UserPromptSubmit Hooks hinzu (siehe oben)

4. Testen

# In Claude Code eingeben:
"TODO: Test-Task erstellen"

# Prüfen ob Task erstellt wurde

Fehlerbehandlung

Der Hook ist non-blocking. Fehler werden zu stderr geloggt, aber der Claude Code Workflow wird nicht unterbrochen.

# Immer zurückgegeben:
{"continue": true}

Debugging

# Hook manuell testen
echo '{"hook_event_name":"UserPromptSubmit","prompt":"TODO: Test"}' | python3 /var/www/tools/ki-protokoll/claude-hook/task_hook.py

# Logs prüfen (stderr)
# Task #123 created: Test...

Zusammenspiel mit anderen Hooks

Änderungshistorie