@zxh126/pi-qqbot 1.0.0 → 1.2.0

package/queue.ts

@@ -0,0 +1,118 @@
+/**
+ * QQ 侧任务队列。
+ *
+ * pi 的单会话是串行执行的：一轮 agent run 结束（agent_settled）后才可能开始下一轮。
+ * 于是忙碌期间收到的消息不再丢弃/拒绝，而是排队；当前任务结束后由 index.ts 的
+ * `drainQueue()` 逐条取出执行。
+ *
+ * 设计要点：
+ * - 全局单队列（本扩展是单会话设计），每条任务记住自己的 openid，回复发给原主人。
+ * - FIFO，编号单调递增不复用，方便用户用 `/queue drop <编号>` 定点删除。
+ * - `/cancel` 不走队列（立即生效），并且会清空队列。
+ */
+
+export interface QueuedJob {
+	/** 队列编号，从 1 开始单调递增 */
+	id: number;
+	/** 任务来自哪个 QQ 用户 */
+	openid: string;
+	/** 交给 pi 的原始文本（普通对话 / 斜杠命令 / 提示模板 / skill 命令） */
+	text: string;
+	/** 入队时间戳（毫秒） */
+	enqueuedAt: number;
+	/** 派发失败的重试次数，由 index.ts 维护 */
+	attempts: number;
+}
+
+export type PushResult =
+	| { ok: true; job: QueuedJob; ahead: number }
+	| { ok: false; reason: "full" };
+
+export const DEFAULT_QUEUE_MAX = 20;
+
+/** 单条预览的最大字符数 */
+const PREVIEW_MAX = 48;
+
+export function previewText(text: string, max = PREVIEW_MAX): string {
+	const flat = text.replace(/\s+/g, " ").trim();
+	return flat.length > max ? `${flat.slice(0, max)}…` : flat || "(空消息)";
+}
+
+/** 距离入队多久：`12s 前` / `3m 前` / `1h 前` */
+export function agoLabel(at: number, now = Date.now()): string {
+	const seconds = Math.max(0, Math.round((now - at) / 1000));
+	if (seconds < 60) return `${seconds}s 前`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m 前`;
+	return `${Math.floor(minutes / 60)}h 前`;
+}
+
+export class MessageQueue {
+	private jobs: QueuedJob[] = [];
+	private nextId = 1;
+	private limit: number;
+
+	/** `limit = 0` 表示关闭排队（忙碌时直接拒绝新消息） */
+	constructor(limit = DEFAULT_QUEUE_MAX) {
+		this.limit = Math.max(0, Math.floor(limit) || 0);
+	}
+
+	/** 按配置调整上限；已有的任务不会被丢弃 */
+	setLimit(limit: number) {
+		this.limit = Math.max(0, Math.floor(limit) || 0);
+	}
+
+	get size(): number {
+		return this.jobs.length;
+	}
+
+	get max(): number {
+		return this.limit;
+	}
+
+	/** 只读快照（保持插入顺序） */
+	list(): readonly QueuedJob[] {
+		return this.jobs;
+	}
+
+	push(openid: string, text: string): PushResult {
+		if (this.limit === 0 || this.jobs.length >= this.limit) return { ok: false, reason: "full" };
+		const job: QueuedJob = {
+			id: this.nextId++,
+			openid,
+			text,
+			enqueuedAt: Date.now(),
+			attempts: 0,
+		};
+		this.jobs.push(job);
+		return { ok: true, job, ahead: this.jobs.length - 1 };
+	}
+
+	/** 手动构造一条不入队的任务（直接执行 / 失败重试时用） */
+	mint(openid: string, text: string): QueuedJob {
+		return { id: 0, openid, text, enqueuedAt: Date.now(), attempts: 0 };
+	}
+
+	shift(): QueuedJob | undefined {
+		return this.jobs.shift();
+	}
+
+	/** 派发失败时放回队首重试 */
+	unshift(job: QueuedJob): void {
+		this.jobs.unshift(job);
+	}
+
+	/** 按编号删除一条 */
+	remove(id: number): QueuedJob | undefined {
+		const index = this.jobs.findIndex((job) => job.id === id);
+		if (index === -1) return undefined;
+		return this.jobs.splice(index, 1)[0];
+	}
+
+	/** 清空并返回被清掉的任务 */
+	clear(): QueuedJob[] {
+		const dropped = this.jobs;
+		this.jobs = [];
+		return dropped;
+	}
+}

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;
 }
 
@@ -108,8 +114,13 @@ export const DEFAULT_COMMANDS: CommandConfig = {
 export interface RouteDeps {
 	/** commands pi currently knows about (extension/prompt/skill) */
 	listPiCommands(): readonly { name: string; source?: string }[];
-	/** deliver a pi command through pi's own dispatcher */
-	dispatch(text: string): void;
+	/**
+	 * deliver a pi command through pi's own dispatcher.
+	 * `runsTurn` marks commands that start an agent run (prompt templates, `/skill:name`):
+	 * those are serialized through the bot's queue, everything else runs immediately.
+	 * Returns "queued" when the bot deferred it, "rejected" when the queue was full.
+	 */
+	dispatch(text: string, options?: { runsTurn?: boolean }): DispatchResult;
 	/** answer the QQ user */
 	reply(text: string): Promise<void>;
 	busy: boolean;
@@ -117,6 +128,8 @@ export interface RouteDeps {
 	log(message: string, ...rest: unknown[]): void;
 }
 
+export type DispatchResult = "dispatched" | "queued" | "rejected";
+
 export type RouteResult = "dispatched" | "handled" | "text";
 
 const allowed = (cfg: CommandConfig, name: string): boolean => {
@@ -133,11 +146,19 @@ export async function routeSlash(deps: RouteDeps, text: string): Promise<RouteRe
 
 	// 1. pi extension commands, prompt templates and skill commands
 	if (deps.cfg.passthrough) {
-		const known = deps.listPiCommands().some((c) => c.name.toLowerCase() === name);
+		const known = deps.listPiCommands().find((c) => c.name.toLowerCase() === name);
 		if (known) {
-			deps.log("[cmd] 派发 pi 扩展命令:", parsed.raw.slice(0, 80));
-			deps.dispatch(parsed.raw);
-			await deps.reply(`已派发 /${name} 给 pi。`);
+			// 提示模板与 /skill: 会开启一轮 agent run，交给队列串行；扩展命令自己管理 LLM 交互
+			const runsTurn = known.source === "prompt" || known.source === "skill";
+			deps.log("[cmd] 派发 pi 命令:", parsed.raw.slice(0, 80), "runsTurn=", runsTurn);
+			const result = deps.dispatch(parsed.raw, { runsTurn });
+			if (result === "queued") {
+				await deps.reply(`已排队 /${name}：当前任务结束后执行（发 /queue 查看队列）。`);
+			} else if (result === "rejected") {
+				await deps.reply(`队列已满，/${name} 没有排上。发 /queue 查看队列，或 /cancel 清空后重发。`);
+			} else {
+				await deps.reply(`已派发 /${name} 给 pi。`);
+			}
 			return "dispatched";
 		}
 	}
@@ -146,16 +167,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 +206,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 +358,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 +386,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 +455,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 +488,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;