feat: 加 §13 实战用法 section

- 心智模型对比（Chrome vs Lightpanda）
- 三大常见误解
- 场景判断表（文字站 vs 图片站）
- Lightpanda + VLM 四层组合拳管道
- 典型项目场景映射（单跑 vs 必须配 VLM）
- 实战命令速查（fetch markdown/html、Playwright 脚本）
- 三个坑 + 铁律

index.html

@@ -249,6 +249,7 @@ footer a:hover{text-decoration:underline}
     <a href="#s8">MCP</a>
     <a href="#s9">构建</a>
     <a href="#s10">限制</a>
+    <a href="#s13" style="color:var(--accent3)">实战用法 ★</a>
   </nav>
   <div class="right">
     <a href="https://github.com/lightpanda-io/browser" target="_blank">GitHub ↗</a>
@@ -886,6 +887,204 @@ zig build <span class="tok-t">-Doptimize</span>=<span class="tok-n">ReleaseSafe<
   </table>
 </section>
 
+<!-- ========== S13: 实战用法 ========== -->
+<section id="s13" style="background:linear-gradient(180deg,transparent,rgba(255,107,157,.03) 40%,transparent);padding-top:6rem;padding-bottom:6rem">
+  <div class="section-head">
+    <div class="section-num" style="color:var(--accent3)">§ 13 / FIELD MANUAL · 实战用法</div>
+    <h2 style="background:linear-gradient(135deg,#fff,var(--accent3))!important;-webkit-background-clip:text;-webkit-text-fill-color:transparent">什么时候用它，什么时候别用</h2>
+    <p class="lead">前面 12 段讲"它是什么、怎么实现"。这一段讲"你该不该用、怎么组合"。技术解析的闭环。</p>
+  </div>
+
+  <div class="verdict-box" style="margin-bottom:3rem;border-color:var(--accent3);background:linear-gradient(135deg,rgba(255,107,157,.08),rgba(255,181,71,.04))">
+    <div class="icon">🧠</div>
+    <div>
+      <h3 style="color:var(--accent3)">一句话定位</h3>
+      <p>
+        Lightpanda <strong>不是给你用的</strong>，是给<strong>你的脚本</strong>用的。
+        就像你不会直接打开 MySQL，你写代码去查 MySQL——Lightpanda 也一样，你写代码让它去"读"网页。
+        你平时上网继续用 Chrome；写脚本批量抓 1000 个页面——用 Lightpanda。
+      </p>
+    </div>
+  </div>
+
+  <h3 style="color:var(--text);margin:2rem 0 1rem">心智模型对比</h3>
+  <table>
+    <thead><tr><th></th><th>你用 Chrome</th><th>脚本用 Lightpanda</th></tr></thead>
+    <tbody>
+      <tr><td><strong>谁在操作</strong></td><td>人（鼠标点击）</td><td>代码（goto/click/eval）</td></tr>
+      <tr><td><strong>目的</strong></td><td>看、购物、娱乐</td><td>提取数据 / 监控 / 自动化</td></tr>
+      <tr><td><strong>速度</strong></td><td>人速</td><td>每秒几十页</td></tr>
+      <tr><td><strong>规模</strong></td><td>1 个页面</td><td>1000 个页面</td></tr>
+      <tr><td><strong>产出</strong></td><td>脑子里的记忆</td><td>JSON / CSV / 数据库</td></tr>
+      <tr><td><strong>界面</strong></td><td>有窗口看得到</td><td>完全无 UI，看不到渲染</td></tr>
+    </tbody>
+  </table>
+
+  <h3 style="color:var(--text);margin:3rem 0 1rem">🚫 三个常见误解</h3>
+  <div class="grid-3">
+    <div class="card" style="border-color:var(--red)">
+      <h4 style="color:var(--red)">✗ 不是搜索引擎</h4>
+      <p>不索引互联网。你给一个 URL，它只处理这一个页面。想搜索得先有 URL 列表。</p>
+    </div>
+    <div class="card" style="border-color:var(--red)">
+      <h4 style="color:var(--red)">✗ 不是下载器</h4>
+      <p>默认不存任何文件，结果流到 stdout。要留下必须自己重定向到文件或写数据库。</p>
+    </div>
+    <div class="card" style="border-color:var(--red)">
+      <h4 style="color:var(--red)">✗ 不是"批量下原始文件"</h4>
+      <p>它是<strong>"批量读网页 → 提取结构化数据"</strong>。保存的不是 HTML 本身，是从 HTML 里挖出来的字段。</p>
+    </div>
+  </div>
+
+  <h3 style="color:var(--text);margin:3rem 0 1rem">🎯 场景判断表</h3>
+  <table>
+    <thead><tr><th>场景</th><th>能不能用</th><th>备注</th></tr></thead>
+    <tbody>
+      <tr><td>新闻 / 博客 / Wiki</td><td style="color:var(--green)">✅ 完美</td><td>纯文字，token 友好 Markdown</td></tr>
+      <tr><td>API 文档、技术站</td><td style="color:var(--green)">✅ 完美</td><td>结构化强</td></tr>
+      <tr><td>论坛（HN / Reddit / V2EX）</td><td style="color:var(--green)">✅ 完美</td><td>纯文字内容</td></tr>
+      <tr><td>SPA 后台管理系统</td><td style="color:var(--green)">✅ 大多行</td><td>DOM 驱动，需要配合登录态</td></tr>
+      <tr><td>企业官网 / SaaS 介绍页</td><td style="color:var(--orange)">🟡 部分</td><td>标题在文字，卖点常在海报</td></tr>
+      <tr><td><strong>电商商品详情页</strong></td><td style="color:var(--red)">❌ <strong>瞎</strong></td><td>规格、材质、使用说明<strong>全在长图</strong></td></tr>
+      <tr><td><strong>小红书 / Instagram</strong></td><td style="color:var(--red)">❌ <strong>瞎</strong></td><td>核心信息载体是图文笔记</td></tr>
+      <tr><td><strong>PDF-as-webpage</strong></td><td style="color:var(--red)">❌ <strong>瞎</strong></td><td>很多文档站把 PDF 转成图嵌入</td></tr>
+      <tr><td>视频站</td><td style="color:var(--red)">❌</td><td>视频内容根本不是 DOM</td></tr>
+    </tbody>
+  </table>
+
+  <div class="hl crit" style="margin-top:2rem">
+    <strong>核心限制</strong>：Lightpanda 对"信息在图里"的站是<strong>瞎子</strong>。
+    它能看到 <code>&lt;img src="xxx.jpg"&gt;</code> 的 URL，但<strong>不下载图片字节、不做 OCR、不做视觉理解</strong>。
+    这是设计取舍——为了 11× 速度砍掉的能力，不是 bug。
+  </div>
+
+  <h3 style="color:var(--text);margin:3rem 0 1rem">🏗️ 正确的组合拳 · Lightpanda + VLM 管道</h3>
+  <p style="color:var(--text2);margin-bottom:1rem">
+    单 Lightpanda 覆盖 60% 的场景，剩下 40%（中文电商、小红书、海报站）必须靠<strong>视觉大模型（VLM）</strong>补。
+    分层调度后，总成本比 "真 Chrome + 整页截图 + VLM" 便宜 5-10 倍。
+  </p>
+
+  <div class="arch">
+    <div class="arch-layer zig">
+      <div class="ln">① 抓取层</div>
+      <div class="val">Lightpanda 抓页面 → DOM + 文字 + 图片 URL 列表</div>
+      <div class="tech">快 · 省钱</div>
+    </div>
+    <div class="arch-layer curl">
+      <div class="ln">② 下载层</div>
+      <div class="val">普通 curl / wget 下载需要的图片字节（非 Lightpanda）</div>
+      <div class="tech">按需精挑</div>
+    </div>
+    <div class="arch-layer v8">
+      <div class="ln">③ 视觉层</div>
+      <div class="val">VLM 读图：Claude Sonnet Vision / GPT-4V / Qwen-VL-Max / PaddleOCR</div>
+      <div class="tech">智能 · 贵</div>
+    </div>
+    <div class="arch-layer rust">
+      <div class="ln">④ 合并层</div>
+      <div class="val">Lightpanda 抽到的文字字段 + VLM 从图读到的字段 → 完整结构化数据</div>
+      <div class="tech">→ PostgreSQL / JSON</div>
+    </div>
+  </div>
+
+  <div class="hl ok">
+    <strong>分工原则</strong>：Lightpanda 负责"快省地扒骨架"，VLM 负责"贵但能看懂图"。
+    加起来比用真 Chrome 方案便宜数倍——因为 Chrome 会加载一堆你不需要的字体、CSS、JS 资源，
+    还要先渲染才能截屏；Lightpanda 直接给你 <code>&lt;img src&gt;</code> URL，你精确挑要看的图交给 VLM。
+  </div>
+
+  <h3 style="color:var(--text);margin:3rem 0 1rem">📂 典型项目的场景映射</h3>
+  <div class="grid-2">
+    <div class="card" style="border-color:var(--green)">
+      <h4 style="color:var(--green)">✓ 单跑 Lightpanda 就够</h4>
+      <ul>
+        <li><strong>法条/题库补抓</strong> — 大多是纯文字</li>
+        <li><strong>新闻监控 / 技术文档同步</strong></li>
+        <li><strong>Wiki / Gitea / 文档站搜索</strong></li>
+        <li><strong>论坛社区数据采集</strong></li>
+        <li><strong>SaaS 后台 API 数据导出</strong></li>
+      </ul>
+    </div>
+    <div class="card" style="border-color:var(--red)">
+      <h4 style="color:var(--red)">✗ 必须配 VLM 组合拳</h4>
+      <ul>
+        <li><strong>电商供应商批量采购</strong> — 80% 信息在长图</li>
+        <li><strong>淘宝/京东对标比价</strong> — 价格、规格、活动规则全在图</li>
+        <li><strong>汽修维修手册</strong> — 接线图、爆炸图必须视觉理解</li>
+        <li><strong>小红书爆款挖掘</strong> — 核心是图文笔记</li>
+        <li><strong>营销活动页抓取</strong> — 海报里写满减规则</li>
+      </ul>
+    </div>
+  </div>
+
+  <h3 style="color:var(--text);margin:3rem 0 1rem">🛠️ 实战命令速查</h3>
+
+  <div class="card" style="margin-bottom:1rem">
+    <h4>一次性抓 + 转 Markdown（最快路径）</h4>
+<pre style="margin:.75rem 0"><code>ssh root@VPS <span class="tok-s">'/opt/lightpanda/lightpanda fetch \
+  --dump markdown \
+  --wait-until networkidle \
+  --wait-ms 3000 \
+  https://目标站.com'</span></code></pre>
+    <p style="color:var(--text2);font-size:.85rem">适合：一次性抓一个 URL，把结果直接喂给 LLM 做摘要/问答</p>
+  </div>
+
+  <div class="card" style="margin-bottom:1rem">
+    <h4>要完整 HTML（图片 URL + 主推文案 + 所有 DOM）</h4>
+<pre style="margin:.75rem 0"><code>ssh root@VPS <span class="tok-s">'/opt/lightpanda/lightpanda fetch \
+  --dump html \
+  --wait-until networkidle \
+  --wait-ms 5000 \
+  --with-base \
+  https://目标站.com'</span></code></pre>
+    <p style="color:var(--text2);font-size:.85rem">
+      适合：要图片 URL 列表、要页面所有内容。<strong>注意</strong>：<code>--dump markdown</code> 会省略 hero/图片区块，
+      想拿到产品主推文案必须用 html 自己 parse。
+    </p>
+  </div>
+
+  <div class="card" style="margin-bottom:1rem">
+    <h4>脚本化（需要登录态 / JS 交互 / 多步操作）</h4>
+<pre style="margin:.75rem 0"><code><span class="tok-c"># 本机开 SSH 隧道</span>
+ssh <span class="tok-t">-N -L</span> 9222:127.0.0.1:9222 root@VPS
+
+<span class="tok-c"># 另一个终端跑 Python（Playwright connectOverCDP）</span>
+browser = <span class="tok-k">await</span> p.chromium.connect_over_cdp(<span class="tok-s">"http://127.0.0.1:9222"</span>)
+context = <span class="tok-k">await</span> browser.new_context()
+<span class="tok-k">await</span> context.add_cookies(cookies)  <span class="tok-c"># 从本机 Chrome 导的登录态</span>
+page = <span class="tok-k">await</span> context.new_page()
+<span class="tok-k">await</span> page.goto(<span class="tok-s">"https://后台.com/订单"</span>)
+data = <span class="tok-k">await</span> page.eval_on_selector_all(<span class="tok-s">"..."</span>, <span class="tok-s">"..."</span>)</code></pre>
+    <p style="color:var(--text2);font-size:.85rem">适合：需要保持登录态的后台管理系统、多步表单交互、抓取分页列表</p>
+  </div>
+
+  <h3 style="color:var(--text);margin:3rem 0 1rem">⚠️ 三个坑必须记住</h3>
+  <div class="grid-3">
+    <div class="card" style="border-color:var(--orange)">
+      <h4 style="color:var(--orange)">坑 1 · wait 时机</h4>
+      <p>默认 <code>--wait-until=done</code>，SPA 内容可能还没渲染就 dump 了。</p>
+      <p><strong>解法</strong>：重页面加 <code>--wait-until networkidle --wait-ms 3000</code>。
+        Apple 首页就是这样才拿到 hero 主推产品。</p>
+    </div>
+    <div class="card" style="border-color:var(--orange)">
+      <h4 style="color:var(--orange)">坑 2 · markdown 省略</h4>
+      <p><code>--dump markdown</code> 是"语义精简"模式，会跳过图片为主的 hero 区块、产品卡片。</p>
+      <p><strong>解法</strong>：想拿到所有内容用 <code>--dump html</code>，自己写 parser 提取 H2/H3/class。</p>
+    </div>
+    <div class="card" style="border-color:var(--orange)">
+      <h4 style="color:var(--orange)">坑 3 · UA 反爬</h4>
+      <p>默认 UA 是 <code>Lightpanda/1.0</code>，很容易被反爬识别封 IP。</p>
+      <p><strong>解法</strong>：加 <code>--user-agent-suffix</code> 或自建 UA。注意代码禁止含 "Mozilla" 的伪装 UA。</p>
+    </div>
+  </div>
+
+  <div class="hl warn" style="margin-top:3rem">
+    <strong>💡 铁律</strong>：Lightpanda 是抓取管道的"第一道工序"，不是全流程方案。
+    启动任何项目前先想清楚下一道工序是什么——直接入库？给 VLM 看图？给 LLM 做摘要？触发告警？
+    <strong>没想清楚下游就别用它</strong>——它只是个"不渲染的 Chrome"，不是银弹。
+  </div>
+</section>
+
 <footer>
   <p><strong>Lightpanda 源码深度解析</strong> · based on <code>lightpanda-io/browser@e6cffae</code></p>
   <p>读源码日期 2026-04-13 · 作者 kang · 部署 <a href="https://lightpanda-docs.kang-kang.com">lightpanda-docs.kang-kang.com</a></p>