@ai-zen/cli 1.0.0-alpha.9 → 1.0.0

package/dist/tui/screens/chat-commands.js

@@ -1,175 +1,706 @@
 import { AgentNS } from "@ai-zen/agents-core";
-import { spawnSync } from "node:child_process";
+import { HandoffAbortedError } from "@ai-zen/agents-sdk";
+import { spawn, spawnSync } from "node:child_process";
 import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { stripCwdNote } from "../chat-session.js";
-import { matchCommandHints } from "../../conversation-commands/registry.js";
-import { conversationRepository, listConversations } from "../../conversation-repository.js";
-import { formatShortTime } from "../../format-time.js";
+import { canonicalCommandName, matchCommandHints, parseCommandArgs, } from "../../conversation-commands/registry.js";
+import { conversationExists, conversationRepository, listConversations } from "../../conversation-repository.js";
+import { mcpConfigOrEmpty, readConfig, readMcpConfig, readReasoningPresets, saveConfig } from "../../config.js";
+import { resetScope } from "../../agent-creator.js";
+import { switchModel } from "../../model-switch.js";
+import { listAgentChoices, switchAgent } from "../../agent-switch.js";
+import { parseMcpScope, pickStartScope } from "../../mcp-command.js";
+import { effortChoices, effortLabel, describeEffort, describeEffortView, setAgentEffort, } from "../../reasoning-effort.js";
+import { matchLevel, presetFor } from "../../reasoning-presets.js";
+import { getLocale, t } from "../../i18n/index.js";
+import { persistLocale } from "../../i18n/preferences.js";
+import { readAgentStore } from "../../agents-store.js";
+import { CLI_VERSION } from "../../version.js";
+import { compareVersions, pickNewest } from "../../version-compare.js";
 import { truncate } from "./render.js";
