@zxh126/pi-qqbot 2.2.1 → 2.3.0

package/CHANGELOG.md

@@ -3,6 +3,45 @@
 本文件记录 pi-qqbot 的版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
 版本号遵循 [SemVer](https://semver.org/lang/zh-CN/)。
 
+## [2.3.0] - 2026-10-31
+
+### Added
+
+- **远程上下文提醒**：`before_agent_start` 里先判断「这一轮是不是本扩展刚派发的 QQ 消息」，是才把一段说明写进
+  系统提示的 `qq-remote-context` section（排在用户消息之前，QQ 侧与 TUI 都看不到）：说明对话来自远程 QQ 用户、
+  对方看不到本机屏幕与弹窗；默认**禁用桌面截屏 / 屏幕 OCR / UI 自动化 / 键鼠模拟 / 带界面的浏览器**
+  （点名 `mcp__screenshot`、`mcp__winui`），需要图就离屏渲染生成 PNG 再用 `qq_send_file` 发回，
+  只有确认是否锁屏时才允许截一次桌面。**仅仅载入扩展、或本机 TUI 直接对话时都不注入**，必须等第一条 QQ 消息真的开跑。
+- **系统提示规则**：每次**来自 QQ 的** run 追加三条短规则（远程用户 / 锁屏→离屏渲染 /
+  需要人工就直说），避免长会话被压缩摘要后丢失；同一轮重复触发不叠加，本机 TUI 自己的 run 不加。
+- **压缩后重注入**：`session_compact` 之后清掉「已提醒」标记，下一条消息重新注入。
+- **配置 `remote`**：`notice`（默认 `true`，每会话一次）、`guidelines`（默认 `true`）、`extra`（追加到提醒末尾，
+  默认空）；顶层默认值 + 每个 bot 逐键覆盖。
+- **本机接管更正**：同一个会话里「上一轮来自 QQ、下一轮本机 TUI 直接打字」时，本机那一轮注入一次
+  `qq-local-handoff` section（「远程 QQ 用户」前提作废：可正常截屏、不需要 `qq_send_file`），连续本机对话不重复；
+  用 `input` 事件的 `source=interactive` 识别（本扩展的 `sendUserMessage` 是 `extension`，不会误判）；
+  QQ run 跑到一半时插话不算接管（没有新的 run）。`/status` 新增「来源: QQ（远程）/ 本机（TUI）」。
+
+### Fixed
+
+- **等审批期间不再推自动进度**：有工具审批在等用户回复时，自动进度推送暂缓（否则每 15s 一条进度会把审批提示
+  顶出屏幕），审批处理完（或超时）后下一拍自动恢复；主动问 `/progress` 不受影响；`/status` 会显示
+  「等审批期间暂缓」。本会话内手动暂停（`/progress off`）与配额静默的语义不变。
+
+### Tests
+
+- 新增 `test/remote-notice.test.mjs`（默认值 / 文案要素 / `extra` 追加 / 系统规则长度）。
+- `test/config.test.mjs` 新增 `remote` 全局默认 + 账号逐键覆盖用例。
+- `test/accounts.test.mjs` 新增 3 个用例：**本机直接对话不注入**、第一条 QQ 消息的 run 才注入且每会话一次、
+  压缩后重注入；`remote.notice=false` 只关说明、`remote.extra` 追加；`remote.guidelines=false` 只关规则，
+  且同一轮重复触发不叠加。
+- `test/progress.test.mjs` 新增用例：等审批期间不推送、`/status` 显示暂缓、手动问进度仍回一次、审批处理完自动恢复。
+- `test/accounts.test.mjs` 再加 2 个用例：本机接管只更正一次（`/status` 显示来源）；交接待定会被新的 QQ 轮覆盖，
+  `source=extension` 的 input 不算接管。
+- `test/remote-notice.test.mjs` 加 `qq-local-handoff` 的 tag 与文案断言。
+
+## [Unreleased]
+
 ## [2.2.1] - 2026-02-11
 
 ### Fixed

package/README.md

@@ -13,6 +13,7 @@ Bridge the **[Pi](https://pi.dev) coding agent** into QQ private (C2C) chats: se
 | **Chat-driven agent** | QQ private messages are fed into the current pi session; the assistant's answer is sent back to QQ (long replies are split automatically). |
 | **Message queue** | While a task is running, further QQ messages are **queued** instead of rejected; each one starts automatically as soon as the current run settles. `/cancel` is the exception — it acts immediately and clears the queue. |
 | **Remote approval** | Before pi runs `bash` / `powershell` / `write` / `edit` — or any tool annotated `destructiveHint` — the bot asks in QQ first. |
+| **Remote-context notice** | The first QQ message of a session is really handed to pi (loading the extension or chatting locally in the TUI adds nothing), then the bot tells it the conversation comes from a remote QQ user and that the machine may be locked: desktop screenshots / screen OCR / UI automation / headed browsers are off by default, images must be rendered off-screen and sent with `qq_send_file`. Re-injected after context compaction. |
 | **Session-scoped "always allow"** | Reply 「以后都同意」 and every approval request in the **current session** is auto-approved, including the one already waiting. |
 | **Single-instance lock** | Only one pi process hosts the QQ gateway; the others stand by and take over automatically when the host exits. |
 | **Cancel a running task** | Send `/cancel` (or 「取消」/「停止」) and the current run is aborted immediately — the QQ reply, the pending tool calls, the half-written answer and the pending queue are all cleaned up. |
@@ -64,6 +65,11 @@ Then create `~/.pi/agent/pi-qqbot.json`:
   "files": {
     "enabled": true,
     "maxBytes": 31457280
+  },
+  "remote": {
+    "notice": true,
+    "guidelines": true,
+    "extra": ""
   }
 }
 ```
@@ -90,6 +96,9 @@ Then create `~/.pi/agent/pi-qqbot.json`:
 | `attachments.maxFiles` | `200` | Keep at most this many files in the directory (oldest are deleted) |
 | `files.enabled` | `true` | Allow sending local files to QQ (both the tool and `/sendfile`); `false` refuses |
 | `files.maxBytes` | `31457280` | Per-file limit for sending (30 MB; QQ hard limit is 200 MB) |
+| `remote.notice` | `true` | Inject a one-time "this is a remote QQ user" note before the first message handed to pi in a session (QQ-side invisible; re-injected after compaction) |
+| `remote.guidelines` | `true` | Also append three short rules to the system prompt of every run started from QQ (remote user, locked screen → off-screen rendering, ask instead of waiting) |
+| `remote.extra` | `""` | Extra text appended to the end of the built-in notice |
 
 Credentials can also come from the `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` environment variables (single-bot setup only).
 
@@ -117,7 +126,7 @@ Start pi, then message the bot in QQ; pi handles it and replies.
 | Command | Description |
 |---|---|
 | `/reset` | Clear the reply buffer, approval memory and session-wide auto-approve (**does not** switch sessions — send `/new` for that) |
-| `/status` | Show the bot this process serves (name + working directory), busy/idle state, queue length, auto-approve state, pending approval count and the progress-report mode |
+| `/status` | Show the bot this process serves (name + working directory), busy/idle state, origin of the last turn (QQ / local TUI), queue length, auto-approve state, pending approval count and the progress-report mode |
 | `/queue` | Show the queue (aliases: `/q`); `/queue clear` empties it, `/queue drop <id>` removes one entry |
 | `/progress` | **Show the current progress summary immediately** (aliases: `/p`, 「进度」, 「当前进度」, 「进展」; plain-text questions like 「到哪了」「怎么样了」 work while busy). While you paused reports yourself it only replies once — use `/progress on` to resume; while reports are merely quota-quiet, asking resumes them |
 | `/progress off` | **Pause automatic progress reports for the rest of the session** (aliases: `pause`, `stop`, `暂停`, 「暂停汇报」, 「关闭汇报」). Manual `/progress` still works, it just no longer resumes the timer |
@@ -189,6 +198,31 @@ Notes:
 - 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:
@@ -306,7 +340,10 @@ While a run is in progress, a summary is pushed to QQ every `progress.intervalMs
 - **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 four modes you are in (on / paused-by-you / quota-quiet / disabled).
+  `/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.

package/config.ts

@@ -8,6 +8,7 @@ import {
   DEFAULT_SEND_MAX_BYTES,
 } from "./constants";
 import { DEFAULT_COMMANDS, type CommandConfig } from "./slash";
+import { DEFAULT_REMOTE, type RemoteConfig } from "./remote";
 import { DEFAULT_QUEUE_MAX } from "./queue";
 
 export interface QueueConfig {
@@ -65,6 +66,8 @@ export interface QQBotConfig {
   attachments: AttachmentConfig;
   /** 把本机文件发到 QQ */
   files: FilesConfig;
+  /** 「以下对话来自远程用户」提醒与系统提示规则 */
+  remote: RemoteConfig;
 }
 
 export interface FilesConfig {
@@ -96,6 +99,7 @@ export interface QQBotsEntry {
   progress?: Partial<ProgressConfig>;
   attachments?: Partial<AttachmentConfig>;
   files?: Partial<FilesConfig>;
+  remote?: Partial<RemoteConfig>;
 }
 
 /** 校验并归一化后的账号（凭据 + 合并好的完整配置） */
@@ -187,6 +191,11 @@ export function resolveConfig(
       enabled: entry.files?.enabled ?? file.files?.enabled ?? true,
       maxBytes: Number(entry.files?.maxBytes ?? file.files?.maxBytes ?? DEFAULT_SEND_MAX_BYTES),
     },
+    remote: {
+      notice: entry.remote?.notice ?? file.remote?.notice ?? DEFAULT_REMOTE.notice,
+      guidelines: entry.remote?.guidelines ?? file.remote?.guidelines ?? DEFAULT_REMOTE.guidelines,
+      extra: String(entry.remote?.extra ?? file.remote?.extra ?? DEFAULT_REMOTE.extra).trim(),
+    },
   };
 }
 

package/docs/README.zh-CN.md

@@ -13,6 +13,7 @@
 | **对话驱动 agent** | QQ 单聊消息送入当前 pi 会话，AI 的回复发回 QQ（长文本自动分片）。 |
 | **消息队列** | 正在处理任务时，后续 QQ 消息会被**排队**而不是被拒；当前任务结束（settled）后按到达顺序自动逐条执行。`/cancel` 是例外——立即生效并清空队列。 |
 | **远程审批** | pi 执行 `bash` / `powershell` / `write` / `edit`，或任何带 `destructiveHint` 注解的工具前，先在 QQ 里申请审批。 |
+| **远程上下文提醒** | **每个会话第一次真正把 QQ 消息交给 pi 跑起来**时，才告诉它「对话来自远程 QQ 用户、本机可能锁屏」：桌面截屏 / 屏幕 OCR / UI 自动化 / 带界面的浏览器默认禁用，要图就离屏渲染再用 `qq_send_file` 发回。仅载入扩展、或本机 TUI 直接对话时都不注入；上下文压缩后自动重新注入。 |
 | **会话级「以后都同意」** | 回复「以后都同意」，**当前会话**内所有审批请求直接放行，连已经挂起的那条也一起放行。 |
 | **单实例锁** | 只有一个 pi 进程作为宿主连接 QQ，其余待命，宿主退出后自动接管。 |
 | **中断正在运行的任务** | 发 `/cancel`（或「取消」/「停止」），当前任务立刻中断 —— QQ 回复、待审批工具调用、写到一半的回答、排队中的消息一并清理。 |
@@ -64,6 +65,11 @@ pi install ./pi-qqbot
   "files": {
     "enabled": true,
     "maxBytes": 31457280
+  },
+  "remote": {
+    "notice": true,
+    "guidelines": true,
+    "extra": ""
   }
 }
 ```
@@ -90,6 +96,9 @@ pi install ./pi-qqbot
 | `attachments.maxFiles` | `200` | 目录内最多保留多少个文件（超出删最旧） |
 | `files.enabled` | `true` | 是否允许把本机文件发到 QQ（工具与 `/sendfile` 共用）；`false` 则拒绕 |
 | `files.maxBytes` | `31457280` | 发送单个文件的上限（30MB；QQ 硬限 200MB） |
+| `remote.notice` | `true` | 每会话第一条消息交给 pi 前注入一次「对话来自远程用户」的说明（QQ 侧不可见，压缩后重新注入） |
+| `remote.guidelines` | `true` | 每次来自 QQ 的 run 额外往系统提示里加三条短规则（远程用户、锁屏→离屏渲染、需要人工就直说） |
+| `remote.extra` | `""` | 追加到内置提醒末尾的自定义补充 |
 
 也可用环境变量 `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 代替文件里的凭据（仅单 bot 场景）。
 
@@ -115,7 +124,7 @@ pi install ./pi-qqbot
 | 指令 | 说明 |
 |---|---|
 | `/reset` | 重置：清空回复缓冲、审批记忆与自动同意开关（**不换会话**，换会话发 `/new`） |
-| `/status` | 查看本进程服务的 bot（名称 + 工作目录）、忙闲状态、队列长度、自动同意状态、待审批数量、自动汇报模式 |
+| `/status` | 查看本进程服务的 bot（名称 + 工作目录）、忙闲状态、上一轮来源（QQ / 本机 TUI）、队列长度、自动同意状态、待审批数量、自动汇报模式 |
 | `/queue` | 查看队列（别名 `/q`）；`/queue clear` 清空，`/queue drop <编号>` 删一条 |
 | `/progress` | **立即获取当前进度摘要**（别名 `/p`、「进度」「当前进度」「进展」；忙碌时「到哪了」「怎么样了」这类问法同样生效）。手动暂停期间**问一次只回一次**，要重新打开定时汇报需发 `/progress on` 或「恢复汇报」；若只是配额静默，问一次即恢复 |
 | `/progress off` | **在本会话内暂停自动进度汇报**（别名：`pause`、`stop`、`暂停`、「暂停汇报」、「关闭汇报」）。手动 `/progress` 仍可看一次，但不再解除暂停 |
@@ -181,6 +190,28 @@ pi install ./pi-qqbot
 - QQ 侧还有 **200MB 硬上限**和**每天发送文件总容量上限**（错误码 `40093002`），都翻成中文回执。
 - 成功后会回一行：`已发送「报告.pdf」（2.31 MB，文件卡片）`。
 
+### 远程上下文提醒
+
+pi 跑在这台机器上，用户在 QQ 那头——而这台机器可能锁屏。所以**每个会话第一次真正把 QQ 消息交给 pi 跑起来**时，
+插件会往**系统提示**里加一段说明（`qq-remote-context` section，排在用户消息之前，QQ 侧看不到），告诉它：
+
+- 用户是远程的：看不见屏幕、也点不到弹窗，回复应简明扼要；
+- 桌面截屏、屏幕 OCR、UI 自动化、键鼠模拟、带界面的浏览器默认都不要用（文案里点名了 `mcp__screenshot`、`mcp__winui`），
+  锁屏下它们只会拍到锁屏画面或直接失败；
+- 需要图时自己离屏渲染（headless 浏览器渲 HTML、SVG、matplotlib/Pillow…），生成 PNG 再用 `qq_send_file` 发到 QQ，
+  不要为了「确认」先截桌面；
+- 只有确实需要判断是否锁屏时，才允许截一次桌面看有没有内容。
+
+时机很关键：只有本扩展派发的 QQ 消息真的开跑（`before_agent_start`）时才会注入——**仅仅载入扩展、或者本机在 TUI 里
+直接跟 pi 对话，都不会给 pi 发任何东西**。每个会话注入一次（上下文压缩后重新注入；`remote.extra` 可追加你自己的话）。
+开了 `remote.guidelines` 时，同样的要求会压成三条规则，随每次来自 QQ 的 run 一起进系统提示，避免长会话被摘要后丢失。
+`remote.notice: false` / `remote.guidelines: false` 可分别关掉这两部分。
+
+如果同一个会话里你从本机接管——上一轮来自 QQ，下一轮直接在 TUI 里打字——本机那一轮会换成一次性
+`qq-local-handoff` 更正：「远程 QQ 用户」的前提作废（可以正常截屏，不需要 `qq_send_file`）。识别靠 `input` 事件
+（`source: "interactive"`；本扩展自己的 `sendUserMessage` 是 `"extension"`，不会误判），每次交接只更正一次，
+QQ run 还在跑时插话不处理（那时不会开新的 run）。`/status` 会显示 `来源: QQ（远程）` 或 `来源: 本机（TUI）`。
+
 ### QQ 里的斜杠命令
 
 任何以 `/` 开头的消息都会先走路由，再决定是否当成对话：
@@ -287,7 +318,9 @@ pi 的会话一次只跑一轮 agent run，所以串行调度由 bot 自己做
   的自动推送（不重试、不刷屏）；你发 `/progress`（或「进度」）即恢复。
 - **手动暂停/恢复**：`/progress off`（或「暂停汇报」）在本会话内停掉自动推送——跨 run 保留，
   之后问 `/progress` 也不会把它打开；`/progress on`（或「恢复汇报」）恢复。开新会话（`/new`、重启）后
-  恢复默认开启。`/status` 会显示当前处于哪种模式（开启 / 手动暂停 / 配额静默 / 配置关闭）。
+  恢复默认开启。`/status` 会显示当前处于哪种模式（开启 / 手动暂停 / 配额静默 / 等审批暂缓 / 配置关闭）。
+- **审批不被顶走**：有工具审批在等你回复时，自动进度暂缓推送——否则每 15 秒一条进度会把审批提示顶出屏幕；
+  你回复（或审批超时）后，下一拍自动恢复。主动发 `/progress` 照旧可用。
 - **保护最终答案**：答案因配额发不出去时会被缓存，等你发下一条消息时以
   `（上一条回复发送失败，补发如下）` 前缀补发。
 - `agent_settled` / `/cancel` / 会话关闭时定时器都会清掉。

package/index.ts

@@ -39,6 +39,14 @@ import { Approver } from "./approver";
 import { parsePickIndex, pickerExpired, routeSlash, runBridge, type PickerState } from "./slash";
 import { agoLabel, MessageQueue, previewText, type QueuedJob } from "./queue";
 import { ProgressTracker } from "./progress";
+import {
+  buildLocalHandoffNotice,
+  buildRemoteGuidelines,
+  buildRemoteNotice,
+  LOCAL_HANDOFF_SECTION,
+  REMOTE_NOTICE_SECTION,
+  resolveRemoteConfig,
+} from "./remote";
 import { redactSecrets } from "./redact";
 import { ReplyBuffer } from "./stream-buffer";
 import { splitText } from "./util/chunk";
@@ -93,6 +101,14 @@ interface State {
   progressPaused: boolean;
   /** 用户手动暂停自动推送（本会话有效：跨 run 保留，/progress on 恢复） */
   progressMuted: boolean;
+  /** 等审批期间暂缓自动进度推送（避免把审批消息顶走）；审批处理完自动恢复 */
+  progressHeldForApproval: boolean;
+  /** 本会话是否已给 pi 注入过「远程用户」提醒（每会话一次，压缩后重新注入） */
+  remoteNotified: boolean;
+  /** 上一轮 run 的来源：null = 还没跑过 */
+  lastRunOrigin: "qq" | "local" | null;
+  /** 本机在 TUI 接管了对话，等下一轮 run 开跑时更正「远程前提作废」 */
+  localHandoffPending: boolean;
   /** 最终答案发送失败时缓存，下一条消息时补发 */
   undelivered: { openid: string; text: string } | null;
   /** 附件下载 401/403 时重试用的凭据（接入后由 applyClaim 注入） */
@@ -130,6 +146,10 @@ export function createInitialState(): State {
     progressTimer: null,
     progressPaused: false,
     progressMuted: false,
+    progressHeldForApproval: false,
+    remoteNotified: false,
+    lastRunOrigin: null,
+    localHandoffPending: false,
     undelivered: null,
     getToken: null,
     attachmentFetch: null,
@@ -153,6 +173,59 @@ export default function (
 ) {
   const state: State = options?.state ?? createInitialState();
 
+  // ---- 事件：本机用户在 TUI 直接打字（source=interactive）→ 记一笔「可能接管」----
+  // 只记待定，真正注入要等下一轮 run 开跑（before_agent_start）。
+  // 本扩展自己的 sendUserMessage 是 source=extension，不会走到这里；QQ run 跑着时接管不处理。
+  pi.on("input", (event) => {
+    const ev = event as any;
+    if (ev?.source !== "interactive") return;
+    if (state.busy) return;
+    if (state.lastRunOrigin !== "qq") return;
+    if (state.localHandoffPending) return;
+    state.localHandoffPending = true;
+    log("[remote] 检测到本机 TUI 输入，下一轮按「本机用户」前提处理");
+  });
+
+  // ---- 事件：真正开始一轮 run 时，按「来自 QQ 还是本机」准备系统提示 ----
+  // 不在扩展载入时注入，也不在本机 TUI 自己对话时注入：只有 startJob() 派发的
+  // QQ 消息真的开跑（state.busy + currentOpenid）才会走到这里。
+  pi.on("before_agent_start", (event) => {
+    const cfg = state.cfg;
+    if (!cfg) return;
+    if ((event as any).messageType !== "user") return;
+    const options = (event as any).systemPromptOptions;
+    if (!options || typeof options !== "object") return;
+
+    // 本扩展派发的 QQ 消息
+    if (state.busy && state.currentOpenid) {
+      const remote = resolveRemoteConfig(cfg);
+      if (remote.guidelines && Array.isArray(options.promptGuidelines)) {
+        const guidelines = buildRemoteGuidelines();
+        // 同一次 run 可能重复触发（如压缩后重试），别叠加两遍
+        if (!options.promptGuidelines.includes(guidelines[0])) options.promptGuidelines.push(...guidelines);
+      }
+      if (remote.notice && !state.remoteNotified) {
+        state.remoteNotified = true;
+        // 放进系统提示的 section：排在用户消息之前，模型不会把它当成要回复的消息；
+        // 只在本轮生效，操作规则由 guidelines 继续带在后续每一轮。
+        options.sections = { ...(options.sections ?? {}), [REMOTE_NOTICE_SECTION]: buildRemoteNotice(remote) };
+        log("[remote] 首次向 pi 交付 QQ 消息，已注入远程上下文说明（系统提示 section）");
+      }
+      // 又轮到 QQ 了：刚才的本机接管待定作废
+      state.localHandoffPending = false;
+      state.lastRunOrigin = "qq";
+      return;
+    }
+
+    // 本机 TUI/CLI 直接开跑：上一轮是 QQ 的话，更正一次「远程前提作废」
+    const handoff = state.localHandoffPending;
+    state.localHandoffPending = false;
+    state.lastRunOrigin = "local";
+    if (!handoff) return;
+    options.sections = { ...(options.sections ?? {}), [LOCAL_HANDOFF_SECTION]: buildLocalHandoffNotice() };
+    log("[remote] 本机接管本轮对话，已注入「远程前提作废」更正");
+  });
+
   // ---- 事件：run 开始，记住 ctx（取消指令要调用 ctx.abort()）----
   pi.on("agent_start", (_event, ctx) => {
     state.ctx = ctx;
@@ -161,6 +234,7 @@ export default function (
     clearCancelTimer(state);
     state.progress.start();
     state.progressPaused = false;
+    state.progressHeldForApproval = false;
     startProgressTimer(pi, state);
   });
 
@@ -317,6 +391,11 @@ export default function (
 
     // 新会话：清空 remember 记忆与自动同意开关（自动同意只在当前会话有效）
     state.approver.reset();
+    // 远程上下文提醒同样只在本会话提醒一次
+    state.remoteNotified = false;
+    // 「QQ ↔ 本机」的来源切换状态也随会话重置
+    state.lastRunOrigin = null;
+    state.localHandoffPending = false;
     // 手动暂停的自动汇报同样只在本会话有效
     state.progressMuted = false;
     state.progressPaused = false;
@@ -490,6 +569,12 @@ export default function (
     enterStandby();
   });
 
+  // ---- 事件：上下文压缩可能把「远程用户」提醒压掉：下一条消息重新注入 ----
+  pi.on("session_compact", (event) => {
+    state.remoteNotified = false;
+    log("[remote] 上下文已压缩（reason=", String((event as any)?.reason ?? "?"), "），下一条消息重新注入提醒");
+  });
+
   // ---- 事件：session_shutdown 清理 ----
   pi.on("session_shutdown", async (event) => {
     const reason = String((event as any)?.reason ?? "quit");
@@ -719,6 +804,7 @@ function startJob(pi: ExtensionAPI, state: State, job: QueuedJob) {
     "text=",
     job.text.slice(0, 60),
   );
+  // 每会话第一条真正跑起来的 QQ 消息，由 before_agent_start 注入远程上下文说明。
   try {
     void Promise.resolve(
       pi.sendUserMessage(job.text, { expandPromptTemplates: true, deliverAs: "followUp" }),
@@ -1087,7 +1173,7 @@ export async function handleMessage(
         [
           "pi-qqbot 指令:",
           "/progress — 查看进度；/progress off 暂停自动汇报、/progress on 恢复（本会话有效）",
-          "/status — 查看状态（当前 qqbot / 忙闲 / 队列 / 自动同意 / 待审批 / 自动汇报）",
+          "/status — 查看状态（当前 qqbot / 忙闲 / 来源 / 队列 / 自动同意 / 待审批 / 自动汇报）",
           "/queue — 查看队列；/queue clear 清空；/queue drop <编号> 删一条",
           "/reset — 清空回复缓冲、审批记忆与自动同意（不换会话；换会话发 /new）",
           "/cancel（或「取消」「停止」「停」）— 中断正在运行的任务并清空队列",
@@ -1106,6 +1192,7 @@ export async function handleMessage(
       const lines = [
         `bot: ${state.account ? `${state.account.name} (…${state.account.appId.slice(-4)})` : "未接入"} · cwd: ${process.cwd()}`,
         `状态: ${state.busy ? "处理中（发送 /cancel 可中断）" : state.queue.size > 0 ? "空闲，但有排队任务待派发" : "空闲"}`,
+        `来源: ${describeRunOrigin(state)}`,
         `队列: ${state.queue.size} 条待执行${state.queue.size > 0 ? "（发 /queue 查看）" : ""}`,
         `自动同意: ${state.approver.autoAllowed ? "已开启（本会话有效）" : "未开启"}`,
         `待审批: ${state.approver.pendingCount}`,
@@ -1268,9 +1355,22 @@ function stopProgressTimer(state: State) {
 /** 推一条进度摘要；失败就暂停自动推送（用户问一次即恢复）；手动暂停（/progress off）管到底 */
 async function pushProgress(state: State, reason: "tick" | "ask"): Promise<boolean> {
   if (reason === "tick" && (state.progressPaused || state.progressMuted)) return false;
+  // 有审批在等用户回复：暂停自动推送，否则每 15s 一条进度会把审批提示顶出屏幕
+  // （手动问进度不受影响：用户自己要看的）
+  if (reason === "tick" && state.approver.pendingCount > 0) {
+    if (!state.progressHeldForApproval) {
+      state.progressHeldForApproval = true;
+      log("[progress] 有", state.approver.pendingCount, "个待审批，暂缓自动进度推送");
+    }
+    return false;
+  }
   const api = state.api;
   const openid = state.currentOpenid ?? state.lastOpenid;
   if (!api || !openid || !state.busy || !state.progress.running) return false;
+  if (state.progressHeldForApproval) {
+    state.progressHeldForApproval = false;
+    log("[progress] 审批已处理，恢复自动进度推送");
+  }
   const text = state.progress.summary();
   if (!text) return false;
   const ok = await replyTo(api, state, openid, text);
@@ -1281,6 +1381,13 @@ async function pushProgress(state: State, reason: "tick" | "ask"): Promise<boole
   return ok;
 }
 
+/** /status 用：最近一轮对话是谁发起的 */
+function describeRunOrigin(state: State): string {
+  if (state.lastRunOrigin === "qq") return "QQ（远程）";
+  if (state.lastRunOrigin === "local") return "本机（TUI）";
+  return "尚未开始";
+}
+
 /** 自动汇报当前状态的人话描述（/status 用） */
 function describeProgressMode(state: State): string {
   const cfg = state.cfg?.progress;
@@ -1288,7 +1395,8 @@ function describeProgressMode(state: State): string {
   if (cfg?.enabled === false) return "未启用（配置 progress.enabled=false）";
   if (state.progressPaused) return "推送失败已静默，发 /progress 恢复";
   const ms = Number.isFinite(cfg?.intervalMs) && (cfg?.intervalMs ?? 0) >= 50 ? cfg!.intervalMs : 15000;
-  return `开启（每 ${Math.round(ms / 1000)}s）`;
+  const base = `开启（每 ${Math.round(ms / 1000)}s）`;
+  return state.approver.pendingCount > 0 ? `${base}，等审批期间暂缓` : base;
 }
 
 /** /progress 的子命令：暂停 / 恢复自动汇报 */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zxh126/pi-qqbot",
-  "version": "2.2.1",
+  "version": "2.3.0",
   "type": "module",
   "description": "Bridge the Pi coding agent into QQ private chats, with remote tool-call approval",
   "license": "MIT",
@@ -27,7 +27,7 @@
     ]
   },
   "scripts": {
-    "test": "node test/queue.test.mjs && node test/approver.test.mjs && node test/logger.test.mjs && node test/usage-bridge.test.mjs && node test/progress.test.mjs && node test/redact.test.mjs && node test/config.test.mjs && node test/lock.test.mjs && node test/accounts.test.mjs && node test/auth.test.mjs && node test/attachment.test.mjs && node test/upload.test.mjs"
+    "test": "node test/queue.test.mjs && node test/approver.test.mjs && node test/logger.test.mjs && node test/usage-bridge.test.mjs && node test/progress.test.mjs && node test/redact.test.mjs && node test/config.test.mjs && node test/remote-notice.test.mjs && node test/lock.test.mjs && node test/accounts.test.mjs && node test/auth.test.mjs && node test/attachment.test.mjs && node test/upload.test.mjs"
   },
   "files": [
     "*.ts",

package/remote.ts

@@ -0,0 +1,81 @@
+import type { QQBotConfig } from "./config";
+
+/**
+ * 「以下对话来自远程用户」提醒。
+ *
+ * pi 在锁屏/无人值守的机器上替 QQ 侧的远程用户干活：对方看不见屏幕，也没法点弹窗。
+ * 所以在每个会话第一次真正把 QQ 消息交给 pi 跑起来时，把一段说明写进系统提示的
+ * `qq-remote-context` section（排在用户消息之前、QQ 侧不可见），让它从一开始就按
+ * 「远程 + 可能锁屏」的前提工作（默认离屏渲染，而不是截桌面）。
+ *
+ * 注入时机由 index.ts 的 before_agent_start 控制：只有本扩展派发的 QQ 消息真的开跑
+ * 才注入；仅载入扩展、或本机 TUI 直接对话都不会触发。上下文压缩后由 session_compact 复位。
+ */
+
+export interface RemoteConfig {
+	/** 每会话第一条消息注入一次提醒 */
+	notice: boolean;
+	/** 每次来自 QQ 的 run 在系统提示里追加几条规则 */
+	guidelines: boolean;
+	/** 追加在默认提醒末尾的自定义补充（留空 = 只用默认文案） */
+	extra: string;
+}
+
+export const DEFAULT_REMOTE: RemoteConfig = {
+	notice: true,
+	guidelines: true,
+	extra: "",
+};
+
+/** 说明放在系统提示的哪个 section 里（排查会话文件时靠这个 tag 认出来） */
+export const REMOTE_NOTICE_SECTION = "qq-remote-context";
+
+/** 「远程前提作废」更正用的 section tag */
+export const LOCAL_HANDOFF_SECTION = "qq-local-handoff";
+
+/** 配置里的 `remote` 可能缺字段（老配置、测试里手搓的 cfg），这里补齐默认值 */
+export function resolveRemoteConfig(cfg: Partial<Pick<QQBotConfig, "remote">> | null | undefined): RemoteConfig {
+	const raw = cfg?.remote ?? {};
+	return {
+		notice: raw.notice ?? DEFAULT_REMOTE.notice,
+		guidelines: raw.guidelines ?? DEFAULT_REMOTE.guidelines,
+		extra: String(raw.extra ?? DEFAULT_REMOTE.extra).trim(),
+	};
+}
+
+/** 首条消息前的说明：说清来源、锁屏风险、离屏渲染要求 */
+export function buildRemoteNotice(remote: RemoteConfig): string {
+	const lines = [
+		"[pi-qqbot 远程上下文 · 说明，不必回复本条]",
+		"",
+		"接下来的对话来自「远程 QQ 私聊用户」，不是本机终端用户。前提：",
+		"",
+		"1. 对方看不到本机屏幕、也收不到弹窗；回复应简明扼要。",
+		"2. 本机可能锁屏或无人值守。默认不要用桌面截屏、屏幕 OCR、UI 自动化、键鼠模拟、带界面的浏览器" +
+			"（例如 mcp__screenshot、mcp__winui 这类工具）：锁屏下它们只会拍到锁屏画面或直接失败。",
+		"3. 需要图/界面效果时，按项目类型自行选择离屏渲染方案（headless 浏览器渲 HTML、SVG、matplotlib/Pillow 等），" +
+			"生成 PNG 后用 qq_send_file 发到 QQ。不要为了“确认”先截桌面。",
+		"4. 只有确实需要判断是否锁屏时，才允许截一次桌面看有没有内容；其余一律以离屏渲染为准。",
+		"5. 需要人工介入（登录、验证码、实体操作）时直接说明并给替代方案；" +
+			"危险工具会先发到 QQ 等审批，对方可能不在电脑旁。",
+	];
+	if (remote.extra) lines.push("", remote.extra);
+	return lines.join("\n");
+}
+
+/** 本机接管后的更正：只在「上一轮来自 QQ」的第一次本机对话注入（只生效一轮） */
+export function buildLocalHandoffNotice(): string {
+	return [
+		"现在是本机用户在终端直接对话（同一会话内接管），之前「远程 QQ 用户」的前提作废：",
+		"可以正常截屏 / 看屏幕，回复详略按本机需求来，不需要用 qq_send_file 交付。",
+	].join("\n");
+}
+
+/** 系统提示里追加的规则（比首条提醒更短，每次 QQ run 都带上） */
+export function buildRemoteGuidelines(): string[] {
+	return [
+		"对话来自远程 QQ 用户：对方看不到本机屏幕，回复应简明扼要。",
+		"本机可能锁屏：默认禁用桌面截屏/屏幕 OCR/UI 自动化/键鼠模拟/带界面浏览器；要图就离屏渲染，再用 qq_send_file 发送。",
+		"需要本机人工操作时直接说明，不要等待或反复重试。",
+	];
+}