Code Trace Tree

Que fait Code Trace Tree ?

Construisez et affichez des flux de code sous forme d'arbres imbriqués de points de trace de lignes, fichiers et répertoires. Utilisez les scripts Python fournis pour manipuler le stockage hybride utilisé par les plugins Code Trace Tree pour l'IDE, puis demandez à l'IDE de recharger.

Modifiez ou synchronisez les traces uniquement lorsque l'utilisateur le demande explicitement (par exemple : générer des nœuds liés à un sujet, ajouter une astuce à une ligne, relier après des modifications). Ne synchronisez pas automatiquement à chaque tour. Ne supprimez jamais les points de trace existants (y compris ceux que rebind signale comme "invalid") sauf si l'utilisateur le demande explicitement.

Comment utiliser cette compétence

Lisez ce SKILL.md uniquement. Ne listez, n'explorez ni ne parcourez les dossiers scripts/ ou references/ de cette compétence, et n'ouvrez pas le code source des scripts pour apprendre l'API. Invoquez les commandes Python documentées en utilisant le chemin absolu.

Ouvrez scripts/ ou references/ uniquement si vous rencontrez un problème critique en utilisant la compétence (script manquant ou en crash, stockage corrompu, ou une erreur que ce fichier ne couvre pas).

Emplacement des scripts de la compétence

Les scripts d'aide se trouvent sous <Chemin de la compétence de l'agent>/code-trace-tree/scripts/.

Chemin de la compétence de l'agent est le répertoire des compétences de cet agent (le parent de code-trace-tree/) pour l'agent que vous exécutez — local au projet s'il est présent, sinon global. Il se termine par skills, pas par code-trace-tree. Les chemins correspondent à npx skills. Le tableau liste des exemples courants ; les autres agents listés fonctionnent de la même manière.

Agent (exemples)	Chemin global de la compétence	Chemin local au projet de la compétence
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

Sous Windows, ~ correspond à %USERPROFILE%. Résolvez le Chemin de la compétence de l'agent une fois par session. Invoquez les scripts avec des chemins absolus via python (ou python3 si c'est celui qui se trouve dans le PATH). Conservez le CWD du processus dans le projet IDE (ne faites pas cd dans le dossier de la compétence). Invocations directes : Opérations de l'arbre de trace. Avec PowerShell, consultez la section Windows PowerShell.

Opérations de l'arbre de trace

Tous les appels aux scripts de la compétence. Remplacez le Chemin de la compétence de l'agent absolu par celui de CET agent. Conservez le CWD du processus dans le projet IDE (ne faites pas cd dans le dossier de la compétence). Avec PowerShell, consultez la section 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

Résout l'ID du projet et le XML global lié. Si le stockage est manquant, le crée (Cas C). Si .idea/code-trace-tree.project.id existe mais que le XML a disparu, recrée le XML avec le même projectId. Ne crée/écrase pas le fichier .idea id. Les opérations mutantes create_tree et trace_tree add / ensure / move / delete / rebind créent également le stockage automatiquement. trace_tree search ne le crée pas automatiquement.

Utilisation

python "<Chemin de la compétence de l'agent>/code-trace-tree/scripts/resolve_storage.py" [chemin_du_projet]

Paramètres optionnels :

• [chemin_du_projet] : Chemin utilisé pour découvrir la racine du projet IDE (par défaut : CWD). Passez la racine du projet pour que le <path> XML soit correct.

Valeur de retour

La sortie standard est du JSON (indent=2, UTF-8). Les erreurs affichent ERROR: … sur stderr.

{
  "created": false,
  "project_root": "<abs>",
  "global_dir": "<Répertoire de config OS>/code-trace-tree",
  "project_id": "<uuid ou null>",
  "storage_xml": "<chemin xml abs>"
}

created est true lorsqu'un nouveau XML a été écrit. Code de sortie 0 en cas de succès ; 1 si la racine du projet n'a pas pu être trouvée.

Exemple :

python "<Chemin de la compétence de l'agent>/code-trace-tree/scripts/resolve_storage.py"
python "<Chemin de la compétence de l'agent>/code-trace-tree/scripts/resolve_storage.py" /chemin/vers/le/projet

create_tree.py

Crée un arbre de points de trace imbriqué en un seul appel. Garantit uniquement les racines de la charge utile (et les enfants des racines qui existent déjà). Une fois un nœud créé, ses descendants sont ajoutés (pas de garantie par enfant). Ne faites pas de search si ce n'est pas nécessaire — ce script assure déjà les nœuds existants. Utilisez search lorsque vous avez besoin d'IDs (sélectionner/déplacer/supprimer) ou pour inspecter. Les localisateurs LINE sont les mêmes que pour trace_tree.py (file + line + content). Ignorez l'occurrence du contenu de la ligne (occurrenceIndex / totalOccurrences) — le script la calcule. Préférez --tree-file avec PowerShell.

L'option --parent-id attache la charge utile sous un nœud existant (ce parent est résolu, pas garanti).

Utilisation

