@xuanyue202/qqbot 2026.3.21

package/openclaw.plugin.json

@@ -0,0 +1,137 @@
+{
+  "id": "qqbot",
+  "name": "QQ Bot",
+  "description": "QQ 开放平台机器人消息渠道插件",
+  "version": "0.1.0",
+  "channels": ["qqbot"],
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "enabled": { "type": "boolean" },
+      "name": { "type": "string" },
+      "defaultAccount": { "type": "string" },
+      "appId": { "type": ["string", "number"] },
+      "clientSecret": { "type": "string" },
+      "displayAliases": {
+        "type": "object",
+        "additionalProperties": { "type": "string" }
+      },
+      "asr": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "appId": { "type": ["string", "number"] },
+          "secretId": { "type": "string" },
+          "secretKey": { "type": "string" }
+        }
+      },
+      "markdownSupport": { "type": "boolean" },
+      "c2cMarkdownDeliveryMode": {
+        "type": "string",
+        "enum": ["passive", "proactive-table-only", "proactive-all"]
+      },
+      "c2cMarkdownChunkStrategy": {
+        "type": "string",
+        "enum": ["markdown-block", "length"]
+      },
+      "typingHeartbeatMode": {
+        "type": "string",
+        "enum": ["none", "idle", "always"]
+      },
+      "typingHeartbeatIntervalMs": { "type": "integer", "minimum": 1 },
+      "typingInputSeconds": { "type": "integer", "minimum": 1 },
+      "dmPolicy": { "type": "string", "enum": ["open", "pairing", "allowlist"] },
+      "groupPolicy": { "type": "string", "enum": ["open", "allowlist", "disabled"] },
+      "requireMention": { "type": "boolean" },
+      "allowFrom": { "type": "array", "items": { "type": "string" } },
+      "groupAllowFrom": { "type": "array", "items": { "type": "string" } },
+      "historyLimit": { "type": "integer", "minimum": 0 },
+      "textChunkLimit": { "type": "integer", "minimum": 1 },
+      "replyFinalOnly": { "type": "boolean" },
+      "longTaskNoticeDelayMs": { "type": "integer", "minimum": 0 },
+      "maxFileSizeMB": { "type": "number", "exclusiveMinimum": 0 },
+      "mediaTimeoutMs": { "type": "integer", "minimum": 1 },
+      "autoSendLocalPathMedia": { "type": "boolean" },
+      "inboundMedia": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "dir": { "type": "string" },
+          "keepDays": { "type": "number", "minimum": 0 }
+        }
+      },
+      "accounts": {
+        "type": "object",
+        "additionalProperties": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "name": { "type": "string" },
+            "enabled": { "type": "boolean" },
+            "appId": { "type": ["string", "number"] },
+            "clientSecret": { "type": "string" },
+            "displayAliases": {
+              "type": "object",
+              "additionalProperties": { "type": "string" }
+            },
+            "asr": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "enabled": { "type": "boolean" },
+                "appId": { "type": ["string", "number"] },
+                "secretId": { "type": "string" },
+                "secretKey": { "type": "string" }
+              }
+            },
+            "markdownSupport": { "type": "boolean" },
+            "c2cMarkdownDeliveryMode": {
+              "type": "string",
+              "enum": ["passive", "proactive-table-only", "proactive-all"]
+            },
+            "c2cMarkdownChunkStrategy": {
+              "type": "string",
+              "enum": ["markdown-block", "length"]
+            },
+            "typingHeartbeatMode": {
+              "type": "string",
+              "enum": ["none", "idle", "always"]
+            },
+            "typingHeartbeatIntervalMs": { "type": "integer", "minimum": 1 },
+            "typingInputSeconds": { "type": "integer", "minimum": 1 },
+            "dmPolicy": { "type": "string", "enum": ["open", "pairing", "allowlist"] },
+            "groupPolicy": { "type": "string", "enum": ["open", "allowlist", "disabled"] },
+            "requireMention": { "type": "boolean" },
+            "allowFrom": { "type": "array", "items": { "type": "string" } },
+            "groupAllowFrom": { "type": "array", "items": { "type": "string" } },
+            "historyLimit": { "type": "integer", "minimum": 0 },
+            "textChunkLimit": { "type": "integer", "minimum": 1 },
+            "replyFinalOnly": { "type": "boolean" },
+            "longTaskNoticeDelayMs": { "type": "integer", "minimum": 0 },
+            "maxFileSizeMB": { "type": "number", "exclusiveMinimum": 0 },
+            "mediaTimeoutMs": { "type": "integer", "minimum": 1 },
+            "autoSendLocalPathMedia": { "type": "boolean" },
+            "inboundMedia": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "dir": { "type": "string" },
+                "keepDays": { "type": "number", "minimum": 0 }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "appId": { "label": "App ID" },
+    "clientSecret": { "label": "Client Secret", "sensitive": true },
+    "asr.appId": { "label": "ASR App ID" },
+    "asr.secretId": { "label": "ASR Secret ID", "sensitive": true },
+    "asr.secretKey": { "label": "ASR Secret Key", "sensitive": true }
+  }
+}

