Enviar contexto visual a um agente

O Pinar grava Markdown simples e HTML na área de transferência. O texto inclui anotações legíveis e um bloco JSON pinar-visual-context. Cole tudo como uma unidade; o bloco estruturado é a fonte de verdade legível pela máquina.

Se o pacote listar um caminho absoluto em Screenshot, o agente local deve abrir essa imagem única; os badges numerados são sobreposições. Avisos como screenshot_missing, helper_unavailable ou viewer_unavailable descrevem uma entrega degradada, mas não invalidam comentários e contexto DOM.

A extensão do Chrome nunca digita no campo do agente. No modo Prompt, depois de Command+Enter / Alt+Enter, cole você mesmo a área de transferência no Cursor, Claude, Codex ou Grok. O texto começa dizendo que as notas dos pins podem pedir uma alteração ou uma explicação, e para tratar seletor e caminho DOM como localizadores complementares, seguidas de um bloco JSON pinar-visual-context. Se houver URL de visualizador, busque-a só quando esses detalhes não bastarem. No modo Link, o agente recebe só o link da sessão e precisa de acesso a esse .md (links do Pinar Cloud são privados e exigem API key ou MCP); Desligado apenas salva.

Trate captureId e pinId como identidade, não como rótulos a reescrever. O Visual Context grava hoje schemaVersion 1; o analisador rejeita um captureId ausente e qualquer schemaVersion que não seja 1 ou o legado 0. Siga só o que os pins descrevem. Se a pessoa não colou, peça para copiar de novo no Pinar em vez de reconstruir pins de memória.

• Cole a área de transferência inteira no agente; não redigite comentários nem invente um captureId novo.
• Confirme que o texto colado ainda contém a cerca fechada pinar-visual-context antes de editar código.
• Se nada foi colado, peça Command+Enter / Alt+Enter no Pinar e siga somente as notas dos pins.

O Pinar também expõe as sessões armazenadas pelo Model Context Protocol. Um cliente MCP pode listar projetos, coleções, lotes, sessões, pins e comentários de pins, e pode criá-los, comentá-los, renomeá-los, movê-los, reordená-los e excluí-los.

O serviço Pinar local expõe MCP na sua própria máquina, sem conta, login ou chave de API. O Pinar Cloud exige uma chave de API com a permissão necessária, e o escopo de recurso da chave limita o que o agente pode ler, comentar ou modificar.

Para a configuração do cliente, incluindo o endpoint, o cabeçalho de autenticação e os detalhes do protocolo, consulte o guia de acesso de agentes no repositório do Pinar.

• Uma sessão criada por agente armazena os metadados da página sem screenshot, e um pin de agente armazena o comentário com um localizador opcional, sem geometria medida.
• O MCP não reidrata nem sincroniza o rascunho no navegador; a extensão continua sendo a escritora do rascunho ativo, e um salvamento explícito posterior substitui a sessão armazenada com o mesmo id.
• O compartilhamento continua explícito: publique um share a partir do workspace, ou deixe um agente com a permissão de compartilhar publicar ou revogar.

O aplicativo local do Pinar oferece a mesma superfície Model Context Protocol a agentes que rodam no mesmo computador, e é aberto por design: nenhuma conta, login ou chave de API está envolvida. Aponte o cliente MCP do seu agente para o endpoint descrito na seção de acesso de agentes a sessões do README do Pinar.

A seção de ferramentas MCP locais do README lista cada ferramenta com os seus argumentos e valor de retorno. As ferramentas de listagem paginam os resultados, até 50 itens por página, para que um agente percorra um workspace grande uma página de cada vez. As ferramentas de reordenação esperam a lista completa de itens e rejeitam uma parcial antes de qualquer coisa se mover.

• Como a conexão é local, o agente trabalha apenas com as capturas armazenadas neste computador e nunca precisa do Pinar Cloud.
• A maior parte da superfície de ferramentas da nuvem está disponível localmente; os extras exclusivos da nuvem dizem respeito a chaves de agente e à publicação de shares.

O Pinar Cloud permite que contas Pro emitam chaves dedicadas de agente. Abra Configurações → “Acesso de agentes” no workspace para criar uma: dê um nome à chave, escolha uma permissão — “Leitura”, “Gerenciar”, “Compartilhar” ou “Completa” — e um vencimento de 7, 30 ou 90 dias. Uma chave de “Leitura” pode ter escopo da conta inteira ou de um projeto, coleção, sessão ou lote. As outras permissões atuam sobre a conta inteira.

A chave é mostrada apenas uma vez, logo depois que você a cria, então copie-a antes que o diálogo feche — o Pinar guarda apenas um prefixo curto e não pode mostrar a chave de novo. Até 20 chaves ativas podem existir ao mesmo tempo. Cada chave listada mostra o seu escopo, permissão, vencimento e último uso, e “Revogar” a encerra imediatamente. Uma solicitação de um recurso fora do escopo da chave é respondida como se o recurso não existisse, para que uma chave nunca revele o que há além do seu escopo. O guia de acesso de agentes na nuvem documenta a matriz de permissões e a superfície completa de ferramentas por trás de cada chave.

• Dê a cada agente ou automação a sua própria chave, para que revogar uma não perturbe as outras.
• As chaves funcionam com clientes MCP que suportam cabeçalhos personalizados e com os links privados de Markdown; o painel “Acesso de agentes” explica como a chave é usada.