# Framework AI Doc

让 AI 编码助手（Claude、Cursor 等）能够访问前端框架的官方文档。

**现已支持多框架！** 🎉

> 💡 **提示**：支持 `AGENTS.md`（Cursor 推荐）和 `CLAUDE.md` 两种文件格式

## 支持的框架

### 完整版本匹配支持

这些框架的文档可以精确匹配你项目的版本：

- ✅ **Next.js** - The React Framework for the Web
- ✅ **Nuxt** - The Intuitive Vue Framework  
- ✅ **Vite** - Next Generation Frontend Tooling

### 使用最新文档

这些框架的官方文档在独立仓库中，工具会下载最新版本的文档：

- ⚠️ **React** - A JavaScript library for building user interfaces（使用最新文档）
- ⚠️ **Vue** - The Progressive JavaScript Framework（使用最新文档）

> **注意**：React 和 Vue 的文档在独立的仓库中，无法按版本号获取历史文档。工具会下载最新的文档内容，这对大多数使用场景已经足够。

## 为什么要做这个？

AI 编码助手的训练数据有时效性，对于快速迭代的前端框架，它可能不了解最新的 API 和特性。与其让 AI 靠过时的知识瞎猜，不如直接给它看官方文档。

这个工具会自动：
1. 检测你项目中使用的框架版本
2. 下载对应版本的官方文档
3. 生成文档索引注入到 `AGENTS.md`（Cursor）或 `CLAUDE.md`（Claude Desktop）
4. 支持多个框架的文档索引共存

## 快速开始

### 自动检测并安装（推荐）

在项目根目录执行，工具会自动检测已安装的框架：

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

### 指定单个框架

```bash
# Next.js 项目
npx @gorden301jiawei/framework-ai-doc --framework nextjs

# React 项目
npx @gorden301jiawei/framework-ai-doc --framework react

# Vue 项目
npx @gorden301jiawei/framework-ai-doc --framework vue

# Nuxt 项目
npx @gorden301jiawei/framework-ai-doc --framework nuxt
```

### 安装所有检测到的框架

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

### 指定版本和输出文件

```bash
# 指定版本（会提示选择输出文件）
npx @gorden301jiawei/framework-ai-doc --framework nextjs --version 15.1.3

# 跳过提示，直接使用 CLAUDE.md
npx @gorden301jiawei/framework-ai-doc --framework react --md CLAUDE.md

# 跳过提示，直接使用 AGENTS.md
npx @gorden301jiawei/framework-ai-doc --framework vue --version 3.4.0 --md AGENTS.md
```

> **注意**：如果不指定 `--md` 参数，工具会提示你选择 AGENTS.md 或 CLAUDE.md

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

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

## 使用场景

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

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

工具会检测到 Next.js，下载文档到 `.next-docs/`，并在 `AGENTS.md` 中添加索引。

### 场景 2：React + Vite 项目

```bash
# 交互式选择多个框架
npx @gorden301jiawei/framework-ai-doc

# 或者分别安装
npx @gorden301jiawei/framework-ai-doc --framework react
npx @gorden301jiawei/framework-ai-doc --framework vite
```

两个框架的文档索引会共存在同一个 `AGENTS.md`（或 `CLAUDE.md`）文件中：

```markdown
<!-- REACT-AGENTS-MD-START -->[React Docs Index]|...<!-- REACT-AGENTS-MD-END -->

<!-- VITE-AGENTS-MD-START -->[Vite Docs Index]|...<!-- VITE-AGENTS-MD-END -->
```

### 场景 3：Nuxt 项目（Vue + Nuxt）

```bash
# 自动安装所有检测到的框架
npx @gorden301jiawei/framework-ai-doc --all
```

工具会同时安装 Vue 和 Nuxt 的文档。

## 工作原理

1. **自动检测版本**：从 `package.json` 中读取框架版本（支持 monorepo）
2. **克隆文档**：使用 Git sparse-checkout 只下载文档目录，避免下载整个仓库
3. **生成索引**：创建压缩的文档目录索引
4. **注入标记**：在 MD 文件中插入带有唯一标记的索引块
5. **多框架共存**：每个框架使用独立的标记，互不干扰

