qwen_agent/plans/deepagents-upgrade.md

# DeepAgents 依赖升级计划

## 概述

将 qwen-agent 项目中的 deepagents 和 deepagents-cli 依赖升级到最新版本，同时保留自定义功能（workspace_root、shell_env、自定义中间件等）。

## 问题背景

### 当前版本

| 包名 | 当前版本 | 最新版本 |
|------|---------|---------|
| deepagents | 0.2.8 | 0.4.4 |
| deepagents-cli | 0.0.11 | 0.0.25 |

### 自定义改造

项目中 `agent/deep_assistant.py:351-518` 的 `create_custom_cli_agent` 函数基于 deepagents-cli 的 `create_cli_agent` 进行了以下改造：

1. **workspace_root 参数** - 自定义工作目录为 `projects/robot/{bot_id}`
2. **shell_env 参数** - 传递上下文环境变量（ASSISTANT_ID, USER_IDENTIFIER, TRACE_ID）
3. **middleware 参数** - 支持外部传入自定义中间件列表
4. **checkpointer 参数** - 支持外部传入 PostgreSQL checkpointer
5. **store 参数** - 支持外部传入 store
6. **CustomAgentMemoryMiddleware** - 修改路径显示为 `./`
7. **CustomSkillsMiddleware** - 修改技能路径显示

### API 变更对比

| 参数 | 0.0.11 (当前) | 0.0.25 (最新) | 影响 |
|------|--------------|--------------|------|
| workspace_root | 支持（自定义添加） | 不支持 | Critical |
| shell_env | 支持（自定义添加） | 不支持 | Critical |
| middleware | 支持（自定义添加） | 不支持 | Critical |
| checkpointer | 支持外部传入 | 内部创建 InMemorySaver | Critical |
| store | 支持 | 不支持 | Important |
| enable_shell | 支持 | 支持 | 兼容 |
| sandbox_type | 支持 | 支持 | 兼容 |

## 模块迁移对照表（重要变更）

> ⚠️ **关键发现**：多个模块已从 `deepagents_cli` 迁移到 `deepagents` 包

| 模块/类名 | 旧位置 (0.0.11) | 新位置 (0.0.25) | 变更说明 |
|-----------|----------------|----------------|---------|
| `ShellMiddleware` | `deepagents_cli.shell` | **已删除** | 被 `LocalShellBackend` 替代 |
| `AgentMemoryMiddleware` | `deepagents_cli.agent_memory` | `deepagents.middleware.memory.MemoryMiddleware` | 改名为 `MemoryMiddleware` |
| `SkillsMiddleware` | `deepagents_cli.skills` | `deepagents.middleware.skills` | 迁移到 SDK |
| `settings` | `deepagents_cli.config` | `deepagents_cli.config` | 无变化 |
| `get_default_coding_instructions` | `deepagents_cli.config` | `deepagents_cli.config` | 无变化 |
| `create_cli_agent` | `deepagents_cli.agent` | `deepagents_cli.agent` | 无变化 |

### LocalShellBackend 替代 ShellMiddleware

`ShellMiddleware` 已被 `LocalShellBackend` 替代。新版本的 `LocalShellBackend` 同时提供文件系统操作和 shell 执行功能：

```python
from deepagents.backends import LocalShellBackend

# 创建 backend，支持自定义环境变量
backend = LocalShellBackend(
    root_dir=workspace_root,
    virtual_mode=False,
    env={"ASSISTANT_ID": "xxx", "USER_IDENTIFIER": "yyy"},  # 自定义环境变量
    inherit_env=True,  # 继承父进程环境变量
)
```

**参数说明**：
- `root_dir`: 工作目录
- `virtual_mode`: 虚拟路径模式
- `env`: 自定义环境变量字典
- `inherit_env`: 是否继承 `os.environ`

## 推荐方案：Fork 并修改

复制最新版本的 `create_cli_agent` 源代码，在其基础上添加缺失的参数支持。

### 原因

1. **保持控制力** - 完全控制 agent 创建过程，不受上游 API 变更影响
2. **复用新功能** - 基于新版本代码，获得 bug 修复和性能改进
3. **维护成本适中** - 只需在版本升级时同步上游变更
4. **风险可控** - 可以逐步验证每个功能

## 技术考虑

### 1. FilesystemBackend 的 root_dir 支持

**最新版本确认**：`FilesystemBackend` 仍然支持 `root_dir` 参数

```python
# 当前实现
composite_backend = CompositeBackend(
    default=FilesystemBackend(root_dir=workspace_root, virtual_mode=False),
    routes={},
)
```

