> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLAUDE

# 项目配置 - API易文档中心

## 项目概述

这是一个基于 Mintlify 的文档网站项目，为 API易 提供技术文档和FAQ支持。官网 [https://mintlify.com/](https://mintlify.com/)

## 文档编写规范

### MDX文件格式要求

* **重要**：Mintlify会自动从frontmatter的`title`字段生成H1标题
* **禁止**：在MDX文件内容中使用H1标题（`# 标题`）
* **原因**：会导致页面出现重复的H1标题，影响SEO和用户体验

### 正确的文件结构

```mdx theme={null}
---
title: "页面标题"
description: "页面描述"
icon: "图标名称"
---

## 第一个章节标题
内容从H2开始...

### 子标题
使用H3及以下级别的标题
```

### 错误的文件结构（避免）

```mdx theme={null}
---
title: "页面标题"
---

# 页面标题  ← 不要这样做！会重复显示

## 第一个章节标题
```

## 文档系统说明

* 使用Mintlify文档框架
* 支持MDX格式（Markdown + JSX组件）
* 导航结构在`docs.json`中定义
* 图片资源存放在`images/`目录

## FAQ页面组织

* 所有FAQ页面位于`faq/`目录
* 作为独立的顶级标签页展示
* 每个问题一个独立的MDX文件

## 编写新内容时的注意事项

1. 遵循上述MDX格式规范
2. 使用适当的Mintlify组件（Info, Warning, Tip, Card等）
3. 保持中文内容的专业性和友好性
4. 引用图片时使用相对路径`/images/文件名`
5. **时间必须标注时区**：文档中涉及具体时间时，必须附加时区说明（如 `18:30 (UTC+8)`），因为我们有全球客户
   * ✅ 正确：`18:30 (UTC+8)`、`6:30 PM (UTC+8)`
   * ❌ 错误：`18:30`、`今晚六点半`（缺少时区，全球客户无法判断）
6. **英文内容品牌名用 APIYI**：英文页面（`en/` 目录）中品牌名一律写 `APIYI`，不要写 `API易`；中文页面仍用 `API易`
   * ✅ 正确（英文）：`the APIYI gateway`、`paste your APIYI key`
   * ❌ 错误（英文）：`the API易 gateway`
   * 域名、代码示例不受影响：`api.apiyi.com`、`APIYI_API_KEY` 等保持原样
7. **新建页面必须中英双语同步**：每次创建一个新页面时，必须同时产出中文版（根目录）和英文版（`en/` 目录），两份内容对应、文件名一致，并在 `docs.json` 的中文版和英文版导航中**同时**注册（位置一致）。不允许只建一个语言版本。
   * 中文页内部链接用 `/api-capabilities/...`，英文页内部链接用 `/en/api-capabilities/...`
   * 英文版品牌名遵循第 6 条（APIYI）
8. **页面标题不要中英混排**：`title` / `sidebarTitle` 只用单一语言。中文页只写中文（如 `原生工具出图`），英文页只写英文（如 `Native Tool Image Generation`），不要写成 `原生工具出图（Responses image_generation）` 这种括号混排。

## 大模型百科写作规范

### 词条页面结构

```mdx theme={null}
---
title: "词条名称"
description: "简短描述(1-2句话，80字以内)"
icon: "相关图标"
tags: ["标签1", "标签2", "标签3"]
difficulty: "basic|intermediate|advanced"
related: ["相关词条1", "相关词条2"]
---

## 概念定义
[30-50字的核心定义，适合小白理解]

## 详细解释 
[200-400字的详细说明，专业但易懂]

## 工作原理
[配图解说明，解释核心机制]

## 实际应用
[具体应用场景和案例]

## 相关概念
[链接到其他相关词条]

## 延伸阅读
[权威参考资源]
```

### 写作风格指南

* **专业性**：确保技术准确性，引用权威来源
* **易懂性**：用类比和实例帮助理解复杂概念
* **简洁性**：避免冗长，重点突出
* **交互性**：善用图解说明和交叉引用
* **更新性**：及时反映最新技术发展

### 联网搜索要求

* **必须联网**：创建每个词条前必须进行联网搜索
* **信息时效**：确保引用最新的技术发展、模型更新、研究成果
* **多源验证**：交叉验证多个权威来源的信息
* **版本更新**：特别注意模型版本、API更新、性能指标等时效性信息
* **标注日期**：对于快速变化的信息，标注数据获取时间

### 难度分级标准

* **basic**：面向初学者，无需预备知识
* **intermediate**：需要基础概念理解
* **advanced**：需要深度技术背景

### 图片格式要求

#### 推荐格式

* **PNG**：用于图解、流程图、架构图等需要高质量显示的图片
* **JPEG**：用于照片类图像，文件较大但压缩率高
* **外部托管SVG**：如需使用SVG，建议外部托管并通过URL引用

#### 格式使用指南

* **图解说明**：优先使用PNG格式，确保清晰度和兼容性
* **图标**：使用Font Awesome或Lucide内置图标，避免自定义SVG
* **浅色/深色主题**：为不同主题准备两个版本的PNG图片
  ```html theme={null}
  <img className="block dark:hidden" src="/images/diagram-light.png" alt="浅色主题图解" />
  <img className="hidden dark:block" src="/images/diagram-dark.png" alt="深色主题图解" />
  ```

#### 注意事项

* **避免内联SVG**：Mintlify对内联SVG支持存在问题，可能导致渲染错误
* **文件大小**：PNG文件控制在200KB以内，JPEG控制在500KB以内
* **命名规范**：使用描述性文件名，如 `transformer-architecture-light.png`
* **测试环境**：本地预览正常不代表生产环境正常，务必在部署后检查

### 其他要求

* 注意：不使用 HTML 注释语法，需要使用JSX注释语法
* **价格符号转义**：`$` 符号的处理方式取决于所在语境，正文和 frontmatter 规则相反，不要混用
  * **MDX 正文**（含表格）：必须转义为 `\$`，避免被 LaTeX 数学模式吞掉
    * ✅ 正确：`\$2.00 / 百万 tokens`
    * ❌ 错误：`$2.00 / 百万 tokens`（会触发 LaTeX 解析错误）
  * **Frontmatter（YAML）**：直接写 `$`，不要转义
    * ✅ 正确：`description: "价格 $0.42/$2.52 每 1M tokens"`
    * ❌ 错误：`description: "价格 \$0.42/\$2.52 每 1M tokens"`
    * 原因：YAML 双引号字符串里 `\$` 不是合法转义序列（YAML 只认 `\n` `\t` `\"` `\\` 等），会触发 frontmatter 解析错误
    * 备选：若一定要转义，写 `\\$`（YAML 把 `\\` 解析为字面 `\`，最终值为 `\$`），但通常没必要
* **外部链接限制**：禁止使用非 `apiyi.com` 域名的超链接，改为纯文本 + 反引号代码格式
  * ✅ 正确：`` 谷歌官方博客：`blog.google/technology/ai/...` ``
  * ❌ 错误：`谷歌官方博客：[链接](https://blog.google/...)`
  * 原因：避免用户直接跳转到第三方网站，让用户主动复制链接访问
* **小于号转义**：在 MDX/JSX 组件内使用小于号 `<` 时需要注意
  * ✅ 正确：`建议少于20字` 或 `建议 &lt; 20字`
  * ❌ 错误：`建议<20字`（`<` 会被误认为 HTML 标签开始）
  * 原因：MDX 会将 `<` 后面的内容当作标签解析，导致解析错误
* **JSX 属性内的引号**：JSX 属性值用 `"..."` 包裹时，里面禁止再出现 ASCII 双引号 `"`
  * ✅ 正确：`<Step title="prompt 聚焦「动作」而不是「画面」">`（用中文引号 `「」`）
  * ✅ 正确：`<Step title='prompt 聚焦"动作"而不是"画面"'>`（外层换单引号）
  * ❌ 错误：`<Step title="prompt 聚焦"动作"而不是"画面"">`（第二个 `"` 提前闭合属性，后面的中文被当作 attribute name 解析报错）
  * 原因：MDX/JSX 不会自动识别"嵌套引号"，第二个 `"` 一定结束属性。中文场景优先用 `「」`，最直观无歧义
  * 同样适用于：解析失败时常常**级联**触发 docs.json 报告"file does not exist"，定位时优先排查最近一次编辑的 JSX 属性

## Changelog 精简格式规范

### 设计理念

Changelog 页面作为快速更新公告，应保持简洁明了。详细内容通过"AI风向标"（News）栏目展示。

### 条目格式要求

```mdx theme={null}
### 🌟 [更新标题]
**YYYY年MM月DD日**

[2-3句话的核心摘要，突出关键信息]

📖 [查看详情](/news/文章slug) | 🔗 [相关文档](/docs/link)
```

### 摘要写作要点

* **第一句**：说明是什么（新增模型/功能更新/价格调整等）
* **第二句**：核心亮点（性能指标/价格优势/关键特性）
* **第三句**：推荐场景或使用建议（可选）
* **长度控制**：总计 50-80 字，不超过 3 句话
* **Emoji使用**：适当使用 emoji 增强可读性（🚀🎉💰🏆等）

### 链接规范

* **查看详情链接**：必须链接到对应的 News 文章
* **相关文档链接**：如有详细 API 文档，提供直达链接
* **格式统一**：使用 `📖 查看详情` 和 `🔗 相关文档` 标识

### 示例（正确）

```mdx theme={null}
### 🌟 Gemini 3 Pro Preview 震撼上线
**2025年11月20日**

谷歌最新多模态智能模型上线！LMArena 排行榜 1501 Elo 全球第一，SWE-bench Verified 76.2%，支持 100 万上下文和思维链输出。充值加赠可达 8 折优惠。

📖 [查看详情](/news/gemini-3-pro-preview-launch) | 🔗 [API文档](/api-capabilities/gemini)
```

### 示例（错误 - 避免）

```mdx theme={null}
### 🌟 Gemini 3 Pro Preview 震撼上线
**2025年11月20日**

<Card>
  [大段详细内容...]  ← 不要在 Changelog 中使用 Card 组件展示详细信息
  [技术细节...]      ← 不要在 Changelog 中写太多技术细节
  [使用指南...]      ← 详细指南应该放在 News 文章中
</Card>
```

## AI风向标（News）书写规范

### 栏目定位

AI风向标是独立的顶级导航栏目，用于发布：

* **本站更新**：新模型上线、价格调整、功能更新的深度解读
* **行业动态**：AI 领域重要事件、技术突破、趋势分析
* **使用指南**：模型对比、最佳实践、应用案例

### 文章页面结构

```mdx theme={null}
---
title: "文章标题（20字以内，吸引眼球）"
description: "一句话摘要（50-80字，适合搜索引擎和社交分享）"
date: "2025-11-20"
author: "API易团队"
category: "site-update | industry-news | tutorial | model-release"
tags: ["标签1", "标签2", "标签3"]
icon: "newspaper"
featured: true  # 是否在首页展示
---

## 核心要点
[3-5个要点，用 bullet points 列出，让读者快速了解文章内容]

## 背景介绍
[为什么要关注这个话题？有什么背景信息？]

## 详细解析
[深入分析，包含技术细节、性能对比、使用场景等]

## 实际应用
[如何使用？代码示例、最佳实践]

## 价格与可用性
[定价信息、购买渠道、优惠活动]

## 总结与建议
[总结核心观点，给出使用建议]
```

### 写作风格指南

* **专业度**：引用官方数据、权威评测、性能指标
* **易读性**：使用副标题、要点列表、代码示例、对比表格
* **时效性**：标注发布日期、版本号、数据来源日期
* **可操作性**：提供具体的使用方法、代码示例、配置指南
* **视觉化**：使用 Card、Info、Warning 等 Mintlify 组件增强可读性

### 联网搜索要求（必须）

* **创作前搜索**：撰写每篇 News 文章前必须进行联网搜索
* **验证信息**：核实模型发布日期、性能指标、官方公告
* **引用来源**：标注信息来源（官方博客、技术报告、评测网站）
* **时效性检查**：确保使用最新的版本号、API 端点、定价信息

### 分类标签系统（Tags）

* **类型标签**：`site-update`（本站更新）、`industry-news`（行业动态）、`tutorial`（教程指南）、`model-release`（模型发布）
* **厂商标签**：`openai`、`google`、`anthropic`、`deepseek`、`zhipu` 等
* **能力标签**：`text-generation`、`image-generation`、`video-generation`、`code`、`reasoning` 等
* **使用场景**：`programming`、`translation`、`creative-writing`、`data-analysis` 等

### 文件命名规范

* **格式**：`模型名-发布类型-日期.mdx`
* **示例**：
  * `gemini-3-pro-preview-launch.mdx`（模型发布）
  * `gpt-5-price-update.mdx`（价格更新）
  * `ai-trends-2025-q4.mdx`（行业趋势）
* **要求**：小写字母、连字符分隔、简洁明了

### 目录组织

* **路径**：`/news/` 和 `/en/news/`（中英双语）
* **结构**：扁平结构，所有文章在根目录
* **排序**：通过 frontmatter 的 `date` 字段自动排序
* **分类**：通过 `tags` 和 `category` 字段分类

### 与 Changelog 的关系

* **Changelog**：简短摘要（2-3句话）+ 链接到 News
* **News**：完整的深度文章（800-2000字）
* **链接**：Changelog 条目必须链接到对应的 News 文章
* **同步更新**：发布 News 文章时，同步更新 Changelog

### Mintlify 组件使用

````mdx theme={null}
{/* 重要信息 */}
<Info>
  这里是重要提示信息
</Info>

{/* 警告提醒 */}
<Warning>
  注意事项和限制
</Warning>

{/* 要点卡片 */}
<Card title="核心特性" icon="star">
  特性说明
</Card>

{/* 多列布局 */}
<CardGroup cols={2}>
  <Card title="优势" icon="check">内容</Card>
  <Card title="限制" icon="ban">内容</Card>
</CardGroup>

{/* 代码示例 */}
```python
# Python 代码示例
import openai
````

| 模型 | 性能  | 价格    |
| -- | --- | ----- |
| A  | 90% | \$1   |
| B  | 85% | \$0.5 |

````

### 图片使用规范
- 遵循"图片格式要求"章节的规范
- 优先使用 PNG 格式
- 支持浅色/深色主题切换
- 文件大小控制在 200KB 以内

### 质量检查清单
发布前检查：
- ✅ 已进行联网搜索验证信息
- ✅ Frontmatter 字段完整（title、description、date、tags 等）
- ✅ 无 H1 标题（使用 H2 起始）
- ✅ 代码示例可运行
- ✅ 链接有效（内部链接和外部链接）
- ✅ 图片正常显示
- ✅ 中英文版本同步
- ✅ Changelog 已更新对应链接
- ✅ **docs.json 导航配置已更新**（中英双版本，见下方说明）
- ✅ **价格符号已转义**（`$` → `\$`）
- ✅ **无外部超链接**（非 apiyi.com 域名改为纯文本 + 反引号）
- ✅ **小于号已处理**（`<数字` 改为 `少于数字` 或 `&lt;数字`）

### docs.json 导航更新（重要）
**每次创建新的 News 文章后必须更新 `docs.json`，否则用户无法在网站导航中找到新文章。**

#### 需要更新的位置
1. **中文版导航**（约第187-192行）：
   - 路径：`navigation.languages[0].tabs` → 找到 `"tab": "AI风向标"` → `groups[0].pages`
   - 在 `pages` 数组**最前面**添加：`"news/文章文件名"`（不含 `.mdx`）

2. **英文版导航**（约第552-557行）：
   - 路径：`navigation.languages[1].tabs` → 找到 `"tab": "AI Radar"` → `groups[0].pages`
   - 在 `pages` 数组**最前面**添加：`"en/news/文章文件名"`（不含 `.mdx`）

#### 示例
```json
{
  "pages": [
    "news/你的新文章-slug",  // 新文章置顶
    "news/seedream-4-5-launch",
    "news/claude-opus-4-5-launch"
  ]
}
````

#### 注意事项

* 新文章必须放在数组最前面（最新的在最上面）
* 注意 JSON 逗号语法
* 中英文版本必须同时更新
* 路径不包含 `.mdx` 扩展名