m4bwav/readwright

readwright は何をしますか？

小説は15万～30万トークンあります。変換ツール（epr -d、pandoc -t plain、ebook-convert book.txt）でダンプすると、質問に答える前にコンテキストがいっぱいになってしまいます。readwright はエージェントに、単語数付きの目次、選択したセクション、そしてセクション番号と段落番号付きの検索結果を提供するため、タスクに必要な部分だけを読み取ることができ、無駄がありません。

以下の RW は python "<このフォルダ>/scripts/rw.py"（macOS と Linux では python3）を意味します。ランチャー scripts/rw.sh と scripts/rw.ps1 も同じことを行います。Python 3.10 以降が必要で、内蔵フォーマットにはそれ以外は不要です。RW formats で、このマシンが持っている外部ツールが表示されます。

ステップ 0: 最新状態の確認

evergreen.json を読んでください。contradiction が設定されているか、今日が next_due 以降の場合は、その旨を一行で伝え、タスクを実行した後、更新（MAINTENANCE.md）を行ってください。

Discord: ライブチャンネルはファイルではありません。everscout の scripts/es_discord.py（ユーザー自身が招待したボット、everscout kb/discord.md）を使用して読み取ってください。ユーザーがエクスポートしたチャンネル（JSON または HTML）は、ここにある他の JSON や HTML ファイルと同様に読み取れます。

ステップ 1: サイズの見積もり

RW info FILE を実行します。これにより、検出されたフォーマット（ファイルの拡張子ではなくバイトから）、タイトル、著者、言語、セクション数、単語数、およびおおよそのトークン数（文字数を 4 で割った値）が出力されます。約 6,000 トークン（25,000 文字）未満の場合は、RW read FILE で全文が出力されるので、ここで終了できます。

info が DRM を報告した場合は、その旨を明確に伝えて停止してください。readwright は DRM を決して解除しません。また、あなたも解除すべきではありません。ストアの独自リーダーまたは販売元からの DRM フリーのコピーを提案してください。不足しているツール（pdftotext、calibre の ebook-convert、LibreOffice）が指定された場合は、出力されるインストールコマンドをそのまま伝えてください。ユーザーの同意なしにインストールを行わないでください。PDF の場合は、エージェント自身の Read ツールを使用してページ範囲を指定する方が良い方法であることがよくあります。

info が note: no text layer と出力した場合、その書籍はページ画像（スキャン）であり、readwright には読み取るものがありません。指定された注記に記載されている方法を、その順序で試してください。まず、同じ書籍の別のフォーマットのコピーが隣にあれば、それを試します。DjVu コピーには OCR テキストが含まれていることがよくあります。次に、PDF の場合は RW ocr FILE を実行します。これにより、ページがレンダリングされ、Windows 10 および 11 に内蔵の OCR（またはインストールされている tesseract）が実行され、1 ページあたり約 1 秒かかり、25 ページごとに保存されます。テキストは ~/.readwright/ocr/ に保持されるため、その後同じファイルに対して info、toc、read、grep を実行すると、そのテキストが使用されます（--pages N-M で数ページのみ、--force で再実行）。書籍全体はバックグラウンドで実行してください。OCR は一部の文字を誤認識し、見出しがないため、セクションはページ単位になります。引用はページ画像と照合してください。最後に、RW page FILE 1-5（60 dpi、--dpi、--out-dir）で数ページをレンダリングし、あなた自身の画像リーダーで表示します。OCR ツールをインストールする前に確認を求めてください。

ステップ 2: アウトライン

RW toc FILE を実行します。各行は N. タイトル (単語数 w) で、レベルに応じてインデントされます。--ids は各セクションの ID（ファイルとフラグメント、ページ、シート）を追加しますが、これが必要になることはほとんどありません。EPUB のタイトルは書籍自身のナビゲーション（nav ドキュメントまたは NCX）から、DOCX と ODT のタイトルは見出しスタイルから、HTML は h1 から h3 まで、プレーンテキストと Markdown は見出しまたは CHAPTER 行から取得されます。構造がないテキストは、約 3,000 単語の部分に分割されます。zip アーカイブの場合、toc はメンバーをリストします。以降のすべてのコマンドに --member NAME（またはその番号）を追加してください。

