v0.7.x升级至v0.16.0需分阶段迁移，因架构断代：v0.9.1为关键分水岭，引入web dashboard与soul.md/agents.md双轨制，旧config.yaml完全失效；v0.16.0依赖远程gateway、状态栏模型切换及桌面端websocket连接，直接覆盖升级将导致dashboard空置、配置丢失。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你需要把旧版 Hermes Agent（v0.7.x）升级到当前最新稳定版 v0.16.0，但直接执行 upgrade 命令可能跳过关键架构变更点，导致 dashboard 无法加载、模型配置丢失或 AGENTS.md 分层规则失效。v0.7 到 v0.16 不是小步迭代，而是从命令行工具跃迁为桌面 AI 工作台的断代升级，中间跨越了 Web Dashboard 引入、远程 Gateway 架构、SOUL.md/AGENTS.md 分离机制、模糊模型选择器等八项不可逆设计变更。
v0.7.x 到 v0.16.0 的核心断代差异
从 v0.7.x 升级前必须认清：这不是补丁更新，而是重装操作系统级别的重构。v0.7.x 仍依赖纯 YAML 配置 + CLI 启动，所有规则写在 config.yaml 里；v0.16.0 默认启用 Web Dashboard 管理 profile、OAuth 远程网关、状态栏模型切换器，且强制分离 SOUL.md（角色语气）与 AGENTS.md（项目规则）。如果你现在还在用 v0.7.x 的 config.yaml 直接覆盖升级，【dashboard 将无法识别任何模型配置，所有 profile 显示为空】。
v0.9.0 是第一个分水岭：它首次引入 Web Dashboard 和微信/iMessage 原生接入，同时废除 config.yaml 全局单文件模式，改用 ~/.hermes/SOUL.md + 启动目录 AGENTS.md 双轨制。这意味着 v0.7.x 的 config.yaml 在 v0.9+ 中已完全失效，不会被自动迁移。
v0.16.0 的桌面端彻底放弃终端主控权——它不再读取本地 config.yaml，而是通过 WebSocket 连接远程 Gateway 实例，所有模型密钥、endpoint、profile 设置都存在 gateway 服务端。你在桌面端看到的“模型列表”，实际是 gateway 返回的 /models 接口响应，不是本地文件解析结果。
升级前必须做的三件事
第一步：确认当前版本是否为语义化格式。在终端运行 hermes --version，输出必须形如 v0.7.3。如果显示 dev-20240115 或 commit abc1234，说明你安装的是开发分支快照，【不能直接用 hermes update 升级，必须先切回最近的 v0.7.x tag】。
第二步：备份两处关键路径。执行：cp -r ~/.hermes ~/.hermes.backup-v07-$(date +%Y%m%d)cp -r ./workspace ./workspace.backup-v07-$(date +%Y%m%d)
注意：v0.7.x 的 workspace 目录结构与 v0.16.0 不兼容，但其中的 skill 文件、自定义工具脚本、SOUL.md 初稿仍有复用价值。
第三步：检查 Python 环境是否满足 v0.16.0 要求。v0.16.0 需要 Python ≥3.11，且依赖 uvloop 和 orjson —— v0.7.x 使用的是 asyncio + json。运行 python --version，若低于 3.11，请先升级 Python，否则 hermes dashboard 启动时会报 ImportError: cannot import name 'uvloop'。
推荐升级路径：分阶段跨版本迁移
方法一：v0.7.x → v0.9.1 → v0.16.0（最稳妥）
① 先升到 v0.9.1：执行 hermes-cli upgrade --version v0.9.1，这一步会自动创建 ~/.hermes/SOUL.md 并将原 config.yaml 中的 role、temperature 等字段迁入；
② 手动清理残留：删除 ~/.hermes/config.yaml（v0.9+ 不再读取它），确认 ~/.hermes/SOUL.md 内容可读；
③ 启动 Web Dashboard：运行 hermes dashboard --port 9119，访问 http://localhost:9119，检查是否能创建第一个 profile；
④ 最后升到 v0.16.0：执行 hermes update，此时系统已具备 v0.9+ 的配置框架，v0.16.0 的桌面端才能正确加载 profile 和模型列表。
方法二：v0.7.x → v0.16.0（激进，仅限新环境）
直接下载 v0.16.0 桌面客户端安装包（macOS/Windows/Linux），全新安装，然后手动迁移以下三项：
– 把 ~/.hermes/SOUL.md 复制到新 ~/.hermes/ 目录下；
– 把原 workspace 中的 skills/ 目录整体复制到新 workspace/skills/；
– 把项目根目录的 AGENTS.md 重命名为 .hermes.md（v0.16.0 优先识别此文件名），并确保从仓库根目录启动 Hermes。
方法三：跳过中间版本，用 gateway 解耦（适合团队部署）
在远程服务器上单独部署 v0.16.0 Gateway（使用 docker run -p 8080:8080 hermes/gateway:v0.16.0），本地桌面端只装 v0.16.0 GUI，通过 Settings → Remote Gateway 输入 http://your-server:8080/oauth；
这样本地无需保留任何模型密钥，v0.7.x 的旧配置完全不参与升级流程，所有风险隔离在 gateway 服务端。
升级后必验的三个致命点
验证点一：Web Dashboard 是否能加载 profile 列表。启动 hermes dashboard 后，点击左上角 “+ New Profile”，如果弹出窗口中 Model Provider 下拉为空，说明 v0.7.x 的 API Key 未被正确导入 gateway 或 endpoint 配置格式错误。v0.16.0 的 Custom Endpoint 必须带 https:// 前缀，且 path 不能以 /v1 结尾（例如 4sAPI 应填 https://api.4sapi.com，而非 https://api.4sapi.com/v1）。
验证点二：拖拽文件是否触发解析。在桌面端聊天窗口直接拖入一个 README.md 文件，等待 3 秒。若右下角状态栏显示 “Processing file…” 但无后续响应，说明 v0.16.0 的 file handler 未启用，需检查 ~/.hermes/config.yaml 中是否包含 file_processing: true 字段（v0.7.x 配置无此字段，必须手动添加）。
验证点三：Cmd+K 指令面板能否调出命令。按下 Cmd+K（macOS）或 Ctrl+K（Windows/Linux），输入 “session”。如果无任何提示，说明 desktop 客户端未成功连接 gateway —— 此时检查终端是否有 WebSocket connection failed 日志，常见原因是 gateway 服务未运行或防火墙拦截了 8080 端口。
