| 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 到输出目录。
执行流程
第一步：确认输入
- 代码仓、代码根目录、特性描述（用于标题与阶段命名）
- 输出目录（绝对路径）
- 特性边界：起止条件（如「从 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～2 句
- 子环节表（4～6 行）：子环节 | 关键日志 | 正常含义 | 异常时/分支
- 文末两行链接（必须）：
→ 全量表：[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 |
阅读顺序固定：大框架 → 全量表 → 全量流程图。
第七步：落盘与回复
- 文首：用途说明 + 目录（TOC）（文档较长时必写）
Write 到 {输出目录}/{特性}日志定位指南.md- 回复用户：绝对路径；简述大阶段数量与附录是否含 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 仍保留
完成检查清单
