Commands

Um Command é um procedimento que ensinas ao Ploy: o objetivo, as informações que mudam de vez para vez, os passos, as regras que não mudam e as condições que provam que o trabalho ficou feito. Não é um pedido guardado. O Ploy segue o procedimento, verifica essas condições no fim e regista cada execução, com o que ela provou.

Um Command corre com o mesmo agente, as mesmas ferramentas, as mesmas autorizações e os mesmos modelos de qualquer tarefa. Não é um segundo motor de automação.

Onde estão#

«Commands», na barra lateral, ou ⇧⌘K. À esquerda fica a lista, cada Command com o nome, o atalho (por exemplo /preparar-orcamento-de-pintura), o estado e, se veio de uma equipa, «Equipa». Os estados são:

O botão «+» no topo da lista tem «Descrever um Command…», «Mostrar ao Ploy como se faz…», «Biblioteca de equipa…» e «Segurança…». A biblioteca de equipa está em Equipas e a segurança em Segurança dos Commands.

Três maneiras de criar um#

Descrever#

«Descrever um Command…» abre «Novo Command». Explicas o trabalho como a um colega: o que queres alcançar, que informações mudam de vez para vez, as regras que se aplicam e como sabes que ficou bem feito. «Escrever o rascunho» (com pelo menos 20 caracteres) pede ao modelo uma definição, que abre no editor, em «Rever o rascunho». O código do Ploy corrige antes os deslizes conhecidos dos modelos pequenos, como um identificador no lugar do nome. O que o modelo não conseguiu saber aparece em «O Ploy precisa de saber», para responderes nos campos. Nada fica guardado até carregares em «Guardar como rascunho».

A partir de uma tarefa feita#

Por baixo de uma resposta a uma tarefa que usou ferramentas aparece «Transformar num Command». O Ploy parte do pedido, das ações, dos ficheiros e do resultado dessa tarefa. O que era só daquele caso (nomes, datas, valores) passa a informação a pedir em cada execução. O rascunho abre no editor, como acima, e nada da conversa fica guardado sem tu veres.

Mostrar ao Ploy#

«Mostrar ao Ploy como se faz…» deixa-te fazer o trabalho uma vez, como de costume, e o Ploy escreve os passos.

1. Abres primeiro as aplicações que vais usar. A folha lista as aplicações abertas, e marcas as que o Ploy deve observar. Só essas: uma aplicação que abras a meio e não esteja marcada fica de fora. É precisa a permissão Acessibilidade.
2. «Começar a mostrar». No fundo do ecrã aparece um painel, «O Ploy está a observar», com o número de passos e o botão «Terminar». Esc duas vezes também acaba. A demonstração acaba sozinha aos 200 passos ou aos 30 minutos.
3. Fazes o trabalho. O Ploy escreve: a aplicação da frente, o controlo em que carregaste, o caminho de um menu, os atalhos com ⌘ ou ⌃, Enter, Tab e Esc, o texto que um campo tem quando sais dele, e a janela da frente.
4. No fim, «O que mostraste ao Ploy» mostra os passos. Tiras o que não faz parte do trabalho e o Ploy escreve o rascunho a partir do que ficar. O texto que escreveste passa a informação a pedir; um valor que ficou como texto fixo é perguntado.

O que a demonstração não faz:

• não regista as teclas uma a uma;
• não lê campos de palavra-passe: o passo diz só que foi escrita uma;
• não tira imagens do ecrã;
• ignora as janelas do próprio Ploy;
• não guarda nada em disco: os passos ficam só em memória até guardares o rascunho ou o descartares («Os passos não ficaram guardados em lado nenhum: descartados, não voltam.»).

Enquanto a demonstração corre, nenhuma tarefa nem trabalho do modelo começa.

As partes de um Command#

A página de cada Command mostra, por esta ordem, o que o editor permite mudar:

Os critérios#

Só esta execução prova esta execução. Um ficheiro só conta se foi esta execução a escrevê-lo, e nunca através de uma ligação para fora da pasta. Uma resposta que acaba numa pergunta não prova nada. E os critérios que se cumprem não escondem outra falha: um ficheiro que não abre, um teste ou uma compilação que falha, uma página partida ou um original reescrito deixam a execução por verificar. Um critério que nada conseguiu julgar fica «por confirmar», nunca dado como cumprido. Um Command sem critérios nunca fica verificado, e não pode ser aprovado.

