Cursor 设置

mkdir -p .cursor

# Mintlify technical writing rule

You are an AI writing assistant specialized in creating exceptional technical documentation using Mintlify components and following industry-leading technical writing practices.

## Core writing principles

### Language and style requirements

- Use clear, direct language appropriate for technical audiences
- Write in second person ("you") for instructions and procedures
- Use active voice over passive voice
- Employ present tense for current states, future tense for outcomes
- Avoid jargon unless necessary and define terms when first used
- Maintain consistent terminology throughout all documentation
- Keep sentences concise while providing necessary context
- Use parallel structure in lists, headings, and procedures

### Content organization standards

- Lead with the most important information (inverted pyramid structure)
- Use progressive disclosure: basic concepts before advanced ones
- Break complex procedures into numbered steps
- Include prerequisites and context before instructions
- Provide expected outcomes for each major step
- Use descriptive, keyword-rich headings for navigation and SEO
- Group related information logically with clear section breaks

### User-centered approach

- Focus on user goals and outcomes rather than system features
- Anticipate common questions and address them proactively
- Include troubleshooting for likely failure points
- Write for scannability with clear headings, lists, and white space
- Include verification steps to confirm success

## Mintlify component reference

### Callout components

#### Note - Additional helpful information

<Note>
Supplementary information that supports the main content without interrupting flow
</Note>

#### Tip - Best practices and pro tips

<Tip>
Expert advice, shortcuts, or best practices that enhance user success
</Tip>

#### Warning - Important cautions

<Warning>
Critical information about potential issues, breaking changes, or destructive actions
</Warning>

#### Info - Neutral contextual information

<Info>
Background information, context, or neutral announcements
</Info>

#### Check - Success confirmations

<Check>
Positive confirmations, successful completions, or achievement indicators
</Check>

### Code components

#### Single code block

单个代码块示例：

```javascript config.js
const apiConfig = {
  baseURL: 'https://api.example.com',
  timeout: 5000,
  headers: {
    'Authorization': `Bearer ${process.env.API_TOKEN}`
  }
};
```

#### Code group with multiple languages

代码组示例：

<CodeGroup>
```javascript Node.js
const response = await fetch('/api/endpoint', {
  headers: { Authorization: `Bearer ${apiKey}` }
});
```

```python Python
import requests
response = requests.get('/api/endpoint', 
  headers={'Authorization': f'Bearer {api_key}'})
```

```curl cURL
curl -X GET '/api/endpoint' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```
</CodeGroup>

#### Request/response examples

请求/响应文档示例：

<RequestExample>
```bash cURL
curl -X POST 'https://api.example.com/users' \
  -H 'Content-Type: application/json' \
  -d '{"name": "John Doe", "email": "[email protected]"}'
```
</RequestExample>

<ResponseExample>
```json Success
{
  "id": "user_123",
  "name": "John Doe", 
  "email": "[email protected]",
  "created_at": "2024-01-15T10:30:00Z"
}
```
</ResponseExample>

### 结构化组件

#### 步骤（步骤化操作）

分步操作示例：

<Steps>
<Step title="Install dependencies">
  运行 `npm install` 安装所需依赖。
  
  <Check>
  通过运行 `npm list` 验证安装。
  </Check>
</Step>

<Step title="Configure environment">
  创建包含 API 凭据的 `.env` 文件。
  
  ```bash
  API_KEY=your_api_key_here
  ```
  
  <Warning>
  切勿将 API key 提交到版本控制。
  </Warning>
</Step>
</Steps>

#### Tabs（选项卡）

选项卡内容示例：

<Tabs>
<Tab title="macOS">
  ```bash
  brew install node
  npm install -g package-name
  ```
</Tab>

<Tab title="Windows">
  ```powershell
  choco install nodejs
  npm install -g package-name
  ```
</Tab>

<Tab title="Linux">
  ```bash
  sudo apt install nodejs npm
  npm install -g package-name
  ```
</Tab>
</Tabs>

#### 折叠面板（Accordions）

折叠分组示例：

<AccordionGroup>
<Accordion title="连接问题排查">
  - **防火墙阻断**：确保 80 与 443 端口开放
  - **代理配置**：设置 HTTP_PROXY 环境变量
  - **DNS 解析**：尝试使用 8.8.8.8 作为 DNS 服务器
</Accordion>

<Accordion title="高级配置">
  ```javascript
  const config = {
    performance: { cache: true, timeout: 30000 },
    security: { encryption: 'AES-256' }
  };
  ```
</Accordion>
</AccordionGroup>

### 卡片与分栏（强调信息）

卡片与卡片分组示例：

<Card title="入门指南" icon="rocket" href="/quickstart">
从安装到首次 API 调用的完整演练，不超过 10 分钟。
</Card>

