deep-agent-cli 0.1.0__tar.gz → 0.1.1__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 (55) hide show
  1. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/PKG-INFO +132 -21
  2. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/README.md +130 -20
  3. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/cli/app.py +501 -81
  4. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/cli/commands.py +2 -1
  5. deep_agent_cli-0.1.1/agent/cli/gitinfo.py +106 -0
  6. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/cli/interactions.py +70 -18
  7. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/cli/main.py +29 -8
  8. deep_agent_cli-0.1.1/agent/cli/pasted_content.py +52 -0
  9. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/cli/rendering.py +10 -2
  10. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/cli/session_controller.py +5 -0
  11. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/cli/state.py +1 -1
  12. deep_agent_cli-0.1.1/agent/config.example.yaml +129 -0
  13. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/config.py +17 -1
  14. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/control.py +10 -0
  15. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/factory.py +2 -0
  16. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/llm.py +57 -5
  17. deep_agent_cli-0.1.1/agent/middleware/runtime_config.py +17 -0
  18. deep_agent_cli-0.1.1/agent/middleware/steering.py +60 -0
  19. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/runner.py +247 -63
  20. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/sandbox.py +36 -7
  21. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/session.py +72 -39
  22. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/session_runtime.py +55 -3
  23. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/tools/human_input.py +1 -0
  24. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/tools/human_interaction.py +21 -3
  25. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/pyproject.toml +2 -1
  26. deep_agent_cli-0.1.0/agent/cli/gitinfo.py +0 -84
  27. deep_agent_cli-0.1.0/agent/config.example.yaml +0 -76
  28. deep_agent_cli-0.1.0/agent/middleware/steering.py +0 -35
  29. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/.gitignore +0 -0
  30. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/LICENSE +0 -0
  31. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/__init__.py +0 -0
  32. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/attachments.py +0 -0
  33. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/bootstrap.py +0 -0
  34. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/cancel.py +0 -0
  35. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/cli/__init__.py +0 -0
  36. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/cli/clipboard.py +0 -0
  37. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/cli/input.py +0 -0
  38. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/cli/previews.py +0 -0
  39. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/file_mutation.py +0 -0
  40. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/middleware/__init__.py +0 -0
  41. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/middleware/attachments.py +0 -0
  42. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/middleware/cancel_tools.py +0 -0
  43. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/middleware/pause.py +0 -0
  44. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/middleware/recovery.py +0 -0
  45. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/middleware/tool_arg_hints.py +0 -0
  46. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/middleware/workspace_filesystem.py +0 -0
  47. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/middleware/write_operation.py +0 -0
  48. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/network.py +0 -0
  49. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/permission.py +0 -0
  50. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/session_lock.py +0 -0
  51. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/stream.py +0 -0
  52. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/tools/__init__.py +0 -0
  53. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/tools/examples.py +0 -0
  54. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/tools/execute.py +0 -0
  55. {deep_agent_cli-0.1.0 → deep_agent_cli-0.1.1}/agent/tools/web_search.py +0 -0
@@ -1,12 +1,13 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: deep-agent-cli
3
- Version: 0.1.0
3
+ Version: 0.1.1
4
4
  Summary: A sandboxed coding agent CLI for Linux and WSL2
5
5
  License-Expression: MIT
6
6
  License-File: LICENSE
7
7
  Classifier: Environment :: Console
8
8
  Classifier: Operating System :: POSIX :: Linux
9
9
  Classifier: Programming Language :: Python :: 3.12
10
+ Classifier: Programming Language :: Python :: 3.13
10
11
  Classifier: Topic :: Software Development
11
12
  Requires-Python: >=3.12
12
13
  Requires-Dist: deepagents<0.8.0,>=0.7.17
@@ -63,12 +64,12 @@ Description-Content-Type: text/markdown
63
64
  - **公开 Web 搜索** — 配置 Tavily 密钥后提供 `web_search`;只返回带 URL 的相关摘要,不授予沙箱命令联网权限
64
65
  - **沙箱执行** — 默认隔离网络;`execute(network=true)` 使用宿主网络,可访问互联网、localhost 和局域网;allow 模式下所有 `execute` 默认使用宿主网络
65
66
  - **权限模式** — `ask` 审批 `execute` 和内置文件写入、删除工具;`allow` 仅 SANDBOXED 可启用(需输入 `ALLOW`),开启后 `execute` 默认开放宿主网络
66
- - **持久会话** — 每个工作区一份 SQLite,`/resume` 恢复最近线程,checkpoint 是恢复依据
67
+ - **持久会话** — 每个工作区一份 SQLite;首次发送消息才保存新会话,`/resume` 选择恢复已有会话
67
68
  - **流式输出** — 思考和回答按增量刷新;`execute` 的 stdout/stderr 原地更新同一个 Tool 块
68
69
  - **转录区跟随** — 停留在底部时持续显示新输出;上滚后保留阅读位置,并提供可点击的回到底部提示
69
70
  - **运行中转向** — `Enter` 注入下一条指令,`Esc` 取消并把未发送的内容还原到输入框
70
71
  - **后续任务** — `Alt+Enter` 排入 Runtime 队列,当前任务完成后由 `AgentRunner` 接续执行
71
- - **多模型** — YAML 按来源分组;`/model` 先选来源再选模型,`Ctrl+P` 循环切换。切换会重建 graph,会话保留
72
+ - **多模型** — YAML 按来源分组;`/model` 依次选择来源、模型、思考强度,`Ctrl+P` 循环切换。空闲时立即生效,有任务或中断时在安全边界生效,会话保留
72
73
  - **图片附件** — Ctrl+V / 路径 / `/image`;checkpoint 只存引用,请求模型时才编码
73
74
  - **自动上下文压缩** — `create_deep_agent()` 默认带 `SummarizationMiddleware`,上下文接近上限时自动摘要;被挤掉的历史落到工作区,需要时还能再读
74
75
  - **人工交互** — Agent 缺判断时弹出单选、多选、布尔、单行、多行,不绑特定 UI
@@ -88,16 +89,32 @@ Description-Content-Type: text/markdown
88
89
 
89
90
  ### Install
90
91
 
91
- 推荐使用独立环境安装:
92
+ Ubuntu 24.04 / WSL2 Ubuntu 24.04 可使用系统 Python 3.12。先安装 pipx、venv 和 Bubblewrap,并检查解释器版本:
92
93
 
93
94
  ```bash
94
- pipx install deep-agent-cli
95
+ sudo apt update
96
+ sudo apt install python3 python3-venv pipx bubblewrap
97
+ python3 -c 'import sys; assert sys.version_info >= (3, 12), "需要 Python 3.12+"; print(sys.version)'
98
+ pipx ensurepath
99
+ # 重新打开终端,让 ~/.local/bin 进入 PATH。
100
+ pipx install --python python3 deep-agent-cli
101
+ deep-agent --version
95
102
  ```
96
103
 
