# 使用示例

## 场景 1：纯 Next.js 项目

### 自动检测并安装

```bash
cd my-nextjs-app
npx @gorden301jiawei/framework-ai-doc
```

**结果：**
- 检测到 Next.js v15.1.0
- 下载文档到 `.next-docs/`
- 在 `CLAUDE.md` 中生成索引

**CLAUDE.md 内容：**

```markdown
<!-- NEXT-AGENTS-MD-START -->[Next.js Docs Index]|root: ./.next-docs|github: https://github.com/vercel/next.js/tree/v15.1.0/docs|...<!-- NEXT-AGENTS-MD-END -->
```

---

## 场景 2：React + Vite 项目

### 交互式安装多个框架

```bash
cd my-react-app
npx @gorden301jiawei/framework-ai-doc
```

**交互界面：**

```
📚 Framework Documentation Tool

   Detected frameworks in your project:
   - React (18.3.0)
   - Vite (5.2.0)

? Select frameworks (space to select, enter to confirm)
  ◉ React (detected: v18.3.0)
  ◉ Vite (detected: v5.2.0)

? React version: 18.3.0
? Vite version: 5.2.0
? Target markdown file: CLAUDE.md
```

**结果：**
- `.react-docs/` - React 文档
- `.vite-docs/` - Vite 文档
- `CLAUDE.md` - 包含两个框架的索引

**CLAUDE.md 内容：**

```markdown
<!-- REACT-AGENTS-MD-START -->[React Docs Index]|root: ./.react-docs|...<!-- REACT-AGENTS-MD-END -->

<!-- VITE-AGENTS-MD-START -->[Vite Docs Index]|root: ./.vite-docs|...<!-- VITE-AGENTS-MD-END -->
```

---

## 场景 3：指定单个框架

### 只安装 Vue 文档

```bash
cd my-vue-app
npx @gorden301jiawei/framework-ai-doc --framework vue
```

**结果：**
- 自动检测 Vue 版本（如 3.4.21）
- 下载 Vue 文档到 `.vue-docs/`
- 在 `CLAUDE.md` 中添加 Vue 索引

### 指定版本

```bash
npx @gorden301jiawei/framework-ai-doc --framework vue --version 3.4.0
```

### 使用 AGENTS.md

```bash
npx @gorden301jiawei/framework-ai-doc --framework vue --md AGENTS.md
```

---

## 场景 4：Nuxt 项目

### 自动安装所有框架

```bash
cd my-nuxt-app
npx @gorden301jiawei/framework-ai-doc --all
```

**检测结果：**
- Vue 3.4.21
- Nuxt 3.11.0

**安装结果：**
- `.vue-docs/` - Vue 文档
- `.nuxt-docs/` - Nuxt 文档
- `CLAUDE.md` - 包含两个框架的索引

---

## 场景 5：Monorepo 项目

### 项目结构

```
my-monorepo/
├── packages/
│   ├── web/          # Next.js 15.1.0
│   ├── admin/        # React 18.3.0 + Vite
│   └── mobile/       # React Native
├── package.json
└── pnpm-workspace.yaml
```

### 在根目录运行

```bash
cd my-monorepo
npx @gorden301jiawei/framework-ai-doc --all
```

**工具会自动：**
1. 扫描所有 workspace 包
2. 检测到 Next.js、React、Vite
3. 安装所有框架的文档

**结果：**

```
my-monorepo/
├── .next-docs/      # Next.js 15.1.0
├── .react-docs/     # React 18.3.0
├── .vite-docs/      # Vite 5.2.0
├── CLAUDE.md        # 包含三个框架的索引
└── .gitignore       # 自动添加文档目录
```

---

## 场景 6：更新文档

### 升级框架后更新文档

假设你升级了 Next.js：

```bash
# 升级前：Next.js 14.2.0
# 升级后：Next.js 15.1.0

# 更新文档
npx @gorden301jiawei/framework-ai-doc --framework nextjs
```

**工具会：**
1. 检测到新版本 15.1.0
2. 删除旧的 `.next-docs/` 目录
3. 下载 v15.1.0 的文档
4. 更新 `CLAUDE.md` 中的 Next.js 索引块
5. **其他框架的索引保持不变**

---

## 场景 7：查看支持的框架

### 列出所有支持的框架

```bash
npx @gorden301jiawei/framework-ai-doc --list
```

**输出：**

```
📚 Supported Frameworks:

   Next.js
   ID: nextjs
   The React Framework for the Web
   Package: next

   React
   ID: react
   A JavaScript library for building user interfaces
   Package: react

   Vue
   ID: vue
   The Progressive JavaScript Framework
   Package: vue

   Nuxt
   ID: nuxt
   The Intuitive Vue Framework
   Package: nuxt

   Vite
   ID: vite
   Next Generation Frontend Tooling
   Package: vite
```

---

## 场景 8：CI/CD 集成

### 在 CI 中自动生成文档

**package.json：**

```json
{
  "scripts": {
    "prepare": "npx @gorden301jiawei/framework-ai-doc --all --md AGENTS.md || true"
  }
}
```

**GitHub Actions：**

```yaml
name: Update Docs

on:
  push:
    paths:
      - 'package.json'
      - 'package-lock.json'

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
      - run: npm install
      - run: npx @gorden301jiawei/framework-ai-doc --all
      - uses: stefanzweifel/git-auto-commit-action@v4
        with:
          commit_message: "docs: update framework documentation"
          file_pattern: "CLAUDE.md"
```

---

## 场景 9：移除框架文档

如果你不再需要某个框架的文档：

```bash
# 手动删除文档目录
rm -rf .react-docs

# 编辑 CLAUDE.md，删除对应的索引块
# 删除 <!-- REACT-AGENTS-MD-START --> 到 <!-- REACT-AGENTS-MD-END --> 之间的内容
```

或者重新运行工具只安装需要的框架。

---

## 场景 10：自定义配置

### 为新项目创建配置模板

在你的新项目中，可以提前准备好 `CLAUDE.md`：

```markdown
# My Project

这是我的项目说明...

## 项目架构

- 前端：Next.js
- 状态管理：Redux
- UI 库：Material-UI

<!-- NEXT-AGENTS-MD-START --><!-- NEXT-AGENTS-MD-END -->
```

运行工具后，索引会自动填充到标记之间。

---

## 常见命令速查

```bash
# 自动检测并交互式安装
npx @gorden301jiawei/framework-ai-doc

# 安装所有检测到的框架（非交互）
npx @gorden301jiawei/framework-ai-doc --all

# 指定单个框架
npx @gorden301jiawei/framework-ai-doc --framework nextjs

# 指定版本
npx @gorden301jiawei/framework-ai-doc --framework react --version 18.3.0

# 指定输出文件
npx @gorden301jiawei/framework-ai-doc --framework vue --md AGENTS.md

# 组合使用
npx @gorden301jiawei/framework-ai-doc --framework nuxt --version 3.11.0 --md AGENTS.md

# 列出支持的框架
npx @gorden301jiawei/framework-ai-doc --list
```

---

## 注意事项

1. **文档目录不会被提交**：工具会自动添加到 `.gitignore`
2. **多次运行是安全的**：重复运行只会更新索引，不影响其他内容
3. **支持多框架共存**：每个框架使用独立的标记，互不干扰
4. **版本匹配很重要**：确保下载的文档版本与项目版本一致
5. **Monorepo 自动检测**：支持 npm/yarn/pnpm workspace