deepseek-cli

DeepSeek-cli v2.2.0

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

---

快速开始

1. 安装依赖

项目使用 Python ≥ 3.9。

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

# 安装全部核心依赖
pip install httpx rich Pygments Jinja2 beautifulsoup4 chardet aiofiles qrcode

# 安装开发依赖（测试/代码检查等）
pip install pytest pytest-asyncio pytest-xdist pytest-cov ruff mypy

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

# 安装核心依赖
pip install .

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

依赖库说明：

2. 配置

方式一：配置文件（推荐）

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

{
    "provider": "deepseek",
    "api_key": "sk-你的API密钥",
    "model": "deepseek-v4-flash",
    "reasoning_effort": "max",
    "temperature": 0.2,
    "base_url": "https://api.deepseek.com/v1/chat/completions",
    "max_context_chars": 60000,
    "max_output_chars": 3000,
    "max_retries": 10,
    "retry_base_sec": 30,
    "max_session_messages": 0,
    "keep_recent_messages": 0,
    "theme": "dark",
    "max_context_tokens": 60000,
    "summary_token_budget": 2000,
    "auto_force_compress_threshold": 60000,
    "enable_notifications": true,
    "notify_on_chat_completion": true,
    "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
        }
    }
}

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

方式二：环境变量

部分配置项支持通过环境变量覆盖：

环境变量优先级高于配置文件。

支持的多模型 Provider

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

通过 -m / --model 临时覆盖配置文件中的模型，不影响配置文件。

多模态视觉（deepseek-flash）

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

python chat.py -m deepseek-flash

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

1. 用户消息直接传图：在输入中携带本地图片路径、![描述](图片路径或URL) 或 裸 http(s) 图片 URL，CLI 自动转换为图片 content blocks（本地图片自动 base64 内联，URL 原样传递）：

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

2. read_image 工具：AI 代理可主动调用 read_image 工具读取本地图像 （支持分块/灰度/旋转/翻转/缩放操作），多模态模型直接看到 base64 图片 （图片按原始尺寸返回，不做自动缩放）。

非多模态模型下，用户消息中的图片引用保持纯文本原样传递（模型不可见图片）。 如有多模态模型未被内置模式识别，可通过配置扩展：

python chat.py config set multimodal_models '["my-vision-model"]'

详细日志模式

python chat.py -v           # INFO 级别日志
python chat.py -vv          # DEBUG 级别日志

会话管理

python chat.py session list                   # 列出所有保存的会话
python chat.py session delete <会话ID>        # 删除指定会话
python chat.py session export <会话ID>        # 导出会话（打印到 stdout）
python chat.py session export <会话ID> -o chat.json  # 导出到文件

查看版本

python chat.py --version
python chat.py version

完整命令一览

3.5 微信 ClawBot 远程控制（clawbot）

通过微信官方 ClawBot 插件协议（iLink Bot API）实现远程发命令 + 结果显示：

python chat.py clawbot              # 启动（复用缓存凭证或扫码登录）
python chat.py clawbot --re-login   # 强制重新扫码登录

登录：终端会直接渲染微信官方登录二维码（手机扫码即可，无需打开文件），扫码确认后自动进入监听模式。

远程发命令（在微信里给 ClawBot 发消息）：

安全配对：首次发消息的用户需回复终端打印的配对码完成授权，之后该用户的所有命令都被处理；已授权用户持久化在 ~/.chat_config/clawbot_allowed.json。

其他说明：

• 每个微信用户有独立会话（LRU 上限 20 个），结果分段回显到微信
• 输入状态指示（"正在输入"）自动发送/取消
• iLink 连接有效期 24 小时，到期前自动提醒并支持扫码重连

4. 快捷操作（终端交互模式下）

以下快捷键仅在终端交互式对话（python chat.py）中生效。

5. 斜杠命令（终端交互模式下）

在对话输入框中以 / 开头输入命令：

SubAgent 聊天记录持久化：每个 SubAgent 的完整内部对话（system 提示词 / 任务指令 / 助手回复 / 工具调用与结果）会在其运行结束时记录到父 Agent，并随会话自动保存到 .chat/msg_list/<id>.json 的 subagents 字段；/load 加载会话时同步恢复， /export 导出 markdown 时一并包含。

工具系统（Tool System）

