@youdu/openclaw-youdu 2026.7.3 → 2026.9.15

package/README.md

@@ -2,6 +2,10 @@
 
 有度机器人接入插件，基于 WebSocket 长连接实现消息收发。
 
+知识库 Tool 需要 OpenClaw `2026.7.1-2` 或更高版本；旧版本不提供本插件所需的 Tool hook 参数调整能力。可信有度 IM 上下文由插件按 OpenClaw `runId` 短期保存，并在本轮 dispatch 结束时清理；插件不会在注册结束后调用注册期 API。
+
+安全边界：知识库调用的短期 `invocationToken` 只由插件 hook 注入并一次性消费，不进入 CLI 请求、stdin、Tool 返回值或插件日志。OpenClaw `2026.7.1-2` 会在进程内保存调整后的参数，并将其提供给 `after_tool_call`；同时完整调整参数可能出现在宿主受控的 private diagnostic payload 和 loop-tracking 内存中。该 token 不写入模型会话 transcript，也不作为模型工具 schema 字段。宿主诊断的可见范围由 OpenClaw 控制，部署时应按受控诊断数据处理。
+
 ## 功能特性
 
 - 🔗 WebSocket 长连接 — 基于 wss 建立持久连接（可通过配置自定义）
@@ -54,9 +58,99 @@ openclaw gateway restart
 | `channels.youdu.botId`          | 有度机器人 ID  | —                                     | —       |
 | `channels.youdu.secret`         | 有度机器人密钥 | —                                     | —       |
 | `channels.youdu.enabled`        | 启用频道       | true / false                          | false   |
-| `channels.youdu.websocketUrl`   | WebSocket 地址 | —                                     | —       |
+| `channels.youdu.url`            | 有度服务器地址（纯主机名） | —                       | —       |
 | `channels.youdu.dmPolicy`       | 私聊访问策略   | pairing / open / allowlist / disabled | pairing |
 | `channels.youdu.allowFrom`      | 私聊允许列表   | —                                     | []      |
