@zhin.js/adapter-qq 1.1.15 → 1.1.17

package/lib/i18n.js

@@ -0,0 +1,72 @@
+import { createMessages } from 'zhin.js/i18n';
+export const messages = createMessages({
+    bindTaskFailed: { 'zh-CN': '获取绑定任务失败: {error}', en: 'Could not create the binding task: {error}' },
+    "kindPrompt": {
+        "zh-CN": "请回复 public（公域）或 private（私域），确认后一次性写入 .env 与配置。",
+        "en": "Reply public or private to save .env and configuration together."
+    },
+    "cancelHint": {
+        "zh-CN": "也可发 {command} 取消。",
+        "en": "Send {command} to cancel."
+    },
+    "bindingBusy": {
+        "zh-CN": "⚠️ 有进行中的扫码绑定，请先取消当前绑定流程",
+        "en": "⚠️ A QR binding is in progress; cancel it before starting another"
+    },
+    "kindBusy": {
+        "zh-CN": "⚠️ endpoint「{id}」等待公域/私域选择，请回复 public/private",
+        "en": "⚠️ Endpoint “{id}” is waiting for public/private selection"
+    },
+    "endpointSaved": {
+        "zh-CN": "✅ 已按 botKind={kind} 将 endpoint「{id}」写入 .env 与 {file}。\nintents: {intents}。\n⚠️ 需重启 zhin 后新 endpoint 才会生效。",
+        "en": "✅ Saved endpoint “{id}” with botKind={kind} to .env and {file}.\nintents: {intents}.\n⚠️ Restart zhin to activate the new endpoint."
+    },
+    "existingFlow": {
+        "zh-CN": "已有进行中的 QQ 机器人绑定或待确认的公域/私域选择，请先取消后再试",
+        "en": "A QQ binding or public/private selection is already in progress; cancel it before trying again"
+    },
+    "scanLink": {
+        "zh-CN": "请用手机 QQ 打开以下链接完成扫码绑定（二维码图片出站暂未支持，故发送链接）：\n{url}",
+        "en": "Open this link in mobile QQ to scan and bind the bot:\n{url}"
+    },
+    "qrExpired": {
+        "zh-CN": "二维码已过期，正在刷新，请扫描新链接…",
+        "en": "The QR code expired. Refreshing; scan the new link…"
+    },
+    "noInteractiveKind": {
+        "zh-CN": "\n（当前会话无法交互选择公/私域；私域请手动改配置。）",
+        "en": "\n(This source cannot answer public/private selection. Edit the configuration manually for a private bot.)"
+    },
+    "scanned": {
+        "zh-CN": "✅ 扫码成功！endpoint「{id}」。\n{prompt}",
+        "en": "✅ QR binding succeeded for endpoint “{id}”.\n{prompt}"
+    },
+    "writeFailed": {
+        "zh-CN": "绑定成功但写入配置失败：{error}",
+        "en": "Binding succeeded but configuration could not be saved: {error}"
+    },
+    "bindingFailed": {
+        "zh-CN": "❌ QQ 绑定失败：{error}",
+        "en": "❌ QQ binding failed: {error}"
+    },
+    "cancelled": {
+        "zh-CN": "已取消进行中的 QQ 绑定流程",
+        "en": "The active QQ binding was cancelled"
+    },
+    "pendingCancelled": {
+        "zh-CN": "已取消 endpoint「{name}」的绑定（尚未写入任何文件）",
+        "en": "Binding for endpoint “{name}” cancelled; no files were written"
+    },
+    "noFlow": {
+        "zh-CN": "当前没有进行中的 QQ 绑定流程",
+        "en": "No QQ binding is in progress"
+    },
+    "kindUnrecognized": {
+        "zh-CN": "未识别「{raw}」。{prompt}",
+        "en": "Unrecognized answer “{raw}”. {prompt}"
+    },
+    "configFailed": {
+        "zh-CN": "写入配置失败：{error}",
+        "en": "Could not save configuration: {error}"
+    }
+});

package/lib/qq-bind-flow.d.ts

