documentation

文档

文档位于 docs/，使用 GitHub 风格的 Markdown，以 Astro Starlight 渲染，并遵循 Diátaxis。

Diátaxis 框架

按照 Diátaxis 的四种类型组织文档：

1. 教程（以学习为导向）

目的：引导初学者实现特定成果，帮助他们建立信心。

• 从用户将构建或实现的内容开始
• 提供从开始到结束清晰、循序渐进的步骤
• 包含具体示例和可运行的代码
• 假设用户几乎没有相关先验知识
• 聚焦于顺利完成的路径（避免边缘情况和替代方案）
• 以用户可以看到并使用的可运行成果收尾
• 使用祈使语气：“创建一个文件”“运行命令”

避免：深入讲解概念、提供多个选项、故障排除

2. 操作指南（以目标为导向）

目的：展示如何解决特定的实际问题或完成特定任务。

• 标题格式：“如何 [实现特定目标]”
• 假设用户了解基础知识
• 聚焦于解决一个问题的实际步骤
• 提供必要的背景信息，但保持重点明确
• 仅在确实有帮助时展示多种方法
• 在目标达成时结束
• 使用祈使语气：“配置该设置”“添加以下内容”

避免：教授基础知识、解释每个细节、面面俱到

3. 参考（以信息为导向）

目的：提供准确、完整的系统技术说明。

• 按结构组织（CLI 命令、配置选项、API 端点）
• 内容全面且权威
• 所有条目的格式保持一致
• 技术准确性至关重要
• 包含所有参数、选项和返回值
• 使用陈述语气：“该命令接受”“返回一个字符串”
• 尽量减少叙述或解释

避免：操作说明、教程、使用建议

4. 解释（以理解为导向）

目的：阐明主题，帮助读者加深理解。

• 讨论事物为何如此
• 解释设计决策和权衡
• 提供背景信息
• 联系不同概念，帮助建立思维模型
• 讨论替代方案及其影响
• 使用陈述语气：“这种方法能够提供”“引擎使用”

避免：循序渐进的操作说明、详尽的参考资料

通用风格指南

• 语气：中立、技术性，不带宣传色彩
• 表达方式：避免使用“我们”“我们的”（改用“该工具”“此命令”）
• 标题：使用 Markdown 标题语法，不要用粗体文本充当标题
• 列表：避免冗长的项目符号列表；优先使用结构清晰的段落
• 代码示例：精简且聚焦；除非相关，否则省略可选字段
• 语言标签：对于包含 YAML frontmatter 的 Agent 工作流代码片段，使用 aw

工作流代码块示例：

on: push
# Your workflow steps here

GitHub 风格的 Markdown 语法

文档文件使用 GitHub 风格的 Markdown，并由 Astro Starlight 渲染。主要语法元素如下：

Frontmatter

每个文档页面都必须包含 frontmatter：

title: Page Title
description: Brief description for SEO and navigation

GitHub 提示框

使用 GitHub 的提示框语法编写注释、提示、警告和注意事项：

> [!NOTE]
> Important information the reader should notice.

> [!TIP]
> Helpful advice for the reader.

> [!WARNING]
> Warning about potential issues or pitfalls.

> [!CAUTION]
> Critical warning about dangerous operations.

> [!IMPORTANT]
> Key information users need to know.

代码块

• 使用带语言标签的语法高亮
• 为文件名添加 title 属性：```yaml title=".github/workflows/example.yml"
• 对包含 YAML frontmatter 的 Agent 工作流文件使用 aw 语言标签
• 添加 wrap 实现自动换行：```aw wrap

链接

• 内部链接：在文档页面之间使用相对路径
• 外部链接：自动在新标签页中打开
• 链接文本：使用描述性文字，避免使用“点击此处”

标签页

使用标签页展示替代选项（例如不同的语言、平台）：

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
  <TabItem label="npm">
    ```bash
    npm install package
    ```
  </TabItem>
  <TabItem label="yarn">
    ```bash
    yarn add package
    ```
  </TabItem>
</Tabs>

卡片

使用卡片提供导航或突出显示多个选项：

import { Card, CardGrid } from '@astrojs/starlight/components';

<CardGrid>
  <Card title="Getting Started" icon="rocket">
    Quick introduction to the basics.
  </Card>
  <Card title="Advanced Usage" icon="setting">
    Deep dive into advanced features.
  </Card>
</CardGrid>

请记住：组件应保持精简。尽可能优先使用标准 Markdown。

应避免的内容

• “关键功能”部分
• 营销语言或卖点
• 过多的项目符号（优先使用结构化的散文）
• 包含所有可选参数、过于冗长的示例
• 混合文档类型（例如，教程变成参考文档）

避免文档臃肿

文档臃肿会降低清晰度，让内容更难浏览。常见的臃肿类型包括：

文档臃肿的类型

1. 内容重复：在不同部分重复相同信息
2. 过多的项目符号：可整理成散文或表格的冗长列表
3. 多余的示例：多个示例展示相同概念
4. 冗长的描述：过于啰嗦、可以更简洁的解释
5. 重复的结构：反复使用相同的“作用是什么”／“价值何在”模式

编写简洁的文档

编辑文档时，请重点关注：

整合项目符号：

• 将冗长的项目符号列表改为简洁的散文或表格
• 删除以不同方式表达相同内容的重复要点

消除重复：

• 删除重复信息
• 整合相似部分

精简冗长文本：

• 让描述更直接、更简洁
• 删除填充词和短语
• 在减少字数的同时保持技术准确性

规范结构：

• 减少反复使用“作用是什么”／“价值何在”的模式
• 使用多样、自然的语言

简化代码示例：

• 删除代码示例中不必要的复杂内容
• 聚焦于清晰展示核心概念
• 除非有助于理解，否则删除样板代码或设置代码
• 保持示例精简且完整
• 使用真实但简单的场景

示例：精简前后

精简前（臃肿）：

### Tool Name
Description of the tool.

- **What it does**: This tool does X, Y, and Z
- **Why it's valuable**: It's valuable because A, B, and C
- **How to use**: You use it by doing steps 1, 2, 3, 4, 5
- **When to use**: Use it when you need X
- **Benefits**: Gets you benefit A, benefit B, benefit C
- **Learn more**: [Link](url)

精简后（简洁）：

### Tool Name
Description of the tool that does X, Y, and Z to achieve A, B, and C.

Use it when you need X by following steps 1-5. [Learn more](url)

文档质量准则

1. 保留含义：切勿丢失重要信息
2. 精准修改：进行精确修改，不要重写所有内容
3. 保持语气：保持中立、技术性的语气
4. 本地测试：确认链接和格式仍然正确

按文件类型组织

• 入门指南：教程格式
• 操作指南：以目标为导向，每份指南完成一项任务
• CLI 参考：参考文档格式，完整记录命令
• 概念：解释性格式，帮助读者建立理解
• API 参考：参考文档格式，完整记录 API