hybrid-debug

混合应用全栈调试

角色：提供四层分析模型和领域知识库，用于调试混合应用（原生壳 + 内嵌网页）。这是一套方法论 + 知识增强，并非独立的端到端工作流——PDCA 宿主通过 frontmatter dependencies 引用本技能（在完成前置检查后调用），并将运行时检查委托给 browser-debug-toolkit。

领域知识（技术陷阱、原生 ↔ H5 契约模板、锚定案例）位于 reference.md。

本技能存在的原因

混合应用存在层间盲区问题。纯前端工程师往往只在 H5 层（CSS/JS）寻找原因；纯原生工程师往往只在原生代码中寻找原因。平台运行时层（WebView 的 prefers-color-scheme、WKWebView 手势处理、Electron IPC）是双方都不熟悉的灰色地带。

结果是：问题不断被“修复”，却始终没有解决；或者修复一个元素后，同样的隐藏问题扩散到同类元素；又或者表面修补引入新的跨平台不一致。此技能旨在贯彻的核心教训是：

对于混合应用，必须跨原生 / 网页 / 平台运行时进行全链路分析，才能找到根本修复方案。单层分析只会导致打地鼠式修补。

适用场景

强烈信号（满足任意一项即可）：

• 混合应用（WebView / WKWebView / Electron / React Native + H5）出现 UI、主题或行为问题。
• 平台差异——问题在 Android 上复现，但在 iOS 上不复现（或反之）；或者在某个 Electron 版本上复现，但在另一个版本上不复现。这是最强的信号：平台差异几乎总是源于 L2/L3/L4（桥接 / 原生配置 / 平台运行时），而非 L1（H5 代码在各个平台间共享，本身无法造成平台差异）。
• 曾尝试只在一端修复，但问题再次出现，或者遗漏了具有相同根因的同类元素。
• 静默失败：调用链看起来完整，参数正确，日志显示已执行，但运行时行为不正确。这说明可能是平台运行时拦截（L4），或原生 ↔ H5 契约不完整（L2）。

与其他技能的关系

技能	职责	与本技能的关系
PDCA 宿主	承载工作流	通过 frontmatter dependencies 引用本技能的 PDCA 宿主（缺失时 → 宿主中止）。本技能深入分析其技术分析阶段中的混合应用特定问题。宿主是此依赖关系的事实来源。
browser-debug-toolkit	浏览器 DevTools 工具选择决策表	本技能的运行时证据步骤会将任务委托给它——四层分析告诉你要验证什么；browser-debug-toolkit 告诉你用哪个工具来验证。
essence-diagnosis	通用本质诊断（SOAP + 多假设 + 对抗式辩论）	如果混合应用问题经过四层分析后仍不明朗，请升级到 essence-diagnosis，进行更深入的多假设验证。
android-webview-debug	开启 / 关闭 Android WebView 远程调试	通常是前置步骤——在执行本技能的运行时证据步骤之前，启用对 Android WebView 的 chrome-devtools 检查。

四层模型

通过将混合问题定位到以下四层，分析任何混合问题。这些层按症状出现的位置（L1）到根本原因通常隐藏的位置（L4）排序。

层级	关注点	典型信号
L1 — Web 运行时	H5 代码逻辑、CSS 规则、DOM 结构、JS 状态	症状在此处可观察到（颜色错误、缺少类名、布局异常）。这是问题显现的地方，很少是问题起始的地方。
L2 — 原生↔Web 桥接	原生端如何通知 H5（属性注入与类切换或 JS API 调用）、注入内容、时序/顺序	setAttribute('data-theme','dark')，但没有类名变化；在 DOM 就绪前调用 evaluateJavascript；原生端设置了 H5 从未读取的状态。
L3 — 原生配置	Activity/主题配置、WebView 设置（forceDarkAllowed、algorithmicDarkening）、Manifest、Info.plist	Activity 锁定为浅色主题；forceDarkAllowed=false；WebView 暗色模式设置与 H5 的假设相矛盾。
L4 — 平台运行时	与桌面浏览器行为不同的平台专属 WebView/WKWebView/Electron 行为	Android WebView 的 prefers-color-scheme 跟随 isLightTheme，而非系统暗色模式；WKWebView 手势异常；Electron IPC 序列化限制。

唯一重要的原则：绝不要止步于 L1

在 L1 找到原因是起点，而非终点。确定 L1 原因后，始终要追问：“为什么 L1 的状态会是这样？”——并沿着 L2 → L3/L4 追查，直到对根本原因的把握达到较高程度。

止步于 L1 是混合调试中最常见的失误。一个典型陷阱是：L1 显示 --color-canvas-subtle 解析为浅色值，于是你修补使用它的元素。但更深一层的问题——“为什么这个变量在此平台上会解析为浅色？”——会将你引向 L3/L4，并找到一个能修复所有共享该变量的元素的方案，而不只是一个元素。

