MinorBaek/wiki-ingest-book

Was macht wiki-ingest-book?

Lies vor der ersten Aufnahme docs/GOTCHAS.md im Kit (betriebliche Fallstricke, einschließlich Seitenversatz-Kalibrierung für Bücher).

Erweitert das LLM-Wiki-Aufnahmemuster auf akademische Bücher. Bücher sind kontextlastig und können nicht auf einmal aufgenommen werden, daher verwendet diese Fähigkeit einen zweiphasigen Ansatz: eine Buchübersicht zuerst, dann Kapitel bei Bedarf.

Rolle und Grenzen

Tut: Erstellt Buchnotizen, erstellt Kapitelnotizen, propagiert Erkenntnisse zu Konzept- und Methodennotizen, aktualisiert den Index und das Logbuch.

Tut NICHT: Liest ein ganzes Buch in einem Durchgang (Risiko der Kontextbegrenzung), erfindet Metadaten oder Kapiteltitel oder dupliziert den Papieraufnahme-Workflow (Kapitel folgen denselben Konzeptpropagationsregeln wie Papiere).

Wo die Dinge leben

Pfade stammen aus wiki.config.json (siehe wiki-ingest). Bücher und Kapitel leben in <wiki_root>/books/. Vorlagen: templates/book.md und templates/chapter.md. Der Ordner, der Ihre PDF-Bibliothek enthält, ist pdf_library_dir in der Konfiguration.

Verwandte Fähigkeiten

• wiki-ingest: teilt die Entscheidungsregeln für den Anfangsstatus und die field_titlecase_map, die für das Index-Routing verwendet wird.
• wiki-lint: nach jeder Kapitelaufnahme ausführen. Prüfung 8 (chapters_ingested-Sync) und Prüfung 9 (Kapitel book:-Frontmatter) erkennen die häufigsten Buchaufnahme-Abweichungen.

Erforderliche Verträge (müssen nach jeder Aufnahme gelten)

1. Jede Kapitelnotiz unter books/{book}_ChNN.md MUSS im Frontmatter book: "[[{book_basename}]]" enthalten, und das Ziel muss in einer vorhandenen Buchnotiz aufgelöst werden. Nach dem Schreiben überprüfen; falls fehlend, wird es von wiki-lint Prüfung 9 markiert.
2. Jede Kapitelaufnahme MUSS die Kapitelnummer an die chapters_ingested:-Liste der übergeordneten Buchnotiz anhängen. Nach dem Anhängen {book}_Ch*.md auflisten und bestätigen, dass die beiden Mengen übereinstimmen; andernfalls markiert wiki-lint Prüfung 8 die Abweichung.
3. Anfangsstatus folgt der wiki-ingest-Statustabelle: stub für definitionsmäßige, draft in Bearbeitung, und eine Kapitelnotiz erreicht final mit 2 oder mehr belegten Erkenntnissen (ein Kapitel ist selbst eine Quelle). Abgeleitete Konzept- und Methodennotizen folgen der strikten Beförderungsregel: final benötigt N verschiedene Quellenwerke (min_distinct_sources_for_final, Standard 2), daher bleibt ein nur aus diesem einen Buch aufgebautes Konzept draft, bis eine zweite unabhängige Quelle es bestätigt.
4. Index-Routing verwendet field_titlecase_map, um neue Konzepte und Methoden unter dem korrekten Titel-Schreibweise-Feld-Unterabschnitt zu platzieren, niemals in einem datierten Sammelblock.

Präambel (immer, vor Modus A oder Modus B)

1. Lies WIKI_SCHEMA.md.
2. Lies die Vorlage: Modus A verwendet templates/book.md; Modus B verwendet templates/chapter.md (und templates/book.md als Referenz).

Werkzeuge: Verwende die Dateiwerkzeuge des Hosts (Read/Write/Edit) für alle Tresor-Schreibvorgänge.

---

