opencode-qq-v2 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 opencode-qq 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,104 @@
-# Temporary Holding Version
+# opencode-qq (V2 适配版)
 
-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.
+把 [OpenCode](https://opencode.ai) 接入 QQ 单聊的桥接插件：在 QQ 里和 AI 对话，驱动 opencode 干活。
+
+> 本仓库基于 [opencode-qq](https://www.npmjs.com/package/opencode-qq) v0.1.0 移植，使其兼容 **OpenCode v2**（`@opencode/plugin` 2.x + EffectTS 运行时）。
+
+## 功能
+
+- **对话驱动 opencode**：QQ 单聊消息直达 opencode 会话，AI 回复发回 QQ；每个 QQ 用户对应一个长期会话，重启后延续。
+- **图片理解**：单聊里发的图片转交给 opencode 多模态处理。
+- **任务完成 / 出错推送**：opencode 会话完成（✅）或出错（❌）时主动推送到 QQ。
+- **QQ 远程审批权限**：opencode 发出权限请求时直接在 QQ 里回复「同意 / 拒绝」。
+- **内置指令**：`/new` 重置会话、`/status` 查看状态、`/help` 帮助。
+
+## V2 适配改动（相对原版 v0.1.0）
+
+1. **插件入口**：`async (input) => Hooks`（V1）→ `Plugin.define({ id, setup(ctx) })`（V2 Promise API）。
+2. **客户端调用**：`input.client.session.*` → `ctx.session.*`（create / prompt / switchModel）、`ctx.permission.reply`、`ctx.model.default`。
+3. **事件模型**：`message.part.updated` → `session.text.delta`；完成事件 `session.idle` → `session.execution.succeeded`；`session.error` → `session.execution.failed`。
+4. **工具钩子**：`tool.execute.after` Hooks 回调 → `ctx.tool.hook("execute.after", cb)`。
+5. **取网关地址补鉴权**：`GET /gateway` 现在要求 `Authorization: QQBot <token>` 头，原版缺失导致一直 401。
+6. **C2C 消息字段修正**：发送者 openid 取 `d.author.user_openid`（原版误用 `d.openid`），消息 ID 取 `d.id`（原版误用 `d.msg_id`）。
+7. **配置路径修正**：Windows 上 `process.env.HOME` 为空，改用 `os.homedir()`。
+8. **双加载幂等保护**：opencode 启动分两阶段加载本地插件，加 `started` 标志避免重复启动 QQ 网关。
+9. **回复格式**：单聊不支持 markdown 消息类型（`msg_type:2`），默认改纯文本；流式 `stream_messages` 会产生不完整文本与 `●` 收尾标记，默认关闭流式。
+10. **单实例锁 + 自动接管**：QQ 网关对同一 bot 只保留一个活跃连接，多实例会互踢。新增 `proper-lockfile` 跨平台文件锁（锁文件 `~/.config/opencode/opencode-qq-<appId>.lock`）：只有抢到锁的实例连接 QQ；其余实例进入待命，每 5 秒重试，宿主退出后自动接管（崩溃则靠 30 秒心跳超时判定僵尸锁后接管）。
+
+## 安装（本地路径）
+
+1. 克隆本仓库到本地，例如 `~/.config/opencode/plugins/opencode-qq`。
+2. 安装依赖：`npm install`（只需 `ws`）。
+3. 在 `~/.config/opencode/opencode.json` 的 `plugin` 数组中加入本目录的**反斜杠绝对路径**：
+
+```json
+{
+  "plugin": [
+    "C:\\Users\\<你>\\ .config\\opencode\\plugins\\opencode-qq"
+  ]
+}
+```
+
+> 注意用反斜杠（Windows 原生分隔符），正斜杠会被 opencode 规范化为另一份，导致重复加载。
+
+4. 重启 opencode。
+
+## 配置
+
+创建 `~/.config/opencode/opencode-qq.json`：
+
+```json
+{
+  "appId": "你的AppID",
+  "appSecret": "你的AppSecret",
+  "sandbox": true,
+  "allowlist": [],
+  "model": "deepseek/deepseek-v4-pro",
+  "markdownReply": false,
+  "streaming": false,
+  "events": { "toolProgress": false }
+}
+```
+
+| 字段 | 默认 | 说明 |
+|------|------|------|
+| `appId` / `appSecret` | 必填 | QQ 开放平台机器人凭据 |
+| `sandbox` | `false` | 未提审上线的 bot 用 `true`（沙箱环境）；已上线用 `false` |
+| `allowlist` | `[]` | openid 白名单，空 = 不限制 |
+| `model` | 无 | 覆盖模型，`providerID/modelID`；不填用 opencode 全局默认模型 |
+| `markdownReply` | `true` | 是否用 Markdown 发送（**单聊请设 `false`，否则「该消息类型不支持查看」**） |
+| `streaming` | `true` | 流式打字机（**有截断/`●` 尾巴问题，建议 `false`**） |
+| `events.toolProgress` | `false` | 是否推送工具执行进度 |
+
+也可用环境变量 `QQ_BOT_APPID` / `QQ_BOT_APPSECRET` 代替文件凭据。
+
+## 多实例行为（单实例锁）
+
+QQ 网关对同一 bot 只保留一个活跃连接，多个 opencode 实例同时连接会互相踢下线。插件用 `proper-lockfile` 文件锁保证同一 bot 只有一个「宿主」实例连接 QQ。
+
+| 场景 | 行为 |
+|---|---|
+| 第 1 个实例启动 | 抢到锁 → 成为宿主 → 连接 QQ |
+| 第 2 个实例启动 | 抢锁失败 → 待命（不连 QQ，不互踢） |
+| 宿主正常退出 | 释放锁 |
+| 宿主崩溃 | 心跳中断，30 秒后锁被判为僵尸锁 |
+| 待命实例 | 每 5 秒重试抢锁，成功后自动接管 |
+
+- **锁文件**：`~/.config/opencode/opencode-qq-<appId>.lock`，按 AppID 隔离，不同 bot 互不影响。
+- **心跳**：宿主每 10 秒刷新一次锁，证明自己还活着。
+- **僵尸锁**：30 秒无心跳视为宿主已死，待命实例可抢占。
+- **接管空窗**：宿主退出后，待命实例最多 5 秒（重试间隔）内接管，QQ bot 短暂下线几秒后自动恢复。
+
+## 前置条件
+
+1. 在 [QQ 开放平台](https://q.qq.com/) 创建机器人，拿到 **AppID** 与 **AppSecret**。
+2. 未上线阶段需在管理端配置**沙箱单聊账号**，并把 `sandbox` 设为 `true`。
+3. 正式环境需在管理端填写服务器公网出口 IP 白名单。
+
+## 日志
+
+调试日志写入 `~/.config/opencode/opencode-qq.log`，包含网关连接、消息收发、会话处理全链路，便于排查。
+
+## License
+
+MIT

package/approver.js

@@ -0,0 +1,52 @@
+export class Approver {
+    timeoutMs;
+    pending = new Map();
+    nextSeq = 1;
+    constructor(timeoutMs) {
+        this.timeoutMs = timeoutMs;
+    }
+    register(sessionId, permissionId, summary) {
+        const seq = this.nextSeq++;
+        const timer = setTimeout(() => this.pending.delete(seq), this.timeoutMs);
+        this.pending.set(seq, { permissionId, sessionId, summary, timer });
+        return seq;
+    }
+    render(seq) {
+        const item = this.pending.get(seq);
+        return [
+            `[权限请求 #${seq}] ${item?.summary ?? ""}`,
+            `回复“同意 ${seq}”批准本次，回复“拒绝 ${seq}”拒绝。`,
+        ].join("\n");
+    }
+    parseReply(text) {
+        const m = /^(同意|拒绝)\s*(\d+)$/.exec(text.trim());
+        if (!m)
+            return null;
+        return { reply: m[1] === "同意" ? "once" : "reject", seq: Number(m[2]) };
+    }
+    confirm(seq) {
+        const item = this.pending.get(seq);
+        if (!item)
+            return undefined;
+        clearTimeout(item.timer);
+        this.pending.delete(seq);
+        const { timer: _t, ...rest } = item;
+        return rest;
+    }
+    clearSession(sessionId) {
+        for (const [seq, item] of this.pending) {
+            if (item.sessionId === sessionId) {
+                clearTimeout(item.timer);
+                this.pending.delete(seq);
+            }
+        }
+    }
+    /** 终审 I4a：某会话当前待审批数量（供 /status 展示） */
+    countBySession(sessionId) {
+        let n = 0;
+        for (const item of this.pending.values())
+            if (item.sessionId === sessionId)
+                n++;
+        return n;
+    }
+}

package/commands.js

@@ -0,0 +1,6 @@
+export function parseCommand(text) {
+    const m = /^\/(new|status|help)\s*$/i.exec(text.trim());
+    if (!m)
+        return null;
+    return { type: m[1].toLowerCase() };
+}

package/config.js

@@ -0,0 +1,25 @@
+import fs from "node:fs";
+import { CONFIG_PATH } from "./constants";
+export function loadConfig(path = CONFIG_PATH()) {
+    let file = {};
+    try {
+        file = JSON.parse(fs.readFileSync(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 ?? [],
+        events: { toolProgress: file.events?.toolProgress ?? false },
+        model: file.model,
+        markdownReply: file.markdownReply ?? true,
+        streaming: file.streaming ?? true,
+    };
+}

package/constants.js

@@ -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; // 每条收到的消息最多被动回复次数（ack+结果 占 2 次）
+export const APPROVAL_TIMEOUT_MS = 10 * 60 * 1000;
+export const STREAM_FLUSH_INTERVAL_MS = 1200; // 流式打字机推送节流间隔
+const CONFIG_DIR = process.env.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config");
+export const CONFIG_PATH = () => path.join(CONFIG_DIR, "opencode", "opencode-qq.json");
+export const SESSIONS_PATH = () => path.join(CONFIG_DIR, "opencode", "opencode-qq-sessions.json");
+export const LOCK_PATH = (appId) => path.join(CONFIG_DIR, "opencode", `opencode-qq-${appId}.lock`);
+export const GATEWAY_PATH = "/gateway";

package/event-pusher.js

@@ -0,0 +1,81 @@
+import { Throttler } from "./util/throttle";
+const TOOL_PROGRESS_INTERVAL_MS = 60_000;
+const ERROR_SUMMARY_MAX = 300;
+/**
+ * 终审 I2：props.error 是结构化对象（如 {name:"UnknownError", data:{message}}），
+ * 直接 String() 会得到 "[object Object]"。按 data.message → name → String 链提取。
+ */
+function summarizeError(error) {
+    if (error && typeof error === "object") {
+        const e = error;
+        const message = e.data && typeof e.data === "object" ? e.data.message : undefined;
+        if (typeof message === "string" && message)
+            return message.slice(0, ERROR_SUMMARY_MAX);
+        if (typeof e.name === "string" && e.name)
+            return e.name.slice(0, ERROR_SUMMARY_MAX);
+    }
+    return String(error ?? "未知错误").slice(0, ERROR_SUMMARY_MAX);
+}
+export class EventPusher {
+    deps;
+    throttler;
+    /** 断线补发队列 */
+    offlineQueue = [];
+    online = true;
+    constructor(deps) {
+        this.deps = deps;
+        this.throttler = new Throttler(deps.toolProgressIntervalMs ?? TOOL_PROGRESS_INTERVAL_MS, (key, lines) => {
+            const openid = key;
+            void this.deps
+                .send(openid, `🛠 工具进度:\n${lines.map((l) => `- ${l}`).join("\n")}`)
+                .catch(() => { });
+        });
+        deps.subscribe((evt) => this.handle(evt));
+    }
+    setOnline(online) {
+        this.online = online;
+        if (online) {
+            for (const item of this.offlineQueue.splice(0)) {
+                this.deps.send(item.openid, item.text).catch(() => { });
+            }
+        }
+    }
+    deliver(openid, text) {
+        if (!this.online) {
+            this.offlineQueue.push({ openid, text });
+            return;
+        }
+        this.deps.send(openid, text).catch(() => { });
+    }
+    handle(evt) {
+        const props = evt.properties ?? {};
+        const sessionId = String(props.sessionID ?? props.sessionId ?? "");
+        if (!sessionId || !this.deps.isOurSession(sessionId))
+            return;
+        const openid = this.deps.openidOfSession(sessionId);
+        if (!openid)
+            return;
+        switch (evt.type) {
+            case "session.idle": {
+                const tail = this.deps.lastAssistantText?.(sessionId);
+                this.deliver(openid, tail ? `✅ 任务完成。\n摘要: ${tail.slice(-200)}` : "✅ 任务完成。");
+                break;
+            }
+            case "session.error": {
+                const err = summarizeError(props.error);
+                this.deliver(openid, `❌ 出错: ${err}`);
+                break;
+            }
+            case "tool.execute.after":
+                if (this.deps.toolProgress) {
+                    const tool = String(props.tool ?? "tool");
+                    const title = String(props.title ?? props.description ?? "").slice(0, 80);
+                    this.throttler.push(openid, `${tool}: ${title}`);
+                }
+                break;
+        }
+    }
+    dispose() {
+        this.throttler.dispose();
+    }
+}