m4bwav/readwright

¿Qué hace readwright?

Una novela tiene de 150.000 a 300.000 tokens. Volcarla con un conversor (epr -d, pandoc -t plain, ebook-convert book.txt) llena el contexto antes de que se responda la pregunta. readwright le da al agente un índice con conteos de palabras, luego las secciones elegidas y luego resultados de búsqueda con números de sección y párrafo, para que lea solo lo que la tarea necesita y nada más.

RW abajo significa python "<esta carpeta>/scripts/rw.py" (python3 en macOS y Linux). Los lanzadores scripts/rw.sh y scripts/rw.ps1 hacen lo mismo. Necesita Python 3.10 o más reciente y nada más para los formatos incorporados; RW formats muestra qué herramientas externas tiene esta máquina.

Paso 0: actualidad

Lee evergreen.json. Si contradiction está establecido o hoy es igual o posterior a next_due, dilo en una línea, haz la tarea y luego actualiza (MAINTENANCE.md). Las versiones de los conversores y los formatos de libros electrónicos cambian; el procedimiento a continuación no depende de ellos.

Discord: un canal en vivo no es un archivo; léelo con scripts/es_discord.py de everscout (el bot invitado por el usuario, everscout kb/discord.md). Una exportación de canal que hizo el usuario (JSON o HTML) se lee como cualquier archivo JSON o HTML aquí.

Paso 1: evaluar tamaño

Ejecuta RW info ARCHIVO. Imprime el formato detectado (por los bytes del archivo, no por su extensión), título, autor, idioma, número de secciones, palabras y tokens aproximados (caracteres divididos por 4). Por debajo de unos 6.000 tokens (25.000 caracteres), RW read ARCHIVO imprime el texto completo y puedes detenerte aquí.

Si info informa de DRM, dilo claramente y detente. readwright nunca elimina DRM, y tú tampoco debes hacerlo: sugiere el lector propio de la tienda o una copia sin DRM del vendedor. Si nombra una herramienta faltante (pdftotext, ebook-convert de calibre, LibreOffice), pasa la línea de instalación que imprime. Nunca instales nada sin el sí del usuario. Para un PDF, la herramienta de Lectura propia del agente con rangos de páginas suele ser la mejor opción.

Si info imprime note: no text layer, el libro son imágenes de página (un escaneo) y readwright no tiene nada que leer. Toma las rutas que nombre la nota, en su orden. Primero, una copia del mismo libro en otro formato junto a él; una copia DjVu suele llevar texto OCR. Luego, para un PDF, RW ocr ARCHIVO: renderiza las páginas y ejecuta el OCR incorporado en Windows 10 y 11 (o tesseract si está instalado), aproximadamente un segundo por página, guardando después de cada 25 páginas, y mantiene el texto en ~/.readwright/ocr/ para que info, toc, read y grep sobre el mismo archivo lo usen a partir de entonces (--pages N-M para unas pocas páginas, --force para rehacer). Ejecuta un libro completo en segundo plano. El OCR lee mal algunas letras y no tiene encabezados, por lo que las secciones son páginas; verifica una cita contra una imagen de página. Por último, unas pocas páginas renderizadas con RW page ARCHIVO 1-5 (60 dpi, --dpi, --out-dir) y visualizadas con tu propio lector de imágenes. Pregunta antes de instalar una herramienta OCR.

Paso 2: esquema

Ejecuta RW toc ARCHIVO. Cada línea es N. título (palabras p), con sangría por nivel; --ids agrega el id de cada sección (archivo y fragmento, página, hoja), que rara vez necesitas. Los títulos EPUB provienen de la navegación propia del libro (documento nav o NCX), los títulos DOCX y ODT de los estilos de encabezado, HTML de h1 a h3, texto plano y Markdown de encabezados o líneas CAPÍTULO. El texto sin estructura se divide en partes de unas 3.000 palabras. Para un archivo zip, toc lista los miembros; agrega --member NOMBRE (o su número) a cada comando posterior.