AI 代理在对话中可调用以下工具完成各类操作。共 19 个内置工具，涵盖文件操作、代码搜索、网络请求、用户交互等能力。

工具列表

工具分类

工具设计原则

• 纯异步 — 所有工具均基于 asyncio，不阻塞事件循环
• 沙盒安全 — 文件操作自动备份，支持撤回（undo）
• 元数据系统 — 每工具声明并行安全、网络依赖、超时估计等元数据，供调度层优化
• 双端适配 — 同时支持终端（display()）渲染路径

工具权限系统（v2.2.0+）

不同 SubAgent 类型对工具有不同的访问权限，通过 Func.can_use() 统一检查：

@classmethod
def can_use(cls, tool_name: str, agent_type: str = "execute", path: str | None = None) -> tuple[bool, str | None]:
    """检查指定类型的 agent 能否使用某工具。"""

• agent_type 注入 — SubAgent 在 _handle_tool_calls() 中自动注入 func.agent_type = self.agent_type
• 排除规则 — 定义在 src/core/subagent.py 的 _TOOL_EXCLUSION_MAP（详见下方 SubAgent 类型表）
• 路径白名单 — FileToolBase._validate_path_and_size() 对 plan Agent 实施路径限制，仅允许写入 .chat/plan/ 目录，防止误写项目源码

光标坐标追踪系统（CursorTracker）

新增于 v2.2.0，全局统一的终端光标坐标追踪基础设施，消除分散在各渲染组件中的坐标推算累积误差。

核心 API

集成架构

ChatUIConsumer
  └── CursorTracker（唯一实例，构造注入到所有子系统）
        ├── ContentRenderer   → _do_content / _do_tool_output 等 14 种渲染后调用 record_newlines()
        ├── RenderEngine       → _phase_render 记录渲染坐标范围，position_cursor 同步最终光标
        ├── _BottomBar         → force_redraw / sync_bottom_lines / ensure_cursor_* 中 set 光标位置
        └── _CompletionPopup   → render / render_cycle_update 中 set 弹窗行坐标

设计决策

• 单线程使用 — 仅在 render 线程中操作，无需锁
• 1-based 坐标 — 与终端 ANSI CUP 序列一致
• 轻量无依赖 — 仅标准库，零外部依赖
• 检查点模式 — save/restore 支持嵌套渲染场景的坐标回退

Agent 工作流程

本项目的核心是 Main-Sub Agent 架构，通过 subagent 委派任务给不同类型的子 Agent。

┌──────────────────────────────────────────────────────────────────┐
│                         Main Agent                               │
│                   主控 Agent，负责任务调度（6 步工作流）                 │
│                                                                  │
│  ① 规划 ─→ ② 探底分析 ─→ ③ 修改执行 ─→ ④ 审查 ─→ ⑤ 验证（完成）│
└───────┬───────┬───────┬───────┬───────┘
        │       │       │       │
        │dispatch│dispatch│dispatch│dispatch
        ▼       ▼       ▼       ▼
┌─────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────────┐
│ plan        │ │ map        │ │ review     │ │ execute      │
│ SubAgent    │ │ SubAgent   │ │ SubAgent   │ │ SubAgent     │
│             │ │            │ │            │ │              │
│ 计划型      │ │ 只读分析型  │ │ 代码审查型  │ │ 执行型       │
│             │ │            │ │            │ │              │
│ • 任务拆解  │ │ • 项目探底 │ │ • P0-P3    │ │ • 读/写文件  │
│ • 依赖分析  │ │ • 模块地图 │ │   分级审查  │ │ • 修改代码   │
│ • 资源估算  │ │ • 调用链   │ │ • 循环审查  │ │ • 创建文件   │
│ • 风险识别  │ │ • 引用关系 │ │ • 阻断策略  │ │ • 测试运行   │
│ • 动态重规划│ │            │ │            │ │ • 执行验证   │
└─────────────┘ └────────────┘ └────────────┘ └──────────────┘

工作流说明

1. 规划 ──→  委派 plan SubAgent 制定结构化计划（任务拆解、依赖分析、风险评估）
     │
2. 探底 ──→  委派 map SubAgent 获取模块地图 + 调用链分析
     │         （只读分析，不修改代码）
     │
3. 修改 ──→  基于探底结果执行代码修改
     │         多个独立目标可并发派发 execute SubAgent
     │
