openclaw-glance-plugin 0.1.10 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-glance-plugin",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "OpenClaw plugin client for ticker-monitor openclaw-bridge",
   "type": "module",
   "main": "index.js",

package/skills/glance-watch/SKILL.md

@@ -75,10 +75,10 @@ description: 智能盯盘插件，用于监控A股、港股、比特币等金融
 - 对应渠道配置（`emailConfig/callConfig/smsConfig`）
 
 渠道参数要求（必须）：
-- 只要 `channels` 包含 `email`，必须提供 `emailConfig` 且包含 `to_address`
-- 只要 `channels` 包含 `call`，必须提供 `callConfig` 且包含 `phone`
-- 只要 `channels` 包含 `sms`，必须提供 `smsConfig` 且包含 `receiver`（或 `phone`）
-- 只要 `channels` 包含 `dingtalk`，必须提供 `dingtalkConfig` 且包含 `cas_id`
+- 只要 `channels` 包含 `email`，必须提供 `emailConfig.to_address/template_id/title/content`
+- 只要 `channels` 包含 `call`，必须提供 `callConfig.phone/customer_name/condition`
+- 只要 `channels` 包含 `sms`，必须提供 `smsConfig.receiver(或phone)/template_id/content`
+- 只要 `channels` 包含 `dingtalk`，必须提供 `dingtalkConfig.cas_id/template_id/msg_type/content`
 
 成功判定：
 - 返回 `success = true`
@@ -86,6 +86,8 @@ description: 智能盯盘插件，用于监控A股、港股、比特币等金融
 失败处理：
 - 明确返回失败原因，不要静默重试
 - 提示用户补充或修正参数
+- 若是超时/网络波动导致的重试，必须使用同一组创建参数再次调用 `watch.create`（不要改字段和值），避免重复创建策略
+- `request_id` 由插件运行时自动生成并在同 payload 重试时自动复用；大模型无需手动设置 `request_id`
 
 #### `watch.pause` / `watch.activate` / `watch.remove`
 
@@ -101,16 +103,18 @@ description: 智能盯盘插件，用于监控A股、港股、比特币等金融
 #### `notify.sms` / `notify.call` / `notify.email` / `notify.dingtalk`
 
 参数：
-- `notify.sms`：必须提供手机号（`receiver` 或 `phone`）
-- `notify.call`：必须提供 `phone`
-- `notify.email`：必须提供 `to_address`
-- `notify.dingtalk`：必须提供 `cas_id`
+- `notify.sms`：必须提供 `receiver`（或 `phone`）、`template_id`、`content`
+- `notify.call`：必须提供 `phone`、`customer_name`、`condition`
+- `notify.email`：必须提供 `to_address`、`template_id`、`title`、`content`
+- `notify.dingtalk`：必须提供 `cas_id`、`template_id`、`msg_type`、`content`
 
 成功判定：
 - 返回 `success = true`
 
 失败处理：
 - 明确返回失败原因，不要静默重试
+- 若是超时/网络波动导致的重试，必须使用同一组通知参数再次调用（不要改字段和值）
+- `request_id` 由插件运行时自动生成并在同 payload 重试时自动复用；大模型无需手动设置 `request_id`
 
 回执说明：
 - 直连通知发送完成后，客户端会收到 `notify.sent` 事件（`overall_status/success_count/failed_count/deliveries`）
@@ -162,6 +166,7 @@ description: 智能盯盘插件，用于监控A股、港股、比特币等金融
 - `data/stock_a.csv`：A股个股列表（`productType=stock`）
 - `data/stock_hk.csv`：港股个股列表（`productType=hk_stock`）
 - `data/index_a.csv`：A股指数列表（`productType=index`）
+- `data/index_hk.csv`：港股指数列表（支持指数代码和中文名称查询）
 
 ### 场景1：用户只说股票简称/名称
 - 使用模糊搜索在上述 CSV 中查找名称。
@@ -169,11 +174,12 @@ description: 智能盯盘插件，用于监控A股、港股、比特币等金融
 - 用户确认后再创建策略。
 
 ### 场景2：不知道某个标的代码或所属市场
