mcpField
P
piclist-upload

piclist-upload

github.com/cat-xierluo文档处理762101 次安装今天更新
代码仓库

关于 piclist-upload

piclist-upload 是用于 Markdown 图片外链化的技能，面向需要整理文档图片引用的用户。它通过 PicList 上传本地图片、替换为云端链接，并支持预览、失败重试和中断后续传。

主要功能

  1. 01上传 Markdown 中的本地图片
  2. 02将路径替换为云端链接
  3. 03预览而不修改文件
  4. 04失败重试并保留原路径
  5. 05中断后可重跑续传

适用场景

  1. 01将文档图片迁移到图床
  2. 02预览图片处理结果
  3. 03上传中断后继续处理

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cat-xierluo/legal-skills --skill piclist-upload

安装后在 Claude Code 中输入/piclist-upload确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

CHANGELOG.md
LICENSE.txt
references/
setup.md
scripts/
process.sh
test_file_url_refs.sh

详细介绍

来自项目 README

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...>

命令选项

选项说明
--in-place直接修改原文件（必须指定，否则仅输出到终端）
--keep-local保留本地图片文件。仅在用户明确要求时使用
--dry-run预览模式，不上传、不修改文件

响应格式

解析上传返回的 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

支持的引用写法

写法示例处理
普通路径![alt](/abs/pic.png)、![alt](rel/pic.png)原样解析（v1.0.0 起）
尖括号路径![alt](</abs/pic (1).png>)剥离尖括号后解析
Obsidian file://![alt](<file:///abs/pic.jpg>)剥离尖括号与 file://，file://<host>/ 形式去掉主机名；URL 内百分号编码（%20 等）解码为真实路径（v1.5.0 起）

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

评论

支持 Markdown