Pular para o conteudo

Pilar 03 · Tecnologia Aplicada

Manual

OKF Bundle Manager: Machine Discoverability no WordPress

O OKF Bundle Manager gera bundles OKF estáticos no WordPress com controle humano, discovery segura e HTML preservado como fonte canônica.

Atualizado em 17 min de leitura
Código
MAN-TA-OKFBM-001
Versão
0.2.3
Situação
Vigente
Vigência
30/10/2026
Próxima revisão
16/01/2027
Licença
CC BY 4.0
OKF Bundle Manager: Machine Discoverability no WordPress

“Como a gente entrega o conhecimento de um site WordPress para agentes de IA sem obrigar cada máquina a separar conteúdo, menu, widget, script e comentário do editor?” Essa pergunta definiu o projeto do plugin OKF Bundle Manager.

Nós precisávamos de um método consistente, confiável e eficiente para gerar um bundle OKF (pacote organizado de conhecimento) em ecossistemas WordPress, sem colocar uma API dinâmica no caminho de cada leitura e sem disputar qual página seria a “fonte oficial” (entre diversos outros imbróglios práticos).

O Open Knowledge Format (OKF), é um projeto iniciado pela Google Cloud. Você pode saber mais diretamente da fonte, clicando aqui. O foco é basicamente organizar informações em formato markdown que possam ser facilmente identificadas e consumidas por sistemas que operam com Inteligência Artificial.

Foi justamente após conhecer o OKF e pensar sobre como poderíamos prover dados para máquinas de forma mais fácil e organizada possível, que projetamos, codamos, testamos e validamos o plugin dentro da infraestrutura real do site.

Reforçando: Estamos aqui falando exclusivamente de instalações em WordPress.

Chamamos essa frente de machine discoverability optimization (otimização da descoberta por máquinas).

O foco é melhorar a forma como agentes, fetchers (sistemas que buscam um recurso sob demanda) e crawlers (robôs de rastreamento) encontram uma representação limpa do conteúdo.

Trabalhamos para reduzir o custo (esforço) de processamento de dados.

Sim, o Plugin é de desenvolvimento nosso. É um plugin In-house, feito e mantido por nós.

Então vem comigo e vamos detalhar como o Plugin OKF Bundle Manager funciona no nosso WordPress!

NOTA TÉCNICA: Todas as informações contidas aqui retratam a minha experiência e o meu método de trabalho, você é o total responsável por alterações no seu site ou no site de seus clientes. Nos responsabilizamos exclusivamente em parcerias formalizadas por contratos. Em dúvida, visite o Aviso Legal.

O que é o OKF Bundle Manager

O OKF Bundle Manager é um plugin proprietário para WordPress que compila o conteúdo público do site em um bundle Open Knowledge Format v0.2. Cada recurso vira um arquivo Markdown com frontmatter YAML (cabeçalho estruturado), URL da fonte HTML, descrição, data de geração e estado do documento.

O bundle fica disponível em nosso índice OKF v0.2. Ele reúne um mapa de páginas (incluindo os documentos técnicos), artigos e conceitos do Dicionário, seguido pelos arquivos individuais que uma máquina pode buscar somente quando precisar de mais contexto.

Essa entrega conversa diretamente com a prontidão para agentes: uma máquina precisa encontrar o conteúdo certo, entender qual fonte é canônica (Single Source of Truth – versão oficial) e receber uma representação que não dependa da interface visual feita para pessoas.

Por que o Bundle é Estático

Uma página HTML serve ao visitante, isto é, ela carrega navegação, identidade visual, CSS, componentes, scripts e outros elementos importantes para a experiência humana, mas que podem virar ruído (fricção) quando um agente de IA quer apenas o conteúdo limpo editorial.

Poderíamos entregar esse conteúdo com foco em máquinas por uma API REST dinâmica (interface que processa uma resposta a cada requisição). O problema é que cada nova consulta acionaria PHP e, dependendo da rota, banco de dados.

