跳转到内容
Hagicode Docs
博客

AI Agent

2 篇包含标签 "AI Agent" 的文章

HagiCode Soul 平台技术解析：从需求萌发到独立平台的演进之路

HagiCode Soul 平台技术解析：从需求萌发到独立平台的演进之路

Section titled “HagiCode Soul 平台技术解析：从需求萌发到独立平台的演进之路”

其实写技术文章这事儿，也没什么了不起的，不过是把一些趟过的坑、绕过的弯路整理出来罢了。毕竟谁还没年轻过呢，对吧？本文将深入解析 HagiCode 项目中 Soul（AI Agent 人格配置系统）的设计理念、架构演进和核心技术实现，探讨如何通过独立平台提供更聚焦的 Agent 人格创建与分享体验。

背景

Section titled “背景”

在 AI Agent 的开发实践中，我们经常会遇到一个看似简单却极其重要的问题：如何让不同的 Agent 拥有稳定且独特的语言风格和人格特征？

这问题说起来也挺无奈的。早期 HagiCode 的 Hero 体系中，不同英雄（Agent 实例）主要依赖职业配置和通用提示词来区分表达方式。这种方式带来了一些明显的痛点，或许做过的朋友都有同感。

首先，语言风格难以保持一致。同样是”开发工程师”角色，今天的回复可能专业严谨，明天的输出又变得随意散漫。这不是模型本身的问题，而是缺乏一个独立的人格配置层来约束和引导输出风格罢了。

其次，角色感普遍较弱。当我们描述一个 Agent 的特征时，往往只能用”友好”、“专业”、“幽默”这样模糊的形容词，却没有具体的语言规则来支撑这些抽象的描述。说白了，就是说起来挺美好，做起来却没辙。

第三，人格配置的复用性几乎为零。假设我们精心设计了一个”猫娘服务员”的说话风格，想要在另一个业务场景中复用这套表达方式，几乎需要从头开始配置。美的事物或人，不一定要占用，只是想复用一下罢了…可是真的难。

正是为了解决这些实际问题，我们引入了 Soul 机制——一个独立于装备和描述的语言风格配置层。Soul 可以定义 Agent 的说话习惯、语气偏好和用词边界，可以在多个英雄间共享复用，还能在 Session 首次调用时自动注入系统提示词。

或许有人会觉得这也罢了，不就是配置几个提示词吗？可是有时候啊，问题的关键不在于能不能做，而在于怎么做更优雅。随着 Soul 能力的逐步成熟，我们意识到它已经具备了独立发展的潜力。一个专门的 Soul 平台可以让用户更聚焦地创建、分享和浏览各种有趣的人格配置，而不必被 Hero 系统的其他功能所干扰。于是，soul.hagicode.com 独立平台应运而生。

关于 HagiCode

Section titled “关于 HagiCode”

HagiCode 是一个开源的 AI 代码助手项目，采用现代化的技术栈构建，致力于为开发者提供流畅的智能编程体验。本文分享的 Soul 平台方案，正是我们在开发 HagiCode 过程中，为了解决 Agent 人格管理这一实际问题而探索出来的实践经验。如果你觉得这套方案有价值，说明我们在工程实践中积累了一定的技术判断力——那么 HagiCode 项目本身也值得关注了解一下。

Soul 平台的技术架构演进

Section titled “Soul 平台的技术架构演进”

Soul 平台的发展并非一蹴而就，而是经历了三个清晰的阶段。这故事开始得突然，结束得自然。

第一阶段：Hero 内嵌 Soul 配置

Section titled “第一阶段：Hero 内嵌 Soul 配置”

最早的 Soul 实现是作为 Hero 工作区的一个功能模块存在的。我们在 Hero 界面中增加了独立的 SOUL 编辑区域，支持预设套用和文本微调两种方式。

预设套用允许用户从一些经典人格模板中选择，比如”专业开发工程师”、“猫娘服务员”等。文本微调则让用户可以在预设基础上进行个性化修改。后端 Hero 实体相应地增加了 Soul 字段，并通过 SoulCatalogId 标识来源。

