html-effectiveness-research

07-research — 研究与学习

"An explainer with collapsible sections, tabbed code samples and a glossary in the margin reads very differently from the same words dumped linearly. The agent can build the scaffolding that makes a new topic navigable."

何时用

用户说	用哪个范式	模板
"rate limit 在这个 repo 里怎么工作"	特性解释器	自建（见下）
"auth flow 是什么样的"	特性解释器	同上
"讲讲一致性哈希 / Raft / token bucket"	概念解释器	../../templates/concept.html
"这是什么 / 我怎么理解 X"	看深度 — markdown 一段或概念解释器	—

特性解释器 = 在这个 repo 里的具体实现（用户已在仓库内） 概念解释器 = 抽象概念（与具体仓库无关，要交互式可视化）

---

范式 7.1 · 特性解释器

空间形状：4 段

1. TL;DR 框 — 一段话讲完核心机制 + 性能数字
2. 请求路径编号步骤 — 1/2/3/4，每步可折叠看代码
3. 配置 Tab 切换 — yaml / route.ts / response 三 tab 切换
4. FAQ — <details> 列表

HTML 骨架：

<aside class="tldr">
  <strong>TL;DR</strong>
  <p>The whole path is ~40 lines and adds about 0.4 ms p50 to every request.</p>
</aside>

<h2>The request path, step by step</h2>
<ol class="steps">
  <li>
    <span class="num">1</span>
    <h3>Identify the caller <code>middleware/ratelimit.ts:21</code></h3>
    <p>The middleware reduces the request to a <code>bucketKey</code>...</p>
    <details><summary>show source</summary>
      <pre><code>...</code></pre>
    </details>
  </li>
  <!-- 步骤 2-4 -->
</ol>

<h2>Configuring a limit on your route</h2>
<div class="tabs" role="tablist">
  <button role="tab" data-tab="yaml" class="active">limits.yaml</button>
  <button role="tab" data-tab="route">route.ts</button>
  <button role="tab" data-tab="resp">response</button>
</div>
<div class="tab-panels">
  <pre data-panel="yaml" class="active"><code>...</code></pre>
  <pre data-panel="route" hidden><code>...</code></pre>
  <pre data-panel="resp" hidden><code>...</code></pre>
</div>

<h2>FAQ</h2>
<details>
  <summary>How do I exempt internal traffic?</summary>
  <p>Set <code>x-acme-internal: 1</code> from the caller; the middleware checks it against mTLS peer name.</p>
</details>