-- 使用 `rg`（或 `grep`）在三个 CSV 中搜索标的名称或代码。
+- 使用 `rg`（或 `grep`）在四个 CSV 中搜索标的名称或代码。
 - 根据命中结果判断市场并映射 `productType`：
   - A股个股 -> `stock`
   - 港股个股 -> `hk_stock`
   - A股指数 -> `index`
+  - 港股指数 -> `index`（`market=HK`）
 - 若搜索结果不唯一或冲突，先向用户确认后再继续。
 
 ### 推荐检索命令
@@ -181,12 +187,14 @@ description: 智能盯盘插件，用于监控A股、港股、比特币等金融
 ```bash
 # 按名称模糊查找（推荐）
 rg -n "平安银行|腾讯|沪深300|BTC" data/stock_a.csv data/stock_hk.csv data/index_a.csv
+rg -n "恒生科技指数|恒生指数|HSTECH|HSI" data/index_hk.csv
 
 # 按代码查找
 rg -n "000001|00700|399001" data/stock_a.csv data/stock_hk.csv data/index_a.csv
+rg -n "HSTECH|HSI|VHSI" data/index_hk.csv
 
 # grep 兜底（无 rg 时）
-grep -nE "平安银行|腾讯|沪深300|000001|00700" data/stock_a.csv data/stock_hk.csv data/index_a.csv
+grep -nE "平安银行|腾讯|沪深300|000001|00700|恒生科技指数|HSTECH" data/stock_a.csv data/stock_hk.csv data/index_a.csv data/index_hk.csv
 ```
 
 ## 行情查询（queryTickerData）
@@ -196,6 +204,7 @@ grep -nE "平安银行|腾讯|沪深300|000001|00700" data/stock_a.csv data/stoc
 1. 先根据用户输入确定标的代码与市场：
 - 如果是简称/名称，先在 `data/*.csv` 里模糊搜索并向用户确认候选。
 - 如果是明确代码，按代码在 `data/*.csv` 查对应 `市场`。
+- 港股指数可直接用代码（如 `HSTECH`）或中文名称（如 `恒生科技指数`）查询；命中 `index_hk.csv` 时优先使用 `market=HK`。
 
 2. 调用已安装插件/包暴露的查询接口（例如 `queryTickerData`）：
 