这个阶段解决了”有没有”的问题，也还算是个孩子，磕磕绊绊地成长着。但随着 Soul 内容越来越丰富，与 Hero 系统耦合在一起的架构开始显现出局限性。

第二阶段：站内 Marketplace

Section titled “第二阶段：站内 Marketplace”

为了提供更好的 Soul 发现和复用体验，我们构建了 SOUL Marketplace 目录页，支持浏览、搜索、详情查看和收藏功能。

在这个阶段，我们引入了 50 组主 Catalog（基础角色） 和 10 组正交规则（表达方式） 的组合设计。主 Catalog 定义了 Agent 的核心人设，比如”雾港旅人”、“夜航猎手”这类抽象的角色设定；正交规则则定义了表达的方式，比如”简洁干练”、“啰嗦亲切”等语言风格特征。

50 × 10 = 500 个组合可能性，为用户提供了丰富的人格配置空间。这数量说多不多，说少不少，怎么说呢，条条大路通罗马，只是有的路好走一点罢了。后端通过 catalog-sources.json 生成完整的 SOUL 目录，前端则负责将这些目录项呈现为可交互的卡片列表。

站内 Marketplace 是一个很好的过渡方案，但也只是过渡而已。它仍然依附于主系统，对于只想使用 Soul 功能的用户来说，访问路径还是太深了。毕竟谁愿意绕一大圈才能做一件简单的事呢？

第三阶段：独立平台拆分

Section titled “第三阶段：独立平台拆分”

最终，我们决定将 Soul 能力迁移到独立仓库（repos/soul），原主系统的 Marketplace 改为外部跳转引导，新平台采用 Builder-first 设计理念——默认首页即为创建工作台，用户打开网站的第一时间就可以开始创建自己的人格配置。

这个阶段的技术栈也进行了全面升级：采用 Vite 8 + React 19 + TypeScript 5.9 组合，使用 shadcn/ui 组件系统统一设计语言，引入 Tailwind CSS 4 的主题变量系统。前端工程化水平的提升，为后续的功能迭代打下了坚实基础。

一切都淡了…不，一切才刚刚开始。

核心技术设计与实现

Section titled “核心技术设计与实现”

素材整合策略

Section titled “素材整合策略”

Soul 平台的一个核心设计理念是本地优先。这意味着首页必须在无后端情况下可完全运行，远端素材失败时不得阻断页面进入。

其实这也没什么了不起的，只是在设计系统时多考虑了一步罢了。本地快照作为基线，远端作为增强，这种思路让产品在任何网络条件下都能提供基本的可用性。具体实现上，我们采用了两层素材架构：

export async function loadBuilderMaterials(): Promise<BuilderMaterials> {
  const localMaterials = createLocalMaterials(snapshot)  // 本地基线


  try {
    const inspirationFragments = await fetchMarketplaceItems()  // 远程增强
    return { ...localMaterials, inspirationFragments, remoteState: "ready" }
  } catch (error) {
    return { ...localMaterials, remoteState: "fallback" }  // 优雅降级
  }
}

本地素材来自主系统文档的构建期快照，包含 50 组基础角色和 10 组表达规则的完整数据。远端素材则来自用户发布的 Soul，通过 Marketplace API 获取。两者的结合，为用户提供了从官方模板到社区创意的完整素材光谱。想笑来伪装自己掉下的泪…不，其实没什么，就是本地加远程罢了。

Soul 碎片数据模型

Section titled “Soul 碎片数据模型”

Soul 的核心数据抽象是 SoulFragment（灵魂碎片）：

export type SoulFragment = {
  fragmentId: string
  group: "main-catalog" | "expression-rule" | "published-soul"
  title: string
  summary: string
  content: string
  keywords: string[]
  localized?: Partial<Record<AppLocale, LocalizedFragmentContent>>
  sourceRef: SoulFragmentSourceRef
  meta: SoulFragmentMeta
}

