adhd-md — 把 Markdown 改造成读得下去的样子

01

读不下去的文档，问题多半在排版

同一段信息，一坨读不下去，切开就能读。

md-cache 是一个 Markdown 渲染缓存中间件，把渲染结果按内容哈希缓存到本地磁盘，命中时直接返回，避免重复渲染。它需要 Node 18 以上版本，依赖只有一个 lru-cache。装好之后在渲染管线里包一层 withCache 就行。缓存目录默认是 .cache/md，可以用 MD_CACHE_DIR 环境变量改。默认最大条目数是 500，用 maxEntries 选项改。默认 TTL 是 7 天，用 ttl 选项改，单位是毫秒。设成 0 表示永不过期，但磁盘会一直涨，生产环境不建议。

回跳「如上所述」要求把眼睛移回去、重新定位、再回来。工作记忆一次强制清空重载
埋结论读者在前 15 行决定去留。结论在第 40 行等于没写
找不到下一步知道原理但不知道该敲什么，启动摩擦直接变成放弃
AI 味「不是 A 而是 B」要读者先装载一个自己本来没有的误解，再卸掉

02

同一篇文档，一个词都没改

下面是真实语料。scope=format 档只动标记、空白和块顺序，正文词序列逐字保留。左右对照看看差别。

改前 87.8

md-cache

md-cache 是一个 Markdown 渲染缓存中间件，把渲染结果按内容哈希缓存到本地磁盘，命中时直接返回，避免重复渲染。它需要 Node 18 以上版本，依赖只有一个 lru-cache。装好之后在渲染管线里包一层 withCache 就行。缓存目录默认是 .cache/md，可以用 MD_CACHE_DIR 环境变量改。默认最大条目数是 500，用 maxEntries 选项改。默认 TTL 是 7 天，用 ttl 选项改，单位是毫秒。设成 0 表示永不过期，但磁盘会一直涨，生产环境不建议。

如果渲染函数有副作用，不要用这个中间件，因为命中缓存时渲染函数根本不会被调用。如果你的 Markdown 里嵌了时间戳或随机数，输出会被缓存住，看起来像是不刷新，这不是 bug。

实测在 1200 篇文档的站点上，冷启动构建 42 秒，二次构建 3.1 秒，快十三倍。

改后 100

md-cache

实测在 1200 篇文档的站点上，冷启动构建 42 秒，二次构建 3.1 秒，快十三倍。

md-cache 是一个 Markdown 渲染缓存中间件，把渲染结果按内容哈希缓存到本地磁盘，命中时直接返回，避免重复渲染。

它需要 Node 18 以上版本，依赖只有一个 lru-cache。装好之后在渲染管线里包一层 withCache 就行。

缓存目录默认是 .cache/md，可以用 MD_CACHE_DIR 环境变量改。
默认最大条目数是 500，用 maxEntries 选项改。
默认 TTL 是 7 天，用 ttl 选项改，单位是毫秒。
设成 0 表示永不过期，但磁盘会一直涨，生产环境不建议。

如果渲染函数有副作用，不要用这个中间件，因为命中缓存时渲染函数根本不会被调用。

如果你的 Markdown 里嵌了时间戳或随机数，输出会被缓存住，看起来像是不刷新，这不是 bug。

首屏结论力

分块粒度

扫读性

句子负荷

行动性

排版一致性

活人感

改动：结论块前置、一坨拆四段、四句配置转列表、裸标识符包成行内代码。新增词 0，删除词 0。

注意改后没有给配置列表加小标题。「配置」这两个字原文里没有，加了就是新写措辞，越界成 content。结构可以大改，一个词都动不了，格式档的天花板就在这里。

已经有文档了？一起读下去

同一篇 md-cache 文档，一次只看一小段。可以自己按节奏读，也可以请 agent 解释卡住的地方。

动手试试 · 聚焦阅读

md-cache

用途与接入

原文片段

md-cache 是一个 Markdown 渲染缓存中间件，把渲染结果按内容哈希缓存到本地磁盘，命中时直接返回，避免重复渲染。它需要 Node 18 以上版本，依赖只有一个 lru-cache。装好之后在渲染管线里包一层 withCache 就行。

默认值与过期时间

原文片段

缓存目录默认是 .cache/md，可以用 MD_CACHE_DIR 环境变量改。默认最大条目数是 500，用 maxEntries 选项改。默认 TTL 是 7 天，用 ttl 选项改，单位是毫秒。设成 0 表示永不过期，但磁盘会一直涨，生产环境不建议。

使用前要知道的限制

原文片段

如果渲染函数有副作用，不要用这个中间件，因为命中缓存时渲染函数根本不会被调用。如果你的 Markdown 里嵌了时间戳或随机数，输出会被缓存住，看起来像是不刷新，这不是 bug。

这篇示例给出的测试结果

原文片段

实测在 1200 篇文档的站点上，冷启动构建 42 秒，二次构建 3.1 秒，快十三倍。