Lokale PDF-Auflösung (bevorzugt für Volltext)

Standardordner: pdf_library_dir in der Konfiguration (PDF-Speicher Ihres Referenzmanagers). Extraktor: pdftotext (poppler) oder, für bessere Tabellentreue, docling. Führe pdftotext immer mit -enc UTF-8 aus.

Lokalisieren Sie das PDF, indem Sie den Autor auflisten und greppen, NICHT mit einem Glob-Werkzeug und NICHT mit find -iname "*<autor>*"; beide haben dokumentierte falsch-negative Ergebnisse für Dateien, die auf einigen Dateisystemen existieren: find "<pdf_library_dir>" -iname "*.pdf" | grep -i <erster_autor_nachname>. Erweitern Sie das Stammverzeichnis auf die gesamte Bibliothek, wenn der erste Durchlauf leer ist (Bücher leben auch in thematischen Unterordnern). Genau 1 Treffer: verwenden. 0 oder mehr als 1: Fragen Sie den Benutzer nach dem genauen Pfad. Wenn das auch fehlschlägt: Fallback auf den Volltext des Referenzmanagers.

Der vollständige Auflösungsalgorithmus, die lokale-volltext-Kaskade und die MCP-Entscheidungstabelle, die Erkennung gescannter PDFs und die Gefahr nicht-ASCII-Dateinamen sind in references/BOOK-INGEST-WORKFLOW.md (Abschnitte 1 und 1bis). Lesen Sie es vor der ersten Extraktion eines neuen Buches. Der untenstehende Körper behält nur die Befehle, die für jedes Kapitel verwendet werden.

Extraktionsbefehle

• Inhaltsverzeichnis / Übersicht (Modus A): pdftotext -enc UTF-8 -f 1 -l 20 "<pfad>" - (erste 20 Seiten, stdout).
• Kapitelbereich (Modus B): pdftotext -enc UTF-8 -f <pdf_start> -l <pdf_end> "<pfad>" -. -f/-l nehmen PDF-Seitennummern, nicht Buchseitennummern; konvertieren Sie aus dem Inhaltsverzeichnis mit dem Versatz (nächster Abschnitt).
• Schreiben des Extrakts in eine Datei, die Sie lesen werden: Ein langer Kapitelausschnitt kann als Datei einfacher sein als als stdout. Schreiben Sie ihn innerhalb des Projekts (z.B. _temp/{book}_Ch{NN}.txt), nicht in ein betriebssystemspezifisches /tmp, das das Read-Werkzeug nicht öffnen kann (Git Bash unter Windows bildet /tmp auf einen Ort ab, den Windows-Werkzeuge nicht sehen können).

Seitenversatz-Kalibrierung (Buchseiten sind nicht PDF-Seiten)

Das Inhaltsverzeichnis eines Buches listet Buch-Seitennummern auf; pdftotext -f/-l adressiert PDF-Seiten. Sie unterscheiden sich um einen Versatz (Frontmatter, Tafeln), der nichtlinear durch das Buch wächst (Abbildungen, Tabellen, Teilteiler). Das Übergeben von Inhaltsverzeichnisnummern direkt an pdftotext extrahiert die falschen Seiten, der häufigste Zeitfresser bei Kapitelaufnahmen. Kalibrieren Sie einmal pro Buch, bevor Sie ein Kapitel extrahieren:

1. Wähle ein Kapitel mit einer bekannten Buch-Startseite. Schätze pdf_start = buch_seite + offset_schaetzung (Frontmatter sind oft 20 bis 60 Seiten).
2. Extrahiere nur seine erste Seite und bestätige, dass der Kapiteltitel erscheint. Passe um bis zu 5 Seiten an, bis er passt.
3. Notiere den kalibrierten Versatz in der Buchnotiz (z.B. > [!note] PDF-Versatz: Buch_S + N = PDF_S (Zone: Teil X) in der Nähe des Inhaltsverzeichnisses), damit spätere Kapitel ihn wiederverwenden.
4. Kalibriere bei langen Büchern pro Zone oder Teil neu: Ein einzelner fester Versatz driftet (z.B. +36 bei Kap. 3 und +56 bei Kap. 21 in einem Lehrbuch). Bei PDFs mit Textebene ergibt das Aufteilen des Textes auf Seitenumbrüche eine schnelle Seitenkarte mit genauen Startseiten.

