0dust/OKFy

Was macht OKFy?

Übersicht

Verwenden Sie OKFy, um Dokumentations-Websites oder lokale Markdown-Ordner in lokale Open Knowledge Format-Bundles zu konvertieren und diese dann über einen schreibgeschützten MCP-Server für Agenten bereitzustellen. Bevorzugen Sie npx -y okfy-ai in generierten Befehlen, damit Clients das veröffentlichte Paket ohne globale Installation starten können.

Kurzreferenz

Ziel	Befehl oder Aktion
Eine Docs-Seite registrieren und Setup ausgeben	npx -y okfy-ai init <name> <url> --client codex --max-pages 100 --max-depth 4
Lokales Markdown importieren	npx -y okfy-ai import ./docs --out ./docs-okf --source-name "Projektdokumentation"
Eine Quelle für eine Aufgabe nachweisen	npx -y okfy-ai activate <name-oder-bundle> --client codex --task "<aufgabe>" --out okfy-activation
Bereitschaft und Graph anzeigen	npx -y okfy-ai map <name-oder-bundle> --out okfy-inspector.html
Einrichtung diagnostizieren	npx -y okfy-ai doctor <name> --client codex
Für MCP bereitstellen	npx -y okfy-ai serve <name-oder-bundle> --mcp --auto-refresh

Einrichtungs-Workflow

1. Wählen Sie einen kurzen Quellnamen wie stripe, clerk oder projekt-docs.
2. Führen Sie für eine Docs-Website npx -y okfy-ai init <name> <url> --client codex --max-pages 100 --max-depth 4 aus.
3. Führen Sie für lokales Markdown import, dann validate, und stellen Sie den generierten Bundle-Pfad bereit. Fügen Sie --force nur hinzu, nachdem der Benutzer das Überschreiben des Ausgabeverzeichnisses ausdrücklich genehmigt hat.
4. Wenn der Benutzer vor Konfigurationsänderungen einen Nachweis wünscht, führen Sie activate mit --task aus, das der tatsächlichen Frage des Benutzers entspricht. Das Paket enthält okfy-inspector.html, okfy-setup.md und okfy-proof.json.
5. Wenn die Einrichtung fehlschlägt oder der MCP-Client keine Tools sieht, führen Sie doctor aus, bevor Sie die Client-Konfiguration manuell bearbeiten.

MCP-Verwendung

Wenn ein OKFy-MCP-Server verfügbar ist, verwenden Sie die Tools in dieser Reihenfolge:

1. bundle_summary, um den Validierungsstatus, die Aktualität, verfügbare Quellen und Tool-Erwartungen zu überprüfen.
2. search_concepts mit den Aufgabenbegriffen des Benutzers. Verwenden Sie source-Filter in Arbeitsbereichen mit mehreren Quellen, wenn die relevante Dokumentationsquelle bekannt ist.
3. read_concept für die relevantesten Konzepte, wobei die Lesevorgänge klein gehalten werden, bevor sie erweitert werden.
4. get_neighbors, wenn die Antwort von verknüpften Konzepten, Backlinks, Voraussetzungen oder nahegelegenen API-/Referenzseiten abhängt.
5. Zitieren Sie die Quell-URLs oder Ressourcenfelder, die von den Konzeptergebnissen bereitgestellt werden.

Beginnen Sie mit engen Suchanfragen und erweitern Sie diese nur, wenn die Ergebnisse dürftig sind. Übergeben Sie in Arbeitsbereichen sowohl source als auch id an read_concept, wenn Konzept-IDs mehrdeutig sind.

Arbeitsbereiche

Stellen Sie mehrere registrierte Quellen über einen MCP-Server bereit, wenn eine Aufgabe einen gesamten Stack umfasst:

npx -y okfy-ai serve stripe clerk --mcp --auto-refresh

Filtern Sie dann Suchen:

{ "query": "checkout sessions", "source": "stripe", "limit": 5 }

Verwenden Sie source-Filter immer dann, wenn der Benutzer das Produkt, die API, das Framework oder die Dokumentationsquelle benennt. Wenn der Benutzer eine Frage zum gesamten Stack stellt, durchsuchen Sie den Arbeitsbereich zuerst ohne Filter und verwenden Sie dann quellspezifische Lesevorgänge für eine höhere Genauigkeit.

Sicherheitsregeln

• MCP-Tools sind schreibgeschützt. Die automatische Aktualisierung ist eine serverseitige Wartungsfunktion für registrierte Quellen und kein agent-aufrufbares Schreibwerkzeug.
• Verwenden Sie nicht npx okfy; verwenden Sie npx -y okfy-ai für Installationsfreie Befehle.
• Führen Sie serve --mcp nicht als normale Chatty-Terminalsitzung aus. MCP-Clients starten es als Stdio-Subprozess.
• Umgehen Sie nicht die Crawler-Sicherheitsstandards, das Private-Network-Schutzsystem oder die unsicheren --force-Schutzmechanismen, es sei denn, der Benutzer akzeptiert das Risiko ausdrücklich.
• Bearbeiten Sie die Client-Konfiguration nicht zuerst manuell, wenn init, activate oder doctor den genauen Befehl / die genaue Konfiguration erstellen oder überprüfen können.

Häufige Fehler

Fehler	Behebung
OKFy wie einen gehosteten Index behandeln	Halten Sie den Workflow lokal: Bundle-Dateien, MCP-Stdio und Quell-URLs bleiben überprüfbar.
Jedes Konzept nach der Suche lesen	Lesen Sie zuerst die wichtigsten Treffer und verwenden Sie dann Nachbarn, um nur bei Bedarf zu erweitern.
Quellennamen in Arbeitsbereichen ignorieren	Verwenden Sie source-Filter und quellqualifizierte Lesevorgänge für Bundle mit mehreren Quellen.
Nachweis überspringen	Verwenden Sie activate --task, wenn der Benutzer Vertrauen benötigt, bevor MCP eingerichtet wird.
Konfiguration blind debuggen	Führen Sie doctor <name> --client codex aus und folgen Sie dem nächsten Reparaturbefehl.