# ai-coding-spec

**Repository Path**: mengfly/ai-coding-spec

## Basic Information

- **Project Name**: ai-coding-spec
- **Description**: 企业级 AI 编程规范层。一份 config.json，同步生成设计 Token、业务术语、组件库清单，注入 Cursor / Trae 等 AI 编辑器，让 AI 生成的代码自动符合企业规范。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-08-28
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @ai-scaffold/core

> 企业级 AI 前端脚手架 — 让 Cursor/Trae 学会你的组件库、设计规范与业务术语。

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
[![React](https://img.shields.io/badge/React-18+-61DAFB?logo=react)](https://react.dev)
[![Vue](https://img.shields.io/badge/Vue-3+-4FC08D?logo=vuedotjs)](https://vuejs.org)
[![TypeScript](https://img.shields.io/badge/TypeScript-5+-317C6?logo=typescript)](https://www.typescriptlang.org)
[![Tailwind CSS](https://img.shields.io/badge/Tailwind-3+-06B6D4?logo=tailwindcss)](https://tailwindcss.com)

---

## 项目定位

这是一个 **npm 包形态的 AI 配置层**，安装到你的现有前端项目后，会在项目根目录生成一组 `.ais/` 配置与 `.cursorrules`/`.traerules` 规则文件。Cursor、Trae 等 AI 编程工具会据此理解你的：

- 设计 Token（颜色、间距、字体、圆角、阴影等）
- 业务术语表（变量命名、状态枚举、文案规范）
- 组件组合模式（列表页、表单页、弹窗等常见模式）
- 框架编码规范（React / Vue 的命名、类型、样式约定）

它不会侵入你的业务代码编译流程，也不依赖特定 UI 组件库。

---

## 快速开始

### 1. 安装

```bash
npm install @ai-scaffold/core --save-dev
# 或
pnpm add -D @ai-scaffold/core
```

安装完成后，`postinstall` 钩子会自动在项目根目录执行一次初始化：

- 创建 `.ais/` 配置目录
- 生成 `.cursorrules` / `.traerules` 规则文件
- 自动检测项目依赖中的 `react` / `vue`，复制对应框架的编码规范

### 2. 手动初始化（可选）

如果自动初始化被跳过（例如 `.ais/` 已存在），或你需要重新生成配置，可以手动执行：

```bash
npx ai-scaffold init
```

这会创建：

```text
your-project/
├── .ais/
│   ├── config.json              # 统一配置：theme / glossary / patterns / outputPaths
│   ├── knowledge/               # 给 AI 读取的 Markdown 知识库
│   │   ├── design-tokens.md     # 设计 Token 规范
│   │   ├── glossary.md          # 业务术语表
│   │   ├── component-patterns.md # UI 模式库
│   │   ├── react/               # 自动检测框架：React
│   │   │   └── coding-standards.md
│   │   └── vue/                 # 自动检测框架：Vue
│   │       └── coding-standards.md
│   ├── templates/               # 由 extract 生成的纯净 UI 模板
│   │   ├── react/
│   │   └── vue/
│   └── theme/                   # 由 sync 生成的设计 Token 产物
│       ├── tokens.css           # CSS 变量
│       └── tailwind.config.js   # Tailwind 扩展配置
├── .cursorrules                 # Cursor IDE 规则
└── .traerules                   # Trae IDE 规则
```

### 3. 填写企业配置

编辑 `.ais/config.json`，填入你的品牌色、业务术语、常用 UI 模式等。

### 4. 同步生成知识库与样式产物

```bash
npx ai-scaffold sync
```

命令会根据 `.ais/config.json` 生成以下内容：

- `.ais/knowledge/design-tokens.md` — AI 可读的设计 Token 说明
- `.ais/knowledge/glossary.md` — 业务术语表
- `.ais/knowledge/component-patterns.md` — UI 模式库
- `.ais/theme/tokens.css` — CSS 变量（如 `--color-primary-500`、`--space-4`）
- `.ais/theme/tailwind.config.js` — 引用上述 CSS 变量的 Tailwind 扩展配置

输出路径可在 `.ais/config.json` 的 `outputPaths` 中自定义，例如：

```json
{
  "outputPaths": {
    "tokensCss": "src/styles/tokens.css",
    "tailwindConfig": "tailwind.config.js"
  }
}
```

### 5. 从业务代码提取纯净模板

当你写出一个可复用的 UI 结构后，可以半自动地提取为模板。命令会根据文件扩展名自动推断 React / Vue，也支持 `--framework` 显式指定：

```bash
# React
npx ai-scaffold extract --file src/components/UserManagement.tsx

# Vue
npx ai-scaffold extract --file src/components/UserManagement.vue
npx ai-scaffold extract --file src/components/UserCard.vue --framework vue
```

命令会输出 `.ais/templates/{react|vue}/UserManagement.template.{tsx|vue}` 及说明文档，自动完成：

- 剥离 API 调用、业务 Hook / 路由 / 业务函数、业务状态判断
- 提取硬编码中文文案为 Props
- 将 Tailwind 硬编码色值/间距替换为 `tokens.css` 中的 CSS 变量

---

## 仓库结构

本仓库是一个 monorepo，核心代码位于 `packages/core`：

```text
Enterprise_AI_Frontend_Scaffold/
├── README.md                    # 本文件
├── LICENSE
├── package.json                 # monorepo root
├── .gitignore
└── packages/
    └── core/
        ├── README.md            # 包级文档
        ├── package.json         # @ai-scaffold/core
        ├── tsconfig.json
        ├── src/
        │   ├── cli.ts
        │   └── commands/
        │       ├── init.ts       # npx ai-scaffold init
        │       ├── sync.ts       # npx ai-scaffold sync
        │       ├── extract-react.ts # npx ai-scaffold extract (React)
        │       └── extract-vue.ts   # npx ai-scaffold extract (Vue)
        ├── templates/            # init 时复制到用户项目的模板
        │   ├── config.json
        │   ├── dot-cursorrules.txt
        │   ├── dot-traerules.txt
        │   └── knowledge/
        │       ├── design-tokens.md
        │       ├── glossary.md
        │       ├── component-patterns.md
        │       ├── react/
        │       │   └── coding-standards.md
        │       └── vue/
        │           └── coding-standards.md
        ├── tests/                # 单元测试与测试 fixture
        │   ├── fixtures/
        │   │   ├── UserManagement.tsx
        │   │   └── UserManagement.vue
        │   ├── extract-react.test.ts
        │   └── extract-vue.test.ts
        └── dist/                 # 构建产物
```

---

## 开发

```bash
# 安装依赖
npm install

# 构建 core 包
cd packages/core && npm run build

# 运行单元测试（覆盖 React / Vue extract 核心逻辑）
cd packages/core && npm test

# 本地测试 CLI
cd /path/to/your-project
node /path/to/this-repo/packages/core/dist/cli.js init
```

---

## 状态与路线图

当前版本：`@ai-scaffold/core@0.1.0`

- [x] 基础 CLI 结构：`init` / `sync` / `extract`
- [x] React 项目支持
- [x] `sync` 命令生成 `tokens.css` 与 `tailwind.config.js`
- [x] 框架自动检测（React / Vue）
- [x] Vue 项目 `extract` 支持
- [x] 单元测试覆盖（React / Vue extract）
- [ ] 模板质量校验命令

---

## 设计原则

1. **零侵入**：不修改宿主项目的构建配置和业务源码。
2. **配置驱动**：企业只需维护一份 `.ais/config.json`。
3. **包与资产分离**：包只提供 CLI 能力，项目专属资产存放在 `.ais/` 目录。
4. **业务零侵入模板**：`ai-scaffold extract` 产出的模板不含 API、硬编码文案、业务状态判断。

---

## License

MIT © Enterprise AI Frontend Scaffold