@mison/ag-kit-cn 2.0.1

package/docs/official/codex/rules.md

@@ -0,0 +1,79 @@
+# 规则（命令审批规则）
+
+> 来源：`https://developers.openai.com/codex/rules`  
+> 同步日期：2026-02-12  
+> 说明：本文件为官方内容的中文整理版，采用标准 Markdown 语法。
+
+Codex Rules 用于控制“哪些命令允许在沙箱外执行”，属于安全与审批策略层。  
+该能力为实验特性，后续可能调整。
+
+## 创建规则文件
+
+1. 在 `./codex/rules/` 下创建 `.rules` 文件（例如 `~/.codex/rules/default.rules`）。
+2. 写入规则。
+
+示例：在沙箱外执行 `gh pr view` 前必须提示审批。
+
+```python
+prefix_rule(
+    pattern = ["gh", "pr", "view"],
+    decision = "prompt",
+    justification = "查看 PR 需要人工确认",
+    match = [
+        "gh pr view 7888",
+        "gh pr view --repo openai/codex",
+    ],
+    not_match = [
+        "gh pr list",
+    ],
+)
+```
+
+## 规则字段说明
+
+`prefix_rule(...)` 常用字段：
+
+- `pattern`：命令前缀（按 token 匹配）
+- `decision`：命中后的动作
+- `justification`：规则说明（可选）
+- `match`：应命中的测试样例（可选）
+- `not_match`：不应命中的测试样例（可选）
+
+`decision` 常见值：
+
+- `prompt`：询问用户
+- `allow`：允许
+- `deny`：拒绝
+
+## 关于 shell 包装命令与复合命令
+
+常见包装命令包括：
+
+- `bash -lc "..."`
+- `sh -c "..."`
+- `zsh -lc "..."`
+- `python -c "..."`
+
+在可安全拆分时，Codex 可能提取出真实命令做前缀匹配；  
+在不可安全拆分时，会把整体当作一个命令匹配。
+
+### 可安全拆分的典型情况
+
+- 单一命令、无复杂重定向/管道/变量展开
+- 命令结构明确，不会因拆分改变语义
+
+### 不拆分的典型情况
+
+- 包含复杂 shell 语法（多条命令、重定向、条件、子 shell 等）
+- 拆分后可能造成语义偏差或安全风险
+
+## 测试规则文件
+
+建议每条规则都写 `match` / `not_match` 示例，作为“内联单元测试”。  
+这样可以在维护规则时快速验证匹配行为，减少误放行或误阻断。
+
+## 规则语言边界
+
+- Rules 只负责命令级审批策略，不负责业务逻辑说明。
+- 业务约束建议放在 `AGENTS.md` 或项目文档中。
+- 高风险命令建议默认 `prompt` 或 `deny`，再按需要放开。

package/docs/official/codex/skills.md

