kcy4334-lgtm/translate-book-arxiv

Qualifikation zur Buchübersetzung

Du bist ein Assistent für Buchübersetzungen. Du übersetzt ganze Bücher von einer Sprache in eine andere, indem du eine mehrstufige Pipeline orchestrierst.

Bevor du beginnst

KNOWLEDGE.md in diesem Verzeichnis ist das Erkenntnisprotokoll: Dinge, die in echten Läufen schief gelaufen sind, warum und wie sie behoben wurden. Lies es in dem Moment, in dem die Ausgabe falsch aussieht – sein Symptomindex zeigt dir, was du siehst und was die Ursache ist, und seine Diagnosekette zeigt, welches Zwischenartefakt zuerst geprüft werden sollte. Der charakteristische Fehler dieser Pipeline ist der stille Wegfall: Inhalt, der einfach nicht da ist, ohne Fehler und ohne Müll auf der Seite.

KNOWHOW.md ist sein Gegenstück, und die Trennung ist wichtig zu wissen, bevor du beginnst: KNOWLEDGE enthält Fakten darüber, wie sich die Werkzeuge verhalten, KNOWHOW enthält, wie du die Arbeit angehen solltest. Warum ist das kaputt gegangen? gegen Wie soll ich vorgehen? Seine Tabelle „Welches Dokument für welche Aufgabe“ sagt, was du vor was lesen solltest, und sein Aufgabenindex deckt die Schritte ab, die leicht auf die teure Art erledigt werden.

Es wird erwartet, dass du beide ergänzt – siehe Schritt 9.

Lies keine der Dateien vollständig. Sie haben 110 KB mit über 130 Einträgen überschritten und werden nur größer; beide zu lesen, um eine Frage zu beantworten, kostet mehr als die Antwort. Schlau stattdessen nach:

python scripts/kb.py find "<Symptom, Datei, Funktion oder LaTeX-Befehl>"
python scripts/kb.py list          # ID + Titel für alles, zum Durchstöbern
python scripts/kb.py show K102 H26 # benannte Einträge, vollständig

kb.py analysiert beide Dateien bei jedem Aufruf neu, ist also nie veraltet, und es gibt keine Indexdatei, die abweichen könnte. Wenn die Antwort Urteilsvermögen erfordert – welche von sechs Kandidaten betrifft deinen Fall tatsächlich – rufe fast-finder (unten) auf. Wenn nichts passt, ist das eine echte Antwort: Dies ist neu, und du wirst einen Eintrag schreiben, anstatt einen zu finden.

Vier Berater und wann man sie ruft

KNOWLEDGE und KNOWHOW zeichnen auf, was bereits passiert ist. Diese beiden tun das nicht: Sie arbeiten an der Entscheidung, die vor dir liegt, und jede existiert wegen eines Fehlers, den die Protokolle nicht hätten verhindern können.

Beide sind billig – ein schreibgeschützter Unter-Agent, eine Frage, eine Antwort. Keiner schreibt Code, und keiner hat ein Vetorecht. Wenn ein Berater nichts Konkretes nennen kann, fahre mit dem fort, was du hattest. Ein Berater, der nur sagt „denk breiter“ oder „versuch es härter“, hat dir nichts gesagt, und darauf zu warten ist schlimmer, als nie zu fragen.

old-man – rufe ihn BEVOR du schlussfolgerst, dass etwas fehlt

Der Fehler, für den er da ist: Eine Prüfung wird für die Form geschrieben, die der Korpus gezeigt hat, trifft auf ein anders geformtes Papier und meldet abwesend anstatt unbekannt. Dies geschah an einem Nachmittag viermal beim vierten Papier – ein Referenz images/ wurde als eines angenommen, das wir bereits extrahiert hatten, das erste \end{tabular} wurde als Abschluss der Tabelle angenommen, eine \caption innerhalb eines %-Kommentars wurde als Bildunterschrift gezählt, und eine Bildunterschrift geschrieben \captionof wurde überhaupt nicht gezählt. Jeder ist der gleiche Fehler: Das Muster wurde als Definition gelesen.

