xcisxc29/dsh-qq-plugin

Drive the DeepSeek Harness agent on this computer from your phone, in QQ.

It goes through Tencent's official QQ bot platform (api.bot.qq.com, bound by scanning a QR code), so there is no public IP to expose, no reverse proxy, and no third-party protocol client in the middle. Bind once, and it keeps working.

Runs on the current DSH desktop app — developed and tested against DSH 0.2.0-rc.2.

This is the QQ counterpart of dsh-wechat-plugin. It is feature-aligned with it, with a few deliberate departures where the QQ protocol makes the WeChat machinery unnecessary — see Differences from the WeChat version.

中文说明

Ask for a file in one sentence and it lands on your phone. Say "send me that DSH self-portrait from my desktop" in QQ and the agent finds the file on the computer, sends it back, and confirms with "sent — DSH 自画像.png on the desktop (29 KB, PNG)". The ＋ at the right of the composer is the attachment entry: images, videos, voice and files all go in that way (see Media in both directions).

• Text both ways. A QQ message becomes a DSH prompt, and the reply comes back to QQ.
• Images, files and voice in; images, videos and files out. Attachments are saved into the session workspace and handed to the agent; the agent sends files back with send_to_qq. A reply that runs long is turned into a .md file and sent to your phone instead of being cut.
• One QQ chat, many DSH conversations. /new, /list, /switch, /current, /cancel — or just say "switch to the other one". The list has session folders and sessions as two levels.
• Pick the model and the reasoning level from your phone too. /model lists the models with each one's reasoning levels; /model 2 and /model 等级 high switch them, effective from the next step.
• Answer permission prompts and questions from your phone. Approvals are answered with 「允许」/「拒绝」 (allow/deny) or a numbered option; the agent's multiple-choice questions arrive in QQ with numbered options and a digit answers them — being away from the desk does not stall the task.
• Proactive push. notify_qq lets any session on this machine message you — that is what makes "tell me when it is done" work. It works in practice: a ten-message burst was delivered in full, and the last six of those went out as proactive pushes. (Tencent's rules for unsolicited sends can change and the plugin assumes no quota; anything undelivered is queued and flushed the next time you speak.)
• Scheduled tasks. Run through the DSH host's own schedule_create / schedule_list / schedule_delete / schedule_update — just say "wake me at 23:12". The plugin does not reimplement what DSH already has; it is only the channel.
• Settings page under Settings → QQ — nine settings, a native folder picker, and diagnostics.

For the DSH desktop app on a machine that stays on. It needs DSH's workspace, tool and UI services — the standard desktop composition.

Open the plugin entry in the sidebar and choose 添加插件 (add plugin). The field takes a package name, a Git URL, a tarball, or a local path.

The name to install is dsh-qq-plugin

The repository and the package share one name, so there is nothing to reconcile — but the -plugin suffix is easy to drop by accident. Copy dsh-qq-plugin rather than typing it. The install command has to match the package name exactly.

From a terminal, that is one line (--profile web works just as well if that is the profile you use):

dsh plugin --profile desktop add dsh-qq-plugin

dsh-qq-plugin

C:\path\to\dsh-qq

npm pack
# → dsh-qq-plugin-1.0.3.tgz

dsh plugin --profile desktop add dsh-qq-plugin
dsh plugin --profile desktop add C:\path\to\dsh-qq

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-web-app",
        "dsh-qq-plugin"
      ]
    }
  }
}

Wait for the install to finish, click 立即启用 (enable now), and restart DSH.

After restarting DSH, open Settings → QQ and click 开始扫码 (start the QR bind). Scan the code with mobile QQ and confirm on the phone.

The scan is the whole registration. The bot application is created by that scan, so you do not need to register anything on Tencent's open platform first and you do not need an AppID/AppSecret in advance — nor a public IP or a reverse proxy.

