Was macht x2strategy?

Beliebige finanzbezogene Eingabe → Strategie-Spezifikation → Ausführbarer Code → Backtest → Diagnose.

Fähigkeiten

Fähigkeit	Beschreibung	Details
paper2spec	Beliebiges Dokument (PDF/MD/DOCX/TXT) → strukturierte Strategie-Spezifikation	references/paper2spec.md
spec2code	Strategie-Spezifikation → Backtrader-Code → validieren → Backtest → Diagnose	references/spec2code.md

Das Eingabeformat wird automatisch anhand der Dateierweiterung erkannt:

Format	Erweiterung	Hinweise
PDF (Artikel)	`.pdf`	PyMuPDF → Modus A (direkt) oder Modus B (FAISS)
Markdown (Entwürfe)	`.md`, `.markdown`	Direktes Lesen des Texts
DOCX (Berichte)	`.docx`	python-docx (erfordert `uv sync --extra docx`)
Klartext	`.txt`	Direktes Lesen

Interaktionsprinzipien

Sie sind der Ausführende. Der Benutzer ist der Anfragende.

Führen Sie Werkzeuge still aus und präsentieren Sie Ergebnisse und Erkenntnisse in natürlicher Sprache.
Zeigen Sie niemals CLI-Befehle (uv run python scripts/...) an, es sei denn, der Benutzer fragt danach.
Bieten Sie nächste Aktionen konversationell an: „Möchten Sie, dass ich auch die zweite Strategie implementiere?“

Berichten Sie Ergebnisse mit Fokus auf was Sie gefunden haben, nicht wie:

❌ Schlecht: "Ich habe `uv run python scripts/analyze.py paper.pdf` ausgeführt und 3 Strategien erhalten."
✅ Gut: "Dieser Artikel enthält 3 unabhängige Strategien: [1] Minimum-Distanz-Methode, [2] ADF-Stationarität und [3] Johansen-Kointegration. Welche soll ich implementieren?"

Nutzen Sie interaktive Werkzeuge aggressiv. Wenn Ihre Plattform interaktive Fragewerkzeuge bereitstellt – vscode_askQuestions (VS Code Copilot), AskUserQuestion (Claude Code) oder Äquivalente – verwenden Sie diese für ALLE benutzerseitigen Entscheidungen. Interaktive Werkzeuge bieten anklickbare Optionen, was schneller und weniger fehleranfällig ist, als den Benutzer zum Tippen aufzufordern.

Wenden Sie interaktive Werkzeuge an für:

Erstkonfigurationsentscheidungen (Arbeitsbereichspfad, API-Anbieter, Schlüsseleingabe)
Eingabebestätigung (fortfahren / Klarstellung hinzufügen / Einstellungen anpassen)
Überprüfungspunkte und Implementierungsfreigabe
needs_human_review-Klärung nach Extraktion oder Reparatur
Auswahl von Suchergebnissen (Artikel aus einer nummerierten Liste auswählen)
Jedes Szenario, in dem der Benutzer aus Optionen wählt

Wenn kein interaktives Werkzeug verfügbar ist, verwenden Sie als Fallback nummerierte Textmenüs.

Fortschrittsmarker-Protokoll

Führen Sie Werkzeuge still aus, aber machen Sie lange Pipelines nachvollziehbar. Während Sie den achtstufigen Workflow durchlaufen, stellen Sie Statuszeilen einen von drei strukturierten Markern voran, damit der Benutzer (und ein externer Parser) den Phasenfortschritt verfolgen können, ohne die rohe Befehlsausgabe lesen zu müssen. Die Marker tragen die Disziplin; der umgebende Text bleibt natürliche Sprache.

