deep-agent-cli

deep-agent 是一个在终端中运行的 Coding Agent，支持 Linux 和 WSL2。它把启动时所在的目录作为工作区，调用你配置的 OpenAI 兼容模型服务，并在 Bubblewrap 沙箱中执行命令。Agent 运行时基于 Deep Agents 和 LangGraph 构建。

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

功能

• 文件操作：在工作区中列目录、读、写、编辑、搜索、删除文件。
• 命令执行：在 Bubblewrap 沙箱中运行 shell 命令，默认没有网络；输出实时显示。
• 审批：默认 ask 模式下，每次运行命令、Web 搜索、写入、编辑、删除文件前都会请求你确认。
• 会话：按工作区保存在本地 SQLite 中，可以随时恢复。
• 多模型：在配置文件中定义多个模型，运行中切换模型和推理强度。支持 Chat Completions 和 Responses 两种接口。
• 流式输出：思考内容和回答都流式显示；思考区默认保留按终端宽度折行后的末尾 5 行正文，Ctrl+T 展开。
• 运行中干预：任务执行时可以追加指令、排队后续任务或取消。
• 图片输入：向声明支持图片的模型发送图片。
• 结构化提问：Agent 需要你做决定时，会弹出单选、多选、是/否或文本输入。
• 上下文压缩：接近模型上下文窗口时自动摘要旧对话，也可以手动压缩。
• 技能：从 ~/.deep-agent/skills/ 加载 Skills，通过 /skill 选择技能并附带任务说明，支持读取技能目录中的参考文件。
• 可选扩展：配置 Tavily API key 后可以搜索公开网页；读取工作区根目录的 AGENTS.md 作为项目说明。

运行要求

• Linux 或 WSL2。WSL1、原生 Windows 和 macOS 无法使用沙箱。
• Python 3.12 或更高版本（CI 测试 3.12 和 3.13）。
• Bubblewrap，并且系统允许非特权 user namespace。Ubuntu 24.04 默认限制这一点，处理方法见 沙箱排查。
• 一个 OpenAI 兼容的模型服务（本地或远程）及其 API key。

安装

Debian / Ubuntu：

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

系统 Python 低于 3.12 时，安装一个新版本的 Python，然后指定解释器（不要替换发行版自带的 /usr/bin/python3）：

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

也可以装进虚拟环境：python3 -m venv ~/.venvs/deep-agent && ~/.venvs/deep-agent/bin/pip install deep-agent-cli。

快速开始

1. 生成配置文件

deep-agent

首次运行会创建 ~/.deep-agent/config.yaml 和 ~/.deep-agent/skills/，然后退出。

2. 配置模型

编辑 ~/.deep-agent/config.yaml，把 llm 部分改成你的服务：

llm:
  default: local/main                  # 启动时使用的模型：来源/模型键
  models:
    local:                             # 来源名，自定义
      base_url: http://localhost:8000/v1
      api_key: ${MY_API_KEY}           # 也可以直接写密钥
      provider: openai-compatible      # 端点支持 Responses API 时可改为 qwen-responses
      stream_usage: true
      reasoning_efforts: [none, low, medium, high]  # 来源级列表，见下文
      models:
        main:                          # 模型键，自定义
          model: your-model-name       # 发给服务端的模型名
          context_window: 128k
          input: [text]                # 支持图片时写 [text, image]
        fast: {}                       # 省略的字段全部继承来源
        other:
          reasoning_efforts: [low, high]  # 写了就完整替换来源列表

模型按「来源」分组。来源下可以写的字段，模型项中也都可以写：模型项省略则继承来源，写了就覆盖。列表字段（input、reasoning_efforts）是整表替换，不是合并；reasoning_efforts 写成 null 或 [] 会清除继承。

provider 未填写时默认为 qwen-responses（Responses API），只提供 Chat Completions 的服务需要显式写 openai-compatible。

reasoning_efforts 需要按服务商文档填写，程序不会自动探测。常见取值包括 none、low、medium、high、xhigh、max，同一模型在不同端点上可能不同。列表非空时，/model 只显示这些值，默认选中第一项；空列表或未配置时只显示 default，请求不携带强度参数。default 是 CLI 选项，不能写进列表。none 仅在端点明确支持关闭思考时才写；low 仍然会思考。Chat Completions 发送 reasoning_effort，Responses API 发送 reasoning.effort。

其他字段和服务商示例见 配置参考。

3. 在项目目录中启动

cd ~/projects/my-app
deep-agent

启动时会先检查沙箱是否可用；不可用时程序给出诊断信息并拒绝启动。界面中直接输入任务即可，以 / 开头的输入是命令。

4. 恢复会话

deep-agent resume            # 选择一个已保存的会话
deep-agent resume 01a08aae   # 按 id 或前缀恢复

恢复只加载会话状态，不会自动继续执行未完成的任务。

常用操作

输入 / 显示命令候选，按连续子串匹配，例如 /elp 匹配 /help，/hlp 不匹配。完整匹配和前缀匹配优先；方向键选择，Tab 或 Enter 填入，退格后重新计算候选。/model 和 /permission 的参数也支持补全。

完整的命令、按键和界面行为见 终端界面。

使用 Skills

每个技能放在 ~/.deep-agent/skills/ 下的独立目录中，入口文件为 SKILL.md。其 YAML 头部必须包含 name 和 description；技能列表显示 name，缺少有效元数据的目录会被跳过。

安装示例：Playwright CLI

