# hermes-go

**Repository Path**: hellodc/hermes-go

## Basic Information

- **Project Name**: hermes-go
- **Description**: Hermes Agent 的 Go 语言实现，基于 [hermes-agent](https://github.com/NousResearch/hermes-agent) (Python) 重写。零外部依赖，纯 Go 标准库。
- **Primary Language**: Go
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-24
- **Last Updated**: 2026-06-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hermes Agent (Go)

Hermes Agent 的 Go 语言实现，基于 [hermes-agent](https://github.com/NousResearch/hermes-agent) (Python) 重写。零外部依赖，纯 Go 标准库。

## 快速开始

### 环境要求

- Go 1.26+
- DeepSeek API Key（或其他 OpenAI 兼容 API）

### 编译

```bash
cd agent
go build -o hermes-go.exe .
```

### 配置 API Key

```powershell
$env:DEEPSEEK_APIKEY = "sk-your-api-key"
```

或设置系统环境变量 `DEEPSEEK_APIKEY`。

### 运行

```bash
.\hermes-go.exe
```

```
Hermes Agent (Go) - AI 编程助手
模型: deepseek-v4-flash | 供应商: deepseek
API: https://api.deepseek.com (已配置密钥)
输入消息开始对话，输入 /exit 退出

> 你好，介绍一下Go语言
```

### 命令行参数

| 参数 | 默认值 | 说明 |
|------|--------|------|
| `--model` | `deepseek-v4-flash` | 模型名称 |
| `--provider` | `deepseek` | LLM 供应商 |
| `--base-url` | `https://api.deepseek.com` | API 基础地址 |
| `--max-tokens` | `64000` | 最大输出 token 数 |
| `--temperature` | `0.0` | 温度参数 |
| `--max-iterations` | `25` | 最大迭代次数 |
| `--system-prompt` | 内置默认 | 自定义系统提示词 |

```bash
# 使用 OpenAI
.\hermes-go.exe --provider openai --base-url https://api.openai.com --model gpt-4o
```

## 使用指南

### 交互式对话

启动后进入交互模式，直接输入消息开始对话：

```
> 用Go写一个HTTP服务器
```

**控制命令：**

| 输入 | 功能 |
|------|------|
| `/exit` 或 `/quit` | 退出程序 |
| `Ctrl+C` | 优雅退出 |
| 空行 | 跳过 |

### 管道输入（非交互模式）

通过管道传入消息，适合脚本化调用：

**单条消息：**

```powershell
"解释一下goroutine" | .\hermes-go.exe
```

**多条消息（多轮对话）：**

```powershell
@"
My name is Bob.
What is my name?
"@ | .\hermes-go.exe
```

每行文本作为一个独立对话回合，历史消息自动累积。

### 切换模型和供应商

**DeepSeek（默认）：**

```powershell
.\hermes-go.exe --model deepseek-v4-flash
```

**OpenAI：**

```powershell
$env:OPENAI_API_KEY = "sk-..."
.\hermes-go.exe --provider openai --base-url https://api.openai.com --model gpt-4o
```

**任何 OpenAI 兼容 API：**

```powershell
.\hermes-go.exe --base-url https://your-api.com --model your-model --provider openai
```

**自定义系统提示词：**

```powershell
.\hermes-go.exe --system-prompt "你是一个精通Go语言的专家，回答简洁。"
```

### 让 Agent 使用工具

Agent 注册了文件操作工具，LLM 会自动判断何时调用。以下是一些典型用法：

**读取文件：**

```
> 读取 go.mod 文件，告诉我模块名是什么
```

Agent 会自动调用 `read_file` 工具，读取文件后将结果返回。

**写入文件：**

```
> 创建一个 test/hello.go 文件，内容是用 fmt.Println 输出 Hello World
```

Agent 会依次调用 `create_directory` 和 `write_file` 工具。

**跨盘操作：**

```
> 列出 E:\ 目录下的所有文件，然后创建一个 E:\notes.txt 写入当前日期
```

工具支持绝对路径，可跨盘符操作。

**批量任务：**

```
> 查看当前目录所有 .go 文件，在每个文件开头添加版权注释
```

Agent 会先用 `list_directory` 列出文件，再用 `read_file` + `write_file` 逐个处理。

### 开发测试

**编译运行：**

```bash
cd agent
go build -o hermes-go.exe .
.\hermes-go.exe
```

**代码检查：**

```bash
go vet ./...
go fmt ./...
```

**运行测试：**

```bash
go test ./...
```

**跨平台编译：**

```bash
# Linux
GOOS=linux GOARCH=amd64 go build -o hermes-go .

# macOS
GOOS=darwin GOARCH=amd64 go build -o hermes-go .
```

## 项目结构

```
hermes-go/
├── agent/                  # Go 源码
│   ├── main.go             # CLI 入口
│   ├── go.mod              # 模块定义（零外部依赖）
│   ├── adapters/           # LLM 供应商适配器
│   ├── auth/               # 凭据管理
│   ├── core/               # 核心引擎（对话循环、记忆、压缩、护栏）
│   ├── infra/              # 基础设施（重试、错误、安全）
│   ├── lsp/                # LSP 协议支持
│   ├── presentation/       # 终端 UI 显示
│   ├── providers/          # 服务提供者接口
│   ├── skills/             # 技能系统
│   ├── tools/              # 文件操作工具
│   └── transports/         # API 传输层（Anthropic/OpenAI/Gemini/Codex/Bedrock）
└── agent copy/             # 原始 Python 代码参考
```

## 内置工具

当前已实现文件操作工具，LLM 可自动调用：

| 工具 | 说明 |
|------|------|
| `read_file` | 读取文本文件，支持行号和分页 |
| `write_file` | 写入文件，自动创建父目录 |
| `list_directory` | 列出目录内容 |
| `create_directory` | 创建目录（递归） |
| `delete_path` | 删除文件或目录树 |

## 支持供应商

- **DeepSeek** — OpenAI 兼容，通过 ChatCompletionsTransport
- **Anthropic** — 通过 AnthropicTransport（需配置 API Key）
- **OpenAI** — 通过 ChatCompletionsTransport
- **Gemini / Bedrock / Codex** — 传输层已实现，待集成

## 架构

```
用户输入 → CLI 交互循环
  → Agent.Run()
    → ConversationLoop.RunTurn()
      → 护栏检查 → 预算检查
      → callLLM() → HTTP POST → Transport 规范化
      → 工具执行（如有 tool_calls）
      → ContinueTurn() → 最终回复
```

- **ProviderTransport 接口**: 统一的消息/工具/响应归一化层
- **ConversationLoop**: 多轮对话管理，消息历史、预算、轨迹记录
- **ToolRegistry**: 工具注册与执行，支持顺序/并发调用
- **GuardrailController**: 内容安全检查
- **MemoryManager**: 持久化记忆管理

## 与 Python 版对比

| | Python | Go |
|------|--------|-----|
| 依赖 | 125+ Python 文件，大量三方库 | 120 Go 文件，零外部依赖 |
| 编译 | 运行时解释 | 编译为单文件二进制 |
| 启动 | ~1s | 即时 |
| 内存 | ~200MB+ | ~10MB |
| 工具 | 40+ 工具 | 5 个基础文件工具 |
| 消息平台 | Telegram/Discord/Slack 等 | CLI only |

## License

MIT