RAGRAF an AutoClaw anbinden

Zwei Kanäle: CLI und MCP

Nicht vermischen — davon hängt ab, was genau zu prüfen ist. Das CLI funktioniert immer und hängt nicht an den App-Einstellungen; MCP stellt dieselben Operationen als Agenten-Tools bereit, erfordert aber die Server-Registrierung.

Was bereits konfiguriert ist

Bestandsaufnahme der Autorenmaschine aus den Messungen der Integrationssitzung — Referenz dafür, wie es nach der Einrichtung aussehen sollte.

AutoClaw-Konten auf der Maschine (jedes mit eigenem Skill-Baum und Runtime)

%APPDATA%\AutoClaw-oversea-official\accounts\<account-1>\   (основной)
%APPDATA%\AutoClaw-oversea-official\accounts\<account-2>\

Der Skill liegt in beiden Konten — beim Kontowechsel bleibt er sichtbar. Die Frische der Kopien wurde gemessen: SKILL.md, reference/operations.md und reference/repair.md stimmen in beiden Konten per SHA-256 mit der Projektversion überein.

CLI-Kanal: funktioniert ohne Konfiguration

Der Hauptweg, solange MCP nicht registriert ist. Drei Regeln.

1. 1Erster Schritt — Korpus aktualisierenDie Antwort trägt status: actual — Index ist aktuell, reindexed — soeben neu gebaut, created — es gab keinen Korpus und einer wurde angelegt, not_a_project — das Verzeichnis sieht nicht nach Projekt aus, error — der Grund steht im Feld reason.
   Erster Schritt einer Aufgabe (PowerShell)Kopieren

   python <repo>\tools\ragraf.py ensure <каталог проекта>

2. 2Danach — eine Operation, nicht Dateien lesenstale: true bedeutet: Den Fakten ist bis zur Neuindizierung nicht zu trauen — der Code ist davongezogen. Das ist keine „Sicherheitshalber“-Warnung.
   Index-Operationen (PowerShell)Kopieren

   python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml query symbol --name corpus_hash
   python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml check

3. 3Korpusliste — Befehl ohne KonfigurationDas Entwicklungsregister ist ohne -p sichtbar: catalog gibt alle eingetragenen Korpora mit Revisionen und Summen aus.
   Korpusregister (PowerShell)Kopieren

   python <repo>\tools\ragraf.py catalog

Warum das CLI hier vorzuziehen ist

Nicht aus Bequemlichkeit. Jeder Befehl druckt Text, den der Agent selbst liest; eine MCP-Antwort muss über ein Schema interpretiert werden. Zudem hängt das CLI weder am App-Neustart noch an der Server-Registrierung — es kann nicht „still wegfallen“. Messung am Polygon: 14 Tool-Aufrufe gegen 28 ohne Index; Erstreffer auf die Zieldatei — 92%.

MCP-Kanal: Aufbau und Anbindung

Der MCP-Anschluss in AutoClaw funktioniert anders als in vertrauten Clients (Claude Desktop, Codex, DeepSeek Harness) — und das ist wesentlich. Vier in der Sitzung gemessene Fakten:

1. 1Keine MCP-Konfiguration im ProfilDie Suche in ~/.pi, <account>\runtime und <account>\projects fand weder mcp.json noch mcpServers in den Einstellungen. Die Registrierung liegt nicht in einer Profildatei.
2. 2ragraf wird von keinem Anwendungspaket registriertAlle 106 Tabellen von runtime.sqlite wurden geprüft — eine MCP-Server-Tabelle gibt es nicht; die ragraf-mcp-Erwähnungen in der Datenbank erwiesen sich als Historie früherer Sitzungen, nicht als Registrierung.
3. 3Das Vertikalpaket deklariert MCP-Server per DeklarationDas Feld mcpServers existiert im Paket-Schema: dist\resources\vertical-packs\code\zwork-pack.json. Bei offiziellen Paketen ist es leer ("mcpServers": []), und Benutzerpakete gibt es auf der Platte gar nicht (Suche nach zwork-pack.json außerhalb der Installation — 0 Dateien).
4. 4Der eingebaute Agent bedient kein MCP@earendil-works/pi-coding-agent enthält keine einzige Zeile über MCP (dist und docs geprüft); alle im Bundle gefundenen mcpServers-Erwähnungen gehören zu gebündelten Vendor-SDKs (Google/Gemini) und haben mit AutoClaw nichts zu tun.

Wie anbinden und was prüfen

