zhuchaowe/qwen_agent

Fork 0

朱潮 3da3cc90e1 virtual_mode=False

2026-04-11 17:52:48 +08:00

12 KiB

Raw Blame History

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 进行了以下改造：

workspace_root 参数 - 自定义工作目录为 projects/robot/{bot_id}
shell_env 参数 - 传递上下文环境变量（ASSISTANT_ID, USER_IDENTIFIER, TRACE_ID）
middleware 参数 - 支持外部传入自定义中间件列表
checkpointer 参数 - 支持外部传入 PostgreSQL checkpointer
store 参数 - 支持外部传入 store
CustomAgentMemoryMiddleware - 修改路径显示为 ./
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 执行功能：

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 源代码，在其基础上添加缺失的参数支持。

原因

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

技术考虑

1. FilesystemBackend 的 root_dir 支持

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

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

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

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

原实现（使用 ShellMiddleware）：

from deepagents_cli.shell import ShellMiddleware

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

新实现（使用 LocalShellBackend）：

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 中的导入：

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

# 旧：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 环境变量的传递方式：

# 原代码（使用 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 的父类：

# 旧代码
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: 测试

单元测试

poetry run pytest tests/test_deep_assistant.py -v

集成测试

# 启动服务
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分钟）

# 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 数据不兼容：

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

成功<EFBFBD><EFBFBD>准

所有现有功能正常工作
性能无明显下降（响应时间 < 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
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 状态: 已完成

12 KiB Raw Blame History Unescape Escape