# ARCS SDK 示例文档编写规范（AI 辅助版）

> 本规范用于指导 AI 生成和检查 ARCS SDK 示例文档，确保所有示例文档风格统一、信息完整、格式规范。

**版本**: 2.0
**日期**: 2025-01-14
**维护者**: ARCS SDK 团队
**适用范围**: 所有 samples/ 目录下的示例文档（README.md 或 README.rst）

---

## 目录

1. [规范概述](#规范概述)
2. [文档结构规范](#文档结构规范)
3. [各章节详细规范](#各章节详细规范)
4. [不同类型示例的差异](#不同类型示例的差异)
5. [格式规范](#格式规范)
6. [AI 生成文档指南](#ai-生成文档指南)
7. [AI 审查文档清单](#ai-审查文档清单)

---

## 规范概述

### 核心原则

1. **结构一致性**: 所有示例遵循统一的章节结构和顺序
2. **信息完整性**: 必需章节不可缺失，关键信息必须包含
3. **格式统一性**: 支持 Markdown 或 reStructuredText 格式，格式内部保持一致
4. **语言规范性**: 中英文使用场景明确，术语表达一致

### 文档格式说明

本规范支持两种文档格式：

- **Markdown (README.md)**: 推荐格式，语法简洁，易于编写
- **reStructuredText (README.rst)**: 可选格式，适合需要复杂文档结构的场景

两种格式的章节结构和内容要求完全相同，仅语法有所差异。本文档主要以 Markdown 语法为例，RST 格式请参考对应的语法规范。

### 示例分类

| 类型 | 路径 | 特征 | 代表示例 |
|------|------|------|----------|
| **设备驱动** | `samples/drivers/devices/` | 使用 LISA 设备 API，需硬件连接说明 | lisa_gpio, lisa_uart |
| **组件模块** | `samples/modules/` | 系统组件/中间件，可能无硬件依赖 | sys_heap, lisa_shell |
| **网络示例** | `samples/network/` | 网络协议/通信，需环境配置 | http, wifi_manager |
| **HAL 驱动** | `samples/drivers/hal/` | 底层硬件抽象层，需硬件连接 | gpio, uart, spi |

---

## 文档结构规范

### 标准章节结构（按顺序）

#### 必需章节（所有示例）

| 序号 | 章节 | 标题格式 | 必需性 | 适用范围 |
|------|------|----------|--------|----------|
| 1 | 标题 | `# {模块名} {功能}示例` | ✅ 必需 | 所有 |
| 2 | 功能说明 | `## 功能说明` | ✅ 必需 | 所有 |
| 3 | 硬件连接 | `## 硬件连接` | ✅ 必需 | 所有 |
| 4 | 示例内容/步骤 | `## 示例内容` 或 `## 示例步骤` | ✅ 必需 | 所有 |
| 5 | 编译 | `## 编译` | ✅ 必需 | 所有 |
| 6 | 烧录 | `## 烧录` | ✅ 必需 | 所有 |
| 7 | 预期输出 | `## 预期输出` | ✅ 必需 | 所有 |
| 8 | 核心 API | `## 核心 API` | ⭐ 强烈推荐 | Devices, Modules |
| 9 | 关键代码 | `## 关键代码` | ⭐ 强烈推荐 | 所有 |
| 10 | 注意事项 | `## 注意事项` | ⭐ 强烈推荐 | 所有 |

#### 可选章节（根据需要）

| 章节 | 标题格式 | 使用场景 |
|------|----------|----------|
| 新特性 | `### 新特性` | 高级示例，展示技术优势 |
| 使用场景 | `## 使用场景` | 需说明技术选型时 |
| 配置说明 | `## 配置说明` | 有重要配置参数时 |
| 功能详解 | `## {功能}说明` | 需解释工作原理时 |
| 验证方法 | `## 验证方法` | 输出不可直接观察时 |
| 测试环境 | `## 测试环境准备` | 需复杂环境配置时 |

### 章节顺序规则

**固定顺序（不可调整）:**

```
1. 标题（H1）
2. 功能说明（H2）
   └── 新特性（H3，可选）
3. 硬件连接（H2）
4. 使用场景/测试环境（H2，可选）
5. 示例内容/步骤（H2）
6. 编译（H2）
7. 烧录（H2）
8. 预期输出（H2）
9. 核心 API（H2，推荐）
10. 功能详解（H2，可选）
11. 关键代码（H2，推荐）
12. 配置说明（H2，可选）
13. 验证方法（H2，可选）
14. 注意事项（H2，推荐）
15. 相关文档（H2，可选）
```

---

## 各章节详细规范

### 1. 标题（H1）

**格式模式:**

```markdown
# {模块名称} {功能描述}示例{（可选说明）}
```

**规则:**

- **模块名称**: 使用正式名称（LISA GPIO、系统堆管理、HTTP 客户端）
- **功能描述**: 简洁明了（基础输出、内存分配、同步接收）
- **可选说明**: 括号中注明特殊模式（DMA 模式、中断模式）

**正确示例:**

```markdown
✅ # LISA GPIO 基础输出示例
✅ # 系统堆管理基础示例
✅ # LISA UART 同步接收示例（DMA 模式）
✅ # HTTP 客户端基础示例
```

**错误示例:**

```markdown
❌ # gpio example (未使用中文，未规范化模块名)
❌ # LISA_GPIO 基础示例 (模块名使用下划线)
❌ # GPIO 示例 (缺少 LISA 前缀)
```

### 2. 功能说明（H2，必需）

**格式:**

```markdown
## 功能说明

{第一段：核心功能说明（1-2 句话）}

{第二段：可选补充说明（技术特点/底层实现）}
```

**内容要求:**

1. **第一段**（必需）:
   - 1-2 句话说明核心功能
   - 40-200 字为宜
   - 说明"做什么"和"怎么做"

2. **第二段**（可选）:
   - 补充技术特点或实现细节
   - 突出技术优势或注意事项

**正确示例:**

```markdown
## 功能说明

演示如何使用 LISA GPIO 驱动控制 LED 闪烁，通过配置引脚为输出模式，周期性输出高低电平实现 LED 的亮灭切换。
```

```markdown
## 功能说明

演示如何使用系统堆管理组件分配和释放内存，包括内部 SRAM 和外部 PSRAM 的基本操作。
```

```markdown
## 功能说明

此示例演示如何使用 LISA HTTP 客户端库进行基本的 HTTP 通信，包括：
- HTTP GET 请求
- HTTP POST 请求（普通表单数据）
- HTTP POST 请求（Chunked 传输编码）

示例通过 WiFi 连接到测试服务器，执行多个 HTTP 请求并接收响应，展示了 HTTP 客户端的基本用法。
```

**错误示例:**

```markdown
❌ ## 功能说明

This example shows... (使用英文)

❌ ## 功能说明

本示例功能强大，非常好用，可以实现各种复杂的操作... (描述过于笼统，未说明具体功能)
```

### 3. 新特性（H3，可选）

**使用时机:**

- 高级示例（DMA、中断、异步等）
- 有明显技术优势需要突出
- 与基础示例有显著差异

**格式:**

```markdown
### 新特性

- **特性1**: 简短说明
- **特性2**: 简短说明
- **特性3**: 简短说明
```

**内容要求:**

- 使用无序列表
- 每项开头用 **粗体** 标注特性名称
- 3-5 项为宜
- 每项一行，简洁明了

**正确示例:**

```markdown
### 新特性

- **DMA 硬件传输**: 无需 CPU 参与数据搬移，降低 CPU 占用
- **异步非阻塞**: 调用后立即返回，DMA 后台传输
- **事件回调通知**: 传输完成后通过中断回调通知应用层
- **适合高速率场景**: 支持高波特率连续发送，不阻塞主任务
```

### 4. 硬件连接（H2，必需）

**格式（有外部连接）:**

```markdown
## 硬件连接

- **引脚编号**: 功能说明
- **引脚编号**: 功能说明

{补充说明（可选）}
```

**格式（无外部连接）:**

```markdown
## 硬件连接

无需外部连接，{模块}为芯片内部资源。
```

**内容要求:**

1. **引脚说明**:
   - 使用无序列表
   - 引脚编号用 **粗体**
   - 说明引脚功能和用途

2. **补充说明**:
   - 连接方式、配置参数
   - 外部设备要求
   - 硬件注意事项

**正确示例（有连接）:**

```markdown
## 硬件连接

- **PB09**: LED 控制引脚（外接 LED 与限流电阻，ARCS-EVB 板载接口）

将 LED 正极（长脚）通过限流电阻（推荐 220Ω-1kΩ）连接到 PB09 引脚，负极（短脚）连接到 GND。
```

```markdown
## 硬件连接

- **PA2**: UART0 RX（接收）
- **PA3**: UART0 TX（发送）

连接到 PC 串口工具，配置为 **115200, 8N1, 无流控**
```

**正确示例（无连接）:**

```markdown
## 硬件连接

无需外部连接，系统堆为芯片内部资源。
```

```markdown
## 硬件连接

本示例使用芯片内部 WiFi 外设，无需额外接线。

**串口输出：**
- 串口 TX: PA3
- 波特率：921600
```

### 5. 示例内容/步骤（H2，必需）

**标题选择:**

- `## 示例内容`: 用于功能演示类示例
- `## 示例步骤`: 用于操作流程类示例

**格式:**

```markdown
## 示例内容

1. 步骤1描述
2. 步骤2描述
3. 步骤3描述
4. 步骤4描述
```

**内容要求:**

- 使用有序列表（编号列表）
- 3-6 个步骤为宜
- 每步简洁明了，突出关键操作
- 按执行顺序排列

**正确示例:**

```markdown
## 示例内容

1. 从内部 SRAM 分配 256 字节内存
2. 从外部 PSRAM 分配 1024 字节内存
3. 使用 `psram_calloc()` 分配并清零内存
4. 使用 `psram_realloc()` 重新分配内存
5. 查看堆使用统计信息
```

```markdown
## 示例步骤

1. 获取 GPIOB 设备
2. 配置 PB09 引脚为输出模式，初始电平为低
3. 循环切换引脚输出电平（高/低）
4. 每次切换间隔 1 秒，实现 LED 闪烁效果
```

### 6. 编译/运行（H2，必需）

**标题选择:**

- `## 编译`: 仅说明编译（推荐）
- `## 编译运行`: 包含编译和运行
- `## 编译` + 独立 `## 烧录`: 编译和烧录分开（推荐）

**推荐格式（使用 RST 引用）:**

```markdown
## 编译

​```{eval-rst}
.. include:: /sample_build.rst
​```

## 烧录

​```{eval-rst}
.. include:: /sample_flash.rst
​```
```

**说明:**

- 统一使用 RST 引用文件，保持格式一致性
- `/sample_build.rst` 包含标准编译命令
- `/sample_flash.rst` 包含标准烧录命令
- 分开成两个独立的 H2 章节（`## 编译` 和 `## 烧录`）

**备选格式（直接写命令）:**

如果需要特殊的编译参数或说明，可以直接写命令：

```markdown
## 编译

​```bash
./build.sh -C -DBOARD=arcs_evb
​```

## 烧录

​```bash
./build.sh -F
​```
```

**合并格式（不推荐）:**

```markdown
## 编译运行

### 编译

​```{eval-rst}
.. include:: /sample_build.rst
​```

### 烧录

​```{eval-rst}
.. include:: /sample_flash.rst
​```
```

**注意:**
- 优先使用 RST 引用格式，除非有特殊说明需要
- 编译和烧录建议分为两个独立的 H2 章节，而不是使用 H3 子章节

### 7. 预期输出（H2，必需）

**格式（单一输出源）:**

```markdown
## 预期输出

​```
[I][sample] === Example Output ===
...
​```
```

**格式（多个输出源）:**

```markdown
## 预期输出

**终端输出：**
​```
[I][sample] === Example Output ===
...
​```

**串口工具接收：**
​```
Hello World
...
​```

**LED 状态：**
- LED 每秒切换一次亮灭状态
```

**内容要求:**

1. **真实输出**: 必须与实际运行结果一致
2. **完整性**: 包含关键日志，可用 `...` 省略重复部分
3. **格式**: 使用代码块，保持原始格式
4. **分类**: 多个输出源用 **粗体标题** 分隔

**正确示例:**

```markdown
## 预期输出

**终端输出：**
​```
=== LISA GPIO output example ===
gpiob device ready
Start toggling LED...
LED is ON
LED is OFF
LED is ON
LED is OFF
...
​```

**LED 状态：**
- LED 每秒切换一次亮灭状态
- 亮时对应高电平输出，灭时对应低电平输出
```

### 8. 核心 API（H2，强烈推荐）

**使用场景:**

- 设备驱动示例（Devices）
- 组件模块示例（Modules）
- 有明确 API 调用的示例

**格式:**

```markdown
## 核心 API

| API | 说明 |
|-----|------|
| `api_function_1()` | 功能说明1 |
| `api_function_2()` | 功能说明2 |
| `api_function_3()` | 功能说明3 |
```

**内容要求:**

1. **使用表格**: 固定两列格式
2. **API 名称**: 使用反引号 `包裹，保留括号 `()`
3. **顺序**: 按调用顺序排列
4. **数量**: 3-8 个关键 API
5. **说明**: 简洁准确，动词开头

**正确示例:**

```markdown
## 核心 API

| API | 说明 |
|-----|------|
| `lisa_device_get()` | 获取 GPIO 设备 |
| `lisa_device_ready()` | 检查设备是否就绪 |
| `lisa_gpio_configure()` | 配置 GPIO 引脚模式和属性 |
| `lisa_gpio_write_pin()` | 设置 GPIO 引脚输出电平 |
```

```markdown
## 核心 API

| API | 说明 |
|-----|------|
| `inram_malloc()` | 从内部 SRAM 分配内存 |
| `inram_free()` | 释放内部 SRAM 内存 |
| `psram_malloc()` | 从 PSRAM 分配内存 |
| `psram_calloc()` | 从 PSRAM 分配并清零内存 |
| `psram_realloc()` | 重新分配 PSRAM 内存 |
| `psram_free()` | 释放 PSRAM 内存 |
| `heap_summary_info()` | 打印堆统计信息 |
```

### 9. 关键代码（H2，强烈推荐）

**使用场景:**

- 有重要配置或技巧需要展示
- 代码包含关键 API 调用序列
- 需要解释复杂代码逻辑

**格式:**

```markdown
## 关键代码

​```c
/* 注释说明 */
code_block();

/* 注释说明 */
another_code_block();
​```
```

**内容要求:**

1. **语言标注**: 必须指定 `c`
2. **注释**: 关键代码添加中文注释
3. **完整性**: 代码片段可独立理解
4. **简洁性**: 省略无关代码，突出重点

**正确示例:**

```markdown
## 关键代码

​```c
/* 配置为输出模式，初始电平为低 */
int ret = lisa_gpio_configure(gpio_dev, LED_PIN,
                              LISA_GPIO_OUTPUT | LISA_GPIO_OUTPUT_INIT_LOW);

/* 循环切换 LED 状态 */
bool led_on = true;
while (1) {
    lisa_gpio_write_pin(gpio_dev, LED_PIN,
                        led_on ? LISA_GPIO_HIGH : LISA_GPIO_LOW);
    LISA_LOGI(LOG_TAG, "LED is %s", led_on ? "ON" : "OFF");
    vTaskDelay(pdMS_TO_TICKS(1000));
    led_on = !led_on;
}
​```
```

### 10. 配置说明（H2，可选）

**使用场景:**

- 有重要配置参数
- 配置有特殊要求或限制
- Kconfig 配置项说明

**格式:**

```markdown
## 配置说明

### 配置项1名称

{说明内容}

- **配置1**: 说明
- **配置2**: 说明

### 配置项2名称

{说明内容}
```

**正确示例:**

```markdown
## 配置说明

### 堆大小配置

在 Kconfig 中可配置堆大小（组件默认已配置）：

- **`CONFIG_HEAP_SIZE`**: 内部 SRAM 堆大小，默认 0x5000 (20KB)
- **`CONFIG_PSRAM_HEAP_SIZE`**: PSRAM 堆大小，默认 0x20000 (128KB)

### 对齐要求

- **`inram_malloc(align, size)`**: `align` 参数指定对齐字节数，必须是 2 的幂次方（4, 8, 16, 32 等）
- **`psram_malloc(size)`**: 默认 4 字节对齐
- **`psram_malloc_align(align, size)`**: 指定对齐字节数，用于 DMA 等需要特定对齐的场景
```

### 11. 注意事项（H2，强烈推荐）

**使用场景:**

- 所有示例都应包含
- 有重要限制或约束
- 常见错误提醒

**格式:**

```markdown
## 注意事项

1. **关键词1**: 详细说明
2. **关键词2**: 详细说明
3. **关键词3**: 详细说明
```

**内容要求:**

1. **使用有序列表**
2. **关键词粗体**: 每项开头用 **粗体** 标注关键词
3. **数量**: 3-5 项为宜
4. **内容**: 安全、限制、易错点、最佳实践

**正确示例:**

```markdown
## 注意事项

1. **返回值检查**: 分配内存后务必检查返回值是否为 NULL，防止使用无效指针
2. **内存释放**: 使用完毕后及时释放内存，避免内存泄漏
3. **对齐参数**: `align` 参数必须是 2 的幂次方，否则会导致对齐错误
4. **自动初始化**: 系统堆在 main 函数前自动初始化，无需手动调用
5. **线程安全**: 所有堆分配接口都是线程安全的，可在多任务环境下使用
```

---

## 不同类型示例的差异

### Devices（设备驱动示例）

**特征:**

- 使用 LISA 设备驱动 API
- 必需硬件连接说明
- 强调引脚配置和参数

**必需章节:**

- ✅ 硬件连接（详细引脚说明）
- ✅ 核心 API（LISA 设备 API）
- ✅ 注意事项（硬件相关限制）

**可选章节:**

- 配置说明（参数配置）
- 验证方法（硬件验证）

**示例:** [lisa_gpio/output_basic](samples/drivers/devices/lisa_gpio/output_basic/)

### Modules（组件模块示例）

**特征:**

- 系统组件/中间件
- 可能无硬件依赖
- 注重 API 使用方法

**必需章节:**

- ✅ 功能说明（详细功能说明）
- ✅ 核心 API（组件 API）
- ✅ 关键代码（使用示例）

**可选章节:**

- 配置说明（Kconfig 配置）
- 使用场景（应用场景）

**示例:** [modules/sys_heap](samples/modules/sys_heap/), [modules/lisa_shell](samples/modules/lisa_shell/)

### Network（网络示例）

**特征:**

- 涉及网络协议
- 需要环境配置
- 包含连接建立过程

**必需章节:**

- ✅ 功能说明（网络功能）
- ✅ 测试环境准备（环境配置）
- ✅ 预期输出（网络交互日志）

**可选章节:**

- 核心 API（网络 API）
- 配置说明（网络参数）

**示例:** [network/http](samples/network/http/)

### HAL（硬件抽象层示例）

**特征:**

- 底层硬件接口
- 使用表情符号标题（历史原因）
- 简洁实用

**必需章节:**

- ✅ 📖示例说明（功能说明）
- ✅ 硬件连接
- ✅ 预期输出

**特殊规则:**

- 可使用 `📖示例说明` 替代 `功能说明`
- 通常不包含核心 API 章节

---

## 格式规范

### 文档格式选择

#### Markdown 格式 (README.md) - 推荐

**优点:**
- 语法简洁，易于学习和编写
- GitHub/GitLab 原生支持预览
- 工具链完善

**适用场景:**
- 大部分示例文档
- 结构简单的文档

#### reStructuredText 格式 (README.rst) - 可选

**优点:**
- 功能强大，支持复杂文档结构
- Sphinx 文档系统原生格式
- 适合技术文档

**适用场景:**
- 需要复杂表格或指令的文档
- 需要与 Sphinx 文档系统集成

**选择建议:** 优先使用 Markdown，除非有特殊需求。

---

### Markdown 语法规范

#### 1. 标题层级

```markdown
# H1 - 文档标题（只能有一个）
## H2 - 主要章节
### H3 - 子章节
#### H4 - 更小的子章节（慎用）
```

**规则:**

- H1 只能有一个（文档标题）
- H2 用于主要章节
- H3 用于子章节（如"新特性"、配置项）
- 避免使用 H4 及以下层级

#### RST 等价语法

```rst
标题（H1）
=========

章节（H2）
---------

子章节（H3）
^^^^^^^^^^^
```

#### 2. 代码块

**Markdown 格式:**

```markdown
​```c
// C 代码
​```

​```bash
# Bash 命令
​```

​```
纯文本输出
​```
```

**RST 格式:**

```rst
.. code-block:: c

   // C 代码

.. code-block:: bash

   # Bash 命令

.. code-block:: text

   纯文本输出
```

**语言标注要求:**

- `c`: C 语言代码
- `bash`: Shell 命令
- `text` (RST) 或无标注 (Markdown): 纯文本输出

#### 3. 行内代码标记

**Markdown 格式:**

```markdown
使用 `lisa_gpio_configure()` 配置引脚。
配置项 `CONFIG_HEAP_SIZE` 的默认值是 0x5000。
变量 `gpio_dev` 保存设备句柄。
```

**RST 格式:**

```rst
使用 ``lisa_gpio_configure()`` 配置引脚。
配置项 ``CONFIG_HEAP_SIZE`` 的默认值是 0x5000。
变量 ``gpio_dev`` 保存设备句柄。
```

**规则:**

- API 函数名保留括号: `function()` (Markdown) 或 ``function()`` (RST)
- 配置项宏定义: `CONFIG_NAME`
- 变量名: `variable_name`

#### 4. 粗体使用

**关键概念、重要信息:**

```markdown
- **返回值检查**: 务必检查返回值
- **内存对齐**: 必须 **32 字节对齐**
连接到 PC 串口工具，配置为 **115200, 8N1, 无流控**
```

**规则:**

- 注意事项的关键词
- 重要参数值
- 强调的概念

#### 5. 表格格式

**Markdown 格式:**

```markdown
| 列1标题 | 列2标题 |
|---------|---------|
| 内容1   | 说明1   |
| 内容2   | 说明2   |
```

**RST 格式:**

```rst
.. list-table::
   :header-rows: 1

   * - 列1标题
     - 列2标题
   * - 内容1
     - 说明1
   * - 内容2
     - 说明2
```

**规则:**

- Markdown: 使用对齐的 `|` 分隔符，第二行用 `-` 分隔标题和内容
- RST: 使用 `.. list-table::` 指令，`:header-rows: 1` 指定标题行
- API 表格固定格式: `| API | 说明 |` (Markdown) 或对应的 RST list-table

#### 6. 列表格式

**有序列表（步骤、注意事项）:**

```markdown
1. 第一步
2. 第二步
3. 第三步
```

**无序列表（特性、引脚、配置）:**

```markdown
- 项目1
- 项目2
- 项目3
```

**子列表（2 空格缩进）:**

```markdown
- 父项目
  - 子项目1
  - 子项目2
```

### 语言规范

#### 1. 中英文使用规则

| 位置 | 语言 | 示例 |
|------|------|------|
| 文档正文 | 中文 | 演示如何使用... |
| 代码注释 | 中文 | `/* 配置引脚为输出模式 */` |
| API 名称 | 英文 | `lisa_gpio_configure()` |
| 配置项 | 英文 | `CONFIG_HEAP_SIZE` |
| 日志输出 | 英文 | `LISA_LOGI(LOG_TAG, "Device ready");` |
| 代码变量 | 英文 | `uint8_t *buffer;` |

#### 2. 术语标准表达

**模块名称:**

- ✅ LISA GPIO（正确）
- ❌ lisa_gpio, GPIO, lisa gpio（错误）

**技术术语:**

- ✅ DMA 模式（正确）
- ❌ dma 模式, Dma 模式（错误）

- ✅ 中断模式（正确）
- ❌ INT 模式, interrupt 模式（错误）

- ✅ 同步/异步（正确）
- ❌ sync/async（仅在代码中使用）

**一致性原则:**

同一概念在整篇文档中必须使用统一术语，不能混用。

#### 3. 中英文混排

**规则:**

中英文之间通常不加空格（除非是完整英文句子）。

**示例:**

```markdown
✅ 使用`lisa_gpio_configure()`配置引脚为输出模式。
✅ 使用 `lisa_gpio_configure()` 配置引脚为输出模式。
✅ 配置项`CONFIG_HEAP_SIZE`的默认值是 0x5000。
```

---

## AI 生成文档指南

### 生成流程

当 AI 收到"生成示例文档"的任务时，按以下流程操作：

#### 第一步：确定示例类型

```
问题：这是哪种类型的示例？
选项：
- Devices（设备驱动）
- Modules（组件模块）
- Network（网络示例）
- HAL（硬件抽象层）
```

#### 第二步：确定复杂度

```
问题：这是基础示例还是高级示例？
- 基础示例：使用基础模板，包含必需章节
- 高级示例：使用高级模板，增加"新特性"、"使用场景"等章节
```

#### 第三步：收集信息

```
收集以下信息：
1. 模块名称（如：LISA GPIO、系统堆管理）
2. 功能描述（如：基础输出、内存分配）
3. 硬件连接（引脚信息或"无需外部连接"）
4. 示例步骤（3-6 个关键步骤）
5. 核心 API（3-8 个关键 API 及说明）
6. 预期输出（实际日志或输出描述）
7. 注意事项（3-5 个关键限制或提醒）
```

#### 第四步：选择模板

根据类型和复杂度选择合适模板：

```
基础示例模板：
- 标题
- 功能说明
- 硬件连接
- 示例内容
- 编译（使用 RST 引用）
- 烧录（使用 RST 引用）
- 预期输出
- 核心 API
- 关键代码
- 注意事项

高级示例模板：
- 标题
- 功能说明
  - 新特性（H3）
- 硬件连接
- 使用场景
- 示例步骤
- 编译（使用 RST 引用）
- 烧录（使用 RST 引用）
- 预期输出
- 核心 API
- 功能详解
- 关键代码
- 配置说明
- 注意事项
```

#### 第五步：填充内容

按模板顺序填充各章节，确保：

1. **标题格式正确**: `# {模块} {功能}示例`
2. **功能说明简洁**: 1-2 句话
3. **硬件连接完整**: 引脚信息或明确说明"无需外部连接"
4. **步骤清晰有序**: 使用有序列表
5. **编译和烧录**: 使用 RST 引用格式（`.. include:: /sample_build.rst` 和 `.. include:: /sample_flash.rst`）
6. **API 表格规范**: 使用标准表格格式
7. **代码块标注语言**: `c`、`bash` 或无标注
8. **注意事项完整**: 3-5 项，关键词粗体

#### 第六步：自检

生成后对照"AI 审查文档清单"自检。

### 生成示例模板

#### 基础示例模板

```markdown
# {模块名称} {功能描述}示例

## 功能说明

{1-2 句话说明核心功能}

## 硬件连接

- **引脚1**: 功能说明
- **引脚2**: 功能说明

或：

无需外部连接，{模块}为芯片内部资源。

## 示例内容

1. 步骤1
2. 步骤2
3. 步骤3
4. 步骤4

## 编译

​```{eval-rst}
.. include:: /sample_build.rst
​```

## 烧录

​```{eval-rst}
.. include:: /sample_flash.rst
​```

## 预期输出

​```
[I][sample] === Example Output ===
{实际输出内容}
​```

## 核心 API

| API | 说明 |
|-----|------|
| `api_1()` | 功能说明1 |
| `api_2()` | 功能说明2 |
| `api_3()` | 功能说明3 |

## 关键代码

​```c
/* 关键代码片段 */
code_example();
​```

## 注意事项

1. **关键词1**: 说明
2. **关键词2**: 说明
3. **关键词3**: 说明
```

#### 高级示例模板

```markdown
# {模块名称} {功能描述}示例（{模式说明}）

## 功能说明

{1-2 句话说明核心功能}

### 新特性

- **特性1**: 说明
- **特性2**: 说明
- **特性3**: 说明

## 硬件连接

- **引脚1**: 功能说明
- **引脚2**: 功能说明

{补充连接说明}

## 使用场景

{适用场景和技术选型说明}

## 示例步骤

1. 步骤1
2. 步骤2
3. 步骤3
4. 步骤4

## 编译

​```{eval-rst}
.. include:: /sample_build.rst
​```

## 烧录

​```{eval-rst}
.. include:: /sample_flash.rst
​```

## 预期输出

**终端输出：**
​```
[I][sample] === Example Output ===
{输出内容}
​```

**{其他输出源}：**
{描述}

## 核心 API

| API | 说明 |
|-----|------|
| `api_1()` | 功能说明1 |
| `api_2()` | 功能说明2 |
| `api_3()` | 功能说明3 |

## {功能}说明

{详细说明工作原理和特性}

## 关键代码

​```c
/* 关键代码片段 */
code_example();
​```

## 配置说明

### 配置项1

{说明}

### 配置项2

{说明}

## 注意事项

1. **关键词1**: 说明
2. **关键词2**: 说明
3. **关键词3**: 说明
4. **关键词4**: 说明
```

---

## AI 审查文档清单

当 AI 收到"检查示例文档"的任务时，使用以下清单逐项检查：

### 结构检查

```
□ 标题（H1）存在且格式正确
□ 功能说明（H2）存在且简洁（1-2 句话，40-200 字）
□ 硬件连接（H2）存在且完整（有引脚信息或明确说明无需连接）
□ 示例内容/步骤（H2）存在且使用有序列表
□ 编译（H2）存在且使用 RST 引用（推荐）或包含构建命令
□ 烧录（H2）存在且使用 RST 引用（推荐）或包含烧录命令
□ 预期输出（H2）存在且非空
□ 核心 API（H2）存在（Devices/Modules 类型）
□ 注意事项（H2）存在且有 3-5 项
□ 章节顺序符合规范
```

### 格式检查

```
□ 文档格式正确（Markdown .md 或 RST .rst）
□ 所有代码块指定了语言（c/bash/text）
□ 编译和烧录使用引用格式（Markdown 用 eval-rst，RST 用 include 指令）
□ API 名称使用正确标记（Markdown 用 `，RST 用 ``）
□ 核心 API 使用标准表格格式（Markdown 表格或 RST list-table）
□ 注意事项使用有序列表，关键词用粗体（Markdown **粗体**，RST **粗体**）
□ 引脚编号用粗体（Markdown **PB09**，RST **PB09**）
□ 中英文混排符合规范
□ 无过深层级标题（避免 H4/H5 或 RST 过多下划线层级）
□ 编译和烧录为独立章节（不使用子章节）
□ 格式内部保持一致（不混用 Markdown 和 RST 语法）
```

### 内容检查

```
□ 标题格式：{模块} {功能}示例
□ 功能说明不超过 200 字
□ 硬件连接有具体引脚或明确说明无需连接
□ 示例步骤有 3-6 项
□ 预期输出与代码一致（如果有源代码）
□ API 表格有 3-8 项，按调用顺序排列
□ 注意事项包含重要限制和易错点
□ 术语使用一致（如：DMA 模式，不是 dma 模式）
```

### 语言检查

```
□ 文档正文使用中文
□ API 名称使用英文
□ 代码注释使用中文
□ 日志输出使用英文
□ 术语表达标准化（LISA GPIO、DMA 模式、中断模式）
□ 同一概念术语统一，无混用
```

### 类型特定检查

**Devices（设备驱动）:**

```
□ 标题使用 LISA 前缀（如：LISA GPIO）
□ 硬件连接详细（引脚编号、功能、接线方式）
□ 核心 API 包含 lisa_device_get() 等设备 API
□ 注意事项包含硬件相关限制
```

**Modules（组件模块）:**

```
□ 功能说明详细说明组件功能
□ 硬件连接说明"无需外部连接"（如适用）
□ 核心 API 包含组件关键 API
□ 可选：配置说明章节（Kconfig）
```

**Network（网络示例）:**

```
□ 功能说明包含网络协议/功能
□ 可选：测试环境准备章节
□ 预期输出包含网络交互日志
□ 注意事项包含网络环境要求
```

### 审查报告格式

AI 检查后应输出以下格式的报告：

```markdown
# 文档审查报告

**文档路径**: {文件路径}
**示例类型**: {Devices/Modules/Network/HAL}
**审查日期**: {日期}

## 审查结果

**总体评分**: {通过/需修改/不合格}

## 问题清单

### 必需修改（阻塞问题）

1. **[结构]** {问题描述}
   - **位置**: {章节名称}
   - **问题**: {具体问题}
   - **建议**: {修改建议}

2. **[格式]** {问题描述}
   - **位置**: {章节名称/行号}
   - **问题**: {具体问题}
   - **建议**: {修改建议}

### 建议优化（非阻塞）

1. **[内容]** {问题描述}
   - **位置**: {章节名称}
   - **建议**: {优化建议}

## 符合规范项

✅ 标题格式正确
✅ 功能说明简洁
✅ 章节顺序符合规范
...

## 总结

{总体评价和建议}
```

---

## 附录

### 附录 A：常见问题

#### Q1: 何时使用"示例内容"vs"示例步骤"？

**A**:
- **示例内容**: 用于功能演示类示例，列出演示的功能点
- **示例步骤**: 用于操作流程类示例，列出执行的步骤

示例：
```markdown
## 示例内容（功能演示）
1. 从内部 SRAM 分配内存
2. 从外部 PSRAM 分配内存
3. 使用 calloc 分配并清零内存

## 示例步骤（操作流程）
1. 获取 UART 设备
2. 配置 UART 参数
3. 发送数据并等待完成
```

#### Q2: 何时添加"新特性"章节？

**A**:
- 高级示例（DMA、中断、异步等）
- 有明显技术优势需要突出
- 与基础示例有显著差异

#### Q3: 硬件连接章节可以省略吗？

**A**:
不可以。所有示例都必须包含硬件连接章节，即使无需外部连接，也应明确说明"无需外部连接，{模块}为芯片内部资源"。

#### Q4: 预期输出必须包含实际日志吗？

**A**:
是的。预期输出必须与实际运行结果一致。如果输出很长，可以使用 `...` 省略重复部分，但关键日志必须包含。

#### Q5: 核心 API 章节是必需的吗？

**A**:
强烈推荐，特别是 Devices 和 Modules 类型示例。Network 和 HAL 类型可根据情况选择。

### 附录 B：术语对照表

| 中文术语 | 英文术语 | 使用场景 |
|----------|----------|----------|
| 设备驱动 | Device Driver | 文档正文 |
| 组件模块 | Module | 文档正文 |
| 引脚 | Pin | 硬件连接 |
| 中断模式 | Interrupt Mode | 功能说明 |
| DMA 模式 | DMA Mode | 功能说明 |
| 同步发送 | Synchronous Send | 功能说明 |
| 异步发送 | Asynchronous Send | 功能说明 |
| 循环缓冲区 | Circular Buffer | 技术说明 |
| 串口工具 | Serial Tool | 硬件连接 |
| 波特率 | Baud Rate | 配置说明 |
| 占空比 | Duty Cycle | PWM 相关 |
| 内存对齐 | Memory Alignment | 配置说明 |

### 附录 C：Markdown 与 RST 格式对照

#### 基本语法对照表

| 元素 | Markdown | RST |
|------|----------|-----|
| H1 标题 | `# 标题` | `标题\n====` |
| H2 标题 | `## 标题` | `标题\n----` |
| H3 标题 | `### 标题` | `标题\n^^^^` |
| 行内代码 | `` `code` `` | ``` ``code`` ``` |
| 代码块 | ` ```c\ncode\n``` ` | `.. code-block:: c\n\n   code` |
| 粗体 | `**粗体**` | `**粗体**` |
| 链接 | `[text](url)` | `` `text <url>`_ `` |
| 表格 | Markdown table | `.. list-table::` |
| Include | `{eval-rst}\n.. include::` | `.. include::` |

#### 完整示例对照

**Markdown 版本:**
```markdown
# LISA GPIO 基础输出示例

## 功能说明

演示如何使用 `lisa_gpio_configure()` 配置引脚。

## 编译

​```{eval-rst}
.. include:: /sample_build.rst
​```

## 核心 API

| API | 说明 |
|-----|------|
| `lisa_device_get()` | 获取设备 |
```

**RST 版本:**
```rst
LISA GPIO 基础输出示例
======================

功能说明
--------

演示如何使用 ``lisa_gpio_configure()`` 配置引脚。

.. include:: /sample_build.rst

核心 API
--------

.. list-table::
   :header-rows: 1

   * - API
     - 说明
   * - ``lisa_device_get()``
     - 获取设备
```

### 附录 D：示例文档索引

**优秀示例文档（推荐参考）:**

- **Devices (Markdown)**:
  - [samples/drivers/devices/lisa_gpio/output_basic/README.md](samples/drivers/devices/lisa_gpio/output_basic/README.md)
  - [samples/drivers/devices/lisa_uart/send_async_dma/README.md](samples/drivers/devices/lisa_uart/send_async_dma/README.md)

- **Modules (Markdown)**:
  - [samples/modules/sys_heap/README.md](samples/modules/sys_heap/README.md)
  - [samples/modules/lisa_shell/README.md](samples/modules/lisa_shell/README.md)

- **Network (Markdown)**:
  - [samples/network/http/README.md](samples/network/http/README.md)

- **Basic (RST)**:
  - [samples/helloworld/README.rst](samples/helloworld/README.rst)

### 附录 E：版本历史

| 版本 | 日期 | 变更说明 |
|------|------|----------|
| 1.0 | 2025-01-15 | 初始版本（Samples_Spec.md） |
| 2.0 | 2025-01-14 | AI 辅助版，基于 114 个示例文档分析 |
| 2.1 | 2025-01-14 | 支持 Markdown 和 RST 两种格式 |

**主要变更（2.1）:**

1. **支持双格式**: 允许使用 Markdown (.md) 或 reStructuredText (.rst)
2. **格式对照**: 新增附录 C - Markdown 与 RST 格式对照表
3. **审查清单更新**: 格式检查项适配双格式要求
4. **语法规范**: 补充 RST 格式的等价语法说明
5. **示例索引**: 新增 RST 格式示例文档引用

**主要变更（2.0）:**

1. 基于实际分析数据（114 个 README.md）
2. 明确不同类型示例的差异和特殊规则
3. 新增 AI 生成文档指南
4. 新增 AI 审查文档清单
5. 详细格式规范和示例
6. 新增常见问题和术语对照表

---

**维护者**: ARCS SDK 团队
**联系方式**: sdk@listenai.com
**最后更新**: 2025-01-14