集成 Deep Code

Deep Code 是一款专为 DeepSeek-V4 系列模型深度适配的开源终端 AI 编程助手，原生支持深度思考模式、推理强度自定义调节、Agent Skills 扩展等特性，与同类型工具相比，无需额外协议适配即可完全发挥 DeepSeek V4 的全部能力，同时支持与 Deep Code VSCode 扩展共享配置，实现终端与IDE的体验一致。其核心优势包括轻量快速、多模态输入支持、技能生态开放，是 DeepSeek 用户的首选终端编程工具之一。

本教程将指导你完成 Deep Code 的安装与配置，阅读完成后你将能够在终端内使用 DeepSeek V4 的全部特性，通过自定义技能大幅提升编码效率。

• GitHub： https://github.com/lessweb/deepcode-cli

1. 安装 Deep Code

操作目的：全局安装 Deep Code CLI 工具，实现系统任意路径下的快速调用。 前置环境检查：Deep Code 依赖 Node.js 18+ 版本，该版本首次原生支持 fetch API 与 ES 模块特性，低版本会出现运行时错误。执行 node -v 确认版本 ≥ v18.0.0，若版本不符合要求，建议通过 nvm 安装适配版本。

• 安装 Node.js 18+ 版本。
• 在终端中运行以下命令：

npm install -g @vegamo/deepcode-cli

国内用户优化：npm 下载速度慢可追加淘宝镜像参数：npm install -g @vegamo/deepcode-cli --registry=https://registry.npmmirror.com 权限问题解决：Linux/macOS 提示权限不足可追加 sudo，Windows 用户需以管理员身份运行 PowerShell。 安装失败排查：若安装过程中出现依赖错误，可先执行 npm install -g npm 升级 npm 到最新版本后重试。

• 验证安装是否成功：

deepcode --version

预期结果：执行命令后正常输出版本号（如 v0.7.1）即表示安装成功。

2. 配置 Deep Code

操作目的：配置 Deep Code 的核心参数，包括模型选择、API 凭证、推理特性等，该配置与 Deep Code VSCode 扩展完全共享，一次配置多端生效。 前置操作：若 ~/.deepcode 目录不存在，先执行 mkdir -p ~/.deepcode（Linux/macOS）或手动创建该目录，用于存放配置文件与对话历史。

创建 ~/.deepcode/settings.json 文件，填入你的 DeepSeek API Key 和模型配置：

{
  "env": {
    "MODEL": "deepseek-v4-pro",
    "BASE_URL": "https://api.deepseek.com",
    "API_KEY": "sk-..."
  },
  "thinkingEnabled": true,
  "reasoningEffort": "max"
}

从 DeepSeek 开放平台 获取你的 API Key。

注意： 此配置文件与 Deep Code VSCode 扩展 共享。 安全提示：请勿将该配置文件提交至公开代码仓库，避免泄露 API Key；可将 ~/.deepcode 目录加入全局 .gitignore 避免误提交。

配置选项说明：

验证方法：配置完成后执行 deepcode config list，可查看当前生效的配置项，确认所有参数填写正确。

3. 进入项目目录并启动 Deep Code

操作目的：进入目标项目目录，Deep Code 会自动扫描项目下的代码、配置文件、.deepcode 目录下的项目级技能，实现项目级上下文感知。

cd /path/to/my-project
deepcode

预期结果：启动后进入 Deep Code 交互式界面，提示你输入问题。可输入测试指令（如「帮我优化当前目录下 utils.js 中的防抖函数，添加立即执行选项与类型定义」），若能正常返回结果即表示配置成功。

快捷键

Deep Code 提供了丰富的快捷键提升操作效率，各快捷键功能说明如下：

使用 Agent Skills

Agent Skills 是 Deep Code 的核心扩展能力，通过自定义提示词模板，你可以将高频使用的任务封装为技能，避免每次重复输入大段提示词，大幅提升操作效率。

Agent Skills 从以下位置自动发现：

• 用户级别： ~/.agents/skills/<name>/SKILL.md 所有项目通用，适合封装通用任务（如代码审查、单元测试生成、文档编写等）
• 项目级别： ./.deepcode/skills/<name>/SKILL.md 仅当前项目生效，适合封装项目特有任务（如公司代码规范检查、部署流程生成等）

按 / 键打开技能选择器，或直接输入技能名称（例如 /skill-writer）即可快速调用对应技能。

技能示例：你可以创建 ~/.agents/skills/code-review/SKILL.md 文件，内容如下：

你是资深前端代码审查专家，请按照以下要求审查提供的代码：
1. 检查是否存在性能问题、安全漏洞、语法错误
2. 检查是否符合编码规范与最佳实践
3. 给出具体的优化建议与代码示例

后续只需输入 /skill-code-review 即可直接调用该技能，无需重复输入上述提示词。

注意事项与避坑指南

1. 配置文件格式错误：若启动后提示配置加载失败，检查 settings.json 的 JSON 格式是否正确，是否存在多余逗号、引号不匹配等问题。
2. 图片粘贴失败：仅支持 PNG、JPG 等常见图片格式，单张图片大小请勿超过 10MB，否则会出现上传失败问题。
3. 深度思考模式响应慢：开启深度思考模式后，模型需要生成完整的推理过程，响应时间会比普通模式长2-3倍，属于正常现象；若追求速度可将 reasoningEffort 调整为 high 或关闭 thinkingEnabled。
4. 技能不显示：检查技能文件路径是否正确，必须严格放在 skills/<name>/SKILL.md 路径下，文件名区分大小写，必须为 SKILL.md。

常见问题（FAQ）

1. 对话历史丢失怎么办？

   • 解决方案：Deep Code 会自动保存所有对话历史到 ~/.deepcode/history 目录下，使用 /resume 命令即可选择并恢复任意历史对话。

2. 上下文被截断怎么办？

   • 解决方案：DeepSeek V4 支持 1M 上下文窗口，若仍出现截断，可将问题拆分为多个子问题分次提问，或删除不必要的上下文信息后重试。

3. 联网搜索功能不生效怎么办？

   • 排查步骤：确认 webSearchTool 配置为 true，且网络可正常访问公共搜索引擎；部分网络环境可能限制搜索功能，可切换网络后重试。

参考资料

• awesome-deepseek-agent：可查看更多 DeepSeek 生态的 Agent 工具与最佳实践。