pi-qqbot

Bridge the Pi coding agent into QQ private (C2C) chats: send a message from QQ and let the agent work on the machine where pi runs — with remote approval before it executes dangerous tools.

English | 简体中文

Single-session design (v1): every QQ user shares one pi session. Multi-user / multi-session support is planned on top of the pi SDK.

Features

Install

# from npm
pi install npm:@zxh126/pi-qqbot

# or from a local checkout (dependencies are needed here)
npm install
pi install ./pi-qqbot

Then create ~/.pi/agent/pi-qqbot.json:

{
  "appId": "YOUR_APP_ID",
  "appSecret": "YOUR_APP_SECRET",
  "sandbox": true,
  "allowlist": [],
  "markdownReply": false,
  "streaming": false,
  "approve": {
    "tools": ["bash", "powershell", "write", "edit"],
    "remember": true
  },
  "queue": {
    "max": 20,
    "ack": true
  },
  "commands": {
    "passthrough": true,
    "allowReload": false,
    "allowQuit": false,
    "allowUpdate": false,
    "allowSession": true
  },
  "attachments": {
    "enabled": true,
    "dir": "",
    "maxBytes": 26214400,
    "maxPerMessage": 10,
    "retentionHours": 24,
    "maxFiles": 200
  },
  "files": {
    "enabled": true,
    "maxBytes": 31457280
  },
  "remote": {
    "notice": true,
    "guidelines": true,
    "extra": ""
  }
}

Credentials can also come from the QQ_BOT_APPID / QQ_BOT_APPSECRET environment variables (single-bot setup only).

Several bots (2.0)

{
  "qqbots": [
    { "name": "work", "appId": "1903340143", "appSecret": "…", "sandbox": true },
    { "name": "home", "appId": "1020123456", "appSecret": "…" }
  ],
  "queue": { "max": 20, "ack": true }   // still the global defaults, per-bot overrides allowed
}

Every pi process claims the first bot (in config order) that is not online; spare processes stand by and rescan every 5 s. After claiming, the credentials are verified by fetching an access_token: a bot with a wrong appId/appSecret releases its lock and is skipped instead of squatting the slot. PI_QQBOT_ACCOUNT=<name|appId> pins one bot instead of auto-claiming. Full details: docs/accounts.md.

Usage

Start pi, then message the bot in QQ; pi handles it and replies.

Images and files from QQ

Send a picture (or a document, an archive, a voice/video message) and the bot downloads it to a temp file, then hands pi a line with the path:

图片路径 C:\Users\you\AppData\Local\Temp\pi-qqbot\bot-340143\2026-02-11\msg-abc-1-103045.jpg

Your own text is kept as the first line, so 看下这个 + an image becomes 看下这个\n图片路径 C:\…\a.jpg — one pi turn, paths included. QQ also gets a receipt such as 已收到 2 个附件（图片 ×1、文档 ×1），已存为临时文件并交给 pi： followed by the paths; failed downloads are listed with the reason and the text is still delivered.

Notes:

• QQ's download URLs carry a short-lived rkey, so files are fetched the moment the message arrives.
• A message that has attachments bypasses slash commands, approval parsing and the numbered picker — it is always treated as ordinary content for pi (an attached /status is not executed).
• Files are deleted by the attachments.retentionHours / attachments.maxFiles sweep at session start, so a path handed to pi stays readable for the rest of the session (and usually a day).
• On file names: only [0-9a-zA-Z._-] are kept, prefixed with the QQ message id.

Sending files to QQ

Two ways to push a file from the machine to your chat:

