立刻智能体平台 - 技能接入规范 Skills Spec 1.0

概述

技能是平台在对话中向你的公网 HTTP 接口出站请求，再把结果回喂给模型。执行器只做 HTTP 调用，不是 MCP，也不在本页提供在线试调。

本页 vs 开放 API：本页 = 如何让你的 API 被登记为技能。开放 API 文档 = 如何调用智能体会话。会话契约见 /doc/v1/。

登记后发生什么

①登记 URL
方法 / Schema / 鉴权头

②绑到智能体
模型按需发起 tool call

③平台出站
注入请求头，不把密钥给模型

④回喂分支
截断后交给模型组织回答

对接示例请用占位地址，例如 https://api.example.com/v1/lookup。预置技能可使用与现网一致的公开生产域名（见下表），正文不写密钥。

预置技能公开 URL

技能	方法	公开 URL
汇率查询	GET	`https://api.likelic.com/api/v1/exchange/convert`
IP 查询	GET	`https://api.likelic.com/api/ip`
二维码生成	GET	`https://api.likelic.com/api/qrcode`
HS 编码搜索	POST	`https://hs.likelic.com/api/keyword-analysis`
HS 编码详情	POST	`https://hs.likelic.com/api/hscode-lookup`
舱单状态查询	POST	`https://manifest.likelic.com/api/v1/manifest/query`

URL 与方法

出站只允许 GET 或 POST。URL 必须是 https 公网地址，登记与执行前都要过 SSRF 校验。

禁止内网、环回、localhost、链路本地与云元数据主机名。
禁止在 URL 里写用户名密码；协议仅 https。
执行器不跟随 3xx，避免公网地址跳到内网。
GET 把 schema 内字段放在 query；POST 放在 JSON body。

GET  https://api.example.com/v1/lookup?q=example
POST https://api.example.com/v1/lookup
Content-Type: application/json

{ "q": "example" }

不要把内网 IP、本机回环或未公开的上游地址写进文档或登记表单。示例一律用 https://api.example.com/...。

鉴权

平台在出站时把密钥注入请求头。默认头名 X-API-Key，可改成你的接口要求的头（如 Authorization）。

项	说明
请求头注入	有密钥时：`{认证头}: {密钥}`。模型看不到头名以外的密钥值。
密钥可空	公开接口可不填密钥，此时不带认证头。
密钥格式	仅可见 ASCII（1–512 位）；混入中文 / 引号 / 空格会被拒绝保存。
附加请求头（可选）	名与值成对填写；上游要求密钥之外的固定标记头（如 `X-Tenant-Id: prod`）时用。头名规则同认证头（禁 `Host` 等保留头），不能与认证头同名；值为 1–200 位可见 ASCII。留空不带。
附加参数（可选）	名与值成对填写；上游从参数里验固定标记时用。GET 并入 query，POST 并入 JSON body 顶层（覆盖模型填的同名入参）。留空不注入。
URL 自带 query	API URL 可直接带查询参数（如 `?source=xxx`），出站时原样保留。POST 接口若从 query 验固定标记，必须用这种方式——附加参数在 POST 下进的是 body，服务端从 query 读不到。
密钥不进模型	回喂文本会脱敏；密钥不进 tool 参数、不进对话、不进帮助中心。
空提交保持	已保存过密钥时，控制台再提交空字段表示保持原值，不会清空。
试调回显	试调结果显示实际携带的请求头与附加参数（认证头只露末 4 位），用于排上游 401。

POST /v1/lookup?source=your-mark HTTP/1.1
Host: api.example.com
X-API-Key: <由平台注入，示例不写真实密钥>
X-Tenant-Id: prod        ← 附加请求头（可选）

{ "q": "example", "channel": "agent" }   ← channel 为附加参数（可选，POST 并入 body）

安全：不要在本页、仓库或提示词里粘贴真实 API Key 或密封密文。轮换密钥只在控制台完成。

入参 JSON Schema

模型只填写 schema 内字段。URL 与 HTTP 方法来自技能登记，不由模型改写。名为 url / method / api_url / http_method 的字段会被忽略。

schema 须为可解析的 JSON Schema 对象（type: object + properties）。必填列在 required。

