readwright

readwright 是做什麼的？

一本小說有 150,000 到 300,000 個 Token。使用轉換器（如 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。它會輸出檢測到的格式（根據檔案的位元組，而非副檔名）、標題、作者、語言、章節數量、字數以及估算的 Token 數（字元數除以 4）。如果少於約 6,000 個 Token（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），大約每秒一頁，每 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. title (words w) 並按層級縮排；--ids 會添加每個章節的 ID（檔案和片段、頁面、工作表），但您很少需要。EPUB 的標題來自書籍本身的導航（nav document 或 NCX），DOCX 和 ODT 的標題來自標題樣式，HTML 來自 h1 到 h3，純文字和 Markdown 來自標題或 CHAPTER 行。沒有結構的文字會被切割成約 3,000 字的部分。對於 zip 壓縮檔，toc 會列出其中的成員；請在之後的每個命令中添加 --member NAME（或其編號）。

那些將每個章節號碼列為自己幾乎為空章節的書籍（如 Packt、某些 O'Reilly 的書）會以合併方式顯示：Ch. 12: Title，並印在該標題的章節號碼下方（僅數字號碼的章節會被隱藏，但保留其編號且仍可讀取）。RW toc FILE --depth 1 僅輸出頂層（部分和章節），並將每行的字數從其下屬章節匯總（--depth 2 添加下一層級；JSON 格式會獲得 chapter 和 words_total）。用它來計算章節數量，而不是手動計算。沒有大綱的 PDF 會將每個頁面列為一個章節；RW toc FILE --group 會將共享相同頁首的頁面摺疊成頁面範圍（章節），以便使用 --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 "REGEX"（不區分大小寫，匹配標題和 ID；當沒有匹配時，會忽略空格，因此 westgate 可以找到 WEST GATE）。
• 當 --title 落在一個少於 300 字的章節時，它會自動添加該章節之後的一個章節，並顯示一條提示。--with-next 對任何選擇都執行相同操作。
• 一個在書中重複出現 3 次或以上的章節標題（如 "Getting ready"、"How to do it..."、"There's more..."），會在 read 的頁首和 toc 中顯示其之前最近的獨特標題：How to do it... (in: Following a path)（在 toc JSON 中為 in）。
• --max-words N 會將每個選定章節截斷為 N 個單詞，因此像 --section 27-58 --max-words 80 這樣的批次操作可以保持簡短；被截斷的章節結尾會顯示 [截斷於 N/M 字；使用 --section S --offset C 繼續]。
• --drop-repeated（read 命令）會丟棄在 30% 或以上的章節中重複出現的短段落（40 字或更少），無論是完全相同還是折疊數字後最後四個單詞相同：例如 EPUB 中每張圖片的圖片來源資訊和版權聲明。它還會丟棄在一個章節內重複十次或以上的八個字或更少的行（佔該章節段落的四分之一），例如每條尾註後面的 "GO TO NOTE REFERENCE IN TEXT" 返回連結。預設為關閉。
• --skip-code（read 和 grep 命令）會丟棄通過結構找到的程式碼區塊（EPUB 和 HTML 的 <pre>、圍欄式 Markdown；PDF 沒有標記，因此不在此列）並說明丟棄了多少字。提示訊息會在最後一行顯示；--quiet 則會隱藏它們。
• --lang CODE（read 和 grep 命令，0.43.0 版；支援 en, de, es, fr, it, nl, pt）會保留那些短常見詞傾向於該語言的段落，適用於並列印刷多種語言的版本。少於 4 個詞的片段和未確定的內容會被丟棄，但標題除外；程式碼和表格會保留；OCR 黏合在一起的單詞仍會計數。頁尾會說明丟棄了多少內容，而 --max-chars 會計算剩餘的內容。info 會註記一本書中是否有許多段落使用兩種或多種語言。
• --headings（read 命令，0.20.0 版）僅輸出所選章節的標題段落，按層級縮排，每個標題附帶其段落編號及其下的字數；使用 --at-para P 跳轉。如果一個章節沒有標題（例如沒有結構的 PDF），它會說明：請改用 toc --group 或 grep。
• --strip-boilerplate（read 和 grep 命令）會根據重複的頻率，丟棄 PDF 頁面中重複的行：如頁尾、純頁碼、頁首。在兩個命令上都使用它，以便 grep 的段落編號能與 --at-para 匹配。
• 每個章節都以一個頁首行開頭：=== [43/80] title | id ... | words | starts at word N of TOTAL (P%) ===。
• 輸出會在達到 --max-chars（預設 25,000）時停止。截斷會發生在接近限制的段落、行或句子邊界（0.11.1 版），然後最後一行會說明從何處繼續：--offset N。請確保每次讀取不超過您 shell 工具的輸出限制：Claude Code 顯示命令輸出的前 30,000 個字元，並將其餘部分儲存到一個您之後需要手動開啟的檔案。對於兩個較長的章節，請分別調用一次讀取。對於更多章節，請使用 --out <scratch>/part.txt 將選取內容寫入檔案，然後使用您自己的 Read 工具開啟。若要將多個章節傳遞給一個閱讀代理，請使用 --out-dir <scratch>/secs，這會將每個選定的章節寫入各自的檔案（NNN-title.txt）並列出它們的大小（0.12.0 版）。
• --section 可以在一次調用中接受列表和範圍：--section 61,80,87 或 --section 12,189-190。章節將按該順序列印，每個都有各自的頁首。
• 一個簡短的選取結尾會包含一個提示，指出下一個章節（當該章節可能繼續正文時）：例如選取的內容是標題頁或題詞（少於 60 字），或者下一個章節沒有標題、標記為 "continued" 或重複了標題（0.15.0 版；不再對每個小節都觸發）。
• 當文字超過限制時，未指定選擇器的 read 命令會拒絕執行（退出碼 2）並輸出 toc。這是工具的正常運作方式：請選擇章節。
• --format md 會將標題和列表保留為 Markdown 格式；--out FILE 會將選取內容寫入檔案；搭配 --max-chars 使用時，它會在一個整潔的斷點處截斷，並輸出 截斷於 chars A-B of N；使用 --offset B 寫入剩餘部分（0.15.1 版）。--compact 會移除段落之間的空白行（0.13.0 版）；與 --offset 一起使用時再次指定即可。