The credentials land straight in DSH's credential store — the plugin's own state file records only the AppID, never the AppSecret. The channel connects by itself once bound: send any message to the bot in QQ and you should get a reply.

That is what it looks like in real use, after installing it: the agent put together a 13-poem anthology on the computer and sent both the docx and the pdf straight to the phone; in the same conversation, "tell me the computer's current time" came back as 2026-10-13 22:43:28 Tuesday, along with an offer to set a reminder.

The computer was locked at that moment — the phone says 22:43 and so does the lock screen:

Locking the screen does not stop the agent, so it keeps working after you walk away while the conversation on your phone carries on. The reverse is also true: locking is exactly what you should do when you leave (see Security).

Just send a message and it reaches the agent:

你好

What follows is grouped by capability, and each group carries a real screenshot showing what it looks like and what it proves.

One QQ chat sits in front of any number of DSH conversations. /list opens this workspace's conversations, ten per screen:

One shot, four things proved: ten rows per screen, a six-character id at the end of every row (7cee80, 4b55e1…), the current conversation marked ← 当前, and that footer line. The list also tells you there are 89 more conversations in the other session folders.

/list all is the level above — the session folders (across projects and workspaces), each with its conversation count; reply with a number or a name to enter one, and what you get is that folder's conversation list (the screenshot replies 1, so it enters 「QQ 会话」):

Entering a folder only moves where you are browsing, not which conversation you are bound to — to actually switch you still pick a conversation inside it.

A bare digit is /switch <digit>: with the list on screen there is no need to type /switch, just reply 2 — and it tells you which one you landed on, short id included, so you can check it against the row you meant:

★ Quoting freezes the numbering: long-press the list message and quote it before replying with a number, and the number is read as that screen printed it. Sessions running while you read cannot make you land on the wrong one — the numbering is frozen inside that message. The list footer says so itself: 「引用这条消息再回编号，可以避免编号过期。」

Plain language works too. Here the user sends 「查看所有会话」 (show all conversations) — not a command:

The agent judges intent rather than matching fixed rules: it recognised "list conversations", listed the session folders, and told you that a number switches and 「查看其余」 turns the page. A switch also reports whether it succeeded or failed.

Type these to control which DSH conversation you are talking to:

Spaces are optional: /switch3, /switch 3 and /switch:3 all work — these commands get typed on a phone keyboard, where a dropped space is normal. A word that merely starts with a command is not one, so /news is not /new.

Numbering expires: sessions run while you are reading the list, so by the time you reply "3" the 3rd row may be someone else. Every row therefore ends with a short id of at most 6 characters — reply with that, or quote that screen's list message and the number is read as that message printed it.

The list has two levels, ten rows per screen: /list opens this workspace's conversations; /list all lists the session folders (workspaces), which you enter by number or name. Both levels walk down ten rows with 「查看其余」, and numbering runs on across screens. When you reach the end it says so instead of inviting you to keep going. Entering a folder only moves where you are browsing, not which conversation you are bound to — to actually switch you still pick a conversation inside it.

/model lists which models there are (marked 「（当前）」/「（默认）」 — current / default) and each one's reasoning levels. /model <name|number> switches model; /model 等级 high changes only the reasoning level; /model 2 等级 high changes both. A switch takes effect from the next step.

Reasoning levels come from the host adapter. The bundled DeepSeek adapter publishes off / low / high / max (printed as Off / Low / High / Max), and those are the names /model 等级 accepts, case-insensitively. There is no separate Chinese spelling — the level names are the ones the list prints, exactly as the WeChat channel does it.

Plain language works here too — "switch to the other one", "what conversations do I have", "stop". The agent judges the intent rather than matching fixed rules, and a switch tells you whether it succeeded or failed.

In: send the agent an image / video / voice message / file from your phone. Voice is transcribed server-side and you never see that step. Document attachments (Word, Excel) are readable too.

Here is a photo of a dog sent in, with a single question — "what is this":

