@mison/ag-kit-cn 3.0.0-beta.0 → 3.0.0

package/bin/core/builder.js

@@ -9,7 +9,7 @@ const pkg = require("../../package.json");
 class CodexBuilder {
     /**
      * Build a Codex structure from a legacy/source repository
-     * @param {string} sourceRoot Root of the repo (containing .agent/)
+     * @param {string} sourceRoot Root of the repo (containing .agents/)
      * @param {string} outputDir Directory to output the built .agents-compatible structure
      */
     static build(sourceRoot, outputDir) {

package/bin/core/generator.js

@@ -22,8 +22,8 @@ class RuleGenerator {
         };
 
         // 2. Generate AGENTS.md managed section content
-        let agentsMd = `# AI Agent Capabilities (AG-Kit Managed)\n\n`;
-        agentsMd += `> **Auto-generated by Antigravity Kit (Full Mode)**\n`;
+        let agentsMd = `# AI Agent Capabilities (Codex Managed)\n\n`;
+        agentsMd += `> **Auto-generated by Antigravity Kit (Codex)**\n`;
         agentsMd += `> Version: ${version}\n\n`;
         
         agentsMd += `## Available Skills\n\n`;
@@ -36,7 +36,7 @@ class RuleGenerator {
         agentsMd += `\n## Usage Rules\n\n`;
         agentsMd += `1. Managed resources are synchronized under \`.agents/skills\`.\n`;
         agentsMd += `2. Do not rename managed skill folders manually.\n`;
-        agentsMd += `3. Use \`ag-kit doctor --fix\` to recover missing managed artifacts.\n`;
+        agentsMd += `3. Use \`ag-kit doctor --target codex --fix\` to recover missing managed artifacts.\n`;
 
         // 3. Generate risk controls
         let antigravityRules = `# Antigravity Risk Controls (Codex Managed)\n\n`;
@@ -45,7 +45,7 @@ class RuleGenerator {
         antigravityRules += `## Controls\n`;
         antigravityRules += `- Managed skills are stored under \`.agents/skills\`.\n`;
         antigravityRules += `- Keep generated skill IDs stable to avoid selector drift.\n`;
-        antigravityRules += `- If integrity checks fail, run \`ag-kit doctor --fix\`.\n`;
+        antigravityRules += `- If integrity checks fail, run \`ag-kit doctor --target codex --fix\`.\n`;
         antigravityRules += `- Before destructive updates, preserve manual edits in source control.\n`;
 
         return {

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/interactive.js

@@ -15,96 +15,51 @@ function askQuestion(rl, query) {
     });
 }
 
-async function askChoice(promptTitle, options) {
+/**
+ * Prompt user to select targets from a list.
+ * Supports multiple selection by comma separated numbers or names.
+ * Currently simplified for 'gemini' and 'codex'.
+ * @param {object} options CLI options
+ * @returns {Promise<string[]>} List of selected targets
+ */
+async function selectTargets(options) {
+    if (options.nonInteractive) {
+        throw new Error("非交互模式下必须通过 --target 或 --targets 指定目标");
+    }
+
     const rl = createInterface();
+    
     try {
-        console.log(`\n${promptTitle}`);
-        for (let i = 0; i < options.length; i++) {
-            const item = options[i];
-            console.log(`   ${i + 1}. ${item.label}`);
-            if (item.hint) {
-                console.log(`      ${item.hint}`);
-            }
-        }
-
-        while (true) {
-            const answer = (await askQuestion(rl, "\n请输入序号（必填）: ")).trim();
-            if (!answer) {
-                console.log("   请输入有效序号。");
-                continue;
-            }
+        console.log("\n🎯 请选择要安装的目标 (多选请用逗号分隔):");
+        console.log("   1. Gemini (适用于 Cursor/VSCode)");
+        console.log("   2. Codex (兼容性增强版)");
+        
+        const answer = await askQuestion(rl, "\n请输入序号或名称（必填）: ");
+        const input = answer.trim();
 
-            const index = Number.parseInt(answer, 10);
-            if (!Number.isFinite(index) || index < 1 || index > options.length) {
-                console.log(`   无效输入: ${answer}`);
-                continue;
-            }
+        if (!input) {
+            throw new Error("必须选择至少一个目标");
+        }
+        
+        const selection = [];
+        const parts = input.split(/[,，\s]+/);
+        
+        for (const part of parts) {
+            const p = part.toLowerCase();
+            if (p === "1" || p === "gemini") selection.push("gemini");
+            else if (p === "2" || p === "codex") selection.push("codex");
+        }
 
-            return options[index - 1].value;
+        if (selection.length === 0) {
+            throw new Error("无效的目标选择，请输入 1 / 2 / gemini / codex（可多选）");
         }
+
+        return [...new Set(selection)];
     } finally {
         rl.close();
     }
 }
 
-/**
- * 统一 full 安装模式下，保留兼容返回。
- * @returns {Promise<string[]>}
- */
-async function selectTargets() {
-    return ["full"];
-}
-
-/**
- * 冲突：已有 .agent 且无法确定是否托管时，询问处理策略。
- * @returns {Promise<"backup_replace"|"keep"|"rename_disable">}
- */
-async function selectAgentConflictPolicy() {
-    return askChoice("检测到已有 .agent 目录，请选择处理方式:", [
-        {
-            value: "backup_replace",
-            label: "备份后替换（推荐）",
-            hint: "将现有 .agent 备份到 .agents-backup 后，用 .agents 投影覆盖",
-        },
-        {
-            value: "keep",
-            label: "保留不动",
-            hint: "跳过 .agent 投影，继续安装 .agents",
-        },
-        {
-            value: "rename_disable",
-            label: "改名失效后创建新投影",
-            hint: "把原目录改名为 .agent.user.<ts>，再生成新的 .agent 投影",
-        },
-    ]);
-}
-
-/**
- * 冲突：已有 .gemini/agents 时，询问处理策略。
- * @returns {Promise<"append"|"backup_replace"|"skip">}
- */
-async function selectGeminiAgentsPolicy() {
-    return askChoice("检测到已有 .gemini/agents 目录，请选择处理方式:", [
-        {
-            value: "append",
-            label: "追加 ag-kit-*.md（推荐）",
-            hint: "保留用户文件，仅追加/更新本项目 namespaced agents",
-        },
-        {
-            value: "backup_replace",
-            label: "备份后替换",
-            hint: "备份现有 .gemini/agents 后，仅写入本项目 agents",
-        },
-        {
-            value: "skip",
-            label: "跳过写入",
-            hint: "不触碰 .gemini/agents",
-        },
-    ]);
-}
-
 module.exports = {
-    selectTargets,
-    selectAgentConflictPolicy,
-    selectGeminiAgentsPolicy,
+    selectTargets
 };

package/bin/utils/manifest.js

@@ -7,7 +7,7 @@ class ManifestManager {
         this.manifestPath = manifestPath;
         this.options = options;
         this.manifest = {
-            version: 3,
+            version: 2,
             target: typeof options.target === "string" ? options.target : "",
             kitVersion: typeof options.kitVersion === "string" ? options.kitVersion : "",
             updatedAt: "",
@@ -52,7 +52,7 @@ class ManifestManager {
 
     static normalizeManifestShape(input) {
         const output = {
-            version: typeof input.version === "number" ? input.version : 3,
+            version: typeof input.version === "number" ? input.version : 2,
             target: typeof input.target === "string" ? input.target : "",
             kitVersion: typeof input.kitVersion === "string" ? input.kitVersion : "",
             updatedAt: typeof input.updatedAt === "string" ? input.updatedAt : "",
@@ -86,7 +86,7 @@ class ManifestManager {
             } catch (err) {
                 this.lastLoadError = err;
                 this.manifest = {
-                    version: 3,
+                    version: 2,
                     target: typeof this.options.target === "string" ? this.options.target : "",
                     kitVersion: typeof this.options.kitVersion === "string" ? this.options.kitVersion : "",
                     updatedAt: "",

package/bin/utils.js

@@ -65,14 +65,19 @@ function cloneBranchAgentDir(branch, options) {
 
     const clonedAgentsDir = path.join(tempDir, ".agents");
     const clonedAgentDir = path.join(tempDir, ".agent");
-    const selectedDir = fs.existsSync(clonedAgentsDir) ? clonedAgentsDir : clonedAgentDir;
-    if (!fs.existsSync(selectedDir)) {
+    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} 中未找到 .agents 或 .agent 目录`);
     }
 
     return {
-        agentDir: selectedDir,
+        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": "3.0.0-beta.0",
+  "version": "3.0.0",
   "description": "AI Agent templates - Skills, Agents, and Workflows for enhanced coding assistance",
   "repository": {
     "type": "git",
@@ -23,28 +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.js\""
+    "test": "node --test \"tests/**/*.test.js\"",
+    "ci:verify": "node scripts/ci-verify.js"
   },
   "publishConfig": {
     "access": "public"
   },
   "files": [
     ".agents/**",
-    ".agent/**",
     "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,
+};