---
name: source-doc-analyzer
description: 用于分析单个源码文件或大型功能模块，生成包含统一源码链接、Mermaid图表、费曼通俗解释及问题解答的 Markdown 文档，并默认执行 Git 忽略策略。
---

# 源码与模块关联分析文档

## 目标

把单个源码文件或整个大型功能模块分析成 Markdown 文档。文档必须回答模块的核心职责、设计思路、关键流转过程、风险改造点，并通过一致的链接完美映射回源码。同时，要用费曼学习法进行通俗讲解，并解答用户提出的所有具体疑问。

## 核心工作流

1. 确认输入与输出。
   - 目标对象：用户指定的单个文件，或整个文件夹/大功能模块。
   - 输出目录：若未指定，优先在当前工作目录创建 `TEMP_MD` 文件夹。
   - Git 追踪：**默认执行 Git 忽略策略**（详见下方规则），确保生成的分析文档绝对不污染项目提交记录。

2. 读取源码与结构。
   - 宏观把控：优先使用 `rg` (ripgrep) 或终端工具提取核心类、接口、依赖关系。
   - 微观深挖：绝不只看方法签名，必须分段读取关键实现逻辑。若为大模块，理清模块间的调用拓扑图。

3. 建立源码链接（**严格统一原则**）。
   - 必须使用相对路径链接到源码：`[显示文本](../path/to/File.cs#锚点)`。
   - **格式强制统一**：全篇必须严格只使用一种锚点定位方式（要么全部使用 `#L行号`，要么全部使用 `#函数名`）。绝对不允许在同一个文档或同批次文档中混用。

4. 动态详细度与文档切分。
   - **默认状态**：输出正常长度的内容，覆盖核心流程和主要方法。
   - **深度模式**：若检测到用户的提示词中包含“详尽”、“仔细”、“全面”、“深入”等词汇，必须极度扩充内容细节，深挖每一层调用链条、数据结构变化和边缘分支；此时**允许并建议将输出拆分成多个 Markdown 文档**（例如：按子模块拆分为 `<模块名>_核心架构.md`、`<模块名>_数据流转.md`）。

5. 绘制图表与组织内容。
   - **图表化**：分析模块或复杂流程时，必须使用 Mermaid 语法生成标准的流程图（Flowchart）或 UML 类图（Class Diagram）。
   - **费曼学习法**：在“设计思路”等抽象环节，必须使用生活中的通俗事物作为比喻，把复杂、晦涩的架构讲得连外行也能听懂。
   - **问题响应**：若用户调用 Skill 时附带了疑问，必须在专门的“用户疑问解答”章节中提供详尽的针对性回复。

6. 验证。
   - 确认 Markdown 文件（或文件组）成功生成，图表语法未越界，链接锚点格式全篇绝对统一。
   - 确认 Git 忽略策略已执行。

## 文档结构模板

（若进入“深度模式”拆分了多文档，请以此模板为基础进行合理变体；单文档严格参考此结构）

```markdown
# <模块或文件名> 架构分析

分析范围：[`<主目录或核心文件>`](../relative/path/)

## 核心解答

<若用户在调用时提出了具体问题，在此处逐一详尽解答。若无，可略过此节。>

## 一句话概括

<用一句话说明该模块/文件在整个系统中承担的核心职责。>

## 架构与流程图

<必须使用 Mermaid 语法提供系统拓扑、UML类图或核心业务流程图>

## 设计思路 (费曼解析)

<使用费曼学习法，用通俗易懂的生活类比来解释这里的架构为什么这样设计。>

## 核心组件/方法索引

| 分类/组件 | 核心方法/类 | 位置 | 作用 |
|---|---|---:|---|
| <功能分类> | `<名称>` | [统一锚点](../relative/path/File.cs#锚点) | <通俗说明核心逻辑> |

## 核心流程走读

### 1. <流程名称>

代码定位：[`<入口名称>`](../relative/path/File.cs#锚点)

| 步骤 | 代码定位 | 逻辑说明 |
|---|---:|---|
| <执行步骤> | [统一锚点](../relative/path/File.cs#锚点) | <该步骤的数据变化与职责> |

## 风险和注意点

<列出真实的潜在风险、并发问题或性能瓶颈，必须附上代码位置。>

## 后续建议

<给出与用户目标相关的落地建议（如重构点、拓展接口预留等）。>
```

## 默认 Git 忽略策略（强制执行）

文档生成前或生成后，必须默认通过以下方式防止文档被 Git 追踪：

1. 优先方案：如果当前目录是 Git 仓库，自动将输出的目录路径追加写入 `.git/info/exclude` 中（不污染项目代码库）。
2. 备选方案：若无法写入 exclude，则在输出目录内创建 `.gitignore`，内容为：
   ```gitignore
   *
   !.gitignore
   ```
3. 在最终对话回复中，必须向用户简要汇报：“已默认将输出目录加入 Git 忽略规则”。

## 全局质量要求

- 除非检测到用户使用其他语言提问，否则默认使用简体中文输出。
- Mermaid 图表中的连线和节点命名必须清晰，支持在标准 Markdown 预览器中渲染。
- 绝不编造方法职责；遇到晦涩代码必须查看上下文后再下笔。
- 最终回复中必须列出：**所有生成文档的路径列表**、**统一使用的锚点类型** 以及 **Git 忽略结果**。