@zhin.js/adapter-qq 1.1.14 → 1.1.16

package/lib/qq-bot-kind-prompt.js

@@ -1,37 +1,37 @@
+import { conversationRefKey } from '@zhin.js/im-contract';
+import { createDeliveryTarget } from 'zhin.js';
+import { resolveLocale } from 'zhin.js/i18n';
+import { messages as t } from './i18n.js';
 import { parseQqBotKind } from './qq-intents.js';
-/** 从命令/中间件入站消息提取会话键；无法识别时返回 undefined。 */
+/** Bind replies to the complete canonical conversation and actual sender. */
 export function qqCommandSessionKey(input) {
+    if (!input || typeof input !== 'object')
+        return undefined;
     const message = input;
-    const conversation = message?.conversation;
-    const adapter = conversation?.endpoint?.adapter;
-    const endpointKey = conversation?.endpoint?.id;
-    const kind = conversation?.kind;
-    const id = conversation?.id;
-    const sender = message?.sender;
-    if (adapter == null
-        || endpointKey == null
-        || (kind !== 'private' && kind !== 'group' && kind !== 'channel')
-        || typeof id !== 'string'
-        || !id
-        || sender == null
-        || String(sender).trim() === '') {
+    if (typeof message.sender?.id !== 'string' || !message.sender.id.trim())
+        return undefined;
+    try {
+        const conversation = createDeliveryTarget({ conversation: message.conversation });
+        return JSON.stringify([conversationRefKey(conversation), message.sender.id]);
+    }
+    catch {
         return undefined;
     }
-    return `${String(adapter)}\0${String(endpointKey)}\0${kind}\0${id}\0${String(sender).trim()}`;
 }
-/**
- * 解析用户对公域/私域的回复。
- * 接受：public / private / 公域 / 私域（大小写不敏感，可带前后空白）。
- */
-export function parseQqBotKindAnswer(raw) {
+/** Public/private are stable botKind values; Chinese aliases apply only to Chinese flows. */
+export function parseQqBotKindAnswer(raw, locale) {
     const text = String(raw ?? '').trim().toLowerCase();
     if (!text)
         return undefined;
-    if (text === '公域' || text === '公开' || text === '1')
-        return 'public';
-    if (text === '私域' || text === '2')
-        return 'private';
+    if (resolveLocale(locale) === 'zh-CN') {
+        if (text === '公域' || text === '公开' || text === '1')
+            return 'public';
+        if (text === '私域' || text === '2')
+            return 'private';
+    }
     return parseQqBotKind(text);
 }
-export const QQ_BOT_KIND_PROMPT = '请回复 public（公域）或 private（私域），确认后一次性写入 .env 与配置。\n'
-    + '也可发 qq endpoint cancel 取消。';
+export function qqBotKindPrompt(locale, cancelCommand) {
+    return t(locale, 'kindPrompt') + (cancelCommand ? '\n' + t(locale, 'cancelHint', { command: cancelCommand }) : '');
+}
+export const QQ_BOT_KIND_PROMPT = qqBotKindPrompt();

package/lib/qq-runtime-state.d.ts

@@ -6,6 +6,9 @@ export interface QqBindFlowHandle {
     /** 绑定期望的 endpoint id（未指定时为 undefined，成功后取 appId） */
     id?: string;
     stop: () => void;
+    readonly locale?: import('zhin.js/i18n').Locale;
+    readonly cancelCommand?: string;
+    readonly commandHeads?: readonly string[];
 }
 /**
  * 扫码成功后暂存在内存：确认公域/私域后再一次性写 .env + yaml。
@@ -17,6 +20,9 @@ export interface QqPendingBotKind {
     readonly appSecret: string;
     /** 发起 add 的会话键；仅同会话回复可完成选择 */
     readonly sessionKey: string;
+    readonly locale?: import('zhin.js/i18n').Locale;
+    readonly cancelCommand?: string;
+    readonly commandHeads?: readonly string[];
 }
 export interface QqRuntimeState {
     /** 当前 generation 已成功创建的 endpoint（id → 描述） */

package/lib/qq-send.d.ts

@@ -0,0 +1,28 @@
+/**
+ * One QQ outbound send: passive reply when a usable source exists, active message otherwise, with
+ * the fallbacks the platform's error codes allow. Shared by the websocket and webhook Endpoints.
+ *
+ * 1. Each message claims a passive source (explicit reply segment first, else the conversation's
+ *    newest usable msg_id / event_id) with its own msg_seq.
+ * 2. Source unusable (expired, over the limit, invalid id): mark it and send that message once as
+ *    an active message. Never after a timeout: the first request may have been delivered.
+ * 3. Markdown not allowed: resend the same message as plain text.
+ * 4. Active message refused (no permission, quota, user switched it off): remember the conversation
+ *    for a while and fail fast instead of calling the platform again.
+ */
+import type { ConversationRef } from '@zhin.js/im-contract';
+import type { QqOutboundMessage } from './outbound.js';
+import { type QqActiveMessageGate, type QqPassiveReplyLedger, type QqReplySource } from './passive-reply.js';
+import type { QqBotTransport } from './ws.js';
+export interface QqSendContext {
+    readonly bot: QqBotTransport;
+    readonly ledger: QqPassiveReplyLedger;
+    readonly activeGate: QqActiveMessageGate;
+    readonly log: (fields: Record<string, string | number | undefined>) => void;
+}
+/** The reply segment the payload already names, as a passive source. */
+export declare function explicitReplySource(message: QqOutboundMessage): QqReplySource | undefined;
+/** Plain-text version of a Markdown message (buttons dropped); undefined when it has no Markdown. */
+export declare function markdownAsText(message: QqOutboundMessage): QqOutboundMessage | undefined;
+/** Sends every message of one delivery in order; returns the last platform result. */
+export declare function sendQqMessages(context: QqSendContext, conversation: ConversationRef, messages: readonly QqOutboundMessage[]): Promise<unknown>;

package/lib/qq-send.js

@@ -0,0 +1,109 @@
+import { EndpointDeliveryError } from '@zhin.js/im-contract';
+import { QQ_ACTIVE_UNAVAILABLE_CODES, QQ_MARKDOWN_DENIED_CODES, QQ_PASSIVE_SOURCE_CODES, } from './passive-reply.js';
+import { qqDeliveryFailure } from './delivery-error.js';
+import { qqOutboundKind } from './protocol.js';
+function elements(message) {
+    return Array.isArray(message) ? [...message] : [message];
+}
+/** The reply segment the payload already names, as a passive source. */
+export function explicitReplySource(message) {
+    for (const part of elements(message)) {
+        if (typeof part === 'string' || part.type !== 'reply')
+            continue;
+        if (typeof part.data.event_id === 'string' && part.data.event_id)
+            return { event_id: part.data.event_id };
+        if (typeof part.data.id === 'string' && part.data.id)
+            return { id: part.data.id };
+    }
+    return undefined;
+}
+/** Plain-text version of a Markdown message (buttons dropped); undefined when it has no Markdown. */
+export function markdownAsText(message) {
+    const parts = elements(message);
+    if (!parts.some(part => typeof part !== 'string' && (part.type === 'markdown' || part.type === 'keyboard' || part.type === 'button')))
+        return undefined;
+    const text = parts.map(part => {
+        if (typeof part === 'string')
+            return part;
+        if (part.type === 'text')
+            return String(part.data.text ?? '');
+        if (part.type === 'markdown') {
+            return String(part.data.content ?? '')
+                .replace(/!\[[^\]\n]{0,500}\]\(([^)\s]{1,2000})\)/g, '$1')
+                .replace(/\[([^\]\n]{1,500})\]\(([^)\s]{1,2000})\)/g, '$1 $2')
+                .replace(/^#{1,6}\s+/gm, '')
+                .replace(/(\*\*|__|~~|`)/g, '');
+        }
+        return '';
+    }).join('').trim();
+    const kept = parts.filter((part) => typeof part !== 'string' && (part.type === 'reply' || part.type === 'at'));
+    return text ? [...kept, text] : undefined;
+}
+function dispatch(bot, kind, id, message, source, options) {
+    switch (kind) {
+        case 'private': return bot.sendPrivateMessage(id, message, source, options);
+        case 'group': return bot.sendGroupMessage(id, message, source, options);
+        case 'channel': return bot.sendGuildMessage(id, message, source, options);
+        case 'direct':
+            if (!bot.sendDirectMessage)
+                throw new Error('QQ direct message not supported by transport');
+            return bot.sendDirectMessage(id, message, source, options);
+    }
+}
+function platformCode(error) {
+    return qqDeliveryFailure(error).diagnostic.platformCode;
+}
+/** Sends one message, passive if possible; returns the platform result. */
+async function sendOne(context, kind, id, message) {
+    const passive = (body, grant) => dispatch(context.bot, kind, id, body, grant.source, { msgSeq: grant.msgSeq });
+    const active = async (body) => {
+        if (context.activeGate.blocked(kind, id)) {
+            throw new EndpointDeliveryError('platform_rejected', 'QQ active messages are unavailable for this conversation', 'not_sent');
+        }
+        try {
+            return await dispatch(context.bot, kind, id, body);
+        }
+        catch (error) {
+            const code = platformCode(error);
+            if (code !== undefined && QQ_ACTIVE_UNAVAILABLE_CODES.has(code) && context.activeGate.block(kind, id)) {
+                context.log({ op: 'qq_active_unavailable', target: `${kind}:${id}`, platformCode: code });
+            }
+            throw error;
+        }
+    };
+    /** Markdown refused: the same message once more as plain text, under a fresh msg_seq when passive. */
+    const asText = (error, previous) => {
+        const code = platformCode(error);
+        const text = code !== undefined && QQ_MARKDOWN_DENIED_CODES.has(code) ? markdownAsText(message) : undefined;
+        if (!text)
+            throw error;
+        context.log({ op: 'qq_markdown_denied_as_text', target: `${kind}:${id}`, platformCode: code });
+        const retry = previous ? context.ledger.acquire(kind, id, previous.source) : undefined;
+        return retry ? passive(text, retry) : active(text);
+    };
+    const activeOrText = (body) => active(body).catch((error) => asText(error, undefined));
+    const grant = context.ledger.acquire(kind, id, explicitReplySource(message));
+    if (!grant)
+        return activeOrText(message);
+    try {
+        return await passive(message, grant);
+    }
+    catch (error) {
+        const code = platformCode(error);
+        if (code !== undefined && QQ_PASSIVE_SOURCE_CODES.has(code)) {
+            context.ledger.exhaust(kind, id, grant.source);
+            context.log({ op: 'qq_passive_source_unusable', target: `${kind}:${id}`, platformCode: code });
+            return activeOrText(message);
+        }
+        // Anything else, including a timeout (outcome unknown), is not retried as an active message.
+        return asText(error, grant);
+    }
+}
+/** Sends every message of one delivery in order; returns the last platform result. */
+export async function sendQqMessages(context, conversation, messages) {
+    const kind = qqOutboundKind(conversation);
+    let result;
+    for (const message of messages)
+        result = await sendOne(context, kind, conversation.id, message);
+    return result;
+}

package/lib/webhook.js

@@ -73,10 +73,10 @@ export function defaultCreateHttpBot(config) {
         removeAllListeners: () => {
             bot.removeAllListeners(undefined);
         },
-        sendPrivateMessage: (userId, message) => bot.sendPrivateMessage(userId, message),
-        sendGroupMessage: (groupId, message) => bot.sendGroupMessage(groupId, message),
-        sendGuildMessage: (channelId, message) => bot.sendGuildMessage(channelId, message),
-        sendDirectMessage: (guildId, message) => bot.sendDirectMessage(guildId, message),
+        sendPrivateMessage: (userId, message, source, options) => bot.sendPrivateMessage(userId, message, source, options),
+        sendGroupMessage: (groupId, message, source, options) => bot.sendGroupMessage(groupId, message, source, options),
+        sendGuildMessage: (channelId, message, source, options) => bot.sendGuildMessage(channelId, message, source, options),
+        sendDirectMessage: (guildId, message, source, options) => bot.sendDirectMessage(guildId, message, source, options),
         recallPrivateMessage: (userId, messageId) => bot.recallPrivateMessage(userId, messageId),
         recallGroupMessage: (groupId, messageId) => bot.recallGroupMessage(groupId, messageId),
         recallGuildMessage: (channelId, messageId) => bot.recallGuildMessage(channelId, messageId),

package/lib/ws.d.ts

@@ -1,6 +1,11 @@
 import { Bot, type ApproveJoinRequestOptions } from 'qq-official-bot';
 import type { EndpointTransportState } from 'zhin.js/adapter';
 import type { QqOutboundMessage } from './outbound.js';
+import type { QqReplySource } from './passive-reply.js';
+/** Per-send options. `msgSeq` numbers replies to one passive source (qq-official-bot ≥ 1.3.3). */
+export interface QqSendOptions {
+    readonly msgSeq?: number;
+}
 import type { QqInboundMessage, ResolvedQqWebsocketConfig } from './protocol.js';
 /** SDK business surface exposed to plugins without bypassing Endpoint lifecycle ownership. */
 export type QqOfficialApi = Pick<Bot, 'messageService' | 'fileProcessor' | 'guildService' | 'channelService' | 'memberService' | 'permissionService' | 'reactionService' | 'scheduleService' | 'threadService' | 'audioService' | 'botService' | 'groupService' | 'menuPanelService' | 'group' | 'user' | 'channel' | 'direct' | 'guild'>;
@@ -13,10 +18,11 @@ export interface QqBotTransport {
     stop(): Promise<void>;
     on(event: string, listener: (...args: unknown[]) => void): void;
     removeAllListeners(): void;
-    sendPrivateMessage(userId: string, message: QqOutboundMessage): Promise<unknown>;
-    sendGroupMessage(groupId: string, message: QqOutboundMessage): Promise<unknown>;
-    sendGuildMessage(channelId: string, message: QqOutboundMessage): Promise<unknown>;
-    sendDirectMessage?(guildId: string, message: QqOutboundMessage): Promise<unknown>;
+    /** `source` makes it a passive reply; without it the platform treats the message as active. */
+    sendPrivateMessage(userId: string, message: QqOutboundMessage, source?: QqReplySource, options?: QqSendOptions): Promise<unknown>;
+    sendGroupMessage(groupId: string, message: QqOutboundMessage, source?: QqReplySource, options?: QqSendOptions): Promise<unknown>;
+    sendGuildMessage(channelId: string, message: QqOutboundMessage, source?: QqReplySource, options?: QqSendOptions): Promise<unknown>;
+    sendDirectMessage?(guildId: string, message: QqOutboundMessage, source?: QqReplySource, options?: QqSendOptions): Promise<unknown>;
     recallPrivateMessage?(userId: string, messageId: string): Promise<unknown>;
     recallGroupMessage?(groupId: string, messageId: string): Promise<unknown>;
     recallGuildMessage?(channelId: string, messageId: string): Promise<unknown>;

package/lib/ws.js

@@ -240,10 +240,10 @@ export function defaultCreateBot(config) {
                 receiver.removeListener(entry.event, entry.listener);
             bot.removeAllListeners(undefined);
         },
-        sendPrivateMessage: (userId, message) => bot.sendPrivateMessage(userId, message),
-        sendGroupMessage: (groupId, message) => bot.sendGroupMessage(groupId, message),
-        sendGuildMessage: (channelId, message) => bot.sendGuildMessage(channelId, message),
-        sendDirectMessage: (guildId, message) => bot.sendDirectMessage(guildId, message),
+        sendPrivateMessage: (userId, message, source, options) => bot.sendPrivateMessage(userId, message, source, options),
+        sendGroupMessage: (groupId, message, source, options) => bot.sendGroupMessage(groupId, message, source, options),
+        sendGuildMessage: (channelId, message, source, options) => bot.sendGuildMessage(channelId, message, source, options),
+        sendDirectMessage: (guildId, message, source, options) => bot.sendDirectMessage(guildId, message, source, options),
         recallPrivateMessage: (userId, messageId) => bot.recallPrivateMessage(userId, messageId),
         recallGroupMessage: (groupId, messageId) => bot.recallGroupMessage(groupId, messageId),
         recallGuildMessage: (channelId, messageId) => bot.recallGuildMessage(channelId, messageId),

package/middlewares/bot-kind-reply/index.js

@@ -1,8 +1,9 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { messages as t } from "../../lib/i18n.js";
 import { defineMiddleware } from 'zhin.js/middleware';
 import { endpointConfigurationStoreToken } from 'zhin.js/adapter';
 import { completeQqPendingBotKind, } from '../../commands/qq/endpoint/definition.js';
-import { parseQqBotKindAnswer, qqCommandSessionKey, QQ_BOT_KIND_PROMPT, } from "../../lib/qq-bot-kind-prompt.js";
+import { parseQqBotKindAnswer, qqCommandSessionKey, qqBotKindPrompt, } from "../../lib/qq-bot-kind-prompt.js";
 import { qqRuntimeStateToken } from "../../lib/qq-runtime-state.js";
 /**
  * 扫码绑定成功后，在同一会话收取 public/private（或 公域/私域）回复并写入 intents。
@@ -26,13 +27,13 @@ export default defineMiddleware({
         }
         const raw = String(context.input.content ?? '').trim();
         // 让 qq endpoint cancel 等命令继续走命令链
-        if (raw.toLowerCase().startsWith('qq endpoint')) {
+        if ([...(pending.commandHeads ?? []), ...(pending.cancelCommand ? [pending.cancelCommand] : [])].some(head => raw.toLowerCase() === head.toLowerCase() || raw.toLowerCase().startsWith(`${head.toLowerCase()} `))) {
             await next();
             return;
         }
-        const botKind = parseQqBotKindAnswer(raw);
+        const botKind = parseQqBotKindAnswer(raw, pending.locale);
         if (!botKind) {
-            await context.input.$reply?.(`未识别「${raw}」。${QQ_BOT_KIND_PROMPT}`);
+            await context.input.$reply?.(t(pending.locale, 'kindUnrecognized', { raw, prompt: qqBotKindPrompt(pending.locale, pending.cancelCommand) }));
             return;
         }
         try {
@@ -41,7 +42,7 @@ export default defineMiddleware({
             await context.input.$reply?.(text);
         }
         catch (error) {
-            await context.input.$reply?.(`写入配置失败：${error instanceof Error ? error.message : String(error)}`);
+            await context.input.$reply?.(t(pending.locale, 'configFailed', { error: error instanceof Error ? error.message : String(error) }));
         }
     },
 });

package/middlewares/bot-kind-reply/index.ts

@@ -1,3 +1,4 @@
+import { messages as t } from '../../src/i18n.js';
 import { defineMiddleware } from 'zhin.js/middleware';
 import type { CommandMessage } from 'zhin.js/command';
 import { endpointConfigurationStoreToken } from 'zhin.js/adapter';
@@ -7,7 +8,7 @@ import {
 import {
   parseQqBotKindAnswer,
   qqCommandSessionKey,
-  QQ_BOT_KIND_PROMPT,
+  qqBotKindPrompt,
 } from '../../src/qq-bot-kind-prompt.js';
 import { qqRuntimeStateToken } from '../../src/qq-runtime-state.js';
 
@@ -35,15 +36,15 @@ export default defineMiddleware<CommandMessage>({
 
     const raw = String(context.input.content ?? '').trim();
     // 让 qq endpoint cancel 等命令继续走命令链
-    if (raw.toLowerCase().startsWith('qq endpoint')) {
+    if ([...(pending.commandHeads ?? []), ...(pending.cancelCommand ? [pending.cancelCommand] : [])].some(head => raw.toLowerCase() === head.toLowerCase() || raw.toLowerCase().startsWith(`${head.toLowerCase()} `))) {
       await next();
       return;
     }
 
-    const botKind = parseQqBotKindAnswer(raw);
+    const botKind = parseQqBotKindAnswer(raw, pending.locale);
     if (!botKind) {
       await context.input.$reply?.(
-        `未识别「${raw}」。${QQ_BOT_KIND_PROMPT}`,
+        t(pending.locale, 'kindUnrecognized', { raw, prompt: qqBotKindPrompt(pending.locale, pending.cancelCommand) }),
       );
       return;
     }
@@ -58,7 +59,7 @@ export default defineMiddleware<CommandMessage>({
       await context.input.$reply?.(text);
     } catch (error) {
       await context.input.$reply?.(
-        `写入配置失败：${error instanceof Error ? error.message : String(error)}`,
+        t(pending.locale, 'configFailed', { error: error instanceof Error ? error.message : String(error) }),
       );
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-qq",
-  "version": "1.1.14",
+  "version": "1.1.16",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -33,25 +33,25 @@
     "directory": "plugins/adapters/qq"
   },
   "dependencies": {
-    "qq-official-bot": "^1.3.1",
-    "@zhin.js/adapter": "1.1.21",
-    "@zhin.js/agent-feature": "1.1.8",
-    "@zhin.js/core": "1.1.49",
-    "@zhin.js/feature-kit": "1.1.7",
-    "@zhin.js/host-http": "1.1.8",
-    "@zhin.js/im-contract": "1.1.5",
+    "qq-official-bot": "^1.3.3",
+    "@zhin.js/adapter": "1.1.23",
+    "@zhin.js/agent-feature": "1.1.10",
+    "@zhin.js/core": "1.1.51",
+    "@zhin.js/feature-kit": "1.1.9",
+    "@zhin.js/host-http": "1.1.10",
+    "@zhin.js/im-contract": "1.1.7",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/permission": "1.1.7",
-    "@zhin.js/skill": "1.1.8",
-    "@zhin.js/tool": "1.1.8"
+    "@zhin.js/permission": "1.1.9",
+    "@zhin.js/skill": "1.1.10",
+    "@zhin.js/tool": "1.1.10"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.21",
-    "@zhin.js/command": "^1.1.9",
-    "@zhin.js/core": "^1.1.49",
-    "@zhin.js/middleware": "^1.1.8",
-    "zhin.js": "^1.1.14"
+    "@zhin.js/adapter": "^1.1.23",
+    "@zhin.js/command": "^1.1.11",
+    "@zhin.js/core": "^1.1.51",
+    "@zhin.js/middleware": "^1.1.10",
+    "zhin.js": "^1.1.16"
   },
   "peerDependenciesMeta": {
     "@zhin.js/command": {
@@ -72,8 +72,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/host-http": "1.1.8",
-    "zhin.js": "1.1.14"
+    "@zhin.js/host-http": "1.1.10",
+    "zhin.js": "1.1.16"
   },
   "files": [
     "adapters",

package/schema.json

@@ -24,14 +24,24 @@
         "private"
       ],
       "default": "public",
-      "description": "公域/私域：均含 GROUP_AND_C2C_EVENT；频道消息分别为 PUBLIC_GUILD_MESSAGES / GUILD_MESSAGES。未显式配置 intents 时按此展开"
+      "description": "公域/私域：均含 GROUP_AND_C2C_EVENT；频道消息分别为 PUBLIC_GUILD_MESSAGES / GUILD_MESSAGES。未显式配置 intents 时按此展开",
+      "x-i18n": {
+        "en": {
+          "description": "Public/private bot type. Both include GROUP_AND_C2C_EVENT; channel messages use PUBLIC_GUILD_MESSAGES or GUILD_MESSAGES respectively. Used to derive intents when they are not explicitly configured."
+        }
+      }
     },
     "master": {
       "type": [
         "string",
         "number"
       ],
-      "description": "框架 master（endpoint 管理命令、AI/工具权限）；openid。endpoints[i].master 可逐项覆盖"
+      "description": "框架 master（endpoint 管理命令、AI/工具权限）；openid。endpoints[i].master 可逐项覆盖",
+      "x-i18n": {
+        "en": {
+          "description": "Framework masters (openid) for endpoint management and AI/tool permissions. endpoints[i].master can override this value."
+        }
+      }
     },
     "trusted": {
       "type": "array",
@@ -42,14 +52,24 @@
         ],
         "description": "Trusted openid"
       },
-      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加",
+      "x-i18n": {
+        "en": {
+          "description": "Framework trusted users, below master authority. endpoints[i].trusted can add users."
+        }
+      }
     },
     "intents": {
       "type": "array",
       "items": {
         "type": "string"
       },
-      "description": "WebSocket Identify intents；省略时按 botKind 自动生成（public→含 PUBLIC_GUILD_MESSAGES）"
+      "description": "WebSocket Identify intents；省略时按 botKind 自动生成（public→含 PUBLIC_GUILD_MESSAGES）",
+      "x-i18n": {
+        "en": {
+          "description": "WebSocket Identify intents. When omitted, derived from botKind; public includes PUBLIC_GUILD_MESSAGES."
+        }
+      }
     },
     "accessTokenUrl": {
       "type": "string"
@@ -94,7 +114,12 @@
               "string",
               "number"
             ],
-            "description": "本 endpoint 的框架 master（openid）；覆盖顶层 master"
+            "description": "本 endpoint 的框架 master（openid）；覆盖顶层 master",
+            "x-i18n": {
+              "en": {
+                "description": "Framework masters for this endpoint (openid), overriding the top-level master list."
+              }
+            }
           },
           "trusted": {
             "type": "array",
@@ -105,7 +130,12 @@
               ],
               "description": "Trusted openid"
             },
-            "description": "本 endpoint 的 trusted 列表"
+            "description": "本 endpoint 的 trusted 列表",
+            "x-i18n": {
+              "en": {
+                "description": "Trusted users for this endpoint."
+              }
+            }
           },
           "botKind": {
             "type": "string",
@@ -113,14 +143,24 @@
               "public",
               "private"
             ],
-            "description": "覆盖顶层 botKind（公域/私域），用于按 endpoint 生成 intents"
+            "description": "覆盖顶层 botKind（公域/私域），用于按 endpoint 生成 intents",
+            "x-i18n": {
+              "en": {
+                "description": "Override top-level botKind (public/private) when deriving this endpoint's intents."
+              }
+            }
           },
           "intents": {
             "type": "array",
             "items": {
               "type": "string"
             },
-            "description": "覆盖顶层 intents"
+            "description": "覆盖顶层 intents",
+            "x-i18n": {
+              "en": {
+                "description": "Override top-level intents."
+              }
+            }
           },
           "accessTokenUrl": {
             "type": "string"
@@ -164,12 +204,22 @@
           "appid",
           "secret"
         ]
+      },
+      "x-i18n": {
+        "en": {
+          "description": "Multiple accounts: each entry defines an endpoint. id, appid and secret are required; other fields override instance defaults."
+        }
       }
     },
     "commandPrefix": {
       "type": "string",
       "default": "",
-      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖",
+      "x-i18n": {
+        "en": {
+          "description": "Command prefix. The default empty string allows unprefixed commands; '/' requires a leading slash. Each endpoints[i] can override it."
+        }
+      }
     },
     "streamProxy": {
       "type": "object",