@lincolness/ponte

Extensão do pi: empacota o repositório num arquivo para um chat externo (Copilot, ChatGPT) e aplica a resposta de volta

Packages

Package details

extension

Install @lincolness/ponte from npm and Pi will load the resources declared by the package manifest.

$ pi install npm:@lincolness/ponte
Package
@lincolness/ponte
Version
0.3.0
Published
Nov 17, 2026
Downloads
631/mo · 631/wk
Author
lincolness
License
MIT
Types
extension
Size
157.2 KB
Dependencies
0 dependencies · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

pi-ponte

Extensão do pi que faz a ponte entre o repositório e um chat externo mais forte (Copilot, ChatGPT, Claude.ai...), sem depender do modelo local para copiar código de um lado para o outro.

  • Ida: /ponte pack gera o repositório inteiro num único .txt, com estrutura, conteúdo e instruções de como o modelo externo deve responder.
  • Volta: /ponte apply lê a resposta do chat e aplica as alterações nos arquivos. Quem aplica é a extensão, não o modelo do pi.
  • Desempacotar: /ponte unpack repo.txt recria a pasta a partir de um pacote, inclusive em outra máquina.
  • Manter atualizado: /ponte delta gera só o que mudou desde o último envio, para continuar a mesma conversa sem reenviar tudo.
  • Sessões: /ponte ver abre um visualizador das sessões do projeto, e /ponte sessao e /ponte sessoes exportam sessões em texto limpo para mandar ao chat externo. O modelo do pi ganha a ferramenta ponte_sessoes para consultar sessões anteriores sem abrir os .jsonl.

Instalação

pi install npm:@lincolness/ponte

Para testar sem instalar: pi -e npm:@lincolness/ponte.

Sem acesso ao npm, copie a pasta para ~/.pi/agent/extensions/ponte.

Não há dependências para instalar. Funciona em Windows, macOS e Linux.

Fluxo de uso

  1. No pi: /ponte pack e depois /ponte copy. O arquivo vai para a área de transferência; cole com Ctrl+V no Copilot como anexo. Outra opção é /ponte abrir e arrastar .pi/ponte/repo.txt para o chat.
  2. No Copilot: peça o que quiser ("corrija o bug X", "adicione testes para Y"). As instruções no topo do pacote já dizem como ele deve responder.
  3. Copie a resposta inteira pelo botão de copiar da mensagem.
  4. No pi, escolha uma das formas:
    • /ponte apply: lê da área de transferência. Se não achar nada, abre um editor para você colar.
    • Ou cole a resposta direto no prompt do pi. A extensão detecta os blocos e pergunta se deve aplicar. Se você responder "Não", o texto vai para o modelo como uma mensagem normal.
    • Ou salve a resposta em .pi/ponte/resposta.txt e rode /ponte apply .pi/ponte/resposta.txt. Essa pasta fica fora do pacote.
  5. Aparece um resumo (+ criar, ~ alterar, - apagar) e você confirma.
    • Se algum trecho não casar, só os arquivos sem erro são aplicados. Um relatório com o erro e o conteúdo atual do arquivo vai para a área de transferência. Cole no Copilot e ele corrige.
  6. Rode testes e ajuste com o pi normalmente. Para o Copilot ver o estado novo, rode /ponte delta e /ponte copy.

O rodapé do pi mostra ponte: N mudança(s) para enviar quando o repositório mudou desde o último envio.

Comandos

Comando O que faz
/ponte pack [filtros...] Gera .pi/ponte/repo.txt. Filtros no estilo .gitignore limitam o recorte: /ponte pack src/api "*.sql"
/ponte delta Gera .pi/ponte/delta-NNN.txt só com os arquivos novos ou alterados e a lista dos removidos
/ponte apply [arquivo] Aplica a resposta. Sem argumento, lê da área de transferência ou abre o editor para colar
/ponte undo Desfaz a última aplicação. Pode repetir para voltar mais aplicações
/ponte status Lista o que mudou desde o último envio
/ponte copy / /ponte copy texto Copia o último pacote ou delta como arquivo (para anexar) ou como texto
/ponte abrir Abre o Explorer ou o Finder com o último pacote já selecionado, para arrastar ao chat
/ponte formato Copia só as instruções de formato, útil para colar num chat já aberto
/ponte unpack [pacote] [destino] Recria a pasta a partir de um pacote. Detalhes em Desempacotar
/ponte ver Gera .pi/ponte/sessoes.html e abre no navegador: todas as sessões do projeto, com busca, níveis de detalhe e botão "Copiar para o chat" (marque várias para juntar)
/ponte sessao [nível] Exporta a sessão atual para .pi/ponte/sessoes/
/ponte sessoes [todas | 1 3 5] [nível] Exporta sessões anteriores. Sem argumentos, abre um seletor

