MinorBaek/wiki-ingest-book

¿Qué hace wiki-ingest-book?

Antes de la primera ingestión, lea docs/GOTCHAS.md en el kit (problemas operativos, incluida la calibración del desfase de páginas para libros).

Extiende el patrón de ingestión de LLM-wiki a libros académicos. Los libros tienen mucho contexto y no pueden ingerirse de una sola vez, por lo que este skill utiliza un enfoque de dos fases: primero una descripción general del libro y luego los capítulos bajo demanda.

Rol y límites

Hace: crear notas de libro, crear notas de capítulo, propagar hallazgos a notas de conceptos y métodos, actualizar el índice y el registro.

NO hace: leer un libro completo en una sola pasada (riesgo de límite de contexto), inventar metadatos o títulos de capítulos, ni duplicar el flujo de trabajo de ingestión de artículos (los capítulos siguen las mismas reglas de propagación de conceptos que los artículos).

Dónde residen las cosas

Las rutas provienen de wiki.config.json (ver wiki-ingest). Los libros y capítulos residen en <wiki_root>/books/. Plantillas: templates/book.md y templates/chapter.md. La carpeta que contiene su biblioteca de PDF es pdf_library_dir en la configuración.

Skills relacionados

• wiki-ingest: comparte las reglas de decisión de estado inicial y el field_titlecase_map utilizado para el enrutamiento del índice.
• wiki-lint: ejecutar después de cada ingestión de capítulo. La comprobación 8 (sincronización de chapters_ingested) y la comprobación 9 (metadato book: del capítulo) detectan la mayoría de las desviaciones en la ingestión de libros.

Contratos requeridos (deben cumplirse después de cada ingestión)

1. Cada nota de capítulo en books/{book}_ChNN.md DEBE incluir book: "[[{book_basename}]]" en los metadatos, y el destino debe resolverse en una nota de libro existente. Verifique después de escribir; si falta, la comprobación 9 de wiki-lint lo señala.
2. Cada ingestión de capítulo DEBE agregar el número de capítulo a la lista chapters_ingested: de la nota del libro principal. Después de agregar, liste {book}_Ch*.md y confirme que los dos conjuntos coinciden; de lo contrario, la comprobación 8 de wiki-lint señala la desviación.
3. El estado inicial sigue la tabla de estados de wiki-ingest: stub solo para definiciones, draft en progreso, y una nota de capítulo alcanza final con 2 o más hallazgos con fuente (un capítulo en sí mismo es una fuente). Las notas derivadas de conceptos y métodos siguen la regla de promoción estricta: final necesita N obras fuente distintas (min_distinct_sources_for_final, por defecto 2), por lo que un concepto construido solo a partir de este libro permanece como draft hasta que una segunda fuente independiente lo corrobore.
4. El enrutamiento del índice usa field_titlecase_map para colocar nuevos conceptos y métodos en la subsección correcta del campo en Title Case, nunca en un bloque genérico con fecha.

Preámbulo (siempre, antes del Modo A o Modo B)

1. Lea WIKI_SCHEMA.md.
2. Lea la plantilla: el Modo A usa templates/book.md; el Modo B usa templates/chapter.md (y templates/book.md como referencia).

Herramientas: use las herramientas de archivo del anfitrión (Leer/Escribir/Editar) para todas las escrituras en la bóveda.

---

Resolución local de PDF (preferida para texto completo)

Carpeta predeterminada: pdf_library_dir en la configuración (almacenamiento de PDF de su gestor de referencias). Extractor: pdftotext (poppler) o, para una mejor fidelidad de tablas, docling. Siempre ejecute pdftotext con -enc UTF-8.

Localice el PDF enumerando y filtrando por el autor, NO con una herramienta glob y NO con find -iname "*<autor>*"; ambos tienen falsos negativos documentados para archivos que existen en algunos sistemas de archivos: find "<pdf_library_dir>" -iname "*.pdf" | grep -i <apellido_del_primer_autor>. Amplíe la raíz a toda la biblioteca si la primera pasada está vacía (los libros también residen en subcarpetas temáticas). Exactamente 1 coincidencia: úsela. 0 o más de 1: pregunte al usuario la ruta exacta. Si eso también falla: recurra al texto completo del gestor de referencias.

