讲解阶梯:文字 < 图 < 网页 < 视频

要让人看懂一件事时,先选形式,再动笔。四级从便宜到贵排。往上走一级之前,要说得出下面那级哪里讲不清。

出处:Karpathy 2026-10-02 的帖子(x.com/karpathy/status/2105819303471976479)把「读懂 AI 的输出」的形式排成这四级。 他的看法是:代码变便宜了,以前不值得做的一次性网页、讲解视频,现在可以随手要。

本 skill 管形式和句子。讲内核原理时,内容按什么顺序、分几层讲,先看 kernel-explain。

0. 选哪一级

• 一次回答可以混着用:结论用文字,关系配一张 ASCII 图,大批数据给一个网页路径。
• 级别高不等于好。写清楚的一段文字,是最快让人看懂的那一级。

1. 文字:STE 打八折

是什么:ASD-STE100(简化技术英语)是欧洲航空航天与防务协会(ASD)维护的受控英语标准, 本来用于飞机维修手册。当前版 Issue 9(2025-01):53 条写作规则,加约 900 个批准词,每个词只有一个意思。

为什么要它:技术文字的读者常常不是母语者,或者是赶时间、只扫一眼的人。读错了没处问, 和维修手册的读者处境一样。AI 写的长句、被动句、同一个东西换着叫,正是读错的来源。

为什么只打八折:原标准很严(说明句 ≤ 25 词、操作句 ≤ 20 词、只许用批准词),词表也不能自由转载。 照搬会写成电报。Karpathy 那条帖子也是这么用的:让模型写到 ASD-STE100 的八成左右。

规则(中英文都适用)

不照搬的部分:批准词表(不能自由转载,中文也没有对应词表)、限制 -ing 形式这类英语语法细则。

边界:代码、命令、日志原文、引用不改写。改别人的旧文字时,只改自己这次动到的句子。

开关:「用 STE 讲」

• 开着时不变的:回答语言照旧(中文问就中文答);内容写什么、先写什么照旧,STE 只管句子怎么写。
• 只在本次会话有效,新会话默认关着。上下文压缩后不确定开没开,看最近一次开关的话;找不到就当关着。

检查

K=~/.claude/skills/explain-ladder/scripts
python3 $K/check_ste.py <文件或目录>                 # 说明类文档
python3 $K/check_ste.py --howto <操作步骤.md>         # 步骤类:句长更严,查一步里的分号
printf '%s' "<草稿>" | python3 $K/check_ste.py --stdin

规则 1、3、6 要靠判断,机器查不准,脚本不查。写文档时跑一遍;聊天回答不要求每条都跑。 文档里故意放的反例:Markdown 行尾写 ste-ok,HTML 元素加 data-ste-ok 属性,检查就跳过它。

2. 图:讲关系先给图

讲的是关系就先给图,再写字。讲的是结论或数字,不画。 图必须承载读者从文字里拿不到的判断;只是把文字框起来的图,不如不画。

终端里:ASCII 图

• 宽度 ≤ 80 列。终端窄了,宽图和宽表格都会折行,框就散了。
• 汉字占两列。按字符个数画的框,一有汉字就歪。check_ste.py 的 S5 按显示宽度算。
• 框线字符(─ │ ┌ ┐)在少数终端里宽度不对;对不齐就改用 + - |。

两种最常用的样子。第一张要读者拿到的判断是:中断函数自己不上报按键。它只排一个延时(hrtimer 或延时任务,二选一),消抖时间到了才上报。

调用链:从上往下,每层挂出处
行号出自一棵 Linux 6.1.141 内核树的 drivers/input/keyboard/gpio_keys.c,只作示意

  按键中断
      │
      ▼
  gpio_keys_gpio_isr()                      :417   不上报,只排一个延时
      │
      ├─ hrtimer_start()                    :439   用 hrtimer 消抖时
      │    └─ gpio_keys_debounce_timer()    :407   到期后调用
      │
      └─ mod_delayed_work()                 :443   不用 hrtimer 时
           └─ gpio_keys_gpio_work_func()    :399   到期后调用

  gpio_keys_debounce_event()                :390   两条路到期后都调它
      │
      ▼
  gpio_keys_gpio_report_event()             :366
      │
      ▼
  input_event()                             :386   按键值交给 input 子系统

数据流:从左往右,箭头上下写传的是什么

  ┌─────────┐  原始帧   ┌──────┐   坐标    ┌──────┐
  │ 触摸 IC │ ────────▶ │ 驱动 │ ────────▶ │ 应用 │
  └─────────┘  (I2C)    └──────┘  (evdev)  └──────┘

正式出图:用设计 skill 的图例库

• 怎么画由模型自己判断。设计 skill 可以用,不是必须用;手写 SVG 也行。
• 设计 skill 不够用时要明说:缺哪种图、样式哪里不合适、为一次性页面走设计流程太重 —— 说出来,并建议怎么补。不要硬套,也不要不声不响换成别的。
• mermaid 之类要从 CDN 加载脚本,放进第 3 级的页面会违反「不引外部资源」;那里手写 SVG。

3. 网页:看懂就扔

文字讲不清时,现做一个只给自己看一次的网页。不追求好看,看懂就扔。常见的三种: 一份几千行的 log,按阶段分段、关键事件可过滤;一次改动的前后对比;一张分区表。

