@mison/ling 1.2.0 → 1.2.3

package/CHANGELOG.md

@@ -7,6 +7,26 @@
 
 ## [Unreleased]
 
+## [ling-1.2.3] - 2026-03-15
+
+### 修复
+
+- 修复 Gemini CLI 全局 Skill 冲突：当 `~/.agents/skills/` 已提供同名 universal Skill 时，`ling global sync --target gemini` 与默认全局同步会自动备份并清理 `~/.gemini/skills/` 中的重复副本，避免 Gemini 启动时出现 `Skill conflict detected`。
+
+## [ling-1.2.2] - 2026-03-14
+
+### 修复
+
+- 修复全局 Skills 重复：当检测到旧版 `~/.codex/skills/` 时，同步 `codex` 会迁移到 `~/.agents/skills/` 并清理遗留目录；若与现有目录冲突则备份到 `~/.ling/backups/global/<timestamp>/codex-legacy/...`。
+
+## [ling-1.2.1] - 2026-03-14
+
+### 修复
+
+- 修正 Codex 全局 Skill 安装根目录：`ling global sync --target codex` 与 `ling spec enable --target codex` 现在统一写入官方要求的 `~/.agents/skills/`，不再误写到旧的 `~/.codex/skills/`。
+- 兼容旧版 Spec 状态：历史 `state.json` 中记录的 `~/.codex/skills/...` 路径会在读取时自动迁移为 `~/.agents/skills/...`，避免修复后仍引用旧路径。
+- 增加旧路径诊断：若用户机器上只存在旧版 `~/.codex/skills/`，`ling global status` 会返回 `broken` 并提示执行 `ling global sync --target codex` 修复。
+
 ## [ling-1.2.0] - 2026-03-14
 
 ### 新增
@@ -98,7 +118,8 @@
 
 本项目在 Ling 重启前的 2.x/3.x 版本记录已冻结，不再维护。
 
-[Unreleased]: https://github.com/MisonL/Ling/compare/ling-1.2.0...HEAD
+[Unreleased]: https://github.com/MisonL/Ling/compare/ling-1.2.1...HEAD
+[ling-1.2.1]: https://github.com/MisonL/Ling/releases/tag/ling-1.2.1
 [ling-1.2.0]: https://github.com/MisonL/Ling/releases/tag/ling-1.2.0
 [ling-1.1.1]: https://github.com/MisonL/Ling/releases/tag/ling-1.1.1
 [ling-1.1.0]: https://github.com/MisonL/Ling/releases/tag/ling-1.1.0

package/README.md

@@ -47,7 +47,7 @@ ling global sync --target antigravity
 | 你要做什么 | 命令 | 结果 |
 | --- | --- | --- |
 | 给当前项目安装完整资产 | `ling init` | 项目内生成 `.agent/` / `.agents/`；共享 `.agent/` 时会维护 `.ling/install-state.json` |
-| 给电脑全局同步可复用 Skills | `ling global sync` | 写入 `~/.codex/skills/`、`~/.gemini/skills/` 等 |
+| 给电脑全局同步可复用 Skills | `ling global sync` | 写入 `~/.agents/skills/`、`~/.gemini/antigravity/skills/` 等，并自动清理 Gemini CLI 的重复副本 |
 | 给项目启用 Spec 工作流 | `ling spec init` | 项目内生成 `issues.csv` 等 Spec 资产 |
 
 一句话区分：
