@mison/ling 1.1.1 → 1.2.2

package/bin/ling-cli.js

@@ -19,7 +19,8 @@ const PRIMARY_CLI_NAME = "ling";
 const WORKSPACE_INDEX_VERSION = 2;
 const UPSTREAM_GLOBAL_PACKAGE = "@vudovn/ag-kit";
 const TOOLKIT_PACKAGE_NAMES = new Set(["@mison/ling", "@mison/ag-kit-cn", "antigravity-kit-cn", "antigravity-kit"]);
-const SUPPORTED_TARGETS = ["gemini", "codex"];
+const SUPPORTED_TARGETS = ["gemini", "antigravity", "codex"];
+const SHARED_AGENT_TARGETS = ["gemini", "antigravity"];
 const LEGACY_INDEX_TARGET_ALIASES = {
     full: "gemini",
 };
@@ -27,8 +28,8 @@ const GLOBAL_TARGET_DESTINATIONS = {
     codex: [
         {
             id: "codex",
-            rootParts: [".codex"],
-            skillsParts: [".codex", "skills"],
+            rootParts: [".agents"],
+            skillsParts: [".agents", "skills"],
         },
     ],
     gemini: [
@@ -37,6 +38,8 @@ const GLOBAL_TARGET_DESTINATIONS = {
             rootParts: [".gemini", "skills"],
             skillsParts: [".gemini", "skills"],
         },
+    ],
+    antigravity: [
         {
             id: "antigravity",
             rootParts: [".gemini", "antigravity"],
@@ -58,6 +61,7 @@ const VERSION_TAG_PREFIX = "ling-";
 const SPEC_TEMPLATE_REQUIRED_FILES = ["issues.template.csv", "driver-prompt.md", "review-report.md", "phase-acceptance.md", "handoff.md"];
 const SPEC_REFERENCE_REQUIRED_FILES = ["README.md", "harness-engineering-digest.md", "gda-framework.md", "cse-quickstart.md"];
 const SPEC_PROFILE_REQUIRED_FILES = ["codex/AGENTS.spec.md", "codex/ling.spec.rules.md", "gemini/GEMINI.spec.md"];
+const LEGACY_CODEX_GLOBAL_SKILLS_BACKUP_TARGET = "codex-legacy";
 
 function nowISO() {
     return new Date().toISOString();
@@ -170,13 +174,13 @@ function printUsage() {
     console.log(`  ${PRIMARY_CLI_NAME} update [--path <dir>] [--branch <name>] [--target <name>|--targets <a,b>] [--no-index] [--quiet] [--dry-run]`);
     console.log(`  ${PRIMARY_CLI_NAME} update-all [--branch <name>] [--targets <a,b>] [--prune-missing] [--quiet] [--dry-run]`);
     console.log(`  ${PRIMARY_CLI_NAME} doctor [--path <dir>] [--target <name>|--targets <a,b>] [--fix] [--quiet]`);
-    console.log(`  ${PRIMARY_CLI_NAME} global sync [--target <name>|--targets <a,b>] [--branch <name>] [--quiet] [--dry-run]  # 默认同步 codex + gemini(cli+antigravity)`);
+    console.log(`  ${PRIMARY_CLI_NAME} global sync [--target <name>|--targets <a,b>] [--branch <name>] [--quiet] [--dry-run]  # 默认同步 codex + gemini + antigravity`);
     console.log(`  ${PRIMARY_CLI_NAME} global status [--quiet]`);
     console.log(`  ${PRIMARY_CLI_NAME} spec enable [--target <name>|--targets <a,b>] [--quiet] [--dry-run]`);
     console.log(`  ${PRIMARY_CLI_NAME} spec disable [--target <name>|--targets <a,b>] [--quiet] [--dry-run]`);
     console.log(`  ${PRIMARY_CLI_NAME} spec status [--quiet]`);
-    console.log(`  ${PRIMARY_CLI_NAME} spec init [--path <dir>] [--target <name>|--targets <a,b>] [--branch <name>] [--force] [--non-interactive] [--no-index] [--quiet] [--dry-run]`);
-    console.log(`  ${PRIMARY_CLI_NAME} spec doctor [--path <dir>] [--quiet]`);
+    console.log(`  ${PRIMARY_CLI_NAME} spec init [--path <dir>] [--spec-workspace] [--csv-only] [--target <name>|--targets <a,b>] [--branch <name>] [--force] [--non-interactive] [--no-index] [--quiet] [--dry-run]`);
+    console.log(`  ${PRIMARY_CLI_NAME} spec doctor [--path <dir>] [--spec-workspace] [--quiet]`);
     console.log(`  ${PRIMARY_CLI_NAME} exclude list [--quiet]`);
     console.log(`  ${PRIMARY_CLI_NAME} exclude add --path <dir> [--dry-run] [--quiet]`);
     console.log(`  ${PRIMARY_CLI_NAME} exclude remove --path <dir> [--dry-run] [--quiet]`);
@@ -202,6 +206,8 @@ function parseArgs(argv) {
         nonInteractive: false,
         noIndex: false,
         fix: false,
+        csvOnly: false,
+        specWorkspace: false,
         subcommand: "",
         path: "",
         branch: "",
@@ -252,6 +258,12 @@ function parseArgs(argv) {
         } else if (arg === "--fix") {
             providedFlags.push(arg);
             options.fix = true;
+        } else if (arg === "--csv-only") {
+            providedFlags.push(arg);
+            options.csvOnly = true;
+        } else if (arg === "--spec-workspace") {
+            providedFlags.push(arg);
+            options.specWorkspace = true;
         } else if (arg === "--path") {
             providedFlags.push(arg);
             if (i + 1 >= argv.length) {
@@ -295,8 +307,8 @@ const COMMAND_ALLOWED_FLAGS = {
     "spec:enable": ["--target", "--targets", "--quiet", "--dry-run"],
     "spec:disable": ["--target", "--targets", "--quiet", "--dry-run"],
     "spec:status": ["--quiet"],
-    "spec:init": ["--force", "--path", "--branch", "--target", "--targets", "--non-interactive", "--no-index", "--quiet", "--dry-run"],
-    "spec:doctor": ["--path", "--quiet"],
+    "spec:init": ["--force", "--path", "--spec-workspace", "--branch", "--csv-only", "--target", "--targets", "--non-interactive", "--no-index", "--quiet", "--dry-run"],
+    "spec:doctor": ["--path", "--spec-workspace", "--quiet"],
     "exclude:list": ["--quiet"],
     "exclude:add": ["--path", "--dry-run", "--quiet"],
     "exclude:remove": ["--path", "--dry-run", "--quiet"],
@@ -389,6 +401,12 @@ function pathCompareKey(inputPath) {
     return normalized;
 }
 
+function findWorkspaceRecord(index, workspaceRoot) {
+    const normalizedPath = normalizeAbsolutePath(workspaceRoot);
+    const targetKey = pathCompareKey(normalizedPath);
+    return (index.workspaces || []).find((item) => pathCompareKey(item.path) === targetKey) || null;
+}
+
 function normalizePathList(items) {
     const map = new Map();
     for (const item of items) {
@@ -627,6 +645,95 @@ function writeWorkspaceIndex(indexPath, index) {
     fs.writeFileSync(indexPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
 }
 
+function getWorkspaceInstallStatePath(workspaceRoot) {
+    return path.join(normalizeAbsolutePath(workspaceRoot), ".ling", "install-state.json");
+}
+
+function createEmptyWorkspaceInstallState() {
+    return {
+        version: 1,
+        updatedAt: "",
+        targets: {},
+    };
+}
+
+function readWorkspaceInstallState(workspaceRoot) {
+    const statePath = getWorkspaceInstallStatePath(workspaceRoot);
+    if (!fs.existsSync(statePath)) {
+        return { statePath, state: createEmptyWorkspaceInstallState() };
+    }
+
+    const raw = fs.readFileSync(statePath, "utf8").trim();
+    if (!raw) {
+        return { statePath, state: createEmptyWorkspaceInstallState() };
+    }
+
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    } catch (_err) {
+        return { statePath, state: createEmptyWorkspaceInstallState() };
+    }
+
+    const state = createEmptyWorkspaceInstallState();
+    state.updatedAt = typeof parsed.updatedAt === "string" ? parsed.updatedAt : "";
+    if (parsed && parsed.targets && typeof parsed.targets === "object") {
+        for (const [targetName, targetState] of Object.entries(parsed.targets)) {
+            const normalizedTargetName = normalizeIndexTargetName(targetName);
+            const normalizedTargetState = normalizeTargetState(targetState);
+            if (normalizedTargetName && normalizedTargetState) {
+                state.targets[normalizedTargetName] = normalizedTargetState;
+            }
+        }
+    }
+
+    return { statePath, state };
+}
+
+function writeWorkspaceInstallState(statePath, state) {
+    const payload = {
+        version: 1,
+        updatedAt: state.updatedAt || nowISO(),
+        targets: state.targets || {},
+    };
+    fs.mkdirSync(path.dirname(statePath), { recursive: true });
+    fs.writeFileSync(statePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+
+function recordWorkspaceInstallTargets(workspaceRoot, targetNames, options) {
+    const logicalTargets = normalizeTargets(targetNames).filter((targetName) => SHARED_AGENT_TARGETS.includes(targetName));
+    if (logicalTargets.length === 0) {
+        return;
+    }
+
+    if (options.dryRun) {
+        log(options, `[dry-run] 将写入工作区安装状态: ${getWorkspaceInstallStatePath(workspaceRoot)} [${logicalTargets.join(", ")}]`);
+        return;
+    }
+
+    const { statePath, state } = readWorkspaceInstallState(workspaceRoot);
+    const timestamp = nowISO();
+    for (const targetName of logicalTargets) {
+        const prev = normalizeTargetState(state.targets[targetName]) || {
+            version: "",
+            installedAt: "",
+            updatedAt: "",
+        };
+        state.targets[targetName] = {
+            version: pkg.version,
+            installedAt: prev.installedAt || timestamp,
+            updatedAt: timestamp,
+        };
+    }
+    state.updatedAt = timestamp;
+    writeWorkspaceInstallState(statePath, state);
+}
+
+function resolveWorkspaceInstallStateTargets(workspaceRoot) {
+    const { state } = readWorkspaceInstallState(workspaceRoot);
+    return normalizeTargets(Object.keys(state.targets || {}));
+}
+
 function sleepSync(ms) {
     const buffer = new SharedArrayBuffer(4);
     const view = new Int32Array(buffer);
@@ -906,19 +1013,41 @@ function normalizeTargets(rawTargets) {
     return result;
 }
 
+function resolveIndexedWorkspaceTargets(workspaceRoot) {
+    try {
+        const { index } = readWorkspaceIndex();
+        const record = findWorkspaceRecord(index, workspaceRoot);
+        if (!record) {
+            return [];
+        }
+        return normalizeTargets(Object.keys(record.targets || {}));
+    } catch (_err) {
+        return [];
+    }
+}
+
 function detectInstalledTargets(workspaceRoot) {
     const targets = [];
+    const localTargets = resolveWorkspaceInstallStateTargets(workspaceRoot);
+    const indexedTargets = resolveIndexedWorkspaceTargets(workspaceRoot);
     if (fs.existsSync(path.join(workspaceRoot, ".agent"))) {
-        targets.push("gemini");
+        const sharedTargets = localTargets
+            .filter((target) => SHARED_AGENT_TARGETS.includes(target))
+            .concat(indexedTargets.filter((target) => SHARED_AGENT_TARGETS.includes(target)));
+        if (sharedTargets.length > 0) {
+            targets.push(...sharedTargets);
+        } else {
+            targets.push("gemini");
+        }
     }
     if (fs.existsSync(path.join(workspaceRoot, ".agents")) || fs.existsSync(path.join(workspaceRoot, ".codex"))) {
         targets.push("codex");
     }
-    return targets;
+    return normalizeTargets(targets);
 }
 
 function isTargetInstalled(workspaceRoot, targetName) {
-    if (targetName === "gemini") {
+    if (SHARED_AGENT_TARGETS.includes(targetName)) {
         return fs.existsSync(path.join(workspaceRoot, ".agent"));
     }
     if (targetName === "codex") {
@@ -927,6 +1056,27 @@ function isTargetInstalled(workspaceRoot, targetName) {
     return false;
 }
 
+function groupTargetsByInstallSurface(targets) {
+    const normalizedTargets = normalizeTargets(targets);
+    const groups = [];
+    const sharedTargets = normalizedTargets.filter((target) => SHARED_AGENT_TARGETS.includes(target));
+    if (sharedTargets.length > 0) {
+        groups.push({
+            installSurface: ".agent",
+            adapterTarget: sharedTargets.includes("gemini") ? "gemini" : "antigravity",
+            logicalTargets: sharedTargets,
+        });
+    }
+    if (normalizedTargets.includes("codex")) {
+        groups.push({
+            installSurface: ".agents",
+            adapterTarget: "codex",
+            logicalTargets: ["codex"],
+        });
+    }
+    return groups;
+}
+
 function setQuietStatusExitCode(state) {
     process.exitCode = Object.prototype.hasOwnProperty.call(QUIET_STATUS_EXIT_CODES, state)
         ? QUIET_STATUS_EXIT_CODES[state]
@@ -1005,6 +1155,22 @@ function evaluateGlobalState() {
         };
     }).filter((item) => item.state !== "missing");
 
+    const legacyCodexSkillsRoot = path.join(globalRoot, ".codex", "skills");
+    const hasCurrentCodexRoot = targetStates.some((item) => item.targetName === "codex");
+    if (!hasCurrentCodexRoot && fs.existsSync(legacyCodexSkillsRoot)) {
+        targetStates.push({
+            targetName: "codex",
+            family: "codex",
+            state: "broken",
+            rootDir: path.join(globalRoot, ".codex"),
+            skillsRoot: legacyCodexSkillsRoot,
+            skillsCount: countSkillsRecursive(legacyCodexSkillsRoot),
+            issues: [
+                "检测到旧版 Codex 全局 Skill 目录；当前版本改用 ~/.agents/skills（运行: ling global sync --target codex）",
+            ],
+        });
+    }
+
     if (targetStates.length === 0) {
         return {
             globalRoot,
@@ -1022,8 +1188,11 @@ function evaluateGlobalState() {
 }
 
 function createAdapter(targetName, workspaceRoot, options) {
-    if (targetName === "gemini") {
-        return new GeminiAdapter(workspaceRoot, options);
+    if (SHARED_AGENT_TARGETS.includes(targetName)) {
+        return new GeminiAdapter(workspaceRoot, {
+            ...options,
+            targetName,
+        });
     }
     if (targetName === "codex") {
         return new CodexAdapter(workspaceRoot, options);
@@ -1067,8 +1236,7 @@ function resolveTargetsForGlobalSync(options) {
     if (requested.length > 0) {
         return requested;
     }
-    // 保持 global sync 简洁：默认同步 codex + gemini；其中 gemini 会展开为 gemini-cli 与 antigravity。
-    return ["codex", "gemini"];
+    return [...SUPPORTED_TARGETS];
 }
 
 function resolveAgentInstallSource(options) {
@@ -1120,6 +1288,74 @@ function backupSkillDirectory(targetName, skillName, sourceDir, timestamp, optio
     log(options, `[backup] 已备份 ${targetName} 全局 Skill: ${skillName} -> ${backupDir}`);
 }
 
+function migrateLegacyCodexGlobalSkills(timestamp, options) {
+    const globalRoot = resolveGlobalRootDir();
+    const legacyRoot = path.join(globalRoot, ".codex", "skills");
+    if (!fs.existsSync(legacyRoot)) {
+        return { migrated: 0, removed: 0, backedUp: 0, conflicts: 0, remaining: 0 };
+    }
+
+    const destRoot = path.join(globalRoot, ".agents", "skills");
+    const legacyDirEntries = fs.readdirSync(legacyRoot, { withFileTypes: true });
+    const legacyEntries = legacyDirEntries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+    if (legacyEntries.length === 0) {
+        if (legacyDirEntries.length === 0) {
+            removeDirIfExists(legacyRoot, options, "遗留 Codex skills 根目录");
+        } else {
+            log(options, `[warn] 遗留 Codex skills 根目录包含非目录条目，已跳过迁移清理: ${legacyRoot}`);
+        }
+        return { migrated: 0, removed: 0, backedUp: 0, conflicts: 0, remaining: legacyDirEntries.length };
+    }
+
+    let migrated = 0;
+    let removed = 0;
+    let backedUp = 0;
+    let conflicts = 0;
+
+    for (const entryName of legacyEntries) {
+        const legacyDir = path.join(legacyRoot, entryName);
+        const destDir = path.join(destRoot, entryName);
+        const destExists = fs.existsSync(destDir);
+
+        if (!destExists) {
+            if (options.dryRun) {
+                log(options, `[dry-run] 将迁移遗留 Codex Skill 目录: ${legacyDir} -> ${destDir}`);
+            } else {
+                const logger = options.quiet ? (() => {}) : log.bind(null, options);
+                AtomicWriter.atomicCopyDir(legacyDir, destDir, { logger });
+                log(options, `[ok] 已迁移遗留 Codex Skill 目录: ${legacyDir} -> ${destDir}`);
+            }
+            migrated += 1;
+        } else if (!areDirectoriesEqual(legacyDir, destDir)) {
+            conflicts += 1;
+            if (options.dryRun) {
+                log(options, `[dry-run] 将备份并移除遗留 Codex Skill（与现有目录冲突）: ${legacyDir}`);
+            } else {
+                backupSkillDirectory(LEGACY_CODEX_GLOBAL_SKILLS_BACKUP_TARGET, entryName, legacyDir, timestamp, options);
+                backedUp += 1;
+            }
+        }
+
+        if (options.dryRun) {
+            log(options, `[dry-run] 将删除遗留 Codex Skill 目录: ${legacyDir}`);
+            continue;
+        }
+
+        fs.rmSync(legacyDir, { recursive: true, force: true });
+        log(options, `[clean] 已删除遗留 Codex Skill 目录: ${legacyDir}`);
+        removed += 1;
+    }
+
+    const remaining = fs.existsSync(legacyRoot) ? fs.readdirSync(legacyRoot).length : 0;
+    if (remaining === 0) {
+        removeDirIfExists(legacyRoot, options, "遗留 Codex skills 根目录");
+    } else {
+        log(options, `[warn] 遗留 Codex skills 根目录仍有残留条目(${remaining})，已保留: ${legacyRoot}`);
+    }
+
+    return { migrated, removed, backedUp, conflicts, remaining };
+}
+
 function syncSkillDirectory(destination, srcDir, destDir, timestamp, options) {
     const exists = fs.existsSync(destDir);
     if (exists) {
@@ -1235,7 +1471,7 @@ function planGlobalSyncTasks(targetName, agentDir) {
         };
     }
 
-    if (targetName === "gemini") {
+    if (SHARED_AGENT_TARGETS.includes(targetName)) {
         const skillsRoot = path.join(agentDir, "skills");
         const skillNames = listSkillDirectories(skillsRoot);
         const tasks = [];
@@ -1317,7 +1553,7 @@ function applyGlobalSync(targetName, agentDir, timestamp, options) {
         }
     }
 
-    if (targetName === "gemini") {
+    if (SHARED_AGENT_TARGETS.includes(targetName)) {
         const skillsRoot = path.join(agentDir, "skills");
         return syncGlobalSkillsFromRoot(targetName, skillsRoot, timestamp, options);
     }
@@ -1386,6 +1622,10 @@ async function commandGlobalSync(options) {
                         log(options, `   - ${item.targetName}: ${item.destRoot}（每目标 ${item.total} 个 Skills）`);
                     }
                 }
+
+                if (target === "codex") {
+                    migrateLegacyCodexGlobalSkills(timestamp, options);
+                }
             } finally {
                 if (plan.cleanup) plan.cleanup();
             }
@@ -1475,15 +1715,121 @@ function createEmptySpecState() {
     };
 }
 
+function rewriteLegacyCodexGlobalSkillPath(targetPath) {
+    if (typeof targetPath !== "string" || targetPath === "") {
+        return targetPath;
+    }
+    const normalizedPath = targetPath.replace(/\\/g, "/");
+    if (!normalizedPath.includes("/.codex/skills")) {
+        return targetPath;
+    }
+    return targetPath.replace(/([\\/])\.codex([\\/])skills/g, "$1.agents$2skills");
+}
+
+function normalizeSpecSkillState(targetName, consumerId, skillState) {
+    if (!skillState || typeof skillState !== "object" || typeof skillState.name !== "string" || !skillState.name) {
+        return null;
+    }
+    const destPath = typeof skillState.destPath === "string" ? skillState.destPath : "";
+    return {
+        name: skillState.name,
+        destPath: targetName === "codex" && consumerId === "codex"
+            ? rewriteLegacyCodexGlobalSkillPath(destPath)
+            : destPath,
+        backupPath: typeof skillState.backupPath === "string" ? skillState.backupPath : "",
+        mode: normalizeSpecAssetMode(skillState),
+    };
+}
+
+function normalizeSpecConsumerState(targetName, consumerId, consumerState) {
+    const skills = [];
+    let migrated = false;
+    for (const skillState of Array.isArray(consumerState && consumerState.skills) ? consumerState.skills : []) {
+        const normalizedSkill = normalizeSpecSkillState(targetName, consumerId, skillState);
+        if (normalizedSkill) {
+            skills.push(normalizedSkill);
+            if (normalizedSkill.destPath !== (typeof skillState.destPath === "string" ? skillState.destPath : "")) {
+                migrated = true;
+            }
+        }
+    }
+    return { skills, migrated };
+}
+
+function normalizeSpecTargetState(targetName, targetState) {
+    const allowedConsumers = new Set(getGlobalDestinations(targetName).map((destination) => destination.id));
+    const consumers = {};
+    let migrated = false;
+    for (const consumerId of allowedConsumers) {
+        if (targetState && targetState.consumers && targetState.consumers[consumerId]) {
+            const normalizedConsumerState = normalizeSpecConsumerState(targetName, consumerId, targetState.consumers[consumerId]);
+            consumers[consumerId] = { skills: normalizedConsumerState.skills };
+            if (normalizedConsumerState.migrated) {
+                migrated = true;
+            }
+        }
+    }
+    return {
+        enabledAt: targetState && typeof targetState.enabledAt === "string" ? targetState.enabledAt : "",
+        consumers,
+        migrated,
+    };
+}
+
+function normalizeSpecTargets(rawTargets) {
+    const normalizedTargets = {};
+    let migrated = false;
+
+    for (const targetName of SUPPORTED_TARGETS) {
+        if (rawTargets && rawTargets[targetName] && typeof rawTargets[targetName] === "object") {
+            normalizedTargets[targetName] = rawTargets[targetName];
+        }
+    }
+
+    const geminiState = normalizedTargets.gemini;
+    if (
+        geminiState
+        && geminiState.consumers
+        && geminiState.consumers.antigravity
+        && !normalizedTargets.antigravity
+    ) {
+        normalizedTargets.antigravity = {
+            enabledAt: typeof geminiState.enabledAt === "string" ? geminiState.enabledAt : "",
+            consumers: {
+                antigravity: geminiState.consumers.antigravity,
+            },
+        };
+        delete geminiState.consumers.antigravity;
+        migrated = true;
+    }
+
+    const finalTargets = {};
+    for (const targetName of Object.keys(normalizedTargets)) {
+        const normalizedTargetState = normalizeSpecTargetState(targetName, normalizedTargets[targetName]);
+        const consumerIds = Object.keys(normalizedTargetState.consumers);
+        const rawConsumerIds = Object.keys((normalizedTargets[targetName] && normalizedTargets[targetName].consumers) || {});
+        if (consumerIds.length !== rawConsumerIds.length || rawConsumerIds.some((consumerId) => !consumerIds.includes(consumerId))) {
+            migrated = true;
+        }
+        if (normalizedTargetState.migrated) {
+            migrated = true;
+        }
+        finalTargets[targetName] = normalizedTargetState;
+        delete finalTargets[targetName].migrated;
+    }
+
+    return { targets: finalTargets, migrated };
+}
+
 function readSpecState() {
     const statePath = getSpecStatePath();
     if (!fs.existsSync(statePath)) {
-        return { statePath, state: createEmptySpecState() };
+        return { statePath, state: createEmptySpecState(), migrated: false };
     }
 
     const raw = fs.readFileSync(statePath, "utf8").trim();
     if (!raw) {
-        return { statePath, state: createEmptySpecState() };
+        return { statePath, state: createEmptySpecState(), migrated: false };
     }
 
     let parsed;
@@ -1495,9 +1841,10 @@ function readSpecState() {
 
     const state = createEmptySpecState();
     state.updatedAt = typeof parsed.updatedAt === "string" ? parsed.updatedAt : "";
-    state.targets = parsed && typeof parsed.targets === "object" && parsed.targets ? parsed.targets : {};
+    const normalizedTargets = normalizeSpecTargets(parsed && typeof parsed.targets === "object" && parsed.targets ? parsed.targets : {});
+    state.targets = normalizedTargets.targets;
     state.assets = parsed && typeof parsed.assets === "object" && parsed.assets ? parsed.assets : {};
-    return { statePath, state };
+    return { statePath, state, migrated: normalizedTargets.migrated };
 }
 
 function writeSpecState(statePath, state) {
@@ -2092,9 +2439,21 @@ function checkSpecProjectIntegrity(workspaceRoot) {
     const profilesDir = path.join(specDir, "profiles");
 
     const hasSpecDir = fs.existsSync(specDir);
+    const globalSpecSummary = !hasSpecDir && issuesResult.status !== "missing" ? evaluateSpecState() : null;
+    const canFallbackToGlobalSpec = Boolean(globalSpecSummary && globalSpecSummary.state === "installed");
     if (!hasSpecDir) {
         if (issuesResult.status !== "missing") {
-            issues.push("Missing .ling/spec directory (run: ling spec init)");
+            if (!canFallbackToGlobalSpec) {
+                issues.push("Missing .ling/spec directory (run: ling spec init)");
+                if (globalSpecSummary && globalSpecSummary.state === "missing") {
+                    issues.push("Global Spec is not enabled (run: ling spec enable)");
+                } else if (globalSpecSummary && globalSpecSummary.state === "broken") {
+                    issues.push("Global Spec is broken (run: ling spec enable)");
+                    for (const issue of globalSpecSummary.issues || []) {
+                        issues.push(`Global Spec issue: ${issue}`);
+                    }
+                }
+            }
         }
     } else {
         if (issuesResult.status === "missing") {
@@ -2141,7 +2500,10 @@ function resolveWorkspaceSpecBackupRoot(workspaceRoot, timestamp) {
 }
 
 async function commandSpecInit(options) {
-    const workspaceRoot = options.path ? resolveWorkspaceRoot(options.path) : getSpecWorkspaceDir();
+    const workspaceRoot = options.path
+        ? resolveWorkspaceRoot(options.path)
+        : (options.specWorkspace ? getSpecWorkspaceDir() : resolveWorkspaceRoot());
+    const csvOnly = Boolean(options.csvOnly);
     const prompter = createConflictPrompter(options);
     const timestamp = nowISO().replace(/[:.]/g, "-");
     const backupRoot = resolveWorkspaceSpecBackupRoot(workspaceRoot, timestamp);
@@ -2175,39 +2537,49 @@ async function commandSpecInit(options) {
     try {
         fs.mkdirSync(workspaceRoot, { recursive: true });
 
-        for (const [assetName, config] of Object.entries(assets)) {
-            const exists = fs.existsSync(config.destDir);
-            if (exists && areDirectoriesEqual(config.sourceDir, config.destDir)) {
-                log(options, `[skip] Spec ${assetName} 已最新，无需覆盖: ${config.destDir}`);
-                continue;
-            }
+        if (!csvOnly) {
+            for (const [assetName, config] of Object.entries(assets)) {
+                const exists = fs.existsSync(config.destDir);
+                if (exists && areDirectoriesEqual(config.sourceDir, config.destDir)) {
+                    log(options, `[skip] Spec ${assetName} 已最新，无需覆盖: ${config.destDir}`);
+                    continue;
+                }
 
-            let action = exists ? "backup" : "";
-            if (exists && prompter) {
-                action = await prompter.resolveConflict({
-                    category: "spec:project:assets",
-                    label: `Spec ${assetName}`,
-                    path: config.destDir,
-                });
-            } else if (exists && !prompter && (options.force || options.nonInteractive || !process.stdin.isTTY)) {
-                action = "backup";
-            }
+                let action = exists ? "backup" : "";
+                if (exists && prompter) {
+                    action = await prompter.resolveConflict({
+                        category: "spec:project:assets",
+                        label: `Spec ${assetName}`,
+                        path: config.destDir,
+                    });
+                } else if (exists && !prompter && (options.force || options.nonInteractive || !process.stdin.isTTY)) {
+                    action = "backup";
+                }
 
-            if (action === "keep") {
-                log(options, `[skip] 已保留 Spec ${assetName} 资产，不覆盖: ${config.destDir}`);
-                continue;
-            }
+                if (action === "keep") {
+                    log(options, `[skip] 已保留 Spec ${assetName} 资产，不覆盖: ${config.destDir}`);
+                    continue;
+                }
 
-            if (exists && action !== "remove") {
-                backupDirSnapshot(config.destDir, path.join(backupRoot, "assets", assetName), options, `Spec ${assetName}`);
-            } else if (exists && action === "remove") {
-                removeDirIfExists(config.destDir, options, `Spec ${assetName}`);
+                if (exists && action !== "remove") {
+                    backupDirSnapshot(config.destDir, path.join(backupRoot, "assets", assetName), options, `Spec ${assetName}`);
+                } else if (exists && action === "remove") {
+                    removeDirIfExists(config.destDir, options, `Spec ${assetName}`);
+                }
+                applyDirSnapshot(config.sourceDir, config.destDir, options, `Spec ${assetName}`);
             }
-            applyDirSnapshot(config.sourceDir, config.destDir, options, `Spec ${assetName}`);
         }
 
         const issuesPath = path.join(workspaceRoot, "issues.csv");
-        const issuesTemplatePath = path.join(specSourceDir, "templates", "issues.template.csv");
+        let issuesTemplatePath = path.join(specSourceDir, "templates", "issues.template.csv");
+        if (csvOnly && !options.branch) {
+            const globalTemplatePath = path.join(getSpecHomeDir(), "templates", "issues.template.csv");
+            if (fs.existsSync(globalTemplatePath)) {
+                issuesTemplatePath = globalTemplatePath;
+            } else if (!options.quiet) {
+                log(options, "[warn] 未检测到全局 Spec templates，已使用内置模板生成 issues.csv。可执行: ling spec enable");
+            }
+        }
         const issuesTemplate = stripUtf8Bom(fs.readFileSync(issuesTemplatePath, "utf8"));
         const hasIssues = fs.existsSync(issuesPath);
         if (hasIssues) {
@@ -2246,7 +2618,8 @@ async function commandSpecInit(options) {
         }
 
         const requestedTargets = normalizeTargets(options.targets);
-        const shouldInitTargets = options.path ? requestedTargets.length > 0 : true;
+        const isSpecWorkspaceMode = Boolean(!options.path && options.specWorkspace);
+        const shouldInitTargets = isSpecWorkspaceMode ? true : requestedTargets.length > 0;
         const targets = shouldInitTargets ? (requestedTargets.length > 0 ? requestedTargets : [...SUPPORTED_TARGETS]) : [];
         if (targets.length > 0) {
             await initTargets(workspaceRoot, targets, options, prompter);
@@ -2260,7 +2633,9 @@ async function commandSpecInit(options) {
 }
 
 function commandSpecDoctor(options) {
-    const workspaceRoot = options.path ? resolveWorkspaceRoot(options.path) : getSpecWorkspaceDir();
+    const workspaceRoot = options.path
+        ? resolveWorkspaceRoot(options.path)
+        : (options.specWorkspace ? getSpecWorkspaceDir() : resolveWorkspaceRoot());
     const result = checkSpecProjectIntegrity(workspaceRoot);
     const state = result.status === "ok" ? "installed" : result.status;
 
@@ -2279,6 +2654,21 @@ function commandSpecDoctor(options) {
 
     console.log(state === "installed" ? "[ok] Spec 项目资产状态正常" : "[warn] Spec 项目资产存在问题");
     console.log(`   工作区: ${workspaceRoot}`);
+    const specDir = path.join(workspaceRoot, ".ling", "spec");
+    const hasSpecDir = fs.existsSync(specDir);
+    const issuesPath = path.join(workspaceRoot, "issues.csv");
+    const hasIssues = fs.existsSync(issuesPath);
+    if (hasSpecDir) {
+        console.log("   模式: project");
+        console.log(`   Spec 根目录: ${specDir}`);
+    } else if (hasIssues) {
+        const globalSpecSummary = evaluateSpecState();
+        const fallback = globalSpecSummary.state === "installed";
+        console.log(`   模式: csv-only${fallback ? " (global fallback)" : ""}`);
+        if (fallback) {
+            console.log(`   Spec 根目录: ${getSpecHomeDir()}`);
+        }
+    }
     console.log(`   任务数: ${result.stats.total}`);
     console.log(`   进行中: ${result.stats.inProgress}`);
     for (const issue of result.issues || []) {
@@ -2308,6 +2698,10 @@ async function commandSpecEnable(options) {
         writeSpecState(statePath, state);
     }
 
+    if (targets.includes("codex")) {
+        migrateLegacyCodexGlobalSkills(timestamp, options);
+    }
+
     log(options, `[ok] Spec Profile 已启用 (Targets: ${targets.join(", ")})`);
 }
 
@@ -2368,23 +2762,23 @@ async function commandSpec(options) {
 }
 
 async function initTargets(workspaceRoot, targets, options, prompter) {
-    for (const target of targets) {
+    for (const group of groupTargetsByInstallSurface(targets)) {
         const runOptions = { ...options };
         const conflicts = [];
 
-        if (target === "gemini") {
+        if (group.installSurface === ".agent") {
             const agentDir = path.join(workspaceRoot, ".agent");
             if (fs.existsSync(agentDir)) {
                 conflicts.push({
-                    category: "project:gemini",
+                    category: "project:shared-agent",
                     label: ".agent",
                     path: agentDir,
-                    target,
+                    target: group.logicalTargets.join(","),
                 });
             }
         }
 
-        if (target === "codex") {
+        if (group.adapterTarget === "codex") {
             const managedDir = path.join(workspaceRoot, ".agents");
             const legacyDir = path.join(workspaceRoot, ".codex");
             if (fs.existsSync(managedDir) || fs.existsSync(legacyDir)) {
@@ -2435,10 +2829,13 @@ async function initTargets(workspaceRoot, targets, options, prompter) {
             }
         }
 
-        const adapter = createAdapter(target, workspaceRoot, runOptions);
-        log(options, `[sync] 正在初始化目标 [${target}] ...`);
+        const adapter = createAdapter(group.adapterTarget, workspaceRoot, runOptions);
+        log(options, `[sync] 正在初始化目标 [${group.logicalTargets.join(", ")}] ...`);
         adapter.install(BUNDLED_AGENT_DIR);
-        registerWorkspaceTarget(workspaceRoot, target, runOptions);
+        recordWorkspaceInstallTargets(workspaceRoot, group.logicalTargets, runOptions);
+        for (const target of group.logicalTargets) {
+            registerWorkspaceTarget(workspaceRoot, target, runOptions);
+        }
     }
 }
 
@@ -2523,71 +2920,73 @@ async function commandUpdate(options) {
 
     let updatedAny = false;
     try {
-        for (const target of targets) {
-        if (!isTargetInstalled(workspaceRoot, target) && options.targets.length > 0) {
-            throw new Error(`目标未安装: ${target}`);
-        }
-        if (!isTargetInstalled(workspaceRoot, target)) {
-            log(options, `[skip] 目标未安装，跳过: ${target}`);
-            continue;
-        }
+        for (const group of groupTargetsByInstallSurface(targets)) {
+            if (!isTargetInstalled(workspaceRoot, group.adapterTarget) && options.targets.length > 0) {
+                throw new Error(`目标未安装: ${group.logicalTargets.join(", ")}`);
+            }
+            if (!isTargetInstalled(workspaceRoot, group.adapterTarget)) {
+                log(options, `[skip] 目标未安装，跳过: ${group.logicalTargets.join(", ")}`);
+                continue;
+            }
 
-        const runOptions = { ...options, force: true };
+            const runOptions = { ...options, force: true };
+            const timestamp = nowISO().replace(/[:.]/g, "-");
 
-        const timestamp = nowISO().replace(/[:.]/g, "-");
-        if (target === "gemini") {
-            const agentDir = path.join(workspaceRoot, ".agent");
-            if (fs.existsSync(agentDir) && !areDirectoriesEqual(BUNDLED_AGENT_DIR, agentDir)) {
-                let action = "backup";
-                if (prompter) {
-                    action = await prompter.resolveConflict({
-                        category: "project:gemini",
-                        label: ".agent",
-                        path: agentDir,
-                        target,
-                    });
-                }
-                if (action === "keep") {
-                    log(options, "[skip] 已保留现有资产，跳过更新: .agent");
-                    continue;
-                }
-                if (action === "backup") {
-                    backupWorkspaceDir(workspaceRoot, agentDir, ".agent-backup", timestamp, options, "工作区资产 .agent");
+            if (group.installSurface === ".agent") {
+                const agentDir = path.join(workspaceRoot, ".agent");
+                if (fs.existsSync(agentDir) && !areDirectoriesEqual(BUNDLED_AGENT_DIR, agentDir)) {
+                    let action = "backup";
+                    if (prompter) {
+                        action = await prompter.resolveConflict({
+                            category: "project:shared-agent",
+                            label: ".agent",
+                            path: agentDir,
+                            target: group.logicalTargets.join(","),
+                        });
+                    }
+                    if (action === "keep") {
+                        log(options, "[skip] 已保留现有资产，跳过更新: .agent");
+                        continue;
+                    }
+                    if (action === "backup") {
+                        backupWorkspaceDir(workspaceRoot, agentDir, ".agent-backup", timestamp, options, "工作区资产 .agent");
+                    }
                 }
             }
-        }
 
-        if (target === "codex") {
-            const managedDir = path.join(workspaceRoot, ".agents");
-            const legacyDir = path.join(workspaceRoot, ".codex");
-            const activeDir = fs.existsSync(managedDir) ? managedDir : legacyDir;
-            const conflict = evaluateCodexUpdateConflict(activeDir);
-            if (conflict.hasConflict) {
-                let action = "backup";
-                if (prompter) {
-                    action = await prompter.resolveConflict({
-                        category: "project:codex",
-                        label: fs.existsSync(managedDir) ? ".agents" : ".codex",
-                        path: activeDir,
-                        target,
-                    });
-                }
-                if (action === "keep") {
-                    log(options, `[skip] 已保留现有资产，跳过更新: ${path.basename(activeDir)}`);
-                    continue;
-                }
-                if (action === "backup") {
-                    const backupRootName = ".agents-backup";
-                    backupWorkspaceDir(workspaceRoot, activeDir, backupRootName, timestamp, options, `工作区资产 ${path.basename(activeDir)}`);
+            if (group.adapterTarget === "codex") {
+                const managedDir = path.join(workspaceRoot, ".agents");
+                const legacyDir = path.join(workspaceRoot, ".codex");
+                const activeDir = fs.existsSync(managedDir) ? managedDir : legacyDir;
+                const conflict = evaluateCodexUpdateConflict(activeDir);
+                if (conflict.hasConflict) {
+                    let action = "backup";
+                    if (prompter) {
+                        action = await prompter.resolveConflict({
+                            category: "project:codex",
+                            label: fs.existsSync(managedDir) ? ".agents" : ".codex",
+                            path: activeDir,
+                            target: group.logicalTargets.join(","),
+                        });
+                    }
+                    if (action === "keep") {
+                        log(options, `[skip] 已保留现有资产，跳过更新: ${path.basename(activeDir)}`);
+                        continue;
+                    }
+                    if (action === "backup") {
+                        backupWorkspaceDir(workspaceRoot, activeDir, ".agents-backup", timestamp, options, `工作区资产 ${path.basename(activeDir)}`);
+                    }
                 }
             }
-        }
 
-        const adapter = createAdapter(target, workspaceRoot, runOptions);
-        log(options, `[sync] 更新 [${target}] ...`);
-        adapter.update(BUNDLED_AGENT_DIR);
-        registerWorkspaceTarget(workspaceRoot, target, runOptions);
-        updatedAny = true;
+            const adapter = createAdapter(group.adapterTarget, workspaceRoot, runOptions);
+            log(options, `[sync] 更新 [${group.logicalTargets.join(", ")}] ...`);
+            adapter.update(BUNDLED_AGENT_DIR);
+            recordWorkspaceInstallTargets(workspaceRoot, group.logicalTargets, runOptions);
+            for (const target of group.logicalTargets) {
+                registerWorkspaceTarget(workspaceRoot, target, runOptions);
+            }
+            updatedAny = true;
         }
     } finally {
         if (prompter) prompter.close();
@@ -2680,7 +3079,7 @@ async function commandUpdateAll(options) {
         const installedTargets = detectInstalledTargets(workspacePath);
         let targets = [];
         if (requestedTargets.length > 0) {
-            targets = installedTargets.filter((target) => requestedTargets.includes(target));
+            targets = requestedTargets.filter((target) => isTargetInstalled(workspacePath, target));
         } else {
             targets = [...Object.keys(item.targets || {}), ...installedTargets];
         }
@@ -2696,9 +3095,9 @@ async function commandUpdateAll(options) {
         log(options, `[sync] [${i + 1}/${records.length}] 更新: ${workspacePath} [${targets.join(", ")}]`);
 
         const updatedTargets = [];
-        for (const target of targets) {
-            if (!isTargetInstalled(workspacePath, target)) {
-                log(options, `[skip] [${i + 1}/${records.length}] 目标未安装，跳过: ${target}`);
+        for (const group of groupTargetsByInstallSurface(targets)) {
+            if (!isTargetInstalled(workspacePath, group.adapterTarget)) {
+                log(options, `[skip] [${i + 1}/${records.length}] 目标未安装，跳过: ${group.logicalTargets.join(", ")}`);
                 continue;
             }
 
@@ -2712,19 +3111,19 @@ async function commandUpdateAll(options) {
 
                 const timestampForBackup = nowISO().replace(/[:.]/g, "-");
 
-                if (target === "gemini") {
+                if (group.installSurface === ".agent") {
                     const agentDir = path.join(workspacePath, ".agent");
                     if (fs.existsSync(agentDir) && !areDirectoriesEqual(BUNDLED_AGENT_DIR, agentDir)) {
                         let action = "backup";
                         if (prompter) {
                             action = await prompter.resolveConflict({
-                                category: "update-all:project:gemini",
+                                category: "update-all:project:shared-agent",
                                 label: `.agent (${workspacePath})`,
                                 path: agentDir,
                             });
                         }
                         if (action === "keep") {
-                            log(options, `[skip] [${i + 1}/${records.length}] 已保留现有资产，跳过更新: ${workspacePath} [gemini]`);
+                            log(options, `[skip] [${i + 1}/${records.length}] 已保留现有资产，跳过更新: ${workspacePath} [${group.logicalTargets.join(", ")}]`);
                             continue;
                         }
                         if (action === "backup") {
@@ -2733,7 +3132,7 @@ async function commandUpdateAll(options) {
                     }
                 }
 
-                if (target === "codex") {
+                if (group.adapterTarget === "codex") {
                     const managedDir = path.join(workspacePath, ".agents");
                     const legacyDir = path.join(workspacePath, ".codex");
                     const activeDir = fs.existsSync(managedDir) ? managedDir : legacyDir;
@@ -2757,13 +3156,14 @@ async function commandUpdateAll(options) {
                     }
                 }
 
-                const adapter = createAdapter(target, workspacePath, runOptions);
+                const adapter = createAdapter(group.adapterTarget, workspacePath, runOptions);
                 adapter.update(BUNDLED_AGENT_DIR);
-                updatedTargets.push(target);
+                recordWorkspaceInstallTargets(workspacePath, group.logicalTargets, runOptions);
+                updatedTargets.push(...group.logicalTargets);
             } catch (err) {
                 failed += 1;
                 if (!options.quiet) {
-                    console.error(`[error] 更新失败: ${workspacePath} [${target}]`);
+                    console.error(`[error] 更新失败: ${workspacePath} [${group.logicalTargets.join(", ")}]`);
                     console.error(`   ${err.message}`);
                 }
             }
@@ -3068,6 +3468,25 @@ function countSkillsRecursive(dir) {
     return count;
 }
 
+function printSharedAgentTargetStatus(workspaceRoot, targetState, label) {
+    const agentDir = path.join(workspaceRoot, ".agent");
+    const agentsCount = countFilesIfExists(path.join(agentDir, "agents"), (name) => name.endsWith(".md"));
+    const workflowsCount = countFilesIfExists(path.join(agentDir, "workflows"), (name) => name.endsWith(".md"));
+    const skillsCount = countSkillsRecursive(path.join(agentDir, "skills"));
+    console.log(`\n[${label}]`);
+    console.log(`   状态: ${targetState.state}`);
+    console.log(`   路径: ${agentDir}`);
+    if (targetState.state === "installed") {
+        console.log(`   Agents: ${agentsCount}`);
+        console.log(`   Skills: ${skillsCount}`);
+        console.log(`   Workflows: ${workflowsCount}`);
+        return;
+    }
+    for (const issue of targetState.integrity.issues || []) {
+        console.log(`   Issue: ${issue}`);
+    }
+}
+
 function commandStatus(options) {
     const workspaceRoot = resolveWorkspaceRoot(options.path);
     const summary = evaluateWorkspaceState(workspaceRoot, options);
@@ -3098,22 +3517,12 @@ function commandStatus(options) {
 
     const geminiState = summary.targets.find((item) => item.targetName === "gemini");
     if (geminiState) {
-        const agentDir = path.join(workspaceRoot, ".agent");
-        const agentsCount = countFilesIfExists(path.join(agentDir, "agents"), (name) => name.endsWith(".md"));
-        const workflowsCount = countFilesIfExists(path.join(agentDir, "workflows"), (name) => name.endsWith(".md"));
-        const skillsCount = countSkillsRecursive(path.join(agentDir, "skills"));
-        console.log("\n[gemini]");
-        console.log(`   状态: ${geminiState.state}`);
-        console.log(`   路径: ${agentDir}`);
-        if (geminiState.state === "installed") {
-            console.log(`   Agents: ${agentsCount}`);
-            console.log(`   Skills: ${skillsCount}`);
-            console.log(`   Workflows: ${workflowsCount}`);
-        } else {
-            for (const issue of geminiState.integrity.issues || []) {
-                console.log(`   Issue: ${issue}`);
-            }
-        }
+        printSharedAgentTargetStatus(workspaceRoot, geminiState, "gemini");
+    }
+
+    const antigravityState = summary.targets.find((item) => item.targetName === "antigravity");
+    if (antigravityState) {
+        printSharedAgentTargetStatus(workspaceRoot, antigravityState, "antigravity");
     }
 
     const codexState = summary.targets.find((item) => item.targetName === "codex");