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

Consultor + agente Claude Code · Codex · Claude.ai Python 3 na máquina gerar.py → relatorio.html ou roteiro: conversa em etapas Worker witly-templates (Cloudflare) OAuth Google → token MCP /authorize · /callback · /token · /register MCP /mcp (Durable Object) listar · obter · montar_query · guia · perguntas conhecimento · sugerir · confirmar registrar · avaliar · salvar_template · resources /dl/<slug>/<v> zip assinado (15 min) UI /api · assets conhecimento · campanhas · ações D1: templates e versões · conhecimento (FTS, histórico, propostas, votos, uso) · atividade KV (OAuth) · Assets (UI, viewer) Delfos (MCP, existe) Credentials · Witly_Query banco do cliente → CSV local Google (identidade) domínio @witly.digital = leitor O time (UI) edita template e roteiro propõe conhecimento · vota editor aprova · reverte confirma ação da campanha fecha resultado 1. cola a URL, loga 2. pede template ou conhecimento 3. curl do kit (zip) 4. SQL do kit no Delfos 5. registra · propõe
máquina da pessoa este projeto Delfos (não muda) Google o time, na UI

Os três jeitos de usar

Análise kind = analise

Um documento, com Python

  1. obter_template(slug): manifesto, tarefas de contexto, queries, documento, guia e a URL assinada do zip.
  2. As tarefas de contexto com o consultor (lançamento, funil, metas, recorte) viram o config.json.
  3. montar_query devolve o SQL preenchido; roda no Delfos; salva dump.csv local.
  4. python gerar.py → 4 camadas + numeros.json + relatorio.html (o mesmo relatório do app, offline).
  5. Aprofundamento: o agente propõe as perguntas norteadoras, calcula o corte em Python sobre o calc.py e roda aprofundar.py.

Sete templates: acompanhamento diário, debriefing, criativos, histórico, conversão por perfil, análise livre e o recorte quente.

Roteiro 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.
Conhecimento

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.

EixoRespondeValores
tipo (em família)que natureza de conhecimento é17 tipos, abaixo
domíniode que assunto trataanalise · dados · midia · negocio · comunicacao · design
escopoonde valegeral · template:<slug> · funil:<tipo> · cliente:<slug> · campanha:<id>
nívelem que altura da decisãoestrategico (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.

Saberconceito · definicao · metrica · benchmark
Pensarprincipio · diagnostico · pergunta
Fazerregra · metodo · padrao
Comunicarestilo · formato
Contextofunil · cliente · campanha
Memóriacaso · teste

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

Proposta

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.
Aprovação

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.

Urgência

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.

  1. Só editor aprova; votos não valem.
  2. Até a aprovação, o agente mostra a pendência ao consultor antes de gerar e pergunta se está certo.
  3. A resposta do consultor vira voto (confirmar); se ele é editor, a próxima análise já nasce com a correção.
Verificaçã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.

EventoDe onde vemVale quando
analiseo agente registra a entrega (registrar)na hora — é log do que foi entregue
achado · acao do agenteregistrar({campanha, eventos})entra marcado proposto; só conta como feito depois que uma pessoa confirma
acao da pessoabotão "+ Registrar" na campanhana 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

ToolPara quê
listar_templateso catálogo: análises e roteiros, com objetivo, quando usar e parâmetros
obter_templateo kit completo (ou o roteiro em etapas) + urgentes pendentes + o conhecimento sempre + o índice do escopo + a URL do zip
montar_query · guia · perguntasSQL preenchido e escapado · guia de leitura · perguntas norteadoras
conhecimentobusca em camadas: família, tipo, domínio, nível, escopo, cliente, campanha, gatilho, tags, texto, situação. indice (1 linha) ou completo
sugerirpropor conhecimento ou correção; urgente exige evidência. Nunca muda nada direto
confirmara resposta do consultor a uma pendência urgente; vira voto
registrargeração, aprofundamento e feedback de uso ao fechar; leva usadas (o conhecimento que entrou) e eventos da campanha
avaliar · salvar_template · remover_templatenota do consultor ao template · template pessoal salvo pelo agente
resourcesconhecimento://<id> · template://<slug>[/parte] · contrato://widgets (design system)

A UI, tela por tela

TelaO que faz
Templatescatá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
Conhecimentobusca 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ênciaspropostas 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çõesa 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 systemgaleria 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údeo 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çõesconvidar, 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çaTecnologiaPara quê
WorkerCloudflare Workers, Hono, TypeScriptAPI, OAuth, downloads, UI
MCPagents (McpAgent, Durable Object) + @modelcontextprotocol/sdktools e resources por Streamable HTTP
Login@cloudflare/workers-oauth-provider + Google OAuthregistro dinâmico de cliente; token MCP com e-mail
DadosD1 (SQLite) + FTS5templates, 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 OAuthKV OAUTH_KVcódigos, tokens, grants
EstáticosWorkers Assets (public/)UI e o viewer (client do app empacotado com esbuild)
Kitzip 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 pessoaPython 3.8+ (stdlib) · curlgerar as camadas e o HTML; cortes em Python sobre o calc.py
TestesVitest (pool de Workers) · unittest · script de paridade95 testes no Worker, os testes de cada kit, kit == app

Requisitos para estar funcionando

Na Cloudflare (conta Witly)
  • Worker publicado (npm run deploy) no workers.dev.
  • D1 witly-templates criado, migrations aplicadas, seed rodado (npm run seed:remote).
  • KV OAUTH_KV criado; ids no wrangler.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).
No Google Cloud
  • Um OAuth client (tipo Web) com redirect https://<worker>/callback.
  • Tela de consentimento com escopos email profile.
Na máquina de quem usa
  • 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

SpecO que entregouEstado
001–002Worker, 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
003gerar.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
005Kit 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
006Design system como template versionado: galeria interativa, regras como entradas, contrato em todo kit✓ em produção
007Os 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
008O 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.