python "<Chemin de la compétence de l'agent>/code-trace-tree/scripts/create_tree.py" --tree-file arbre.json
python "<Chemin de la compétence de l'agent>/code-trace-tree/scripts/create_tree.py" arbre.json
python "<Chemin de la compétence de l'agent>/code-trace-tree/scripts/create_tree.py" --tree '<json>'

Paramètres requis (une seule source d'arbre) :

• --tree-file <chemin> : Fichier JSON (- = entrée standard). Préférez ceci à --tree.
• --tree <json> : Chaîne JSON.
• Positionnel <chemin> : identique à --tree-file.

Paramètres (partagés ; tous optionnels) :

• --project <chemin> : Chemin du projet (par défaut : CWD).
• --profile <nom> : Surcharge du nom de profil (par défaut : <nomProfilActif>).
• --dry-run : N'écrit pas le XML et n'actualise pas.
• --no-refresh : Ignore le signal d'actualisation de l'IDE.
• --parent-id <uuid> : Parent existant ; répétez de la racine vers le parent immédiat. Omettez pour la racine du profil.
• --parent <json> : Chemin du parent existant en JSON (ne combinez pas avec --parent-id).

JSON de l'arbre (un objet nœud, ou un tableau d'objets nœuds). Chaque nœud utilise la même forme, y compris les children (description sur chaque nœud, pas seulement sur la racine) :

{
  "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": ""
        }
      ]
    }
  ]
}

Champs (chaque nœud, y compris les enfants) : file (obligatoire) ; type (LINE | FILE | DIRECTORY ; omettez pour inférer : line/content → LINE, sinon chemin sur disque) ; LINE nécessite line + content ; name / description / children optionnels. N'incluez pas occurrenceIndex / totalOccurrences. children est un tableau des mêmes objets.

Valeur de retour

La sortie standard est du JSON (indent=2, UTF-8). skipped: true sur un nœud signifie que la garantie a trouvé le nœud ; les enfants de ce nœud sont toujours garantis. created: true signifie ajout ; les descendants de ce nœud ont été ajoutés sans garantie.

{
  "action": "create_tree",
  "profile": "<nom-du-profil>",
  "storage_xml": "<abs>",
  "parentId": "<uuid ou vide>",
  "created": 3,
  "skipped": 1,
  "ids": ["<uuid>", …],
  "roots": [ { "skipped": false, "created": true, "node": <objet-nœud>, "children": [ … ] } ],
  "refreshed": true
}

Code de sortie 0 en cas de succès.

Exemple :

python "<Chemin de la compétence de l'agent>/code-trace-tree/scripts/create_tree.py" --tree-file arbre.json
python "<Chemin de la compétence de l'agent>/code-trace-tree/scripts/create_tree.py" --parent-id "$PARENT_ID" --tree-file arbre.json

trace_tree.py

Recherche, ajoute, garantit, déplace, supprime et relie les nœuds. Ignorez l'occurrence du contenu de la ligne (occurrenceIndex / totalOccurrences) — ne passez jamais ces champs ; le script les calcule.

Utilisation

python "<Chemin de la compétence de l'agent>/code-trace-tree/scripts/trace_tree.py" <sous-commande> [drapeaux…]
python "<Chemin de la compétence de l'agent>/code-trace-tree/scripts/trace_tree.py" [drapeaux-partagés] <sous-commande> [drapeaux…]