各章番号がそれ自身のほとんど空のセクションとしてリストされる書籍（Packt、一部の O'Reilly）は、Ch. 12: タイトル としてマージされて表示されます。これはタイトルのセクション番号の下に出力されます（番号のみのセクションは非表示になりますが、番号は保持され、読み取ることもできます）。RW toc FILE --depth 1 は、最上位レベル（部や章）のみを出力し、各行の単語数はその下のセクションから集計されます（--depth 2 は次のレベルを追加します。JSON は chapter と words_total を取得します）。手動で数える代わりに、これを使用して章を数えてください。アウトラインのない PDF は、1 ページを 1 セクションとしてリストします。RW toc FILE --group は、同じ柱（running head）を共有するページをページ範囲（章）にまとめ、--section 20-40 で読み取ります。柱がない場合は、印刷された目次ページを使用します。各エントリはタイトル行の後にページ番号行が続くか（0.26.0）、エントリが Title ... 21 Next ... 26 のように続きます（0.35.0）。toc は注記でその旨を伝えます。

ユーザーの言葉を toc 行に一致させてください。「Chapter 14」は通常、CHAPTER FOURTEEN というタイトルの行を意味します。多くの電子書籍では、この行には章のタイトルとエピグラフのみが含まれており、その本文は次のセクションになります。単語数からそれがわかります（72 単語、次に 6,330 単語）。セクション番号は章番号ではありません。前付が最初に来るため、小説の第 16 章がセクション 24 になる可能性があります。

ステップ 3: 必要なものだけを読み取る

• RW read FILE --section 43-44（他にも N、N-、N,M が使用可能。--section を繰り返すと累積されます）または --title "正規表現"（大文字小文字を区別せず、タイトルと ID に対してマッチング。何もマッチしない場合はスペースが無視されるため、westgate は WEST GATE を見つけます）。
• --title が 300 単語未満のセクションにヒットした場合、その次のセクションが追加され、その旨の注記が表示されます。--with-next は任意の選択に対して同じことを行います。
• タイトルが本の中で 3 回以上繰り返されるセクション（「準備」、「実行手順...」、「さらに...」）は、その前にある最も近い識別可能な見出しと共に、read のヘッダーと toc に表示されます：How to do it... (in: Following a path)（toc JSON では in）。
• --max-words N は、選択された各セクションを N 単語に制限します。これにより、--section 27-58 --max-words 80 のようなバッチを小さく保つことができます。切り詰められたセクションは [cut at N of M words; continue with --section S --offset C] で終わります。
• --drop-repeated（read）は、30% 以上のセクションで繰り返される短い段落（40 単語以下）を削除します。これは、数字が統合された後の同じ最後の 4 単語を持つもの、または逐語的なものを含みます。EPUB の画像ごとのクレジットや著作権表示が該当します。また、1 つのセクション内で 10 回以上繰り返される 8 単語以下の行（段落の 4 分の 1）も削除します。例えば、すべての後注の後に続く「GO TO NOTE REFERENCE IN TEXT」のような戻るリンクが該当します。デフォルトではオフです。
• --skip-code（read と grep）は、構造によって検出されたコードブロック（EPUB と HTML の <pre>、フェンス付き Markdown。PDF にはマーカーがないため該当なし）を削除し、削除された単語数を表示します。アドバイス行は最後に 1 行として出力されます。--quiet はそれらを削除します。
• --lang CODE（read と grep、0.43.0。en、de、es、fr、it、nl、pt が使用可能）は、複数の言語が併記されている版のために、その言語の短い一般語が優勢な段落のみを保持します。4 単語未満の同点のものや断片は削除されますが、見出しは保持されます。コードとテーブルは保持されます。OCR で接着された単語もカウントされます。フッターには削除された単語数が表示され、--max-chars は残ったものをカウントします。info は、2 つ以上の言語の段落が多い書籍について注記します。
• --headings（read、0.20.0）は、選択されたセクションの見出し段落のみを、レベルに応じてインデントして出力します。各見出しには段落番号とその下の単語が表示されます。--at-para P でジャンプします。構造がない（アウトラインのない PDF など）セクションの場合は、その旨が表示されます。その場合は toc --group または grep を使用してください。
• --strip-boilerplate（read と grep）は、PDF のページ間で繰り返される行（フッター、ベアページ番号、柱）を削除します。これらは繰り返し頻度によって検出されます。両方のコマンドで使用して、grep の段落番号が --at-para と一致するようにしてください。
• すべてのセクションはヘッダー行で始まります：=== [43/80] タイトル | ID ... | 単語数 | TOTAL の単語 N 番目から開始 (P%) ===
• 出力は --max-chars（デフォルト 25,000）で停止します。カットは制限付近の段落、行、または文の区切りで行われ（0.11.1）、最後の行は継続場所を示します：--offset N。各読み取りをシェルツールの出力制限内に収めてください。Claude Code はコマンドの出力の 30,000 文字を表示し、残りはファイルに保存するため、後で開く必要があります。長い章が 2 つある場合は、それぞれを 1 回の呼び出しで読み取ってください。それ以上ある場合は、選択範囲を --out <scratch>/part.txt に書き込み、自身の Read ツールで開いてください。リーダーエージェントに複数の章を渡すには、--out-dir <scratch>/secs を使用すると、選択された各セクションが独自のファイル（NNN-title.txt）に書き込まれ、サイズがリストされます（0.12.0）。
• --section は、1 回の呼び出しでリストと範囲を受け付けます：--section 61,80,87 または --section 12,189-190。セクションは指定された順序で、それぞれ独自のヘッダーとともに出力されます。
• 短い選択範囲は、そのセクションがおそらくテキストを続けている場合、次のセクションを示すヒントで終わります。選択範囲がタイトルページまたはエピグラフ（60 単語未満）であるか、次のセクションが無題であるか、継続を示すマークがあるか、タイトルが繰り返されている場合です（0.15.0。小さなサブセクションごとに発動することはなくなりました）。
• テキストが制限を超えている場合、read はセレクタなしでは拒否され（終了コード 2）、代わりに toc が出力されます。この拒否はツールが機能していることを示します。セクションを選択してください。
• --format md は見出しとリストを Markdown として保持します。--out FILE は選択範囲をファイルに書き込みます。--max-chars と一緒に使用すると、適切な区切りでカットされ、cut at chars A-B of N; write the rest with --offset B と出力されます（0.15.1）。--compact は段落間の空行を削除します（0.13.0）。--offset と一緒に再度指定することもできます。