What is worth noticing is not that it recognised a dog but the two details only someone who really looked at the image could give: the yellow-bodied orange-beaked duck toy, the person's legs at the left edge of the frame, and its unprompted remark that the photo is sideways (the phone was held the wrong way round).

Now a PDF sent in, again with a single question — "what is this":

Document attachments are read too: it says this is a five-page recruitment task document, exported from MarkText, and summarises it as "Part 1 environment setup / Part 2 using AI plus engineering discipline / Part 3 traditional OpenCV, four tasks".

Out: the agent sends files from this computer to your phone with send_to_qq — images arrive as photos, videos as playable clips, everything else as a file attachment:

This is the story the cover image at the top of the page tells, and it is a complete pickup: say which file you mean, the agent finds it on the computer and sends it back, and it confirms with the filename and size so you can see at a glance whether it sent the one you meant.

★ A reply that runs long is turned into a .md file and sent to your phone (4000 characters by default, adjustable; 0 = no limit):

Something that would not fit on one phone screen is far more usable as a file — not truncated, and not split into a dozen messages that flood the chat. The threshold is the settings page's "单条回复字数上限" (per-reply character limit).

Voice: hold to talk on the phone and the agent receives text (transcribed server-side, with nothing extra for you to do):

Under that 3-second voice bubble in the screenshot is a complete weather answer — the middle step, turning speech into text, is invisible on your phone, and does not need to be visible.

These three have no screenshots — they are a question and an answer inside the same conversation, so a picture of one would look much like the ones above; prose says it better. This is what arrives on your phone:

• Permission approvals: when the agent wants to touch your files, a pending request appears in QQ saying what it intends to do. Reply 「允许」 (allow), 「拒绝」 (deny), or a numbered option — all three answer it, and the task carries on. (For such a prompt to appear at all, the permission preset has to be one of the two that can show prompts — see Settings.)
• Either/or and multiple-choice questions: the agent's question arrives with numbered options, and a single digit answers it.
• Quoting as context: long-press and quote one of its answers before speaking — for example "expand the second point in this one" — and it knows which answer "this one" is and which point "the second" is.

★★ notify_qq: any session on this machine can push a message to you — that is what "tell me when it is done" is built on. On the left is the desktop session doing the work; on the right is what arrives on mobile QQ:

Note that the two sides are not the same session: the work was done by that desktop session, and the message arrived in the QQ conversation you are bound to. That is exactly why allowCrossSessionNotify is on by default — without it, the session doing the work could not report its own result.

