@mison/ag-kit-cn 2.0.1 → 3.0.0

package/{.agent → .agents}/agents/frontend-specialist.md

@@ -3,7 +3,7 @@ name: frontend-specialist
 description: 资深前端架构师，构建可维护的 React/Next.js 系统，强调性能优先。适用于 UI 组件、样式、状态管理、响应式设计或前端架构。触发关键词：component, react, vue, ui, ux, css, tailwind, responsive。
 tools: Read, Grep, Glob, Bash, Edit, Write
 model: inherit
-skills: clean-code, react-best-practices, web-design-guidelines, tailwind-patterns, frontend-design, lint-and-validate
+skills: clean-code, nextjs-react-expert, web-design-guidelines, tailwind-patterns, frontend-design, lint-and-validate
 ---
 
 # 资深前端架构师
@@ -599,7 +599,7 @@ _你必须在写代码前向用户展示这个块。_
 
 ---
 
-> **注意（Note）：** 本 Agent 会加载相关技能（clean-code、react-best-practices 等）提供细节。请根据技能规则行事，不要复制模板。
+> **注意（Note）：** 本 Agent 会加载相关技能（clean-code、nextjs-react-expert 等）提供细节。请根据技能规则行事，不要复制模板。
 
 ---
 

package/{.agent → .agents}/agents/orchestrator.md

@@ -120,7 +120,6 @@ skills: clean-code, parallel-agents, behavioral-modes, plan-writing, brainstormi
 | `devops-engineer` | DevOps & Infra | 部署、CI/CD、PM2、监控 |
 | `database-architect` | Database & Schema | Prisma、迁移、性能优化 |
 | `mobile-developer` | Mobile Apps | React Native、Flutter、Expo |
-| `api-designer` | API Design | REST、GraphQL、OpenAPI |
 | `debugger` | Debugging | 根因分析、系统化排障 |
 | `explorer-agent` | Discovery | 代码库探索、依赖关系 |
 | `documentation-writer` | Documentation | **仅用户明确要求文档时** |
@@ -141,13 +140,12 @@ skills: clean-code, parallel-agents, behavioral-modes, plan-writing, brainstormi
 | Agent | CAN Do | CANNOT Do |
 | --- | --- | --- |
 | `frontend-specialist` | 组件、UI、样式、hooks | ❌ 测试文件、API 路由、数据库 |
-| `backend-specialist` | API、服务逻辑、DB 查询 | ❌ UI 组件、样式 |
+| `backend-specialist` | API、服务逻辑、DB 查询、OpenAPI/GraphQL schema | ❌ UI 组件、样式 |
 | `test-engineer` | 测试文件、mock、覆盖率 | ❌ 业务生产代码 |
 | `mobile-developer` | RN/Flutter 组件、移动 UX | ❌ Web 组件 |
 | `database-architect` | schema、迁移、查询 | ❌ UI、API 逻辑 |
 | `security-auditor` | 审计、漏洞、鉴权评估 | ❌ 新功能代码、UI |
 | `devops-engineer` | CI/CD、部署、基础设施配置 | ❌ 应用业务代码 |
-| `api-designer` | API 规范、OpenAPI、GraphQL schema | ❌ UI 代码 |
 | `performance-optimizer` | 性能分析、优化、缓存策略 | ❌ 新功能开发 |
 | `seo-specialist` | Meta、SEO 配置、分析埋点 | ❌ 业务逻辑 |
 | `documentation-writer` | 文档、README、注释 | ❌ 代码逻辑、**未授权自动调用** |

package/.agents/mcp_config.json

@@ -0,0 +1,22 @@
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp"],
+      "env": {
+        "CONTEXT7_API_KEY": "YOUR_API_KEY"
+      }
+    },
+    "context7_backup": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@iflow-mcp/context7-mcp@1.0.0"
+      ]
+    },
+    "shadcn": {
+      "command": "npx",
+      "args": ["shadcn@latest", "mcp"]
+    }
+  }
+}

package/{.agent → .agents}/rules/GEMINI.md

@@ -242,8 +242,8 @@ trigger: always_on
 
 | 任务 | 读取 |
 | ------------ | ------------------------------- |
-| Web UI/UX | `.agent/frontend-specialist.md` |
-| Mobile UI/UX | `.agent/mobile-developer.md` |
+| Web UI/UX | `.agent/agents/frontend-specialist.md` |
+| Mobile UI/UX | `.agent/agents/mobile-developer.md` |
 
 **上述智能体文件包含：**
 