Em hospedagens compartilhadas (realidade da maioria das PMEs no Brasil – nossos clientes), colocar processamento de origem em toda leitura automatizada não é o método mais eficiente, e poderíamos comprometer o funcionamento da infraestrutura.

Outro caminho possível seria publicar um arquivo /pagina.md ao lado de cada URL HTML ou redirecionar o visitante para Markdown. Mas, nós recusamos essa arquitetura porque ela cria uma segunda URL concorrendo com a fonte humana e complica a governança do canonical.

Logo, a decisão foi simples: o WordPress escreve e o agente lê o arquivo. O trabalho de compilação acontece quando existe uma mudança editorial, não a cada acesso ao bundle.

Como o Plugin Funciona

O fluxo do nosso plugin OKF Bundle Manager mantém controle humano antes da escala. Ele começa com diagnóstico, passa por um piloto comparável e só então libera o processamento em lote.

Dentre os recursos do plugin, temos:

  1. Diagnóstico: o plugin confere requisitos, diretórios, extensões PHP e condições de publicação. Um semáforo vermelho bloqueia piloto e lote.
  2. Piloto: um conteúdo é convertido primeiro. O painel apresenta HTML e Markdown para uma confirmação humana antes de ampliar a execução.
  3. Lote: o inventário elegível é compilado de forma cadenciada, em blocos de cinco itens, com limite operacional e registro de status por ID.
  4. Manutenção: ao salvar um post, o plugin recompila somente aquele ID. Rascunho ou lixeira remove o arquivo correspondente. Um cron semanal verifica diferenças e também atualiza as páginas cujo HTML público mudou sem um novo salvamento, como acontece num deploy de template do tema.
  5. Publicação: os arquivos ficam em uploads/okf/ e são servidos em URLs públicas sob /okf/. Os endereços /okf e /okf/ redirecionam (301) para /okf/index.md.
  6. Discovery: a sinalização só aparece quando o bundle está saudável e o site permite indexação pública.

Parser do Conteúdo Útil

A fonte primária que define a base do conteúdo markdown é o post_content cru do WordPress. Quando (se) o corpo útil fica abaixo do limite mínimo, o plugin pode consultar o HTML canônico da mesma página e restringir a leitura a <main> ou <article>. Nas páginas e nos documentos técnicos, o plugin compara o post_content com o <main> do HTML canônico e usa a versão que traz mais conteúdo útil e mais links seguros.

Então, o parser (extrator e conversor) remove comentários Gutenberg, shortcodes, navegação, scripts, estilos e iframes; preservando títulos, parágrafos, listas, tabelas, links, ênfases, citações, código e texto alternativo de imagens. Tabelas HTML viram tabelas Markdown (GFM), blocos de código passam sem alteração e o corpo sai com exatamente um H1, o título do conteúdo.

A saída, como já mencionei, é Markdown UTF-8, sem ler opções do tema nem JSON interno de page builder.

Compilador OKF v0.2

Cada página ou artigo recebe frontmatter com o tipo do recurso, título, descrição, URL pública e referência explícita ao HTML canônico. Este é um recorte do contrato:

---
type: Article
title: "Título do conteúdo"
resource: https://asctheme.felipecferreira.com.br/slug/
generated: { by: process:okf-bridge, at: 2026-08-28T21:00:00Z }
published_at: 2026-08-28T21:00:00Z
modified_at: 2026-08-28T21:00:00Z
status: stable
sources:
  - id: canonical-html
    resource: https://asctheme.felipecferreira.com.br/slug/
    title: "Página oficial em HTML"
    last_modified: 2026-08-28T21:00:00Z
---

Nos artigos, o compilador também registra as datas de publicação e de modificação, abre o corpo com um TL;DR tirado do resumo e inclui até cinco perguntas da FAQ editorial. Documentos técnicos como este entram em Pages com o tipo Reference, e os verbetes do Dicionário entram como Concept em concepts/, terminando com os conceitos relacionados que o próprio texto já linka.

