/piclist-upload

变更日志

[1.5.0] - 2026-09-23

新增

• Obsidian file:// 引用支持：Obsidian 导出的图片引用格式 ![alt](<file:///绝对路径.jpg>)（尖括号 + file:// 协议）此前无法解析——路径带着尖括号与协议前缀直接做文件存在性检查，每张都报 "File not found"（2026-09-23 处理新疆律协授课报道 4 张图全部失败的实战案例）。现识别并剥离尖括号与 file:// scheme：file:///abs/path 取 // 后的绝对路径；file://<host>/path（如 file://localhost/...）去掉主机名保留路径；URL 内百分号编码（%20 空格等）解码为真实路径——仅对 file:// 引用解码，普通路径中的字面 %（如 50%.png）不受影响

验证

• 新增回归脚本 scripts/test_file_url_refs.sh（mock PicList server，无需真实上传）：file:// 引用上传替换、同一图多次引用去重复用 URL、--dry-run 识别、file://localhost 形式、--keep-local 保留、已有云端链接不动——10 项断言全过；补充分离验证：%20 编码路径解码上传成功、字面 % 路径不解码直传成功
• 修复前后对照：旧版 file:// 引用 100% "File not found"，新版全部正常上传
• macOS /bin/bash 3.2.57 与 Homebrew bash 双 runtime 通过；bash -n 通过；shellcheck 无新增告警（仅存量 3 处 SC2219 style）

[1.4.1] - 2026-09-21

修复

• 中断丢 URL（数据丢失级）：此前 URL 替换只累积在内存变量 content 中，直到整个文件全部处理完才一次性写回 md；而本地图片在上传成功后立即删除。运行中途被打断（终端超时杀进程、崩溃、Ctrl-C）即产生"图已删、md 里还是本地死链、URL 只存在于丢失的内存"——本次实战中 104 张批量上传在第 44 张被 300s 超时杀死，前 43 张的 URL 全部丢失（后从 PicList 本地 gallery 数据库逐张恢复）。现改为 --in-place 模式下每张上传成功后、删除本地文件之前，原子写回（tmp + mv）当前已替换的 md 内容；中断最坏情形退化为"本地文件还在、URL 已在 md 中"，重跑即可幂等续传
• 非 --in-place 模式删原图：不带 --in-place 时改写结果只打到 stdout、原 md 不落盘，但本地图片仍被删除——URL 没有持久化到任何地方，等于销毁唯一副本。现该模式下一律保留本地图片（与 --keep-local 同语义）

验证

• mock PicList server 回归三件套（新旧对照）：① 中断测试——旧版复现"删 2 文件/md 0 URL"丢失，新版 PASS（md URL 数 == 已删文件数）；② 完整运行 6 图——新旧均 PASS；③ 非 in-place——新版不再删除本地文件且 stdout URL 完整
• bash -n 双 runtime 语法检查（/bin/bash 3.2 + Homebrew bash）通过；shellcheck 无新增告警（仅存量 SC2219 style）

[1.4.0] - 2026-09-18

修复

• 跨系统兼容性根修（bash 4+ 依赖移除）：脚本此前使用关联数组 declare -A，在 macOS 自带 /bin/bash 3.2 下启动即报 declare: -A: invalid option，首张图片都无法上传。v1.1.1 只改了 shebang（#!/usr/bin/env bash）未根治——macOS 上 env bash 仍解析到系统 bash 3.2。本次将两处关联数组（deleted_dirs、uploaded_files）改写为换行分隔列表 + grep -Fxq 精确去重，bash 3.2 开箱即用；实测 /bin/bash（3.2.57）与 Homebrew bash 5.3 双通过
• 重复引用死链：同一本地图片被多处引用（尤其 alt 文本不同）时，首处上传后本地文件即被删除，后续引用被去重跳过、不替换——留下指向已删除文件的死链。此 bug 自关联数组时代即存在。现改为在去重分支复用已上传的 URL 完成替换（还省去重复上传）
• 路径含括号截断：图片路径含括号（如浏览器/微信另存的 截图 (1).png、dir (1)/file (2).png）时，提取正则 ([^)]*) 在第一个 ) 处截断，路径解析失败。改为支持路径内多组括号的 ERE

改进

• bc → awk：UPLOAD_INTERVAL > 0 判断改用 awk（bc 在精简 Debian/Ubuntu、多数 NAS 上非预装）
• lsof 缺失回退：端口探测在无 lsof 环境（最小化 Linux 镜像、部分容器）自动回退 bash 内建 /dev/tcp
• 嵌套替换处统一使用平引号模式形式（\" 转义形式在 bash 3.2 嵌套上下文中为 no-op）

验证

• macOS /bin/bash 3.2.57 + Homebrew bash 5.3.3 双 runtime 真实上传回归：单图/多图、重复引用复用 URL、已是云端跳过、缺失文件保留原路径、--keep-local、目录批量递归、空目录清理、路径含空格+中文+多组括号——全部通过，上传 URL HTTP 200 复核

[1.3.0] - 2026-09-09

修复

• 连通性检查假阳性：系统代理（如本地 SOCKS/HTTP 代理 127.0.0.1:1082）对未知本地端口返回 503，旧版裸 curl 检查被欺骗误报"已连接"。改为 lsof 端口级监听探测 + --noproxy '*' 直连业务端点探测，全部 curl 调用统一绕过代理

