@xcanwin/manyoyo 5.8.5 → 5.8.9

package/lib/web/server.js

@@ -10,6 +10,31 @@ const WebSocket = require('ws');
 const JSON5 = require('json5');
 const { buildContainerRunArgs } = require('../container-run');
 const { extractAgentMessageFromCodexJsonl } = require('../codex-output');
+const { findValueRangeByPath, applyTextReplacements } = require('../json5-text-edit');
+const { resolveRuntimeConfig } = require('../runtime-resolver');
+const {
+    normalizeAgentPromptCommandTemplate,
+    isAgentPromptCommandEnabled,
+    buildWebAgentExecCommand,
+    getAgentRuntimeMeta
+} = require('./agent-command');
+const { createStructuredOutputHelpers } = require('./structured-output');
+const { prepareStructuredTraceEvents, extractContentDeltaFromPayload } = require('./structured-trace');
+const { createWebContainerExecHelpers } = require('./container-exec');
+const { createWebRuntimeStateHelpers } = require('./runtime-state');
+const { createWebTerminalHelpers } = require('./terminal-session');
+const { createWebUpgradeHandler } = require('./upgrade-handler');
+const { createWebHttpHandlers } = require('./http-handlers');
+const { createWebServerContextHelpers } = require('./server-context');
+const { createWebServerLifecycleHelpers } = require('./server-lifecycle');
+const { createApiRouteHelpers, runMatchedRoute } = require('./api-route-helpers');
+const { createSystemApiRoutes } = require('./system-api-routes');
+const { createSessionApiRoutes } = require('./session-api-routes');
+const {
+    parseEnvEntry,
+    expandHomeAliasPath,
+    normalizeVolume
+} = require('../runtime-normalizers');
 const {
     resolveAgentProgram,
     resolveAgentPromptCommandTemplate,
@@ -34,6 +59,9 @@ const WEB_DEFAULT_AGENT_ID = 'default';
 const WEB_DEFAULT_AGENT_NAME = 'AGENT 1';
 const WEB_CONFIG_KEEP_SECRET_PLACEHOLDER = '***HIDDEN_SECRET***';
 const FRONTEND_DIR = path.join(__dirname, 'frontend');
+const AUTH_FRONTEND_ASSETS = new Set(['login.css', 'login.js']);
+const APP_FRONTEND_ASSETS = new Set(['app.css', 'app.js', 'markdown.css', 'markdown-renderer.js']);
+const APP_VENDOR_ASSETS = new Set(['xterm.css', 'xterm.js', 'xterm-addon-fit.js', 'marked.min.js']);
 const SAFE_CONTAINER_NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_.-]*$/;
 const IMAGE_VERSION_TAG_PATTERN = /^(\d+\.\d+\.\d+)-([A-Za-z0-9][A-Za-z0-9_.-]*)$/;
 const SENSITIVE_CONFIG_KEY_PATTERN = /(pass(word)?|passwd|secret|token|api(?:_|-)?key|auth(?:_|-)?token|oauth(?:_|-)?token)$/i;
@@ -517,273 +545,95 @@ function clipText(text, maxChars = WEB_OUTPUT_MAX_CHARS) {
     return `${text.slice(0, maxChars)}\n...[truncated]`;
 }
 