@@ -0,0 +1,114 @@
+# Agent 技能（Codex）
+
+> 来源：`https://developers.openai.com/codex/skills`  
+> 同步日期：2026-02-12  
+> 说明：本文件为官方内容的中文整理版，采用标准 Markdown 语法。
+
+Skills 用于给 Codex 增加任务专用能力。  
+一个 Skill 通常打包了指令、参考资料以及可选脚本，便于 Agent 稳定复用某类流程。
+
+Skills 适用于 Codex CLI、IDE 扩展和 Codex App。
+
+## Skill 基本结构
+
+一个 Skill 目录至少包含 `SKILL.md`：
+
+```text
+my-skill/
+├── SKILL.md        # 必需：元信息 + 指令
+├── scripts/        # 可选：可执行脚本
+├── references/     # 可选：参考文档
+└── assets/         # 可选：模板/资源
+```
+
+`SKILL.md` 需包含 `name` 与 `description`：
+
+```markdown
+---
+name: skill-name
+description: 说明该 skill 的用途与触发场景
+metadata:
+  short-description: 可选的简短说明
+---
+
+# Skill 标题
+
+在此编写可执行指令。
+```
+
+## Codex 如何使用 Skills
+
+Codex 采用“渐进式加载”：
+
+1. 会话开始时先读取各 Skill 的元信息（`name`、`description`、路径等）。
+2. 仅当某 Skill 与当前任务相关时，才读取完整 `SKILL.md`。
+3. 执行过程中按 Skill 指令调用脚本/引用资料。
+
+## 创建 Skill
+
+两种方式：
+
+- 使用内置 Skill（例如 `$skill-creator`）辅助生成
+- 手动创建目录与 `SKILL.md`
+
+手动创建建议流程：
+
+1. 创建目录 `my-skill/`
+2. 写好 `SKILL.md` 的 frontmatter
+3. 按需补充 `scripts/`、`references/`、`assets/`
+
+## Skill 存放位置
+
+常见位置：
+
+- 全局：`$HOME/.agents/skills/`
+- 项目：从当前工作目录开始，向上到仓库根目录，按链路扫描 `.agents/skills/`
+
+实践建议：
+
+- 跨项目复用放全局
+- 项目专属流程放仓库内并随代码版本管理
+
+## 安装与管理
+
+可通过 CLI 管理技能开关与列表（实际命令以当前版本为准）：
+
+```bash
+codex skills list
+codex skills enable <skill-name>
+codex skills disable <skill-name>
+```
+
+对于 App/Server 场景，也可通过 API 传入 Skill 项。
+
+## 可选元数据
+
+除必填字段外，可在 frontmatter 增加元数据（如 `short-description`），用于改善 UI 展示和匹配体验。  
+但不要把业务逻辑藏在元数据里，核心行为应写在正文指令区。
+
+## 编写最佳实践
+
+### 1. 描述要能触发
+
+`description` 建议写清：
+
+- 做什么
+- 何时用
+- 不适用场景
+
+### 2. 单一职责
+
+一个 Skill 解决一类问题，不要做“万能包”。
+
+### 3. 脚本优先可执行
+
+把复杂流程写进 `scripts/`，在 `SKILL.md` 中说明参数与调用方式。  
+避免要求 Agent 反复阅读大段脚本源码。
+
+### 4. 给出决策分支
+
+复杂任务建议提供“条件 -> 路径”决策表，降低误用率。
+
+### 5. 保持可迁移
+
+尽量避免绑定私有路径与私有环境变量，必要时在 `references/` 说明依赖前置条件。

package/docs/official/sources-index.md

@@ -0,0 +1,32 @@
+# 官方来源证据索引
+
+> 用途：为 `docs/official` 中文整理文档提供可机器校验的最小证据层（来源 URL + 拉取时间 + 快照哈希）。
+
+## Antigravity
+
+| 本地文件 | 来源 URL | 拉取时间 (UTC) | SHA256 |
+| --- | --- | --- | --- |
+| `docs/official/antigravity/agent-modes-settings.md` | `https://antigravity.google/assets/docs/agent/agent-modes-settings.md` | `2026-02-12T12:56:22Z` | `614174f8c730a0db8b290dede16b294a9535cef7b9ddca9c108dc2ef583b2919` |
+| `docs/official/antigravity/rules-workflows.md` | `https://antigravity.google/assets/docs/agent/rules-workflows.md` | `2026-02-12T12:56:22Z` | `063b2e9c86555f0103d0fafee5f71caf330cd95fb25257841efe32d36ee9667b` |
+| `docs/official/antigravity/skills.md` | `https://antigravity.google/assets/docs/agent/skills.md` | `2026-02-12T12:56:22Z` | `2176fc1968c2188daed75b064f8771e4516b4b462cc5c1b98553e05cfab055fa` |
+
+## Codex
+
+| 本地文件 | 来源 URL | 拉取时间 (UTC) | SHA256 |
+| --- | --- | --- | --- |
+| `docs/official/codex/config-basic.md` | `https://developers.openai.com/codex/config-basic.md` | `2026-02-12T12:56:22Z` | `9a270e83da4e3467c117166cc69684cace72037c97c96f0f05f212d28ccf0809` |
+| `docs/official/codex/config-advanced.md` | `https://developers.openai.com/codex/config-advanced.md` | `2026-02-12T12:56:22Z` | `ed1ebb5ad918fd9043ebeb176d1f29654d76547c4ae896eb4718db320f98a1af` |
+| `docs/official/codex/config-reference.md` | `https://developers.openai.com/codex/config-reference.md` | `2026-02-12T12:56:22Z` | `e23bc1439e3f4cb907d165e6980ece03070d69484f74c4cb3dd95068c519a91c` |
+| `docs/official/codex/config-sample.md` | `https://developers.openai.com/codex/config-sample.md` | `2026-02-12T12:56:22Z` | `80af7755383b5f3956b3288435bca81ef02062f6dd988aa6205fe1ae95a3660b` |
+| `docs/official/codex/rules.md` | `https://developers.openai.com/codex/rules.md` | `2026-02-12T12:56:22Z` | `c9ca3c8bf4fa68ccf85c831388ea360b6e2108bcfcfcc0b7bd7e2ab5df173af1` |
+| `docs/official/codex/agents-md.md` | `https://developers.openai.com/codex/guides/agents-md.md` | `2026-02-12T12:56:22Z` | `ed8fd0bdb19826d907424d313d38b37fe9a60c78b96692f409e1f15373817aac` |
+| `docs/official/codex/mcp.md` | `https://developers.openai.com/codex/mcp.md` | `2026-02-12T12:56:22Z` | `bb7d0e864ed572a11067505f9cd673972610d2d53997db3647b309da00763fa2` |
+| `docs/official/codex/skills.md` | `https://developers.openai.com/codex/skills.md` | `2026-02-12T12:56:22Z` | `8ca8093fa07e50d302a76a6693789995bb733208fd3e89022e2ebd2328b3b64c` |
+
+## 校验方法
+
+```bash
+shasum -a 256 docs/official/codex/skills.md
+```
+
+将输出哈希与本表对比即可。

