ZoaK
Zepp OS Agent Knowledge Base
Uma camada ciente de compatibilidade entre as fontes oficiais do Zepp OS e os agentes de IA que escrevem código para Zepp OS.
- 513símbolos
- 50módulos
- 41dispositivos
- 33apps de exemplo lidos como código
Calculado a partir de data/ a cada render, nunca digitado à mão.
A pergunta que ela existe para responder
Isto não é um espelho da documentação. A documentação oficial existe, mas não está no formato que um agente consegue consumir de forma confiável quando a pergunta é “posso chamar esta API, neste runtime, neste API_LEVEL?” Este projeto extrai essas fontes para uma camada estruturada em que essa pergunta tem resposta verificável.
A falha específica que ela evita é um agente produzir código Zepp OS plausível que não consegue justificar. Todas as avaliações feitas até aqui terminaram a tarefa e nenhuma ficou bloqueada — elas falharam em comprovar, entregando código que a base não conseguia sustentar com uma citação. É esse o problema, não o desconhecimento.
O que as fontes não carregam
Compatibilidade como eixo
Qual símbolo roda em qual API_LEVEL mínimo, cruzado com os dispositivos que declaram um.
Atribuição de runtime
Em qual dos cinco runtimes um símbolo é válido, tirado do caminho da fonte, nunca do texto da página.
Contradição entre fontes
Onde a documentação e os samples publicados discordam, declarada em vez de resolvida em silêncio.
Busca reversa
Símbolos, membros, valores de enum e propriedades de shape indexados pelo que você digitaria, não por onde eles moram.
Como funciona
fetchclonar ou atualizar os repositórios oficiais em um cache localparsedez frentes, cada uma lendo um formato de fonteenrichfundir as frentes em um registro por símbolostoregravar o JSON fonte de verdade, um arquivo por módulorendergerar o Markdown que o agente lê
E três coisas que consomem isso:
verifyfazer perguntas reais à base renderizada e checar as respostascheckpontuar um diretório de app contra a basemcpservir a base por MCP, para o agente consultar em vez de ler
O JSON em data/ é a fonte de verdade; a árvore Markdown é derivada e reproduzível. O CI re-renderiza e falha em qualquer diferença, então uma página editada à mão não sobrevive.
Como usar
Tudo roda localmente. Clone o repositório e instale — não há nada para sincronizar antes, porque data/ e as páginas renderizadas estão commitadas:
git clone https://github.com/FelipeRicardo5/zeppos-agent-knowledge-base.git
cd zeppos-agent-knowledge-base
npm install
npm run sync só é necessário para mover a base contra o upstream; um clone novo já é legível. Ele clona os repositórios oficiais em .cache/ e reescreve data/.
Três formas de entrar, na ordem de quanto quem consome precisa ler.
-
Consultar por nome
npm run mcpDezesseis tools somente-leitura sobre stdio. Chame get_freshness primeiro: um relatório que não consegue nomear a versão que leu não pode ser comparado com outro. Nada para autenticar, e nenhuma requisição sai da máquina.
-
Pontuar um app contra a base
npm run check -- caminho/para/um/appConfere um diretório sob quatro regras — runtime, permissão, API_LEVEL e manifest — e devolve um veredito por linha, em vez de um passou ou não passou.
-
Ler o Markdown renderizado
api/ compatibility/ runtimes/ patterns/ …Está commitado, então clonar basta. É isto que a Agent Skill em skills/zepp-os/SKILL.md lê: ela não carrega documentação própria, só como usar esta base.
O que o check responde
| Status | Significado |
|---|---|
VOUCHED | Esta base consegue apontar o registro que sustenta aquilo |
UNVERIFIABLE | Não coberto aqui. Nunca evidência de que o símbolo não existe |
VIOLATION | Esta base contradiz aquilo |
Ausência de violação não é aprovação. Todo relatório traz uma lista notChecked, porque um checador que listasse só o que encontrou ensinaria o leitor a ler silêncio como aprovação — exatamente a leitura que este projeto existe para evitar.
O que tem dentro
Gerado a partir de data/ a cada render. O que cada número significa é a parte que vale ler; o tamanho de hoje está na tabela.
| O quê | Quantidade |
|---|---|
| Símbolos | 513 |
| Módulos | 50 |
OFFICIAL / OBSERVED | 496 / 17 |
Símbolos que declaram API_LEVEL mínimo | 353 |
| Símbolos com descrição | 435 |
| Símbolos com assinatura de chamada | 234 |
| Símbolos com tabela de propriedades, e propriedades nelas | 184, 1300 |
| Tipos declarados sob um heading sem coluna de nome | 142, 232 |
| Conjuntos de valores, e membros neles | 55, 388 |
| Membros de instância | 257 |
| Por runtime | device-app 375, watchface 105, settings 21, side-service 20, workout-extension 12 |
| Dispositivos, dos quais rodam Zepp OS com nível declarado | 41, 29 |
| Padrões de boas práticas | 11 |
| Apps de exemplo lidos como código | 33 |
O que mantém a base honesta
Um render reproduzível
data/ e as páginas renderizadas estão ambas commitadas, então o CI re-renderiza de um checkout limpo e falha em qualquer diferença — a regra “JSON é a fonte de verdade”, tornada verificável.
Perguntas, não cobertura
O verify faz às páginas renderizadas um conjunto fixo de perguntas que um desenvolvedor faria de verdade, e falha nomeando a que deixou de ter resposta. Cada pergunta carrega o motivo de estar no conjunto.
Um sync semanal que abre PR
Todo bug de parser aqui foi uma mudança de formato upstream que deixou a extração silenciosamente menor. Contagem que caiu é o que se olha, e um diff revisável é a única forma em que esses já foram pegos.