adhd-md git:20261019.50e6d63A

Immutable. This exact content never changes and is served at /api/v1/blob/06a8f2d1f01478fa.

---
name: adhd-md
description: 把 Markdown 文档改造成 ADHD 友好、可扫读的版本，可选择只改格式、只改内容或两者兼改，并用脚本检查已定义的信息不变量。也能自动提取网页、HTML、PDF 与扫描件的正文，保留来源，逐段陪读已有文档、解释重点、暂停续读，或生成离线专注阅读页。Use when the user asks to make a document ADHD-friendly, more skimmable, or easier to read; when they say 文档太长看不下去 / 排版太密 / 全是大段文字 / 帮我把这个文档改得好读一点 / 优化一下排版; or asks to audit, lint, or restructure Markdown for readability. Triggers include ADHD friendly, ADHD 友好, 注意力友好, 可扫读, skimmable, wall of text, 文字墙, 大段文字, 改排版, 重排文档, make this readable, 陪我读, 带我读, 读不进去, 从上次继续, focus reader, guided reading.
---

# adhd-md

把 Markdown 改造成 ADHD 友好的样子：结论前置、段落切碎、句子变短、动作明确、噪音归零。

**铁律：只重排信息，绝不删信息。** 篇幅太长就折叠或移到附录，不许删。违反这条，其他做得再好都是失败。

也可以保留原文，陪用户一次读一小段，或生成可在浏览器打开的离线阅读页。

## 什么时候用

用户给了一个 Markdown 文件（或一段 Markdown），希望它更好读、更好扫、更适合注意力容易断的人。

用户想读懂已有文档、长文或笔记时，使用 `mode=read`。直接粘贴的文本也能陪读。

网页链接、本地 HTML 和 PDF 可通过 `read` 自动提取后阅读，或用 `extract` 另存为 Markdown；PDF 与扫描件需要本机的提取或 OCR 工具。没有 shell 时使用宿主读取能力，按来源标出缺口。

不适用的情况：

- 改写模式的输入不是 Markdown（先转换，或直接拒绝）
- 用户要的是**内容审查**（事实核查、逻辑校对）—— 那不是这个 skill
- 用户要的是**翻译**或**扩写** —— 都不是

## 先选模式

| mode | 做什么 | 用户会怎么说 |
|---|---|---|
| `edit` | 改写或审计 Markdown，走下方工作流 | 改排版 / 帮我改得好读一点 / 审计 |
| `read` | 保留原文，逐段陪读或生成阅读页 | 陪我读 / 带我读 / 读不进去 / 从上次继续 |

`mode=read` 先读 [references/reading.md](references/reading.md)，按其中的陪读或阅读页流程执行。单文件版对应附录 D。不要运行 `fmt --write`，不要给原文打分后自动改写。

用户只想开始阅读时，直接从第一小段开始；有阅读目标就用，没有也能开始。明确要求两个功能时，生成阅读页并开始第一段陪读。

有 shell 时用 `read --json` 取得阅读会话和分段位置；阅读页与对话共用 JSON 书签。没有 shell 时继续用纯文本书签。

携带书签时用 `read --session bookmark.json --json` 核对原文，回看保留待读位置；原文不匹配时保留旧书签，不猜测重定位。

生成阅读页时可加 `--open`，成功后尝试打开浏览器；打开失败保留文件并给出路径。书签字段、导入导出与暂停规则见陪读流程。

下方的 `scope`、`level`、改写工作流和输出契约仅用于 `mode=edit`。用户只说「优化一下」时保留原有默认值。

## 改写的两个参数

### scope：改什么

| 值 | 边界 | 用户会怎么说 |
|---|---|---|
| `format` | 不改措辞；可移动整块。词序变化或不支持的语法会标为 `unknown` | 只改格式 / 只调样式 / 别动我的字 / 排版优化 |
| `content` | 只改措辞与信息组织，不碰排版风格 | 只改内容 / 句子太长 / 帮我改写 |
| `both`（默认） | 全都改 | 优化一下 / 改成 ADHD 友好 |

划线判据：**搬移已有块算 format，写出新句子算 content。**

把结论段整块搬到开头 = format。新写一段 TL;DR = content。

### level：改多狠

| 值 | 适用 | 会做什么 |
|---|---|---|
| `light` | 规范、合同、API 文档，怕动 | 只做少量调整，不重排顺序；仍需检查差异 |
| `standard`（默认） | README、教程、设计文档 | 拆段、列表化、改标题、写 TL;DR、给时间预估、块重排 |
| `deep` | 会议记录、长文、堆积的笔记 | 全量重构骨架、渐进披露、生成 checklist |

用户没说就用 `both` + `standard`，并在报告开头一句话说明用了什么档，让人能反悔。

## 改写工作流

### 第 0 步 · 决定写哪里

