upstream-dependency-debug

将依赖升级作为 Bug 修复

角色：一种决策与执行方法，用于处理这样一种情况：修复 Bug 最简洁的方式是升级依赖，而不是编写本地变通方案。这是一项方法增强：既可独立调用，也会在 PDCA 主持者的技术分析阶段被引用（作为“没有可行解决方案”分支的乐观对照）。

为什么需要这项技能

工程师（以及 AI Agent）遇到 Bug 时，往往会条件反射地在本地打补丁——添加保护逻辑、调整计时器、隐藏元素、覆盖 CSS 规则。当根本原因存在于上游依赖中时，这种反应往往是错误的：本地补丁成了掩盖他人 Bug 的变通方案，而变通方案会不断叠加。

这项技能旨在打破以下模式：

某个 Bug 的真正修复方法是“升级库”，但没人查看上游的 Changelog。相反，三层本地变通方案被层层叠加——一个魔法数字计时器、一次 UX 降级，以及一条平台会悄悄忽略的 CSS 覆盖规则。每一层在真实设备上的失效方式都略有不同。几周后，终于有人查看了 Changelog，发现修复早在两个次版本前就已发布，于是只需在 package.json 中改一行，就能替代所有三个变通方案。

典型案例（已脱敏）：一个富文本编辑器的任务列表项在 iOS 上进行 IME 输入时，出现异常的选中高亮。曾尝试三种本地变通方案，但在真实设备上都失败了——最后一种失败的原因是，iOS 会在输入期间强制渲染原生 ::selection 背景，任何 CSS 都无法覆盖它。真正的修复方法是将编辑器库升级两个次版本，上游已修复了输入期间附近的组件复用行为。本地代码无需任何更改。

核心经验：

编写变通方案前，先问：“这个 Bug 是否已在上游修复？”升级一次依赖往往只需改一行，比任何本地补丁都更省力、更正确，也更持久。

适用场景

强烈信号（满足任意一条即可——这项技能应当经常调用，因为人们容易忘记“先检查上游”这一点）：

• Bug 涉及某个具名的第三方库、框架或 API，且与特定版本相关。
• 症状具有平台或库特异性——例如 Bug 在 iOS 上可复现、在桌面版 Chrome 上无法复现；或只出现在某个框架特定的渲染路径中；或只在最近升级依赖后出现。
• 静默失败：调用链看起来完整，参数也正确，日志显示代码已执行——但行为不正确。这通常意味着平台或运行时拦截，而本应由库处理这种情况。
• 变通方案不断叠加：你已经编写了一两个本地补丁，但每个都只能部分生效，或者会带来新的降级（魔法数字计时、UX 降级、无效的 CSS）。
• 某个平台上的 CSS 或布局 Bug 中，!important 覆盖规则悄无声息地失效——这强烈表明渲染行为由平台强制控制，无法通过 CSS 修复。

4 步决策顺序

上述信号出现时，在编写任何本地补丁之前，请按以下顺序处理：

1. 判断 Bug 的归属：问题更可能出在上游还是我们的代码中？上游问题的信号包括：症状与特定平台或库的行为有关；仅在特定环境中复现；行为异常的层由该库负责（选择、组合、渲染）。
2. 如果问题可能出在上游——检查依赖项的 Changelog / Release Notes / Issues，寻找匹配的修复。按与症状对应的关键字搜索依赖项的变更日志（例如 composition、selection、Safari、iOS、widget、cursor）。确认是否已有修复版本，以及项目当前使用的版本是否低于该版本。
3. 优先升级依赖项（patch/minor，semver 风险较低），而不是编写本地变通方案。对于遵循 semver 的库，按约定，同一 major 版本内的 minor/patch 升级不会引入破坏性变更。
4. 仅在无法升级时才考虑变通方案——唯一可用的修复版本包含破坏性变更、项目的版本被锁定，或上游尚未修复。如果必须采用变通方案，请注明它是临时方案，并记录其触发条件和所跟踪的上游问题。

反模式（禁止的做法）