新增

• 自动启动 PicList：端口未监听时自动 open -a PicList.app（仅 macOS 且应用存在时），轮询等待最多 PICLIST_START_WAIT 秒（默认 15s）
• 单图上传重试：失败自动重试 1 次（MAX_RETRIES=1，间隔 RETRY_DELAY=2s），失败日志携带最后 HTTP code。与 v1.2.0 移除的 429 重试不同，本次针对单图瞬时 5xx，速率控制责任仍在调用方
• 故障分级提示：区分"进程未运行"与"端口在监听但业务端点 503/000（应用卡死/图床未配置）"两类故障，分别给出修复指引
• SKILL.md 补充 PICLIST_START_WAIT、MAX_RETRIES、RETRY_DELAY 三个环境变量文档

验证

• bash -n 语法通过；PicList 运行中 --dry-run 探测返回 HTTP 200；自动启动分支未实测（需 PicList 处于退出状态时触发）

[1.2.0] - 2026-04-28

移除

• 移除 429 速率限制重试逻辑：经核实，429 错误来源于调用方（大模型）而非 PicList 上传 API，现已移除相关检测和重试机制

技术优化

• 简化 upload_image() 函数，移除不必要的重试循环
• 删除 MAX_RETRY、RETRY_BACKOFF 参数（原本专用于 429 重试）

[1.1.2] - 2026-04-10

修复

• --dry-run 语义修正：预览模式现在只显示待上传图片，不再实际上传或修改文件

文档完善

• 在 SKILL.md 的前置条件中补充 jq 与 curl
• 将 --dry-run 说明统一为“不上传、不修改文件”的预览模式

[1.1.1] - 2026-02-05

修复

• 修复 macOS 兼容性问题: macOS 默认 /bin/bash 版本为 3.2，不支持关联数组 declare -A
  • 将 shebang 改为 #!/usr/bin/env bash，优先使用较新的 bash（如 homebrew 安装的版本）
• 修复图片匹配正则表达式问题: bash 内置正则表达式无法正确匹配复杂图片路径
  • 改用 grep -o 提取所有图片引用，更可靠且兼容性更好
  • 使用字符串处理提取 alt 文本和路径，避免正则表达式转义问题

技术优化

• 使用 grep + 字符串操作代替 bash 正则匹配，提高脚本兼容性
• 优化已处理路径的去重逻辑，避免重复上传同一图片

[1.1.0] - 2026-01-21

新增

• 自动删除本地图片: 上传成功后默认删除本地图片文件，节省存储空间
• --keep-local 选项: 支持保留本地图片文件，用户可选择是否删除

修复

• 修复脚本意外退出问题: 原脚本使用 set -e 导致计数器为 0 时返回退出码 1，脚本被终止
  • 改用 set -o pipefail + let 命令进行计数，避免计数器导致脚本退出
• 修复一行多图片处理问题: 原脚本逐行处理，一行有多个 ![]() 时只处理第一个
  • 改用正则循环 + 字符串替换，正确处理一行中的所有图片引用

技术优化

• 新增 delete_local_image() 函数处理本地图片删除逻辑
• 使用关联数组 declare -A uploaded_files 追踪已上传文件
• 优化图片匹配正则表达式，支持复杂 Markdown 场景
• 改进路径规范化处理，兼容更多路径格式

文档更新

• 更新 SKILL.md，补充 --keep-local 选项说明
• 新增命令选项表格，清晰展示各选项功能
• 更新工作流程说明，明确默认删除本地图片的行为

[1.0.0] - 2026-01-09

新增

• 初始版本发布：PicList 图片上传技能，支持通过 PicList HTTP Server 接口上传 Markdown 中的本地图片到图床
• 支持单个/多个 Markdown 文件批量处理
• 支持目录扫描：自动发现并处理指定目录下的所有 .md 文件
• 支持两种输出模式：
  • --dry-run：预览模式，显示上传结果但不修改原文件
  • --in-place：替换模式，直接修改原文件，将本地路径替换为云端 URL
• 智能过滤：自动跳过已经是云端链接（http://、https://）的图片，避免重复上传
• 相对路径解析：自动将 Markdown 中的相对路径解析为绝对路径
• 统计报告：显示上传成功、跳过和失败的图片数量
• 错误处理：文件不存在或上传失败时保留原路径，继续处理其他图片

技术优化

• 使用 Bash 脚本实现图片上传和 Markdown 文件处理
• 通过 curl 调用 PicList HTTP Server API（默认端口 36677）
• 支持环境变量 PICLIST_SERVER 自定义服务器地址
• 逐行解析 Markdown 文件，精确替换图片链接
• 保留原始 alt 文本描述

支持格式

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

文档完善

• 添加 PicList 安装与配置指南（references/setup.md），包含：
  • 各平台下载安装方法
  • HTTP Server 启用步骤
  • 主流图床配置示例（GitHub、阿里云 OSS、腾讯云 COS、SM.MS）
  • 配置验证方法
• 更新 SKILL.md 前置条件，明确指向配置文档

改进

• 添加启动预检查：在处理前自动检测 PicList HTTP Server 连接状态
• 提供友好的错误提示：当服务不可用时，显示配置指南和下载地址
• 连接超时设置为 3 秒，快速反馈服务状态