@@ -1,3 +1,4 @@
+import type { Locale } from 'zhin.js/i18n';
 export interface QqBindCredentials {
     appId: string;
     appSecret: string;
@@ -10,6 +11,7 @@ export interface QqBindCallbacks {
     onQrExpired?: () => void | Promise<void>;
 }
 export interface QqBindFlowOptions {
+    locale?: Locale;
     signal?: AbortSignal;
     source?: string;
 }

package/lib/qq-bind-flow.js

@@ -1,3 +1,4 @@
+import { messages as t } from './i18n.js';
 /**
  * QQ Bot 扫码绑定流程（内联，等价 qqbot-connector startQrConnect）
  */
@@ -60,7 +61,7 @@ export function startQqBindFlow(callbacks, options = {}) {
                 task = await createBindTask();
             }
             catch (err) {
-                throw new Error(`获取绑定任务失败: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+                throw new Error(t(options.locale, 'bindTaskFailed', { error: err instanceof Error ? err.message : String(err) }), { cause: err });
             }
             const connectUrl = buildConnectUrl(task.taskId, options.source ?? 'zhin');
             await callbacks.onQrDisplayed?.(connectUrl);

package/lib/qq-bot-kind-prompt.d.ts

@@ -1,9 +1,8 @@
+import { type Locale } from 'zhin.js/i18n';
 import { type QqBotKind } from './qq-intents.js';
-/** 从命令/中间件入站消息提取会话键；无法识别时返回 undefined。 */
+/** Bind replies to the complete canonical conversation and actual sender. */
 export declare function qqCommandSessionKey(input: unknown): string | undefined;
-/**
- * 解析用户对公域/私域的回复。
- * 接受：public / private / 公域 / 私域（大小写不敏感，可带前后空白）。
- */
-export declare function parseQqBotKindAnswer(raw: unknown): QqBotKind | undefined;
+/** Public/private are stable botKind values; Chinese aliases apply only to Chinese flows. */
+export declare function parseQqBotKindAnswer(raw: unknown, locale?: Locale): QqBotKind | undefined;
+export declare function qqBotKindPrompt(locale?: Locale, cancelCommand?: string): string;
 export declare const QQ_BOT_KIND_PROMPT: string;

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/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.15",
+  "version": "1.1.17",
   "description": "Zhin.js QQ Official adapter for Plugin Runtime (WebSocket gateway)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,24 +34,24 @@
   },
   "dependencies": {
     "qq-official-bot": "^1.3.3",
-    "@zhin.js/adapter": "1.1.22",
-    "@zhin.js/agent-feature": "1.1.9",
-    "@zhin.js/core": "1.1.50",
-    "@zhin.js/feature-kit": "1.1.8",
-    "@zhin.js/host-http": "1.1.9",
-    "@zhin.js/im-contract": "1.1.6",
+    "@zhin.js/adapter": "1.1.24",
+    "@zhin.js/agent-feature": "1.1.10",
+    "@zhin.js/core": "1.1.52",
+    "@zhin.js/feature-kit": "1.1.9",
+    "@zhin.js/host-http": "1.1.11",
+    "@zhin.js/im-contract": "1.1.8",
     "@zhin.js/logger": "1.1.2",
-    "@zhin.js/permission": "1.1.8",
-    "@zhin.js/skill": "1.1.9",
-    "@zhin.js/tool": "1.1.9"
+    "@zhin.js/permission": "1.1.9",
+    "@zhin.js/skill": "1.1.10",
+    "@zhin.js/tool": "1.1.11"
   },
   "peerDependencies": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "^1.1.22",
-    "@zhin.js/command": "^1.1.10",
-    "@zhin.js/core": "^1.1.50",
-    "@zhin.js/middleware": "^1.1.9",
-    "zhin.js": "^1.1.15"
+    "@zhin.js/adapter": "^1.1.24",
+    "@zhin.js/command": "^1.1.11",
+    "@zhin.js/core": "^1.1.52",
+    "@zhin.js/middleware": "^1.1.10",
+    "zhin.js": "^1.1.17"
   },
   "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.9",
-    "zhin.js": "1.1.15"
+    "@zhin.js/host-http": "1.1.11",
+    "zhin.js": "1.1.17"
   },
   "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",

package/src/i18n.ts

@@ -0,0 +1,73 @@
+import { createMessages } from 'zhin.js/i18n';
+
+export const messages = createMessages({
+  bindTaskFailed: { 'zh-CN': '获取绑定任务失败: {error}', en: 'Could not create the binding task: {error}' },
+  "kindPrompt": {
+    "zh-CN": "请回复 public（公域）或 private（私域），确认后一次性写入 .env 与配置。",
+    "en": "Reply public or private to save .env and configuration together."
+  },
+  "cancelHint": {
+    "zh-CN": "也可发 {command} 取消。",
+    "en": "Send {command} to cancel."
+  },
+  "bindingBusy": {
+    "zh-CN": "⚠️ 有进行中的扫码绑定，请先取消当前绑定流程",
+    "en": "⚠️ A QR binding is in progress; cancel it before starting another"
+  },
+  "kindBusy": {
+    "zh-CN": "⚠️ endpoint「{id}」等待公域/私域选择，请回复 public/private",
+    "en": "⚠️ Endpoint “{id}” is waiting for public/private selection"
+  },
+  "endpointSaved": {
+    "zh-CN": "✅ 已按 botKind={kind} 将 endpoint「{id}」写入 .env 与 {file}。\nintents: {intents}。\n⚠️ 需重启 zhin 后新 endpoint 才会生效。",
+    "en": "✅ Saved endpoint “{id}” with botKind={kind} to .env and {file}.\nintents: {intents}.\n⚠️ Restart zhin to activate the new endpoint."
+  },
+  "existingFlow": {
+    "zh-CN": "已有进行中的 QQ 机器人绑定或待确认的公域/私域选择，请先取消后再试",
+    "en": "A QQ binding or public/private selection is already in progress; cancel it before trying again"
+  },
+  "scanLink": {
+    "zh-CN": "请用手机 QQ 打开以下链接完成扫码绑定（二维码图片出站暂未支持，故发送链接）：\n{url}",
+    "en": "Open this link in mobile QQ to scan and bind the bot:\n{url}"
+  },
+  "qrExpired": {
+    "zh-CN": "二维码已过期，正在刷新，请扫描新链接…",
+    "en": "The QR code expired. Refreshing; scan the new link…"
+  },
+  "noInteractiveKind": {
+    "zh-CN": "\n（当前会话无法交互选择公/私域；私域请手动改配置。）",
+    "en": "\n(This source cannot answer public/private selection. Edit the configuration manually for a private bot.)"
+  },
+  "scanned": {
+    "zh-CN": "✅ 扫码成功！endpoint「{id}」。\n{prompt}",
+    "en": "✅ QR binding succeeded for endpoint “{id}”.\n{prompt}"
+  },
+  "writeFailed": {
+    "zh-CN": "绑定成功但写入配置失败：{error}",
+    "en": "Binding succeeded but configuration could not be saved: {error}"
+  },
+  "bindingFailed": {
+    "zh-CN": "❌ QQ 绑定失败：{error}",
+    "en": "❌ QQ binding failed: {error}"
+  },
+  "cancelled": {
+    "zh-CN": "已取消进行中的 QQ 绑定流程",
+    "en": "The active QQ binding was cancelled"
+  },
+  "pendingCancelled": {
+    "zh-CN": "已取消 endpoint「{name}」的绑定（尚未写入任何文件）",
+    "en": "Binding for endpoint “{name}” cancelled; no files were written"
+  },
+  "noFlow": {
+    "zh-CN": "当前没有进行中的 QQ 绑定流程",
+    "en": "No QQ binding is in progress"
+  },
+  "kindUnrecognized": {
+    "zh-CN": "未识别「{raw}」。{prompt}",
+    "en": "Unrecognized answer “{raw}”. {prompt}"
+  },
+  "configFailed": {
+    "zh-CN": "写入配置失败：{error}",
+    "en": "Could not save configuration: {error}"
+  }
+});

package/src/qq-bind-flow.ts

@@ -1,3 +1,5 @@
+import type { Locale } from 'zhin.js/i18n';
+import { messages as t } from './i18n.js';
 /**
  * QQ Bot 扫码绑定流程（内联，等价 qqbot-connector startQrConnect）
  */
@@ -25,6 +27,7 @@ export interface QqBindCallbacks {
 }
 
 export interface QqBindFlowOptions {
+  locale?: Locale;
   signal?: AbortSignal;
   source?: string;
 }
@@ -99,7 +102,7 @@ export function startQqBindFlow(
         task = await createBindTask();
       } catch (err) {
         throw new Error(
-          `获取绑定任务失败: ${err instanceof Error ? err.message : String(err)}`,
+          t(options.locale, 'bindTaskFailed', { error: err instanceof Error ? err.message : String(err) }),
           { cause: err },
         );
       }

package/src/qq-bot-kind-prompt.ts

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