Compare commits
4 Commits
917cb344cf
...
_main
| Author | SHA1 | Date | |
|---|---|---|---|
| a003416e56 | |||
| 9ba591795b | |||
| c9f61419cb | |||
| cc807484fc |
192
README.md
192
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:<monitor_port>` (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 `<openclaw>/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:<monitor_port>` 与 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:<monitor_port>` |
|
||||
| `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:<MONITOR_PORT>` 提供本地桥接服务
|
||||
- 插件可探测 `GET /health`
|
||||
- 插件工具 `harborforge_monitor_telemetry` 可读取 `GET /telemetry`
|
||||
- 如果桥接端口未配置或不可达，插件仍可正常运行
|
||||
- Monitor serves a local bridge on `127.0.0.1:<MONITOR_PORT>`
|
||||
- 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`
|
||||
|
||||
@@ -197,7 +197,18 @@ function register(api: PluginAPI): void {
|
||||
* Wake agent via dispatchInboundMessage — same mechanism used by Discord plugin.
|
||||
* Direct in-process call, no WebSocket or CLI needed.
|
||||
*/
|
||||
async function wakeAgent(agentId: string): Promise<boolean> {
|
||||
async function wakeAgent(
|
||||
agentId: string,
|
||||
dueSlots?: Array<{
|
||||
id?: number | null;
|
||||
virtual_id?: string | null;
|
||||
event_data?: any;
|
||||
scheduled_at?: string;
|
||||
priority?: number;
|
||||
slot_type?: string;
|
||||
[k: string]: unknown;
|
||||
}>
|
||||
): Promise<boolean> {
|
||||
logger.info(`Waking agent ${agentId}: has due slots`);
|
||||
|
||||
const sessionKey = `agent:${agentId}:hf-wakeup`;
|
||||
@@ -208,13 +219,39 @@ function register(api: PluginAPI): void {
|
||||
/* webpackIgnore: true */ sdkPath
|
||||
);
|
||||
|
||||
const cfg = api.runtime?.config?.loadConfig?.();
|
||||
// api.config first (current public API). Fall back to deprecated
|
||||
// runtime.config.loadConfig() for older host versions. Both should
|
||||
// contain agents.list / channels for dispatch routing.
|
||||
const cfg = (api as any).config ?? api.runtime?.config?.loadConfig?.();
|
||||
if (!cfg) {
|
||||
logger.error('Cannot load OpenClaw config for dispatch');
|
||||
return false;
|
||||
}
|
||||
|
||||
const wakeupMessage = `You have due slots. Follow the \`hf-wakeup\` workflow of skill \`hf-hangman-lab\` to proceed. Only reply \`WAKEUP_OK\` in this session.`;
|
||||
// Inline the highest-priority due slot's context so the agent does
|
||||
// not need a second round-trip to harborforge_calendar_status. The
|
||||
// agent can read event_data.task_code / task_title etc. directly.
|
||||
let slotBlock = '';
|
||||
const top = dueSlots && dueSlots.length ? dueSlots[0] : undefined;
|
||||
if (top) {
|
||||
slotBlock = `\n\nMatching slot:\n\`\`\`json\n${JSON.stringify(
|
||||
{
|
||||
slot_id: top.id ?? null,
|
||||
virtual_id: top.virtual_id ?? null,
|
||||
scheduled_at: top.scheduled_at ?? null,
|
||||
priority: top.priority ?? null,
|
||||
slot_type: top.slot_type ?? null,
|
||||
event_data: top.event_data ?? null,
|
||||
},
|
||||
null,
|
||||
2
|
||||
)}\n\`\`\``;
|
||||
}
|
||||
|
||||
const wakeupMessage =
|
||||
`You have due slots. Follow the \`hf-wakeup\` workflow of skill ` +
|
||||
`\`hf-hangman-lab\` to proceed. Only reply \`WAKEUP_OK\` in this ` +
|
||||
`session.${slotBlock}`;
|
||||
|
||||
const result = await dispatchInboundMessageWithDispatcher({
|
||||
ctx: {
|
||||
@@ -308,28 +345,59 @@ function register(api: PluginAPI): void {
|
||||
}
|
||||
}
|
||||
|
||||
// Track wakes already dispatched for a slot in the current sync
|
||||
// window — the simplified inline scheduler does not PATCH slot
|
||||
// status server-side, so without dedupe the check loop re-wakes
|
||||
// the same slot every 30s. Set is cleared by runSync (fresh wake
|
||||
// budget per sync).
|
||||
const wakedSlotKeys = new Set<string>();
|
||||
|
||||
// Check: find agents with due slots and wake them
|
||||
async function runCheck() {
|
||||
const now = new Date();
|
||||
const agentsWithDue = scheduleCache.getAgentsWithDueSlots(now);
|
||||
|
||||
for (const { agentId } of agentsWithDue) {
|
||||
// Check if agent is busy
|
||||
const status = await calendarBridge.getAgentStatus(agentId);
|
||||
for (const { agentId, slots } of agentsWithDue) {
|
||||
// Filter out slots we've already woken this sync window
|
||||
const fresh = slots.filter((s) => {
|
||||
const key = `${agentId}::${s.id ?? s.virtual_id ?? s.scheduled_at}`;
|
||||
if (wakedSlotKeys.has(key)) return false;
|
||||
return true;
|
||||
});
|
||||
if (fresh.length === 0) continue;
|
||||
|
||||
// Check if agent is busy (best effort; backend may 405 the GET
|
||||
// — treat unknown as not-busy so wakeup still fires)
|
||||
let status: string | null = null;
|
||||
try {
|
||||
status = await calendarBridge.getAgentStatus(agentId);
|
||||
} catch {
|
||||
status = null;
|
||||
}
|
||||
if (status === 'busy' || status === 'offline' || status === 'exhausted') {
|
||||
continue;
|
||||
}
|
||||
|
||||
// Wake the agent
|
||||
await wakeAgent(agentId);
|
||||
// Wake the agent with the slot context inlined
|
||||
const ok = await wakeAgent(agentId, fresh);
|
||||
if (ok) {
|
||||
for (const s of fresh) {
|
||||
const key = `${agentId}::${s.id ?? s.virtual_id ?? s.scheduled_at}`;
|
||||
wakedSlotKeys.add(key);
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// Initial sync
|
||||
runSync();
|
||||
// Initial sync (also resets the wake-dedupe window)
|
||||
const runSyncReset = async () => {
|
||||
wakedSlotKeys.clear();
|
||||
await runSync();
|
||||
};
|
||||
runSyncReset();
|
||||
|
||||
// Start intervals
|
||||
const syncHandle = setInterval(runSync, SYNC_INTERVAL_MS);
|
||||
const syncHandle = setInterval(runSyncReset, SYNC_INTERVAL_MS);
|
||||
const checkHandle = setInterval(runCheck, CHECK_INTERVAL_MS);
|
||||
|
||||
// Store handles for cleanup (reuse calendarScheduler variable)
|
||||
|
||||
@@ -11,7 +11,11 @@
|
||||
"harborforge_telemetry",
|
||||
"harborforge_monitor_telemetry",
|
||||
"harborforge_calendar_status",
|
||||
"harborforge_calendar_complete"
|
||||
"harborforge_calendar_complete",
|
||||
"harborforge_calendar_abort",
|
||||
"harborforge_calendar_pause",
|
||||
"harborforge_calendar_resume",
|
||||
"harborforge_restart_status"
|
||||
]
|
||||
},
|
||||
"configSchema": {
|
||||
|
||||
8
plugin/package-lock.json
generated
8
plugin/package-lock.json
generated
@@ -9,14 +9,14 @@
|
||||
"version": "0.2.0",
|
||||
"license": "MIT",
|
||||
"devDependencies": {
|
||||
"@types/node": "^20.0.0",
|
||||
"@types/node": "^20.19.41",
|
||||
"typescript": "^5.0.0"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/node": {
|
||||
"version": "20.19.37",
|
||||
"resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.37.tgz",
|
||||
"integrity": "sha512-8kzdPJ3FsNsVIurqBs7oodNnCEVbni9yUEkaHbgptDACOPW04jimGagZ51E6+lXUwJjgnBw+hyko/lkFWCldqw==",
|
||||
"version": "20.19.41",
|
||||
"resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.41.tgz",
|
||||
"integrity": "sha512-ECymXOukMnOoVkC2bb1Vc/w/836DXncOg5m8Xj1RH7xSHZJWNYY6Zh7EH477vcnD5egKNNfy2RpNOmuChhFPgQ==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
|
||||
@@ -10,7 +10,7 @@
|
||||
"watch": "tsc --watch"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^20.0.0",
|
||||
"@types/node": "^20.19.41",
|
||||
"typescript": "^5.0.0"
|
||||
},
|
||||
"license": "MIT"
|
||||
|
||||
Reference in New Issue
Block a user