@openclaw/qqbot 2026.6.11 → 2026.7.1-beta.2

package/dist/{runtime-D1hn91-s.js → runtime-B4HWCOa-.js}

@@ -1,4 +1,4 @@
-import { v as setOpenClawVersion } from "./sender-CRZ2af7P.js";
+import { v as setOpenClawVersion } from "./sender-BfVLJJYp.js";
 import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
 //#region extensions/qqbot/src/bridge/runtime.ts
 const { setRuntime: _setRuntime, clearRuntime: resetQQBotRuntimeForTest, getRuntime: getQQBotRuntime } = createPluginRuntimeStore({

package/dist/runtime-api.js

@@ -1,2 +1,2 @@
-import { r as setQQBotRuntime, t as getQQBotRuntime } from "./runtime-D1hn91-s.js";
+import { r as setQQBotRuntime, t as getQQBotRuntime } from "./runtime-B4HWCOa-.js";
 export { getQQBotRuntime, setQQBotRuntime };

package/dist/{sender-CRZ2af7P.js → sender-BfVLJJYp.js}

@@ -2,10 +2,11 @@ import { c as getPlatformAdapter, i as normalizeOptionalString, s as sanitizeFil
 import { a as formatErrorMessage, n as debugLog, r as debugWarn, t as debugError } from "./log-SDfMMBWe.js";
 import * as fs$1 from "node:fs";
 import os from "node:os";
-import { readResponseTextLimited } from "openclaw/plugin-sdk/provider-http";
+import { readProviderTextResponse, readResponseTextLimited } from "openclaw/plugin-sdk/provider-http";
 import { fetchWithSsrFGuard, isBlockedHostnameOrIp } from "openclaw/plugin-sdk/ssrf-runtime";
 import * as crypto$1 from "node:crypto";
 import crypto from "node:crypto";
+import { sleep } from "openclaw/plugin-sdk/runtime-env";
 import { FsSafeError, openLocalFileSafely, readRegularFile, statRegularFileSync } from "openclaw/plugin-sdk/security-runtime";
 import * as path$1 from "node:path";
 import { mimeTypeFromFilePath } from "openclaw/plugin-sdk/media-mime";
@@ -159,7 +160,7 @@ var ApiClient = class {
 			this.logger?.info?.(`[qqbot:api] <<< Status: ${res.status} ${res.statusText}${traceId ? ` | TraceId: ${traceId}` : ""}`);
 			const readBody = async (limitBytes) => {
 				try {
-					return limitBytes === void 0 ? await res.text() : await readResponseTextLimited(res, limitBytes);
+					return limitBytes === void 0 ? await readProviderTextResponse(res, "QQBot API response") : await readResponseTextLimited(res, limitBytes);
 				} catch (err) {
 					throw new ApiError(`Failed to read response [${path}]: ${formatErrorMessage(err)}`, res.status, path);
 				}
@@ -462,6 +463,17 @@ async function normalizeSource(raw, opts = {}) {
 //#endregion
 //#region extensions/qqbot/src/engine/api/retry.ts
 /**
+* Generic retry engine for QQ Bot API requests.
+*
+* Replaces the three separate retry implementations in the old `api.ts`:
+* - `apiRequestWithRetry` (upload retry with exponential backoff)
+* - `partFinishWithRetry` (part-finish retry + persistent retry on specific biz codes)
+* - `completeUploadWithRetry` (unconditional retry for complete-upload)
+*
+* All three patterns are expressed as a single `withRetry` function
+* parameterized by `RetryPolicy` and optional `PersistentRetryPolicy`.
+*/
+/**
 * Execute an async operation with configurable retry semantics.
 *
 * @param fn - The async operation to retry.
@@ -484,7 +496,7 @@ async function withRetry(fn, policy, persistentPolicy, logger) {
 		if (attempt < policy.maxRetries) {
 			const delay = policy.backoff === "exponential" ? policy.baseDelayMs * 2 ** attempt : policy.baseDelayMs;
 			logger?.debug?.(`[qqbot:retry] Attempt ${attempt + 1} failed, retrying in ${delay}ms: ${lastError.message.slice(0, 100)}`);
-			await sleep$1(delay);
+			await sleep(delay);
 		}
 	}
 	throw lastError;
@@ -514,16 +526,11 @@ async function persistentRetryLoop(fn, policy, logger) {
 		if (remaining <= 0) break;
 		const actualDelay = Math.min(policy.intervalMs, remaining);
 		(logger?.warn ?? logger?.error)?.(`[qqbot:retry] Persistent retry #${attempt}: retrying in ${actualDelay}ms (remaining=${Math.round(remaining / 1e3)}s)`);
-		await sleep$1(actualDelay);
+		await sleep(actualDelay);
 	}
 	logger?.error?.(`[qqbot:retry] Persistent retry timed out after ${policy.timeoutMs / 1e3}s (${attempt} attempts)`);
 	throw lastError ?? /* @__PURE__ */ new Error(`Persistent retry timed out (${policy.timeoutMs / 1e3}s)`);
 }
-function sleep$1(ms) {
-	return new Promise((resolve) => {
-		setTimeout(resolve, ms);
-	});
-}
 /** Standard upload retry: exponential backoff, skip 400/401/timeout errors. */
 const UPLOAD_RETRY_POLICY = {
 	maxRetries: 2,
@@ -967,11 +974,6 @@ async function runWithConcurrency(tasks, maxConcurrent) {
 		await Promise.all(batch.map((task) => task()));
 	}
 }
-function sleep(ms) {
-	return new Promise((resolve) => {
-		setTimeout(resolve, ms);
-	});
-}
 //#endregion
 //#region extensions/qqbot/src/engine/api/token.ts
 /**

package/dist/setup-plugin-api.js

@@ -1,2 +1,2 @@
-import { t as qqbotSetupPlugin } from "./channel.setup-CldhUlTO.js";
+import { t as qqbotSetupPlugin } from "./channel.setup-2ItDYKhz.js";
 export { qqbotSetupPlugin };

package/dist/{doctor-contract-BYTS8-ia.js → state-keys-CQKlAFyo.js}

@@ -1,3 +1,4 @@
+import crypto from "node:crypto";
 import { asObjectRecord } from "openclaw/plugin-sdk/runtime-doctor";
 //#region extensions/qqbot/src/doctor-contract.ts
 const RESTRICTED_GROUP_TOOLS = { deny: [
@@ -132,4 +133,9 @@ function normalizeCompatibilityConfig({ cfg }) {
 	};
 }
 //#endregion
-export { normalizeCompatibilityConfig as n, legacyConfigRules as t };
+//#region extensions/qqbot/src/engine/utils/state-keys.ts
+function buildQQBotStateKey(...parts) {
+	return crypto.createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+}
+//#endregion
+export { legacyConfigRules as n, normalizeCompatibilityConfig as r, buildQQBotStateKey as t };

package/dist/target-parser-DagYRQkP.js

@@ -0,0 +1,71 @@
+//#region extensions/qqbot/src/engine/messaging/target-parser.ts
+/**
+* Parse a qqbot target string into a structured delivery target.
+*
+* Supported formats:
+* - `qqbot:c2c:openid` → C2C direct message
+* - `qqbot:group:groupid` → Group message
+* - `qqbot:channel:channelid` → Channel message
+* - `c2c:openid` → C2C (without qqbot: prefix)
+* - `group:groupid` → Group (without qqbot: prefix)
+* - `channel:channelid` → Channel (without qqbot: prefix)
+* - `openid` → C2C (bare openid, default)
+*
+* @param to - Raw target string.
+* @returns Parsed target with type and id.
+* @throws {Error} When the target format is invalid.
+*/
+function parseTarget(to) {
+	const id = to.replace(/^qqbot:/i, "");
+	if (id.startsWith("c2c:")) {
+		const userId = id.slice(4);
+		if (!userId) throw new Error(`Invalid c2c target format: ${to} - missing user ID`);
+		return {
+			type: "c2c",
+			id: userId
+		};
+	}
+	if (id.startsWith("group:")) {
+		const groupId = id.slice(6);
+		if (!groupId) throw new Error(`Invalid group target format: ${to} - missing group ID`);
+		return {
+			type: "group",
+			id: groupId
+		};
+	}
+	if (id.startsWith("channel:")) {
+		const channelId = id.slice(8);
+		if (!channelId) throw new Error(`Invalid channel target format: ${to} - missing channel ID`);
+		return {
+			type: "channel",
+			id: channelId
+		};
+	}
+	if (!id) throw new Error(`Invalid target format: ${to} - empty ID after removing qqbot: prefix`);
+	return {
+		type: "c2c",
+		id
+	};
+}
+/**
+* Normalize a QQ Bot target string into the canonical `qqbot:...` form.
+*
+* Returns `undefined` when the target does not look like a QQ Bot address.
+*/
+function normalizeTarget(target) {
+	const id = target.replace(/^qqbot:/i, "");
+	if (id.startsWith("c2c:") || id.startsWith("group:") || id.startsWith("channel:")) return `qqbot:${id}`;
+	if (/^[0-9a-fA-F]{32}$/.test(id)) return `qqbot:c2c:${id}`;
+	if (/^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(id)) return `qqbot:c2c:${id}`;
+}
+/**
+* Return true when the string looks like a QQ Bot target ID.
+*/
+function looksLikeQQBotTarget(id) {
+	if (/^qqbot:(c2c|group|channel):/i.test(id)) return true;
+	if (/^(c2c|group|channel):/i.test(id)) return true;
+	if (/^[0-9a-fA-F]{32}$/.test(id)) return true;
+	return /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/.test(id);
+}
+//#endregion
+export { normalizeTarget as n, parseTarget as r, looksLikeQQBotTarget as t };

package/dist/{tools-CeUI9pG-.js → tools-C8kTMXKc.js}

@@ -1,10 +1,11 @@
 import { a as resolveQQBotAccount, r as listQQBotAccountIds } from "./config-C1qZbh0K.js";
 import { a as formatErrorMessage, n as debugLog, t as debugError } from "./log-SDfMMBWe.js";
 import { t as getRequestContext } from "./request-context-Bm7PTBD1.js";
-import { readResponseTextLimited } from "openclaw/plugin-sdk/provider-http";
+import { readProviderTextResponse, readResponseTextLimited } from "openclaw/plugin-sdk/provider-http";
 import { fetchWithSsrFGuard } from "openclaw/plugin-sdk/ssrf-runtime";
 import { resolveExpiresAtMsFromDurationMs } from "openclaw/plugin-sdk/number-runtime";
 import { callGatewayTool } from "openclaw/plugin-sdk/agent-harness-runtime";
+import { truncateUtf16Safe } from "openclaw/plugin-sdk/text-utility-runtime";
 //#region extensions/qqbot/src/engine/tools/channel-api.ts
 /**
 * QQ Channel API proxy tool core logic.
@@ -33,7 +34,7 @@ const ChannelApiSchema = {
 	properties: {
 		method: {
 			type: "string",
-			description: "HTTP method. Allowed values: GET, POST, PUT, PATCH, DELETE.",
+			description: "HTTP method. Allowed values: GET, POST, PUT, PATCH, DELETE. Use DELETE and other mutating methods only after explicit user intent and target confirmation.",
 			enum: [
 				"GET",
 				"POST",
@@ -48,12 +49,20 @@ const ChannelApiSchema = {
 		},
 		body: {
 			type: "object",
-			description: "JSON request body for POST/PUT/PATCH requests. GET/DELETE usually do not need it."
+			description: "JSON request body for POST/PUT/PATCH requests. GET/DELETE usually do not need it. For write requests, include only fields the user explicitly asked to change."
 		},
 		query: {
 			type: "object",
 			description: "URL query parameters as key/value pairs appended to the path. For example, { \"limit\": \"100\", \"after\": \"0\" } becomes ?limit=100&after=0.",
 			additionalProperties: { type: "string" }
+		},
+		confirmed: {
+			type: "boolean",
+			description: "Required true for DELETE requests after the user confirms the exact QQ resource to delete."
+		},
+		bulkConfirmed: {
+			type: "boolean",
+			description: "Required true in addition to confirmed for bulk DELETE requests such as deleting all announcements."
 		}
 	},
 	required: ["method", "path"]
@@ -80,6 +89,33 @@ function validatePath(path) {
 	if (!path.startsWith("/")) return "path must start with /";
 	if (path.includes("..") || path.includes("//")) return "path must not contain .. or //";
 	if (!/^\/[a-zA-Z0-9\-._~:@!$&'()*+,;=/%]+$/.test(path) && path !== "/") return "path contains unsupported characters";
+	for (const segment of path.split("/").slice(1)) {
+		let decodedSegment;
+		try {
+			decodedSegment = decodeURIComponent(segment);
+		} catch {
+			return "path contains invalid percent encoding";
+		}
+		if (decodedSegment.includes("/") || decodedSegment.includes("\\")) return "path contains encoded path separators";
+		if (decodedSegment === "." || decodedSegment === "..") return "path must not contain . or .. segments";
+	}
+	return null;
+}
+function decodePathSegments(path) {
+	try {
+		return path.replace(/\/+$/, "").split("/").slice(1).map((segment) => decodeURIComponent(segment));
+	} catch {
+		return null;
+	}
+}
+function isBulkAnnouncementDeletePath(path) {
+	const segments = decodePathSegments(path);
+	return Boolean(segments && segments.length === 4 && segments[0]?.toLowerCase() === "guilds" && segments[2]?.toLowerCase() === "announces" && segments[3]?.toLowerCase() === "all");
+}
+function validateDeleteConfirmation(params) {
+	if (params.method.toUpperCase() !== "DELETE") return null;
+	if (!params.confirmed) return "DELETE requests require confirmed=true after the user confirms the exact QQ resource.";
+	if (isBulkAnnouncementDeletePath(params.path) && !params.bulkConfirmed) return "Deleting all announcements requires bulkConfirmed=true after a separate bulk-delete confirmation.";
 	return null;
 }
 function json$1(data) {
@@ -112,6 +148,14 @@ async function executeChannelApi(params, options) {
 	].includes(method)) return json$1({ error: `Unsupported HTTP method: ${method}. Allowed values: GET, POST, PUT, PATCH, DELETE` });
 	const pathError = validatePath(params.path);
 	if (pathError) return json$1({ error: pathError });
+	const confirmationError = validateDeleteConfirmation({
+		...params,
+		method
+	});
+	if (confirmationError) return json$1({
+		error: confirmationError,
+		path: params.path
+	});
 	if ((method === "GET" || method === "DELETE") && params.body && Object.keys(params.body).length > 0) debugLog(`[qqbot-channel-api] ${method} request with body, body will be ignored`);
 	try {
 		const url = buildUrl(params.path, params.query);
@@ -162,7 +206,7 @@ async function executeChannelApi(params, options) {
 		}
 		try {
 			debugLog(`[qqbot-channel-api] <<< Status: ${res.status} ${res.statusText}`);
-			const rawBody = res.ok ? await res.text() : await readResponseTextLimited(res, CHANNEL_API_ERROR_BODY_LIMIT_BYTES);
+			const rawBody = res.ok ? await readProviderTextResponse(res, "QQ channel API response") : await readResponseTextLimited(res, CHANNEL_API_ERROR_BODY_LIMIT_BYTES);
 			if (!rawBody || rawBody.trim() === "") {
 				if (res.ok) return json$1({
 					success: true,
@@ -227,16 +271,17 @@ function registerChannelTool(api) {
 	api.registerTool({
 		name: "qqbot_channel_api",
 		label: "QQBot Channel API",
-		description: "Authenticated HTTP proxy for QQ Open Platform channel APIs. Common endpoints: list guilds GET /users/@me/guilds | list channels GET /guilds/{guild_id}/channels | get channel GET /channels/{channel_id} | create channel POST /guilds/{guild_id}/channels | list members GET /guilds/{guild_id}/members?after=0&limit=100 | get member GET /guilds/{guild_id}/members/{user_id} | list threads GET /channels/{channel_id}/threads | create thread PUT /channels/{channel_id}/threads | create announce POST /guilds/{guild_id}/announces | create schedule POST /channels/{channel_id}/schedules. See the qqbot-channel skill for full endpoint details.",
+		description: "Authenticated HTTP proxy for QQ Open Platform channel APIs. Use write and delete endpoints only after explicit user intent; DELETE requires confirmed=true, and bulk deletes require bulkConfirmed=true after confirming the exact target. Common endpoints: list guilds GET /users/@me/guilds | list channels GET /guilds/{guild_id}/channels | get channel GET /channels/{channel_id} | create channel POST /guilds/{guild_id}/channels | list members GET /guilds/{guild_id}/members?after=0&limit=100 | get member GET /guilds/{guild_id}/members/{user_id} | list threads GET /channels/{channel_id}/threads | create thread PUT /channels/{channel_id}/threads | create announce POST /guilds/{guild_id}/announces | create schedule POST /channels/{channel_id}/schedules. See the qqbot-channel skill for full endpoint details.",
 		parameters: ChannelApiSchema,
 		async execute(_toolCallId, params) {
-			const { getAccessToken } = await import("./sender-CRZ2af7P.js").then((n) => n._);
+			const { getAccessToken } = await import("./sender-BfVLJJYp.js").then((n) => n._);
 			return executeChannelApi(params, { accessToken: await getAccessToken(account.appId, account.clientSecret) });
 		}
 	}, { name: "qqbot_channel_api" });
 }
 //#endregion
 //#region extensions/qqbot/src/engine/tools/remind-logic.ts
+const QQBOT_DEFAULT_REMINDER_TIMEZONE = "Asia/Shanghai";
 /**
 * JSON Schema for AI tool parameters (used by framework registration).
 * AI Tool 参数的 JSON Schema 定义（供框架注册使用）。
@@ -246,7 +291,7 @@ const RemindSchema = {
 	properties: {
 		action: {
 			type: "string",
-			description: "Action type. add=create a reminder, list=show reminders, remove=delete a reminder.",
+			description: "Action type. add=create a reminder only after explicit user request, list=show reminders, remove=delete a reminder by confirmed job ID.",
 			enum: [
 				"add",
 				"list",
@@ -263,11 +308,11 @@ const RemindSchema = {
 		},
 		time: {
 			type: "string",
-			description: "Time description. Supported formats:\n1. Relative time, for example \"5m\", \"1h\", \"1h30m\", or \"2d\"\n2. Cron expression, for example \"0 8 * * *\" or \"0 9 * * 1-5\"\nValues containing spaces are treated as cron expressions; everything else is treated as a one-shot relative delay.\nRequired when action=add."
+			description: "Time description. Supported formats:\n1. Relative time, for example \"5m\", \"1h\", \"1h30m\", or \"2d\"\n2. Cron expression, for example \"0 8 * * *\" or \"0 9 * * 1-5\"\nValues containing spaces are treated as cron expressions; everything else is treated as a one-shot relative delay.\nRequired when action=add. Ask for clarification before scheduling if the time is ambiguous."
 		},
 		timezone: {
 			type: "string",
-			description: "Timezone used for cron reminders. Defaults to \"Asia/Shanghai\"."
+			description: "Optional IANA timezone used for cron reminders. Include it when the user provides or confirms a timezone; if omitted, QQBot preserves its existing default timezone."
 		},
 		name: {
 			type: "string",
@@ -333,7 +378,7 @@ function isCronExpression(timeStr) {
 */
 function generateJobName(content) {
 	const trimmed = content.trim();
-	return `Reminder: ${trimmed.length > 20 ? `${trimmed.slice(0, 20)}…` : trimmed}`;
+	return `Reminder: ${trimmed.length > 20 ? `${truncateUtf16Safe(trimmed, 20)}…` : trimmed}`;
 }
 /** Build the reminder system prompt sent to the AI. */
 function buildReminderPrompt(content) {
@@ -370,7 +415,7 @@ function buildOnceJob(params, atMs, to, accountId) {
 function buildCronJob(params, to, accountId) {
 	const content = params.content;
 	const name = params.name || generateJobName(content);
-	const tz = params.timezone || "Asia/Shanghai";
+	const tz = params.timezone || QQBOT_DEFAULT_REMINDER_TIMEZONE;
 	return {
 		action: "add",
 		job: {
@@ -456,7 +501,7 @@ function prepareRemindCronAction(params, ctx = {}) {
 		ok: true,
 		action: "add",
 		cronAction: buildCronJob(params, resolvedTo, resolvedAccountId),
-		summary: `⏰ Recurring reminder: "${params.content}" (${params.time}, tz=${params.timezone || "Asia/Shanghai"})`
+		summary: `⏰ Recurring reminder: "${params.content}" (${params.time}, tz=${params.timezone || QQBOT_DEFAULT_REMINDER_TIMEZONE})`
 	};
 	const delayMs = parseRelativeTime(params.time);
 	if (delayMs == null) return {
@@ -515,7 +560,7 @@ function createRemindTool(toolContext = {}, deps = defaultDeps) {
 	return {
 		name: "qqbot_remind",
 		label: "QQBot Reminder",
-		description: "Create, list, and remove QQ reminders. This tool schedules Gateway cron jobs directly; do not call the cron tool after it succeeds.\nCreate: action=add, content=message, time=schedule (to is optional, resolved automatically from the current conversation)\nList: action=list\nRemove: action=remove, jobId=job id from list\nTime examples: \"5m\", \"1h\", \"0 8 * * *\"",
+		description: "Create, list, and remove QQ reminders. Use only for explicit user requests, and ask when reminder content, schedule, or timezone is ambiguous. This tool schedules Gateway cron jobs directly; do not call the cron tool after it succeeds.\nCreate: action=add, content=message, time=schedule (to is optional, resolved automatically from the current conversation)\nList: action=list\nRemove: action=remove, jobId=job id from list\nTime examples: \"5m\", \"1h\", \"0 8 * * *\"; include timezone for recurring cron reminders when known.",
 		parameters: RemindSchema,
 		async execute(_toolCallId, params) {
 			const ctx = getRequestContext();

package/dist/tools-api.js

@@ -1,2 +1,2 @@
-import { t as registerQQBotTools } from "./tools-CeUI9pG-.js";
+import { t as registerQQBotTools } from "./tools-C8kTMXKc.js";
 export { registerQQBotTools };

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@openclaw/qqbot",
-  "version": "2026.6.11",
+  "version": "2026.7.1-beta.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@openclaw/qqbot",
-      "version": "2026.6.11",
+      "version": "2026.7.1-beta.2",
       "dependencies": {
         "@tencent-connect/qqbot-connector": "1.1.0",
         "mpg123-decoder": "1.0.3",
@@ -15,7 +15,7 @@
         "zod": "4.4.3"
       },
       "peerDependencies": {
-        "openclaw": ">=2026.6.11"
+        "openclaw": ">=2026.7.1-beta.2"
       },
       "peerDependenciesMeta": {
         "openclaw": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/qqbot",
-  "version": "2026.6.11",
+  "version": "2026.7.1-beta.2",
   "private": false,
   "description": "OpenClaw QQ Bot channel plugin for group and direct-message workflows.",
   "repository": {
@@ -16,7 +16,7 @@
     "zod": "4.4.3"
   },
   "peerDependencies": {
-    "openclaw": ">=2026.6.11"
+    "openclaw": ">=2026.7.1-beta.2"
   },
   "peerDependenciesMeta": {
     "openclaw": {
@@ -45,10 +45,10 @@
       "minHostVersion": ">=2026.4.10"
     },
     "compat": {
-      "pluginApi": ">=2026.6.11"
+      "pluginApi": ">=2026.7.1-beta.2"
     },
     "build": {
-      "openclawVersion": "2026.6.11"
+      "openclawVersion": "2026.7.1-beta.2"
     },
     "release": {
       "publishToClawHub": true,

package/skills/qqbot-channel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: qqbot-channel
-description: QQ channel management skill. Use qqbot_channel_api to list guilds and channels, inspect members, publish posts, manage announcements, and work with schedules through the QQ Open Platform HTTP API with automatic token authentication.
+description: QQ channel management skill. Use qqbot_channel_api for explicit QQ channel-management requests; confirm write, delete, and bulk actions before calling authenticated QQ Open Platform endpoints.
 metadata: { "openclaw": { "emoji": "📡", "requires": { "config": ["channels.qqbot"] } } }
 ---
 
@@ -18,15 +18,25 @@ metadata: { "openclaw": { "emoji": "📡", "requires": { "config": ["channels.qq
 
 ## 🔧 工具参数
 
-| 参数     | 类型   | 必填 | 说明                                                                         |
-| -------- | ------ | ---- | ---------------------------------------------------------------------------- |
-| `method` | string | 是   | HTTP 方法：`GET`, `POST`, `PUT`, `PATCH`, `DELETE`                           |
-| `path`   | string | 是   | API 路径（不含域名），如 `/guilds/{guild_id}/channels`，需替换占位符为实际值 |
-| `body`   | object | 否   | 请求体 JSON（POST/PUT/PATCH 使用）                                           |
-| `query`  | object | 否   | URL 查询参数键值对，值为字符串类型                                           |
+| 参数            | 类型    | 必填 | 说明                                                                         |
+| --------------- | ------- | ---- | ---------------------------------------------------------------------------- |
+| `method`        | string  | 是   | HTTP 方法：`GET`, `POST`, `PUT`, `PATCH`, `DELETE`                           |
+| `path`          | string  | 是   | API 路径（不含域名），如 `/guilds/{guild_id}/channels`，需替换占位符为实际值 |
+| `body`          | object  | 否   | 请求体 JSON（POST/PUT/PATCH 使用）                                           |
+| `query`         | object  | 否   | URL 查询参数键值对，值为字符串类型                                           |
+| `confirmed`     | boolean | 否   | `DELETE` 必须传 `true`，表示用户已确认精确删除目标                           |
+| `bulkConfirmed` | boolean | 否   | 批量 `DELETE`（如删除全部公告）必须额外传 `true`                             |
 
 > 基础 URL：`https://api.sgroup.qq.com`，鉴权头 `Authorization: QQBot {token}` 由工具自动填充。
 
+## 🛡️ 安全边界
+
+- 只在用户明确要求管理 QQ 频道、子频道、公告、论坛帖子或日程时调用写入接口。
+- `POST`、`PUT`、`PATCH` 和 `DELETE` 会修改真实 QQ 资源。调用前先复述目标频道/子频道/帖子/日程和预期改动；删除、批量删除、公告覆盖等不可逆或大范围操作必须等用户确认后再执行。
+- 删除前优先用 `GET`/列表接口查出候选项，让用户选择具体 ID；不要根据模糊名称猜测删除目标。
+- `DELETE` 请求必须传 `confirmed: true`，否则工具会拒绝执行。`announces/all` 这样的批量操作还必须传 `bulkConfirmed: true`，只有在用户明确说要删除全部公告并再次确认后才可使用。
+- 成员资料、头像 URL、频道图标等属于用户/群组资料。默认只总结必要字段；只有用户要求查看头像/图标或视觉比对时才内联展示图片，不要无关转发头像 URL。
+
 ---
 
 ## ⭐ 接口速查
@@ -40,13 +50,13 @@ metadata: { "openclaw": { "emoji": "📡", "requires": { "config": ["channels.qq
 
 ### 子频道（Channel）
 
-| 操作           | 方法     | 路径                          | 参数说明                                                                                                                                  |
-| -------------- | -------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| 获取子频道列表 | `GET`    | `/guilds/{guild_id}/channels` | —                                                                                                                                         |
-| 获取子频道详情 | `GET`    | `/channels/{channel_id}`      | —                                                                                                                                         |
-| 创建子频道     | `POST`   | `/guilds/{guild_id}/channels` | body: `name`\*, `type`\*, `position`\*, `sub_type`, `parent_id`, `private_type`, `private_user_ids`, `speak_permission`, `application_id` |
-| 修改子频道     | `PATCH`  | `/channels/{channel_id}`      | body: `name`, `position`, `parent_id`, `private_type`, `speak_permission`（至少一个）                                                     |
-| 删除子频道     | `DELETE` | `/channels/{channel_id}`      | ⚠️ 不可逆                                                                                                                                 |
+| 操作           | 方法    | 路径                          | 参数说明                                                                                                                                  |
+| -------------- | ------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| 获取子频道列表 | `GET`   | `/guilds/{guild_id}/channels` | —                                                                                                                                         |
+| 获取子频道详情 | `GET`   | `/channels/{channel_id}`      | —                                                                                                                                         |
+| 创建子频道     | `POST`  | `/guilds/{guild_id}/channels` | body: `name`\*, `type`\*, `position`\*, `sub_type`, `parent_id`, `private_type`, `private_user_ids`, `speak_permission`, `application_id` |
+| 修改子频道     | `PATCH` | `/channels/{channel_id}`      | body: `name`, `position`, `parent_id`, `private_type`, `speak_permission`（至少一个）                                                     |
+| 删除子频道     | —       | 见受确认保护的删除流程        | 破坏性操作；不要在未确认时调用                                                                                                            |
 
 **子频道类型（type）**：`0`=文字, `2`=语音, `4`=分组(position≥2), `10005`=直播, `10006`=应用, `10007`=论坛
 
@@ -61,28 +71,28 @@ metadata: { "openclaw": { "emoji": "📡", "requires": { "config": ["channels.qq
 
 ### 公告（Announces）
 
-| 操作     | 方法     | 路径                                        | 参数说明                                                                                         |
-| -------- | -------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------ |
-| 创建公告 | `POST`   | `/guilds/{guild_id}/announces`              | body: `message_id`, `channel_id`, `announces_type`(0=成员,1=欢迎), `recommend_channels`(最多3条) |
-| 删除公告 | `DELETE` | `/guilds/{guild_id}/announces/{message_id}` | message_id 设 `all` 删除所有                                                                     |
+| 操作     | 方法   | 路径                           | 参数说明                                                                                         |
+| -------- | ------ | ------------------------------ | ------------------------------------------------------------------------------------------------ |
+| 创建公告 | `POST` | `/guilds/{guild_id}/announces` | body: `message_id`, `channel_id`, `announces_type`(0=成员,1=欢迎), `recommend_channels`(最多3条) |
+| 删除公告 | —      | 见受确认保护的删除流程         | 破坏性操作；批量删除需二次确认                                                                   |
 
 ### 论坛（Forum）— 仅私域机器人
 
-| 操作         | 方法     | 路径                                                 | 参数说明                                                                       |
-| ------------ | -------- | ---------------------------------------------------- | ------------------------------------------------------------------------------ |
-| 获取帖子列表 | `GET`    | `/channels/{channel_id}/threads`                     | —                                                                              |
-| 获取帖子详情 | `GET`    | `/channels/{channel_id}/threads/{thread_id}`         | —                                                                              |
-| 发表帖子     | `PUT`    | `/channels/{channel_id}/threads`                     | body: `title`\*, `content`\*, `format`(1=文本,2=HTML,3=Markdown,4=JSON，默认3) |
-| 删除帖子     | `DELETE` | `/channels/{channel_id}/threads/{thread_id}`         | ⚠️ 不可逆                                                                      |
-| 发表评论     | `POST`   | `/channels/{channel_id}/threads/{thread_id}/comment` | body: `thread_author`\*, `content`\*, `thread_create_time`, `image`            |
+| 操作         | 方法   | 路径                                                 | 参数说明                                                                       |
+| ------------ | ------ | ---------------------------------------------------- | ------------------------------------------------------------------------------ |
+| 获取帖子列表 | `GET`  | `/channels/{channel_id}/threads`                     | —                                                                              |
+| 获取帖子详情 | `GET`  | `/channels/{channel_id}/threads/{thread_id}`         | —                                                                              |
+| 发表帖子     | `PUT`  | `/channels/{channel_id}/threads`                     | body: `title`\*, `content`\*, `format`(1=文本,2=HTML,3=Markdown,4=JSON，默认3) |
+| 删除帖子     | —      | 见受确认保护的删除流程                               | 破坏性操作；不要在未确认时调用                                                 |
+| 发表评论     | `POST` | `/channels/{channel_id}/threads/{thread_id}/comment` | body: `thread_author`\*, `content`\*, `thread_create_time`, `image`            |
 
 ### 日程（Schedule）
 
-| 操作     | 方法     | 路径                                             | 参数说明                                                                                        |
-| -------- | -------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
-| 创建日程 | `POST`   | `/channels/{channel_id}/schedules`               | body: `{ schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }` |
-| 修改日程 | `PATCH`  | `/channels/{channel_id}/schedules/{schedule_id}` | body: `{ schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }` |
-| 删除日程 | `DELETE` | `/channels/{channel_id}/schedules/{schedule_id}` | ⚠️ 不可逆                                                                                       |
+| 操作     | 方法    | 路径                                             | 参数说明                                                                                        |
+| -------- | ------- | ------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| 创建日程 | `POST`  | `/channels/{channel_id}/schedules`               | body: `{ schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }` |
+| 修改日程 | `PATCH` | `/channels/{channel_id}/schedules/{schedule_id}` | body: `{ schedule: { name*, start_timestamp*, end_timestamp*, jump_channel_id, remind_type } }` |
+| 删除日程 | —       | 见受确认保护的删除流程                           | 破坏性操作；不要在未确认时调用                                                                  |
 
 **提醒类型（remind_type）**：`"0"`=不提醒, `"1"`=开始时, `"2"`=5分钟前, `"3"`=15分钟前, `"4"`=30分钟前, `"5"`=60分钟前
 
@@ -180,14 +190,17 @@ metadata: { "openclaw": { "emoji": "📡", "requires": { "config": ["channels.qq
 }
 ```
 
-### 删除所有公告
+### 受确认保护的删除流程
 
-```json
-{
-  "method": "DELETE",
-  "path": "/guilds/123456/announces/all"
-}
-```
+删除类 QQ API 不作为普通速查示例暴露。若用户明确要求删除资源，先读取并复述目标对象，确认后再调用 `qqbot_channel_api`：`method` 设为 `"DELETE"`，`confirmed` 设为 `true`，`path` 使用已确认对象对应的资源路径。
+
+| 删除对象 | 已确认后使用的 `path`                            | 额外要求                                 |
+| -------- | ------------------------------------------------ | ---------------------------------------- |
+| 子频道   | `/channels/{channel_id}`                         | 确认子频道 ID 和名称                     |
+| 单条公告 | `/guilds/{guild_id}/announces/{message_id}`      | 确认公告 ID                              |
+| 全部公告 | `/guilds/{guild_id}/announces/all`               | 用户再次确认后再传 `bulkConfirmed: true` |
+| 帖子     | `/channels/{channel_id}/threads/{thread_id}`     | 确认帖子 ID、标题/作者                   |
+| 日程     | `/channels/{channel_id}/schedules/{schedule_id}` | 确认日程 ID、名称/时间                   |
 
 ---
 
@@ -222,7 +235,7 @@ metadata: { "openclaw": { "emoji": "📡", "requires": { "config": ["channels.qq
 
 ### 展示成员头像
 
-成员详情返回的 `user.avatar` 是头像 URL，**必须使用 Markdown 图片语法展示**，让用户直接看到头像图片，而非纯文本链接：
+成员详情返回的 `user.avatar` 是头像 URL。默认只展示昵称、ID、加入时间等必要字段；当用户明确要求查看头像/图标或头像是当前任务的必要依据时，再用 Markdown 图片语法内联展示：
 
 ```
 成员信息：
@@ -231,7 +244,7 @@ metadata: { "openclaw": { "emoji": "📡", "requires": { "config": ["channels.qq
 ![头像]({user.avatar})
 ```
 
-> **禁止**将头像 URL 作为纯文本或超链接展示（如 `查看头像`），必须用 `![描述](URL)` 语法内联显示。频道的 `icon` 字段同理。
+不要无关输出原始头像 URL 或把头像作为普通链接转发。频道的 `icon` 字段同理：仅在用户明确需要查看时展示。
 
 ---
 
@@ -255,8 +268,8 @@ metadata: { "openclaw": { "emoji": "📡", "requires": { "config": ["channels.qq
 3. **成员列表翻页**时可能返回重复成员，需按 `user.id` 去重
 4. **公告**的两种类型（消息公告和推荐子频道公告）会互相顶替
 5. **日程**的时间戳为毫秒级字符串
-6. **删除操作不可逆**，请谨慎使用
+6. **删除操作不可逆**，必须先确认精确目标并传 `confirmed: true`；批量删除需二次确认并传 `bulkConfirmed: true`
 7. **论坛操作**仅私域机器人可用
 8. **子频道分组**（type=4）的 `position` 必须 >= 2
 9. **日程操作**有频率限制：单个管理员每天 10 次，单个频道每天 100 次
-10. **头像/图标展示**：成员 `user.avatar` 和频道 `icon` 等图片 URL 必须使用 Markdown 图片语法 `![描述](URL)` 展示，禁止作为纯文本或超链接展示
+10. **头像/图标展示**：成员 `user.avatar` 和频道 `icon` 等图片 URL 属于资料信息；默认总结必要字段，只在用户明确需要查看图片时用 Markdown 图片语法 `![描述](URL)` 展示