ステップ 4: 検索

RW grep FILE "パターン" -C 1 --max 5 は、一致する各段落を、セクション番号とタイトル、段落番号、および前後 1 段落のコンテキストとともに出力します。長い段落は一致箇所の周りでトリミングされます（--width）。--after N（-A N）は、各ヒットの後に N 段落を追加します。これらは --width まで、改行を含めて表示されます。これは、その文が名前を付けているコードブロックまたはリストをキャプチャするのに役立ちます（0.15.0）。大文字を含まないパターンは、大文字小文字を区別せずにマッチします（--case-sensitive は大文字小文字を強制し、-i は大文字小文字を問いません）。-F はプレーンな文字列を受け付けます。--count はセクションごとの一致数を提供し、特定の文字や用語がどこに出現するかを最も早く見つける方法です。各ヒット行は | offset N で終わります。これは read --section S --offset N が開始する文字オフセットです。read --section S --at-para P は段落から開始します。toc が 1 つの巨大なセクション（早期に停止するブックマーク）に言及している場合にこれらを使用します。0.17.0 以降では、そのようなセクションは、印刷された目次ページまたは「Chapter N, Title」リストが指定する章で最初にカットされるため、注記はそれが失敗した場合にのみ表示されます。終了コード 1 は一致がないことを意味します。ユーザーが何かがどこで言及されているか、または言及されているかどうかを尋ねた場合は、読み取る前に検索してください。

RW rank FILE トピック単語（0.24.0）は、いくつかのトピック単語に対して BM25 でセクションをランク付けし、スコア、単語数、および各セクションが保持する用語を出力します。どのセクションを最初に読むべきか、grep がブックの順序でヒットを出力する場所がわかります。ストップワードと複数形、-ed、-ing の語尾は統合されるため、shingles は shingling を見つけます。本に含まれていない単語は指定されます。--paras は段落をランク付けします（見出し行が勝つことが多いため、そこから読み取ってください）。--top N、--section、--k1、--b は BM25 と同様に使用します。長い本では最初にランク付けし、次にトップセクション内で grep します。

