mindspore-ai/docs/doc-release

Claude Code and agent skill by mindspore-ai/docs

Trust tier 3
  • community
Source check pending

Checking that the SKILL.md file is still in the repository.

MindSpore 文档发布新分支时,链接更替与组件清洗技能,用于清理组件和替换链接。

Install

npx vskill@latest install mindspore-ai/docs/doc-release

SKILL.md

The same SKILL.md was published earlier as mindspore-ai/docs/doc-release.

OpenCode Skill: 文档发布 Skill

技能元信息

属性值
技能名称文档发布 Skill
适用项目MindSpore 文档仓库
维护者MindSpore Docs Team

技能描述

文档发布 Skill,用于 MindSpore 文档发布分支内容处理。发布新版本时,将文档从开发分支同步到发布分支,清理不发布的组件,并修正文档内部指向旧分支的链接。

本技能通过精确的正则表达式匹配,覆盖多种链接格式(OBS 资源链接、OBS Notebook 链接、atomgit 链接、官网链接、git clone 命令等),确保文档中的链接在新版本中正确指向目标分支。

核心特性:

  1. source_branch 参数可配置为任意分支名(master、r2.9.0、dev 等)
  2. 官网链接使用 target_html_branch,仓库链接使用 tag(仅 MindSpore 系列有 tag)
  3. 增加链接有效性检测功能
  4. 支持 .ipynb (Jupyter Notebook) 文件中的链接替换
  5. 组件清洗,仅保留需要的组件目录
  6. 支持 git clone 命令(含带 -b、不带 -b 两种形式)的分支替换
  7. 保留 `git clone URL -b {version}` 形式(-b 在 URL 后面,占位符形式,不替换)
  8. 自动处理所有 RST 文件中的网格表格折行 URL,无需维护文件清单

触发条件

当用户需要执行以下操作时触发本技能:

  • 发布新版本,需要将文档从开发分支迁移到发布分支
  • 清理文档仓库中不发布的组件文件夹
  • 批量修正文档中指向旧分支的链接
  • 验证替换后的仓库链接是否有效

限制条件

  • 组件清洗仅在仓库根目录的 docs/ 目录下执行
  • 链接替换作用于以下三个目录:
  • docs/
  • tutorials/
  • install/
  • 文件类型处理:
  • .md / .txt / .html / .yml / .yaml / .ipynb:普通正则替换
  • .rst:网格表格按"逐逻辑行还原折行 URL → 替换 → 重新折行"处理(列宽按显示宽度计算),非表格区域直接替换
⚠️ 运行前请确保当前工作目录为仓库根目录(即 tutorials/、install/、docs/ 所在的那一层)。

输入参数

参数名类型必填默认值说明
source_branchstring否master源旧分支名称(可以是任意分支名)
components_to_keeplist[string]是-需要保留的组件白名单(sample_code 目录始终保留)
component_branch_mapmap[string]object是-组件到目标分支的映射配置
enable_link_checkboolean否true是否启用替换后的链接有效性检测
component_branch_map 配置说明

每个组件配置包含以下字段:

字段类型必填说明
repo_namestring是atomgit 仓库名称
has_gitboolean是是否有独立的 atomgit 仓库(true/false)
target_html_branchstring是官网 HTML 分支(如 r2.10.0、r2.0.0、r0.7、81RC1)
tagstring否仓库 tag(如 v2.10.0),只有 MindSpore 有 tag
url_namestring是官网链接 cn/ 后的路径名(如 tutorials、docs、lite、mindquantum)
组件配置参考表
python
# 只有 MindSpore 有 tag
# [repo_name, has_git, source_branch, target_html_branch, tag, url_name]
# ['tutorials', False, 'master', 'r2.10.0', '', 'tutorials'],
# ['mindscience', True, 'master', 'r0.7', '', 'mindscience'],
# ['mindflow', False, 'master', 'r0.3', '', 'mindflow'],
# ['mindearth', False, 'master', 'r0.3', '', 'mindearth'],
# ['mindformers', True, 'master', 'r2.0.0', '', 'mindformers'],
# ['mindspore', True, 'master', 'r2.10.0', 'v2.10.0', 'docs'],
# ['mindspore-lite', True, 'master', 'r2.10.0', 'r2.10', 'lite'],
# ['vllm-mindspore', True, 'master', 'r0.5.0', '', 'vllm_mindspore'],
# ['golden-stick', True, 'master', 'r1.3.0', '', 'golden_stick'],
# ['mindquantum', True, 'master', 'r0.11', '', 'mindquantum'],
# ['mindstudio', False, 'master', '81RC1', '', 'mindstudio'],

字段说明:

字段说明
repo_name仓库名
has_git是否有独立仓库
source_branch源分支(通常为 master)
target_html_branch目标 HTML 分支(用于官网链接和 OBS 链接)
tag仓库 tag(仅 MindSpore 有)
url_name官网链接 cn/ 后的路径名
官网链接格式说明

官网链接形如:

text
https://www.mindspore.cn/tutorials/zh-CN/master/index.html
^^^^^^^^^ ^^^^^^
url_name source_branch

其中 url_name(如 tutorials、docs、lite)是 cn/ 后的路径名,master 是源分支。

替换后:

text
https://www.mindspore.cn/tutorials/zh-CN/r2.10.0/index.html
特殊组件说明
组件特殊处理
tutorials需额外处理教程专属链接:mindspore.cn/tutorials/...
mindspore需额外处理 docs 仓链接:atomgit.com/mindspore/docs/... 和 OBS 链接
.ipynb 文件处理说明

.ipynb 是 JSON 格式文件,其中的链接通常以未转义的普通形式存储,例如:

json
"source": [
"[![View Source On AtomGit](https://mindspore-website.obs.cn-north-4.myhuaweicloud.com/website-images/master/resource/_static/logo_source_en.svg)](https://atomgit.com/mindspore/docs/blob/master/tutorials/source_en/dataset/record.ipynb)\n"
]

由于这些链接是普通字符串(非正则表达式),不需要额外的转义处理,直接将 .ipynb 加入文件后缀列表即可。


执行步骤

步骤 1:清理不发布的组件

在 docs/docs 目录下,删除不在白名单中的组件文件夹。sample_code 目录始终保留。

执行逻辑
  1. 构建保留列表:["sample_code"] + components_to_keep
  2. 遍历 docs/docs 目录下的所有一级子目录
  3. 如果目录名不在保留列表中,执行删除
执行代码
python
import os
import shutil
DOCS_COMPONENTS_DIR = "./docs/docs"
# 构建保留列表:sample_code + 用户指定的组件白名单
keep_list = ["sample_code"] + {{ parameters.components_to_keep }}
print(f"保留的组件: {keep_list}")
if os.path.isdir(DOCS_COMPONENTS_DIR):
for entry in os.listdir(DOCS_COMPONENTS_DIR):
full_path = os.path.join(DOCS_COMPONENTS_DIR, entry)
if os.path.isdir(full_path) and entry not in keep_list:
print(f"删除组件: {entry}")
shutil.rmtree(full_path)
else:
print(f"目录不存在: {DOCS_COMPONENTS_DIR}")

步骤 2:替换分支链接并检测有效性(普通文件 + RST)

在 docs/、tutorials/、install/ 三个目录下,对所有支持的文件替换分支名:

  • .md / .txt / .html / .yml / .yaml / .ipynb:普通正则替换
  • .rst:网格表格按"逐逻辑行还原折行 URL → 替换 → 重新折行"处理(列宽按显示宽度计算),非表格区域直接替换
