@cosco-team/ai-kit (v2.0)

团队级 AI 效能工程套件 — 支持 Web、移动端原生、微信小程序、UniApp 多平台开发治理

基于企业级 Monorepo 治理实践（模块化 .cursor/rules、SSOT 规范文档、Guard 脚本、双层 Husky）抽象而来，可一键接入新项目或存量项目。

npm 地址：https://www.npmjs.com/package/@cosco-team/ai-kit

一、核心特性

| 功能 | 说明 | |------|------| | 多平台支持 | Web / React Native / Flutter / 微信小程序 / UniApp | | 引导式安装 | npx ai-kit-2 init 交互式选择平台和配置 | | 空文件夹初始化 | 自动检测空目录并引导创建 package.json | | Cursor 规则集成 | 模块化 AI 协作规则（.mdc 格式） | | Git 钩子自动化 | commitlint + husky 预提交检查 | | 配置分区管理 | locked / configurable / generated 三级约束 | | 发版记录 | release-it + releases/*.json + 贡献者统计 | | 团队人员分组 | config/team-members.json 定义权限组 | | CODEOWNERS 生成 | 从人员配置自动生成 GitHub CODEOWNERS | | 配置备份 | 覆盖已有文件前自动备份到 .ai-kit-backups/ |

二、快速开始

2.1 全新项目（空文件夹）

# 进入空目录
cd my-new-project

# 交互式引导安装
npx ai-kit-2 init

# 非交互式模式（指定平台）
npx ai-kit-2 init --yes --platform web
npx ai-kit-2 init --yes --platform mobile-native
npx ai-kit-2 init --yes --platform wechat-miniprogram
npx ai-kit-2 init --yes --platform uniapp

2.2 现有项目

# 使用传统命令（保持向后兼容）
npx @team/ai-kit init --profile single --yes
npx @team/ai-kit init --profile monorepo --yes

三、支持的 Platform

🌐 Web / Frontend

• 适用场景: React, Vue, Angular 等前端项目
• Profile: single / monorepo
• 模板: Vite/Webpack 配置、ESLint 规则、CI/CD 流水线

📱 Mobile Native

• 适用场景: React Native, Flutter 原生移动应用
• Profile: mobile-native
• 模板: Metro 配置、React Native/Flutter 规则、性能优化指南

💬 WeChat Mini Program

• 适用场景: 微信小程序开发
• Profile: wechat-miniprogram
• 模板: project.config.json、小程序 API 规则、分包配置

📲 UniApp

• 适用场景: 跨平台应用（H5 + App + 多小程序）
• Profile: uniapp
• 模板: manifest.json、pages.json、条件编译规则

四、CLI 命令

ai-kit-2 (新版 - 推荐)

npx ai-kit-2 <command> [options]

Commands:
  init              交互式引导安装（推荐）
  backup            备份核心治理文件
  doctor            检查项目就绪状态
  zones             查看配置分区清单

Options:
  -y, --yes         非交互模式
  --profile <name>  强制 profile: single | monorepo
  --platform <name> 强制平台：web | mobile-native | wechat-miniprogram | uniapp
  --dry-run         预览变更不写入
  --skip-patch      跳过 package.json 补丁
  --name <name>     项目名称（用于空目录）
  --version <ver>   项目版本
  --description <desc> 项目描述

ai-kit (旧版 - 向后兼容)

npx @team/ai-kit <command> [options]

Commands:
  init       Deploy rules, hooks, docs, and configs
  backup     Backup specific files to .ai-kit-backups/
  doctor     Check project readiness
  zones      Print configuration zones summary

五、项目结构

新安装后新增内容

my-project/
├── .cursor/rules/              # AI 规则（index、git、协作、安全边界、平台特定）
├── .cursor/skills/             # Skills 模板（调试、性能、状态管理等）
├── config/
│   └── team-members.json       # 团队人员分组
├── docs/spec/                  # 强制规范（AI 不可违反）
├── docs/CONTEXT.md             # 业务上下文（团队填写）
├── docs/platform-mobile.md     # 移动端平台指南（仅 mobile-native）
├── docs/platform-wechat.md     # 微信小程序指南（仅 wechat-miniprogram）
├── docs/platform-uniapp.md     # UniApp 指南（仅 uniapp）
├── .github/                    # PR 模板、CODEOWNERS、CI
├── .husky/                     # Git 钩子
├── scripts/                    # 发版记录、guard、CODEOWNERS 生成
├── prompts/                    # AI 提示词模板
├── releases/                   # 发版记录与 ADR
├── .ai-kit-backups/            # 配置备份
└── platform-specific/          # 平台特定配置
    ├── mobile/                 # React Native / Flutter 配置
    ├── miniprogram/            # 微信小程序配置
    └── uniapp/                 # UniApp 配置

六、平台特定配置

6.1 移动端 (React Native / Flutter)

# 安装后配置
npx react-native upgrade        # React Native
flutter pub get                 # Flutter

# 关键配置文件
metro.config.js                 # Metro bundler 配置
.react-native.config.js         # React Native 配置

6.2 微信小程序

# 打开微信开发者工具
# 配置 project.config.json 中的 AppID

# 关键配置文件
project.config.json             # 小程序配置
tsconfig.miniprogram.json       # TypeScript 配置
eslint.wechat.js                # ESLint 配置

6.3 UniApp

# CLI 方式
npx degit dcloudio/uni-preset-vue my-uniapp-app
cd my-uniapp-app
pnpm install

# HBuilderX 导入项目

# 关键配置文件
manifest.json                   # 应用配置
pages.json                      # 页面路由配置
vite.uniapp.config.js           # Vite 配置

七、团队接入指南

7.1 首次接入（5 步）

# 1. 初始化
npx ai-kit-2 init --yes --platform <web|mobile-native|wechat-miniprogram|uniapp>

# 2. 安装依赖
pnpm install   # 或 npm/yarn install

# 3. 初始化 Husky
pnpm exec husky init

# 4. 填写团队配置
#    - config/team-members.json → 补充各组 GitHub 用户名
#    - docs/CONTEXT.md          → 填写业务背景

# 5. 生成 CODEOWNERS
node scripts/generate-codeowners.js

7.2 团队人员配置

config/team-members.json 定义分组与权限。前端架构组永远包含 zhanglichen。

| 分组 key | 名称 | 职责 | 默认成员 | |----------|------|------|----------| | frontend-architecture | 前端架构组 | 治理配置、架构评审、发版审批 | zhanglichen（固定） | | frontend-development | 前端开发组 | 日常功能开发 | 待填写 | | frontend-temporary | 前端临时开发组 | POC、短期需求 | 待填写 | | frontend-hotfix | 前端修复组 | 生产 hotfix | 待填写 | | backend-deploy | 后端查看部署组 | 部署配置只读/审查 | 待填写 | | qa | 测试组 | 测试用例、E2E | 待填写 | | readonly | 其他只读组 | 只读，不可 push | — |

八、配置分区（AI 约束）

| 分区 | 含义 | AI 行为 | |------|------|---------| | locked | 治理 SSOT | 禁止修改（除非用户 /admin） | | configurable | 团队可定制 | 建议后询问用户 | | generated | 脚本输出 | 禁止手改 |

详见目标项目 docs/spec/02-config-zones.md。

九、常用命令

# 预览变更
npx ai-kit-2 init --dry-run

# 手动备份治理文件
npx ai-kit backup

# 检查就绪状态
npx ai-kit doctor

# 查看配置分区
npx ai-kit zones

# 发版
npm run release

# 刷新 AI 上下文
npm run ai:context

十、升级指南

# 升级到最新版本
npx @cosco-team/ai-kit@latest init

# 旧配置自动备份到 .ai-kit-backups/
# 无需手动迁移

十一、相关文档

| 文档 | 说明 | |------|------| | docs/CONFIGURATION-GUIDE.md | 什么可以改、什么不能改 | | docs/AI-CONSTRAINTS.md | 给 AI 工具的约束条款 | | docs/GOVERNANCE.md | 治理模型与实践 | | docs/PUBLISH.md | 发布流程 |

十二、版本更新日志

v2.0.0（当前版本，未发布）

🆕 = 新增功能 | 🔧 = 改进优化

| 类型 | 功能 | 说明 | |------|------|------| | 🆕 | 多平台支持 | 新增 Mobile Native（React Native / Flutter）、微信小程序、UniApp 三大平台支持 | | 🆕 | 新版 CLI ai-kit-2 | 全新交互式引导安装命令，支持平台选择和 profile 选择 | | 🆕 | 平台选择向导 | init 命令交互式选择目标平台（Web / Mobile / WeChat / UniApp） | | 🆕 | 空目录初始化 | 自动检测空目录并引导创建 package.json，支持 --name、--version、--description 参数 | | 🆕 | 移动端 Cursor 规则 | 新增 mobile-development.mdc、react-native.mdc、flutter.mdc、mobile-security.mdc | | 🆕 | 移动端 Skills | 新增 react-native-debug、mobile-performance、native-module-integration 技能模板 | | 🆕 | 微信小程序模板 | 新增 miniprogram-development.mdc、wechat-sdk.mdc、miniprogram-ui.mdc 规则及 project.config.json 等配置 | | 🆕 | UniApp 模板 | 新增 uniapp-development.mdc、uniapp-api.mdc、uniapp-platform-diff.mdc 规则及 vite.uniapp.config.js 等配置 | | 🆕 | 平台特定 CI | 各平台独立的 GitHub Actions 工作流模板 | | 🆕 | --platform 参数 | 非交互模式下指定平台：web / mobile-native / wechat-miniprogram / uniapp | | 🔧 | 配置分区扩展 | 新增 reference 分区（仅复制模板，不部署到项目根目录） | | 🔧 | 向后兼容 | 旧版 ai-kit CLI 保留，ai-kit-2 为推荐入口 |

v1.0.0（2026-05-22 发布）

| 类型 | 功能 | 说明 | |------|------|------| | 🆕 | Web 项目支持 | 支持 single / monorepo 两种 profile | | 🆕 | Cursor 规则集成 | 模块化 AI 协作规则（.mdc 格式）：index、git-conventions、ai-collaboration、security-boundaries | | 🆕 | Git 钩子自动化 | Husky + commitlint 预提交检查（pre-commit / commit-msg / pre-push / post-merge） | | 🆕 | 配置分区管理 | locked / configurable / generated 三级约束体系 | | 🆕 | 团队人员分组 | config/team-members.json 定义权限组（架构组、开发组、修复组、测试组等） | | 🆕 | CODEOWNERS 生成 | 从人员配置自动生成 GitHub CODEOWNERS 文件 | | 🆕 | 配置备份 | 覆盖已有文件前自动备份到 .ai-kit-backups/ | | 🆕 | 发版管理 | release-it 集成 + releases/decisions.md 发版记录 | | 🆕 | CLI 命令 | init / backup / doctor / zones 四大命令 | | 🆕 | AI 提示词模板 | 5 个内置 prompts（组件生成、代码审查、重构、自动测试、决策总结） | | 🆕 | GitHub 集成 | PR 模板、CI 工作流、CODEOWNERS | | 🆕 | 规范文档 | docs/spec/ 下 4 份强制规范文档（治理模型、AI 约束、配置分区、质量门禁） |

十三、反馈与联系

如有问题、建议或 Bug 反馈，请发送邮件至：

📧 [email protected]

License

MIT