mirror of
https://github.com/mintlify/docs.git
synced 2026-09-14 13:35:46 +08:00
locadex-agent[bot]
c2e8eef182
Co-authored-by: locadex-agent[bot] <217277504+locadex-agent[bot]@users.noreply.github.com>
159 lines
5.2 KiB
Plaintext
159 lines
5.2 KiB
Plaintext
---
|
||
title: "Windsurf"
|
||
description: "将 Windsurf 配置为你的写作 AI 助手。"
|
||
keywords: ["Windsurf", "Cascade", "workspace rules", "memories"]
|
||
---
|
||
|
||
通过 workspace rules 和 memories，将 Windsurf 打造成一位熟悉你的样式指南、组件和项目 context 的文档专家。
|
||
|
||
<div id="use-windsurf-with-mintlify">
|
||
## 将 Windsurf 与 Mintlify 配合使用
|
||
</div>
|
||
|
||
Windsurf 的 Cascade AI 助手可以配合 Mintlify 组件，按照你的标准撰写文档。工作区规则与记忆会为你的项目提供持久的 context，从而让 Cascade 的建议更加一致。
|
||
|
||
* **工作区规则** 存储在你的文档存储库中，并与团队共享。
|
||
* **记忆** 提供会随时间累积的个人 context。
|
||
|
||
我们建议为共享的文档规范设置工作区规则。你可以在工作中逐步积累记忆，但由于记忆不共享，团队成员之间的体验将不一致。
|
||
|
||
在你的文档存储库的 `.windsurf/rules` 目录中创建工作区规则。更多信息请参阅 Windsurf 文档：[Memories & Rules](https://docs.windsurf.com/windsurf/cascade/memories)。
|
||
|
||
<div id="example-workspace-rule">
|
||
## 示例工作区规则
|
||
</div>
|
||
|
||
此规则为 Cascade 提供有关 Mintlify 组件和通用技术写作最佳实践的 context。
|
||
|
||
你可以按原样使用此示例规则，或根据你的文档进行自定义：
|
||
|
||
* **写作标准**：更新语言规范以符合你的风格指南。
|
||
* **组件模式**：添加项目特定的组件，或修改现有示例。
|
||
* **代码示例**：将通用示例替换为与你的产品相关的真实 API 调用与响应。
|
||
* **风格与语气偏好**：调整术语、格式和其他规则。
|
||
|
||
将此规则以 `.md` 文件保存到文档仓库的 `.windsurf/rules` 目录中。
|
||
|
||
````mdx
|
||
# Mintlify 技术写作规范
|
||
|
||
## 项目背景
|
||
|
||
- 这是一个基于 Mintlify 平台的文档项目
|
||
- 我们使用带有 YAML frontmatter 的 MDX 文件
|
||
- 导航在 `docs.json` 中配置
|
||
- 我们遵循技术写作最佳实践
|
||
|
||
## 写作标准
|
||
|
||
- 使用第二人称（"你"）来编写说明
|
||
- 使用主动语态和现在时
|
||
- 操作步骤开始前先列出前提条件
|
||
- 为主要步骤提供预期结果
|
||
- 使用描述性、关键词丰富的标题
|
||
- 保持句子简洁但信息丰富
|
||
|
||
## 必需的页面结构
|
||
|
||
每个页面都必须以 frontmatter 开始：
|
||
|
||
```yaml
|
||
---
|
||
title: "清晰、具体的标题"
|
||
description: "用于 SEO 和导航的简洁说明"
|
||
---
|
||
```
|
||
|
||
## Mintlify 组件
|
||
|
||
### docs.json
|
||
|
||
- 在构建 docs.json 文件和网站导航时，请参考 [docs.json 架构](https://mintlify.com/docs.json)
|
||
|
||
### 标注
|
||
|
||
- `<Note>` 用于有用的补充信息
|
||
- `<Warning>` 用于重要警告和破坏性更改
|
||
- `<Tip>` 用于最佳实践和专家建议
|
||
- `<Info>` 用于中性的上下文信息
|
||
- `<Check>` 用于成功确认
|
||
|
||
### 代码示例
|
||
|
||
- 在适当的时候，包含完整的、可运行的示例
|
||
- 使用 `<CodeGroup>` 展示多语言示例
|
||
- 在所有代码块上指定语言标签
|
||
- 包含真实数据，而不是占位符
|
||
- 对于 API 文档使用 `<RequestExample>` 和 `<ResponseExample>`
|
||
|
||
### 操作步骤
|
||
|
||
- 使用 `<Steps>` 组件编写顺序说明
|
||
- 在相关时包含带有 `<Check>` 组件的验证步骤
|
||
- 将复杂操作分解为较小的步骤
|
||
|
||
### 内容组织
|
||
|
||
- 使用 `<Tabs>` 展示平台特定内容
|
||
- 使用 `<Accordion>` 实现渐进式展示
|
||
- 使用 `<Card>` 和 `<CardGroup>` 突出显示内容
|
||
- 将图像包装在带有描述性替代文本的 `<Frame>` 组件中
|
||
|
||
## API 文档要求
|
||
|
||
- 使用 `<ParamField>` 记录所有参数
|
||
- 使用 `<ResponseField>` 显示响应结构
|
||
- 包含成功和错误示例
|
||
- 对嵌套对象属性使用 `<Expandable>`
|
||
- 始终包含认证示例
|
||
|
||
## 质量标准
|
||
|
||
- 发布前测试所有代码示例
|
||
- 对内部链接使用相对路径
|
||
- 为所有图像包含替代文本
|
||
- 确保正确的标题层次结构（从 h2 开始）
|
||
- 检查现有模式的一致性
|
||
````
|
||
|
||
<div id="working-with-cascade">
|
||
## 使用 Cascade
|
||
</div>
|
||
|
||
完成规则配置后，您可以使用 Cascade 协助处理各类文档任务。有关更多信息，请参阅 Windsurf 文档中的 [Cascade](https://docs.windsurf.com/windsurf/cascade)。
|
||
|
||
<div id="example-prompts">
|
||
### 示例提示
|
||
</div>
|
||
|
||
**撰写新对象**:
|
||
|
||
```text wrap
|
||
创建一个新页面，说明如何通过我们的 API 进行身份验证。包含 JavaScript、Python 和 cURL 的代码示例。
|
||
```
|
||
|
||
**改进现有对象**:
|
||
|
||
```text wrap
|
||
审查此页面并建议改进清晰度和组件使用方式。重点让步骤更易于理解和执行。
|
||
```
|
||
|
||
**创建代码示例**：
|
||
|
||
```text wrap
|
||
生成一个完整的代码示例，展示此 API 端点的错误处理。使用真实数据并包含预期响应。
|
||
```
|
||
|
||
**保持一致性**：
|
||
|
||
```text wrap
|
||
检查此新页面是否符合我们的文档标准，并提出必要的修改建议。
|
||
```
|
||
|
||
<div id="enhance-with-mcp-server">
|
||
## 使用 MCP 服务器增强功能
|
||
</div>
|
||
|
||
将 Mintlify MCP 服务器连接到 Windsurf，使 Cascade 在帮助你写作时可以搜索 Mintlify 文档。连接 MCP 服务器后，Cascade 会在最新的 Mintlify 文档中搜索相关上下文，这样你就不需要离开 IDE 来查阅文档。
|
||
|
||
完整的设置说明请参见 [Model Context Protocol](/zh/ai/model-context-protocol#example%3A-connect-to-the-mintlify-mcp-server)。 |