Gerar e publicar componentes

Gerar escreve cada candidato novo como um componente de conhecimento (knowledge component) completo, em um arquivo no seu disco. O push publica esses arquivos no Fito, um por vez. Os dois dividem uma página porque um componente gerado é só um arquivo até você publicá-lo — e, depois de publicado, ele não pode ser editado.

Esta página supõe que a identificação já rodou e deixou uma lista de candidatos. Se não rodou, comece em Identificar componentes de conhecimento. Ela não cobre a criação de um caso — isso começa em Crie seu primeiro caso, depois que os componentes de que o caso precisa estiverem publicados.

Antes de começar

• Uma sessão do pi em um diretório de trabalho seu, com o Fito instalado nele. Veja Preparar um diretório de trabalho.
• Um provedor de LLM configurado no pi, e o pacote pi-subagents instalado. A geração roda em uma persona trabalhadora, no seu próprio modelo.
• Uma lista de candidatos da identificação, no mesmo diretório de trabalho.
• Para o push, um login no Fito pelo terminal — rode o /fito-login se ainda não rodou. Gerar não exige login.

Gerar os componentes

Um comando por tipo de componente. Cada um lê a lista que o comando de identificação correspondente escreveu, e escreve um arquivo por componente:

Comando	Lê por padrão	Escreve por padrão
/fito-generate-domain-concepts	./output/2-identify/domain_concepts/domain_concepts.json	./output/3-generate/concept_content/
/fito-generate-execution-facts	./output/2-identify/execution_facts/execution_facts.json	./output/3-generate/execution_fact_content/
/fito-generate-usage-scenarios	./output/2-identify/usage_scenarios/usage_scenarios.json	./output/3-generate/usage_scenario_content/

1. Rode o comando com o mesmo nome, a mesma tecnologia e a mesma linha principal que você passou para a identificação:

   /fito-generate-domain-concepts Javalin --technology javalin --technology-version 7

   Por padrão, ele escreve todo candidato novo da lista. Para escrever só alguns, acrescente --mode batch --select com os que você quer — veja Flags da geração.

2. Leia o resumo que ele repassa. Ele nomeia cada componente que escreveu, e cada candidato que pulou porque aquele componente já existe no Fito.

3. Repita para os outros dois tipos, se você os identificou.

Confirme que deu certo: a pasta de saída tem um arquivo .json por candidato novo.

Flags da geração

Flag	Obrigatória	Padrão	O que faz
<tool-name>	Sim	—	O nome do assunto, como primeiro argumento
--technology <slug>	Não	O nome, em minúsculas, com espaços trocados por hifens	A tecnologia a que os componentes pertencem
--technology-version <slug>[,<slug>...]	Sim	—	As linhas principais a que os componentes se aplicam. Separe com vírgulas — 6,7 — para componentes que valem em mais de uma
--version <ver>	Não	Nenhum	A versão da ferramenta a mirar, para que exemplos, nomes de API e terminologia batam com ela
--concepts, --facts ou --scenarios <path>	Não	A lista da tabela acima	A lista de candidatos a ler — o nome da flag acompanha o comando
--output <path>	Não	A pasta da tabela acima	Onde os arquivos de componente vão parar
--mode one|batch|all	Não	all	Quantos candidatos escrever
--select <items>	Com one ou batch	—	Quais candidatos, separados por vírgula
--audience beginner|intermediate|advanced	Não	intermediate	O leitor para quem o texto é escrito
--language <lang>	Não	English	O idioma de toda frase gerada
--identify	Não	—	Roda antes o comando de identificação correspondente. As quatro flags abaixo só chegam à identificação por meio dela
--source <path>	Não	—	Monta o bundle dessa árvore de código-fonte e o lê. Vence o --fetch
--fetch	Não	—	Roda o /fito-fetch-urls-content antes
--urls <file>	Não	urls.txt	A lista de URLs do --fetch
--docs <path>	Não	./output/1-ingest/extracted_links_content/	Uma pasta já ingerida para ler

--version não é linha principal nem revisão

O --technology-version nomeia as linhas principais (major lines) a que um componente se aplica, e é o que o Fito registra. O --version só diz a quem escreve de qual versão ser fiel — 7.1.4, por exemplo — e o Fito nunca o guarda. A revisão (revision) própria de um componente é outra coisa ainda, definida na hora do push. Quando você deixa o --version de fora, os comandos de execution facts e de usage scenarios deduzem uma versão da lista de candidatos; o de concepts escreve sem nenhuma.

O --select aceita ids de candidato, intervalos e nomes, misturados à vontade:

--select "1-3, 10, Bean"

