qqbot-remind

QQ Bot Lembretes Agendados

⚠️ Regras de Intenção

Só chame a ferramenta quando o usuário pedir explicitamente para criar, consultar ou cancelar lembretes/alarmes/tarefas agendadas. Não chame a ferramenta em conversas casuais, hipóteses, explicações sobre a função de lembrete ou discussões sobre planos futuros sem solicitação de criação.

Se o usuário realmente pedir um lembrete, você não tem memória ou thread em segundo plano — prometer verbalmente "lembrar na hora" é ineficaz. Você deve chamar a ferramenta para realmente registrar a tarefa agendada. Se hora, conteúdo do lembrete, sessão de destino ou fuso horário não estiverem claros, pergunte primeiro; não adivinhe pelo usuário.

---

Fluxo Recomendado (usando a ferramenta qqbot_remind)

Passo 1: Chame a ferramenta qqbot_remind com parâmetros simples:

Parâmetro	Descrição	Exemplo
action	Tipo de operação	"add" / "list" / "remove"
content	Conteúdo do lembrete	"Beber água"
to	Endereço de destino (opcional, obtido automaticamente pelo sistema, geralmente não precisa preencher)	—
time	Horário (tempo relativo ou expressão cron)	"5m" / "1h30m" / "0 8 * * *"
timezone	Fuso horário IANA (recomendado para lembretes periódicos)	"America/Sao_Paulo" / "America/Los_Angeles"
jobId	ID da tarefa (apenas para remove)	"xxx"

Passo 2: Com base no resultado retornado por qqbot_remind, responda ao usuário. qqbot_remind criará, consultará ou cancelará diretamente a tarefa cron do Gateway; após o sucesso, não chame a ferramenta cron novamente.

Exemplo

Usuário diz: "Me lembre de beber água em 5 minutos"

1. Chame qqbot_remind: { "action": "add", "content": "Beber água", "time": "5m" }
2. Após a ferramenta retornar sucesso, responda: ⏰ OK, vou lembrar você de beber água em 5 minutos~

---

Plano Alternativo (usando diretamente a ferramenta cron)

Use o método abaixo apenas quando a ferramenta qqbot_remind não estiver disponível, mas a ferramenta cron estiver.

Regras Principais

payload.kind deve ser "agentTurn", nunca use "systemEvent"! systemEvent só injeta texto internamente na sessão da IA; o usuário não receberá a mensagem no QQ.

Campos que não podem ser alterados:

Campo	Valor Fixo	Motivo
payload.kind	"agentTurn"	systemEvent não envia mensagem para o QQ
delivery.mode	"announce"	Modo de entrega ativa
delivery.channel	"qqbot"	Identificador do canal QQ
delivery.to	Endereço destino	Obtido do contexto da sessão atual
delivery.accountId	ID da conta atual	Obrigatório em cenários com múltiplas contas
sessionTarget	"isolated"	Isola a sessão para evitar contaminação

schedule.atMs deve ser um timestamp absoluto em milissegundos (ex.: 1770733800000), não suporta strings relativas como "5m". Cálculo: timestamp atual em ms + atraso em ms.

Lembrete Único (schedule.kind = "at")

{
  "action": "add",
  "job": {
    "name": "{Nome da tarefa}",
    "schedule": { "kind": "at", "atMs": "{timestamp atual ms + N*60000}" },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "deleteAfterRun": true,
    "payload": {
      "kind": "agentTurn",
      "message": "Você é um assistente de lembretes carinhoso. Lembre o usuário de: {conteúdo do lembrete} de forma calorosa e divertida. Requisitos: (1) Não responda HEARTBEAT_OK (2) Não explique quem você é (3) Envie diretamente uma mensagem de lembrete carinhosa (4) Pode adicionar uma frase curta de incentivo ou carinho (5) Limite a 2-3 frases (6) Use emojis para decorar"
    },
    "delivery": {
      "mode": "announce",
      "channel": "qqbot",
      "to": "qqbot:c2c:{openid}",
      "accountId": "{accountId}"
    }
  }
}

Lembrete Periódico (schedule.kind = "cron")

{
  "action": "add",
  "job": {
    "name": "{Nome da tarefa}",
    "schedule": { "kind": "cron", "expr": "0 8 * * *", "tz": "{Fuso horário IANA confirmado pelo usuário}" },
    "sessionTarget": "isolated",
    "wakeMode": "now",
    "payload": {
      "kind": "agentTurn",
      "message": "Você é um assistente de lembretes carinhoso. Lembre o usuário de: {conteúdo do lembrete} de forma calorosa e divertida. Requisitos: (1) Não responda HEARTBEAT_OK (2) Não explique quem você é (3) Envie diretamente uma mensagem de lembrete carinhosa (4) Pode adicionar uma frase curta de incentivo ou carinho (5) Limite a 2-3 frases (6) Use emojis para decorar"
    },
    "delivery": {
      "mode": "announce",
      "channel": "qqbot",
      "to": "qqbot:c2c:{openid}",
      "accountId": "{accountId}"
    }
  }
}

Tarefas periódicas não usam deleteAfterRun. Para grupos, o formato de delivery.to é "qqbot:group:{group_openid}".

---

Referência Rápida de Expressões Cron

Cenário	expr
Todos os dias às 8h	"0 8 * * *"
Todas as noites às 22h	"0 22 * * *"
Dias úteis às 9h	"0 9 * * 1-5"
Toda segunda-feira às 9h	"0 9 * * 1"
Fins de semana às 10h	"0 10 * * 0,6"
A cada hora cheia	"0 * * * *"

Para lembretes periódicos, use o fuso horário IANA que o usuário forneceu explicitamente, que esteja disponível de forma confiável no perfil/sessão do usuário, ou que tenha sido confirmado pelo usuário. Se não puder determinar, pergunte; não assuma que todos os usuários estão no mesmo fuso horário.

---

Guia de Decisão para a IA

Fala do Usuário	action	Formato do time
"Me lembre de beber água em 5 minutos"	add	"5m"
"Me lembre da reunião em 1 hora"	add	"1h"
"Me lembre de bater o ponto todos os dias às 8h"	add	"0 8 * * *"
"Me lembre dias úteis às 9h"	add	"0 9 * * 1-5"
"Quais são meus lembretes?"	list	—
"Cancele o lembrete de beber água"	remove	—
"Modifique o horário do lembrete"	remove → add	—
"Me lembre" (sem horário)	Perguntar	—

Tempos relativos puros ("em 5 minutos", "em 1 hora") podem ser calculados diretamente, sem confirmação. Se horário, data, período, conteúdo ou fuso horário estiverem ambíguos/ausentes, pergunte. Para lembretes periódicos, explique o horário local e o fuso horário na resposta.

---

Modelos de Resposta

• Único: ⏰ OK, vou lembrar você de {conteúdo} em {tempo}~
• Periódico: ⏰ Entendido, vou lembrar você de {conteúdo} {periodicidade}~
• Consulta sem resultados: 📋 No momento, não há lembretes~ Que tal dizer "Me lembre de xxx em 5 minutos"?
• Exclusão bem-sucedida: ✅ O lembrete "{nome}" foi cancelado