# BitSeek Claw WebUI

`@bitseek/hermes-webui` 用来在本机启动和管理 BitSeek Claw WebUI。

## 快速开始

全局安装：

```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`。

默认情况下，WebUI 会尝试从以下位置查找 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
```

`hermes-webui start` 默认是后台 daemon 模式；启动命令退出后，WebUI 仍会继续运行。
关闭终端窗口不会停止它。需要停止时运行：

```bash
hermes-webui stop
```

前台模式适合开发或调试：

```bash
hermes-webui start --foreground --port 8787
```

`doctor` 是诊断命令，不是启动前的必需步骤。首次安装后或启动失败时可以运行：

```bash
hermes-webui doctor
```

## 开机或登录自启动

如果希望 WebUI 在系统登录或开机后自动启动，可以安装为系统服务：

```bash
hermes-webui service install --port 8787
```

安装后会立即启动服务；如果只想安装自启动配置，不立刻启动：

```bash
hermes-webui service install --port 8787 --no-start
```

服务管理命令：

```bash
hermes-webui service status
hermes-webui service start
hermes-webui service stop
hermes-webui service restart
hermes-webui service uninstall
```

各平台使用的服务管理器：

- Linux: user systemd，unit 位于 `~/.config/systemd/user/bitseek-hermes-webui.service`。
- macOS: launchd，plist 位于 `~/Library/LaunchAgents/com.bitseek.hermes-webui.plist`。
- Windows: Task Scheduler，任务名 `BitSeekHermesWebUI`。

服务模式内部运行 `hermes-webui start --foreground`，由系统服务管理器负责守护和
自启动。普通的 `hermes-webui start` 仍适合手动后台启动。

## 首次启动会做什么

第一次运行 `hermes-webui start` 时，WebUI 会：

- 创建运行时状态目录。
- 创建并管理 Python venv。
- 安装 WebUI 所需的 Python 依赖。
- 检查当前 Python 是否能导入 Hermes Agent；如果不能，会把
  `HERMES_WEBUI_AGENT_DIR` 指向的 Hermes Agent 以 editable 模式安装到 WebUI
  venv。
- 默认启用 BitSeek 外观和扩展入口，包括 “AI 同事” 页面。
- 启动 BitSeek Claw WebUI 服务。
- 等待 `/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
```

BitSeek 扩展默认值：

```text
HERMES_WEBUI_EXTENSION_DIR                默认 ./extensions
HERMES_WEBUI_EXTENSION_STYLESHEET_URLS    默认 /extensions/themes/bitseek/index.css
HERMES_WEBUI_EXTENSION_SCRIPT_URLS        默认 /extensions/themes/bitseek/index.js,/extensions/index.js
HERMES_WEBUI_BOT_NAME                     默认 BitSeek Claw
```

这些默认值在 macOS、Linux、Windows 上都可用。显式设置同名环境变量可以覆盖
默认值。

示例：

```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 目录。
- `AIAgent importable: fail`：当前 WebUI Python 不能导入 Hermes Agent。运行
  `hermes-webui start` 会自动尝试修复；如果仍失败，请查看 `server.log` 和
  `pip install -e` 的错误输出。
- `systemctl --user is not available`：当前 Linux 会话没有可用的 user systemd。
  可以先运行 `hermes-webui start` 手动后台启动，或启用 linger 后重试：
  `sudo loginctl enable-linger $USER`。
- `WebUI runtime is missing`：发布包缺少必要文件，需要维护者重新打包并发布。

## 维护者说明

同步 WebUI 文件：

```bash
npm run sync:vendor
```

发布前检查：

```bash
npm run check
npm pack --dry-run
```

确认 `package.json` 的 `files` 包含：

```text
bin/
scripts/
templates/
vendor/
README.md
```

发布：

```bash
npm publish --access public
```

发布后验证：

```bash
npm view @bitseek/hermes-webui version
npx @bitseek/hermes-webui doctor
```
