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