openclaw-glance-plugin 0.1.0

package/README.md

@@ -0,0 +1,122 @@
+# openclaw-glance
+
+智能盯盘：OpenClaw 插件客户端（连接 `openclaw-bridge`）。
+
+OpenClaw 集成引导请看：[docs/openclaw-install-guide.md](./docs/openclaw-install-guide.md)
+
+## 插件定位
+
+这个插件用于让 OpenClaw 在“用户提出盯盘需求”时，快速完成以下动作：
+
+- 建立与 `openclaw-bridge` 的长连接
+- 把用户自然语言需求转成结构化策略并提交（`watch.create`）
+- 在触发后实时接收 `watch.triggered` 回调给 OpenClaw 业务层
+- 支持策略控制（激活、暂停、删除）
+
+## OpenClaw 调用时机
+
+- 用户新建盯盘：调用 `submitWatchDemand` 或 `createWatch`
+- 用户修改状态：调用 `activate` / `pause`
+- 用户删除盯盘：调用 `remove`
+- 需要接收触发消息：注册 `onTriggered` 并保持连接在线
+
+## 功能
+
+- 与 `openclaw-bridge` 建立 WebSocket 长连接
+- 支持请求：`watch.create` / `watch.activate` / `watch.pause` / `watch.delete` / `ping`
+- 订阅推送：`watch.triggered`
+- 自动重连 + 心跳
+- 断线请求排队（可配置），重连后自动冲刷
+- 提供业务适配层 `OpenClawPluginAdapter`
+
+## 安装
+
+```bash
+npm install
+```
+
+## 测试
+
+```bash
+npm test
+```
+
+## 运行示例
+
+```bash
+OPENCLAW_BRIDGE_WS_BASE=ws://glanceup-pre.100credit.cn \
+OPENCLAW_WS_TOKEN=your_ws_token \
+npm start
+```
+
+运行适配层示例：
+
+```bash
+npm run start:adapter
+```
+
+## SDK 使用
+
+```js
+import { OpenClawBridgeClient } from './src/index.js';
+
+const client = new OpenClawBridgeClient({
+  baseWsUrl: 'ws://glanceup-pre.100credit.cn',
+  token: '<JWT_TOKEN>',
+  enqueueIfDisconnected: true
+});
+
+client.on('triggered', (msg) => {
+  console.log(msg);
+});
+
+await client.connect();
+const res = await client.createWatch({
+  product_code: '00700',
+  product_type: 'hk_stock',
+  operator_type: 'rule',
+  operator_parameters: {
+    condition: 'price < threshold',
+    variables: { threshold: 420 }
+  },
+  channels: ['openclaw'],
+  channel_configs: { openclaw: {} }
+});
+```
+
+## 适配层用法
+
+```js
+import { OpenClawPluginAdapter } from './src/index.js';
+
+const adapter = new OpenClawPluginAdapter({
+  baseWsUrl: 'ws://glanceup-pre.100credit.cn',
+  token: '<JWT_TOKEN>'
+});
+
+await adapter.start();
+await adapter.submitWatchDemand({
+  productCode: '06608',
+  productType: 'hk_stock',
+  condition: 'price >= threshold',
+  variables: { threshold: 8.97 },
+  channels: ['openclaw'],
+  channelConfigs: { openclaw: {} }
+});
+```
+
+## 客户端事件
+
+- `connected`
+- `disconnected`
+- `reconnecting`
+- `warning`
+- `error`
+- `queued`（请求入队）
+- `queueFlushed`（重连后队列发送）
+- `triggered`
+
+## 说明
+
+- 先获取 ws `token`，然后连接 `ws://<host>:8005/openclaw/ws`，并在握手 Header 传 `Authorization: Bearer <TOKEN>`。
+- 发布时将导出 `src/` 与 `README.md`（见 `package.json` 的 `files/exports`）。

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "openclaw-glance-plugin",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin client for ticker-monitor openclaw-bridge",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node examples/basic.js",
+    "start:adapter": "node examples/adapter.js",
+    "test": "node --test tests/**/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "ws": "^8.18.0"
+  }
+}

package/src/OpenClawBridgeClient.js