group 字段区分了碎片的类型：主目录定义角色内核，正交规则定义表达方式，用户发布的 Soul 则标记为 published-soul。localized 字段支持多语言，让同一个碎片可以在不同语言环境下呈现不同的标题和描述。国际化设计要趁早，这话我们也算是用上了。

Builder 草稿状态则封装了用户当前的编辑状态：

export type SoulBuilderDraft = {
  draftId: string
  name: string
  selectedMainFragmentId: string | null
  selectedRuleFragmentId: string | null
  inspirationSoulId: string | null
  mainSlotText: string
  ruleSlotText: string
  customPrompt: string
  previewText: string
  updatedAt: string
}

用户在编辑器中选择的每个碎片，其内容都会被拼接到对应的 slot（槽位）中，形成最终的预览文本。mainSlotText 对应主角色内容，ruleSlotText 对应表达规则内容，customPrompt 则是用户的额外补充指令。

预览编译机制

Section titled “预览编译机制”

预览编译是 Soul Builder 的核心功能，它将用户选择的碎片和自定义文本组装成可复制的系统提示词：

export function compilePreview(
  draft: Pick<SoulBuilderDraft, "mainSlotText" | "ruleSlotText" | "customPrompt">,
  fragments: {
    mainFragment: SoulFragment | null
    ruleFragment: SoulFragment | null
    inspirationFragment: SoulFragment | null
  }
): PreviewCompilation {
  // 组装逻辑：主角色 + 表达规则 + 灵感参考 + 自定义内容
}

编译结果会展示在中央预览面板中，用户可以实时看到最终效果，并一键复制到剪贴板。这功能说起来也挺简单的，不是吗？可是简单的东西往往最实用。

前端状态管理

Section titled “前端状态管理”

Soul Builder 的前端状态管理遵循一个重要原则：状态边界清晰划分。具体来说，抽屉状态不持久化，不直接写入草稿；只有明确的 Builder 操作才会触发状态变更。

// 领域状态（useSoulBuilder）
export function useSoulBuilder() {
  // 素材加载与缓存
  // 槽位聚合与预览编译
  // 复制行为与反馈消息
  // Locale 安全的描述符
}


// 呈现状态（useHomeEditorState）
export function useHomeEditorState() {
  // activeSlot, drawerSide, drawerOpen
  // 默认焦点行为
}

这种分离确保了编辑状态的安全性和界面的响应速度。抽屉的打开关闭是纯粹的 UI 交互，不需要触发复杂的持久化逻辑。这无异于废话了！不，其实很重要——界面状态和业务状态要明确区分，避免 UI 交互污染核心数据模型。

单抽屉生命周期

Section titled “单抽屉生命周期”

Soul Builder 采用单抽屉模式：同时只允许一个槽位抽屉打开。点击遮罩层、按 ESC 键或切换槽位都会自动关闭当前抽屉。这个设计简化了状态管理，也符合移动端抽屉交互的常见模式。

抽屉关闭不会清空当前编辑内容，用户切换回来时，上下文得以保留。这种”轻量级”的抽屉设计，避免了用户操作的中断感。毕竟谁愿意辛辛苦苦写的东西，因为不小心点错就全没了吗？

双语支持架构

Section titled “双语支持架构”

国际化是 Soul 平台的重要特性。系统文案完全支持双语切换，而用户草稿文本则永远不会因语言切换而被重写——因为草稿文本本身就是用户自由输入的内容，不涉及系统翻译。

官方灵感卡（Marketplace Soul）保持上游显示名称，但提供最佳努力的英文摘要。对于中文名称的 Soul，我们通过预定义的映射规则生成英文版本：

// 主角色英文名映射
const mainNameEnglishMap = {
  "雾港旅人": "Mistport Traveler",
  "夜航猎手": "Night Hunter",
  // ...
}


// 正交规则英文名映射
const ruleNameEnglishMap = {
  "简洁干练": "Concise & Professional",
  "啰嗦亲切": "Verbose & Friendly",
  // ...
}

这映射表看起来也挺简单的，可是要维护好它，也得花不少心思。毕竟有 50 组主角色和 10 组正交规则，乘起来就是 500 个组合，这数量说大不大，说小也不小。

