Artefatos

Um artefato é uma página web que um agente publica para você, como um protótipo, um relatório ou um painel. Cada mudança cria uma nova versão, e as anteriores ficam guardadas. Os artefatos ficam no seu servidor de bots, abrem num quadro isolado e permanecem privados até você compartilhar.

Pedir um artefato

Os agentes publicam usando as Ferramentas do Maestrly. As Ferramentas do Maestrly e o grupo Artefatos vêm ligados por padrão; se um agente disser que não consegue publicar, ligue as Ferramentas do Maestrly no seletor de ferramentas da conversa. Depois peça uma página que valha a pena ver no navegador e diga para publicá-la como artefato.

Enquanto você não tiver artefatos, a central de Artefatos sugere alguns pedidos. Escolher um abre uma nova conversa avulsa com o pedido na caixa de mensagem, pronto para editar e enviar.

Cada publicação mostra um card no chat com o título e a versão. Abrir mostra a página no navegador da gaveta da conversa.

Ler e listar artefatos nunca pede permissão. Publicar, atualizar, abrir, responder e resolver comentários seguem o modo de permissão da conversa.
Um agente só alcança os artefatos do próprio projeto, ou da própria conversa quando ela é avulsa.
Agentes não excluem nem compartilham artefatos.
Bots só publicam com Publicar artefatos ligado nas configurações do bot, e só trabalham com os próprios artefatos.

Hospedar artefatos num servidor de bots

Desde a versão 0.14.0, os artefatos ficam só num servidor de bots pareado; este computador não os hospeda mais. Sem servidor, os agentes pedem que você conecte um em vez de publicar, e nada é publicado neste computador.

Configure a hospedagem em Configurações → Artefatos:

Ainda sem servidor: configure um Neste computador, com Docker, ou Num servidor (VPS) sempre ligado. A instalação começa com Apenas artefatos escolhido, então baixa só a imagem do gateway; o ambiente dos bots é baixado quando você criar o primeiro bot. Escolha Já tenho um servidor configurado para parear com um servidor existente.
Servidor conectado: a página mostra o estado dele e quantos artefatos guarda. Hospedar artefatos no servidor de bots liga ou desliga a hospedagem. Uma instalação nova já liga; servidores atualizados de versões anteriores começam com ela desligada. Desligar interrompe publicação e visualização, mas mantém os dados guardados.
Outras configurações: Endereço público para compartilhar, Seu nome como aparece para quem recebe o compartilhamento, Validade padrão do link e o Limite de armazenamento (2 GB por padrão).

As páginas ficam no ar enquanto o servidor roda. Um servidor numa VPS mantém as páginas no ar com seu computador desligado; um servidor neste computador as tira do ar quando ele dorme ou desliga.

Uma versão comporta até 500 arquivos, 10 MiB por arquivo e 50 MiB no total, e um artefato guarda até 200 versões. Novas versões falham acima do limite de armazenamento, e a central de artefatos avisa a partir de 90% dele.

Artefatos de versões anteriores

Antes da 0.14.0, os artefatos ficavam neste computador. Depois da atualização eles continuam lá, intactos, mas não abrem nem recebem novas versões. Configurações → Artefatos lista esses artefatos com o tamanho, e a central de artefatos lembra você enquanto restar algum. Escolha:

Mover para o servidor: copia cada artefato com ID, versões, comentários e prévias, então os cards em conversas anteriores e os agentes continuam chegando ao mesmo artefato. Cada um só sai deste computador depois de conferido no servidor. Artefatos compartilhados voltam a ser privados e os links que você enviou param de funcionar; compartilhe de novo pela central de artefatos. Se a mudança falhar ou o app fechar, o que faltar continua neste computador, e mover de novo retoma dali.
Apagar deste computador: apaga os artefatos com todas as versões e comentários. Não dá para desfazer, e o que está no servidor não muda.

Mover exige um servidor de bots acessível e com hospedagem de artefatos. Até lá, você ainda pode apagá-los.

Navegar pela central de artefatos