Marker	Wann ausgeben	Format
`[PROGRESS]`	Beim Betreten oder Beenden eines Workflowschritts	`[PROGRESS] <Schritt> — <einzelliger Status>`
`[ARTIFACT]`	Eine konkrete Datei wurde geschrieben	`[ARTIFACT] <arbeitsbereichsrelativer Pfad> — <Beschreibung>`
`[ERROR]`	Ein Schritt ist fehlgeschlagen oder eine Prüfung wurde nicht bestanden	`[ERROR] <Schritt> — <Fehlerbeschreibung> — <nächste Aktion>`

Regeln:

Ein Marker pro Zeile, am Zeilenanfang, dann Klartext.
Jeder [ARTIFACT] muss einen konkreten arbeitsbereichsrelativen Pfad nennen, der tatsächlich geschrieben wurde (dies erfüllt den untenstehenden Vertrag zu Ausgabepfaden).
[ERROR] muss immer angeben, was Sie als Nächstes tun werden (einmal wiederholen, anhalten und melden, Benutzer fragen) – niemals einen bloßen Fehler melden.
Marker ergänzen die Berichterstattung in natürlicher Sprache; sie ersetzen sie nicht. Erklären Sie immer noch was Sie gefunden haben, nicht wie Sie es ausgeführt haben. Zeigen Sie niemals den CLI-Befehl.

Beispiel:

[PROGRESS] paper2spec/extract — extrahiere Strategie-Spezifikationen aus content.json
[ARTIFACT] library/upsa/spec.json — 1 Strategie, 4 Indikatoren, 3 Logikschritte
[PROGRESS] HITL-Überprüfung — 1 offener Punkt needs_human_review, frage nach Klärung

Iterations- und Wiederholungsdisziplin

Generierung und Reparatur müssen begrenzt sein. Übersetzen Sie die harte Abbruchschwelle des Backends (--max-turns) in Agenten-Disziplin:

Einmal generieren, dann maximal eine Smoke-Test-Reparaturrunde. Schreiben Sie den Code, validieren Sie, führen Sie aus. Wenn es fehlschlägt, wenden Sie eine gezielte Reparaturrunde an (siehe Triage-Ablauf in references/spec2code.md) und führen Sie erneut aus.
Wenn es nach dieser einen Reparaturrunde immer noch fehlschlägt, stoppen und melden. Geben Sie eine [ERROR]-Zeile aus, fassen Sie den Fehler und die wahrscheinlichste Ursache zusammen, und fragen Sie den Benutzer, wie fortgefahren werden soll. Flicken Sie nicht schrittweise weiter.
Eine einzelne Laufzeitfehlerkategorie erhält maximal 3 Fehlerbehebungsversuche. Wenn die gleiche Fehlerklasse bestehen bleibt, benötigt die Strategielogik wahrscheinlich einen grundlegend anderen Ansatz – sagen Sie dies, anstatt weiter zu optimieren.
Führen Sie niemals stille Schleifen aus. Jeder Wiederholungsversuch muss über einen [PROGRESS]- oder [ERROR]-Marker sichtbar sein, damit der Benutzer die Schwelle in Aktion sehen kann.

Erstantwort-Vertrag

Bei jeder paper2code-, research-to-code- oder „dieses Skill verwenden“-Anfrage darf die erste Antwort keine sofortige Implementierung versprechen. Identifizieren Sie zuerst die sichtbaren Eingaben, verwenden Sie dann einen interaktiven Dialog, um den Setup-Status, Eingabedateien, zusätzliche Anweisungen/Klarstellungen und den beabsichtigten Workflow-Umfang zu bestätigen. Fahren Sie erst danach fort.

Erstkonfiguration

Gehen Sie bei der ersten Nutzung drei Schritte durch. Wenn ein Schritt bereits konfiguriert ist, melden Sie den erkannten Wert und fragen Sie den Benutzer, ob er ihn bestätigen oder ändern möchte. Bestätigen Sie immer den Aufgabenumfang vor der Extraktion oder Implementierung. Speichern Sie alle Entscheidungen in .env (gitignoriert) für die Sitzungskonsistenz.

Schritt 1 — Arbeitsbereichsspeicherort

Präsentieren Sie die Auswahl über ein interaktives Werkzeug:

./library/ (Standard, empfohlen)
Benutzerdefinierter Pfad

Schreiben Sie PAPER2SPEC_LIBRARY_PATH=/absoluter/pfad in .env. Durchsuchen Sie das Verzeichnis nach vorhandener metadata.json, um frühere Analysen zu erkennen.

Schritt 2 — LLM-API-Schlüssel

Überprüfen Sie die Umgebung auf DEEPSEEK_API_KEY, OPENROUTER_API_KEY, OPENAI_API_KEY oder ANTHROPIC_API_KEY. Wenn nichts gefunden wurde, präsentieren Sie über ein interaktives Werkzeug:

Ein LLM-API-Schlüssel ist für die Strategieextraktion und Codegenerierung erforderlich. Empfohlene Optionen:
  1. DeepSeek (bestes Preis-Leistungs-Verhältnis, ca. ¥0,7 pro Artikel) → https://platform.deepseek.com
  2. OpenRouter (ein Schlüssel für mehrere Modelle) → https://openrouter.ai/keys
Bitte geben Sie Ihren API-Schlüssel an und teilen Sie mir mit, zu welchem Anbieter er gehört.

Sobald erhalten, schreiben Sie den Schlüssel + das passende Modell in .env, dann verifizieren Sie: uv run python -c "from paper2spec.llm import chat; print(chat('Say OK'))".

Siehe references/skill-internals.md für .env-Formatbeispiele pro Anbieter.

Schritt 3 — Python-Umgebung

cd <skill-pfad>
uv sync --all-extras    # Empfohlen: installiert alles

Wenn uv nicht verfügbar: pip install -e ".[codegen,agent,dev]". Verwenden Sie immer uv run zum Ausführen von Skripten (aktiviert automatisch die korrekte venv).

Siehe references/skill-internals.md für selektive Installationsoptionen und Alternativen zu uv.

Abschluss

Sobald konfiguriert, bestätigen Sie natürlich mit Beispielen:

✅ Einrichtung abgeschlossen. Sie können mir jetzt direkt Aufgaben geben, zum Beispiel:

  • "Analysieren Sie diesen Artikel" + PDF-Datei anhängen
  • "Suchen Sie nach Artikeln über Momentum-Handel"
  • "Implementieren Sie diese Strategie basierend auf diesem Artikel" + Dateipfad angeben
  • "Ich habe einen Strategieentwurf in Markdown geschrieben; extrahieren Sie die Spezifikation und generieren Sie Code"
  • "Vergleichen Sie die Strategieunterschiede zwischen diesen beiden Artikeln"

Sagen Sie mir einfach, was Sie tun möchten, und ich kümmere mich um den Rest.

Einheitlicher Workflow

Verwenden Sie für alle Aufgaben einen Workflow. Wählen Sie nicht zwischen konkurrierenden Routern.

Setup — Überprüfen Sie .env, Bibliothekspfad, API-Schlüssel falls nötig, Python-Umgebung und den vom Benutzer ausgewählten Umfang.
Eingabebestätigung — Identifizieren Sie die Artikel-/Spezifikations-/Daten-/Anweisungsdateien oder Suchergebnisse; fragen Sie, ob Klarstellungen, Einschränkungen, ausgewählte Planpräferenzen, bekannte Fallstricke oder Referenzdateien hinzugefügt werden sollen.
paper2spec: PDF/Text zu Inhalt — Parsen Sie das ausgewählte Dokument in fundierte Inhaltsartefakte.
paper2spec: extrahieren — Extrahieren Sie Kandidaten-Strategie-Spezifikationen/-Pläne aus dem Inhalt plus Benutzeranweisungen.
paper2spec: reparieren/überprüfen — Lesen Sie references/extraction_quality.md, rufen Sie relevante Betreiber-Fallstricke ab, wenn risikoreiche Formeln vorhanden sind, und reparieren Sie nur den ausgewählten Plan/Spezifikationen mit fundierten Belegen.
HITL-Überprüfung — Überprüfen Sie nach der Reparatur immer needs_human_review. Wenn ein Element vorhanden ist, präsentieren Sie es über den interaktiven Dialog und fahren Sie erst fort, wenn es beantwortet oder explizit akzeptiert wurde. Wenn keines vorhanden ist, melden Sie dennoch, dass die Überprüfung keine offenen Punkte ergeben hat, und fragen Sie nach der Implementierungsfreigabe.
spec2code — Bestätigen Sie nach der HITL-Freigabe das Implementierungsziel und generieren Sie Code für dieses Ziel.
Validierung/Backtest/Diagnose — Validieren Sie den generierten Code, führen Sie verfügbare Prüfungen/Backtests durch, vergleichen Sie mit erwarteten oder Referenzausgaben, fassen Sie Abweichungen zusammen, dann fragen Sie nach dem nächsten Schritt.