Approval is mandatory on every send: qq_send_file is force-gated no matter what approve.tools says, and it ignores both the session-wide 「以后都同意」 and remembered decisions — sending a file is data leaving the machine, so each upload is confirmed on its own. The prompt says so explicitly: [审批 #1] 发送文件到 QQ: D:\docs\a.pdf + 「需单独确认」.

How it is delivered (QQ rich media, chunked upload):

Notes:

• The file is uploaded in chunks (upload_prepare → PUT → upload_part_finish → merge) — the only path that works for local files, since URL upload needs a public URL and the one-shot binary upload caps at 5 MB.
• Passive reply is used (srv_send_msg: false + msg_type: 7 with msg_id/msg_seq), so it does not burn the active-message quota.
• Limits on QQ's side: 200 MB hard cap and a daily total file quota (40093002); the bot turns both into readable replies.
• The reply also tells you what was sent: 已发送「报告.pdf」（2.31 MB，文件卡片）.

Remote-context notice

pi runs on the machine, you are in QQ — and that machine may be locked. So the first time a QQ message of a session is actually handed to pi, the bot adds a short note to the system prompt (a qq-remote-context section, so it sits before the user message and QQ never sees it) that says:

• the user is remote: no screen, no dialogs, keep replies concise;
• desktop screenshots, screen OCR, UI automation, keyboard/mouse simulation and headed browsers are off by default (mcp__screenshot, mcp__winui are named explicitly) — on a locked machine they only capture the lock screen or fail;
• when an image is needed, render it off-screen (headless browser over HTML, SVG, matplotlib/Pillow, …) and send the PNG with qq_send_file instead of trying to capture the desktop;
• capturing the desktop once is allowed only to check whether the machine is locked; everything else stays off-screen.

Timing matters: the note is only added from before_agent_start for a run this extension dispatched, so merely loading the extension — or chatting with pi directly in the TUI on the host — sends nothing. It appears once per session (again after context compaction; remote.extra appends your own lines). With remote.guidelines the same expectations are condensed into three bullets that ride along in the system prompt of every run that came from QQ, so they survive summarisation. Set remote.notice: false / remote.guidelines: false to turn either part off.

If you take over the same session from the host — turn N from QQ, turn N+1 typed in the TUI — the next local run gets a one-time qq-local-handoff section instead: the remote/locked-screen premise is void (screenshots are fine, no qq_send_file needed). Detection uses the input event (source: "interactive"; the bot's own sendUserMessage is "extension", so it never misfires), it only fires once per hand-off, and it is skipped while a QQ run is still streaming (no new run starts then). /status shows 来源: QQ（远程） or 来源: 本机（TUI）.

Slash commands from QQ

Any message that starts with / is routed before it can become a chat prompt:

Host-only (answered, never forwarded to the model): /settings, /hotkeys, /changelog, /trust, /login, /logout, /scoped-models, /llama, /import, /export, /share, /bug, /copy, /privacy.

Messages that start with ! or !! (full-width ！ / ！！ included) are not shell commands here. Those prefixes are expanded only by pi's TUI / RPC front end (! runs the command and lets the model see the output, !! keeps it out of the context), and the extension API has no equivalent — pi.sendUserMessage() does not dispatch them, and pi.exec() bypasses approval and session history. So !ls gets a receipt saying it was not executed; it is never forwarded to the model as prose either. To run something, just ask in words — the agent then calls the bash tool and asks in QQ before it runs. A lone !, !!!, or an exclamation mark at the end of a sentence is still ordinary chat.

TUI-only commands come back to QQ

Some extension commands never print into the conversation — they call ctx.ui.notify() (and pi.appendEntry()), which only renders on the host TUI/RPC front end. In QQ that showed up as "dispatched, then silence". The bridge closes that hole:

A bare /usage rate and /usage help are answered locally, without running the command. Coupling with pi-usage-report is limited to the usage-report entry type plus the two files it keeps in ~/.pi/agent/.

Guards:

• /reload, /new, /compact, /quit, /tree, /fork, /clone and /resume refuse to run while a task is in progress — send /cancel first.
• Prompt templates and /skill:name start an agent run, so while a task is in progress they are queued like ordinary messages (see Queueing while busy). Extension commands that manage their own LLM interaction still run immediately.
• Selection commands (/tree, /fork, /resume) answer with a numbered list of at most 10 entries (with tap-to-select buttons when markdownReply is on), scoped to the user who asked and valid for 10 minutes. The next bare number from that user executes the choice; anything else (or 「取消」) abandons it. A number without a pending list is ordinary chat.
• /reload is off by default: it restarts the bot, and if the new code fails to load the bot stays down until someone fixes it on the host. Turn it on with commands.allowReload: true.
• Sending the bridge command yourself (/qq reload, /qq quit, /qq new, /qq list fork, …) hits the same gates: the sub-command is mapped back to its built-in name first, so commands.allowReload / allowQuit / allowUpdate / allowSession and the busy check all apply. Routing it as a plain extension command would have bypassed every gate — with allowQuit: false, /qq quit could shut the host pi down. Destructive sub-commands (reload, new, quit, clone) answer before they are dispatched, because they replace the runtime they would answer through.
• Dispatch receipts echo the whole command (已派发 /deploy prod 给 pi。) instead of only the first word, truncated at 80 characters with …. Previously /qq reload was answered with 已派发 /qq 给 pi。, which looked like the argument had been dropped.
• Why the indirection: pi only dispatches extension commands from a message (prompt() → _tryExecuteExtensionCommand), and reload() / newSession() are command-context APIs. So this extension registers /qq and forwards /reload → /qq reload. Built-in names are hard-coded here because pi does not export its built-in list; any unknown /word falls back to plain text.
• The bridged command never touches the command ctx after a session replacement: reload / update / new / clone / quit (and the tree / fork / resume picks) invalidate it, and pi then throws This extension ctx is stale after session replacement or reload on any property access. The model cache sync is skipped in those cases instead (REPLACES_RUNTIME + a guarded read).

Queueing while busy

pi's session runs one agent run at a time, so the bot serializes QQ input itself:

you: 帮我把测试跑一遍
bot: 收到，正在处理
you: 顺便看看 README 有没有错别字
bot: 已排队 #1，当前任务结束后自动执行。发 /queue 查看队列，/cancel 可中止当前任务并清空队列。
you: /queue
bot: 当前任务：处理中（发 /cancel 可中断）
     队列：1 条（上限 20）
       1. #1 · 12s 前 · 顺便看看 README 有没有错别字
     发 /queue clear 清空，/queue drop <编号> 删除一条。
bot: （第一轮结束后）开始执行队列 #1

Semantics:

• Every message that would start a run — plain chat, prompt templates, /skill:name — is queued while a task is running, in arrival order (FIFO). Replies go to the QQ user who sent that message.
• The next entry starts when pi has settled (agent_settled, no automatic continuation left), so a retry, a compaction retry or a follow-up turn is never cut in half.
• The queue holds at most queue.max entries; beyond that the message is refused with a notice. queue.max: 0 restores the old "上一条消息还在处理中" behaviour.
• If handing a message to pi fails (pi was still finishing the previous run), it is put back at the head of the queue and retried — messages are not lost. A run that already started is never retried, so a failure inside a run cannot execute the same message twice.
• Control commands are not queued: approvals, /status, /queue, /reset, /help, the pi built-ins and /cancel all act immediately.
• /cancel empties the queue as well, because "cancel" means "stop doing all of this". Use /queue drop <id> to remove a single entry instead.

Progress reports

While a run is in progress, a summary is pushed to QQ every progress.intervalMs (15 s by default):

[进度 02:15] · 第 3 轮 · 工具 6 次（bash 4 / read 2）· 失败 1
最近: bash "npm test" · 6.2s
正在: 分析测试输出… · 12.3k tok

• Built purely from local event data (tool_execution_*, turn_end, message_end, message_update) — no model call, no tokens spent.
• Tool arguments are redacted and truncated, so a command carrying a token never reaches QQ in clear.
• Quota-aware: one QQ message buys only 4 passive replies, so a long run will eventually run out. The first failed send stops automatic reports for that run (no retry spam); send /progress (or 「进度」) and they resume.
• Manual pause / resume: /progress off (or 「暂停汇报」) silences the reports for the rest of the session — it survives agent_settled and the next run, and asking for /progress no longer turns it back on. /progress on (or 「恢复汇报」) resumes. A new session (/new, restart) starts enabled again. /status shows which of the five modes you are in (on / paused-by-you / quota-quiet / held-during-approval / disabled).
• Approvals stay visible: while a tool approval is waiting for your reply, automatic reports are held back — otherwise a 15 s progress line would keep pushing the prompt off your screen. They resume on the next interval after you answer (or the approval times out). Asking for /progress yourself still works.
• The final answer is protected: if it cannot be delivered (quota), it is cached and re-sent with a （上一条回复发送失败，补发如下） prefix as soon as you send the next message.
• Timer is cleared on agent_settled / /cancel / session shutdown.
• Set progress.enabled: false to turn the whole thing off (across sessions; read at session start).

Colloquial shortcuts (Chinese, matched only as a whole message)

A bare 「停」 interrupts the task; only phrases carrying a report noun (「停止汇报」) or an explicit silence word (「别说了」「闭嘴」) pause the reports. Sentences like 「帮我加个进度条」 are still forwarded to pi.

Cancelling a run

Long tasks started from QQ (installs, builds, a runaway agent loop) can be interrupted without going back to the machine:

you: /cancel
bot: 已取消当前任务，并终止了 1 个待审批请求，队列中的 2 条已清空。可以发送新消息继续。

What it does, in order: terminate every pending approval request, empty the queue, call ctx.abort() on the current run (the same path as pressing Escape in the TUI), drop the partially streamed answer so it is not sent to QQ, keep the busy flag until pi reports agent_settled (so messages arriving during the abort are queued instead of racing it), and reply with a confirmation. If agent_settled never arrives, an 8-second watchdog releases the busy flag and continues the queue. Replies that only look like cancelling — 「取消自动同意」, 「恢复审批」 — still go to the approval handler, so the auto-approve switch keeps working as before.

Anything else is forwarded to pi as a user message.

When the model runs out of credit

A provider error used to look like silence in QQ: pi records stopReason: "error" plus the provider's message on the assistant message and produces no text at all, so there was nothing to forward. Now the failure is classified (billing / auth / permission / rate / other) and reported:

❌ 当前模型的余额/额度不足，暂时无法继续对话
当前模型：deepseek/deepseek-flash
服务端原文：402: {"message":"Insufficient Balance (request_id: …)", …}

恢复方式（直接回消息即可，key 我不会写进日志）—
1. 有新 key：只发 key（任意前缀都行，比如 sk-… / ark-… / AIza…，带引号也认）→ 我更新当前模型所属服务的 key
2. 换服务商：发「https://api.xxx.com/v1 <你的 key>」→ 我拉它的模型列表，再把编号发给你挑
3. 先换现成模型：发 /model 看列表，或 /model provider/id 直接切

The reply names the model that actually failed, and the recovery path needs no working model — that is the whole point, since the agent itself is unusable at that moment.

Send a new key — after a 402/401, a message that is just a key (sk-…, ark-…, AIza…, a plain hex key, even a dummy ollama when it comes with an endpoint) is taken as a credential, not as chat:

Details that matter:

• A bare token is only treated as a key while a 402/401 is still the last thing that happened — otherwise a random pasted string would be swallowed instead of reaching the model. The explicit key … form is always accepted.
• Keys are never written to the log or echoed back; replies show sk-ab…cd, and redactSecrets() runs over everything that leaves the machine.
• auth.json is written with pi's own lockfile and an atomic rename, so pi picks the new key up on the next request (verified: an invalid key on disk + a write during before_agent_start → the same process succeeds without a restart).
• models.json is written in pi's documented format, so the provider survives restarts; pi.registerProvider() makes it usable immediately in the running process.
• Model metadata for a newly registered endpoint is borrowed from pi's built-in catalog when the same model id exists there (e.g. glm-5.3 → contextWindow: 1e6, maxTokens: 131072, compat.thinkingFormat: "zai"). Unknown ids fall back to conservative defaults (128k / 16k) and the reply says so.
• Non-chat ids (embedding, rerank, tts, cogview, …) are filtered out; at most 40 models are registered and the first 10 are offered as numbers.

Self-update from QQ

you: /update          (or 「更新自己」)
bot: 正在检查 pi-qqbot 更新…
bot: 发现新版本 v2.3.0 → v2.4.0，开始更新（pi update，最多等 5 分钟）…
bot: ✅ 已更新到 v2.4.0，正在重载扩展（会话保留，模型上下文不受影响）…

This is pi's own update path, not a re-implementation: npm view @zxh126/pi-qqbot version to learn the latest, pi update npm:@zxh126/pi-qqbot (the same command the release checklist uses) to install it, then /qq reload (ctx.reload()). Guard rails:

• commands.allowUpdate defaults to false — enable it in pi-qqbot.json if you want QQ to be able to update itself.
• Refuses while a task is running (needsIdle), like /reload and /new.
• Version verification gate: after pi update, the on-disk package.json version must equal the registry version. If it does not (npm version already bumped locally, pi update deciding "already latest", …) the bot reports it and does not reload.
• A failing npm view or pi update leaves the bot untouched; the error is echoed to QQ.
• The installation directory is shared: other pi processes still running the old code keep running it until they reload.
• Natural-language triggers are narrow on purpose — 「更新自己」「升级一下插件」「自更新」 yes, a bare 「更新」 no.

Remote approval

[审批 #1] bash: rm -rf node_modules
回复「同意 1」批准，「拒绝 1」拒绝，「停止」终止本轮。
要本会话内全部放行，回复「以后都同意」（可用「取消自动同意」关闭）。

With markdownReply: true the card carries ✅ 允许一次 / ❌ 拒绝 / 🚀 以后都同意 buttons — tapping one is the same as replying. Strict tools (qq_send_file) show only the first two buttons. Text replies keep working either way.

Reply vocabulary (approval keywords are Chinese, with English aliases; the card buttons are the faster path when they are shown):

Semantics:

• Session scope only. The auto-approve switch lives in memory and lasts until /new, a new pi session, or one of the "back to per-request approval" replies. Nothing is persisted, nothing survives a restart.
• The switch is an explicit user instruction, so it is not affected by approve.remember.
• approve.remember: true additionally remembers the decision per tool for the session: after approving bash once, later bash calls are not asked again (/new clears it).
• Requests time out after 10 minutes and are rejected with a notification. A timeout is not remembered as a rejection — the tool is asked again next time.
• Approval text that arrives while no request is pending is forwarded to pi as a normal message.

Single-instance lock

The QQ gateway keeps only one active connection per bot. The extension uses a proper-lockfile lock at ~/.pi/agent/pi-qqbot-<appId>.lock:

• the process that acquires the lock becomes the host and connects to QQ;
• other processes stand by, retry every 5 seconds, and claim any bot of the list that is free;
• when the host exits or crashes (30 second heartbeat timeout), a standby process takes over;
• a host that is only rebuilding its session (/reload, /new, /fork, /resume) writes a 20 second reservation next to the lock, so nobody else grabs its bot in the gap;
• the last owner (pid + working directory) is kept in ~/.pi/agent/pi-qqbot-<appId>.owner.json and is used to tell you that a new process took over, and from which directory.

Prerequisites

1. Create a bot on the QQ Open Platform and copy its AppID / AppSecret.
2. Before the bot is published, configure a sandbox C2C account and set sandbox to true.
3. In production, add the server's public egress IP to the bot's allowlist.

Logs

Debug logs are written to ~/.pi/agent/pi-qqbot-<name>.log (one file per bot, so several pi processes on the same machine never interleave). A single-bot v1 config keeps writing pi-qqbot.log. Each line starts with a local timestamp that carries the UTC offset, e.g. [2026-10-24T07:39:09.762+08:00], so it lines up with file mtimes and process start times without mental arithmetic.

Changelog

See CHANGELOG.en.md — every release with what changed and why. (中文：CHANGELOG.zh-CN.md) The progress-report pause/resume (/progress off / on) landed in 1.5.0; multi-bot auto-claiming in 2.0.0; receiving QQ images/files (saved to temp files and handed to pi as 图片路径 <path>) in 2.1.0; sending local files to QQ (qq_send_file / /sendfile, chunked rich-media upload) in 2.2.0.

License

MIT