nick334455/manual-explainer

Manual Explainer (Handbuch-Erklärer)

Erstelle eine eigenständige HTML-„Lektions-App“ aus einem Handbuch: Die Seiten werden als Bilder dargestellt, jeder Schritt wird auf Chinesisch, Koreanisch oder Englisch erklärt – jederzeit umschaltbar (Browser-Text-to-Speech mit Satzhervorhebung). Der Lernende kann jederzeit ✋ 打断提问 (Unterbrechen & Fragen) drücken. Das pausiert die Erzählung mitten im Satz, öffnet ein Fragetableau, das den aktuellen Stand des Lernenden kennt, Antworten aus dem Handbuch mit [p.N]-Seitenlinks liefert, und ▶ 继续讲解 (Weiter mit der Erklärung) setzt die Erzählung an der unterbrochenen Stelle fort.

Die Qualität der App hängt fast ausschließlich von Schritt 2 (Verständnis) und Schritt 3 (Lektionsdesign) ab. Die Skripte erledigen die Mechanik.

Arbeitsablauf

1. Extrahieren

SK=<Verzeichnis dieses Skills>
python $SK/scripts/extract_manual.py "/mnt/user-data/uploads/<Datei>" /home/claude/mx

Unterstützt pdf, pptx, ppt, docx, doc (alles geht durch ein PDF, sodass die Seitenzahlen mit den Bildern übereinstimmen). Ausgabe in /home/claude/mx: content.md (Volltext mit [[pN]]-Markern, PPTX-Referentennotizen, DOCX-Gliederungsübersicht), content.json, pages/pN.jpg. Der gedruckte Bericht listet image_heavy_pages auf und gibt an, wie viele Geheimnisse maskiert wurden.

Bei PPTX-Folien, die ein großes Bild mit Notizen in einem Textfeld daneben sind, verwendet der Extraktor das Bild selbst in nativer Auflösung als Seitenbild (gemeldet in warnings), sodass Folien größer und schärfer dargestellt werden.

Wenn keine Datei angehängt ist, frage danach. Wenn die Datei ein gescanntes PDF ohne Text ist (total_chars nahe 0), lies die Seitenbilder visuell und schreibe knowledge selbst aus dem, was du siehst.

2. Verstehe das Handbuch vollständig – bevor du etwas entwirfst

Lies content.md von Anfang bis Ende (in Teilen mit view, falls es lang ist). Dann view die Seitenbilder für jede image_heavy-Seite und für jede Seite, deren Text sich auf eine Abbildung, einen Bildschirm, ein Bedienfeld, einen Schaltplan, eine Tabelle oder eine Tastenanordnung bezieht – diese Visualisierungen sind oft das Herzstück eines Handbuchs, und die Textextraktion übersieht sie.

Erstelle ein funktionierendes Modell und notiere in /home/claude/mx/notes.md:

• Was das Produkt / der Prozess ist, wer der Leser ist, was er danach können muss
• Die tatsächliche Struktur: Einrichtung → Normalbetrieb → Einstellungen → Wartung → Fehlerbehebung oder was auch immer das Handbuch tatsächlich verwendet
• Jede Vorgehensweise mit ihrer Reihenfolge, Vorbedingungen und erwartetem Ergebnis
• Jede Warnung / Vorsicht / Gefahrenhinweis (diese müssen sinngemäß wortwörtlich in die Lektion übernommen werden)
• Spezifikationen und Zahlen (Drücke, Spannungen, Zeitangaben, Grenzwerte) und auf welcher Seite
• Begriffe, die der Lernende kennen muss (→ Glossar)
• Widersprüche, Lücken oder unklare Punkte – erwähne diese dem Benutzer am Ende, anstatt zu raten

3. Entwerfe die Lektion → /home/claude/mx/lesson.json

Lies references/lesson_schema.md für das genaue Format und die Erzählregeln. Gestaltungsprinzipien:

• Lehren, nicht vorlesen. Ordne nach dem, was der Lernende zuerst braucht, nicht unbedingt nach der Seitenreihenfolge. Typische Größe: 3–10 Kapitel, 2–8 Schritte pro Kapitel, eine Idee pro Schritt.
• Jeder Schritt zeigt das relevanteste Seitenbild (image) und listet jede unterstützende Seite in page_refs auf.
• Die Erzählung erklärt warum und was schiefgehen kann, zeigt auf das, was auf dem Seitenbild sichtbar ist, und ist zum Sprechen geschrieben.
• Übertrage jeden Sicherheitshinweis in die warning des Schrittes, in dem er gilt.
• 1–3 Quizfragen pro Kapitel zu Dingen, die in der Praxis wichtig sind (Vorgehensreihenfolge, Grenzwerte, Warnungen) – keine Trivia.
• knowledge = der bereinigte Volltext von content.md mit seinen [[pN]]-Markern (Seitenkopf-/fußzeilen und wiederholten Textbausteine entfernen; Tabellen behalten). Füge eine kurze Beschreibung wichtiger Abbildungen, die du auf bildlastigen Seiten gesehen hast, unter ihrem Seitenmarker hinzu, damit der Tutor auch dazu antworten kann.
• Abdeckungsprüfung: Jede Seite sollte in image oder page_refs eines Schrittes vorkommen, mit Ausnahme von Umschlag-, Inhaltsverzeichnis-, Leer- und rechtlichen Seiten. Der Erstellungsbericht druckt uncovered_pages; schließe Lücken, die echten Inhalt enthalten.
• Sprachen (Standard: 中文 / 한국어 / English): Erstelle jede Lektion in allen drei – "languages": ["zh","ko","en"] – damit der Lernende in der Kopfzeile der App jederzeit wechseln kann. Setze language (die Standardsprache) auf die Sprache, in der der Benutzer mit dir spricht. Verwende nur dann weniger Sprachen, wenn der Benutzer danach fragt. Jeder sichtbare Text (Titel, Erzählung, Aufzählungspunkte, Warnungen, Quiz, Glossar) ist dann ein {"zh":…,"ko":…,"en":…}-Objekt; der Build weigert sich, ausgeführt zu werden, wenn eines fehlt. Schreibe jede Sprache muttersprachlich zum Sprechen, nicht als wörtliche Übersetzung der anderen beiden, und halte Warnungen in allen gleichermaßen streng. knowledge bleibt in der Originalsprache des Handbuchs – der Tutor liest es und antwortet in der jeweils ausgewählten Sprache. Behalte die ursprünglichen Bildschirmbeschriftungen des Handbuchs (Bedienelementnamen, Alarmcodes) beim ersten Auftreten in jeder Sprache bei.
• Bei langen Handbüchern schreibe die Lektion zuerst in der Standardsprache, überprüfe die Abdeckung, füge dann die anderen beiden Sprachen feldweise hinzu.

4. Erstellen

python $SK/scripts/build_app.py /home/claude/mx/lesson.json /home/claude/mx /mnt/user-data/outputs/<Name>-讲解.html

Der Build validiert die Lektion (korrigiert und wiederholt bei LESSON ERROR), maskiert erneut Geheimnisse, bettet Seitenbilder innerhalb eines Budgets von ~14,5 MiB ein (veröffentlichte Seiten müssen unter 16 MB bleiben) und druckt einen Bericht. Bilder sind im WebP-Format und identische Seiten werden nur einmal gespeichert. Schrittbilder werden immer eingebettet und am schärfsten gehalten (bis zu 1800px, niemals hochskaliert); Seiten, die nur in page_refs aufgeführt sind, werden kleiner eingebettet, und diejenigen, die nicht passen, erscheinen als reine Textzitate. Bei sehr langen Handbüchern (Hunderte von Seiten) beschränke Schrittbilder auf eindeutige, wesentliche Seiten. Anmeldeinformationen, die in Seitenbildern (Screenshots, Folientext) erscheinen, werden vom Textscan nicht erfasst: schwärze sie in pages/pN.jpg vor dem Erstellen. Bearbeite die Logik der Vorlage nicht von Hand für ein einzelnes Handbuch; ändere lesson.json.

5. Ausliefern

• Wo das Artefakt-Werkzeug existiert (claude.ai): Veröffentliche das HTML mit capabilities: {"sample": {}} und Favicon 📘. sample ist das, was dem Tutor in der App ermöglicht, Claude zu fragen. Deklariere keine anderen Fähigkeiten.
• Andernorts (Claude Code, Cowork, kein Artefakt-Werkzeug): Präsentiere die HTML-Datei. Als einfache Datei geöffnet, greift das Fragentableau auf die Suche im Handbuch zurück und zeigt die relevantesten Originalpassagen mit Seitenzahlen an.

Antworte dann kurz in der Sprache des Benutzers: die Kapitelliste in ein oder zwei Zeilen, wie man sie verwendet (▶ abspielen, ✋ jederzeit unterbrechen, Tastatur: Leertaste / ← → / Q), dass die erste Frage um Erlaubnis zur Nutzung der Claude-Nutzung bittet, und etwaige Lücken oder Widersprüche, die du im Handbuch gefunden hast.