{
  "type": "object",
  "required": ["q"],
  "properties": {
    "q": { "type": "string", "description": "查询关键词" },
    "limit": { "type": "integer", "description": "最多返回条数" }
  }
}

缺必填参数时执行器会走 need_clarification，不出站、不扣点，由模型向用户追问。

四分支及默认匹配

每次出站结果归入四个分支之一。可配置有序 match_rules（按 HTTP 状态、JSON 路径或 Content-Type）。未配置或无一命中时：HTTP 2xx → success，其余 → error。

分支	含义	对接建议
`success`	查到可用结果	2xx + 业务成功；回喂字段供模型转述
`need_clarification`	缺参或参数不合法	返回可给用户看的补参说明，不要编造
`not_found`	参数齐但无记录	明确未找到，引导核对后再试
`error`	上游失败 / 超时 / 非预期	不要把密钥、白名单或内部栈暴露给模型

默认匹配

未写规则，或规则都未命中：200–299 → success，其它状态（含 3xx/4xx/5xx、网络失败）→ error。
规则按数组顺序，先命中先生效。

[
  { "when": { "http": [401, 403, 429, 500, 502, 503, 504] }, "branch": "error" },
  { "when": { "json": { "path": "status", "eq": "error" } }, "branch": "error" },
  { "when": { "json": { "path": "status", "eq": "need_clarification" } }, "branch": "need_clarification" },
  { "when": { "json": { "path": "status", "eq": "not_found" } }, "branch": "not_found" },
  { "when": { "json": { "path": "status", "eq": "success" } }, "branch": "success" }
]

超时与每分钟上限

每个技能有独立的超时与每分钟调用上限（RPM）。缺省：超时 10000 ms，RPM 30。舱单等慢接口可把超时调高（预置舱单为 25000 ms）。超时须为正整数，不另设「不得低于 25 秒」的上限。

项	说明
超时	超过 `timeout_ms` 记为出站失败，分支 `error`，摘要「请求超时」。
每分钟上限	按（企业, 技能, 自然分钟）计数。超限不出站、分支按错误处理、不扣点；对话仍正常返回。
试调	控制台试调不计入 RPM、不写调用流水、不扣点。

回喂截断

回喂给模型的正文最长 4000 字符，超出后截断并标明已截断。密钥会被打码。

禁止把图片字节或 base64（含 data:image/...;base64,...）送给模型。
非 JSON / 非文本响应默认拒绝回喂原始字节，按错误处理。
二维码等出图技能把图片交给前端展示，不把二进制塞进模型上下文。

你的接口应返回 JSON 或短文本。不要在 JSON 里嵌整图 base64。需要展示图片时返回可访问的 https 图片 URL，由会话界面渲染。

扣点时机

收费技能（N 技能点/次）与套餐 Token 分户记账。扣点只看这次有没有真正出站。

情况	是否扣点
已向你的 URL 发出请求（出站）	先扣。HTTP 失败、超时等技术失败会冲正（退回本次点数）。
缺参追问、套餐不符、积分不足、触达 RPM 未出站	不扣
企业自建技能	强制免费，不扣技能点
控制台试调	不扣、不记流水

业务上的 not_found / need_clarification 若已经出站，按计费规则处理；技术失败（超时、连接失败、5xx 被判 error 等）走冲正。未出站一律不扣。

企业自建

旗舰版（Ultra）企业可在控制台「技能管理 → 我的技能」登记自己的 HTTP 接口，试调通过后再绑到智能体。基础版 / 专业版不提供该入口。

约束	说明
仅 Ultra	可用套餐固定为旗舰版，不可改。
免费	计费强制免费，不能标技能点单价。
最多 20	本企业未硬删的自建技能最多 20 条。
`skill_key`	须匹配 `^[a-zA-Z][a-zA-Z0-9_]{1,63}$`（字母开头，2–64 位字母数字下划线）。创建后不可改。不得与任一平台技能 key 相同，本企业内唯一。
不可上广场	自建技能不能上架智能广场，不能当技能包售卖。

出站、鉴权、Schema、四分支、超时 / RPM、回喂规则与平台技能相同。密钥只回显脱敏末几位。

立刻智能体平台 · 技能接入规范

概述