ym-hermes-desktop

本地 Hermes 接入点客户端（Node.js）。通过配置接入 Hermes Agent 的 API server（OpenAI 兼容接口），让你的 AI 工具/脚本调用 Hermes——Hermes 会自行执行它注册的工具（包括 MCP 工具）并返回结果。纯本地运行，零额外依赖（Node 22 内置 fetch）。

环境要求

• Node.js 20+
• Hermes Agent 已安装并启动 API server（本机已配置好，端口 8642）

安装

cd ~/Desktop/ym-hermes-desktop
npm install

配置

编辑 .env（已配好，密钥为本机 Hermes API server 的 Bearer token）：

HERMES_API_ENDPOINT=http://127.0.0.1:8642/v1
HERMES_API_KEY=你的 Bearer token
HERMES_MODEL=hermes-agent

• HERMES_API_ENDPOINT：Hermes API server 地址（默认本地 8642）
• HERMES_API_KEY：Hermes 的 API_SERVER_KEY（与 ~/.hermes/.env 一致）
• HERMES_MODEL：/v1/models 返回的模型 id（默认 hermes-agent）
• REPORT_URL：可选。任务完成上报接口（POST），配置后 dispatch 异步任务执行完自动上报

使用

npm run check      # 检查 Hermes 接入点是否可用
npm run models     # 查看模型列表
npm start          # 交互模式：直接输入问题，Hermes 执行并回答
npm run ask "帮我查一下今天杭州天气"   # 单次提问

交互模式内可用 /models、/check、/help、/exit，以及 /dispatch <任务名> <任务内容...>（立即返回「任务名 已下达」，后台执行完自动上报）。

异步下发（下发即确认，完成后自动上报）

hermes_chat MCP 工具与库函数 dispatch 均为异步模式：调用后立即返回「任务名 已下达」，任务后台执行；完成后自动上报到 REPORT_URL（raw JSON，固定上报体，见下）。

import { dispatch } from './src/hermes.js';

// 调用后立即返回确认，不等任务执行完
const ack = dispatch({
  taskName: '周报生成',
  content: '请总结今天的工作生成周报',
  reportUrl: 'http://127.0.0.1:3780/api/mcp/yunxiangji',   // 可选；不传则用 .env 的 REPORT_URL
});
// ack = { task_name: '周报生成', status: '已下达', received_at: '2026-09-13 06:12:28' }

上报 JSON（固定模板）：

{
  "title": "下发给hermes工作任务",
  "content": "下发HerMes的任务：周报生成已完成请前往查阅结果",
  "datetime": "2026-09-13 06:12:38"
}

• title：固定「下发给hermes工作任务」
• content：固定模板「下发HerMes的任务：{任务名}已完成请前往查阅结果」
• datetime：完成后 +10 秒，精确到年月日时分秒

配合独立上报工具 ym-hermes-task（注册进 Hermes 的 MCP 工具 report_task）可双保险：客户端上报 + Hermes 任务结束主动上报。

作为模块接入你自己的 AI 工具

src/hermes.js 可直接 import：

import { chat, listModels } from './src/hermes.js';

// 简单对话
const r = await chat({ messages: [{ role: 'user', content: '你好' }] });
console.log(r.choices[0].message.content);

// 透传 tools（function calling）给 Hermes 编排
const r2 = await chat({
  messages: [{ role: 'user', content: '搜索 AI 相关的文章' }],
  tools: [...],          // 可选：传给 Hermes 的工具定义
});

Hermes 内部已注册的 MCP 工具会自动通过 function calling 被调用，无需在本地重复接入。

发布到 npm 后（作为包安装使用）

npm i -g ym-hermes-desktop        # 全局安装
# 配置环境变量（包内不读取 .env，用系统环境变量）
export HERMES_API_ENDPOINT=http://127.0.0.1:8642/v1
export HERMES_API_KEY=你的 Bearer token
export HERMES_MODEL=hermes-agent
ym-hermes                          # 启动交互 CLI

或作为库：

import { chat } from 'ym-hermes-desktop';
const r = await chat({ messages: [{ role: 'user', content: '你好' }] });

说明：ym-hermes-desktop 的发布包只包含 src/ 与 README.md，不含任何本地配置文件与密钥。

作为 MCP server 使用（发布到 npm 的形态）

包内置 stdio MCP server，任何 MCP 客户端（Cursor / Claude Desktop / Cherry Studio 等）可连接：

{
  "mcpServers": {
    "ym-hermes": {
      "command": "npx",
      "args": ["-y", "ym-hermes-desktop"],
      "env": {
        "HERMES_API_ENDPOINT": "http://127.0.0.1:8642/v1",
        "HERMES_API_KEY": "你的 Bearer token",
        "HERMES_MODEL": "hermes-agent",
        "REPORT_URL":"Yo send apiurl"
      }
    }
  }
}

本地调试：

npm run mcp        # 以 MCP server 方式启动（stdio）

暴露的工具：

| 工具 | 参数 | 说明 | | --- | --- | --- | | hermes_chat | question（或 messages） | 让 Hermes 处理任务，Hermes 自动调度其注册的工具/MCP |

常见问题

• ✗ Hermes 接入点不可用：Hermes API server 未启动。检查 hermes gateway status，若 api_server 被拒绝，确认 ~/.hermes/.env 中 API_SERVER_KEY 是强密钥（≥32 字符，可用 openssl rand -hex 32 生成），然后 hermes gateway restart。
• HTTP 401：.env 的 HERMES_API_KEY 与 Hermes 实际 API_SERVER_KEY 不一致。
• 想接入更多 MCP 工具：在 Hermes 里注册即可（hermes mcp add 或配置 ~/.hermes/config.yaml 的 mcp_servers），无需改本工具。