+| `channels.youdu.groups.<群ID>.requireMention` | 该群是否必须 @ 机器人 | true / false         | true    |
+| `channels.youdu.groups."*".requireMention`    | 所有群的默认 @ 要求   | true / false         | true    |
+| `channels.youdu.historyLimit`   | 未被 @ 的群消息保留条数（作为下次被 @ 时的上下文） | 数字，0 表示关闭 | 50 |
+| `channels.youdu.defaultAccount` | 默认账号 ID    | 任意账号 ID                            | —       |
+| `channels.youdu.accounts`       | 多账号配置     | 账号 ID → 账号级字段的映射            | —       |
+
+### 群聊 @ 回复（默认）
+
+从本版本起，**群聊里只有 @ 了机器人的消息才会触发回复**。行为对齐 OpenClaw 其它渠道的 mention gating：
+
+- 判定依据是有度回调 `raw.decoded.atUser` 是否包含机器人自身的用户 ID（`gid`，来自认证应答）；
+  配置文件里的 `mentionPatterns` 同样计入。斜杠命令（`/new`、`/status` 等）不受 @ 限制，
+  仍按现有命令权限执行。
+- 送进模型前会剥掉消息里的 `@账号(显示名)` 包装，避免模型看到 @ 前缀。
+- **未被 @ 的消息不会进入会话**：不研究、不下载附件、不发"思考中"占位消息。它们只按群进入一个
+  **内存中的 pending 窗口**（默认每个群保留最近 50 条，`channels.youdu.historyLimit` 可调，`0` 关闭；
+  窗口在每次回复结束、以及进程重启后清空）。下一次被 @ 时，这些消息会以
+  `[Chat messages since your last reply - for context]` 的形式随当次请求一起注入，让机器人知道群里刚才说了什么。
+- 判定能力缺失时（认证应答没有 `gid`，也没有配置 `mentionPatterns`）**宁可不回**：会记录一条错误日志并丢弃
+  该消息，而不会退化成"群里全回"。
+- 想让某个群恢复"全部回复"，在该群配置里显式关闭即可：
+
+  ```bash
+  openclaw config set channels.youdu.groups.'{0798E01E-CD68-42BB-813C-EB51593BB0F5}'.requireMention false
+  ```
+
+- 群访问仍然先由 `channels.youdu.groupPolicy`（open / allowlist / disabled）控制，@ 判定在其后。
+
+### 多账号配置
+
+插件支持配置多个有度机器人账号，每个账号可拥有独立的凭据和访问策略；账号级字段会覆盖顶层默认值。
+
+**CLI 配置示例：**
+
+```bash
+openclaw config set channels.youdu.accounts.bot-one.botId "<BOT_ID_1>"
+openclaw config set channels.youdu.accounts.bot-one.secret "<BOT_SECRET_1>"
+openclaw config set channels.youdu.accounts.bot-one.url "<HOST_1>"
+
+openclaw config set channels.youdu.accounts.bot-two.botId "<BOT_ID_2>"
+openclaw config set channels.youdu.accounts.bot-two.secret "<BOT_SECRET_2>"
+openclaw config set channels.youdu.accounts.bot-two.url "<HOST_2>"
+
+# 指定默认账号
+openclaw config set channels.youdu.defaultAccount bot-one
+
+openclaw gateway restart
+```
+
+**等效的配置文件写法：**
+
+```json
+{
+  "channels": {
+    "youdu": {
+      "enabled": true,
+      "dmPolicy": "pairing",
+      "defaultAccount": "bot-one",
+      "accounts": {
+        "bot-one": {
+          "botId": "<BOT_ID_1>",
+          "secret": "<BOT_SECRET_1>",
+          "url": "<HOST_1>"
+        },
+        "bot-two": {
+          "botId": "<BOT_ID_2>",
+          "secret": "<BOT_SECRET_2>",
+          "url": "<HOST_2>"
+        }
+      }
+    }
+  }
+}
+```
+
+**规则说明：**
+
+- `url` 只填主机名（如 `youdu.example.com`），不要带 `https://` 协议前缀或端口
+- 顶层字段作为默认值：账号级未配置的字段（如 `dmPolicy`、`allowFrom`、`groupPolicy`）会继承顶层值
+- `defaultAccount` 指定默认账号；未指定时优先使用 `default` 账号，否则取第一个账号
+- 若顶层同时配置了 `botId`/`secret`/`url`，顶层凭据会作为一个独立的 `default` 账号保留（除非某个命名账号的 botId 与之重复）
+- 账号级可用字段与顶层一致：`botId`、`secret`、`url`、`enabled`、`name`、`dmPolicy`、`allowFrom`、`groupPolicy`、`groupAllowFrom`、`sendThinkingMessage`、`mediaMaxMb`、`mediaLocalRoots`
+- 查看多账号运行状态：`openclaw channels status youdu`
+- 仅配置顶层凭据（不配置 `accounts`）时行为与之前完全一致，即为单账号模式
+
+### 知识库工具授权
+
+OpenClaw 的 `coding` 工具 profile 默认不包含插件工具。有度频道的 `botId`、`secret` 和 Host 配置完整后，插件会在 Gateway 启动或配置热加载时，将精确工具名 `youdu_kb` 追加到 `tools.alsoAllow`。有度 Channel 会在当前运行配置确认包含该授权后才建立连接；首次补齐配置时，本轮启动等待 OpenClaw 自动热加载或重启后再连接，因此首条有度消息不会早于工具授权。
+
+插件不会添加 `group:plugins`，也不会修改 `tools.profile`、`tools.allow`、`tools.deny` 或其他工具策略。`youdu_kb` 只在有度 IM 会话中挂载；它在 webchat 等其他频道不可见属于预期行为。用户额外配置的 agent、provider、sandbox 或 deny 策略仍可能进一步过滤该工具。
 
 ## 使用
 
