cowagent升级前必须执行三步强制备份：备份config.json为config.json.bak、记录cow --version或查看changelog.md确认版本、复制plugins/为plugins_backup/，缺一不可。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你正在运行 CowAgent v1.x（原 chatgpt-on-wechat），想升级到 v2.x 并保留全部配置、插件和历史记忆，但担心升级后服务崩溃、插件失效或配置键名报错——这不是小概率事件，而是 v2.0.0 发布后 GitHub 上高频出现的三类卡点：KeyError 启动失败、plugins/ 目录被清空、Docker 镜像拉取 404。
CowAgent 升级前强制备份三步法
这三步不做，80% 的升级问题无法回滚。不是建议，是硬性前提。
第一步：备份 config.json 文件。CowAgent v2.x 不会自动迁移旧配置，【config.json.bak 必须手动创建，不能只靠 git commit】。执行：cp config.json config.json.bak
第二步：记录当前版本号。不要只看 README，要执行 cow --version 或打开项目根目录下的 CHANGELOG.md，确认末尾版本是否为 v1.9.3 或更低——v1.9.4+ 已含部分 v2 兼容补丁，升级路径不同。
第三步：完整复制 plugins/ 目录。v2.x 插件加载机制重构，【v1.x 插件不会被自动识别，必须人工恢复】。执行：cp -r plugins/ plugins_backup/。注意：不要用 rsync 或 tar，避免权限丢失导致插件加载时报 PermissionDenied。
三种升级方式实测对比与选择
选错方式，轻则重装依赖失败，重则覆盖 workspace/ 导致记忆索引损坏。
方法一：cow CLI 自动升级（推荐用于干净部署）
执行 cow update。该命令会拉取最新 release 包、校验签名、重建 venv，并调用内置 _deep_merge 合并 config.json.bak 中的自定义字段。但注意：若你修改过 core/ 模块或打了 patch，此方式会直接覆盖源码。
方法二：脚本式升级（适用于 Linux/macOS 且保留本地 patch）
运行 ./run.sh update。它不替换源码，仅更新 requirements.txt 中指定版本的依赖包，并触发 config.json 字段映射器。适合你手动改过 message_handler.py 等文件的场景。
方法三：Git 手动切换（仅限高级用户）
进入项目根目录 → git fetch origin → git checkout v2.0.6 → pip3 install -e . --force-reinstall --no-deps。这一步跳过 pip 依赖重装，保留你已配置的模型路径和 OpenRouter 凭证，但要求你已提前阅读 v2.0.0 CHANGELOG.md 中的 breaking changes 表格。
用于在用户想通过浏览器自动化与 Google Gemini 或 ChatGPT 交互时。触发短语包括“ask Gemini”“ask ChatGPT”“ask GPT”“让...”。
v1.x → v2.x 配置键名变更与修复
启动时若报 KeyError: 'plugin_dir' 或 ValueError: 'model_name not found'，说明配置迁移失败。v2.x 已废弃 7 个旧键名，全部需手动修正。
① 打开 config.json.bak，搜索 "plugin_dir" → 替换为 "plugins_path"；
② 搜索 "openai_api_key" → 替换为 "api_keys.openai"；
③ 搜索 "wechat_qrcode_path" → 替换为 "wechat.qrcode_path"；
④ 检查 "llm.model" 字段值是否为字符串（如 "gpt-4o"），v2.x 要求必须是对象："llm": {"model": "gpt-4o", "provider": "openai"}；
⑤ 删除所有以 "_" 开头的键（如 "_debug_mode"），v2.x 已移除内部调试开关，保留会导致解析失败。
插件失效的紧急修复流程
升级后插件全部灰色不可用？不是 bug，是 v2.x 加载机制变更的必然结果。
执行 cow plugin list，若输出为空，则说明插件未注册。此时不要重装 pip 包，先还原插件目录：rm -rf plugins/ && cp -r plugins_backup/ plugins/。
然后逐个重载：例如 godcmd 插件，运行 cow plugin install godcmd。注意：v2.x 插件安装命令不再接受本地路径参数，【必须从官方插件仓库拉取，本地 .py 文件需先打包为 wheel】。
最后验证：重启 cow 服务，执行 cow plugin enable godcmd，再发一条 /godcmd test 指令，观察日志中是否出现 "Plugin loaded successfully"。
Docker 部署用户专属步骤
如果你用 docker-compose.yml 启动 CowAgent，升级后镜像拉取会失败——因为 v2.x 已弃用旧镜像名。
打开 docker-compose.yml，将 image: zhayujie/chatgpt-on-wechat 替换为 image: zhayujie/cow-agent:latest 或指定标签如 zhayujie/cow-agent:v2.0.6。
执行 docker-compose down && docker-compose pull && docker-compose up -d。注意：v2.x 默认挂载点已从 /app/config.json 改为 /root/.cow/config.json，【volume 映射路径必须同步更新，否则配置不生效】。
