@zhin.js/adapter-qq 1.1.15 → 1.1.16

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @zhin.js/adapter-qq
 
+## 1.1.16
+
+### Patch Changes
+
+- 53bc6a0: 适配器配置标签、端点命令和工具反馈支持中英文；复用当前操作语言，保持协议值、用户内容、身份、权限与发送链路不变。Sandbox 展示使用项目语言，QQ 绑定与交互状态保留完整会话身份。
+- Updated dependencies [334e92d]
+- Updated dependencies [f3b7c9f]
+- Updated dependencies [658a5fb]
+- Updated dependencies [144a17b]
+- Updated dependencies [18296cf]
+- Updated dependencies [08e64de]
+- Updated dependencies [9cade30]
+- Updated dependencies [53bc6a0]
+- Updated dependencies [7595136]
+- Updated dependencies [66b6404]
+- Updated dependencies [adb4af2]
+- Updated dependencies [69f9ef6]
+- Updated dependencies [17d1301]
+  - @zhin.js/adapter@1.1.23
+  - @zhin.js/host-http@1.1.10
+  - @zhin.js/core@1.1.51
+  - @zhin.js/permission@1.1.9
+  - @zhin.js/tool@1.1.10
+  - @zhin.js/skill@1.1.10
+  - @zhin.js/im-contract@1.1.7
+  - @zhin.js/agent-feature@1.1.10
+  - @zhin.js/feature-kit@1.1.9
+
 ## 1.1.15
 
 ### Patch Changes

package/README.md

@@ -237,3 +237,9 @@ QQ 当前未实现 canonical `share` 的标题/描述/URL 消息卡片。适配
 可选 `streamProxy: { port: 18443, serverName: "实际网关 hostname" }` 将 WSS 的 TCP 连接导向 `127.0.0.1:port`。需代理固定转发到相同官方网关的 443 端口；SDK 每次仍动态调用 `getWsUrl()`，hostname/443 不匹配会拒绝连接并只记录 hostname，不能自动绕过代理。原始 URL、HTTP Host、TLS SNI 保留，证书验证始终开启。不要填带 query 的 URL。
 
 仅 WSS 入站、心跳和会话认证经过此代理；AppSecret 换 token、网关发现 HTTP、消息 API 和媒体上传仍直连。故障恢复由 `createEndpointLifecycle` 负责，SDK 内置重连关闭，避免双重重连。此入口用于受控网络验收，不提供全局代理或 TLS 验证绕过。
+
+## 语言与绑定会话
+
+Endpoint 管理命令和工具反馈使用当前操作语言。扫码绑定在开始时固定语言，后续二维码刷新、公域/私域选择和结果回复保持一致；`public` / `private` 是稳定的配置值，两种语言都可使用，中文别名只在中文流程中接受。
+
+取消指引使用发起命令时的真实前缀及插件命名空间，不猜测调用方式。确认回复仅接受发起者所在的完整会话（Endpoint、会话、父容器、线程和发送者）；其他成员或线程不会完成该绑定。

package/agents/qq/messages.js

@@ -0,0 +1,24 @@
+// Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { createMessages } from 'zhin.js/i18n';
+export const messages = createMessages({
+    "operationFailed": {
+        "zh-CN": "操作失败",
+        "en": "Operation failed"
+    },
+    "roleAdded": {
+        "zh-CN": "已给成员添加角色",
+        "en": "Role added to the member"
+    },
+    "createFailed": {
+        "zh-CN": "创建失败",
+        "en": "Creation failed"
+    },
+    "namedRoleCreated": {
+        "zh-CN": "角色 \"{p0}\" 创建成功",
+        "en": "Role \"{p0}\" created"
+    },
+    "roleRemoved": {
+        "zh-CN": "已移除成员的角色",
+        "en": "Role removed from the member"
+    }
+});

package/agents/qq/messages.ts

