speccore 8.3.21 → 8.3.26

package/dist/core/unified-config.js

@@ -1,141 +1,915 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PROJECT_CONFIG = exports.DEFAULT_CONFIG = exports.PROJECT_CURRENT_SCHEMA_VERSION = exports.CURRENT_SCHEMA_VERSION = void 0;
 exports.loadConfig = loadConfig;
+exports.loadConfigWithMeta = loadConfigWithMeta;
+exports.loadProjectConfig = loadProjectConfig;
+exports.loadProjectConfigWithMeta = loadProjectConfigWithMeta;
+exports.getConfig = getConfig;
 exports.saveConfig = saveConfig;
+exports.saveProjectConfig = saveProjectConfig;
 exports.initConfig = initConfig;
+exports.initProjectConfig = initProjectConfig;
+exports.detectConfigDiff = detectConfigDiff;
+exports.requiresUserConfirmation = requiresUserConfirmation;
+exports.formatConfigDiff = formatConfigDiff;
+exports.upgradeConfig = upgradeConfig;
+exports.upgradeProjectConfig = upgradeProjectConfig;
+exports.resolveEnvVars = resolveEnvVars;
 /**
  * unified-config — .speccore.yml 统一配置入口
  *
- * 合并 SETTINGS.md / CONSTITUTION.md / TEAM.md 的配置到单一 YAML
- * 向后兼容：现有项目继续用旧文件，新项目自动用 .speccore.yml
+ * v8.3.25+: 配置版本化 + 结构校验 + 自动升级
+ * - schema_version: 配置结构版本号（CLI 升级时检测）
+ * - 运行时校验：加载时自动校验结构完整性
+ * - 自动补全：缺失字段自动填充默认值
+ * - 升级提示：schema_version < CURRENT_SCHEMA_VERSION 时警告
  */
 const fs_extra_1 = require("fs-extra");
 const path_1 = require("path");
 const logger_1 = require("../utils/logger");
