开发指南

发布新工具

518.PLUS 是面向 AI Agent 与 Web 用户的工具发布与托管平台。你只需托管自己的 HTTPS 端点,平台负责南向拼装、鉴权封装、SSRF 防护传输、计费结算与多模态结果呈现。本指南提供通过 MCP、REST API 与网页表单发布工具的完整规范、manifest 声明模式及端点通信契约。

1. 什么是 518 工具

工具是开发者自主托管的标准 HTTPS 服务。一个工具的输入由两部分组成,全部请求行为均由声明严格定义:

  • 附件输入(Attachments):[files_min, files_max](至多 20 个文件),附带格式分组(format_family)与 accept 扩展名清单。
  • 字段输入(Fields):至多 16 个字段(其中对调用方可见至多 8 个),支持 enum、number、boolean、text(≤ 100000 字符,可选多行)与 json(任意合法 JSON,规范序列化 ≤ 100000 字符)。

请求拼装声明定义平台如何将一次调用组装为发往你端点的 HTTP 请求:

  • 请求方法与地址:支持 GET / POST。固定查询参数可直接写在 URL 中;路径占位符 {key} 绑定 in: path 字段。完整拼装 URL ≤ 8 KB。
  • 请求体编码:支持 none、json、form、multipart、raw、envelope。字段按各自 in 位置注入请求。
  • 常量字段(const):固定为其默认值,不向调用方透出,但每次请求均完整拼装发送。
  • 凭证封存:鉴权 Token 可落位在 Header 或 Query,由平台安全封存,严禁进入调用方日志或响应。

单文件体积上限为 50 MB。工具发布后,同时在网页端、MCP 服务(/mcp)与公开 REST API(/v1)统一就绪。

2. 通过 Agent 发布(MCP 协议)

标准工作流如下:

  1. 接入验证:使用具备 tools:publish 权限的 API 密钥或 OAuth 凭据连接 https://518.plus/mcp。
  2. 提交声明:调用 publish_tool 提交 manifest。新建工具默认处于 unlisted(私有测试)状态,通过返回的 key 可立即发起调用。
  3. 自测联调:调用 tools/call 对新工具自测一次(作者自测完全免费)。成功通过一次调用即可解锁公开上架权限。
  4. 上架市场:调用 update_tool 提交 {"visibility": "public"},正式对全网开放。
  5. 日常维护:通过 list_my_tools、get_my_tool、tool_call_log 与 delete_tool 管理工具生命周期与查看调用审计。

三个典型 Manifest 示例:

(a)GET API:固定查询参数嵌入端点,多行文本参数落位 Query:

{
  "label": { "en": "Commons Search", "zh": "Commons 搜索" },
  "url": "https://commons.wikimedia.org/w/api.php?action=query&list=search&format=json",
  "method": "GET",
  "body": "none",
  "cost": 0,
  "fields": [
    { "key": "srsearch", "type": "text", "multiline": true,
      "in": "query", "required": true,
      "label": { "en": "Search term", "zh": "搜索词" } } ]
}

(b)JSON POST API:模型版本为常量 Body 字段,鉴权置于 Header:

{
  "label": { "en": "Describe Image", "zh": "图片描述" },
  "url": "https://api.example.com/v1/describe",
  "method": "POST",
  "body": "json",
  "timeout_s": 120,
  "auth_in": "header", "auth_name": "Authorization", "auth_token": "Bearer sk-…",
  "cost": 20,
  "files_min": 1, "files_max": 1, "format_families": "image", "accept": [".png", ".jpg"],
  "fields": [
    { "key": "model", "type": "enum", "const": true, "default": "v2",
      "in": "body", "options": [{"value": "v2", "label": "v2"}],
      "label": {"en": "Model"} },
    { "key": "detail", "type": "json", "in": "body",
      "label": { "en": "Extra options (JSON)" } },
    { "key": "image_url", "type": "text", "in": "body", "files": true,
      "label": { "en": "Image" } } ]
}

(c)multipart 文件 API:附件按附件落位字段名为分段名发送文件:

{
  "label": { "en": "REST Packager", "zh": "打包" },
  "url": "https://api.example.com/package",
  "method": "POST",
  "body": "multipart",
  "cost": 10,
  "files_min": 1, "files_max": 8, "format_families": "document", "accept": [".pdf"],
  "fields": [
    { "key": "docs", "type": "text", "in": "body", "files": true,
      "label": { "en": "Documents" } },
    { "key": "title", "type": "text", "in": "body",
      "label": { "en": "Package title" } } ]
}

