Code Trace Tree (Spur-Baum)

Was macht Code Trace Tree (Spur-Baum)?

Erstellen und anzeigen von Code-Workflows als verschachtelte Bäume von Trace-Punkten für Zeilen, Dateien und Verzeichnisse. Verwenden Sie die bereitgestellten Python-Skripte, um den hybriden Speicher zu bedienen, der von den Code Trace Tree IDE-Plugins verwendet wird, und bitten Sie die IDE dann, neu zu laden.

Bearbeiten oder synchronisieren Sie Traces nur, wenn der Benutzer explizit danach fragt (z. B. themenbezogene Knoten generieren, einen Tipp an einer Zeile hinzufügen, nach Bearbeitungen neu binden). Synchronisieren Sie nicht automatisch nach jeder Aktion. Löschen Sie niemals vorhandene Trace-Punkte (einschließlich derer, die rebind als "ungültig" meldet), es sei denn, der Benutzer bittet explizit darum, sie zu entfernen.

So verwenden Sie diese Fähigkeit

Lesen Sie nur diese SKILL.md. Listen Sie die Ordner scripts/ oder references/ dieser Fähigkeit nicht auf, durchsuchen Sie sie nicht und öffnen Sie keine Skriptquellen, um die API zu erlernen. Rufen Sie die dokumentierten Python-Befehle mit absolutem Pfad auf.

Öffnen Sie scripts/ oder references/ nur, wenn Sie auf ein kritisches Problem bei der Verwendung der Fähigkeit stoßen (Skript fehlt oder stürzt ab, Speicher beschädigt oder ein Fehler, der von dieser Datei nicht abgedeckt wird).

Speicherort der Fähigkeitsskripte

Hilfsskripte befinden sich unter <Agent Skill Path>/code-trace-tree/scripts/.

Agent Skill Path ist das Fähigkeitenverzeichnis dieses Agenten (das übergeordnete Verzeichnis von code-trace-tree/) für den Agenten, den Sie ausführen – projektlokal, falls vorhanden, ansonsten global. Es endet bei skills, nicht bei code-trace-tree. Pfade stimmen mit npx skills überein. Die Tabelle listet gängige Beispiele auf; andere aufgeführte Agenten funktionieren genauso.

Agent (Beispiele)	Globaler Agent Skill Path	Projektlokaler Agent Skill Path
Claude Code	~/.claude/skills	<repo>/.claude/skills
Cursor	~/.cursor/skills	<repo>/.agents/skills
GitHub Copilot	~/.copilot/skills	<repo>/.agents/skills
Codex	~/.codex/skills	<repo>/.agents/skills
Gemini CLI	~/.gemini/skills	<repo>/.agents/skills

Unter Windows entspricht ~ %USERPROFILE%. Lösen Sie Agent Skill Path einmal pro Sitzung auf. Rufen Sie Skripte mit absoluten Pfaden über python (oder python3, falls dies im PATH ist) auf. Behalten Sie das aktuelle Arbeitsverzeichnis (CWD) im IDE-Projekt bei (wechseln Sie nicht per cd in das Fähigkeitenverzeichnis). Direkte Aufrufe: Trace Tree Operationen. Unter PowerShell siehe auch Windows PowerShell.

Trace Tree Operationen

Alle Aufrufe der Fähigkeitsskripte. Ersetzen Sie den absoluten Agent Skill Path für DIESEN Agenten. Behalten Sie das CWD im IDE-Projekt bei (wechseln Sie nicht per cd in das Fähigkeitenverzeichnis). Unter PowerShell siehe Windows PowerShell.

• resolve_storage.py
• create_tree.py
• trace_tree.py
• request_refresh.py
• request_refresh_profile.py
• request_refresh_settings.py
• select_trace_points.py

resolve_storage.py

Löst die Projekt-ID und die gebundene globale XML auf. Wenn der Speicher fehlt, wird er erstellt (Fall C). Wenn .idea/code-trace-tree.project.id existiert, die XML jedoch fehlt, wird die XML mit derselben projectId neu erstellt. Erstellt/überschreibt die .idea-ID-Datei nicht. Verändernde Operationen (create_tree und trace_tree add / ensure / move / delete / rebind) erstellen den Speicher ebenfalls automatisch. trace_tree search erstellt nichts automatisch.

Verwendung

python "<Agent Skill Path>/code-trace-tree/scripts/resolve_storage.py" [project_path]

Optionale Parameter:

