外部黑盒系统调试方法论

"代码没说谎,但黑盒系统的行为不在代码里。"

涉及代码以外的环境(浏览器、编辑器、CDN、IM 平台、第三方 API),编码和调试都必须先抓真实数据,再做推理。

---

何时触发

写代码场景

• 输出会被第三方平台消费的内容(HTML 推送到 CSDN/微信/Notion/钉钉/飞书)
• 集成浏览器/操作系统 API(Clipboard / Drag-Drop / File System)
• 调用经过 CDN/WAF/反代的第三方 HTTP API
• 在 IM / 富文本编辑器中渲染内容

调试场景

• 跨浏览器/跨设备/跨终端表现不一致
• 粘贴/复制行为异常
• 第三方 API 返回怪结果(body 空、headers 不全、200 但 error)
• 本地复现失败但线上有问题
• 连续 2 轮"凭代码推理"的修复都 no-op(最强信号)

---

黑盒判定清单

维度	不是黑盒	是黑盒(触发本 skill)
控制权	自己写的代码	第三方/平台/浏览器实现
文档完备性	有完整 API 文档	文档不全或有未文档化行为
可调试性	能加日志、断点	只能从外部观察输入输出
行为可预测	给定输入必然得到给定输出	同一输入在不同环境表现不同

满足任意 2 项 → 走本 skill 方法论。

---

数据采集模板(核心)

不同黑盒类型,第一步该让用户抓什么:

黑盒类型	优先采集	工具/方法
浏览器粘贴/复制	实际剪贴板 HTML	navigator.clipboard.read() 列出所有 mime + 打印 outerHTML
第三方编辑器渲染	粘贴前 vs 粘贴后 DOM	DevTools Elements 拷 outerHTML 做 diff
跨浏览器渲染	真机截图 + DOM 结构	真机/BrowserStack;不仅看效果,要拷 DOM
HTTP 第三方 API	完整 request/response	curl -v / Charles / mitmproxy;比对 GET vs POST
CDN/WAF 拦截	中间节点信息	curl -I 看 Server / Via 头;空 body + 极简 headers 强信号
IM 平台(微信/钉钉/飞书)	发送+接收两端实际渲染	必须真机截图;不能只看发送端
操作系统剪贴板	所有可用 mime type	navigator.clipboard.read() / macOS pbpaste -Prefer html
移动端 webview	UA + 实际加载的 CSS/JS	Chrome DevTools 远程调试

⚠️ 抓数据必须保留原始格式:HTML 用 outerHTML 而非 innerText,JSON 用原始字节,二进制用 hexdump。

---

调试决策流

Bug 现象 → 涉及外部黑盒? 
  ├─ 是 → 数据采集模板 → 基于数据做假设 → 单变量验证 → 修复 → 追加到 references/
  └─ 否 → 走通用系统化调试流程

关键节点:

1. 不要跳过数据采集:用户描述的现象可能不准确,真实数据才是事实
2. 假设必须基于数据:每个假设都要能引用具体的抓取结果,不能"我以为"
3. 单变量验证:一次只改一个变量,验证假设
4. 修复后必须沉淀:追加新案例到 references/case-{name}.md

---

反模式警示(铁律)