Resolver problemas de autoria

Esta página é para quem cria: escrevendo componentes de conhecimento, ou construindo e publicando um caso. Se nenhum comando /fito- aparece, comece por Resolver problemas de instalação.

As paradas de autoria em geral são deliberadas. Os comandos recusam em vez de adivinhar, e a maior parte das recusas nomeia a correção. Esta página junta as que aparecem em vários comandos.

Antes de começar

Duas coisas são verdade em uma sessão de autoria que funciona, e muitos sintomas daqui são uma delas sendo falsa:

• A tecnologia e a linha principal que você nomeia já existem no Fito.
• Você está logado, para os três comandos que gravam — /fito-create-or-update-technology, /fito-push-knowledge e /fito-publish-case.

O vocabulário não tem o que você precisa

A mesma lacuna aparece em quatro comandos com quatro mensagens diferentes.

Onde	O que você vê	O que significa
/fito-identify-	The Fito vocabulary holds no <slug> technology…	O slug não existe
/fito-push-knowledge	No technology found for "<slug>".	O slug não existe
/fito-push-knowledge	"<name>" (<file>) was not stored: technology "<slug>" has no version "<v>"	A tecnologia existe; a linha principal não
/fito-case-design	“The Fito vocabulary doesn’t hold these declared technologies yet”	Um slug não existe, ou a linha principal que você nomeou não existe
/fito-case-design	“These components don’t exist in the Knowledge Repository yet”	Ninguém escreveu o conhecimento de que o caso precisa

Um slug escrito errado não é motivo para provisionar

Provisionar o erro de escrita cria uma segunda tecnologia independente ao lado da verdadeira, e componentes enviados contra as duas aterrissam em linhas diferentes. Confira a grafia antes de recorrer a Provisionar uma tecnologia.

Mais duas coisas que essa mensagem não significa:

• Um servidor fora do ar não é uma tecnologia faltando. Quando uma consulta falha por qualquer razão que não seja não-encontrado, o comando reporta a falha como ela chegou e para, sem o conselho de provisionar primeiro.
• Não encolha um caso para caber no que existe. Largar um componente de que o caso genuinamente precisa faz um caso pior. O que deve crescer é o vocabulário.

Uma verificação antes de rodar o pipeline inteiro: se todos os candidatos de uma tecnologia voltaram faltando, desconfie da linha principal, e não do vocabulário.

Uma quase duplicata para a execução

Gravar uma tecnologia ou um componente compara o que você tem com o que o Fito já guarda. Uma coincidência para a execução sem gravar nada, e lista toda coincidência com a camada que a encontrou — dedup-key para uma colisão determinística, trigram para uma difusa.

Near-duplicate technologies found (409): <message>

  <slug> — "<name>" (<layer>)

A escolha é sua, e o comando nunca a faz por você:

Escolha	Quando	O que acontece
Reaproveitar	A coincidência é a sua coisa	Rode de novo declarando o slug encontrado. A execução vira uma atualização. A resposta preferida
Redeclarar	A coincidência só se parece com a sua	Rode de novo com um slug diferente
Sobrepor	A coincidência é alarme falso	Uma linha nova e independente é criada ao lado de cada coincidência

Sobrepor não é atalho para passar por uma duplicata real: componentes enviados contra dois slugs aterrissam em duas tecnologias diferentes e nunca se encontram. O relato completo está em Provisionar uma tecnologia.

Nada foi ingerido

No source found at <docs-path>. significa que o pipeline não teve o que ler.

1. Prefira a árvore de código do próprio caso: passe --source <path>.
2. Senão, busque documentação primeiro — --fetch com --urls <file>, ou o /fito-fetch-urls-content sozinho.
3. Ou aponte --docs para uma pasta que uma busca anterior já encheu.

As duas fontes de ingestão não são iguais, e qual escolher está em Ingerir uma árvore de código-fonte.

Um componente gerado não é enviado

Nunca edite um arquivo de componente para fazê-lo passar. Os arquivos gerados são entradas somente de leitura do envio. Quando um está errado, gere de novo e envie o arquivo novo.

Um arquivo que falha é registrado e o envio segue para o próximo. Um arquivo ruim nunca para a execução inteira. A tabela de mensagens está em Gerar e publicar componentes.

O validador estrutural reprova

O validador reporta todas as violações de uma vez, cada uma vinculada ao arquivo .case/ que a produziu e em geral a um caminho de campo dentro dele.

Leia o path além da message. Sozinha, uma mensagem pode dizer Invalid input: expected string, received undefined, que não nomeia campo algum.

Corrija os arquivos nomeados e rode de novo. Não gere a árvore de novo por causa de um erro que você consegue corrigir. Campo a campo, o contrato está em O contrato de arquivos .case/; ler a saída está em Validar a pasta .case/.

Uma publicação para

Todas estas são seguras de repetir. O repositório nunca é duplicado, e um rascunho registrado é reaproveitado em vez de criado de novo.

O que você vê	O que fazer
“The working tree has uncommitted changes”	Commite ou guarde, e rode de novo
“The local solution branch … does not exist”	Construa o branch exemplar, e rode de novo
“Your local gh account … is not your Fito account’s linked GitHub identity”	Rode de novo com --accept-gh-mismatch se for intencional. A confirmação é sua para dar
“… is already a published Fito case”	Isto é uma atualização, não uma primeira publicação
“The .case/ tree fails structural validation”	Corrija os arquivos nomeados e rode de novo
Uma rejeição do servidor com um status HTTP	Em geral uma referência que não resolve, ou um ping de alcance que falhou

Um ping de alcance que falha significa que os refs não chegaram. O servidor verifica a tag da versão e o branch da solução, então confira os dois no GitHub antes de repetir. As duas tabelas por inteiro estão em Publicar um caso.

Uma versão nova não publica

Publicar uma segunda versão tem paradas próprias, e a que surpreende quem cria é o conjunto de referências congelado:

O que você vê	O que significa
“The knowledge-reference set is frozen across versions, and this tree changes it”	Esta edição pertence ao outro caminho — um caso sucessor, não uma versão nova
“.case/manifest.yaml is stale for the new version”	O submission.target_branch ainda nomeia a versão antiga
“.case/solution.yaml is stale for the new version”	O branch: ainda nomeia a versão antiga
“manifest.version is still …”	A versão não mudou, ou andou para trás

A parada por referência congelada itemiza exatamente o que foi acrescentado e o que foi retirado. Leia essa lista antes de decidir — é a diferença entre um erro de digitação e uma mudança real de escopo. Veja Corrigir ou aposentar um caso publicado.

Se nada disso resolveu

Junte isto antes de pedir ajuda:

• O comando exato, com todas as flags.
• A primeira linha do erro, literal, com qualquer status HTTP.
• O slug da tecnologia e a linha principal que você nomeou.
• Se você está logado, e se a árvore de trabalho está limpa.

O que vem depois

• Resolver problemas de instalação — quando o problema é a sessão ou os comandos.
• Resolver problemas ao trabalhar um caso — quando você está trabalhando um caso em vez de escrever um.