Planos agendados

Um plano (também chamado de plano agendado ou tarefa agendada) faz o HagiCode iniciar uma sessão automaticamente em um horário que você define, sem que você precise estar presente para clicar em Submit. Usos típicos: executar uma revisão de código às 2h de todos os dias úteis, verificar atualizações de dependências toda manhã ou redigir as notas de versão amanhã às 10h.

Um plano guarda duas coisas: tudo o que é necessário para criar a sessão (exatamente o que você preencheria normalmente em uma caixa de diálogo de criação) e um agendamento. Quando chega a hora, o HagiCode cria a sessão pelo mesmo fluxo de um envio manual, então uma sessão iniciada por um plano não é diferente de uma que você criou por conta própria.

Conceitos

Conceito	Significado
Type (Tipo)	Há dois tipos de plano: Proposal (Proposta; cria uma sessão de proposta quando é executado) e HagiTask (cria uma sessão a partir de uma HagiTask quando é executado). O tipo é definido pela caixa de diálogo de criação em que você salva o plano.
Run once / Recurring (Executar uma vez / Recorrente)	Um plano único é executado em um único momento. Um plano recorrente se repete diariamente ou semanalmente entre uma data de início e uma data de término.
Occurrence (Ocorrência)	Um horário específico de um plano no calendário. Um plano único tem uma; um plano recorrente tem uma para cada vez que vence, e cada uma pode ser alterada ou excluída por conta própria, sem afetar as outras.
Next run (Próxima execução)	A próxima vez em que o plano será iniciado por conta própria, exibida no fuso horário do próprio plano.
Scheduled / Completed (Agendado / Concluído)	O estado do plano. Um plano único passa a Completed depois de ser executado; um plano recorrente passa a Completed quando sua data de término já passou.
Enabled / Disabled (Ativado / Desativado)	Todo plano tem um interruptor de ativação. Um plano desativado continua na lista e no calendário, mas nunca é executado automaticamente.

Abrir o gerenciador de planos

O botão Plans (Planos) na barra superior abre o gerenciador de planos. Em uma janela estreita, o botão mostra apenas o ícone de calendário; passe o mouse sobre ele para ver a dica Scheduled plans (Planos agendados).

O gerenciador é uma gaveta que desliza da direita, com duas visualizações no topo:

• Calendar (Calendário): mostra por mês, semana ou agenda quando os planos serão executados. Toda vez que você o abre, ele começa em hoje.
• All plans (Todos os planos): lista todos os planos, e aqui você pode ativar, desativar, executar agora, editar e excluir cada um.

O gerenciador serve apenas para ver e gerenciar planos existentes; você não pode criar um aqui. Os planos são sempre salvos a partir da caixa de diálogo que cria uma proposta ou uma HagiTask. Sem nenhum plano ainda, All plans mostra No scheduled plans yet e uma dica de como criar um.

Ver seus planos no calendário

Calendar abre no mês atual. Cada horário em que um plano será executado é uma entrada no calendário.

Os controles no topo:

Controle	O que faz
Today (Hoje)	Volta ao mês, à semana ou à agenda que contém hoje.
‹ / ›	Passa para o período anterior ou seguinte: por mês na visualização Month, por semana nas visualizações Week e Agenda.
Month / Week / Agenda	Alterna a visualização. Em uma janela com menos de 768 pixels de largura, o gerenciador abre em Agenda todas as vezes, porque uma única coluna é mais fácil de ler.
Display time zone (Fuso horário de exibição)	O fuso horário que o calendário usa para organizar e mostrar os horários. O padrão é o fuso horário atual do navegador. Ele altera apenas como os horários são exibidos, nunca o fuso horário do próprio plano nem o momento em que ele realmente é executado.

As três visualizações mostram os mesmos dados:

• Month: cada célula de dia mostra até 3 entradas; além disso aparece +N more, e clicar nele abre uma caixa de diálogo com todos os horários de execução daquele dia.
• Week: sete colunas lado a lado, com espaço para o nome completo do plano em cada entrada.
• Agenda: uma lista agrupada por data, que exibe apenas os dias com horários de execução, com o estado escrito por extenso à direita de cada entrada.