@@ -0,0 +1,24 @@
+import { createMessages } from 'zhin.js/i18n';
+
+export const messages = createMessages({
+  "operationFailed": {
+    "zh-CN": "操作失败",
+    "en": "Operation failed"
+  },
+  "roleAdded": {
+    "zh-CN": "已给成员添加角色",
+    "en": "Role added to the member"
+  },
+  "createFailed": {
+    "zh-CN": "创建失败",
+    "en": "Creation failed"
+  },
+  "namedRoleCreated": {
+    "zh-CN": "角色 \"{p0}\" 创建成功",
+    "en": "Role \"{p0}\" created"
+  },
+  "roleRemoved": {
+    "zh-CN": "已移除成员的角色",
+    "en": "Role removed from the member"
+  }
+});

package/agents/qq/skills/qq/tools/add_role/index.js

@@ -1,4 +1,5 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { messages as t } from "../../../../messages.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { platformPermission } from '@zhin.js/permission';
@@ -17,6 +18,6 @@ export default defineAgentTool({
     async execute({ guild_id, channel_id, user_id, role_id }, context) {
         const client = context.$client;
         const success = await client.addMemberRole(guild_id, channel_id, user_id, role_id);
-        return { success, message: success ? '已给成员添加角色' : '操作失败' };
+        return { success, message: success ? t(context.locale, 'roleAdded') : t(context.locale, 'operationFailed') };
     },
 });

package/agents/qq/skills/qq/tools/add_role/index.ts

@@ -1,3 +1,4 @@
+import { messages as t } from "../../../../messages.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { platformPermission } from '@zhin.js/permission';
@@ -17,6 +18,6 @@ export default defineAgentTool<{ guild_id: string; channel_id: string; user_id:
   async execute({ guild_id, channel_id, user_id, role_id  }: { guild_id: string; channel_id: string; user_id: string; role_id: string }, context) {
     const client = context.$client;
     const success = await client.addMemberRole(guild_id, channel_id, user_id, role_id);
-    return { success, message: success ? '已给成员添加角色' : '操作失败' };
+    return { success, message: success ? t(context.locale, 'roleAdded') : t(context.locale, 'operationFailed') };
   },
 });

package/agents/qq/skills/qq/tools/create_role/index.js

@@ -1,4 +1,5 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { messages as t } from "../../../../messages.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { platformPermission } from '@zhin.js/permission';
@@ -16,6 +17,6 @@ export default defineAgentTool({
     async execute({ guild_id, name, color }, context) {
         const client = context.$client;
         const role = await client.createGuildRole(guild_id, name, color);
-        return { success: !!role, role, message: role ? `角色 "${name}" 创建成功` : '创建失败' };
+        return { success: !!role, role, message: role ? t(context.locale, 'namedRoleCreated', { p0: name }) : t(context.locale, 'createFailed') };
     },
 });

package/agents/qq/skills/qq/tools/create_role/index.ts

@@ -1,3 +1,4 @@
+import { messages as t } from "../../../../messages.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { platformPermission } from '@zhin.js/permission';
@@ -16,6 +17,6 @@ export default defineAgentTool<{ guild_id: string; name: string; color?: number
   async execute({ guild_id, name, color  }: { guild_id: string; name: string; color?: number }, context) {
     const client = context.$client;
     const role = await client.createGuildRole(guild_id, name, color);
-    return { success: !!role, role, message: role ? `角色 "${name}" 创建成功` : '创建失败' };
+    return { success: !!role, role, message: role ? t(context.locale, 'namedRoleCreated', { p0: name }) : t(context.locale, 'createFailed') };
   },
 });

package/agents/qq/skills/qq/tools/remove_role/index.js

@@ -1,4 +1,5 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { messages as t } from "../../../../messages.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { platformPermission } from '@zhin.js/permission';
@@ -17,6 +18,6 @@ export default defineAgentTool({
     async execute({ guild_id, channel_id, user_id, role_id }, context) {
         const client = context.$client;
         const success = await client.removeMemberRole(guild_id, channel_id, user_id, role_id);
-        return { success, message: success ? '已移除成员的角色' : '操作失败' };
+        return { success, message: success ? t(context.locale, 'roleRemoved') : t(context.locale, 'operationFailed') };
     },
 });

