Witly Grimório — como funciona
Uma plataforma na Cloudflare que dá ao agente do consultor três coisas: templates de análise (kit com Python que gera o relatório), roteiros (conversas em etapas) e o conhecimento do time (métricas, diagnósticos, regras, casos, clientes e campanhas). O MCP é inteligência, não compute: o Python roda na máquina do consultor. Atualizado em 2026-09-14 · specs 001 a 008 em produção.
O fluxo, ponta a ponta
Os três jeitos de usar
kind = analise
Um documento, com Python
obter_template(slug): manifesto, tarefas de contexto, queries, documento, guia e a URL assinada do zip.- As tarefas de contexto com o consultor (lançamento, funil, metas, recorte) viram o
config.json. montar_querydevolve o SQL preenchido; roda no Delfos; salvadump.csvlocal.python gerar.py→ 4 camadas +numeros.json+relatorio.html(o mesmo relatório do app, offline).- Aprofundamento: o agente propõe as perguntas norteadoras, calcula o corte em Python sobre o
calc.pye rodaaprofundar.py.
Sete templates: acompanhamento diário, debriefing, criativos, histórico, conversão por perfil, análise livre e o recorte quente.
kind = conversa
Uma conversa em etapas, sem Python
Nem todo trabalho vira HTML. O roteiro descreve uma conversa: cada etapa diz o que o agente entrega, o que ele espera do consultor para avançar, o que registra antes de seguir e o que puxa do conhecimento.
A regra é não fazer tudo de uma vez: entrega a etapa, pergunta, anota, avança.
otimizar-trafego— report geral, por temperatura, campanha a campanha e decisão uma por vez. "Roda o report" para na etapa 1; "otimização" vai até o fim.novo-cliente— monta o contexto do cliente pela página dele ou por perguntas e termina propondo a entrada.
O cérebro do time
Entradas curtas e tipadas que o agente puxa quando precisa: a fórmula de uma métrica, o que um sintoma costuma significar, como escrever o report, o contexto de um cliente, o que já funcionou numa situação parecida.
Título de até 200 caracteres, corpo de até 2.000. O que não cabe vira outra entrada. Nada é enciclopédia: tudo é escrito em função dos negócios que a gente analisa.
Tool conhecimento(filtro), resource conhecimento://<id>, tela #/conhecimento.
O conhecimento: como é organizado
Uma tabela só, com quatro eixos. Os eixos são o que permite o agente pedir pouco e certo, e você filtrar na tela sem rolar lista.
| Eixo | Responde | Valores |
|---|---|---|
| tipo (em família) | que natureza de conhecimento é | 17 tipos, abaixo |
| domínio | de que assunto trata | analise · dados · midia · negocio · comunicacao · design |
| escopo | onde vale | geral · template:<slug> · funil:<tipo> · cliente:<slug> · campanha:<id> |
| nível | em que altura da decisão | estrategico (direção do negócio) · tatico (como conduzir) · operacional (execução do dia) |
Mais as tags, livres, com vocabulário sugerido por grupo (mídia, funil, métricas, leitura, dados, entrega, processo). É a tag que junta tudo o que é de tráfego pago, por exemplo.
Cada tipo tem campos próprios, validados: metrica tem fórmula, unidade, se maior é melhor, onde está no Delfos e as armadilhas; diagnostico tem sintoma, causas em ordem e o que checar; caso tem a situação estruturada e Fato, Causa, Ação, Resultado. O formulário da UI é gerado desses campos, então não existe entrada pela metade.
Como o contexto chega ao agente
Despejar tudo no contexto estraga a análise e custa caro. O conhecimento vem em camadas, e cada entrada declara quando é puxada.
- nível 0
- Sempre. Em toda chamada: as correções urgentes pendentes e as entradas marcadas
sempre, em uma linha cada. Teto de 40 entradas e 10 KB — promover uma com a cota cheia exige dizer qual sai. - nível 1
- Ao abrir o template. As regras do próprio kit e um índice (só títulos, até 40 linhas) do conhecimento escopado àquele template, funil e tags.
- nível 2
- Ao identificar cliente ou campanha. O resumo do cliente, ou o da campanha com metas, tetos, budgets, pendências e os últimos eventos.
- nível 3
- Por gatilho. O corpo completo, só quando a etapa pede:
ao_consultar_dados(antes do SQL),ao_diagnosticar(número fora da faixa),ao_recomendar(antes de propor ação, inclui os casos que já funcionaram),ao_escrever(antes de redigir),ao_fechar.
Cada etapa de um roteiro declara os gatilhos dela. Entrada sem gatilho só aparece por busca. A tela Saúde mostra quanto do orçamento do nível 0 está em uso, e o registro de uso por entrada mostra o que nunca é lido.
Como o conhecimento muda
Ninguém edita direto
Toda mudança é uma proposta na própria entrada: nova, edição, substituta, fechar resultado ou superseder. Vem da UI (botão Propor) ou do agente (sugerir), sempre com o motivo: o que aconteceu que mostrou a falta.
- Proposta parecida com uma existente aparece antes de salvar: se é a mesma coisa, vota na que já existe.
- Proposta idêntica já aberta só conta uma ocorrência e sobe na fila.
- Recusada é lembrada por 90 dias, com o motivo — não reabre sozinha.
Editor ou votos
Um editor aprova quando quiser. Sem editor, 2 votos líquidos aprovam (o número é configurável). O que entrou por votos fica 30 dias num painel com Reverter: a entrada volta à versão anterior e o histórico permanece.
Nada se apaga. Entrada substituída fica supersedida apontando para a nova, e cada versão vira um snapshot no histórico, com diff e restaurar.
O erro que contamina as próximas análises
Cálculo errado, métrica usada com o sentido trocado, regra de dado quebrada: urgencia: urgente, com evidência do número errado.
- Só editor aprova; votos não valem.
- Até a aprovação, o agente mostra a pendência ao consultor antes de gerar e pergunta se está certo.
- A resposta do consultor vira voto (
confirmar); se ele é editor, a próxima análise já nasce com a correção.
Confiança numérica engana. O que vale é ter dono e prazo: qualquer editor marca uma entrada como verificada, com data e, se quiser, um prazo para reverificar. O MCP devolve esse status junto da entrada ("verificada em 01/09 por X" ou "não verificada"), e a Saúde acusa as vencidas.
Campanha: o que foi feito e o que deu
Uma campanha é uma entrada de conhecimento com linha do tempo: contexto, análise, achado, ação e resultado. É onde o histórico do cliente para de morar na cabeça de quem operou.
| Evento | De onde vem | Vale quando |
|---|---|---|
analise | o agente registra a entrega (registrar) | na hora — é log do que foi entregue |
achado · acao do agente | registrar({campanha, eventos}) | entra marcado proposto; só conta como feito depois que uma pessoa confirma |
acao da pessoa | botão "+ Registrar" na campanha | na hora — quem registrou foi gente |
A ação é genérica e serve a qualquer frente (tráfego, CRM, página, oferta, conteúdo, dados): área, nível, alvo, verbo, valor, o fato com número e janela, a causa com o motivo real do consultor, o resultado e a data de verificar.
O ciclo fecha: quando a data de verificação chega, a ação aparece no resumo da campanha que o agente recebe, com a instrução de perguntar o resultado antes de olhar o dia. É a primeira etapa do roteiro de tráfego. A tela Ações reúne tudo o que foi feito em todos os clientes, com filtro por área, nível, verbo, resultado e "só a verificar".
As tools do MCP
| Tool | Para quê |
|---|---|
listar_templates | o catálogo: análises e roteiros, com objetivo, quando usar e parâmetros |
obter_template | o kit completo (ou o roteiro em etapas) + urgentes pendentes + o conhecimento sempre + o índice do escopo + a URL do zip |
montar_query · guia · perguntas | SQL preenchido e escapado · guia de leitura · perguntas norteadoras |
conhecimento | busca em camadas: família, tipo, domínio, nível, escopo, cliente, campanha, gatilho, tags, texto, situação. indice (1 linha) ou completo |
sugerir | propor conhecimento ou correção; urgente exige evidência. Nunca muda nada direto |
confirmar | a resposta do consultor a uma pendência urgente; vira voto |
registrar | geração, aprofundamento e feedback de uso ao fechar; leva usadas (o conhecimento que entrou) e eventos da campanha |
avaliar · salvar_template · remover_template | nota do consultor ao template · template pessoal salvo pelo agente |
| resources | conhecimento://<id> · template://<slug>[/parte] · contrato://widgets (design system) |
A UI, tela por tela
| Tela | O que faz |
|---|---|
| Templates | catálogo com filtro por análises e roteiros; editor por abas (manifesto, tarefas, regras, queries, Python, documento, guia, perguntas, exemplo, versões). Roteiro tem a aba Roteiro, onde as etapas se editam e reordenam. Publicar escolhe o tamanho da mudança e mostra o diff |
| Conhecimento | busca sem acento e filtros por família, tipo, domínio, nível, escopo, tag, status, "sempre" e "não verificadas" — tudo na URL. A entrada mostra corpo, campos, gatilhos, uso, relações, propostas e histórico |
| Pendências | propostas abertas (com urgentes no topo), aprovadas por votos com Reverter, casos e testes a fechar, e a triagem do que o agente registrou |
| Campanhas · Ações | a linha do tempo de cada campanha, com confirmar e fechar resultado; e tudo o que foi feito em todos os clientes, com o que falta verificar |
| Design system | galeria interativa dos elementos (renderizada pelo mesmo viewer dos relatórios), regras, contrato e versões. Entra em todo kit como design-system.md |
| Atividade · Saúde | o que os agentes registraram, com veredito; e o que está parado, o que estourou o orçamento do nível 0 e o que ninguém verificou |
| Usuários · Configurações | convidar, promover a editor, cortar acesso; número de votos que aprova e os limites |
Princípios que não mudam
- Número nasce no Python; o modelo escreve prosa.
- Dado pessoal nunca sobe. Linha crua nunca; agregado pode.
- O agente propõe, nunca decide sozinho: conhecimento entra por proposta, ação de campanha entra por confirmação.
- A decisão de mídia é do consultor. O registro guarda o motivo real dele.
- Entrada curta e aplicada ao negócio: nada de enciclopédia.
- Nada se apaga: supersessão e histórico.
- Template autossuficiente e versionado; o MCP serve só o publicado.
- Uma plataforma, um login (Google). Spec-driven, com teste por tarefa.
O que usa
| Peça | Tecnologia | Para quê |
|---|---|---|
| Worker | Cloudflare Workers, Hono, TypeScript | API, OAuth, downloads, UI |
| MCP | agents (McpAgent, Durable Object) + @modelcontextprotocol/sdk | tools e resources por Streamable HTTP |
| Login | @cloudflare/workers-oauth-provider + Google OAuth | registro dinâmico de cliente; token MCP com e-mail |
| Dados | D1 (SQLite) + FTS5 | templates, versões, arquivos do kit, tarefas; conhecimento com histórico por trigger, busca sem acento, relações tipadas, propostas, votos e uso; atividade; usuários |
| Estado OAuth | KV OAUTH_KV | códigos, tokens, grants |
| Estáticos | Workers Assets (public/) | UI e o viewer (client do app empacotado com esbuild) |
| Kit | zip montado na hora (fflate) | autossuficiente, sem git: python/ (cópia literal do app/pysrc), viewer/, exemplo/, design-system.md, textos. Roteiro não tem zip |
| Máquina da pessoa | Python 3.8+ (stdlib) · curl | gerar as camadas e o HTML; cortes em Python sobre o calc.py |
| Testes | Vitest (pool de Workers) · unittest · script de paridade | 95 testes no Worker, os testes de cada kit, kit == app |
Requisitos para estar funcionando
- Worker publicado (
npm run deploy) noworkers.dev. - D1
witly-templatescriado, migrations aplicadas, seed rodado (npm run seed:remote). - KV
OAUTH_KVcriado; ids nowrangler.jsonc. - Secrets:
GOOGLE_CLIENT_ID,GOOGLE_CLIENT_SECRET,COOKIE_ENCRYPTION_KEY. - Vars:
ALLOWED_DOMAIN=witly.digital,EDITOR_SEED(primeiro editor),PUBLIC_URL(a URL do Worker).
- Um OAuth client (tipo Web) com redirect
https://<worker>/callback. - Tela de consentimento com escopos
email profile.
- Um agente com MCP remoto (Claude Code, Claude.ai, Codex, Cursor).
- Conta Google do domínio.
- Python 3 e curl para os templates de análise. Acesso ao Delfos para o dado.
Como instalar (a pessoa)
claude mcp add --transport http witly https://grimorio.witly.com.br/mcp # Claude Code # Claude.ai: Conectores → adicionar → a mesma URL # Codex/Cursor: a mesma URL no config # → abre o navegador → login Google → pronto
Estado
| Spec | O que entregou | Estado |
|---|---|---|
| 001–002 | Worker, D1, OAuth Google, MCP, montar_query, zip assinado, viewer offline, seed e paridade kit == app; atividade, curadoria, versões com diff e restaurar, templates pessoais, perguntas norteadoras, aprofundamento no design system | ✓ em produção |
| 003 | gerar.py genérico por manifesto (--goals/--dict/--hist, --opts) e os kits debriefing, criativos, histórico e conversão por perfil; filtros offline no viewer; versão semântica | ✓ em produção |
| 005 | Kit sem query_api: o agente escreve o corte em Python sobre o calc.py; perguntas e definições viram entradas; sugerir_regra; seed idempotente por hash | ✓ em produção |
| 006 | Design system como template versionado: galeria interativa, regras como entradas, contrato em todo kit | ✓ em produção |
| 007 | Os 13 pedidos do feedback de uso (card e destaque vivos no filtro, filtro validado, seletor inline, dinheiro exato, tabela com escala, chrome) e o feedback como evento do MCP, com triagem | ✓ em produção |
| 008 | O conhecimento: 17 tipos em 6 famílias × domínio × escopo × nível; camadas e gatilhos; propostas com votos, urgência e reversão; verificação com dono e prazo; roteiros (kind = conversa); campanha com linha do tempo e a tela de Ações | ✓ em produção |
Hoje no ar: 7 templates de análise, 2 roteiros, o design system e 75 entradas de conhecimento (32 no nível 0).
Fonte: witly-templates/specs/ (uma pasta por spec, com spec.md, tasks.md e evidencias*.md) e constitution.md. Este desenho é atualizado ao fechar cada fase.