u1s1-cli 1.14.6 → 1.15.0

package/dist/agents/status.d.ts

@@ -0,0 +1,20 @@
+import { type DefaultAgent } from "../config.js";
+import { type LaunchPaths } from "./launch.js";
+import { dailyUpdateCheck, ensureAgentRuntime, type ManagedAgent } from "./runtime.js";
+export declare function launchPaths(agent: ManagedAgent): LaunchPaths;
+export declare function printAgentsStatus(defaultAgent: DefaultAgent | undefined): Promise<void>;
+export declare function pinCommand(raw: string | undefined, agent?: ManagedAgent): Promise<number>;
+export declare function unpinCommand(agent?: ManagedAgent): number;
+export interface InstallCommandDeps {
+    /** GET /public/agents/:agent/runtime;测试注入 */
+    fetchPublicRuntime?: (url: URL) => Promise<Response>;
+    ensure?: typeof ensureAgentRuntime;
+    checkLatest?: typeof dailyUpdateCheck;
+}
+/**
+ * `u1s1 agents install claude|codex`:找到或下载原版,不启动。与 `u1s1 claude` / `u1s1 codex` 走同一套
+ * ensureAgentRuntime:首次从官方下载前同样要用户确认(没有终端就不下载)。
+ * 不需要登录。刹车用缓存的网关配置;没有缓存时问网关的公开刹车接口,问不到就不下载。
+ * 缓存里或公开接口明确停用时不下载。
+ */
+export declare function installCommand(deps?: InstallCommandDeps, agent?: ManagedAgent): Promise<number>;

package/dist/agents/status.js

