deep-agent-cli 0.1.2__tar.gz → 0.1.4__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 (68) hide show
  1. deep_agent_cli-0.1.4/PKG-INFO +355 -0
  2. deep_agent_cli-0.1.4/README.md +324 -0
  3. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cancel.py +6 -1
  4. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/app.py +251 -58
  5. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/commands.py +5 -0
  6. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/interactions.py +26 -7
  7. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/main.py +19 -5
  8. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/rendering.py +76 -13
  9. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/session_controller.py +9 -7
  10. deep_agent_cli-0.1.4/agent/cli/skills.py +71 -0
  11. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/state.py +4 -2
  12. deep_agent_cli-0.1.4/agent/config.example.yaml +147 -0
  13. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/config.py +40 -26
  14. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/factory.py +17 -2
  15. deep_agent_cli-0.1.4/agent/llm.py +393 -0
  16. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/middleware/attachments.py +2 -2
  17. deep_agent_cli-0.1.4/agent/middleware/usage.py +29 -0
  18. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/network.py +3 -3
  19. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/permission.py +14 -12
  20. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/runner.py +99 -14
  21. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/sandbox.py +316 -137
  22. deep_agent_cli-0.1.4/agent/sandbox_pool.py +369 -0
  23. deep_agent_cli-0.1.4/agent/sandbox_worker.py +172 -0
  24. deep_agent_cli-0.1.4/agent/server/__init__.py +1 -0
  25. deep_agent_cli-0.1.4/agent/server/app.py +181 -0
  26. deep_agent_cli-0.1.4/agent/server/config.py +88 -0
  27. deep_agent_cli-0.1.4/agent/server/main.py +29 -0
  28. deep_agent_cli-0.1.4/agent/server/runtime.py +270 -0
  29. deep_agent_cli-0.1.4/agent/server/store.py +157 -0
  30. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/stream.py +10 -0
  31. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/tools/execute.py +19 -9
  32. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/tools/human_interaction.py +12 -0
  33. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/pyproject.toml +2 -1
  34. deep_agent_cli-0.1.2/PKG-INFO +0 -202
  35. deep_agent_cli-0.1.2/README.md +0 -174
  36. deep_agent_cli-0.1.2/agent/config.example.yaml +0 -148
  37. deep_agent_cli-0.1.2/agent/llm.py +0 -391
  38. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/.gitignore +0 -0
  39. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/LICENSE +0 -0
  40. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/__init__.py +0 -0
  41. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/attachments.py +0 -0
  42. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/bootstrap.py +0 -0
  43. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/__init__.py +0 -0
  44. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/clipboard.py +0 -0
  45. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/gitinfo.py +0 -0
  46. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/input.py +0 -0
  47. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/pasted_content.py +0 -0
  48. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/previews.py +0 -0
  49. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/working_messages.py +0 -0
  50. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/cli/working_messages.yaml +0 -0
  51. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/control.py +0 -0
  52. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/file_mutation.py +0 -0
  53. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/middleware/__init__.py +0 -0
  54. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/middleware/cancel_tools.py +0 -0
  55. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/middleware/pause.py +0 -0
  56. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/middleware/recovery.py +0 -0
  57. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/middleware/runtime_config.py +0 -0
  58. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/middleware/steering.py +0 -0
  59. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/middleware/tool_arg_hints.py +0 -0
  60. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/middleware/workspace_filesystem.py +0 -0
  61. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/middleware/write_operation.py +0 -0
  62. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/session.py +0 -0
  63. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/session_lock.py +0 -0
  64. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/session_runtime.py +0 -0
  65. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/tools/__init__.py +0 -0
  66. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/tools/examples.py +0 -0
  67. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/tools/human_input.py +0 -0
  68. {deep_agent_cli-0.1.2 → deep_agent_cli-0.1.4}/agent/tools/web_search.py +0 -0
