# HermesBuddy

**Repository Path**: ExtraCilantro/hermes-buddy

## Basic Information

- **Project Name**: HermesBuddy
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-28
- **Last Updated**: 2026-06-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hermes Buddy

HermesLink 移动客户端 — 连接 [Hermes Agent](https://hermes-agent.nousresearch.com) 服务器，在手机上管理会话、收发消息、审批工具调用。

## 特性

- **扫码 / Token 配网** — 扫描服务器端二维码或手动输入连接 Token 完成配对
- **会话管理** — 创建、切换、删除会话，支持历史消息回溯
- **Markdown 聊天** — 用户消息/助手回复气泡展示，助手回复支持 Markdown 渲染
- **工具审批** — 审批或拒绝助手发起的工具调用请求
- **Profile 切换** — 查看服务器上配置的 Agent Profile 及其能力
- **多平台** — Android / iOS / Web / Windows / Linux / macOS

## 快速开始

### 依赖

- [Flutter](https://flutter.dev) SDK `^3.5.0`
- 一个运行中的 [Hermes Agent](https://hermes-agent.nousresearch.com) 实例（需启用 Hermes Link）

### 构建

```bash
# 克隆仓库
git clone https://gitee.com/ExtraCilantro/hermes-buddy.git
cd hermes-buddy

# 安装依赖
flutter pub get

# 运行（指定平台）
flutter run -d chrome      # Web
flutter run -d android     # Android（需连接设备或模拟器）
flutter run -d ios         # iOS（需 macOS + Xcode）
```

### 打包

```bash
flutter build apk          # Android APK
flutter build ios          # iOS IPA（需 macOS + Xcode）
flutter build web          # Web 静态文件
```

## 使用流程

1. 在 Hermes Agent 服务器上执行 `hermes link` 启动 Hermes Link 服务
2. 打开 App，输入服务器 URL（如 `http://192.168.1.100:8080`）
3. 扫描服务器端显示的二维码，或手动输入连接 Token
4. 配对成功后自动进入会话列表页，即可开始聊天

## 项目结构

```
lib/
├── main.dart                    # 入口，路由配置
├── models/
│   ├── conversation.dart        # 会话数据模型
│   ├── message.dart             # 消息 & 附件模型
│   └── profile.dart             # Profile / Capabilities / Permissions
├── providers/
│   └── hermes_provider.dart     # 状态管理（ChangeNotifier + Provider）
├── screens/
│   ├── setup_screen.dart        # 服务器连接 & 配网（扫码 / Token）
│   ├── home_screen.dart         # 会话列表
│   ├── chat_screen.dart         # 聊天界面
│   └── settings_screen.dart     # 设置页
└── services/
    ├── hermes_link_service.dart # HermesLink REST API 客户端
    └── storage_service.dart     # 本地持久化（SharedPreferences）
```

## API 说明

App 通过 REST API 与 HermesLink 服务端通信。主要端点：

| 功能 | 端点 |
|---|---|
| 获取服务器信息 | `GET /api/v1/bootstrap` |
| 配对 | `POST /api/v1/pairing/claim` / `POST /api/v1/auth/device-session` |
| 会话 CRUD | `GET/POST/DELETE /api/v1/conversations` |
| 消息 | `GET/POST /api/v1/conversations/{id}/messages` |
| 工单审批 | `POST .../approvals/{id}/approve` / `POST .../deny` |
| Profiles | `GET /api/v1/profiles` / `GET /api/v1/profiles/catalog` |
| 模型列表 | `GET /api/v1/models` |

## 相关项目

- [Hermes Agent](https://github.com/nousresearch/hermes) — 开源 AI Agent 框架
- [Hermes Link](https://hermes-agent.nousresearch.com/docs/link) — 手机 ↔ 服务端连接协议

## License

MIT