@zhin.js/adapter-qq 1.1.14 → 1.1.16

package/CHANGELOG.md

@@ -1,5 +1,58 @@
 # @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
+
+- 7d68df6: 精简 Agent 内置固定提示词与消息说明，保留工具、审批和结构化回复能力。适配器 Skill 按会话场景拆分，群／频道管理仅向对应场景披露；提示段与模型消息段支持场景声明，沿用当前回合权限和 generation 投影。
+- e684ade: Upgrade `qq-official-bot` to 1.3.3 and send the passive-reply `msg_seq` the Endpoint assigns per source, so the platform's `msg_id + msg_seq` deduplication protects a retried passive reply.
+- 34c536b: Send QQ replies as passive messages. The Endpoint never passed the user message's `msg_id`, so every reply went out as an active message (quota-limited, blocked when the user turns off active messages). It now records each conversation's recent `msg_id` and interaction `event_id` and replies passively within the platform limits (group 5 min × 5, C2C 60 min × 4, guild 5 min), preferring an explicit reply segment. An expired or exhausted source falls back to one active message; an unknown outcome or a content rejection never does. Conversations that refuse active messages are skipped for an hour, and Markdown the platform does not allow is resent as plain text. Requires `qq-official-bot` 1.3.3, which accepts the Endpoint's per-source `msg_seq` so a retried passive reply is deduplicated by the platform.
+- Updated dependencies [f98025b]
+- Updated dependencies [66ec1a5]
+- Updated dependencies [7d68df6]
+- Updated dependencies [bf0fa9f]
+- Updated dependencies [3326db3]
+- Updated dependencies [e91235e]
+- Updated dependencies [6da2bad]
+- Updated dependencies [3781f1c]
+  - @zhin.js/core@1.1.50
+  - @zhin.js/adapter@1.1.22
+  - @zhin.js/im-contract@1.1.6
+  - @zhin.js/tool@1.1.9
+  - @zhin.js/host-http@1.1.9
+  - @zhin.js/agent-feature@1.1.9
+  - @zhin.js/feature-kit@1.1.8
+  - @zhin.js/permission@1.1.8
+  - @zhin.js/skill@1.1.9
+
 ## 1.1.14
 
 ### Patch Changes

package/README.md

@@ -174,6 +174,28 @@ Markdown + 指令按钮组。按钮值与手动输入共用同一解析入口，
 不支持原生按钮的 Adapter 会在 Core 中把同一 keyboard 语义降级为编号列表，并保存数字到
 payload 的回跳映射。图片、音频、视频和文件仍沿 canonical `MediaRef` 出站链投递。
 
+## 被动回复与主动消息
+
+QQ 开放平台按有没有带上用户消息的 `msg_id`（或事件的 `event_id`）区分被动回复和主动消息。
+主动消息有额度限制，用户还可以在客户端关闭"允许主动发送"。Endpoint 会记录每个会话最近
+收到的 `msg_id`，以及按钮回调（`INTERACTION_CREATE`）的 `event_id`，发送时自动带上：
+
+| 场景 | 被动回复有效期 | 每个来源最多回复 |
+| --- | --- | --- |
+| 群聊 | 5 分钟 | 5 次 |
+| 单聊（C2C） | 60 分钟 | 4 次 |
+| 频道 / 频道私信 | 5 分钟 | 5 次（平台未公布次数） |
+
+- **怎么选来源**：每条消息取会话里最新的可用来源。payload 里有 `reply` 段时，优先用它指向的消息。快到有效期时（提前 15 秒）就不再使用，`msg_seq` 按来源递增，经 `qq-official-bot` 的 `SendOptions.msgSeq` 传给平台。
+- **来源不可用**：平台返回来源过期、次数用完或 msg_id 错误（`40034128`、`40034005`、`304027`、`304026` 等）时，这个来源作废，这条消息改发一次主动消息。
+- **结果未知不重发**：超时、断线这类结果未知的情况，不会改发主动消息，因为第一次请求可能已经送达；会报告 `deliveryUnknown`。
+- **内容被拒不改发主动**：审核、敏感词等内容类错误照常报失败，不改发主动消息，以免消耗主动额度。
+- **主动消息被拒**：平台拒绝主动消息时（无权限 `40034105`、私信已关闭、额度用完等），这个会话 1 小时内不再尝试主动发送，直接报失败。
+- **Markdown 没有权限**：平台拒绝 Markdown 时（`304036`、`304014`、`50056`），同一条消息改成纯文本重发，按钮会被去掉。
+
+公域机器人在群里只能收到 @ 它的消息，所以群聊旁听（`ai.trigger.ambient`）只对拥有全量
+消息权限的私域机器人有意义。
+
 ## 故障排查
 
 | 现象 | 排查 |