后端目录生成

Section titled “后端目录生成”

Soul Catalog 的批量生成在后端完成，使用 C# 实现了 50 × 10 = 500 个组合的自动化创建：

foreach (var main in source.MainCatalogs)
{
    foreach (var orthogonal in source.OrthogonalCatalogs)
    {
        var catalogId = $"soul-{main.Index:00}-{orthogonal.Index:00}";
        var displayName = BuildNickname(main, orthogonal);
        var soulSnapshot = BuildSoulSnapshot(main, orthogonal);
        // 写入数据库...
    }
}

昵称生成算法将主角色名和表达规则名组合在一起，创造出富有想象力的 Agent 代号：

private static readonly string[] MainHandleRoots = [
    "雾港", "夜航", "零帧", "星渊", "霓虹", "断云", ...
];
private static readonly string[] OrthogonalHandleSuffixes = [
    "旅人", "猎手", "术师", "行者", "星使", ...
];
// 组合示例：雾港旅人、夜航猎手、零帧术师...

Soul 快照的拼装则按照固定的模板格式，将主角色核心、标志特征、表达规则核心和输出约束组合在一起：

private static string BuildSoulSnapshot(main, orthogonal) => string.Join('\n', [
    $"你的人设内核来自「{main.Name}」：{main.Core}",
    $"保持以下标志性语言特征：{main.Signature}",
    $"你的表达规则来自「{orthogonal.Name}」：{orthogonal.Core}",
    $"必须遵循这些输出约束：{orthogonal.Signature}"
]);

这模板拼装说起来也是无聊透顶的活儿，可是没有这些无聊的工作，哪来有趣的产品呢？

平台迁移策略

Section titled “平台迁移策略”

Soul 从主系统拆分到独立平台后，我们面临的一个重要挑战是如何处理已有用户数据。这问题说起来也挺常见的——拆分容易，迁移难。我们采取了三项保障措施：

向后兼容保障。已保存的 Hero SOUL 快照保持可见，历史快照即使失去 Marketplace 来源 ID 仍可预览。这意味着用户之前的所有配置都不会丢失，只是展示位置发生了变化。毕竟谁也不想辛辛苦苦的配置，说没就没了。

主系统接口弃用。站内 Marketplace API 返回 410 Gone 状态码，并附带迁移提示，引导用户访问 soul.hagicode.com。

Hero SOUL 表单改造。在 Hero Soul 编辑区域新增迁移提示区块，明确告知用户 Soul 平台已经独立，并提供一键跳转按钮：

HeroSoulForm.tsx
<div className="rounded-2xl border border-orange-200/70 bg-orange-50/80 p-4">
  <div>{t('hero.soul.migrationTitle')}</div>
  <p>{t('hero.soul.migrationDescription')}</p>
  <Button onClick={onOpenSoulPlatform}>
    {t('hero.soul.openSoulPlatformAction')}
  </Button>
</div>

实践要点总结

Section titled “实践要点总结”

回顾 Soul 平台的整个开发过程，有几点实践经验值得分享。这也算是过来人的一点心得，不是什么大道理，只是踩过的坑罢了。

本地优先的运行时假设。在设计依赖远端数据的特性时，始终假设网络可能不可用。本地快照作为基线，远端作为增强，这种思路让产品在任何网络条件下都能提供基本的可用性。毕竟这年头，网络这东西，说断就断，谁也说不准。

状态边界清晰划分。界面状态和业务状态要明确区分，避免 UI 交互污染核心数据模型。抽屉开关是纯粹的 UI 状态，不需要和草稿持久化混在一起。

国际化设计要趁早。如果你的产品有国际化需求，最好在数据模型设计阶段就考虑进去。localized 字段虽然增加了数据结构的复杂度，但后续维护多语言内容的成本会大大降低。

素材同步工作流要自动化。Soul 平台的本地素材来自主系统文档，当上游文档更新时，需要有机制同步到前端快照。我们设计了 npm run materials:sync 脚本自动化这个过程，确保素材始终和上游保持一致。

未来展望

Section titled “未来展望”

