上传说明

AI 或自动化脚本可通过以下接口，将工具文件及说明上传到本站私密区。上传成功后，工具会自动出现在私密工具列表中，并生成受密码保护的下载链接。

接口信息

POST https://你的域名/上传路径

认证

所有请求必须在请求头中携带 API Token，支持以下两种方式（任选其一）：

# 方式一：自定义头
X-API-Token: YOUR_TOKEN

# 方式二：标准 Bearer
Authorization: Bearer YOUR_TOKEN

Token 缺失或错误时返回 401 Unauthorized。

API Token

上传需要 API Token 进行认证，Token 由站点管理员单独提供。请妥善保管，不要泄露到公开仓库或客户端代码中。

请求参数

接口接收以下表单字段。其中 file 和 uploader 为必填，其余均为可选：

字段类型必填说明
fileFile必填要上传的工具文件（zip、脚本、二进制等任意类型）
uploaderstring必填上传者标识，格式 类型/名字：人类用 human/张三，AI 用 ai/Claude、ai/GPT-5 等。也可拆成 uploader_type（human/ai）+ uploader_name 两个字段。缺失或类型非法返回 400
idstring可选工具唯一标识。不传则自动生成一个新工具；传入已存在的 ID 会给该工具新增一个版本（旧版本及其文件完整保留，详见下方「多版本机制」）
namestring可选工具显示名称。不传则使用文件名（去掉扩展名）
descriptionstring可选工具的一句话说明，会显示在卡片上
langstring可选编程语言或技术栈，如 Python、Go、Rust、Shell，默认 Unknown
tagsstring可选标签，多个用英文逗号 , 或中文逗号 ， 分隔，如 运维,脚本
iconstring可选一个 emoji 作为工具图标，如 🤖，默认 📦
statusstring可选状态：已完成、WIP（开发中）、自用，默认 WIP
visibilitystring可选可见性：private（私有，默认）或 public（公开到首页）。填其他值按 private 处理
notestring可选本次版本的标签/说明，如 v2.1 修复启动崩溃。不填自动生成 v1、v2…

调用示例

curl

# 最简上传（文件 + 上传者）
curl -X POST 上传地址 \
  -H "X-API-Token: 你的Token" \
  -F "file=@my-tool.zip" \
  -F "uploader=ai/Claude"

# 带上完整元数据
curl -X POST 上传地址 \
  -H "Authorization: Bearer 你的Token" \
  -F "file=@my-tool.zip" \
  -F "uploader=ai/Claude" \
  -F "id=my-tool" \
  -F "name=我的工具" \
  -F "description=这是一个好用的工具" \
  -F "lang=Python" \
  -F "tags=运维,脚本" \
  -F "icon=🤖" \
  -F "status=已完成"

Python

import requests

url = "上传地址"
headers = {"X-API-Token": "你的Token"}

with open("my-tool.zip", "rb") as f:
    resp = requests.post(
        url,
        headers=headers,
        files={"file": f},
        data={
            "uploader": "ai/Claude",
            "name": "我的工具",
            "description": "这是一个好用的工具",
            "lang": "Python",
            "tags": "运维,脚本",
            "status": "已完成",
        },
    )

print(resp.status_code)
print(resp.json())

Node.js

const fs = require("fs");
const form = new FormData();
form.append("file", fs.createReadStream("./my-tool.zip"));
form.append("uploader", "ai/Claude");
form.append("name", "我的工具");
form.append("description", "这是一个好用的工具");
form.append("lang", "Node.js");
form.append("tags", "工具,CLI");

fetch("上传地址", {
  method: "POST",
  headers: {
    "X-API-Token": "你的Token",
    ...form.getHeaders(),
  },
  body: form,
}).then(r => r.json()).then(console.log);

响应

成功响应（HTTP 200）

{
  "ok": true,
  "id": "my-tool",
  "name": "我的工具",
  "file": "my-tool.zip",
  "size": 17408,
  "size_human": "17 KB",
  "url": "/dl/my-tool.zip",
  "replaced": true,
  "version": 2,
  "versions_count": 2,
  "date": "2026-09-10"
}
字段说明
ok是否成功，固定为 true
id工具 ID（传入的或自动生成的）
name工具名称
file服务器上保存的文件名（已做安全清洗，同名自动加序号）
size文件大小，单位字节
size_human人类可读的文件大小
url下载路径（私有工具需登录或使用分享链接才能访问）
replaced是否命中了已存在的同 ID 工具（true 表示这是给老工具加的新版本，而不是新建）
version本次上传生成的版本号（从 1 递增）
versions_count该工具当前的历史版本总数
date上传日期

错误响应

错误时 HTTP 状态码表示错误类型，响应体为 JSON，包含 error 字段：

{ "error": "错误信息" }
状态码含义
400请求格式错误：缺少 file 字段、缺少或非法的 uploader、不是 multipart 请求、表单解析失败等
401API Token 缺失或不正确
404请求路径错误
413文件超过 500 MB 大小限制

多版本机制

同一个工具可以持续上传新版本，历史版本永久保留，不会被覆盖删除。关键在于 id 字段：

场景做法结果
发布新工具不传 id，或传一个全新的 id新建工具，版本号从 v1 开始，replaced 为 false
发布新版本传同一个 id，附上新文件新增 v2、v3…，旧版本文件仍可下载，replaced 为 true

要点：

# 第一次：创建工具（v1）
curl -X POST 上传地址 \
  -H "X-API-Token: 你的Token" \
  -F "file=@my-tool-1.0.zip" \
  -F "id=my-tool" \
  -F "name=我的工具" \
  -F "uploader=ai/Claude"

# 之后升级：同一个 id，自动变成 v2
curl -X POST 上传地址 \
  -H "X-API-Token: 你的Token" \
  -F "file=@my-tool-2.0.zip" \
  -F "id=my-tool" \
  -F "name=我的工具" \
  -F "note=v2.0 新增批量模式" \
  -F "uploader=human/张三"

上传后的行为