Code Trace Tree

O que Code Trace Tree faz?

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

Edite ou sincronize rastros apenas quando o usuário solicitar 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 rebind relata 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 nem explore as pastas scripts/ ou references/ desta skill, e não abra o código-fonte dos scripts para aprender a API. Execute os comandos Python documentados usando caminhos absolutos.

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

Localização dos scripts da skill

Os scripts auxiliares ficam 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 da Skill do Agente (local ao projeto)
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

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

Operações da Árvore de Rastreamento

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 do 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

Resolve o ID do projeto e o XML global vinculado. Se o armazenamento estiver ausente, cria-o (Caso C). Se .idea/code-trace-tree.project.id existir, mas o XML tiver sumido, recria o XML com o mesmo projectId. Não cria/sobrescreve o arquivo .idea id. Chamadas mutantes de 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 do 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 ou 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

Cria uma árvore aninhada de pontos de rastreamento em uma única chamada. Garante apenas as raízes da carga (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 faça search se não for necessário — este script já garante a existência dos nós. Use search quando precisar de IDs (para selecionar/mover/excluir) ou para inspecionar. Os localizadores LINE são os mesmos de trace_tree.py (file + line + content). Ignore a ocorrência de conteúdo de linha (occurrenceIndex / totalOccurrences) — o script a calcula. Prefira --tree-file no PowerShell.

Opcional --parent-id anexa a carga 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 escreve XML nem atualiza.
• --no-refresh: Pula o sinal de atualização do IDE.
• --parent-id <uuid>: Pai existente; repita da raiz em direção ao pai imediato. Omita para raiz do perfil.
• --parent <json>: Caminho do pai existente em JSON (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 adição; descendentes desse nó foram adicionados sem garantia.

{
  "action": "create_tree",
  "profile": "<nome-do-perfil>",
  "storage_xml": "<abs>",
  "parentId": "<uuid ou vazio>",
  "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

Pesquisa, adiciona, garante, move, exclui e religa 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 do IDE (os scripts caminham para cima para encontrar .vscode / .idea / .git ou outros marcadores comuns de projeto). Perfil padrão: <activeProfileName>.

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

Dica	Resultado
Linha exata + texto aparado completo	Usado como está
Substring distintiva daquela linha (ex.: .handleEmailTriggerRequest()	--line obrigatório; armazena a linha total aparada
Mesmo texto aparado em 2+ linhas	Passe --line para a cópia desejada; script define ocorrência
Chamada multi-linha	Prefira a linha física mais distintiva (geralmente a continuação .methodName()

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

Gerando uma árvore: prefira create_tree.py. Não faça 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/excluir ou para inspecionar. Para um único nó, use ensure (get-or-create; nenhuma pesquisa necessária) ou add (sempre um novo UUID).

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

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

def method A
  chamada method B
    chamada method C   ← add (ou ensure se B já existia) com --parent-id idA --parent-id idB

Rebind após edições no disco: Agentes não editam através do editor IDE, então o deslocamento de linha ao vivo não se aplica. Após qualquer turno que tenha modificado o código-fonte do projeto, execute rebind (opcionalmente --file para caminhos tocados) antes de confiar nos localizadores ou em selecionar/navegar. Rebind repara lineNumber a partir de lineContent aparado e recalcula ocorrências. O array "invalid" significa que aqueles 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 mutantes, use --no-refresh em cada uma e então 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 escreve XML nem atualiza.
• --no-refresh: Pula o sinal de atualização do IDE.

Parâmetros (search; todos opcionais):

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

Parâmetros (add / ensure):

• Localizador (obrigatório): --file + --line + --content para LINE (substring da 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 → pai imediato (preferido). Omita para raiz.
• --parent <json> (opcional): Caminho do pai em JSON (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 do 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 → pai imediato) ou --parent JSON. 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 caminho(s) relativo(s); 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.

node-object:

{
  "id": "<uuid>",
  "parentId": "<uuid ou vazio>",
  "type": "LINE|FILE|DIRECTORY",
  "file": "<caminho relativo>",
  "line": "<n ou vazio>",
  "content": "<lineContent aparado>",
  "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"):

{
  "action": "add",
  "profile": "<nome-do-perfil>",
  "node": <objeto-nó>,
  "refreshed": true|false
}

ensure ("skipped": true se existir, senão "created": true):

{
  "action": "ensure",
  "skipped": true|false,
  "created": true|false,
  "profile": "<nome-do-perfil>",
  "node": <objeto-nó>,
  "refreshed": true|false
}

move (o nó movido; "parentId" no objeto muda):

{
  "action": "move",
  "profile": "<nome-do-perfil>",
  "node": <objeto-nó>,
  "refreshed": true|false
}

delete (nó excluído):

{
  "action": "delete",
  "profile": "<nome-do-perfil>",
  "node": <objeto-nó>,
  "refreshed": true|false
}

rebind:

{
  "action": "rebind",
  "profile": "<nome-do-perfil>",
  "rebound": <n>,
  "invalid": [ <objeto-nó>, … ],
  "refreshed": true|false
}

Saída 0 em caso de sucesso.

Exemplos:

python "<Caminho da Skill do Agente>/code-trace-tree/scripts/trace_tree.py" search --file src/A.java
python "<Caminho da Skill do Agente>/code-trace-tree/scripts/trace_tree.py" ensure src/A.java 10 "void methodA() {"
python "<Caminho da Skill do Agente>/code-trace-tree/scripts/trace_tree.py" add --file src/B.java --line 40 --content "void methodB() {" --parent-id "$PARENT_ID"
python "<Caminho da Skill do Agente>/code-trace-tree/scripts/trace_tree.py" delete --id "$NODE_ID"
python "<Caminho da Skill do Agente>/code-trace-tree/scripts/trace_tree.py" rebind --file src/A.java --file src/B.java

request_refresh.py

Dispara uma atualização no IDE para um perfil específico. O script não interage diretamente com o plugin IDE; em vez disso, ele toca em um caminho de arquivo de sentinela específico da plataforma (por exemplo, um arquivo markdown gerado ou um caminho de soquete) que o plugin observa para disparar uma recarga da árvore. É útil para forçar o IDE a refletir alterações feitas por outros scripts nesta skill sem exigir que o usuário recarregue manualmente a janela. Deve ser chamado após uma sequência de operações com --no-refresh para evitar sinais individuais.

Uso

python "<Caminho da Skill do Agente>/code-trace-tree/scripts/request_refresh.py" [--profile <nome>] [--project <caminho>]

Parâmetros Opcionais:

• --profile <nome>: Nome do perfil (padrão: <activeProfileName>).
• --project <caminho>: Caminho do projeto (padrão: CWD).

Valor de retorno

Stdout é JSON (indent=2, UTF-8).

{
  "action": "refresh",
  "profile": "<nome-do-perfil>",
  "sent": true
}

Saída 0 em caso de sucesso.

request_refresh_profile.py

Adiciona, remove ou lista perfis. Um perfil é uma visão nomeada da árvore de rastreamento (conjunto independente de pontos de rastreamento). Operações create_tree e trace_tree padrão para <activeProfileName> a menos que --profile seja passado. Perfis são armazenados no diretório global de configuração do SO (por exemplo, ~/.config/code-trace-tree/profile no Linux).

Uso

python "<Caminho da Skill do Agente>/code-trace-tree/scripts/request_refresh_profile.py" [--add <nome> | --remove <nome> | --list]

Parâmetros (exatamente uma ação):

• --add <nome>: Cria um novo perfil.
• --remove <nome>: Remove um perfil existente.
• --list: Lista todos os perfis.

Valor de retorno

--list stdout é JSON (indent=2, UTF-8):

{
  "profiles": ["<nome>", …],
  "active": "<activeProfileName>"
}

--add / --remove stdout é JSON:

{
  "action": "profile",
  "name": "<nome>",
  "created": true|false,
  "removed": true|false,
  "active": "<activeProfileName>"
}

Saída 0 em caso de sucesso.

request_refresh_settings.py

Obtém ou define configurações por perfil. As configurações controlam a renderização da árvore, a largura da coluna de conteúdo, a ordenação de nós e se as linhas de conteúdo são aparadas. Atualmente, as opções com suporte são lineContentMaxLength (número) e sortBy ("file" | "line" | "name" | "type").

Uso

python "<Caminho da Skill do Agente>/code-trace-tree/scripts/request_refresh_settings.py" [--get | --set <chave>=<valor>] [--profile <nome>]

Parâmetros:

• --get: Recupera as configurações atuais para o perfil.
• --set <chave>=<valor>: Define uma configuração. Especial: --set sortBy=default para redefinir para a ordenação padrão.
• --profile <nome>: Perfil (padrão: <activeProfileName>).

Valor de retorno

--get stdout é JSON:

{
  "action": "settings",
  "profile": "<nome>",
  "settings": {
    "lineContentMaxLength": 120,
    "sortBy": "file"
  }
}

--set stdout é JSON:

{
  "action": "settings",
  "profile": "<nome>",
  "key": "<chave>",
  "value": "<valor>",
  "set": true
}

Saída 0 em caso de sucesso.

select_trace_points.py

Abre o arquivo de origem no IDE e seleciona linhas específicas com base nos pontos de rastreamento fornecidos. Isso permite que um agente "mostre" ao usuário onde os pontos de rastreamento estão sem exigir que ele expanda manualmente a árvore. Se nenhum ponto de rastreamento for fornecido, seleciona todos os nós válidos no perfil atual. Útil para depuração ou para destacar rapidamente locais de código que correspondem a pontos de rastreamento.

Uso

python "<Caminho da Skill do Agente>/code-trace-tree/scripts/select_trace_points.py" [--id <uuid> ...] [--profile <nome>] [--project <caminho>]

Parâmetros Opcionais:

• --id <uuid>: UUID(s) do(s) nó(s) a selecionar; repetível. Se omitido, seleciona todos os nós no perfil.
• --profile <nome>: Perfil (padrão: <activeProfileName>).
• --project <caminho>: Caminho do projeto (padrão: CWD).

Valor de retorno

Stdout é JSON:

{
  "action": "select",
  "profile": "<nome>",
  "selected": <n>,
  "files": {
    "src/A.java": [10, 40],
    "src/B.java": [20]
  }
}

Saída 0 em caso de sucesso.

Instalação e compatibilidade do Windows PowerShell

No Windows PowerShell, os argumentos de linha de comando podem exigir escapes especiais. Use --% (o símbolo de parada de análise) antes de strings que contenham espaços ou caracteres especiais, ou use aspas com cuidado. Para scripts como request_refresh_settings.py, certifique-se de que as aspas estejam balanceadas e que os caracteres % sejam escapados se necessário. Exemplo:

python "<Caminho da Skill do Agente>/code-trace-tree/scripts/trace_tree.py" --% search --file "src/A.java"

Se você encontrar um erro "The system cannot find the path specified", verifique se o Caminho da Skill do Agente está resolvido corretamente e se o caminho não contém caracteres de espaço sem escape. Use o operador & do PowerShell ou chame python diretamente com um caminho absoluto. Prefira --tree-file em vez de --tree inline no PowerShell.

Dicas e Melhores Práticas

• Sempre resolva o Caminho da Skill do Agente uma vez por sessão e o reutilize.
• Use --no-refresh em chamadas individuais trace_tree ou create_tree, depois chame request_refresh.py uma vez.
• Prefira create_tree.py para construir árvores com vários nós; é mais rápido e mais limpo.
• Após modificar o código-fonte, execute trace_tree.py rebind antes de pesquisar ou navegar.
• Nunca exclua nós "invalid" de rebind a menos que o usuário os remova.
• Mantenha o CWD do processo no diretório raiz do projeto IDE; não use cd para a pasta da skill.
• Em sistemas Windows, lembre-se de que a variável de ambiente %USERPROFILE% é o equivalente ao ~ do Unix.

Essa estrutura garante que os agentes de IA possam gerenciar árvores de rastreamento complexas sem modificar o armazenamento XML diretamente, seguindo as intenções do usuário e fornecendo feedback visual através do plugin IDE.