1. 1Den MCP-Abschnitt in den Produkteinstellungen findenÖffnen Sie die Projekt- (oder App-)Einstellungen in AutoClaw und suchen Sie den Abschnitt über MCP / externe Tools — dort wird der Server registriert.
2. 2Die Startwerte eintragen (durch Lauf verifiziert)--project ist nicht nötig: Der Server bestimmt den Korpus aus dem Arbeitsverzeichnis über das Entwicklungsregister; für ein fremdes Projekt wählt das Tool ragraf_use_project den Korpus (die Liste liefert ragraf_catalog).
3. 3Prüfen, nicht annehmenVor der Anbindung tool_search mit der Anfrage ragraf aufrufen — erwartet werden 0. Nach Registrierung und Neustart — 24 Tools. Genau diese Differenz ist der Beweis, dass die Anbindung funktioniert.

команда:            <repo>\.venv\Scripts\python.exe
аргументы:          <repo>\tools\ragraf-mcp.py
                    --agent AutoClaw --agent-kind autoclaw
рабочий каталог:    <repo>

Wenn es diesen Einstellungsabschnitt nicht gibt

Dann ist die ehrliche Antwort: Der MCP-Kanal ist in diesem Build nicht verfügbar, und RAGRAF arbeitet über das CLI (Abschnitt oben). Es geht nichts verloren, außer dass jeder Aufruf ein Befehl statt eines Tools ist. Eine Registrierung per Datenbankänderung oder Dateiaustausch zu erfinden ist unzulässig: runtime.sqlite ist Anwendungszustand, und ihn am Produkt vorbei zu ändern, umgeht die Buchführung von Rechten und Artefakten (governed_tool_*-Tabellen).

Vier Kompatibilitätsdefekte

Die Anbindung des zweiten Clients (DeepSeek Harness) legte Defekte frei, die auch AutoClaw betrafen. Alle vier sind geschlossen, jeder mit Regressionsschutz.

1. 1Der Server starb bei der ersten russischen Antwort in bereinigter UmgebungDer MCP-Client gibt dem Kindprozess nur 12 Variablen mit (APPDATA, HOMEDRIVE, HOMEPATH, LOCALAPPDATA, PATH, PROCESSOR_ARCHITECTURE, SYSTEMDRIVE, SYSTEMROOT, TEMP, USERNAME, USERPROFILE, PROGRAMFILES). Weder PYTHONUTF8 noch PYTHONIOENCODING sind dabei, die Prozess-Locale bleibt cp1252 — und send() starb mit UnicodeEncodeError: charmap codec (src/ragraf/mcp_server.py). Die AutoClaw-Shell setzt beide Variablen, deshalb war der Defekt für AutoClaw unsichtbar — er zeigte sich erst beim zweiten Client. Fix: force_utf8_stdio() — die Ströme werden im Server selbst auf UTF-8 gestellt, nicht aus der Umgebung übernommen.
2. 2Das Pflichtfeld --project blockierte Mehrprojekt-BetriebFix: --project ist optional, der Korpus wird über das Arbeitsverzeichnis gesucht (Entwicklungsregister), das Tool ragraf_use_project kam hinzu. Ein Server bedient alle 18 Korpora der Autorenmaschine.
3. 3Das Kommando reindex schrieb den Lauf nicht ins RegisterAm eigenen Korpus gemessen: rev-0046 im Index, rev-0045 mit alter Summe im Register; dadurch indizierte check den Korpus jedes Mal neu, während catalog und das Panel den Vergangenheitsstand zeigten. Fix: src/ragraf/cli.py — reindex schreibt den Lauf über denselben gemeinsamen Einstieg watch.record_index_run wie index.
4. 4ensure und use_project fehlten in der StatistikDie Telemetrie hängt als Wrapper an den op_*-Methoden der Fassade, doch diese zwei Operationen leben im MCP-Server. In der usage-Zusammenfassung fehlten sie — es war also nicht beantwortbar, ob Agenten die Erster-Schritt-Regel befolgen. Fix: Facade.record_external_call (src/ragraf/facade.py) plus Aufzeichnung serverseitig. Messung nach dem Fix: ensure 1, use_project 1 in der Agenten-Zusammenfassung.

Abhängigkeiten: warum der .venv-Interpreter

Auf der Autorenmaschine sind die RAGRAF-Abhängigkeiten für den PATH-Interpreter nur über PYTHONUSERBASE erreichbar (%APPDATA%\AutoClaw-oversea-official\toolchain\python\Python313\site-packages). Ein externer Client bereinigt sie — und python aus PATH scheitert mit „PyYAML ist nicht installiert“. Gemessen: Die Projekt-.venv ist autark — bei vollständig entfernten PYTHON*-Variablen importiert sie yaml, fastembed, sqlite_vec, tree_sitter, ijson, tiktoken. Auch für AutoClaw nützlich: Das CLI in der Agent-Shell läuft ohnehin, aber die .venv hängt nicht mehr an den Umgebungseinstellungen.

Skill und Regeln

Der Skill ragraf-core

Der Skill liegt im Baum jedes Kontos:

%APPDATA%\AutoClaw-oversea-official\accounts\<account>\runtime\zwork-agent\skills\ragraf-core\
    SKILL.md                 (вход: когда применять, порядок работы)
    reference/operations.md  (выбор операции и границы)
    reference/repair.md      (что делать, когда индекс сломан)

Die Quelle ist das Projektverzeichnis: <repo>\docs\skills\ragraf-core. Änderungen gehen zuerst ins Projekt und werden dann in den Dienstrordner des Kontos kopiert. Sonst „hinkt“ die Kontokopie dem Projekt hinterher und der Agent arbeitet mit einer alten Version. Es gibt genau zwei Kopien — eine pro Konto; der Skill ist in beiden vorhanden.

Per Frischemessung verifiziert (diese Sitzung): In beiden Konten liegen drei Dateien — SKILL.md 9811 Bytes, reference/operations.md 7546, reference/repair.md 11271 — und die SHA-256 jeder Datei stimmt mit der Projektversion überein. Die Kontokopien sind nicht veraltet.

$src = '<repo>\docs\skills\ragraf-core'
Get-ChildItem "$env:APPDATA\AutoClaw-oversea-official\accounts" -Directory | ForEach-Object {
    $dst = Join-Path $_.FullName 'runtime\zwork-agent\skills\ragraf-core'
    if (Test-Path -LiteralPath $dst) {
        Copy-Item -Recurse -Force "$src\*" $dst
        Write-Host "обновлено: $dst"
    }
}

Skill-Prüfung: Datei beginnt mit ---, die Felder name und description werden zeilenweise geparst, Größe unter 256 KiB, Kodierung UTF-8 ohne BOM, Zeilenenden LF, und die Kontokopie stimmt byteweise mit der Projektversion überein.

Regeln: ~/.pi/agent/AGENTS.md

Das ist die AutoClaw-Benutzerregeldatei — sie greift in jedem Projekt ohne eigene AGENTS.md, und umgekehrt: eine Projekt-AGENTS.md ist strenger. Auch AGENTS.md aus übergeordneten Verzeichnissen wird herangezogen, bis zur .git-Grenze.

Der Abschnitt, der die Arbeit über den Index erzwingt, ist Abschnitt 8 „Verpflichtende Nutzung von RAGRAF bei der Code-Entwicklung“. Drei Stellen, die man kennen sollte:

Überprüfung — vier Stufen

Von eng nach breit: CLI und Register → Korpusfrische → MCP-Kanal → Telemetrie. Jede Stufe ist ein Befehl und das erwartete Ergebnis aus der Sitzung.

python <repo>\tools\ragraf.py catalog
python <repo>\tools\ragraf.py ensure <repo>

18 Entwicklungen im Register; status: actual und übereinstimmende Summen.

python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml check

„Summe des Korpus jetzt“ = „Summe bei der Indizierung“, „nach Indizierung geändert: nein“.

tool_search("ragraf")                    → до подключения: 0 инструментов
                                           после регистрации и перезапуска: 24
ragraf_ensure()                          → status = actual | reindexed | created
ragraf_index_status()                    → index_rev, capability
ragraf_use_project(project="<имя>")      → ревизия ДРУГОГО корпуса

cd <repo>
Remove-Item Env:\PYTHONUTF8, Env:\PYTHONIOENCODING -ErrorAction SilentlyContinue
python tests\test_mcp_compat.py        # 15 проверок

python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml usage --agent AutoClaw

Eine Zeile pro Agent mit Aufrufzahl und Operationen, einschließlich ensure. Fehlt ensure in der Aufschlüsselung, hat der Client es nie aufgerufen — die Telemetrie hat es nicht „verloren“.

Rückbau

Die MCP-Registrierung ist die einzige umkehrbare Aktion in der Oberfläche: Server im selben Einstellungsabschnitt entfernen und die Anwendung neu starten. Index, Register und Korpora bleiben unverändert.

Die RAGRAF-Änderungen selbst sind additiv; für das alte Verhalten genügen drei Änderungen: den force_utf8_stdio()-Aufruf entfernen, required=True an --project zurückgeben, ragraf_use_project aus TOOLS und _handlers löschen. Keine davon berührt Index, Speicherschema, Revisionsnummerierung oder Register — der Rückbau erfordert keine Neuindizierung.

Die Skill-Kopien in den Konten werden aus dem Projekt wiederhergestellt:

Copy-Item -Recurse -Force <repo>\docs\skills\ragraf-core `
    "$env:APPDATA\AutoClaw-oversea-official\accounts\<account>\runtime\zwork-agent\skills\ragraf-core"

Wo was in AutoClaw liegt

Installationsbesonderheit: Der Anwendungscode liegt entpackt (resources\app\dist), nicht in app.asar. Das ist praktisch für die Erkundung: Dateien sind mit Bordmitteln lesbar, main.cjs kann zeilenweise durchsucht werden.

Einladung zu AutoClaw