Spec: QQ group chat through dsh-im with own Bot identities and media understanding #1149

v1.3 release topology — 2026-10-11

Parent: #48 (native sub-issue relationship verified). Project #10; target milestone v1.3. Preserve the existing implementation/qualification scope, claims, accepted evidence and runtime authorization. Native parentage is coordination, not an additional execution blocker.

Problem Statement

People want their Bots to participate in ordinary QQ groups through the same identity, conversation, Inbox and Channel experience they use for Lark, Slack and Discord. Today the maintained dsh-im Provider includes an official QQ adapter, but BotHarness does not expose a qualified QQ account-to-Inbox-to-original-group reply path. Enabling the Provider's standalone QQ chat does not give a PersonaBot its persistent identity, existing Orchestrator, canonical history or shared Channel participation.

The complete need includes mention-driven conversation, optional observation of ordinary group messages, several independently identified Bots in one group, image and file understanding with result delivery, and incoming voice understanding with text answers. A connection indicator, attachment preview or SDK method alone does not satisfy those behaviors.

Solution

Extend the existing official QQ adapter in dsh-im and integrate its public checked capabilities into BotHarness's existing Messaging and Client experience. Implement missing reusable Provider contracts in the maintained fork and submit them to the original dsh-im repository. QQ connections, SDKs, credentials and platform setup remain Provider-owned; PersonaBot identity, Channel placement, Bot Inbox, attention and Outbox remain BotHarness-owned.

Use the shared app-binding and conversation-management direction already accepted for other IM platforms. A qualified QQ app's group mentions reach its bound Bot through the existing default-traffic policy. Ordinary group-message collection remains an explicit choice and defaults to mentions-only. A person may sync an external group to a chosen local Group Channel or leave it Inbox-only. No QQ-specific parallel authorization screen or separate chat runtime is introduced.

Deliver a narrow working path first: one official QQ app, one PersonaBot, one ordinary QQ group, one real mention and one own-identity reply in the original group, including usable Client setup and state. After feedback on that path, extend ordinary-message observation and autonomous participation, multiple identities, image/file processing and incoming voice understanding. These later capabilities are required parts of this specification, not optional omissions. If the actual official account cannot enable a capability, keep the verified subset usable and explain the unavailable capability; the complete specification remains unfinished.

User Stories