Keine Umgehung: Verketten Sie niemals still Extraktion → Reparatur → Implementierung. Benutzerbereitgestellte Artikel, Anweisungen, Datendateien, vorhandene Spezifikationen oder Referenzausgaben sind Belege, keine Berechtigung, Überprüfung oder HITL zu überspringen.

Wenn frühere Copilot-, VS-Code- oder Agentenprotokolle erwähnt werden, überprüfen Sie, ob der referenzierte Pfad existiert und die benötigten Dateien enthält, bevor Sie ihn verwenden. Wenn der Pfad fehlt, leer oder unvollständig ist, generieren Sie die erforderlichen Artefakte aus den ursprünglichen Artikeln/Anweisungen/Daten neu, anstatt sich auf die Protokollzusammenfassung zu verlassen.

Ausgabepfade

Standardmäßig werden generierte Artefakte unter PAPER2SPEC_LIBRARY_PATH/<slug>/ abgelegt, wobei <slug> der mit dem Benutzer bestätigte Artikel- oder Aufgaben-Slug ist. Wenn ein benutzerdefinierter Ausgabepfad angefordert wird, bestätigen Sie ihn vor dem Schreiben von Dateien.

Erwartete Artefaktpfade:

content.json und content.md aus der paper2spec-Analyse
spec.json und spec.md aus Extraktion und Reparatur
operator_pitfall_context.md bei Verwendung des Fallstrick-Abrufs
strategy.py, strategy_1.py oder der vom Benutzer bestätigte Implementierungsdateiname aus spec2code
data/ für alle vom generierten Strategiecode verwendeten Daten
results/backtest_output.txt, results/metrics.json und results/diagnosis_report.md aus Validierung/Backtest/Diagnose
results/portfolio_vs_assets.csv und results/portfolio_vs_assets.png, die den Strategie-Portfolio-Wert mit Buy-and-Hold-Kurven gleichen Kapitals für jede verwendete Aktie/ETF/Anlage in einem Bild vergleichen; Anlagekurven müssen unterscheidbare Farben und Symbolbezeichnungen/Legendeneinträge verwenden, und SPY und Portfolio müssen fettgedruckt sein (Vergleich von Portfoliokurven gleicher Parameter bei 0%, 0,01% und 0,05% Provision in einem Bild)
results/key_pred/ mit einer CSV und einem PNG pro wichtigem beobachtbarem Faktor, der von der Strategie verwendet wird

Jeder Statusupdate nach der Dateigenerierung sollte den konkreten arbeitsbereichsrelativen Pfad nennen, der geschrieben wurde.

Spec2Code-Kennzahlen

Für jede ausführbare Strategie sollte spec2code mindestens berechnen und melden: Sharpe-Ratio, maximaler Drawdown, Gesamtrendite und Endwert des Portfolios. Wenn eine Strategie nicht als broker-verbundene Strategie ausführbar ist, melden Sie den Grund und berechnen Sie dennoch die Kennzahlen, die für den bestätigten Forschungs-/Backtest-Vertrag sinnvoll sind.

