@zxh126/pi-qqbot 1.0.0 → 1.1.0

package/README.md

@@ -90,15 +90,23 @@ Any message that starts with `/` is routed before it can become a chat prompt:
 | `/name [name]` | get or set the session name | `commands.allowSession` |
 | `/model [provider/model]` | list available models or switch | `commands.allowSession` |
 | `/thinking [level]` | get or set the thinking level | `commands.allowSession` |
+| `/tree` | list branch points (numbered), answer with a number to jump there | `commands.allowSession` |
+| `/fork` | list earlier user messages (numbered), answer with a number to fork from it | `commands.allowSession` |
+| `/clone` | duplicate the current session at its current leaf | `commands.allowSession` |
+| `/resume` | list the project's other sessions (numbered), answer with a number to switch | `commands.allowSession` |
 | `/quit` | shuts the host pi down | `commands.allowQuit` (default **false**) |
 
 Host-only (answered, never forwarded to the model): `/settings`, `/hotkeys`, `/changelog`,
-`/trust`, `/login`, `/logout`, `/scoped-models`, `/llama`, `/tree`, `/fork`, `/clone`, `/resume`,
-`/import`, `/export`, `/share`, `/bug`, `/copy`, `/privacy`, `/handoff`.
+`/trust`, `/login`, `/logout`, `/scoped-models`, `/llama`, `/import`, `/export`, `/share`, `/bug`,
+`/copy`, `/privacy`.
 
 Guards:
 
-- `/reload`, `/new`, `/compact` and `/quit` refuse to run while a task is in progress — send `/cancel` first.
+- `/reload`, `/new`, `/compact`, `/quit`, `/tree`, `/fork`, `/clone` and `/resume` refuse to run while a task
+  is in progress — send `/cancel` first.
+- Selection commands (`/tree`, `/fork`, `/resume`) answer with a numbered list of at most 10 entries, scoped to
+  the user who asked and valid for 10 minutes. The next bare number from that user executes the choice; anything
+  else (or 「取消」) abandons it. A number without a pending list is ordinary chat.
 - `/reload` is off by default: it restarts the bot, and if the new code fails to load the bot stays
   down until someone fixes it on the host. Turn it on with `commands.allowReload: true`.
 - Why the indirection: pi only dispatches **extension** commands from a message

package/docs/README.zh-CN.md

@@ -90,15 +90,21 @@ pi install ./pi-qqbot
 | `/name [名字]` | 查看或设置会话名 | `commands.allowSession` |
 | `/model [provider/model]` | 列出可用模型或切换 | `commands.allowSession` |
 | `/thinking [等级]` | 查看或设置思考等级 | `commands.allowSession` |
+| `/tree` | 列出会话树上的分支点（编号），回编号即跳转 | `commands.allowSession` |
+| `/fork` | 列出之前的用户消息（编号），回编号即从该处分叉 | `commands.allowSession` |
+| `/clone` | 在当前叶子位置复制整个会话 | `commands.allowSession` |
+| `/resume` | 列出本项目其他会话（编号），回编号即切换 | `commands.allowSession` |
 | `/quit` | 关掉主机上的 pi | `commands.allowQuit`（默认 **false**） |
 
 只能在主机执行（回执，不转发给模型）：`/settings`、`/hotkeys`、`/changelog`、`/trust`、`/login`、
-`/logout`、`/scoped-models`、`/llama`、`/tree`、`/fork`、`/clone`、`/resume`、`/import`、`/export`、
-`/share`、`/bug`、`/copy`、`/privacy`、`/handoff`。
+`/logout`、`/scoped-models`、`/llama`、`/import`、`/export`、`/share`、`/bug`、`/copy`、`/privacy`。
 
 约束：
 
