Max Lin

让 agent 把长材料
读到最后一行Make your agent read to the last line

这里收着我在真实任务里打磨过的 Claude Code skill。第一个是 deep-read：脚本先把转写稿切成一次读得下的块，agent 按顺序一块块亲自读完，每块写笔记，最后交出覆盖声明，写明每一块读了哪几行。Claude Code skills I've hardened on real work. The first is deep-read: a script cuts a transcript into chunks that each fit in one read, the agent reads every chunk in order itself, writes notes after each, and ends with a coverage statement naming the lines each chunk covered.

在 GitHub 上查看View on GitHub Claude Code skill，公开在 GitHub 上，需要 Python 3A Claude Code skill, public on GitHub. Needs Python 3. 
$ python3 scripts/prepare.py course.vtt --out scratch
5065 cues, last one starts at 03:01:27 -> scratch/transcript.txt
Reading copy: scratch/read.txt, 1547 lines, ~54965 tokens, each line <= 200 characters
Chunk plan (Read offset starts at 1; read every chunk in order):
  chunk 1: offset=1 limit=414 (lines 1-414, ~15032 tokens)  chunk 2: offset=415 limit=412 (lines 415-826, ~15009 tokens)  chunk 3: offset=827 limit=416 (lines 827-1242, ~15018 tokens)  chunk 4: offset=1243 limit=305 (lines 1243-1547, ~11066 tokens)
notes.md

字幕内容是编的；上面的分块计划是 prepare.py 处理一份同样长度的虚构字幕时的原样输出。The subtitles are made up; the chunk plan above is prepare.py's verbatim output for a made-up subtitle file of this length.

只读了一部分的 agent，也会交出一份看起来完整的总结An agent that read a fraction still hands you a summary that looks complete

它读开头一屏、结尾一屏，再 grep 几个关键词，就开始写。写出来的东西没有破绽，因为漏掉的部分它根本没见过。deep-read 不让它跳，并要求它拿出证据。It reads the first screen, the last screen and a few grep hits, then starts writing. The summary has no visible holes, because it never saw what it missed. deep-read doesn't let it skip, and makes it show proof.

一次读太多，报错A read too big errors out
单次读取超过约 2.5 万 token 就失败，agent 退回去 grep 或只看第一屏，后面的再也没读。A single read fails above about 25k tokens; the agent falls back to grep or the first screen and never reads the rest.
一行太长，切不开A line too long to split
分块只能按行切。转写稿常常一整段写在一行里，一行超过上限就没法分块。Chunks split by line. Transcripts often put a whole paragraph on one line, and a line over the limit can't be chunked.
默认只给 2000 行The 2000-line cap
Read 默认只返回前 2000 行，之后的内容不声不响地没了。Read returns the first 2000 lines by default; everything after is silently dropped.
抽样冒充读过Sampling passed off as reading
看看开头结尾、grep 几处命中，直接写总结。Head, tail and a few grep hits, then straight to the summary.
交给子 agent 读Handing it to a subagent
子 agent 交回的是它自己的总结，主 agent 从没见过原文。The subagent returns its own summary; the main agent never saw the source.
读完再凭记忆写Writing from memory
全部读完再回忆，前面的细节早忘了；上下文一压缩，连印象都没了。所以每读完一块就写笔记。Recalling after reading everything loses early details, and compaction erases even the impressions. Hence notes after every chunk.
字幕、文本、PDFSubtitles, text, PDFs
SRT/VTT 去掉序号和时间轴，合并滚动字幕的重复行，每段带 [HH:MM:SS]。PDF 先用 pdftotext 转成文字。SRT/VTT lose cue numbers and timings, rolling-caption repeats merge, and each paragraph starts with [HH:MM:SS]. PDFs go through pdftotext first.
一次读不完也行Longer than one session
笔记顶部记下「读到第 N 行」，下次从那里接着读。The notes record "read up to line N" at the top, and the next session picks up there.
原话和看法分开Source apart from opinion
作者说的写进正文，数字标「作者原话，未核实」；agent 自己的看法单独一节。What the author said goes in the body, numbers marked as stated and unverified; the agent's own take gets its own section.
安装Install
npx skills add max1874/skills --skill deep-read
平台Platform
Claude Code
要求Requires
Claude Code；Python 3（只用标准库）；处理 PDF 需要 poppler 里的 pdftotext。skill 是标准的 SKILL.md 文件夹，skills 命令行也能把它装给 Codex 等其他 agent，但读取步骤是按 Claude Code 的 Read 工具写的。Claude Code; Python 3 (standard library only); pdftotext from poppler for PDFs. Each skill is a standard SKILL.md folder that the skills CLI can also install for Codex and other agents, but the reading steps are written around Claude Code's Read tool.

