colin4k/benben-kingdom-skill

Benben Kingdom Helfer (奔奔王国攻略助手)

Zerlegt lokale Markdown-Notizen zu Benben Kingdom anhand von ##-Überschriften in Abschnitte, speichert sie in einer JSON-Indexdatei und führt alle Abfragen über eine BM25-Schlüsselwortsuche durch.

Kernfunktionen

1. Index erstellen/neu aufbauen – Zerlegt alle MD-Dateien im konfigurierten Verzeichnis anhand von ##-Überschriften in Abschnitte und schreibt sie in eine JSON-Indexdatei.
2. Semantische Abfrage – Führt eine BM25-Schlüsselwortsuche auf die Spielerfrage durch, gibt die relevantesten Abschnitte zurück und lässt Claude die Antwort im Spieljargon formulieren.
3. Inkrementelle Aktualisierung – Ermöglicht das Hinzufügen/Aktualisieren einer lokalen MD-Datei, eines Webartikels oder eines WeChat-Artikels zum Wissensspeicher.

Auslöser

Das Skill wird ausgelöst, wenn die Nachricht des Nutzers "奔奔" oder "奔奔王国" enthält.

Je nach Situation wird einer der folgenden Abläufe verwendet:

• Frage nach Tipps/Problemen → [Abfrageablauf]
• Bereitstellen eines MD-Pfades oder einer URL zum Hinzufügen → [Inkrementeller Aktualisierungsablauf]
• Erste Nutzung / Neuerstellung des Index / Index leer → [Initialisierungsablauf]

Abfrageablauf (für alle Fragen)

Reine Schlüsselwort-/BM25-Suche, kein Embedding-Modell oder Vektordatenbank erforderlich.

1. Ausführen: python -m scripts.query --question "<Benutzerfrage>" --top-k 8
2. Das zurückgegebene JSON parsen (Struktur siehe references/schemas.md) und das Feld _footer für später aufheben:
   • chunks: Die relevantesten Originalabschnitte (mit Quelldatei, Titel, Überschrift, Inhalt, Tags, Score)
   • concepts: Leeres Array (Konzeptextraktion entfernt)
   • sources: Liste der gefundenen Dateien (dedupliziert)
   • max_score: Höchster BM25-Score
   • _footer: Fester Footer-Text
3. Antwort aus den Suchergebnissen organisieren, am Ende den in Schritt 2 abgerufenen _footer anhängen:
   • Die eigene Terminologie von Benben Kingdom verwenden ("传说", "集结", "驻防", "夯", "白嫖", "体力", "号角", "试炼", "秘境", "四代", "三代" … nicht in allgemeine Sprache übersetzen)
   • Wie ein erfahrener Spieler direkt Schlussfolgerungen und Begründungen geben, keine Schablonen verwenden
   • Falls in den Suchergebnissen "Fallen"-Hinweise enthalten sind ("千万别", "注意"), diese unbedingt erwähnen
4. Wenn max_score gleich 0 ist oder die Ergebnisse leer sind, nichts erfinden – ehrlich sagen: "Im Notizspeicher gibt es keine relevanten Inhalte. Möchtest du einen neuen Guide hinzufügen?"

Initialisierungsablauf (Erstnutzung)

Schritt 1 – Wissensspeicherpfad konfigurieren

python -m scripts.setup --set-vault /pfad/zu/deinem/vault

/pfad/zu/deinem/vault ist das Verzeichnis, in dem deine Markdown-Dateien mit Benben-Kingdom-Notizen liegen.

Schritt 2 – Index erstellen

python -m scripts.index_vault

Durchsucht das Vault-Verzeichnis nach allen .md-Dateien, zerlegt sie anhand von ##-Überschriften in Abschnitte und erzeugt ~/.benben-kingdom/index.json.

Danach einfach direkt Fragen stellen – der Index ist bereits vorgebaut.

Inkrementeller Aktualisierungsablauf

A. Lokale Markdown-Datei

python -m scripts.add_source --path <absoluter_Pfad>

B. Web- / WeChat-Artikel-URL

1. Mit dem wechat-article-pdf-Skill (oder einem anderen Tool) die URL in Markdown umwandeln und in einer temporären Datei speichern.
2. Ausführen:

python -m scripts.add_source --path /tmp/benben-xxx.md \
  --origin-url <Original-URL> --title "<Artikeltitel>"

C. Direkt eingefügter Text

In eine temporäre Markdown-Datei schreiben und dann wie unter A vorgehen, mit --title den Titel angeben.

Nach jeder inkrementellen Aktualisierung wird der Index automatisch neu aufgebaut – kein weiterer Schritt nötig.

Skript-Übersicht

Alle Skripte werden aus dem Skill-Verzeichnis mit python -m scripts.<name> ausgeführt:

Skript	Zweck	Wichtige Parameter
setup.py	Abhängigkeiten prüfen, initialisieren	--check, --reset
index_vault.py	JSON-Index erstellen	--vault <Pfad>
add_source.py	Einzelne MD-Datei hinzufügen/aktualisieren und Index neu aufbauen	--path, --origin-url, --title
query.py	Schlüsselwort-/BM25-Suche, gibt JSON zurück	--question, --top-k

Entwurfsprinzipien

• Schlüsselwortsuche ist der einzige Einstiegspunkt: Alle Fragen müssen über query.py gehen – niemals direkt MD-Dateien auslesen und antworten.
• Deterministische Operationen dem Skript, Sprachverständnis dem Modell: Indexerstellung und Suchlogik sind klar und zuverlässig; wie die Antwort formuliert wird, entscheidet Claude.
• Nichts erfinden: Wenn keine Ergebnisse gefunden werden, dies klar sagen. Das Spiel wird schnell aktualisiert – eine falsche Antwort ist schlimmer als keine.
• Spielerjargon verwenden: Wenn Spieler Begriffe wie "夯", "白嫖", "卡点", "上号子", "进队伍" verwenden, direkt in diesem Stil antworten – das klingt nach einem erfahrenen Kumpel, der Tipps gibt.

Referenzdokumente

• references/schemas.md – JSON-Schema der Skripte / Datenbanktabellenstruktur
• references/configuration.md – Erklärung der Konfigurationsoptionen
• references/troubleshooting.md – Häufige Fehler (fehlende Indexdatei, falscher Vault-Pfad usw.)