saidake/árvore-de-trace-de-código-jetbrains

Code Trace Tree (Árvore de Trace de Código)

Construa e exiba fluxos de trabalho de código como árvores aninhadas de pontos de rastreamento (pontos de trace) de linha, arquivo e diretório. Use os scripts Python fornecidos para operar o armazenamento híbrido usado pelos plugins Code Trace Tree da IDE e, em seguida, peça à IDE para recarregar.

Apenas edite ou sincronize traces quando o usuário pedir explicitamente (por exemplo: gerar nós relacionados a um tópico, adicionar uma dica em uma linha, religar após edições). Não faça sincronização automática a cada turno. Nunca delete pontos de rastreamento existentes (incluindo aqueles que o rebind reporta como "invalid") a menos que o usuário peça explicitamente para removê-los.

Como usar esta skill

Leia apenas este SKILL.md. Não liste, pesquise ou explore as pastas scripts/ ou references/ desta skill e não abra o código-fonte dos scripts para aprender a API. Invoque os comandos Python documentados pelo caminho absoluto.

Abra scripts/ ou references/ apenas se você encontrar um problema crítico ao usar a skill (script ausente ou com falha, armazenamento corrompido ou um erro que este arquivo não cobre).

Localização dos scripts da skill

Os scripts auxiliares estão em <Caminho da Skill do Agente>/code-trace-tree/scripts/.

Caminho da Skill do Agente é o diretório de skills deste agente (o pai de code-trace-tree/) para o agente que você está executando — local ao projeto, se presente, caso contrário, global. Ele termina em skills, não em code-trace-tree. Os caminhos correspondem a npx skills. A tabela lista exemplos comuns; outros agentes listados funcionam da mesma forma.

Agente (exemplos)	Caminho Global da Skill do Agente	Caminho Local da Skill do Agente (projeto)
Claude Code	~/.claude/skills	<repositorio>/.claude/skills
Cursor	~/.cursor/skills	<repositorio>/.agents/skills
GitHub Copilot	~/.copilot/skills	<repositorio>/.agents/skills
Codex	~/.codex/skills	<repositorio>/.agents/skills
Gemini CLI	~/.gemini/skills	<repositorio>/.agents/skills

No Windows, ~ é %USERPROFILE%. Resolva o Caminho da Skill do Agente uma vez por sessão. Invoque scripts com caminhos absolutos via python (ou python3 se for o que estiver no PATH). Mantenha o CWD do processo no projeto da IDE (não use cd para a pasta da skill). Invocações diretas: Operações de Árvore de Trace. No PowerShell, veja também Windows PowerShell.

Operações de Árvore de Trace

Todas as chamadas de script da skill. Substitua o Caminho da Skill do Agente absoluto para ESTE agente. Mantenha o CWD do processo no projeto da IDE (não use cd para a pasta da skill). No PowerShell, veja 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

Resolva o ID do projeto e o XML global vinculado. Se o armazenamento estiver faltando, crie-o (Caso C). Se .idea/code-trace-tree.project.id existir, mas o XML tiver sumido, recria o XML com esse mesmo projectId. Não cria/sobrescreve o arquivo .idea de id. As operações de mutação create_tree e trace_tree add / ensure / move / delete / rebind também criam o armazenamento automaticamente. trace_tree search não cria automaticamente.

Uso

python "<Caminho da Skill do Agente>/code-trace-tree/scripts/resolve_storage.py" [caminho_do_projeto]

Parâmetros Opcionais:

• [caminho_do_projeto]: Caminho usado para descobrir a raiz do projeto da IDE (padrão: CWD). Passe a raiz do projeto para que o <path> do XML fique correto.

Valor de retorno

Stdout é JSON (indent=2, UTF-8). Erros imprimem ERROR: … no stderr.

{
  "created": false,
  "project_root": "<abs>",
  "global_dir": "<Diretório de Config do SO>/code-trace-tree",
  "project_id": "<uuid or null>",
  "storage_xml": "<caminho absoluto do xml>"
}

created é true quando um novo XML foi escrito. Saída 0 em caso de sucesso; 1 se a raiz do projeto não puder ser encontrada.

Exemplo:

python "<Caminho da Skill do Agente>/code-trace-tree/scripts/resolve_storage.py"
python "<Caminho da Skill do Agente>/code-trace-tree/scripts/resolve_storage.py" /caminho/para/projeto

create_tree.py

Crie uma árvore aninhada de pontos de rastreamento em uma única chamada. Garante apenas as raízes do payload (e filhos de raízes que já existem). Uma vez que um nó é criado, seus descendentes são adicionados (sem garantia por filho). Não use search se não for necessário — este script já garante nós existentes. Use search quando precisar de ids (para selecionar/mover/deletar) ou para inspecionar. Localizadores LINE são os mesmos de trace_tree.py (arquivo + linha + conteúdo). Ignore a ocorrência de conteúdo de linha (occurrenceIndex / totalOccurrences) — o script calcula. Prefira --tree-file no PowerShell.

