内容
dstools — DeepSeek-V4 工具> 为 **DeepSeek** 模型赋予视觉能力。
>
> 一个 [ (模型上下文协议)](modelcontextprotocol.io) 服务器，增强了
> DeepSeek 的文本模型，具备两种原生不具备的能力：
>
> 1. **图像内容理解** — DeepSeek-V4 是一个仅限文本的模型。`dstools` 添加了一个
> 视觉工具，可以将任何图像转换为丰富的结构化文本，V4 模型可以对其进行推理
> （利用其 100 万令牌上下文和世界级的推理能力）。
> 2. **深度研究** — 一个多步骤、基于引文的研究流程，使用 V4 作为
> 计划和合成大脑，连接实时网络搜索和页面提取。
`dstools` 是一个可产品化、可安装的 Python 包。它通过 **stdio** 和
**可流式 HTTP** 发送 MCP支持 MCP 的主机（Claude Code、Claude Desktop、Cherry Studio、自定义代理……）都可以连接到 DeepSeek-V4 后端，并立即调用这些工具。
---
## 为什么存在该项目
Deep4（`deepseek-flash` / `deep4-pro`，发布于6-04-24出色的
文本模型，具有 100 万上下文、强大的智能体/工具调用能力和自动上下文
缓存 — 但官方聊天 API **仅限文本** （无多模态视觉）。`dstools` 正好填补了这一空白：
| DeepSeek-V4 优势 | 缺失功能 | `dstools` 添加功能 |
| --- | --- | --- |
| 100 万上下文，顶级推理 | 无法查看图像 | `analyze_image` → 视觉转文本 |
| 智能体，工具调用 | 无实时网络访问 | `web_search`，`fetch_page`，`deep_research` |
| 自动提示缓存 | — | 稳定前缀提示以最大化缓存命中率 |
| 思考模式（`thinking={"type":"enabled"}`） | — | 选择性地用于硬合成步骤 |
该工具包 **深度适应 V4**：它默认为 `deepseek-v4-pro` 进行合成，
`deepseek-v4-flash` 用于廉价的子步骤，根据调用切换 V4 的原生思考模式，
构造提示以实现缓存命中，并使用 V4 的 JSON 输出模式进行结构化提取。
## 提供的工具
| 工具 | 描述 | 需要密钥？ |
| --- | --- | --- |
| `analyze_image` | 描述/理解图像（路径，URL 或 base64）。返回结构化文本。 | 视觉提供者密钥（或本地模型） |
| `ocr_image` | 从图像中提取文本（OCR）。 | 可选 `pytesseract` |
| `web_search` | 运行网络搜索，返回排名结果（标题，URL，摘要）。 | **否** （DuckDuckGo，无需密钥） |
| `fetch_page` | 获取 URL 并返回干净、易读的 Markdown。 | **否** |
| `deep_research` | 完整流程：计划 → 搜索 → 获取 → 选择 → 合成，附带引文。 | DeepSeek API 密钥 |
粒度工具（`web_search`，`fetch_page`，`analyze_image`）允许主机代理运行其自己的
智能体循环；`deep_research` 是一个一键式编排器，用于需要引文报告的场景。
## 快速入门
```bash
# 1. 安装（Python 3.10+）
uv sync # 或：pip install -e .
# 2. 配置
cp .env.example .env # 然后编辑：设置 DEEPSEEK_API_KEY 和视觉提供者
# 3. 运行 MCP 服务器（stdio — 适用于本地主机，如 Claude Code/Desktop）
uv run dstools serve
# …或通过可流式 HTTP（适用于远程主机）
uv run dstools serve --transport http --port 8000
```
从 Claude Code 连接：
```bash
claude mcp add --transport stdio dstools -- uv run --directory /path/to/dstools dstools serve
```
为 Claude Desktop 提供了现成的 `examples/claude_desktop_config.json` 配置文件。
## 配置
所有设置均为环境变量（支持 `.env`）。合理的默认值意味着无需密钥的部分（搜索 + 获取）开箱即用。
| 变量 | 默认值 | 用途 |
| --- | --- | --- |
| `DEEPSEEK_API_KEY` | — | DeepSeek API 密钥（`deep_research` 需要） |
| `DEEPSEEK_BASE_URL` | `https://api.deepseek.com` | OpenAI 兼容端点 |
| `DEEPSEEK_MODEL` | `deepseek-v4-pro` | 合成/重型模型 |
| `DEEPSEEK_FAST_MODEL` | `deepseek-v4-flash` | 廉价子步骤模型 |
| `DEEPSEEK_THINKING` | `auto` | `auto`/`on`/`off` — V4 硬步骤的思考模式 |
| `DEEPSEEK_REASONING_EFFORT` | `high` | `low`/`medium`/`high` |
| `VISION_BASE_URL` | — | OpenAI 兼容 **视觉** 端点（任何多模态模型） |
| `VISION_API_KEY` | — | 视觉端点密钥 |
| `VISION_MODEL` | — | 例如 `gpt-4o`，`qwen-vl-max`，`glm-4v`，通过 Ollama 的本地 `qwen2.5-vl` |
| `SEARCH_PROVIDER` | `duckduckgo` | `duckduckgo`（无需 / `tavily` |
| `TAVIL_KEY` | — |SEARCH_PROVIDER=tavily` 则需要 |
| `RESEARCH_BREADTH` | `3` | 每轮生成的子查询数 |
| `RESEARCH_DEPTH` | `2` | 研究轮数 |
| `RESEARCH_MAX_SOURCES` | `8` | 获取和合成的页面数 |
| `LOG_LEVEL` | `INFO` | 日志详细程度 |
### 视觉提供者（用于_image`）
Seek-V4 无法查看图像，请将 `VISION_*` 指向任何 OpenAI 兼容的多模态模型：
- **OpenAI**：`VISION_BASE_URL=https://api.openai.com`，`=gpt-4o` / `gpt-4o-mini`
- **阿里巴巴 Qwen-VL** （DashScope，OpenAI 兼容）：`VISION_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1`，`VISION_MODEL=qwen-vl-max`
- **智谱 GLM-4V**：`VISION_BASE_URL=https://open.bigmodel.cn/api/paas/v4`，`VISION_MODEL=glm-4v`
- **本地（Ollama）**：`VISION_BASE_URL=http://localhost:11434/v1`，`VISION_MODEL=qwen2.5-vl`（无需密钥）
如果没有视觉提供者，`analyze_image` 会降级为图像元数据 + OCR（如果安装了 `pytesseract`），并返回明确的注释 — 它永远不会崩溃。
## 开发
```bash
uv sync --extra dev
make lint # ruff
make typecheck # mypy
make test # pytest
make serve # 运行服务器（stdio）
```
## 项目布局
```
src/dstools/
server.py # FastMCP 服务器 + 工具注册
cli.py # `dstools` CLI（serve / inspect / doctor）
config.py # pydantic-settings 配置
llm/ # DeepSeek（OpenAI 兼容）+ 视觉客户端，V4 思考感知
search/ # 可插拔的搜索提供者（默认 DuckDuckGo，可选 Tavily）
web/ # 异步器 + HTML→Markdown 提取
tools/ # 图像 / 搜索 / 获取 / 研究工具
utils/ # 图像 I/O 和编码，文本分块
tests/ # pytest 套件（网络和 LLM 模拟）
examples/ # claude_desktop_config.json，MCP 客户端演示
```
## 许可证
MIT。
