@mison/ag-kit-cn 3.0.0-beta.0 → 3.0.0

package/bin/ag-kit.js

@@ -5,30 +5,51 @@ const os = require("os");
 const path = require("path");
 
 const pkg = require("../package.json");
-const { readGlobalNpmDependencies } = require("./utils");
+const { readGlobalNpmDependencies, cloneBranchAgentDir } = require("./utils");
+const ManifestManager = require("./utils/manifest");
+const AtomicWriter = require("./utils/atomic-writer");
+const CodexBuilder = require("./core/builder");
+const GeminiAdapter = require("./adapters/gemini");
 const CodexAdapter = require("./adapters/codex");
-const {
-    selectTargets,
-    selectAgentConflictPolicy,
-    selectGeminiAgentsPolicy,
-} = require("./interactive");
-
-const BUNDLED_AGENT_DIR = fs.existsSync(path.resolve(__dirname, "../.agents"))
-    ? path.resolve(__dirname, "../.agents")
-    : path.resolve(__dirname, "../.agent");
+const { selectTargets } = require("./interactive");
+
+const BUNDLED_AGENT_DIR = path.resolve(__dirname, "../.agents");
 const WORKSPACE_INDEX_VERSION = 2;
 const UPSTREAM_GLOBAL_PACKAGE = "@vudovn/ag-kit";
 const TOOLKIT_PACKAGE_NAMES = new Set(["@mison/ag-kit-cn", "antigravity-kit-cn", "antigravity-kit"]);
