hermes-web-ui 0.1.2 → 0.1.3

package/README.md

@@ -1,434 +1,143 @@
-# Hermes UI
+# Hermes Web UI
 
-Hermes Agent 的 Web 管理面板，用于对话交互和定时任务管理。
+Web dashboard for [Hermes Agent](https://github.com/EKKOLearnAI/hermes-agent) — chat interaction, session management, scheduled jobs, and log viewing.
 
-## 技术栈
+## Tech Stack
 
 - **Vue 3** — Composition API + `<script setup>`
 - **TypeScript**
-- **Vite** — 构建工具
-- **Naive UI** — 组件库
-- **Pinia** — 状态管理
-- **Vue Router** — 路由（Hash 模式）
-- **SCSS** — 样式预处理
-- **markdown-it** + **highlight.js** — Markdown 渲染与代码高亮
+- **Vite** — Build tool
+- **Naive UI** — Component library
+- **Pinia** — State management
+- **Vue Router** — Routing (Hash mode)
+- **Koa 2** — BFF server (API proxy, file upload, session management)
+- **SCSS** — Style preprocessor
+- **markdown-it** + **highlight.js** — Markdown rendering and code highlighting
 
-## 快速开始
-
-### 1. 配置 API Server
-
-编辑 `~/.hermes/config.yaml`，启用 API Server：
-
-```yaml
-platforms:
-  api_server:
-    enabled: true
-    host: "127.0.0.1"
-    port: 8642
-    key: ""
-    cors_origins: "*"
-```
-
-重启 Gateway 使配置生效：
-
-```bash
-hermes gateway restart
-```
-
-### 2. 安装并启动
+## Install and Run
 
 ```bash
-# 全局安装
 npm install -g hermes-web-ui
-
-# 启动 Web 面板（默认 http://localhost:8648）
 hermes-web-ui start
 ```
 
-### 开发模式
-
-```bash
-# 克隆项目后
-npm install
-npm run dev
-```
-
-## 项目结构
-
-```
-src/
-├── api/
-│   ├── client.ts              # HTTP 请求封装（fetch + Bearer Auth）
-│   ├── chat.ts                # 对话 API（startRun + SSE 事件流）
-│   ├── jobs.ts                # 定时任务 CRUD
-│   └── system.ts              # 健康检查、模型列表
-├── stores/
-│   ├── app.ts                 # 全局状态（连接状态、版本、模型）
-│   ├── chat.ts                # 对话状态（消息、会话、流式输出）
-│   └── jobs.ts                # 任务状态（列表、CRUD 操作）
-├── components/
-│   ├── layout/
-│   │   └── AppSidebar.vue     # 侧边栏导航
-│   ├── chat/
-│   │   ├── ChatPanel.vue      # 对话面板（会话列表 + 聊天区域）
-│   │   ├── MessageList.vue    # 消息列表（自动滚动、加载动画）
-│   │   ├── MessageItem.vue    # 单条消息（用户/AI/工具/系统）
-│   │   ├── ChatInput.vue      # 输入框（Ctrl+Enter 发送）
-│   │   └── MarkdownRenderer.vue # Markdown 渲染（代码高亮、复制）
-│   └── jobs/
-│       ├── JobsPanel.vue      # 任务面板
-│       ├── JobCard.vue        # 任务卡片
-│       └── JobFormModal.vue   # 创建/编辑任务弹窗
-├── views/
-│   ├── ChatView.vue           # 对话页
-│   └── JobsView.vue           # 任务页
-├── router/
-│   └── index.ts               # 路由配置
-├── styles/
-│   ├── variables.scss         # SCSS 设计变量
-│   ├── global.scss            # 全局样式
-│   └── theme.ts               # Naive UI 主题覆盖
-├── composables/
-│   └── useKeyboard.ts         # 键盘快捷键
-└── main.ts                    # 应用入口
-```
-
-## 功能特性
-
-### 对话（Chat）
-
-- 基于 `/v1/runs` + `/v1/runs/{id}/events` 的异步 Run + SSE 事件流
-- 实时流式输出，工具调用进度可视化
-- 多会话管理，会话历史持久化到 localStorage
-- Markdown 渲染，代码块语法高亮与一键复制
-
-### 定时任务（Jobs）
-
-- 任务列表查看（含暂停/禁用任务）
-- 创建、编辑、删除任务
-- 暂停/恢复任务
-- 立即触发任务执行
-- Cron 表达式快速预设
-
-### 其他
-
-- 连接状态实时检测（30s 轮询）
-- 纯黑白主题
-- 键盘快捷键支持
-
----
-
-## API 接口文档
-
-Base URL: `http://127.0.0.1:8642`
-
-### 认证
-
-除 `/health` 外，所有接口支持 Bearer Token 认证（如果服务端配置了 `key`）：
-
-```
-Authorization: Bearer <your-api-key>
-```
-
-未配置 key 时所有请求放行。
-
-### 通用错误格式
-
-```json
-{
-  "error": {
-    "message": "错误描述",
-    "type": "invalid_request_error",
-    "param": null,
-    "code": "invalid_api_key"
-  }
-}
-```
-
-| 状态码 | 说明 |
-|--------|------|
-| 200 | 成功 |
-| 400 | 请求参数错误 |
-| 401 | API Key 无效 |
-| 404 | 资源不存在 |
-| 413 | 请求体过大（上限 1MB） |
-| 429 | 并发超限（最大 10 个 Run） |
-| 500 | 服务器内部错误 |
-
----
-
-### 1. 健康检查
-
-**GET** `/health` 或 `/v1/health`
-
-无需认证。
-
-```json
-{"status": "ok", "platform": "hermes-agent"}
-```
-
----
-
-### 2. 模型列表
-
-**GET** `/v1/models`
-
-```json
-{
-  "object": "list",
-  "data": [
-    {
-      "id": "hermes-agent",
-      "object": "model",
-      "created": 1744348800,
-      "owned_by": "hermes"
-    }
-  ]
-}
-```
-
----
-
-### 3. Chat Completions（OpenAI 兼容）
-
-**POST** `/v1/chat/completions`
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| messages | array | Y | 消息数组，格式同 OpenAI |
-| stream | boolean | N | 是否流式返回，默认 false |
-| model | string | N | 模型名，默认 "hermes-agent" |
-
-可选 Header: `X-Hermes-Session-Id` 指定会话 ID。
-
-**stream=false 响应：**
-```json
-{
-  "id": "chatcmpl-xxxxx",
-  "object": "chat.completion",
-  "created": 1744348800,
-  "model": "hermes-agent",
-  "choices": [{"index": 0, "message": {"role": "assistant", "content": "回复内容"}, "finish_reason": "stop"}],
-  "usage": {"prompt_tokens": 100, "completion_tokens": 50, "total_tokens": 150}
-}
-```
-
-**stream=true 响应：** SSE 流（`Content-Type: text/event-stream`）
-```
-data: {"id":"chatcmpl-xxx","choices":[{"delta":{"content":"你"},"index":0}]}
-data: [DONE]
-```
-
----
-
-### 4. Responses（有状态链式对话）
-
-**POST** `/v1/responses`
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| input | string / array | Y | 用户输入 |
-| instructions | string | N | 系统指令 |
-| previous_response_id | string | N | 链式对话的上一次响应 ID |
-| conversation | string | N | 会话名称，自动链式到最新响应 |
-| conversation_history | array | N | 显式传入对话历史 |
-| store | boolean | N | 是否存储响应，默认 true |
-| truncation | string | N | 设为 "auto" 自动截断历史到 100 条 |
-| model | string | N | 模型名 |
-
-> `conversation` 和 `previous_response_id` 互斥。
-
-可选 Header: `Idempotency-Key` 幂等键。
-
-```json
-{
-  "id": "resp_xxx",
-  "object": "response",
-  "status": "completed",
-  "created_at": 1744348800,
-  "output": [{"type": "message", "role": "assistant", "content": "回复内容"}],
-  "usage": {"input_tokens": 100, "output_tokens": 50, "total_tokens": 150}
-}
-```
-
----
-
-### 5. 获取 / 删除存储的响应
-
-**GET** `/v1/responses/{response_id}` — 获取存储的响应
-
-**DELETE** `/v1/responses/{response_id}` — 删除存储的响应
-
-```json
-{"id": "resp_xxx", "object": "response", "deleted": true}
-```
-
----
-
-### 6. 启动异步 Run
-
-**POST** `/v1/runs`
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| input | string / array | Y | 用户输入 |
-| instructions | string | N | 系统指令 |
-| previous_response_id | string | N | 链式对话 ID |
-| conversation_history | array | N | 对话历史 |
-| session_id | string | N | 会话 ID，默认使用 run_id |
-
-```json
-{"run_id": "run_xxx", "status": "started"}
-```
-
----
-
-### 7. SSE 事件流
-
-**GET** `/v1/runs/{run_id}/events`
-
-`Content-Type: text/event-stream`
-
-**事件类型：**
-
-| 事件 | 说明 |
-|------|------|
-| `run.started` | Run 开始 |
-| `message.delta` | 消息内容片段（字段 `delta`） |
-| `tool.started` | 工具调用开始（字段 `tool`、`preview`） |
-| `tool.completed` | 工具调用完成（字段 `tool`、`duration`） |
-| `run.completed` | Run 完成（字段 `output`、`usage`） |
-| `run.failed` | Run 失败（字段 `error`） |
-
-示例：
-```
-data: {"event":"message.delta","run_id":"run_xxx","delta":"你好","timestamp":...}
-data: {"event":"tool.started","run_id":"run_xxx","tool":"browser_navigate","preview":"https://...","timestamp":...}
-data: {"event":"tool.completed","run_id":"run_xxx","tool":"browser_navigate","duration":3.8,"timestamp":...}
-data: {"event":"run.completed","run_id":"run_xxx","output":"完整回复","usage":{"input_tokens":100,"output_tokens":50,"total_tokens":150}}
-```
-
----
-
-### 8. 定时任务
-
-#### 列出任务
-
-**GET** `/api/jobs?include_disabled=true`
-
-```json
-{
-  "jobs": [
-    {
-      "job_id": "61a5eb0baeb9",
-      "name": "任务名",
-      "schedule": "0 9 * * *",
-      "repeat": "forever",
-      "deliver": "origin",
-      "next_run_at": "2026-04-12T09:00:00+08:00",
-      "last_run_at": "2026-04-11T09:04:25+08:00",
-      "last_status": "ok",
-      "enabled": true,
-      "state": "scheduled",
-      "prompt_preview": "...",
-      "skills": []
-    }
-  ]
-}
-```
-
-#### 创建任务
-
-**POST** `/api/jobs`
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| name | string | Y | 任务名称（最大 200 字符） |
-| schedule | string | Y | Cron 表达式 |
-| prompt | string | N | 任务 prompt |
-| deliver | string | N | 投递目标（origin / local / telegram / discord） |
-| skills | array | N | skill 名称数组 |
-| repeat | integer | N | 重复次数，不传表示永久 |
-
-响应包裹在 `{"job": {...}}` 中。
+Open http://localhost:8648
 
-#### 查看任务详情
+### CLI Commands
 
-**GET** `/api/jobs/{job_id}`
+| Command | Description |
+|---------|-------------|
+| `hermes-web-ui start` | Start in background (daemon mode) |
+| `hermes-web-ui start --port 9000` | Start on custom port |
+| `hermes-web-ui stop` | Stop background process |
+| `hermes-web-ui restart` | Restart background process |
+| `hermes-web-ui status` | Check if running |
+| `hermes-web-ui` | Run in foreground (for debugging) |
 
-#### 更新任务
+### Auto Configuration
 
-**PATCH** `/api/jobs/{job_id}`
+On startup, the BFF server automatically checks `~/.hermes/config.yaml` and ensures `platforms.api_server.enabled` is set to `true`. If modified, it backs up the original to `config.yaml.bak` and restarts the gateway.
 
-可更新字段：`name`、`schedule`、`prompt`、`deliver`、`skills`、`repeat`、`enabled`
-
-#### 删除任务
-
-**DELETE** `/api/jobs/{job_id}`
-
-```json
-{"ok": true}
-```
-
-#### 暂停任务
-
-**POST** `/api/jobs/{job_id}/pause`
-
-```json
-{"job": {"job_id": "xxx", "enabled": false, "state": "paused", ...}}
-```
+## Development
 
-#### 恢复任务
-
-**POST** `/api/jobs/{job_id}/resume`
-
-```json
-{"job": {"job_id": "xxx", "enabled": true, "state": "scheduled", ...}}
-```
-
-#### 立即触发任务
-
-**POST** `/api/jobs/{job_id}/run`
-
-```json
-{"job": {"job_id": "xxx", "state": "scheduled", ...}}
+```bash
+git clone https://github.com/EKKOLearnAI/hermes-web-ui.git
+cd hermes-web-ui
+npm install
+npm run dev
 ```
 
----
+This starts:
+- Frontend: http://localhost:5173
+- BFF Server: http://localhost:8648 (proxies to Hermes on 8642)
 
-## 快速测试
+### Build
 
 ```bash
-# 健康检查
-curl http://127.0.0.1:8642/health
-
-# 模型列表
-curl http://127.0.0.1:8642/v1/models
-
-# Chat Completions
-curl -X POST http://127.0.0.1:8642/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{"messages":[{"role":"user","content":"你好"}]}'
+npm run build
+```
+
+Outputs to `dist/` (frontend + compiled BFF server).
+
+## Project Structure
+
+```
+hermes-web-ui/
+├── bin/
+│   └── hermes-web-ui.mjs         # CLI entry (start/stop/restart/status)
+├── server/src/
+│   ├── index.ts                   # BFF entry (Koa app bootstrap)
+│   ├── config.ts                  # Configuration (port, upstream, etc.)
+│   ├── routes/
+│   │   ├── proxy.ts               # API proxy to Hermes (/api/*, /v1/*)
+│   │   ├── upload.ts              # File upload (POST /upload)
+│   │   ├── sessions.ts            # Session management via Hermes CLI
+│   │   ├── webhook.ts             # Webhook receiver
+│   │   └── logs.ts                # Log file listing and reading
+│   └── services/
+│       └── hermes-cli.ts          # Hermes CLI wrapper (sessions, logs, version)
+├── src/
+│   ├── api/                       # Frontend API layer
+│   ├── stores/                    # Pinia state management
+│   ├── components/
+│   │   ├── layout/AppSidebar.vue  # Sidebar navigation
+│   │   ├── chat/                  # Chat components
+│   │   └── jobs/                  # Job components
+│   ├── views/
+│   │   ├── ChatView.vue           # Chat page
+│   │   ├── JobsView.vue           # Jobs page
+│   │   └── LogsView.vue           # Logs page
+│   └── router/index.ts            # Router configuration
+└── dist/                          # Build output (published to npm)
+    ├── server/index.js            # Compiled BFF
+    ├── index.html                 # Frontend entry
+    └── assets/                    # Frontend static assets
+```
+
+## Features
+
+### Chat
+- Async Run + SSE event streaming via BFF proxy
+- Session management via Hermes CLI
+- Multi-session switching with message history
+- Markdown rendering with syntax highlighting and code copy
+- File upload support (saved to temp, path passed to API)
+
+### Scheduled Jobs
+- Job list view (including paused/disabled jobs)
+- Create, edit, pause, resume, and delete jobs
+- Trigger immediate job execution
+- Cron expression quick presets
+
+### Logs
+- View Hermes agent/gateway/error logs
+- Filter by log level, log file, and search keyword
+- Structured log parsing with HTTP access log highlighting
+
+### Other
+- Real-time connection status monitoring
+- Hermes version display in sidebar
+- Auto config check on startup
+- Minimalist dark theme
+
+## Architecture
+
+```
+Browser → BFF (Koa, :8648) → Hermes API (:8642)
+                ↓
+           Hermes CLI (sessions, logs, version)
+```
+
+The BFF layer handles:
+- API proxy to Hermes (with header forwarding)
+- SSE streaming passthrough
+- File upload to temp directory
+- Session CRUD via Hermes CLI
+- Log file reading and parsing
+- Static file serving (SPA fallback)
 
-# 启动异步 Run
-curl -X POST http://127.0.0.1:8642/v1/runs \
-  -H "Content-Type: application/json" \
-  -d '{"input":"你好"}'
-
-# 监听 Run 事件流
-curl http://127.0.0.1:8642/v1/runs/{run_id}/events
-
-# 列出任务（含已暂停）
-curl "http://127.0.0.1:8642/api/jobs?include_disabled=true"
+---
 
-# 创建任务
-curl -X POST http://127.0.0.1:8642/api/jobs \
-  -H "Content-Type: application/json" \
-  -d '{"name":"测试任务","schedule":"0 9 * * *","prompt":"执行测试"}'
+## License
 
-# 暂停 / 恢复 / 触发 / 删除
-curl -X POST http://127.0.0.1:8642/api/jobs/{job_id}/pause
-curl -X POST http://127.0.0.1:8642/api/jobs/{job_id}/resume
-curl -X POST http://127.0.0.1:8642/api/jobs/{job_id}/run
-curl -X DELETE http://127.0.0.1:8642/api/jobs/{job_id}
-```
+[MIT](./LICENSE)