Code Trace Tree

Was macht Code Trace Tree?

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

Traces sollten nur dann bearbeitet oder synchronisiert werden, wenn der Benutzer dies explizit wünscht (z. B. themenbezogene Knoten generieren, einen Tipp in einer Zeile hinzufügen, nach Bearbeitungen neu binden). Führen Sie nicht bei jeder Runde eine automatische Synchronisation durch. Löschen Sie niemals vorhandene Trace-Punkte (einschließlich solcher, die von rebind als "invalid" gemeldet werden), es sei denn, der Benutzer fordert explizit deren Entfernung an.

So verwenden Sie diese Fertigkeit

Lesen Sie nur diese SKILL.md. Listen, durchsuchen oder erkunden Sie die scripts/- oder references/-Ordner dieser Fertigkeit nicht, und öffnen Sie keinen Skriptquellcode, um die API zu lernen. Führen Sie die dokumentierten Python-Befehle über den absoluten Pfad aus.

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

Speicherort der Fertigkeitsskripte

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

Agent Skill Path ist das Fertigkeitsverzeichnis dieses Agenten (das Elternverzeichnis 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. Die Pfade stimmen mit npx skills überein. Die Tabelle listet gängige Beispiele auf; andere aufgeführte Agenten funktionieren gleich.

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 ist ~ das %USERPROFILE%. Lösen Sie den Agent Skill Path einmal pro Sitzung auf. Führen Sie Skripte mit absoluten Pfaden mittels python (oder python3, falls dies im PATH ist) aus. Behalten Sie den Prozess-CWD im IDE-Projekt bei (wechseln Sie nicht per cd in den Fertigkeitsordner). Direkte Aufrufe: Trace Tree OPs. Unter PowerShell siehe auch Windows PowerShell.

Trace Tree OPs

Alle Aufrufe der Fertigkeitsskripte. Ersetzen Sie den absoluten Agent Skill Path für DIESEN Agenten. Behalten Sie den Prozess-CWD im IDE-Projekt bei (wechseln Sie nicht per cd in den Fertigkeitsordner). 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 das gebundene globale XML auf. Falls der Speicher fehlt, wird er erstellt (Fall C). Wenn .idea/code-trace-tree.project.id existiert, das XML aber fehlt, wird das XML mit derselben projectId neu erstellt. Es wird keine .idea-ID-Datei erstellt/überschrieben. Mutierende create_tree und trace_tree add / ensure / move / delete / rebind erstellen den Speicher ebenfalls automatisch. trace_tree search erstellt ihn nicht 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-Projekt-Root zu finden (Standard: CWD). Übergeben Sie das Projekt-Root, 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 ein neues XML geschrieben wurde. Exit 0 bei Erfolg; 1, wenn das Projekt-Root 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

Erstellt in einem Aufruf einen verschachtelten Trace-Punkt-Baum. Stellt nur die Payload-Wurzeln sicher (und die Kinder von Wurzeln, die bereits existieren). Sobald ein Knoten erstellt ist, werden seine Nachkommen hinzugefügt (kein pro-Kind-ensure). Führen Sie kein search durch, wenn nicht nötig – dieses Skript stellt bereits vorhandene Knoten sicher. Verwenden Sie search, wenn Sie IDs benötigen (select/move/delete) oder zum Überprüfen. Zeilen-Lokatoren sind identisch mit trace_tree.py (file + line + content). Ignorieren Sie das Zeileninhalt-Vorkommen (occurrenceIndex / totalOccurrences) – das Skript berechnet es. Bevorzugen Sie --tree-file unter PowerShell.

Das optionale --parent-id hängt die Payload unter einem vorhandenen Knoten an (dieser Elternteil 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>: identisch mit --tree-file.

Parameter (gemeinsam; alle optional):

• --project <path>: Projektpfad (Standard: CWD).
• --profile <name>: Profilnamen-Überschreibung (Standard: <activeProfileName>).
• --dry-run: Kein XML schreiben oder aktualisieren.
• --no-refresh: IDE-Aktualisierungssignal überspringen.
• --parent-id <uuid>: Vorhandener Elternteil; wiederholen von Wurzel zu unmittelbarem Eltern. Für Profil-Wurzel weglassen.
• --parent <json>: Vorhandener Elternpfad als JSON (nicht mit --parent-id kombinieren).

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

{
  "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 Scheibe); LINE benötigt line + content; name / description / children optional. Geben Sie kein occurrenceIndex / totalOccurrences an. children ist ein Array derselben Objekte.

Rückgabewert

Stdout ist JSON (indent=2, UTF-8). skipped: true bei einem Knoten bedeutet, dass ensure ihn gefunden hat; die Kinder dieses Knotens werden dennoch sichergestellt. created: true bedeutet Hinzufügen; Nachkommen dieses Knotens wurden ohne ensure 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

Suche, Hinzufügen, Sicherstellen, Verschieben, Löschen und Neubinden von Knoten. Ignorieren Sie das Zeileninhalt-Vorkommen (occurrenceIndex / totalOccurrences) – übergeben Sie diese Felder nie; 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 CWD sich bereits innerhalb des IDE-Projekts befindet (Skripte durchsuchen die Verzeichnisse aufwärts, um .vscode / .idea / .git oder andere übliche Projektmarkierungen zu finden). Standardprofil: <activeProfileName>.

Zeilen-Lokatoren: Gespeicherter Tipp ist [datei, zeile, vollständig-getrimmte-zeile]. --line ist erforderlich. Das Skript prü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, da --line auswählt, welches Exemplar gemeint ist. Ignorieren Sie occurrence: Lesen, übergeben oder berechnen Sie occurrenceIndex / totalOccurrences nicht. Schützen Sie unter PowerShell zitiertes --content mit --% (siehe Windows PowerShell) oder verwenden Sie einen Teilstring-Tipp plus --line. Umwickeln Sie die CLI niemals in einen Helfer, der einen Parameter namens $Args verwendet.

Tipp	Ergebnis
Exakte Zeile + vollständig getrimmter Text	Wie angegeben verwendet
Aussagekräftiger Teilstring dieser Zeile (z. B. .handleEmailTriggerRequest()	--line erforderlich; speichert die vollständig getrimmte Zeile
Gleicher getrimmter Text in 2+ Zeilen	--line für das gewünschte Exemplar übergeben; Skript setzt occurrence
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 Bezeichnung oder einem anderen Elternteil. ensure ist get-or-create: gleiche Identität → "skipped": true (exit 0). Bei LINE ist die Identität Datei + getrimmter lineContent + das durch --line ausgewählte Exemplar (das Skript speichert occurrence; übergeben Sie es nicht). FILE/DIRECTORY-Identität ist Pfad + Typ. --trace-name, Beschreibung und Elternteil sind nicht Teil der Identität.

Generieren eines Baums: Bevorzugen Sie create_tree.py. Führen Sie kein search durch, wenn nicht nötig – 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 zum Überprüfen. Für einen einzelnen Knoten verwenden Sie ensure (get-or-create; keine Suche erforderlich) oder add (immer eine neue UUID).

Elternpfad: Bevorzugen Sie wiederholtes --parent-id vom wurzelwärtigen Vorfahren zum unmittelbaren Eltern. Für die Wurzel bei add / ensure weglassen. Kombinieren Sie nicht --parent-id mit --parent. Bloße Zeichenketten im JSON von --parent sind nur UUIDs, keine traceName-Bezeichnungen.

--parent-Form	Beispiel
Wurzel	--parent [] (für move zur Wurzel benötigt; add / ensure verwenden standardmäßig die Wurzel)
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, falls B bereits existierte) mit --parent-id idA --parent-id idB

Neubinden nach Festplatten-Änderungen: Agenten bearbeiten nicht über den IDE-Editor, daher ist eine Live-Verschiebung von Zeilen nicht anwendbar. Führen Sie nach jeder Runde, die den Projektquellcode geändert hat, rebind aus (optional --file für betroffene Pfade), 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 – lassen 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 mutierenden Aufrufen für jeden --no-refresh und dann am Ende einen einzigen request_refresh.py.

Erforderlicher Unterbefehl:

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

Parameter (gemeinsam; alle optional):

• --project <path>: Projektpfad (Standard: CWD).
• --profile <name>: Profilnamen-Überschreibung (Standard: <activeProfileName>).
• --dry-run: Kein XML 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 auf lineContent.
• --trace-name <text>: Teilstring-Übereinstimmung auf traceName.
• --type <LINE|FILE|DIRECTORY>: Filter nach Typ.

Parameter (add / ensure):

• Locator (erforderlich): --file + --line + --content für LINE (Teilstring dieser Zeile ist in Ordnung); --file für FILE/DIRECTORY. Oder positional DATEI ZEILE INHALT, oder Pfad.
• --parent-id <uuid> (optional): Elternknoten-UUID; von der Wurzel zum unmittelbaren Eltern wiederholen (bevorzugt). Für die Wurzel weglassen.
• --parent <json> (optional): JSON-Elternpfad (nicht mit --parent-id kombinieren).
• --trace-name <text> (optional): Trace-Punkt-Bezeichnung.
• --description <text> (optional): Beschreibung.
• --type <LINE|FILE|DIRECTORY> (optional): Typ-Überschreibung (Standard: LINE).

Parameter (move):

• Locator (erforderlich): --id, oder --file + --line + --content, oder --file allein für FILE/DIRECTORY.
• Neuer Elternteil (erforderlich): --parent-id (von der Wurzel zum unmittelbaren Eltern wiederholen) oder --parent JSON. Für die Wurzel --parent [] verwenden. --parent-id nicht mit --parent kombinieren.

Parameter (delete):

• Locator (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")

…

[dokumentation abgeschnitten für die Übersetzung]