HagiCode 为什么选择 Hermes 作为综合 Agent 核心

在构建 AI 辅助编码平台时，选择合适的 Agent 核心直接决定了系统能力的天花板。毕竟有些事情，勉强不来——选错了框架，怎么折腾都不得劲。本文分享 HagiCode 在技术选型中的思考，以及 Hermes Agent 的集成实践。

背景

做 AI 辅助编码这事儿，最头疼的莫过于选择底层 Agent 框架了。其实市面上可选的方案也挺多的，只是吧——有的功能太简单，有的部署太复杂，有的扩展性又不够看。我们要的是一个既能跑在 5 美元 VPS 上，又能接入 GPU 集群的方案，这要求说高也不高，说低吧，也不少人被劝退了。

但实际情况是，很多所谓的"全能 Agent" 要么只能跑在云端，要么本地部署要求高得离谱。花了两周时间调研各种方案后，我们做了一个大胆的决定：整个 Agent 核心推倒重来，采用 Hermes 作为综合 Agent 的底层引擎。

这决定带来的一切，或许都是冥冥之中罢。

关于 HagiCode

本文分享的方案来自 HagiCode 项目中的实践经验。HagiCode 是一个 AI 辅助编码平台，通过 VSCode 扩展、桌面客户端和 Web 服务，为开发者提供智能编码助手。或许你也用过类似的工具，只是总觉得差了那么一口气——这我们也理解。

• GitHub: github.com/HagiCode-org/site
• 官网: hagicode.com

为什么 HagiCode 需要 Hermes

在详细介绍 Hermes 之前，先说说 HagiCode 为什么会有这样的需求。这世上的事情啊，往往不是你想怎么样就能怎么样的，总得找个合适的由头。

作为一个 AI 代码助手，HagiCode 需要同时支持多种使用场景：

• 本地开发环境：开发者希望在自gu电脑上运行，数据不出本地——这年头，数据安全这事说大不大，说小也不小
• 团队协作环境：小团队可以共享部署在服务器上的 Agent——省钱嘛，大家都不容易
• 云端弹力扩展：处理复杂任务时，能自动扩展到 GPU 集群——有备无患

这种"既要又要"的需求，让我们把目光投向了 Hermes。这选择对不对我不知道，只是当时也没别的更好的办法了。

什么是 Hermes Agent

Hermes Agent 是由 Nous Research 创建的自主 AI Agent。可能有人对 Nous Research 不熟悉——他们就是开发了 Hermes、Nomos 和 Psyché 等开源大模型的实验室。说起来他们也挺不容易的，做了这么多好东西，知道的人却不多。

跟传统的 IDE 编程助手或者简单的 API 聊天包装器不同，Hermes 有一个特点：运行时间越长，能力越强。它不是一次性完成任务就完事，而是能在长时间运行中持续学习和积累经验。这点也挺像人的，是不是？

核心特性

Hermes 的几个核心特性，正好契合了 HagiCode 的需求。你说巧不巧？

这意味着 HagiCode 可以根据用户场景，选择最合适的部署方式。个人用户本地跑，团队用户服务器部署，复杂任务上 GPU——一套代码搞定。这世道，能省一事算一事罢。

多平台消息网关
Hermes 原生支持 Telegram、Discord、Slack、WhatsApp 等平台。对 HagiCode 来说，这意味着未来可以轻松支持这些渠道的 AI 助手。毕竟谁不想多几条路呢？

丰富的工具系统
40+ 内置工具，加上 MCP（Model Context Protocol）扩展能力。这对于代码助手来说太重要了——执行 shell 命令、操作文件系统、调用 Git，这些都需要工具支持。没有工具的 Agent，就像没有翅膀的鸟——想飞也飞不起来。

跨会话记忆
Hermes 有持久记忆系统，用 FTS5 全文检索召回历史对话。这让 Agent 能记住之前的上下文，不会每次都"失忆"。有时候我也想失忆一下，什么都不想，可就是做不到。

HagiCode 如何集成 Hermes

说完了"为什么"，接下来看看"怎么做"。有些事情想明白了，就得动手，光想不做也不是个事儿。

Provider 层抽象

在 HagiCode 的架构中，所有 AI Provider 都实现统一的 IAIProvider 接口：