El algoritmo de resolución completo, la cascada de texto completo local primero y la tabla de decisión MCP, la detección de PDF escaneado y el peligro de nombres de archivo no ASCII están en references/BOOK-INGEST-WORKFLOW.md (secciones 1 y 1bis). Léalo antes de la primera extracción de un libro nuevo. El cuerpo a continuación mantiene solo los comandos utilizados para cada capítulo.

Comandos de extracción

• TOC / descripción general (Modo A): pdftotext -enc UTF-8 -f 1 -l 20 "<ruta>" - (primeras 20 páginas, salida estándar).
• Rango de capítulo (Modo B): pdftotext -enc UTF-8 -f <inicio_pdf> -l <fin_pdf> "<ruta>" -. Las opciones -f/-l toman números de página de PDF, no números de página del libro; convierta desde la TOC con el desfase (siguiente sección).
• Escribir la extracción en un archivo que luego leerá: un fragmento largo de capítulo puede ser más fácil como archivo que como salida estándar. Escríbalo dentro del proyecto (por ejemplo _temp/{libro}_Ch{NN}.txt), no en un /tmp específico del sistema operativo que la herramienta de lectura no pueda abrir (Git Bash en Windows asigna /tmp a una ubicación que las herramientas de Windows no pueden ver).

Calibración del desfase de páginas (las páginas del libro no son páginas del PDF)

La TOC de un libro enumera números de página del libro; pdftotext -f/-l se dirige a páginas de PDF. Difieren por un desfase (materia preliminar, láminas) que crece de forma no lineal a lo largo del libro (figuras, tablas, divisores de partes). Pasar los números de la TOC directamente a pdftotext extrae las páginas incorrectas, la causa más común de pérdida de tiempo en la ingestión de capítulos. Calibre una vez por libro, antes de extraer cualquier capítulo:

1. Elija un capítulo con una página de inicio del libro conocida. Estime inicio_pdf = página_libro + desfase_estimado (la materia preliminar suele ser de 20 a 60 páginas).
2. Extraiga solo su primera página y confirme que aparece el título del capítulo. Ajuste hasta 5 páginas hasta que acierte.
3. Registre el desfase calibrado en la nota del libro (por ejemplo > [!note] Desfase PDF: pg_libro + N = pg_pdf (zona: Parte X) cerca de la TOC) para que los capítulos posteriores lo reutilicen.
4. Vuelva a calibrar por zona o Parte en libros largos: un desfase fijo único se desvía (por ejemplo +36 en el Cap. 3 y +56 en el Cap. 21 en un libro de texto). Para PDF con capa de texto, dividir el texto en saltos de página proporciona un mapa de páginas rápido con páginas de inicio exactas.

---

Modo A: Descripción general del libro

Disparador: /wiki-ingest-book [título]

1. Resuelva en el gestor de referencias: busque por título, luego obtenga metadatos (título, autores, editores, año, editorial, ISBN, edición, DOI, citekey).
   • Advertencia de citekey con sufijo de año (series de varios volúmenes o Partes): un citekey de Better BibTeX como ...2019a / ...2019b NO se asigna de manera confiable a la Parte 1 frente a la Parte 2 de una serie del mismo autor y año (el sufijo es el orden de desambiguación, no el significado). Confirme siempre el título real (y el subtítulo o "Parte N") de los metadatos antes de nombrar la nota o confiar en qué volumen tiene.
2. Resuelva el texto completo para la TOC (cascada; ver "Resolución local de PDF"):
   • Principal: pdftotext -enc UTF-8 -f 1 -l 20 "<ruta_local>" - (aproximadamente de 3 a 8 mil tokens).
   • Respaldo 1: texto completo del gestor de referencias, solo si el PDF local no está disponible Y la salida tiene menos de 2000 palabras.
   • Respaldo 2: pida al usuario que pegue la TOC; márquela como "Fuente: proporcionada por el usuario".
   • Respaldo 3: conocimiento del modelo para libros de texto conocidos; marque cada elemento con [!note].