-const SUPPORTED_TARGETS = ["full", "agents", "gemini", "codex"];
-const TARGET_ALIAS_MAP = {
-    full: "full",
-    agents: "full",
-    gemini: "full",
-    codex: "full",
+const SUPPORTED_TARGETS = ["gemini", "codex"];
+const LEGACY_INDEX_TARGET_ALIASES = {
+    full: "gemini",
+};
+const GLOBAL_TARGET_DESTINATIONS = {
+    codex: [
+        {
+            id: "codex",
+            rootParts: [".codex"],
+            skillsParts: [".codex", "skills"],
+        },
+    ],
+    gemini: [
+        {
+            id: "gemini-cli",
+            rootParts: [".gemini", "skills"],
+            skillsParts: [".gemini", "skills"],
+        },
+        {
+            id: "antigravity",
+            rootParts: [".gemini", "antigravity"],
+            skillsParts: [".gemini", "antigravity", "skills"],
+        },
+    ],
 };
 const INDEX_LOCK_RETRY_MS = 50;
 const INDEX_LOCK_TIMEOUT_MS = 3000;
 const INDEX_LOCK_STALE_MS = 30000;
+const QUIET_STATUS_EXIT_CODES = {
+    installed: 0,
+    broken: 1,
+    missing: 2,
+};
 
 function nowISO() {
     return new Date().toISOString();
@@ -51,20 +72,79 @@ function createEmptyWorkspaceIndex() {
     };
 }
 
+function resolveGlobalRootDir() {
+    const customRoot = process.env.AG_KIT_GLOBAL_ROOT;
+    if (typeof customRoot === "string" && customRoot.trim()) {
+        return path.resolve(process.cwd(), customRoot);
+    }
+    return os.homedir();
+}
+
+function getGlobalDestinations(targetName, globalRoot = resolveGlobalRootDir()) {
+    const config = GLOBAL_TARGET_DESTINATIONS[targetName];
+    if (!config) {
+        throw new Error(`未知目标: ${targetName}`);
+    }
+    return config.map((item) => ({
+        ...item,
+        targetName,
+        rootDir: path.join(globalRoot, ...item.rootParts),
+        skillsRoot: path.join(globalRoot, ...item.skillsParts),
+    }));
+}
+
+function listGlobalDestinations(globalRoot = resolveGlobalRootDir()) {
+    return Object.keys(GLOBAL_TARGET_DESTINATIONS).flatMap((targetName) => getGlobalDestinations(targetName, globalRoot));
+}
+
+function resolveGlobalBackupRoot(timestamp) {
+    const globalRoot = resolveGlobalRootDir();
+    return path.join(globalRoot, ".ag-kit", "backups", "global", timestamp);
+}
+
+function copyDirRecursive(src, dest) {
+    fs.mkdirSync(dest, { recursive: true });
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(src, entry.name);
+        const destPath = path.join(dest, entry.name);
+        if (entry.isDirectory()) {
+            copyDirRecursive(srcPath, destPath);
+        } else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}
+
+function areDirectoriesEqual(leftDir, rightDir) {
+    const left = ManifestManager.generateFromDir(leftDir);
+    const right = ManifestManager.generateFromDir(rightDir);
+    const leftKeys = Object.keys(left);
+    const rightKeys = Object.keys(right);
+    if (leftKeys.length !== rightKeys.length) {
+        return false;
+    }
+    for (const key of leftKeys) {
+        if (left[key] !== right[key]) {
+            return false;
+        }
+    }
+    return true;
+}
+
 function printUsage() {
     console.log("用法:");
     console.log("  ag-kit init [--force] [--path <dir>] [--branch <name>] [--target <name>|--targets <a,b>] [--non-interactive] [--no-index] [--quiet] [--dry-run]");
     console.log("  ag-kit update [--path <dir>] [--branch <name>] [--target <name>|--targets <a,b>] [--no-index] [--quiet] [--dry-run]");
     console.log("  ag-kit update-all [--branch <name>] [--targets <a,b>] [--prune-missing] [--quiet] [--dry-run]");
     console.log("  ag-kit doctor [--path <dir>] [--target <name>|--targets <a,b>] [--fix] [--quiet]");
+    console.log("  ag-kit global sync [--target <name>|--targets <a,b>] [--branch <name>] [--quiet] [--dry-run]  # 默认同步 codex + gemini(cli+antigravity)");
+    console.log("  ag-kit global status [--quiet]");
     console.log("  ag-kit exclude list [--quiet]");
     console.log("  ag-kit exclude add --path <dir> [--dry-run] [--quiet]");
     console.log("  ag-kit exclude remove --path <dir> [--dry-run] [--quiet]");
     console.log("  ag-kit status [--path <dir>] [--quiet]");
     console.log("  ag-kit --version");
-    console.log("");
-    console.log("说明:");
-    console.log("  --target gemini/codex/full 现均归一为统一 full 安装（.agents 为主目录）");
 }
 
 function printVersion() {
@@ -89,18 +169,16 @@ function parseArgs(argv) {
         path: "",
         branch: "",
         targets: [],
-        agentConflictPolicy: "",
-        geminiAgentsPolicy: "",
     };
     const providedFlags = [];
 
     let startIndex = 1;
-    if (command === "exclude") {
+    if (command === "exclude" || command === "global") {
         if (argv.length > 1 && !argv[1].startsWith("--")) {
             options.subcommand = argv[1];
             startIndex = 2;
         } else {
-            options.subcommand = "list";
+            options.subcommand = command === "global" ? "status" : "list";
             startIndex = 1;
         }
     }
@@ -167,6 +245,8 @@ const COMMAND_ALLOWED_FLAGS = {
     "update-all": ["--branch", "--targets", "--prune-missing", "--quiet", "--dry-run"],
     doctor: ["--path", "--target", "--targets", "--fix", "--quiet"],
     status: ["--path", "--quiet"],
+    "global:sync": ["--target", "--targets", "--branch", "--quiet", "--dry-run"],
+    "global:status": ["--quiet"],
     "exclude:list": ["--quiet"],
     "exclude:add": ["--path", "--dry-run", "--quiet"],
     "exclude:remove": ["--path", "--dry-run", "--quiet"],
@@ -178,6 +258,11 @@ function resolveAllowedFlags(command, options) {
         const key = `exclude:${subcommand}`;
         return COMMAND_ALLOWED_FLAGS[key] || null;
     }
+    if (command === "global") {
+        const subcommand = String(options.subcommand || "status").toLowerCase();
+        const key = `global:${subcommand}`;
+        return COMMAND_ALLOWED_FLAGS[key] || null;
+    }
     return COMMAND_ALLOWED_FLAGS[command] || null;
 }
 
@@ -186,6 +271,10 @@ function resolveCommandLabel(command, options) {
         const subcommand = String(options.subcommand || "list").toLowerCase();
         return `exclude ${subcommand}`;
     }
+    if (command === "global") {
+        const subcommand = String(options.subcommand || "status").toLowerCase();
+        return `global ${subcommand}`;
+    }
     return command;
 }
 
@@ -357,25 +446,34 @@ function normalizeTargetState(value) {
     };
 }
 
-function normalizeTargetName(rawTarget) {
-    const key = String(rawTarget || "").trim().toLowerCase();
-    if (!key) {
-        return "";
+function normalizeIndexTargetName(targetName) {
+    if (typeof targetName !== "string") {
+        return null;
+    }
+    const normalized = targetName.trim().toLowerCase();
+    if (!normalized) {
+        return null;
+    }
+    if (Object.prototype.hasOwnProperty.call(LEGACY_INDEX_TARGET_ALIASES, normalized)) {
+        return LEGACY_INDEX_TARGET_ALIASES[normalized];
     }
-    return TARGET_ALIAS_MAP[key] || "";
+    if (SUPPORTED_TARGETS.includes(normalized)) {
+        return normalized;
+    }
+    return null;
 }
 
 function normalizeWorkspaceRecordV2(item, normalizedPath) {
     const targets = {};
     if (item && item.targets && typeof item.targets === "object") {
         for (const [targetName, state] of Object.entries(item.targets)) {
-            const normalizedTarget = normalizeTargetName(targetName);
-            if (!normalizedTarget) {
+            const normalizedTargetName = normalizeIndexTargetName(targetName);
+            if (!normalizedTargetName) {
                 continue;
             }
             const normalizedState = normalizeTargetState(state);
             if (normalizedState) {
-                targets[normalizedTarget] = normalizedState;
+                targets[normalizedTargetName] = normalizedState;
             }
         }
     }
@@ -389,7 +487,7 @@ function migrateRecordV1ToV2(item, normalizedPath) {
     const targets = {};
     const installedAt = typeof item.installedAt === "string" ? item.installedAt : "";
     if (installedAt) {
-        targets.full = {
+        targets.gemini = {
             version: typeof item.cliVersion === "string" ? item.cliVersion : "",
             installedAt,
             updatedAt: typeof item.lastUpdatedAt === "string" ? item.lastUpdatedAt : installedAt,
@@ -594,14 +692,13 @@ function upsertWorkspaceTarget(index, workspaceRoot, targetName, timestamp) {
         record.targets = {};
     }
 
-    const normalizedTarget = normalizeTargetName(targetName) || "full";
-    const prev = normalizeTargetState(record.targets[normalizedTarget]) || {
+    const prev = normalizeTargetState(record.targets[targetName]) || {
         version: "",
         installedAt: "",
         updatedAt: "",
     };
 
-    record.targets[normalizedTarget] = {
+    record.targets[targetName] = {
         version: pkg.version,
         installedAt: prev.installedAt || timestamp,
         updatedAt: timestamp,
@@ -698,7 +795,12 @@ function maybeWarnUpstreamGlobalConflict(command, options) {
     if (process.env.AG_KIT_SKIP_UPSTREAM_CHECK === "1") {
         return;
     }
-    if (command !== "init" && command !== "update" && command !== "update-all") {
+    const shouldWarn =
+        command === "init"
+        || command === "update"
+        || command === "update-all"
+        || (command === "global" && String(options.subcommand || "").toLowerCase() === "sync");
+    if (!shouldWarn) {
         return;
     }
 
@@ -714,25 +816,7 @@ function maybeWarnUpstreamGlobalConflict(command, options) {
     log(options, `⚠️ 检测到全局已安装上游英文版 ${UPSTREAM_GLOBAL_PACKAGE}。`);
     log(options, "⚠️ 上游英文版与当前中文版共用 `ag-kit` 命令名，后安装者会覆盖命令入口。");
     log(options, `👉 建议执行: npm uninstall -g ${UPSTREAM_GLOBAL_PACKAGE}`);
-}
-
-function maybeWarnLegacyTargetAlias(options, rawTargets) {
-    if (options.quiet) {
-        return;
-    }
-    const aliases = [];
-    for (const raw of rawTargets || []) {
-        const key = String(raw || "").trim().toLowerCase();
-        if (!key || key === "full" || key === "agents") {
-            continue;
-        }
-        if (key === "gemini" || key === "codex") {
-            aliases.push(key);
-        }
-    }
-    if (aliases.length > 0) {
-        log(options, `ℹ️ 检测到兼容目标参数: ${Array.from(new Set(aliases)).join(", ")}，将自动归一为 full 安装流程。`);
-    }
+    log(options, "ℹ️ 若你通过 bun install -g 安装，Bun 默认会阻止本包 postinstall；因此这里会在首次执行 CLI 时再次提醒。");
 }
 
 function normalizeTargets(rawTargets) {
@@ -752,13 +836,9 @@ function normalizeTargets(rawTargets) {
             if (!SUPPORTED_TARGETS.includes(target)) {
                 throw new Error(`不支持的目标: ${target}（可选: ${SUPPORTED_TARGETS.join(", ")}）`);
             }
-            const normalized = normalizeTargetName(target);
-            if (!normalized) {
-                continue;
-            }
-            if (!seen.has(normalized)) {
-                seen.add(normalized);
-                result.push(normalized);
+            if (!seen.has(target)) {
+                seen.add(target);
+                result.push(target);
             }
         }
     }
@@ -766,66 +846,155 @@ function normalizeTargets(rawTargets) {
     return result;
 }
 
-function isManagedLegacyCodexDir(workspaceRoot) {
-    const legacyManifest = path.join(workspaceRoot, ".codex", "manifest.json");
-    if (!fs.existsSync(legacyManifest)) {
-        return false;
+function detectInstalledTargets(workspaceRoot) {
+    const targets = [];
+    if (fs.existsSync(path.join(workspaceRoot, ".agent"))) {
+        targets.push("gemini");
     }
-    try {
-        const parsed = JSON.parse(fs.readFileSync(legacyManifest, "utf8"));
-        const target = typeof parsed.target === "string" ? parsed.target.toLowerCase() : "";
-        return (target === "codex" || target === "full") && parsed.files && typeof parsed.files === "object";
-    } catch (_err) {
-        return false;
+    if (fs.existsSync(path.join(workspaceRoot, ".agents")) || fs.existsSync(path.join(workspaceRoot, ".codex"))) {
+        targets.push("codex");
     }
+    return targets;
 }
 
-function hasLegacyLayoutSignal(workspaceRoot) {
-    return fs.existsSync(path.join(workspaceRoot, ".agent"))
-        || fs.existsSync(path.join(workspaceRoot, ".gemini"))
-        || isManagedLegacyCodexDir(workspaceRoot);
+function isTargetInstalled(workspaceRoot, targetName) {
+    if (targetName === "gemini") {
+        return fs.existsSync(path.join(workspaceRoot, ".agent"));
+    }
+    if (targetName === "codex") {
+        return fs.existsSync(path.join(workspaceRoot, ".agents")) || fs.existsSync(path.join(workspaceRoot, ".codex"));
+    }
+    return false;
 }
 
-function detectInstalledTargets(workspaceRoot) {
-    if (fs.existsSync(path.join(workspaceRoot, ".agents")) || hasLegacyLayoutSignal(workspaceRoot)) {
-        return ["full"];
+function setQuietStatusExitCode(state) {
+    process.exitCode = Object.prototype.hasOwnProperty.call(QUIET_STATUS_EXIT_CODES, state)
+        ? QUIET_STATUS_EXIT_CODES[state]
+        : 1;
+}
+
+function normalizeIntegrityState(result) {
+    if (!result || result.status === "missing") {
+        return "missing";
+    }
+    if (result.status === "ok") {
+        return "installed";
     }
-    return [];
+    return "broken";
 }
 
-function isTargetInstalled(workspaceRoot, targetName) {
-    const normalized = normalizeTargetName(targetName);
-    if (normalized === "full") {
-        return fs.existsSync(path.join(workspaceRoot, ".agents")) || hasLegacyLayoutSignal(workspaceRoot);
+function evaluateWorkspaceState(workspaceRoot, options) {
+    const targets = detectInstalledTargets(workspaceRoot);
+    if (targets.length === 0) {
+        return {
+            state: "missing",
+            targets: [],
+        };
     }
-    return false;
+
+    const targetStates = targets.map((targetName) => {
+        const adapter = createAdapter(targetName, workspaceRoot, {
+            ...options,
+            quiet: true,
+        });
+        const integrity = adapter.checkIntegrity();
+        return {
+            targetName,
+            state: normalizeIntegrityState(integrity),
+            integrity,
+            version: typeof adapter.getInstalledVersion === "function" ? adapter.getInstalledVersion() : null,
+        };
+    });
+
+    const hasIssue = targetStates.some((item) => item.state !== "installed");
+    return {
+        state: hasIssue ? "broken" : "installed",
+        targets: targetStates,
+    };
+}
+
+function evaluateGlobalState() {
+    const globalRoot = resolveGlobalRootDir();
+    const targetStates = listGlobalDestinations(globalRoot).map((destination) => {
+        const rootExists = fs.existsSync(destination.rootDir);
+        const skillsExists = fs.existsSync(destination.skillsRoot);
+        const skillsCount = skillsExists ? countSkillsRecursive(destination.skillsRoot) : 0;
+        let state = "missing";
+        const issues = [];
+
+        if (rootExists || skillsExists) {
+            if (!skillsExists) {
+                state = "broken";
+                issues.push("Skills 根目录缺失");
+            } else if (skillsCount === 0) {
+                state = "broken";
+                issues.push("未检测到任何 SKILL.md");
+            } else {
+                state = "installed";
+            }
+        }
+
+        return {
+            targetName: destination.id,
+            family: destination.targetName,
+            state,
+            rootDir: destination.rootDir,
+            skillsRoot: destination.skillsRoot,
+            skillsCount,
+            issues,
+        };
+    }).filter((item) => item.state !== "missing");
+
+    if (targetStates.length === 0) {
+        return {
+            globalRoot,
+            state: "missing",
+            targets: [],
+        };
+    }
+
+    const hasIssue = targetStates.some((item) => item.state !== "installed");
+    return {
+        globalRoot,
+        state: hasIssue ? "broken" : "installed",
+        targets: targetStates,
+    };
 }
 
 function createAdapter(targetName, workspaceRoot, options) {
-    const normalized = normalizeTargetName(targetName);
-    if (normalized === "full") {
+    if (targetName === "gemini") {
+        return new GeminiAdapter(workspaceRoot, options);
+    }
+    if (targetName === "codex") {
         return new CodexAdapter(workspaceRoot, options);
     }
     throw new Error(`未知目标: ${targetName}`);
 }
 
 async function resolveTargetsForInit(options) {
-    maybeWarnLegacyTargetAlias(options, options.targets);
     let targets = normalizeTargets(options.targets);
 
     if (targets.length > 0) {
         return targets;
     }
+
+    if (options.nonInteractive) {
+        throw new Error("非交互模式下必须通过 --target 或 --targets 指定目标");
+    }
+
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        throw new Error("当前环境不是交互终端，请通过 --target 或 --targets 指定目标");
+    }
+
     targets = normalizeTargets(await selectTargets(options));
     if (targets.length === 0) {
-        return ["full"];
+        throw new Error("必须选择至少一个目标");
     }
 
     return targets;
 }
 
 function resolveTargetsForUpdate(workspaceRoot, options) {
-    maybeWarnLegacyTargetAlias(options, options.targets);
     const requested = normalizeTargets(options.targets);
     if (requested.length > 0) {
         return requested;
@@ -833,50 +1002,267 @@ function resolveTargetsForUpdate(workspaceRoot, options) {
     return detectInstalledTargets(workspaceRoot);
 }
 
-async function resolveConflictPolicies(workspaceRoot, options) {
-    const next = { ...options };
-    const isInteractive = !next.nonInteractive && process.stdin.isTTY && process.stdout.isTTY;
+function resolveTargetsForGlobalSync(options) {
+    const requested = normalizeTargets(options.targets);
+    if (requested.length > 0) {
+        return requested;
+    }
+    // 保持 global sync 简洁：默认同步 codex + gemini；其中 gemini 会展开为 gemini-cli 与 antigravity。
+    return ["codex", "gemini"];
+}
+
+function resolveAgentInstallSource(options) {
+    let agentDir = BUNDLED_AGENT_DIR;
+    let cleanup = null;
+    let sourceLabel = "bundled";
 
-    if (!next.agentConflictPolicy) {
-        if (fs.existsSync(path.join(workspaceRoot, ".agent")) && isInteractive) {
-            next.agentConflictPolicy = await selectAgentConflictPolicy();
-        } else {
-            next.agentConflictPolicy = "backup_replace";
+    if (options.branch) {
+        const remote = cloneBranchAgentDir(options.branch, {
+            quiet: options.quiet,
+            logger: log.bind(null, options),
+        });
+        agentDir = remote.agentDir;
+        cleanup = remote.cleanup;
+        sourceLabel = `branch:${options.branch}`;
+    }
+
+    if (!fs.existsSync(agentDir) && !options.branch) {
+        const legacyDir = path.resolve(__dirname, "../.agent");
+        if (fs.existsSync(legacyDir)) {
+            agentDir = legacyDir;
+            sourceLabel = "bundled:legacy";
         }
     }
 
-    if (!next.geminiAgentsPolicy) {
-        if (fs.existsSync(path.join(workspaceRoot, ".gemini", "agents")) && isInteractive) {
-            next.geminiAgentsPolicy = await selectGeminiAgentsPolicy();
-        } else {
-            next.geminiAgentsPolicy = "append";
+    if (!fs.existsSync(agentDir)) {
+        throw new Error(`未找到模板目录: ${agentDir}`);
+    }
+
+    return { agentDir, cleanup, sourceLabel };
+}
+
+function listSkillDirectories(skillsRoot) {
+    if (!fs.existsSync(skillsRoot)) {
+        return [];
+    }
+    return fs
+        .readdirSync(skillsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => entry.name)
+        .filter((name) => fs.existsSync(path.join(skillsRoot, name, "SKILL.md")));
+}
+
+function backupSkillDirectory(targetName, skillName, sourceDir, timestamp, options) {
+    const backupRoot = resolveGlobalBackupRoot(timestamp);
+    const backupDir = path.join(backupRoot, targetName, skillName);
+    fs.mkdirSync(path.dirname(backupDir), { recursive: true });
+    copyDirRecursive(sourceDir, backupDir);
+    log(options, `📦 已备份 ${targetName} 全局 Skill: ${skillName} -> ${backupDir}`);
+}
+
+function syncSkillDirectory(destination, srcDir, destDir, timestamp, options) {
+    const exists = fs.existsSync(destDir);
+    if (exists) {
+        if (areDirectoriesEqual(srcDir, destDir)) {
+            log(options, `⏭️ 全局 Skill 已最新，无需同步: ${destination.id}/${path.basename(destDir)}`);
+            return { skipped: 1, synced: 0, backedUp: 0 };
         }
     }
 
-    return next;
+    if (options.dryRun) {
+        log(options, `[dry-run] 将同步全局 Skill: ${destination.id}/${path.basename(destDir)}`);
+        return { skipped: 0, synced: 0, backedUp: exists ? 1 : 0 };
+    }
+
+    let backedUp = 0;
+    if (exists) {
+        backupSkillDirectory(destination.id, path.basename(destDir), destDir, timestamp, options);
+        backedUp = 1;
+    }
+
+    const logger = options.quiet ? (() => {}) : log.bind(null, options);
+    AtomicWriter.atomicCopyDir(srcDir, destDir, { logger });
+    log(options, `✅ 已同步全局 Skill: ${destination.id}/${path.basename(destDir)}`);
+
+    return { skipped: 0, synced: 1, backedUp };
+}
+
+function syncGlobalSkillsFromRoot(targetName, skillsRoot, timestamp, options) {
+    const destinations = getGlobalDestinations(targetName);
+    const skillNames = listSkillDirectories(skillsRoot);
+    if (skillNames.length === 0) {
+        throw new Error(`未检测到可同步的 Skills: ${skillsRoot}`);
+    }
+
+    if (options.dryRun) {
+        for (const destination of destinations) {
+            log(options, `[dry-run] 将同步 ${skillNames.length} 个全局 Skills -> ${destination.skillsRoot}`);
+        }
+    }
+
+    let synced = 0;
+    let skipped = 0;
+    let backedUp = 0;
+    const destinationResults = [];
+
+    for (const destination of destinations) {
+        let destinationSynced = 0;
+        let destinationSkipped = 0;
+        let destinationBackedUp = 0;
+
+        for (const skillName of skillNames) {
+            const srcDir = path.join(skillsRoot, skillName);
+            const destDir = path.join(destination.skillsRoot, skillName);
+            const result = syncSkillDirectory(destination, srcDir, destDir, timestamp, options);
+            synced += result.synced;
+            skipped += result.skipped;
+            backedUp += result.backedUp;
+            destinationSynced += result.synced;
+            destinationSkipped += result.skipped;
+            destinationBackedUp += result.backedUp;
+        }
+
+        destinationResults.push({
+            targetName: destination.id,
+            family: destination.targetName,
+            destRoot: destination.skillsRoot,
+            total: skillNames.length,
+            synced: destinationSynced,
+            skipped: destinationSkipped,
+            backedUp: destinationBackedUp,
+        });
+    }
+
+    return {
+        total: skillNames.length * destinations.length,
+        skillsPerDestination: skillNames.length,
+        synced,
+        skipped,
+        backedUp,
+        destinations: destinationResults,
+    };
+}
+
+function applyGlobalSync(targetName, agentDir, timestamp, options) {
+    if (targetName === "codex") {
+        const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-global-codex-"));
+        const mockRoot = path.join(tempRoot, "source");
+        const mockAgent = path.join(mockRoot, ".agents");
+        const outputDir = path.join(tempRoot, "out");
+
+        try {
+            copyDirRecursive(agentDir, mockAgent);
+            CodexBuilder.build(mockRoot, outputDir);
+            const skillsRoot = path.join(outputDir, "skills");
+            return syncGlobalSkillsFromRoot(targetName, skillsRoot, timestamp, options);
+        } finally {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+    }
+
+    if (targetName === "gemini") {
+        const skillsRoot = path.join(agentDir, "skills");
+        return syncGlobalSkillsFromRoot(targetName, skillsRoot, timestamp, options);
+    }
+
+    throw new Error(`未知目标: ${targetName}`);
+}
+
+async function commandGlobalSync(options) {
+    const targets = await resolveTargetsForGlobalSync(options);
+    const { agentDir, cleanup, sourceLabel } = resolveAgentInstallSource(options);
+    const timestamp = nowISO().replace(/[:.]/g, "-");
+
+    try {
+        log(options, `🌍 全局同步源: ${sourceLabel}`);
+        for (const target of targets) {
+            log(options, `📦 正在同步全局目标 [${target}] ...`);
+            const result = applyGlobalSync(target, agentDir, timestamp, options);
+            if (!options.dryRun) {
+                log(options, `📊 全局同步完成 [${target}]：总计 ${result.total}，新增/覆盖 ${result.synced}，跳过 ${result.skipped}，备份 ${result.backedUp}`);
+                for (const item of result.destinations) {
+                    log(options, `   - ${item.targetName}: ${item.destRoot}（每目标 ${item.total} 个 Skills）`);
+                }
+            }
+        }
+    } finally {
+        if (cleanup) cleanup();
+    }
+}
+
+function commandGlobalStatus(options) {
+    const summary = evaluateGlobalState();
+
+    if (summary.state === "missing") {
+        if (options.quiet) {
+            console.log("missing");
+        }
+        if (!options.quiet) {
+            console.log("❌ 未检测到全局安装的 Skills");
+            console.log(`   全局根目录: ${summary.globalRoot}`);
+        }
+        setQuietStatusExitCode("missing");
+        return;
+    }
+
+    if (options.quiet) {
+        console.log(summary.state);
+        setQuietStatusExitCode(summary.state);
+        return;
+    }
+
+    console.log(summary.state === "installed" ? "✅ 全局 Skills 状态正常" : "⚠️ 全局 Skills 存在问题");
+    console.log(`   全局根目录: ${summary.globalRoot}`);
+    console.log(`   总体状态: ${summary.state}`);
+    console.log(`   Targets: ${summary.targets.map((item) => item.targetName).join(", ")}`);
+
+    for (const item of summary.targets) {
+        console.log(`\n[${item.targetName}:global]`);
+        console.log(`   家族: ${item.family}`);
+        console.log(`   状态: ${item.state}`);
+        console.log(`   路径: ${item.skillsRoot}`);
+        if (item.state === "installed") {
+            console.log(`   Skills: ${item.skillsCount}`);
+            continue;
+        }
+        for (const issue of item.issues) {
+            console.log(`   Issue: ${issue}`);
+        }
+    }
+
+    setQuietStatusExitCode(summary.state);
+}
+
+function commandGlobal(options) {
+    const subcommand = String(options.subcommand || "status").toLowerCase();
+    if (subcommand === "sync") {
+        return commandGlobalSync(options);
+    }
+    if (subcommand === "status") {
+        return commandGlobalStatus(options);
+    }
+    throw new Error(`未知 global 子命令: ${subcommand}`);
 }
 
 async function commandInit(options) {
     const workspaceRoot = resolveWorkspaceRoot(options.path);
     const targets = await resolveTargetsForInit(options);
-    const runOptions = await resolveConflictPolicies(workspaceRoot, options);
 
     for (const target of targets) {
-        const adapter = createAdapter(target, workspaceRoot, runOptions);
+        const adapter = createAdapter(target, workspaceRoot, options);
         log(options, `📦 正在初始化目标 [${target}] ...`);
         adapter.install(BUNDLED_AGENT_DIR);
-        registerWorkspaceTarget(workspaceRoot, target, runOptions);
+        registerWorkspaceTarget(workspaceRoot, target, options);
     }
 
     if (targets.length > 0) {
-        log(options, `✅ 初始化完成 (Mode: ${targets.join(", ")})`);
+        log(options, `✅ 初始化完成 (Targets: ${targets.join(", ")})`);
     }
 }
 
 async function commandUpdate(options) {
     const workspaceRoot = resolveWorkspaceRoot(options.path);
     const targets = resolveTargetsForUpdate(workspaceRoot, options);
-    const runOptions = await resolveConflictPolicies(workspaceRoot, options);
 
     if (targets.length === 0) {
         throw new Error("此目录未检测到 Antigravity Kit 安装，无法更新。请先执行 init。");
@@ -894,11 +1280,11 @@ async function commandUpdate(options) {
             continue;
         }
 
-        const targetOptions = { ...runOptions, force: true };
-        const adapter = createAdapter(target, workspaceRoot, targetOptions);
+        const runOptions = { ...options, force: true };
+        const adapter = createAdapter(target, workspaceRoot, runOptions);
         log(options, `📦 更新 [${target}] ...`);
         adapter.update(BUNDLED_AGENT_DIR);
-        registerWorkspaceTarget(workspaceRoot, target, targetOptions);
+        registerWorkspaceTarget(workspaceRoot, target, runOptions);
         updatedAny = true;
     }
 
@@ -912,13 +1298,12 @@ function mergeUpdatedTargets(record, workspacePath, targetNames, timestamp) {
     const next = normalizeWorkspaceRecordV2(record || {}, normalizedPath);
 
     for (const target of targetNames) {
-        const normalizedTarget = normalizeTargetName(target) || "full";
-        const prev = normalizeTargetState(next.targets[normalizedTarget]) || {
+        const prev = normalizeTargetState(next.targets[target]) || {
             version: "",
             installedAt: "",
             updatedAt: "",
         };
-        next.targets[normalizedTarget] = {
+        next.targets[target] = {
             version: pkg.version,
             installedAt: prev.installedAt || timestamp,
             updatedAt: timestamp,
@@ -933,7 +1318,6 @@ async function commandUpdateAll(options) {
         throw new Error("update-all 不支持 --path，请直接执行 ag-kit update-all");
     }
 
-    maybeWarnLegacyTargetAlias(options, options.targets);
     const requestedTargets = normalizeTargets(options.targets);
     const { indexPath, index } = readWorkspaceIndex();
     const records = index.workspaces || [];
@@ -1016,8 +1400,6 @@ async function commandUpdateAll(options) {
                     force: true,
                     path: workspacePath,
                     silentIndexLog: true,
-                    agentConflictPolicy: "backup_replace",
-                    geminiAgentsPolicy: "append",
                 };
                 const adapter = createAdapter(target, workspacePath, runOptions);
                 adapter.update(BUNDLED_AGENT_DIR);
@@ -1311,61 +1693,76 @@ function countSkillsRecursive(dir) {
 
 function commandStatus(options) {
     const workspaceRoot = resolveWorkspaceRoot(options.path);
-    const installedTargets = detectInstalledTargets(workspaceRoot);
+    const summary = evaluateWorkspaceState(workspaceRoot, options);
 
-    if (installedTargets.length === 0) {
+    if (summary.state === "missing") {
+        if (options.quiet) {
+            console.log("missing");
+        }
         if (!options.quiet) {
             console.log("❌ 未检测到 Antigravity Kit 安装");
             console.log(`   目标目录: ${workspaceRoot}`);
         }
-        process.exitCode = 1;
+        setQuietStatusExitCode("missing");
         return;
     }
 
     if (options.quiet) {
-        console.log("installed");
+        console.log(summary.state);
+        setQuietStatusExitCode(summary.state);
         return;
     }
 
-    console.log("✅ Antigravity Kit 已安装");
+    console.log(summary.state === "installed" ? "✅ Antigravity Kit 状态正常" : "⚠️ Antigravity Kit 存在问题");
     console.log(`   CLI 版本: ${pkg.version}`);
     console.log(`   工作区: ${workspaceRoot}`);
-    console.log(`   Mode: ${installedTargets.join(", ")}`);
-
-    const managedDir = path.join(workspaceRoot, ".agents");
-    const agentProjectionDir = path.join(workspaceRoot, ".agent");
-    const geminiProjectionDir = path.join(workspaceRoot, ".gemini");
-    const legacyDir = path.join(workspaceRoot, ".codex");
-    const hasManaged = fs.existsSync(managedDir);
-    const hasLegacy = fs.existsSync(legacyDir);
-    const isManagedLegacy = isManagedLegacyCodexDir(workspaceRoot);
-
-    const skillsCount = countSkillsRecursive(path.join(managedDir, "skills"));
-    const agentsCount = countFilesIfExists(path.join(managedDir, "agents"), (name) => name.endsWith(".md"));
-    const workflowsCount = countFilesIfExists(path.join(managedDir, "workflows"), (name) => name.endsWith(".md"));
-    const hasManifest = fs.existsSync(path.join(managedDir, "manifest.json"));
-
-    console.log("\n[full]");
-    console.log(`   Canonical(.agents): ${hasManaged ? "yes" : "no"}`);
-    if (hasManaged) {
-        console.log(`   Skills: ${skillsCount}`);
-        console.log(`   Agents: ${agentsCount}`);
-        console.log(`   Workflows: ${workflowsCount}`);
-        console.log(`   Manifest: ${hasManifest ? "yes" : "no"}`);
+    console.log(`   总体状态: ${summary.state}`);
+    console.log(`   Targets: ${summary.targets.map((item) => item.targetName).join(", ")}`);
+
+    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}`);
+            }
+        }
     }
 
-    console.log("\n[projections]");
-    console.log(`   .agent: ${fs.existsSync(agentProjectionDir) ? "yes" : "no"}`);
-    console.log(`   .gemini: ${fs.existsSync(geminiProjectionDir) ? "yes" : "no"}`);
-
-    if (hasLegacy) {
-        console.log("\n[legacy]");
-        if (isManagedLegacy) {
-            console.log("   .codex: 托管 legacy（建议执行 ag-kit update 迁移清理）");
-        } else {
-            console.log("   .codex: 非托管目录（已保留，不会自动删除）");
+    const codexState = summary.targets.find((item) => item.targetName === "codex");
+    if (codexState) {
+        const managedDir = path.join(workspaceRoot, ".agents");
+        const legacyDir = path.join(workspaceRoot, ".codex");
+        const activeDir = fs.existsSync(managedDir) ? managedDir : legacyDir;
+        const skillsCount = countSkillsRecursive(path.join(activeDir, "skills"));
+        const hasManifest = fs.existsSync(path.join(activeDir, "manifest.json"));
+        const legacyDetected = fs.existsSync(legacyDir);
+        console.log("\n[codex]");
+        console.log(`   状态: ${codexState.state}`);
+        console.log(`   路径: ${activeDir}`);
+        console.log(`   Skills: ${skillsCount}`);
+        console.log(`   Manifest: ${hasManifest ? "yes" : "no"}`);
+        if (legacyDetected) {
+            console.log("   Legacy: 检测到 .codex（建议执行 ag-kit update 迁移清理）");
+        }
+        if (codexState.state !== "installed") {
+            for (const issue of codexState.integrity.issues || []) {
+                console.log(`   Issue: ${issue}`);
+            }
         }
     }
+
+    setQuietStatusExitCode(summary.state);
 }
 
 async function main() {
@@ -1407,6 +1804,11 @@ async function main() {
             return;
         }
 
+        if (command === "global") {
+            await commandGlobal(options);
+            return;
+        }
+
         if (command === "exclude") {
             commandExclude(options);
             return;