u1s1-cli 1.14.6 → 1.15.0

package/dist/agents/pi.js

@@ -0,0 +1,562 @@
+/**
+ * Pi:内置客户端,以库的方式在本进程内运行(不是子进程)。原 index.ts 的 runAgent,
+ * 拆分时整体搬来,行为不变。启动器(launcher.ts)按需 import 本模块,
+ * 跑其他客户端时不加载 Pi 的任何东西。
+ */
+import { execSync, spawnSync } from "node:child_process";
+import { writeFileSync } from "node:fs";
+import { cleanupBrandThemes, endpointKeyEnv, endpointProviderEntry, ensureBrandPrompt, ensureDefaultSettings, ensureProviderModels, removeLegacyWorkflowPromptTemplate, scrubForeignProviderEnv, toProviderModels, writeAnnouncementsExtension, writeAttributionExtension, writeMcpExtension, removeLegacyCompactUiExtension, removeLegacyUiTextExtension, writeErrorHumanizeExtension, writeWebToolsExtension, } from "../agent-setup.js";
+import { registerUiText } from "../pi-ui-text.js";
+import { Text } from "@earendil-works/pi-tui";
+import { activeSite, agentDir, apiModelToDef, CUSTOM_ENDPOINTS, isPortableInstall, loadConfig, MODELS, persistPreferredModel, PROVIDER_ID, readCompactionBudgetSetting, readCompactionReserveTokens, readSettings, refValid, resolvePreferredModel, setModelsFromApi, VERSION, } from "../config.js";
+import { registerLoopCommand } from "../loop.js";
+import { ensureSearchTools } from "../search-tools.js";
+import { ensureUsableShell } from "../shell-doctor.js";
+import { applyBrandUi, setAnnouncement, setUpdateNotice } from "../style.js";
+import { AccessDeniedError, AuthError, fetchModels, loadCustomEndpoints, readJsonResponseCapped } from "../api.js";
+import { ensureSigningProxy, onGatewayFetchFailure } from "../device-auth.js";
+import { installChildEnvGuard } from "../secret-env.js";
+import { deployHintText, markNudge, shouldShowDeployHint } from "../nudges.js";
+import { createGatewayTelemetry } from "../telemetry.js";
+import { installCommand, siteLinks, siteOf } from "../site.js";
+import { lang, tr } from "../i18n.js";
+const PACKAGE_NAME = "u1s1-cli";
+/** 启动时检测到的可自动安装的新版;TUI 退出后才装(见 installPendingUpdate)。 */
+let pendingUpdate;
+/**
+ * 启动时自动检查 npm 最新版:autoUpdate 开着就记下退出后安装,关着也在启动横幅的
+ * 版本号后面提示一句(u1s1 vX.Y.Z 后跟升级状态,见 setUpdateNotice)。
+ * 不阻塞启动流程,失败也不报错(留到手动 `u1s1 update`)。
+ *
+ * 绝不能边跑 TUI 边后台 npm install -g 原地更新:npm 会整棵重铺
+ * u1s1-cli/node_modules,而 pi-ai 的 API 适配器要到首次模型调用才按路径懒加载
+ * (openai-completions.lazy.js),路径被砸掉就 ERR_MODULE_NOT_FOUND 当场炸
+ * (0.13.2 之前云端沙箱首任务必崩的现场)。所以这里只记 pending,退出后再装。
+ */
+async function checkForUpdate() {
+    let latest;
+    try {
+        const url = `https://registry.npmjs.org/${PACKAGE_NAME}/latest`;
+        const res = await fetch(url, {
+            headers: { Accept: "application/json" },
+            signal: AbortSignal.timeout(5_000),
+        });
+        if (res.ok) {
+            const body = await readJsonResponseCapped(res, 64 * 1024);
+            latest = typeof body.version === "string"
+                && body.version.length <= 100
+                && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(body.version)
+                ? body.version
+                : undefined;
+        }
+    }
+    catch {
+        return; // 网络不可用，静默跳过
+    }
+    if (!latest)
+        return;
+    // parseInt 而非 Number:预发布段("0-beta.1")取前导数字,避免 NaN 让比较全军覆没
+    const pa = VERSION.split(".").map((s) => parseInt(s, 10) || 0);
+    const pb = latest.split(".").map((s) => parseInt(s, 10) || 0);
+    let newer = false;
+    for (let i = 0; i < 3; i++) {
+        const diff = (pb[i] ?? 0) - (pa[i] ?? 0);
+        if (diff > 0) {
+            newer = true;
+            break;
+        }
+        if (diff < 0)
+            break;
+    }
+    if (!newer)
+        return;
+    const settings = readSettings();
+    // 便携版没法用 npm 自更新;autoUpdate 关闭同理只提示。u1s1 update 会给出正确升级方式
+    if (settings.autoUpdate === false || isPortableInstall()) {
+        setUpdateNotice(tr(`⬆ 新版 v${latest} 可用 · u1s1 update 升级`, `⬆ v${latest} available · run u1s1 update`));
+        return;
+    }
+    // 检测包管理器
+    const userAgent = process.env.npm_config_user_agent ?? "";
+    const pm = userAgent.startsWith("pnpm") ? "pnpm"
+        : userAgent.startsWith("yarn") ? "yarn"
+            : userAgent.startsWith("bun") ? "bun"
+                : "npm";
+    const installCmd = pm === "npm"
+        ? `npm install -g --loglevel=error ${PACKAGE_NAME}@latest`
+        : `${pm} add -g ${PACKAGE_NAME}@latest`;
+    pendingUpdate = { latest, installCmd };
+    setUpdateNotice(tr(`⬆ 发现新版 v${latest},退出后自动更新`, `⬆ v${latest} available, will update on exit`));
+}
+/**
+ * TUI 退出后前台安装新版:此刻不再有模型调用和懒加载,重铺 node_modules 才安全。
+ * 不设 timeout——半路杀掉 npm 会留下残缺的全局安装,之后连启动都起不来;
+ * stdio 直通,装多久用户看得见。(同机另开的 u1s1 实例仍会被重铺波及,属残余
+ * 风险,但远好于更新自己脚下这棵树。)
+ */
+export function installPendingUpdate() {
+    if (!pendingUpdate)
+        return;
+    const { latest, installCmd } = pendingUpdate;
+    console.log(tr(`\n⬆ 正在更新到 v${latest}…`, `\n⬆ Updating to v${latest}…`));
+    console.log(tr("  (可能需要几分钟,期间请不要关闭窗口或按 Ctrl+C,中途打断会装出半截)", "  (This may take a few minutes. Don't close the window or press Ctrl+C; interrupting leaves a broken install.)"));
+    try {
+        execSync(installCmd, { stdio: "inherit" });
+        console.log(tr(`✅ 已更新到 v${latest},下次运行 u1s1 生效。`, `✅ Updated to v${latest}. It takes effect the next time you run u1s1.`));
+    }
+    catch {
+        // 失败不挡退出,下次启动还会再试。npm 全局目录没写权限时 `u1s1 update` 也会
+        // 走同一条命令再失败一次,所以这里直接给出能跳出循环的路径(官网安装脚本)
+        console.error(tr("自动更新失败(上面是 npm 的报错,常见原因是没有全局安装权限)。", "Auto-update failed (npm's error is above; usually missing permission for global installs)."));
+        console.error(tr("可以改用官网安装脚本重装,一步到位:", "Reinstall with the official install script instead:"));
+        console.error(process.platform === "win32"
+            ? `  powershell -c "${installCommand(activeSite(), "ps1")}"`
+            : `  ${installCommand(activeSite(), "sh")}`);
+        console.error(tr("不想每次退出都尝试更新的话,可在 ~/.u1s1/agent/settings.json 里设 \"autoUpdate\": false", "To stop trying to update on every exit, set \"autoUpdate\": false in ~/.u1s1/agent/settings.json"));
+    }
+}
+/**
+ * tmux 默认不转发键盘修饰键,会把 Shift+Enter 当成普通回车发出去,消息没写完就被发送。
+ * 只开 extended-keys 不够:默认 terminal-features 里 xterm* 没有 extkeys,tmux 根本不会
+ * 向外层终端要 modifyOtherKeys,S-Enter 绑定也就永远触发不了。
+ * 启动时自动做这些事(运行时生效,不写用户 tmux.conf;失败则静默忽略,仍可用 Ctrl+J 换行):
+ * 1. 开启 extended-keys,并给当前终端补上 extkeys;
+ * 2. tmux 3.5+ 再切到 csi-u(3.4 及以下没有这个选项,忽略即可);
+ * 3. 兜底把 S-Enter / C-Enter 原样转成 pi 认得的 CSI-u 序列。
+ */
+function ensureTmuxKeyboardProtocol() {
+    if (!process.env.TMUX)
+        return;
+    const runTmux = (args) => spawnSync("tmux", args, { timeout: 1500, encoding: "utf8" });
+    if (runTmux(["-V"]).status !== 0)
+        return; // tmux 不可用(如沙箱)则跳过
+    // 当前会话 + 全局默认都开,避免只改 -g 时已有会话仍是 off
+    runTmux(["set-option", "-g", "extended-keys", "on"]);
+    runTmux(["set-option", "extended-keys", "on"]);
+    // 3.5+; 3.4 会失败,忽略
+    runTmux(["set-option", "-g", "extended-keys-format", "csi-u"]);
+    runTmux(["set-option", "extended-keys-format", "csi-u"]);
+    const features = runTmux(["show", "-gv", "terminal-features"]);
+    if (features.status === 0 && !/\bextkeys\b/.test(features.stdout ?? "")) {
+        runTmux(["set-option", "-ga", "terminal-features", "xterm*:extkeys"]);
+    }
+    // 已挂上的客户端不会自动重读 terminal-features;直接往当前客户端 tty
+    // 发 modifyOtherKeys,让外层终端立刻开始区分 Shift+Enter。
+    const tty = runTmux(["display-message", "-p", "#{client_tty}"]).stdout?.trim();
+    if (tty) {
+        try {
+            writeFileSync(tty, "\x1b[>4;2m");
+        }
+        catch {
+            // 没权限或不是 tty 就忽略
+        }
+    }
+    // -l: 按字面量发送,避免 send-keys 把转义序列拆成一串普通按键
+    runTmux(["bind-key", "-n", "S-Enter", "send-keys", "-l", "\x1b[13;2u"]);
+    runTmux(["bind-key", "-n", "C-Enter", "send-keys", "-l", "\x1b[13;5u"]);
+}
+export async function runAgent(cfg, args) {
+    cleanupBrandThemes();
+    ensureDefaultSettings();
+    // Set constant environment values before startup I/O; values derived from
+    // responses are configured below, before loading the kernel.
+    process.env["PI_CODING_AGENT_DIR"] = agentDir;
+    process.env["U1S1_TOOLS_VIA_EXTENSION"] = "1";
+    // hide pi's own "Run pi update" banner; users should run `u1s1 update` instead
+    process.env["PI_SKIP_VERSION_CHECK"] = "1";
+    // Windows shell 体检异步先行,与取模型列表/搜索工具下载并行;首启验活
+    // (Defender 首扫 bash.exe 可达秒级)藏进网络等待,进 pi 前再 await
+    const shellReady = ensureUsableShell();
+    // 预 seed fd/rg(国内直连 GitHub 不通,pi 自己下不动);与取模型列表并行,
+    // 但必须在进 pi 之前就位,否则 pi 会自己去 GitHub 下载
+    const searchToolsReady = ensureSearchTools(cfg);
+    // Fetch model list from server; fall back to built-in MODELS on error.
+    // 服务端没开搜索(或老网关没有 features 字段)时不注册 web_search,模型就不会白调
+    // 自定义端点与模型列表并行拉取,失败各自兜底(内置列表 / 本地缓存)
+    let webSearchEnabled = true;
+    // 老网关没有 /v1/fetch,web_fetch_render 缺失时按关闭处理,直连失败不去白调
+    let webFetchRenderEnabled = false;
+    // 老网关没有 /v1/image,image_gen 缺失时按关闭处理,不注册生图工具
+    let imageGenEnabled = false;
+    const endpointsReady = loadCustomEndpoints(cfg);
+    const modelsReady = fetchModels(cfg);
+    let modelsResp;
+    try {
+        modelsResp = await modelsReady;
+    }
+    catch (e) {
+        if (e instanceof AuthError) {
+            // 凭证形状还在但服务端已作废(设备被移除/换过钥匙):直接进 TUI 每条消息都会失败,
+            // 不如现在就引导重新登录
+            console.error(tr("  登录已失效(这台设备可能被移除,或账号更换过钥匙),需要重新登录。", "  Your session has expired (this device may have been removed, or the account's keys changed). Please sign in again."));
+            const { login } = await import("../login.js");
+            cfg = await login();
+            modelsResp = await fetchModels(cfg).catch((e2) => {
+                console.error(tr("  获取模型列表失败,使用内置列表:", "  Couldn't fetch the model list; using the built-in list:"), e2.message);
+                return undefined;
+            });
+        }
+        else if (e instanceof AccessDeniedError) {
+            // 封禁/停用/设备不受信任:进 TUI 后每条消息都会失败,不如现在就把原因说清楚并退出
+            console.error(`  ${e.message}`);
+            const site = siteOf(cfg);
+            console.error(tr(`  这个账号当前无法使用 u1s1。如有疑问可发邮件到 ${site.contactEmail},或在 ${siteLinks(site).dashboard} 提交工单。`, `  This account can't use u1s1 right now. Questions? Email ${site.contactEmail} or open a support ticket at ${siteLinks(site).dashboard}.`));
+            process.exit(1);
+        }
+        else {
+            console.error(tr("  获取模型列表失败,使用内置列表:", "  Couldn't fetch the model list; using the built-in list:"), e.message);
+        }
+    }
+    if (modelsResp) {
+        const { models, features, announcement } = modelsResp;
+        setModelsFromApi(models.map(apiModelToDef));
+        webSearchEnabled = features.web_search !== false;
+        webFetchRenderEnabled = features.web_fetch_render === true;
+        imageGenEnabled = features.image_gen === true;
+        // 后台下发的启动公告(与模型列表同一次请求捎回,零额外开销);空/老网关不显示
+        if (announcement?.text)
+            setAnnouncement(announcement);
+    }
+    await endpointsReady;
+    // Gateway metadata owns each official model's default thinking level. Seed
+    // it after the live model list arrives; explicit user choices remain intact.
+    ensureDefaultSettings(MODELS);
+    // pi provider 只支持静态 header；指向本机 signing proxy，由它逐请求附 DPoP proof。
+    const signing = await ensureSigningProxy(cfg, "terminal", {
+        token: modelsResp?.clientAttestation,
+        expiresInSeconds: modelsResp?.clientAttestationExpiresInSeconds,
+        refresh: async () => {
+            const refreshed = await fetchModels(cfg);
+            return {
+                token: refreshed.clientAttestation,
+                expiresInSeconds: refreshed.clientAttestationExpiresInSeconds,
+            };
+        },
+    });
+    const officialCfg = { ...cfg, baseUrl: signing.baseUrl, apiKey: signing.localKey };
+    ensureBrandPrompt(await shellReady);
+    ensureProviderModels(officialCfg);
+    removeLegacyWorkflowPromptTemplate();
+    // 联网工具经 agentDir/extensions 投影,TUI 和 Desktop App 共用一份注册
+    writeWebToolsExtension(officialCfg, {
+        webSearch: webSearchEnabled,
+        webFetchRender: webFetchRenderEnabled,
+        imageGen: imageGenEnabled,
+    });
+    // 精简 UI 已下线,界面回到 Pi 默认;清掉旧版写进 agentDir/extensions 的扩展,否则 Pi 仍会加载它
+    removeLegacyCompactUiExtension();
+    // 模型调用错误人话化（同样投影,Desktop App 共享）
+    writeErrorHumanizeExtension();
+    // 斜杠命令补全描述、「思考中」提示改由下面的进程内扩展注册(registerUiText);
+    // 删掉上一版投影到 agentDir/extensions 的 u1s1-ui-text.js,免得两边各包一层
+    removeLegacyUiTextExtension();
+    // 会话内公告触达:5 分钟轮询,公告变化时推进会话(同样投影,Desktop 共享)
+    writeAnnouncementsExtension();
+    // OpenRouter 应用归因：直连流量计入 u1s1 的公开排行
+    writeAttributionExtension();
+    // 自定义 MCP 服务:TUI 用 pi 内置 MCP 读 agent/mcp.json;这里迁旧配置,并给 Desktop 的旧引擎投影兜底扩展
+    writeMcpExtension();
+    ensureTmuxKeyboardProtocol();
+    // must be set before pi reads them (getAgentDir() reads at call time);
+    // 常量部分已在 runAgent 开头、发起 import 之前设好
+    process.env["U1S1_API_KEY"] = officialCfg.apiKey;
+    process.env["U1S1_SIGNING_PROXY_URL"] = officialCfg.baseUrl;
+    // 自定义端点的密钥走环境变量引用(models.json 里只有 $VAR,不落明文)
+    Object.assign(process.env, endpointKeyEnv());
+    // 剔掉环境里的其他厂商密钥,/model 只展示 u1s1 官方模型 + 自定义端点
+    scrubForeignProviderEnv();
+    // 密钥只留在本进程:模型跑的 shell 命令、子 agent、扩展派生的任何子进程都拿不到
+    installChildEnvGuard();
+    // 客户端事件上报(见 telemetry.ts):状态放在 runAgent 作用域,/clear、/resume
+    // 会重建扩展运行时、重跑下面的 factory,但一个 TUI 进程只算一个会话
+    const telemetry = createGatewayTelemetry(cfg);
+    const sessionStartedAt = Date.now();
+    const stats = { turns: 0, toolCalls: 0, filesWritten: 0, writesThisRun: 0 };
+    let firstToolSuccessSent = false;
+    let firstTaskDoneSent = false;
+    let sessionEndSent = false;
+    telemetry.track("session_start", { surface: "terminal" });
+    // 「连不上 u1s1 服务器」只在用户本机可见;记下底层错误码,网络恢复后随批次上报
+    onGatewayFetchFailure((failure) => telemetry.track("gateway_unreachable", { code: failure.code, surface: "terminal" }));
+    const trackSessionEnd = () => {
+        if (sessionEndSent)
+            return;
+        sessionEndSent = true;
+        telemetry.track("session_end", {
+            duration_ms: Date.now() - sessionStartedAt,
+            turns: stats.turns,
+            tool_calls: stats.toolCalls,
+            files_written: stats.filesWritten,
+        });
+    };
+    await searchToolsReady;
+    // 界面语言跟站点走(见 i18n.ts)。pi 引擎的补丁文案(patches/)读不到 u1s1 的配置,
+    // 只认 U1S1_LANG;登录/换站都已在上面处理完,这里定下来再加载内核,TUI 与 -p 模式都覆盖
+    process.env["U1S1_LANG"] = lang();
+    // Module evaluation can block the event loop for seconds on slow filesystems.
+    // Finish startup requests and fallback/login handling before loading the kernel.
+    const { CustomEditor, main } = await import("@earendil-works/pi-coding-agent");
+    // Start this optional request after module evaluation so its timeout can progress.
+    void checkForUpdate();
+    // 网页终端(如 Taikula)把 Shift+Enter 发成 ESC+CR(\x1b\r)。pi 在没开 Kitty
+    // 协议时把它当成 Alt+Enter:空闲就直接发送,忙碌才排队。先改成 CSI-u 的
+    // Shift+Enter,输入框就会换行,真·Alt+Enter(\x1b[13;3u)不受影响。
+    // TUI 里 console.log 会被下一帧重绘吞掉,拦截提示必须走 ui.notify;
+    // session_start 时把 notify 句柄存出来给编辑器拦截用
+    let notifyUi;
+    class ShiftEnterEditor extends CustomEditor {
+        handleInput(data) {
+            // 拦截 /login 和 /logout,不让 pi 弹出内置供应商列表
+            if (data === "\r" || data === "\n") {
+                const text = this.getText().trim();
+                const tip = (msg) => (notifyUi ? notifyUi(msg) : console.log(`  ${msg}`));
+                if (text.startsWith("/login")) {
+                    tip(tr("切换模型用 /model;要换 u1s1 账号:先 /exit 退出,再在终端运行 u1s1 logout && u1s1 login", "Use /model to switch models. To switch u1s1 accounts, /exit first, then run u1s1 logout && u1s1 login in your terminal"));
+                    this.setText("");
+                    this.addToHistory?.(text);
+                    return;
+                }
+                if (text === "/logout") {
+                    tip(tr("退出登录请先 /exit 回到终端,再运行:u1s1 logout", "To sign out, /exit to your terminal first, then run: u1s1 logout"));
+                    this.setText("");
+                    this.addToHistory?.(text);
+                    return;
+                }
+            }
+            super.handleInput(data === "\x1b\r" ? "\x1b[13;2u" : data);
+        }
+    }
+    const extension = [
+        {
+            name: "u1s1",
+            factory: (pi) => {
+                applyBrandUi(pi, VERSION);
+                // 斜杠命令补全描述(按 U1S1_LANG 换文案、去掉 /bug)和「思考中」提示,以前是 Pi 补丁。
+                // 放在进程内扩展里:--no-extensions、设置里禁用 agentDir 扩展都不影响,跟补丁一样总是生效
+                registerUiText(pi);
+                // /loop: 会话级定时循环执行提示词(对标 Claude Code),实现见 loop.ts
+                registerLoopCommand(pi);
+                // 会话标题:拿用户第一条正经输入的前半截当名字(像 Claude Code 那样),
+                // /resume 的会话列表里就能一眼认出每个会话。/clear 后 session_start
+                // 会重置标记,新会话重新起标题。
+                let sessionTitled = false;
+                pi.on("session_start", () => {
+                    sessionTitled = false;
+                });
+                pi.on("input", async (event) => {
+                    if (sessionTitled || event.source === "extension")
+                        return;
+                    const text = event.text.trim().replace(/\s+/g, " ");
+                    // 空输入(纯图片粘贴)和斜杠命令不当标题
+                    if (!text || text.startsWith("/"))
+                        return;
+                    sessionTitled = true;
+                    const title = text.length > 30 ? `${text.slice(0, 30)}…` : text;
+                    pi.setSessionName(title);
+                });
+                // pi 内置只有 /quit；补一个更常见的 /exit，方便新手退出
+                pi.registerCommand("exit", {
+                    description: tr("退出 u1s1", "Exit u1s1"),
+                    handler: async (_args, ctx) => {
+                        ctx.shutdown();
+                    },
+                });
+                // /help:启动横幅和官网教程都在引导用户输入它,必须真实存在
+                pi.registerEntryRenderer("u1s1-help", (_entry, _opts, theme) => {
+                    const site = siteOf(cfg);
+                    const text = [
+                        theme.bold(theme.fg("text", tr("u1s1 常用操作", "u1s1 basics"))),
+                        theme.fg("text", tr("直接打字说需求,回车发送 · Shift+Enter 换行 · Ctrl+V 贴图 · Esc 中断", "Type what you need, Enter to send · Shift+Enter newline · Ctrl+V paste image · Esc stop")),
+                        theme.fg("text", tr("/model 切换模型(留意免费/价格提示) · /clear 清空上下文开新会话", "/model switch models (check the price hints) · /clear clear context, start a new session")),
+                        theme.fg("text", tr("/usage 查剩余额度 · /context 看上下文占用与压缩预算 · /resume 恢复历史会话", "/usage remaining balance · /context context usage and compaction budget · /resume past sessions")),
+                        theme.fg("text", tr("/feedback 一句话反馈问题或建议(自动附带版本与请求编号建工单)", "/feedback report a problem or idea (opens a support ticket with version and request IDs)")),
+                        theme.fg("dim", tr("/compact 手动压缩上下文 · /settings 设置 · /hotkeys 全部快捷键 · /exit 退出", "/compact compact context now · /settings settings · /hotkeys all shortcuts · /exit exit")),
+                        // 国际站没有网页托管,不提 u1s1 deploy
+                        theme.fg("dim", site.id === "intl"
+                            ? tr("退出后在终端:u1s1 update 升级", "Back in your terminal: u1s1 update to upgrade")
+                            : tr("退出后在终端:u1s1 deploy 发布网页 · u1s1 update 升级", "Back in your terminal: u1s1 deploy to publish a web page · u1s1 update to upgrade")),
+                        theme.fg("dim", tr("匿名使用统计只记会话开始/结束等节点,不含任何内容;U1S1_TELEMETRY=0 可关闭", "Anonymous usage stats only record events like session start/end, never content; U1S1_TELEMETRY=0 turns them off")),
+                        theme.fg("dim", tr(`新手教程 → ${siteLinks(site).guides}`, `Guides → ${siteLinks(site).guides}`)),
+                    ].join("\n");
+                    return new Text(text, 1, 0);
+                });
+                pi.registerCommand("help", {
+                    description: tr("查看常用操作和命令", "Show common actions and commands"),
+                    handler: async () => {
+                        pi.appendEntry("u1s1-help");
+                    },
+                });
+                // /usage:会话内查额度。此前额度只有用完撞 429 才可见(审计 G1)
+                pi.registerEntryRenderer("u1s1-usage", (entry, _opts, theme) => {
+                    const data = entry.data ?? {};
+                    if (data.error)
+                        return new Text(theme.fg("dim", data.error), 1, 0);
+                    return new Text((data.lines ?? []).map((l) => theme.fg("text", l)).join("\n"), 1, 0);
+                });
+                pi.registerCommand("usage", {
+                    description: tr("查看剩余额度和本月用量", "Show remaining balance and this month's usage"),
+                    handler: async () => {
+                        const { usageEntryData } = await import("../usage.js");
+                        pi.appendEntry("u1s1-usage", await usageEntryData());
+                    },
+                });
+                // /context:上下文占用与自动压缩预算。注册给 pi 的 contextWindow 是压缩预算
+                // (默认 200K,见 effectiveContextWindow),不是模型真实窗口,这里把两者都说清楚,
+                // 免得用户看着 1M 的模型却在 20 万 token 就被压缩时以为出了问题
+                pi.registerEntryRenderer("u1s1-context", (entry, _opts, theme) => {
+                    const data = entry.data ?? {};
+                    return new Text((data.lines ?? []).map((l) => theme.fg("text", l)).join("\n"), 1, 0);
+                });
+                pi.registerCommand("context", {
+                    description: tr("查看上下文占用与自动压缩预算", "Show context usage and the auto-compaction budget"),
+                    handler: async (_args, ctx) => {
+                        const { contextEntryLines } = await import("../context-usage.js");
+                        const settings = readSettings();
+                        pi.appendEntry("u1s1-context", {
+                            lines: contextEntryLines({
+                                usage: ctx.getContextUsage(),
+                                model: ctx.model ? { provider: ctx.model.provider, id: ctx.model.id } : undefined,
+                                budgetSetting: readCompactionBudgetSetting(settings),
+                                reserveTokens: readCompactionReserveTokens(settings),
+                            }),
+                        });
+                    },
+                });
+                // /feedback:会话内直接建工单,附版本/平台/最近请求编号(运营清单 E4)
+                pi.registerEntryRenderer("u1s1-feedback", (entry, _opts, theme) => {
+                    const data = entry.data ?? {};
+                    return new Text((data.lines ?? []).map((l) => theme.fg("text", l)).join("\n"), 1, 0);
+                });
+                pi.registerCommand("feedback", {
+                    description: tr("反馈问题或建议(自动附带诊断信息建工单)", "Report a problem or idea (opens a support ticket with diagnostics)"),
+                    handler: async (cmdArgs, ctx) => {
+                        const { feedbackInSession, parseFeedbackArgs } = await import("../feedback.js");
+                        let raw = cmdArgs.trim();
+                        let parsed;
+                        try {
+                            parsed = parseFeedbackArgs(raw.split(/\s+/).filter(Boolean));
+                        }
+                        catch (e) {
+                            pi.appendEntry("u1s1-feedback", { lines: [e instanceof Error ? e.message : String(e)] });
+                            return;
+                        }
+                        if (!parsed.help && !parsed.text && ctx.hasUI) {
+                            const text = (await ctx.ui.input(tr("反馈内容", "Feedback"), tr("一句话说清楚问题或建议", "Describe the problem or idea in a sentence")))?.trim();
+                            if (!text)
+                                return;
+                            raw = `--${parsed.category} ${text}`;
+                        }
+                        const model = ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : undefined;
+                        pi.appendEntry("u1s1-feedback", { lines: await feedbackInSession(raw, model) });
+                    },
+                });
+                // ---- 事件上报 + 首次写文件后的 deploy 提示 ----
+                pi.on("agent_start", () => {
+                    stats.writesThisRun = 0;
+                });
+                pi.on("turn_end", () => {
+                    stats.turns++;
+                });
+                pi.on("tool_result", (event) => {
+                    stats.toolCalls++;
+                    if (event.isError)
+                        return;
+                    if (!firstToolSuccessSent) {
+                        firstToolSuccessSent = true;
+                        telemetry.track("first_tool_success", { tool: event.toolName });
+                    }
+                    if (event.toolName === "write" || event.toolName === "edit") {
+                        stats.filesWritten++;
+                        stats.writesThisRun++;
+                    }
+                });
+                pi.on("agent_end", (_event, ctx) => {
+                    if (stats.writesThisRun === 0)
+                        return;
+                    if (!firstTaskDoneSent) {
+                        firstTaskDoneSent = true;
+                        telemetry.track("first_task_done", { files_written: stats.filesWritten });
+                    }
+                    // 每台机器只提示一次;跑过 u1s1 deploy 后永不再提(见 nudges.ts)。国际站没有网页托管,不提示
+                    if (ctx.hasUI && siteOf(cfg).id !== "intl" && shouldShowDeployHint()) {
+                        markNudge("deploy_hint_shown");
+                        ctx.ui.notify(deployHintText(), "info");
+                    }
+                });
+                // pi 在 session_shutdown 处理完后直接 process.exit,session_end 只能在这里
+                // 发并等冲刷(最多 1 秒);/clear、/resume 的 reason 不是 quit,不算会话结束
+                pi.on("session_shutdown", async (event) => {
+                    if (event.reason !== "quit")
+                        return;
+                    trackSessionEnd();
+                    await telemetry.shutdown();
+                });
+                // 模型调用错误人话化不在这里注册:走 writeErrorHumanizeExtension 投影,
+                // TUI 和 Desktop App 共用一份(见 agent-setup.ts)
+                // /clear: 清空当前对话上下文，开始新会话
+                pi.registerCommand("clear", {
+                    description: tr("清除当前对话上下文，开始新会话", "Clear the conversation context and start a new session"),
+                    handler: async (_args, ctx) => {
+                        await ctx.newSession({
+                            withSession: async (sessionContext) => {
+                                sessionContext.ui.notify(tr("🗑️ 上下文已清除", "🗑️ Context cleared"), "info");
+                            },
+                        });
+                    },
+                });
+                // 进程内注册直接给字面量密钥:不经 $VAR 环境变量引用,也不落文件
+                pi.registerProvider(PROVIDER_ID, {
+                    name: "u1s1",
+                    baseUrl: officialCfg.baseUrl,
+                    api: "openai-completions",
+                    apiKey: officialCfg.apiKey,
+                    models: toProviderModels(MODELS),
+                });
+                // 用户在云端配置的自定义端点,一个端点一个 provider,/model 里即可切换
+                for (const ep of CUSTOM_ENDPOINTS) {
+                    pi.registerProvider(ep.id, endpointProviderEntry(ep, { literalKey: true }));
+                }
+                // /model and Ctrl+P already write pi settings; also keep ~/.u1s1/config.json in sync
+                pi.on("model_select", (event) => {
+                    if (event.source === "restore")
+                        return;
+                    const ref = { provider: event.model.provider, id: event.model.id };
+                    if (!refValid(ref))
+                        return;
+                    persistPreferredModel(loadConfig(), ref.provider, ref.id);
+                });
+                pi.on("session_start", (_event, ctx) => {
+                    notifyUi = (msg) => ctx.ui.notify(msg, "info");
+                    const previous = ctx.ui.getEditorComponent();
+                    ctx.ui.setEditorComponent((tui, theme, keybindings) => {
+                        if (previous) {
+                            const inner = previous(tui, theme, keybindings);
+                            const orig = inner.handleInput.bind(inner);
+                            inner.handleInput = (data) => orig(data === "\x1b\r" ? "\x1b[13;2u" : data);
+                            return inner;
+                        }
+                        return new ShiftEnterEditor(tui, theme, keybindings);
+                    });
+                });
+            },
+        },
+    ];
+    const hasModelArg = args.some((a) => a === "--model" || a.startsWith("--model=") || a === "--provider");
+    const pref = resolvePreferredModel(cfg);
+    // 拿到了目录但本站一个模型都没上(国际站上线初期就是这样):别让 pi 报「Model not found」
+    if (!hasModelArg && modelsResp && MODELS.length === 0 && pref.provider === PROVIDER_ID) {
+        console.error(tr(`  ${siteOf(cfg).origin} 暂时还没有可用的模型,请稍后再试。`, `  No models are available on ${siteOf(cfg).origin} yet. Please try again later.`));
+        process.exit(1);
+    }
+    if (cfg.model !== pref.id || (cfg.modelProvider ?? PROVIDER_ID) !== pref.provider) {
+        persistPreferredModel(cfg, pref.provider, pref.id);
+    }
+    const finalArgs = hasModelArg ? args : ["--model", `${pref.provider}/${pref.id}`, ...args];
+    try {
+        await main(finalArgs, { extensionFactories: extension });
+    }
+    finally {
+        trackSessionEnd();
+        await telemetry.shutdown();
+    }
+}

