pi-weixin-connect 0.1.0 → 0.2.0

package/README.md

@@ -1,12 +1,15 @@
 # pi-weixin-connect
 
+> **平台要求：Linux**。后台服务通过 systemd 用户单元（`systemctl --user`）管理，
+> 仅在 Linux 上验证；macOS / Windows 未支持。
+
 把**微信 ClawBot**（腾讯 iLink Bot 协议）接到**当前 Pi 会话**的桥接插件。
 
 微信里发的消息进入当前 Pi 会话，Pi 干完活后把最终回答发回微信；用法和
 [`pi-qq-connect`](https://github.com/JiangXingChi/pi-qq-connect) 对齐，只是聊天软件换成微信。
 
-> 状态：P0（文本通道）、P2（媒体）与独立后台服务（P1 的常驻部分）已完成，
-> **桌面命令映射（`/new`、`/model` 等）尚未接入**。
+> 状态：文本通道、媒体与独立后台服务已完成。聊天窗口里只映射 `/new`（技能与提示模板
+> 仍可正常使用）；`/model` 等控制命令请在终端执行。
 > 文本收发已在真机微信验证；图片/文件目前只有单元与 mock 验证，尚未做真机回归。
 
 ## 能力
@@ -30,7 +33,13 @@
 
 ## 安装
 
-尚未发布 npm，先从本地目录安装：
+已发布 npm（[`pi-weixin-connect`](https://www.npmjs.com/package/pi-weixin-connect)）：
+
+```bash
+pi install pi-weixin-connect
+```
+
+本地开发目录：
 
 ```bash
 pi install /path/to/pi-weixin-connect
@@ -66,6 +75,7 @@ node scripts/login.mjs --force  # 强制重扫，失败会回滚旧凭证
 | `/wx stop [--force]` | 停止独立后台服务 |
 | `/wx logout` | 删除凭证并断开 |
 | `/wx log [n]` | 最近 n 条日志 |
+| `/wx help` | 命令表 |
 
 ## 独立后台服务（推荐）
 
@@ -84,7 +94,7 @@ scripts/uninstall-service.sh        # 卸载（不删凭证）
 状态看 `/wx status` 的“后台服务”一行。服务日志：journal 或
 `~/.pi/agent/pi-weixin-connect.service.log`。
 
-微信里直接发 `/new`、`/model` 等桌面命令属于 P1，尚未接入。
+微信里可以直接发 `/new` 开新会话（聊天窗口只映射这一条）；`/model` 等控制命令请在终端执行。
 
 ## 配置
 

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-weixin-connect",
-	"version": "0.1.0",
-	"description": "微信 ClawBot（iLink）⇄ 当前 Pi 会话：私聊、文本收发、后台常驻",
+	"version": "0.2.0",
+	"description": "微信 ClawBot（iLink）⇄ 当前 Pi 会话：私聊、文本收发、后台常驻（Linux）",
 	"type": "module",
 	"license": "MIT",
 	"keywords": [
@@ -12,7 +12,8 @@
 		"weixin",
 		"ilink",
 		"clawbot",
-		"bridge"
+		"bridge",
+		"linux"
 	],
 	"engines": {
 		"node": ">=22.19.0"
@@ -28,7 +29,6 @@
 		"bin",
 		"scripts",
 		"packaging",
-		"examples",
 		"README.md"
 	],
 	"scripts": {

package/src/api.js

@@ -83,7 +83,7 @@ export class WeixinApi {
 					// 200 + 非 JSON（反代门户页、HTML 错误页）必须当失败，
 					// 否则 getupdates 会把它当空结果，200ms 一次热轮询
 					if (res.ok) {
-						throw new ApiError(`响应不是 JSON：${method} ${url.pathname}`, {
+						throw new ApiError(`response is not JSON: ${method} ${url.pathname}`, {
 							status: res.status,
 							body: text.slice(0, 200),
 						});
@@ -117,7 +117,7 @@ export class WeixinApi {
 			return data ?? {};
 		} catch (err) {
 			if (err?.name === "AbortError") {
-				throw new ApiError(signal?.aborted ? `请求已取消：${path}` : `请求超时：${path}`, { status: 0 });
+				throw new ApiError(signal?.aborted ? `request cancelled: ${path}` : `request timed out: ${path}`, { status: 0 });
 			}
 			throw err;
 		} finally {
@@ -153,7 +153,7 @@ export class WeixinApi {
 		// 空对象意味着响应体是空的（#request 对空体返回 {}）。长轮询不能把这种
 		// 响应当成功，否则会 200ms 一次热循环。
 		if (!data || typeof data !== "object" || Object.keys(data).length === 0) {
-			throw new ApiError("getupdates 返回空响应", { status: 200 });
+			throw new ApiError("getupdates returned an empty response", { status: 200 });
 		}
 		return data;
 	}

package/src/auth.js

@@ -170,10 +170,10 @@ export async function login({
 
 	try {
 	for (let refresh = 0; refresh <= maxRefreshes; refresh++) {
-		if (signal?.aborted) throw new Error("登录已取消");
+		if (signal?.aborted) throw new Error("login cancelled");
 		// 取二维码固定打官方基座；redirect 只用于状态轮询
 		const qr = await api.getQrCode(localTokens, api.baseUrl);
-		if (!qr?.qrcode || !qr?.qrcode_img_content) throw new Error("服务端没有返回二维码");
+		if (!qr?.qrcode || !qr?.qrcode_img_content) throw new Error("server did not return a QR code");
 
 		const rendered = renderQr(qr.qrcode_img_content);
 		if (lastPng && lastPng !== rendered.pngPath) {
@@ -192,14 +192,14 @@ export async function login({
 		let expired = false;
 		let pollErrors = 0;
 		while (!expired) {
-			if (signal?.aborted) throw new Error("登录已取消");
+			if (signal?.aborted) throw new Error("login cancelled");
 			let status;
 			try {
 				status = await api.getQrStatus(qr.qrcode, verifyCode, baseUrl);
 			} catch (err) {
 				pollErrors++;
 				log?.warn(`轮询二维码状态失败 ${pollErrors}/5：${err?.message ?? err}`);
-				if (pollErrors >= 5) throw new Error("连续 5 次无法查询二维码状态，检查网络后重试");
+				if (pollErrors >= 5) throw new Error("could not fetch the QR status 5 times in a row; check the network and retry");
 				await sleep(1500);
 				continue;
 			}
@@ -219,14 +219,14 @@ export async function login({
 					break;
 				case "need_verifycode": {
 					onStatus("需要输入手机上的配对码");
-					if (!onNeedVerifyCode) throw new Error("需要配对码，但当前环境无法输入");
+					if (!onNeedVerifyCode) throw new Error("a pairing code is required but this environment cannot prompt for it");
 					const code = await onNeedVerifyCode();
-					if (!code) throw new Error("没有输入配对码，登录取消");
+					if (!code) throw new Error("no pairing code entered; login cancelled");
 					verifyCode = String(code).trim();
 					break;
 				}
 				case "verify_code_blocked":
-					throw new Error("配对码错误次数过多，二维码已作废");
+					throw new Error("too many wrong pairing codes; the QR code expired");
 				case "expired":
 					expired = true;
 					log?.info("二维码已过期，重新获取");
@@ -236,10 +236,10 @@ export async function login({
 						log?.info("扫码的 Bot 已绑定本机，复用现有凭证");
 						return existing;
 					}
-					throw new Error("扫码的 Bot 已绑定其他客户端，但本机没有可用凭证");
+					throw new Error("this bot is bound to another client and no local credentials are available");
 				}
 				case "confirmed": {
-					if (!status.bot_token) throw new Error("登录成功但没有返回 bot_token");
+					if (!status.bot_token) throw new Error("login succeeded but no bot_token was returned");
 					const credentials = {
 						token: status.bot_token,
 						botId: status.ilink_bot_id ?? "",
@@ -269,5 +269,5 @@ export async function login({
 			}
 		}
 	}
-	throw new Error("二维码多次过期，登录未完成");
+	throw new Error("the QR code expired repeatedly; login did not finish");
 }

package/src/config.js

@@ -36,7 +36,7 @@ export const DEFAULT_CONFIG = Object.freeze({
 	sessionWindowHours: 24, // context_token 有效期
 	typing: true,
 	maxQueue: 20,
-	emptyReply: "（Pi 这轮没有返回文字）",
+	emptyReply: "(pi returned no text this round)",
 	dedupeTtlMs: 10 * 60 * 1000,
 	lock: true,
 	// standalone：微信跑独立后台进程/会话（默认，避免陷进“共享会话”的坑）
@@ -77,11 +77,11 @@ export function loadConfig() {
 		try {
 			raw = JSON.parse(fs.readFileSync(file, "utf8"));
 			if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
-				error = "配置不是 JSON 对象";
+				error = "config is not a JSON object";
 				raw = {};
 			}
 		} catch (err) {
-			error = `配置解析失败：${err?.message ?? err}`;
+			error = `could not parse config: ${err?.message ?? err}`;
 			raw = {};
 		}
 	}

package/src/i18n.js

@@ -0,0 +1,29 @@
+/** English notice codes for pi-weixin-connect: every warning/error carries a stable [CODE] prefix. */
+export const CODE = {
+	CONFIG: "WX_E_CONFIG",
+	NOT_LOGGED_IN: "WX_E_NOT_LOGGED_IN",
+	SERVICE_STALE: "WX_E_SERVICE_STALE",
+	SERVICE_START_FAILED: "WX_E_SERVICE_START_FAILED",
+	LOCK_HELD: "WX_E_LOCK_HELD",
+	LOCK_TAKEN: "WX_E_LOCK_TAKEN",
+	LOGIN_EXPIRED: "WX_E_LOGIN_EXPIRED",
+	START_FAILED: "WX_E_START_FAILED",
+	QR_BUSY: "WX_E_QR_BUSY",
+	STOP_OLD_FAILED: "WX_E_STOP_OLD_FAILED",
+	LOGIN_NO_USERID: "WX_E_LOGIN_NO_USERID",
+	GATEWAY_NOT_STARTED: "WX_E_GATEWAY_NOT_STARTED",
+	LOGIN_FAILED: "WX_E_LOGIN_FAILED",
+	STOP_FAILED: "WX_E_STOP_FAILED",
+	LOGOUT_BLOCKED: "WX_E_LOGOUT_BLOCKED",
+	REPLY_FAILED: "WX_E_REPLY_FAILED",
+	BRIDGE_PAUSED: "WX_E_BRIDGE_PAUSED",
+	WINDOW_EXPIRED: "WX_E_WINDOW_EXPIRED",
+	NEW_SESSION_FAILED: "WX_E_NEW_SESSION_FAILED",
+	TUI_ONLY: "WX_E_TUI_ONLY",
+};
+
+/** `[CODE] text: detail` — detail is optional. */
+export function err(code, text, detail) {
+	const body = detail === undefined || detail === null || detail === "" ? text : `${text}: ${detail}`;
+	return `[${code}] ${body}`;
+}

package/src/index.js

@@ -35,6 +35,7 @@ import {
 	stopService,
 } from "./service.js";
 import { maskId } from "./text.js";
+import { CODE, err } from "./i18n.js";
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const SERVICE_BIN = path.resolve(HERE, "..", "bin", "pi-weixin-connect.mjs");
@@ -62,16 +63,16 @@ function lockFilePath() {
 }
 
 const STATE_LABEL = {
-	idle: "未启动",
-	connecting: "连接中",
-	connected: "在线",
-	disconnected: "重连中",
-	expired: "会话过期",
-	error: "出错",
-	stopped: "已停止",
-	disabled: "已关闭",
-	unconfigured: "未登录",
-	locked: "被占用",
+	idle: "not started",
+	connecting: "connecting",
+	connected: "online",
+	disconnected: "reconnecting",
+	expired: "session expired",
+	error: "error",
+	stopped: "stopped",
+	disabled: "disabled",
+	unconfigured: "not logged in",
+	locked: "locked",
 };
 
 const RUNTIME_KEY = Symbol.for("pi-weixin-connect.runtime.v1");
@@ -94,6 +95,7 @@ function newRuntime() {
 		lockWatch: undefined,
 		lastInbound: undefined,
 		loginInFlight: false,
+		pendingExec: undefined,
 	};
 }
 
@@ -116,7 +118,7 @@ export default function createExtension(pi) {
 	seen.add(pi);
 
 	function setStatus(label, detail) {
-		const text = detail ? `微信: ${label} · ${detail}` : `微信: ${label}`;
+		const text = detail ? `wx: ${label} · ${detail}` : `wx: ${label}`;
 		try {
 			state.ctx?.ui?.setStatus?.("weixin", text);
 		} catch {
@@ -124,8 +126,10 @@ export default function createExtension(pi) {
 		}
 	}
 
-	function notify(message, level = "info") {
+	function notify(message, level = "info", { silent = false } = {}) {
 		state.logger?.[level === "warning" ? "warn" : level === "error" ? "error" : "info"](message);
+		// startup / background status notices stay in the log only
+		if (silent) return;
 		try {
 			state.ctx?.ui?.notify?.(message, level);
 		} catch {
@@ -133,7 +137,120 @@ export default function createExtension(pi) {
 		}
 	}
 
+	/** 开新会话：失败只提示，不打断当前会话；返回值给聊天侧回执用。 */
+	async function switchSession(ctx, name = "") {
+		const label = String(name ?? "").trim();
+		try {
+			const result = await ctx.newSession({
+				setup: async (sessionManager) => {
+					if (label) sessionManager.appendSessionInfo(label);
+				},
+				withSession: (next) => {
+					state.ctx = next;
+				},
+			});
+			if (result?.cancelled) return { ok: false, cancelled: true, message: "cancelled" };
+			return { ok: true };
+		} catch (err) {
+			if (isStaleContextError(err)) {
+				return { ok: false, message: "this session was replaced by another switch" };
+			}
+			return { ok: false, message: err?.message ?? String(err) };
+		}
+	}
+
+	/** 聊天侧开新会话：借 /wx __new 这条扩展命令走 ctx.newSession（ctx 只在命令里有）。 */
+	function requestNewSession(args = "") {
+		if (state.pendingExec) {
+			return Promise.resolve({ ok: false, message: "a new-session request is already in progress" });
+		}
+		return new Promise((resolve) => {
+			let settled = false;
+			const done = (result) => {
+				if (settled) return;
+				settled = true;
+				clearTimeout(timer);
+				const owner = state.pendingExec?.done === done;
+				const pending = state.pendingExec;
+				if (owner) state.pendingExec = undefined;
+				// 切换失败且没真的开始换会话：立刻解除暂停，别让队列停摆 30 秒
+				if (!result?.ok && owner && !pending?.sawShutdown) state.bridge?.cancelSwitch();
+				resolve(result);
+			};
+			const timer = setTimeout(() => done({ ok: false, message: "pi did not switch sessions within 35s" }), 35_000);
+			timer.unref?.();
+			state.pendingExec = { done };
+			state.bridge?.beginSwitch();
+			try {
+				state.pi.sendUserMessage(args ? `/wx __new ${args}` : "/wx __new", { expandPromptTemplates: true });
+			} catch (err) {
+				done({ ok: false, message: err?.message ?? String(err) });
+			}
+		});
+	}
+
+	const BUILTIN_COMMANDS = new Set([
+		"settings",
+		"model",
+		"tree",
+		"thinking",
+		"scoped-models",
+		"export",
+		"import",
+		"share",
+		"bug",
+		"copy",
+		"name",
+		"session",
+		"changelog",
+		"hotkeys",
+		"fork",
+		"clone",
+		"trust",
+		"login",
+		"logout",
+		"new",
+		"compact",
+		"resume",
+		"reload",
+		"quit",
+		"help",
+		"tools",
+	]);
+
+	function isKnownCommand(name) {
+		if (BUILTIN_COMMANDS.has(name)) return true;
+		try {
+			return (state.pi?.getCommands?.() ?? []).some((item) => String(item.name).toLowerCase() === name);
+		} catch {
+			return false;
+		}
+	}
+
+	/** 聊天窗口里的斜杠命令：只映射 /new，其余一律提示回终端。 */
+	async function handleChatCommand(command) {
+		switch (command.name) {
+			case "new": {
+				const result = await requestNewSession(command.args);
+				if (result?.cancelled) return err(CODE.NEW_SESSION_FAILED, "new session cancelled");
+				if (!result?.ok) {
+					return err(CODE.NEW_SESSION_FAILED, "could not open a new session", result?.message ?? "unknown reason");
+				}
+				return command.args ? `new session started (${command.args})` : "new session started";
+			}
+			default:
+				// 只有真正存在的命令才拒绝；`/tmp`、`/var 为什么…` 这类当普通消息
+				if (!isKnownCommand(command.name)) return null;
+				return err(CODE.TUI_ONLY, `/${command.raw ?? command.name} runs in the terminal; only /new works here`);
+		}
+	}
+
+
 	function stop({ release = true } = {}) {
+		if (state.pendingExec) {
+			state.pendingExec.done({ ok: false, message: "background service stopped" });
+			state.pendingExec = undefined;
+		}
 		if (state.lockWatch) {
 			clearInterval(state.lockWatch);
 			state.lockWatch = undefined;
@@ -149,7 +266,7 @@ export default function createExtension(pi) {
 		if (release && state.config?.lock !== false) releaseLock(lockFilePath());
 	}
 
-	async function start(ctx, { quietService = false } = {}) {
+	async function start(ctx) {
 		if (state.starting) return;
 		state.starting = true;
 		state.ctx = ctx ?? state.ctx;
@@ -170,7 +287,7 @@ export default function createExtension(pi) {
 			if (error) {
 				state.error = error;
 				setStatus(STATE_LABEL.error, error);
-				notify(`pi-weixin-connect: ${error}`, "warning");
+				notify(err(CODE.CONFIG, "config error", error), "warning");
 				// 之前可能是 inline 轮询进程：不再连长轮询时必须把锁还回去
 				stop({ release: true });
 				return;
@@ -186,7 +303,7 @@ export default function createExtension(pi) {
 			state.credentials = credentials;
 			if (!credentials) {
 				setStatus(STATE_LABEL.unconfigured);
-				notify("pi-weixin-connect: 还没有登录。在终端运行 /wx login 扫码。", "info");
+				notify(err(CODE.NOT_LOGGED_IN, "not logged in; run /wx login in the terminal"), "warning");
 				stop({ release: true });
 				return;
 			}
@@ -200,17 +317,15 @@ export default function createExtension(pi) {
 			if (!selfService && config.service.mode !== "inline") {
 				if (svcAlive) {
 					stop({ release: true });
-					setStatus("服务在线", `pid ${svc.pid}`);
-					if (!quietService) {
-						notify(`微信后台服务在线（pid ${svc.pid}），本进程不连长轮询；用 /wx status 查看`, "info");
-					}
+					setStatus("service online", `pid ${svc.pid}`);
+					notify(`background service online (pid ${svc.pid}); this process does not poll; see /wx status`, "info", { silent: true });
 					return;
 				}
 				if (svcProcessAlive) {
 					// 进程还在但心跳停了：再拉一个只会抢锁/双开，交给用户明确处理
-					state.error = `后台服务进程（pid ${svc.pid}）还在，但心跳已停；用 /wx stop --force 后重试`;
+					state.error = `background service pid ${svc.pid} is alive but its heartbeat stopped`;
 					setStatus(STATE_LABEL.error, state.error);
-					if (!quietService) notify(`pi-weixin-connect: ${state.error}`, "warning");
+					notify(err(CODE.SERVICE_STALE, "background service heartbeat stopped", `pid ${svc.pid}; run /wx stop --force then retry`), "warning");
 					stop({ release: true });
 					return;
 				}
@@ -223,13 +338,13 @@ export default function createExtension(pi) {
 					sessionId: config.service.sessionId,
 				});
 				if (!started.pid) {
-					state.error = started.error ?? "无法启动后台服务";
+					state.error = started.error ?? "could not start background service";
 					setStatus(STATE_LABEL.error, state.error);
-					notify(`微信后台服务启动失败：${state.error}\n日志：${started.logFile}`, "warning");
+					notify(err(CODE.SERVICE_START_FAILED, "could not start background service", `${state.error} (log: ${started.logFile})`), "warning");
 					return;
 				}
-				setStatus("服务启动中", `pid ${started.pid}`);
-				notify(`已自动启动微信后台服务（pid ${started.pid}）；日志：${started.logFile}`, "info");
+				setStatus("service starting", `pid ${started.pid}`);
+				notify(`background service started automatically (pid ${started.pid}); log: ${started.logFile}`, "info", { silent: true });
 				return;
 			}
 
@@ -249,16 +364,16 @@ export default function createExtension(pi) {
 					lock = acquireLock(lockFilePath());
 				}
 				if (!lock.ok) {
-					state.error = `长轮询已被另一个 Pi 进程持有（pid ${lock.holder?.pid}）`;
+					state.error = `long-polling lock held by another Pi process (pid ${lock.holder?.pid})`;
 					setStatus(STATE_LABEL.locked, `pid ${lock.holder?.pid}`);
-					notify(`pi-weixin-connect: ${state.error}。关掉那个进程后再试。`, "warning");
+					notify(err(CODE.LOCK_HELD, "long-polling lock held by another Pi process", `pid ${lock.holder?.pid}; close it and retry`), "warning");
 					return;
 				}
-				if (lock.takenOver) notify("pi-weixin-connect: 已接管长轮询锁", "info");
+				if (lock.takenOver) notify("took over the long-polling lock", "info", { silent: true });
 				state.lockWatch = setInterval(() => {
 					const holder = readLock(lockFilePath());
 					if (holder && holder.pid !== process.pid && isProcessAlive(holder.pid)) {
-						notify(`微信长轮询已被 pid ${holder.pid} 接管，本进程断开`, "warning");
+						notify(err(CODE.LOCK_TAKEN, "long-polling taken over by another process", `pid ${holder.pid}; disconnecting`), "warning");
 						stop({ release: false });
 						setStatus(STATE_LABEL.locked, `pid ${holder.pid}`);
 					}
@@ -272,10 +387,11 @@ export default function createExtension(pi) {
 				config,
 				log: state.logger,
 				notify,
+				onCommand: (command) => handleChatCommand(command),
 				credentials,
 				onExpired: () => {
 					setStatus(STATE_LABEL.expired);
-					notify("微信登录已过期（-14）：运行 /wx login 重新扫码。", "warning");
+					notify(err(CODE.LOGIN_EXPIRED, "weixin login expired (-14); run /wx login to scan again"), "warning");
 				},
 			});
 			const gateway = new WeixinGateway({
@@ -294,7 +410,7 @@ export default function createExtension(pi) {
 				},
 				onExpired: () => {
 					setStatus(STATE_LABEL.expired);
-					notify("微信登录已过期（-14）：运行 /wx login 重新扫码。", "warning");
+					notify(err(CODE.LOGIN_EXPIRED, "weixin login expired (-14); run /wx login to scan again"), "warning");
 				},
 			});
 
@@ -307,11 +423,11 @@ export default function createExtension(pi) {
 				state.logger.error(`网关启动失败：${state.error}`);
 				setStatus(STATE_LABEL.error, state.error);
 			});
-		} catch (err) {
-			state.error = err?.message ?? String(err);
-			state.logger?.error(`启动失败：${err?.stack ?? err}`);
+		} catch (cause) {
+			state.error = cause?.message ?? String(cause);
+			state.logger?.error(`启动失败：${cause?.stack ?? cause}`);
 			setStatus(STATE_LABEL.error, state.error);
-			notify(`pi-weixin-connect 启动失败：${state.error}`, "warning");
+			notify(err(CODE.START_FAILED, "pi-weixin-connect failed to start", state.error), "warning");
 			// 启动到一半抛异常时不要留着锁
 			stop({ release: true });
 		} finally {
@@ -323,34 +439,44 @@ export default function createExtension(pi) {
 		const cfg = state.config;
 		const cred = loadCredentials() ?? state.credentials;
 		const lines = [];
-		lines.push(`配置：${configPath()}${cfg ? "" : "（未加载）"}`);
-		lines.push(`凭证：${credentialsPath()}${cred ? "（已登录）" : "（未登录）"}`);
-		if (state.error) lines.push(`错误：${state.error}`);
+		lines.push(`config: ${configPath()}${cfg ? "" : " (not loaded)"}`);
+		lines.push(`credentials: ${credentialsPath()}${cred ? " (logged in)" : " (not logged in)"}`);
+		if (state.error) lines.push(`error: ${state.error}`);
 		if (!cfg) return lines.join("\n");
-		if (cred) lines.push(`Bot：${maskId(cred.botId)} · 用户 ${maskId(cred.userId)}`);
+		if (cred) lines.push(`bot: ${maskId(cred.botId)} · user ${maskId(cred.userId)}`);
 		const gw = state.gateway;
 		const svcForPoll = liveService();
 		lines.push(
-			`长轮询：${gw ? STATE_LABEL[gw.state] ?? gw.state : svcForPoll ? `由后台服务承载（pid ${svcForPoll.pid}）` : "未启动"}`,
+			`long polling: ${gw ? STATE_LABEL[gw.state] ?? gw.state : svcForPoll ? `served by background service (pid ${svcForPoll.pid})` : "not running"}`,
 		);
-		lines.push(`权限：用户白名单 ${cfg.allowUsers.length} 个${cfg.allowUsers.length === 0 ? "（仅登录者本人）" : ""}`);
+		lines.push(`acl: users ${cfg.allowUsers.length}${cfg.allowUsers.length === 0 ? " (only the logged-in user)" : ""}`);
 		const lock = readLock(lockFilePath());
-		lines.push(`锁：${lock ? `pid ${lock.pid}（${lock.at}）` : "无"}`);
-		lines.push(`后台服务：${describeService(readServiceState(serviceStatePath(baseDir())))}（模式 ${cfg.service.mode}）`);
+		lines.push(`lock: ${lock ? `pid ${lock.pid} (${lock.at})` : "none"}`);
+		lines.push(`service: ${describeService(readServiceState(serviceStatePath(baseDir())))} (mode ${cfg.service.mode})`);
 		if (state.bridge) {
 			const s = state.bridge.status;
-			const flags = [s.busy ? "Pi 忙" : "", s.switching ? "切换中" : "", s.stale ? "已暂停" : ""].filter(Boolean).join(" · ");
+			const flags = [s.busy ? "pi busy" : "", s.switching ? "switching" : "", s.stale ? "paused" : ""].filter(Boolean).join(" · ");
 			lines.push(
-				`队列：${s.queue} 条 · 已收 ${s.stats.received} / 已发 ${s.stats.sent} / 失败 ${s.stats.failed} / 忽略 ${s.stats.ignored}${flags ? ` · ${flags}` : ""}`,
+				`queue: ${s.queue} · received ${s.stats.received} / sent ${s.stats.sent} / failed ${s.stats.failed} / ignored ${s.stats.ignored}${flags ? ` · ${flags}` : ""}`,
 			);
 		}
-		if (state.lastInbound) lines.push(`最近入站：${state.lastInbound.at} · 用户 ${state.lastInbound.user} · ${state.lastInbound.len} 字`);
-		lines.push(`预算：每条消息最多 ${cfg.maxChunks} 段 × ${cfg.chunkChars} 字 · 窗口 ${cfg.sessionWindowHours}h`);
+		if (state.lastInbound) lines.push(`last inbound: ${state.lastInbound.at} · user ${state.lastInbound.user} · ${state.lastInbound.len} chars`);
+		lines.push(`budget: up to ${cfg.maxChunks} chunks × ${cfg.chunkChars} chars per message · window ${cfg.sessionWindowHours}h`);
 		try {
-			const model = state.ctx?.model ?? state.pi?.model;
-			if (model) lines.push(`模型：${model.provider ?? "?"}/${model.id ?? model.modelId ?? "?"}`);
 			const sessionId = state.ctx?.sessionManager?.getSessionId?.();
-			if (sessionId) lines.push(`Pi 会话：${sessionId}`);
+			if (sessionId) lines.push(`pi session: ${sessionId}`);
+			const model = state.ctx?.model ?? state.pi?.model;
+			if (model) lines.push(`model: ${model.provider ?? "?"}/${model.id ?? model.modelId ?? "?"}`);
+			lines.push(`thinking: ${state.pi?.getThinkingLevel?.() ?? "unknown"}`);
+			const usage = state.ctx?.getContextUsage?.();
+			if (usage) {
+				const tokens = usage.tokens ?? usage.usedTokens;
+				const window = usage.contextWindow ?? usage.maxTokens;
+				const percent = Number.isFinite(usage.percent) ? ` (${Math.round(usage.percent)}%)` : "";
+				lines.push(`context: ${tokens ?? "?"} / ${window ?? "?"}${percent}`);
+			}
+			const tools = state.pi?.getActiveTools?.() ?? [];
+			if (tools.length) lines.push(`tools: ${tools.length}`);
 		} catch {
 			// ignore
 		}
@@ -360,7 +486,7 @@ export default function createExtension(pi) {
 	/** 扫码登录：二维码落盘 + 提示路径；配对码优先用 TUI 输入。 */
 	async function doLogin(ctx, { force = false } = {}) {
 		if (state.loginInFlight) {
-			notify("上一次扫码还没结束，稍等", "warning");
+			notify(err(CODE.QR_BUSY, "previous QR login is still running; wait a moment"), "warning");
 			return;
 		}
 		state.loginInFlight = true;
@@ -378,15 +504,15 @@ export default function createExtension(pi) {
 				log: logger,
 			});
 			backup = force ? backupCredentials() : null;
-			notify("正在获取微信登录二维码…", "info");
+			notify("fetching weixin login QR code...", "info");
 			let qrShown = false;
 			const credentials = await qrLogin({
 				api,
 				log: logger,
 				onQr: (qr) => {
 					qrShown = true;
-					const where = qr.pngPath ? `二维码已保存：${qr.pngPath}` : `二维码内容：${qr.content}`;
-					notify(`${where}\n用微信扫码并确认。`, "info");
+					const where = qr.pngPath ? `QR saved: ${qr.pngPath}` : `QR content: ${qr.content}`;
+					notify(`${where}\nscan it with WeChat and confirm.`, "info");
 					if (qr.ansi) logger.debug(`已生成终端二维码（${qr.ansi.split("\n").length} 行），不写入日志`);
 				},
 				onStatus: (text) => logger.info(text),
@@ -400,7 +526,7 @@ export default function createExtension(pi) {
 								timer.unref?.();
 							});
 							try {
-								return await Promise.race([ctx.ui.input("请输入手机微信上显示的配对码"), timeout]);
+								return await Promise.race([ctx.ui.input("Enter the pairing code shown on WeChat"), timeout]);
 							} finally {
 								clearTimeout(timer);
 							}
@@ -413,7 +539,7 @@ export default function createExtension(pi) {
 			});
 			loggedIn = true;
 			state.error = null;
-			notify(`微信登录成功：用户 ${maskId(credentials.userId)}`, "info");
+			notify(`weixin login ok: user ${maskId(credentials.userId)}`, "info");
 			state.credentials = credentials;
 			const svc = readServiceState(serviceStatePath(baseDir()));
 			if (config.service.mode !== "inline") {
@@ -426,7 +552,7 @@ export default function createExtension(pi) {
 						removeServiceState(serviceStatePath(baseDir()), svc.pid);
 					} else {
 						oldServiceStopped = false;
-						notify(`旧后台服务未能停止（${stopped.reason}），本次登录不会重启服务`, "warning");
+						notify(err(CODE.STOP_OLD_FAILED, "previous background service did not stop; login will not restart it", stopped.reason), "warning");
 					}
 				}
 				// 无论旧服务是否停掉，控制面自己都不能再拿旧凭证轮询
@@ -440,8 +566,8 @@ export default function createExtension(pi) {
 					});
 					notify(
 						started.pid
-							? `凭证已更新，微信独立服务已启动（pid ${started.pid}）`
-							: `凭证已更新，但服务启动失败：${started.error ?? "未知原因"}`,
+							? `credentials updated; background service started (pid ${started.pid})`
+							: err(CODE.SERVICE_START_FAILED, "credentials updated but service did not start", started.error ?? "unknown reason"),
 						started.pid ? "info" : "warning",
 					);
 				}
@@ -451,16 +577,16 @@ export default function createExtension(pi) {
 			}
 			dropCredentialsBackup(backup);
 			if (!credentials.userId) {
-				notify("登录成功，但服务端没有返回用户 ID：默认白名单会拒绝所有消息。请重试 /wx login。", "warning");
+				notify(err(CODE.LOGIN_NO_USERID, "login ok but the server returned no user id; the default allowlist rejects all messages, retry /wx login"), "warning");
 			}
 			if (config.service.mode === "inline" && qrShown && !state.gateway)
-				notify("登录成功，但网关没有启动，查看 /wx status 或日志", "warning");
-		} catch (err) {
+				notify(err(CODE.GATEWAY_NOT_STARTED, "login ok but the gateway did not start; see /wx status or the log"), "warning");
+		} catch (cause) {
 			// 只有扫码本身失败才回滚旧凭证；登录已成功、只是网关没起来时保留新凭证
 			if (!loggedIn) restoreCredentials(backup);
 			else dropCredentialsBackup(backup);
-			loggerSafeError(err);
-			notify(`扫码登录失败：${err?.message ?? err}`, "warning");
+			loggerSafeError(cause);
+			notify(err(CODE.LOGIN_FAILED, "QR login failed", cause?.message ?? cause), "warning");
 		} finally {
 			state.loginInFlight = false;
 		}
@@ -479,12 +605,12 @@ export default function createExtension(pi) {
 		const file = serviceStatePath(baseDir());
 		const svc = readServiceState(file);
 		if (svc && isServiceAlive(svc)) {
-			notify(`后台服务已在运行：${describeService(svc)}`, "info");
+			notify(`background service already running: ${describeService(svc)}`, "info");
 			return;
 		}
 		if (svc && isProcessAlive(svc.pid)) {
 			// 进程活着、心跳过期：不要双开，让用户先显式停掉
-			notify(`后台服务进程还在（pid ${svc.pid}），但心跳已停；先 /wx stop --force 再启动`, "warning");
+			notify(err(CODE.SERVICE_STALE, "background service heartbeat stopped", `pid ${svc.pid}; run /wx stop --force then start again`), "warning");
 			return;
 		}
 		if (svc) removeServiceState(file, svc.pid);
@@ -492,7 +618,7 @@ export default function createExtension(pi) {
 		const credentials = loadCredentials();
 		if (credentials) state.credentials = credentials;
 		if (!state.credentials) {
-			notify("还没有登录，先 /wx login 扫码", "warning");
+			notify(err(CODE.NOT_LOGGED_IN, "not logged in; run /wx login first"), "warning");
 			return;
 		}
 		const cwd = state.ctx?.cwd ?? os.homedir();
@@ -503,7 +629,7 @@ export default function createExtension(pi) {
 			sessionId: state.config?.service?.sessionId ?? "pi-weixin-connect-service",
 		});
 		if (!started.pid) {
-			notify(`后台服务启动失败：${started.error ?? "没有拿到 pid"}\n日志：${started.logFile}`, "warning");
+			notify(err(CODE.SERVICE_START_FAILED, "could not start background service", `${started.error ?? "no pid"} (log: ${started.logFile})`), "warning");
 			return;
 		}
 		let current = readServiceState(file);
@@ -514,10 +640,10 @@ export default function createExtension(pi) {
 		if (current && isServiceAlive(current)) {
 			// 服务接管长轮询：本进程让出
 			stop({ release: true });
-			setStatus("服务在线", `pid ${current.pid}`);
-			notify(`微信后台服务已启动：${describeService(current)}\n日志：${started.logFile}`, "info");
+			setStatus("service online", `pid ${current.pid}`);
+			notify(`weixin background service started: ${describeService(current)}\nlog: ${started.logFile}`, "info");
 		} else {
-			notify(`后台服务启动中（pid ${started.pid}），稍后 /wx status 查看。日志：${started.logFile}`, "warning");
+			notify(`background service starting (pid ${started.pid}); check /wx status later; log: ${started.logFile}`, "info");
 		}
 	}
 
@@ -528,30 +654,31 @@ export default function createExtension(pi) {
 		if (svc && isProcessAlive(svc.pid)) {
 			const result = await stopService(svc, { force });
 			if (!result.stopped) {
-				notify(`停止失败：${result.reason}`, "warning");
+				notify(err(CODE.STOP_FAILED, "stop failed", result.reason), "warning");
 				return;
 			}
 			removeServiceState(file, svc.pid);
 			setStatus(STATE_LABEL.stopped);
-			notify("微信后台服务已停止", "info");
+			notify("weixin background service stopped", "info");
 			return;
 		}
 		if (svc) removeServiceState(file, svc.pid);
 		stop({ release: true });
-		notify("已断开本进程的微信连接", "info");
+		notify("disconnected this process from weixin", "info");
 		setStatus(STATE_LABEL.stopped);
 	}
 
 	const HELP = [
-		"用法：/wx <命令>",
-		"  status        查看登录、长轮询、队列、预算",
-		"  login [--force]  扫码登录（首次或 -14 过期后）",
-		"  start         启动独立后台服务（微信走单独进程）",
-		"  stop [--force] 停止后台服务；没有服务时断开本进程",
-		"  logout        删除本机凭证并断开",
-		"  log [n]       看最近 n 条日志（默认 20）",
+		"usage: /wx <command>",
+		"  status          service, connection, queue, budget",
+		"  start           start the background service",
+		"  stop [--force]  stop the service; disconnects this process when none runs",
+		"  log [n]         show the last n log lines (default 20)",
+		"  help            this list",
+		"  login [--force] QR login (first time or after -14)",
+		"  logout          delete local credentials and disconnect",
 		"",
-		"微信里可直接用终端命令：/new /model /thinking /compact /session /name /tools /help（P1 接入）。",
+		"In chat: only /new works; every other command runs in the terminal.",
 	].join("\n");
 
 	let commandsRegistered = false;
@@ -559,7 +686,7 @@ export default function createExtension(pi) {
 		if (commandsRegistered) return;
 		commandsRegistered = true;
 		pi.registerCommand("wx", {
-			description: "微信 ClawBot：status / login / logout / log",
+			description: "WeChat ClawBot: status / login / logout / log",
 			handler: async (args, ctx) => {
 				state.ctx = ctx;
 				const [sub, ...rest] = String(args ?? "").trim().split(/\s+/);
@@ -567,6 +694,16 @@ export default function createExtension(pi) {
 					case "status":
 						notify(statusReport(), "info");
 						return;
+					case "__new": {
+						const pending = state.pendingExec;
+						if (!pending) {
+							notify(err(CODE.NEW_SESSION_FAILED, "no pending new-session request"), "warning");
+							return;
+						}
+						const result = await switchSession(ctx, rest.join(" "));
+						pending.done(result);
+						return;
+					}
 					case "login":
 						await doLogin(ctx, { force: rest.includes("--force") });
 						return;
@@ -582,7 +719,7 @@ export default function createExtension(pi) {
 						if (svc && isProcessAlive(svc.pid)) {
 							const stopped = await stopService(svc, { force: true });
 							if (!stopped.stopped) {
-								notify(`无法停止后台服务（${stopped.reason}），登出已取消；先 /wx stop --force`, "warning");
+								notify(err(CODE.LOGOUT_BLOCKED, "cannot stop background service; logout cancelled, run /wx stop --force first", stopped.reason), "warning");
 								return;
 							}
 						}
@@ -591,13 +728,13 @@ export default function createExtension(pi) {
 						stop({ release: true });
 						clearCredentials();
 						state.credentials = undefined;
-						notify("已删除微信凭证并断开连接", "info");
+						notify("weixin credentials deleted; connection closed", "info");
 						setStatus(STATE_LABEL.unconfigured);
 						return;
 					}
 					case "log": {
 						const n = Number(rest[0]) > 0 ? Math.min(Number(rest[0]), 200) : 20;
-						notify(state.logger?.tail(n)?.join("\n") ?? "（没有日志）", "info");
+						notify(state.logger?.tail(n)?.join("\n") ?? "(no log)", "info");
 						return;
 					}
 					default:
@@ -625,11 +762,12 @@ export default function createExtension(pi) {
 			if (svc && (state.config?.service?.mode ?? "standalone") !== "inline") {
 				// 独立服务在跑：控制面每次 /new 都不该再拉起一遍，也不该报“正在重建”；
 				// 但仍然要跑 start() 把配置/凭证读进来，后台服务状态才算完整。
-				setStatus("服务在线", `pid ${svc.pid}`);
-				void start(ctx, { quietService: true });
+				setStatus("service online", `pid ${svc.pid}`);
+				void start(ctx);
 				return;
 			}
-			if (reason !== "startup") notify(`会话已切换（${reason}），没有活动桥，正在重建微信连接…`, "warning");
+			if (reason !== "startup")
+				notify(`session switched (${reason}); rebuilding weixin connection...`, "info", { silent: true });
 			void start(ctx);
 			return;
 		}
@@ -649,6 +787,7 @@ export default function createExtension(pi) {
 			return;
 		}
 		state.ownerStale = true;
+		if (state.pendingExec) state.pendingExec.sawShutdown = true;
 		state.bridge?.beginSwitch();
 	});
 

package/src/lock.js

@@ -41,7 +41,7 @@ export function acquireLock(file, { force = false, pid = process.pid } = {}) {
 			fs.linkSync(tmp, file);
 			return { ok: true, takenOver: false };
 		} catch (err) {
-			if (err?.code !== "EEXIST") return { ok: false, error: "无法写入锁文件" };
+			if (err?.code !== "EEXIST") return { ok: false, error: "could not write the lock file" };
 			const current = readLock(file);
 			if (current && current.pid !== pid && isProcessAlive(current.pid) && !force) {
 				return { ok: false, holder: current };
@@ -50,7 +50,7 @@ export function acquireLock(file, { force = false, pid = process.pid } = {}) {
 			return { ok: true, takenOver: Boolean(holder && holder.pid !== pid && force) };
 		}
 	} catch (err) {
-		return { ok: false, error: err?.message ?? "无法写入锁文件" };
+		return { ok: false, error: err?.message ?? "could not write the lock file" };
 	} finally {
 		try {
 			fs.unlinkSync(tmp);

package/src/media.js

@@ -125,17 +125,17 @@ function isDenied(filePath, allowDirs) {
 /** 校验出站文件；返回 {ok, size, kind, reason}。 */
 export function inspectFile(filePath, { maxBytes = CDN_MAX_BYTES, allowDirs = [] } = {}) {
 	const resolved = realPath(String(filePath ?? ""));
-	if (isDenied(resolved, allowDirs)) return { ok: false, reason: "敏感路径，拒绝发送", path: resolved };
+	if (isDenied(resolved, allowDirs)) return { ok: false, reason: "path is not allowed", path: resolved };
 	let stat;
 	try {
 		stat = fs.statSync(resolved);
 	} catch {
-		return { ok: false, reason: "文件不存在", path: resolved };
+		return { ok: false, reason: "file not found", path: resolved };
 	}
-	if (!stat.isFile()) return { ok: false, reason: "不是普通文件", path: resolved };
+	if (!stat.isFile()) return { ok: false, reason: "not a regular file", path: resolved };
 	const { mediaType, kind, maxBytes: limit } = mediaKindForFile(resolved);
 	const cap = Math.min(maxBytes, limit);
-	if (stat.size > cap) return { ok: false, reason: `超过上限 ${Math.round(cap / 1048576)}MB`, path: resolved };
+	if (stat.size > cap) return { ok: false, reason: `exceeds the ${Math.round(cap / 1048576)}MB limit`, path: resolved };
 	return { ok: true, size: stat.size, kind, mediaType, path: resolved, name: path.basename(resolved) };
 }
 
@@ -155,7 +155,7 @@ export function parseFileMarkers(text, { maxCount = 3, maxBytes = CDN_MAX_BYTES,
 			return "";
 		}
 		if (files.length + skipped.length >= maxCount + 5) {
-			skipped.push({ path: filePath, reason: "标记太多" });
+			skipped.push({ path: filePath, reason: "too many file markers" });
 			return "";
 		}
 		const check = inspectFile(filePath, { maxBytes, allowDirs });
@@ -164,14 +164,14 @@ export function parseFileMarkers(text, { maxCount = 3, maxBytes = CDN_MAX_BYTES,
 			return "";
 		}
 		if (files.length >= maxCount) {
-			skipped.push({ path: filePath, reason: `最多 ${maxCount} 个` });
+			skipped.push({ path: filePath, reason: `at most ${maxCount} files` });
 			return "";
 		}
 		files.push({ path: check.path, name: check.name, kind: check.kind, mediaType: check.mediaType, size: check.size });
 		return "";
 	});
 	if (disabled && disabledCount > 0) {
-		skipped.push({ path: "", reason: "文件发送已关闭", count: disabledCount });
+		skipped.push({ path: "", reason: "file sending is disabled", count: disabledCount });
 	}
 	return { text: kept.trim(), files, skipped };
 }
@@ -181,7 +181,7 @@ function uploadUrl(uploadFullUrl, uploadParam, filekey, cdnBaseUrl) {
 	if (uploadParam) {
 		return `${cdnBaseUrl}/upload?encrypted_query_param=${encodeURIComponent(uploadParam)}&filekey=${encodeURIComponent(filekey)}`;
 	}
-	throw new Error("getuploadurl 没有返回上传地址");
+	throw new Error("getuploadurl returned no upload url");
 }
 
 /**
@@ -219,13 +219,13 @@ export async function uploadFile(api, token, { to, filePath, mediaType, cdnBaseU
 			});
 			if (res.status >= 400 && res.status < 500) {
 				const msg = res.headers.get("x-error-message") ?? `HTTP ${res.status}`;
-				throw new Error(`CDN 客户端错误 ${res.status}: ${msg}`);
+				throw new Error(`CDN client error ${res.status}: ${msg}`);
 			}
 			if (res.status !== 200) {
-				throw new Error(`CDN 服务端错误 HTTP ${res.status}`);
+				throw new Error(`CDN server error HTTP ${res.status}`);
 			}
 			const downloadParam = res.headers.get("x-encrypted-param");
-			if (!downloadParam) throw new Error("CDN 响应缺少 x-encrypted-param");
+			if (!downloadParam) throw new Error("CDN response is missing x-encrypted-param");
 			return {
 				media: {
 					encrypt_query_param: downloadParam,
@@ -238,30 +238,30 @@ export async function uploadFile(api, token, { to, filePath, mediaType, cdnBaseU
 			};
 		} catch (err) {
 			lastError = err;
-			if (/客户端错误/.test(String(err?.message))) break;
+			if (/^CDN client error /.test(String(err?.message))) break;
 			log?.warn(`CDN 上传失败 ${attempt}/3：${err?.message ?? err}`);
 			await new Promise((resolve) => setTimeout(resolve, 800 * attempt));
 		}
 	}
-	throw lastError ?? new Error("CDN 上传失败");
+	throw lastError ?? new Error("CDN upload failed");
 }
 
 /** 下载 CDN 媒体并解密；返回 Buffer。 */
 export async function downloadMedia({ media, itemAeskey, cdnBaseUrl, maxBytes = CDN_MAX_BYTES, requireKey = false }) {
-	if (!media?.full_url && !media?.encrypt_query_param) throw new Error("媒体缺少下载参数");
+	if (!media?.full_url && !media?.encrypt_query_param) throw new Error("media is missing download parameters");
 	const url =
 		media.full_url?.trim() ||
 		`${cdnBaseUrl}/download?encrypted_query_param=${encodeURIComponent(media.encrypt_query_param)}`;
 	const res = await fetch(url, { signal: AbortSignal.timeout(120_000) });
-	if (!res.ok) throw new Error(`媒体下载 HTTP ${res.status}`);
+	if (!res.ok) throw new Error(`media download HTTP ${res.status}`);
 	const declared = Number(res.headers.get("content-length"));
-	if (Number.isFinite(declared) && declared > maxBytes) throw new Error("媒体超过大小上限");
+	if (Number.isFinite(declared) && declared > maxBytes) throw new Error("media exceeds the size limit");
 	const ciphertext = Buffer.from(await res.arrayBuffer());
-	if (ciphertext.length > maxBytes) throw new Error("媒体超过大小上限");
+	if (ciphertext.length > maxBytes) throw new Error("media exceeds the size limit");
 
 	const key = parseAesKey(itemAeskey) ?? parseAesKey(media.aes_key);
 	if (!key) {
-		if (requireKey) throw new Error("媒体缺少解密密钥");
+		if (requireKey) throw new Error("media is missing its decryption key");
 		return ciphertext; // 明文图片
 	}
 	return decryptAesEcb(ciphertext, key);

package/src/service.js

@@ -67,20 +67,20 @@ export function isServiceAlive(state, { now = Date.now(), staleMs = HEARTBEAT_ST
 }
 
 export function describeService(state, { now = Date.now(), staleMs = HEARTBEAT_STALE_MS } = {}) {
-	if (!state) return "未运行";
+	if (!state) return "not running";
 	const alive = isProcessAlive(state.pid);
 	const fresh = isServiceAlive(state, { now, staleMs });
 	const parsed = Date.parse(state.heartbeatAt ?? "");
 	const beat = Number.isFinite(parsed) ? Math.round((now - parsed) / 1000) : null;
-	const detail = !alive ? "进程已退出" : fresh ? "在线" : beat === null ? "心跳时间未知" : `心跳停了 ${beat}s`;
-	return `pid ${state.pid} · ${detail} · 会话 ${state.sessionId ?? "?"}`;
+	const detail = !alive ? "process exited" : fresh ? "online" : beat === null ? "heartbeat time unknown" : `heartbeat stopped ${beat}s ago`;
+	return `pid ${state.pid} · ${detail} · session ${state.sessionId ?? "?"}`;
 }
 
 /** 拉起后台服务（detached，父进程退出后仍在）。 */
 export function startService({ binPath, baseDir, cwd, sessionId = "pi-weixin-connect-service", nodePath = process.execPath }) {
 	const logFile = serviceLogPath(baseDir);
-	if (!fs.existsSync(binPath)) return { pid: null, logFile, error: `找不到启动脚本：${binPath}` };
-	if (!fs.existsSync(cwd)) return { pid: null, logFile, error: `工作目录不存在：${cwd}` };
+	if (!fs.existsSync(binPath)) return { pid: null, logFile, error: `start script not found: ${binPath}` };
+	if (!fs.existsSync(cwd)) return { pid: null, logFile, error: `working directory does not exist: ${cwd}` };
 	fs.mkdirSync(path.dirname(logFile), { recursive: true });
 	try {
 		if (fs.statSync(logFile).size > 5 * 1024 * 1024) fs.renameSync(logFile, `${logFile}.1`);
@@ -134,10 +134,10 @@ function looksLikeService(pid) {
 export async function stopService(state, { timeoutMs = 10_000, intervalMs = 200, force = false } = {}) {
 	if (!state || !isProcessAlive(state.pid)) return { stopped: true, reason: "already-exited" };
 	if (!force && !isServiceAlive(state)) {
-		return { stopped: false, reason: `pid ${state.pid} 还活着但心跳已停，确认后用 /wx stop --force` };
+		return { stopped: false, reason: `pid ${state.pid} is alive but the heartbeat stopped; run /wx stop --force after confirming` };
 	}
 	if (force && !looksLikeService(state.pid)) {
-		return { stopped: false, reason: `pid ${state.pid} 看起来不是 pi-weixin-connect，拒绝强制结束` };
+		return { stopped: false, reason: `pid ${state.pid} does not look like pi-weixin-connect; refusing to force-kill` };
 	}
 	try {
 		process.kill(state.pid, "SIGTERM");
@@ -149,7 +149,7 @@ export async function stopService(state, { timeoutMs = 10_000, intervalMs = 200,
 		if (!isProcessAlive(state.pid)) return { stopped: true };
 		await new Promise((resolve) => setTimeout(resolve, intervalMs));
 	}
-	return { stopped: false, reason: `进程 ${state.pid} 在 ${timeoutMs}ms 内没有退出` };
+	return { stopped: false, reason: `process ${state.pid} did not exit within ${timeoutMs}ms` };
 }
 
 /** 当前进程是不是后台服务（launcher 注入 env，pi 的 ppid = launcher）。
@@ -184,7 +184,7 @@ export async function startManagedService({ binPath, baseDir, cwd, sessionId = "
 		const systemdError = res.error
 			? res.error.message
 			: res.status !== 0
-				? (res.stderr || res.stdout || `systemctl 退出码 ${res.status}`).trim()
+				? (res.stderr || res.stdout || `systemctl exited with ${res.status}`).trim()
 				: "";
 		if (!systemdError) {
 			usedSystemd = true;
@@ -192,7 +192,7 @@ export async function startManagedService({ binPath, baseDir, cwd, sessionId = "
 			// 容器 / 没有 user bus / 残留 unit：不要卡死在 systemd 上，退回 detached 启动
 			const started = startService({ binPath, baseDir, cwd, sessionId });
 			if (!started.pid) {
-				return { pid: null, logFile, systemd: false, error: `${systemdError}；回退启动失败：${started.error ?? "未知原因"}` };
+				return { pid: null, logFile, systemd: false, error: `${systemdError}; fallback start failed: ${started.error ?? "unknown reason"}` };
 			}
 		}
 	} else {
@@ -206,5 +206,5 @@ export async function startManagedService({ binPath, baseDir, cwd, sessionId = "
 		if (state && isServiceAlive(state)) return { pid: state.pid, logFile, systemd: usedSystemd };
 		await new Promise((resolve) => setTimeout(resolve, 200));
 	}
-	return { pid: null, logFile, systemd: usedSystemd, error: "服务没有在 8 秒内上线" };
+	return { pid: null, logFile, systemd: usedSystemd, error: "service did not come online within 8s" };
 }

package/src/session.js

@@ -17,11 +17,19 @@ import { randomInt } from "node:crypto";
 
 import { downloadMedia, parseFileMarkers, sniffImageMime, uploadFile } from "./media.js";
 import { buildPrompt, chunkText, isAllowed, maskId, stripMarkdown } from "./text.js";
+import { CODE, err } from "./i18n.js";
 
 export function isStaleContextError(err) {
 	return /stale after session replacement or reload/i.test(String(err?.message ?? err ?? ""));
 }
 
+function parseChatCommand(text) {
+	const trimmed = String(text ?? "").trim();
+	const match = /^\/([^\s]+)(?:\s+([\s\S]*))?$/.exec(trimmed);
+	if (!match) return null;
+	return { name: match[1].toLowerCase(), raw: match[1], args: (match[2] ?? "").trim() };
+}
+
 export function retryDelayFor(count) {
 	return Math.min(2000 * 2 ** Math.max(0, count - 1), 30_000);
 }
@@ -39,7 +47,7 @@ function messageText(message) {
 }
 
 export class WeixinBridge {
-	constructor({ pi, api, config, log, notify, credentials, onExpired, injectTimeoutMs = 5000 }) {
+	constructor({ pi, api, config, log, notify, credentials, onExpired, onCommand, injectTimeoutMs = 5000 }) {
 		this.pi = pi;
 		this.api = api;
 		this.cfg = config;
@@ -47,6 +55,7 @@ export class WeixinBridge {
 		this.notify = notify ?? (() => {});
 		this.credentials = credentials;
 		this.onExpired = onExpired ?? (() => {});
+		this.onCommand = onCommand ?? (async () => null);
 
 		this.queue = [];
 		this.deferred = [];
@@ -128,11 +137,8 @@ export class WeixinBridge {
 	}
 
 	cancelSwitch() {
-		this.switching = false;
-		if (this.switchTimer) {
-			clearTimeout(this.switchTimer);
-			this.switchTimer = undefined;
-		}
+		// 失败也要把暂存消息放回队列，否则它们会卡到下一次成功切换
+		this.endSwitch();
 	}
 
 	/** 入队；返回 {accepted, reason}。 */
@@ -265,11 +271,11 @@ export class WeixinBridge {
 			}
 			const text = inflight.texts.join("\n\n").trim() || this.cfg.emptyReply;
 			await this.#deliver(inflight, text);
-		} catch (err) {
+		} catch (cause) {
 			this.stats.failed++;
-			this.log?.error(`回复失败：${err?.stack ?? err}`);
-			this.notify(`微信回复失败：${err?.message ?? err}`, "warning");
-			if (isSessionExpired(err)) this.onExpired(err);
+			this.log?.error(`回复失败：${cause?.stack ?? cause}`);
+			this.notify(err(CODE.REPLY_FAILED, "failed to send weixin reply", cause?.message ?? cause), "warning");
+			if (isSessionExpired(cause)) this.onExpired(cause);
 		} finally {
 			this.finishing = false;
 			void this.pump();
@@ -305,6 +311,29 @@ export class WeixinBridge {
 
 	async #pumpOnce() {
 		const item = this.queue.shift();
+		const command = parseChatCommand(item.text);
+		if (command) {
+			this.finishing = true;
+			let reply = null;
+			try {
+				reply = await this.onCommand(command, item);
+			} catch (err) {
+				this.log?.error(`command failed: ${err?.message ?? err}`);
+			} finally {
+				this.finishing = false;
+			}
+			if (reply) {
+				try {
+					await this.replyCommand(item, reply);
+				} catch (cause) {
+					this.stats.failed++;
+					this.notify(err(CODE.REPLY_FAILED, "failed to send weixin reply", cause?.message ?? cause), "warning");
+					if (isSessionExpired(cause)) this.onExpired(cause);
+				}
+				return;
+			}
+			// null = not one of our commands: fall through and treat it as a normal message
+		}
 		let images = [];
 		let files = [];
 		let prompt;
@@ -366,7 +395,7 @@ export class WeixinBridge {
 		const cfg = this.cfg.images ?? {};
 		if (!cfg.enabled || !item.images?.length) return [];
 		const list = item.images.slice(0, Math.max(0, cfg.maxCount ?? 2));
-		if (item.images.length > list.length) notes.push(`（另有 ${item.images.length - list.length} 张图片未下载）`);
+		if (item.images.length > list.length) notes.push(`(${item.images.length - list.length} more images not downloaded)`);
 		const results = await Promise.all(
 			list.map(async (image) => {
 				try {
@@ -376,11 +405,11 @@ export class WeixinBridge {
 						cdnBaseUrl: this.cfg.endpoints.cdn,
 						maxBytes: cfg.maxBytes ?? 8 * 1024 * 1024,
 					});
-					if (!buf?.length) throw new Error("空文件");
+					if (!buf?.length) throw new Error("empty file");
 					return { type: "image", data: buf.toString("base64"), mimeType: sniffImageMime(buf) };
 				} catch (err) {
 					this.log?.warn(`入站图片下载失败：${err?.message ?? err}`);
-					notes.push("[图片下载失败]");
+					notes.push("[image download failed]");
 					return null;
 				}
 			}),
@@ -409,17 +438,17 @@ export class WeixinBridge {
 				const target = path.join(dir, `${Date.now()}-${randomInt(1000, 9999)}-${safe}`);
 				fs.writeFileSync(target, buf, { mode: 0o600 });
 				saved.push(target);
-				notes.push(`[文件] ${file.name} → ${target}`);
+				notes.push(`[file] ${file.name} → ${target}`);
 			} catch (err) {
 				this.log?.warn(`入站文件下载失败：${err?.message ?? err}`);
-				notes.push(`[文件下载失败] ${file.name}`);
+				notes.push(`[file download failed] ${file.name}`);
 			}
 		}
 		return saved;
 	}
 
-	#failOnStale(item, err) {
-		const reason = err?.message ?? String(err);
+	#failOnStale(item, cause) {
+		const reason = cause?.message ?? String(cause);
 		const first = !this.stale;
 		this.stale = true;
 		this.injecting = false;
@@ -427,7 +456,7 @@ export class WeixinBridge {
 		if (item) this.queue.unshift(item);
 		if (first) {
 			this.log?.error(`会话已被替换，暂停注入直到新会话接棒：${reason}`);
-			this.notify("微信桥已暂停：Pi 会话被替换，等新会话接手后自动恢复", "warning");
+			this.notify(err(CODE.BRIDGE_PAUSED, "weixin bridge paused: pi session was replaced; it resumes when the new session takes over"), "warning");
 		}
 	}
 
@@ -472,6 +501,12 @@ export class WeixinBridge {
 		}
 	}
 
+	/** 直接回复一条命令回执（不进入模型）。 */
+	async replyCommand(item, text) {
+		const inflight = { item, texts: [], attemptsLeft: this.cfg.maxChunks };
+		await this.#deliver(inflight, text);
+	}
+
 	async #deliver(inflight, text) {
 		if (this.stopped) return;
 		const { item } = inflight;
@@ -487,7 +522,7 @@ export class WeixinBridge {
 		const last = this.lastInboundAt.get(target) || item.at || Date.now();
 		if (Date.now() - last > windowMs) {
 			this.log?.warn("已超过 24 小时窗口，回复未发送");
-			this.notify("微信 24 小时窗口已过：请在微信里先发一条消息，再重试", "warning");
+			this.notify(err(CODE.WINDOW_EXPIRED, "weixin 24h window closed; send a message in WeChat first, then retry"), "warning");
 			return;
 		}
 
@@ -509,21 +544,21 @@ export class WeixinBridge {
 				.slice(0, 3)
 				.map((skip) => {
 					const name = path.basename(String(skip.path || ""));
-					return name ? `${name}：${skip.reason}` : skip.reason;
+					return name ? `${name}: ${skip.reason}` : skip.reason;
 				})
-				.join("；");
-			body = [body, `（${skippedCount} 个文件未发送：${detail}）`].filter(Boolean).join("\n");
+				.join("; ");
+			body = [body, `(${skippedCount} file(s) not sent: ${detail})`].filter(Boolean).join("\n");
 		}
 		const textBudget = Math.max(1, inflight.attemptsLeft - parsed.files.length);
 		const chunks = chunkText(body, {
 			chunkChars: this.cfg.chunkChars,
 			maxChunks: Math.min(textBudget, this.cfg.maxChunks),
-			overflowHint: "……（内容过长，已截断）",
+			overflowHint: "... (truncated, message too long)",
 		});
 
 		for (const chunk of chunks) {
 			if (this.stopped) return;
-			await this.#sendWithRetry("文本", () =>
+			await this.#sendWithRetry("text", () =>
 				this.api.sendText(this.credentials.token, { to: target, contextToken, text: chunk }),
 			);
 			this.stats.sent++;
@@ -545,7 +580,7 @@ export class WeixinBridge {
 					cdnBaseUrl: this.cfg.endpoints.cdn,
 					log: this.log,
 				});
-				await this.#sendWithRetry("媒体", () =>
+				await this.#sendWithRetry("media", () =>
 					this.api.sendItems(this.credentials.token, {
 						to: target,
 						contextToken,
@@ -559,11 +594,11 @@ export class WeixinBridge {
 				this.stats.failed++;
 				this.log?.error(`文件发送失败 ${file.path}：${err?.stack ?? err}`);
 				if (inflight.attemptsLeft > 0) {
-					await this.#sendWithRetry("失败提示", () =>
+					await this.#sendWithRetry("notice", () =>
 						this.api.sendText(this.credentials.token, {
 							to: target,
 							contextToken,
-							text: `（文件发送失败：${file.name} — ${err?.message ?? err}）`,
+							text: `(file send failed: ${file.name} — ${err?.message ?? err})`,
 						}),
 					);
 					this.stats.sent++;
@@ -578,7 +613,7 @@ export class WeixinBridge {
 		let lastError;
 		for (let i = 0; i < attempts; i++) {
 			try {
-				if (this.stopped) throw new Error("桥已停止");
+				if (this.stopped) throw new Error("bridge is stopped");
 				return await fn();
 			} catch (err) {
 				lastError = err;
@@ -588,11 +623,11 @@ export class WeixinBridge {
 				const retryableStatus = [408, 425, 429].includes(status);
 				const fatal = (status >= 400 && status < 500 && !retryableStatus) || business;
 				if (fatal) throw err;
-				this.log?.warn(`${label}发送失败 ${i + 1}/${attempts}：${err?.message ?? err}`);
+				this.log?.warn(`${label} send failed ${i + 1}/${attempts}: ${err?.message ?? err}`);
 				if (i + 1 < attempts) await new Promise((resolve) => setTimeout(resolve, 500 * (i + 1)));
 			}
 		}
-		throw lastError ?? new Error(`${label}发送失败`);
+		throw lastError ?? new Error(`${label} send failed`);
 	}
 
 	// ── 输入状态 ──────────────────────────────────────────────────────

package/src/text.js

@@ -166,7 +166,7 @@ function splitFenced(text, limit) {
 /** 分片 + (i/n)；超过 maxChunks 只发前几段并带提示。 */
 export function chunkText(
 	text,
-	{ chunkChars = MAX_CONTENT_CHARS, maxChunks = 9, overflowHint = "……（内容过长，已截断）" } = {},
+	{ chunkChars = MAX_CONTENT_CHARS, maxChunks = 9, overflowHint = "... (message too long, truncated)" } = {},
 ) {
 	const normalized = String(text ?? "").trim();
 	if (!normalized) return [];