deepv-code

🚀 DeepV Code

AI 驱动的智能编程助手

赋能开发者，加速创新

English | 简体中文

📖 目录

• 项目简介
• 为什么选择 DeepV Code
• 核心特性
• 快速安装
• 快速开始
• CLI 命令参考
• 交互式斜杠命令
• 项目架构
• VS Code 扩展
• 内置工具系统
• MCP 协议支持
• Hooks 钩子机制
• 配置文件
• 开发指南
• 常见问题
• 贡献指南
• 路线图
• 许可证
• 相关链接

✨ 项目简介

DeepV Code 是一款革命性的 AI 驱动智能编程助手，通过深度整合人工智能技术，全面提升软件开发的效率、质量和创新能力。

不同于传统的代码补全工具，DeepV Code 是一个能够理解整个项目上下文、自主编排工具完成复杂任务的智能代理（Agent）。它将开发者从繁琐重复的工作中解放出来，让你专注于更高层次的创新和问题解决。

💡 DeepV Code 能做什么？

👤 你：帮我分析这个项目的架构，找出性能瓶颈，并给出优化方案

🤖 DeepV Code：
   ├── 📂 扫描项目结构，理解模块依赖
   ├── 🔍 分析代码热点和复杂度
   ├── 📊 识别潜在的性能问题
   ├── 💡 生成优化建议和重构方案
   └── ✏️ 自动应用修改（经你确认后）

🌟 为什么选择 DeepV Code

🎯 与传统 AI 编码助手的区别 特性 传统工具 DeepV Code 上下文范围 单文件 整个项目 交互方式 被动补全 主动代理 任务复杂度 简单补全 复杂工作流 工具调用 无 Shell/文件/Web 会话管理 无 持久化会话 可扩展性 受限 MCP/Hooks/Skills

🚀 核心优势 🧠 深度理解 - 通过 MCP 协议构建完整项目认知 🛠️ 自主执行 - AI 可调用工具完成实际操作 🔄 持续对话 - 会话保存/恢复，上下文不丢失 🎨 多端支持 - CLI + VS Code 插件 🔌 高度可扩展 - Hooks、Skills、MCP 服务器 🔒 安全可控 - 敏感操作需用户确认

🎯 核心特性

🧠 AI 驱动的代码生成与重构

• 智能代码生成 - 根据自然语言描述生成完整的函数、类、模块甚至整个应用
• 代码重构建议 - 识别代码异味，提供优化方案，自动统一代码风格
• Bug 智能修复 - 分析错误堆栈，定位问题根源，生成修复代码
• 多语言支持 - TypeScript、JavaScript、Python、Go、Rust、Java 等主流语言

🔍 智能调试与问题解决

• 错误日志分析 - 深入解析错误信息，快速定位问题
• 堆栈追踪诊断 - 理解调用链路，找出异常根因
• 自动修复执行 - 生成修复方案，一键应用（需确认）
• 增强调试控制台 - Ctrl+O 三状态循环：全部日志 → 仅错误 → 关闭，智能过滤错误信息

📦 高级上下文管理 (MCP)

Model Context Protocol (MCP) 是 DeepV Code 的核心创新：

• 全局项目视图 - 理解文件结构、模块依赖、代码语义
• 跨文件分析 - 追踪函数调用链、类型引用、导入导出
• 智能上下文选择 - 自动识别与任务相关的文件和代码段
• 第三方 MCP 服务器 - 接入外部数据源和工具

🛠️ 可扩展工具系统

AI 通过工具与外部环境交互，内置丰富工具集：

📁 文件操作    → read_file, write_file, replace, delete_file, glob
🔍 代码搜索    → grep (ripgrep), read_many_files
💻 命令执行    → shell (bash/powershell)
🌐 网络访问    → web_fetch, web_search (Google)
🧩 MCP 工具    → 调用任意 MCP 服务器提供的工具
📊 代码分析    → task (启动分析子 Agent)
📝 任务管理    → todo_write
💾 记忆系统    → memory (长期记忆)

🪝 Hooks 钩子机制