@@ -0,0 +1,355 @@
1
+ Metadata-Version: 2.4
2
+ Name: deep-agent-cli
3
+ Version: 0.1.4
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
+ Provides-Extra: dev
24
+ Requires-Dist: build<2,>=1.2; extra == 'dev'
25
+ Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
26
+ Requires-Dist: twine<7,>=6; extra == 'dev'
27
+ Provides-Extra: server
28
+ Requires-Dist: fastapi<1,>=0.115; extra == 'server'
29
+ Requires-Dist: uvicorn<1,>=0.30; extra == 'server'
30
+ Description-Content-Type: text/markdown
31
+
32
+ # deep-agent-cli
33
+
34
+ `deep-agent` 是一个在终端中运行的 Coding Agent,支持 Linux 和 WSL2。它把启动时所在的目录作为工作区,调用你配置的 OpenAI 兼容模型服务,并在 [Bubblewrap](https://github.com/containers/bubblewrap) 沙箱中执行命令。Agent 运行时基于 [Deep Agents](https://github.com/langchain-ai/deepagents) 和 LangGraph 构建。
35
+
36
+ 当前版本 0.1.4,处于早期开发阶段。第一个稳定版之前,配置格式、会话存储格式和 Python API 都可能出现不兼容变更。
37
+
38
+ ## 功能
39
+
40
+ - **文件操作**:在工作区中列目录、读、写、编辑、搜索、删除文件。
41
+ - **命令执行**:在 Bubblewrap 沙箱中运行 shell 命令,默认没有网络;输出实时显示。
42
+ - **审批**:默认 `ask` 模式下,每次运行命令、Web 搜索、写入、编辑、删除文件前都会请求你确认。
43
+ - **会话**:按工作区保存在本地 SQLite 中,可以随时恢复。
44
+ - **多模型**:在配置文件中定义多个模型,运行中切换模型和推理强度。支持 Chat Completions 和 Responses 两种接口。
45
+ - **流式输出**:思考内容和回答都流式显示;思考区默认保留按终端宽度折行后的末尾 5 行正文,`Ctrl+T` 展开。
46
+ - **运行中干预**:任务执行时可以追加指令、排队后续任务或取消。
47
+ - **图片输入**:向声明支持图片的模型发送图片。
48
+ - **结构化提问**:Agent 需要你做决定时,会弹出单选、多选、是/否或文本输入。
49
+ - **上下文压缩**:接近模型上下文窗口时自动摘要旧对话,也可以手动压缩。
50
+ - **技能**:从 `~/.deep-agent/skills/` 加载 Skills,通过 `/skill` 选择技能并附带任务说明,支持读取技能目录中的参考文件。
51
+ - **可选扩展**:配置 Tavily API key 后可以搜索公开网页;读取工作区根目录的 `AGENTS.md` 作为项目说明。
52
+ - **HTTP 后端服务**:通过可选 `server` 依赖提供后台任务、SSE 进度、会话恢复和系统界面审批,见 [后端接入](docs/server.md)。
53
+
54
+ ## 运行要求
55
+
56
+ - Linux 或 WSL2。WSL1、原生 Windows 和 macOS 无法使用沙箱。
57
+ - Python 3.12 或更高版本(CI 测试 3.12 和 3.13)。
58
+ - Bubblewrap,并且系统允许非特权 user namespace。Ubuntu 24.04 默认限制这一点,处理方法见 [沙箱排查](https://github.com/ADaozz/deep_agent_cli/blob/main/docs/sandbox.md#排查ubuntu--wsl2)。
59
+ - 一个 OpenAI 兼容的模型服务(本地或远程)及其 API key。
60
+
61
+ ## 安装
62
+
63
+ Debian / Ubuntu:
64
+
65
+ ```bash
66
+ sudo apt install pipx bubblewrap
67
+ pipx ensurepath # 之后重新打开终端
68
+ pipx install deep-agent-cli
69
+ deep-agent --version
70
+ ```
71
+
72
+ 系统 Python 低于 3.12 时,安装一个新版本的 Python,然后指定解释器(不要替换发行版自带的 `/usr/bin/python3`):
73
+
74
+ ```bash
75
+ pipx install --python /path/to/python3.12 deep-agent-cli
76
+ ```
77
+
78
+ 也可以装进虚拟环境:`python3 -m venv ~/.venvs/deep-agent && ~/.venvs/deep-agent/bin/pip install deep-agent-cli`。
79
+
80
+ ## 快速开始
81
+
82
+ **1. 生成配置文件**
83
+
84
+ ```bash
85
+ deep-agent
86
+ ```
87
+
88
+ 首次运行会创建 `~/.deep-agent/config.yaml` 和 `~/.deep-agent/skills/`,然后退出。
89
+
90
+ **2. 配置模型**
91
+
92
+ 编辑 `~/.deep-agent/config.yaml`,把 `llm` 部分改成你的服务:
93
+
94
+ ```yaml
95
+ llm:
96
+ default: token-plan/qwen3.8-flash
97
+ models:
98
+ token-plan:
99
+ base_url: https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
100
+ api_key: ${TOKEN_PLAN_API_KEY}
101
+ api: chat_completions
102
+ reasoning_efforts: [none, low, medium, xhigh]
103
+ models:
104
+ qwen3.8-flash:
105
+ input: [text, image]
106
+ context_window: 1m
107
+ ```
108
+
109
+ 模型按「来源」分组。来源下可以写的字段,模型项中也都可以写:模型项省略则继承来源,写了就覆盖。列表字段(`input`、`reasoning_efforts`)是整表替换,不是合并;`reasoning_efforts` 写成 `null` 或 `[]` 会清除继承。
110
+
111
+ `api` 未填写时默认为 `responses`(Responses API),只提供 Chat Completions 的服务需要显式写 `chat_completions`。
112
+
113
+ 配置只接受 `api: responses/chat_completions`;`provider`、`stream_usage` 已移除,出现时直接报错。Chat Completions 固定请求 usage。右下角 Context 仅显示最近一次 API 返回的输入 token 占用,缺失时显示 `Unknown`,不做估算。
114
+
115
+ `reasoning_efforts` 需要按服务商文档填写,程序不会自动探测。常见取值包括 `none`、`low`、`medium`、`high`、`xhigh`、`max`,同一模型在不同端点上可能不同。列表非空时,`/model` 只显示这些值,默认选中第一项;空列表或未配置时只显示 `default`,请求不携带强度参数。`default` 是 CLI 选项,不能写进列表。`none` 仅在端点明确支持关闭思考时才写;`low` 仍然会思考。Chat Completions 发送 `reasoning_effort`,Responses API 发送 `reasoning.effort`。
116
+
117
+ 其他字段和服务商示例见 [配置参考](https://github.com/ADaozz/deep_agent_cli/blob/main/docs/configuration.md)。
118
+
119
+ **3. 在项目目录中启动**
120
+
121
+ ```bash
122
+ cd ~/projects/my-app
123
+ deep-agent
124
+ ```
125
+
126
+ 启动时会先检查沙箱是否可用;不可用时程序给出诊断信息并拒绝启动。界面中直接输入任务即可,以 `/` 开头的输入是命令。
127
+
128
+ **4. 恢复会话**
129
+
130
+ ```bash
131
+ deep-agent resume # 选择一个已保存的会话
132
+ deep-agent resume 01a08aae # 按 id 或前缀恢复
133
+ ```
134
+
135
+ 恢复只加载会话状态,不会自动继续执行未完成的任务。
136
+
137
+ ## 常用操作
138
+
139
+ | 命令 | 作用 |
140
+ |---|---|
141
+ | `/help` | 列出命令和快捷键 |
142
+ | `/status` | 当前模型、权限模式、沙箱状态 |
143
+ | `/model` | 选择模型和推理强度 |
144
+ | `/skill` | 选择技能,在输入框插入技能名称块 |
145
+ | `/permission ask\|allow` | 切换审批模式 |
146
+ | `/resume`、`/new` | 切换到已有会话、新建会话 |
147
+ | `/compact` | 手动压缩上下文 |
148
+ | `/image <路径>` | 为下一条消息附加图片 |
149
+ | `/quit` | 退出 |
150
+
151
+ 输入 `/` 显示命令候选,按连续子串匹配,例如 `/elp` 匹配 `/help`,`/hlp` 不匹配。完整匹配和前缀匹配优先;方向键选择,`Tab` 或 `Enter` 填入,退格后重新计算候选。`/model ` 和 `/permission ` 的参数也支持补全。
152
+
153
+ | 按键 | 作用 |
154
+ |---|---|
155
+ | `Enter` | 提交;任务运行中提交为追加指令 |
156
+ | `Ctrl+J` | 换行 |
157
+ | `Alt+Enter` | 排队,当前任务结束后执行 |
158
+ | `Esc` | 取消当前任务 |
159
+ | `F2` | 重新打开待处理的审批或提问 |
160
+ | `Ctrl+O` / `Ctrl+T` | 展开工具详情 / 思考内容 |
161
+ | `Ctrl+R` | 查看文件改动 |
162
+ | `Ctrl+P` | 切换到下一个模型 |
163
+ | `Ctrl+C` | 清空输入;连按两次退出 |
164
+
165
+ 完整的命令、按键和界面行为见 [终端界面](https://github.com/ADaozz/deep_agent_cli/blob/main/docs/tui.md)。
166
+
167
+ ## 使用 Skills
168
+
169
+ 每个技能放在 `~/.deep-agent/skills/` 下的独立目录中,入口文件为 `SKILL.md`。其 YAML 头部必须包含 `name` 和 `description`;技能列表显示 `name`,缺少有效元数据的目录会被跳过。
170
+
171
+ ### 安装示例:Playwright CLI
172
+
173
+ 准备好 Node.js 和 npm 后,在终端执行以下命令。先使用[微软官方 Playwright CLI](https://github.com/microsoft/playwright-cli#installing-skills) 的安装命令生成 Skill,再复制到本项目使用的目录:
174
+
175
+ ```bash
176
+ mkdir -p ~/.deep-agent/skills
177
+ cd ~/.deep-agent/skills
178
+
179
+ # 如果还没安装 CLI
180
+ npm install -g @playwright/cli@latest
181
+
182
+ # 安装官方 Skill 到临时目录
183
+ skill_tmp_dir="$(mktemp -d)"
184
+ (cd "$skill_tmp_dir" && playwright-cli install --skills=agents)
185
+
186
+ # 复制到 DeepAgent 的技能目录
187
+ cp -a "$skill_tmp_dir/.agents/skills/playwright-cli" ~/.deep-agent/skills/
188
+
189
+ # 清理临时目录
190
+ rm -rf "$skill_tmp_dir"
191
+ ```
192
+
193
+ 验证安装:
194
+
195
+ ```bash
196
+ ls -R ~/.deep-agent/skills/playwright-cli
197
+ ```
198
+
199
+ 安装后目录结构如下,`references/` 中的参考文档也能读取:
200
+
201
+ ```text
202
+ ~/.deep-agent/
203
+ └── skills/
204
+ └── playwright-cli/
205
+ ├── SKILL.md
206
+ └── references/
207
+ ├── playwright-tests.md
208
+ ├── request-mocking.md
209
+ ├── running-code.md
210
+ ├── session-management.md
211
+ ├── storage-state.md
212
+ ├── test-generation.md
213
+ ├── tracing.md
214
+ ├── video-recording.md
215
+ ├── element-attributes.md
216
+ └── pr-attachments.md
217
+ ```
218
+
219
+ ### 在输入框中调用技能
220
+
221
+ 在 CLI 中输入 `/skill` 后回车,用上下键选择技能,再回车将 `[Skill: playwright-cli]` 插入输入框。此时可以直接回车调用,也可以追加说明后提交:
222
+
223
+ ```text
224
+ [Skill: playwright-cli] 检查当前项目页面的登录流程,并记录截图。
225
+ ```
226
+
227
+ 选择时按 `Esc` 取消;完整删除输入框中的技能块即可取消本次技能调用。技能列表在每次打开时重新读取目录。发送后的聊天记录仍显示技能名称块和附带说明,恢复会话时也保持这一显示方式。
228
+
229
+ 技能目录以只读方式映射到 `/skills/`。DeepAgent 原生 SkillsMiddleware 加载技能名称和描述;提交时携带所选技能的名称及路径,由模型按需读取 `/skills/playwright-cli/SKILL.md` 和相关参考文件,技能正文不会整段展开到输入框中。
230
+
231
+ 加载技能只提供操作说明。工具链要在宿主机装好,再通过沙箱挂载暴露给命令。沙箱不能 `sudo` 或 `apt-get`,所以不要在里面执行 `npx playwright install chrome`。
232
+
233
+ `network=false` 使用 Bubblewrap 的独立网络命名空间(`--unshare-net`),限制本次命令及子进程直接访问 IP 网络;不保证完全没有间接联网。例如有网后台服务在共享 `/workspace` 创建 Unix Socket,无网命令通过它请求服务代为联网;共享文件或 FIFO 也可形成类似通路。这是已知隔离边界,不是沙箱逃逸,也不表示本轮已修复。见 [网络边界](docs/sandbox.md#网络)。
234
+
235
+ ### 沙箱里的工具链
236
+
237
+ 首次启动时,[`agent/config.example.yaml`](agent/config.example.yaml) 会复制成 `~/.deep-agent/config.yaml`。其中的 `sandbox` 段已经是默认工具链配置:`PATH` 包含 Node.js 和 Cargo,并挂载下面这些目录。`optional: true` 的源目录在宿主机上不存在时会被跳过,不会阻止启动。
238
+
239
+ | 宿主机路径 | 沙箱路径 | 权限 | 用途 |
240
+ |---|---|---|---|
241
+ | `~/.nvm/versions/node/v22.23.2` | `/opt/node` | 只读 | `node`、`npm`、`playwright-cli` |
242
+ | `~/.cargo` | `/opt/cargo` | 只读 | Rust 工具链 |
243
+ | `/opt/google` | `/opt/google` | 只读 | 系统 Chrome。`playwright-cli open` 使用 `/opt/google/chrome/chrome` |
244
+ | `/mnt/wslg/.X11-unix` | `/tmp/.X11-unix` | 只读 | WSLg 的 X11 文件 socket,供有头浏览器连接宿主显示服务 |
245
+ | `~/.cache/ms-playwright` | `/opt/ms-playwright` | 可写 | CLI 版本对应的 Chromium / Chrome for Testing。环境变量 `PLAYWRIGHT_BROWSERS_PATH` 指向这里 |
246
+
247
+ Node.js 版本以本机 `~/.nvm/versions/node/` 下的目录名为准,和模板不一致时改 `source`。其他装在 `~/.local`、`/opt` 或家目录里的程序同样处理:用 `readlink -f "$(command -v 工具名)"` 找到落在 `/usr`、`/bin`、`/lib` 之外的目录,按同样格式追加挂载,并把可执行文件所在目录加到 `PATH` 前面。`PATH` 会替换沙箱默认值,末尾保留 `/usr/local/bin:/usr/bin:/bin`。
248
+
249
+ `playwright-cli open` 默认走系统 Chrome(通常位于 `/opt/google/chrome/chrome`),而 `playwright-cli open --browser=chromium` 选择 CLI 依赖版本对应的缓存 Chromium。没有系统 Chrome 时,先在宿主机查看当前版本的帮助,再安装浏览器:
250
+
251
+ ```bash
252
+ playwright-cli install-browser --help
253
+ playwright-cli install-browser chromium
254
+ ```
255
+
256
+ 不要用独立的 `npx playwright install chromium` 代替:它可能解析到另一版 Playwright,下载的浏览器修订号与 CLI 查找的缓存目录不同。命令以实际安装的 CLI 帮助为准;本轮核对的 CLI 0.1.22 支持上述命令(包括 `--dry-run`),不要求锁定项目 Node 或 Playwright 版本。缓存目录可写时,沙箱中的安装和删除会改宿主机上的同一目录;只使用已安装浏览器且需要只读缓存时,先从 `extra_read_write_mounts` 移除该项,再加入 `extra_read_only_mounts`,不要在两个列表中重复配置同一目标。下载浏览器需要网络,由用户在宿主机完成。
257
+
258
+ Node 本体也可以来自系统 `/usr/bin/node`。若 CLI 和 npm 包安装在自定义 npm prefix(例如 `npm config get prefix` 返回 `~/.local`),必须挂载整个 prefix,而不只是它的 `bin` 目录,再调整 `PATH`。系统 Node 已在默认只读系统目录内,无需 nvm:
259
+
260
+ ```yaml
261
+ sandbox:
262
+ extra_read_only_mounts:
263
+ - source: ~/.local # 替换为本机 npm prefix
264
+ destination: /opt/npm-prefix
265
+ env_set:
266
+ PATH: /opt/npm-prefix/bin:/usr/local/bin:/usr/bin:/bin
267
+ PLAYWRIGHT_BROWSERS_PATH: /opt/ms-playwright
268
+ ```
269
+
270
+ 此示例只新增 npm prefix 挂载;浏览器缓存沿用默认模板中的 `extra_read_write_mounts`,目标仍为 `/opt/ms-playwright`,不要重复添加。
271
+
272
+ 使用系统 Chrome 时保留 `/opt/google` 的只读挂载。系统目录以外的 Node 本体则需要另行只读挂载,并把其 `bin` 加到 `PATH`。
273
+
274
+ 有头模式需要宿主提供 X Server、传入 `DISPLAY`,并让沙箱访问显示 socket。默认模板已允许 `DISPLAY`,并可选挂载 WSLg 的 `/mnt/wslg/.X11-unix` 到沙箱 `/tmp/.X11-unix`。在 WSLg 环境中可直接复用现有显示服务,无需另装 Xvfb。启动 `deep-agent` 的终端必须已有正确的 `DISPLAY`(WSLg 通常为 `:0`)。
275
+
276
+ 已有配置请合并以下内容,保留其他环境变量和挂载:
277
+
278
+ ```yaml
279
+ sandbox:
280
+ env_allowlist:
281
+ - DISPLAY
282
+ extra_read_only_mounts:
283
+ - source: /mnt/wslg/.X11-unix
284
+ destination: /tmp/.X11-unix
285
+ optional: true
286
+ ```
287
+
288
+ 保存后退出并重新启动 `deep-agent`,让新沙箱加载配置,再执行 `playwright-cli open about:blank --headed`。已在 WSLg 下实测 `network=false` 的有头启动、页面截图及关闭成功;访问互联网页面仍需要声明 `network=true`,ask 模式需审批。此配置允许沙箱连接宿主 X Server,不改变 IP 网络或 IPC 隔离。
289
+
290
+ 普通 Linux X11 桌面可把挂载源改为 `/tmp/.X11-unix`。仅使用 X11 抽象 socket 时,无网沙箱无法访问宿主网络命名空间中的该 socket,需要有网沙箱。Xauthority 认证可能需要传入 `XAUTHORITY` 并挂载对应认证文件,该场景未验证;原生 Wayland 连接也未验证,WSLg 此处使用的是 X11。
291
+
292
+ 保留 Bubblewrap 的 `--unshare-ipc`。用户提供的真实机器 A/B 验证表明,在专用 Xvfb 关闭 MIT-SHM 可以稳定渲染,无需添加 Chrome 启动参数:
293
+
294
+ ```bash
295
+ Xvfb :2 -screen 0 1600x900x24 -extension MIT-SHM
296
+ # 启动 deep-agent 前设置 DISPLAY=:2,并在 env_allowlist 中允许 DISPLAY
297
+ ```
298
+
299
+ Xvfb 示例仅适用于宿主没有现成显示服务的情况;CLI 不会自动安装 Node、浏览器或 Xvfb。有头渲染必须通过实际 X 窗口截图核验;读取 title、DOM 或看到窗口存在不足以证明渲染成功。详细 A/B 结果和挂载说明见 [docs/sandbox.md](docs/sandbox.md#playwright-与有头-x11)。Playwright CLI 可能生成 `.playwright-cli/`,建议在自己的项目 `.gitignore` 中忽略它;程序不会自动修改 `.gitignore`。
300
+
301
+ 已经存在的 `~/.deep-agent/config.yaml` 不会被模板覆盖。把模板里的 `sandbox.env_allowlist`、`sandbox.env_set` 和两个挂载列表合并进现有文件,保存后退出并重新启动 `deep-agent`。挂载规则见 [沙箱与权限](https://github.com/ADaozz/deep_agent_cli/blob/main/docs/sandbox.md)。
302
+
303
+ ## 安全模型
304
+
305
+ | | 行为 |
306
+ |---|---|
307
+ | 命令能访问的文件 | 工作区(读写,在沙箱中为 `/workspace`)、`~/.deep-agent/skills/`(只读)、系统的 `/usr`、`/bin`、`/lib`(只读)。家目录的其余部分不可见 |
308
+ | 网络 | 命令默认无网络。模型可以为单条命令申请网络,此时它能访问互联网、`localhost` 和局域网 |
309
+ | 沙箱复用 | 每个会话最多一个无网沙箱和一个有网沙箱,按需启动、跨命令复用(`/tmp` 和后台进程保留),会话结束时销毁。切换模型或权限模式不重建沙箱;`ask` / `allow` 只决定之后的命令要不要审批 |
310
+ | 环境变量 | 只传入 `LANG`、`TERM` 等少量变量,其余需在配置中显式列出 |
311
+ | `ask` 模式(默认) | 每次运行命令、Web 搜索、写入、编辑、删除文件前需要确认 |
312
+ | `allow` 模式 | 所有工具自动批准,所有命令都开放网络。仅在沙箱可用时可开启,开启时需输入 `ALLOW` |
313
+ | 沙箱不可用 | 拒绝启动。只有在配置中设置 `sandbox.allow_unsandboxed: true`,或在启动提示中输入 `UNSANDBOXED`,命令才会以当前用户身份直接在宿主机上运行,此时只能使用 `ask` 模式 |
314
+
315
+ 细节见 [沙箱与权限](https://github.com/ADaozz/deep_agent_cli/blob/main/docs/sandbox.md)。
316
+
317
+ ## 已知限制
318
+
319
+ - 沙箱不限制 CPU、内存和磁盘用量。
320
+ - 沙箱中只有系统目录下的程序。安装在 `~/.local`、`~/.nvm`、`/opt` 等位置的工具链默认不可用,需要在配置中添加只读挂载。
321
+ - 文件工具在 `deep-agent` 进程中直接读写宿主文件,不经过沙箱,路径限定在工作区和 Skills 目录内。工作区里的所有内容 Agent 都能读写,包括 `.git/` 和 `.env`。
322
+ - 程序会在工作区中创建 `.deep-agent/`(命令输出超限时的日志)和 `.deepagents/`(上下文压缩时保存的历史),但不会修改 `.gitignore`。
323
+ - 不能在家目录或其上层目录启动,因为配置目录 `~/.deep-agent` 必须位于工作区之外。
324
+ - CLI 需要交互式终端;非交互调用使用可选的 [HTTP 服务](docs/server.md)。
325
+ - 模型请求和 Tavily 请求不读取 `HTTP_PROXY`、`HTTPS_PROXY`、`ALL_PROXY` 等代理环境变量。
326
+ - 从剪贴板粘贴图片只支持 WSL;其他环境需要通过文件路径添加图片。
327
+ - 推理强度的可选值需要按服务商文档手动配置,程序不会自动探测。
328
+ - 不支持 MCP,也没有子 Agent。
329
+ - 同一个会话同一时间只能被一个进程打开。
330
+
331
+ ## 文档
332
+
333
+ - [配置参考](https://github.com/ADaozz/deep_agent_cli/blob/main/docs/configuration.md):所有配置项、模型与推理强度、Web 搜索、按键、环境变量
334
+ - [沙箱与权限](https://github.com/ADaozz/deep_agent_cli/blob/main/docs/sandbox.md):隔离范围、网络、日志、Ubuntu / WSL2 排查
335
+ - [终端界面](https://github.com/ADaozz/deep_agent_cli/blob/main/docs/tui.md):命令、快捷键、图片、会话、显示规则
336
+ - [作为 Python 库使用](https://github.com/ADaozz/deep_agent_cli/blob/main/docs/library.md):`AgentRunner`、事件、自定义工具
337
+ - [HTTP 后端服务](docs/server.md):部署、接口、任务与事件、审批和现有系统接入
338
+ - [架构](https://github.com/ADaozz/deep_agent_cli/blob/main/docs/architecture.md):分层、中间件、会话存储、上下文压缩
339
+ - [开发](https://github.com/ADaozz/deep_agent_cli/blob/main/docs/development.md):测试、冒烟脚本、CI 与发布
340
+
341
+ ## 开发
342
+
343
+ ```bash
344
+ git clone https://github.com/ADaozz/deep_agent_cli.git
345
+ cd deep_agent_cli
346
+ python3 -m venv .venv && source .venv/bin/activate
347
+ pip install -e ".[dev]"
348
+ pytest -q
349
+ ```
350
+
351
+ 自动测试不调用真实模型。欢迎提交 Issue 和 Pull Request;修改行为时请附带测试。更多说明见 [开发文档](https://github.com/ADaozz/deep_agent_cli/blob/main/docs/development.md)。
352
+
353
+ ## 许可证
354
+
355
+ [MIT](https://github.com/ADaozz/deep_agent_cli/blob/main/LICENSE)