-export async function runCommand(name, raw, host) {
-    const { session, notice, clearTranscript, rows, exit, suspendTerminal, openWizard, openKeyEditor, doExit, setPickerState, setConfirmState, setInputText, } = host;
-    const push = (text, tone = "info") => {
-        notice(text, tone);
-    };
-    switch (name) {
-        case "config":
-            await openWizard({ kind: "menu" });
-            break;
-        case "key":
-            await openKeyEditor();
-            break;
-        case "help": {
-            const lines = ["可用命令："];
-            for (const hint of matchCommandHints("")) {
-                lines.push(`  ${hint.label}  ${hint.description}`);
+import { STATUS_BAR_LINES, pickerLines } from "./layout.js";
+import { usableFrameRows } from "../text.js";
+import { chooseHandoffMode } from "./handoff-choice.js";
+/**
+ * 解析命令后的执行者参数（`/migrate self`、`/handoff summary`）。
+ * 缺省返回 undefined（走服务默认值）；非法值也返回 undefined，由调用方报错。
+ */
+export function parseHandoffMode(raw) {
+    const value = raw?.trim().toLowerCase();
+    return value === "self" || value === "summary" ? value : undefined;
+}
+/**
+ * 解析 `/handoff` `/migrate` 的执行者参数。
+ *
+ * 单独成函数而不是挂在 `CommandContext` 上：16 个命令里只有这两个用得到，
+ * 挂在上下文中会让另外 14 个命令（`/save` `/help` `/clear` …）每次也白算一遍。
+ */
+export function parseHandoffSelection(args) {
+    const raw = args[0]?.toLowerCase();
+    const mode = parseHandoffMode(raw);
+    return { mode, invalid: raw !== undefined && mode === undefined ? raw : undefined };
+}
+// ==================== 各命令 ====================
+/**
+ * `/save [名字]`
+ *
+ *   无参 → 时间戳 id（维持原行为）
+ *   带名 → 另存为该文件名；重名且不是当前会话时**先二次确认**（静默覆盖会让另一份
+ *          对话凭空消失，而文件名是用户唯一能看到的身份）
+ *
+ * 名字的合法性（路径穿越等）不在这里校验：会话仓储的 `path()` 是唯一落盘口，
+ * L2 修好后 `/save ../x` 会被那一层拦住，此处不另写一套。
+ */
+const cmdSave = async ({ session, push, args, confirm }) => {
+    const name = args[0]?.trim();
+    try {
+        if (!name) {
+            const id = await session.save();
+            push(t("cmd.save.done", { id }));
+            return;
+        }
+        if (name !== session.currentId && (await conversationExists(name))) {
+            if (!(await confirm(t("cmd.save.overwrite", { id: name })))) {
+                push(t("cmd.save.cancelled"));
+                return;
             }
-            push(lines.join("\n"));
-            break;
         }
-        case "clear":
-            // 清屏但保留上下文：仅把转录显示起点推到最新
-            clearTranscript();
-            break;
-        case "new": {
-            // reset 会先归档当前对话（有内容才存），返回存档 id（无内容为 null）
-            const archivedId = await session.reset();
-            clearTranscript();
-            push(archivedId ? `旧对话已存档：${archivedId}\n已开始新对话` : "已开始新对话");
-            break;
+        const id = await session.saveAs(name);
+        push(t("cmd.save.done", { id }));
+    }
+    catch (error) {
+        push(t("cmd.save.failed", { error: error?.message ?? error }), "error");
+    }
+};
+const cmdLoad = async ({ push, rows, exit, pick }) => {
+    // 条数上限：用布局自己的公式算，不留魔数 —— 命令层拿到的是**原始终端行数**，而
+    // 覆盖层能用的是 `usableFrameRows(rows) = rows - 1`；picker 自身占
+    // `pickerLines(n) + STATUS_BAR_LINES`。
+    const maxItems = Math.max(1, usableFrameRows(rows ?? 24) - (pickerLines(0) + STATUS_BAR_LINES));
+    const list = await listConversations();
+    if (list.length === 0) {
+        push(t("cmd.load.none"), "error");
+        return;
+    }
+    // 列表只显示会话文件名（id）：不再解析首条消息当摘要（读盘开销已从 /load 消失）
+    const allItems = list.map((c) => ({ label: c.id, value: c.id }));
+    // 覆盖层不能高于终端：仅展示最近的有限条
+    const items = allItems.slice(0, maxItems);
+    const title = allItems.length > maxItems ? t("cmd.load.tooMany", { n: maxItems }) : t("cmd.load.titleReplacing");
+    const choice = await pick(title, items);
+    if (choice == null) {
+        push(t("cmd.load.cancelled"));
+        return;
+    }
+    const conversation = await conversationRepository().read(choice);
+    if (!conversation) {
+        push(t("cmd.load.readFailed", { id: choice }), "error");
+        return;
+    }
+    // 整体切换会话（含模型 / Agent）——交由上层重挂载对话屏
+    exit({
+        load: {
+            agentId: conversation.agentId,
+            messages: conversation.messages,
+            conversationId: conversation.id,
+            conversationName: conversation.id,
+        },
+    });
+};
+const cmdNew = async ({ session, clearTranscript, push }) => {
+    // reset 会先归档当前对话（有内容才存），返回存档 id（无内容为 null）
+    const archivedId = await session.reset();
+    clearTranscript();
+    push(archivedId ? t("cmd.new.archived", { id: archivedId }) : t("cmd.new.started"));
+};
+const cmdBack = async ({ session, push, rows, exit, pick }) => {
+    const allItems = [];
+    session.messages.forEach((message, index) => {
+        if (message.role !== AgentNS.Role.User)
+            return;
+        const content = typeof message.content === "string" ? message.content : "";
+        allItems.push({ label: truncate(stripCwdNote(content), 60), value: String(index) });
+    });
+    if (allItems.length === 0) {
+        push(t("cmd.back.empty"), "error");
+        return;
+    }
+    // 最近的在最前；仅展示最近的有限条，避免覆盖层高于终端（上界同 /load）
+    const maxItems = Math.max(1, usableFrameRows(rows ?? 24) - (pickerLines(0) + STATUS_BAR_LINES));
+    const items = allItems.reverse().slice(0, maxItems);
+    const title = allItems.length > maxItems ? t("cmd.back.tooMany", { n: maxItems }) : t("cmd.back.title");
+    const choice = await pick(title, items);
+    if (choice == null) {
+        push(t("cmd.back.cancelled"));
+        return;
+    }
+    const text = session.rollbackTo(Number(choice));
+    // 撤回也要落盘：否则存档里仍留着被撤回的消息，下次 `/load` 或重启就「复活」。
+    // `save()` 会顺带更新 last-session 指针 —— 刚撤回的会话就是本目录的上一轮，符合预期。
+    await session.save();
+    exit({ restart: true, messages: session.messages, initialInput: text });
+};
+const cmdEditor = async ({ push, suspendTerminal, setInputText }) => {
+    const file = join(tmpdir(), `aizen-input-${Date.now()}.md`);
+    try {
+        writeFileSync(file, "", "utf-8");
+        await suspendTerminal(() => {
+            const editor = process.env.EDITOR || process.env.VISUAL || (process.platform === "win32" ? "notepad" : "vi");
+            const result = spawnSync(editor, [file], { stdio: "inherit" });
+            if (result.error)
+                throw result.error;
+        });
+        const text = readFileSync(file, "utf-8").trim();
+        if (text)
+            setInputText(text);
+    }
+    catch (error) {
+        push(t("cmd.editor.failed", { error: error?.message ?? error }), "error");
+    }
+    finally {
+        try {
+            unlinkSync(file);
         }
-        case "save": {
-            try {
-                const id = await session.save();
-                push(`对话已保存：${id}`);
-            }
-            catch (error) {
-                push(`保存失败：${error?.message ?? error}`, "error");
-            }
-            break;
+        catch {
+            /* 忽略 */
         }
-        case "load": {
-            const list = await listConversations();
-            if (list.length === 0) {
-                push("还没有已保存的对话", "error");
-                break;
-            }
-            const allItems = list.map((c) => ({
-                label: c.name,
-                value: c.id,
-                hint: formatShortTime(c.updatedAt),
-            }));
-            // 覆盖层不能高于终端：仅展示最近的有限条
-            const maxItems = Math.max(1, (rows ?? 24) - 8);
-            const items = allItems.slice(0, maxItems);
-            const title = allItems.length > maxItems
-                ? `选择要加载的对话（仅显示最近 ${maxItems} 条）`
-                : "选择要加载的对话（当前会话将被替换）";
-            const choice = await new Promise((resolve) => setPickerState({ title, items, resolve }));
-            if (choice == null) {
-                push("已取消加载");
-                break;
-            }
-            const conversation = await conversationRepository.read(choice);
-            if (!conversation) {
-                push(`对话不存在或读取失败：${choice}`, "error");
-                break;
-            }
-            // 整体切换会话（含模型 / Agent）——交由上层重挂载对话屏
-            exit({
-                load: {
-                    modelId: conversation.modelId,
-                    agentId: conversation.agentId,
-                    messages: conversation.messages,
-                    conversationId: conversation.id,
-                    conversationName: conversation.id,
-                },
-            });
-            break;
+    }
+};
+const cmdClear = async ({ clearTranscript }) => {
+    // 清屏但保留上下文：仅把转录显示起点推到最新
+    clearTranscript();
+};
+const cmdConfig = async ({ openWizard }) => {
+    await openWizard({ kind: "menu" });
+};
+const cmdModel = async ({ session, push, args, exit, pick }) => {
+    const config = await readConfig();
+    const models = config.models ?? [];
+    if (models.length === 0) {
+        push(t("cmd.model.noModels"), "error");
+        return;
+    }
+    // 支持 `/model <id>` 直切，无参时弹选择器
+    let chosen = args[0];
+    if (chosen && !models.some((model) => model.id === chosen)) {
+        push(t("cmd.model.unknown", { id: chosen, options: models.map((m) => m.id).join(" / ") }), "error");
+        return;
+    }
+    if (!chosen) {
+        const items = models.map((model) => ({
+            label: model.id === session.modelId ? `${model.name}${t("common.current")}` : model.name,
+            value: model.id,
+            hint: model.id,
+        }));
+        const picked = await pick(t("cmd.model.title"), items);
+        if (picked == null) {
+            push(t("cmd.model.cancelled"));
+            return;
         }
-        case "migrate": {
-            if (!session.messages.some((m) => m.role === AgentNS.Role.User)) {
-                push("当前对话还没有可迁移的内容", "error");
-                break;
-            }
-            const ok = await new Promise((resolve) => setConfirmState({ question: "确定对当前对话进行任务迁移吗？", resolve }));
-            if (!ok) {
-                push("已取消迁移");
-                break;
-            }
-            try {
-                await session.migrate();
-                push("任务迁移完成，已开启新会话");
-            }
-            catch (error) {
-                push(`任务迁移失败：${error?.message ?? error}`, "error");
-            }
-            break;
+        chosen = picked;
+    }
+    if (chosen === session.modelId) {
+        push(t("cmd.model.already", { id: chosen }));
+        return;
+    }
+    // 先确认目标模型可用：重挂载走的是 ChatSession.create → createModel，
+    // 端点缺 Key 会直接抛错落到启动错误屏，用户连 /key 都进不去
+    const targetModel = models.find((model) => model.id === chosen);
+    const targetEndpoint = (config.endpoints ?? []).find((endpoint) => endpoint.id === targetModel.endpointId);
+    if (!targetEndpoint) {
+        push(t("cmd.model.endpointMissing", { id: chosen, endpoint: targetModel.endpointId }), "error");
+        return;
+    }
+    if (!targetEndpoint.apiKey) {
+        push(t("cmd.model.noApiKey", { name: targetEndpoint.name }), "error");
+        return;
+    }
+    try {
+        // 只写 Agent 定义（模型唯一真相源）
+        const result = await switchModel({ config, agentId: session.agentId, modelId: chosen });
+        // Scope 持有配置快照：不重建的话 getScope() 会把旧模型又交给新 Agent
+        await resetScope();
+        // 重挂载对话屏：模型变了要重算上下文阈值、重建 Agent；消息与上下文保留
+        exit({ restart: true, agentId: session.agentId, messages: session.messages, notice: result.summary });
+    }
+    catch (error) {
+        push(t("cmd.model.failed", { error: error?.message ?? error }), "error");
+    }
+};
+const cmdAgent = async ({ session, push, args, exit, pick }) => {
+    const config = await readConfig();
+    const store = await readAgentStore();
+    const choices = listAgentChoices(config, store.agents);
+    if (choices.length === 0) {
+        push(t("cmd.agent.noAgents"), "error");
+        return;
+    }
+    // 支持 `/agent <id>` 直切，无参时弹选择器（与 /model 同一套做法）
+    let chosen = args[0];
+    if (chosen && !choices.some((choice) => choice.id === chosen)) {
+        push(t("cmd.agent.unknown", { id: chosen, options: choices.map((choice) => choice.id).join(" / ") }), "error");
+        return;
+    }
+    if (!chosen) {
+        const items = choices.map((choice) => {
+            const current = choice.id === session.agentId;
+            return {
+                label: `${choice.name}${current ? t("common.current") : ""}${choice.selectable ? "" : t("cmd.agent.unavailable")}`,
+                value: choice.id,
+                // 可用时给模型名（切换等于连模型一起换，得让用户看见换成哪个）；
+                // 不可用时给原因，否则用户只能干看着选不动
+                hint: choice.selectable ? (choice.modelName ?? choice.id) : (choice.reason ?? ""),
+            };
+        });
+        const picked = await pick(t("cmd.agent.title"), items);
+        if (picked == null) {
+            push(t("cmd.agent.cancelled"));
+            return;
         }
-        case "back": {
-            const allItems = [];
-            session.messages.forEach((message, index) => {
-                if (message.role !== AgentNS.Role.User)
-                    return;
-                const content = typeof message.content === "string" ? message.content : "";
-                allItems.push({ label: truncate(stripCwdNote(content), 60), value: String(index) });
-            });
-            if (allItems.length === 0) {
-                push("还没有可撤回的消息", "error");
-                break;
-            }
-            // 最近的在最前；仅展示最近的有限条，避免覆盖层高于终端
-            const maxItems = Math.max(1, (rows ?? 24) - 8);
-            const items = allItems.reverse().slice(0, maxItems);
-            const title = allItems.length > maxItems
-                ? `选择要撤回到的消息（仅显示最近 ${maxItems} 条）`
-                : "选择要撤回到的消息（其后内容将被移除）";
-            const choice = await new Promise((resolve) => setPickerState({ title, items, resolve }));
-            if (choice == null) {
-                push("已取消撤回");
-                break;
-            }
-            const text = session.rollbackTo(Number(choice));
-            exit({ restart: true, messages: session.messages, initialInput: text });
-            break;
+        chosen = picked;
+    }
+    const target = choices.find((choice) => choice.id === chosen);
+    // 切过去跑不起来（未绑模型 / 端点缺 Key）就别切：重挂载后用户会卡在启动错误屏
+    if (!target.selectable) {
+        push(t("cmd.agent.unavailableReason", { name: target.name, reason: target.reason ?? "" }), "error");
+        return;
+    }
+    try {
+        const result = switchAgent({ config, agents: store.agents, targetAgentId: chosen });
+        await saveConfig(result.config);
+        if (chosen === session.agentId) {
+            // 会话已经在这个 Agent 上：只需把「默认 Agent」记号写对，不必重建
+            push(t("cmd.agent.alreadyOn", { summary: result.summary ?? "" }));
+            return;
         }
-        case "editor": {
-            const file = join(tmpdir(), `aizen-input-${Date.now()}.md`);
-            try {
-                writeFileSync(file, "", "utf-8");
-                await suspendTerminal(() => {
-                    const editor = process.env.EDITOR ||
-                        process.env.VISUAL ||
-                        (process.platform === "win32" ? "notepad" : "vi");
-                    const result = spawnSync(editor, [file], { stdio: "inherit" });
-                    if (result.error)
-                        throw result.error;
-                });
-                const text = readFileSync(file, "utf-8").trim();
-                if (text)
-                    setInputText(text);
-            }
-            catch (error) {
-                push(`编辑器打开失败：${error?.message ?? error}`, "error");
-            }
-            finally {
-                try {
-                    unlinkSync(file);
-                }
-                catch {
-                    /* 忽略 */
-                }
-            }
-            break;
+        // Scope 持有 Agent / 配置快照：不重建的话下一轮请求还是旧 Agent
+        await resetScope();
+        // 重挂载对话屏：提示词、工具集、模型都跟着 Agent 变；消息与上下文保留
+        exit({ restart: true, agentId: chosen, messages: session.messages, notice: result.summary });
+    }
+    catch (error) {
+        push(t("cmd.agent.failed", { error: error?.message ?? error }), "error");
+    }
+};
+const cmdReload = async ({ session, push }) => {
+    // 手改配置文件（mcp.json / skills / tools / config.json）后不用重启 CLI：
+    // `session.reload()` 内含 resetScope()（断开旧 MCP 连接）→ 重建 Agent → 重新发现。
+    // 消息与上下文保留，所以「刷新一下就看到新东西」不需要新开对话。
+    try {
+        await session.reload();
+        push(t("cmd.reload.done"));
+    }
+    catch (error) {
+        push(t("cmd.reload.failed", { error: error?.message ?? error }), "error");
+    }
+};
+// ==================== /update ====================
+/** `/update` 的安装目标包 */
+const UPDATE_PACKAGE = "@ai-zen/cli";
+/** npm 查询类调用的超时：断网 / registry 无响应时不能无限期挂着 */
+const UPDATE_QUERY_TIMEOUT_MS = 20_000;
+/**
+ * 跑一次 npm 并收集 stdout（**异步**）。
+ *
+ * 为什么不能用 `spawnSync`：`npm view` 走网络要 1–3 秒，同步执行会把事件循环钉死，
+ * Ink 的动画定时器跟着停摆 —— 用户看到的是一个**冻住的转圈**，既没有进度也不知道
+ * 在等什么。超时主动 kill，避免断网时命令永远不返回。
+ */
+function runNpmCapture(args, spawnImpl = spawn) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let timer;
+        const child = spawnImpl("npm", args, { stdio: ["ignore", "pipe", "ignore"] });
+        let stdout = "";
+        const done = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            resolve(value);
+        };
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        // `error` 与 `close` 可能都触发（`spawn` 失败时先 error 再 close），settled 保证只结算一次
+        child.on("error", (err) => done({ code: null, stdout, error: err.message }));
+        child.on("close", (code) => done({ code, stdout }));
+        timer = setTimeout(() => {
+            child.kill("SIGKILL");
+            done({ code: null, stdout, error: `timeout ${UPDATE_QUERY_TIMEOUT_MS}ms` });
+        }, UPDATE_QUERY_TIMEOUT_MS);
+    });
+}
+/**
+ * 读取包在 registry 上的全部 dist-tag（`{ latest, alpha, … }`）。
+ *
+ * 只拿 `latest` **不够**：本项目的实际发布状态就是「alpha 比正式版新」
+ * （曾经 `latest = 0.9.0`、`alpha = 1.0.0-alpha.23`），只认 `latest` 会把正在跑
+ * alpha 的用户**降级**回去。所以取全部 tag、再挑 semver 最大的那个。
+ *
+ * `--prefer-online`：npm 会缓存 packument，刚发版时 `npm view` 可能仍拿到旧 tag，
+ * 把「有新版」误判成「已是最新」（发布当天踩过这个坑）。
+ *
+ * 失败（npm 不存在 / 网络不通 / 输出不是 JSON）返回 `undefined`，由调用方报错。
+ */
+async function readDistTags(pkg, spawnImpl) {
+    const result = await runNpmCapture(["view", pkg, "dist-tags", "--json", "--prefer-online"], spawnImpl);
+    if (result.code !== 0)
+        return undefined;
+    try {
+        const parsed = JSON.parse(result.stdout);
+        const tags = {};
+        for (const [tag, version] of Object.entries(parsed)) {
+            if (typeof version === "string")
+                tags[tag] = version;
+        }
+        return tags;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** 全局安装目录（`npm root -g`）；读不到返回 `undefined` */
+async function readGlobalRoot(spawnImpl) {
+    const result = await runNpmCapture(["root", "-g"], spawnImpl);
+    const dir = result.stdout.trim();
+    return result.code === 0 && dir ? dir : undefined;
+}
+/**
+ * 读取**全局安装目录**里某个包的实际版本，读不到返回 `undefined`。
+ *
+ * 走 `npm root -g` + 读 `package.json`，而不是 `npm view`：后者查的是 registry，
+ * 刚装完的版本在 registry 上通常要几分钟才可见（发布经验，见交接文档），
+ * 拿它报「装好了没」会把成功误报成失败。
+ */
+async function readGlobalInstalledVersion(pkg, spawnImpl) {
+    try {
+        const root = await readGlobalRoot(spawnImpl);
+        if (!root)
+            return undefined;
+        const parsed = JSON.parse(readFileSync(join(root, pkg, "package.json"), "utf-8"));
+        return typeof parsed.version === "string" ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * 安装（`stdio: inherit`，npm 的输出直接打在真实终端上）。成功返回 `undefined`，失败返回原因。
+ *
+ * `--prefer-online` 治 npm 的元数据缓存（否则刚发版的包可能解析失败 / 装到旧版本）；
+ * `--no-fund` 只是减噪 —— 募捐提示对正在等结果的人没有信息量。
+ */
+function installGlobal(spec, spawnImpl = spawn) {
+    return new Promise((resolve) => {
+        const child = spawnImpl("npm", ["install", "-g", spec, "--prefer-online", "--no-fund"], {
+            stdio: "inherit",
+        });
+        child.on("error", (err) => resolve(err.message));
+        child.on("close", (code) => resolve(code === 0 ? undefined : `exit ${code ?? "unknown"}`));
+    });
+}
+const cmdUpdate = async ({ push, suspendTerminal, confirm, restartProcess, session, spawn: spawnImpl, }) => {
+    // 每一步都说清「在干什么、看到什么」：只给一个转圈，无法区分「在查」和「在装」
+    push(t("cmd.update.checking", { pkg: UPDATE_PACKAGE }));
+    const tags = await readDistTags(UPDATE_PACKAGE, spawnImpl);
+    if (!tags) {
+        push(t("cmd.update.tagsFailed", { pkg: UPDATE_PACKAGE }), "error");
+        return;
+    }
+    // 全部 dist-tag 里 semver 最大的那个——不管是 alpha 还是正式版
+    const target = pickNewest(Object.values(tags));
+    if (!target) {
+        push(t("cmd.update.noVersion", { pkg: UPDATE_PACKAGE }), "error");
+        return;
+    }
+    // 不比当前进程新就不装：本地跑的开发版（或超前于 registry 的构建）不能被「升级」降级
+    const order = compareVersions(target, CLI_VERSION);
+    if (order !== null && order <= 0) {
+        push(t("cmd.update.same", { version: CLI_VERSION }));
+        return;
+    }
+    const spec = `${UPDATE_PACKAGE}@${target}`;
+    push(t("cmd.update.found", { target, current: CLI_VERSION }));
+    // 安装过程交给**真实终端**（`suspendTerminal` 期间 Ink 暂停渲染）：npm 的进度条与
+    // 报错直接打在 TTY 上，比捕获后回放可读。移交之前先在 TTY 上打一段头部 ——
+    // 否则用户只看到 npm 自己的滚动输出，不知道装的是什么、从哪来、装到哪。
+    const root = await readGlobalRoot(spawnImpl);
+    let error;
+    await suspendTerminal(async () => {
+        process.stdout.write(t("cmd.update.installHeader", {
+            spec,
+            current: CLI_VERSION,
+            root: root ?? t("cmd.update.rootUnknown"),
+        }) + "\n");
+        error = await installGlobal(spec, spawnImpl);
+    });
+    if (error) {
+        push(t("cmd.update.failed", { spec, error }), "error");
+        return;
+    }
+    // 装完读全局目录里的版本：读不到（自建安装路径 / 别的包管理器）就按目标版本报
+    const installed = (await readGlobalInstalledVersion(UPDATE_PACKAGE, spawnImpl)) ?? target;
+    if (installed === CLI_VERSION) {
+        push(t("cmd.update.same", { version: installed }));
+        return;
+    }
+    push(t("cmd.update.done", { spec, current: CLI_VERSION, version: installed }));
+    // 新代码只在**新进程**里生效：本进程的模块图已经加载完了，连 `exit({ restart: true })`
+    // 都只是重挂载界面、跑的还是旧模块，所以「重启」必须是真的重新 exec 自己。
+    // 用二次确认而不是装完直接重启：否则「装好了什么」这句结果还没看清，画面就换掉了；
+    // 确认框默认停在「是」——敲 `/update` 的人本来就是要升级，一个回车就走完。
+    const ok = await confirm(t("cmd.update.confirmRestart", { current: CLI_VERSION, version: installed }));
+    if (!ok) {
+        push(t("cmd.update.restart", { current: CLI_VERSION }));
+        return;
+    }
+    // 重启前把当前对话落盘：新进程靠 `last-session.json` 指针续接，而指针正是落盘时更新的。
+    // 没有用户消息（刚开的新会话）就不落盘，免得留下一份空会话文件。
+    if (session.messages.some((m) => m.role === AgentNS.Role.User)) {
+        try {
+            await session.save();
+        }
+        catch {
+            // 落盘失败不阻断重启：ConversationPersistPlugin 每轮已落过一次，这里只是补最后一手
+        }
+    }
+    await restartProcess();
+};
+const cmdMcp = async ({ push, args, openWizard }) => {
+    // 不另建一套 MCP 编辑界面：直接打开配置中心里已有的 MCP 屏。
+    // 增 / 删 / 改 / 启停 / 切换作用域都在那一屏里；关闭后宿主会因 `mcpChanged`
+    // 自动 `session.reload()`，新服务器当场生效（与 /config 走同一条路径）。
+    const rawScope = args[0];
+    const explicit = parseMcpScope(rawScope);
+    if (rawScope && !explicit) {
+        push(t("cmd.mcp.unknownScope", { scope: rawScope }), "error");
+        return;
+    }
+    const scope = explicit ??
+        pickStartScope({
+            // 这里读只是为了「默认进哪个作用域」：坏文件按空配置算即可，
+            // 「已损坏」的提示由编辑屏负责（宿主那一轮会重新读并带上原因）
+            global: mcpConfigOrEmpty(await readMcpConfig("global")),
+            project: mcpConfigOrEmpty(await readMcpConfig("project")),
+        });
+    await openWizard({ kind: "mcp", scope });
+};
+const cmdLang = async ({ push, args, refreshLocale }) => {
+    // `/lang` 无参在中文 / 英文之间切；`/lang zh`、`/lang en` 直接指定。
+    // 状态栏、输入行、通知等界面文案都走 `t()`，但它是模块级函数 —— 语言变了
+    // 已渲染的内容不会自己更新，必须让 React 重跑一遍渲染函数（refreshLocale）。
+    const wanted = args[0]?.toLowerCase();
+    if (wanted && wanted !== "zh" && wanted !== "en") {
+        push(t("cmd.lang.unknown", { lang: wanted }), "error");
+        return;
+    }
+    const target = wanted ?? (getLocale() === "zh" ? "en" : "zh");
+    await persistLocale(target);
+    refreshLocale();
+    push(t("notice.languageChanged"));
+};
+const cmdThink = async ({ session, push, args, setEffortView, pick }) => {
+    const config = await readConfig();
+    const presets = await readReasoningPresets();
+    const store = await readAgentStore();
+    const definition = store.agents.find((item) => item.id === session.agentId) ?? null;
+    const modelId = definition?.modelId;
+    if (!modelId) {
+        push(t("cmd.think.noModel", { id: session.agentId }), "error");
+        return;
+    }
+    const model = (config.models ?? []).find((item) => item.id === modelId);
+    if (!model) {
+        push(t("cmd.think.modelMissing", { id: modelId }), "error");
+        return;
+    }
+    const choices = effortChoices(model, presets);
+    if (choices.length === 0) {
+        push(t("cmd.think.notAdjustable", { id: model.id }), "error");
+        return;
+    }
+    // 支持 `/think high` 直设、`/think default` 恢复跟随模型默认，无参时弹选择器
+    let picked = args[0];
+    if (picked !== undefined && picked !== "default" && !choices.includes(picked)) {
+        push(t("cmd.think.unknown", { level: picked, options: choices.join(" / ") }), "error");
+        return;
+    }
+    if (!picked) {
+        // 「当前」指 Agent 定义上真正写着的那一档（模型默认参数不算，那是跟随状态）
+        const current = matchLevel(presetFor(model.id, model.reasoningPreset, presets), definition?.modelParams);
+        const items = [
+            {
+                label: `${t("cmd.think.followDefault")}${current ? "" : t("common.current")}`,
+                value: "default",
+                hint: t("cmd.think.clearHint"),
+            },
+            ...choices.map((value) => ({
+                label: `${effortLabel(value)}${value === current ? t("common.current") : ""}`,
+                value,
+                hint: value,
+            })),
+        ];
+        const choice = await pick(t("cmd.think.title", { level: describeEffort(model, presets, definition) }), items);
+        if (choice == null) {
+            push(t("cmd.think.cancelled"));
+            return;
+        }
+        picked = choice;
+    }
+    const effort = picked === "default" ? null : picked;
+    const agentLevel = matchLevel(presetFor(model.id, model.reasoningPreset, presets), definition?.modelParams);
+    const unchanged = effort === null ? agentLevel === undefined : agentLevel === effort;
+    if (unchanged) {
+        push(t("cmd.think.unchanged"));
+        return;
+    }
+    try {
+        const result = await setAgentEffort({
+            config,
+            presets,
+            agentId: session.agentId,
+            effort,
+            // 已读过定义，避免命令层与写入层各读一次盘
+            readAgent: async () => definition,
+        });
+        // 状态栏先跟上；档位要通过重建 Agent 才会进请求参数
+        setEffortView(describeEffortView(result.model, presets, result.definition));
+        await session.reload();
+        push(result.summary);
+    }
+    catch (error) {
+        push(t("cmd.think.failed", { error: error?.message ?? error }), "error");
+    }
+};
+const cmdKey = async ({ openKeyEditor }) => {
+    await openKeyEditor();
+};
+const cmdHandoff = async ({ session, push, args, setPickerState }) => {
+    const handoff = parseHandoffSelection(args);
+    if (handoff.invalid !== undefined) {
+        push(t("cmd.handoff.unknownMode", { who: handoff.invalid }), "error");
+        return;
+    }
+    if (!session.messages.some((m) => m.role === AgentNS.Role.User)) {
+        push(t("cmd.handoff.empty"), "error");
+        return;
+    }
+    // 未显式指定执行者时三选一（与自动迁移统一）；显式 `/handoff self|summary` 则直接采用
+    const chosen = handoff.mode ?? (await chooseHandoffMode(setPickerState, t("cmd.handoff.title")));
+    if (chosen == null) {
+        push(t("cmd.handoff.cancelled"));
+        return;
+    }
+    try {
+        const path = await session.handoff(chosen);
+        push(t("cmd.handoff.done", { path }));
+    }
+    catch (error) {
+        // 用户按 Ctrl+C 取消：不是失败，也不该报错堆栈
+        if (error instanceof HandoffAbortedError) {
+            push(t("cmd.handoff.cancelled"));
+            return;
         }
-        case "exit":
-        case "quit": {
-            await doExit();
-            break;
+        push(t("cmd.handoff.failed", { error: error?.message ?? error }), "error");
+    }
+};
+const cmdMigrate = async ({ session, push, args, setPickerState, clearTranscript }) => {
+    const handoff = parseHandoffSelection(args);
+    if (handoff.invalid !== undefined) {
+        push(t("cmd.handoff.unknownMode", { who: handoff.invalid }), "error");
+        return;
+    }
+    if (!session.messages.some((m) => m.role === AgentNS.Role.User)) {
+        push(t("cmd.migrate.empty"), "error");
+        return;
+    }
+    // 与原 yes/no 确认统一为三选一：选「不交接」即取消本次迁移
+    const chosen = handoff.mode ?? (await chooseHandoffMode(setPickerState, t("cmd.migrate.title")));
+    if (chosen == null) {
+        push(t("cmd.migrate.cancelled"));
+        return;
+    }
+    try {
+        const path = await session.migrate(chosen);
+        // 迁移用 `prune` 策略把 messages 剔除到「系统提示 + 交接断点」（仅 1~2 条），
+        // 转录显示起点必须跟着归零，否则 `messages.slice(transcriptFrom)` 恒为空——
+        // 迁移成功、上下文有内容，但屏幕上什么都没有（同 `/new` 分支的做法）。
+        clearTranscript();
+        push(t("cmd.migrate.done", { path }));
+    }
+    catch (error) {
+        // 用户按 Ctrl+C 取消：交接已停下且未改动会话，不是失败
+        if (error instanceof HandoffAbortedError) {
+            push(t("cmd.migrate.cancelled"));
+            return;
         }
-        default:
-            push(`未知命令：${raw}（输入 /help 查看可用命令）`, "error");
+        push(t("cmd.migrate.failed", { error: error?.message ?? error }), "error");
+    }
+};
+const cmdHelp = async ({ push }) => {
+    const lines = [t("cmd.help.title")];
+    for (const hint of matchCommandHints("")) {
+        lines.push(`  ${hint.label}  ${hint.description}`);
+    }
+    push(lines.join("\n"));
+};
+const cmdExit = async ({ doExit }) => {
+    await doExit();
+};
+/**
+ * 命令处理器表 —— 键是**主名**，类型保证与 `COMMAND_REGISTRY` 一一对应。
+ * 别名（`/effort`、`/quit`）由 `canonicalCommandName()` 归一后落到同一处理器。
+ */
+const HANDLERS = {
+    save: cmdSave,
+    load: cmdLoad,
+    new: cmdNew,
+    back: cmdBack,
+    editor: cmdEditor,
+    clear: cmdClear,
+    config: cmdConfig,
+    model: cmdModel,
+    agent: cmdAgent,
+    reload: cmdReload,
+    update: cmdUpdate,
+    mcp: cmdMcp,
+    lang: cmdLang,
+    think: cmdThink,
+    key: cmdKey,
+    handoff: cmdHandoff,
+    migrate: cmdMigrate,
+    help: cmdHelp,
+    exit: cmdExit,
+};
+/** 组装执行上下文：参数解析、通知与选择器的统一入口 */
+function buildContext(name, raw, host) {
+    return {
+        ...host,
+        name,
+        raw,
+        // 参数切分与命令名解析同源（registry 的 splitCommandInput），命令层不再自己切一遍
+        args: parseCommandArgs(raw),
+        push: (text, tone = "info") => host.notice(text, tone),
+        pick: (title, items) => new Promise((resolve) => host.setPickerState({ title, items, resolve })),
+        confirm: (question) => new Promise((resolve) => host.setConfirmState({ question, resolve })),
+    };
+}
+/**
+ * 执行一条斜杠命令。
+ *
+ * @param name 命令名（含别名，大小写不敏感；由 `parseCommandInput()` 从输入里取出）
+ * @param raw  原始输入（含 `/`），用于参数解析与错误回显
+ */
+export async function runCommand(name, raw, host) {
+    const canonical = canonicalCommandName(name);
+    if (!canonical) {
+        host.notice(t("cmd.unknown", { cmd: raw }), "error");
+        return;
     }
+    await HANDLERS[canonical](buildContext(canonical, raw, host));
 }
 //# sourceMappingURL=chat-commands.js.map