在关键工作流节点注入自定义逻辑：

• PreToolExecution - 工具执行前触发
• PostToolExecution - 工具执行后触发
• OnSessionStart - 会话开始时触发
• OnSessionEnd - 会话结束时触发

支持自动化代码检查、格式化、提交前验证等场景。

🔄 会话管理

• 会话持久化 - 自动保存对话历史和上下文
• 会话恢复 - 随时继续之前的工作
• 历史压缩 - 智能压缩对话历史，节省 Token
• 检查点恢复 - 文件修改可回滚到之前状态

📦 快速安装

系统要求

• Node.js 20.0.0 或更高版本
• 操作系统 Windows / macOS / Linux
• 终端 支持 ANSI 颜色的终端模拟器

方式一：npm 全局安装（推荐）

# 使用 npm
npm install -g deepv-code

# 使用 yarn
yarn global add deepv-code

# 使用 pnpm
pnpm add -g deepv-code

安装完成后，验证安装：

dvcode --version

方式二：从源码构建

# 1. 克隆仓库
git clone https://github.com/OrionStarAI/DeepVCode.git
cd DeepVCode

# 2. 安装依赖
npm install

# 3. 构建项目
npm run build

# 4. 本地开发运行
npm run dev

# 5. (可选) 生产环境打包
npm run pack:prod

🚀 快速开始

第一步：启动 DeepV Code

在任意项目目录中运行：

dvcode

首次启动会引导你完成身份认证。

第二步：开始对话

┌─────────────────────────────────────────────────────────────┐
│  🚀 DeepV Code - AI 驱动的智能编程助手                    │
│─────────────────────────────────────────────────────────────│
│                                                             │
│  👋 你好！我是 DeepV Code，你的 AI 编程助手。                  │
│                                                             │
│  💡 试试这些命令开始：                                        │
│     • "分析这个项目的架构"                                    │
│     • "帮我写一个用户登录的 API"                              │
│     • "这段代码有什么问题？"                                  │
│     • /help 查看帮助                                         │
│                                                             │
└─────────────────────────────────────────────────────────────┘

> 你想做什么？

第三步：与 AI 协作

# 示例对话
> 帮我创建一个 Express REST API，包含用户的 CRUD 操作

🤖 好的，我来帮你创建。首先让我了解一下项目结构...

[调用工具: glob] 扫描项目文件...
[调用工具: read_file] 读取 package.json...
[调用工具: write_file] 创建 src/routes/users.js...
[调用工具: write_file] 创建 src/controllers/userController.js...
[调用工具: shell] 安装依赖 express...

✅ 已创建用户 CRUD API，包含以下文件：
   - src/routes/users.js
   - src/controllers/userController.js
   - src/models/User.js

启动服务器：npm run dev

📋 CLI 命令参考

全局选项

dvcode [options]

选项	简写	说明
--model <name>	-m	指定 AI 模型
--prompt <text>	-p	非交互模式，执行单次提示
--prompt-interactive <text>	-i	执行提示后进入交互模式
--sandbox	-s	在沙箱环境中运行（增强安全性）
--debug	-d	启用调试模式，输出详细日志
--all-files	-a	在上下文中包含所有项目文件
--yolo	-y	YOLO 模式：自动执行所有操作，无需确认
--continue	-c	继续上次会话
--session <id>		恢复指定 ID 的会话
--list-sessions		列出所有可用会话
--workdir <path>		指定工作目录
--version	-v	显示版本号
--help	-h	显示帮助信息

使用示例

# 基本启动
dvcode

# 使用 Gemini 2.0 Flash 模型
dvcode -m gemini-2.0-flash

# 执行单次任务（非交互）
dvcode -p "为 src/utils.ts 添加单元测试"

# 继续上次会话
dvcode -c

# YOLO 模式（危险：自动执行所有操作）
dvcode -y

# 调试模式
dvcode -d

# 指定工作目录
dvcode --workdir /path/to/project

# 列出所有会话
dvcode --list-sessions

# 恢复特定会话
dvcode --session abc123

⚡ 交互式斜杠命令