Cada entrada mostra o horário e o nome do plano. As visualizações Month e Week marcam o estado com ícones (passe o mouse para ver o texto); Agenda o escreve por extenso:

Marcador	Significado
Ícone de repetição / Repeats	Este é um horário de um plano recorrente.
Ícone de visto / Completed	O plano está concluído (por exemplo, um plano único que já foi executado).
Ícone de pausa / Disabled	O plano está desativado, então este horário não será executado automaticamente.
Ícone de lápis / Changed	Este horário foi alterado individualmente e difere do plano recorrente no horário ou no conteúdo.

O calendário mostra horários calculados a partir das configurações atuais do plano, não um histórico de execuções. É isso que Scheduled times from current plan settings. They are not run history. significa na página: depois que um plano é editado, desativado ou concluído, o calendário continua organizando-o a partir das configurações atuais e não registra o que foi executado antes. Para ver as sessões que já foram iniciadas, use o quadro de sessões.

Ver os detalhes de um horário

Clique em qualquer entrada para abrir uma gaveta de detalhes daquele horário. Você não precisa abrir o editor para olhar.

Campo	Descrição
Título e selos	O nome do plano, seu tipo (Proposal ou HagiTask), seu estado (Scheduled ou Completed) e Enabled ou Disabled.
This time (Este horário)	O horário de execução desta entrada, organizado no fuso horário de exibição.
Original time (Horário original)	Aparece apenas quando este horário foi movido, e mostra o horário que o plano recorrente havia agendado originalmente.
Schedule (Agendamento)	O agendamento completo do plano.
Schedule time zone (Fuso horário do agendamento)	O fuso horário que o próprio plano usa.
Next run	A próxima execução real do plano inteiro; um plano concluído mostra –. Não é necessariamente igual a “este horário”.
Project / repositories (Projeto / repositórios)	Os projetos e repositórios de destino salvos com o plano.
Agent	Aparece apenas quando o plano tem um Agent, e mostra Random agent from the plan pool.

Edit e Delete na parte inferior da gaveta alteram ou excluem o plano. Em um plano recorrente, eles primeiro perguntam a qual horário a ação se aplica; veja Editar um plano e Excluir um plano.

Criar um plano

As caixas de diálogo de criação de proposta e de HagiTask podem passar de “iniciar agora” para “iniciar em um horário agendado”. Create Normal Session (Criar sessão normal) não tem o interruptor de plano.

1. Abra uma caixa de diálogo de criação como de costume, por exemplo New Idea (Nova ideia), e preencha o nome da ideia, o projeto e o pedido. Para os campos, veja Sessões.

2. Olhe para o canto inferior direito da caixa de diálogo. Ao lado do botão de envio há um interruptor Plan (Plano), desativado por padrão.

   

3. Ative o interruptor Plan. A caixa de diálogo passa para o modo de plano:

   • O rótulo no canto superior esquerdo muda de Create Proposal para Proposal plan (Plano de proposta).
   • Um campo obrigatório Plan name (Nome do plano) aparece no topo de Basic Setup, por exemplo “Weekly release check”, com até 200 caracteres.
   • Uma seção Schedule (Agendamento) aparece.
   • O botão de envio passa a ser Save plan (Salvar plano).

   

4. Defina quando o plano é executado em Schedule; veja Definir o agendamento. Um plano de HagiTask também precisa de um Agent; veja Escolher um Agent para um plano de HagiTask.

5. Clique em Save plan. O HagiCode mostra um aviso Plan saved (Plano salvo); clique em View plans (Ver planos) para abrir o gerenciador de planos imediatamente.

   

A lista Required content (Conteúdo obrigatório) mostra em tempo real o que ainda falta. Um plano de proposta verifica Project, Requirement description, Plan name e Schedule; um plano de HagiTask verifica Project, as entradas obrigatórias da própria HagiTask, Plan name, Schedule e Agent. Quando tudo está pronto, mostra All required content is ready.