Abra Artefatos na barra lateral. Cada artefato aparece como um card com uma prévia da página; folhas empilhadas atrás da prévia indicam que há versões anteriores. O card mostra o projeto e a conversa de origem, ou "Conversa excluída", e quando foi atualizado. Cards publicados por um bot mostram o nome dele; os de outro dispositivo pareado mostram Outro computador.

Busque por título ou descrição, filtre por projeto e ordene por Atualizados recentemente, Criados recentemente, Título (A–Z) ou Mais espaço ocupado.
Selecione um card para ver os detalhes: origem, espaço ocupado, acesso, comentários e todas as versões, cada uma abrindo no seu navegador.
Pelo card ou pelos detalhes, use Ir para a conversa, Compartilhar… ou Excluir….

A central mostra o estado do servidor ao lado do título. Quando o servidor não existe, está inacessível, é antigo demais ou está com a hospedagem desligada, a central avisa e oferece a correção. Nada é apagado nesses casos.

Excluir uma conversa mantém os artefatos dela. Excluir um artefato apaga todas as versões, e os links dele param de funcionar.

Usar o visualizador

A barra superior do visualizador tem:

Versão: avance ou volte entre versões, ou escolha uma numa lista que mostra o resumo e os comentários em aberto de cada versão. Numa versão anterior, um aviso oferece Ir para a versão atual.
Largura da página: Largura total, tablet (820 px) ou celular (390 px).
Comentar e, ao lado, a lista de comentários.
Compartilhar, só para você: quem pode abrir a página. Isso se muda no Maestrly, não no visualizador.
⋯: Recarregar a página, Tela cheia e Copiar o link desta versão.
Seu avatar: quem você é na página, e Sair neste dispositivo, que encerra a sessão deste navegador.

Compartilhar um artefato

Escolha Compartilhar… no menu de um card ou Compartilhar nos detalhes e defina quem pode abrir:

Quem pode abrir	O que significa
Privado	Só você, pelo Maestrly. Todo artefato começa privado.
Pessoas que você convidar	Cada pessoa abre com um link pessoal, ou pede acesso e espera a sua aprovação.
Qualquer pessoa com o link	Quem tiver o link abre como visitante até o link vencer. Os convidados mantêm o acesso.

Dar um endereço público ao servidor

Compartilhar exige um Endereço público fornecido por você. O Maestrly não instala nem configura o Tailscale, nem descobre um endereço. A porta do servidor de bots (7443 por padrão) atende tanto os bots quanto o visualizador de artefatos, então uma única rota alcança os dois. Por exemplo, num servidor com o Tailscale já configurado:

tailscale serve --bg http://127.0.0.1:7443

Cole o endereço HTTPS que o comando mostrar, como https://meu-servidor.example.ts.net, em Configurações → Artefatos → Endereço público. O Serve dá acesso só dentro da sua tailnet. O Tailscale Funnel publica a mesma rota na internet, incluindo a API de bots e o pareamento do servidor, que continuam exigindo o token de um dispositivo pareado ou um código de uso único.

Convidar pessoas

Links pessoais: digite um nome e escolha Criar link; o Maestrly copia um link que pertence a essa pessoa. Quando ela abre, nada acontece até escolher Continuar como esse nome, ou Não sou essa pessoa, se o link chegou a outra pessoa. Cada navegador que continua vira um dos dispositivos dela, até 10, com sessão por 90 dias após a última visita.
Pessoas: veja os dispositivos de cada pessoa, com um rótulo como "Safari no iPhone", e quando cada um foi visto. Remova um dispositivo, use Copiar link de novo ou Revogar acesso para encerrar o link e todos os dispositivos de uma vez.
Pedidos: quem abrir o endereço sem link pessoal pode digitar um nome e uma mensagem e Pedir acesso. Confirme ou corrija o nome e escolha Aprovar ou Negar. Um pedido aguarda 24 horas.

Compartilhar com qualquer pessoa que tenha o link