在交互模式下，使用以 / 开头的命令快速执行操作：

核心命令

命令	说明
/help	显示帮助信息和快速入门指南
/help-ask	AI 智能帮助助手，解答使用问题
/issue <描述>	提交 GitHub Issue（自动附带错误日志）
/quit 或 /exit	退出应用，显示会话统计

会话与模型

命令	说明
/session	会话管理：list / new / select <id> / rebuild
/model [name]	切换 AI 模型，不带参数显示选择对话框
/compress	压缩对话历史，减少 Token 消耗
/stats	显示会话统计信息

工具与扩展

命令	说明
/tools [nodesc]	查看可用工具列表
/mcp [subcommand]	MCP 服务器管理：add / auth / refresh
/memory	长期记忆管理：show / add / refresh

工作模式

命令	说明
/plan [on|off]	计划模式：只讨论不修改代码
/yolo [on|off]	YOLO 模式：自动执行所有操作
/vim	切换 Vim 编辑模式

文件与编辑

命令	说明
/restore [id]	恢复文件到检查点状态
/refine <text>	文本润色，支持 --tone / --lang / --level
/trim-spaces [on|off]	配置是否自动删除行末空格
/copy	复制最后一条 AI 回复到剪贴板

界面与设置

命令	说明
/clear	清空终端屏幕
/theme	主题选择对话框
/editor	编辑器配置对话框
/about	显示系统和应用信息

调试控制台

DeepV Code 提供增强的调试控制台功能，通过 Ctrl+O 快捷键实现三状态循环：

快捷键	状态	说明
Ctrl+O (第1次)	📊 全部日志	打开调试控制台，显示所有日志信息
Ctrl+O (第2次)	⚠️ 仅错误	过滤显示错误日志，显示黄色 [ERRORS ONLY] 标识
Ctrl+O (第3次)	🚫 关闭	关闭调试控制台

功能特点：

• 🎯 智能过滤：自动识别错误、异常、堆栈跟踪等关键信息
• 🎨 视觉提示：错误模式显示醒目的黄色标识
• ⚡ 快速切换：一键在全部日志和错误过滤间切换
• 🔍 错误高亮：自动检测并显示错误关键词和堆栈信息

账户与认证

命令	说明
/auth	身份认证管理
/account	账户信息和余额查看

项目配置

命令	说明
/init	初始化项目配置文件 DEEPV.md
/hooks	查看 Hooks 钩子机制帮助文档
/ide	IDE 集成管理（VS Code 模式下可用）

🏗️ 项目架构

DeepV Code 采用现代化的 Monorepo 架构，确保代码一致性和高效协作。

目录结构