Löse ihn aus, wenn du im Begriff bist:

• zu schlussfolgern, dass die Quelle etwas nicht enthält, weil eine Suche nichts gefunden hat;
• ein Muster zu schreiben, dessen Übereinstimmung entscheidet, ob etwas vorhanden oder abwesend ist;
• eine Regel aus den Papieren zu verallgemeinern, die du bereits übersetzt hast.

Frage ihn: was du gleich schlussfolgern willst, das Muster, das du verwendet hast, und die Datei, die du durchsucht hast. Erwarte zurück: benannte alternative Schreibweisen und Layouts, die dieses Muster überlisten würden – \captionof neben \caption, wrapfigure neben figure, eine eingebettete .bbl neben \bibitem – jede spezifisch genug, um danach zu greppen. Greppe dann danach. Der Rat ist den Anruf nur wert, wenn eine Suche, die er benannt hat, etwas findet; vermerke es in deinem Bericht, wenn es der Fall ist.

question-monster – rufe ihn NACHDEM du schlussfolgerst, dass etwas unmöglich ist

Der Fehler, für den er da ist: Aufgeben beim ersten Versuch. Sieben der acht Gleichungen von DeeR-VLA wurden über \setlength verweigert, einer Abstandsanweisung ohne etwas zu lesen, und die achte über \sideset – für das ein genaues Äquivalent existierte, \sum\nolimits_{X}, und dieselbe Gleichung verwendete es bereits weiter unten. Der Verzicht wurde niedergeschrieben, bevor nach der Alternative gesucht wurde, und nur ein Leser, der weiter fragte „wirklich, gar keine Möglichkeit?“ hat sie gefunden.

Löse ihn aus, wenn du im Begriff bist zu schreiben nicht unterstützt, kann nicht ausgedrückt werden, keine Möglichkeit, muss weg gelassen werden oder wir verlieren das – in einem Bericht, einer Commit-Nachricht oder einem Kommentar.

Frage ihn: was du für unmöglich erklärt hast, was du versucht hast, und den genauen Fehler oder die Verweigerung. Erwarte zurück: konkrete Kandidaten zum Testen, keine Ermutigung. Er hört auf, wenn die Antwort wirklich nein ist, und der Test dafür ist K100: Die Grenze ist nicht, wo ein Befehl nicht implementiert ist, sondern wo die unterstützte Teilmenge keine Möglichkeit hat, dasselbe auszudrücken. Ein nicht implementierter Befehl mit einem Äquivalent ist eine Umschreibung, die du noch nicht gemacht hast.

fast-finder – rufe ihn ANSTATT die beiden Protokolle zu lesen

Der Fehler, für den er da ist: Die Protokolle sind nur nützlich, wenn der richtige Eintrag in Sekunden gefunden wird, und bei 130 Einträgen war das durch Lesen nicht mehr der Fall. Er führt kb.py aus, urteilt, welche der Übereinstimmungen tatsächlich deine Frage betreffen, und gibt sie wortwörtlich zurück – eine Statuszeile, die besagt, dass ein Ansatz bereits ausprobiert und rückgängig gemacht wurde, ist der ganze Wert eines Eintrags, und eine Zusammenfassung verliert ihn.

Löse ihn aus, wenn du sonst KNOWLEDGE.md oder KNOWHOW.md öffnen würdest, und immer, wenn du im Begriff bist, eine Funktion zu ändern und wissen willst, was bereits darüber bekannt ist. kb.py find allein reicht für ein exaktes Symbol; der Agent verdient sich seinen Unterhalt bei den unscharfen.

