fix(cli): align global sync with real consumer paths

Author: MisonL

README.md

@@ -54,6 +54,9 @@ npm install -g .
 - 项目安装：`ag-kit init` / `ag-kit update`（功能最完整）
 - 全局安装：`ag-kit global sync`（仅同步 Skills，跨项目复用）
 - 默认行为：`ag-kit global sync` 未指定 `--target/--targets` 时，同步 `codex + gemini`
+- 真实落盘：
+  - `codex` -> `~/.codex/skills/`
+  - `gemini` -> 同时写入 `~/.gemini/skills/` 与 `~/.gemini/antigravity/skills/`
 
 示例：
 
@@ -165,7 +168,7 @@ CLI（命令行界面）工具：
 | `ag-kit update` | 更新当前项目已安装目标 |
 | `ag-kit update-all` | 批量更新所有已登记工作区 |
 | `ag-kit doctor` | 诊断安装完整性（可 `--fix` 自愈） |
-| `ag-kit global sync` | 全局同步 Skills（默认同步 codex+gemini） |
+| `ag-kit global sync` | 全局同步 Skills（默认同步 codex + gemini；其中 gemini 同步到 gemini-cli 与 antigravity） |
 | `ag-kit global status` | 查看全局 Skills 安装状态 |
 | `ag-kit exclude` | 管理全局索引排除清单 |
 | `ag-kit status` | 检查安装状态 |
