@zxh126/pi-qqbot 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-qqbot contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,117 @@
-# Temporary Holding Version
+# pi-qqbot
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Bridge the **[Pi](https://pi.dev) 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** | [简体中文](README.zh-CN.md)
+
+> **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
+
+| Feature | Description |
+|---|---|
+| **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). |
+| **Remote approval** | Before pi runs `bash` / `powershell` / `write` / `edit` — or any tool annotated `destructiveHint` — the bot asks in QQ first. |
+| **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. |
+| **Built-in commands** | `/new`, `/status`, `/help`. |
+
+## Install
+
+```bash
+# 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`:
+
+```json
+{
+  "appId": "YOUR_APP_ID",
+  "appSecret": "YOUR_APP_SECRET",
+  "sandbox": true,
+  "allowlist": [],
+  "markdownReply": false,
+  "streaming": false,
+  "approve": {
+    "tools": ["bash", "powershell", "write", "edit"],
+    "remember": true
+  }
+}
+```
+
+| Field | Default | Description |
+|---|---|---|
+| `appId` / `appSecret` | required | Credentials of your QQ Open Platform bot |
+| `sandbox` | `false` | Set `true` while the bot is not yet published (sandbox environment) |
+| `allowlist` | `[]` | openid allowlist; empty means no restriction |
+| `markdownReply` | `false` | QQ private chat does not support markdown, keep `false` |
+| `streaming` | `false` | Reserved, streaming is not enabled in v1 |
+| `approve.tools` | `["bash","powershell","write","edit"]` | Tools that require approval; tools annotated `destructiveHint` are always gated too |
+| `approve.remember` | `true` | Remember the decision per tool inside the session (no more prompts for that tool) |
+
+Credentials can also come from the `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` environment variables.
+
+## Usage
+
+Start pi, then message the bot in QQ; pi handles it and replies.
+
+| Command | Description |
+|---|---|
+| `/new` | Reset: clear the reply buffer, approval memory and session-wide auto-approve |
+| `/status` | Show busy/idle state, auto-approve state and pending approval count |
+| `/help` | Show help |
+
+Anything else is forwarded to pi as a user message.
+
+## Remote approval
+
+```text
+[审批 #1] bash: rm -rf node_modules
+回复「同意 1」批准，「拒绝 1」拒绝，「停止」终止本轮。
+要本会话内全部放行，回复「以后都同意」（可用「取消自动同意」关闭）。
+```
+
+Reply vocabulary (approval keywords are Chinese, with English aliases):
+
+| Intent | Reply |
+|---|---|
+| Approve one request | `同意 1` / `allow 1` — a bare `同意` / `allow` applies to the oldest pending request |
+| Reject one request | `拒绝 1` / `deny 1` — a bare `拒绝` / `deny` applies to the oldest pending request |
+| Abort the pending requests | `停止` |
+| Allow everything in this session | `以后都同意`, `一直同意`, `全部放行`, `别再问了`, `always allow` |
+| Back to per-request approval | `取消自动同意`, `恢复审批`, `以后都不同意` |
+
+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 and retry every 5 seconds;
+- when the host exits or crashes (30 second heartbeat timeout), a standby process takes over.
+
+## Prerequisites
+
+1. Create a bot on the [QQ Open Platform](https://q.qq.com/) 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.log`.
+
+## License
+
+MIT

package/README.zh-CN.md

@@ -0,0 +1,117 @@
+# pi-qqbot
+
+把 **[Pi](https://pi.dev) coding agent** 接入 QQ 单聊的桥接插件：在 QQ 里发一句话，让 AI 在运行 pi 的那台机器上干活 —— 执行危险工具前会先在 QQ 里向你申请审批。
+
+[English](README.md) | **简体中文**
+
+> **单会话设计（v1）**：所有 QQ 用户共用同一个 pi 会话。多用户/多会话后续基于 pi SDK 实现。
+
+## 功能
+
+| 功能 | 说明 |
+|---|---|
+| **对话驱动 agent** | QQ 单聊消息送入当前 pi 会话，AI 的回复发回 QQ（长文本自动分片）。 |
+| **远程审批** | pi 执行 `bash` / `powershell` / `write` / `edit`，或任何带 `destructiveHint` 注解的工具前，先在 QQ 里申请审批。 |
+| **会话级「以后都同意」** | 回复「以后都同意」，**当前会话**内所有审批请求直接放行，连已经挂起的那条也一起放行。 |
+| **单实例锁** | 只有一个 pi 进程作为宿主连接 QQ，其余待命，宿主退出后自动接管。 |
+| **内置指令** | `/new`、`/status`、`/help`。 |
+
+## 安装
+
+```bash
+# 从 npm 安装
+pi install npm:@zxh126/pi-qqbot
+
+# 或从本地目录安装（需要先装依赖）
+npm install
+pi install ./pi-qqbot
+```
+
+然后创建 `~/.pi/agent/pi-qqbot.json`：
+
+```json
+{
+  "appId": "你的AppID",
+  "appSecret": "你的AppSecret",
+  "sandbox": true,
+  "allowlist": [],
+  "markdownReply": false,
+  "streaming": false,
+  "approve": {
+    "tools": ["bash", "powershell", "write", "edit"],
+    "remember": true
+  }
+}
+```
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `appId` / `appSecret` | 必填 | QQ 开放平台机器人凭据 |
+| `sandbox` | `false` | 未提审上线的 bot 用 `true`（沙箱环境） |
+| `allowlist` | `[]` | openid 白名单，空 = 不限制 |
+| `markdownReply` | `false` | QQ 单聊不支持 markdown，保持 `false` |
+| `streaming` | `false` | 预留，v1 未启用流式 |
+| `approve.tools` | `["bash","powershell","write","edit"]` | 需要审批的工具名；带 `destructiveHint` 注解的工具同样会拦截 |
+| `approve.remember` | `true` | 会话内按工具记住决策（同类工具不再重复询问） |
+
+也可用环境变量 `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 代替文件里的凭据。
+
+## 使用
+
+启动 pi 后，在 QQ 里给机器人发消息，pi 会处理并回复。
+
+| 指令 | 说明 |
+|---|---|
+| `/new` | 重置：清空回复缓冲、审批记忆与自动同意开关 |
+| `/status` | 查看忙闲状态、自动同意状态、待审批数量 |
+| `/help` | 帮助 |
+
+其余文本都作为用户消息交给 pi。
+
+## 远程审批
+
+```text
+[审批 #1] bash: rm -rf node_modules
+回复「同意 1」批准，「拒绝 1」拒绝，「停止」终止本轮。
+要本会话内全部放行，回复「以后都同意」（可用「取消自动同意」关闭）。
+```
+
+回复用语（审批关键词以中文为主，也支持英文别名）：
+
+| 意图 | 回复 |
+|---|---|
+| 批准某条 | `同意 1` / `allow 1`；裸 `同意` / `allow` 作用于最早的一条待审批 |
+| 拒绝某条 | `拒绝 1` / `deny 1`；裸 `拒绝` / `deny` 作用于最早的一条待审批 |
+| 终止当前待审批 | `停止` |
+| 本会话全部放行 | `以后都同意`、`一直同意`、`全部放行`、`别再问了`、`always allow` |
+| 恢复逐条审批 | `取消自动同意`、`恢复审批`、`以后都不同意` |
+
+语义说明：
+
+- **仅当前会话有效**：自动同意开关只存在于内存，`/new`、pi 新会话，或回复「取消自动同意」类用语后立即失效；不写盘、不跨进程保留。
+- 该开关是**用户的显式指令**，**不受 `approve.remember` 配置限制**。
+- `approve.remember: true` 时会额外**按工具名**记住决策：同意过一次 `bash`，本会话后续 `bash` 不再询问（`/new` 清除）。
+- 审批请求 **10 分钟**超时后自动拒绝并通知；超时**不会**被记成“拒绝”，下次仍会询问。
+- 没有待审批请求时，这类文本会作为普通消息转交给 pi。
+
+## 单实例锁
+
+QQ 网关对同一 bot 只保留一个活跃连接。插件用 `proper-lockfile` 文件锁（`~/.pi/agent/pi-qqbot-<appId>.lock`）：
+
+- 抢到锁的进程 = 宿主，连接 QQ；
+- 其余进程待命，每 5 秒重试；
+- 宿主退出或崩溃（30 秒心跳超时）后，待命进程自动接管。
+
+## 前置条件
+
+1. 在 [QQ 开放平台](https://q.qq.com/) 创建机器人，拿到 **AppID** 与 **AppSecret**。
+2. 未上线阶段配置**沙箱单聊账号**，并把 `sandbox` 设为 `true`。
+3. 正式环境填写服务器公网出口 IP 白名单。
+
+## 日志
+
+调试日志写入 `~/.pi/agent/pi-qqbot.log`。
+
+## License
+
+MIT

package/approver.ts

@@ -0,0 +1,153 @@
+/**
+ * QQ 远程审批：
+ * - 每个待审批请求生成编号，发到 QQ，等用户回复「同意/拒绝 N」或「停止」。
+ * - register 返回一个 Promise，QQ 回复后 resolve 决策。
+ * - remember 记忆：会话内同意/拒绝某工具后，同类工具不再询问。
+ * - 自动同意（「以后都同意」）：会话级开关，开启后本会话内所有需审批的工具直接放行，
+ *   直到 /new、新会话或回复「取消自动同意」为止（不跨会话、不写盘）。
+ */
+export type ApproveDecision = "allow" | "block" | "terminate" | "timeout";
+
+/** parseReply 的解析结果：前四种对应具体动作，always/revoke 操作会话级自动同意 */
+export type ParsedDecision = "allow" | "block" | "terminate" | "always" | "revoke";
+
+export interface ParsedReply {
+  decision: ParsedDecision;
+  /** 缺省表示「作用于最早的一条待审批」，没有待审批时按普通消息处理 */
+  seq?: number;
+}
+
+interface PendingApproval {
+  summary: string;
+  timer: ReturnType<typeof setTimeout>;
+  resolve: (decision: ApproveDecision) => void;
+}
+
+/** 「以后都同意」类表达 */
+const RE_ALWAYS =
+  /(以后|之后|今后|一直|全都|全部|都)\s*(同意|允许|批准|放行)|别再(问|烦|提示)|always\s*(allow|yes)/i;
+/** 「取消自动同意」类表达（含「以后都不同意」） */
+const RE_REVOKE =
+  /(取消|关闭|结束|停止)\s*自动同意|^恢复审批$|(以后|之后|今后|都|全部)\s*不(同意|允许|批准|放行)/;
+/** 「停止」终止本轮 */
+const RE_TERMINATE = /^停止$/;
+/** 带或不带编号的批准/拒绝 */
+const RE_DECIDE = /^(同意|批准|放行|允许|allow|拒绝|驳回|deny)\s*(\d+)?$/i;
+
+export class Approver {
+  private pending = new Map<number, PendingApproval>();
+  private rememberMap = new Map<string, ApproveDecision>();
+  private nextSeq = 1;
+  private autoAllow = false;
+  private timeoutMs: number;
+
+  constructor(timeoutMs: number) {
+    this.timeoutMs = timeoutMs;
+  }
+
+  /** 会话级自动同意是否开启 */
+  get autoAllowed(): boolean {
+    return this.autoAllow;
+  }
+
+  /** 待审批请求数量 */
+  get pendingCount(): number {
+    return this.pending.size;
+  }
+
+  /** 会话内是否已记住某工具的决策 */
+  isRemembered(toolName: string): ApproveDecision | undefined {
+    return this.rememberMap.get(toolName);
+  }
+
+  register(
+    summary: string,
+    onTimeout?: () => void,
+  ): { seq: number; done: Promise<ApproveDecision> } {
+    const seq = this.nextSeq++;
+    const done = new Promise<ApproveDecision>((resolve) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(seq);
+        resolve("timeout");
+        onTimeout?.();
+      }, this.timeoutMs);
+      this.pending.set(seq, { summary, timer, resolve });
+    });
+    return { seq, done };
+  }
+
+  render(seq: number): string {
+    const item = this.pending.get(seq);
+    return [
+      `[审批 #${seq}] ${item?.summary ?? ""}`,
+      `回复「同意 ${seq}」批准，「拒绝 ${seq}」拒绝，「停止」终止本轮。`,
+      `要本会话内全部放行，回复「以后都同意」（可用「取消自动同意」关闭）。`,
+    ].join("\n");
+  }
+
+  /** 最早（编号最小）的待审批请求 */
+  oldestSeq(): number | undefined {
+    let oldest: number | undefined;
+    for (const seq of this.pending.keys()) {
+      if (oldest === undefined || seq < oldest) oldest = seq;
+    }
+    return oldest;
+  }
+
+  parseReply(text: string): ParsedReply | null {
+    const t = text.trim();
+    if (!t) return null;
+    if (RE_REVOKE.test(t)) return { decision: "revoke" };
+    if (RE_ALWAYS.test(t)) return { decision: "always" };
+    if (RE_TERMINATE.test(t)) return { decision: "terminate" };
+    const m = RE_DECIDE.exec(t);
+    if (!m) return null;
+    const allow = /^(同意|批准|放行|允许|allow)$/i.test(m[1]);
+    return { decision: allow ? "allow" : "block", seq: m[2] ? Number(m[2]) : undefined };
+  }
+
+  confirm(seq: number, decision: ApproveDecision): boolean {
+    const item = this.pending.get(seq);
+    if (!item) return false;
+    clearTimeout(item.timer);
+    this.pending.delete(seq);
+    item.resolve(decision);
+    return true;
+  }
+
+  /** 放行所有待审批请求（开启自动同意时用） */
+  allowAll(): number {
+    return this.resolveAll("allow");
+  }
+
+  /** 终止所有待审批请求（「停止」） */
+  terminateAll(): number {
+    return this.resolveAll("terminate");
+  }
+
+  /** 开启/关闭会话级自动同意 */
+  setAutoAllow(on: boolean): void {
+    this.autoAllow = on;
+  }
+
+  remember(toolName: string, decision: ApproveDecision) {
+    this.rememberMap.set(toolName, decision);
+  }
+
+  /** 清空会话状态（remember 记忆 + 自动同意开关） */
+  reset() {
+    this.rememberMap.clear();
+    this.autoAllow = false;
+  }
+
+  private resolveAll(decision: ApproveDecision): number {
+    let count = 0;
+    for (const [seq, item] of [...this.pending]) {
+      clearTimeout(item.timer);
+      this.pending.delete(seq);
+      item.resolve(decision);
+      count++;
+    }
+    return count;
+  }
+}

package/config.ts

@@ -0,0 +1,45 @@
+import fs from "node:fs";
+import { CONFIG_PATH } from "./constants";
+
+export interface ApproveConfig {
+  /** 需要 QQ 审批的工具名（如 bash/powershell/write/edit） */
+  tools: string[];
+  /** 会话内记住选择：同意/拒绝后同类工具不再询问（「以后都同意」不受此开关限制） */
+  remember: boolean;
+}
+
+export interface QQBotConfig {
+  appId: string;
+  appSecret: string;
+  sandbox: boolean;
+  allowlist: string[];
+  markdownReply: boolean;
+  streaming: boolean;
+  toolProgress: boolean;
+  approve: ApproveConfig;
+}
+
+export function loadConfig(): QQBotConfig | null {
+  let file: any = {};
+  try {
+    file = JSON.parse(fs.readFileSync(CONFIG_PATH(), "utf8"));
+  } catch {
+    /* 文件不存在或非法不致命，凭据可完全来自环境变量 */
+  }
+  const appId = process.env.QQ_BOT_APPID ?? file.appId;
+  const appSecret = process.env.QQ_BOT_APPSECRET ?? file.appSecret;
+  if (!appId || !appSecret) return null;
+  return {
+    appId,
+    appSecret,
+    sandbox: file.sandbox ?? false,
+    allowlist: file.allowlist ?? [],
+    markdownReply: file.markdownReply ?? false,
+    streaming: file.streaming ?? false,
+    toolProgress: file.toolProgress ?? false,
+    approve: {
+      tools: file.approve?.tools ?? ["bash", "powershell", "write", "edit"],
+      remember: file.approve?.remember ?? true,
+    },
+  };
+}

package/constants.ts

@@ -0,0 +1,16 @@
+import os from "node:os";
+import path from "node:path";
+
+export const TOKEN_URL = "https://api.bot.qq.com/app/getAppAccessToken";
+export const REST_BASE_PROD = "https://api.bot.qq.com";
+export const REST_BASE_SANDBOX = "https://sandbox.api.sgroup.qq.com";
+export const INTENT_GROUP_AND_C2C = 1 << 25;
+export const PASSIVE_WINDOW_MS = 60 * 60 * 1000; // 单聊被动窗口 60 分钟
+export const MAX_REPLIES_PER_MSG_ID = 4;
+export const APPROVAL_TIMEOUT_MS = 10 * 60 * 1000;
+export const STREAM_FLUSH_INTERVAL_MS = 1200;
+export const GATEWAY_PATH = "/gateway";
+
+const PI_DIR = path.join(os.homedir(), ".pi", "agent");
+export const CONFIG_PATH = () => path.join(PI_DIR, "pi-qqbot.json");
+export const LOCK_PATH = (appId: string) => path.join(PI_DIR, `pi-qqbot-${appId}.lock`);

package/index.ts

@@ -0,0 +1,352 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadConfig, QQBotConfig } from "./config";
+import {
+  REST_BASE_PROD,
+  REST_BASE_SANDBOX,
+  INTENT_GROUP_AND_C2C,
+  PASSIVE_WINDOW_MS,
+  APPROVAL_TIMEOUT_MS,
+  LOCK_PATH,
+} from "./constants";
+import { log } from "./logger";
+import { tryAcquireLock, startLockRetry } from "./lock";
+import { AuthManager } from "./qq/auth";
+import { QQApi } from "./qq/api";
+import { createGatewayUrlFetcher, QQGateway, QQMessage } from "./qq/gateway";
+import { Approver } from "./approver";
+import { ReplyBuffer } from "./stream-buffer";
+import { splitText } from "./util/chunk";
+
+interface State {
+  cfg: QQBotConfig | null;
+  api: QQApi | null;
+  approver: Approver;
+  gateway: QQGateway | null;
+  currentOpenid: string | null;
+  replyBuffer: ReplyBuffer;
+  releaseLock: (() => Promise<void>) | null;
+  stopRetry: (() => void) | null;
+  passiveRefs: Map<string, { msgId: string; receivedAt: number }>;
+  busy: boolean;
+}
+
+export default function (pi: ExtensionAPI) {
+  const state: State = {
+    cfg: null,
+    api: null,
+    approver: new Approver(APPROVAL_TIMEOUT_MS),
+    gateway: null,
+    currentOpenid: null,
+    replyBuffer: new ReplyBuffer(),
+    releaseLock: null,
+    stopRetry: null,
+    passiveRefs: new Map(),
+    busy: false,
+  };
+
+  // ---- 事件：累积 assistant 文本 ----
+  pi.on("message_update", (event) => {
+    const ev = event.assistantMessageEvent as any;
+    if (ev?.type === "text_delta") {
+      state.replyBuffer.append(ev.delta ?? ev.text ?? "");
+    }
+  });
+
+  // ---- 事件：run 结束，发回复 ----
+  pi.on("agent_settled", async () => {
+    const text = state.replyBuffer.take();
+    const openid = state.currentOpenid;
+    state.currentOpenid = null;
+    state.busy = false;
+    if (!text || !openid || !state.api) return;
+    log("[reply] agent_settled，回复 openid=", openid, "text=", text.slice(0, 80));
+    for (const chunk of splitText(text)) {
+      await state.api.sendC2C(openid, chunk).catch((e) => log("[reply] 发送失败:", String(e)));
+    }
+  });
+
+  // ---- 事件：tool_call 审批 ----
+  pi.on("tool_call", async (event) => {
+    const openid = state.currentOpenid;
+    if (!openid || !state.api || !state.cfg) return; // 无 QQ 上下文，放行
+    const ev = event as any;
+    const toolName: string = ev.toolName ?? "tool";
+    const cfg = state.cfg;
+
+    // 判断是否需要审批：配置的 tools 列表 + destructiveHint 兑底
+    const allTools = (pi.getAllTools() ?? []) as any[];
+    const toolMeta = allTools.find((t) => t.name === toolName);
+    const destructive = toolMeta?.annotations?.destructiveHint === true;
+    const needsApproval = cfg.approve.tools.includes(toolName) || destructive;
+    if (!needsApproval) return; // 放行
+
+    // 会话级自动同意（用户回复过「以后都同意」）：本会话内直接放行，不落盘、不跨会话
+    if (state.approver.autoAllowed) {
+      log("[approve] 自动同意放行:", toolName);
+      return;
+    }
+
+    // 会话内已记住的决策
+    const remembered = cfg.approve.remember ? state.approver.isRemembered(toolName) : undefined;
+    if (remembered === "allow") return; // 已记住放行
+    if (remembered === "block") return { block: true, reason: `QQ 用户已拒绝 ${toolName}` };
+    if (remembered === "terminate") return { block: true, terminate: true, reason: "已停止" };
+
+    const summary = summarizeTool(ev);
+    log("[approve] 工具需要审批:", summary);
+    const { seq, done } = state.approver.register(summary, () => {
+      // 超时通知
+      state.api?.sendC2C(openid, `审批 #${seq} 已超时，已自动拒绝。`).catch(() => {});
+    });
+    await state.api.sendC2C(openid, state.approver.render(seq)).catch(() => {});
+    const decision = await done;
+
+    if (decision === "allow") {
+      if (cfg.approve.remember) state.approver.remember(toolName, "allow");
+      log("[approve] 用户批准 #", seq);
+      return;
+    }
+    if (decision === "terminate") {
+      log("[approve] 用户停止");
+      return { block: true, terminate: true, reason: "QQ 用户停止" };
+    }
+    if (decision === "timeout") {
+      // 超时不写 remember：一次没回复不该永久封死该工具
+      log("[approve] 审批超时 #", seq);
+      return { block: true, reason: `QQ 审批超时（#${seq}）：${summary}` };
+    }
+    // block（用户显式拒绝）
+    if (cfg.approve.remember) state.approver.remember(toolName, "block");
+    log("[approve] 用户拒绝 #", seq);
+    return { block: true, reason: `QQ 用户拒绝了 ${summary}` };
+  });
+
+  // ---- 事件：session_start 抢锁 + 启动网关 ----
+  pi.on("session_start", async () => {
+    const cfg = loadConfig();
+    if (!cfg) {
+      log("[setup] 缺少 QQ_BOT_APPID/QQ_BOT_APPSECRET 或配置，插件未启用");
+      return;
+    }
+    state.cfg = cfg;
+    // 新会话：清空 remember 记忆与自动同意开关（自动同意只在当前会话有效）
+    state.approver.reset();
+    log("[setup] 配置已加载 sandbox=", cfg.sandbox);
+
+    const restBase = cfg.sandbox ? REST_BASE_SANDBOX : REST_BASE_PROD;
+    const auth = new AuthManager(cfg.appId, cfg.appSecret);
+    const api = new QQApi({ restBase, getToken: () => auth.getToken() });
+    state.api = api;
+
+    const startGateway = () => {
+      const gateway = new QQGateway({
+        getGatewayUrl: createGatewayUrlFetcher(restBase, () => auth.getToken()),
+        getToken: () => auth.getToken(),
+        intents: INTENT_GROUP_AND_C2C,
+        connected: () => {},
+        disconnected: () => {},
+        message: (msg) => handleMessage(pi, state, api, cfg, msg),
+      });
+      state.gateway = gateway;
+      log("[lock] 启动 QQ 网关");
+      gateway.start();
+    };
+
+    // 单实例锁：只有抢到锁的实例连接 QQ
+    const lockPath = LOCK_PATH(cfg.appId);
+    const release = await tryAcquireLock(lockPath);
+    if (release) {
+      state.releaseLock = release;
+      log("[lock] 抢锁成功，本实例为 QQ bot 宿主");
+      startGateway();
+    } else {
+      log("[lock] 锁被占用，本实例进入待命");
+      state.stopRetry = startLockRetry(lockPath, (r) => {
+        state.releaseLock = r;
+        log("[lock] 抢锁成功，接管 QQ bot");
+        startGateway();
+      });
+    }
+  });
+
+  // ---- 事件：session_shutdown 清理 ----
+  pi.on("session_shutdown", async () => {
+    log("[shutdown] 清理资源");
+    if (state.stopRetry) state.stopRetry();
+    state.gateway?.stop();
+    if (state.releaseLock) {
+      try {
+        await state.releaseLock();
+      } catch {
+        /* ignore */
+      }
+    }
+    state.releaseLock = null;
+    state.gateway = null;
+    state.api = null;
+  });
+}
+
+// ---- QQ 消息处理 ----
+async function handleMessage(
+  pi: ExtensionAPI,
+  state: State,
+  api: QQApi,
+  cfg: QQBotConfig,
+  msg: QQMessage,
+) {
+  try {
+    log("[msg] 收到消息 openid=", msg.openid, "content=", msg.content.slice(0, 100));
+    if (cfg.allowlist.length > 0 && !cfg.allowlist.includes(msg.openid)) {
+      log("[msg] 被 allowlist 拦截");
+      return;
+    }
+    state.passiveRefs.set(msg.openid, { msgId: msg.msgId, receivedAt: Date.now() });
+
+    // 远程审批回复优先
+    const parsed = state.approver.parseReply(msg.content.trim());
+    if (parsed) {
+      if (parsed.decision === "terminate") {
+        const n = state.approver.terminateAll();
+        state.approver.setAutoAllow(false);
+        await replyTo(api, state, msg.openid, `已终止 ${n} 个待审批请求，自动同意已关闭`);
+        return;
+      }
+      if (parsed.decision === "always") {
+        // 「以后都同意」= 本会话内全部放行：立刻开启开关并放行当前所有待审批
+        state.approver.setAutoAllow(true);
+        const n = state.approver.allowAll();
+        log("[approve] 开启会话级自动同意，放行", n, "个待审批");
+        await replyTo(
+          api,
+          state,
+          msg.openid,
+          [
+            `已开启自动同意：本会话内需审批的工具全部放行${n > 0 ? `，已放行 ${n} 个待审批请求` : ""}。`,
+            "回复「取消自动同意」或 /new 恢复逐条审批。",
+          ].join("\n"),
+        );
+        return;
+      }
+      if (parsed.decision === "revoke") {
+        const was = state.approver.autoAllowed;
+        state.approver.setAutoAllow(false);
+        log("[approve] 关闭自动同意 was=", was);
+        await replyTo(
+          api,
+          state,
+          msg.openid,
+          was ? "已关闭自动同意，恢复逐条审批。" : "当前没有开启自动同意，仍需逐条审批。",
+        );
+        return;
+      }
+      // allow / block：没写编号时作用于最早的一条待审批
+      const seq = parsed.seq ?? state.approver.oldestSeq();
+      if (seq !== undefined) {
+        const ok = state.approver.confirm(seq, parsed.decision);
+        const text = !ok
+          ? `#${seq} 不存在或已超时`
+          : parsed.decision === "allow"
+            ? `已批准 #${seq}`
+            : `已拒绝 #${seq}`;
+        await replyTo(api, state, msg.openid, text);
+        return;
+      }
+      // 没有待审批：这句「同意/拒绝」当普通消息交给 pi，继续往下走
+      log("[msg] 审批类文本但无待审批，按普通消息处理");
+    }
+
+    // 内置指令
+    const cmd = parseCommand(msg.content);
+    if (cmd === "help") {
+      await replyTo(
+        api,
+        state,
+        msg.openid,
+        ["pi-qqbot 指令:", "/new — 开新会话", "/status — 查看状态", "/help — 帮助", "其余文本交给 pi 处理。"].join("\n"),
+      );
+      return;
+    }
+    if (cmd === "status") {
+      await replyTo(
+        api,
+        state,
+        msg.openid,
+        [
+          `状态: ${state.busy ? "处理中" : "空闲"}`,
+          `自动同意: ${state.approver.autoAllowed ? "已开启（本会话有效）" : "未开启"}`,
+          `待审批: ${state.approver.pendingCount}`,
+        ].join("\n"),
+      );
+      return;
+    }
+    if (cmd === "new") {
+      state.replyBuffer.reset();
+      state.approver.reset();
+      await replyTo(api, state, msg.openid, "已重置（含审批记忆/自动同意），下一条消息开启新对话。");
+      return;
+    }
+
+    // 忙检查：单会话串行处理
+    if (state.busy) {
+      await replyTo(api, state, msg.openid, "上一条消息还在处理中，请稍候…");
+      return;
+    }
+
+    // ack
+    await replyTo(api, state, msg.openid, "收到，正在处理");
+
+    state.currentOpenid = msg.openid;
+    state.busy = true;
+    state.replyBuffer.reset();
+
+    // 交给 pi 处理
+    pi.sendUserMessage(msg.content, { deliverAs: "followUp" });
+    log("[msg] 已送入 pi:", msg.content.slice(0, 60));
+  } catch (e) {
+    log("[msg] 处理失败:", String(e));
+    await replyTo(api, state, msg.openid, `处理失败: ${String(e).slice(0, 200)}`).catch(() => {});
+  }
+}
+
+async function replyTo(
+  api: QQApi,
+  state: State,
+  openid: string,
+  text: string,
+  format: "text" | "markdown" = "text",
+) {
+  const ref = state.passiveRefs.get(openid);
+  for (const chunk of splitText(text)) {
+    const usePassive = !!ref && Date.now() - ref.receivedAt < PASSIVE_WINDOW_MS;
+    try {
+      await api.sendC2C(openid, chunk, usePassive ? { msgId: ref.msgId, format } : { format });
+      log("[reply] 已发送 (passive=", usePassive, "):", chunk.slice(0, 50));
+    } catch (e) {
+      log("[reply] 发送失败:", String(e));
+    }
+  }
+}
+
+function parseCommand(text: string): "new" | "status" | "help" | null {
+  const m = /^\/(new|status|help)\s*$/i.exec(text.trim());
+  return m ? (m[1].toLowerCase() as "new" | "status" | "help") : null;
+}
+
+/** 从 tool_call 事件提取可读摘要，让用户在 QQ 里看清要执行什么 */
+function summarizeTool(event: any): string {
+  const input = event.input ?? {};
+  switch (event.toolName) {
+    case "bash":
+    case "powershell":
+      return `${event.toolName}: ${String(input.command ?? "").slice(0, 200)}`;
+    case "write":
+    case "edit":
+    case "read":
+      return `${event.toolName}: ${String(input.path ?? input.file ?? input.filePath ?? "").slice(0, 200)}`;
+    case "grep":
+      return `${event.toolName}: ${String(input.pattern ?? "").slice(0, 200)}`;
+    default:
+      return `${event.toolName}: ${JSON.stringify(input).slice(0, 200)}`;
+  }
+}