O modelo do pi também ganha duas ferramentas: ponte_pack ("gera o pacote só da pasta src") e ponte_apply ("aplica a resposta que salvei em resposta.txt"). Assim ele chama a extensão em vez de redigitar o código.

Desempacotar

/ponte unpack faz o caminho inverso do pack: lê o pacote e recria os arquivos. Serve para levar um projeto de uma máquina para outra só com um .txt, ou para montar um projeto que o chat externo devolveu inteiro no formato do pacote.

/ponte unpack repo.txt                  # recria aqui (pasta vazia) ou numa subpasta com o nome do repositório
/ponte unpack repo.txt meu-projeto      # recria em meu-projeto/
/ponte unpack repo.parte1.txt           # pacote dividido: junta as partes irmãs sozinho
/ponte unpack delta-003.txt destino     # aplica um delta: atualiza e remove o que o delta mandar
/ponte unpack                           # lê da área de transferência ou abre o editor para colar
  • Sem destino, recria na pasta atual se ela estiver vazia ou já tiver esses arquivos (é uma atualização). Caso contrário, cria uma subpasta com o nome do repositório.
  • Na pasta do projeto atual, sobrescrever passa pelo mesmo fluxo do apply: mostra o resumo, pede confirmação e dá para voltar com /ponte undo. Em outra pasta, pede confirmação antes de sobrescrever ou remover.
  • O que não veio no pacote não volta: binários, dados, ambientes (.venv) e segredos. O aviso no fim mostra quantos itens da lista de omitidos faltam.
  • Os arquivos saem com fim de linha LF.
  • Caminhos absolutos, com .. ou dentro de .git são recusados.

Sessões

Um .jsonl de sessão do pi guarda tudo: imagens em base64, assinaturas de raciocínio, o prompt de sistema com a declaração de todas as ferramentas e cada saída de comando. Numa sessão real de 16 MB, o que você e o modelo escreveram somava 24 KB. Por isso os modelos "ignoram" as sessões anteriores: o arquivo não cabe no contexto deles.

A ponte converte a sessão em texto, sem modelo nenhum no meio. Há três níveis:

Nível O que entra Sessão de 16 MB vira
conversa o que você e o assistente escreveram, com as ações resumidas em uma linha ([ações: alterou src/a.ts; rodou 3 comandos; 1 com erro]) 27 KB, ~7k tokens
normal mais uma linha por ferramenta ($ npm test, editou src/a.ts) e a saída das que falharam 42 KB, ~10k tokens
completo mais diffs das edições, saídas (cortadas no meio quando longas) e o raciocínio 316 KB, ~80k tokens
  • Sempre ficam de fora: imagens, o prompt de sistema e as declarações de ferramentas.
  • Uma skill expandida no pedido vira uma linha ([skill x carregada]).
  • Mostra o ramo ativo da árvore da sessão; os ramos abandonados aparecem só como contagem.
  • Compactações aparecem como marcador, junto com o resumo.

A ferramenta ponte_sessoes dá ao modelo do pi três ações:

  • list lista as sessões;
  • search busca palavras em todas as sessões;
  • read lê uma sessão (ou all) no nível escolhido, em páginas.

O prompt do sistema instrui o modelo a usá-la sempre que você falar de sessões anteriores. Basta pedir "olha as sessões anteriores sobre o login".

Quando o copy não funciona

A cópia tenta mais de um caminho, porque máquinas corporativas costumam bloquear algum:

  • Texto (/ponte copy texto, /ponte formato): tenta o clip.exe, que existe em todo Windows e não depende de PowerShell. Depois tenta o PowerShell e o pwsh.
  • Arquivo (/ponte copy): tenta o Set-Clipboard -LiteralPath do Windows PowerShell 5.1. Depois tenta a API do .NET, que também funciona no pwsh 7.
  • Também funciona no WSL, usando a área de transferência do Windows.

Se tudo falhar, o Explorer abre com o pacote já selecionado, e o aviso mostra o motivo de cada tentativa. Daí é só arrastar o arquivo para o chat.