DeepVCode/
│
├── 📁 packages/                     # 核心包目录
│   │
│   ├── 📁 cli/                      # 命令行界面包
│   │   ├── src/
│   │   │   ├── commands/            # 斜杠命令实现
│   │   │   ├── ui/                  # 终端 UI 组件 (React Ink)
│   │   │   │   ├── components/      # 可复用 UI 组件
│   │   │   │   ├── dialogs/         # 对话框组件
│   │   │   │   └── themes/          # 主题配置
│   │   │   ├── services/            # 服务层
│   │   │   ├── auth/                # 客户端认证
│   │   │   └── utils/               # 工具函数
│   │   └── package.json
│   │
│   ├── 📁 core/                     # 核心功能库
│   │   ├── src/
│   │   │   ├── tools/               # AI 工具集
│   │   │   │   ├── shell.ts         # Shell 命令执行
│   │   │   │   ├── read-file.ts     # 文件读取
│   │   │   │   ├── write-file.ts    # 文件写入
│   │   │   │   ├── edit.ts          # 文件编辑 (replace)
│   │   │   │   ├── glob.ts          # 文件搜索
│   │   │   │   ├── grep.ts          # 内容搜索
│   │   │   │   ├── web-fetch.ts     # 网页抓取
│   │   │   │   ├── web-search.ts    # Google 搜索
│   │   │   │   ├── task.ts          # 子 Agent 任务
│   │   │   │   └── ...
│   │   │   ├── mcp/                 # MCP 引擎
│   │   │   ├── prompts/             # Prompt 模板
│   │   │   ├── auth/                # 认证模块
│   │   │   ├── hooks/               # Hooks 系统
│   │   │   ├── skills/              # Skills 扩展
│   │   │   ├── services/            # 核心服务
│   │   │   ├── config/              # 配置管理
│   │   │   └── utils/               # 工具函数
│   │   └── package.json
│   │
│   ├── 📁 vscode-ide-companion/     # VS Code CLI 伴侣扩展
│   │   ├── src/
│   │   │   └── extension.ts         # 扩展入口
│   │   └── package.json
│   │
│   └── 📁 vscode-ui-plugin/         # VS Code 完整 UI 插件
│       ├── src/                     # 扩展源码
│       ├── webview/                 # React Webview 前端
│       └── package.json
│
├── 📁 docs/                         # 文档目录
│   ├── architecture.md              # 架构设计
│   ├── hooks-user-guide.md          # Hooks 使用指南
│   ├── mcp-improvements-summary.md  # MCP 集成说明
│   └── ...
│
├── 📁 scripts/                      # 构建和工具脚本
│   ├── build.js                     # 主构建脚本
│   ├── build_package.js             # 包构建
│   ├── clean.js                     # 清理脚本
│   └── ...
│
├── 📄 package.json                  # 根配置 (Workspaces)
├── 📄 tsconfig.json                 # TypeScript 配置
├── 📄 eslint.config.js              # ESLint 配置
├── 📄 esbuild.config.js             # esbuild 打包配置
├── 📄 DeepV_Code_Whitepaper.md      # 产品白皮书
├── 📄 DEEPV.md                      # 项目 AI 开发规范
└── 📄 LICENSE                       # Apache 2.0 许可证

技术栈详解

类别	技术	说明
语言	TypeScript 5.x	强类型，提升代码质量
运行时	Node.js 20+	现代 JavaScript 运行时
CLI UI	React + Ink	声明式终端 UI 框架
构建	esbuild	极速打包，毫秒级构建
测试	Vitest	现代化单元测试框架
代码规范	ESLint + Prettier	统一代码风格
包管理	npm Workspaces	Monorepo 管理
AI SDK	@google/genai	Google Gemini API
MCP	@modelcontextprotocol/sdk	MCP 协议实现

交互流程

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   用户输入   │────▶│  CLI 包     │────▶│  Core 包    │
│  (终端)     │     │  (UI/交互)   │     │  (业务逻辑)  │
└─────────────┘     └─────────────┘     └──────┬──────┘
                                               │
                    ┌──────────────────────────┼──────────────────────────┐
                    │                          │                          │
                    ▼                          ▼                          ▼
            ┌─────────────┐           ┌─────────────┐            ┌─────────────┐
            │  AI Model   │           │   Tools     │            │    MCP      │
            │  (Gemini)   │           │ (Shell/File)│            │  Servers    │
            └─────────────┘           └─────────────┘            └─────────────┘

🔌 VS Code 扩展

DeepV Code 提供两个 VS Code 扩展，满足不同使用场景：

📡 IDE Companion（CLI 伴侣）

轻量级扩展，让 VS Code 与终端中运行的 CLI 无缝连接。

功能：

• 感知当前打开的文件
• 获取选中的代码片段
• 与 CLI 实时同步工作区状态

构建方法：

cd packages/vscode-ide-companion

# 安装依赖
npm install

# 构建
npm run build

# 打包为 .vsix
npm run package

🎨 UI Plugin（图形化插件）

完整功能的图形化 AI 编码助手。

功能：

• 📱 侧边栏 AI 对话窗口
• 🖱️ 右键菜单代码操作
  • 解释选中代码
  • 优化代码
  • 生成单元测试
  • 添加到当前对话
• ✨ 代码内联补全建议
• 🔌 MCP 服务器状态管理
• 📜 自定义规则管理
• ⏪ 版本历史和回滚

构建方法：

cd packages/vscode-ui-plugin

# 安装扩展依赖
npm install

