19. 二开路线：想改一个能力时从哪里下手

这篇解决什么问题

源码看懂一部分后，真正的问题是：想改一个功能时，该从哪里下手？

Hermes 的目录多，如果层级判断错，很容易在 Agent loop 里改工具，在 Gateway 里改模型，在 Skill 里硬塞本该属于配置的东西。

先按目标分类

想改 CLI 命令

看：

hermes_cli/main.py
hermes_cli/commands.py
cli.py

如果是 slash command，还要看 Gateway 是否也需要同步支持。

想改模型/provider

看：

agent/*_adapter.py
agent/chat_completion_helpers.py
agent/credential_pool.py
hermes_cli/auth*.py
hermes_cli/config.py

不要直接在业务逻辑里写死 provider。

想改系统提示词

看：

agent/system_prompt.py
agent/prompt_builder.py
项目里的 .hermes.md / AGENTS.md
skills/
memory

先判断这是全局规则、项目规则、Skill 流程，还是用户偏好。

想新增工具

看：

tools/registry.py
tools/<your_tool>.py
toolsets.py
model_tools.py
agent/tool_executor.py

大部分情况下，你只需要新增 tools/<your_tool>.py，然后用 registry.register() 注册。

只有要进默认工具集时，才改 toolsets.py。

想新增 Skill

看：

~/.hermes/skills/
agent/skill_utils.py
tools/skills_tool.py
agent/prompt_builder.py

Skill 是文件内容和加载规则，不要改 Agent loop 来实现某类工作流程。

想改 Gateway 平台

看：

gateway/run.py
gateway/platform_registry.py
gateway/platforms/
gateway/delivery.py
gateway/session.py

平台适配只做消息入口和出口，不要把 Agent 逻辑写进去。

想改 Cron

看：

cron/jobs.py
cron/scheduler.py
cron/scheduler_provider.py
tools/cronjob_tool.py
hermes_cli/cron.py

先判断是 job 存储、schedule 解析、执行、输出保存，还是 delivery 问题。

想接外部工具

优先看是不是适合 MCP：

tools/mcp_tool.py
config.yaml 的 mcp_servers

如果只是 Hermes 内部能力，再写内置 tool。

二开前的三个问题

每次改之前先问：

这个能力属于入口层、运行层还是能力层？
它是否需要进入模型上下文？
它是否有副作用和安全边界？

答不清，先不要写代码。

推荐小改动练习

如果你是第一次二开 Hermes，可以按这个顺序练：

1. 写一个只读工具，比如返回当前项目信息
2. 把它注册到一个非默认 toolset
3. 通过 enabled_toolsets 限制让模型调用它
4. 写一个 Skill 指导模型什么时候用它
5. 写一个 cron job 定时调用这个能力

这条线能串起 Tools、Skills、Cron 和 Agent loop。

最容易改错的地方

把流程写进工具

工具只做动作，不要塞太多“应该怎么工作”的流程。

流程应该进 Skill。

把用户偏好写进代码

用户偏好应该进 Memory 或 Profile，不应该硬编码。

把平台差异写进 Agent loop

平台差异应该留在 Gateway adapter。

Agent loop 应该尽量保持平台无关。

忽略工具结果大小

新增工具时要考虑输出会进上下文。长结果要摘要、分页或落盘。

下一篇看什么

最后一篇收束：读完这套教程后，你应该具备什么判断力。