@zxh126/pi-qqbot 1.2.1 → 1.3.1

package/README.md

@@ -84,6 +84,7 @@ Any message that starts with `/` is routed before it can become a chat prompt:
 
 | # | Kind | Behaviour |
 |---|---|---|
+| 0 | extension commands whose output only goes to `ctx.ui.*` (`/usage`, `/cost`, `/mcp`, `/llama`) | `/usage` and `/cost` are **bridged** (see below) so the report comes back to QQ; `/mcp` and `/llama` need host-TUI dialogs and are answered with an explanation instead of being silently swallowed |
 | 1 | pi **extension commands**, prompt templates, `/skill:name` | dispatched to pi with `expandPromptTemplates: true`, so things like `/usage`, `/cost` or your own commands work from QQ |
 | 2 | pi built-ins this bridge can take over | re-implemented through the extension API (table below) |
 | 3 | pi built-ins that only exist in the TUI | answered with "run it on the host", never sent to the model |
@@ -108,6 +109,21 @@ Host-only (answered, never forwarded to the model): `/settings`, `/hotkeys`, `/c
 `/trust`, `/login`, `/logout`, `/scoped-models`, `/llama`, `/import`, `/export`, `/share`, `/bug`,
 `/copy`, `/privacy`.
 
+### TUI-only commands come back to QQ
+
+Some extension commands never print into the conversation — they call `ctx.ui.notify()` (and
+`pi.appendEntry()`), which only renders on the host TUI/RPC front end. In QQ that showed up as
+"dispatched, then silence". The bridge closes that hole:
+
+| Command | What happens |
+|---|---|
+| `/usage [range]`, `/cost [range]` | re-dispatched as `/qq usage <range>`: the bridge runs the original `/usage` command, then reads the fresh `customType: "usage-report"` entry from the session and renders it as text (requests, tokens, cache ratio, cost, per-model). **Usage unchanged** — keep sending `/usage today`. |
+| `/mcp`, `/llama` | answered: they need host-TUI selection dialogs / browser login, so nothing is dispatched |
+
+`/usage rate ...` and `/usage help` change settings or print help on the TUI; the bridge tells you
+that instead of silently doing nothing. The `usage-report` entry type is the only coupling point with
+[`pi-usage-report`](https://gitee.com/zxh126/pi-usage-report).
+
 Guards:
 
 - `/reload`, `/new`, `/compact`, `/quit`, `/tree`, `/fork`, `/clone` and `/resume` refuse to run while a task

package/constants.ts

@@ -16,5 +16,7 @@ export const DISPATCH_RETRY_MS = 3000;
 export const CANCEL_SETTLE_GRACE_MS = 8000;
 
 const PI_DIR = path.join(os.homedir(), ".pi", "agent");
+/** pi 的 agent 目录（其他扩展也往里写东西，如 pi-usage-report） */
+export const PI_AGENT_DIR = PI_DIR;
 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/docs/README.zh-CN.md

@@ -84,6 +84,7 @@ pi install ./pi-qqbot
 
 | # | 类型 | 行为 |
 |---|---|---|
+| 0 | 输出只走 `ctx.ui.*` 的扩展命令（`/usage`、`/cost`、`/mcp`、`/llama`） | `/usage`、`/cost` 会**桥接**（见下）把报告发回 QQ；`/mcp`、`/llama` 需要主机 TUI 的选择框/登录，直接回执说明，不再静默 |
 | 1 | pi 的**扩展命令**、prompt 模板、`/skill:name` | 以 `expandPromptTemplates: true` 派发给 pi，所以 `/usage`、`/cost` 或你自己注册的命令在 QQ 里也能用 |
 | 2 | 本桥接能接管的 pi 内置命令 | 用扩展 API 重新实现（见下表） |
 | 3 | 只能在 TUI 里跑的 pi 内置命令 | 回执「请在主机执行」，**不会**送进模型 |
@@ -107,6 +108,20 @@ pi install ./pi-qqbot
 只能在主机执行（回执，不转发给模型）：`/settings`、`/hotkeys`、`/changelog`、`/trust`、`/login`、
 `/logout`、`/scoped-models`、`/llama`、`/import`、`/export`、`/share`、`/bug`、`/copy`、`/privacy`。
 
+### 只往 TUI 打字的命令，现在会回到 QQ
+
+有些扩展命令从不往对话里输出，而是调 `ctx.ui.notify()`（配合 `pi.appendEntry()`）——只渲染在主机
+TUI/RPC 前端。在 QQ 里的表现就是「已派发，然后没下文」。桥接把这个洞堵上：
+
+| 命令 | 现在发生什么 |
+|---|---|
+| `/usage [范围]`、`/cost [范围]` | 改派为 `/qq usage <范围>`：桥接先重跑原 `/usage` 命令，再从 session 里读出新的 `customType: "usage-report"` 条目，渲染成文本回 QQ（请求数/总 token/缓存比/费用/按模型）。**用法不变**，照旧发 `/usage today` |
+| `/mcp`、`/llama` | 直接回执：它们需要主机 TUI 的选择框 / 浏览器登录，不会派发 |
+| `/usage rate <值>`、`/usage rate auto` | 会真的执行（写 `~/.pi/agent/pi-usage-report.json` / 刷新汇率缓存），桥接再读回该文件确认新汇率；只发 `/usage rate` 与 `/usage help` 则本地直接回执 |
+
+桥接与 [`pi-usage-report`](https://gitee.com/zxh126/pi-usage-report) 的耦合只有两处：`usage-report` 这个
+custom entry 类型名，以及它写在 `~/.pi/agent/` 下的两个配置文件。
+
 约束：
 
 - 有任务在跑时，`/reload`、`/new`、`/compact`、`/quit`、`/tree`、`/fork`、`/clone`、`/resume` 会拒绝执行

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zxh126/pi-qqbot",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "type": "module",
   "description": "Bridge the Pi coding agent into QQ private chats, with remote tool-call approval",
   "license": "MIT",
@@ -27,7 +27,7 @@
     ]
   },
   "scripts": {
-    "test": "node test/queue.test.mjs && node test/logger.test.mjs"
+    "test": "node test/queue.test.mjs && node test/logger.test.mjs && node test/usage-bridge.test.mjs"
   },
   "files": [
     "*.ts",

package/slash.ts

@@ -26,6 +26,8 @@
 import fs from "node:fs";
 import path from "node:path";
 
+import { PI_AGENT_DIR } from "./constants";
+
 export interface SlashCommandText {
 	/** command name without the leading slash, lower-cased (`skill:name` keeps its colon) */
 	name: string;
@@ -130,6 +132,26 @@ export interface RouteDeps {
 
 export type DispatchResult = "dispatched" | "queued" | "rejected";
 
+/**
+ * 输出只走 `ctx.ui.*`（TUI / RPC 通道）的扩展命令。
+ *
+ * 这类命令在 QQ 里发了不会有任何回复：它们的结果是通过 `ctx.ui.notify()` 渲染的，
+ * 而本桥接只把 assistant 文本（`message_update.text_delta`）转发到 QQ。
+ *
+ * - 带 `bridge`：改派 `/qq <bridge> <args>`，由桥接命令重新执行原命令并读 session 里
+ *   的 custom entry，自行渲染回 QQ（用户用法不变，仍发 `/usage today`）。
+ * - 不带 `bridge`：需要主机 TUI 的交互（选择框/浏览器登录），直接回执说清楚，不能沉默。
+ *
+ * 必须在 passthrough **之前**判断：这些命令确实在 `pi.getCommands()` 里，
+ * 一旦先走 passthrough 就会被派发到黑洞。
+ */
+export const UI_ONLY: Readonly<Record<string, { bridge?: string; hint: string }>> = {
+	usage: { bridge: "usage", hint: "用量统计会改走 /qq usage 桥接" },
+	cost: { bridge: "usage", hint: "用量统计会改走 /qq usage 桥接" },
+	mcp: { hint: "MCP 管理需要主机 TUI 的选择框与浏览器登录" },
+	llama: { hint: "本地 llama 管理需要主机 TUI" },
+};
+
 export type RouteResult = "dispatched" | "handled" | "text";
 
 const allowed = (cfg: CommandConfig, name: string): boolean => {
@@ -144,6 +166,19 @@ export async function routeSlash(deps: RouteDeps, text: string): Promise<RouteRe
 	if (!parsed) return "text";
 	const { name } = parsed;
 
+	// 0. 输出只走 TUI 通道的扩展命令：桥接或明确回执（必须早于 passthrough）
+	const uiOnly = UI_ONLY[name];
+	if (uiOnly && deps.listPiCommands().some((c) => c.name.toLowerCase() === name)) {
+		if (uiOnly.bridge) {
+			const bridge = `/qq ${uiOnly.bridge}${parsed.args ? ` ${parsed.args}` : ""}`;
+			deps.log("[cmd] 桥接 UI-only 命令:", parsed.raw.slice(0, 60), "->", bridge.slice(0, 60));
+			deps.dispatch(bridge);
+			return "dispatched";
+		}
+		await deps.reply(`/${name} ${uiOnly.hint}，QQ 侧无法执行。`);
+		return "handled";
+	}
+
 	// 1. pi extension commands, prompt templates and skill commands
 	if (deps.cfg.passthrough) {
 		const known = deps.listPiCommands().find((c) => c.name.toLowerCase() === name);
@@ -344,6 +379,108 @@ export function pickerExpired(picker: PickerState | null): boolean {
 	return !picker || Date.now() - picker.createdAt > PICKER_TTL_MS;
 }
 
+/** pi-usage-report 写入 session 的 custom entry 类型（耦合点，约定值） */
+const USAGE_ENTRY_TYPE = "usage-report";
+
+/** pi-usage-report 的配置/汇率缓存（读回来确认：命令真的生效了，而不是口头应下） */
+const USAGE_SETTINGS_FILE = "pi-usage-report.json";
+const USAGE_RATE_FILE = "pi-usage-report-rate.json";
+
+const USAGE_HELP = [
+	"/usage（默认 today）",
+	"/usage today | yesterday | week | lastweek | month | lastmonth | all",
+	"/usage 7d | 12h | 2w | 3m | 10天        滚动窗口",
+	"/usage 2026-09-01..2026-09-30       本地日期区间（含首尾）",
+	"/usage 今天 | 昨天 | 本周 | 上周 | 本月 | 上月 | 全部",
+	"/usage rate <值> | rate auto        固定 USD→本币汇率，或恢复自动（会真的写配置）",
+].join("\n");
+
+function readAgentJson(file: string): any {
+	try {
+		return JSON.parse(fs.readFileSync(path.join(PI_AGENT_DIR, file), "utf8"));
+	} catch {
+		return undefined;
+	}
+}
+
+const CURRENCY_SYMBOLS: Record<string, string> = { CNY: "¥", USD: "$", EUR: "€", JPY: "¥", GBP: "£", HKD: "HK$" };
+
+/** 复刻 pi-usage-report 的 readSettings 优先级：fixed(usdRate) > 缓存的发布汇率 > 无 */
+function usageMoney(): { code: string; symbol: string; rate: number | null; source: string } {
+	const raw = readAgentJson(USAGE_SETTINGS_FILE) ?? {};
+	const code = String(raw.currency ?? "CNY").toUpperCase();
+	const symbol = typeof raw.symbol === "string" ? raw.symbol : (CURRENCY_SYMBOLS[code] ?? code);
+	const pinned = typeof raw.usdRate === "number" && raw.usdRate > 0 ? raw.usdRate : undefined;
+	const fixed = raw.rateMode === "auto" ? undefined : pinned;
+	if (fixed !== undefined) return { code, symbol, rate: fixed, source: "fixed，/usage rate 手动固定" };
+	const cache = readAgentJson(USAGE_RATE_FILE);
+	if (cache && cache.code === code && typeof cache.rate === "number" && cache.rate > 0) {
+		const ageMinutes = Math.max(0, Math.round((Date.now() - Number(cache.fetchedAt ?? 0)) / 60000));
+		return { code, symbol, rate: cache.rate, source: `cache，${ageMinutes} 分钟前抓取` };
+	}
+	return { code, symbol, rate: null, source: "无，可用 /usage rate <值>" };
+}
+
+function moneyText(money: { code: string; rate: number | null; source: string }): string {
+	return money.rate === null
+		? `USD/${money.code}：无可用汇率（${money.source}）`
+		: `USD/${money.code} = ${money.rate}（${money.source}）`;
+}
+
+function sessionEntries(ctx: any): any[] {
+	try {
+		return ctx?.sessionManager?.getEntries?.() ?? [];
+	} catch {
+		return [];
+	}
+}
+
+const intText = (value: unknown): string =>
+	typeof value === "number" && Number.isFinite(value) ? Math.round(value).toLocaleString("en-US") : "0";
+
+function localStamp(value: unknown): string {
+	if (typeof value !== "string") return "?";
+	const date = new Date(value);
+	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())}`;
+}
+
+/** 把 pi-usage-report 的 ReportData 渲染成 QQ 可读的纯文本 */
+function formatUsage(data: any): string {
+	if (!data?.totals) return "用量报告为空。";
+	const t = data.totals;
+	const money = data.money ?? {};
+	const usd = Number(t.costUsd ?? 0);
+	const rate = typeof money.rate === "number" ? money.rate : null;
+	const symbol = money.symbol ?? "$";
+	const costText = rate !== null ? `${symbol}${(usd * rate).toFixed(2)}（USD ${usd.toFixed(4)}，汇率 ${rate}）` : `USD ${usd.toFixed(4)}（无汇率）`;
+	const totalTokens = Number(t.totalTokens ?? 0);
+	const cachePct = totalTokens > 0 ? ((Number(t.cacheRead ?? 0) / totalTokens) * 100).toFixed(1) : "0.0";
+	const lines = [
+		`用量统计：${data.rangeLabel ?? "?"}   ${localStamp(data.from)} → ${localStamp(data.to)}`,
+		`请求 ${intText(t.requests)} 次   合计 ${formatTokens(totalTokens)} tokens   费用 ${costText}`,
+		`输入 ${intText(t.input)}   输出 ${intText(t.output)}   缓存读 ${intText(t.cacheRead)}（${cachePct}%）`,
+		`缓存写 ${intText(t.cacheWrite)}   推理 ${intText(t.reasoning)}`,
+	];
+	const models: any[] = Array.isArray(data.byModel) ? data.byModel : [];
+	if (models.length > 0) {
+		lines.push("按模型：");
+		for (const row of models.slice(0, 5)) {
+			const bucket = row?.bucket ?? {};
+			const rowUsd = Number(bucket.costUsd ?? 0);
+			const rowCost = rate !== null ? `${symbol}${(rowUsd * rate).toFixed(2)}` : `USD ${rowUsd.toFixed(4)}`;
+			lines.push(
+				`  ${row?.model ?? "unknown"}  ${intText(bucket.requests)} 次  ${formatTokens(Number(bucket.totalTokens ?? 0))} tokens  ${rowCost}`,
+			);
+		}
+	}
+	const sessions: any[] = Array.isArray(data.bySession) ? data.bySession : [];
+	if (sessions.length > 1) lines.push(`会话数：${sessions.length} 个`);
+	if (t.unpriced) lines.push(`注：${intText(t.unpriced)} 次请求没有计价。`);
+	return lines.join("\n");
+}
+
 /**
  * Body of the `/qq` bridge command: pi hands it a fresh `ExtensionCommandContext`,
  * which is the only place `reload()`, `newSession()`, `fork()`, `navigateTree()` and
@@ -444,6 +581,62 @@ export async function runBridge(
 			await ctx.fork(leaf, { position: "at" });
 			return;
 		}
+		case "usage": {
+			// /qq usage [...]：重跑原 /usage 命令，再从 session 里读回它写的 custom entry
+			const rest = arg.slice(first.length).trim();
+
+			// help：不执行命令（它在 TUI 打文本），直接回本地帮助
+			if (first === "help" || first === "?") {
+				reply(USAGE_HELP);
+				return;
+			}
+
+			const commands = (pi?.getCommands?.() ?? []) as { name: string }[];
+			const hasUsage = commands.some((c) => ["usage", "cost"].includes(String(c.name).toLowerCase()));
+			if (!hasUsage) {
+				reply("主机上没有 /usage 命令（需要安装 pi-usage-report），无法统计。");
+				return;
+			}
+
+			// rate：会写配置/联网刷新汇率，必须真的执行，再读回状态确认（不能只回一句“TUI 可见”）
+			if (first === "rate") {
+				if (!rest) {
+					reply(moneyText(usageMoney()));
+					return;
+				}
+				const rateCommand = `/usage rate ${rest}`;
+				try {
+					await pi.sendUserMessage(rateCommand, { expandPromptTemplates: true });
+				} catch (error) {
+					reply(`执行 ${rateCommand} 失败：${String((error as any)?.message ?? error).slice(0, 200)}`);
+					return;
+				}
+				const after = usageMoney();
+				reply(
+					`已执行 ${rateCommand}\n${moneyText(after)}\n（下一步 /usage today 的 ¥/USD 换算就用它；无效值会被忽略）`,
+				);
+				return;
+			}
+
+			const command = `/usage${arg ? ` ${arg}` : ""}`;
+			const before = new Set(sessionEntries(ctx).map((entry: any) => entry?.id));
+			reply(`正在统计用量（${command}）…`);
+			try {
+				await pi.sendUserMessage(command, { expandPromptTemplates: true });
+			} catch (error) {
+				reply(`统计失败：${String((error as any)?.message ?? error).slice(0, 200)}`);
+				return;
+			}
+			const entry = [...sessionEntries(ctx)]
+				.reverse()
+				.find((e: any) => e?.type === "custom" && e?.customType === USAGE_ENTRY_TYPE && !before.has(e?.id));
+			if (!entry) {
+				reply("没拿到用量报告（命令没有产出数据）。");
+				return;
+			}
+			reply(formatUsage(entry.data));
+			return;
+		}
 		case "session": {
 			const sm = ctx.sessionManager;
 			const usage = ctx.getContextUsage?.();