structured-analyze

name	structured-analyze
description	系统性技术问题诊断框架。通过"边界收敛→分支诊断→假设验证→证据链→方案决策"五步法，将试错式排查变为结构化分析。当用户说"分析这个问题"、"报错了帮我看看"、"定位一下根因"、"帮我分析一下这个现象"、"这个Bug怎么查"、"内存泄漏/崩溃/性能退化/死锁怎么定位"、或描述了任何软件异常现象时触发。不用于产品需求分析或日常决策（那是 structured-thinking 的范畴）。

问题诊断分析 — 结构化诊断框架

定位

structured-thinking 解决决策类问题（做什么、值不值得做），本 skill 解决诊断类问题（哪里出了问题、怎么最快修）。

核心思路：不是拿到问题就开始翻代码或抓 dump，而是先分边界，再定策略，再并行验证。把试错循环变成收敛过程。

三个关键规则

1. 先分边界，再查代码 — 问题可能根本不在算法里，输入/软件/硬件都可能是原因。确定归属后再深入，不浪费时间看无关代码。
2. 假设并行验证 — 互不依赖的假设同时执行，不串行试错。
3. 日志不足时，精确建议收集方向 — 不说"需要更多日志"，说"需要在 X 时刻抓 Y 日志，关键字段是 Z"。

辅助工具：需要深入分析日志时可用 log-analyze skill，但本框架不强制依赖它。

四层边界

输入侧 — 参数值/操作序列/输入数据本身是否合理？
软件侧 — 参数的流转路径是否正常？（加载→传递→生效→存储）
算法侧 — 在给定参数下，算法内部计算是否符合预期？
硬件侧 — 物理设备/环境是否正常？

判定优先级：输入 > 软件 > 算法 > 硬件。输入问题最常见也最快确认，硬件问题最耗时。

---

工作流程

阶段零 边界收敛（迭代式）

这是最关键的阶段。一个常见陷阱是：拿到问题直接翻代码。正确做法是先用现有证据判定归属。

Step 0: 确认已有证据（必须先执行）

分析前必须确认用户手头有什么。不要假设有日志。

逐项询问：

- 有问题描述吗？（现象、时间、频率、操作步骤）
- 有软件日志吗？（应用运行日志、配置日志、错误日志、操作审计日志）
- 有算法日志吗？（匹配过程、评分、中间状态、候选输出）
- 有其他可用数据吗？（截图、现场照片、dump、硬件SDK日志、性能监视器）

然后标注每层判定受限于什么：

有完整日志	该层判定置信度高
只有问题描述	该层可以基于现象推理，但置信度低
什么都没有	所有分析基于现象推理，标注置信度低，同时输出"需要收集的最小证据集"

一个例子：如果用户只描述了现象但无日志，那你仍然可以做推理（像 RMS case 里基于因果关系推断输入侧问题），但必须标注"置信度：中，待日志验证"。

第1轮：逐层判定

按输入→软件→算法→硬件的优先级逐层检查：

┌─ 输入侧检查 ─────────────────────────────────────────────────┐
│                                                              │
│  关键词：参数值、配置项、操作序列、输入数据                    │
│                                                              │
│  查什么：                                                     │
│    - 被修改的参数/配置值本身是否合理？                          │
│    - 操作序列是什么？谁在什么时候做了什么？                     │
│    - 输入数据本身是否合法？（格式、范围、编码）                │
│                                                              │
│  判定信号：                                                   │
│    - 参数值不合理（min > 正常值 → 排除正确结果）                │
│    - 操作序列有误（改了值但语义理解错了）                      │
│    - 输入数据异常（格式错误、超范围）                          │
│                                                              │
│  → 命中任一 → 归属"输入侧"，跳至阶段一输入分支                 │
└──────────────────────────────────────────────────────────────┘

┌─ 软件侧检查 ─────────────────────────────────────────────────┐
│                                                              │
│  关键词：参数传递、配置加载、状态机、生效规则                  │
│                                                              │
│  查什么：                                                     │
│    - 参数从输入到使用的完整链路：UI → 存储 → 加载 → 算法       │
│    - 配置变更后是否立即生效？是否需重启？                      │
│    - 多个配置源之间是否一致？（UI/配置文件/数据库）            │
│    - 状态机是否在合法状态下接收了参数变更？                    │
│    - 软件日志中的错误/告警/异常状态                            │
│                                                              │
│  判定信号：                                                   │
│    - 配置加载失败或加载了错误的值                               │
│    - 配置变更未生效（依赖重启但未重启）                        │
│    - 多配置源不一致（UI 显示值 ≠ 算法使用值）                   │
│    - 状态机处于异常状态导致参数处理错误                         │
│                                                              │
│  → 命中任一 → 归属"软件侧"，跳至阶段一软件分支                 │
└──────────────────────────────────────────────────────────────┘

