By name: project-analyzer description: 代码仓库梳理与项目文档生成技能。当用户明确要求梳理项目或使用项目梳理功能时触发此技能。典型触发场景包括"帮我梳理这个项目"、"梳理一下这个代码仓"、"使用项目梳理"等。此技能读取项目代码仓，按照结构化模板生成完整的项目梳理 Markdown 文档。 agent_created: true
Project Analyzer — 代码仓库梳理
概述
此技能用于系统性梳理代码仓库，生成结构化的项目文档。通过分阶段探索代码仓——从宏观架构到微观接口细节——最终输出一份按模板组织的 Markdown 文档，帮助用户快速理解项目的定位、架构、业务流程和接口逻辑。
触发条件
仅在用户明确要求时触发，包括但不限于：
- 用户说"梳理项目"、"梳理一下这个项目"、"帮我梳理项目"
- 用户说"使用项目梳理"
- 用户明确要求生成项目梳理文档
不触发的场景：
- 用户只是问某个模块怎么工作、某个接口怎么实现（这类问题直接回答，不启动完整梳理流程）
- 用户说"理解一下代码"、"看看这个文件"（这不等于梳理项目）
核心工作流
当用户触发此技能时，按以下流程执行：
阶段一：读取梳理模板
- 读取
references/project-analysis-template.md，了解输出文档的结构和各节要求。 - 模板定义了以下核心章节（根据项目实际情况取舍）：
- 第1章：项目一句话定位
- 第2章：解决什么问题（痛点 + 处理思路）
- 第3章：技术架构（前端/后端框架、关键依赖、启动方式、配置项）
- 第4章起：按功能模块组织，每个功能模块一个大章节
- 功能模块内部先按接口分子章节（文字总结 + 流程图 + 补充说明）
- 接口之后列出本模块涉及的关键机制子章节（数据存储、记忆/会话机制、提示词设计等）
- 关键机制归属到使用它的功能模块下，不单独成顶级章节
关键原则：模板是参考框架而非强制约束。根据项目实际情况调整章节结构——简单项目可简化，复杂项目可扩展。模板中的【】占位符为填写指引，最终输出应替换为实际内容。
阶段二：宏观探索 — 理解项目全貌
目标：建立对项目整体结构的认知，不深入代码细节。
- 识别项目类型：查看根目录文件（README.md、package.json、pyproject.toml、requirements.txt、Makefile、docker-compose.yml 等），判断项目语言、框架、前后端结构。
- 梳理目录结构：列出顶层目录和关键子目录，理解代码组织方式（如 monorepo、前后端分离、模块化等）。
- 识别入口文件：找到服务启动入口（main.py、app.py、index.ts、server.js 等），了解服务如何启动。
- 识别配置文件：查看 .env、config/、settings 等，了解环境变量和配置结构。
- 识别路由/接口定义：找到 API 路由注册位置（routes/、api/、controllers/ 等），建立接口清单。
- 识别数据模型：找到 models/、schemas/、entities/ 等，了解核心数据结构。
- 识别关键模块：根据项目类型，识别需要单独成章节的关键模块（如记忆机制、提示词、存储、沙箱等）。
产出：对项目的整体架构、技术栈、目录组织有清晰认知，为后续深入梳理奠定基础。
阶段三：微观深入 — 逐功能模块梳理
目标：深入代码逻辑，按功能模块逐个梳理接口流程和关键机制。
功能模块划分：
- 根据路由定义和业务逻辑，将接口划分为不同功能模块
- 每个功能模块对应输出文档的一个大章节
- 功能模块内部先按接口分子章节，接口之后列出本模块涉及的关键机制子章节
接口梳理（每个接口按以下结构组织）：
- 接口声明：HTTP 方法、路径、入口文件、处理函数
- 文字总结：1-2 句话说明接口做什么
- 流程图：使用 text 格式的树状流程图，标注每一步调用的函数和所在文件路径，深度对标原始代码
- 补充说明：关键细节、边界条件、注意事项
- 入参/返回值：仅接口较复杂时列出字段说明表，简单接口可省略
关键机制梳理（归属到使用它的功能模块下，作为子章节）：
- 数据存储：存储分层、表结构、存储目录
- 记忆/会话机制（智能体/对话项目）：历史加载、消息保存、记忆轮数、压缩策略、上下文管理
- 提示词设计（LLM/智能体项目）：每个提示词的用途、组装结构、关键约束
- 其他关键机制：沙箱执行、缓存策略、权限控制等
- 如果多个功能模块都涉及同一关键机制，各自在自己的章节下说明，侧重描述本模块如何使用
关键原则：
- 接口梳理使用流程图（text 格式树状图）而非纯文字逐步骤描述，流程图更直观、更易对标代码
- 流程图中每个节点标注：做了什么 + 调用的函数名 + 所在文件路径
- 条件分支用文字说明判断条件
- 简单接口可简化流程图，不必强行拆分过多步骤
- 关键机制（存储、记忆、提示词等）归属到使用它的功能模块下，不单独成顶级章节
阶段四：生成输出文档
- 按模板结构组织内容：将梳理结果填入模板定义的各章节中。
- 自定义调整：
- 如果项目没有前后端分离，省略前端相关章节
- 如果项目是智能体/Agent 类，其功能模块下必须包含记忆机制和提示词设计子章节
- 如果项目是 LLM 应用，其功能模块下必须包含提示词设计子章节
- 根据项目特点追加必要的章节
- 输出 Markdown 文件：将最终文档写入用户指定的路径，或默认放在项目根目录下命名为
项目梳理.md。
代码探索策略
在阶段二和阶段三中，使用以下策略高效探索代码：
探索工具选择
- 目录结构：优先使用 Glob 工具匹配文件模式（
**/*.py、**/routes/*等） - 关键定义搜索：使用 Grep 工具搜索路由装饰器（
@router、@app）、类定义（class）、配置项等 - 文件阅读：使用 Read 工具逐文件阅读关键源码
- 大规模探索：当代码仓较大时，优先使用 Agent（Explore 类型）进行并行探索
探索顺序建议
- 入口文件 → 路由注册 → 服务层 → 数据层
- 主业务流程 → 辅助功能 → 工具函数
- 核心模块 → 扩展模块 → 测试文件
深度控制
- 接口梳理：深入到服务层内部，用流程图标注每一步调用和文件位置
- 工具函数：仅说明用途和关键参数，不必展开实现
- 第三方库调用：说明调用了什么、传了什么参数，不必展开库内部逻辑
- 配置项：列出关键配置项和默认值
- 关键模块（存储、记忆、提示词）：需要详细说明机制、参数、限制
输出质量要求
- 准确性：所有代码路径、函数名、文件位置必须与实际代码一致，不得臆造
- 完整性：核心接口和业务流程必须全部覆盖，不得遗漏
- 可读性：流程图优先于纯文字描述，技术描述应兼顾深度与可理解性
- 实用性：文档应能让新成员快速理解项目架构和核心流程
- 结构化：严格按照模板章节组织，功能模块独立成章，关键机制归属到对应功能模块下
- 关键机制不遗漏：智能体项目的功能模块下必须包含记忆机制和提示词子章节，LLM 项目的功能模块下必须包含提示词子章节
资源说明
references/project-analysis-template.md
项目梳理输出模板。定义了文档的标准结构和各章节的填写指引。在阶段一必须读取此文件，在阶段四按此模板组织输出内容。
模板的关键结构说明：
- 第1-3章：固定结构，所有项目必须包含
- 第4章起：按功能模块组织，每个功能模块一个大章节
- 功能模块内部：先按接口分子章节，接口之后列出本模块涉及的关键机制子章节（数据存储、记忆/会话机制、提示词设计等）
- 关键机制归属：归属到使用它的功能模块下，不单独成顶级章节；多个模块都涉及的，各自在自己章节下说明
- 模板使用说明：章节组织原则、接口编写规范、流程图编写规范、关键机制归属规则