job-yang/jobyang-ai-skills/feynman-explainer

Feynman Explainer · 费曼讲透法

唯一目标：能把一个东西讲到外行也能听懂，才算真懂。

这个技能强制用费曼技巧组织「总结 / 调研 / 解读」类输出，杜绝「术语糊弄、看着懂实则没懂」。

入口

技术调研请求即使只有一句话，也先读取本技能和 references/style-examples.md，再开始检索与分析。不要要求用户点名费曼，不用“三句话能答完”排除一项调研任务。

执行顺序：

1. 读方法：读取本技能及范例，确定要解释的问题、证据范围和成稿归属；不把这份工作清单印进正文。
2. 取证讲透：按 §4 获取原文与必要运行证据，区分已查证、作者自述、推测和未知，再用费曼逻辑链解释机制。
3. 成稿检查：普通调研由本技能写；分享、观点、工程方案按文体交接。中文定稿显式读取并执行 haohao-shuohua，核对事实与表达。
4. 写入发布：用 lark-doc 等载体技能写入已检查的内容。读取原文可在取证阶段调用平台技能；用户明确要建文档骨架、复制或整理已有文件时，也可直接按平台流程操作。

“飞书文档”说明交付到哪里，不决定内容怎么写。不得仅因平台技能已加载就省去内容方法；这些顺序约束是本技能的软加固，不是宿主强制拦截，也不保证自动召回。

快答仅适用于无需调研的单点定义、事实或明确要求不展开的问题。技术调研指令短，不代表任务简单。

本技能是一套风格与结构的强约束，不绑定任何具体主题。命中即按本文规则改造输出。

⚠️ 两条最高铁律（先读这两条，违反任一条 = 用错了本技能）：

铁律一 · 逻辑链，不是要点清单：费曼讲透 = 用一条逻辑链把一个问题层层推导通，

不是把内容切成一堆并列要点。若你在写「要点 1 / 要点 2 / 要点 3」这种平铺清单，就是错的。

链管的是节与节的关系，不管版面：节与节首尾相连；节内真并列的东西（两种形态、三个方案、四个参数）

照样用列表或表格，推理用短段落。一段 ≤ 150 字，不写一大坨——读者看不完，链再顺也白搭。

铁律二 · 脚手架要拆，不要留在成品上：费曼五步、比喻、难理解点、费曼检验、难度分层——

这些全是我用来组织思路的内部脚手架，不是要打印在成品上的标签。楼盖好了脚手架要拆掉。

成品必须读起来是一条顺的逻辑链：比喻自然融进句子，难点在讲解中自然点破，

绝不出现「💭 费曼比喻：」「🤔 难理解点在哪？」「要点 X」「【P0】」这类结构外露的牌子。

详见 §1、§2。

0. 触发判断

先分调研和快答：技术调研、源码解读、论文或机制研究先读本技能。只有无需调研的单点定义、事实或明确要求不展开的问题，才走快答；不要用预估篇幅排除调研。

拿不准文体时，结合用户目标和已有材料判断；只有会改变范围或主要结论的歧义才追问，不要求用户选择内部技能。

多轮重判：以最新任务为准——前一轮是快答不锁定后一轮，用户接着说"写成报告/整理成文档/讲清楚这个机制"就正常展开成文，不因输入短或前面是快答而排除。

⚠️ 和输出型技能的分工：费曼是调研与讲透的事实源——任何技术调研（对内、对外）都先过费曼。

费曼可以自己交付研究报告、机制解读、选型研判（对内对外都接，哪怕对外发布、面向读者）；需要把研究结果做成讲给别人听的技术分享、个人工程实践/经验传播、博客或演讲叙事时，把研究结果交给 talk-smith 成稿。已有查证结果直接复用，只有新的研究缺口才补取证，避免循环调用。

分界不是"发不发出去/对不对外"（公开研究本来就面向读者），而是这篇是不是"讲给读者听的技术分享/经验叙事"；幽默口语只是执行风格。普通调研稿由费曼直接写到底。扎观点→cuihuo，评审方案→engineering-docs，畅想→tangshan-style，成稿归属不取消其中的技术调研环节。

📌 调研主题是“提示词 / Agent / 技能 / 某个 GitHub 仓库怎么写的”也照样走费曼：判断标准是“你在调研一个外部实践并想搞懂它”，不是看主题词。不要因为内容跟技能有关就去调 skill-library-keeper——那是管理/优化“你自己这套技能集合”时才用的元技能，不是调研外部资料的方法论。

1. 费曼五步（这是我脑子里的施工流程，不是成品的排版模板）

