codexmate 0.0.13 → 0.0.14

package/cli.js

@@ -21,6 +21,8 @@ const {
     detectLineEnding,
     normalizeLineEnding,
     isValidProviderName,
+    escapeTomlBasicString,
+    buildModelProviderTableHeader,
     buildModelsCandidates,
     isValidHttpUrl,
     normalizeBaseUrl,
@@ -54,6 +56,10 @@ const {
     resolveMaxMessagesValue
 } = require('./lib/cli-session-utils');
 const { createMcpStdioServer } = require('./lib/mcp-stdio');
+const {
+    validateWorkflowDefinition,
+    executeWorkflowDefinition
+} = require('./lib/workflow-engine');
 
 const DEFAULT_WEB_PORT = 3737;
 const DEFAULT_WEB_HOST = '127.0.0.1';
@@ -78,6 +84,8 @@ const CLAUDE_DIR = path.join(os.homedir(), '.claude');
 const CLAUDE_SETTINGS_FILE = path.join(CLAUDE_DIR, 'settings.json');
 const CLAUDE_PROJECTS_DIR = path.join(os.homedir(), '.claude', 'projects');
 const RECENT_CONFIGS_FILE = path.join(CONFIG_DIR, 'recent-configs.json');
+const WORKFLOW_DEFINITIONS_FILE = path.join(CONFIG_DIR, 'codexmate-workflows.json');
+const WORKFLOW_RUNS_FILE = path.join(CONFIG_DIR, 'codexmate-workflow-runs.jsonl');
 const DEFAULT_CLAUDE_MODEL = 'glm-4.7';
 const CODEX_BACKUP_NAME = 'codex-config';
 
@@ -98,6 +106,15 @@ const SESSION_SCAN_FACTOR = 4;
 const SESSION_SCAN_MIN_FILES = 800;
 const MAX_SESSION_PATH_LIST_SIZE = 2000;
 const AGENTS_FILE_NAME = 'AGENTS.md';
+const CODEX_SKILLS_DIR = path.join(CONFIG_DIR, 'skills');
+const CLAUDE_SKILLS_DIR = path.join(CLAUDE_DIR, 'skills');
+const GEMINI_SKILLS_DIR = path.join(os.homedir(), '.gemini', 'skills');
+const OPENCODE_SKILLS_DIR = path.join(os.homedir(), '.opencode', 'skills');
+const SKILL_IMPORT_SOURCES = Object.freeze([
+    { app: 'claude', label: 'Claude Code', dir: CLAUDE_SKILLS_DIR },
+    { app: 'gemini', label: 'Gemini CLI', dir: GEMINI_SKILLS_DIR },
+    { app: 'opencode', label: 'OpenCode', dir: OPENCODE_SKILLS_DIR }
+]);
 const MODELS_CACHE_TTL_MS = 60 * 1000;
 const MODELS_NEGATIVE_CACHE_TTL_MS = 5 * 1000;
 const MODELS_CACHE_MAX_ENTRIES = 50;
@@ -215,16 +232,50 @@ function ensureConfigDir() {
     }
 }
 