# 构建 Webview 前端（首次需要）
cd webview
npm install
npm run build
cd ..

# 构建扩展
npm run build

# 打包为 .vsix
npm run package

安装扩展：

• 打开 VS Code
• 按 Ctrl+Shift+P (Windows/Linux) 或 Cmd+Shift+P (macOS)
• 输入 "Install from VSIX"
• 选择生成的 .vsix 文件

🛠️ 内置工具系统

DeepV Code 的 AI 通过工具系统与外部环境交互。所有工具都经过精心设计，确保安全性和可控性。

文件操作工具

工具	说明	安全级别
read_file	读取文件内容，支持文本、图片、PDF、Excel、Word	🟢 只读
read_many_files	批量读取多个文件，支持 glob 模式	🟢 只读
write_file	创建新文件或覆盖写入	🟡 需确认
replace	精准替换文件中的特定内容	🟡 需确认
delete_file	删除文件（会保存备份以便恢复）	🔴 需确认

搜索工具

工具	说明	安全级别
glob	按模式搜索文件名，支持 **/*.ts 等模式	🟢 只读
grep	在文件内容中搜索正则表达式 (ripgrep)	🟢 只读
ls	列出目录内容	🟢 只读

命令执行

工具	说明	安全级别
shell	执行 Shell 命令 (bash/powershell)	🔴 需确认

网络工具

工具	说明	安全级别
web_fetch	抓取网页内容，支持本地和远程 URL	🟢 只读
web_search	Google 搜索	🟢 只读

高级工具

工具	说明	安全级别
task	启动代码分析子 Agent	🟢 只读
mcp_tool	调用 MCP 服务器提供的工具	🟡 视工具而定
todo_write	管理任务列表	🟢 只读
memory	保存/读取长期记忆	🟢 只读

代码质量工具

工具	说明	安全级别
read_lints	读取代码 Linter 错误	🟢 只读
lint_fix	自动修复 Linter 错误	🟡 需确认

🔗 MCP 协议支持

Model Context Protocol (MCP) 是 DeepV Code 实现深度上下文理解的核心协议。

什么是 MCP？

MCP 允许 AI 模型：

• 连接外部数据源和工具
• 获取实时信息
• 与第三方服务交互

配置 MCP 服务器

在项目根目录创建 .deepvcode/settings.json：

方式一：标准模式（通过命令启动）

适用于本地 MCP 服务器，通过命令行启动进程。

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-filesystem", "/path/to/allowed/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token"
      }
    }
  }
}

字段说明：

• command（必需）：启动服务器的命令
• args（可选）：命令参数数组
• env（可选）：环境变量对象
• cwd（可选）：工作目录
• timeout（可选）：请求超时（毫秒）
• trust（可选）：信任服务器，跳过确认
• includeTools（可选）：白名单，仅启用指定工具
• excludeTools（可选）：黑名单，排除指定工具

方式二：Streamable HTTP 模式（推荐用于云服务）

适用于支持 HTTP 的远程 MCP 服务器，无需本地启动进程。

{
  "mcpServers": {
    "Web-Search-by-Z.ai": {
      "httpUrl": "https://open.bigmodel.cn/api/mcp-broker/proxy/web-search/mcp",
      "headers": {
        "Authorization": "Bearer **************************"
      }
    },
    "myHttpServer": {
      "httpUrl": "https://api.example.com/mcp/endpoint",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "Custom-Header": "custom-value"
      }
    }
  }
}

Streamable HTTP 模式字段说明：

• httpUrl（必需）：MCP 服务器的 HTTP 端点 URL
• headers（可选）：HTTP 请求头对象，用于认证或传递自定义信息
  • 常用认证方式：Authorization: Bearer <token>
• 其他字段（includeTools、excludeTools、trust 等）同样适用

两种模式对比：

特性	标准模式	Streamable HTTP 模式
连接方式	本地启动进程	HTTP 请求
适用场景	本地 MCP 服务器	云服务、远程 MCP
配置复杂度	需要配置命令、路径	只需 URL 和可选 Headers
资源占用	本地进程资源	无本地进程
网络要求	无需网络	需要网络连接

管理 MCP 服务器

# 查看所有 MCP 服务器状态
/mcp

# 添加新服务器
/mcp add github

# 刷新服务器连接
/mcp refresh github

# 进行 OAuth 认证
/mcp auth github

🤖 自定义模型支持

DeepV Code 支持配置 OpenAI 兼容格式和 Anthropic Claude API 格式的自定义模型，让你可以使用任何兼容的 AI 服务。

为什么使用自定义模型？

• 🔓 自由选择 - 使用你最喜爱的 AI 服务商
• 💰 成本控制 - 直接向服务商付费，无需通过中间商
• 🏠 本地部署 - 支持本地模型（LM Studio, Ollama 等）
• 🚀 灵活配置 - 根据需求调整参数和端点

快速配置

方式一：使用模型管理界面（推荐）

在 CLI 中输入：

/model

然后选择 "Model Management"（模型管理）选项，按向导提示填写：

• 选择提供商类型（OpenAI Compatible / Anthropic Claude）
• 输入显示名称
• 输入 API 基础 URL
• 输入 API 密钥（推荐使用环境变量格式 ${OPENAI_API_KEY}）
• 输入模型 ID
• 设置最大 Token 数（可选）
• 确认配置

方式二：手动编辑配置文件

编辑 ~/.deepv/custom-models.json：

{
  "models": [
    {
      "displayName": "GPT-4 Turbo",
      "provider": "openai",
      "baseUrl": "https://api.openai.com/v1",
      "apiKey": "${OPENAI_API_KEY}",
      "modelId": "gpt-4-turbo",
      "maxTokens": 128000,
      "enabled": true
    },
    {
      "displayName": "Claude Sonnet",
      "provider": "anthropic",
      "baseUrl": "https://api.anthropic.com",
      "apiKey": "${ANTHROPIC_API_KEY}",
      "modelId": "claude-sonnet-4-5",
      "maxTokens": 200000,
      "enabled": true
    }
  ]
}

支持的提供商

OpenAI Compatible (openai)

适用于任何遵循 OpenAI Chat Completions 格式的 API：

• OpenAI 官方 API

  {
    "displayName": "GPT-4 Turbo",
    "provider": "openai",
    "baseUrl": "https://api.openai.com/v1",
    "apiKey": "${OPENAI_API_KEY}",
    "modelId": "gpt-4-turbo"
  }
  

• Azure OpenAI

  {
    "displayName": "Azure GPT-4",
    "provider": "openai",
    "baseUrl": "https://your-resource.openai.azure.com/openai/deployments/your-deployment",
    "apiKey": "${AZURE_OPENAI_KEY}",
    "modelId": "gpt-4",
    "headers": {
      "api-version": "2024-02-01"
    }
  }
  

• 本地模型（LM Studio, Ollama）

  {
    "displayName": "Local Llama",
    "provider": "openai",
    "baseUrl": "http://localhost:1234/v1",
    "apiKey": "not-needed",
    "modelId": "llama-3-70b"
  }
  

• 第三方服务（Groq, Together AI 等）

  {
    "displayName": "Groq Llama 3",
    "provider": "openai",
    "baseUrl": "https://api.groq.com/openai/v1",
    "apiKey": "${GROQ_API_KEY}",
    "modelId": "llama-3-70b-8192"
  }
  

Anthropic Claude (anthropic)

适用于 Claude API 端点，支持扩展思考功能：

{
  "displayName": "Claude Sonnet (Thinking)",
  "provider": "anthropic",
  "baseUrl": "https://api.anthropic.com",
  "apiKey": "${ANTHROPIC_API_KEY}",
  "modelId": "claude-sonnet-4-5",
  "enableThinking": true
}

配置字段说明

必需字段：

字段	说明	示例
displayName	显示名称	GPT-4 Turbo
provider	提供商类型	openai 或 anthropic
baseUrl	API 基础 URL	https://api.openai.com/v1
apiKey	API 密钥	${OPENAI_API_KEY}
modelId	模型名称	gpt-4-turbo

可选字段：

字段	说明	默认值
maxTokens	最大上下文窗口	视提供商而定
enabled	是否启用	true
headers	额外 HTTP 请求头	无
timeout	请求超时（毫秒）	300000
enableThinking	启用 Anthropic 扩展思考	false

使用自定义模型

通过模型选择对话框

/model

自定义模型会显示 [Custom] 标签和青色，使用方向键选择。

直接切换

/model custom:openai:gpt-4-turbo@abc123

环境变量设置

推荐使用环境变量存储 API 密钥：

Linux/macOS：

export OPENAI_API_KEY="sk-your-key-here"
export ANTHROPIC_API_KEY="sk-ant-your-key-here"

Windows PowerShell：

$env:OPENAI_API_KEY="sk-your-key-here"
$env:ANTHROPIC_API_KEY="sk-ant-your-key-here"

特性与限制

✅ 支持的功能：

• 流式和非流式响应
• 工具调用（Function Calling）
• 多模态输入（文本、图片）
• 与 DeepV Code 所有功能集成

⚠️ 注意：

• 自定义模型不消耗 DeepV 积分
• 需直接向 API 提供商付费
• 某些高级功能可能因提供商限制而不可用
• Token 计数由提供商决定

相关文档

• 📖 自定义模型快速入门
• 📖 自定义模型完整指南
• 📖 自定义模型架构说明

🪝 Hooks 钩子机制

Hooks 允许你在关键工作流节点注入自定义逻辑。

配置 Hooks

在 .deepvcode/settings.json 中添加：

{
  "hooks": {
    "preToolExecution": [
      {
        "matcher": { "toolName": "write_file" },
        "action": {
          "type": "shell",
          "command": "echo 'About to write file: $TOOL_ARGS'"
        }
      }
    ],
    "postToolExecution": [
      {
        "matcher": { "toolName": "write_file", "exitCode": 0 },
        "action": {
          "type": "shell",
          "command": "npm run lint -- --fix $FILE_PATH"
        }
      }
    ]
  }
}

使用场景

• 自动格式化 - 文件写入后自动运行 Prettier
• 代码检查 - 修改代码后自动运行 ESLint
• 提交验证 - 执行 Shell 命令前检查分支
• 日志记录 - 记录所有工具调用

相关文档

• 📖 Hooks 使用指南
• 📖 Hooks 架构设计
• 📖 Hooks 示例

⚙️ 配置文件

项目配置 DEEPV.md

在项目根目录创建 DEEPV.md，为 AI 提供项目特定的上下文和规范：

# 项目概述
这是一个基于 React + TypeScript 的前端项目...

# 技术栈
- React 18
- TypeScript 5
- Vite
- TailwindCSS

# 代码规范
- 使用函数组件和 Hooks
- 命名使用 camelCase
- 组件文件使用 PascalCase

# 目录结构说明
- src/components/ - 可复用组件
- src/pages/ - 页面组件
- src/hooks/ - 自定义 Hooks
- src/utils/ - 工具函数

使用 /init 命令可以自动生成初始配置。

用户配置 .deepvcode/settings.json

{
  "preferredModel": "gemini-2.0-flash",
  "theme": "dark",
  "trimSpaces": true,
  "mcpServers": {},
  "hooks": {}
}

🧑‍💻 开发指南

环境准备

# 确保 Node.js 版本 >= 20
node --version

# 克隆仓库
git clone https://github.com/OrionStarAI/DeepVCode.git
cd DeepVCode

# 安装依赖
npm install

常用命令

命令	说明
npm install	安装所有依赖
npm run build	构建所有包
npm run dev	开发模式运行（带调试）
npm run test	运行所有测试
npm run lint	代码风格检查
npm run lint:fix	自动修复代码风格
npm run format	格式化代码 (Prettier)
npm run typecheck	TypeScript 类型检查
npm run clean	清理构建产物和缓存
npm run pack:prod	生产环境打包
npm run pack:vscode	打包 VS Code 插件

开发流程

• 修改代码 - 在相应的 packages/*/src 目录下修改
• 构建 - 运行 npm run build
• 测试 - 运行 npm run dev 本地测试
• 检查 - 运行 npm run lint && npm run typecheck
• 提交 - 确保测试通过后提交代码