package/lock.ts

@@ -0,0 +1,33 @@
+import lockfile from "proper-lockfile";
+
+const LOCK_RETRY_MS = 5000; // 待命实例抢锁间隔
+const LOCK_STALE_MS = 30000; // 锁文件超过 30 秒无心跳视为僵尸锁
+const LOCK_UPDATE_MS = 10000; // 宿主每 10 秒心跳刷新锁
+
+type Release = () => Promise<void>;
+
+/** 抢文件锁：成功返回 release 函数；被占/异常返回 null */
+export async function tryAcquireLock(lockPath: string): Promise<Release | null> {
+  try {
+    const release = await lockfile.lock(lockPath, {
+      retries: 0,
+      stale: LOCK_STALE_MS,
+      update: LOCK_UPDATE_MS,
+      realpath: false,
+    });
+    return release;
+  } catch {
+    return null;
+  }
+}
+
+export function startLockRetry(lockPath: string, onAcquired: (release: Release) => void): () => void {
+  const timer = setInterval(async () => {
+    const release = await tryAcquireLock(lockPath);
+    if (release) {
+      clearInterval(timer);
+      onAcquired(release);
+    }
+  }, LOCK_RETRY_MS);
+  return () => clearInterval(timer);
+}

package/logger.ts

@@ -0,0 +1,18 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const LOG_PATH = path.join(os.homedir(), ".pi", "agent", "pi-qqbot.log");
+
+function ts() {
+  return new Date().toISOString();
+}
+
+export function log(...args: unknown[]) {
+  const line = `[${ts()}] ${args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ")}\n`;
+  try {
+    fs.appendFileSync(LOG_PATH, line, "utf8");
+  } catch {
+    /* ignore */
+  }
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@zxh126/pi-qqbot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Bridge the Pi coding agent into QQ private chats, with remote tool-call approval",
+  "license": "MIT",
+  "keywords": ["pi-package", "pi", "qq", "qqbot", "bot", "coding-agent", "approval"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitee.com/zxh126/pi-qqbot.git"
+  },
+  "homepage": "https://gitee.com/zxh126/pi-qqbot#readme",
+  "bugs": {
+    "url": "https://gitee.com/zxh126/pi-qqbot/issues"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "files": ["*.ts", "qq", "util", "README.md", "README.zh-CN.md", "LICENSE"],
+  "dependencies": {
+    "ws": "^8.18.0",
+    "proper-lockfile": "^4.1.2"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}

package/qq/api.ts

@@ -0,0 +1,81 @@
+import { MAX_REPLIES_PER_MSG_ID } from "../constants";
+
+export interface QQApiOptions {
+  restBase: string;
+  getToken: () => Promise<string>;
+  fetchFn?: typeof fetch;
+}
+
+export interface SendOptions {
+  msgId?: string;
+  format?: "text" | "markdown";
+}
+
+export class QQApi {
+  private queue: Promise<void> = Promise.resolve();
+  private seqCounters = new Map<string, number>();
+
+  constructor(private opts: QQApiOptions) {}
+
+  sendC2C(openid: string, content: string, options: SendOptions = {}): Promise<void> {
+    const task = this.queue.then(() => this.doSend(openid, content, options));
+    this.queue = task.catch(() => {});
+    return task;
+  }
+
+  private nextSeq(msgId?: string): number | undefined {
+    if (!msgId) return undefined;
+    const used = this.seqCounters.get(msgId) ?? 0;
+    if (used >= MAX_REPLIES_PER_MSG_ID) return undefined;
+    const seq = used + 1;
+    this.seqCounters.set(msgId, seq);
+    if (this.seqCounters.size > 500) this.seqCounters.clear();
+    return seq;
+  }
+
+  private async postWithRetry(openid: string, body: any): Promise<void> {
+    const fetchFn = this.opts.fetchFn ?? fetch;
+    for (let attempt = 0; attempt <= 3; attempt++) {
+      const token = await this.opts.getToken();
+      const res = await fetchFn(`${this.opts.restBase}/v2/users/${openid}/messages`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `QQBot ${token}` },
+        body: JSON.stringify(body),
+      });
+      if (res.status === 429 && attempt < 3) {
+        const retryAfter = Number(res.headers.get("Retry-After") ?? "1");
+        await new Promise((r) => setTimeout(r, Math.min(retryAfter, 30) * 1000));
+        continue;
+      }
+      if (!res.ok) throw new Error(`sendC2C failed: HTTP ${res.status} ${await res.text()}`);
+      return;
+    }
+  }
+
+  private async doSend(openid: string, content: string, options: SendOptions): Promise<void> {
+    const format = options.format ?? "text";
+    let msgId = options.msgId;
+    let seq: number | undefined;
+    if (msgId) {
+      seq = this.nextSeq(msgId);
+      if (seq === undefined) msgId = undefined; // 被动额度用尽 → 主动消息
+    }
+    const makeBody = (fmt: "text" | "markdown") => {
+      const body: any = fmt === "markdown" ? { msg_type: 2, markdown: { content } } : { msg_type: 0, content };
+      if (msgId && seq !== undefined) {
+        body.msg_id = msgId;
+        body.msg_seq = seq;
+      }
+      return body;
+    };
+    try {
+      await this.postWithRetry(openid, makeBody(format));
+    } catch (e) {
+      if (format === "markdown") {
+        await this.postWithRetry(openid, makeBody("text"));
+        return;
+      }
+      throw e;
+    }
+  }
+}