O índice separa Pages, Articles e Concepts. Um hash SHA-256 evita reescrever arquivo idêntico, reduzindo trabalho desnecessário no disco e no cache.

Entrega, Headers e Discovery

Os arquivos são entregues como text/markdown. O servidor também comunica como cada recurso deve ser interpretado:

Sinal Função
Content-Type: text/markdown Identifica a representação como Markdown.
X-Robots-Tag: noindex, follow Impede o bundle de competir como resultado indexável.
Link: <URL-HTML>; rel="canonical" Declara a página humana como fonte canônica.
Cache-Control, ETag e Last-Modified Permitem reutilização e validação eficiente da resposta.

A descoberta usa mais de uma placa. O robots.txt informa o caminho permitido, o llms.txt aponta para o índice e cada página HTML publica rel="alternate" type="text/markdown" apontando para o próprio arquivo dentro do bundle (em /okf/pages/, /okf/posts/ ou /okf/concepts/), nunca para um /pagina.md inventado a partir do slug. O HTML também publica rel="describedby" apontando para o llms.txt.

Essa redundância também encontra apoio em observação de mercado. Num censo de acessos publicado pela DEJAN AI, o bundle OKF recebeu 2.841 requisições no conjunto total, contra 157 do llms.txt. Entre agentes da OpenAI, foram 11 acessos ao bundle, sendo seis do ChatGPT-User, e nenhum ao llms.txt.

O próprio levantamento delimita o resultado: são requisições registradas no servidor, não citações nem aparições em respostas. Para nós, o aprendizado é usar sinais complementares e medir cada um pelo trabalho que realmente executa.

Integridade do Markdown

Desde a versão 0.3.6, o plugin mantém um histórico SHA-256 só de acréscimo (append-only) dos arquivos Markdown publicados. A coleta inicial registrou o hash do Markdown que já estava em disco, sem recompilar nada.

A página Verificar integridade do Markdown responde se um arquivo .md é uma versão que o site publicou. O código SHA-256 é calculado no navegador e o arquivo não sai do computador de quem consulta. Nos artigos, o link de download do .md só aparece quando a discovery pública está ligada e o arquivo estático existe, e o clique não dispara compilação.

Os limites ficam declarados na resposta: um hash ausente significa apenas que aqueles bytes não estão no histórico disponível, e a verificação não prova autoria nem falsificação. A página de verificação também envia noindex.

Painel OKF BM

No wp-admin, o menu OKF BM abre o OKF Bundle Manager. As abas Diagnóstico, Piloto, Lote, Descoberta, Infra L2 e Integridade (L2 vem da nossa padronização com foco em sistemas, para saber mais, clique aqui) mostram o estado do processo sem oferta comercial na interface e sem esconder falhas atrás de uma execução automática.

A tela de plugins também oferece o atalho Abrir painel. Esta documentação é a página pública associada ao plugin: o link Ver detalhes da tela de plugins aponta para cá, enquanto a operação permanece restrita a administradores.

Três Camadas, Três Trabalhos

O OKF Bundle Manager não substitui tudo o que o site já faz para máquinas, nem substitui qualquer trabalho sério de SEO!

Nós separamos integração, descoberta e conhecimento para evitar que um componente acumule responsabilidades incompatíveis.

Camada Trabalho Responsável
API REST Integrações e produtos como o IA Vision Map Infraestrutura fora do plugin
llms.txt e robots.txt Descoberta e política de acesso automatizado ASC Site Core
Bundle /okf/ Conhecimento estruturado para agentes OKF Bundle Manager

O plugin vive entre a aplicação e a entrega estática. Dentro do nosso Protocolo L0 a L7, o WordPress compila na camada de aplicação (L4), enquanto o servidor entrega os arquivos na camada de origem e edge (borda da rede, L2).

O HTML Continua Canônico

O bundle é uma via de leitura para máquinas, não um novo permalink editorial.