1. As a Human, I want to connect an official QQ Bot through dsh-im, so that QQ uses the same maintained Provider as my other IM accounts.
2. As a Human, I want QQ setup to use the Provider's supported authorization flow, so that I do not copy credentials into unrelated BotHarness forms.
3. As a Human, I want the UI to identify the connected account as an official QQ app, so that I know which identity will appear in the group.
4. As a Human, I want setup to distinguish an official QQ Bot from an ordinary QQ account, so that scanning an authorization QR does not imply a different account type.
5. As a Human, I want to bind a connected QQ app through the existing Bind app experience, so that QQ does not require a separate management workflow.
6. As a Human, I want an app already owned by another Bot to remain unavailable for binding, so that Bots cannot impersonate each other.
7. As a Human, I want the actual receiver state and qualified capabilities shown after binding, so that saved configuration is distinguishable from a working connection.
8. As a QQ group member, I want to mention the group's QQ Bot and receive its PersonaBot's answer, so that I can converse without opening BotHarness.
9. As a PersonaBot, I want QQ messages to enter my existing Bot Inbox and Orchestrator, so that my identity and execution do not split into a second chat runtime.
10. As a QQ group member, I want replies in the original group through the Bot's own QQ identity, so that the answer is attributable and reaches the right people.
11. As a Human, I want each new QQ group to inherit mentions-only collection, so that enabling an identity does not automatically collect every group message.
12. As a Human, I want ordinary-message collection to be available only when the platform and receiver actually support it, so that a switch never promises unavailable intake.
13. As a Human, I want to opt a group into ordinary-message collection, so that the Bot can follow the surrounding conversation.
14. As a PersonaBot, I want ordinary messages to use my existing observation and wake policies, so that collecting messages does not force an answer to every message.
15. As a Human, I want direct mentions to remain distinguishable from ordinary conversation, so that explicit requests retain their existing attention behavior.
16. As a Human, I want to sync a QQ group to a selected local Group Channel, so that its received conversation is visible alongside other authorized sources.
17. As a Human, I want an Inbox-only option, so that QQ exchanges need not appear in local Channel history.
18. As a Human, I want Inbox-only QQ messages to stay outside my DM with the Bot, so that external traffic does not become an implicit DM transcript.
19. As a Channel member, I want the QQ sender, source and message association preserved, so that external content is not attributed to a local Human or the receiving Bot.
20. As a Human, I want the existing conversation rules, mute, block and allow-again controls to work for QQ, so that I can manage participation through familiar controls.
21. As a Human, I want a blocked conversation to remain blocked across restart and same-app rebind, so that reconnecting does not reopen it silently.
22. As a Human, I want pausing a route or identity to preserve accepted history, so that stopping future intake does not erase earlier conversation.
23. As a Human, I want restarting or reconnecting to retain my valid configuration without duplicate receivers, so that recovery does not produce duplicate answers.
24. As a Human, I want duplicate deliveries to create no duplicate consideration or replies on the same account path, so that reconnects do not repeat a conversation.
25. As a Human, I want several PersonaBots to participate in the same QQ group using independent QQ app identities, so that group members can distinguish who is speaking.
26. As a PersonaBot, I want shared-source replies to use only my own authorized app, so that reading a shared Channel does not lend me another Bot's identity.
27. As a Human, I want ambiguous own-app destinations to be refused clearly, so that the Host does not guess which identity should answer.
28. As a Human, I want app-scoped QQ addresses to remain distinct, so that unrelated groups or members are not merged by names or similar identifiers.
29. As a QQ group member, I want a long task's result to reach the group when proactive sending is allowed, so that expiry of the original reply window does not lose the result.
30. As a Human, I want an expired reply to use a separately authorized proactive post, so that permission for a reply is not silently widened.
31. As a Human, I want a result retained locally with a clear explanation when proactive sending is unavailable, so that I can still inspect completed work.
32. As a Human, I want ambiguous send outcomes to remain visible without automatic resending, so that a timeout does not generate a second copy.
33. As a Human, I want native reply limits and frequency restrictions reported honestly, so that platform refusal is distinguishable from a model failure.
34. As a Human, I want unavailable full-message or proactive capabilities explained while verified mention chat remains usable, so that I can understand the actual delivered subset.
35. As a QQ group member, I want to send an image and have the Bot understand its content, so that I can ask visual questions in the group.
36. As a Human Channel participant, I want received images in their originating message with the existing preview experience, so that I can inspect the same conversation locally.
37. As a PersonaBot, I want to send an authorized image result to the original QQ group, so that visual work can be returned where it was requested.
38. As a QQ group member, I want to send a file for the Bot to read or process, so that QQ can initiate the same file workflows as existing IM integrations.
39. As a PersonaBot, I want to process an independent authorized working copy, so that producing a result does not overwrite the received original.
40. As a QQ group member, I want the resulting file returned to the original group, so that I can use the completed work without visiting BotHarness.
41. As a Human, I want file type, known size and acquisition failures visible, so that unsupported or oversized content is not treated as successfully read.
42. As a QQ group member, I want the Bot to understand my incoming voice message and answer in text, so that I can speak a request without requiring voice output.
43. As a Human Channel participant, I want incoming voice playable on demand when the format is supported, so that I can inspect the original request.
44. As a Human, I want platform transcription, recognized content and unavailable recognition distinguished, so that audio transport is not mistaken for understanding.
45. As a Human, I want media collection to follow the same conversation scope and authority as text, so that adding media does not bypass collection or access choices.
46. As a Human, I want Channel previews not to change Bot Observation or wake behavior, so that my inspection is separate from the Bot reading content.
47. As a Human, I want history to begin with messages received after enabling the integration, so that setup does not imply an unverified import of old QQ messages.
48. As a Human, I want retained local history available after restart and missed-message gaps explained, so that I understand what the Bot actually received.
49. As a Human, I want usable loading, failure, disconnected and rebind states in the existing Client, so that I can recover without guessing at hidden configuration.
50. As a Human, I want each completed slice demonstrated through a real QQ group and the actual Client, so that reported support matches observable behavior.
51. As a maintainer, I want reusable QQ contract improvements contributed to the maintained fork and upstream, so that the integration does not become a second provider codebase.
52. As a maintainer, I want separately qualified and reproducible Provider artifacts, so that an upstream merge or package version alone is not treated as runtime proof.

