deep-agent-cli 0.1.7__tar.gz → 0.1.8__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 (72) hide show
  1. deep_agent_cli-0.1.8/PKG-INFO +238 -0
  2. deep_agent_cli-0.1.8/README.md +206 -0
  3. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/app.py +18 -3
  4. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/main.py +1 -8
  5. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/previews.py +1 -1
  6. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/rendering.py +14 -9
  7. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/session_controller.py +1 -0
  8. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/state.py +5 -0
  9. deep_agent_cli-0.1.8/agent/version.py +9 -0
  10. deep_agent_cli-0.1.8/assets/readme/runtime-map.svg +56 -0
  11. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/pyproject.toml +2 -2
  12. deep_agent_cli-0.1.8//347/273/210/347/253/257.png +0 -0
  13. deep_agent_cli-0.1.7/PKG-INFO +0 -216
  14. deep_agent_cli-0.1.7/README.md +0 -184
  15. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/.gitignore +0 -0
  16. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/LICENSE +0 -0
  17. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/__init__.py +0 -0
  18. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/attachments.py +0 -0
  19. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/bootstrap.py +0 -0
  20. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cancel.py +0 -0
  21. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/__init__.py +0 -0
  22. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/clipboard.py +0 -0
  23. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/commands.py +0 -0
  24. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/gitinfo.py +0 -0
  25. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/input.py +0 -0
  26. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/interactions.py +0 -0
  27. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/pasted_content.py +0 -0
  28. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/skills.py +0 -0
  29. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/working_messages.py +0 -0
  30. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/cli/working_messages.yaml +0 -0
  31. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/config.example.yaml +0 -0
  32. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/config.py +0 -0
  33. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/control.py +0 -0
  34. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/factory.py +0 -0
  35. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/file_mutation.py +0 -0
  36. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/llm.py +0 -0
  37. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/llm_stream.py +0 -0
  38. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/middleware/__init__.py +0 -0
  39. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/middleware/attachments.py +0 -0
  40. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/middleware/cancel_tools.py +0 -0
  41. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/middleware/pause.py +0 -0
  42. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/middleware/recovery.py +0 -0
  43. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/middleware/runtime_config.py +0 -0
  44. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/middleware/steering.py +0 -0
  45. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/middleware/tool_arg_hints.py +0 -0
  46. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/middleware/usage.py +0 -0
  47. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/middleware/workspace_filesystem.py +0 -0
  48. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/middleware/write_operation.py +0 -0
  49. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/network.py +0 -0
  50. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/permission.py +0 -0
  51. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/runner.py +0 -0
  52. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/sandbox.py +0 -0
  53. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/sandbox_pool.py +0 -0
  54. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/sandbox_worker.py +0 -0
  55. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/server/__init__.py +0 -0
  56. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/server/app.py +0 -0
  57. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/server/config.py +0 -0
  58. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/server/main.py +0 -0
  59. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/server/runtime.py +0 -0
  60. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/server/store.py +0 -0
  61. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/session.py +0 -0
  62. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/session_lock.py +0 -0
  63. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/session_runtime.py +0 -0
  64. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/stream.py +0 -0
  65. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/tools/__init__.py +0 -0
  66. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/tools/_grep_worker.py +0 -0
  67. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/tools/examples.py +0 -0
  68. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/tools/execute.py +0 -0
  69. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/tools/grep.py +0 -0
  70. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/tools/human_input.py +0 -0
  71. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/tools/human_interaction.py +0 -0
  72. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.8}/agent/tools/web_search.py +0 -0