• [project_path]: Pfad, der verwendet wird, um das IDE-Projektstammverzeichnis zu finden (Standard: CWD). Übergeben Sie das Projektstammverzeichnis, damit der XML <path> korrekt ist.

Rückgabewert

Stdout ist JSON (indent=2, UTF-8). Fehler geben ERROR: … auf stderr aus.

{
  "created": false,
  "project_root": "<abs>",
  "global_dir": "<OS Config Dir>/code-trace-tree",
  "project_id": "<uuid or null>",
  "storage_xml": "<abs xml path>"
}

created ist true, wenn eine neue XML geschrieben wurde. Exit 0 bei Erfolg; 1, wenn das Projektstammverzeichnis nicht gefunden werden kann.

Beispiel:

python "<Agent Skill Path>/code-trace-tree/scripts/resolve_storage.py"
python "<Agent Skill Path>/code-trace-tree/scripts/resolve_storage.py" /path/to/project

create_tree.py

Erstellen Sie einen verschachtelten Trace-Punkt-Baum in einem Aufruf. Stellt sicher, dass nur die Payload-Stammknoten (und Kinder von Stammknoten, die bereits existieren) vorhanden sind. Sobald ein Knoten erstellt ist, werden seine Nachkommen hinzugefügt (keine pro-Kind-Sicherstellung). Führen Sie kein search durch, wenn es nicht nötig ist – dieses Skript stellt bereits sicher, dass vorhandene Knoten bestehen. Verwenden Sie search, wenn Sie IDs benötigen (für select/move/delete) oder zur Inspektion. LINE-Lokatoren sind dieselben wie bei trace_tree.py (file + line + content). Ignorieren Sie das Vorkommen von Zeileninhalten (occurrenceIndex / totalOccurrences) – das Skript berechnet es. Bevorzugen Sie --tree-file unter PowerShell.

Optionales --parent-id hängt die Payload unter einem vorhandenen Knoten an (dieser Elternknoten wird aufgelöst, nicht sichergestellt).

Verwendung

python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --tree-file tree.json
python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" tree.json
python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --tree '<json>'

Erforderliche Parameter (genau eine Baumquelle):

• --tree-file <path>: JSON-Datei (- = stdin). Bevorzugen Sie dies gegenüber --tree.
• --tree <json>: JSON-String.
• Positional <path>: dasselbe wie --tree-file.

Parameter (gemeinsam; alle optional):

• --project <path>: Projektpfad (Standard: CWD).
• --profile <name>: Profilname-Überschreibung (Standard: <activeProfileName>).
• --dry-run: XML nicht schreiben oder aktualisieren.
• --no-refresh: IDE-Aktualisierungssignal überspringen.
• --parent-id <uuid>: Vorhandener Elternknoten; wiederholen Sie von der Wurzel aus zum direkten Elternknoten. Für das Profil-Stammverzeichnis weglassen.
• --parent <json>: JSON-Pfad des vorhandenen Elternknotens (nicht kombinieren mit --parent-id).

Baum-JSON (ein Knotenobjekt oder ein Array von Knotenobjekten). Jeder Knoten verwendet die gleiche Struktur, einschließlich children (description auf jedem Knoten, nicht nur auf dem Stamm):

{
  "file": "src/A.java",
  "line": 10,
  "content": "void methodA() {",
  "name": "methodA",
  "description": "",
  "type": "LINE",
  "children": [
    {
      "file": "src/B.java",
      "line": 40,
      "content": "void methodB() {",
      "name": "methodB",
      "description": "",
      "type": "LINE",
      "children": [
        {
          "file": "src/C.java",
          "line": 20,
          "content": "void methodC() {",
          "name": "methodC",
          "description": "",
          "type": "LINE"
        },
        {
          "type": "FILE",
          "file": "src/Util.java",
          "name": "Util",
          "description": ""
        }
      ]
    }
  ]
}

Felder (jeder Knoten, einschließlich Kinder): file (erforderlich); type (LINE | FILE | DIRECTORY; weglassen zur Ableitung: line/content → LINE, sonst Pfad auf Disk); LINE benötigt line + content; name / description / children optional. Fügen Sie nicht occurrenceIndex / totalOccurrences ein. children ist ein Array derselben Objekte.

Rückgabewert

Stdout ist JSON (indent=2, UTF-8). skipped: true bei einem Knoten bedeutet, dass die Sicherstellung ihn gefunden hat; die Kinder dieses Knotens werden trotzdem sichergestellt. created: true bedeutet hinzugefügt; Nachkommen dieses Knotens wurden ohne Sicherstellung hinzugefügt.

