npm package: @siliconoid/agentkit
Description: CLI tool to initialize and manage AI coding rules across multiple platforms
Author: superteam
Latest version: 0.4.17

# AgentKit

一套 Frontend CLI 工具，为项目统一初始化和管理 AI 编码规则，一次配置、6 个平台同步对齐。

---

## 快速开始

### 1. 安装

```bash
# 直接运行（无需安装）
npx @siliconoid/agentkit init

# 或全局安装
npm i -g @siliconoid/agentkit
agentkit init
```

### 2. 初始化项目

```bash
# 推荐：零提问，全自动检测
agentkit init --smart

# 交互式：逐步引导，自动填充默认值
agentkit init

# 全量安装：6 平台 + 全部技能包 + 全部 bundle
agentkit init --yes

# 精简模式：仅核心规则，不含技能/工作流
agentkit init --minimal
```

CLI 会自动从你的项目中检测：

- **项目名称 / 描述** — 来自 `package.json` 或 `pyproject.toml`
- **框架** — Next.js Pages/App、React SPA、Vue、NestJS、FastAPI
- **UI 库** — Ant Design、Tailwind CSS（从依赖中识别）
- **已有平台** — 扫描 `CLAUDE.md`、`.cursorrules` 等
- **项目类型** — 前端、后端、全栈（自动创建 `frontend/` + `backend/` 子目录）

#### Init 参数

| 参数            | 说明                                           |
| --------------- | ---------------------------------------------- |
| `--smart`       | 零提问全自动初始化                             |
| `-y, --yes`     | 使用所有默认值，不弹提示                       |
| `--minimal`     | 仅核心规则（01/03/06/07/10），不含技能和工作流 |
| `--force`       | 强制重新初始化                                 |
| `--dry-run`     | 预览将要创建的文件，不实际写入                 |
| `--no-scaffold` | 跳过空目录的项目文件生成                       |

### 3. 审查 & 定制

```bash
# 查看已生成的配置
agentkit list --rules

# 对比本地规则与模板差异
agentkit diff

# 检查配置健康度
agentkit doctor --deep
```

建议优先审查：

1. `.ai/rules/01-project-overview.md` — 技术栈和约束
2. `.ai/rules/03-coding-conventions.md` — 代码风格和模式
3. `.ai/USER-GUIDE.md` — 完整用户手册

### 4. 日常使用

```bash
# 更新模板（非破坏性，仅补充缺失文件）
agentkit update

# 强制覆盖最新模板
agentkit update --force

# 添加新 AI 平台
agentkit add-platform codex

# 添加技能包
agentkit add-skill-pack frontend-design

# 创建自定义技能
agentkit add-skill my-skill -d "技能描述"

# 修改技能后同步到所有平台
agentkit sync
```

---

## Brownfield 模式（已有 AI 配置的项目）

当项目中已有 AI 配置文件（如手写的 `CLAUDE.md`、`.cursorrules` 等），`agentkit init` 会自动检测为 **brownfield 项目**，并提示选择迁移策略：

| 策略                | 说明                                                    | 适用场景                               |
| ------------------- | ------------------------------------------------------- | -------------------------------------- |
| **Absorb**（吸收）  | 提取现有内容到 `20-absorbed-rules.md`，重新生成平台文件 | 统一管理规则，保留已有内容（**推荐**） |
| **Coexist**（共存） | 保留现有文件不动，仅创建 `.ai/rules/` 作为补充          | 不想改动现有配置，先试用               |
| **Replace**（替换） | 备份现有文件后全部替换为 AgentKit 体系                  | 彻底切换到 AgentKit                    |

**非交互模式：** `--smart` / `--yes` 自动选择 Absorb；`--minimal` 自动选择 Coexist

| 行为                   | Absorb           | Coexist          | Replace         |
| ---------------------- | ---------------- | ---------------- | --------------- |
| 备份原文件             | 是               | 否               | 是              |
| 原平台文件             | 备份 → 重新生成  | 保留不动         | 备份 → 重新生成 |
| `.ai/rules/`           | 创建（跳过已有） | 创建（跳过已有） | 清空后重建      |
| `20-absorbed-rules.md` | 自动生成         | 不创建           | 不创建          |

备份位置：`.ai/brownfield-backup/<timestamp>/`

初始化后建议运行 `/agentkit-calibrate` 进行 AI 辅助规则校准。

---

## `/agentkit-calibrate` — AI 辅助规则校准

内置技能，在 AI 编码助手中运行，自动扫描项目实际状态并校准 `.ai/rules/` 中的规则文件。

**典型场景：**

- Brownfield 项目初始化后 — init 生成的规则是模板默认值，需要校准
- 项目技术栈变更后 — 例如从 CSS Modules 迁移到 Tailwind
- AI 生成的代码不符合项目风格 — 说明规则与代码有偏差
- 定期维护 — 随项目演进保持规则一致性