package/{.agent → .agents}/skills/api-patterns/SKILL.md

@@ -36,9 +36,9 @@ allowed-tools: Read, Write, Edit, Glob, Grep
 
 | Need（需求） | Skill（技能） |
 | ---- | ------------ |
-| API implementation（API 落地实现） | `@[skills/backend-development]` |
+| API implementation（API 落地实现） | `@[skills/nodejs-best-practices]` |
 | Data structure（数据库结构设计） | `@[skills/database-design]` |
-| Security details（安全加固细节） | `@[skills/security-hardening]` |
+| Security details（安全加固细节） | `@[skills/vulnerability-scanner]` |
 
 ---
 

package/{.agent → .agents}/skills/app-builder/project-detection.md

@@ -29,6 +29,6 @@
 1. Tokenize user request（对用户请求分词）
 2. 提取关键词
 3. 确定项目类型
-4. 检测缺失信息 → 转发给 conversation-manager（对话管理器）
+4. 检测缺失信息 → 转发给 brainstorming（结构化澄清）
 5. 建议技术栈
 ```

package/{.agent → .agents}/skills/nextjs-react-expert/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: react-best-practices
+name: nextjs-react-expert
 description: 来自 Vercel Engineering 的 React 与 Next.js 性能优化规则。适用于构建组件、优化性能、消除瀑布式请求（waterfalls）、缩减 bundle、性能代码审查与服务端/客户端优化实现。
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 ---
@@ -106,7 +106,7 @@ allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 | 数据库优化              | `@[skills/database-design]`       |
 | 测试策略                | `@[skills/testing-patterns]`      |
 | UI/UX 设计原则          | `@[skills/frontend-design]`       |
-| TypeScript 模式         | `@[skills/typescript-expert]`     |
+| TypeScript/Node 实践    | `@[skills/nodejs-best-practices]` |
 | 部署与 DevOps           | `@[skills/deployment-procedures]` |
 
 ---

package/{.agent → .agents}/skills/parallel-agents/SKILL.md

@@ -115,7 +115,6 @@ allowed-tools: Read, Glob, Grep
 | `devops-engineer` | 运维开发 | "部署", "CI/CD（持续集成/交付）", "基础设施" |
 | `database-architect` | 数据库架构 | "模式（Schema）", "Prisma", "迁移" |
 | `mobile-developer` | 移动端开发 | "React Native", "Flutter", "移动端" |
-| `api-designer` | API 设计 | "REST（表述性状态转移）", "GraphQL（图查询语言）", "OpenAPI（开放 API 规范）" |
 | `debugger` | 调试专家 | "Bug（缺陷）", "错误", "不工作" |
 | `explorer-agent` | 探索发现 | "探索", "映射", "结构" |
 | `documentation-writer` | 文档编写 | "写文档", "创建 README（说明文档）", "生成 API 文档" |

package/.agents/skills/refactoring-patterns/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: refactoring-patterns
+description: 遗留系统的安全重构模式。适用于代码异味治理、模块拆分、接口迁移与低风险迭代重构。
+allowed-tools: Read, Write, Edit, Grep, Glob
+---
+
+# 重构模式（Refactoring Patterns）
+
+## 目标
+
+在不破坏现有行为的前提下，逐步提升可读性、可测试性与可维护性。
+
+## 适用场景
+
+- 巨型函数、深层嵌套、重复逻辑。
+- 历史模块耦合严重，改一处影响多处。
+- 需要在持续交付中逐步替换旧实现，而非一次性重写。
+
+## 执行顺序（强制）
+
+1. 先锁定行为：补齐回归测试或特征测试（characterization tests）。
+2. 小步提交：每次只做一种重构动作（如提取函数、重命名、移动模块）。
+3. 每步验证：确保测试通过后再进入下一步。
+4. 接口稳定优先：对外 API 先兼容，内部再逐层替换。
+
+## 常用模式
+
+- 提取函数（Extract Function）：把多职责逻辑拆成具名步骤。
+- 引入门面（Facade）：先封装旧接口，再在门面后逐步替换实现。
+- 依赖倒置（Dependency Inversion）：把硬编码依赖替换为可注入接口。
+- 删除死代码（Dead Code Removal）：仅在有覆盖和调用链确认后执行。
+
+## 禁止事项
+
+- 无测试直接大规模重写。
+- 同一提交混入功能变更与重构变更。
+- 修改外部契约却不提供迁移路径或兼容层。
+
+## 完成标准
+
+- 行为保持一致（回归测试通过）。
+- 复杂度下降（函数长度、嵌套层级、重复率可观测改善）。
+- 变更说明清晰（记录重构动机、范围与风险点）。

package/{.agent → .agents}/workflows/create.md

@@ -16,7 +16,7 @@ $ARGUMENTS
 
 1. **需求分析**
    - 理解用户的具体需求
-   - 如果信息缺失，使用 `conversation-manager` 技能进行提问
+   - 如果信息缺失，使用 `brainstorming` 技能进行结构化提问
 
 2. **项目规划**
    - 使用 `project-planner` Agent（智能体）进行任务拆解

package/CHANGELOG.md

@@ -7,6 +7,27 @@
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-03-13
+
+### 重大变更
+
+- **仓库模板源统一**：仓库内统一收敛到 `.agents/` 作为唯一 Canonical 模板源；旧 `.agent/` 仅保留输入兼容，不再作为主路径。
+- **项目级 Codex 体系稳定化**：Codex 项目安装/更新统一落到 `.agents/`，并继续支持从遗留 `.codex/` 自动迁移。
+- **全局安装模型重构**：`ag-kit global sync/status` 成为统一的全局 Skills 安装/更新入口。
+
+### 新增
+
+- **全局 Skills 同步**：
+  - `codex` 同步到 `~/.codex/skills/`
+  - `gemini` 同时同步到 `~/.gemini/skills/` 与 `~/.gemini/antigravity/skills/`
+- **状态契约收紧**：`ag-kit status --quiet` 与 `ag-kit global status --quiet` 统一输出 `installed / broken / missing`，并使用固定退出码 `0 / 1 / 2`。
+- **跨平台验证增强**：新增 `ci:verify`、Node 版 `health-check` 与 GitHub Actions 跨平台工作流。
+
+### 修复
+
+- **旧索引兼容**：`update-all` 现在能自动归一化历史索引中的 `targets.full`，不再要求手工清理索引。
+- **全局路径对齐真实工具**：修正之前全局路径和真实消费端不一致的问题，确保文档、测试、CI 与实际工具行为一致。
+
 
 ## [2.0.2] - 2026-02-04
 

package/README.md

@@ -1,6 +1,10 @@
 # Antigravity Kit CN
 
-> 包含 Skills（技能）、Agents（智能体）与 Workflows（工作流）的 AI Agent 模板
+[![npm version](https://img.shields.io/npm/v/%40mison%2Fag-kit-cn?logo=npm)](https://www.npmjs.com/package/@mison/ag-kit-cn)
+[![npm downloads](https://img.shields.io/npm/dm/%40mison%2Fag-kit-cn?logo=npm)](https://www.npmjs.com/package/@mison/ag-kit-cn)
+[![license](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+> 面向 Antigravity 与 Codex 的中文 AI Agent 模板工具包，提供 Skills、Agents、Workflows 与 ag-kit CLI 的一键安装、更新和治理。
 >
 > [!NOTE]
 > 本仓库基于上游 vudovn/antigravity-kit 同步更新并进行中文化，同时提供 Codex（代码智能体环境）适配。
@@ -11,6 +15,12 @@
 npm install -g @mison/ag-kit-cn
 ```
 