Implementation Decisions

1. Platform and scope. The selected transport is the existing official QQ Bot adapter in dsh-im. This specification concerns ordinary QQ groups, not QQ guild channels. Group membership is established on QQ through its real administration and app authorization; local Channel membership does not add an app to a QQ group. NapCat and OneBot are not part of this implementation.
2. Provider ownership. Extend the maintained dsh-im fork's public Service Definition for authenticated QQ account description, exclusive inbound Consumer, normalized message provenance, checked original-group replies, applicable proactive sends and native receipts. Keep SDKs, token refresh, credentials, account setup and connection lifecycle in the Provider. Submit reusable changes to the original dsh-im repository without adding PersonaBot domain behavior there.
3. Shared app-binding policy. Reuse the accepted app-binding and conversation-entry model, including qualified default traffic, new-conversation handling, conversation blocks, own-app replies and the existing fallback for Providers without conversation capabilities. Do not recreate the older mandatory saved-target and per-group-consent onboarding for every QQ mention. Ordinary collection and local Channel placement remain explicit. QQ qualifies group mentions in this specification; the shared default-traffic model does not automatically qualify QQ private messages.
4. Identity multiplicity. Each QQ app has one PersonaBot owner. Several PersonaBots may participate in one native group through independent apps. Preserve the shared model's support for several apps per PersonaBot; do not introduce a QQ-specific one-app-per-platform constraint. Refuse an ambiguous responder-owned destination under the shared reply contract. The first runnable slice uses one app, one Bot and one group.
5. Current-state qualification. The existing maintained QQ adapter uses the official QQ SDK and an explicit WebSocket transport; its standalone bridge filters out non-mention group events and lacks the qualified PersonaBot intake contract. Neither the existing QR flow nor its proactive SDK method proves the full BotHarness path. Inspect the implementation baseline again before editing; avoid treating old research revisions as permanent API guarantees.
6. Official capability evidence. Current official documentation describes both mentioned and ordinary group events, as well as proactive group messages. Actual account eligibility, the full-message switch, event delivery, deployment transport, native send result and app publication conditions require real qualification. Verify the selected SDK against current official authentication and domain contracts. Use the Provider's existing transport ownership; if transport must change, make and qualify that change there.
7. Canonical admission. One account-level exclusive Consumer feeds BotHarness Messaging. Trusted normalization preserves the authenticated account, app-scoped conversation and sender addresses, native message and delivery identifiers, timestamp, mention evidence and original reply association. Commit the canonical Source Event and applicable Channel placements and Inbox Admissions before acknowledging acceptance. Do not also execute the Provider's standalone Session path.
8. Native identity semantics. QQ app-scoped OpenIDs are not numeric QQ account or group IDs and are not globally comparable across apps. Names remain presentation. Do not fabricate a native thread or equate a quote with a Slack or Lark topic. Detect a trusted group mention through qualified event evidence rather than searching rendered text alone.
9. Collection and participation. Group conversation entries start with mentions-only collection. Ordinary-message collection requires explicit effective policy, qualified platform access and actual ordinary delivery on the current receiver lease. Collection, Inbox Admission, Observation, wake and external speech remain separate decisions. Reuse existing count/time harvest, silent observation and safe-turn behavior rather than introducing a QQ scheduler.
10. Placement. Reuse existing explicit conversation-to-Channel synchronization and Inbox-only intake. A native message has one canonical authority on its account path; routing references it rather than copying content. Inbox-only creates no implicit Human DM placement. Shared Channel reading grants neither another Bot's sender identity nor new platform access.
11. Original replies and delayed results. Within the platform's valid reply window, send through the trusted source-bound reply route and its checked receipt. If a reply is definitely expired or otherwise definitely not started because its window ended, a completed result may use a distinct proactive Outbox action only when current platform reach and the effective shared authorization permit it. The saved-target Service Grant fallback remains applicable where required by the shared Provider contract. Never reinterpret an unknown started send as a fresh proactive attempt. Preserve and explain locally retained results when posting is unavailable.
12. Native limits. Respect qualified reply deadlines, per-source reply counts, sequence semantics, app and group frequency limits and QQ-side proactive controls. Keep those platform restrictions separate from the existing product participation and loop policies. Do not stream model deltas as repeated group messages. Platform acceptance is not evidence of a group member reading a message.
13. Lifecycle. Binding, conversation block, route pause, identity pause, unbind, PersonaBot archive and Provider disposal retain their owning semantics. Recheck authority immediately before external effects and media acquisition or serving. Release subscriptions, pending calls, heartbeats and timers with the owning Plugin/Fiber; a lost lease does not authorize a fallback standalone Session. Restart restores only valid registrations and retains known source and Outbox facts without blindly retrying unknown outcomes.
14. Multiple identities and echoes. Qualify each app's independent account/conversation mapping. Do not merge cross-app receipts or Source Events merely because they represent a similarly named group or apparently similar text. Reuse correlated Provider Echo handling and existing loop controls so own send echoes do not generate fresh attention or recursive sends. Multiple-Bot completion requires real independently attributed replies and no identity borrowing.
15. Media authority and display. Extend the existing checked source-file and media contracts, canonical Attachment owner and cross-provider presentation model. Preserve the native message boundary, content order where known and trusted source association. Keep private resource URLs and access material in the Provider. Channel previews, downloads and playback remain Human presentation, not automatic Bot Observation or new admissions.
16. Images. The complete image slice includes qualified image intake, local display, actual image understanding through a supported model or tool path and own-identity result-image delivery to the original group. A Human preview alone does not qualify understanding. Reuse the existing model-media and attachment mechanisms where applicable; document any genuinely new capability boundary when its implementation is selected.
17. Files. The complete file slice includes checked acquisition, explicit access by the Bot, an independent authorized working copy, processing and one checked result-file reply to the original group. Preserve originals and native association. Reuse existing Workspace Grant and Tool Approval Rules; receiving an attachment does not automatically execute it or authorize workspace writes.
18. Incoming voice. The complete voice slice includes actual voice intake, bounded source-bound original/playback access where supported, recognized content entering the existing Orchestrator and a checked text answer. Platform transcription is preferred when demonstrably available; otherwise select and qualify a supported model or speech-recognition capability before claiming understanding. Record actual transcription provenance and explicit unavailable states. No automatic voice synthesis or outgoing voice reply is required by this specification.
19. Media bounds. Apply existing acquisition, decoding, cancellation and output budgets together with the actual QQ limits. Known original metadata stays distinct from validated or derived metadata. Unsupported formats, unavailable model/recognition capability, expired resources, oversized inputs and revoked access are explicit failures or unavailable states. Do not invent a transcript, infer successful understanding from a download, or bypass a failed check through a raw public URL.
20. History. Start collection with newly eligible messages after enablement. Retain already committed local history and expose reception gaps truthfully. Paused, blocked, held or disconnected intervals are not silently backfilled. A later reliable native history capability requires its own bounded qualification; it is not a prerequisite assumed to exist here.
21. Client and diagnostics. Extend the current identity/conversation/source controls and shared media components using existing DSH Slots and Typert/API Gateway transport. Show saved preference separately from actual connection, qualified capability and effective permission. Publish stable bounded developer lifecycle diagnostics for connection, qualification, refusal, duration and disposal without credentials or message dumps. Do not create a second API Gateway interceptor or Client configuration authority.
22. Durable changes. Reuse owning Messaging, attachment and operational database modules. Extend persisted schemas only for demonstrated QQ requirements, through existing migrations and recovery rules; preserve existing provider behavior and historical records. QQ transport fields must not become a second message, identity or credential store. Record any newly necessary architecture decision and integrate it into the living architecture when that change is actually selected.
23. Delivery. The first implementation slice includes the owning Provider contract, Core admission/reply path, Client configuration and observable state, and a real QQ group test. Provider-only scaffolding and disconnected UI are preparatory work. Validate and obtain first-slice feedback before expanding ordinary collection, identity multiplicity or media. The specification is complete only when all confirmed behaviors have their own evidence; a functional text subset may ship while the remaining scope is explicitly unfinished.
24. Artifact and upstream policy. Pin and qualify an immutable maintained Provider input and its separately versioned product artifact on the supported DSH revision. Submit generic contract improvements upstream. Continue with a qualified fork without making an upstream review delay a reason to duplicate the integration. Replacing it with an upstream release requires independent artifact and runtime qualification; a merged PR is not a compatible published artifact.

