@zxh126/pi-qqbot 0.0.0-stage → 0.1.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,89 @@
-# 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.
+把 [Pi](https://pi.dev) coding agent 接入 QQ 单聊的桥接插件：在 QQ 里和 AI 对话，驱动 pi 干活。
+
+> 单会话版：所有 QQ 用户共用同一个 pi 会话（v1 设计，多用户多会话后续用 SDK 方案实现）。
+
+## 功能
+
+- **对话驱动 pi**：QQ 单聊消息送入当前 pi 会话，AI 回复发回 QQ。
+- **QQ 远程审批**：pi 执行 `bash` / `powershell` 等命令类工具时，先在 QQ 里发「同意 N / 拒绝 N」请求，用户回复后放行/拦截。
+- **单实例锁**：多个 pi 实例只会有「宿主」连接 QQ，其余待命，宿主退出后自动接管。
+- **内置指令**：`/new` 重置、`/status` 状态、`/help` 帮助。
+
+## 安装
+
+1. 把本目录放到 `~/.pi/agent/extensions/pi-qqbot/`（或作为 Pi Package：`pi install ./pi-qqbot`）。
+2. 安装依赖：`npm install`。
+3. 创建配置 `~/.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"]` | 需要 QQ 审批的工具名；另有 `destructiveHint` 注解的工具也会拦截 |
+| `approve.remember` | `true` | 会话内记住选择：同意/拒绝后同类工具不再询问 |
+
+也可用环境变量 `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 代替文件凭据。
+
+## 使用
+
+启动 pi 后，在 QQ 里给机器人发消息，pi 会处理并回复。内置指令：
+
+- `/new` — 重置会话（清空当前回复缓冲）
+- `/status` — 查看是否空闲
+- `/help` — 帮助
+
+## 单实例锁
+
+QQ 网关对同一 bot 只保留一个活跃连接。插件用 `proper-lockfile` 文件锁（`~/.pi/agent/pi-qqbot-<appId>.lock`）：
+
+- 抢到锁的实例 = 宿主，连接 QQ；
+- 其余实例待命，每 5 秒重试；
+- 宿主退出或崩溃（30 秒心跳超时）后，待命实例自动接管。
+
+## 远程审批
+
+pi 执行 `bash` / `powershell` / `write` / `edit` 等工具时（或带 `destructiveHint` 注解的工具），会先在 QQ 里发审批请求：
+
+```
+[审批 #1] bash: rm -rf node_modules
+回复「同意 1」批准，「拒绝 1」拒绝，「停止」终止本轮。
+```
+
+- 回复「同意 N」/「拒绝 N」：放行/拦截对应工具调用；
+- 回复「停止」：终止所有待审批请求；
+- `approve.remember: true` 时，本次会话内同类工具记住选择，不再重复询问（`/new` 重置记忆）；
+- 超时（10 分钟）自动拒绝并通知。
+
+## 前置条件
+
+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,87 @@
+/**
+ * QQ 远程审批：
+ * - 每个待审批请求生成编号，发到 QQ，等用户回复「同意/拒绝 N」或「停止」。
+ * - register 返回一个 Promise，QQ 回复后 resolve 决策。
+ * - remember 记忆：会话内同意/拒绝某工具后，同类工具不再询问。
+ */
+export type ApproveDecision = "allow" | "block" | "terminate";
+
+interface PendingApproval {
+  summary: string;
+  timer: ReturnType<typeof setTimeout>;
+  resolve: (decision: ApproveDecision) => void;
+}
+
+export class Approver {
+  private pending = new Map<number, PendingApproval>();
+  private rememberMap = new Map<string, ApproveDecision>();
+  private nextSeq = 1;
+
+  constructor(private timeoutMs: number) {}
+
+  /** 会话内是否已记住某工具的决策 */
+  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("block");
+        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");
+  }
+
+  parseReply(text: string): { decision: ApproveDecision; seq?: number } | null {
+    const t = text.trim();
+    if (/^停止$/.test(t)) return { decision: "terminate" };
+    const m = /^(同意|拒绝)\s*(\d+)$/.exec(t);
+    if (!m) return null;
+    return { decision: m[1] === "同意" ? "allow" : "block", seq: Number(m[2]) };
+  }
+
+  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;
+  }
+
+  /** 终止所有待审批请求（「停止」） */
+  terminateAll(): number {
+    let count = 0;
+    for (const [seq, item] of [...this.pending]) {
+      clearTimeout(item.timer);
+      this.pending.delete(seq);
+      item.resolve("terminate");
+      count++;
+    }
+    return count;
+  }
+
+  remember(toolName: string, decision: ApproveDecision) {
+    this.rememberMap.set(toolName, decision);
+  }
+
+  reset() {
+    this.rememberMap.clear();
+  }
+}

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,295 @@
+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; // 放行
+
+    // 会话内已记住的决策
+    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 用户停止" };
+    }
+    // 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;
+    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();
+        await replyTo(api, state, msg.openid, `已终止 ${n} 个待审批请求`);
+        return;
+      }
+      const ok = state.approver.confirm(parsed.seq!, parsed.decision);
+      await replyTo(
+        api,
+        state,
+        msg.openid,
+        ok ? (parsed.decision === "allow" ? `已批准 #${parsed.seq}` : `已拒绝 #${parsed.seq}`) : `#${parsed.seq} 不存在或已超时`,
+      );
+      return;
+    }
+
+    // 内置指令
+    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 ? "处理中" : "空闲"}`);
+      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,19 @@
 {
   "name": "@zxh126/pi-qqbot",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "把 Pi coding agent 接入 QQ 单聊的桥接插件（单会话版）",
+  "license": "MIT",
+  "keywords": ["pi-package", "qq", "bot"],
+  "pi": {
+    "extensions": ["./index.ts"]
+  },
+  "files": ["*.ts", "qq", "util", "README.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;
+}