调试技巧

# 启用调试模式
npm run debug

# 启用文件日志
LOG_TO_FILE=true npm run dev

# 查看详细日志
FILE_DEBUG=1 npm run dev

调试控制台功能

Ctrl+O 三状态循环：

• 第1次：打开调试控制台，显示全部日志
• 第2次：切换到仅错误模式，显示黄色 [ERRORS ONLY] 标识
• 第3次：关闭调试控制台

智能错误过滤：自动识别并显示错误、异常、堆栈跟踪等关键信息，帮助开发者快速定位问题。

添加新工具

• 在 packages/core/src/tools/ 创建工具文件
• 实现工具接口
• 在 tool-registry.ts 注册工具
• 添加单元测试

❓ 常见问题

安装问题

Q: npm install 失败，提示权限错误

A: 尝试以下方法：

# 方法 1: 使用 --unsafe-perm
npm install -g deepv-code --unsafe-perm

# 方法 2: 修改 npm 全局目录权限
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH

Q: 提示 Node.js 版本过低

A: DeepV Code 需要 Node.js 20+。使用 nvm 管理版本：

nvm install 20
nvm use 20

使用问题

Q: 如何切换 AI 模型？

A: 使用 /model 命令或启动时指定：

# 交互模式
/model gemini-2.0-flash