Les drapeaux partagés (--project, --profile, --dry-run, --no-refresh) peuvent apparaître avant ou après la sous-commande. Omettez --project lorsque le CWD est déjà dans le projet IDE (les scripts remontent pour trouver .vscode / .idea / .git, ou d'autres marqueurs de projet courants). Profil par défaut : <nomProfilActif>.

Localisateurs LINE : l'astuce stockée est [fichier, ligne, ligne-trimée-complète]. --line est obligatoire. Le script vérifie le texte trimé à cette ligne, stocke la ligne trimée complète (une sous-chaîne --content est développée), puis définit occurrenceIndex / totalOccurrences en scannant le fichier. Les lignes trimées en double dans un même fichier sont distinctes car --line choisit quelle copie. Ignorez l'occurrence : ne lisez, ne passez et ne calculez pas occurrenceIndex / totalOccurrences. Avec PowerShell, protégez le --content entre guillemets avec --% (voir Windows PowerShell) ou utilisez une astuce sous-chaîne plus --line. N'encapsulez jamais le CLI dans un assistant qui utilise un paramètre nommé $Args.

Astuce	Résultat
Ligne exacte + texte trimé complet	Utilisé tel quel
Sous-chaîne distinctive de cette ligne (ex. .handleEmailTriggerRequest()	--line obligatoire ; stocke la ligne trimée complète
Même texte trimé sur 2+ lignes	Passez --line pour la copie visée ; le script définit l'occurrence
Appel multi-ligne	Préférez la ligne physique la plus distinctive (souvent la continuation .nomMéthode()

add vs ensure : add crée toujours un nouvel UUID (comme le plugin IDE). Utilisez-le pour un second nœud sur la même ligne avec une étiquette ou un parent différent. ensure est get-or-create : même identité → "skipped": true (code sortie 0). Pour LINE, l'identité est fichier + lineContent trimé + la copie sélectionnée par --line (le script stocke l'occurrence ; ne la passez pas). L'identité FILE/DIRECTORY est chemin + type. --trace-name, description et parent ne font pas partie de l'identité.

Génération d'un arbre : préférez create_tree.py. Ne faites pas de search si ce n'est pas nécessaire — le script assure les nœuds existants et ajoute les sous-arbres. Utilisez search lorsque vous avez besoin d'IDs pour sélectionner/déplacer/supprimer ou pour inspecter. Pour un seul nœud, utilisez ensure (get-or-create ; pas besoin de recherche) ou add (toujours un nouvel UUID).

Chemin parent : préférez des --parent-id répétés depuis l'ancêtre racine jusqu'au parent immédiat. Omettez pour la racine pour add / ensure. Ne combinez pas --parent-id avec --parent. Les chaînes nues dans le JSON --parent sont uniquement des UUIDs, pas des étiquettes traceName.

Forme --parent	Exemple
Racine	--parent [] (nécessaire pour move vers la racine ; add / ensure par défaut à la racine)
ID de nœud en JSON	--parent '["3d41c2d1-…"]'
[fichier, ligne, contenu]	--parent '[["src/A.java",10,"void methodA() {"]]'

def method A
  appel method B
    appel method C   ← ajoutez (ou assurez si B existait déjà) avec --parent-id idA --parent-id idB

Relier après des modifications sur disque : Les agents ne modifient pas via l'éditeur IDE, donc le décalage de ligne en direct ne s'applique pas. Après tout tour qui a modifié le code source du projet, exécutez rebind (optionnellement --file pour les chemins touchés) avant de vous fier aux localisateurs ou de sélectionner/naviguer. Rebind répare lineNumber à partir de lineContent trimé et recalcule les occurrences. Le tableau "invalid" signifie que ces localisateurs LINE n'ont pas été trouvés — laissez ces nœuds dans l'arbre ; ne les delete pas sauf si l'utilisateur a demandé à les supprimer.

Pour plusieurs appels mutants, utilisez --no-refresh sur chacun, puis un seul request_refresh.py à la fin.

Sous-commande obligatoire :

• <sous-commande> : search | add | ensure | move | delete | rebind

Paramètres (partagés ; tous optionnels) :

• --project <chemin> : Chemin du projet (par défaut : CWD).
• --profile <nom> : Surcharge du nom de profil (par défaut : <nomProfilActif>).
• --dry-run : N'écrit pas le XML et n'actualise pas.
• --no-refresh : Ignore le signal d'actualisation de l'IDE.

Paramètres (search ; tous optionnels) :

• --id <uuid> : UUID du nœud.
• --file <chemin> : Chemin relatif du fichier/répertoire.
• --line <n> : Numéro de ligne basé sur 1.
• --content <texte> : Correspondance de sous-chaîne sur lineContent.
• --trace-name <texte> : Correspondance de sous-chaîne sur traceName.
• --type <LINE|FILE|DIRECTORY> : Filtrer par type.

Paramètres (add / ensure) :

• Localisateur (obligatoire) : --file + --line + --content pour LINE (une sous-chaîne de cette ligne est OK) ; --file pour FILE/DIRECTORY. Ou positionnel FICHIER LIGNE CONTENU, ou chemin.
• --parent-id <uuid> (optionnel) : UUID du nœud parent ; répétez de la racine vers le parent immédiat (préféré). Omettez pour la racine.
• --parent <json> (optionnel) : Chemin parent en JSON (ne combinez pas avec --parent-id).
• --trace-name <texte> (optionnel) : Étiquette du point de trace.
• --description <texte> (optionnel) : Description.
• --type <LINE|FILE|DIRECTORY> (optionnel) : Surcharge du type (par défaut : LINE).

Paramètres (move) :

• Localisateur (obligatoire) : --id, ou --file + --line + --content, ou --file seul pour FILE/DIRECTORY.
• Nouveau parent (obligatoire) : --parent-id (répétez de la racine vers le parent immédiat) ou JSON --parent. Pour la racine, utilisez --parent []. Ne combinez pas --parent-id avec --parent.

Paramètres (delete) :

• Localisateur (obligatoire) : --id, ou --file + --line + --content, ou --file seul pour FILE/DIRECTORY.

Paramètres (rebind ; tous optionnels) :

• --file <chemin> : Limiter aux chemins relatifs ; répétable. Par défaut : tous les nœuds LINE du profil.

Valeur de retour

La sortie standard est du JSON (indent=2, UTF-8). Les erreurs affichent ERROR: … sur stderr et un code de sortie non nul.

node-object :

{
  "id": "<uuid>",
  "parentId": "<uuid ou vide>",
  "type": "LINE|FILE|DIRECTORY",
  "file": "<chemin relatif>",
  "line": "<n ou vide>",
  "content": "<lineContent trimé>",
  "name": "<traceName>",
  "depth": 0,
  "childCount": 0
}

search :

{
  "project_root": "<abs>",
  "storage_xml": "<abs>",
  "profile": "<nom-du-profil>",
  "matches": [ <objet-nœud>, … ]
}

add (toujours créé ; pas de "skipped")