开发指南
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 协议)
标准工作流如下:
- 接入验证:使用具备
tools:publish权限的 API 密钥或 OAuth 凭据连接https://518.plus/mcp。 - 提交声明:调用
publish_tool提交 manifest。新建工具默认处于unlisted(私有测试)状态,通过返回的 key 可立即发起调用。 - 自测联调:调用
tools/call对新工具自测一次(作者自测完全免费)。成功通过一次调用即可解锁公开上架权限。 - 上架市场:调用
update_tool提交{"visibility": "public"},正式对全网开放。 - 日常维护:通过
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 完全一致:
| 字段 | 类型 / 范围 | 说明 |
|---|---|---|
label | LocalizedText (string | object) | Tool name shown in the market and to agents: a string or a {locale: text} object |
desc | LocalizedText (string | object) | What the tool does, what it takes and what it returns: a string or a {locale: text} object |
url | string | Your 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 |
method | enum: GET, POST | GET admits no request body and no in:body fields |
body | enum: none, json, form, multipart, raw, envelope | How 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_s | integer | Seconds the platform waits for your endpoint to answer |
auth_in | enum: header, query | Where the credential rides |
auth_name | string | Name 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_token | string | Value 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 |
cost | integer | Price per call in credits (1000 credits = US$1); 0 = free |
visibility | enum: private, unlisted, public | private = 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) |
enabled | boolean | Whether the tool accepts calls |
files_min | integer | Fewest attachments per call |
files_max | integer | Most attachments per call; 0 declares a no-attachment tool |
accept | array (max — items) | Attachments: accepted extensions, lowercase with a leading dot (e.g. .png); all must belong to the format_families category |
format_families | enum: image, document, data, text, audio, video, cad3d, archive, all | Attachments: the input category (one key; it also sets the tool icon) |
fields | array (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` |
outputs | array (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_label | The tool name is missing, empty or longer than 40 characters. |
bad_desc | The description is invalid (over 200 characters per language or wrong shape). |
https_required | The endpoint must be an https URL on a public address. |
bad_url | The endpoint URL is invalid. |
bad_timeout | timeout_s must be an integer between 5 and 300. |
bad_auth_name | Something went wrong, please try again |
bad_auth_in | Something went wrong, please try again |
bad_method | Something went wrong, please try again |
bad_body_encoding | Something went wrong, please try again |
bad_files_range | Minimum files cannot exceed the maximum |
bad_accept | accept must be an explicit non-empty list of extensions inside the declared scenario's format group. |
bad_format_family | format_families must be a single scenario key. |
bad_binding | The request assembly is inconsistent: check method, body encoding, field locations and the endpoint's own query |
bad_outputs | Choose at least one output type |
bad_visibility | visibility must be private, unlisted or public. |
bad_cost | cost must be an integer between 0 and 100000. |
fields_too_many | Too many fields: max 16 per tool, 8 visible |
unknown_field | Unknown manifest field: it is not part of the publish manifest and is not accepted. |
needs_successful_run | Call your own tool successfully once before making it public. |
too_many_tools | You reached the limit of 20 tools. |
credential_vault_unavailable | Credential storage is temporarily unavailable — try again shortly. |
not_found | No such tool under your account. |
8. 经济模型与生命周期
- 定价:每次调用 0–100000 积分(1000 积分 = 1 美元),0 代表免费。
- 分成:付费调用成功结算时,扣减平台佣金(当前 20%)后的全部收益实时计入你的收益余额。
- 提现:收益余额达到 $10.00 即可申请提现。
- 失败保护:调用失败 100% 自动退款给调用方。作者自测免扣费、不产生收益。
- 生命周期:新建工具默认为
unlisted;自测成功后可公开为public;支持自主停用/启用与删除。每个账号至多支持创建 20 个工具。
9. 平台边界与设计约束
- 同步调用:每次调用为严格的同步请求/响应,不支持轮询长任务。
- 整包返回:应答整体读取并解析,不支持 SSE 流式传输。
- 固定凭证:每个工具由平台安全注入一个预设凭证,平台不代用户做 OAuth 授权。
- 原样传递:端点返回什么,调用方即按 Content-Type 接收什么,平台不做侵入式数据改写。
- 单次结果集:单次调用产出至多 20 项结果,不支持分页流式拉取。