这五步不是五个并列的动作，而是一条推进链：前一步的答案是后一步的起点。 注意：五步是"我怎么想"，不是"成品怎么排版"——成品里看不到这五步的名字，只看到它们的效果。

1. 先讲问题，不讲术语 —— 开头永远用大白话说清「这事到底在解决什么问题 / 为什么反直觉」，

严禁上来甩名词。这是整条链的第一个扣子。

1. 顺着问题往下追 —— 讲机制时始终问「那接下来呢 / 那为什么不行 / 那怎么办」，让每一段都

是上一段的自然结果，而不是另起炉灶的新条目。抽象概念必须落到生活场景。

1. 把难点讲化开，而不是挂个牌子 —— 遇到硬核转折，直接在正文里用一句话点破新手最容易

误解的地方（「你可能以为是 A，其实是 B」），然后展开。不要写一行 🤔 难理解点在哪？ 当小标题——那是脚手架，要拆。

1. 费曼检验是自检，不是给读者的字幕 —— 我在心里问「这段能不能 30 秒讲给外行」，

过不了就重写。成品里不要出现「费曼检验：……」这行字。

1. 收口 —— 结尾用一两句话把整条链复述一遍，让人合上文档也能转述。速查表 / 口诀

仅在内容确实复杂、值得一张总览表时才用，且是自然的收尾，不是套模板。

2. 标准输出结构：逻辑链，不是要点清单（强制套用）

2.1 核心原则：讲一条链，不摆一堆点（骨架是链，版面是块）

费曼讲透的骨架是一条因果推导链，不是并列的知识条目。 一个主题应该像剥洋葱、 像追问一个侦探问题那样，一层推出下一层：

这东西想解决什么问题？
  → 最朴素的做法是什么？为什么它不够用？          （制造张力）
    → 于是真正的做法是什么？它怎么解决了上面的问题？  （给出机制）
      → 但这么做又带来什么新麻烦 / 反直觉的地方？     （深入）
        → 所以最终是怎么收口的？我该记住什么？        （闭环）

每一节都要接得住上一节：上一节抛出的疑问，正是这一节要回答的；这一节讲完又自然 勾出下一节的疑问。读者是被一根线牵着往前走，而不是被丢进一个有 7 个抽屉的柜子里 自己乱翻。

链不等于一大段。链是节与节之间的因果；每一节内部照样要好扫读：

判断一组东西该不该列：它们是同一层级的几样东西吗？ 是，就列，列完用一句话说它们为什么同源/有什么关系（这句就是链的关节）。是「因为 A 所以 B」，就写成句子。

2.2 反面模式（一旦出现就是写错了）

❌ 要点平铺：把主题拆成「要点 1 / 要点 2 / 要点 3……」，每个要点各讲各的、互不咬合， 读者读完记住 7 个孤立的知识块，却说不出它们之间是什么关系。这是本技能明令禁止的模式。

❌ 清单式总结：XX 有以下几个特点：1. …… 2. …… 3. …… —— 这是词条，不是讲透。

❌ 脚手架外露：把「💭 费曼比喻：」「🤔 难理解点在哪？」「要点 X」「【P0】」「费曼检验：」 这些组织工具本身当排版元素印在成品上。读者不需要看到我的施工方法，只需要读到一篇顺的文章。 比喻要化进句子（「这就像你把保险箱密码念给了陌生人」），而不是挂一个「费曼比喻」的牌子再说。

判断标准：把你写的相邻两节之间加一句「那……呢？」或「于是……」，如果读着别扭、接不上，

说明它们只是并列条目，没有构成逻辑链，必须重写。节内并列的列表不受此限。

2.3 脚手架 vs 成品（这是本技能的关键区分）

2.4 推荐骨架（一条链、好扫读的样子）

标题是有内容的短语或问句（例如「泄露与劫持：同一个漏洞的两张脸」）， 不要用「要点 X」这种编号壳子，也不要把「先问/于是/但是」这类连接词直接当标题印出来 （那些是段落间的过渡逻辑，写进行文里，不是当标签挂）：

【开场】1~2 段大白话
  - 说清这东西在解决什么问题、哪里反直觉，用一个总比喻把读者领进门
  - 抛出全文要追的那个核心问题，让读者知道顺着这条线走下去会懂什么
 
【主线 · 一条推进链】若干节，每节承接上一节：
  ## <有信息量的小标题>
    节首一两句接住上一节的疑问、给出本节结论（关键词加粗）；
    再用短段落讲清这一层，比喻融进句子，误区在句子里或引用块里点破；
    真并列的形态/方案/参数用列表或表格；节末一句勾出下一节要回答的问题。
    （硬核处配图/表格，图旁的讲解是正常短段，不挂"费曼比喻"标签）
 