Quando alguém recebe uma citação ou decide visitar a fonte, a referência deve continuar levando para a página HTML.

  • Canonical: a URL HTML aparece no YAML e no header HTTP do Markdown.
  • Noindex: os arquivos OKF não devem ocupar espaço no índice de busca (importantíssimo).
  • Sitemap: o Yoast continua listando apenas as fontes humanas no sitemap XML.
  • Sem Redirect: não criamos um 301 de /pagina.md quando o slug HTML muda, porque essa URL irmã não faz parte do contrato.

O Yoast também permanece responsável pelo canonical, pelo Open Graph e pelo grafo de JSON-LD para SEO, GEO e AEO.

O OKF acrescenta uma representação para agentes sem tomar o lugar dessas estruturas.

Projetado, Codado, Testado e Validado por Nós

Nós não encontramos no wordpress.org um compilador OKF v0.2 com o contrato que esta arquitetura WordPress precisava: silo independente do tema, arquivos estáticos, confirmação humana, proteção contra duplicidade e trava de piloto para hospedagem compartilhada.

Isso não significa que nenhum plugin do mercado trabalhe Markdown ou descoberta para IA.

Significa apenas que este conjunto de decisões precisava ser tratado como sistema, não como um snippet colado no tema nem como uma rota dinâmica reprocessada a cada acesso.

Então precisávamos colocar a mão na massa, passando por:

  1. Projeto: especificação de execução no próprio repositório do plugin, com limites, critérios de aceite e rollback.
  2. Código: módulos separados para diagnóstico, parser, compiler, lote, hooks, headers, discovery e administração.
  3. Teste: regressões puras no Docker local, homologação em staging privado e validação posterior no live.
  4. Entrada no Live: discovery ligada no site público somente depois de o índice responder corretamente. O staging permanece sem anunciar o bundle.

Na validação de 28 de agosto de 2026, o índice público reuniu 120 itens, sendo 14 páginas e 106 artigos. O lote do acervo restante terminou com zero erros, o GET /okf/index.md respondeu 200 e os headers de noindex e canonical atravessaram a infraestrutura até a resposta pública. Em 16 de outubro de 2026, o índice reunia 130 itens: 18 páginas, 97 artigos e 15 conceitos.

Esses são dados do nosso próprio site, não números de cliente!

Eles comprovam a operação do bundle nesta infraestrutura. Não comprovam citação em ChatGPT, Perplexity ou qualquer outro motor generativo.

Infraestrutura em Operação

O OKF Bundle Manager não foi validado num WordPress vazio de demonstração. Ele roda no site público, em conjunto com cache de origem, proxy no edge, SEO técnico e outros componentes que continuam donos de suas próprias responsabilidades.

Camada Estado atual
CMS e runtime WordPress 6.6 ou superior e PHP 8.1 ou superior
Origem Hostinger com LiteSpeed e cache de página
Edge Cloudflare como proxy, preservando os headers do bundle, com Cache Rule para os arquivos .md
Tema ASC Base Theme com Gutenberg nativo no caminho editorial
SEO Yoast mantém canonical HTML, sitemap e Open Graph
Discovery ASC Site Core mantém política de crawlers e llms.txt

Hoje, a origem entrega cache e o Cloudflare repassa corretamente X-Robots-Tag e Link. Desde 28 de setembro de 2026, uma Cache Rule guarda no edge os arquivos .md do caminho /okf/, respeitando o Cache-Control da origem (até uma hora). O HTML continua fora dessa regra.

A Cache Rule é uma decisão de infraestrutura, não um requisito escondido do plugin. Nesta hospedagem ela passou a ser necessária, para que as leituras de agentes não cheguem todas à origem. O plugin não chama a API do Cloudflare, então, depois de uma recompilação, o edge pode servir a versão anterior de um arquivo por até uma hora.

O que o Plugin Não é

