saidake/code-trace-tree-jetbrains

Code Trace Tree (Árbol de Trazas de Código)

Construye y muestra flujos de trabajo de código como árboles anidados de puntos de trazado de línea, archivo y directorio. Usa los scripts Python proporcionados para operar el almacenamiento híbrido utilizado por los plugins de Code Trace Tree en las IDE, y luego pide a la IDE que recargue.

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

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 Python documentados usando la ruta absoluta.

Abre scripts/ o references/ solo si encuentras un problema crítico al usar la habilidad (script faltante o que falla, 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, o 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 Global del Agente	Ruta de Habilidad 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 usando python (o python3 si eso es lo que está en PATH). Mantén el CWD del proceso dentro del proyecto de la IDE (no hagas cd a la carpeta de la habilidad). Invocaciones directas: Operaciones del Árbol de Trazas. En PowerShell, consulta también Windows PowerShell.

Operaciones del Árbol de Trazas

Todas las llamadas a los scripts de la habilidad. Sustituye la Ruta de Habilidad del Agente absoluta para ESTE agente. Mantén el CWD del proceso en el proyecto de la 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 existe .idea/code-trace-tree.project.id pero el XML ha desaparecido, recrea el XML con ese mismo projectId. No crea ni sobrescribe el archivo de ID en .idea. 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 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 Configuración 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. 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 anidado de puntos de trazado 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 son agregados (sin asegurar cada hijo). No busques si no es necesario — este script ya asegura los nodos existentes. Usa search cuando necesites IDs (para seleccionar/mover/eliminar) o inspeccionar. Los localizadores LINE son los mismos que en trace_tree.py (archivo + línea + contenido). Ignora la ocurrencia del 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>: Nombre del perfil a usar (por defecto: <activeProfileName>).
• --dry-run: No escribe XML ni refresca.
• --no-refresh: Omite la señal de refresco a la IDE.
• --parent-id <uuid>: Padre existente; repite desde el ancestro raíz hasta el padre inmediato. Omite para la raíz del perfil.
• --parent <json>: JSON de la ruta del padre existente (no combinar con --parent-id).

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

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

Campos (cada nodo, incluidos hijos): file (requerido); type (LINE | FILE | DIRECTORY; omitir para inferir: line/content → LINE, si no, ruta en disco); LINE necesita line + content; name / description / children opcionales. No incluyas occurrenceIndex / totalOccurrences. children es un arreglo 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 que se agregó; los descendientes de ese nodo fueron agregados sin asegurar.

{
  "action": "create_tree",
  "profile": "<nombre-del-perfil>",
  "storage_xml": "<abs>",
  "parentId": "<uuid o vacío>",
  "created": 3,
  "skipped": 1,
  "ids": ["<uuid>", …],
  "roots": [ { "skipped": false, "created": true, "node": <objeto-nodo>, "children": [ … ] } ],
  "refreshed": true
}

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 "$PARENT_ID" --tree-file arbol.json

trace_tree.py

Busca, agrega, asegura, mueve, elimina y reenlaza nodos. Ignora la ocurrencia del 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> [banderas…]
python "<Ruta de Habilidad del Agente>/code-trace-tree/scripts/trace_tree.py" [banderas-compartidas] <subcomando> [banderas…]

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

Localizadores LINE: la traza almacenada 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 selecciona cuál copia. Ignora ocurrencia: no leas, pases ni computes occurrenceIndex / totalOccurrences. En PowerShell, protege el --content con comillas con --% (consulta Windows PowerShell) o usa un substring de la línea más --line. Nunca envuelvas el CLI en un helper que use un parámetro llamado $Args.

Sugerencia	Resultado
Línea exacta + texto recortado completo	Se usa tal cual
Substring distintivo de esa línea (ej. .handleEmailTriggerRequest()	--line requerido; almacena la línea completa recortada
Mismo texto recortado en 2+ líneas	Pasa --line para la copia deseada; el script establece la ocurrencia
Llamada de múltiples líneas	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 de la 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 (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 parte de la identidad.

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

Ruta del padre: prefiere repetir --parent-id desde el ancestro raíz hasta el padre inmediato. Omite para la raíz en add / ensure. No combines --parent-id con --parent. Las cadenas simples 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 a raíz)
ID de nodo en JSON	--parent '["3d41c2d1-…"]'
[archivo, línea, contenido]	--parent '[["src/A.java",10,"void methodA() {"]]'

definición método A
  llamada método B
    llamada método C   ← add (o ensure 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 de la IDE, por lo que el desplazamiento en vivo de líneas no aplica. Después de cualquier turno que haya modificado el código fuente del proyecto, ejecuta rebind (opcionalmente con --file para las rutas tocadas) antes de confiar en los localizadores o seleccionar/navegar. Rebind repara lineNumber a partir de lineContent recortado y recalcula ocurrencias. El arreglo "invalid" significa que esos localizadores LINE no fueron encontrados — deja esos nodos en el árbol; no los elimines a menos que el usuario haya solicitado eliminarlos.

Para muchas llamadas mutantes, usa --no-refresh en cada una, y luego una sola 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>: Nombre del perfil a usar (por defecto: <activeProfileName>).
• --dry-run: No escribe XML ni refresca.
• --no-refresh: Omite la señal de refresco a la 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>: Filtro 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 LINEA CONTENIDO, o ruta.
• --parent-id <uuid> (opcional): UUID del nodo padre; repite desde el ancestro raíz hasta el padre inmediato (preferido). Omite para la raíz.
• --parent <json> (opcional): JSON de la ruta del padre (no combinar con --parent-id).
• --trace-name <texto> (opcional): Etiqueta del punto de trazado.
• --description <texto> (opcional): Descripción.
• --type <LINE|FILE|DIRECTORY> (opcional): Tipo a usar (por defecto: LINE).

Parámetros (move):

• Localizador (requerido): --id, o --file + --line + --content, o --file solo para FILE/DIRECTORY.
• Nuevo padre (requerido): --parent-id (repite desde el ancestro 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 --file solo para FILE/DIRECTORY.

Parámetros (rebind; todos opcionales):

• --file <ruta>: Limitar a ruta(s) relativa(s); repetible. Por defecto: todos los nodos LINE en el 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.

node-object:

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

(Nota: El contenido original se truncó en la solicitud; se ha traducido la parte proporcionada manteniendo la estructura markdown, dejando el resto sin cambios ya que no estaba disponible. Si se necesita la traducción completa del archivo SKILL.md original, se debe proporcionar el texto completo.)