4. 审查 ──→  委派 review SubAgent 逐文件审查
     │         P0/P1/P2 阻断修复，P3 纳入记录
     │         最多三轮循环审查
     │
5. 验证 ──→  语法检查 → 构建/编译 → 加测试 → 运行测试 → 运行验证

SubAgent 类型

各类型 SubAgent 通过 _TOOL_EXCLUSION_MAP（定义在 src/core/subagent.py）控制工具可用性。

工具排除策略（与 src/core/subagent.py 的 _TOOL_EXCLUSION_MAP 一致）：execute 排除 subagent/subagent_opt/user_select/web_search；map 排除 bash/bash_opt/write_file/update_file/rm/mv/cp/mkdir/web_search/subagent/subagent_opt/user_select；review 排除 bash/bash_opt/write_file/update_file/rm/mv/cp/mkdir/subagent/subagent_opt/user_select（纯只读审查：仅 read_file/search/find/ls/web_search，无任何 shell 执行能力）；plan 排除 bash/bash_opt/rm/mv/cp/subagent/subagent_opt/user_select，write_file/update_file/mkdir 仅限 .chat/plan/ 目录。subagent_opt 与后台 subagent 均仅主 Agent 独有：SubAgent 工具白名单全类型排除 + 工具运行时 isinstance(agent, SubAgent) 双保险。SubAgent 在 _handle_tool_calls() 中注入 agent_type 到 Func 实例，Func.can_use() 进行统一检查。FileToolBase._validate_path_and_size() 额外实施 plan Agent 路径白名单校验。

并发调度策略

多个独立分析/审查任务同时触发时，同轮并发派发多个 SubAgent（如同时分析多个模块、同时审查多个文件），互不阻塞，缩短总执行时间。

目录结构

├── chat.py                # 入口脚本（asyncio.run(main())）
├── pyproject.toml         # 项目配置与依赖
├── prompts/               # 系统提示词（6 个文件）
│   ├── prompts_export_main.md    # 主 Agent 系统提示词
│   ├── prompts_export_main_empty.md  # 主 Agent 系统提示词（精简/空版本）
│   ├── prompts_export_map.md     # map SubAgent 探底提示词
│   ├── prompts_export_plan.md    # plan SubAgent 计划提示词
│   ├── prompts_export_execute.md  # execute SubAgent 提示词
│   ├── prompts_export_review.md  # review SubAgent 审查提示词

