169 lines
4.4 KiB
Markdown
169 lines
4.4 KiB
Markdown
---
|
||
name: sample-doc-review
|
||
description: 使用 Samples_Spec.md 规范对示例文档进行全面审查，生成详细审查报告
|
||
---
|
||
|
||
# 示例文档审查器
|
||
|
||
基于 `samples/Samples_Spec.md` 规范对 ARCS SDK 示例文档进行全面审查，检查结构、格式、内容和语言规范性。
|
||
|
||
## 快速使用
|
||
|
||
直接在对话中使用以下任一方式触发：
|
||
|
||
```
|
||
审查 samples/modules/sys_heap/README.md
|
||
检查 lisa_gpio 示例文档
|
||
审查 sys_heap
|
||
```
|
||
|
||
## 执行步骤
|
||
|
||
### 1. 读取规范文档
|
||
|
||
**必须先读取** `samples/Samples_Spec.md` 文件，获取完整的审查标准：
|
||
- 标准章节结构和顺序
|
||
- 各章节的详细规范
|
||
- 不同类型示例的差异要求
|
||
- 格式规范
|
||
- 语言规范
|
||
- AI 审查文档清单
|
||
|
||
### 2. 确定示例文档路径
|
||
|
||
- 如果用户提供了文档路径，直接使用
|
||
- 如果用户只提供了示例名称（如 "sys_heap"），在 `samples/` 目录下搜索对应的 README.md
|
||
- 显示找到的文档路径供用户确认
|
||
|
||
### 3. 读取并分析目标文档
|
||
|
||
- 读取目标 README.md 文件
|
||
- 根据路径自动识别示例类型：
|
||
- `samples/drivers/devices/` → Devices
|
||
- `samples/modules/` → Modules
|
||
- `samples/network/` → Network
|
||
- `samples/drivers/hal/` → HAL
|
||
|
||
### 4. 执行全面检查
|
||
|
||
严格按照 `Samples_Spec.md` 中的 **"AI 审查文档清单"** 部分逐项检查：
|
||
|
||
1. **结构检查**（10 项）
|
||
2. **格式检查**（9 项）
|
||
3. **内容检查**（8 项）
|
||
4. **语言检查**（6 项）
|
||
5. **类型特定检查**（根据示例类型）
|
||
|
||
### 5. 生成审查报告
|
||
|
||
使用 `Samples_Spec.md` 中定义的 **"审查报告格式"** 生成报告：
|
||
|
||
```markdown
|
||
# 文档审查报告
|
||
|
||
**文档路径**: {文件路径}
|
||
**示例类型**: {Devices/Modules/Network/HAL}
|
||
**审查日期**: {日期}
|
||
|
||
## 审查结果
|
||
|
||
**总体评分**: {通过/需修改/不合格}
|
||
|
||
## 问题清单
|
||
|
||
### 必需修改（阻塞问题）
|
||
|
||
{列出所有阻塞问题}
|
||
|
||
### 建议优化（非阻塞）
|
||
|
||
{列出所有优化建议}
|
||
|
||
## 符合规范项
|
||
|
||
{列出所有通过的检查项}
|
||
|
||
## 总结
|
||
|
||
{总体评价和建议}
|
||
```
|
||
|
||
## 评分标准
|
||
|
||
参考 `Samples_Spec.md` 的规范，但具体标准如下：
|
||
|
||
- **通过**：无阻塞问题，建议优化 ≤ 3 个
|
||
- **需修改**：有 1-3 个阻塞问题
|
||
- **不合格**：有 >3 个阻塞问题
|
||
|
||
### 阻塞问题定义
|
||
|
||
以下属于阻塞问题（必须修改）：
|
||
|
||
1. 缺少必需章节
|
||
2. 标题格式严重错误
|
||
3. 章节顺序严重混乱
|
||
4. 核心 API 章节缺失（Devices/Modules 类型）
|
||
5. 代码块未标注语言
|
||
6. API 表格格式错误
|
||
|
||
其他问题归为建议优化。
|
||
|
||
## 更多触发方式
|
||
|
||
### 完整路径
|
||
```
|
||
审查 samples/drivers/devices/lisa_uart/send_async_dma/README.md
|
||
帮我审查 http 示例文档是否符合规范
|
||
```
|
||
|
||
### 使用关键词
|
||
```
|
||
使用规范审查 sys_heap 示例
|
||
对 lisa_gpio 文档进行规范检查
|
||
验证 http 示例文档的规范性
|
||
```
|
||
|
||
## 使用示例
|
||
|
||
### 示例 1: 审查指定路径
|
||
|
||
```
|
||
用户：审查 samples/modules/sys_heap/README.md
|
||
AI：[读取规范] → [读取文档] → [识别类型: Modules] → [执行检查] → [生成报告]
|
||
```
|
||
|
||
### 示例 2: 根据名称查找
|
||
|
||
```
|
||
用户：审查 sys_heap 示例文档
|
||
AI：找到文档：samples/modules/sys_heap/README.md
|
||
类型：Modules
|
||
[开始审查...]
|
||
```
|
||
|
||
### 示例 3: 批量审查
|
||
|
||
```
|
||
用户：审查 samples/drivers/devices/lisa_gpio/ 下的所有文档
|
||
AI：找到 3 个文档：
|
||
- output_basic/README.md
|
||
- input_basic/README.md
|
||
- interrupt/README.md
|
||
[逐个审查...]
|
||
```
|
||
|
||
## 特别注意
|
||
|
||
1. **规范引用**：所有检查标准以 `Samples_Spec.md` 为准，不要使用过时规范
|
||
2. **类型识别**：必须正确识别示例类型，应用对应的特定检查
|
||
3. **详细定位**：问题描述要包含章节名称和行号（如果适用）
|
||
4. **具体建议**：提供可直接应用的修改示例
|
||
5. **RST 引用检查**：编译和烧录章节优先推荐使用 `.. include:: /sample_build.rst` 和 `.. include:: /sample_flash.rst`
|
||
|
||
## 特殊情况处理
|
||
|
||
- **HAL 示例**：允许使用 `📖示例说明` 替代 `功能说明`，在报告中注明即可
|
||
- **特殊编译参数**：如果示例需要特殊编译参数，允许直接写命令而非 RST 引用，但需说明原因
|
||
- **文档不存在**：提示用户并建议可能的路径
|