贡献指南:提交一个脚本的完整流程
更新于 #贡献指南#投稿#PR#CI#审核
这篇写给想提交脚本的人:什么样的脚本本站会收、什么样的直接拒绝、从 Fork 到 PR 的每一步,以及 CI 和审核会看什么。动手前建议先读一遍脚本开发规范。
适合投稿的脚本
- 解决具体问题,且在常见发行版上可复现:换源、系统初始化、备份迁移、监控巡检、故障信息采集等;
- 默认安全:只读,或支持
--dry-run,变更前备份、能回滚; - 参数清晰,换一台机器、换一个环境仍能复用;
- 代码可读,许可证明确,不含密钥、内网地址、个人路径等敏感信息。
明确不接收
下面这些内容不做审核,直接拒绝:
- 绕过监管或审查的脚本,例如代理搭建、流量伪装、跨境绕过;
- 破解、授权绕过、激活工具、绕过付费限制;
- 挖矿、刷量、薅羊毛类脚本;
- 未授权的扫描、爆破、入侵与提权利用;
- 窃取凭据、键盘记录、隐私数据回传;
- 捆绑不可审计的二进制,或从不明地址下载后直接执行;
- 默认就是破坏性操作、又不提供
--dry-run的脚本。
只对某一台机器有效、把具体命令硬编码成“参数”、或严重依赖闭源服务的脚本,也暂不接收。
提交流程
-
Fork 仓库并 clone 到本地。
-
新建
src/content/scripts/<slug>/,目录名就是脚本 slug,同时写script.yaml与body/*.sh。字段与写法见脚本开发规范。 -
在仓库根目录运行本地自检:
Terminal window node scripts/verify.mjs它按 CI 的口径检查脚本定义 schema、预设参数、渲染确定性、危险命令红线与 Shell 语法,并用版本锁确认内容与版本号一致。新增脚本或升版本后如果提示未登记,按提示执行
node scripts/verify.mjs --write更新版本锁,再跑一次确认通过。改动涉及页面或内容集合时,再跑一次pnpm build,确认站点能正常构建。 -
检查暂存区,确认没有把密钥、服务器地址、个人路径带进来。
-
提交 PR,标题写清「新增脚本:xxx」或「修复:xxx」。一次 PR 只做一件事:一个脚本、一个修复或一篇文档,不要把三件事塞进同一个 PR。如果 CI 失败,先按日志在本地复现并修复,不要通过删检查绕过。
-
PR 描述里写清楚:脚本用途、危险等级与改动路径、是否需要 root/网络、是否幂等、是否支持
--dry-run、在哪些系统与架构上测过、如何回滚、许可证。
CI 会检查什么
- 构建期 schema:字段范围、分类是否存在、slug 与目录名一致、参数 key 唯一、预设只引用已声明参数且枚举值合法;
- 危险规则:
destructive必须有dryRun: true,非只读脚本必须声明rollback.supported; - 渲染:默认参数与每个预设都能渲染成完整脚本,同一组参数每次渲染结果一致;
- 版本锁:内容变更必须升版本,避免产物地址与内容不一致;
- shell 静态检查:声明
posix的脚本不能出现 bash 专属语法,shellcheck 的告警要处理; - 容器矩阵:在多个发行版容器里跑参数校验、非法参数、非 root、
--dry-run零写入、连续执行两次无变更等断言; - 危险命令扫描:
rm -rf /、eval、curl -k、setenforce 0等会被单独检查; - 站点构建:文档 frontmatter 与链接不能把构建搞挂。
审核标准
- 代码能读懂:命名清楚、有注释,不堆砌一行流命令;
- 错误处理:失败时给出可读消息和正确退出码,不吞错;
- 安全默认值:不自动关 SELinux、不默认改防火墙、不静默改 SSH;
- 可逆:变更前备份,并说明恢复步骤;
- 兼容声明真实:
tested不要乱标,没测过就如实写未测试; - 文档完整:
intro、faq、references该有的有,不夸大效果; - 许可证:默认 MIT,引用他人代码要标注来源。
版本与后续维护
已上线脚本的行为发生变化时,应提升 version(语义化版本)并更新 updated,让用户能区分新旧产物;只改注释或文档可以不升。审阅者会按新版本重新跑 CI,合并后站点按新版本重新构建。