Testing Decisions

1. Confirmed highest useful seam. The Human confirmed this primary verification path: QQ inbound message → public checked dsh-im contract → canonical Source Event and Bot Inbox, with optional Channel placement → existing Orchestrator → own-identity original-group send and native receipt. Automated integration regressions enter through public Provider/Messaging contracts and assert externally meaningful outcomes, not private helper call sequences or enum membership.
2. Modules and prior art. Reuse the existing Lark/Slack/Discord Messaging admission, original-location reply, shared-source and lifecycle integration coverage; existing identity/conversation Client interaction coverage; Slack real file-processing evidence; and cross-provider media and WeChat voice provenance/playback tests. Provider contract tests verify the QQ normalization and checked-operation boundary. Controlled transports and deterministic Orchestrator execution in automated tests are not described as real QQ or live-model proof.
3. First real tracer. In an isolated verified DSH Profile, bind a real official QQ app, add it to a dedicated ordinary QQ QA group through the supported platform flow, compose a real mention and observe one canonical admission, actual Orchestrator model execution and one independently inspected native own-app reply in that same group. Exercise the corresponding Client setup and state. Record exact Core, Client, Provider, SDK and DSH revisions.
4. Identity and authorization. Cover wrong-account and forged route evidence, another conversation, stale or revoked authority, blocked and held conversations where applicable, paused identities, archived Bots and ambiguous responder-owned identities. Unauthorized attempts produce no admitted source, unintended wake or external effect. A shared read never authorizes sending through another member's app.
5. Commit and deduplication. Prove acknowledgement follows canonical commit, repeated delivery on the same account path causes no duplicate consideration or reply, overlapping local routes share their canonical source, and a conflicting replay is not treated as a replacement success. Test restart through actual persisted authority rather than only recreating an empty fixture.
6. Lifecycle and uncertainty. Cover receiver exclusivity, cold start, real reconnect/disposal, late callbacks from lost leases and Provider replacement. Missing connection and definite pre-send failure are distinct from a request with unknown completion. Assert unknown outcomes survive refresh/restart and are neither resent nor converted to proactive posts automatically.
7. Ordinary participation. Prove a fresh actual non-mentioned QQ group event on the current receiver lease. Demonstrate mentions-only refusal of ordinary content, explicit opt-in collection, independent member attention, at least one ordinary-context read and one intentional externally visible participation under current posting authority. Receiving every message must not cause an answer to every message.
8. Delayed results. With controlled time, verify reply expiry and count restrictions, definitely unstarted expiry permitting only a separately authorized proactive action, unavailable proactive rights retaining the result locally, and unknown started replies refusing automatic fallback. Complete a real delayed-task/post path only if the actual QQ account supports it and inspect its native receipt and original destination.
9. Multiple Bots. Use independent real apps in the same QA group, explicit local source mapping and distinct PersonaBots. Verify trustworthy mention attribution and each reply's own native identity, absence of identity borrowing, correct independent participation and echo suppression. Cross-app message deduplication is not invented to hide separate platform identities.
10. Image understanding. Use synthetic visual content requiring actual visual interpretation. Verify original message/media association, authorized display, the model/tool's observed content and an independently inspected result image in the original QQ group. A caption-only response, fixture assertion or Human preview does not qualify image understanding.
11. File processing. Send a synthetic file with known content, acquire and process an independent copy using existing permissions, return the result to the original group and independently compare native association, original/result bytes and expected result content. Reuse existing over-limit, invalid resource, cancellation and authority-revocation regressions.
12. Voice understanding. Send a real synthetic spoken request, distinguish platform text from recognition output, verify source-bound playback when supported, confirm the actual Orchestrator received recognized content and independently inspect its text answer in the group. Separately cover missing transcript, unavailable recognition, unsupported codec and interrupted acquisition. Playback or raw audio retrieval alone does not pass this acceptance.
13. Client and history. Through the actual Client, operate binding/source sync, mentions/all where qualified, pause/resume and shared controls; inspect committed states after errors, refresh and restart. Verify Channel versus Inbox-only placement, retained local history, visible gaps, non-autoplay voice playback and explicit media failure states. Cover keyboard/focus and readable light/dark behavior for changed interactions.
14. Evidence and release qualification. Each user-facing tracer supplies a runnable verification path and matched real before/after UI evidence under the repository's PR rules. Use dedicated synthetic QA content and sanitized assertions; exclude credentials, live authorization QR codes, private login URLs and unrelated group messages. Installed-product verification is distinct from source-build success and upstream merge. Complete the required formatting, static checks, focused regressions and build for each change, and pause after the first runnable slice for Human feedback before breadth expansion.

