脚本开发原则

好脚本不只是能跑：它应该容易理解、可靠稳定，让用户用得顺手，让其他开发者愿意参考。

这些原则来自社区脚本的实践观察。遵循它们，脚本更容易被理解、维护和复用。

核心原则：一个脚本做好一件事

每个脚本只专注解决一个具体问题，这是最重要的原则。

选择合适的交互方式

根据脚本的使用场景选择交互方式，并用 terminal 字段配合：

GUI 交互

脚本需要复杂交互（设置参数、预览结果等）时，考虑用图形界面：

Python：盒子配置的环境中包含 tkinter，可直接使用
AutoHotkey：原生支持 GUI
PowerShell：可以使用 .NET WinForms
Node.js：可以使用 HTML 或 webview

GUI 脚本请把 terminal 设为 "always"，避免窗口被隐藏。

CLI 交互

只需要简单命令行交互时，保持界面清爽：

帮助信息：明确说明脚本的功能和用途，不要让使用者看到原始代码输出
暂停与退出机制：脚本执行完成后提供暂停，否则用户来不及看到必要信息就关闭了；也可以用倒计时自动退出

静默执行

不需要交互的后台任务（批量处理等），把 terminal 设为 "never"，执行完毕后通过盒子的通知接口告知用户结果：

python

import json, sys, requests

payload = json.load(open(sys.argv[1], encoding='utf-8'))
api_base = payload["environment"]["api_base"]

requests.post(f"{api_base}/api/notify", json={
    "notify_type": "success",
    "message": "已处理 42 个文件",
})

接口详情见发送通知 · /api/notify，模式选择见终端模式详解。

做好错误处理

好的错误处理能让用户快速知道发生了什么，而不是看到一堆不知所云的堆栈跟踪。

捕获可能发生的异常，给出有意义的提示
文件不存在、权限不足等常见问题，提前检查并给出友好说明
对于 terminal 为 "auto" 或 "never" 的脚本，把关键信息打印到 stdout，盒子会捕获并展示给用户

python

import sys
import json

try:
    with open(sys.argv[1], 'r', encoding='utf-8') as f:
        params = json.load(f)
except FileNotFoundError:
    print("错误：未找到参数文件")
    sys.exit(1)
except json.JSONDecodeError as e:
    print(f"错误：参数文件格式不正确 - {e}")
    sys.exit(1)

管理好依赖

最小化依赖

只引入真正需要的依赖，避免臃肿
优先使用 Python 标准库、Node.js 内置模块
Python 依赖在 pyproject.toml 的 dependencies 中声明
Node.js 依赖在 package.json 的 dependencies 中声明

指定版本范围

toml

# pyproject.toml — 推荐使用范围约束
dependencies = [
    "pillow>=10.0,<11",
    "send2trash>=1.8",
]

外部二进制工具

脚本需要依赖外部命令行工具（FFmpeg、ImageMagick、7-Zip 等）时，在配置文件中声明 binaries 字段，盒子自动管理下载和环境配置：

声明依赖：在脚本配置文件中列出所需的二进制工具名称
自动下载：盒子检测到声明后，自动把对应工具下载到用户本地
环境配置：盒子自动把工具所在目录加入 PATH
无感调用：脚本中直接通过工具名调用即可，无需关心安装路径
全局共享：多个脚本依赖同一个工具时，仅首次下载一次，后续脚本直接复用

详见外部二进制工具。

安全建议

不要硬编码密钥：API 密钥、密码等敏感信息应通过环境变量或配置文件传入
路径校验：文件操作时检查路径是否合法，避免路径穿越漏洞
临时文件清理：使用临时文件后及时删除，避免磁盘残留
输入校验：对用户传入的参数做基本校验，不要直接拼接命令

版本管理

严格遵循语义化版本规范：

版本变化	说明	示例
主版本 `x`	不兼容的 API 变更	`1.0.0` → `2.0.0`
次版本 `y`	向下兼容的功能新增	`1.0.0` → `1.1.0`
修订号 `z`	向下兼容的问题修复	`1.0.0` → `1.0.1`

几条实用建议：

每次发布前更新 bm-scripts-box-rc.toml 中的 version 字段
不要发布比用户本地版本号更低的版本（盒子不会执行降级）
版本变更时，同步更新 README 中的更新日志

兼容性

更新脚本时，注意不要影响已安装用户的个性化配置：

配置文件中的 id（UUID）一经固定不要再修改，否则会被识别为新的脚本
修改 inputs 的 name 会改变 JSON 参数中的键名，确保脚本代码同步更新
快捷键、右键菜单开关等用户配置不受配置更新影响

toml

[bmscriptsbox.info]
id = "a1b2c3d4-..."    # 固定不变，用于标识脚本唯一身份
version = "1.2.0"      # 每次发布递增

法律与合规

遵守法规：不要开发、发布违反国家法律法规的脚本
尊重开源协议：GPL 类许可证要求衍生作品同样开源；MIT、Apache 等宽松许可证需保留版权声明
署名声明：在脚本中标注使用的开源项目及其作者，在 README 中说明使用了哪些开源组件
社区规则：发布到社区的脚本如果被发现违规，盒子运营方有权下架或删除，且不另行通知

代码托管

盒子不会托管你的代码。你的代码始终存储在你自己的 Git 仓库中。发布到社区时，盒子仅保存元数据——脚本名称、描述、版本号、分类、仓库地址等。实际安装时，盒子直接从你的 Git 仓库克隆代码。

编写 README

发布到社区的脚本，建议编写 README。一份好的 README 通常包含：

markdown

# 脚本名称

> 一句话概括脚本功能

## 功能演示

（截图或 GIF 动图，生动展示用法）

## 使用方法

安装后在资源管理器中选中文件 → 右键 → 选择脚本名称

## 参数说明

（如果有可配置的参数）

## 更新日志

### v1.1.0 (2026-05-20)
- 新增批量处理功能
- 优化性能

演示素材可以用 ScreenToGif、LICEcap 等工具录制 GIF。一张演示图能直观说明用法，读者不用读大段文字。

脚本开发原则 ​

核心原则：一个脚本做好一件事 ​

选择合适的交互方式 ​

GUI 交互 ​

CLI 交互 ​

静默执行 ​

做好错误处理 ​

管理好依赖 ​

最小化依赖 ​

指定版本范围 ​

外部二进制工具 ​

安全建议 ​

版本管理 ​

兼容性 ​

法律与合规 ​

代码托管 ​

编写 README ​

相关文档 ​