package/agents/qq/skills/qq/tools/remove_role/index.ts

@@ -1,3 +1,4 @@
+import { messages as t } from "../../../../messages.js";
 import { defineAgentTool } from '@zhin.js/tool';
 import { z } from 'zod';
 import { platformPermission } from '@zhin.js/permission';
@@ -17,6 +18,6 @@ export default defineAgentTool<{ guild_id: string; channel_id: string; user_id:
   async execute({ guild_id, channel_id, user_id, role_id  }: { guild_id: string; channel_id: string; user_id: string; role_id: string }, context) {
     const client = context.$client;
     const success = await client.removeMemberRole(guild_id, channel_id, user_id, role_id);
-    return { success, message: success ? '已移除成员的角色' : '操作失败' };
+    return { success, message: success ? t(context.locale, 'roleRemoved') : t(context.locale, 'operationFailed') };
   },
 });

package/commands/qq/endpoint/cancel/index.js

@@ -1,11 +1,12 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { endpointCommandForbidden } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { isQqEndpointOperator, QQ_ENDPOINT_FORBIDDEN, qqRuntimeStateToken, runQqEndpointCancel, } from '../definition.js';
+import { isQqEndpointOperator, qqRuntimeStateToken, runQqEndpointCancel, } from '../definition.js';
 export default defineCommand({
-    description: '取消进行中的 QQ 扫码绑定或公域/私域选择',
-    execute({ config, input, use }) {
+    description: '取消进行中的 QQ 扫码绑定或公域/私域选择', descriptionI18n: { en: "Cancel an active QQ QR binding or public/private-domain selection" },
+    execute({ config, input, use, locale }) {
         if (!isQqEndpointOperator(config, input))
-            return QQ_ENDPOINT_FORBIDDEN;
-        return runQqEndpointCancel(use(qqRuntimeStateToken));
+            return endpointCommandForbidden('QQ', locale);
+        return runQqEndpointCancel(use(qqRuntimeStateToken), locale);
     },
 });

package/commands/qq/endpoint/cancel/index.ts

@@ -1,15 +1,15 @@
+import { endpointCommandForbidden } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
 import {
   isQqEndpointOperator,
-  QQ_ENDPOINT_FORBIDDEN,
   qqRuntimeStateToken,
   runQqEndpointCancel,
 } from '../definition.js';
 
 export default defineCommand({
-  description: '取消进行中的 QQ 扫码绑定或公域/私域选择',
-  execute({ config, input, use }) {
-    if (!isQqEndpointOperator(config, input)) return QQ_ENDPOINT_FORBIDDEN;
-    return runQqEndpointCancel(use(qqRuntimeStateToken));
+  description: '取消进行中的 QQ 扫码绑定或公域/私域选择', descriptionI18n: { en: "Cancel an active QQ QR binding or public/private-domain selection" },
+  execute({ config, input, use, locale }) {
+    if (!isQqEndpointOperator(config, input)) return endpointCommandForbidden('QQ', locale);
+    return runQqEndpointCancel(use(qqRuntimeStateToken), locale);
   },
 });

package/commands/qq/endpoint/definition.js

@@ -1,4 +1,6 @@
 // Generated by build-plugin-runtime-entries.mjs. Do not edit.
+import { resolveLocale } from 'zhin.js/i18n';
+import { messages as t } from "../../../lib/i18n.js";
 /**
  * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
  * 通用部分（权限 / list / remove / 配置写回 / .env 持久化）已迁移到
@@ -8,7 +10,7 @@
  */
 import { buildEndpointEnvKey, createEndpointCommands, endpointCommandForbidden, endpointConfigurationStoreToken, extractEndpointCommandReply, formatEndpointList, isEndpointOperator, removeEndpointById, } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { QQ_BOT_KIND_PROMPT, qqCommandSessionKey } from "../../../lib/qq-bot-kind-prompt.js";
+import { qqBotKindPrompt, qqCommandSessionKey } from "../../../lib/qq-bot-kind-prompt.js";
 import { startQqBindFlow } from "../../../lib/qq-bind-flow.js";
 import { defaultQqEndpointIntentFields } from "../../../lib/qq-intents.js";
 import { qqRuntimeStateToken, } from "../../../lib/qq-runtime-state.js";
@@ -28,20 +30,20 @@ export const QQ_ENDPOINT_FORBIDDEN = endpointCommandForbidden('QQ');
 export function extractQqCommandReply(input) {
     return extractEndpointCommandReply(input);
 }
-function busyFooter(state) {
+function busyFooter(state, locale) {
     if (state.bindFlow)
-        return '⚠️ 有进行中的扫码绑定，可用 qq endpoint cancel 取消';
+        return t(locale, 'bindingBusy') + (state.bindFlow.cancelCommand ? `\n${t(locale, 'cancelHint', { command: state.bindFlow.cancelCommand })}` : '');
     if (state.pendingBotKind) {
-        return `⚠️ endpoint「${state.pendingBotKind.endpointId}」等待公域/私域选择，回复 public/private 或 qq endpoint cancel`;
+        return t(locale, 'kindBusy', { id: state.pendingBotKind.endpointId });
     }
     return undefined;
 }
 /** `qq endpoint list`：运行中的 endpoints（本 generation adapter create 注册）+ 配置里的 endpoints */
-export async function runQqEndpointList(state, store) {
+export async function runQqEndpointList(state, store, locale) {
     return formatEndpointList(qqEndpointListSpec, {
         running: state.endpoints.values(),
         configured: await store.list('qq'),
-        footer: busyFooter(state),
+        footer: busyFooter(state, locale), locale,
     });
 }
 const qqEndpointListSpec = {
@@ -50,6 +52,7 @@ const qqEndpointListSpec = {
     describeEntry: (entry) => `appid: ${String(entry.appid)}`,
 };
 async function writeEndpointWithBotKind(pending, botKind, store) {
+    const locale = pending.locale;
     const appidKey = buildEndpointEnvKey('qq', pending.endpointId, 'appid');
     const secretKey = buildEndpointEnvKey('qq', pending.endpointId, 'secret');
     const intentFields = defaultQqEndpointIntentFields(botKind);
@@ -67,9 +70,7 @@ async function writeEndpointWithBotKind(pending, botKind, store) {
             [secretKey]: pending.appSecret,
         },
     });
-    return (`✅ 已按 botKind=${intentFields.botKind} 将 endpoint「${pending.endpointId}」写入 .env 与 ${filePath}。\n` +
-        `intents: ${intentFields.intents.join(', ')}。\n` +
-        '⚠️ 需重启 zhin 后新 endpoint 才会生效。');
+    return t(locale, 'endpointSaved', { kind: intentFields.botKind, id: pending.endpointId, file: filePath, intents: intentFields.intents.join(', ') });
 }
 /**
  * 完成 pending 的公域/私域选择：一次性写 .env + yaml。
@@ -84,9 +85,9 @@ export async function completeQqPendingBotKind(pending, botKind, store) {
  * 后续状态（已扫码 / 成功 / 失败 / 过期刷新）通过 reply 推回当前会话。
  * 扫码成功后凭据暂存内存并询问公域/私域；确认后一次性写 .env + yaml。
  */
-export function runQqEndpointAdd(state, id, reply, store, input) {
+export function runQqEndpointAdd(state, id, reply, store, input, locale = 'zh-CN', cancelCommand, commandHeads) {
     if (state.bindFlow || state.pendingBotKind) {
-        return Promise.resolve('已有进行中的 QQ 机器人绑定或待确认的公域/私域选择，请先发送 qq endpoint cancel 取消后再试');
+        return Promise.resolve(t(locale, 'existingFlow'));
     }
     const endpointId = id?.trim() || undefined;
     const sessionKey = qqCommandSessionKey(input);
@@ -106,11 +107,11 @@ export function runQqEndpointAdd(state, id, reply, store, input) {
         const stop = startQqBindFlow({
             onQrDisplayed: (url) => {
                 // QQ 出站当前仅支持纯文本（富媒体未迁移），二维码只能发链接文本
-                settle(`请用手机 QQ 打开以下链接完成扫码绑定（二维码图片出站暂未支持，故发送链接）：\n${url}`);
+                settle(t(locale, 'scanLink', { url }));
             },
             onQrExpired: async () => {
                 try {
-                    await reply('二维码已过期，正在刷新，请扫描新链接…');
+                    await reply(t(locale, 'qrExpired'));
                 }
                 catch {
                     // same as settle follow-up: best-effort after command scope ends
@@ -127,45 +128,45 @@ export function runQqEndpointAdd(state, id, reply, store, input) {
                             endpointId: finalName,
                             appId,
                             appSecret,
-                            sessionKey: '',
+                            sessionKey: '', locale, cancelCommand,
                         }, 'public', store) +
-                            '\n（当前会话无法交互选择公/私域；私域请手动改配置。）');
+                            t(locale, 'noInteractiveKind'));
                         return;
                     }
                     state.pendingBotKind = {
                         endpointId: finalName,
                         appId,
                         appSecret,
-                        sessionKey,
+                        sessionKey, locale, cancelCommand, commandHeads,
                     };
-                    settle(`✅ 扫码成功！endpoint「${finalName}」。\n` +
-                        QQ_BOT_KIND_PROMPT);
+                    settle(t(locale, 'scanned', { id: finalName, prompt: qqBotKindPrompt(locale, cancelCommand) }));
                 }
                 catch (error) {
-                    settle(`绑定成功但写入配置失败：${error instanceof Error ? error.message : String(error)}`);
+                    settle(t(locale, 'writeFailed', { error: error instanceof Error ? error.message : String(error) }));
                 }
             },
             onFailure: (error) => {
                 state.bindFlow = null;
-                settle(`❌ QQ 绑定失败：${error.message}`);
+                settle(t(locale, 'bindingFailed', { error: error.message }));
             },
-        }, { source: 'zhin' });
-        state.bindFlow = { id: endpointId, stop };
+        }, { source: 'zhin', locale });
+        state.bindFlow = { id: endpointId, stop, locale, cancelCommand, commandHeads };
     });
 }
 /** `qq endpoint cancel`：中止进行中的绑定或待选 botKind */
