AHA · 概念图解

把任意复杂概念讲成一份渐进分层、大图少字、可交互的独立 HTML 页面。 目标是建立正确的心智模型 —— 不是模仿幼儿说话，不是让人"觉得懂了"， 而是让人"真的懂了"。

When to Use

用： 用户想真正理解某概念（"讲讲 X""X 到底是什么""X 和 Y 有什么区别"）、 要求图解 / 可视化 / 做一页解释（含 aha）、想给别人分享一份概念讲解。

便宜预检：两三句话能答清的问题直接答，不起本 skill —— 完整的图解页是为"值得读五分钟"的概念准备的。

不用： 超短摘要、一句话回答；专家向深潜（读者本来就会，缺的不是解释）； 改写既有文档（那是文档编辑任务）。

立场（先读这个）

1. 用户的明确要求 > 本 skill 的默认建议。 用户指定语言、受众、文件位置、 讲解范围或动效偏好时，按用户的执行。
2. 语言跟随用户提问的语言。
3. 简化不得牺牲准确性：说不准的事实不编精确数字，注明推断与未验证的部分。
4. 读者是聪明的、只是不熟悉这个领域的人 —— 尊重他们，不居高临下， 禁用"很简单""显然""只要……就行"。

七层骨架（固定，内容可取舍）

每层「为什么这样设计」的学习科学依据(先行组织者/结构映射/测试效应等) 集中在 references/theory.md（改层、改顺序、改常数前必读；日常生成不读）。

菜单，不是模板：按主题取舍 —— 不是每层都要写满；某层对这个主题没价值 就不写，但第 1、4、7 层永远要有。反过来，不得为了凑层加没有解释价值的内容。

起点校准（渐进式的实现）

校准只调起点与类比选择，永不删层。 判断错了，读者往下读一层就自愈； 但砍掉内容是不可挽回的。用户显式指定受众时，覆盖一切信号。 页首徽章只标级别（起点 L1）—— 依据一行放页脚小字（起点依据：L2 · 提问带 统计背景），读者首屏不被校准元信息打扰。L2 页在类比处点明桥接来源 （pill："桥接自：Rust 所有权" —— 不写"你熟悉的"，页面会被分享给其他读者）。

关键契约

类比边界 —— 每个类比：① 只讲一个映射；② 标注在哪里失效， 且失效点中至少一条要指向类比所掩盖的真实机制 （如手套类比掩盖了"结果测量前不存在"、房卡类比掩盖了"静态判定 vs 动态巡视"）； ③ 建立直觉后仍要讲真实机制，类比不能替代机制。

具体实例 —— 第 4 层至少一个带真实值的实例（4 个采样点手算一次 DFT、 D↔E 成环从根走不到）。大白话降低语言门槛，实例才让抽象落地，两者不可互相替代。

数字纪律 + 数字账本 —— 关键数字当场复算或给出处；同一句不得混用不同量纲的比例 （坡度比 ≠ 曲率比、倍数 ≠ 百分点）；图形若做了非等比拉伸，caption 必须注明。 页尾账本（脚手架自带 [data-ledger]）：正文里每个 N% / N 倍 都要有一条， data-kind 三选一 —— 实算（页内可复算，写算式）/ 出处（外部来源，写名字）/ 估算（示意值，写假设）；其他关键数字（时长、容量、次数）也建议入账。 数据表内的百分数不入账（表格本身即结构化上下文,门 13 豁免表内数字,见「质量门」)。没有比例类数字就删掉全部条目、保留块。量级断言（「上千万条才慢」「基本都支持」）同样要么给出处、要么软化成「通常/视实现而定」。"看起来像事实错误"的表述比模糊更糟 —— 这套页面的信誉押在每个数字都经得起复算上；账本缺条目时补来源，不是删数字。

自测题 —— 问题不能靠复述第 7 层公式回答；答案 ≤80 字/问，默认折叠； 只改脚手架里的文字，不改 data-quiz* 与 hidden(结构由门 12 校验,见「质量门」)。