**工作流程：** Discovery → Audit → 用户确认 → Calibrate

> 仅修改 AI 配置文件（`.ai/rules/`、平台文件等），**不会修改项目源码和依赖**。

---

## 支持平台

| 平台        | 根文件                      | 技能目录          | 命令目录                  |
| ----------- | --------------------------- | ----------------- | ------------------------- |
| Claude Code | `CLAUDE.md`                 | `.claude/skills/` | `.claude/commands/`       |
| Cursor      | `.cursor/rules/project.mdc` | —                 | `.cursor/commands/`       |
| Codex       | `AGENTS.md`                 | `.codex/skills/`  | —                         |
| Gemini      | `GEMINI.md`                 | `.gemini/skills/` | `.gemini/commands/*.toml` |
| Antigravity | `.agent/rules.md`           | `.agent/skills/`  | `.agent/workflows/`       |
| Windsurf    | `.windsurfrules`            | —                 | —                         |

---

## 支持框架

| 框架                       | Key            | 特性                                                 |
| -------------------------- | -------------- | ---------------------------------------------------- |
| **React SPA**              | `react-spa`    | Vite + React 18 + react-router-dom + TypeScript      |
| **Next.js (App Router)**   | `nextjs-app`   | Server Components、`'use client'`、Server Actions    |
| **Next.js (Pages Router)** | `nextjs-pages` | Pages Router、`getServerSideProps`、SSR              |
| **Vue**                    | `vue`          | Composition API、`<script setup>`、Pinia、Vue Router |
| **NestJS**                 | `nestjs`       | Fastify、Prisma、PostgreSQL、BullMQ                  |
| **FastAPI**                | `fastapi`      | SQLAlchemy 2.0、Alembic、PostgreSQL、Celery          |
| **Custom**                 | `custom`       | 仅通用基础模板                                       |

### UI 库

| UI 库                     | Key             | 安装的规则                                            |
| ------------------------- | --------------- | ----------------------------------------------------- |
| **Ant Design**            | `antd`          | 08-styling (SCSS)、17-antd、18-pro-components         |
| **Tailwind + shadcn**     | `tailwind`      | 08-styling (Tailwind)、17-shadcn、18-dashboard-shadcn |
| **Ant Design + Tailwind** | `antd-tailwind` | 17-antd、18-pro-components + Tailwind 08-styling      |
| **无**                    | `none`          | 仅基础 08-styling                                     |

---

## 技能包

预置的技能包，`init` 时选择或后续通过 `add-skill-pack` 添加：

| 技能包                        | 适用栈 | 说明                                        |
| ----------------------------- | ------ | ------------------------------------------- |
| `security-best-practices`     | 通用   | 语言/框架安全最佳实践                       |
| `frontend-design`             | 前端   | 生产级前端设计指南                          |
| `next-best-practices`         | 前端   | Next.js 文件约定、RSC、数据模式             |
| `vercel-react-best-practices` | 前端   | React & Next.js 性能优化                    |
| `vercel-composition-patterns` | 前端   | React 组合模式                              |
| `web-design-guidelines`       | 前端   | Web 界面设计规范合规                        |
| `antd-best-practices`         | 前端   | Ant Design + ProComponents + SCSS Modules   |
| `tailwind-best-practices`     | 前端   | Tailwind CSS v4 + shadcn/ui + TanStack      |
| `nestjs-best-practices`       | 后端   | NestJS + Fastify + Prisma + PostgreSQL      |
| `fastapi-best-practices`      | 后端   | FastAPI + SQLAlchemy + Alembic + PostgreSQL |

### 技能 Bundle

| Bundle                    | 说明                                                             | 安装范围           |
| ------------------------- | ---------------------------------------------------------------- | ------------------ |
| **Superpowers** (by obra) | TDD、code-review、brainstorming、调试 — 14 个可组合技能 + agents | 项目 / 全局 / 两者 |

```bash
agentkit add-skill-bundle superpowers --project
agentkit add-skill-bundle superpowers --global   # → ~/.claude/skills/
```

### 工作流包

| 包              | 说明                                  | 适合                       |
| --------------- | ------------------------------------- | -------------------------- |
| **BMAD Method** | PM、架构师、开发、QA agents，46+ 命令 | 架构设计、PRD、Sprint 规划 |

---

## 命令速查

### 项目初始化