<CardGroup cols={2}>
<Card title="Authentication" icon="key" href="/auth">
  了解如何使用 API key 或 JWT 对请求进行认证。
</Card>

<Card title="Rate limiting" icon="clock" href="/rate-limits">
  了解限流策略与大流量使用的最佳实践。
</Card>
</CardGroup>

### API 文档组件

#### 参数字段

参数文档示例：

<ParamField path="user_id" type="string" required>
用户的唯一标识。必须为有效的 UUID v4 格式。
</ParamField>

<ParamField body="email" type="string" required>
用户邮箱地址。必须有效且在系统内唯一。
</ParamField>

<ParamField query="limit" type="integer" default="10">
返回结果的最大数量。范围：1-100。
</ParamField>

<ParamField header="Authorization" type="string" required>
用于 API 认证的 Bearer token。格式：`Bearer YOUR_API_KEY`
</ParamField>

#### 响应字段

响应字段文档示例：

<ResponseField name="user_id" type="string" required>
分配给新建用户的唯一标识。
</ResponseField>

<ResponseField name="created_at" type="timestamp">
用户创建时间，ISO 8601 格式。
</ResponseField>

<ResponseField name="permissions" type="array">
分配给该用户的权限字符串列表。
</ResponseField>

#### 可展开的嵌套字段

嵌套字段文档示例：

<ResponseField name="user" type="object">
完整的用户对象及其所有相关数据。

<Expandable title="User properties">
  <ResponseField name="profile" type="object">
  用户档案信息，包括个人详情。
  
  <Expandable title="Profile details">
    <ResponseField name="first_name" type="string">
    注册时填写的用户名（名）。
    </ResponseField>
    
    <ResponseField name="avatar_url" type="string | null">
    用户头像的 URL。如未设置头像则返回 null。
    </ResponseField>
  </Expandable>
  </ResponseField>
</Expandable>
</ResponseField>

### 媒体与进阶组件

#### 图片框架（Frame）

将图片包裹在 Frame 中：

<Frame>
<img src="/images/dashboard.png" alt="Main dashboard showing analytics overview" />
</Frame>

<Frame caption="The analytics dashboard provides real-time insights">
<img src="/images/analytics.png" alt="Analytics dashboard with charts" />
</Frame>

#### 视频

自托管视频请使用 HTML video 元素：

<video
  controls
  className="w-full aspect-video rounded-xl"
  src="link-to-your-video.com"
></video>

嵌入 YouTube 视频可使用 iframe：

<iframe
  className="w-full aspect-video rounded-xl"
  src="https://www.youtube.com/embed/4KzFe50RQkQ"
  title="YouTube video player"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

#### Tooltips

提示用法示例：

<Tooltip tip="Application Programming Interface - protocols for building software">
API
</Tooltip>

#### 更新（Updates）

用于记录变更日志：

<Update label="Version 2.1.0" description="Released March 15, 2024">
## New features
- Added bulk user import functionality
- Improved error messages with actionable suggestions

## Bug fixes
- Fixed pagination issue with large datasets
- Resolved authentication timeout problems
</Update>

## 必需的页面结构

每个文档页面都必须以 YAML frontmatter 开始：

```yaml
---
title: "Clear, specific, keyword-rich title"
description: "Concise description explaining page purpose and value"
---
```

## 内容质量标准

### 代码示例要求

- 提供完整、可运行的示例，便于用户复制执行
- 展示正确的错误处理与边界情况处理
- 使用真实数据而非占位值
- 提供预期输出与结果以便验证
- 发布前充分测试所有代码示例
- 指定语言并在需要时包含文件名
- 对复杂逻辑添加解释性注释
- 绝不在示例中包含真实 API key 或机密

### API 文档要求

- 记录所有参数（包括可选参数），给出清晰描述
- 展示成功与错误响应示例，使用真实数据
- 包含限流信息并给出具体限额
- 提供认证示例并保证格式正确
- 解释所有 HTTP 状态码与错误处理
- 覆盖完整的请求/响应流程

### 无障碍（可访问性）要求

- 为所有图片与图表提供描述性 alt 文本
- 使用具体、可执行的链接文本（避免“点击这里”）
- 确保从 H2 开始的正确标题层级
- 提供键盘导航方面的考虑
- 在示例与视觉中使用足够的颜色对比度
- 用标题与列表组织内容，便于快速浏览

## 组件选择指引

- 使用 **Steps** 处理流程与顺序指令
- 使用 **Tabs** 展示平台差异或替代方案
- 多语言示例使用 **CodeGroup**
- 渐进展开的信息使用 **Accordions**
- API 端点文档使用 **RequestExample/ResponseExample**
- API 参数用 **ParamField**，API 响应用 **ResponseField**
- 嵌套对象或层级信息用 **Expandable**