mindspore-ai/docs/doc-quality-checker-mindspore
Claude Code and agent skill by mindspore-ai/docs
- community
Checking that the SKILL.md file is still in the repository.
检查文档质量的工具。当用户提到检查文档质量、审查文档、文档检查、文档审查、lint文档, 或者提供文档URL/PR链接/本地文件路径要求检查时触发。支持通用性检查、教程检查和API文档检查。 输入类型:1) 可访问的HTML页面URL;2) AtomGit PR链接(分析PR中的文档diff); 3) 本地文件夹路径。自动根据内容判断执行 通用+教程 或 通用+API 的检查组合。
Install
npx vskill@latest install mindspore-ai/docs/doc-quality-checker-mindsporeSKILL.md
The same SKILL.md was published earlier as mindspore-ai/docs/doc-quality-checker-mindspore.
文档质量检查器
输入解析
解析用户提供的输入,判断输入类型并获取内容:
| 输入类型 | 识别方式 | 获取内容方法 | |
|---|---|---|---|
| HTML页面URL | 以 http:// 或 https:// 开头且非Git链接 | 使用 WebFetch 工具获取页面内容 | |
| AtomGit PR链接 | 包含 atomgit.com 的PR URL | 使用 AtomGit API + Token 获取PR内容 | |
| 本地文件夹 | 本地路径 | 使用 read 工具读取文件内容 |
PR链接处理流程
对于 AtomGit PR链接:
- 获取Token → 提示用户输入 AtomGit/Gitee 私人令牌(用于API认证)
- 解析PR链接获取仓库信息(owner)、仓库名(repo)和PR编号
- 调用脚本
scripts/fetch_pr.ps1或scripts/fetch_pr.sh获取PR详情和diff内容:
- 脚本路径:
scripts/fetch_pr.ps1(Windows)或scripts/fetch_pr.sh(Linux/Mac) - 使用
PRIVATE-TOKENheader 认证:--header 'PRIVATE-TOKEN: {token}' - API格式:
https://api.atomgit.com/api/v5/repos/{owner}/{repo}/pulls/{pr_number}
- 识别diff中的文档文件(.md, .rst, .txt等)
- 分析文档变更内容
脚本用法:
Token获取方式:
- AtomGit: https://atomgit.com/user_settings/apitokens
- 需要创建私人令牌,勾选
repo权限
检查类型判断
根据输入内容特征自动选择检查组合:
| 特征 | 检查组合 | |
|---|---|---|
| 包含"安装"、"快速开始"、"教程"、"开发指南"等 | 通用性检查 + 教程检查 | |
| 包含"API"、"参数"、"返回值"、"函数"等 | 通用性检查 + API文档检查 | |
| 包含代码示例、函数签名、参数说明 | 通用性检查 + API文档检查 | |
| 包含步骤说明、截图指引、操作流程 | 通用性检查 + 教程检查 | |
| 无法判断时默认 | 通用性检查 + 教程检查 |
检查规则
1. 通用性检查(所有文档必须通过)
规则文件为rules/doc_general_rules.md,支持所有格式文件的内容检查。
2. 教程检查(教程类文档额外检查)
规则文件为rules/doc_tutorials_rules.md,支持Markdown、reStructuredText、Jupyter Notebook等格式文件的内容检查。
3. API文档检查(API类文档额外检查)
重要:API文档检查必须同时包含以下两部分,缺一不可:
- 格式检查:检查文档本身的格式和质量(如参数说明、返回值、异常等)
- 一致性检查:检查中文API文档与英文源文件(Python/C++/YAML/RST目录)的对应关系
API文档检查流程
- 执行格式检查 → 按文档语言类型应用对应规则文件:
- Python API中文文档(RST格式):
rules/api_python_zh_rules.md - Python API英文注释(Python docstring/YAML):
rules/api_python_en_rules.md - C++ API中文文档(MD格式):
rules/api_cpp_zh_rules.md - C++ API英文注释:
rules/api_cpp_en_rules.md - PR 场景:对每个修改的文件分别应用对应规则
- 混合输入:同时存在多种类型时,分别按各自规则执行
- 查找对应源文件 → 按方向查找配对文件:
- 中文文档 → 找英文源:按下文"英文源文件查找"方法定位(路径推断、YAML 搜索、别名链追踪、op 定义文件反查)
- 英文源 → 找中文 RST/MD:
- 直接映射:原名按模块路径推断中文路径
- 别名场景:搜索各模块
__init__.py中from X import 原名 as 别名,所有别名的中文路径一并查找
- 执行一致性检查 → 使用
rules/api_python_consistency_rules.md,按输入类型选择子检查项:
- 中文RST ↔ 英文源码:检查 Summary/Args/Returns/Raises 等字段的中英文对应关系(英文源可以是 Python docstring 或 YAML)
- 别名场景:检查 AL-01~04(名称差异、重导出内容、YAML 名称匹配、废弃标注)
- 英文RST目录:检查接口列表/数量/分组与中文RST一致
- PR配对:中文修改需有英文对应,英文修改需有中文对应
英文源文件查找
当输入为中文API文档时,需要查找对应的英文源文件:
| 英文源类型 | 后缀 | 说明 | |
|---|---|---|---|
| Python代码 | .py | 包含docstrings的Python代码 | |
| C++代码 | .h, .cpp | 包含 /// 注释的C++代码 | |
| YAML配置 | .yaml, .yml | MindSpore算子/接口定义文件(Tensor方法等) | |
| 英文RST目录 | .rst | API索引/目录文件(如 mindspore.nn.rst) |
典型路径映射(含别名场景):
YAML文档类型说明:
| 类型 | 路径 | 用途 | |
|---|---|---|---|
| function_doc | mindspore/ops/op_def/yaml/doc/ | 函数接口文档 | |
| method_doc | mindspore/ops/op_def/yaml/doc/ | 方法接口文档 | |
| function_doc(alternative) | mindspore/ops/api_def/function_doc/ | 函数接口文档(备选) | |
| method_doc(alternative) | mindspore/ops/api_def/method_doc/ | 方法接口文档(备选) |
查找策略(优先级从高到低):
- 直接路径推断:根据模块路径映射到对应 Python/YAML 文件
- YAML 文档搜索:根据 API 名称搜索
op_def/yaml/doc/和api_def/function_doc/等目录 - 别名导入链追踪:当直接推断和 YAML 搜索均未找到,或找到的内容不足以进行完整一致性检查时,必须追溯 import 别名链。具体做法:
- 解析 RST 文件名提取完整模块路径(如
mindspore.mint.nn.Hardshrink) - 从最内层模块开始,读取其
__init__.py(如mindspore/mint/nn/__init__.py) - 搜索
from X import Y as Z或from X import Z语句,匹配别名Z是否等于 API 名称 - 如果匹配,记录映射关系(
别名 → 真实类/函数名),并继续解析真实导入路径的__init__.py - 递归追踪直到找到实际的类/函数定义所在文件(
class HShrink或def hardshrink) - 同时记录别名路径上的 YAML doc 文件(如
hardshrink_doc.yaml)用于辅助检查
- YAML op 定义文件反查:当第 3 步得到 auto_generate 函数名后,若按函数名搜
*_doc.yaml找不到,搜索op_def/yaml/*_op.yaml中name:字段等于函数名的文件,其文件名前缀即为 doc 文件名:
``text 例: col2im_ext_op.yaml 中 name: fold_ext → doc 文件为 col2im_ext_doc.yaml ``
- 用户指定路径
4. 生成并保存报告
汇总所有检查结果,按照"输出格式"生成 Markdown 报告保存到本地,在"基本信息"中列出本次使用的规则文件,告知用户路径。
- 多输入或混合输入都合并到
report_{场景}.md(如report_PR_1234.md),文件已存在则覆盖 - 报告内按输入源分章节(如
## PR #1234、## 本地文件: xxx.rst) - 默认保存到当前目录,或用户指定路径
输出格式
生成Markdown格式的检查报告。
报告结构
注意事项
- 对于PR链接,会分析PR中的文档变更部分
- 检查过程会尽量获取页面完整内容
- 图片使用本地路径时无法验证,会标记为"需人工确认"
- 中文RST不包含示例,不需要检查样例部分
Security
- Security scanPassed, 90 of 100Pattern checks on the skill's files.
- Model reviewPassed
Quality evaluation
- Task evaluationNot runNo evaluation yet. Run one in Skill Studio.
Source
- SKILL.md in the repositoryCheckingskills/doc-quality-checker-mindspore/SKILL.md
Popularity
- Repository stars
- 167
- Repository forks
- 33
- 7-day trend score
- 31
Stars and forks are for the whole GitHub repository, not this skill alone. Not refreshed yet.
Works with
Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.
- Claude Code
- Cursor
- GitHub Copilot
- Windsurf
- Codex
- Gemini CLI
- Cline
- Amp
- Roo Code
- Goose
- Continue
- Kilo Code
- Junie
- Trae
- OpenHands
- Qwen Code
- AI Agent
- Tabnine Chat
- Sourcegraph Cody
- Amazon Q
- Firebase Genkit
- Sweep
- Devin
- Phind
- Mentat
- Claude Desktop
- Aider
- GPT Pilot
- Plandex
- bolt.new
- v0
- Replit Agent
- Anse
- TypingMind
- BetterChatGPT
- LibreChat
- Warp AI
- Pieces
- Fig AI
Embed badge
[](https://verified-skill.com/skills/mindspore-ai/docs/doc-quality-checker-mindspore)