@@ -227,7 +230,7 @@ bun install --cwd web
 bun run lint --cwd web
 ```
 
-> 说明：若你通过 `bun install -g` 安装 CLI，Bun 默认会阻止本包 `postinstall`。上游同名包冲突提示会在首次执行 `ag-kit init/update/global sync` 时给出。
+> 说明：若你通过 `bun install -g` 安装 CLI，Bun 默认会阻止本包 `postinstall`。上游同名包冲突提示会在首次执行 `ag-kit init/update/update-all/global sync` 时给出。
 
 ## 卸载
 

bin/ag-kit.js

@@ -18,6 +18,30 @@ 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 = ["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;
@@ -56,15 +80,21 @@ function resolveGlobalRootDir() {
     return os.homedir();
 }
 
-function resolveGlobalSkillRoot(targetName) {
-    const globalRoot = resolveGlobalRootDir();
-    if (targetName === "codex") {
-        return path.join(globalRoot, ".agents", "skills");
+function getGlobalDestinations(targetName, globalRoot = resolveGlobalRootDir()) {
+    const config = GLOBAL_TARGET_DESTINATIONS[targetName];
+    if (!config) {
+        throw new Error(`未知目标: ${targetName}`);
     }
-    if (targetName === "gemini") {
-        return path.join(globalRoot, ".gemini", "antigravity", "skills");
-    }
-    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) {
@@ -108,7 +138,7 @@ function printUsage() {
     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");
+    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]");
@@ -416,13 +446,34 @@ function normalizeTargetState(value) {
     };
 }
 
+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];
+    }
+    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 normalizedTargetName = normalizeIndexTargetName(targetName);
+            if (!normalizedTargetName) {
+                continue;
+            }
             const normalizedState = normalizeTargetState(state);
             if (normalizedState) {
-                targets[targetName] = normalizedState;
+                targets[normalizedTargetName] = normalizedState;
             }
         }
     }
@@ -862,33 +913,16 @@ function evaluateWorkspaceState(workspaceRoot, options) {
     };
 }
 
-function getGlobalTargetPaths(globalRoot, targetName) {
-    if (targetName === "codex") {
-        return {
-            markerDir: path.join(globalRoot, ".agents"),
-            skillsRoot: path.join(globalRoot, ".agents", "skills"),
-        };
-    }
-    if (targetName === "gemini") {
-        return {
-            markerDir: path.join(globalRoot, ".gemini", "antigravity"),
-            skillsRoot: path.join(globalRoot, ".gemini", "antigravity", "skills"),
-        };
-    }
-    throw new Error(`未知全局目标: ${targetName}`);
-}
-
 function evaluateGlobalState() {
     const globalRoot = resolveGlobalRootDir();
-    const targetStates = SUPPORTED_TARGETS.map((targetName) => {
-        const paths = getGlobalTargetPaths(globalRoot, targetName);
-        const markerExists = fs.existsSync(paths.markerDir);
-        const skillsExists = fs.existsSync(paths.skillsRoot);
-        const skillsCount = skillsExists ? countSkillsRecursive(paths.skillsRoot) : 0;
+    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 (markerExists || skillsExists) {
+        if (rootExists || skillsExists) {
             if (!skillsExists) {
                 state = "broken";
                 issues.push("Skills 根目录缺失");
@@ -901,10 +935,11 @@ function evaluateGlobalState() {
         }
 
         return {
-            targetName,
+            targetName: destination.id,
+            family: destination.targetName,
             state,
-            markerDir: paths.markerDir,
-            skillsRoot: paths.skillsRoot,
+            rootDir: destination.rootDir,
+            skillsRoot: destination.skillsRoot,
             skillsCount,
             issues,
         };
@@ -972,7 +1007,7 @@ function resolveTargetsForGlobalSync(options) {
     if (requested.length > 0) {
         return requested;
     }
-    // 保持 global sync 简洁：默认同步两个目标。
+    // 保持 global sync 简洁：默认同步 codex + gemini；其中 gemini 会展开为 gemini-cli 与 antigravity。
     return ["codex", "gemini"];
 }
 
@@ -1025,58 +1060,87 @@ function backupSkillDirectory(targetName, skillName, sourceDir, timestamp, optio
     log(options, `📦 已备份 ${targetName} 全局 Skill: ${skillName} -> ${backupDir}`);
 }
 
-function syncSkillDirectory(targetName, srcDir, destDir, timestamp, options) {
+function syncSkillDirectory(destination, srcDir, destDir, timestamp, options) {
     const exists = fs.existsSync(destDir);
     if (exists) {
         if (areDirectoriesEqual(srcDir, destDir)) {
-            log(options, `⏭️ 全局 Skill 已最新，无需同步: ${targetName}/${path.basename(destDir)}`);
+            log(options, `⏭️ 全局 Skill 已最新，无需同步: ${destination.id}/${path.basename(destDir)}`);
             return { skipped: 1, synced: 0, backedUp: 0 };
         }
     }
 
     if (options.dryRun) {
-        log(options, `[dry-run] 将同步全局 Skill: ${targetName}/${path.basename(destDir)}`);
+        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(targetName, path.basename(destDir), destDir, timestamp, options);
+        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: ${targetName}/${path.basename(destDir)}`);
+    log(options, `✅ 已同步全局 Skill: ${destination.id}/${path.basename(destDir)}`);
 
     return { skipped: 0, synced: 1, backedUp };
 }
 
 function syncGlobalSkillsFromRoot(targetName, skillsRoot, timestamp, options) {
-    const destRoot = resolveGlobalSkillRoot(targetName);
+    const destinations = getGlobalDestinations(targetName);
     const skillNames = listSkillDirectories(skillsRoot);
     if (skillNames.length === 0) {
         throw new Error(`未检测到可同步的 Skills: ${skillsRoot}`);
     }
 
     if (options.dryRun) {
-        log(options, `[dry-run] 将同步 ${skillNames.length} 个全局 Skills -> ${destRoot}`);
+        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;
+        }
 
-    for (const skillName of skillNames) {
-        const srcDir = path.join(skillsRoot, skillName);
-        const destDir = path.join(destRoot, skillName);
-        const result = syncSkillDirectory(targetName, srcDir, destDir, timestamp, options);
-        synced += result.synced;
-        skipped += result.skipped;
-        backedUp += 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, synced, skipped, backedUp, destRoot };
+    return {
+        total: skillNames.length * destinations.length,
+        skillsPerDestination: skillNames.length,
+        synced,
+        skipped,
+        backedUp,
+        destinations: destinationResults,
+    };
 }
 
 function applyGlobalSync(targetName, agentDir, timestamp, options) {
@@ -1116,7 +1180,9 @@ async function commandGlobalSync(options) {
             const result = applyGlobalSync(target, agentDir, timestamp, options);
             if (!options.dryRun) {
                 log(options, `📊 全局同步完成 [${target}]：总计 ${result.total}，新增/覆盖 ${result.synced}，跳过 ${result.skipped}，备份 ${result.backedUp}`);
-                log(options, `   目标路径: ${result.destRoot}`);
+                for (const item of result.destinations) {
+                    log(options, `   - ${item.targetName}: ${item.destRoot}（每目标 ${item.total} 个 Skills）`);
+                }
             }
         }
     } finally {
@@ -1152,6 +1218,7 @@ function commandGlobalStatus(options) {
 
     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") {

docs/PLAN.md

@@ -19,8 +19,8 @@ Ag-Kit 只做一件事：把仓库内统一的 `.agents/` 模板，优雅地投
 - 命令：`ag-kit global sync` / `ag-kit global status`
 - 默认行为：`ag-kit global sync` 未指定 `--target/--targets` 时，同步 `codex + gemini`
 - 目标路径：
-  - `codex` -> `$HOME/.agents/skills/`
-  - `gemini` -> `$HOME/.gemini/antigravity/skills/`
+  - `codex` -> `$HOME/.codex/skills/`
+  - `gemini` -> 同时写入 `$HOME/.gemini/skills/` 与 `$HOME/.gemini/antigravity/skills/`
 - 安全边界：全局只同步 Skills，不写入全局 Rules/Agents/Workflows。
 
 ## 覆盖与回滚（全局同步）
@@ -31,8 +31,9 @@ Ag-Kit 只做一件事：把仓库内统一的 `.agents/` 模板，优雅地投
 ## 兼容策略
 - Gemini/Antigravity：输出 `.agent/`，保持与官方工作区机制一致。
 - Codex：受管目录为 `.agents/`，并使用 `manifest.json` 做完整性与漂移检测；识别并迁移遗留 `.codex/`。
+- 全局同步遵循真实消费端目录，而不是仓库模板源目录；仓库内仍以 `.agents/` 作为唯一 Canonical。
 
 ## 成功标准
-- `ag-kit global sync` 一条命令即可完成全局 Skills 安装/更新（默认 codex+gemini）。
+- `ag-kit global sync` 一条命令即可完成全局 Skills 安装/更新（默认 codex + gemini，其中 gemini 同步到 gemini-cli 与 antigravity）。
 - 覆盖可回滚：每次覆盖同名 Skill 都有可用备份。
 - 跨平台 CI（Linux/macOS/Windows）验证主链路通过。