m4bwav/readwright

O que readwright faz?

Um romance tem de 150.000 a 300.000 tokens. Despejá-lo com um conversor (epr -d, pandoc -t plain, ebook-convert book.txt) preenche o contexto antes mesmo de a pergunta ser respondida. O readwright fornece ao agente um sumário com contagens de palavras, depois as seções escolhidas e, por fim, resultados de pesquisa com números de seção e parágrafo, para que leia apenas o que a tarefa precisa e nada mais.

RW abaixo significa python "<esta pasta>/scripts/rw.py" (python3 no macOS e Linux). Os lançadores scripts/rw.sh e scripts/rw.ps1 fazem o mesmo. Ele precisa de Python 3.10 ou mais recente e nada mais para os formatos nativos; RW formats mostra quais ferramentas externas esta máquina possui.

Etapa 0: atualização

Leia evergreen.json. Se contradiction estiver definido ou a data de hoje for igual ou posterior a next_due, informe isso em uma linha, execute a tarefa e, em seguida, atualize (MAINTENANCE.md). As versões do conversor e os formatos de ebook mudam; o procedimento abaixo não depende deles.

Discord: um canal ao vivo não é um arquivo; leia-o com o scripts/es_discord.py do everscout (o próprio bot convidado pelo usuário, everscout kb/discord.md). Uma exportação de canal que o usuário fez (JSON ou HTML) é lida como qualquer arquivo JSON ou HTML aqui.

Etapa 1: avaliar o tamanho

Execute RW info ARQUIVO. Ele imprime o formato detectado (pelos bytes do arquivo, não pela extensão), título, autor, idioma, número de seções, palavras e tokens aproximados (caracteres divididos por 4). Abaixo de aproximadamente 6.000 tokens (25.000 caracteres), RW read ARQUIVO imprime o texto inteiro e você pode parar por aqui.

Se a informação informar DRM, diga isso claramente e pare. O readwright nunca remove DRM, e você também não deve: sugira o próprio leitor da loja ou uma cópia livre de DRM do vendedor. Se ele nomear uma ferramenta ausente (pdftotext, ebook-convert do calibre, LibreOffice), repasse a linha de instalação que ele imprime. Nunca instale nada sem a permissão do usuário. Para um PDF, a própria ferramenta de Leitura do agente com intervalos de páginas geralmente é o melhor caminho.

Se info imprimir note: no text layer, o livro é composto por imagens de página (um escaneamento) e o readwright não tem nada para ler. Siga as rotas que a nota nomeia, na ordem delas. Primeiro, uma cópia do mesmo livro em outro formato ao lado; uma cópia DjVu geralmente contém texto de OCR. Em seguida, para um PDF, RW ocr ARQUIVO: ele renderiza as páginas e executa o OCR integrado ao Windows 10 e 11 (ou tesseract, se instalado), cerca de um segundo por página, salvando após cada 25 páginas, e mantém o texto em ~/.readwright/ocr/ para que info, toc, read e grep no mesmo arquivo o usem a partir de então (--pages N-M para algumas páginas, --force para refazer). Execute um livro inteiro em segundo plano. O OCR lê mal algumas letras e não tem cabeçalhos, portanto as seções são páginas; verifique uma citação com uma imagem de página. Por último, algumas páginas renderizadas com RW page ARQUIVO 1-5 (60 dpi, --dpi, --out-dir) e visualizadas com seu próprio leitor de imagens. Pergunte antes de instalar uma ferramenta de OCR.

Etapa 2: esboço

Execute RW toc ARQUIVO. Cada linha é N. título (palavras p), indentada por nível; --ids adiciona o id de cada seção (arquivo e fragmento, página, planilha), que raramente é necessário. Os títulos EPUB vêm da própria navegação do livro (documento nav ou NCX), os títulos DOCX e ODT dos estilos de cabeçalho, HTML de h1 a h3, texto simples e Markdown de cabeçalhos ou linhas CHAPTER. Texto sem estrutura é dividido em partes de aproximadamente 3.000 palavras. Para um arquivo zip, toc lista os membros; adicione --member NOME (ou seu número) a todos os comandos posteriores.