步驟 4：搜尋

RW grep FILE "PATTERN" -C 1 --max 5 會輸出每個匹配的段落，包含其章節號碼和標題、段落編號以及前後各一個段落的上下文。長段落會在匹配內容周圍進行修剪（--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 註記到一個巨型章節（書籤提前結束）時使用它們；自 0.17.0 版起，這樣的章節會首先根據印刷目錄頁或 "Chapter N, Title" 列表中的章節名稱進行切割，因此僅在該方法失敗時才會顯示註記。退出碼 1 表示沒有匹配。當使用者詢問某事物在哪裡或被提及時，請先搜尋再閱讀。

RW rank FILE topic words（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 會寫入 <!-- readwright section N/... --> 註解以及 Markdown 標題。僅當文字少於 25,000 個字元時，Dump 命令才會輸出到標準輸出。請將檔案放在工作階段的 scratch 或 temp 資料夾中，切勿放在使用者的儲存庫中。

步驟 6：回答

簡短引用。對於受版權保護的書籍，請摘要並一次引用一兩句話，切勿引用整頁或整章，即使使用者擁有該副本。請註明每個觀點的來源（章節號碼和標題），以便使用者可以查證。如果輸出了轉換提示（calibre、LibreOffice、pdftotext），若措辭相關，請說明文字是透過轉換器獲得的。

提煉一本書

• 基於先前閱讀的筆記進行建構：在重複使用之前，先 grep 他們引用的兩三個段落，並閱讀筆記中跳過的一個章節，這樣新的總結就能增加價值，且不會帶入任何複製的錯誤。
• 如果 toc 行顯示 (0 w) 且其同級項目在同一個頁面上，表示它的文字被歸入相鄰的章節：使用 --section N-M 閱讀整個群組。實務書籍會將框架或公差級別作為經驗陳述；請將其引用為作者的觀點，而非經測量的結果。
• 查閱作者為支持一個強烈主張而引用的研究，並記錄其局限性。一本通俗讀物可能會省略這些細節：例如，一個報告了性別差異的研究，可能沒有說明該論文僅在其部分年齡範圍內發現了這種差異。

為另一個主題已閱讀過的廣泛參考書：檢查先前的筆記中針對您主題的內容，然後閱讀它們跳過但與您工作相關的章節（例如評估附錄、分析章節），並按類型分配給兩個閱讀代理。

為聲音或剪輯主題再次閱讀的電影或廣播教科書：先前的筆記通常涵蓋了理論章節；請閱讀剪輯和預混章節（音軌佈局、stem、場景轉換），其中包含工作規則。一次調用閱讀選定的章節，例如 read --section 248,250,251，而不是每次調用一個章節。

透過 OCR 閱讀的掃描實務書籍（每頁一個章節）：使用 toc --chapters 取得章節頁碼範圍；然後在您想要的章節內使用 --section N-M grep 主題詞彙，並僅閱讀包含匹配的頁面，因為大部分頁面是軼事和舊設備的描述。

一個具有編號或全大寫標題的扁平 PDF 章節：使用 read --headings 列出它們，然後使用 --at-para 跳轉到您想要的標題。

一個書籤僅到「部分」層級的 PDF（toc 警告一個章節佔據了文本的很大一部分）：對每個大章節使用 read --section N --headings，這會給出真正的章節地圖，並附帶用於 --at-para 的段落編號。

一本編輯手冊：首先閱讀編輯的引言，因為它會說明哪個章節涵蓋了什麼內容，然後僅閱讀那些章節的開頭以及任何關於方法的段落。每個章節都有各自的作者，因此請引用章節並單獨判斷其品質。

一本來自相鄰行業的操作指南（例如為遊戲音效閱讀劇場聲音書）：跳過關於人員和場地硬體的章節，閱讀關於如何製作材料的章節，並在其餘部分 grep 相關工作的詞彙。像 mu?ed 這樣的文字可能存在於出版商的檔案中；在指責閱讀器之前，請先檢查來源。

一部長篇歷史綜述：跳過關於樂器的章節。Grep 方法詞彙，閱讀關於這些方法的章節、結論，以及任何作者判斷其證據的部分。