Dnnecessary/skills - 排版助手

Skill de Maquetación de Artículos para WeChat (公众号)

Convierte un artículo en Markdown en HTML que se puede copiar y pegar directamente en el editor oficial de WeChat, manteniendo los estilos al pegar.

El activo principal es la biblioteca de componentes de tema en references/ (cada tema: variables de diseño + HTML completo de cada componente + esqueleto de plantilla + reglas de mapeo) más una biblioteca incremental general (bloques de código / imágenes·GIF / títulos con etiquetas pequeñas, compartida por todos los temas). El listado de temas se basa únicamente en references/theme-index.md. Este SKILL.md solo se encarga del flujo de trabajo y las decisiones; el código HTML concreto se obtiene siempre de la biblioteca de componentes, sin escribirlo de memoria.

Flujo de trabajo

0. Entrada y normalización de formato

El usuario puede proporcionar: texto Markdown o ruta .md (entra directamente en el paso 1), .docx, .pdf, .txt/texto plano sin marcas, o texto enriquecido web. Las entradas que no sean Markdown deben leerse primero references/format-normalize.md y seguir sus reglas para convertirlas a un borrador Markdown y confirmar la estructura (.docx usa scripts/extract_docx.py, PDF usa Read página a página + limpieza de ruido, texto plano infiere estructura heurísticamente a partir de títulos). Si no se proporciona nada, solicitar al usuario.

Cuando el usuario diga «directamente / automático / un clic / no preguntes», se entra en modo completamente automático: se omite la confirmación de estructura y la pregunta de selección de tema, se infiere la estructura automáticamente, se selecciona el tema según el tema del artículo, se maqueta y valida, y al entregar se incluye una explicación de las decisiones (estructura de capítulos, título propuesto, motivo de la selección del tema).

1. Selección de tema (recomendación automática)

Leer references/theme-index.md (fuente única de información de temas). Recomendar activamente el tema más adecuado según el tema del artículo, y luego pedir al usuario que confirme en un solo paso---recomendar pero no fijar sin permiso:

• El usuario ya ha especificado un tema en la solicitud → usarlo directamente, sin preguntar.
• El tema del artículo tiene una correspondencia clara → preguntar con una sola confirmación: «Se recomienda XX (motivo), ¿confirmar o cambiar a otro?» Las opciones incluyen la recomendación + 1~2 alternativas + «Ver todos». La correspondencia tema → artículo se basa en la columna «Escenarios de aplicación» del theme-index:
  • Tutoriales / reseñas / listas / inventario de herramientas / organización de conocimientos / análisis metodológicos (alta densidad de información) → Verde Mofei
  • Análisis profundos / opiniones / temas contundentes → Rojo y blanco
  • Diseño / reseñas de tecnología / opiniones profesionales / marcas premium → Minimalismo Grafito
  • Zen / vida minimalista / ensayos profundos → Estilo Zen con espacios
  • Comparación de herramientas / reseñas creativas (metáfora visual de billetes) → Estilo Billete Mofei
  • Notas internas / reseñas profundas / análisis de casos → Notas Aceituna
• Sin tendencia clara → por defecto, el primer tema del theme-index (Verde Mofei) se coloca como primera opción recomendada, y se usa AskUserQuestion para que el usuario elija entre varias opciones (si hay más de 4 temas, primero preguntar por grupos según la atmósfera, luego preguntar por el tema dentro de ese grupo).
• Modo completamente automático (el usuario dice explícitamente «directamente / un clic / no preguntes») → no preguntar, seleccionar automáticamente el tema más adecuado o el primer tema por defecto, y al entregar explicar el motivo de la selección.
• El usuario no está satisfecho con ningún tema existente / quiere un nuevo estilo → ir al flujo de «Generación de tema personalizado» (ver sección siguiente), generar y registrar, luego volver a este paso para seleccionarlo.
• theme-index está vacío → detener la maquetación e informar al usuario de que primero debe añadir un estilo de tema (puede usar la «Generación de tema personalizado»).

Una vez que el usuario ha decidido el tema, se procede a la combinación de componentes dentro de ese tema (pasos 3 y 4: determinar el tipo de artículo → seleccionar la combinación de componentes según la tabla de recetas de ese tema).