```bash
git -C <文档所在仓库> status --porcelain <文件>
```

- 仓库干净 → **原地改**，用户用 `git diff` 审阅
- 有未提交改动，或不在 git 里 → 写到 `<原名>.adhd.md`，并告诉用户为什么

绝不在有未提交改动的文件上原地覆盖。

### 第 1 步 · 审计

先固定本次 `scope` 与 `level`，包括用户随文件提供的上下文。将 `light / standard / deep` 映射为 `1 / 2 / 3`；所有 audit 与 report 都显式传同一个档位和 scope，不能沿用示例中的默认档位。下例是 standard，其他档位替换数字。

```bash
python3 <skill>/scripts/adhd_md.py audit 文件.md --level 2 --scope=<scope>
```

拿到脚本分、逐条 findings（带 `文件:行`）、以及需要你判断的规则清单。

审计报告同时显示规则覆盖。`--scope=format|content` 只过滤 findings 展示和覆盖统计；脚本分仍按全文所有适用轴计算。仅提示项不扣分，需模型判断项按未命中计入脚本分，但不表示通过。JSON 保留旧 `findings`（全轴）字段，并在 `schema_version=2` 增加按 scope 展示的 `shown_findings` 和覆盖统计；脚本分的 `score.band` 为 `null`，只有完整评分才给档位。

**先读输出再动手。** 不要凭印象改 —— 脚本已经把能算准的都算了。

### 第 2 步 · 确定性格式修复

```bash
python3 <skill>/scripts/adhd_md.py fmt 文件.md
```

自动处理项包括行尾空白、有序列表序号、块间空行、中英文间距和中文标点；具体输出仍要先预览并检查差异。

先看预览，再决定是否写回。`fmt --write` 会先运行 `verify --scope=format`；硬失败或无法判断时拒绝写回。通过后用同目录临时文件校验并原子替换，保留换行、UTF-8 内容、POSIX mode 位及所有者 / 组；拒绝符号链接和硬链接。系统 ACL、扩展属性和文件 flags 不在保留范围内。写入失败或检测到并发编辑时保留原文件并清理临时文件。多文件按文件分别替换，失败会逐个报告，可能出现部分成功。`--strip-emoji` 会跳过 format 校验，是显式有损操作，会单独标示；仍走原子写入保护。

`scope=content` 时跳过这一步。

可选开关：`--toc`（按已有标题生成目录）、`--join-cjk`（合并中文软换行）、`--strip-emoji`（删 emoji，注意这会改动字符）。

### 第 3 步 · 你来改

读 `references/rules.md`，按 scope 过滤出生效的规则子集，逐条改。

顺序：**先 content 再 format**。措辞定了，排版决策才稳。

先执行以下边界检查，再优化分数：

1. 列出原文的事实、条件、例外、否定、适用对象及数值边界；改完逐项找到对应句。尤其区分「手动设置只对当前设备有效」与泛指所有设置、「超过上限」与「达到上限」。
2. 新句只能重述原文或给出可从文档直接数出的篇幅。不得补产品行为、界面状态、因果关系、用途或未提供的成功输出。A7 缺少来源时在报告中标为未满足，不猜测结果。
3. 拆条件动作时，原条件必须仍控制每个子动作，且保留先后关系。例：「如果队列非零，等 3 分钟后刷新一次」可拆成「如果队列非零，等 3 分钟」「在该非零分支等待结束后，刷新一次」；不能把刷新变成无条件步骤。
4. `scope=content` 保留现有块类型、标题层级、列表形态、强调标记和折叠结构。标题文字属于措辞，可以改写；不能把保留层级误读为禁止改标题文字。摘要用现有段落风格；复合步骤可以在原列表项内分句，不能为了 A8 擅自新增列表项。H4 / N7 可用普通文字表达。项内分句后若一个编号下仍有多个动作，A8 仍为「不满足（scope 限制）」，不能报满足。
5. 用户要求逐字或保留标点时，优先于默认 format 的标点归一规则。跳过会改字符的 fmt 修复，逐项审阅 diff；机器 pass 不豁免更严格的要求。

保留原文与候选分开，完成校验才交付。HTML 注释等造成 `unknown` 时撤回候选修改，保留或逐字复制原文作为输出；可另附待审 diff，但不能把待审候选标为完成版。不要删除注释来规避门禁。

改之前必读：

- `references/rules.md` —— 规则全表，含阈值
- `references/antipatterns.md` —— 八种过度优化，**这个必读**
- `references/cjk.md` —— 文档是中文时读
- `references/doc-types.md` —— 只在 `level=deep` 需要重排骨架时读
- `references/evidence.md` —— 需要解释「为什么这样改」、或对某条规则做取舍时读

### 第 4 步 · 校验