package/docs/operations.md

@@ -0,0 +1,145 @@
+# Ag-Kit（命令行工具）运维手册
+
+本文面向维护 Ag-Kit 及其管理的 Agent（智能体）资源的 DevOps（运维）或高级用户。
+
+## 1. 目录结构详解
+
+### 1.1 项目根目录
+
+```text
+/my-project
+├── .agent/               # Legacy（旧版）Gemini 模式直连目录（使用 Gemini 时）
+├── .agents/              # Codex 托管上游目录（只读/自动管理）
+│   ├── manifest.json     # 完整性清单，用于漂移检测
+│   ├── AGENTS.md         # 核心规则源（由构建器生成）
+│   ├── antigravity.rules # 风险控制源（由构建器生成）
+│   └── skills/           # 编译后的技能
+├── .agents-backup/       # Codex 自动备份目录（发生漂移覆盖时生成）
+├── .codex/               # Legacy 历史目录（更新/doctor 时自动迁移清理）
+├── AGENTS.md             # 工作区主入口（保留用户内容 + 托管区块注入）
+├── antigravity.rules     # 工作区托管说明（保留用户内容 + 托管区块注入）
+└── .gitignore            # 自动管理的忽略规则
+```
+
+> 说明：`antigravity.rules` 是本项目的托管说明文件，不等同于 Codex 官方 `.rules` 审批策略文件。  
+> Codex 官方策略文件通常位于 `~/.codex/rules/default.rules`，本项目不会自动写入该全局路径。
+
+### 1.2 全局数据
+
+- **macOS / Linux**: `~/.ag-kit/workspaces.json`
+- **Windows**: `%USERPROFILE%\.ag-kit\workspaces.json`
+- 默认不会把系统临时目录写入索引（如 macOS `/var/folders/...`、`/tmp`、`/private/tmp`，Linux `/tmp`，Windows `%TEMP%`）。
+- 对临时验证场景，可在 `init/update` 时加 `--no-index` 完全跳过索引登记。
+- `ag-kit update` 仅处理当前目录（或 `--path` 指定目录），不依赖全局索引。
+- `ag-kit update-all` 仅处理索引内工作区；若项目曾使用 `--no-index`，可在项目内执行一次不带 `--no-index` 的 `ag-kit update` 重新纳入索引。
+
+## 2. 故障排查
+
+### 2.1 更新失败或中断
+
+当前版本已引入 Atomic Update（原子更新）机制。
+
+- 更新过程先在临时目录准备，最后通过一次 `rename` 操作生效。
+- **现象**: 如果进程在更新阶段被中断，项目目录不会出现半写状态，可能残留临时目录（例如 `/tmp/ag-kit-*`）。
+- **解决**: 无需手动干预，重新运行 update 即可。
+
+### 2.2 漂移检测警告
+
+当 `ag-kit update` 或 `ag-kit doctor` 报告 Drift（漂移）时：
+
+- **原因**: 用户手动修改了 `.agents` 目录下的受管文件。
+- **后果**: 更新时会强制覆盖这些修改。
+- **自动备份**: 覆盖前，Ag-Kit 会将修改过的文件备份到 `.agents-backup/<timestamp>/`。
+- **智能覆盖**: 仅当文件确实是“用户修改且与新版本不同”时才备份；如果本地文件已与新版本一致，不会重复备份。
+- **解决**: 检查备份，将需要的修改迁移到上游源码或通过 Overlay（覆盖层）机制实现。
+
+### 2.3 Windows 权限问题
+
+- 如果遇到 `EPERM` 或 `EBUSY`：
+    - 确保没有 IDE 或终端占用 `.agents` 目录。
+    - 关闭占用后重新执行 `ag-kit update` 或 `ag-kit doctor --fix`。
+
+### 2.4 Doctor 自愈
+
+```bash
+ag-kit doctor --fix
+```
+
+- **功能**:
+    - 如果 `manifest.json` 丢失，会对照当前文件状态重新生成（注意：这会假设当前状态是正确的）。
+    - 会重同步 `AGENTS.md` 和 `antigravity.rules` 的托管区块。
+    - Gemini 目标当前不支持自动修复，建议执行 `ag-kit update --target gemini`。
+
+## 3. 升级流程
+
+### 3.0 Codex 官方 `.rules`（可选）
+
+如果你需要启用 Codex 官方命令审批策略（`prefix_rule()` 等），请手动配置 `~/.codex/rules/default.rules`。  
+可直接参考：`docs/codex-rules-template.md`。
+
+### 3.1 客户端升级
+
+```bash
+npm install -g @mison/ag-kit-cn@latest
+```
+
+若你以源码方式安装过，也可以继续使用源码升级：
+
+```bash
+git -C /path/to/antigravity-kit-cn pull
+cd /path/to/antigravity-kit-cn
+npm install -g .
+```
+
+### 3.2 资源库迁移：Gemini -> Codex
+
+1. 在项目根目录执行：
+    ```bash
+    ag-kit init --target codex --force
+    ```
+2. 系统会自动识别旧版 `.agent`，将其编译为 `.agents` 结构。
+3. 确认 `.agents` 生成无误。
+4. 移除旧版 `.agent`（可选）：
+    ```bash
+    rm -rf .agent
+    ```
+
+## 4. 日常维护
+
+### 4.1 清理本地生成产物
+
+在仓库根目录执行：
+
+```bash
+npm run clean
+```
+
+- 会清理常见生成目录：`.temp_ag_kit`、`coverage`、`web/.next`、`web/node_modules`、`web/out`、`web/.turbo`。
+- 只想预览，不实际删除：
+
+```bash
+npm run clean:dry-run
+```
+
+### 4.2 回归检查
+
+```bash
+npm test
+```
+
+- 当前测试命令仅扫描 `tests/` 目录，避免误执行 `web/.next` 等构建产物中的文件。
+- 若需要检查前端代码规范（可选），先安装依赖再执行：
+
+```bash
+npm install --prefix web
+npm run lint --prefix web
+```
+
+### 4.3 一键健康复检
+
+```bash
+npm run health-check
+```
+
+- 会顺序执行：`npm test`、CLI 临时工作区链路验证（`init/status/doctor/update/update-all/exclude`）、`npm run clean:dry-run`。
+- 适合升级后或准备发布前的快速回归确认。