2. Leer la biblioteca de componentes (dos partes)

(1) Según la columna «Archivo de biblioteca de componentes» del theme-index para ese tema, leer la biblioteca de componentes exclusiva del tema references/theme-{identificador}.md (incluye tarjetas de cita, títulos de capítulos, marcas de cuerpo de texto, firmas, etc., específicos del tema). (2) Leer simultáneamente la biblioteca incremental general references/common-components.md---bloques de código, imágenes/GIF y títulos con etiquetas pequeñas son compartidos por todos los temas; solo se adaptan al color principal del tema actual.

La generación posterior se basa exclusivamente en estas dos bibliotecas de componentes; el HTML se obtiene siempre de ellas, sin escribir desde la memoria.

3. Analizar la estructura Markdown

Elemento	Regla de reconocimiento
Título del artículo	# Título o title en frontmatter
Cita de apertura	Bloque > cita al inicio del artículo
Título de capítulo	## Título
Subcapítulo	### Título
Negrita / Resaltado / Subrayado	**texto** / ==texto== / <u>texto</u> o ++texto++
Párrafo de cita	> texto que no esté al inicio
Imagen / GIF	,  (GIF se trata igual que las imágenes)
Código / Comando / Prompt	``` bloque de código ```, `código` en línea
Línea divisoria / Lista	---, *** / - elemento o 1. elemento
Tabla	Tabla Markdown separada por `

Después de analizar la estructura, determinar el tipo de artículo (tomar el tipo dominante, puede ser compuesto): Tutorial/Guía de operación, Inventario/Lista de herramientas, Opinión/Análisis profundo, Entrevista/Reportaje de personajes, Revisión de datos/Informe, Vida/Ensayo emocional, Caso práctico. Criterios: muchos pasos y comandos → Tutorial; muchos elementos en paralelo → Inventario; muchas citas y narrativa de personajes → Entrevista; muchos números y comparaciones → Datos; mucha argumentación y razonamiento → Opinión.

4. Seleccionar combinación de componentes según la receta → Ensamblar HTML

Primero consultar la tabla de «Tipo de artículo → Combinación de componentes (receta)» de la biblioteca de temas seleccionada, y determinar la combinación de componentes centrales y complementarios para este artículo según el tipo---no seleccionar componentes aleatoriamente párrafo por párrafo al obtener la biblioteca de componentes; la receta garantiza la consistencia visual de artículos del mismo tipo. Los elementos fuera de la receta se complementan según las reglas de mapeo de la biblioteca de temas.

Luego ensamblar según la sección «Esqueleto de plantilla de artículo completo» de la biblioteca de temas, reemplazando cada elemento Markdown por el componente correspondiente:

• El orden del esqueleto se basa en la biblioteca de temas; diferentes temas pueden tener esqueletos diferentes, no aplicar el esqueleto de otro tema.
• Las marcas en línea se buscan semánticamente en la biblioteca de componentes seleccionada (los números de componente no son uniformes entre bibliotecas, siempre guiarse por la semántica, no por números fijos): **negrita** → negrita con color principal; ==resaltado== → resaltado con fondo claro de color sólido; <u>texto</u> o ++texto++ → subrayado; ~~texto~~ → resaltador (fondo claro de color sólido); >cita → bloque de cita resaltado.
• Componentes de la biblioteca incremental general: ``` bloque de código ``` → 1a bloque oscuro / 1b bloque claro, `código` en línea → 1c; ![descripción](url) → 2a imagen (agregar componente de descripción solo si hay descripción), .gif → 2b GIF; subtítulo/énfasis que necesite resaltar → 3a subtítulo con barra vertical izquierda o 3b etiqueta tipo píldora, frase clave → 3d, nota marginal → 3e. Prioridad: primero consultar la tabla de reglas de mapeo de la biblioteca de temas---si ese tema tiene un componente semánticamente equivalente (como su propia frase clave o bloque de nota), usar la versión de la biblioteca de temas para mantener la coherencia visual; si la biblioteca de temas no tiene un componente correspondiente, usar el de la biblioteca general (3x) y aplicar su regla de cambio de color al color del tema.
• Un artículo usa solo el conjunto de componentes del tema seleccionado, no mezclar componentes de diferentes temas.
• Énfasis y subtítulos: usar «etiqueta pequeña / barra vertical izquierda», no usar bordes discontinuos: para resaltar un subtítulo o un fragmento, usar el subtítulo con barra vertical izquierda (3a), la etiqueta tipo píldora (3b), o la frase clave/bloque de nota con barra vertical izquierda (3d/3e); no usar un borde discontinuo (dashed) alrededor de un título, ya que resulta pesado y llama demasiado la atención.

5. Verificar el cumplimiento (obligatorio)

Después de escribir el HTML generado en el archivo de destino, es obligatorio ejecutar el script de validación, y solo cuando los ERROR estén a cero se considera completo:

# Llamar usando la ruta absoluta del skill donde se encuentra el script; el parámetro HTML también usa su ruta real (normalmente los directorios son diferentes)
<SKILL_ROOT>/scripts/validate_gzh_html.py <ruta real del .html generado>

Verifica deterministicamente los elementos prohibidos por la plataforma y el envoltorio <span leaf>. Si reporta ERROR, volver al paso 4 para corregir; las ADVERTENCIAS de puntuación de ancho medio también deben corregirse a cero antes de entregar (este es el punto de retrabajo más frecuente en el uso real).

Las ADVERTENCIAS de fondo degradado deben tratarse una por una: el fondo de resaltados de texto, citas, tarjetas de datos/guía se cambian por defecto a un color sólido del tema o rgba sólido; si el usuario solicita explícitamente mantenerlo, al entregar se indica que puede activar la ventana emergente darkmode-no-gradient. Los degradados puramente decorativos también se notifican; aún no se ha confirmado que no activen la ventana emergente, por lo que al mantenerlos también se explica el riesgo.

6. Salida

Formato del producto: fragmento de cuerpo <section>…</section> puro, comenzando desde el contenedor global, sin incluir <!DOCTYPE>/<html>/<head>/<body>---el editor de WeChat solo acepta fragmentos de cuerpo; las envolturas de documento sobrantes se descartan o interfieren con el pegado.

1. Archivo de cuerpo limpio: HTML guardado en el directorio de trabajo actual, nombre {nombre_original}_maquetación_{nombre_chino_del_tema}({identificador_inglés}).html (identificador inglés = nombre del archivo de biblioteca de componentes del theme-index sin el prefijo theme- y la extensión .md). Este archivo se usa para la validación y como copia de seguridad para pegado manual.
2. Página de vista previa con botón «Copiar» (para que el usuario copie con un clic, evitando la selección manual):

   <SKILL_ROOT>/scripts/wrap_preview.py <el archivo de cuerpo limpio anterior.html>
   

   Genera {...}_vista_previa.html---al abrirlo en el navegador, aparece un botón «Copiar a WeChat» en la esquina superior derecha; al hacer clic, copia el texto enriquecido renderizado al portapapeles (equivalente a Ctrl+A/Ctrl+C), y luego se pega con Ctrl/⌘+V en el editor de WeChat. El botón y el script solo están en la envoltura de vista previa, no dentro de la sección que se copia, por lo que lo que se pega en WeChat sigue siendo el fragmento de cuerpo limpio y conforme.
3. Informar al usuario: Abrir {...}_vista_previa.html → Hacer clic en «Copiar» en la esquina superior derecha → Pegar en el editor de WeChat; y proporcionar la ruta del archivo de cuerpo limpio como copia de seguridad. Adjuntar la conclusión del script de validación (aprobado / advertencias restantes).

Procesamiento inteligente durante la generación (estas son características distintivas de este skill, deben hacerse)

1. Numeración automática de capítulos: Asignar 01/02/03… según el orden de aparición de ##; si el último capítulo es de tipo conclusión/resumen, usar la variante de numeración de conclusión especificada por la biblioteca de temas (por ejemplo ∞), si la biblioteca de temas no lo especifica, seguir usando la numeración numérica.
2. Etiqueta en inglés: Generar una etiqueta en inglés a partir del título del capítulo en chino (ejemplo real → TEST, tutorial → TUTORIAL, resumen → SUMMARY, reflexión → THOUGHTS…), usar cuando la biblioteca de temas tenga una ranura correspondiente.
3. Subrayado de palabras clave en el cuerpo del texto (característica central): Para cada párrafo del cuerpo, identificar activamente 1–3 frases más importantes y marcarlas con el CSS de subrayado de ese tema (ver theme-index). Priorizar marcar ideas centrales, conclusiones, datos clave, nombres propios; frases de 4–15 caracteres; si un párrafo no tiene puntos clave, no es necesario marcar. Incluso si el texto original no tiene negrita, se debe añadir subrayado activamente---es la marca básica más frecuente.
4. Resaltado de palabras clave en la cita de apertura: Identificar las palabras clave de la frase inicial y marcarlas con el componente de resaltado.
5. Extracción de tabla de contenidos: Tomar los primeros 3 de todos los ## como puntos de la tabla de contenidos/guía (cuando la biblioteca de temas tenga un componente de tabla de contenidos).
6. Atribución en la tarjeta de cita de apertura: Según el autor o tema del artículo---si el artículo tiene atribución, escribir «—— Nombre del autor»; si no hay un autor claro, usar una breve despedida relacionada con el tema u omitirla. No escribir fijo «Jiǎ Mù» (la zona de firma al final también usa el marcador de posición {{nombre del autor}}, ver punto 7).
7. Zona de firma del autor al final (que el autor complete, solo un lugar al final): Por defecto no escribir ningún nombre fijo, usar un marcador de posición para que el usuario lo reemplace con el suyo.
   • Primera frase (presentación del autor): Soy {{nombre del autor}}, {{breve descripción, ej.: apasionado por compartir observaciones y contenido práctico sobre IA}}---si el usuario ha proporcionado una firma o descripción en la solicitud o preferencia, se completa directamente; si no, se mantiene el marcador de posición {{nombre del autor}} / {{descripción}}, y al entregar se indica al usuario que lo reemplace con su propia firma.
   • Segunda frase (llamada a la interacción, se puede mantener tal cual): Si crees que el artículo de hoy te ha sido útil, no dudes en darle a **Me gusta, Ver en segundos, Compartir**, ¡nos vemos en el próximo!
   • Si el final del texto original ya tiene una firma de autor (como «Soy XXX…») → mantener directamente la firma del original, sin reemplazarla por el marcador de posición.
8. Conversión de listas: Procesar según las reglas de mapeo de la biblioteca de temas; si no hay un componente de lista específico, convertir en párrafos de cuerpo con sangría.
9. Puntuación de ancho completo en chino: Toda la puntuación del cuerpo debe ser de ancho completo (，。！？：；""''（）—— …), no usar comas, puntos, signos de exclamación, interrogación, dos puntos, punto y coma de ancho medio ni comillas rectas inglesas " '. Al generar HTML, usar directamente comillas curvas ""''; no escribir primero comillas rectas y luego reemplazar---las comillas rectas del texto original se convierten en el momento de la transcripción. Excepción: dentro de bloques de código, código en línea, nombres propios en inglés/URL/identificadores de código se mantienen igual.

Jerarquía visual (3 niveles progresivos, común a todos los temas)

Nivel	Función	Frecuencia	Medio
Nivel de anclaje	Anclaje más fuerte: nombre del producto/pasos/CTA/frase clave central	≤ 5 en todo el artículo	Negrita con color principal, cita con fondo oscuro y texto blanco
Nivel de marca	Palabras clave del cuerpo, 1–3 por párrafo	Alta frecuencia	Marca de subrayado
Nivel de contenedor	Bloques de cita, etiquetas de concepto, énfasis en frases largas	Según necesidad	Cita con fondo claro, resaltador, insignia

Reglas de la plataforma (críticas, la verificación completa se deja al script de validación)

• Prohibido: <style>/<script>/<div>, atributos class/id, position:fixed/absolute/sticky, float, @media/@keyframes, display:grid, variables CSS, fuentes/CSS externos.
• Obligatorio: Todos los estilos en línea style; todos los nodos de texto deben estar envueltos en <span leaf="">texto</span> (de lo contrario, los estilos se pierden al pegar).
• Permitido: display:flex (limitado), border-radius, box-shadow, <section>/<p>/<span>/<strong>/<img>/<h3>.
• Compatibilidad de fondos degradados: Los degradados se pueden renderizar, pero pueden activar la detección de contenido darkmode-no-gradient de WeChat; el fondo de texto y tarjetas se usa por defecto con colores sólidos, sin añadir degradados adicionales. Los componentes antiguos o temas personalizados que se encuentren con esto también se tratan según el paso 5.

Gotchas (problemas encontrados en maquetaciones reales)

• Falta de envoltorio <span leaf> es el error fatal más común---al pegar en WeChat, los estilos se pierden por completo. Depender del script de validación del paso 5 como respaldo; no saltarlo.
• Subrayado: aplicar párrafo por párrafo, 1–3 frases por párrafo. No subrayar todo el párrafo (pierde el foco), y no saltarse algunos párrafos; las descripciones clave en elementos de lista también deben marcarse.
• Numeración de capítulos desordenada: Seguir estrictamente el orden de ##, no saltar números; la variante de numeración de conclusión solo se usa para el último capítulo, no para los intermedios.
• La zona de firma solo aparece una vez al final: Usar texto fijo, no aparecer en medio ni en varios lugares; si al final del texto original ya hay un párrafo de firma del autor/"Me gusta, Ver, Compartir", identificarlo y fusionarlo en esta única zona de firma/tarjeta CTA, no mantener el párrafo original y generar otro.
• Inventar descripciones de imágenes: Solo generar el componente de descripción de imagen si ![descripción](url) realmente tiene texto de descripción; con ![](url) y alt vacío, no inventar una descripción.
• Imágenes adaptativas, no a lo ancho: <img> siempre con max-width:100%;height:auto;display:block;margin:0 auto---se muestran según su tamaño original, centradas; las imágenes grandes se reducen al ancho del contenedor, las pequeñas mantienen su tamaño. No usar width:100% (estiraría las imágenes pequeñas volviéndolas borrosas); solo los elementos de diseño como tablas, tarjetas de portada o diagramas de flujo usan width:100%.
• Mezclar componentes de diferentes temas: Un artículo usa solo componentes del tema seleccionado + la biblioteca general; no tomar prestados componentes de otros temas.
• Abuso del nivel de anclaje: La marca más fuerte ≤ 5 en todo el artículo; poner negrita en todas partes equivale a no tener énfasis.
• Omisión de contenido original: Cada párrafo y cada imagen deben convertirse; no omitir; no añadir ni eliminar contenido sustancial del original.
• Restos de imágenes de marcador de posición: Si la zona de firma/componentes CTA llevan imágenes de marcador de posición (como <img src="...URL de tarjeta de presentación o guía">), si no hay una URL de imagen real, eliminar toda la línea; no dejar marcadores de posición en el producto final.
• La tabla de contenidos es seleccionada, no completa: El componente de introducción/guía/tabla de contenidos muestra 3 puntos destacados seleccionados, no la lista completa de capítulos; si hay más de 3 capítulos, elegir los 3 más importantes; no forzar la inclusión de todos ni dar a entender que solo hay 3 capítulos.
• No usar bordes discontinuos: Para resaltar títulos/énfasis, usar etiquetas pequeñas o barras verticales izquierdas (biblioteca general 3a–3e); no usar border:…dashed con bordes discontinuos alrededor de un título. Excepción: los componentes con bordes discontinuos definidos explícitamente en la biblioteca de temas (como el cuadro de cita quote-box de Verde Mofei o la tarjeta destacada oneliner-card) son características de estilo de ese tema y se usan normalmente según las reglas de la biblioteca.
• No mezclar puntuación de ancho medio: Las comas y puntos de ancho medio en el cuerpo, así como las comillas rectas inglesas " ', deben cambiarse a ancho completo; pero los símbolos de ancho medio dentro de bloques de código o código en línea se mantienen igual, sin «pasar a ancho completo» el código.
• Código/Prompt debe usar bloques de código: El código, comandos y prompts del artículo deben usar los componentes de bloque de código de la biblioteca general (1a/1b); no deben meterse en párrafos normales o bloques de cita, o se perderán la sangría y la fuente monoespaciada.
• Los bloques de código deben ser compactos, evitar grandes espacios en blanco: Usar la escritura "cada línea un <p style="margin:0">" de la biblioteca general 1a/1b; no usar white-space:pre---renderizaría la sangría antes de span y los saltos de línea entre líneas del código fuente HTML como una gran sangría izquierda + líneas en blanco; la sangría se hace solo con espacios de ancho completo 　, y el interlineado con line-height:1.6.
• Materiales pendientes centrados: Los marcadores de posición como 【Insertar…】, captura de pantalla/GIF/video/imagen de resultado, etc., usar el componente 2c de marcador de posición de material centrado de la biblioteca general (borde discontinuo suave con fondo claro + icono centrado y descripción), no usar bloques de nota alineados a la izquierda.

Generación de tema personalizado (segundo flujo de trabajo)

Cuando el usuario quiera un estilo nuevo que no esté entre los temas integrados (diga «generar un nuevo tema / estilo personalizado / hacer un conjunto de componentes según esta imagen de referencia», o no esté satisfecho con ningún tema existente), leer references/theme-generator.md y ejecutar estrictamente su flujo:

1. Recopilar preferencias: La descripción del tema es obligatoria (o imagen de referencia); el nombre/ID/5 colores/fuente/3 etiquetas TAG/radio de borde/sombra se pueden dejar vacíos y se completan automáticamente; preguntar todo de una vez, no preguntar campo por campo.
2. Generar el HTML de la biblioteca de bloques: Ejecutar el 【Prompt de generación】 al final de theme-generator.md tal cual, generando una biblioteca de bloques completa de 45~75 bloques, guardarla en assets/theme-previews/{theme-id}.html---todos los bloques dispuestos de forma continua en la misma página; el usuario abre la página completa de una vez para confirmar el estilo, no se confirma bloque por bloque.
3. Convertir + Registrar: Una vez que el usuario confirma el estilo, convertirlo al estándar references/theme-{identificador}.md (obligatorio añadir envoltorio <span leaf="">, eliminar los id de vista previa, completar los 5 capítulos, las reglas se detallan en el paso 3 de theme-generator.md), registrar en theme-index.md, ejecutar component_lint.py hasta 0 ERROR.
4. Después de la entrega, ese tema se convierte en un tema opcional permanente, con los mismos derechos que los temas integrados para maquetaciones posteriores.

Durante la fase de generación, se siguen las reglas del prompt; durante la fase de conversión a la biblioteca de temas, se siguen las «Reglas de la plataforma» y las «Normas para añadir un nuevo tema» de este documento (en caso de conflicto, prevalecen estas últimas, ya que la biblioteca de temas determina directamente el producto de maquetación).

Normas para añadir un nuevo tema

El nuevo tema se nombra como references/theme-{identificador_inglés}.md, y su contenido debe incluir obligatoriamente:

1. Tabla de referencia de variables de diseño (color principal/fondo claro/texto oscuro/color de título/color de cuerpo/color de línea divisoria, etc.)
2. HTML completo de cada componente (estilo en línea + envoltorio <span leaf="">, cumpliendo las «Reglas de la plataforma» anteriores)
3. Esqueleto de plantilla de artículo completo (orden de ensamblaje de componentes; si hay componentes de tabla de contenidos/navegación, especificar su posición relativa a la portada/cita de apertura)
4. Tabla de recetas de combinación de componentes por tipo de artículo (combinación de componentes centrales + componentes complementarios para cada tipo de artículo; la receta es clave para la consistencia visual de la maquetación)
5. Tabla de reglas de mapeo de Markdown a componentes

Después de añadirlo, registrar una línea en references/theme-index.md (nombre del tema / color principal / escenarios de aplicación / archivo de biblioteca de componentes / CSS de subrayado del cuerpo), y ejecutar python3 scripts/component_lint.py . para confirmar que la biblioteca de componentes no tiene antipatrones (0 ERROR).

Los casos de prueba para la activación y selección de temas se encuentran en references/eval-cases.md (se usan para comprobaciones de regresión durante el mantenimiento, no afectan a la generación individual).