Imported from MistEO/ai-issue-analysis (
.claude/skills/generic-issue-log-analysis/SKILL.md). Install upstream withnpx skills add MistEO/ai-issue-analysis --skill generic-issue-log-analysis. Copyright stays with the author.
Generic Issue Log Analysis
Scope
- 默认把
#1234视为当前仓库 issue。 - 如果用户给了完整 issue URL，则以该 URL 为准。
- 只分析可以直接访问的公开 issue、评论、截图和附件。
- 如果缺少日志、现场图、配置导出或崩溃信息，要先明确说明证据不足，再基于现有材料给出初步判断。
- 如果问题依赖私有环境、外部服务或用户本地状态，而仓库内证据不足，要明确列出还缺哪些材料。
Workflow
-
规范化输入。
#1234视为当前仓库 issue。- 完整 issue URL 以 URL 为准。
- 如果用户给的是模糊描述，先在 issue 文本里定位编号、链接或关键上下文。
-
获取 issue 内容。
- 读取正文和评论。
- 提取这些信息：版本、分支、平台、环境、任务或入口、预期行为、实际行为、复现步骤、维护者评论、附件链接。
- 如果维护者、机器人或其他评论已经给出结论，不要直接照抄；仍要用日志、代码和文档自行验证。
-
提取附件和现场证据。
- 优先关注日志包、截图、配置导出、崩溃转储、诊断报告和资源导出。
- 不要假定附件命名固定；除了项目约定命名，也要留意
log、report、debug、crash、dump、config、trace、screenshot等常见关键词。 - 如果同一个 issue 有多份日志，先看最新一次复现；如果 issue 在对比不同版本、不同环境或不同控制器，再补看旧样本。
-
下载并解压附件。
- 二进制附件不要只靠网页抓取工具直接分析，应先下载到工作区临时目录，例如
.cache/issue-logs/issue-<number>/。 - 解压后先列目录，不要假定内部结构固定。
- 只读取和结论直接相关的文件，不要把整份大日志、整份配置或整个转储内容直接塞进回复。
- 二进制附件不要只靠网页抓取工具直接分析，应先下载到工作区临时目录，例如
-
建立时间线。
- 先从 issue 文本确定“用户认为出问题的时刻”和复现条件。
- 再把界面日志、服务日志、运行时日志、截图、配置快照和崩溃信息串成一条时间线。
- 优先锁定这次复现对应的
task_id、session_id、请求 ID、时间戳或其他稳定标识，再追踪细节。
-
回溯到代码和文档。
- 先看本仓库文档、配置定义和实现代码。
- 如果问题明显落在上游依赖、共享组件、绑定层或外部工具，再按需查看相关仓库或文档。
- 只看真正相关的模块，不要为了“完整”而把整个依赖栈都扫一遍。
-
区分 issue 当时环境和当前分支。
- 先以 issue 文本、附件、配置快照和缓存资源还原用户当时的实际环境。
- 再对照当前仓库代码，判断问题是当前仍存在，还是当时存在但现在可能已修复。
- 如果 issue 很旧，或日志流程与当前主线明显不一致，必要时按对应 tag、release 或历史提交复核旧逻辑。
- 输出给用户时，如果提到任务名、入口名、设置项、按钮名、错误提示或日志前缀，先在仓库里搜索翻译 / 本地化文件，不要直接把
t("...")、i18n.t("...")、LocalizationHelper.GetString("...")、DynamicResourcekey、枚举名或内部 ID 当成最终展示文本。
-
输出结论。
- 明确区分“已证实的根因”“高概率怀疑点”“证据不足的待确认项”。
- 给出能执行的下一步，例如修复方向、需要补充的材料、临时绕过方案、是否建议升级或回滚。
Artifact Map
Runtime / Core Logs
- 模块归属：核心运行时、执行引擎、任务调度层。
- 最适合看：
- 实际执行路径
- 识别、调用、动作失败
- 超时、重试、异常栈
- 对任务行为和底层错误通常最权威。
UI / Frontend Logs
- 模块归属：GUI、前端或用户交互层。
- 最适合看：
- 用户到底点了什么
- 参数是否真的提交
- 用户可见报错和时间线入口
Service / Bridge / Agent Logs
- 模块归属：后台服务、桥接层、agent、进程编排或 IPC 层。
- 最适合看：
- 服务启动失败
- 子进程异常
- IPC、HTTP、RPC、FFI、资源加载或实例生命周期错误
Config Snapshots
- 模块归属：配置快照、导出配置、任务参数、缓存配置。
- 最适合看：
- 实际启用了哪些选项
- issue 文字里说的配置是否真和日志一致
- 当前行为是配置问题还是实现问题
Screenshots / On-Error Artifacts
- 模块归属：出错现场图、保存的识别图、界面截图。
- 最适合看：
- 当时停留画面
- 是否被弹窗、遮罩、加载态、分辨率、缩放、主题或权限影响
- 日志和用户描述冲突时，画面证据是否支持其中一方
Dumps / Crash Reports
- 模块归属：崩溃现场、转储、调用栈、诊断报告。
- 最适合看：
- 闪退、崩溃、进程退出
- 是否需要进一步用符号表、调试器或上游信息分析
Exported Resources / Cached Definitions
- 模块归属：缓存资源、导出的任务定义、运行时生成的元数据。
- 最适合看：
- issue 当时到底使用了哪一版资源或配置定义
- 当前主线和用户当时环境是否不一致
How To Filter Evidence
-
先从 issue 文本拿到这些锚点：
- 版本、分支、提交、发布日期
- 平台、设备、环境、控制方式
- 任务名、入口名、操作路径
- 用户说“出问题”的具体时间、阶段或界面
-
再从日志里找高价值信号：
Error、Warn、Fataltimeout、retryfailed、exceptiontask_id、session_id、请求 ID- 保存截图、导出现场、崩溃恢复、资源加载失败
-
先锁定“这一次复现”再下钻。
- 一个日志包里通常会混有很多历史运行。
- 如果 issue 文本说失败，但对应这次复现的任务最终成功，要明确写出“本次日志未复现用户描述的问题”。
-
区分表象和根因。
- 高层日志、UI 提示或机器人评论经常只是表象。
- 如果更靠近执行层的日志已经给出更直接的错误链路，应优先以那层为准，再回头解释用户看到的现象。
-
回答时只保留关键片段。
- 只摘足够支撑结论的少量证据。
- 不要把整份日志、整段 issue 讨论或整份配置直接倾倒进回复。
Common Patterns
-
维护者评论已经给出判断，但日志和代码证据并不支持：
- 以可验证证据为准，把维护者评论当成补强而不是唯一依据。
-
issue 文本说“失败 / 卡死 / 误点”，但对应复现日志最终成功：
- 先明确“本次日志没有复现出用户描述的问题”。
- 再区分是用户补错了日志，还是代码里确实存在脆弱点但这次没触发。
-
用户日志里的流程与当前主线代码明显不一致：
- 先确认 issue 当时的版本、tag 或 release。
- 不要用当前主线直接否定旧版本问题。
-
配置快照和实际运行日志不一致：
- 不要立刻认定是用户表述错误。
- 先确认配置是否在复现后又被修改、是否有多个配置文件、是否存在缓存或导出时机差异。
-
日志显示现场图、诊断包或转储已保存，但附件里没有对应文件：
- 把“缺失的关键证据”单独写出来。
- 不要假装已经验证过那部分现场。
-
多层架构项目里某一层日志只暴露表象：
- 先在最接近问题根因的那层日志定性，再回到上层解释用户看到的现象。
-
证据更接近“场景不支持”而不是“实现缺陷”：
- 必须给出代码、配置白名单、文档限制或运行时分支依据，而不是只给主观判断。
Correlating With Code
- 先看 issue 模板、README、开发文档、排障文档。
- 再看任务入口、配置定义、流水线或调度定义。
- 然后看运行时、服务层、桥接层、前端或 GUI 实现。
- 只有当证据已经明显指向上游依赖时，才继续看外部仓库、SDK、框架或绑定层。
Localized Copy
- 总结任务、入口、设置项、按钮、错误提示、日志前缀等用户可见文案时，先在仓库里主动搜索翻译 / 本地化文件。
- 优先搜索这些常见目录、文件名和关键词：
locale、locales、i18n、lang、langs、translations、messageszh-cn、zh_cn、zh-hans、zhHans、zh*.json、*.yaml、*.yml、*.toml、*.resx、*.xaml、*.ts、*.js
- 再从实际代码调用反查 key：
t("...")、i18n.t("...")、intl.formatMessage(...)LocalizationHelper.GetString("...")、GetString("...")DynamicResource SomeKey、StaticResource SomeKey- 其他项目自定义的资源读取函数
- 查找顺序建议：
- 先从报错日志、配置字段、界面代码里提取疑似 key / id / 枚举名
- 再在本地化文件中找对应中文文案
- 如果同时存在多语言，优先使用简体中文；若没有简体中文，则退回 issue 正文更接近的语言或仓库主语言，并说明未找到中文文案
- 如果配置或日志里带有用户自定义名称，输出时优先保留用户自定义名称；必要时再括号补默认任务 / 入口文案或原始 key。
- 如果仓库里确实找不到翻译 / 本地化文件，要明确说明“未发现可用的翻译文件 / 本地化资源”，再退回原始 key、英文字符串或内部 ID。
Linking Code Evidence
- 如果要指向具体代码行，不要写本地路径加行号，也不要写绝对路径。
- 统一给出对应仓库的远端 GitHub
blob行号链接，用尖括号包裹。 - 链接格式：
https://github.com/<owner>/<repo>/blob/<commit>/<path>#L14-L20
<owner>/<repo>应使用本次实际分析的代码仓库；如果引用的是上游依赖或外部仓库，就用那个仓库自己的链接。<commit>必须是本次分析实际依据的代码版本：- 默认使用当前检出的
HEAD - 如果为了复核旧 issue 切到了某个 tag / commit，就使用那个版本解析后的 SHA
- 默认使用当前检出的
- 如果引用的是文档、配置样例或资源定义，也尽量给对应远端链接，而不是本地路径。
Output Format
最终回答用这个结构：
## Issue 概要
- issue：`#1234`
- 版本 / 分支 / 环境：
- 任务 / 入口 / 相关设置：优先写翻译文件里的用户可见文案；必要时再补 key / id / 枚举名
- 关键提示 / 报错文案：优先写翻译文件中的实际显示文本
- 用户现象：
## 附件概览
- 实际可读文件：
- 缺失或未上传的证据：
## 关键证据
<details><summary>点击此处展开</summary>
- issue 正文 / 评论：
- 运行时日志：
- UI / 服务日志：
- 配置快照：
- 现场图 / 转储：
- 代码依据：如需指向具体实现，直接附远端 GitHub 行号链接
</details>
## 根因判断
- 直接结论：
- 证据链：
- 当前主线是否可能已修复：
## 修复方案
1. 代码 / 配置 / 资源层修复
2. 需要补充的测试、日志或截图
3. 如问题属于不支持场景，应如何限制入口或改进提示
## 给用户的建议
- 用户现在可以直接尝试的动作：
- 是否建议升级 / 重下完整包 / 重置配置 / 更换环境：
- 是否有临时绕过方案：
## 给修复 AI 的建议（可复制）
<details><summary>点击此处展开</summary>
~~~text
现象：
[一句话描述用户可见的问题]
关键证据：
[粘贴原始日志、堆栈、监控截图中的关键文本]
可能相关线索（待验证）：
[根据日志/现象推测的可能方向，不保证准确，供参考]
~~~
</details>
## 置信度
- 高 / 中 / 低
- 还缺什么证据Reminders
- 不要只看一个日志文件下结论。
- 不要把 issue 评论、机器人提示或维护者判断当成唯一证据。
- 不要把当前分支代码直接当成 issue 当时的真实环境。
- 日志和截图冲突时，优先解释冲突，再决定更可信的证据链。
- 如果问题本身没有在当前日志中复现，要明确写“证据未复现”，不要硬凑结论。
- 如果 issue 版本较旧，要明确区分“当时的根因”和“当前主线是否已修复”。
- 如果回答里出现任务名、入口名、设置项、按钮名、提示文案，优先先搜索项目里的翻译 / 本地化文件，再使用实际用户可见文案；必要时才补原始 key / id。
- 如果回答里引用了具体代码行，直接给远端 GitHub
blob行号链接，用尖括号包裹，不要给本地路径加行号。 - 如果证据表明问题已在新版本修复，明确建议升级；如果怀疑安装包、资源文件或配置损坏，明确建议重建；如果判断为真实代码缺陷且暂无 workaround，明确建议等待修复。