形式选择映射（选错形式 = 白画）：

规模上限（防内容过载，拖慢生成且不加分）：模拟器 4-6 步、 SVG 节点 ≤ 12、对比卡 ≤ 3、自测 2-3 问。账本以全覆盖正文比例数字为先， 条数尽量 ≤ 6(多时合并同类项，不靠漏数字凑条数)。

大图少字：每节一个视觉中心；文字只留标题、关键标签、必要解释与边界。 禁止把长篇正文拆成多个文字卡片伪装成视觉化。 第 4 层的核心机制（对象图 / 交换过程 / 混合过程）至少要有一个图形载体 —— "判活看根""混颜料"这类核心概念不允许只活在旁白文字里； 视觉性强的类比（调颜料、滚雪球）优先配图而非纯文字。

动画体面：动画必须表现内容或状态的真实变化，不许只让成品闪烁/脉冲/高亮； 非首屏动画进视口自动播一次，保留暂停/逐步/重播；prefers-reduced-motion 直出静态结果；每个动画都有可读的静态版本。

因果链：输入或条件 → 发生什么 → 输出或影响。优先讲清少量相互连接的概念， 不罗列事实；不为"简短"删掉会改变含义的关键限定。

形式硬规则：

• 单文件自包含，渲染零远程依赖（tokens/引擎/工具条/自测块/账本已由 CLI 注入）
• 取色只能 var(--token)，tokens 块外禁止 hex/rgb/hsl； SVG 取色用 tokens 块中已定义的任意变量——常用:--cat-a/b/c(及 -soft)/ --accent / --warn / --ok / --info(及 -soft)/ --t-1…4(文字)/ --line、--line-2(线框)/ --panel、--surface(填充)
• 页面局部布局样式允许且常需要（before/after 网格、手算表、SVG 尺寸等）： 集中放在 <head> 里一个新增的 <style>，只用 var()；不改 tokens 块， 不改 [SCAFFOLD-STYLE]。tokens 已提供的类（.card .callout .compare .fails .flow .pipe .analogy .panel .pill .grid-2/3）优先复用
• 模拟器的 .sim-node 可按需增删（引擎遍历全部 [data-node]），值需唯一
• 语义 HTML：恰好一个 <h1>，标题不跳档，img 必带 alt
• 模拟器标签跟随页面语言（专有标识符 ClientHello/Q·Kᵀ 除外）
• 正文不得有"你问的"等提问者指代（页面会被分享给未提问的读者）

工作流（三步）

模型推理是主要耗时（写约 200 行高质量解释，实测分钟级），工具调用不到 1 分钟。 能砍的只有读文件（已归零）、浏览器验证（默认跳过）、探索性命令（禁止）。 CLI 做施工（样板注入/check/serve），你只做内容创意。

Step 1 · 跑一条命令

命令输出的第一行（stderr）会标注配套 skill 版本：与你读到的这份 SKILL.md 开头 metadata.version 比对 —— 不低于它就直接继续；低于它说明 skill 是旧版，先执行输出里给的升级命令（npx skills add ...，幂等覆盖）， 升级后必须重新读取 SKILL.md 再从 Step 1 重来（本次生成作废，脚手架 结构可能已变）。

npx @dimples/aha new <slug> "<概念名>"

(版本体系:skill 本体 1.x / design tokens v1.3.x / npm CLI 0.x 是三条独立发布线, 版本握手只校验 skill ↔ CLI 配套,互不约束。) <slug> 用小写 kebab-case(如 bayes-theorem),是文件名与 URL 的一部分。 标题参数决定脚手架 lang：概念名是纯英文而用户说中文时， 传 "<英文名>（<中文名>）"（如 WebGL（网页图形库）），免得后补一次 lang 修正。