Los libros que listan cada número de capítulo como su propia sección casi vacía (Packt, algunos O'Reilly) se muestran fusionados: Cap. 12: Título, impreso bajo el número de sección del título (la sección solo con número está oculta pero conserva su número y aún se puede leer). RW toc ARCHIVO --depth 1 imprime solo el nivel superior (partes y capítulos) con las palabras de cada línea acumuladas de las secciones inferiores (--depth 2 agrega el siguiente nivel; JSON obtiene chapter y words_total). Úsalo para contar capítulos en lugar de contar a mano. Un PDF sin esquema lista una sección por página; RW toc ARCHIVO --group agrupa páginas que comparten un encabezado corrido en rangos de páginas (capítulos) para leer con --section 20-40; sin encabezados corridos usa la tabla de contenido impresa, donde cada entrada es una línea de título seguida de una línea de número de página (0.26.0), o las entradas continúan como Título ... 21 Siguiente ... 26 (0.35.0), y toc lo dice en una nota.

Relaciona las palabras del usuario con las líneas de toc. "Capítulo 14" suele referirse a la línea titulada CAPÍTULO CATORCE, que en muchos libros electrónicos contiene solo el título del capítulo y un epígrafe: su cuerpo es la siguiente sección. Los conteos de palabras lo muestran (72 palabras, luego 6.330). Los números de sección no son números de capítulo: el material preliminar va primero, por lo que el capítulo 16 de una novela puede ser la sección 24.

Paso 3: leer solo lo necesario

• RW read ARCHIVO --section 43-44 (también N, N-, N,M; un --section repetido se acumula) o --title "REGEX" (sin distinción de mayúsculas/minúsculas, comparado con títulos e ids; cuando no coincide nada, se ignoran los espacios, por lo que westgate encuentra WEST GATE).
• Cuando --title aterriza en una sección de menos de 300 palabras, la sección siguiente se agrega y una nota lo dice. --with-next hace lo mismo para cualquier selección.
• Una sección cuyo título se repite 3 o más veces en el libro ("Getting ready", "How to do it...", "There's more...") se muestra con el encabezado distintivo más cercano antes de ella, en los encabezados de read y en toc: How to do it... (en: Following a path) (en en toc JSON).
• --max-words N limita cada sección seleccionada a N palabras, por lo que un lote como --section 27-58 --max-words 80 se mantiene pequeño; una sección cortada termina [cortado en N de M palabras; continúa con --section S --offset C].
• --drop-repeated (read) elimina párrafos cortos (40 palabras o menos) que se repiten en un 30% o más de las secciones, textualmente o con las mismas cuatro últimas palabras una vez que se pliegan los dígitos: créditos de imágenes y avisos de derechos de autor en EPUB. También elimina una línea de ocho palabras o menos repetida diez veces o más dentro de una sección (una cuarta parte de sus párrafos), como el enlace de retorno "GO TO NOTE REFERENCE IN TEXT" después de cada nota al final. Desactivado por defecto.
• --skip-code (read y grep) elimina los bloques de código encontrados por estructura (EPUB y HTML <pre>, Markdown delimitado; los PDF no tienen marcador, por lo que no están allí) y dice cuántas palabras se fueron. Las líneas de consejo vienen como una línea al final; --quiet las elimina.
• --lang CÓDIGO (read y grep, 0.43.0; en, de, es, fr, it, nl, pt) mantiene los párrafos cuyas palabras comunes cortas favorecen ese idioma, para una edición que imprime varios uno al lado del otro. Los empates y fragmentos de menos de 4 palabras se eliminan, excepto los encabezados; el código y las tablas se quedan; las palabras unidas por OCR aún cuentan. El pie de página dice cuántas se fueron, y --max-chars cuenta lo que queda. info nota un libro con muchos párrafos en dos o más idiomas.
• --headings (read, 0.20.0) imprime solo los párrafos de encabezado de las secciones elegidas, con sangría por nivel, cada uno con su número de párrafo y las palabras debajo; salta con --at-para P. Una sección sin encabezados (un PDF sin estructura) lo dice: usa toc --group o grep.
• --strip-boilerplate (read y grep) elimina líneas repetidas en las páginas de un PDF: pies de página, números de página solos, encabezados corridos, encontrados por la frecuencia con que se repiten. Úsalo en ambos comandos para que los números de párrafo de grep coincidan con --at-para.
• Cada sección comienza con una línea de encabezado: === [43/80] título | id ... | palabras | comienza en la palabra N de TOTAL (P%) ===.
• La salida se detiene en --max-chars (por defecto 25.000). El corte termina en un límite de párrafo, línea u oración cerca del límite (0.11.1), y la última línea dice entonces dónde continuar: --offset N. Mantén cada lectura por debajo del límite de salida de tu herramienta de shell: Claude Code muestra 30.000 caracteres de la salida de un comando y guarda el resto en un archivo que luego tendrías que abrir. Para dos capítulos largos, léelos en una llamada cada uno. Para más que eso, escribe la selección con --out <scratch>/parte.txt y ábrela con tu propia herramienta de Lectura. Para entregar varios capítulos a un agente lector, --out-dir <scratch>/secs escribe cada sección seleccionada en su propio archivo (NNN-titulo.txt) y lista sus tamaños (0.12.0).
• --section toma una lista y rangos en una sola llamada: --section 61,80,87 o --section 12,189-190. Las secciones se imprimen en ese orden, cada una con su propio encabezado.
• Una selección corta termina con una pista que nombra la siguiente sección cuando esa sección probablemente continúa el texto: la selección es una página de título o epígrafe (menos de 60 palabras), o la siguiente sección no tiene título, está marcada como continuación o repite el título (0.15.0; ya no se activa en cada subsección pequeña).
• read sin un selector se niega cuando el texto supera el límite (código de salida 2) e imprime el toc en su lugar. Esa negativa es la herramienta funcionando: elige secciones.
• --format md mantiene los encabezados y listas como Markdown; --out ARCHIVO escribe la selección en un archivo; con --max-chars corta en un límite limpio e imprime cortado en caracteres A-B de N; escribe el resto con --offset B (0.15.1). --compact elimina la línea en blanco entre párrafos (0.13.0); dale de nuevo con --offset.

Paso 4: buscar

RW grep ARCHIVO "PATRÓN" -C 1 --max 5 imprime cada párrafo coincidente con su número de sección y título, número de párrafo y un párrafo de contexto a cada lado. Los párrafos largos se recortan alrededor de la coincidencia (--width). --after N (-A N) agrega N párrafos después de cada resultado, mostrados hasta --width con sus saltos de línea: el bloque de código o lista que sigue a la oración que lo nombra (0.15.0). Un patrón sin letras mayúsculas coincide con cualquier caso (--case-sensitive fuerza mayúsculas/minúsculas exactas, -i fuerza cualquier caso), y -F toma una cadena simple; --count da coincidencias por sección, la forma más rápida de encontrar dónde aparece un personaje o término. Cada línea de resultado termina | offset N, el desplazamiento de caracteres en el que comienza read --section S --offset N; read --section S --at-para P comienza en un párrafo. Úsalos cuando toc note una sección gigante (marcadores que se detienen temprano); desde 0.17.0, dicha sección se corta primero en los capítulos que nombra una tabla de contenido impresa o una lista "Capítulo N, Título", por lo que la nota solo se muestra cuando eso falla. El código de salida 1 significa que no hay coincidencia. Busca antes de leer cuando el usuario pregunte dónde o si se menciona algo.

RW rank ARCHIVO palabras tema (0.24.0) clasifica las secciones por BM25 para algunas palabras del tema e imprime la puntuación, las palabras y los términos que contiene cada una: qué sección leer primero, donde grep imprime resultados en el orden del libro. Las palabras vacías y las terminaciones plural, -ed y -ing se pliegan, por lo que shingles encuentra shingling; una palabra que no está en el libro se nombra. --paras clasifica párrafos (las líneas de encabezado a menudo ganan: lee desde allí), --top N, --section, --k1 y --b como en BM25. Clasifica primero en un libro largo, luego grep dentro de las mejores secciones.

Paso 5: libro completo a un archivo temporal

Para trabajo que necesita múltiples pasadas sobre un libro largo (cada escena con un personaje, una línea de tiempo), ejecuta RW dump ARCHIVO --out <scratch>/libro.txt una vez. Luego usa tus propias herramientas de búsqueda y lectura en ese archivo, nunca cat. Los marcadores de sección son líneas que comienzan con === [N/; --format md escribe comentarios <!-- readwright section N/... --> con encabezados Markdown. Dump escribe en la salida estándar solo cuando el texto tiene menos de 25.000 caracteres. Coloca el archivo en la carpeta temporal o de trabajo de la sesión, nunca en el repositorio del usuario.

Paso 6: responder

Cita brevemente. Para un libro con derechos de autor, resume y cita una o dos oraciones a la vez, nunca páginas o capítulos completos, incluso si el usuario posee la copia. Cita de dónde vino cada punto (número de sección y título) para que el usuario pueda verificarlo. Cuando se imprimió una nota de conversión (calibre, LibreOffice, pdftotext), menciona que el texto pasó por un conversor si la redacción es importante.

Destilar un libro

• Basándose en notas de una lectura anterior: busca dos o tres de los pasajes que citan antes de reutilizarlos y lee un capítulo que las notas omitieron, para que el nuevo resumen agregue algo y no lleve un desliz copiado.
• Una fila de toc que muestra (0 p) junto a hermanos en la misma página significa que su texto terminó en un vecino: lee el grupo completo con --section N-M. Los libros de práctica establecen tolerancias de marco o nivel como experiencia; cítalos como del autor, no como medidos.
• Busca un estudio que el autor cita para una afirmación sólida y registra sus límites. Un libro popular puede omitirlos: uno informó una diferencia de sexo sin decir que el artículo la encontró solo en parte de su rango de edad.

Una referencia amplia ya leída para otro tema: verifica qué apuntaban las notas anteriores a tu tema, luego lee los capítulos sobre tu propio trabajo que omitieron (un apéndice de evaluación, los capítulos de análisis), divididos por tipo entre dos agentes lectores.

Un libro de texto de cine o transmisión leído de nuevo para un tema de sonido o edición: las notas anteriores solían tomar los capítulos de teoría; ve a las secciones de edición y premezcla (diseño de pistas, stems, transiciones de escena), que contienen las reglas de trabajo. Lee las secciones elegidas en una sola llamada, read --section 248,250,251, no una llamada cada una.

Un libro de práctica escaneado leído a través de OCR (una sección por página): toc --chapters da los rangos de páginas de los capítulos; luego busca las palabras del tema con --section N-M dentro de los capítulos que quieras y lee solo las páginas con resultados, ya que la mayoría de las páginas son anécdotas y equipo antiguo.

Una sección PDF plana con encabezados numerados o en mayúsculas completas: read --headings los lista, luego --at-para salta al que quieras.

Un PDF cuyos marcadores se detienen en las partes (toc advierte que una sección contiene una gran parte del texto): read --section N --headings en cada sección grande da el mapa de capítulos real, con números de párrafo para --at-para.

Un manual editado: lee primero la introducción del editor, ya que dice qué capítulo cubre qué, luego solo las aperturas de esos capítulos y cualquier pasaje sobre el método. Cada capítulo tiene sus propios autores, así que cita el capítulo y juégalo solo.

Un manual de un oficio vecino (sonido teatral leído para efectos de juego): salta a las personas y el hardware del lugar, lee los capítulos sobre cómo hacer el material y busca las palabras del trabajo en el resto. Texto como mu?ed puede estar en el archivo del editor; verifica la fuente antes de culpar al lector.

Un estudio histórico largo: salta los capítulos de instrumentos. Busca las palabras del método, lee los capítulos sobre esos, la conclusión y cualquier pasaje donde el autor juzgue.