**结论**：可以直接复用，无需修改。

### 2. Shell 环境变量支持（重大变更）

**原实现**（使用 ShellMiddleware）：
```python
from deepagents_cli.shell import ShellMiddleware

agent_middleware.append(
    ShellMiddleware(
        workspace_root=workspace_root,
        env=final_shell_env,
    )
)
```

**新实现**（使用 LocalShellBackend）：
```python
from deepagents.backends import LocalShellBackend

# 创建带自定义环境变量的 backend
shell_backend = LocalShellBackend(
    root_dir=workspace_root,
    virtual_mode=False,
    env=shell_env,
    inherit_env=True,
)

# 或使用 CompositeBackend 路由
composite_backend = CompositeBackend(
    default=FilesystemBackend(root_dir=workspace_root, virtual_mode=False),
    routes={
        "/shell/": shell_backend,  # shell 命令路由
    },
)
```

**结论**：需要修改 shell 环境变量的传递方式。

### 3. checkpointer 管理

**问题**：最新版本在 `create_deep_agent` 中硬编码 `InMemorySaver`

**解决方案**：在自定义的 `create_custom_cli_agent` 中保留外部传入 checkpointer 的能力。

### 4. 中间件兼容性

需要验证以下自定义中间件与最新版本的兼容性：

- `CustomAgentMemoryMiddleware` - 父类已从 `AgentMemoryMiddleware` 改名为 `MemoryMiddleware`
- `CustomSkillsMiddleware` - 父类 `SkillsMiddleware` 已迁移到 `deepagents.middleware.skills`

## 实施步骤

### Phase 1: 准备工作

- [ ] 创建升级分支 `git checkout -b upgrade/deepagents-0.4.4`
- [ ] 备份当前 `agent/deep_assistant.py`
- [ ] 更新 pyproject.toml 中的依赖版本
  ```
  deepagents = ">=0.4.4,<0.5.0"
  deepagents-cli = ">=0.0.25,<0.0.26"
  ```
- [ ] 执行 `poetry install` 安装新版本
- [ ] 执行 `poetry export -f requirements.txt -o requirements.txt --without-hashes`

### Phase 2: 更新导入语句

根据模块迁移对照表，更新 `agent/deep_assistant.py` 中的导入：

```python
# === 需要修改的导入 ===

# 旧：from deepagents_cli.shell import ShellMiddleware
# 新：不再使用 ShellMiddleware，改用 LocalShellBackend
from deepagents.backends import LocalShellBackend

# 旧：from deepagents_cli.agent_memory import AgentMemoryMiddleware
# 新：from deepagents.middleware import MemoryMiddleware
from deepagents.middleware import MemoryMiddleware

# 旧：from deepagents_cli.skills import SkillsMiddleware
# 新：
from deepagents.middleware import SkillsMiddleware

# === 无需修改的导入 ===
from deepagents_cli.config import settings, get_default_coding_instructions
from deepagents_cli.agent import create_cli_agent
```

### Phase 3: 适配 LocalShellBackend

修改 shell 环境变量的传递方式：

```python
# 原代码（使用 ShellMiddleware）
if enable_shell:
    final_shell_env = os.environ.copy()
    if shell_env:
        final_shell_env.update(shell_env)
    agent_middleware.append(
        ShellMiddleware(
            workspace_root=workspace_root,
            env=final_shell_env,
        )
    )

# 新代码（使用 LocalShellBackend）
if enable_shell:
    final_shell_env = shell_env or {}
    shell_backend = LocalShellBackend(
        root_dir=workspace_root,
        virtual_mode=False,
        env=final_shell_env,
        inherit_env=True,  # 继承 os.environ
    )
    # 将 shell_backend 传入 CompositeBackend 或作为 sandbox 参数
```

### Phase 4: 适配自定义中间件

更新 `CustomAgentMemoryMiddleware` 和 `CustomSkillsMiddleware` 的父类：

```python
# 旧代码
from deepagents_cli.agent_memory import AgentMemoryMiddleware
from deepagents_cli.skills import SkillsMiddleware

class CustomAgentMemoryMiddleware(AgentMemoryMiddleware):
    ...

class CustomSkillsMiddleware(SkillsMiddleware):
    ...

# 新代码
from deepagents.middleware import MemoryMiddleware, SkillsMiddleware

class CustomAgentMemoryMiddleware(MemoryMiddleware):
    ...

class CustomSkillsMiddleware(SkillsMiddleware):
    ...
```

