@zhin.js/adapter-qq 1.1.15 → 1.1.17

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @zhin.js/adapter-qq
 
+## 1.1.17
+
+### Patch Changes
+
+- Updated dependencies [f67883e]
+- Updated dependencies [e23cabc]
+- Updated dependencies [4d728c0]
+- Updated dependencies [eb8feeb]
+- Updated dependencies [24a2b71]
+- Updated dependencies [d0e1fac]
+- Updated dependencies [1ca669a]
+- Updated dependencies [3771f7a]
+- Updated dependencies [4f96ad5]
+  - @zhin.js/core@1.1.52
+  - @zhin.js/adapter@1.1.24
+  - @zhin.js/tool@1.1.11
+  - @zhin.js/host-http@1.1.11
+  - @zhin.js/im-contract@1.1.8
+
+## 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;