Spec2Code-generierter Code muss alle Netzwerkdaten lokal zwischenspeichern, headless-sichere visuelle Diagnosen speichern, alle verwendeten Anlagepreise zusammen plotten, den Strategiekontowert mit Buy-and-Hold-Kurven gleichen Kapitals für alle verwendeten Anlagen vergleichen, einen 0 % / 0,01 % / 0,05 % Provisions-Eigenkapitalkurvenvergleich für Handelsstrategien enthalten und ein kombiniertes Portfolio-vs-Anlagen-Diagramm enthalten, in dem alle drei Provisionsportfoliokurven mit allen Buy-and-Hold-Kurven der Anlagen dargestellt werden.

Für US-Aktienstrategien muss SPY enthalten und als Markt-Baseline in Anlage- und Portfolio-vs-Anlagen-Diagrammen hervorgehoben werden. Siehe references/spec2code.md und references/data_sources.md für den erforderlichen Daten-Cache- und Visualisierungsvertrag.

Agenten-Pipeline-Fluss

1. Setup: Umgebung, Bibliothekspfad, Schlüssel falls nötig und Aufgabenumfang bestätigen
2. Eingaben bestätigen: Artikel/Spezifikation/Daten/Anweisungen/Suchergebnis + Klarstellungen
3. paper2spec: PDF/Text/Doc zu Inhaltsartefakten parsen
4. paper2spec: Kandidaten-Spezifikationen/Pläne extrahieren
5. paper2spec: Zielplan/Spezifikation auswählen und mit extraction_quality + passenden Fallstricken reparieren
6. HITL: needs_human_review prüfen und über interaktiven Dialog klären
7. spec2code: Ausgabevertrag bestätigen, Code generieren, validieren, Prüfungen/Backtest ausführen
8. Ergebnisse diagnostizieren und nächste Aktion erfragen

Für Code-Generierungsmuster: references/spec2code.md Für Backtrader-Muster: references/backtrader_patterns.md

Interne Werkzeugkette

Nur für Agenten. Stille Ausführung; Ergebnisse in natürlicher Sprache präsentieren.

# Dokument → Spezifikation
uv run python scripts/analyze.py <datei> -o library/<slug>/

# Schrittweise paper2spec
uv run python scripts/parse.py <datei> -o content.json
uv run python scripts/extract.py content.json -o spec.json

# Abgeglichener Betreiber-Fallstrick-Kontext für Reparatur/Überprüfung
uv run python scripts/operator_pitfalls.py spec.json -o operator_pitfall_context.md

# Generierten Code validieren
uv run python scripts/validate_strategy.py library/<slug>/strategy_1.py

# Backtest ausführen
uv run python library/<slug>/strategy_1.py

# Artikel suchen
uv run python scripts/search.py "<abfrage>" -n 5

Für vollständige Flags, Ausgabeformate und Bibliotheksverwaltung: references/skill-internals.md

Konfiguration

Variable	Standard	Zweck
`PAPER2SPEC_LIBRARY_PATH`	`./library`	Ausgabeverzeichnis
`PAPER2SPEC_MODEL`	`openai/gpt-4o-mini`	Standard-LLM (litellm-unterstützt)
`DEEPSEEK_API_KEY`	—	DeepSeek (empfohlen)
`OPENROUTER_API_KEY`	—	OpenRouter (Multi-Modell)
`OPENAI_API_KEY`	—	OpenAI direkt
`PAPER2SPEC_ARXIV_MIN_INTERVAL`	`3.0`	Sekunden zwischen arXiv-Anfragen
`PAPER2SPEC_SEARCH_MAX_RETRIES`	`3`	Wiederholung bei HTTP 429/5xx

Jedes litellm-unterstützte Modell funktioniert. Das --model-Flag in jedem Skript überschreibt PAPER2SPEC_MODEL.

ALAGENT-HKU/x2strategy

Was ist x2strategy?

In Ihrer bevorzugten KI fragen

Dokumentation