@wentorai/research-plugins 1.2.1 → 1.2.3

package/openclaw.plugin.json

@@ -1,6 +1,6 @@
 {
   "id": "research-plugins",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "name": "Research Plugins",
   "description": "487 academic research skills, 13 agent tools, 150 MCP configs & 6 curated lists for Research-Claw",
   "skills": ["./skills"],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wentorai/research-plugins",
-  "version": "1.2.1",
+  "version": "1.2.3",
   "type": "module",
   "description": "487 academic research skills, 150 MCP configs, 13 agent tools, and 6 curated lists for Research-Claw and AI agents",
   "keywords": [

package/skills/tools/document/qq-connect/SKILL.md

@@ -0,0 +1,227 @@
+---
+name: qq-connect
+description: "Connect QQ messaging to Research-Claw via QQ Bot API"
+metadata:
+  openclaw:
+    emoji: "💬"
+    category: "tools"
+    subcategory: "document"
+    keywords: ["QQ", "QQ Bot", "messaging", "Tencent", "channel"]
+    source: "https://q.qq.com/"
+---
+
+# QQ 连接指南 — Research-Claw × QQ Bot
+
+通过 QQ Bot 官方 API 将 QQ 消息通道连接到 Research-Claw，实现在 QQ 中直接与科研助手交流。
+
+## 架构概述
+
+```
+QQ 用户 ⟶ QQ 开放平台 (WebSocket) ⟶ openclaw-qqbot 插件 ⟶ OpenClaw Gateway ⟶ Research-Claw Agent
+                                                                       ↕
+                                                              research-claw-core (文献/任务/工作区/雷达)
+```
+
+- **openclaw-qqbot** 是一个 OpenClaw channel plugin，使用腾讯 QQ Bot API v2（官方接口）
+- 它与 research-claw-core 插件共存于同一 gateway 进程，共享 agent 上下文
+- 安装后，QQ 用户的消息等同于 dashboard 中的对话 — agent 的全部 27 个工具均可用
+- 附带 2 个技能：`qqbot-cron`（定时提醒）和 `qqbot-media`（图片/语音/视频/文件收发）
+
+## 前提条件
+
+1. **QQ 开放平台账号** — 前往 https://q.qq.com/ 注册开发者账号
+2. **创建机器人应用** — 在开放平台创建一个机器人，获取：
+   - **AppID**（应用 ID）
+   - **AppSecret**（应用密钥）
+3. **配置机器人权限**（在 QQ 开放平台控制台）：
+   - 消息接收：开启「群聊」和/或「私聊」权限
+   - 推荐开启：`PUBLIC_GUILD_MESSAGES` + `GROUP_AND_C2C`（频道+群+私聊）
+4. **Research-Claw 已正常运行** — gateway 可访问 (`ws://127.0.0.1:18789`)
+
+## 安装步骤（Agent 可直接执行）
+
+### 步骤 1：安装 QQ Bot 插件
+
+```bash
+openclaw plugins install @tencent-connect/openclaw-qqbot@latest
+```
+
+如果网络不通，可使用代理：
+```bash
+HTTPS_PROXY=http://127.0.0.1:7890 openclaw plugins install @tencent-connect/openclaw-qqbot@latest
+```
+
+### 步骤 2：配置凭证
+
+**方法 A — 使用 CLI（推荐）：**
+
+> 注意：`openclaw channels add` 仅支持内置通道（Telegram、Discord 等）。
+> qqbot 作为自定义插件，需通过 `config set` 配置。
+
+```bash
+openclaw config set channels.qqbot.appId "<APP_ID>"
+openclaw config set channels.qqbot.clientSecret "<APP_SECRET>"
+openclaw config set channels.qqbot.enabled true
+```
+
+**方法 B — 直接编辑配置文件：**
+
+在 `~/.openclaw/openclaw.json` 中添加：
+
+```jsonc
+{
+  "channels": {
+    "qqbot": {
+      "appId": "<APP_ID>",
+      "clientSecret": "<APP_SECRET>",
+      "enabled": true
+    }
+  }
+}
+```
+
+### 步骤 3：重启 Gateway
+
+```bash
+openclaw gateway restart
+```
+
+### 步骤 4：验证连接
+
+重启后，在 QQ 中向你的机器人发送一条消息（如「你好」）。如果收到回复，连接成功。
+
+查看 gateway 日志确认：
+```bash
+openclaw logs | grep -i qqbot
+```
+
+正常应看到类似：
+```
+[qqbot] Connected to QQ gateway
+[qqbot] Session ready: sessionId=xxx
+```
+
+## 可选配置
+
+```jsonc
+{
+  "channels": {
+    "qqbot": {
+      "appId": "<APP_ID>",
+      "clientSecret": "<APP_SECRET>",
+      "enabled": true,
+
+      // 机器人显示名称（可选）
+      "name": "科研龙虾",
+
+      // 系统提示（可选，追加到 agent 默认提示之后）
+      "systemPrompt": "你现在通过 QQ 与用户交流，回复请简洁。",
+
+      // 私聊策略：open=开放 | pairing=需要用户先发消息 | allowlist=白名单
+      "dmPolicy": "open",
+
+      // 语音转文字（需要 STT 模型配置）
+      "stt": {
+        "provider": "openai",
+        "model": "whisper-1",
+        "enabled": true
+      },
+
+      // 文字转语音
+      "tts": {
+        "provider": "openai",
+        "model": "tts-1",
+        "voice": "nova",
+        "enabled": false
+      },
+
+      // 多账号（可选）
+      "accounts": {
+        "bot2": {
+          "appId": "<BOT2_APP_ID>",
+          "clientSecret": "<BOT2_APP_SECRET>",
+          "enabled": true
+        }
+      }
+    }
+  }
+}
+```
+
+## Agent 自动化设置流程
+
+当用户要求连接 QQ 时，按以下步骤操作：
+
+1. **询问凭证**：
+   > 要连接 QQ，需要你在 QQ 开放平台（https://q.qq.com/）创建机器人后获取的 AppID 和 AppSecret。
+   > 你已经有了吗？如果没有，我可以指导你创建。
+
+2. **获取 AppID 和 AppSecret 后，执行安装**：
+   ```bash
+   openclaw plugins install @tencent-connect/openclaw-qqbot@latest
+   openclaw config set channels.qqbot.appId "<用户提供的AppID>"
+   openclaw config set channels.qqbot.clientSecret "<用户提供的Secret>"
+   openclaw config set channels.qqbot.enabled true
+   openclaw gateway restart
+   ```
+
+3. **引导测试**：
+   > 安装完成！请在 QQ 中找到你的机器人，发送一条消息试试。
+
+4. **记录到 MEMORY.md**：
+   ```markdown
+   ### Environment
+   - QQ Bot: connected (AppID: <前4位>****)
+   ```
+
+## QQ Bot 注册指引（用于引导无账号的用户）
+
+1. 访问 https://q.qq.com/，使用 QQ 账号登录
+2. 点击「创建机器人」（或「应用管理」→「创建」）
+3. 填写机器人基本信息（名称、头像、简介）
+4. 在「开发设置」中获取 **AppID** 和 **AppSecret**
+5. 在「消息」→「消息订阅」中开启消息接收权限：
+   - 群消息（推荐）
+   - 私聊消息（推荐）
+   - 频道消息（可选）
+6. 审核通过后即可使用
+
+> 注意：QQ 机器人需要通过腾讯审核。测试阶段可使用沙箱环境。
+
+## 消息能力
+
+连接 QQ 后，agent 可以：
+
+| 能力 | 说明 |
+|------|------|
+| 文本对话 | QQ 消息 ↔ agent 双向交流 |
+| 图片收发 | 用户发图自动下载，agent 用 `<qqimg>` 标签发图 |
+| 语音处理 | STT 转文字（需配置），TTS 发语音 |
+| 视频/文件 | `<qqvideo>` / `<qqfile>` 标签发送 |
+| 定时提醒 | cron 工具创建一次性/周期提醒 |
+| 群聊 | 支持群组中 @机器人 交流 |
+| 私聊 | 支持一对一私聊 |
+
+## 常见问题
+
+### 连接超时
+- 检查网络：QQ Bot API 需要能访问 `api.sgroup.qq.com` 和 `bots.qq.com`
+- 如果在国内需要代理，在配置中不需要设置代理（QQ API 是国内服务）
+- 如果在海外，可能需要配置代理
+
+### 权限不足（Intent 降级）
+- 插件会自动尝试 3 个权限级别：全功能 → 群+频道 → 仅频道
+- 如果只能用基础功能，去 QQ 开放平台检查机器人权限配置
+
+### 消息发不出去
+- 确认 AppID 和 AppSecret 正确
+- 确认机器人已通过审核（或在沙箱中测试）
+- 检查 gateway 日志：`openclaw logs | grep qqbot`
+
+### 语音无法转文字
+- 需要配置 STT 提供商（如 OpenAI Whisper）
+- 在 `channels.qqbot.stt` 中设置 provider 和 model
+
+### 重启后断开
+- 5 分钟内重启可自动恢复 session（session persistence）
+- 超过 5 分钟会重新建立连接，不影响功能

package/src/tools/arxiv.ts

@@ -1,13 +1,9 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult } from "./util.js";
 
 const BASE = "https://export.arxiv.org/api/query";
 
-function toolResult(data: unknown) {
-  const text = JSON.stringify(data, null, 2);
-  return { content: [{ type: "text" as const, text }] };
-}
-
 function parseArxivXml(xml: string) {
   const entries: Record<string, unknown>[] = [];
   const entryBlocks = xml.split("<entry>").slice(1);

package/src/tools/crossref.ts

@@ -1,13 +1,9 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult } from "./util.js";
 
 const BASE = "https://api.crossref.org";
 
-function toolResult(data: unknown) {
-  const text = JSON.stringify(data, null, 2);
-  return { content: [{ type: "text" as const, text }] };
-}
-
 export function createCrossRefTools(
   _ctx: OpenClawPluginToolContext,
   _api: OpenClawPluginApi,

package/src/tools/openalex.ts

@@ -1,13 +1,9 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult } from "./util.js";
 
 const BASE = "https://api.openalex.org";
 
-function toolResult(data: unknown) {
-  const text = JSON.stringify(data, null, 2);
-  return { content: [{ type: "text" as const, text }] };
-}
-
 export function createOpenAlexTools(
   _ctx: OpenClawPluginToolContext,
   _api: OpenClawPluginApi,

package/src/tools/pubmed.ts

@@ -1,13 +1,9 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult } from "./util.js";
 
 const EUTILS = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
 
-function toolResult(data: unknown) {
-  const text = JSON.stringify(data, null, 2);
-  return { content: [{ type: "text" as const, text }] };
-}
-
 export function createPubMedTools(
   _ctx: OpenClawPluginToolContext,
   _api: OpenClawPluginApi,

package/src/tools/semantic-scholar.ts

@@ -1,13 +1,9 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult } from "./util.js";
 
 const BASE = "https://api.semanticscholar.org/graph/v1";
 
-function toolResult(data: unknown) {
-  const text = JSON.stringify(data, null, 2);
-  return { content: [{ type: "text" as const, text }] };
-}
-
 export function createSemanticScholarTools(
   ctx: OpenClawPluginToolContext,
   api: OpenClawPluginApi,

package/src/tools/unpaywall.ts

@@ -1,13 +1,9 @@
 import { Type } from "@sinclair/typebox";
 import type { OpenClawPluginApi, OpenClawPluginToolContext } from "openclaw/plugin-sdk";
+import { toolResult } from "./util.js";
 
 const BASE = "https://api.unpaywall.org/v2";
 
-function toolResult(data: unknown) {
-  const text = JSON.stringify(data, null, 2);
-  return { content: [{ type: "text" as const, text }] };
-}
-
 export function createUnpaywallTools(
   _ctx: OpenClawPluginToolContext,
   _api: OpenClawPluginApi,

package/src/tools/util.ts

@@ -0,0 +1,11 @@
+/**
+ * Wrap raw data into the OpenClaw AgentTool return format.
+ *
+ * Expected shape: { content: [{ type: "text", text: string }], details: unknown }
+ *   - content  → displayed to the user / consumed by the model as text
+ *   - details  → structured data for programmatic access by downstream tools
+ */
+export function toolResult(data: unknown) {
+  const text = JSON.stringify(data, null, 2);
+  return { content: [{ type: "text" as const, text }], details: data };
+}