项目分析技能
本技能提供两种分析模式，帮助理解和可视化代码库结构。
前置检查：已有文档检索
在执行任何分析之前，必须先执行此步骤。
步骤 1：扫描已有文档
使用 metadata 扫描脚本检查目标项目的 docs/ 目录是否存在已有的分析文档：
python3 <skills-root>/skills/project-analysis/scripts/scan_docs_metadata.py <项目根目录>/docs
脚本会输出 JSON 格式的文档列表，包含每份文档的 metadata（type、scope、module、keywords）和内容摘要。
步骤 2：判断相似性
将用户当前的分析请求与扫描结果进行比对：
- 类型匹配：用户请求的分析类型（architecture/dataflow/sequence）是否与已有文档的
type字段匹配 - 范围匹配：分析范围（full/module）和目标模块（
module字段）是否一致 - 关键词匹配：用户描述中的关键词是否与已有文档的
keywords字段高度重叠
步骤 3：发现相似文档时暂停
如果发现与用户请求高度相似的已有文档（类型+范围+模块匹配，或关键词重叠度高），必须暂停分析任务，使用 AskUserQuestion 工具向用户提问：
提问内容应包含：
- 已有文档的文件路径
- 已有文档的简要概述（基于 metadata 和 summary）
- 已有文档的生成日期
- 询问用户是否仍需继续进行新的分析
示例提问格式：
在 docs/ 目录下发现了类似的分析文档：
- 文件：docs/architecture.md
- 类型：系统架构分析
- 日期：2024-01-15
- 概述：全项目架构分析，涵盖 React + Node.js 技术栈...
是否仍需要重新进行分析？
用户确认继续后，才进入下方的分析模式执行实际分析。
如果 docs/ 目录不存在或无相似文档，直接进入分析模式。
分析模式
模式一：系统架构分析
从宏观层面分析项目，生成整体架构视图。
详细分析步骤和执行指南参考：
references/mode-architecture.md
模式二：模块数据流分析
深入分析特定模块或功能的数据流转过程。
详细分析步骤和执行指南参考：
references/mode-dataflow.md
文档输出步骤
分析完成后，按以下步骤将结果保存到 docs/ 目录。
步骤 1：确定输出文件路径
根据分析类型确定文件名（命名规范见 references/output-spec.md）：
| 分析类型 | 文件名 |
|---|---|
| 系统架构 | docs/architecture.md |
| 模块架构 | docs/architecture-{模块}.md |
| 数据流 | docs/dataflow-{功能}.md |
| 时序图 | docs/sequence-{流程}.md |
步骤 2：写入文档
使用 Write 工具将报告写入目标文件。文档必须采用两段式结构：
第一段：YAML Frontmatter Metadata
---
type: architecture | dataflow | sequence
scope: full | module
module: "" # scope=module 时必填
date: "YYYY-MM-DD"
keywords:
- 关键词1
- 关键词2
tech_stack:
- 技术栈1
entry_point: "" # 数据流分析时填写
---
第二段：Markdown 正文
按对应分析类型的报告模板填写（模板见 references/output-spec.md）。
步骤 3：确认输出
告知用户：
- 文档已保存的完整路径
参考文件
- 分析模式详细步骤：
references/mode-architecture.md、references/mode-dataflow.md - 文档模板与命名规范：
references/output-spec.md - Mermaid 图表模板：
references/mermaid-templates.md