manual-explainer (explorateur de manuels)

Explainer de manuel (Manual Explainer)

Construisez une application de formation HTML autonome à partir d'un manuel : les pages sont affichées sous forme d'images, chaque étape est commentée en chinois, coréen ou anglais — commutable à tout moment (synthèse vocale du navigateur, avec surlignage des phrases). L'apprenant peut à tout moment appuyer sur ✋ 打断提问. Cela interrompt la narration en milieu de phrase, ouvre un panneau de questions qui sait où se trouve l'apprenant, répond à partir du manuel avec des liens [p.N] vers les pages, et ▶ 继续讲解 reprend là où la phrase a été interrompue.

La qualité de l'application dépend presque entièrement de l'étape 2 (compréhension) et de l'étape 3 (conception de la leçon). Les scripts gèrent la mécanique.

Workflow

1. Extraction

SK=<ce répertoire de compétence>
python $SK/scripts/extract_manual.py "/mnt/user-data/uploads/<fichier>" /home/claude/mx

Supporte pdf, pptx, ppt, docx, doc (tout passe par un PDF pour que les numéros de page correspondent aux images). Résultat dans /home/claude/mx : content.md (texte complet avec les marqueurs [[pN]], notes du présentateur pptx, plan docx), content.json, pages/pN.jpg. Le rapport imprimé liste image_heavy_pages et le nombre de secrets masqués.

Pour les diapositives PPTX qui sont une grande image avec des notes dans une zone de texte à côté, l'extracteur utilise l'image elle-même en résolution native comme image de page (signalé dans warnings), donc les diapositives s'affichent plus grandes et plus nettes.

Si aucun fichier n'est joint, demandez-le. Si le fichier est un PDF scanné sans texte (total_chars proche de 0), lisez visuellement les images des pages et rédigez vous-même le knowledge à partir de ce que vous voyez.

2. Comprendre le manuel complètement — avant de concevoir quoi que ce soit

Lisez content.md du début à la fin (par morceaux avec view si long). Ensuite, view les images des pages pour chaque image_heavy page et pour toute page dont le texte fait référence à une figure, un écran, un panneau, un schéma de câblage, un tableau ou une disposition de boutons — ces visuels sont souvent le cœur d'un manuel et l'extraction de texte les rate.

Construisez un modèle de travail et gardez des notes dans /home/claude/mx/notes.md :

• ce qu'est le produit/processus, qui est le lecteur, ce qu'il doit être capable de faire après
• la structure réelle : installation → fonctionnement normal → réglages → maintenance → dépannage, ou toute autre structure utilisée par le manuel
• chaque procédure avec son ordre, ses préconditions et son résultat attendu
• chaque avertissement / mise en garde / danger (ceux-ci doivent survivre dans la leçon mot pour mot dans leur sens)
• spécifications et nombres (pressions, tensions, temporisations, limites) et sur quelle page
• termes que l'apprenant doit connaître (→ glossaire)
• contradictions, lacunes ou points peu clairs — mentionnez-les à l'utilisateur à la fin plutôt que de deviner

3. Concevoir la leçon → /home/claude/mx/lesson.json

Lisez references/lesson_schema.md pour le format exact et les règles de narration. Principes de conception :