Opcional --parent-id anexa o payload sob um nó existente (esse pai é resolvido, não garantido).

Uso

python "<Caminho da Skill do Agente>/code-trace-tree/scripts/create_tree.py" --tree-file arvore.json
python "<Caminho da Skill do Agente>/code-trace-tree/scripts/create_tree.py" arvore.json
python "<Caminho da Skill do Agente>/code-trace-tree/scripts/create_tree.py" --tree '<json>'

Parâmetros Obrigatórios (exatamente uma fonte de árvore):

• --tree-file <caminho>: Arquivo JSON (- = stdin). Prefira este em vez de --tree.
• --tree <json>: String JSON.
• Posicional <caminho>: mesmo que --tree-file.

Parâmetros (compartilhados; todos opcionais):

• --project <caminho>: Caminho do projeto (padrão: CWD).
• --profile <nome>: Substituição do nome do perfil (padrão: <activeProfileName>).
• --dry-run: Não escrever XML ou recarregar.
• --no-refresh: Pular o sinal de recarregamento da IDE.
• --parent-id <uuid>: Pai existente; repita da raiz em direção ao pai → pai imediato. Omita para a raiz do perfil.
• --parent <json>: JSON do caminho do pai existente (não combine com --parent-id).

JSON da Árvore (um objeto de nó, ou um array de objetos de nó). Cada nó usa a mesma forma, incluindo children (description em cada nó, não apenas na raiz):