O nome técnico não pode esconder os limites do produto. O OKF Bundle Manager:

  • não substitui o HTML, o sitemap XML, o JSON-LD, o robots.txt ou o llms.txt;
  • não promete ranking, citação, resposta de IA ou crescimento de tráfego;
  • não cria uma versão .md concorrente para cada slug humano;
  • não publica conteúdo privado, protegido por senha, rascunho ou marcado como noindex pelo Yoast;
  • não é um ZIP público, um plugin gratuito nem um listing do wordpress.org.

Ele é uma peça da nossa abordagem de machine discoverability optimization. Cloudflare, SEO e GEO, política de crawlers, API REST e governança editorial continuam existindo fora dele.

Estado do Produto e Disponibilidade

A versão atual é a 0.3.10. O plugin está ativo no live e a discovery pública foi ligada em 28 de agosto de 2026. A janela de hardening (endurecimento e observação em produção), com acompanhamento de erros PHP e comportamento do bundle, estava prevista até 4 de setembro de 2026. Desde então, o plugin recebeu as versões 0.2.0 a 0.3.10.

Por isso, não tratamos o código como pronto e congelado. O parser, a operação de cache e o manual de infraestrutura continuam recebendo ajustes controlados.

As versões são registradas no changelog do plugin. Da 0.1.0 até a 0.3.9 entraram, entre outras mudanças, o rel=”alternate” por documento, os documentos técnicos e os verbetes do Dicionário no bundle, as tabelas em Markdown, o reparo semanal de páginas cujo HTML mudou e o histórico de integridade.

O OKF Bundle Manager é proprietário, não está disponível para download público e não pode ser instalado hoje em um site de terceiro. Talvez exista uma distribuição pública ou gratuita no futuro, mas não há promessa nem data.

Quando um projeto exige esse tipo de arquitetura, o plugin entra como parte do método e da infraestrutura que avaliamos em uma parceria de consultoria, não como produto isolado que resolve sozinho a descoberta por máquinas.

Perguntas frequentes

O que é OKF neste site?

É o Open Knowledge Format usado para organizar conhecimento em Markdown e YAML para agentes. O nosso bundle segue o contrato v0.2 e mantém a URL HTML como fonte canônica.

O bundle OKF substitui as páginas HTML?

Não. O HTML continua sendo a página oficial para pessoas, busca e citação. O bundle é uma representação auxiliar para leitura automatizada.

O OKF Bundle Manager é gratuito?

Não. O plugin é proprietário e não possui download público. Uma distribuição diferente pode ser avaliada no futuro, sem data ou compromisso anunciado.

O Google indexa os arquivos em /okf/?

O plugin envia X-Robots-Tag: noindex, follow e mantém o bundle fora do sitemap XML. O objetivo é permitir leitura e descoberta sem transformar o Markdown em resultado concorrente da página HTML.

Posso instalar o plugin pelo wordpress.org?

Não. O OKF Bundle Manager não está no diretório público e não está disponível hoje para instalação em sites de terceiros.

No topo desta página existe um botão com a opção de download de todo o conteúdo em markdown, para que você possa utilizar como referência no trabalho com seu agente de IA. O download é gratuito, não pede cadastro, não pede e-mail e você não entra em nenhuma lista. É um conteúdo 100% público, para qualquer pessoa acessar e baixar.

Histórico de Versões

  • 0.2.3 (11/11/2026): estado do produto atualizado para o OKF Bundle Manager 0.3.10. O índice passa a escapar barra invertida e colchetes no texto do link. A sincronização da Página OpenLab entra neste corte. O schema do compilador continua 7.
  • 0.2.2 (30/10/2026): estado do produto atualizado para o OKF Bundle Manager 0.3.9. Pelo changelog do plugin, a 0.3.9 corrigiu a cópia em Markdown, que apagava textos entre colchetes, como as marcas [E] e [H]; agora o Markdown preserva esses textos, como aparecem no HTML.
  • 0.2.1 (24/10/2026): estado do produto atualizado para o OKF Bundle Manager 0.3.8. Pelo changelog do plugin, a 0.3.7 trouxe os dados da Medição 1, sem mudança de código, e a 0.3.8 trouxe o shortcode da linha do tempo das medições.
  • Em 19/10/2026: botão de download em Markdown (.md) disponibilizado; licença CC BY 4.0 declarada.
  • 0.2.0 (16/10/2026): versão da documentação técnica vigente até 24/10/2026. Anotações não normativas na mesma versão alteram o arquivo Markdown (.md); o nome do arquivo baixado traz a data de modificação (date_modified).