97
- 也可以:
104
+ 旧版 Ubuntu 的系统 Python 可能低于 3.12。可升级到 Ubuntu 24.04,或按 [Python 官方安装说明](https://docs.python.org/3/using/unix.html) 安装 3.12/3.13 到独立目录,再指定解释器:
98
105
 
99
106
  ```bash
100
- pip install deep-agent-cli
107
+ pipx install --python /absolute/path/to/python3.13 deep-agent-cli
108
+ ```
109
+
110
+ 不要覆盖发行版依赖的 `/usr/bin/python3`。pipx 安装说明见 [pipx 官方文档](https://pipx.pypa.io/latest/how-to/install-pipx.html)。
111
+
112
+ 也可使用虚拟环境:
113
+
114
+ ```bash
115
+ python3 -m venv ~/.venvs/deep-agent
116
+ ~/.venvs/deep-agent/bin/python -m pip install deep-agent-cli
117
+ ~/.venvs/deep-agent/bin/deep-agent --help
101
118
  ```
102
119
 
103
120
  ### Start
@@ -107,7 +124,41 @@ cd ~/projects/my-app
107
124
  deep-agent
108
125
  ```
109
126
 
110
- 首次运行会生成配置模板并退出。编辑 `~/.deep-agent/config.yaml` 的模型端点和 API key 后,再运行 `deep-agent`。当前不支持原生 Windows 或 macOS 沙箱。
127
+ 首次运行会生成配置模板并退出,即使输入来自管道也可初始化。有配置后,TUI 要求 stdin 和 stdout 都是交互终端;`echo hi | deep-agent` 会明确报错并以退出码 2 退出,不创建运行会话。`--help`、`resume --help` 和 `--version` 不读取配置、不启动沙箱或模型。编辑 `~/.deep-agent/config.yaml` 的模型端点和 API key 后,再运行 `deep-agent`。当前不支持原生 Windows 或 macOS 沙箱。
128
+
129
+ 进入 TUI 后,新会话先保留在内存中,首次发送消息时才保存。只启动、切换模型或退出,不会新增空会话记录或会话锁文件;已有工作区的 SQLite 文件仍可被打开。
130
+
131
+ ### Ubuntu / WSL2 troubleshooting
132
+
133
+ 先在不改系统策略的情况下运行:
134
+
135
+ ```bash
136
+ command -v bwrap
137
+ python3 examples/sandbox_probe.py --require-sandbox # 在已安装依赖的源码检出中运行
138
+ sysctl kernel.unprivileged_userns_clone kernel.apparmor_restrict_unprivileged_userns user.max_user_namespaces
139
+ sudo aa-status
140
+ sudo journalctl -k -g 'apparmor|DENIED|userns'
141
+ ```
142
+
143
+ 未安装 bwrap 时安装 `bubblewrap`;已安装却出现 `Operation not permitted` / namespace 权限错误时,应检查 AppArmor、userns 和容器 seccomp 策略。普通预检失败应检查挂载路径、权限、`/bin/sh` 及超时。WSL1、原生 Windows/macOS 和禁止 namespace 的容器不能提供本项目要求的沙箱;WSL 用户在 Windows 中运行 `wsl -l -v` 确认版本为 2,必要时用 `wsl --set-version <发行版名称> 2` 转换。
144
+
145
+ Ubuntu 24.04 开始限制无特定授权的 user namespace,详见 [Ubuntu 官方发行说明](https://documentation.ubuntu.com/release-notes/24.04/#unprivileged-user-namespace-restrictions)。优先检查发行版已有的 bwrap profile;若缺少授权,由管理员给**实际 bwrap 可执行文件**配置专属 profile。例如路径为 `/usr/bin/bwrap` 且没有现有 profile 与之匹配时,创建 `/etc/apparmor.d/deep-agent-bwrap`:
146
+
147
+ ```text
148
+ abi <abi/4.0>,
149
+ include <tunables/global>
150
+ profile deep-agent-bwrap /usr/bin/bwrap flags=(unconfined) {
151
+ userns,
152
+ }
153
+ ```
154
+
155
+ ```bash
156
+ sudo apparmor_parser -r /etc/apparmor.d/deep-agent-bwrap
157
+ ```
158
+
159
+ 这是针对该可执行文件的 userns 例外,会影响通过该文件启动的所有 bwrap 调用;它不是额外的文件访问隔离策略,工作区隔离仍由 Bubblewrap 完成。已有发行版 profile 时,应调整其本地 override,避免添加相同路径的冲突 profile;也可使用管理员拥有的独立 bwrap 副本并只给该路径授权。不要给 Python 或整个用户目录通配授权,也不默认关闭全局 AppArmor/userns 保护。删除自定义 profile 时先运行 `sudo apparmor_parser -R /etc/apparmor.d/deep-agent-bwrap`,再删除该文件。
160
+
161
+ 若日志没有 AppArmor 拒绝记录,可能是容器、seccomp 或内核不支持所需 namespace,上述 profile 不会解决这些限制。程序默认拒绝启动隔离失败的沙箱;只有明确配置 `sandbox.allow_unsandboxed: true` 或交互输入 `UNSANDBOXED` 才授权宿主执行。沙箱测试被跳过表示当前环境未验证隔离能力,不代表兼容。
111
162
 
112
163
  ### Configure
113
164
 
@@ -153,16 +204,42 @@ llm:
153
204
  provider: openai-compatible
154
205
  stream_usage: true
155
206
  context_window: 1m
207
+ reasoning_efforts: [none, low, medium, xhigh] # Qwen3.8 的档位
156
208
  models:
157
209
  auto: # 由 Token Plan 侧自动路由
158
210
  input: [text]
211
+ reasoning_efforts: [] # 未确认 auto 的枚举,清除来源配置,只提供 default
159
212
  qwen3.8-max:
160
213
  input: [text, image]
214
+ # 省略 reasoning_efforts,继承来源的枚举。
215
+ glm-5.3:
216
+ input: [text]
217
+ reasoning_efforts: [low, high, max] # 完整覆盖来源枚举,不支持关闭思考
161
218
  ```
162
219
 
163
220
  `llm.default` 必须明确指定已配置的 `来源/模型`,例如 `token-plan/auto`。`local`、`token-plan` 和模型键都是自定义名称;模型键默认也是发给 API 的模型名,需要别名时在模型项内写 `model:`。配置只接受 `llm.models.<来源>.models.<模型>` 结构;旧版 `llm.model`、扁平 `llm.models.<模型>` 以及放在 `llm` 顶层的端点或密钥字段都会报错。缺少默认模型、字段无效或 YAML 语法错误时,启动会指出配置文件及错误位置,不会默默切换模型。
164
221
 
165
- `/model` 先选来源,再选来源下的模型;在模型列表按 `Esc` 返回来源列表。`/model token-plan` 可直接打开该来源,`/model token-plan/auto` 可直接切换。`context_window` 决定自动压缩阈值和占用百分比分母。区域按自己的开通情况替换 `cn-beijing`。密钥只写在 workspace 外的配置里,不要提交进仓库。
222
+ ### 模型与推理强度
223
+
224
+ `/model` 依次选择来源、具体模型、思考强度;第三段确认后统一提交,`Esc` 逐段返回。模型列表直接显示实际 API 模型名,例如 `qwen3.5-plus`;命令参数仍使用 YAML 中的 `来源/模型键`。`/model token-plan` 直接打开该来源,`/model token-plan/qwen3.8-max` 直接进入强度选择。底栏按 `来源 · 模型 · 强度` 显示,例如 `token-plan · qwen3.8-max · medium`。
225
+
226
+ `reasoning_efforts` 由用户按实际模型、端点和 API 协议配置:
227
+
228
+ - 有非空枚举时,菜单只显示该枚举,不添加 `default`;选择其他模型时默认定位到枚举第一项。
229
+ - 未配置或枚举为空时,菜单只有 `default`,请求不传强度参数。`default` 使用服务端默认行为,不代表关闭思考。
230
+ - 来源级枚举由子模型继承;子模型声明的枚举完整覆盖,显式 `null` 或 `[]` 清除继承。
231
+ - `none` 只有在实际 API 支持时才能加入枚举;它用于关闭思考,`low` 仍然会思考。不要把 `default` 写进枚举。
232
+
233
+ | provider | 强度参数 |
234
+ |---|---|
235
+ | `openai-compatible` | Chat Completions 的 `reasoning_effort` |
236
+ | `qwen-responses` | Responses 的 `reasoning.effort` |
237
+
238
+ 两种协议的可选值可能不同。例如,百炼 DeepSeek V4.1 Flash 的 Chat Completions 文档列出 `low/high/max`,关闭思考使用 `enable_thinking=false`;Responses 则明确支持 `none/low/high/max`。本项目只通过 effort 控制强度,因此当前 Chat Completions 配置不加入未经文档确认的 `none`。详见 [Chat 参数](https://help.aliyun.com/zh/model-studio/qwen-api-via-openai-chat-completions)、[Responses 参数](https://help.aliyun.com/zh/model-studio/qwen-api-via-openai-responses) 和 [GLM 参数](https://help.aliyun.com/zh/model-studio/glm)。其他厂商模板见 [config.example.yaml](agent/config.example.yaml)。
239
+
240
+ 空闲且无中断时,模型切换立即生效,提示为 `Model: 来源 · 模型 · 强度`。任务执行中或有未完成的审批/暂停中断时才排队,提示为 `Model queued: …`;旧调用与工具流程完成后,在下一次模型推理前生效。`/permission` 在同样的安全边界生效。已有 `ask` 审批仍需按 `F2` 批准或拒绝,`/permission allow` 不会自动批准旧调用。
241
+
242
+ 已持久化会话保存当前及待切换配置,恢复该会话时继续使用;尚未发送消息的新会话只在内存中保存选择。`context_window` 决定自动压缩阈值和占用百分比分母。区域按自己的开通情况替换 `cn-beijing`。密钥只写在 workspace 外的配置里,不要提交进仓库。
166
243
 
167
244
  ### Resume
168
245
 
@@ -173,6 +250,8 @@ deep-agent resume 01a08aae-... # 按 id 恢复
173
250
 
174
251
  源码仓库中也可运行 `python -m agent.cli.main`。没有 `bwrap` 时默认拒绝启动;交互式终端只有输入 `UNSANDBOXED` 才会降级到宿主执行。
175
252
 
253
+ 直接运行 `deep-agent` 开始新会话;要继续之前的对话,使用上述 `resume` 命令或 TUI 中的 `/resume`。恢复只加载已有状态,不自动调用模型。`/new` 同样先创建内存中的会话,首次发送消息后才持久化。反复启动、退出或执行 `/new` 不会积累新的空记录;旧版本留下的空记录不会自动清理。
254
+
176
255
  ## Usage
177
256
 
178
257
  进入交互会话后,普通文本就是任务。以 `/` 开头是命令。
@@ -180,13 +259,13 @@ deep-agent resume 01a08aae-... # 按 id 恢复
180
259
  ```text
181
260
  /help 命令与快捷键
182
261
  /status 工作区、沙箱、权限、session
183
- /session 当前线程、创建/更新时间与 SQLite 路径
184
- /new 开一条新线程
262
+ /session 当前线程与 SQLite 路径;已保存会话显示创建/更新时间
263
+ /new 新建会话,首次发送消息后保存
185
264
  /resume 列出有内容的会话并选择恢复
186
265
  /resume a1b2 按 id 前缀切换 session
187
- /model 先选来源,再选模型
266
+ /model 依次选择来源、模型、思考强度
188
267
  /model token-plan 打开 Token Plan 模型列表
189
- /model token-plan/auto 直接切换模型
268
+ /model token-plan/auto 选择思考强度,确认后提交切换
190
269
  /compact 达到手动压缩门槛后摘要旧对话;未达到时显示当前占用百分比
191
270
  /permission ask|allow # allow 仅 SANDBOXED 且开放沙箱网络;UNSANDBOXED / CUSTOM 只有 ask
192
271
  /image clipboard | <path> | clear
@@ -199,7 +278,8 @@ deep-agent resume 01a08aae-... # 按 id 恢复
199
278
  | 操作 | 按键 |
200
279
  |------|------|
201
280
  | 提交;运行中注入 steering | `Enter` |
202
- | 命令候选 | 输入 `/` 后用方向键选择,`Tab` / `Enter` 填入,再按 `Enter` 执行 |
281
+ | 拖选并复制转录内容 | 鼠标左键拖动,松开后自动复制,可用 `Ctrl+V` 粘贴 |
282
+ | 命令候选 | 输入 `/` 后用方向键选择,`Tab` / `Enter` 填入,再按 `Enter` 执行;`/model ` 和 `/permission ` 也会补全参数 |
203
283
  | 换行 | `Ctrl+J` |
204
284
  | 排到本轮结束后再问 | `Alt+Enter` |
205
285
  | 上滚时回到底部;再次按下执行当前界面的取消操作 | `Esc`;也可点击 `↓ Back to bottom · esc` |
@@ -212,10 +292,18 @@ deep-agent resume 01a08aae-... # 按 id 恢复
212
292
  | 取回未应用的 steering | `Alt+Up` |
213
293
  | 回看历史输出 | 滚轮 / `PgUp` / `PgDn`,`Ctrl+Home` 到顶,`Ctrl+End` 回到底部跟随 |
214
294
 
215
- 输入 `/` 时显示命令候选,按 `Esc` 可直接清空尚未执行的命令。执行 `/model` 等交互式命令时,蓝色分隔线将选择界面与对话区隔开;如果对话已上滚,居中的 `↓ Back to bottom · esc` 提示显示在分隔线正上方。转录区隐藏右侧滚动条,可用滚轮、翻页键或 `Ctrl+Home` / `Ctrl+End` 滚动。
295
+ 输入 `/` 时显示命令候选;输入 `/model ` 时补全已配置的来源与模型 ID,输入 `/permission ` 时补全当前环境可用的 `ask`、`allow`。按 `Esc` 可直接清空尚未执行的命令。执行 `/model` 等交互式命令时,蓝色分隔线将选择界面与对话区隔开;如果对话已上滚,居中的 `↓ Back to bottom · esc` 提示显示在分隔线正上方。转录区隐藏右侧滚动条,可用滚轮、翻页键或 `Ctrl+Home` / `Ctrl+End` 滚动。
296
+
297
+ 转录区可直接按住鼠标左键拖选,松开后自动复制选中文本到系统剪贴板;拖到转录区顶部或底部会持续滚动,以便选中屏幕外的历史内容。无需按 `Ctrl+Shift`。
298
+
299
+ 粘贴 500 字符及以上的文本时,输入框用 `[Pasted Content XXXX chars]` 块代替长正文,周围仍可继续编辑文字;提交时会把块还原成完整粘贴内容发送给 Agent。短文本保持原样。
300
+
301
+ 运行中按 `Enter` 提交的 steering 会在下一次工具调用开始前交给 Agent:如果模型返回时已有新输入排队,先取消这批尚未进入审批或执行的调用,再带着新输入重新推理。已经进入审批的调用仍需按原权限处理;已经开始的工具会先完成。`Alt+Enter` 提交的 follow-up 则在当前任务结束后开始新一轮。
216
302
 
217
303
  探索类工具调用合并显示为 `Explored N items`,只预览最后五项;省略项数量显示在预览上方,底部灰色的 `Ctrl+O to expand` 提示可展开完整工具详情。再次按 `Ctrl+O` 可收起。
218
304
 
305
+ 底栏的 Git 状态在后台刷新,首次探测期间显示 `⎇ checking git`。Git 未安装、探测报错或超时分别显示 `git unavailable`、`git error`、`git timeout`;只有确认当前目录不属于仓库时才显示 `⎇ no git`。探测允许最长 10 秒,适用于 Git 状态扫描较慢的工作区;超时后保留已识别的分支名。
306
+
219
307
  `web_search` 单独显示查询和结果数,按 `Ctrl+O` 展开结果摘要。`write_file` 根据执行前的文件状态显示 `Create /path` 或 `Wrote /path`;连续创建多个文件合并为 `Create N files`,按 `Ctrl+O` 展开完整文件列表。覆盖写入预览显示写入行数和前六行内容,省略的行数在下方提示;按 `Ctrl+R` 查看完整内容,不在写入预览或审阅中显示 `/dev/null`、`+++`、`@@` 等 diff 头。恢复已中断会话时,没有保存工具结果的历史调用显示灰色 `interrupted (completion unconfirmed)`,不会继续转圈;仍待审批的调用显示等待状态。
220
308
 
221
309
  工具失败时显示灰色圆点、`Failed (exit N)`、具体命令或工具目标,以及简短错误;`Ctrl+O` 展开完整输出。探索组在标题中统计失败数,并额外列出最近的失败项。`execute` 显示命令的真实退出码;没有进程退出码的工具错误以约定的 `exit 1` 显示。搜索超时但返回部分结果时只提示结果不完整,不计为失败。
@@ -238,7 +326,7 @@ result = runner.invoke("列出 /workspace 下的文件")
238
326
  `execute` 的 `tool_completed` 事件在 `result` 中携带 `exit_code`、`truncated`、`host_log_path`、`agent_log_path` 和 `termination_reason`;`content` 仍是发给模型的可读结果。
239
327
 
240
328
  默认工具包括文件、沙箱命令、人工输入和 `write_todos`;配置 Tavily 密钥后另行注册 `web_search`。`agent.tools.examples` 中的文档查询示例需要作为 `extra_tools` 显式加入;自定义副作用工具需要通过 `interrupt_on` 显式追加审批规则,内置审批规则不能被覆盖。工具异常不会自动重试,以免超时后重复执行副作用;模型传输错误由 OpenAI SDK 最多重试两次。
241
- 人工输入只使用 `request_human_input`:可传 `fields` 描述文本、布尔或选择题;恢复时用 `runner.submit_human_input({"text": "..."})`。审批用 `approve_tool` / `reject_tool`,暂停用 `continue_run`。旧工具 `handoff_to_human` 已移除,停在该工具调用上的旧会话恢复时会给出迁移错误。
329
+ 人工输入只使用 `request_human_input`:可传 `fields` 描述文本、布尔或选择题;每道选择题自动提供 `Other:` 自定义输入,单选回传自定义文本,多选将其加入结果列表;恢复时用 `runner.submit_human_input({"text": "..."})`。审批用 `approve_tool` / `reject_tool`,暂停用 `continue_run`。旧工具 `handoff_to_human` 已移除,停在该工具调用上的旧会话恢复时会给出迁移错误。
242
330
 
243
331
  传入 `create_deep_agent()` 的 `middleware=[...]` 是附加到默认栈,不会整表替换。Deep Agents 0.7.17 会自动加入 `create_summarization_middleware(model, backend)`。本项目只禁用了默认 general-purpose subagent,没有 `excluded_middleware`,因此自动压缩是开着的。
244
332
 
@@ -320,6 +408,7 @@ CLI 使用 `DEEP_AGENT_CONFIG` 指定的现有配置,否则读取 `~/.deep-age
320
408
  | `llm.models.<source>.api_key` | `sk-local` | 来源共用密钥;模型级可以覆盖 |
321
409
  | `web_search.tavily_api_key` | `null` | 私有配置中的 Tavily 密钥;`TAVILY_API_KEY` 环境变量优先 |
322
410
  | `llm.models.<source>.provider` | `qwen-responses` | 来源共用 `qwen-responses` 或 `openai-compatible`;模型级可以覆盖 |
411
+ | `llm.models.<source>.reasoning_efforts` | `[]` | 推理强度枚举;子模型省略时继承,声明时完整覆盖,`null`/`[]` 清除;非空时 CLI 仅显示枚举,空时仅显示 `default` |
323
412
  | `llm.models.<source>.stream_usage` | `false` | 流式 Chat Completions 请求附带 `stream_options.include_usage`;模型级可以覆盖 |
324
413
  | `llm.models.<source>.base_url` | `http://localhost:8000/v1` | 来源共用推理端点;模型级可以覆盖 |
325
414
  | `llm.models.<source>.models.<name>.input` | `[text]` | 图片模型写成 `[text, image]` |
@@ -347,11 +436,11 @@ web_search:
347
436
  `execute` 输出超限时,完整日志保存到当前工作区的 `.deep-agent/logs/exec/`。最终工具结果同时给出宿主机真实路径和 Agent 可用文件工具读取的 `/workspace/.deep-agent/logs/exec/...` 路径。建议在自己的项目 `.gitignore` 中加入 `.deep-agent/`;程序不会修改项目的忽略规则。
348
437
  父 shell 退出后,如果后台进程仍占有输出管道,`execute` 会继续收集数据,直到管道关闭或连续 100 毫秒没有新输出;后台进程在此后写出的内容不会进入本次工具结果。
349
438
 
350
- `qwen-responses` 使用 `QwenChatOpenAI` 和 Responses API;`openai-compatible` 使用普通 `ChatOpenAI`,固定走 Chat Completions,百炼 Token Plan 的 compatible-mode 端点走这一条。两者都可通过 `AttachmentStore` 引用发送图片,前提是模型 profile 声明 `input: [text, image]` 且端点支持图片。
439
+ `qwen-responses` 使用 `QwenChatOpenAI` 和 Responses API;`openai-compatible` 固定走 Chat Completions,使用 `ReasoningChatOpenAI` 保留兼容端点流式和非流式响应中的 `reasoning_content`,供思考区展示及会话恢复,并在后续请求中透传已有思考内容。两者都可通过 `AttachmentStore` 引用发送图片,前提是模型 profile 声明 `input: [text, image]` 且端点支持图片。
351
440
 
352
441
  每次构图都会按默认身份、`agent.instructions`、工作区根目录 `AGENTS.md` 的顺序组成 system prompt;`AGENTS.md` 映射到 Agent 内的 `/workspace/AGENTS.md`。切换模型或权限会重新读取它。作为库调用时,`create_agent(instructions="...")` 可覆盖配置中的长期说明。
353
442
 
354
- LangGraph checkpoint 保存消息、中断和图状态;同一 SQLite 的 `session_catalog` 另存 thread 的 model、permission 和上一轮运行原因,展示状态按运行原因计算。旧 catalog 在打开时迁移。旧会话若保存了已不存在的扁平模型 ID,恢复时会提示该模型不可用,并改用 YAML 指定的默认模型;旧 ID 不会被当作新模型别名。模型的 `finish_reason` 保留在 checkpoint 消息中。`/resume` 只恢复状态,不调用模型。若上一轮是 `pending` 且已有 checkpoint,或上一轮是 `aborted`、`error`,下一次用户输入保持原文写入 checkpoint,恢复说明仅临时加入首次模型请求。空白新 thread 的 `pending` 不触发恢复说明。明确的审批或暂停中断仍按 checkpoint 恢复,不自动重跑工具。切换或新建会话时,TUI 会把未执行的 steering / follow-up 退回输入框;库调用者需先取回队列,才能切换会话。
443
+ CLI 启动及 `/new` 创建的新会话先保留在内存中,首次提交消息后才写入会话目录并取得持久化锁;未发送消息就退出或恢复其他会话,不留下空会话记录。历史空记录不会自动删除。LangGraph checkpoint 保存消息、中断和图状态;同一 SQLite 的 `session_catalog` 另存 thread 的 model、permission 和上一轮运行原因,展示状态按运行原因计算。旧 catalog 在打开时迁移。旧会话若保存了已不存在的扁平模型 ID,恢复时会提示该模型不可用,并改用 YAML 指定的默认模型;旧 ID 不会被当作新模型别名。模型的 `finish_reason` 保留在 checkpoint 消息中。`/resume` 只恢复状态,不调用模型。若上一轮是 `pending` 且已有 checkpoint,或上一轮是 `aborted`、`error`,下一次用户输入保持原文写入 checkpoint,恢复说明仅临时加入首次模型请求。空白新 thread 的 `pending` 不触发恢复说明。明确的审批或暂停中断仍按 checkpoint 恢复,不自动重跑工具。切换或新建会话时,TUI 会把未执行的 steering / follow-up 退回输入框;库调用者需先取回队列,才能切换会话。
355
444
 
356
445
  同一 thread 同时只能被一个进程写入:`SessionStore` 在数据库旁的 `<db>.locks/` 目录用 `flock` 实现 thread 独占,锁文件不删除,进程退出自动释放,Agent 子进程不继承锁描述符。目标会话正被其他窗口持有时,`/resume` 和 `deep-agent resume <id>` 启动恢复都会先释放当前会话并进入等待提示,`Esc` 取消等待回到会话选择器;库调用者同步调用 `switch_session` 则直接抛出 `SessionLockBusyError`。会话切换的提交点在完成全部图与 catalog 读取之后,中途失败会回滚到原会话;`steer` / `follow_up` 在脱离会话或 Runner 关闭后会被拒绝。没有持久化存储的 Runner 只在进程内通过 checkpointer 对象互斥。
357
446
 
@@ -360,7 +449,8 @@ LangGraph checkpoint 保存消息、中断和图状态;同一 SQLite 的 `sess
360
449
  ## Development
361
450
 
362
451
  ```bash
363
- python3.12 -m venv .venv
452
+ python3 -c 'import sys; assert sys.version_info >= (3, 12), "需要 Python 3.12+"'
453
+ python3 -m venv .venv
364
454
  source .venv/bin/activate
365
455
  pip install -e ".[dev]"
366
456
  pytest -q
@@ -371,10 +461,31 @@ python -m build
371
461
 
372
462
  使用 pipx 安装过本项目时,修改源码后在项目根目录运行 `pipx install --force .`,再重启 CLI;已有进程不会自动加载新工具。
373
463
 
374
- 测试不打真模型。对着本地端点做流式冒烟:
464
+ 自动回归不调用真实模型。`python -m pytest` 包含本地模拟 OpenAI Chat Completions HTTP 服务,覆盖流式回答、工具调用、审批、暂停、恢复和 SQLite 重启恢复。可单独运行 `python -m pytest -m integration`;它需要允许监听 `127.0.0.1`。实际隔离能力测试需要可用 bwrap,`REQUIRE_BWRAP_TEST=1 python -m pytest` 将缺失能力视为失败。CI 分别验证 Python 3.12 / 3.13,并保存未放宽 AppArmor 的 Ubuntu 环境诊断报告,不把 skipped 测试当成兼容证明。
465
+
466
+ 真实模型冒烟由用户主动运行,会使用配置中的 API Key 并消耗额度,不进入默认 pytest 或自动 CI:
467
+
468
+ ```bash
469
+ python examples/e2e_live_smoke.py --help
470
+ python examples/e2e_live_smoke.py --model token-plan/qwen3.8-flash
471
+ # 默认创建并清理临时工作区/会话;指定 --workspace 时必须是空目录。
472
+ # 需要外网工具测试时额外传 --network。
473
+ python examples/sandbox_probe.py --require-sandbox
474
+ ```
475
+
476
+ `stream_smoke.py` 是 **Qwen Responses 思考流** 专用验证,不是通用模型连通性测试。配置的活动模型必须使用 `provider: qwen-responses`,端点须支持 Responses,并使用会输出思考内容的 Qwen 模型;脚本的 `--effort` 必须来自 YAML 的有效枚举且不能是 `none`。默认不指定强度时,要求服务端默认开启思考。Chat Completions、关闭思考的模型或只有回答流的模型不满足其验收条件:
375
477
 
376
478
  ```bash
377
- python examples/stream_smoke.py
479
+ python examples/stream_smoke.py --effort low
480
+ ```
481
+
482
+ 库函数 `create_agent()` 不会自动读取 `~/.deep-agent/config.yaml`,未传 `settings` 时使用 `Settings()` 的代码默认值。CLI 则先初始化配置,再通过 `Settings.load()` 读取文件。库调用如需与 CLI 一致,应显式加载:
483
+
484
+ ```python
485
+ from agent import create_agent
486
+ from agent.config import Settings
487
+
488
+ prepared = create_agent(settings=Settings.load())
378
489
  ```
379
490
 
380
491
  ## Roadmap
@@ -36,12 +36,12 @@
36
36
  - **公开 Web 搜索** — 配置 Tavily 密钥后提供 `web_search`;只返回带 URL 的相关摘要,不授予沙箱命令联网权限
37
37
  - **沙箱执行** — 默认隔离网络;`execute(network=true)` 使用宿主网络,可访问互联网、localhost 和局域网;allow 模式下所有 `execute` 默认使用宿主网络
38
38
  - **权限模式** — `ask` 审批 `execute` 和内置文件写入、删除工具;`allow` 仅 SANDBOXED 可启用(需输入 `ALLOW`),开启后 `execute` 默认开放宿主网络
39
- - **持久会话** — 每个工作区一份 SQLite,`/resume` 恢复最近线程,checkpoint 是恢复依据
39
+ - **持久会话** — 每个工作区一份 SQLite;首次发送消息才保存新会话,`/resume` 选择恢复已有会话
40
40
  - **流式输出** — 思考和回答按增量刷新;`execute` 的 stdout/stderr 原地更新同一个 Tool 块
41
41
  - **转录区跟随** — 停留在底部时持续显示新输出;上滚后保留阅读位置,并提供可点击的回到底部提示
42
42
  - **运行中转向** — `Enter` 注入下一条指令,`Esc` 取消并把未发送的内容还原到输入框
43
43
  - **后续任务** — `Alt+Enter` 排入 Runtime 队列,当前任务完成后由 `AgentRunner` 接续执行
44
- - **多模型** — YAML 按来源分组;`/model` 先选来源再选模型,`Ctrl+P` 循环切换。切换会重建 graph,会话保留
44
+ - **多模型** — YAML 按来源分组;`/model` 依次选择来源、模型、思考强度,`Ctrl+P` 循环切换。空闲时立即生效,有任务或中断时在安全边界生效,会话保留
45
45
  - **图片附件** — Ctrl+V / 路径 / `/image`;checkpoint 只存引用,请求模型时才编码
46
46
  - **自动上下文压缩** — `create_deep_agent()` 默认带 `SummarizationMiddleware`,上下文接近上限时自动摘要;被挤掉的历史落到工作区,需要时还能再读
47
47
  - **人工交互** — Agent 缺判断时弹出单选、多选、布尔、单行、多行,不绑特定 UI
@@ -61,16 +61,32 @@
61
61
 
62
62
  ### Install
63
63
 
64
- 推荐使用独立环境安装:
64
+ Ubuntu 24.04 / WSL2 Ubuntu 24.04 可使用系统 Python 3.12。先安装 pipx、venv 和 Bubblewrap,并检查解释器版本:
65
65
 
66
66
  ```bash
67
- pipx install deep-agent-cli
67
+ sudo apt update
68
+ sudo apt install python3 python3-venv pipx bubblewrap
69
+ python3 -c 'import sys; assert sys.version_info >= (3, 12), "需要 Python 3.12+"; print(sys.version)'
70
+ pipx ensurepath
71
+ # 重新打开终端,让 ~/.local/bin 进入 PATH。
72
+ pipx install --python python3 deep-agent-cli
73
+ deep-agent --version
68
74
  ```
69
75
 
70
- 也可以:
76
+ 旧版 Ubuntu 的系统 Python 可能低于 3.12。可升级到 Ubuntu 24.04,或按 [Python 官方安装说明](https://docs.python.org/3/using/unix.html) 安装 3.12/3.13 到独立目录,再指定解释器:
71
77
 
72
78
  ```bash
73
- pip install deep-agent-cli
79
+ pipx install --python /absolute/path/to/python3.13 deep-agent-cli
80
+ ```
81
+
82
+ 不要覆盖发行版依赖的 `/usr/bin/python3`。pipx 安装说明见 [pipx 官方文档](https://pipx.pypa.io/latest/how-to/install-pipx.html)。
83
+
84
+ 也可使用虚拟环境:
85
+
86
+ ```bash
87
+ python3 -m venv ~/.venvs/deep-agent
88
+ ~/.venvs/deep-agent/bin/python -m pip install deep-agent-cli
89
+ ~/.venvs/deep-agent/bin/deep-agent --help
74
90
  ```
75
91
 
76
92
  ### Start
@@ -80,7 +96,41 @@ cd ~/projects/my-app
80
96
  deep-agent
81
97
  ```
82
98
 
83
- 首次运行会生成配置模板并退出。编辑 `~/.deep-agent/config.yaml` 的模型端点和 API key 后,再运行 `deep-agent`。当前不支持原生 Windows 或 macOS 沙箱。
99
+ 首次运行会生成配置模板并退出,即使输入来自管道也可初始化。有配置后,TUI 要求 stdin 和 stdout 都是交互终端;`echo hi | deep-agent` 会明确报错并以退出码 2 退出,不创建运行会话。`--help`、`resume --help` 和 `--version` 不读取配置、不启动沙箱或模型。编辑 `~/.deep-agent/config.yaml` 的模型端点和 API key 后,再运行 `deep-agent`。当前不支持原生 Windows 或 macOS 沙箱。
100
+
101
+ 进入 TUI 后,新会话先保留在内存中,首次发送消息时才保存。只启动、切换模型或退出,不会新增空会话记录或会话锁文件;已有工作区的 SQLite 文件仍可被打开。
102
+
103
+ ### Ubuntu / WSL2 troubleshooting
104
+
105
+ 先在不改系统策略的情况下运行:
106
+
107
+ ```bash
108
+ command -v bwrap
109
+ python3 examples/sandbox_probe.py --require-sandbox # 在已安装依赖的源码检出中运行
110
+ sysctl kernel.unprivileged_userns_clone kernel.apparmor_restrict_unprivileged_userns user.max_user_namespaces
111
+ sudo aa-status
112
+ sudo journalctl -k -g 'apparmor|DENIED|userns'
113
+ ```
114
+
115
+ 未安装 bwrap 时安装 `bubblewrap`;已安装却出现 `Operation not permitted` / namespace 权限错误时,应检查 AppArmor、userns 和容器 seccomp 策略。普通预检失败应检查挂载路径、权限、`/bin/sh` 及超时。WSL1、原生 Windows/macOS 和禁止 namespace 的容器不能提供本项目要求的沙箱;WSL 用户在 Windows 中运行 `wsl -l -v` 确认版本为 2,必要时用 `wsl --set-version <发行版名称> 2` 转换。
116
+
117
+ Ubuntu 24.04 开始限制无特定授权的 user namespace,详见 [Ubuntu 官方发行说明](https://documentation.ubuntu.com/release-notes/24.04/#unprivileged-user-namespace-restrictions)。优先检查发行版已有的 bwrap profile;若缺少授权,由管理员给**实际 bwrap 可执行文件**配置专属 profile。例如路径为 `/usr/bin/bwrap` 且没有现有 profile 与之匹配时,创建 `/etc/apparmor.d/deep-agent-bwrap`:
118
+
119
+ ```text
120
+ abi <abi/4.0>,
121
+ include <tunables/global>
122
+ profile deep-agent-bwrap /usr/bin/bwrap flags=(unconfined) {
123
+ userns,
124
+ }
125
+ ```
126
+
127
+ ```bash
128
+ sudo apparmor_parser -r /etc/apparmor.d/deep-agent-bwrap
129
+ ```
130
+
131
+ 这是针对该可执行文件的 userns 例外,会影响通过该文件启动的所有 bwrap 调用;它不是额外的文件访问隔离策略,工作区隔离仍由 Bubblewrap 完成。已有发行版 profile 时,应调整其本地 override,避免添加相同路径的冲突 profile;也可使用管理员拥有的独立 bwrap 副本并只给该路径授权。不要给 Python 或整个用户目录通配授权,也不默认关闭全局 AppArmor/userns 保护。删除自定义 profile 时先运行 `sudo apparmor_parser -R /etc/apparmor.d/deep-agent-bwrap`,再删除该文件。
132
+
133
+ 若日志没有 AppArmor 拒绝记录,可能是容器、seccomp 或内核不支持所需 namespace,上述 profile 不会解决这些限制。程序默认拒绝启动隔离失败的沙箱;只有明确配置 `sandbox.allow_unsandboxed: true` 或交互输入 `UNSANDBOXED` 才授权宿主执行。沙箱测试被跳过表示当前环境未验证隔离能力,不代表兼容。
84
134
 
85
135
  ### Configure
86
136
 
@@ -126,16 +176,42 @@ llm:
126
176
  provider: openai-compatible
127
177
  stream_usage: true
128
178
  context_window: 1m
179
+ reasoning_efforts: [none, low, medium, xhigh] # Qwen3.8 的档位
129
180
  models:
130
181
  auto: # 由 Token Plan 侧自动路由
131
182
  input: [text]
183
+ reasoning_efforts: [] # 未确认 auto 的枚举,清除来源配置,只提供 default
132
184
  qwen3.8-max:
133
185
  input: [text, image]
186
+ # 省略 reasoning_efforts,继承来源的枚举。
187
+ glm-5.3:
188
+ input: [text]
189
+ reasoning_efforts: [low, high, max] # 完整覆盖来源枚举,不支持关闭思考
134
190
  ```
135
191
 
136
192
  `llm.default` 必须明确指定已配置的 `来源/模型`,例如 `token-plan/auto`。`local`、`token-plan` 和模型键都是自定义名称;模型键默认也是发给 API 的模型名,需要别名时在模型项内写 `model:`。配置只接受 `llm.models.<来源>.models.<模型>` 结构;旧版 `llm.model`、扁平 `llm.models.<模型>` 以及放在 `llm` 顶层的端点或密钥字段都会报错。缺少默认模型、字段无效或 YAML 语法错误时,启动会指出配置文件及错误位置,不会默默切换模型。
137
193
 
138
- `/model` 先选来源,再选来源下的模型;在模型列表按 `Esc` 返回来源列表。`/model token-plan` 可直接打开该来源,`/model token-plan/auto` 可直接切换。`context_window` 决定自动压缩阈值和占用百分比分母。区域按自己的开通情况替换 `cn-beijing`。密钥只写在 workspace 外的配置里,不要提交进仓库。
194
+ ### 模型与推理强度
195
+
196
+ `/model` 依次选择来源、具体模型、思考强度;第三段确认后统一提交,`Esc` 逐段返回。模型列表直接显示实际 API 模型名,例如 `qwen3.5-plus`;命令参数仍使用 YAML 中的 `来源/模型键`。`/model token-plan` 直接打开该来源,`/model token-plan/qwen3.8-max` 直接进入强度选择。底栏按 `来源 · 模型 · 强度` 显示,例如 `token-plan · qwen3.8-max · medium`。
197
+
198
+ `reasoning_efforts` 由用户按实际模型、端点和 API 协议配置:
199
+
200
+ - 有非空枚举时,菜单只显示该枚举,不添加 `default`;选择其他模型时默认定位到枚举第一项。
201
+ - 未配置或枚举为空时,菜单只有 `default`,请求不传强度参数。`default` 使用服务端默认行为,不代表关闭思考。
202
+ - 来源级枚举由子模型继承;子模型声明的枚举完整覆盖,显式 `null` 或 `[]` 清除继承。
203
+ - `none` 只有在实际 API 支持时才能加入枚举;它用于关闭思考,`low` 仍然会思考。不要把 `default` 写进枚举。
204
+
205
+ | provider | 强度参数 |
206
+ |---|---|
207
+ | `openai-compatible` | Chat Completions 的 `reasoning_effort` |
208
+ | `qwen-responses` | Responses 的 `reasoning.effort` |
209
+
210
+ 两种协议的可选值可能不同。例如,百炼 DeepSeek V4.1 Flash 的 Chat Completions 文档列出 `low/high/max`,关闭思考使用 `enable_thinking=false`;Responses 则明确支持 `none/low/high/max`。本项目只通过 effort 控制强度,因此当前 Chat Completions 配置不加入未经文档确认的 `none`。详见 [Chat 参数](https://help.aliyun.com/zh/model-studio/qwen-api-via-openai-chat-completions)、[Responses 参数](https://help.aliyun.com/zh/model-studio/qwen-api-via-openai-responses) 和 [GLM 参数](https://help.aliyun.com/zh/model-studio/glm)。其他厂商模板见 [config.example.yaml](agent/config.example.yaml)。
211
+
212
+ 空闲且无中断时,模型切换立即生效,提示为 `Model: 来源 · 模型 · 强度`。任务执行中或有未完成的审批/暂停中断时才排队,提示为 `Model queued: …`;旧调用与工具流程完成后,在下一次模型推理前生效。`/permission` 在同样的安全边界生效。已有 `ask` 审批仍需按 `F2` 批准或拒绝,`/permission allow` 不会自动批准旧调用。
213
+
214
+ 已持久化会话保存当前及待切换配置,恢复该会话时继续使用;尚未发送消息的新会话只在内存中保存选择。`context_window` 决定自动压缩阈值和占用百分比分母。区域按自己的开通情况替换 `cn-beijing`。密钥只写在 workspace 外的配置里,不要提交进仓库。
139
215
 
140
216
  ### Resume
141
217
 
@@ -146,6 +222,8 @@ deep-agent resume 01a08aae-... # 按 id 恢复
146
222
 
147
223
  源码仓库中也可运行 `python -m agent.cli.main`。没有 `bwrap` 时默认拒绝启动;交互式终端只有输入 `UNSANDBOXED` 才会降级到宿主执行。
148
224
 
225
+ 直接运行 `deep-agent` 开始新会话;要继续之前的对话,使用上述 `resume` 命令或 TUI 中的 `/resume`。恢复只加载已有状态,不自动调用模型。`/new` 同样先创建内存中的会话,首次发送消息后才持久化。反复启动、退出或执行 `/new` 不会积累新的空记录;旧版本留下的空记录不会自动清理。
226
+
149
227
  ## Usage
150
228
 
151
229
  进入交互会话后,普通文本就是任务。以 `/` 开头是命令。
@@ -153,13 +231,13 @@ deep-agent resume 01a08aae-... # 按 id 恢复
153
231
  ```text
154
232
  /help 命令与快捷键
155
233
  /status 工作区、沙箱、权限、session
156
- /session 当前线程、创建/更新时间与 SQLite 路径
157
- /new 开一条新线程
234
+ /session 当前线程与 SQLite 路径;已保存会话显示创建/更新时间
235
+ /new 新建会话,首次发送消息后保存
158
236
  /resume 列出有内容的会话并选择恢复
159
237
  /resume a1b2 按 id 前缀切换 session
160
- /model 先选来源,再选模型
238
+ /model 依次选择来源、模型、思考强度
161
239
  /model token-plan 打开 Token Plan 模型列表
162
- /model token-plan/auto 直接切换模型
240
+ /model token-plan/auto 选择思考强度,确认后提交切换
163
241
  /compact 达到手动压缩门槛后摘要旧对话;未达到时显示当前占用百分比
164
242
  /permission ask|allow # allow 仅 SANDBOXED 且开放沙箱网络;UNSANDBOXED / CUSTOM 只有 ask
165
243
  /image clipboard | <path> | clear
@@ -172,7 +250,8 @@ deep-agent resume 01a08aae-... # 按 id 恢复
172
250
  | 操作 | 按键 |
173
251
  |------|------|
174
252
  | 提交;运行中注入 steering | `Enter` |
175
- | 命令候选 | 输入 `/` 后用方向键选择,`Tab` / `Enter` 填入,再按 `Enter` 执行 |
253
+ | 拖选并复制转录内容 | 鼠标左键拖动,松开后自动复制,可用 `Ctrl+V` 粘贴 |
254
+ | 命令候选 | 输入 `/` 后用方向键选择,`Tab` / `Enter` 填入,再按 `Enter` 执行;`/model ` 和 `/permission ` 也会补全参数 |
176
255
  | 换行 | `Ctrl+J` |
177
256
  | 排到本轮结束后再问 | `Alt+Enter` |
178
257
  | 上滚时回到底部;再次按下执行当前界面的取消操作 | `Esc`;也可点击 `↓ Back to bottom · esc` |
@@ -185,10 +264,18 @@ deep-agent resume 01a08aae-... # 按 id 恢复
185
264
  | 取回未应用的 steering | `Alt+Up` |
186
265
  | 回看历史输出 | 滚轮 / `PgUp` / `PgDn`,`Ctrl+Home` 到顶,`Ctrl+End` 回到底部跟随 |
187
266
 
188
- 输入 `/` 时显示命令候选,按 `Esc` 可直接清空尚未执行的命令。执行 `/model` 等交互式命令时,蓝色分隔线将选择界面与对话区隔开;如果对话已上滚,居中的 `↓ Back to bottom · esc` 提示显示在分隔线正上方。转录区隐藏右侧滚动条,可用滚轮、翻页键或 `Ctrl+Home` / `Ctrl+End` 滚动。
267
+ 输入 `/` 时显示命令候选;输入 `/model ` 时补全已配置的来源与模型 ID,输入 `/permission ` 时补全当前环境可用的 `ask`、`allow`。按 `Esc` 可直接清空尚未执行的命令。执行 `/model` 等交互式命令时,蓝色分隔线将选择界面与对话区隔开;如果对话已上滚,居中的 `↓ Back to bottom · esc` 提示显示在分隔线正上方。转录区隐藏右侧滚动条,可用滚轮、翻页键或 `Ctrl+Home` / `Ctrl+End` 滚动。
268
+
269
+ 转录区可直接按住鼠标左键拖选,松开后自动复制选中文本到系统剪贴板;拖到转录区顶部或底部会持续滚动,以便选中屏幕外的历史内容。无需按 `Ctrl+Shift`。
270
+
271
+ 粘贴 500 字符及以上的文本时,输入框用 `[Pasted Content XXXX chars]` 块代替长正文,周围仍可继续编辑文字;提交时会把块还原成完整粘贴内容发送给 Agent。短文本保持原样。
272
+
273
+ 运行中按 `Enter` 提交的 steering 会在下一次工具调用开始前交给 Agent:如果模型返回时已有新输入排队,先取消这批尚未进入审批或执行的调用,再带着新输入重新推理。已经进入审批的调用仍需按原权限处理;已经开始的工具会先完成。`Alt+Enter` 提交的 follow-up 则在当前任务结束后开始新一轮。
189
274
 
190
275
  探索类工具调用合并显示为 `Explored N items`,只预览最后五项;省略项数量显示在预览上方,底部灰色的 `Ctrl+O to expand` 提示可展开完整工具详情。再次按 `Ctrl+O` 可收起。
191
276
 
277
+ 底栏的 Git 状态在后台刷新,首次探测期间显示 `⎇ checking git`。Git 未安装、探测报错或超时分别显示 `git unavailable`、`git error`、`git timeout`;只有确认当前目录不属于仓库时才显示 `⎇ no git`。探测允许最长 10 秒,适用于 Git 状态扫描较慢的工作区;超时后保留已识别的分支名。
278
+
192
279
  `web_search` 单独显示查询和结果数,按 `Ctrl+O` 展开结果摘要。`write_file` 根据执行前的文件状态显示 `Create /path` 或 `Wrote /path`;连续创建多个文件合并为 `Create N files`,按 `Ctrl+O` 展开完整文件列表。覆盖写入预览显示写入行数和前六行内容,省略的行数在下方提示;按 `Ctrl+R` 查看完整内容,不在写入预览或审阅中显示 `/dev/null`、`+++`、`@@` 等 diff 头。恢复已中断会话时,没有保存工具结果的历史调用显示灰色 `interrupted (completion unconfirmed)`,不会继续转圈;仍待审批的调用显示等待状态。
193
280
 
194
281
  工具失败时显示灰色圆点、`Failed (exit N)`、具体命令或工具目标,以及简短错误;`Ctrl+O` 展开完整输出。探索组在标题中统计失败数,并额外列出最近的失败项。`execute` 显示命令的真实退出码;没有进程退出码的工具错误以约定的 `exit 1` 显示。搜索超时但返回部分结果时只提示结果不完整,不计为失败。
@@ -211,7 +298,7 @@ result = runner.invoke("列出 /workspace 下的文件")
211
298
  `execute` 的 `tool_completed` 事件在 `result` 中携带 `exit_code`、`truncated`、`host_log_path`、`agent_log_path` 和 `termination_reason`;`content` 仍是发给模型的可读结果。
212
299
 
213
300
  默认工具包括文件、沙箱命令、人工输入和 `write_todos`;配置 Tavily 密钥后另行注册 `web_search`。`agent.tools.examples` 中的文档查询示例需要作为 `extra_tools` 显式加入;自定义副作用工具需要通过 `interrupt_on` 显式追加审批规则,内置审批规则不能被覆盖。工具异常不会自动重试,以免超时后重复执行副作用;模型传输错误由 OpenAI SDK 最多重试两次。
214
- 人工输入只使用 `request_human_input`:可传 `fields` 描述文本、布尔或选择题;恢复时用 `runner.submit_human_input({"text": "..."})`。审批用 `approve_tool` / `reject_tool`,暂停用 `continue_run`。旧工具 `handoff_to_human` 已移除,停在该工具调用上的旧会话恢复时会给出迁移错误。
301
+ 人工输入只使用 `request_human_input`:可传 `fields` 描述文本、布尔或选择题;每道选择题自动提供 `Other:` 自定义输入,单选回传自定义文本,多选将其加入结果列表;恢复时用 `runner.submit_human_input({"text": "..."})`。审批用 `approve_tool` / `reject_tool`,暂停用 `continue_run`。旧工具 `handoff_to_human` 已移除,停在该工具调用上的旧会话恢复时会给出迁移错误。
215
302
 
216
303
  传入 `create_deep_agent()` 的 `middleware=[...]` 是附加到默认栈,不会整表替换。Deep Agents 0.7.17 会自动加入 `create_summarization_middleware(model, backend)`。本项目只禁用了默认 general-purpose subagent,没有 `excluded_middleware`,因此自动压缩是开着的。
217
304
 
@@ -293,6 +380,7 @@ CLI 使用 `DEEP_AGENT_CONFIG` 指定的现有配置,否则读取 `~/.deep-age
293
380
  | `llm.models.<source>.api_key` | `sk-local` | 来源共用密钥;模型级可以覆盖 |
294
381
  | `web_search.tavily_api_key` | `null` | 私有配置中的 Tavily 密钥;`TAVILY_API_KEY` 环境变量优先 |
295
382
  | `llm.models.<source>.provider` | `qwen-responses` | 来源共用 `qwen-responses` 或 `openai-compatible`;模型级可以覆盖 |
383
+ | `llm.models.<source>.reasoning_efforts` | `[]` | 推理强度枚举;子模型省略时继承,声明时完整覆盖,`null`/`[]` 清除;非空时 CLI 仅显示枚举,空时仅显示 `default` |
296
384
  | `llm.models.<source>.stream_usage` | `false` | 流式 Chat Completions 请求附带 `stream_options.include_usage`;模型级可以覆盖 |
297
385
  | `llm.models.<source>.base_url` | `http://localhost:8000/v1` | 来源共用推理端点;模型级可以覆盖 |
298
386
  | `llm.models.<source>.models.<name>.input` | `[text]` | 图片模型写成 `[text, image]` |
@@ -320,11 +408,11 @@ web_search:
320
408
  `execute` 输出超限时,完整日志保存到当前工作区的 `.deep-agent/logs/exec/`。最终工具结果同时给出宿主机真实路径和 Agent 可用文件工具读取的 `/workspace/.deep-agent/logs/exec/...` 路径。建议在自己的项目 `.gitignore` 中加入 `.deep-agent/`;程序不会修改项目的忽略规则。
321
409
  父 shell 退出后,如果后台进程仍占有输出管道,`execute` 会继续收集数据,直到管道关闭或连续 100 毫秒没有新输出;后台进程在此后写出的内容不会进入本次工具结果。
322
410
 
323
- `qwen-responses` 使用 `QwenChatOpenAI` 和 Responses API;`openai-compatible` 使用普通 `ChatOpenAI`,固定走 Chat Completions,百炼 Token Plan 的 compatible-mode 端点走这一条。两者都可通过 `AttachmentStore` 引用发送图片,前提是模型 profile 声明 `input: [text, image]` 且端点支持图片。
411
+ `qwen-responses` 使用 `QwenChatOpenAI` 和 Responses API;`openai-compatible` 固定走 Chat Completions,使用 `ReasoningChatOpenAI` 保留兼容端点流式和非流式响应中的 `reasoning_content`,供思考区展示及会话恢复,并在后续请求中透传已有思考内容。两者都可通过 `AttachmentStore` 引用发送图片,前提是模型 profile 声明 `input: [text, image]` 且端点支持图片。
324
412
 
325
413
  每次构图都会按默认身份、`agent.instructions`、工作区根目录 `AGENTS.md` 的顺序组成 system prompt;`AGENTS.md` 映射到 Agent 内的 `/workspace/AGENTS.md`。切换模型或权限会重新读取它。作为库调用时,`create_agent(instructions="...")` 可覆盖配置中的长期说明。
326
414
 
327
- LangGraph checkpoint 保存消息、中断和图状态;同一 SQLite 的 `session_catalog` 另存 thread 的 model、permission 和上一轮运行原因,展示状态按运行原因计算。旧 catalog 在打开时迁移。旧会话若保存了已不存在的扁平模型 ID,恢复时会提示该模型不可用,并改用 YAML 指定的默认模型;旧 ID 不会被当作新模型别名。模型的 `finish_reason` 保留在 checkpoint 消息中。`/resume` 只恢复状态,不调用模型。若上一轮是 `pending` 且已有 checkpoint,或上一轮是 `aborted`、`error`,下一次用户输入保持原文写入 checkpoint,恢复说明仅临时加入首次模型请求。空白新 thread 的 `pending` 不触发恢复说明。明确的审批或暂停中断仍按 checkpoint 恢复,不自动重跑工具。切换或新建会话时,TUI 会把未执行的 steering / follow-up 退回输入框;库调用者需先取回队列,才能切换会话。
415
+ CLI 启动及 `/new` 创建的新会话先保留在内存中,首次提交消息后才写入会话目录并取得持久化锁;未发送消息就退出或恢复其他会话,不留下空会话记录。历史空记录不会自动删除。LangGraph checkpoint 保存消息、中断和图状态;同一 SQLite 的 `session_catalog` 另存 thread 的 model、permission 和上一轮运行原因,展示状态按运行原因计算。旧 catalog 在打开时迁移。旧会话若保存了已不存在的扁平模型 ID,恢复时会提示该模型不可用,并改用 YAML 指定的默认模型;旧 ID 不会被当作新模型别名。模型的 `finish_reason` 保留在 checkpoint 消息中。`/resume` 只恢复状态,不调用模型。若上一轮是 `pending` 且已有 checkpoint,或上一轮是 `aborted`、`error`,下一次用户输入保持原文写入 checkpoint,恢复说明仅临时加入首次模型请求。空白新 thread 的 `pending` 不触发恢复说明。明确的审批或暂停中断仍按 checkpoint 恢复,不自动重跑工具。切换或新建会话时,TUI 会把未执行的 steering / follow-up 退回输入框;库调用者需先取回队列,才能切换会话。
328
416
 
329
417
  同一 thread 同时只能被一个进程写入:`SessionStore` 在数据库旁的 `<db>.locks/` 目录用 `flock` 实现 thread 独占,锁文件不删除,进程退出自动释放,Agent 子进程不继承锁描述符。目标会话正被其他窗口持有时,`/resume` 和 `deep-agent resume <id>` 启动恢复都会先释放当前会话并进入等待提示,`Esc` 取消等待回到会话选择器;库调用者同步调用 `switch_session` 则直接抛出 `SessionLockBusyError`。会话切换的提交点在完成全部图与 catalog 读取之后,中途失败会回滚到原会话;`steer` / `follow_up` 在脱离会话或 Runner 关闭后会被拒绝。没有持久化存储的 Runner 只在进程内通过 checkpointer 对象互斥。
330
418
 
@@ -333,7 +421,8 @@ LangGraph checkpoint 保存消息、中断和图状态;同一 SQLite 的 `sess
333
421
  ## Development
334
422
 
335
423
  ```bash
336
- python3.12 -m venv .venv
424
+ python3 -c 'import sys; assert sys.version_info >= (3, 12), "需要 Python 3.12+"'
425
+ python3 -m venv .venv
337
426
  source .venv/bin/activate
338
427
  pip install -e ".[dev]"
339
428
  pytest -q
@@ -344,10 +433,31 @@ python -m build
344
433
 
345
434
  使用 pipx 安装过本项目时,修改源码后在项目根目录运行 `pipx install --force .`,再重启 CLI;已有进程不会自动加载新工具。
346
435
 
347
- 测试不打真模型。对着本地端点做流式冒烟:
436
+ 自动回归不调用真实模型。`python -m pytest` 包含本地模拟 OpenAI Chat Completions HTTP 服务,覆盖流式回答、工具调用、审批、暂停、恢复和 SQLite 重启恢复。可单独运行 `python -m pytest -m integration`;它需要允许监听 `127.0.0.1`。实际隔离能力测试需要可用 bwrap,`REQUIRE_BWRAP_TEST=1 python -m pytest` 将缺失能力视为失败。CI 分别验证 Python 3.12 / 3.13,并保存未放宽 AppArmor 的 Ubuntu 环境诊断报告,不把 skipped 测试当成兼容证明。
437
+
438
+ 真实模型冒烟由用户主动运行,会使用配置中的 API Key 并消耗额度,不进入默认 pytest 或自动 CI:
439
+
440
+ ```bash
441
+ python examples/e2e_live_smoke.py --help
442
+ python examples/e2e_live_smoke.py --model token-plan/qwen3.8-flash
443
+ # 默认创建并清理临时工作区/会话;指定 --workspace 时必须是空目录。
444
+ # 需要外网工具测试时额外传 --network。
445
+ python examples/sandbox_probe.py --require-sandbox
446
+ ```
447
+
448
+ `stream_smoke.py` 是 **Qwen Responses 思考流** 专用验证,不是通用模型连通性测试。配置的活动模型必须使用 `provider: qwen-responses`,端点须支持 Responses,并使用会输出思考内容的 Qwen 模型;脚本的 `--effort` 必须来自 YAML 的有效枚举且不能是 `none`。默认不指定强度时,要求服务端默认开启思考。Chat Completions、关闭思考的模型或只有回答流的模型不满足其验收条件:
348
449
 
349
450
  ```bash
350
- python examples/stream_smoke.py
451
+ python examples/stream_smoke.py --effort low
452
+ ```
453
+
454
+ 库函数 `create_agent()` 不会自动读取 `~/.deep-agent/config.yaml`,未传 `settings` 时使用 `Settings()` 的代码默认值。CLI 则先初始化配置,再通过 `Settings.load()` 读取文件。库调用如需与 CLI 一致,应显式加载:
455
+
456
+ ```python
457
+ from agent import create_agent
458
+ from agent.config import Settings
459
+
460
+ prepared = create_agent(settings=Settings.load())
351
461
  ```
352
462
 
353
463
  ## Roadmap