m4bwav/readwright

Que fait readwright ?

Un roman fait 150 000 à 300 000 tokens. Le déverser avec un convertisseur (epr -d, pandoc -t plain, ebook-convert book.txt) remplit le contexte avant même que la question ne soit répondue. readwright donne à l'agent une table des matières avec les nombres de mots, puis les sections choisies, puis les résultats de recherche avec les numéros de section et de paragraphe, afin qu'il lise ce dont la tâche a besoin et rien d'autre.

RW ci-dessous signifie python "<ce dossier>/scripts/rw.py" (python3 sur macOS et Linux). Les lanceurs scripts/rw.sh et scripts/rw.ps1 font la même chose. Il nécessite Python 3.10 ou plus récent et rien d'autre pour les formats intégrés ; RW formats indique quels outils externes cette machine possède.

Étape 0 : fraîcheur

Lisez evergreen.json. Si contradiction est défini ou si aujourd'hui est le ou après next_due, dites-le en une ligne, effectuez la tâche, puis rafraîchissez (MAINTENANCE.md). Les versions des convertisseurs et les formats de livres numériques changent ; la procédure ci-dessous n'en dépend pas.

Discord : un canal en direct n'est pas un fichier ; lisez-le avec scripts/es_discord.py d'everscout (le propre bot invité de l'utilisateur, everscout kb/discord.md). Un export de canal que l'utilisateur a fait (JSON ou HTML) se lit comme n'importe quel fichier JSON ou HTML ici.

Étape 1 : évaluer la taille

Exécutez RW info FICHIER. Il affiche le format détecté (à partir des octets du fichier, pas de son extension), le titre, l'auteur, la langue, le nombre de sections, les mots et les tokens approximatifs (caractères divisés par 4). En dessous d'environ 6 000 tokens (25 000 caractères), RW read FICHIER imprime tout le texte et vous pouvez vous arrêter ici.

Si info signale un DRM, dites-le clairement et arrêtez-vous. readwright ne supprime jamais les DRM, et vous ne devriez pas non plus : suggérez le lecteur du magasin ou une copie sans DRM du vendeur. S'il nomme un outil manquant (pdftotext, ebook-convert de calibre, LibreOffice), transmettez la ligne d'installation qu'il imprime. N'installez jamais rien sans l'accord de l'utilisateur. Pour un PDF, l'outil de lecture propre de l'agent avec des plages de pages est souvent la meilleure voie.

Si info imprime note: no text layer, le livre est composé d'images de pages (un scan) et readwright n'a rien à lire. Suivez les voies que la note nomme, dans son ordre. D'abord, une copie du même livre dans un autre format à côté ; une copie DjVu contient souvent du texte OCR. Ensuite, pour un PDF, RW ocr FICHIER : il rend les pages et exécute l'OCR intégré à Windows 10 et 11 (ou tesseract là où il est installé), environ une seconde par page, en sauvegardant après toutes les 25 pages, et conserve le texte dans ~/.readwright/ocr/ afin que info, toc, read et grep sur le même fichier l'utilisent ensuite (--pages N-M pour quelques pages, --force pour refaire). Exécutez un livre entier en arrière-plan. L'OCR peut mal lire certaines lettres et n'a pas de titres, donc les sections sont des pages ; vérifiez une citation par rapport à une image de page. Enfin, quelques pages rendues avec RW page FICHIER 1-5 (60 dpi, --dpi, --out-dir) et visualisées avec votre propre lecteur d'images. Demandez avant d'installer un outil d'OCR.

Étape 2 : le plan

Exécutez RW toc FICHIER. Chaque ligne est N. titre (mots m), indentée par niveau ; --ids ajoute l'identifiant de chaque section (fichier et fragment, page, feuille), dont vous avez rarement besoin. Les titres EPUB proviennent de la propre navigation du livre (document nav ou NCX), les titres DOCX et ODT des styles de titre, HTML de h1 à h3, le texte brut et Markdown des titres ou des lignes CHAPITRE. Le texte sans structure est divisé en parties d'environ 3 000 mots. Pour une archive zip, toc liste les membres ; ajoutez --member NOM (ou son numéro) à chaque commande ultérieure.

Les livres qui listent chaque numéro de chapitre comme sa propre section presque vide (Packt, certains O'Reilly) sont affichés fusionnés : Ch. 12 : Titre, imprimé sous le numéro de section du titre (la section avec uniquement le numéro est cachée mais conserve son numéro et peut toujours être lue). RW toc FICHIER --depth 1 imprime uniquement le niveau supérieur (parties et chapitres) avec les mots de chaque ligne cumulés à partir des sections en dessous (--depth 2 ajoute le niveau suivant ; le JSON obtient chapter et words_total). Utilisez-le pour compter les chapitres au lieu de compter à la main. Un PDF sans plan liste une section par page ; RW toc FICHIER --group plie les pages qui partagent un en-tête courant en plages de pages (chapitres) à lire avec --section 20-40 ; sans en-têtes courants, il utilise la table des matières imprimée, où chaque entrée est une ligne de titre puis une ligne de numéro de page (0.26.0), ou les entrées se suivent comme Titre ... 21 Suivant ... 26 (0.35.0), et toc le dit dans une note.

Faites correspondre les mots de l'utilisateur aux lignes de toc. « Chapitre 14 » signifie généralement la ligne intitulée CHAPITRE QUATORZE, qui dans de nombreux livres numériques contient uniquement le titre du chapitre et une épigraphe : son corps est la section suivante. Les nombres de mots le montrent (72 mots, puis 6 330). Les numéros de section ne sont pas des numéros de chapitre : les pages de garde viennent en premier, donc le chapitre 16 d'un roman peut être la section 24.

Étape 3 : lire uniquement ce qui est nécessaire

• RW read FICHIER --section 43-44 (aussi N, N-, N,M ; un --section répété s'accumule) ou --title "REGEX" (insensible à la casse, mis en correspondance avec les titres et les identifiants ; lorsque rien ne correspond, les espaces sont ignorés, donc westgate trouve WEST GATE).
• Lorsque --title tombe sur une section de moins de 300 mots, la section suivante est ajoutée et une note le dit. --with-next fait de même pour toute sélection.
• Une section dont le titre se répète 3 fois ou plus dans le livre (« Préparation », « Comment faire... », « Il y a plus... ») est affichée avec le titre distinctif le plus proche avant elle, dans les en-têtes de read et dans toc : Comment faire... (dans : Suivre un chemin) (in dans le JSON de toc).
• --max-words N limite chaque section sélectionnée à N mots, donc un lot comme --section 27-58 --max-words 80 reste petit ; une section coupée se termine par [coupé à N sur M mots ; continuer avec --section S --offset C].
• --drop-repeated (read) supprime les courts paragraphes (40 mots ou moins) qui reviennent dans 30 % ou plus des sections, textuellement ou avec les mêmes quatre derniers mots une fois les chiffres réduits : crédits par image et avis de droits d'auteur dans les EPUB. Il supprime également une ligne de huit mots ou moins répétée dix fois ou plus à l'intérieur d'une section (un quart de ses paragraphes), comme le lien de retour « ALLER À LA NOTE DE RÉFÉRENCE DANS LE TEXTE » après chaque note de fin. Désactivé par défaut.
• --skip-code (read et grep) supprime les blocs de code trouvés par structure (EPUB et HTML <pre>, Markdown délimité ; les PDF n'ont pas de marqueur, donc pas là) et indique combien de mots ont été retirés. Les lignes de conseils viennent en une ligne à la fin ; --quiet les supprime.
• --lang CODE (read et grep, 0.43.0 ; en, de, es, fr, it, nl, pt) conserve les paragraphes dont les mots courants courts favorisent cette langue, pour une édition imprimant plusieurs langues côte à côte. Les égalités et les fragments de moins de 4 mots disparaissent, sauf les titres ; le code et les tableaux restent ; les mots collés par l'OCR comptent toujours. Le pied de page indique combien ont disparu, et --max-chars compte ce qui reste. info note un livre avec de nombreux paragraphes dans deux langues ou plus.
• --headings (read, 0.20.0) imprime uniquement les paragraphes de titre des sections choisies, indentés par niveau, chacun avec son numéro de paragraphe et les mots en dessous ; sautez avec --at-para P. Une section sans titres (un PDF sans structure) le dit : utilisez toc --group ou grep.
• --strip-boilerplate (read et grep) supprime les lignes répétées sur les pages d'un PDF : pieds de page, numéros de page nus, en-têtes courants, trouvés par leur fréquence de répétition. Utilisez-le sur les deux commandes pour que les numéros de paragraphe de grep correspondent à --at-para.
• Chaque section commence par une ligne d'en-tête : === [43/80] titre | id ... | mots | commence au mot N du TOTAL (P%) ===.
• La sortie s'arrête à --max-chars (par défaut 25 000). La coupure se fait à une limite de paragraphe, de ligne ou de phrase proche de la limite (0.11.1), et la dernière ligne indique alors où continuer : --offset N. Maintenez chaque lecture en dessous de la limite de sortie de votre outil shell : Claude Code affiche 30 000 caractères de la sortie d'une commande et sauvegarde le reste dans un fichier que vous devriez alors ouvrir. Pour deux longs chapitres, lisez-les un par un. Pour plus que cela, écrivez la sélection avec --out <scratch>/part.txt et ouvrez-la avec votre propre outil de lecture. Pour remettre plusieurs chapitres à un agent de lecture, --out-dir <scratch>/secs écrit chaque section sélectionnée dans son propre fichier (NNN-titre.txt) et liste leurs tailles (0.12.0).
• --section prend une liste et des plages en un seul appel : --section 61,80,87 ou --section 12,189-190. Les sections sont imprimées dans cet ordre, chacune avec son propre en-tête.
• Une courte sélection se termine par un indice nommant la section suivante lorsque cette section continue probablement le texte : la sélection est une page de titre ou une épigraphe (moins de 60 mots), ou la section suivante est sans titre, marquée comme continuée, ou répète le titre (0.15.0 ; il ne se déclenche plus sur chaque petite sous-section).
• read sans sélecteur refuse lorsque le texte dépasse la limite (code de sortie 2) et imprime le toc à la place. Ce refus est l'outil qui fonctionne : choisissez des sections.
• --format md conserve les titres et les listes en Markdown ; --out FICHIER écrit la sélection dans un fichier ; avec --max-chars, il coupe à une limite propre et imprime coupé aux caractères A-B sur N ; écrire le reste avec --offset B (0.15.1). --compact supprime la ligne vide entre les paragraphes (0.13.0) ; donnez-le à nouveau avec --offset.

Étape 4 : recherche

RW grep FICHIER "MOTIF" -C 1 --max 5 imprime chaque paragraphe correspondant avec son numéro de section et son titre, le numéro de paragraphe et un paragraphe de contexte de chaque côté. Les longs paragraphes sont tronqués autour de la correspondance (--width). --after N (-A N) ajoute N paragraphes après chaque résultat, affichés jusqu'à --width avec leurs sauts de ligne : le bloc de code ou la liste qui suit la phrase le nommant (0.15.0). Un motif sans lettre majuscule correspond à n'importe quelle casse (--case-sensitive force la casse exacte, -i force n'importe quelle casse), et -F prend une chaîne simple ; --count donne les correspondances par section, le moyen le plus rapide de trouver où un personnage ou un terme apparaît. Chaque ligne de résultat se termine par | offset N, le décalage de caractères par lequel read --section S --offset N commence ; read --section S --at-para P commence à un paragraphe. Utilisez-les lorsque toc note une section géante (signets qui s'arrêtent tôt) ; depuis 0.17.0, une telle section est d'abord coupée aux chapitres nommés par une table des matières imprimée ou une liste « Chapitre N, Titre », donc la note n'apparaît que lorsque cela échoue. Le code de sortie 1 signifie aucune correspondance. Recherchez avant de lire lorsque l'utilisateur demande où ou si quelque chose est mentionné.

RW rank FICHIER mots de sujet (0.24.0) classe les sections par BM25 pour quelques mots de sujet et imprime le score, les mots et les termes que chacune contient : quelle section lire en premier, où grep imprime les résultats dans l'ordre du livre. Les mots vides et les terminaisons de pluriel, -ed et -ing sont réduits, donc shingles trouve shingling ; un mot qui n'est pas dans le livre est nommé. --paras classe les paragraphes (les lignes de titre gagnent souvent : lisez à partir de là), --top N, --section, --k1 et --b comme dans BM25. Classez d'abord sur un long livre, puis grep à l'intérieur des meilleures sections.

Étape 5 : livre entier vers un fichier temporaire

Pour un travail qui nécessite plusieurs passages sur un long livre (chaque scène avec un personnage, une chronologie), exécutez RW dump FICHIER --out <scratch>/livre.txt une fois. Utilisez ensuite vos propres outils de recherche et de lecture sur ce fichier, jamais cat. Les marqueurs de section sont des lignes commençant par === [N/ ; --format md écrit des commentaires <!-- readwright section N/... --> avec des titres Markdown. Dump écrit sur stdout uniquement lorsque le texte fait moins de 25 000 caractères. Placez le fichier dans le dossier temporaire ou de travail de la session, jamais dans le dépôt de l'utilisateur.

Étape 6 : répondre

Citez brièvement. Pour un livre protégé par le droit d'auteur, résumez et citez une phrase ou deux à la fois, jamais des pages ou des chapitres entiers, même lorsque l'utilisateur possède la copie. Citez d'où vient chaque point (numéro de section et titre) afin que l'utilisateur puisse le vérifier. Lorsqu'une note de conversion a été imprimée (calibre, LibreOffice, pdftotext), mentionnez que le texte est passé par un convertisseur si le libellé est important.

Distiller un livre

• En s'appuyant sur les notes d'une lecture précédente : grep deux ou trois des passages qu'ils citent avant de les réutiliser, et lisez un chapitre que les notes ont sauté, afin que le nouveau compte rendu ajoute quelque chose et ne porte aucune erreur copiée.
• Une ligne de toc montrant (0 m) à côté de frères sur la même page signifie que son texte a atterri dans un voisin : lisez tout le groupe avec --section N-M. Les livres pratiques indiquent les tolérances de cadre ou de niveau comme une expérience ; citez-les comme celles de l'auteur, non comme mesurées.
• Recherchez une étude que l'auteur cite pour une affirmation forte, et enregistrez ses limites. Un livre populaire peut les omettre : l'un a rapporté une différence entre les sexes sans dire que l'article ne l'a trouvée que dans une partie de sa tranche d'âge.

Une large référence déjà lue pour un autre sujet : vérifiez ce que les notes précédentes visaient pour votre sujet, puis lisez les chapitres sur votre propre travail qu'elles ont sauté (une annexe d'évaluation, les chapitres d'analyse), répartis par type entre deux agents de lecture.

Un manuel de cinéma ou de radiodiffusion lu à nouveau pour un sujet sonore ou de montage : les notes précédentes ont généralement pris les chapitres théoriques ; allez dans les sections de montage et de pré-mixage (disposition des pistes, stems, transitions de scènes), qui contiennent les règles de travail. Lisez les sections choisies en un seul appel, read --section 248,250,251, pas un appel chacune.

Un livre pratique scanné lu via l'OCR (une section par page) : toc --chapters donne les plages de pages des chapitres ; puis grep les mots du sujet avec --section N-M à l'intérieur des chapitres que vous voulez et lisez uniquement les pages avec des résultats, car la plupart des pages sont des anecdotes et du vieux matériel.

Une section PDF plate avec des titres numérotés ou en majuscules : read --headings les liste, puis --at-para saute à celui que vous voulez.

Un PDF dont les signets s'arrêtent aux parties (toc prévient qu'une section détient une grande partie du texte) : read --section N --headings sur chaque grande section donne la véritable carte des chapitres, avec des numéros de paragraphe pour --at-para.

Un manuel édité : lisez d'abord l'introduction de l'éditeur, car elle indique quel chapitre couvre quoi, puis seulement les ouvertures de ces chapitres et tout passage sur la méthode. Chaque chapitre a ses propres auteurs, citez donc le chapitre et jugez-le seul.

Un guide pratique d'un métier voisin (son de théâtre lu pour des effets de jeu) : sautez les personnes et le matériel de la salle, lisez les chapitres sur la fabrication du matériel, et grep les mots du travail dans le reste. Un texte comme mu?ed peut être dans le fichier de l'éditeur ; vérifiez la source avant de blâmer le lecteur.

Une longue enquête historique : sautez les chapitres sur les instruments. Grep les mots de la méthode, lisez les chapitres sur ceux-ci, la conclusion, et tout passage où l'auteur juge...