```bash
python3 <skill>/scripts/adhd_md.py verify 原文.md 新文.md --scope=format
python3 <skill>/scripts/adhd_md.py report 原文.md 新文.md --scope=<scope> --level=<1|2|3>
python3 <skill>/scripts/adhd_md.py report 原文.md 新文.md --scope=<scope> --level=<1|2|3> --json
```

当前 `verify` 有三态：`pass` 表示声明的机器检查通过且没有待复核警告，`fail` 表示硬约束变化，`unknown` 表示解析器不能可靠判断或有警告待人工复核。CLI 退出码依次为 `0`、`3`、`4`。JSON 保留旧的 `scope`、`hard_failures`、`warnings`、`ok` 字段，并增加 `status`、`unknowns`；确认完整块重排时还会给出 `notes` 指代复核提示。`ok` 仅在 `status=pass` 时为真，旧调用方不会把未知当成成功。

校验器只实现常见 Markdown 子集，不是完整 CommonMark / GFM 解析器。标题、段落、基础列表、引用块、简单表格和成对 fenced code 可检查；代码块正文逐字比较并检查重复次数，不比较围栏样式、语言标签和位置。行内链接、图片与 HTTP(S) URL 的目标及重复次数受保护。format 模式保护闭合 YAML frontmatter；content / both 允许修改，但会提示核对元数据。

四空格缩进或复杂嵌套块、未闭合围栏、引用式链接、原始 HTML、HTML 注释及扩展 Markdown / MDX 有改动时会返回 `unknown` 和源行。唯一原 H2 标题被原样用作 `<summary>` 时，标准 `<details>` 外壳可识别；重复标题或其他 HTML 仍需人工审阅。目录与折叠的自动识别仍有限；不能用伪目录或折叠标签隐藏正文变化。

`format` 允许复用原词拆段、列表化、改标记层级、添加强调 / 行内代码、由已有标题生成目录、折叠原文标题、移动整块、修空格和标点。它不允许改词、删内容、改数字或链接目标。未改写且能唯一映射的完整块重排可以通过，并在 CLI 提示检查悬空指代；句内换序、顺序敏感列表变化或重复块映射歧义返回 `unknown`。`pass` 不是语义等价证明；无法确认时不要写回。硬失败必须回退。

三个 scope 都会按完整值和重复次数检查原有代码块正文、链接目标、行内代码值、命令选项、常见相对路径、权限值和大小写敏感技术标识符；不能用更长的新值包含旧值来绕过检查。`content` / `both` 可以添加新代码块和链接，但不能丢失或改写原值；`format` 还会拒绝新增代码块和链接目标。给原有裸标识符加反引号仍可通过，原行内值移入新代码块也会按原值复核。API、CLI、URL、HTTP、HTML、JSON、PDF、ID、UI、UX、CPU、GPU 等通用缩写至少保留一次，不要求保留每次重复出现。

数字与单位之间的空白可归一，例如 `2 MB` 与 `2MB` 等价；数值或单位本身改变时，`format` 硬失败，`content` / `both` 给出带原值、新值和行号的警告，结果为 `unknown`。单位缩写与全称不互相折算。frontmatter 在 `format` 下逐字保护；在 `content` / `both` 下允许修改，但会报告新旧内容并阻止 `pass`。`pass` 只表示已声明检查通过。硬失败必须修复；`unknown` 不能写成通过，需保留原文并人工复核。

原地改时先留一份原文到临时文件，否则没法 verify：

```bash
cp 文件.md /tmp/adhd-orig.md   # 改之前
```

### 第 5 步 · 报告

必须包含四项：

1. 用了什么 scope 与 level
2. 脚本分 before → after，逐维度 delta
3. verify 结论（通过 / 失败 / 无法判断，以及原因）
4. **你改了什么、以及故意没改什么**

反模式扣分（X 组）after 必须为 0 才能宣称达标。非零先修复或回退自己的改动；若源文已有问题且受 scope 或字符约束无法安全消除，保留原文并明确「未达标」，列出剩余命中，不得编造内容或填空行凑分。短会议记录可将非必要的小标题转为保留原字的普通标签，保留唯一 H1，再检查 X2 与加粗密度；content 范围不允许此类格式变更。

逐条记录 audit 返回的 judge 规则为「满足 / 不满足 / 不适用 / 无法判断」，附原文或输出位置及理由。至少具体复核 H4、A7、A8、N7 和 X 组；未逐项判断就不得声称规则全部通过。scope 冲突、缺来源和结构限制必须写入理由。报告可链接单独的判断表，脚本 100 分不能替代这张表。

**AI 味（M 组）命中数只许下降，不许上升。** 你改写内容时最容易顺手写出「不是 A 而是 B」「值得注意的是」，等于用一套问题换掉另一套。改完对比 `audit` 的活人感维度。