错误统一以 isError 结果的 _meta.error = {code, field, message} 结构返回(详见第 7 节)。

3. 用 REST API 或网页控制台发布

REST API(/v1):携带具 tools:publish 权限的 API 密钥,与 MCP 发布元工具保持完全同构:

  • GET /v1/usertools —— 查看名下工具列表
  • POST /v1/usertools —— 创建新工具(提交 Manifest)
  • GET /v1/usertools/{key} —— 获取配置与只读运行时事实({manifest, readonly})
  • PATCH /v1/usertools/{key} —— 局部更新指定字段
  • DELETE /v1/usertools/{key} —— 删除工具
  • GET /v1/usertools/{key}/calls —— 查看最近 20 次他人调用明细

网页控制台:登录后访问 /account/tools/publish,支持粘贴 cURL 命令一键导入、可视化字段编辑及实时联调自测。

4. Manifest 字段参考

与 MCP 发布元工具声明的 Schema 完全一致:

字段类型 / 范围说明
labelLocalizedText (string | object)Tool name shown in the market and to agents: a string or a {locale: text} object
descLocalizedText (string | object)What the tool does, what it takes and what it returns: a string or a {locale: text} object
urlstringYour https endpoint; its host must resolve to a public IP address. Fixed query parameters may live in the URL; path {key} placeholders bind in:path fields
methodenum: GET, POSTGET admits no request body and no in:body fields
bodyenum: none, json, form, multipart, raw, envelopeHow the request body is assembled: none (no body) / json (in:body fields as top-level keys) / form (urlencoded) / multipart (in:body fields as parts, attachments as file parts) / raw (the ONE in:body field is the whole body) / envelope (the 518 protocol {files, params}). Default: json without attachments, envelope with
timeout_sintegerSeconds the platform waits for your endpoint to answer
auth_inenum: header, queryWhere the credential rides
auth_namestringName of the one fixed credential header (or query key) sent to your endpoint (optional); header names are reserved and rejected: connection, content-length, content-type, expect, host, proxy-connection, te, trailer, transfer-encoding, upgrade, user-agent
auth_tokenstringValue of the credential: stored encrypted and never returned; a query-placed token never appears in logs or error details. Send auth_name and auth_token both as empty strings to clear the credential
costintegerPrice per call in credits (1000 credits = US$1); 0 = free
visibilityenum: private, unlisted, publicprivate = only you; unlisted = callable by anyone who has the key, not in the market; public = listed in the market (needs one successful call by you first)
enabledbooleanWhether the tool accepts calls
files_minintegerFewest attachments per call
files_maxintegerMost attachments per call; 0 declares a no-attachment tool
acceptarray (max — items)Attachments: accepted extensions, lowercase with a leading dot (e.g. .png); all must belong to the format_families category
format_familiesenum: image, document, data, text, audio, video, cad3d, archive, allAttachments: the input category (one key; it also sets the tool icon)
fieldsarray (max 16 items)Input fields (at most 16, of which 8 are visible to callers); their values are validated and assembled into the request per the field's `in`
outputsarray (max — items)Result kinds your endpoint may return

字符限制:label 每语言 ≤ 40,desc ≤ 200;auth_name ≤ 64,auth_token ≤ 4096。数值字段仅接收标准 JSON 数字。

5. 公开调用 API(/v1)与调用方输入契约

所有入口(Web / MCP / REST)遵循精确五键调用契约:{tool_id, files, params, delivery, client_ref}。

  • files 为附件引用列表(files_max = 0 的无附件工具省略该键)。
  • params 携带非常量可见字段(常量与附件落位字段拒绝调用方传值)。
  • client_ref 必填非空字符串(≤ 128 字符),作为幂等操作标识,重试相同请求绝不发生二次扣费。

调用侧 /v1 公开端点(仅认 Authorization: Bearer fsk_…,统一 JSON 错误,无 CORS 头):

  • GET /v1/tools、GET /v1/tools/{key} —— 获取公开目录与单工具声明。
  • POST /v1/tools/{key} —— 执行工具;支持 JSON({"params", "files"})或 multipart/form-data(file 文件分段 + 具名参数分段)。请求头携带 Idempotency-Key(充当 client_ref)及可选 X-518-Expiry-Days / X-518-Allowed-Downloads。
  • GET /v1/balance —— 查询当前可用积分与 24 小时入站配额余量。
  • GET/POST /v1/topup/crypto/… —— 程序化稳定币充值订单面(options、orders、orders/{id}、orders/{id}/paid、orders/{id}/cancel;建单必须携带 Idempotency-Key)。