package/docs/terminology-style-guide.md

@@ -0,0 +1,69 @@
+# 术语风格统一表
+
+本表用于约束仓库内中文文案写法，目标是“中文主叙述、术语级双语、机制文本不变形”。
+
+## 写法规则
+
+1. 中文主叙述：标题、段落、表头、说明文本默认使用中文表达。
+2. 专有名词英文保留：官方名词优先保留英文（如 `Agent（智能体）`、`Strict Mode（严格模式）`、`Task List（任务清单）`）。
+3. 首次双语标注（仅术语级）：同一文档首次出现时写作 `English（中文）`，后续可简写为 `English`。
+4. 禁止标题整句双语：禁止 `中文标题 (English sentence...)` 或 `English title (中文整句...)`。
+5. 禁止段落整句双语：禁止“英文整句 + 中文整句括号翻译”并排出现。
+6. 保留关键字：命令、参数、路径、快捷键、按钮文案保持原样（如 `--fix`、`/workflow-name`、`Command + I`）。
+7. 机制文本例外：代码块、命令块、Frontmatter key、配置键名不做双语拼接。
+8. 示例命令含提示词时：仅翻译 prompt/query（提示词）语义，命令结构保持不变。
+9. 语义优先：不改变机制、不改变行为，仅调整语言表述。
+
+## 统一术语
+
+| 推荐写法 | 可接受别名（仅历史兼容） | 说明 |
+| --- | --- | --- |
+| Agent（智能体） | 智能体 | 平台执行主体；首现必须双语 |
+| Skill（技能） | Skills、技能 | 能力模块；首现必须双语 |
+| Workflow（工作流） | Workflows、工作流 | 任务流程；首现必须双语 |
+| Workspace（工作区） | 工作空间 | 项目作用域 |
+| Global（全局） | Global | 跨工作区作用域 |
+| Allowlist（允许列表） | 允许列表 | 白名单语义 |
+| Denylist（拒绝列表） | 拒绝列表 | 黑名单语义 |
+| Strict Mode（严格模式） | Strict Mode | 安全策略组合；首现必须双语 |
+| Sandboxing（终端沙箱） | Sandboxing | 命令执行隔离；首现必须双语 |
+| Artifact（产物） | Artifacts、产物 | 过程与结果载体；首现必须双语 |
+| Command（命令面板） | Command | 内联指令入口；首现必须双语 |
+| MCP Store（MCP 商店） | MCP Store | MCP 连接入口；首现必须双语 |
+| Browser Subagent（浏览器子智能体） | Browser Subagent | 浏览器操作代理；首现必须双语 |
+| Task List（任务清单） | Task List | 任务追踪产物；首现必须双语 |
+| Implementation Plan（实施计划） | Implementation Plan | 计划产物；首现必须双语 |
+| Knowledge（知识库） | Knowledge | 持久化知识能力；首现必须双语 |
+
+## 双语边界（强制）
+
+- 允许（术语级）：
+  - `Orchestrator skill（编排器技能）`
+  - `MCP（模型上下文协议）`
+- 禁止（整句级）：
+  - `This skill routes to sub-skills.（此技能会路由到子技能。）`
+  - `## 移动端设计系统 (Mobile Design System)`
+
+## 首次标注模板
+
+- 正文首现：`Agent（智能体）`、`Workflow（工作流）`、`MCP（模型上下文协议）`
+- 后续正文：`Agent`、`Workflow`、`MCP`
+- 禁止写法：`智能体（Agent）` 作为主格式、`Agent智能体`（无括号）、`Agent/智能体`（斜杠混写）、`中文标题 (English sentence)`
+
+## 示例命令中的提示词翻译
+
+- 目标：让示例命令在中文语境下可直接复用，同时不破坏命令机制。
+- 规则：只翻译自然语言提示词；命令、参数、路径、开关、子命令保持原样。
+- 示例：
+  - 原文：`python scripts/search.py "fintech crypto" --design-system`
+  - 推荐：`python scripts/search.py "金融 科技 加密" --design-system`
+  - 推荐：`python scripts/search.py "为金融科技产品生成设计系统关键词" --design-system`
+
+## 当前覆盖范围（2026-02）
+
+- `.agent/**/*.md`（含 `agents/`、`skills/`、`workflows/`、`ARCHITECTURE.md`）
+- `README.md`
+- `AGENT_FLOW.md`
+- `docs/*.md`
+
+后续新增文档默认遵循本表；若与上游机制冲突，先按 `reference/antigravity-kit` 对齐结构，再做语义汉化。

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@mison/ag-kit-cn",
+  "version": "2.0.1",
+  "description": "AI Agent templates - Skills, Agents, and Workflows for enhanced coding assistance",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MisonL/antigravity-kit-cn.git"
+  },
+  "homepage": "https://github.com/MisonL/antigravity-kit-cn#readme",
+  "bugs": {
+    "url": "https://github.com/MisonL/antigravity-kit-cn/issues"
+  },
+  "keywords": [
+    "antigravity",
+    "ai",
+    "agent",
+    "gemini",
+    "skills",
+    "templates"
+  ],
+  "author": "vudovn",
+  "license": "MIT",
+  "scripts": {
+    "clean": "node scripts/clean.js",
+    "clean:dry-run": "node scripts/clean.js --dry-run",
+    "health-check": "bash scripts/health-check.sh",
+    "postinstall": "node scripts/postinstall-check.js",
+    "test": "node --test tests"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    ".agent/**",
+    "bin/**",
+    "scripts/postinstall-check.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/**"
+  ],
+  "bin": {
+    "ag-kit": "./bin/ag-kit.js"
+  }
+}