3. Determine el nombre del archivo: PrimerAutor_Año_PalabraClave.md (apellido del primer autor, solo ASCII; la palabra clave es de 1 a 3 palabras sobre el tema principal del libro). Si books/{nombre_archivo}.md existe, actualícelo.
4. Cree o actualice la nota del libro en books/{nombre_archivo}.md a partir de templates/book.md. Establezca last_verified a la fecha de hoy.
5. Complete la TOC a partir del paso 2. Si no está seguro, marque los capítulos con ? y anote la limitación.
6. Extraiga de 3 a 5 temas de alto nivel (solo a nivel de libro, sin afirmaciones específicas de capítulos). Propagación ligera: actualice las notas de concepts/ solo si el tema es central para una línea de investigación Y 2 o más artículos de la wiki ya lo tocan; de lo contrario, solo enumérelo en la nota del libro. Un tema que llega a una nota sigue la regla de la tabla de evidencias: pasos 6b y 8b del Modo B.
7. Verificación de gobernanza: aplique la coincidencia de líneas de investigación y el enrutamiento de conceptos frente a métodos de wiki-ingest paso 5. A nivel de descripción general, solo anote qué capítulos probablemente producirán notas de método frente a notas de concepto; la propagación completa ocurre en el Modo B.
8. index.md: si el índice incrusta vistas de Bases, NO agregue una entrada de libro; solo aumente el contador ## Quick Stats "Libros (ingeridos)" cuando esto complete una nueva ingestión de libro principal. En modo manual, agregue la entrada. Nunca toque un índice heredado congelado.
9. Agregue a log.md: ## [AAAA-MM-DD] ingest-book | {Título}: descripción general.
10. Informe: ruta de la nota del libro, temas identificados y qué capítulos están disponibles para ingestión profunda (/wiki-ingest-book [título] > Capítulo N).

---

Modo B: Ingestión de capítulo

Disparador: /wiki-ingest-book [título] > Capítulo N (o > Capítulo: [título del capítulo])

1. Lea la nota del libro existente en books/PrimerAutor_Año_PalabraClave.md.

   • Si no existe: deténgase. Ejecute el Modo A primero y luego vuelva a intentarlo.
   • Si el capítulo no está listado en la TOC: agregue una fila con status: pending, anótelo en el informe final, continúe.
   • Si el capítulo ya está marcado como ingested: confirme con el usuario antes de sobrescribir (predeterminado: actualizar en el lugar, conservando los [[wikilinks]] existentes).

2. Resuelva el contenido del capítulo (cascada; ver "Resolución local de PDF"):

   • Tome el rango de páginas del capítulo de la TOC de la nota del libro y convierta las páginas del libro a páginas del PDF con el desfase registrado. Pregunte al usuario solo si los números de página de la TOC en sí son desconocidos.
   • Principal: pdftotext -enc UTF-8 -f <inicio_pdf> -l <fin_pdf> "<ruta_local>" - (un capítulo típico tiene de 1 mil a 8 mil tokens).
   • Respaldo 1: si el capítulo es un elemento bookSection con su propia entrada en la biblioteca, use el texto completo de ese elemento.
   • Respaldo 2: texto completo del libro completo desde el gestor de referencias, solo si el PDF local no está disponible Y el libro tiene menos de 5000 palabras.
   • Respaldo 3: pida al usuario que pegue el texto del capítulo.
   • Respaldo 4: conocimiento del modelo, con [!warning] en cada afirmación. Nunca llega a una nota de concepto o método y no recibe sello.

3. Nombre del archivo del capítulo: PrimerAutor_Año_PalabraClave_ChNN.md (por ejemplo Knuttgen_1987_Strength_Ch03.md).

4. Cree la nota del capítulo en books/{nombre_archivo_capitulo}.md a partir de templates/chapter.md. Establezca last_verified a la fecha de hoy.

   • Contrato requerido: emita book: "[[{nombre_base_libro_padre}]]" en los metadatos y verifique que se resuelva. Si no es así, el padre no se ingirió: ejecute el Modo A primero.
   • Estado inicial: aplique la tabla de estados de wiki-ingest. Un capítulo esqueleto con solo la entrada de la TOC completada es stub; un capítulo con al menos 2 hallazgos con fuente es final.
   • Nivel de evidencia: evidence_level: textbook por defecto. Anule a SR-MA o SR solo si el capítulo en sí mismo es una revisión sistemática o metanálisis independiente. La calidad de la medición permanece en línea en los hallazgos, nunca en los metadatos.