若命令退出并输出"存储位置选择"（仅 Windows 首次/存量用户会出现）： 把给出的选项转述给用户，按其选择执行对应的 aha config ... 命令， 然后重新运行本命令即可。

零 skill 文件读取、零探索命令。脚手架 = canonical tokens + 工具条 + 引擎 + 七节空槽（第 7 层含自测块与数字账本），未填即过 13 门。跑完直接进 Step 2， 不要 ls/find/grep skill 目录、不要读任何 assets / references / cli 源码 （实测：探索过的一律显著更慢；唯一例外是选配模式按 references/modes.md 明示的文件）。 读取刚生成的页面本身不受此限 —— Edit 需要精确的 old_string，读它是必需的。

Step 2 · 分块 Edit 填完全部内容

动笔前先定界（默想一行，不进页面）：本页讲 X 的 A/B/C，不讲 D —— 它同时是第 6 层「边界」的素材。随后校准起点（见上节），按内容自然分块、建议 4-6 次 Edit 填完（不逐槽小改，也不必为凑次数硬合并）：① <head> 新增一个页面局部 <style>； ② 起点徽章 起点 L1 + 页脚 起点依据：… + 容器内七槽正文 + 自测块 + 账本条目 (从 (SLOT1: 到 (SLOT8: —— 1-7 对应七层,SLOT8 是数字账本条目;约 200 行,可拆成两次)；③ SIM_STEPS 步骤数据。 脚手架按标题语言判定 lang —— 英文标题配中文内容时，把 lang 改对并入上面任意一次 Edit，不单开一步。 [SCAFFOLD-STYLE] / [QUIZ-TOGGLE] / [SIM-ENGINE] / [TOOLBAR] 四段 原样保留，不进 Edit 范围；脚手架的说明注释可留可删，不影响门。 填完 grep 一次页面,确认不再有 (SLOT / (依据 / (中文标签 字样(全半角都试,防誊写误差)。 内容约束见上方「七层骨架」「关键契约」—— 不要读 reference.html。

内容自检（Step 2 写完 → Step 3 之前，8 个是/否，不需要工具）

讲不清的地方就是知识漏洞 —— 补齐再交付，哪条答不上就回资料补哪条：

1. 第 4 层每个关键术语，我都能用一句大白话说出它「做了什么」？图里的每条连线/箭头，与机制里的指向一一对应？
2. 第 4 层有至少一个带真实值的具体实例，而不只有抽象描述？
3. 每个类比的失效点里，至少一条指向了类比掩盖的真实机制？
4. 页面里每个精确数字，我都复算过或有出处，并且比例类数字已入账本？
5. 第 5 层邻居概念，我是在按「各自改变什么」对比，而不是罗列特性？
6. 第 6 层的误区，先点名了错误直觉（你可能以为 X）再纠正，而不是只陈述正确答案？
7. 第 7 层：公式单独拿给读者不借助上文也成立；自测题不能靠复述公式回答，答案也不照抄正文原句（换个说法/换个数字）？
8. 模拟器的每一步、图里的每个状态，与正文叙述互不矛盾（同一数字/同一过程）？

全部「是」才进 Step 3；有「否」→ 先改内容（改了几处，回执里如实记）。

Step 3 · check + 交付（跳过浏览器验证）

npx @dimples/aha check <aha new 输出的路径> && npx @dimples/aha start

13 门(按 check 输出顺序): 1.单 h1 / 2.标题不跳档 / 3.head 元数据 / 4.img alt / 5.tokens 与 canonical 一致 / 6.块外无颜色字面量 / 7.语义类在词表 / 8.脚本可解析且无外链 / 9.无提问者指代 / 10.失败标签 1-2 字一致 / 11.中文页模拟器标签中文化 / 12.自测块(≥2 问,答案默认 hidden)/ 13.数字账本(每个 N%/N 倍 有条目,data-kind 合法;表内百分数豁免)。 门不过 → 修 → 重跑，每轮只修被点名的那一个问题；连续两轮无改善 → 停止修复、 如实报告。不得为了过门删内容、藏溢出、缩字号。门的细节与已知覆盖边界见 references/gates.md(修门修不动时才读)。已知边界:第 1/4 层的存在性、类比失效 边界质量、自检真实性由内容自检与回执铁律兜底,不设机器门;门 5 比对剥注释核心, tokens 注释措辞的历史差异(如旧页注释)属容忍范围。

check 过 → aha start（幂等：未运行则后台拉起守护，已运行则复用）→ 交付。 默认不打开浏览器截图/点击模拟器；用户说「看效果」或反馈「页面有问题」时才截图核查， 此时回执视觉验证如实写 passed（已截图核查）。 交付物 = 可点击的文件链接（粘贴 HTML 源码到聊天不算交付）+ 回执。

交付回执（固定格式）

回执前两行以 check 实际输出为准(与其一致时直接复用)：

check: 13/13 门通过
视觉验证: skipped（默认跳过；说「看效果」即可触发）
校准: 起点 Lx（依据：<一句证据>）
内容自检: 8/8 通过（修正 N 处）
形式门: N 轮

aha start 只输出书架地址与篇数 N，不含本页链接 —— 按下面三行模板写给用户 （三行都必须给出：直达本页 / 书架入口 / 寓言模式的唯一推销，用户不接话就到此为止）：

http://127.0.0.1:7332/<slug>.html
你历史产生过 N 条概念图解，可以访问 http://127.0.0.1:7332 查看概念书架
如果你还想通过一个寓言故事来方便记忆，请对我说：补充寓言故事

其他命令：npx @dimples/aha serve（本地 7332，主页 = 概念书架）、 npx @dimples/aha share（临时公网链接）。

选配模式（默认不用，用户明确要求才触发）

• 寓言故事：用户在交付后说「补充寓言故事」/「加个寓言帮我记」/ fable 时， 读 references/modes.md 与 references/fable.md，按其契约写 ≤1000 字同构寓言， 插入自测块之后、账本之前，重跑 check 13/13。
• vgpu 着色器展示层：仅当概念本质是连续场/波/流 且 用户明确要求更炫/实时演示； 核心解释永不依赖它。细则见 references/modes.md。

反模式（违反即重做）

• ❌ 跳过或假做内容自检（8 问有「否」却照样交付）
• ❌ 类比没有失效边界；类比替代了真实机制
• ❌ 第 4 层只有抽象机制没有带真实值的实例
• ❌ 特性罗列式对比（必须按"改变什么"对比）
• ❌ 误区只陈述正确答案、不点名错误直觉
• ❌ 自测题能靠复述公式回答；答案默认展开；删掉自测块过门
• ❌ 账本缺条目时删数字过门；把估算标成实算
• ❌ 文字卡片阵列伪装视觉化
• ❌ 只会闪烁/高亮的装饰动画；声称存在但没实现的交互
• ❌ 内联颜色、修改 tokens、引入远程渲染依赖
• ❌ 居高临下的语气词（"很简单""显然""只要"）
• ❌ 为了过 check 删内容 / 藏溢出 / 缩字号 —— 这算作弊，不算修复
• ❌ 把没有视觉验证说成"已验证"

English quick reference

The Chinese sections above are the full contract; this is the command sheet.

1. npx @dimples/aha new <slug> "<concept>" — CLI injects everything; read nothing else (no ls/grep of skill dir, assets, references, cli).
2. Scope the page, calibrate L1/L2/L3, fill slots + SIM_STEPS in 4-6 Edits (~200 lines, colors only via var(--token)), grep no (SLOT remains, answer the 8 self-check questions.
3. aha check <path> 13/13 → aha start → deliver file link + receipt (visual verification stays skipped unless screenshotted).

Optional, never default: fable / vgpu — explicit request only, see references/modes.md. Never: inline color literals, questioner references, decorative-only animation, unverified claims, skipping the self-check.