Code Trace Tree

¿Qué hace Code Trace Tree?

Construye y muestra flujos de trabajo de código como árboles anidados de puntos de rastreo de líneas, archivos y directorios. Utiliza los scripts de Python proporcionados para operar el almacenamiento híbrido usado por los plugins de Code Trace Tree IDE y luego pide al IDE que recargue.

Solo edita o sincroniza trazas cuando el usuario lo solicite explícitamente (por ejemplo: generar nodos relacionados con un tema, añadir un consejo en una línea, reenlazar después de ediciones). No sincronices automáticamente en cada turno. Nunca elimines puntos de rastreo existentes (incluyendo aquellos que rebind reporta como "invalid") a menos que el usuario lo pida explícitamente.

Cómo usar esta habilidad

Lee solo este SKILL.md. No listes, busques ni explores las carpetas scripts/ o references/ de esta habilidad, y no abras el código fuente de los scripts para aprender la API. Invoca los comandos de Python documentados mediante la ruta absoluta.

Abre scripts/ o references/ solo si encuentras un problema crítico al usar la habilidad (script faltante o con error, almacenamiento corrupto, o un error que este archivo no cubre).

Ubicación de los scripts de la habilidad

Los scripts auxiliares se encuentran en <Ruta de Habilidad del Agente>/code-trace-tree/scripts/.

Ruta de Habilidad del Agente es el directorio de habilidades de este agente (el padre de code-trace-tree/) para el agente que estás ejecutando — local al proyecto si existe, global en caso contrario. Termina en skills, no en code-trace-tree. Las rutas coinciden con npx skills. La tabla muestra ejemplos comunes; otros agentes listados funcionan igual.

Agente (ejemplos)	Ruta de Habilidad del Agente Global	Ruta de Habilidad del Agente Local al Proyecto
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

En Windows, ~ es %USERPROFILE%. Resuelve la Ruta de Habilidad del Agente una vez por sesión. Invoca los scripts con rutas absolutas mediante python (o python3 si es lo que está en PATH). Mantén el CWD del proceso en el proyecto del IDE (no hagas cd a la carpeta de la habilidad). Invocaciones directas: Operaciones de Árbol de Traza. En PowerShell, consulta también Windows PowerShell.

Operaciones de Árbol de Traza

Todas las llamadas a scripts de la habilidad. Sustituye la Ruta de Habilidad del Agente absoluta para ESTE agente. Mantén el CWD del proceso en el proyecto del IDE (no hagas cd a la carpeta de la habilidad). En PowerShell, consulta 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

Resuelve el ID del proyecto y el XML global vinculado. Si el almacenamiento falta, lo crea (Caso C). Si .idea/code-trace-tree.project.id existe pero el XML ha desaparecido, recrea el XML con el mismo projectId. No crea/sobrescribe el archivo .idea de id. Las operaciones mutantes create_tree y trace_tree add / ensure / move / delete / rebind también crean el almacenamiento automáticamente. trace_tree search no lo crea automáticamente.

Uso

python "<Ruta de Habilidad del Agente>/code-trace-tree/scripts/resolve_storage.py" [ruta_del_proyecto]

Parámetros Opcionales:

• [ruta_del_proyecto]: Ruta utilizada para descubrir la raíz del proyecto del IDE (por defecto: CWD). Pasa la raíz del proyecto para que el <path> del XML sea correcto.

Valor de retorno

La salida estándar es JSON (indent=2, UTF-8). Los errores imprimen ERROR: … en stderr.

{
  "created": false,
  "project_root": "<abs>",
  "global_dir": "<Directorio de Config del SO>/code-trace-tree",
  "project_id": "<uuid o null>",
  "storage_xml": "<ruta xml absoluta>"
}

created es true cuando se ha escrito un nuevo XML. Código de salida 0 en éxito; 1 si no se puede encontrar la raíz del proyecto.

Ejemplo:

python "<Ruta de Habilidad del Agente>/code-trace-tree/scripts/resolve_storage.py"
python "<Ruta de Habilidad del Agente>/code-trace-tree/scripts/resolve_storage.py" /ruta/al/proyecto

create_tree.py

Crea un árbol de puntos de rastreo anidados en una sola llamada. Asegura solo las raíces de la carga útil (y los hijos de raíces que ya existen). Una vez que un nodo es creado, sus descendientes se añaden (sin asegurar por hijo). No hagas search si no es necesario — este script ya asegura los nodos existentes. Usa search cuando necesites ids (seleccionar/mover/eliminar) o para inspeccionar. Los localizadores LINE son los mismos que en trace_tree.py (archivo + línea + contenido). Ignora la ocurrencia de contenido de línea (occurrenceIndex / totalOccurrences) — el script la calcula. Prefiere --tree-file en PowerShell.

El parámetro opcional --parent-id adjunta la carga útil bajo un nodo existente (ese padre se resuelve, no se asegura).

Uso

python "<Ruta de Habilidad del Agente>/code-trace-tree/scripts/create_tree.py" --tree-file arbol.json
python "<Ruta de Habilidad del Agente>/code-trace-tree/scripts/create_tree.py" arbol.json
python "<Ruta de Habilidad del Agente>/code-trace-tree/scripts/create_tree.py" --tree '<json>'

Parámetros Requeridos (exactamente una fuente de árbol):

• --tree-file <ruta>: Archivo JSON (- = stdin). Prefiere esto sobre --tree.
• --tree <json>: Cadena JSON.
• Posicional <ruta>: igual que --tree-file.

Parámetros (compartidos; todos opcionales):

• --project <ruta>: Ruta del proyecto (por defecto: CWD).
• --profile <nombre>: Sobrescribe el nombre del perfil (por defecto: <activeProfileName>).
• --dry-run: No escribe XML ni refresca.
• --no-refresh: Omite la señal de refresco del IDE.
• --parent-id <uuid>: Padre existente; repite desde la raíz hacia el padre inmediato. Omítelo para la raíz del perfil.
• --parent <json>: Ruta JSON del padre existente (no lo combines con --parent-id).

JSON del Árbol (un objeto nodo, o un array de objetos nodo). Cada nodo usa la misma forma, incluyendo children (description en cada nodo, no solo en la raíz):

{
  "archivo": "src/A.java",
  "línea": 10,
  "contenido": "void methodA() {",
  "nombre": "methodA",
  "descripción": "",
  "tipo": "LINE",
  "hijos": [
    {
      "archivo": "src/B.java",
      "línea": 40,
      "contenido": "void methodB() {",
      "nombre": "methodB",
      "descripción": "",
      "tipo": "LINE",
      "hijos": [
        {
          "archivo": "src/C.java",
          "línea": 20,
          "contenido": "void methodC() {",
          "nombre": "methodC",
          "descripción": "",
          "tipo": "LINE"
        },
        {
          "tipo": "FILE",
          "archivo": "src/Util.java",
          "nombre": "Util",
          "descripción": ""
        }
      ]
    }
  ]
}

Campos (cada nodo, incluyendo hijos): archivo (requerido); tipo (LINE | FILE | DIRECTORY; omítelo para inferir: línea/contenido → LINE, si no, ruta en disco); LINE necesita línea + contenido; nombre / descripción / hijos opcionales. No incluyas occurrenceIndex / totalOccurrences. hijos es un array de los mismos objetos.

Valor de retorno

La salida estándar es JSON (indent=2, UTF-8). skipped: true en un nodo significa que ensure lo encontró; los hijos de ese nodo aún se aseguran. created: true significa añadido; los descendientes de ese nodo se añadieron sin asegurar.