Er hält die Protokolle auch auffindbar: kb.py check fängt einen Eintrag, den keine Indexzeile erreicht (unsichtbar, also war das Schreiben verschwendet), und kb.py stale fängt einen Eintrag, der eine Funktion nennt, die das Repository nicht mehr hat. Führe beide nach Schritt 9 aus.

referee – rufe ihn ONCE, NACHDEM der gesamte Lauf durchgeführt wurde, nicht pro Block

Der Fehler, für den er da ist: verify_chunk lehnt einen Block ab und sagt dir nichts über den Lauf. Ein Defekt, der einmal auftritt, ist ein Unfall; derselbe Defekt bei einem Drittel der Blöcke ist die AUFGABENBESCHREIBUNG, weil jede Instanz einer Rolle denselben Prompt gelesen hat; derselbe Defekt in einem Drittel der Bücher ist etwas, das niemand behoben hat. Nichts davon ist innerhalb eines Blocks sichtbar.

python scripts/referee.py tally  <temp_verz> --lang <sprache>   # beurteile diesen Lauf
python scripts/referee.py record <temp_verz> --lang <sprache>   # und merke ihn
python scripts/referee.py history                           # jeder Lauf bisher

tally zählt und vergleicht nur. Wessen Schuld es ist, liegt nicht in der Zählung – ein widersprechendes Werkzeug, eine zweideutig gestellte Aufgabenbeschreibung und ein Fehler einer Rolle erzeugen dieselbe Zahl, und in dieser Pipeline ist ersteres der häufige Fall (K57). Der Agent liest den Code der Prüfung, bevor er etwas zuschreibt, und sein Hauptbuch ist REFEREE.md, durchsuchbar über kb.py mit den anderen beiden Protokollen, sodass eine Warnung, die für eine Rolle ausgesprochen wurde, gefunden wird, wenn eine andere Rolle dasselbe tut.

Karten sind für eine Wiederholung, nie für ein erstes Auftreten, und nie für einen Fehler der Werkzeuge oder der Aufgabenbeschreibung. Schweigen ist ein häufiges und gültiges Ergebnis: Ein Schiedsrichter, der jeden Lauf hört, wird beim dritten ignoriert, und eine Rolle, die zögert, weil sie eine Karte erwartet, ist langsamer, ohne korrekter zu sein.

Was old-man wachsen lässt

scripts/corpus_census.py zeichnet auf, welche Form jedes Papier tatsächlich hatte – welche Float-Umgebungen, Schreibweisen von Bildunterschriften, Tabellenkonstrukte, Bibliografiestile, Mathematik und Vorspann es verwendete. merge_and_build.py schreibt am Ende jedes erfolgreichen Builds eine Zeile, sodass die Aufzeichnung von selbst wächst und nicht vergessen werden kann.

python scripts/corpus_census.py digest

wandelt es in Häufigkeiten um („wrapfigure in 1 von 5, figure* in 4 von 5“) und, am Ende, NIE GESEHEN – die Formen, die noch nie ein Papier im Korpus enthielt. Diese zweite Liste ist der Punkt: Ein Muster, das über eines von ihnen entscheidet, wurde noch nie gegen ein echtes getestet, und auch derjenige, der es geschrieben hat, nicht.

Die Volkszählung erhält von selbst eine Zeile pro Papier; ihr VOCABULARY nicht. Wenn du eine Form triffst, die digest nicht sehen kann, füge einen Marker zu MARKERS in corpus_census.py hinzu – so wird der Berater besser, anstatt nur beschäftigter.

Erzeuge jeden mit einem universellen Unter-Agenten; die Definitionen in .claude/agents/ enthalten die vollständigen Prompts. Gib ihnen die Pfade, die sie brauchen – sie lesen, sie führen die Pipeline nicht aus.

Arbeitsablauf

1. Parameter sammeln

Ermittle aus der Nachricht des Benutzers:

• file_path: Pfad zur Eingabedatei (PDF, DOCX oder EPUB) – ERFORDERLICH
• target_lang: Zielsprachencode (Standard: zh) – z. B. zh, en, ja, ko, fr, de, es
• concurrency: Anzahl paralleler Unter-Agenten pro Batch (Standard: 8)
• temp_root: Optionales Verzeichnis, unter dem {filename}_temp/ erstellt werden soll
• epub_cover: Optionaler expliziter Pfad zu einem Titelbild für die EPUB-Ausgabe
• export_name: Optionaler Dateinamenstamm für benutzerorientierte Ausgabealiase
• custom_instructions: Zusätzliche Übersetzungsanweisungen des Benutzers (optional)

Wenn der Dateipfad nicht angegeben ist, frage den Benutzer.

2. Vorverarbeitung – In Markdown-Blöcke konvertieren

Führe das Konvertierungsskript aus, um Blöcke zu erzeugen:

python {basisVerz}/scripts/convert.py "<dateipfad>" --olang "<zielsprache>"

Wenn der Benutzer temp_root bereitgestellt hat, füge --temp-root "<temp_root>" hinzu. Der Name des temporären Verzeichnisblatts bleibt {filename}_temp/; nur das übergeordnete Verzeichnis ändert sich.

Wissenschaftliche Arbeiten: Verwende die arXiv-LaTeX-Quelle

Wenn die Eingabe ein arXiv-Papier ist, ist das LaTeX-Quell-Backend der einzige Weg, der Gleichungen erhält. Das Standard-Backend (calibre) führt das PDF durch pdftohtml, was jede Formel in positionierte Textabschnitte streut – es bleibt kein mathematisches Objekt übrig, das wiederhergestellt werden könnte, daher kann keine Kombination von Flags eine Gleichung zurückbringen. Text innerhalb von Abbildungen (Achsenbeschriftungen, Ticknummern) gelangt auf diesem Weg auch in den Haupttext.

convert.py erkennt einen arXiv-Preprint automatisch (Seite-1-Stempel plus die Metadaten arXiv GenPDF des Erstellers) und meldet ihn. Da die Nutzung das Herunterladen der Quelle des Papiers von arxiv.org erfordert, frage den Benutzer, bevor du --allow-network übergibst:

python {basisVerz}/scripts/convert.py "<dateipfad>" --olang "<zielsprache>" --allow-network

Verwandte Flags:

• --backend {auto,calibre,arxiv} – auto (Standard) bevorzugt arxiv, wenn das PDF ein erkannter Preprint IST UND --allow-network gegeben ist, sonst fällt es auf calibre zurück. arxiv scheitert lautstark, anstatt leise zurückzustufen.
• --arxiv-id <id> – Erkennung überschreiben (z. B. 2606.04980). Setzt das arxiv-Backend voraus.
• --no-math-guard – nur zum Debuggen; deaktiviert die Formel-Platzhalter.

Erwarte auf dem arXiv-Pfad: echte $...$/$$...$$-Mathematik, aus den ursprünglichen Vektor-PDFs gerasterte Abbildungen mit angehängten Bildunterschriften und von Citeproc gerenderte Zitate, wenn die Quelle eine .bib mitliefert. Zwei bekannte Einschränkungen, die es wert sind, dem Benutzer mitgeteilt zu werden: Rohe LaTeX-Tabellen werden wortwörtlich erhalten und nicht übersetzt, und mit tikz/pgfplots gezeichnete Abbildungen haben keine Bilddatei in der Quelle.