@@ -181,7 +203,9 @@ payload 的回跳映射。图片、音频、视频和文件仍沿 canonical `Med
 | Gateway Identify 后断线 | 检查 `botKind` 与 intents；公域机器人不要订阅受限 intent |
 | 二维码绑定后仍离线 | 在 Console 登录待办确认结果，并检查 App ID、Secret 与 Token |
 | Webhook 无事件 | 检查 HTTP Host、公网路径、平台回调与签名参数 |
-| Markdown/按钮发送失败 | 检查平台模板与权限，并按 Endpoint 能力降级 |
+| Markdown/按钮发送失败 | 检查平台模板与权限；无权限时 Endpoint 会自动改发纯文本 |
+| 日志出现 `qq_active_unavailable` | 该会话拒绝主动消息：让用户打开"允许主动发送"，或等用户再发消息后以被动回复送达 |
+| 定时任务、超时通知发不出 | 触发时会话里没有有效期内的 `msg_id`，只能发主动消息；检查主动消息权限与额度 |
 
 ## 许可证
 
@@ -213,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/SKILL.md

@@ -1,11 +1,18 @@
 ---
 name: qq
-platforms: [qq]
-description: QQ 官方机器人频道、角色和成员详情能力。
-keywords: [qq, guild, channel, role, member]
-tags: [adapter, community]
+platforms:
+  - qq
+description: QQ 官方机器人频道、角色和成员详情管理。
+keywords:
+  - qq
+  - guild
+  - channel
+  - role
+  - member
+tags:
+  - adapter
+  - community
 tools:
-  - list_guilds
   - list_channels
   - list_roles
   - create_role
@@ -13,10 +20,9 @@ tools:
   - remove_role
   - channel_info
   - member_detail
+scopes:
+  - channel
 ---
+# QQ 频道
 
-# QQ 官方机器人
-
-先用 `list_guilds` 和 `list_channels` 确认频道上下文。角色操作前用 `list_roles` 获取角色 ID；成员操作前用 `member_detail` 确认目标。创建、授予和移除角色属于写操作，应遵守对应 Tool 的审批策略。
-
-当前 Agent Tool 不提供群踢人、禁言或成员列表能力。
+确认频道和成员 ID 后查询详情或维护角色；权限与审批由各 Tool 执行。可访问频道列表使用 qq-directory。

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';
@@ -11,11 +12,12 @@ export default defineAgentTool({
         role_id: z.string().describe('角色 ID'),
     }),
     adapter: 'qq',
+    scopes: ["channel"],
     tags: ['qq'],
     permissions: [platformPermission('qq', 'manage_roles')],
     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';
@@ -11,11 +12,12 @@ export default defineAgentTool<{ guild_id: string; channel_id: string; user_id:
     role_id: z.string().describe('角色 ID'),
   }),
   adapter: 'qq',
+  scopes: ["channel"],
   tags: ['qq'],
   permissions: [platformPermission('qq', 'manage_roles')],
   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/channel_info/index.js

@@ -8,6 +8,7 @@ export default defineAgentTool({
         channel_id: z.string().describe('子频道 ID'),
     }),
     adapter: 'qq',
+    scopes: ["channel"],
     tags: ['qq'],
     permissions: [platformPermission('qq', 'guild_admin')],
     async execute({ channel_id }, context) {

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

@@ -8,6 +8,7 @@ export default defineAgentTool<{ channel_id: string }>({
     channel_id: z.string().describe('子频道 ID'),
   }),
   adapter: 'qq',
+  scopes: ["channel"],
   tags: ['qq'],
   permissions: [platformPermission('qq', 'guild_admin')],
   async execute({ channel_id  }: { channel_id: string }, context) {

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';
@@ -10,11 +11,12 @@ export default defineAgentTool({
         color: z.number().optional().describe('颜色（RGB 十进制数值）'),
     }),
     adapter: 'qq',
+    scopes: ["channel"],
     tags: ['qq'],
     permissions: [platformPermission('qq', 'guild_owner')],
     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';
@@ -10,11 +11,12 @@ export default defineAgentTool<{ guild_id: string; name: string; color?: number
     color: z.number().optional().describe('颜色（RGB 十进制数值）'),
   }),
   adapter: 'qq',
+  scopes: ["channel"],
   tags: ['qq'],
   permissions: [platformPermission('qq', 'guild_owner')],
   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/list_channels/index.js

@@ -8,6 +8,7 @@ export default defineAgentTool({
         guild_id: z.string().describe('频道 ID'),
     }),
     adapter: 'qq',
+    scopes: ["channel"],
     tags: ['qq'],
     permissions: [platformPermission('qq', 'manage_channels')],
     async execute({ guild_id }, context) {

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

@@ -8,6 +8,7 @@ export default defineAgentTool<{ guild_id: string }>({
     guild_id: z.string().describe('频道 ID'),
   }),
   adapter: 'qq',
+  scopes: ["channel"],
   tags: ['qq'],
   permissions: [platformPermission('qq', 'manage_channels')],
   async execute({ guild_id  }: { guild_id: string }, context) {

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

@@ -8,6 +8,7 @@ export default defineAgentTool({
         guild_id: z.string().describe('频道 ID'),
     }),
     adapter: 'qq',
+    scopes: ["channel"],
     tags: ['qq'],
     permissions: [platformPermission('qq', 'manage_roles')],
     async execute({ guild_id }, context) {

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

@@ -8,6 +8,7 @@ export default defineAgentTool<{ guild_id: string }>({
     guild_id: z.string().describe('频道 ID'),
   }),
   adapter: 'qq',
+  scopes: ["channel"],
   tags: ['qq'],
   permissions: [platformPermission('qq', 'manage_roles')],
   async execute({ guild_id  }: { guild_id: string }, context) {

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

@@ -9,6 +9,7 @@ export default defineAgentTool({
         user_id: z.string().describe('用户 ID'),
     }),
     adapter: 'qq',
+    scopes: ["channel"],
     tags: ['qq'],
     permissions: [platformPermission('qq', 'guild_admin')],
     async execute({ guild_id, user_id }, context) {

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

@@ -9,6 +9,7 @@ export default defineAgentTool<{ guild_id: string; user_id: string }>({
     user_id: z.string().describe('用户 ID'),
   }),
   adapter: 'qq',
+  scopes: ["channel"],
   tags: ['qq'],
   permissions: [platformPermission('qq', 'guild_admin')],
   async execute({ guild_id, user_id  }: { guild_id: string; user_id: string }, context) {

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';
@@ -11,11 +12,12 @@ export default defineAgentTool({
         role_id: z.string().describe('角色 ID'),
     }),
     adapter: 'qq',
+    scopes: ["channel"],
     tags: ['qq'],
     permissions: [platformPermission('qq', 'manage_roles')],
     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';
@@ -11,11 +12,12 @@ export default defineAgentTool<{ guild_id: string; channel_id: string; user_id:
     role_id: z.string().describe('角色 ID'),
   }),
   adapter: 'qq',
+  scopes: ["channel"],
   tags: ['qq'],
   permissions: [platformPermission('qq', 'manage_roles')],
   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/agents/qq/skills/qq-directory/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: qq-directory
+platforms:
+  - qq
+description: QQ 官方机器人可访问的频道列表查询。
+keywords:
+  - qq
+  - list_guilds
+tools:
+  - list_guilds
+---
+# qq-directory
+
+先查询可访问的频道列表，使用工具返回的真实 ID。

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