不能直接执行 hermes update 一键跳升，必须分步升级：先升至 v0.18.0 并验证运行正常、清理技能缓存，再升至 v0.19.1 并补全依赖（如 lark-oapi[feishu]），升级后须重置 api_server_key、启用飞书插件、校验网关健康状态。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
装完 Hermes Agent v0.17.0 后想升到 v0.19.1，不能直接执行 hermes update 一键跳升，因为 v0.17.0 到 v0.19.1 跨越了两个大版本（v0.18.0 和 v0.19.0），中间存在配置结构变更、依赖升级和安全策略强化，官方未提供跨多版的自动迁移路径，强行直更会导致 gateway 启动失败、飞书插件静默失效或 API Server 拒绝运行。
先确认当前环境是否满足 v0.19.1 升级前提
打开终端，进入 Hermes 安装目录：cd ~/.hermes/hermes-agent。
执行 git status，确保工作区干净——【如果有未提交修改，必须先 stash 或 commit，否则 git checkout 会失败】。
运行 hermes doctor，检查 Python 版本是否 ≥3.11.15、模型加载器是否就绪、网络能否访问 GitHub Releases 页面；任一 FAIL 都需先修复。
备份当前配置：cp -r ~/.hermes/config.yaml ~/.hermes/config.yaml.backup-$(date +%Y%m%d)，这一步不可跳过，v0.19.1 的 config.yaml 字段已重排，旧字段可能被忽略。
分步升级：先升到 v0.18.0，再升到 v0.19.1
第一步：拉取远程标签并检出 v0.18.0
执行 git fetch origin --tags → git checkout v0.18.0 → pip install -e . --force-reinstall。
第二步：验证 v0.18.0 运行正常
运行 hermes --version 确认输出含 v0.18.0 → 启动 hermes dashboard 看 Web UI 是否加载 → 执行 hermes chat -q "hello" 测试基础响应。
第三步：清理残留缓存
v0.18.0 引入了新的技能加载器缓存机制，需手动清除：rm -rf ~/.hermes/cache/skill_loader/，否则 v0.19.1 启动时会卡在 Loading SOUL.md 阶段。
第四步：升级至 v0.19.1
执行 git fetch origin --tags → git checkout v0.19.1 → pip install -e . --force-reinstall --no-deps → 最后单独运行 pip install -r requirements.txt 补全新依赖（特别是 lark-oapi[feishu]，飞书用户必装）。
升级后必须做的三件事
方法一：重置 API Server 密钥
v0.19.1 强制要求 API_SERVER_KEY ≥16 字符且不得含常见弱密码模式，编辑 ~/.hermes/config.yaml，将 api_server_key 改为类似 Qz9#mXp2!vR8&nL5 的随机字符串。
方法二：手动启用飞书插件
v0.19.1 中飞书插件默认不激活，需在配置中显式开启：plugins: {lark: {enabled: true}}，同时确认 HERMES_DISABLE_LAZY_INSTALLS 环境变量未设为 1。
方法三：校验网关稳定性
启动 hermes gateway 后，立刻执行 curl http://127.0.0.1:9119/health，返回 {"status":"ok","uptime_sec":...} 才算真正就绪；若返回 503，检查日志中是否有 delivery_ledger init failed，有则需删掉 ~/.hermes/gateway/ledger/ 目录重试。