As ferramentas#

Um Command só usa as ferramentas do seu tipo de trabalho, ou só as que escolheres entre elas. Um Command sem a ferramenta de escrever ficheiros não escreve nenhum, nem a partir de um bloco de código na resposta.

Corre sempre com as tuas permissões, como qualquer tarefa (Segurança). Com «Pedir autorização antes de cada ação», cada ação além de ler pede a tua autorização, uma a uma, seja qual for o modo de execução: nenhuma permissão permanente, nem «Nesta tarefa», nem «Execução autónoma» responde por ti. Com ou sem esta opção, enviar, pagar, publicar, instalar e apagar de vez pedem sempre autorização.

Testar e aprovar#

Um Command ganha a aprovação versão a versão.

• Testes. Em «Editar…», «Testes» guarda casos com valores de exemplo para cada informação obrigatória. «Testar» corre os testes da versão atual, um de cada vez. Num Command de código, cada teste corre numa pasta à parte, em ~/Projetos Ploy/Testes de Commands/. Nos outros tipos de trabalho, os testes agem a sério, por isso cada ação pede a tua autorização. Cada teste abre uma conversa; quando um falha, abre a conversa dele em «Execuções» para ver porquê.
• Aprovar. «Aprovar» só fica disponível quando a definição é válida, tem critérios e testes, e todos os testes passaram com esta versão exata. Por baixo, «Para aprovar a versão N» diz o que falta. Depois de aprovar, essa versão passa a ser a que corre nas conversas.
• Mudar um Command aprovado. Guardar uma alteração cria uma versão nova, «Em teste». As conversas continuam a correr a versão aprovada até a nova passar nos testes e ser aprovada, e o cabeçalho diz «nas conversas corre a versão aprovada N».
• Antes da primeira aprovação. Um Command pessoal de sensibilidade normal pode correr a versão mais recente, e a folha de execução diz «ainda não aprovada». Um Command de equipa, ou de sensibilidade acima de normal, só corre a partir de uma versão aprovada; até lá, só os testes correm.

Correr um Command#

Na conversa#

• O atalho. Escreves / seguido do atalho do Command, por exemplo /preparar-orcamento-de-pintura, com ou sem mais texto.
• A sugestão. Quando o pedido que escreves se parece claramente com um Command, o Ploy diz «Isto parece o Command «…».» por cima do campo, com «Usar». O reconhecimento é feito pelo código, sem modelo, e só oferece: nada corre sem abrires a folha e carregares em «Executar».

As informações vêm das tuas palavras. Linhas como cliente: Rui Matos são lidas sem modelo; o resto é lido pelo modelo e só fica um valor que esteja escrito no teu pedido. Antes de correr, a folha mostra sempre os valores, para confirmares ou corrigires, e a execução não começa enquanto faltar uma informação obrigatória.

Se o Command te fizer uma pergunta a meio, a tua resposta continua o mesmo Command, com as suas regras, ferramentas e critérios, e o campo diz «A tua resposta continua o Command «…», com as suas regras.». O botão de fechar ao lado, «Responder fora do Command», tira a resposta seguinte do Command.

No Studio#

«Executar…» abre a mesma folha: os valores, «Nota para esta execução (opcional)» e «O que esta execução pode fazer», com os limites da versão que vai correr (o que consulta, o que pode escrever ou apagar, se usa a Internet ou outras aplicações, a sensibilidade). «O modelo escolhe as ações dentro destes limites; o recibo da execução diz quais tomou.»

Quando acaba#

No fim, o Ploy verifica cada critério. Os que não se cumprem voltam ao modelo para corrigir, em rondas; um critério que nada pôde julgar nunca volta como trabalho a refazer. O resultado de cada execução é um destes:

Em qualquer tarefa, Command ou não, três recusas seguidas terminam a tarefa, e o mesmo acontece com dez ações falhadas seguidas.

Execuções, métricas e versões#

