# Hermes Agent Sidebar

**Repository Path**: bianlinge/hermes-agent-sidebar

## Basic Information

- **Project Name**: Hermes Agent Sidebar
- **Description**: Hermes Agent 侧边栏
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-11
- **Last Updated**: 2026-04-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Hermes Agent 侧边栏 - Chrome 扩展

为 Hermes Agent API Server 提供美观的 Chrome 侧边栏界面。

## 功能特性

### 核心功能
- **深色/浅色主题** - 现代护眼设计，支持一键切换
- **流式响应** - 实时消息流，打字机效果
- **Markdown 渲染** - 代码块、表格、标题等
- **思考过程展示** - AI 思考过程以可折叠块形式显示

### 对话管理
- **多对话支持** - 创建、重命名、切换、删除对话
- **对话历史** - 消息跨会话持久化
- **自动命名** - 第一条消息成为对话标题
- **存储限制** - 自动保留最近 50 个对话，超出自动清理
- **导出功能** - 导出所有对话为 JSON 文件备份
- **清空功能** - 一键删除所有对话（带确认防误删）

### 模型支持
- **模型选择器** - 从 `/v1/models` 获取可用模型下拉列表
- **手动输入** - 支持自定义模型名称
- **模型记忆** - 记住每个对话使用的模型

### 操作与工具
- **复制响应** - 一键复制 AI 回复内容
- **重新生成** - 重新发送上一条消息
- **Token 计数器** - 显示估算的 token 使用量
- **快捷操作** - 常用提示一键发送

### 错误处理
- **连接测试** - 保存前验证 API 凭据
- **重试按钮** - 快速重试失败的请求
- **错误提示** - 清晰的错误消息和详情
- **API Key 校验** - 空值、过短、错误（401/403）都有对应提示

## 环境要求

1. **Hermes Agent** 已安装并运行
2. **API Server** 已在 Hermes 中启用

## 安装配置

### 1. 启用 Hermes API Server

编辑 `~/.hermes/.env` 文件：

```bash
API_SERVER_ENABLED=true
API_SERVER_KEY=你的密钥
API_SERVER_CORS_ORIGINS=*
```

### 2. 启动 Hermes Gateway

```bash
hermes gateway
```

看到以下输出表示成功：
```
[API Server] API server listening on http://127.0.0.1:8642
```

### 3. 加载 Chrome 扩展

1. 打开 Chrome，访问 `chrome://extensions/`
2. 开启 **开发者模式**（右上角开关）
3. 点击 **加载已解压的扩展程序**
4. 选择 `hermes-sidebar` 文件夹

### 4. 配置扩展

1. 点击 Chrome 工具栏的扩展图标
2. 点击 **设置** (⚙️)
3. 填写 API Server URL（默认：`http://127.0.0.1:8642`）
4. 填写 API Key（第1步设置的密钥）
5. 点击 **测试连接** 验证
6. 点击 **保存**

### 5. 打开侧边栏

- 点击扩展图标，再点击 **打开侧边栏**
- 或使用快捷键：`Ctrl+Shift+H`（Mac：`Cmd+Shift+H`）

## 使用说明

### 与 Hermes 对话

在输入框输入消息，按 `Ctrl+Enter` 或点击发送按钮。

### 选择模型

点击顶部的模型下拉框，可查看从 `/v1/models` 获取的可用模型列表。

### 对话管理

- **新建** (➕)：开始新对话
- **历史** (📜)：查看和切换所有对话
- **重命名**：点击对话上的 ✏️
- **删除**：点击对话上的 🗑️
- **导出** (📤)：下载所有对话为 JSON 文件
- **清空** (🗑️)：一次删除所有对话

### 思考过程块

当 Hermes 思考时，会显示 💭 标记的可折叠块。点击标题可展开/折叠。

### 复制与重新生成

鼠标悬停在 AI 回复上可看到：
- 📋 **复制**：复制完整回复
- 🔄 **重新生成**：重新发送上一条消息

## 存储说明

- 对话存储在 Chrome 的 localStorage 中（浏览器专用）
- 最多保留 50 个对话（旧的自动删除）
- 使用 **导出** 功能可将对话备份到磁盘 JSON 文件
- 清除浏览器数据会删除所有对话记录

## 项目结构

```
hermes-sidebar/
├── manifest.json           # Chrome 扩展清单
├── background.js           # Service Worker（API 调用）
├── sidebar.html            # 侧边栏页面
├── sidebar.js              # 侧边栏逻辑
├── styles.css              # 深色/浅色主题样式
├── popup.html              # 扩展弹出页
├── popup.js                # 弹出页逻辑
├── marked.min.js           # Markdown 解析器（本地化）
├── github-markdown.min.css # GitHub Markdown 样式
├── icons/                  # 扩展图标
└── README.md               # 本文件
```

## 使用的 API 端点

| 端点 | 方法 | 用途 |
|------|------|------|
| `/health` | GET | 连接检查 |
| `/v1/models` | GET | 获取模型列表 |
| `/v1/chat/completions` | POST | 发送聊天消息（流式/非流式） |

## 故障排除

### "连接失败" 错误

1. 确认 Hermes Gateway 正在运行
2. 检查 `.env` 中 API Server 是否启用
3. 确认 `.env` 中 `API_SERVER_CORS_ORIGINS=*`
4. 在设置中使用 **测试连接** 诊断问题

### 401/403 认证错误

1. API Key 不正确或未授权
2. 检查 `~/.hermes/.env` 中的 `API_SERVER_KEY`
3. 确认扩展设置中的密钥与 `.env` 完全一致

### 下拉框没有模型

模型列表从 `/v1/models` 获取。如果不可用，会回退到手动输入的模型名称。请确认 Hermes 正在运行且可访问。

### 侧边栏打不开

1. 确认使用 Chrome 114+（sidePanel API 要求）
2. 检查 sidePanel 权限是否授予
3. 尝试刷新扩展页面

### 存储满了 / 对话太多

扩展自动限制 50 个对话。在自动删除前，使用 **导出** 功能备份对话。

## 快捷键

| 快捷键 | 功能 |
|--------|------|
| `Ctrl+Enter` | 发送消息 |
| `Ctrl+Shift+H` | 打开侧边栏 |

## 更新日志

### v1.1.0 (2026-04-12)
- 新增对话数量限制（最多 50 个）
- 新增导出对话为 JSON 功能
- 新增清空所有对话功能
- 优化 API Key 校验，提供具体错误提示
- 新增 401/403 认证错误检测

### v1.0.0 (2026-04-11)
- 初始版本，包含核心聊天功能
- 模型选择器和对话管理
- 深色/浅色主题支持

## 开源许可

MIT - 参见 Hermes Agent 项目