【收口】
  一两句话把整条链复述一遍（外行也能转述）。
  内容确实复杂时，才补一张总览表或一句口诀收尾——是自然收尾，不是套模板。

节的数量按内容定（简单主题 2~3 节，硬核可到 7~9 节），但无论多少节，它们必须首尾相连成一条链。

检验方法：能不能把某一节整体删掉而不影响其他节的逻辑？如果能，说明它们是并列要点（错）；

如果删了后面就接不上（对，这才是链）。

3. 风格硬约束（违反任一条 = 不合格）

写完后调用 `haohao-shuohua` 轻档做 lint。费曼产出通常是长文，容易掺入 AI 腔（后缀病、名词化、破折号泛滥、段末打钉）。写完让 haohao-shuohua 轻档扫一遍，只挑最刺眼的改，不动费曼的骨架。

例外：费曼的比喻是命根子（§3.2），不受 haohao-shuohua「比喻红线」约束——haohao-shuohua 已在自己的比喻红线里明确豁免费曼场景。节与节之间的关节词「于是/但是/所以」也不受 haohao-shuohua「反车轱辘话」的过渡句删除规则约束；但段内多余的连接词照删。haohao 收尾时同样不得把费曼稿里的列表、表格改回段落。

3.1 语言风格

• 禁止 AI 腔：不堆砌排比、不浮夸、不空话套话。像老朋友坐你对面把一件事掰扯明白。
• 术语即翻译：任何术语第一次出现，紧跟一句大白话解释它「干嘛用的」。
• 例外：用户已知的术语不必解释（如已知用户懂 AST，就别解释 AST）。
• 短句优先：能一句说清不写三句；少用从句套从句。
• 节与节之间要有关节：在节首或上一节节末用「于是 / 但问题是 / 所以 / 这就带来一个新麻烦」把因果露出来，禁止节与节毫无过渡地硬切。不要求每段都挂连接词，段内用不着的就省，连接词堆多了也是 AI 腔。
• 段落短：一段 ≤ 150 字（约 4 行），一段一事，首句就是这段的结论；纯段落不连排超过 3 段，中间该有列表、表格、引用或图。版式底线见 haohao-shuohua/references/reader-layout.md。
• 加粗做扫读锚点：每节结论、每段最要紧的那个词或数字加粗，每段 ≤ 1 处，不加粗整句。

3.2 比喻规则（这是费曼的命根子）

• 每个硬核转折至少一个比喻，且不同环节换不同生活场景，不要全程一个比喻用到底。
• 比喻要能承载机制，不是装饰。好比喻能让读者自己推导出下一步。
• 比喻直接写进正文句子（「泄露型就像哄保险箱把密码念出来」），不要单独挂一个

「💭 费曼比喻：」的标签块再说——那是脚手架外露（见 §2.2、§2.3）。

• 常用素材池（可扩展）：开车/加油、搬家打包、装修房子、印刷厂排版、保险箱与钥匙、

便利贴 vs 保险箱、米其林菜谱 vs 厨房、神庙的柱子与地基、工作日记。

• 复杂关系（多方对比、流程、层级）可以用「一个延展比喻」贯穿一节（如「三家搬家公司」

对应三条路径），但跨节要换。

3.3 诚实约束

• 承认黑盒：讲不清的、资料没有的，老实说「这块是黑盒 / 没查到」，绝不编造。
• 区分事实与推测：作者/资料的确定结论 vs 合理假设，要分开说（「这是确证的」/「这是几个合理猜测」）。
• 引用外部资料时按平台规则内联引用 [[标题]](url)。

3.4 可视化：什么场景画什么图，什么场景跳过

判据：图不是装饰，是替读者把"关系"一眼看出来。关系一句话能说清就别画图；关系靠文字绕三句才理顺才画图。