查看完整原文

# md-cache

md-cache 是一个 Markdown 渲染缓存中间件，把渲染结果按内容哈希缓存到本地磁盘，命中时直接返回，避免重复渲染。它需要 Node 18 以上版本，依赖只有一个 lru-cache。装好之后在渲染管线里包一层 withCache 就行。

缓存目录默认是 .cache/md，可以用 MD_CACHE_DIR 环境变量改。默认最大条目数是 500，用 maxEntries 选项改。默认 TTL 是 7 天，用 ttl 选项改，单位是毫秒。设成 0 表示永不过期，但磁盘会一直涨，生产环境不建议。

如果渲染函数有副作用，不要用这个中间件，因为命中缓存时渲染函数根本不会被调用。如果你的 Markdown 里嵌了时间戳或随机数，输出会被缓存住，看起来像是不刷新，这不是 bug。

实测在 1200 篇文档的站点上，冷启动构建 42 秒，二次构建 3.1 秒，快十三倍。

这里演示分段阅读。完整阅读页还支持字号、行距和本地进度保存。

打开完整阅读页

03

只改格式，只改内容，或者两者都改

划线判据只有一句话。搬移已有块算格式，写出新句子算内容。

`format`

正文词序列逐字不变，只动标记、空白、块顺序。

能做

在已有句界拆段 · 并列句转列表（复用原词）· 加粗已有术语 · 块顺序重排 · 补代码块语言标签 · 折叠 · 中英文间距与标点规范

不能做

改任何一个词 · 新写 TL;DR · 改写标题措辞

可证明无损

`content`

只改措辞与信息组织，不碰排版风格。

能做

长句拆短 · 被动改主动 · 新写 TL;DR · 标题改成结论式 · 补时间预估与下一步 · 术语首现解释 · 删填充词

不能做

动排版结构 · 借「精简」之名删约束、单位、版本号、例外

不变量保全

`both`默认

先改内容再改格式，最后统一校验。

另一根轴

light 只做零风险项，适合规范与 API 文档。standard 拆段、列表化、改标题、写 TL;DR、给时间预估。deep 全量重构骨架，适合会议记录和乱笔记。

怎么用

直接说人话：「把 README 改成 ADHD 友好的，只改格式」

78 条规则按轴与档过滤

04

顺手把 AI 味洗掉

模型写出来的中文有一些固定套路。每一种都要读者多花一次注意力，所以归这个 skill 管。

套路	读者多花的注意力
不是 A 而是 B	先装载一个自己本来没有的误解，再卸掉。白付一次工作记忆
核心是：	先宣布重要性再给货，等于把一句话说两遍
值得注意的是	承诺了深度，后面内容没变深，骗走一次注意力
完成了对流程的优化	动作藏进名词，要多解一层才知道谁做了什么
赋能、闭环、全链路	换成普通说法信息量不变，但读者要先翻译
时间会保管细节	没有主语能负责，读者无法核对真假
大量测试、各种场景	没有数字的量词，等于没给信息
显著提升、彻底解决	不写快了多少，读者无法核对

破折号不硬禁，看密度

—— 是标准中文标点，用来插一句补充说明很正常。AI 味在于把它当节奏拐杖。实测手写技术文档中位数约 5 个/千字，模型生成常在 15 以上，所以阈值定在 8。列表里 事项 —— 负责人 —— 期限 是字段分隔，不计入。

正则分不清的交给模型

三个 flag 并列是好写法，「为什么出发，为什么放弃，为什么害怕」才要改，两者在正则眼里长得一样。所以同构排比与借喻只提示、不扣分。git 仓库 是本义，「记忆的仓库」才是包装。

05

删一个词就会被拦下来

格式档下，剥掉标记后的正文 token 多重集必须完全一致。删词是 missing，新写措辞是 added，两者都拒绝写回。

$ adhd_md.py verify 原文.md 新文.md --scope=format
scope=format → 通过
  [警告] blocks_reordered: 检测到块重排，检查悬空指代

$ adhd_md.py verify 原文.md 删了一句的.md --scope=format
scope=format → 失败
  [硬失败] prose_tokens_missing  count=9
    items: [生产, 环境, 别, 设成, 0, …]
    hint: 这些词从正文里消失了。format 档不许删词。

能算准的不交给模型

审计、格式修复、无损校验都在一个纯标准库的 Python 单文件里。跑的是同一个进程，不是同一个模型，所以六个宿主的分数与校验结果必然一致。

分数不虚报

78 条规则里 34 条只由模型判断，另有 3 条只提示不扣分 —— 这 37 条在脚本分里都按满分计入。audit 输出的叫「脚本分」，不给「优」档。脚本分低说明一定有问题，脚本分高不说明没问题。

07

真实 agent 评测：新规则会执行，也不会被滥用

Codex 0.36.0 + gpt-5.6-sol，4 个语料各跑 scope=both 完整工作流（审计 → 改写 → verify → 报告）。