-- 有任务在跑时，`/reload`、`/new`、`/compact`、`/quit` 会拒绝执行 —— 先发 `/cancel`。
+- 有任务在跑时，`/reload`、`/new`、`/compact`、`/quit`、`/tree`、`/fork`、`/clone`、`/resume` 会拒绝执行
+  —— 先发 `/cancel`。
+- 选择型命令（`/tree`、`/fork`、`/resume`）会回一个最多 10 项的编号列表，只对该用户有效、10 分钟内有效；
+  该用户下一条「纯数字」消息即执行选择，其它内容（或「取消」）则放弃。没有待选列表时，数字就是普通对话。
 - `/reload` 默认关闭：它会重启 bot，如果新代码加载失败，bot 会一直哑着，只能在主机上救。
   置 `commands.allowReload: true` 才启用。
 - 为什么要绕一层：pi 只对**扩展命令**执行派发（`prompt()` → `_tryExecuteExtensionCommand`），而

package/index.ts

@@ -14,7 +14,7 @@ import { AuthManager } from "./qq/auth";
 import { QQApi } from "./qq/api";
 import { createGatewayUrlFetcher, QQGateway, QQMessage } from "./qq/gateway";
 import { Approver } from "./approver";
-import { routeSlash, runBridge } from "./slash";
+import { parsePickIndex, pickerExpired, routeSlash, runBridge, type PickerState } from "./slash";
 import { ReplyBuffer } from "./stream-buffer";
 import { splitText } from "./util/chunk";
 