@@ -0,0 +1,360 @@
+import EventEmitter from 'node:events';
+import WebSocket from 'ws';
+
+const DEFAULT_BASE_WS_URL = 'ws://glanceup-pre.100credit.cn';
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function makeRequestId() {
+  return `req_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
+}
+
+/**
+ * 全局单例实例
+ * @type {OpenClawBridgeClient|null}
+ */
+let globalInstance = null;
+
+/**
+ * 获取全局单例实例
+ * @param {Object} options - 创建实例的选项（仅首次创建时有效）
+ * @returns {OpenClawBridgeClient} 全局单例实例
+ */
+export function getGlobalClient(options) {
+  if (!globalInstance) {
+    globalInstance = new OpenClawBridgeClient(options);
+  }
+  return globalInstance;
+}
+
+/**
+ * 获取全局单例实例（别名，推荐使用）
+ * @param {Object} options - 创建实例的选项（仅首次创建时有效）
+ * @returns {OpenClawBridgeClient} 全局单例实例
+ */
+export function getInstance(options) {
+  return getGlobalClient(options);
+}
+
+/**
+ * 重置全局单例实例（主要用于测试）
+ */
+export async function resetGlobalClient() {
+  if (globalInstance) {
+    await globalInstance.close(true);
+    globalInstance = null;
+  }
+}
+
+export class OpenClawBridgeClient extends EventEmitter {
+  constructor(options) {
+    super();
+    const {
+      baseWsUrl = DEFAULT_BASE_WS_URL,
+      token = '',
+      heartbeatMs = 15000,
+      requestTimeoutMs = 10000,
+      waitConnectTimeoutMs = 20000,
+      reconnect = true,
+      reconnectBaseMs = 1000,
+      reconnectMaxMs = 15000,
+      enqueueIfDisconnected = true,
+      maxQueueSize = 200
+    } = options || {};
+
+    if (!token) throw new Error('token is required');
+
+    this.baseWsUrl = baseWsUrl.replace(/\/$/, '');
+    this.userId = '';
+    this.token = token;
+
+    this.heartbeatMs = heartbeatMs;
+    this.requestTimeoutMs = requestTimeoutMs;
+    this.waitConnectTimeoutMs = waitConnectTimeoutMs;
+    this.reconnect = reconnect;
+    this.reconnectBaseMs = reconnectBaseMs;
+    this.reconnectMaxMs = reconnectMaxMs;
+    this.enqueueIfDisconnected = enqueueIfDisconnected;
+    this.maxQueueSize = maxQueueSize;
+
+    this.ws = null;
+    this.connected = false;
+    this.stopped = false;
+    this.heartbeatTimer = null;
+    this.reconnectAttempt = 0;
+    this.pending = new Map();
+    this.requestQueue = [];
+  }
+
+  get wsUrl() {
+    const url = new URL('/openclaw/ws', this.baseWsUrl);
+    return url.toString();
+  }
+
+  async connect() {
+    this.stopped = false;
+    await this._connectOnce();
+  }
+
+  async close(force = true) {
+    this.stopped = Boolean(force);
+    this._clearHeartbeat();
+
+    for (const [requestId, waiter] of this.pending.entries()) {
+      clearTimeout(waiter.timer);
+      waiter.reject(new Error(`connection closed before response: ${requestId}`));
+    }
+    this.pending.clear();
+    for (const queued of this.requestQueue) {
+      queued.reject(new Error(`connection closed before request sent: ${queued.requestId}`));
+    }
+    this.requestQueue = [];
+
+    if (this.ws) {
+      try {
+        this.ws.close();
+      } catch (_err) {
+        // ignore
+      }
+    }
+  }
+
+  async createWatch(payload) {
+    return this._request('watch.create', payload);
+  }
+
+  async activateWatch(strategyId) {
+    return this._request('watch.activate', { strategy_id: strategyId });
+  }
+
+  async pauseWatch(strategyId) {
+    return this._request('watch.pause', { strategy_id: strategyId });
+  }
+
+  async deleteWatch(strategyId) {
+    return this._request('watch.delete', { strategy_id: strategyId });
+  }
+
+  async ping() {
+    return this._request('ping', {});
+  }
+
+  async waitUntilConnected(timeoutMs = this.waitConnectTimeoutMs) {
+    if (this.connected && this.ws && this.ws.readyState === WebSocket.OPEN) {
+      return true;
+    }
+
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        cleanup();
+        reject(new Error(`waitUntilConnected timeout (${timeoutMs}ms)`));
+      }, timeoutMs);
+
+      const onConnected = () => {
+        cleanup();
+        resolve(true);
+      };
+
+      const cleanup = () => {
+        clearTimeout(timer);
+        this.off('connected', onConnected);
+      };
+
+      this.on('connected', onConnected);
+    });
+  }
+
+  async _request(type, payload) {
+    const requestId = makeRequestId();
+    const msg = { type, request_id: requestId, payload: payload || {} };
+    const { promise, resolve, reject } = this._buildWaiter(type, requestId);
+
+    if (!this.connected || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      if (!this.enqueueIfDisconnected) {
+        reject(new Error('websocket not connected'));
+        return promise;
+      }
+      if (this.requestQueue.length >= this.maxQueueSize) {
+        reject(new Error(`request queue overflow (max=${this.maxQueueSize})`));
+        return promise;
+      }
+      this.requestQueue.push({ msg, requestId, type, resolve, reject });
+      this.emit('queued', { type, requestId, queueSize: this.requestQueue.length });
+      return promise;
+    }
+
+    this._sendWithTimeout({ msg, requestId, type, resolve, reject });
+    return promise;
+  }
+
+  _buildWaiter(type, requestId) {
+    let resolve;
+    let reject;
+    const promise = new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    return { promise, resolve, reject, type, requestId };
+  }
+
+  _sendWithTimeout({ msg, requestId, type, resolve, reject }) {
+    const timer = setTimeout(() => {
+      this.pending.delete(requestId);
+      reject(new Error(`request timeout: ${type} (${requestId})`));
+    }, this.requestTimeoutMs);
+
+    this.pending.set(requestId, { resolve, reject, timer, type });
+    this.ws.send(JSON.stringify(msg));
+  }
+
+  async _connectOnce() {
+    const ws = new WebSocket(this.wsUrl, {
+      headers: {
+        Authorization: `Bearer ${this.token}`
+      }
+    });
+
+    await new Promise((resolve, reject) => {
+      const onOpen = () => {
+        cleanup();
+        resolve();
+      };
+      const onError = (err) => {
+        cleanup();
+        reject(err);
+      };
+      const cleanup = () => {
+        ws.off('open', onOpen);
+        ws.off('error', onError);
+      };
+      ws.on('open', onOpen);
+      ws.on('error', onError);
+    });
+
+    this.ws = ws;
+    this.connected = true;
+    this.reconnectAttempt = 0;
+    this.emit('connected');
+    this._flushQueue();
+
+    ws.on('message', (raw) => {
+      this._onMessage(raw.toString());
+    });
+
+    ws.on('close', (code, reason) => {
+      this._onClose(code, reason?.toString());
+    });
+
+    ws.on('error', (err) => {
+      this.emit('error', err);
+    });
+
+    this._startHeartbeat();
+  }
+
+  _onMessage(raw) {
+    let msg;
+    try {
+      msg = JSON.parse(raw);
+    } catch (err) {
+      this.emit('warning', new Error(`invalid json from bridge: ${raw}`));
+      return;
+    }
+
+    const requestId = msg.request_id;
+    if (requestId && this.pending.has(requestId)) {
+      const waiter = this.pending.get(requestId);
+      this.pending.delete(requestId);
+      clearTimeout(waiter.timer);
+      waiter.resolve(msg);
+      return;
+    }
+
+    if (msg.type === 'watch.triggered') {
+      this.emit('triggered', msg);
+      return;
+    }
+
+    if (msg.type === 'system.connected') {
+      this.userId = msg.user_id || this.userId;
+      this.emit('systemConnected', msg);
+      return;
+    }
+
+    this.emit('message', msg);
+  }
+
+  async _onClose(code, reason) {
+    this.connected = false;
+    this._clearHeartbeat();
+    this.emit('disconnected', { code, reason, reconnect: this.reconnect, stopped: this.stopped });
+
+    if (this.stopped) {
+      return;
+    }
+
+    // 如果不是主动停止，则自动重连
+    if (!this.reconnect) {
+      return;
+    }
+
+    while (!this.stopped) {
+      this.reconnectAttempt += 1;
+      const backoff = Math.min(
+        this.reconnectBaseMs * Math.min(this.reconnectAttempt, 10),
+        this.reconnectMaxMs
+      );
+      this.emit('reconnecting', { attempt: this.reconnectAttempt, backoffMs: backoff, reason: 'auto' });
+      await sleep(backoff);
+
+      if (this.stopped) {
+        break;
+      }
+
+      try {
+        await this._connectOnce();
+        this.emit('reconnected', { attempt: this.reconnectAttempt });
+        return;
+      } catch (err) {
+        const reconnectErr = new Error(`重连失败: ${err.message}`);
+        reconnectErr.attempt = this.reconnectAttempt;
+        this.emit('error', reconnectErr);
+      }
+    }
+  }
+
+  _startHeartbeat() {
+    this._clearHeartbeat();
+    this.heartbeatTimer = setInterval(async () => {
+      if (!this.connected) return;
+      try {
+        await this.ping();
+      } catch (err) {
+        this.emit('warning', new Error(`heartbeat failed: ${err.message}`));
+      }
+    }, this.heartbeatMs);
+  }
+
+  _flushQueue() {
+    if (!this.connected || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      return;
+    }
+    if (!this.requestQueue.length) {
+      return;
+    }
+    const queued = this.requestQueue.splice(0, this.requestQueue.length);
+    for (const item of queued) {
+      this._sendWithTimeout(item);
+    }
+    this.emit('queueFlushed', { count: queued.length });
+  }
+
+  _clearHeartbeat() {
+    if (this.heartbeatTimer) {
+      clearInterval(this.heartbeatTimer);
+      this.heartbeatTimer = null;
+    }
+  }
+}

package/src/OpenClawPluginAdapter.js

@@ -0,0 +1,104 @@
+import { OpenClawBridgeClient } from './OpenClawBridgeClient.js';
+
+/**
+ * 全局单例 Adapter 实例
+ * @type {OpenClawPluginAdapter|null}
+ */
+let globalAdapterInstance = null;
+
+/**
+ * 获取全局单例 Adapter 实例
+ * @param {Object} clientOrOptions - 客户端实例或配置选项
+ * @returns {OpenClawPluginAdapter} 全局单例 Adapter 实例
+ */
+export function getGlobalAdapter(clientOrOptions) {
+  if (!globalAdapterInstance) {
+    globalAdapterInstance = new OpenClawPluginAdapter(clientOrOptions);
+  }
+  return globalAdapterInstance;
+}
+
+/**
+ * 获取全局单例 Adapter 实例（别名，推荐使用）
+ * @param {Object} clientOrOptions - 客户端实例或配置选项
+ * @returns {OpenClawPluginAdapter} 全局单例 Adapter 实例
+ */
+export function getAdapter(clientOrOptions) {
+  return getGlobalAdapter(clientOrOptions);
+}
+
+/**
+ * 重置全局单例 Adapter（主要用于测试）
+ */
+export async function resetGlobalAdapter() {
+  if (globalAdapterInstance) {
+    await globalAdapterInstance.stop();
+    globalAdapterInstance = null;
+  }
+}
+
+/**
+ * 面向 OpenClaw 业务层的薄适配器。
+ * 负责把业务输入转换为 bridge 协议中的 watch.* 请求。
+ * 支持单例模式：通过 getAdapter() 或 getGlobalAdapter() 获取全局实例
+ */
+export class OpenClawPluginAdapter {
+  constructor(clientOrOptions) {
+    const looksLikeClient =
+      clientOrOptions &&
+      typeof clientOrOptions === 'object' &&
+      typeof clientOrOptions.createWatch === 'function' &&
+      typeof clientOrOptions.pauseWatch === 'function' &&
+      typeof clientOrOptions.activateWatch === 'function' &&
+      typeof clientOrOptions.deleteWatch === 'function';
+
+    if (clientOrOptions instanceof OpenClawBridgeClient || looksLikeClient) {
+      this.client = clientOrOptions;
+    } else {
+      this.client = new OpenClawBridgeClient(clientOrOptions || {});
+    }
+  }
+
+  async start() {
+    await this.client.connect();
+  }
+
+  async stop() {
+    await this.client.close(true);
+  }
+
+  onTriggered(handler) {
+    this.client.on('triggered', handler);
+  }
+
+  /**
+   * 统一创建盯盘需求接口（适配 OpenClaw 侧参数）。
+   */
+  async submitWatchDemand(demand) {
+    const payload = {
+      product_code: demand.productCode,
+      product_type: demand.productType || 'stock',
+      operator_type: 'rule',
+      operator_parameters: {
+        condition: demand.condition,
+        variables: demand.variables || {},
+        message_template: demand.messageTemplate
+      },
+      channels: demand.channels || ['openclaw'],
+      channel_configs: demand.channelConfigs || { openclaw: {} }
+    };
+    return this.client.createWatch(payload);
+  }
+
+  async pause(strategyId) {
+    return this.client.pauseWatch(strategyId);
+  }
+
+  async activate(strategyId) {
+    return this.client.activateWatch(strategyId);
+  }
+
+  async remove(strategyId) {
+    return this.client.deleteWatch(strategyId);
+  }
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { OpenClawBridgeClient, getGlobalClient, getInstance, resetGlobalClient } from './OpenClawBridgeClient.js';
+export { OpenClawPluginAdapter, getGlobalAdapter, getAdapter, resetGlobalAdapter } from './OpenClawPluginAdapter.js';