Livros que listam cada número de capítulo como sua própria seção quase vazia (Packt, alguns O'Reilly) são mostrados mesclados: Ch. 12: Título, impresso sob o número de seção do título (a seção somente numérica fica oculta, mas mantém seu número e ainda pode ser lida). RW toc ARQUIVO --depth 1 imprime apenas o nível superior (partes e capítulos) com as palavras de cada linha acumuladas das seções abaixo dele (--depth 2 adiciona o próximo nível; JSON obtém chapter e words_total). Use-o para contar capítulos em vez de contar manualmente. Um PDF sem sumário lista uma seção por página; RW toc ARQUIVO --group agrupa páginas que compartilham um cabeçalho corrente em intervalos de páginas (capítulos) para ler com --section 20-40; sem cabeçalhos correntes, ele usa a página de conteúdo impressa, onde cada entrada é uma linha de título seguida por uma linha de número de página (0.26.0), ou as entradas continuam como Título ... 21 Próximo ... 26 (0.35.0), e toc informa isso em uma nota.

Combine as palavras do usuário com as linhas de toc. "Capítulo 14" geralmente significa a linha intitulada CAPÍTULO QUATORZE, que em muitos ebooks contém apenas o título do capítulo e um epígrafe: seu corpo é a próxima seção. As contagens de palavras mostram isso (72 palavras, depois 6.330). Os números de seção não são números de capítulo: o material de abertura vem primeiro, portanto o capítulo 16 de um romance pode ser a seção 24.

Etapa 3: ler apenas o necessário

• RW read ARQUIVO --section 43-44 (também N, N-, N,M; um --section repetido é acumulado) ou --title "REGEX" (insensível a maiúsculas/minúsculas, correspondido contra títulos e ids; quando nada corresponde, espaços são ignorados, então westgate encontra WEST GATE).
• Quando --title encontra uma seção com menos de 300 palavras, a seção seguinte é adicionada e uma nota informa isso. --with-next faz o mesmo para qualquer seleção.
• Uma seção cujo título se repete 3 ou mais vezes no livro ("Preparando", "Como fazer...", "Há mais...") é mostrada com o título distintivo mais próximo antes dela, nos cabeçalhos de read e em toc: Como fazer... (em: Seguindo um caminho) (in no JSON de toc).
• --max-words N limita cada seção selecionada a N palavras, para que um lote como --section 27-58 --max-words 80 permaneça pequeno; uma seção cortada termina com [cortado em N de M palavras; continue com --section S --offset C].
• --drop-repeated (read) remove parágrafos curtos (40 palavras ou menos) que ocorrem em 30% ou mais das seções, ipsis litteris ou com as mesmas últimas quatro palavras, uma vez que os dígitos são dobrados: créditos de imagem e avisos de direitos autorais em EPUBs. Também remove uma linha de oito palavras ou menos repetida dez vezes ou mais dentro de uma seção (um quarto de seus parágrafos), como o back-link "VOLTAR À NOTA DE REFERÊNCIA NO TEXTO" após cada nota final. Desativado por padrão.
• --skip-code (read e grep) remove blocos de código encontrados pela estrutura (EPUB e HTML <pre>, Markdown cercado; PDFs não têm marcador, portanto não estão lá) e informa quantas palavras foram removidas. As linhas de conselho vêm como uma linha no final; --quiet as remove.
• --lang CODE (read e grep, 0.43.0; en, de, es, fr, it, nl, pt) mantém os parágrafos cujas palavras comuns curtas favorecem esse idioma, para uma edição que imprime vários lado a lado. Empates e fragmentos com menos de 4 palavras são removidos, exceto cabeçalhos; código e tabelas permanecem; palavras coladas pelo OCR ainda contam. O rodapé informa quantas foram removidas, e --max-chars conta o que sobrou. info observa um livro com muitos parágrafos em dois ou mais idiomas.
• --headings (read, 0.20.0) imprime apenas os parágrafos de cabeçalho das seções escolhidas, indentados por nível, cada um com seu número de parágrafo e as palavras abaixo dele; pule com --at-para P. Uma seção sem cabeçalhos (um PDF sem estrutura) informa isso: use toc --group ou grep.
• --strip-boilerplate (read e grep) remove linhas repetidas nas páginas de um PDF: rodapés, números de página nus, cabeçalhos correntes, encontrados pela frequência com que se repetem. Use-o em ambos os comandos para que os números de parágrafo do grep correspondam a --at-para.
• Cada seção começa com uma linha de cabeçalho: === [43/80] título | id ... | palavras | começa na palavra N do TOTAL (P%) ===.
• A saída para em --max-chars (padrão 25.000). O corte termina em uma quebra de parágrafo, linha ou frase perto do limite (0.11.1), e a última linha informa onde continuar: --offset N. Mantenha cada leitura abaixo do limite de saída da sua ferramenta de shell: Claude Code mostra 30.000 caracteres da saída de um comando e salva o restante em um arquivo que você teria que abrir. Para dois capítulos longos, leia-os em uma chamada cada. Para mais do que isso, escreva a seleção com --out <scratch>/part.txt e abra-a com sua própria ferramenta de Leitura. Para entregar vários capítulos a um agente leitor, --out-dir <scratch>/secs escreve cada seção selecionada em seu próprio arquivo (NNN-title.txt) e lista seus tamanhos (0.12.0).
• --section aceita uma lista e intervalos em uma chamada: --section 61,80,87 ou --section 12,189-190. As seções são impressas nessa ordem, cada uma com seu próprio cabeçalho.
• Uma seleção curta termina com uma dica nomeando a próxima seção quando essa seção provavelmente dá continuidade ao texto: a seleção é uma página de título ou epígrafe (menos de 60 palavras), ou a próxima seção não tem título, é marcada como continuação ou repete o título (0.15.0; não é mais acionada em cada pequena subseção).
• read sem um seletor recusa quando o texto está acima do limite (código de saída 2) e imprime o toc. Essa recusa é a ferramenta funcionando: escolha seções.
• --format md mantém cabeçalhos e listas como Markdown; --out ARQUIVO escreve a seleção em um arquivo; com --max-chars ele corta em uma quebra limpa e imprime cortado em caracteres A-B de N; escreva o resto com --offset B (0.15.1). --compact remove a linha em branco entre parágrafos (0.13.0); repita-o com --offset.

Etapa 4: pesquisa

RW grep ARQUIVO "PADRÃO" -C 1 --max 5 imprime cada parágrafo correspondente com seu número de seção e título, número de parágrafo e um parágrafo de contexto de cada lado. Parágrafos longos são truncados em torno da correspondência (--width). --after N (-A N) adiciona N parágrafos após cada ocorrência, mostrados até --width com suas quebras de linha: o bloco de código ou lista que segue a frase que o nomeia (0.15.0). Um padrão sem letras maiúsculas corresponde a qualquer caso (--case-sensitive força maiúsculas/minúsculas, -i força qualquer caso), e -F aceita uma string simples; --count fornece correspondências por seção, a maneira mais rápida de encontrar onde um personagem ou termo aparece. Cada linha de ocorrência termina com | offset N, o deslocamento de caractere onde read --section S --offset N começa; read --section S --at-para P começa em um parágrafo. Use-os quando o toc notar uma seção gigante (marcadores que param cedo); desde 0.17.0, essa seção é primeiro cortada nos capítulos que uma página de conteúdo impressa ou uma lista "Capítulo N, Título" nomeia, para que a nota apareça apenas quando isso falha. Código de saída 1 significa nenhuma correspondência. Pesquise antes de ler quando o usuário perguntar onde ou se algo é mencionado.

RW rank ARQUIVO palavras do tópico (0.24.0) classifica seções por BM25 para algumas palavras do tópico e imprime pontuação, palavras e os termos que cada uma contém: qual seção ler primeiro, onde o grep imprime ocorrências na ordem do livro. Stop words e terminações de plural, -ed e -ing são dobradas, então shingles encontra shingling; uma palavra que não está no livro é nomeada. --paras classifica parágrafos (linhas de cabeçalho frequentemente vencem: leia a partir daí), --top N, --section, --k1 e --b como no BM25. Classifique primeiro em um livro longo, depois use grep dentro das principais seções.

Etapa 5: livro inteiro para um arquivo temporário

Para trabalhos que precisam de várias passagens sobre um livro longo (cada cena com um personagem, uma linha do tempo), execute RW dump ARQUIVO --out <scratch>/book.txt uma vez. Em seguida, use suas próprias ferramentas de pesquisa e leitura nesse arquivo, nunca cat. Os marcadores de seção são linhas começando com === [N/; --format md escreve comentários <!-- readwright section N/... --> com cabeçalhos Markdown. Dump escreve na saída padrão apenas quando o texto tem menos de 25.000 caracteres. Coloque o arquivo na pasta temporária ou de rascunho da sessão, nunca no repositório do usuário.

Etapa 6: responder

Cite brevemente. Para um livro com direitos autorais, resuma e cite uma ou duas frases por vez, nunca páginas ou capítulos inteiros, mesmo quando o usuário possui a cópia. Cite de onde veio cada ponto (número de seção e título) para que o usuário possa verificar. Quando uma nota de conversão foi impressa (calibre, LibreOffice, pdftotext), mencione que o texto passou por um conversor se a redação for importante.

Destilando um livro

• Com base em anotações de uma leitura anterior: pesquise (grep) duas ou três das passagens que elas citam antes de reutilizá-las e leia um capítulo que as anotações pularam, para que o novo texto adicione algo e não carregue um deslize copiado.
• Uma linha de toc mostrando (0 p) ao lado de irmãos na mesma página significa que seu texto caiu em um vizinho: leia o grupo inteiro com --section N-M. Livros de praticantes afirmam tolerâncias de quadro ou nível como experiência; cite-os como do autor, não como medidos.
• Procure um estudo que o autor cita para uma afirmação forte e registre seus limites. Um livro popular pode omiti-los: um relatou uma diferença sexual sem dizer que o artigo a encontrou apenas em parte de sua faixa etária.

Uma referência ampla já lida para outro assunto: verifique o que as anotações anteriores visavam no seu assunto e, em seguida, leia os capítulos sobre seu próprio trabalho que elas pularam (um apêndice de avaliação, os capítulos de análise), divididos por tipo entre dois agentes leitores.

Um livro didático de cinema ou rádio lido novamente para um assunto de som ou edição: as anotações anteriores geralmente pegaram os capítulos teóricos; vá para as seções de edição e pré-mixagem (layout de faixas, stems, transições de cena), que contêm as regras práticas. Leia as seções escolhidas em uma chamada, read --section 248,250,251, não uma chamada cada.

Um livro de praticante escaneado lido por OCR (uma seção por página): toc --chapters fornece os intervalos de páginas do capítulo; em seguida, pesquise as palavras do assunto com --section N-M dentro dos capítulos desejados e leia apenas as páginas com ocorrências, já que a maioria das páginas são anedotas e equipamentos antigos.

Uma seção de PDF plana com cabeçalhos numerados ou em maiúsculas: read --headings os lista, então --at-para pula para o desejado.

Um PDF cujos marcadores param nas partes (o toc avisa que uma seção contém uma grande parcela do texto): read --section N --headings em cada seção grande fornece o mapa real do capítulo, com números de parágrafo para --at-para.

Um manual editado: leia primeiro a introdução do editor, pois ela diz qual capítulo cobre o quê, depois apenas as aberturas desses capítulos e qualquer passagem sobre método. Cada capítulo tem seus próprios autores, então cite o capítulo e julgue-o sozinho.

Um guia prático de uma profissão vizinha (som teatral lido para efeitos de jogo): pule as pessoas e o hardware do local, leia os capítulos sobre como fazer o material e pesquise as palavras do trabalho no restante. Texto como mu?ed pode estar no arquivo da editora; verifique a fonte antes de culpar o leitor.

Uma longa pesquisa histórica: pule os capítulos sobre instrumentos. Pesquise as palavras do método, leia os capítulos sobre eles, a conclusão e qualquer passagem onde o autor julga...