-function normalizeAgentPromptCommandTemplate(value, sourceLabel = 'agentPromptCommand') {
-    if (value === undefined || value === null) {
-        return '';
-    }
-    if (typeof value !== 'string') {
-        throw new Error(`${sourceLabel} 必须是字符串`);
-    }
-    const text = value.trim();
-    if (!text) {
-        return '';
-    }
-    if (!text.includes('{prompt}')) {
-        throw new Error(`${sourceLabel} 必须包含 {prompt} 占位符`);
-    }
-    if (/^codex\s+exec(?:\s|$)/.test(text) && !text.includes('--skip-git-repo-check')) {
-        return text.replace(/^codex\s+exec\b/, 'codex exec --skip-git-repo-check');
-    }
-    return text;
-}
-
-function isAgentPromptCommandEnabled(value) {
-    return typeof value === 'string' && value.includes('{prompt}') && Boolean(value.trim());
-}
-
-function quoteBashSingleValue(value) {
-    const text = String(value || '');
-    return `'${text.replace(/'/g, `'\"'\"'`)}'`;
-}
-
-function renderAgentPromptCommand(template, prompt) {
-    const templateText = normalizeAgentPromptCommandTemplate(template, 'agentPromptCommand');
-    const safePrompt = quoteBashSingleValue(prompt);
-    return templateText.replace(/\{prompt\}/g, safePrompt);
-}
-
-function buildCodexAgentExecCommand(template, prompt) {
-    const templateText = normalizeAgentPromptCommandTemplate(template, 'agentPromptCommand');
-    const execMatch = templateText.match(
-        /^((?:(?:[A-Za-z_][A-Za-z0-9_]*=)(?:"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s]+)\s+)*)codex\s+exec\b/
-    );
-    let codexTemplate = templateText;
-    if (execMatch) {
-        const prefix = execMatch[1] || '';
-        const suffix = templateText.slice(execMatch[0].length);
-        const hasJson = /(?:^|\s)--json(?:\s|$)/.test(suffix);
-        const injectedFlags = hasJson ? '' : ' --json';
-        codexTemplate = `${prefix}codex exec${injectedFlags}${suffix}`;
-    }
-    return codexTemplate === templateText
-        ? renderAgentPromptCommand(templateText, prompt)
-        : renderAgentPromptCommand(codexTemplate, prompt);
-}
-
-function prependAgentFlags(commandText, matchPattern, flagSpecs) {
-    const matched = String(commandText || '').match(matchPattern);
-    if (!matched) {
-        return String(commandText || '');
-    }
-    const prefix = matched[1] || '';
-    let suffix = matched[matched.length - 1] || '';
-    for (let i = flagSpecs.length - 1; i >= 0; i -= 1) {
-        const spec = flagSpecs[i];
-        if (!spec || !spec.flag || !(spec.pattern instanceof RegExp) || spec.pattern.test(suffix)) {
-            continue;
-        }
-        suffix = ` ${spec.flag}${suffix}`;
-    }
-    return `${prefix}${suffix}`;
-}
-
-function buildClaudeAgentExecCommand(template, prompt) {
-    const templateText = normalizeAgentPromptCommandTemplate(template, 'agentPromptCommand');
-    const claudeTemplate = prependAgentFlags(
-        templateText,
-        /^(((?:(?:[A-Za-z_][A-Za-z0-9_]*=)(?:"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s]+)\s+)*)claude\b)(.*)$/,
-        [
-            { flag: '--verbose', pattern: /(?:^|\s)--verbose(?:\s|$)/ },
-            { flag: '--output-format stream-json', pattern: /(?:^|\s)--output-format(?:\s|$)/ }
-        ]
-    );
-    return claudeTemplate === templateText
-        ? renderAgentPromptCommand(templateText, prompt)
-        : renderAgentPromptCommand(claudeTemplate, prompt);
-}
-
-function buildGeminiAgentExecCommand(template, prompt) {
-    const templateText = normalizeAgentPromptCommandTemplate(template, 'agentPromptCommand');
-    const geminiTemplate = prependAgentFlags(
-        templateText,
-        /^(((?:(?:[A-Za-z_][A-Za-z0-9_]*=)(?:"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s]+)\s+)*)gemini\b)(.*)$/,
-        [
-            { flag: '--output-format stream-json', pattern: /(?:^|\s)--output-format(?:\s|$)/ }
-        ]
-    );
-    return geminiTemplate === templateText
-        ? renderAgentPromptCommand(templateText, prompt)
-        : renderAgentPromptCommand(geminiTemplate, prompt);
-}
-
-function buildOpenCodeAgentExecCommand(template, prompt) {
-    const templateText = normalizeAgentPromptCommandTemplate(template, 'agentPromptCommand');
-    const opencodeTemplate = prependAgentFlags(
-        templateText,
-        /^(((?:(?:[A-Za-z_][A-Za-z0-9_]*=)(?:"(?:\\.|[^"])*"|'(?:\\.|[^'])*'|[^\s]+)\s+)*)opencode\s+run\b)(.*)$/,
-        [
-            { flag: '--format json', pattern: /(?:^|\s)--format(?:\s|$)/ }
-        ]
-    );
-    return opencodeTemplate === templateText
-        ? renderAgentPromptCommand(templateText, prompt)
-        : renderAgentPromptCommand(opencodeTemplate, prompt);
-}
-
-function buildWebAgentExecCommand(template, prompt, agentProgram) {
-    switch (agentProgram) {
-    case 'claude':
-        return buildClaudeAgentExecCommand(template, prompt);
-    case 'gemini':
-        return buildGeminiAgentExecCommand(template, prompt);
-    case 'codex':
-        return buildCodexAgentExecCommand(template, prompt);
-    case 'opencode':
-        return buildOpenCodeAgentExecCommand(template, prompt);
-    default:
-        break;
-    }
-    return renderAgentPromptCommand(template, prompt);
-}
-
-function parseJsonObjectLine(line) {
-    const text = String(line || '').trim();
-    if (!text) {
-        return null;
-    }
-    try {
-        const payload = JSON.parse(text);
-        return payload && typeof payload === 'object' ? payload : null;
-    } catch (e) {
-        return null;
-    }
-}
-
-function collectStructuredText(value) {
-    if (typeof value === 'string') {
-        return value.trim();
-    }
-    if (Array.isArray(value)) {
-        return value.map(item => collectStructuredText(item)).filter(Boolean).join('\n').trim();
-    }
-    if (!value || typeof value !== 'object') {
-        return '';
-    }
-    if (typeof value.text === 'string' && value.text.trim()) {
-        return value.text.trim();
-    }
-    if (typeof value.content === 'string' && value.content.trim()) {
-        return value.content.trim();
-    }
-    if (Array.isArray(value.content)) {
-        return value.content.map(item => collectStructuredText(item)).filter(Boolean).join('\n').trim();
-    }
-    return '';
-}
+const {
+    parseJsonObjectLine,
+    collectStructuredText,
+    extractAgentMessageFromStructuredOutput
+} = createStructuredOutputHelpers({
+    pickFirstString,
+    toPlainObject,
+    extractAgentMessageFromCodexJsonl
+});
+
+const STRUCTURED_TRACE_DEPS = {
+    pickFirstString,
+    toPlainObject,
+    collectStructuredText,
+    clipText,
+    stripAnsi
+};
 
-function extractClaudeAgentMessage(text) {
-    let lastMessage = '';
-    for (const rawLine of String(text || '').split('\n')) {
-        const payload = parseJsonObjectLine(rawLine);
-        if (!payload || payload.type !== 'assistant') {
-            continue;
-        }
-        const message = toPlainObject(payload.message);
-        const content = Array.isArray(message.content) ? message.content : [];
-        const nextMessage = content
-            .filter(item => item && typeof item === 'object' && item.type === 'text')
-            .map(item => collectStructuredText(item))
-            .filter(Boolean)
-            .join('\n')
-            .trim();
-        if (nextMessage) {
-            lastMessage = nextMessage;
-        }
-    }
-    return lastMessage.trim();
-}
+const {
+    execCommandInWebContainer,
+    execAgentInWebContainerStream
+} = createWebContainerExecHelpers({
+    buildWebSessionKey,
+    defaultAgentId: WEB_DEFAULT_AGENT_ID,
+    extractAgentMessageFromStructuredOutput,
+    parseJsonObjectLine,
+    prepareStructuredTraceEvents,
+    extractContentDeltaFromPayload,
+    structuredTraceDeps: STRUCTURED_TRACE_DEPS,
+    clipText,
+    stripAnsi
+});
 
-function extractGeminiAgentMessage(text) {
-    let lastMessage = '';
-    let deltaMessage = '';
-    for (const rawLine of String(text || '').split('\n')) {
-        const payload = parseJsonObjectLine(rawLine);
-        if (!payload || payload.type !== 'message' || payload.role !== 'assistant') {
-            continue;
-        }
-        const content = collectStructuredText(payload.content);
-        if (!content) {
-            continue;
-        }
-        if (payload.delta === true) {
-            deltaMessage += content;
-            lastMessage = deltaMessage.trim();
-            continue;
-        }
-        deltaMessage = '';
-        lastMessage = content;
-    }
-    return lastMessage.trim();
-}
+const {
+    createInitialWebRuntimeState,
+    stopWebAgentRun,
+    cleanupWebRuntimeState
+} = createWebRuntimeStateHelpers();
 
-function extractOpenCodeAgentMessage(text) {
-    let lastMessage = '';
-    let deltaMessage = '';
-    for (const rawLine of String(text || '').split('\n')) {
-        const payload = parseJsonObjectLine(rawLine);
-        if (!payload) {
-            continue;
-        }
-        const eventType = pickFirstString(payload.type);
-        const message = toPlainObject(payload.message);
-        const role = pickFirstString(payload.role, message.role);
-        if (eventType !== 'message' && eventType !== 'assistant' && eventType !== 'assistant_message' && eventType !== 'text') {
-            continue;
-        }
-        if (role && role !== 'assistant') {
-            continue;
-        }
-        const content = collectStructuredText(message.content || payload.content || payload.text || payload);
-        if (!content) {
-            continue;
-        }
-        if (payload.delta === true) {
-            deltaMessage += content;
-            lastMessage = deltaMessage.trim();
-            continue;
-        }
-        deltaMessage = '';
-        lastMessage = content;
-    }
-    return lastMessage.trim();
-}
+const {
+    createWebServerContext,
+    createWebServerState
+} = createWebServerContextHelpers({
+    createInitialWebRuntimeState,
+    getDefaultWebConfigPath
+});
 
-function extractAgentMessageFromStructuredOutput(agentProgram, text) {
-    if (agentProgram === 'codex') {
-        return extractAgentMessageFromCodexJsonl(text);
-    }
-    if (agentProgram === 'claude') {
-        return extractClaudeAgentMessage(text);
-    }
-    if (agentProgram === 'gemini') {
-        return extractGeminiAgentMessage(text);
-    }
-    if (agentProgram === 'opencode') {
-        return extractOpenCodeAgentMessage(text);
-    }
-    return '';
-}
+const {
+    normalizeTerminalSize,
+    sendWebSocketUpgradeError,
+    bindTerminalWebSocket
+} = createWebTerminalHelpers({
+    WebSocket,
+    spawn,
+    forceKillMs: WEB_TERMINAL_FORCE_KILL_MS,
+    defaultCols: WEB_TERMINAL_DEFAULT_COLS,
+    defaultRows: WEB_TERMINAL_DEFAULT_ROWS,
+    minCols: WEB_TERMINAL_MIN_COLS,
+    minRows: WEB_TERMINAL_MIN_ROWS
+});
+
+const handleWebUpgradeRequest = createWebUpgradeHandler({
+    formatUrlHost,
+    sendWebSocketUpgradeError,
+    getWebAuthSession,
+    parseWebSessionKey,
+    decodeSessionName,
+    safeContainerNamePattern: SAFE_CONTAINER_NAME_PATTERN,
+    normalizeTerminalSize,
+    ensureWebContainer,
+    maxTerminalSessions: WEB_TERMINAL_MAX_SESSIONS
+});
 
-function getAgentRuntimeMeta(template) {
-    const normalizedTemplate = normalizeAgentPromptCommandTemplate(template, 'agentPromptCommand');
-    const agentProgram = resolveAgentProgram(normalizedTemplate);
-    const resumeCommand = buildAgentResumeCommand(agentProgram);
-    return {
-        agentProgram: agentProgram || '',
-        resumeCommand: resumeCommand || '',
-        resumeSupported: Boolean(resumeCommand)
-    };
-}
+const {
+    createWsServer,
+    createHttpServer,
+    listenWebServer,
+    closeWebServer
+} = createWebServerLifecycleHelpers({
+    http,
+    WebSocket,
+    formatUrlHost,
+    normalizeTerminalSize,
+    bindTerminalWebSocket,
+    handleWebUpgradeRequest,
+    sendJson,
+    sendHtml,
+    cleanupWebRuntimeState
+});
 
 function hasAgentConversationHistory(history) {
     const messages = history && Array.isArray(history.messages) ? history.messages : [];
@@ -845,599 +695,6 @@ function buildAgentPromptWithHistory(history, prompt) {
     ].join('\n');
 }
 
-function shortenTraceText(value, maxChars = 140) {
-    const raw = clipText(stripAnsi(String(value || '')).replace(/\s+/g, ' ').trim(), maxChars);
-    return raw.trim();
-}
-
-function summarizeTraceArguments(args) {
-    if (!args || typeof args !== 'object' || Array.isArray(args)) {
-        return '';
-    }
-    const parts = [];
-    for (const [key, value] of Object.entries(args)) {
-        if (value === undefined || value === null) continue;
-        if (typeof value === 'string') {
-            const textValue = value.trim();
-            if (!textValue) continue;
-            parts.push(`${key}=${shortenTraceText(textValue, 80)}`);
-            continue;
-        }
-        if (typeof value === 'number' || typeof value === 'boolean') {
-            parts.push(`${key}=${String(value)}`);
-        }
-    }
-    return parts.slice(0, 3).join(', ');
-}
-
-function createStructuredTraceEvent(provider, kind, eventType, textValue, extra = {}) {
-    const normalizedText = String(textValue || '').trim();
-    if (!normalizedText) {
-        return null;
-    }
-    return {
-        provider,
-        kind,
-        eventType,
-        text: normalizedText,
-        ...extra
-    };
-}
-
-function prepareClaudeTraceEvents(payload, state) {
-    const eventType = pickFirstString(payload.type);
-    const subtype = pickFirstString(payload.subtype);
-    const message = toPlainObject(payload.message);
-    const content = Array.isArray(message.content) ? message.content : [];
-    const toolNamesById = state.toolNamesById;
-    const events = [];
-
-    if (eventType === 'system' && subtype === 'init') {
-        events.push(createStructuredTraceEvent('claude', 'thread', eventType, '[会话] Claude 已开始处理', {
-            phase: 'started',
-            status: 'started',
-            subtype
-        }));
-        return events.filter(Boolean);
-    }
-    if (eventType === 'assistant') {
-        content.forEach(item => {
-            if (!item || typeof item !== 'object') {
-                return;
-            }
-            if (item.type === 'text') {
-                const detail = collectStructuredText(item);
-                if (detail) {
-                    events.push(createStructuredTraceEvent('claude', 'agent_message', eventType, `[说明] ${detail}`, {
-                        phase: 'completed',
-                        status: 'completed',
-                        detail
-                    }));
-                }
-                return;
-            }
-            if (item.type === 'tool_use') {
-                const toolName = pickFirstString(item.name, item.id, 'tool');
-                const toolId = pickFirstString(item.id);
-                if (toolId) {
-                    toolNamesById.set(toolId, toolName);
-                }
-                const summary = summarizeTraceArguments(toPlainObject(item.input));
-                events.push(createStructuredTraceEvent(
-                    'claude',
-                    'tool',
-                    eventType,
-                    summary ? `[工具开始] ${toolName} (${summary})` : `[工具开始] ${toolName}`,
-                    {
-                        phase: 'started',
-                        status: 'in_progress',
-                        toolName,
-                        toolId,
-                        arguments: toPlainObject(item.input),
-                        argumentSummary: summary
-                    }
-                ));
-            }
-        });
-        return events.filter(Boolean);
-    }
-    if (eventType === 'user') {
-        content.forEach(item => {
-            if (!item || typeof item !== 'object' || item.type !== 'tool_result') {
-                return;
-            }
-            const toolId = pickFirstString(item.tool_use_id);
-            const toolName = pickFirstString(toolNamesById.get(toolId), toolId, 'tool');
-            const status = item.is_error === true ? 'error' : 'success';
-            events.push(createStructuredTraceEvent('claude', 'tool', eventType, `[工具完成] ${toolName} (${status})`, {
-                phase: 'completed',
-                status,
-                toolName,
-                toolId,
-                result: collectStructuredText(item.content),
-                error: item.is_error === true ? collectStructuredText(item.content) : ''
-            }));
-        });
-        return events.filter(Boolean);
-    }
-    if (eventType === 'result') {
-        events.push(createStructuredTraceEvent('claude', 'turn', eventType, '[回合] 响应完成', {
-            phase: 'completed',
-            status: pickFirstString(subtype, 'completed'),
-            subtype
-        }));
-        return events.filter(Boolean);
-    }
-    if (eventType === 'error') {
-        const detail = pickFirstString(payload.message, payload.error);
-        events.push(createStructuredTraceEvent('claude', 'error', eventType, detail ? `[错误] ${detail}` : '[错误] Claude 返回了错误事件', {
-            status: 'error',
-            detail
-        }));
-        return events.filter(Boolean);
-    }
-    return [];
-}
-
-function prepareGeminiTraceEvents(payload, state) {
-    const eventType = pickFirstString(payload.type);
-    const toolNamesById = state.toolNamesById;
-    const events = [];
-
-    if (eventType === 'init') {
-        events.push(createStructuredTraceEvent('gemini', 'thread', eventType, '[会话] Gemini 已开始处理', {
-            phase: 'started',
-            status: 'started',
-            sessionId: pickFirstString(payload.session_id),
-            model: pickFirstString(payload.model)
-        }));
-        return events.filter(Boolean);
-    }
-    if (eventType === 'message' && payload.role === 'assistant') {
-        if (payload.delta === true) {
-            return [];
-        }
-        const detail = collectStructuredText(payload.content);
-        if (!detail) {
-            return [];
-        }
-        events.push(createStructuredTraceEvent('gemini', 'agent_message', eventType, `[说明] ${detail}`, {
-            phase: 'completed',
-            status: 'completed',
-            detail
-        }));
-        return events.filter(Boolean);
-    }
-    if (eventType === 'tool_use') {
-        const toolName = pickFirstString(payload.tool_name, payload.tool_id, 'tool');
-        const toolId = pickFirstString(payload.tool_id);
-        if (toolId) {
-            toolNamesById.set(toolId, toolName);
-        }
-        const summary = summarizeTraceArguments(toPlainObject(payload.parameters));
-        events.push(createStructuredTraceEvent(
-            'gemini',
-            'tool',
-            eventType,
-            summary ? `[工具开始] ${toolName} (${summary})` : `[工具开始] ${toolName}`,
-            {
-                phase: 'started',
-                status: 'in_progress',
-                toolName,
-                toolId,
-                arguments: toPlainObject(payload.parameters),
-                argumentSummary: summary
-            }
-        ));
-        return events.filter(Boolean);
-    }
-    if (eventType === 'tool_result') {
-        const toolId = pickFirstString(payload.tool_id);
-        const toolName = pickFirstString(toolNamesById.get(toolId), toolId, 'tool');
-        const status = pickFirstString(payload.status, 'completed');
-        events.push(createStructuredTraceEvent('gemini', 'tool', eventType, `[工具完成] ${toolName} (${status})`, {
-            phase: 'completed',
-            status,
-            toolName,
-            toolId,
-            result: collectStructuredText(payload.output),
-            error: toPlainObject(payload.error)
-        }));
-        return events.filter(Boolean);
-    }
-    if (eventType === 'result') {
-        events.push(createStructuredTraceEvent('gemini', 'turn', eventType, '[回合] 响应完成', {
-            phase: 'completed',
-            status: pickFirstString(payload.status, 'completed')
-        }));
-        return events.filter(Boolean);
-    }
-    if (eventType === 'error') {
-        const detail = pickFirstString(payload.message);
-        events.push(createStructuredTraceEvent('gemini', 'error', eventType, detail ? `[错误] ${detail}` : '[错误] Gemini 返回了错误事件', {
-            status: pickFirstString(payload.severity, 'error'),
-            detail
-        }));
-        return events.filter(Boolean);
-    }
-    return [];
-}
-
-function prepareOpenCodeTraceEvents(payload, state) {
-    const eventType = pickFirstString(payload.type);
-    const message = toPlainObject(payload.message);
-    const role = pickFirstString(payload.role, message.role);
-    const toolNamesById = state.toolNamesById;
-    const events = [];
-
-    if (eventType === 'session.start' || eventType === 'init') {
-        events.push(createStructuredTraceEvent('opencode', 'thread', eventType, '[会话] OpenCode 已开始处理', {
-            phase: 'started',
-            status: 'started',
-            sessionId: pickFirstString(payload.session_id, payload.sessionID)
-        }));
-        return events.filter(Boolean);
-    }
-    if (eventType === 'message' || eventType === 'assistant' || eventType === 'assistant_message' || eventType === 'text') {
-        if (role && role !== 'assistant') {
-            return [];
-        }
-        if (payload.delta === true) {
-            return [];
-        }
-        const detail = collectStructuredText(message.content || payload.content || payload.text || payload);
-        if (!detail) {
-            return [];
-        }
-        events.push(createStructuredTraceEvent('opencode', 'agent_message', eventType, `[说明] ${detail}`, {
-            phase: 'completed',
-            status: 'completed',
-            detail
-        }));
-        return events.filter(Boolean);
-    }
-    if (eventType === 'tool_use' || eventType === 'step_start') {
-        const toolName = pickFirstString(payload.tool_name, payload.name, payload.tool, payload.step, payload.tool_id, 'tool');
-        const toolId = pickFirstString(payload.tool_id, payload.id);
-        if (toolId) {
-            toolNamesById.set(toolId, toolName);
-        }
-        const argumentsValue = toPlainObject(payload.parameters || payload.input || payload.arguments);
-        const summary = summarizeTraceArguments(argumentsValue);
-        events.push(createStructuredTraceEvent(
-            'opencode',
-            'tool',
-            eventType,
-            summary ? `[工具开始] ${toolName} (${summary})` : `[工具开始] ${toolName}`,
-            {
-                phase: 'started',
-                status: pickFirstString(payload.status, 'in_progress'),
-                toolName,
-                toolId,
-                arguments: argumentsValue,
-                argumentSummary: summary
-            }
-        ));
-        return events.filter(Boolean);
-    }
-    if (eventType === 'tool_result' || eventType === 'step_finish') {
-        const toolId = pickFirstString(payload.tool_id, payload.id);
-        const toolName = pickFirstString(toolNamesById.get(toolId), payload.tool_name, payload.name, payload.tool, toolId, 'tool');
-        const status = pickFirstString(payload.status, payload.state, 'completed');
-        events.push(createStructuredTraceEvent('opencode', 'tool', eventType, `[工具完成] ${toolName} (${status})`, {
-            phase: 'completed',
-            status,
-            toolName,
-            toolId,
-            result: collectStructuredText(payload.output || payload.result),
-            error: toPlainObject(payload.error)
-        }));
-        return events.filter(Boolean);
-    }
-    if (eventType === 'result') {
-        events.push(createStructuredTraceEvent('opencode', 'turn', eventType, '[回合] 响应完成', {
-            phase: 'completed',
-            status: pickFirstString(payload.status, 'completed')
-        }));
-        return events.filter(Boolean);
-    }
-    if (eventType === 'error') {
-        const detail = pickFirstString(payload.message, payload.error && payload.error.message);
-        events.push(createStructuredTraceEvent('opencode', 'error', eventType, detail ? `[错误] ${detail}` : '[错误] OpenCode 返回了错误事件', {
-            status: 'error',
-            detail
-        }));
-        return events.filter(Boolean);
-    }
-    return [];
-}
-
-function prepareStructuredTraceEvents(agentProgram, payload, state) {
-    if (!payload || typeof payload !== 'object') {
-        return [];
-    }
-    if (agentProgram === 'codex') {
-        const traceEvent = prepareCodexTraceEvent(payload);
-        return traceEvent ? [traceEvent] : [];
-    }
-    if (agentProgram === 'claude') {
-        return prepareClaudeTraceEvents(payload, state);
-    }
-    if (agentProgram === 'gemini') {
-        return prepareGeminiTraceEvents(payload, state);
-    }
-    if (agentProgram === 'opencode') {
-        return prepareOpenCodeTraceEvents(payload, state);
-    }
-    return [];
-}
-
-function extractContentDeltaFromPayload(agentProgram, payload) {
-    if (!payload || typeof payload !== 'object') {
-        return null;
-    }
-    if (agentProgram === 'claude') {
-        if (pickFirstString(payload.type) !== 'assistant') {
-            return null;
-        }
-        const message = toPlainObject(payload.message);
-        const content = Array.isArray(message.content) ? message.content : [];
-        const text = content
-            .filter(item => item && typeof item === 'object' && item.type === 'text')
-            .map(item => collectStructuredText(item))
-            .filter(Boolean)
-            .join('\n')
-            .trim();
-        if (!text) {
-            return null;
-        }
-        return { text, reset: true };
-    }
-    if (agentProgram === 'gemini' || agentProgram === 'opencode') {
-        const eventType = pickFirstString(payload.type);
-        if (eventType !== 'message') {
-            return null;
-        }
-        const role = pickFirstString(payload.role);
-        if (role !== 'assistant') {
-            return null;
-        }
-        const text = collectStructuredText(payload.content);
-        if (!text) {
-            return null;
-        }
-        if (payload.delta === true) {
-            return { text, reset: false };
-        }
-        return { text, reset: true };
-    }
-    return null;
-}
-
-function prepareCodexTraceEvent(payload) {
-    if (!payload || typeof payload !== 'object') {
-        return null;
-    }
-
-    const eventType = typeof payload.type === 'string' ? payload.type : '';
-    const item = payload.item && typeof payload.item === 'object' && !Array.isArray(payload.item)
-        ? payload.item
-        : {};
-    const itemType = typeof item.type === 'string' ? item.type : '';
-    const text = pickFirstString(
-        item.title,
-        item.summary,
-        item.text,
-        item.name,
-        item.command,
-        payload.message,
-        payload.text
-    );
-    const toolName = pickFirstString(
-        item.name,
-        item.tool_name,
-        item.tool,
-        item.command
-    );
-    const commandText = pickFirstString(item.command);
-    const mcpServer = pickFirstString(item.server);
-    const mcpTool = pickFirstString(item.tool);
-    const itemStatus = pickFirstString(item.status);
-
-    function shortenText(value, maxChars = 140) {
-        const raw = clipText(stripAnsi(String(value || '')).replace(/\s+/g, ' ').trim(), maxChars);
-        return raw.trim();
-    }
-
-    function summarizeArguments(args) {
-        if (!args || typeof args !== 'object' || Array.isArray(args)) {
-            return '';
-        }
-        const parts = [];
-        for (const [key, value] of Object.entries(args)) {
-            if (value === undefined || value === null) continue;
-            if (typeof value === 'string') {
-                const textValue = value.trim();
-                if (!textValue) continue;
-                parts.push(`${key}=${shortenText(textValue, 80)}`);
-                continue;
-            }
-            if (typeof value === 'number' || typeof value === 'boolean') {
-                parts.push(`${key}=${String(value)}`);
-            }
-        }
-        return parts.slice(0, 3).join(', ');
-    }
-
-    function pickDisplayStatus(defaultStatus) {
-        const status = String(itemStatus || defaultStatus || '').trim();
-        return status || '';
-    }
-
-    function createTraceEvent(kind, textValue, extra = {}) {
-        const normalizedText = String(textValue || '').trim();
-        if (!normalizedText) {
-            return null;
-        }
-        return {
-            provider: 'codex',
-            kind,
-            eventType,
-            itemType: itemType || '',
-            text: normalizedText,
-            ...extra
-        };
-    }
-
-    if (eventType === 'thread.started') {
-        return createTraceEvent('thread', '[会话] Codex 已开始处理', {
-            phase: 'started',
-            status: 'started'
-        });
-    }
-    if (eventType === 'thread.completed') {
-        return createTraceEvent('thread', '[会话] Codex 已完成当前任务', {
-            phase: 'completed',
-            status: 'completed'
-        });
-    }
-    if (eventType === 'turn.started') {
-        return createTraceEvent('turn', '[回合] 开始生成响应', {
-            phase: 'started',
-            status: 'started'
-        });
-    }
-    if (eventType === 'turn.completed') {
-        return createTraceEvent('turn', '[回合] 响应完成', {
-            phase: 'completed',
-            status: 'completed'
-        });
-    }
-    if (eventType === 'item.started') {
-        if (itemType === 'tool_call') {
-            return createTraceEvent('tool', `[工具开始] ${toolName || 'tool_call'}`, {
-                phase: 'started',
-                status: pickDisplayStatus('in_progress'),
-                toolName: toolName || 'tool_call'
-            });
-        }
-        if (itemType === 'command_execution') {
-            return createTraceEvent('command', `[命令开始] ${commandText || 'command_execution'}`, {
-                phase: 'started',
-                status: pickDisplayStatus('in_progress'),
-                command: commandText || 'command_execution'
-            });
-        }
-        if (itemType === 'mcp_tool_call') {
-            const summary = summarizeArguments(item.arguments);
-            return createTraceEvent(
-                'mcp',
-                summary
-                    ? `[MCP开始] ${mcpServer || 'mcp'}.${mcpTool || 'tool'} (${summary})`
-                    : `[MCP开始] ${mcpServer || 'mcp'}.${mcpTool || 'tool'}`,
-                {
-                    phase: 'started',
-                    status: pickDisplayStatus('in_progress'),
-                    server: mcpServer || 'mcp',
-                    tool: mcpTool || 'tool',
-                    arguments: item.arguments && typeof item.arguments === 'object' && !Array.isArray(item.arguments)
-                        ? item.arguments
-                        : null,
-                    argumentSummary: summary
-                }
-            );
-        }
-        if (itemType === 'reasoning') {
-            return createTraceEvent('status', text ? `[状态] ${text}` : '[状态] Codex 正在分析', {
-                phase: 'started',
-                status: pickDisplayStatus('in_progress'),
-                detail: text || 'Codex 正在分析'
-            });
-        }
-        if (itemType === 'agent_message') {
-            return createTraceEvent('agent_message', text ? `[说明] ${text}` : '[回复] 正在生成最终答复', {
-                phase: 'started',
-                status: pickDisplayStatus('in_progress'),
-                detail: text || '正在生成最终答复'
-            });
-        }
-        return createTraceEvent('event', text ? `[事件开始] ${text}` : `[事件开始] ${itemType || eventType}`, {
-            phase: 'started',
-            status: pickDisplayStatus('in_progress'),
-            detail: text || itemType || eventType
-        });
-    }
-    if (eventType === 'item.completed') {
-        if (itemType === 'tool_call') {
-            return createTraceEvent('tool', `[工具完成] ${toolName || 'tool_call'}`, {
-                phase: 'completed',
-                status: pickDisplayStatus('completed'),
-                toolName: toolName || 'tool_call'
-            });
-        }
-        if (itemType === 'command_execution') {
-            const suffix = itemStatus || (typeof item.exit_code === 'number' ? `exit=${item.exit_code}` : 'completed');
-            return createTraceEvent('command', `[命令完成] ${commandText || 'command_execution'} (${suffix})`, {
-                phase: 'completed',
-                status: pickDisplayStatus(suffix),
-                command: commandText || 'command_execution',
-                exitCode: typeof item.exit_code === 'number' ? item.exit_code : null
-            });
-        }
-        if (itemType === 'mcp_tool_call') {
-            const summary = summarizeArguments(item.arguments);
-            return createTraceEvent(
-                'mcp',
-                summary
-                    ? `[MCP完成] ${mcpServer || 'mcp'}.${mcpTool || 'tool'} (${summary})`
-                    : `[MCP完成] ${mcpServer || 'mcp'}.${mcpTool || 'tool'}`,
-                {
-                    phase: 'completed',
-                    status: pickDisplayStatus('completed'),
-                    server: mcpServer || 'mcp',
-                    tool: mcpTool || 'tool',
-                    arguments: item.arguments && typeof item.arguments === 'object' && !Array.isArray(item.arguments)
-                        ? item.arguments
-                        : null,
-                    argumentSummary: summary,
-                    result: item.result !== undefined ? item.result : null,
-                    error: item.error !== undefined ? item.error : null
-                }
-            );
-        }
-        if (itemType === 'reasoning') {
-            return createTraceEvent('status', text ? `[状态] ${text}` : '', {
-                phase: 'completed',
-                status: pickDisplayStatus('completed'),
-                detail: text || ''
-            });
-        }
-        if (itemType === 'agent_message') {
-            return createTraceEvent('agent_message', text ? `[说明] ${text}` : '[回复] 已生成', {
-                phase: 'completed',
-                status: pickDisplayStatus('completed'),
-                detail: text || '已生成'
-            });
-        }
-        return createTraceEvent('event', text ? `[事件完成] ${text}` : `[事件完成] ${itemType || eventType}`, {
-            phase: 'completed',
-            status: pickDisplayStatus('completed'),
-            detail: text || itemType || eventType
-        });
-    }
-    if (eventType === 'error') {
-        return createTraceEvent('error', text ? `[错误] ${text}` : '[错误] Codex 返回了错误事件', {
-            status: 'error',
-            detail: text || 'Codex 返回了错误事件'
-        });
-    }
-
-    return createTraceEvent('event', `[事件] ${eventType}`, {
-        status: itemStatus || '',
-        detail: eventType
-    });
-}
-
 async function prepareWebAgentExecution(ctx, state, sessionRef, prompt) {
     const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
     const agentSession = getWebAgentSession(history, sessionRef.agentId, { create: true });
@@ -1636,242 +893,22 @@ function isSensitiveConfigKey(key) {
     return Boolean(normalized) && SENSITIVE_CONFIG_KEY_PATTERN.test(normalized);
 }
 
-function readConfigQuotedString(text, startIndex) {
-    const quote = text[startIndex];
-    let value = '';
-
-    for (let i = startIndex + 1; i < text.length; i += 1) {
-        const ch = text[i];
-        if (ch === '\\') {
-            value += ch;
-            if (i + 1 < text.length) {
-                value += text[i + 1];
-                i += 1;
-            }
-            continue;
-        }
-        if (ch === quote) {
-            return {
-                value,
-                end: i + 1
-            };
-        }
-        value += ch;
+function collectSensitiveConfigPaths(value, pathParts = []) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return [];
     }
-
-    return null;
-}
-
-function isConfigIdentifierStart(ch) {
-    return /[A-Za-z_$]/.test(ch);
-}
-
-function isConfigIdentifierPart(ch) {
-    return /[A-Za-z0-9_$]/.test(ch);
-}
-
-function skipConfigTrivia(text, index) {
-    let cursor = index;
-    while (cursor < text.length) {
-        const ch = text[cursor];
-        const next = text[cursor + 1];
-        if (/\s/.test(ch)) {
-            cursor += 1;
-            continue;
-        }
-        if (ch === '/' && next === '/') {
-            cursor += 2;
-            while (cursor < text.length && text[cursor] !== '\n') {
-                cursor += 1;
-            }
-            continue;
+    const result = [];
+    Object.entries(toPlainObject(value)).forEach(([key, item]) => {
+        const nextPath = pathParts.concat(key);
+        if (isSensitiveConfigKey(key)) {
+            result.push(nextPath);
+            return;
         }
-        if (ch === '/' && next === '*') {
-            cursor += 2;
-            while (cursor + 1 < text.length && !(text[cursor] === '*' && text[cursor + 1] === '/')) {
-                cursor += 1;
-            }
-            cursor = cursor + 1 < text.length ? cursor + 2 : text.length;
-            continue;
+        if (item && typeof item === 'object' && !Array.isArray(item)) {
+            result.push(...collectSensitiveConfigPaths(item, nextPath));
         }
-        break;
-    }
-    return cursor;
-}
-
-function scanConfigValueEnd(text, startIndex) {
-    let cursor = startIndex;
-    let stringQuote = '';
-    let lineComment = false;
-    let blockComment = false;
-    let depth = 0;
-
-    for (; cursor < text.length; cursor += 1) {
-        const ch = text[cursor];
-        const next = text[cursor + 1];
-
-        if (lineComment) {
-            if (ch === '\n') {
-                lineComment = false;
-            }
-            continue;
-        }
-        if (blockComment) {
-            if (ch === '*' && next === '/') {
-                blockComment = false;
-                cursor += 1;
-            }
-            continue;
-        }
-        if (stringQuote) {
-            if (ch === '\\') {
-                cursor += 1;
-                continue;
-            }
-            if (ch === stringQuote) {
-                stringQuote = '';
-            }
-            continue;
-        }
-
-        if (ch === '/' && next === '/') {
-            lineComment = true;
-            cursor += 1;
-            continue;
-        }
-        if (ch === '/' && next === '*') {
-            blockComment = true;
-            cursor += 1;
-            continue;
-        }
-        if (ch === '"' || ch === '\'') {
-            stringQuote = ch;
-            continue;
-        }
-        if (ch === '{' || ch === '[' || ch === '(') {
-            depth += 1;
-            continue;
-        }
-        if (ch === '}' || ch === ']' || ch === ')') {
-            if (depth === 0) {
-                break;
-            }
-            depth -= 1;
-            continue;
-        }
-        if (depth === 0 && ch === ',') {
-            break;
-        }
-    }
-
-    let end = cursor;
-    while (end > startIndex && /\s/.test(text[end - 1])) {
-        end -= 1;
-    }
-    return end;
-}
-
-function findConfigRootObjectStart(text) {
-    const start = skipConfigTrivia(String(text || ''), 0);
-    return text[start] === '{' ? start : -1;
-}
-
-function readConfigPropertyToken(text, startIndex) {
-    const ch = text[startIndex];
-    if (ch === '"' || ch === '\'') {
-        const token = readConfigQuotedString(text, startIndex);
-        if (!token) {
-            return null;
-        }
-        return token;
-    }
-    if (!isConfigIdentifierStart(ch)) {
-        return null;
-    }
-    let end = startIndex + 1;
-    while (end < text.length && isConfigIdentifierPart(text[end])) {
-        end += 1;
-    }
-    return {
-        value: text.slice(startIndex, end),
-        end
-    };
-}
-
-function findConfigObjectPropertyValueRange(text, objectStartIndex, propertyName) {
-    let cursor = skipConfigTrivia(text, objectStartIndex + 1);
-    while (cursor < text.length) {
-        cursor = skipConfigTrivia(text, cursor);
-        if (text[cursor] === '}') {
-            return null;
-        }
-        const token = readConfigPropertyToken(text, cursor);
-        if (!token) {
-            return null;
-        }
-        cursor = skipConfigTrivia(text, token.end);
-        if (text[cursor] !== ':') {
-            return null;
-        }
-        const valueStart = skipConfigTrivia(text, cursor + 1);
-        const valueEnd = scanConfigValueEnd(text, valueStart);
-        if (token.value === propertyName) {
-            return { start: valueStart, end: valueEnd };
-        }
-        cursor = skipConfigTrivia(text, valueEnd);
-        if (text[cursor] === ',') {
-            cursor += 1;
-            continue;
-        }
-        if (text[cursor] === '}') {
-            return null;
-        }
-    }
-    return null;
-}
-
-function findConfigValueRangeByPath(text, pathParts) {
-    if (!Array.isArray(pathParts) || pathParts.length === 0) {
-        return null;
-    }
-    let objectStart = findConfigRootObjectStart(text);
-    if (objectStart === -1) {
-        return null;
-    }
-    let range = null;
-    for (let i = 0; i < pathParts.length; i += 1) {
-        range = findConfigObjectPropertyValueRange(text, objectStart, pathParts[i]);
-        if (!range) {
-            return null;
-        }
-        if (i === pathParts.length - 1) {
-            return range;
-        }
-        const nextObjectStart = skipConfigTrivia(text, range.start);
-        if (text[nextObjectStart] !== '{') {
-            return null;
-        }
-        objectStart = nextObjectStart;
-    }
-    return range;
-}
-
-function collectSensitiveConfigPaths(value, pathParts = []) {
-    if (!value || typeof value !== 'object' || Array.isArray(value)) {
-        return [];
-    }
-    const result = [];
-    Object.entries(toPlainObject(value)).forEach(([key, item]) => {
-        const nextPath = pathParts.concat(key);
-        if (isSensitiveConfigKey(key)) {
-            result.push(nextPath);
-            return;
-        }
-        if (item && typeof item === 'object' && !Array.isArray(item)) {
-            result.push(...collectSensitiveConfigPaths(item, nextPath));
-        }
-    });
-    return result;
+    });
+    return result;
 }
 
 function collectSensitivePlaceholderPaths(value, pathParts = []) {
@@ -1894,13 +931,6 @@ function collectSensitivePlaceholderPaths(value, pathParts = []) {
     return result;
 }
 
-function applyConfigTextReplacements(text, replacements) {
-    return replacements
-        .slice()
-        .sort((a, b) => b.start - a.start)
-        .reduce((result, item) => `${result.slice(0, item.start)}${item.text}${result.slice(item.end)}`, text);
-}
-
 function buildConfigPathLabel(pathParts) {
     return (Array.isArray(pathParts) ? pathParts : []).join('.');
 }
@@ -1908,7 +938,7 @@ function buildConfigPathLabel(pathParts) {
 function maskWebConfigRaw(raw, parsed) {
     const text = String(raw || '');
     const replacements = collectSensitiveConfigPaths(parsed).map(pathParts => {
-        const range = findConfigValueRangeByPath(text, pathParts);
+        const range = findValueRangeByPath(text, pathParts);
         if (!range) {
             throw new Error(`敏感字段定位失败: ${buildConfigPathLabel(pathParts)}`);
         }
@@ -1918,7 +948,7 @@ function maskWebConfigRaw(raw, parsed) {
             text: JSON.stringify(WEB_CONFIG_KEEP_SECRET_PLACEHOLDER)
         };
     });
-    return applyConfigTextReplacements(text, replacements);
+    return applyTextReplacements(text, replacements);
 }
 
 function parseConfigRawObject(raw) {
@@ -1946,8 +976,8 @@ function restoreWebConfigSecrets(raw, snapshot) {
 
     const currentRaw = String(snapshot.raw || '');
     const replacements = placeholderPaths.map(pathParts => {
-        const editedRange = findConfigValueRangeByPath(text, pathParts);
-        const currentRange = findConfigValueRangeByPath(currentRaw, pathParts);
+        const editedRange = findValueRangeByPath(text, pathParts);
+        const currentRange = findValueRangeByPath(currentRaw, pathParts);
         if (!editedRange) {
             throw new Error(`敏感字段定位失败: ${buildConfigPathLabel(pathParts)}`);
         }
@@ -1961,7 +991,7 @@ function restoreWebConfigSecrets(raw, snapshot) {
         };
     });
 
-    return applyConfigTextReplacements(text, replacements);
+    return applyTextReplacements(text, replacements);
 }
 
 function redactConfigValue(value) {
@@ -2078,23 +1108,6 @@ function validateWebHostPath(hostPath) {
     }
 }
 
-function parseEnvEntry(entryText) {
-    const text = String(entryText || '');
-    const idx = text.indexOf('=');
-    if (idx <= 0) {
-        throw new Error(`env 格式应为 KEY=VALUE: ${text}`);
-    }
-    const key = text.slice(0, idx);
-    const value = text.slice(idx + 1);
-    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
-        throw new Error(`env key 非法: ${key}`);
-    }
-    if (/[\r\n\0]/.test(value) || /[;&|`$<>]/.test(value)) {
-        throw new Error(`env value 含非法字符: ${key}`);
-    }
-    return { key, value };
-}
-
 function normalizeEnvMap(envConfig, sourceLabel) {
     if (envConfig === undefined || envConfig === null) {
         return {};
@@ -2113,6 +1126,15 @@ function normalizeEnvMap(envConfig, sourceLabel) {
     return result;
 }
 
+function normalizeCliEnvMap(envList) {
+    const result = {};
+    for (const envText of (envList || [])) {
+        const parsed = parseEnvEntry(envText);
+        result[parsed.key] = parsed.value;
+    }
+    return result;
+}
+
 function normalizeStringArray(value, sourceLabel) {
     if (value === undefined || value === null) {
         return [];
@@ -2125,41 +1147,6 @@ function normalizeStringArray(value, sourceLabel) {
         .filter(Boolean);
 }
 
-function expandHomeAliasPath(filePath) {
-    const text = String(filePath || '').trim();
-    if (!text) {
-        return text;
-    }
-    const homeDir = os.homedir();
-    if (text === '~') {
-        return homeDir;
-    }
-    if (text.startsWith('~/')) {
-        return path.join(homeDir, text.slice(2));
-    }
-    if (text === '$HOME') {
-        return homeDir;
-    }
-    if (text.startsWith('$HOME/')) {
-        return path.join(homeDir, text.slice('$HOME/'.length));
-    }
-    return text;
-}
-
-function normalizeVolume(volume) {
-    const text = String(volume || '').trim();
-    if (!text.startsWith('~') && !text.startsWith('$HOME')) {
-        return text;
-    }
-    const separatorIndex = text.indexOf(':');
-    if (separatorIndex === -1) {
-        return expandHomeAliasPath(text);
-    }
-    const hostPath = text.slice(0, separatorIndex);
-    const rest = text.slice(separatorIndex);
-    return `${expandHomeAliasPath(hostPath)}${rest}`;
-}
-
 function parseEnvFileToArgs(filePath) {
     const resolvedPath = expandHomeAliasPath(filePath);
     if (!path.isAbsolute(resolvedPath)) {
@@ -2428,30 +1415,66 @@ function buildCreateRuntime(ctx, state, payload) {
     const hasConfigVolumes = hasOwn(config, 'volumes');
     const hasConfigPorts = hasOwn(config, 'ports');
 
+    const requestEnvMap = hasRequestEnv ? normalizeEnvMap(requestOptions.env, 'createOptions.env') : {};
+    const requestEnvList = Object.entries(requestEnvMap).map(([key, value]) => `${key}=${value}`);
+    const requestEnvFileList = hasRequestEnvFile ? normalizeStringArray(requestOptions.envFile, 'createOptions.envFile') : [];
+    const requestVolumeList = hasRequestVolumes ? normalizeStringArray(requestOptions.volumes, 'createOptions.volumes') : [];
+    const requestPortList = hasRequestPorts ? normalizeStringArray(requestOptions.ports, 'createOptions.ports') : [];
     const requestName = pickFirstString(requestOptions.containerName, body.name);
-    let containerName = pickFirstString(requestName, runConfig.containerName, config.containerName);
-    if (!containerName) {
-        containerName = `my-${ctx.formatDate()}`;
-    }
-    containerName = resolveNowTemplate(containerName, ctx.formatDate);
+
+    const resolvedBase = resolveRuntimeConfig({
+        cliOptions: {
+            hostPath: requestOptions.hostPath,
+            contName: requestName,
+            contPath: requestOptions.containerPath,
+            imageName: requestOptions.imageName,
+            imageVer: requestOptions.imageVersion,
+            env: requestEnvList,
+            envFile: requestEnvFileList,
+            volume: requestVolumeList,
+            port: requestPortList
+        },
+        globalConfig: config,
+        runConfig,
+        globalFirstConfig: {},
+        runFirstConfig: {},
+        defaults: {
+            hostPath: ctx.hostPath,
+            containerName: `my-${ctx.formatDate()}`,
+            containerPath: ctx.containerPath,
+            imageName: ctx.imageName,
+            imageVersion: ctx.imageVersion
+        },
+        envVars: {},
+        argv: [],
+        isServerMode: false,
+        isServerStopMode: false,
+        pickConfigValue: pickFirstString,
+        resolveContainerNameTemplate: value => resolveNowTemplate(value, ctx.formatDate),
+        normalizeCommandSuffix: value => {
+            const text = String(value || '').trim();
+            return text ? ` ${text}` : '';
+        },
+        normalizeJsonEnvMap: normalizeEnvMap,
+        normalizeCliEnvMap,
+        mergeArrayConfig: (globalValue, runValue, cliValue) => [...(globalValue || []), ...(runValue || []), ...(cliValue || [])],
+        normalizeVolume,
+        parseServerListen: () => ({ host: '', port: 0 })
+    });
+
+    const containerName = resolvedBase.containerName;
     validateContainerNameStrict(containerName);
 
-    const hostPath = pickFirstString(requestOptions.hostPath, runConfig.hostPath, config.hostPath, ctx.hostPath);
+    const hostPath = resolvedBase.hostPath;
     if (typeof ctx.validateHostPath === 'function') {
         ctx.validateHostPath(hostPath);
     } else {
         validateWebHostPath(hostPath);
     }
 
-    const containerPath = pickFirstString(
-        requestOptions.containerPath,
-        runConfig.containerPath,
-        config.containerPath,
-        ctx.containerPath,
-        hostPath
-    ) || hostPath;
-    const imageName = pickFirstString(requestOptions.imageName, runConfig.imageName, config.imageName, ctx.imageName);
-    const imageVersion = pickFirstString(requestOptions.imageVersion, runConfig.imageVersion, config.imageVersion, ctx.imageVersion);
+    const containerPath = resolvedBase.containerPath || hostPath;
+    const imageName = resolvedBase.imageName;
+    const imageVersion = resolvedBase.imageVersion;
 
     if (!/^[A-Za-z0-9][A-Za-z0-9._/:-]*$/.test(imageName)) {
         throw new Error(`imageName 非法: ${imageName}`);
@@ -2510,22 +1533,14 @@ function buildCreateRuntime(ctx, state, payload) {
     const hasRunEnv = hasOwn(runConfig, 'env');
     const hasRunEnvFile = hasOwn(runConfig, 'envFile');
     if (hasRequestEnv || hasRequestEnvFile || hasRunEnv || hasRunEnvFile || hasConfigEnv || hasConfigEnvFile) {
-        const configEnv = normalizeEnvMap(config.env, 'config.env');
-        const runEnv = normalizeEnvMap(runConfig.env, runName ? `runs.${runName}.env` : 'run.env');
-        const requestEnv = hasRequestEnv ? normalizeEnvMap(requestOptions.env, 'createOptions.env') : {};
-        const mergedEnv = { ...configEnv, ...runEnv, ...requestEnv };
         const envArgs = [];
-        Object.entries(mergedEnv).forEach(([key, value]) => {
+        Object.entries(resolvedBase.env).forEach(([key, value]) => {
             const parsed = parseEnvEntry(`${key}=${value}`);
             envArgs.push('--env', `${parsed.key}=${parsed.value}`);
         });
 
-        const envFileList = []
-            .concat(normalizeStringArray(config.envFile, 'config.envFile'))
-            .concat(normalizeStringArray(runConfig.envFile, runName ? `runs.${runName}.envFile` : 'run.envFile'))
-            .concat(hasRequestEnvFile ? normalizeStringArray(requestOptions.envFile, 'createOptions.envFile') : []);
         const envFileArgs = [];
-        envFileList.forEach(filePath => {
+        resolvedBase.envFile.forEach(filePath => {
             envFileArgs.push(...parseEnvFileToArgs(filePath));
         });
 
@@ -2535,12 +1550,8 @@ function buildCreateRuntime(ctx, state, payload) {
     let containerVolumes = Array.isArray(ctx.containerVolumes) ? ctx.containerVolumes.slice() : [];
     const hasRunVolumes = hasOwn(runConfig, 'volumes');
     if (hasRequestVolumes || hasRunVolumes || hasConfigVolumes) {
-        const volumeList = []
-            .concat(normalizeStringArray(config.volumes, 'config.volumes'))
-            .concat(normalizeStringArray(runConfig.volumes, runName ? `runs.${runName}.volumes` : 'run.volumes'))
-            .concat(hasRequestVolumes ? normalizeStringArray(requestOptions.volumes, 'createOptions.volumes') : []);
         containerVolumes = [];
-        volumeList.forEach(volume => {
+        resolvedBase.volumes.forEach(volume => {
             containerVolumes.push('--volume', normalizeVolume(volume));
         });
     }
@@ -2548,12 +1559,8 @@ function buildCreateRuntime(ctx, state, payload) {
     let containerPorts = Array.isArray(ctx.containerPorts) ? ctx.containerPorts.slice() : [];
     const hasRunPorts = hasOwn(runConfig, 'ports');
     if (hasRequestPorts || hasRunPorts || hasConfigPorts) {
-        const portList = []
-            .concat(normalizeStringArray(config.ports, 'config.ports'))
-            .concat(normalizeStringArray(runConfig.ports, runName ? `runs.${runName}.ports` : 'run.ports'))
-            .concat(hasRequestPorts ? normalizeStringArray(requestOptions.ports, 'createOptions.ports') : []);
         containerPorts = [];
-        portList.forEach(port => {
+        resolvedBase.ports.forEach(port => {
             containerPorts.push('--publish', port);
         });
     }
@@ -2716,229 +1723,6 @@ async function ensureWebContainer(ctx, state, containerInput, messageSessionRef
     }
 }
 
-async function execCommandInWebContainer(ctx, containerName, command, options = {}) {
-    const opts = options && typeof options === 'object' ? options : {};
-    const agentProgram = typeof opts.agentProgram === 'string' ? opts.agentProgram : '';
-    return await new Promise((resolve, reject) => {
-        const process = spawn(
-            ctx.dockerCmd,
-            ['exec', containerName, '/bin/bash', '-lc', command],
-            { stdio: ['ignore', 'pipe', 'pipe'] }
-        );
-
-        const MAX_RAW_OUTPUT_CHARS = 32 * 1024 * 1024;
-        let stdoutOutput = '';
-        let stderrOutput = '';
-        let stdoutTruncated = false;
-        let stderrTruncated = false;
-
-        function appendChunk(chunk, target) {
-            if (!chunk) return;
-            const text = chunk.toString('utf-8');
-            if (!text) return;
-            if (target.value.length >= MAX_RAW_OUTPUT_CHARS) {
-                target.truncated = true;
-                return;
-            }
-            const remain = MAX_RAW_OUTPUT_CHARS - target.value.length;
-            if (text.length > remain) {
-                target.value += text.slice(0, remain);
-                target.truncated = true;
-                return;
-            }
-            target.value += text;
-        }
-
-        process.stdout.on('data', chunk => appendChunk(chunk, {
-            get value() { return stdoutOutput; },
-            set value(nextValue) { stdoutOutput = nextValue; },
-            get truncated() { return stdoutTruncated; },
-            set truncated(nextValue) { stdoutTruncated = nextValue; }
-        }));
-        process.stderr.on('data', chunk => appendChunk(chunk, {
-            get value() { return stderrOutput; },
-            set value(nextValue) { stderrOutput = nextValue; },
-            get truncated() { return stderrTruncated; },
-            set truncated(nextValue) { stderrTruncated = nextValue; }
-        }));
-
-        process.on('error', reject);
-        process.on('close', code => {
-            const exitCode = typeof code === 'number' ? code : 1;
-            const clippedStdout = stdoutTruncated ? `${stdoutOutput}\n...[stdout-truncated]` : stdoutOutput;
-            const clippedStderr = stderrTruncated ? `${stderrOutput}\n...[stderr-truncated]` : stderrOutput;
-            const clippedRaw = `${clippedStdout}${clippedStdout && clippedStderr ? '\n' : ''}${clippedStderr}`;
-            const extractedAgentMessage = extractAgentMessageFromStructuredOutput(agentProgram, clippedStdout);
-            const cleanOutputSource = extractedAgentMessage || clippedRaw;
-            const output = clipText(stripAnsi(cleanOutputSource).trim() || '(无输出)');
-            resolve({ exitCode, output });
-        });
-    });
-}
-
-async function execAgentInWebContainerStream(ctx, state, sessionRefOrContainerName, command, options = {}) {
-    const opts = options && typeof options === 'object' ? options : {};
-    const sessionRef = typeof sessionRefOrContainerName === 'string'
-        ? { containerName: sessionRefOrContainerName, agentId: WEB_DEFAULT_AGENT_ID }
-        : sessionRefOrContainerName;
-    const sessionKey = buildWebSessionKey(sessionRef.containerName, sessionRef.agentId);
-    const agentProgram = typeof opts.agentProgram === 'string' ? opts.agentProgram : '';
-    const onEvent = typeof opts.onEvent === 'function' ? opts.onEvent : () => {};
-    const process = spawn(
-        ctx.dockerCmd,
-        ['exec', sessionRef.containerName, '/bin/bash', '-lc', command],
-        { stdio: ['ignore', 'pipe', 'pipe'] }
-    );
-
-    const runState = {
-        containerName: sessionRef.containerName,
-        sessionKey,
-        process,
-        command,
-        startedAt: new Date().toISOString(),
-        stopping: false
-    };
-    state.agentRuns.set(sessionRef.containerName, runState);
-
-    return await new Promise((resolve, reject) => {
-        const MAX_RAW_OUTPUT_CHARS = 32 * 1024 * 1024;
-        let stdoutOutput = '';
-        let stderrOutput = '';
-        let stdoutTruncated = false;
-        let stderrTruncated = false;
-        let stdoutPending = '';
-        let stderrPending = '';
-        const structuredTraceState = {
-            toolNamesById: new Map()
-        };
-        let contentDeltaAccumulator = '';
-        function appendChunk(chunk, target) {
-            if (!chunk) return;
-            const text = chunk.toString('utf-8');
-            if (!text) return;
-            if (target.value.length >= MAX_RAW_OUTPUT_CHARS) {
-                target.truncated = true;
-                return;
-            }
-            const remain = MAX_RAW_OUTPUT_CHARS - target.value.length;
-            if (text.length > remain) {
-                target.value += text.slice(0, remain);
-                target.truncated = true;
-                return;
-            }
-            target.value += text;
-        }
-
-        function emitStdoutTraceLine(line) {
-            const rawLine = String(line || '').trim();
-            if (!rawLine) {
-                return;
-            }
-            if (agentProgram === 'claude' || agentProgram === 'gemini' || agentProgram === 'codex' || agentProgram === 'opencode') {
-                const payload = parseJsonObjectLine(rawLine);
-                if (payload) {
-                    const traceEvents = prepareStructuredTraceEvents(agentProgram, payload, structuredTraceState);
-                    traceEvents.forEach(traceEvent => {
-                        if (!traceEvent || !traceEvent.text) {
-                            return;
-                        }
-                        onEvent({
-                            type: 'trace',
-                            stream: 'stdout',
-                            text: traceEvent.text,
-                            traceEvent
-                        });
-                    });
-                    const deltaContent = extractContentDeltaFromPayload(agentProgram, payload, structuredTraceState);
-                    if (deltaContent !== null) {
-                        if (deltaContent.reset) {
-                            contentDeltaAccumulator = deltaContent.text;
-                        } else {
-                            contentDeltaAccumulator += deltaContent.text;
-                        }
-                        onEvent({
-                            type: 'content_delta',
-                            content: contentDeltaAccumulator
-                        });
-                    }
-                    return;
-                }
-                if (agentProgram === 'codex' && (/^OpenAI Codex\b/.test(rawLine) || /^tokens used\b/i.test(rawLine))) {
-                    return;
-                }
-            }
-            onEvent({ type: 'trace', stream: 'stdout', text: rawLine });
-        }
-
-        function emitStderrTraceLine(line) {
-            const rawLine = String(line || '').trim();
-            if (!rawLine) {
-                return;
-            }
-            onEvent({ type: 'trace', stream: 'stderr', text: `[stderr] ${rawLine}` });
-        }
-
-        function drainLines(text, carry, handleLine) {
-            let pending = carry + String(text || '');
-            let newlineIndex = pending.indexOf('\n');
-            while (newlineIndex !== -1) {
-                const line = pending.slice(0, newlineIndex).replace(/\r$/, '');
-                handleLine(line);
-                pending = pending.slice(newlineIndex + 1);
-                newlineIndex = pending.indexOf('\n');
-            }
-            return pending;
-        }
-
-        process.stdout.on('data', chunk => {
-            appendChunk(chunk, {
-                get value() { return stdoutOutput; },
-                set value(nextValue) { stdoutOutput = nextValue; },
-                get truncated() { return stdoutTruncated; },
-                set truncated(nextValue) { stdoutTruncated = nextValue; }
-            });
-            stdoutPending = drainLines(chunk.toString('utf-8'), stdoutPending, emitStdoutTraceLine);
-        });
-        process.stderr.on('data', chunk => {
-            appendChunk(chunk, {
-                get value() { return stderrOutput; },
-                set value(nextValue) { stderrOutput = nextValue; },
-                get truncated() { return stderrTruncated; },
-                set truncated(nextValue) { stderrTruncated = nextValue; }
-            });
-            stderrPending = drainLines(chunk.toString('utf-8'), stderrPending, emitStderrTraceLine);
-        });
-
-        process.on('error', error => {
-            state.agentRuns.delete(sessionRef.containerName);
-            reject(error);
-        });
-        process.on('close', code => {
-            state.agentRuns.delete(sessionRef.containerName);
-            if (stdoutPending) {
-                emitStdoutTraceLine(stdoutPending);
-                stdoutPending = '';
-            }
-            if (stderrPending) {
-                emitStderrTraceLine(stderrPending);
-                stderrPending = '';
-            }
-            const exitCode = typeof code === 'number' ? code : 1;
-            const clippedStdout = stdoutTruncated ? `${stdoutOutput}\n...[stdout-truncated]` : stdoutOutput;
-            const clippedStderr = stderrTruncated ? `${stderrOutput}\n...[stderr-truncated]` : stderrOutput;
-            const clippedRaw = `${clippedStdout}${clippedStdout && clippedStderr ? '\n' : ''}${clippedStderr}`;
-            const extractedAgentMessage = extractAgentMessageFromStructuredOutput(agentProgram, clippedStdout);
-            const cleanOutputSource = extractedAgentMessage || clippedRaw;
-            const output = clipText(stripAnsi(cleanOutputSource).trim() || '(无输出)');
-            resolve({
-                exitCode,
-                output,
-                interrupted: exitCode !== 0 && runState.stopping === true
-            });
-        });
-    });
-}
-
 function readRequestBody(req) {
     return new Promise((resolve, reject) => {
         let body = '';
@@ -2979,20 +1763,6 @@ function sendNdjson(res, payload) {
     res.write(`${JSON.stringify(payload)}\n`);
 }
 
-function stopWebAgentRun(state, containerName) {
-    const runState = state.agentRuns.get(containerName);
-    if (!runState || !runState.process || runState.process.killed) {
-        return false;
-    }
-    runState.stopping = true;
-    try {
-        runState.process.kill('SIGTERM');
-    } catch (e) {
-        return false;
-    }
-    return true;
-}
-
 function sendHtml(res, statusCode, html, extraHeaders = {}) {
     res.writeHead(statusCode, {
         'Content-Type': 'text/html; charset=utf-8',
@@ -3218,277 +1988,6 @@ function loadTemplate(name) {
     return fs.readFileSync(filePath, 'utf-8');
 }
 
-function toPositiveInt(value, fallback) {
-    const parsed = Number.parseInt(value, 10);
-    if (!Number.isFinite(parsed) || parsed <= 0) {
-        return fallback;
-    }
-    return parsed;
-}
-
-function normalizeTerminalSize(cols, rows) {
-    return {
-        cols: Math.max(WEB_TERMINAL_MIN_COLS, toPositiveInt(cols, WEB_TERMINAL_DEFAULT_COLS)),
-        rows: Math.max(WEB_TERMINAL_MIN_ROWS, toPositiveInt(rows, WEB_TERMINAL_DEFAULT_ROWS))
-    };
-}
-
-function getUpgradeStatusText(statusCode) {
-    if (statusCode === 400) return 'Bad Request';
-    if (statusCode === 401) return 'Unauthorized';
-    if (statusCode === 404) return 'Not Found';
-    if (statusCode === 429) return 'Too Many Requests';
-    if (statusCode === 500) return 'Internal Server Error';
-    return 'Error';
-}
-
-function sendWebSocketUpgradeError(socket, statusCode, message) {
-    const body = String(message || getUpgradeStatusText(statusCode));
-    const reason = getUpgradeStatusText(statusCode);
-    if (!socket.destroyed) {
-        socket.write(
-            `HTTP/1.1 ${statusCode} ${reason}\r\n` +
-            'Content-Type: text/plain; charset=utf-8\r\n' +
-            'Connection: close\r\n' +
-            `Content-Length: ${Buffer.byteLength(body, 'utf-8')}\r\n` +
-            '\r\n' +
-            body
-        );
-    }
-    socket.destroy();
-}
-
-function sendTerminalEvent(ws, type, payload = {}) {
-    if (!ws || ws.readyState !== WebSocket.OPEN) {
-        return;
-    }
-    ws.send(JSON.stringify({ type, ...payload }));
-}
-
-function spawnWebTerminalProcess(ctx, containerName, cols, rows) {
-    const terminalBootstrap = [
-        'MANYOYO_WEB_BASHRC="$(mktemp /tmp/manyoyo-web-bashrc.XXXXXX 2>/dev/null || mktemp)"',
-        'cat > "$MANYOYO_WEB_BASHRC" <<\'EOF_MANYOYO_RC\'',
-        'if [ -f /etc/bash.bashrc ]; then',
-        '    . /etc/bash.bashrc',
-        'fi',
-        'if [ -f ~/.bashrc ]; then',
-        '    . ~/.bashrc',
-        'fi',
-        'if [ -n "${MANYOYO_TERM_COLS:-}" ] && [ -n "${MANYOYO_TERM_ROWS:-}" ]; then',
-        '    COLUMNS="$MANYOYO_TERM_COLS"',
-        '    LINES="$MANYOYO_TERM_ROWS"',
-        '    export COLUMNS LINES',
-        '    stty cols "$MANYOYO_TERM_COLS" rows "$MANYOYO_TERM_ROWS" >/dev/null 2>&1 || true',
-        'fi',
-        'EOF_MANYOYO_RC',
-        'chmod 600 "$MANYOYO_WEB_BASHRC" >/dev/null 2>&1 || true',
-        'if command -v script >/dev/null 2>&1; then',
-        '  exec script -qefc "/bin/bash --rcfile $MANYOYO_WEB_BASHRC -i" /dev/null;',
-        'fi;',
-        'if command -v python3 >/dev/null 2>&1; then',
-        '  exec python3 -c \'import os, pty; pty.spawn(["/bin/bash","--rcfile",os.environ.get("MANYOYO_WEB_BASHRC","/dev/null"),"-i"])\';',
-        'fi;',
-        'if command -v python >/dev/null 2>&1; then',
-        '  exec python -c \'import os, pty; pty.spawn(["/bin/bash","--rcfile",os.environ.get("MANYOYO_WEB_BASHRC","/dev/null"),"-i"])\';',
-        'fi;',
-        'echo "[manyoyo] 容器内未找到 script/python，终端将降级为非 TTY 模式" >&2;',
-        'exec /bin/bash --rcfile "$MANYOYO_WEB_BASHRC" -i'
-    ].join('\n');
-
-    const termValue = process.env.TERM && process.env.TERM !== 'dumb' ? process.env.TERM : 'xterm-256color';
-    const colorTermValue = process.env.COLORTERM || 'truecolor';
-    const dockerExecArgs = [
-        'exec',
-        '-i',
-        '-e', `TERM=${termValue}`,
-        '-e', `COLORTERM=${colorTermValue}`,
-        '-e', `MANYOYO_TERM_COLS=${String(cols)}`,
-        '-e', `MANYOYO_TERM_ROWS=${String(rows)}`,
-        containerName,
-        '/bin/bash',
-        '-lc',
-        terminalBootstrap
-    ];
-
-    return spawn(ctx.dockerCmd, dockerExecArgs, { stdio: ['pipe', 'pipe', 'pipe'] });
-}
-
-function bindTerminalWebSocket(ctx, state, ws, containerName, cols, rows) {
-    const sessionId = `${containerName}-${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
-    const ptyProcess = spawnWebTerminalProcess(ctx, containerName, cols, rows);
-    const session = {
-        id: sessionId,
-        containerName,
-        ptyProcess,
-        closing: false
-    };
-
-    state.terminalSessions.set(sessionId, session);
-    sendTerminalEvent(ws, 'status', {
-        phase: 'ready',
-        sessionId,
-        containerName,
-        cols,
-        rows
-    });
-
-    const cleanup = () => {
-        if (session.closing) {
-            return;
-        }
-        session.closing = true;
-        state.terminalSessions.delete(sessionId);
-        if (ptyProcess && !ptyProcess.killed) {
-            ptyProcess.kill('SIGTERM');
-            setTimeout(() => {
-                if (!ptyProcess.killed) {
-                    ptyProcess.kill('SIGKILL');
-                }
-            }, WEB_TERMINAL_FORCE_KILL_MS);
-        }
-    };
-
-    ptyProcess.stdout.on('data', chunk => {
-        sendTerminalEvent(ws, 'output', { data: chunk.toString('utf-8') });
-    });
-
-    ptyProcess.stderr.on('data', chunk => {
-        sendTerminalEvent(ws, 'output', { data: chunk.toString('utf-8') });
-    });
-
-    ptyProcess.on('error', err => {
-        sendTerminalEvent(ws, 'error', {
-            error: err && err.message ? err.message : '终端进程启动失败'
-        });
-    });
-
-    ptyProcess.on('close', (code, signal) => {
-        sendTerminalEvent(ws, 'status', {
-            phase: 'closed',
-            code: typeof code === 'number' ? code : null,
-            signal: signal || null
-        });
-        cleanup();
-        if (ws.readyState === WebSocket.OPEN) {
-            ws.close();
-        }
-    });
-
-    ws.on('message', raw => {
-        let payload = null;
-        try {
-            payload = JSON.parse(raw.toString('utf-8'));
-        } catch (e) {
-            payload = {
-                type: 'input',
-                data: raw.toString('utf-8')
-            };
-        }
-        if (!payload || typeof payload !== 'object') {
-            return;
-        }
-
-        if (payload.type === 'input' && typeof payload.data === 'string' && payload.data.length) {
-            ptyProcess.stdin.write(payload.data);
-            return;
-        }
-
-        if (payload.type === 'resize') {
-            // 当前后端不直接驱动 docker exec 的 TTY 动态 resize，保留事件以便后续扩展。
-            return;
-        }
-
-        if (payload.type === 'close') {
-            ws.close();
-        }
-    });
-
-    ws.on('close', cleanup);
-    ws.on('error', cleanup);
-}
-
-async function handleWebAuthRoutes(req, res, pathname, ctx, state) {
-    if (req.method === 'GET' && pathname === '/favicon.ico') {
-        res.writeHead(204, { 'Cache-Control': 'no-store' });
-        res.end();
-        return true;
-    }
-
-    if (req.method === 'GET' && pathname === '/auth/login') {
-        sendHtml(res, 200, loadTemplate('login.html'));
-        return true;
-    }
-
-    const authFrontendMatch = pathname.match(/^\/auth\/frontend\/([A-Za-z0-9._-]+)$/);
-    if (req.method === 'GET' && authFrontendMatch) {
-        const assetName = authFrontendMatch[1];
-        if (!(assetName === 'login.css' || assetName === 'login.js')) {
-            sendHtml(res, 404, '<h1>404 Not Found</h1>');
-            return true;
-        }
-        sendStaticAsset(res, assetName);
-        return true;
-    }
-
-    if (req.method === 'POST' && pathname === '/auth/login') {
-        const payload = await readJsonBody(req);
-        const username = String(payload.username || '').trim();
-        const password = String(payload.password || '');
-
-        if (!username || !password) {
-            sendJson(res, 400, { error: '用户名和密码不能为空' });
-            return true;
-        }
-
-        const userOk = secureStringEqual(username, ctx.authUser);
-        const passOk = secureStringEqual(password, ctx.authPass);
-        if (!(userOk && passOk)) {
-            sendJson(res, 401, { error: '用户名或密码错误' });
-            return true;
-        }
-
-        const sessionId = createWebAuthSession(state, username);
-        sendJson(
-            res,
-            200,
-            { ok: true, username },
-            { 'Set-Cookie': getWebAuthCookie(sessionId) }
-        );
-        return true;
-    }
-
-    if (req.method === 'POST' && pathname === '/auth/logout') {
-        clearWebAuthSession(state, req);
-        sendJson(
-            res,
-            200,
-            { ok: true },
-            { 'Set-Cookie': getWebAuthClearCookie() }
-        );
-        return true;
-    }
-
-    return false;
-}
-
-function sendWebUnauthorized(res, pathname) {
-    if (pathname.startsWith('/api/') || pathname.startsWith('/auth/')) {
-        sendJson(res, 401, { error: 'UNAUTHORIZED' });
-        return;
-    }
-    if (pathname === '/' || pathname === '') {
-        sendRedirect(res, 302, '/auth/login', { 'Set-Cookie': getWebAuthClearCookie() });
-        return;
-    }
-    sendHtml(
-        res,
-        401,
-        loadTemplate('login.html'),
-        { 'Set-Cookie': getWebAuthClearCookie() }
-    );
-}
-
 async function handleWebApi(req, res, pathname, ctx, state) {
     // [P2-03] 对非只读请求校验自定义头，防止 CSRF 攻击
     // 跨站请求无法设置自定义头（浏览器同源策略），合法前端请求统一携带此头
@@ -3498,823 +1997,121 @@ async function handleWebApi(req, res, pathname, ctx, state) {
             return true;
         }
     }
-    const routes = [
-        {
-            method: 'GET',
-            match: currentPath => currentPath === '/api/fs/directories' ? [] : null,
-            handler: async () => {
-                const requestUrl = new URL(req.url || '/api/fs/directories', 'http://localhost');
-                const requestedPath = expandHomeAliasPath(String(requestUrl.searchParams.get('path') || '').trim() || os.homedir());
-                const requestedBasePath = expandHomeAliasPath(String(requestUrl.searchParams.get('basePath') || '').trim());
-                const realPath = fs.realpathSync(requestedPath);
-                if (!fs.statSync(realPath).isDirectory()) {
-                    sendJson(res, 400, { error: `目录不存在: ${realPath}` });
-                    return;
-                }
-
-                let realBasePath = '';
-                if (requestedBasePath) {
-                    realBasePath = fs.realpathSync(requestedBasePath);
-                    if (!fs.statSync(realBasePath).isDirectory()) {
-                        sendJson(res, 400, { error: `basePath 不是目录: ${realBasePath}` });
-                        return;
-                    }
-                    const relativeToBase = path.relative(realBasePath, realPath);
-                    if (relativeToBase.startsWith('..') || path.isAbsolute(relativeToBase)) {
-                        sendJson(res, 400, { error: '目录超出 basePath 范围' });
-                        return;
-                    }
-                }
-
-                const parentPath = realBasePath
-                    ? (realPath === realBasePath ? '' : path.dirname(realPath))
-                    : (realPath === path.parse(realPath).root ? '' : path.dirname(realPath));
-                const entries = fs.readdirSync(realPath, { withFileTypes: true })
-                    .filter(entry => entry && entry.isDirectory())
-                    .map(entry => ({
-                        name: entry.name,
-                        path: path.join(realPath, entry.name)
-                    }))
-                    .sort((a, b) => a.name.localeCompare(b.name, 'zh-CN'));
-
-                sendJson(res, 200, {
-                    currentPath: realPath,
-                    basePath: realBasePath || '',
-                    parentPath,
-                    entries
-                });
-            }
-        },
-        {
-            method: 'GET',
-            match: currentPath => currentPath === '/api/config' ? [] : null,
-            handler: async () => {
-                const snapshot = readWebConfigSnapshot(state.webConfigPath);
-                sendJson(res, 200, buildSafeWebConfigSnapshot(snapshot, ctx));
-            }
-        },
-        {
-            method: 'PUT',
-            match: currentPath => currentPath === '/api/config' ? [] : null,
-            handler: async () => {
-                const payload = await readJsonBody(req);
-                const raw = typeof payload.raw === 'string' ? payload.raw : '';
-                if (!raw.trim()) {
-                    sendJson(res, 400, { error: '配置内容不能为空' });
-                    return;
-                }
-
-                const currentSnapshot = readWebConfigSnapshot(state.webConfigPath);
-                let finalRaw = raw;
-                let parsed = null;
-                try {
-                    finalRaw = restoreWebConfigSecrets(raw, currentSnapshot);
-                    parsed = parseAndValidateConfigRaw(finalRaw);
-                } catch (e) {
-                    sendJson(res, 400, { error: '配置格式错误', detail: e.message || '解析失败' });
-                    return;
-                }
-
-                const savePath = path.resolve(state.webConfigPath);
-                fs.mkdirSync(path.dirname(savePath), { recursive: true });
-                fs.writeFileSync(savePath, finalRaw, 'utf-8');
-
-                sendJson(res, 200, {
-                    saved: true,
-                    path: savePath,
-                    defaults: buildConfigDefaults(ctx, parsed)
-                });
-            }
-        },
-        {
-            method: 'GET',
-            match: currentPath => currentPath === '/api/sessions' ? [] : null,
-            handler: async () => {
-                const containerMap = listWebManyoyoContainers(ctx);
-                const names = new Set([
-                    ...Object.keys(containerMap),
-                    ...listWebHistorySessionNames(state.webHistoryDir, ctx.isValidContainerName)
-                ]);
-
-                const sessions = Array.from(names)
-                    .flatMap(name => {
-                        const history = loadWebSessionHistory(state.webHistoryDir, name);
-                        return listWebAgentSessions(history, { includeSyntheticDefault: true })
-                            .map(agentSession => buildSessionSummary(ctx, state, containerMap, {
-                                containerName: name,
-                                agentId: agentSession.agentId
-                            }))
-                            .filter(Boolean);
-                    })
-                    .sort((a, b) => {
-                        const timeA = a.updatedAt ? new Date(a.updatedAt).getTime() : 0;
-                        const timeB = b.updatedAt ? new Date(b.updatedAt).getTime() : 0;
-                        return timeB - timeA;
-                    });
-
-                sendJson(res, 200, { sessions });
-            }
-        },
-        {
-            method: 'POST',
-            match: currentPath => currentPath === '/api/sessions' ? [] : null,
-            handler: async () => {
-                const payload = await readJsonBody(req);
-                let runtime = null;
-                try {
-                    runtime = buildCreateRuntime(ctx, state, payload);
-                } catch (e) {
-                    sendJson(res, 400, { error: e.message || '创建参数错误' });
-                    return;
-                }
-
-                await ensureWebContainer(ctx, state, runtime);
-                setWebSessionAgentPromptCommand(state.webHistoryDir, runtime.containerName, runtime.agentPromptCommand);
-                patchWebSessionHistory(state.webHistoryDir, runtime.containerName, {
-                    applied: runtime.applied
-                });
-                sendJson(res, 200, { name: runtime.containerName, applied: runtime.applied });
-            }
-        },
-        {
-            method: 'POST',
-            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/agents$/),
-            handler: async match => {
-                const sessionRef = getValidSessionRef(ctx, res, match[1]);
-                if (!sessionRef) {
-                    return;
-                }
-                const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
-                const agentSession = createWebAgentSession(history);
-                saveWebSessionHistory(state.webHistoryDir, sessionRef.containerName, history);
-                sendJson(res, 200, {
-                    name: buildWebSessionKey(sessionRef.containerName, agentSession.agentId),
-                    containerName: sessionRef.containerName,
-                    agentId: agentSession.agentId,
-                    agentName: agentSession.agentName
-                });
-            }
-        },
-        {
-            method: 'GET',
-            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/messages$/),
-            handler: async match => {
-                const sessionRef = getValidSessionRef(ctx, res, match[1]);
-                if (!sessionRef) {
-                    return;
-                }
-                const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
-                const agentSession = getWebAgentSession(history, sessionRef.agentId)
-                    || createEmptyWebAgentSession(sessionRef.agentId);
-                sendJson(res, 200, {
-                    name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId),
-                    containerName: sessionRef.containerName,
-                    agentId: sessionRef.agentId,
-                    messages: agentSession.messages
-                });
-            }
-        },
-        {
-            method: 'GET',
-            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/detail$/),
-            handler: async match => {
-                const sessionRef = getValidSessionRef(ctx, res, match[1]);
-                if (!sessionRef) {
-                    return;
-                }
-
-                const containerMap = listWebManyoyoContainers(ctx);
-                const detail = buildSessionDetail(ctx, state, containerMap, sessionRef);
-                sendJson(res, 200, { name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId), detail });
-            }
-        },
-        {
-            method: 'PUT',
-            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/agent-template$/),
-            handler: async match => {
-                const sessionRef = getValidSessionRef(ctx, res, match[1]);
-                if (!sessionRef) {
-                    return;
-                }
-
-                let payload = null;
-                try {
-                    payload = await readJsonBody(req);
-                } catch (e) {
-                    sendJson(res, 400, { error: e.message || '请求参数错误' });
-                    return;
-                }
-                const normalizedPayload = payload && typeof payload === 'object' && !Array.isArray(payload) ? payload : {};
-                const hasContainerTemplate = hasOwn(normalizedPayload, 'containerAgentPromptCommand');
-                const hasAgentOverride = hasOwn(normalizedPayload, 'agentPromptCommandOverride');
-                if (!hasContainerTemplate && !hasAgentOverride) {
-                    sendJson(res, 400, { error: '至少提供一个模板字段' });
-                    return;
-                }
-                if (hasAgentOverride && sessionRef.agentId === WEB_DEFAULT_AGENT_ID) {
-                    sendJson(res, 400, { error: '默认 AGENT 不支持单独覆盖模板，请直接修改容器模板' });
-                    return;
-                }
-
-                try {
-                    if (hasContainerTemplate) {
-                        setWebSessionAgentPromptCommand(
-                            state.webHistoryDir,
-                            sessionRef.containerName,
-                            normalizedPayload.containerAgentPromptCommand
-                        );
-                    }
-                    if (hasAgentOverride) {
-                        setWebAgentSessionPromptCommand(
-                            state.webHistoryDir,
-                            sessionRef,
-                            normalizedPayload.agentPromptCommandOverride
-                        );
-                    }
-                } catch (e) {
-                    sendJson(res, 400, { error: e.message || '保存 Agent 模板失败' });
-                    return;
-                }
-
-                const containerMap = listWebManyoyoContainers(ctx);
-                const detail = buildSessionDetail(ctx, state, containerMap, sessionRef);
-                sendJson(res, 200, {
-                    saved: true,
-                    name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId),
-                    detail
-                });
-            }
-        },
-        {
-            method: 'POST',
-            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/run$/),
-            handler: async match => {
-                const sessionRef = getValidSessionRef(ctx, res, match[1]);
-                if (!sessionRef) {
-                    return;
-                }
-
-                const payload = await readJsonBody(req);
-                const command = (payload.command || '').trim();
-                if (!command) {
-                    sendJson(res, 400, { error: 'command 不能为空' });
-                    return;
-                }
-
-                await ensureWebContainer(ctx, state, sessionRef.containerName, sessionRef);
-                appendWebSessionMessage(state.webHistoryDir, sessionRef, 'user', command);
-                const result = await execCommandInWebContainer(ctx, sessionRef.containerName, command);
-                appendWebSessionMessage(
-                    state.webHistoryDir,
-                    sessionRef,
-                    'assistant',
-                    result.output,
-                    { exitCode: result.exitCode }
-                );
-                sendJson(res, 200, { exitCode: result.exitCode, output: result.output });
-            }
-        },
-        {
-            method: 'POST',
-            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/agent$/),
-            handler: async match => {
-                const sessionRef = getValidSessionRef(ctx, res, match[1]);
-                if (!sessionRef) {
-                    return;
-                }
-
-                const payload = await readJsonBody(req);
-                const prompt = (payload.prompt || '').trim();
-                if (!prompt) {
-                    sendJson(res, 400, { error: 'prompt 不能为空' });
-                    return;
-                }
-
-                let prepared = null;
-                try {
-                    prepared = await prepareWebAgentExecution(ctx, state, sessionRef, prompt);
-                } catch (e) {
-                    sendJson(res, 400, { error: e && e.message ? e.message : 'Agent 执行准备失败' });
-                    return;
-                }
-
-                const { agentSession, agentMeta, command, contextMode, resumeAttempted, resumeSucceeded, resumeError } = prepared;
-                appendWebSessionMessage(state.webHistoryDir, sessionRef, 'user', prompt, {
-                    mode: 'agent',
-                    contextMode
-                });
-                const result = await execCommandInWebContainer(ctx, sessionRef.containerName, command, {
-                    agentProgram: agentMeta.agentProgram
-                });
-                finalizeWebAgentExecution(state, sessionRef, agentSession, agentMeta, {
-                    contextMode,
-                    resumeAttempted,
-                    resumeSucceeded,
-                    resumeError
-                }, result);
-                sendJson(res, 200, {
-                    exitCode: result.exitCode,
-                    output: result.output,
-                    contextMode,
-                    resumeAttempted,
-                    resumeSucceeded,
-                    interrupted: result.interrupted === true
-                });
-            }
-        },
-        {
-            method: 'POST',
-            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/agent\/stream$/),
-            handler: async match => {
-                const sessionRef = getValidSessionRef(ctx, res, match[1]);
-                if (!sessionRef) {
-                    return;
-                }
-
-                const payload = await readJsonBody(req);
-                const prompt = (payload.prompt || '').trim();
-                if (!prompt) {
-                    sendJson(res, 400, { error: 'prompt 不能为空' });
-                    return;
-                }
-                if (state.agentRuns.has(sessionRef.containerName)) {
-                    sendJson(res, 409, { error: '当前会话已有运行中的 agent 任务' });
-                    return;
-                }
-
-                let prepared = null;
-                try {
-                    prepared = await prepareWebAgentExecution(ctx, state, sessionRef, prompt);
-                } catch (e) {
-                    sendJson(res, 400, { error: e && e.message ? e.message : 'Agent 执行准备失败' });
-                    return;
-                }
-
-                const { agentSession, agentMeta, command, contextMode, resumeAttempted, resumeSucceeded, resumeError } = prepared;
-                const traceLines = ['[执行过程]'];
-                const traceEvents = [];
-                appendWebSessionMessage(state.webHistoryDir, sessionRef, 'user', prompt, {
-                    mode: 'agent',
-                    contextMode
-                });
-
-                res.writeHead(200, {
-                    'Content-Type': 'application/x-ndjson; charset=utf-8',
-                    'Cache-Control': 'no-store',
-                    'X-Accel-Buffering': 'no'
-                });
-                sendNdjson(res, {
-                    type: 'meta',
-                    containerName: sessionRef.containerName,
-                    sessionName: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId),
-                    contextMode,
-                    resumeAttempted,
-                    resumeSucceeded,
-                    agentProgram: agentMeta.agentProgram
-                });
-                if (contextMode) {
-                    traceLines.push(`上下文模式: ${contextMode}`);
-                }
-                if (resumeAttempted) {
-                    traceLines.push(resumeSucceeded ? '会话恢复成功' : '会话恢复失败，已回退到历史注入');
-                }
-
-                try {
-                    const result = await execAgentInWebContainerStream(ctx, state, sessionRef, command, {
-                        agentProgram: agentMeta.agentProgram,
-                        onEvent: event => {
-                            if (event && event.type === 'trace' && event.text) {
-                                traceLines.push(String(event.text));
-                                if (event.traceEvent && typeof event.traceEvent === 'object') {
-                                    traceEvents.push(event.traceEvent);
-                                }
-                            }
-                            sendNdjson(res, event);
-                        }
-                    });
-                    traceLines.push(result.interrupted === true ? '[任务] 已停止' : '[任务] 已完成');
-                    appendWebAgentTraceMessage(state.webHistoryDir, sessionRef, traceLines.join('\n'), {
-                        traceEvents,
-                        contextMode,
-                        resumeAttempted,
-                        resumeSucceeded,
-                        interrupted: result.interrupted === true
-                    });
-                    finalizeWebAgentExecution(state, sessionRef, agentSession, agentMeta, {
-                        contextMode,
-                        resumeAttempted,
-                        resumeSucceeded,
-                        resumeError
-                    }, result);
-                    sendNdjson(res, {
-                        type: 'result',
-                        exitCode: result.exitCode,
-                        output: result.output,
-                        contextMode,
-                        resumeAttempted,
-                        resumeSucceeded,
-                        interrupted: result.interrupted === true
-                    });
-                } catch (e) {
-                    traceLines.push(`[错误] ${e && e.message ? e.message : 'Agent 执行失败'}`);
-                    appendWebAgentTraceMessage(state.webHistoryDir, sessionRef, traceLines.join('\n'), {
-                        traceEvents,
-                        contextMode,
-                        resumeAttempted,
-                        resumeSucceeded,
-                        interrupted: true
-                    });
-                    sendNdjson(res, {
-                        type: 'error',
-                        error: e && e.message ? e.message : 'Agent 执行失败'
-                    });
-                } finally {
-                    res.end();
-                }
-            }
-        },
-        {
-            method: 'POST',
-            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/agent\/stop$/),
-            handler: async match => {
-                const sessionRef = getValidSessionRef(ctx, res, match[1]);
-                if (!sessionRef) {
-                    return;
-                }
-                const stopped = stopWebAgentRun(state, sessionRef.containerName);
-                if (!stopped) {
-                    sendJson(res, 404, { error: '当前会话没有运行中的 agent 任务' });
-                    return;
-                }
-                sendJson(res, 200, { ok: true, stopping: true });
-            }
-        },
-        {
-            method: 'POST',
-            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/remove$/),
-            handler: async match => {
-                const sessionRef = getValidSessionRef(ctx, res, match[1]);
-                if (!sessionRef) {
-                    return;
-                }
-
-                if (ctx.containerExists(sessionRef.containerName)) {
-                    ctx.removeContainer(sessionRef.containerName);
-                    appendWebSessionMessage(state.webHistoryDir, sessionRef, 'system', `容器 ${sessionRef.containerName} 已删除。`);
-                }
-
-                sendJson(res, 200, { removed: true, name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId) });
-            }
-        },
-        {
-            method: 'POST',
-            match: currentPath => currentPath.match(/^\/api\/sessions\/([^/]+)\/remove-with-history$/),
-            handler: async match => {
-                const sessionRef = getValidSessionRef(ctx, res, match[1]);
-                if (!sessionRef) {
-                    return;
-                }
-
-                const history = loadWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
-                if (history.agents && typeof history.agents === 'object') {
-                    if (sessionRef.agentId === WEB_DEFAULT_AGENT_ID) {
-                        delete history.agents[WEB_DEFAULT_AGENT_ID];
-                    } else {
-                        delete history.agents[sessionRef.agentId];
-                    }
-                }
-                if (!Object.keys(history.agents || {}).length && !ctx.containerExists(sessionRef.containerName)) {
-                    removeWebSessionHistory(state.webHistoryDir, sessionRef.containerName);
-                } else {
-                    saveWebSessionHistory(state.webHistoryDir, sessionRef.containerName, history);
-                }
-                sendJson(res, 200, {
-                    removedHistory: true,
-                    name: buildWebSessionKey(sessionRef.containerName, sessionRef.agentId)
-                });
-            }
-        }
-    ];
 
-    for (const route of routes) {
-        if (route.method !== req.method) {
-            continue;
-        }
-        const matched = route.match(pathname);
-        if (!matched) {
-            continue;
-        }
-        await route.handler(matched);
-        return true;
-    }
+    const {
+        withSessionRef,
+        withJsonBody,
+        withSessionJsonBody,
+        getRequiredBodyText,
+        prepareAgentRequest
+    } = createApiRouteHelpers({
+        req,
+        res,
+        ctx,
+        state,
+        sendJson,
+        readJsonBody,
+        getValidSessionRef,
+        prepareWebAgentExecution
+    });
 
-    return false;
+    const routes = [
+        ...createSystemApiRoutes({
+            req,
+            res,
+            ctx,
+            state,
+            fs,
+            os,
+            path,
+            withJsonBody,
+            sendJson,
+            expandHomeAliasPath,
+            readWebConfigSnapshot,
+            buildSafeWebConfigSnapshot,
+            restoreWebConfigSecrets,
+            parseAndValidateConfigRaw,
+            buildConfigDefaults
+        }),
+        ...createSessionApiRoutes({
+            req,
+            res,
+            ctx,
+            state,
+            WEB_DEFAULT_AGENT_ID,
+            withSessionRef,
+            withJsonBody,
+            withSessionJsonBody,
+            getRequiredBodyText,
+            prepareAgentRequest,
+            sendJson,
+            sendNdjson,
+            buildCreateRuntime,
+            ensureWebContainer,
+            setWebSessionAgentPromptCommand,
+            patchWebSessionHistory,
+            listWebManyoyoContainers,
+            listWebHistorySessionNames,
+            loadWebSessionHistory,
+            listWebAgentSessions,
+            buildSessionSummary,
+            createWebAgentSession,
+            saveWebSessionHistory,
+            buildWebSessionKey,
+            getWebAgentSession,
+            createEmptyWebAgentSession,
+            buildSessionDetail,
+            hasOwn,
+            setWebAgentSessionPromptCommand,
+            appendWebSessionMessage,
+            execCommandInWebContainer,
+            finalizeWebAgentExecution,
+            execAgentInWebContainerStream,
+            appendWebAgentTraceMessage,
+            stopWebAgentRun,
+            removeWebSessionHistory
+        })
+    ];
+    return await runMatchedRoute(routes, req.method, pathname);
 }
 
 async function startWebServer(options) {
-    const fallbackLogger = {
-        info: () => {},
-        warn: () => {},
-        error: () => {}
-    };
-    const ctx = {
-        serverHost: options.serverHost || '127.0.0.1',
-        serverPort: options.serverPort,
-        authUser: options.authUser,
-        authPass: options.authPass,
-        authPassAuto: options.authPassAuto,
-        dockerCmd: options.dockerCmd,
-        hostPath: options.hostPath,
-        containerPath: options.containerPath,
-        imageName: options.imageName,
-        imageVersion: options.imageVersion,
-        execCommandPrefix: options.execCommandPrefix,
-        execCommand: options.execCommand,
-        execCommandSuffix: options.execCommandSuffix,
-        contModeArgs: options.contModeArgs,
-        containerExtraArgs: options.containerExtraArgs,
-        containerEnvs: options.containerEnvs,
-        containerVolumes: options.containerVolumes,
-        containerPorts: options.containerPorts,
-        validateHostPath: options.validateHostPath,
-        formatDate: options.formatDate,
-        isValidContainerName: options.isValidContainerName,
-        containerExists: options.containerExists,
-        getContainerStatus: options.getContainerStatus,
-        waitForContainerReady: options.waitForContainerReady,
-        dockerExecArgs: options.dockerExecArgs,
-        showImagePullHint: options.showImagePullHint,
-        removeContainer: options.removeContainer,
-        logger: options.logger && typeof options.logger.info === 'function' ? options.logger : fallbackLogger,
-        colors: options.colors || {
-            GREEN: '',
-            CYAN: '',
-            YELLOW: '',
-            NC: ''
-        }
-    };
-
-    if (!ctx.authUser || !ctx.authPass) {
-        throw new Error('Web 认证配置缺失，请设置 serve -U / serve -P');
-    }
-
-    const state = {
-        webHistoryDir: options.webHistoryDir || path.join(os.homedir(), '.manyoyo', 'web-history'),
-        webConfigPath: options.webConfigPath || getDefaultWebConfigPath(),
-        authSessions: new Map(),
-        terminalSessions: new Map(),
-        agentRuns: new Map()
-    };
+    const ctx = createWebServerContext(options);
+    const state = createWebServerState(options);
 
     ensureWebHistoryDir(state.webHistoryDir);
 
-    const wsServer = new WebSocket.Server({
-        noServer: true,
-        maxPayload: 1024 * 1024
-    });
-    wsServer.on('error', err => {
-        ctx.logger.error('ws server error', err);
-    });
-
-    wsServer.on('connection', (ws, req, meta = {}) => {
-        const containerName = meta.containerName;
-        if (!containerName || !ctx.isValidContainerName(containerName)) {
-            ws.close();
-            return;
-        }
-        const { cols, rows } = normalizeTerminalSize(meta.cols, meta.rows);
-        bindTerminalWebSocket(ctx, state, ws, containerName, cols, rows);
-    });
-
-    const server = http.createServer(async (req, res) => {
-        try {
-            const fallbackHost = `${formatUrlHost(ctx.serverHost)}:${ctx.serverPort}`;
-            const url = new URL(req.url, `http://${req.headers.host || fallbackHost}`);
-            const pathname = url.pathname;
-
-            // 全局认证入口：除登录路由外，默认全部请求都要求认证
-            if (await handleWebAuthRoutes(req, res, pathname, ctx, state)) {
-                return;
-            }
-
-            const authSession = getWebAuthSession(state, req);
-            if (!authSession) {
-                sendWebUnauthorized(res, pathname);
-                return;
-            }
-
-            if (req.method === 'GET' && pathname === '/') {
-                sendHtml(res, 200, loadTemplate('app.html'));
-                return;
-            }
-
-            const appFrontendMatch = pathname.match(/^\/app\/frontend\/([A-Za-z0-9._-]+)$/);
-            if (req.method === 'GET' && appFrontendMatch) {
-                const assetName = appFrontendMatch[1];
-                if (!(assetName === 'app.css' || assetName === 'app.js' || assetName === 'markdown.css' || assetName === 'markdown-renderer.js')) {
-                    sendHtml(res, 404, '<h1>404 Not Found</h1>');
-                    return;
-                }
-                sendStaticAsset(res, assetName);
-                return;
-            }
-
-            const appVendorMatch = pathname.match(/^\/app\/vendor\/([A-Za-z0-9._-]+)$/);
-            if (req.method === 'GET' && appVendorMatch) {
-                const assetName = appVendorMatch[1];
-                if (!(assetName === 'xterm.css' || assetName === 'xterm.js' || assetName === 'xterm-addon-fit.js' || assetName === 'marked.min.js')) {
-                    sendHtml(res, 404, '<h1>404 Not Found</h1>');
-                    return;
-                }
-                sendVendorAsset(res, assetName);
-                return;
-            }
-
-            if (pathname === '/healthz') {
-                sendJson(res, 200, { ok: true });
-                return;
-            }
-
-            if (pathname.startsWith('/api/')) {
-                const handled = await handleWebApi(req, res, pathname, ctx, state);
-                if (!handled) {
-                    sendJson(res, 404, { error: 'Not Found' });
-                }
-                return;
-            }
-
-            sendHtml(res, 404, '<h1>404 Not Found</h1>');
-        } catch (e) {
-            ctx.logger.error('http request error', {
-                method: req && req.method ? req.method : '',
-                url: req && req.url ? req.url : '',
-                message: e && e.message ? e.message : 'Server Error'
-            });
-            if ((req.url || '').startsWith('/api/')) {
-                sendJson(res, 500, { error: e.message || 'Server Error' });
-            } else {
-                sendHtml(res, 500, '<h1>500 Server Error</h1>');
-            }
-        }
-    });
-    server.on('error', err => {
-        ctx.logger.error('http server error', err);
-    });
-    server.on('close', () => {
-        ctx.logger.warn('http server closed');
+    const wsServer = createWsServer(ctx, state);
+
+    const { handleWebHttpRequest } = createWebHttpHandlers({
+        loadTemplate,
+        sendHtml,
+        sendJson,
+        sendRedirect,
+        sendStaticAsset,
+        sendVendorAsset,
+        readJsonBody,
+        secureStringEqual,
+        createWebAuthSession,
+        clearWebAuthSession,
+        getWebAuthCookie,
+        getWebAuthClearCookie,
+        getWebAuthSession,
+        AUTH_FRONTEND_ASSETS,
+        APP_FRONTEND_ASSETS,
+        APP_VENDOR_ASSETS,
+        handleWebApi
     });
 
-    server.on('upgrade', (req, socket, head) => {
-        const fallbackHost = `${formatUrlHost(ctx.serverHost)}:${ctx.serverPort}`;
-        let url;
-        try {
-            url = new URL(req.url || '/', `http://${req.headers.host || fallbackHost}`);
-        } catch (e) {
-            sendWebSocketUpgradeError(socket, 400, 'Invalid URL');
-            return;
-        }
-
-        const terminalMatch = url.pathname.match(/^\/api\/sessions\/([^/]+)\/terminal\/ws$/);
-        if (!terminalMatch) {
-            socket.destroy();
-            return;
-        }
-
-        // [P1-03] Origin 校验，防止跨站 WebSocket 劫持（CSWSH）
-        // 浏览器发起的 WebSocket 请求必须携带 Origin 头，非浏览器客户端（如 curl）不携带则放行
-        const requestOrigin = req.headers.origin;
-        if (requestOrigin) {
-            const allowedOrigins = new Set();
-            // 始终以请求的 Host 头构造允许来源，兼容 nginx 等反向代理场景
-            const hostHeader = req.headers.host || '';
-            if (hostHeader) {
-                allowedOrigins.add(`http://${hostHeader}`);
-                allowedOrigins.add(`https://${hostHeader}`);
-            }
-            if (ctx.serverHost !== '0.0.0.0') {
-                allowedOrigins.add(`http://${formatUrlHost(ctx.serverHost)}:${listenPort}`);
-                if (ctx.serverHost === '127.0.0.1') {
-                    allowedOrigins.add(`http://localhost:${listenPort}`);
-                }
-            }
-            if (allowedOrigins.size > 0 && !allowedOrigins.has(requestOrigin)) {
-                sendWebSocketUpgradeError(socket, 403, 'Forbidden');
-                return;
-            }
-        }
-
-        const authSession = getWebAuthSession(state, req);
-        if (!authSession) {
-            sendWebSocketUpgradeError(socket, 401, 'UNAUTHORIZED');
-            return;
-        }
-
-        const sessionRef = parseWebSessionKey(decodeSessionName(terminalMatch[1]));
-        if (!ctx.isValidContainerName(sessionRef.containerName)) {
-            sendWebSocketUpgradeError(socket, 400, `containerName 非法: ${sessionRef.containerName}`);
-            return;
-        }
-        if (!SAFE_CONTAINER_NAME_PATTERN.test(sessionRef.agentId)) {
-            sendWebSocketUpgradeError(socket, 400, `agentId 非法: ${sessionRef.agentId}`);
-            return;
-        }
-
-        if (state.terminalSessions.size >= WEB_TERMINAL_MAX_SESSIONS) {
-            sendWebSocketUpgradeError(socket, 429, 'TERMINAL_LIMIT_REACHED');
-            return;
-        }
-
-        const { cols, rows } = normalizeTerminalSize(
-            url.searchParams.get('cols'),
-            url.searchParams.get('rows')
-        );
-
-        ensureWebContainer(ctx, state, sessionRef.containerName)
-            .then(() => {
-                wsServer.handleUpgrade(req, socket, head, ws => {
-                    wsServer.emit('connection', ws, req, {
-                        containerName: sessionRef.containerName,
-                        cols,
-                        rows
-                    });
-                });
-            })
-            .catch(e => {
-                sendWebSocketUpgradeError(socket, 500, e && e.message ? e.message : '终端创建失败');
-            });
-    });
-
-    let listenPort = ctx.serverPort;
-
-    await new Promise((resolve, reject) => {
-        server.once('error', err => {
-            ctx.logger.error('http server listen failed', err);
-            reject(err);
-        });
-        server.listen(ctx.serverPort, ctx.serverHost, () => {
-            const address = server.address();
-            if (address && typeof address === 'object' && typeof address.port === 'number') {
-                listenPort = address.port;
-            }
-            const { GREEN, CYAN, YELLOW, NC } = ctx.colors;
-            const listenHost = formatUrlHost(ctx.serverHost);
-            console.log(`${GREEN}✅ MANYOYO Web 服务已启动: http://${listenHost}:${listenPort}${NC}`);
-            console.log(`${CYAN}提示: 左侧是 manyoyo 容器会话列表，中间是活动/终端/配置/检查工作台，右侧显示当前会话上下文。${NC}`);
-            if (ctx.serverHost === '0.0.0.0') {
-                console.log(`${CYAN}提示: 当前监听全部网卡，请用本机局域网 IP 访问。${NC}`);
-            }
-            console.log(`${CYAN}🔐 登录用户名: ${YELLOW}${ctx.authUser}${NC}`);
-            if (ctx.authPassAuto) {
-                console.log(`${CYAN}🔐 登录密码(本次随机): ${YELLOW}${ctx.authPass}${NC}`);
-            } else {
-                console.log(`${CYAN}🔐 登录密码: 使用你配置的 serve -P / serverPass / MANYOYO_SERVER_PASS${NC}`);
-            }
-            ctx.logger.info('web server started', {
-                host: ctx.serverHost,
-                port: listenPort,
-                authUser: ctx.authUser,
-                authPassAuto: Boolean(ctx.authPassAuto)
-            });
-            resolve();
-        });
-    });
+    const server = createHttpServer(ctx, state, wsServer, handleWebHttpRequest);
+    const listenPort = await listenWebServer(server, ctx);
 
     return {
         server,
         wsServer,
         host: ctx.serverHost,
         port: listenPort,
-        close: () => new Promise(resolve => {
-            ctx.logger.info('web server closing');
-            for (const session of state.terminalSessions.values()) {
-                const ptyProcess = session && session.ptyProcess;
-                if (ptyProcess && !ptyProcess.killed) {
-                    try { ptyProcess.kill('SIGTERM'); } catch (e) {}
-                }
-            }
-            state.terminalSessions.clear();
-            for (const runState of state.agentRuns.values()) {
-                const child = runState && runState.process;
-                if (child && !child.killed) {
-                    try { child.kill('SIGTERM'); } catch (e) {}
-                }
-            }
-            state.agentRuns.clear();
-
-            const closeHttp = () => {
-                if (!server.listening) {
-                    resolve();
-                    return;
-                }
-                server.close(() => resolve());
-            };
-
-            try {
-                wsServer.close(() => closeHttp());
-            } catch (e) {
-                closeHttp();
-            }
-        })
+        close: () => closeWebServer(server, wsServer, ctx, state)
     };
 }