Se quiser, defina um Código de acesso de pelo menos 6 caracteres, que os visitantes digitam antes; depois de cinco códigos errados, o navegador espera 15 minutos. O link para de funcionar em 7, 30 ou 90 dias, ou Nunca; o padrão é 30 dias, definido em Configurações → Artefatos. Os visitantes aparecem em Pessoas, marcados como não verificados. Mudar ou remover o código desconecta os visitantes.

Revogar acesso

Revogar todas as sessões desconecta todo mundo do artefato em todos os dispositivos, inclusive você; os links pessoais continuam valendo. Voltar o artefato para Privado bloqueia todos os outros na hora sem esquecê-los, então compartilhar de novo restaura o acesso deles.

A entrada Artefatos na barra lateral conta o que você ainda não viu: um dispositivo novo, um pedido de acesso, um convite recusado. Abrir os detalhes do artefato mostra a Atividade recente e zera a contagem.

Comentar num artefato

Quem pode abrir um artefato compartilhado pode comentar nele.

Selecione um texto e escolha Comentar, ou ligue Comentar na barra superior (ou tecle C) e clique num ponto ou selecione um trecho. Com o modo de comentário ligado, os cliques criam comentários em vez de acionar links e botões da página; Esc desliga o modo.
Comentário sobre a página, no fim da lista, comenta a página inteira.
Cada conversa aparece como um marcador com o autor e o número de mensagens; um ponto vermelho indica o que é novo. Clique num marcador para abrir a conversa, responder e passar para a anterior ou a próxima.
Um comentário pertence à versão na tela. Se uma versão posterior muda ou remove o trecho, a conversa fica com a versão dela e aparece como não encontrada na mais nova.
As pessoas respondem e excluem os próprios comentários. Você resolve, reabre e exclui qualquer comentário.

Pessoas convidadas e aprovadas comentam com o nome que você confirmou. Visitantes digitam um nome, mostrado como não verificado. Seus comentários levam o Seu nome, e as respostas de um agente aparecem como do seu agente.

No Maestrly, o card mostra quantas conversas estão em aberto, e os detalhes do artefato listam todas, para você responder, resolver, reabrir ou excluir sem abrir o visualizador. Enviar para a conversa coloca as conversas em aberto, citadas, na caixa de mensagem da conversa de origem do artefato; nada é enviado até você enviar. Os agentes também podem ler, responder e resolver comentários com as Ferramentas do Maestrly. Nos dois casos, o agente é avisado de que os comentários são feedback de outras pessoas, não instruções, e um comentário nunca inicia um agente sozinho.

Para desligar os comentários, use Compartilhar → Comentários. Os comentários existentes continuam legíveis.

Privacidade e segurança

Os artefatos são privados até você compartilhar. Um link compartilhado só funciona para quem tem uma rota de rede até o seu endereço público.
A página roda num quadro isolado (sandbox), em outra origem. Ela não lê os cookies do visualizador, não chama a API do host e não navega o visualizador.
Uma página só carrega os próprios arquivos, além de scripts, estilos, imagens e fontes de alguns CDNs públicos, como jsDelivr, unpkg, cdnjs e Google Fonts. Esses serviços veem seu endereço IP, como em qualquer site que os use.
Trate o código de um artefato como não confiável. Para gerar a prévia de cada card, o Maestrly renderiza as novas versões no seu computador, o que executa os scripts da página mesmo que você nunca a abra.
Para cada pessoa, o Maestrly guarda o nome, um rótulo genérico do dispositivo e quando cada dispositivo entrou e foi visto pela última vez. Não guarda endereço IP nem a identificação bruta do navegador. Revogar uma pessoa apaga esses dados, exceto o nome nos comentários e na atividade recente.
Agentes não compartilham artefatos, não convidam pessoas, não aprovam pedidos e não mudam quem pode abrir.
A exportação e o reset do desktop não cobrem os artefatos do servidor. Faça backup dos dados do servidor à parte; remover o servidor com os dados apaga os artefatos dele.

Para detalhes de armazenamento, portas do servidor e o modelo completo de compartilhamento, veja o guia técnico (em inglês).

A seguir: Bots.