**注意**：需要检查新版本的 `MemoryMiddleware` 和 `SkillsMiddleware` 的构造函数签名是否有变化。

### Phase 5: 测试

- [ ] 单元测试
  ```bash
  poetry run pytest tests/test_deep_assistant.py -v
  ```

- [ ] 集成测试
  ```bash
  # 启动服务
  poetry run uvicorn fastapi_app:app --host 0.0.0.0 --port 8001

  # 执行测试请求
  curl --request POST \
    --url http://localhost:8001/api/v2/chat/completions \
    --header 'authorization: Bearer test' \
    --header 'content-type: application/json' \
    --data '{
      "messages": [{"role": "user", "content": "你好"}],
      "stream": true,
      "model": "whatever",
      "bot_id": "test-bot",
      "session_id": "test-session"
    }'
  ```

- [ ] 功能验证
  - [ ] 文件隔离：验证不同 bot_id 的文件不互相干扰
  - [ ] 环境变量：验证 shell 命令中可以访问 ASSISTANT_ID 等
  - [ ] 中间件：验证自定义中间件正常执行
  - [ ] 会话持久化：验证 session_id 恢复对话正常

## 风险分析

### 高风险

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| API 不兼容 | 编译失败 | 逐步升级，逐个验证 |
| 功能丢失 | 业务中断 | 保留旧版本代码，快速回滚 |
| checkpointer 不兼容 | 会话丢失 | 先在测试环境验证 |
| LocalShellBackend 行为差异 | shell 执行异常 | 详细测试 shell 功能 |

### 中风险

| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 中间件不兼容 | 功能异常 | 单独测试每个中间件 |
| 性能下降 | 响应变慢 | 压力测试对比 |
| 路径显示异常 | 用户困惑 | 视觉验证 |
| MemoryMiddleware 签名变更 | 编译失败 | 检查新签名并适配 |

## 回滚策略

### 快速回滚（5分钟）

```bash
# 1. 切换回主分支
git checkout master

# 2. 恢复依赖
poetry install

# 3. 重启服务
pkill -f "uvicorn fastapi_app:app"
poetry run uvicorn fastapi_app:app --host 0.0.0.0 --port 8001
```

### 数据回滚

如果 checkpointer 数据不兼容：

```bash
# 恢复到升级前的数据库备份
pg_restore -d qwen_agent backup_before_upgrade.dump
```

## 成功<E68890><E58A9F>准

- [ ] 所有现有功能正常工作
- [ ] 性能无明显下降（响应时间 < 2s）
- [ ] 错误率 < 0.1%
- [ ] 用户无感知升级

## 参考资源

### 内部文件

- `agent/deep_assistant.py:351-518` - 当前 create_custom_cli_agent 实现
- `agent/deep_assistant.py:242-259` - workspace_root 使用
- `agent/deep_assistant.py:45-50` - 当前导入语句
- `pyproject.toml:29` - deepagents 版本约束
- `pyproject.toml:34` - deepagents-cli 版本约束

### 外部资源

- [deepagents GitHub](https://github.com/langchain-ai/deepagents)
- [deepagents 官方文档](https://docs.langchain.com/oss/python/deepagents)
- 本地克隆仓库：`/Users/moshui/Documents/felo/deepagents`

### 关键源文件（本地克隆）

| 文件 | 用途 |
|------|------|
| `libs/cli/deepagents_cli/agent.py` | 最新 create_cli_agent |
| `libs/deepagents/deepagents/backends/local_shell.py` | LocalShellBackend（替代 ShellMiddleware） |
| `libs/deepagents/deepagents/middleware/memory.py` | MemoryMiddleware（原 AgentMemoryMiddleware） |
| `libs/deepagents/deepagents/middleware/skills.py` | SkillsMiddleware |
| `libs/deepagents/deepagents/middleware/__init__.py` | 中间件导出 |
| `libs/deepagents/deepagents/backends/__init__.py` | Backend 导出 |
| `libs/cli/deepagents_cli/config.py` | settings, get_default_coding_instructions |

## 变更检查清单

升级前需要确认的关键变更：

- [ ] `ShellMiddleware` → `LocalShellBackend` 替代方案
- [ ] `AgentMemoryMiddleware` → `MemoryMiddleware` 命名变更
- [ ] `SkillsMiddleware` 导入路径变更
- [ ] `LocalShellBackend` 的 `env` 和 `inherit_env` 参数使用
- [ ] `MemoryMiddleware` 新签名适配
- [ ] `SkillsMiddleware` 新签名适配

---

**创建时间**: 2026-03-02
**状态**: 已完成