@@ -33,6 +33,10 @@ interface State {
   ctx: ExtensionContext | null;
   /** 最近一条 QQ 消息的发送者：桥接命令用它回执 */
   lastOpenid: string | null;
+  /** 待选择列表（/tree、/fork、/resume 发出后的编号等待状态） */
+  picker: PickerState | null;
+  /** 发出列表的 QQ 用户：只有他能回编号 */
+  pickerOwner: string | null;
   /** /qq 桥接命令的回执通道（每次收到 QQ 消息时刷新） */
   bridgeReply: ((text: string) => void) | null;
   /** 本轮已被用户取消：settle 时丢弃半截回复 */
@@ -53,6 +57,8 @@ export default function (pi: ExtensionAPI) {
     busy: false,
     ctx: null,
     lastOpenid: null,
+    picker: null,
+    pickerOwner: null,
     bridgeReply: null,
     cancelled: false,
   };
@@ -225,7 +231,7 @@ export default function (pi: ExtensionAPI) {
       const rest = (space === -1 ? "" : trimmed.slice(space + 1)).trim();
       const reply = (text: string) => state.bridgeReply?.(text);
       try {
-        await runBridge(sub, rest, ctx, pi, reply);
+        await runBridge(sub, rest, ctx, pi, reply, state);
       } catch (e) {
         log("[/qq] 桥接失败:", String(e));
         reply(`/${sub} 执行失败：${String(e).slice(0, 200)}`);
@@ -304,6 +310,37 @@ export async function handleMessage(
     }
     state.passiveRefs.set(msg.openid, { msgId: msg.msgId, receivedAt: Date.now() });
 
+    // 待选择的编号回复（/tree、/fork、/resume 之后）
+    if (state.picker) {
+      if (pickerExpired(state.picker)) {
+        state.picker = null;
+      } else if (state.picker.openid === msg.openid) {
+        const index = parsePickIndex(msg.content);
+        if (index !== null) {
+          if (state.busy) {
+            await replyTo(api, state, msg.openid, "当前有任务在跑，先发 /cancel 取消，再回编号。");
+            return;
+          }
+          if (index > state.picker.items.length) {
+            await replyTo(api, state, msg.openid, `编号 ${index} 超出范围（1-${state.picker.items.length}）。`);
+            return;
+          }
+          state.pickerOwner = msg.openid;
+          state.bridgeReply = (text: string) => {
+            void replyTo(api, state, msg.openid, text);
+          };
+          log("[cmd] 选择编号", index, "kind=", state.picker.kind);
+          pi.sendUserMessage(`/qq pick ${index}`, { expandPromptTemplates: true });
+          return;
+        }
+        if (/^(取消|算了|cancel)$/i.test(msg.content.trim())) {
+          state.picker = null;
+          await replyTo(api, state, msg.openid, "已放弃选择。");
+          return;
+        }
+      }
+    }
+
     // 取消指令优先于审批解析：「取消」不该被当成审批动作
     if (isCancelIntent(msg.content)) {
       await handleCancel(state, api, msg.openid);
@@ -312,6 +349,7 @@ export async function handleMessage(
 
     // 斜杠命令路由：pi 扩展命令 → 可接管的内置命令 → 仅主机可用的内置命令 → 普通文字
     state.lastOpenid = msg.openid;
+    state.pickerOwner = msg.openid;
     state.bridgeReply = (text: string) => {
       void replyTo(api, state, msg.openid, text);
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zxh126/pi-qqbot",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "type": "module",
   "description": "Bridge the Pi coding agent into QQ private chats, with remote tool-call approval",
   "license": "MIT",

package/slash.ts

@@ -11,14 +11,21 @@
  *   2. **pi built-in commands we can take over** (`TAKEOVER`) — pi never dispatches
  *      built-ins from a message (only the TUI/RPC layer does), so these are
  *      re-implemented through the extension API. The command-only APIs
- *      (`reload`, `newSession`) need a fresh `ExtensionCommandContext`, so they run
- *      inside the `/qq` bridge command registered by this extension.
+ *      (`reload`, `newSession`, `fork`, `navigateTree`, `switchSession`) need a fresh
+ *      `ExtensionCommandContext`, so they run inside the `/qq` bridge command
+ *      registered by this extension.
  *   3. **built-ins we cannot reach** (`HOST_ONLY`) — reply "run it on the host".
  *   4. **anything else** — treated as ordinary chat text (the caller forwards it).
  *
+ * Selection-style commands (`/tree`, `/fork`, `/resume`) answer with a numbered list
+ * and accept the number as the next message; the pending list lives in `BridgeStore`.
+ *
  * Everything is opted in conservatively through `commands` in the config file.
  */
 
+import fs from "node:fs";
+import path from "node:path";
+
 export interface SlashCommandText {
 	/** command name without the leading slash, lower-cased (`skill:name` keeps its colon) */
 	name: string;
@@ -36,12 +43,12 @@ export function parseSlash(text: string): SlashCommandText | null {
 	return { name: match[1]!.toLowerCase(), args: (match[2] ?? "").trim(), raw: text.trim() };
 }
 
-export type BridgeSub = "reload" | "new" | "compact" | "quit" | "session" | "name" | "model" | "thinking";
+export type BridgeSub = "reload" | "new" | "compact" | "quit" | "session" | "name" | "model" | "thinking" | "tree" | "fork" | "clone" | "resume";
 
 interface Takeover {
-	sub: BridgeSub;
+	sub: string;
 	/** the command tears down the current runtime/session: reply before dispatching */
-selfDestroying?: boolean;
+	selfDestroying?: boolean;
 	/** unsafe to run while a task is in progress */
 	needsIdle?: boolean;
 	needsArgs?: boolean;
@@ -62,6 +69,10 @@ export const TAKEOVER: Readonly<Record<string, Takeover>> = {
 	name: { sub: "name", hint: "设置或查看会话名称" },
 	model: { sub: "model", hint: "查看/切换模型（provider/model）" },
 	thinking: { sub: "thinking", hint: "查看/切换思考等级" },
+	tree: { sub: "list tree", needsIdle: true, hint: "在会话树上跳转（回编号选择）" },
+	fork: { sub: "list fork", needsIdle: true, hint: "从某条历史用户消息分叉（回编号选择）" },
+	resume: { sub: "list resume", needsIdle: true, hint: "切换到本项目的另一个会话（回编号选择）" },
+	clone: { sub: "clone", selfDestroying: true, needsIdle: true, hint: "在当前叶子位置复制会话" },
 };
 
 /** pi built-ins that the extension API cannot reach at all. */
@@ -74,17 +85,12 @@ export const HOST_ONLY: ReadonlySet<string> = new Set([
 	"logout",
 	"scoped-models",
 	"llama",
-	"tree",
-	"fork",
-	"clone",
-	"resume",
 	"import",
 	"export",
 	"share",
 	"bug",
 	"copy",
 	"privacy",
-	"handoff",
 ]);
 
 export interface CommandConfig {
@@ -94,7 +100,7 @@ export interface CommandConfig {
 	allowReload: boolean;
 	/** allow /quit (stops the host pi process) */
 	allowQuit: boolean;
-	/** allow session-level commands: /new, /compact, /session, /name, /model, /thinking */
+	/** allow session-level commands: /new, /compact, /session, /name, /model, /thinking, /tree, /fork, /clone, /resume */
 	allowSession: boolean;
 }
 
@@ -146,16 +152,15 @@ export async function routeSlash(deps: RouteDeps, text: string): Promise<RouteRe
 	const takeover = TAKEOVER[name];
 	if (takeover) {
 		if (!allowed(deps.cfg, name)) {
-			await deps.reply(
-				`/${name} 在 QQ 侧被禁用（配置 commands.allow${name === "reload" ? "Reload" : name === "quit" ? "Quit" : "Session"}）。`,
-			);
+			const gate = name === "reload" ? "allowReload" : name === "quit" ? "allowQuit" : "allowSession";
+			await deps.reply(`/${name} 在 QQ 侧被禁用（配置 commands.${gate}）。`);
 			return "handled";
 		}
 		if (takeover.needsIdle && deps.busy) {
 			await deps.reply(`当前有任务在跑，先发 /cancel 取消，再执行 /${name}。`);
 			return "handled";
 		}
-		const bridge = takeover.needsArgs && !parsed.args ? `/qq ${takeover.sub}` : `/qq ${takeover.sub}${parsed.args ? ` ${parsed.args}` : ""}`;
+		const bridge = `/qq ${takeover.sub}${parsed.args ? ` ${parsed.args}` : ""}`;
 		deps.log("[cmd] 接管内置命令:", parsed.raw.slice(0, 80), "->", bridge.slice(0, 80));
 		if (takeover.selfDestroying) {
 			// the command tears the runtime down; answer before it lands
@@ -186,9 +191,151 @@ function formatTokens(value: number | null | undefined): string {
 	return String(value);
 }
 
+// ---------------------------------------------------------------------------
+// pickers (tree / fork / resume)
+// ---------------------------------------------------------------------------
+
+export type PickerKind = "tree" | "fork" | "resume";
+
+export interface PickerItem {
+	/** entry id (tree/fork) */
+	id?: string;
+	/** session file (resume) */
+	path?: string;
+	/** what the user sees next to the number */
+	label: string;
+}
+
+export interface PickerState {
+	kind: PickerKind;
+	items: PickerItem[];
+	/** only this QQ user may answer with a number */
+	openid: string | null;
+	createdAt: number;
+}
+
+/** Shared mutable state between the router (index.ts) and the bridge command. */
+export interface BridgeStore {
+	picker: PickerState | null;
+	/** set by the router right before dispatching a `list` command */
+	pickerOwner: string | null;
+}
+
+export const PICKER_TTL_MS = 10 * 60_000;
+export const PICKER_MAX_ITEMS = 10;
+
+const KIND_LABEL: Record<PickerKind, string> = {
+	tree: "会话树节点",
+	fork: "可分叉的用户消息",
+	resume: "本项目的其他会话",
+};
+
+function previewText(content: unknown): string {
+	const parts = Array.isArray(content) ? content : [];
+	const text = parts
+		.map((part: any) => (part?.type === "text" && typeof part.text === "string" ? part.text : ""))
+		.join(" ")
+		.replace(/\s+/g, " ")
+		.trim();
+	return text.length > 50 ? `${text.slice(0, 50)}…` : text || "(无文本)";
+}
+
+const stamp = (value: unknown): string => {
+	const date = typeof value === "string" || typeof value === "number" ? new Date(value) : new Date();
+	if (Number.isNaN(date.getTime())) return "?";
+	const pad = (n: number) => String(n).padStart(2, "0");
+	return `${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}`;
+};
+
+function branchItems(ctx: any): PickerItem[] {
+	let branch: any[] = [];
+	try {
+		branch = ctx.sessionManager.getBranch() ?? [];
+	} catch {
+		branch = [];
+	}
+	return branch
+		.filter((entry) => entry?.type === "message" && entry?.message?.role === "user")
+		.slice(-PICKER_MAX_ITEMS)
+		.map((entry) => ({
+			id: entry.id,
+			label: `${stamp(entry.timestamp)}  ${previewText(entry.message.content)}`,
+		}));
+}
+
+function resumeItems(ctx: any): PickerItem[] {
+	let dir: string | undefined;
+	let current: string | undefined;
+	try {
+		dir = ctx.sessionManager.getSessionDir?.();
+		current = ctx.sessionManager.getSessionFile?.();
+	} catch {
+		return [];
+	}
+	if (!dir) return [];
+	let names: string[] = [];
+	try {
+		names = fs.readdirSync(dir).filter((name) => name.endsWith(".jsonl"));
+	} catch {
+		return [];
+	}
+	return names
+		.map((name) => {
+			const full = path.join(dir!, name);
+			let mtime = 0;
+			let size = 0;
+			try {
+				const stat = fs.statSync(full);
+				mtime = stat.mtimeMs;
+				size = stat.size;
+			} catch {
+				// unreadable: keep it out of the ranking
+			}
+			return { full, name, mtime, size };
+		})
+		.filter((row) => row.mtime > 0 && row.full !== current)
+		.sort((a, b) => b.mtime - a.mtime)
+		.slice(0, PICKER_MAX_ITEMS)
+		.map((row) => ({
+			path: row.full,
+			label: `${stamp(row.mtime)}  ${Math.max(1, Math.round(row.size / 1024))}KB  ${row.name.replace(/\.jsonl$/, "").slice(0, 44)}`,
+		}));
+}
+
+function buildPickerItems(kind: PickerKind, ctx: any): PickerItem[] {
+	if (kind === "resume") return resumeItems(ctx);
+	return branchItems(ctx);
+}
+
+function formatPicker(picker: PickerState): string {
+	const header = `选择${KIND_LABEL[picker.kind]}（${picker.items.length} 项）：`;
+	const rows = picker.items.map((item, index) => `  ${index + 1}. ${item.label}`);
+	return [
+		header,
+		...rows,
+		`回复编号执行，或回复「取消」放弃（${Math.round(PICKER_TTL_MS / 60000)} 分钟内有效）。`,
+	].join("\n");
+}
+
+/** Parse a bare "3" reply that answers the pending picker. */
+export function parsePickIndex(text: string): number | null {
+	const match = /^\s*(\d{1,3})\s*$/.exec(text);
+	if (!match) return null;
+	const value = Number(match[1]);
+	return Number.isFinite(value) && value > 0 ? value : null;
+}
+
+export function pickerExpired(picker: PickerState | null): boolean {
+	return !picker || Date.now() - picker.createdAt > PICKER_TTL_MS;
+}
+
 /**
  * Body of the `/qq` bridge command: pi hands it a fresh `ExtensionCommandContext`,
- * which is the only place `reload()` / `newSession()` are legal.
+ * which is the only place `reload()`, `newSession()`, `fork()`, `navigateTree()` and
+ * `switchSession()` are legal.
+ *
+ * Session-replacing actions (`reload`, `new`, `tree`/`fork`/`resume` picks, `clone`)
+ * tear this runtime down; the caller answers the QQ user before dispatching them.
  */
 export async function runBridge(
 	sub: string,
@@ -196,8 +343,11 @@ export async function runBridge(
 	ctx: any,
 	pi: any,
 	reply: (text: string) => void,
+	store?: BridgeStore,
 ): Promise<void> {
 	const level = String(sub ?? "").toLowerCase();
+	const first = arg.split(/\s+/)[0]?.toLowerCase() ?? "";
+
 	switch (level) {
 		case "reload": {
 			await ctx.reload();
@@ -221,6 +371,64 @@ export async function runBridge(
 			});
 			return;
 		}
+		case "list": {
+			const kind = first as PickerKind;
+			if (kind !== "tree" && kind !== "fork" && kind !== "resume") {
+				reply(`未知列表类型：${first || "(空)"}`);
+				return;
+			}
+			const items = buildPickerItems(kind, ctx);
+			if (items.length === 0) {
+				reply(`没有可用的${KIND_LABEL[kind]}。`);
+				return;
+			}
+			const picker: PickerState = { kind, items, openid: store?.pickerOwner ?? null, createdAt: Date.now() };
+			if (store) store.picker = picker;
+			reply(formatPicker(picker));
+			return;
+		}
+		case "pick": {
+			const index = Number.parseInt(first, 10);
+			const picker = store?.picker ?? null;
+			if (!picker || !Number.isFinite(index)) {
+				reply("选择列表已失效，请重新发送命令。");
+				return;
+			}
+			const item = picker.items[index - 1];
+			if (!item) {
+				reply(`编号 ${first} 超出范围（1-${picker.items.length}）。`);
+				return;
+			}
+			if (store) store.picker = null;
+			if (picker.kind === "tree") {
+				reply(`正在跳转到第 ${index} 个节点…`);
+				await ctx.navigateTree(item.id);
+				return;
+			}
+			if (picker.kind === "fork") {
+				reply(`正在从第 ${index} 条消息分叉…`);
+				await ctx.fork(item.id);
+				return;
+			}
+			reply(`正在切换会话：${item.label.slice(0, 44)}…`);
+			await ctx.switchSession(item.path);
+			return;
+		}
+		case "clone": {
+			let leaf: string | null = null;
+			try {
+				leaf = ctx.sessionManager.getLeafId?.() ?? null;
+			} catch {
+				leaf = null;
+			}
+			if (!leaf) {
+				reply("当前会话还没有可复制的位置（先发一条消息）。");
+				return;
+			}
+			reply("正在当前叶子位置复制会话…");
+			await ctx.fork(leaf, { position: "at" });
+			return;
+		}
 		case "session": {
 			const sm = ctx.sessionManager;
 			const usage = ctx.getContextUsage?.();
@@ -232,14 +440,19 @@ export async function runBridge(
 					return "?";
 				}
 			})();
-			const lines = [
-				`会话：${sm.getSessionName?.() || "(未命名)"}`,
-				`id：${sm.getSessionId?.() ?? "?"}`,
-				`cwd：${sm.getCwd?.() ?? ctx.cwd ?? "?"}`,
-				`模型：${model ? `${model.provider}/${model.id}` : "(未设置)"}  思考：${ctx.thinkingLevel ?? "?"}`,
-				`条目：${entries}   上下文：${usage && usage.tokens !== undefined ? `${formatTokens(usage.tokens)}${usage.percent !== undefined ? ` (${Math.round(usage.percent)}%)` : ""}` : "未知"}`,
-			];
-			reply(lines.join("\n"));
+			reply(
+				[
+					`会话：${sm.getSessionName?.() || "(未命名)"}`,
+					`id：${sm.getSessionId?.() ?? "?"}`,
+					`cwd：${sm.getCwd?.() ?? ctx.cwd ?? "?"}`,
+					`模型：${model ? `${model.provider}/${model.id}` : "(未设置)"}  思考：${ctx.thinkingLevel ?? "?"}`,
+					`条目：${entries}   上下文：${
+						usage && usage.tokens !== undefined
+							? `${formatTokens(usage.tokens)}${usage.percent !== undefined ? ` (${Math.round(usage.percent)}%)` : ""}`
+							: "未知"
+					}`,
+				].join("\n"),
+			);
 			return;
 		}
 		case "name": {
@@ -260,7 +473,9 @@ export async function runBridge(
 				reply(
 					[
 						`当前模型：${current ? `${current.provider}/${current.id}` : "(未设置)"}`,
-						available.length > 0 ? `可选（${available.length}）：${names.join(", ")}${available.length > MAX_LIST ? " …" : ""}` : "没有可用模型",
+						available.length > 0
+							? `可选（${available.length}）：${names.join(", ")}${available.length > MAX_LIST ? " …" : ""}`
+							: "没有可用模型",
 					].join("\n"),
 				);
 				return;