package/qq/auth.ts

@@ -0,0 +1,27 @@
+import { TOKEN_URL } from "../constants";
+
+export class AuthManager {
+  private token: string | null = null;
+  private expireAt = 0;
+
+  constructor(
+    private appId: string,
+    private appSecret: string,
+    private fetchFn: typeof fetch = fetch,
+  ) {}
+
+  async getToken(): Promise<string> {
+    const now = Date.now();
+    if (this.token && now < this.expireAt - 60_000) return this.token;
+    const res = await this.fetchFn(TOKEN_URL, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ appId: this.appId, clientSecret: this.appSecret }),
+    });
+    if (!res.ok) throw new Error(`getAppAccessToken failed: HTTP ${res.status}`);
+    const data = (await res.json()) as any;
+    this.token = data.access_token;
+    this.expireAt = Date.now() + Number(data.expires_in) * 1000;
+    return this.token;
+  }
+}

package/qq/gateway.ts

@@ -0,0 +1,235 @@
+import WebSocket from "ws";
+import { GATEWAY_PATH } from "../constants";
+import { log } from "../logger";
+
+const OP_DISPATCH = 0;
+const OP_HEARTBEAT = 1;
+const OP_IDENTIFY = 2;
+const OP_RESUME = 6;
+const OP_HELLO = 10;
+const OP_HEARTBEAT_ACK = 11;
+
+export interface QQMessage {
+  openid: string;
+  content: string;
+  msgId: string;
+  timestamp: number;
+  attachments: { url: string }[];
+  quotedText?: string;
+}
+
+export interface QQGatewayOptions {
+  getGatewayUrl: () => Promise<string>;
+  getToken: () => Promise<string>;
+  intents: number;
+  connected: () => void;
+  disconnected: () => void;
+  message: (msg: QQMessage) => Promise<void> | void;
+  reconnectBaseMs?: number;
+  maxSeen?: number;
+}
+
+export class QQGateway {
+  private ws: WebSocket | null = null;
+  private sessionId: string | null = null;
+  private lastSeq: number | null = null;
+  private resumeAttempted = false;
+  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
+  private reconnectTimer: ReturnType<typeof setTimeout> | null = null;
+  private reconnectAttempt = 0;
+  private stopped = false;
+  private seenIds = new Set<string>();
+  private seenOrder: string[] = [];
+
+  constructor(private opts: QQGatewayOptions) {}
+
+  private isDuplicate(key: string): boolean {
+    if (!key) return false;
+    if (this.seenIds.has(key)) return true;
+    this.seenIds.add(key);
+    this.seenOrder.push(key);
+    const cap = this.opts.maxSeen ?? 1000;
+    if (this.seenOrder.length > cap) {
+      const oldest = this.seenOrder.shift();
+      if (oldest !== undefined) this.seenIds.delete(oldest);
+    }
+    return false;
+  }
+
+  start() {
+    this.stopped = false;
+    this.connect().catch(() => this.scheduleReconnect());
+  }
+
+  stop() {
+    this.stopped = true;
+    this.cleanup();
+  }
+
+  private cleanup() {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    this.heartbeatTimer = null;
+    if (this.reconnectTimer) clearTimeout(this.reconnectTimer);
+    this.reconnectTimer = null;
+    if (this.ws) {
+      this.ws.removeAllListeners();
+      try {
+        this.ws.close();
+      } catch {
+        /* ignore */
+      }
+    }
+    this.ws = null;
+  }
+
+  private scheduleReconnect() {
+    if (this.stopped) return;
+    if (this.resumeAttempted) {
+      this.resumeAttempted = false;
+      this.sessionId = null;
+      this.lastSeq = null;
+    }
+    const base = this.opts.reconnectBaseMs ?? 1000;
+    const delay = Math.min(base * 2 ** this.reconnectAttempt, 60_000);
+    this.reconnectAttempt++;
+    this.reconnectTimer = setTimeout(() => {
+      if (this.stopped) return;
+      this.connect().catch(() => this.scheduleReconnect());
+    }, delay);
+  }
+
+  private async connect() {
+    log("[gateway] 开始连接...");
+    const url = await this.opts.getGatewayUrl();
+    log("[gateway] 网关地址:", url);
+    const ws = new WebSocket(url);
+    this.ws = ws;
+    ws.on("open", () => log("[gateway] WebSocket 已连接，等待 HELLO..."));
+    ws.on("message", (raw) => {
+      let pkt: any;
+      try {
+        pkt = JSON.parse(raw.toString());
+      } catch (e) {
+        log("[gateway] 丢弃非 JSON 网关帧:", String(e).slice(0, 120));
+        return;
+      }
+      this.handlePacket(pkt);
+    });
+    ws.on("close", (code) => {
+      log("[gateway] WebSocket 关闭 code=", code);
+      this.opts.disconnected();
+      this.scheduleReconnect();
+    });
+    ws.on("error", (e: any) => {
+      log("[gateway] WebSocket 错误:", String(e?.message ?? e));
+      ws.terminate();
+    });
+  }
+
+  private handlePacket(pkt: any) {
+    switch (pkt.op) {
+      case OP_HELLO: {
+        const interval = pkt.d.heartbeat_interval;
+        this.startHeartbeat(interval);
+        if (this.sessionId !== null && this.lastSeq !== null) {
+          this.resumeAttempted = true;
+          void this.sendResume().catch(() => this.ws?.terminate());
+        } else {
+          this.resumeAttempted = false;
+          void this.sendIdentify().catch(() => this.ws?.terminate());
+        }
+        break;
+      }
+      case OP_HEARTBEAT_ACK:
+        break;
+      case OP_DISPATCH: {
+        this.lastSeq = pkt.s ?? this.lastSeq;
+        const d = pkt.d ?? {};
+        if (this.isDuplicate(pkt.id ?? String(d.msg_id ?? d.id ?? ""))) return;
+        this.handleDispatch(pkt.t ?? "", d);
+        break;
+      }
+    }
+  }
+
+  private async sendIdentify() {
+    const token = await this.opts.getToken();
+    log("[gateway] 发送 identify...");
+    this.ws?.send(
+      JSON.stringify({
+        op: OP_IDENTIFY,
+        d: { token: `QQBot ${token}`, intents: this.opts.intents, shard: [0, 1] },
+      }),
+    );
+  }
+
+  private async sendResume() {
+    const token = await this.opts.getToken();
+    this.ws?.send(
+      JSON.stringify({
+        op: OP_RESUME,
+        d: { token: `QQBot ${token}`, session_id: this.sessionId, seq: this.lastSeq },
+      }),
+    );
+  }
+
+  private startHeartbeat(intervalMs: number) {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    this.heartbeatTimer = setInterval(() => {
+      this.ws?.send(JSON.stringify({ op: OP_HEARTBEAT, d: this.lastSeq }));
+    }, intervalMs);
+  }
+
+  private handleDispatch(t: string, d: any) {
+    if (t === "READY") {
+      this.sessionId = String(d.session_id);
+      this.resumeAttempted = false;
+      this.reconnectAttempt = 0;
+      log("[gateway] ✅ READY，bot 已上线 session=", this.sessionId);
+      this.opts.connected();
+      return;
+    }
+    if (t === "RESUMED") {
+      this.resumeAttempted = false;
+      this.reconnectAttempt = 0;
+      log("[gateway] RESUMED 会话恢复");
+      this.opts.connected();
+      return;
+    }
+    if (t === "C2C_MESSAGE_CREATE") {
+      log("[gateway] C2C 原始数据:", JSON.stringify(d).slice(0, 600));
+      const rawAttachments = Array.isArray(d.attachments) ? d.attachments : [];
+      this.opts.message({
+        openid: String(d.author?.user_openid ?? d.author?.id ?? d.openid ?? ""),
+        content: String(d.content ?? ""),
+        msgId: String(d.id ?? d.msg_id ?? ""),
+        timestamp: Date.parse(String(d.timestamp ?? "")) || Date.now(),
+        attachments: rawAttachments
+          .filter((a: any) => !!a && typeof a === "object")
+          .filter(
+            (a: any) =>
+              String(a.content_type ?? a.contentType ?? "") === "image" ||
+              String(a.url ?? "").match(/\.(png|jpe?g|gif|webp)/i),
+          )
+          .map((a: any) => ({ url: String(a.url ?? "") }))
+          .filter((a: any) => a.url),
+        quotedText: undefined,
+      });
+    }
+  }
+}
+
+export function createGatewayUrlFetcher(
+  restBase: string,
+  getToken: () => Promise<string>,
+  fetchFn: typeof fetch = fetch,
+): () => Promise<string> {
+  return async () => {
+    const token = await getToken();
+    const res = await fetchFn(`${restBase}${GATEWAY_PATH}`, {
+      headers: { Authorization: `QQBot ${token}` },
+    });
+    if (!res.ok) throw new Error(`get gateway failed: HTTP ${res.status}`);
+    return (await res.json()).url;
+  };
+}