5. Extraiga de 3 a 8 conceptos y de 1 a 4 métodos: mismas reglas de extracción que wiki-ingest (ver references/BOOK-INGEST-WORKFLOW.md).

6. Verificación de gobernanza: misma coincidencia de líneas de investigación y enrutamiento de conceptos frente a métodos que wiki-ingest paso 5. Decida explícitamente para este capítulo: notas de concepto (hallazgos empíricos), notas de método (marcos, protocolos), o ambas. El contenido pedagógico general generalmente produce solo notas de método; no fuerce la creación de conceptos para contenido que pertenece a methods/. 6b. Tabla de evidencias y verificación, antes de cualquier propagación: aplique los pasos 5b y 5c de wiki-ingest a este capítulo, con una tabla provisional para el capítulo. Tres adiciones para libros:

   • La columna de página proporciona tanto la página del PDF como la página impresa, y el título del capítulo se confirma en la página en la que aterriza (un desfase incorrecto cita otro capítulo).
   • Un libro de texto recibe la lectura estricta: verifique cada mecanismo y marcador que el hallazgo nombra. Una lista de causas o criterios de un capítulo no es evidencia para cada elemento a menos que el elemento esté en la página.
   • Diga quién habla: una afirmación que el capítulo entrega a otro autor se escribe "X, según lo informado por [[capítulo]]", y la opinión clínica de un capítulo no se escribe como un resultado de ensayo. Solo las filas que pasan van a los pasos 7 y 8. Lea las señales de la página renderizada.

7. Propague a notas de concepto, idéntico a la ingestión de artículos: agregue el hallazgo con un enlace [[nota_capitulo]] a la nota concepts/{Concepto}.md existente, o cree una nueva a partir de templates/concept.md bajo las mismas reglas de creación que wiki-ingest/references/CONCEPT-PROPAGATION.md.

8. Propague a notas de método si corresponde. 8b. Selle la nota del capítulo: aplique el paso 8b de wiki-ingest con el capítulo como obra (registre la verificación en source_verification: clave de biblioteca, ISBN, capítulo y páginas verificadas, fecha).

9. Stubs de referencias cruzadas (automático): después de escribir el cuerpo del capítulo, materialice cualquier referencia cruzada a capítulos hermanos que aún no existan:

   python skills/wiki-ingest-book/scripts/create_forward_ref_stubs.py \
     <wiki_root>/books/{libro}_Ch{NN}.md  <wiki_root>/books/{libro}.md   [--dry-run]
   

   El script escanea el capítulo recién ingerido en busca de enlaces [[{libro}_ChNN]] (consciente de alias), lee la tabla ## Table of Contents del centro del libro para recuperar título y páginas de cada capítulo faltante, deriva DOI y citekey de los metadatos del centro ({doi_base}_{N}, {citekey_base}_ch{N}), y escribe stubs UTF-8 con status: stub. Las referencias cruzadas sin una fila en la TOC se omiten y se informan (requiere ingestión manual). Las acciones se registran en _temp/wiki_ingest_book_stubs_created.md. La comprobación 8 de wiki-lint respeta status: stub, por lo que estos stubs NO desincronizan chapters_ingested, que sigue siendo la lista canónica de capítulos realmente ingeridos.

   ⚠️ Nunca escriba un marcador de estado de ingestión en la prosa de un capítulo. Sin "(pendiente de ingestión)", sin "aún no ingerido" junto a un capítulo hermano, en ## Related Papers, en un punto de ver también, ni en ningún otro lugar. El estado de ingestión es mutable y tiene exactamente un hogar: la fila ## Table of Contents del centro del libro, que el paso 11 cambia de pending a ingested. Un marcador copiado en la prosa duplica un hecho mutable en un lugar inmutable: el hermano se ingiere, la TOC se actualiza y la prosa sigue afirmando lo opuesto para siempre. En una auditoría, esto produjo 68 marcas obsoletas en 58 notas, cada dependencia ya ingerida. Ninguna verificación de lint ve esta clase, porque cada archivo permanece coherente consigo mismo y la contradicción existe solo entre archivos. Simplemente enlace al hermano; si un trabajo está fuera de la wiki, nómbrelo en texto plano.

10. Informe de concepto faltante (automático): después del s...

[truncado para traducción]