project-analyzer

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