log-analysis-locate-guide

name	log-analysis-locate-guide
description	从代码仓提取指定特性的关键日志，生成「日志定位指南」Markdown（正文三层快速定位+分阶段+卡点速查，附录含特性链路全量日志表与 Mermaid）。不产出 CSV/9列表格关系图。触发词：整理{特性}日志定位指南、生成{特性}日志定位指南、从代码整理{特性}定位指南。

日志定位指南生成器

从代码仓库提取指定特性的关键日志，生成单一 Markdown 文件《{特性}日志定位指南》。结构以标准范例为准，禁止交付 CSV 或表格版「定位日志关系图」。

文档骨架速记（生成时严格对齐此结构）：

# {特性} — 日志定位指南
> 概述（是什么 / 覆盖范围 / 术语表 / 准备什么）

## 一、快速定位（先看这里）
（4-5 步表格 + 判断口诀 + 极简 flowchart LR）

## 二、分阶段详细定位
### 2.1 阶段 N：...
（子环节表 + → 全量表 [C.x] · 全量图 [D.x]）

## 三、卡点速查（卡在 X → 查 Y）
（8-12 行卡点表 + 排查顺序）

## 四、附录
### A. 涉及仓库与组件
### B. 关键配置
### C. 全量日志逐步明细（特性链路内全量，分 C.1/C.2... 对应 §二大阶段）
### D. 全量流程图（Mermaid）（每大阶段至少 1 张 flowchart，多组件加 sequenceDiagram）
### E. 关键节点索引
### F. 故障场景流程

附录 C/D 必须双向互链；阅读顺序固定为 大框架（§一/§二）→ 全量表（附录 C）→ 全量流程图（附录 D）。

本 skill 为单体流程，不调用 log-analysis-dispatcher / log-analysis-from-code / structurize / document 等子 skill。

---

触发词

• 整理{特性}日志定位指南
• 生成{特性}日志定位指南
• 从代码整理{特性}定位指南

示例：整理大EP启动日志定位指南、整理PD建链日志定位指南

不触发：用户仅问「日志定位指南是什么」「怎么理解定位指南」等概念问题（无「整理/生成」+ 特性名）。

---

输入

输入	必需	说明
代码仓	必需	cmotor / pymotor / mindie-llm / vllm / vllm-ascend 或用户指定
特性描述	必需	自然语言，如「PD 实例建链」「大 EP 场景启动」
代码根目录	必需	仓库绝对路径
输出目录	必需	.md 落盘目录；用户未指定时询问，勿硬编码

---

输出（唯一交付物）

产出	格式	文件名
日志定位指南	Markdown	{特性}日志定位指南.md

禁止交付

• {特性}日志表格.csv 或任意 9 列 CSV
• 正文大段「编号|出现场景|组件|…|代码位置」全量表（全量只允许在附录 C）
• 仅 Mermaid、无 §一 快速定位的「流程图文档」
• 在对话里贴完整文档代替落盘（用户要的是文件）

内部可按阶段整理日志列表，不得 Write CSV 到输出目录。

---

执行流程

第一步：确认输入

1. 代码仓、代码根目录、特性描述（用于标题与阶段命名）
2. 输出目录（绝对路径）
3. 特性边界：起止条件（如「从 main 到 coordinator ready」），不清楚则根据代码入口/出口日志推断并写入概述

第二步：从代码提取日志

先确认日志框架（在特性相关目录快速扫几行代码确认日志调用风格）：

语言	常见日志调用形式
C++	LOG(INFO) / LOG_F(INFO, ...) / LOGGING_INFO(...) / MLOG(...) / VLOG(...) / LOG_ERROR(...)
Python	logger.debug() / logger.info() / logger.warning() / logger.error() / logger.exception() / logger.critical() / logging.info()

根据实际框架构造搜索，在特性相关目录内覆盖 debug / info / warning / error / fatal / exception 各级别。

「全量」边界（必须遵守）：附录 C 的「全量」= 本特性调用链上的全部关键日志，不是仓库内所有日志。只收录：入口→出口路径上、能反映阶段推进/分支/失败/重试的日志；无关模块的通用启动/调试日志不收录，或在说明中标注「非本特性主路径」。