-export function runQqEndpointCancel(state) {
+export function runQqEndpointCancel(state, preference) {
+    const locale = resolveLocale(state.pendingBotKind?.locale ?? state.bindFlow?.locale ?? preference);
     if (state.bindFlow) {
         state.bindFlow.stop();
         state.bindFlow = null;
-        return '已取消进行中的 QQ 绑定流程';
+        return t(locale, 'cancelled');
     }
     if (state.pendingBotKind) {
         const name = state.pendingBotKind.endpointId;
         state.pendingBotKind = null;
-        return `已取消 endpoint「${name}」的绑定（尚未写入任何文件）`;
+        return t(locale, 'pendingCancelled', { name });
     }
-    return '当前没有进行中的 QQ 绑定流程';
+    return t(locale, 'noFlow');
 }
 /** `qq endpoint remove <id>`：从 zhin.config.yml 移除对应 endpoints 项 */
 export async function runQqEndpointRemove(_state, id, store) {
@@ -178,11 +179,12 @@ export async function runQqEndpointRemove(_state, id, store) {
 export const qqEndpointCommands = createEndpointCommands({
     ...qqEndpointListSpec,
     fields: [
-        { key: 'appid', required: true, env: true, description: 'QQ 机器人 appid' },
-        { key: 'secret', required: true, env: true, description: 'QQ 机器人 secret' },
+        { key: 'appid', required: true, env: true, description: 'QQ 机器人 appid', descriptionI18n: { en: "QQ bot app ID" } },
+        { key: 'secret', required: true, env: true, description: 'QQ 机器人 secret', descriptionI18n: { en: "QQ bot secret" } },
     ],
     running: (use) => use(qqRuntimeStateToken).endpoints.values(),
-    listFooter: (use) => busyFooter(use(qqRuntimeStateToken)),
+    listFooter: (use, locale) => busyFooter(use(qqRuntimeStateToken), locale),
+    addDescriptionI18n: { en: 'Bind a bot through mobile QQ, choose public/private, then save configuration; restart to apply' },
     addDescription: '手机 QQ 扫码绑定机器人：确认公域/私域后一次性写入 .env 与 zhin.config.yml（重启生效）',
-    bindFlow: ({ id, reply, input, use }) => runQqEndpointAdd(use(qqRuntimeStateToken), id, reply, use(endpointConfigurationStoreToken), input),
+    bindFlow: ({ id, reply, input, use, locale, formatCommand }) => runQqEndpointAdd(use(qqRuntimeStateToken), id, reply, use(endpointConfigurationStoreToken), input, locale, formatCommand?.('qq endpoint cancel'), ['qq endpoint list', 'qq endpoint add', 'qq endpoint remove', 'qq endpoint cancel'].flatMap(path => { const head = formatCommand?.(path); return head ? [head] : []; })),
 }, defineCommand);

package/commands/qq/endpoint/definition.ts

@@ -1,3 +1,5 @@
+import { resolveLocale, type Locale } from 'zhin.js/i18n';
+import { messages as t } from '../../../src/i18n.js';
 /**
  * `qq endpoint` 命令的业务逻辑（与命令定义文件分离，便于测试）。
  * 通用部分（权限 / list / remove / 配置写回 / .env 持久化）已迁移到
@@ -19,7 +21,7 @@ import {
   type EndpointConfigurationStore,
 } from 'zhin.js/adapter';
 import { defineCommand } from 'zhin.js/command';
-import { QQ_BOT_KIND_PROMPT, qqCommandSessionKey } from '../../../src/qq-bot-kind-prompt.js';
+import { qqBotKindPrompt, qqCommandSessionKey } from '../../../src/qq-bot-kind-prompt.js';
 import { startQqBindFlow } from '../../../src/qq-bind-flow.js';
 import { defaultQqEndpointIntentFields, type QqBotKind } from '../../../src/qq-intents.js';
 import {
@@ -50,10 +52,10 @@ export function extractQqCommandReply(input: unknown): QqCommandReply {
   return extractEndpointCommandReply(input);
 }
 
-function busyFooter(state: QqRuntimeState): string | undefined {
-  if (state.bindFlow) return '⚠️ 有进行中的扫码绑定，可用 qq endpoint cancel 取消';
+function busyFooter(state: QqRuntimeState, locale?: Locale): string | undefined {
+  if (state.bindFlow) return t(locale, 'bindingBusy') + (state.bindFlow.cancelCommand ? `\n${t(locale, 'cancelHint', { command: state.bindFlow.cancelCommand })}` : '');
   if (state.pendingBotKind) {
-    return `⚠️ endpoint「${state.pendingBotKind.endpointId}」等待公域/私域选择，回复 public/private 或 qq endpoint cancel`;
+    return t(locale, 'kindBusy', { id: state.pendingBotKind.endpointId });
   }
   return undefined;
 }
@@ -62,11 +64,12 @@ function busyFooter(state: QqRuntimeState): string | undefined {
 export async function runQqEndpointList(
   state: QqRuntimeState,
   store: EndpointConfigurationStore,
+  locale?: Locale,
 ): Promise<string> {
   return formatEndpointList(qqEndpointListSpec, {
     running: state.endpoints.values(),
     configured: await store.list('qq'),
-    footer: busyFooter(state),
+    footer: busyFooter(state, locale), locale,
   });
 }
 
@@ -81,6 +84,7 @@ async function writeEndpointWithBotKind(
   botKind: QqBotKind,
   store: EndpointConfigurationStore,
 ): Promise<string> {
+  const locale = pending.locale;
   const appidKey = buildEndpointEnvKey('qq', pending.endpointId, 'appid');
   const secretKey = buildEndpointEnvKey('qq', pending.endpointId, 'secret');
   const intentFields = defaultQqEndpointIntentFields(botKind);
@@ -98,11 +102,7 @@ async function writeEndpointWithBotKind(
       [secretKey]: pending.appSecret,
     },
   });
-  return (
-    `✅ 已按 botKind=${intentFields.botKind} 将 endpoint「${pending.endpointId}」写入 .env 与 ${filePath}。\n` +
-    `intents: ${intentFields.intents.join(', ')}。\n` +
-    '⚠️ 需重启 zhin 后新 endpoint 才会生效。'
-  );
+  return t(locale, 'endpointSaved', { kind: intentFields.botKind, id: pending.endpointId, file: filePath, intents: intentFields.intents.join(', ') });
 }
 
 /**
@@ -129,10 +129,13 @@ export function runQqEndpointAdd(
   reply: QqCommandReply,
   store: EndpointConfigurationStore,
   input?: unknown,
+  locale: Locale = 'zh-CN',
+  cancelCommand?: string,
+  commandHeads?: readonly string[],
 ): Promise<string> {
   if (state.bindFlow || state.pendingBotKind) {
     return Promise.resolve(
-      '已有进行中的 QQ 机器人绑定或待确认的公域/私域选择，请先发送 qq endpoint cancel 取消后再试',
+      t(locale, 'existingFlow'),
     );
   }
   const endpointId = id?.trim() || undefined;
@@ -155,12 +158,12 @@ export function runQqEndpointAdd(
         onQrDisplayed: (url) => {
           // QQ 出站当前仅支持纯文本（富媒体未迁移），二维码只能发链接文本
           settle(
-            `请用手机 QQ 打开以下链接完成扫码绑定（二维码图片出站暂未支持，故发送链接）：\n${url}`,
+            t(locale, 'scanLink', { url }),
           );
         },
         onQrExpired: async () => {
           try {
-            await reply('二维码已过期，正在刷新，请扫描新链接…');
+            await reply(t(locale, 'qrExpired'));
           } catch {
             // same as settle follow-up: best-effort after command scope ends
           }
@@ -179,12 +182,12 @@ export function runQqEndpointAdd(
                     endpointId: finalName,
                     appId,
                     appSecret,
-                    sessionKey: '',
+                    sessionKey: '', locale, cancelCommand,
                   },
                   'public',
                   store,
                 ) +
-                '\n（当前会话无法交互选择公/私域；私域请手动改配置。）',
+                t(locale, 'noInteractiveKind'),
               );
               return;
             }
@@ -193,40 +196,40 @@ export function runQqEndpointAdd(
               endpointId: finalName,
               appId,
               appSecret,
-              sessionKey,
+              sessionKey, locale, cancelCommand, commandHeads,
             };
             settle(
-              `✅ 扫码成功！endpoint「${finalName}」。\n` +
-              QQ_BOT_KIND_PROMPT,
+              t(locale, 'scanned', { id: finalName, prompt: qqBotKindPrompt(locale, cancelCommand) }),
             );
           } catch (error) {
-            settle(`绑定成功但写入配置失败：${error instanceof Error ? error.message : String(error)}`);
+            settle(t(locale, 'writeFailed', { error: error instanceof Error ? error.message : String(error) }));
           }
         },
         onFailure: (error) => {
           state.bindFlow = null;
-          settle(`❌ QQ 绑定失败：${error.message}`);
+          settle(t(locale, 'bindingFailed', { error: error.message }));
         },
       },
-      { source: 'zhin' },
+      { source: 'zhin', locale },
     );
-    state.bindFlow = { id: endpointId, stop };
+    state.bindFlow = { id: endpointId, stop, locale, cancelCommand, commandHeads };
   });
 }
 
 /** `qq endpoint cancel`：中止进行中的绑定或待选 botKind */
-export function runQqEndpointCancel(state: QqRuntimeState): string {
+export function runQqEndpointCancel(state: QqRuntimeState, preference?: Locale): string {
+  const locale = resolveLocale(state.pendingBotKind?.locale ?? state.bindFlow?.locale ?? preference);
   if (state.bindFlow) {
     state.bindFlow.stop();
     state.bindFlow = null;
-    return '已取消进行中的 QQ 绑定流程';
+    return t(locale, 'cancelled');
   }
   if (state.pendingBotKind) {
     const name = state.pendingBotKind.endpointId;
     state.pendingBotKind = null;
-    return `已取消 endpoint「${name}」的绑定（尚未写入任何文件）`;
+    return t(locale, 'pendingCancelled', { name });
   }
-  return '当前没有进行中的 QQ 绑定流程';
+  return t(locale, 'noFlow');
 }
 
 /** `qq endpoint remove <id>`：从 zhin.config.yml 移除对应 endpoints 项 */
@@ -245,19 +248,21 @@ export async function runQqEndpointRemove(
 export const qqEndpointCommands = createEndpointCommands({
   ...qqEndpointListSpec,
   fields: [
-    { key: 'appid', required: true, env: true, description: 'QQ 机器人 appid' },
-    { key: 'secret', required: true, env: true, description: 'QQ 机器人 secret' },
+    { key: 'appid', required: true, env: true, description: 'QQ 机器人 appid', descriptionI18n: { en: "QQ bot app ID" } },
+    { key: 'secret', required: true, env: true, description: 'QQ 机器人 secret', descriptionI18n: { en: "QQ bot secret" } },
   ],
   running: (use) => use(qqRuntimeStateToken).endpoints.values(),
-  listFooter: (use) => busyFooter(use(qqRuntimeStateToken)),
+  listFooter: (use, locale) => busyFooter(use(qqRuntimeStateToken), locale),
+  addDescriptionI18n: { en: 'Bind a bot through mobile QQ, choose public/private, then save configuration; restart to apply' },
   addDescription:
     '手机 QQ 扫码绑定机器人：确认公域/私域后一次性写入 .env 与 zhin.config.yml（重启生效）',
-  bindFlow: ({ id, reply, input, use }) =>
+  bindFlow: ({ id, reply, input, use, locale, formatCommand }) =>
     runQqEndpointAdd(
       use(qqRuntimeStateToken),
       id,
       reply,
       use(endpointConfigurationStoreToken),
-      input,
+      input, locale, formatCommand?.('qq endpoint cancel'),
+      ['qq endpoint list', 'qq endpoint add', 'qq endpoint remove', 'qq endpoint cancel'].flatMap(path => { const head = formatCommand?.(path); return head ? [head] : []; }),
     ),
 }, defineCommand);

package/lib/i18n.d.ts

@@ -0,0 +1 @@
+export declare const messages: (locale: import("zhin.js").Locale | undefined, key: "bindTaskFailed" | "kindPrompt" | "cancelHint" | "bindingBusy" | "kindBusy" | "endpointSaved" | "existingFlow" | "scanLink" | "qrExpired" | "noInteractiveKind" | "scanned" | "writeFailed" | "bindingFailed" | "cancelled" | "pendingCancelled" | "noFlow" | "kindUnrecognized" | "configFailed", values?: import("zhin.js").MessageValues) => string;

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.16",
   "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.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.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.10"
   },
   "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.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.9",
-    "zhin.js": "1.1.15"
+    "@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",

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();

package/src/qq-runtime-state.ts

@@ -14,6 +14,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[];
 }
 
 /**
@@ -26,6 +29,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 {