## 三种 scope 的 do / don't

### scope=format

**能做**：在已有句界拆段 · 并列句转列表（复用原词）· 加粗已有关键术语 · 补空行分割线 · 代码块补语言标签 · 标题层级修正 · 列表降嵌套 · `<details>` 折叠（summary 复用已有标题文字）· 由已有标题生成 TOC · 块顺序重排 · 中英文间距与标点规范

**不能做**：改任何一个词 · 新写 TL;DR · 改写标题措辞 · 补时间预估 · 补下一步动作 · 删填充词

**块重排的陷阱**：把结论块搬到开头后，扫一遍被搬走的块里有没有「这个方案」「上述配置」「它」这类**悬空指代**。修指代要改词，属于 content —— 所以 `scope=format` 下检出悬空指代时，**放弃这次搬移**，在报告里记「需 content 权限才能安全前置」。

### scope=content

**能做**：长句拆短 · 被动改主动 · 结论前置改写 · 新写 TL;DR · 标题改成结论式 · 补时间预估与下一步 · 每步给预期输出或验证方法（A7）· 复合步骤拆成单动作（A8）· 多步流程标注进度（N7）· 术语首现解释 · 删填充词与虚词壳 · 拆括号插入语 · 消灭「如上所述」· **洗掉 AI 味**（翻案腔、预告式冒号、装深刻的话、黑话、名词化）

**不能做**：改排版风格（不新增标题层级、不改列表形态、不动折叠结构）· 也不能借「精简」之名删约束条件、单位、版本号、例外情况

### scope=both

先 content 再 format，然后运行现有检查并人工复核排版、词序和语义。`verify --scope=both` 的 `pass` 只覆盖已声明的不变量；句内语义、指代与机器未支持的语法仍需人工复核。默认档。

## 没有 shell 的宿主怎么办

`mode=read` 的对话陪读不需要 shell。直接按 `references/reading.md` 处理已取得的原文，并在暂停时给出可复制书签。

离线 HTML 生成器需要 Python 3；没有执行能力就说明无法运行生成器，不声称已经创建文件。

拿不到 Bash / 命令执行时：

1. 跳过 audit / fmt / verify，按 `references/rules.md` 人工过一遍
2. 用 `references/antipatterns.md` 末尾的自检清单逐条自查
3. **在报告里明确写「未做机器校验」** —— 不许假装跑过脚本

假装跑过校验，比不校验更糟。

## 输出契约

改完给用户的报告，照这个格式：

```markdown
## 改完了：<文件名>

**scope** `both` · **level** `standard` · 写到 `原地`（git 干净）

脚本分 62.4 → 88.1（+25.7）

| 维度 | before | after |
|---|---|---|
| 首屏结论力 | 40 | 100 |
| …… | | |

**verify(both)** 通过 —— 报告列出的检查已运行；说明检查范围及尚未覆盖的内容，不把通过写成完整保全证明

**改了什么**
- 把最后一段的结论整块搬到开头（format）
- 12 个超长句拆成 28 句（content）
- 3 处「如上所述」就地重述（content）

**故意没改**
- `## API 参数` 一节保持原样：参考类内容需要跳读，重排会破坏定位
- 两处 92 字长句保留：拆开会切断因果关系
```

「故意没改」这一节不许省。它让用户知道你是判断过的，不是漏了。

## 参考文件索引

| 文件 | 什么时候读 |
|---|---|
| `references/reading.md` | `mode=read`。陪读、来源边界、书签与离线阅读页 |
| `references/rules.md` | 每次改写都读。规则全表 + 阈值 + 轴/档标记 |
| `references/antipatterns.md` | 每次改写都读。八种过度优化 + 自检清单 |
| `references/rubric.md` | 需要解释分数、或要手工补 judge 项评分时 |
| `references/cjk.md` | 改写的文档是中文 |
| `references/doc-types.md` | `level=deep` 且要重排整体骨架 |
| `references/evidence.md` | 解释「为什么这样改」或做规则取舍时 |

## 常见错误

| 错误 | 后果 |
|---|---|
| 把脚本分说成最终分 | 默认 standard + both 有 23 条规则需模型判断、7 条仅提示；未判断不代表通过，必须说明这是脚本分 |
| `scope=format` 却改了词 | verify 硬失败。回退 |
| 以「精简」为名删内容 | 违反铁律。折叠或移附录，不删 |
| 改写时写出「不是 A 而是 B」 | M1 翻案腔。直接从正面下判断 |
| 加 emoji 当锚点 | X1 扣分。用 `> **注意**`、表格、分割线 |
| 切成一堆两行小节 | X2 碎片化扣分 |
| 列表项砍成关键词 | X3 剩词不剩句扣分 |
| 说跑了校验其实没跑 | 诚信问题，比不校验严重 |