v0.15 把运行了16个月的
run_agent.py（16,083行）拆成了14个独立模块，启动速度从30秒降到秒级。但这意味着你的旧配置、自定义 Skill、MCP 接入都可能需要调整。本文给出完整迁移清单和可复制的配置模板。
背景：这次更新为什么叫「速度版」
Hermes Agent 在 2026年5月28日推送了 v0.15.0，代号 "The Velocity Release"。这个版本的核心动作只有一个：拆解单体文件。
从项目诞生以来，run_agent.py 一直在膨胀——Agent 启动、工具调用、记忆管理、子任务调度、会话恢复……所有核心逻辑挤在一个文件中。到 v0.14.0 时，它已经涨到 16,083 行。
v0.15 的解决方案很干脆：按功能域拆成 14 个独立文件，放在新建的 agent/ 目录下。拆完后的 agent/run.py 只剩 3,821 行——缩减了 76%。
这次重构的总量级：
- 1,302 次提交，747 个合并 PR
- 282,712 行新增代码，净增 24.6 万行
- 关闭 560+ 个 issue（含 15 个 P0、65 个 P1、19 个安全类）
- 321 名社区贡献者参与
带来的直接效果：冷启动从 30 秒级降到秒级。而且模块化之后，每个功能域可以独立迭代，不再互相阻塞。
发布 28 小时后，v0.15.1 热修复跟进——修复了 Dashboard 无限刷新循环、Kanban SIGTERM 优雅退出、/yolo 模式认证绕过等关键问题。
迁移第一步：看懂新的模块地图
v0.14 时代，你想改一个工具调用逻辑，得在 16,083 行里大海捞针。现在每个功能域有独立文件：
agent/
├── run.py # Agent 启动流程（原 __main__ 段）
├── tools.py # 工具调用管理（tool dispatch）
├── memory.py # 记忆管理（conversation context）
├── delegate.py # 子 Agent 调度（delegate_task）
├── session.py # 会话管理（恢复/持久化）
├── config.py # 配置加载（settings/skills 解析）
├── provider.py # LLM Provider 适配（OpenAI/Anthropic/DeepSeek 等）
├── skills.py # Skill 加载和执行
├── cron.py # Cron 任务调度
├── browser.py # 浏览器自动化（Playwright 集成）
├── dashboard.py # Web Dashboard
├── kanban.py # Kanban 任务面板
├── mcp.py # MCP 协议支持
└── utils.py # 公共工具函数
和你的关系：如果你有以下任一种情况，需要做迁移适配：
- ❌ 直接修改过旧版
run_agent.py→ 必须迁移 - ❌ 自定义 Skill 中 hardcode 了旧模块路径 → 需要更新 import
- ❌ 用了
--config指向旧版配置结构 → 配置 schema 有变化 - ✅ 只用
hermes new默认配置 + 官方 Skill → 大概率开箱即用
迁移第二步：配置文件的三个关键变化
2.1 Provider 配置：从全局到多 Provider 支持
v0.15 的 agent/config.py 支持为不同场景指定不同 Provider。旧配置只有一个全局模型：
# v0.14 旧配置（单 Provider）
model: claude-sonnet-4-5-20250929
provider: anthropic
api_key: sk-ant-xxx
v0.15 的新配置支持多 Provider 路由：
# v0.15 新配置（多 Provider 路由）
providers:
default:
type: anthropic
model: claude-sonnet-4-5-20250929
api_key: ${ANTHROPIC_API_KEY}
reasoning:
type: openai
model: gpt-5.1
api_key: ${OPENAI_API_KEY}
cheap:
type: deepseek
model: deepseek-chat
api_key: ${DEEPSEEK_API_KEY}
# 路由规则
routing:
- match: {task_type: reasoning}
provider: reasoning
- match: {task_type: simple}
provider: cheap
- default: default
实操建议：把你的 API Key 全部移到环境变量（${VAR_NAME} 语法），不要在配置文件中 hardcode。v0.15 的环境变量解析比旧版更严格——未定义变量会直接报错而不是静默跳过。
2.2 Skill 目录结构：从扁平到分层
v0.15 的 agent/skills.py 现在支持 Skill 分层加载：
~/.hermes/skills/
├── user/ # 用户自定义 Skill（最高优先级）
│ ├── my-toolkit/
│ │ ├── skill.md
│ │ └── scripts/
│ └── custom-workflow/
│ └── skill.md
├── project/ # 项目级 Skill
│ └── ai-neican/
│ └── skill.md
└── shared/ # 社区共享 Skill（最低优先级）
└── code-review/
└── skill.md
优先级：user > project > shared。同名 Skill 的 user 版会覆盖 project 版。
如果你有自定义 Skill，迁移步骤：
# 1. 创建新目录结构
mkdir -p ~/.hermes/skills/user/
# 2. 把旧 Skill 文件移过去
mv ~/.hermes/skills/my-skill.md ~/.hermes/skills/user/my-skill/skill.md
# 3. 更新 Skill 中的 import（如果引用了旧模块）
# 旧: from run_agent import ToolRegistry
# 新: from agent.tools import ToolRegistry
2.3 MCP 配置：独立配置文件
v0.15 把 MCP 配置从主配置中抽离到了独立的 mcp_servers.json：
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
"env": {}
},
"playwright": {
"command": "npx",
"args": ["-y", "@anthropic/mcp-server-playwright"],
"env": {
"PLAYWRIGHT_BROWSER": "chromium"
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"DATABASE_URL": "${PG_URL}"
}
}
}
}
如果你的旧配置里 MCP 是内嵌在主 YAML 中的，需要手动迁移到这个独立 JSON。
迁移第三步：测试与验证
完成配置迁移后，用以下步骤验证：
3.1 基础健康检查
# 1. 检查版本
hermes --version
# 期望输出: v0.15.1（如果已更新）
# 2. 检查配置合法性
hermes config validate
# 会逐项检查 providers/routing/skills/mcp 是否有效
# 3. 检查 Skill 加载状态
hermes skills list
# 列出所有已加载的 Skill 及优先级
3.2 功能逐项测试
# 4. 测试多 Provider 路由（用小任务测试 cheap provider）
hermes run --task "echo hello" --provider cheap
# 5. 测试 delegate_task（子 Agent）
hermes run --task "用 delegate_task 启动一个子 Agent 写首诗"
# 6. 测试 MCP 工具调用
hermes run --task "列出 /tmp 目录下的文件"
# 如果 filesystem MCP 配好了，会返回文件列表
# 7. 测试 Dashboard（先检查是否触发无限刷新）
hermes dashboard
# 浏览器打开后等 30 秒，确认不会无限 reload
3.3 性能基准对比
# 冷启动计时
time hermes run --task "echo ok" --no-mcp --no-skills
# v0.14 典型值: 25-35s
# v0.15 典型值: 3-8s（改善 70-85%）
常见踩坑与解决
坑1：Dashboard 无限刷新
现象：升级到 v0.15.0 后 Dashboard 持续 reload。
原因：loopback 模式下的 session cookie 校验逻辑变更。v0.15.0 的 agent/dashboard.py 在无有效 session 时会重定向到 /login，但 /login 又触发一次 redirect，形成死循环。
修复：升级到 v0.15.1（28小时内已修复）：
pip install --upgrade hermes-agent
hermes --version # 确认 ≥ 0.15.1
坑2：/yolo 模式认证绕过
现象：/yolo 参数在 v0.15.0 中可以绕过 session 认证，直接执行命令。
影响：部署在公网的 Hermes 实例存在安全风险。
修复：同样在 v0.15.1 中修复。如果暂时不能升级，加 nginx 层 Basic Auth 作为临时措施：
location /dashboard {
auth_basic "Hermes Dashboard";
auth_basic_user_file /etc/nginx/.htpasswd;
proxy_pass http://localhost:8080;
}
坑3：旧 Skill 中 import 失败
现象：自定义 Skill 运行时报 ModuleNotFoundError: No module named 'run_agent'。
修复：全局替换 import 路径：
# 旧版（v0.14）
from run_agent import ToolRegistry, MemoryStore, delegate_task
# 新版（v0.15）
from agent.tools import ToolRegistry
from agent.memory import MemoryStore
from agent.delegate import delegate_task
坑4：/model 选择器在不同 Provider 间不统一
现象：切换 Provider 后 /model 命令返回的模型列表不一致。
说明：v0.15.1 仍在修复中，部分 Provider 的模型列表尚未对齐。这是一个已知的 cosmetic issue，不影响实际模型调用——实际使用的模型由配置文件中的 providers.<name>.model 决定，而非 /model 显示。
新功能速览：迁移后你能利用的
① 多 Provider 自动路由
配置好 routing 规则后，Agent 会根据任务类型自动切换模型。比如：复杂推理任务自动走 OpenAI GPT-5.1，简单脚本任务走 DeepSeek。实测可节省 40-60% 的 API 成本。
② Kanban Worker 优雅退出
v0.15.1 修复后，收到 SIGTERM 时 Kanban worker 会完成当前任务再退出，而不是直接中断导致任务丢失。
③ Skill 分层覆盖
团队协作场景：项目组可以定义一个公共 Skill 放在 project/，个人可以在 user/ 覆盖其中的某些行为，无需 fork 整个 Skill。
④ 启动速度 3-8 秒
这个不用多解释——以前喝杯咖啡等 Agent 启动的日子结束了。
总结：迁移清单
□ 更新到 v0.15.1: pip install --upgrade hermes-agent
□ 把 API Key 移到环境变量，配置用 ${VAR_NAME} 引用
□ 旧 MCP 配置迁移到 mcp_servers.json
□ 自定义 Skill 的 import 从 run_agent 改为 agent.* 模块
□ 配置多 Provider 路由（可选，建议做，能省钱）
□ Skill 按 user/project/shared 分层整理
□ 运行 hermes config validate 检查
□ 逐个测试 Provider/MCP/delegate_task/Dashboard
□ 公网部署的加 nginx Basic Auth（如果暂时不能升到 v0.15.1）
一句话：v0.15 的核心价值不是新功能，是基础设施的升级。模块化之后，每个组件可以独立演进，未来的新功能添加速度会更快。现在花 10 分钟完成迁移，后面的迭代就不用每次都折腾配置了。
迁移遇到问题？在文章评论区留言你的具体报错，我来帮你排查。