替换规则说明
链接类型使用的字段示例(source_branch=master, target_html_branch=r2.11.0, tag=v2.11.0)
OBS 资源链接target_html_branchwebsite-images/master/resource/... → website-images/r2.11.0/resource/...
OBS Notebook 链接target_html_branchnotebook/master/tutorials/... → notebook/r2.11.0/tutorials/...
官网链接target_html_branchmindspore.cn/docs/zh-CN/master/ → .../r2.11.0/
atomgit docs 仓链接target_html_branchdocs/blob/master/tutorials/... → docs/blob/r2.11.0/tutorials/...
atomgit 仓库链接tag(无 tag 用 target_html_branch)mindspore/blob/master/... → mindspore/blob/v2.11.0/...
git clone(-b 在前)tag(无 tag 用 target_html_branch)git clone -b master ... → git clone -b v2.11.0 ...
git clone(不带 -b)tag(无 tag 用 target_html_branch)git clone https://.../mindspore.git → git clone -b v2.11.0 https://.../mindspore.git
git clone(`-b` 在 URL 后,占位符)不替换git clone ...git -b {version} → 保留原样
RST 网格表格折行 URL同上由本步骤的 RST 分支自动处理
执行代码
python
import os
import re
import logging
import requests
from concurrent.futures import ThreadPoolExecutor, as_completed
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
# ============ 链接检测函数 ============
def check_url(url, timeout=5):
try:
resp = requests.head(url, timeout=timeout, allow_redirects=True)
return resp.status_code < 400
except Exception:
return False
def validate_links(link_list, max_workers=5):
if not link_list:
return
logger.info(f"开始检测 {len(link_list)} 个链接...")
failed_links = []
with ThreadPoolExecutor(max_workers=max_workers) as executor:
future_to_url = {executor.submit(check_url, url): url for url in link_list}
for future in as_completed(future_to_url):
url = future_to_url[future]
try:
is_valid = future.result()
if not is_valid:
failed_links.append(url)
logger.warning(f"⚠️ 链接可能无效: {url}")
except Exception as e:
failed_links.append(url)
logger.error(f"检测失败 {url}: {e}")
if failed_links:
logger.error(f"发现 {len(failed_links)} 个可能无效的链接:")
for link in failed_links:
logger.error(f" - {link}")
else:
logger.info("✅ 所有检测的链接均有效")
# ============ RST 网格表格工具 ============
BORDER_RE = re.compile(r'^\+[-=+]+\+$')
URI_RE = re.compile(r'<https?://[^>]+>')
# 嵌入式 URI 的 '<' 前必须有空白。单元格拼接会吃掉换行,故折行时若 '<' 前无空白需重新断行。
EMBED_URI_RE = re.compile(r'(?<!\s)(<[a-zA-Z][a-zA-Z0-9+.\-]*://)')
# docutils 解析网格表格按“显示宽度”计算列宽:CJK 等宽字符算 2 列。
# 优先复用 docutils 自带实现,保证与 Sphinx 完全一致。
try:
from docutils.utils import column_width as dwidth
except Exception:
import unicodedata
def dwidth(s):
width = 0
for ch in s:
if unicodedata.category(ch) in ('Mn', 'Me', 'Cf'):
continue
width += 2 if unicodedata.east_asian_width(ch) in ('W', 'F') else 1
return width
def is_border(line):
return bool(BORDER_RE.match(line.strip()))
def is_data_row(line):
s = line.strip()
return s.startswith('|') and s.endswith('|')
def border_positions(border_line):
"""分隔符所在的显示位置(边框为 ASCII,字符下标即显示宽度)。"""
return [i for i, ch in enumerate(border_line) if ch == '+']
def slice_display(line, start, end):
"""按显示宽度区间 [start, end) 截取内容(不含两端的分隔符 '|')。"""
w = 0
out = []
for ch in line:
cw = dwidth(ch)
if w >= start and (w + cw) <= end:
out.append(ch)
w += cw
return ''.join(out)
def split_row(line, positions):
"""按边框给出的列边界做“位置切分”,与 docutils 一致。
不能用 body.split('|'):单元格内可能含转义竖线 \\|,且中文列宽按显示宽度对齐,
直接按 '|' 切分会把内容/填充错位。
"""
return [slice_display(line, positions[i] + 1, positions[i + 1])
for i in range(len(positions) - 1)]
def cpad(s, width):
pad = width - dwidth(s)
return s + ' ' * pad if pad > 0 else s
def build_row(cells, widths):
return '|' + '|'.join(cpad(c, w) for c, w in zip(cells, widths)) + '|'
def fold_by_width(text, width):
lines = []
cur = ''
for ch in text:
if cur and dwidth(cur) + dwidth(ch) > width:
lines.append(cur)
cur = ch
else:
cur += ch
if cur or not lines:
lines.append(cur)
return lines
def fold_uri_safe(text, width):
"""折行,并保证嵌入式 URI 的 '<' 前有空白(reST 要求)。"""
text = EMBED_URI_RE.sub(r'\n\1', text)
out = []
for part in text.split('\n'):
out.extend(fold_by_width(part, width))
return out
def process_run(run, positions, widths, rules):
"""处理一个逻辑行(两个边框之间的一组物理行)。
逐逻辑行处理很关键:一张网格表格通常由表头与多个逻辑行组成(用 +---+ 分隔),
不能把整表所有物理行按列拼接,否则表头文字与各行 URL 会被串到一起。
"""
ncols = len(widths)
cells = [split_row(l, positions) for l in run]
cells = [r[:ncols] + [''] * (ncols - len(r)) for r in cells]
new = [list(r) for r in cells]
changed = False
for c in range(ncols):
# 跨物理行拼接该列内容(去掉填充空白),用于还原被硬折行的 URL
joined = ''.join(r[c].strip() for r in cells)
if URI_RE.search(joined):
new_joined = joined
for pat, rep in rules:
new_joined = re.sub(pat, rep, new_joined)
if new_joined != joined:
changed = True
folded = fold_uri_safe(new_joined, widths[c])
if len(folded) > len(run):
logger.warning(f"折行数({len(folded)})超过原行数({len(run)}),可能错位,col={c}")
for r in range(len(run)):
new[r][c] = folded[r] if r < len(folded) else ''
else:
for r in range(len(run)):
cell = cells[r][c]
for pat, rep in rules:
cell = re.sub(pat, rep, cell)
if cell != cells[r][c]:
changed = True
new[r][c] = cell
if not changed:
return run, False
return [build_row(new[r], widths) for r in range(len(run))], True
def process_table(table_lines, rules):
"""处理整张网格表格:逐逻辑行处理,返回 (新行列表, 是否有改动)。"""
borders = [l for l in table_lines if is_border(l)]
if not borders:
return table_lines, False
positions = border_positions(borders[0])
if len(positions) < 2:
return table_lines, False
widths = [positions[i + 1] - positions[i] - 1 for i in range(len(positions) - 1)]

This is the start of the file. Read the full SKILL.md on GitHub.

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

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
vskill VERIFIED badge
[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/mindspore-ai/docs/doc-release/badge)](https://verified-skill.com/skills/mindspore-ai/docs/doc-release)

Something wrong with this skill or its page? Tell us.