@mison/ling 1.2.2 → 1.2.4

package/CHANGELOG.md

@@ -7,6 +7,22 @@
 
 ## [Unreleased]
 
+## [ling-1.2.4] - 2026-03-15
+
+### 修复
+
+- 修复 `ling spec enable` 在全局 `codex` Skills 已存在时重新写回 Gemini CLI 重复 Skill 的问题，并避免将仅同名但内容不同的 Gemini 专用 Skill 误判为重复副本。
+
+### 维护
+
+- 完善仓库根 `.gitignore`，补充测试临时目录、日志缓存和 Web 构建产物忽略规则。
+
+## [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/skills/`、`~/.gemini/antigravity/skills/`；若与 universal 根目录重复，会自动清理 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/...`）。
@@ -128,6 +128,8 @@ ling spec init --csv-only
 - `--csv-only`：`<project>/issues.csv`、`<project>/docs/reviews/`、`<project>/docs/handoff/`
 - 全局 Spec 资源：`~/.ling/spec/templates/`、`~/.ling/spec/references/`、`~/.ling/spec/profiles/`
 
+如果这台电脑已经有 `~/.agents/skills/`，`ling spec enable` 在启用 `gemini` 目标时也会自动清理 `~/.gemini/skills/` 里的同名重复副本；若同名 Skill 内容不同，则会保留 Gemini 专用版本，不会误删。
+
 如果你只想要一个本机演练空间，而不是某个真实项目：
 
 ```bash

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,59 @@ 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, skippedConflicts: 0 };
+    }
+
+    let removed = 0;
+    let backedUp = 0;
+    let skippedConflicts = 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 (!areDirectoriesEqual(geminiSkillDir, universalSkillDir)) {
+            log(options, `[warn] Gemini CLI Skill 与 universal 根目录同名但内容不同，已保留: ${geminiSkillDir}`);
+            skippedConflicts += 1;
+            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, skippedConflicts };
+}
+
 function syncSkillDirectory(destination, srcDir, destDir, timestamp, options) {
     const exists = fs.existsSync(destDir);
     if (exists) {
@@ -1625,6 +1679,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();
@@ -2701,6 +2759,9 @@ async function commandSpecEnable(options) {
     if (targets.includes("codex")) {
         migrateLegacyCodexGlobalSkills(timestamp, options);
     }
+    if (targets.includes("codex") || targets.includes("gemini")) {
+        reconcileGeminiGlobalSkillsAgainstUniversalRoot(timestamp, options);
+    }
 
     log(options, `[ok] Spec Profile 已启用 (Targets: ${targets.join(", ")})`);
 }

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/...`）。
@@ -41,6 +41,7 @@
     - References：`$HOME/.ling/spec/references/`
     - Profiles：`$HOME/.ling/spec/profiles/`
   - 回退原则：启用前先备份同名资源；停用时优先恢复原资源
+  - 与全局 Skills 的关系：若机器上已存在 `$HOME/.agents/skills/`，启用包含 `gemini` 的 Spec 目标时会自动清理 `$HOME/.gemini/skills/` 中与 universal 根目录完全相同的重复副本；同名但内容不同的 Gemini 专用 Skill 会保留
 - 项目层（工作区级）命令：`ling spec init` / `ling spec doctor`
   - 默认作用于当前目录；`--spec-workspace` 才会使用 `$HOME/.ling/spec-workspace`
   - 完整模式：写入 `.ling/spec/`、`issues.csv`、`docs/reviews/`、`docs/handoff/`

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>/...`；若只是同名但内容不同，则记录警告并保留 Gemini 专用版本
 
 ### 测试隔离
 - `LING_GLOBAL_ROOT`：替代 `$HOME`（用于测试与 CI，避免污染真实用户目录）
@@ -88,6 +89,7 @@ cd web && npm install && npm run lint
     - 会校验 `issues.csv` 表头与状态枚举
     - 当项目缺少 `.ling/spec/` 但已启用全局 Spec 时，会使用全局 Spec 资产作为后备
 - Spec 源目录：`.spec/`
+- 若 `spec enable` 包含 `gemini` 或 `codex`，启用后还会执行一次 Gemini CLI 重复 Skill 清理，避免全局 universal Skill 与 Gemini CLI 同时暴露同名副本
 
 ### 心智模型
 - `ling spec enable`：给这台电脑安装 Spec 工具箱
@@ -171,8 +173,8 @@ Windows PowerShell 示例：
 ```powershell
 $ts = "2026-03-12T12-00-00-000Z"
 $skill = "clean-code"
-Remove-Item "$HOME\\.codex\\skills\\$skill" -Recurse -Force -ErrorAction SilentlyContinue
-Copy-Item "$HOME\\.ling\\backups\\global\\$ts\\codex\\$skill" "$HOME\\.codex\\skills\\$skill" -Recurse -Force
+Remove-Item "$HOME\\.agents\\skills\\$skill" -Recurse -Force -ErrorAction SilentlyContinue
+Copy-Item "$HOME\\.ling\\backups\\global\\$ts\\codex\\$skill" "$HOME\\.agents\\skills\\$skill" -Recurse -Force
 ```
 
 Gemini CLI 回滚示例：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mison/ling",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "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 },

package/tests/spec-profile.test.js

@@ -142,6 +142,47 @@ describe("Spec Profile", () => {
         assert.ok(!fs.existsSync(antigravitySkill), "gemini spec enable should not install antigravity skill");
     });
 
+    test("spec enable should prune redundant gemini skills when codex universal skills already exist", () => {
+        const env = { LING_GLOBAL_ROOT: tempRoot };
+
+        const globalResult = runCli(["global", "sync", "--target", "codex", "--quiet"], { env });
+        assert.strictEqual(globalResult.status, 0, globalResult.stderr || globalResult.stdout);
+
+        const enableResult = runCli(["spec", "enable", "--quiet"], { env });
+        assert.strictEqual(enableResult.status, 0, enableResult.stderr || enableResult.stdout);
+
+        const geminiSkillRoot = path.join(tempRoot, ".gemini", "skills");
+        const antigravitySkill = path.join(tempRoot, ".gemini", "antigravity", "skills", "harness-engineering", "SKILL.md");
+        const codexSkill = path.join(tempRoot, ".agents", "skills", "harness-engineering", "SKILL.md");
+        assert.ok(!fs.existsSync(geminiSkillRoot), "redundant gemini spec skills should be pruned after enable");
+        assert.ok(fs.existsSync(antigravitySkill), "antigravity spec skill should still be installed");
+        assert.ok(fs.existsSync(codexSkill), "codex spec skill should still be installed");
+
+        const backupRoot = path.join(tempRoot, ".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", "harness-engineering", "SKILL.md");
+        assert.ok(fs.existsSync(redundantBackup), "backup for redundant gemini spec skill missing");
+    });
+
+    test("spec enable should keep gemini-only skill when content differs from codex universal root", () => {
+        const env = { LING_GLOBAL_ROOT: tempRoot };
+        const codexSkillDir = path.join(tempRoot, ".agents", "skills", "harness-engineering");
+        fs.mkdirSync(codexSkillDir, { recursive: true });
+        fs.writeFileSync(path.join(codexSkillDir, "SKILL.md"), "codex-only variant", "utf8");
+
+        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");
+        assert.ok(fs.existsSync(geminiSkill), "gemini-only skill should be kept when content differs");
+        assert.strictEqual(fs.readFileSync(geminiSkill, "utf8"), fs.readFileSync(path.join(REPO_ROOT, ".spec", "skills", "harness-engineering", "SKILL.md"), "utf8"));
+    });
+
     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");