---
name: piclist-upload
homepage: https://github.com/cat-xierluo/legal-skills
author: 杨卫薪律师（微信ywxlaw）
version: "1.5.0"
description: 通过 PicList HTTP Server 将 Markdown 文件中的本地图片上传到图床，并替换为云端链接。本技能应在用户需要上传 Markdown 中的图片、处理包含本地图片引用的 Markdown、批量处理多个 Markdown 文件或目录、或替换本地路径为云端链接以实现跨设备访问时使用。
license: Complete terms in LICENSE.txt
---

# 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](references/setup.md) 安装和配置指南。

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

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

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

## 使用方法

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

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

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

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

### 预览模式（不修改文件）

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

## 命令选项

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

## 响应格式

解析上传返回的 JSON：

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

## 统计报告

处理完成后显示：

```markdown
📊 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`。可通过环境变量覆盖：

```bash
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`）不会被解码，保持原样。