ステップ 5: 書籍全体をスクラッチファイルに

長い本に対して複数回のパスが必要な作業（特定のキャラクターが登場するすべてのシーン、タイムラインなど）には、RW dump FILE --out <scratch>/book.txt を一度実行します。その後、そのファイルに対して自身の検索ツールと読み取りツールを使用します。cat は絶対に使用しないでください。セクションマーカーは === [N/ で始まる行です。--format md は、Markdown 見出しとともに <!-- readwright section N/... --> コメントを書き込みます。Dump は、テキストが 25,000 文字未満の場合にのみ標準出力に書き込みます。ファイルはセッションのスクラッチフォルダまたはテンポラリフォルダに置き、ユーザーのリポジトリには決して置かないでください。

ステップ 6: 回答

簡潔に引用してください。著作権のある書籍の場合、ユーザーがコピーを所有している場合でも、要約し、一度に 1 文か 2 文だけを引用し、ページ全体や章全体を決して引用しないでください。各ポイントの出典（セクション番号とタイトル）を明記し、ユーザーが確認できるようにしてください。変換に関する注意が出力された場合（calibre、LibreOffice、pdftotext）、表現が重要な場合は、テキストがコンバーターを経由したものであることに言及してください。

書籍の蒸留

• 以前の読み取りのメモに基づいて構築する場合：再利用する前に、それらが引用している 2 つまたは 3 つの箇所を grep し、メモでスキップされた 1 つの章を読み取ってください。これにより、新しい書き起こしに何かが追加され、コピーされた誤りが含まれなくなります。
• 同じページ上の兄弟と一緒に (0 w) を示す toc 行は、そのテキストが隣接するセクションに配置されたことを意味します。--section N-M でグループ全体を読み取ってください。実務書はフレームまたはレベルの許容差を経験として示しています。それらを測定値としてではなく、著者のものとして引用してください。
• 著者が強い主張のために引用している研究を調査し、その限界を記録してください。一般向けの書籍はそれらを省略することがあります。ある研究では、年齢範囲の一部でのみ見られた性差を報告したにもかかわらず、その点が省略されている場合があります。

別の主題ですでに読まれた広範な参考文献：以前のメモがあなたの主題をどのように扱っているかを確認し、次に、それらがスキップした、あなた自身の仕事に関する章（評価の付録、分析の章）を読み、種類ごとに 2 つのリーダーエージェントに分割してください。

サウンドまたは編集の主題で再度読まれる映画または放送の教科書：以前のメモは通常、理論の章を扱っています。編集およびプレミックスセクション（トラックレイアウト、ステム、シーントランジション）に進んでください。これらには作業ルールが含まれています。選択したセクションは、read --section 248,250,251 のように 1 回の呼び出しで読み取ってください。1 回の呼び出しで 1 セクションずつ読まないでください。

OCR で読み取られたスキャンされた実務書（1 セクションあたり 1 ページ）：toc --chapters は章のページ範囲を提供します。次に、目的の章内で --section N-M を使用して主題の単語を grep し、ヒットのあるページのみを読み取ってください。ほとんどのページは逸話や古い機器に関するものです。

番号付きまたはすべて大文字の見出しを持つフラットな PDF セクション：read --headings でそれらをリストし、次に --at-para で目的の見出しにジャンプします。

ブックマークが部で停止する PDF（toc は 1 つのセクションがテキストの大部分を保持していると警告します）：各大きなセクションで read --section N --headings を実行すると、実際の章マップが得られ、--at-para の段落番号が付いています。

編集されたハンドブック：最初に編集者の序文を読んでください。どの章が何をカバーしているかが説明されています。その後、それらの章の冒頭と方法に関する箇所のみを読んでください。各章には独自の著者がいるため、章を引用し、それを単独で判断してください。

隣接する業界からのハウツー本（ゲーム効果音のために読まれる劇場音響）：人物や会場のハードウェアはスキップし、素材を作成する章を読み、残りの部分で仕事の単語を grep してください。mu?ed のようなテキストは出版社のファイルに含まれている可能性があります。リーダーを非難する前にソースを確認してください。

長い歴史の概説：楽器の章はスキップしてください。方法の単語を grep し、それらの章、結論、および著者が判断を下す箇所を読んでください。

…（翻訳のため省略）