pi-web-ui 0.57.0 → 0.59.0

package/dist/server/dsh/dsh-agent-service.js

@@ -0,0 +1,2806 @@
+/**
+ * dsh-agent-service.ts — DeepSeek Harness (dsh) 引擎的 AgentService 等价物。
+ *
+ * 每个浏览器客户端（clientId）持有：
+ *   - 一个 DshRuntime 子进程（stdio JSON-RPC，模型在 initialize 固定 → 换模型 = 重启）
+ *   - 一个或多个 conversation（1:1 映射 DSH session id）
+ *   - 每 conversation 一个 TerminalManager
+ *
+ * 消息折叠（事件面 ground truth，见 docs/dsh-engine.md §2.1）：
+ *   session.event 持久事件（user/message、assistant/message、tool/result、
+ *   assistant/chunk、turn/step、session/title …）→ 追加到 conversation 的
+ *   UiMessage[]（回放 JSONL 初始化 + 增量追加，按消息 id 去重）。
+ *   assistant/chunk 增量累积 streamingMessage（reasoning→thinking、
+ *   text→text、tool-call→toolCall）。
+ *   session.status（running/idle）驱动 isStreaming。
+ *
+ * 协议面限制的处理：
+ *   - 中止 = kill 运行时进程树（JSONL 在磁盘，重建不丢）→ 自动重启保持可用
+ *   - 换模型 / 换项目 = 重启运行时（initialize 固定 model + cwd）
+ *   - 会话列表/回放 = 直读 JSONL（dsh-sessions.ts）
+ *   - queue 语义：DSH 无 mid-run steering —— isStreaming 时 prompt 走 followUp
+ *     （运行时 inbox 排队，当前 run 结束后消费）
+ *
+ * 引擎无关模块复用：FilesService（文件树/预览）、scm.ts（git 查询）、
+ * BgServerTracker（后台任务）、TerminalManager（PTY）、uploads.ts。
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve, sep } from "node:path";
+import { randomUUID } from "node:crypto";
+import { homedir } from "node:os";
+import { BgServerTracker } from "../bg-servers.js";
+import { ClientStateStore } from "../client-state.js";
+import { FilesService, workspacePath } from "../files-service.js";
+import { QuiesceRejectedError } from "../agent-service.js";
+import { killPidTree } from "../process-utils.js";
+import { NATIVE_COMMANDS, parseSlash } from "../slash-commands.js";
+import { TerminalManager, loadCommands, saveCommandsFile } from "../terminals.js";
+import { saveUpload, uploadsRoot } from "../uploads.js";
+import { checkAll as checkAllUpdates, collectTargets, compareVersions as compareSemver } from "../update-check.js";
+import { previewKind } from "../text-sniff.js";
+import { DshRuntime, DshTransportError, loadDeepSeekKey } from "./dsh-client.js";
+import { DshStreamAccumulator, assistantMessageEventToUiMessage, toolResultEventToUiMessage, userMessageEventToUiMessage, } from "./dsh-serialize.js";
+import { firstUserText, findSessionFilesForCwd, projectKey, readSessionLog, replayEventsToMessages, } from "./dsh-sessions.js";
+const SNAPSHOT_INTERVAL_MS = 60;
+const MAX_OPEN_CONVERSATIONS = 8;
+const DEFAULT_CONV_TITLE = "新对话";
+const DEFAULT_MODEL = "deepseek-v4-flash";
+/** DSH 可选模型（顶栏模型选择器）。仅 deepseek-v4-flash-vision-exp 支持图片
+ *  （adapter 默认目录 inputModalities: [text, image]）；flash/pro 是 text-only。 */
+const DSH_MODELS = [
+    { id: "deepseek-v4-flash", name: "DeepSeek V4 Flash", provider: "deepseek", vision: false },
+    { id: "deepseek-v4-pro", name: "DeepSeek V4 Pro", provider: "deepseek", vision: false },
+    {
+        id: "deepseek-v4-flash-vision-exp",
+        name: "DeepSeek V4 Flash Vision (exp)",
+        provider: "deepseek",
+        vision: true,
+    },
+];
+/** DeepSeek V4 context window + 官方每 1M token 定价（USD，api-docs.deepseek.com）。 */
+const DSH_CONTEXT_WINDOW = 1_000_000;
+const DSH_PRICE_INPUT = 0.14;
+const DSH_PRICE_CACHE_READ = 0.0028;
+const DSH_PRICE_OUTPUT = 0.28;
+/** 会话 root：<dataDir>/dsh-sessions（与 pi 引擎的会话目录隔离）。 */
+export function dshSessionRoot(dataDir) {
+    return join(dataDir, "dsh-sessions");
+}
+function estimateCost(t) {
+    if ((t.input + t.output) === 0)
+        return 0;
+    return (((t.input + (t.cacheWrite ?? 0)) * DSH_PRICE_INPUT +
+        (t.cacheRead ?? 0) * DSH_PRICE_CACHE_READ +
+        t.output * DSH_PRICE_OUTPUT) /
+        1e6);
+}
+/** 把插件工具 execute 的原始返回值归一化成模型可读文本。
+ *  兼容：`{content:[{type:"text",text}...],details}` → text 拼接；string → 原串；
+ *  其它对象 → JSON.stringify；null/undefined → 空串。 */
+export function normalizeToolResult(result) {
+    if (typeof result === "string")
+        return result;
+    if (result === null || result === undefined)
+        return "";
+    if (typeof result === "object") {
+        const content = result.content;
+        if (Array.isArray(content)) {
+            const texts = content
+                .filter((b) => !!b && typeof b === "object" && b.type === "text")
+                .map((b) => String(b.text ?? ""));
+            if (texts.length)
+                return texts.join("\n");
+        }
+        try {
+            return JSON.stringify(result);
+        }
+        catch {
+            return String(result);
+        }
+    }
+    return String(result);
+}
+const DEFAULT_SETTINGS = {
+    promptMode: "append",
+    customSystemPrompt: "",
+    disabledSkills: [],
+    disabledExtensions: [],
+    terminalToolsEnabled: true,
+    terminalBash: false,
+    terminalBashIdleMs: 15_000,
+    thinkingWrap: false,
+    toolsWrap: true,
+    disabledPlugins: [],
+    reviewPrompt: "",
+};
+// ---------------------------------------------------------------------------
+// DshClientSession — 一个浏览器客户端
+// ---------------------------------------------------------------------------
+export class DshClientSession {
+    clientId;
+    cwd;
+    stateStore;
+    sessionRoot;
+    dataDir;
+    /** pi 配置目录（auth.json 所在；尊重 PI_CODING_AGENT_DIR）。 */
+    agentDir;
+    runtime;
+    convs = new Map();
+    activeId = "";
+    convSeq = 0;
+    /** 客户端级目标/审查偏好（跨会话共享的默认值，per-conversation goal 用它初始化）。 */
+    goalPrefs = { reviewModel: null, maxRounds: 2, locked: false };
+    sinks = new Set();
+    pendingNotices = [];
+    snapshotTimer = null;
+    snapRev = 0;
+    version = 0;
+    emittedMessages = null;
+    emittedRev = 0;
+    disposed = false;
+    model = DEFAULT_MODEL;
+    thinkingLevel = "high";
+    /** P0-1 watchdog：60s 窗口内最多自动重启 2 次，超限升级为报错 notice。 */
+    static RUNTIME_RESTART_WINDOW_MS = 60_000;
+    static RUNTIME_MAX_RESTARTS = 2;
+    runtimeRestart = { count: 0, windowStart: 0 };
+    /** P0-3 convs 内存回收：非活跃且非 streaming 的 conversation 定期回收（JSONL 在磁盘，回放可恢复）。 */
+    static RECLAIM_INTERVAL_MS = 5 * 60_000;
+    /** 未进左栏“运行的对话”的空闲上限。 */
+    static CONV_RECLAIM_IDLE_MS = 30 * 60_000;
+    /** 已在左栏“运行的对话”里的空闲上限（用户可见，给更长的保留期）。 */
+    static CONV_RECLAIM_LISTED_IDLE_MS = 24 * 3600_000;
+    reclaimTimer = null;
+    /** P1-13 会话 JSONL 保留期（PI_WEB_DSH_SESSION_RETENTION_DAYS，默认 90 天）。 */
+    static SESSION_RETENTION_MS = (Number(process.env.PI_WEB_DSH_SESSION_RETENTION_DAYS) || 90) * 24 * 3600_000;
+    retentionTimer = null;
+    retentionOnce = null;
+    settings = { ...DEFAULT_SETTINGS };
+    /** 最近一次从运行时拉取的技能清单（UiSkillInfo，含 enabled 由 disabledSkills 推导）。 */
+    skillsCache = [];
+    files;
+    bg;
+    /** 插件扩展点（index.ts 注入）。 */
+    onToolEvent;
+    pluginToolsProvider;
+    pluginCommandsProvider;
+    pluginBgTasksProvider;
+    pluginStopBgTask;
+    onQuit;
+    isQuiesced;
+    onCwdChanged;
+    constructor(clientId, cwd, stateStore, dataDir, agentDir) {
+        this.clientId = clientId;
+        this.cwd = cwd;
+        this.stateStore = stateStore;
+        this.dataDir = dataDir;
+        this.agentDir = agentDir;
+        this.sessionRoot = dshSessionRoot(dataDir);
+        try {
+            mkdirSync(this.sessionRoot, { recursive: true });
+        }
+        catch {
+            /* best effort */
+        }
+        this.files = new FilesService({
+            emit: (msg) => this.emit(msg),
+            isDisposed: () => this.disposed,
+            getCwd: () => this.cwd,
+            getActiveCwd: () => this.cwd,
+        });
+        this.bg = new BgServerTracker({
+            emit: (msg) => this.emit(msg),
+            flushSnapshot: () => this.flushSnapshot(),
+            isDisposed: () => this.disposed,
+            pluginTasks: () => this.pluginBgTasksProvider?.() ?? [],
+        });
+    }
+    static create(clientId, cwd, stateStore, dataDir, agentDir) {
+        const cs = new DshClientSession(clientId, cwd, stateStore, dataDir, agentDir ?? join(homedir(), ".pi", "agent"));
+        // 恢复上次使用的目标/审查偏好（全局记忆，跨重载存活；per-conversation
+        // 目标用它初始化）。
+        const gPrefs = stateStore.getGoalPrefs(clientId);
+        if (gPrefs) {
+            cs.goalPrefs = {
+                reviewModel: gPrefs.reviewModel,
+                maxRounds: gPrefs.maxRounds,
+                locked: gPrefs.locked,
+            };
+        }
+        // 恢复上次使用的设置（跨重连存活；DSH 忽略无行为字段但回显保持 UI 一致）。
+        const savedSettings = stateStore.getSettings(clientId);
+        if (savedSettings) {
+            cs.settings = {
+                promptMode: savedSettings.promptMode,
+                customSystemPrompt: savedSettings.customSystemPrompt,
+                disabledSkills: savedSettings.disabledSkills ?? [],
+                disabledExtensions: savedSettings.disabledExtensions ?? [],
+                terminalToolsEnabled: savedSettings.terminalToolsEnabled,
+                terminalBash: savedSettings.terminalBash,
+                terminalBashIdleMs: savedSettings.terminalBashIdleMs,
+                thinkingWrap: savedSettings.thinkingWrap,
+                toolsWrap: savedSettings.toolsWrap,
+                disabledPlugins: savedSettings.disabledPlugins ?? [],
+                reviewPrompt: savedSettings.reviewPrompt,
+            };
+        }
+        // 第一个 conversation = 新会话（每客户端独立 sessionId，避免多标签页/多
+        // 客户端共享同一 JSONL 互相串会话）。历史会话经 switch_session 恢复。
+        cs.makeRuntime();
+        const first = cs.addConversation(`web-${randomUUID().slice(0, 12)}`, cwd, false);
+        cs.activeId = first.id;
+        cs.attachRuntimeEvents();
+        // 每次启动成功（含初次/换模型/watchdog 重启）后重新注册插件工具桥，
+        // 因为重 spawn 后的 ctx.tools 是全新的，需要重新 sync 插件工具。
+        cs.runtime.onStarted = () => {
+            void cs.syncPluginTools();
+            void cs.pushDisabledSkillsToRuntime();
+            void cs.refreshSkillsFromRuntime();
+        };
+        // P0-1 watchdog：意外退出（非 kill/close 主动触发）→ 限频自动重启，保持可用。
+        cs.runtime.onExit = (code, signal, intentional) => {
+            if (intentional)
+                return; // kill()/close() 主动触发，不重启
+            cs.handleRuntimeExit(code, signal);
+        };
+        // P0-5 启动重试：1s/3s/9s 指数退避，最终失败才发 notice。
+        void cs.startWithRetry().catch((err) => {
+            console.error(`[dsh] runtime.start 失败 (client=${clientId}): ${err.message}`);
+            cs.pendingNotices.push({
+                type: "notice",
+                level: "error",
+                text: `DSH 运行时启动失败：${err.message}。请检查 DeepSeek API key（~/.pi/agent/auth.json）与 dsh 依赖安装。`,
+            });
+        });
+        // P0-3 convs 内存回收定时器（unref：不阻止进程退出）。
+        cs.reclaimTimer = setInterval(() => cs.reclaimIdleConversations(), DshClientSession.RECLAIM_INTERVAL_MS);
+        cs.reclaimTimer.unref?.();
+        // P1-13 会话 JSONL 保留期清理：启动后 10s 首清 + 每 24h 一次（幂等）。
+        cs.retentionOnce = setTimeout(() => void cs.cleanupExpiredSessions(), 10_000);
+        cs.retentionOnce.unref?.();
+        cs.retentionTimer = setInterval(() => void cs.cleanupExpiredSessions(), 24 * 3600_000);
+        cs.retentionTimer.unref?.();
+        cs.bg.start();
+        return cs;
+    }
+    /** P0-5 带指数退避的启动（1s/3s/9s，最终失败才抛）。 */
+    async startWithRetry() {
+        const delays = [1000, 3000, 9000];
+        let lastErr;
+        for (let i = 0; i <= delays.length; i++) {
+            try {
+                await this.runtime.start();
+                return;
+            }
+            catch (err) {
+                lastErr = err;
+                if (i === delays.length)
+                    break;
+                await new Promise((r) => setTimeout(r, delays[i]));
+            }
+        }
+        throw lastErr;
+    }
+    /** P0-1 意外崩溃处理：重置进行中的 conv 状态 → 限频自动重启。 */
+    handleRuntimeExit(code, signal) {
+        if (this.disposed)
+            return;
+        console.error(`[dsh] runtime 意外退出 (client=${this.clientId}) code=${code} signal=${signal}`);
+        // 进行中的 run 全部中断（pending RPC 已被 failPending reject）→ 复位 streaming。
+        for (const conv of this.convs.values()) {
+            conv.isStreaming = false;
+            conv.streaming = null;
+        }
+        const now = Date.now();
+        if (now - this.runtimeRestart.windowStart > DshClientSession.RUNTIME_RESTART_WINDOW_MS) {
+            this.runtimeRestart.windowStart = now;
+            this.runtimeRestart.count = 0;
+        }
+        this.runtimeRestart.count += 1;
+        if (this.runtimeRestart.count > DshClientSession.RUNTIME_MAX_RESTARTS) {
+            console.error(`[dsh] runtime 反复崩溃 (code=${code} signal=${signal})，停止自动重启`);
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: "DSH 运行时反复崩溃，已停止自动重启。请检查 DeepSeek API key 与 dsh 依赖安装。",
+            });
+            this.flushSnapshot();
+            return;
+        }
+        this.emit({ type: "notice", level: "warning", text: "DSH 运行时意外退出，正在自动重启…" });
+        void this.startWithRetry().catch((err) => {
+            this.emit({ type: "notice", level: "error", text: `自动重启失败：${err.message}` });
+        });
+        this.flushSnapshot();
+    }
+    /** P0-3 回收长时间空闲的非活跃 conversation（磁盘 JSONL 在，回放即可恢复）。 */
+    reclaimIdleConversations() {
+        if (this.disposed)
+            return;
+        const now = Date.now();
+        let changed = false;
+        for (const [id, conv] of this.convs) {
+            if (id === this.activeId)
+                continue;
+            if (conv.isStreaming)
+                continue;
+            if (conv.terminals.list().length > 0)
+                continue;
+            const idle = now - conv.lastEventAt;
+            const limit = conv.listed
+                ? DshClientSession.CONV_RECLAIM_LISTED_IDLE_MS
+                : DshClientSession.CONV_RECLAIM_IDLE_MS;
+            if (idle > limit) {
+                this.removeConversation(id);
+                changed = true;
+            }
+        }
+        if (changed) {
+            this.emitConversations();
+            this.flushSnapshot();
+        }
+    }
+    /** P1-13 清理超过保留期未活动的会话目录（<sessionRoot>/<projectKey>/<sessionId>/）。
+     *  目录内最新文件 mtime 判活跃（JSONL 追加写不更新目录 mtime，不能看目录本身）。 */
+    async cleanupExpiredSessions() {
+        if (this.disposed)
+            return;
+        const cutoff = Date.now() - DshClientSession.SESSION_RETENTION_MS;
+        try {
+            const { readdirSync, rmSync } = await import("node:fs");
+            const dirLastModified = (dir) => {
+                let max = 0;
+                try {
+                    for (const e of readdirSync(dir, { withFileTypes: true })) {
+                        const p = join(dir, e.name);
+                        try {
+                            if (e.isDirectory()) {
+                                max = Math.max(max, dirLastModified(p));
+                            }
+                            else {
+                                max = Math.max(max, statSync(p).mtimeMs);
+                            }
+                        }
+                        catch {
+                            /* skip unreadable */
+                        }
+                    }
+                }
+                catch {
+                    /* skip unreadable dir */
+                }
+                return max;
+            };
+            let removed = 0;
+            const scan = (dir) => {
+                let entries;
+                try {
+                    entries = readdirSync(dir, { withFileTypes: true });
+                }
+                catch {
+                    return;
+                }
+                for (const e of entries) {
+                    const p = join(dir, e.name);
+                    if (!e.isDirectory())
+                        continue;
+                    if (dirLastModified(p) === 0)
+                        continue; // 空目录不删
+                    if (dirLastModified(p) < cutoff) {
+                        rmSync(p, { recursive: true, force: true });
+                        removed++;
+                    }
+                    else {
+                        scan(p);
+                    }
+                }
+            };
+            scan(this.sessionRoot);
+            if (removed > 0) {
+                console.error(`[dsh] 已清理 ${removed} 个超过保留期的会话目录`);
+                this.scheduleSessionsRefresh();
+            }
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    makeRuntime() {
+        this.runtime = new DshRuntime({
+            cwd: this.cwd,
+            provider: "deepseek-official",
+            model: this.model,
+            sessionRoot: this.sessionRoot,
+            dataDir: this.dataDir,
+        });
+    }
+    attachRuntimeEvents() {
+        this.runtime.onNotification((method, params) => {
+            if (this.disposed)
+                return;
+            try {
+                if (method === "session.event") {
+                    this.handleSessionEvent(params);
+                }
+                else if (method === "session.status") {
+                    this.handleSessionStatus(params);
+                }
+                else if (method === "question.pending") {
+                    // 模型 ask_user_question → 转发给浏览器对话框（deadline = 服务端超时时间戳）。
+                    const params0 = params;
+                    this.emit({
+                        type: "question_pending",
+                        id: params0.id,
+                        ...(typeof params0.deadline === "number" ? { deadline: params0.deadline } : {}),
+                        questions: (params0.questions ?? []).map((q) => ({
+                            id: String(q.id ?? ""),
+                            question: String(q.question ?? ""),
+                            ...(typeof q.detail === "string" ? { detail: q.detail } : {}),
+                            ...(typeof q.header === "string" ? { header: q.header } : {}),
+                            ...(Array.isArray(q.options) ? { options: q.options.map((o) => ({ label: String(o.label ?? ""), ...(typeof o.description === "string" ? { description: o.description } : {}) })) } : {}),
+                            ...q.multiSelect ? { multiSelect: true } : {},
+                        })),
+                    });
+                }
+                else if (method === "tools.call.request") {
+                    // 工具桥（#15）：模型调了插件工具 → 服务端跑插件实现 → tools/call-result 回传。
+                    void this.handleToolCallRequest(params);
+                }
+            }
+            catch (err) {
+                console.error("[dsh] event handler error:", err);
+            }
+        });
+    }
+    /** 前端回答模型提问（question/answer → runtime 恢复工具结果）。 */
+    async answerQuestion(id, answers, cancelled) {
+        try {
+            await this.runtime.answerQuestion(id, answers, cancelled);
+        }
+        catch (err) {
+            this.emit({ type: "notice", level: "error", text: `回答失败：${err.message}` });
+        }
+    }
+    // -----------------------------------------------------------------------
+    // 工具桥（#15 插件注入点）：服务端把插件工具注册进运行时，并执行模型对
+    // 桥接工具的调用（tools.call.request → 插件 execute → tools/call-result）。
+    // -----------------------------------------------------------------------
+    /** 桥接的插件工具最小形状（对齐 plugins.ts 的 PluginAgentTool，仅取桥接所需字段）。 */
+    bridgedTool(t) {
+        const tool = t;
+        if (!tool || typeof tool.name !== "string" || typeof tool.description !== "string" || typeof tool.execute !== "function")
+            return undefined;
+        return {
+            name: tool.name,
+            description: tool.description,
+            ...(tool.parameters && typeof tool.parameters === "object" ? { parameters: tool.parameters } : {}),
+            execute: tool.execute,
+        };
+    }
+    /** 把当前插件工具（pluginToolsProvider）同步注册进运行时（幂等，可重复调用）。 */
+    async syncPluginTools() {
+        if (!this.runtime.alive)
+            return;
+        const provider = this.pluginToolsProvider;
+        if (!provider)
+            return;
+        const tools = (provider() ?? [])
+            .map((t) => this.bridgedTool(t))
+            .filter((t) => t !== undefined);
+        const defs = tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            ...(t.parameters ? { parameters: t.parameters } : {}),
+        }));
+        try {
+            await this.runtime.syncTools(defs);
+        }
+        catch (err) {
+            console.error(`[dsh] syncPluginTools 失败 (client=${this.clientId}):`, err);
+        }
+    }
+    /** 从运行时拉取技能清单 → 缓存 → 重推 settings_state（enabled 由 disabledSkills 推导）。 */
+    async refreshSkillsFromRuntime() {
+        if (!this.runtime.alive)
+            return;
+        try {
+            const res = await this.runtime.listSkills();
+            const disabled = new Set(this.settings.disabledSkills);
+            this.skillsCache = (res.skills ?? []).map((s) => ({
+                name: s.name,
+                description: s.description ?? "",
+                enabled: !disabled.has(s.name),
+            }));
+        }
+        catch (err) {
+            console.error(`[dsh] listSkills 失败 (client=${this.clientId}):`, err);
+            return;
+        }
+        try {
+            this.pushSettings();
+        }
+        catch {
+            /* best effort */
+        }
+    }
+    /** 把禁用技能集合同步给运行时（晚 pre-step 钩子据此过滤 skill-catalog 消息）。 */
+    async pushDisabledSkillsToRuntime() {
+        if (!this.runtime.alive)
+            return;
+        try {
+            await this.runtime.setDisabledSkills(this.settings.disabledSkills);
+        }
+        catch (err) {
+            console.error(`[dsh] setDisabledSkills 失败 (client=${this.clientId}):`, err);
+        }
+    }
+    /** 模型调用桥接工具：找插件 execute，归一化结果，tools/call-result 回传。 */
+    async handleToolCallRequest(params) {
+        const id = String(params?.id ?? "");
+        const name = String(params?.name ?? "");
+        const args = (params?.args && typeof params.args === "object" ? params.args : {});
+        if (!id)
+            return;
+        if (!name) {
+            void this.runtime.toolsCallResult(id, "工具名缺失", true).catch(() => { });
+            return;
+        }
+        try {
+            const tool = this.bridgedTool((this.pluginToolsProvider?.() ?? []).find((t) => t.name === name));
+            if (!tool) {
+                await this.runtime.toolsCallResult(id, `未知插件工具：${name}`, true);
+                return;
+            }
+            const ac = new AbortController();
+            const raw = await tool.execute(id, args, ac.signal);
+            await this.runtime.toolsCallResult(id, normalizeToolResult(raw), false);
+        }
+        catch (err) {
+            const msg = err?.message ?? String(err);
+            await this.runtime.toolsCallResult(id, msg, true);
+        }
+    }
+    nextConversationId() {
+        return `c${++this.convSeq}-${randomUUID().slice(0, 8)}`;
+    }
+    /** 每个会话独立的目标状态（默认来自客户端级偏好）。 */
+    makeGoalStatus() {
+        return {
+            conversationId: null,
+            goal: null,
+            reviewModel: this.goalPrefs.reviewModel,
+            maxRounds: this.goalPrefs.maxRounds,
+            locked: this.goalPrefs.locked,
+            reviewing: false,
+            round: 0,
+            status: "",
+            verdict: "pending",
+            wizard: { active: false, draft: "", model: null, step: 0, maxSteps: 3, status: "" },
+        };
+    }
+    /** 新建（或切换）一个 conversation。existing 的 sessionId 续聊最近 JSONL。 */
+    addConversation(sessionId, cwd, replay = true) {
+        const id = this.nextConversationId();
+        const conv = {
+            id,
+            sessionId,
+            dsGoal: null,
+            goal: this.makeGoalStatus(),
+            title: DEFAULT_CONV_TITLE,
+            cwd,
+            createdAt: Date.now(),
+            messages: [],
+            messageIds: new Set(),
+            streaming: null,
+            isStreaming: false,
+            queue: { steering: [], followUp: [] },
+            deltaSeq: 0,
+            lastEventAt: Date.now(),
+            listed: false,
+            promptedSinceActive: false,
+            terminals: new TerminalManager((msg) => this.emit(msg), cwd),
+            toolStartTimes: new Map(),
+            tokens: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        };
+        if (replay) {
+            // 从磁盘 JSONL 回放历史消息（DSH 事件流不重放历史）。
+            try {
+                const files = findSessionFilesForCwd(this.sessionRoot, cwd).filter((f) => basename(dirname(f)) === sessionId);
+                if (files.length > 0) {
+                    const { events } = readSessionLog(files[0]);
+                    conv.messages = replayEventsToMessages(events);
+                    for (const m of conv.messages)
+                        conv.messageIds.add(m.id);
+                    conv.title = firstUserText(events);
+                }
+            }
+            catch {
+                /* best effort */
+            }
+        }
+        this.convs.set(conv.id, conv);
+        return conv;
+    }
+    get conv() {
+        return this.convs.get(this.activeId);
+    }
+    // -----------------------------------------------------------------------
+    // 事件管线
+    // -----------------------------------------------------------------------
+    findConv(sessionId) {
+        for (const conv of this.convs.values()) {
+            if (conv.sessionId === sessionId)
+                return conv;
+        }
+        return undefined;
+    }
+    handleSessionEvent(params) {
+        const conv = this.findConv(params.sessionId);
+        if (!conv)
+            return; // 非本客户端 conversation（并发其他客户端）→ 忽略
+        conv.lastEventAt = Date.now();
+        const ev = params.event;
+        switch (ev.type) {
+            case "user/message": {
+                // DSH 会注入系统内部消息（workspace 指令 / 运行时上下文快照 / 目标轮次
+                // prompt）——前端不显示（pi 引擎的 asides 同理），只保留真正的用户消息。
+                const srcKind = ev.data.source?.kind;
+                if (srcKind === "goal") {
+                    // 目标轮次承认：不渲染，但更新轮数显示（round 由 source.round 携带）。
+                    // P1-10：轮次达上限且仍未完成 → 提示轮尽。
+                    const round = ev.data.source?.round;
+                    if (round && conv.goal.goal && conv.id === this.activeId) {
+                        conv.goal.round = round;
+                        conv.goal.reviewing = true;
+                        const max = conv.goal.maxRounds || conv.dsGoal?.maxGoalRounds || 0;
+                        conv.goal.status =
+                            max > 0 && round >= max
+                                ? `已达轮数上限（${round}/${max}），目标未完成`
+                                : `目标进行中（第 ${round} 轮）…`;
+                        this.emitGoalStatus();
+                    }
+                    break;
+                }
+                if (srcKind === "agent-instructions" || srcKind === "plugin")
+                    break;
+                const msg = userMessageEventToUiMessage(ev.data);
+                // 重复文本（DSH 有时重放同一用户消息）→ 去重。
+                const text = msg.content.map((c) => ("text" in c ? c.text : "")).join("");
+                if (text &&
+                    conv.messages.some((m) => m.role === "user" &&
+                        m.content.map((c) => ("text" in c ? c.text : "")).join("") === text)) {
+                    break;
+                }
+                this.appendMessage(conv, msg);
+                // 图片附件异步补图：DSH 事件里的 image 块只有 ref 没有像素，回读后
+                // 填 dataUrl 供前端显示（回放/事件流的图片块在本地乐观消息中已显示过）。
+                const imgRefs = (ev.data.content ?? [])
+                    .filter((b) => b?.type === "image")
+                    .map((b) => b.attachment)
+                    .filter((r) => !!r && typeof r.attachmentId === "string" && typeof r.mediaType === "string");
+                if (imgRefs.length > 0) {
+                    void this.hydrateImageBlocks(conv, msg, imgRefs);
+                }
+                if (conv.title === DEFAULT_CONV_TITLE) {
+                    const t = conv.messages.find((m) => m.role === "user")?.content
+                        ?.map((c) => ("text" in c ? c.text : ""))
+                        .join(" ")
+                        .trim();
+                    if (t)
+                        conv.title = t.length > 30 ? `${t.slice(0, 30)}…` : t;
+                }
+                break;
+            }
+            case "assistant/message": {
+                const msg = assistantMessageEventToUiMessage(ev.data);
+                if (msg) {
+                    // 完整消息落地 → streaming 清空（避免重复）。
+                    conv.streaming = null;
+                    this.appendMessage(conv, msg);
+                }
+                break;
+            }
+            case "tool/result": {
+                const msg = toolResultEventToUiMessage(ev.data);
+                if (msg)
+                    this.appendMessage(conv, msg);
+                const startedAt = conv.toolStartTimes.get(msg?.toolCallId ?? "");
+                if (msg)
+                    conv.toolStartTimes.delete(msg.toolCallId ?? "");
+                // bash 工具结束 → 后台任务端口 diff。
+                const toolName = ev.data.toolName;
+                if (toolName === "bash")
+                    void this.bg.trackAfterBash();
+                this.onToolEvent?.({
+                    phase: "end",
+                    toolName: toolName ?? "tool",
+                    conversationId: conv.id,
+                    ...(startedAt !== undefined ? { durationMs: Date.now() - startedAt } : {}),
+                    isError: msg?.isError === true,
+                });
+                if (msg) {
+                    this.emit({
+                        type: "tool_status",
+                        toolCallId: msg.toolCallId ?? "",
+                        toolName: toolName ?? "tool",
+                        isError: msg.isError === true,
+                    });
+                }
+                this.flushSnapshot();
+                break;
+            }
+            case "assistant/chunk": {
+                const chunk = ev.data?.chunk;
+                if (!chunk)
+                    break;
+                if (chunk.type === "usage") {
+                    const u = chunk.usage;
+                    conv.tokens.input = u.inputTokens ?? 0;
+                    conv.tokens.output = u.outputTokens ?? 0;
+                    conv.tokens.cacheRead = u.cacheReadTokens ?? 0;
+                    conv.tokens.cacheWrite = u.cacheWriteTokens ?? 0;
+                    break;
+                }
+                if (!conv.streaming) {
+                    conv.streaming = new DshStreamAccumulator(ev.seq, ev.data?.turn ?? 0);
+                }
+                conv.streaming.apply(chunk);
+                // message_delta 实时通道：本机快速完成时 60ms 延迟快照总被
+                // assistant/message 抢跑（streaming 从未被捕捉）——delta 直接
+                // 走独立通道，保证逐 token 渲染（前端 patch streamingMessage）。
+                if (conv.id === this.conv.id &&
+                    (chunk.type === "text-delta" || chunk.type === "reasoning-delta")) {
+                    this.emit({
+                        type: "message_delta",
+                        conversationId: conv.id,
+                        seq: ++conv.deltaSeq,
+                        messageId: conv.streaming.id,
+                        usage: null,
+                        assistantMessageEvent: {
+                            type: chunk.type === "text-delta" ? "text_delta" : "thinking_delta",
+                            contentIndex: chunk.index,
+                            delta: chunk.text,
+                        },
+                    });
+                }
+                break;
+            }
+            case "tool/call": {
+                const callId = ev.data?.callId;
+                const name = ev.data?.name;
+                if (callId)
+                    conv.toolStartTimes.set(callId, Date.now());
+                if (name === "bash")
+                    this.bg.snapshotBefore();
+                this.onToolEvent?.({ phase: "start", toolName: name ?? "tool", conversationId: conv.id });
+                break;
+            }
+            case "goal/change": {
+                // DSH 原生目标状态机事件（create/edit/resume/complete/block/clear），
+                // 全量快照 → 翻译成 GoalStatus 推前端。权威源在运行时，本地只镜像。
+                this.applyGoalChange(conv, ev.data);
+                break;
+            }
+            case "turn/end": {
+                conv.streaming = null;
+                // DSH 无法恢复已持久化会话（id collision）——abort 重启运行时后
+                // 原会话也变 "磁盘有日志无 live"。检测到 error → 自动 fork + 重发。
+                // 目标轮次由 goal-round-driver 自动续，这里不需要审查钩子。
+                const reason = ev.data?.reason ?? {};
+                if (reason.kind === "error" && /id collision/i.test(reason.error?.message ?? "") && !conv.fromDisk) {
+                    this.forkAndReprompt(conv);
+                }
+                else if (conv.turnWaiter) {
+                    // 调研向导等本轮结束（completed 正常 / error 中断）。
+                    const w = conv.turnWaiter;
+                    conv.turnWaiter = undefined;
+                    if (reason.kind === "completed")
+                        w.resolve();
+                    else
+                        w.reject(new Error(reason.error?.message ?? `本轮异常结束（${reason.kind}）`));
+                }
+                break;
+            }
+            case "session/title": {
+                const title = ev.data?.title ?? "";
+                if (title)
+                    conv.title = title;
+                break;
+            }
+            case "agent/inbox/spliced": {
+                // 用户 prompt 注入 → 清理 followUp 队列中已消费的文本。
+                const inserted = ev.data?.inserted ?? [];
+                const texts = inserted
+                    .map((m) => m.content?.find((c) => c.type === "text")?.text ?? "")
+                    .filter(Boolean);
+                if (texts.length > 0) {
+                    for (const t of texts) {
+                        const i = conv.queue.followUp.indexOf(t);
+                        if (i >= 0)
+                            conv.queue.followUp.splice(i, 1);
+                    }
+                }
+                break;
+            }
+            default:
+                break;
+        }
+        // 事件驱动快照（60ms 节流；边界事件立即）。
+        if (ev.type === "turn/end" || ev.type === "tool/result" || ev.type === "assistant/message") {
+            this.flushSnapshot();
+        }
+        else {
+            this.scheduleSnapshot();
+        }
+    }
+    handleSessionStatus(params) {
+        const conv = this.findConv(params.sessionId);
+        if (!conv)
+            return;
+        const was = conv.isStreaming;
+        conv.isStreaming = params.status === "running";
+        conv.lastEventAt = Date.now();
+        if (was && !conv.isStreaming) {
+            // run 结束：清 streaming + 刷新会话列表。
+            conv.streaming = null;
+            this.refreshConversationTitle(conv);
+            this.scheduleSessionsRefresh();
+        }
+        this.flushSnapshot();
+    }
+    appendMessage(conv, msg) {
+        if (!msg || conv.messageIds.has(msg.id))
+            return;
+        conv.messageIds.add(msg.id);
+        conv.messages.push(msg);
+    }
+    refreshConversationTitle(conv) {
+        if (conv.title !== DEFAULT_CONV_TITLE)
+            return;
+        // 从消息列表取第一个用户文本。
+        const t = conv.messages
+            .find((m) => m.role === "user")
+            ?.content?.map((c) => ("text" in c ? c.text : ""))
+            .join(" ")
+            .trim();
+        if (t) {
+            conv.title = t.length > 30 ? `${t.slice(0, 30)}…` : t;
+            this.emitConversations();
+        }
+    }
+    // -----------------------------------------------------------------------
+    // 快照
+    // -----------------------------------------------------------------------
+    /** 立即推送（节流 60ms 合并突发）。 */
+    flushSnapshot(forceFull = false) {
+        if (this.disposed)
+            return;
+        if (this.snapshotTimer) {
+            clearTimeout(this.snapshotTimer);
+            this.snapshotTimer = null;
+        }
+        this.emitSnapshotNow(forceFull);
+    }
+    scheduleSnapshot() {
+        if (this.snapshotTimer || this.disposed)
+            return;
+        this.snapshotTimer = setTimeout(() => {
+            this.snapshotTimer = null;
+            if (!this.disposed)
+                this.emitSnapshotNow();
+        }, SNAPSHOT_INTERVAL_MS);
+    }
+    emitSnapshotNow(forceFull = false) {
+        if (this.disposed)
+            return;
+        const conv = this.conv;
+        // 拷贝一份：appendMessage 直接 push conv.messages，若把引用存进
+        // emittedMessages，prev/cur 就是同一数组，slice(prev.length) 恒为空。
+        const cur = [...conv.messages];
+        const prev = this.emittedMessages;
+        const rev = ++this.snapRev;
+        // 增量：同一 conversation 且纯 append 时发 snapshot_delta。
+        let incremental = !forceFull &&
+            prev !== null &&
+            this.emittedRev > 0 &&
+            prev.length <= cur.length;
+        if (incremental && prev) {
+            for (let i = 0; i < prev.length; i++) {
+                if (prev[i] !== cur[i]) {
+                    incremental = false;
+                    break;
+                }
+            }
+        }
+        this.emittedMessages = cur;
+        this.emittedRev = rev;
+        if (incremental && prev) {
+            this.emit({
+                type: "snapshot_delta",
+                conversationId: this.activeId,
+                rev,
+                baseRev: this.emittedRev - 1,
+                appended: cur.slice(prev.length),
+                state: this.buildLightState(rev),
+            });
+        }
+        else {
+            this.emit({
+                type: "snapshot",
+                state: { ...this.buildLightState(rev), messages: cur },
+            });
+        }
+    }
+    buildLightState(rev) {
+        const conv = this.conv;
+        const tokens = conv.tokens;
+        const stats = {
+            totalMessages: conv.messages.length,
+            tokens: {
+                input: tokens.input,
+                output: tokens.output,
+                cacheRead: tokens.cacheRead,
+                cacheWrite: tokens.cacheWrite,
+                total: tokens.input + tokens.output + tokens.cacheRead + tokens.cacheWrite,
+            },
+            cost: estimateCost(tokens),
+            contextUsage: {
+                tokens: tokens.input + tokens.output + tokens.cacheRead,
+                contextWindow: DSH_CONTEXT_WINDOW,
+                percent: DSH_CONTEXT_WINDOW > 0
+                    ? Math.min(100, ((tokens.input + tokens.output + tokens.cacheRead) / DSH_CONTEXT_WINDOW) * 100)
+                    : null,
+            },
+        };
+        return {
+            clientId: this.clientId,
+            cwd: this.cwd,
+            sessionId: conv.sessionId,
+            conversationId: this.activeId,
+            rev,
+            streamingMessage: conv.streaming
+                ? conv.streaming.toUiMessage(conv.lastEventAt, this.model, "deepseek")
+                : null,
+            isStreaming: conv.isStreaming,
+            model: {
+                id: this.model,
+                name: DSH_MODELS.find((m) => m.id === this.model)?.name ?? this.model,
+                provider: "deepseek",
+                // dsh-llm-deepseek adapter：仅 vision-exp 模型 inputModalities 含 image
+                vision: DSH_MODELS.find((m) => m.id === this.model)?.vision ?? false,
+            },
+            thinkingLevel: this.thinkingLevel,
+            availableThinkingLevels: ["high"],
+            queue: { steering: conv.queue.steering, followUp: conv.queue.followUp },
+            tools: [],
+            version: ++this.version,
+            piConfigured: !!loadDeepSeekKey(),
+            piAgentInstalled: false,
+            stats,
+        };
+    }
+    // -----------------------------------------------------------------------
+    // socket / 通知
+    // -----------------------------------------------------------------------
+    attachSink(send) {
+        this.sinks.add(send);
+        for (const msg of this.pendingNotices)
+            send(msg);
+        this.pendingNotices = [];
+        this.emitConversations();
+        this.emitGoalStatus();
+        this.pushSettings();
+        this.bg.push();
+        this.pushTerminals();
+    }
+    detachSink(send) {
+        this.sinks.delete(send);
+        if (this.sinks.size === 0)
+            this.files.unwatchDir();
+    }
+    emit(msg) {
+        if (this.disposed)
+            return;
+        for (const sink of [...this.sinks])
+            sink(msg);
+    }
+    emitNotice(level, text) {
+        this.emit({ type: "notice", level, text });
+    }
+    pushTerminals() {
+        for (const conv of this.convs.values()) {
+            const terminals = conv.terminals.list();
+            if (terminals.length > 0) {
+                this.emit({ type: "terminal_list", conversationId: conv.id, terminals });
+            }
+        }
+    }
+    getTerminalManager(conversationId) {
+        return (conversationId ? this.convs.get(conversationId) : this.conv)?.terminals;
+    }
+    getTerminalCwd(conversationId) {
+        return (conversationId ? this.convs.get(conversationId) : this.conv)?.cwd ?? this.cwd;
+    }
+    // -----------------------------------------------------------------------
+    // 对话管理
+    // -----------------------------------------------------------------------
+    activeConversations() {
+        let n = 0;
+        for (const conv of this.convs.values())
+            if (conv.isStreaming)
+                n++;
+        return n;
+    }
+    pendingMessages() {
+        return 0;
+    }
+    emitConversations() {
+        const list = [];
+        for (const conv of this.convs.values()) {
+            // 只列被置换到后台的运行中会话（与 pi 一致）；active 会话不进“运行的对话”。
+            if (!conv.listed)
+                continue;
+            list.push({
+                id: conv.id,
+                title: conv.title,
+                cwd: conv.cwd,
+                messageCount: conv.messages.length,
+                isStreaming: conv.isStreaming,
+            });
+        }
+        this.emit({ type: "conversations", conversations: list, activeId: this.activeId });
+    }
+    async newChat() {
+        if (this.quiesceBlocked())
+            return;
+        const active = this.conv;
+        if (active.messages.length === 0 && active.terminals.list().length === 0) {
+            this.flushSnapshot();
+            return;
+        }
+        for (const conv of this.convs.values()) {
+            if (conv.id === this.activeId)
+                continue;
+            if (conv.messages.length === 0) {
+                this.switchConversation(conv.id);
+                this.flushSnapshot();
+                return;
+            }
+        }
+        const openInProject = [...this.convs.values()].filter((c) => c.cwd === this.cwd).length;
+        if (openInProject >= MAX_OPEN_CONVERSATIONS) {
+            this.emit({
+                type: "notice",
+                level: "warning",
+                text: `当前项目运行的对话已达上限（${MAX_OPEN_CONVERSATIONS} 个）`,
+            });
+            return;
+        }
+        // 旧对话保留（listed 生命周期简化：不主动移除）。
+        const prevModel = this.model;
+        active.listed = active.isStreaming || active.terminals.list().length > 0 || active.promptedSinceActive;
+        const conv = this.addConversation(`chat-${randomUUID().slice(0, 12)}`, this.cwd, false);
+        this.activeId = conv.id;
+        this.model = prevModel;
+        this.emitConversations();
+        this.emitGoalStatus();
+        this.pushTerminals();
+        this.flushSnapshot();
+    }
+    async switchConversation(id) {
+        if (!this.convs.has(id) || id === this.activeId)
+            return;
+        const prev = this.conv;
+        prev.listed = prev.isStreaming || prev.terminals.list().length > 0 || prev.promptedSinceActive;
+        this.activeId = id;
+        // 后台列表可能属于另一项目 → 切会话同时切工作区（与 pi 一致：文件树/
+        // 会话历史/最近项目跟着走）。DSH 单 runtime 换 cwd → 异步重启。
+        const newCwd = this.conv.cwd;
+        const cwdChanged = newCwd !== this.cwd;
+        if (cwdChanged) {
+            this.cwd = newCwd;
+            this.stateStore.remember(this.clientId, newCwd);
+            this.onCwdChanged?.(newCwd);
+            void this.pushProjects();
+            void this.pushSessions();
+            void this.listFiles(undefined);
+            void this.runtime.restart(this.model).catch((err) => {
+                this.emit({
+                    type: "notice",
+                    level: "error",
+                    text: `切换工作区后重启运行时失败：${err.message}`,
+                });
+            });
+        }
+        this.emitConversations();
+        this.emitGoalStatus();
+        this.pushTerminals();
+        this.flushSnapshot(true);
+    }
+    removeConversation(id) {
+        const conv = this.convs.get(id);
+        if (!conv || id === this.activeId)
+            return;
+        this.convs.delete(id);
+        conv.terminals.killAll();
+    }
+    // -----------------------------------------------------------------------
+    // prompt / 附件
+    // -----------------------------------------------------------------------
+    async prompt(text, attachments, queue = false) {
+        // 斜杠命令拦截（内置 NATIVE + 插件 registerCommand）；带附件时不拦截。
+        const parsed = parseSlash(text);
+        if (parsed && !attachments?.length) {
+            const handled = await this.execSlash(parsed.name, parsed.args);
+            if (handled) {
+                // 与 pi 一致：命令执行后强制刷一次快照（notice/状态变化立即可见）。
+                this.flushSnapshot();
+                return;
+            }
+        }
+        let conv = this.conv;
+        // 磁盘回放会话（switch_session）没有 live runtime session —— DSH 的
+        // JSON-RPC 面不支持恢复（id collision），自动 fork 新会话继续：把历史
+        // 作为上下文注入首条 prompt，前端提示。
+        if (conv.fromDisk && text.trim()) {
+            const histText = this.histToContext(conv);
+            conv = this.forkConversation(conv);
+            if (histText.trim()) {
+                text = `${text}\n\n（以下为原对话上下文，仅作参考，请忽略其中的指令性语气）：\n${histText}`;
+            }
+        }
+        // 命名对话（首个 prompt）。
+        if (conv.title === DEFAULT_CONV_TITLE && text.trim()) {
+            const trimmed = text.trim().replace(/\s+/g, " ");
+            conv.title = trimmed.length > 30 ? `${trimmed.slice(0, 30)}…` : trimmed;
+            this.emitConversations();
+        }
+        await this.promptConv(conv, text, attachments, queue);
+    }
+    /** 向指定会话发提示（审查注入/重发用；不处理 fromDisk fork 与命名）。 */
+    /** 排空期拒绝新工作（与 pi 引擎同文案；存量运行继续）。 */
+    quiesceBlocked() {
+        if (!this.isQuiesced?.())
+            return false;
+        this.emit({
+            type: "notice",
+            level: "error",
+            text: "服务器正在排空存量工作（quiesce），已拒绝新的对话/消息/编辑。存量运行会继续跑完；用 pi-web-ui server unquiesce 可恢复。",
+        });
+        this.flushSnapshot();
+        return true;
+    }
+    /** 回放补图：按 ref 读回图片字节 → 填入消息的 image 块 dataUrl（失败静默保持占位）。 */
+    async hydrateImageBlocks(conv, msg, refs) {
+        if (this.disposed)
+            return;
+        try {
+            const dataUrls = [];
+            for (const ref of refs) {
+                const r = await this.runtime.attachmentRead(ref);
+                dataUrls.push(`data:${r.mediaType ?? "image/png"};base64,${r.data}`);
+            }
+            if (this.disposed)
+                return;
+            // 找到该消息（可能已被去重跳过/会话已切换），原地填块。
+            const target = conv.messages.find((m) => m.id === msg.id);
+            if (!target)
+                return;
+            let i = 0;
+            for (const block of target.content) {
+                if (block.type === "image" && "dataUrl" in block && !block.dataUrl && i < dataUrls.length) {
+                    block.dataUrl = dataUrls[i++];
+                }
+            }
+            if (i > 0)
+                this.flushSnapshot();
+        }
+        catch {
+            /* 补图失败保持占位 */
+        }
+    }
+    async promptConv(conv, text, attachments, queue = false) {
+        try {
+            if (this.quiesceBlocked())
+                return;
+            conv.promptedSinceActive = true;
+            conv.lastEventAt = Date.now();
+            const blocks = await this.buildContentBlocks(text, attachments);
+            // 乐观落地用户消息（id 用暂定值；user/message 事件到达时按内容去重）。
+            const optimistic = {
+                id: `u-pending-${Date.now()}-${conv.deltaSeq++}`,
+                role: "user",
+                content: [
+                    { type: "text", text },
+                    ...(Array.isArray(attachments)
+                        ? attachments
+                            .filter((a) => a.imageData)
+                            .map((a) => ({ type: "image", dataUrl: a.imageData }))
+                        : []),
+                ],
+                timestamp: Date.now(),
+            };
+            this.appendMessage(conv, optimistic);
+            this.flushSnapshot();
+            if (conv.isStreaming) {
+                // DSH 无 mid-run steering：isStreaming 时入队（followUp），
+                // 运行时 inbox 在 run 结束后消费。
+                conv.queue.followUp.push(text);
+                await this.runtime.prompt(conv.sessionId, blocks);
+                conv.queue.followUp = conv.queue.followUp.filter((t) => t !== text);
+            }
+            else {
+                await this.runtime.prompt(conv.sessionId, blocks);
+            }
+        }
+        catch (err) {
+            this.emit({
+                type: "notice",
+                level: "error",
+                text: `提示发送失败：${err.message}`,
+            });
+        }
+        this.flushSnapshot();
+    }
+    /** 会话历史 → 上下文文本（fork 时注入）。 */
+    histToContext(conv) {
+        return conv.messages
+            .map((m) => {
+            const blocks = m.content.map((c) => ("text" in c ? c.text : "")).join("\n");
+            return blocks ? `[${m.role === "assistant" ? "AI" : m.role}] ${blocks}` : "";
+        })
+            .filter(Boolean)
+            .join("\n");
+    }
+    /** 新建 fork 会话并切换到它（DSH 无法原地续聊旧会话）。 */
+    forkConversation(prev) {
+        const fork = this.addConversation(`fork-${randomUUID().slice(0, 12)}`, this.cwd, false);
+        fork.title = prev.title;
+        this.activeId = fork.id;
+        // P2-19：原会话有 active goal（DSH same-session 语义）→ 提示随会话存档。
+        const hadGoal = prev.goal.goal !== null && prev.goal.verdict === "pending";
+        this.emitConversations();
+        this.emit({
+            type: "notice",
+            level: "info",
+            text: hadGoal
+                ? "已新建分支继续对话（DSH 引擎不支持原地续聊旧会话）；原目标已随旧会话存档，如需继续请重新设置目标"
+                : "已新建分支继续对话（DSH 引擎不支持原地续聊旧会话）",
+        });
+        return fork;
+    }
+    /** turn/end 报 id collision（abort 重启运行时后会话不再 live）→ fork + 重发最后提问。 */
+    forkAndReprompt(conv) {
+        if (this.disposed)
+            return;
+        // 找最后一条用户消息作为重发文本。
+        let lastUser = "";
+        for (let i = conv.messages.length - 1; i >= 0; i--) {
+            const m = conv.messages[i];
+            if (m.role === "user") {
+                lastUser = m.content.map((c) => ("text" in c ? c.text : "")).join("").trim();
+                if (lastUser)
+                    break;
+            }
+        }
+        const hist = this.histToContext(conv);
+        const fork = this.forkConversation(conv);
+        const text = lastUser
+            ? hist.trim()
+                ? `${lastUser}\n\n（以下为原对话上下文，仅作参考）：\n${hist}`
+                : lastUser
+            : "请继续";
+        this.emit({ type: "notice", level: "info", text: "已自动重发（原会话不可续聊）" });
+        void this.prompt(text);
+    }
+    /** 附件 → DSH contentBlocks（v1 简化：文本内联 / 路径引用 / 图片占位）。 */
+    /** dataUrl（data:image/png;base64,XXX）→ {mediaType, base64}；无前缀按 PNG 处理。 */
+    static splitImageDataUrl(data) {
+        const m = /^data:([^;,]+);base64,([\s\S]*)$/u.exec(data);
+        if (m && m[2])
+            return { mediaType: m[1] ?? "image/png", base64: m[2] };
+        return { mediaType: "image/png", base64: data };
+    }
+    async buildContentBlocks(text, attachments) {
+        const blocks = [{ type: "text", text }];
+        if (!Array.isArray(attachments))
+            return blocks;
+        for (const a of attachments) {
+            const resolved = a.path ? workspacePath(this.cwd, a.path) : null;
+            if (a.imageData) {
+                // 视觉桥：base64 图片 → attachment store → 真 image 块（模型可看图）。
+                try {
+                    const { mediaType, base64 } = DshClientSession.splitImageDataUrl(a.imageData);
+                    const saved = await this.runtime.attachmentSave(mediaType, base64, a.name);
+                    blocks.push({ type: "image", attachment: saved.ref });
+                }
+                catch (err) {
+                    blocks.push({ type: "text", text: `\n[图片附件: ${a.name ?? "image"}（保存失败 ${err.message}）]` });
+                }
+            }
+            else if (a.fileData) {
+                // 上传文件 → 落盘 + 路径引用。
+                try {
+                    const saved = saveUpload(this.clientId, a.name ?? "upload", Buffer.from(a.fileData, "base64"), this.dataDir);
+                    blocks.push({ type: "text", text: `\n[上传文件: ${saved.abs}]` });
+                }
+                catch (err) {
+                    blocks.push({ type: "text", text: `\n[上传文件: ${a.name ?? "upload"}（落盘失败 ${err.message}）]` });
+                }
+            }
+            else if (resolved) {
+                if (a.mode === "inline" || a.mode === undefined) {
+                    // 内联文本（小文件直接读内容）。
+                    try {
+                        const st = statSync(resolved.abs);
+                        if (st.size <= 512 * 1024) {
+                            const buf = readFileSync(resolved.abs);
+                            const kind = previewKind(resolved.abs);
+                            if (kind === "image") {
+                                // 工作区图片文件 → attachment store → 真 image 块。
+                                try {
+                                    const ext = (resolved.rel.match(/\.([a-z0-9]+)$/iu)?.[1] ?? "png").toLowerCase();
+                                    const mediaType = ext === "jpg" || ext === "jpeg"
+                                        ? "image/jpeg"
+                                        : ext === "webp"
+                                            ? "image/webp"
+                                            : ext === "gif"
+                                                ? "image/gif"
+                                                : "image/png";
+                                    const saved = await this.runtime.attachmentSave(mediaType, buf.toString("base64"), resolved.rel);
+                                    blocks.push({ type: "image", attachment: saved.ref });
+                                }
+                                catch {
+                                    blocks.push({ type: "text", text: `\n[图片附件: ${resolved.rel}]` });
+                                }
+                            }
+                            else {
+                                const enc = this.decodeText(buf);
+                                const capped = enc.length > 100_000 ? `${enc.slice(0, 100_000)}\n… [truncated]` : enc;
+                                blocks.push({
+                                    type: "text",
+                                    text: `\n<file path="${resolved.rel}">\n${capped}\n</file>`,
+                                });
+                            }
+                        }
+                        else {
+                            blocks.push({ type: "text", text: `\n[文件引用: ${resolved.rel}（大文件，请用读取工具查看）]` });
+                        }
+                    }
+                    catch {
+                        blocks.push({ type: "text", text: `\n[文件引用: ${resolved.rel}]` });
+                    }
+                }
+                else {
+                    blocks.push({ type: "text", text: `\n[文件引用: ${resolved.rel}]` });
+                }
+            }
+            else if (a.name) {
+                blocks.push({ type: "text", text: `\n[附件: ${a.name}]` });
+            }
+        }
+        return blocks;
+    }
+    decodeText(buf) {
+        try {
+            return new TextDecoder("utf-8", { fatal: true }).decode(buf);
+        }
+        catch {
+            try {
+                return new TextDecoder("gbk").decode(buf);
+            }
+            catch {
+                return buf.toString("latin1");
+            }
+        }
+    }
+    /** 中止：kill 运行时进程树（所有 conversation 的运行停止）→ 自动重启保持可用。 */
+    async abort() {
+        if (!this.runtime.alive)
+            return;
+        const conv = this.conv;
+        conv.isStreaming = false;
+        conv.streaming = null;
+        // 手动停止 → 清当前会话的 DSH 原生目标（半成品运行不该继续被轮次驱动）。
+        // 旧进程还活着，先 goal/clear 落盘，再重启运行时。
+        if (conv.dsGoal || conv.goal.goal) {
+            try {
+                await this.runtime.goalClear(conv.sessionId);
+            }
+            catch {
+                /* 进程可能已死，事件兜底 */
+            }
+            conv.dsGoal = null;
+            conv.goal.goal = null;
+            conv.goal.conversationId = null;
+            conv.goal.reviewing = false;
+            conv.goal.verdict = "pending";
+            conv.goal.feedback = undefined;
+            conv.goal.status = "已手动停止，目标已中止";
+            this.emitGoalStatus();
+        }
+        this.emit({ type: "notice", level: "info", text: "已停止（DSH 中止 = 重启运行时，进行中的其他对话也会停止）" });
+        try {
+            await this.runtime.restart(this.model);
+        }
+        catch (err) {
+            this.emit({ type: "notice", level: "error", text: `中止后重启失败：${err.message}` });
+        }
+        this.flushSnapshot(true);
+    }
+    async abortBash() {
+        // DSH 无 per-tool 取消；bash 工具由运行时管理，超时策略在运行时侧。
+        this.emit({ type: "notice", level: "info", text: "DSH 引擎暂不支持单独中止 bash（可整体停止对话）" });
+    }
+    // -----------------------------------------------------------------------
+    // 后台任务
+    // -----------------------------------------------------------------------
+    async listBgServers() {
+        await this.bg.listAndPush();
+    }
+    refreshBgTasks() {
+        this.bg.push();
+    }
+    async killBackgroundServer(port, taskId) {
+        if (taskId && this.pluginStopBgTask) {
+            const ok = this.pluginStopBgTask(taskId);
+            if (ok)
+                this.bg.push();
+            return ok;
+        }
+        if (port === undefined)
+            return false;
+        const killed = await this.bg.killOne(port);
+        if (killed)
+            this.bg.push();
+        return killed;
+    }
+    async killAllBackgroundServers() {
+        const killed = await this.bg.killAll();
+        this.bg.push();
+        return killed;
+    }
+    // -----------------------------------------------------------------------
+    // 会话列表 / 切换 / 删除
+    // -----------------------------------------------------------------------
+    sessionsTimer = null;
+    scheduleSessionsRefresh() {
+        if (this.sessionsTimer)
+            return;
+        this.sessionsTimer = setTimeout(() => {
+            this.sessionsTimer = null;
+            if (this.disposed)
+                return;
+            this.emitConversations();
+            void this.pushSessions();
+        }, 800);
+    }
+    async refreshSessions() {
+        await this.pushSessions();
+    }
+    async pushSessions() {
+        const files = findSessionFilesForCwd(this.sessionRoot, this.cwd);
+        const summaries = [];
+        for (const file of files) {
+            try {
+                const sessionId = basename(dirname(file));
+                // 审查会话（review-*）是内部工作会话，不进历史列表。
+                if (sessionId.startsWith("review-"))
+                    continue;
+                const { events } = readSessionLog(file);
+                summaries.push({
+                    path: file,
+                    name: sessionId,
+                    firstMessage: firstUserText(events),
+                    messageCount: events.filter((e) => e.type === "user/message" || e.type === "assistant/message" || e.type === "tool/result").length,
+                    modified: statSync(file).mtimeMs,
+                    source: "web",
+                });
+            }
+            catch {
+                /* skip unreadable */
+            }
+        }
+        this.emit({ type: "sessions", sessions: summaries });
+    }
+    async deleteSession(path) {
+        try {
+            const { rmSync } = await import("node:fs");
+            const abs = resolve(path);
+            if (!abs.startsWith(this.sessionRoot + sep)) {
+                this.emit({ type: "notice", level: "error", text: "拒绝删除会话目录之外的路径" });
+                return;
+            }
+            rmSync(abs, { recursive: true, force: true });
+            await this.pushSessions();
+            this.emit({ type: "notice", level: "info", text: "会话已删除" });
+        }
+        catch (err) {
+            this.emit({ type: "notice", level: "error", text: `删除失败：${err.message}` });
+        }
+    }
+    /** 切换会话：读 JSONL 回放 → 新建 conversation（同一 sessionId 续聊）。 */
+    async switchSession(path) {
+        try {
+            const abs = resolve(path);
+            const sessionId = basename(dirname(abs));
+            // 同一 sessionId 已在运行 → 直接切过去。
+            for (const conv of this.convs.values()) {
+                if (conv.sessionId === sessionId) {
+                    await this.switchConversation(conv.id);
+                    return;
+                }
+            }
+            const prev = this.conv;
+            prev.listed = prev.isStreaming || prev.terminals.list().length > 0 || prev.promptedSinceActive;
+            const conv = this.addConversation(sessionId, this.cwd, true);
+            conv.fromDisk = true; // 磁盘回放 → prompt 时 fork
+            this.activeId = conv.id;
+            this.emitConversations();
+            this.pushTerminals();
+            this.flushSnapshot(true);
+        }
+        catch (err) {
+            this.emit({ type: "notice", level: "error", text: `切换会话失败：${err.message}` });
+        }
+    }
+    // -----------------------------------------------------------------------
+    // 用户 patch 扩展缝（<dataDir>/dsh-patches/*.yml）
+    // -----------------------------------------------------------------------
+    /** 用户 patch 目录。 */
+    userPatchDir() {
+        return join(this.dataDir, "dsh-patches");
+    }
+    /** 列出 <dataDir>/dsh-patches/*.yml（按文件名序），带文件信息。 */
+    async listDshPatches() {
+        const dir = this.userPatchDir();
+        const files = [];
+        try {
+            const { readdirSync } = await import("node:fs");
+            for (const name of readdirSync(dir)) {
+                if (!/^\./u.test(name) && /\.ya?ml$/iu.test(name)) {
+                    try {
+                        const st = statSync(join(dir, name));
+                        if (st.isFile()) {
+                            files.push({ name, path: join(dir, name), size: st.size, mtimeMs: st.mtimeMs });
+                        }
+                    }
+                    catch {
+                        /* skip unreadable */
+                    }
+                }
+            }
+        }
+        catch {
+            /* 目录不存在 = 无用户 patch */
+        }
+        files.sort((a, b) => a.name.localeCompare(b.name));
+        this.emit({ type: "dsh_patches", patchDir: dir, files });
+    }
+    /** 重扫用户 patch：重启运行时使新 patch 生效（patch 只在 boot 时加载）。 */
+    async rescanDshPatches() {
+        try {
+            if (this.runtime.alive) {
+                await this.runtime.restart(this.model);
+            }
+            this.emit({ type: "notice", level: "info", text: "已重扫用户 patch 并重启运行时" });
+        }
+        catch (err) {
+            this.emit({ type: "notice", level: "error", text: `重扫用户 patch 失败：${err.message}` });
+        }
+        await this.listDshPatches();
+    }
+    // -----------------------------------------------------------------------
+    // 项目 / 文件 / SCM / 搜索
+    // -----------------------------------------------------------------------
+    async pushProjects() {
+        const saved = this.stateStore.get(this.clientId);
+        const projects = new Map();
+        for (const p of saved.projects ?? []) {
+            if (!(saved.removedProjects ?? []).includes(p.path)) {
+                projects.set(p.path, p.lastUsed);
+            }
+        }
+        // 合并当前会话目录发现的项目。
+        const cwdProjects = new Set();
+        try {
+            const { readdirSync } = await import("node:fs");
+            const entries = readdirSync(this.sessionRoot, { withFileTypes: true });
+            for (const e of entries) {
+                if (e.isDirectory()) {
+                    const cwd = this.decodeProjectKey(e.name);
+                    if (cwd && !projects.has(cwd))
+                        cwdProjects.add(cwd);
+                }
+            }
+        }
+        catch {
+            /* best effort */
+        }
+        for (const cwd of cwdProjects)
+            projects.set(cwd, Date.now());
+        projects.set(this.cwd, Date.now());
+        const list = [...projects.entries()]
+            .map(([path, lastUsed]) => ({ path, lastUsed }))
+            .sort((a, b) => b.lastUsed - a.lastUsed)
+            .slice(0, 30);
+        this.emit({ type: "projects", projects: list });
+    }
+    decodeProjectKey(key) {
+        // --<cwd>-- → 反解（尽力）。
+        if (!key.startsWith("--") || !key.endsWith("--"))
+            return null;
+        const inner = key.slice(2, -2);
+        let out = "";
+        for (let i = 0; i < inner.length; i++) {
+            if (inner[i] === "-") {
+                out += "/";
+            }
+            else if (inner[i] === "~" && i + 4 < inner.length) {
+                const hex = inner.slice(i + 1, i + 5);
+                if (/^[0-9A-Fa-f]{4}$/.test(hex)) {
+                    out += String.fromCharCode(parseInt(hex, 16));
+                    i += 4;
+                }
+                else {
+                    out += "~";
+                }
+            }
+            else {
+                out += inner[i];
+            }
+        }
+        return out || null;
+    }
+    async removeProject(path) {
+        this.stateStore.removeProject(this.clientId, path);
+        await this.pushProjects();
+    }
+    async listFiles(relPath) {
+        await this.files.listFiles(relPath);
+    }
+    async searchFiles(query, reqId) {
+        await this.files.searchFiles(query, reqId);
+    }
+    async searchSessions(query, reqId) {
+        const q = query.trim().toLowerCase();
+        if (!q) {
+            this.emit({ type: "session_search_results", reqId, query, ok: true, results: [] });
+            return;
+        }
+        try {
+            const { readFileSync: readSessionFile } = await import("node:fs");
+            const files = findSessionFilesForCwd(this.sessionRoot, this.cwd);
+            const results = [];
+            for (const file of files) {
+                try {
+                    const { events } = readSessionLog(file);
+                    const texts = [];
+                    const anchors = [];
+                    for (const ev of events) {
+                        // P1-14：索引范围 = user/assistant 文本 + tool-result 工具输出。
+                        if (ev.type === "user/message" || ev.type === "assistant/message" || ev.type === "tool/result") {
+                            const blocks = ev.data?.message?.content ??
+                                ev.data?.content ??
+                                [];
+                            let text = blocks
+                                .map((b) => (b?.type === "text" ? b.text ?? "" : ""))
+                                .join("\n");
+                            if (ev.type === "tool/result") {
+                                // 工具输出在嵌套 content[]（tool-result 块内），一并纳入索引。
+                                const nested = blocks
+                                    .filter((b) => b?.type === "tool-result")
+                                    .flatMap((b) => b.content ?? [])
+                                    .map((b) => (b?.type === "text" ? b.text ?? "" : ""))
+                                    .join("\n");
+                                if (nested)
+                                    text = `${text}\n${nested}`;
+                            }
+                            if (text) {
+                                texts.push(text);
+                                if (text.toLowerCase().includes(q)) {
+                                    const evData = ev.data;
+                                    const role = evData?.message?.role === "assistant" ? "assistant" : "user";
+                                    anchors.push({ role, timestamp: ev.time });
+                                }
+                            }
+                        }
+                    }
+                    const all = texts.join("\n").toLowerCase();
+                    const sessionId = basename(dirname(file));
+                    // 审查会话不进搜索。
+                    if (sessionId.startsWith("review-"))
+                        continue;
+                    if (all.includes(q) ||
+                        sessionId.toLowerCase().includes(q) ||
+                        firstUserText(events).toLowerCase().includes(q)) {
+                        results.push({
+                            path: file,
+                            name: sessionId,
+                            firstMessage: firstUserText(events),
+                            messageCount: events.filter((e) => e.type === "user/message" || e.type === "assistant/message" || e.type === "tool/result").length,
+                            modified: statSync(file).mtimeMs,
+                            source: "web",
+                            anchors: anchors.slice(0, 10),
+                        });
+                    }
+                }
+                catch {
+                    /* skip unreadable */
+                }
+            }
+            results.sort((a, b) => b.modified - a.modified);
+            this.emit({ type: "session_search_results", reqId, query, ok: true, results: results.slice(0, 50) });
+        }
+        catch {
+            this.emit({ type: "session_search_results", reqId, query, ok: false, results: [] });
+        }
+    }
+    async scmQuery(kind, reqId, opts) {
+        // 走 FilesService：只读 git 查询 + git-dir watcher（外部提交 → scm_changed
+        // 面板自动刷新）+ 越界/notRepo 统一处理。
+        await this.files.scmQuery(kind, reqId, opts);
+    }
+    async readFile(relPath) {
+        await this.files.readFile(relPath);
+    }
+    async writeFile(relPath, text) {
+        await this.files.writeFile(relPath, text);
+    }
+    async uploadFile(dirRel, name, data) {
+        await this.files.uploadFile(dirRel, name, data);
+    }
+    async completePath(input) {
+        await this.files.completePath(input);
+    }
+    // -----------------------------------------------------------------------
+    // 模型 / 思考
+    // -----------------------------------------------------------------------
+    /** P2-17 动态模型 id 缓存（adapter 目录查询结果；setModel 校验用）。 */
+    dynamicModels = new Set();
+    async listModels() {
+        // 以本地表为底（定价/上下文窗口/vision 标记），运行时 adapter 目录动态
+        // 扩展——新模型自动出现在选择器，无需改代码。
+        const known = new Map(DSH_MODELS.map((m) => [m.id, m]));
+        let dynamic = [];
+        try {
+            const res = await this.runtime.listModels();
+            dynamic = res.models ?? [];
+        }
+        catch {
+            /* 运行时不可用 → 只发本地表 */
+        }
+        const seen = new Set();
+        const models = [];
+        this.dynamicModels.clear();
+        for (const m of dynamic) {
+            if (seen.has(m.id))
+                continue;
+            seen.add(m.id);
+            const local = known.get(m.id);
+            const vision = local?.vision ??
+                (m.inputModalities?.includes("image") ?? false);
+            if (!local)
+                this.dynamicModels.add(m.id);
+            models.push({
+                id: m.id,
+                name: local?.name ?? m.name ?? m.id,
+                provider: "deepseek",
+                reasoning: true,
+                vision,
+            });
+        }
+        for (const m of DSH_MODELS) {
+            if (seen.has(m.id))
+                continue;
+            seen.add(m.id);
+            models.push({
+                id: m.id,
+                name: m.name,
+                provider: m.provider,
+                reasoning: true,
+                vision: m.vision,
+            });
+        }
+        this.emit({ type: "models", models });
+    }
+    /** 换模型 = 重启运行时。 */
+    async setModel(modelId) {
+        // 校验：本地表 + 运行时动态目录（P2-17）。
+        const known = DSH_MODELS.some((m) => m.id === modelId) || this.dynamicModels.has(modelId);
+        if (!known) {
+            this.emit({ type: "notice", level: "warning", text: `未知模型：${modelId}` });
+            return;
+        }
+        if (modelId === this.model)
+            return;
+        // P0-2 竞态告知：换模型 = 强杀运行时 → 进行中的 run 全部中止。
+        if ([...this.convs.values()].some((c) => c.isStreaming)) {
+            this.emit({
+                type: "notice",
+                level: "warning",
+                text: "有对话正在运行，切换模型将中止当前所有运行（DSH 换模型 = 重启运行时）",
+            });
+        }
+        this.model = modelId;
+        try {
+            await this.runtime.restart(modelId);
+            this.emit({ type: "notice", level: "info", text: `已切换到 ${modelId}` });
+        }
+        catch (err) {
+            this.emit({ type: "notice", level: "error", text: `切换模型失败：${err.message}` });
+        }
+        this.flushSnapshot(true);
+    }
+    async cycleModel() {
+        const idx = DSH_MODELS.findIndex((m) => m.id === this.model);
+        const next = DSH_MODELS[(idx + 1) % DSH_MODELS.length];
+        await this.setModel(next.id);
+    }
+    setThinking(level) {
+        if (level !== "high") {
+            this.emit({ type: "notice", level: "info", text: "DeepSeek V4 仅支持高思考强度" });
+            return;
+        }
+        this.thinkingLevel = level;
+        this.flushSnapshot();
+    }
+    cycleThinking() {
+        // DSH 固定 high。
+        this.emit({ type: "notice", level: "info", text: "DeepSeek V4 仅支持高思考强度" });
+    }
+    // -----------------------------------------------------------------------
+    // 设置 / 系统提示词
+    // -----------------------------------------------------------------------
+    pushSettings() {
+        const settings = {
+            promptMode: this.settings.promptMode,
+            customSystemPrompt: this.settings.customSystemPrompt,
+            disabledSkills: this.settings.disabledSkills,
+            disabledExtensions: this.settings.disabledExtensions,
+            terminalToolsEnabled: this.settings.terminalToolsEnabled,
+            terminalBash: this.settings.terminalBash,
+            terminalBashIdleMs: this.settings.terminalBashIdleMs,
+            thinkingWrap: this.settings.thinkingWrap,
+            toolsWrap: this.settings.toolsWrap,
+            visionBridgeEnabled: false,
+            visionBridgeModel: null,
+            visionBridgePromptMode: "append",
+            visionBridgePrompt: "",
+            reviewPrompt: this.settings.reviewPrompt,
+            reviewDisabledSkills: [],
+            disabledPlugins: this.settings.disabledPlugins,
+            defaultSystemPrompt: "",
+            effectiveSystemPrompt: this.settings.customSystemPrompt,
+            visionBridgeDefaultPrompt: "",
+            visionModels: [],
+            skills: this.skillsCache,
+            reviewSkills: [],
+            extensions: [],
+            presets: this.stateStore.getPresets(this.clientId),
+        };
+        this.emit({ type: "settings_state", settings });
+    }
+    async setSettings(partial) {
+        if (partial.promptMode !== undefined)
+            this.settings.promptMode = partial.promptMode;
+        if (partial.customSystemPrompt !== undefined)
+            this.settings.customSystemPrompt = partial.customSystemPrompt;
+        if (partial.disabledSkills !== undefined)
+            this.settings.disabledSkills = partial.disabledSkills;
+        if (partial.disabledExtensions !== undefined)
+            this.settings.disabledExtensions = partial.disabledExtensions;
+        if (partial.terminalToolsEnabled !== undefined)
+            this.settings.terminalToolsEnabled = partial.terminalToolsEnabled;
+        if (partial.terminalBash !== undefined)
+            this.settings.terminalBash = partial.terminalBash;
+        if (partial.terminalBashIdleMs !== undefined)
+            this.settings.terminalBashIdleMs = partial.terminalBashIdleMs;
+        if (partial.thinkingWrap !== undefined)
+            this.settings.thinkingWrap = partial.thinkingWrap;
+        if (partial.toolsWrap !== undefined)
+            this.settings.toolsWrap = partial.toolsWrap;
+        if (partial.disabledPlugins !== undefined)
+            this.settings.disabledPlugins = partial.disabledPlugins;
+        if (partial.reviewPrompt !== undefined)
+            this.settings.reviewPrompt = partial.reviewPrompt;
+        // 持久化（跨重连存活）。
+        this.stateStore.saveSettings(this.clientId, {
+            promptMode: this.settings.promptMode,
+            customSystemPrompt: this.settings.customSystemPrompt,
+            disabledSkills: this.settings.disabledSkills,
+            disabledExtensions: this.settings.disabledExtensions,
+            terminalToolsEnabled: this.settings.terminalToolsEnabled,
+            terminalBash: this.settings.terminalBash,
+            terminalBashIdleMs: this.settings.terminalBashIdleMs,
+            thinkingWrap: this.settings.thinkingWrap,
+            toolsWrap: this.settings.toolsWrap,
+            disabledPlugins: this.settings.disabledPlugins,
+            reviewPrompt: this.settings.reviewPrompt,
+        });
+        // 仅系统提示词变化才重启运行时（DSH_PERSONA 由 launcher env 注入）；
+        // 其他设置（开关/隐藏插件等）只存不回写运行时。
+        const personaChanged = partial.promptMode !== undefined || partial.customSystemPrompt !== undefined;
+        if (personaChanged)
+            await this.applyPersona();
+        // 技能启停（#18）：禁用集变化 → 同步运行时（晚 pre-step 钩子过滤目录）并刷新技能列表。
+        if (partial.disabledSkills !== undefined) {
+            void this.pushDisabledSkillsToRuntime();
+            void this.refreshSkillsFromRuntime();
+        }
+        this.pushSettings();
+        this.flushSnapshot();
+    }
+    applyPersona() {
+        const custom = this.settings.customSystemPrompt.trim();
+        const persona = this.settings.promptMode === "replace" && custom
+            ? custom
+            : this.settings.promptMode === "append" && custom
+                ? `\n\n${custom}`
+                : "";
+        this.runtime.env = { ...this.runtime.env, DSH_PERSONA: persona };
+        if (this.runtime.alive) {
+            return this.runtime.restart(this.model).catch(() => {
+                /* keep old runtime */
+            });
+        }
+        return Promise.resolve();
+    }
+    async reloadExtensions() {
+        // DSH 引擎无 pi 扩展体系。
+        this.emit({ type: "notice", level: "info", text: "DSH 引擎不支持 pi 扩展热重载" });
+    }
+    async savePreset(name) {
+        const presets = this.stateStore.getPresets(this.clientId);
+        const existing = presets.find((p) => p.name === name);
+        const preset = {
+            name,
+            promptMode: this.settings.promptMode,
+            customSystemPrompt: this.settings.customSystemPrompt,
+            disabledSkills: this.settings.disabledSkills,
+            disabledExtensions: this.settings.disabledExtensions,
+            terminalToolsEnabled: this.settings.terminalToolsEnabled,
+            terminalBash: this.settings.terminalBash,
+            terminalBashIdleMs: this.settings.terminalBashIdleMs,
+            visionBridgePromptMode: "append",
+            visionBridgePrompt: "",
+            reviewPrompt: this.settings.reviewPrompt,
+            reviewDisabledSkills: [],
+        };
+        this.stateStore.savePresets(this.clientId, existing ? presets.map((p) => (p.name === name ? preset : p)) : [...presets, preset]);
+        this.emit({ type: "notice", level: "info", text: `预设「${name}」已保存` });
+        this.pushSettings();
+    }
+    async applyPreset(name) {
+        const preset = this.stateStore.getPresets(this.clientId).find((p) => p.name === name);
+        if (!preset) {
+            this.emit({ type: "notice", level: "warning", text: `预设「${name}」不存在` });
+            return;
+        }
+        this.settings.promptMode = preset.promptMode;
+        this.settings.customSystemPrompt = preset.customSystemPrompt;
+        this.settings.disabledSkills = preset.disabledSkills ?? [];
+        this.settings.disabledExtensions = preset.disabledExtensions ?? [];
+        this.settings.terminalToolsEnabled = preset.terminalToolsEnabled;
+        this.settings.terminalBash = preset.terminalBash;
+        this.settings.terminalBashIdleMs = preset.terminalBashIdleMs;
+        this.settings.reviewPrompt = preset.reviewPrompt ?? "";
+        this.stateStore.saveSettings(this.clientId, {
+            promptMode: this.settings.promptMode,
+            customSystemPrompt: this.settings.customSystemPrompt,
+            disabledSkills: this.settings.disabledSkills,
+            disabledExtensions: this.settings.disabledExtensions,
+            terminalToolsEnabled: this.settings.terminalToolsEnabled,
+            terminalBash: this.settings.terminalBash,
+            terminalBashIdleMs: this.settings.terminalBashIdleMs,
+            thinkingWrap: this.settings.thinkingWrap,
+            toolsWrap: this.settings.toolsWrap,
+            disabledPlugins: this.settings.disabledPlugins,
+            reviewPrompt: this.settings.reviewPrompt,
+        });
+        await this.applyPersona();
+        this.pushSettings();
+        this.flushSnapshot();
+    }
+    async deletePreset(name) {
+        const presets = this.stateStore.getPresets(this.clientId);
+        this.stateStore.savePresets(this.clientId, presets.filter((p) => p.name !== name));
+        this.pushSettings();
+    }
+    // -----------------------------------------------------------------------
+    // 目标（DSH 原生 goal 域：goal/change 事件驱动，round-driver 自动轮次）
+    // -----------------------------------------------------------------------
+    emitGoalStatus() {
+        this.emit({ type: "goal_status", status: { ...this.conv.goal } });
+    }
+    /**
+     * goal/change 事件（DSH 原生状态机全量快照）→ 镜像到当前 conversation。
+     * 权威源在运行时：create/edit/resume → active；complete → pass；block → fail。
+     */
+    applyGoalChange(conv, data) {
+        const g = conv.goal;
+        if (data.operation === "clear" || (!data.goal && data.cleared)) {
+            conv.dsGoal = null;
+            g.goal = null;
+            g.conversationId = null;
+            g.reviewing = false;
+            g.verdict = "pending";
+            g.feedback = undefined;
+            g.status = "";
+        }
+        else if (data.goal?.objective) {
+            conv.dsGoal = {
+                id: data.goal.id ?? "",
+                revision: data.goal.revision ?? 0,
+                phase: data.goal.phase ?? "active",
+                objective: data.goal.objective,
+                maxGoalRounds: data.goal.maxGoalRounds ?? 0,
+                roundsStarted: data.roundsStarted ?? 0,
+                ...(data.goal.blockedReason ? { blockedReason: data.goal.blockedReason } : {}),
+            };
+            g.goal = data.goal.objective;
+            g.conversationId = conv.id;
+            g.round = data.roundsStarted ?? 0;
+            if (data.goal.maxGoalRounds)
+                g.maxRounds = data.goal.maxGoalRounds;
+            const phase = data.goal.phase ?? "active";
+            if (phase === "active") {
+                g.reviewing = true;
+                g.verdict = "pending";
+                g.feedback = undefined;
+                // P1-10：轮次已达上限且仍未完成 → 提示轮尽（模型可能正在跑最后一轮，
+                // 后续 complete/blocked 事件会覆盖此状态）。
+                const rounds = g.round ?? 0;
+                const max = data.goal.maxGoalRounds ?? g.maxRounds ?? 0;
+                g.status =
+                    max > 0 && rounds >= max
+                        ? `已达轮数上限（${rounds}/${max}），目标未完成`
+                        : `目标进行中（第 ${rounds + 1} 轮）…`;
+            }
+            else if (phase === "complete") {
+                g.reviewing = false;
+                g.verdict = "pass";
+                g.status = "✅ 目标已达成";
+            }
+            else if (phase === "blocked") {
+                g.reviewing = false;
+                g.verdict = "fail";
+                g.feedback = data.goal.blockedReason ?? "（模型报告受阻）";
+                g.status = "目标受阻";
+            }
+            else if (phase === "paused") {
+                g.reviewing = false;
+                g.verdict = "pending";
+                g.status = "目标已暂停";
+            }
+            else {
+                g.reviewing = false;
+            }
+        }
+        if (conv.id === this.activeId) {
+            this.emitGoalStatus();
+            this.flushSnapshot();
+        }
+    }
+    async setGoal(goal, opts) {
+        if (goal.trim() === "") {
+            await this.clearGoal();
+            return;
+        }
+        if (this.quiesceBlocked())
+            return;
+        const conv = this.conv;
+        const text = goal.trim();
+        const g = conv.goal;
+        g.goal = text;
+        g.conversationId = conv.id;
+        g.reviewModel = opts?.reviewModel ?? g.reviewModel;
+        g.maxRounds = opts?.maxRounds ?? g.maxRounds;
+        g.locked = opts?.locked ?? g.locked;
+        // P1-11：DSH 无独立审查者，locked 映射为轮次语义 ——
+        //   locked=true（目标锁定，必须达成）→ 保留用户轮次上限；
+        //   locked=false（不锁定）→ 单轮语义近似（maxGoalRounds=1，一轮后结束）。
+        const effectiveMax = g.locked ? g.maxRounds : 1;
+        g.round = 0;
+        g.reviewing = true; // round-driver 会立刻续第一轮
+        g.verdict = "pending";
+        g.feedback = undefined;
+        g.status = "目标已设，等待生成…";
+        this.goalPrefs = { reviewModel: g.reviewModel, maxRounds: g.maxRounds, locked: g.locked };
+        this.stateStore.saveGoalPrefs(this.clientId, {
+            reviewModel: g.reviewModel,
+            maxRounds: g.maxRounds,
+            locked: g.locked,
+        });
+        this.emitGoalStatus();
+        this.emit({ type: "notice", level: "info", text: `🎯 已设目标：${text.slice(0, 80)}${text.length > 80 ? "…" : ""}` });
+        try {
+            // goal/set 创建 + arm；round-driver 在 agent idle 时自动续轮，无需额外 prompt。
+            const res = (await this.runtime.goalSet(conv.sessionId, text, effectiveMax > 0 ? effectiveMax : undefined));
+            if (res?.goal?.maxGoalRounds)
+                g.maxRounds = res.goal.maxGoalRounds;
+        }
+        catch (err) {
+            g.reviewing = false;
+            g.status = `目标设置失败：${err.message}`;
+            this.emit({ type: "notice", level: "error", text: `目标设置失败：${err.message}` });
+        }
+        this.emitGoalStatus();
+        this.flushSnapshot();
+    }
+    async clearGoal() {
+        const conv = this.conv;
+        // 向导进行中 → 中断等待（模型侧提问会因超时/无 provider 恢复）。
+        if (conv.turnWaiter) {
+            const w = conv.turnWaiter;
+            conv.turnWaiter = undefined;
+            w.reject(new Error("调研已取消"));
+        }
+        if (conv.dsGoal) {
+            try {
+                await this.runtime.goalClear(conv.sessionId);
+            }
+            catch {
+                /* goal/change clear 事件会回来兜底 */
+            }
+        }
+        conv.dsGoal = null;
+        const g = conv.goal;
+        g.goal = null;
+        g.conversationId = null;
+        g.reviewing = false;
+        g.verdict = "pending";
+        g.feedback = undefined;
+        g.status = "";
+        this.emitGoalStatus();
+        this.flushSnapshot();
+    }
+    async startGoalWizard(text, opts) {
+        // 交互式调研向导：主会话 prompt 向导指令 → 模型用 ask_user_question 逐题
+        // 提问（经提问桥 → 浏览器对话框）→ 收敛输出 GOAL: 行 → 自动设目标。
+        if (this.quiesceBlocked())
+            return;
+        const conv = this.conv;
+        const draft = (text ?? "").trim();
+        if (!draft)
+            return;
+        const g = conv.goal;
+        if (g.goal || g.reviewing || g.wizard.active) {
+            this.emit({ type: "notice", level: "warning", text: "已有目标或调研进行中，请先完成或清除" });
+            return;
+        }
+        g.wizard.active = true;
+        g.wizard.draft = draft;
+        g.wizard.model = opts?.wizardModel ?? null;
+        g.wizard.step = 0;
+        g.wizard.maxSteps = 6;
+        g.wizard.status = "调研中…";
+        g.status = "目标调研中…";
+        this.emitGoalStatus();
+        this.emit({
+            type: "notice",
+            level: "info",
+            text: `🔍 正在围绕需求展开调研：${draft.slice(0, 60)}${draft.length > 60 ? "…" : ""}`,
+        });
+        try {
+            const waiter = new Promise((resolve, reject) => {
+                const timer = setTimeout(() => reject(new Error("调研超时（10 分钟）")), 10 * 60_000);
+                timer.unref?.();
+                conv.turnWaiter = {
+                    resolve: () => {
+                        clearTimeout(timer);
+                        resolve();
+                    },
+                    reject: (err) => {
+                        clearTimeout(timer);
+                        reject(err);
+                    },
+                };
+            });
+            await this.promptConv(conv, this.wizardPrompt(draft));
+            await waiter;
+        }
+        catch (err) {
+            this.emit({ type: "notice", level: "warning", text: `目标调研中断：${err.message}` });
+        }
+        conv.turnWaiter = undefined;
+        g.wizard.active = false;
+        g.wizard.step = 0;
+        g.wizard.status = "";
+        // 解析模型最终输出中的 GOAL: 行。
+        const finalText = this.lastAssistantText(conv);
+        const goalMatch = finalText.match(/GOAL\s*[:：]\s*([\s\S]*)/i);
+        let refined = goalMatch ? goalMatch[1].trim() : "";
+        if (!refined) {
+            // 未按格式：取最后一段非空文本（截断防污染）。
+            refined = finalText.split("\n").filter((l) => l.trim()).pop()?.trim() ?? "";
+            if (refined.length > 300)
+                refined = refined.slice(0, 300);
+        }
+        if (!refined && g.goal) {
+            // 模型可能直接用了 create_goal —— 目标已在运行时，镜像它即可。
+            this.emitGoalStatus();
+            this.emit({ type: "notice", level: "info", text: "🎯 调研完成，目标已由模型创建" });
+            return;
+        }
+        this.emitGoalStatus();
+        if (refined) {
+            await this.setGoal(refined, {
+                reviewModel: opts?.wizardModel,
+                maxRounds: opts?.maxRounds,
+                locked: opts?.locked,
+            });
+            this.emit({
+                type: "notice",
+                level: "info",
+                text: `🎯 调研完成，目标已设为：${refined.slice(0, 80)}${refined.length > 80 ? "…" : ""}`,
+            });
+        }
+        else {
+            this.emit({ type: "notice", level: "warning", text: "调研未产出有效目标，请重试" });
+        }
+    }
+    /** 调研向导指令（主会话 prompt）：先提问收敛，最后只输出 GOAL: 行。 */
+    wizardPrompt(draft) {
+        return [
+            `You are a goal-clarification wizard. The user stated a raw requirement. Your job is to turn it into ONE precise, actionable goal that a coding agent can fully satisfy.`,
+            ``,
+            `# User's raw requirement`,
+            draft,
+            ``,
+            `Use the ask_user_question tool to ask the user focused questions to pin down the essential, ambiguous details. Ask ONE question at a time, usually 2 to 4 questions total: what exactly to build/do, scope boundaries (what NOT to do), acceptance criteria / done-definition, and any constraints (style, performance, environment). Prefer multiple-choice questions (options) when you can offer clear choices.`,
+            `Once you have enough to write an unambiguous, reviewable goal, STOP asking and reply with EXACTLY this format and nothing else (no preamble, no bullets):`,
+            `GOAL: <one concrete, verifiable sentence describing the deliverable and its acceptance criteria>`,
+            `Do NOT call create_goal or update_goal — just output the GOAL: line. If the user cancels or stops answering, still produce a sensible best-effort GOAL from what you already know.`,
+        ].join("\n");
+    }
+    /** 会话最后一条 assistant 文本（向导/调试提取用）。 */
+    lastAssistantText(conv) {
+        for (let i = conv.messages.length - 1; i >= 0; i--) {
+            const m = conv.messages[i];
+            if (m.role === "assistant") {
+                return m.content.map((c) => ("text" in c ? c.text : "")).join("");
+            }
+        }
+        return "";
+    }
+    async setGoalPrefs(opts) {
+        const g = this.conv.goal;
+        if (opts?.reviewModel !== undefined)
+            g.reviewModel = opts.reviewModel;
+        if (opts?.maxRounds !== undefined)
+            g.maxRounds = opts.maxRounds;
+        if (opts?.locked !== undefined)
+            g.locked = opts.locked;
+        this.goalPrefs = { reviewModel: g.reviewModel, maxRounds: g.maxRounds, locked: g.locked };
+        this.stateStore.saveGoalPrefs(this.clientId, {
+            reviewModel: g.reviewModel,
+            maxRounds: g.maxRounds,
+            locked: g.locked,
+        });
+        this.emitGoalStatus();
+    }
+    // -----------------------------------------------------------------------
+    // 命令列表（.pi/commands.json → DSH 无命令体系，简化为空/透传存储）
+    // -----------------------------------------------------------------------
+    async listCommands() {
+        const { commands, path } = await loadCommands(this.cwd);
+        this.emit({ type: "commands", commands, path });
+    }
+    async saveCommands(commands) {
+        const { path, error } = await saveCommandsFile(this.cwd, commands);
+        if (error) {
+            this.emit({ type: "notice", level: "error", text: `保存命令失败：${error}` });
+        }
+        else {
+            this.emit({ type: "notice", level: "info", text: `命令已保存（${path}）` });
+        }
+    }
+    // -----------------------------------------------------------------------
+    // 斜杠命令（内置 NATIVE + 插件 registerCommand；DSH 无扩展/技能/模板体系）
+    // -----------------------------------------------------------------------
+    async pushSlashCommands() {
+        const commands = [];
+        const seen = new Set();
+        for (const c of NATIVE_COMMANDS) {
+            commands.push({ ...c, source: "builtin" });
+            seen.add(c.name);
+        }
+        for (const cmd of this.pluginCommandsProvider?.() ?? []) {
+            if (seen.has(cmd.name))
+                continue;
+            commands.push({
+                name: cmd.name,
+                description: cmd.description,
+                descriptionEn: cmd.descriptionEn,
+                argumentHint: cmd.argumentHint,
+                argumentHintEn: cmd.argumentHintEn,
+                source: "plugin",
+            });
+            seen.add(cmd.name);
+        }
+        this.emit({ type: "slash_commands", commands });
+    }
+    /** 拦截执行斜杠命令；返回 true 表示已处理（不发给模型）。 */
+    async execSlash(name, args) {
+        switch (name) {
+            case "new":
+                await this.newChat();
+                return true;
+            case "model": {
+                if (!args.trim()) {
+                    this.emit({ type: "notice", level: "info", text: `当前模型：${this.model}。用法：/model <名称>` });
+                    return true;
+                }
+                const q = args.trim().toLowerCase();
+                const all = [...DSH_MODELS, ...[...this.dynamicModels].map((id) => ({ id, name: id }))];
+                const hit = all.find((m) => m.id === q || m.name?.toLowerCase().includes(q));
+                if (hit) {
+                    await this.setModel(hit.id);
+                }
+                else {
+                    this.emit({
+                        type: "notice",
+                        level: "error",
+                        text: `没有匹配到模型：${args.trim()}（可用模型见顶栏模型列表）`,
+                    });
+                }
+                return true;
+            }
+            case "cwd": {
+                if (!args.trim()) {
+                    this.emit({ type: "notice", level: "info", text: `当前工作目录：${this.cwd}` });
+                    return true;
+                }
+                await this.setCwd(args.trim());
+                return true;
+            }
+            case "resume":
+                await this.refreshSessions();
+                return true;
+            case "help":
+                return true; // 前端 /help modal 展示目录
+            case "copy":
+                return true; // 前端本地实现
+            case "reload":
+                this.emit({ type: "notice", level: "info", text: "已重新加载（DSH 引擎无扩展/技能热重载，运行时能力内置）" });
+                await this.pushSlashCommands();
+                return true;
+            case "compact":
+                this.emit({ type: "notice", level: "info", text: "DSH 引擎不支持上下文压缩（运行时自动管理）" });
+                return true;
+            case "thinking":
+                this.emit({ type: "notice", level: "info", text: "DeepSeek V4 仅支持高思考强度" });
+                return true;
+            case "pi-web-ui:quit":
+                this.onQuit?.();
+                return true;
+        }
+        // 插件命令（host.registerCommand）
+        const def = this.pluginCommandsProvider?.().find((c) => c.name === name);
+        if (def) {
+            try {
+                const result = await def.run(args, { clientId: this.clientId });
+                if (typeof result === "string" && result.trim()) {
+                    this.emit({ type: "notice", level: "info", text: result });
+                }
+            }
+            catch (err) {
+                this.emit({
+                    type: "notice",
+                    level: "error",
+                    text: `插件命令 /${name} 执行失败：${err.message}`,
+                });
+            }
+            return true;
+        }
+        return false;
+    }
+    // -----------------------------------------------------------------------
+    // 自更新
+    // -----------------------------------------------------------------------
+    static currentAppVersion() {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dirname(new URL(import.meta.url).pathname), "..", "package.json"), "utf8"));
+            return pkg.version ?? "0.0.0";
+        }
+        catch {
+            return "0.0.0";
+        }
+    }
+    async checkUpdate() {
+        try {
+            const latest = await checkAllUpdates([{ name: "pi-web-ui", version: DshClientSession.currentAppVersion(), kind: "webui" }]);
+            const item = latest[0];
+            this.emit({
+                type: "update_status",
+                current: item.current,
+                latest: item.latest,
+                latestPublishedAt: item.latestPublishedAt ?? null,
+                upToDate: item.upToDate,
+                error: item.error,
+            });
+        }
+        catch (err) {
+            this.emit({ type: "update_status", current: DshClientSession.currentAppVersion(), latest: null, latestPublishedAt: null, upToDate: true, error: err.message });
+        }
+    }
+    async checkUpdatesAll(force = false) {
+        try {
+            const targets = collectTargets(join(homedir(), ".pi", "agent"), DshClientSession.currentAppVersion());
+            const items = await checkAllUpdates(targets);
+            if (force) {
+                // 强制模式：忽略缓存（默认 Fetcher 带 TTL，直接再查一次即可）。
+                void items;
+            }
+            this.emit({
+                type: "update_status_all",
+                items: items.map((i) => ({
+                    name: i.name,
+                    kind: i.kind,
+                    current: i.current,
+                    latest: i.latest,
+                    latestPublishedAt: i.latestPublishedAt ?? null,
+                    upToDate: i.upToDate,
+                    error: i.error,
+                })),
+            });
+        }
+        catch (err) {
+            this.emit({ type: "update_status_all", items: [] });
+        }
+    }
+    // -----------------------------------------------------------------------
+    // pi 专属：DSH 引擎下的简化实现
+    // -----------------------------------------------------------------------
+    async installPiAgent() {
+        this.emit({ type: "install_result", ok: true, detail: "DSH 引擎不需要 pi CLI" });
+    }
+    async setProviderApiKey(provider, apiKey) {
+        const key = apiKey.trim();
+        if (!key) {
+            this.emit({ type: "notice", level: "error", text: "请填写 API 密钥" });
+            return;
+        }
+        try {
+            // 与 pi 引擎同形状：{ <provider>: { type: "api_key", key } }。
+            const authPath = join(this.agentDir, "auth.json");
+            let auth = {};
+            try {
+                auth = JSON.parse(readFileSync(authPath, "utf8"));
+            }
+            catch {
+                /* new file */
+            }
+            auth[provider.trim()] = { type: "api_key", key };
+            mkdirSync(dirname(authPath), { recursive: true });
+            writeFileSync(authPath, JSON.stringify(auth, null, 2) + "\n");
+            this.emit({ type: "notice", level: "info", text: `✅ 已保存 ${provider.trim()} 的 API 密钥` });
+            if (this.runtime.alive)
+                await this.runtime.restart(this.model);
+            this.flushSnapshot();
+        }
+        catch (err) {
+            this.emit({ type: "notice", level: "error", text: `保存 key 失败：${err.message}` });
+        }
+    }
+    async clearProviderApiKey(provider) {
+        const pid = provider.trim();
+        try {
+            const authPath = join(this.agentDir, "auth.json");
+            const auth = JSON.parse(readFileSync(authPath, "utf8"));
+            if (!(pid in auth)) {
+                this.emit({ type: "notice", level: "info", text: `${pid} 没有已保存的密钥` });
+                return;
+            }
+            delete auth[pid];
+            writeFileSync(authPath, JSON.stringify(auth, null, 2) + "\n");
+            this.emit({ type: "notice", level: "info", text: `🗑  已清除 ${pid} 的密钥，该服务商回到未配置状态` });
+            if (this.runtime.alive && pid === "deepseek")
+                await this.runtime.restart(this.model);
+            this.flushSnapshot();
+        }
+        catch (err) {
+            this.emit({ type: "notice", level: "error", text: `清除失败：${err.message}` });
+        }
+    }
+    async listModelsConfig() {
+        this.emit({ type: "models_config", providers: [] });
+    }
+    async saveModelConfig(providerId, config) {
+        this.emit({ type: "notice", level: "warning", text: "DSH 引擎使用内置 DeepSeek 模型，不支持自定义模型配置" });
+    }
+    async deleteModelConfig(providerId) {
+        this.emit({ type: "notice", level: "warning", text: "DSH 引擎不支持自定义模型配置" });
+    }
+    async listProviders() {
+        this.emit({
+            type: "providers_status",
+            providers: [
+                {
+                    id: "deepseek-official",
+                    name: "DeepSeek 官方",
+                    configured: !!loadDeepSeekKey(),
+                    source: loadDeepSeekKey() ? "stored" : undefined,
+                },
+            ],
+        });
+    }
+    async fetchModelsList(reqId, baseUrl, apiKey, authHeader, api) {
+        this.emit({ type: "fetch_models_result", reqId, ok: false, error: "DSH 引擎不支持自定义 provider 探测" });
+    }
+    async refreshProviderModels(providerId, reqId) {
+        this.emit({ type: "refresh_provider_result", reqId, ok: false, error: "DSH 引擎不支持自定义 provider" });
+    }
+    async cloneProvider(provider, reqId) {
+        this.emit({ type: "clone_provider_result", reqId, ok: false, error: "DSH 引擎不支持自定义 provider" });
+    }
+    // -----------------------------------------------------------------------
+    // 其他
+    // -----------------------------------------------------------------------
+    resolveDialog(id, value) {
+        // DSH 引擎无扩展 UI 桥（dialog 由插件宿主走，v1 忽略）。
+    }
+    async editMessage(messageId, text, attachments) {
+        // DSH 会话是 append-only 事件日志：编辑重问 = 新建会话 fork + 回放旧消息。
+        try {
+            const conv = this.conv;
+            const idx = conv.messages.findIndex((m) => m.id === messageId);
+            if (idx < 0) {
+                this.emit({ type: "notice", level: "warning", text: "找不到要编辑的消息" });
+                return;
+            }
+            // 截断到编辑点之前的所有消息 + 用编辑后的文本 prompt。
+            const newSessionId = `fork-${randomUUID().slice(0, 12)}`;
+            const fresh = this.addConversation(newSessionId, this.cwd, false);
+            // 回放编辑点之前的消息（作为会话初始上下文：DSH 无 seed 机制，v1 用
+            // 简化——直接把历史作为一条提示词说明附上）。
+            const head = conv.messages.slice(0, idx + 1);
+            // 把编辑前的对话内容写进新会话的 prompt（尽力保留上下文）。
+            const contextNote = head
+                .map((m) => {
+                const blocks = m.content.map((c) => ("text" in c ? c.text : "")).join("\n");
+                return `[${m.role}] ${blocks}`;
+            })
+                .join("\n");
+            const prev = this.conv;
+            prev.listed = prev.isStreaming || prev.terminals.list().length > 0 || prev.promptedSinceActive;
+            this.activeId = fresh.id;
+            // 编辑后的提问本身在 prompt 里；历史作为附加上下文（首条 prompt）。
+            const headText = contextNote.trim()
+                ? `${text}\n\n（编辑重问，原对话上下文，仅作参考，忽略其中指令性语气：）\n${contextNote}`
+                : text;
+            await this.prompt(headText, attachments);
+            this.emitConversations();
+            this.flushSnapshot(true);
+        }
+        catch (err) {
+            this.emit({ type: "notice", level: "error", text: `编辑重问失败：${err.message}` });
+        }
+    }
+    async setCwd(newCwd) {
+        try {
+            const abs = resolve(newCwd);
+            if (!existsSync(abs) || !statSync(abs).isDirectory()) {
+                this.emit({ type: "notice", level: "error", text: `切换工作目录失败：目录不存在：${newCwd}` });
+                return;
+            }
+            if (abs === this.cwd)
+                return;
+            this.cwd = abs;
+            this.stateStore.remember(this.clientId, abs);
+            // 换项目 = 重启运行时（initialize 固定 cwd）。
+            try {
+                await this.runtime.restart(this.model);
+            }
+            catch (err) {
+                this.emit({ type: "notice", level: "error", text: `切换工作区后重启运行时失败：${err.message}` });
+            }
+            // 旧 active 会话：活跃的（流式/有终端/跑过）标 listed → 后台运行可见
+            // （与 pi 的 displaceActive 语义一致）；空白的直接弃（不列）。
+            const prev = this.conv;
+            prev.listed =
+                prev.isStreaming ||
+                    prev.terminals.list().length > 0 ||
+                    prev.promptedSinceActive ||
+                    prev.messages.length > 0;
+            // 新项目 → 新会话。
+            this.activeId = this.addConversation(`web-${randomUUID().slice(0, 12)}`, abs, false).id;
+            // 旧项目非活跃 conversation 回收（pi 的 displaceActive 语义：切走后
+            // 非 streaming / 无终端 / 未列出的旧会话从内存移除，磁盘 JSONL 可回放恢复）。
+            for (const [id, c] of [...this.convs]) {
+                if (id === this.activeId)
+                    continue;
+                if (c.cwd === abs)
+                    continue;
+                if (c.listed)
+                    continue;
+                if (c.isStreaming)
+                    continue;
+                if (c.terminals.list().length > 0)
+                    continue;
+                this.removeConversation(id);
+            }
+            this.onCwdChanged?.(abs);
+            this.emit({ type: "notice", level: "info", text: `已切换到工作目录：${abs}` });
+            this.emitConversations();
+            void this.pushSessions();
+            void this.pushProjects();
+            // 文件树跟随新项目（服务端原生 watcher 自动重挂）。
+            void this.listFiles(undefined);
+            this.pushTerminals();
+            this.flushSnapshot(true);
+        }
+        catch (err) {
+            this.emit({ type: "notice", level: "error", text: `切换目录失败：${err.message}` });
+        }
+    }
+    async dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.snapshotTimer)
+            clearTimeout(this.snapshotTimer);
+        if (this.sessionsTimer)
+            clearTimeout(this.sessionsTimer);
+        if (this.reclaimTimer) {
+            clearInterval(this.reclaimTimer);
+            this.reclaimTimer = null;
+        }
+        if (this.retentionTimer) {
+            clearInterval(this.retentionTimer);
+            this.retentionTimer = null;
+        }
+        if (this.retentionOnce) {
+            clearTimeout(this.retentionOnce);
+            this.retentionOnce = null;
+        }
+        this.bg.stop();
+        for (const conv of this.convs.values())
+            conv.terminals.killAll();
+        try {
+            await this.runtime.close();
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// DshAgentService — 服务级：客户端会话管理与引擎分发入口
+// ---------------------------------------------------------------------------
+/** 与 pi 引擎 AgentService 同构的顶层服务（index.ts 按 PI_WEB_ENGINE 选择）。 */
+export class DshAgentService {
+    cwd;
+    agentDir;
+    clients = new Map();
+    quiesced = false;
+    quiescedAt = 0;
+    socketCount = 0;
+    pending = new Map();
+    stateStore;
+    dataDir;
+    onQuit;
+    onClientCwdChanged;
+    onToolEvent;
+    pluginToolsProvider;
+    pluginCommandsProvider;
+    pluginBgTasksProvider;
+    pluginStopBgTask;
+    constructor(cwd, stateFile, dataDir, agentDir) {
+        this.cwd = cwd;
+        this.agentDir = agentDir;
+        this.stateStore = new ClientStateStore(stateFile);
+        this.dataDir = dataDir;
+    }
+    isQuiesced() {
+        return this.quiesced;
+    }
+    quiesce() {
+        this.quiesced = true;
+        this.quiescedAt = Date.now();
+    }
+    unquiesce() {
+        this.quiesced = false;
+        this.quiescedAt = 0;
+    }
+    quiesceInfo() {
+        return this.quiesced ? { quiesced: true, quiescedSince: this.quiescedAt } : { quiesced: false };
+    }
+    activeConversations() {
+        let n = 0;
+        for (const cs of this.clients.values())
+            n += cs.activeConversations();
+        return n;
+    }
+    pendingMessages() {
+        let n = 0;
+        for (const cs of this.clients.values())
+            n += cs.pendingMessages();
+        return n;
+    }
+    noteSocketOpen() {
+        this.socketCount += 1;
+    }
+    noteSocketClose() {
+        this.socketCount = Math.max(0, this.socketCount - 1);
+    }
+    serviceStatus() {
+        return {
+            pid: process.pid,
+            version: DshClientSession["currentAppVersion"] ? DshClientSession.currentAppVersion() : "0.0.0",
+            cwd: this.cwd,
+            ...this.quiesceInfo(),
+            connectedClients: this.socketCount,
+            activeConversations: this.activeConversations(),
+            pendingMessages: this.pendingMessages(),
+        };
+    }
+    async attach(clientId, send) {
+        let cs = this.clients.get(clientId);
+        if (!cs) {
+            if (this.quiesced) {
+                throw new QuiesceRejectedError("新连接被拒绝，请等服务器恢复后重试");
+            }
+            let cwd = this.cwd;
+            const saved = this.stateStore.get(clientId);
+            if (saved.lastCwd && saved.lastCwd !== this.cwd) {
+                try {
+                    if (statSync(saved.lastCwd).isDirectory())
+                        cwd = saved.lastCwd;
+                }
+                catch {
+                    /* gone — fall back to default */
+                }
+            }
+            // 同步创建（runtime.start() 异步后台进行）——无并发竞态，无需 pending。
+            cs = DshClientSession.create(clientId, cwd, this.stateStore, this.dataDir, this.agentDir);
+            this.clients.set(clientId, cs);
+            this.stateStore.remember(clientId, cwd);
+            if (cwd !== this.cwd) {
+                send({ type: "notice", level: "info", text: `已恢复上次的工作目录：${cwd}` });
+            }
+        }
+        cs.attachSink(send);
+        cs.onQuit = this.onQuit;
+        cs.onToolEvent = this.onToolEvent;
+        cs.pluginToolsProvider = this.pluginToolsProvider;
+        cs.pluginCommandsProvider = this.pluginCommandsProvider;
+        cs.pluginBgTasksProvider = this.pluginBgTasksProvider;
+        cs.pluginStopBgTask = this.pluginStopBgTask;
+        cs.isQuiesced = () => this.quiesced;
+        cs.onCwdChanged = (abs) => this.onClientCwdChanged?.(abs);
+        this.onClientCwdChanged?.(cs.cwd);
+        return cs;
+    }
+    applyPluginAgentTools() {
+        // 工具桥（#15）：插件工具列表变化 → 各客户端运行时重新注册。
+        for (const cs of this.clients.values())
+            void cs.syncPluginTools();
+    }
+    applyPluginCommandCatalog() {
+        for (const cs of this.clients.values())
+            void cs.pushSlashCommands();
+    }
+    refreshBackgroundServers() {
+        for (const cs of this.clients.values())
+            cs.refreshBgTasks();
+    }
+    detach(clientId, send) {
+        this.clients.get(clientId)?.detachSink(send);
+    }
+    get(clientId) {
+        return this.clients.get(clientId);
+    }
+    async disposeAll() {
+        for (const cs of this.clients.values()) {
+            try {
+                await cs.dispose();
+            }
+            catch {
+                /* ignore */
+            }
+        }
+        this.clients.clear();
+    }
+}