deep-agent-cli 0.1.7__tar.gz → 0.1.9__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 (89) hide show
  1. deep_agent_cli-0.1.9/PKG-INFO +244 -0
  2. deep_agent_cli-0.1.9/README.md +213 -0
  3. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/app.py +364 -64
  4. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/commands.py +24 -5
  5. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/interactions.py +129 -2
  6. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/main.py +31 -68
  7. deep_agent_cli-0.1.9/agent/cli/mcp_ui.py +608 -0
  8. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/previews.py +2 -2
  9. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/rendering.py +46 -18
  10. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/session_controller.py +2 -6
  11. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/state.py +24 -4
  12. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/config.example.yaml +65 -34
  13. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/config.py +94 -9
  14. deep_agent_cli-0.1.9/agent/environment.py +405 -0
  15. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/factory.py +116 -59
  16. deep_agent_cli-0.1.9/agent/http_environment.py +28 -0
  17. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/llm.py +152 -11
  18. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/llm_stream.py +34 -0
  19. deep_agent_cli-0.1.9/agent/mcp/__init__.py +4 -0
  20. deep_agent_cli-0.1.9/agent/mcp/adapter.py +327 -0
  21. deep_agent_cli-0.1.9/agent/mcp/bridge.py +168 -0
  22. deep_agent_cli-0.1.9/agent/mcp/config.py +336 -0
  23. deep_agent_cli-0.1.9/agent/mcp/content.py +46 -0
  24. deep_agent_cli-0.1.9/agent/mcp/logging.py +17 -0
  25. deep_agent_cli-0.1.9/agent/mcp/manager.py +709 -0
  26. deep_agent_cli-0.1.9/agent/mcp/middleware.py +28 -0
  27. deep_agent_cli-0.1.9/agent/mcp/names.py +56 -0
  28. deep_agent_cli-0.1.9/agent/mcp/oauth.py +47 -0
  29. deep_agent_cli-0.1.9/agent/mcp/oauth_storage.py +39 -0
  30. deep_agent_cli-0.1.9/agent/mcp/tools.py +63 -0
  31. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/middleware/workspace_filesystem.py +3 -3
  32. deep_agent_cli-0.1.9/agent/performance.py +117 -0
  33. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/permission.py +7 -10
  34. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/runner.py +146 -18
  35. deep_agent_cli-0.1.9/agent/sandbox.py +1976 -0
  36. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/sandbox_pool.py +4 -4
  37. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/sandbox_worker.py +8 -2
  38. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/session.py +26 -0
  39. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/stream.py +77 -1
  40. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/tools/execute.py +33 -7
  41. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/tools/grep.py +26 -8
  42. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/tools/web_search.py +3 -3
  43. deep_agent_cli-0.1.9/agent/version.py +9 -0
  44. deep_agent_cli-0.1.9/assets/readme/runtime-map.svg +56 -0
  45. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/pyproject.toml +6 -5
  46. deep_agent_cli-0.1.9//347/273/210/347/253/257.png +0 -0
  47. deep_agent_cli-0.1.7/PKG-INFO +0 -216
  48. deep_agent_cli-0.1.7/README.md +0 -184
  49. deep_agent_cli-0.1.7/agent/sandbox.py +0 -939
  50. deep_agent_cli-0.1.7/agent/server/__init__.py +0 -1
  51. deep_agent_cli-0.1.7/agent/server/app.py +0 -181
  52. deep_agent_cli-0.1.7/agent/server/config.py +0 -88
  53. deep_agent_cli-0.1.7/agent/server/main.py +0 -29
  54. deep_agent_cli-0.1.7/agent/server/runtime.py +0 -296
  55. deep_agent_cli-0.1.7/agent/server/store.py +0 -157
  56. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/.gitignore +0 -0
  57. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/LICENSE +0 -0
  58. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/__init__.py +0 -0
  59. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/attachments.py +0 -0
  60. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/bootstrap.py +0 -0
  61. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cancel.py +0 -0
  62. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/__init__.py +0 -0
  63. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/clipboard.py +0 -0
  64. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/gitinfo.py +0 -0
  65. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/input.py +0 -0
  66. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/pasted_content.py +0 -0
  67. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/skills.py +0 -0
  68. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/working_messages.py +0 -0
  69. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/cli/working_messages.yaml +0 -0
  70. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/control.py +0 -0
  71. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/file_mutation.py +0 -0
  72. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/middleware/__init__.py +0 -0
  73. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/middleware/attachments.py +0 -0
  74. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/middleware/cancel_tools.py +0 -0
  75. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/middleware/pause.py +0 -0
  76. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/middleware/recovery.py +0 -0
  77. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/middleware/runtime_config.py +0 -0
  78. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/middleware/steering.py +0 -0
  79. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/middleware/tool_arg_hints.py +0 -0
  80. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/middleware/usage.py +0 -0
  81. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/middleware/write_operation.py +0 -0
  82. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/network.py +0 -0
  83. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/session_lock.py +0 -0
  84. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/session_runtime.py +0 -0
  85. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/tools/__init__.py +0 -0
  86. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/tools/_grep_worker.py +0 -0
  87. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/tools/examples.py +0 -0
  88. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/tools/human_input.py +0 -0
  89. {deep_agent_cli-0.1.7 → deep_agent_cli-0.1.9}/agent/tools/human_interaction.py +0 -0