Largura da janela e layout

Quando a janela é larga o suficiente (cerca de 1464 pixels ou mais), Required content e Schedule aparecem como dois cartões à direita da gaveta. Em uma janela mais estreita, Schedule passa para a parte inferior da gaveta, acima do botão de envio, e Required content se recolhe em uma barra que você pode expandir. O conteúdo e as regras são idênticos nos dois layouts.

Os planos não podem incluir imagens. Se já houver imagens anexadas ao formulário, o interruptor Plan fica desativado e avisa que você deve removê-las antes de salvar a tarefa como plano.

Definir o agendamento

Os dois botões no topo de Schedule escolhem como o plano é executado: Run once (Executar uma vez) ou Recurring (Recorrente). Nos dois modos, Next run na parte inferior da seção é atualizado em tempo real para o próximo horário de execução que as configurações atuais produzem. Se mostrar Not scheduled (Não agendado), nenhum horário de execução é possível com as configurações atuais; ajuste as datas ou o horário.

Executar uma vez

Executa uma única vez.

Campo	Descrição
Date (Data) e Time (Hora)	O dia e a hora da execução. O padrão é amanhã às 09:00. Deve ser posterior ao momento atual.
Run in (Executar em)	Botões rápidos: +5 min, +10 min, +30 min, +1 hour, contados a partir de agora.
Next at (Próximo às)	Botões rápidos: 02:00, 09:00, 12:00, 18:00, 22:00. Escolhem a próxima ocorrência desse horário: hoje, se ainda estiver por vir, ou amanhã, caso contrário.
Time zone (Fuso horário)	O fuso horário em que a data e a hora são interpretadas. O padrão é o fuso horário atual do navegador.

Recorrente

Repete diariamente ou semanalmente entre uma data de início e uma data de término.

Campo	Descrição
From (De) e To (Até)	A primeira e a última data do período, ambas inclusivas. O padrão é começar hoje e durar um mês. Em Start (Início), Today, Tomorrow, In 1 week, In 1 month e In 3 months definem rapidamente a data de início; em Length (Duração), +1 week, +1 month e +3 months definem a duração.
Time (Hora)	A hora do dia de cada execução, no formato HH:mm. Quick time (Hora rápida) oferece 02:00, 09:00, 12:00, 18:00 e 22:00.
Repeat (Repetir)	Every day (Todos os dias) ou Every week (Toda semana).
On (Em)	Aparece quando você escolhe Every week. Escolha os dias da semana, de Mon a Sun, em que o plano é executado; escolha pelo menos um.
Time zone (Fuso horário)	O fuso horário em que a hora é interpretada. Cada execução segue o horário local desse fuso, então um plano diário às 02:00 continua às 02:00 nas mudanças de horário de verão.

Para tornar um plano “de longa duração”, defina To bem adiante, por exemplo clicando em +3 months. Depois da data de término, o plano passa a Completed e deixa de ser executado.

Escolher um Agent para um plano de HagiTask

Um plano de proposta não precisa de Agent. Um plano de HagiTask deve ter um Agent selecionado, porque ninguém estará presente para escolher um quando ele for iniciado por conta própria:

• No modo de plano, a caixa de diálogo mostra uma seção de seleção de Agent explicando que este é o Agent com o qual o plano é executado e que o plano mantém essa escolha quando é iniciado. Clique em um Agent para selecioná-lo.
• A barra inferior mostra Agent: name. Até você escolher, ela mostra No agent selected yet. e o plano não pode ser salvo.
• Atualmente um plano só pode ter um Agent. Para criar Agents, veja Agents.

Editar um plano

Há duas formas de chegar lá: clique em Edit na gaveta de detalhes de um horário no Calendar, ou clique em Edit na linha do plano em All plans. Nos dois casos, o HagiCode primeiro lê o conteúdo salvo mais recente do plano e depois abre a mesma caixa de diálogo usada para criá-lo, no modo de plano. Um plano salvo continua sempre sendo um plano: o interruptor Plan fica bloqueado e não pode transformá-lo de volta em uma tarefa normal.

