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。结构可以大改，一个词都动不了，格式档的天花板就在这里。

03

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

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

`format`

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

能做

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

不能做

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

可证明无损

`content`

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

能做

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

不能做

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

不变量保全

`both`默认

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

另一根轴

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

怎么用

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

75 条规则按轴与档过滤

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 单文件里。跑的是同一个进程，不是同一个模型，所以六个宿主的分数与校验结果必然一致。

分数不虚报

75 条规则里 44 条脚本可判定（42 条计分、2 条提示），31 条标记为需模型判断。audit 输出的叫「脚本分」，不给「优」档。脚本分低说明一定有问题，脚本分高不说明没问题。

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 分，都零词改动。

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

07

两分钟装好

装。三种方式任选一种，脚本会探测本机装了哪些 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 友好的，只改格式

接 CI

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

没有命令执行能力的环境

网页版 LLM 直接粘贴自包含单文件 adhd-md.standalone.md ，30 KB，规则全带。降级后没有机器校验，报告里必须写明。

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

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

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

md-cache

md-cache

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

format

content

both默认

顺手把 AI 味洗掉

破折号不硬禁，看密度

正则分不清的交给模型

删一个词就会被拦下来

能算准的不交给模型

分数不虚报

一份 skill，六个 agent

两分钟装好

接 CI

没有命令执行能力的环境

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

`format`

`content`

`both`默认