@zxh126/pi-qqbot 2.3.0 → 2.4.0

package/remote.ts

@@ -1,81 +1,81 @@
-import type { QQBotConfig } from "./config";
-
-/**
- * 「以下对话来自远程用户」提醒。
- *
- * pi 在锁屏/无人值守的机器上替 QQ 侧的远程用户干活：对方看不见屏幕，也没法点弹窗。
- * 所以在每个会话第一次真正把 QQ 消息交给 pi 跑起来时，把一段说明写进系统提示的
- * `qq-remote-context` section（排在用户消息之前、QQ 侧不可见），让它从一开始就按
- * 「远程 + 可能锁屏」的前提工作（默认离屏渲染，而不是截桌面）。
- *
- * 注入时机由 index.ts 的 before_agent_start 控制：只有本扩展派发的 QQ 消息真的开跑
- * 才注入；仅载入扩展、或本机 TUI 直接对话都不会触发。上下文压缩后由 session_compact 复位。
- */
-
-export interface RemoteConfig {
-	/** 每会话第一条消息注入一次提醒 */
-	notice: boolean;
-	/** 每次来自 QQ 的 run 在系统提示里追加几条规则 */
-	guidelines: boolean;
-	/** 追加在默认提醒末尾的自定义补充（留空 = 只用默认文案） */
-	extra: string;
-}
-
-export const DEFAULT_REMOTE: RemoteConfig = {
-	notice: true,
-	guidelines: true,
-	extra: "",
-};
-
-/** 说明放在系统提示的哪个 section 里（排查会话文件时靠这个 tag 认出来） */
-export const REMOTE_NOTICE_SECTION = "qq-remote-context";
-
-/** 「远程前提作废」更正用的 section tag */
-export const LOCAL_HANDOFF_SECTION = "qq-local-handoff";
-
-/** 配置里的 `remote` 可能缺字段（老配置、测试里手搓的 cfg），这里补齐默认值 */
-export function resolveRemoteConfig(cfg: Partial<Pick<QQBotConfig, "remote">> | null | undefined): RemoteConfig {
-	const raw = cfg?.remote ?? {};
-	return {
-		notice: raw.notice ?? DEFAULT_REMOTE.notice,
-		guidelines: raw.guidelines ?? DEFAULT_REMOTE.guidelines,
-		extra: String(raw.extra ?? DEFAULT_REMOTE.extra).trim(),
-	};
-}
-
-/** 首条消息前的说明：说清来源、锁屏风险、离屏渲染要求 */
-export function buildRemoteNotice(remote: RemoteConfig): string {
-	const lines = [
-		"[pi-qqbot 远程上下文 · 说明，不必回复本条]",
-		"",
-		"接下来的对话来自「远程 QQ 私聊用户」，不是本机终端用户。前提：",
-		"",
-		"1. 对方看不到本机屏幕、也收不到弹窗；回复应简明扼要。",
-		"2. 本机可能锁屏或无人值守。默认不要用桌面截屏、屏幕 OCR、UI 自动化、键鼠模拟、带界面的浏览器" +
-			"（例如 mcp__screenshot、mcp__winui 这类工具）：锁屏下它们只会拍到锁屏画面或直接失败。",
-		"3. 需要图/界面效果时，按项目类型自行选择离屏渲染方案（headless 浏览器渲 HTML、SVG、matplotlib/Pillow 等），" +
-			"生成 PNG 后用 qq_send_file 发到 QQ。不要为了“确认”先截桌面。",
-		"4. 只有确实需要判断是否锁屏时，才允许截一次桌面看有没有内容；其余一律以离屏渲染为准。",
-		"5. 需要人工介入（登录、验证码、实体操作）时直接说明并给替代方案；" +
-			"危险工具会先发到 QQ 等审批，对方可能不在电脑旁。",
-	];
-	if (remote.extra) lines.push("", remote.extra);
-	return lines.join("\n");
-}
-
-/** 本机接管后的更正：只在「上一轮来自 QQ」的第一次本机对话注入（只生效一轮） */
-export function buildLocalHandoffNotice(): string {
-	return [
-		"现在是本机用户在终端直接对话（同一会话内接管），之前「远程 QQ 用户」的前提作废：",
-		"可以正常截屏 / 看屏幕，回复详略按本机需求来，不需要用 qq_send_file 交付。",
-	].join("\n");
-}
-
-/** 系统提示里追加的规则（比首条提醒更短，每次 QQ run 都带上） */
-export function buildRemoteGuidelines(): string[] {
-	return [
-		"对话来自远程 QQ 用户：对方看不到本机屏幕，回复应简明扼要。",
-		"本机可能锁屏：默认禁用桌面截屏/屏幕 OCR/UI 自动化/键鼠模拟/带界面浏览器；要图就离屏渲染，再用 qq_send_file 发送。",
-		"需要本机人工操作时直接说明，不要等待或反复重试。",
-	];
-}
+import type { QQBotConfig } from "./config";
+
+/**
+ * 「以下对话来自远程用户」提醒。
+ *
+ * pi 在锁屏/无人值守的机器上替 QQ 侧的远程用户干活：对方看不见屏幕，也没法点弹窗。
+ * 所以在每个会话第一次真正把 QQ 消息交给 pi 跑起来时，把一段说明写进系统提示的
+ * `qq-remote-context` section（排在用户消息之前、QQ 侧不可见），让它从一开始就按
+ * 「远程 + 可能锁屏」的前提工作（默认离屏渲染，而不是截桌面）。
+ *
+ * 注入时机由 index.ts 的 before_agent_start 控制：只有本扩展派发的 QQ 消息真的开跑
+ * 才注入；仅载入扩展、或本机 TUI 直接对话都不会触发。上下文压缩后由 session_compact 复位。
+ */
+
+export interface RemoteConfig {
+	/** 每会话第一条消息注入一次提醒 */
+	notice: boolean;
+	/** 每次来自 QQ 的 run 在系统提示里追加几条规则 */
+	guidelines: boolean;
+	/** 追加在默认提醒末尾的自定义补充（留空 = 只用默认文案） */
+	extra: string;
+}
+
+export const DEFAULT_REMOTE: RemoteConfig = {
+	notice: true,
+	guidelines: true,
+	extra: "",
+};
+
+/** 说明放在系统提示的哪个 section 里（排查会话文件时靠这个 tag 认出来） */
+export const REMOTE_NOTICE_SECTION = "qq-remote-context";
+
+/** 「远程前提作废」更正用的 section tag */
+export const LOCAL_HANDOFF_SECTION = "qq-local-handoff";
+
+/** 配置里的 `remote` 可能缺字段（老配置、测试里手搓的 cfg），这里补齐默认值 */
+export function resolveRemoteConfig(cfg: Partial<Pick<QQBotConfig, "remote">> | null | undefined): RemoteConfig {
+	const raw = cfg?.remote ?? {};
+	return {
+		notice: raw.notice ?? DEFAULT_REMOTE.notice,
+		guidelines: raw.guidelines ?? DEFAULT_REMOTE.guidelines,
+		extra: String(raw.extra ?? DEFAULT_REMOTE.extra).trim(),
+	};
+}
+
+/** 首条消息前的说明：说清来源、锁屏风险、离屏渲染要求 */
+export function buildRemoteNotice(remote: RemoteConfig): string {
+	const lines = [
+		"[pi-qqbot 远程上下文 · 说明，不必回复本条]",
+		"",
+		"接下来的对话来自「远程 QQ 私聊用户」，不是本机终端用户。前提：",
+		"",
+		"1. 对方看不到本机屏幕、也收不到弹窗；回复应简明扼要。",
+		"2. 本机可能锁屏或无人值守。默认不要用桌面截屏、屏幕 OCR、UI 自动化、键鼠模拟、带界面的浏览器" +
+			"（例如 mcp__screenshot、mcp__winui 这类工具）：锁屏下它们只会拍到锁屏画面或直接失败。",
+		"3. 需要图/界面效果时，按项目类型自行选择离屏渲染方案（headless 浏览器渲 HTML、SVG、matplotlib/Pillow 等），" +
+			"生成 PNG 后用 qq_send_file 发到 QQ。不要为了“确认”先截桌面。",
+		"4. 只有确实需要判断是否锁屏时，才允许截一次桌面看有没有内容；其余一律以离屏渲染为准。",
+		"5. 需要人工介入（登录、验证码、实体操作）时直接说明并给替代方案；" +
+			"危险工具会先发到 QQ 等审批，对方可能不在电脑旁。",
+	];
+	if (remote.extra) lines.push("", remote.extra);
+	return lines.join("\n");
+}
+
+/** 本机接管后的更正：只在「上一轮来自 QQ」的第一次本机对话注入（只生效一轮） */
+export function buildLocalHandoffNotice(): string {
+	return [
+		"现在是本机用户在终端直接对话（同一会话内接管），之前「远程 QQ 用户」的前提作废：",
+		"可以正常截屏 / 看屏幕，回复详略按本机需求来，不需要用 qq_send_file 交付。",
+	].join("\n");
+}
+
+/** 系统提示里追加的规则（比首条提醒更短，每次 QQ run 都带上） */
+export function buildRemoteGuidelines(): string[] {
+	return [
+		"对话来自远程 QQ 用户：对方看不到本机屏幕，回复应简明扼要。",
+		"本机可能锁屏：默认禁用桌面截屏/屏幕 OCR/UI 自动化/键鼠模拟/带界面浏览器；要图就离屏渲染，再用 qq_send_file 发送。",
+		"需要本机人工操作时直接说明，不要等待或反复重试。",
+	];
+}

