@zhin.js/adapter-qq 1.1.19 → 1.1.21

package/CHANGELOG.md

@@ -1,5 +1,62 @@
 # @zhin.js/adapter-qq
 
+## 1.1.21
+
+### Patch Changes
+
+- af8f803: Use the current Endpoint's platform profile for Agent account identity, with per-field configured fallbacks and scoped, identity-approved profile tools. Keep SOUL first-person and independent of account names. Profile ports preserve the source Client, cancellation, truthful update outcomes and private image authority.
+
+  Adapter Feature API 2.1 and Tool Feature API 1.1 describe the additive profile requirements; new Core, official adapters and generated plugins declare the corresponding floors. Existing compatible API-2.0/API-1.0 plugins remain accepted by the newer providers. npm releases remain patch.
+
+  Private IM assets now bind to the full canonical conversation and principal. Existing IM asset records that contain only the earlier lossy hash remain on disk until their original expiry, but cannot be safely rebound; recapture them. No automatic file deletion, platform profile mutation or workspace SOUL rewrite occurs during upgrade.
+
+- 26fda97: Deliver validated final answers progressively through configured QQ C2C, Telegram drafts, Slack streams, Lark cards and Sandbox updates. Keep complete-message delivery for unsupported scenes, disabled adapters and outbound middleware that does not explicitly support revisions. Discord retains complete-message delivery.
+
+  Preserve source-account leases, media order and confirmed delivery facts across cancellation, capacity rollover and follow-up answer phases. Preview drafts and uncertain outcomes do not become sent history. Bound each reply's semantic snapshot to 1 MiB, retain confirmed prefixes on failure and avoid replaying published answers.
+
+  Project the latest confirmed message revision into paginated conversation history and synchronize Sandbox message updates across connections. Existing adapter implementations and complete-send callers remain compatible.
+
+- 976886c: Preserve confirmed progressive reply content, routing and delivery evidence across cancellation, rollover and closing failures without replaying published text. Keep error dispositions and actual message references, and abort the owning provider request when its functional text consumer fails.
+
+  Enable native Sandbox Markdown through the real Core projection so Console updates retain formatting in one message. Preserve instance-level streaming opt-outs, recall tombstones and multi-page synchronization. The first safe content is immediate; later updates retain the configured pacing, including large valid intervals.
+
+  Keep Slack and Lark Markdown streaming within the current physical message. When continuation formatting cannot be verified, stop and retain confirmed content instead of replaying or silently changing it to plain text. Plain-text continuations retain their original reply route.
+
+  Use rebuildable revision metadata and indexes in the existing conversation event table for bounded SQL history reads. Original event JSON and retention remain unchanged; older writers and models keep their compatible read path. Supported adapter streaming remains enabled by default, with complete-message fallback for disabled settings or outbound middleware without incremental: true.
+
+- 3c1912f: Restore legacy Sandbox streaming history updates while preserving revision precedence, creation order, recall boundaries and browser-cache provenance. Report empty QQ send plans as not sent before any platform call.
+
+  Seek past completed conversation-history backfill batches instead of re-scanning the migrated prefix. Preserve original event data, retention and compatible older writers.
+
+  Report terminal provider quota and billing failures after publication without regeneration, and isolate synchronous diagnostic failures from provider outcomes and retry/fallback decisions.
+
+- Updated dependencies [b88e988]
+- Updated dependencies [f78eb84]
+- Updated dependencies [c15cef9]
+- Updated dependencies [b0c02a2]
+- Updated dependencies [af8f803]
+- Updated dependencies [26fda97]
+- Updated dependencies [976886c]
+- Updated dependencies [032dc96]
+  - @zhin.js/adapter@1.1.27
+  - @zhin.js/client@1.1.23
+  - @zhin.js/im-contract@1.1.10
+  - @zhin.js/core@1.1.55
+  - @zhin.js/tool@1.1.14
+  - @zhin.js/page@1.1.13
+  - @zhin.js/host-http@1.1.13
+  - @zhin.js/agent-feature@1.1.12
+  - @zhin.js/feature-kit@1.1.11
+  - @zhin.js/permission@1.1.11
+  - @zhin.js/skill@1.1.12
+
+## 1.1.20
+
+### Patch Changes
+
+- Updated dependencies [5e878ba]
+  - @zhin.js/page@1.1.12
+
 ## 1.1.19
 
 ### Patch Changes

package/README.md

@@ -44,6 +44,19 @@ pnpm add @zhin.js/adapter-qq
 
 必填字段（`endpoints[i]`）：`id`、`appid`、`secret`。
 