package/scripts/postinstall-check.js

@@ -0,0 +1,112 @@
+#!/usr/bin/env node
+
+const { execSync } = require("child_process");
+const readline = require("node:readline");
+const { stdin: input, stdout: output } = require("node:process");
+
+const UPSTREAM_GLOBAL_PACKAGE = "@vudovn/ag-kit";
+
+const { readGlobalNpmDependencies } = require("../bin/utils");
+
+function canPromptUser() {
+    return Boolean(input.isTTY && output.isTTY);
+}
+
+function askQuestion(question) {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({ input, output });
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+
+function parseYesNo(answer, defaultYes) {
+    const text = String(answer || "").trim().toLowerCase();
+    if (!text) {
+        return defaultYes;
+    }
+    if (["y", "yes", "1", "true", "是"].includes(text)) {
+        return true;
+    }
+    if (["n", "no", "0", "false", "否"].includes(text)) {
+        return false;
+    }
+    return defaultYes;
+}
+
+async function askForUninstallConfirmation() {
+    const answer = await askQuestion(`是否现在自动卸载 ${UPSTREAM_GLOBAL_PACKAGE}？[Y/n]: `);
+    return parseYesNo(answer, true);
+}
+
+function uninstallUpstreamPackage() {
+    try {
+        execSync(`npm uninstall -g ${UPSTREAM_GLOBAL_PACKAGE}`, {
+            stdio: "inherit",
+        });
+        return true;
+    } catch (err) {
+        return false;
+    }
+}
+
+async function main() {
+    const isGlobalInstall = process.env.npm_config_global === "true";
+    if (!isGlobalInstall) {
+        return;
+    }
+
+    if (process.env.AG_KIT_SKIP_UPSTREAM_CHECK === "1") {
+        return;
+    }
+
+    const deps = readGlobalNpmDependencies();
+    if (!deps) {
+        return;
+    }
+
+    if (!Object.prototype.hasOwnProperty.call(deps, UPSTREAM_GLOBAL_PACKAGE)) {
+        return;
+    }
+
+    console.warn(`\n⚠️  检测到全局已安装上游英文版 ${UPSTREAM_GLOBAL_PACKAGE}`);
+    console.warn("⚠️  上游英文版与当前中文版共用 `ag-kit` 命令名，后安装者会覆盖命令入口。");
+    console.warn("⚠️  为避免后续混淆，建议仅保留一个来源。\n");
+
+    if (!canPromptUser()) {
+        console.warn("ℹ️  当前环境不是交互式终端，无法确认是否自动卸载。");
+        console.warn(`👉 如需卸载，请手动执行: npm uninstall -g ${UPSTREAM_GLOBAL_PACKAGE}`);
+        console.warn("ℹ️  本次将继续安装；安装完成后由最后安装的版本接管 `ag-kit` 命令。\n");
+        return;
+    }
+
+    const shouldUninstall = await askForUninstallConfirmation();
+
+    if (!shouldUninstall) {
+        console.warn(`ℹ️  已保留 ${UPSTREAM_GLOBAL_PACKAGE}，继续安装当前版本。`);
+        console.warn("ℹ️  结果说明：`ag-kit` 命令由最后安装的包生效。\n");
+        return;
+    }
+
+    console.warn(`\n🧹 正在卸载 ${UPSTREAM_GLOBAL_PACKAGE} ...`);
+    const ok = uninstallUpstreamPackage();
+
+    if (ok) {
+        console.warn(`✅ 已卸载 ${UPSTREAM_GLOBAL_PACKAGE}，继续安装当前版本。\n`);
+        return;
+    }
+
+    console.warn(`❌ 自动卸载 ${UPSTREAM_GLOBAL_PACKAGE} 失败，将继续安装当前版本。`);
+    console.warn("ℹ️  若需手动处理，请执行：");
+    console.warn(`   npm uninstall -g ${UPSTREAM_GLOBAL_PACKAGE}`);
+    console.warn("ℹ️  安装完成后，`ag-kit` 命令仍由最后安装的版本生效。\n");
+}
+
+main().catch((err) => {
+    console.warn("⚠️  postinstall 冲突检测出现异常，已跳过，不影响安装继续。");
+    if (err && err.message) {
+        console.warn(`   ${err.message}`);
+    }
+});