# 启动时指定
dvcode -m gemini-2.0-flash

Q: 如何继续之前的会话？

A: 使用 -c 参数或 /session 命令：

# 继续最近会话
dvcode -c

# 列出所有会话
/session list

# 选择特定会话
/session select 1

Q: YOLO 模式是什么？

A: YOLO 模式下，AI 的所有操作会自动执行，无需用户确认。⚠️ 谨慎使用！

# 启用
dvcode -y
# 或
/yolo on

🤝 贡献指南

我们欢迎社区贡献！无论是 Bug 修复、新功能还是文档改进。

贡献流程

• Fork 本仓库
• 创建特性分支

  git checkout -b feature/AmazingFeature
  

• 提交改动

  git commit -m 'feat: add some amazing feature'
  

• 推送分支

  git push origin feature/AmazingFeature
  

• 提交 Pull Request

提交规范

使用 Conventional Commits 规范：

• feat: 新功能
• fix: Bug 修复
• docs: 文档更新
• style: 代码格式
• refactor: 重构
• test: 测试相关
• chore: 构建/工具

报告问题

发现 Bug 或有功能建议？请 创建 Issue，包含：

• 问题描述
• 复现步骤
• 期望行为
• 环境信息（OS、Node 版本等）

⭐ Star History

🗺️ 路线图

短期目标 (v1.x)

• 优化 MCP 上下文理解能力
• 扩展工具系统，支持更多场景
• 增强 VS Code 插件体验
• 支持更多 AI 模型

中期目标 (v2.x)

• 多模态支持（图表、设计稿）
• 深度架构分析和设计辅助
• 开放插件生态系统
• 团队协作功能

长期愿景

• 自主学习和进化
• 预测开发需求
• 全自动化软件工程

📄 许可证与法律信息

本项目基于 Apache License 2.0 开源。

📄 Legal
License	Apache License 2.0
Terms of Service	Terms & Privacy
Privacy Policy	Privacy Policy
Security	Security Policy

Copyright 2025 DeepV Code Team

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

🔗 相关链接

资源	链接
🌐 官方网站	https://dvcode.deepvlab.ai
📦 npm 包	https://www.npmjs.com/package/deepv-code
📖 白皮书	DeepV_Code_Whitepaper.md
🐛 问题反馈	GitHub Issues
💬 讨论区	GitHub Discussions

💬 "AI 不只是工具，更是每位开发者的伙伴。"

⭐ 如果这个项目对你有帮助，请给我们一个 Star！⭐

🪄 Happy Coding with DeepV Code! 💻✨

Made with ❤️ by DeepV Code Team