known-issue-research

已知问题研究

用于代码修复工作流技术分析阶段的内部共享技能。用于判断已确认的问题何时需要在深入代码级分析之前（或取代深入代码级分析）进行外部网络研究，以及如何处理研究结果。

前置条件检查：此技能在 frontmatter dependencies 中声明了 effective-web-research。加载时，请确认其可用；若缺失，则中止并打印安装命令（npx skills add FuDesign2008/open-skills -g）。不得静默回退。

步骤编号参数化

此技能由步骤编号不同的工作流共享。以下所有跳转目标均写为占位符——{impact-assessment step}、{root-cause step}、{upstream-eval step}——引用该技能的工作流会在引用行内注明自己的步骤编号（例如“跳转到步骤 4”）。此处不得硬编码工作流的步骤编号。

1. 研究路由分诊

确认问题存在后立即执行。判断根因最可能属于哪一类——这会调整后续步骤的优先级，但不会取代这些步骤：

路由	信号	重点
🟢 内部优先	与“我们的代码／逻辑／约定”有关；怀疑根因位于此仓库	优先查找代码位置；快速搜索（§2）可作为备选；根因分析是核心
🔵 外部优先	指明第三方库／框架／API 及版本；或询问“如何使用／为什么／是否有已知问题”；或命中任一 §2 触发条件（平台静默失败／嵌套宿主／没有代码级疑点）	快速搜索（§2）成为首要操作——先搜索已知案例
🟣 混合（先外部后内部）	外部概念 + 内部对象（“我们使用的 X 库是否存在漏洞 Y”、“将模式 X 应用于我们的代码”）	先通过 §2 从外部了解该概念，再进行内部根因分析并将其应用于代码

不确定时，默认选择🟢 内部优先（这些工作流旨在修改代码；大多数根因都在仓库中）。

与 effective-web-research 的步骤 0 的关系：该分诊决定一次搜索是否应转向外部；此处则决定整个问题的研究构成。两者互为补充——不确定时，请参考该技能的步骤 0。

2. 已知问题快速搜索

触发条件（满足任一条件即可；在 🔵／🟣 路由中，这是首要操作；在 🟢 路由中，则是在为代码添加检测手段之前可选的回退操作）：

• 涉及平台／原生组件（Android WebView、iOS UIPickerView、浏览器 API、操作系统级控件……），且出现静默失败——没有错误、没有崩溃、调用正确，但行为完全无响应。
• 使用嵌套宿主运行时（React Native、Electron、Cordova、WebView-in-App……），而前端逻辑看起来完全正确。
• 没有代码级疑点：调用链完整、参数正确、日志显示已执行，但运行时仍无法工作。

执行：使用“症状关键词 + 平台／框架 + 年份”进行 WebSearch，并搜索 StackOverflow、GitHub Issues 和官方文档。并行操作（涉及已指明的第三方库／框架，或症状与平台特定行为高度相关时必须执行）：检查上游依赖的 Changelog／Release Notes／Issues，确认是否已有修复版本——升级可能是最简单的修复方式（交由工作流的 {upstream-eval step} 处理，该步骤会委派给 upstream-dependency-debug）。

结果处理：

结果	操作
✅ 找到已知案例，根因明确	输出快速搜索结论；跳转到 {impact-assessment step}，跳过根因分析
✅ 找到上游修复版本	输出线索；继续到 {upstream-eval step} 评估升级可行性（上游已有修复的线索尚不等于解决方案）
⚠️ 找到相关讨论，根因部分明确	将发现作为参考，提供给 {root-cause step}
❌ 未找到任何结果	静默跳过；继续到 {root-cause step}

2.1 性能模式变体（适用于 perf-optimize-workflow）

当所引用的工作流用于性能分析（perf-optimize-workflow）时，将 §2 视为已知性能模式快速搜索，并在进入该工作流的假设阶段之前，额外检查以下触发条件（满足任意一项即可）：

• 已定位异常，但无法归类到该工作流的已知性能模式表中
• 怀疑存在框架／库的性能缺陷或限制（明确指出框架及版本）

执行：按照 §2 中相同的 WebSearch 规则进行搜索，查询格式为：症状 + 框架/库 + 版本 + 年份，优先查看 GitHub Issues、官方变更日志和 StackOverflow。

结果	操作
✅ 已知案例／版本缺陷	将已知修复列为候选解决方案；后续假设验证重点围绕该方向展开
⚠️ 相关讨论，结论不明确	将结果纳入假设方向
❌ 未找到结果	跳过，不作说明；继续工作流的下一阶段

perf-optimize-workflow 保留其模式表和阶段编排；本小节仅负责搜索方法。

3. 行业普遍问题评估

触发条件（可选的悲观分支）：根因明显指向平台／语言／协议／标准的硬性限制（例如浏览器安全策略、JS 单线程、协议约束），且没有明显的应用层变通方案。

执行：使用 WebSearch 搜索：这是否是公认的行业普遍问题？主流框架／大型公司如何处理？是否存在可行的变通方案？

结果处理：

结果	操作
🚫 公认的硬性问题，且无可行解决方案	输出评估报告（模板见 reference.md），并暂停，等待用户决定（探索变通方案／接受现状）
⚠️ 存在限制，但有变通方案	将变通方案列为解决方案探索中的候选项；继续
✅ 并非行业普遍问题，且可以修复	继续执行 {impact-assessment step}

与 §2 的区别：§2 在确定根因之前按症状搜索已知案例（无论是否存在解决方案都适用）；§3 则在根因明确之后评估行业是否已有公认的解决方案（适用于无解的情形）。两者绝不重叠。

WebSearch 规则

此技能中的所有 WebSearch 操作都遵循 effective-web-research：先执行其第 0 步分流（确认问题需要外部信息，无法从仓库中解决），然后遵循其 4 项准则（优先权威来源／检查时效性／交叉验证重要声明／跳过内容农场）；用户要求严谨性时，切换到其严格模式并生成报告。搜索前先阅读该技能的当前文档，切勿凭记忆操作。

集成指南（供引用工作流使用）

• 在 frontmatter dependencies 中声明此技能；如果缺失，则在启动时中止。
• 引用说明必须指出：上述占位符对应的步骤编号映射，以及 §2／§3 分别对应你的哪些步骤。
• 在你自己的正文中保留语义变体——例如：jira-fix-workflow 中的 §3 是一个关卡（而非可选项），🚫 结果会停止流程并写入 Jira 评论，其报告模板位于自己的 reference.md 中。