{
  "action": "create_tree",
  "profile": "<profile-name>",
  "storage_xml": "<abs>",
  "parentId": "<uuid or empty>",
  "created": 3,
  "skipped": 1,
  "ids": ["<uuid>", …],
  "roots": [ { "skipped": false, "created": true, "node": <node-object>, "children": [ … ] } ],
  "refreshed": true
}

Exit 0 bei Erfolg.

Beispiel:

python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --tree-file tree.json
python "<Agent Skill Path>/code-trace-tree/scripts/create_tree.py" --parent-id "$PARENT_ID" --tree-file tree.json

trace_tree.py

Suchen, hinzufügen, sicherstellen, verschieben, löschen und neu binden von Knoten. Ignorieren Sie das Vorkommen von Zeileninhalten (occurrenceIndex / totalOccurrences) – übergeben Sie diese Felder niemals; das Skript berechnet sie.

Verwendung

python "<Agent Skill Path>/code-trace-tree/scripts/trace_tree.py" <subcommand> [flags…]
python "<Agent Skill Path>/code-trace-tree/scripts/trace_tree.py" [shared-flags] <subcommand> [flags…]

Gemeinsame Flags (--project, --profile, --dry-run, --no-refresh) können vor oder nach dem Unterbefehl erscheinen. Lassen Sie --project weg, wenn sich das CWD bereits im IDE-Projekt befindet (Skripte durchsuchen die Verzeichnisstruktur nach oben, um .vscode / .idea / .git oder andere gängige Projektmarkierungen zu finden). Standardprofil: <activeProfileName>.

LINE-Lokatoren: Der gespeicherte Tipp ist [datei, zeile, vollständig-getrimmte-zeile]. --line ist erforderlich. Das Skript überprüft den getrimmten Text in dieser Zeile, speichert die vollständig getrimmte Zeile (ein Teilstring --content wird erweitert) und setzt dann occurrenceIndex / totalOccurrences durch Scannen der Datei. Doppelte getrimmte Zeilen in einer Datei sind unterscheidbar, weil --line die Kopie auswählt. Ignorieren Sie das Vorkommen: Lesen, übergeben oder berechnen Sie occurrenceIndex / totalOccurrences nicht. Schützen Sie unter PowerShell zitierte --content mit --% (siehe Windows PowerShell) oder verwenden Sie einen Teilstring-Tipp plus --line. Wickeln Sie die CLI niemals in einen Helfer ein, der einen Parameter namens $Args verwendet.