+## 渐进式回复
+
+C2C 私聊默认在生成过程中更新文本或 Markdown，群聊和频道继续使用完整消息发送。Markdown 是否可用仍取决于机器人已开通的平台权限；不支持的内容组合沿用完整发送链路。图片、语音、文件和按钮通过同一回复链路按内容顺序处理。
+
+首段立即发送，后续更新默认至少间隔 500 毫秒。可在实例配置或单个 endpoint 中设置：
+
+```yaml
+streaming: true
+streamingIntervalMs: 500
+```
+
+`streaming: false` 关闭生成中的公开更新，恢复完整消息发送。流式回复与普通回复共用被动消息来源和配额；同一流的分片不重复申领被动回复序号。取消停止后续更新，不自动撤回已确认内容；发送结果未知时不会整条重发。
+
 ## 最小配置
 
 ```yaml

package/agents/qq/skills/qq/SKILL.md

@@ -31,4 +31,4 @@ scopes:
 
 确认频道和成员 ID 后查询详情、维护角色或处置成员；权限与审批由各 Tool 执行。可访问频道列表使用 qq-directory。
 
-`guild_mute_member` 作用于当前频道（0 秒 = 解除），`guild_kick_member` 每次人工审批，可选拉黑和撤回近 N 天消息；机器人需具备频道管理权限，平台拒绝时不要自动重试。
+`guild_mute_member` 作用于当前频道（0 秒 = 解除），`guild_kick_member` 每次人工审批，可选拉黑和撤回近 N 天消息；你需具备频道管理权限，平台拒绝时不要自动重试。

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

@@ -5,7 +5,7 @@ import { platformPermission } from '@zhin.js/permission';
 import { currentGuildChannel } from '../../../../conversation.js';
 import { messages as t } from '../../../../messages.js';
 export default defineAgentTool({
-    description: '禁言 / 解除禁言当前 QQ 频道中的成员；需机器人具备频道管理权限',
+    description: '禁言 / 解除禁言当前 QQ 频道中的成员；需你具备频道管理权限',
     adapter: 'qq',
     scopes: ['channel'],
     tags: ['qq'],

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

@@ -5,7 +5,7 @@ import { currentGuildChannel } from '../../../../conversation.js';
 import { messages as t } from '../../../../messages.js';
 
 export default defineAgentTool({
-  description: '禁言 / 解除禁言当前 QQ 频道中的成员；需机器人具备频道管理权限',
+  description: '禁言 / 解除禁言当前 QQ 频道中的成员；需你具备频道管理权限',
   adapter: 'qq',
   scopes: ['channel'],
   tags: ['qq'],

package/agents/qq/skills/qq-conversation/SKILL.md

@@ -15,10 +15,10 @@ tools:
 ---
 # qq-conversation
 
-Use `conversation_info` before claiming the bot's role or available platform permissions. Group roles come live from the official `bot_state` API for the current endpoint, not from the sender's role. A failed lookup is not evidence that the bot is an ordinary member.
+Use `conversation_info` before claiming your role or available platform permissions. Group roles come live from the official `bot_state` API for the current endpoint, not from the sender's role. A failed lookup is not evidence that you are an ordinary member.
 
-Caller roles authorize a request; bot platform roles determine whether QQ can execute it. They are independent, and a successful inspection does not replace the live check each management tool performs.
+Caller roles authorize a request; your platform roles determine whether QQ can execute it. They are independent, and a successful inspection does not replace the live check each management tool performs.
 
-In guilds the bot role is read from its guild member record (4 owner, 2 admin, 5 child-channel admin). A `channel_admin` record does not say which child channels it governs, so it cannot authorize an operation in the current channel.
+In guilds your role is read from your guild member record (4 owner, 2 admin, 5 child-channel admin). A `channel_admin` record does not say which child channels it governs, so it cannot authorize an operation in the current channel.
 
 The official QQ Bot API has no merged forward, poke, profile like, leave group, group announcement, essence, special title, anonymous, group files or group sign-in. Do not promise or simulate them.

package/agents/qq/skills/qq-conversation/tools/conversation_info/index.js

@@ -14,7 +14,7 @@ function guildRole(roles) {
     return ids.length ? 'member' : 'unknown';
 }
 export default defineAgentTool({
-    description: '读取当前 QQ 官方机器人会话及机器人自己的群／频道身份；区分调用者权限、机器人平台权限和官方不支持的操作',
+    description: '读取当前 QQ 官方机器人会话及你自己的群／频道身份；区分调用者权限、你的平台权限和官方不支持的操作',
     adapter: 'qq',
     requiresApproval: 'never',
     readOnly: true,

package/agents/qq/skills/qq-conversation/tools/conversation_info/index.ts

@@ -12,7 +12,7 @@ function guildRole(roles: readonly unknown[] | undefined): string {
 }
 
 export default defineAgentTool({
-  description: '读取当前 QQ 官方机器人会话及机器人自己的群／频道身份；区分调用者权限、机器人平台权限和官方不支持的操作',
+  description: '读取当前 QQ 官方机器人会话及你自己的群／频道身份；区分调用者权限、你的平台权限和官方不支持的操作',
   adapter: 'qq',
   requiresApproval: 'never',
   readOnly: true,

package/agents/qq/skills/qq-group-admin/SKILL.md

@@ -21,14 +21,14 @@ scopes:
 ---
 # qq-group-admin
 
-Load only when the current group and target member are explicit. Every tool targets the current conversation; the model cannot choose another group. Each tool re-checks the bot's live role (`bot_state`) before acting.
+Load only when the current group and target member are explicit. Every tool targets the current conversation; you cannot choose another group. Each tool re-checks your live role (`bot_state`) before acting.
 
-Official limits (enforced by QQ, not by this skill): the bot must be group owner/admin; only ordinary members (not owner, admins or bots) can be removed or muted; mute is at most 30 days; recall works only within 2 minutes; member removal and join-request APIs are invite-only (11253 = no access).
+Official limits (enforced by QQ, not by this skill): you must be group owner/admin; only ordinary members (not owner, admins or bots) can be removed or muted; mute is at most 30 days; recall works only within 2 minutes; member removal and join-request APIs are invite-only (11253 = no access).
 
 `group_kick` and `handle_join_request` need a fresh human approval each time; show the target member and the reason. A previous approval never authorizes the next action. `set_mute` always needs approval.
 
 Automatic moderation needs a confirmed rule and target group; never invent trigger conditions from permissions alone.
 
-`recall_member_message` keeps the master/admin/trusted/owner requester permission without per-call approval and also works in guild channels (platform-enforced admin rights). To recall the bot's own message, use `qq-messages`.
+`recall_member_message` keeps the master/admin/trusted/owner requester permission without per-call approval and also works in guild channels (platform-enforced admin rights). To recall your own message, use `qq-messages`.
 
 Not available on official bots: invite to group, leave group, special title, anonymous, announcement, essence, poke and group sign-in.

package/agents/qq/skills/qq-group-admin/tools/handle_join_request/index.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { currentGroup, requireGroupManager } from '../../../../conversation.js';
 import { messages as t } from '../../../../messages.js';
 export default defineAgentTool({
-    description: '通过或拒绝当前 QQ 群的一条入群申请；每次人工审批，需机器人为群管理员，官方白名单能力',
+    description: '通过或拒绝当前 QQ 群的一条入群申请；每次人工审批，需你为群管理员，官方白名单能力',
     adapter: 'qq',
     scopes: ['group'],
     permissions: ['role(master,admin,trusted,owner)'],

package/agents/qq/skills/qq-group-admin/tools/handle_join_request/index.ts

@@ -4,7 +4,7 @@ import { currentGroup, requireGroupManager } from '../../../../conversation.js';
 import { messages as t } from '../../../../messages.js';
 
 export default defineAgentTool({
-  description: '通过或拒绝当前 QQ 群的一条入群申请；每次人工审批，需机器人为群管理员，官方白名单能力',
+  description: '通过或拒绝当前 QQ 群的一条入群申请；每次人工审批，需你为群管理员，官方白名单能力',
   adapter: 'qq',
   scopes: ['group'],
   permissions: ['role(master,admin,trusted,owner)'],

package/agents/qq/skills/qq-group-admin/tools/recall_member_message/index.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { currentConversation, recallTarget, requireGroupManager, resolveMessageTarget } from '../../../../conversation.js';
 import { messages as t } from '../../../../messages.js';
 export default defineAgentTool({
-    description: '撤回当前 QQ 群或频道子频道内他人的真实消息；需调用方具备群管发起权限，机器人须为管理员，官方只允许 2 分钟内',
+    description: '撤回当前 QQ 群或频道子频道内他人的真实消息；需调用方具备群管发起权限，你须为管理员，官方只允许 2 分钟内',
     adapter: 'qq',
     scopes: ['group', 'channel'],
     permissions: ['role(master,admin,trusted,owner)'],

package/agents/qq/skills/qq-group-admin/tools/recall_member_message/index.ts

@@ -4,7 +4,7 @@ import { currentConversation, recallTarget, requireGroupManager, resolveMessageT
 import { messages as t } from '../../../../messages.js';
 
 export default defineAgentTool({
-  description: '撤回当前 QQ 群或频道子频道内他人的真实消息；需调用方具备群管发起权限，机器人须为管理员，官方只允许 2 分钟内',
+  description: '撤回当前 QQ 群或频道子频道内他人的真实消息；需调用方具备群管发起权限，你须为管理员，官方只允许 2 分钟内',
   adapter: 'qq',
   scopes: ['group', 'channel'],
   permissions: ['role(master,admin,trusted,owner)'],

package/agents/qq/skills/qq-group-admin/tools/set_mute/index.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { currentGroup, muteQqGroupMember, QQ_GROUP_MUTE_MAX_SECONDS, requireGroupManager } from '../../../../conversation.js';
 import { messages as t } from '../../../../messages.js';
 export default defineAgentTool({
-    description: '禁言 / 解除禁言当前 QQ 群中的普通成员（最长 30 天）；需机器人为群管理员',
+    description: '禁言 / 解除禁言当前 QQ 群中的普通成员（最长 30 天）；需你为群管理员',
     adapter: 'qq',
     scopes: ['group'],
     permissions: ['role(master,admin,trusted,owner)'],

package/agents/qq/skills/qq-group-admin/tools/set_mute/index.ts

@@ -4,7 +4,7 @@ import { currentGroup, muteQqGroupMember, QQ_GROUP_MUTE_MAX_SECONDS, requireGrou
 import { messages as t } from '../../../../messages.js';
 
 export default defineAgentTool({
-  description: '禁言 / 解除禁言当前 QQ 群中的普通成员（最长 30 天）；需机器人为群管理员',
+  description: '禁言 / 解除禁言当前 QQ 群中的普通成员（最长 30 天）；需你为群管理员',
   adapter: 'qq',
   scopes: ['group'],
   permissions: ['role(master,admin,trusted,owner)'],

package/agents/qq/skills/qq-group-directory/SKILL.md

@@ -17,8 +17,8 @@ scopes:
 ---
 # qq-group-directory
 
-All lookups target the current group only. Members are identified by `member_openid`, which is scoped to this bot and group; never derive it from a nickname or reuse it in another group.
+All lookups target the current group only. Members are identified by `member_openid`, which is scoped to your current account and group; never derive it from a nickname or reuse it in another group.
 
-Member list and member detail are invite-only official capabilities. Error 11253 means the bot has no access; report that instead of guessing. `group_members` is paged (≤30 per page, 60 QPM): request further pages only when needed.
+Member list and member detail are invite-only official capabilities. Error 11253 means you have no access; report that instead of guessing. `group_members` is paged (≤30 per page, 60 QPM): request further pages only when needed.
 
-There is no official API for the bot's group list, friend list or arbitrary user profiles, so `group_list`, `friend_list` and `user_info` do not exist on QQ official bots.
+There is no official API for your group list, friend list or arbitrary user profiles, so `group_list`, `friend_list` and `user_info` do not exist on QQ official bots.

package/agents/qq/skills/qq-group-state/SKILL.md

@@ -16,6 +16,6 @@ scopes:
 ---
 # qq-group-state
 
-Read-only views of the current group. `list_muted` returns the global mute rule and members whose mute has not expired. `list_join_requests` and `group_blacklist` are paged invite-only APIs; error 11253 means the bot has no access.
+Read-only views of the current group. `list_muted` returns the global mute rule and members whose mute has not expired. `list_join_requests` and `group_blacklist` are paged invite-only APIs; error 11253 means you have no access.
 
 Act on a join request with `qq-group-admin` → `handle_join_request`, after confirming the applicant. Group files are not exposed by the official API.

package/agents/qq/skills/qq-messages/SKILL.md

@@ -22,6 +22,6 @@ Only use real message IDs from the current conversation. Do not invent IDs or so
 
 `quote_reply` sends a text reply that references one original (passive reply `msg_id` / guild `message_reference`) through the unified outbound pipeline. Use `inspect_conversation_reference` to read an incoming quote when available; it does not send messages.
 
-`recall_own_message` accepts only the bot's own send receipt ID and needs no management role or approval. QQ only recalls messages younger than 2 minutes; never promise success before confirmation or retry an unconfirmed result. To recall another member's message, load `qq-group-admin`.
+`recall_own_message` accepts only your own send receipt ID and needs no management role or approval. QQ only recalls messages younger than 2 minutes; never promise success before confirmation or retry an unconfirmed result. To recall another member's message, load `qq-group-admin`.
 
 Merged forward (`forward_messages`) is not available: the official API cannot send merged-forward records.

package/agents/qq/skills/qq-messages/tools/recall_own_message/index.js

@@ -4,7 +4,7 @@ import { z } from 'zod';
 import { recallTarget, resolveMessageTarget } from '../../../../conversation.js';
 import { messages as t } from '../../../../messages.js';
 export default defineAgentTool({
-    description: '撤回机器人在当前 QQ 会话中自己发送的消息；无需群管角色或逐次审批，官方只允许撤回 2 分钟内的消息',
+    description: '撤回你在当前 QQ 会话中自己发送的消息；无需群管角色或逐次审批，官方只允许撤回 2 分钟内的消息',
     adapter: 'qq',
     scopes: ['private', 'group', 'channel'],
     requiresApproval: 'never',

package/agents/qq/skills/qq-messages/tools/recall_own_message/index.ts

@@ -4,7 +4,7 @@ import { recallTarget, resolveMessageTarget } from '../../../../conversation.js'
 import { messages as t } from '../../../../messages.js';
 
 export default defineAgentTool({
-  description: '撤回机器人在当前 QQ 会话中自己发送的消息；无需群管角色或逐次审批，官方只允许撤回 2 分钟内的消息',
+  description: '撤回你在当前 QQ 会话中自己发送的消息；无需群管角色或逐次审批，官方只允许撤回 2 分钟内的消息',
   adapter: 'qq',
   scopes: ['private', 'group', 'channel'],
   requiresApproval: 'never',

package/lib/adapter.js

@@ -12,7 +12,7 @@ export class QqAdapter extends Adapter {
     get configurationIdentityFields() { return ['id', 'appid']; }
     get configurationIdentityProbeFields() { return ['accessTokenUrl', 'gatewayUrl']; }
     get configurationUpdateFields() {
-        return ['secret', 'mode', 'sandbox', 'intents', 'botKind',
+        return ['secret', 'mode', 'sandbox', 'streaming', 'streamingIntervalMs', 'intents', 'botKind',
             'accessTokenUrl', 'gatewayUrl', 'streamProxy', 'streamProxy.port', 'streamProxy.serverName', 'webhookPath'];
     }
     validateConfiguration(input) { resolveQqConfig(input); }

package/lib/delivery-error.d.ts

@@ -8,6 +8,6 @@ export declare function qqDeliveryFailure(error: unknown): {
         httpStatus: number | undefined;
         platformCode: number | undefined;
         code: string;
-        disposition: "not_sent" | "rejected" | "unknown";
+        disposition: "unknown" | "not_sent" | "rejected";
     };
 };

package/lib/endpoint.js

@@ -1,9 +1,11 @@
+import { createQqSelfProfile } from './self-profile.js';
 import { Bot } from 'qq-official-bot';
 import { installQqUploadDiagnostics } from './upload-diagnostics.js';
 import { projectQqGuildSenderRoles } from './platform-permit.js';
 import { qqDeliveryFailure } from './delivery-error.js';
 import { normalizeQqInteraction } from './interaction.js';
 import { awaitQqStartup } from './start-deadline.js';
+import { createQqStreaming } from './streaming.js';
 import { EndpointDeliveryError } from '@zhin.js/im-contract';
 import { inspectQqGroupMember, inspectQqGroupMemberProfile, inspectQqGroupScene, kickQqGroupMember, moderateQqGroupMember, muteQqGroupMember, qqGroupService, } from './group-admin.js';
 /**
@@ -47,6 +49,8 @@ export class QqWebsocketEndpoint extends Bot {
             start: signal => this.#startFramework(signal), open: () => this.#openFramework(), close: () => this.#closeFramework(),
             stop: () => this.#stopFramework(), send: request => this.#sendFramework(request), name: options.config.id,
             get transportState() { return endpoint.#transportState; }, management: this.#management, control: this.#control,
+            streaming: options.config.streaming !== false ? createQqStreaming(() => this.#requireBot(), this.#passiveReplies, options.config.streamingIntervalMs) : undefined,
+            profile: createQqSelfProfile({ client: this, reportAccount: id => this[endpointSpec].reportSelfUserId(id) }),
         });
         this.#bindBot(this);
     }
@@ -344,6 +348,8 @@ export class QqHttpEndpoint extends Bot {
             stop: () => this.#stopFramework(), send: request => this.#sendFramework(request), name: options.config.id,
             get transportState() { return endpoint.#transportState; },
             management: this.#management, control: this.#control,
+            streaming: options.config.streaming !== false ? createQqStreaming(() => this.#requireBot(), this.#passiveReplies, options.config.streamingIntervalMs) : undefined,
+            profile: createQqSelfProfile({ client: this, reportAccount: id => this[endpointSpec].reportSelfUserId(id) }),
         });
         this.#bindBot(this);
     }

package/lib/outbound.d.ts

@@ -21,16 +21,10 @@ export interface FormatOutboundMessagesOptions {
     readonly imageSizes?: ReadonlyMap<string, QqImageSize>;
 }
 /**
- * 渲染后 payload → 按序发送的 QQ Sendable 列表。
- *
- * QQ 单条消息的 msg_type 只能是一种：富媒体（7，media.file_info）与 markdown/按钮（2）
- * 互斥，SDK 后处理的段会覆盖 msg_type，导致图片被静默丢弃。处理顺序：
- * 1. 公网 URL 图片且已知尺寸：按 QQ markdown 语法 `![图片 #宽px #高px](url)` 嵌入同一
- *    markdown 段（开放平台会下载转存），仍为一条消息；
- * 2. 其余媒体（base64 / 本地渲染图：v2 /files 上传只返回 file_info，拿不到 URL；或尺寸
- *    未知、模板 markdown 无法拼接）降级为独立富媒体消息先发，markdown + 按钮作为最后一条
- *    （返回其消息 ID）。reply 段随每条消息携带，保持被动回复。
- * 不含媒体与 markdown/按钮冲突时与 formatOutbound 一致（单条）。
+ * Preserve the original segment order before formatOutbound merges Markdown.
+ * Public images with known dimensions become inline Markdown at their original
+ * position. Other media form physical-message barriers; reply routing is copied
+ * to every resulting message, without moving text across a media barrier.
  */
 export declare function formatOutboundMessages(payload: unknown, options?: FormatOutboundMessagesOptions): QqOutboundMessage[];
 /**

package/lib/outbound.js

@@ -274,75 +274,66 @@ export function formatOutbound(payload) {
 const SPLIT_MEDIA_TYPES = new Set(['image', 'audio', 'video']);
 /** 走 msg_type=2 的 markdown/按钮段 */
 const MARKDOWN_MESSAGE_TYPES = new Set(['markdown', 'keyboard', 'button']);
-function isElemOf(types) {
-    return (part) => typeof part !== 'string' && types.has(part.type);
+function requireKeyboardMarkdown(messages) {
+    if (!messages.length)
+        throw new EndpointDeliveryError('unsupported_operation', 'QQ payload has no sendable content', 'not_sent');
+    for (const message of messages) {
+        const parts = Array.isArray(message) ? message : [message];
+        if (parts.some(part => typeof part !== 'string' && (part.type === 'keyboard' || part.type === 'button'))
+            && !parts.some(part => typeof part !== 'string' && part.type === 'markdown')) {
+            throw new EndpointDeliveryError('unsupported_operation', 'QQ keyboard requires Markdown in the same physical message', 'not_sent');
+        }
+    }
+    return messages;
 }
 /**
- * 渲染后 payload → 按序发送的 QQ Sendable 列表。
- *
- * QQ 单条消息的 msg_type 只能是一种：富媒体（7，media.file_info）与 markdown/按钮（2）
- * 互斥，SDK 后处理的段会覆盖 msg_type，导致图片被静默丢弃。处理顺序：
- * 1. 公网 URL 图片且已知尺寸：按 QQ markdown 语法 `![图片 #宽px #高px](url)` 嵌入同一
- *    markdown 段（开放平台会下载转存），仍为一条消息；
- * 2. 其余媒体（base64 / 本地渲染图：v2 /files 上传只返回 file_info，拿不到 URL；或尺寸
- *    未知、模板 markdown 无法拼接）降级为独立富媒体消息先发，markdown + 按钮作为最后一条
- *    （返回其消息 ID）。reply 段随每条消息携带，保持被动回复。
- * 不含媒体与 markdown/按钮冲突时与 formatOutbound 一致（单条）。
+ * Preserve the original segment order before formatOutbound merges Markdown.
+ * Public images with known dimensions become inline Markdown at their original
+ * position. Other media form physical-message barriers; reply routing is copied
+ * to every resulting message, without moving text across a media barrier.
  */
 export function formatOutboundMessages(payload, options = {}) {
-    const body = formatOutbound(payload);
-    if (!Array.isArray(body))
-        return [body];
-    const elems = body;
-    const isMedia = isElemOf(SPLIT_MEDIA_TYPES);
-    if (!elems.some(isMedia) || !elems.some(isElemOf(MARKDOWN_MESSAGE_TYPES)))
-        return [body];
-    const markdownIndex = elems.findIndex(isElemOf(new Set(['markdown'])));
-    const markdownElem = markdownIndex >= 0 ? elems[markdownIndex] : undefined;
-    const markdownContent = markdownElem ? markdownElem.data.content : '';
-    const embedded = new Set();
-    let merged;
-    if (typeof markdownContent === 'string') {
-        const before = [];
-        const after = [];
-        elems.forEach((part, index) => {
-            if (!isMedia(part) || part.type !== 'image' || typeof part.data.url !== 'string')
-                return;
-            const size = options.imageSizes?.get(part.data.url);
-            if (!size)
-                return;
-            (markdownIndex < 0 || index < markdownIndex ? before : after)
-                .push(`![图片 #${size.width}px #${size.height}px](${part.data.url})`);
-            embedded.add(part);
-        });
-        if (embedded.size > 0) {
-            merged = { type: 'markdown', data: { content: [...before, markdownContent, ...after].filter((piece) => piece.trim()).join('\n\n') } };
-        }
-    }
-    const replies = elems.filter(isElemOf(new Set(['reply'])));
-    const separate = [];
-    const rest = [];
-    let mergedPlaced = false;
-    for (const part of elems) {
-        if (merged && (part === markdownElem || (!markdownElem && embedded.has(part)))) {
-            if (!mergedPlaced)
-                rest.push(merged);
-            mergedPlaced = true;
-        }
-        else if (embedded.has(part)) {
+    const items = toSegmentList(payload);
+    const rich = items.some(item => typeof item !== 'string' && MARKDOWN_MESSAGE_TYPES.has(item.type));
+    const media = items.some(item => typeof item !== 'string' && SPLIT_MEDIA_TYPES.has(item.type));
+    if (!rich || !media)
+        return requireKeyboardMarkdown([formatOutbound(payload)]);
+    const replies = items.filter(item => typeof item !== 'string' && item.type === 'reply');
+    const templates = items.some(item => typeof item !== 'string' && item.type === 'markdown' && markdownTemplateId(item.data ?? {}));
+    const messages = [];
+    let pending = [];
+    const append = (items) => {
+        const message = formatOutbound(items);
+        const parts = Array.isArray(message) ? message : [message];
+        if (parts.some(part => typeof part === 'string' ? part.length > 0 : part.type !== 'reply'))
+            messages.push(message);
+    };
+    const flush = () => {
+        if (!pending.length)
+            return;
+        append([...replies, ...pending]);
+        pending = [];
+    };
+    for (const item of items) {
+        if (typeof item !== 'string' && item.type === 'reply')
             continue;
-        }
-        else if (isMedia(part)) {
-            separate.push(part);
+        if (typeof item !== 'string' && SPLIT_MEDIA_TYPES.has(item.type)) {
+            const source = item.type === 'image' && isMediaRef(item.data?.media) ? item.data.media : undefined;
+            const size = !templates && source?.kind === 'url' ? options.imageSizes?.get(source.value) : undefined;
+            if (source?.kind === 'url' && size) {
+                pending.push({ type: 'markdown', data: { content: `![图片 #${size.width}px #${size.height}px](${source.value})` } });
+            }
+            else {
+                flush();
+                append([...replies, item]);
+            }
         }
         else {
-            rest.push(part);
+            pending.push(item);
         }
     }
-    return [
-        ...separate.map((item) => (replies.length ? [...replies, item] : item)),
-        rest.length === 1 ? rest[0] : rest,
-    ];
+    flush();
+    return requireKeyboardMarkdown(messages);
 }
 /**
  * 预先探测需要嵌入 markdown 的公网图片尺寸：仅当 payload 同时含图片与 markdown/按钮时，

package/lib/passive-reply.d.ts

@@ -37,6 +37,8 @@ export declare class QqPassiveReplyLedger {
      * newest usable source in the conversation. Undefined when only an active message is possible.
      */
     acquire(kind: QqOutboundKind, conversationId: string, preferred?: QqReplySource): PassiveReplyGrant | undefined;
+    /** Local stream preflight must not reserve a reply before any content exists. */
+    hasUsableSource(kind: QqOutboundKind, conversationId: string, preferred?: QqReplySource): boolean;
     /** The platform said this source can no longer be replied to (expired, over the limit, invalid id). */
     exhaust(kind: QqOutboundKind, conversationId: string, source: QqReplySource): void;
     /** Drop conversations whose every source is past its window. */

package/lib/passive-reply.js

@@ -36,6 +36,17 @@ export class QqPassiveReplyLedger {
      * newest usable source in the conversation. Undefined when only an active message is possible.
      */
     acquire(kind, conversationId, preferred) {
+        const entry = this.#usableSource(kind, conversationId, preferred);
+        if (!entry)
+            return undefined;
+        entry.replies += 1;
+        return { source: entry.source, msgSeq: entry.replies };
+    }
+    /** Local stream preflight must not reserve a reply before any content exists. */
+    hasUsableSource(kind, conversationId, preferred) {
+        return this.#usableSource(kind, conversationId, preferred) !== undefined;
+    }
+    #usableSource(kind, conversationId, preferred) {
         const limit = QQ_PASSIVE_LIMITS[kind];
         const now = this.now();
         const entries = this.#conversations.get(`${kind}:${conversationId}`) ?? [];
@@ -43,12 +54,8 @@ export class QqPassiveReplyLedger {
             && entry.replies < limit.maxReplies
             && now - entry.receivedAt < limit.windowMs - SAFETY_MARGIN_MS;
         const preferredKey = preferred ? sourceKey(preferred) : undefined;
-        const entry = (preferredKey ? entries.find(item => sourceKey(item.source) === preferredKey && usable(item)) : undefined)
+        return (preferredKey ? entries.find(item => sourceKey(item.source) === preferredKey && usable(item)) : undefined)
             ?? [...entries].reverse().find(usable);
-        if (!entry)
-            return undefined;
-        entry.replies += 1;
-        return { source: entry.source, msgSeq: entry.replies };
     }
     /** The platform said this source can no longer be replied to (expired, over the limit, invalid id). */
     exhaust(kind, conversationId, source) {

package/lib/protocol.d.ts

@@ -1,14 +1,18 @@
+import type { EndpointProfileConfiguration } from 'zhin.js/adapter';
 /** QQ Official Bot protocol helpers. Canonicalization is owned by Core. */
 import { type ConversationRef } from '@zhin.js/im-contract';
 import { type AdapterNotifyTarget, type ResolvedAdapterNotifyTarget } from 'zhin.js/adapter';
 /** One endpoint config after AdapterIndex expands `plugins.<instanceKey>.endpoints`. */
-export interface QqEndpointConfig {
+export interface QqEndpointConfig extends EndpointProfileConfiguration {
     readonly id: string;
     readonly appid: string;
     readonly secret: string;
     /** Default `websocket`. `webhook` / `middleware` use httpHostToken POST. */
     readonly mode?: 'websocket' | 'webhook' | 'middleware';
     readonly sandbox?: boolean;
+    /** Publish supported C2C replies while generated; false keeps complete delivery. */
+    readonly streaming?: boolean;
+    readonly streamingIntervalMs?: number;
     /** Explicit intents; when omitted, derived from `botKind` (default public). */
     readonly intents?: readonly string[];
     /** public | private — drives default intents when `intents` omitted. */
@@ -27,6 +31,8 @@ export interface ResolvedQqWebsocketConfig {
     readonly appid: string;
     readonly secret: string;
     readonly sandbox: boolean;
+    readonly streaming?: boolean;
+    readonly streamingIntervalMs?: number;
     readonly intents?: readonly string[];
     readonly accessTokenUrl?: string;
     readonly gatewayUrl?: string;
@@ -41,6 +47,8 @@ export interface ResolvedQqHttpConfig {
     readonly secret: string;
     readonly webhookPath: string;
     readonly sandbox: boolean;
+    readonly streaming?: boolean;
+    readonly streamingIntervalMs?: number;
     readonly notify?: ResolvedAdapterNotifyTarget;
 }
 export type ResolvedQqConfig = ResolvedQqWebsocketConfig | ResolvedQqHttpConfig;

package/lib/protocol.js

@@ -9,6 +9,9 @@ export function resolveQqConfig(config) {
     const appid = requiredEndpointField(config.appid, 'appid');
     const secret = requiredEndpointField(config.secret, 'secret');
     const mode = config.mode ?? 'websocket';
+    const streamingIntervalMs = config.streamingIntervalMs ?? 500;
+    if (!Number.isFinite(streamingIntervalMs) || streamingIntervalMs < 0)
+        throw new TypeError('streamingIntervalMs must be a non-negative finite number');
     const notify = resolveAdapterNotifyTarget(config.notify);
     if (mode === 'webhook' || mode === 'middleware') {
         const webhookPathRaw = config.webhookPath ?? '/qq/webhook';
@@ -21,6 +24,8 @@ export function resolveQqConfig(config) {
             secret,
             webhookPath,
             sandbox: config.sandbox === true,
+            streaming: config.streaming !== false,
+            streamingIntervalMs,
             ...(notify ? { notify } : {}),
         };
     }
@@ -34,6 +39,8 @@ export function resolveQqConfig(config) {
         appid,
         secret,
         sandbox: config.sandbox === true,
+        streaming: config.streaming !== false,
+        streamingIntervalMs,
         intents: resolveQqIntents({
             intents: config.intents,
             botKind: config.botKind,

package/lib/qq-console-spec.js

@@ -6,6 +6,8 @@ export const qqConsoleSpec = {
         { key: 'secret', required: true, env: true, description: 'QQ app secret' },
         { key: 'mode', description: 'websocket, webhook or middleware' },
         { key: 'sandbox', type: 'boolean', description: 'QQ sandbox environment' },
+        { key: 'streaming', type: 'boolean', description: 'Publish supported C2C replies while generating (default true)' },
+        { key: 'streamingIntervalMs', type: 'number', description: 'Delay between reply updates in milliseconds (default 500)' },
         { key: 'botKind', description: 'public or private; existing explicit intents remain authoritative' },
         { key: 'accessTokenUrl', description: 'Configured access-token API URL' },
         { key: 'gatewayUrl', description: 'Configured Gateway discovery URL' },

package/lib/self-profile.d.ts

@@ -0,0 +1,9 @@
+import { type EndpointProfile } from 'zhin.js/adapter';
+import type { Bot } from 'qq-official-bot';
+interface QqSelfProfileOptions {
+    readonly client: Pick<Bot, 'getSelfInfo'>;
+    readonly reportAccount: (id: string) => void;
+}
+/** QQ official Bot.Info has an actual bot id, display username and public avatar URL. */
+export declare function createQqSelfProfile({ client, reportAccount }: QqSelfProfileOptions): EndpointProfile;
+export {};