mxchen-xyz/knowledge-graph-skill-zh

Generador de Grafos de Conocimiento por Lotes

📌 Historial de Versiones

Versión	Fecha	Cambios
2.2.0	2026-09-02	Actualización masiva de proyectos a gran escala: ① Estrategia de actualización de tarjetas esqueleto – cuando el usuario reporta "demasiados pendientes/reglas demasiado simples" se desencadena una actualización completa, con agentes hijos distribuidos por área y un agente principal que monitorea la salida (grep de elementos pendientes restantes). Si un agente secundario se estanca, el principal toma el control y completa el trabajo. ② Prohibición de paréntesis anidados en etiquetas de nodos mermaid (principal causa de fallo de renderizado) y script de corrección masiva con expresiones regulares. ③ Los agentes secundarios son propensos a errores con rutas relativas entre módulos (nivel ../..); la verificación final debe ejecutar un script de validación de enlaces bidireccionales. ④ Actualización de estadísticas y README tras la actualización.
2.1.0	2026-09-01	Corrección importante de rutas de enlaces wiki de Obsidian: los enlaces wiki [[...]] de Obsidian no admiten rutas relativas ../ (../ se interpreta como nombre de nota y no se puede hacer clic). Se cambian todos a rutas completas desde la raíz del repositorio de conocimiento (`[[Área/Módulo/Función.md
2.0.0	2026-08-24	Corrección de compatibilidad de enlaces bidireccionales de Obsidian: se añade en el quinto lote "sintaxis de puntos + verificación de resolución de ruta relativa por enlace". El repositorio de conocimiento generado puede navegarse correctamente en Obsidian.
1.0.0	Versión inicial	Capacidad básica de generación por lotes en 5 tandas (esqueleto L1+L2 → índice de módulos L3 → tarjetas de funciones principales → esqueleto de funciones restantes → verificación de calidad global).

Resumen

Ingeniería del conocimiento para proyectos a gran escala. Cuando un proyecto tiene código/documentación completo, más de 50 nodos de funcionalidades, y se necesita generar un repositorio de conocimiento completo de cientos de nodos en una sola vez, se utiliza una estrategia por lotes para una generación eficiente, evitando la sobrecarga de salida única. Todo el contenido de los archivos debe seguir las especificaciones de plantilla definidas en la habilidad business-knowledge-graph-generator (references/templates.md).

Cuándo usarlo

• Proyectos a gran escala con más de 50 funcionalidades.
• Se dispone de la estructura completa del directorio del proyecto y el contenido de los archivos de código principales (se pueden proporcionar por lotes).
• Necesidad de generar un repositorio de conocimiento completo de cientos de nodos en una sola vez.

Requisito de entrada: proporcionar la estructura completa del directorio del proyecto + el contenido de los archivos de código principales (se puede proporcionar por lotes).

Estrategia de Procesamiento por Lotes

Cuando el número de funcionalidades supera 50, se procesan en 5 lotes en el siguiente orden:

Primer Lote: Esqueleto L1 + L2 (Estructura Global) – Salida esperada: 6~20 archivos

1. Generar knowledge/_index.md (Panorama L1).
2. Generar <Área>/_index.md para cada área (Mapa de área L2).
3. Control de calidad: confirmar que todas las áreas y módulos están cubiertos, sin omisiones.

Segundo Lote: Índices de Módulos L3 (Lista de Funcionalidades) – Salida esperada: 20~50 archivos

1. Generar <Área>/<Módulo>/_index.md para cada módulo (Mapa de módulo L3).
2. Control de calidad: confirmar que la lista de funcionalidades de cada módulo está completa y que todas las funcionalidades están nombradas.

Tercer Lote: Tarjetas de Funcionalidades de Alta Prioridad (Flujos Principales) – Salida esperada: 20~30 archivos

1. Identificar las funcionalidades principales del sistema (el 20% de funciones más usadas, como inicio de sesión, realizar pedido, pago).
2. Generar tarjetas L4 completas para estas funcionalidades (incluyendo flujo, reglas, eventos, dependencias, ubicación del código).
3. Control de calidad: los flujos principales deben incluir ramas de excepción, la ubicación del código debe ser precisa hasta el número de línea.

Cuarto Lote: Tarjetas Esqueleto de Funcionalidades Restantes – Salida esperada: 50~200+ archivos

1. Generar tarjetas minimizadas para las funcionalidades restantes (que contengan al menos Frontmatter + descripción de la función + reglas básicas).
2. Marcar con Estado: Pendiente, para que el usuario las complete manualmente más adelante.
3. Control de calidad: todas las funcionalidades tienen su archivo .md correspondiente, sin omisiones.

Quinto Lote: Verificación de Calidad Global y Actualización de Índices

1. Verificar que todos los enlaces bidireccionales son rutas relativas compatibles con Obsidian ([[../módulo/función.md|alias]]), sin sintaxis de puntos como [[Área.Módulo.Función]].
2. Validar transversalmente: cada enlace, resuelto desde el archivo actual, debe apuntar a un archivo .md existente.
3. Marcar todos los enlaces rotos y generar una lista de corrección.
4. Actualizar las estadísticas (número de módulos, número de funcionalidades) en los _index.md de cada nivel.
5. Generar knowledge/README.md con instrucciones de uso.

Reglas de Clasificación de Prioridad

Prioridad	Criterio	Ejemplos de Funcionalidades
Principal	Escenarios de uso diario > 80%, relacionados con seguridad financiera	Inicio de sesión, realizar pedido, pago, reembolso
Importante	Escenarios de uso diario 30%~80%, relacionados con gestión de datos	Consulta de pedidos, seguimiento de envíos, modificación de información
General	Funcionalidades de panel de administración, operaciones de baja frecuencia, configuración	Gestión de categorías de productos, consulta de registros, generación de informes

Requisitos de Salida

1. Salida por lotes. Después de cada lote, informar del progreso y esperar la confirmación del usuario antes de continuar con el siguiente.
2. En cada salida de lote, listar el inventario de archivos generados en este lote.
3. Una vez completado el tercer lote (funcionalidades principales), pausar y esperar a que el usuario especifique el área de enfoque para el siguiente lote.
4. Todo el contenido de los archivos debe seguir las especificaciones de plantilla definidas en business-knowledge-graph-generator/references/templates.md.

Formato de Informe por Lote

## Lote X completado ✅

**Número de archivos generados**: XX
**Áreas implicadas**: ÁreaA, ÁreaB
**Lista de archivos**:

- knowledge/ÁreaA/_index.md
- knowledge/ÁreaA/MóduloA/_index.md
- ...

**Plan para el siguiente lote**: Generar tarjetas de funcionalidades principales del área XXX

¿Confirma que desea continuar?

Notas Importantes

• Entrega por lotes: si el proyecto tiene más de 100 funcionalidades, complete primero el esqueleto L1 y L2, luego profundice gradualmente a L3, y finalmente genere L4 por lotes.
• Límite de lectura de código: si hay demasiados archivos de código, pida al usuario que proporcione primero 5~10 archivos clave del módulo principal; el resto puede describirse solo con la estructura de directorios.
• Complemento manual: la habilidad genera el 80% del contenido (estructura, flujo, marco de reglas), pero la información histórica sobre incidentes y los responsables deben ser añadidos manualmente por el usuario.

Experiencia Práctica (Proyecto jetlinks, 2026-09-01)

1. Los enlaces de Obsidian deben usar rutas desde la raíz del repositorio y sin extensión .md (lo más importante): Los enlaces wiki de Obsidian no admiten rutas relativas ../ (../ se interpreta como nombre de nota) y tampoco admiten la extensión .md ([[Nota.md]] se interpreta como una nota llamada "Nota.md" en lugar de "Nota", lo que impide hacer clic). Todos los enlaces deben escribirse como [[Área/Módulo/Función|alias]] (desde la raíz de knowledge/, sin .md). En los diagramas mermaid, usar nodos de texto plano (A[Función] --> B[Función]), prohibido el uso de [[...]].
2. Degradación por límite de velocidad 429 en agentes secundarios: durante la exploración/generación a gran escala, los agentes secundarios pueden alcanzar el límite de frecuencia (429). En ese caso, degradar a que la sesión principal genere directamente: primero localizar todos los @RequestMapping y anotaciones de método HTTP de los Controllers (puede ser preciso hasta el número de línea) usando Glob/Grep, y luego escribir archivo por archivo.
3. El script de control de calidad debe omitir los bloques de código: los ejemplos de "normas de enlace" dentro de las tarjetas L4 suelen estar en bloques de código con comillas invertidas. La expresión regular de control de calidad debe primero excluir el contenido de bloques `...` y mermaid , de lo contrario, los ejemplos se reportarán falsamente como enlaces rotos.
4. Mecanismo de reescritura del número de funcionalidades: el número de funcionalidades del módulo en el índice L2 es una estimación inicial; después de generar L3, se toma el valor real, y en el quinto lote se usa un script para reescribir automáticamente la columna de estadísticas L2 y las estadísticas de escala L1.
5. Usar script para la generación por lotes: para las tarjetas esqueleto del cuarto lote (100+ archivos), usar un script de Python que extraiga el nombre/tipo/descripción de la funcionalidad de la tabla del índice L3 mediante expresiones regulares y los escriba por lotes, garantizando la coherencia de nombres y enlaces. Es más eficiente y menos propenso a errores que escribir manualmente archivo por archivo.

Experiencia Práctica (Actualización masiva de proyectos a gran escala, 2026-09-02)

6. Actualización completa de tarjetas esqueleto, sin esperar a que se nombren: si el usuario no está satisfecho con "demasiados pendientes/reglas demasiado simples", se desencadena una actualización completa, por áreas, actualizando todas las tarjetas al nivel de detalle de las tarjetas completas (ver "Estándar de detalle de tarjetas L4" en la habilidad de negocio).
7. Agentes secundarios paralelos asignados por área + agente principal monitorizando: se asigna un agente secundario para cada área (el prompt incluye ejemplos de plantilla, la regla de hierro de mermaid y el requisito de inspección de código). El agente principal utiliza grep -rl "Estado: Pendiente" <Área> | wc -l para revisar periódicamente la cantidad restante. Si un agente secundario se estanca (sin nuevos archivos durante un tiempo), el principal toma el control y completa el trabajo, sin esperar pasivamente.
8. Prohibición de paréntesis anidados en etiquetas de nodos mermaid (principal causa de fallo de renderizado): la aparición de () dentro de nodos [..]/{..} del flowchart (por ejemplo, A[Foo(x)]) provoca un error de análisis "Expecting SQE, DOUBLECIRCLEEND...". Los parámetros de firma de función deben eliminarse o separarse con espacios. Corrección masiva: la expresión regular solo escanea bloques mermaid y reemplaza [label(args)] por [label args] (elimina paréntesis, convierte comas en espacios).
9. Los agentes secundarios son propensos a errores con rutas relativas entre módulos: al escribir enlaces entre módulos, los agentes secundarios calculan mal el nivel ../.. (por ejemplo, Gestión de Transacciones/Registro de Transacciones/ apunta a Datos de Mercado/Gestión de Favoritos/ y debería ser ../../Datos de Mercado/Gestión de Favoritos/_index.md en lugar de ../Gestión de Favoritos/). La verificación final debe ejecutar un script de validación de enlaces bidireccionales para listar los enlaces rotos y corregirlos uno por uno.
10. Verificación final triple: tras la actualización, ejecutar ① script de integridad de enlaces bidireccionales (recorrer todos los .md, analizar las rutas relativas de [[...]] y verificar que el destino existe) ② escaneo de paréntesis mermaid ③ recuento de residuos pendientes (grep -rl "Estado: Pendiente" | wc -l debe ser 0); actualizar las estadísticas del README antes de la entrega.

Guía de Operación para Actualización Masiva de Tarjetas Esqueleto

Cuando en knowledge/ ya existen muchas tarjetas esqueleto que deben actualizarse:

1. Estadísticas restantes: grep -rl "Estado: Pendiente" knowledge/*/ | wc -l   (desglosado por área)
2. Asignar agentes secundarios en paralelo por área (cada prompt debe incluir: ruta absoluta del ejemplo de plantilla, regla de hierro de mermaid,
   requisitos de inspección de código "al menos 1-2 nombres de función reales + número de línea, si no se encuentra, marcar como pendiente de localización, no inventar", formato del informe de salida)
3. El agente principal revisa periódicamente: find archivos con mtime reciente / grep número restante de pendientes; si se estanca, toma el control
4. Verificación final: script de validación de enlaces bidireccionales + escaneo de paréntesis mermaid + recuento de pendientes a cero
5. Actualizar estadísticas del README y números de estadísticas en los _index de cada nivel

Recursos

• business-knowledge-graph-generator/references/templates.md: Especificaciones de plantilla L1~L4 (deben seguirse obligatoriamente)