准备好 Node.js 和 npm 后，在终端执行以下命令。先使用微软官方 Playwright CLI 的安装命令生成 Skill，再复制到本项目使用的目录：

mkdir -p ~/.deep-agent/skills
cd ~/.deep-agent/skills

# 如果还没安装 CLI
npm install -g @playwright/cli@latest

# 安装官方 Skill 到临时目录
skill_tmp_dir="$(mktemp -d)"
(cd "$skill_tmp_dir" && playwright-cli install --skills=agents)

# 复制到 DeepAgent 的技能目录
cp -a "$skill_tmp_dir/.agents/skills/playwright-cli" ~/.deep-agent/skills/

# 清理临时目录
rm -rf "$skill_tmp_dir"

验证安装：

ls -R ~/.deep-agent/skills/playwright-cli

安装后目录结构如下，references/ 中的参考文档也能读取：

~/.deep-agent/
└── skills/
    └── playwright-cli/
        ├── SKILL.md
        └── references/
            ├── playwright-tests.md
            ├── request-mocking.md
            ├── running-code.md
            ├── session-management.md
            ├── storage-state.md
            ├── test-generation.md
            ├── tracing.md
            ├── video-recording.md
            ├── element-attributes.md
            └── pr-attachments.md

在输入框中调用技能

在 CLI 中输入 /skill 后回车，用上下键选择技能，再回车将 [Skill: playwright-cli] 插入输入框。此时可以直接回车调用，也可以追加说明后提交：

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

选择时按 Esc 取消；完整删除输入框中的技能块即可取消本次技能调用。技能列表在每次打开时重新读取目录。发送后的聊天记录仍显示技能名称块和附带说明，恢复会话时也保持这一显示方式。

技能目录以只读方式映射到 /skills/。DeepAgent 原生 SkillsMiddleware 加载技能名称和描述；提交时携带所选技能的名称及路径，由模型按需读取 /skills/playwright-cli/SKILL.md 和相关参考文件，技能正文不会整段展开到输入框中。

加载技能只提供操作说明。工具链要在宿主机装好，再通过沙箱挂载暴露给命令。沙箱不能 sudo 或 apt-get，所以不要在里面执行 npx playwright install chrome。

沙箱里的工具链

首次启动时，agent/config.example.yaml 会复制成 ~/.deep-agent/config.yaml。其中的 sandbox 段已经是默认工具链配置：PATH 包含 Node.js 和 Cargo，并挂载下面这些目录。optional: true 的源目录在宿主机上不存在时会被跳过，不会阻止启动。

Node.js 版本以本机 ~/.nvm/versions/node/ 下的目录名为准，和模板不一致时改 source。其他装在 ~/.local、/opt 或家目录里的程序同样处理：用 readlink -f "$(command -v 工具名)" 找到落在 /usr、/bin、/lib 之外的目录，按同样格式追加挂载，并把可执行文件所在目录加到 PATH 前面。PATH 会替换沙箱默认值，末尾保留 /usr/local/bin:/usr/bin:/bin。

playwright-cli open 走系统 Chrome，不读浏览器缓存。没有系统 Chrome 时，在宿主机执行 npx playwright install chromium（先保证 ~/.cache/ms-playwright 存在），沙箱里再用 playwright-cli open --browser=chromium。缓存目录可写，沙箱中的安装和删除会改宿主机上的同一目录；只使用已安装浏览器时，把该项改到 extra_read_only_mounts。下载浏览器的命令需要网络。

已经存在的 ~/.deep-agent/config.yaml 不会被模板覆盖。把模板里的 sandbox.env_set 和两个挂载列表合并进现有文件，保存后退出并重新启动 deep-agent。挂载规则见 沙箱与权限。

安全模型

细节见 沙箱与权限。

已知限制

• 沙箱不限制 CPU、内存和磁盘用量。
• 沙箱中只有系统目录下的程序。安装在 ~/.local、~/.nvm、/opt 等位置的工具链默认不可用，需要在配置中添加只读挂载。
• 文件工具在 deep-agent 进程中直接读写宿主文件，不经过沙箱，路径限定在工作区和 Skills 目录内。工作区里的所有内容 Agent 都能读写，包括 .git/ 和 .env。
• 程序会在工作区中创建 .deep-agent/（命令输出超限时的日志）和 .deepagents/（上下文压缩时保存的历史），但不会修改 .gitignore。
• 不能在家目录或其上层目录启动，因为配置目录 ~/.deep-agent 必须位于工作区之外。
• 只能在交互式终端中使用，没有非交互或批处理模式。
• 模型请求和 Tavily 请求不读取 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 等代理环境变量。
• 从剪贴板粘贴图片只支持 WSL；其他环境需要通过文件路径添加图片。
• 推理强度的可选值需要按服务商文档手动配置，程序不会自动探测。
• 不支持 MCP，也没有子 Agent。
• 同一个会话同一时间只能被一个进程打开。

文档

• 配置参考：所有配置项、模型与推理强度、Web 搜索、按键、环境变量
• 沙箱与权限：隔离范围、网络、日志、Ubuntu / WSL2 排查
• 终端界面：命令、快捷键、图片、会话、显示规则
• 作为 Python 库使用：AgentRunner、事件、自定义工具
• 架构：分层、中间件、会话存储、上下文压缩
• 开发：测试、冒烟脚本、CI 与发布

开发

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

自动测试不调用真实模型。欢迎提交 Issue 和 Pull Request；修改行为时请附带测试。更多说明见 开发文档。

许可证

MIT