DeepSeek-cli

DeepSeek-cli v2.2.0

全异步、高可扩展的 AI 聊天服务后端，支持多模型适配、增量流式 Markdown 渲染、工具调用系统、上下文压缩和终端交互界面。

快速开始

1. 安装依赖

项目使用 Python ≥ 3.9。

方式一：一键安装（推荐）

# 安装全部核心依赖
pip install httpx Pygments beautifulsoup4 chardet aiofiles qrcode \
            Pillow psutil PyYAML typing_extensions

# 可选加速（推荐）
pip install orjson h2

# 安装开发依赖（测试 / 代码检查 / 提交钩子）
pip install pytest pytest-asyncio pytest-xdist pytest-cov ruff mypy pre-commit orjson h2

方式二：通过项目安装（自动读取 pyproject.toml，推荐）

# 安装核心依赖
pip install .

# 核心依赖 + 高性能 JSON / HTTP2
pip install ".[perf,http2]"

# 安装开发依赖（测试/代码检查等）
pip install ".[dev]"

依赖库说明：

包 · 用途 · 必需 httpx · HTTP 请求库 · ✅ Pygments · 代码语法高亮 · ✅ beautifulsoup4 · HTML 抓取解析（web_fetch） · ✅ chardet · 字符编码检测（read） · ✅ aiofiles · 异步文件操作 · ✅ qrcode · 终端二维码生成（微信 ClawBot 登录） · ✅ Pillow · 图像解码/归一化（read_image、图片上传） · ✅ psutil · 状态栏 CPU/内存、Shell 探测（缺失时回退平台实现） · ✅ PyYAML · 插件清单 / 技能 frontmatter（缺失时回退内置 YAML 子集解析） · ✅ typing_extensions · Python < 3.11 的 dataclass_transform 支持 · ✅（<3.11） orjson · 高性能 JSON 编解码（缺失时回退标准库 json） · 可选 h2 · HTTP/2 支持（配置 enable_http2 生效前提） · 可选

可选依赖缺失时程序仍可运行，只是对应能力降级（由 pip install ".[perf,http2]" 启用）。

Cygwin / MSYS2 平台限制：orjson（Rust 扩展，无该平台 wheel）、psutil（上游

setup.py 明确拒绝 cygwin）、ruff（Rust 二进制，无该平台 wheel）在该平台没有可安装的

发行版，requirements*.txt 与 pyproject.toml 已用 sys_platform 标记跳过，程序按上表

自动降级；Pillow 在该平台锁 8.4.0（9.5+ 源码构建在 jpeg 探测阶段失败）；pre-commit

按 Python 版本锁定（3.9/3.10 → 4.3.0，≥3.11 → 4.7.0）。

2. 配置

方式一：配置文件 + 模型选择器（推荐）

LLM 访问参数（API 密钥 / 接口地址 / 模型名 / 提供商）的唯一来源是模型档案 （model_profiles）——首次运行未配置档案时会自动打开模型选择器引导配置 （/models 可随时打开；新增只需三步：① 选提供商 → ② 选/填模型名（可从该 提供商内置模型列表 ↑↓ 选择，也可输入自定义名）→ ③ 填 API 密钥）。

创建配置文件 ~/.chat_config/chatrc.json：

{
    "model_profiles": [
        {
            "provider": "deepseek",
            "model": "deepseek-v4-flash",
            "api_key": "sk-你的API密钥",
            "base_url": "https://api.deepseek.com/v1/chat/completions",
            "name": "DeepSeek Flash",
            "temperature": "0.3",
            "reasoning_effort": "high",
            "multimodal": "true"
        }
    ],
    "active_model_profile": 0,
    "reasoning_effort": "max",
    "temperature": 0.2,
    "thinking_enabled": true,
    "max_context_chars": 3000000,
    "max_output_chars": 1000000,
    "max_retries": 10,
    "retry_base_sec": 30,
    "empty_response_max_retries": 0,
    "max_session_messages": 0,
    "keep_recent_messages": 0,
    "theme": "dark",
    "max_context_tokens": 1000000,
    "summary_token_budget": 100000,
    "auto_force_compress_threshold": 600000,
    "enable_notifications": true,
    "notify_on_chat_completion": true,
    "image_upload_optimize": true,
    "image_upload_keep_recent": 4,
    "image_upload_max_dimension": 1568,
    "image_upload_quality": 80,
    "mcp_servers": [],
    "performance": {
        "http_client": {
            "connect_timeout": 30,
            "read_timeout": 120,
            "write_timeout": 120,
            "max_connections": 100,
            "max_connections_per_host": 20,
            "keep_alive_timeout": 15,
            "enable_pool": true,
            "enable_http2": true
        }
    }
}

