u1s1-cli 1.3.2 → 1.4.0

package/dist/agent-setup.d.ts

@@ -32,6 +32,15 @@ export declare function writeWebToolsExtension(cfg: CliConfig, features: {
     webFetchRender: boolean;
     imageGen: boolean;
 }): void;
+/**
+ * 生成「错误信息人话化」扩展到 <agentDir>/extensions/u1s1-error-humanize.js:
+ * 把「429: {json}」形态的模型调用错误翻成中文正文 + 状态码尾巴,TUI 和
+ * Desktop App 共用(同 compact-ui 的投影机制)。实现见 error-humanize.ts,
+ * 分类兼容性(重试/配额/上下文超长)的约束也写在那里。
+ * import 失败时静默跳过——Desktop 独立运行时若指向的 CLI dist 已不存在,
+ * 宁可回到原始错误文本,也不能让扩展报错刷英文堆栈。
+ */
+export declare function writeErrorHumanizeExtension(): void;
 /**
  * 生成「OpenRouter 应用归因」扩展到 <agentDir>/extensions/u1s1-attribution.js。
  * 用户自己配 OPENROUTER_API_KEY 直连时，pi 内置的归因头归到 pi.dev 名下（且受遥测

package/dist/agent-setup.js

@@ -235,6 +235,35 @@ export function writeWebToolsExtension(cfg, features) {
         subagentBlock +
         `}\n`);
 }
+/**
+ * 生成「错误信息人话化」扩展到 <agentDir>/extensions/u1s1-error-humanize.js:
+ * 把「429: {json}」形态的模型调用错误翻成中文正文 + 状态码尾巴,TUI 和
+ * Desktop App 共用(同 compact-ui 的投影机制)。实现见 error-humanize.ts,
+ * 分类兼容性(重试/配额/上下文超长)的约束也写在那里。
+ * import 失败时静默跳过——Desktop 独立运行时若指向的 CLI dist 已不存在,
+ * 宁可回到原始错误文本,也不能让扩展报错刷英文堆栈。
+ */
+export function writeErrorHumanizeExtension() {
+    const dir = join(agentDir, "extensions");
+    mkdirSync(dir, { recursive: true });
+    const url = new URL("./error-humanize.js", import.meta.url).href;
+    writeFileSync(join(dir, "u1s1-error-humanize.js"), `// 由 u1s1 每次启动自动生成,请勿手改\n` +
+        `export default async function (pi) {\n` +
+        `  let humanize;\n` +
+        `  try {\n` +
+        `    humanize = (await import(${JSON.stringify(url)})).humanizeModelError;\n` +
+        `  } catch {\n` +
+        `    return;\n` +
+        `  }\n` +
+        `  pi.on("message_end", (event) => {\n` +
+        `    const msg = event.message;\n` +
+        `    if (msg.role !== "assistant" || msg.stopReason !== "error" || !msg.errorMessage) return;\n` +
+        `    const friendly = humanize(msg.errorMessage);\n` +
+        `    if (!friendly) return;\n` +
+        `    return { message: { ...msg, errorMessage: friendly } };\n` +
+        `  });\n` +
+        `}\n`);
+}
 /**
  * 生成「OpenRouter 应用归因」扩展到 <agentDir>/extensions/u1s1-attribution.js。
  * 用户自己配 OPENROUTER_API_KEY 直连时，pi 内置的归因头归到 pi.dev 名下（且受遥测
@@ -404,7 +433,8 @@ export function toProviderModels(models) {
         }
         return {
             id: m.id,
-            name: m.name,
+            // 选择器只渲染 name 一行,把「免费/几倍」提示拼进去,切模型前就能看到
+            name: m.note ? `${m.name} · ${m.note}` : m.name,
             reasoning: m.reasoning,
             thinkingLevelMap,
             input: m.vision ? ["text", "image"] : ["text"],

package/dist/brand.d.ts

@@ -18,5 +18,7 @@ export declare function renderBrandHeader(theme: Theme, input: {
         text: string;
         url?: string;
     };
+    /** 当前目录为空时给可照抄的开场 prompt(见 starterLines)。 */
+    starterTips?: boolean;
 }): string[];
 export declare function printConsoleBanner(version: string): void;

package/dist/brand.js

@@ -47,6 +47,15 @@ function announcementLine(theme, a) {
     const link = a.url ? `  ${theme.fg("dim", a.url)}` : "";
     return `${theme.fg("accent", "📢")} ${theme.fg("accent", a.text)}${link}`;
 }