---

Modus A: Buchübersicht

Auslöser: /wiki-ingest-book [Titel]

1. Im Referenzmanager auflösen: Suche nach Titel, dann Metadaten abrufen (Titel, Autoren, Herausgeber, Jahr, Verlag, ISBN, Auflage, DOI, Citekey).
   • Jahr-Suffix-Citekey-Falle (mehrbändig oder Teilserie): Ein Better BibTeX-Citekey wie ...2019a / ...2019b bildet NICHT zuverlässig Teil 1 versus Teil 2 einer Serie mit gleichem Autor und Jahr ab (das Suffix ist eine Disambiguierungsreihenfolge, keine Bedeutung). Bestätige immer den tatsächlichen Titel (und Untertitel oder "Teil N") aus den Metadaten, bevor du die Notiz benennst oder darauf vertraust, welchen Band du hast.
2. Volltext für das Inhaltsverzeichnis auflösen (Kaskade; siehe "Lokale PDF-Auflösung"):
   • Primär: pdftotext -enc UTF-8 -f 1 -l 20 "<lokaler_pfad>" - (etwa 3 bis 8k Token).
   • Fallback 1: Volltext des Referenzmanagers, nur wenn das lokale PDF NICHT verfügbar ist UND die Ausgabe unter 2.000 Wörtern liegt.
   • Fallback 2: Den Benutzer bitten, das Inhaltsverzeichnis einzufügen; als "Quelle: vom Benutzer bereitgestellt" kennzeichnen.
   • Fallback 3: Modellwissen für bekannte Lehrbücher; jeden Eintrag mit [!note] kennzeichnen.
3. Dateinamen bestimmen: Erstautor_Jahr_Schlusselwort.md (Nachname des ersten Autors, nur ASCII; Schlüsselwort ist 1 bis 3 Wörter zum Hauptthema des Buches). Wenn books/{dateiname}.md existiert, an Ort und Stelle aktualisieren.
4. Buchnotiz erstellen oder aktualisieren unter books/{dateiname}.md aus templates/book.md. Setze last_verified auf das heutige Datum.
5. Inhaltsverzeichnis aus Schritt 2 füllen. Bei Unsicherheit Kapitel mit ? kennzeichnen und die Einschränkung notieren.
6. 3 bis 5 übergeordnete Themen extrahieren (nur Buchebene, keine kapitelspezifischen Behauptungen). Leichte Propagierung: concepts/-Notizen nur aktualisieren, wenn das Thema für eine Forschungslinie zentral ist UND 2 oder mehr Wiki-Papiere es bereits berühren; andernfalls nur in der Buchnotiz auflisten. Ein Thema, das eine Notiz erreicht, folgt der Evidenztabellenregel: Modus B Schritte 6b und 8b.
7. Governance-Prüfung: Die Forschungslinien-Zuordnung und Konzept-versus-Methode-Routing aus wiki-ingest Schritt 5 anwenden. Auf Übersichtsebene nur notieren, welche Kapitel wahrscheinlich Methodennotizen versus Konzeptnotizen produzieren; die vollständige Propagierung erfolgt in Modus B.
8. index.md: Wenn der Index Bases-Ansichten einbettet, KEINEN Bucheintrag hinzufügen; nur den ## Quick Stats-Zähler "Bücher (aufgenommen)" erhöhen, wenn dies eine neue übergeordnete Buchaufnahme abschließt. Im manual-Modus den Eintrag hinzufügen. Nie einen eingefrorenen Legacy-Index berühren.
9. An log.md anhängen: ## [YYYY-MM-DD] ingest-book | {Titel}: Übersicht.
10. Bericht: Pfad der Buchnotiz, identifizierte Themen und welche Kapitel für eine tiefgehende Aufnahme verfügbar sind (/wiki-ingest-book [Titel] > Kapitel N).