6. 端点通信与 HTTP 契约

南向请求拼装:

  • none:无请求体(GET 请求)。
  • json:in: body 字段作为 JSON 顶层键;附件以单次临时签名拉取 URL 落入附件落位字段。
  • form:表单编码注入参数与附件拉取地址。
  • multipart:in: body 字段为表单分段;附件以落位字段名为名称作为实际文件分段直接上传,内容字节与暂存一致。
  • raw:唯一的 in: body 字段即整个请求体(文本按 UTF-8,JSON 按标准序列化字节)。
  • envelope:518 标准信封协议 {"files": [...], "params": {...}}。

响应解释规则(基于 Content-Type):

  • application/vnd.518.items+json:解释为多项结果信封(支持 data_b64 或 url)。
  • application/json 及 application/*+json:单个 JSON 项。
  • text/*:单个文本项(text/html 与 application/xhtml+xml 一律强制作为文件项落地以防 XSS)。
  • 其他二进制类型:解释为单个文件项(优先按 Content-Disposition 提取文件名,否则根据字节嗅探推导扩展名)。
  • 2xx 空响应体或超过 1 MB 且未声明输出含 file 的文本直接判定失败。

上游故障与自动熔断:

  • 端点返回非 2xx:平台向调用方返回 HTTP 502,附带提供者状态码与响应体前 4 KB 报文以供排障。
  • 端点超时:平台返回 HTTP 504。
  • 自动暂停规则:超时、无法连接(DNS/网络失败)、上游 5xx、401/403 鉴权失败、响应不合规均计入故障统计。同一配置下 10 分钟内连续失败 3 次,系统自动暂停该工具的公开供应以保护调用方;发布者成功自测运行一次后即可恢复。

7. 错误码表

发布接口返回统一三元组 {code, field, message}:

code含义 / 调整指引
bad_labelThe tool name is missing, empty or longer than 40 characters.
bad_descThe description is invalid (over 200 characters per language or wrong shape).
https_requiredThe endpoint must be an https URL on a public address.
bad_urlThe endpoint URL is invalid.
bad_timeouttimeout_s must be an integer between 5 and 300.
bad_auth_nameSomething went wrong, please try again
bad_auth_inSomething went wrong, please try again
bad_methodSomething went wrong, please try again
bad_body_encodingSomething went wrong, please try again
bad_files_rangeMinimum files cannot exceed the maximum
bad_acceptaccept must be an explicit non-empty list of extensions inside the declared scenario's format group.
bad_format_familyformat_families must be a single scenario key.
bad_bindingThe request assembly is inconsistent: check method, body encoding, field locations and the endpoint's own query
bad_outputsChoose at least one output type
bad_visibilityvisibility must be private, unlisted or public.
bad_costcost must be an integer between 0 and 100000.
fields_too_manyToo many fields: max 16 per tool, 8 visible
unknown_fieldUnknown manifest field: it is not part of the publish manifest and is not accepted.
needs_successful_runCall your own tool successfully once before making it public.
too_many_toolsYou reached the limit of 20 tools.
credential_vault_unavailableCredential storage is temporarily unavailable — try again shortly.
not_foundNo such tool under your account.

8. 经济模型与生命周期

  • 定价:每次调用 0–100000 积分(1000 积分 = 1 美元),0 代表免费。
  • 分成:付费调用成功结算时,扣减平台佣金(当前 20%)后的全部收益实时计入你的收益余额。
  • 提现:收益余额达到 $10.00 即可申请提现。
  • 失败保护:调用失败 100% 自动退款给调用方。作者自测免扣费、不产生收益。
  • 生命周期:新建工具默认为 unlisted;自测成功后可公开为 public;支持自主停用/启用与删除。每个账号至多支持创建 20 个工具。

9. 平台边界与设计约束

  • 同步调用:每次调用为严格的同步请求/响应,不支持轮询长任务。
  • 整包返回:应答整体读取并解析,不支持 SSE 流式传输。
  • 固定凭证:每个工具由平台安全注入一个预设凭证,平台不代用户做 OAuth 授权。
  • 原样传递:端点返回什么,调用方即按 Content-Type 接收什么,平台不做侵入式数据改写。
  • 单次结果集:单次调用产出至多 20 项结果,不支持分页流式拉取。