6. Iterieren

Bei Änderungen („第3章讲细一点“, „Sprechgeschwindigkeit zu schnell“, „Füge ein Kapitel zur Fehlerbehebung hinzu“) bearbeite lesson.json, erstelle neu und veröffentliche im selben Artefakt neu (übergib seine url).

Sicherheit (Unternehmensdokumente)

Handbücher können Kontonamen, Standardpasswörter, IPs mit Anmeldeinformationen, Lizenzschlüssel oder Kundendaten enthalten.

• Beide Skripte maskieren automatisch Passwörter, Tokens, Schlüssel, private Schlüssel und Verbindungszeichenfolgen mit Anmeldeinformationen. Kopiere solche Werte niemals in Erzählungen, Aufzählungspunkte oder deine Antworten; berichte nur, dass N Elemente maskiert wurden und von welcher Art.
• Wenn die Standard-Anmeldeinformation eines Handbuchs wirklich Teil einer Vorgehensweise ist (z. B. „melden Sie sich als Admin mit dem initialen Passwort an“), beschreibe den Schritt und verweise auf die Seite („初始密码见手册第12页，或向管理员获取“), anstatt den Wert zu nennen.
• Lade das Handbuch nicht auf einen externen Dienst hoch; alles läuft lokal und innerhalb der veröffentlichten Seite.

Was die App tut (zur Beantwortung von Benutzerfragen darüber)

• Kopfzeile: Titel, Sprachumschalter (中文 / 한국어 / EN – das Umschalten behält den aktuellen Schritt und funktioniert mitten in der Lektion oder im Fragentableau), 🔊 Sprachtableau, Geschwindigkeit 0,8–1,5×; Fortschrittsbalken.
• Stimme: Die App bewertet die Stimmen des Browsers und wählt automatisch die natürlichste aus (Edge „Natural/Online“ neuronale Stimmen > Apple Enhanced/Premium > Google-Stimmen > andere). Das 🔊-Tableau listet sie auf (★ = natürlich), bietet eine Vorschau und merkt sich die Auswahl pro Sprache. Wenn es nur Roboterstimmen gibt, teilt es dies mit und schlägt Edge / eine Google-Stimme / das Herunterladen einer verbesserten Stimme vor. Voraufgezeichnetes Audio ist nicht möglich: Eine veröffentlichte Seite kann keinen TTS-Dienst aufrufen, und Audio würde das Größenlimit überschreiten.
• Inhaltsverzeichnis-Ziehfach (☰ auf Mobilgeräten): Kapitel, Schritte (besuchte markiert), Quizze, Glossar.
• Schrittkarte: Seitenbild, Titel, Kernpunkte, Warnung, Erzählung mit aktuell hervorgehobenem Satz, Seiten-Chips.
• 🖼 Großbildmodus (standardmäßig aktiviert): Der Inhalt wird in das ☰-Ziehfach verschoben, und die Folie füllt die Bildschirmhöhe neben einer schmalen Textspalte (bei schmalen Bildschirmen gestapelt). Umschaltbar und pro Betrachter gespeichert.
• Seitenbetrachter (tippe auf eine Folie, einen Seiten-Chip oder einen [p.N]-Link): Pinch-/Mausrad-Zoom bis zu 6×, ziehen zum Verschieben, Doppeltippen zum Zoomen, − ⤢ + Schaltflächen, ‹ › zum Durchblättern aller eingebetteten Seiten; Tastatur + − 0 ← → Esc. Auf einem Hochformat-Telefon wird empfohlen, das Telefon seitlich zu halten.
• Autoplay setzt sich über Schritte hinweg fort und stoppt bei jedem Kapitel-Quiz.
• ✋ Fragentableau: Kontextzeile, die die aktuelle Position anzeigt, Vorschlags-Chips (再讲一遍 / 更简单 / 举例 / 为什么重要 / 常见错误), Streaming-Antworten mit anklickbaren [p.N], Stopp-Button, ▶ 继续讲解 setzt an der unterbrochenen Stelle fort.
• Position, Stimme und Geschwindigkeit werden pro Betrachter gespeichert.
• Stimmen hängen vom Browser/Betriebssystem des Betrachters ab; ohne passende Stimme schreitet die App trotzdem fort, indem sie die Lesezeit mit Hervorhebung simuliert.