Emrys-Merlin/agent-skills

Construa com TypeSafe

A TypeSafe disponibiliza unidades de inteligência artificial utilizáveis como primitivas de programação: pequenos julgamentos que você pode compor em capacidades maiores. Seus modelos System One retornam julgamentos rápidos e focados que o software pode consumir diretamente. Jev é o modelo principal e o primeiro System One da TypeSafe. Ele compreende linguagem natural e retorna respostas tipadas e probabilidades, em vez de gerar texto ou explicações de raciocínio. O código detém o fluxo de trabalho; o modelo fornece senso comum programável onde o código comum precisa de compreensão semântica.

Chame o Jev através do OpenRouter

Esta variante da skill chama o Jev através do OpenRouter, não pela API própria da TypeSafe. A documentação da TypeSafe continua sendo a referência para conceitos e design de perguntas; apenas acesso, IDs de modelo e faturamento diferem.

• Credencial: uma chave de API do OpenRouter, faturada na conta do OpenRouter. Nenhuma conta TypeSafe é necessária. Leia-a do ambiente (OPENROUTER_API_KEY, ou TYPESAFE_API_KEY definida com a chave do OpenRouter); nunca a codifique diretamente e mantenha-a no lado do servidor em aplicações web.
• API System One (padrão): POST https://openrouter.ai/api/v1/systemone com Authorization: Bearer <chave OpenRouter>. Ela implementa os formatos de requisição e resposta da TypeSafe e adiciona id, provider e usage.cost à resposta.
• SDKs TypeSafe (@typesafe-ai/sdk, typesafe_sdk): defina a URL base como https://openrouter.ai/api (o SDK anexa /v1/systemone) via baseURL / base_url ou TYPESAFE_BASE_URL, e passe a chave OpenRouter via apiKey / api_key ou TYPESAFE_API_KEY. Todo o resto segue a documentação do SDK da TypeSafe.
• Não chame a listagem de modelos do SDK (client.models.list()): no OpenRouter, isso atinge a API de Modelos do OpenRouter, cujo formato de resposta o SDK rejeita.
• IDs de modelo: jev-1.14 (atual), jev-1.13, ou jev-latest; IDs simples mapeiam para typesafe/jev-… e ~typesafe/jev-latest. Fixe uma versão para limites reproduzíveis. Verifique os modelos TypeSafe no OpenRouter para versões atuais, preços e comprimento de contexto; o campo model da resposta nomeia a versão exata que atendeu a requisição.
• Box (localizar um alvo descrito em uma imagem no state) precisa de jev-1.14 ou superior; a versão 1.13 o rejeita com um erro 400. Box sempre retorna bordas, portanto combine-o com um Noul quando o alvo pode estar ausente.
• Superfície alternativa: a própria API Decisions do OpenRouter (POST https://openrouter.ai/api/alpha/decisions) e seus SDKs TypeScript, Python e Go. Prefira-a apenas quando o projeto já utiliza o SDK do OpenRouter.
• Não é a API tipada do Jev: typesafe/jev-router é um roteador de chat-completions que usa o Jev para escolher outro LLM. Ele retorna texto gerado, não respostas tipadas, portanto não se encaixa nos padrões desta skill.
• Sessões em nuvem e em sandbox: a lista de permissões de rede deve incluir openrouter.ai; armazene a chave como um segredo, não como uma variável de ambiente simples.

Documentação do OpenRouter: Jev no OpenRouter, SDK TypeSafe no OpenRouter, Tutorial Jev e o índice de documentação (pesquise por "Jev" para encontrar os cookbooks). Quando a documentação do OpenRouter e da TypeSafe discordarem sobre acesso, endpoints, IDs de modelo ou preços, a documentação do OpenRouter prevalece para esta configuração.

Leia a documentação atualizada

A documentação ao vivo da TypeSafe é a fonte da verdade. Leia-a como parte da tarefa. Esta skill fornece direção; os documentos trazem conceitos atuais, orientação de prompts, contratos de API, uso do SDK, modelos, limites e exemplos práticos.

• Comece com o índice de documentação para descobrir páginas relevantes e cookbooks. Use leituras direcionadas em vez de carregar o site inteiro.
• O Mintlify serve Markdown anexando .md ao caminho de uma página, por exemplo como construir com TypeSafe. Siga os links do índice; converta links de páginas de documentação sem extensão para .md quando útil. Resolva links relativos com base em https://docs.typesafe.ai.
• Antes de escrever uma integração, leia a página atual da API ou do SDK escolhido e a orientação de perguntas relevante ao design. Para um novo fluxo de trabalho, inspecione também o cookbook mais próximo: ele frequentemente mostra uma decomposição melhor do que um classificador genérico.
• Se o índice estiver indisponível, use os links diretos abaixo ou a navegação do site. Se a obtenção de Markdown falhar, tente a página normal. Se o acesso ao vivo estiver indisponível, use a documentação local disponível ou os tipos do SDK instalado, declare essa limitação e evite inventar detalhes dependentes de versão.

Tarefa	Comece aqui; siga os detalhes relevantes
Entender o modelo de programação	System One, guia de construção
Explorar o que construir	Mapa de casos de uso, depois cookbooks relevantes do índice
Preparar entradas e perguntas	Estado, primitivas, depois a página da primitiva escolhida
Decidir como lidar com incerteza	Confiança
Escrever código de API	SDK TypeSafe no OpenRouter primeiro, depois API HTTP, Python SDK ou JavaScript SDK para formatos de requisição, com URL base e chave do OpenRouter
Encontrar cookbooks do OpenRouter	Gating de chamadas de ferramenta, cascata verificada, classificação em escala, aprovação automática de prompts de permissão
Atualizar uma integração antiga	Guia de migração e a referência atual do SDK instalado

Encontre a forma útil

Comece pelo comportamento que o usuário deseja: o que a aplicação mostrará, selecionará, alterará ou transferirá? Trabalhe de trás para frente até os julgamentos necessários. Mantenha regras conhecidas, cálculos, buscas exatas e execução no código. Preserve a pilha e o escopo escolhidos pelo usuário; adicione TypeSafe onde a compreensão semântica ajuda.

Ao fazer brainstorming ou escolher uma arquitetura, considere mais do que classificação. Os padrões abaixo são pontos de partida: combine primitivas em torno do objetivo do usuário, incluindo ideias que não se encaixam em uma receita estabelecida.

• Roteie e preencha argumentos conhecidos. Uma requisição pode selecionar um manipulador e seus parâmetros tipados. Faça perguntas úteis específicas do ramo antecipadamente e consuma apenas as respostas relevantes. Explore chamada de função e fan-out especulativo.
• Selecione em vez de gerar. Encontre valores candidatos ou intervalos de origem no código, use um julgamento para selecionar o pretendido, depois copie ou normalize-o. O código também pode montar texto de origem em um documento formatado ou guia de leitura. Explore extração de valor e recuperação de estrutura.
• Encontre e julgue evidências. Recupere candidatos, compare sua relevância a uma consulta e selecione contexto útil. Explore reordenação e classificação hierárquica.
• Transforme julgamentos em dados reutilizáveis. Pontue dimensões uma vez, depois deixe que o código ou controles do usuário alterem pesos, limites, classificações e visualizações. Com resultados rotulados, esses sinais podem se tornar características de ML clássico. Explore pontuação composta e descoberta de características.
• Verifique e escale. Verifique alegações ou campos específicos contra suas evidências; envie casos incertos ou com falha para uma pessoa ou modelo de raciocínio. Explore verificações de citação e cascatas de extração.
• Responda a estados mutáveis. O código pode reter metas e observações enquanto julgamentos recentes guiam o próximo passo delimitado. Mantenha o estado inferido distinto dos fatos observados e verifique a atualidade antes de aplicar um resultado a uma situação alterada.

Para requisições abertas, ofereça as poucas direções que melhor atendam ao objetivo do usuário e recomende um ponto de partida. Para uma requisição concreta, escolha o padrão relevante e construa; um brainstorming não é um desvio obrigatório.

Projete os julgamentos

Escolha pelo que a resposta significa, depois leia a página da primitiva relevante:

Necessidade	Primitiva	Distinção importante
Um de um conjunto definido	Choice	Escolhe uma opção; sua distribuição compara opções concorrentes
Se uma condição é verdadeira	Noul	Probabilidade de sim; sem confiança separada; use um por rótulo quando vários podem se aplicar
Grau ao longo de uma dimensão descrita	Score	Posição ponderada por probabilidade em níveis ordenados; use Scores comparáveis por item para ranqueamento graduado
Onde um alvo descrito está em uma imagem	Box	Apenas Jev 1.14+; sem critérios; sempre retorna bordas, então pergunte a um Noul pela presença

Forneça a cada pergunta estado relevante suficiente para responder: texto fonte, identidades, relacionamentos, políticas e fatos atuais. Prefira campos JSON nomeados quando o contexto tiver várias partes. Coloque o julgamento em instruções e defina suas respostas possíveis em critérios. IDs de pergunta são para código e não são enviados ao modelo; inclua significado completo na pergunta. Referencie estado aninhado com caminhos entre crases, como ticket.messages[0].text.

Faça uma pergunta estreita e coerente por julgamento. Separe dimensões independentemente úteis, sem destruir o relacionamento sendo julgado. Uma seleção de ação delimitada ou interpretação contextual é válida; atômico não significa extração literal de fatos ou limite de uma frase. Strings funcionam para perguntas simples. Use objetos estruturados ou arrays quando definições, contrastes, exclusões ou exemplos esclarecerem instruções ou critérios. Os níveis de Score devem descrever situações concretas e ser autossuficientes.

Mantenha as respostas necessárias disponíveis. Inclua um resultado de não correspondência quando nada pode se encaixar; use um julgamento de presença separado quando for independentemente útil. Para seleção de valor de origem, verifique a cobertura dos candidatos: o modelo não pode escolher um valor omitido.

Componha e verifique

Faça perguntas independentes sobre o mesmo estado juntas, incluindo perguntas especulativas úteis. Elas são executadas em paralelo e não podem ver as respostas umas das outras. Enuncie cada premissa especulativa explicitamente; o código consome as respostas aplicáveis. Uma segunda requisição é justificada quando uma resposta anterior é necessária para buscar evidências, construir novo estado ou determinar as próximas opções. Perguntas extras ainda usam tokens; meça os orçamentos reais de requisição, custo e latência de ponta a ponta.

Use probabilidades e confiança para guiar o comportamento, com limites avaliados nos dados e consequências do usuário. A confiança de Choice/Score resume a concentração da distribuição, não a correção geral do fluxo de trabalho ou permissão para agir. Um Noul próximo de 0.5 significa probabilidade similar para sim e não, não intensidade média. Várias alternativas aceitáveis também podem espalhar a probabilidade; confiança baixa não precisa invalidar uma escolha de preferência inofensiva. Ignore incerteza em ramos não utilizados.

Mantenha a política explícita e os julgamentos brutos reutilizáveis. Pontuações ponderadas são adequadas para preferências compensatórias; uma regra de "qualquer violação grave" precisa de condições separadas. Alterar um peso ou filtro de exibição não precisa reexecutar inferência quando evidências e significados da pergunta não mudaram. A saída tipada garante a interface, não a verdade. Modelos System One são treinados para decisões calibradas; valide seu desempenho no domínio alvo.

Teste casos representativos e o comportamento resultante da aplicação. Para falhas, inspecione o estado exato, perguntas, candidatos, respostas, composição e resultado observado. Separe evidências ausentes, erros de modelo, erros de código e falhas de serviço. Trate limites de cookbooks e resultados de demonstração como exemplos a serem avaliados, não regras universais ou limitações permanentes do modelo. Mantenha credenciais de API no lado do servidor em aplicações web.