@zxh126/pi-qqbot 1.2.0 → 1.3.0

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
@@ -221,7 +237,7 @@ The QQ gateway keeps only one active connection per bot. The extension uses a `p
 
 ## Logs
 
-Debug logs are written to `~/.pi/agent/pi-qqbot.log`.
+Debug logs are written to `~/.pi/agent/pi-qqbot.log`. Each line starts with a **local** timestamp that carries the UTC offset, e.g. `[2026-10-24T07:39:09.762+08:00]`, so it lines up with file mtimes and process start times without mental arithmetic.
 
 ## License
 

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 help` 会改汇率或打印帮助（只在 TUI 可见），桥接会明确告知。
+桥接与 [`pi-usage-report`](https://gitee.com/zxh126/pi-usage-report) 的唯一耦合是 `usage-report` 这个
+custom entry 类型名。
+
 约束：
 
 - 有任务在跑时，`/reload`、`/new`、`/compact`、`/quit`、`/tree`、`/fork`、`/clone`、`/resume` 会拒绝执行
@@ -211,7 +226,7 @@ QQ 网关对同一 bot 只保留一个活跃连接。插件用 `proper-lockfile`
 
 ## 日志
 
-调试日志写入 `~/.pi/agent/pi-qqbot.log`。
+调试日志写入 `~/.pi/agent/pi-qqbot.log`。每行开头是**本地时间 + 时区偏移**（如 `[2026-10-24T07:39:09.762+08:00]`），和文件 mtime、进程启动时间直接对得上，不需要再拿 UTC 换算。
 
 ## License
 

package/logger.ts

@@ -4,12 +4,28 @@ import path from "node:path";
 
 const LOG_PATH = path.join(os.homedir(), ".pi", "agent", "pi-qqbot.log");
 
-function ts() {
-  return new Date().toISOString();
+const pad = (value: number, width = 2): string =>
+  String(Math.trunc(Math.abs(value))).padStart(width, "0");
+
+/**
+ * 本地时间戳 + 时区偏移，例如 `2026-10-24T07:39:09.762+08:00`。
+ *
+ * 以前用 `toISOString()`（UTC），看日志要和文件 mtime、进程启动时间（都是本地）
+ * 来回换算，容易对不上；北京时间直接读即可，同时又保留偏移，跨时区不会歧义。
+ */
+export function timestamp(date = new Date()): string {
+  const offsetMinutes = -date.getTimezoneOffset(); // 东八区 = +480
+  const sign = offsetMinutes >= 0 ? "+" : "-";
+  const offset = `${sign}${pad(offsetMinutes / 60)}:${pad(offsetMinutes % 60)}`;
+  const local =
+    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+    `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +
+    `.${pad(date.getMilliseconds(), 3)}`;
+  return `${local}${offset}`;
 }
 
 export function log(...args: unknown[]) {
-  const line = `[${ts()}] ${args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ")}\n`;
+  const line = `[${timestamp()}] ${args.map((a) => (typeof a === "string" ? a : JSON.stringify(a))).join(" ")}\n`;
   try {
     fs.appendFileSync(LOG_PATH, line, "utf8");
   } catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zxh126/pi-qqbot",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "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"
+    "test": "node test/queue.test.mjs && node test/logger.test.mjs && node test/usage-bridge.test.mjs"
   },
   "files": [
     "*.ts",

package/slash.ts

@@ -130,6 +130,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 +164,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 +377,63 @@ 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";
+
+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 +534,38 @@ export async function runBridge(
 			await ctx.fork(leaf, { position: "at" });
 			return;
 		}
+		case "usage": {
+			// /qq usage [...]：重跑原 /usage 命令，再从 session 里读回它写的 custom entry
+			if (first === "rate" || first === "help" || first === "?") {
+				reply(
+					`/usage ${arg} 会修改汇率或打印帮助，那些输出只在主机 TUI 可见；\n发 /usage today|week|month|all|7d 可在 QQ 里看统计。`,
+				);
+				return;
+			}
+			const commands = (pi?.getCommands?.() ?? []) as { name: string }[];
+			if (!commands.some((c) => ["usage", "cost"].includes(String(c.name).toLowerCase()))) {
+				reply("主机上没有 /usage 命令（需要安装 pi-usage-report），无法统计。");
+				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?.();