+或使用 Bun：
+
+```bash
+bun install -g @mison/ag-kit-cn
+```
+
 然后在你的目标项目中初始化：
 
 ```bash
@@ -37,12 +47,37 @@ npm install -g .
 
 这会把所选目标结构安装到你的项目中（`gemini -> .agent`，`codex -> .agents`），并把 Codex 托管内容注入工作区 `AGENTS.md` 与 `antigravity.rules`（说明性托管区块，不是 Codex 官方 `.rules` 审批策略文件）。
 
+### 全局安装（跨项目复用 Skills）
+
+为区分“项目安装”和“全局安装”，提供专用命令面：
+
+- 项目安装：`ag-kit init` / `ag-kit update`（功能最完整）
+- 全局安装：`ag-kit global sync`（仅同步 Skills，跨项目复用）
+- 默认行为：`ag-kit global sync` 未指定 `--target/--targets` 时，同步 `codex + gemini`
+- 真实落盘：
+  - `codex` -> `~/.codex/skills/`
+  - `gemini` -> 同时写入 `~/.gemini/skills/` 与 `~/.gemini/antigravity/skills/`
+
+示例：
+
+```bash
+ag-kit global sync
+ag-kit global sync --target codex
+ag-kit global sync --target gemini
+ag-kit global status
+```
+
+全局安装只同步 Skills，不写入 Rules/Agents/Workflows，避免全局副作用。
+覆盖同名 Skill 前会自动备份；手动回滚方式见 `docs/TECH.md`。
+
+规划与边界细节见：`docs/PLAN.md`（规划）与 `docs/TECH.md`（技术）。
+
 ### Codex 规则边界说明
 
 - `antigravity.rules`：本项目生成并注入的托管说明文件，用于记录受管资源与运维约束。
 - `.rules`（如 `~/.codex/rules/default.rules`）：Codex 官方的命令审批/执行策略文件（Starlark 规则，支持 `prefix_rule()`）。
 - 默认行为：本项目不会自动写入你的全局 `~/.codex/rules`，避免引入不可预期的全局副作用。
-- 如需启用官方 `.rules` 审批策略，请参考 `docs/codex-rules-template.md`。
+- 如需启用官方 `.rules` 审批策略，请参考 `docs/TECH.md` 的「Codex 官方 `.rules`（手动配置）」小节。
 
 ### ⚠️ 关于 `.gitignore` 的重要说明
 
@@ -133,6 +168,8 @@ CLI（命令行界面）工具：
 | `ag-kit update` | 更新当前项目已安装目标 |
 | `ag-kit update-all` | 批量更新所有已登记工作区 |
 | `ag-kit doctor` | 诊断安装完整性（可 `--fix` 自愈） |
+| `ag-kit global sync` | 全局同步 Skills（默认同步 codex + gemini；其中 gemini 同步到 gemini-cli 与 antigravity） |
+| `ag-kit global status` | 查看全局 Skills 安装状态 |
 | `ag-kit exclude` | 管理全局索引排除清单 |
 | `ag-kit status` | 检查安装状态 |
 
@@ -156,6 +193,13 @@ ag-kit exclude add --path /path/to/dir            # 新增排除路径
 ag-kit exclude remove --path /path/to/dir         # 删除排除路径
 ```
 
