From cc807484fc462659502ab1a0da9367bcf5ae712a Mon Sep 17 00:00:00 2001 From: hzhang Date: Sat, 16 May 2026 17:50:01 +0100 Subject: [PATCH] =?UTF-8?q?docs:=20refresh=20README=20=E2=80=94=20accuracy?= =?UTF-8?q?=20pass=20+=20HarborForge=20platform=20context?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Verified against current code; fixed stale/inaccurate sections and documented previously-undocumented features/flags/endpoints. Added a "Part of the HarborForge platform" reference and role/port. Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 192 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 120 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index 27fc914..3fc7b77 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,107 @@ # HarborForge OpenClaw Plugin -OpenClaw 插件：向 HarborForge Monitor 暴露 OpenClaw 侧元数据，并提供可选的本地桥接能力；安装时也可顺带安装 `hf` CLI。 +OpenClaw plugin that exposes OpenClaw-side metadata to the HarborForge Monitor, provides an optional local Monitor bridge, drives the HarborForge Calendar scheduler, and can optionally install the `hf` CLI. -## 当前状态 +Part of the [HarborForge](../README.md) platform. -- 插件注册名：`harbor-forge` -- 旧 sidecar `server/` 架构已移除 -- 监控桥接走本地 `monitor_port` -- 安装脚本支持 `--install-cli` -- `skills/hf/` 仅在 `--install-cli` 时一并安装 +- Role: OpenClaw integration layer for HarborForge (registered plugin id: `harbor-forge`). +- Talks to the HarborForge backend (`backendUrl`, default `https://monitor.hangman-lab.top`) for Calendar APIs. +- Talks to a local HarborForge.Monitor bridge over `127.0.0.1:` (no fixed default; commonly `9100`). -## 项目结构 +## Current State + +- Plugin registration id: `harbor-forge` (was `harborforge-monitor`) +- Plugin version: `0.2.0` (package manifests); telemetry reports `pluginVersion` `0.3.1` +- Legacy sidecar `server/` architecture removed — telemetry is served directly by the plugin +- Monitor bridge runs over the local `monitor_port` +- Calendar scheduler integration (PLG-CAL-001 / 002 / 004) +- Installer supports `--install-cli` and an optional managed Monitor (`--install-monitor`) +- `skills/hf/` is installed only with `--install-cli` + +## Project Structure ```text HarborForge.OpenclawPlugin/ ├── package.json ├── README.md +├── docs/ # design notes (calendar, monitor connector) ├── plugin/ -│ ├── openclaw.plugin.json -│ ├── index.ts +│ ├── openclaw.plugin.json # plugin manifest + config schema +│ ├── index.ts # plugin entry, tool registration +│ ├── tsconfig.json │ ├── core/ -│ │ ├── config.ts -│ │ ├── managed-monitor.ts -│ │ └── monitor-bridge.ts +│ │ ├── config.ts # config defaults / resolution +│ │ ├── managed-monitor.ts # optionally spawn HarborForge.Monitor +│ │ ├── monitor-bridge.ts # client for the Monitor bridge +│ │ └── openclaw-agents.ts # enumerate OpenClaw agents +│ ├── calendar/ # Calendar scheduler + bridge +│ │ ├── index.ts +│ │ ├── scheduler.ts +│ │ ├── calendar-bridge.ts +│ │ └── types.ts │ ├── hooks/ │ │ ├── gateway-start.ts │ │ └── gateway-stop.ts │ └── package.json ├── skills/ │ └── hf/ -│ └── SKILL.md +│ └── SKILL.md # installed only with --install-cli └── scripts/ └── install.mjs ``` -## 安装 +## Installation -### 普通安装 +### Standard Install ```bash node scripts/install.mjs ``` -这会： -- 构建并安装 OpenClaw 插件 -- 复制常规 skills -- **不会**安装 `hf` 二进制 -- **不会**复制 `skills/hf/` +This will: +- Build and install the OpenClaw plugin +- Copy regular skills +- **Not** install the `hf` binary +- **Not** copy `skills/hf/` -### 安装插件 + `hf` CLI +### Plugin + `hf` CLI ```bash node scripts/install.mjs --install-cli ``` -这会额外： -- 构建 `HarborForge.Cli` -- 安装 `hf` 到 `~/.openclaw/bin/hf` -- `chmod +x ~/.openclaw/bin/hf` -- 复制 `skills/hf/` 到 OpenClaw profile skills 目录 +This additionally: +- Builds `HarborForge.Cli` (`go build ./cmd/hf`) +- Installs `hf` to `/bin/hf` (default `~/.openclaw/bin/hf`) and `chmod +x` +- Copies `skills/hf/` into the OpenClaw skills directory -### 常用选项 +### Common Options ```bash -# 仅构建 +# Build only (no install / config) node scripts/install.mjs --build-only -# 指定 OpenClaw profile +# Install only, skip dependency checks +node scripts/install.mjs --skip-check + +# Specify OpenClaw profile path (also honors OPENCLAW_PATH env) node scripts/install.mjs --openclaw-profile-path /custom/path/.openclaw -# 详细日志 +# Build and install a managed HarborForge.Monitor binary alongside the plugin +node scripts/install.mjs --install-monitor yes --monitor-branch main + +# Verbose logs node scripts/install.mjs --verbose -# 卸载 +# Uninstall (plugin, config entries, hf binary, managed monitor) node scripts/install.mjs --uninstall ``` -## 配置 +The installer also updates OpenClaw config (`plugins.load.paths`, `plugins.allow`, `plugins.entries.harbor-forge.enabled`) via `openclaw config`. -编辑 `~/.openclaw/openclaw.json`： +## Configuration + +Edit `~/.openclaw/openclaw.json`: ```json { @@ -94,7 +117,9 @@ node scripts/install.mjs --uninstall "monitor_port": 9100, "reportIntervalSec": 30, "httpFallbackIntervalSec": 60, - "logLevel": "info" + "logLevel": "info", + "calendarEnabled": true, + "calendarHeartbeatIntervalSec": 60 } } } @@ -102,51 +127,72 @@ node scripts/install.mjs --uninstall } ``` -然后重启： +Then restart: ```bash openclaw gateway restart ``` -## 配置项 +## Config Options -| 选项 | 类型 | 默认值 | 说明 | -|------|------|--------|------| -| `enabled` | boolean | `true` | 是否启用插件 | -| `backendUrl` | string | `https://monitor.hangman-lab.top` | HarborForge Monitor 后端地址 | -| `identifier` | string | 主机名 | 服务器标识符 | -| `apiKey` | string | 无 | HarborForge Monitor 生成的服务器 API Key | -| `monitor_port` | number | 无 | 本地桥接端口；插件通过 `127.0.0.1:` 与 HarborForge.Monitor 通信 | -| `reportIntervalSec` | number | `30` | 报告间隔（秒） | -| `httpFallbackIntervalSec` | number | `60` | HTTP 回退间隔（秒） | -| `logLevel` | string | `info` | 日志级别：`debug` / `info` / `warn` / `error` | +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `enabled` | boolean | `true` | Enable the plugin | +| `backendUrl` | string | `https://monitor.hangman-lab.top` | HarborForge backend base URL (Monitor + Calendar APIs) | +| `identifier` | string | hostname | Server / claw identifier | +| `apiKey` | string | (none) | Server API key from the HarborForge Monitor admin panel | +| `monitor_port` | number | (none) | Local bridge port; plugin talks to HarborForge.Monitor via `127.0.0.1:` | +| `reportIntervalSec` | number | `30` | Metadata push interval (seconds) | +| `httpFallbackIntervalSec` | number | `60` | HTTP heartbeat interval when WS unavailable | +| `logLevel` | string | `info` | Log level: `debug` / `info` / `warn` / `error` | +| `calendarEnabled` | boolean | `true` | Enable Calendar scheduler integration (PLG-CAL-001) | +| `calendarHeartbeatIntervalSec` | number | `60` | Calendar heartbeat interval (seconds) | +| `calendarApiKey` | string | (none) | API key for Calendar API auth; falls back to `apiKey` / `X-Agent-ID` | +| `managedMonitor` | string | (none) | Absolute path to a HarborForge.Monitor binary; if set, gateway start/stop hooks spawn/stop it | -## 本地桥接说明 +## Local Monitor Bridge -当插件配置了 `monitor_port`，并且 HarborForge.Monitor 也使用相同的 `MONITOR_PORT` 时： +When the plugin has `monitor_port` configured and HarborForge.Monitor uses the same `MONITOR_PORT`: -- Monitor 在 `127.0.0.1:` 提供本地桥接服务 -- 插件可探测 `GET /health` -- 插件工具 `harborforge_monitor_telemetry` 可读取 `GET /telemetry` -- 如果桥接端口未配置或不可达，插件仍可正常运行 +- Monitor serves a local bridge on `127.0.0.1:` +- The plugin probes `GET /health` +- The plugin tool `harborforge_monitor_telemetry` reads `GET /telemetry` +- The plugin pushes OpenClaw metadata (version, plugin version, agents) via `POST /openclaw` on the `reportIntervalSec` cadence, enriching Monitor heartbeats +- If the bridge port is unconfigured or unreachable, the plugin still works normally -也就是说，这条链路是**可选增强**，不是插件启动或 Monitor 心跳的前置条件。 +This link is an **optional enhancement**, not a precondition for the plugin to start or for Monitor heartbeats. -## 插件提供的信息 +## Managed Monitor -### OpenClaw 元数据 -- OpenClaw version -- plugin version -- 标识符 / 主机名 -- 时间戳 +If `managedMonitor` points to an installed HarborForge.Monitor binary, the `gateway_start` hook spawns it (passing `--backend-url`, `--identifier`, `--api-key`, `--monitor-port`, `--report-interval`, `--log-level` from the plugin config) and `gateway_stop` terminates it. Use `install.mjs --install-monitor yes` to build and wire this automatically. -### 系统快照 -- uptime -- memory total/free/used/usagePercent -- load avg1/avg5/avg15 -- platform +## Calendar Scheduler -## 开发 +When `calendarEnabled` is true, on gateway start the plugin starts a Calendar scheduler that heartbeats the backend (`/calendar/agent/heartbeat`, `/calendar/agent/status`, `/calendar/agent/notify`) to receive and run scheduled TimeSlots, waking/spawning agents via the OpenClaw `spawn` API (with a notification fallback). Scheduler state is persisted to a state file; gateway restarts can be requested by the backend (PLG-CAL-004). + +## Tools Provided + +| Tool | Description | +|------|-------------| +| `harborforge_status` | Plugin status, resolved config, Monitor bridge health, calendar status, telemetry snapshot | +| `harborforge_telemetry` | Current system telemetry snapshot from this host | +| `harborforge_monitor_telemetry` | Query the Monitor bridge for host hardware telemetry | +| `harborforge_calendar_status` | Calendar scheduler status and current slot | +| `harborforge_calendar_complete` | Complete the current calendar slot with actual duration | +| `harborforge_calendar_abort` | Abort the current calendar slot | +| `harborforge_calendar_pause` | Pause the current calendar slot | +| `harborforge_calendar_resume` | Resume the paused calendar slot | +| `harborforge_restart_status` | Check whether a gateway restart is pending | + +### Telemetry Snapshot Fields + +- `identifier`, `hostname`, `platform`, `timestamp` +- `uptime` +- `memory`: `total` / `free` / `used` / `usagePercent` +- `load`: `avg1` / `avg5` / `avg15` +- `openclaw`: `version` / `pluginVersion` + +## Development ```bash cd plugin @@ -154,14 +200,16 @@ npm install npm run build ``` -## 依赖 +The build runs `tsc` and emits `dist/` (`dist/index.js` is the plugin entry). + +## Dependencies - Node.js 18+ - OpenClaw Gateway -- Go 1.20+（仅 `--install-cli` 需要） +- Go 1.20+ (only for `--install-cli` / `--install-monitor`) -## 相关提示 +## Tips -- 安装 `hf` 后，建议把 `~/.openclaw/bin` 加到 `PATH` -- Agent 使用 `hf` 时，优先试 `hf --help-brief` -- 完整命令树看 `hf --help` +- After installing `hf`, add `~/.openclaw/bin` to your `PATH` +- When an agent uses `hf`, try `hf --help-brief` first +- For the full command tree, see `hf --help`