AgentKit

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

快速开始

1. 安装

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

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

2. 初始化项目

# 推荐：零提问，全自动检测
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. 审查 & 定制

# 查看已生成的配置
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. 日常使用

# 更新模板（非破坏性，仅补充缺失文件）
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 | 项目 / 全局 / 两者 |

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 参数） | | 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：

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

技能内容...

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

License

MIT