---

Modus B: Kapitelaufnahme

Auslöser: /wiki-ingest-book [Titel] > Kapitel N (oder > Kapitel: [Kapiteltitel])

1. Die vorhandene Buchnotiz lesen unter books/Erstautor_Jahr_Schlusselwort.md.

   • Wenn sie nicht existiert: Anhalten. Zuerst Modus A ausführen, dann wiederholen.
   • Wenn das Kapitel nicht im Inhaltsverzeichnis aufgeführt ist: Eine Zeile mit status: pending anhängen, im Abschlussbericht notieren, fortfahren.
   • Wenn das Kapitel bereits als ingested markiert ist: Mit dem Benutzer bestätigen, bevor überschrieben wird (Standard: an Ort und Stelle aktualisieren, vorhandene [[Wikilinks]] beibehalten).

2. Kapitelinhalt auflösen (Kaskade; siehe "Lokale PDF-Auflösung"):

   • Den Seitenbereich des Kapitels aus dem Buchnotiz-Inhaltsverzeichnis nehmen und Buchseiten mit dem aufgezeichneten Versatz in PDF-Seiten umwandeln. Den Benutzer nur fragen, wenn die Seitenzahlen des Inhaltsverzeichnisses selbst unbekannt sind.
   • Primär: pdftotext -enc UTF-8 -f <pdf_start> -l <pdf_end> "<lokaler_pfad>" - (ein typisches Kapitel hat 1k bis 8k Token).
   • Fallback 1: Wenn das Kapitel ein bookSection-Eintrag mit eigenem Bibliothekseintrag ist, den Volltext dieses Eintrags verwenden.
   • Fallback 2: Volltext des gesamten Buches aus dem Referenzmanager, nur wenn das lokale PDF NICHT verfügbar ist UND das Buch unter 5.000 Wörtern hat.
   • Fallback 3: Den Benutzer bitten, den Kapiteltext einzufügen.
   • Fallback 4: Modellwissen, mit [!warning] bei jeder Behauptung. Es erreicht nie eine Konzept- oder Methodennotiz und erhält kein Siegel.

3. Kapiteldateiname: Erstautor_Jahr_Schlusselwort_KapNN.md (z.B. Knuttgen_1987_Strength_Kap03.md).

4. Kapitelnotiz erstellen unter books/{kapitel_dateiname}.md aus templates/chapter.md. Setze last_verified auf das heutige Datum.

   • Erforderlicher Vertrag: Im Frontmatter book: "[[{elternbuch_basename}]]" ausgeben und überprüfen, ob es aufgelöst wird. Wenn nicht, wurde das Elternbuch nicht aufgenommen: Zuerst Modus A ausführen.
   • Anfangsstatus: Die wiki-ingest-Statustabelle anwenden. Eine Gerüst-Kapitelnotiz, die nur den Inhaltsverzeichniseintrag gefüllt hat, ist stub; eine Kapitelnotiz mit mindestens 2 belegten Erkenntnissen ist final.
   • Evidenzstufe: evidence_level: textbook standardmäßig. Auf SR-MA oder SR nur überschreiben, wenn das Kapitel selbst eine eigenständige systematische Übersichtsarbeit oder Metaanalyse ist. Die Messqualität bleibt inline in den Erkenntnissen, niemals im Frontmatter.

5. 3 bis 8 Konzepte und 1 bis 4 Methoden extrahieren: Gleiche Extraktionsregeln wie wiki-ingest (siehe references/BOOK-INGEST-WORKFLOW.md).