public sealed class HermesCliProvider : IAIProvider, IVersionedAIProvider
{
   
    public ProviderCapabilities Capabilities {
    get; } = new ProviderCapabilities
    {
   
        SupportsStreaming = true,   // 支持流式输出
        SupportsTools = true,       // 支持工具调用
        SupportsSystemMessages = true, // 支持系统提示
        SupportsArtifacts = false
    };
}

这个抽象层让 HagiCode 可以无缝切换不同的 AI Provider，无论是 OpenAI、Claude 还是 Hermes，上层调用方式完全一致。说白了，就是省事儿。

ACP 通信协议

Hermes 使用 ACP (Agent Communication Protocol) 进行通信。这是一个专门为 Agent 通信设计的协议，主要方法包括：

HagiCode 通过 StdioAcpTransport 实现 ACP 传输层，启动 Hermes 子进程并通过标准输入输出进行通信。这事儿听起来复杂，做起来也还行——主要是要有耐心。

配置管理

通过 HermesPlatformConfiguration 类管理配置：

public sealed class HermesPlatformConfiguration : IAcpPlatformConfiguration
{
   
    public string ExecutablePath {
    get; set; } = "hermes";
    public string Arguments {
    get; set; } = "acp";
    public int StartupTimeoutMs {
    get; set; } = 5000;
    public string ClientName {
    get; set; } = "HagiCode";
    public HermesAuthenticationConfiguration Authentication {
    get; set; }
    public HermesSessionDefaultsConfiguration SessionDefaults {
    get; set; }
}

在 appsettings.json 中配置 Hermes：

{
   
  "Providers": {
   
    "HermesCli": {
   
      "ExecutablePath": "hermes",
      "Arguments": "acp",
      "StartupTimeoutMs": 10000,
      "ClientName": "HagiCode",
      "Authentication": {
   
        "PreferredMethodId": "api-key",
        "MethodInfo": {
   
          "api-key": "your-api-key-here"
        }
      },
      "SessionDefaults": {
   
        "Model": "claude-sonnet-4-20250514",
        "ModeId": "default"
      }
    }
  }
}

配置这东西吧，看着简单，真要调对了也得费些功夫。

Orleans 分布式架构

HagiCode 使用 Orleans 构建分布式系统，Hermes 集成通过以下组件实现：

• HermesGrain：Orleans Grain 实现，处理会话执行
• HermesPlatformConfiguration：平台特定配置
• HermesAcpSessionAdapter：ACP 会话适配器

• HermesConsole：专用的验证控制台

  Orleans 这名字起得挺好听的，传说中的阿里巴巴——虽然此 Orleans 非彼 Orleans，但名字好听总是加分的。

完整执行流程

以下是 Hermes Provider 的核心执行逻辑：

private async IAsyncEnumerable<AIStreamingChunk> StreamCoreAsync(
    AIRequest request,
    string? embeddedCommandPrompt,
    [EnumeratorCancellation] CancellationToken cancellationToken)
{
   
    // 1. 创建传输层，启动 Hermes 子进程
    await using var transport = new StdioAcpTransport(
        platformConfiguration.GetExecutablePath(),
        platformConfiguration.GetArguments(),
        platformConfiguration.GetEnvironmentVariables(),
        platformConfiguration.GetStartupTimeout(),
        _loggerFactory.CreateLogger<StdioAcpTransport>());
    await transport.ConnectAsync(cancellationToken);

    // 2. 初始化，获取协议版本和认证方法
    var initializeResult = await SendHermesRequestAsync(
        transport, nextRequestId++, "initialize",
        BuildInitializeParameters(platformConfiguration), cancellationToken);

    // 3. 处理认证
    var authMethods = ParseAuthMethods(initializeResult);
    if (!isAuthenticated)
    {
   
        var methodId = platformConfiguration.Authentication.ResolveMethodId(authMethods);
        await SendHermesRequestAsync(transport, nextRequestId++, "authenticate", ...);
    }

    // 4. 创建会话
    var newSessionResult = await SendHermesRequestAsync(
        transport, nextRequestId++, "session/new",
        BuildNewSessionParameters(platformConfiguration, workingDirectory, model), cancellationToken);
    var sessionId = ParseSessionId(newSessionResult);

    // 5. 执行提示并收集流式响应
    await foreach (var payload in transport.ReceiveMessagesAsync(cancellationToken))
    {
   
        // 处理 session/update 通知，转换为流式块
        if (TryParseSessionNotification(root, out var notification))
        {
   
            if (_responseMapper.TryConvertToStreamingChunk(notification, out var chunk))
            {
   
                yield return chunk;
            }
        }
    }
}

