脚本系统

使用 JavaScript 扩展桌面 PicList 的上传流程。脚本直接在应用中管理，无需单独打包为 npm 插件。

创建与管理

没有脚本时从新脚本开始。先选择适合的阶段，再确认启用状态；环境文件可能含私密值。 查看大图 ↗

第一次尝试建议用下方“上传前加文件名前缀”的简单示例：

1. 点击 新脚本，给脚本一个描述性名称。
2. 阶段选择 beforeUpload，粘贴该示例并保存。
3. 检查该脚本是否启用。
4. 用本地上传练习配置上传一张文件，在目标目录中检查 docs- 前缀。
5. 不再需要时关闭该脚本，避免后续图床继续使用该前缀。

脚本中不要打印完整 ctx、配置、请求头或 .env。只输出必要的操作状态。日期与随机名称可以直接使用内置命名，无需为此创建脚本。

手动触发与高级自定义上传脚本有专门入口。其他脚本由所选阶段决定执行时机。

脚本默认位于数据目录的 scripts 文件夹。可从 ScriptsHub寻找示例；运行前阅读脚本内容。

执行阶段

阶段 ID	执行时机
onSoftwareOpen / onSoftwareClose	应用启动 / 退出
preProcess	文件读入后的预处理入口
beforeTransform / transform	转换输入为上传数据之前 / 之后
beforeUpload	文件发送到目标服务前
upload / afterUpload	上传阶段完成后及上传插件之后
onUploadSuccess	每个结果保存到相册后
onGalleryRemove	相册移除操作阶段
manualTrigger	在脚本页面主动运行
uploader.advancedplist	高级自定义上传器

请选择最接近目的的阶段，并用一个文件验证执行效果。上传成功阶段可能参与任务收尾，失败后需要处理恢复信息。

脚本入口

async function main(ctx, extra) {
  // ctx is the upload client; extra depends on the stage.
  return ctx
}

高级自定义上传脚本必须返回 ctx，并为每个结果填写 imgUrl。其他脚本返回值按所选阶段使用。

可用 API

对象	用途
ctx.input / ctx.output	输入列表 / 当前上传记录
ctx.getConfig(key)	读取配置
ctx.saveConfig(object)	按字段路径保存配置
ctx.request(options)	兼容的请求接口
ctx.log	应用日志
extra	阶段附加数据，如 galleryItem
axios, crypto, fs, path, os, Buffer	请求、加密工具、文件与路径工具
env	scripts/.env 中读取的变量
base64Encode / base64Decode	编码工具
定时器函数	setTimeout / setInterval 等

示例：上传前加文件名前缀

将此脚本放在 beforeUpload 阶段：

async function main(ctx) {
  for (const image of ctx.output) {
    if (image.fileName && !image.fileName.startsWith('docs-')) {
      image.fileName = 'docs-' + image.fileName
    }
  }
  return ctx
}

需要日期、哈希或随机名称时，优先使用内置重命名。

凭据与运行权限

将自己脚本所需的私密值放在本机 scripts/.env，通过 env 读取；不要将 .env 提交到公开仓库。脚本可访问文件与网络，运行前检查代码，不要把完整 ctx、配置或请求认证头写入日志。