@mison/ag-kit-cn 2.0.1 → 3.0.0

package/bin/core/resource-loader.js

@@ -4,8 +4,8 @@ const path = require("path");
 class ResourceLoader {
     constructor(rootDir) {
         this.rootDir = rootDir;
-        this.skillsDir = path.join(rootDir, ".agent", "skills");
-        this.workflowsDir = path.join(rootDir, ".agent", "workflows");
+        this.skillsDir = path.join(rootDir, ".agents", "skills");
+        this.workflowsDir = path.join(rootDir, ".agents", "workflows");
     }
 
     /**

package/bin/utils/manifest.js

@@ -13,6 +13,7 @@ class ManifestManager {
             updatedAt: "",
             files: {},
         };
+        this.lastLoadError = null;
     }
 
     /**
@@ -77,11 +78,13 @@ class ManifestManager {
      * Load manifest from disk
      */
     load() {
+        this.lastLoadError = null;
         if (fs.existsSync(this.manifestPath)) {
             try {
                 const raw = fs.readFileSync(this.manifestPath, "utf8");
                 this.manifest = ManifestManager.normalizeManifestShape(JSON.parse(raw));
             } catch (err) {
+                this.lastLoadError = err;
                 this.manifest = {
                     version: 2,
                     target: typeof this.options.target === "string" ? this.options.target : "",

package/bin/utils.js

@@ -63,14 +63,21 @@ function cloneBranchAgentDir(branch, options) {
         throw new Error(`无法拉取分支 ${safeBranch}，请确认分支存在且网络可用`);
     }
 
+    const clonedAgentsDir = path.join(tempDir, ".agents");
     const clonedAgentDir = path.join(tempDir, ".agent");
-    if (!fs.existsSync(clonedAgentDir)) {
+    let templateDir = "";
+
+    if (fs.existsSync(clonedAgentsDir)) {
+        templateDir = clonedAgentsDir;
+    } else if (fs.existsSync(clonedAgentDir)) {
+        templateDir = clonedAgentDir;
+    } else {
         fs.rmSync(tempDir, { recursive: true, force: true });
-        throw new Error(`分支 ${safeBranch} 中未找到 .agent 目录`);
+        throw new Error(`分支 ${safeBranch} 中未找到 .agents 或 .agent 目录`);
     }
 
     return {
-        agentDir: clonedAgentDir,
+        agentDir: templateDir,
         cleanup: () => fs.rmSync(tempDir, { recursive: true, force: true }),
     };
 }

package/docs/PLAN.md

@@ -0,0 +1,39 @@
+# Ag-Kit 规划（PLAN）
+
+## 一句话
+Ag-Kit 只做一件事：把仓库内统一的 `.agents/` 模板，优雅地投影到不同平台（Gemini/Antigravity 与 Codex），并提供安全、可回滚的更新机制。
+
+## 设计原则
+- 命令面少而强：用 `sync` 统一“首次安装 + 更新”，避免双心智。
+- 默认安全：不做全局清理、不自动写入高风险全局规则。
+- 模板源单一：仓库 Canonical 为 `.agents/`；旧 `.agent/` 只作为输入兼容，不作为主路径。
+
+## 能力边界（项目 vs 全局）
+### 项目安装（功能最完整）
+- 命令：`ag-kit init` / `ag-kit update` / `ag-kit status` / `ag-kit doctor`
+- 目标输出：
+  - `gemini` -> 项目内 `.agent/`（兼容 Gemini/Antigravity 工作区规范）
+  - `codex` -> 项目内 `.agents/`（受管目录）+ 注入工作区 `AGENTS.md` / `antigravity.rules` 托管区块
+
+### 全局安装（跨项目复用 Skills）
+- 命令：`ag-kit global sync` / `ag-kit global status`
+- 默认行为：`ag-kit global sync` 未指定 `--target/--targets` 时，同步 `codex + gemini`
+- 目标路径：
+  - `codex` -> `$HOME/.codex/skills/`
+  - `gemini` -> 同时写入 `$HOME/.gemini/skills/` 与 `$HOME/.gemini/antigravity/skills/`
+- 安全边界：全局只同步 Skills，不写入全局 Rules/Agents/Workflows。
+
+## 覆盖与回滚（全局同步）
+- 覆盖单位：每个 Skill 目录。
+- 覆盖策略：只覆盖同名 Skill；不清理用户已有的其他 Skill。
+- 覆盖前备份：每次覆盖同名 Skill 前备份到 `$HOME/.ag-kit/backups/global/<timestamp>/...`。
+
+## 兼容策略
+- Gemini/Antigravity：输出 `.agent/`，保持与官方工作区机制一致。
+- Codex：受管目录为 `.agents/`，并使用 `manifest.json` 做完整性与漂移检测；识别并迁移遗留 `.codex/`。
+- 全局同步遵循真实消费端目录，而不是仓库模板源目录；仓库内仍以 `.agents/` 作为唯一 Canonical。
+
+## 成功标准
+- `ag-kit global sync` 一条命令即可完成全局 Skills 安装/更新（默认 codex + gemini，其中 gemini 同步到 gemini-cli 与 antigravity）。
+- 覆盖可回滚：每次覆盖同名 Skill 都有可用备份。
+- 跨平台 CI（Linux/macOS/Windows）验证主链路通过。

package/docs/TECH.md

@@ -0,0 +1,136 @@
+# Ag-Kit 技术说明（TECH）
+
+## 快速验证（维护者）
+```bash
+bun install
+bun run test
+bun run ci:verify
+bun run health-check
+cd web && bun install && bun run lint
+```
+
+## 核心目录与职责
+- `.agents/`：仓库模板源（Canonical）
+- `bin/ag-kit.js`：CLI 入口与命令分发
+- `bin/adapters/`：目标差异（`gemini` / `codex`）
+- `bin/core/`：构建/转换（将 Workflows 投影为 Codex Skills 等）
+- `bin/utils/`：原子写入、manifest、托管区块等通用能力
+
+## 路径映射（最重要）
+### 项目级（功能最完整）
+- `gemini`：项目根目录 `.agent/`
+- `codex`：项目根目录 `.agents/`（受管）+ `.agents-backup/`（漂移覆盖备份）
+
+### 全局级（仅同步 Skills）
+- `codex`：`$HOME/.codex/skills/`
+- `gemini-cli`：`$HOME/.gemini/skills/`
+- `antigravity`：`$HOME/.gemini/antigravity/skills/`
+
+> 说明：仓库内 Skills 源路径为 `.agents/skills/`，全局同步会将其投影到真实工具读取的全局目录；仓库 Canonical 仍是 `.agents/`。
+
+## 端到端链路（简述）
+### 项目安装 / 更新
+- `init`：选择目标 -> 适配器 `install()` -> 落盘目标目录（Gemini: `.agent/`；Codex: `.agents/`）->（Codex）注入托管区块到工作区 `AGENTS.md` 与 `antigravity.rules`
+- `update`：自动检测已安装目标（或通过 `--target/--targets` 指定）-> 适配器 `update()` ->（Codex）漂移检测与备份 -> 原子替换
+- `doctor`：检查完整性；`--fix` 尝试修复（Codex 支持迁移 `.codex/` 与重写托管区块）
+
+### Codex 构建（Workflow -> Skill）
+- 输入：`.agents/skills/` 与 `.agents/workflows/`
+- 规则：每个 Workflow `<name>.md` 会转换为一个 Skill：`workflow-<name>/SKILL.md`
+- 输出（受管目录 `.agents/` 内）：`skills/`、`codex.json`、`AGENTS.md`、`antigravity.rules`、`manifest.json`
+
+## 全局同步：`ag-kit global sync/status`
+### 默认目标
+- 未指定 `--target/--targets`：默认同步 `codex + gemini`
+- `--target gemini` / `--targets codex,gemini` 中的 `gemini` 会同时写入 gemini-cli 与 antigravity 两个消费端目录
+
+### 来源与覆盖策略
+- 来源：默认使用本包内置 `.agents/`；也可用 `--branch <name>` 从远端分支拉取模板源
+- 覆盖单位：每个 Skill 目录
+- 覆盖策略：只覆盖同名 Skill，不清理其他 Skill
+- 原子替换：按 Skill 目录原子替换，避免半写状态
+- 覆盖前备份：覆盖同名 Skill 前备份到 `$HOME/.ag-kit/backups/global/<timestamp>/<consumer>/<skill>/...`
+  - `consumer` 可能是 `codex`、`gemini-cli`、`antigravity`
+
+### 测试隔离
+- `AG_KIT_GLOBAL_ROOT`：替代 `$HOME`（用于测试与 CI，避免污染真实用户目录）
+
+## 状态契约（自动化）
+- `ag-kit status --quiet` / `ag-kit global status --quiet` 只输出三态：
+  - `installed`：检测到目标且完整性正常
+  - `broken`：检测到目标但存在残缺、漂移或结构异常
+  - `missing`：未检测到任何已安装目标
+- 退出码固定为：
+  - `0` = `installed`
+  - `1` = `broken`
+  - `2` = `missing`
+- 若需要问题明细，使用 `ag-kit doctor`；`status` 负责健康状态，`doctor` 负责诊断细节。
+
+## 手动回滚（全局 Skills）
+1. 找到备份目录：`$HOME/.ag-kit/backups/global/<timestamp>/...`
+2. 按 Skill 回滚（推荐一次只处理一个 Skill 目录）：
+   - Codex 目标：恢复到 `$HOME/.codex/skills/<skill>/`
+   - Gemini CLI：恢复到 `$HOME/.gemini/skills/<skill>/`
+   - Antigravity：恢复到 `$HOME/.gemini/antigravity/skills/<skill>/`
+
+macOS / Linux 示例（把某个 Skill 回滚为备份版本）：
+```bash
+ts="2026-03-12T12-00-00-000Z"
+skill="clean-code"
+rm -rf "$HOME/.codex/skills/$skill"
+cp -a "$HOME/.ag-kit/backups/global/$ts/codex/$skill" "$HOME/.codex/skills/$skill"
+```
+
+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\\.ag-kit\\backups\\global\\$ts\\codex\\$skill" "$HOME\\.codex\\skills\\$skill" -Recurse -Force
+```
+
+Gemini CLI 回滚示例：
+```bash
+ts="2026-03-12T12-00-00-000Z"
+skill="clean-code"
+rm -rf "$HOME/.gemini/skills/$skill"
+cp -a "$HOME/.ag-kit/backups/global/$ts/gemini-cli/$skill" "$HOME/.gemini/skills/$skill"
+```
+
+Antigravity 回滚示例：
+```bash
+ts="2026-03-12T12-00-00-000Z"
+skill="clean-code"
+rm -rf "$HOME/.gemini/antigravity/skills/$skill"
+cp -a "$HOME/.ag-kit/backups/global/$ts/antigravity/$skill" "$HOME/.gemini/antigravity/skills/$skill"
+```
+
+## 环境变量
+- `AG_KIT_INDEX_PATH`：工作区索引文件路径（默认 `~/.ag-kit/workspaces.json`）
+- `AG_KIT_GLOBAL_ROOT`：全局目录根（替代 `$HOME`）
+- `AG_KIT_SKIP_UPSTREAM_CHECK`：跳过上游同名包安装提示（测试用）
+
+## 安装提示机制
+- npm 全局安装：`postinstall` 会尽力检测并提示上游英文版 `@vudovn/ag-kit` 冲突。
+- Bun 全局安装：Bun 默认会阻止本包 `postinstall`；因此冲突提示以内置 CLI 运行期检查为准，会在 `init` / `update` / `update-all` / `global sync` 时提示。
+- 冲突提示只负责提醒，不会自动修改当前安装状态；如需清理可执行 `npm uninstall -g @vudovn/ag-kit`。
+
+## 常见故障
+- 更新中断：原子替换保证不会出现半写状态；重新运行 `update`/`global sync` 即可。
+- Windows `EPERM/EBUSY`：通常是目录被占用；关闭占用 `.agents/` 或目标 Skill 目录的进程后重试。
+- 漂移覆盖：Codex 若检测到用户修改受管文件，会在覆盖前写入 `.agents-backup/<timestamp>/`。
+
+## Codex 官方 `.rules`（手动配置）
+Ag-Kit 不会自动写入全局 `~/.codex/rules/default.rules`，避免引入不可预期的全局副作用。若你需要启用 Codex 官方命令审批策略（如 `prefix_rule()`），可按需手动创建：
+
+```python
+# default.rules
+load("builtin://rules/rules.star", "prefix_rule")
+
+rules = [
+    prefix_rule(["ls"], action="allow"),
+    prefix_rule(["cat"], action="allow"),
+    prefix_rule(["rg"], action="allow"),
+    prefix_rule(["git", "status"], action="allow"),
+]
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mison/ag-kit-cn",
-  "version": "2.0.1",
+  "version": "3.0.0",
   "description": "AI Agent templates - Skills, Agents, and Workflows for enhanced coding assistance",
   "repository": {
     "type": "git",
@@ -23,27 +23,29 @@
   "scripts": {
     "clean": "node scripts/clean.js",
     "clean:dry-run": "node scripts/clean.js --dry-run",
-    "health-check": "bash scripts/health-check.sh",
+    "health-check": "node scripts/health-check.js",
     "postinstall": "node scripts/postinstall-check.js",
-    "test": "node --test tests"
+    "test": "node --test \"tests/**/*.test.js\"",
+    "ci:verify": "node scripts/ci-verify.js"
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
-    ".agent/**",
+    ".agents/**",
     "bin/**",
+    "scripts/clean.js",
+    "scripts/ci-verify.js",
+    "scripts/health-check.js",
+    "scripts/health-check.sh",
     "scripts/postinstall-check.js",
+    "tests/**/*.test.js",
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
     "AGENT_FLOW.md",
-    "docs/codex-rules-template.md",
-    "docs/mapping-spec.md",
-    "docs/multi-target-adapter.md",
-    "docs/operations.md",
-    "docs/terminology-style-guide.md",
-    "docs/official/**"
+    "docs/PLAN.md",
+    "docs/TECH.md"
   ],
   "bin": {
     "ag-kit": "./bin/ag-kit.js"

package/scripts/ci-verify.js

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("node:child_process");
+
+const REPO_ROOT = path.resolve(__dirname, "..");
+const CLI_PATH = path.join(REPO_ROOT, "bin", "ag-kit.js");
+
+function runCli(args, options = {}) {
+    const env = {
+        ...process.env,
+        AG_KIT_SKIP_UPSTREAM_CHECK: "1",
+        ...options.env,
+    };
+
+    const result = spawnSync(process.execPath, [CLI_PATH, ...args], {
+        cwd: REPO_ROOT,
+        env,
+        encoding: "utf8",
+    });
+
+    if (result.status !== 0) {
+        const message = result.stderr || result.stdout || "";
+        throw new Error(`命令失败: ag-kit ${args.join(" ")}\n${message}`);
+    }
+
+    return result.stdout || "";
+}
+
+function ensureExists(targetPath, label) {
+    if (!fs.existsSync(targetPath)) {
+        throw new Error(`缺少 ${label}: ${targetPath}`);
+    }
+}
+
+function main() {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-ci-"));
+    const workspaceDir = path.join(tempRoot, "workspace");
+    const indexPath = path.join(tempRoot, "workspaces.json");
+    const globalRoot = path.join(tempRoot, "global-root");
+
+    fs.mkdirSync(workspaceDir, { recursive: true });
+
+    const env = {
+        AG_KIT_INDEX_PATH: indexPath,
+        AG_KIT_GLOBAL_ROOT: globalRoot,
+    };
+
+    runCli(["init", "--targets", "gemini,codex", "--path", workspaceDir, "--quiet"], { env });
+
+    const status = runCli(["status", "--path", workspaceDir, "--quiet"], { env }).trim();
+    if (status !== "installed") {
+        throw new Error(`status 结果异常: ${status}`);
+    }
+
+    runCli(["doctor", "--path", workspaceDir, "--quiet"], { env });
+    runCli(["update", "--path", workspaceDir, "--quiet"], { env });
+    runCli(["update-all", "--dry-run", "--quiet"], { env });
+
+    runCli(["exclude", "add", "--path", workspaceDir, "--quiet"], { env });
+    const excluded = runCli(["exclude", "list", "--quiet"], { env });
+    if (!excluded.split(/\r?\n/).includes(workspaceDir)) {
+        throw new Error("exclude add 未生效");
+    }
+    runCli(["exclude", "remove", "--path", workspaceDir, "--quiet"], { env });
+    const excludedAfter = runCli(["exclude", "list", "--quiet"], { env });
+    if (excludedAfter.split(/\r?\n/).includes(workspaceDir)) {
+        throw new Error("exclude remove 未生效");
+    }
+
+    runCli(["global", "sync", "--quiet"], { env });
+    const globalStatus = runCli(["global", "status", "--quiet"], { env }).trim();
+    if (globalStatus !== "installed") {
+        throw new Error(`global status 结果异常: ${globalStatus}`);
+    }
+
+    const codexSkill = path.join(globalRoot, ".codex", "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");
+    ensureExists(codexSkill, "全局 Codex workflow-plan Skill");
+    ensureExists(geminiCliSkill, "全局 Gemini CLI clean-code Skill");
+    ensureExists(antigravitySkill, "全局 Antigravity clean-code Skill");
+
+    fs.rmSync(tempRoot, { recursive: true, force: true });
+}
+
+try {
+    main();
+    console.log("✅ CI 全链路演练通过");
+} catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+}

package/scripts/clean.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const DEFAULT_RELATIVE_TARGETS = [
+    ".temp_ag_kit",
+    "coverage",
+    "web/.next",
+    "web/node_modules",
+    "web/out",
+    "web/.turbo",
+];
+
+function parseArgs(argv) {
+    const options = {
+        dryRun: false,
+        quiet: false,
+    };
+
+    for (const arg of argv) {
+        if (arg === "--dry-run") {
+            options.dryRun = true;
+            continue;
+        }
+        if (arg === "--quiet") {
+            options.quiet = true;
+            continue;
+        }
+        if (arg === "--help" || arg === "-h") {
+            options.help = true;
+            continue;
+        }
+        throw new Error(`未知参数: ${arg}`);
+    }
+
+    return options;
+}
+
+function removeTarget(rootDir, relativePath, options) {
+    const absolutePath = path.join(rootDir, relativePath);
+    const exists = fs.existsSync(absolutePath);
+    const result = {
+        path: relativePath,
+        absolutePath,
+        action: "skipped",
+        reason: "",
+    };
+
+    if (!exists) {
+        result.reason = "not_found";
+        return result;
+    }
+
+    if (options.dryRun) {
+        result.action = "would_remove";
+        return result;
+    }
+
+    fs.rmSync(absolutePath, { recursive: true, force: true });
+    result.action = "removed";
+    return result;
+}
+
+function runClean(options = {}) {
+    const rootDir = path.resolve(options.rootDir || path.join(__dirname, ".."));
+    const targets = Array.isArray(options.targets) && options.targets.length > 0
+        ? options.targets
+        : DEFAULT_RELATIVE_TARGETS;
+
+    const normalizedOptions = {
+        dryRun: Boolean(options.dryRun),
+        quiet: Boolean(options.quiet),
+    };
+
+    const results = targets.map((targetPath) => removeTarget(rootDir, targetPath, normalizedOptions));
+    const removedCount = results.filter((item) => item.action === "removed").length;
+    const wouldRemoveCount = results.filter((item) => item.action === "would_remove").length;
+    const skippedCount = results.filter((item) => item.action === "skipped").length;
+
+    if (!normalizedOptions.quiet) {
+        for (const item of results) {
+            if (item.action === "removed") {
+                console.log(`🧹 已清理: ${item.path}`);
+                continue;
+            }
+            if (item.action === "would_remove") {
+                console.log(`[dry-run] 将清理: ${item.path}`);
+                continue;
+            }
+            console.log(`⏭️ 已跳过: ${item.path} (${item.reason})`);
+        }
+        console.log(`📊 清理完成: removed=${removedCount}, dryRun=${wouldRemoveCount}, skipped=${skippedCount}`);
+    }
+
+    return {
+        rootDir,
+        removedCount,
+        wouldRemoveCount,
+        skippedCount,
+        results,
+    };
+}
+
+if (require.main === module) {
+    try {
+        const options = parseArgs(process.argv.slice(2));
+        if (options.help) {
+            console.log("用法: node scripts/clean.js [--dry-run] [--quiet]");
+            process.exit(0);
+        }
+        runClean(options);
+    } catch (err) {
+        console.error(`❌ ${err.message}`);
+        process.exit(1);
+    }
+}
+
+module.exports = {
+    DEFAULT_RELATIVE_TARGETS,
+    parseArgs,
+    runClean,
+};

package/scripts/health-check.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { spawnSync } = require("node:child_process");
+
+const ROOT_DIR = path.resolve(__dirname, "..");
+
+function logStep(message) {
+    console.log(`[health-check] ${message}`);
+}
+
+function runCommand(command, options = {}) {
+    const result = spawnSync(command, {
+        cwd: options.cwd || ROOT_DIR,
+        env: {
+            ...process.env,
+            ...options.env,
+        },
+        encoding: "utf8",
+        shell: true,
+    });
+
+    if (result.status !== 0) {
+        const detail = result.stderr || result.stdout || "";
+        throw new Error(`${command}\n${detail}`.trim());
+    }
+
+    return result.stdout || "";
+}
+
+function commandExists(command) {
+    const probe = spawnSync(command, {
+        encoding: "utf8",
+        shell: true,
+        stdio: "ignore",
+    });
+    return probe.status === 0;
+}
+
+function main() {
+    logStep("检查运行环境");
+    if (!commandExists("node --version")) {
+        throw new Error("缺少命令: node");
+    }
+
+    const packageRunner = commandExists("bun --version") ? "bun" : "npm";
+    if (!commandExists(`${packageRunner} --version`)) {
+        throw new Error(`缺少命令: ${packageRunner}`);
+    }
+
+    logStep("执行测试套件");
+    if (packageRunner === "bun") {
+        runCommand("bun run test");
+    } else {
+        runCommand("npm test --silent");
+    }
+
+    logStep("验证 CLI 核心链路");
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-health-check-"));
+    try {
+        const workspaceDir = path.join(tempRoot, "workspace");
+        const indexPath = path.join(tempRoot, "workspaces.json");
+        const globalRoot = path.join(tempRoot, "global-root");
+        fs.mkdirSync(workspaceDir, { recursive: true });
+
+        const env = {
+            AG_KIT_INDEX_PATH: indexPath,
+            AG_KIT_GLOBAL_ROOT: globalRoot,
+            AG_KIT_SKIP_UPSTREAM_CHECK: "1",
+        };
+
+        runCommand(`node bin/ag-kit.js init --targets gemini,codex --path "${workspaceDir}" --quiet`, { env });
+
+        const status = runCommand(`node bin/ag-kit.js status --path "${workspaceDir}" --quiet`, { env }).trim();
+        if (status !== "installed") {
+            throw new Error(`status 结果异常: ${status}`);
+        }
+
+        runCommand(`node bin/ag-kit.js doctor --path "${workspaceDir}" --quiet`, { env });
+        runCommand(`node bin/ag-kit.js update --path "${workspaceDir}" --quiet`, { env });
+        runCommand("node bin/ag-kit.js update-all --dry-run --quiet", { env });
+        runCommand(`node bin/ag-kit.js exclude add --path "${workspaceDir}" --quiet`, { env });
+
+        const excluded = runCommand("node bin/ag-kit.js exclude list --quiet", { env });
+        if (!excluded.split(/\r?\n/).includes(workspaceDir)) {
+            throw new Error("exclude add 未生效");
+        }
+
+        runCommand(`node bin/ag-kit.js exclude remove --path "${workspaceDir}" --quiet`, { env });
+        const excludedAfter = runCommand("node bin/ag-kit.js exclude list --quiet", { env });
+        if (excludedAfter.split(/\r?\n/).includes(workspaceDir)) {
+            throw new Error("exclude remove 未生效");
+        }
+
+        runCommand("node bin/ag-kit.js global sync --quiet", { env });
+        const globalStatus = runCommand("node bin/ag-kit.js global status --quiet", { env }).trim();
+        if (globalStatus !== "installed") {
+            throw new Error(`global status 结果异常: ${globalStatus}`);
+        }
+
+        const globalChecks = [
+            path.join(globalRoot, ".codex", "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) {
+            if (!fs.existsSync(targetPath)) {
+                throw new Error(`global sync 未生成预期文件: ${targetPath}`);
+            }
+        }
+    } finally {
+        fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+
+    logStep("执行清理预检");
+    if (packageRunner === "bun") {
+        runCommand("bun run clean:dry-run");
+    } else {
+        runCommand("npm run clean:dry-run --silent");
+    }
+
+    console.log("✅ 健康检查通过");
+}
+
+try {
+    main();
+} catch (err) {
+    console.error(`❌ ${err.message}`);
+    process.exit(1);
+}

package/scripts/health-check.sh

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+node "${ROOT_DIR}/scripts/health-check.js" "$@"