6. Governance-Prüfung: Gleiche Forschungslinien-Zuordnung und Konzept-versus-Methode-Routing wie wiki-ingest Schritt 5. Für dieses Kapitel explizit entscheiden: Konzeptnotizen (empirische Erkenntnisse), Methodennotizen (Rahmenwerke, Protokolle) oder beides. Allgemeiner pädagogischer Inhalt liefert typischerweise nur Methodennotizen; erzwinge keine Konzepterstellung für Inhalte, die in methods/ gehören. 6b. Evidenztabelle und -prüfung, vor jeder Propagierung: wiki-ingest Schritte 5b und 5c auf dieses Kapitel anwenden, mit einer Entwurfstabelle für das Kapitel. Drei Ergänzungen für Bücher:

   • Die Seitenspalte gibt sowohl die PDF-Seite als auch die gedruckte Seite an, und der Kapiteltitel wird auf der Seite bestätigt, auf der Sie landen (ein falscher Versatz zitiert ein anderes Kapitel).
   • Ein Lehrbuch erhält die strenge Lesart: Jeden Mechanismus und Marker, den die Erkenntnis nennt, überprüfen. Eine Liste von Ursachen oder Kriterien eines Kapitels ist kein Beleg für jedes Element, es sei denn, das Element ist auf der Seite.
   • Sage, wer spricht: Eine Behauptung, die das Kapitel an einen anderen Autor weitergibt, wird geschrieben als "X, berichtet von [[Kapitel]]", und eine klinische Meinung eines Kapitels wird nicht als Studienergebnis geschrieben. Nur Zeilen, die bestehen, gehen zu Schritten 7 und 8. Zeichen von der gerenderten Seite lesen.

7. Zu Konzeptnotizen propagieren, identisch zur Papieraufnahme: Die Erkenntnis mit einem [[Kapitelnotiz]]-Rücklink zur vorhandenen concepts/{Konzept}.md anhängen oder eine neue aus templates/concept.md unter denselben Erstellungsregeln wie wiki-ingest/references/CONCEPT-PROPAGATION.md erstellen.

8. Zu Methodennotizen propagieren, falls zutreffend. 8b. Die Kapitelnotiz versiegeln: wiki-ingest Schritt 8b mit dem Kapitel als Werk anwenden (die Überprüfung in source_verification aufzeichnen: Bibliotheksschlüssel, ISBN, Kapitel und überprüfte Seiten, Datum).

9. Vorwärts-Referenz-Gerüste (automatisch): Nachdem der Kapiteltext geschrieben ist, materialisiere alle Vorwärts-Referenzen auf Geschwisterkapitel, die noch nicht existieren:

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

   Das Skript scannt das gerade aufgenommene Kapitel nach [[{book}_KapNN]]-Links (alias-bewusst), liest die Tabelle ## Inhaltsverzeichnis des Buch-Knotenpunkts, um Titel und Seiten für jedes fehlende Kapitel wiederherzustellen, leitet DOI und Citekey aus dem Knotenpunkt-Frontmatter ab ({doi_basis}_{N}, {citekey_basis}_ch{N}) und schreibt UTF-8-Gerüste mit status: stub. Vorwärts-Referenzen ohne eine Inhaltsverzeichniszeile werden übersprungen und gemeldet (manuelle Aufnahme erforderlich). Aktionen werden in _temp/wiki_ingest_book_stubs_created.md protokolliert. wiki-lint Prüfung 8 respektiert status: stub, sodass diese Gerüste chapters_ingested NICHT desynchronisieren, das die kanonische Liste der tatsächlich aufgenommenen Kapitel bleibt.

   ⚠️ Schreibe niemals einen Aufnahme-Status-Marker in den Prosatext eines Kapitels. Kein *(Aufnahme ausstehend)*, kein "noch nicht aufgenommen" neben einem Geschwisterkapitel, in ## Verwandte Papiere, in einem siehe auch-Aufzählungspunkt oder irgendwo anders. Der Aufnahmestatus ist veränderlich und hat genau ein Zuhause: die Zeile ## Inhaltsverzeichnis des Buch-Knotenpunkts, die Schritt 11 von pending auf ingested umstellt. Ein Marker, der in den Prosatext kopiert wird, dupliziert eine veränderliche Tatsache an einen unveränderlichen Ort: Das Geschwister wird aufgenommen, das Inhaltsverzeichnis aktualisiert, und der Prosa behauptet für immer das Gegenteil. In einer Überprüfung produzierte dies 68 veraltete Markierungen in 58 Notizen, jede Abhängigkeit bereits aufgenommen. Keine Lint-Prüfung sieht diese Klasse, weil jede Datei für sich kohärent bleibt und der Widerspruch nur zwischen Dateien existiert. Verlinke einfach das Geschwister; wenn ein Werk außerhalb des Wikis ist, nenne es im Klartext.