Um plano único

O editor abre diretamente. Altere o nome, o conteúdo, o Agent ou o horário e clique em Save plan.

Um plano recorrente: este horário ou a série inteira

Quando você edita um plano recorrente a partir da gaveta de detalhes do calendário, primeiro aparece uma caixa de diálogo de escopo:

Opção	O que altera
This occurrence (Esta ocorrência)	Apenas o horário que você abriu. Os outros horários do plano permanecem como estão.
Entire series (Série inteira)	Todos os horários do plano recorrente. Os horários que foram alterados individualmente e já não correspondem ao novo agendamento são redefinidos.

Edit a partir de All plans sempre edita a série inteira.

Quando você edita a série inteira, o topo da gaveta diz This is a recurring plan. Saving changes the entire series, not a single time., para lembrar que salvar afeta todos os horários.

Quando você edita este horário, o topo da gaveta diz “Saving changes only this time, …”, e a área de agendamento se reduz à data, hora e fuso horário deste horário; ela não pode mais ser alterada para recorrente. Você pode alterar o horário de execução, o nome, o pedido e o Agent deste horário; qualquer campo que você deixar como está continua acompanhando a série inteira.

Depois de salvar, você volta ao calendário. O horário alterado agora tem o ícone de lápis (Changed), e o topo do calendário mostra Saved.

Se o plano salvo não tiver nenhum horário de execução no mês, na semana ou na agenda exibidos no momento, o calendário mostra "…" has no scheduled time in this period e oferece um botão All plans, onde os detalhes do plano continuam disponíveis.

Excluir um plano

Também há duas formas de excluir, e as duas pedem confirmação primeiro.

• A partir do calendário: clique em Delete na gaveta de detalhes de um horário. Um plano recorrente primeiro pergunta o escopo: escolha This occurrence e clique em Continue para chegar à confirmação Delete this time?, ou escolha Entire series para confirmar a exclusão do plano inteiro. Um plano único tem apenas um escopo, então vai direto para a confirmação de exclusão.

  

• A partir de All plans: clique em Delete na linha do plano e confirme para excluir o plano inteiro.

  

Excluir um horário apenas impede que esse único horário seja executado; excluir o plano inteiro interrompe o plano. Nos dois casos, as sessões que já foram iniciadas são mantidas.

Gerenciar planos em All plans

Passe para All plans para ver todos os planos. Cada linha é um plano.

Cada linha contém:

• O nome, um selo de tipo Proposal ou HagiTask e um selo de estado Scheduled ou Completed.
• Um resumo do agendamento, por exemplo Weekly on Mon, Tue, Wed, Thu, Fri 02:00 AM, Oct 19, 2026 - Jan 18, 2027 (America/New_York).
• Next run. Um plano concluído mostra –.
• File (Arquivo): a localização do arquivo do plano, no formato Scheduled Plans / plan id / series.md. O botão ao lado copia o caminho completo do arquivo. Veja Arquivos do plano.

Os controles à direita de cada linha:

Controle	O que faz
Interruptor Enabled / Disabled	Ativa ou desativa o plano. Um plano desativado não é executado automaticamente, mas continua na lista e no calendário. Quando você o ativa de novo, o HagiCode recalcula a próxima execução a partir do momento atual; os horários perdidos enquanto ele esteve desativado não são recuperados.
Run now (Executar agora)	Cria uma sessão agora mesmo a partir das entradas salvas; em caso de sucesso, a linha mostra Session started. Isso não altera o agendamento do plano nem Next run, e um plano desativado ou concluído também pode ser executado manualmente.
Edit (Editar)	Edita o plano inteiro; veja Editar um plano.
Delete (Excluir)	Exclui o plano inteiro; veja Excluir um plano.

Arquivos do plano

Quando você salva um plano, o HagiCode sincroniza o conteúdo dele com arquivos Markdown no vault Scheduled Plans, que o HagiCode gerencia para você; você não precisa criá-lo. Cada plano recebe uma pasta com o nome do seu id:

• series.md: a configuração do plano e o texto do pedido.
• occurrence-<time>.md: um para cada horário alterado que tem conteúdo próprio.

Esses arquivos são cópias geradas a partir do plano, úteis para ler, pesquisar ou referenciar em outro lugar. O HagiCode os reescreve a partir do conteúdo mais recente do plano e os remove quando o plano é excluído. Para alterar um plano, edite-o no gerenciador de planos: alterar um arquivo não altera o plano, e a alteração é sobrescrita. Em All plans, clique no botão de copiar na linha File para obter o caminho completo do arquivo. Para saber mais sobre vaults em geral, veja Vault.

Quando os planos são executados

• Os planos são executados apenas enquanto o HagiCode estiver em execução. O HagiCode verifica a cada 30 segundos se há planos vencidos, então uma execução pode começar até cerca de 30 segundos depois do horário agendado.
• Os horários perdidos são recuperados uma vez. Se o HagiCode não estava em execução quando um plano venceu (por exemplo, o computador estava desligado), o plano é executado uma vez assim que o HagiCode inicia, e depois a próxima execução é agendada normalmente. Por mais vezes que o horário tenha sido perdido, ele é executado apenas uma vez, não em lote.
• As execuções com falha não são repetidas. Se uma execução não consegue criar a sessão (por exemplo, o projeto foi removido ou o Agent escolhido está indisponível), essa execução é ignorada e o plano aguarda o próximo horário agendado. Para se recuperar, corrija o problema e clique em Run now. Se uma execução manual falhar, a linha mostra Run now failed: e o motivo.
• Um plano único passa a Completed depois de ser executado. Para usá-lo de novo, clique em Edit e defina um novo horário no futuro. Ativar o interruptor de um plano único expirado é rejeitado, porque o horário de execução dele já passou.
• Toda execução cria uma nova sessão. Um plano de proposta cria uma sessão de proposta e um plano de HagiTask cria uma sessão de HagiTask. Elas aparecem no quadro de sessões como as sessões que você cria manualmente.

Perguntas frequentes

Ao salvar um plano, aparece a mensagem de que o horário de execução deve ser posterior ao horário atual ou de que é preciso escolher pelo menos um dia da semana. É a validação do formulário, e o motivo aparece abaixo do campo. Um plano único deve ser posterior ao momento atual. Em um plano recorrente, a data de término não pode ser anterior à de início, um plano semanal precisa de pelo menos um dia da semana e o intervalo deve conter pelo menos uma execução possível.

O interruptor Plan está esmaecido. Há imagens anexadas ao formulário, e os planos não aceitam imagens. Remova-as e o interruptor volta a funcionar.

O plano que acabei de salvar não está no calendário. O calendário mostra apenas os horários dentro do intervalo de mês, semana ou agenda exibido na tela. Passe para um mês que contenha essas datas ou veja o plano em All plans.

Os horários no calendário são diferentes do que eu defini. O calendário organiza os horários no Display time zone, que por padrão é o fuso horário do navegador. O fuso horário do próprio plano aparece como Schedule time zone nos detalhes, e um plano sempre é executado de acordo com o seu próprio fuso horário.

Um plano não foi executado quando venceu. Verifique em ordem: o plano está Enabled; Next run é o horário que você espera (principalmente o fuso horário); o HagiCode estava em execução naquele momento; o projeto e o Agent usados pelo plano ainda existem; aquele horário específico não foi excluído. O calendário mostra as configurações do plano, não um registro de execuções, então não pode confirmar se algo foi executado.

Onde os planos ficam armazenados? Todos os planos ficam em scheduled-plans.json, no diretório de configuração gerenciado pelo sistema do HagiCode. Eles não dependem do navegador, então abrir o mesmo HagiCode em outro navegador mostra os mesmos planos.

SessõesConheça o quadro de sessões e onde aparecem as sessões iniciadas por planos.

Habilidades e HagiTaskInstale HagiTasks e depois crie planos de HagiTask para elas.

AgentsCrie o Agent de que um plano de HagiTask precisa.

Visão geral do workbenchVolte ao tour de todo o workbench.