log-diagnosis-framework

name	log-diagnosis-framework
description	日志问题定位技能组框架。定义了一组基于日志进行问题定位的 skill 的组织方式、通用结构和命名规范。每个具体问题（如缩P保D、建链失败）有独立的诊断 skill。触发词：日志定位、日志诊断、log diagnosis、问题定位、故障定位。

Log Diagnosis Skills 框架

本框架定义了一组基于日志进行问题定位的 skill 的组织方式和通用结构。每个具体问题类型有独立的诊断 skill，本文件是框架说明，不直接执行诊断。

---

1. 设计思路

log-analyzer-skill 负责从代码仓库提取日志并生成结构化文档（日志表格、流程图、故障模式库），是"整理"能力。 log-diagnosis 系列 skill 负责拿着日志做问题定位，是"诊断"能力。

两者关系：

• log-analyzer 产出是 log-diagnosis 的输入（日志表格、故障模式库是诊断的参考基线）
• log-analyzer 的第八步可以同步生成一个 log-diagnosis skill 的骨架

---

2. Skill 命名规范

命名格式	说明	示例
log-diagnosis-{problem-id}	每个问题类型一个 skill	log-diagnosis-shrink-p-reserve-d
log-diagnosis-framework	本框架文件	-

problem-id 使用小写英文短横线连接，语义化描述问题。

---

3. 每个 Diagnosis Skill 的通用结构

每个 log-diagnosis-{problem-id} 的 SKILL.md 必须包含以下章节：

3.1 YAML Frontmatter

---
name: log-diagnosis-{problem-id}
description: 一句话描述该 skill 解决什么问题。触发词：xxx、yyy。
parent: log-diagnosis-framework
---

3.2 问题描述

• 问题是什么
• 涉及哪些仓库/组件
• 问题的典型表现（用户能看到什么异常）
• 与其他问题的关联（如建链失败可能是缩P保D的下游问题）

3.3 诊断入口日志

列出标志该问题开始的关键日志，格式：

入口日志	组件	含义	grep 命令
日志内容模板	组件名	含义	grep "pattern" /path/to/log

用户遇到问题时，先按入口日志确认问题类型，然后加载对应的 diagnosis skill。

3.4 诊断决策树

基于日志的分支判断，用决策树描述排查路径：

[入口日志]
├── 分支A（条件1）→ 检查项1 → 结论A1 / 继续分支
├── 分支B（条件2）→ 检查项2 → 结论B1 / 继续分支
└── 分支C（条件3）→ 检查项3 → 结论C1 / 继续分支

每个分支的判断依据是实际日志中是否出现某条日志，不是猜测。

3.5 诊断执行流程

按步骤拆分，每个步骤：必须是可执行的检查、有明确的预期结果、异常时有跳转路径。

3.6 诊断输出格式（必须遵循）

每个 skill 诊断完成后，必须按以下格式输出结论：

## [问题类型] 诊断报告

### 诊断结论
**方向**: xxx
**根因**: [一句话描述根因]

### 证据链
| # | 日志位置 | 日志内容 | 推导结论 |
|---|----------|----------|----------|
| 1 | 行xxx | `日志内容` | 从这条日志能推导出的结论 |
| 2 | 行xxx | `日志内容` | ... |
| ... | ... | ... | ... |

### 根因分析
[2-3句话分析：这些证据为什么指向这个根因]

### 下一步行动
| 优先级 | 方向 | 具体操作 | 可信度 |
|--------|------|----------|--------|
| P0 | 验证根因 | [检查命令或配置] | 高/中/低 |
| P1 | 继续排查 | [如果可信度不够，还需要查什么] | 中/低 |

### 修复建议
[如果根因确定，给出具体修复步骤或配置修改建议。如果根因不确定，给出最可能的修复方向。]

关键要求：

• 证据链必须有行号 — 每条证据都要标注在日志中的具体位置
• 可信度必须标注 — 高/中/低，让用户知道结论的可靠程度
• 下一步必须有优先级 — P0 是最需要先做的
• 修复建议要有具体操作 — 不能只说"检查配置"，要给出具体要查什么、怎么改

3.7 快速诊断表

针对最常见的问题，提供"日志现象 → 根因 → 修复"的快速映射：

日志现象	根因	修复方法	优先级
xxx	yyy	zzz	P0/P1/P2

3.7 关联问题

关联问题	关联方向	对应 Skill
问题名	上游/下游/并发	log-diagnosis-xxx

---

4. 诊断工作流程

当用户报告问题时：

1. 确认问题类型：根据入口日志判断属于哪类问题
2. 加载对应 skill：使用 skill_view(name="log-diagnosis-xxx") 加载
3. 按决策树排查：执行 grep 命令，根据结果走对应分支
4. 收敛根因：定位到具体故障点
5. 给出修复建议：基于故障模式库和代码逻辑

---

5. 与 log-analyzer-skill 的关系

维度	log-analyzer	log-diagnosis
目标	整理日志、建基线	定位问题、找根因
输入	代码仓库 + 可选实际日志	实际环境日志 + analyzer 产出的基线
输出	CSV表格 + MD流程图 + 故障模式库	根因定位 + 修复建议
使用时机	功能开发/文档阶段	故障发生/排查阶段
前置依赖	无	log-analyzer 产出（可选但推荐）

log-analyzer-skill 的第八步（生成故障模式库）完成后，可以同步生成一个 log-diagnosis skill 骨架，预填入口日志和诊断决策树。

---

6. 文件组织

所有 log-diagnosis skills 放在 ~/projects/doc/skills/archive/cursor/log-diagnosis-{problem-id}/ 目录下。

每个 skill 目录结构：

log-diagnosis-{problem-id}/
├── SKILL.md                          # 主文件
├── references/
│   ├── diagnosis-tree.md             # 详细诊断决策树（可展开）
│   └── related-fault-modes.csv       # 关联的故障模式库子集
└── scripts/
    └── quick-diagnose.sh             # 一键诊断脚本（可选）

---

7. 现有 Skills 清单

Skill 名称	问题描述	状态
log-diagnosis-shrink-p-reserve-d	缩P保D流程异常	已创建
log-diagnosis-pd-link-establishment	PD实例建链失败	已创建