1. 尚未检查 Changelog 就叠加变通方案——这是最常见的失败原因。上游修复可能早已存在。
2. 认为“CSS !important 能解决问题”，即使问题出在平台强制执行的渲染路径中——某些平台行为（例如 iOS 在组合期间的 ::selection）会完全忽略 CSS。
3. 使用神奇数字的计时变通方案（在 compositionend 后执行 setTimeout 120ms）——这会掩盖症状、在负载较高时失效，而且始终无法解决根本原因。
4. 降低用户体验的变通方案（在组合期间将小组件降级为源码标记）——它们以牺牲用户体验为代价隐藏 Bug，而且往往无法彻底隐藏。
5. 仅以“升级感觉有风险”为由选择变通方案，却不实际阅读 Changelog 中有关破坏性变更的说明——升级的风险通常低于维护变通方案的成本。

升级工程规范

决定升级后，请安全地执行。之所以需要这些检查，是因为每一项都对应着实践中出现过的真实故障：

• 包管理器一致性：使用项目实际采用的包管理器——根据被纳入跟踪的锁文件确定（git ls-files package-lock.json yarn.lock pnpm-lock.yaml），而非系统级的 packageManager 字段。系统可能强制使用 pnpm，而项目实际使用 npm；混用会导致锁文件污染和重复的包版本。不要混用。
• 升级后验证流程：typecheck + build + 完整的单元测试套件 + 在真实设备／目标环境中验证。依赖项升级虽通过了类型检查，却导致在目标设备上运行时出错，就不算完成。
• semver 风险评估：对于遵循 semver 的库，同一 major 版本内的 patch/minor 升级风险较低（请确认该库确实遵循 semver——大多数库遵循，但也有一些不遵循）。升级 major 版本需要阅读破坏性变更清单并逐项评估。
• 去重检查：升级后，运行 npm ls <pkg>（或该项目包管理器的等效命令），确认解析出的版本只有一个。多个版本共存（例如，旧的 1.5.0 实体与新的 1.5.2 并存）会导致类型不兼容和难以追溯到此次升级的诡异故障。

结果表

结论	操作
✅ 上游已修复，升级风险较低	将升级依赖作为首选方案。进入方案探索阶段，并将升级作为推荐选项。
⚠️ 升级存在风险（大版本升级／不兼容变更）	在方案探索阶段并列呈现升级和变通方案；根据风险权衡做出决定。
❌ 上游尚未修复，或无法升级（版本锁定／存在不兼容变更）	退而采用变通方案——但要注明这是临时方案、其触发条件，以及它跟踪的上游问题。

与其他技能的关系

技能	关系
PDCA hosts	由 PDCA hosts 在 technical-analysis 阶段引用（与“整个行业都没有可行解决方案”分支相对应的乐观方案）。通过 host 调用时，从 4 步决策顺序开始，并使用 host 已确定的根因。对于这一流程，host 是 SoT。
effective-web-research	第 2 步（检查 Changelog）可借鉴此技能的研究规范——优先查阅官方来源（库自己的 changelog 网站）、检查时效性，并交叉验证重要主张。
runtime-evidence-debug	如果检查 Changelog 后仍不能确定根因，此技能的备用方案（通过网络研究查找已知的平台／框架问题）与此处的第 2 步有所重叠。此技能负责决定修复策略；runtime-evidence-debug 负责收集证据的方法。

特定领域知识的边界

此技能仅包含通用方法。库特定知识——例如某个编辑器框架的哪些版本修复了哪些组合问题，或某个 UI 库特定版本的渲染怪异之处——应放在各项目自己的文档中（其 AGENTS.md 或修复日志），而不是此技能中。原因是：库特定的 changelog 关键词和版本号会过时，且只与使用该库的项目相关；将它们塞进通用技能会增加维护负担，并导致主题偏移。

应用此技能时，如果项目文档中包含相关依赖的库特定 changelog 关键词，请参考这些关键词来确定搜索词——此技能告诉你要检查 changelog；项目文档告诉你要搜索什么。

独立调用

直接调用（而非通过工作流调用）时，从适用场景开始——确认信号符合条件，然后按 4 步决策顺序进行。如果选择升级，输出结果表中的结论，并附上升级工程规范检查清单。