package/selfupdate.ts

@@ -0,0 +1,212 @@
+/**
+ * pi-qqbot「自我更新」：QQ 用户发「更新自己」/ `/update`，插件检查 npm 上的最新版，
+ * 用 **pi 自己的机制**（`pi update npm:@zxh126/pi-qqbot`）更新磁盘上的安装目录，
+ * 校验版本真的变了的之后，再走 `/qq reload` 重载扩展——不重启宿主进程。
+ *
+ * 为什么是确定性代码而不是丢给模型做：更新流程必须在「模型不可用」时也能跑，
+ * 且涉及写安装目录，不能交给模型自由发挥。
+ *
+ * 纯逻辑（版本比较、输出解析、流程编排）都走注入，单测不联网、不真跑 pi update。
+ */
+import { exec } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const PACKAGE_NAME = "@zxh126/pi-qqbot";
+export const NPM_REGISTRY = "https://registry.npmjs.org";
+export const NPM_CHECK_TIMEOUT_MS = 30_000;
+export const UPDATE_TIMEOUT_MS = 300_000;
+
+/** 包根目录（index.ts / selfupdate.ts 都在包根，package.json 是兄弟文件） */
+export function packageRoot(): string {
+	return path.dirname(fileURLToPath(import.meta.url));
+}
+
+/** 当前安装的版本；读不到返回 null */
+export function installedVersion(dir: string = packageRoot()): string | null {
+	try {
+		const pkg = JSON.parse(fs.readFileSync(path.join(dir, "package.json"), "utf8"));
+		return typeof pkg.version === "string" ? pkg.version : null;
+	} catch {
+		return null;
+	}
+}
+
+/** npm 输出里可能混着 warning，取第一个 semver */
+export function parseVersionOutput(text: string): string | null {
+	const match = /(\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?)/.exec(String(text ?? ""));
+	return match ? match[1] : null;
+}
+
+/** a 更新返回正数；相等返回 0；兼容 prerelease（1.0.0-beta < 1.0.0） */
+export function compareVersions(a: string, b: string): number {
+	const parse = (version: string) => {
+		const [core, pre] = String(version).split("-");
+		return {
+			nums: core.split(".").map((part) => Number.parseInt(part, 10) || 0),
+			pre: pre ?? null,
+		};
+	};
+	const left = parse(a);
+	const right = parse(b);
+	for (let index = 0; index < 3; index += 1) {
+		const diff = (left.nums[index] ?? 0) - (right.nums[index] ?? 0);
+		if (diff !== 0) return diff;
+	}
+	if (left.pre === null && right.pre === null) return 0;
+	if (left.pre === null) return 1;
+	if (right.pre === null) return -1;
+	return left.pre < right.pre ? -1 : left.pre > right.pre ? 1 : 0;
+}
+
+// ---------------------------------------------------------------------------
+// 命令执行（可注入；默认真跑）
+// ---------------------------------------------------------------------------
+
+export interface CommandResult {
+	code: number;
+	stdout: string;
+	stderr: string;
+}
+
+export type CommandRunner = (command: string, timeoutMs: number) => Promise<CommandResult>;
+
+/**
+ * 默认执行器：child_process.exec（shell）。命令串全部来自本文件的常量，
+ * 没有用户输入参与拼接，无注入面。Windows 上 pi/npm 都是 .cmd shim，必须走 shell。
+ */
+export const shellRunner: CommandRunner = (command, timeoutMs) =>
+	new Promise((resolve) => {
+		exec(
+			command,
+			{ timeout: timeoutMs, windowsHide: true, maxBuffer: 8 * 1024 * 1024, encoding: "utf8" },
+			(error, stdout, stderr) => {
+				const code =
+					error && typeof (error as { code?: unknown }).code === "number"
+						? ((error as { code: number }).code)
+						: error
+							? 1
+							: 0;
+				resolve({ code, stdout: String(stdout ?? ""), stderr: String(stderr ?? "") });
+			},
+		);
+	});
+
+export interface VersionCheckResult {
+	ok: boolean;
+	version?: string;
+	error?: string;
+}
+
+/** `npm view <pkg> version`：拿 registry 上的最新版本 */
+export async function checkLatestVersion(
+	runner: CommandRunner = shellRunner,
+	registry: string = NPM_REGISTRY,
+): Promise<VersionCheckResult> {
+	try {
+		const result = await runner(`npm view ${PACKAGE_NAME} version --registry=${registry}`, NPM_CHECK_TIMEOUT_MS);
+		const version = parseVersionOutput(result.stdout);
+		if (result.code !== 0 || !version) {
+			return { ok: false, error: `npm view 失败（exit ${result.code}）${result.stderr ? `：${result.stderr.trim().slice(0, 160)}` : ""}` };
+		}
+		return { ok: true, version };
+	} catch (error) {
+		return { ok: false, error: String((error as Error)?.message ?? error).slice(0, 160) };
+	}
+}
+
+export interface UpdateResult {
+	ok: boolean;
+	code?: number;
+	output?: string;
+	error?: string;
+}
+
+/** `pi update npm:<pkg>`：pi 官方的扩展更新命令（就是用户手动发版验收用的那条） */
+export async function applyUpdate(runner: CommandRunner = shellRunner): Promise<UpdateResult> {
+	try {
+		const result = await runner(`pi update npm:${PACKAGE_NAME}`, UPDATE_TIMEOUT_MS);
+		if (result.code !== 0) {
+			const detail = `${result.stderr || result.stdout}`.trim().split(/\r?\n/).slice(-3).join(" | ").slice(0, 300);
+			return { ok: false, code: result.code, output: detail, error: `pi update 失败（exit ${result.code}）` };
+		}
+		if (/已是最新|already (?:at the )?(?:latest|up.to.date)|Skipping/i.test(result.stdout) && !/Updated|updated/i.test(result.stdout)) {
+			return { ok: false, error: "pi update 认为已是最新（磁盘版本号可能和 registry 不一致），未做变更" };
+		}
+		return { ok: true, output: result.stdout.trim().split(/\r?\n/).slice(-3).join(" | ").slice(0, 300) };
+	} catch (error) {
+		return { ok: false, error: String((error as Error)?.message ?? error).slice(0, 160) };
+	}
+}
+
+// ---------------------------------------------------------------------------
+// 流程编排（依赖注入：QQ 回执 / 更新器 / 重载都从外面给）
+// ---------------------------------------------------------------------------
+
+export interface SelfUpdateDeps {
+	/** 当前安装版本（通常 = installedVersion()） */
+	currentVersion: string | null;
+	/** 查 registry 最新版 */
+	checkLatest(): Promise<VersionCheckResult>;
+	/** 执行 pi update */
+	applyUpdate(): Promise<UpdateResult>;
+	/** 更新后磁盘上的版本（通常 = installedVersion()） */
+	versionAfterUpdate(): string | null;
+	/** 给 QQ 用户回话 */
+	reply(text: string): Promise<unknown>;
+	/** 重载扩展（对应 /qq reload） */
+	reload(): Promise<void> | void;
+}
+
+export type SelfUpdateOutcome =
+	| "already-latest"
+	| "updated"
+	| "check-failed"
+	| "update-failed"
+	| "version-mismatch";
+
+export async function runSelfUpdate(deps: SelfUpdateDeps): Promise<SelfUpdateOutcome> {
+	await deps.reply("正在检查 pi-qqbot 更新…");
+	const latest = await deps.checkLatest();
+	if (!latest.ok || !latest.version) {
+		await deps.reply(`❌ 查询最新版本失败：${latest.error ?? "未知错误"}`);
+		return "check-failed";
+	}
+	const current = deps.currentVersion ?? "0.0.0";
+	if (compareVersions(latest.version, current) <= 0) {
+		await deps.reply(`✅ 已是最新版本 v${current}，无需更新。`);
+		return "already-latest";
+	}
+	await deps.reply(`发现新版本 v${current} → v${latest.version}，开始更新（pi update，最多等 5 分钟）…`);
+	const updated = await deps.applyUpdate();
+	if (!updated.ok) {
+		await deps.reply(`❌ 更新失败：${updated.error ?? "未知错误"}${updated.output ? `\n${updated.output}` : ""}`);
+		return "update-failed";
+	}
+	const after = deps.versionAfterUpdate();
+	if (after !== latest.version) {
+		await deps.reply(
+			`⚠️ 更新命令执行完，但磁盘版本是 v${after ?? "?"}（预期 v${latest.version}）。先不重载，请人工确认安装目录。`,
+		);
+		return "version-mismatch";
+	}
+	await deps.reply(`✅ 已更新到 v${latest.version}，正在重载扩展（会话保留，模型上下文不受影响）…`);
+	await deps.reload();
+	return "updated";
+}
+
+// ---------------------------------------------------------------------------
+// 自然语言意图
+// ---------------------------------------------------------------------------
+
+/** 「更新自己」「升级一下插件」这类口令；单说「更新」不认（太容易撞车） */
+const RE_UPDATE_SELF = /^(?:帮我)?(?:更新|升级|自更|自我更)(?:新)?(?:一下)?(?:自己|本身|qqbot|pi-?qqbot|插件|扩展)?$/i;
+
+export function isUpdateSelfIntent(text: string): boolean {
+	const value = String(text ?? "").trim();
+	if (!RE_UPDATE_SELF.test(value)) return false;
+	// 「更新」「升级」单字不带宾语时不认，太容易撞车；但「自更新」「自我更新」本身带了宾语
+	if (/^(?:帮我)?(?:更新|升级)(?:一下)?$/.test(value)) return false;
+	return true;
+}