"The code doesn't lie, but the behavior of black-box systems isn't in the code."
When environments beyond the code are involved (browsers, editors, CDNs, IM platforms, third-party APIs), both coding and debugging mustcapture real data first, then reason。
When to Trigger
Coding Scenarios
- Outputting content that will be consumed by third-party platforms (HTML pushed to CSDN/WeChat/Notion/DingTalk/Feishu)
- Integrating browser/OS APIs (Clipboard / Drag-Drop / File System)
- Calling third-party HTTP APIs that go through CDN/WAF/reverse proxy
- Rendering content in IM / rich text editors
Debugging Scenarios
- Inconsistent behavior across browsers/devices/terminals
- Abnormal paste/copy behavior
- Third-party API returns weird results (empty body, incomplete headers, 200 but error)
- Fails to reproduce locally but has issues online
- Two consecutive rounds of "reasoning from code" fixes are both no-ops(strongest signal)
Black-Box Determination Checklist
| Dimension | Not a black box | Is a black box (triggers this skill) |
|---|---|---|
| Control | Code you wrote yourself | Third-party/platform/browser implementation |
| Documentation completeness | Has complete API documentation | Documentation is incomplete or has undocumented behavior |
| Debuggability | Can add logs and breakpoints | Can only observe input and output from the outside |
| Behavior predictability | Given input必然得到给定输出 | The same input behaves differently in different environments |
Satisfying any 2 items → follow this skill's methodology.
Data Collection Template (Core)
For different black-box types,what the user should capture first:
| Black-Box Type | Capture First | Tool/Method |
|---|---|---|
| Browser paste/copy | Actual clipboard HTML | navigator.clipboard.read() list all mime types + print outerHTML |
| Third-party editor rendering | DOM before paste vs after paste | Copy outerHTML in DevTools Elements and diff |
| Cross-browser rendering | Real device screenshots + DOM structure | Real device/BrowserStack; not just the visual result, must copy the DOM |
| HTTP third-party API | Complete request/response | curl -v / Charles / mitmproxy; compare GET vs POST |
| CDN/WAF interception | Intermediate node information | curl -I check Server / Via headers; empty body + minimal headers is a strong signal |
| IM platforms (WeChat/DingTalk/Feishu) | Actual rendering on both send and receive ends | Must use real device screenshots; cannot only look at the sending end |
| OS clipboard | All available mime types | navigator.clipboard.read() / macOS pbpaste -Prefer html |
| Mobile webview | UA + actually loaded CSS/JS | Chrome DevTools remote debugging |
⚠️ When scraping data, the original format must be preserved:For HTML use outerHTML instead of innerText, for JSON use raw bytes, for binary use hexdump.
Debugging decision flow
Bug 现象 → 涉及外部黑盒?
├─ 是 → 数据采集模板 → 基于数据做假设 → 单变量验证 → 修复 → 追加到 references/
└─ 否 → 走通用系统化调试流程
Key nodes:
- Do not skip data collection:The phenomenon described by the user may be inaccurate; the real data is the fact
- Hypotheses must be based on data:Each hypothesis must be able to cite specific scraping results; "I thought" is not allowed
- Single-variable verification:Change only one variable at a time to verify the hypothesis
- After a fix, it must be recorded:Append a new case to
references/case-{name}.md
Anti-pattern warnings (iron rules)
| ❌ Anti-pattern | ✅ Correct approach |
|---|---|
| "I thought the browser would preserve property X" | "The measured behavior of this browser for property X: [the data scraped out]" |
| Two consecutive rounds of "reasoning from the code" fixes are both no-op, and the third round continues reasoning | On the third roundyou must stop,and have the user output the real data |
| Use try-catch / global polyfill as a fallback to cover up behavior that is not understood | First understand the black box's actual behavior, then decide whether a fallback is warranted |
| Change multiple variables at the same time and try your luck | Single-variable verification, with evidence to follow |
| Once fixed, it's done; the case stays only in your head | Append references/case-{name}.md,with the title containing the system name + symptom |
| Based on "mainstream editors/browsers should all support X" | List the versions actually tested; mark untested ones as unknown |
Boundaries with other skills
| skill | When to use | Relationship to this skill |
|---|---|---|
| General systematic debugging process | General bug debugging | Upstream general methodology; this skill adds the hard rule of "scrape data first" on top of it |
cc-api-design-safety |
When designing your own API | Proactive design; this skill is passive adaptation to third parties |
Case library
After fixing, append a new case to references/,Naming conventions:
| Prefix | Purpose | When to use |
|---|---|---|
case-{system}-{symptom}.md |
Real case:Has already occurred, including the specific root cause/fix/lesson | Accumulated pitfalls encountered |
template-{system}-{symptom}.md |
Placeholder framework:A template to fill in when this type of system encounters a bug in the future | Reserved direction, collection template pre-filled |
After filling in the pitfalls for the template- file, please rename it to case-,to keep the semantics clear.
Currently available:
- CSDN paste list bug — HTML→MD losing the start attribute causes 4 "1." and huge spacing
- HTTP CDN/WAF interception — body empty + headers extremely minimal, GET normal but POST abnormal
- Proxy keyword substring matching misjudgment — normal long body text containing technical terms such as Cloudflare/502 is misjudged by the proxy as an upstream error
- Browser paste behavior differences (template) — to be added
Rule provenance
> 📋 本回复遵循:`cc-external-system-debugging` - [章节]