• model_profiles：模型档案列表（每个档案含 provider / model / api_key /

base_url / name，以及可选的 temperature（0.0~2.0）与 reasoning_effort（low / medium / high / max）；base_url 留空则用提供商 默认地址；生成参数留空则沿用全局 temperature / reasoning_effort 默认值）。

• thinking_enabled：思考模式开关（默认 true）。Ctrl+T 可随时切换并

持久化；关闭时 DeepSeek V4 请求注入 thinking.type=disabled（官方默认 enabled，必须显式关闭），状态栏模型名后显示 [off]。也可用 /config set thinking_enabled false 或 python chat.py config set thinking_enabled false 设置。 温度与该开关联动：官方文档明确「思考模式不支持 temperature」（设置 不报错但会被忽略），因此思考模式开启时请求不携带 temperature（/models 温度字段标注「思考模式开启，不生效」），关闭思考模式后再发送并生效； presence_penalty / frequency_penalty 同理。 multimodal（"true" / "false"，默认 "false"）声明该模型是否支持 多模态读图：true 时才会向模型加载 read_image 工具，false 时该工具不 进入工具集、执行也会被拒绝（在 /models 界面「多模态读图」字段设置）。

• active_model_profile：当前生效档案下标（由模型选择器写入，-1 = 未选择）。
• empty_response_max_retries：模型返回完全空响应（无正文/无推理/无工具

调用）时的自动重发上限。0（默认）= 无限重试，直到拿到有效回答或用户 ESC 中断——空响应不是「调用失败」而是「没拿到回答」，请求健康、尚未渲染 任何内容、重发幂等安全，因此不占用 `max_retries` 瞬时错误预算，也 不输出错误（连续多次未恢复时给一条弱提示）；等待按 2→4→8→15 秒封顶。 >0 = 有界重试（内部调用方如压缩摘要、SubAgent 恒为有界，快速失败）。

配置文件位于 ~/.chat_config/chatrc.json，首次运行时自动创建（使用默认值）。

方式二：环境变量

仅流式输出节奏类参数支持环境变量覆盖（LLM 访问参数已不再支持环境变量—— API 密钥 / 接口地址 / 模型名 / 提供商只能通过模型档案配置）：

环境变量 · 说明 · 示例 CHAT_STAGGER_MIN_DELAY · 流式输出最小延迟 · export CHAT_STAGGER_MIN_DELAY="0.1" CHAT_STAGGER_MAX_DELAY · 流式输出最大延迟 · export CHAT_STAGGER_MAX_DELAY="0.5"

已移除：CHAT_API_KEY / CHAT_BASE_URL / CHAT_MODEL / CHAT_LOW_MODEL

以及 RC 旧键 api_key / base_url / model / provider / low_model /

models（加载配置时自动清理）。

支持的多模型 Provider

Provider · 适配器 · 说明 deepseek · DeepSeekAdapter · DeepSeek 官方 API（默认）。内置模型：deepseek-flash（V4.1 Flash，最新一代、原生多模态视觉）、deepseek-v4-pro（V4-Pro 旗舰）；旧名 deepseek-v4-flash / deepseek-v4-flash-vision-exp 已下线并由 V4.1 Flash 承接（保留以兼容旧配置）。deepseek-chat / deepseek-reasoner 已退役 custom · OpenAICompatAdapter · 任意 OpenAI 兼容 API（OpenAI / 通义千问 / 本地 Ollama 的 OpenAI 兼容端点等），自动检测 reasoner 模型 anthropic · AnthropicAdapter · Anthropic Claude 系列模型（API 格式自动转换）。内置模型：claude-opus-5-5（默认，官方推荐）、claude-sonnet-5-5、claude-haiku-5-5、claude-fable-5-1、claude-opus-5、claude-sonnet-5、claude-haiku-4-5-20251001、claude-opus-4-8、claude-sonnet-4-6 glm · OpenAICompatAdapter · 智谱 GLM（open.bigmodel.cn）。内置模型：glm-5.3（默认，旗舰）、glm-5.3-flash / glm-5.3-flashx（原生多模态）、glm-5.2、glm-5.1、glm-5、glm-4.7 mimo · OpenAICompatAdapter · 小米 MiMo（token-plan-cn）。内置模型：mimo-v2.6-pro（默认）/ mimo-v2.6-flash / mimo-v2.6-pro-ultraspeed（全模态理解）；mimo-v2.5-pro / mimo-v2.5 将于 2026-10-21 下线（保留候选便于迁移）