+/** 空目录首跑引导:不让新手面对空白输入框想 prompt,给几句能照抄的开场白。 */
+function starterLines(theme) {
+    return [
+        ` ${theme.fg("muted", "这个文件夹还是空的?把想做的直接说出来就行,比如:")}`,
+        ` ${theme.fg("text", "「做一个自我介绍网页,做完帮我发布出去」")}`,
+        ` ${theme.fg("text", "「做一个给朋友的生日祝福页面,要有点小动画」")}`,
+        ` ${theme.fg("text", "「写一个把文件夹里照片按日期重命名的小工具」")}`,
+    ];
+}
 /**
  * Startup hero, responsive to terminal width:
  * wide → wordmark with info column beside it; medium → stacked; narrow → one-liner.
@@ -57,10 +66,13 @@ export function renderBrandHeader(theme, input) {
     const brand = theme.fg("muted", `${BRAND_CN} · ${BRAND_TAGLINE}`);
     const dir = theme.fg("dim", `cwd: ${formatHomePath(input.cwd)}`);
     const hints = theme.fg("dim", "/help · Ctrl+V 图片 · Shift+Enter 换行 · Esc 中断");
+    const starter = input.starterTips ? starterLines(theme) : [];
     if (input.width < ART_WIDTH + 4) {
         const lines = ["", ` ${theme.fg("accent", "✻")} ${name}  ${theme.fg("muted", BRAND_CN)}`, `   ${dir}`, `   ${theme.fg("dim", "Ctrl+V 粘贴图片")}`];
         if (input.announcement)
             lines.push(`   ${announcementLine(theme, input.announcement)}`);
+        if (starter.length)
+            lines.push("", ...starter);
         return [...lines, ""];
     }
     const art = HERO_ART.map((line) => ` ${paintArt(theme, line)}`);
@@ -69,6 +81,8 @@ export function renderBrandHeader(theme, input) {
         const lines = ["", ...art, "", ` ${name}  ${brand}`, ` ${dir}`, ` ${hints}`];
         if (input.announcement)
             lines.push(` ${announcementLine(theme, input.announcement)}`);
+        if (starter.length)
+            lines.push("", ...starter);
         return [...lines, ""];
     }
     const rows = [...art];
@@ -80,6 +94,8 @@ export function renderBrandHeader(theme, input) {
     // 公告放信息列末尾(最后一行字模旁),够醒目又不挤掉常规信息
     if (input.announcement)
         rows[5] += `${gap}${announcementLine(theme, input.announcement)}`;
+    if (starter.length)
+        rows.push("", ...starter);
     return ["", ...rows, ""];
 }
 export function printConsoleBanner(version) {

package/dist/config.d.ts

@@ -25,14 +25,18 @@ export interface ApiThinkingCapabilities {
     level_map: Record<string, string>;
     request_format: string;
 }
-interface ApiModelShape {
+export interface ApiModel {
     id: string;
     name: string;
     reasoning: boolean;
+    /** Older gateways omit model-specific thinking metadata. */
     thinking?: ApiThinkingCapabilities | null;
+    /** Older gateways omit this field; missing means text-only. */
     vision?: boolean;
     context_length: number;
     max_tokens: number;
+    /** Older gateways omit this field; missing means unknown coverage. */
+    free_package_eligible?: boolean;
     price: {
         input: number;
         output: number;
@@ -43,7 +47,7 @@ interface ApiModelShape {
  * Convert an API model response to our internal ModelDef.
  * Aliases are derived from the short id; note is left empty (filled by /model command).
  */
-export declare function apiModelToDef(m: ApiModelShape): ModelDef;
+export declare function apiModelToDef(m: ApiModel): ModelDef;
 export interface ModelDef {
     id: string;
     name: string;
@@ -62,6 +66,8 @@ export interface ModelDef {
         cacheRead: number;
         cacheWrite: number;
     };
+    /** 网关下发的免费用量包覆盖标记;老网关缺失时为 undefined(不派生 note)。 */
+    freeEligible?: boolean;
     note: string;
 }
 export declare const MODELS: ModelDef[];
@@ -158,4 +164,3 @@ export declare function saveConfig(cfg: CliConfig): void;
 export declare function persistPreferredModel(cfg: CliConfig, provider: string, modelId: string): CliConfig;
 export declare function saveEndpointsCache(endpoints: CustomEndpoint[]): void;
 export declare function loadEndpointsCache(): CustomEndpoint[];
-export {};

package/dist/config.js

@@ -28,6 +28,7 @@ function defaultAliases(id) {
     const aliases = [short, ...parts.filter((p) => p.length > 1)];
     return [...new Set(aliases)];
 }
+// 与 workers/gateway/src/model-thinking.ts 的 THINKING_LEVELS 是同一契约,改动必须双侧同步(gateway test/thinking-levels-contract.test.ts 钉死)。
 export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
 const THINKING_LEVEL_SET = new Set(THINKING_LEVELS);
 function parseThinkingCapabilities(value) {
@@ -75,6 +76,7 @@ export function apiModelToDef(m) {
             cacheRead: m.price.cache_read ?? 0,
             cacheWrite: 0,
         },
+        freeEligible: typeof m.free_package_eligible === "boolean" ? m.free_package_eligible : undefined,
         note: "",
     };
 }
@@ -109,8 +111,32 @@ export const MODELS = [
         note: "更强 · 但烧额度快约 20 倍,难题再用",
     },
 ];
+/**
+ * 按免费包覆盖标记 + 相对默认免费模型的价格倍数派生一句人话提示。
+ * TUI 的模型选择器只渲染 name 一行,note 会被拼进去(见 toProviderModels),
+ * 让人切模型前就知道「这个不走免费包 / 大概贵多少」。
+ */
+function deriveModelNote(m, base) {
+    if (m.freeEligible === true)
+        return "免费用量包可抵扣";
+    if (m.freeEligible === false) {
+        const blended = (m.cost.input + m.cost.output) / 2;
+        const baseBlended = base ? (base.cost.input + base.cost.output) / 2 : 0;
+        const mult = baseBlended > 0 ? Math.round(blended / baseBlended) : 0;
+        return mult >= 2
+            ? `不走免费包 · 费用约为默认模型 ${mult} 倍`
+            : "不走免费包,用余额或全模型包";
+    }
+    return "";
+}
 /** Replace MODELS with a fresh list fetched from server (e.g. at startup). */
 export function setModelsFromApi(apiModels) {
+    const base = apiModels.find((m) => m.id === DEFAULT_MODEL_ID)
+        ?? apiModels.find((m) => m.freeEligible === true);
+    for (const m of apiModels) {
+        if (!m.note)
+            m.note = deriveModelNote(m, base);
+    }
     MODELS.length = 0;
     MODELS.push(...apiModels);
 }

