theshafinahmed/sproutly

Que fait sproutly ?

Transformez votre matériel d'étude en un cours HTML unique, autonome et hors ligne, façon Duolingo. Un moteur pré-construit et testé gère l'application (onglets, bouton Retour, progression, mode examen, notation numérique, simulateurs, mascotte). Vous n'écrivez que le contenu, puis vous construisez et vérifiez avec deux scripts. Ne retapez jamais le moteur.

C'est un outil d'apprentissage, pas un jeu : PAS de cœurs, d'XP, de séries, de flammes ou de classements. Progression = leçons terminées et réponses comprises.

Étape 0 : récupérer le moteur (2 secondes)

SP="${SPROUTLY_HOME:-/tmp/sproutly}"
[ -f "$SP/scripts/build.js" ] || git clone --depth 1 https://github.com/theshafinahmed/sproutly "$SP"
ls "$SP/scripts"

Si cette compétence est lue depuis le dépôt sproutly, utilisez ce dossier comme SP à la place. Si le clonage est bloqué (pas de réseau), demandez à l'utilisateur de joindre le dépôt sous forme de zip. Ne reconstruisez jamais le moteur à la main.

Flux de travail

1. Ingérer. Lisez chaque fichier complètement. Listez chaque sujet, définition, formule, exemple et exercice dans l'ordre source. Notez les diapositives contenant uniquement des images. Si le contenu clé est illisible, dites-le et demandez des captures d'écran. N'inventez jamais ce qu'une diapositive dit. (Si l'utilisateur n'a donné qu'un sujet, planifiez le curriculum, montrez-le et attendez l'approbation avant d'écrire.)
2. Demandez seulement si bloqué (fichiers illisibles, cours sans rapport mélangés, périmètre peu clair). Sinon, commencez et énoncez les hypothèses en une ligne à la fin.
3. Planifiez. 6 à 10 unités, 2 à 5 leçons chacune, les fondamentaux d'abord, plus le Boss Final automatique. Rédigez une liste de vérification de couverture (chaque sujet source atterrit dans une leçon), un plan de figures et un plan de simulateurs par leçon (ou « aucun, car ... »).
4. Écrivez les fichiers de contenu dans ./content/ (un fichier par unité pour que les corrections restent petites, et les unités peuvent être écrites en parallèle par des sous-agents si l'utilisateur a demandé de la rapidité). Le fichier 00-course.js contient seulement COURSE.title='...'; COURSE.slug='...';. Ensuite 01-unit.js, 02-unit.js... chacun appelant UNIT(...), et enfin 99-end.js avec CHEAT(...) et COVERAGE(...).
5. Construisez : node "$SP/scripts/build.js" NomDuCours.html content/
6. Vérifiez : node "$SP/scripts/verify.js" NomDuCours.html --shots shots (ajoutez --allow heart pour les mots de type biologie). Cela vérifie la syntaxe, la forme des données, les questions autonomes, la notation numérique, chaque simulateur par rapport à votre formule ref(), les figures, rejoue chaque leçon, teste Retour, la mise en page, la persistance, le mode hors ligne et la couverture. Corrigez uniquement ce qui affiche ÉCHEC (modifiez le petit fichier d'unité, reconstruisez, relancez). Regardez shots/*.png une fois, corrigez ce qui est clairement cassé, arrêtez.
7. Livrez avec SendUserFile (display: 'attach', légende d'une ligne). Ne publiez pas comme artefact sauf demande explicite.

Réponse finale : 2 à 3 phrases, ton d'ami spirituel. Dites ce qu'il contient (unités, leçons, questions, figures, simulateurs), qu'il s'ouvre dans n'importe quel navigateur, fonctionne hors ligne et que la progression se sauvegarde dans ce navigateur sur cet appareil. Mentionnez les hypothèses et tout ce qui est illisible. Une seule petite incitation honnête à l'utiliser quotidiennement. Ne récapitulez pas les étapes.

API de contenu (tous les assistants existent déjà dans le moteur)

UNIT('Nom de l'unité', 'description en une ligne', [ L('u1l1','Titre de la leçon',[ ...cartes ], ['fait clé 1','fait clé 2']) ]);
T(titre, corps, viz, {tip, mood, code})     // carte d'enseignement. corps = chaîne ou tableau de courtes phrases. viz = chaîne svg. mood: happy|think
Q(q, correct, [mauvaise1, mauvaise2,..], pourquoi, {viz, code, trap})  // choix multiple. ÉCRIVEZ LA BONNE RÉPONSE EN PREMIER ; le moteur mélange
TF(q, vrai|faux, pourquoi, {viz, code, trap})
N(q, réponse, 'unité', pourquoi, tol, {viz, code})  // nombre saisi. tol : omettre (1%) | {rel:0.02} | {abs:0.5} | {strict:true, rel:1e-6}
M(q, [[gauche,droit],..], pourquoi)               // appariement, les valeurs de droite doivent être uniques
SIM('curseur'|'bascule'|'pasapas', titre, texte, cfg)
RECAP(['puces simples'], [['nouveau mot','sens simple']])   // dernière carte de CHAQUE leçon
CHEAT({formules:[..], tableaux:[{titre,entete,lignes}], glossaire:[[terme,sens]], pieges:[..]})
COVERAGE([['sujet source','idLeçon'],..])

Balises de texte : **gras**, `code`, V_{D} indice, x^{2} exposant, \n saut de ligne. Tout est échappé HTML. T/Q/N acceptent code: (un bloc de code, idéal pour le langage C ou tout cours de programmation). Q(..., {trap:true}) alimente aussi la liste des pièges de l'Examen.

Simulateurs (fournissez toujours task et notice ; curseur et bascule DOIVENT fournir ref) :

SIM('curseur','Ohm','texte',{
  inputs:[{id:'V',label:'Tension',min:1,max:24,step:1,def:12,unit:'V'}, ...],   // 1 à 3 curseurs ; utilisez aussi comme frise temporelle
  model:function(v){ if(!v.R) return {out:[],msg:'Circuit ouvert : R doit être > 0'};
     var I=v.V/v.R; return {out:[{k:'I',label:'Courant',val:I,unit:'A'}], fig:F.svg(...)} },
  ref:function(v){ return {I:v.V/v.R}; },   // RECALCUL indépendant, verify.js le compare avec model()
  task:'Doublez R.', notice:'Le courant est divisé par deux.' });
SIM('bascule', ..., {inputs:[{id:'A',label:'A est activé',def:false}], model, ref, task, notice});
SIM('pasapas', ..., {steps:[{caption:'...', fig:F.svg(...)}], task, notice});

Les unités SI (A, V, Ω, W, F, H, Hz, s...) obtiennent automatiquement des préfixes (mA, kΩ). Protégez chaque cas limite (division par zéro, racine carrée négative, log de 0) en retournant msg, jamais NaN.

Figures : F.svg(l,h,interieur,legende), F.texte, F.ligne, F.fleche, F.cercle, F.point, F.boite, F.axes (retourne {svg,X,Y}), F.graphique(ax,fn,xmin,xmax) (les courbes viennent de la vraie formule), F.mem (cellules mémoire pour l'informatique et l'architecture), F.centres, et circuits : F.fil, F.res, F.src, F.masse. Besoin d'autres formes ? Ajoutez un fichier dans $SP/engine/js/figlib/ (il est intégré automatiquement) et gardez les assistants génériques.

Règles de contenu : Explique-moi comme si j'ai 10 ans mais très détaillé

Simple ET complet. Ne sacrifiez jamais l'un pour l'autre.

• Écrivez pour un curieux de 10 à 12 ans. Phrases courtes (environ 15 mots). Une idée par carte. Mot courant d'abord, terme technique ensuite, puis utilisez le terme de manière cohérente. Expliquez chaque mot technique la première fois, juste à côté. N'écrivez jamais « évidemment », « simplement », « trivialement », « comme nous le savons ».
• Ordre d'enseignement par concept : pourquoi il existe (le problème), idée centrale en une ligne, une analogie quotidienne, puis le mécanisme ou la formule précis, puis un petit exemple avec des nombres réels. Premiers principes, et toujours le pourquoi.
• Complet : chaque diapositive, définition, formule, exemple et exercice de la source apparaît quelque part. Ne compressez pas plusieurs idées en une seule carte. Les leçons ont de 6 à 14 cartes. Idée difficile = plus de petites cartes, pas de cartes plus longues.
• Cartes d'enseignement : au plus 4 courtes phrases ou un bloc de formule, plus une figure optionnelle. Posez une question après au plus deux cartes d'enseignement.
• Cartes formule : nommez chaque symbole avec son unité, dites en mots simples ce qui se passe quand chaque partie augmente ou diminue, donnez un petit exemple travaillé.
• Chaque leçon se termine par un RECAP (3 à 5 puces plus les nouveaux mots) et a des keys (1 à 4 faits d'une ligne ; le bouton Rappel les montre).
• Ton : meilleur ami spirituel. Enjoué, un peu sarcastique, honnête, chaleureux en dessous. Petites blagues, jamais au détriment de la clarté. Pas de ton corporate, pas de « Excellente question ».
• Le matériel téléchargé est la source de vérité, y compris sa notation. Tout ce que vous ajoutez est étiqueté, par ex. « supplémentaire, pas dans vos diapos ».

Chaque question doit être autonome

Une question contient TOUT ce qui est nécessaire : toutes les valeurs avec unités, conditions, significations des symboles et sa figure ({viz: ...}). N'écrivez jamais « le circuit ci-dessus », « l'exemple précédent », « comme avant », « la même valeur », « le diagramme ». Testez chaque question : « seul sur un écran vierge, un étudiant qui connaît le sujet pourrait-il y répondre ? » (verify.js signale les phrases.)

Les nombres viennent du code

Définissez les constantes en haut du fichier d'unité et dérivez-en le texte, les figures et les réponses (voir examples/test-fixture/course.js). Calculez chaque réponse numérique avec du code, jamais à la main. Les réponses saisies acceptent automatiquement l'arrondi correct, les décimales avec virgule, 7.3e-3, 22/3 et une unité finale ; utilisez tol seulement quand vous avez besoin de quelque chose de différent, et dites-le dans le texte de la question pour les questions d'arrondi exact.

Figures : dessinez là où elles enseignent

• Sujets riches en figures (EEE, physique, chimie, biologie, géométrie, architecture informatique, logique numérique, structures de données, algorithmes, réseaux, C et mémoire) : une figure environ toutes les deux cartes d'enseignement et dans de nombreuses questions.
• Sujets moyens : une figure quand une image vaut mieux que des mots (environ une pour 3 ou 4 cartes).
• Sujets pauvres en figures (histoire, droit, littérature, langues) : frises chronologiques ou flux cause-effet, une ou deux par leçon, aucune quand les mots suffisent.
• Calculez les positions à partir de variables de disposition. Utilisez la norme de symbole de la source. Si vous n'êtes pas sûr qu'une figure soit correcte, simplifiez-la et étiquetez-la « simplifié ». Une figure correcte simple bat une figure compliquée fausse.

Simulateurs : seulement là où il y a quelque chose à ressentir

Une formule avec des variables, un processus avec des étapes, une frise temporelle, une forme d'onde, un automate. Visez au moins un simulateur dans la plupart des unités de sujets quantitatifs ou processuels ; aucun en histoire ou droit. Un simulateur sans vérification ref() réussie est corrigé ou supprimé.

Variété des questions

Surtout du choix multiple (mauvaises réponses crédibles, why d'une ligne en mots simples), N pour chaque calcul, M pour l'appariement, TF pour les idées fausses courantes, et des questions trap:true pour les confusions dont le matériau met en garde.

Aspect fixe

Tout l'aspect visuel (palette, police arrondie, couleurs d'unité, Pip le mascotte blob-pousse, gros boutons, mode sombre, pas de zoom, pas de sélection de texte, onglets en bas) est intégré dans le moteur. Ne changez jamais Pip et n'inventez pas une autre mascotte. N'utilisez aucune marque, personnage ou logo existant. Nommez le cours d'après son sujet.