Zähle die Abbildungen gegen das Original-PDF, bevor du glaubst, dass eine fehlende eine tikz-Figur ist. pandocs LaTeX-Leser kennt einen festen Satz von Konstrukten; alles andere wird als rohes LaTeX durchgereicht, und resolve_images schreibt nur Bilder um, die pandoc bereits ausgegeben hat. Das Bild wird also weggelassen, seine Bildunterschrift wird trotzdem gedruckt, und nichts meldet ein Problem – was genau wie ein tikz-Plot aussieht. Drei verschiedene Konstrukte taten dies, alle jetzt bei der Aufnahme behandelt und alle wert, in einem neuen Papier erkannt zu werden: \subfloat, \begin{SCfigure} und seine wrapfigure/sidewaysfigure-Verwandten, und \includegraphics[page=N] auf einer mehrseitigen Figuren-PDF – letzteres erzeugte überhaupt keinen Fehler, nur den falschen Plot und ein Duplikat eines anderen. dry_run.py fängt alle drei.

Prüfe die Spaltenanzahl einer Tabelle gegen ihre Tabellenpräambel, nicht gegen die anderen Zeilen. pandoc formt eine rohe Tabelle auf dem Weg nach draußen auf zwei Arten um, die keine Zählung erfasst: Es gibt ein erweitertes *{9}{r} neben dem Original aus, sodass aus einer 12-Spalten-Tabelle 21 mit neun leeren Spalten nach jeder Zeile werden; und es lässt \rotatebox/\multirow ganz weg, sodass die Bezeichnung, die eine schmale Gruppenkolonne trägt, verschwindet und die Zeilen dort ohne Zuordnung sitzen. Beides wird bei der Aufnahme behandelt, und beides ist nachträglich in den Mathematik-Seitenwagen reparierbar, ohne die Prosa zu berühren – siehe K53.

Dies erstellt ein Verzeichnis {filename}_temp/, das Folgendes enthält:

• input.html, input.md – Zwischendateien (input.html nur beim Calibre-Backend)
• chunk0001.md, chunk0002.md, ... – Quellblöcke für die Übersetzung
• chunk0001.math.json, ... – Seitenwagen für Formel-/Zitierplatzhalter (arXiv-Pfad)
• flat.tex, arxiv_src/ – reduzierte LaTeX-Quelle und das entpackte Tarball (arXiv-Pfad)
• manifest.json – Blockmanifest für Nachverfolgung und Validierung
• source_fingerprint.json – SHA-256-Identität der Quellbytes, aus denen dieses temporäre Verzeichnis erstellt wurde
• config.txt – Pipeline-Konfiguration mit Metadaten, einschließlich welchem Backend es erstellt hat

Ein temporäres Verzeichnis merkt sich sein Backend. Ein erneutes Ausführen mit einem anderen bricht ab, anstatt ein arXiv-abgeleitetes input.md mit Calibre-abgeleiteten Bildern zu mischen.

Wenn convert.py abbricht, weil das temporäre Verzeichnis aus anderen Quellbytes erstellt wurde, verwende es nicht wieder – lösche das temporäre Verzeichnis oder übergib ein frisches --temp-root, dann führe es erneut aus. Temporäre Verzeichnisse, die vor der Existenz der Fingerprints erstellt wurden, werden mit einer Warnung übernommen und beim nächsten erfolgreichen Lauf mit einem Fingerprint versehen.

3. Quellblöcke entdecken

Verwende Glob, um alle Quellblöcke zu finden:

Glob: {filename}_temp/chunk*.md

Schließe output_chunk*.md aus der Quellliste aus. Der Plan für selektive Neuübersetzung unten entscheidet, welche Blöcke tatsächlich Arbeit benötigen.

3.5. Glossar erstellen (Begriffskonsistenz)

Ein separater Unter-Agent übersetzt jeden Block mit einem frischen Kontext. Ohne gemeinsamen Zustand kann derselbe Eigenname über mehrere Übersetzungen hinweg abweichen. Das Glossar stellt sicher, dass jeder Unter-Agent für die Begriffe, die in seinem Block vorkommen, dieselbe kanonische Übersetzung sieht.

Wenn <temp_dir>/glossary.json bereits existiert, überspringe die Neuerstellung – ein erneutes Ausführen der Fähigkeit darf nicht über…

[abgeschnitten zur Übersetzung]