@@ -0,0 +1,241 @@
+/**
+ * `u1s1 agents`:各客户端的安装状态、版本、是否有更新;`pin` / `unpin` 锁定版本;
+ * `install` 只下载不启动(安装脚本预选客户端时用)。
+ * 刹车用上次成功拉到的网关配置(缓存);没有缓存时 status / pin 只按版本号格式校验,
+ * install 改问网关的公开刹车接口,问不到就不下载。
+ */
+import { mkdirSync } from "node:fs";
+import { loadConfig, VERSION } from "../config.js";
+import { gatewayFetch } from "../gateway-route.js";
+import { tr } from "../i18n.js";
+import { siteOf } from "../site.js";
+import { loadPublicAgentRuntime, parseAgentConfig, readConfigCache } from "./agent-config.js";
+import { claudePaths } from "./claude.js";
+import { codexPaths } from "./codex.js";
+import { AGENT_PROFILES, agentsRoot, cliInstallHooks, notOpenText, printRuntimeFailure, printRuntimeNotes, } from "./launch.js";
+import { readAgentPrefs } from "./prefs.js";
+import { bestInstallTarget, checkBrake, compareVersions, dailyUpdateCheck, ensureAgentRuntime, fetchLatestVersion, findOnPath, installedVersions, MANAGED_AGENTS, NO_BRAKE, normalizeVersion, npmRegistryFor, probeVersion, readRuntimeState, runtimeSpec, updateRuntimeState, } from "./runtime.js";
+export function launchPaths(agent) {
+    return agent === "codex" ? codexPaths() : claudePaths();
+}
+function cachedConfig(agent) {
+    const cfg = loadConfig();
+    const cached = readConfigCache(launchPaths(agent).configCache, new URL(cfg.baseUrl).origin);
+    return cached ? parseAgentConfig(cached.body, AGENT_PROFILES[agent].gatewayAgent) : undefined;
+}
+function cachedBrake(agent) {
+    return cachedConfig(agent)?.runtime ?? NO_BRAKE;
+}
+function verdictText(v, brake) {
+    if (v === "blocked")
+        return tr("该版本已被停用", "this version has been disabled");
+    if (v === "below_min")
+        return tr(`低于最低要求 ${brake.minVersion}`, `below the minimum ${brake.minVersion}`);
+    return tr(`高于已验证的最高版本 ${brake.maxTestedVersion}`, `above the highest tested version ${brake.maxTestedVersion}`);
+}
+export async function printAgentsStatus(defaultAgent) {
+    const mark = (agent) => (defaultAgent === agent ? tr("  [默认]", "  [default]") : "");
+    console.log(tr("客户端", "Clients"));
+    console.log(`  pi      ${tr(`内置,随 u1s1 v${VERSION} 发布`, `built in, ships with u1s1 v${VERSION}`)}${mark("pi")}`);
+    for (const agent of MANAGED_AGENTS) {
+        const lines = await managedAgentLines(agent);
+        console.log(`  ${agent.padEnd(6)}  ${lines[0]}${mark(agent)}`);
+        for (const line of lines.slice(1))
+            console.log(`          ${line}`);
+    }
+}
+async function managedAgentLines(agent) {
+    const cfg = loadConfig();
+    const site = siteOf(cfg);
+    const spec = runtimeSpec(agent);
+    const cached = cachedConfig(agent);
+    const brake = cached?.runtime ?? NO_BRAKE;
+    const paths = launchPaths(agent);
+    const state = readRuntimeState(paths);
+    const installed = installedVersions(paths, spec);
+    const managed = state.current && installed.includes(state.current) ? state.current : installed[0];
+    const envBin = process.env[spec.binEnv]?.trim();
+    const pathBin = findOnPath(spec.command, { env: process.env, platform: process.platform });
+    // 探测用户自己的命令时把配置目录指到启动器自己的目录(CODEX_HOME 指向不存在的目录时 Codex 会报错)
+    if (envBin || pathBin)
+        mkdirSync(paths.configDir, { recursive: true, mode: 0o700 });
+    const pathVersion = pathBin ? probeVersion(pathBin, paths.configDir, spec) : undefined;
+    const latest = await fetchLatestVersion(npmRegistryFor(site.id), spec.npmPackage);
+    const autoUpdate = readAgentPrefs(agent).autoUpdate;
+    const lines = [];
+    if (cached && !cached.enabled) {
+        lines.push(tr(`暂不可用:${cached.disabledReason ?? notOpenText()}`, `Not available: ${cached.disabledReason ?? notOpenText()}`));
+    }
+    if (envBin) {
+        const v = probeVersion(envBin, paths.configDir, spec);
+        lines.push(tr(`使用 ${spec.binEnv} 指定的 ${envBin}(${v ?? "无法运行"})`, `Using ${envBin} from ${spec.binEnv} (${v ?? "doesn't run"})`));
+        if (v && checkBrake(v, brake) === "above_max_tested") {
+            lines.push(tr(`它${verdictText("above_max_tested", brake)},运行时改用 u1s1 管理的版本`, `It's ${verdictText("above_max_tested", brake)}; u1s1 ${agent} uses a u1s1-managed copy instead`));
+        }
+    }
+    else if (managed) {
+        lines.push(tr(`已安装 ${managed}(由 u1s1 管理)`, `Installed ${managed} (managed by u1s1)`));
+    }
+    else if (pathVersion && checkBrake(pathVersion, brake) === "ok") {
+        lines.push(tr(`使用本机已有的 ${pathBin}(${pathVersion})`, `Using the existing ${pathBin} (${pathVersion})`));
+    }
+    else if (pathVersion && checkBrake(pathVersion, brake) === "above_max_tested") {
+        lines.push(tr(`本机已有的 ${pathBin}(${pathVersion})${verdictText("above_max_tested", brake)},不会使用;首次运行 u1s1 ${agent} 时另装一份`, `The existing ${pathBin} (${pathVersion}) is ${verdictText("above_max_tested", brake)} and won't be used; a separate copy is installed the first time you run u1s1 ${agent}`));
+    }
+    else {
+        lines.push(tr(`未安装,首次运行 u1s1 ${agent} 时从官方渠道下载`, `Not installed; downloaded from the official source the first time you run u1s1 ${agent}`));
+    }
+    if (managed) {
+        const verdict = checkBrake(managed, brake);
+        if (verdict !== "ok") {
+            lines.push(autoUpdate
+                ? tr(`当前版本不可用(${verdictText(verdict, brake)}),下次启动前会换到可用的版本`, `Current version can't be used (${verdictText(verdict, brake)}); it will be replaced with an allowed version before the next launch`)
+                : tr(`当前版本不可用(${verdictText(verdict, brake)}),自动更新已关闭:运行 u1s1 agents install ${agent} 换到可用的版本`, `Current version can't be used (${verdictText(verdict, brake)}). Automatic updates are off: run u1s1 agents install ${agent} to switch to an allowed version`));
+        }
+    }
+    const managedBraked = managed !== undefined && checkBrake(managed, brake) !== "ok";
+    if (!autoUpdate && !state.pinned && !managedBraked)
+        lines.push(tr(`自动更新已关闭(u1s1 config set ${agent}.auto-update on 打开)`, `Automatic updates are off (u1s1 config set ${agent}.auto-update on to turn them on)`));
+    if (state.pinned)
+        lines.push(tr(`已锁定 ${state.pinned}`, `Pinned to ${state.pinned}`));
+    if (!envBin) {
+        const target = state.pinned ?? bestInstallTarget([latest, brake.maxTestedVersion], brake);
+        if (!latest)
+            lines.push(tr("暂时查不到官方最新版(网络?)", "Couldn't check the latest official version (network?)"));
+        else if (managed && target && compareVersions(target, managed) > 0) {
+            lines.push(autoUpdate || state.pinned
+                ? tr(`有更新:${target},下次运行 u1s1 ${agent} 时安装`, `Update available: ${target}, installed the next time you run u1s1 ${agent}`)
+                : tr(`有更新:${target},运行 u1s1 agents install ${agent} 安装`, `Update available: ${target}; run u1s1 agents install ${agent} to install it`));
+        }
+        else if (managed) {
+            lines.push(tr(`已是可用的最新版(官方最新 ${latest})`, `Up to date (latest official: ${latest})`));
+        }
+        else {
+            lines.push(tr(`官方最新 ${latest}`, `Latest official: ${latest}`));
+        }
+    }
+    return lines;
+}
+const PIN_EXAMPLE = { claude: "2.1.322", codex: "0.167.2" };
+export async function pinCommand(raw, agent = "claude") {
+    const version = normalizeVersion(raw);
+    if (!version) {
+        console.error(tr(`用法: u1s1 agents pin ${agent} <版本>,例如 ${PIN_EXAMPLE[agent]}`, `Usage: u1s1 agents pin ${agent} <version>, e.g. ${PIN_EXAMPLE[agent]}`));
+        return 1;
+    }
+    const brake = cachedBrake(agent);
+    const verdict = checkBrake(version, brake);
+    if (verdict !== "ok") {
+        console.error(tr(`不能锁定 ${version}:${verdictText(verdict, brake)}。`, `Can't pin ${version}: ${verdictText(verdict, brake)}.`));
+        return 1;
+    }
+    updateRuntimeState(launchPaths(agent), { pinned: version, pending: undefined });
+    console.log(tr(`已锁定 ${version},下次运行 u1s1 ${agent} 时生效(需要时会先下载)。解除:u1s1 agents unpin ${agent}`, `Pinned to ${version}; takes effect the next time you run u1s1 ${agent} (downloading it first if needed). To undo: u1s1 agents unpin ${agent}`));
+    return 0;
+}
+export function unpinCommand(agent = "claude") {
+    const state = readRuntimeState(launchPaths(agent));
+    if (!state.pinned) {
+        console.log(tr("没有锁定版本。", "No version is pinned."));
+        return 0;
+    }
+    updateRuntimeState(launchPaths(agent), { pinned: undefined, lastCheckAt: undefined });
+    console.log(readAgentPrefs(agent).autoUpdate
+        ? tr("已解除锁定,恢复自动更新。", "Pin removed; automatic updates resume.")
+        : tr(`已解除锁定。自动更新是关着的:继续用现在的版本,运行 u1s1 agents install ${agent} 手动更新。`, `Pin removed. Automatic updates are off: the current version stays; run u1s1 agents install ${agent} to update.`));
+    return 0;
+}
+function fetchPublicRuntime(url) {
+    return gatewayFetch(url, {
+        headers: { "x-u1s1-version": VERSION, accept: "application/json" },
+        signal: AbortSignal.timeout(15_000),
+    });
+}
+/**
+ * 没有配置缓存(多半还没登录)时的刹车来源:网关的公开刹车接口。拿不到(老网关 404、网络失败)
+ * 或明确停用时返回退出码,调用方不下载——宁可晚装,也不在没有版本上限的情况下装。
+ */
+async function publicBrake(agent, baseUrl, deps) {
+    const fetchRuntime = deps.fetchPublicRuntime ?? fetchPublicRuntime;
+    const gatewayAgent = AGENT_PROFILES[agent].gatewayAgent;
+    const result = await loadPublicAgentRuntime({
+        agent: gatewayAgent,
+        fetchRuntime: () => fetchRuntime(new URL(`/public/agents/${gatewayAgent}/runtime`, baseUrl)),
+    });
+    if (result.status !== "ok") {
+        console.error(tr(`  暂时拿不到允许安装的版本范围,这次先不下载;第一次运行 u1s1 ${agent} 时会再安装。`, `  Couldn't get the range of versions allowed right now, so nothing was downloaded; it will be installed the first time you run u1s1 ${agent}.`));
+        return 1;
+    }
+    if (!result.brakes.enabled) {
+        console.error(result.brakes.disabledReason ?? notOpenText());
+        return 1;
+    }
+    return result.brakes.runtime;
+}
+/**
+ * `u1s1 agents install claude|codex`:找到或下载原版,不启动。与 `u1s1 claude` / `u1s1 codex` 走同一套
+ * ensureAgentRuntime:首次从官方下载前同样要用户确认(没有终端就不下载)。
+ * 不需要登录。刹车用缓存的网关配置;没有缓存时问网关的公开刹车接口,问不到就不下载。
+ * 缓存里或公开接口明确停用时不下载。
+ */
+export async function installCommand(deps = {}, agent = "claude") {
+    const cfg = loadConfig();
+    const site = siteOf(cfg);
+    const cached = cachedConfig(agent);
+    let brake;
+    if (cached) {
+        if (!cached.enabled) {
+            console.error(cached.disabledReason ?? notOpenText());
+            return 1;
+        }
+        brake = cached.runtime;
+    }
+    else {
+        const got = await publicBrake(agent, cfg.baseUrl, deps);
+        if (typeof got === "number")
+            return got;
+        brake = got;
+    }
+    const paths = launchPaths(agent);
+    const spec = runtimeSpec(agent);
+    mkdirSync(paths.configDir, { recursive: true, mode: 0o700 });
+    // 自动更新关着时这就是「手动更新」:现在查一次官方最新版(记成 pending,下面照常安装)。
+    // 开着时行为不变:每天的检查已经记下了 pending。
+    if (!readAgentPrefs(agent).autoUpdate) {
+        await (deps.checkLatest ?? ((input) => dailyUpdateCheck(input)))({
+            paths,
+            brake,
+            now: Date.now(),
+            latest: () => fetchLatestVersion(npmRegistryFor(site.id), spec.npmPackage),
+            force: true,
+        }).catch(() => undefined);
+    }
+    let runtime;
+    try {
+        runtime = await (deps.ensure ?? ensureAgentRuntime)(agent, {
+            brake,
+            site: site.id,
+            agentsRoot: agentsRoot(),
+            hooks: cliInstallHooks(agent),
+            probeConfigDir: paths.configDir,
+        });
+    }
+    catch (e) {
+        if (!printRuntimeFailure(e, agent))
+            throw e;
+        return 1;
+    }
+    printRuntimeNotes(runtime, agent);
+    if (runtime.installError)
+        return 1;
+    if (runtime.source === "env") {
+        console.log(tr(`使用 ${spec.binEnv} 指定的 ${runtime.bin}(${runtime.version}),不用下载。`, `Using ${runtime.bin} from ${spec.binEnv} (${runtime.version}); nothing to download.`));
+    }
+    else if (runtime.source === "path") {
+        console.log(tr(`将使用本机已有的 ${runtime.bin}(${runtime.version}),不用下载。`, `The existing ${runtime.bin} (${runtime.version}) will be used; nothing to download.`));
+    }
+    else {
+        console.log(tr(`${agent} ${runtime.version} 已就绪,运行 u1s1 ${agent} 开始使用。`, `${agent} ${runtime.version} is ready. Run u1s1 ${agent} to start.`));
+    }
+    return 0;
+}

