deep-agent-cli 0.1.6__tar.gz → 0.1.7__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (69) hide show
  1. deep_agent_cli-0.1.7/PKG-INFO +216 -0
  2. deep_agent_cli-0.1.7/README.md +184 -0
  3. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/app.py +87 -10
  4. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/input.py +1 -0
  5. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/interactions.py +1 -1
  6. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/previews.py +8 -22
  7. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/rendering.py +37 -33
  8. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/session_controller.py +0 -1
  9. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/state.py +5 -9
  10. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/config.py +0 -5
  11. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/control.py +10 -1
  12. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/factory.py +10 -3
  13. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/llm.py +1 -26
  14. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/middleware/steering.py +17 -3
  15. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/middleware/tool_arg_hints.py +1 -0
  16. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/permission.py +4 -14
  17. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/runner.py +2 -41
  18. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/sandbox.py +32 -0
  19. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/sandbox_pool.py +29 -7
  20. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/sandbox_worker.py +64 -8
  21. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/session.py +20 -61
  22. deep_agent_cli-0.1.7/agent/tools/_grep_worker.py +319 -0
  23. deep_agent_cli-0.1.7/agent/tools/grep.py +606 -0
  24. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/tools/human_input.py +5 -5
  25. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/tools/human_interaction.py +1 -1
  26. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/pyproject.toml +2 -1
  27. deep_agent_cli-0.1.6/PKG-INFO +0 -366
  28. deep_agent_cli-0.1.6/README.md +0 -335
  29. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/.gitignore +0 -0
  30. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/LICENSE +0 -0
  31. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/__init__.py +0 -0
  32. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/attachments.py +0 -0
  33. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/bootstrap.py +0 -0
  34. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cancel.py +0 -0
  35. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/__init__.py +0 -0
  36. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/clipboard.py +0 -0
  37. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/commands.py +0 -0
  38. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/gitinfo.py +0 -0
  39. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/main.py +0 -0
  40. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/pasted_content.py +0 -0
  41. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/skills.py +0 -0
  42. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/working_messages.py +0 -0
  43. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/cli/working_messages.yaml +0 -0
  44. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/config.example.yaml +0 -0
  45. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/file_mutation.py +0 -0
  46. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/llm_stream.py +0 -0
  47. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/middleware/__init__.py +0 -0
  48. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/middleware/attachments.py +0 -0
  49. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/middleware/cancel_tools.py +0 -0
  50. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/middleware/pause.py +0 -0
  51. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/middleware/recovery.py +0 -0
  52. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/middleware/runtime_config.py +0 -0
  53. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/middleware/usage.py +0 -0
  54. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/middleware/workspace_filesystem.py +0 -0
  55. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/middleware/write_operation.py +0 -0
  56. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/network.py +0 -0
  57. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/server/__init__.py +0 -0
  58. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/server/app.py +0 -0
  59. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/server/config.py +0 -0
  60. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/server/main.py +0 -0
  61. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/server/runtime.py +0 -0
  62. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/server/store.py +0 -0
  63. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/session_lock.py +0 -0
  64. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/session_runtime.py +0 -0
  65. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/stream.py +0 -0
  66. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/tools/__init__.py +0 -0
  67. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/tools/examples.py +0 -0
  68. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/tools/execute.py +0 -0
  69. {deep_agent_cli-0.1.6 → deep_agent_cli-0.1.7}/agent/tools/web_search.py +0 -0
