@qingtui/openclaw-plugin 0.0.0-stage → 1.1.0

package/dist/src/stream.js

@@ -0,0 +1,244 @@
+/**
+ * 分片节流间隔：onPartialReply 每个 token 都可能触发，每个分片是一次
+ * socket 往返，不节流会打爆代理；被跳过的内容由定时器/后续分片/收尾补齐。
+ */
+const STREAM_MIN_INTERVAL_MS = 700;
+/** 空闲保活间隔：须明显小于代理 30 秒空闲关流阈值 */
+const STREAM_KEEPALIVE_MS = 15_000;
+/** 思考过程与正文的分隔标题：轻推流式只能追加，思考过程会保留在正文上方 */
+const REASONING_HEADER = "【思考过程】\n";
+const ANSWER_HEADER = "\n\n【回答】\n";
+export class NudgeReplyStream {
+    ctx;
+    api;
+    logger;
+    tag;
+    minIntervalMs;
+    keepaliveMs;
+    /** 串行链：update/finish/abort/定时任务严格按序执行（增量分片必须有序） */
+    chain = Promise.resolve();
+    /** 首个非空增量前为 null（未开流） */
+    placeholder = null;
+    /** 已推送到轻推的累计文本（与最新快照比对得出增量） */
+    sentText = "";
+    /** 最新累计快照（节流跳过的部分由下一次 flush 补发） */
+    latestText = "";
+    /** 推理快照分段：每轮模型调用的推理各自累计，新一轮追加为新段 */
+    reasoningSegments = [];
+    /** 正文累计快照（不含思考过程） */
+    answerText = "";
+    lastSentAt = 0;
+    closed = false;
+    /** 流式链路失败后本回合不再尝试，调用方回退普通文本 */
+    failed = false;
+    timer = null;
+    constructor(options) {
+        this.ctx = options.ctx;
+        this.api = options.api;
+        this.logger = options.logger;
+        this.tag = options.ctx.accountId ? `[${options.ctx.accountId}]` : "";
+        this.minIntervalMs = options.minIntervalMs ?? STREAM_MIN_INTERVAL_MS;
+        this.keepaliveMs = options.keepaliveMs ?? STREAM_KEEPALIVE_MS;
+    }
+    /** onPartialReply：记录最新快照，按节流间隔推送 status=1 增量分片 */
+    update(fullText) {
+        return this.enqueue(async () => {
+            if (!this.isActive() || !fullText)
+                return;
+            this.answerText = fullText;
+            await this.pushLatest();
+        });
+    }
+    /**
+     * onReasoningStream：正文开始前把思考过程流式推送。正文开始后忽略，
+     * 否则插在正文前的内容会破坏"快照以已发文本为前缀"的增量换算。
+     */
+    updateReasoning(fullText) {
+        return this.enqueue(async () => {
+            if (!this.isActive() || !fullText || this.answerText)
+                return;
+            const last = this.reasoningSegments.length - 1;
+            if (last >= 0 && fullText.startsWith(this.reasoningSegments[last])) {
+                this.reasoningSegments[last] = fullText;
+            }
+            else {
+                this.reasoningSegments.push(fullText);
+            }
+            await this.pushLatest();
+        });
+    }
+    /** 重新拼接快照并按节流推送；已开流后的中间快照按间隔节流，首个分片不延迟 */
+    async pushLatest() {
+        this.latestText = this.composeText();
+        if (this.placeholder && Date.now() - this.lastSentAt < this.minIntervalMs) {
+            return;
+        }
+        await this.flushSafely(1, "流式分片推送失败");
+    }
+    composeText() {
+        if (!this.reasoningSegments.length)
+            return this.answerText;
+        const reasoning = REASONING_HEADER + this.reasoningSegments.join("\n\n");
+        return this.answerText
+            ? reasoning + ANSWER_HEADER + this.answerText
+            : reasoning;
+    }
+    /**
+     * final 回复收尾：补发剩余增量并以 status=2 结束流。
+     * 返回 false 表示本回合未真正开流、流式已失败，或已收尾后又收到内容
+     * 不同的 final，调用方应改走普通文本。
+     */
+    async finish(finalText) {
+        let handled = false;
+        await this.enqueue(async () => {
+            if (this.failed)
+                return;
+            if (this.closed) {
+                // 已收尾：仅吞掉与已推送内容相同的重复 final（或空收尾）；
+                // 内容不同的后续 final 是独立回复，返回 false 让调用方走普通文本
+                handled = !finalText || finalText === this.answerText;
+                return;
+            }
+            if (finalText) {
+                this.answerText = finalText;
+                this.latestText = this.composeText();
+            }
+            // 无任何增量（未开流），走普通文本
+            if (!this.placeholder)
+                return;
+            if (await this.flushSafely(2, "流式收尾失败")) {
+                this.close();
+                handled = true;
+            }
+        });
+        return handled;
+    }
+    /** 异常收尾（status=5，轻推客户端显示异常态）；未开流时为空操作 */
+    abort() {
+        return this.enqueue(async () => {
+            if (!this.isActive() || !this.placeholder) {
+                this.stopTimer();
+                return;
+            }
+            try {
+                await this.api.sendChunk({
+                    ctx: this.ctx,
+                    placeholder: this.placeholder,
+                    message: "",
+                    status: 5,
+                });
+            }
+            catch (err) {
+                this.logger?.warn(`openclaw-nudge${this.tag}: 流式异常收尾失败: ${String(err)}`);
+            }
+            this.close();
+        });
+    }
+    isActive() {
+        return !this.closed && !this.failed;
+    }
+    /** 执行 flush，失败时标记 failed；返回是否成功 */
+    async flushSafely(status, what) {
+        try {
+            await this.flush(status);
+            return true;
+        }
+        catch (err) {
+            this.failed = true;
+            this.stopTimer();
+            this.logger?.warn(`openclaw-nudge${this.tag}: ${what}，本回合回退普通文本: ${String(err)}`);
+            return false;
+        }
+    }
+    /**
+     * 把 sentText -> latestText 的增量发出去。
+     * status=1 且无增量时跳过；status=2 即使无增量也要发（关流信号）。
+     */
+    async flush(status) {
+        const delta = this.resolveDelta();
+        if (status === 1 && !delta)
+            return;
+        if (!this.placeholder) {
+            this.placeholder = await this.api.createPlaceholder(this.ctx);
+            this.logger?.info(`openclaw-nudge${this.tag}: 流式占位已创建 (msgId=${this.placeholder.msgId})`);
+            this.startTimer();
+        }
+        await this.sendChunk(delta, status);
+        this.sentText = this.latestText;
+    }
+    async sendChunk(message, status) {
+        if (!this.placeholder)
+            return;
+        await this.api.sendChunk({
+            ctx: this.ctx,
+            placeholder: this.placeholder,
+            message,
+            status,
+        });
+        this.lastSentAt = Date.now();
+    }
+    /**
+     * 定时任务：有被节流的尾部增量且已过节流间隔则补发；否则空闲超过保活
+     * 间隔时发空的 status=1 分片重置代理的空闲关流计时。
+     */
+    tick() {
+        return this.enqueue(async () => {
+            if (!this.isActive() || !this.placeholder)
+                return;
+            const idle = Date.now() - this.lastSentAt;
+            if (this.resolveDelta()) {
+                if (idle >= this.minIntervalMs) {
+                    await this.flushSafely(1, "流式分片推送失败");
+                }
+                return;
+            }
+            if (idle >= this.keepaliveMs) {
+                try {
+                    await this.sendChunk("", 1);
+                }
+                catch (err) {
+                    this.failed = true;
+                    this.stopTimer();
+                    this.logger?.warn(`openclaw-nudge${this.tag}: 流式保活失败，本回合回退普通文本: ${String(err)}`);
+                }
+            }
+        });
+    }
+    startTimer() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => {
+            void this.tick();
+        }, this.minIntervalMs);
+        // 不因流式定时器阻止进程退出
+        this.timer.unref?.();
+    }
+    stopTimer() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+    }
+    close() {
+        this.closed = true;
+        this.stopTimer();
+    }
+    /**
+     * 增量 = 最新快照去掉已发送前缀。快照被替换（非前缀延续，如
+     * onPartialReply 的 replace / 回复边界）时无法撤回已发内容，
+     * 以空行分隔追加整段新正文（思考过程只会前缀式增长，不重复追加）。
+     */
+    resolveDelta() {
+        if (this.latestText === this.sentText)
+            return "";
+        if (this.latestText.startsWith(this.sentText)) {
+            return this.latestText.slice(this.sentText.length);
+        }
+        return (this.sentText ? "\n\n" : "") + this.answerText;
+    }
+    /** 挂到串行链末尾；链上任务的异常已在任务内消化，不会中断后续任务 */
+    enqueue(task) {
+        const run = this.chain.then(task);
+        this.chain = run.then(() => undefined, () => undefined);
+        return run;
+    }
+}