@@ -0,0 +1,238 @@
1
+ Metadata-Version: 2.4
2
+ Name: deep-agent-cli
3
+ Version: 0.1.8
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
+ <div align="center">
34
+
35
+ # deep-agent-cli
36
+
37
+ **在终端中理解代码、审阅修改、运行命令。**
38
+
39
+ Linux / WSL2 · Python 3.12+<br>
40
+ OpenAI 兼容接口 · Bubblewrap
41
+
42
+ [快速开始](#快速开始) · [常用操作](#常用操作) · [架构与安全](#架构与安全) · [文档](#文档)
43
+
44
+ </div>
45
+
46
+ <p align="center">
47
+ <img src="终端.png" width="760" alt="deep-agent 真实终端空闲界面,底栏显示工作区、模型来源、SANDBOXED 和 perm:ask。">
48
+ </p>
49
+
50
+ `deep-agent` 是基于 [Deep Agents](https://github.com/langchain-ai/deepagents) 和 LangGraph 的终端 Coding Agent。它在当前项目中工作,默认在文件变更、命令执行和网页搜索前请求批准,通过 [Bubblewrap](https://github.com/containers/bubblewrap) 隔离命令执行。
51
+
52
+ > 当前版本 **0.1.8**,处于早期开发阶段。稳定版前,配置、会话存储格式和 Python API 可能出现不兼容变更。
53
+
54
+ ## 能做什么
55
+
56
+ - **查代码、改文件** — 浏览、读取、正则搜索、编辑和删除;`Ctrl+R` 审阅完整改动,`F2` 处理审批。
57
+ - **运行项目命令** — 实时查看输出,会话内复用持久沙箱;默认审批、隔离直接 IP 网络。
58
+ - **随时介入任务** — 追加指令、排队后续任务、暂停、取消,以及结构化人工输入。
59
+ - **保留工作上下文** — SQLite 会话恢复、模型与推理强度切换、上下文压缩;支持图片输入的模型可接收附件。
60
+
61
+ 支持通过 Skills 和 `AGENTS.md` 扩展项目指令。可选 [HTTP 服务](docs/server.md) 与 [Python API](docs/library.md) 复用运行核心。
62
+
63
+ ## 快速开始
64
+
65
+ 需要 **Linux / WSL2、Python 3.12+、Bubblewrap**,以及支持 Chat Completions 或 Responses 的模型端点。CLI 需要交互式终端;原生 Windows、macOS 和 WSL1 不支持这套沙箱。Ubuntu / WSL2 的 user namespace 限制见 [沙箱排查](docs/sandbox.md#排查ubuntu--wsl2)。
66
+
67
+ ### 1. 安装
68
+
69
+ Debian / Ubuntu:
70
+
71
+ ```bash
72
+ sudo apt install pipx bubblewrap
73
+ pipx ensurepath
74
+ # 重新打开终端后安装
75
+ pipx install deep-agent-cli
76
+ deep-agent --version
77
+ ```
78
+
79
+ 系统默认 Python 低于 3.12 时,使用 `pipx install --python /path/to/python3.12 deep-agent-cli` 指定已安装的解释器。ripgrep 随 Python 依赖安装,无需另行安装。
80
+
81
+ ### 2. 初始化与配置
82
+
83
+ 从项目目录启动,首次运行会创建 `~/.deep-agent/config.yaml` 和 Skills 目录,然后退出。已有配置不会被覆盖;设置了 `DEEP_AGENT_CONFIG` 时使用指定配置。
84
+
85
+ ```bash
86
+ cd ~/projects/my-app # 替换为你的项目目录
87
+ deep-agent
88
+ ```
89
+
90
+ 配置、Skills 和按键配置目录必须位于工作区之外,**不要将家目录或其上层目录作为工作区**。
91
+
92
+ 默认模板使用 `token-plan/qwen3.8-flash`。在启动 Agent 的同一个 Bash 终端中输入对应密钥:
93
+
94
+ ```bash
95
+ read -rsp 'Token Plan API key: ' TOKEN_PLAN_API_KEY
96
+ export TOKEN_PLAN_API_KEY
97
+ printf '\n'
98
+ ```
99
+
100
+ 使用其他模型服务时,编辑 `~/.deep-agent/config.yaml`,调整端点、密钥、模型 ID 及能力配置。`api` 必须与端点匹配;省略时默认为 `responses`,不会自动判断。
101
+
102
+ <details>
103
+ <summary>查看模型配置示例</summary>
104
+
105
+ 以下与默认模板一致;`llm.default` 使用“来源/模型”标识,模型项继承来源级字段,并可单独覆盖。
106
+
107
+ ```yaml
108
+ llm:
109
+ default: token-plan/qwen3.8-flash
110
+ models:
111
+ token-plan:
112
+ base_url: https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
113
+ api_key: ${TOKEN_PLAN_API_KEY}
114
+ api: chat_completions
115
+ reasoning_efforts: [none, low, medium, xhigh]
116
+ models:
117
+ qwen3.8-flash:
118
+ input: [text, image]
119
+ context_window: 1m
120
+ ```
121
+
122
+ 端点、上下文窗口、输入模态和推理强度取决于所选服务,完整说明见 [配置参考](docs/configuration.md)。
123
+
124
+ </details>
125
+
126
+ ### 3. 开始第一个任务
127
+
128
+ 在项目目录再次运行 `deep-agent`,输入:
129
+
130
+ ```text
131
+ 阅读当前项目,列出程序入口、关键模块和测试命令,并注明对应文件。
132
+ 暂不修改文件或执行命令。
133
+ ```
134
+
135
+ 获得项目概览后,可以继续要求一次小范围修改。默认 `ask` 下,文件变更会等待审批:`Ctrl+R` 查看改动,`F2` 打开审批面板。启动检查失败时默认拒绝进入宿主执行,见 [沙箱与权限](docs/sandbox.md)。
136
+
137
+ <details>
138
+ <summary>恢复会话、升级与虚拟环境安装</summary>
139
+
140
+ ```bash
141
+ deep-agent resume # 选择已保存的会话
142
+ deep-agent resume 01a08aae # 换成已有会话的 ID 或前缀
143
+ pipx upgrade deep-agent-cli
144
+ ```
145
+
146
+ 恢复只加载状态,不自动继续未完成任务;旧数据库格式不自动迁移。取消不回滚已发生的文件修改或外部副作用。
147
+
148
+ 不使用 pipx 时,也可安装到虚拟环境:
149
+
150
+ ```bash
151
+ python3.12 -m venv ~/.venvs/deep-agent
152
+ ~/.venvs/deep-agent/bin/pip install deep-agent-cli
153
+ ~/.venvs/deep-agent/bin/deep-agent --version
154
+ ```
155
+
156
+ </details>
157
+
158
+ ## 常用操作
159
+
160
+ | 操作 | 用途 |
161
+ |---|---|
162
+ | `/model` | 切换模型与推理强度 |
163
+ | `Ctrl+R` / `F2` | 审阅文件改动 / 处理审批与提问 |
164
+ | `Enter` / `Alt+Enter` | 提交或运行中追加指令 / 排队后续任务 |
165
+ | `Esc` | 请求取消当前任务 |
166
+ | `Ctrl+O` / `Ctrl+T` | 展开工具输出 / 思考内容 |
167
+ | `/resume` / `/new` | 恢复或新建会话 |
168
+ | `/help` / `/status` | 查看完整操作与当前状态 |
169
+
170
+ 更多按键、图片附件、队列、Skills 和显示设置见 [终端界面](docs/tui.md)。
171
+
172
+ ## 架构与安全
173
+
174
+ **审批决定是否执行,隔离决定命令能访问哪些资源。** 文件工具和命令走不同通路:
175
+
176
+ - **文件工具 → 宿主进程**:Backend 将 `/workspace` 映射到工作区,`/skills` 只读,拒绝其他虚拟路径。
177
+ - **命令 → Bubblewrap**:`execute` 经沙箱池运行,会话内按需复用有网、无网 Worker。模型与 Tavily 请求从宿主发送,不受命令网络策略约束。
178
+
179
+ <details>
180
+ <summary>展开运行架构图</summary>
181
+
182
+ ![TUI 或 HTTP 进入共享的 AgentRunner 和 Deep Agents / LangGraph;普通文件工具在宿主进程访问授权路径,execute 经 SandboxPool 进入 Bubblewrap Worker。](assets/readme/runtime-map.svg)
183
+
184
+ SQLite 保存会话状态。`grep` 免审批且独立于 `execute`;沙箱模式下有 rg 时复用沙箱池,否则使用宿主 Python 正则回退。完整分层与生命周期见 [架构文档](docs/architecture.md)。
185
+
186
+ </details>
187
+
188
+ | 模式 | 审批 | 命令网络 |
189
+ |---|---|---|
190
+ | **沙箱 + `ask`**(默认) | 文件变更、命令、网页搜索需批准 | 默认隔离直接 IP 网络;`network=true` 获批后共享宿主网络 |
191
+ | 沙箱 + `allow` | 所有工具免审批 | 所有 execute 共享宿主网络 |
192
+ | 宿主回退 + `ask` | 显式授权回退后,仍需审批 | 以宿主用户权限执行,无沙箱网络隔离 |
193
+
194
+ 只读文件工具与 `grep` 免审批;`allow` 仅限沙箱模式。**工作区内的 `.env`、`.git` 同样可访问,取消不回滚已发生的副作用。**
195
+
196
+ <details>
197
+ <summary>更多边界与当前限制</summary>
198
+
199
+ - **网络与进程**:无网命名空间不阻断通过共享 Unix socket、FIFO 或文件实现的间接通信。有网实例可访问互联网、localhost 和局域网;切回 `ask` 不停止此前的后台进程。会话切换及关闭时清理沙箱。
200
+ - **挂载与资源**:额外挂载会扩大访问范围;没有 CPU、内存、磁盘或进程数硬配额。Skills、`AGENTS.md` 和提示词不是操作系统安全边界。
201
+ - **本地状态**:同一会话只允许一个进程持有;工作区可能产生 `.deep-agent/` 命令日志和 `.deepagents/` 压缩历史,程序不修改 `.gitignore`。
202
+ - **HTTP 接入**:固定 `ask`、强制沙箱。服务级 Bearer 令牌不区分最终用户,接入方需校验登录、项目权限和会话归属,见 [服务接入边界](docs/server.md#推荐连接方式)。
203
+ - **客户端**:模型与 Tavily 请求忽略代理环境变量;剪贴板图片仅支持 WSL,其他环境通过文件添加;当前不提供 MCP 或子 Agent。
204
+
205
+ 完整隔离范围、环境变量与宿主回退说明见 [沙箱与权限](docs/sandbox.md)。
206
+
207
+ </details>
208
+
209
+ ## 文档
210
+
211
+ - **使用**:[配置参考](docs/configuration.md) · [终端界面](docs/tui.md) · [正则搜索](docs/search.md)
212
+ - **机制**:[沙箱与权限](docs/sandbox.md) · [架构设计](docs/architecture.md)
213
+ - **集成**:[HTTP 服务](docs/server.md) · [Python API](docs/library.md) · [开发指南](docs/development.md)
214
+
215
+ <details>
216
+ <summary>扩展 Skills 与网页搜索</summary>
217
+
218
+ Skills 位于 `~/.deep-agent/skills/<技能目录>/SKILL.md`,使用 `/skill` 选择;配置 Tavily key 后启用 `web_search`。外部工具与浏览器需预先安装并通过沙箱挂载,见 [Skills 用法](docs/tui.md#skills) 与 [沙箱工具链](docs/sandbox.md#playwright-与有头-x11)。
219
+
220
+ </details>
221
+
222
+ <details>
223
+ <summary>从源码开发</summary>
224
+
225
+ ```bash
226
+ git clone https://github.com/ADaozz/deep_agent_cli.git
227
+ cd deep_agent_cli
228
+ python3.12 -m venv .venv
229
+ source .venv/bin/activate
230
+ pip install -e ".[dev,server]"
231
+ pytest -q
232
+ ```
233
+
234
+ 自动化测试不调用真实模型;CI 覆盖 Python 3.12 和 3.13。更多说明见 [开发指南](docs/development.md)。
235
+
236
+ </details>
237
+
238
+ [MIT License](LICENSE)
@@ -0,0 +1,206 @@
1
+ <div align="center">
2
+
3
+ # deep-agent-cli
4
+
5
+ **在终端中理解代码、审阅修改、运行命令。**
6
+
7
+ Linux / WSL2 · Python 3.12+<br>
8
+ OpenAI 兼容接口 · Bubblewrap
9
+
10
+ [快速开始](#快速开始) · [常用操作](#常用操作) · [架构与安全](#架构与安全) · [文档](#文档)
11
+
12
+ </div>
13
+
14
+ <p align="center">
15
+ <img src="终端.png" width="760" alt="deep-agent 真实终端空闲界面,底栏显示工作区、模型来源、SANDBOXED 和 perm:ask。">
16
+ </p>
17
+
18
+ `deep-agent` 是基于 [Deep Agents](https://github.com/langchain-ai/deepagents) 和 LangGraph 的终端 Coding Agent。它在当前项目中工作,默认在文件变更、命令执行和网页搜索前请求批准,通过 [Bubblewrap](https://github.com/containers/bubblewrap) 隔离命令执行。
19
+
20
+ > 当前版本 **0.1.8**,处于早期开发阶段。稳定版前,配置、会话存储格式和 Python API 可能出现不兼容变更。
21
+
22
+ ## 能做什么
23
+
24
+ - **查代码、改文件** — 浏览、读取、正则搜索、编辑和删除;`Ctrl+R` 审阅完整改动,`F2` 处理审批。
25
+ - **运行项目命令** — 实时查看输出,会话内复用持久沙箱;默认审批、隔离直接 IP 网络。
26
+ - **随时介入任务** — 追加指令、排队后续任务、暂停、取消,以及结构化人工输入。
27
+ - **保留工作上下文** — SQLite 会话恢复、模型与推理强度切换、上下文压缩;支持图片输入的模型可接收附件。
28
+
29
+ 支持通过 Skills 和 `AGENTS.md` 扩展项目指令。可选 [HTTP 服务](docs/server.md) 与 [Python API](docs/library.md) 复用运行核心。
30
+
31
+ ## 快速开始
32
+
33
+ 需要 **Linux / WSL2、Python 3.12+、Bubblewrap**,以及支持 Chat Completions 或 Responses 的模型端点。CLI 需要交互式终端;原生 Windows、macOS 和 WSL1 不支持这套沙箱。Ubuntu / WSL2 的 user namespace 限制见 [沙箱排查](docs/sandbox.md#排查ubuntu--wsl2)。
34
+
35
+ ### 1. 安装
36
+
37
+ Debian / Ubuntu:
38
+
39
+ ```bash
40
+ sudo apt install pipx bubblewrap
41
+ pipx ensurepath
42
+ # 重新打开终端后安装
43
+ pipx install deep-agent-cli
44
+ deep-agent --version
45
+ ```
46
+
47
+ 系统默认 Python 低于 3.12 时,使用 `pipx install --python /path/to/python3.12 deep-agent-cli` 指定已安装的解释器。ripgrep 随 Python 依赖安装,无需另行安装。
48
+
49
+ ### 2. 初始化与配置
50
+
51
+ 从项目目录启动,首次运行会创建 `~/.deep-agent/config.yaml` 和 Skills 目录,然后退出。已有配置不会被覆盖;设置了 `DEEP_AGENT_CONFIG` 时使用指定配置。
52
+
53
+ ```bash
54
+ cd ~/projects/my-app # 替换为你的项目目录
55
+ deep-agent
56
+ ```
57
+
58
+ 配置、Skills 和按键配置目录必须位于工作区之外,**不要将家目录或其上层目录作为工作区**。
59
+
60
+ 默认模板使用 `token-plan/qwen3.8-flash`。在启动 Agent 的同一个 Bash 终端中输入对应密钥:
61
+
62
+ ```bash
63
+ read -rsp 'Token Plan API key: ' TOKEN_PLAN_API_KEY
64
+ export TOKEN_PLAN_API_KEY
65
+ printf '\n'
66
+ ```
67
+
68
+ 使用其他模型服务时,编辑 `~/.deep-agent/config.yaml`,调整端点、密钥、模型 ID 及能力配置。`api` 必须与端点匹配;省略时默认为 `responses`,不会自动判断。
69
+
70
+ <details>
71
+ <summary>查看模型配置示例</summary>
72
+
73
+ 以下与默认模板一致;`llm.default` 使用“来源/模型”标识,模型项继承来源级字段,并可单独覆盖。
74
+
75
+ ```yaml
76
+ llm:
77
+ default: token-plan/qwen3.8-flash
78
+ models:
79
+ token-plan:
80
+ base_url: https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
81
+ api_key: ${TOKEN_PLAN_API_KEY}
82
+ api: chat_completions
83
+ reasoning_efforts: [none, low, medium, xhigh]
84
+ models:
85
+ qwen3.8-flash:
86
+ input: [text, image]
87
+ context_window: 1m
88
+ ```
89
+
90
+ 端点、上下文窗口、输入模态和推理强度取决于所选服务,完整说明见 [配置参考](docs/configuration.md)。
91
+
92
+ </details>
93
+
94
+ ### 3. 开始第一个任务
95
+
96
+ 在项目目录再次运行 `deep-agent`,输入:
97
+
98
+ ```text
99
+ 阅读当前项目,列出程序入口、关键模块和测试命令,并注明对应文件。
100
+ 暂不修改文件或执行命令。
101
+ ```
102
+
103
+ 获得项目概览后,可以继续要求一次小范围修改。默认 `ask` 下,文件变更会等待审批:`Ctrl+R` 查看改动,`F2` 打开审批面板。启动检查失败时默认拒绝进入宿主执行,见 [沙箱与权限](docs/sandbox.md)。
104
+
105
+ <details>
106
+ <summary>恢复会话、升级与虚拟环境安装</summary>
107
+
108
+ ```bash
109
+ deep-agent resume # 选择已保存的会话
110
+ deep-agent resume 01a08aae # 换成已有会话的 ID 或前缀
111
+ pipx upgrade deep-agent-cli
112
+ ```
113
+
114
+ 恢复只加载状态,不自动继续未完成任务;旧数据库格式不自动迁移。取消不回滚已发生的文件修改或外部副作用。
115
+
116
+ 不使用 pipx 时,也可安装到虚拟环境:
117
+
118
+ ```bash
119
+ python3.12 -m venv ~/.venvs/deep-agent
120
+ ~/.venvs/deep-agent/bin/pip install deep-agent-cli
121
+ ~/.venvs/deep-agent/bin/deep-agent --version
122
+ ```
123
+
124
+ </details>
125
+
126
+ ## 常用操作
127
+
128
+ | 操作 | 用途 |
129
+ |---|---|
130
+ | `/model` | 切换模型与推理强度 |
131
+ | `Ctrl+R` / `F2` | 审阅文件改动 / 处理审批与提问 |
132
+ | `Enter` / `Alt+Enter` | 提交或运行中追加指令 / 排队后续任务 |
133
+ | `Esc` | 请求取消当前任务 |
134
+ | `Ctrl+O` / `Ctrl+T` | 展开工具输出 / 思考内容 |
135
+ | `/resume` / `/new` | 恢复或新建会话 |
136
+ | `/help` / `/status` | 查看完整操作与当前状态 |
137
+
138
+ 更多按键、图片附件、队列、Skills 和显示设置见 [终端界面](docs/tui.md)。
139
+
140
+ ## 架构与安全
141
+
142
+ **审批决定是否执行,隔离决定命令能访问哪些资源。** 文件工具和命令走不同通路:
143
+
144
+ - **文件工具 → 宿主进程**:Backend 将 `/workspace` 映射到工作区,`/skills` 只读,拒绝其他虚拟路径。
145
+ - **命令 → Bubblewrap**:`execute` 经沙箱池运行,会话内按需复用有网、无网 Worker。模型与 Tavily 请求从宿主发送,不受命令网络策略约束。
146
+
147
+ <details>
148
+ <summary>展开运行架构图</summary>
149
+
150
+ ![TUI 或 HTTP 进入共享的 AgentRunner 和 Deep Agents / LangGraph;普通文件工具在宿主进程访问授权路径,execute 经 SandboxPool 进入 Bubblewrap Worker。](assets/readme/runtime-map.svg)
151
+
152
+ SQLite 保存会话状态。`grep` 免审批且独立于 `execute`;沙箱模式下有 rg 时复用沙箱池,否则使用宿主 Python 正则回退。完整分层与生命周期见 [架构文档](docs/architecture.md)。
153
+
154
+ </details>
155
+
156
+ | 模式 | 审批 | 命令网络 |
157
+ |---|---|---|
158
+ | **沙箱 + `ask`**(默认) | 文件变更、命令、网页搜索需批准 | 默认隔离直接 IP 网络;`network=true` 获批后共享宿主网络 |
159
+ | 沙箱 + `allow` | 所有工具免审批 | 所有 execute 共享宿主网络 |
160
+ | 宿主回退 + `ask` | 显式授权回退后,仍需审批 | 以宿主用户权限执行,无沙箱网络隔离 |
161
+
162
+ 只读文件工具与 `grep` 免审批;`allow` 仅限沙箱模式。**工作区内的 `.env`、`.git` 同样可访问,取消不回滚已发生的副作用。**
163
+
164
+ <details>
165
+ <summary>更多边界与当前限制</summary>
166
+
167
+ - **网络与进程**:无网命名空间不阻断通过共享 Unix socket、FIFO 或文件实现的间接通信。有网实例可访问互联网、localhost 和局域网;切回 `ask` 不停止此前的后台进程。会话切换及关闭时清理沙箱。
168
+ - **挂载与资源**:额外挂载会扩大访问范围;没有 CPU、内存、磁盘或进程数硬配额。Skills、`AGENTS.md` 和提示词不是操作系统安全边界。
169
+ - **本地状态**:同一会话只允许一个进程持有;工作区可能产生 `.deep-agent/` 命令日志和 `.deepagents/` 压缩历史,程序不修改 `.gitignore`。
170
+ - **HTTP 接入**:固定 `ask`、强制沙箱。服务级 Bearer 令牌不区分最终用户,接入方需校验登录、项目权限和会话归属,见 [服务接入边界](docs/server.md#推荐连接方式)。
171
+ - **客户端**:模型与 Tavily 请求忽略代理环境变量;剪贴板图片仅支持 WSL,其他环境通过文件添加;当前不提供 MCP 或子 Agent。
172
+
173
+ 完整隔离范围、环境变量与宿主回退说明见 [沙箱与权限](docs/sandbox.md)。
174
+
175
+ </details>
176
+
177
+ ## 文档
178
+
179
+ - **使用**:[配置参考](docs/configuration.md) · [终端界面](docs/tui.md) · [正则搜索](docs/search.md)
180
+ - **机制**:[沙箱与权限](docs/sandbox.md) · [架构设计](docs/architecture.md)
181
+ - **集成**:[HTTP 服务](docs/server.md) · [Python API](docs/library.md) · [开发指南](docs/development.md)
182
+
183
+ <details>
184
+ <summary>扩展 Skills 与网页搜索</summary>
185
+
186
+ Skills 位于 `~/.deep-agent/skills/<技能目录>/SKILL.md`,使用 `/skill` 选择;配置 Tavily key 后启用 `web_search`。外部工具与浏览器需预先安装并通过沙箱挂载,见 [Skills 用法](docs/tui.md#skills) 与 [沙箱工具链](docs/sandbox.md#playwright-与有头-x11)。
187
+
188
+ </details>
189
+
190
+ <details>
191
+ <summary>从源码开发</summary>
192
+
193
+ ```bash
194
+ git clone https://github.com/ADaozz/deep_agent_cli.git
195
+ cd deep_agent_cli
196
+ python3.12 -m venv .venv
197
+ source .venv/bin/activate
198
+ pip install -e ".[dev,server]"
199
+ pytest -q
200
+ ```
201
+
202
+ 自动化测试不调用真实模型;CI 覆盖 Python 3.12 和 3.13。更多说明见 [开发指南](docs/development.md)。
203
+
204
+ </details>
205
+
206
+ [MIT License](LICENSE)
@@ -101,6 +101,15 @@ def _call_in_run_epoch(epoch: int, func: Callable[..., Any], /, *args: Any, **kw
101
101
  return copy_context().run(call)
102
102
 
103
103
 
104
+ def format_workspace_path(path: Path) -> str:
105
+ """Abbreviate the current user's home directory for display only."""
106
+ try:
107
+ relative = path.relative_to(Path.home())
108
+ except ValueError:
109
+ return str(path)
110
+ return "~/" if relative == Path(".") else f"~/{relative}"
111
+
112
+
104
113
  def format_context_window(window: int) -> str:
105
114
  """1000000 -> "1.0m", 200000 -> "200k"."""
106
115
  if window >= 1_000_000:
@@ -110,12 +119,14 @@ def format_context_window(window: int) -> str:
110
119
  return str(window)
111
120
 
112
121
 
113
- def format_context_usage(usage: dict[str, int], window: int) -> str:
122
+ def format_context_usage(usage: dict[str, int], window: int, *, empty_session: bool = False) -> str:
114
123
  """Right-hand footer label, empty when the profile declares no window."""
115
124
  if window <= 0:
116
125
  return ""
117
126
  label = f"{format_context_window(window)} Context"
118
127
  used = usage.get("input_tokens")
128
+ if empty_session and not usage:
129
+ used = 0
119
130
  if type(used) is not int or used < 0:
120
131
  return f"{label} · Unknown"
121
132
  percent = used / window * 100
@@ -374,6 +385,7 @@ class CliApplication:
374
385
  require_keybindings_outside_workspace(config_dir, workspace)
375
386
  _register_terminal_sequences()
376
387
  self.state = CliState()
388
+ self.state.context_pristine = not runner.thread_has_content()
377
389
  self.commands = command_table()
378
390
  self.command_by_name = {item.name: item for item in self.commands}
379
391
  keymap_path = (config_dir / "keybindings.json") if config_dir else None
@@ -1619,7 +1631,10 @@ class CliApplication:
1619
1631
  elif pending_effort is not None:
1620
1632
  model_label += f" → {pending_effort} (pending)"
1621
1633
  resume_id = self.runner.thread_id[:8]
1622
- context = format_context_usage(self.state.usage, self.runner.context_window())
1634
+ context = format_context_usage(
1635
+ self.state.usage, self.runner.context_window(),
1636
+ empty_session=self.state.context_pristine and not self.state.running,
1637
+ )
1623
1638
  # Row 1: workspace · model · resume on the left, git on the right.
1624
1639
  # Row 2: sandbox/permission on the left, context on the right.
1625
1640
  # The left side always truncates before the right side.
@@ -1638,7 +1653,7 @@ class CliApplication:
1638
1653
  model_width = max(1, available - get_cwidth(resume_id) - 6)
1639
1654
  model_fit = _truncate_cells(model_label, model_width)
1640
1655
  workspace_width = max(1, available - get_cwidth(model_fit) - get_cwidth(resume_id) - 6)
1641
- workspace_fit = _truncate_cells(f" {self._workspace()}", workspace_width)
1656
+ workspace_fit = _truncate_cells(f" {format_workspace_path(self._workspace())}", workspace_width)
1642
1657
  left_width = get_cwidth(workspace_fit) + get_cwidth(model_fit) + get_cwidth(resume_id) + 6
1643
1658
  first_padding = " " * max(1, width - left_width - get_cwidth(git_fit))
1644
1659
  if workspace_fit.startswith(" "):
@@ -4,7 +4,6 @@ from __future__ import annotations
4
4
 
5
5
  import argparse
6
6
  import sys
7
- from importlib.metadata import PackageNotFoundError, version
8
7
  from dataclasses import replace
9
8
  from prompt_toolkit import PromptSession
10
9
  from prompt_toolkit.validation import Validator
@@ -18,6 +17,7 @@ from agent.config import ConfigError, Settings, require_keybindings_outside_work
18
17
  from agent.runner import AgentRunner
19
18
  from agent.sandbox import ExecutionMode, SandboxUnavailableError, UNSANDBOXED_WARNING
20
19
  from agent.session import SessionStore
20
+ from agent.version import package_version
21
21
 
22
22
 
23
23
  def create_runner(settings: Settings) -> AgentRunner:
@@ -70,13 +70,6 @@ def _confirm_unsandboxed(error: str) -> None:
70
70
  raise SystemExit("Startup cancelled.") from exc
71
71
 
72
72
 
73
- def package_version() -> str:
74
- try:
75
- return version("deep-agent-cli")
76
- except PackageNotFoundError:
77
- return "unknown (source checkout; install the package to read its version)"
78
-
79
-
80
73
  def parse_startup_args(argv: list[str]) -> tuple[str | None, bool]:
81
74
  parser = argparse.ArgumentParser(
82
75
  prog="deep-agent",
@@ -351,7 +351,7 @@ def build_review_mutation(name: str, args: dict[str, Any]) -> FileMutationPrevie
351
351
 
352
352
 
353
353
  def file_tool_preview(mutation: FileMutationPreview) -> ToolPreview:
354
- verb = {"create": "Create", "modify": "Edited", "overwrite": "Wrote", "delete": "Deleted"}[mutation.operation]
354
+ verb = {"create": "Created", "modify": "Edited", "overwrite": "Wrote", "delete": "Deleted"}[mutation.operation]
355
355
  detail = ""
356
356
  if mutation.operation == "modify" and mutation.diff:
357
357
  detail = f"(+{mutation.diff.added or 0} -{mutation.diff.deleted or 0})"
@@ -43,6 +43,7 @@ from agent.cli.previews import (
43
43
  from agent.cli.state import CliState, MessageBlock, ToolBlock, TurnSummaryBlock
44
44
  from agent.cli.skills import skill_message_display
45
45
  from agent.config import DEFAULT_UI_DISPLAY_LIMITS, DEFAULT_UI_TIMEZONE, UiDisplayLimits
46
+ from agent.version import package_version
46
47
 
47
48
  # PreviewLine style -> Rich style mapping for line-oriented mutation bodies.
48
49
  _PREVIEW_LINE_STYLES: dict[str, str] = {
@@ -243,7 +244,7 @@ def _create_group(blocks: list[ToolBlock], expanded: bool, width: int, *, limits
243
244
  mutation = aggregate_file_mutations(mutations, expanded=expanded, limits=limits)
244
245
  if len(mutation.paths) == 1:
245
246
  return _tool(blocks[-1], expanded, width, limits=limits)
246
- title = Text.assemble(("● ", "green"), (f"Create {len(mutation.paths)} files", "bold"))
247
+ title = Text.assemble(("● ", "green"), (f"Created {len(mutation.paths)} files", "bold"))
247
248
  rows = [Text(line.text, style=_PREVIEW_LINE_STYLES[line.style]) for line in mutation.compact_lines]
248
249
  for row in (title, *rows):
249
250
  row.truncate(max(1, width - 1), overflow="ellipsis")
@@ -555,12 +556,12 @@ def _turn_summary(block: TurnSummaryBlock, timezone: ZoneInfo) -> Any:
555
556
 
556
557
 
557
558
  def _header() -> list[Any]:
558
- title = Text.assemble(("DeepAgent", "bold bright_cyan"), (" terminal coding agent", "dim"))
559
- hints = Text(
560
- "Esc interrupt · F2 pending · Ctrl+O tools · Ctrl+R review · / commands",
561
- style="dim",
559
+ title = Text.assemble(
560
+ ("DeepAgentCLI", "bold bright_cyan"),
561
+ (f" v{package_version()}", "dim"),
562
+ (" terminal coding agent", "dim"),
562
563
  )
563
- items: list[Any] = [title, hints]
564
+ items: list[Any] = [title]
564
565
  items.extend([Rule(style="#303030"), Text("")])
565
566
  return items
566
567
 
@@ -587,9 +588,10 @@ def _explore_group(blocks: list[ToolBlock], width: int = 80, *, limits: UiDispla
587
588
  marker_status = "error" if failed or interrupted else "running" if running else "waiting" if waiting else "completed"
588
589
  symbol, color = _tool_status_marker(marker_status)
589
590
  count = len(blocks)
591
+ verb = "Exploring" if running else "Explore" if waiting or interrupted or failed else "Explored"
590
592
  title = Text.assemble(
591
593
  (f" {symbol} ", color),
592
- (f"Explored {count} {'item' if count == 1 else 'items'}", "bold"),
594
+ (f"{verb} {count} {'item' if count == 1 else 'items'}", "bold"),
593
595
  (f" · {len(failed)} failed", "dim") if failed else ("", ""),
594
596
  (f" · {interrupted} interrupted", "dim") if interrupted else ("", ""),
595
597
  (suffix, "dim"),
@@ -649,7 +651,10 @@ def render_tool_preview(
649
651
  else " — interrupted (completion unconfirmed)" if block.status == "interrupted"
650
652
  else ""
651
653
  )
652
- summary = f"{preview.verb} {preview.target}".strip()
654
+ verb = preview.verb
655
+ if block.status == "running":
656
+ verb = {"edit_file": "Editing", "write_file": "Writing", "delete": "Deleting"}.get(block.name, verb)
657
+ summary = f"{verb} {preview.target}".strip()
653
658
  title = Text.assemble((f"{symbol} ", color), (summary, "bold"))
654
659
  mutation = preview.file_mutation
655
660
  if mutation is not None and mutation.operation == "modify" and mutation.diff is not None:
@@ -691,7 +696,7 @@ def _command_card(output: str, preview: CommandExecutionPreview, expanded: bool,
691
696
  """Render the current output snapshot; every delta rebuilds this card."""
692
697
  status = preview.status
693
698
  verb = {
694
- "running": "execute", "waiting": "execute", "interrupted": "execute",
699
+ "running": "Running", "waiting": "execute", "interrupted": "execute",
695
700
  "succeeded": "Ran", "failed": f"Failed (exit {preview.exit_code if preview.exit_code is not None else 1})",
696
701
  "timeout": "Timed out", "cancelled": "Cancelled", "spawn_error": "Failed to start",
697
702
  }[status]
@@ -73,6 +73,7 @@ class SessionController:
73
73
  app._clear_skill_draft()
74
74
  app.clear_transcript_selection()
75
75
  app.state.clear()
76
+ app.state.context_pristine = True
76
77
  app.state.attachments.clear()
77
78
  app.interaction = None
78
79
  app._deferred_config_interaction = None
@@ -69,6 +69,9 @@ class CliState:
69
69
  pending_user_ids: dict[str, str] = field(default_factory=dict)
70
70
  attachments: list[ImageAttachmentRef] = field(default_factory=list)
71
71
  usage: dict[str, int] = field(default_factory=dict)
72
+ # Separate a never-started conversation from missing model usage.
73
+ # Clearing the visible transcript must not reset this session property.
74
+ context_pristine: bool = True
72
75
 
73
76
  def add_user(
74
77
  self,
@@ -98,6 +101,7 @@ class CliState:
98
101
 
99
102
  def load_transcript(self, blocks: list[TranscriptBlock]) -> None:
100
103
  self.clear()
104
+ self.context_pristine = not bool(blocks)
101
105
  for item in blocks:
102
106
  if item.kind == "user":
103
107
  self.blocks.append(MessageBlock(
@@ -123,6 +127,7 @@ class CliState:
123
127
  if event.type in {"run_started", "run_completed", "run_failed", "run_cancelled", "interaction_requested"}:
124
128
  self.compacting = False
125
129
  if event.type == "run_started":
130
+ self.context_pristine = False
126
131
  self.running = True
127
132
  self.status = "Working… Esc to cancel"
128
133
  self.active_block = None
@@ -0,0 +1,9 @@
1
+ """Shared package version for CLI output and terminal presentation."""
2
+ from importlib.metadata import PackageNotFoundError, version
3
+
4
+
5
+ def package_version() -> str:
6
+ try:
7
+ return version("deep-agent-cli")
8
+ except PackageNotFoundError:
9
+ return "unknown (source checkout; install the package to read its version)"