10. Bericht über fehlende Konzepte (automatisch): Nach dem Skript für Vorwärts-Referenzgerüste wird _temp/wiki_ingest_book_concepts_missing.md mit einer Aufzählung der Konzepte und Methoden geschrieben, die dieses Kapitel einführt, aber noch nicht im Wiki existieren (von Schritt 7 neu erstellt oder in Schritt 6 markiert). Der Bericht ist ein praktischer Merkzettel, wird aber nicht automatisch befolgt: Der Benutzer kann das Kapitel zuerst prüfen und dann entscheiden, ob die neuen Konzepte einen vorläufigen concept/-Eintrag verdienen. Das Log gibt dieses Kapitel als eingefrorene Referenz aus, sodass eine spätere Papieraufnahme die Lücke automatisch füllen kann.11. Buch-Knotenpunkt aktualisieren: chapters_ingested: anhängen, last_verified: auf heute setzen, die Zeile im Inhaltsverzeichnis von pending auf ingested setzen. Niemals manuell in die ## Verwandte Papiere des Elternbuchs schreiben (sie sind entweder von der Aufnahme eines Geschwisterkapitels abgeleitet oder im Elternbuch kein Thema).12. Zu meta/changelog.md: Einen Eintrag mit Pfad der Kapitelnotiz, Inhaltsverzeichnis-Statuswechsel und einem 1-Satz-Überblick der konzeptionellen Erkenntnisse hinzufügen.13. An log.md anhängen: ## [YYYY-MM-DD] ingest-book | {Titel} > Kapitel N: {Kapiteltitel}.14. Bericht: Pfad der Kapitelnotiz, Status (z.B. final, 4 belegte Erkenntnisse), erstellte/aktualisierte Konzept- und Methodennotizen und benutzerdefinierter Aktionsbedarf (falls z.B. das Inhaltsverzeichnis nicht den Titel des Kapitels enthielt, sondern Sie ihn aus dem Volltext ableiten mussten; wenn das PDF gescannt wurde und der Text unsicher ist; wenn die Referenzmanager-ID des Kapitels von seiner ISBN abweicht).

---

Risiken / Annahmen

• Keine automatische vollständige Buchaufnahme: Ein Benutzer, der ein ganzes Buch auf einmal anfordert, wird höflich auf den zweiphasigen Ansatz hingewiesen. Das Skript für Vorwärts-Referenzgerüste sorgt dafür, dass noch nicht aufgenommene Geschwister in der Wiki-Nachbarschaft als stub sichtbar sind.
• Der Versatz ist die häufigste Fehlerquelle: Das Skript mit -f/-l besteht darin, über die ersten Seiten eines Kapitels hinauszugehen (und die falsche Seite zu parsen) oder darin, nicht weit genug zu gehen (ein verwirrtes Kapitel). Jedes Kapitel beginnt auf seiner ersten Seite, nicht auf der vorherigen

[truncated for translation]