├── tests/                 # 测试（按模块划分，覆盖各功能域）
├── .chat/                 # 运行时数据目录（首次运行自动创建）
│   ├── memory/            # 跨对话记忆系统（索引 + 详情）
│   ├── plan/              # Plan Agent 计划文件
│   └── msg_list/          # 会话消息存储（JSON 格式）
│
├── src/                   # 核心源码
│   ├── app.py             # 入口 re-export
│   ├── app_init/          # 应用初始化（参数解析、模式选择）
│   ├── app_loop/          # 交互式/单次模式主循环
│   ├── application.py     # 应用层编排（Application、AppMode）
│   ├── chat_msgs.py       # 对话消息存/取/列/导出
│   ├── checkpoint.py      # 任务断点保存与恢复
│   ├── paths.py           # 路径常量
│   ├── terminal.py        # 终端颜色配置（始终启用颜色）
│   ├── _compat.py         # Python 版本兼容（dataclass/aclosing/get_event_loop）
│   │
│   ├── api/               # API 适配层
│   │   ├── client_async.py    # httpx 异步 HTTP 客户端
│   │   ├── model_async.py     # 模型调用入口 + 重试
│   │   ├── interrupt_async.py # 全局中断信号
│   │   ├── stream/            # 流式输出处理（含推理/工具调用/速度）
│   │   ├── stream_parse.py    # 流式工具调用解析
│   │   ├── tokens.py          # Token 启发式估算
│   │   ├── stats.py           # 会话级 Token 统计
│   │   ├── json_repair.py     # JSON 格式自动修复
│   │   ├── protocols.py       # LLM 协议定义
│   │   ├── telemetry.py        # API 层可观测性
│   │   ├── escape_monitor.py   # 键盘输入监听
│   │   ├── events.py           # API 事件定义
│   │   ├── _model_loops.py / _stats_core.py / _stream_lifecycle.py / _token_speed.py / _tool_parse_utils.py  # 内部辅助模块
│   │   ├── multimodal.py       # 多模态模型判定 + 图片 content blocks 构造（read_image 依赖）
│   │   ├── adapters/          # 多模型适配器（DeepSeek/OpenAI/Anthropic/Ollama）
│   │   └── _adapter_manager.py   # 适配器管理
│   │
│   ├── config/            # 配置系统
│   │   ├── loader.py          # 配置加载/持久化（~/.chat_config/chatrc.json）
│   │   ├── defaults.py        # 默认配置 + Provider 定义
│   │   └── schema.py          # 配置校验
│   │
│   ├── core/               # 核心业务逻辑
│   │   ├── agent.py           # Agent 对话代理（Pipeline 驱动）
│   │   ├── base_agent.py      # Agent 基类（消息管理、沙盒上下文）
│   │   ├── agent_di.py        # Agent 依赖注入工厂
│   │   ├── agent_builder.py   # Agent 构建器
│   │   ├── session.py         # ChatSession 纯领域会话对象（状态机驱动）
│   │   ├── state_machine.py   # 会话状态机（INIT→IDLE→RUNNING→COMPLETED/INTERRUPTED）
│   │   ├── subagent.py        # SubAgent 子代理（含 _TOOL_EXCLUSION_MAP 工具权限策略）
│   │   ├── pipeline.py        # Pipeline 中间件管道（Model-Execute 循环编排）
│   │   ├── compression.py     # 上下文压缩（策略模式）
│   │   ├── context_manager.py # 上下文管理器 + 消息上限控制
│   │   ├── context_selector.py / context_summarizer.py
│   │   ├── message_queue.py   # MessageQueue 异步消息队列
│   │   ├── message_edit.py    # 消息编辑功能
│   │   ├── file_change_record.py # 文件变更记录
│   │   ├── sandbox_manager.py # 文件沙盒管理器
│   │   ├── parallel_executor.py # ParallelExecutor 并行 SubAgent 调度
│   │   ├── tool_executor_async.py # AsyncToolExecutor 异步工具执行器
│   │   ├── tool_dag.py        # 工具 DAG 调度
│   │   ├── cache.py           # 增量统计缓存
│   │   ├── constants.py       # 主题常量
│   │   ├── commands/          # 命令系统（base / _ui_adapter / plugins/）
│   │   ├── exceptions.py      # 异常定义
│   │   ├── internal/          # 内部实现子模块
│   │   │   ├── agent/         # Agent 内部（spawner / callbacks / capture）
│   │   │   ├── shared/        # 共享工具（sandbox_history / stats_cache）
│   │   │   ├── session/       # 会话内部（persistence / messages）
│   │   │   └── commands/      # 命令内部（_command_core / _config_cmd / _data_cmd / _session_cmd）
│   │   ├── events/            # 核心事件总线 + 事件类型
│   │   ├── middleware/        # Pipeline 中间件（审计/中断/状态机/可观测性/工具适配器）
│   │   ├── ports/             # 六边形架构端口定义（8 个端口）
│   │   └── telemetry/         # 可观测性（指标/追踪/上下文传播）
│   │
│   ├── tui/                # 终端 UI 聊天渲染引擎（替代 chat_ui/）
│   │   ├── _assembly.py / _assembly_steps.py / _base_display.py / _completion.py / _completion_engine.py
│   │   ├── _config.py / _const.py / _consumer.py / _diff_renderer.py / _dispatcher.py / _format.py
│   │   ├── _input.py / _input_io.py / _input_parser.py / _input_buffer.py / _input_dispatcher.py
│   │   ├── _input_layout.py / _input_metrics.py / _input_orchestrator.py / _ink_bridge.py / _lifecycle.py
│   │   ├── _screen.py / _snapshot.py / _stdout_tracker.py / _subagent_panel.py / _subagent_render.py
│   │   ├── _subagent_state.py / _tool_icons.py / _width.py / input.py / _history_disk.py / _system_monitor.py
│   │   ├── app/               # AppModel + apply_cmd + 组件树（input_area/status_bar/toolcard/...）
│   │   ├── consumer/          # ChatUIConsumer 事件消费者 + 渲染入口
│   │   ├── core/              # 核心工具（color/style/singleton/_fx/_theme）
│   │   ├── events/            # UI 事件总线 + DisplayEvent 类型定义
│   │   ├── ink/               # React Ink 风格组件框架（调和器/flexbox/hooks/渲染器）
│   │   ├── pipeline/          # 消息编辑/显示管道
│   │   ├── state/             # 消费/注册表状态管理
│   │   └── subagent/          # SubAgent 面板子域聚合门面
│   │
│   ├── renderer/           # 增量流式 Markdown 渲染引擎
│   │   ├── engine.py          # RenderEngine 渲染引擎
│   │   ├── pipeline.py        # TokenPipeline 过滤器链
│   │   ├── recursive_parser.py # 递归下降解析器
│   │   ├── types.py           # Token/TokenType/RenderContext 类型
│   │   ├── states.py          # 渲染状态
│   │   ├── factory.py         # 渲染器工厂
│   │   ├── protocols.py       # 渲染协议
│   │   ├── output.py          # OutputAdapter 输出适配器
│   │   ├── indicator.py       # 流式指示器
│   │   ├── ast/               # AST 构建→扁平化→优化→渲染
│   │   ├── handlers/          # 块级元素处理器（code/table/mermaid/math/admonition 等）
│   │   ├── targets/           # 渲染目标抽象（RenderTarget / CompositeRenderTarget）
│   │   │   ├── __init__.py
│   │   │   └── base.py
│   │   │
│   │   ├── pipeline_filters/  # 流式优化过滤器
│   │   ├── math_symbols/      # 数学符号定义
│   │   ├── _rendering/        # 内部渲染辅助
│   │   └── _utils/            # 内部工具函数
│   │
│   ├── tools/              # 工具调用系统（19 个内置工具）
│   │   ├── base.py            # Func 基类 + 元数据系统（含 can_use 工具可用性检查 / agent_type）
│   │   ├── file_base.py       # FileToolBase 文件操作基类（含 plan agent 路径白名单）
│   │   ├── registry.py        # 工具注册表（自动发现 + 调度 + 元数据索引）
│   │   ├── read_file.py / write_file.py / update_file.py / read_image.py
│   │   ├── search.py / find.py / ls.py
│   │   ├── bash.py / cp.py / mv.py / rm.py / mkdir.py / skill_tool.py
│   │   ├── web_search.py / web_fetch.py / user_select.py / subagent.py / subagent_opt.py
│   │   ├── file_ops.py        # 文件操作原子工具（原子写入、路径安全校验、沙盒记录）
│   │   ├── _constants.py      # 共享常量（排除目录、安全路径、编码等）
│   │   ├── encoding.py        # 编码检测工具函数
│   │   ├── utils.py           # 工具通用辅助函数
│   │   ├── search_providers.py  # DeepSeek 官方原生搜索提供者（web_search 依赖）
│   │   └── page_fetcher.py    # 网页内容抓取（web_fetch 依赖）
│   │
│   ├── prompt_builder/     # 系统提示词构建
│   ├── notifications/      # 桌面通知（Termux/Linux/Windows）
│   └── observability/      # 可观测性门面（聚合指标/追踪/遥测日志）