Tipp	Ergebnis
Exakte Zeile + vollständig getrimmter Text	Wird unverändert verwendet
Besonderer Teilstring dieser Zeile (z. B. .handleEmailTriggerRequest()	--line erforderlich; speichert die vollständig getrimmte Zeile
Gleicher getrimmter Text in 2+ Zeilen	Übergeben Sie --line für die beabsichtigte Kopie; Skript setzt Vorkommen
Mehrzeiliger Aufruf	Bevorzugen Sie die markanteste physische Zeile (oft die .methodName(-Fortsetzung)

add vs. ensure: add erstellt immer eine neue UUID (wie das IDE-Plugin). Verwenden Sie es für einen zweiten Knoten in derselben Zeile mit einer anderen Beschriftung oder einem anderen Elternknoten. ensure ist holen-oder-erstellen: gleiche Identität → "skipped": true (Exit 0). Bei LINE ist die Identität Datei + getrimmter lineContent + die durch --line ausgewählte Kopie (das Skript speichert das Vorkommen; übergeben Sie es nicht). Die Identität von FILE/DIRECTORY ist Pfad + Typ. --trace-name, Beschreibung und Elternknoten sind nicht Teil der Identität.

Generieren eines Baums: Bevorzugen Sie create_tree.py. Führen Sie kein search durch, wenn es nicht nötig ist – das Skript stellt vorhandene Knoten sicher und fügt neue Unterbäume hinzu. Verwenden Sie search, wenn Sie IDs für select/move/delete benötigen oder zur Inspektion. Für einen einzelnen Knoten verwenden Sie ensure (holen-oder-erstellen; kein search erforderlich) oder add (immer eine neue UUID).

Elternpfad: Bevorzugen Sie wiederholte --parent-id vom wurzelwärtigen Vorfahren zum direkten Elternknoten. Lassen Sie es für die Wurzel bei add / ensure weg. Kombinieren Sie nicht --parent-id mit --parent. Bloße Zeichenketten innerhalb von --parent JSON sind nur UUIDs, keine traceName-Beschriftungen.

--parent-Form	Beispiel
Stamm	--parent [] (wird für move zum Stamm benötigt; add / ensure standardmäßig zum Stamm)
Knoten-ID in JSON	--parent '["3d41c2d1-…"]'
[datei, zeile, inhalt]	--parent '[["src/A.java",10,"void methodA() {"]]'

method A def
  method B call
    method C call   ← add (oder ensure, wenn B bereits existierte) mit --parent-id idA --parent-id idB

Neu binden nach Dateibearbeitung: Agenten bearbeiten nicht über den IDE-Editor, daher ist eine Live-Zeilenverschiebung nicht anwendbar. Führen Sie nach jeder Aktion, die den Projektquelltext geändert hat, rebind (optional --file für betroffene Pfade) aus, bevor Sie sich auf Lokatoren oder select/navigate verlassen. rebind repariert lineNumber aus getrimmtem lineContent und berechnet Vorkommen neu. Das "invalid"-Array bedeutet, dass diese LINE-Lokatoren nicht gefunden wurden – belassen Sie diese Knoten im Baum; löschen Sie sie nicht, es sei denn, der Benutzer hat darum gebeten, sie zu entfernen.

Verwenden Sie bei vielen verändernden Aufrufen --no-refresh bei jedem einzelnen und dann einmal request_refresh.py am Ende.

Erforderlicher Unterbefehl:

• <subcommand>: search | add | ensure | move | delete | rebind

Parameter (gemeinsam; alle optional):

• --project <path>: Projektpfad (Standard: CWD).
• --profile <name>: Profilname-Überschreibung (Standard: <activeProfileName>).
• --dry-run: XML nicht schreiben oder aktualisieren.
• --no-refresh: IDE-Aktualisierungssignal überspringen.

Parameter (search; alle optional):

• --id <uuid>: Knoten-UUID.
• --file <path>: Relativer Datei-/Verzeichnispfad.
• --line <n>: 1-basierte Zeilennummer.
• --content <text>: Teilstring-Übereinstimmung von lineContent.
• --trace-name <text>: Teilstring-Übereinstimmung von traceName.
• --type <LINE|FILE|DIRECTORY>: Nach Typ filtern.

Parameter (add / ensure):

• Lokator (erforderlich): --file + --line + --content für LINE (Teilstring dieser Zeile ist in Ordnung); --file für FILE/DIRECTORY. Oder positionell DATEI ZEILE INHALT, oder Pfad.
• --parent-id <uuid> (optional): UUID des Elternknotens; wiederholen Sie vom Wurzelknoten ausgehend zum direkten Elternknoten (bevorzugt). Für die Wurzel weglassen.
• --parent <json> (optional): JSON-Elternpfad (nicht kombinieren mit --parent-id).
• --trace-name <text> (optional): Beschriftung des Trace-Punkts.
• --description <text> (optional): Beschreibung.
• --type <LINE|FILE|DIRECTORY> (optional): Typ-Überschreibung (Standard: LINE).

Parameter (move):

• Lokator (erforderlich): --id, oder --file + --line + --content, oder --file allein für FILE/DIRECTORY.
• Neuer Elternknoten (erforderlich): --parent-id (vom Wurzelknoten ausgehend wiederholen → direkter Elternknoten) oder --parent JSON. Für die Wurzel verwenden Sie --parent []. Kombinieren Sie --parent-id nicht mit --parent.

Parameter (delete):

• Lokator (erforderlich): --id, oder --file + --line + --content, oder --file allein für FILE/DIRECTORY.

Parameter (rebind; alle optional):

• --file <path>: Auf relative Pfade beschränken; wiederholbar. Standard: Alle LINE-Knoten im Profil.

Rückgabewert

Stdout ist JSON (indent=2, UTF-8). Fehler geben ERROR: … auf stderr aus und beenden mit einem Exit-Code ungleich Null.

node-object:

{
  "id": "<uuid>",
  "parentId": "<uuid or empty>",
  "type": "LINE|FILE|DIRECTORY",
  "file": "<relative path>",
  "line": "<n or empty>",
  "content": "<trimmed lineContent>",
  "name": "<traceName>",
  "depth": 0,
  "childCount": 0
}

search:

{
  "project_root": "<abs>",
  "storage_xml": "<abs>",
  "profile": "<profile-name>",
  "matches": [ <node-object>, … ]
}

add (immer erstellt; kein "skipped")

[Fortsetzung folgt – der Rest der SKILL.md wird nach dem gleichen Prinzip übersetzt]