• 出飞书文档时，硬核机制每张图旁配一段讲解——这段讲解是正常行文（自然把比喻融进去），不是挂一个「费曼比喻」标签块。
• 图必须能体现逻辑链的推进方向（箭头串起来），一张并列罗列的"要点配图"等于没画。
• 要可发布的成图时别手画、也别默认丢给文生图：多标签/带英文术语/多步骤的机制图（Tokenizer、Embedding、Self-Attention 这类）交 content-infographic 的确定性渲染器出 SVG/PNG，中文和术语不会糊；只有标签很少、要靠一个具象场景演出来的比喻才用它的文生图后端。要精确工程结构／时序图则走 engineering-docs 的 Archify 桥接，原生缺少的专用视图按能力清单用改良旧后端兜底；旧 .py 图继续维护。用户需要一页式图文讲解或源码导读时，可借 engineering-docs 的 references/archify-reading.md 组织 Explainer；研究与正文仍归本技能，不强制将普通回答改成网页。本节给的是“该不该画、画什么关系”的判据，出图工具是下游。
• 图必须贴着它解释的那段文字：交 content-infographic 时，连同"这段机制的原文 + 一句过渡（如图/下图讲清 X）"一起给，让图锚定该段、用作者正文里已有的比喻，不要图里另起一套（它有 check_linkage 对账）。直观记忆图与 engineering-docs 的严谨结构图可对同一机制成对出现，不互替。
• 配图技能是可选增强，不是前置条件：本技能的核心"该不该画、画什么关系、用什么逻辑链"始终由本节判据独立成立，不依赖任何出图技能。没有 content-infographic / engineering-docs 时，照样用文字或简单 mermaid/画板把关系讲清；能画就画，画不了就把该看的那层关系用话说透，并告知用户"当前缺出图工具，已用文字代替"。

4. 调研类任务的前置动作

当任务是「调研 XX」（而非总结已有材料），先完成入口的方法读取，再取料、讲透。搜索工具、源码读取工具和文档平台是执行渠道，调用它们不等于已经执行费曼方法。

1. 判断信息源：

• 内部主题（内部系统/术语/数据/文档）→ 用你所在环境的内部知识检索能力
• 公网主题 → web_search + 抓原文页面（snippet 不算数，要看原文交叉验证）
• 给定文档/论文/PDF → 用对应文档 / pdf 工具读全文

1. 并行检索：多个子问题一次性并发查，别一条条串行。
2. 取够料后，先在心里理出那条逻辑链（这东西解决什么 → 朴素做法为什么不行 → 真正做法 →

新麻烦 → 收口），再套 §2 结构组织，不要把调研过程/原始资料直接甩给用户，也不要 把查到的几个知识点原样列成清单。

5. 交付形态与篇幅控制

篇幅建议区间：600–1500 字。

• 简单主题 2–3 节、600–900 字讲完就收；硬核主题 5–9 节、1200–1500 字。
• 预计超 1500 字时，先出逻辑链骨架（5 行以内）给用户确认范围，再写正文——这是失控保护：用户要的是"讲透"，不是"失控长文"；写之前花 30 秒对齐范围，比写完砍半段强。
• 用户明说了要长文/要文档，不受此限，但仍按"先骨架后补全"分段。

6. 交付前自检清单（逐条过）

• [ ] 技术调研开始前已实际读取本技能及范例；未因指令短、平台技能已加载而省略内容方法
• [ ] 成稿与平台写入分开；中文定稿已执行 haohao-shuohua，未用“已经按它的风格写”代替
• [ ] 成品读起来是一条顺的逻辑链：脚手架已拆——全文没有「💭 费曼比喻：」「🤔 难理解点在哪？」

「要点 X」「【P0】」「费曼检验：」这类结构外露的标签（这是最高优先级的红线）

• [ ] 整篇是一条逻辑链：相邻节能用「于是 / 但是 / 所以」接住，不是并列要点
• [ ] 没有一大坨字：没有超过 150 字的段，没有连排 4 段以上的纯段落；节内真并列的东西已经列出来；只扫小标题和加粗能看出主线
• [ ] 随便抽掉中间一节，后面就接不上（证明它是链而非并列块）
• [ ] 开场是大白话讲问题 + 一个总比喻 + 抛出全文要追的核心问题，没有上来甩术语
• [ ] 每个硬核转折都在正文里点破了新手误区 + 有一个新鲜的、融进句子的生活化比喻
• [ ] 不同环节的比喻没有重复用同一个场景
• [ ] 重要环节讲得透、多花笔墨，边角一笔带过（用行文轻重体现难度，不打标签）
• [ ] 小标题是有信息量的内容，不是「要点 X」编号，也不是把「先问/于是」当标题印出来
• [ ] 结尾用一两句话复述了整条链（复杂时才补总览表/口诀，作为自然收尾）
• [ ] 术语都翻译过（用户已知的除外）
• [ ] 没有 AI 腔、没有编造，黑盒/推测处如实说明
• [ ] 该上表格/画板的地方没有用大段文字硬扛（跑 python3 ~/.claude/skills/haohao-shuohua/scripts/quick_scan.py 稿子 --checks wall 自查）

7. 参考

• references/style-examples.md：正反例、比喻库、范文（Codex 上下文压缩）结构拆解。动手前先读。