O que Concept Forge faz?
O Concept Forge transforma uma pergunta dispersa do usuário em um ativo de conhecimento durável: uma resposta concisa, um cartão de conhecimento estruturado, um rascunho de leitura Quarkdown, um rascunho de apresentação Slidev e um explicador HTML interativo autocontido.
O objetivo não é produzir uma resposta descartável. O objetivo é tornar o conceito mais fácil de lembrar e cultivar uma biblioteca local de conhecimento/HTML reutilizável ao longo do tempo.
Fluxo Principal
Sempre siga esta ordem:
- Normalize a pergunta: identifique o conceito central, aliases, alvos de comparação e a intenção do usuário.
- Consulte as entradas existentes primeiro com
scripts/concept_forge.py lookup. - Planeje a profundidade com
scripts/concept_forge.py planou o Método de Pesquisa: escolha Rápida, Padrão ou Profunda. - Reutilize antes de reconstruir: se existir uma correspondência forte, retorne a resposta direta existente e o caminho do HTML. Atualize apenas quando o usuário solicitar, a entrada estiver desatualizada ou o conceito for sensível ao tempo.
- Pesquise na profundidade escolhida se nenhuma entrada utilizável existir: use a Lente de Conceito abaixo, navegando quando o tópico pode ter mudado ou a fonte precisa importar.
- Forje o registro do conceito como JSON estruturado usando
references/concept-schema.md. - Renderize e armazene com
scripts/concept_forge.py upsert; isto deve criar artefatos JSON, Quarkdown, Markdown, HTML e Slidev. - Verifique o ramo de entrega com
scripts/concept_forge.py bootstrap "<solicitação original>"se o usuário solicitou leitura formal, PDF, slides, palestra, pré-visualização, construção ou exportação. - Valide a entrada armazenada e os artefatos gerados com
scripts/concept_forge.py validate. - Relate em chinês: sempre dê a resposta primeiro, depois o caminho do HTML local. Evite detalhes de implementação a menos que solicitado.
Formato da Resposta para o Usuário
Toda solicitação concluída deve retornar duas coisas, nesta ordem:
- Resposta direta: 1 a 3 frases curtas em chinês que respondam à pergunta do usuário imediatamente. Prefira uma analogia vívida quando ajudar na memorização. Isso deve ser autossuficiente para usuários que não têm tempo de abrir o HTML.
- HTML interativo: um caminho local ou link para o explicador HTML gerado/reutilizado.
Use um formato compacto como:
Uma frase, Skill é como um pequeno manual preparado para a IA: Prompt é como fazer desta vez, Skill é como fazer sempre que encontrar tarefas semelhantes no futuro.
Página interativa: <caminho/para/html>
Não faça o usuário abrir o HTML para obter a resposta básica.
Espaço de Trabalho
Espaço de trabalho padrão:
<diretório de trabalho atual>/concept-forge-workspace
Se o usuário nomear outro local de armazenamento, use esse. Inicialize antes do primeiro uso:
python <skill>/scripts/concept_forge.py init --workspace <workspace>
O espaço de trabalho contém:
knowledge/index.json
knowledge/concepts/<slug>/concept.json
knowledge/concepts/<slug>/concept.qd
knowledge/concepts/<slug>/concept.md
knowledge/concepts/<slug>/sources.json
html/<slug>.html
slidev/<slug>/slides.md
slidev/<slug>/package.json
quarkdown/
assets/
config.json
Lente de Conceito
Inspire-se no espírito do hv-analysis, mas mantenha-o leve e no tamanho de um conceito.
Para cada conceito novo ou atualizado, responda a estas camadas:
- Memória de uma linha: a definição útil mais curta.
- Resposta direta: uma explicação pronta para chat, geralmente um parágrafo curto, opcionalmente com uma metáfora.
- O que é: explicação em linguagem simples.
- Por que existe: que problema, confusão, fluxo de trabalho ou mudança histórica criou a necessidade dele.
- Como funciona: o mecanismo mínimo necessário para entendê-lo.
- O que não é: equívocos comuns e linhas divisórias.
- Comparação horizontal: conceitos, ferramentas, prompts, fluxos de trabalho ou termos próximos com os quais é frequentemente confundido.
- Mapa relacionado: conceitos pai, conceitos irmãos, conceitos filhos, pré-requisitos e próximas perguntas.
- Exemplo: um cenário cotidiano concreto.
- Gancho de memória: metáfora, frase ou âncora visual que o fixe.
- Mini questionário: 2 a 3 perguntas leves para reforçar a memória.
Use pesquisa na web quando os fatos puderem ser atuais, nicho, controversos, específicos de produtos ou sensíveis à fonte. Prefira documentação oficial e fontes primárias. Se não estiver navegando, marque as fontes como "derivado de modelo / fornecido pelo usuário / contexto local" honestamente no registro.
Modos de Saída
Seleção de Ramo
Existem três ramos de produto. Diferencie-os com precisão.
- Ramo de conceito normal: o usuário pergunta "O que é X", "Qual a diferença entre X e Y", "Ajude-me a entender/lembrar/organizar este conceito" ou dá uma palavra-chave. Gere a resposta direta, fonte Quarkdown, fonte Slidev, HTML e índice. Não pergunte sobre instalação do Quarkdown ou Slidev.
- Ramo de leitura formal: o usuário solicita "leitura formal", "documento longo", "relatório", "PDF", "documento", "impressão", "compilar", "exportar", "entregar" ou nomeia explicitamente o Quarkdown. Execute
bootstrapantes de compilar. Se o Quarkdown estiver faltando, pare antes de compilar/exportar e mostre as instruções de instalação. - Ramo de apresentação formal: o usuário solicita "apresentação", "palestra pública", "material didático", "slides", "PPT", "slides", "deck", "apresentação", "pré-visualização", "construir", "exportar" ou nomeia explicitamente o Slidev. Execute
bootstrapantes de pré-visualizar/construir/exportar. Se o Node/npm ou as dependências do projeto Slidev estiverem faltando, pare antes de pré-visualizar/construir/exportar e mostre as instruções de configuração.
Se o usuário solicitar leitura e apresentação, use o Quarkdown como rascunho mestre e o Slidev como rascunho de palestra derivado, depois verifique ambos os ramos.
Comandos auxiliares de ramo:
python <skill>/scripts/concept_forge.py --workspace <workspace> plan "<solicitação original>"
python <skill>/scripts/concept_forge.py --workspace <workspace> bootstrap "<solicitação original>"
python <skill>/scripts/concept_forge.py --workspace <workspace> bootstrap --intent quarkdown
python <skill>/scripts/concept_forge.py --workspace <workspace> bootstrap --intent slidev
python <skill>/scripts/concept_forge.py --workspace <workspace> bootstrap --intent all
Entrada Existente
Se a consulta encontrar uma entrada existente forte:
- Diga que já existe.
- Dê a resposta curta de
direct_answerse presente, caso contrário, usesummarymaismemory_hook. - Forneça o link para a página HTML local.
- Ofereça o que pode ser atualizado apenas se for útil; não reconstrua por padrão.
Nova Entrada
Para um novo conceito:
- Crie um registro JSON seguindo
references/concept-schema.md. - Inclua pelo menos: título, aliases, profundidade, resposta direta, resumo, o quê, porquê, não, comparações, relacionados, gancho de memória, questionário, fontes.
- Execute:
python <skill>/scripts/concept_forge.py upsert --workspace <workspace> --input <concept.json>
python <skill>/scripts/concept_forge.py validate --workspace <workspace> --slug <slug>
- Retorne primeiro a resposta direta, depois o caminho do HTML gerado. Mencione os caminhos do Quarkdown ou Slidev apenas quando o usuário solicitar arquivos, rascunhos de leitura, palestras, exportações ou depuração.
Atualização
Atualize apenas quando:
- o usuário solicitar atualizar / refazer / expandir;
- a idade da entrada exceder
refresh_policy.days; - o tópico for atual ou de rápida evolução;
- as fontes forem fracas ou estiverem faltando;
- o usuário fizer uma pergunta de acompanhamento mais específica que altere o limite do conceito.
Ao atualizar, preserve os aliases existentes e links relacionados, a menos que estejam claramente errados.
Requisitos de HTML
Use references/html-explainer.md para a forma exata do produto.
A página gerada deve ser autocontida e deve incluir:
- definição de herói;
- seções "o quê / porquê / não";
- cartões de comparação;
- mapa de conceitos relacionados;
- linha do tempo ou faixa de origem quando útil;
- cartões interativos de revelação;
- mini questionário;
- "três coisas para lembrar";
- rodapé de fonte/atualização.
A página deve ser compreensível sem a transcrição do chat.
Quarkdown e Slidev como Cidadãos de Primeira Classe
Quarkdown e Slidev fazem parte da forma do produto.
- Sempre gere
concept.qdcomo o rascunho mestre Quarkdown. É o documento de leitura canônico para a base de conhecimento. - Sempre gere
slidev/<slug>/slides.mdcomo o rascunho da apresentação. Ele é extraído do registro do conceito e do rascunho mestre. - Sempre gere
html/<slug>.htmlcomo a superfície de memória interativa rápida. - Use profundidade dinâmica para decidir quanta pesquisa, fontes e polimento adicionar:
- Rápida: conceito pequeno e estável; gere todos os artefatos de origem, normalmente pule a compilação/exportação.
- Padrão: padrão para ferramentas, métodos, comparações e "o que é X"; gere todos os artefatos e verifique a estrutura.
- Profunda: o usuário solicita pesquisa ou o tópico é atual/complexo; fortaleça fontes, histórico, comparação horizontal e estrutura da palestra.
- Compile o Quarkdown ou construa/exporte o Slidev apenas quando a solicitação entrar em um ramo formal. A geração de origem não deve depender da instalação dos CLIs.
- Use
scripts/concept_forge.py doctorno primeiro uso para uma verificação geral do ambiente. - Use
scripts/concept_forge.py bootstrap "<solicitação original>"antes da compilação/exportação formal para decidir se deve orientar a instalação. - Para leitura formal do Quarkdown, é necessário o
quarkdown. Se estiver faltando no Windows, mostre:irm https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/heads/main/install.ps1 | iexe, em seguida, verifique comquarkdown doctor get install-dir. - Para compilação do Quarkdown, execute
quarkdown c <concept.qd> --strict --out <verify-dir>quando oquarkdownestiver disponível. - Para apresentação formal do Slidev, é necessário Node mais npm ou pnpm. Em
slidev/<slug>, executenpm installoupnpm install, depoisnpm run dev,npm run buildounpm run exportconforme necessário. - Para exportação Slidev PDF/PPTX, instale
playwright-chromiumno projeto de slides gerado primeiro:npm i -D playwright-chromium.
Portão de Qualidade
Antes de relatar a conclusão, verifique:
- a consulta foi tentada antes de criar;
- a resposta final contém tanto uma resposta direta quanto um caminho HTML;
- o conceito tem uma memória de uma linha clara;
- conceitos próximos e equívocos são cobertos;
- o HTML existe e não está vazio;
- o rascunho mestre Quarkdown existe;
- a fonte Slidev existe;
- os ramos formais executaram
bootstrapantes de compilar/exportar; - a falta de ferramentas formais foi relatada antes de tentar compilar/exportar;
- a validação (
validate) passa; - o índice contém título, aliases, slug, resposta direta, resumo, caminho Quarkdown, caminho Slidev e caminho HTML;
- a resposta final é curta, em chinês e voltada para o usuário.
Referências
references/concept-schema.md: formato do registro JSON e Markdown.references/research-method.md: adaptação leve do hv-analysis.references/html-explainer.md: especificação do produto HTML interativo.