package/dist/agents/prefs.d.ts

@@ -0,0 +1,35 @@
+import type { AgentConfig } from "./agent-config.js";
+import type { ManagedAgent } from "./runtime.js";
+export interface AgentPrefs {
+    model?: string;
+    autoUpdate: boolean;
+    /** 已经提示过「不在阵容里」的那个 model(内部用) */
+    modelNotice?: string;
+}
+/** 用户能填的模型 id:不带空白、引号等(会原样写进 TOML / JSON)。 */
+export declare function isModelId(value: unknown): value is string;
+export declare function readAgentPrefs(agent: ManagedAgent, raw?: Record<string, unknown> | undefined): AgentPrefs;
+/** null = 删掉这一项(恢复默认);undefined = 不动。 */
+export interface AgentPrefsPatch {
+    model?: string | null;
+    autoUpdate?: boolean | null;
+    modelNotice?: string | null;
+}
+export declare function saveAgentPrefs(agent: ManagedAgent, patch: AgentPrefsPatch): void;
+export interface ModelChoice {
+    /** 这次启动用的模型;null = 网关也没给默认(交给客户端自己) */
+    model: string | null;
+    /** 用户选的模型不在当前阵容里,退回了网关默认 */
+    missing?: string;
+}
+/** 纯函数:用户偏好在阵容里就用它,否则网关默认。 */
+export declare function chooseAgentModel(config: Pick<AgentConfig, "defaultModel" | "models">, preferred: string | undefined): ModelChoice;
+/**
+ * 启动时选模型。用户选的模型不在阵容里时退回网关默认,同一个 id 只提示一次;
+ * 它回到阵容后清掉提示记录(再消失时会再提示)。偏好本身不删:模型可能只是暂时下架。
+ */
+export declare function resolveLaunchModel(agent: ManagedAgent, config: Pick<AgentConfig, "defaultModel" | "models">, deps?: {
+    prefs?: AgentPrefs;
+    save?: (patch: AgentPrefsPatch) => void;
+    notify?: (missing: string, fallback: string | null) => void;
+}): string | null;