六边形架构（Ports & Adapters）

核心层通过 8 个端口接口 访问基础设施，实现依赖倒置——核心层不直接依赖 api、tui、chat_msgs 等具体实现模块，基础设施层通过适配器模式实现这些端口。

设计原则：所有端口均为 Protocol 或抽象基类，核心层仅依赖端口接口，不感知具体实现。测试时可通过 Mock 适配器替换基础设施，实现核心逻辑的独立单元测试。

事件系统

核心事件总线（src/core/events/）

通用事件发布/订阅系统，支持通配符订阅和优先级排序。定义 16 种事件类型：

特性：通配符订阅（如 model.* 匹配所有模型事件）、优先级排序（EventPriority 枚举，LOWEST→HIGHEST）、不可变事件数据类（frozen dataclass）。

UI 事件总线（src/tui/events/）

显示层事件系统，定义 24 种 DisplayEvent 类型（生命周期/工具调用/Agent 状态/模型阶段/流式内容/附加状态/通用输出/用户交互），基于 CoreEventBus 底层发布机制实现。DisplayEventBus 对 DisplayEvent 子类提供类型安全包装，与核心事件（字符串类型）并行独立运作，确保终端共享相同的事件语义。

Pipeline 中间件管道

Pipeline 将 Agent 对话循环编排为可插拔中间件链。中间件按注册顺序依次执行，每个钩子可拦截/增强/跳过特定阶段。

中间件列表（5 个）

前往 GitHub