Concept Forge
Concept Forge convierte una pregunta dispersa del usuario en un activo de conocimiento duradero: una respuesta concisa, una ficha de conocimiento estructurada, un borrador de lectura en Quarkdown, un borrador de presentación en Slidev y un explicador HTML interactivo autónomo.
El objetivo no es producir una respuesta única. El objetivo es hacer que el concepto sea más fácil de recordar y desarrollar una biblioteca local de conocimiento/HTML reutilizable a lo largo del tiempo.
Ciclo Principal
Siga siempre este orden:
- Normalizar la pregunta: identifique el concepto central, los alias, los objetivos de comparación y la intención del usuario.
- Consultar primero las entradas existentes con
scripts/concept_forge.py lookup. - Planificar la profundidad con
scripts/concept_forge.py plano el Método de Investigación: elija Rápida, Estándar o Profunda. - Reutilizar antes de reconstruir: si existe una coincidencia sólida, devuelva la respuesta directa existente y la ruta HTML. Refresque solo cuando el usuario lo solicite, la entrada esté desactualizada o el concepto sea sensible al tiempo.
- Investigar a la profundidad elegida si no hay una entrada utilizable: use el Lente de Concepto a continuación, navegando cuando el tema pueda haber cambiado o la fuente precisa sea importante.
- Forjar el registro del concepto como JSON estructurado usando
references/concept-schema.md. - Renderizar y almacenar con
scripts/concept_forge.py upsert; esto debe crear artefactos JSON, Quarkdown, Markdown, HTML y fuente de Slidev. - Verificar la rama de entrega con
scripts/concept_forge.py bootstrap "<solicitud original>"si el usuario solicitó lectura formal, PDF, diapositivas, charla, vista previa, compilación o exportación. - Validar la entrada almacenada y los artefactos generados con
scripts/concept_forge.py validate. - Informar en chino: primero dé la respuesta, luego la ruta HTML local. Evite los detalles de implementación a menos que se le pregunte.
Forma de la Respuesta para el Usuario
Cada solicitud completada debe devolver dos cosas, en este orden:
- Respuesta directa: 1-3 oraciones cortas en chino que respondan la pregunta del usuario de inmediato. Prefiera una analogía vívida cuando ayude a la memoria. Esto debe ser comprensible por sí solo para los usuarios que no tienen tiempo de abrir el HTML.
- HTML interactivo: una ruta local o enlace al explicador HTML generado/reutilizado.
Use una forma compacta como:
一句话说,Skill 像给 AI 准备的一本小手册:Prompt 是这次怎么做,Skill 是以后遇到同类任务都按这套做。
互动页:<path/to/html>
No obligue al usuario a abrir el HTML para obtener la respuesta básica.
Espacio de Trabajo (Workspace)
Espacio de trabajo predeterminado:
<directorio de trabajo actual>/concept-forge-workspace
Si el usuario nombra otra ubicación de almacenamiento, use esa. Inicialice antes del primer uso:
python <skill>/scripts/concept_forge.py init --workspace <workspace>
El espacio de trabajo contiene:
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 Concepto
Tome prestado el espíritu de hv-analysis, pero manténgalo ligero y del tamaño de un concepto.
Para cada concepto nuevo o actualizado, responda a estas capas:
- Resumen de una línea: la definición útil más corta.
- Respuesta directa: una explicación lista para el chat, generalmente un párrafo corto, opcionalmente con una metáfora.
- Qué es: explicación en lenguaje sencillo.
- Por qué existe: qué problema, confusión, flujo de trabajo o cambio histórico creó la necesidad.
- Cómo funciona: el mecanismo mínimo necesario para entenderlo.
- Qué no es: conceptos erróneos comunes y líneas límite.
- Comparación horizontal: conceptos, herramientas, prompts, flujos de trabajo o términos cercanos con los que a menudo se confunde.
- Mapa relacionado: conceptos padre, conceptos hermanos, conceptos hijo, requisitos previos y preguntas siguientes.
- Ejemplo: un escenario cotidiano concreto.
- Gancho de memoria: metáfora, frase o anclaje visual que lo haga perdurar.
- Mini cuestionario: 2-3 preguntas ligeras para reforzar la memoria.
Use investigación web cuando los hechos puedan ser actuales, específicos de un producto, controvertidos o sensibles a la fuente. Prefiera documentación oficial y fuentes primarias. Si no se navega, marque las fuentes como "derivado del modelo / proporcionado por el usuario / contexto local" honestamente en el registro.
Modos de Salida
Selección de Rama
Hay tres ramas de producto. Distíngalas con precisión.
- Rama de concepto normal: el usuario pregunta "X 是什么", "X 和 Y 有什么区别", "帮我理解/记住/整理这个概念", o da una palabra clave. Genere respuesta directa, fuente Quarkdown, fuente Slidev, HTML e índice. No solicite la instalación de Quarkdown o Slidev.
- Rama de lectura formal: el usuario solicita "正式阅读", "长文档", "报告", "PDF", "文档", "打印", "编译", "导出", "交付", o menciona explícitamente Quarkdown. Ejecute
bootstrapantes de compilar. Si falta Quarkdown, deténgase antes de compilar/exportar y muestre las instrucciones de instalación. - Rama de presentación formal: el usuario solicita "演示", "公开讲解", "课件", "幻灯片", "PPT", "slides", "deck", "presentation", "预览", "构建", "导出", o menciona explícitamente Slidev. Ejecute
bootstrapantes de la vista previa/compilación/exportación. Si faltan Node/npm o las dependencias del proyecto Slidev, deténgase antes de la vista previa/compilación/exportación y muestre las instrucciones de configuración.
Si el usuario solicita tanto lectura como presentación, use Quarkdown como borrador maestro y Slidev como borrador de charla derivado, luego verifique ambas ramas.
Comandos auxiliares de rama:
python <skill>/scripts/concept_forge.py --workspace <workspace> plan "<solicitud original>"
python <skill>/scripts/concept_forge.py --workspace <workspace> bootstrap "<solicitud 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
Si la búsqueda encuentra una entrada existente sólida:
- Diga que ya existe.
- Dé la respuesta corta de
direct_answersi está presente, de lo contrario usesummarymásmemory_hook. - Enlace la página HTML local.
- Ofrezca qué se puede actualizar solo si es útil; no reconstruya por defecto.
Nueva Entrada
Para un nuevo concepto:
- Cree un registro JSON siguiendo
references/concept-schema.md. - Incluya al menos: título, alias, profundidad, respuesta directa, resumen, qué, por qué, no, comparaciones, relacionado, gancho de memoria, cuestionario, fuentes.
- Ejecute:
python <skill>/scripts/concept_forge.py upsert --workspace <workspace> --input <concept.json>
python <skill>/scripts/concept_forge.py validate --workspace <workspace> --slug <slug>
- Devuelva la respuesta directa primero, luego la ruta HTML generada. Mencione las rutas de Quarkdown o Slidev solo cuando el usuario solicite archivos, borradores de lectura, charlas, exportaciones o depuración.
Actualización
Actualice solo cuando:
- el usuario pida actualizar / rehacer / expandir;
- la antigüedad de la entrada supere
refresh_policy.days; - el tema sea actual o de rápida evolución;
- las fuentes sean débiles o falten;
- el usuario haga una pregunta de seguimiento más específica que cambie el límite del concepto.
Al actualizar, conserve los alias existentes y los enlaces relacionados a menos que sean claramente incorrectos.
Requisitos HTML
Use references/html-explainer.md para la forma exacta del producto.
La página generada debe ser autónoma y debe incluir:
- definición principal;
- secciones "qué / por qué / no";
- tarjetas de comparación;
- mapa de conceptos relacionados;
- línea de tiempo o banda de origen cuando sea útil;
- tarjetas interactivas de revelación;
- mini cuestionario;
- "tres cosas para recordar";
- pie de página de fuente/actualización.
La página debe ser comprensible sin la transcripción del chat.
Quarkdown y Slidev de Primera Clase
Quarkdown y Slidev son parte de la forma del producto.
- Genere siempre
concept.qdcomo el borrador maestro de Quarkdown. Es el documento de lectura canónico para la base de conocimiento. - Genere siempre
slidev/<slug>/slides.mdcomo el borrador de presentación. Se extrae del registro del concepto y del borrador maestro. - Genere siempre
html/<slug>.htmlcomo la superficie de memoria interactiva rápida. - Use profundidad dinámica para decidir cuánta investigación, referencias y pulido agregar:
- Rápida: concepto pequeño y estable; genere todos los artefactos fuente, normalmente omita la compilación/exportación.
- Estándar: predeterminada para herramientas, métodos, comparaciones y "qué es X"; genere todos los artefactos y verifique la estructura.
- Profunda: el usuario solicita investigación o el tema es actual/complejo; fortalezca las fuentes, el historial, la comparación horizontal y la estructura de la charla.
- Compile Quarkdown o compile/exporte Slidev solo cuando la solicitud entre en una rama formal. La generación de fuentes no debe depender de que los CLI estén instalados.
- Use
scripts/concept_forge.py doctoren el primer uso para una verificación general del entorno. - Use
scripts/concept_forge.py bootstrap "<solicitud original>"antes de la compilación/exportación formal para decidir si guiar la instalación. - Para la lectura formal de Quarkdown, requiera
quarkdown. Si falta en Windows, muestre:irm https://raw.githubusercontent.com/quarkdown-labs/get-quarkdown/refs/heads/main/install.ps1 | iex, luego verifique conquarkdown doctor get install-dir. - Para la compilación de Quarkdown, ejecute
quarkdown c <concept.qd> --strict --out <verify-dir>cuandoquarkdownesté disponible. - Para la presentación formal de Slidev, requiera Node más npm o pnpm. En
slidev/<slug>, ejecutenpm installopnpm install, luegonpm run dev,npm run buildonpm run exportsegún sea necesario. - Para la exportación a PDF/PPTX de Slidev, instale primero
playwright-chromiumen el proyecto de diapositivas generado:npm i -D playwright-chromium.
Puerta de Calidad
Antes de informar la finalización, verifique:
- se intentó la búsqueda antes de crear;
- la respuesta final contiene tanto una respuesta directa como una ruta HTML;
- el concepto tiene un resumen de una línea claro;
- se cubren los conceptos cercanos y los conceptos erróneos;
- el HTML existe y no está vacío;
- el borrador maestro de Quarkdown existe;
- la fuente de Slidev existe;
- las ramas formales ejecutaron
bootstrapantes de compilar/exportar; - la falta de herramientas formales se informó antes de intentar compilar/exportar;
validatepasa;- el índice contiene título, alias, slug, respuesta directa, resumen, ruta Quarkdown, ruta Slidev y ruta HTML;
- la respuesta final es corta, en chino y orientada al usuario.
Referencias
references/concept-schema.md: forma del registro JSON y Markdown.references/research-method.md: adaptación ligera de hv-analysis.references/html-explainer.md: especificación del producto HTML interactivo.