package/dist/deploy.d.ts

@@ -12,5 +12,6 @@ interface DeployArgs {
     visibility?: SiteVisibility;
 }
 export declare function parseDeployArgs(args: string[]): DeployArgs;
+export declare function printDeployHelp(): void;
 export declare function deployCommand(cfg: CliConfig, args: string[]): Promise<void>;
 export {};

package/dist/deploy.js

@@ -342,8 +342,22 @@ function printDeploymentResult(result, start) {
     console.log("  改完代码再跑一次 u1s1 deploy 即可更新。");
     console.log("");
 }
+export function printDeployHelp() {
+    console.log("");
+    console.log("  u1s1 deploy [目录] [--name 站点名] [--public|--private]");
+    console.log("");
+    console.log("    不带参数时自动找构建产物目录(dist/build/out 等),否则用当前目录。");
+    console.log("    首次发布会问项目名和公开/私密,之后记住;再跑一次即为更新。");
+    console.log("");
+    console.log("  u1s1 deploy list    查看已发布的站点");
+    console.log("");
+}
 export async function deployCommand(cfg, args) {
     // 参数:[dir] [--name xxx] [--public|--private];u1s1 deploy list 列出已有站点
+    if (args.includes("--help") || args.includes("-h")) {
+        printDeployHelp();
+        return;
+    }
     if (args[0] === "list") {
         await listDeployments(cfg);
         return;

package/dist/error-humanize.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 模型调用失败时,网关的中文说明会被 OpenAI SDK + pi-ai 包成
+ * `429: {"message":"…","type":"…","code":"…"}` 直出到聊天区。
+ * 这里把 JSON 里的 message 提出来当正文,状态码与错误代号收进尾巴。
+ *
+ * 尾巴不是装饰,必须保留:pi 按 errorMessage 正则做三类分类——
+ * - 重试:429/5xx 数字、rate_limit、fetch failed 等(retry.js RETRYABLE)
+ * - 不重试:insufficient_quota(额度用尽时快速失败,不做无谓退避)
+ * - 上下文超长:context_length_exceeded(触发自动压缩而非重试)
+ * 改写后的文本必须与原文落进同一分类,否则会破坏重试/压缩行为。
+ *
+ * 网关会在错误 JSON 里注入 error.request_id(见 gateway request-id.ts),
+ * 拼进尾巴让用户报障时有编号可给,客服凭它直查日志和 usage 记录。
+ */
+export declare function humanizeModelError(raw: string): string | undefined;

package/dist/error-humanize.js

@@ -0,0 +1,47 @@
+/**
+ * 模型调用失败时,网关的中文说明会被 OpenAI SDK + pi-ai 包成
+ * `429: {"message":"…","type":"…","code":"…"}` 直出到聊天区。
+ * 这里把 JSON 里的 message 提出来当正文,状态码与错误代号收进尾巴。
+ *
+ * 尾巴不是装饰,必须保留:pi 按 errorMessage 正则做三类分类——
+ * - 重试:429/5xx 数字、rate_limit、fetch failed 等(retry.js RETRYABLE)
+ * - 不重试:insufficient_quota(额度用尽时快速失败,不做无谓退避)
+ * - 上下文超长:context_length_exceeded(触发自动压缩而非重试)
+ * 改写后的文本必须与原文落进同一分类,否则会破坏重试/压缩行为。
+ *
+ * 网关会在错误 JSON 里注入 error.request_id(见 gateway request-id.ts),
+ * 拼进尾巴让用户报障时有编号可给,客服凭它直查日志和 usage 记录。
+ */
+export function humanizeModelError(raw) {
+    const jsonStart = raw.indexOf("{");
+    const jsonEnd = raw.lastIndexOf("}");
+    if (jsonStart === -1 || jsonEnd <= jsonStart)
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw.slice(jsonStart, jsonEnd + 1));
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed === null || typeof parsed !== "object")
+        return undefined;
+    const root = parsed;
+    const err = root["error"] !== null && typeof root["error"] === "object"
+        ? root["error"]
+        : root;
+    const message = typeof err["message"] === "string" ? err["message"].trim() : "";
+    if (!message)
+        return undefined;
+    const code = typeof err["code"] === "string" ? err["code"] : "";
+    const type = typeof err["type"] === "string" ? err["type"] : "";
+    const status = /(?:^|\s|\()(\d{3})\b/.exec(raw.slice(0, jsonStart))?.[1];
+    const requestId = typeof err["request_id"] === "string" ? err["request_id"] : "";
+    const tags = [
+        status ? `HTTP ${status}` : "",
+        type === "insufficient_quota" || code === "quota_exceeded" ? "insufficient_quota" : code,
+        requestId ? `请求编号 ${requestId}` : "",
+    ].filter(Boolean);
+    const friendly = tags.length ? `${message} (${tags.join(" · ")})` : message;
+    return friendly === raw ? undefined : friendly;
+}

package/dist/index.js

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 import { execSync, spawnSync } from "node:child_process";
 import { writeFileSync } from "node:fs";
-import { cleanupBrandThemes, endpointKeyEnv, endpointProviderEntry, ensureBrandPrompt, ensureDefaultSettings, ensureProviderModels, ensureWorkflowPromptTemplate, scrubForeignProviderEnv, toProviderModels, writeAttributionExtension, writeCompactUiExtension, writeWebToolsExtension, } from "./agent-setup.js";
+import { cleanupBrandThemes, endpointKeyEnv, endpointProviderEntry, ensureBrandPrompt, ensureDefaultSettings, ensureProviderModels, ensureWorkflowPromptTemplate, scrubForeignProviderEnv, toProviderModels, writeAttributionExtension, writeCompactUiExtension, writeErrorHumanizeExtension, writeWebToolsExtension, } from "./agent-setup.js";
+import { Text } from "@earendil-works/pi-tui";
 import { printConsoleBanner } from "./brand.js";
 import { agentDir, apiModelToDef, CUSTOM_ENDPOINTS, isPortableInstall, loadConfig, MODELS, persistPreferredModel, PROVIDER_ID, readSettings, refValid, resolvePreferredModel, setModelsFromApi, VERSION, } from "./config.js";
 import { registerLoopCommand } from "./loop.js";
@@ -220,6 +221,8 @@ async function runAgent(cfg, args) {
     });
     // 精简 UI：隐藏工具调用 + 汇总行 + 隐藏思考标签（同样投影到 agentDir/extensions）
     writeCompactUiExtension();