{
  "acción": "create_tree",
  "perfil": "<nombre-del-perfil>",
  "xml_almacenamiento": "<abs>",
  "id_padre": "<uuid o vacío>",
  "creados": 3,
  "saltados": 1,
  "ids": ["<uuid>", …],
  "raíces": [ { "saltado": false, "creado": true, "nodo": <objeto-nodo>, "hijos": [ … ] } ],
  "refrescado": true
}

Código de salida 0 en éxito.

Ejemplo:

python "<Ruta de Habilidad del Agente>/code-trace-tree/scripts/create_tree.py" --tree-file arbol.json
python "<Ruta de Habilidad del Agente>/code-trace-tree/scripts/create_tree.py" --parent-id "$ID_PADRE" --tree-file arbol.json

trace_tree.py

Busca, añade, asegura, mueve, elimina y reenlaza nodos. Ignora la ocurrencia de contenido de línea (occurrenceIndex / totalOccurrences) — nunca pases esos campos; el script los calcula.

Uso

python "<Ruta de Habilidad del Agente>/code-trace-tree/scripts/trace_tree.py" <subcomando> [flags…]
python "<Ruta de Habilidad del Agente>/code-trace-tree/scripts/trace_tree.py" [flags-compartidos] <subcomando> [flags…]

Los flags compartidos (--project, --profile, --dry-run, --no-refresh) pueden aparecer antes o después del subcomando. Omite --project cuando el CWD ya está dentro del proyecto del IDE (los scripts recorren hacia arriba para encontrar .vscode / .idea / .git, u otros marcadores de proyecto comunes). Perfil por defecto: <activeProfileName>.

Localizadores LINE: el consejo almacenado es [archivo, línea, línea-completa-recortada]. --line es requerido. El script verifica el texto recortado en esa línea, almacena la línea completa recortada (un substring --content se expande), luego establece occurrenceIndex / totalOccurrences escaneando el archivo. Las líneas recortadas duplicadas en un mismo archivo son distintas porque --line elige qué copia. Ignora ocurrencia: no leas, pases ni calcules occurrenceIndex / totalOccurrences. En PowerShell, protege el --content entre comillas con --% (consulta Windows PowerShell) o usa un consejo substring más --line. Nunca envuelvas la CLI en un helper que use un parámetro llamado $Args.