@@ -0,0 +1,216 @@
1
+ Metadata-Version: 2.4
2
+ Name: deep-agent-cli
3
+ Version: 0.1.7
4
+ Summary: A sandboxed coding agent CLI for Linux and WSL2
5
+ License-Expression: MIT
6
+ License-File: LICENSE
7
+ Classifier: Environment :: Console
8
+ Classifier: Operating System :: POSIX :: Linux
9
+ Classifier: Programming Language :: Python :: 3.12
10
+ Classifier: Programming Language :: Python :: 3.13
11
+ Classifier: Topic :: Software Development
12
+ Requires-Python: >=3.12
13
+ Requires-Dist: deepagents<0.8.0,>=0.7.17
14
+ Requires-Dist: httpx<1,>=0.27
15
+ Requires-Dist: langchain-core<2.0,>=1.0
16
+ Requires-Dist: langchain-openai<1.7.0,>=1.6.2
17
+ Requires-Dist: langchain<2.0,>=1.0
18
+ Requires-Dist: langgraph-checkpoint-sqlite<4,>=3.1.1
19
+ Requires-Dist: langgraph<2.0,>=1.0
20
+ Requires-Dist: prompt-toolkit<4.0,>=3.0.48
21
+ Requires-Dist: pyyaml<7.0,>=6.0
22
+ Requires-Dist: rich<15.0,>=13.9
23
+ Requires-Dist: ripgrep-bin<16,>=15.2.0
24
+ Provides-Extra: dev
25
+ Requires-Dist: build<2,>=1.2; extra == 'dev'
26
+ Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
27
+ Requires-Dist: twine<7,>=6; extra == 'dev'
28
+ Provides-Extra: server
29
+ Requires-Dist: fastapi<1,>=0.115; extra == 'server'
30
+ Requires-Dist: uvicorn<1,>=0.30; extra == 'server'
31
+ Description-Content-Type: text/markdown
32
+
33
+ # deep-agent-cli
34
+
35
+ `deep-agent` 是面向 Linux 和 WSL2 的终端 Coding Agent,基于 [Deep Agents](https://github.com/langchain-ai/deepagents) 和 LangGraph 构建,支持 OpenAI 兼容模型服务,通过 [Bubblewrap](https://github.com/containers/bubblewrap) 隔离命令执行。工作区默认为启动目录,也可通过配置指定。
36
+
37
+ 当前版本为 0.1.7,处于早期开发阶段。稳定版发布前,配置格式、会话存储格式和 Python API 可能出现不兼容变更。
38
+
39
+ ## 功能
40
+
41
+ - **代码与文件**:目录浏览、读取、编辑、写入、删除,以及默认正则搜索。
42
+ - **命令执行与审批**:使用会话内的持久沙箱;默认 `ask` 模式在命令执行、文件变更和 Web 搜索前等待审批。
43
+ - **模型与上下文**:支持 Chat Completions / Responses、流式思考与回答、模型和推理强度切换、自动与手动上下文压缩。
44
+ - **交互控制**:运行中追加指令、排队后续任务、暂停、取消,以及结构化人工输入。
45
+ - **会话与附件**:按工作区保存 SQLite 会话,支持恢复;具备图片输入能力的模型可接收图片附件。
46
+ - **项目扩展**:加载 `~/.deep-agent/skills/` 中的 Skills 和工作区根目录的 `AGENTS.md`;配置 Tavily key 后提供 `web_search`。
47
+ - **HTTP 服务**:可选服务复用 Runner,提供文字任务、SSE、审批、人工输入与恢复。接口范围见 [HTTP 服务](docs/server.md)。
48
+
49
+ ## 运行要求
50
+
51
+ - Linux 或 WSL2;原生 Windows、macOS 和 WSL1 不支持 Bubblewrap 沙箱。
52
+ - Python 3.12+;CI 覆盖 Python 3.12 和 3.13。
53
+ - Bubblewrap 及可用的非特权 user namespace;Ubuntu / WSL2 的限制与处理见 [沙箱排查](docs/sandbox.md#排查ubuntu--wsl2)。
54
+ - 支持 Chat Completions 或 Responses 的模型端点及相应凭据。
55
+ - CLI 需要交互式终端;非交互接入使用 [HTTP 服务](docs/server.md) 或 [Python API](docs/library.md)。
56
+
57
+ ripgrep(`rg`)由项目的 `ripgrep-bin` Python 依赖自动安装,无需默认执行系统安装步骤。定位顺序为当前 Python 环境 scripts 目录、系统 PATH、Python 正则回退;运行时不自动下载二进制或修改 PATH。备选安装与验证见 [正则搜索](docs/search.md)。
58
+
59
+ ## 安装
60
+
61
+ Debian / Ubuntu:
62
+
63
+ ```bash
64
+ sudo apt install pipx bubblewrap
65
+ pipx ensurepath
66
+ # 重新打开终端后安装
67
+ pipx install deep-agent-cli
68
+ deep-agent --version
69
+ ```
70
+
71
+ 系统默认 Python 低于 3.12 时,可指定已安装的解释器,不替换发行版的 `/usr/bin/python3`:
72
+
73
+ ```bash
74
+ pipx install --python /path/to/python3.12 deep-agent-cli
75
+ ```
76
+
77
+ 也可使用虚拟环境:
78
+
79
+ ```bash
80
+ python3.12 -m venv ~/.venvs/deep-agent
81
+ ~/.venvs/deep-agent/bin/pip install deep-agent-cli
82
+ ~/.venvs/deep-agent/bin/deep-agent --version
83
+ ```
84
+
85
+ 升级现有 pipx 安装:
86
+
87
+ ```bash
88
+ pipx upgrade deep-agent-cli
89
+ ```
90
+
91
+ ## 快速开始
92
+
93
+ ### 1. 生成配置
94
+
95
+ ```bash
96
+ deep-agent
97
+ ```
98
+
99
+ 未指定 `DEEP_AGENT_CONFIG` 且默认配置不存在时,首次运行创建 `~/.deep-agent/config.yaml` 和 Skills 目录,然后退出。已存在的配置不会被模板覆盖。
100
+
101
+ ### 2. 配置模型
102
+
103
+ 在 `~/.deep-agent/config.yaml` 中配置模型端点。以下示例与默认配置模板一致,通过 `TOKEN_PLAN_API_KEY` 环境变量读取密钥:
104
+
105
+ ```yaml
106
+ llm:
107
+ default: token-plan/qwen3.8-flash
108
+ models:
109
+ token-plan:
110
+ base_url: https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
111
+ api_key: ${TOKEN_PLAN_API_KEY}
112
+ api: chat_completions
113
+ reasoning_efforts: [none, low, medium, xhigh]
114
+ models:
115
+ qwen3.8-flash:
116
+ input: [text, image]
117
+ context_window: 1m
118
+ ```
119
+
120
+ `llm.default` 使用“来源/模型”标识。模型项省略的字段继承来源级配置,模型级配置可覆盖来源级配置。使用其他端点时,应同步调整端点、密钥、模型 ID、输入模态、上下文窗口和推理强度;`api` 省略时默认为 `responses`,不会按模型名或 URL 自动判断协议。完整字段与服务商示例见 [配置参考](docs/configuration.md)。
121
+
122
+ ### 3. 在项目目录启动
123
+
124
+ ```bash
125
+ cd ~/projects/my-app
126
+ deep-agent
127
+ ```
128
+
129
+ 启动时检查配置与沙箱。默认在沙箱不可用时拒绝启动;宿主执行回退需要显式授权,见 [沙箱与权限](docs/sandbox.md)。主配置、Skills 和按键配置目录必须位于工作区之外,因此不能将家目录或其上层目录作为工作区。
130
+
131
+ 终端界面接受自然语言任务,以 `/` 开头的输入用于调用 CLI 命令。
132
+
133
+ ### 4. 恢复会话
134
+
135
+ ```bash
136
+ deep-agent resume # 选择已保存的会话
137
+ deep-agent resume 01a08aae # 替换为已有会话的 ID 或前缀
138
+ ```
139
+
140
+ 恢复加载会话状态,不自动继续未完成任务。仅支持当前会话数据库结构,不自动迁移旧格式。取消不会回滚已经发生的文件修改或外部副作用,恢复后需核对实际状态。
141
+
142
+ ## 常用操作
143
+
144
+ | 操作 | 用途 |
145
+ |---|---|
146
+ | `/help`、`/status` | 查看帮助、模型、权限和执行状态 |
147
+ | `/model` | 选择模型与推理强度 |
148
+ | `/permission ask\|allow` | 切换审批模式与后续命令的网络策略 |
149
+ | `/resume`、`/new` | 切换或新建会话 |
150
+ | `/skill` | 选择 Skill 并插入输入框 |
151
+ | `/image <路径>` | 附加图片 |
152
+ | `/compact` | 手动压缩上下文 |
153
+ | `Enter` / `Alt+Enter` | 提交任务或运行中追加指令 / 排队后续任务 |
154
+ | `Alt+↑` | 将尚未取用的排队消息移回输入框,停止自动发送 |
155
+ | `Esc` | 请求取消当前任务 |
156
+ | `F2` | 打开待处理的审批或人工输入面板 |
157
+ | `Ctrl+O` / `Ctrl+T` | 展开工具详情 / 思考内容 |
158
+ | `Ctrl+B` | 展开 / 收起排队消息和已发送的长消息 |
159
+ | `/quit` | 退出 |
160
+
161
+ 完整命令、按键、排队、长消息、Skills、显示和取消行为见 [终端界面](docs/tui.md)。HTTP 取消为异步操作,以最终 Run 状态及 `run_finished` 事件为准,见 [服务接口](docs/server.md)。
162
+
163
+ ## 正则搜索
164
+
165
+ `grep` 默认使用正则表达式;搜索普通文本时设置 `fixed_string=true`。本地工具默认 `output_mode=files_with_matches`,结果与执行时间均有上限。rg 定位、Glob、ignore 和输出限制见 [正则搜索](docs/search.md)。
166
+
167
+ ## 使用 Skills
168
+
169
+ 每个 Skill 位于 `~/.deep-agent/skills/<技能目录>/`,入口为 `SKILL.md`,YAML 头部包含 `name` 和 `description`。`/skill` 选择后插入技能块,可追加说明:
170
+
171
+ ```text
172
+ [Skill: playwright-cli] 检查当前项目的登录流程并记录截图。
173
+ ```
174
+
175
+ Skills 只读映射到 `/skills`。Skill 提供操作说明,不安装执行工具;Node、Playwright、浏览器等需预先安装并通过沙箱暴露。[Playwright CLI 官方安装](https://github.com/microsoft/playwright-cli#installing-skills) 生成的目录需复制到 `~/.deep-agent/skills/`。选择器见 [终端界面](docs/tui.md#skills),挂载见 [沙箱工具链](docs/sandbox.md#playwright-与有头-x11)。
176
+
177
+ ## 安全边界与限制
178
+
179
+ - **审批与隔离独立**:`ask` 默认审批命令、Web 搜索及文件变更;`allow` 仅支持沙箱模式,免审批且所有 execute 使用有网实例。切换权限不停止此前的后台进程。
180
+ - **路径与挂载**:普通文件工具在宿主进程执行,访问受 Backend 路径约束;命令在 Bubblewrap 内访问授权挂载。工作区内的 `.git`、`.env` 等也在可访问范围内,Skills 只读。额外挂载会扩大访问范围。
181
+ - **网络**:`ask` 下 execute 默认无直接 IP 网络,可为单条命令声明 `network=true` 并审批;无网命名空间不阻断通过共享 Unix socket、FIFO 或文件实现的一切间接通信。模型与 Tavily 请求在宿主发送,不受该命令网络策略约束。
182
+ - **资源与生命周期**:没有 CPU、内存、磁盘或进程数硬配额。会话内按需复用有网/无网沙箱,模型和权限切换不重建实例;会话切换及关闭时清理。
183
+ - **本地状态**:同一会话同时只允许一个进程持有;工作区可能生成 `.deep-agent/` 命令日志和 `.deepagents/` 压缩历史,程序不修改 `.gitignore`。
184
+ - **客户端限制**:模型和 Tavily 请求不读取代理环境变量;剪贴板图片仅支持 WSL,其他环境通过文件添加图片;当前不提供 MCP 或子 Agent。
185
+
186
+ 隔离范围、环境变量、工具链挂载、宿主回退及排查步骤以 [沙箱与权限](docs/sandbox.md) 为准。
187
+
188
+ ## 文档
189
+
190
+ | 文档 | 内容 |
191
+ |---|---|
192
+ | [配置参考](docs/configuration.md) | 模型、推理强度、Web 搜索、路径与环境变量 |
193
+ | [终端界面](docs/tui.md) | 命令、快捷键、图片、Skills 和会话操作 |
194
+ | [正则搜索](docs/search.md) | rg 安装定位、搜索模式、Glob、ignore 和结果限制 |
195
+ | [沙箱与权限](docs/sandbox.md) | 隔离、网络、日志、工具链和系统排查 |
196
+ | [HTTP 服务](docs/server.md) | 部署、接口、审批、人工输入、SSE 与恢复 |
197
+ | [Python API](docs/library.md) | AgentRunner、事件、自定义工具与 Backend |
198
+ | [架构](docs/architecture.md) | Harness 分层、运行边界、Middleware 和持久化 |
199
+ | [开发](docs/development.md) | 测试、冒烟、CI 与发布 |
200
+
201
+ ## 开发
202
+
203
+ ```bash
204
+ git clone https://github.com/ADaozz/deep_agent_cli.git
205
+ cd deep_agent_cli
206
+ python3.12 -m venv .venv
207
+ source .venv/bin/activate
208
+ pip install -e ".[dev,server]"
209
+ pytest -q
210
+ ```
211
+
212
+ 自动化测试不调用真实模型。环境、冒烟脚本、CI 与发布见 [开发文档](docs/development.md)。
213
+
214
+ ## 许可证
215
+
216
+ [MIT](LICENSE)
@@ -0,0 +1,184 @@
1
+ # deep-agent-cli
2
+
3
+ `deep-agent` 是面向 Linux 和 WSL2 的终端 Coding Agent,基于 [Deep Agents](https://github.com/langchain-ai/deepagents) 和 LangGraph 构建,支持 OpenAI 兼容模型服务,通过 [Bubblewrap](https://github.com/containers/bubblewrap) 隔离命令执行。工作区默认为启动目录,也可通过配置指定。
4
+
5
+ 当前版本为 0.1.7,处于早期开发阶段。稳定版发布前,配置格式、会话存储格式和 Python API 可能出现不兼容变更。
6
+
7
+ ## 功能
8
+
9
+ - **代码与文件**:目录浏览、读取、编辑、写入、删除,以及默认正则搜索。
10
+ - **命令执行与审批**:使用会话内的持久沙箱;默认 `ask` 模式在命令执行、文件变更和 Web 搜索前等待审批。
11
+ - **模型与上下文**:支持 Chat Completions / Responses、流式思考与回答、模型和推理强度切换、自动与手动上下文压缩。
12
+ - **交互控制**:运行中追加指令、排队后续任务、暂停、取消,以及结构化人工输入。
13
+ - **会话与附件**:按工作区保存 SQLite 会话,支持恢复;具备图片输入能力的模型可接收图片附件。
14
+ - **项目扩展**:加载 `~/.deep-agent/skills/` 中的 Skills 和工作区根目录的 `AGENTS.md`;配置 Tavily key 后提供 `web_search`。
15
+ - **HTTP 服务**:可选服务复用 Runner,提供文字任务、SSE、审批、人工输入与恢复。接口范围见 [HTTP 服务](docs/server.md)。
16
+
17
+ ## 运行要求
18
+
19
+ - Linux 或 WSL2;原生 Windows、macOS 和 WSL1 不支持 Bubblewrap 沙箱。
20
+ - Python 3.12+;CI 覆盖 Python 3.12 和 3.13。
21
+ - Bubblewrap 及可用的非特权 user namespace;Ubuntu / WSL2 的限制与处理见 [沙箱排查](docs/sandbox.md#排查ubuntu--wsl2)。
22
+ - 支持 Chat Completions 或 Responses 的模型端点及相应凭据。
23
+ - CLI 需要交互式终端;非交互接入使用 [HTTP 服务](docs/server.md) 或 [Python API](docs/library.md)。
24
+
25
+ ripgrep(`rg`)由项目的 `ripgrep-bin` Python 依赖自动安装,无需默认执行系统安装步骤。定位顺序为当前 Python 环境 scripts 目录、系统 PATH、Python 正则回退;运行时不自动下载二进制或修改 PATH。备选安装与验证见 [正则搜索](docs/search.md)。
26
+
27
+ ## 安装
28
+
29
+ Debian / Ubuntu:
30
+
31
+ ```bash
32
+ sudo apt install pipx bubblewrap
33
+ pipx ensurepath
34
+ # 重新打开终端后安装
35
+ pipx install deep-agent-cli
36
+ deep-agent --version
37
+ ```
38
+
39
+ 系统默认 Python 低于 3.12 时,可指定已安装的解释器,不替换发行版的 `/usr/bin/python3`:
40
+
41
+ ```bash
42
+ pipx install --python /path/to/python3.12 deep-agent-cli
43
+ ```
44
+
45
+ 也可使用虚拟环境:
46
+
47
+ ```bash
48
+ python3.12 -m venv ~/.venvs/deep-agent
49
+ ~/.venvs/deep-agent/bin/pip install deep-agent-cli
50
+ ~/.venvs/deep-agent/bin/deep-agent --version
51
+ ```
52
+
53
+ 升级现有 pipx 安装:
54
+
55
+ ```bash
56
+ pipx upgrade deep-agent-cli
57
+ ```
58
+
59
+ ## 快速开始
60
+
61
+ ### 1. 生成配置
62
+
63
+ ```bash
64
+ deep-agent
65
+ ```
66
+
67
+ 未指定 `DEEP_AGENT_CONFIG` 且默认配置不存在时,首次运行创建 `~/.deep-agent/config.yaml` 和 Skills 目录,然后退出。已存在的配置不会被模板覆盖。
68
+
69
+ ### 2. 配置模型
70
+
71
+ 在 `~/.deep-agent/config.yaml` 中配置模型端点。以下示例与默认配置模板一致,通过 `TOKEN_PLAN_API_KEY` 环境变量读取密钥:
72
+
73
+ ```yaml
74
+ llm:
75
+ default: token-plan/qwen3.8-flash
76
+ models:
77
+ token-plan:
78
+ base_url: https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
79
+ api_key: ${TOKEN_PLAN_API_KEY}
80
+ api: chat_completions
81
+ reasoning_efforts: [none, low, medium, xhigh]
82
+ models:
83
+ qwen3.8-flash:
84
+ input: [text, image]
85
+ context_window: 1m
86
+ ```
87
+
88
+ `llm.default` 使用“来源/模型”标识。模型项省略的字段继承来源级配置,模型级配置可覆盖来源级配置。使用其他端点时,应同步调整端点、密钥、模型 ID、输入模态、上下文窗口和推理强度;`api` 省略时默认为 `responses`,不会按模型名或 URL 自动判断协议。完整字段与服务商示例见 [配置参考](docs/configuration.md)。
89
+
90
+ ### 3. 在项目目录启动
91
+
92
+ ```bash
93
+ cd ~/projects/my-app
94
+ deep-agent
95
+ ```
96
+
97
+ 启动时检查配置与沙箱。默认在沙箱不可用时拒绝启动;宿主执行回退需要显式授权,见 [沙箱与权限](docs/sandbox.md)。主配置、Skills 和按键配置目录必须位于工作区之外,因此不能将家目录或其上层目录作为工作区。
98
+
99
+ 终端界面接受自然语言任务,以 `/` 开头的输入用于调用 CLI 命令。
100
+
101
+ ### 4. 恢复会话
102
+
103
+ ```bash
104
+ deep-agent resume # 选择已保存的会话
105
+ deep-agent resume 01a08aae # 替换为已有会话的 ID 或前缀
106
+ ```
107
+
108
+ 恢复加载会话状态,不自动继续未完成任务。仅支持当前会话数据库结构,不自动迁移旧格式。取消不会回滚已经发生的文件修改或外部副作用,恢复后需核对实际状态。
109
+
110
+ ## 常用操作
111
+
112
+ | 操作 | 用途 |
113
+ |---|---|
114
+ | `/help`、`/status` | 查看帮助、模型、权限和执行状态 |
115
+ | `/model` | 选择模型与推理强度 |
116
+ | `/permission ask\|allow` | 切换审批模式与后续命令的网络策略 |
117
+ | `/resume`、`/new` | 切换或新建会话 |
118
+ | `/skill` | 选择 Skill 并插入输入框 |
119
+ | `/image <路径>` | 附加图片 |
120
+ | `/compact` | 手动压缩上下文 |
121
+ | `Enter` / `Alt+Enter` | 提交任务或运行中追加指令 / 排队后续任务 |
122
+ | `Alt+↑` | 将尚未取用的排队消息移回输入框,停止自动发送 |
123
+ | `Esc` | 请求取消当前任务 |
124
+ | `F2` | 打开待处理的审批或人工输入面板 |
125
+ | `Ctrl+O` / `Ctrl+T` | 展开工具详情 / 思考内容 |
126
+ | `Ctrl+B` | 展开 / 收起排队消息和已发送的长消息 |
127
+ | `/quit` | 退出 |
128
+
129
+ 完整命令、按键、排队、长消息、Skills、显示和取消行为见 [终端界面](docs/tui.md)。HTTP 取消为异步操作,以最终 Run 状态及 `run_finished` 事件为准,见 [服务接口](docs/server.md)。
130
+
131
+ ## 正则搜索
132
+
133
+ `grep` 默认使用正则表达式;搜索普通文本时设置 `fixed_string=true`。本地工具默认 `output_mode=files_with_matches`,结果与执行时间均有上限。rg 定位、Glob、ignore 和输出限制见 [正则搜索](docs/search.md)。
134
+
135
+ ## 使用 Skills
136
+
137
+ 每个 Skill 位于 `~/.deep-agent/skills/<技能目录>/`,入口为 `SKILL.md`,YAML 头部包含 `name` 和 `description`。`/skill` 选择后插入技能块,可追加说明:
138
+
139
+ ```text
140
+ [Skill: playwright-cli] 检查当前项目的登录流程并记录截图。
141
+ ```
142
+
143
+ Skills 只读映射到 `/skills`。Skill 提供操作说明,不安装执行工具;Node、Playwright、浏览器等需预先安装并通过沙箱暴露。[Playwright CLI 官方安装](https://github.com/microsoft/playwright-cli#installing-skills) 生成的目录需复制到 `~/.deep-agent/skills/`。选择器见 [终端界面](docs/tui.md#skills),挂载见 [沙箱工具链](docs/sandbox.md#playwright-与有头-x11)。
144
+
145
+ ## 安全边界与限制
146
+
147
+ - **审批与隔离独立**:`ask` 默认审批命令、Web 搜索及文件变更;`allow` 仅支持沙箱模式,免审批且所有 execute 使用有网实例。切换权限不停止此前的后台进程。
148
+ - **路径与挂载**:普通文件工具在宿主进程执行,访问受 Backend 路径约束;命令在 Bubblewrap 内访问授权挂载。工作区内的 `.git`、`.env` 等也在可访问范围内,Skills 只读。额外挂载会扩大访问范围。
149
+ - **网络**:`ask` 下 execute 默认无直接 IP 网络,可为单条命令声明 `network=true` 并审批;无网命名空间不阻断通过共享 Unix socket、FIFO 或文件实现的一切间接通信。模型与 Tavily 请求在宿主发送,不受该命令网络策略约束。
150
+ - **资源与生命周期**:没有 CPU、内存、磁盘或进程数硬配额。会话内按需复用有网/无网沙箱,模型和权限切换不重建实例;会话切换及关闭时清理。
151
+ - **本地状态**:同一会话同时只允许一个进程持有;工作区可能生成 `.deep-agent/` 命令日志和 `.deepagents/` 压缩历史,程序不修改 `.gitignore`。
152
+ - **客户端限制**:模型和 Tavily 请求不读取代理环境变量;剪贴板图片仅支持 WSL,其他环境通过文件添加图片;当前不提供 MCP 或子 Agent。
153
+
154
+ 隔离范围、环境变量、工具链挂载、宿主回退及排查步骤以 [沙箱与权限](docs/sandbox.md) 为准。
155
+
156
+ ## 文档
157
+
158
+ | 文档 | 内容 |
159
+ |---|---|
160
+ | [配置参考](docs/configuration.md) | 模型、推理强度、Web 搜索、路径与环境变量 |
161
+ | [终端界面](docs/tui.md) | 命令、快捷键、图片、Skills 和会话操作 |
162
+ | [正则搜索](docs/search.md) | rg 安装定位、搜索模式、Glob、ignore 和结果限制 |
163
+ | [沙箱与权限](docs/sandbox.md) | 隔离、网络、日志、工具链和系统排查 |
164
+ | [HTTP 服务](docs/server.md) | 部署、接口、审批、人工输入、SSE 与恢复 |
165
+ | [Python API](docs/library.md) | AgentRunner、事件、自定义工具与 Backend |
166
+ | [架构](docs/architecture.md) | Harness 分层、运行边界、Middleware 和持久化 |
167
+ | [开发](docs/development.md) | 测试、冒烟、CI 与发布 |
168
+
169
+ ## 开发
170
+
171
+ ```bash
172
+ git clone https://github.com/ADaozz/deep_agent_cli.git
173
+ cd deep_agent_cli
174
+ python3.12 -m venv .venv
175
+ source .venv/bin/activate
176
+ pip install -e ".[dev,server]"
177
+ pytest -q
178
+ ```
179
+
180
+ 自动化测试不调用真实模型。环境、冒烟脚本、CI 与发布见 [开发文档](docs/development.md)。
181
+
182
+ ## 许可证
183
+
184
+ [MIT](LICENSE)
@@ -63,6 +63,7 @@ from agent.cli.rendering import (
63
63
  TranscriptDocument,
64
64
  TranscriptRenderer,
65
65
  render_interaction,
66
+ render_queued_messages,
66
67
  render_review,
67
68
  )
68
69
  from agent.cli.session_controller import SessionController
@@ -341,15 +342,19 @@ class _TranscriptWindow(Window):
341
342
  outright and skips the cursor-chasing arithmetic entirely.
342
343
  """
343
344
 
344
- def __init__(self, *args: Any, viewport: Any = None, **kwargs: Any) -> None:
345
+ def __init__(self, *args: Any, viewport: Any = None, scroll_offset: Any = None, **kwargs: Any) -> None:
345
346
  self._viewport = viewport
347
+ self._scroll_offset = scroll_offset
346
348
  super().__init__(*args, **kwargs)
347
349
 
348
350
  def _scroll(self, ui_content: Any, width: int, height: int) -> None:
349
351
  self.horizontal_scroll = 0
350
352
  self.vertical_scroll_2 = 0
351
353
  maximum = max(0, ui_content.line_count - height)
352
- self.vertical_scroll = self._viewport.transcript_offset(maximum) if self._viewport is not None else maximum
354
+ if self._scroll_offset is not None:
355
+ self.vertical_scroll = self._scroll_offset(maximum)
356
+ else:
357
+ self.vertical_scroll = self._viewport.transcript_offset(maximum) if self._viewport is not None else maximum
353
358
 
354
359
  class CliApplication:
355
360
  """pi-inspired terminal presentation over the existing synchronous runner."""
@@ -394,6 +399,8 @@ class CliApplication:
394
399
  self._transcript_line_count = 1
395
400
  # None = stick to bottom (follow new output); int = pinned scroll row.
396
401
  self._transcript_anchor: int | None = None
402
+ self._queue_scroll = 0
403
+ self._queue_preview_cache: tuple[Any, FormattedText, int] | None = None
397
404
  self._selection_start: tuple[int, int] | None = None
398
405
  self._selection_end: tuple[int, int] | None = None
399
406
  self._selection_dragging = False
@@ -447,6 +454,14 @@ class CliApplication:
447
454
  text=self._status_text, focusable=False, on_scroll=self.scroll_transcript,
448
455
  on_select_outside=self._select_below_transcript,
449
456
  )
457
+ self.queue_control = _ScrollableTextControl(
458
+ text=self._queue_text, focusable=False, on_scroll=self._scroll_queue,
459
+ )
460
+ self.queue_window = _TranscriptWindow(
461
+ self.queue_control, scroll_offset=self._queue_offset,
462
+ height=self._queue_height, wrap_lines=False, always_hide_cursor=True,
463
+ dont_extend_height=True, style="class:status",
464
+ )
450
465
  self.back_to_bottom_control = _BackToBottomControl(
451
466
  text=lambda: FormattedText([("class:back-to-bottom", "↓ Back to bottom · esc")])
452
467
  if self.interaction is None and self.transcript_away_from_bottom() else FormattedText([]),
@@ -556,6 +571,7 @@ class CliApplication:
556
571
  ),
557
572
  filter=Condition(self._status_visible),
558
573
  ),
574
+ ConditionalContainer(self.queue_window, filter=Condition(self._queue_expanded)),
559
575
  ConditionalContainer(
560
576
  self.interaction_bottom_divider_window,
561
577
  filter=interaction_visible | Condition(lambda: self.state.status == "Waiting for input"),
@@ -818,7 +834,7 @@ class CliApplication:
818
834
  "Keyboard\n"
819
835
  "Enter submit · Ctrl+J newline · Alt+Enter follow-up · Esc cancel+restore · "
820
836
  "PgUp/PgDn scroll · Ctrl+P next model · Alt+P prev model · Alt+Up restore queue · "
821
- "Ctrl+O tools · Ctrl+R review · F2 pending · Ctrl+T thinking · "
837
+ "Ctrl+O tools · Ctrl+R review · F2 pending · Ctrl+T thinking · Ctrl+B messages · "
822
838
  "Mouse drag selects and copies across history · "
823
839
  "Ctrl+V/Alt+V paste image/text · "
824
840
  "Ctrl+C clear/exit · Ctrl+D exit\n\n"
@@ -1243,7 +1259,6 @@ class CliApplication:
1243
1259
  self._clear_skill_draft()
1244
1260
  self.clear_transcript_selection()
1245
1261
  self.state.load_transcript(snapshot.transcript)
1246
- self.state.todos = list(snapshot.todos)
1247
1262
  self.interaction = None
1248
1263
  self._reviewing = False
1249
1264
  self.state.add_system(
@@ -1528,11 +1543,40 @@ class CliApplication:
1528
1543
  or self.runner.control.pending_follow_up_count()
1529
1544
  )
1530
1545
 
1546
+ def _queue_expanded(self) -> bool:
1547
+ return self.state.messages_expanded and bool(self.runner.control.pending_message_texts())
1548
+
1549
+ def _queue_text(self) -> FormattedText:
1550
+ key = (tuple(self.runner.control.pending_message_texts()), self._width())
1551
+ if self._queue_preview_cache is None or self._queue_preview_cache[0] != key:
1552
+ text = render_queued_messages(list(key[0]), key[1]) if key[0] else ""
1553
+ self._queue_preview_cache = (key, to_formatted_text(ANSI(text)), text.count("\n") + 1)
1554
+ self._queue_scroll = 0
1555
+ return self._queue_preview_cache[1]
1556
+
1557
+ def _queue_height(self) -> Dimension:
1558
+ self._queue_text()
1559
+ rows = self.application.output.get_size().rows
1560
+ height = min(self._queue_preview_cache[2], max(1, rows // 3))
1561
+ return Dimension.exact(height)
1562
+
1563
+ def _queue_offset(self, maximum: int) -> int:
1564
+ self._queue_scroll = max(0, min(self._queue_scroll, maximum))
1565
+ return self._queue_scroll
1566
+
1567
+ def _scroll_queue(self, delta: int) -> None:
1568
+ self._queue_text()
1569
+ maximum = max(0, self._queue_preview_cache[2] - self._queue_height().preferred)
1570
+ self._queue_offset(maximum)
1571
+ self._queue_scroll = max(0, min(maximum, self._queue_scroll + delta))
1572
+ self.application.invalidate()
1573
+
1531
1574
  def _status_text(self) -> FormattedText:
1532
1575
  if not self._status_visible():
1533
1576
  self._working_messages.reset()
1534
1577
  return FormattedText([])
1535
- pending = self.runner.control.pending_steering_count() + self.runner.control.pending_follow_up_count()
1578
+ queued = self.runner.control.pending_message_texts()
1579
+ pending = len(queued)
1536
1580
  active = self.state.running and self.interaction is None and not self.state.status.startswith("Cancelling")
1537
1581
  now = monotonic()
1538
1582
  message = self._working_messages.current(active, now)
@@ -1542,8 +1586,16 @@ class CliApplication:
1542
1586
  if (self._compacting or self.state.compacting) and not label.startswith("Cancelling"):
1543
1587
  label = "Compacting context"
1544
1588
  if pending:
1545
- label = f"{label} · queued {pending}" if label else f"queued {pending}"
1546
- status = _truncate_cells(f" {spinner}{label}", width)
1589
+ preview = " | ".join(" ".join(text.split()) for text in queued)
1590
+ queue_label = f"queued {pending} · Ctrl+B collapse" if self.state.messages_expanded else f"queued {pending}: {preview}"
1591
+ label = f"{label} · {queue_label}" if label else queue_label
1592
+ raw_status = f" {spinner}{label}"
1593
+ if pending and not self.state.messages_expanded and get_cwidth(raw_status) > width and width >= 20:
1594
+ hint = " · Ctrl+B expand" if width >= 32 else " · Ctrl+B"
1595
+ status = _truncate_cells(raw_status, max(1, width - get_cwidth(hint))) + hint
1596
+ status = _truncate_cells(status, width)
1597
+ else:
1598
+ status = _truncate_cells(raw_status, width)
1547
1599
  fragments = [("class:status", status)]
1548
1600
  remaining = width - get_cwidth(status)
1549
1601
  if message is not None and remaining > 3:
@@ -1699,11 +1751,11 @@ class CliApplication:
1699
1751
 
1700
1752
  @kb.add("pageup")
1701
1753
  def page_up(event) -> None: # type: ignore[no-untyped-def]
1702
- self.scroll_transcript(-10)
1754
+ self._scroll_queue(-10) if self._queue_expanded() else self.scroll_transcript(-10)
1703
1755
 
1704
1756
  @kb.add("pagedown")
1705
1757
  def page_down(event) -> None: # type: ignore[no-untyped-def]
1706
- self.scroll_transcript(10)
1758
+ self._scroll_queue(10) if self._queue_expanded() else self.scroll_transcript(10)
1707
1759
 
1708
1760
  @kb.add("c-home")
1709
1761
  def scroll_top(event) -> None: # type: ignore[no-untyped-def]
@@ -1833,6 +1885,13 @@ class CliApplication:
1833
1885
  self.state.thinking_collapsed = not self.state.thinking_collapsed
1834
1886
  self.set_status(f"Thinking: {'collapsed' if self.state.thinking_collapsed else 'expanded'}")
1835
1887
 
1888
+ @bind("messages_toggle")
1889
+ def messages_toggle(event) -> None: # type: ignore[no-untyped-def]
1890
+ self.state.messages_expanded = not self.state.messages_expanded
1891
+ self._queue_scroll = 0
1892
+ self.clear_transcript_selection()
1893
+ self.application.invalidate()
1894
+
1836
1895
  @bind("dequeue")
1837
1896
  def dequeue(event) -> None: # type: ignore[no-untyped-def]
1838
1897
  restored = self._restore_queued_to_editor(event.current_buffer)
@@ -1912,7 +1971,7 @@ class CliApplication:
1912
1971
  self.buffer.reset(append_to_history=True)
1913
1972
  asyncio.create_task(self._dispatch_command(text))
1914
1973
  return
1915
- if self.state.running:
1974
+ if self.state.running or self.runner.control.pending_message_texts():
1916
1975
  if self.state.attachments:
1917
1976
  self.set_status("Wait for the active run before sending images")
1918
1977
  return
@@ -1923,6 +1982,8 @@ class CliApplication:
1923
1982
  else:
1924
1983
  self.runner.steer(text)
1925
1984
  self.set_status("Steering queued")
1985
+ if not self.state.running and (self._run_task is None or self._run_task.done()):
1986
+ self._start_queued_run()
1926
1987
  self.application.invalidate()
1927
1988
  return
1928
1989
  self._reset_submitted_buffer(text)
@@ -1998,6 +2059,18 @@ class CliApplication:
1998
2059
 
1999
2060
  self._run_task = asyncio.create_task(work())
2000
2061
 
2062
+ def _start_queued_run(self) -> None:
2063
+ if self.interaction is not None or self.runner.current_interrupt() is not None:
2064
+ return
2065
+ text = self.runner.control.pop_steering()
2066
+ if text is None:
2067
+ text = self.runner.control.pop_follow_up()
2068
+ if text is not None:
2069
+ # The applied event records the user message in the transcript.
2070
+ self._start_run("", resume_call=partial(
2071
+ self.runner.invoke, text, on_event=self._on_event_thread,
2072
+ ))
2073
+
2001
2074
  async def image_command(self, arg: str) -> None:
2002
2075
  value = arg.strip()
2003
2076
  if not value:
@@ -2182,6 +2255,10 @@ class CliApplication:
2182
2255
  self.interaction = self._deferred_config_interaction
2183
2256
  self._deferred_config_interaction = None
2184
2257
  self.set_status("Type ALLOW to confirm · Esc cancel", transient=False)
2258
+ elif result.status == "completed":
2259
+ # Input can arrive after the worker's final queue check, while
2260
+ # the UI still considers that worker to be running.
2261
+ self._start_queued_run()
2185
2262
  self.application.invalidate()
2186
2263
 
2187
2264
  def _finish_interaction(self, *, cancelled: bool = False) -> None:
@@ -16,6 +16,7 @@ DEFAULT_BINDINGS: dict[str, list[str]] = {
16
16
  "review_diff": ["c-r"],
17
17
  "reopen_interaction": ["f2"],
18
18
  "thinking_toggle": ["c-t"],
19
+ "messages_toggle": ["c-b"],
19
20
  "dequeue": ["alt+up"],
20
21
  # Windows Terminal may reserve Ctrl+V for terminal paste. Alt+V is the
21
22
  # reliable application-level image clipboard fallback.
@@ -82,7 +82,7 @@ class InteractionController:
82
82
  details.append("Network: OFF" + (" (default)" if "network" not in args else ""))
83
83
  details.append(f"Command: {_approval_summary(args.get('command'))}")
84
84
  elif name in {"write_file", "edit_file", "delete"}:
85
- target = args.get("file_path") or args.get("path")
85
+ target = args.get("file_path")
86
86
  details.append(f"Target: {_approval_summary(target, kind='target')}")
87
87
  elif name == "web_search":
88
88
  details.append("Network: public web search via Tavily")