@@ -89,10 +89,12 @@ ling global sync --target antigravity
 ling global status
 ```
 
-- `codex` -> `~/.codex/skills/`
-- `gemini` -> `~/.gemini/skills/`
+- `codex` -> `~/.agents/skills/`
+- `gemini` -> `~/.gemini/skills/`（若已存在 `~/.agents/skills/`，会自动移除重复副本，避免 Gemini CLI 冲突提示）
 - `antigravity` -> `~/.gemini/antigravity/skills/`
 
+若检测到旧版 `~/.codex/skills/`，`ling global sync --target codex` 会将其迁移到 `~/.agents/skills/` 并清理，避免 Skills 重复（冲突内容会先备份到 `~/.ling/backups/global/<timestamp>/codex-legacy/...`）。
+
 全局模式不会写入项目 Rules、Agents、Workflows，也不会改你的全局 `~/.codex/rules`。
 
 ## Spec

package/bin/ling-cli.js

@@ -28,8 +28,8 @@ const GLOBAL_TARGET_DESTINATIONS = {
     codex: [
         {
             id: "codex",
-            rootParts: [".codex"],
-            skillsParts: [".codex", "skills"],
+            rootParts: [".agents"],
+            skillsParts: [".agents", "skills"],
         },
     ],
     gemini: [
@@ -61,6 +61,8 @@ 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";
+const REDUNDANT_GEMINI_GLOBAL_SKILLS_BACKUP_TARGET = "gemini-cli-redundant";
 
 function nowISO() {
     return new Date().toISOString();
@@ -1154,6 +1156,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,
@@ -1271,6 +1289,120 @@ 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 reconcileGeminiGlobalSkillsAgainstUniversalRoot(timestamp, options) {
+    const [codexDestination] = getGlobalDestinations("codex");
+    const [geminiDestination] = getGlobalDestinations("gemini");
+    const universalRoot = codexDestination.skillsRoot;
+    const geminiRoot = geminiDestination.skillsRoot;
+
+    if (!fs.existsSync(universalRoot) || !fs.existsSync(geminiRoot)) {
+        return { removed: 0, backedUp: 0 };
+    }
+
+    let removed = 0;
+    let backedUp = 0;
+    for (const skillName of listSkillDirectories(geminiRoot)) {
+        const geminiSkillDir = path.join(geminiRoot, skillName);
+        const universalSkillDir = path.join(universalRoot, skillName);
+        if (!fs.existsSync(universalSkillDir)) {
+            continue;
+        }
+
+        if (options.dryRun) {
+            log(options, `[dry-run] 将移除 Gemini CLI 重复 Skill（由 universal 根目录提供）: ${geminiSkillDir}`);
+            removed += 1;
+            continue;
+        }
+
+        backupSkillDirectory(
+            REDUNDANT_GEMINI_GLOBAL_SKILLS_BACKUP_TARGET,
+            skillName,
+            geminiSkillDir,
+            timestamp,
+            options,
+        );
+        backedUp += 1;
+        fs.rmSync(geminiSkillDir, { recursive: true, force: true });
+        log(options, `[clean] 已移除 Gemini CLI 重复 Skill: ${geminiSkillDir}`);
+        removed += 1;
+    }
+
+    if (!options.dryRun && fs.existsSync(geminiRoot) && fs.readdirSync(geminiRoot).length === 0) {
+        fs.rmSync(geminiRoot, { recursive: true, force: true });
+        log(options, `[clean] 已删除空的 Gemini CLI skills 根目录: ${geminiRoot}`);
+    }
+
+    return { removed, backedUp };
+}
+
 function syncSkillDirectory(destination, srcDir, destDir, timestamp, options) {
     const exists = fs.existsSync(destDir);
     if (exists) {
@@ -1537,6 +1669,14 @@ async function commandGlobalSync(options) {
                         log(options, `   - ${item.targetName}: ${item.destRoot}（每目标 ${item.total} 个 Skills）`);
                     }
                 }
+
+                if (target === "codex") {
+                    migrateLegacyCodexGlobalSkills(timestamp, options);
+                    reconcileGeminiGlobalSkillsAgainstUniversalRoot(timestamp, options);
+                }
+                if (target === "gemini") {
+                    reconcileGeminiGlobalSkillsAgainstUniversalRoot(timestamp, options);
+                }
             } finally {
                 if (plan.cleanup) plan.cleanup();
             }
@@ -1626,15 +1766,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;
@@ -1646,9 +1892,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) {
@@ -2502,6 +2749,10 @@ async function commandSpecEnable(options) {
         writeSpecState(statePath, state);
     }
 
+    if (targets.includes("codex")) {
+        migrateLegacyCodexGlobalSkills(timestamp, options);
+    }
+
     log(options, `[ok] Spec Profile 已启用 (Targets: ${targets.join(", ")})`);
 }
 

package/docs/PLAN.md

@@ -20,10 +20,11 @@
 - 命令：`ling global sync` / `ling global status`
 - 默认行为：`ling global sync` 未指定 `--target/--targets` 时，同步 `codex + gemini + antigravity`
 - 目标路径：
-  - `codex` -> `$HOME/.codex/skills/`
-  - `gemini` -> `$HOME/.gemini/skills/`
+  - `codex` -> `$HOME/.agents/skills/`
+  - `gemini` -> `$HOME/.gemini/skills/`（若与 `$HOME/.agents/skills/` 重叠则清理重复副本）
   - `antigravity` -> `$HOME/.gemini/antigravity/skills/`
 - 安全边界：全局只同步 Skills，不写入全局 Rules/Agents/Workflows。
+- 旧版迁移：若存在遗留 `~/.codex/skills/`，同步 codex 时会迁移到 `$HOME/.agents/skills/` 并清理遗留根目录，避免 Skills 重复（冲突内容会备份到 `$HOME/.ling/backups/global/<timestamp>/codex-legacy/...`）。
 
 ## 覆盖与回滚（全局同步）
 - 覆盖单位：每个 Skill 目录。

package/docs/TECH.md

@@ -27,8 +27,8 @@ cd web && npm install && npm run lint
   - Codex：`<project>/.agents-backup/<timestamp>/preflight/.agents/` 或 `<project>/.agents-backup/<timestamp>/preflight/.codex/`
 
 ### 全局级（仅同步 Skills）
-- `codex`：`$HOME/.codex/skills/`
-- `gemini-cli`：`$HOME/.gemini/skills/`
+- `codex`：`$HOME/.agents/skills/`
+- `gemini-cli`：`$HOME/.gemini/skills/`（若存在与 `$HOME/.agents/skills/` 重叠的同名 Skill，灵轨会在同步后清理重复副本）
 - `antigravity`：`$HOME/.gemini/antigravity/skills/`
 
 > 说明：仓库内 Skills 源路径为 `.agents/skills/`，全局同步会将其投影到真实工具读取的全局目录；仓库 Canonical 仍是 `.agents/`。
@@ -64,6 +64,8 @@ cd web && npm install && npm run lint
 - 原子替换：按 Skill 目录原子替换，避免半写状态
 - 覆盖前备份：覆盖同名 Skill 前备份到 `$HOME/.ling/backups/global/<timestamp>/<consumer>/<skill>/...`
   - `consumer` 可能是 `codex`、`gemini-cli`、`antigravity`
+- 遗留迁移：若检测到旧版 `~/.codex/skills/`，同步 codex 时会迁移到 `~/.agents/skills/` 并清理，避免 Skills 重复（冲突内容会备份到 `.../codex-legacy/<skill>/...`）
+- Gemini 去重：若 `~/.agents/skills/` 已存在，同步 gemini 后会移除 `~/.gemini/skills/` 内同名重复目录，并备份到 `.../gemini-cli-redundant/<skill>/...`
 
 ### 测试隔离
 - `LING_GLOBAL_ROOT`：替代 `$HOME`（用于测试与 CI，避免污染真实用户目录）
@@ -154,7 +156,7 @@ cd web && npm install && npm run lint
 ## 手动回滚（全局 Skills）
 1. 找到备份目录：`$HOME/.ling/backups/global/<timestamp>/...`
 2. 按 Skill 回滚（推荐一次只处理一个 Skill 目录）：
-   - Codex 目标：恢复到 `$HOME/.codex/skills/<skill>/`
+   - Codex 目标：恢复到 `$HOME/.agents/skills/<skill>/`
    - Gemini CLI：恢复到 `$HOME/.gemini/skills/<skill>/`
    - Antigravity：恢复到 `$HOME/.gemini/antigravity/skills/<skill>/`
 
@@ -162,8 +164,8 @@ macOS / Linux 示例（把某个 Skill 回滚为备份版本）：
 ```bash
 ts="2026-03-12T12-00-00-000Z"
 skill="clean-code"