It works in practice: a ten-message burst was delivered in full, and the last six of those went out as proactive pushes. (Tencent's rules for unsolicited sends can change and the plugin assumes no quota; anything undelivered is queued and flushed the next time you speak.)

Scheduled tasks run through the DSH host's own schedule_create / schedule_list / schedule_delete / schedule_update — the plugin does not reimplement what DSH already has, it is only the channel. Plain language is enough:

When the time comes it really does push one over (this is a proactive push, not you asking):

"Remind me every morning at 9 what I have to do today", "send me the current time every hour", "show me which scheduled tasks I have" all belong here. Showing them is schedule_list, and so are deleting and changing them.

• A session that is archived or disappears is re-bound automatically, with a line telling you so rather than the message being swallowed: the old conversation was archived → a new one is created to carry on, and you are notified.
• State writes on Windows have retries and backoff (for the "file is in use" kind of EPERM).
• Inbound messages with empty content or an unknown frame type leave a log line instead of leaving no trace at all.

The qq_ / _qq in those names is deliberate: tool names are unique across the whole host scope, and the WeChat plugin already occupies session_control. Two plugins claiming the same name means whichever registers second fails silently.

Those three come from the plugin. Scheduling is not among them because it does not need the plugin to implement anything: it runs through the DSH host's own schedule_create / schedule_list / schedule_delete / schedule_update, and the plugin's part is only to carry the result over the QQ channel.

Settings → QQ, in six groups, in the order the page renders them:

• 帮助 (Help) — the one button on the page that opens the user handbook (docs/HANDBOOK-USER.md, the file that lists every command and every setting)
• 连接 (Connection) — channel on/off, the QR bind, the bound account, unbind
• 权限 (Permissions) — the permission preset for QQ conversations (only auto and «Follow the DSH setting, same as the desktop» can still show approval prompts)
• 行为设置 (Behaviour) — the table below
• 指令 (Commands) — the slash-command reference the page prints (/help, /new, /list, /switch, /current, /cancel, /model)
• 诊断 (Diagnostics) — log tail, workspace path, conversation count, pending interactions

This is the page in full (the ones below are the same page section by section):

These are the top two cards — and the first thing you see after installing it — 帮助 (Help) and 连接 (Connection):

The QR bind is in the lower half of that shot: click 重新扫码, scan with mobile QQ and confirm on the phone. You do not have to register on Tencent's open platform first, and you do not need an AppID/AppSecret — the bot application is created by that scan. The 已绑定账号 row is what it looks like once bound (AppID ← an irreversible fingerprint · bind time), and 已连接 beside it is the channel's state right now.

The middle two groups are permissions and the command reference:

The permission preset has three Chinese options, with the default selected in the shot:

Only the last two can still send a permission prompt to QQ. To see for yourself that an approval can flow back to a phone, set this to one of the presets that can prompt — a pending request then arrives in QQ, and 「允许」/「拒绝」 or a numbered option answers it.

That group is /help as the page prints it, and the user handbook is what every command and setting is measured against. The line underneath — that plain language works too — is also true: DSH first says what it is about to do and waits for you to agree; turn off 「会话操作先确认」 above to skip that step.

Lower on the page, the behaviour settings and the session folder:

The session folder setting has a native folder picker — the 选择… button. The box holds the text you typed and 当前生效 to its right is the path actually in use; keeping the two apart is deliberate, so that when a path is wrong you can see what you wrote and change it while still knowing which folder is really being used.

Last is the diagnostics block, your first clue when something goes wrong:

Diagnostics gives you the log path plus the tail of the log, so most problems you can see for yourself — whether a send failed, whether you were rate-limited, whether an attachment never landed. The last line in the shot happens to be a successful send_to_qq.

Adding those cards up, there are nine settings in total:

Settings are persisted and survive a restart. An older state file (one with no settings block) still reads fine.

Every setting is defined in exactly one place — lib/settings.js's SETTINGS_SCHEMA, one validator plus one default per entry. Loading, saving, the settings page and the round-trip test are all derived from it, so adding a setting is one line there and nothing else can drift out of step. Plain JavaScript has no compiler to catch a forgotten setting, so scripts/verify.mjs asserts that the schema's key set, the key set the runtime actually holds, and the key set written to disk are the same set — that assertion is the compiler we do not have.

Next to workspacePath, the currently in effect line shows the path actually in use, while the box holds the text you typed. Keeping the two apart is deliberate: when a path is wrong you can see what you wrote and change it, while still knowing which folder is really being used.

⚠️ Changing the path does not move existing conversations. They stay in the old folder; only conversations created afterwards use the new path. That is the only safe behaviour — the host compares cwd when it adopts an existing conversation, and a mismatch raises ApiSessionCwdConflict, after which that conversation can never be picked up again.

The debugging HTTP endpoints all live under /.dsh-qq-plugin/: status, log, settings, permission-presets, accounts, login, start, stop and a few more.

Feature-aligned, but a few things differ on purpose, because the QQ protocol hands us something the WeChat one does not:

Only you can reach it. The channel talks to Tencent's official QQ bot service and nothing else — no third-party service, no self-hosted relay in the middle. The bot is a separate application whose administrator is your QQ account, and it was created by your own scan; an uncertified bot is limited to its administrator. It is not a QQ contact you can hand out: nothing searches for it and nobody can add it. There is no "someone else could message it" surface, which is why no allowlist exists: the platform's own rules already are one.

The AppSecret is a long-lived key, and it is treated as one. It is written to DSH's credential store as a grant record rather than into the plugin's plaintext state file, which keeps only the AppID. Rotating it means binding again from the settings page.

Three things are still true and worth knowing:

Conversations from QQ run with full permissions by default — the agent does not ask before it acts. That is deliberate: a permission prompt is delivered to QQ and the task then waits there, so on a phone every command would stall until you answered a conversation you had walked away from. Set Permission preset for QQ conversations to auto (or to the profile's own policy) in the settings page if you want the same guardrails you have at the desk.

The agent runs as you. It can execute commands and read and write files, with your user's permissions — that is what it is for, and it means anything you can do on this machine, it can do. So: skim what you asked for before walking away, and lock the screen when you leave. Locking does not stop the agent, and it keeps anyone passing by out of your desktop.

Any session on this machine can push to your QQ by default. That is what makes "tell me when it is done" work: the session doing the work is usually not the one your QQ conversation is bound to, and without this it could not report its own result. Turn off allowCrossSessionNotify to restore the stricter rule, where only the bound session may send.

Plain JavaScript, no build step, no transpiler. CI runs Node 24; the manifest declares no engines range, because the plugin only has to run inside the DSH host that is already there.

npm ci

node scripts/verify.mjs          # host side
node scripts/verify-client.mjs   # client registration shape (not a visual check)
node scripts/verify-send-path.mjs  # the send path, against a fake SDK

782 host checks, 108 client checks, 60 send-path checks.

Those three numbers are read out of the runs above, not typed by hand: tools/check-doc-counts.mjs compares them against what the scripts actually print, and the CI job fails naming the file if any of them disagrees. Change a test and the number here, or the gate stops the build.

Four checkers live in tools/. Each one corresponds to a real incident, so run them before committing:

node tools/check-unbound.mjs .          # used but never imported
node tools/check-unused-imports.mjs .   # imported but never used
node tools/check-doc-counts.mjs --run   # the documented counts, and the repository name in publish.yml
node tools/check-cross-plugin.mjs <profileDir>   # shared resources across plugins

check-doc-counts.mjs reads the three numbers out of the actual output of the three suites and compares them against this file, README.zh.md and docs/RELEASING.md, naming the file, the number written and the number measured when they disagree. In CI it reads the output the three test steps captured, so it costs a second rather than a second full run. --run is the local form: it runs the suites once itself.

It carries a second job, for the same reason: the four Trusted Publisher fields in publish.yml's header are typed by hand and a typo in them shows up as a 403 at publish time and as nothing else, so the checker compares that block against package.json (organization and repository), the workflow's own filename and its name:, and both READMEs' CI badges. The repository it names was once dsh-qq while every other copy said dsh-qq-plugin — that is the failure this half exists to catch.

check-cross-plugin.mjs is a local check and does not run in CI: it reads a real DSH profile — the dsh.profile.bundles list and the plugins installed under that profile's node_modules — and a CI runner has neither. It checks the two things every plugin shares: the client plugin top-level scope (the shell concatenates every enabled client.js into one script, so a top-level const in one plugin collides with another's) and host tool names, which are globally unique.

Each checker carries a reverse control: it has to catch the failure it was written for, or it is declared untrustworthy and exits non-zero. A checker that always prints "pass" is worse than no checker at all — it makes people believe something was verified.

Two probes under smoke/ (step3-probe.mjs and step4-probe.mjs) talk to Tencent's live service and need real bot credentials; the other two (step4-surface.mjs and check-sdk-surface.mjs) are offline surface checks that need neither credentials nor a network. None of the four is in CI — the two probes because credentials do not belong in a public repository's CI, the two surface checks because they are one-off research probes that print observations rather than assert pass/fail.

MIT — see LICENSE.