Alguns chats não aceitam arquivo colado com Ctrl+V. Se o arquivo foi copiado mas o chat não anexa, use /ponte abrir e arraste o arquivo, ou use /ponte copy texto.

Formato da resposta

Este é o formato que o pacote pede ao modelo externo:

FILE: caminho/novo.py
```python
conteúdo completo
```

EDIT: caminho/existente.ts
```
<<<<<<< SEARCH
linhas atuais, exatas
=======
linhas novas
>>>>>>> REPLACE
```

DELETE: caminho/velho.txt
MOVE: antigo.ts -> novo.ts

A aplicação aceita as variações que costumam aparecer quando se copia de um chat:

  • cabeçalho com markdown em volta (### **FILE:** \x``);
  • CRLF e espaços não separáveis;
  • SEARCH com espaços sobrando no fim da linha;
  • SEARCH com a indentação errada (o REPLACE é reindentado);
  • resposta inteira embrulhada num bloco de código.

Ela mantém o fim de linha (CRLF/LF) e o BOM de cada arquivo. Antes de gravar, simula tudo em memória, então um arquivo nunca fica com parte das alterações aplicada.

O que entra no pacote

  • Num repositório git, entra o que o git conhece (versionado ou novo, respeitando o .gitignore). Fora de git, a pasta é percorrida respeitando o .gitignore da raiz.
  • Ambientes e dependências nunca entram, mesmo sem .gitignore: .venv/, venv/, node_modules/, site-packages/, __pycache__/, caches de ferramentas, e qualquer pasta com pyvenv.cfg ou conda-meta/ dentro (um ambiente Python ou conda com qualquer nome). O pacote lista essas pastas em "Pastas ignoradas".
  • Saídas de build (dist/, build/, target/, bin/, obj/, out/, coverage/) ficam de fora quando não estão versionadas.
  • Dados ficam de fora: parquet, feather, arrow, pickle, npy, h5, sqlite, duckdb, Excel etc. nem são lidos. Viram uma linha em "Arquivos omitidos" com o tamanho. CSV, TSV, JSONL e logs acima de 32 KB também ficam de fora, mas as primeiras linhas vão como amostra, para o modelo conhecer as colunas.
  • Ficam sempre de fora: .git, .pi, lockfiles, arquivos minificados, imagens, PDFs, arquivos compactados, modelos (.pt, .onnx, .safetensors), arquivos que não estão em UTF-8 e arquivos acima de 256 KB.
  • Segredos ficam de fora: .env, .env.*, *.pem, *.key, .npmrc, secrets.* etc. O .env.example entra. Mesmo assim, confira o pacote antes de mandar para um serviço externo.
  • Com muitos arquivos omitidos, a lista vira um resumo por pasta (dados/raw/: 200 arquivo(s) (parquet 200), 1,2 GB).
  • A ordem no pacote é README e código primeiro, depois docs e configuração, e o resto no fim. Se o chat cortar um anexo longo, o que se perde é o menos útil.
  • Acima de ~150k tokens, o /ponte pack avisa quais pastas mais pesam. Recorte com /ponte pack src ou com exclude na configuração.

Configuração (opcional)

Crie o arquivo .pi/ponte.json no projeto:

{
  "exclude": ["docs/legado/", "*.csv"],
  "include": [],
  "maxFileKB": 256,
  "maxPartKB": 0,
  "outDir": ".pi/ponte",
  "ext": "txt"
}
  • maxPartKB: divide o pacote em repo.parte1.txt, repo.parte2.txt... quando o chat tem limite de tamanho por anexo. Arquivos nunca são cortados ao meio.
  • ext: use md se o chat aceitar e você preferir.

A pasta .pi/ponte/ cria o próprio .gitignore, então nada dela vai para o git.

Desenvolvimento

npm test          # node --test (Node >= 22.18, que roda TypeScript direto)
  • src/files.ts: listagem e filtros
  • src/pack.ts: pacote, delta e manifesto
  • src/parse.ts: leitura da resposta
  • src/apply.ts: plano, gravação e undo
  • src/unpack.ts: desempacotar
  • src/sessions.ts: leitura e transcrição de sessões
  • src/session-tool.ts: ferramenta ponte_sessoes
  • src/viewer.ts: visualizador HTML
  • src/clipboard.ts: área de transferência
  • src/index.ts: ligação com o pi