┌─ 算法侧检查 ─────────────────────────────────────────────────┐
│                                                              │
│  关键词：匹配评分、中间结果、错误码                            │
│                                                              │
│  查什么：                                                     │
│    - 算法日志中的候选评分/迭代次数/中间状态                    │
│    - 给定输入（含参数约束），输出是否符合算法设计预期？         │
│    - 是否有错误码或异常状态？                                  │
│                                                              │
│  判定信号：                                                   │
│    - 给定合理输入和正确参数，算法输出错误                       │
│    - 边界条件未处理（空输入、极值、重复执行）                   │
│    - 算法输出了错误码或异常状态                                │
│                                                              │
│  → 命中任一 → 归属"算法侧"，跳至阶段一算法分支                 │
└──────────────────────────────────────────────────────────────┘

┌─ 硬件侧检查 ─────────────────────────────────────────────────┐
│                                                              │
│  关键词：相机状态、通信链路、信号时序、驱动版本                │
│                                                              │
│  查什么：                                                     │
│    - SDK日志中的设备状态/错误码/心跳                           │
│    - 系统事件日志（设备断开、驱动错误）                        │
│    - 已知的驱动/固件兼容性问题                                 │
│                                                              │
│  判定信号：                                                   │
│    - SDK报告设备异常或断开                                    │
│    - 通信超时/丢包                                            │
│    - 信号时序异常                                             │
│                                                              │
│  → 命中任一 → 归属"硬件侧"，跳至阶段一硬件分支                 │
└──────────────────────────────────────────────────────────────┘

第 1 轮判定结果

• 能判定归属 → 进入对应分支诊断（阶段一）
• 不能判定 → 输出"进一步收集建议"，明确告诉用户需要补什么证据。例如：
  • 怀疑输入侧 → "需要抓取 X 时刻的配置变更日志，确认 RMS 范围参数是否被修改"
  • 怀疑软件侧 → "需要确认参数从 UI 到算法的完整流转路径，检查是否有多配置源不一致"
  • 怀疑算法侧 → "需要开启 debug 级别日志，重放同一板件，对比正常/异常的候选评分"
  • 怀疑硬件侧 → "需要现场抓取相机 SDK 日志，确认图像采集链路状态"

第2轮及以后

用户补充新证据后，重新执行判定。边界越来越清晰，直到锁定归属。

输出格式

## 阶段零：边界收敛

### Step 0: 已有证据确认
- 问题描述：[有/无] — [概括]
- 软件日志：[有/无] — [概括]
- 算法日志：[有/无] — [概括]
- 其他数据：[有/无] — [概括]
- 数据限制：[哪些层的判定因缺数据置信度降低]

### 逐层判定
- 输入侧：[通过/可疑/排除] — [理由] — 置信度: [高/中/低]
- 软件侧：[通过/可疑/排除] — [理由] — 置信度: [高/中/低]
- 算法侧：[通过/可疑/排除] — [理由] — 置信度: [高/中/低]
- 硬件侧：[通过/可疑/排除] — [理由] — 置信度: [高/中/低]

### 结论
- 问题归属：[输入/软件/算法/硬件/待定]
- 置信度：[高/中/低]

### 进一步收集建议（如果待定）
- [精确的日志/数据收集建议，含时间点、关键字段]

---

阶段一 分支诊断

根据阶段零的归属，进入对应分支。四个分支的诊断策略完全不同。

输入分支

目标：确认是操作失误、配置缺陷还是输入数据本身有问题。

诊断路径：

1. 参数传递链路追踪
   → 输入端 → 存储位置 → 读取时机 → 使用位置
   → 关键词：config/param/setting/limit/threshold

2. 变更时间线重建
   → 从日志时间点倒推：谁在什么时刻改了什么值
   → 对比修改前后的运行结果

3. 默认值与生效规则
   → 未配置时使用什么默认值？默认值是否合理？
   → 配置变更后是否立即生效？是否需重启？

4. 多配置源一致性
   → 同一个参数是否有多个配置入口（UI/配置文件/数据库/命令行）？
   → 不同入口的值是否一致？哪个优先级最高？