+### 状态命令约定
+
+- `ag-kit status --quiet`：输出 `installed` / `broken` / `missing`
+- `ag-kit global status --quiet`：输出 `installed` / `broken` / `missing`
+- 退出码：`0=installed`，`1=broken`，`2=missing`
+- `status` 面向自动化健康判断；如需问题明细，使用 `ag-kit doctor`
+
 ### 批量更新机制
 
 - 执行 `ag-kit init` / `ag-kit update` 时，会把工作区路径登记到全局索引文件：
@@ -173,19 +217,21 @@ ag-kit exclude remove --path /path/to/dir         # 删除排除路径
 ### 开发维护命令
 
 ```bash
-npm run clean           # 清理本地生成产物（如 web/.next、web/node_modules）
-npm run clean:dry-run   # 预览将被清理的路径
-npm test                # 只执行 tests/ 目录下测试
-npm run health-check    # 一键执行全链路健康复检
+bun run clean           # 清理本地生成产物（如 web/.next、web/node_modules）
+bun run clean:dry-run   # 预览将被清理的路径
+bun run test            # 只执行 tests/ 目录下测试
+bun run health-check    # 一键执行全链路健康复检
 ```
 
 如果你在 `web/` 子项目内开发，可按需执行：
 
 ```bash
-npm install --prefix web
-npm run lint --prefix web
+bun install --cwd web
+bun run lint --cwd web
 ```
 
+> 说明：若你通过 `bun install -g` 安装 CLI，Bun 默认会阻止本包 `postinstall`。上游同名包冲突提示会在首次执行 `ag-kit init/update/update-all/global sync` 时给出。
+
 ## 卸载
 
 ### 卸载本机全局 CLI

package/bin/adapters/codex.js