package/stream-buffer.ts

@@ -0,0 +1,22 @@
+/** 单会话回复文本累积：message_update 的 text_delta 累加，agent_settled 时取走 */
+export class ReplyBuffer {
+  private text = "";
+
+  append(delta: string) {
+    if (typeof delta === "string") this.text += delta;
+  }
+
+  peek(): string {
+    return this.text;
+  }
+
+  take(): string {
+    const t = this.text;
+    this.text = "";
+    return t;
+  }
+
+  reset() {
+    this.text = "";
+  }
+}

package/util/chunk.ts

@@ -0,0 +1,42 @@
+export function splitText(text: string, maxBytes = 1900): string[] {
+  if (Buffer.byteLength(text, "utf8") <= maxBytes) return text ? [text] : [];
+  const parts: string[] = [];
+  let current = "";
+  let currentBytes = 0;
+  for (const seg of text.split(/(?<=\n)/)) {
+    const segBytes = Buffer.byteLength(seg, "utf8");
+    if (segBytes > maxBytes) {
+      if (current) {
+        parts.push(current);
+        current = "";
+        currentBytes = 0;
+      }
+      let buf = "";
+      let bufBytes = 0;
+      for (const ch of seg) {
+        const chBytes = Buffer.byteLength(ch, "utf8");
+        if (bufBytes + chBytes > maxBytes) {
+          parts.push(buf);
+          buf = ch;
+          bufBytes = chBytes;
+        } else {
+          buf += ch;
+          bufBytes += chBytes;
+        }
+      }
+      current = buf;
+      currentBytes = bufBytes;
+      continue;
+    }
+    if (currentBytes + segBytes > maxBytes) {
+      parts.push(current);
+      current = seg;
+      currentBytes = segBytes;
+    } else {
+      current += seg;
+      currentBytes += segBytes;
+    }
+  }
+  if (current) parts.push(current);
+  return parts;
+}