package/dist/src/target.js

@@ -0,0 +1,35 @@
+/**
+ * 出站目标编解码。
+ *
+ * ChannelOutboundContext.to 不携带会话类型，轻推单聊/群聊的发送接口又不同
+ * （single 用 to_user，channel 用 channel_id），因此在会话标识里编码前缀。
+ * 入站（inbound.ts）构造回复目标时用 encodeNudgeTarget，出站发送前解码。
+ */
+const USER_TARGET_PREFIX = "user:";
+const CHANNEL_TARGET_PREFIX = "channel:";
+export function encodeNudgeTarget(chatType, id) {
+    return chatType === "group"
+        ? `${CHANNEL_TARGET_PREFIX}${id}`
+        : `${USER_TARGET_PREFIX}${id}`;
+}
+/** 解码出站目标；缺少 user:/channel: 前缀或 id 为空时抛错（不猜测会话类型） */
+export function decodeNudgeTarget(to) {
+    const decoded = to.startsWith(CHANNEL_TARGET_PREFIX)
+        ? { sendType: "channel", id: to.slice(CHANNEL_TARGET_PREFIX.length) }
+        : to.startsWith(USER_TARGET_PREFIX)
+            ? { sendType: "single", id: to.slice(USER_TARGET_PREFIX.length) }
+            : null;
+    if (!decoded?.id) {
+        throw new Error(`openclaw-nudge: 无法解码出站目标 "${to}"（缺少 user:/channel: 前缀）`);
+    }
+    return decoded;
+}
+/**
+ * 按目标类型组装消息体：单聊放 to_user，群聊放 channel_id。
+ * 文本、引用、图片、文件消息共用这一外层结构，只是内层 message 不同。
+ */
+export function buildTargetedMessage(target, message) {
+    return target.sendType === "channel"
+        ? { channel_id: target.id, message }
+        : { to_user: target.id, message };
+}

