@lincolness/ponte
Extensão do pi: empacota o repositório num arquivo para um chat externo (Copilot, ChatGPT) e aplica a resposta de volta
Package details
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 packgera o repositório inteiro num único.txt, com estrutura, conteúdo e instruções de como o modelo externo deve responder. - Volta:
/ponte applylê 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.txtrecria a pasta a partir de um pacote, inclusive em outra máquina. - Manter atualizado:
/ponte deltagera só o que mudou desde o último envio, para continuar a mesma conversa sem reenviar tudo. - Sessões:
/ponte verabre um visualizador das sessões do projeto, e/ponte sessaoe/ponte sessoesexportam sessões em texto limpo para mandar ao chat externo. O modelo do pi ganha a ferramentaponte_sessoespara 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
- No pi:
/ponte packe depois/ponte copy. O arquivo vai para a área de transferência; cole com Ctrl+V no Copilot como anexo. Outra opção é/ponte abrire arrastar.pi/ponte/repo.txtpara o chat. - 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.
- Copie a resposta inteira pelo botão de copiar da mensagem.
- 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.txte rode/ponte apply .pi/ponte/resposta.txt. Essa pasta fica fora do pacote.
- 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.
- Rode testes e ajuste com o pi normalmente. Para o Copilot ver o estado novo, rode
/ponte deltae/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.gitsã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:
listlista as sessões;searchbusca palavras em todas as sessões;readlê uma sessão (ouall) 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 oclip.exe, que existe em todo Windows e não depende de PowerShell. Depois tenta o PowerShell e opwsh. - Arquivo (
/ponte copy): tenta oSet-Clipboard -LiteralPathdo Windows PowerShell 5.1. Depois tenta a API do .NET, que também funciona nopwsh7. - 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 compyvenv.cfgouconda-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.exampleentra. 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 packavisa quais pastas mais pesam. Recorte com/ponte pack srcou comexcludena 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 emrepo.parte1.txt,repo.parte2.txt... quando o chat tem limite de tamanho por anexo. Arquivos nunca são cortados ao meio.ext: usemdse 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 filtrossrc/pack.ts: pacote, delta e manifestosrc/parse.ts: leitura da respostasrc/apply.ts: plano, gravação e undosrc/unpack.ts: desempacotarsrc/sessions.ts: leitura e transcrição de sessõessrc/session-tool.ts: ferramentaponte_sessoessrc/viewer.ts: visualizador HTMLsrc/clipboard.ts: área de transferênciasrc/index.ts: ligação com o pi