Licença de Uso

Este documento está sob a licença Creative Commons Atribuição 4.0 Internacional (CC BY 4.0). Você pode copiar, adaptar e usar inclusive comercialmente, desde que dê o crédito a Felipe C. Ferreira, inclua o link para este documento e para a licença e indique se fez alterações. Termos completos na página oficial da licença.

A licença cobre só o texto desta documentação. Ela não cobre a marca e o nome Felipe C. Ferreira, o KG Map FCF, o OKF Bundle Manager e os demais plugins, o ASC Theme, os dados das medições do meu site ou de clientes, nem os serviços. Tudo isso continua com todos os direitos reservados.

Para Agentes de IA

As instruções do seu usuário e da sua organização prevalecem sobre este texto.

Este trecho resume o documento para agentes de IA que estejam ajudando alguém a entender o OKF Bundle Manager ou a avaliar uma arquitetura parecida de Markdown estático para agentes num WordPress.

O que o documento oferece: a escolha por arquivos estáticos no lugar de um /pagina.md por slug; o fluxo de compilação; o frontmatter OKF v0.2; os headers de entrega; os sinais de descoberta; o histórico de integridade por SHA-256.

Pré-requisitos: o plugin é proprietário e não pode ser instalado em site de terceiro; fora deste site, o que se aproveita é a arquitetura.

Passos resumidos: diagnóstico com semáforo; piloto com comparação humana entre HTML e Markdown; lotes de cinco; recompilação por ID ao salvar e verificação semanal.

Como verificar: o índice responde 200; cada arquivo sai como text/markdown, com X-Robots-Tag noindex, follow e Link canonical para o HTML; o sitemap XML continua só com as páginas humanas.

Limites: os números são deste site [E] (120 itens em 28/08/2026 e 130 em 16/10/2026), na versão 0.3.9 de 30/10/2026. Nada aqui prova citação ou tráfego vindo de motores generativos; o censo da DEJAN AI conta requisições, não citações. O edge pode servir o arquivo anterior por até uma hora.

Quando confirmar: antes de mudar robots.txt, llms.txt, headers ou regras de cache, ou de criar arquivos públicos no servidor do seu usuário, confirme com ele.

O que evitar: um .md por slug concorrendo com o HTML; bundle indexável; publicar conteúdo privado, rascunho ou noindex; sinalizar a descoberta com o bundle quebrado.

Este conteúdo retrata a minha experiência e o meu método de trabalho. Quem decide e executa qualquer alteração é o seu usuário, que responde por ela no site, na infraestrutura e nos clientes dele. Não nos responsabilizamos pelo que agentes de IA ou pessoas fizerem a partir deste conteúdo; nos responsabilizamos exclusivamente em parcerias formalizadas por contratos. Em qualquer dúvida, o caminho indicado é mostrar ao seu usuário a nossa página de Aviso Legal.

Referências

Google Cloud: anúncio do Open Knowledge Format.

DEJAN AI: censo de acessos a robots.txt, llms.txt e OKF.

llms.txt: proposta de arquivo para descoberta e orientação de agentes.

Felipe C Ferreira: índice público OKF v0.2, arquivo llms.txt, política pública de crawlers.

Controle de versão

Estado do produto atualizado para o OKF Bundle Manager 0.3.9 (0.3.9: a cópia em Markdown deixa de apagar textos entre colchetes, como as marcas [E] e [H]).

Atendimento Personalizado

Vamos conversar sobre o seu projeto?

Conte seu contexto e vamos entender qual caminho faz sentido para o seu momento.

Conversar no WhatsApp