-rm -rf "$HOME/.codex/skills/$skill"
-cp -a "$HOME/.ling/backups/global/$ts/codex/$skill" "$HOME/.codex/skills/$skill"
+rm -rf "$HOME/.agents/skills/$skill"
+cp -a "$HOME/.ling/backups/global/$ts/codex/$skill" "$HOME/.agents/skills/$skill"
 ```
 
 Windows PowerShell 示例：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mison/ling",
-  "version": "1.2.0",
+  "version": "1.2.3",
   "description": "面向 Gemini CLI、Antigravity 与 Codex 的中文 AI Agent 模板工具包",
   "repository": {
     "type": "git",

package/scripts/ci-verify.js

@@ -96,13 +96,14 @@ function main() {
         throw new Error(`spec disable 后状态异常: ${specStatusAfterDisable}`);
     }
 
-    const codexSkill = path.join(globalRoot, ".codex", "skills", "workflow-plan", "SKILL.md");
-    const geminiCliSkill = path.join(globalRoot, ".gemini", "skills", "clean-code", "SKILL.md");
+    const codexSkill = path.join(globalRoot, ".agents", "skills", "workflow-plan", "SKILL.md");
     const antigravitySkill = path.join(globalRoot, ".gemini", "antigravity", "skills", "clean-code", "SKILL.md");
-    const specCodexSkill = path.join(globalRoot, ".codex", "skills", "harness-engineering");
+    const specCodexSkill = path.join(globalRoot, ".agents", "skills", "harness-engineering");
     ensureExists(codexSkill, "全局 Codex workflow-plan Skill");
-    ensureExists(geminiCliSkill, "全局 Gemini CLI clean-code Skill");
     ensureExists(antigravitySkill, "全局 Antigravity clean-code Skill");
+    if (fs.existsSync(path.join(globalRoot, ".gemini", "skills"))) {
+        throw new Error("默认全局同步后不应保留重复的 Gemini CLI skills 根目录");
+    }
     if (fs.existsSync(specCodexSkill)) {
         throw new Error(`spec disable 后仍残留 Spec Skill: ${specCodexSkill}`);
     }

package/scripts/health-check.js

@@ -113,8 +113,7 @@ function main() {
         }
 
         const globalChecks = [
-            path.join(globalRoot, ".codex", "skills", "workflow-plan", "SKILL.md"),
-            path.join(globalRoot, ".gemini", "skills", "clean-code", "SKILL.md"),
+            path.join(globalRoot, ".agents", "skills", "workflow-plan", "SKILL.md"),
             path.join(globalRoot, ".gemini", "antigravity", "skills", "clean-code", "SKILL.md"),
         ];
         for (const targetPath of globalChecks) {
@@ -122,6 +121,9 @@ function main() {
                 throw new Error(`global sync 未生成预期文件: ${targetPath}`);
             }
         }
+        if (fs.existsSync(path.join(globalRoot, ".gemini", "skills"))) {
+            throw new Error("默认全局同步后不应保留重复的 Gemini CLI skills 根目录");
+        }
     } finally {
         fs.rmSync(tempRoot, { recursive: true, force: true });
     }

package/tests/global-sync.test.js

@@ -42,7 +42,7 @@ describe("Global Sync", () => {
     });
 
     test("global status should report broken when target root exists but skills are incomplete", () => {
-        fs.mkdirSync(path.join(tempDir, ".codex"), { recursive: true });
+        fs.mkdirSync(path.join(tempDir, ".agents"), { recursive: true });
 
         const result = runCli(["global", "status", "--quiet"], {
             env: { LING_GLOBAL_ROOT: tempDir },
@@ -51,30 +51,92 @@ describe("Global Sync", () => {
         assert.strictEqual((result.stdout || "").trim(), "broken");
     });
 
-    test("global sync should install codex skills into $HOME/.codex/skills", () => {
+    test("global status should report broken when only legacy ~/.codex/skills exists", () => {
+        const legacySkillDir = path.join(tempDir, ".codex", "skills", "legacy-skill");
+        fs.mkdirSync(legacySkillDir, { recursive: true });
+        fs.writeFileSync(path.join(legacySkillDir, "SKILL.md"), "legacy", "utf8");
+
+        const result = runCli(["global", "status", "--quiet"], {
+            env: { LING_GLOBAL_ROOT: tempDir },
+        });
+        assert.strictEqual(result.status, 1);
+        assert.strictEqual((result.stdout || "").trim(), "broken");
+    });
+
+    test("global sync should install codex skills into $HOME/.agents/skills", () => {
         const result = runCli(["global", "sync", "--target", "codex", "--quiet"], {
             env: { LING_GLOBAL_ROOT: tempDir },
         });
         assert.strictEqual(result.status, 0, result.stderr || result.stdout);
 
-        const skillsRoot = path.join(tempDir, ".codex", "skills");
+        const skillsRoot = path.join(tempDir, ".agents", "skills");
         assert.ok(fs.existsSync(skillsRoot), "missing global codex skills root");
         assert.ok(fs.existsSync(path.join(skillsRoot, "clean-code", "SKILL.md")), "missing expected skill: clean-code");
         assert.ok(fs.existsSync(path.join(skillsRoot, "workflow-plan", "SKILL.md")), "missing expected workflow skill: workflow-plan");
     });
 
+    test("global sync should migrate legacy ~/.codex/skills and remove legacy root", () => {
+        const legacySkillDir = path.join(tempDir, ".codex", "skills", "legacy-skill");
+        fs.mkdirSync(legacySkillDir, { recursive: true });
+        fs.writeFileSync(path.join(legacySkillDir, "SKILL.md"), "legacy", "utf8");
+
+        const result = runCli(["global", "sync", "--target", "codex", "--quiet"], {
+            env: { LING_GLOBAL_ROOT: tempDir },
+        });
+        assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+
+        const migratedSkill = path.join(tempDir, ".agents", "skills", "legacy-skill", "SKILL.md");
+        assert.ok(fs.existsSync(migratedSkill), "legacy skill should be migrated into .agents/skills");
+        assert.strictEqual(fs.readFileSync(migratedSkill, "utf8"), "legacy");
+
+        assert.ok(!fs.existsSync(path.join(tempDir, ".codex", "skills")), "legacy .codex/skills should be removed");
+    });
+
+    test("global sync should backup and remove conflicting legacy ~/.codex/skills entries", () => {
+        const destSkillDir = path.join(tempDir, ".agents", "skills", "conflict-skill");
+        fs.mkdirSync(destSkillDir, { recursive: true });
+        fs.writeFileSync(path.join(destSkillDir, "SKILL.md"), "agents", "utf8");
+
+        const legacySkillDir = path.join(tempDir, ".codex", "skills", "conflict-skill");
+        fs.mkdirSync(legacySkillDir, { recursive: true });
+        fs.writeFileSync(path.join(legacySkillDir, "SKILL.md"), "legacy", "utf8");
+
+        const result = runCli(["global", "sync", "--target", "codex", "--quiet"], {
+            env: { LING_GLOBAL_ROOT: tempDir },
+        });
+        assert.strictEqual(result.status, 0, result.stderr || result.stdout);
+
+        const destSkillMd = path.join(destSkillDir, "SKILL.md");
+        assert.strictEqual(fs.readFileSync(destSkillMd, "utf8"), "agents");
+
+        assert.ok(!fs.existsSync(path.join(tempDir, ".codex", "skills")), "legacy .codex/skills should be removed");
+
+        const backupRoot = path.join(tempDir, ".ling", "backups", "global");
+        assert.ok(fs.existsSync(backupRoot), "missing backup root");
+
+        const timestamps = fs
+            .readdirSync(backupRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+        assert.ok(timestamps.length > 0, "backup timestamp directory missing");
+
+        const backupSkillMd = path.join(backupRoot, timestamps[0], "codex-legacy", "conflict-skill", "SKILL.md");
+        assert.ok(fs.existsSync(backupSkillMd), "backup for legacy conflict skill missing");
+        assert.strictEqual(fs.readFileSync(backupSkillMd, "utf8"), "legacy");
+    });
+
     test("global sync should default to syncing codex, gemini, and antigravity when no target is provided", () => {
         const result = runCli(["global", "sync", "--quiet"], {
             env: { LING_GLOBAL_ROOT: tempDir },
         });
         assert.strictEqual(result.status, 0, result.stderr || result.stdout);
 
-        const codexRoot = path.join(tempDir, ".codex", "skills");
+        const codexRoot = path.join(tempDir, ".agents", "skills");
         assert.ok(fs.existsSync(path.join(codexRoot, "clean-code", "SKILL.md")), "missing expected codex skill: clean-code");
         assert.ok(fs.existsSync(path.join(codexRoot, "workflow-plan", "SKILL.md")), "missing expected codex workflow skill: workflow-plan");
 
         const geminiCliRoot = path.join(tempDir, ".gemini", "skills");
-        assert.ok(fs.existsSync(path.join(geminiCliRoot, "clean-code", "SKILL.md")), "missing expected gemini-cli skill: clean-code");
+        assert.ok(!fs.existsSync(geminiCliRoot), "default sync should prune redundant gemini-cli skills when universal root exists");
 
         const antigravityRoot = path.join(tempDir, ".gemini", "antigravity", "skills");
         assert.ok(fs.existsSync(path.join(antigravityRoot, "clean-code", "SKILL.md")), "missing expected antigravity skill: clean-code");
@@ -107,6 +169,31 @@ describe("Global Sync", () => {
         assert.ok(!fs.existsSync(antigravityRoot), "gemini sync should not create antigravity skills root");
     });
 
+    test("global sync gemini should prune redundant ~/.gemini/skills when universal root already exists", () => {
+        const codexResult = runCli(["global", "sync", "--target", "codex", "--quiet"], {
+            env: { LING_GLOBAL_ROOT: tempDir },
+        });
+        assert.strictEqual(codexResult.status, 0, codexResult.stderr || codexResult.stdout);
+
+        const geminiResult = runCli(["global", "sync", "--target", "gemini", "--quiet"], {
+            env: { LING_GLOBAL_ROOT: tempDir },
+        });
+        assert.strictEqual(geminiResult.status, 0, geminiResult.stderr || geminiResult.stdout);
+
+        const geminiCliRoot = path.join(tempDir, ".gemini", "skills");
+        assert.ok(!fs.existsSync(geminiCliRoot), "redundant gemini-cli skills root should be pruned");
+
+        const backupRoot = path.join(tempDir, ".ling", "backups", "global");
+        const timestamps = fs
+            .readdirSync(backupRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+        assert.ok(timestamps.length > 0, "backup timestamp directory missing");
+
+        const redundantBackup = path.join(backupRoot, timestamps[timestamps.length - 1], "gemini-cli-redundant", "clean-code", "SKILL.md");
+        assert.ok(fs.existsSync(redundantBackup), "backup for redundant gemini-cli skill missing");
+    });
+
     test("global sync should install antigravity skills only into ~/.gemini/antigravity/skills", () => {
         const result = runCli(["global", "sync", "--target", "antigravity", "--quiet"], {
             env: { LING_GLOBAL_ROOT: tempDir },
@@ -122,7 +209,7 @@ describe("Global Sync", () => {
     });
 
     test("global sync should create backup when overwriting an existing skill", () => {
-        const skillsRoot = path.join(tempDir, ".codex", "skills", "clean-code");
+        const skillsRoot = path.join(tempDir, ".agents", "skills", "clean-code");
         fs.mkdirSync(skillsRoot, { recursive: true });
         fs.writeFileSync(path.join(skillsRoot, "SKILL.md"), "modified", "utf8");
 

package/tests/spec-profile.test.js

@@ -47,7 +47,7 @@ describe("Spec Profile", () => {
         const enableResult = runCli(["spec", "enable", "--target", "codex", "--quiet"], { env });
         assert.strictEqual(enableResult.status, 0, enableResult.stderr || enableResult.stdout);
 
-        const codexSkill = path.join(tempRoot, ".codex", "skills", "harness-engineering", "SKILL.md");
+        const codexSkill = path.join(tempRoot, ".agents", "skills", "harness-engineering", "SKILL.md");
         const stateFile = path.join(tempRoot, ".ling", "spec", "state.json");
         const templatesDir = path.join(tempRoot, ".ling", "spec", "templates");
         const referencesDir = path.join(tempRoot, ".ling", "spec", "references");
@@ -66,7 +66,7 @@ describe("Spec Profile", () => {
 
         const disableResult = runCli(["spec", "disable", "--target", "codex", "--quiet"], { env });
         assert.strictEqual(disableResult.status, 0, disableResult.stderr || disableResult.stdout);
-        assert.ok(!fs.existsSync(path.join(tempRoot, ".codex", "skills", "harness-engineering")), "spec skill should be removed");
+        assert.ok(!fs.existsSync(path.join(tempRoot, ".agents", "skills", "harness-engineering")), "spec skill should be removed");
         assert.ok(!fs.existsSync(stateFile), "spec state should be removed after final disable");
         assert.ok(!fs.existsSync(templatesDir), "spec templates should be removed after final disable");
         assert.ok(!fs.existsSync(referencesDir), "spec references should be removed after final disable");
@@ -75,7 +75,7 @@ describe("Spec Profile", () => {
 
     test("spec disable should restore pre-existing skill backup", () => {
         const env = { LING_GLOBAL_ROOT: tempRoot };
-        const skillDir = path.join(tempRoot, ".codex", "skills", "harness-engineering");
+        const skillDir = path.join(tempRoot, ".agents", "skills", "harness-engineering");
         fs.mkdirSync(skillDir, { recursive: true });
         fs.writeFileSync(path.join(skillDir, "SKILL.md"), "legacy skill", "utf8");
 
@@ -95,7 +95,7 @@ describe("Spec Profile", () => {
         assert.strictEqual(enableResult.status, 0, enableResult.stderr || enableResult.stdout);
 
         const templatesDir = path.join(tempRoot, ".ling", "spec", "templates");
-        const codexSkillDir = path.join(tempRoot, ".codex", "skills", "harness-engineering");
+        const codexSkillDir = path.join(tempRoot, ".agents", "skills", "harness-engineering");
         fs.rmSync(templatesDir, { recursive: true, force: true });
         fs.rmSync(codexSkillDir, { recursive: true, force: true });
 
@@ -130,6 +130,53 @@ describe("Spec Profile", () => {
         assert.strictEqual((statusResult.stdout || "").trim(), "installed");
     });
 
+    test("spec enable should install gemini skills independently", () => {
+        const env = { LING_GLOBAL_ROOT: tempRoot };
+
+        const enableResult = runCli(["spec", "enable", "--target", "gemini", "--quiet"], { env });
+        assert.strictEqual(enableResult.status, 0, enableResult.stderr || enableResult.stdout);
+
+        const geminiSkill = path.join(tempRoot, ".gemini", "skills", "harness-engineering", "SKILL.md");
+        const antigravitySkill = path.join(tempRoot, ".gemini", "antigravity", "skills", "harness-engineering", "SKILL.md");
+        assert.ok(fs.existsSync(geminiSkill), "missing installed gemini spec skill");
+        assert.ok(!fs.existsSync(antigravitySkill), "gemini spec enable should not install antigravity skill");
+    });
+
+    test("spec enable should migrate legacy codex global skill path to ~/.agents/skills", () => {
+        const env = { LING_GLOBAL_ROOT: tempRoot };
+        const stateDir = path.join(tempRoot, ".ling", "spec");
+        fs.mkdirSync(stateDir, { recursive: true });
+        fs.writeFileSync(path.join(stateDir, "state.json"), JSON.stringify({
+            version: 1,
+            updatedAt: new Date().toISOString(),
+            targets: {
+                codex: {
+                    enabledAt: new Date().toISOString(),
+                    consumers: {
+                        codex: {
+                            skills: [
+                                {
+                                    name: "harness-engineering",
+                                    destPath: path.join(tempRoot, ".codex", "skills", "harness-engineering"),
+                                    backupPath: "",
+                                    mode: "created",
+                                },
+                            ],
+                        },
+                    },
+                },
+            },
+            assets: {},
+        }, null, 2), "utf8");
+
+        const enableResult = runCli(["spec", "enable", "--target", "codex", "--quiet"], { env });
+        assert.strictEqual(enableResult.status, 0, enableResult.stderr || enableResult.stdout);
+
+        const state = JSON.parse(fs.readFileSync(path.join(stateDir, "state.json"), "utf8"));
+        const skillState = state.targets.codex.consumers.codex.skills.find((skill) => skill.name === "harness-engineering");
+        assert.ok(skillState.destPath.includes(`${path.sep}.agents${path.sep}skills${path.sep}harness-engineering`), "legacy codex path should be migrated to .agents/skills");
+    });
+
     test("spec status should report broken when an asset file is missing", () => {
         const env = { LING_GLOBAL_ROOT: tempRoot };
 

package/tests/standards-compliance.test.js

@@ -137,11 +137,11 @@ describe('Standards Compliance', () => {
         const file = path.resolve('docs/TECH.md');
         const content = fs.readFileSync(file, 'utf8');
 
-        assert.ok(content.includes('$HOME/.codex/skills/'), 'missing global skill path: $HOME/.codex/skills/');
+        assert.ok(content.includes('$HOME/.agents/skills/'), 'missing global skill path: $HOME/.agents/skills/');
         assert.ok(content.includes('$HOME/.gemini/skills/'), 'missing global skill path: $HOME/.gemini/skills/');
         assert.ok(content.includes('$HOME/.gemini/antigravity/skills/'), 'missing global skill path: $HOME/.gemini/antigravity/skills/');
         assert.ok(content.includes('.agents/skills'), 'missing repo skill path: .agents/skills');
-        assert.ok(!content.includes('$HOME/.agents/skills/'), 'should not contain deprecated global path: $HOME/.agents/skills/');
+        assert.ok(!content.includes('$HOME/.codex/skills/'), 'should not contain deprecated global path: $HOME/.codex/skills/');
     });
 
     test('README spec section should reflect implemented spec commands', () => {