上表「内置模型」即 /models 新增档案时「模型名」字段的候选来源（随各提供商

官方最新模型更新，候选行标注「默认」与计费单价；deepseek / anthropic 为

美元 / 百万 tokens，glm / mimo 以人民币计价故不内置单价）；候选之外仍可

直接键入任意自定义模型名。

模型名以 ollama 开头时按 OllamaAdapter 路由（本地 Ollama 部署，默认

localhost:11434）；该路由由模型名决定，不需要 provider: ollama。

3. 启动

交互式对话（默认）

python chat.py

启动终端交互界面，进入多轮对话。

单次问答模式

python chat.py -p "你好，请介绍一下自己"

输入一句话，大模型回答完成后立即退出，适合脚本调用。

从保存的会话恢复

python chat.py --load <会话ID>

指定模型

python chat.py -m deepseek-v4-pro      # 按模型名匹配已有「模型档案」并设为当前
python chat.py --model deepseek-v4-pro

LLM 访问参数唯一来源 = 模型档案，因此 -m / --model 只能选择已有档案 （按档案的 model 或 name 匹配）——档案不存在时会列出可用档案并提示先运行 /models 新增。

多模态视觉（deepseek-flash）

deepseek-flash（DeepSeek V4.1 Flash）是 DeepSeek 最新一代模型，原生支持 多模态视觉理解，图片按 token 计费。旧模型名 deepseek-v4-flash 与 deepseek-v4-flash-vision-exp 已下线，请求统一路由到 V4.1 Flash（按相同 单价计费，同样具备视觉能力）。接入方式：

# 先确保模型档案中有该模型（/models 界面新增，或 config set model_profiles），
# 再按名选择：
python chat.py -m deepseek-flash

该模型支持两种图片输入方式（图片仅支持出现在用户消息中）：

1. 用户消息直接传图：在输入中携带本地图片路径、`` 或

裸 http(s) 图片 URL，CLI 自动转换为图片 content blocks（本地图片自动 base64 内联，URL 原样传递）：

分析 /path/to/screenshot.png 里的报错信息
   看下 ![架构图](https://example.com/diagram.png)

拖动文件输入路径：把文件从文件管理器拖入终端窗口（输入框），终端会把

路径文本注入为「粘贴」——CLI 自动识别并规范化为干净路径（去引号、还原

反斜杠转义、解析 file:// URI、Cygwin/MSYS 下把 Windows 路径转为 POSIX

路径），多文件每行一个、含空格路径用双引号包裹；非路径文本（自然语言、

代码）原样输入不受影响。图片路径因此同样可直接拖入传图。

关闭：python chat.py config set tui_drop_path_normalize false。

1. read_image 工具（按模型开关加载）：模型档案的「多模态读图」

（multimodal）为 true 时才向该模型加载 read_image 工具；为 false 时工具不进入工具集、执行也会被拒绝。开启后 AI 代理可主动调用 read_image 读取本地图像（DSH 对齐：路径参数 file_path；支持全部 Pillow 可解码格式，无扩展名按文件内容识别；自动应用 EXIF 方向并规范化为 8-bit sRGB；大图自动降采样到 2048×2048 总像素预算 / 4 MiB 目标，返回文本给出原尺寸与坐标换算倍数；图片字节持久化到内容寻址附件库， 工具结果返回附件引用）。本项目保留分块/灰度/旋转/翻转/缩放扩展。 在 /models 编辑模型档案的「多模态读图」字段即可切换（默认 false）。

上传前图片瘦身（默认开启）：图片随会话历史累积，而每轮 API 请求都会

重传整个历史（发送副本会把附件引用展开为 base64 data URI），图片一多

请求体便随图片数量线性膨胀（实测 6 张 1080p 截图 ≈ 47MB/请求），表现为

"图片多了每次都很卡"。客户端在发送副本上自动做三件事：

① 折叠——仅保留最近 image_upload_keep_recent 张图片，更早的图片块替换为

文本占位；② 压缩——超过 image_upload_max_dimension 长边或体积阈值的图片

降采样并重编码为 JPEG；③ 编码缓存——同一图片不重复解码/编码。

该优化不改动会话存档、TUI 显示与 read_image 的附件引用（存档保留

引用，发送副本才展开为 data URI）。

```bash