@@ -132,16 +132,17 @@ class CodexAdapter extends BaseAdapter {
         const CodexBuilder = require("../core/builder");
         let buildTemp = "";
 
-        const hasAgentDir = fs.existsSync(path.join(installSource, ".agent"));
+        const hasAgentsRoot = fs.existsSync(path.join(installSource, ".agents"));
+        const hasLegacyAgentRoot = fs.existsSync(path.join(installSource, ".agent"));
         const hasSkillsDir = fs.existsSync(path.join(installSource, "skills"));
         const isCodexPrebuilt = fs.existsSync(path.join(installSource, "manifest.json"));
 
         if (!isCodexPrebuilt) {
             if (hasSkillsDir) {
-                this.log("🛠️ 检测到 .agent 内容格式，正在构建 Codex 结构...");
+                this.log("🛠️ 检测到模板目录格式，正在构建 Codex 结构...");
                 const mockRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-build-root-"));
-                const mockAgent = path.join(mockRoot, ".agent");
-                this._copyDir(installSource, mockAgent);
+                const mockAgents = path.join(mockRoot, ".agents");
+                this._copyDir(installSource, mockAgents);
 
                 buildTemp = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-build-out-"));
                 CodexBuilder.build(mockRoot, buildTemp);
@@ -154,8 +155,8 @@ class CodexAdapter extends BaseAdapter {
                     fs.rmSync(mockRoot, { recursive: true, force: true });
                     fs.rmSync(buildTemp, { recursive: true, force: true });
                 };
-            } else if (hasAgentDir) {
-                this.log("🛠️ 检测到仓库根目录格式，正在构建 Codex 结构...");
+            } else if (hasAgentsRoot) {
+                this.log("🛠️ 检测到仓库根目录格式(.agents)，正在构建 Codex 结构...");
                 buildTemp = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-build-out-"));
                 CodexBuilder.build(installSource, buildTemp);
                 installSource = buildTemp;
@@ -166,6 +167,23 @@ class CodexAdapter extends BaseAdapter {
                     if (previousCleanup) previousCleanup();
                     fs.rmSync(buildTemp, { recursive: true, force: true });
                 };
+            } else if (hasLegacyAgentRoot) {
+                this.log("🛠️ 检测到旧版仓库根目录格式(.agent)，正在构建 Codex 结构...");
+                const mockRoot = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-build-root-"));
+                const mockAgents = path.join(mockRoot, ".agents");
+                this._copyDir(path.join(installSource, ".agent"), mockAgents);
+
+                buildTemp = fs.mkdtempSync(path.join(os.tmpdir(), "ag-kit-build-out-"));
+                CodexBuilder.build(mockRoot, buildTemp);
+                installSource = buildTemp;
+                sourceLabel = `${sourceLabel}:compiled`;
+
+                const previousCleanup = cleanup;
+                cleanup = () => {
+                    if (previousCleanup) previousCleanup();
+                    fs.rmSync(mockRoot, { recursive: true, force: true });
+                    fs.rmSync(buildTemp, { recursive: true, force: true });
+                };
             }
         }
 
@@ -320,6 +338,11 @@ class CodexAdapter extends BaseAdapter {
 
         const manager = new ManifestManager(manifestPath, { target: "codex" });
         manager.load();
+        if (manager.lastLoadError) {
+            result.status = "broken";
+            result.issues.push("Critical: manifest.json invalid JSON");
+            return result;
+        }
         const drift = manager.checkDrift(managedDir);
 
         if (drift.missing.length > 0) {

package/bin/adapters/gemini.js

@@ -11,11 +11,9 @@ class GeminiAdapter extends BaseAdapter {
     }
 
     getInstalledVersion() {
-        // In v1, version was not strictly tracked per target in a file.
-        // We assume check existence of .agent/agents directory.
         const agentDir = path.join(this.workspaceRoot, ".agent");
         if (fs.existsSync(agentDir)) {
-            return "2.0.1"; // Default to current version if exists
+            return null;
         }
         return null;
     }
@@ -126,6 +124,28 @@ class GeminiAdapter extends BaseAdapter {
         if (!fs.existsSync(agentDir)) {
              return { status: "missing", issues: [".agent directory missing"] };
         }
+
+        const issues = [];
+        const requiredDirs = ["agents", "skills", "rules", "workflows"];
+        for (const relPath of requiredDirs) {
+            const absPath = path.join(agentDir, relPath);
+            if (!fs.existsSync(absPath) || !fs.statSync(absPath).isDirectory()) {
+                issues.push(`Missing required directory: .agent/${relPath}`);
+            }
+        }
+
+        const requiredFiles = ["rules/GEMINI.md", "agents/orchestrator.md"];
+        for (const relPath of requiredFiles) {
+            const absPath = path.join(agentDir, relPath);
+            if (!fs.existsSync(absPath) || !fs.statSync(absPath).isFile()) {
+                issues.push(`Missing required file: .agent/${relPath}`);
+            }
+        }
+
+        if (issues.length > 0) {
+            return { status: "broken", issues };
+        }
+
         return { status: "ok", issues: [] };
     }