Out of Scope

• NapCat, OneBot, personal QQ-account login and automatic switching between official and ordinary-account identities.
• QQ guild/channel integration, QQ private-message qualification, automatic group joining or a QQ administration control plane.
• Automatically synthesized voice responses, outgoing native voice replies, video understanding or video delivery.
• A separate QQ Session runner, QQ-specific memory store, new wake scheduler, duplicated credential manager or second content authority.
• A QQ-specific replacement for the accepted shared app-binding, conversation-management or media-presentation specifications.
• Implicitly mirroring Inbox-only sources into Human–PersonaBot DMs or forwarding every local Channel reply to QQ.
• Borrowing another Bot's QQ app identity or merging app-scoped groups, members or messages by display name or text similarity.
• Full remote group-history import, guaranteed backfill across pauses/disconnects, and synchronized remote edits/recalls or content purges.
• Claiming all official QQ capabilities are available to every developer, or calling the complete specification finished when only mentions-only text has been qualified.
• Upstream merge, registry publication, production deployment, issue decomposition or implementation merely as a consequence of publishing this specification.

Further Notes

• The Human confirmed the complete design on 2026-10-08 (Asia/Tokyo), including required later image/file/voice input support and exclusion of voice output. The Human separately confirmed the testing seam and authorized publication on the same date. No further product interview is required to publish this specification.
• The tracker resolves the original repository remote to BotHarness/DeepSeekBot. This is the normative QQ feature specification; follow-up runnable slices should be attached through the repository's native issue workflow when decomposition is requested.
• Related shared work: IM provider coordination #48, Channel and Inbox Bridges #629, identity and source management #693, qualified product composition #822, cross-provider Human media presentation #1020, and current one-step app binding #1107. Reuse these specifications; do not create duplicate generic identity or media projects.
• The newer accepted app-binding ADR-0142 amends the older per-conversation admission and one-account-per-platform constraints. QQ follows that shared target; older working-tree code is implementation evidence, not permission to restore obsolete UI. Provider artifact ownership ADR-0127 and qualified fork ADR-0104 remain the ownership and qualification references.
• The inspected development input was maintained dsh-im revision 4f4f0a6, with QQ SDK 1.0.4 on DSH 0.2.0-rc.1. This is a static baseline, not proof of live QQ qualification; select the current qualified baseline deliberately when implementation begins.
• Official evidence: group mentions, ordinary group events, group sending, message limits, and QQ SDK. Account-level permission, present transport availability and native media behavior remain qualification work.
• Lark Human image display and Slack file processing are reusable precedents with different acceptance scopes. This specification explicitly extends QQ to real image and voice understanding; it does not retroactively declare those model capabilities qualified on other platforms.
• Delivery order starts with official account/transport proof and the first runnable mention/text path, then ordinary participation, independent identities, image/file handling and incoming voice understanding. It is sequencing guidance, not a pre-created set of implementation tickets. Unsupported capabilities remain visible unfinished scope rather than a reason to introduce speculative alternative-platform tickets.