脚本开发规范:script.yaml 字段与 body 约定
更新于 #脚本开发#script.yaml#参数类型#退出码#回滚
这份规范写给要投稿或维护脚本的人。它描述 script.yaml 与 body 片段怎么写,以及构建期会强制检查哪些规则——不满足就直接构建失败,脚本无法上线。
目录结构
src/content/scripts/<slug>/├── script.yaml└── body/ ├── 10-check.sh └── 20-main.sh- 目录名必须与
slug一致,否则加载失败。 body/至少有一个.sh文件,所有片段按文件名排序后拼接;用10-、20-这类编号控制顺序。- 以
_开头的目录不会被加载,可以放模板。 - 片段里不要写 shebang、
set -eu、umask,这些由生成器统一注入;也不要重复定义公共函数。
script.yaml 字段
基本信息
| 字段 | 含义 | 约束 |
|---|---|---|
slug |
URL 与产物标识 | 小写字母/数字/连字符,2–48 位 |
title |
标题 | 4–40 字 |
summary |
一句话摘要 | 10–80 字,用于卡片和列表 |
intro |
详情页引言 | 可选,最多 4 段,每段 10–500 字 |
category / subcategory |
一级/二级分类 | 必须存在于分类注册表,二级分类还必须在所属分类下 |
tags |
标签 | 1–10 个,每个不超过 16 字 |
version |
版本号 | 语义化 x.y.z |
status |
状态 | draft / beta / stable / deprecated |
license |
许可证 | 如 MIT |
authors |
作者 | 1–6 项,每项含 name,可选 url |
updated |
更新日期 | YYYY-MM-DD |
draft |
草稿 | 为 true 时不参与构建与列表 |
兼容、运行与风险
| 字段 | 含义 | 约束 |
|---|---|---|
shell |
脚本方言 | posix 或 bash |
distros |
兼容矩阵 | 至少 1 项,每项 { id, min, max, tested };id 用 /etc/os-release 的发行版 ID |
arch |
支持架构 | 可选,如 x86_64、aarch64 |
requiresRoot / requiresNetwork |
是否需要 root / 网络 | 布尔,必填 |
requiresTty |
是否需要交互终端 | 布尔,可选 |
danger |
危险等级 | read / change / destructive |
idempotent / dryRun |
是否幂等 / 是否支持预演 | 布尔,必填 |
rollback |
回滚声明 | { supported, how };danger 不是 read 时必须 supported: true |
changesPaths |
改动路径 | 字符串数组,最多 20 项 |
参数、预设与文档
| 字段 | 含义 | 约束 |
|---|---|---|
params |
参数定义 | 最多 20 个,key 唯一且小写字母开头 |
presets |
预设组合 | 最多 12 个,key 唯一,只能引用已声明参数 |
faq |
常见问题 | 可选,最多 10 条,q / a 问答对 |
related |
相关脚本 | 可选,最多 8 个脚本 slug |
references |
外部参考 | 可选,最多 10 项,title / url 数组 |
seo |
SEO 覆盖 | 可选,title / description / keywords |
8 种参数类型
| 类型 | 适合什么 | 校验与安全边界 |
|---|---|---|
enum |
有限选项,如镜像站、模式 | 必须给 options,default 必须在其中,运行时再校验一次 |
bool |
开关 | 渲染为 0 / 1,只接受这两种值 |
int |
数量、阈值 | 用 min / max 限定范围,不接受小数 |
port |
端口 | 整数,1–65535 |
path |
绝对路径 | 以 / 开头,不允许空格、引号、反引号、$、反斜杠与 .. |
url |
下载地址 | 只接受 http(s),不允许空白、引号、反引号、$ 与反斜杠 |
hostname |
主机名或 IP | 校验主机名与 IPv4 格式 |
text |
自由文本 | 拒绝换行与控制字符,默认限长 200,可用 max / pattern 收紧 |
原则是能用 enum 就不选 text:选项越少,运行时越不容易进到奇怪的分支。参数只作为数据,以 LM_<KEY> 变量形式注入,绝不拼进命令位置;不要设计“参数值本身就是一条命令”的参数。
body 片段约定
- 可直接使用生成器注入的公共函数:
die、log、warn、has_cmd、need_cmd、need_root、need_os_release、in_container、has_systemd。 - 系统识别统一读
/etc/os-release的ID、ID_LIKE、VERSION_ID,不要读/etc/redhat-release。 - 变更前备份到
/var/backups/linuxmirror/<脚本 ID>/<时间戳>/,结束时打印回滚命令。 - 并发保护用
flock;临时目录用mktemp -d加trap清理。 - systemd 服务分
systemctl enable和systemctl start两步操作。 - 不自动执行
setenforce 0;默认不修改防火墙,只有显式要求时才按探测到的防火墙类型操作。 - 重复执行应是 no-op;
--dry-run只打印改动,不写任何文件。 - 网络下载使用
curl --proto '=https' --tlsv1.2 -fsSL --retry 3 --connect-timeout 5,不要加-k。
参数变量与元信息
参数 key: format 会渲染成 LM_FORMAT='text',布尔值渲染成 LM_DETAIL='1' 或 '0'。生成器还会注入 LM_SCRIPT_ID、LM_SCRIPT_VERSION、LM_SCRIPT_BUILD、LM_DOC_URL,用于 banner 与文档链接。正文只引用这些变量,不要用 eval 展开。
退出码
| 退出码 | 含义 | 用法 |
|---|---|---|
0 |
成功 | 正常结束 |
1 |
通用失败 | 命令失败且无法归类时 |
2 |
用法错误 | 参数非法、缺少参数 |
3 |
环境不符 | 发行版不支持、缺依赖命令、没有 /etc/os-release |
4 |
需要 root | 未以 root 执行 |
统一用 die <退出码> "消息" 退出,错误消息写到 stderr。
构建期校验清单
以下任一项不满足,astro build 就会失败,脚本无法上线:
- 分类与二级分类存在于注册表;
slug与目录名一致,version是x.y.z;- 参数
key唯一,且以小写字母开头; enum必须有options,默认值在选项内;- 预设 key 唯一,只引用已声明参数,枚举值合法;
danger: destructive必须dryRun: true;danger不是read时必须声明rollback.supported;body/存在且至少有一个.sh文件。
参考
- system-info 详情页:一个完整、可运行的只读脚本示例
- 贡献指南
- 脚本安全说明