Um intervalo são dois inteiros, com as duas pontas incluídas. Os nomes mudam por comando: o nome de um concept, um trecho do enunciado de um execution fact, ou um trecho do título de um usage scenario. Execution facts têm ids como EF-010.

Qual gerador roda

O tipo (kind) da tecnologia escolhe quem escreve, como escolheu o identificador. Ele também escolhe o template contra o qual o componente é escrito, que o comando lê do Fito — então um concept sobre uma ferramenta e um concept sobre uma prática pedem campos diferentes. Usage scenarios são a exceção: os dois tipos de tecnologia dividem um template só.

Todo valor de campo é um fragmento de markdown. O conteúdo do componente é um conjunto de campos, e cada campo guarda o próprio pedacinho de markdown.

O que é um arquivo de componente

Cada arquivo se chama <id>-<slug>.json — 1-dependency-injection.json, por exemplo —, em que o número é o id do candidato na lista. Esse nome serve só para o seu disco. O Fito cria o id de referência do componente na hora do push, a partir do nome do componente.

Usar o --identify

O --identify roda o comando de identificação correspondente antes de gerar. Toda flag de ingestão que você passar vai junto, então as regras de entrada são as da própria identificação — veja De onde vem a entrada.

/fito-generate-domain-concepts Javalin --technology javalin --technology-version 7 --identify --source ~/code/my-javalin-app

Sem nenhuma flag de ingestão, a identificação lê a pasta da documentação buscada. Dentro de um checkout de caso que é seu para autorar, ela oferece ler o próprio checkout.

O --concepts e o --identify escrevem e leem pastas diferentes

O --identify sempre escreve a lista de candidatos na pasta da tabela acima. O --concepts — e o --facts, e o --scenarios — manda a geração ler em outro lugar. Junte os dois e a geração ignora a lista que acabou de fazer: ou para com No domain concepts found, ou, se uma lista antiga estiver naquele caminho, escreve componentes a partir dela sem avisar. Use um ou outro.

Quando a geração para

Mensagem	O que significa	O que fazer
Please provide the Fito technology version(s) the components apply to with --technology-version <slug> …	Falta a linha principal	Acrescente --technology-version. O push recusa um componente sem linha principal
The Fito vocabulary holds no <slug> technology, so there is nothing to attach these components to. …	O slug não existe no Fito	Provisione a tecnologia, ou corrija um --technology digitado errado
No domain concepts found at <concepts-path>. …	Não há lista de candidatos nesse caminho — os outros dois comandos nomeiam o próprio tipo	Rode a identificação antes, ou passe --identify
Please specify which concepts to process with --select. …	--mode one ou batch sem --select	Acrescente --select
Content template not found. The Fito package installation may be incomplete.	Falta um arquivo no pacote do Fito da sua máquina	Reinstale o pacote

Como na identificação, uma falha do servidor que não seja não-encontrado é relatada como veio, e o comando para sem mandar você provisionar nada.

Publicar os componentes

1. Rode o push sem argumento, para publicar tudo o que a geração escreveu:

   /fito-push-knowledge

   Ou diga o que publicar — um arquivo de componente, ou uma pasta deles:

   /fito-push-knowledge ./output/3-generate/concept_content/

   Sem argumento, ele reúne todo arquivo .json que está diretamente dentro de ./output/3-generate/concept_content/, execution_fact_content/ e usage_scenario_content/. Ele não olha dentro de subpastas.

2. Confira a lista que ele mostra. O push nomeia cada arquivo e a contagem antes de guardar qualquer coisa.

3. Responda a cada parada. O push trata um arquivo por vez, e um arquivo que lembra algo que já está no Fito para esperando a sua escolha — veja Resolver um componente parecido ou duplicado.

4. Leia o relatório no fim. Ele tem três listas, e cada item nomeia o componente e o arquivo dele: Stored (guardados), com cada id de referência e a contagem total; Skipped by you (pulados por você); e Not stored because of an error (não guardados por causa de um erro), cada um com o motivo.

Cada componente guardado imprime uma linha, com o componente, o novo id de referência, a revisão e o arquivo de origem:

✓ Stored "<name>" as <reference-id> (revision <revision>), from <component-file>

Confirme que deu certo: abra o componente no aplicativo web em /knowledge/<type>/<technology-slug>.<component-slug>. Para concept:javalin.handler, isso é /knowledge/concept/javalin.handler.

Resolver um componente parecido ou duplicado

Duas verificações rodam em todo push simples, e qualquer uma pode parar um arquivo antes que algo seja guardado. As duas comparam o seu componente só com componentes da mesma tecnologia que dividem uma linha principal com ele.

Componentes parecidos vêm primeiro. O Fito procura componentes existentes próximos do novo — incluindo os reescritos o bastante para passar por baixo da barra de duplicata. O push nomeia o seu componente e o arquivo dele, lista cada correspondência por quão parecida ela é, pelo nome e pelo id de referência, e pergunta o que fazer:

