一、DeepX-Code 是什么？

DeepX-Code（项目名 deepx）是一款基于DeepSeek模型、兼容OpenAI接口的终端编程Agent。它的核心定位是：

• 单二进制文件：无需安装Node.js、Python等运行时环境
• 缓存友好：长会话场景下提示缓存命中率约99%，极大节省API调用成本
• 内置代码图谱：支持符号级跳转、调用关系查询，替代传统grep搜索
• 本地OCR能力：基于PaddleOCR，支持离线识别截图中的文字
• 多模型路由：支持DeepSeek、小米MiMo、Kimi、通义千问等主流模型

---

二、系统要求

DeepX-Code支持主流操作系统，无特殊硬件要求：

操作系统	支持版本
Windows	Windows 10/11（PowerShell 5.0+）
macOS	10.15+
Linux	主流发行版（Ubuntu 18.04+, CentOS 7+）

---

三、安装教程

3.1 在Windows系统上安装

打开PowerShell（以管理员身份运行），执行以下命令：

$env:SOURCE='gitee'; irm https://gitee.com/itmisx/deepx-code/raw/main/scripts/install.ps1 | iex

说明：使用 SOURCE='gitee' 参数会从Gitee镜像源下载，适合国内用户加速安装。

安装成功后，DeepX-Code会被安装到 %LOCALAPPDATA%\Programs\deepx 目录，并自动添加到系统PATH环境变量中。

3.2 在macOS/Linux上安装

打开终端，执行以下命令：

# 使用GitHub源（国际用户）
curl -fsSL https://raw.githubusercontent.com/itmisx/deepx-code/main/scripts/install.sh | bash && exec $SHELL

# 使用Gitee镜像（国内用户）
curl -fsSL https://gitee.com/itmisx/deepx-code/raw/main/scripts/install.sh | SOURCE=gitee bash && exec $SHELL

安装后，deepx 命令会被放置在 ~/.local/bin/ 目录下，且该目录已自动加入PATH环境变量。

3.3 验证安装

安装完成后，在终端执行以下命令验证是否安装成功：

deepx --version

如果输出版本号信息（如 v0.2.98），则说明安装成功。

---

四、卸载与更新

4.1 卸载DeepX-Code

Windows系统

在PowerShell中执行：

# 删除程序文件
Remove-Item -Recurse -Force 'C:\Users\<你的用户名>\AppData\Local\Programs\deepx'

# 删除配置文件
Remove-Item -Recurse -Force "C:\Users\<你的用户名>\.deepx"

或者使用通用路径（注意替换 admin 为你的实际用户名）：

Remove-Item -Recurse -Force 'C:\Users\admin\AppData\Local\Programs\deepx', "C:\Users\admin\.deepx"

注意：删除配置文件 .deepx 会清除所有配置信息，包括API Key和会话历史。

macOS/Linux系统

rm -f ~/.local/bin/deepx && rm -rf ~/.deepx

4.2 更新DeepX-Code

DeepX-Code内置了自动更新功能，你可以在任意终端执行：

deepx upgrade

该命令会自动检测最新版本并完成更新，无需手动下载安装包。

---

五、首次使用与配置

5.1 进入项目目录并启动

在终端中切换到你的项目目录：

cd <你的项目目录>

推荐：在VS Code中直接使用内置终端（快捷键 Ctrl + `` ），它会自动定位到当前打开的项目根目录。

启动DeepX-Code的交互式界面：

deepx

5.2 配置API Key

首次启动时，会弹出配置向导：

1. 选择模型供应商：使用键盘的 ← 和 → 方向键切换，可选供应商包括：

   • DeepSeek（推荐，缓存友好）
   • 小米 MiMo
   • Kimi
   • 通义千问
   • Custom（自定义OpenAI兼容端点）

2. 输入API Key：根据选择的供应商，输入对应的API Key

3. 配置保存：配置会被自动保存到 ~/.deepx/model.yaml 文件中

如果你想后续修改配置，可以在DeepX-Code的交互界面中使用 /config 命令重新配置。

---

六、核心功能使用指南

6.1 交互式编程（TUI模式）

启动 deepx 后，你会进入一个全屏终端交互界面。你可以像和AI对话一样，用自然语言下达编程任务。

示例任务：

帮我创建一个计算器函数，支持加减乘除运算，并编写对应的单元测试

DeepX-Code会自动：

• 分析任务复杂度
• 选择合适的模型（flash/pro自动路由）
• 调用必要的工具（Read、Write、Bash等）
• 在需要时请求用户确认（审核模式默认开启）

6.2 非交互式执行（Exec模式）

当你需要将DeepX-Code集成到CI/CD流程或脚本中时，可以使用 exec 模式：

# 单次任务执行
deepx exec "将main.go中的错误处理改为使用errors包的新特性"

# 从管道读取数据
cat error.log | deepx exec "分析这段错误日志，给出修复建议"

# 输出重定向
deepx exec "生成项目的README文档" > README.md

exec 模式的特点是：

• 只输出最终结果，不显示中间过程
• 适合自动化场景
• 执行完成后自动退出

6.3 工作模式切换

DeepX-Code提供了三种工作模式，通过 /working-mode 命令切换：

模式	说明	适用场景
karpathy（默认）	务实工匠模式	日常开发任务
openspec	规格驱动开发	需要严格遵循规格说明的项目
superpowers	全流程严谨模式	关键系统开发、代码审查

使用方法：