package/dist/config-command.d.ts

@@ -0,0 +1,18 @@
+declare const CLIENTS: readonly ["claude", "codex"];
+type Client = (typeof CLIENTS)[number];
+export type ConfigKey = "default-client" | "pi.model" | `${Client}.model` | `${Client}.auto-update` | `${Client}.pin`;
+export declare const CONFIG_KEYS: readonly ConfigKey[];
+export declare function isConfigKey(value: unknown): value is ConfigKey;
+export interface ConfigValue {
+    /** 存下来的值;undefined = 没设置 */
+    value?: string;
+    /** 没设置时实际生效的说明(列表里显示) */
+    fallback: string;
+}
+/** 读当前值。deps 供测试注入。 */
+export declare function readConfigValue(key: ConfigKey): Promise<ConfigValue>;
+/** 写一项;返回退出码(已向用户说明)。value = undefined 表示 unset。 */
+export declare function writeConfigValue(key: ConfigKey, value: string | undefined): Promise<number>;
+export declare function configHelpLines(): string[];
+export declare function configCommand(args: readonly string[]): Promise<number>;
+export {};

package/dist/config-command.js

@@ -0,0 +1,335 @@
+/**
+ * `u1s1 config`:用户可调的启动器设置(规划 4.6)。已有命令(`u1s1 use`、`u1s1 model`、`u1s1 agents pin`)
+ * 行为不变,这里是它们的统一入口,另加「每个客户端的默认模型」和「是否自动更新」。
+ *
+ *   u1s1 config                       终端里是交互菜单;没有终端时同 list
+ *   u1s1 config list                  列出全部设置和当前值
+ *   u1s1 config get <键>              只打印值(脚本用);没设置过、也没有默认值时退出码 1
+ *   u1s1 config set <键> <值>
+ *   u1s1 config unset <键>            恢复默认
+ *
+ * 键:
+ *   default-client        pi | claude | codex             同 u1s1 use
+ *   pi.model              模型 id 或别名                  同 u1s1 model <模型>
+ *   claude.model          模型 id                          u1s1 claude 的默认模型(--settings 的 model)
+ *   codex.model           模型 id                          u1s1 codex 的默认模型(config.toml 的 model)
+ *   claude.auto-update    on | off                         每天查新、下次启动前更新;缺省 on
+ *   codex.auto-update     on | off
+ *   claude.pin            版本号                           同 u1s1 agents pin / unpin
+ *   codex.pin             版本号
+ *
+ * 客户端的模型只按网关上次下发的阵容(启动配置缓存)核对:还没启动过、没有缓存时照收,启动时再核对,
+ * 不在阵容里就退回默认模型并提示一次(prefs.ts)。
+ */
+import { existsSync } from "node:fs";
+import { createInterface } from "node:readline/promises";
+import { agentSettingsFile, isDefaultAgent, loadConfig, readRawConfigFile, saveDefaultAgent, } from "./config.js";
+import { tr } from "./i18n.js";
+const CLIENTS = ["claude", "codex"];
+export const CONFIG_KEYS = [
+    "default-client",
+    "pi.model",
+    "claude.model",
+    "codex.model",
+    "claude.auto-update",
+    "codex.auto-update",
+    "claude.pin",
+    "codex.pin",
+];
+export function isConfigKey(value) {
+    return typeof value === "string" && CONFIG_KEYS.includes(value);
+}
+function clientOf(key) {
+    const prefix = key.split(".")[0];
+    return prefix === "claude" || prefix === "codex" ? prefix : undefined;
+}
+function describe(key) {
+    const client = clientOf(key);
+    if (key === "default-client")
+        return tr("运行 u1s1 时进入的客户端", "Client that plain u1s1 opens");
+    if (key === "pi.model")
+        return tr("Pi 的默认模型(同 u1s1 model)", "Pi's default model (same as u1s1 model)");
+    if (key.endsWith(".model"))
+        return tr(`u1s1 ${client} 启动时用的模型`, `Model u1s1 ${client} starts with`);
+    if (key.endsWith(".auto-update"))
+        return tr(`每天查一次 ${client} 新版,下次启动前更新`, `Check for a new ${client} daily and update before the next launch`);
+    return tr(`把 ${client} 锁定在某个版本(同 u1s1 agents pin)`, `Pin ${client} to a version (same as u1s1 agents pin)`);
+}
+/** 读当前值。deps 供测试注入。 */
+export async function readConfigValue(key) {
+    const client = clientOf(key);
+    if (key === "default-client") {
+        const raw = readRawConfigFile();
+        const stored = raw?.["defaultAgent"];
+        if (isDefaultAgent(stored))
+            return { value: stored, fallback: "" };
+        const { isExistingUser } = await import("./launcher.js");
+        return {
+            fallback: isExistingUser(raw, existsSync(agentSettingsFile))
+                ? tr("pi(未设置)", "pi (not set)")
+                : tr("未设置(首次运行 u1s1 时选择)", "not set (chosen the first time you run u1s1)"),
+        };
+    }
+    if (key === "pi.model") {
+        const model = loadConfig().model;
+        return model ? { value: model, fallback: "" } : { fallback: tr("站点默认", "site default") };
+    }
+    const { readAgentPrefs } = await import("./agents/prefs.js");
+    if (key.endsWith(".model")) {
+        const model = readAgentPrefs(client).model;
+        return model ? { value: model, fallback: "" } : { fallback: tr("跟随网关默认", "gateway default") };
+    }
+    if (key.endsWith(".auto-update")) {
+        return readAgentPrefs(client).autoUpdate ? { value: "on", fallback: "" } : { value: "off", fallback: "" };
+    }
+    const { readRuntimeState } = await import("./agents/runtime.js");
+    const { launchPaths } = await import("./agents/status.js");
+    const pinned = readRuntimeState(launchPaths(client)).pinned;
+    return pinned ? { value: pinned, fallback: "" } : { fallback: tr("未锁定", "not pinned") };
+}
+// ---------------------------------------------------------------- write
+/** 客户端阵容:上次缓存的网关启动配置;没有缓存返回 undefined(不核对)。 */
+async function cachedLineup(client) {
+    const { readConfigCache, parseAgentConfig } = await import("./agents/agent-config.js");
+    const { AGENT_PROFILES } = await import("./agents/launch.js");
+    const { launchPaths } = await import("./agents/status.js");
+    const cached = readConfigCache(launchPaths(client).configCache, new URL(loadConfig().baseUrl).origin);
+    const config = cached ? parseAgentConfig(cached.body, AGENT_PROFILES[client].gatewayAgent) : undefined;
+    if (!config || !config.enabled)
+        return undefined;
+    return { ids: config.models.map((m) => m.id), defaultModel: config.defaultModel };
+}
+function parseSwitch(value) {
+    const v = value.trim().toLowerCase();
+    if (["on", "true", "yes", "1", "开"].includes(v))
+        return true;
+    if (["off", "false", "no", "0", "关"].includes(v))
+        return false;
+    return undefined;
+}
+/** 写一项;返回退出码(已向用户说明)。value = undefined 表示 unset。 */
+export async function writeConfigValue(key, value) {
+    const client = clientOf(key);
+    if (key === "default-client") {
+        if (value === undefined) {
+            saveDefaultAgent(undefined);
+            console.log(tr("已清除默认客户端。", "Default client cleared."));
+            return 0;
+        }
+        if (!isDefaultAgent(value)) {
+            console.error(tr("default-client 只能是 pi、claude 或 codex。", "default-client must be pi, claude or codex."));
+            return 1;
+        }
+        saveDefaultAgent(value);
+        console.log(tr(`已把默认客户端设为 ${value}:运行 u1s1 直接进入它。`, `Default client set to ${value}: running u1s1 now opens it.`));
+        return 0;
+    }
+    if (key === "pi.model") {
+        if (value === undefined) {
+            console.error(tr("Pi 总要有一个模型,没法清除;用 u1s1 config set pi.model <模型> 换一个(u1s1 model 可看列表)。", "Pi always needs a model, so this can't be cleared; pick one with u1s1 config set pi.model <model> (u1s1 model lists them)."));
+            return 1;
+        }
+        const { modelCommand } = await import("./model.js");
+        const before = process.exitCode;
+        process.exitCode = 0;
+        await modelCommand(value);
+        const code = typeof process.exitCode === "number" ? process.exitCode : 0;
+        process.exitCode = before;
+        return code;
+    }
+    const { saveAgentPrefs } = await import("./agents/prefs.js");
+    if (key.endsWith(".model")) {
+        if (value === undefined) {
+            saveAgentPrefs(client, { model: null });
+            console.log(tr(`u1s1 ${client} 改回跟随网关默认模型。`, `u1s1 ${client} is back on the gateway default model.`));
+            return 0;
+        }
+        const { isModelId } = await import("./agents/prefs.js");
+        const model = value.trim();
+        if (model === "default")
+            return writeConfigValue(key, undefined);
+        if (!isModelId(model)) {
+            console.error(tr(`不是有效的模型 id:${value}`, `Not a valid model id: ${value}`));
+            return 1;
+        }
+        const lineup = await cachedLineup(client);
+        if (lineup && !lineup.ids.includes(model)) {
+            console.error(tr(`${model} 不在 ${client} 当前可用的模型里。可选:`, `${model} isn't one of the models currently available for ${client}. Choose from:`));
+            for (const id of lineup.ids)
+                console.error(`  ${id}`);
+            return 1;
+        }
+        saveAgentPrefs(client, { model });
+        console.log(lineup
+            ? tr(`u1s1 ${client} 的默认模型设为 ${model},下次启动生效。`, `u1s1 ${client} will start with ${model} from the next launch.`)
+            : tr(`u1s1 ${client} 的默认模型设为 ${model}。还没拿到过 ${client} 的模型列表,下次启动时核对;不可用时会用默认模型并提示。`, `u1s1 ${client} will start with ${model}. The ${client} model list hasn't been fetched yet, so it's checked at the next launch; if it isn't available, the default model is used and you'll be told.`));
+        return 0;
+    }
+    if (key.endsWith(".auto-update")) {
+        const on = value === undefined ? true : parseSwitch(value);
+        if (on === undefined) {
+            console.error(tr(`${key} 只能是 on 或 off。`, `${key} must be on or off.`));
+            return 1;
+        }
+        saveAgentPrefs(client, { autoUpdate: on });
+        console.log(on
+            ? tr(`已打开 ${client} 的自动更新:每天查一次新版,下次启动前更新。`, `Automatic updates for ${client} are on: checked daily, installed before the next launch.`)
+            : tr(`已关闭 ${client} 的自动更新:一直用现在的版本,运行 u1s1 agents install ${client} 手动更新。`
+                + `版本被停用或太旧时仍要先更新才能启动。`, `Automatic updates for ${client} are off: the current version stays; run u1s1 agents install ${client} to update. `
+                + `A version that has been disabled or is too old still has to be updated before it can start.`));
+        return 0;
+    }
+    const { pinCommand, unpinCommand } = await import("./agents/status.js");
+    return value === undefined ? unpinCommand(client) : await pinCommand(value, client);
+}
+// ---------------------------------------------------------------- command
+export function configHelpLines() {
+    const rows = [
+        ["u1s1 config", tr("交互式修改(没有终端时同 list)", "Change settings interactively (same as list without a terminal)")],
+        ["u1s1 config list", tr("列出全部设置", "List all settings")],
+        ["u1s1 config get <键>", tr("打印一项的值", "Print one value")],
+        ["u1s1 config set <键> <值>", tr("修改一项", "Change one value")],
+        ["u1s1 config unset <键>", tr("恢复默认", "Restore the default")],
+    ];
+    const keyRows = [
+        ["default-client", "pi | claude | codex"],
+        ["pi.model", tr("模型 id 或别名", "model id or alias")],
+        ["claude.model, codex.model", tr("模型 id;default = 跟随网关默认", "model id; default = gateway default")],
+        ["claude.auto-update, codex.auto-update", "on | off"],
+        ["claude.pin, codex.pin", tr("版本号", "version")],
+    ];
+    const usage = rows.map(([a, b]) => `  ${tr(a, a.replace("<键>", "<key>").replace("<值>", "<value>")).padEnd(30)}${b}`);
+    return [
+        tr("用法:", "Usage:"),
+        ...usage,
+        "",
+        tr("键:", "Keys:"),
+        ...keyRows.map(([a, b]) => `  ${a.padEnd(38)}${b}`),
+        "",
+        tr("  客户端里用 /model 换的模型只对那一次会话有效;想让 u1s1 claude / u1s1 codex 每次都用它,在这里设。", "  A model picked with /model inside a client only lasts for that session; set it here to start with it every time."),
+    ];
+}
+export async function configCommand(args) {
+    const [sub, key, ...rest] = args;
+    if (sub === "--help" || sub === "-h" || sub === "help") {
+        for (const line of configHelpLines())
+            console.log(line);
+        return 0;
+    }
+    if (sub === undefined) {
+        if (process.stdin.isTTY && process.stdout.isTTY)
+            return interactiveConfig();
+        return listConfig();
+    }
+    if (sub === "list" && key === undefined)
+        return listConfig();
+    if ((sub === "get" || sub === "set" || sub === "unset") && key !== undefined && !isConfigKey(key)) {
+        console.error(tr(`不认识的设置项:${key}`, `Unknown setting: ${key}`));
+        console.error(tr(`可用的:${CONFIG_KEYS.join("、")}`, `Available: ${CONFIG_KEYS.join(", ")}`));
+        return 1;
+    }
+    if (sub === "get" && isConfigKey(key) && rest.length === 0) {
+        const v = await readConfigValue(key);
+        if (v.value === undefined)
+            return 1;
+        console.log(v.value);
+        return 0;
+    }
+    if (sub === "set" && isConfigKey(key) && rest.length === 1)
+        return writeConfigValue(key, rest[0]);
+    if (sub === "unset" && isConfigKey(key) && rest.length === 0)
+        return writeConfigValue(key, undefined);
+    for (const line of configHelpLines())
+        console.error(line);
+    return 1;
+}
+async function listConfig() {
+    for (const key of CONFIG_KEYS) {
+        const v = await readConfigValue(key);
+        console.log(`${key.padEnd(20)}${v.value ?? `(${v.fallback})`}`);
+    }
+    return 0;
+}
+// ---------------------------------------------------------------- interactive
+/** 终端里的显示宽度:中日韩字符和全角标点按 2 列算。 */
+function displayWidth(text) {
+    let width = 0;
+    for (const ch of text)
+        width += /[\u1100-\u115f\u2e80-\ua4cf\uac00-\ud7a3\uf900-\ufaff\ufe30-\ufe4f\uff00-\uff60\uffe0-\uffe6]/.test(ch) ? 2 : 1;
+    return width;
+}
+function padDisplay(text, width) {
+    return text + " ".repeat(Math.max(1, width - displayWidth(text)));
+}
+/** 某一项可选的值(交互菜单用);undefined = 自由输入。 */
+async function choicesFor(key) {
+    const client = clientOf(key);
+    if (key === "default-client") {
+        return ["pi", "claude", "codex"].map((a) => ({ label: a, value: a }));
+    }
+    if (key.endsWith(".auto-update")) {
+        return [
+            { label: tr("on  每天查新,下次启动前更新", "on   check daily, update before the next launch"), value: "on" },
+            { label: tr("off 一直用现在的版本,手动更新", "off  keep the current version, update by hand"), value: "off" },
+        ];
+    }
+    if (client && key.endsWith(".model")) {
+        const lineup = await cachedLineup(client);
+        if (!lineup)
+            return undefined;
+        return [
+            { label: tr(`跟随网关默认${lineup.defaultModel ? `(现在是 ${lineup.defaultModel})` : ""}`, `Gateway default${lineup.defaultModel ? ` (currently ${lineup.defaultModel})` : ""}`), value: undefined },
+            ...lineup.ids.map((id) => ({ label: id, value: id })),
+        ];
+    }
+    return undefined;
+}
+async function interactiveConfig() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        for (;;) {
+            console.log("");
+            console.log(tr("  u1s1 设置(脚本里可用 u1s1 config get|set <键> [值])", "  u1s1 settings (scripts can use u1s1 config get|set <key> [value])"));
+            for (const [i, key] of CONFIG_KEYS.entries()) {
+                const v = await readConfigValue(key);
+                console.log(`    ${String(i + 1).padStart(2)}) ${key.padEnd(20)}${padDisplay(v.value ?? `(${v.fallback})`, 26)}${describe(key)}`);
+            }
+            const answer = (await rl.question(tr("  要改哪一项?输入序号,直接回车退出: ", "  Which one? Enter a number, or press Enter to quit: "))).trim();
+            if (answer === "" || answer === "q")
+                return 0;
+            const index = Number(answer);
+            const key = Number.isInteger(index) ? CONFIG_KEYS[index - 1] : undefined;
+            if (!key) {
+                console.log(tr(`  请输入 1-${CONFIG_KEYS.length}`, `  Please enter 1-${CONFIG_KEYS.length}`));
+                continue;
+            }
+            await editOne(rl, key);
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+async function editOne(rl, key) {
+    const choices = await choicesFor(key);
+    if (!choices) {
+        const hint = key.endsWith(".pin")
+            ? tr("输入版本号,输入 - 解除锁定", "Enter a version, or - to unpin")
+            : tr("输入模型 id,输入 - 恢复默认", "Enter a model id, or - for the default");
+        const answer = (await rl.question(`  ${key}: ${hint}(${tr("回车取消", "Enter to cancel")}) `)).trim();
+        if (answer === "")
+            return;
+        await writeConfigValue(key, answer === "-" ? undefined : answer);
+        return;
+    }
+    choices.forEach((c, i) => console.log(`      ${i + 1}) ${c.label}`));
+    const answer = (await rl.question(tr("    选哪个?(回车取消) ", "    Which one? (Enter to cancel) "))).trim();
+    if (answer === "")
+        return;
+    const picked = choices[Number(answer) - 1];
+    if (!picked) {
+        console.log(tr("    没有这一项。", "    No such option."));
+        return;
+    }
+    await writeConfigValue(key, picked.value);
+}

package/dist/config.d.ts

@@ -176,8 +176,13 @@ export interface CliConfig {
     modelProvider?: string;
     /** 登录时记下的账号邮箱,只用于横幅「账号」展示(真相以 u1s1 whoami 为准)。 */
     email?: string;
+    /** 默认客户端(`u1s1 use`/首次选择器写入);缺省 = 存量用户,按 Pi 处理(见 launcher.ts)。 */
+    defaultAgent?: DefaultAgent;
 }
+export type DefaultAgent = "pi" | "claude" | "codex";
+export declare function isDefaultAgent(value: unknown): value is DefaultAgent;
 export declare const u1s1Dir: string;
+export declare const configFile: string;
 /** pi keeps auth/models/settings/sessions under this dir — isolated from any real pi install. */
 export declare const agentDir: string;
 export declare const agentSettingsFile: string;
@@ -246,6 +251,18 @@ export declare function writePrivateFile(path: string, content: string): void;
 export declare function stripEnvOverrides(cfg: CliConfig, file: Partial<CliConfig>, env?: NodeJS.ProcessEnv): Partial<CliConfig>;
 export declare function saveConfig(cfg: CliConfig): void;
 /** Persist the user's preferred model to both stores. */
+/**
+ * 只改 config.json 里的 defaultAgent 一个键,其余原样保留(还没登录、文件不存在时也能写)。
+ * 不经 saveConfig:那会把默认 baseUrl 等生效值一并写死进文件。
+ */
+export declare function saveDefaultAgent(agent: DefaultAgent | undefined): void;
+/**
+ * 只改 config.json 里 mutate 碰到的键,其余原样保留(不经 saveConfig,理由同 saveDefaultAgent)。
+ * 文件在但读不出来时不覆盖(里面可能有登录凭据),抛错让用户先修好。
+ */
+export declare function updateRawConfigFile(mutate: (file: Record<string, unknown>) => void): void;
+/** config.json 的原始内容(不叠加环境变量);不存在或解析失败为 undefined。 */
+export declare function readRawConfigFile(): Record<string, unknown> | undefined;
 export declare function persistPreferredModel(cfg: CliConfig, provider: string, modelId: string): CliConfig;
 export declare function saveEndpointsCache(endpoints: CustomEndpoint[]): void;
 export declare function loadEndpointsCache(): CustomEndpoint[];