package/openclaw.plugin.json

@@ -0,0 +1,72 @@
+{
+	"version": "1.1.0",
+	"id": "openclaw-nudge",
+	"name": "Openclaw Nudge",
+	"description": "connect nudge to OpenClaw",
+	"channels": ["qingtui"],
+	"configSchema": {
+		"type": "object",
+		"properties": {},
+		"additionalProperties": false
+	},
+	"channelConfigs": {
+		"qingtui": {
+			"schema": {
+				"type": "object",
+				"additionalProperties": false,
+				"properties": {
+					"enabled": {
+						"type": "boolean"
+					},
+					"streaming": {
+						"type": "boolean"
+					},
+					"serverUrl": {
+						"type": "string"
+					},
+					"openUrl": {
+						"type": "string"
+					},
+					"accounts": {
+						"type": "object",
+						"additionalProperties": {
+							"type": "object",
+							"additionalProperties": false,
+							"properties": {
+								"enabled": {
+									"type": "boolean"
+								},
+								"name": {
+									"type": "string"
+								},
+								"appid": {
+									"type": "string"
+								},
+								"appsecret": {
+									"type": "string"
+								}
+							}
+						}
+					}
+				}
+			},
+			"uiHints": {
+				"serverUrl": {
+					"label": "轻推服务地址",
+					"help": "Socket 代理地址，缺省 https://open.qingtui.com；QA 为 https://qaqtopen.qingtui.com"
+				},
+				"openUrl": {
+					"label": "开放平台 REST 地址",
+					"help": "缺省与轻推服务地址相同"
+				},
+				"accounts.*.appid": {
+					"label": "应用ID"
+				},
+				"accounts.*.appsecret": {
+					"label": "应用密钥",
+					"sensitive": true
+				}
+			}
+		}
+	}
+}

package/package.json

@@ -1,6 +1,52 @@
 {
-  "name": "@qingtui/openclaw-plugin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@qingtui/openclaw-plugin",
+	"version": "1.1.0",
+	"type": "module",
+	"scripts": {
+		"format": "biome format --write",
+		"lint": "biome check .",
+		"build": "tsc -p tsconfig.json",
+		"test": "tsc -p tsconfig.test.json && node --test \".test-dist/test/**/*.test.js\"",
+		"package": "pnpm run build && pnpm pack --out qingtui-openclaw-plugin-%v.tgz",
+		"link": "openclaw plugins install --link ./",
+		"plugin:build": "pnpm run build && openclaw plugins build --entry ./dist/index.js",
+		"plugin:validate": "pnpm run build && openclaw plugins validate --entry ./dist/index.js",
+		"plugin:install": "pnpm run package && openclaw plugins install npm-pack:./qingtui-openclaw-plugin-$npm_package_version.tgz --force",
+		"plugin:publish": "clawhub package publish . --source-repo cisdi/openclaw-nudge --source-commit $(git rev-parse HEAD)"
+	},
+	"files": [
+		"dist",
+		"openclaw.plugin.json"
+	],
+	"dependencies": {
+		"@qingtui/socket-sdk": "1.1.0",
+		"typebox": "1.3.37"
+	},
+	"peerDependencies": {
+		"openclaw": ">=2026.10.8"
+	},
+	"openclaw": {
+		"extensions": [
+			"./dist/index.js"
+		],
+		"setupEntry": "./dist/setup-entry.js",
+		"channel": {
+			"id": "qingtui",
+			"label": "qingtui (轻推)",
+			"blurb": "connect qingtui to OpenClaw"
+		},
+		"compat": {
+			"pluginApi": ">=2026.10.8",
+			"minGatewayVersion": "2026.10.8"
+		},
+		"build": {
+			"openclawVersion": "2026.10.8",
+			"pluginSdkVersion": "2026.10.8"
+		}
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.5.15",
+		"openclaw": "2026.10.8",
+		"typescript": "7.0.2"
+	}
+}