{
  "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 nó, incluindo filhos): file (obrigatório); type (LINE | FILE | DIRECTORY; omita para inferir: line/content → LINE, senão caminho no disco); LINE precisa de line + content; name / description / children opcionais. Não inclua occurrenceIndex / totalOccurrences. children é um array dos mesmos objetos.

Valor de retorno

Stdout é JSON (indent=2, UTF-8). skipped: true em um nó significa que a garantia o encontrou; os filhos desse nó ainda são garantidos. created: true significa adicionado; os descendentes desse nó foram adicionados sem garantia.

{
  "action": "create_tree",
  "profile": "<nome-do-perfil>",
  "storage_xml": "<abs>",
  "parentId": "<uuid or empty>",
  "created": 3,
  "skipped": 1,
  "ids": ["<uuid>", …],
  "roots": [ { "skipped": false, "created": true, "node": <objeto-nó>, "children": [ … ] } ],
  "refreshed": true
}

Saída 0 em caso de sucesso.

Exemplo:

python "<Caminho da Skill do Agente>/code-trace-tree/scripts/create_tree.py" --tree-file arvore.json
python "<Caminho da Skill do Agente>/code-trace-tree/scripts/create_tree.py" --parent-id "$PARENT_ID" --tree-file arvore.json

trace_tree.py

Pesquise, adicione, garanta, mova, delete e religue nós. Ignore a ocorrência de conteúdo de linha (occurrenceIndex / totalOccurrences) — nunca passe esses campos; o script os calcula.

Uso

python "<Caminho da Skill do Agente>/code-trace-tree/scripts/trace_tree.py" <subcomando> [flags…]
python "<Caminho da Skill do Agente>/code-trace-tree/scripts/trace_tree.py" [flags-compartilhadas] <subcomando> [flags…]

Flags compartilhadas (--project, --profile, --dry-run, --no-refresh) podem aparecer antes ou depois do subcomando. Omita --project quando o CWD já estiver dentro do projeto da IDE (os scripts sobem para encontrar .vscode / .idea / .git, ou outros marcadores comuns de projeto). Perfil padrão: <activeProfileName>.

Localizadores LINE: a dica armazenada é [arquivo, linha, linha-total-ajustada]. --line é obrigatório. O script verifica o texto ajustado naquela linha, armazena a linha total ajustada (uma substring --content é expandida), então define occurrenceIndex / totalOccurrences escaneando o arquivo. Linhas ajustadas duplicadas em um arquivo são distintas porque --line escolhe qual cópia. Ignore ocorrência: não leia, passe ou compute occurrenceIndex / totalOccurrences. No PowerShell, proteja --content entre aspas com --% (veja Windows PowerShell) ou use uma substring da dica mais --line. Nunca envolva o CLI em um auxiliar que use um parâmetro chamado $Args.

Dica	Resultado
Linha exata + texto ajustado completo	Usado como está
Substring distinta dessa linha (ex.: .handleEmailTriggerRequest()	--line obrigatório; armazena a linha ajustada completa
Mesmo texto ajustado em 2+ linhas	Passe --line para a cópia pretendida; o script define a ocorrência
Chamada multilinha	Prefira a linha física mais distinta (geralmente a continuação .methodName()

add vs ensure: add sempre cria um novo UUID (igual ao plugin da IDE). Use para um segundo nó na mesma linha com um rótulo ou pai diferente. ensure é obter-ou-criar: mesma identidade → "skipped": true (saída 0). Para LINE, identidade é arquivo + lineContent ajustado + a cópia selecionada por --line (o script armazena ocorrência; não passe). Para FILE/DIRECTORY, identidade é caminho + tipo. --trace-name, descrição e pai não são identidade.

Gerando uma árvore: prefira create_tree.py. Não use search se não for necessário — o script garante nós existentes e adiciona novas subárvores. Use search quando precisar de ids para selecionar/mover/deletar ou para inspecionar. Para um único nó, use ensure (obter-ou-criar; nenhuma pesquisa necessária) ou add (sempre um novo UUID).

Caminho do pai: prefira --parent-id repetido do ancestral em direção à raiz → pai imediato. Omita para raiz em add / ensure. Não combine --parent-id com --parent. Strings simples dentro do JSON --parent são apenas UUIDs, não rótulos traceName.

Forma --parent	Exemplo
Raiz	--parent [] (necessário para move para raiz; add / ensure padrão é raiz)
ID do nó em JSON	--parent '["3d41c2d1-…"]'
[arquivo, linha, conteúdo]	--parent '[["src/A.java",10,"void methodA() {"]]'

método A def
  chamada método B
    chamada método C   ← adicione (ou garanta se B já existia) com --parent-id idA --parent-id idB

Religar após edições no disco: Agentes não editam através do editor da IDE, então a mudança de linha ao vivo não se aplica. Após qualquer turno que modificou o código-fonte do projeto, execute rebind (opcionalmente --file para caminhos tocados) antes de confiar em localizadores ou selecionar/navegar. Rebind repara lineNumber a partir de lineContent ajustado e recalcula ocorrências. O array "invalid" significa que esses localizadores LINE não foram encontrados — deixe esses nós na árvore; não os delete a menos que o usuário tenha pedido para removê-los.

Para muitas chamadas de mutação, use --no-refresh em cada uma, depois um request_refresh.py no final.

Subcomando Obrigatório:

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

Parâmetros (compartilhados; todos opcionais):

• --project <caminho>: Caminho do projeto (padrão: CWD).
• --profile <nome>: Substituição do nome do perfil (padrão: <activeProfileName>).
• --dry-run: Não escrever XML ou recarregar.
• --no-refresh: Pular o sinal de recarregamento da IDE.

Parâmetros (search; todos opcionais):

• --id <uuid>: UUID do nó.
• --file <caminho>: Caminho relativo de arquivo/diretório.
• --line <n>: Número da linha (baseado em 1).
• --content <texto>: Correspondência de substring em lineContent.
• --trace-name <texto>: Correspondência de substring em traceName.
• --type <LINE|FILE|DIRECTORY>: Filtrar por tipo.

Parâmetros (add / ensure):

• Localizador (obrigatório): --file + --line + --content para LINE (substring dessa linha é OK); --file para FILE/DIRECTORY. Ou posicional ARQUIVO LINHA CONTEÚDO, ou caminho.
• --parent-id <uuid> (opcional): UUID do nó pai; repita da raiz em direção ao pai → pai imediato (preferido). Omita para raiz.
• --parent <json> (opcional): JSON do caminho do pai (não combine com --parent-id).
• --trace-name <texto> (opcional): Rótulo do ponto de rastreamento.
• --description <texto> (opcional): Descrição.
• --type <LINE|FILE|DIRECTORY> (opcional): Substituição de tipo (padrão: LINE).

Parâmetros (move):

• Localizador (obrigatório): --id, ou --file + --line + --content, ou apenas --file para FILE/DIRECTORY.
• Novo pai (obrigatório): --parent-id (repita da raiz em direção ao pai → pai imediato) ou JSON --parent. Para raiz, use --parent []. Não combine --parent-id com --parent.

Parâmetros (delete):

• Localizador (obrigatório): --id, ou --file + --line + --content, ou apenas --file para FILE/DIRECTORY.

Parâmetros (rebind; todos opcionais):

• --file <caminho>: Limitar a caminhos relativos; repetível. Padrão: todos os nós LINE no perfil.

Valor de retorno

Stdout é JSON (indent=2, UTF-8). Erros imprimem ERROR: … no stderr e saem com código diferente de zero.

objeto-nó:

{
  "id": "<uuid>",
  "parentId": "<uuid or empty>",
  "type": "LINE|FILE|DIRECTORY",
  "file": "<caminho relativo>",
  "line": "<n or empty>",
  "content": "<linha ajustada>",
  "name": "<traceName>",
  "depth": 0,
  "childCount": 0
}

search:

{
  "project_root": "<abs>",
  "storage_xml": "<abs>",
  "profile": "<nome-do-perfil>",
  "matches": [ <objeto-nó>, … ]
}

add (sempre criado; sem "skipped"

[truncado para tradução]