为什么不用设计 skill 做:设计 skill 做的是给别人看的成品,讲究版式和配色。 一次性页面要的是两件事:数据可信、做得快。想借某个设计 skill 的配色,抄进 p.style() 就行。

两条硬要求(都有检查)

每项检查都有「故意做坏,必须报」的反向用例,在 check_page.py --self-test 里。

怎么做

K=~/.claude/skills/explain-ladder/scripts
python3 $K/page_kit.py new <主题>          # 建 ~/throwaway-pages/YYYYMMDD-<主题>/build.py
# 改 build.py:SRC 换成真实文件,按这页要回答的问题算数据,挑控件
python3 ~/throwaway-pages/<目录>/build.py   # 生成 index.html,打印 Linux / Windows 两个路径
python3 $K/check_page.py ~/throwaway-pages/<目录>   # 四项检查,有失败就改

templates/build_template.py 是完整骨架。交给 user 时说三件事:路径、这页回答什么问题、怎么用(过滤框支持 /正则/)。

页面要放进公开仓时,用 Page(标题, relative=True):出处里的路径按 build.py 所在目录记相对路径, 不会把本机家目录带出去;check_page.py 按页面目录去找这些文件。 样例:demos/explain-ladder/ste-report/(从固定提交取快照,以后也能逐字节重建)。

怎么打开、怎么扔

• Windows 上的 Chrome:家目录用 samba 共享出去时,build.py 会打印 \\<本机 IP>\<用户名>\throwaway-pages\…\index.html,粘到地址栏就能开(路径带中文也行,2026-10-07 试过)。 IP 取 hostname -I 的第一个,共享名按用户名推;推错了就设 THROWAWAY_SMB_ROOT。 没有共享时,把 index.html 拷到本地打开 —— 单个文件,拷走就能用。
• 想在手机上看:内容不含公司代码和 log 时,可以问 user 后发布成 claude.ai 私有页面;含公司内容的只放本机。
• 扔:page_kit.py list 列出每个页面放了几天。工具不删,user 自己删。 build.py 留着:源文件更新了,重跑一次就是新页面。

检查覆盖不到的

• 四项检查证明的是「数据确实从这个文件经 build.py 算出来」,不证明 build.py 算得对。 2026-10-07 第一次试用:一份 OTA 升级后自动重启的串口 log,按「内核时间戳 > 1000 秒就算升级前的旧系统」分段。 新系统启动后跑过 1000 秒的几行,被标成了旧系统,四项检查全过。 改成按 Restarting system、Starting kernel 这两行事件来切,才对。 分类规则、统计方法要像看代码一样看 build.py;规则尽量按事件切,不按数值大小猜。
• P4 在没有显卡的机器上是软件渲染,只看打开报不报错、有没有网络请求,不看好不好看。

4. 视频:默认不做

默认不做。 视频做起来最贵,看的人也只能从头看到尾,没法过滤、搜索、跳到某一行。

什么时候可以提

只在下面三种情况下,在回答末尾提一句:

1. 要讲的是随时间展开的过程,先后顺序和时机本身就是要点。 例如启动各阶段谁先谁后、竞争窗口、一段动画演示的机制。网页上,这些要读者一步步点才看得到。
2. 看的人不是 user 本人,而是要被动看完的人(转给组里、给新人讲)。
3. user 自己提到视频。

怎么提:一行,写清为什么视频更好、用哪条路做、要花什么。例:

这个启动过程做成 30 秒的无声录屏可能更直观:六个阶段的先后和耗时一眼就能看出来。要做吗?做的话就录上面那个页面,几分钟。

user 点头之前:不录、不装依赖、不写配音稿。没回应就当没提过,同一件事不再追问。

点头之后:两条路

node $K/record_page.cjs <page.html> --seconds=30 [--size=1280x720] [--actions=steps.json] [--out=x.webm]

• --actions 按顺序点按钮、按键、滚动,用来录分步讲解的页面,格式见脚本开头。
• 录完自动核对两件事,不过就退出码 1。V1:文件能播,读得到时长和宽度。 V2:画面动了 —— 取 5 个时间点和第一帧比,变化像素最多的那一帧要 ≥ 0.1%。 V2 抓的是「动画在录之前就播完了」「页面开了减少动态效果」,这两种录出来都是静止画面。 2026-10-07 实测:静止页 0%,只有首屏一小块在动的页 0.25%–0.43%,整屏平移 5.8%。 不用整幅平均差:一小块在动时平均差只有 0.5–1.1,和静止页的 0.35–0.5 拉不开。
• V2 拿第一帧当基准:页面加载很慢、第一帧还是白屏时,静止页也会被判成在动。这条往「放过」那边坏。
• 视频里的数和网页一样要有出处:录的页面最好就是用 page_kit 做出来、过了 check_page.py 的那个。
• 用要 API key 的配音服务时,key 放文件、从文件读,不贴进对话。
• 交给 user 时说:文件路径(page_kit.py where <文件> 打印 Windows 路径)、时长、讲的是什么。

5. 文件

自测(2026-10-07 全过):

python3 $K/check_ste.py --self-test      # 19 通过
python3 $K/check_page.py --self-test     # 13 通过
node $K/record_page.cjs --self-test      # 5 通过

playwright 从 sky-skills 仓根目录的 node_modules 里找;放在别处时设 PLAYWRIGHT_NODE_PATH(check_page)或 NODE_PATH(record_page)。