@qingtui/openclaw-plugin 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# OpenClaw 轻推渠道插件
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+将轻推（Qingtui / Nudge）机器人接入 OpenClaw，支持私聊、群聊、多机器人、动态白名单、文本与媒体发送、流式回复。入站通过 Socket 长连接接收，不需要部署 HTTP webhook。
+
+## 文档导航
+
+- [开发指南](docs/开发指南.md)：依赖与工具版本、源码结构、构建、本地链接开发、现有脚本的适用范围。
+- [调试指南](docs/调试指南.md)：隔离环境冒烟、运行日志、真实消息验收、连接与权限故障定位。
+- [发布指南](docs/发布指南.md)：版本同步、打包检查、安装验收、npm / ClawHub 发布、升级与回滚。
+
+文档以仓库的 `package.json`、`pnpm-lock.yaml`、`pnpm-workspace.yaml`、`tsconfig.json`、`openclaw.plugin.json` 和当前源码为准。
+
+## 三个名称不要混用
+
+| 用途 | 标识 | 使用位置 |
+| --- | --- | --- |
+| npm 包名 | `@qingtui/openclaw-plugin` | 安装依赖、npm 发布 |
+| 插件 ID | `openclaw-nudge` | `openclaw plugins inspect/enable`、`plugins.entries` |
+| 渠道 ID | `qingtui` | `channels.qingtui`、机器人账号配置 |
+
+## 从源码开始
+
+要求 OpenClaw `>=2026.10.8`；本项目按 `2026.10.8` 构建。该宿主要求 Node.js `>=24.22.1 <25 || >=26.12.1`。依赖版本和 pnpm 使用说明见[开发指南](docs/开发指南.md#环境与依赖基线)。
+
+在仓库根目录安装并构建：
+
+```bash
+pnpm install --frozen-lockfile
+pnpm run build
+```
+
+准备**安装在本仓库之外**的 OpenClaw 宿主，并确认当前 shell 的 `openclaw` 指向它。接下来的命令会修改当前 OpenClaw 配置；仅验证加载时，请改用[隔离调试流程](docs/调试指南.md)。
+
+```bash
+command -v openclaw
+openclaw --version
+openclaw plugins install --link .
+openclaw plugins inspect openclaw-nudge --json
+```
+
+`--link` 只登记路径，不复制文件；不能与 `--force` 同用。若安装策略阻止操作，先审查提示与宿主策略，不要绕过安全检查。需要启用插件或确认其声明能力时，先审查插件，再手动执行：
+
+```bash
+openclaw plugins enable openclaw-nudge --accept-capabilities
+```
+
+发布入口是 `dist/index.js`，配置向导入口是 `dist/setup-entry.js`。修改源码后需要重新 `pnpm run build`，再用外部宿主执行 `openclaw gateway restart`。不要用本仓库的 `pnpm exec openclaw gateway run` 加载本仓库：OpenClaw `2026.10.x` 在这种目录布局下存在源码捕获问题，详见调试指南。
+
+## 配置机器人
+
+推荐交互配置，避免把密钥写进 shell 历史：
+
+```bash
+openclaw channels add
+```
+
+在向导中选择轻推渠道，选择或新建账号，依次输入 `appid`、`appsecret` 和轻推服务地址（缺省 `https://open.qingtui.com`，QA 环境填 `https://qaqtopen.qingtui.com`）。录入后回到渠道列表，必须选择 **Finished** 并继续到 **Channels updated.** 才会保存；中途取消不会写盘。外部渠道不要使用 `channels add --channel qingtui`。
+
+`appsecret` 以掩码方式录入，重跑向导时只询问是否保留、不回显已存密钥。`appid` 仍为明文输入。
+
+配置位于默认的 `~/.openclaw/openclaw.json`，也可由 `OPENCLAW_CONFIG_PATH` 指定。以下仅展示需要合并到现有配置的分节，不能用它覆盖整个配置文件；占位值必须换成真实凭证：
+
+```json5
+{
+  channels: {
+    qingtui: {
+      streaming: true,
+      serverUrl: "https://open.qingtui.com",
+      accounts: {
+        default: {
+          enabled: true,
+          appid: "替换为机器人ID",
+          appsecret: "替换为机器人密钥",
+        },
+        // 多机器人时继续增加账号，例如 bot2: { appid: "...", appsecret: "..." }
+      },
+    },
+  },
+}
+```
+
+- `appid` / `appsecret` 必须是字符串，且只能位于 `accounts.<账号ID>`，包括 `accounts.default`；不能放到渠道顶层。
+- `streaming` 缺省开启，设为 `false` 使用普通回复。
+- `serverUrl` 是轻推服务（Socket 代理）地址，缺省 `https://open.qingtui.com`；QA 环境为 `https://qaqtopen.qingtui.com`。所有账号共用。
+- `openUrl` 是 token、白名单、媒体上传等 **REST API** 的基地址，可选；未配置时与 `serverUrl` 相同，只有两者不同域时才需要单独设置。
+- **从 1.0.x 升级**：旧版 Socket 固定连 QA（`qaqtopen`），新版缺省连生产。仍要连 QA 时需显式设置 `serverUrl: "https://qaqtopen.qingtui.com"`。
+- 私聊与群聊都使用轻推平台同步的同一份动态白名单，按机器人账号隔离；没有可配置的 `dmPolicy`、`groupPolicy`、`allowFrom` 或 `groupAllowFrom`。
+- 临时禁用某个机器人时设置 `accounts.<账号ID>.enabled: false`；禁用整个渠道时设置 `channels.qingtui.enabled: false`。两者都需要重启网关后生效。
+
+保存后验证并重启：
+
+```bash
+openclaw config validate
+openclaw gateway restart
+openclaw plugins inspect openclaw-nudge --runtime --json
+openclaw gateway health
+```
+
+`inspect` 成功只证明插件能加载；`health` 中的 `qingtui: not-running` 也不能直接判定 Socket 故障。真实账号应结合“socket 认证成功”“已连接轻推消息代理”“动态白名单已同步”日志，并实际收发一条消息验收，详见[调试指南](docs/调试指南.md)。

package/dist/index.js

@@ -0,0 +1,65 @@
+/**
+ * openclaw-nudge —— OpenClaw 外部渠道插件：把「轻推」（nudge）接入 OpenClaw。
+ *
+ * 【给不熟悉 OpenClaw 的读者】渠道插件 = 一组约定的导出，告诉 OpenClaw：
+ *   1. 渠道怎么配置（配置在 ~/.openclaw/openclaw.json 的
+ *      channels["qingtui"] 里；一个账号 = 一个轻推机器人）
+ *   2. 消息怎么进来（本插件用 WebSocket 长连接，轻推服务器主动推送，
+ *      不暴露 HTTP webhook，无需公网地址）
+ *   3. OpenClaw 的回复怎么发回去（outbound）
+ *
+ * 文件导览（建议阅读顺序）：
+ *   src/config.ts       配置长什么样、怎么读（账号/凭证/服务地址模型）
+ *   src/setup-wizard.ts 交互式配置向导（openclaw channels add 的提问流程）
+ *   src/channel.ts      渠道插件组装：能力声明、私聊安全策略、出站发送
+ *   src/client.ts       轻推连接层：WebSocket 连接池、动态白名单缓存、发送 API
+ *   src/service.ts      后台服务：逐账号建连、定时同步白名单
+ *   src/event.ts        推送负载归一化与按账号去重
+ *   src/inbound.ts      入站流水线：推送如何变成 agent 的一轮对话
+ *   src/stream.ts       单聊流式回复：快照转增量、节流、保活与收尾
+ *   src/target.ts       出站目标 user:/channel: 编解码
+ *
+ * 消息流向：
+ *   入站  轻推服务器 --WebSocket--> service.ts --> inbound.ts --> OpenClaw agent
+ *   出站  agent 回复 --> channel.ts(outbound) --> client.ts --> 轻推服务器
+ *
+ * 本文件只做三件事：setRuntime 把 PluginRuntime 句柄存入 runtime store（入站派发要用）、
+ * registerCliMetadata 注册 CLI 帮助描述、registerFull 注册后台 service
+ * （实现在 src/service.ts）。
+ */
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/core";
+import { createPluginRuntimeStore, } from "openclaw/plugin-sdk/runtime-store";
+import { nudgeChatPlugin } from "./src/channel.js";
+import { createNudgeInboundService } from "./src/service.js";
+// 宿主运行时句柄：按插件 ID 存在全局命名槽位，SDK 模块被重复加载时也共享同一份
+const runtimeStore = createPluginRuntimeStore({
+    pluginId: "openclaw-nudge",
+    errorMessage: "openclaw-nudge: plugin runtime is not initialized",
+});
+export default defineChannelPluginEntry({
+    id: "openclaw-nudge",
+    name: "Openclaw Nudge",
+    description: "connect nudge to OpenClaw",
+    plugin: nudgeChatPlugin,
+    setRuntime: runtimeStore.setRuntime,
+    registerCliMetadata(api) {
+        api.registerCli(({ program }) => {
+            program.command("openclaw-nudge").description("Nudge Chat management");
+        }, {
+            descriptors: [
+                {
+                    name: "openclaw-nudge",
+                    description: "Nudge Chat management",
+                    hasSubcommands: false,
+                },
+            ],
+        });
+    },
+    registerFull(api) {
+        // registerFull 在 "tool-discovery" 模式也会被调用，只有 full 模式
+        // 才允许建长连接这类重副作用（docs/plugins/sdk-entrypoints.md）。
+        if (api.registrationMode !== "full")
+            return;
+        api.registerService(createNudgeInboundService(() => runtimeStore.tryGetRuntime()));
+    },
+});

package/dist/setup-entry.js

@@ -0,0 +1,5 @@
+import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
+// setup-only 入口：`openclaw channels add` 等配置类命令只加载本文件
+// （不建连、不起 service）；package.json 的 openclaw.setupEntry 指向这里。
+import { nudgeChatPlugin } from "./src/channel.js";
+export default defineSetupPluginEntry(nudgeChatPlugin);

package/dist/src/channel.js

@@ -0,0 +1,112 @@
+/**
+ * 渠道插件组装：把配置、向导、安全策略、出站发送拼成 OpenClaw 渠道插件对象。
+ *
+ * 【新手须知】createChatChannelPlugin 是 OpenClaw 聊天渠道的标准工厂：
+ *   base.meta         渠道在 CLI/UI 里的展示信息
+ *   base.setupWizard  交互式配置向导（实现在 src/setup-wizard.ts）
+ *   base.capabilities 支持的会话类型（direct 单聊 / group 群聊）
+ *   base.config       账号枚举与解析（实现在 src/config.ts）
+ *   base.setup        onboarding 时的账号命名/写盘回调
+ *   security.dm       私聊准入：固定 allowlist，白名单 = 轻推服务器同步的
+ *                     运行时缓存（src/client.ts），无静态配置项、不走 pairing
+ *   threading         回复引用模式
+ *   outbound          出站：agent 回复经 src/client.ts 的 nudgeChatApi 发回轻推
+ */
+import { createChatChannelPlugin } from "openclaw/plugin-sdk/channel-core";
+import { applyAccountNameToChannelSection } from "openclaw/plugin-sdk/setup";
+import { getDynamicAllowFrom, nudgeChatApi } from "./client.js";
+import { isNudgeAccountConfigured, isNudgeChannelEnabled, listNudgeAccountIds, NUDGE_CHANNEL_ID, patchNudgeAccountConfig, resolveAccount, resolveDefaultNudgeAccountId, } from "./config.js";
+import { nudgeSetupWizard } from "./setup-wizard.js";
+export const nudgeChatPlugin = createChatChannelPlugin({
+    // 注意：不用 createChannelPluginBase —— 它把 capabilities 标成可选，
+    // 而 createChatChannelPlugin 要求必填，直接过类型检查会报
+    // TS2322（SDK 声明缺陷）。内置渠道同样直接传对象字面量。
+    base: {
+        id: NUDGE_CHANNEL_ID,
+        // 外部插件不在内置渠道目录里，meta 必须显式给全
+        // （resolveSdkChatChannelMeta 只认 bundled channel id）。
+        meta: {
+            id: NUDGE_CHANNEL_ID,
+            label: "qingtui",
+            selectionLabel: "qingtui (轻推)",
+            docsPath: "/channels/qingtui",
+            blurb: "connect qingtui to OpenClaw",
+        },
+        setupWizard: nudgeSetupWizard,
+        capabilities: { chatTypes: ["direct", "group"] },
+        // 账号解析/检查放 config，不放 setup（setup 只管 onboarding 写回）
+        config: {
+            listAccountIds: listNudgeAccountIds,
+            defaultAccountId: resolveDefaultNudgeAccountId,
+            resolveAccount,
+            inspectAccount(cfg, accountId) {
+                const configured = isNudgeAccountConfigured(cfg, accountId);
+                return {
+                    // 渠道总开关关闭时 service 不建连，账号视为未启用
+                    enabled: configured && isNudgeChannelEnabled(cfg),
+                    configured,
+                    tokenStatus: configured ? "available" : "missing",
+                };
+            },
+        },
+        setup: {
+            applyAccountName: ({ cfg, accountId, name }) => applyAccountNameToChannelSection({
+                cfg,
+                channelKey: NUDGE_CHANNEL_ID,
+                accountId,
+                name,
+                alwaysUseAccounts: true,
+            }),
+            applyAccountConfig: ({ cfg, accountId, input }) => patchNudgeAccountConfig({ cfg, accountId, patch: input }),
+        },
+    },
+    // DM 安全：固定 allowlist（白名单来自开放平台可见范围同步，不走 pairing）
+    security: {
+        dm: {
+            channelKey: NUDGE_CHANNEL_ID,
+            resolvePolicy: () => "allowlist",
+            // 生效白名单由 service 按账号后台定时刷新，见 client.ts getDynamicAllowFrom
+            resolveAllowFrom: (account) => [
+                ...getDynamicAllowFrom(account.accountId),
+            ],
+        },
+    },
+    // 回复携带 replyToId；群聊引用消息由 nudgeChatApi.sendMessage 按
+    // sendType 升级为 type="ref"，单聊忽略 replyToId 发普通文本
+    threading: { topLevelReplyToMode: "reply" },
+    // 出站：OpenClaw 回复 -> nudge
+    outbound: {
+        attachedResults: {
+            channel: NUDGE_CHANNEL_ID,
+            sendText: async (ctx) => {
+                const result = await nudgeChatApi.sendMessage({
+                    accountId: ctx.accountId,
+                    to: ctx.to,
+                    text: ctx.text,
+                    replyToId: ctx.replyToId,
+                });
+                return { messageId: result.id, chatId: result.chatId };
+            },
+            // 媒体读取交给宿主加载器并带上宿主授予的读取能力：远程 URL 受
+            // SSRF 策略约束，本地路径只允许授权根目录
+            sendMedia: async (ctx) => {
+                const result = await nudgeChatApi.sendFile({
+                    accountId: ctx.accountId,
+                    to: ctx.to,
+                    mediaUrl: ctx.mediaUrl ?? "",
+                    text: ctx.text,
+                    mediaAccess: {
+                        localRoots: ctx.mediaAccess?.localRoots ?? ctx.mediaLocalRoots,
+                        readFile: ctx.mediaAccess?.readFile ?? ctx.mediaReadFile,
+                        workspaceDir: ctx.mediaAccess?.workspaceDir,
+                    },
+                });
+                return { messageId: result.id, chatId: result.chatId };
+            },
+        },
+        // base 里放通用出站策略；deliveryMode 是必填项
+        base: {
+            deliveryMode: "direct",
+        },
+    },
+});