平台差异是完整链路的信号

当问题在平台 A 上可以复现、在平台 B 上却无法复现时，不要只分析平台 A。差异源自 L2/L3/L4——应当对比两个平台的桥接路径、原生配置和平台运行时行为。L1 的 H5 代码是共享的；它本身无法解释平台差异。

示例：iOS 调用 setTheme('dark') → 切换 H5 类名 → WKWebView 的 prefers-color-scheme 跟随系统。Android 调用 setAttribute('data-theme','dark') → 没有类名变化 → WebView 的 prefers-color-scheme 保持浅色。差异存在于 L2（桥接机制）和 L4（平台运行时），而非 L1。

调查流程

1. 定位症状所在层（通常是 L1）。观察可见的错误行为，以及导致该行为的确切 CSS/DOM/状态。
2. 追问“为什么 L1 会处于这种状态？”，并沿着 L2 → L3/L4 追溯。此时不要提出修复方案。这一步的目标是将根因置信度提高到高。
3. 交叉核对已知陷阱。 查阅 reference.md — 五个技术陷阱涵盖了最常见的混合环境问题（平台 prefers-color-scheme 特性、双主题变量系统、不完整的原生↔H5 契约、CSS 同特异性源码顺序、开发/构建 CSS 处理差异）。如果符合某个已知陷阱，就可以据此快速确认根因。
4. 用运行时证据锁定根因。 CSS 变量解析、规则优先级和平台媒体查询返回值只能在运行时观察到——静态阅读代码会造成误判。将工具选择交给 browser-debug-toolkit：使用“逐条禁用规则”技术找出生效规则，模拟平台环境（移动端 UA + prefers-color-scheme + 注入的类）以复现设备行为，并对截图进行像素采样，确认实际渲染的颜色。
5. 扫描根因相同的元素。 确认根因后，找出所有存在同一问题的元素/场景（例如，所有使用同一个错误 CSS 变量的元素）。修复一个却漏掉其他问题，必然会导致问题再次出现。
6. 选择修复方案前，评估跨层副作用。 询问：这个修复会改变其他层的现有行为吗？（仅针对 H5 的补丁可能改变 iOS 上现有的视觉效果；仅针对原生端的补丁可能破坏仅限 Web 的代码路径。）修复必须覆盖所有受影响层中的根因，且不能引入新的不一致。
7. 以根因置信度作为执行门槛。 如果第 2 步后置信度仍为模糊或未知，不要急于修复——继续追查，或升级到运行时检测。在根因置信度较低时就开始执行，往往会让首次尝试变成被丢弃的表面补丁。

第 4–7 步背后的通用原则（运行时证据、扫描同根问题、评估副作用、置信度门控）由 runtime-evidence-debug 技能提供（也是 solve-workflow 的 dependencies 条目）。该技能侧重于如何在四层模型内应用这些原则——单独使用时，即使没有完整工作流，也应遵循这些原则的精神。

反模式（禁止的做法）

这些做法会导致打地鼠式修复。请识别并拒绝：

1. 止步于 L1 — 找到 Web 层原因后就直接修复，不追问 L1 为何会处于这种状态。这是修复反复失败的首要原因。
2. 只在单端分析平台差异问题 — 差异存在于 L2/L3/L4；只分析单端，就找错了方向。
3. 通过阅读源码猜测 CSS 规则优先级 — 层叠和变量解析都是运行时行为；务必通过 DevTools 验证。
4. 只修复单点，不扫描同类项 — 修复 pre，却漏掉使用同一错误变量的 thead/kbd/code。
5. 选择修复方案时不评估跨层副作用 — H5 补丁悄然改变其他平台现有的视觉效果。
6. 根因置信度低时就开始执行 — “大概是这个原因”会导致首次尝试被丢弃，白白浪费时间。
7. 用“防御性回退”自我辩解 — 为了保留已知的表面修复，编造经不起推敲的“向后兼容”理由。半吊子的修复比不修更容易造成混乱。

领域知识参考

以下内容存放在 reference.md 中，以精简本文件：

• 五个技术陷阱 — Android WebView 的 prefers-color-scheme 特性、双主题变量系统冲突、不完整的原生↔H5 主题同步契约、CSS 同特异性源顺序陷阱、开发环境与构建环境的 CSS 处理差异。每项均包含行为、官方依据和规避指南。
• 原生↔H5 通信契约模板 — 原生端通知 H5 状态变化时必须保持同步的三项内容（类 + 属性 + 持久化存储），以及统一的 H5 暴露 API 为何优于直接操作 DOM。
• 锚定案例摘要 — 一份经过脱敏的参考案例（某个平台上的深色模式代码块背景未随主题变化），端到端展示四层模型，包括仅尝试 L1 但失败的首次修复，以及成功的完整链路根因修复。