| 命令                        | 说明                                            |
| --------------------------- | ----------------------------------------------- |
| `agentkit init [选项]`      | 初始化项目（见 [Init 参数](#init-参数)）        |
| `agentkit update [--force]` | 更新模板（`--force` 覆盖已修改文件）            |
| `agentkit doctor [--deep]`  | 检查配置健康度（`--deep` 检查占位符和同步状态） |

### 配置查看

| 命令                      | 说明                                           |
| ------------------------- | ---------------------------------------------- |
| `agentkit list [--rules]` | 查看配置和已安装组件（`--rules` 显示规则标题） |
| `agentkit diff`           | 对比本地规则与模板版本的差异                   |

### 组件添加

| 命令                                 | 说明                                        |
| ------------------------------------ | ------------------------------------------- |
| `agentkit add-platform <平台>`       | 添加 AI 平台                                |
| `agentkit add-skill-pack <包名>`     | 安装技能包                                  |
| `agentkit add-skill-bundle <id>`     | 安装技能 Bundle（`--global` / `--project`） |
| `agentkit add-skill <名称> [-d ...]` | 创建自定义技能                              |

### 技能 & 包管理

| 命令                              | 说明                                       |
| --------------------------------- | ------------------------------------------ |
| `agentkit sync [--dry] [--clean]` | 同步技能到各平台（`--clean` 清除过期文件） |
| `agentkit install <来源>`         | 从本地路径或 npm 安装包（`--force` 覆盖）  |
| `agentkit remove <名称>`          | 移除已安装的包                             |

### 全局选项

| 选项            | 说明         |
| --------------- | ------------ |
| `--verbose`     | 显示详细输出 |
| `--quiet`       | 静默模式     |
| `-V, --version` | 显示版本号   |

---

## 生成结构

```
your-project/
├── .ai/                           # 规则单一数据源
│   ├── rules/                     # 规则文件（13 基础 + 框架/UI 覆盖）
│   │   ├── 01-project-overview.md
│   │   ├── 02-architecture.md
│   │   ├── ...
│   │   └── 13-ai-agent.md
│   ├── skills/                    # 可移植技能定义
│   │   ├── adr/                   #   架构决策记录
│   │   ├── agentkit-calibrate/    #   AI 辅助规则校准
│   │   ├── devlog/                #   AI 优化的 Changelog
│   │   └── wrap-up/               #   任务结束时同步记忆
│   ├── decisions/                 # ADR 归档
│   ├── changelog/                 # 月度变更日志
│   ├── memory/                    # 调试模式、已知问题
│   ├── agentkit.json              # CLI 配置
│   ├── QUICK-START.md             # 快速入门（自动生成）
│   └── USER-GUIDE.md             # 用户手册（自动生成）
├── .specs/                        # PRD、设计、Epic、Story（/spec 管理）
├── CLAUDE.md                      # Claude Code 根文件
├── AGENTS.md                      # Codex 根文件
├── GEMINI.md                      # Gemini 根文件
├── .windsurfrules                 # Windsurf（合并规则）
├── .cursor/rules/project.mdc     # Cursor 根文件
├── .agent/rules.md                # Antigravity 根文件
├── .claude/skills/                # 技能（可移植 + 技能包 + bundle）
├── .claude/commands/bmad/         # BMAD 工作流命令
└── (其他平台目录...)
```

> 仅为你选择的平台创建对应的平台文件。

---

## 架构

### 规则分层

规则按层叠加，后者覆盖前者：

```
base → framework → UI library → CSS framework → user custom (20+)
```

每个基础规则文件带有 `<!-- tech-stack: xxx -->` 元数据标签：

| 标签        | 文件                                      | 说明             |
| ----------- | ----------------------------------------- | ---------------- |
| `universal` | 01–05, 09–13                              | 适用于所有技术栈 |
| `frontend`  | 06 (TypeScript), 07 (React), 08 (Styling) | 前端专用         |

### 工作原理

1. **`.ai/rules/`** 是所有项目规则的唯一数据源
2. **根文件**（`CLAUDE.md`、`AGENTS.md` 等）通过 `@` 引用 `.ai/rules/`
3. **规则分层**：base → framework → UI library → CSS framework → user custom (20+)
4. **`.ai/skills/`** 定义可移植技能（`manifest.yaml` + `skill.md`）
5. **`sync`** 为各平台生成适配文件（Claude 的 SKILL.md、Gemini 的 .toml 等）
6. **Windsurf** 获取合并后的 `.windsurfrules`（不支持目录引用）

### CLI Router

所有 CLI 命令在 `lib/router.mjs` 中声明式定义。添加新命令只需 3 步：

1. 在 `lib/commands/<name>.mjs` 创建处理函数
2. 在 `COMMANDS` 数组中添加条目
3. 完成 — `registerCommands()` 自动注册

### 自定义技能包

在 `templates/skills/<pack-name>/` 放一个带 YAML frontmatter 的 `SKILL.md`：

```markdown
---
name: my-new-pack
description: 这个技能包的用途
---

技能内容...
```

CLI 自动发现，无需改代码。

---

## License

MIT