deep-agent-cli

deep-agent 是面向 Linux 和 WSL2 的终端 Coding Agent，基于 Deep Agents 和 LangGraph 构建，支持 OpenAI 兼容模型服务，通过 Bubblewrap 隔离命令执行。工作区默认为启动目录，也可通过配置指定。

当前版本为 0.1.7，处于早期开发阶段。稳定版发布前，配置格式、会话存储格式和 Python API 可能出现不兼容变更。

功能

• 代码与文件：目录浏览、读取、编辑、写入、删除，以及默认正则搜索。
• 命令执行与审批：使用会话内的持久沙箱；默认 ask 模式在命令执行、文件变更和 Web 搜索前等待审批。
• 模型与上下文：支持 Chat Completions / Responses、流式思考与回答、模型和推理强度切换、自动与手动上下文压缩。
• 交互控制：运行中追加指令、排队后续任务、暂停、取消，以及结构化人工输入。
• 会话与附件：按工作区保存 SQLite 会话，支持恢复；具备图片输入能力的模型可接收图片附件。
• 项目扩展：加载 ~/.deep-agent/skills/ 中的 Skills 和工作区根目录的 AGENTS.md；配置 Tavily key 后提供 web_search。
• HTTP 服务：可选服务复用 Runner，提供文字任务、SSE、审批、人工输入与恢复。接口范围见 HTTP 服务。

运行要求

• Linux 或 WSL2；原生 Windows、macOS 和 WSL1 不支持 Bubblewrap 沙箱。
• Python 3.12+；CI 覆盖 Python 3.12 和 3.13。
• Bubblewrap 及可用的非特权 user namespace；Ubuntu / WSL2 的限制与处理见 沙箱排查。
• 支持 Chat Completions 或 Responses 的模型端点及相应凭据。
• CLI 需要交互式终端；非交互接入使用 HTTP 服务 或 Python API。

ripgrep（rg）由项目的 ripgrep-bin Python 依赖自动安装，无需默认执行系统安装步骤。定位顺序为当前 Python 环境 scripts 目录、系统 PATH、Python 正则回退；运行时不自动下载二进制或修改 PATH。备选安装与验证见 正则搜索。

安装

Debian / Ubuntu：

sudo apt install pipx bubblewrap
pipx ensurepath
# 重新打开终端后安装
pipx install deep-agent-cli
deep-agent --version

系统默认 Python 低于 3.12 时，可指定已安装的解释器，不替换发行版的 /usr/bin/python3：

pipx install --python /path/to/python3.12 deep-agent-cli

也可使用虚拟环境：

python3.12 -m venv ~/.venvs/deep-agent
~/.venvs/deep-agent/bin/pip install deep-agent-cli
~/.venvs/deep-agent/bin/deep-agent --version

升级现有 pipx 安装：

pipx upgrade deep-agent-cli

快速开始

1. 生成配置

deep-agent

未指定 DEEP_AGENT_CONFIG 且默认配置不存在时，首次运行创建 ~/.deep-agent/config.yaml 和 Skills 目录，然后退出。已存在的配置不会被模板覆盖。

2. 配置模型

在 ~/.deep-agent/config.yaml 中配置模型端点。以下示例与默认配置模板一致，通过 TOKEN_PLAN_API_KEY 环境变量读取密钥：

llm:
  default: token-plan/qwen3.8-flash
  models:
    token-plan:
      base_url: https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
      api_key: ${TOKEN_PLAN_API_KEY}
      api: chat_completions
      reasoning_efforts: [none, low, medium, xhigh]
      models:
        qwen3.8-flash:
          input: [text, image]
          context_window: 1m

llm.default 使用“来源/模型”标识。模型项省略的字段继承来源级配置，模型级配置可覆盖来源级配置。使用其他端点时，应同步调整端点、密钥、模型 ID、输入模态、上下文窗口和推理强度；api 省略时默认为 responses，不会按模型名或 URL 自动判断协议。完整字段与服务商示例见 配置参考。

3. 在项目目录启动

cd ~/projects/my-app
deep-agent

启动时检查配置与沙箱。默认在沙箱不可用时拒绝启动；宿主执行回退需要显式授权，见 沙箱与权限。主配置、Skills 和按键配置目录必须位于工作区之外，因此不能将家目录或其上层目录作为工作区。

终端界面接受自然语言任务，以 / 开头的输入用于调用 CLI 命令。

4. 恢复会话

deep-agent resume           # 选择已保存的会话
deep-agent resume 01a08aae   # 替换为已有会话的 ID 或前缀

恢复加载会话状态，不自动继续未完成任务。仅支持当前会话数据库结构，不自动迁移旧格式。取消不会回滚已经发生的文件修改或外部副作用，恢复后需核对实际状态。

常用操作

完整命令、按键、排队、长消息、Skills、显示和取消行为见 终端界面。HTTP 取消为异步操作，以最终 Run 状态及 run_finished 事件为准，见 服务接口。

正则搜索

grep 默认使用正则表达式；搜索普通文本时设置 fixed_string=true。本地工具默认 output_mode=files_with_matches，结果与执行时间均有上限。rg 定位、Glob、ignore 和输出限制见 正则搜索。

使用 Skills

每个 Skill 位于 ~/.deep-agent/skills/<技能目录>/，入口为 SKILL.md，YAML 头部包含 name 和 description。/skill 选择后插入技能块，可追加说明：

[Skill: playwright-cli] 检查当前项目的登录流程并记录截图。

Skills 只读映射到 /skills。Skill 提供操作说明，不安装执行工具；Node、Playwright、浏览器等需预先安装并通过沙箱暴露。Playwright CLI 官方安装 生成的目录需复制到 ~/.deep-agent/skills/。选择器见 终端界面，挂载见 沙箱工具链。

安全边界与限制

• 审批与隔离独立：ask 默认审批命令、Web 搜索及文件变更；allow 仅支持沙箱模式，免审批且所有 execute 使用有网实例。切换权限不停止此前的后台进程。
• 路径与挂载：普通文件工具在宿主进程执行，访问受 Backend 路径约束；命令在 Bubblewrap 内访问授权挂载。工作区内的 .git、.env 等也在可访问范围内，Skills 只读。额外挂载会扩大访问范围。
• 网络：ask 下 execute 默认无直接 IP 网络，可为单条命令声明 network=true 并审批；无网命名空间不阻断通过共享 Unix socket、FIFO 或文件实现的一切间接通信。模型与 Tavily 请求在宿主发送，不受该命令网络策略约束。
• 资源与生命周期：没有 CPU、内存、磁盘或进程数硬配额。会话内按需复用有网/无网沙箱，模型和权限切换不重建实例；会话切换及关闭时清理。
• 本地状态：同一会话同时只允许一个进程持有；工作区可能生成 .deep-agent/ 命令日志和 .deepagents/ 压缩历史，程序不修改 .gitignore。
• 客户端限制：模型和 Tavily 请求不读取代理环境变量；剪贴板图片仅支持 WSL，其他环境通过文件添加图片；当前不提供 MCP 或子 Agent。

隔离范围、环境变量、工具链挂载、宿主回退及排查步骤以 沙箱与权限 为准。

文档

开发

git clone https://github.com/ADaozz/deep_agent_cli.git
cd deep_agent_cli
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,server]"
pytest -q

自动化测试不调用真实模型。环境、冒烟脚本、CI 与发布见 开发文档。

许可证

MIT