-const DEFAULT_CONFIG = {
+/** 当前系统配置 schema 版本号（.speccore.yml） */
+exports.CURRENT_SCHEMA_VERSION = 1;
+/** 当前项目配置 schema 版本号（.speccore/PROJECT.yaml） */
+exports.PROJECT_CURRENT_SCHEMA_VERSION = 1;
+// ─────────────────────────────────────────
+// 系统配置默认值（.speccore.yml）
+// ─────────────────────────────────────────
+exports.DEFAULT_CONFIG = {
+    schema_version: exports.CURRENT_SCHEMA_VERSION,
+    quality_gates: { enforce_testing: true, enforce_review: true, require_pr: true },
+    arbitration: { enabled: true, mode: 'full' },
+    settings: {
+        assignee: { enabled: true, mode: 'loose' },
+        trace: { enabled: true, auto_annotate: true },
+        archive: { auto_cleanup: false },
+        plan: { parallel_suggest: true },
+        validation: { strict_mode: false },
+        sync: { auto_check: true },
+        patterns: { auto_save: 'smart' },
+        review: { check_assignee: false },
+    },
+    ask: {
+        routing: { mode: 'hybrid', high_threshold: 70, low_threshold: 45, auto_host_ai: true, cache_enabled: true, cache_min_hits: 3 },
+        rules: { force_host_ai: false },
+        llm_providers: [],
+    },
+    config_history: [],
+};
+// ─────────────────────────────────────────
+// 项目配置默认值（.speccore/PROJECT.yaml）
+// ─────────────────────────────────────────
+exports.DEFAULT_PROJECT_CONFIG = {
+    schema_version: exports.CURRENT_SCHEMA_VERSION,
     project: { name: 'my-project' },
-    tech_stack: {},
-    team: { members: [] },
     platforms: [],
-    git: { default_base: 'main', branch_prefix: 'feature/' },
+    git: { default_base: 'main', branch_prefix: 'feature/', protected_branches: ['main', 'master'] },
     code_scope: ['src/'],
-    conventions: {},
-    quality_gates: { enforce_testing: true, enforce_review: true, require_pr: true },
 };
 const CONFIG_PATH = (0, path_1.join)('.speccore.yml');
+const PROJECT_CONFIG_PATH = (0, path_1.join)('.speccore', 'PROJECT.yaml');
 async function loadConfig() {
-    if (await (0, fs_extra_1.pathExists)(CONFIG_PATH)) {
-        try {
-            const raw = await (0, fs_extra_1.readFile)(CONFIG_PATH, 'utf-8');
-            return { ...DEFAULT_CONFIG, ...parseYaml(raw) };
+    const { config, warnings } = await loadConfigWithMeta();
+    if (warnings.length > 0) {
+        for (const w of warnings)
+            logger_1.logger.warn(w);
+    }
+    return config;
+}
+/** 获取配置 + 元信息（warnings、是否迁移过） */
+async function loadConfigWithMeta() {
+    const warnings = [];
+    if (!(await (0, fs_extra_1.pathExists)(CONFIG_PATH))) {
+        warnings.push('⚠️ .speccore.yml 不存在，使用默认配置');
+        return { config: { ...exports.DEFAULT_CONFIG }, warnings, migrated: false };
+    }
+    try {
+        const raw = await (0, fs_extra_1.readFile)(CONFIG_PATH, 'utf-8');
+        const parsed = parseYaml(raw);
+        // v8.3.25+: 解析环境变量引用（如 apiKey: ${SPECCORE_LLM_KEY}）
+        const envResult = resolveEnvVars(parsed);
+        if (envResult.unresolved.length > 0) {
+            warnings.push(`⚠️ 以下环境变量未设置，配置项保持原样: ${envResult.unresolved.join(', ')}`);
+        }
+        // 1. 结构校验 + 自动补全
+        const validation = validateConfig(parsed);
+        if (!validation.valid) {
+            warnings.push(`⚠️ .speccore.yml 结构校验失败：`);
+            for (const issue of validation.issues.slice(0, 5)) {
+                warnings.push(`  - ${issue}`);
+            }
+            if (validation.issues.length > 5) {
+                warnings.push(`  ... 还有 ${validation.issues.length - 5} 项`);
+            }
+        }
+        // 用默认值深度合并（补全缺失字段）
+        const merged = deepMerge(exports.DEFAULT_CONFIG, parsed);
+        const config = merged;
+        // 2. 版本检测
+        if (config.schema_version < exports.CURRENT_SCHEMA_VERSION) {
+            warnings.push(`⚠️ .speccore.yml schema_version=${config.schema_version} < ${exports.CURRENT_SCHEMA_VERSION}，` +
+                `配置结构已过期。建议运行: speccore config --upgrade`);
+        }
+        else if (config.schema_version > exports.CURRENT_SCHEMA_VERSION) {
+            warnings.push(`⚠️ .speccore.yml schema_version=${config.schema_version} > ${exports.CURRENT_SCHEMA_VERSION}，` +
+                `CLI 版本可能过旧，建议升级 CLI`);
+        }
+        const migrated = config.schema_version !== exports.CURRENT_SCHEMA_VERSION || !validation.valid;
+        return { config, warnings, migrated };
+    }
+    catch (e) {
+        warnings.push(`⚠️ .speccore.yml 解析失败: ${e.message}，使用默认配置`);
+        return { config: { ...exports.DEFAULT_CONFIG }, warnings, migrated: false };
+    }
+}
+/** 加载项目配置（简化版） */
+async function loadProjectConfig() {
+    const { config, warnings } = await loadProjectConfigWithMeta();
+    if (warnings.length > 0) {
+        for (const w of warnings)
+            logger_1.logger.warn(w);
+    }
+    return config;
+}
+/** 获取项目配置 + 元信息 */
+async function loadProjectConfigWithMeta() {
+    const warnings = [];
+    if (!(await (0, fs_extra_1.pathExists)(PROJECT_CONFIG_PATH))) {
+        warnings.push('⚠️ .speccore/PROJECT.yaml 不存在，使用默认项目配置');
+        return { config: { ...exports.DEFAULT_PROJECT_CONFIG }, warnings, migrated: false };
+    }
+    try {
+        const raw = await (0, fs_extra_1.readFile)(PROJECT_CONFIG_PATH, 'utf-8');
+        const parsed = parseYaml(raw);
+        // 解析环境变量
+        const envResult = resolveEnvVars(parsed);
+        if (envResult.unresolved.length > 0) {
+            warnings.push(`⚠️ 以下环境变量未设置，配置项保持原样: ${envResult.unresolved.join(', ')}`);
+        }
+        // 1. 结构校验
+        const validation = validateProjectConfig(parsed);
+        if (!validation.valid) {
+            warnings.push(`⚠️ .speccore/PROJECT.yaml 结构校验失败：`);
+            for (const issue of validation.issues.slice(0, 5)) {
+                warnings.push(`  - ${issue}`);
+            }
+            if (validation.issues.length > 5) {
+                warnings.push(`  ... 还有 ${validation.issues.length - 5} 项`);
+            }
+        }
+        // 用默认值深度合并
+        const merged = deepMerge(exports.DEFAULT_PROJECT_CONFIG, parsed);
+        const config = merged;
+        // 2. 版本检测
+        if (config.schema_version < exports.PROJECT_CURRENT_SCHEMA_VERSION) {
+            warnings.push(`⚠️ .speccore/PROJECT.yaml schema_version=${config.schema_version} < ${exports.PROJECT_CURRENT_SCHEMA_VERSION}，` +
+                `配置结构已过期。建议运行: speccore config --upgrade --project`);
         }
-        catch (e) {
-            logger_1.logger.warn(`⚠️ .speccore.yml 解析失败，使用默认配置`);
+        else if (config.schema_version > exports.PROJECT_CURRENT_SCHEMA_VERSION) {
+            warnings.push(`⚠️ .speccore/PROJECT.yaml schema_version=${config.schema_version} > ${exports.PROJECT_CURRENT_SCHEMA_VERSION}，` +
+                `CLI 版本可能过旧，建议升级 CLI`);
         }
+        const migrated = config.schema_version !== exports.PROJECT_CURRENT_SCHEMA_VERSION || !validation.valid;
+        return { config, warnings, migrated };
+    }
+    catch (e) {
+        warnings.push(`⚠️ .speccore/PROJECT.yaml 解析失败: ${e.message}，使用默认配置`);
+        return { config: { ...exports.DEFAULT_PROJECT_CONFIG }, warnings, migrated: false };
     }
-    return DEFAULT_CONFIG;
 }
+/** 兼容旧代码：getConfig = loadConfig */
+async function getConfig() {
+    return loadConfig();
+}
+// ─────────────────────────────────────────
+// 配置保存（自动写入 schema_version）
+// ─────────────────────────────────────────
 async function saveConfig(config) {
-    const yaml = toYaml(config);
+    const enriched = { ...config, schema_version: exports.CURRENT_SCHEMA_VERSION };
+    const yaml = toYaml(enriched);
     await (0, fs_extra_1.writeFile)(CONFIG_PATH, yaml, 'utf-8');
 }
+async function saveProjectConfig(config) {
+    const enriched = { ...config, schema_version: exports.CURRENT_SCHEMA_VERSION };
+    const yaml = toProjectYaml(enriched);
+    await (0, fs_extra_1.ensureDir)((0, path_1.join)('.speccore'));
+    await (0, fs_extra_1.writeFile)(PROJECT_CONFIG_PATH, yaml, 'utf-8');
+}
 /**
- * 初始化时生成 .speccore.yml
+ * 初始化时生成 .speccore.yml（系统配置）
  */
-async function initConfig(projectName) {
-    const config = { ...DEFAULT_CONFIG };
-    if (projectName)
-        config.project.name = projectName;
-    await saveConfig(config);
-    logger_1.logger.info(`  📄 .speccore.yml 已生成`);
+async function initConfig() {
+    await saveConfig({ ...exports.DEFAULT_CONFIG });
+    logger_1.logger.info(`  📄 .speccore.yml 已生成 (schema_version=${exports.CURRENT_SCHEMA_VERSION})`);
 }
 /**
- * 简易 YAML 解析器（只处理简单 key-value + list）
+ * 初始化时生成 .speccore/PROJECT.yaml（项目配置）
+ */
+async function initProjectConfig(projectName) {
+    const config = {
+        ...exports.DEFAULT_PROJECT_CONFIG,
+        project: { ...exports.DEFAULT_PROJECT_CONFIG.project, name: projectName || 'my-project' },
+    };
+    await saveProjectConfig(config);
+    logger_1.logger.info(`  📄 .speccore/PROJECT.yaml 已生成 (schema_version=${exports.CURRENT_SCHEMA_VERSION})`);
+}
+/**
+ * 系统配置版本迁移注册表（.speccore.yml）
+ * 键 = 目标 schema_version，值 = 从上一版本升级到该版本需要执行的迁移步骤。
+ */
+const MIGRATIONS = {
+    // schema_version 1 是初始版本，无迁移步骤
+    1: [],
+    // 未来版本示例（预留）：
+    // 2: [
+    //   {
+    //     type: 'rename',
+    //     description: 'settings.assignee.mode: strict_mode → strict',
+    //     migrate: (cfg) => {
+    //       const old = (cfg as any).settings?.assignee?.strict_mode;
+    //       if (old !== undefined) {
+    //         (cfg.settings.assignee as any).mode = old ? 'strict' : 'loose';
+    //         delete (cfg.settings.assignee as any).strict_mode;
+    //         return true;
+    //       }
+    //       return false;
+    //     },
+    //   },
+    // ],
+};
+/**
+ * 项目配置版本迁移注册表（.speccore/PROJECT.yaml）
  */
+const PROJECT_MIGRATIONS = {
+    1: [],
+};
+/**
+ * 执行从当前 config.schema_version 到目标版本的所有迁移步骤。
+ * 返回迁移过程中产生的日志信息。
+ */
+function runMigrations(config, migrations, currentVersion) {
+    const logs = [];
+    const startVersion = config.schema_version;
+    for (let v = startVersion + 1; v <= currentVersion; v++) {
+        const steps = migrations[v];
+        if (!steps || steps.length === 0)
+            continue;
+        for (const step of steps) {
+            try {
+                const changed = step.migrate(config);
+                if (changed) {
+                    logs.push(`  [v${v}] ${step.description}`);
+                }
+            }
+            catch (e) {
+                logs.push(`  [v${v}] ⚠️ 迁移失败: ${step.description} — ${e.message}`);
+            }
+        }
+    }
+    return logs;
+}
+// ─────────────────────────────────────────
+// 枚举约束定义（字段路径 → 合法值列表）
+// ─────────────────────────────────────────
+/** 支持通配符 * 的路径模式 */
+const ENUM_CONSTRAINTS = {
+    'platforms.*.type': ['frontend', 'backend', 'infra'],
+    'arbitration.mode': ['full', 'l1-only', 'report-only'],
+    'settings.assignee.mode': ['strict', 'loose', 'off'],
+    'settings.patterns.auto_save': ['off', 'smart', 'aggressive'],
+    'ask.routing.mode': ['hybrid', 'cli-only', 'host-ai-only'],
+    'ask.llm_providers.*.type': ['ollama', 'openai', 'anthropic', 'custom'],
+};
+/**
+ * 按通配符路径模式遍历对象，获取所有匹配的值
+ * 示例: 'platforms.*.type' → [{path:'platforms.0.type', value:'frontend'}, ...]
+ */
+function getValuesAtPath(obj, pathPattern) {
+    const parts = pathPattern.split('.');
+    const results = [];
+    function traverse(current, currentPath, idx) {
+        if (idx >= parts.length) {
+            results.push({ path: currentPath.join('.'), value: current });
+            return;
+        }
+        const part = parts[idx];
+        if (part === '*') {
+            if (Array.isArray(current)) {
+                for (let i = 0; i < current.length; i++) {
+                    traverse(current[i], [...currentPath, String(i)], idx + 1);
+                }
+            }
+            else if (isPlainObject(current)) {
+                for (const key of Object.keys(current)) {
+                    traverse(current[key], [...currentPath, key], idx + 1);
+                }
+            }
+        }
+        else if (isPlainObject(current) && part in current) {
+            traverse(current[part], [...currentPath, part], idx + 1);
+        }
+    }
+    traverse(obj, [], 0);
+    return results;
+}
+/**
+ * 检测配置中的枚举值是否超出合法范围
+ */
+function checkEnumConstraints(config) {
+    const changes = [];
+    for (const [pattern, allowedValues] of Object.entries(ENUM_CONSTRAINTS)) {
+        const matches = getValuesAtPath(config, pattern);
+        for (const { path, value } of matches) {
+            if (typeof value === 'string' && !allowedValues.includes(value)) {
+                changes.push({
+                    path,
+                    current: [value],
+                    expected: allowedValues,
+                });
+            }
+        }
+    }
+    return changes;
+}
+/**
+ * 递归比较当前配置与目标配置（DEFAULT_CONFIG），检测所有差异
+ */
+function detectConfigDiff(current, target, path = '') {
+    const diff = { added: [], removed: [], typeChanged: [], enumChanged: [], structureChanged: [] };
+    // 根节点类型不同（极少发生，如整体从对象变成数组）
+    if (typeof current !== typeof target) {
+        if (path === '') {
+            diff.structureChanged.push({ path: '(root)', description: `根节点类型从 ${typeof current} 变为 ${typeof target}` });
+        }
+        return diff;
+    }
+    // 两者都是对象（非数组）
+    if (isPlainObject(current) && isPlainObject(target)) {
+        const currentKeys = Object.keys(current);
+        const targetKeys = Object.keys(target);
+        // 检测删除的字段（当前有，目标没有）
+        for (const key of currentKeys) {
+            if (!targetKeys.includes(key)) {
+                diff.removed.push(path ? `${path}.${key}` : key);
+            }
+        }
+        // 检测新增和变更的字段
+        for (const key of targetKeys) {
+            const currentVal = current[key];
+            const targetVal = target[key];
+            const childPath = path ? `${path}.${key}` : key;
+            if (!(key in current)) {
+                // 新增字段
+                diff.added.push(childPath);
+                continue;
+            }
+            // 两者都存在，递归比较
+            const childDiff = detectConfigDiff(currentVal, targetVal, childPath);
+            diff.added.push(...childDiff.added);
+            diff.removed.push(...childDiff.removed);
+            diff.typeChanged.push(...childDiff.typeChanged);
+            diff.enumChanged.push(...childDiff.enumChanged);
+            diff.structureChanged.push(...childDiff.structureChanged);
+        }
+        return diff;
+    }
+    // 两者都是数组
+    if (Array.isArray(current) && Array.isArray(target)) {
+        // 如果数组元素类型不同（如 string[] → object[]）
+        const currentElemType = current.length > 0 ? typeof current[0] : 'empty';
+        const targetElemType = target.length > 0 ? typeof target[0] : 'empty';
+        if (currentElemType !== targetElemType && currentElemType !== 'empty' && targetElemType !== 'empty') {
+            diff.structureChanged.push({
+                path: path || '(array)',
+                description: `数组元素类型从 ${currentElemType} 变为 ${targetElemType}`,
+            });
+        }
+        return diff;
+    }
+    // 一个是数组，一个不是
+    if (Array.isArray(current) !== Array.isArray(target)) {
+        diff.structureChanged.push({
+            path: path || '(value)',
+            description: `类型从 ${Array.isArray(current) ? 'array' : typeof current} 变为 ${Array.isArray(target) ? 'array' : typeof target}`,
+        });
+        return diff;
+    }
+    // 基本类型值不同（不算结构变更，只是值不同）
+    // 但可能涉及枚举值非法
+    const enumChanges = checkEnumConstraints(current);
+    diff.enumChanged.push(...enumChanges);
+    return diff;
+}
+/**
+ * 判断差异是否需要用户确认（新增字段除外，可自动处理）
+ */
+function requiresUserConfirmation(diff) {
+    return diff.removed.length > 0
+        || diff.typeChanged.length > 0
+        || diff.enumChanged.length > 0
+        || diff.structureChanged.length > 0;
+}
+/**
+ * 格式化差异为可读文本
+ */
+function formatConfigDiff(diff) {
+    const lines = [];
+    if (diff.added.length > 0) {
+        lines.push(`📌 新增字段（${diff.added.length} 项，将使用默认值）:`);
+        for (const p of diff.added)
+            lines.push(`   + ${p}`);
+    }
+    if (diff.removed.length > 0) {
+        lines.push(`⚠️  删除字段（${diff.removed.length} 项，配置已过时）:`);
+        for (const p of diff.removed)
+            lines.push(`   - ${p}`);
+    }
+    if (diff.typeChanged.length > 0) {
+        lines.push(`🔧 类型变更（${diff.typeChanged.length} 项，需人工确认）:`);
+        for (const t of diff.typeChanged)
+            lines.push(`   ~ ${t.path}: ${t.current} → ${t.expected}`);
+    }
+    if (diff.enumChanged.length > 0) {
+        lines.push(`📝 枚举值变更（${diff.enumChanged.length} 项，需人工确认）:`);
+        for (const e of diff.enumChanged) {
+            lines.push(`   ~ ${e.path}:`);
+            lines.push(`     当前: [${e.current.join(', ')}]`);
+            lines.push(`     目标: [${e.expected.join(', ')}]`);
+        }
+    }
+    if (diff.structureChanged.length > 0) {
+        lines.push(`🏗️  结构变更（${diff.structureChanged.length} 项，需人工确认）:`);
+        for (const s of diff.structureChanged)
+            lines.push(`   ~ ${s.path}: ${s.description}`);
+    }
+    return lines;
+}
+// ─────────────────────────────────────────
+// 配置升级（补全缺失字段 + 执行迁移 + 更新版本号）
+// ─────────────────────────────────────────
+async function upgradeConfig() {
+    const { config, warnings } = await loadConfigWithMeta();
+    if (config.schema_version === exports.CURRENT_SCHEMA_VERSION && warnings.length === 0) {
+        logger_1.logger.info(`✅ .speccore.yml 已经是 schema_version=${exports.CURRENT_SCHEMA_VERSION}，无需升级`);
+        return { config, warnings: [], migrated: false };
+    }
+    // 1. 检测配置差异（当前配置 vs 目标配置）
+    const diff = detectConfigDiff(config, exports.DEFAULT_CONFIG);
+    const needsConfirm = requiresUserConfirmation(diff);
+    if (needsConfirm) {
+        // 生成差异报告文件
+        const reportLines = [
+            '# .speccore.yml 升级差异报告',
+            '',
+            `生成时间: ${new Date().toLocaleString('zh-CN')}`,
+            `当前 schema_version: ${config.schema_version}`,
+            `目标 schema_version: ${exports.CURRENT_SCHEMA_VERSION}`,
+            '',
+            '## 检测到的变更',
+            '',
+            ...formatConfigDiff(diff),
+            '',
+            '## 处理建议',
+            '',
+            '1. **删除字段**: 检查这些字段是否在你的项目中有自定义值，如果有，需要迁移到新字段',
+            '2. **类型变更**: 手动修改字段值类型，确保与新版 schema 一致',
+            '3. **枚举值变更**: 将字段值改为合法枚举值之一',
+            '4. **结构变更**: 重组配置对象结构，确保嵌套关系正确',
+            '',
+            '修改完成后，重新运行: speccore config --upgrade',
+        ];
+        try {
+            const diffPath = (0, path_1.join)('.speccore', 'config', 'upgrade-diff.md');
+            await (0, fs_extra_1.ensureDir)((0, path_1.join)('.speccore', 'config'));
+            await (0, fs_extra_1.writeFile)(diffPath, reportLines.join('\n'), 'utf-8');
+            logger_1.logger.info(`\n📝 差异报告已保存: ${diffPath}`);
+        }
+        catch { /* 静默失败 */ }
+        logger_1.logger.info('\n⚠️  检测到配置结构性变更，需要确认:\n');
+        for (const line of formatConfigDiff(diff)) {
+            logger_1.logger.info(line);
+        }
+        logger_1.logger.info('\n💡 建议操作:');
+        logger_1.logger.info('   1. 检查上述变更是否影响现有配置');
+        logger_1.logger.info('   2. 手动调整 .speccore.yml 中的相关字段');
+        logger_1.logger.info('   3. 确认无误后重新运行 speccore config --upgrade');
+        logger_1.logger.info('');
+        // 不执行升级，返回当前配置和差异信息
+        return { config, warnings: [...warnings, '配置存在结构性变更，需人工确认后重新升级'], migrated: false };
+    }
+    // 2. 用默认值深度合并（补全缺失字段）
+    const upgraded = deepMerge(exports.DEFAULT_CONFIG, config);
+    // 3. 执行跨版本迁移（rename / add / remove / transform）
+    const migrationLogs = runMigrations(upgraded, MIGRATIONS, exports.CURRENT_SCHEMA_VERSION);
+    // 4. 更新 schema_version
+    upgraded.schema_version = exports.CURRENT_SCHEMA_VERSION;
+    // 5. 记录升级历史
+    const changeParts = [`升级到 schema_version=${exports.CURRENT_SCHEMA_VERSION}`];
+    if (migrationLogs.length > 0) {
+        changeParts.push(`包含 ${migrationLogs.length} 项迁移`);
+    }
+    if (diff.added.length > 0) {
+        changeParts.push(`自动补全 ${diff.added.length} 个新字段`);
+    }
+    upgraded.config_history = [
+        ...(upgraded.config_history || []),
+        {
+            date: new Date().toISOString().split('T')[0],
+            change: changeParts.join('，'),
+        },
+    ];
+    await saveConfig(upgraded);
+    logger_1.logger.info(`✅ .speccore.yml 已升级到 schema_version=${exports.CURRENT_SCHEMA_VERSION}`);
+    if (diff.added.length > 0) {
+        logger_1.logger.info(`   自动补全 ${diff.added.length} 个新字段（使用默认值）`);
+    }
+    if (warnings.length > 0) {
+        logger_1.logger.info('   修复了以下问题:');
+        for (const w of warnings)
+            logger_1.logger.info(`   ${w}`);
+    }
+    if (migrationLogs.length > 0) {
+        logger_1.logger.info('   执行了以下迁移:');
+        for (const log of migrationLogs)
+            logger_1.logger.info(`   ${log}`);
+    }
+    return { config: upgraded, warnings, migrated: true };
+}
+// ─────────────────────────────────────────
+// 项目配置升级（.speccore/PROJECT.yaml）
+// ─────────────────────────────────────────
+async function upgradeProjectConfig() {
+    const { config, warnings } = await loadProjectConfigWithMeta();
+    if (config.schema_version === exports.PROJECT_CURRENT_SCHEMA_VERSION && warnings.length === 0) {
+        logger_1.logger.info(`✅ .speccore/PROJECT.yaml 已经是 schema_version=${exports.PROJECT_CURRENT_SCHEMA_VERSION}，无需升级`);
+        return { config, warnings: [], migrated: false };
+    }
+    // 1. 检测配置差异（当前配置 vs 目标配置）
+    const diff = detectConfigDiff(config, exports.DEFAULT_PROJECT_CONFIG);
+    const needsConfirm = requiresUserConfirmation(diff);
+    if (needsConfirm) {
+        // 生成差异报告文件
+        const reportLines = [
+            '# .speccore/PROJECT.yaml 升级差异报告',
+            '',
+            `生成时间: ${new Date().toLocaleString('zh-CN')}`,
+            `当前 schema_version: ${config.schema_version}`,
+            `目标 schema_version: ${exports.PROJECT_CURRENT_SCHEMA_VERSION}`,
+            '',
+            '## 检测到的变更',
+            '',
+            ...formatConfigDiff(diff),
+            '',
+            '## 处理建议',
+            '',
+            '1. **删除字段**: 检查这些字段是否在你的项目中有自定义值，如果有，需要迁移到新字段',
+            '2. **类型变更**: 手动修改字段值类型，确保与新版 schema 一致',
+            '3. **枚举值变更**: 将字段值改为合法枚举值之一',
+            '4. **结构变更**: 重组配置对象结构，确保嵌套关系正确',
+            '',
+            '修改完成后，重新运行: speccore config --upgrade --project',
+        ];
+        try {
+            const diffPath = (0, path_1.join)('.speccore', 'config', 'upgrade-diff-project.md');
+            await (0, fs_extra_1.ensureDir)((0, path_1.join)('.speccore', 'config'));
+            await (0, fs_extra_1.writeFile)(diffPath, reportLines.join('\n'), 'utf-8');
+            logger_1.logger.info(`\n📝 差异报告已保存: ${diffPath}`);
+        }
+        catch { /* 静默失败 */ }
+        logger_1.logger.info('\n⚠️  检测到项目配置结构性变更，需要确认:\n');
+        for (const line of formatConfigDiff(diff)) {
+            logger_1.logger.info(line);
+        }
+        logger_1.logger.info('\n💡 建议操作:');
+        logger_1.logger.info('   1. 检查上述变更是否影响现有配置');
+        logger_1.logger.info('   2. 手动调整 .speccore/PROJECT.yaml 中的相关字段');
+        logger_1.logger.info('   3. 确认无误后重新运行 speccore config --upgrade --project');
+        logger_1.logger.info('');
+        return { config, warnings: [...warnings, '项目配置存在结构性变更，需人工确认后重新升级'], migrated: false };
+    }
+    // 2. 用默认值深度合并（补全缺失字段）
+    const upgraded = deepMerge(exports.DEFAULT_PROJECT_CONFIG, config);
+    // 3. 执行跨版本迁移
+    const migrationLogs = runMigrations(upgraded, PROJECT_MIGRATIONS, exports.PROJECT_CURRENT_SCHEMA_VERSION);
+    // 4. 更新 schema_version
+    upgraded.schema_version = exports.PROJECT_CURRENT_SCHEMA_VERSION;
+    await saveProjectConfig(upgraded);
+    logger_1.logger.info(`✅ .speccore/PROJECT.yaml 已升级到 schema_version=${exports.PROJECT_CURRENT_SCHEMA_VERSION}`);
+    if (diff.added.length > 0) {
+        logger_1.logger.info(`   自动补全 ${diff.added.length} 个新字段（使用默认值）`);
+    }
+    if (warnings.length > 0) {
+        logger_1.logger.info('   修复了以下问题:');
+        for (const w of warnings)
+            logger_1.logger.info(`   ${w}`);
+    }
+    if (migrationLogs.length > 0) {
+        logger_1.logger.info('   执行了以下迁移:');
+        for (const log of migrationLogs)
+            logger_1.logger.info(`   ${log}`);
+    }
+    return { config: upgraded, warnings, migrated: true };
+}
+function validateConfig(obj) {
+    const issues = [];
+    // schema_version
+    if (typeof obj.schema_version !== 'number') {
+        issues.push('schema_version 必须是数字');
+    }
+    // quality_gates
+    if (isObject(obj.quality_gates)) {
+        for (const key of ['enforce_testing', 'enforce_review', 'require_pr']) {
+            if (obj.quality_gates[key] !== undefined && typeof obj.quality_gates[key] !== 'boolean') {
+                issues.push(`quality_gates.${key} 必须是布尔值`);
+            }
+        }
+    }
+    // arbitration
+    if (isObject(obj.arbitration)) {
+        if (obj.arbitration.enabled !== undefined && typeof obj.arbitration.enabled !== 'boolean') {
+            issues.push('arbitration.enabled 必须是布尔值');
+        }
+        if (obj.arbitration.mode && !['full', 'l1-only', 'report-only'].includes(obj.arbitration.mode)) {
+            issues.push('arbitration.mode 必须是 full/l1-only/report-only 之一');
+        }
+    }
+    // settings
+    if (isObject(obj.settings)) {
+        const s = obj.settings;
+        if (isObject(s.assignee) && s.assignee.mode && !['strict', 'loose', 'off'].includes(s.assignee.mode)) {
+            issues.push('settings.assignee.mode 必须是 strict/loose/off 之一');
+        }
+        if (isObject(s.patterns) && s.patterns.auto_save && !['off', 'smart', 'aggressive'].includes(s.patterns.auto_save)) {
+            issues.push('settings.patterns.auto_save 必须是 off/smart/aggressive 之一');
+        }
+    }
+    return { valid: issues.length === 0, issues };
+}
+function validateProjectConfig(obj) {
+    const issues = [];
+    // schema_version
+    if (typeof obj.schema_version !== 'number') {
+        issues.push('schema_version 必须是数字');
+    }
+    // project
+    if (!isObject(obj.project)) {
+        issues.push('project 必须是对象');
+    }
+    else {
+        if (typeof obj.project.name !== 'string')
+            issues.push('project.name 必须是字符串');
+    }
+    // platforms
+    if (Array.isArray(obj.platforms)) {
+        for (let idx = 0; idx < obj.platforms.length; idx++) {
+            const p = obj.platforms[idx];
+            if (!isObject(p)) {
+                issues.push(`platforms[${idx}] 必须是对象`);
+                continue;
+            }
+            if (typeof p.name !== 'string')
+                issues.push(`platforms[${idx}].name 必须是字符串`);
+            if (p.type && !['frontend', 'backend', 'infra'].includes(p.type)) {
+                issues.push(`platforms[${idx}].type 必须是 frontend/backend/infra 之一`);
+            }
+        }
+    }
+    // git
+    if (isObject(obj.git)) {
+        if (typeof obj.git.default_base !== 'string')
+            issues.push('git.default_base 必须是字符串');
+        if (typeof obj.git.branch_prefix !== 'string')
+            issues.push('git.branch_prefix 必须是字符串');
+        if (!Array.isArray(obj.git.protected_branches))
+            issues.push('git.protected_branches 必须是数组');
+    }
+    return { valid: issues.length === 0, issues };
+}
+function isObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+// ─────────────────────────────────────────
+// YAML 解析 / 序列化
+// ─────────────────────────────────────────
 function parseYaml(content) {
     const result = {};
     const lines = content.split('\n');
-    let currentSection = null;
-    let currentList = null;
+    let stack = [{ obj: result, indent: -1 }];
     for (const line of lines) {
-        const trimmed = line.trim();
-        if (!trimmed || trimmed.startsWith('#'))
-            continue;
-        // Top-level section
-        if (!trimmed.startsWith('-') && trimmed.endsWith(':')) {
-            currentSection = trimmed.slice(0, -1).trim();
-            if (!result[currentSection])
-                result[currentSection] = {};
-            currentList = null;
+        if (!line.trim() || line.trim().startsWith('#'))
             continue;
+        const indent = line.length - line.trimStart().length;
+        // 回退到正确层级
+        while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+            stack.pop();
         }
-        // List item
-        if (trimmed.startsWith('- ') && currentSection) {
+        const trimmed = line.trim();
+        const parent = stack[stack.length - 1].obj;
+        if (trimmed.startsWith('- ')) {
             const value = trimmed.slice(2).trim();
-            if (!Array.isArray(result[currentSection])) {
-                result[currentSection] = [];
+            if (!Array.isArray(parent))
+                continue;
+            if (value.includes(':')) {
+                const obj = {};
+                const [k, ...rest] = value.split(':');
+                const v = rest.join(':').trim();
+                if (v)
+                    obj[k.trim()] = autoType(v);
+                parent.push(obj);
+                stack.push({ obj, indent });
+            }
+            else {
+                parent.push(autoType(value));
             }
-            result[currentSection].push(value);
-            currentList = currentSection;
-            continue;
         }
-        // Sub-section
-        if (!trimmed.startsWith('-') && trimmed.endsWith(':') && currentSection) {
-            const subSection = trimmed.slice(0, -1).trim();
-            if (typeof result[currentSection] === 'object' && !Array.isArray(result[currentSection])) {
-                result[currentSection][subSection] = result[currentSection][subSection] || {};
+        else if (trimmed.endsWith(':')) {
+            const key = trimmed.slice(0, -1).trim();
+            if (Array.isArray(parent)) {
+                const last = parent[parent.length - 1];
+                if (last && typeof last === 'object' && !Array.isArray(last)) {
+                    last[key] = {};
+                    stack.push({ obj: last[key], indent });
+                }
+            }
+            else {
+                if (!parent[key])
+                    parent[key] = {};
+                stack.push({ obj: parent[key], indent });
             }
-            currentList = null;
-            continue;
         }
-        // Key: value
-        if (trimmed.includes(':') && !trimmed.endsWith(':')) {
-            const [key, ...rest] = trimmed.split(':');
-            const value = rest.join(':').trim();
-            if (currentSection && typeof result[currentSection] === 'object') {
-                result[currentSection][key.trim()] = value;
+        else if (trimmed.includes(':')) {
+            const [k, ...rest] = trimmed.split(':');
+            const v = rest.join(':').trim();
+            if (Array.isArray(parent)) {
+                const last = parent[parent.length - 1];
+                if (last && typeof last === 'object') {
+                    last[k.trim()] = autoType(v);
+                }
             }
             else {
-                result[key.trim()] = value;
+                parent[k.trim()] = autoType(v);
             }
         }
     }
     return result;
 }
+/** 自动推断简单值的类型 */
+function autoType(v) {
+    if (v === 'true')
+        return true;
+    if (v === 'false')
+        return false;
+    if (/^-?\d+$/.test(v))
+        return parseInt(v, 10);
+    if (/^-?\d+\.\d+$/.test(v))
+        return parseFloat(v);
+    return v;
+}
 function toYaml(config) {
-    let yaml = '# SpecCore Configuration\n';
+    let yaml = '# SpecCore System Configuration\n';
+    yaml += `# schema_version: ${config.schema_version}\n`;
     yaml += `# ${new Date().toISOString().split('T')[0]}\n\n`;
-    yaml += `project:\n  name: ${config.project.name}\n`;
+    yaml += '\nquality_gates:\n';
+    yaml += `  enforce_testing: ${config.quality_gates.enforce_testing}\n`;
+    yaml += `  enforce_review: ${config.quality_gates.enforce_review}\n`;
+    yaml += `  require_pr: ${config.quality_gates.require_pr}\n`;
+    yaml += '\narbitration:\n';
+    yaml += `  enabled: ${config.arbitration.enabled}\n`;
+    yaml += `  mode: ${config.arbitration.mode}\n`;
+    yaml += '\nsettings:\n';
+    yaml += `  assignee:\n    enabled: ${config.settings.assignee.enabled}\n    mode: ${config.settings.assignee.mode}\n`;
+    yaml += `  trace:\n    enabled: ${config.settings.trace.enabled}\n    auto_annotate: ${config.settings.trace.auto_annotate}\n`;
+    yaml += `  archive:\n    auto_cleanup: ${config.settings.archive.auto_cleanup}\n`;
+    yaml += `  plan:\n    parallel_suggest: ${config.settings.plan.parallel_suggest}\n`;
+    yaml += `  validation:\n    strict_mode: ${config.settings.validation.strict_mode}\n`;
+    yaml += `  sync:\n    auto_check: ${config.settings.sync.auto_check}\n`;
+    yaml += `  patterns:\n    auto_save: ${config.settings.patterns.auto_save}\n`;
+    yaml += `  review:\n    check_assignee: ${config.settings.review.check_assignee}\n`;
+    yaml += '\nask:\n';
+    yaml += `  routing:\n    mode: ${config.ask.routing.mode}\n`;
+    yaml += `    high_threshold: ${config.ask.routing.high_threshold}\n`;
+    yaml += `    low_threshold: ${config.ask.routing.low_threshold}\n`;
+    yaml += `    auto_host_ai: ${config.ask.routing.auto_host_ai}\n`;
+    yaml += `    cache_enabled: ${config.ask.routing.cache_enabled}\n`;
+    yaml += `    cache_min_hits: ${config.ask.routing.cache_min_hits}\n`;
+    yaml += `  rules:\n    force_host_ai: ${config.ask.rules.force_host_ai}\n`;
+    if (config.ask.llm_providers.length > 0) {
+        yaml += `  llm_providers:\n`;
+        for (const p of config.ask.llm_providers) {
+            yaml += `    - name: ${p.name}\n      enabled: ${p.enabled}\n      type: ${p.type}\n      endpoint: ${p.endpoint}\n      model: ${p.model}\n`;
+            if (p.apiKey)
+                yaml += `      apiKey: ${p.apiKey}\n`;
+            yaml += `      priority: ${p.priority}\n`;
+        }
+    }
+    if (config.config_history.length > 0) {
+        yaml += '\nconfig_history:\n';
+        for (const h of config.config_history) {
+            yaml += `  - date: ${h.date}\n    change: ${h.change}\n`;
+            if (h.changed_by)
+                yaml += `    changed_by: ${h.changed_by}\n`;
+        }
+    }
+    return yaml;
+}
+function toProjectYaml(config) {
+    let yaml = '# SpecCore Project Configuration\n';
+    yaml += `# schema_version: ${config.schema_version}\n`;
+    yaml += `# ${new Date().toISOString().split('T')[0]}\n\n`;
+    yaml += `project:\n`;
+    yaml += `  name: ${config.project.name}\n`;
     if (config.project.description)
-        yaml += `  description: ${config.project.description}\n\n`;
-    else
-        yaml += '\n';
-    yaml += 'tech_stack:\n';
-    for (const [k, v] of Object.entries(config.tech_stack)) {
-        if (v)
-            yaml += `  ${k}: ${v}\n`;
-    }
-    yaml += '\n';
-    yaml += 'team:\n  members:\n';
-    for (const m of config.team.members) {
-        yaml += `    - name: ${m.name}\n      role: ${m.role}\n`;
-    }
-    yaml += '\n';
-    yaml += 'platforms:\n';
+        yaml += `  description: ${config.project.description}\n`;
+    if (config.project.version)
+        yaml += `  version: ${config.project.version}\n`;
+    yaml += '\nplatforms:\n';
     for (const p of config.platforms) {
-        yaml += `  - ${p}\n`;
+        yaml += `  - name: ${p.name}\n    type: ${p.type}\n`;
+        if (p.description)
+            yaml += `    description: ${p.description}\n`;
+        if (p.code_path)
+            yaml += `    code_path: ${p.code_path}\n`;
+        if (p.git_repo)
+            yaml += `    git_repo: ${p.git_repo}\n`;
+        if (p.default_branch)
+            yaml += `    default_branch: ${p.default_branch}\n`;
     }
-    yaml += '\n';
-    yaml += `git:\n  default_base: ${config.git.default_base}\n  branch_prefix: ${config.git.branch_prefix}\n\n`;
-    yaml += 'code_scope:\n';
+    yaml += `\ngit:\n`;
+    yaml += `  default_base: ${config.git.default_base}\n`;
+    yaml += `  branch_prefix: ${config.git.branch_prefix}\n`;
+    yaml += `  protected_branches:\n`;
+    for (const b of config.git.protected_branches) {
+        yaml += `    - ${b}\n`;
+    }
+    yaml += '\ncode_scope:\n';
     for (const s of config.code_scope) {
         yaml += `  - ${s}\n`;
     }
-    yaml += '\n';
-    yaml += 'quality_gates:\n';
-    yaml += `  enforce_testing: ${config.quality_gates.enforce_testing}\n`;
-    yaml += `  enforce_review: ${config.quality_gates.enforce_review}\n`;
-    yaml += `  require_pr: ${config.quality_gates.require_pr}\n`;
     return yaml;
 }
+// ─────────────────────────────────────────
+// 深度合并（用于自动补全缺失字段）
+// ─────────────────────────────────────────
+function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key of Object.keys(source)) {
+        const sVal = source[key];
+        const tVal = target[key];
+        if (sVal === undefined)
+            continue;
+        if (isPlainObject(tVal) && isPlainObject(sVal)) {
+            result[key] = deepMerge(tVal, sVal);
+        }
+        else {
+            result[key] = sVal;
+        }
+    }
+    return result;
+}
+/**
+ * 递归遍历对象/数组，将所有字符串中的 ${ENV_VAR} 替换为环境变量值。
+ * 支持默认值语法: ${VAR:-default}
+ */
+function resolveEnvVars(obj) {
+    const resolved = [];
+    const unresolved = [];
+    function traverse(current) {
+        if (typeof current === 'string') {
+            return resolveEnvVar(current, resolved, unresolved);
+        }
+        if (Array.isArray(current)) {
+            return current.map((item) => traverse(item));
+        }
+        if (isPlainObject(current)) {
+            const result = {};
+            for (const [key, value] of Object.entries(current)) {
+                result[key] = traverse(value);
+            }
+            return result;
+        }
+        return current;
+    }
+    const value = traverse(obj);
+    return { value, resolved, unresolved };
+}
+/** 解析单个字符串中的 ${VAR} 和 ${VAR:-default} */
+function resolveEnvVar(str, resolved, unresolved) {
+    return str.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}/g, (match, varName, defaultValue) => {
+        const envValue = process.env[varName];
+        if (envValue !== undefined && envValue !== '') {
+            if (!resolved.includes(varName))
+                resolved.push(varName);
+            return envValue;
+        }
+        if (defaultValue !== undefined) {
+            return defaultValue;
+        }
+        if (!unresolved.includes(varName))
+            unresolved.push(varName);
+        return match; // 保留原样，环境变量不存在
+    });
+}
+function isPlainObject(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
 //# sourceMappingURL=unified-config.js.map