输出: 非Bug（操作/配置问题）或 输入校验缺陷

软件分支

目标：确认参数的完整流转路径是否正常。即使输入值本身是合理的，软件在加载/传递/生效过程中也可能出问题。

诊断路径：

1. 参数传递链路追踪
   → 输入端(UI/配置文件/数据库) → 存储位置 → 读取时机 → 使用位置(算法入口)
   → 关键词：config/param/setting/limit/threshold

2. 变更生效规则
   → 配置变更后是否立即生效？是否需重启或触发重载？
   → 如果需重启，操作员是否知晓？

3. 多配置源一致性
   → 同一个参数是否有多个配置入口（UI/配置文件/数据库/命令行）？
   → 不同入口的值是否一致？哪个优先级最高？
   → 操作员在UI上改的值和算法实际读到的值是否相同？

4. 状态机上下文
   → 参数变更时系统是否在合法状态？
   → 是否在运行中/暂停/停止等状态下有不同的参数处理逻辑？

5. 默认值与回退逻辑
   → 未配置时使用什么默认值？默认值是否合理？
   → 非法值时是否回退到默认？回退逻辑是否被正确触发？

输出: 配置加载缺陷 / 参数传递断裂 / 多源不一致 / 生效时序问题

算法分支

目标：定位到具体的算法步骤、状态或逻辑。

诊断路径：

1. 日志对比（最快）
   → 同一输入，正常场景 vs 异常场景的算法日志对比
   → 找到第一个分叉点：在哪里输出开始不同？

2. 中间状态检查
   → 算法各阶段的中间结果是否在预期范围？
   → 状态机是否在合法状态？

3. 版本影响评估
   → 最近有算法变更吗？diff 了什么？
   → 回退到旧版本能否复现？

4. 边界条件覆盖
   → 空输入、极端值、重复执行 → 是否触发未知路径？

5. 控制变量（兜底）
   → 只改一个参数/输入，其余不变，观察输出
   → 二分法缩小可疑代码范围

输出: 逻辑Bug / 边界条件缺陷 / 异常路径未处理 / 版本引入

硬件分支

目标：确认是硬件故障，还是驱动/环境问题。

诊断路径：

1. SDK/驱动日志
   → 设备状态码、错误计数、心跳中断时间点
   → 重连次数、超时频率

2. 系统事件日志（evtx / dmesg / syslog）
   → 设备断开/重连事件
   → 驱动加载失败/崩溃事件

3. 环境交叉对比
   → 同一硬件在不同机器/不同版本的同一软件上的表现
   → 同型号其他设备是否有相同现象？

4. 性能监视器（blg / perf）
   → CPU/内存/磁盘/网络趋势
   → 资源耗尽时间和问题出现时间的对齐

5. 现场环境检查
   → 线缆、电源、交换机端口统计
   → 温度、振动、EMC干扰

输出: 硬件故障 / 驱动兼容性 / 环境干扰 / 间歇性连接

输出格式

## 阶段一：分支诊断 — [输入/软件/算法/硬件]

### 诊断路径
[根据具体情况选择1-N个路径]

### 发现
- [证据1]：来源 + 说明
- [证据2]：来源 + 说明

### 判定
- 类型：[操作问题 / 配置缺陷 / 参数传递断裂 / 算法Bug / 边界条件 / 硬件故障 / ...]
- 置信度：[高/中/低]
- 是否终止（非Bug）：[是/否]

---

阶段二 假设驱动验证

当阶段一无法直接锁定根因时，进入假设驱动验证。分两步：先发散（列出所有可能根因，不急于收敛）→ 后验证（并行排查、逐个排除）。

核心原则：互不依赖的假设并行验证，不串行试错。

第一步：发散 — 生成假设池

在列出假设之前，先用几个角度做脑力激荡，确保不遗漏。不要在这一阶段就自我审查——"不太可能"的想法也先列进来。

从以下角度逐一扫一遍，遇到可能相关的就生成一个假设：

