/piclist-upload

PicList 图片上传

将 Markdown 文件中的本地图片上传到配置的图床，并将本地路径替换为云端链接。

前置条件

• 已安装 PicList 并启用 HTTP Server
• 已在 PicList 中配置图床
• 已安装 jq
• 已安装 curl

系统兼容性: 脚本兼容 bash 3.2+（macOS 自带 /bin/bash 直接可用，无需安装新版 bash）、Linux 各发行版、Git Bash（Windows）。lsof 缺失时自动回退 /dev/tcp 端口探测，无需 bc。

首次配置: 请参阅 references/setup.md 安装和配置指南。

⚠️ 强制规则：必须通过脚本执行

禁止手动 curl 上传。所有操作必须通过 scripts/process.sh 脚本执行。 脚本已内置上传、URL 替换和本地文件删除的完整逻辑，手动操作容易遗漏步骤。

默认行为是上传成功后删除本地图片。 只有当用户明确要求保留时，才可添加 --keep-local。不得擅自保留本地图片。

使用方法

处理文件或目录（默认删除本地图片）

bash scripts/process.sh --in-place <file.md|directory...>

保留本地图片（仅在用户明确要求时使用）

bash scripts/process.sh --in-place --keep-local <file.md|directory...>

预览模式（不修改文件）

bash scripts/process.sh --dry-run <file.md|directory...>

命令选项

响应格式

解析上传返回的 JSON：

{"success":true,"result":["https://example.com/image.png"]}

统计报告

处理完成后显示：

📊 Summary:
  Total uploaded: 5
  Total skipped: 3
  Total failed: 0

• Uploaded: 成功上传并替换（已删除本地图片）
• Skipped: 已是云端 URL（无需操作）
• Failed: 上传错误（保留原始路径）

断点续传

--in-place 模式下每张图片上传成功后、删除本地文件之前，脚本都会立即把已替换的 md 内容原子写回磁盘。因此中途被打断（超时、崩溃、Ctrl-C）不会丢失已上传的 URL：已完成的部分在 md 中已是云端链接，未完成的部分保持本地引用，直接重跑同一命令即可续传（幂等）。

错误处理

• PicList 进程未运行: 脚本会先做端口级探测，缺失则自动尝试 open -a PicList.app（仅 macOS）并等待最多 15 秒（PICLIST_START_WAIT）；仍无响应才退出。
• PicList 在监听但业务端点 503/000: 通常是 PicList 应用卡死或图床后端未配置。脚本会报错并提示用户在 PicList 应用里检查默认图床/token，必要时重启应用。
• 文件不存在: 跳过并显示 ⚠️ 警告，继续处理
• 单张上传失败: 自动重试一次（MAX_RETRIES=1，间隔 RETRY_DELAY=2s），仍失败则保留原始路径，标记 ❌，继续
• 无效 JSON: 视为上传失败

配置

PicList Server 默认地址为 http://127.0.0.1:36677/upload。可通过环境变量覆盖：

export PICLIST_SERVER=http://127.0.0.1:PORT
# 以下为可选调优（一般无需改动）
export PICLIST_START_WAIT=15   # 启动 PicList 后等待端口就绪的秒数
export MAX_RETRIES=1           # 单图上传失败时的额外重试次数
export RETRY_DELAY=2           # 重试间隔秒数

支持格式

png, jpg, jpeg, gif, webp, svg, bmp

支持的引用写法

普通路径中的字面 %（如 50%.png）不会被解码，保持原样。