/working-mode    # 进入交互选择界面
/working-mode kp # 直接切换到karpathy模式
/working-mode sp # 直接切换到superpowers模式

6.4 模型路由与切换

DeepX-Code支持双模型自动路由：

/model        # 弹出模型选择界面
/model flash  # 强制使用flash模型（经济型）
/model pro    # 强制使用pro模型（高性能型）

自动路由策略会根据任务复杂度智能选择模型，兼顾效果与成本。

6.5 代码图谱（CodeGraph）

CodeGraph是DeepX-Code的核心特色功能，提供符号级代码导航：

操作	说明
跳转定义	查找符号的定义位置
查找调用	找出所有调用某函数的位置
接口实现	查找实现某接口的所有类型
影响面分析	分析修改某符号的影响范围

支持的编程语言：Go、TypeScript、JavaScript、Python、Java、Rust、C/C++、C#、Ruby、PHP、Kotlin、Swift、Scala、Dart等。

6.6 本地OCR能力

DeepX-Code内置PaddleOCR引擎，支持离线识别图片中的文字：

• 首次使用时会自动下载OCR模型（约37MB）
• 支持粘贴图片路径或直接粘贴图片
• 适合识别报错截图、UI设计稿等

使用示例：

# 在对话中发送图片路径
请识别这张截图中的错误信息：./screenshots/error.png

# 或直接粘贴图片

---

七、常用Slash命令速查

命令	功能说明
/plan	切换到计划模式（只读工具）
/auto	切换到全自动模式
/review	切换到审核模式（默认，需人工确认写/执行操作）
/model	切换模型（flash/pro）
/provider	切换模型供应商
/config	重新配置API Key等参数
/sessions	查看历史会话列表
/new	开启全新对话
/compact	手动压缩会话（节省上下文）
/sandbox	配置沙箱模式（native/docker/off）
/workflow	运行可复用的工作流脚本
/help	查看帮助信息
/exit	退出DeepX-Code

---

八、高级特性

8.1 Skills技能系统

DeepX-Code兼容Claude Code的skill目录结构，支持技能复用：

工作区目录/
├── .deepx/
│   └── skills/          # 项目级技能
└── 其他文件/

全局技能目录（优先级顺序）：
~/.agents/skills/
~/.claude/skills/
~/.deepx/skills/

8.2 Workflow工作流

使用JavaScript脚本将多agent流程固化：

// 示例：代码审查工作流
agent("代码审查", { model: "pro" });
pipeline([
  agent("检查代码规范"),
  agent("分析潜在bug"),
  agent("生成改进建议")
]);

运行方式：

/ultracode 描述任务   # 让模型自动生成workflow
/workflow 名称        # 运行指定的workflow
/workflows            # 列出所有可用的workflow

8.3 MCP协议支持

DeepX-Code原生支持MCP（Model Context Protocol）：

/mcp-add      # 添加MCP服务器
/mcp-list     # 列出已添加的MCP服务器
/mcp-delete   # 删除MCP服务器

8.4 沙箱隔离

DeepX-Code提供多种沙箱模式保障安全：

模式	说明
native（默认）	macOS Seatbelt/Linux bubblewrap，写操作限定workspace
docker	Docker容器隔离
off	关闭沙箱（不推荐）

切换方式：

/sandbox native
/sandbox docker ubuntu:22.04
/sandbox off

---

九、常见问题解答

Q1: 安装失败提示权限不足怎么办？

A: 确保以管理员身份运行终端。Windows上右键点击PowerShell选择"以管理员身份运行"；Linux/macOS使用 sudo 或确保对 ~/.local/bin 目录有写入权限。

Q2: 如何查看当前使用的模型和配置？

A: 在交互界面中，右侧状态栏会显示当前模型、模式等信息。也可以使用 /status 命令切换状态栏显示。

Q3: API Key可以存放多个吗？

A: 可以。每次使用 /config 配置新的供应商时，配置会被存档到 ~/.deepx/provider.yaml。之后通过 /provider 命令可以在已配置的供应商间一键切换。

Q4: 会话如何持久化？

A: 所有会话自动以gob二进制格式持久化到 ~/.deepx/sessions/ 目录。重启DeepX-Code后，会自动恢复上次会话，包括工具调用、推理过程等完整上下文。

Q5: 如何节省Token费用？

A: DeepX-Code内置多种优化机制：

• 提示缓存命中率约99%（DeepSeek）
• 本地路由零Token消耗
• 工具不预注入，按需调用
• 代码图谱替代盲搜减少Token浪费

---

十、总结

DeepX-Code作为一款单二进制的终端AI编程助手，通过以下特性显著提升了开发效率：

1. 一键安装：无需配置复杂环境
2. 缓存友好：大幅降低API调用成本
3. 代码图谱：精准的符号级代码导航
4. 本地OCR：离线识别截图文字
5. 多模型支持：灵活切换不同供应商
6. 安全可控：审核模式+沙箱隔离

无论是日常开发、代码审查还是项目探索，DeepX-Code都能成为你可靠的AI编程搭档。

---

相关链接：

• GitHub仓库：https://github.com/itmisx/deepx-code
• Gitee镜像：https://gitee.com/itmisx/deepx-code
• 官方网站：https://itmisx.github.io/deepx-code/

---

📌 温馨提示：本文基于DeepX-Code v0.2.98版本编写，后续版本可能会有功能更新和界面优化，建议定期执行 deepx upgrade 保持最新版本。