Resolver problemas de instalação

Tudo nesta página acontece antes de você fazer qualquer trabalho no Fito: a sessão não inicia, os comandos não estão lá, um pacote é antigo demais, ou a entrada não termina. Problemas que aparecem enquanto você trabalha um caso ou cria conteúdo têm páginas próprias, ligadas no fim.

Antes de começar

Uma instalação saudável é assim, e cada parte tem a sua própria seção nesta página:

• Exatamente uma instalação do Fito, pelo npm. O pi list mostra npm:fito-tui, e nenhum clone do repositório do Fito.
• O pi-subagents 0.68.0 ou mais novo, para os onze comandos que usam uma persona trabalhadora.
• Um pacote do Fito que o servidor do Fito ainda aceita.

Nenhum comando /fito- aparece

Digite /fito- na sessão. Se a lista de autocompletar não oferecer nada, o Fito não está carregado.

1. Saia da sessão.

2. Verifique se a instalação foi registrada:

   pi list

   Se a lista não mostrar npm:fito-tui, instale o Fito, como em Instalação e pré-requisitos.

3. Se a lista o mostrar, rode pi config e ligue de novo os recursos do Fito. O pi config desliga um pacote sem removê-lo.

4. Inicie o pi de novo e digite /fito- uma segunda vez.

Confirme que funcionou: a lista oferece /fito-login.

O pi se recusa a iniciar: Tool "fito_knowledge_fetch" conflicts with …

A sessão não inicia de jeito nenhum, e o erro nomeia dois caminhos absolutos e nenhuma solução.

O pi carrega o Fito duas vezes. A causa de sempre é uma instalação por clone do Fito ao lado da instalação pelo npm, porque versões anteriores da página de instalação instalavam o Fito a partir de um clone. O pi trata um registro duplicado de ferramenta como erro fatal de carga de extensão, e o levanta antes de verificar as suas credenciais. A sessão morre em vez de iniciar degradada.

Um dos dois caminhos do erro fica no seu clone do repositório do Fito. Essa é a instalação a remover. Os passos estão em Sair de uma instalação por clone.

Unknown tool: subagent, ou o /run não é reconhecido

O pi-subagents não está instalado. Onze comandos do Fito entregam o seu trabalho a uma persona trabalhadora e chegam a ela por esse pacote — o tutor e a pontuação da rubrica entre eles.

pi install npm:pi-subagents

Depois reinicie o pi.

A mesma causa tem um sintoma mais silencioso: as personas trabalhadoras do Fito são declaradas para o pi-subagents no manifesto do pacote, então sem esse pacote nada as carrega. A sessão avisa no início.

Fito needs pi-subagents 0.68.0 or newer

O seu pi-subagents é mais antigo que a versão de que as personas trabalhadoras do Fito precisam. O Fito confere isso quando o pi inicia, e mostra:

Fito needs pi-subagents 0.68.0 or newer. Run: `pi update --extensions`

Para atualizá-lo, rode isto no seu shell e depois inicie o pi de novo:

pi update --extensions

Confirme que funcionou: a mensagem não aparece quando o pi inicia.

Your Fito TUI … is too old

O servidor do Fito só aceita um pacote do Fito a partir de uma versão mínima. O Fito pergunta ao servidor quando o pi inicia, e o servidor também recusa cada comando que um pacote mais antigo envia. A mensagem nomeia a sua versão e a mínima do servidor, por exemplo:

Your Fito TUI 0.2.1 is too old. The minimum is 0.3.0. Update it with: `pi update --extensions`

Para atualizar, rode isto no seu shell e depois inicie o pi de novo:

pi update --extensions

Se a mensagem voltar, o Fito provavelmente é uma instalação por clone, que o pi update pula. Saia dela, como em Sair de uma instalação por clone.

A página de login abre no Fito errado

O /fito-login abre um navegador no endereço de FITO_URL. Quando essa variável não está definida, ele abre o Fito hospedado, em https://fito.codes. Então a página de login abre no Fito errado quando FITO_URL nomeia outro Fito, ou quando ela não está definida e você queria um local.

Confira no shell de onde você inicia o pi:

echo "$FITO_URL"

Defina-a com o Fito que você quer, ou remova-a para usar o Fito hospedado, e depois inicie o pi de novo. A lista completa está em Configuração da TUI.

A entrada nunca se completa

O /fito-login espera cinco minutos pelo navegador devolver os tokens, e então desiste. Um tempo esgotado não quebra nada — rode de novo.

O que você vê	O que fazer
O navegador não abre	O terminal imprime a URL. Abra você mesmo
Você entrou e o terminal continua esperando	Volte para a aba; ela avisa quando a troca termina
Esgotou o tempo	Rode /fito-login de novo

Confirme que a entrada funcionou:

✓ Logged in. Credentials saved to ~/.fito/credentials (mode 0600).

Se um comando posterior ainda pedir para você entrar, o arquivo de credenciais pode estar escrito pela metade — um arquivo malformado é lido como não logado, e não como erro. Rode /fito-login de novo para reescrevê-lo.

Se nada disso resolveu

Junte isto antes de pedir ajuda. Em conjunto, identifica toda causa desta página:

• A saída de pi list.
• A pasta em que você iniciou a sessão do pi.
• A primeira linha exata do erro, com quaisquer caminhos que ela nomeie.
• Se FITO_URL está definida, e com que valor.

O que vem depois

• Resolver problemas ao trabalhar um caso — abrir, o tutor, avaliar e enviar.
• Resolver problemas de autoria — o pipeline de conhecimento e a autoria de casos.