package/package.json

@@ -0,0 +1,113 @@
+{
+  "name": "@xuanyue202/qqbot",
+  "version": "2026.3.21",
+  "type": "module",
+  "description": "Moltbot QQ Bot channel plugin",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "skills"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "channel": {
+      "id": "qqbot",
+      "label": "QQ Bot",
+      "selectionLabel": "QQ Bot",
+      "docsPath": "/channels/qqbot",
+      "blurb": "QQ 开放平台机器人消息",
+      "aliases": [
+        "qq"
+      ],
+      "order": 72
+    },
+    "install": {
+      "npmSpec": "@xuanyue202/qqbot",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "moltbot": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "channel": {
+      "id": "qqbot",
+      "label": "QQ Bot",
+      "selectionLabel": "QQ Bot",
+      "docsPath": "/channels/qqbot",
+      "blurb": "QQ 开放平台机器人消息",
+      "aliases": [
+        "qq"
+      ],
+      "order": 72
+    },
+    "install": {
+      "npmSpec": "@xuanyue202/qqbot",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "clawdbot": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "channel": {
+      "id": "qqbot",
+      "label": "QQ Bot",
+      "selectionLabel": "QQ Bot",
+      "docsPath": "/channels/qqbot",
+      "blurb": "QQ 开放平台机器人消息",
+      "aliases": [
+        "qq"
+      ],
+      "order": 72
+    },
+    "install": {
+      "npmSpec": "@xuanyue202/qqbot",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "release": "npm run build && npm publish"
+  },
+  "dependencies": {
+    "@xuanyue202/shared": "2026.3.21",
+    "ffmpeg-static": "^5.3.0",
+    "silk-wasm": "^3.7.1",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.0",
+    "tsup": "^8.2.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0",
+    "zod": "^3.23.0"
+  },
+  "peerDependencies": {
+    "moltbot": ">=0.1.0"
+  },
+  "peerDependenciesMeta": {
+    "moltbot": {
+      "optional": true
+    }
+  },
+  "private": false
+}

package/skills/qqbot-contact-send/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: qqbot-contact-send
+description: Resolve a QQBot recipient from the local known-targets registry, distinguish between similarly named contacts, and send text or files to the intended QQ user with the correct target. Use whenever the user says things like “发给这个 QQ 联系人”, “把这个文件发给某个 QQ 用户”, “看看 known-targets.json 里是谁”, “确认发送对象”, or when you need to map a human-readable QQ contact name to a concrete `user:<openid>` target before sending. Prefer this skill over guessing from the current chat when multiple QQ users exist.
+---
+
+# qqbot-contact-send
+
+Use this skill when the user wants to send something to a QQ contact identified by display name or nickname rather than by raw target id.
+
+## What this skill is for
+
+This skill helps avoid sending to the wrong QQ user when:
+- the current chat user is not the intended recipient
+- multiple QQ contacts exist in `known-targets.json`
+- display names are similar or duplicated
+- different users may use multiple agents with the same display name
+- the user asks to inspect the local QQBot target registry before sending
+
+## Data source
+
+Read this file first when resolving a recipient:
+
+- `~/.openclaw/qqbot/data/known-targets.json`
+
+It contains entries like:
+- `accountId`
+- `kind`
+- `target`
+- `displayName`
+- `lastSeenAt`
+
+## Default workflow
+
+1. Read `~/.openclaw/qqbot/data/known-targets.json`.
+2. Default to the current session's `accountId` as the lookup scope unless the user explicitly asks to send across another agent/account.
+3. Prefer the bundled helper script for deterministic lookup:
+   - `python3 {baseDir}/scripts/resolve_known_target.py "<name-or-target>" --account-id "<current-accountId>"`
+4. Match the requested human name against `displayName` first.
+5. If more than one candidate is plausible, show the candidates briefly and ask which one to use.
+6. If exactly one match is clear, use that entry's `target` and `accountId`.
+7. Optionally run the bundled send-prep helper:
+   - `python3 {baseDir}/scripts/prepare_send.py "<recipient>" --account-id "<current-accountId>" --file <path> [--caption <text>]`
+   - or `--text <message>`
+8. Send via the `message` tool using:
+   - `channel: "qqbot"`
+   - `target: <resolved target>`
+   - `accountId: <resolved accountId>`
+9. If sending a file, pass the local path directly.
+10. If upload fails, report the real error plainly. Offer retry or text fallback if appropriate.
+
+## Matching rules
+
+Prefer in this order:
+1. exact `displayName` match
+2. exact user-provided target id if given
+3. recent active contact with a highly similar name
+
+Do not assume the current inbound sender is the destination when the user explicitly names another person.
+
+## Ambiguity handling
+
+Ask a short follow-up if:
+- multiple entries share the same or similar name
+- no clear `displayName` match exists
+- the user says only “发给他/她” without context
+
+Good follow-up style:
+- `我查到两个候选：A（user:...）和 B（user:...），你要发给哪一个？`
+
+## Output style
+
+When reporting the resolved recipient, be brief and concrete:
+- who it maps to
+- which target will be used
+- whether send succeeded or failed
+
+## Important caveat
+
+QQ file messages sent through the generic `message` tool may not automatically enter the qqbot plugin's `ref-index`, so later quote recovery can be incomplete. This does not block sending, but it may affect future reply-context restoration.
+
+## Example prompts this skill should trigger on
+
+- `把这个文件发给这个 QQ 联系人`
+- `看 known-targets.json，确认发送对象`
+- `发给这个备注名联系人，不是当前这个人`
+- `把这份 md 发给另一个 QQ 用户`
+- `先查联系人再发，别发错人`
+
+## Helper scripts
+
+Bundled helpers:
+- `scripts/resolve_known_target.py` → resolve recipient candidates
+- `scripts/prepare_send.py` → resolve recipient and generate a ready-to-use `message` tool payload
+
+Examples:
+
+```bash
+python3 {baseDir}/scripts/resolve_known_target.py "<contact-name>" --account-id "<current-accountId>"
+```
+
+```bash
+python3 {baseDir}/scripts/prepare_send.py "<contact-name>" --account-id "<current-accountId>" --file <path> --caption "<optional-caption>"
+```
+
+The scripts use:
+- exact `displayName`
+- exact `target`
+- substring match
+- `lastSeenAt` recency as tie-breaker
+- current session `accountId` as the default scope filter
+
+`prepare_send.py` does not send by itself; it emits a verified payload for the `message` tool so the agent can deliver without hand-building target fields.

package/skills/qqbot-contact-send/scripts/prepare_send.py

@@ -0,0 +1,141 @@
+#!/usr/bin/env python3
+import json
+import sys
+from pathlib import Path
+
+KNOWN_TARGETS = Path.home() / '.openclaw' / 'qqbot' / 'data' / 'known-targets.json'
+
+
+def norm(s: str) -> str:
+    return (s or '').strip().casefold()
+
+
+def load_targets(account_id: str | None = None):
+    if not KNOWN_TARGETS.exists():
+        return []
+    with KNOWN_TARGETS.open('r', encoding='utf-8') as f:
+        data = json.load(f)
+    items = data if isinstance(data, list) else []
+    if account_id:
+        account_norm = norm(account_id)
+        items = [item for item in items if norm(str(item.get('accountId', ''))) == account_norm]
+    return items
+
+
+def score(entry, query: str):
+    q = norm(query)
+    name = norm(entry.get('displayName', ''))
+    target = norm(entry.get('target', ''))
+    if not q:
+        return -1
+    if name == q:
+        return 300
+    if target == q:
+        return 290
+    if q in name and name:
+        return 200 - max(0, len(name) - len(q))
+    if q in target and target:
+        return 180 - max(0, len(target) - len(q))
+    return -1
+
+
+def ranked_matches(query: str, account_id: str | None = None):
+    items = load_targets(account_id)
+    ranked = []
+    for item in items:
+        s = score(item, query)
+        if s >= 0:
+            ranked.append((s, int(item.get('lastSeenAt', 0) or 0), item))
+    ranked.sort(key=lambda x: (x[0], x[1]), reverse=True)
+    out = []
+    for s, _, item in ranked:
+        out.append({
+            'score': s,
+            'displayName': item.get('displayName'),
+            'target': item.get('target'),
+            'accountId': item.get('accountId'),
+            'kind': item.get('kind'),
+            'lastSeenAt': item.get('lastSeenAt'),
+            'sourceChatType': item.get('sourceChatType'),
+        })
+    return out
+
+
+def usage():
+    print('Usage:', file=sys.stderr)
+    print('  prepare_send.py <recipient> [--account-id <id>] --file <path> [--caption <text>]', file=sys.stderr)
+    print('  prepare_send.py <recipient> [--account-id <id>] --text <message>', file=sys.stderr)
+
+
+def main():
+    if len(sys.argv) < 4:
+        usage()
+        sys.exit(2)
+
+    recipient = sys.argv[1]
+    args = sys.argv[2:]
+    file_path = None
+    caption = None
+    text = None
+    account_id = None
+
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a == '--account-id' and i + 1 < len(args):
+            account_id = args[i + 1]
+            i += 2
+        elif a == '--file' and i + 1 < len(args):
+            file_path = args[i + 1]
+            i += 2
+        elif a == '--caption' and i + 1 < len(args):
+            caption = args[i + 1]
+            i += 2
+        elif a == '--text' and i + 1 < len(args):
+            text = args[i + 1]
+            i += 2
+        else:
+            usage()
+            sys.exit(2)
+
+    if bool(file_path) == bool(text):
+        print(json.dumps({'error': 'Provide exactly one of --file or --text'}, ensure_ascii=False, indent=2))
+        sys.exit(2)
+
+    matches = ranked_matches(recipient, account_id)
+    if not matches:
+        print(json.dumps({'status': 'no_match', 'recipient': recipient, 'matches': []}, ensure_ascii=False, indent=2))
+        sys.exit(1)
+
+    top = matches[0]
+    ambiguous = len(matches) > 1 and matches[1]['score'] == top['score']
+
+    payload = {
+        'channel': 'qqbot',
+        'target': top['target'],
+        'accountId': top['accountId'],
+    }
+    if file_path:
+        p = Path(file_path)
+        payload['path'] = str(p)
+        payload['pathExists'] = p.exists()
+        if caption:
+            payload['caption'] = caption
+    else:
+        payload['message'] = text
+
+    result = {
+        'status': 'ambiguous' if ambiguous else 'ok',
+        'recipient': recipient,
+        'accountScope': account_id,
+        'resolved': top,
+        'matches': matches[:5],
+        'messageToolPayload': payload,
+        'note': 'Use message(action=send, ...messageToolPayload) for actual delivery.'
+    }
+    print(json.dumps(result, ensure_ascii=False, indent=2))
+    sys.exit(3 if ambiguous else 0)
+
+
+if __name__ == '__main__':
+    main()

package/skills/qqbot-contact-send/scripts/resolve_known_target.py

@@ -0,0 +1,74 @@
+#!/usr/bin/env python3
+import json
+import sys
+from pathlib import Path
+
+KNOWN_TARGETS = Path.home() / ".openclaw" / "qqbot" / "data" / "known-targets.json"
+
+
+def norm(s: str) -> str:
+    return (s or "").strip().casefold()
+
+
+def load_targets(account_id: str | None = None):
+    if not KNOWN_TARGETS.exists():
+        return []
+    with KNOWN_TARGETS.open("r", encoding="utf-8") as f:
+        data = json.load(f)
+    items = data if isinstance(data, list) else []
+    if account_id:
+        account_norm = norm(account_id)
+        items = [item for item in items if norm(str(item.get("accountId", ""))) == account_norm]
+    return items
+
+
+def score(entry, query: str):
+    q = norm(query)
+    name = norm(entry.get("displayName", ""))
+    target = norm(entry.get("target", ""))
+    if not q:
+        return -1
+    if name == q:
+        return 300
+    if target == q:
+        return 290
+    if q in name and name:
+        return 200 - (len(name) - len(q))
+    if q in target and target:
+        return 180 - (len(target) - len(q))
+    return -1
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: resolve_known_target.py <query> [--account-id <id>]", file=sys.stderr)
+        sys.exit(2)
+
+    query = sys.argv[1]
+    account_id = None
+    if len(sys.argv) >= 4 and sys.argv[2] == "--account-id":
+        account_id = sys.argv[3]
+    items = load_targets(account_id)
+    ranked = []
+    for item in items:
+        s = score(item, query)
+        if s >= 0:
+            ranked.append((s, int(item.get("lastSeenAt", 0) or 0), item))
+
+    ranked.sort(key=lambda x: (x[0], x[1]), reverse=True)
+    out = []
+    for s, _, item in ranked:
+        out.append({
+            "score": s,
+            "displayName": item.get("displayName"),
+            "target": item.get("target"),
+            "accountId": item.get("accountId"),
+            "kind": item.get("kind"),
+            "lastSeenAt": item.get("lastSeenAt"),
+            "sourceChatType": item.get("sourceChatType"),
+        })
+    print(json.dumps(out, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()