用例	level	脚本分	H4 行为
中文 README	standard	87.8 → 100	加「约 1 分钟读完」，合理
英文 API 参考	light	83.9 → 89.2	没加，符合 light 排除
中文会议记录	deep	76.2 → 100	加「约 2 分钟」+ 读完收益，合理
英文 runbook	standard	72.8 → 100	前两轮漏掉；补规则详解后给出「四步响应路径」

没有滥用

4 例零「每节塞时间」、零编造时长；light 档正确不加时间预估。

judge 规则只写表里会漏

runbook 前两轮漏 H4。在 rules.md 补写法示例后，第三轮给出 Step 1 of 4、每步预期输出、复合动作拆成子步骤。

完整评测过程、三轮迭代与复现方法

06

一份 skill，六个 agent

六个宿主都原生支持同一套 SKILL.md 目录格式，所以不需要六套适配器。canonical skill 放 ~/.agents/skills/，各宿主放软链，改一处同时生效。

Claude Code ~/.claude/skills/ 运行时实测
Codex ~/.codex/skills/ 运行时实测
Grok Build ~/.grok/skills/ 加载实测
Gemini CLI ~/.gemini/skills/ 加载实测
Cursor ~/.cursor/skills/ 加载实测
opencode ~/.config/opencode/skills/ 加载实测

Codex headless 跑了完整流程，自己发现目标文件有未提交改动，于是改写到旁路文件而没覆盖原文件。这正是 skill 第 0 步的逻辑。产出与手写版本不同，但同样合格。它把两条警告合成引用块，我把配置转成列表，都是 100 分，都零词改动。

另外四个宿主只验证了能加载，没验证执行效果。验证结论里写清了哪些验过、哪些没验、有哪些已知局限。

08

两分钟装好

装。三种方式任选一种，脚本会探测本机装了哪些 agent，只往存在的宿主里放。

有 Node

npx github:tsonglew/adhd-md

没 Node

curl -fsSL https://tsonglew.github.io/adhd-md/install.sh | bash

想改源码

git clone https://github.com/tsonglew/adhd-md && cd adhd-md bash scripts/install.sh

克隆装的是软链，git pull 即更新。npx 与 curl 装的是复制，重跑一次即更新。
先审一篇看看分数和问题清单。

npx github:tsonglew/adhd-md audit your-doc.md
然后在任意 agent 里直接说人话。

把 README.md 改成 ADHD 友好的，只改格式

已有文档，也可以陪你读

在对话里一次读一小段，解释卡住的地方；随时暂停，下次从书签继续。

陪我读这篇文档，一次一小段，不修改原文

想自己读，就生成离线阅读页。Markdown、网页链接和 PDF 都用同一个命令。

npx github:tsonglew/adhd-md read your-doc.md
npx github:tsonglew/adhd-md read "https://example.com/article" -o article.reader.html
npx github:tsonglew/adhd-md read your-doc.pdf

用浏览器打开生成的阅读页。可切换全文、调整字号与行距，并在当前浏览器记住进度。原文件保持不变，网页和 PDF 显示提取文本、来源与缺口。

PDF 与扫描件的准备

网页和本地 HTML 无需额外依赖。PDF 需 Poppler；扫描页会尝试本机 OCR，另需 Tesseract 和语言包。按系统安装一次即可。

macOS（Homebrew）

brew install poppler tesseract tesseract-lang

Ubuntu / Debian

sudo apt install poppler-utils tesseract-ocr tesseract-ocr-chi-sim

提取稿保留页码，表格、公式和图片请结合原 PDF 核对。登录或动态网页需由 agent 的浏览器工具读取。

只要正文文件：npx github:tsonglew/adhd-md extract your-doc.pdf

接 CI

adhd_md.py fmt --check docs/*.md
adhd_md.py audit --min-score 70 docs/*.md

没有命令执行能力的环境

网页版 LLM 直接粘贴自包含单文件 adhd-md.standalone.md，包含改写与陪读规则。没有机器校验，改写报告里必须写明；对话陪读可以直接开始。

把 Markdown 改造成 读得下去的样子

读不下去的文档，问题多半在排版

同一篇文档，一个词都没改

md-cache

md-cache

已经有文档了？一起读下去

用途与接入

默认值与过期时间

使用前要知道的限制

这篇示例给出的测试结果

只改格式，只改内容，或者两者都改

format

content

both默认

顺手把 AI 味洗掉

破折号不硬禁，看密度

正则分不清的交给模型

删一个词就会被拦下来

能算准的不交给模型

分数不虚报

真实 agent 评测：新规则会执行，也不会被滥用

没有滥用

judge 规则只写表里会漏

一份 skill，六个 agent

两分钟装好

已有文档，也可以陪你读

接 CI

没有命令执行能力的环境

把 Markdown 改造成
读得下去的样子

`format`

`content`

`both`默认