@bitseek/hermes-webui 0.1.0-beta.0

package/README.md

@@ -0,0 +1,213 @@
+# Bitseek Hermes WebUI
+
+`@bitseek/hermes-webui` 用来在本机启动和管理 Bitseek Hermes WebUI。
+
+它是一个轻量级 npm 包装器，负责进程生命周期、健康检查、日志和运行时状态。
+WebUI 本体来自 vendored `agent-frontend-shell` 运行时。
+
+## 快速开始
+
+全局安装：
+
+```bash
+npm install -g @bitseek/hermes-webui
+hermes-webui start --port 8787 --open
+```
+
+不全局安装，直接运行：
+
+```bash
+npx @bitseek/hermes-webui start --port 8787 --open
+```
+
+启动成功后访问：
+
+```text
+http://localhost:8787
+```
+
+如果 `8787` 端口已被占用，可以换一个端口：
+
+```bash
+hermes-webui start --port 8788 --open
+```
+
+## 使用前提
+
+- Node.js 20 到 24。
+- 本机需要可用的 Python 3。
+- 如果 WebUI 要调用 Hermes Agent，需要准备 Hermes Agent checkout，并确保其中有
+  `run_agent.py`。
+
+默认情况下，包装器会尝试从以下位置查找 Hermes Agent：
+
+```text
+$HERMES_HOME/hermes-agent
+../hermes-agent
+```
+
+也可以显式指定：
+
+```bash
+export HERMES_WEBUI_AGENT_DIR=/path/to/hermes-agent
+hermes-webui start --port 8787 --open
+```
+
+## 常用命令
+
+```bash
+hermes-webui start --port 8787 --open
+hermes-webui status --port 8787
+hermes-webui logs --lines 100
+hermes-webui logs --follow
+hermes-webui restart --port 8787
+hermes-webui stop
+hermes-webui version
+```
+
+前台模式适合开发或调试：
+
+```bash
+hermes-webui start --foreground --port 8787
+```
+
+`doctor` 是诊断命令，不是启动前的必需步骤。首次安装后或启动失败时可以运行：
+
+```bash
+hermes-webui doctor
+```
+
+## 首次启动会做什么
+
+第一次运行 `hermes-webui start` 时，包装器会：
+
+- 创建运行时状态目录。
+- 创建并管理 Python venv。
+- 按 vendored WebUI 的 `requirements.txt` 安装 Python 依赖。
+- 启动 vendored `agent-frontend-shell/server.py`。
+- 等待 `/health` 健康检查通过。
+- 把 PID、日志路径和运行时信息写入状态目录。
+
+## 状态和日志
+
+默认情况下，运行时状态会写入：
+
+```text
+$HERMES_HOME/webui
+```
+
+重要文件：
+
+```text
+server.pid
+server.log
+runtime.json
+venv/
+```
+
+查看状态：
+
+```bash
+hermes-webui status --port 8787
+```
+
+查看日志：
+
+```bash
+hermes-webui logs --lines 200
+hermes-webui logs --follow
+```
+
+## 环境变量
+
+```text
+HERMES_HOME              默认 ~/.hermes
+HERMES_WEBUI_STATE_DIR   默认 $HERMES_HOME/webui
+HERMES_WEBUI_PYTHON      使用已有 Python 解释器
+HERMES_WEBUI_VENV_DIR    默认 $HERMES_WEBUI_STATE_DIR/venv
+HERMES_WEBUI_AGENT_DIR   Hermes Agent checkout 路径
+HERMES_WEBUI_HOST        默认 127.0.0.1
+HERMES_WEBUI_PORT        默认 8787
+```
+
+示例：
+
+```bash
+export HERMES_HOME="$HOME/.hermes"
+export HERMES_WEBUI_AGENT_DIR="$HERMES_HOME/hermes-agent"
+hermes-webui start --port 8787 --open
+```
+
+如果不想使用包装器管理的 venv，可以指定已有 Python：
+
+```bash
+export HERMES_WEBUI_PYTHON=/usr/bin/python3
+hermes-webui start --port 8787 --open
+```
+
+## 排查问题
+
+先运行：
+
+```bash
+hermes-webui doctor
+```
+
+常见问题：
+
+- `Port 8787 is already occupied`：端口已被其他进程占用，换端口启动。
+- `Python 3 is required but was not found in PATH`：安装 Python 3，或设置
+  `HERMES_WEBUI_PYTHON`。
+- `Hermes Agent dir: not found`：设置 `HERMES_WEBUI_AGENT_DIR` 指向包含
+  `run_agent.py` 的 Hermes Agent 目录。
+- `Vendored agent-frontend-shell runtime is missing`：发布包缺少 vendored
+  运行时，需要维护者重新同步并发布包。
+
+## 维护者说明
+
+打包的 WebUI 运行时来自：
+
+```text
+repo: adv-org/agent-frontend-shell
+branch: dev-zkp
+source checkout: /home/boj/hermes/agent-frontend-shell
+```
+
+该包装器不会把 Python + 原生 JavaScript WebUI 重写成 Node 应用，只负责用 npm
+包形式分发和启动 vendored 运行时。
+
+更新 vendored 运行时：
+
+```bash
+npm run sync:vendor
+```
+
+发布前检查：
+
+```bash
+npm run check
+npm pack --dry-run
+```
+
+确认 `package.json` 的 `files` 包含：
+
+```text
+bin/
+scripts/
+templates/
+vendor/agent-frontend-shell/
+README.md
+```
+
+发布：
+
+```bash
+npm publish --access public
+```
+
+发布后验证：
+
+```bash
+npm view @bitseek/hermes-webui version
+npx @bitseek/hermes-webui doctor
+```