Consejo	Resultado
Línea exacta + texto recortado completo	Se usa tal cual
Substring distintivo de esa línea (ej. .handleEmailTriggerRequest()	Se requiere --line; almacena la línea completa recortada
Mismo texto recortado en 2+ líneas	Pasa --line para la copia deseada; el script establece ocurrencia
Llamada multilínea	Prefiere la línea física más distintiva (a menudo la continuación .methodName()

add vs ensure: add siempre crea un nuevo UUID (igual que el plugin del IDE). Úsalo para un segundo nodo en la misma línea con una etiqueta o padre diferente. ensure es obtener-o-crear: misma identidad → "skipped": true (código de salida 0). Para LINE, la identidad es archivo + lineContent recortado + la copia seleccionada por --line (el script almacena la ocurrencia; no la pases). La identidad de FILE/DIRECTORY es ruta + tipo. --trace-name, descripción y padre no son identidad.

Generar un árbol: prefiere create_tree.py. No hagas search si no es necesario — el script asegura los nodos existentes y añade nuevos subárboles. Usa search cuando necesites ids para seleccionar/mover/eliminar o inspeccionar. Para un solo nodo, usa ensure (obtener-o-crear; no requiere búsqueda) o add (siempre un nuevo UUID).

Ruta del padre: prefiere --parent-id repetido desde el ancestro raíz hasta el padre inmediato. Omítelo para la raíz en add / ensure. No combines --parent-id con --parent. Las cadenas sin formato dentro del JSON de --parent son solo UUIDs, no etiquetas traceName.

Forma de --parent	Ejemplo
Raíz	--parent [] (necesario para move a raíz; add / ensure por defecto van a la raíz)
Id de nodo en JSON	--parent '["3d41c2d1-…"]'
[archivo, línea, contenido]	--parent '[["src/A.java",10,"void methodA() {"]]'

def método A
  llamada método B
    llamada método C   ← añadir (o asegurar si B ya existía) con --parent-id idA --parent-id idB

Reenlazar después de ediciones en disco: Los agentes no editan a través del editor del IDE, por lo que el desplazamiento de líneas en vivo no aplica. Después de cualquier turno que haya modificado el código fuente del proyecto, ejecuta rebind (opcionalmente --file para las rutas tocadas) antes de confiar en los localizadores o en la selección/navegación. Rebind repara lineNumber a partir de lineContent recortado y recalcula las ocurrencias. El array "invalid" significa que esos localizadores LINE no se encontraron — deja esos nodos en el árbol; no los elimines a menos que el usuario haya pedido eliminarlos.

Para muchas llamadas mutantes, usa --no-refresh en cada una, luego un solo request_refresh.py al final.

Subcomando Requerido:

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

Parámetros (compartidos; todos opcionales):

• --project <ruta>: Ruta del proyecto (por defecto: CWD).
• --profile <nombre>: Sobrescribe el nombre del perfil (por defecto: <activeProfileName>).
• --dry-run: No escribe XML ni refresca.
• --no-refresh: Omite la señal de refresco del IDE.

Parámetros (search; todos opcionales):

• --id <uuid>: UUID del nodo.
• --file <ruta>: Ruta relativa de archivo/directorio.
• --line <n>: Número de línea (base 1).
• --content <texto>: Coincidencia de substring en lineContent.
• --trace-name <texto>: Coincidencia de substring en traceName.
• --type <LINE|FILE|DIRECTORY>: Filtrar por tipo.

Parámetros (add / ensure):

• Localizador (requerido): --file + --line + --content para LINE (un substring de esa línea está bien); --file para FILE/DIRECTORY. O posicional ARCHIVO LÍNEA CONTENIDO, o ruta.
• --parent-id <uuid> (opcional): UUID del nodo padre; repite desde la raíz hasta el padre inmediato (preferido). Omítelo para la raíz.
• --parent <json> (opcional): Ruta JSON del padre (no lo combines con --parent-id).
• --trace-name <texto> (opcional): Etiqueta del punto de rastreo.
• --description <texto> (opcional): Descripción.
• --type <LINE|FILE|DIRECTORY> (opcional): Sobrescribe el tipo (por defecto: LINE).

Parámetros (move):

• Localizador (requerido): --id, o --file + --line + --content, o solo --file para FILE/DIRECTORY.
• Nuevo padre (requerido): --parent-id (repite desde la raíz hasta el padre inmediato) o --parent JSON. Para la raíz, usa --parent []. No combines --parent-id con --parent.

Parámetros (delete):

• Localizador (requerido): --id, o --file + --line + --content, o solo --file para FILE/DIRECTORY.

Parámetros (rebind; todos opcionales):

• --file <ruta>: Limitar a una o más rutas relativas; repetible. Por defecto: todos los nodos LINE del perfil.

Valor de retorno

La salida estándar es JSON (indent=2, UTF-8). Los errores imprimen ERROR: … en stderr y salen con código distinto de cero.

objeto-nodo:

{
  "id": "<uuid>",
  "parentId": "<uuid o vacío>",
  "type": "LINE|FILE|DIRECTORY",
  "file": "<ruta relativa>",
  "line": "<n o vacío>",
  "content": "<lineContent recortado>",
  "name": "<traceName>",
  "depth": 0,
  "childCount": 0
}

search:

{
  "project_root": "<abs>",
  "storage_xml": "<abs>",
  "profile": "<nombre-del-perfil>",
  "matches": [ <objeto-nodo>, … ]
}

add (siempre creado; sin "skipped"

…

[truncado para traducción]