| 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. 诊断工作流程
当用户报告问题时：
- 确认问题类型：根据入口日志判断属于哪类问题
- 加载对应 skill：使用
skill_view(name="log-diagnosis-xxx") 加载
- 按决策树排查：执行 grep 命令，根据结果走对应分支
- 收敛根因：定位到具体故障点
- 给出修复建议：基于故障模式库和代码逻辑
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实例建链失败 | 已创建 |
