deep-agent 是基于 Deep Agents 和 LangGraph 的终端 Coding Agent。它在当前项目中工作，默认在文件变更、命令执行和网页搜索前请求批准，通过 Bubblewrap 隔离命令执行。

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

能做什么

• 查代码、改文件 — 浏览、读取、正则搜索、编辑和删除；Ctrl+R 审阅完整改动，F2 处理审批。
• 运行项目命令 — 实时查看输出，会话内复用持久沙箱；默认审批、隔离直接 IP 网络。
• 随时介入任务 — 追加指令、排队后续任务、暂停、取消，以及结构化人工输入。
• 保留工作上下文 — SQLite 会话恢复、模型与推理强度切换、上下文压缩；支持图片输入的模型可接收附件。

支持通过 Skills 和 AGENTS.md 扩展项目指令。可选 HTTP 服务 与 Python API 复用运行核心。

快速开始

需要 Linux / WSL2、Python 3.12+、Bubblewrap，以及支持 Chat Completions 或 Responses 的模型端点。CLI 需要交互式终端；原生 Windows、macOS 和 WSL1 不支持这套沙箱。Ubuntu / WSL2 的 user namespace 限制见 沙箱排查。

1. 安装

Debian / Ubuntu：

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

系统默认 Python 低于 3.12 时，使用 pipx install --python /path/to/python3.12 deep-agent-cli 指定已安装的解释器。ripgrep 随 Python 依赖安装，无需另行安装。

2. 初始化与配置

从项目目录启动，首次运行会创建 ~/.deep-agent/config.yaml 和 Skills 目录，然后退出。已有配置不会被覆盖；设置了 DEEP_AGENT_CONFIG 时使用指定配置。

cd ~/projects/my-app  # 替换为你的项目目录
deep-agent

配置、Skills 和按键配置目录必须位于工作区之外，不要将家目录或其上层目录作为工作区。

默认模板使用 token-plan/qwen3.8-flash。在启动 Agent 的同一个 Bash 终端中输入对应密钥：

read -rsp 'Token Plan API key: ' TOKEN_PLAN_API_KEY
export TOKEN_PLAN_API_KEY
printf '\n'

使用其他模型服务时，编辑 ~/.deep-agent/config.yaml，调整端点、密钥、模型 ID 及能力配置。api 必须与端点匹配；省略时默认为 responses，不会自动判断。

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

3. 开始第一个任务

在项目目录再次运行 deep-agent，输入：

阅读当前项目，列出程序入口、关键模块和测试命令，并注明对应文件。
暂不修改文件或执行命令。

获得项目概览后，可以继续要求一次小范围修改。默认 ask 下，文件变更会等待审批：Ctrl+R 查看改动，F2 打开审批面板。启动检查失败时默认拒绝进入宿主执行，见 沙箱与权限。

deep-agent resume           # 选择已保存的会话
deep-agent resume 01a08aae   # 换成已有会话的 ID 或前缀
pipx upgrade 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

常用操作

更多按键、图片附件、队列、Skills 和显示设置见 终端界面。

架构与安全

审批决定是否执行，隔离决定命令能访问哪些资源。 文件工具和命令走不同通路：

• 文件工具 → 宿主进程：Backend 将 /workspace 映射到工作区，/skills 只读，拒绝其他虚拟路径。
• 命令 → Bubblewrap：execute 经沙箱池运行，会话内按需复用有网、无网 Worker。模型与 Tavily 请求从宿主发送，不受命令网络策略约束。

只读文件工具与 grep 免审批；allow 仅限沙箱模式。工作区内的 .env、.git 同样可访问，取消不回滚已发生的副作用。

文档

• 使用：配置参考 · 终端界面 · 正则搜索
• 机制：沙箱与权限 · 架构设计
• 集成：HTTP 服务 · Python API · 开发指南

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

MIT License