常见问题Questions

怎么让 Claude Code 把一份长文档或转写稿完整读完？How do I make Claude Code read a long document or transcript all the way through?

装上 deep-read，然后用 /deep-read，或者直接说「全部读完，别跳」。它先用脚本生成带行号的短行阅读副本和分块计划，agent 按计划逐块读完、逐块写笔记，最后给出覆盖声明，写明每块读了哪些行。Install deep-read, then run /deep-read or simply ask it to read everything without skipping. A script first builds a short-line reading copy and a chunk plan; the agent reads and takes notes chunk by chunk, then gives a coverage statement listing the lines each chunk covered.

为什么 Claude Code 读长文件会只读一部分？Why does Claude Code only read part of a long file?

常见原因有几种：单次读取超过约 2.5 万 token 会报错；Read 默认只返回前 2000 行；一整段写在一行里的转写稿没法按行切块；或者 agent 用 grep、开头结尾和子 agent 摘要代替了阅读。deep-read 的脚本和规则针对的就是这几种情况。A few usual causes: a single read errors above roughly 25k tokens; Read returns only the first 2000 lines by default; a transcript with a whole paragraph per line cannot be split by line; or the agent substitutes grep, head and tail, or a subagent's summary for reading. deep-read's script and rules target each of these.

怎么安装 Claude Code 的 skill？How do I install a Claude Code skill?

运行 npx skills add max1874/skills --skill deep-read；或者把 deep-read/ 文件夹复制到 ~/.claude/skills/（所有项目可用）或项目里的 .claude/skills/（只对这个项目）。之后在 Claude Code 里用 /deep-read 调用。Run npx skills add max1874/skills --skill deep-read, or copy the deep-read/ folder into ~/.claude/skills/ (all projects) or a project's .claude/skills/ (that project only). Then call it in Claude Code with /deep-read.

能用在 Codex 或其他 agent 上吗？Does it work with Codex or other agents?

skill 是标准的 SKILL.md 文件夹，skills 命令行可以用 -a codex 等参数装给其他 agent，prepare.py 也是任何能跑命令的 agent 都能用的 Python 脚本。但读取步骤里的 offset/limit、pages 和读取上限是按 Claude Code 的 Read 工具写的，在其他 agent 上要按它们自己的读文件方式对应。Each skill is a standard SKILL.md folder, the skills CLI can install it for other agents with flags such as -a codex, and prepare.py is a Python script any agent with a shell can run. The reading steps, though (offset/limit, pages, the read-size limit), are written for Claude Code's Read tool, so other agents need the equivalent in their own file-reading tools.

能读字幕文件和 PDF 吗？Can it read subtitle files and PDFs?

能。SRT 和 VTT 字幕会被转成带时间戳的段落；有文字层的 PDF 先用 pdftotext -layout 转成文本（macOS 用 brew install poppler 安装）；扫描版 PDF 用 Read 的 pages 参数每次最多 20 页按顺序读。网页先抽出纯文本再处理。Yes. SRT and VTT subtitles become timestamped paragraphs; a PDF with a text layer is converted with pdftotext -layout first (brew install poppler on macOS); a scanned PDF is read in page order with Read's pages parameter, up to 20 pages at a time. Web pages need their plain text extracted first.

获取帮助Get help

发邮件到Email hi@max1874.com，或在 , or open an issue on GitHub 提 issue。写上版本和运行环境，能更快定位问题。. Include the version and your environment so the problem is easier to find.