pinme-share

将任意文件或目录上传至 PinMe（公共 IPFS），并获取一个简短的 *.pinit.eth.limo URL。

• 版本: 1.0.1
• 许可证: MIT
• 作者: Evan Song · github.com/Songhonglei
• 代码仓库: https://github.com/Songhonglei/html-tool-suite

⚠️ 公共数据警告 — 首次使用前请务必阅读

• PinMe 运行于公共 IPFS 上：您上传的任何内容均为全球可读；任何人只要持有该 URL 即可访问。
• CID 实质上不可删除：IPFS 节点会缓存内容；--rm 仅从您的账户中移除 pin 引用 — 第三方节点上的副本仍可能持续存在。
• 🚫 切勿上传：公司内部文档 / 客户数据 / 凭据 / 私人信息 / 尚未发布的材料。
• 每次执行 upload 均会在 stderr 输出一条警告；在自动化流程中可通过传入 --yes 跳过该提示。

🔑 首次配置 — 设置您的 AppKey

PinMe v2.x 需要身份认证。AppKey 查找顺序如下：

1. PINME_APPKEY 环境变量（最高优先级，不持久化 — 适用于 CI 或一次性任务）
2. pinme CLI 已配置 AppKey → 直接复用
3. 本地文件 ~/.local/share/pinme-share/appkey.json 存在 → 自动应用于 pinme CLI
4. 否则 → 脚本返回 error_type: auth_required，并提示用户前往 https://pinme.eth.limo 获取 AppKey

配置 / 替换 AppKey（持久化）

python3 scripts/upload_to_pinme.py --set-appkey 

该命令将密钥同时写入 pinme CLI 和 ~/.local/share/pinme-share/appkey.json（权限为 0600）。 该本地文件绝不会被提交至 Git 或随发布的 skill bundle 分发。

自定义存储路径（高级）

export PINME_APPKEY_FILE=/custom/path/appkey.json
# 或自动适配 $XDG_DATA_HOME：
export XDG_DATA_HOME=$HOME/my-xdg-data   # → $HOME/my-xdg-data/pinme-share/appkey.json

查看当前配置

python3 scripts/upload_to_pinme.py --show-appkey

📤 上传

# 任意单个文件
python3 scripts/upload_to_pinme.py /path/to/file.html
python3 scripts/upload_to_pinme.py /path/to/report.pdf

# 整个目录（无需 index.html）
python3 scripts/upload_to_pinme.py /path/to/dist/

# 添加 --verbose 查看大文件上传进度
python3 scripts/upload_to_pinme.py /path/to/video.mp4 --verbose

# 跳过隐私警告（适用于 cron / 自动化流水线）
python3 scripts/upload_to_pinme.py /path/to/file.html --yes

# 自定义超时时间（默认：60s + 每 MB 2s，下限 180s，上限 1800s）
python3 scripts/upload_to_pinme.py /path/to/big.zip --timeout 900

输出格式 — stdout 最后一行始终为单个 JSON 对象：

{"success": true, "url": "https://xxxx.pinit.eth.limo", "size_bytes": 12345, "timeout_used": 180}

📜 浏览上传历史

python3 scripts/upload_to_pinme.py --list
python3 scripts/upload_to_pinme.py --list --limit 5
python3 scripts/upload_to_pinme.py --list --raw   # 不解析；直接返回原始 CLI 文本

结构化输出示例：

{"success": true, "count": 3, "history": [
  {"name": "foo.html", "cid": "Qm...", "url": "https://xxxx.pinit.eth.limo", "size": "12 KB", "time": "2026-05-21 09:30"}
]}

🗑️ 取消 pin（从您的 pin 列表中移除）

python3 scripts/upload_to_pinme.py --rm 

⚠️ 公共 IPFS 上的副本无法真正删除；此操作仅从您的账户中移除 pin 引用。

💰 钱包 / 配额

python3 scripts/upload_to_pinme.py --wallet

PinMe 提供免费配额（约 500 次上传）。超出后可能产生费用 — 详见 https://pinme.eth.limo 控制台。

🚪 注销

python3 scripts/upload_to_pinme.py --logout

清除 pinme CLI 的会话状态及 ~/.local/share/pinme-share/appkey.json 文件。

🧰 stdout / stderr 接口约定

示例：

URL=$(python3 scripts/upload_to_pinme.py /tmp/foo.html | jq -r '.url')

📋 错误码参考（用于 agent 路由）

退出码说明：0 表示成功 / 1 表示通用失败 / 2 表示结构化失败（需解析 JSON 中的 error_type）。

📦 约束条件与依赖项

• 单个文件 ≤ 200 MB，目录 ≤ 1 GB（PinMe 服务端限制）
• 仅支持静态文件（不支持服务端处理）
• Node.js ≥ 16.13.0（自动校验）
• pinme CLI（如缺失则自动通过 npm install -g pinme 安装）
• PinMe AppKey（必需）

🛠️ 粘贴内容工作流

若用户直接在聊天窗口中粘贴 HTML 内容，agent 应执行以下步骤：

1. 将其写入 /tmp/pinme_user_.html
2. 以该路径调用本脚本
3. 返回生成的 URL

🔧 环境变量

默认存储路径：${XDG_DATA_HOME:-$HOME/.local/share}/pinme-share/appkey.json。

🪪 致谢

• 感谢 PinMe 提供 IPFS 固定服务及 pinme CLI 工具
• 本工具属于 html-tool-suite 项目的一部分 —— 专注于 HTML 生成、发布与共享能力

更新日志

v1.0.1

• 修复（静默失败）：当同时传入多个互斥操作（例如 + --list）时，不再静默执行首个匹配分支并丢弃其余参数，而是返回 conflicting_args 错误。
• 修复（安全性）：当使用 --set-appkey 传入过短的密钥时，不再将密钥片段（key[:20]）回显至错误输出；现仅报告密钥长度。

v1.0.0

• 首次开源发布（符合 XDG 规范的存储路径、英文文档、全英文 CLI）。