• Enseignez, ne lisez pas à voix haute. Ordonnez par ce dont l'apprenant a besoin en premier, pas nécessairement par ordre de page. Taille typique : 3 à 10 chapitres, 2 à 8 étapes chacun, une idée par étape.
• Chaque étape montre l'image de page la plus pertinente (image) et liste chaque page de support dans page_refs.
• La narration explique pourquoi et ce qui peut mal tourner, pointe ce qui est visible sur l'image de page, et est écrite pour être parlée.
• Reportez chaque avertissement de sécurité dans warning de l'étape où il s'applique.
• 1 à 3 questions de quiz par chapitre sur des choses qui comptent en pratique (ordre des procédures, limites, avertissements) — pas des trivia.
• knowledge = le texte complet nettoyé de content.md avec ses marqueurs [[pN]] (supprimez les en-têtes/pieds de page et les éléments répétés ; gardez les tableaux). Ajoutez une brève description des figures importantes que vous avez vues sur les pages riches en images sous leur marqueur de page, pour que le tuteur puisse aussi répondre à leur sujet.
• Vérification de couverture : chaque page doit apparaître dans l'image ou les page_refs d'une étape, sauf la couverture, la table des matières, les pages vierges et juridiques. Le rapport de construction imprime uncovered_pages ; comblez les lacunes qui contiennent du contenu réel.
• Langues (par défaut : 中文 / 한국어 / English) : construisez chaque leçon dans les trois — "languages": ["zh","ko","en"] — afin que l'apprenant puisse basculer à tout moment dans l'en-tête de l'application. Définissez language (la langue par défaut) sur la langue dans laquelle l'utilisateur vous parle. Ne construisez moins de langues que si l'utilisateur le demande. Chaque texte visible (titres, narration, puces, avertissements, quiz, glossaire) est alors un objet {"zh":…,"ko":…,"en":…} ; la construction refuse de s'exécuter si l'un manque. Rédigez chaque langue de manière native pour être parlée, pas comme une traduction littérale des deux autres, et gardez les avertissements tout aussi stricts dans toutes. knowledge reste dans la langue originale du manuel — le tuteur le lit et répond dans la langue sélectionnée. Conservez les libellés d'écran originaux du manuel (noms de boutons, codes d'alarme) la première fois qu'ils apparaissent dans chaque langue.
• Pour les longs manuels, rédigez la leçon d'abord dans la langue par défaut, vérifiez la couverture, puis ajoutez les deux autres langues champ par champ.

4. Construire

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

La construction valide la leçon (corrigez et relancez en cas d'ERREUR DE LEÇON), masque à nouveau les secrets, intègre les images de page dans un budget d'environ 14,5 Mo (les pages publiées doivent rester sous 16 Mo), et imprime un rapport. Les images sont en WebP et les pages identiques sont stockées une seule fois. Les images d'étape sont toujours intégrées et conservées les plus nettes (jusqu'à 1800 px, jamais agrandies) ; les pages listées uniquement dans page_refs sont intégrées plus petites, et celles qui ne tiennent pas apparaissent comme des citations textuelles uniquement. Pour les très longs manuels (centaines de pages), conservez les images d'étape sur des pages distinctes et essentielles. Les informations d'identification qui apparaissent dans les images de page (captures d'écran, texte de diapositive) ne sont pas détectées par l'analyse de texte : noircissez-les dans pages/pN.jpg avant la construction. Ne modifiez pas à la main la logique du modèle pour un seul manuel ; modifiez lesson.json.

5. Livraison

• Là où l'outil Artifact existe (claude.ai) : publiez le HTML avec capabilities: {"sample": {}} et une favicon 📘. sample est ce qui permet au tuteur intégré à l'application d'interroger Claude. Ne déclarez pas d'autres capacités.
• Ailleurs (Claude Code, Cowork, pas d'outil Artifact) : présentez le fichier HTML. Ouvert comme un fichier simple, le panneau de questions utilise la recherche dans le manuel et affiche les passages originaux les plus pertinents avec les numéros de page.

Répondez ensuite brièvement, dans la langue de l'utilisateur : la liste des chapitres en une ou deux lignes, comment utiliser (▶ lecture, ✋ interruption à tout moment, clavier : Barre d'espace / ← → / Q), que la première question demande l'autorisation d'utiliser leur utilisation Claude, et toutes les lacunes ou contradictions que vous avez trouvées dans le manuel.

6. Itération

Pour les modifications ("Chapitre 3 plus détaillé", "Débit trop rapide", "Ajouter un chapitre de dépannage"), éditez lesson.json, reconstruisez, et republiez vers le même artifact (passez son url).

Sécurité (documents d'entreprise)

Les manuels peuvent contenir des noms de compte, des mots de passe par défaut, des adresses IP avec identifiants, des clés de licence ou des données client.

• Les deux scripts masquent automatiquement les mots de passe, jetons, clés, clés privées et chaînes de connexion avec identifiants. Ne copiez jamais ces valeurs dans la narration, les puces ou vos réponses ; signalez uniquement que N éléments ont été masqués et de quel type.
• Si une information d'identification par défaut d'un manuel fait vraiment partie d'une procédure (par exemple « connectez-vous en tant qu'administrateur avec le mot de passe initial »), décrivez l'étape et pointez vers la page ("初始密码见手册第12页，或向管理员获取") au lieu de donner la valeur.
• Ne téléchargez pas le manuel vers un service externe ; tout s'exécute localement et dans la page publiée.

Ce que fait l'application (pour répondre aux questions de l'utilisateur à son sujet)

• En-tête : titre, sélecteur de langue (中文 / 한국어 / EN — le changement conserve l'étape en cours et fonctionne en milieu de leçon ou dans le panneau de questions), 🔊 panneau vocal, vitesse 0,8–1,5× ; barre de progression.
• Voix : l'application classe les voix du navigateur et sélectionne automatiquement la plus naturelle (voix neuronales Edge "Natural/Online" > Apple Enhanced/Premium > voix Google > autres). Le panneau 🔊 les liste (★ = naturelle), propose un aperçu et mémorise le choix par langue. Lorsqu'il n'existe que des voix robotiques, il le dit et suggère Edge / une voix Google / le téléchargement d'une voix améliorée. Un préenregistrement audio n'est pas possible : une page publiée ne peut pas appeler un service TTS et l'audio dépasserait la limite de taille.
• Tiroir de contenu (☰ sur mobile) : chapitres, étapes (visitées marquées), quiz, glossaire.
• Carte d'étape : image de page, titre, points clés, avertissement, narration avec la phrase en cours surlignée, puces de page.
• 🖼 mode grand écran (par défaut activé) : le contenu se déplace dans le tiroir ☰ et la diapositive remplit la hauteur de l'écran à côté d'une colonne de texte étroite (empilée sur les écrans étroits). Basculable et mémorisé par spectateur.
• Visualiseur de page (appuyez sur une diapositive, une puce de page ou un lien [p.N]) : zoom par pincement/molette jusqu'à 6×, faites glisser pour vous déplacer, double-tap pour zoomer, boutons − ⤢ +, ‹ › pour feuilleter chaque page intégrée ; clavier + - 0 ← → Esc. Sur un téléphone en mode portrait, il suggère de tourner le téléphone sur le côté.
• La lecture automatique continue à travers les étapes et s'arrête à chaque quiz de chapitre.
• ✋ panneau de questions : ligne de contexte montrant la position actuelle, puces de suggestion (再讲一遍 / 更简单 / 举例 / 为什么重要 / 常见错误), réponses en streaming avec [p.N] cliquables, bouton Stop, ▶ 继续讲解 reprend à partir de la phrase interrompue.
• La position, la voix et la vitesse sont mémorisées par spectateur.
• Les voix dépendent du navigateur/système d'exploitation du spectateur ; sans voix correspondante, l'application avance toujours en utilisant le temps de lecture avec surlignage.