@@ -0,0 +1,244 @@
1
+ Metadata-Version: 2.4
2
+ Name: deep-agent-cli
3
+ Version: 0.1.9
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: cryptography<51,>=43
14
+ Requires-Dist: deepagents<0.8.0,>=0.7.17
15
+ Requires-Dist: httpx[socks]<1,>=0.27
16
+ Requires-Dist: langchain-core<2.0,>=1.0
17
+ Requires-Dist: langchain-openai<1.7.0,>=1.6.2
18
+ Requires-Dist: langchain[mcp]<2.0,>=1.4.2
19
+ Requires-Dist: langgraph-checkpoint-sqlite<4,>=3.1.1
20
+ Requires-Dist: langgraph<2.0,>=1.0
21
+ Requires-Dist: prompt-toolkit<4.0,>=3.0.48
22
+ Requires-Dist: py-key-value-aio[filetree]<0.5,>=0.4.4
23
+ Requires-Dist: pyyaml<7.0,>=6.0
24
+ Requires-Dist: rich<15.0,>=13.9
25
+ Requires-Dist: ripgrep-bin<16,>=15.2.0
26
+ Provides-Extra: dev
27
+ Requires-Dist: build<2,>=1.2; extra == 'dev'
28
+ Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
29
+ Requires-Dist: twine<7,>=6; extra == 'dev'
30
+ Description-Content-Type: text/markdown
31
+
32
+ <div align="center">
33
+
34
+ # deep-agent-cli
35
+
36
+ **在终端中理解代码、审阅修改、运行命令。**
37
+
38
+ Linux / WSL2 · Python 3.12+<br>
39
+ OpenAI 兼容接口 · Bubblewrap
40
+
41
+ [快速开始](#快速开始) · [常用操作](#常用操作) · [架构与安全](#架构与安全) · [文档](#文档)
42
+
43
+ </div>
44
+
45
+ <p align="center">
46
+ <img src="终端.png" width="760" alt="deep-agent 真实终端空闲界面,底栏显示工作区、模型来源、SANDBOXED 和 perm:ask。">
47
+ </p>
48
+
49
+ `deep-agent` 是基于 [Deep Agents](https://github.com/langchain-ai/deepagents) 和 LangGraph 的终端 Coding Agent。它在当前项目中工作,默认在文件变更、命令执行和网页搜索前请求批准,通过 [Bubblewrap](https://github.com/containers/bubblewrap) 隔离命令执行。
50
+
51
+ 在项目目录运行 `deep-agent` 进入交互式终端,用 `deep-agent resume` 恢复已有会话。要在其他 Python 程序里复用同一套运行核心,使用 [Python API](docs/library.md)。
52
+
53
+ > 当前版本 **0.1.9**,处于早期开发阶段。稳定版前,配置、会话存储格式和 Python API 可能出现不兼容变更。
54
+
55
+ ## 能做什么
56
+
57
+ - **查代码、改文件** — 浏览、读取、正则搜索、编辑和删除;`Ctrl+R` 审阅完整改动,`F2` 处理审批。
58
+ - **运行项目命令** — 实时查看输出,会话内复用持久沙箱;默认审批、隔离直接 IP 网络。
59
+ - **随时介入任务** — 追加指令、排队后续任务、暂停、取消,以及结构化人工输入。
60
+ - **保留工作上下文** — SQLite 会话恢复、模型与推理强度切换、上下文压缩;支持图片输入的模型可接收附件。
61
+
62
+ 支持通过 Skills 和 `AGENTS.md` 扩展项目指令。
63
+
64
+ ## 快速开始
65
+
66
+ 需要 **Linux / WSL2、Python 3.12+、Bubblewrap**,以及支持 Chat Completions 或 Responses 的模型端点。CLI 需要交互式终端;原生 Windows、macOS 和 WSL1 不支持这套沙箱。Ubuntu / WSL2 的 user namespace 限制见 [沙箱排查](docs/sandbox.md#排查ubuntu--wsl2)。
67
+
68
+ 使用 Node 编写的 stdio MCP 服务或通过 `execute` 运行 Node 工具时,推荐 **Node.js 24(使用最新的 24.x 补丁版本)**;具体 MCP 服务仍以其自身的版本要求为准。
69
+
70
+ ### 1. 安装
71
+
72
+ Debian / Ubuntu:
73
+
74
+ ```bash
75
+ sudo apt install pipx bubblewrap
76
+ pipx ensurepath
77
+ # 重新打开终端后安装
78
+ pipx install deep-agent-cli
79
+ deep-agent --version
80
+ ```
81
+
82
+ 系统默认 Python 低于 3.12 时,使用 `pipx install --python /path/to/python3.12 deep-agent-cli` 指定已安装的解释器。ripgrep 随 Python 依赖安装,无需另行安装。
83
+
84
+ ### 2. 初始化与配置
85
+
86
+ 从项目目录启动,首次运行会创建 `~/.deep-agent/config.yaml` 和 Skills 目录,然后退出。已有配置不会被覆盖;设置了 `DEEP_AGENT_CONFIG` 时使用指定配置。
87
+
88
+ ```bash
89
+ cd ~/projects/my-app # 替换为你的项目目录
90
+ deep-agent
91
+ ```
92
+
93
+ 配置、Skills 和按键配置目录必须位于工作区之外,**不要将家目录或其上层目录作为工作区**。
94
+
95
+ 默认模板提供可选的 Node、Cargo / Rustup、Chrome、X11 和浏览器缓存挂载。NVM 挂载整个版本目录,使用哪个版本由用户在沙箱 `PATH` 中指定;程序不自动发现工具安装位置或选择版本。已有配置需手动对照 [默认挂载说明](docs/configuration.md#默认工具挂载) 合并,升级不会覆盖用户配置。
96
+
97
+ 默认模板使用 `token-plan/qwen3.8-flash`。在启动 Agent 的同一个 Bash 终端中输入对应密钥:
98
+
99
+ ```bash
100
+ read -rsp 'Token Plan API key: ' TOKEN_PLAN_API_KEY
101
+ export TOKEN_PLAN_API_KEY
102
+ printf '\n'
103
+ ```
104
+
105
+ 使用其他模型服务时,编辑 `~/.deep-agent/config.yaml`,调整端点、密钥、模型 ID 及能力配置。`api` 必须与端点匹配;省略时默认为 `responses`,不会自动判断。
106
+
107
+ <details>
108
+ <summary>查看模型配置示例</summary>
109
+
110
+ 以下与默认模板一致;`llm.default` 使用“来源/模型”标识,模型项继承来源级字段,并可单独覆盖。
111
+
112
+ ```yaml
113
+ llm:
114
+ default: token-plan/qwen3.8-flash
115
+ models:
116
+ token-plan:
117
+ base_url: https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
118
+ api_key: ${TOKEN_PLAN_API_KEY}
119
+ api: chat_completions
120
+ reasoning_efforts: [none, low, medium, xhigh]
121
+ models:
122
+ qwen3.8-flash:
123
+ input: [text, image]
124
+ context_window: 1m
125
+ ```
126
+
127
+ 端点、上下文窗口、输入模态和推理强度取决于所选服务,完整说明见 [配置参考](docs/configuration.md)。
128
+
129
+ </details>
130
+
131
+ ### 3. 开始第一个任务
132
+
133
+ 在项目目录再次运行 `deep-agent`,输入:
134
+
135
+ ```text
136
+ 阅读当前项目,列出程序入口、关键模块和测试命令,并注明对应文件。
137
+ 暂不修改文件或执行命令。
138
+ ```
139
+
140
+ 获得项目概览后,可以继续要求一次小范围修改。默认 `ask` 下,文件变更会等待审批:`Ctrl+R` 查看改动,`F2` 打开审批面板。启动检查失败时默认拒绝进入宿主执行,见 [沙箱与权限](docs/sandbox.md)。
141
+
142
+ <details>
143
+ <summary>恢复会话、升级与虚拟环境安装</summary>
144
+
145
+ ```bash
146
+ deep-agent resume # 选择已保存的会话
147
+ deep-agent resume 01a08aae # 换成已有会话的 ID 或前缀
148
+ pipx upgrade deep-agent-cli
149
+ ```
150
+
151
+ 恢复只加载状态,不自动继续未完成任务;旧数据库格式不自动迁移。取消不回滚已发生的文件修改或外部副作用。
152
+
153
+ 不使用 pipx 时,也可安装到虚拟环境:
154
+
155
+ ```bash
156
+ python3.12 -m venv ~/.venvs/deep-agent
157
+ ~/.venvs/deep-agent/bin/pip install deep-agent-cli
158
+ ~/.venvs/deep-agent/bin/deep-agent --version
159
+ ```
160
+
161
+ </details>
162
+
163
+ ## 常用操作
164
+
165
+ | 操作 | 用途 |
166
+ |---|---|
167
+ | `/model` | 切换模型与推理强度 |
168
+ | `Ctrl+R` / `F2` | 审阅文件改动 / 处理审批与提问 |
169
+ | `Enter` / `Alt+Enter` | 提交或运行中追加指令 / 排队后续任务 |
170
+ | `Esc` | 请求取消当前任务 |
171
+ | `Ctrl+O` / `Ctrl+T` | 展开工具输出 / 思考内容 |
172
+ | `/resume` / `/new` | 恢复或新建会话 |
173
+ | `/mcp` | 查看、开关和配置宿主 MCP 服务 |
174
+ | `/help` / `/status` | 查看完整操作与当前状态 |
175
+
176
+ 更多按键、图片附件、队列、Skills 和显示设置见 [终端界面](docs/tui.md)。
177
+
178
+ ## 架构与安全
179
+
180
+ **审批决定是否执行,隔离决定命令能访问哪些资源。** 文件工具和命令走不同通路:
181
+
182
+ - **文件工具 → 宿主进程**:Backend 使用工作区的真实绝对路径(如 `/mnt/d/test`),`/skills` 可写。`restricted` 下,启动时声明的额外挂载按同样的只读或读写属性授权;未声明路径拒绝访问。
183
+ - **命令 → Bubblewrap**:`execute` 经沙箱池运行,会话内按需复用有网、无网 Worker。模型与 Tavily 请求从宿主发送,不受命令网络策略约束。
184
+
185
+ <details>
186
+ <summary>展开运行架构图</summary>
187
+
188
+ ![TUI 进入共享的 AgentRunner 和 Deep Agents / LangGraph;普通文件工具在宿主进程访问授权路径,execute 经 SandboxPool 进入 Bubblewrap Worker。](assets/readme/runtime-map.svg)
189
+
190
+ SQLite 保存会话状态。模型工具表不包含 `grep` 和 `glob`。代码搜索和文件发现通过 `execute` 运行宿主提供、只读挂载进沙箱的 `rg`;搜索的审批与网络和其他命令相同。完整分层与生命周期见 [架构文档](docs/architecture.md)。
191
+
192
+ </details>
193
+
194
+ | 模式 | 审批 | 命令网络 |
195
+ |---|---|---|
196
+ | **沙箱 + `ask`**(默认) | 文件变更、命令、网页搜索、MCP 调用及增删服务需批准 | 默认隔离直接 IP 网络;`network=true` 获批后共享宿主网络 |
197
+ | 沙箱 + `allow` | 所有工具免审批,包括 MCP 工具、`mcp_add`、`mcp_remove` | 所有 execute 共享宿主网络 |
198
+
199
+ 只读文件工具免审批;`/permission` 统一控制原生与 MCP 工具审批,`allow` 仅限沙箱模式。MCP 在宿主进程中运行,不经过 Bubblewrap,也不受沙箱网络策略限制。配置在 `~/.deep-agent/mcp.json`,根级 `enabled` 是全局开关(默认开启);用 `/mcp`、`/mcp enable`、`/mcp disable` 或 `mcp_add` / `mcp_remove` 管理。全局关闭时不连接、不启动 stdio、不打开 OAuth,也不把 MCP 工具交给模型;配置和令牌缓存仍保留。**工作区内的 `.env`、`.git` 同样可访问,取消不回滚已发生的副作用。**
200
+
201
+ 全局开关打开时,启动会自动连接各服务里 `enabled: true` 的项。OAuth 优先使用加密缓存并刷新令牌,无法刷新时打开浏览器授权;无需鉴权的服务直接连接。`/mcp` 先显示 `MCP: Enabled` 或 `MCP: Disabled`,开启时再列出 `服务名 状态 N tools`;`connected` 为绿色,其余状态为红色。连接恢复、附件处理和后台日志见 [MCP 配置](docs/configuration.md#mcpmcpjson),命令和状态说明见 [TUI 文档](docs/tui.md#mcp-服务)。
202
+
203
+ <details>
204
+ <summary>更多边界与当前限制</summary>
205
+
206
+ - **网络与进程**:无网命名空间不阻断通过共享 Unix socket、FIFO 或文件实现的间接通信。有网实例可访问互联网、localhost 和局域网;切回 `ask` 不停止此前的后台进程。会话切换及关闭时清理沙箱。
207
+ - **挂载与资源**:用户可通过现有挂载列表扩大或缩小文件系统可见范围,审批逻辑保持独立。只读挂载仍允许读取其中的敏感文件。没有 CPU、内存、磁盘或进程数硬配额。Skills、`AGENTS.md` 和提示词不是操作系统安全边界。
208
+ - **本地状态**:同一会话只允许一个进程持有;工作区可能产生 `.deep-agent/` 命令日志和 `.deepagents/` 压缩历史,程序不修改 `.gitignore`。
209
+ - **客户端**:模型、MCP、Tavily 和子进程统一使用全局 [`trust_env`](docs/configuration.md#全局网络环境trust_env) 配置,默认忽略代理与 CA 环境变量;剪贴板图片仅支持 WSL,其他环境通过文件添加。MCP 支持 Streamable HTTP 和 stdio 工具调用及工具返回的内嵌资源;不提供独立 Resources / Prompts 接口、Sampling 回调、旧式服务端 Elicitation、MCP Apps UI 或子 Agent。
210
+
211
+ 完整隔离范围与环境变量见 [沙箱与权限](docs/sandbox.md)。
212
+
213
+ </details>
214
+
215
+ ## 文档
216
+
217
+ - **使用**:[配置参考](docs/configuration.md) · [终端界面](docs/tui.md) · [正则搜索](docs/search.md)
218
+ - **机制**:[沙箱与权限](docs/sandbox.md) · [架构设计](docs/architecture.md)
219
+ - **集成**:[Python API](docs/library.md) · [开发指南](docs/development.md)
220
+
221
+ <details>
222
+ <summary>扩展 Skills 与网页搜索</summary>
223
+
224
+ Skills 位于 `~/.deep-agent/skills/<技能目录>/SKILL.md`,使用 `/skill` 选择;配置 Tavily key 后启用 `web_search`。外部工具与浏览器需预先安装并通过沙箱挂载,见 [Skills 用法](docs/tui.md#skills) 与 [沙箱工具链](docs/sandbox.md#playwright-与有头-x11)。
225
+
226
+ </details>
227
+
228
+ <details>
229
+ <summary>从源码开发</summary>
230
+
231
+ ```bash
232
+ git clone https://github.com/ADaozz/deep_agent_cli.git
233
+ cd deep_agent_cli
234
+ python3.12 -m venv .venv
235
+ source .venv/bin/activate
236
+ pip install -e ".[dev]"
237
+ pytest -q
238
+ ```
239
+
240
+ 自动化测试不调用真实模型;CI 覆盖 Python 3.12 和 3.13。更多说明见 [开发指南](docs/development.md)。
241
+
242
+ </details>
243
+
244
+ [MIT License](LICENSE)
@@ -0,0 +1,213 @@
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
+ 在项目目录运行 `deep-agent` 进入交互式终端,用 `deep-agent resume` 恢复已有会话。要在其他 Python 程序里复用同一套运行核心,使用 [Python API](docs/library.md)。
21
+
22
+ > 当前版本 **0.1.9**,处于早期开发阶段。稳定版前,配置、会话存储格式和 Python API 可能出现不兼容变更。
23
+
24
+ ## 能做什么
25
+
26
+ - **查代码、改文件** — 浏览、读取、正则搜索、编辑和删除;`Ctrl+R` 审阅完整改动,`F2` 处理审批。
27
+ - **运行项目命令** — 实时查看输出,会话内复用持久沙箱;默认审批、隔离直接 IP 网络。
28
+ - **随时介入任务** — 追加指令、排队后续任务、暂停、取消,以及结构化人工输入。
29
+ - **保留工作上下文** — SQLite 会话恢复、模型与推理强度切换、上下文压缩;支持图片输入的模型可接收附件。
30
+
31
+ 支持通过 Skills 和 `AGENTS.md` 扩展项目指令。
32
+
33
+ ## 快速开始
34
+
35
+ 需要 **Linux / WSL2、Python 3.12+、Bubblewrap**,以及支持 Chat Completions 或 Responses 的模型端点。CLI 需要交互式终端;原生 Windows、macOS 和 WSL1 不支持这套沙箱。Ubuntu / WSL2 的 user namespace 限制见 [沙箱排查](docs/sandbox.md#排查ubuntu--wsl2)。
36
+
37
+ 使用 Node 编写的 stdio MCP 服务或通过 `execute` 运行 Node 工具时,推荐 **Node.js 24(使用最新的 24.x 补丁版本)**;具体 MCP 服务仍以其自身的版本要求为准。
38
+
39
+ ### 1. 安装
40
+
41
+ Debian / Ubuntu:
42
+
43
+ ```bash
44
+ sudo apt install pipx bubblewrap
45
+ pipx ensurepath
46
+ # 重新打开终端后安装
47
+ pipx install deep-agent-cli
48
+ deep-agent --version
49
+ ```
50
+
51
+ 系统默认 Python 低于 3.12 时,使用 `pipx install --python /path/to/python3.12 deep-agent-cli` 指定已安装的解释器。ripgrep 随 Python 依赖安装,无需另行安装。
52
+
53
+ ### 2. 初始化与配置
54
+
55
+ 从项目目录启动,首次运行会创建 `~/.deep-agent/config.yaml` 和 Skills 目录,然后退出。已有配置不会被覆盖;设置了 `DEEP_AGENT_CONFIG` 时使用指定配置。
56
+
57
+ ```bash
58
+ cd ~/projects/my-app # 替换为你的项目目录
59
+ deep-agent
60
+ ```
61
+
62
+ 配置、Skills 和按键配置目录必须位于工作区之外,**不要将家目录或其上层目录作为工作区**。
63
+
64
+ 默认模板提供可选的 Node、Cargo / Rustup、Chrome、X11 和浏览器缓存挂载。NVM 挂载整个版本目录,使用哪个版本由用户在沙箱 `PATH` 中指定;程序不自动发现工具安装位置或选择版本。已有配置需手动对照 [默认挂载说明](docs/configuration.md#默认工具挂载) 合并,升级不会覆盖用户配置。
65
+
66
+ 默认模板使用 `token-plan/qwen3.8-flash`。在启动 Agent 的同一个 Bash 终端中输入对应密钥:
67
+
68
+ ```bash
69
+ read -rsp 'Token Plan API key: ' TOKEN_PLAN_API_KEY
70
+ export TOKEN_PLAN_API_KEY
71
+ printf '\n'
72
+ ```
73
+
74
+ 使用其他模型服务时,编辑 `~/.deep-agent/config.yaml`,调整端点、密钥、模型 ID 及能力配置。`api` 必须与端点匹配;省略时默认为 `responses`,不会自动判断。
75
+
76
+ <details>
77
+ <summary>查看模型配置示例</summary>
78
+
79
+ 以下与默认模板一致;`llm.default` 使用“来源/模型”标识,模型项继承来源级字段,并可单独覆盖。
80
+
81
+ ```yaml
82
+ llm:
83
+ default: token-plan/qwen3.8-flash
84
+ models:
85
+ token-plan:
86
+ base_url: https://token-plan.cn-beijing.maas.aliyuncs.com/compatible-mode/v1
87
+ api_key: ${TOKEN_PLAN_API_KEY}
88
+ api: chat_completions
89
+ reasoning_efforts: [none, low, medium, xhigh]
90
+ models:
91
+ qwen3.8-flash:
92
+ input: [text, image]
93
+ context_window: 1m
94
+ ```
95
+
96
+ 端点、上下文窗口、输入模态和推理强度取决于所选服务,完整说明见 [配置参考](docs/configuration.md)。
97
+
98
+ </details>
99
+
100
+ ### 3. 开始第一个任务
101
+
102
+ 在项目目录再次运行 `deep-agent`,输入:
103
+
104
+ ```text
105
+ 阅读当前项目,列出程序入口、关键模块和测试命令,并注明对应文件。
106
+ 暂不修改文件或执行命令。
107
+ ```
108
+
109
+ 获得项目概览后,可以继续要求一次小范围修改。默认 `ask` 下,文件变更会等待审批:`Ctrl+R` 查看改动,`F2` 打开审批面板。启动检查失败时默认拒绝进入宿主执行,见 [沙箱与权限](docs/sandbox.md)。
110
+
111
+ <details>
112
+ <summary>恢复会话、升级与虚拟环境安装</summary>
113
+
114
+ ```bash
115
+ deep-agent resume # 选择已保存的会话
116
+ deep-agent resume 01a08aae # 换成已有会话的 ID 或前缀
117
+ pipx upgrade deep-agent-cli
118
+ ```
119
+
120
+ 恢复只加载状态,不自动继续未完成任务;旧数据库格式不自动迁移。取消不回滚已发生的文件修改或外部副作用。
121
+
122
+ 不使用 pipx 时,也可安装到虚拟环境:
123
+
124
+ ```bash
125
+ python3.12 -m venv ~/.venvs/deep-agent
126
+ ~/.venvs/deep-agent/bin/pip install deep-agent-cli
127
+ ~/.venvs/deep-agent/bin/deep-agent --version
128
+ ```
129
+
130
+ </details>
131
+
132
+ ## 常用操作
133
+
134
+ | 操作 | 用途 |
135
+ |---|---|
136
+ | `/model` | 切换模型与推理强度 |
137
+ | `Ctrl+R` / `F2` | 审阅文件改动 / 处理审批与提问 |
138
+ | `Enter` / `Alt+Enter` | 提交或运行中追加指令 / 排队后续任务 |
139
+ | `Esc` | 请求取消当前任务 |
140
+ | `Ctrl+O` / `Ctrl+T` | 展开工具输出 / 思考内容 |
141
+ | `/resume` / `/new` | 恢复或新建会话 |
142
+ | `/mcp` | 查看、开关和配置宿主 MCP 服务 |
143
+ | `/help` / `/status` | 查看完整操作与当前状态 |
144
+
145
+ 更多按键、图片附件、队列、Skills 和显示设置见 [终端界面](docs/tui.md)。
146
+
147
+ ## 架构与安全
148
+
149
+ **审批决定是否执行,隔离决定命令能访问哪些资源。** 文件工具和命令走不同通路:
150
+
151
+ - **文件工具 → 宿主进程**:Backend 使用工作区的真实绝对路径(如 `/mnt/d/test`),`/skills` 可写。`restricted` 下,启动时声明的额外挂载按同样的只读或读写属性授权;未声明路径拒绝访问。
152
+ - **命令 → Bubblewrap**:`execute` 经沙箱池运行,会话内按需复用有网、无网 Worker。模型与 Tavily 请求从宿主发送,不受命令网络策略约束。
153
+
154
+ <details>
155
+ <summary>展开运行架构图</summary>
156
+
157
+ ![TUI 进入共享的 AgentRunner 和 Deep Agents / LangGraph;普通文件工具在宿主进程访问授权路径,execute 经 SandboxPool 进入 Bubblewrap Worker。](assets/readme/runtime-map.svg)
158
+
159
+ SQLite 保存会话状态。模型工具表不包含 `grep` 和 `glob`。代码搜索和文件发现通过 `execute` 运行宿主提供、只读挂载进沙箱的 `rg`;搜索的审批与网络和其他命令相同。完整分层与生命周期见 [架构文档](docs/architecture.md)。
160
+
161
+ </details>
162
+
163
+ | 模式 | 审批 | 命令网络 |
164
+ |---|---|---|
165
+ | **沙箱 + `ask`**(默认) | 文件变更、命令、网页搜索、MCP 调用及增删服务需批准 | 默认隔离直接 IP 网络;`network=true` 获批后共享宿主网络 |
166
+ | 沙箱 + `allow` | 所有工具免审批,包括 MCP 工具、`mcp_add`、`mcp_remove` | 所有 execute 共享宿主网络 |
167
+
168
+ 只读文件工具免审批;`/permission` 统一控制原生与 MCP 工具审批,`allow` 仅限沙箱模式。MCP 在宿主进程中运行,不经过 Bubblewrap,也不受沙箱网络策略限制。配置在 `~/.deep-agent/mcp.json`,根级 `enabled` 是全局开关(默认开启);用 `/mcp`、`/mcp enable`、`/mcp disable` 或 `mcp_add` / `mcp_remove` 管理。全局关闭时不连接、不启动 stdio、不打开 OAuth,也不把 MCP 工具交给模型;配置和令牌缓存仍保留。**工作区内的 `.env`、`.git` 同样可访问,取消不回滚已发生的副作用。**
169
+
170
+ 全局开关打开时,启动会自动连接各服务里 `enabled: true` 的项。OAuth 优先使用加密缓存并刷新令牌,无法刷新时打开浏览器授权;无需鉴权的服务直接连接。`/mcp` 先显示 `MCP: Enabled` 或 `MCP: Disabled`,开启时再列出 `服务名 状态 N tools`;`connected` 为绿色,其余状态为红色。连接恢复、附件处理和后台日志见 [MCP 配置](docs/configuration.md#mcpmcpjson),命令和状态说明见 [TUI 文档](docs/tui.md#mcp-服务)。
171
+
172
+ <details>
173
+ <summary>更多边界与当前限制</summary>
174
+
175
+ - **网络与进程**:无网命名空间不阻断通过共享 Unix socket、FIFO 或文件实现的间接通信。有网实例可访问互联网、localhost 和局域网;切回 `ask` 不停止此前的后台进程。会话切换及关闭时清理沙箱。
176
+ - **挂载与资源**:用户可通过现有挂载列表扩大或缩小文件系统可见范围,审批逻辑保持独立。只读挂载仍允许读取其中的敏感文件。没有 CPU、内存、磁盘或进程数硬配额。Skills、`AGENTS.md` 和提示词不是操作系统安全边界。
177
+ - **本地状态**:同一会话只允许一个进程持有;工作区可能产生 `.deep-agent/` 命令日志和 `.deepagents/` 压缩历史,程序不修改 `.gitignore`。
178
+ - **客户端**:模型、MCP、Tavily 和子进程统一使用全局 [`trust_env`](docs/configuration.md#全局网络环境trust_env) 配置,默认忽略代理与 CA 环境变量;剪贴板图片仅支持 WSL,其他环境通过文件添加。MCP 支持 Streamable HTTP 和 stdio 工具调用及工具返回的内嵌资源;不提供独立 Resources / Prompts 接口、Sampling 回调、旧式服务端 Elicitation、MCP Apps UI 或子 Agent。
179
+
180
+ 完整隔离范围与环境变量见 [沙箱与权限](docs/sandbox.md)。
181
+
182
+ </details>
183
+
184
+ ## 文档
185
+
186
+ - **使用**:[配置参考](docs/configuration.md) · [终端界面](docs/tui.md) · [正则搜索](docs/search.md)
187
+ - **机制**:[沙箱与权限](docs/sandbox.md) · [架构设计](docs/architecture.md)
188
+ - **集成**:[Python API](docs/library.md) · [开发指南](docs/development.md)
189
+
190
+ <details>
191
+ <summary>扩展 Skills 与网页搜索</summary>
192
+
193
+ Skills 位于 `~/.deep-agent/skills/<技能目录>/SKILL.md`,使用 `/skill` 选择;配置 Tavily key 后启用 `web_search`。外部工具与浏览器需预先安装并通过沙箱挂载,见 [Skills 用法](docs/tui.md#skills) 与 [沙箱工具链](docs/sandbox.md#playwright-与有头-x11)。
194
+
195
+ </details>
196
+
197
+ <details>
198
+ <summary>从源码开发</summary>
199
+
200
+ ```bash
201
+ git clone https://github.com/ADaozz/deep_agent_cli.git
202
+ cd deep_agent_cli
203
+ python3.12 -m venv .venv
204
+ source .venv/bin/activate
205
+ pip install -e ".[dev]"
206
+ pytest -q
207
+ ```
208
+
209
+ 自动化测试不调用真实模型;CI 覆盖 Python 3.12 和 3.13。更多说明见 [开发指南](docs/development.md)。
210
+
211
+ </details>
212
+
213
+ [MIT License](LICENSE)