理解现有代码
使用 Verdent 探索、分析和理解现有代码库
Verdent for VS Code 通过自然语言提问和自动化探索，帮助你理解陌生的代码库。内置的 Explorer 子智能体能够快速查找文件、搜索代码模式并回答架构相关问题，而不会消耗你的主上下文窗口。
你将学到
- 使用 Explorer 子智能体探索陌生的代码库
- 询问代码结构和实现相关的问题
- 获取函数、类和模块的详细解释
- 从现有代码生成文档
- 理解项目架构和数据流
- 高效地帮助新团队成员上手
前置条件
在使用 Verdent 理解代码之前：
- 已安装 Verdent 扩展的 Visual Studio Code
- 在 VS Code 中打开了一个代码库或项目工作区
- 拥有积分可用的有效 Verdent 套餐
探索陌生的代码库
当你询问代码库结构相关的问题或请求文件搜索时，Verdent 会自动委派给 Explorer 子智能体（@Explorer），这是一个针对快速代码库探索优化的 token 高效型专家。
Explorer 子智能体能够快速：
- 查找匹配模式或名称的文件
- 搜索特定关键字或函数的代码
- 回答关于代码库的架构问题
- 定位功能的实现位置
探索性问题示例：
What is the structure of this project?Where is user authentication handled?Find all API endpoint definitionsShow me where database queries are definedExplorer 在后台高效工作，提供快速答案的同时不会消耗你的主上下文窗口。Verdent 会以相关的文件路径和代码片段呈现结果。
面向复杂任务的并行探索：
对于复杂的探索任务，多个 Explorer 智能体可以并行运行以节省时间，每个智能体同时调查代码库的不同方面。随后 Verdent 会将这些发现综合成一份连贯的总结。
示例：
Use the Explorer agent to find all places where we manually validate email addresses这确保 Verdent 能够系统地发现每一处位置，不会遗漏代码库中的任何实例。
询问你的代码相关问题
Verdent 使用自然语言回答几乎任何关于你代码库的问题。AI 会理解上下文，并提供详细的解释、分析和洞见。
询问特定功能的工作方式：
Explain how authentication works in this projectWhat does the calculateTotal function do?How are API requests handled?Verdent 会分析相关代码，追踪执行流程，并结合具体文件和行号解释其实现。
理解应用程序的全局视图：
What is the overall architecture of this application?How do the components communicate with each other?What design patterns are used in this codebase?Verdent 会检查你的项目结构，识别模式，并解释架构决策。
深入了解技术决策：
Why do you think Redux was chosen instead of Context API for state management?What would happen if I changed the API timeout from 30s to 60s?Is this validateUserInput function redundant?Verdent 会分析代码上下文，并基于你项目的模式和行业最佳实践提供有理有据的解释。
查找特定功能或依赖项：
Where is user data validated?Show me all database queries in the projectWhat dependencies does this project have?Explorer 子智能体使用 grep（内容搜索）和 glob（文件模式匹配）等工具进行高效搜索，返回相关结果而不消耗主上下文。
理解算法和模式：
How does the quicksort algorithm work in the sortItems function?What are the best practices for error handling in React components?Explain the Observer pattern implementation in the EventEmitter classVerdent 会提供清晰的解释，并引用你代码库中的具体实现。
解释函数和类
Verdent 通过分析特定函数或类的实现、参数、返回值以及在整个代码库中的使用情况，提供详细的解释。
示例：
Explain the UserAuth classWhat does the processPayment function do?Break down the ApiService class methodsVerdent 会解释的内容：
- 用途：该函数或类完成了什么
- 参数：输入类型、预期值和约束条件
- 返回类型：输出类型和可能的返回值
- 内部逻辑：实现是如何逐步运作的
- 依赖项：使用的外部模块、函数或服务
- 使用示例：该函数/类在你代码的其他位置如何使用
Verdent 会追踪代码的执行流程，识别边界情况，并解释实现选择背后的理由。
生成文档
Verdent 可以生成多种格式的文档，包括内联代码注释（JSDoc、Python docstrings 等）、README 文件、API 文档和架构指南。
使用 Plan Mode 生成文档
在 Plan Mode 中，Verdent 可以：
- 分析你现有的文档，匹配其风格和详细程度
- 就格式偏好提出澄清性问题（注释风格、详细程度、是否包含示例）
- 分析代码库以了解当前的文档模式
- 呈现一份文档计划，说明将记录哪些内容以及采用何种风格
示例：
Generate JSDoc comments for all functions in the utils folderVerdent 会检查你项目中现有的 JSDoc 注释，就偏好提问（参数描述、是否包含示例用法），然后生成符合你既有约定的文档。
支持的文档格式：
- 内联注释：JSDoc、Python docstrings、Javadoc、XML 文档注释
- README 文件：项目概览、安装说明、使用指南
- API 文档：端点描述、请求/响应格式、认证细节
- 架构指南：系统设计说明、组件关系、数据流图
在生成大量文档时使用 Plan Mode。Verdent 会审查你现有的文档风格并提出澄清性问题，以确保生成的文档符合你项目的约定。
为多个文件生成文档时使用 Plan Mode，在提交前审查文档结构。
总结文件和模块
Verdent 通过阅读代码、理解其结构，并用通俗的语言解释其用途，来分析和总结文件或模块。
示例：
Summarize what the authMiddleware.js file doesExplain the purpose of the UserService moduleWhat's the main responsibility of the PaymentController?Verdent 会提供的内容：
- 主要用途：该文件/模块在系统中完成了什么
- 关键函数：主要的函数或方法及其作用
- 依赖项：使用的外部模块和服务
- 导出项：公共 API 以及系统其他部分可以访问的内容
- 模式：使用的设计模式或架构方法
- 集成点：它如何与项目的其他部分连接
Verdent 会阅读文件、识别关键函数、追踪依赖项，并解释该代码如何融入更大的项目架构中。
理解架构
Verdent 通过详细的文字描述、组件关系和数据流说明来解释架构。虽然它不会直接生成图形化图表，但可以创建 ASCII 字符图或可供渲染的 Mermaid 图表代码。
示例：
Explain the architecture of this application and show component relationshipsVerdent 可能会生成一个 ASCII 表示：
Frontend (React)
↓
API Layer (Express)
↓
Service Layer (Business Logic)
↓
Database Layer (PostgreSQL)或生成可供渲染的 Mermaid 代码：
graph TD
A[React Frontend] --> B[API Gateway]
B --> C[Auth Service]
B --> D[User Service]
C --> E[Database]
D --> E架构解释包括：
- 组件交互：系统不同部分如何通信
- 数据流：信息如何在应用程序中流动
- 架构模式：MVC、微服务、分层架构等
- 技术栈：前端、后端、数据库、外部服务
- 集成点：API、消息队列、webhook、第三方服务
- 可扩展性模式：负载均衡、缓存、数据库分片
Verdent 会分析你的项目结构，追踪导入和依赖关系，识别模式，并解释你系统设计背后的架构决策。
帮助新团队成员上手
Verdent 通过回答代码库相关问题、解释架构决策、识别关键文件和模式，以及生成专门帮助新人理解项目结构和约定的文档，来帮助新团队成员上手。
在 Plan Mode 中，Verdent 可以提出澄清性问题，了解代码库的哪些方面与新团队成员的职责最相关，然后创建个性化的上手指南。
上手问题示例：
What's the best starting point for understanding this codebase?How does data flow from the API to the frontend?Where should I look to understand the authentication system?What are the naming conventions and code style guidelines used here?Verdent 可以生成：
- 上手指南：代码库架构的逐步讲解
- 组件图：展示组件之间关系的可视化或文本指南
- 常见模式：频繁使用的模式和约定的文档
- 安装说明：如何配置开发环境并运行项目
- 首批任务：建议简单的首次贡献以熟悉项目
新团队成员可以通过对话方式探索代码库，立即获得答案，无需打断资深开发者，也无需花费数小时通读代码。
Verdent 的 Explorer 子智能体让新人能够高效地发现代码库。他们可以提出宽泛的问题，如"展示所有 React 组件"，或具体的查询，如"错误日志在哪里实现？"，并立即获得准确的答案。
最佳实践
先提宽泛的问题，再逐步深入
先从高层次的问题开始，如"架构是什么？"，然后再深入具体的实现。这样可以逐步构建上下文。
进行全面搜索时显式使用 Explorer 子智能体
对于跨代码库的彻底搜索，显式提及 Explorer 智能体以确保不遗漏任何实例："使用 Explorer 查找所有的认证检查。"
多问'为什么'，而不只是'是什么'
理解决策背后的理由往往比理解实现更有价值。在问"这段代码做什么？"的同时，也问"为什么选择这种模式？"
利用 Plan Mode 生成文档
在生成文档时，使用 Plan Mode 来审查 Verdent 的方案，确保它符合你的风格，并在执行前完善计划。
使用 @ 提及获得聚焦的解释
当你想要详细解释时，引用具体的文件："@components/UserProfile.tsx 解释这个组件"可确保 Verdent 聚焦于正确的代码。
在请求修改前先构建上下文
在进行修改之前，先让 Verdent 解释当前的实现。这有助于 Verdent 提出更符合现有模式的建议。
自由地提出后续问题
Verdent 会保持对话上下文，因此你可以提出澄清性问题、请求更深入的解释，或探索相关主题，而无需重复上下文。