+function createConfigLoadError(type, message, detail) {
+    const err = new Error(detail || message);
+    err.configErrorType = type || 'read';
+    err.configPublicReason = message || '读取 config.toml 失败';
+    err.configDetail = detail || message || '';
+    return err;
+}
+
 function readConfig() {
     if (!fs.existsSync(CONFIG_FILE)) {
-        throw new Error(`配置文件不存在: ${CONFIG_FILE}`);
+        throw createConfigLoadError(
+            'missing',
+            '未检测到 config.toml',
+            `配置文件不存在: ${CONFIG_FILE}`
+        );
+    }
+
+    let content = '';
+    try {
+        content = fs.readFileSync(CONFIG_FILE, 'utf-8');
+    } catch (e) {
+        throw createConfigLoadError(
+            'read',
+            '读取 config.toml 失败',
+            `读取配置文件失败: ${e && e.message ? e.message : e}`
+        );
     }
+
+    let parsed;
     try {
-        const content = fs.readFileSync(CONFIG_FILE, 'utf-8');
-        return toml.parse(content);
+        parsed = toml.parse(content);
     } catch (e) {
-        throw new Error(`配置文件解析失败: ${e.message}`);
+        throw createConfigLoadError(
+            'parse',
+            'config.toml 解析失败',
+            `配置文件解析失败: ${e && e.message ? e.message : e}`
+        );
+    }
+
+    if (isPlainObject(parsed) && isPlainObject(parsed.model_providers)) {
+        const providerHeaderSegmentKeySet = collectModelProviderHeaderSegmentKeySet(content);
+        parsed.model_providers = normalizeLegacyModelProviders(parsed.model_providers, providerHeaderSegmentKeySet);
     }
+    return parsed;
 }
 
 function writeConfig(content) {
@@ -277,6 +328,519 @@ function isPlainObject(value) {
     return !!value && typeof value === 'object' && !Array.isArray(value);
 }
 
+const PROVIDER_CONFIG_KEYS = new Set([
+    'name',
+    'base_url',
+    'wire_api',
+    'requires_openai_auth',
+    'preferred_auth_method',
+    'request_max_retries',
+    'stream_max_retries',
+    'stream_idle_timeout_ms'
+]);
+const RECOVERABLE_PROVIDER_SIGNAL_KEYS = [...PROVIDER_CONFIG_KEYS].filter((key) => key !== 'name' && key !== 'base_url');
+
+function looksLikeProviderConfig(value) {
+    if (!isPlainObject(value)) return false;
+    return Object.keys(value).some((key) => PROVIDER_CONFIG_KEYS.has(key));
+}
+
+function isRecoverableNestedProviderConfig(value) {
+    if (!isPlainObject(value)) return false;
+    const hasBaseUrl = typeof value.base_url === 'string' && value.base_url.trim() !== '';
+    if (!hasBaseUrl) return false;
+    const hasName = typeof value.name === 'string' && value.name.trim() !== '';
+    const hasProviderSignals = RECOVERABLE_PROVIDER_SIGNAL_KEYS.some((key) => Object.prototype.hasOwnProperty.call(value, key));
+    return hasName || hasProviderSignals;
+}
+
+function collectNestedProviderConfigs(node, pathSegments, collector) {
+    if (!isPlainObject(node)) return;
+    const segments = Array.isArray(pathSegments) ? pathSegments : [String(pathSegments || '')];
+    const lastSegment = segments.length > 0 ? segments[segments.length - 1] : '';
+    if (segments.length > 1 && lastSegment === 'metadata') {
+        return;
+    }
+    if (isRecoverableNestedProviderConfig(node)) {
+        collector.push({
+            name: segments.join('.'),
+            segments: segments.slice(),
+            provider: node
+        });
+    }
+    for (const [childKey, childValue] of Object.entries(node)) {
+        if (!isPlainObject(childValue)) continue;
+        collectNestedProviderConfigs(childValue, [...segments, childKey], collector);
+    }
+}
+
+function normalizeLegacySegments(segments) {
+    if (!Array.isArray(segments) || segments.length === 0) return null;
+    return segments.map((item) => String(item));
+}
+
+function buildLegacySegmentsKey(segments) {
+    const normalized = normalizeLegacySegments(segments);
+    return normalized ? JSON.stringify(normalized) : '';
+}
+
+function appendLegacySegmentsVariant(provider, segments) {
+    if (!isPlainObject(provider)) return;
+    const normalized = normalizeLegacySegments(segments);
+    if (!normalized) return;
+
+    const variants = [];
+    const seen = new Set();
+    const pushVariant = (candidate) => {
+        const key = buildLegacySegmentsKey(candidate);
+        if (!key || seen.has(key)) return;
+        seen.add(key);
+        variants.push(normalizeLegacySegments(candidate));
+    };
+
+    if (Array.isArray(provider.__codexmate_legacy_segments)) {
+        pushVariant(provider.__codexmate_legacy_segments);
+    }
+    if (Array.isArray(provider.__codexmate_legacy_segment_variants)) {
+        for (const candidate of provider.__codexmate_legacy_segment_variants) {
+            pushVariant(candidate);
+        }
+    }
+    pushVariant(normalized);
+
+    try {
+        if (!Array.isArray(provider.__codexmate_legacy_segments)) {
+            Object.defineProperty(provider, '__codexmate_legacy_segments', {
+                value: normalized,
+                enumerable: false,
+                configurable: true,
+                writable: true
+            });
+        }
+        Object.defineProperty(provider, '__codexmate_legacy_segment_variants', {
+            value: variants,
+            enumerable: false,
+            configurable: true,
+            writable: true
+        });
+    } catch (e) {}
+}
+
+function setLegacySegmentsMetadata(provider, segments) {
+    appendLegacySegmentsVariant(provider, segments);
+}
+
+function normalizeLegacyModelProviders(modelProviders, providerHeaderSegmentKeySet = null) {
+    if (!isPlainObject(modelProviders)) {
+        return modelProviders;
+    }
+
+    let changed = false;
+    const normalized = {};
+    const addRecovered = (entry) => {
+        const name = entry && typeof entry.name === 'string' ? entry.name : '';
+        const segments = entry && Array.isArray(entry.segments) ? entry.segments.slice() : null;
+        const provider = entry ? entry.provider : null;
+        if (!name || !isPlainObject(provider)) return;
+        const segmentKey = buildLegacySegmentsKey(segments);
+        if (providerHeaderSegmentKeySet instanceof Set && segmentKey && !providerHeaderSegmentKeySet.has(segmentKey)) {
+            return;
+        }
+        const existing = Object.prototype.hasOwnProperty.call(normalized, name)
+            ? normalized[name]
+            : (Object.prototype.hasOwnProperty.call(modelProviders, name) ? modelProviders[name] : null);
+        if (isPlainObject(existing)) {
+            if (!Array.isArray(existing.__codexmate_legacy_segments)) {
+                setLegacySegmentsMetadata(existing, [name]);
+            }
+            appendLegacySegmentsVariant(existing, segments);
+            return;
+        }
+        if (Object.prototype.hasOwnProperty.call(modelProviders, name)) return;
+        if (Object.prototype.hasOwnProperty.call(normalized, name)) return;
+        setLegacySegmentsMetadata(provider, segments);
+        normalized[name] = provider;
+        changed = true;
+    };
+
+    for (const [name, provider] of Object.entries(modelProviders)) {
+        normalized[name] = provider;
+        if (!isPlainObject(provider)) continue;
+
+        if (looksLikeProviderConfig(provider)) {
+            setLegacySegmentsMetadata(provider, [name]);
+            for (const [childKey, childValue] of Object.entries(provider)) {
+                if (!isPlainObject(childValue)) continue;
+                const recovered = [];
+                collectNestedProviderConfigs(childValue, [name, childKey], recovered);
+                for (const recoveredEntry of recovered) {
+                    addRecovered(recoveredEntry);
+                }
+            }
+            continue;
+        }
+
+        const recovered = [];
+        collectNestedProviderConfigs(provider, [name], recovered);
+        delete normalized[name];
+        changed = true;
+        for (const recoveredEntry of recovered) {
+            addRecovered(recoveredEntry);
+        }
+    }
+
+    return changed ? normalized : modelProviders;
+}
+
+function escapeRegex(value) {
+    return String(value || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function areStringArraysEqual(a, b) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    for (let i = 0; i < a.length; i++) {
+        if (String(a[i]) !== String(b[i])) return false;
+    }
+    return true;
+}
+
+function parseTomlDottedKeyExpression(expression) {
+    const text = String(expression || '');
+    let index = 0;
+    const segments = [];
+    const skipWhitespace = () => {
+        while (index < text.length && /\s/.test(text[index])) index++;
+    };
+
+    while (index < text.length) {
+        skipWhitespace();
+        if (index >= text.length) break;
+
+        const ch = text[index];
+        if (ch === "'") {
+            const end = text.indexOf("'", index + 1);
+            if (end === -1) return null;
+            segments.push(text.slice(index + 1, end));
+            index = end + 1;
+        } else if (ch === '"') {
+            index += 1;
+            let value = '';
+            let closed = false;
+            while (index < text.length) {
+                const cur = text[index];
+                if (cur === '"') {
+                    index += 1;
+                    closed = true;
+                    break;
+                }
+                if (cur !== '\\') {
+                    value += cur;
+                    index += 1;
+                    continue;
+                }
+                if (index + 1 >= text.length) return null;
+                const esc = text[index + 1];
+                if (esc === 'u' || esc === 'U') {
+                    const hexLen = esc === 'u' ? 4 : 8;
+                    const hex = text.slice(index + 2, index + 2 + hexLen);
+                    if (!/^[0-9a-fA-F]+$/.test(hex)) return null;
+                    try {
+                        value += String.fromCodePoint(parseInt(hex, 16));
+                    } catch (e) {
+                        return null;
+                    }
+                    index += 2 + hexLen;
+                    continue;
+                }
+                const unescaped = {
+                    b: '\b',
+                    t: '\t',
+                    n: '\n',
+                    f: '\f',
+                    r: '\r',
+                    '"': '"',
+                    '\\': '\\'
+                }[esc];
+                if (unescaped === undefined) return null;
+                value += unescaped;
+                index += 2;
+            }
+            if (!closed) return null;
+            segments.push(value);
+        } else {
+            const start = index;
+            while (index < text.length && !/\s|\./.test(text[index])) index++;
+            const bare = text.slice(start, index);
+            if (!bare) return null;
+            segments.push(bare);
+        }
+
+        skipWhitespace();
+        if (index >= text.length) break;
+        if (text[index] !== '.') return null;
+        index += 1;
+    }
+
+    return segments.length > 0 ? segments : null;
+}
+
+function collectTomlMultilineStringRanges(text) {
+    const source = typeof text === 'string' ? text : '';
+    const ranges = [];
+    let i = 0;
+    let inMultilineBasic = false;
+    let inMultilineLiteral = false;
+    let rangeStart = -1;
+
+    while (i < source.length) {
+        if (inMultilineBasic) {
+            if (source.slice(i, i + 3) === '"""') {
+                let slashCount = 0;
+                for (let j = i - 1; j >= 0 && source[j] === '\\'; j--) {
+                    slashCount++;
+                }
+                if (slashCount % 2 === 0) {
+                    let runEnd = i + 3;
+                    while (runEnd < source.length && source[runEnd] === '"') runEnd++;
+                    ranges.push({ start: rangeStart, end: runEnd });
+                    inMultilineBasic = false;
+                    rangeStart = -1;
+                    i = runEnd;
+                    continue;
+                }
+            }
+            i++;
+            continue;
+        }
+
+        if (inMultilineLiteral) {
+            if (source.slice(i, i + 3) === "'''") {
+                let runEnd = i + 3;
+                while (runEnd < source.length && source[runEnd] === '\'') runEnd++;
+                ranges.push({ start: rangeStart, end: runEnd });
+                inMultilineLiteral = false;
+                rangeStart = -1;
+                i = runEnd;
+                continue;
+            }
+            i++;
+            continue;
+        }
+
+        const ch = source[i];
+        if (ch === '#') {
+            while (i < source.length && source[i] !== '\n') i++;
+            continue;
+        }
+
+        if (source.slice(i, i + 3) === '"""') {
+            inMultilineBasic = true;
+            rangeStart = i;
+            i += 3;
+            continue;
+        }
+
+        if (source.slice(i, i + 3) === "'''") {
+            inMultilineLiteral = true;
+            rangeStart = i;
+            i += 3;
+            continue;
+        }
+
+        if (ch === '"') {
+            i++;
+            while (i < source.length) {
+                if (source[i] === '\\') {
+                    i += 2;
+                    continue;
+                }
+                if (source[i] === '"' || source[i] === '\n') {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+
+        if (ch === '\'') {
+            i++;
+            while (i < source.length) {
+                if (source[i] === '\'' || source[i] === '\n') {
+                    i++;
+                    break;
+                }
+                i++;
+            }
+            continue;
+        }
+
+        i++;
+    }
+
+    if (rangeStart >= 0) {
+        ranges.push({ start: rangeStart, end: source.length });
+    }
+    return ranges;
+}
+
+function isIndexInRanges(index, ranges) {
+    for (const range of ranges) {
+        if (index < range.start) return false;
+        if (index >= range.start && index < range.end) return true;
+    }
+    return false;
+}
+
+function findProviderSectionRanges(content, providerName, exactSegments = null) {
+    const text = typeof content === 'string' ? content : '';
+    const name = typeof providerName === 'string' ? providerName.trim() : '';
+    const targetSegments = Array.isArray(exactSegments) ? exactSegments.map((item) => String(item)) : null;
+    if (!text || !name) return [];
+
+    const safeName = escapeRegex(name);
+    const headerPatterns = [
+        { priority: 0, regex: new RegExp(`^\\s*model_providers\\s*\\.\\s*"${safeName}"\\s*$`) },
+        { priority: 1, regex: new RegExp(`^\\s*model_providers\\s*\\.\\s*'${safeName}'\\s*$`) },
+        { priority: 2, regex: new RegExp(`^\\s*model_providers\\s*\\.\\s*${safeName}\\s*$`) }
+    ];
+
+    const allHeaders = [];
+    const targetPriorityByStart = new Map();
+    const multilineStringRanges = collectTomlMultilineStringRanges(text);
+    const sectionLineRegex = /^[ \t]*\[(?!\[)([^\]\n]+)\][ \t]*(?:#.*)?$/gm;
+    let match;
+    while ((match = sectionLineRegex.exec(text)) !== null) {
+        const start = match.index;
+        if (isIndexInRanges(start, multilineStringRanges)) {
+            continue;
+        }
+        allHeaders.push(start);
+        const headerExpr = String(match[1] || '').trim();
+
+        const parsedSegments = parseTomlDottedKeyExpression(headerExpr);
+        if (Array.isArray(parsedSegments) && parsedSegments.length >= 2 && parsedSegments[0] === 'model_providers') {
+            const providerSegments = parsedSegments.slice(1);
+            if (targetSegments && targetSegments.length > 0 && areStringArraysEqual(providerSegments, targetSegments)) {
+                const prev = targetPriorityByStart.get(start);
+                if (prev === undefined || -3 < prev) {
+                    targetPriorityByStart.set(start, -3);
+                }
+                continue;
+            }
+            if (!targetSegments || targetSegments.length === 0) {
+                const parsedName = providerSegments.join('.');
+                if (parsedName === name) {
+                    const prev = targetPriorityByStart.get(start);
+                    if (prev === undefined || -2 < prev) {
+                        targetPriorityByStart.set(start, -2);
+                    }
+                    continue;
+                }
+            }
+        }
+
+        for (const pattern of headerPatterns) {
+            if (pattern.regex.test(headerExpr)) {
+                const prev = targetPriorityByStart.get(start);
+                if (prev === undefined || pattern.priority < prev) {
+                    targetPriorityByStart.set(start, pattern.priority);
+                }
+                break;
+            }
+        }
+    }
+
+    if (targetPriorityByStart.size === 0) {
+        return [];
+    }
+
+    const ranges = [];
+    for (let i = 0; i < allHeaders.length; i++) {
+        const start = allHeaders[i];
+        if (!targetPriorityByStart.has(start)) continue;
+        const end = i + 1 < allHeaders.length ? allHeaders[i + 1] : text.length;
+        ranges.push({
+            start,
+            end,
+            priority: targetPriorityByStart.get(start)
+        });
+    }
+    const exactMatches = ranges.filter((range) => range.priority === -3);
+    return exactMatches.length > 0 ? exactMatches : ranges;
+}
+
+function doesSegmentsStartWith(segments, prefix) {
+    if (!Array.isArray(segments) || !Array.isArray(prefix) || prefix.length === 0 || segments.length < prefix.length) {
+        return false;
+    }
+    for (let i = 0; i < prefix.length; i++) {
+        if (String(segments[i]) !== String(prefix[i])) return false;
+    }
+    return true;
+}
+
+function findProviderDescendantSectionRanges(content, prefixSegments) {
+    const text = typeof content === 'string' ? content : '';
+    const prefix = Array.isArray(prefixSegments) ? prefixSegments.map((item) => String(item)) : [];
+    if (!text || prefix.length === 0) return [];
+
+    const allHeaders = [];
+    const parsedProviderSegmentsByStart = new Map();
+    const multilineStringRanges = collectTomlMultilineStringRanges(text);
+    const sectionLineRegex = /^[ \t]*\[(?!\[)([^\]\n]+)\][ \t]*(?:#.*)?$/gm;
+    let match;
+    while ((match = sectionLineRegex.exec(text)) !== null) {
+        const start = match.index;
+        if (isIndexInRanges(start, multilineStringRanges)) {
+            continue;
+        }
+        allHeaders.push(start);
+        const headerExpr = String(match[1] || '').trim();
+        const parsedSegments = parseTomlDottedKeyExpression(headerExpr);
+        if (!Array.isArray(parsedSegments) || parsedSegments.length < 2 || parsedSegments[0] !== 'model_providers') {
+            continue;
+        }
+        parsedProviderSegmentsByStart.set(start, parsedSegments.slice(1));
+    }
+
+    const ranges = [];
+    for (let i = 0; i < allHeaders.length; i++) {
+        const start = allHeaders[i];
+        const providerSegments = parsedProviderSegmentsByStart.get(start);
+        if (!providerSegments) continue;
+        if (!doesSegmentsStartWith(providerSegments, prefix)) continue;
+        if (providerSegments.length <= prefix.length) continue;
+        const end = i + 1 < allHeaders.length ? allHeaders[i + 1] : text.length;
+        ranges.push({ start, end, priority: 0 });
+    }
+    return ranges;
+}
+
+function collectModelProviderHeaderSegmentKeySet(content) {
+    const text = typeof content === 'string' ? content : '';
+    const keys = new Set();
+    if (!text) return keys;
+
+    const multilineStringRanges = collectTomlMultilineStringRanges(text);
+    const sectionLineRegex = /^[ \t]*\[(?!\[)([^\]\n]+)\][ \t]*(?:#.*)?$/gm;
+    let match;
+    while ((match = sectionLineRegex.exec(text)) !== null) {
+        const start = match.index;
+        if (isIndexInRanges(start, multilineStringRanges)) {
+            continue;
+        }
+        const headerExpr = String(match[1] || '').trim();
+        const parsedSegments = parseTomlDottedKeyExpression(headerExpr);
+        if (!Array.isArray(parsedSegments) || parsedSegments.length < 2 || parsedSegments[0] !== 'model_providers') {
+            continue;
+        }
+        const key = buildLegacySegmentsKey(parsedSegments.slice(1));
+        if (key) keys.add(key);
+    }
+    return keys;
+}
+
 function normalizeAuthProfileName(value) {
     const raw = typeof value === 'string' ? value.trim() : '';
     if (!raw) return '';
@@ -790,78 +1354,620 @@ function validateAgentsBaseDir(filePath) {
     return { ok: true, dirPath };
 }
 
-function readAgentsFile(params = {}) {
-    const filePath = resolveAgentsFilePath(params);
-    const dirCheck = validateAgentsBaseDir(filePath);
-    if (dirCheck.error) {
-        return { error: dirCheck.error };
+function normalizeCodexSkillName(name) {
+    const value = typeof name === 'string' ? name.trim() : '';
+    if (!value) {
+        return { error: '技能名称不能为空' };
     }
-
-    if (!fs.existsSync(filePath)) {
-        return {
-            exists: false,
-            path: filePath,
-            content: '',
-            lineEnding: os.EOL === '\r\n' ? '\r\n' : '\n'
-        };
+    if (value.includes('\0')) {
+        return { error: '技能名称非法' };
     }
-
-    try {
-        const raw = fs.readFileSync(filePath, 'utf-8');
-        return {
-            exists: true,
-            path: filePath,
-            content: stripUtf8Bom(raw),
-            lineEnding: detectLineEnding(raw)
-        };
-    } catch (e) {
-        return { error: `读取 AGENTS.md 失败: ${e.message}` };
+    if (value === '.' || value === '..') {
+        return { error: '技能名称非法' };
     }
-}
-
-function applyAgentsFile(params = {}) {
-    const filePath = resolveAgentsFilePath(params);
-    const dirCheck = validateAgentsBaseDir(filePath);
-    if (dirCheck.error) {
-        return { error: dirCheck.error };
+    if (value.includes('/') || value.includes('\\')) {
+        return { error: '技能名称非法' };
     }
+    if (path.basename(value) !== value) {
+        return { error: '技能名称非法' };
+    }
+    if (value.startsWith('.')) {
+        return { error: '系统技能不可删除' };
+    }
+    return { name: value };
+}
 
-    const content = typeof params.content === 'string' ? params.content : '';
-    const lineEnding = params.lineEnding === '\r\n' ? '\r\n' : '\n';
-    const normalized = normalizeLineEnding(content, lineEnding);
-    const finalContent = ensureUtf8Bom(normalized);
-
+function isSkillDirectoryEntry(entryName) {
+    const targetPath = path.join(CODEX_SKILLS_DIR, entryName);
     try {
-        fs.writeFileSync(filePath, finalContent, 'utf-8');
-        return { success: true, path: filePath };
+        const stat = fs.statSync(targetPath);
+        return stat.isDirectory();
     } catch (e) {
-        return { error: `写入 AGENTS.md 失败: ${e.message}` };
+        return false;
     }
 }
 
-function resolveOpenclawWorkspaceDir(config) {
-    const workspace = config
-        && config.agents
-        && config.agents.defaults
-        && typeof config.agents.defaults.workspace === 'string'
-        ? config.agents.defaults.workspace
-        : '';
-    const resolved = resolveHomePath(workspace);
-    if (!resolved) {
-        return OPENCLAW_WORKSPACE_DIR;
-    }
-    if (path.isAbsolute(resolved)) {
-        return resolved;
-    }
-    return path.join(OPENCLAW_DIR, resolved);
+function normalizeSkillImportSourceApp(app) {
+    const value = typeof app === 'string' ? app.trim().toLowerCase() : '';
+    return SKILL_IMPORT_SOURCES.some((item) => item.app === value) ? value : '';
 }
 
-function normalizeOpenclawWorkspaceFileName(input) {
-    const raw = typeof input === 'string' ? input.trim() : '';
-    if (!raw) {
-        return { error: '文件名不能为空' };
+function getSkillImportSourceByApp(app) {
+    const normalizedApp = normalizeSkillImportSourceApp(app);
+    if (!normalizedApp) return null;
+    return SKILL_IMPORT_SOURCES.find((item) => item.app === normalizedApp) || null;
+}
+
+function parseSimpleSkillFrontmatter(content = '') {
+    const normalized = String(content || '').replace(/\r\n/g, '\n');
+    if (!normalized.startsWith('---\n')) {
+        return {};
     }
-    if (raw.includes('\0')) {
+    const endIndex = normalized.indexOf('\n---\n', 4);
+    if (endIndex <= 4) {
+        return {};
+    }
+    const frontmatterRaw = normalized.slice(4, endIndex);
+    const result = {};
+    const lines = frontmatterRaw.split('\n');
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+        const line = lines[lineIndex];
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue;
+        const matched = trimmed.match(/^([A-Za-z0-9_-]+)\s*:\s*(.*)$/);
+        if (!matched) continue;
+        const key = matched[1];
+        let value = matched[2] || '';
+        const indicator = value.trim();
+        if (/^[>|]/.test(indicator)) {
+            const blockLines = [];
+            let cursor = lineIndex + 1;
+            while (cursor < lines.length) {
+                const candidateLine = lines[cursor];
+                if (!candidateLine.trim()) {
+                    blockLines.push('');
+                    cursor += 1;
+                    continue;
+                }
+                if (/^\s/.test(candidateLine)) {
+                    blockLines.push(candidateLine);
+                    cursor += 1;
+                    continue;
+                }
+                break;
+            }
+            lineIndex = cursor - 1;
+            const indents = blockLines
+                .filter((item) => item.trim())
+                .map((item) => {
+                    const indentMatch = item.match(/^[ \t]*/);
+                    return indentMatch ? indentMatch[0].length : 0;
+                });
+            const commonIndent = indents.length ? Math.min(...indents) : 0;
+            const deindented = blockLines.map((item) => {
+                if (!item.trim()) return '';
+                return item.slice(commonIndent);
+            });
+            if (indicator.startsWith('>')) {
+                const paragraphs = [];
+                let paragraphLines = [];
+                for (const blockLine of deindented) {
+                    const blockTrimmed = blockLine.trim();
+                    if (!blockTrimmed) {
+                        if (paragraphLines.length) {
+                            paragraphs.push(paragraphLines.join(' '));
+                            paragraphLines = [];
+                        }
+                        continue;
+                    }
+                    paragraphLines.push(blockTrimmed);
+                }
+                if (paragraphLines.length) {
+                    paragraphs.push(paragraphLines.join(' '));
+                }
+                value = paragraphs.join('\n');
+            } else {
+                value = deindented.join('\n');
+            }
+        }
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith('\'') && value.endsWith('\''))) {
+            value = value.slice(1, -1);
+        }
+        result[key] = value.trim();
+    }
+    return result;
+}
+
+function stripMarkdownFrontmatter(content = '') {
+    const normalized = String(content || '').replace(/\r\n/g, '\n');
+    if (!normalized.startsWith('---\n')) {
+        return normalized;
+    }
+    const endIndex = normalized.indexOf('\n---\n', 4);
+    if (endIndex <= 4) {
+        return normalized;
+    }
+    return normalized.slice(endIndex + 5);
+}
+
+function extractSkillDescriptionFromMarkdown(content = '') {
+    const normalized = String(content || '').replace(/\r\n/g, '\n');
+    const lines = normalized.split('\n');
+    let inFence = false;
+    for (const line of lines) {
+        const trimmedStart = line.trimStart();
+        if (trimmedStart.startsWith('```')) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence) continue;
+        if (/^( {4}|\t)/.test(line)) continue;
+        const trimmed = line.trim();
+        if (!trimmed) continue;
+        if (trimmed.startsWith('#')) continue;
+        if (trimmed.startsWith('---')) continue;
+        if (/^([A-Za-z0-9_-]+)\s*:\s*/.test(trimmed)) continue;
+        return trimmed.slice(0, 200);
+    }
+    return '';
+}
+
+function readCodexSkillMetadata(skillPath) {
+    const skillFile = path.join(skillPath, 'SKILL.md');
+    if (!fs.existsSync(skillFile)) {
+        return {
+            hasSkillFile: false,
+            displayName: '',
+            description: ''
+        };
+    }
+    try {
+        const raw = fs.readFileSync(skillFile, 'utf-8');
+        const content = stripUtf8Bom(raw);
+        const frontmatter = parseSimpleSkillFrontmatter(content);
+        const contentWithoutFrontmatter = stripMarkdownFrontmatter(content);
+        const heading = contentWithoutFrontmatter.match(/^\s*#\s+(.+)$/m);
+        const displayName = typeof frontmatter.name === 'string' && frontmatter.name.trim()
+            ? frontmatter.name.trim()
+            : (heading && heading[1] ? heading[1].trim() : '');
+        const description = typeof frontmatter.description === 'string' && frontmatter.description.trim()
+            ? frontmatter.description.trim().slice(0, 200)
+            : extractSkillDescriptionFromMarkdown(contentWithoutFrontmatter);
+        return {
+            hasSkillFile: true,
+            displayName,
+            description
+        };
+    } catch (e) {
+        return {
+            hasSkillFile: false,
+            displayName: '',
+            description: ''
+        };
+    }
+}
+
+function getCodexSkillEntryInfoByName(entryName) {
+    const targetPath = path.join(CODEX_SKILLS_DIR, entryName);
+    const normalized = normalizeCodexSkillName(entryName);
+    if (normalized.error) {
+        return null;
+    }
+    const relativePath = path.relative(CODEX_SKILLS_DIR, targetPath);
+    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+        return null;
+    }
+
+    try {
+        const lstat = fs.lstatSync(targetPath);
+        const isSymbolicLink = lstat.isSymbolicLink();
+        if (!lstat.isDirectory() && !isSymbolicLink) {
+            return null;
+        }
+        if (isSymbolicLink && !isSkillDirectoryEntry(entryName)) {
+            return null;
+        }
+        const metadata = readCodexSkillMetadata(targetPath);
+        return {
+            name: entryName,
+            path: targetPath,
+            hasSkillFile: !!metadata.hasSkillFile,
+            displayName: metadata.displayName || entryName,
+            description: metadata.description || '',
+            sourceType: isSymbolicLink ? 'symlink' : 'directory',
+            updatedAt: Number.isFinite(lstat.mtimeMs) ? Math.floor(lstat.mtimeMs) : 0
+        };
+    } catch (e) {
+        return null;
+    }
+}
+
+function listCodexSkills() {
+    if (!fs.existsSync(CODEX_SKILLS_DIR)) {
+        return {
+            root: CODEX_SKILLS_DIR,
+            exists: false,
+            items: []
+        };
+    }
+    try {
+        const entries = fs.readdirSync(CODEX_SKILLS_DIR, { withFileTypes: true });
+        const items = entries
+            .map((entry) => {
+                const name = entry && entry.name ? entry.name : '';
+                if (!name || name.startsWith('.')) return null;
+                return getCodexSkillEntryInfoByName(name);
+            })
+            .filter(Boolean)
+            .sort((a, b) => a.displayName.localeCompare(b.displayName, 'zh-Hans-CN'));
+        return {
+            root: CODEX_SKILLS_DIR,
+            exists: true,
+            items
+        };
+    } catch (e) {
+        return { error: `读取 skills 目录失败: ${e.message}` };
+    }
+}
+
+function listSkillEntriesByRoot(rootDir) {
+    if (!rootDir || !fs.existsSync(rootDir)) {
+        return [];
+    }
+    try {
+        const entries = fs.readdirSync(rootDir, { withFileTypes: true });
+        return entries
+            .map((entry) => {
+                const name = entry && entry.name ? entry.name : '';
+                if (!name || name.startsWith('.')) return null;
+                const normalized = normalizeCodexSkillName(name);
+                if (normalized.error) return null;
+                const skillPath = path.join(rootDir, name);
+                const relativePath = path.relative(rootDir, skillPath);
+                if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+                    return null;
+                }
+                try {
+                    const lstat = fs.lstatSync(skillPath);
+                    const isSymbolicLink = lstat.isSymbolicLink();
+                    if (!lstat.isDirectory() && !isSymbolicLink) {
+                        return null;
+                    }
+                    if (isSymbolicLink) {
+                        const realPath = fs.realpathSync(skillPath);
+                        const realStat = fs.statSync(realPath);
+                        if (!realStat.isDirectory()) {
+                            return null;
+                        }
+                    }
+                    return {
+                        name,
+                        path: skillPath,
+                        sourceType: isSymbolicLink ? 'symlink' : 'directory'
+                    };
+                } catch (e) {
+                    return null;
+                }
+            })
+            .filter(Boolean);
+    } catch (e) {
+        return [];
+    }
+}
+
+function scanUnmanagedCodexSkills() {
+    const existing = listCodexSkills();
+    if (existing.error) {
+        return { error: existing.error };
+    }
+    const existingNames = new Set((Array.isArray(existing.items) ? existing.items : [])
+        .map((item) => (item && typeof item.name === 'string' ? item.name.trim() : ''))
+        .filter(Boolean));
+
+    const items = [];
+    for (const source of SKILL_IMPORT_SOURCES) {
+        const sourceEntries = listSkillEntriesByRoot(source.dir);
+        for (const entry of sourceEntries) {
+            if (existingNames.has(entry.name)) {
+                continue;
+            }
+            const metadata = readCodexSkillMetadata(entry.path);
+            items.push({
+                key: `${source.app}:${entry.name}`,
+                name: entry.name,
+                displayName: metadata.displayName || entry.name,
+                description: metadata.description || '',
+                sourceApp: source.app,
+                sourceLabel: source.label,
+                sourcePath: entry.path,
+                sourceType: entry.sourceType,
+                hasSkillFile: !!metadata.hasSkillFile
+            });
+        }
+    }
+
+    items.sort((a, b) => {
+        const nameCompare = a.displayName.localeCompare(b.displayName, 'zh-Hans-CN');
+        if (nameCompare !== 0) return nameCompare;
+        return a.sourceLabel.localeCompare(b.sourceLabel, 'zh-Hans-CN');
+    });
+
+    return {
+        root: CODEX_SKILLS_DIR,
+        items,
+        sources: SKILL_IMPORT_SOURCES.map((source) => ({
+            app: source.app,
+            label: source.label,
+            path: source.dir,
+            exists: fs.existsSync(source.dir)
+        }))
+    };
+}
+
+function importCodexSkills(params = {}) {
+    const rawItems = Array.isArray(params.items) ? params.items : [];
+    if (!rawItems.length) {
+        return { error: '请先选择要导入的 skill' };
+    }
+
+    ensureDir(CODEX_SKILLS_DIR);
+
+    const imported = [];
+    const failed = [];
+    const dedup = new Set();
+
+    for (const rawItem of rawItems) {
+        const safeItem = rawItem && typeof rawItem === 'object' ? rawItem : {};
+        const normalizedName = normalizeCodexSkillName(safeItem.name);
+        if (normalizedName.error) {
+            failed.push({
+                name: safeItem && safeItem.name ? String(safeItem.name) : '',
+                sourceApp: safeItem && safeItem.sourceApp ? String(safeItem.sourceApp) : '',
+                error: normalizedName.error
+            });
+            continue;
+        }
+        const source = getSkillImportSourceByApp(safeItem.sourceApp);
+        if (!source) {
+            failed.push({
+                name: normalizedName.name,
+                sourceApp: safeItem && safeItem.sourceApp ? String(safeItem.sourceApp) : '',
+                error: '来源应用不支持'
+            });
+            continue;
+        }
+        const dedupKey = `${source.app}:${normalizedName.name}`;
+        if (dedup.has(dedupKey)) {
+            continue;
+        }
+        dedup.add(dedupKey);
+
+        const sourcePath = path.join(source.dir, normalizedName.name);
+        const sourceRelative = path.relative(source.dir, sourcePath);
+        if (sourceRelative.startsWith('..') || path.isAbsolute(sourceRelative)) {
+            failed.push({
+                name: normalizedName.name,
+                sourceApp: source.app,
+                error: '来源路径非法'
+            });
+            continue;
+        }
+        if (!fs.existsSync(sourcePath)) {
+            failed.push({
+                name: normalizedName.name,
+                sourceApp: source.app,
+                error: '来源 skill 不存在'
+            });
+            continue;
+        }
+
+        const targetPath = path.join(CODEX_SKILLS_DIR, normalizedName.name);
+        const targetRelative = path.relative(CODEX_SKILLS_DIR, targetPath);
+        if (targetRelative.startsWith('..') || path.isAbsolute(targetRelative)) {
+            failed.push({
+                name: normalizedName.name,
+                sourceApp: source.app,
+                error: '目标路径非法'
+            });
+            continue;
+        }
+        if (fs.existsSync(targetPath)) {
+            failed.push({
+                name: normalizedName.name,
+                sourceApp: source.app,
+                error: 'Codex 中已存在同名 skill'
+            });
+            continue;
+        }
+
+        let copiedToTarget = false;
+        try {
+            const lstat = fs.lstatSync(sourcePath);
+            if (!lstat.isDirectory() && !lstat.isSymbolicLink()) {
+                failed.push({
+                    name: normalizedName.name,
+                    sourceApp: source.app,
+                    error: '来源不是技能目录'
+                });
+                continue;
+            }
+            const sourceDirForCopy = lstat.isSymbolicLink() ? fs.realpathSync(sourcePath) : sourcePath;
+            const sourceStat = fs.statSync(sourceDirForCopy);
+            if (!sourceStat.isDirectory()) {
+                failed.push({
+                    name: normalizedName.name,
+                    sourceApp: source.app,
+                    error: '来源 skill 无法读取'
+                });
+                continue;
+            }
+            const visitedRealPaths = new Set([sourceDirForCopy]);
+            copyDirRecursive(sourceDirForCopy, targetPath, {
+                dereferenceSymlinks: true,
+                visitedRealPaths
+            });
+            copiedToTarget = true;
+            imported.push({
+                name: normalizedName.name,
+                sourceApp: source.app,
+                sourceLabel: source.label,
+                path: targetPath
+            });
+        } catch (e) {
+            if (!copiedToTarget && fs.existsSync(targetPath)) {
+                try {
+                    removeDirectoryRecursive(targetPath);
+                } catch (_) {}
+            }
+            failed.push({
+                name: normalizedName.name,
+                sourceApp: source.app,
+                error: e && e.message ? e.message : '导入失败'
+            });
+        }
+    }
+
+    return {
+        success: failed.length === 0,
+        imported,
+        failed,
+        root: CODEX_SKILLS_DIR
+    };
+}
+
+function removeDirectoryRecursive(targetPath) {
+    if (typeof fs.rmSync === 'function') {
+        fs.rmSync(targetPath, { recursive: true, force: false });
+        return;
+    }
+    fs.rmdirSync(targetPath, { recursive: true });
+}
+
+function deleteCodexSkills(params = {}) {
+    const rawList = Array.isArray(params.names) ? params.names : [];
+    const uniqueNames = Array.from(new Set(rawList
+        .map((item) => (typeof item === 'string' ? item.trim() : ''))
+        .filter(Boolean)));
+    if (!uniqueNames.length) {
+        return { error: '请先选择要删除的 skill' };
+    }
+
+    const deleted = [];
+    const failed = [];
+    for (const rawName of uniqueNames) {
+        const normalized = normalizeCodexSkillName(rawName);
+        if (normalized.error) {
+            failed.push({ name: rawName, error: normalized.error });
+            continue;
+        }
+
+        const skillPath = path.join(CODEX_SKILLS_DIR, normalized.name);
+        const relativePath = path.relative(CODEX_SKILLS_DIR, skillPath);
+        if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+            failed.push({ name: normalized.name, error: '技能路径非法' });
+            continue;
+        }
+        if (!fs.existsSync(skillPath)) {
+            failed.push({ name: normalized.name, error: 'skill 不存在' });
+            continue;
+        }
+
+        try {
+            const stat = fs.lstatSync(skillPath);
+            if (!stat.isDirectory() && !stat.isSymbolicLink()) {
+                failed.push({ name: normalized.name, error: '仅支持删除技能目录' });
+                continue;
+            }
+            removeDirectoryRecursive(skillPath);
+            deleted.push(normalized.name);
+        } catch (e) {
+            failed.push({
+                name: normalized.name,
+                error: e && e.message ? e.message : '删除失败'
+            });
+        }
+    }
+
+    return {
+        success: failed.length === 0,
+        deleted,
+        failed,
+        root: CODEX_SKILLS_DIR
+    };
+}
+
+function readAgentsFile(params = {}) {
+    const filePath = resolveAgentsFilePath(params);
+    const dirCheck = validateAgentsBaseDir(filePath);
+    if (dirCheck.error) {
+        return { error: dirCheck.error };
+    }
+
+    if (!fs.existsSync(filePath)) {
+        return {
+            exists: false,
+            path: filePath,
+            content: '',
+            lineEnding: os.EOL === '\r\n' ? '\r\n' : '\n'
+        };
+    }
+
+    try {
+        const raw = fs.readFileSync(filePath, 'utf-8');
+        return {
+            exists: true,
+            path: filePath,
+            content: stripUtf8Bom(raw),
+            lineEnding: detectLineEnding(raw)
+        };
+    } catch (e) {
+        return { error: `读取 AGENTS.md 失败: ${e.message}` };
+    }
+}
+
+function applyAgentsFile(params = {}) {
+    const filePath = resolveAgentsFilePath(params);
+    const dirCheck = validateAgentsBaseDir(filePath);
+    if (dirCheck.error) {
+        return { error: dirCheck.error };
+    }
+
+    const content = typeof params.content === 'string' ? params.content : '';
+    const lineEnding = params.lineEnding === '\r\n' ? '\r\n' : '\n';
+    const normalized = normalizeLineEnding(content, lineEnding);
+    const finalContent = ensureUtf8Bom(normalized);
+
+    try {
+        fs.writeFileSync(filePath, finalContent, 'utf-8');
+        return { success: true, path: filePath };
+    } catch (e) {
+        return { error: `写入 AGENTS.md 失败: ${e.message}` };
+    }
+}
+
+function resolveOpenclawWorkspaceDir(config) {
+    const workspace = config
+        && config.agents
+        && config.agents.defaults
+        && typeof config.agents.defaults.workspace === 'string'
+        ? config.agents.defaults.workspace
+        : '';
+    const resolved = resolveHomePath(workspace);
+    if (!resolved) {
+        return OPENCLAW_WORKSPACE_DIR;
+    }
+    if (path.isAbsolute(resolved)) {
+        return resolved;
+    }
+    return path.join(OPENCLAW_DIR, resolved);
+}
+
+function normalizeOpenclawWorkspaceFileName(input) {
+    const raw = typeof input === 'string' ? input.trim() : '';
+    if (!raw) {
+        return { error: '文件名不能为空' };
+    }
+    if (raw.includes('\0')) {
         return { error: '文件名非法' };
     }
     if (raw.includes('/') || raw.includes('\\') || raw.includes('..')) {
@@ -1307,11 +2413,28 @@ async function buildConfigHealthReport(params = {}) {
     const config = status.config || {};
 
     if (status.isVirtual) {
+        const parseFailed = status.errorType === 'parse';
+        const readFailed = status.errorType === 'read';
         issues.push({
-            code: 'config-missing',
-            message: status.reason || '未检测到 config.toml',
-            suggestion: '在模板编辑器中确认应用配置，生成可用的 config.toml'
+            code: parseFailed ? 'config-parse-failed' : (readFailed ? 'config-read-failed' : 'config-missing'),
+            message: status.reason || (parseFailed
+                ? 'config.toml 解析失败'
+                : (readFailed ? '读取 config.toml 失败' : '未检测到 config.toml')),
+            suggestion: parseFailed
+                ? '修复 config.toml 语法错误后重试'
+                : (readFailed ? '检查文件权限后重试' : '在模板编辑器中确认应用配置，生成可用的 config.toml')
         });
+        if (parseFailed || readFailed) {
+            return {
+                ok: false,
+                issues,
+                summary: {
+                    currentProvider: '',
+                    currentModel: ''
+                },
+                remote: null
+            };
+        }
     }
 
     const providerName = typeof config.model_provider === 'string' ? config.model_provider.trim() : '';
@@ -1498,13 +2621,26 @@ function readConfigOrVirtualDefault() {
             return {
                 config: readConfig(),
                 isVirtual: false,
-                reason: ''
+                reason: '',
+                detail: '',
+                errorType: ''
             };
         } catch (e) {
+            const errorType = typeof e.configErrorType === 'string' && e.configErrorType.trim()
+                ? e.configErrorType.trim()
+                : 'read';
+            const publicReason = typeof e.configPublicReason === 'string' && e.configPublicReason.trim()
+                ? e.configPublicReason.trim()
+                : (errorType === 'parse' ? 'config.toml 解析失败' : '读取 config.toml 失败');
+            const detail = typeof e.configDetail === 'string' && e.configDetail.trim()
+                ? e.configDetail.trim()
+                : (e && e.message ? e.message : publicReason);
             return {
-                config: buildVirtualDefaultConfig(),
+                config: errorType === 'missing' ? buildVirtualDefaultConfig() : {},
                 isVirtual: true,
-                reason: e.message || '配置文件无效，已回退到默认模板'
+                reason: publicReason,
+                detail,
+                errorType
             };
         }
     }
@@ -1512,10 +2648,31 @@ function readConfigOrVirtualDefault() {
     return {
         config: buildVirtualDefaultConfig(),
         isVirtual: true,
-        reason: `配置文件不存在: ${CONFIG_FILE}`
+        reason: '未检测到 config.toml',
+        detail: `配置文件不存在: ${CONFIG_FILE}`,
+        errorType: 'missing'
     };
 }
 
+function hasConfigLoadError(result) {
+    return !!(result
+        && result.isVirtual
+        && (result.errorType === 'parse' || result.errorType === 'read'));
+}
+
+function printConfigLoadErrorAndMarkExit(result) {
+    const isReadError = result && result.errorType === 'read';
+    const detail = result && typeof result.detail === 'string' && result.detail.trim()
+        ? result.detail.trim()
+        : (isReadError ? '读取配置文件失败' : '配置文件解析失败');
+    console.error(`\n错误: ${isReadError ? '读取 config.toml 失败' : '配置文件解析失败'}`);
+    console.error(`  详情: ${detail}`);
+    console.error(`  路径: ${CONFIG_FILE}`);
+    console.error(`  建议: ${isReadError ? '检查文件权限后重试' : '修复 config.toml 语法后重试'}`);
+    console.error();
+    process.exitCode = 1;
+}
+
 function normalizeTopLevelConfigWithTemplate(template, selectedProvider, selectedModel) {
     let content = typeof template === 'string' ? template : '';
     if (!content.trim()) {
@@ -1656,6 +2813,9 @@ function addProviderToConfig(params = {}) {
 
     if (!name) return { error: '名称不能为空' };
     if (!url) return { error: 'URL 不能为空' };
+    if (!isValidProviderName(name)) {
+        return { error: '名称仅支持字母/数字/._-' };
+    }
     if (isReservedProviderNameForCreation(name)) {
         return { error: 'local provider 为系统保留名称，不可新增' };
     }
@@ -1687,24 +2847,20 @@ function addProviderToConfig(params = {}) {
         return { error: `config.toml 解析失败: ${e.message}` };
     }
 
-    if (!parsed.model_providers || typeof parsed.model_providers !== 'object') {
-        parsed.model_providers = {};
-    }
-
-    if (parsed.model_providers[name]) {
+    const providerHeaderSegmentKeySet = collectModelProviderHeaderSegmentKeySet(content);
+    const normalizedProviders = isPlainObject(parsed.model_providers)
+        ? normalizeLegacyModelProviders(parsed.model_providers, providerHeaderSegmentKeySet)
+        : {};
+    if (normalizedProviders && normalizedProviders[name]) {
         return { error: '提供商已存在' };
     }
 
-    const escapeTomlString = (value) => String(value || '')
-        .replace(/\\/g, '\\\\')
-        .replace(/"/g, '\\"');
-
     const lineEnding = content.includes('\r\n') ? '\r\n' : '\n';
-    const safeName = escapeTomlString(name);
-    const safeUrl = escapeTomlString(url);
-    const safeKey = escapeTomlString(key);
+    const safeName = escapeTomlBasicString(name);
+    const safeUrl = escapeTomlBasicString(url);
+    const safeKey = escapeTomlBasicString(key);
     const block = [
-        `[model_providers.${safeName}]`,
+        buildModelProviderTableHeader(name),
         `name = "${safeName}"`,
         `base_url = "${safeUrl}"`,
         `wire_api = "responses"`,
@@ -1804,8 +2960,36 @@ function performProviderDeletion(name, options = {}) {
     const content = fs.readFileSync(CONFIG_FILE, 'utf-8');
     const lineEnding = content.includes('\r\n') ? '\r\n' : '\n';
     const hasBom = content.charCodeAt(0) === 0xFEFF;
-    const safeName = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const sectionRegex = new RegExp(`\\[\\s*model_providers\\s*\\.\\s*(?:"${safeName}"|'${safeName}'|${safeName})\\s*\\]`);
+    const providerConfig = config.model_providers[name];
+    const providerSegments = providerConfig && Array.isArray(providerConfig.__codexmate_legacy_segments)
+        ? providerConfig.__codexmate_legacy_segments
+        : null;
+    const providerSegmentVariants = (() => {
+        const variants = [];
+        const seen = new Set();
+        const pushVariant = (segments) => {
+            const normalized = normalizeLegacySegments(segments);
+            const key = buildLegacySegmentsKey(normalized);
+            if (!key || seen.has(key)) return;
+            seen.add(key);
+            variants.push(normalized);
+        };
+        if (providerConfig && Array.isArray(providerConfig.__codexmate_legacy_segments)) {
+            pushVariant(providerConfig.__codexmate_legacy_segments);
+        }
+        if (providerConfig && Array.isArray(providerConfig.__codexmate_legacy_segment_variants)) {
+            for (const segments of providerConfig.__codexmate_legacy_segment_variants) {
+                pushVariant(segments);
+            }
+        }
+        if (providerSegments) {
+            pushVariant(providerSegments);
+        }
+        if (variants.length === 0) {
+            pushVariant(String(name || '').split('.').filter((item) => item));
+        }
+        return variants;
+    })();
 
     const remainingProviders = Object.keys(config.model_providers || {}).filter(item => item !== name);
     if (remainingProviders.length === 0) {
@@ -1844,17 +3028,25 @@ function performProviderDeletion(name, options = {}) {
     };
 
     let updatedContent = null;
-    const match = content.match(sectionRegex);
-    if (match) {
-        const startIdx = match.index;
-        const rest = content.slice(startIdx + match[0].length);
-        const nextIdx = rest.indexOf('[');
-        const endIdx = nextIdx === -1 ? content.length : (startIdx + match[0].length + nextIdx);
-
-        const removedContent = (content.slice(0, startIdx) + content.slice(endIdx))
-            .replace(/\n{3,}/g, lineEnding + lineEnding);
-
-        updatedContent = removedContent;
+    const combinedRanges = [];
+    for (const segments of providerSegmentVariants) {
+        combinedRanges.push(...findProviderSectionRanges(content, name, segments));
+        combinedRanges.push(...findProviderDescendantSectionRanges(content, segments));
+    }
+    if (combinedRanges.length === 0) {
+        combinedRanges.push(...findProviderSectionRanges(content, name, providerSegments));
+    }
+    if (combinedRanges.length > 0) {
+        const sorted = combinedRanges.sort((a, b) => b.start - a.start || b.end - a.end);
+        const seen = new Set();
+        let removedContent = content;
+        for (const range of sorted) {
+            const rangeKey = `${range.start}:${range.end}`;
+            if (seen.has(rangeKey)) continue;
+            seen.add(rangeKey);
+            removedContent = removedContent.slice(0, range.start) + removedContent.slice(range.end);
+        }
+        updatedContent = removedContent.replace(/\n{3,}/g, lineEnding + lineEnding);
     }
 
     if (updatedContent) {
@@ -4857,7 +6049,12 @@ async function cmdSetup() {
 
 // 显示当前状态
 function cmdStatus() {
-    const { config, isVirtual } = readConfigOrVirtualDefault();
+    const configResult = readConfigOrVirtualDefault();
+    if (hasConfigLoadError(configResult)) {
+        printConfigLoadErrorAndMarkExit(configResult);
+        return;
+    }
+    const { config, isVirtual } = configResult;
     const current = config.model_provider || '未设置';
     const currentModel = config.model || '未设置';
 
@@ -4873,7 +6070,12 @@ function cmdStatus() {
 
 // 列出所有提供商
 function cmdList() {
-    const { config, isVirtual } = readConfigOrVirtualDefault();
+    const configResult = readConfigOrVirtualDefault();
+    if (hasConfigLoadError(configResult)) {
+        printConfigLoadErrorAndMarkExit(configResult);
+        return;
+    }
+    const { config, isVirtual } = configResult;
     const providers = config.model_providers || {};
     const current = config.model_provider;
 
@@ -5028,6 +6230,10 @@ function cmdAdd(name, baseUrl, apiKey, silent = false) {
         }
         throw new Error('名称和URL必填');
     }
+    if (!isValidProviderName(providerName)) {
+        if (!silent) console.error('错误: 名称仅支持字母/数字/._-');
+        throw new Error('名称仅支持字母/数字/._-');
+    }
     if (isReservedProviderNameForCreation(providerName)) {
         if (!silent) console.error('错误: local provider 为系统保留名称，不可新增');
         throw new Error('local provider 为系统保留名称，不可新增');
@@ -5039,13 +6245,16 @@ function cmdAdd(name, baseUrl, apiKey, silent = false) {
         throw new Error('提供商已存在');
     }
 
+    const safeName = escapeTomlBasicString(providerName);
+    const safeBaseUrl = escapeTomlBasicString(providerBaseUrl);
+    const safeApiKey = escapeTomlBasicString(apiKey || '');
     const newBlock = `
-[model_providers.${providerName}]
-name = "${providerName}"
-base_url = "${providerBaseUrl}"
+${buildModelProviderTableHeader(providerName)}
+name = "${safeName}"
+base_url = "${safeBaseUrl}"
 wire_api = "responses"
 requires_openai_auth = false
-preferred_auth_method = "${apiKey || ''}"
+preferred_auth_method = "${safeApiKey}"
 request_max_retries = 4
 stream_max_retries = 10
 stream_idle_timeout_ms = 300000
@@ -5105,42 +6314,156 @@ function cmdUpdate(name, baseUrl, apiKey, silent = false, options = {}) {
     }
 
     const content = fs.readFileSync(CONFIG_FILE, 'utf-8');
-    const safeName = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-    const sectionRegex = new RegExp(`\\[\\s*model_providers\\s*\\.\\s*${safeName}\\s*\\]`);
-    const match = content.match(sectionRegex);
-    if (!match) {
+    const providerConfig = config.model_providers[name];
+    const providerSegments = providerConfig && Array.isArray(providerConfig.__codexmate_legacy_segments)
+        ? providerConfig.__codexmate_legacy_segments
+        : null;
+    const ranges = findProviderSectionRanges(content, name, providerSegments);
+    if (ranges.length === 0) {
         if (!silent) console.error('错误: 无法找到提供商配置块');
         throw new Error('无法找到提供商配置块');
     }
 
-    const startIdx = match.index;
-    const rest = content.slice(startIdx + match[0].length);
-    const nextIdx = rest.indexOf('[');
-    const endIdx = nextIdx === -1 ? content.length : (startIdx + match[0].length + nextIdx);
-
-    // 提取该提供商的配置块
-    const providerBlock = content.slice(startIdx, endIdx);
+    const replaceTomlStringField = (block, fieldName, rawValue) => {
+        const safeValue = escapeTomlBasicString(rawValue);
+        const escapedFieldName = escapeRegex(fieldName);
+        const multilineRanges = collectTomlMultilineStringRanges(block);
+        const tripleStartRegex = new RegExp(`^(\\s*${escapedFieldName}\\s*=\\s*)(\"\"\"|''')`, 'mg');
+        let tripleStartMatch = null;
+        let tripleCandidate;
+        while ((tripleCandidate = tripleStartRegex.exec(block)) !== null) {
+            if (isIndexInRanges(tripleCandidate.index, multilineRanges)) {
+                continue;
+            }
+            tripleStartMatch = tripleCandidate;
+            break;
+        }
+        if (tripleStartMatch) {
+            const prefixStart = tripleStartMatch.index;
+            const prefixEnd = prefixStart + tripleStartMatch[1].length;
+            const tripleQuote = tripleStartMatch[2];
+            const valueStart = prefixEnd + tripleQuote.length;
+            const quoteChar = tripleQuote[0];
+            let valueEnd = -1;
+            let closingRunLength = 0;
+            for (let i = valueStart; i < block.length; i++) {
+                if (block[i] !== quoteChar) continue;
+                let runEnd = i + 1;
+                while (runEnd < block.length && block[runEnd] === quoteChar) {
+                    runEnd++;
+                }
+                const runLength = runEnd - i;
+                if (runLength < tripleQuote.length) {
+                    i = runEnd - 1;
+                    continue;
+                }
+                if (tripleQuote === '"""') {
+                    let slashCount = 0;
+                    for (let j = i - 1; j >= valueStart && block[j] === '\\'; j--) {
+                        slashCount++;
+                    }
+                    if (slashCount % 2 !== 0) {
+                        continue;
+                    }
+                }
+                valueEnd = i;
+                closingRunLength = runLength;
+                break;
+            }
+            if (valueEnd === -1) {
+                throw new Error(`${fieldName} 使用了未闭合的多行 TOML 字符串，无法安全更新`);
+            }
+            const lineEndIndex = block.indexOf('\n', valueEnd + closingRunLength);
+            let tailEnd = lineEndIndex === -1 ? block.length : lineEndIndex;
+            if (lineEndIndex > 0 && block[lineEndIndex - 1] === '\r') {
+                tailEnd = lineEndIndex - 1;
+            }
+            const tail = block.slice(valueEnd + closingRunLength, tailEnd);
+            const tailMatch = tail.match(/^(\s+#.*)?\s*$/);
+            if (!tailMatch) {
+                throw new Error(`${fieldName} 多行字符串后的语法不受支持，无法安全更新`);
+            }
+            const commentSuffix = tailMatch[1] || '';
+            const replacementLine = `${block.slice(prefixStart, prefixEnd)}"${safeValue}"${commentSuffix}`;
+            return block.slice(0, prefixStart) + replacementLine + block.slice(tailEnd);
+        }
 
-    // 替换 base_url
-    let updatedBlock = providerBlock;
-    if (baseUrl) {
-        updatedBlock = updatedBlock.replace(
-            /^(base_url\s*=\s*)(["']).*?\2/m,
-            `$1$2${baseUrl}$2`
+        const withCommentRegex = new RegExp(
+            `^(\\s*${escapedFieldName}\\s*=\\s*)(?:"(?:\\\\.|[^"\\\\])*"|'[^'\\n]*')(\\s+#.*)?$`,
+            'mg'
         );
-    }
-
-    // 替换 preferred_auth_method (API Key)
-    if (apiKey !== undefined) {
-        updatedBlock = updatedBlock.replace(
-            /^(preferred_auth_method\s*=\s*)(["']).*?\2/m,
-            `$1$2${apiKey}$2`
+        let replaced = false;
+        let next = block.replace(
+            withCommentRegex,
+            (full, prefix, suffix = '', offset) => {
+                if (replaced || isIndexInRanges(offset, multilineRanges)) {
+                    return full;
+                }
+                replaced = true;
+                return `${prefix}"${safeValue}"${suffix}`;
+            }
         );
+        if (!replaced) {
+            const fallbackRegex = new RegExp(`^(\\s*${escapedFieldName}\\s*=\\s*)(.*?)(\\s+#.*)?$`, 'mg');
+            let fallbackReplaced = false;
+            const multilineRangesForNext = collectTomlMultilineStringRanges(next);
+            let fallbackMatch;
+            let fallbackCandidate;
+            while ((fallbackCandidate = fallbackRegex.exec(next)) !== null) {
+                if (isIndexInRanges(fallbackCandidate.index, multilineRangesForNext)) {
+                    continue;
+                }
+                fallbackMatch = fallbackCandidate;
+                break;
+            }
+            if (fallbackMatch) {
+                const existingValue = String(fallbackMatch[2] || '').trim();
+                const looksLikeMultilineArray = existingValue.startsWith('[') && !existingValue.endsWith(']');
+                const looksLikeMultilineInlineTable = existingValue.startsWith('{') && !existingValue.endsWith('}');
+                if (looksLikeMultilineArray || looksLikeMultilineInlineTable) {
+                    throw new Error(`${fieldName} 当前值是多行 TOML 结构，无法安全更新`);
+                }
+                const prefix = fallbackMatch[1];
+                const suffix = fallbackMatch[3] || '';
+                const replacement = `${prefix}"${safeValue}"${suffix}`;
+                next = `${next.slice(0, fallbackMatch.index)}${replacement}${next.slice(fallbackMatch.index + fallbackMatch[0].length)}`;
+                fallbackReplaced = true;
+            }
+            if (!fallbackReplaced) {
+                const keyIndentMatch = block.match(/^(\s*)[A-Za-z0-9_.-]+\s*=/m);
+                const indent = keyIndentMatch ? keyIndentMatch[1] : '';
+                const lineEnding = block.includes('\r\n') ? '\r\n' : '\n';
+                const tailMatch = block.match(/(\s*)$/);
+                const tail = tailMatch ? tailMatch[1] : '';
+                const body = block.slice(0, block.length - tail.length);
+                const separator = body.endsWith('\n') || body.endsWith('\r') ? '' : lineEnding;
+                next = `${body}${separator}${indent}${fieldName} = "${safeValue}"${tail}`;
+            }
+        }
+        return next;
+    };
+
+    let newContent = content;
+    const sorted = ranges.sort((a, b) => b.start - a.start);
+    for (const range of sorted) {
+        const providerBlock = newContent.slice(range.start, range.end);
+        let updatedBlock = providerBlock;
+        if (baseUrl) {
+            updatedBlock = replaceTomlStringField(updatedBlock, 'base_url', baseUrl);
+        }
+        if (apiKey !== undefined) {
+            updatedBlock = replaceTomlStringField(updatedBlock, 'preferred_auth_method', apiKey);
+        }
+        newContent = newContent.slice(0, range.start) + updatedBlock + newContent.slice(range.end);
     }
 
-    // 组合新的内容
-    const newContent = content.slice(0, startIdx) + updatedBlock + content.slice(endIdx);
-    writeConfig(newContent.trim());
+    const finalContent = newContent.trim();
+    try {
+        toml.parse(finalContent);
+    } catch (e) {
+        throw new Error(`更新后的 config.toml 无效: ${e.message}`);
+    }
+    writeConfig(finalContent);
 
     // 如果更新了 API Key 且该提供商是当前激活的，同步更新 auth.json
     const currentProvider = config.model_provider;
@@ -5368,17 +6691,57 @@ async function prepareCodexDirDownload() {
     }
 }
 
-function copyDirRecursive(srcDir, destDir) {
+function copyDirRecursive(srcDir, destDir, options = {}) {
+    const dereferenceSymlinks = !!(options && options.dereferenceSymlinks);
+    const visitedRealPaths = options && options.visitedRealPaths instanceof Set
+        ? options.visitedRealPaths
+        : new Set();
+    const childOptions = {
+        ...options,
+        dereferenceSymlinks,
+        visitedRealPaths
+    };
     ensureDir(destDir);
     const entries = fs.readdirSync(srcDir, { withFileTypes: true });
     for (const entry of entries) {
         const srcPath = path.join(srcDir, entry.name);
         const destPath = path.join(destDir, entry.name);
         if (entry.isDirectory()) {
-            copyDirRecursive(srcPath, destPath);
+            if (!dereferenceSymlinks) {
+                copyDirRecursive(srcPath, destPath, childOptions);
+                continue;
+            }
+            const realPath = fs.realpathSync(srcPath);
+            if (visitedRealPaths.has(realPath)) {
+                continue;
+            }
+            visitedRealPaths.add(realPath);
+            try {
+                copyDirRecursive(srcPath, destPath, childOptions);
+            } finally {
+                visitedRealPaths.delete(realPath);
+            }
         } else if (entry.isSymbolicLink()) {
-            const target = fs.readlinkSync(srcPath);
-            fs.symlinkSync(target, destPath);
+            if (dereferenceSymlinks) {
+                const realPath = fs.realpathSync(srcPath);
+                const realStat = fs.statSync(realPath);
+                if (realStat.isDirectory()) {
+                    if (visitedRealPaths.has(realPath)) {
+                        continue;
+                    }
+                    visitedRealPaths.add(realPath);
+                    try {
+                        copyDirRecursive(realPath, destPath, childOptions);
+                    } finally {
+                        visitedRealPaths.delete(realPath);
+                    }
+                } else {
+                    fs.copyFileSync(realPath, destPath);
+                }
+            } else {
+                const target = fs.readlinkSync(srcPath);
+                fs.symlinkSync(target, destPath);
+            }
         } else {
             fs.copyFileSync(srcPath, destPath);
         }
@@ -6185,6 +7548,7 @@ function createWebServer({ htmlPath, assetsDir, webDir, host, port, openBrowser
                                 serviceTier,
                                 modelReasoningEffort,
                                 configReady: !statusConfigResult.isVirtual,
+                                configErrorType: statusConfigResult.errorType || '',
                                 configNotice: statusConfigResult.reason || '',
                                 initNotice: consumeInitNotice()
                             };
@@ -6199,6 +7563,8 @@ function createWebServer({ htmlPath, assetsDir, webDir, host, port, openBrowser
                             const current = listConfig.model_provider;
                             result = {
                                 configReady: !listConfigResult.isVirtual,
+                                configErrorType: listConfigResult.errorType || '',
+                                configNotice: listConfigResult.reason || '',
                                 providers: Object.entries(providers).map(([name, p]) => ({
                                     name,
                                     url: p.base_url || '',
@@ -6273,6 +7639,18 @@ function createWebServer({ htmlPath, assetsDir, webDir, host, port, openBrowser
                         case 'apply-agents-file':
                             result = applyAgentsFile(params || {});
                             break;
+                        case 'list-codex-skills':
+                            result = listCodexSkills();
+                            break;
+                        case 'delete-codex-skills':
+                            result = deleteCodexSkills(params || {});
+                            break;
+                        case 'scan-unmanaged-codex-skills':
+                            result = scanUnmanagedCodexSkills();
+                            break;
+                        case 'import-codex-skills':
+                            result = importCodexSkills(params || {});
+                            break;
                         case 'get-openclaw-config':
                             result = readOpenclawConfigFile();
                             break;
@@ -6433,6 +7811,58 @@ function createWebServer({ htmlPath, assetsDir, webDir, host, port, openBrowser
                         case 'proxy-apply-provider':
                             result = applyBuiltinProxyProvider(params || {});
                             break;
+                        case 'workflow-list':
+                            result = listWorkflowDefinitions();
+                            break;
+                        case 'workflow-get':
+                            {
+                                const id = params && typeof params.id === 'string' ? params.id.trim() : '';
+                                if (!id) {
+                                    result = { error: 'workflow id is required' };
+                                } else {
+                                    result = getWorkflowDefinitionById(id);
+                                }
+                            }
+                            break;
+                        case 'workflow-validate':
+                            {
+                                const id = params && typeof params.id === 'string' ? params.id.trim() : '';
+                                if (!id) {
+                                    result = { ok: false, error: 'workflow id is required' };
+                                    break;
+                                }
+                                const input = params && params.input && typeof params.input === 'object' && !Array.isArray(params.input)
+                                    ? params.input
+                                    : {};
+                                result = validateWorkflowById(id, input);
+                            }
+                            break;
+                        case 'workflow-run':
+                            {
+                                const id = params && typeof params.id === 'string' ? params.id.trim() : '';
+                                if (!id) {
+                                    result = { error: 'workflow id is required' };
+                                    break;
+                                }
+                                const input = params && params.input && typeof params.input === 'object' && !Array.isArray(params.input)
+                                    ? params.input
+                                    : {};
+                                result = await runWorkflowById(id, input, {
+                                    allowWrite: !!(params && params.allowWrite),
+                                    dryRun: !!(params && params.dryRun)
+                                });
+                            }
+                            break;
+                        case 'workflow-runs':
+                            {
+                                const rawLimit = params && Number.isFinite(params.limit) ? params.limit : parseInt(params && params.limit, 10);
+                                const limit = Number.isFinite(rawLimit) ? Math.max(1, Math.floor(rawLimit)) : 20;
+                                result = {
+                                    runs: listWorkflowRunRecords(limit),
+                                    limit
+                                };
+                            }
+                            break;
                         default:
                             result = { error: '未知操作' };
                     }
@@ -6942,13 +8372,229 @@ async function cmdProxy(args = []) {
         return;
     }
 
-    if (subcommand === 'stop') {
-        await stopBuiltinProxyRuntime();
-        console.log('✓ 内建代理已停止\n');
+    if (subcommand === 'stop') {
+        await stopBuiltinProxyRuntime();
+        console.log('✓ 内建代理已停止\n');
+        return;
+    }
+
+    throw new Error(`未知 proxy 子命令: ${subcommand}`);
+}
+
+function parseWorkflowInputArg(rawInput) {
+    const raw = typeof rawInput === 'string' ? rawInput.trim() : '';
+    if (!raw) {
+        return {};
+    }
+    let content = raw;
+    if (raw.startsWith('@')) {
+        const filePath = path.resolve(raw.slice(1));
+        if (!fs.existsSync(filePath)) {
+            throw new Error(`工作流输入文件不存在: ${filePath}`);
+        }
+        content = fs.readFileSync(filePath, 'utf-8');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    } catch (e) {
+        throw new Error(`工作流输入 JSON 解析失败: ${e.message}`);
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('工作流输入必须是 JSON 对象');
+    }
+    return parsed;
+}
+
+function printWorkflowHelp() {
+    console.log('\n用法: codexmate workflow <list|get|validate|run|runs> [参数]');
+    console.log('  codexmate workflow list');
+    console.log('  codexmate workflow get diagnose-config');
+    console.log('  codexmate workflow validate safe-provider-switch --input \'{"provider":"e2e"}\'');
+    console.log('  codexmate workflow run diagnose-config --input \'{}\'');
+    console.log('  codexmate workflow run safe-provider-switch --input \'{"provider":"e2e","apply":true}\' --allow-write');
+    console.log('  codexmate workflow runs --limit 20');
+    console.log('参数:');
+    console.log('  --input <JSON|@file>  传入工作流输入');
+    console.log('  --allow-write         允许执行写入步骤');
+    console.log('  --dry-run             跳过写入步骤，仅预演');
+    console.log('  --limit <N>           读取最近执行记录数量（runs）');
+    console.log('  --json                以 JSON 输出');
+    console.log();
+}
+
+function parseWorkflowCliOptions(args = []) {
+    const options = {
+        inputRaw: '',
+        allowWrite: false,
+        dryRun: false,
+        limit: 20,
+        json: false
+    };
+    const rest = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i];
+        if (arg === '--allow-write') {
+            options.allowWrite = true;
+            continue;
+        }
+        if (arg === '--dry-run') {
+            options.dryRun = true;
+            continue;
+        }
+        if (arg === '--json') {
+            options.json = true;
+            continue;
+        }
+        if (arg === '--input') {
+            options.inputRaw = args[i + 1] || '';
+            i += 1;
+            continue;
+        }
+        if (arg.startsWith('--input=')) {
+            options.inputRaw = arg.slice('--input='.length);
+            continue;
+        }
+        if (arg === '--limit') {
+            const raw = args[i + 1];
+            i += 1;
+            const value = parseInt(raw, 10);
+            if (Number.isFinite(value)) {
+                options.limit = value;
+            }
+            continue;
+        }
+        if (arg.startsWith('--limit=')) {
+            const value = parseInt(arg.slice('--limit='.length), 10);
+            if (Number.isFinite(value)) {
+                options.limit = value;
+            }
+            continue;
+        }
+        rest.push(arg);
+    }
+    return { options, rest };
+}
+
+async function cmdWorkflow(args = []) {
+    const argv = Array.isArray(args) ? args : [];
+    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+        printWorkflowHelp();
+        return;
+    }
+    const subcommand = String(argv[0] || '').trim().toLowerCase();
+    const parsed = parseWorkflowCliOptions(argv.slice(1));
+    const options = parsed.options;
+    const rest = parsed.rest;
+
+    if (subcommand === 'list') {
+        const result = listWorkflowDefinitions();
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        const workflows = Array.isArray(result.workflows) ? result.workflows : [];
+        console.log('\n可用工作流:');
+        for (const item of workflows) {
+            const mode = item.readOnly ? 'read-only' : 'read-write';
+            console.log(`  - ${item.id} (${mode}, steps=${item.stepCount})`);
+            if (item.description) {
+                console.log(`    ${item.description}`);
+            }
+        }
+        if (Array.isArray(result.warnings) && result.warnings.length > 0) {
+            console.log('\n警告:');
+            result.warnings.forEach((msg) => console.log(`  - ${msg}`));
+        }
+        console.log();
+        return;
+    }
+
+    if (subcommand === 'runs') {
+        const limit = Number.isFinite(options.limit) ? Math.max(1, Math.floor(options.limit)) : 20;
+        const runs = listWorkflowRunRecords(limit);
+        if (options.json) {
+            console.log(JSON.stringify({ runs, limit }, null, 2));
+            return;
+        }
+        console.log(`\n最近执行记录（${runs.length}/${limit}）:`);
+        for (const item of runs) {
+            const status = item && item.success ? 'OK' : 'FAIL';
+            console.log(`  - [${status}] ${item.workflowId || '(unknown)'} runId=${item.runId || ''} duration=${item.durationMs || 0}ms`);
+            if (item && item.error) {
+                console.log(`    error: ${item.error}`);
+            }
+        }
+        console.log();
+        return;
+    }
+
+    const workflowId = typeof rest[0] === 'string' ? rest[0].trim() : '';
+    if (!workflowId) {
+        throw new Error('workflow id is required');
+    }
+    const input = parseWorkflowInputArg(options.inputRaw);
+
+    if (subcommand === 'get') {
+        const result = getWorkflowDefinitionById(workflowId);
+        if (result.error) {
+            throw new Error(result.error);
+        }
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+
+    if (subcommand === 'validate') {
+        const result = validateWorkflowById(workflowId, input);
+        if (!result.ok) {
+            throw new Error(result.error || 'workflow validate failed');
+        }
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+        } else {
+            console.log(`✓ 工作流校验通过: ${workflowId}`);
+            if (Array.isArray(result.warnings) && result.warnings.length > 0) {
+                result.warnings.forEach((msg) => console.log(`  - ${msg}`));
+            }
+            console.log();
+        }
+        return;
+    }
+
+    if (subcommand === 'run') {
+        const result = await runWorkflowById(workflowId, input, {
+            allowWrite: options.allowWrite,
+            dryRun: options.dryRun
+        });
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+        } else {
+            if (result.error) {
+                console.error(`✗ 工作流执行失败: ${result.error}`);
+            } else {
+                console.log(`✓ 工作流执行完成: ${workflowId} (${result.durationMs || 0}ms)`);
+            }
+            const steps = Array.isArray(result.steps) ? result.steps : [];
+            for (const step of steps) {
+                const status = step.status || 'unknown';
+                const label = step.id || step.tool || '(step)';
+                console.log(`  - ${label}: ${status} (${step.durationMs || 0}ms)`);
+                if (step.error) {
+                    console.log(`    error: ${step.error}`);
+                }
+            }
+            if (result.runId) {
+                console.log(`  runId: ${result.runId}`);
+            }
+            console.log();
+        }
+        if (result.error) {
+            throw new Error(result.error);
+        }
         return;
     }
 
-    throw new Error(`未知 proxy 子命令: ${subcommand}`);
+    throw new Error(`未知 workflow 子命令: ${subcommand}`);
 }
 
 async function runProxyCommand(displayName, binNames, args = [], installTip = '') {
@@ -7103,6 +8749,7 @@ function buildMcpStatusPayload() {
         serviceTier,
         modelReasoningEffort,
         configReady: !statusConfigResult.isVirtual,
+        configErrorType: statusConfigResult.errorType || '',
         configNotice: statusConfigResult.reason || '',
         initNotice: consumeInitNotice()
     };
@@ -7115,6 +8762,8 @@ function buildMcpProviderListPayload() {
     const current = listConfig.model_provider;
     return {
         configReady: !listConfigResult.isVirtual,
+        configErrorType: listConfigResult.errorType || '',
+        configNotice: listConfigResult.reason || '',
         providers: Object.entries(providers).map(([name, p]) => ({
             name,
             url: p.base_url || '',
@@ -7167,6 +8816,541 @@ function normalizeMcpSource(value) {
     return null;
 }
 
+const BUILTIN_WORKFLOW_DEFINITIONS = Object.freeze({
+    'diagnose-config': {
+        id: 'diagnose-config',
+        name: 'Diagnose Config',
+        description: 'Collect status/providers/proxy snapshots for troubleshooting.',
+        readOnly: true,
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false
+        },
+        steps: [
+            { id: 'status', tool: 'codexmate.status.get', arguments: {} },
+            { id: 'providers', tool: 'codexmate.provider.list', arguments: {} },
+            { id: 'proxy', tool: 'codexmate.proxy.status', arguments: {} }
+        ]
+    },
+    'safe-provider-switch': {
+        id: 'safe-provider-switch',
+        name: 'Safe Provider Switch',
+        description: 'Build template for a provider switch and optionally apply it.',
+        readOnly: false,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                provider: { type: 'string' },
+                model: { type: 'string' },
+                serviceTier: { type: 'string' },
+                reasoningEffort: { type: 'string' },
+                apply: { type: 'boolean' }
+            },
+            required: ['provider'],
+            additionalProperties: false
+        },
+        steps: [
+            { id: 'providers', tool: 'codexmate.provider.list', arguments: {} },
+            {
+                id: 'template',
+                tool: 'codexmate.config.template.get',
+                arguments: {
+                    provider: '{{input.provider}}',
+                    model: '{{input.model}}',
+                    serviceTier: '{{input.serviceTier}}',
+                    reasoningEffort: '{{input.reasoningEffort}}'
+                }
+            },
+            {
+                id: 'apply',
+                tool: 'codexmate.config.template.apply',
+                when: { path: 'input.apply', equals: true },
+                arguments: {
+                    template: '{{steps.template.output.template}}'
+                }
+            },
+            {
+                id: 'statusAfter',
+                tool: 'codexmate.status.get',
+                when: { path: 'input.apply', equals: true },
+                arguments: {}
+            }
+        ]
+    },
+    'session-issue-pack': {
+        id: 'session-issue-pack',
+        name: 'Session Issue Pack',
+        description: 'Collect session detail and markdown export for issue reports.',
+        readOnly: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                source: { type: 'string' },
+                sessionId: { type: 'string' },
+                file: { type: 'string' },
+                maxMessages: { type: ['string', 'number'] }
+            },
+            additionalProperties: true
+        },
+        steps: [
+            {
+                id: 'detail',
+                tool: 'codexmate.session.detail',
+                arguments: {
+                    source: '{{input.source}}',
+                    sessionId: '{{input.sessionId}}',
+                    file: '{{input.file}}',
+                    maxMessages: '{{input.maxMessages}}'
+                }
+            },
+            {
+                id: 'export',
+                tool: 'codexmate.session.export',
+                arguments: {
+                    source: '{{input.source}}',
+                    sessionId: '{{input.sessionId}}',
+                    file: '{{input.file}}',
+                    maxMessages: '{{input.maxMessages}}'
+                }
+            }
+        ]
+    }
+});
+
+function cloneJson(value, fallback) {
+    try {
+        return JSON.parse(JSON.stringify(value));
+    } catch (_) {
+        return fallback;
+    }
+}
+
+function normalizeWorkflowId(value) {
+    const raw = typeof value === 'string' ? value.trim() : '';
+    if (!raw) return '';
+    if (!/^[a-zA-Z0-9._-]+$/.test(raw)) {
+        return '';
+    }
+    return raw.toLowerCase();
+}
+
+function normalizeWorkflowDefinition(raw, idHint = '', source = 'custom') {
+    const safe = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : null;
+    if (!safe) {
+        return { ok: false, error: 'workflow must be an object' };
+    }
+    const id = normalizeWorkflowId(safe.id || idHint);
+    if (!id) {
+        return { ok: false, error: 'workflow id is invalid' };
+    }
+    const name = typeof safe.name === 'string' && safe.name.trim()
+        ? safe.name.trim()
+        : id;
+    const description = typeof safe.description === 'string' ? safe.description.trim() : '';
+    const inputSchema = safe.inputSchema && typeof safe.inputSchema === 'object'
+        ? cloneJson(safe.inputSchema, { type: 'object', properties: {}, additionalProperties: true })
+        : { type: 'object', properties: {}, additionalProperties: true };
+    const stepsRaw = Array.isArray(safe.steps) ? safe.steps : [];
+    if (stepsRaw.length === 0) {
+        return { ok: false, error: 'workflow steps cannot be empty' };
+    }
+
+    const steps = [];
+    for (let i = 0; i < stepsRaw.length; i += 1) {
+        const item = stepsRaw[i];
+        if (!item || typeof item !== 'object' || Array.isArray(item)) {
+            return { ok: false, error: `workflow step #${i + 1} must be an object` };
+        }
+        const stepIdRaw = typeof item.id === 'string' && item.id.trim()
+            ? item.id.trim()
+            : `step${i + 1}`;
+        const stepId = normalizeWorkflowId(stepIdRaw);
+        if (!stepId) {
+            return { ok: false, error: `workflow step id invalid at #${i + 1}` };
+        }
+        const toolName = typeof item.tool === 'string' ? item.tool.trim() : '';
+        if (!toolName) {
+            return { ok: false, error: `workflow step "${stepId}" missing tool` };
+        }
+        const args = item.arguments && typeof item.arguments === 'object' && !Array.isArray(item.arguments)
+            ? cloneJson(item.arguments, {})
+            : {};
+        const when = item.when && typeof item.when === 'object' && !Array.isArray(item.when)
+            ? cloneJson(item.when, {})
+            : null;
+        steps.push({
+            id: stepId,
+            name: typeof item.name === 'string' ? item.name.trim() : '',
+            tool: toolName,
+            arguments: args,
+            when,
+            continueOnError: item.continueOnError === true,
+            write: item.write === true
+        });
+    }
+
+    return {
+        ok: true,
+        data: {
+            id,
+            name,
+            description,
+            source,
+            readOnly: safe.readOnly !== false,
+            inputSchema,
+            steps
+        }
+    };
+}
+
+function loadBuiltinWorkflowDefinitions() {
+    const items = [];
+    for (const [id, raw] of Object.entries(BUILTIN_WORKFLOW_DEFINITIONS)) {
+        const normalized = normalizeWorkflowDefinition(raw, id, 'builtin');
+        if (!normalized.ok) {
+            continue;
+        }
+        items.push(normalized.data);
+    }
+    return items;
+}
+
+function loadCustomWorkflowDefinitions() {
+    const parsed = readJsonObjectFromFile(WORKFLOW_DEFINITIONS_FILE, {});
+    if (!parsed.ok || !parsed.exists) {
+        return {
+            items: [],
+            warnings: parsed.ok ? [] : [parsed.error || 'workflow file parse failed']
+        };
+    }
+    const data = parsed.data && typeof parsed.data === 'object' ? parsed.data : {};
+    let list = [];
+    if (Array.isArray(data.workflows)) {
+        list = data.workflows;
+    } else if (data.workflows && typeof data.workflows === 'object') {
+        list = Object.entries(data.workflows).map(([id, item]) => ({ ...(item || {}), id }));
+    } else {
+        list = Object.entries(data).map(([id, item]) => ({ ...(item || {}), id }));
+    }
+
+    const items = [];
+    const warnings = [];
+    for (const item of list) {
+        const normalized = normalizeWorkflowDefinition(item, item && item.id ? item.id : '', 'custom');
+        if (!normalized.ok) {
+            warnings.push(normalized.error || 'invalid custom workflow');
+            continue;
+        }
+        items.push(normalized.data);
+    }
+    return { items, warnings };
+}
+
+function buildWorkflowRegistry() {
+    const registry = new Map();
+    const warnings = [];
+    const builtin = loadBuiltinWorkflowDefinitions();
+    for (const item of builtin) {
+        registry.set(item.id, item);
+    }
+    const custom = loadCustomWorkflowDefinitions();
+    for (const item of custom.items) {
+        if (registry.has(item.id)) {
+            warnings.push(`custom workflow id duplicated with builtin and ignored: ${item.id}`);
+            continue;
+        }
+        registry.set(item.id, item);
+    }
+    warnings.push(...custom.warnings);
+    return { registry, warnings };
+}
+
+function listWorkflowDefinitions() {
+    const { registry, warnings } = buildWorkflowRegistry();
+    const workflows = Array.from(registry.values())
+        .sort((a, b) => a.id.localeCompare(b.id))
+        .map((item) => ({
+            id: item.id,
+            name: item.name,
+            description: item.description,
+            source: item.source,
+            readOnly: item.readOnly !== false,
+            stepCount: Array.isArray(item.steps) ? item.steps.length : 0
+        }));
+    return {
+        workflows,
+        warnings
+    };
+}
+
+function getWorkflowDefinitionById(rawId) {
+    const id = normalizeWorkflowId(rawId);
+    if (!id) {
+        return { error: 'workflow id is required' };
+    }
+    const { registry, warnings } = buildWorkflowRegistry();
+    const workflow = registry.get(id);
+    if (!workflow) {
+        return { error: `workflow not found: ${id}` };
+    }
+    return {
+        workflow: cloneJson(workflow, {}),
+        warnings
+    };
+}
+
+function createWorkflowToolCatalog() {
+    return {
+        'codexmate.status.get': {
+            readOnly: true,
+            handler: async () => buildMcpStatusPayload()
+        },
+        'codexmate.provider.list': {
+            readOnly: true,
+            handler: async () => buildMcpProviderListPayload()
+        },
+        'codexmate.proxy.status': {
+            readOnly: true,
+            handler: async () => getBuiltinProxyStatus()
+        },
+        'codexmate.session.list': {
+            readOnly: true,
+            handler: async (args = {}) => {
+                const source = normalizeMcpSource(args.source);
+                if (source === null) {
+                    return { error: 'Invalid source. Must be codex, claude, or all' };
+                }
+                return {
+                    source: source || 'all',
+                    sessions: listAllSessions({
+                        ...args,
+                        source: source || 'all'
+                    })
+                };
+            }
+        },
+        'codexmate.session.detail': {
+            readOnly: true,
+            handler: async (args = {}) => readSessionDetail(args || {})
+        },
+        'codexmate.session.export': {
+            readOnly: true,
+            handler: async (args = {}) => exportSessionData(args || {})
+        },
+        'codexmate.config.template.get': {
+            readOnly: true,
+            handler: async (args = {}) => getConfigTemplate(args || {})
+        },
+        'codexmate.config.template.apply': {
+            readOnly: false,
+            handler: async (args = {}) => applyConfigTemplate(args || {})
+        }
+    };
+}
+
+function getWorkflowKnownToolsSet() {
+    return new Set(Object.keys(createWorkflowToolCatalog()));
+}
+
+function resolveWorkflowDefinitionWithToolMeta(workflow) {
+    const catalog = createWorkflowToolCatalog();
+    const safe = cloneJson(workflow, {});
+    safe.steps = (Array.isArray(safe.steps) ? safe.steps : []).map((step) => {
+        const tool = catalog[step.tool];
+        return {
+            ...step,
+            write: step.write === true || !!(tool && tool.readOnly === false)
+        };
+    });
+    return safe;
+}
+
+function validateWorkflowInputBySchema(inputSchema, input) {
+    const schema = inputSchema && typeof inputSchema === 'object' ? inputSchema : {};
+    if (schema.type && schema.type !== 'object') {
+        return { ok: false, error: `unsupported input schema type: ${schema.type}` };
+    }
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        return { ok: false, error: 'workflow input must be an object' };
+    }
+    const required = Array.isArray(schema.required) ? schema.required : [];
+    for (const key of required) {
+        if (!Object.prototype.hasOwnProperty.call(input, key)) {
+            return { ok: false, error: `missing required input field: ${key}` };
+        }
+    }
+    const properties = schema.properties && typeof schema.properties === 'object' ? schema.properties : {};
+    for (const [key, expected] of Object.entries(properties)) {
+        if (!Object.prototype.hasOwnProperty.call(input, key)) continue;
+        const value = input[key];
+        if (!expected || typeof expected !== 'object') continue;
+        const type = expected.type;
+        if (!type) continue;
+        const typeList = Array.isArray(type) ? type : [type];
+        const actualType = value === null ? 'null' : (Array.isArray(value) ? 'array' : typeof value);
+        const matched = typeList.some((candidate) => {
+            if (candidate === 'number') return typeof value === 'number' && Number.isFinite(value);
+            if (candidate === 'integer') return Number.isInteger(value);
+            if (candidate === 'array') return Array.isArray(value);
+            if (candidate === 'object') return value && typeof value === 'object' && !Array.isArray(value);
+            if (candidate === 'null') return value === null;
+            return actualType === candidate;
+        });
+        if (!matched) {
+            return { ok: false, error: `input field "${key}" type mismatch` };
+        }
+    }
+    return { ok: true };
+}
+
+function appendWorkflowRunRecord(record) {
+    ensureDir(path.dirname(WORKFLOW_RUNS_FILE));
+    const content = `${JSON.stringify(record)}\n`;
+    fs.appendFileSync(WORKFLOW_RUNS_FILE, content, { encoding: 'utf-8', mode: 0o600 });
+}
+
+function listWorkflowRunRecords(limit = 20) {
+    const max = Number.isFinite(limit) ? Math.max(1, Math.floor(limit)) : 20;
+    if (!fs.existsSync(WORKFLOW_RUNS_FILE)) {
+        return [];
+    }
+    let content = '';
+    try {
+        content = fs.readFileSync(WORKFLOW_RUNS_FILE, 'utf-8');
+    } catch (_) {
+        return [];
+    }
+    const rows = content
+        .split(/\r?\n/g)
+        .map((line) => line.trim())
+        .filter(Boolean);
+    const parsed = [];
+    for (let i = rows.length - 1; i >= 0; i -= 1) {
+        try {
+            const item = JSON.parse(rows[i]);
+            parsed.push(item);
+            if (parsed.length >= max) {
+                break;
+            }
+        } catch (_) {}
+    }
+    return parsed;
+}
+
+function validateWorkflowById(workflowId, input = {}) {
+    const definitionResult = getWorkflowDefinitionById(workflowId);
+    if (definitionResult.error) {
+        return { ok: false, error: definitionResult.error };
+    }
+    const workflow = resolveWorkflowDefinitionWithToolMeta(definitionResult.workflow);
+    const knownTools = getWorkflowKnownToolsSet();
+    const validation = validateWorkflowDefinition(workflow, { knownTools });
+    if (!validation.ok) {
+        return {
+            ok: false,
+            error: validation.error || 'workflow validation failed',
+            issues: validation.issues || []
+        };
+    }
+    const schemaValidation = validateWorkflowInputBySchema(workflow.inputSchema, input || {});
+    if (!schemaValidation.ok) {
+        return { ok: false, error: schemaValidation.error || 'workflow input validation failed' };
+    }
+    return {
+        ok: true,
+        workflow: {
+            id: workflow.id,
+            name: workflow.name,
+            readOnly: workflow.readOnly !== false,
+            stepCount: Array.isArray(workflow.steps) ? workflow.steps.length : 0
+        },
+        warnings: definitionResult.warnings || []
+    };
+}
+
+async function runWorkflowById(workflowId, input = {}, options = {}) {
+    const definitionResult = getWorkflowDefinitionById(workflowId);
+    if (definitionResult.error) {
+        return { error: definitionResult.error };
+    }
+    const workflow = resolveWorkflowDefinitionWithToolMeta(definitionResult.workflow);
+    const knownTools = getWorkflowKnownToolsSet();
+    const validation = validateWorkflowDefinition(workflow, { knownTools });
+    if (!validation.ok) {
+        return {
+            error: validation.error || 'workflow validation failed',
+            issues: validation.issues || []
+        };
+    }
+    const schemaValidation = validateWorkflowInputBySchema(workflow.inputSchema, input || {});
+    if (!schemaValidation.ok) {
+        return { error: schemaValidation.error || 'workflow input validation failed' };
+    }
+
+    const catalog = createWorkflowToolCatalog();
+    const allowWrite = options.allowWrite === true;
+    const dryRun = options.dryRun === true;
+    const runId = `wf-${Date.now()}-${crypto.randomBytes(3).toString('hex')}`;
+    const startedAt = toIsoTime(Date.now());
+
+    const execution = await executeWorkflowDefinition(workflow, input || {}, {
+        allowWrite,
+        dryRun,
+        invokeTool: async (toolName, args = {}) => {
+            const tool = catalog[toolName];
+            if (!tool) {
+                return { error: `workflow tool not supported: ${toolName}` };
+            }
+            if (!tool.readOnly && !allowWrite) {
+                return { error: `workflow requires write permission for tool: ${toolName}` };
+            }
+            return tool.handler(args || {});
+        }
+    });
+
+    const endedAt = toIsoTime(Date.now());
+    const record = {
+        runId,
+        workflowId: workflow.id,
+        workflowName: workflow.name,
+        success: execution.success === true,
+        error: execution.error || '',
+        allowWrite,
+        dryRun,
+        startedAt,
+        endedAt,
+        durationMs: execution.durationMs || 0,
+        steps: Array.isArray(execution.steps) ? execution.steps.map((step) => ({
+            id: step.id,
+            tool: step.tool,
+            status: step.status,
+            durationMs: step.durationMs || 0,
+            error: step.error || ''
+        })) : [],
+        input: cloneJson(input || {}, {})
+    };
+    try {
+        appendWorkflowRunRecord(record);
+    } catch (_) {}
+
+    return {
+        success: execution.success === true,
+        runId,
+        workflowId: workflow.id,
+        workflowName: workflow.name,
+        allowWrite,
+        dryRun,
+        startedAt: execution.startedAt || startedAt,
+        endedAt: execution.endedAt || endedAt,
+        durationMs: execution.durationMs || 0,
+        steps: execution.steps || [],
+        output: execution.output || null,
+        warnings: definitionResult.warnings || [],
+        ...(execution.error ? { error: execution.error } : {})
+    };
+}
+
 function createMcpTools(options = {}) {
     const allowWrite = !!options.allowWrite;
     const tools = [];
@@ -7362,6 +9546,89 @@ function createMcpTools(options = {}) {
         handler: async () => getBuiltinProxyStatus()
     });
 
+    pushTool({
+        name: 'codexmate.workflow.list',
+        description: 'List available workflows (builtin + custom).',
+        readOnly: true,
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        handler: async () => listWorkflowDefinitions()
+    });
+
+    pushTool({
+        name: 'codexmate.workflow.get',
+        description: 'Get one workflow definition by id.',
+        readOnly: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' }
+            },
+            required: ['id'],
+            additionalProperties: false
+        },
+        handler: async (args = {}) => {
+            const id = typeof args.id === 'string' ? args.id.trim() : '';
+            if (!id) {
+                return { error: 'workflow id is required' };
+            }
+            return getWorkflowDefinitionById(id);
+        }
+    });
+
+    pushTool({
+        name: 'codexmate.workflow.validate',
+        description: 'Validate workflow definition and input payload.',
+        readOnly: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                input: { type: 'object' }
+            },
+            required: ['id'],
+            additionalProperties: false
+        },
+        handler: async (args = {}) => {
+            const id = typeof args.id === 'string' ? args.id.trim() : '';
+            if (!id) {
+                return { ok: false, error: 'workflow id is required' };
+            }
+            const input = args.input && typeof args.input === 'object' && !Array.isArray(args.input)
+                ? args.input
+                : {};
+            return validateWorkflowById(id, input);
+        }
+    });
+
+    pushTool({
+        name: 'codexmate.workflow.run',
+        description: 'Run workflow by id. Write steps require allow-write mode.',
+        readOnly: true,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'string' },
+                input: { type: 'object' },
+                dryRun: { type: 'boolean' }
+            },
+            required: ['id'],
+            additionalProperties: false
+        },
+        handler: async (args = {}) => {
+            const id = typeof args.id === 'string' ? args.id.trim() : '';
+            if (!id) {
+                return { error: 'workflow id is required' };
+            }
+            const input = args.input && typeof args.input === 'object' && !Array.isArray(args.input)
+                ? args.input
+                : {};
+            return runWorkflowById(id, input, {
+                allowWrite,
+                dryRun: args.dryRun === true
+            });
+        }
+    });
+
     pushTool({
         name: 'codexmate.config.template.apply',
         description: 'Apply Codex TOML template and sync auth/model pointers.',
@@ -7636,6 +9903,50 @@ function createMcpResources() {
                     }]
                 };
             }
+        },
+        {
+            uri: 'codexmate://workflows',
+            name: 'Workflows',
+            description: 'Workflow list resource (builtin + custom).',
+            mimeType: 'application/json',
+            read: async () => ({
+                contents: [{
+                    uri: 'codexmate://workflows',
+                    mimeType: 'application/json',
+                    text: JSON.stringify(listWorkflowDefinitions(), null, 2)
+                }]
+            })
+        },
+        {
+            uri: 'codexmate://workflow-runs',
+            name: 'WorkflowRuns',
+            description: 'Recent workflow execution records. Supports ?limit=<N>.',
+            mimeType: 'application/json',
+            read: async (params = {}) => {
+                const uri = typeof params.uri === 'string' ? params.uri : 'codexmate://workflow-runs';
+                let limit = 20;
+                try {
+                    const parsed = new URL(uri);
+                    const rawLimit = parsed.searchParams.get('limit');
+                    if (rawLimit) {
+                        const parsedLimit = parseInt(rawLimit, 10);
+                        if (Number.isFinite(parsedLimit)) {
+                            limit = parsedLimit;
+                        }
+                    }
+                } catch (_) {}
+                const payload = {
+                    runs: listWorkflowRunRecords(limit),
+                    limit: Number.isFinite(limit) ? Math.max(1, Math.floor(limit)) : 20
+                };
+                return {
+                    contents: [{
+                        uri,
+                        mimeType: 'application/json',
+                        text: JSON.stringify(payload, null, 2)
+                    }]
+                };
+            }
         }
     ];
 }
@@ -7820,6 +10131,7 @@ async function main() {
         console.log('  codexmate delete-model <模型> 删除模型');
         console.log('  codexmate auth <list|import|switch|delete|status>  认证文件管理');
         console.log('  codexmate proxy <status|set|apply|enable|start|stop>  内建代理');
+        console.log('  codexmate workflow <list|get|validate|run|runs>  MCP 工作流中心');
         console.log('  codexmate run [--host <HOST>]    启动 Web 界面');
         console.log('  codexmate codex [参数...]  等同于 codex --yolo');
         console.log('  codexmate qwen [参数...]   等同于 qwen --yolo');
@@ -7846,6 +10158,7 @@ async function main() {
         case 'delete-model': cmdDeleteModel(args[1]); break;
         case 'auth': cmdAuth(args.slice(1)); break;
         case 'proxy': await cmdProxy(args.slice(1)); break;
+        case 'workflow': await cmdWorkflow(args.slice(1)); break;
         case 'run': cmdStart(parseStartOptions(args.slice(1))); break;
         case 'start':
             console.error('错误: 命令已更名为 "run"，请使用: codexmate run');