## 命令行参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `--framework <name>` | 指定框架名称 | `--framework nextjs` |
| `--version <version>` | 指定框架版本 | `--version 15.1.3` |
| `--md <path>` | 指定输出文件（不提供则提示选择） | `--md AGENTS.md` |
| `--list` | 列出所有支持的框架 | `--list` |
| `--all` | 安装所有检测到的框架 | `--all` |

## 更新文档

当框架升级后，重新运行相同的命令即可更新文档：

```bash
# 更新 Next.js 文档
npx @gorden301jiawei/framework-ai-doc --framework nextjs

# 更新所有框架文档
npx @gorden301jiawei/framework-ai-doc --all
```

工具会自动检测新版本并更新对应的索引块，不影响其他框架的索引。

## 目录结构

运行后，项目中会生成：

```
your-project/
├── .next-docs/          # Next.js 文档
├── .react-docs/         # React 文档
├── .vue-docs/           # Vue 文档
├── .nuxt-docs/          # Nuxt 文档
├── .vite-docs/          # Vite 文档
├── AGENTS.md            # 包含所有框架索引的文件（或 CLAUDE.md）
└── .gitignore           # 自动添加文档目录到忽略列表
```

## 向后兼容

如果你之前使用的是 1.x 版本（仅支持 Next.js），现在仍然可以使用相同的命令：

```bash
# 仍然有效，只会安装 Next.js 文档
npx @gorden301jiawei/framework-ai-doc
npx @gorden301jiawei/framework-ai-doc --version 15.1.3 --md CLAUDE.md
```

## 常见问题

### Q: 文档文件会被提交到 Git 吗？

不会。工具会自动在 `.gitignore` 中添加文档目录（如 `.next-docs/`、`.react-docs/` 等）。

### Q: 可以同时安装多个框架的文档吗？

可以！每个框架的索引使用独立的标记，可以安全地共存在同一个 MD 文件中。

### Q: 已有的 CLAUDE.md 或 AGENTS.md 内容会被覆盖吗？

不会。工具只会添加或更新框架索引块，其他内容保持不变。

### Q: 如何在非交互模式下直接指定输出文件？

使用 `--md` 参数：

```bash
# 非交互，直接写入 AGENTS.md
npx @gorden301jiawei/framework-ai-doc --framework nextjs --md AGENTS.md

# 非交互，直接写入 CLAUDE.md
npx @gorden301jiawei/framework-ai-doc --all --md CLAUDE.md
```

如果不提供 `--md` 参数，工具会提示你选择文件。

### Q: 支持 monorepo 吗？

支持。工具会自动扫描 workspace 中的所有包，找到使用框架的版本。

### Q: 为什么 React 和 Vue 使用最新文档？

React 和 Vue 的官方文档在独立的仓库中（react.dev 和 vuejs/docs），这些仓库不按版本维护历史文档。工具会下载 main 分支的最新文档，这对大多数使用场景已经足够，因为：

1. React 和 Vue 的 API 相对稳定
2. 文档通常会标注 API 的版本要求
3. 最新文档包含最佳实践和完整的 API 说明

如果你需要特定版本的文档，建议：
- **Next.js 项目**：使用 Next.js 文档（版本匹配）
- **Nuxt 项目**：使用 Nuxt 文档（版本匹配）+ Vue 最新文档

### Q: 如何添加新的框架支持？

工具采用插件化架构，可以轻松添加新框架。查看 `src/frameworks/configs.ts` 了解如何添加配置。

## 贡献

欢迎提交 Issue 和 Pull Request！

如果你希望添加新的框架支持，请在 Issue 中说明。

## License

MIT

## 相关链接

- [GitHub 仓库](https://github.com/gorden301/next-ai-doc)
- [npm 包](https://www.npmjs.com/package/@gorden301jiawei/framework-ai-doc)