对每条日志记录：

• 日志原文（占位符 %s、{}、N 等原样保留）
• 级别、文件路径、行号、函数/类名
• 所在分支（成功/失败/重试）

结合调用链（谁调谁、循环/定时器）判断执行顺序，不要只按文件名排序。

缩小模块范围：先检查是否存在 project-content-navigator skill 或 PROJECT-NAV.md，有则用它定位特性相关目录；没有则用通用方式——从项目 README 或顶层目录名判断模块边界，或跑一次 rg -c '<已知的一条关键日志>' 看命中了哪些目录，反向锁定模块范围。

第三步：划分大阶段（§一 用）

• 合并为 3～7 个大阶段（默认 4～5），颗粒度对齐范例：
  • ✅ 「系统初始化 + 角色设置」「配置下发」「建链执行」「状态确认 / 就绪」
  • ❌ 不要把每条 INFO 当成一个阶段
• 每阶段选 1～2 条标志日志（最后出现即可判断「走到了」）。标志日志选择标准：
  • 必经：正常路径一定打印（不能是仅异常分支才打的日志）
  • 唯一：内容足够独特，grep 不会和其他日志混淆
  • 可判：出现它就能断定「走到了这个阶段」
• 写「正常应接着看到」「没走到 → §二.x / §三」
• 在 §一 表中增加列 「全量（表→图）」 或 「备查（表 → 图）」：每步写 [C.x](#c1) → [D.x](#d1)（使用显式锚点 id，见下）
• 总览 Mermaid 下补一行：跨阶段图链接（如 D.5 时序图、D.6 状态图）

第四步：写正文 §二（中等粒度）

每个大阶段一节：

1. 在干什么：1～2 句
2. 子环节表（4～6 行）：子环节 | 关键日志 | 正常含义 | 异常时/分支
3. 文末两行链接（必须）：
   • → 全量表：[C.x](#...)
   • → 全量流程图：[D.x](#...)

第五步：写正文 §三（卡点速查）

表头：你卡在这里 | 落在哪个大阶段 | 优先查什么 | 常见原因

• 8～12 行，覆盖：起不来、缺 Config、正常跳过建链、link 失败、内存注册卡住、部分 failed、无 READY 等
• 文末一条排查顺序（与 §一 步骤一致）

第六步：写附录

附录	内容
A	涉及仓库与组件表
B	关键配置（配置项 | 日志体现 | 说明）
C	特性链路全量日志：按执行顺序编号；分 C.1/C.2… 对应 §二 大阶段；列：序号 | 子模块 | 日志原文 | 说明；另设 C.5 故障相关（若有）
D	全量 Mermaid：每大阶段至少 1 张 flowchart（节点=日志原文，可比分阶段略细）；多组件时加 sequenceDiagram；有队列/状态时加 stateDiagram-v2
E	关键节点索引（阶段 | 关键日志 | 说明），8～10 行
F	故障场景 flowchart 或表

附录 C 编号规则：

场景	规则	示例
单组件 / 单进程	全局连续数字 1, 2, 3…	PD 建链：1～73
多组件 / 多进程并行	组件前缀 + 段内序号，前缀在 §一 表与附录 A 中说明	大 EP：C1～C42（Controller）、CO1～CO43（Coordinator）

同一特性内不要混用两种规则；多组件时 §一「备查」列可写 [C.1](#c1) · [CO 起](#co1)。

显式锚点（必须，避免中文标题 slug 失效）：

每个 #### C.x / #### D.x 标题前插入 HTML 锚点，链接统一用 #id：

<a id="c1"></a>
#### C.1 阶段 1：…

<a id="d1"></a>
#### D.1 …流程

id 命名：c1 c2 … / d1 d2 …；多组件可加前缀 c-ctrl-1、co1。同一文档内 id 唯一。

附录 C / D 互链（必须，缺任一条视为未完成）：

位置	链接
C 章首	阅读链：§一/§二 → 附录 C → 附录 D
每个 C.x 章首	← §一步骤 · §2.x · 流程图 → #dN
每个 C.x 章末	→ 全量流程图：#dN
D 章首	← 附录 C · §一/§二
每个 D.x 章首	← 全量表 #cN

阅读顺序固定：大框架 → 全量表 → 全量流程图。

第七步：落盘与回复

1. 文首：用途说明 + 目录（TOC）（文档较长时必写）
2. Write 到 {输出目录}/{特性}日志定位指南.md
3. 回复用户：绝对路径；简述大阶段数量与附录是否含 D/E/F

---

文档结构模板

生成时必须包含以下章节（标题可随特性微调，层次不得删减）：

# {特性} — 日志定位指南

> **这是什么**：{一句话，这个流程做什么，在整体架构的哪个位置}
> **覆盖范围**：从 {起点日志} 到 {终点日志}
> **涉及组件**：{组件1}、{组件2}（详见 [附录 A](#a-涉及仓库与组件)）
>
> | 术语 | 含义 |
> |------|------|
> | {术语1} | {解释1} |
> | {术语2} | {解释2} |
>
> **你需要准备**：
> - 日志文件：{典型路径或获取方式}
> - 快速过滤：`grep -E "{关键pattern}" <日志文件>`
>
> **阅读优先级**：紧急排障 → 直接看下方「判断口诀」；系统了解 → 按 §一 → §二 → 附录顺序读

## 目录
- [一、快速定位](#一快速定位先看这里)
- [二、分阶段详细定位](#二分阶段详细定位)
- [三、卡点速查](#三卡点速查卡在-x--查-y)
- [四、附录](#四附录)
  - …

## 一、快速定位（先看这里）

> **30 秒速判**：在日志里搜下面几步的标志日志，**最后出现的那条 = 你卡在哪一步**，直接跳对应 §二或 §三。

（4～5 步表格 + 判断口诀 + 可选极简 flowchart LR）

## 二、分阶段详细定位
### 2.1 阶段 1：…
### 2.2 …

## 三、卡点速查（卡在 X → 查 Y）

## 四、附录
### A. 涉及仓库与组件
### B. 关键配置
### C. 全量日志逐步明细
<a id="c1"></a>
#### C.1 …
<a id="d1"></a>
### D. 全量流程图（Mermaid）
### E. 关键节点索引
### F. 故障场景流程

完整行文风格、表格列、附录粒度：对照「文档骨架速记」逐段对齐，不要退化成 log-analysis-document 的「日志整理 + 单张逻辑流程图」格式。

---

Mermaid 规则

• §一 总览图：仅 3～7 个节点（大阶段名），flowchart LR 即可
• 附录 D：按阶段分子图；节点内写日志原文；判断用 {}
• 节点 ID 不重复；subgraph 名用中文
• 颜色（可选，与 document skill 一致）：ERROR 浅红 #ffcccc，判断浅橙 #ffcc99，成功浅绿 #99ff99，跨组件浅蓝 #ccccff

---

注意事项

• 特性跨多仓库时，组件列写成 仓库/子模块（如 cmotor/coordinator），勿过细到内层函数
• 日志未在代码中找到但用户坚持要有：标注「待代码补证」，勿编造
• 与 log-analysis-from-code（表格+关系图）并存：用户要「定位指南」时用本 skill，要「关系图/CSV」时用旧 skill
• 用户说「带附录全量」为默认；若明确「不要 Mermaid」可省略附录 D，但附录 C 仍保留

---

完成检查清单

• 仅 1 个 .md 落盘，无 CSV
• §一 为 3～7 个大阶段，非逐条日志
• §二 每阶段有子环节表 + 指向附录 C 的链接
• §三 有卡点表 + 排查顺序
• 附录 C 仅为特性链路内日志，非全仓扫日志
• 附录 C 编号符合单组件连续 / 多组件前缀规则
• 每个 C.x、D.x 前有 <a id="..."></a>，互链用 #id 而非依赖标题 slug
• §一 表含「表→图」列；§二 每节含 C.x + D.x 链接；附录 C/D 双向互链完整
• 结构对齐「文档骨架速记」（见文件头部）
• 已告知用户绝对路径