@@ -216,18 +225,17 @@ await runtime.queryTickerData({
 `openclaw` 渠道必传，`email` / `call` / `sms` / `dingtalk` 可选。如用户没明确说明使用邮件(email)、电话/外呼(call)、短信(sms)、钉钉(dingtalk)通知提醒，则只需要传入`openclaw`渠道。
 
 但一旦用户选择了某个通知渠道，其配置参数必须完整填写：
-- 选择 `email` 必须提供 `emailConfig.to_address`
-- 选择 `call` 必须提供 `callConfig.phone`
-- 选择 `sms` 必须提供 `smsConfig.receiver`（或 `phone`）
-- 选择 `dingtalk` 必须提供 `dingtalkConfig.cas_id`
+- 选择 `email` 必须提供 `emailConfig.to_address/template_id/title/content`
+- 选择 `call` 必须提供 `callConfig.phone/customer_name/condition`
+- 选择 `sms` 必须提供 `smsConfig.receiver(或phone)/template_id/content`
+- 选择 `dingtalk` 必须提供 `dingtalkConfig.cas_id/template_id/msg_type/content`
 
 ### email 参数（emailConfig）
 - `to_address`：收件人邮箱（必填，缺失不可创建/不可发送）
 - `template_id`：邮件模板 ID（必填，默认为4，不需要修改）
 - `template_params`：模板变量
-- `title`: 收到邮件的标题
-- `product_name`: 产品名称 
-- `content`: 消息内容
+- `title`: 收到邮件的标题（必填）
+- `content`: 消息内容（必填）
 示例：
 ```javascript
 emailConfig: {
@@ -235,7 +243,6 @@ emailConfig: {
   template_id: 4,
   template_params: {
     title: '监控提醒',
-    product_name: '比特币',
     content: '测试消息1'
   }
 }
@@ -244,8 +251,8 @@ emailConfig: {
 
 ### call 参数（callConfig）
 - `phone`：手机号（必填，缺失不可创建/不可发送）
-- `customer_name`：客户名称
-- `condition`：外呼内容
+- `customer_name`：客户名称（必填）
+- `condition`：外呼内容（必填）
 
 示例：
 ```javascript
@@ -260,8 +267,8 @@ callConfig: {
 
 ### sms 参数（smsConfig）
 - `receiver`：手机号（必填，必须是纯数字；缺失不可创建/不可发送）
-- `template_id`：短信模板 ID（可选，默认 90010，不需要修改）
-- `content`：短信变量内容
+- `template_id`：短信模板 ID（必填，默认 90010，不需要修改）
+- `content`：短信变量内容（必填）
 
 示例：
 ```javascript
@@ -276,9 +283,9 @@ smsConfig: {
 
 ### 钉钉 参数（dingtalkConfig）
 - `cas_id`：钉钉用户ID（必填，缺失不可创建/不可发送）
-- `template_id`：钉钉模板 ID（可选，默认 3，不需要修改）
-- `msg_type`: 消息类型：text/markdown，默认 text
-- `content`：消息内容
+- `template_id`：钉钉模板 ID（必填，默认 3，不需要修改）
+- `msg_type`: 消息类型（必填）：`text`/`markdown`
+- `content`：消息内容（必填）
 
 示例：
 ```javascript
@@ -298,6 +305,7 @@ dingtalkConfig: {
 |------|-------------|------|------|
 | A股个股 | stock | 000001 | 每3秒行情 |
 | A股指数 | index | 000300 | 每3秒行情 |
+| 港股指数 | index | HSTECH / 恒生科技指数 | 查询时 `market=HK` |
 | 港股 | hk_stock | 00700 | 延迟15分钟 |
 | 加密货币 | crypto | BTCUSDT | 每10秒行情 |
 
@@ -345,6 +353,12 @@ variables: { threshold: 420, product_name: '腾讯控股' }
 - 明确返回失败原因给用户
 - 引导用户补充或修正参数后再次创建
 
+如果直连通知失败（`notify.send.result.success=false`）：
+- 优先读取并返回 `code/error/hint`，不要只说“通知失败”
+- 若 `code=MISSING_REQUIRED_FIELD`，直接告诉用户缺失字段并让其补齐
+- 若 `code=UNSUPPORTED_MESSAGE_TYPE`，提示“bridge 版本不支持 notify.send，需要升级并重启”
+- 若 `code=UPSTREAM_UNAVAILABLE`，提示“notification 服务不可用或超时，请稍后重试”
+
 ## 相关资源
 
 - 市场参考: [references/markets.md](references/markets.md)

package/skills/glance-watch/data/index_hk.csv

@@ -0,0 +1,40 @@
+类型,代码,名称,完整代码,市场
+港股指数,VHSI,恒指波幅指数,VHSI,HK
+港股指数,HSTECH,恒生科技指数,HSTECH,HK
+港股指数,H11144,HKT内地消费指数,H11144,HK
+港股指数,H11140,香港红利指数,H11140,HK
+港股指数,HSMOGI,恒生内地石油,HSMOGI,HK
+港股指数,CES120,中华120指数,CES120,HK
+港股指数,CESHKM,中华香港内地指数,CESHKM,HK
+港股指数,SCCEA,沪深港通中国企业,SCCEA,HK
+港股指数,HSMBI,恒生内地银行,HSMBI,HK
+港股指数,HSCEI,国企指数,HSCEI,HK
+港股指数,H11153,内地国企指数,H11153,HK
+港股指数,H11123,香港内地股指数,H11123,HK
+港股指数,CESA80,中华A80指数,CESA80,HK
+港股指数,HSC,恒生工商指数,HSC,HK
+港股指数,H11152,内地民企指数,H11152,HK
+港股指数,HSCEESG,恒生国指ESG指数,HSCEESG,HK
+港股指数,SPHKL,香港大型股指数,SPHKL,HK
+港股指数,CES300,中华沪港通300,CES300,HK
+港股指数,CES280,中华280指数,CES280,HK
+港股指数,CESCPD,中华内房股,CESCPD,HK
+港股指数,H11143,HKT内地地产指数,H11143,HK
+港股指数,HSCCI,恒生红筹指数,HSCCI,HK
+港股指数,H11110,香港基本面50指数,H11110,HK
+港股指数,SPHKG,香港创业板指数,SPHKG,HK
+港股指数,CESP50,中华港股通优选50,CESP50,HK
+港股指数,HSI,恒生指数,HSI,HK
+港股指数,H11100,香港100指数,H11100,HK
+港股指数,CESFHY,中华预期高息股,CESFHY,HK
+港股指数,HSU,恒生公用事业指数,HSU,HK
+港股指数,H11120,香港中盘精选指数,H11120,HK
+港股指数,HSIESG,恒指ESG指数,HSIESG,HK
+港股指数,HSMPI,恒生内地地产,HSMPI,HK
+港股指数,CES100,港股通精选100,CES100,HK
+港股指数,HSBIO,恒生生物科技指数,HSBIO,HK
+港股指数,HSIESGS,恒指ESG增强指数,HSIESGS,HK
+港股指数,HSF,恒生金融分类指数,HSF,HK
+港股指数,CESHKB,中华香港生物科技,CESHKB,HK
+港股指数,HSP,恒生地产分类指数,HSP,HK
+港股指数,CESG10,中华博彩指数,CESG10,HK

package/src/OpenClawBridgeClient.js

@@ -11,6 +11,32 @@ function makeRequestId() {
   return `req_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`;
 }
 
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value).sort();
+    return `{${keys
+      .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+const IDEMPOTENT_REQUEST_TYPES = new Set(['watch.create', 'notify.send']);
+const IDEMPOTENT_RESULT_TYPE_TO_REQUEST_TYPE = new Map([
+  ['watch.create.result', 'watch.create'],
+  ['notify.send.result', 'notify.send']
+]);
+
+function idempotentRequestFingerprint(payload = {}) {
+  const normalized = { ...(payload || {}) };
+  delete normalized.request_id;
+  delete normalized.requestId;
+  return stableStringify(normalized);
+}
+
 /**
  * 全局单例实例
  * @type {OpenClawBridgeClient|null}
@@ -86,6 +112,10 @@ export class OpenClawBridgeClient extends EventEmitter {
     this.reconnectAttempt = 0;
     this.pending = new Map();
     this.requestQueue = [];
+    this.idempotentRetryWindowMs = 5 * 60 * 1000;
+    this.idempotentMaxCacheEntries = 1000;
+    this.idempotentRequestCache = new Map();
+    this.idempotentFingerprintByRequestId = new Map();
   }
 
   get wsUrl() {
@@ -122,7 +152,8 @@ export class OpenClawBridgeClient extends EventEmitter {
   }
 
   async createWatch(payload) {
-    return this._request('watch.create', payload);
+    const resolved = this._resolveIdempotentRequest('watch.create', payload || {});
+    return this._request('watch.create', resolved.payload, { requestId: resolved.requestId });
   }
 
   async activateWatch(strategyId) {
@@ -170,9 +201,18 @@ export class OpenClawBridgeClient extends EventEmitter {
     });
   }
 
-  async _request(type, payload) {
-    const requestId = makeRequestId();
-    const msg = { type, request_id: requestId, payload: payload || {} };
+  async _request(type, payload, options = {}) {
+    let requestId = options.requestId || '';
+    let normalizedPayload = payload || {};
+    if (!requestId && IDEMPOTENT_REQUEST_TYPES.has(type)) {
+      const resolved = this._resolveIdempotentRequest(type, normalizedPayload);
+      requestId = resolved.requestId;
+      normalizedPayload = resolved.payload;
+    }
+    if (!requestId) {
+      requestId = makeRequestId();
+    }
+    const msg = { type, request_id: requestId, payload: normalizedPayload };
     const { promise, resolve, reject } = this._buildWaiter(type, requestId);
 
     if (!this.connected || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
@@ -272,6 +312,7 @@ export class OpenClawBridgeClient extends EventEmitter {
       const waiter = this.pending.get(requestId);
       this.pending.delete(requestId);
       clearTimeout(waiter.timer);
+      this._finalizeIdempotentRequest(msg, requestId);
       waiter.resolve(msg);
       return;
     }
@@ -361,4 +402,74 @@ export class OpenClawBridgeClient extends EventEmitter {
       this.heartbeatTimer = null;
     }
   }
+
+  _resolveIdempotentRequest(type, payload = {}) {
+    this._cleanupIdempotentRequestCache();
+    const normalizedPayload = { ...(payload || {}) };
+    let requestId = String(
+      normalizedPayload.request_id || normalizedPayload.requestId || ''
+    ).trim();
+
+    if (!requestId) {
+      const fingerprint = idempotentRequestFingerprint(normalizedPayload);
+      const cacheKey = `${type}:${fingerprint}`;
+      const cached = this.idempotentRequestCache.get(cacheKey);
+      const now = Date.now();
+      if (cached && now - cached.ts <= this.idempotentRetryWindowMs) {
+        requestId = cached.requestId;
+      } else {
+        requestId = makeRequestId();
+        this.idempotentRequestCache.set(cacheKey, { requestId, ts: now });
+      }
+      this.idempotentFingerprintByRequestId.set(requestId, cacheKey);
+    }
+
+    normalizedPayload.request_id = requestId;
+    return { requestId, payload: normalizedPayload };
+  }
+
+  _cleanupIdempotentRequestCache(now = Date.now()) {
+    for (const [cacheKey, entry] of this.idempotentRequestCache.entries()) {
+      if (!entry || now - entry.ts > this.idempotentRetryWindowMs) {
+        this.idempotentRequestCache.delete(cacheKey);
+        if (entry?.requestId) {
+          this.idempotentFingerprintByRequestId.delete(entry.requestId);
+        }
+      }
+    }
+
+    if (this.idempotentRequestCache.size > this.idempotentMaxCacheEntries) {
+      const sorted = Array.from(this.idempotentRequestCache.entries()).sort(
+        (a, b) => (a[1]?.ts || 0) - (b[1]?.ts || 0)
+      );
+      const overflow = this.idempotentRequestCache.size - this.idempotentMaxCacheEntries;
+      for (let i = 0; i < overflow; i += 1) {
+        const [cacheKey, entry] = sorted[i] || [];
+        if (!cacheKey) continue;
+        this.idempotentRequestCache.delete(cacheKey);
+        if (entry?.requestId) {
+          this.idempotentFingerprintByRequestId.delete(entry.requestId);
+        }
+      }
+    }
+
+    for (const [requestId, cacheKey] of this.idempotentFingerprintByRequestId.entries()) {
+      if (!this.idempotentRequestCache.has(cacheKey)) {
+        this.idempotentFingerprintByRequestId.delete(requestId);
+      }
+    }
+  }
+
+  _finalizeIdempotentRequest(msg, requestId) {
+    const requestType = IDEMPOTENT_RESULT_TYPE_TO_REQUEST_TYPE.get(msg?.type);
+    if (!requestType) {
+      return;
+    }
+    const cacheKey = this.idempotentFingerprintByRequestId.get(requestId);
+    if (!cacheKey || !cacheKey.startsWith(`${requestType}:`)) {
+      return;
+    }
+    this.idempotentFingerprintByRequestId.delete(requestId);
+    this.idempotentRequestCache.delete(cacheKey);
+  }
 }

package/src/config/runtime-config.js

@@ -1,3 +1,4 @@
+import os from 'node:os';
 import path from 'node:path';
 import process from 'node:process';
 
@@ -15,13 +16,32 @@ function pick(source, keys, fallback = undefined) {
   return fallback;
 }
 
+export function resolveDefaultLockDir({ env = process.env, cwd = process.cwd() } = {}) {
+  const xdgStateHome = pick(env, ['XDG_STATE_HOME']);
+  if (xdgStateHome) {
+    return path.join(String(xdgStateHome), 'openclaw-locks');
+  }
+
+  const homeDir = pick(env, ['HOME', 'USERPROFILE']);
+  if (homeDir) {
+    return path.join(String(homeDir), '.openclaw-locks');
+  }
+
+  const cwdRoot = path.parse(cwd).root;
+  if (cwd === cwdRoot) {
+    return path.join(os.tmpdir(), 'openclaw-locks');
+  }
+
+  return path.join(cwd, '.openclaw-locks');
+}
+
 export function resolveRuntimeConfig({ env = process.env, pluginConfig = {} } = {}) {
   const baseWsUrl = String(
     pick(pluginConfig, ['baseWsUrl', 'base_ws_url'], pick(env, ['OPENCLAW_BASE_WS_URL'], DEFAULT_BASE_WS_URL))
   );
   const token = String(pick(pluginConfig, ['token'], pick(env, ['OPENCLAW_WS_TOKEN'], '')));
   const lockDir = String(
-    pick(pluginConfig, ['lockDir', 'lock_dir'], pick(env, ['OPENCLAW_LOCK_DIR'], path.join(process.cwd(), '.openclaw-locks')))
+    pick(pluginConfig, ['lockDir', 'lock_dir'], pick(env, ['OPENCLAW_LOCK_DIR'], resolveDefaultLockDir({ env })))
   );
   const lockKey = ProcessLock.buildLockKey(baseWsUrl, token);
   if (!token) {

package/src/plugin/index.js

@@ -24,6 +24,9 @@ export async function startPluginRuntime({ runtime, pluginConfig } = {}) {
     return activeRuntime;
   }
   const config = resolveRuntimeConfig({ pluginConfig });
+  runtime?.logger?.info?.(
+    `[openclaw-glance-plugin] runtime config resolved: baseWsUrl=${config.baseWsUrl}, lockDir=${config.lockDir}`
+  );
   const lock = new ProcessLock({
     lockDir: config.lockDir,
     key: config.lockKey

package/src/runtime/BridgeRuntime.js

@@ -9,6 +9,32 @@ function makeRequestId() {
   return `req_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
 }
 
+function stableStringify(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  }
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value).sort();
+    return `{${keys
+      .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key])}`)
+      .join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+const IDEMPOTENT_REQUEST_TYPES = new Set(['watch.create', 'notify.send']);
+const IDEMPOTENT_RESULT_TYPE_TO_REQUEST_TYPE = new Map([
+  ['watch.create.result', 'watch.create'],
+  ['notify.send.result', 'notify.send']
+]);
+
+function idempotentRequestFingerprint(payload = {}) {
+  const normalized = { ...(payload || {}) };
+  delete normalized.request_id;
+  delete normalized.requestId;
+  return stableStringify(normalized);
+}
+
 export class BridgeRuntime extends EventEmitter {
   constructor({
     baseWsUrl,
@@ -38,6 +64,8 @@ export class BridgeRuntime extends EventEmitter {
     this.reconnectMaxMs = reconnectMaxMs;
     this.enqueueIfDisconnected = enqueueIfDisconnected;
     this.maxQueueSize = maxQueueSize;
+    this.idempotentRetryWindowMs = 5 * 60 * 1000;
+    this.idempotentMaxCacheEntries = 1000;
 
     this.ws = null;
     this.connected = false;
@@ -46,6 +74,8 @@ export class BridgeRuntime extends EventEmitter {
     this.heartbeatTimer = null;
     this.pending = new Map();
     this.requestQueue = [];
+    this.idempotentRequestCache = new Map();
+    this.idempotentFingerprintByRequestId = new Map();
   }
 
   get wsUrl() {
@@ -89,8 +119,14 @@ export class BridgeRuntime extends EventEmitter {
   }
 
   async request(type, payload = {}) {
-    const requestId = makeRequestId();
-    const msg = { type, request_id: requestId, payload };
+    let requestId = makeRequestId();
+    let normalizedPayload = payload || {};
+    if (IDEMPOTENT_REQUEST_TYPES.has(type)) {
+      const resolved = this._resolveIdempotentRequest(type, normalizedPayload);
+      requestId = resolved.requestId;
+      normalizedPayload = resolved.payload;
+    }
+    const msg = { type, request_id: requestId, payload: normalizedPayload };
     const { promise, resolve, reject } = this._buildWaiter();
 
     if (!this.connected || !this.ws || this.ws.readyState !== WebSocket.OPEN) {
@@ -190,6 +226,7 @@ export class BridgeRuntime extends EventEmitter {
       const waiter = this.pending.get(requestId);
       this.pending.delete(requestId);
       clearTimeout(waiter.timer);
+      this._finalizeIdempotentRequest(msg, requestId);
       waiter.resolve(msg);
       return;
     }
@@ -251,4 +288,75 @@ export class BridgeRuntime extends EventEmitter {
       this._sendWithTimeout(item);
     }
   }
+
+  _resolveIdempotentRequest(type, payload = {}) {
+    this._cleanupIdempotentRequestCache();
+    const normalizedPayload = { ...(payload || {}) };
+    let requestId = String(
+      normalizedPayload.request_id || normalizedPayload.requestId || ''
+    ).trim();
+
+    if (!requestId) {
+      const fingerprint = idempotentRequestFingerprint(normalizedPayload);
+      const cacheKey = `${type}:${fingerprint}`;
+      const cached = this.idempotentRequestCache.get(cacheKey);
+      const now = Date.now();
+      if (cached && now - cached.ts <= this.idempotentRetryWindowMs) {
+        requestId = cached.requestId;
+      } else {
+        requestId = makeRequestId();
+        this.idempotentRequestCache.set(cacheKey, { requestId, ts: now });
+      }
+      this.idempotentFingerprintByRequestId.set(requestId, cacheKey);
+    }
+
+    normalizedPayload.request_id = requestId;
+    return { requestId, payload: normalizedPayload };
+  }
+
+  _cleanupIdempotentRequestCache(now = Date.now()) {
+    for (const [cacheKey, entry] of this.idempotentRequestCache.entries()) {
+      if (!entry || now - entry.ts > this.idempotentRetryWindowMs) {
+        this.idempotentRequestCache.delete(cacheKey);
+        if (entry?.requestId) {
+          this.idempotentFingerprintByRequestId.delete(entry.requestId);
+        }
+      }
+    }
+
+    if (this.idempotentRequestCache.size > this.idempotentMaxCacheEntries) {
+      const sorted = Array.from(this.idempotentRequestCache.entries()).sort(
+        (a, b) => (a[1]?.ts || 0) - (b[1]?.ts || 0)
+      );
+      const overflow = this.idempotentRequestCache.size - this.idempotentMaxCacheEntries;
+      for (let i = 0; i < overflow; i += 1) {
+        const [cacheKey, entry] = sorted[i] || [];
+        if (!cacheKey) continue;
+        this.idempotentRequestCache.delete(cacheKey);
+        if (entry?.requestId) {
+          this.idempotentFingerprintByRequestId.delete(entry.requestId);
+        }
+      }
+    }
+
+    for (const [requestId, cacheKey] of this.idempotentFingerprintByRequestId.entries()) {
+      if (!this.idempotentRequestCache.has(cacheKey)) {
+        this.idempotentFingerprintByRequestId.delete(requestId);
+      }
+    }
+  }
+
+  _finalizeIdempotentRequest(msg, requestId) {
+    const requestType = IDEMPOTENT_RESULT_TYPE_TO_REQUEST_TYPE.get(msg?.type);
+    if (!requestType) {
+      return;
+    }
+    const cacheKey = this.idempotentFingerprintByRequestId.get(requestId);
+    if (!cacheKey || !cacheKey.startsWith(`${requestType}:`)) {
+      return;
+    }
+    // 收到明确回包后结束本次重试窗口；仅“超时无回包”保留复用 request_id。
+    this.idempotentFingerprintByRequestId.delete(requestId);
+    this.idempotentRequestCache.delete(cacheKey);
+  }
 }