"Observer Pattern" (./3-observer-pattern.json) was not stored.
Fito already has components that are similar to it:

   99% similar  "Observer"              concept:design-patterns.observer
   90% similar  "Observer Participant"  concept:design-patterns.observer-participant

What do you want to do?
  Link                  Store it as an alternative definition of "Observer".
  Supersede             Store it as the next revision of "Observer" (now revision 1.0.0).
  Skip                  Store nothing for this file.
  Create new component  Store it as a separate component, next to the similar ones.
                        If it is almost the same as one of them, Fito asks you again.

Uma duplicata vem em segundo. Um componente quase igual a um que já está no Fito é recusado, e o push nomeia a duplicata e faz a mesma pergunta.

Nos dois casos, a escolha é sua, e o push nunca escolhe por você:

Escolha	O que é guardado
Link	Um componente novo, com o próprio id de referência, ligado como definição alternativa (alternative definition) da correspondência mais próxima
Supersede	Um componente novo que é a próxima revisão da correspondência mais próxima
Skip	Nada. O arquivo é registrado como pulado
Create new component	Um componente independente, que convive com as correspondências

Link e supersede são as respostas preferidas. As duas miram a correspondência mais próxima.

Create new component deixa dois componentes descrevendo quase a mesma coisa. A descrição da escolha já diz isso, então escolhê-la é a sua confirmação. Depois da parada de componentes parecidos, o Fito ainda pode recusá-lo como duplicata, e aí o push pergunta de novo.

Três coisas sobre o supersede passam despercebidas com facilidade:

• A revisão precisa de um rótulo mais novo. O push pede um, mostra a revisão atual e sugere a próxima — 2.0.0 depois de 1.0.0. Ele recusa um rótulo que não está na forma X.Y.Z, ou que não é mais novo que a revisão atual. Quando a revisão atual não está nessa forma, qualquer rótulo X.Y.Z é aceito.
• O id de referência pode mudar. O id da nova revisão é criado a partir do próprio nome dela, então uma revisão renomeada ganha um id novo. O histórico de versões liga os dois.
• As linhas principais são herdadas. Uma nova revisão se aplica exatamente às linhas da anterior, diga o arquivo o que disser.

O supersede só funciona na revisão mais nova de uma cadeia. Mire em uma mais antiga e o push nomeia a mais nova, e pergunta se você quer suceder essa.

Publicar o mesmo arquivo duas vezes

Se um push foi interrompido e você o roda de novo, um arquivo já publicado para no componente que ele mesmo criou, 100% parecido. A sessão acrescenta uma linha abaixo da mensagem dizendo isso. Skip é a resposta certa: ele já está no Fito.

Para cada escolha, a sessão roda o script de push de novo com uma flag — --link '<reference-id>'; --supersede '<reference-id>', e depois --version <label> quando você dá o rótulo; ou, para Create new component, --proceed depois da parada de componentes parecidos e --override '<reference-id>' depois da de duplicata. Você escolhe; ela digita.

Quando um push falha

Um arquivo que falha é registrado, e o push passa para o próximo. Um arquivo ruim nunca interrompe a execução.

Nunca edite um arquivo de componente para ele passar. Os arquivos são entradas somente leitura do push. Quando um estiver errado, gere-o de novo com o comando de geração e publique o arquivo novo.

Mensagem	O que significa	O que fazer
You are not logged in to Fito. Run /fito-login first, then re-run this flow.	Não há sessão	Rode /fito-login e publique de novo
No generated component files found in <path>. …	Nada para publicar	Gere antes, ou indique a pasta
No technology found for "<slug>".	O arquivo nomeia uma tecnologia que o Fito não tem	Provisione a tecnologia e publique de novo
"<name>" (<file>) was not stored: technology "<slug>" has no version "<v>"	O arquivo nomeia uma linha principal que a tecnologia não tem	Gere de novo com o --technology-version certo
"<name>" (<file>) was not stored: Invalid component content: …	O conteúdo quebra o template; cada campo com problema é nomeado	Gere o componente de novo
<file> is not valid JSON. ou <file> is not a generated component file. Generate it again.	O arquivo está corrompido, ou não é um arquivo de componente	Gere de novo
No registered template for component type …	O servidor do Fito não tem templates carregados	Um problema do servidor — avise quem administra o seu servidor Fito

O que vem a seguir

• Crie seu primeiro caso — ponha em uso os componentes que você publicou.
• Navegar pela área de conhecimento — leia o que você publicou, do jeito que quem aprende vai ler.
• Criar uma competência — agrupe os componentes que você publicou numa capacidade que uma tecnologia exige.