@@ -71,6 +165,41 @@ openclaw status
 openclaw channels status youdu
 ```
 
+## 主动发送（Outbound）
+
+机器人可以在没有人先说话的情况下主动发消息（定时任务、告警、后台任务结果）：
+
+```bash
+# 私聊：数字 userId 直接可用（有度单聊的 chatId 就是对方 userId）
+openclaw message send --channel youdu --to 6463894 --message "早上好"
+
+# 私聊：用账号名（需该账号先私聊过机器人，插件会记住映射）
+openclaw message send --channel youdu --to lewis.liu --message "早上好"
+
+# 群聊：直接填群 ID，或显式声明类型
+openclaw message send --channel youdu --to "group:{0798E01E-CD68-42BB-813C-EB51593BB0F5}" --message "群公告"
+```
+
+目标解析顺序（`src/message-sender.ts` 的 `resolveOutboundTarget`）：
+
+1. 去掉 `youdu:` 前缀，以及可选的显式类型前缀 `group:` / `user:`（`single:` 亦可）；
+2. 已学到的私聊账号名 → 该账号的 chatId（单聊）；
+3. 已学到的群 ID，或形如 `{GUID}` 的群 ID → 群聊；
+4. 纯数字 → 单聊；
+5. 其余报错，并提示可用写法。
+
+学习与持久化（`src/target-store.ts`）：
+
+- 收到私聊消息时记录 `账号名 → chatId` 与昵称，收到群消息时记录群 ID；
+- 记录写入 `~/.openclaw/youdu-targets.json`（权限 0600、先写临时文件再 rename、变更后去抖落盘），
+  **进程重启后仍然可用**；
+- 账号从配置中移除时会一并清掉该账号的目标；
+- `openclaw channels directory youdu`（`directory.listPeers` / `listGroups`）会列出这些已聊过的联系人与群，
+  方便确认可投递目标；有度回调不下发群名，因此群只显示 ID。
+
+> 注意：`send_msg` 必须带 `chatType`（`single`/`group`）。有度服务端只在 `chatType === 'group'`
+> 时按群会话投递，其余值一律按单聊处理，漏传会把群 ID 当成用户 ID 发成私聊。
+
 ## 消息处理流程
 
 1. 插件通过 WebSocket 连接到有度服务

package/dist/index.esm.js

@@ -1,7 +1,10 @@
-import { youduPlugin } from './src/channel.js';
+import { createYouDuPlugin } from './src/channel.js';
 import { emptyPluginConfigSchema } from './src/openclaw-compat.js';
 import { setYouDuRuntime } from './src/runtime.js';
 import { CHANNEL_ID } from './src/const.js';
+import { youduKbToolFactory } from './src/kb/tool.js';
+import { registerYouDuKbRunContext } from './src/kb/run-context.js';
+import { createYouDuKbToolPolicy } from './src/kb/tool-policy.js';
 
 /**
  * YouDu OpenClaw Plugin - 主入口
@@ -16,7 +19,10 @@ const plugin = {
     configSchema: emptyPluginConfigSchema(),
     register(api) {
         setYouDuRuntime(api.runtime);
-        api.registerChannel({ plugin: youduPlugin });
+        registerYouDuKbRunContext(api);
+        const toolPolicy = createYouDuKbToolPolicy(api);
+        api.registerChannel({ plugin: createYouDuPlugin(toolPolicy) });
+        api.registerTool(youduKbToolFactory, { name: "youdu_kb", optional: false });
         /** 有度频道系统指令 — 条件→动作格式，便于 LLM 精确遵循 */
         const YOUDU_SYSTEM_CONTEXT_HINTS = [
             "## 有度频道输出约束",

package/dist/src/channel.d.ts

@@ -1,3 +1,20 @@
 import { type ChannelPlugin } from "openclaw/plugin-sdk/core";
+import { monitorYouDuProvider } from './monitor.js';
 import { type ResolvedYouDuAccount } from './utils.js';
-export declare const youduPlugin: ChannelPlugin<ResolvedYouDuAccount>;
+import type { YouDuKbToolPolicy } from "./kb/tool-policy.js";
+import type { WsConnectionSnapshot } from "./sdk/types.js";
+export type YouDuProbeResult = WsConnectionSnapshot & {
+    ok: boolean;
+    status: number;
+    error?: string;
+};
+export type YouDuChannelLifecycleEvent = {
+    type: "gate-start" | "gate-result" | "gate-wait-start" | "gate-wait-abort" | "monitor-start" | "monitor-abort";
+    attemptId: string;
+    result?: Awaited<ReturnType<YouDuKbToolPolicy["ensureYouDuKbToolPolicy"]>>;
+    authorized: boolean;
+    profile?: string;
+};
+export type YouDuChannelLifecycleObserver = (event: YouDuChannelLifecycleEvent) => void | Promise<void>;
+export declare function createYouDuPlugin(policy?: YouDuKbToolPolicy, monitor?: typeof monitorYouDuProvider, lifecycleObserver?: YouDuChannelLifecycleObserver): ChannelPlugin<ResolvedYouDuAccount, YouDuProbeResult>;
+export declare const youduPlugin: ChannelPlugin<ResolvedYouDuAccount, YouDuProbeResult>;