代码嘛，看多了也就那么回事。重要的是思路，对吧？

健康检查

为了保证 Hermes 服务的可用性，HagiCode 实现了健康检查机制：

public async Task<ProviderTestResult> PingAsync(CancellationToken cancellationToken = default)
{
   
    var response = await ExecuteAsync(
        new AIRequest
        {
   
            Prompt = "Reply with exactly PONG.",
            CessionId = null,
            AllowedTools = Array.Empty<string>(),
            WorkingDirectory = ResolveWorkingDirectory(null)
        },
        cancellationToken);

    var success = string.Equals(response.Content.Trim(), "PONG", StringComparison.OrdinalIgnoreCase);
    return new ProviderTestResult
    {
   
        ProviderName = Name,
        Success = success,
        ResponseTimeMs = stopwatch.ElapsedMilliseconds,
        ErrorMessage = success ? null : $"Unexpected Hermes ping response: '{response.Content}'."
    };
}

这大概就是所谓的"健康检查"了罢。其实人也一样，总要时不时检查一下自己——只是通常没人告诉我们应该检查什么。

实践中的注意事项

集成 Hermes 过程中，有一些坑值得提前了解。这年头，谁还没踩过几个坑呢？

认证方法配置

Hermes 支持多种认证方法（API Key、Token 等），需要根据实际部署情况选择。配置错误会导致连接失败，但错误信息可能不够直观。有时候报错信息跟实际原因差了十万八千里，得慢慢排查。

MCP 服务器配置

创建会话时可以配置 MCP 服务器列表，让 Hermes 调用外部工具。但要注意：

• MCP 服务器地址必须可访问
• 超时时间要合理设置
• 服务器不可用时的降级处理

这世道，防不胜防啊。

工作目录管理

每个会话都需要指定工作目录，确保 Hermes 能正确访问项目文件。对于多项目场景，需要动态切换工作目录。说起来简单，做起来要考虑的情况也挺多的。

响应聚合处理

Hermes 的响应可能分散在 session/update 通知和最终结果中，需要正确合并处理，否则会出现内容丢失。这事儿我也没少吃亏，慢慢就好了。

错误处理策略

运行时错误应该明确返回，而不是静默回退到其他 Provider。这样用户才知道是 Hermes 出了问题，而不是莫名其妙换了别的模型。毕竟糊弄事儿也不是这么个糊弄法。

总结

HagiCode 选择 Hermes 作为综合 Agent 核心，不是拍脑袋的决定，而是基于实际需求和技术特点的慎重选择。这选择对不对，现在说也为时过早，只是目前用起来还算顺手。

Hermes 提供的灵活部署能力，让 HagiCode 可以适应各种使用场景；强大的工具系统和 MCP 支持，让 AI 助手能真正干实事；而 ACP 协议和 Provider 抽象层，则让整个集成过程清晰可控。

如果你正在为你的 AI 项目选择 Agent 框架，希望这篇文章能提供一些参考。毕竟，选对底层架构，后续开发会轻松很多......

如果本文对你有帮助

• 来 GitHub 给个 Star：github.com/HagiCode-org/site
• 访问官网了解更多：hagicode.com
• 观看 30 分钟实战演示：www.bilibili.com/video/BV1pirZBuEzq/
• 一键安装体验：docs.hagicode.com/installation/docker-compose
• Desktop 桌面端快速安装：hagicode.com/desktop/
• 公测已开始，欢迎安装体验
• Hermes 官方文档

原文与版权说明

感谢您的阅读,如果您觉得本文有用,欢迎点赞、收藏和分享支持。
本内容采用人工智能辅助协作,最终内容由作者审核并确认。

• 本文作者: newbe36524
• 原文链接: https://docs.hagicode.com/go?platform=aliyun-community&target=%2Fblog%2F2026-03-19-hagicode-hermes-agent-core%2F
• 版权声明: 本博客所有文章除特别声明外,均采用 BY-NC-SA 许可协议。转载请注明出处!