基于当前的架构设计，Soul 平台未来可以考虑以下发展方向。这也只是一些粗浅的想法，不一定对，权当抛砖引玉罢了。

社区共享生态。支持用户上传和分享自定义 Soul，增加评分、评论和推荐机制，让优秀的 Soul 配置能够被更多人发现和使用。毕竟独乐乐不如众乐乐。

多模态扩展。除了文字风格，还可以考虑支持语音风格配置、表情符号使用偏好、代码风格与格式化规则等维度。这事儿说起来挺美好，做起来可能就…

智能辅助。基于使用场景自动推荐 Soul，风格迁移与融合，甚至 A/B 测试不同 Soul 的实际效果。美又何必在乎天晴阴呢？试试就知道了。

跨平台同步。支持从其他 AI 平台导入人格配置，提供标准化的 Soul 导出格式，与主流 Agent 框架集成。

总结

Section titled “总结”

本文分享了 HagiCode Soul 平台从需求萌发到独立平台的完整演进过程。我们探讨了为什么需要 Soul 机制（解决 Agent 人格一致性问题），分析了技术架构的三个发展阶段（内嵌配置、站内 Marketplace、独立平台），深入讲解了核心的数据模型、状态管理、预览编译和国际化设计，并分享了平台迁移的实践经验。

Soul 的本质，是一个独立于业务逻辑的人格配置层。它让 AI Agent 的语言风格变得可定义、可复用、可分享。从技术角度看，这个设计并不复杂，但它解决的问题却是真实的、有广泛需求的。

如果你也在开发 AI Agent 产品，不妨思考一下你的人格配置方案是否足够灵活。Soul 平台的实践或许能给你一些启发。

此情可待成追忆，只是当时已惘然。或许有一天，你也会遇到类似的问题，到时候这篇文章能帮上一点忙，那也就够了。

参考资料

Section titled “参考资料”

如果你觉得这篇文章有帮助，欢迎来 GitHub 给个项目一颗 Star。公测已经开始了，欢迎安装体验。

版权说明

Section titled “版权说明”

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

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

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

Section titled “HagiCode 为什么选择 Hermes 作为综合 Agent 核心”

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

背景

Section titled “背景”

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

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

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

关于 HagiCode

Section titled “关于 HagiCode”

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

为什么 HagiCode 需要 Hermes

Section titled “为什么 HagiCode 需要 Hermes”

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

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

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

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

什么是 Hermes Agent

Section titled “什么是 Hermes Agent”

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

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

核心特性

Section titled “核心特性”

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

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

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

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

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

HagiCode 如何集成 Hermes

Section titled “HagiCode 如何集成 Hermes”

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

Provider 层抽象

Section titled “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 通信协议

Section titled “ACP 通信协议”

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

方法说明
initialize初始化连接，获取协议版本和客户端能力
authenticate处理认证，支持多种认证方法
session/new创建新会话，设置工作目录和 MCP 服务器
session/prompt发送提示并获取响应

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

配置管理

Section titled “配置管理”

通过 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 分布式架构

Section titled “Orleans 分布式架构”

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

  • HermesGrain：Orleans Grain 实现，处理会话执行
  • HermesPlatformConfiguration：平台特定配置
  • HermesAcpSessionAdapter：ACP 会话适配器
  • HermesConsole：专用的验证控制台

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

完整执行流程

Section titled “完整执行流程”

以下是 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;
            }
        }
    }
}

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

健康检查

Section titled “健康检查”

为了保证 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}'."
    };
}

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

实践中的注意事项

Section titled “实践中的注意事项”

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

认证方法配置

Section titled “认证方法配置”

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

MCP 服务器配置

Section titled “MCP 服务器配置”

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

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

这世道，防不胜防啊。

工作目录管理

Section titled “工作目录管理”

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

响应聚合处理

Section titled “响应聚合处理”

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

错误处理策略

Section titled “错误处理策略”

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

总结

Section titled “总结”

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

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

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

如果本文对你有帮助

Section titled “如果本文对你有帮助”

版权说明

Section titled “版权说明”

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