@mison/ling 1.2.2 → 1.2.3

package/CHANGELOG.md

@@ -7,6 +7,12 @@
 
 ## [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
 
 ### 修复

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` | 写入 `~/.agents/skills/`、`~/.gemini/skills/` 等 |
+| 给电脑全局同步可复用 Skills | `ling global sync` | 写入 `~/.agents/skills/`、`~/.gemini/antigravity/skills/` 等，并自动清理 Gemini CLI 的重复副本 |
 | 给项目启用 Spec 工作流 | `ling spec init` | 项目内生成 `issues.csv` 等 Spec 资产 |
 
 一句话区分：
@@ -90,7 +90,7 @@ ling global status
 ```
 
 - `codex` -> `~/.agents/skills/`
-- `gemini` -> `~/.gemini/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/...`）。

package/bin/ling-cli.js

@@ -62,6 +62,7 @@ const SPEC_TEMPLATE_REQUIRED_FILES = ["issues.template.csv", "driver-prompt.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();
@@ -1356,6 +1357,52 @@ function migrateLegacyCodexGlobalSkills(timestamp, options) {
     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) {
@@ -1625,6 +1672,10 @@ async function commandGlobalSync(options) {
 
                 if (target === "codex") {
                     migrateLegacyCodexGlobalSkills(timestamp, options);
+                    reconcileGeminiGlobalSkillsAgainstUniversalRoot(timestamp, options);
+                }
+                if (target === "gemini") {
+                    reconcileGeminiGlobalSkillsAgainstUniversalRoot(timestamp, options);
                 }
             } finally {
                 if (plan.cleanup) plan.cleanup();

package/docs/PLAN.md

@@ -21,7 +21,7 @@
 - 默认行为：`ling global sync` 未指定 `--target/--targets` 时，同步 `codex + gemini + antigravity`
 - 目标路径：
   - `codex` -> `$HOME/.agents/skills/`
-  - `gemini` -> `$HOME/.gemini/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/...`）。

package/docs/TECH.md

@@ -28,7 +28,7 @@ cd web && npm install && npm run lint
 
 ### 全局级（仅同步 Skills）
 - `codex`：`$HOME/.agents/skills/`
-- `gemini-cli`：`$HOME/.gemini/skills/`
+- `gemini-cli`：`$HOME/.gemini/skills/`（若存在与 `$HOME/.agents/skills/` 重叠的同名 Skill，灵轨会在同步后清理重复副本）
 - `antigravity`：`$HOME/.gemini/antigravity/skills/`
 
 > 说明：仓库内 Skills 源路径为 `.agents/skills/`，全局同步会将其投影到真实工具读取的全局目录；仓库 Canonical 仍是 `.agents/`。
@@ -65,6 +65,7 @@ cd web && npm install && npm run lint
 - 覆盖前备份：覆盖同名 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，避免污染真实用户目录）

package/package.json

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

package/scripts/ci-verify.js

@@ -97,12 +97,13 @@ function main() {
     }
 
     const codexSkill = path.join(globalRoot, ".agents", "skills", "workflow-plan", "SKILL.md");
-    const geminiCliSkill = path.join(globalRoot, ".gemini", "skills", "clean-code", "SKILL.md");
     const antigravitySkill = path.join(globalRoot, ".gemini", "antigravity", "skills", "clean-code", "SKILL.md");
     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

@@ -114,7 +114,6 @@ function main() {
 
         const globalChecks = [
             path.join(globalRoot, ".agents", "skills", "workflow-plan", "SKILL.md"),
-            path.join(globalRoot, ".gemini", "skills", "clean-code", "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

@@ -136,7 +136,7 @@ describe("Global Sync", () => {
         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");
@@ -169,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 },