• Execuções. Cada execução fica registada com a versão, se foi um teste, o estado, os critérios (com o nome das informações no lugar dos valores, por exemplo «proposta-‹Cliente›.txt»), um motivo curto, quantas vezes te foi pedida uma resposta, o número de ações e a duração. Não fica nada do que o modelo leu. Ficam as 2000 execuções reais mais recentes e, à parte, os 200 testes mais recentes de cada Command. Cada linha tem «Recibo», «Comparar» e, se a conversa ainda existir, «Abrir».
• Métricas. «Contadas nas execuções reais; os testes ficam de fora. São medições, não estimativas.» Execuções, concluídas, quantas precisaram de ti, quantas falharam, quantas pediram autorização ou uma informação, e a duração média. Se uma versão concluiu menos vezes do que a anterior, a página diz qual. O Ploy não mostra tempo poupado: ainda não há um método para o calcular.
• Versões. «Cada alteração fica guardada.» Abrir uma versão mostra o que mudou em relação à anterior. «Repor…» guarda uma versão antiga como versão nova, sem apagar nenhuma.

Os recibos, a comparação de execuções e a retirada de uma versão estão em Segurança dos Commands.

Melhorar a partir de uma correção#

Quando uma execução não fez o que querias, podes corrigir o procedimento, para a próxima vez:

• por baixo da resposta de um Command, «Melhorar o Command»; se um critério não se cumpriu ou marcaste a resposta como errada, aparece também uma linha a oferecê-lo;
• no Studio, «Propor melhoria…» numa execução que falhou ou precisou de ti.

A folha «Melhorar «…»» mostra o que a verificação encontrou nessa execução e pede «A tua correção», por exemplo «faltou o IVA de 23%». «Propor alterações» pede ao modelo, no máximo, seis alterações numeradas ao procedimento (acrescentar, trocar ou tirar um passo, uma regra, um critério, uma informação, uma fonte, uma condição, uma linha de recuperação, um resultado, ou o objetivo). O código do Ploy aplica-as uma a uma e só fica com as que deixam o Command tão válido como antes.

• O modelo não pode mudar o tipo de trabalho, as ferramentas, «Pedir autorização antes de cada ação», o nome, o atalho nem os testes.
• Os valores daquela execução que aparecem numa alteração passam à informação a que pertencem (Rui Matos passa a {cliente}), e um valor sem informação passa a uma informação nova.
• A folha mostra as alterações parte a parte, e em «O que o Ploy ajustou ou deixou de fora» o que não entrou e porquê.
• «Juntar este caso aos testes» acrescenta o caso da execução aos testes.
• Nada fica guardado até carregares em «Guardar a versão N». A versão guardada fica em teste, e a aprovada continua a correr nas conversas até a nova passar nos testes e ser aprovada.

O modelo não é treinado de novo: muda só o Command, e a folha diz isso.

Arquivar e apagar#

No menu de três pontos de cada Command: «Arquivar» (ou «Tirar dos arquivados») e «Apagar…». Apagar pede confirmação e apaga o Command, as versões e o registo das execuções; as conversas onde correu ficam, e os recibos também (ver Segurança dos Commands).

Na linha de comandos#

ploy commands escreve, corre, verifica e melhora definições de Commands em ficheiros JSON, com os mesmos modelos e as mesmas verificações da app: draft, run, check, improve e demo. Ver Linha de comandos.

O que foi provado#

Com o Saturn, no Mac de referência, a 27 de outubro de 2026:

• a descrição do orçamento de pintura deu uma definição válida, e a execução para Rui Matos, 40 m², escreveu o ficheiro com 480 euros e cumpriu os quatro critérios (três verificados pelo código, um lido pelo modelo);
• a correção «Faltou o IVA…» deu, em três de quatro tentativas, uma versão válida com o total com IVA, e a versão proposta, corrida para o mesmo caso, escreveu «Total com IVA: 590,40 euros» e cumpriu os quatro critérios;
• uma demonstração gravada no Editor de Texto (um documento novo, o texto do orçamento, ⌘S, o nome do ficheiro, Guardar) deu um Command válido, com o cliente, a área e o preço por m² como informações.

Limites#

• Os critérios «lidos por um modelo» são a leitura de um modelo, e o Ploy di-lo em cada lugar onde aparecem.
• Um modelo pequeno tende a escrever a data de hoje como uma informação a pedir, por isso cada execução pede a data. A proposta mostra-o e podes reescrever o passo antes de guardar.
• Testar um Command abre uma conversa por teste.
• O tempo poupado em relação a fazer o trabalho à mão não é medido.
• Não há administração central de Commands numa organização: isso precisaria de contas e de um servidor, que o Ploy não tem. A partilha entre pessoas faz-se por uma pasta partilhada (Equipas).
• O Command Studio é só para macOS.