• 常规原因 — 阶段一指向的最可能方向的直接推导。最容易被首先想到，也是最该最先验证的。但验证完后，如果排除了，不要在此打住。
• 历史类比 — 这个问题/类似问题以前出现过吗？上次根因是什么？当时的修复是否完整？本次现象是否和上次完全相同？
• 时序相关 — 问题是否有时序特征？（改了参数后立刻触发 vs 等了几秒、连续运行几天后才出现、只在启动/退出时出现）→ 时序可能暗示资源累积、竞态、预热等方面的原因。
• 多因素交互 — 是不是两个条件同时满足才触发？（改参数 + 特定板件、改参数 + 特定流程步骤、特定相机 + 特定光照）→ 单看每个条件都不足以触发
• 隐藏假设 — 分析过程中默认假设了什么？这些假设一定成立吗？（"参数修改后立即生效"、"算法读到的值和 UI 显示的相同"、"同一型号的所有设备行为一致"）
• 最近变更 — 版本、配置、驱动、环境最近改了什么？变更是什么时候的？和问题出现时间是否对齐？

实践提示：发散阶段不要急于评判假设的合理性。列出所有候选后，再按可能性排序。一个不成立 → 立即检验下一个。

第二步：假设卡片

将发散阶段产生的每个可能根因具象化为可验证的假设卡片：

## 假设1: [简短描述]

- **可能性**: [高/中/低] — [依据]
- **排除条件**: [什么证据可以证明此假设不成立]
- **验证实验**: [最小验证动作 — 可以是一次日志查询、一次重放测试、一次参数修改]
- **互不依赖**: [是/否] — [与哪些假设互斥]

第三步：并行执行

• 互不依赖的假设 → 同时验证，不分先后
• 互斥的假设（A 成立 B 就不成立）→ 先验证置信度高的

第四步：逐个排除

每个验证实验完成后：

• 假设成立 → 标记"存活"
• 假设不成立 → 记录排除原因

输出格式

## 阶段二：假设验证

### 发散脑力激荡
[从常规原因/历史类比/时序/多因素/隐藏假设/最近变更角度，列出所有可能根因]

### 假设池
假设1: [描述] — 可能性: [高/中/低]
假设2: [描述] — 可能性: [高/中/低]
...

### 验证结果
- 假设1: [存活/排除] — [证据]
- 假设2: [排除] — [证据]
...

### 存活假设
[未排除的假设列表，按置信度排序]

---

阶段三 证据链收敛

汇总所有证据，锁定单一根因。

验证结果汇总
    ↓
排除不成立的假设（记录排除原因）
    ↓
存活假设排序（置信度从高到低）
    ↓
单一根因被证据链锁定？
    ├── 是 → 输出根因
    └── 否 → 标注"待补充证据"
              → 建议下一轮要收集什么
              → 退回阶段零

输出格式

## 阶段三：证据链收敛

### 根因
[一句话描述根本原因]

### 证据链
1. [证据1] — 来源: [日志文件:行号/时间戳/工具输出]
2. [证据2] — 来源: [...]
3. [证据3] — 来源: [...]

### 已排除假设
- 假设X: 排除原因 — [证据]

### 待补充（如果无法锁定）
- [需要进一步收集的证据]

---

阶段四 方案决策

根因锁定后，梳理修复方案池。同时回答两个问题：

1. 怎么修？
2. 后续生产是否还会出现？如何预防？

修复方案池 → 风险/工作量/效果评分 → 推荐路径 → 第一步动作

每个方案评估维度：
- 风险: 引入新问题的概率（低/中/高）
- 工作量: 人天估算
- 效果: 根除(解决所有场景) / 规避(解决当前场景) / 减轻(降低概率)
- 验证: 如何确认修复有效

输出格式

## 阶段四：方案决策

| 方案 | 描述 | 风险 | 工作量 | 效果 | 验证方式 |
|------|------|------|--------|------|----------|
| A | ... | 低 | 0.5天 | — | ... |
| B | ... | 中 | 2天 | — | ... |

### 推荐
- **立即**: [方案A]
- **后续**: [方案B/C]
- **预防**: [防止类似问题再出现的措施]

### 第一步
[今天/本周立即可以执行的最小动作]

---

阶段五 归档（可选）

仅在用户明确说"总结"、"归档"、"沉淀"、"写报告"时触发。报告模板：

【问题名称】：...
【问题表象】：...
【原因解析】：...
【影响范围】：...
【修改方式】：...
【排查过程】：...（按时间或逻辑顺序，引用实际日志/证据）
【经验总结】：...

---

输出要求

• 语言：中文
• 风格：每条结论都锚定到具体证据
• 置信度必须标注，无证据时写"待验证"
• 阶段零是必须通过的关卡，不可绕过
• 非Bug问题在阶段一即可终止，不必走完全部阶段
• 不要在阶段零未完成时就开始查代码或抓dump