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 流程图编写规范、接口文档编写规范、关键机制归属规则