# Project Analyzer

> 代码仓库梳理与项目文档生成技能。当用户明确要求梳理项目或使用项目梳理功能时触发此技能。典型触发场景包括"帮我梳理这个项目"、"梳理一下这个代码仓"、"使用项目梳理"等。此技能读取项目代码仓，按照结构化模板生成完整的项目梳理 Markdown 文档。

- Skill: `5zjk5/project-analyzer` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add 5zjk5/project-analyzer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/5zjk5/project-analyzer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: 5zjk5 (https://skillmd.com/u/5zjk5)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/5zjk5/project-analyzer

---


# Project Analyzer — 代码仓库梳理

## 概述

此技能用于系统性梳理代码仓库，生成结构化的项目文档。通过分阶段探索代码仓——从宏观架构到微观功能流程——最终输出一份按模板组织的 Markdown 文档，帮助用户快速理解项目的定位、架构、业务流程和接口细节。

文档设计理念：**流程与接口分离**。功能模块章节聚焦"业务流程理解"（text 流程图对标代码 + mermaid 流程图可视化流转），接口的入参/返回值等技术细节统一汇总到最后的接口文档章节，避免流程阅读被接口字段表格打断。

## 触发条件

**仅在用户明确要求时触发**，包括但不限于：
- 用户说"梳理项目"、"梳理一下这个项目"、"帮我梳理项目"
- 用户说"使用项目梳理"
- 用户明确要求生成项目梳理文档

**不触发**的场景：
- 用户只是问某个模块怎么工作、某个接口怎么实现（这类问题直接回答，不启动完整梳理流程）
- 用户说"理解一下代码"、"看看这个文件"（这不等于梳理项目）

## 核心工作流

当用户触发此技能时，按以下流程执行：

### 阶段一：读取梳理模板

1. 读取 `references/project-analysis-template.md`，了解输出文档的结构和各节要求。
2. 模板定义了以下核心章节（根据项目实际情况取舍）：
   - **第1章**：项目一句话定位
   - **第2章**：解决什么问题（痛点 + 处理思路）
   - **第3章**：技术架构（前端/后端框架、关键依赖、启动方式、配置项）
   - **第4章起至倒数第二章**：按功能模块组织，每个功能模块一个大章节
     - 功能模块内部先按**功能点**分子章节（文字总结 + text 流程图 + mermaid 流程图 + 补充说明）
     - 功能点之后列出本模块涉及的**关键机制**子章节（数据存储、记忆/会话机制、提示词设计等）
     - 关键机制归属到使用它的功能模块下，不单独成顶级章节
   - **最后章节（接口文档）**：汇总项目所有后端接口，按业界接口文档规范编写，每个接口一个小节，标题用功能名而非 HTTP 方法和路径

**关键原则**：模板是参考框架而非强制约束。根据项目实际情况调整章节结构——简单项目可简化，复杂项目可扩展。模板中的【】占位符为填写指引，最终输出应替换为实际内容。

### 阶段二：宏观探索 — 理解项目全貌

目标：建立对项目整体结构的认知，不深入代码细节。

1. **识别项目类型**：查看根目录文件（README.md、package.json、pyproject.toml、requirements.txt、Makefile、docker-compose.yml 等），判断项目语言、框架、前后端结构。
2. **梳理目录结构**：列出顶层目录和关键子目录，理解代码组织方式（如 monorepo、前后端分离、模块化等）。
3. **识别入口文件**：找到服务启动入口（main.py、app.py、index.ts、server.js 等），了解服务如何启动。
4. **识别配置文件**：查看 .env、config/、settings 等，了解环境变量和配置结构。
5. **识别路由/接口定义**：找到 API 路由注册位置（routes/、api/、controllers/ 等），建立接口清单。
6. **识别数据模型**：找到 models/、schemas/、entities/ 等，了解核心数据结构。
7. **识别关键模块**：根据项目类型，识别需要单独成章节的关键模块（如记忆机制、提示词、存储、沙箱等）。

**产出**：对项目的整体架构、技术栈、目录组织有清晰认知，为后续深入梳理奠定基础。

### 阶段三：微观深入 — 逐功能模块梳理

目标：深入代码逻辑，按功能模块逐个梳理功能点流程和关键机制。

1. **功能模块划分**：
   - 根据路由定义和业务逻辑，将功能点划分为不同功能模块
   - 每个功能模块对应输出文档的一个大章节
   - 功能模块内部先按功能点分子章节，功能点之后列出本模块涉及的关键机制子章节

2. **功能点梳理**（每个功能点按以下结构组织，聚焦流程理解，不包含入参/返回值）：
   - **功能点命名**：用功能描述命名（如"创建会话"、"查询历史消息"），让人一眼看出功能点做什么，不要用 HTTP 方法和路径
   - **文字总结**：1-2 句话说明功能点做什么
   - **text 流程图**：使用 text 格式的树状流程图，标注每一步调用的函数和所在文件路径，深度对标原始代码，便于读者定位源码
   - **mermaid 流程图**：使用 `flowchart TD` 类型，直观可视化展现业务流转，节点标注关键动作和函数/文件位置
   - **补充说明**：关键细节、边界条件、注意事项

3. **关键机制梳理**（归属到使用它的功能模块下，作为子章节）：
   - **数据存储**：存储分层、表结构、存储目录
   - **记忆/会话机制**（智能体/对话项目）：历史加载、消息保存、记忆轮数、压缩策略、上下文管理
   - **提示词设计**（LLM/智能体项目）：每个提示词的用途、组装结构、关键约束
   - **其他关键机制**：沙箱执行、缓存策略、权限控制等
   - 如果多个功能模块都涉及同一关键机制，各自在自己的章节下说明，侧重描述本模块如何使用

**关键原则**：
- 功能点梳理使用**两种流程图互补**：text 流程图对标代码细节（便于定位源码），mermaid 流程图展现业务流转（便于直观理解）
- text 流程图中每个节点标注：做了什么 + 调用的函数名 + 所在文件路径
- mermaid 流程图节点标注关键动作，可用 `<br/>` 换行后附上函数名和文件位置；条件分支的边标注判断条件
- 条件分支在 text 流程图中用文字说明判断条件
- 简单线性流程可省略 mermaid 图，仅保留 text 流程图
- **入参/返回值不在功能模块章节出现**，统一放到最后的接口文档章节
- 关键机制（存储、记忆、提示词等）归属到使用它的功能模块下，不单独成顶级章节

### 阶段四：接口文档梳理

目标：按业界接口文档规范，梳理项目所有后端接口的入参、返回值等技术细节。

1. **汇总所有后端接口**：从阶段二建立的路由清单和阶段三梳理的功能点中，汇总项目所有后端接口。
2. **每个接口按以下结构组织**（作为接口文档章节的一个小节）：
   - **章节标题**：用**功能名**命名（如"创建会话"），不要用 `POST /api/xxx`，让人一眼看懂接口用途
   - **所属模块**：标注属于哪个功能模块，便于交叉查阅
   - **请求方法**：GET/POST/PUT/DELETE 等
   - **请求路径**：接口路径
   - **入口文件**：路径/文件.py → 函数名()
   - **功能说明**：1-2 句话说明接口做什么
   - **请求参数**：字段表格（字段名、类型、是否必填、说明）
   - **请求示例**：JSON 示例
   - **返回结果**：字段表格（字段名、类型、说明）
   - **返回示例**：JSON 示例
   - **补充说明**：边界条件、异常情况、注意事项
3. **接口排序**：同一功能模块的接口放在一起，按业务流程顺序排列。
4. **简单接口**：如果请求参数或返回结果很简单，可省略示例，仅保留字段表格。
5. **无后端接口的项目**：如果项目没有后端接口（如纯前端项目、纯脚本工具），可省略此章节。

### 阶段五：生成输出文档

1. **按模板结构组织内容**：将梳理结果填入模板定义的各章节中。
2. **自定义调整**：
   - 如果项目没有前后端分离，省略前端相关章节
   - 如果项目是智能体/Agent 类，其功能模块下必须包含记忆机制和提示词设计子章节
   - 如果项目是 LLM 应用，其功能模块下必须包含提示词设计子章节
   - 如果项目没有后端接口，省略接口文档章节
   - 根据项目特点追加必要的章节
3. **输出 Markdown 文件**：将最终文档写入用户指定的路径，或默认放在项目根目录下命名为 `项目梳理.md`。

## 代码探索策略

在阶段二和阶段三中，使用以下策略高效探索代码：

### 探索工具选择

- **目录结构**：优先使用 Glob 工具匹配文件模式（`**/*.py`、`**/routes/*` 等）
- **关键定义搜索**：使用 Grep 工具搜索路由装饰器（`@router`、`@app`）、类定义（`class`）、配置项等
- **文件阅读**：使用 Read 工具逐文件阅读关键源码
- **大规模探索**：当代码仓较大时，优先使用 Agent（Explore 类型）进行并行探索

### 探索顺序建议

1. 入口文件 → 路由注册 → 服务层 → 数据层
2. 主业务流程 → 辅助功能 → 工具函数
3. 核心模块 → 扩展模块 → 测试文件

### 深度控制

- 功能点梳理：深入到服务层内部，用 text 流程图标注每一步调用和文件位置，用 mermaid 流程图可视化业务流转
- 接口文档梳理：梳理完整的入参、返回值字段，提供请求/返回示例
- 工具函数：仅说明用途和关键参数，不必展开实现
- 第三方库调用：说明调用了什么、传了什么参数，不必展开库内部逻辑
- 配置项：列出关键配置项和默认值
- 关键模块（存储、记忆、提示词）：需要详细说明机制、参数、限制

## 输出质量要求

- **准确性**：所有代码路径、函数名、文件位置必须与实际代码一致，不得臆造
- **完整性**：核心功能点和业务流程必须全部覆盖，所有后端接口必须在接口文档章节中汇总，不得遗漏
- **流程图互补**：text 流程图对标代码细节便于定位源码，mermaid 流程图直观展现业务流转，两者互补而非重复
- **流程与接口分离**：功能模块章节聚焦流程理解（不含入参/返回值），接口文档章节汇总接口技术细节（入参、返回值、示例）
- **可读性**：功能点和接口用功能名命名，让人一眼看懂用途；技术描述应兼顾深度与可理解性
- **实用性**：文档应能让新成员快速理解项目架构和核心流程
- **结构化**：严格按照模板章节组织，功能模块独立成章，关键机制归属到对应功能模块下，接口文档作为最后章节
- **关键机制不遗漏**：智能体项目的功能模块下必须包含记忆机制和提示词子章节，LLM 项目的功能模块下必须包含提示词子章节

## 资源说明

### references/project-analysis-template.md

项目梳理输出模板。定义了文档的标准结构和各章节的填写指引。在阶段一必须读取此文件，在阶段五按此模板组织输出内容。

模板的关键结构说明：
- **第1-3章**：固定结构，所有项目必须包含
- **第4章起至倒数第二章**：按功能模块组织，每个功能模块一个大章节
- **功能模块内部**：先按功能点分子章节（文字总结 + text 流程图 + mermaid 流程图 + 补充说明），功能点之后列出本模块涉及的关键机制子章节
- **关键机制归属**：归属到使用它的功能模块下，不单独成顶级章节；多个模块都涉及的，各自在自己章节下说明
- **最后章节（接口文档）**：汇总项目所有后端接口，按业界接口文档规范编写，每个接口一个小节，标题用功能名而非 HTTP 方法和路径
- **模板使用说明**：章节组织原则、功能点编写规范、text 流程图编写规范、mermaid 流程图编写规范、接口文档编写规范、关键机制归属规则