+    // 模型调用错误人话化（同样投影,Desktop App 共享）
+    writeErrorHumanizeExtension();
     // OpenRouter 应用归因：直连流量计入 u1s1 的公开排行
     writeAttributionExtension();
     ensureTmuxKeyboardProtocol();
@@ -296,6 +299,41 @@ async function runAgent(cfg, args) {
                         ctx.shutdown();
                     },
                 });
+                // /help:启动横幅和官网教程都在引导用户输入它,必须真实存在
+                pi.registerEntryRenderer("u1s1-help", (_entry, _opts, theme) => {
+                    const text = [
+                        theme.bold(theme.fg("text", "u1s1 常用操作")),
+                        theme.fg("text", "直接打字说需求,回车发送 · Shift+Enter 换行 · Ctrl+V 贴图 · Esc 中断"),
+                        theme.fg("text", "/model 切换模型(留意免费/价格提示) · /clear 清空上下文开新会话"),
+                        theme.fg("text", "/usage 查剩余额度 · /resume 恢复历史会话 · /settings 设置"),
+                        theme.fg("dim", "/compact 压缩上下文 · /hotkeys 全部快捷键(英文) · /exit 退出"),
+                        theme.fg("dim", "退出后在终端:u1s1 deploy 发布网页 · u1s1 update 升级"),
+                        theme.fg("dim", "新手教程 → https://u1s1.io/guides"),
+                    ].join("\n");
+                    return new Text(text, 1, 0);
+                });
+                pi.registerCommand("help", {
+                    description: "查看常用操作和命令",
+                    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: "查看剩余额度和本月用量",
+                    handler: async () => {
+                        const { usageEntryData } = await import("./usage.js");
+                        pi.appendEntry("u1s1-usage", await usageEntryData());
+                    },
+                });
+                // 模型调用错误人话化不在这里注册:走 writeErrorHumanizeExtension 投影,
+                // TUI 和 Desktop App 共用一份(见 agent-setup.ts)
                 // /clear: 清空当前对话上下文，开始新会话
                 pi.registerCommand("clear", {
                     description: "清除当前对话上下文，开始新会话",
@@ -358,21 +396,23 @@ async function run() {
         console.log(`u1s1 v${VERSION}`);
         return;
     }
-    if (cmd === "--help" || cmd === "-h") {
+    if (cmd === "--help" || cmd === "-h" || cmd === "help") {
         printConsoleBanner(VERSION);
-        console.log(" u1s1 命令:deploy(发布网页,可选 --public / --private)· login / logout · model · usage · update · import · bench");
-        console.log("");
         console.log(" 命令:");
+        console.log("   u1s1                   进入对话界面(最常用,不带参数)");
+        console.log("   u1s1 -p \"一句话\"       不进界面直接回答,适合脚本里用");
         console.log("   u1s1 login / logout    登录 / 退出登录");
         console.log("   u1s1 model             查看或切换默认模型");
-        console.log("   u1s1 usage             查看免费额度和余额");
+        console.log("   u1s1 usage             查看剩余额度");
         console.log("   u1s1 update            升级到最新版");
-        console.log("   u1s1 deploy            发布网页,可选 --public / --private");
+        console.log("   u1s1 deploy            发布网页(--public / --private)");
+        console.log("   u1s1 deploy list       查看已发布的站点");
         console.log("   u1s1 import            导入历史会话");
+        console.log("   u1s1 bench             模型编码能力评测");
         console.log("   u1s1 --version         查看版本");
         console.log("");
-        console.log(" 对话里输入 / 可以看会话内命令(/model /clear /exit …)");
-        console.log(" 更多帮助 → https://u1s1.io/guide");
+        console.log(" 对话里输入 /help 看会话内命令(/model /clear /exit …)");
+        console.log(" 更多帮助 → https://u1s1.io/guides");
         return;
     }
     if (cmd === "web") {
@@ -381,9 +421,14 @@ async function run() {
         return;
     }
     if (cmd === "deploy") {
+        const { deployCommand, printDeployHelp } = await import("./deploy.js");
+        // --help 不该先被拽去登录
+        if (args.slice(1).includes("--help") || args.slice(1).includes("-h")) {
+            printDeployHelp();
+            return;
+        }
         const { ensureAuth } = await import("./login.js");
         const cfg = await ensureAuth();
-        const { deployCommand } = await import("./deploy.js");
         await deployCommand(cfg, args.slice(1));
         return;
     }
@@ -447,6 +492,20 @@ async function run() {
         await benchCommand(args.slice(1));
         return;
     }
+    // 拼错的子命令(如 `u1s1 depoly`)不该被静默当成第一条消息发给模型白烧 token。
+    // 只拦「单个短英文词 + 与已知命令编辑距离很近」的情况,正常 prompt 不受影响。
+    if (cmd
+        && args.length === 1
+        && /^[a-z][a-z0-9-]{1,15}$/.test(cmd)
+        && !KNOWN_COMMANDS.includes(cmd)) {
+        const near = KNOWN_COMMANDS.find((k) => editDistance(k, cmd) <= (k.length <= 4 ? 1 : 2));
+        if (near) {
+            console.error(`不认识的命令「${cmd}」,你是不是想运行:u1s1 ${near}`);
+            console.error("查看全部命令:u1s1 --help;直接开始对话:运行 u1s1(不带参数)");
+            process.exitCode = 1;
+            return;
+        }
+    }
     const { ensureAuth } = await import("./login.js");
     const cfg = await ensureAuth();
     // 在后台检查更新（非阻塞，不影响启动速度）
@@ -455,6 +514,21 @@ async function run() {
     // autoUpdate 开着且启动时发现了新版:现在装(TUI 已退出,原地重铺安全)
     installPendingUpdate();
 }
+const KNOWN_COMMANDS = ["deploy", "login", "logout", "usage", "model", "update", "import", "bench", "help", "web"];
+/** 经典 Levenshtein,命令名都很短,O(nm) 足够。 */
+function editDistance(a, b) {
+    const dp = Array.from({ length: a.length + 1 }, (_, i) => i);
+    for (let j = 1; j <= b.length; j++) {
+        let prev = dp[0];
+        dp[0] = j;
+        for (let i = 1; i <= a.length; i++) {
+            const cur = dp[i];
+            dp[i] = Math.min(dp[i] + 1, dp[i - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+            prev = cur;
+        }
+    }
+    return dp[a.length];
+}
 run().catch((e) => {
     console.error(e instanceof Error ? e.message : e);
     process.exit(1);

package/dist/login.d.ts

@@ -10,8 +10,15 @@ export interface DeviceStart {
     private_jwk: webcrypto.JsonWebKey;
     public_jwk: webcrypto.JsonWebKey;
 }
-/** 发起浏览器设备登录；网关不支持或网络不可用时返回 null。 */
-export declare function startDeviceLogin(origin: string): Promise<DeviceStart | null>;
+/**
+ * 发起浏览器设备登录；网关不支持或网络不可用时返回 null。
+ * 服务器主动拒绝(限流/风控)时把原因带出到 failure —— 否则「请求太频繁」
+ * 会被误报成「检查网络」,用户怎么查网络都查不出问题。
+ */
+export declare function startDeviceLogin(origin: string, failure?: {
+    status?: number;
+    message?: string;
+}): Promise<DeviceStart | null>;
 export interface DeviceLoginResult {
     apiKey: string;
     deviceToken: string;

package/dist/login.js

@@ -36,8 +36,12 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export function apiOrigin(cfg) {
     return cfg.baseUrl.replace(/\/v1\/?$/, "");
 }
-/** 发起浏览器设备登录；网关不支持或网络不可用时返回 null。 */
-export async function startDeviceLogin(origin) {
+/**
+ * 发起浏览器设备登录；网关不支持或网络不可用时返回 null。
+ * 服务器主动拒绝(限流/风控)时把原因带出到 failure —— 否则「请求太频繁」
+ * 会被误报成「检查网络」,用户怎么查网络都查不出问题。
+ */
+export async function startDeviceLogin(origin, failure) {
     try {
         const pair = await generateDeviceKeyPair();
         const resp = await fetch(`${origin}/auth/device/start`, {
@@ -51,7 +55,17 @@ export async function startDeviceLogin(origin) {
             signal: AbortSignal.timeout(15_000),
         });
         if (!resp.ok) {
-            void resp.body?.cancel("device login start rejected").catch(() => { });
+            if (failure) {
+                failure.status = resp.status;
+                const body = await readJsonResponseCapped(resp, MAX_DEVICE_AUTH_RESPONSE_BYTES).catch(() => null);
+                const message = body?.error?.message;
+                if (typeof message === "string" && message && message.length <= 500) {
+                    failure.message = message;
+                }
+            }
+            else {
+                void resp.body?.cancel("device login start rejected").catch(() => { });
+            }
             return null;
         }
         const data = await readJsonResponseCapped(resp, MAX_DEVICE_AUTH_RESPONSE_BYTES);
@@ -134,10 +148,19 @@ export async function login(keyArg) {
     }
     printConsoleBanner(VERSION);
     const origin = apiOrigin(cfg);
-    const start = await startDeviceLogin(origin);
+    const failure = {};
+    const start = await startDeviceLogin(origin, failure);
     if (!start) {
-        console.error("  连不上 u1s1 服务器,请检查网络后重试。");
-        console.error("  如果网络正常,可能是 u1s1 版本太旧,运行 u1s1 update 升级后再试。");
+        if (failure.message) {
+            // 服务器有明确说法(限流/风控等),原样转达,别伪装成网络问题
+            console.error(`  服务器没有接受登录请求:${failure.message}`);
+            if (failure.status === 429)
+                console.error("  稍等几分钟再运行 u1s1 login 重试即可。");
+        }
+        else {
+            console.error("  连不上 u1s1 服务器,请检查网络后重试。");
+            console.error("  如果网络正常,可能是 u1s1 版本太旧,运行 u1s1 update 升级后再试。");
+        }
         process.exit(1);
     }
     console.log("  用浏览器登录并批准这台设备:");

package/dist/model.js

@@ -14,6 +14,9 @@ export async function refreshOfficialModels(cfg, fetcher = fetchModels) {
     }
 }
 export async function modelCommand(nameOrAlias) {
+    // `u1s1 model --help` 不该被当成模型名报错;直接展示列表(自带切换说明)
+    if (nameOrAlias === "--help" || nameOrAlias === "-h")
+        nameOrAlias = undefined;
     const cfg = loadConfig();
     // Fetch both live catalogues before resolving the persisted default.
     const [officialModelsError] = await Promise.all([

package/dist/style.js

@@ -1,3 +1,4 @@
+import { readdirSync } from "node:fs";
 import { basename } from "node:path";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import { readSettings } from "./config.js";
@@ -26,6 +27,15 @@ export function applyBrandUi(pi, version) {
     pi.on("session_start", async (_event, ctx) => {
         if (ctx.mode !== "tui")
             return;
+        // 空目录首跑:横幅下给几句可照抄的开场 prompt(dotfile 不算「有内容」)
+        const starterTips = (() => {
+            try {
+                return readdirSync(process.cwd()).filter((n) => !n.startsWith(".")).length === 0;
+            }
+            catch {
+                return false;
+            }
+        })();
         // 检查设置:关掉就不显示启动横幅
         const settings = readSettings();
         if (settings.showStartupBanner !== false) {
@@ -40,6 +50,7 @@ export function applyBrandUi(pi, version) {
                             width,
                             notice: updateNotice,
                             announcement,
+                            starterTips,
                         }).map((line) => truncateToWidth(line, width));
                     },
                     invalidate() { },

package/dist/usage.d.ts

@@ -1 +1,9 @@
+import { type MeResponse } from "./api.js";
+/** 额度报告正文(不含首尾空行),终端 `u1s1 usage` 和会话内 /usage 共用。 */
+export declare function usageReportLines(me: MeResponse): string[];
+/** 会话内 /usage 用:拉取额度并打包成 entry data,错误转成中文提示而不是抛出。 */
+export declare function usageEntryData(): Promise<{
+    lines?: string[];
+    error?: string;
+}>;
 export declare function usage(): Promise<void>;

package/dist/usage.js

@@ -26,6 +26,7 @@ const PACKAGE_LABELS = {
     invite: "邀请赠送",
     new_user: "新用户赠送",
     login_checkin: "登录打卡",
+    login_checkin_bonus: "打卡加成",
     payment_delay_gift: "临时加量包",
     topup_daily: "每日加量包",
     admin_grant: "官方赠送",
@@ -61,58 +62,82 @@ function packageLabel(pkg) {
     const count = pkg.count > 1 ? ` ×${pkg.count}` : "";
     return `${PACKAGE_LABELS[pkg.kind] ?? pkg.kind}${count}`.padEnd(5, "　");
 }
-function printPackage(pkg) {
+function packageLines(pkg) {
     const isDaily = pkg.daily_tokens != null;
     const total = isDaily ? (pkg.daily_tokens ?? 0) : (pkg.total_tokens ?? 0);
     const ratio = total > 0 ? pkg.remaining / total : 0;
-    console.log(`  ${packageLabel(pkg)} 还剩 ${fmtTokensCn(pkg.remaining)} / ${fmtTokensCn(total)}${isDaily ? "/天" : ""}  ${bar(ratio)}`);
     const expiry = pkg.expires_at ? `${pkg.expires_at.slice(0, 10)} 到期` : "永不过期";
-    console.log(`             ${packageScopeNote(pkg)} · ${expiry}`);
+    return [
+        `  ${packageLabel(pkg)} 还剩 ${fmtTokensCn(pkg.remaining)} / ${fmtTokensCn(total)}${isDaily ? "/天" : ""}  ${bar(ratio)}`,
+        `             ${packageScopeNote(pkg)} · ${expiry}`,
+    ];
 }
-function printPackageUsage(me, tokensPerUsd) {
+function packageUsageLines(me, tokensPerUsd) {
     const packages = me.packages ?? [];
+    const lines = [];
     if (packages.length === 0)
-        console.log("  用量包     (无生效中的用量包)");
+        lines.push("  用量包     (无生效中的用量包)");
     for (const pkg of groupPackages(packages))
-        printPackage(pkg);
+        lines.push(...packageLines(pkg));
     if (me.bonus_balance_usd > 0) {
         const balance = tokensPerUsd > 0
             ? `${fmtTokensCn(me.bonus_balance_usd * tokensPerUsd)} Token`
             : `$${me.bonus_balance_usd.toFixed(2)}`;
-        console.log(`  余额(按量) ${balance}`);
+        lines.push(`  余额(按量) ${balance}`);
     }
     const monthlyUsage = tokensPerUsd > 0
         ? `约 ${fmtTokensCn(me.mtd_usd * tokensPerUsd)} Token($${me.mtd_usd.toFixed(2)})`
         : `$${me.mtd_usd.toFixed(2)}`;
-    console.log(`  本月已用   ${monthlyUsage}`);
-    console.log("");
-    console.log("  免费用量包覆盖 DeepSeek V4 Flash / Vision、GLM-5.3 Flash、Qwen3.8 Flash 和联网搜索。");
-    console.log("  DeepSeek V4 Pro 仅可使用余额 → https://u1s1.io/dashboard");
-    console.log("  Token 数按默认模型单价折算,为约数;用更贵的模型时消耗更快。");
-    console.log("");
+    lines.push(`  本月已用   ${monthlyUsage}`);
+    lines.push("");
+    lines.push("  免费用量包覆盖 DeepSeek V4 Flash / Vision、GLM-5.3 Flash、Qwen3.8 Flash 和联网搜索。");
+    lines.push("  其他模型(如 DeepSeek V4 Pro)不走免费包，可用余额或全模型包 → https://u1s1.io/dashboard");
+    lines.push("  Token 数按默认模型单价折算,为约数;用更贵的模型时消耗更快。");
+    return lines;
 }
-function printLegacyUsage(me, tokensPerUsd) {
+function legacyUsageLines(me, tokensPerUsd) {
     const freeRemain = me.daily_free_remaining_usd;
     const freeTotal = me.daily_free_usd;
     const freeRatio = freeTotal > 0 ? freeRemain / freeTotal : 0;
+    const lines = [];
     if (tokensPerUsd > 0) {
         const tokens = (usd) => `${fmtTokensCn(usd * tokensPerUsd)} Token`;
-        console.log(`  今日免费   还剩 ${fmtTokensCn(freeRemain * tokensPerUsd)} / ${tokens(freeTotal)}  ${bar(freeRatio)}`);
-        console.log("             DeepSeek V4 Flash · 北京时间 0 点恢复");
-        console.log(`  永久余额   ${tokens(me.remaining_usd)}`);
-        console.log(`  本月已用   约 ${tokens(me.mtd_usd)}($${me.mtd_usd.toFixed(2)})`);
-        console.log("");
-        console.log("  Token 数按默认模型单价折算,为约数;用更贵的模型时消耗更快。");
+        lines.push(`  今日免费   还剩 ${fmtTokensCn(freeRemain * tokensPerUsd)} / ${tokens(freeTotal)}  ${bar(freeRatio)}`);
+        lines.push("             DeepSeek V4 Flash · 北京时间 0 点恢复");
+        lines.push(`  永久余额   ${tokens(me.remaining_usd)}`);
+        lines.push(`  本月已用   约 ${tokens(me.mtd_usd)}($${me.mtd_usd.toFixed(2)})`);
+        lines.push("");
+        lines.push("  Token 数按默认模型单价折算,为约数;用更贵的模型时消耗更快。");
     }
     else {
-        console.log(`  今日免费   $${freeRemain.toFixed(2)} / $${freeTotal.toFixed(2)}  ${bar(freeRatio)}`);
-        console.log("             DeepSeek V4 Flash · 北京时间 0 点恢复");
-        console.log(`  永久余额   $${me.remaining_usd.toFixed(2)}`);
-        console.log(`  本月成本   $${me.mtd_usd.toFixed(2)}`);
+        lines.push(`  今日免费   $${freeRemain.toFixed(2)} / $${freeTotal.toFixed(2)}  ${bar(freeRatio)}`);
+        lines.push("             DeepSeek V4 Flash · 北京时间 0 点恢复");
+        lines.push(`  永久余额   $${me.remaining_usd.toFixed(2)}`);
+        lines.push(`  本月成本   $${me.mtd_usd.toFixed(2)}`);
+    }
+    lines.push("");
+    lines.push("  免费额度每天自动恢复；邀请朋友双方各得永久加量 → https://u1s1.io/dashboard");
+    return lines;
+}
+/** 额度报告正文(不含首尾空行),终端 `u1s1 usage` 和会话内 /usage 共用。 */
+export function usageReportLines(me) {
+    const tokensPerUsd = me.tokens_per_usd ?? 0;
+    return [
+        `  账号       ${me.email ?? "(未绑定邮箱)"}`,
+        ...(me.packages ? packageUsageLines(me, tokensPerUsd) : legacyUsageLines(me, tokensPerUsd)),
+    ];
+}
+/** 会话内 /usage 用:拉取额度并打包成 entry data,错误转成中文提示而不是抛出。 */
+export async function usageEntryData() {
+    const cfg = loadConfig();
+    if (!hasDeviceCredential(cfg))
+        return { error: "还没登录，先在终端运行 u1s1 login" };
+    try {
+        return { lines: usageReportLines(await fetchMe(cfg)) };
+    }
+    catch (e) {
+        return { error: e instanceof Error ? e.message : String(e) };
     }
-    console.log("");
-    console.log("  免费额度每天自动恢复；邀请朋友双方各得永久加量 → https://u1s1.io/dashboard");
-    console.log("");
 }
 export async function usage() {
     const cfg = loadConfig();
@@ -124,12 +149,8 @@ export async function usage() {
         console.error(e.message);
         process.exit(1);
     });
-    const tokensPerUsd = me.tokens_per_usd ?? 0;
     console.log("");
-    console.log(`  账号       ${me.email ?? "(未绑定邮箱)"}`);
-    if (me.packages) {
-        printPackageUsage(me, tokensPerUsd);
-        return;
-    }
-    printLegacyUsage(me, tokensPerUsd);
+    for (const line of usageReportLines(me))
+        console.log(line);
+    console.log("");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "u1s1-cli",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "u1s1 — 有一说一,最省心的 AI 编程搭子。终端里用中文说需求,AI 帮你读文件、改代码、跑命令。",
   "type": "module",
   "bin": {

package/scripts/patch-pi.js

@@ -76,6 +76,58 @@ const COMPACT_UI_REPLACEMENTS = [
   ],
 ];
 
+// 内置斜杠命令描述汉化(dist/core/slash-commands.js),与 pnpm coding-agent patch 同步。
+const SLASH_COMMANDS_REPLACEMENTS = [
+  ['{ name: "settings", description: "Open settings menu" },', '{ name: "settings", description: "打开设置菜单" },'],
+  ['{ name: "model", description: "Select model (opens selector UI)", argumentHint: "<provider/model>" },', '{ name: "model", description: "切换模型(列表里有免费/价格提示)", argumentHint: "<provider/model>" },'],
+  ['{ name: "tree", description: "Navigate session tree (switch branches)" },', '{ name: "tree", description: "查看会话分支树,切换分支" },'],
+  ['{ name: "thinking", description: "Set thinking level", argumentHint: "<level>" },', '{ name: "thinking", description: "调整思考强度(想得越深越费额度)", argumentHint: "<level>" },'],
+  ['{ name: "scoped-models", description: "Enable/disable models for Ctrl+P cycling" },', '{ name: "scoped-models", description: "设置 Ctrl+P 轮换的模型范围" },'],
+  ['{ name: "export", description: "Export session (HTML default, or specify path: .html/.jsonl)" },', '{ name: "export", description: "导出会话(默认 HTML,也可指定 .html/.jsonl 路径)" },'],
+  ['{ name: "import", description: "Import and resume a session from a JSONL file" },', '{ name: "import", description: "从 JSONL 文件导入并继续会话" },'],
+  ['{ name: "share", description: "Share session as a secret GitHub gist" },', '{ name: "share", description: "把会话分享为 GitHub 私密 gist" },'],
+  ['{ name: "copy", description: "Copy last agent message to clipboard" },', '{ name: "copy", description: "复制上一条回复到剪贴板" },'],
+  ['{ name: "name", description: "Set session display name" },', '{ name: "name", description: "给当前会话起个名字" },'],
+  ['{ name: "session", description: "Show session info and stats" },', '{ name: "session", description: "查看会话信息与统计" },'],
+  ['{ name: "changelog", description: "Show changelog entries" },', '{ name: "changelog", description: "查看引擎更新日志(英文)" },'],
+  ['{ name: "hotkeys", description: "Show all keyboard shortcuts" },', '{ name: "hotkeys", description: "查看全部快捷键(英文)" },'],
+  ['{ name: "fork", description: "Create a new fork from a previous user message" },', '{ name: "fork", description: "从之前某条消息分叉出一个新会话" },'],
+  ['{ name: "clone", description: "Duplicate the current session at the current position" },', '{ name: "clone", description: "复制当前会话再继续" },'],
+  ['{ name: "trust", description: "Save project trust decision for future sessions" },', '{ name: "trust", description: "记住对这个项目目录的信任选择" },'],
+  ['{ name: "login", description: "Configure provider authentication", argumentHint: "<provider>" },', '{ name: "login", description: "换 u1s1 账号请先 /exit,再运行 u1s1 login", argumentHint: "<provider>" },'],
+  ['{ name: "logout", description: "Remove provider authentication" },', '{ name: "logout", description: "退出登录请先 /exit,再运行 u1s1 logout" },'],
+  ['{ name: "new", description: "Start a new session" },', '{ name: "new", description: "开始新会话" },'],
+  ['{ name: "compact", description: "Manually compact the session context" },', '{ name: "compact", description: "压缩会话上下文,腾出空间继续聊" },'],
+  ['{ name: "resume", description: "Resume a different session" },', '{ name: "resume", description: "恢复或切换到其他会话" },'],
+  ['{ name: "reload", description: "Reload keybindings, extensions, skills, prompts, themes, and context files" },', '{ name: "reload", description: "重新加载扩展、技能、主题等资源" },'],
+  ['{ name: "quit", description: `Quit ${APP_NAME}` },', '{ name: "quit", description: `退出 ${APP_NAME}` },'],
+];
+
+function patchSlashCommands() {
+  for (const piDir of findPackageDirs("@earendil-works/pi-coding-agent")) {
+    const target = join(piDir, "dist", "core", "slash-commands.js");
+    try {
+      let text = readFileSync(target, "utf8");
+      if (text.includes("打开设置菜单")) continue; // pnpm patch 或此前运行已应用
+
+      let applied = 0;
+      for (const [from, to] of SLASH_COMMANDS_REPLACEMENTS) {
+        if (!text.includes(from)) continue;
+        text = text.split(from).join(to);
+        applied++;
+      }
+      if (applied < SLASH_COMMANDS_REPLACEMENTS.length) {
+        console.log(
+          `[u1s1] 提示: pi 版本可能已更新，命令描述汉化只应用了 ${applied}/${SLASH_COMMANDS_REPLACEMENTS.length} 处（不影响使用）`,
+        );
+      }
+      writeFileSync(target, text);
+    } catch {
+      continue;
+    }
+  }
+}
+
 function patchCompactUi() {
   const piDirs = findPackageDirs("@earendil-works/pi-coding-agent");
   if (piDirs.length === 0) {
@@ -166,6 +218,7 @@ const ENABLE_AUTOWRAP = "\\x1b[?7h";`,
 
 try {
   patchCompactUi();
+  patchSlashCommands();
   patchMainScreenAutowrap();
 } catch (err) {
   console.log(`[u1s1] 提示: pi 运行时补丁未生效（${err?.message ?? err}），不影响安装`);