类型	适合场景	需要你做什么
AI 大模型（`ai_model`）	直接调用 OpenAI / Claude / 国内大模型 API	填写 API Key 和模型 ID，无需写代码
HTTP 服务商（`http_sync`）	有自己的业务逻辑服务器（查数据库、调工具、自定义 AI 流程等）	搭建一个符合 SlashX 协议的 HTTP 服务
OpenClaw	使用 OpenClaw 网关托管的模型或 Agent	填写 endpoint 和 API Key，无需写代码
Make AI Agents（`make_agent`）	直接运行 Make AI Agent	填写 Make API Host、Token、Team ID 并选择 Agent

不确定选哪个？ 有自己的服务器逻辑 → 选 HTTP 服务商；直接调大模型 → 选 AI 大模型；已有 Make AI Agent → 选 Make AI Agents。

文档导航

快速上手

5 分钟跑通 HTTP 服务商

服务商详解

HTTP 服务商（重点） — 协议、请求格式、响应格式、SSE 流式、示例代码
AI 大模型服务商 — 配置说明、多轮上下文、参数暴露
OpenClaw 服务商 — 配置说明、多轮记忆机制
Make AI Agents 服务商 — 连接参数、上下文与步骤级流式

协议参考

slashx.request.v1 字段详解 — SlashX 发给你服务器的请求格式
slashx.response.v1 字段详解 — 你的服务器返回给 SlashX 的格式
流式响应与 SSE 实现逻辑 — 上下行两套 SSE 协议、同步降级、取消、异步轮询

专题指南

多轮上下文策略 — 四种服务商如何处理对话历史
计费模式与退款 — 按次、按 token、退款触发条件
安全与访问控制 — SSRF 防护、出站白名单、签名验证
调试与错误排查 — 常见错误码、日志位置、排查步骤

示例代码

Node.js 回显 Bot
Python 回显 Bot
Node.js 流式 SSE Bot
curl 自测命令

常见问题 FAQ

核心概念速查

名词	含义
智能体（Agent）	平台上的一个对话单元，配置了服务商、系统提示词、参数限制
服务商（Provider）	实际处理消息的后端：大模型 API、自建服务器、OpenClaw 或 Make AI Agents
会话（Conversation）	一个用户与一个智能体的完整对话历史
对话运行（ChatRun）	每次消息往返的执行记录，包含请求参数、响应、耗时、计费信息
slashx.request.v1	SlashX 发给 HTTP 服务商的请求 JSON 格式
slashx.response.v1	HTTP 服务商返回给 SlashX 的响应 JSON 格式

GET STARTEDQUICKSTART.md

5 分钟快速上手

从零跑通一个 HTTP 回显机器人

5 分钟跑通 HTTP 服务商

本教程带你搭建一个最简单的「回显机器人」：用户发什么，它就回什么。跑通后你就理解了 SlashX 与 HTTP 服务商交互的全部基础。

你需要准备

一台能被 SlashX 访问到的服务器（或本地 + 内网穿透工具，如 ngrok、frp）
Node.js 或 Python 环境（本教程用 Node.js，Python 版见示例代码）

第 1 步：写一个最简服务

新建 echo-bot.js：

const http = require('node:http')

const server = http.createServer((req, res) => {
  if (req.method !== 'POST') {
    res.writeHead(405)
    return res.end('Only POST')
  }

  let raw = ''
  req.on('data', (chunk) => (raw += chunk))
  req.on('end', () => {
    // 1. 解析 SlashX 发来的请求
    const request = JSON.parse(raw)
    const userText = request.input?.text ?? ''

    // 2. 你的业务逻辑（这里只是回显）
    const replyText = `你说的是：${userText}`

    // 3. 按 slashx.response.v1 格式返回
    const response = {
      schemaVersion: 'slashx.response.v1',
      runStatus: 'success',
      messages: [
        {
          id: request.runId,
          role: 'assistant',
          status: 'success',
          content: { text: replyText },
        },
      ],
    }

    res.writeHead(200, { 'content-type': 'application/json' })
    res.end(JSON.stringify(response))
  })
})

server.listen(8080, () => console.log('Echo bot 跑在 http://localhost:8080'))

启动：

bash

node echo-bot.js

第 2 步：在 SlashX 后台配置服务商

进入管理后台 → 服务连接 → 新建
类型选择 HTTP 服务商
端点 URL 填写你的服务地址（如 https://your-domain.com/，本地调试可用内网穿透地址）
鉴权方式：如果你的服务需要鉴权，选 Bearer 并填入密钥；不需要可留空
保存

保存时 SlashX 会校验端点 URL 是否指向内网/保留地址（SSRF 防护）。如果你在私有化部署里需要访问内网地址，见安全指南。

第 3 步：绑定到智能体并测试

新建或编辑一个智能体，把服务商设为刚才创建的连接
在前台打开这个智能体，发一条消息
你会收到「你说的是：xxx」的回复

接下来

这个例子用的是同步返回（一次性返回完整 JSON）。如果你想做流式输出（打字机效果），见 HTTP 服务商详解。

想了解 SlashX 究竟发了什么、字段都是什么含义，见 slashx.request.v1 字段详解。

关键提示：SlashX 对返回格式有一定容错。如果你只返回 { "text": "xxx" } 这样的简单结构，SlashX 也能识别出文本。但生产环境建议严格用 slashx.response.v1 格式，才能用上富文本、多媒体、引用、卡片等能力。详见响应协议。

GET STARTEDARCHITECTURE.md

端到端架构与全流程

一条消息从发出到回复，中间发生了什么

端到端架构与全流程

本文讲清楚：终端用户从发出一条消息，到看到回复，中间 SlashX 和服务商各自做了什么。四种服务商的链路略有不同，分别说明。

整体角色

SlashX 在中间统一负责：身份鉴权、授权校验、参数校验、多轮上下文管理、计费扣费、安全防护（SSRF）、对话记录落库。你只需关心服务商那一端。

统一入口：一个路由，两种返回

所有消息都先进入 SlashX 的流式路由 POST /api/chat/scenario-run-stream。它按服务商类型分叉：

AI 大模型 / OpenClaw / Make AI Agents：SlashX 直接对接上游并转成统一 SSE；Make 是步骤级流式。
HTTP 服务商：转发到专门的处理逻辑，根据你返回的 Content-Type 自动判断：
- 返回 text/event-stream → 当作流式，边收边转发（打字机效果）
- 返回 application/json → 当作同步，一次性返回完整内容

此外还有一个旧的同步路由 POST /api/chat/scenario-run，当流式路由不可用时前端会自动降级到它。两条路由共享同一套计费、归一化、落库逻辑。

链路一：HTTP 服务商（重点）

这是你最需要理解的链路，因为只有这一种需要你自己写服务端代码。

每一步 SlashX 做了什么：

鉴权：确认终端用户已登录、有权访问这个智能体。
创建 ChatRun：写一条运行记录，记下 conversationId、agentId、服务商类型、入站参数。
前置扣费：如果智能体配置了「按次计费」，先扣费；失败（余额不足）则直接返回 BILLING_INSUFFICIENT，不会请求你的服务。
SSRF 校验：校验你配置的端点 URL，禁止指向内网/云元数据地址（除非私有化部署放行，见安全指南）。
发请求：以 slashx.request.v1 格式 POST 到你的端点，带上鉴权头和追踪头。
处理你的响应：按 Content-Type 决定流式还是同步，归一化后推给前端。
落库 + 结算：保存助手回复；如果是「按 token 计费」，按你返回的 usage.promptTokens / usage.completionTokens 分别按输入/输出单价结算。
失败退款：如果你返回了错误，或网络异常，SlashX 会自动把第 3 步扣的费退回。

完整协议见 HTTP 服务商详解。

链路二：AI 大模型

你不需要写代码。SlashX 负责：

把系统提示词 + 多轮历史 + 当前消息拼成 messages 数组
按智能体配置的 context_rounds 截断历史
调用大模型 API（OpenAI 兼容协议），把流式输出实时转给用户

详见 AI 大模型服务商。

链路三：OpenClaw

关键区别：SlashX 不向 OpenClaw 传历史，只发当前这一句。多轮记忆完全由 OpenClaw 服务端按会话标识（x-openclaw-session-key）维护。详见 OpenClaw 服务商。

链路四：Make AI Agents

SlashX 把按 context_rounds 截断的历史和当前消息组成 Make messages，把系统提示词、模型、递归限制等映射到 Make config。同步路径调用 /run，流式路径调用 /run/stream，并把 Make 的 step / done / error 事件归一化后转发给前端。详见 Make AI Agents 服务商。

四种服务商对比

维度	AI 大模型	HTTP 服务商	OpenClaw	Make AI Agents
是否需要写代码	可选	必填	可选	可选
多轮历史	SlashX 拼接并传给模型	SlashX 在请求里带 `history`，你自行决定用不用	SlashX 不传，OpenClaw 服务端维护	SlashX 截断后传入 Make，并可续用 threadId
流式输出	token 流	你返回 SSE	token 流	步骤级 SSE
系统提示词	SlashX 注入	由你的服务端控制	由 OpenClaw 服务端控制	SlashX 写入 Make 运行配置
适合场景	纯模型对话	带业务逻辑的自定义服务	OpenClaw 托管的模型/Agent	已在 Make 中构建的 Agent

关于「系统提示词归谁管」：HTTP 服务商和 OpenClaw 的提示词在你的服务端；AI 大模型和 Make AI Agents 由 SlashX 注入或映射运行配置。

PROVIDERSproviders/http-sync.md

HTTP 服务商

唯一需要写服务端的类型，协议最完整

HTTP 服务商对接详解

适用类型：http_sync · 协议版本：slashx.request.v1 / slashx.response.v1

HTTP 服务商是四种类型里唯一需要你自己写服务端的。本文把出口协议（SlashX 发给你）、入口协议（你返回给 SlashX）、流式输出、鉴权、错误处理彻底讲清楚。

工作原理一句话

SlashX 在每次用户发消息时，向你配置的端点 URL 发一个 POST 请求（JSON 格式），你的服务处理后返回结果。你可以选择同步返回（一次性 JSON）或流式返回（SSE 打字机效果）。

一、SlashX 发给你的请求（出口协议）

请求方法与头

SlashX 用 POST 请求你的端点，带以下请求头：

请求头	说明
`content-type`	`application/json`
`accept`	`text/event-stream, application/json`（表示两种返回都接受）
`x-slashx-trace-id`	本次请求的追踪 ID（UUID），排障时可对照
`x-slashx-run-id`	本次运行 ID（UUID），与响应里的 `runId` 对应
`x-slashx-agent-id`	智能体记录 ID
`x-slashx-version`	协议主版本号（当前为 `1`），始终携带
`authorization`	仅当你配置了 Bearer 鉴权时携带，值为 `Bearer <你的密钥>`
`x-slashx-signature`	仅当你配置了签名密钥时携带，值为 `sha256=<hex>`（HMAC-SHA256，见安全指南）
`x-slashx-timestamp`	仅当你配置了签名密钥时携带，Unix 秒级时间戳（防重放）
自定义头	你在连接配置里填的自定义 Header 会原样带上

请求体（slashx.request.v1）

json

{
  "schemaVersion": "slashx.request.v1",
  "event": "user_message",
  "runId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "traceId": "9c858901-8a57-4791-81fe-4c455b099bc9",
  "conversationId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "userId": "user_abc123",
  "agent": {
    "id": "agent_xyz",
    "name": "客服助手"
  },
  "client": {
    "platform": "pc-web",
    "capabilities": ["stream", "markdown"],
    "locale": "zh-CN"
  },
  "input": {
    "text": "你好，帮我查一下订单"
  },
  "history": [
    { "role": "user", "content": { "text": "上一句用户说的话" } },
    { "role": "assistant", "content": { "text": "上一句助手的回复" } }
  ],
  "extensions": {}
}

重点字段说明（完整字段见 request-v1 详解）：

input.text：用户这次发的消息文本，这是你最需要处理的字段。
history：多轮历史，可选使用。SlashX 已经按智能体配置的轮数截断好。你可以：
- 用它：把 history 拼进你给模型的 prompt，实现多轮对话
- 忽略它：如果你自己用 conversationId 维护状态
conversationId：会话唯一 ID，同一对话每次请求都一样，可作为你侧存储的 key。
runId：建议作为你返回消息的 id，方便对账。
extensions：透传字段。智能体配置的「用户可调参数」会放在这里（如用户在聊天页选的标签、自定义选项）。

关于多轮历史的完整策略，见多轮上下文指南。

二、你返回给 SlashX 的响应（入口协议）

你有两种返回方式，由响应的 Content-Type 决定。

方式 A：同步返回（application/json）

设置 Content-Type: application/json，返回完整的 slashx.response.v1：

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "role": "assistant",
      "status": "success",
      "content": {
        "text": "好的，请提供你的订单号。"
      }
    }
  ],
  "usage": {
    "promptTokens": 120,
    "completionTokens": 30,
    "totalTokens": 150
  }
}

SlashX 收到后会一次性把文本推给前端（用户看到完整回复）。

方式 B：流式返回（SSE）

设置 Content-Type: text/event-stream，按 SSE 格式逐块输出，实现打字机效果。

SSE 帧格式：每帧由 event: 行 + data: 行组成，以两个换行 \n\n 结尾。

css

event: delta
data: {"messages":[{"content":{"text":"好的，"}}]}

event: delta
data: {"messages":[{"content":{"text":"请提供订单号。"}}]}

event: done
data: {"finishReason":"stop"}

SlashX 识别的事件类型：

event	data 结构	说明
`message` / `delta`	`{ "messages": [{ "content": { "text": "片段" } }] }`	文本增量，SlashX 累加并实时转发
`done`	`{ "finishReason": "stop" }`	结束信号，必须发
`error`	`{ "error": { "code": "...", "message": "..." } }`	业务错误，SlashX 会退款

⚠️ 最重要的一条规则：流式必须显式发送 event: done。

不要只是关闭连接就完事。SlashX 靠 done 事件判断生成结束。如果你只关连接不发 done，SlashX 会进入兜底逻辑：有累积文本就按成功保存，完全空响应则按错误（UPSTREAM_CLOSED）处理并退款。为避免歧义，请始终发 done。

⚠️ 不要用 runStatus 判断结束。 中间的 delta 帧即使带了 runStatus 字段也不会被当作结束信号，只有 event: done 才结束。

三、富文本与多媒体

content 不止能放文本。以下字段当前已支持，前端会自动渲染：

字段	类型	渲染效果
`text`	string	Markdown 文本
`images`	数组	图片
`videos`	数组	视频
`audio`	数组	音频
`attachments`	数组	文件附件
`citations`	数组	引用来源（角标 + 来源列表）
`cards`	数组	结构化卡片
`actions`	数组	快捷操作按钮

带图片和引用的例子：

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    {
      "id": "msg-1",
      "role": "assistant",
      "status": "success",
      "content": {
        "text": "根据资料，答案是这样的[1]。",
        "images": [
          { "url": "https://cdn.example.com/a.png", "mimeType": "image/png", "fileName": "图示.png" }
        ],
        "citations": [
          { "index": 1, "title": "参考文档", "url": "https://example.com/doc", "snippet": "原文片段…" }
        ]
      }
    }
  ]
}

各字段的完整 schema 见 response-v1 详解。

四、错误处理

你主动返回业务错误

同步方式：

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "error",
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "找不到该订单",
    "userVisible": true,
    "retryable": false
  }
}

流式方式：发 event: error，data 为 { "error": { "code": "...", "message": "..." } }。

当 SlashX 判定为错误（runStatus: "error" 或带 error）时，会自动退还本次的前置扣费，并把错误提示展示给用户。

SlashX 侧可能返回给前端的错误码

错误码	含义
`BILLING_INSUFFICIENT`	用户余额不足，未发起对你的请求
`PROVIDER_URL_FORBIDDEN`	你的端点 URL 被 SSRF 防护拦截
`NETWORK_ERROR`	连不上你的服务
`HTTP_4xx` / `HTTP_5xx`	你的服务返回了非 2xx 状态码
`UPSTREAM_CLOSED`	流式时你没发任何内容就关了连接
`PARSE_ERROR`	你返回的 JSON 无法解析

完整排障流程见调试指南。

五、鉴权配置

SlashX 后台配置连接时有两类机制，注意它们是独立的：

1. 鉴权方式（auth_type） —— 用来携带一个鉴权凭据：

bearer：请求带 Authorization: Bearer <密钥>。
custom_header：把密钥按 Header-Name: value 格式拆成一个自定义鉴权头（如填 X-Api-Key: abc123，就会带 X-Api-Key: abc123）。
none：不带鉴权头。

2. 附加自定义头（custom_headers） —— 一个独立的键值表，无论选哪种鉴权方式，这些头都会原样带到每个请求上（适合带固定的业务头）。

⚠️ 重要差异：同步处理路径（你返回 JSON）同时支持 bearer 和 custom_header 两种鉴权方式；而流式处理路径目前只实现了 bearer，custom_header 在流式下不会注入鉴权头（但 custom_headers 附加头在两条路径都会带）。如果你的服务靠 custom_header 鉴权，建议改用 bearer，或把鉴权信息放进 custom_headers。

出站签名（HMAC 验签，让你确认请求确实来自 SlashX）已上线：在连接里配置「签名密钥（Webhook Secret）」后，每个请求会带 X-SlashX-Signature / X-SlashX-Timestamp / X-SlashX-Version 头，见安全指南。

六、容错说明

SlashX 对响应格式有一定容错。如果你只返回最简结构，SlashX 也能识别文本：

json

{ "text": "直接返回纯文本也行" }

SlashX 会从 content.text、或顶层的 output / result / message / text / body 等常见字段里提取文本兜底。但生产环境强烈建议严格使用 slashx.response.v1 格式，否则无法使用多媒体、引用、卡片、按 token 计费（需要 usage）等能力。

想深入理解 SlashX 内部如何在「你的上行 SSE」和「前端下行 SSE」之间转译，以及同步降级、取消、异步轮询的完整逻辑，见流式响应与 SSE 实现逻辑。

已知限制与说明

出站请求的 HMAC 签名（需配置签名密钥）、响应体积上限（默认 4MB）、流式空闲超时控制（基于 timeout_ms）、指数退避重试（配置 retryConfig）均已上线，详见安全指南。
event 字段当前主要为 user_message 和 action_click（用户点击按钮时）。conversation_open、cancel、retract、idle 已在协议中预留，标记为 [规划中]，见 request-v1 详解。
流式处理路径目前只实现了 bearer 鉴权方式，custom_header 鉴权仅在同步路径生效；附加自定义头（custom_headers）两条路径都会带。

PROVIDERSproviders/ai-model.md

AI 大模型服务商

直连 OpenAI 兼容模型，零代码

AI 大模型服务商

适用类型：ai_model

AI 大模型服务商让你直接接入兼容 OpenAI 协议的大模型 API（OpenAI、Claude、以及各类国内大模型中转）。你不需要写任何服务端代码，只需在后台填写配置。

工作原理

终端用户发消息后，SlashX 自动完成：

拼接 messages 数组：系统提示词 + 多轮历史 + 当前消息
按配置的 context_rounds 截断历史
以流式方式调用大模型 API
把流式输出实时转给用户（打字机效果）
按返回的 token 用量计费、落库

需要配置什么

配置项	说明
baseURL	大模型 API 的基础地址。连接里可单独覆盖，否则用平台默认
API Key	调用大模型的密钥
模型 ID	如 `gpt-4o`、`claude-3-5-sonnet` 等。SlashX 不预设固定列表，由你按所用中转站实际支持的模型手填
默认参数	`temperature`、`max_tokens` 等

模型 ID 必填且不预设，因为不同中转站支持的模型名各不相同，必须以你的供应商为准。

系统提示词

智能体的系统提示词由 SlashX 注入到 messages 的最前面（role: system）。你在智能体配置里写好提示词即可，无需在别处处理。

多轮上下文（context_rounds）

context_rounds 控制传给模型的历史对话轮数（1 轮 = 1 个用户提问 + 1 个助手回答）。

设置值	行为
留空（不设置）	不限制，传递全部历史
`0`	不带任何历史（每次都是全新对话）
`10`	只带最近 10 轮

SlashX 内部按「最多保留 context_rounds × 2 条消息」截断，从最新的往前取。

这个参数可以固定（开发者设默认值），也可以开放给终端用户调节（在智能体配置里把它设为「用户可调参数」，用户就能在聊天页用滑块自己改）。

轮数越大 token 消耗越高，也可能超出模型上下文窗口，按需设置。

可暴露给用户的参数

你可以把部分模型参数开放给终端用户在聊天页调节，常见的有：

temperature（随机性）
max_tokens（最大输出长度）
context_rounds（上下文轮数）
model（让用户在多个模型间切换，需在配置里预设选项）

参数优先级（从低到高）：连接默认值 → 智能体覆盖 → 用户在聊天页的调节值。

出于安全，只有白名单内的参数会真正传给大模型 API。SlashX 内部参数（如 context_rounds）不会泄漏到模型请求体里。

计费

AI 大模型通常按 token 计费：对话成功后，SlashX 按大模型返回的实际 token 用量结算。详见计费指南。

PROVIDERSproviders/openclaw.md

OpenClaw 服务商

历史由网关托管，零代码

OpenClaw 服务商

适用类型：openclaw

OpenClaw 服务商用于接入 OpenClaw 网关托管的模型或 Agent。你不需要写服务端代码，只需填写配置。

与其他服务商最大的区别：历史归 OpenClaw 管

OpenClaw 服务端本身会维护多轮对话记忆。因此 SlashX 在调用 OpenClaw 时：

只发送当前这一句用户消息，不传任何历史
通过会话标识头让 OpenClaw 服务端自己接上下文

SlashX 注入的标识头：

请求头	值	作用
`x-openclaw-session-key`	`slashx:<conversationId>`	会话标识，OpenClaw 据此维护该会话的历史
`x-openclaw-message-channel`	`slashx`	标记消息来自 SlashX

为什么不传历史？ 如果 SlashX 这边也把历史发过去，就会变成「SlashX 和 OpenClaw 各记一份」，导致内容重复、token 翻倍、回答漂移。所以历史完全交给 OpenClaw 服务端。

需要配置什么

配置项	说明
Gateway 地址	OpenClaw 网关的 endpoint URL
Gateway Token	访问网关的密钥
Agent Target	OpenClaw 侧的目标模型/Agent 标识（相当于「模型 ID」）

三项都必填，缺一会在调用时报错。

系统提示词

与 HTTP 服务商类似，OpenClaw 的提示词和行为由 OpenClaw 服务端控制，SlashX 不注入系统提示词。

设计约束：清空对话需要换会话 ID

由于会话记忆绑定在 session-key = slashx:<conversationId> 上，同一个 conversationId 在 OpenClaw 侧会一直累积历史。

如果你需要「清空上下文重新开始」，应当开启一个新的会话（新的 conversationId）。在旧 conversationId 上继续发消息，OpenClaw 仍会记着之前的历史。这是设计上的隐含约束，不是 bug。

计费

OpenClaw 走与 AI 大模型一致的计费链路，支持按 token 或按次计费。详见计费指南。

PROVIDERSproviders/make-agent.md

Make AI Agents

直连 Make Agent，同步或步骤级流式

Make AI Agents 服务商

适用类型：make_agent

该类型直接调用 Make AI Agents API。你不需要实现 slashx.request.v1 接口，但需要已有可运行的 Make AI Agent 和对应 API Token。

连接配置

在管理端 /profile/service-connections 新建 Make AI Agents 连接，填写：

配置	代码中的用途
API Host	Make API 基地址；保存和调用前会执行出站 URL 安全校验
API Token	以 `Authorization: Token <token>` 调用 Make
Team ID	作为 Make API 的 `teamId` 查询参数
Agent ID	Make Agent 标识；可通过连接拉取 Agent 列表后选择
默认模型	可选，写入 Make 的 `config.llmConfig`

同步调用使用：

text

POST {host}/ai-agents/v1/agents/{agentId}/run?teamId={teamId}

流式调用使用：

text

POST {host}/ai-agents/v1/agents/{agentId}/run/stream?teamId={teamId}

消息与上下文

SlashX 会按 context_rounds 截取最近的用户/助手历史，再追加当前用户消息，组成 Make 的 messages。智能体系统提示词通过 config.systemPrompt 发送；开发者或用户开放的追加提示词通过 config.additionalSystemPrompt 发送。

如果提供已有 threadId，SlashX 会继续传给 Make；没有时由 Make 的响应决定后续线程信息。

流式事件

Make 返回的是步骤级 SSE，而不是逐 token SSE：

event: step：一个完整执行步骤
event: done：最终回复、token 用量和 thread 信息
event: error：Make 执行失败

SlashX 会把这些事件归一化成前端使用的统一流式协议，并将 Make 的 inputTokens / outputTokens / totalTokens 映射到平台计费 usage。

可开放参数

当前向 Make 运行配置映射的参数包括：

追加系统提示词 additional_system_prompt
模型与最大 token 数
递归上限 recursion_limit
历史轮数 context_rounds

具体可见范围仍由智能体的参数暴露配置决定。

PROVIDERSproviders/n8n.md

n8n 工作流

Webhook / Chat Trigger 原生流式接入

n8n 工作流服务商

适用类型：n8n

SlashX 可以调用已激活的 n8n Webhook 或 Chat Trigger 工作流，并把 n8n 的 HTTP chunked JSON 流转换为 SlashX 聊天页统一的 SSE 打字机效果。

推荐：Generic Webhook

在 n8n 创建下面的工作流：

text

Webhook（POST，Respond = Streaming）
  → AI Agent（Enable Streaming）
       ↳ Chat Model
       ↳ 可选 Tools

Webhook 收到的是完整 slashx.request.v1。常用表达式：

数据	n8n 表达式
当前用户文字	`{{ $json.body.input.text }}`
会话 ID	`{{ $json.body.conversationId }}`
历史消息	`{{ $json.body.history }}`
用户参数	`{{ $json.body.extensions }}`
运行 ID	`{{ $json.body.runId }}`

把 AI Agent 的 Prompt 设置为：

text

{{ $json.body.input.text }}

在 SlashX 连接配置中分别填写：

Test Webhook URL：n8n 的 /webhook-test/ 地址，仅用于“测试连接”。
Production Webhook URL：n8n 的 /webhook/ 地址，仅用于智能体真实运行。

测试前先在 n8n Webhook 节点中点击 Listen for test event，再立即点击 SlashX 的“测试连接”。生产使用前保存并激活工作流。

Chat Trigger 模式

Chat Trigger 模式发送：

json

{
  "action": "sendMessage",
  "chatInput": "用户消息",
  "sessionId": "slashx:<conversationId>",
  "metadata": {
    "slashxRunId": "...",
    "slashxTraceId": "...",
    "slashxAgentId": "...",
    "extensions": {}
  }
}

如果工作流连接了 n8n Memory，使用 sessionId 作为会话键。该模式首期主要面向文本聊天；需要完整附件、引用和历史结构时使用 Generic Webhook。

流式配置

真实流式要求：

Webhook 的 Respond 设为 Streaming，或 Chat Trigger 的 Response Mode 设为 Streaming。
AI Agent 开启 Enable Streaming。
让 AI Agent 直接成为最终流式输出节点。
不要在 AI Agent 后放置会等待完整结果的 Code、Set、Respond to Webhook 等节点。
Nginx、Ingress 或 CDN 必须关闭响应缓冲。

如果工作流只产生一个完整 item，连接仍可使用，但聊天页会一次性显示完整回复。

非流式富内容与按 Token 计费

非流式工作流可以直接返回 slashx.response.v1。图片、视频、文件、引用、卡片和按钮会与 HTTP 服务商使用同一套聊天渲染、持久化和媒体编辑能力。

如果智能体选择“按 Token 计费”，响应必须携带 usage：

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    {
      "id": "answer-1",
      "role": "assistant",
      "status": "success",
      "content": {
        "text": "处理完成",
        "images": [
          {
            "url": "https://cdn.example.com/result.png",
            "mimeType": "image/png",
            "fileName": "result.png"
          }
        ]
      }
    }
  ],
  "usage": {
    "promptTokens": 120,
    "completionTokens": 80,
    "totalTokens": 200
  }
}

SlashX 优先按照 promptTokens 和 completionTokens 分别应用输入、输出单价。只返回 totalTokens 时，会把全部 Token 按输出单价结算。没有返回有效 Token 数时不会产生本次按 Token 费用，因此生产工作流应从实际模型节点取得用量，不要估算或写固定值。

鉴权

推荐在 n8n Webhook 使用 Header Auth，并在 SlashX 中选择 Header Auth，按以下格式填写：

text

X-N8N-Auth: your-secret

也可使用 Bearer Token。不要把密钥放在 Webhook URL query 中。

连接测试

服务商页面的“测试连接”只调用 Test Webhook URL，并发送完整、通过 Schema 校验的 slashx.request.v1，其中测试文字为 Reply with pong.。测试可能执行工作流中的外部写操作，因此请先为测试工作流关闭发邮件、写数据库等副作用。

测试会检查：

URL 和鉴权是否可用；
是否能解析 n8n chunked JSON 流；
是否产生可展示文本；
是否完整结束。

常见问题

工作流返回 404

连接测试时确认 n8n 正在监听 Test URL；真实对话时确认工作流已经激活，并使用 /webhook/ Production URL。

没有打字机效果

同时检查 Webhook/Chat Trigger 和 AI Agent 的 Streaming 配置，并移除 AI Agent 后的缓冲节点。

回复重复

SlashX 会识别 n8n 的增量 item 与末尾累计 output，避免重复追加。如果使用了自定义节点再次拼接 Agent 输出，仍可能产生业务层重复，请让最终输出链只保留一份正文。

响应中途超时

提高连接超时，并检查反向代理的 idle timeout。n8n 工作流若包含长时间无输出的节点，连接可能在下一段内容到达前被代理关闭。

PROTOCOLprotocols/request-v1.md

slashx.request.v1

SlashX 发给你的请求格式

slashx.request.v1 字段详解

这是 SlashX 发给 HTTP 服务商的请求格式。本文按代码中的协议定义（provider-protocol-v1.ts）逐字段说明。

schemaVersion 固定为 "slashx.request.v1"。

完整示例

先看一个覆盖所有主要字段的完整请求（包含可选字段），下面的字段表逐项对照阅读会更清楚。真实场景下大部分可选字段会缺失，这里为演示协议能力而全放上：

json

{
  "schemaVersion": "slashx.request.v1",
  "event": "user_message",
  "eventPayload": {},
  "runId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "traceId": "9c858901-8a57-4791-81fe-4c455b099bc9",
  "conversationId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  "userId": "user_abc123",
  "agent": {
    "id": "agent_xyz",
    "name": "客服助手",
    "config": {
      "systemPrompt": "你是一个电商客服助手",
      "model": "gpt-4o",
      "temperature": 0.7,
      "tags": ["vip", "electronics"]
    }
  },
  "client": {
    "platform": "pc-web",
    "capabilities": ["stream", "markdown", "card"],
    "viewport": { "width": 1920, "height": 1080 },
    "locale": "zh-CN",
    "timezone": "Asia/Shanghai"
  },
  "input": {
    "text": "那它支持退货吗？",
    "images": [
      { "url": "https://cdn.example.com/order.png", "mimeType": "image/png", "fileName": "订单截图.png" }
    ],
    "audio": [
      { "url": "https://cdn.example.com/question.mp3", "mimeType": "audio/mpeg", "fileName": "语音咨询.mp3" }
    ],
    "videos": [
      { "url": "https://cdn.example.com/product-demo.mp4", "mimeType": "video/mp4", "fileName": "产品演示.mp4" }
    ],
    "attachments": [
      { "url": "https://cdn.example.com/contract.pdf", "mimeType": "application/pdf", "fileName": "合同.pdf", "attachmentType": "document" }
    ],
    "quotes": [
      {
        "kind": "quote",
        "text": "这个商品是 199 元。",
        "messageId": "prev-msg-id",
        "quotedRole": "assistant",
        "excerpt": "199 元"
      }
    ],
    "actionClick": null
  },
  "history": [
    { "role": "user", "content": { "text": "这个商品多少钱？" } },
    { "role": "assistant", "content": { "text": "这个商品是 199 元。" } }
  ],
  "historyTruncated": false,
  "extensions": {
    "tagKey": "vip",
    "style": "concise"
  }
}

说明：input 里的媒体类字段（images/audio/videos/attachments/quotes/actionClick）在当前运行链路中主要传 text，多模态输入能力随平台支持逐步开放。attachments 比其他媒体多一个 attachmentType 字段（可选），用于标注附件类型（document/video/audio/image 等）。

顶层字段

字段	类型	必填	说明	示例 / 取值
`schemaVersion`	string	必填	固定值	`"slashx.request.v1"`（固定）
`event`	enum	必填	事件类型，见下方枚举	`"user_message"`（默认）/ `"action_click"` / `"conversation_open"` / `"cancel"` / `"retract"` / `"idle"`
`eventPayload`	object	可选	事件附加数据	`{}`
`runId`	string(uuid)	必填	本次运行 ID	`"f47ac10b-58cc-4372-a567-0e02b2c3d479"`
`traceId`	string(uuid)	必填	追踪 ID	`"9c858901-8a57-4791-81fe-4c455b099bc9"`
`conversationId`	string(uuid)	必填	会话 ID，同一对话保持不变	`"1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed"`
`userId`	string	必填	终端用户 ID	`"user_abc123"`
`agent`	object	必填	智能体上下文，见下	见 agent 小节
`client`	object	必填	客户端信息，见下	见 client 小节
`input`	object	必填	用户输入，见下	见 input 小节
`history`	array	可选	多轮历史，默认 `[]`	`[]`
`historyTruncated`	boolean	可选	历史是否被截断过，默认 `false`	`true` / `false`
`extensions`	object	可选	透传扩展字段，默认 `{}`	`{ "tagKey": "vip" }`

event 枚举

值	含义	状态
`user_message`	用户发送消息（默认）	当前主用
`action_click`	用户点击快捷按钮	当前已生效
`conversation_open`	用户打开会话（用于发欢迎语）	`[规划中]`
`cancel`	用户取消当前生成	`[规划中]`
`retract`	用户撤回消息	`[规划中]`
`idle`	长时间未活动	`[规划中]`

当前运行链路主要发送 user_message 和 action_click（用户点击按钮时）。其他事件已在协议中预留，标记 [规划中] 的尚未在运行链路触发。建议你的服务对未知 event 做兼容（忽略或返回空）。

agent（智能体上下文）

字段	类型	必填	说明	示例 / 取值
`id`	string	必填	智能体 ID	`"agent_xyz"`
`name`	string	必填	智能体名称	`"客服助手"`
`config`	object	可选	智能体配置，见下	见下表

agent.config（智能体配置）

字段	类型	必填	说明	示例 / 取值
`systemPrompt`	string	可选	系统提示词	`"你是一个电商客服助手"`
`model`	string	可选	模型 ID	`"gpt-4o"`
`temperature`	number	可选	随机性，范围 0~2	`0.7`
`tags`	array	可选	标签列表	`["vip", "electronics"]`

client（客户端信息）

字段	类型	必填	说明	示例 / 取值
`platform`	enum	必填	客户端平台	`"h5"` / `"ios"` / `"android"` / `"miniprogram"` / `"pc-web"` / `"pc-app"`
`capabilities`	array	可选	客户端能力（可多选）	取值集合：`"image"` / `"video"` / `"audio"` / `"card"` / `"action"` / `"stream"` / `"markdown"`，如 `["stream", "markdown"]`
`viewport`	object	可选	视口尺寸（`width` 必填正整数，`height` 可选）	`{ "width": 1920, "height": 1080 }`
`locale`	string	可选	语言，默认 `zh-CN`	`"zh-CN"`
`timezone`	string	可选	时区	`"Asia/Shanghai"`

你可以根据 capabilities 判断客户端是否支持卡片、流式等，决定返回什么形态的内容。

input（用户输入）

字段	类型	必填	说明	示例 / 取值
`text`	string	可选	文本，默认空字符串	`"那它支持退货吗？"`
`images`	array	可选	图片（MediaPart 数组）	见 MediaPart
`audio`	array	可选	音频（MediaPart 数组）	见 MediaPart
`videos`	array	可选	视频（MediaPart 数组）	见 MediaPart
`attachments`	array	可选	附件（比 MediaPart 多 `attachmentType`）	见 AttachmentPart
`quotes`	array	可选	引用的消息片段	见 Quote
`actionClick`	object/null	可选	用户点击按钮时的数据	`null`（非按钮点击）或见 actionClick

当前运行链路主要传 input.text。媒体类输入字段已在协议定义中，实际投喂能力随多模态支持逐步开放。

MediaPart（多媒体片段）

images / audio / videos 都是 MediaPart 数组，每个元素：

字段	必填	说明	示例 / 取值
`url`	二选一	资源 URL（与 `base64` 至少有一个）	`"https://cdn.example.com/a.png"`
`base64`	二选一	base64 内容（与 `url` 至少有一个）	`"data:image/png;base64,iVBOR..."`
`mimeType`	可选	MIME 类型	`"image/png"` / `"audio/mpeg"` / `"video/mp4"`
`fileName`	可选	文件名	`"订单截图.png"`
`meta`	可选	附加元数据（自由键值）	`{ "width": 800, "height": 600 }`

AttachmentPart（附件）

attachments 是 AttachmentPart 数组，比 MediaPart 多一个字段：

字段	必填	说明	示例 / 取值
`url` / `base64`	二选一	同 MediaPart（至少一个）	`"https://cdn.example.com/c.pdf"`
`mimeType`	可选	MIME 类型	`"application/pdf"`
`fileName`	可选	文件名	`"合同.pdf"`
`meta`	可选	附加元数据	`{}`
`attachmentType`	可选	附件类型（自由字符串，约定取值如下）	`"document"` / `"video"` / `"audio"` / `"image"`（也可自定义）

Quote（引用）

quotes 数组的每个元素：

字段	必填	说明	示例 / 取值
`kind`	必填	固定值	`"quote"`（固定）
`text`	必填	被引用的文本（不能为空）	`"这个商品是 199 元。"`
`messageId`	可选	被引用消息的 ID	`"prev-msg-id"`
`quotedRole`	可选	被引用消息的角色	`"user"` / `"assistant"`
`excerpt`	可选	摘录片段	`"199 元"`

actionClick（用户点击按钮）

当 event: "action_click" 时，actionClick 为对象（否则为 null）：

字段	必填	说明	示例 / 取值
`kind`	必填	按钮类型（自由字符串，通常与响应里 action 的 kind 对应）	`"send_message"` / `"open_url"` / `"copy"` / `"feedback"` / `"custom"`
`value`	必填	按钮值（要发送的文本、要打开的 URL 等）	`"查一下我的物流"`
`label`	可选	按钮显示文字	`"查询物流"`
`sourceMessageId`	可选	源消息 ID	`"msg-1"`

history（多轮历史）

数组，每个元素：

字段	类型	必填	说明	示例 / 取值
`role`	enum	必填	消息角色	`"user"` / `"assistant"` / `"system"` / `"tool"`
`content.text`	string	可选	该轮的文本	`"这个商品多少钱？"`

历史里不传媒体，只传文本，避免请求体过大。如需历史中的媒体，请用 conversationId 在你侧关联存储。

SlashX 已按智能体的 context_rounds 截断好历史。是否使用由你决定，见多轮上下文指南。

extensions（透传扩展）

一个自由键值对象。智能体配置的「用户可调参数」中，目标为非模型参数的部分会进入这里（如用户选择的标签 tagKey、自定义业务选项）。你可以据此实现差异化逻辑。

PROTOCOLprotocols/response-v1.md

slashx.response.v1

你返回给 SlashX 的格式

slashx.response.v1 字段详解

这是 HTTP 服务商返回给 SlashX 的格式。本文按代码中的协议定义（provider-protocol-v1.ts）逐字段说明。

schemaVersion 固定为 "slashx.response.v1"。

完整示例

一个覆盖所有字段的完整成功响应（含全部可选字段），下面的字段表可逐项对照。真实场景下大部分字段会缺失，这里为演示协议全貌而全放上：

json

{
  "schemaVersion": "slashx.response.v1",
  "runId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "traceId": "9c858901-8a57-4791-81fe-4c455b099bc9",
  "runStatus": "success",
  "progress": 1,
  "messages": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "role": "assistant",
      "status": "success",
      "delta": false,
      "done": true,
      "content": {
        "text": "支持 7 天无理由退货[1]。下面是退货入口：",
        "images": [
          { "url": "https://cdn.example.com/guide.png", "mimeType": "image/png", "fileName": "退货指引.png", "meta": { "width": 800, "height": 600 } }
        ],
        "videos": [
          { "url": "https://cdn.example.com/demo.mp4", "mimeType": "video/mp4", "fileName": "退货演示.mp4" }
        ],
        "audio": [
          { "url": "https://cdn.example.com/tip.mp3", "mimeType": "audio/mpeg", "fileName": "语音提示.mp3" }
        ],
        "attachments": [
          { "url": "https://cdn.example.com/policy.pdf", "mimeType": "application/pdf", "fileName": "退货政策.pdf", "attachmentType": "document" }
        ],
        "citations": [
          { "index": 1, "title": "退货政策", "url": "https://example.com/policy", "snippet": "自签收起 7 日内…", "meta": { "source": "kb" } }
        ],
        "cards": [
          {
            "type": "product",
            "title": "无线降噪耳机",
            "subtitle": "旗舰款 · 现货",
            "imageUrl": "https://cdn.example.com/headphone.png",
            "fields": [
              { "label": "价格", "value": "￥999" },
              { "label": "库存", "value": "充足" }
            ],
            "actions": [
              { "label": "立即购买", "kind": "open_url", "value": "https://example.com/buy/123" }
            ],
            "meta": { "skuId": "123" }
          }
        ],
        "actions": [
          { "label": "申请退货", "kind": "open_url", "value": "https://example.com/refund", "meta": { "track": "refund_btn" } }
        ]
      },
      "meta": {
        "toolName": "order_lookup",
        "modelUsed": "gpt-4o",
        "thinkingDurationMs": 320,
        "finishReason": "stop"
      }
    }
  ],
  "conversationUpdate": { "title": "退货咨询", "modeTag": "after_sales" },
  "usage": {
    "promptTokens": 220,
    "completionTokens": 48,
    "totalTokens": 268,
    "costUsd": 0.0021,
    "modelUsed": "gpt-4o",
    "latencyMs": 1280
  },
  "nextPoll": { "afterMs": 2000, "url": "https://example.com/poll/run-123" },
  "extensions": { "anyCustomKey": "任意自定义数据" }
}

上面把所有字段都列出来了，仅用于展示协议全貌。error 字段未出现在这里——它只在失败响应（runStatus: "error"）中出现，见下方「场景化响应示例 → 业务失败」。

顶层字段

字段	类型	必填	说明	示例 / 取值
`schemaVersion`	string	必填	固定值	`"slashx.response.v1"`（固定）
`runId`	string(uuid)	可选	同步可省略（沿用请求的 runId）	`"f47ac10b-58cc-4372-a567-0e02b2c3d479"`
`traceId`	string(uuid)	可选	追踪 ID	`"9c858901-8a57-4791-81fe-4c455b099bc9"`
`runStatus`	enum	可选	运行状态，默认 `success`	`"pending"` / `"running"` / `"success"` / `"error"` / `"cancelled"`
`progress`	number	可选	进度，范围 0~1	`1`
`messages`	array	可选	助手消息列表，默认 `[]`	见 messages 小节
`conversationUpdate`	object	可选	更新会话标题/模式标签	`{ "title": "退货咨询", "modeTag": "after_sales" }`
`usage`	object	可选	token 用量（按 token 计费必填）	见 usage 小节
`error`	object	可选	错误详情（`runStatus: error` 时填）	见 error 小节
`nextPoll`	object	可选	异步轮询提示（`afterMs` 必填正整数，`url` 可选）	`{ "afterMs": 2000, "url": "https://..." }`
`extensions`	object	可选	扩展字段，默认 `{}`	`{ "anyCustomKey": "任意数据" }`

异步 Operation 响应

当 Operation Contract 声明 taskSupport: "async" 或 "both" 时，服务商可以先返回：

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "running",
  "progress": 0.05,
  "messages": [],
  "nextPoll": {
    "afterMs": 3000,
    "url": "https://provider.example/tasks/task-123"
  },
  "extensions": {
    "externalRunId": "task-123",
    "cancelUrl": "https://provider.example/tasks/task-123"
  }
}

SlashX 的启动请求会在 extensions.slashxAsync 中提供 callbackUrl、高熵 callbackToken、callbackExpiresAt 和可选 idempotencyKey。完成后向 callbackUrl POST 完整的 slashx.response.v1，并通过 X-SlashX-Callback-Token（或 Authorization: Bearer）原样提交 token。数据库只保存 token 摘要；不要把 token 写入日志。

若返回 nextPoll.url，当前 HTTP Provider 要求它与应用 endpoint 同源；SlashX 会按 afterMs 使用原连接鉴权发起 GET。声明支持取消时，cancelUrl 也必须同源，SlashX 使用 DELETE 尽力取消。最终回调和轮询结果都必须返回 success、error 或 cancelled，pending/running 不会被当作成功。

messages（助手消息）

每条消息：

字段	类型	必填	说明	示例 / 取值
`id`	string	必填	消息 ID（建议用请求的 `runId`）	`"f47ac10b-58cc-4372-a567-0e02b2c3d479"`
`role`	enum	可选	消息角色，默认 `assistant`	`"assistant"` / `"thinking"` / `"tool"` / `"system"` / `"error"`
`status`	enum	可选	消息状态，默认 `success`	`"pending"` / `"streaming"` / `"success"` / `"error"` / `"cancelled"`
`delta`	boolean	可选	是否为增量帧，默认 `false`	`true` / `false`
`done`	boolean	可选	是否为最后一帧，默认 `true`	`true` / `false`
`content`	object	必填	消息内容，见下	见 content 小节
`meta`	object	可选	消息元数据，见下	见 meta 小节

content（消息内容）

字段	类型	必填	说明	示例 / 取值
`text`	string	可选	文本，默认空	`"支持 7 天无理由退货"`
`images`	array	可选	图片（元素 `url` 必填）	见 AssistantMedia
`videos`	array	可选	视频，同 AssistantMedia 结构	见 AssistantMedia
`audio`	array	可选	音频，同 AssistantMedia 结构	见 AssistantMedia
`attachments`	array	可选	附件，额外含 `attachmentType`	见 AssistantMedia（+`attachmentType`）
`citations`	array	可选	引用来源，见下	见 citations 小节
`cards`	array	可选	结构化卡片，见下	见 cards 小节
`actions`	array	可选	快捷操作按钮，见下	见 actions 小节

AssistantMedia（助手返回的媒体）

images / videos / audio / attachments 的元素结构：

字段	必填	说明	示例 / 取值
`url`	必填	资源 URL（响应里必填，不能只给 base64）	`"https://cdn.example.com/out.png"`
`mimeType`	可选	MIME 类型，默认 `application/octet-stream`	`"image/png"` / `"video/mp4"` / `"audio/mpeg"`
`fileName`	可选	文件名，默认空	`"结果.png"`
`meta`	可选	附加元数据	`{ "width": 800 }`
`attachmentType`	可选	仅 `attachments` 有，标注附件类型	`"document"` / `"video"` / `"audio"` / `"image"`（也可自定义）

meta（消息元数据）

字段	类型	必填	说明	示例 / 取值
`toolName`	string	可选	工具名（`role: tool` 时用）	`"order_lookup"`
`modelUsed`	string	可选	实际使用的模型	`"gpt-4o"`
`thinkingDurationMs`	number	可选	思考耗时（毫秒，非负整数）	`320`
`finishReason`	string	可选	结束原因	`"stop"` / `"length"` 等

助手返回的媒体里 url 是必填的（请求里的媒体允许 base64，但响应里建议给可访问 URL）。

citations（引用）

字段	类型	必填	说明	示例 / 取值
`index`	number	可选	角标序号（正整数）	`1`
`title`	string	必填	来源标题	`"退货政策"`
`url`	string	可选	来源链接	`"https://example.com/policy"`
`snippet`	string	可选	原文摘录	`"自签收起 7 日内…"`
`meta`	object	可选	附加元数据	`{ "source": "kb" }`

actions（操作按钮）

字段	类型	必填	说明	示例 / 取值
`label`	string	必填	按钮文字	`"申请退货"`
`kind`	enum	必填	按钮类型	`"send_message"` / `"open_url"` / `"copy"` / `"feedback"` / `"custom"`
`value`	string	必填	按钮值（要发送的文本、要打开的 URL 等）	`"https://example.com/refund"`
`meta`	object	可选	附加元数据	`{ "track": "refund_btn" }`

cards（卡片）

字段	类型	必填	说明	示例 / 取值
`type`	string	必填	卡片类型（自由字符串）	`"product"` / `"order"` 等自定义
`title`	string	可选	标题	`"无线降噪耳机"`
`subtitle`	string	可选	副标题	`"旗舰款 · 现货"`
`imageUrl`	string	可选	卡片图	`"https://cdn.example.com/headphone.png"`
`fields`	array	可选	`{ label, value }` 列表	`[{ "label": "价格", "value": "￥999" }]`
`actions`	array	可选	卡片内按钮（结构同上 actions）	见 actions 小节
`meta`	object	可选	附加元数据	`{ "skuId": "123" }`

usage（用量）

字段	类型	必填	说明	示例 / 取值
`promptTokens`	number	可选	输入 token（非负整数）	`220`
`completionTokens`	number	可选	输出 token（按 token 计费时必填，非负整数）	`48`
`totalTokens`	number	可选	总 token（建议返回，非负整数）	`268`
`costUsd`	number	可选	成本（美元，非负）	`0.0021`
`modelUsed`	string	可选	实际使用的模型	`"gpt-4o"`
`latencyMs`	number	可选	耗时（毫秒，非负整数）	`1280`

如果智能体配置了按 token 计费，请务必分别返回 usage.promptTokens（输入）与 usage.completionTokens（输出），SlashX 按输入/输出单价分别精确计费。仅返回 totalTokens 时会按输出单价对全部 token 计费（偏贵）。

error（错误详情）

字段	类型	必填	说明	示例 / 取值
`code`	string	必填	错误码（自定义字符串）	`"ORDER_NOT_FOUND"`
`message`	string	必填	错误信息	`"找不到该订单"`
`userVisible`	boolean	可选	是否展示给用户，默认 `true`	`true` / `false`
`retryable`	boolean	可选	是否可重试，默认 `false`	`true` / `false`

当 runStatus: "error" 或带 error 时，SlashX 会自动退还本次前置扣费。

场景化响应示例

不同业务场景下，建议这样返回。直接照着改即可。

1. 最简纯文本（最常用）

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    { "id": "m-1", "role": "assistant", "content": { "text": "你好，有什么可以帮你？" } }
  ]
}

2. 按 token 计费：带 usage

如果智能体配了按 token 计费，必须分别带 usage.promptTokens 与 usage.completionTokens（分别按输入/输出单价计费）。仅返回 totalTokens 时会按输出单价对全部 token 计费（偏贵）。

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    { "id": "m-1", "role": "assistant", "content": { "text": "已为你查询完成。" } }
  ],
  "usage": { "promptTokens": 120, "completionTokens": 30, "totalTokens": 150, "modelUsed": "gpt-4o" }
}

3. 返回图片

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    {
      "id": "m-1",
      "role": "assistant",
      "content": {
        "text": "这是为你生成的图：",
        "images": [
          { "url": "https://cdn.example.com/out.png", "mimeType": "image/png", "fileName": "结果.png" }
        ]
      }
    }
  ]
}

4. 返回文件附件

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    {
      "id": "m-1",
      "role": "assistant",
      "content": {
        "text": "报表已生成，请下载：",
        "attachments": [
          { "url": "https://cdn.example.com/report.xlsx", "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "fileName": "月度报表.xlsx", "attachmentType": "document" }
        ]
      }
    }
  ]
}

5. 带引用来源（知识库 / RAG 场景）

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    {
      "id": "m-1",
      "role": "assistant",
      "content": {
        "text": "根据公司规定，年假为 10 天[1]，可跨年使用[2]。",
        "citations": [
          { "index": 1, "title": "员工手册 v3", "url": "https://example.com/handbook#leave", "snippet": "全职员工每年享有 10 天带薪年假…" },
          { "index": 2, "title": "年假管理细则", "url": "https://example.com/leave-policy", "snippet": "未休年假可顺延至次年 3 月…" }
        ]
      }
    }
  ]
}

6. 带快捷操作按钮

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    {
      "id": "m-1",
      "role": "assistant",
      "content": {
        "text": "我能帮你处理订单，想做什么？",
        "actions": [
          { "label": "查询物流", "kind": "send_message", "value": "查一下我的物流" },
          { "label": "申请退款", "kind": "open_url", "value": "https://example.com/refund" },
          { "label": "复制订单号", "kind": "copy", "value": "NO20260610001" }
        ]
      }
    }
  ]
}

7. 带结构化卡片（商品 / 订单展示）

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    {
      "id": "m-1",
      "role": "assistant",
      "content": {
        "text": "为你找到这款商品：",
        "cards": [
          {
            "type": "product",
            "title": "无线降噪耳机",
            "subtitle": "旗舰款 · 现货",
            "imageUrl": "https://cdn.example.com/headphone.png",
            "fields": [
              { "label": "价格", "value": "￥999" },
              { "label": "库存", "value": "充足" }
            ],
            "actions": [
              { "label": "立即购买", "kind": "open_url", "value": "https://example.com/buy/123" }
            ]
          }
        ]
      }
    }
  ]
}

8. 业务失败（会触发自动退款）

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "error",
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "找不到该订单，请确认订单号",
    "userVisible": true,
    "retryable": false
  }
}

9. 更新会话标题

首次对话时可顺便给会话设一个标题（展示在用户的会话列表里）。

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    { "id": "m-1", "role": "assistant", "content": { "text": "好的，我们来规划你的三亚行程。" } }
  ],
  "conversationUpdate": { "title": "三亚旅行规划" }
}

容错说明

SlashX 对非标准格式有容错：能从 content.text、或顶层的 output/result/message/text/body 等字段提取文本兜底。所以下面这种最简结构也能识别出文本：

json

{ "text": "直接返回纯文本也行" }

但生产环境强烈建议严格用上面的 slashx.response.v1 结构，否则无法使用多媒体、引用、卡片、按 token 计费（需 usage）等能力。

PROTOCOLprotocols/streaming.md

流式响应与 SSE

上下行两套 SSE 与同步降级逻辑

流式响应与 SSE 实现逻辑

本文讲清楚 SlashX 的流式（打字机效果）是怎么实现的：上下行各有一套 SSE 协议，以及 SlashX 内部如何在它们之间转译。

读懂这篇，你就能理解从「用户发消息」到「文字一个个蹦出来」中间发生了什么。

两套 SSE，别搞混

流式涉及两个方向的 SSE，事件名相近但用途不同：

① 上行 SSE（你 → SlashX）：只有 HTTP 服务商需要关心。你的服务返回 text/event-stream 时，按这套格式输出。
② 下行 SSE（SlashX → 前端）：SlashX 内部协议，前端据此渲染。你不直接产生它，但理解它有助于排查。

SlashX 后端的工作就是把 ① 解析、转译成 ②。

一、下行 SSE（SlashX → 前端）

这是 SlashX 统一对前端输出的事件，四种服务商最终都转成这套。

event	data	说明
`start`	`{ runId, model? }`	流开始，带本次运行 ID
`delta`	`{ text }`	文本增量，前端累加显示
`usage`	`{ promptTokens?, completionTokens?, totalTokens? }`	token 用量（可选，AI 路径有）
`done`	`{ finishReason?, assistantMessageId? }`	流正常结束
`error`	`{ code, message }`	出错，前端展示错误
`async`	`{ runId, nextPollAt?, message? }`	转入异步轮询（`[规划中]`，见末尾）

帧格式（标准 SSE）：每帧 event: 行 + data:（JSON）行，以两个换行结尾：

css

event: delta
data: {"text":"你好"}

前端的处理（见 sse-client.ts）：start 标记开始，delta 往气泡里追加文字，done 收尾并替换为真实消息 ID，error 显示错误并按 code（如 BILLING_INSUFFICIENT）做相应处理。

二、上行 SSE（HTTP 服务商 → SlashX）

只有 HTTP 服务商需要实现这套。你的服务返回 Content-Type: text/event-stream 时，SlashX 按下面的规则解析。

你发的 event	SlashX 读取的 data	SlashX 的动作
`message` / `delta`	`{ "messages": [{ "content": { "text": "片段" } }] }`	取出 `text`，累加，并向前端转发一帧 `delta`
`done`	`{ "finishReason": "stop" }`	结束：落库助手消息、结算、向前端发 `done`
`error`	`{ "error": { "code": "...", "message": "..." } }`	退款、向前端发 `error`、标记失败

一段完整的上行流示例：

css

event: delta
data: {"messages":[{"content":{"text":"好的，"}}]}

event: delta
data: {"messages":[{"content":{"text":"请提供订单号。"}}]}

event: done
data: {"finishReason":"stop"}

三条必须遵守的规则

结束必须发 event: done。SlashX 只认 done 作为结束信号，不会因为你关闭连接就自动收尾。
不要用 runStatus 判断结束。中间 delta 帧即使带了 runStatus: "success" 也不会触发结束，只有 event: done 才结束。
每帧以两个换行 \n\n 结尾，data 必须是合法 JSON。

异常断流的兜底

如果你的服务异常断开、既没发 done 也没发 error，SlashX 会兜底处理：

已经收到过文字 → 按成功保存已有内容，向前端补发 done
完全没收到内容 → 按错误处理，退款，向前端发 error（code UPSTREAM_CLOSED）

这是保护机制，但不要依赖它，请始终显式发 done。

三、同步降级（你返回 JSON 而非 SSE）

如果你的服务返回 Content-Type: application/json（而非 text/event-stream），SlashX 走「同步降级」：

读取完整 JSON，按 slashx.response.v1 归一化
判定成败：runStatus: "error" 或带 error → 退款 + 向前端发 error；否则继续
成功时：把全部文本一次性作为一帧 delta 推给前端，再发 done
落库时保留完整结构（媒体、引用、卡片、actions），历史回放时还原

所以即使你只能返回 JSON，用户侧仍然走的是同一套下行 SSE，只是没有「逐字蹦出」的效果而已。

四、AI 大模型 / OpenClaw 的流式

这两类你不用写代码。SlashX 直接以流式方式调用上游（OpenAI 兼容协议），把上游返回的 token 实时转成下行 delta，并在结束时发 usage + done。多轮上下文的差异见多轮上下文指南。

五、取消

用户中途取消时，前端 abort 掉 fetch。SlashX 后端通过请求的中断信号感知，把本次运行标记为 cancelled 并退还前置扣费。你的 HTTP 服务可通过请求的连接断开来感知取消（SlashX 会断开对你的请求）。

六、异步长任务

小斜杠的多应用复杂任务已使用 Durable Agent Task：规划完成后下行 queued 事件，前端轮询 /api/superslash/tasks/:taskId，可获得步骤状态、审批、进度、Artifact 和最终摘要。浏览器断线不会取消任务；用户必须显式调用任务取消接口。

应用级异步执行使用 slashx.response.v1 的 runStatus=running/pending、nextPoll 和 callback。详见 Response v1 的异步 Operation。普通单应用聊天的旧 async SSE 事件仍保留兼容，但新的复杂任务不要依赖长连接等待服务商完成。

速查：上行 vs 下行事件

	方向	`delta` 的 data	结束事件	谁实现
上行	你 → SlashX	`{ messages: [{ content: { text } }] }`	`done`	HTTP 服务商
下行	SlashX → 前端	`{ text }`	`done`	SlashX（你无需关心）

最容易踩的坑：上行 delta 的文本在 messages[].content.text 里，不是顶层 text。可直接参考 Node.js 流式示例。

GUIDESguides/multiround-context.md

多轮上下文策略

四种服务商如何处理历史

多轮上下文策略

本文解释四种服务商如何处理对话历史，以及 context_rounds 参数的作用。

背景：为什么多轮上下文需要策略

大多数 AI 对话需要「记得之前说过什么」。但历史越多，请求体越大，token 消耗越高，也可能超出模型的上下文窗口。所以需要按配置截断。

四种服务商的策略不同：

AI 大模型：SlashX 维护历史，按轮截断后发给模型

SlashX 在每次请求时从数据库读取该会话的历史，按 context_rounds 截断，拼成 messages 数组发给大模型：

csharp

[system]    智能体系统提示词
[user]      第 3 轮用户消息
[assistant] 第 3 轮助手回复
[user]      第 4 轮用户消息（当前消息）

context_rounds 规则：

值	行为
不设置（留空）	不限制，传全部历史
`0`	不带任何历史，每次都是全新对话
`N`（正整数）	只带最近 N 轮（= N × 2 条消息，从最新往前取）

这个参数可以开放给终端用户自己调节，见 AI 大模型服务商。

HTTP 服务商：SlashX 把历史传给你，你决定怎么用

SlashX 把截断后的历史放在 slashx.request.v1 的 history 字段里传给你：

json

{
  "history": [
    { "role": "user",      "content": { "text": "上上句用户说的" } },
    { "role": "assistant", "content": { "text": "上上句助手回的" } },
    { "role": "user",      "content": { "text": "上一句用户说的" } },
    { "role": "assistant", "content": { "text": "上一句助手回的" } }
  ]
}

你有两种选择：

选择 A（推荐）：用 history 自己拼 prompt

const messages = [
  { role: 'system', content: '你是一个客服助手' },
  ...request.history.map(h => ({ role: h.role, content: h.content.text })),
  { role: 'user', content: request.input.text },
]
// 把 messages 发给你自己调用的大模型

选择 B：忽略 history，自己维护状态

如果你的服务有自己的会话存储，可以直接用 conversationId 作为 key，完全不依赖 SlashX 传来的 history。

注意：history 里只有文本，不含图片等多媒体。如需历史媒体，请在你侧以 conversationId 关联存储。

OpenClaw：历史完全由 OpenClaw 服务端维护

SlashX 不传 history 给 OpenClaw，只发当前这一句。SlashX 通过请求头标识会话：

less

x-openclaw-session-key: slashx:<conversationId>
x-openclaw-message-channel: slashx

OpenClaw 服务端据此维护该会话的历史，不需要 SlashX 这边管。

为什么不传？ 如果 SlashX 也传 history，两边各记一份，回复里会出现重复内容、token 翻倍、语义漂移等问题。

设计约束：想清空上下文必须开新会话（新 conversationId）。在旧会话上继续发消息，OpenClaw 仍记着之前的历史。

Make AI Agents：SlashX 传截断历史，也可续用 Make thread

SlashX 将最近 context_rounds × 2 条用户/助手消息转换为 Make messages，再追加当前用户消息。context_rounds=0 时不带历史；留空时不在 SlashX 侧限制。

同时，SlashX 会把 context_rounds 映射为 Make 的 config.historyConfig.iterationsFromHistoryCount。如果请求中有 threadId，还会传给 Make 继续对应线程。因此实际记忆范围也受 Make Agent 配置和 thread 状态影响。

一张表对比

	AI 大模型	HTTP 服务商	OpenClaw	Make AI Agents
历史存哪	SlashX 数据库	SlashX 数据库	OpenClaw 服务端	SlashX 数据库 + 可选 Make thread
谁拼进请求	SlashX	你（用 `history` 字段）	OpenClaw	SlashX 转换为 Make messages
截断控制	`context_rounds`	`context_rounds`（已替你截好）	OpenClaw 侧自定	`context_rounds` + Make 配置
清空上下文	设 `context_rounds=0` 或开新会话	你自行控制	开新会话	设 0 且不续用旧 thread，或开新会话

GUIDESguides/billing.md

计费模式与退款

按次 / 按 token 与退款触发条件

计费模式与退款

本文讲清楚 SlashX 如何对一次对话计费，以及哪些情况会退款。计费规则由平台/开发者在后台配置，本文帮你理解机制，以便正确返回 usage。

计费规则类型

SlashX 当前支持以下计费规则（在后台「定价规则」里配置）：

规则类型	含义	扣费时机
`flat_per_run`	按次计费，每次对话固定积分	请求前（before）
`pass_through`	按 token 透传计费，按实际用量算	成功后（after）
`free_quota_daily`	每日免费额度	仅校验额度（free-only）
`free_quota_monthly`	每月免费额度	仅校验额度（free-only）

两种扣费时机

请求前扣费（flat_per_run）

对话开始之前就扣费。如果余额不足，直接返回 BILLING_INSUFFICIENT，不会请求你的服务。

如果对话后续失败（你返回错误、网络异常等），SlashX 会自动把这笔费退回。

成功后扣费（pass_through）

对话成功完成后，按实际 token 用量结算。输入 token 与输出 token 分别按各自单价计费（输出通常更贵，符合业界惯例）。

⚠️ 这种模式下，你必须在响应里分别返回 usage.promptTokens（输入）与 usage.completionTokens（输出），SlashX 据此分别按输入/输出单价精确计费。
json
{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [ /* ... */ ],
  "usage": { "promptTokens": 120, "completionTokens": 30, "totalTokens": 150 }
}
若只返回 totalTokens、缺少输入/输出拆分，SlashX 会按输出单价对全部 token 计费（偏贵），以保护开发者收入。请务必返回拆分字段以获得准确计费。

退款触发条件

只有「请求前扣费」的费用才需要退款。以下情况 SlashX 会自动退还：

你返回了业务错误（runStatus: "error" 或带 error 对象）
连不上你的服务（NETWORK_ERROR）
你返回了非 2xx 状态码（HTTP_4xx / HTTP_5xx）
响应无法解析（PARSE_ERROR）
流式时你没发任何内容就关了连接（UPSTREAM_CLOSED）
用户参数校验失败（USER_PARAM_INVALID）

退款是自动的，你不需要做任何处理。

计费走向（了解即可）

SlashX 会根据「当前工作区类型」和「智能体归属」决定这笔费用从哪个账户体系出（平台 / 开发者 / 企业等）。这是平台内部的账务路由，对你的服务端对接没有影响，你只需正确返回 usage 即可。

给开发者的实践建议

如果你的服务调用了大模型，把大模型返回的 token 用量原样填进 usage，让按 token 计费准确。
如果你的服务是固定逻辑（不调模型），用按次计费（flat_per_run）更合适，可以不返回 usage。
业务失败时务必返回 runStatus: "error"，这样用户会被自动退款，避免投诉。

GUIDESguides/security.md

安全与访问控制

SSRF 防护、签名验签、超时限额

安全与访问控制

本文说明 SlashX 对外部请求的安全防护，以及私有化部署时的注意事项。

SSRF 防护（已生效）

为防止恶意配置把 SlashX 当跳板去访问内网，SlashX 在向你的 HTTP 端点发请求前，会校验目标 URL。

默认拦截的地址（除非显式放行）：

私有网段：10.0.0.0/8、172.16.0.0/12、192.168.0.0/16
回环：127.0.0.0/8、::1
链路本地：169.254.0.0/16
未指定/当前网络：0.0.0.0/8
云元数据地址：169.254.169.254、fd00:ec2::254、metadata.google.internal

只允许 http / https 协议，其他协议（如 file://、gopher://）一律拒绝。

两道校验：

保存连接时：校验协议 + 字面量 IP + 明显内网域名，让你尽早看到配置错误。
运行时：发请求前再校验一次，并对域名做 DNS 解析后逐个 IP 复核，缓解 DNS rebinding 攻击。

如果你的端点被拦截，会返回错误码 PROVIDER_URL_FORBIDDEN。

私有化部署：放行内网地址

如果你把 SlashX 部署在自己的环境里，服务商端点本身就在内网（如 http://10.0.0.5:8080），需要放行内网访问。

总开关（环境变量）：

bash

# 默认 false（严格拦截）。设为 true 放行内网/保留地址。
SLASHX_ALLOW_PRIVATE_NETWORK=true

或在管理后台「网络安全」配置（优先级高于环境变量）：

总开关：是否放行内网/保留地址
白名单：即使总开关关闭，命中白名单的地址也放行。支持三种条目：
- IPv4 CIDR：如 10.0.0.0/8
- IP 字面量：如 192.168.1.10
- 域名/域名后缀：如 internal.corp、.local

注意：云元数据地址（169.254.169.254 等）即使开了总开关也默认拦死，必须显式加入白名单才放行。这是为了防止云环境凭据泄露。

策略优先级：后台「网络安全」配置 > 环境变量 SLASHX_ALLOW_PRIVATE_NETWORK > 默认（最严格）。

鉴权（已生效）

你的 HTTP 服务可以要求 SlashX 携带凭据：

鉴权方式（auth_type）：bearer（带 Authorization: Bearer <密钥>）/ custom_header（密钥按 Header-Name: value 拆成一个鉴权头）/ none。
附加自定义头（custom_headers）：独立的键值表，无论哪种鉴权方式都会原样带上。

在你的服务端校验这些凭据，拒绝非法请求。

注意：流式处理路径目前只实现了 bearer 鉴权方式，custom_header 仅在同步路径生效；custom_headers 附加头两条路径都带。详见 HTTP 服务商 → 鉴权配置。

请求超时

两条处理路径都已生效，统一用连接的 timeout_ms（默认 60 秒，可在后台配置）：

同步处理路径（你返回 JSON）：从发起请求到收到完整响应超过 timeout_ms 即中断，按 PROVIDER_TIMEOUT 错误处理 + 退款。
流式处理路径（你返回 SSE）：建连阶段（请求发出到首个响应到达）超过 timeout_ms 中断；进入 SSE 流后，若两帧之间超过 timeout_ms 没有新数据，视为上游卡死，按 PROVIDER_TIMEOUT 中断 + 退款。用户主动取消也会立即中断。

出站签名（已上线）

为了让你能确认请求确实来自 SlashX（而非伪造），在连接里配置「签名密钥（Webhook Secret）」后，SlashX 会为每个出站请求加上以下头：

X-SlashX-Signature：sha256=<hex>，其中 hex = HMAC-SHA256(secret, timestamp + "." + body)
X-SlashX-Timestamp：Unix 秒级时间戳（防重放）
X-SlashX-Version：协议主版本号（当前为 1），无论是否配置签名密钥都会下发

secret 是你在连接配置里设置的签名密钥，body 是请求体原文（即你收到的 HTTP body 字符串）。

验签步骤（建议）：

读取 X-SlashX-Timestamp，校验与当前时间偏差在容忍窗口内（建议 ±5 分钟），超出则拒绝，防重放。
用你保存的同一份密钥，按 ${timestamp}.${rawBody} 计算 HMAC-SHA256 的 hex。
用恒定时间比较（如 crypto.timingSafeEqual）对比 X-SlashX-Signature 去掉 sha256= 前缀后的 hex。

未配置签名密钥时不会下发签名头（保持向后兼容），此时请继续用 Bearer / 自定义 Header 鉴权。

响应体积上限（已上线）

为防止超大响应拖垮平台，SlashX 读取你的响应时设有最大字节上限（默认 4MB），同步与流式两条路径都生效：

若响应声明的 Content-Length 已超限，直接拒绝。
否则边读边累计字节数，超过上限立即中断，按 PROVIDER_RESPONSE_TOO_LARGE 错误处理 + 退款。

请把大文件（图片、附件等）以 URL 形式返回，不要内联到响应体里。

其他规划中的防护

以下仍为 [规划中]，列出以便你提前了解：

异步回调：长任务先返回受理，再通过回调通知结果

GUIDESguides/debugging.md

调试与错误排查

错误码对照、日志位置、自测流程

调试与错误排查

本文帮你在对接出问题时快速定位。

在哪看日志

SlashX 把每次对话往返都记在 ChatRun（对话运行记录） 里。在管理后台进入对应智能体的对话记录，可以看到：

字段	含义
`requestPayload`	SlashX 发给你的完整请求（slashx.request.v1）
`responsePayload`	你返回的原始响应
`status`	`success` / `error` / `cancelled` 等
`errorCode`	失败时的错误码
`errorMessage`	失败时的错误详情
`traceId` / `runId`	与请求头 `x-slashx-trace-id` / `x-slashx-run-id` 对应，便于和你侧日志对照

排障第一步：拿到这次对话的 runId，在你的服务端日志里搜对应请求，两边对照。

错误码对照表

这些是 SlashX 侧可能产生的错误码（你的服务正常时不会看到大部分）：

错误码	含义	怎么处理
`BILLING_INSUFFICIENT`	用户余额不足，未请求你的服务	提示用户充值；与你无关
`USER_PARAM_INVALID`	用户填的参数没通过校验	检查智能体的用户参数配置
`PROVIDER_URL_FORBIDDEN`	你的端点 URL 被 SSRF 防护拦截	见安全指南，内网地址需放行
`NETWORK_ERROR`	SlashX 连不上你的服务	检查服务是否在线、端点 URL 是否正确、防火墙
`HTTP_4xx` / `HTTP_5xx`	你的服务返回了非 2xx 状态码	看你服务端日志
`PARSE_ERROR`	你返回的 JSON 无法解析	检查响应是否为合法 JSON
`NO_BODY`	你的流式响应没有 body	检查 SSE 是否正确开启
`UPSTREAM_CLOSED`	流式时你没发任何内容就关了连接	确保发了 `event: done`，且至少有一帧 delta
`STREAM_PARSE_ERROR`	解析你的 SSE 流时出错	检查 SSE 帧格式（`event:` / `data:` / `\n\n`）
`EMPTY_ASSISTANT_RESPONSE`	上游返回了空内容	检查你的回复是否真的有文本
`PROVIDER_CALL_FAILED`	调用服务商整体失败	综合看 errorMessage
`STREAM_NOT_SUPPORTED`	该服务商类型不支持流式（前端会自动降级到同步）	通常无需处理

常见问题排查

用户看到空白气泡 / 没有回复

流式：检查是否发了 event: done。只发 delta 不发 done，会触发兜底逻辑。
同步：检查响应是不是合法 JSON，messages[].content.text 是否有值。

流式回复中途断了

检查你是不是在中间帧误发了 event: done（一旦发 done，SlashX 就认为结束了）。
确认 SSE 帧之间是两个换行 \n\n 分隔。

返回了图片/卡片但前端没显示

检查响应格式是否严格符合 slashx.response.v1（容错模式只能提取纯文本，多媒体必须用标准结构）。
图片的 url 必须可被前端访问。
字段结构见 response-v1 详解。

按 token 计费金额不对 / 没扣费

确认响应里分别带了 usage.promptTokens 与 usage.completionTokens。缺输入/输出拆分时会按输出单价对全部 token 计费（偏贵）。

端点保存时报「URL 被拒绝」

这是 SSRF 防护。如果端点在内网（私有化部署），见安全指南放行内网地址。

自测建议

先用 curl 直接打你的端点，确认它能正确解析 slashx.request.v1 并返回合法响应：

bash

curl -X POST https://你的域名/ \
  -H 'content-type: application/json' \
  -d '{
    "schemaVersion": "slashx.request.v1",
    "event": "user_message",
    "runId": "00000000-0000-4000-8000-000000000000",
    "conversationId": "00000000-0000-4000-8000-000000000001",
    "input": { "text": "你好" },
    "history": [],
    "extensions": {}
  }'

确认返回的是合法 slashx.response.v1（或至少含 text 的 JSON）。
再到 SlashX 后台绑定智能体，发消息端到端验证。

EXAMPLESexamples/http-echo-bot.js

Node.js 回显 Bot

同步返回，零依赖

/* eslint-disable @typescript-eslint/no-require-imports -- CommonJS copy-paste example for Node.js users */
/**
 * SlashX HTTP 服务商示例：同步回显 Bot（Node.js，零依赖）
 * ---------------------------------------------------------
 * 用户发什么，它就回 “你说的是：xxx”。
 * 演示如何解析 slashx.request.v1、返回 slashx.response.v1。
 *
 * 运行：node http-echo-bot.js
 * 然后在 SlashX 后台把 HTTP 服务商端点指向 http://你的地址:8080/
 */
const http = require('node:http')

const PORT = process.env.PORT || 8080
// 如果你在 SlashX 后台配置了 Bearer 鉴权，把密钥填到这里做校验（留空表示不校验）
const EXPECTED_TOKEN = process.env.SLASHX_BOT_TOKEN || ''

const server = http.createServer((req, res) => {
  if (req.method !== 'POST') {
    res.writeHead(405)
    return res.end('Only POST is supported')
  }

  // 可选：校验 SlashX 带来的 Bearer Token
  if (EXPECTED_TOKEN) {
    const auth = req.headers['authorization'] || ''
    if (auth !== `Bearer ${EXPECTED_TOKEN}`) {
      res.writeHead(401, { 'content-type': 'application/json' })
      return res.end(JSON.stringify({
        schemaVersion: 'slashx.response.v1',
        runStatus: 'error',
        error: { code: 'UNAUTHORIZED', message: '鉴权失败' },
      }))
    }
  }

  let raw = ''
  req.on('data', (chunk) => (raw += chunk))
  req.on('end', () => {
    let request
    try {
      request = JSON.parse(raw)
    } catch {
      res.writeHead(400, { 'content-type': 'application/json' })
      return res.end(JSON.stringify({
        schemaVersion: 'slashx.response.v1',
        runStatus: 'error',
        error: { code: 'BAD_REQUEST', message: '请求体不是合法 JSON' },
      }))
    }

    // 从 slashx.request.v1 取用户文本
    const userText = request.input?.text ?? ''

    // —— 你的业务逻辑放这里 ——
    const replyText = `你说的是：${userText}`

    // 按 slashx.response.v1 返回
    const response = {
      schemaVersion: 'slashx.response.v1',
      runStatus: 'success',
      messages: [
        {
          id: request.runId || 'm-1',
          role: 'assistant',
          status: 'success',
          content: { text: replyText },
        },
      ],
    }

    res.writeHead(200, { 'content-type': 'application/json' })
    res.end(JSON.stringify(response))
  })
})

server.listen(PORT, () => {
  console.log(`SlashX echo bot 运行在 http://localhost:${PORT}`)
})

EXAMPLESexamples/http-echo-bot.py

Python 回显 Bot

同步返回，标准库零依赖

python

"""
SlashX HTTP 服务商示例：同步回显 Bot（Python 标准库，零依赖）
-----------------------------------------------------------
用户发什么，它就回 “你说的是：xxx”。
演示如何解析 slashx.request.v1、返回 slashx.response.v1。

运行：python http_echo_bot.py
然后在 SlashX 后台把 HTTP 服务商端点指向 http://你的地址:8080/
"""
import json
import os
from http.server import BaseHTTPRequestHandler, HTTPServer

PORT = int(os.environ.get("PORT", "8080"))
# 如果你在 SlashX 后台配置了 Bearer 鉴权，把密钥填到这里做校验（留空表示不校验）
EXPECTED_TOKEN = os.environ.get("SLASHX_BOT_TOKEN", "")


class Handler(BaseHTTPRequestHandler):
    def _send_json(self, status, payload):
        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
        self.send_response(status)
        self.send_header("Content-Type", "application/json; charset=utf-8")
        self.send_header("Content-Length", str(len(body)))
        self.end_headers()
        self.wfile.write(body)

    def do_POST(self):
        # 可选：校验 Bearer Token
        if EXPECTED_TOKEN:
            auth = self.headers.get("Authorization", "")
            if auth != f"Bearer {EXPECTED_TOKEN}":
                return self._send_json(401, {
                    "schemaVersion": "slashx.response.v1",
                    "runStatus": "error",
                    "error": {"code": "UNAUTHORIZED", "message": "鉴权失败"},
                })

        length = int(self.headers.get("Content-Length", "0"))
        raw = self.rfile.read(length)
        try:
            request = json.loads(raw)
        except json.JSONDecodeError:
            return self._send_json(400, {
                "schemaVersion": "slashx.response.v1",
                "runStatus": "error",
                "error": {"code": "BAD_REQUEST", "message": "请求体不是合法 JSON"},
            })

        # 从 slashx.request.v1 取用户文本
        user_text = (request.get("input") or {}).get("text", "")

        # —— 你的业务逻辑放这里 ——
        reply_text = f"你说的是：{user_text}"

        # 按 slashx.response.v1 返回
        self._send_json(200, {
            "schemaVersion": "slashx.response.v1",
            "runStatus": "success",
            "messages": [
                {
                    "id": request.get("runId", "m-1"),
                    "role": "assistant",
                    "status": "success",
                    "content": {"text": reply_text},
                }
            ],
        })

    # 关掉默认日志噪音（可选）
    def log_message(self, *args):
        pass


if __name__ == "__main__":
    print(f"SlashX echo bot 运行在 http://localhost:{PORT}")
    HTTPServer(("0.0.0.0", PORT), Handler).serve_forever()

EXAMPLESexamples/http-streaming-bot.js

Node.js 流式 SSE Bot

打字机效果，SSE 帧格式示范

/* eslint-disable @typescript-eslint/no-require-imports -- CommonJS copy-paste example for Node.js users */
/**
 * SlashX HTTP 服务商示例：流式 SSE Bot（Node.js，零依赖）
 * ---------------------------------------------------------
 * 把回复一个字一个字地流式输出，实现打字机效果。
 * 演示 slashx 的 SSE 帧格式：event: delta / event: done。
 *
 * 运行：node http-streaming-bot.js
 * 关键点：
 *   1. 响应头必须 Content-Type: text/event-stream
 *   2. 每个 delta 帧的 data 结构是 { messages: [{ content: { text: "片段" } }] }
 *   3. 最后必须发 event: done，不能只关连接
 *   4. 每帧以两个换行 \n\n 结尾
 */
const http = require('node:http')

const PORT = process.env.PORT || 8080

function sseFrame(event, data) {
  return `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`
}

const server = http.createServer((req, res) => {
  if (req.method !== 'POST') {
    res.writeHead(405)
    return res.end('Only POST is supported')
  }

  let raw = ''
  req.on('data', (chunk) => (raw += chunk))
  req.on('end', async () => {
    let request = {}
    try {
      request = JSON.parse(raw)
    } catch {
      /* 忽略，按空输入处理 */
    }
    const userText = request.input?.text ?? ''
    const replyText = `你说的是：${userText}`

    // 开启 SSE
    res.writeHead(200, {
      'content-type': 'text/event-stream',
      'cache-control': 'no-cache',
      connection: 'keep-alive',
    })

    // 逐字符流式输出（真实场景下这里换成大模型的流式 token）
    for (const ch of replyText) {
      res.write(sseFrame('delta', { messages: [{ content: { text: ch } }] }))
      await new Promise((r) => setTimeout(r, 40)) // 模拟生成延迟
    }

    // 必须显式发 done
    res.write(sseFrame('done', { finishReason: 'stop' }))
    res.end()
  })
})

server.listen(PORT, () => {
  console.log(`SlashX streaming bot 运行在 http://localhost:${PORT}`)
})

EXAMPLESexamples/curl-examples.sh

curl 自测命令

本地模拟 SlashX 发请求

bash

#!/usr/bin/env bash
#
# SlashX HTTP 服务商：curl 自测示例
# -----------------------------------------------------------
# 这些命令模拟 SlashX 向你的服务发请求，用来在本地验证你的服务端
# 能否正确解析 slashx.request.v1 并返回合法响应。
#
# 用法：把 ENDPOINT 改成你的服务地址，按需取消注释逐条运行。
#   bash curl-examples.sh
# 或直接复制单条命令到终端执行。

set -euo pipefail

ENDPOINT="${ENDPOINT:-http://localhost:8080/}"
# 如果你的服务配了 Bearer 鉴权，把密钥填这里（留空表示不带鉴权头）
TOKEN="${SLASHX_BOT_TOKEN:-}"

AUTH_HEADER=()
if [ -n "$TOKEN" ]; then
  AUTH_HEADER=(-H "Authorization: Bearer ${TOKEN}")
fi

echo "==> 1. 最简单的一条用户消息"
curl -sS -X POST "$ENDPOINT" \
  -H 'content-type: application/json' \
  "${AUTH_HEADER[@]}" \
  -H 'x-slashx-trace-id: 9c858901-8a57-4791-81fe-4c455b099bc9' \
  -H 'x-slashx-run-id: f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  -d '{
    "schemaVersion": "slashx.request.v1",
    "event": "user_message",
    "runId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "traceId": "9c858901-8a57-4791-81fe-4c455b099bc9",
    "conversationId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "userId": "user_abc123",
    "agent": { "id": "agent_xyz", "name": "客服助手" },
    "client": { "platform": "pc-web", "capabilities": ["stream", "markdown"], "locale": "zh-CN" },
    "input": { "text": "你好" },
    "history": [],
    "extensions": {}
  }'
echo -e "\n"

echo "==> 2. 带多轮历史的请求（验证你是否正确拼接上下文）"
curl -sS -X POST "$ENDPOINT" \
  -H 'content-type: application/json' \
  "${AUTH_HEADER[@]}" \
  -d '{
    "schemaVersion": "slashx.request.v1",
    "event": "user_message",
    "runId": "f47ac10b-58cc-4372-a567-0e02b2c3d480",
    "traceId": "9c858901-8a57-4791-81fe-4c455b099bca",
    "conversationId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "userId": "user_abc123",
    "agent": { "id": "agent_xyz", "name": "客服助手" },
    "client": { "platform": "pc-web", "capabilities": ["stream", "markdown"], "locale": "zh-CN" },
    "input": { "text": "那它支持退货吗？" },
    "history": [
      { "role": "user", "content": { "text": "这个商品多少钱？" } },
      { "role": "assistant", "content": { "text": "这个商品是 199 元。" } }
    ],
    "extensions": {}
  }'
echo -e "\n"

echo "==> 3. 带用户自定义参数（extensions 透传）"
curl -sS -X POST "$ENDPOINT" \
  -H 'content-type: application/json' \
  "${AUTH_HEADER[@]}" \
  -d '{
    "schemaVersion": "slashx.request.v1",
    "event": "user_message",
    "runId": "f47ac10b-58cc-4372-a567-0e02b2c3d481",
    "traceId": "9c858901-8a57-4791-81fe-4c455b099bcb",
    "conversationId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "userId": "user_abc123",
    "agent": { "id": "agent_xyz", "name": "客服助手" },
    "client": { "platform": "pc-web", "capabilities": ["stream", "markdown"], "locale": "zh-CN" },
    "input": { "text": "帮我推荐" },
    "history": [],
    "extensions": { "tagKey": "vip", "style": "concise" }
  }'
echo -e "\n"

echo "==> 4. 观察 SSE 流式输出（你的服务返回 text/event-stream 时）"
echo "    用 -N 关闭缓冲，能看到逐帧到达："
curl -sS -N -X POST "$ENDPOINT" \
  -H 'content-type: application/json' \
  "${AUTH_HEADER[@]}" \
  -d '{
    "schemaVersion": "slashx.request.v1",
    "event": "user_message",
    "runId": "f47ac10b-58cc-4372-a567-0e02b2c3d482",
    "traceId": "9c858901-8a57-4791-81fe-4c455b099bcc",
    "conversationId": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
    "userId": "user_abc123",
    "agent": { "id": "agent_xyz", "name": "客服助手" },
    "client": { "platform": "pc-web", "capabilities": ["stream", "markdown"], "locale": "zh-CN" },
    "input": { "text": "讲个一句话笑话" },
    "history": [],
    "extensions": {}
  }'
echo -e "\n"

echo "全部完成。如果某条返回的不是合法 slashx.response.v1，请对照 ../protocols/response-v1.md 检查。"

FAQFAQ.md

常见问题 FAQ

高频疑问一站式解答

常见问题 FAQ

Q：我该选哪种服务商？

有自己的业务逻辑服务器（查库、调工具、自定义流程）→ HTTP 服务商
只想直接调大模型 API → AI 大模型
用 OpenClaw 网关托管的模型/Agent → OpenClaw
已有 Make AI Agent，希望直接调用 Make 执行 → Make AI Agents

Q：HTTP 服务商，流式输出什么时候算结束？

必须收到你发的 event: done。不要只关闭连接。只发 delta 不发 done 会触发兜底逻辑（有文本按成功、空响应按 UPSTREAM_CLOSED 错误退款）。

Q：为什么我在中间帧带了 runStatus: success，回复却被截断了？

这是早期的一个 bug，现已修复：SlashX 只认 event: done 作为结束信号，中间 delta 帧带 runStatus 不会再导致截断。请确保你用 event: done 标记结束。

Q：为什么 OpenClaw 不传历史？

OpenClaw 服务端自己维护多轮记忆。如果 SlashX 再传一份，会变成两边各记一份，导致内容重复、token 翻倍、回答漂移。所以 SlashX 只发当前消息，通过 x-openclaw-session-key 让 OpenClaw 接上下文。详见多轮上下文指南。

Q：context_rounds=0 到底是带历史还是不带？

不带任何历史。早期版本存在「设 0 反而带全量历史」的 bug，现已修复：0 = 无历史，留空 = 不限制（全量）。

Q：我返回了图片，前端看不到？

检查响应是否严格符合 slashx.response.v1，图片要放在 messages[].content.images[]，每个元素的 url 必填且可访问。容错模式只能提取纯文本，多媒体必须用标准结构。见 response-v1 详解。

Q：按 token 计费，为什么没扣费/金额不对？

按 token 计费（pass_through）需要你在响应里分别返回 usage.promptTokens（输入）与 usage.completionTokens（输出），SlashX 按输入/输出单价分别计费。仅返回 totalTokens 会按输出单价对全部 token 计费（偏贵）。

Q：对话失败了，用户会被扣费吗？

不会。「请求前扣费」的费用在对话失败（你返回错误、网络异常、解析失败等）时会自动退还。详见计费指南。

Q：我的服务在内网，保存端点时报 URL 被拒绝？

这是 SSRF 防护。私有化部署可通过环境变量 SLASHX_ALLOW_PRIVATE_NETWORK=true 或后台「网络安全」配置放行内网地址。见安全指南。

Q：怎么确认请求确实来自 SlashX？

在连接里配置「签名密钥（Webhook Secret）」后，SlashX 会为每个出站请求加 X-SlashX-Signature（HMAC-SHA256）、X-SlashX-Timestamp、X-SlashX-Version 头，你按密钥验签即可。验签步骤见安全指南。也可继续用 Bearer Token 或自定义 Header 鉴权。

Q：怎么排查一次具体的对话出了什么问题？

在管理后台找到这次对话的 ChatRun 记录，拿 runId / traceId，和你服务端日志对照。看 errorCode / errorMessage 定位。错误码含义见调试指南。

Q：协议会变吗？我要兼容未来版本吗？

当前协议是 slashx.request.v1 / slashx.response.v1。新增可选字段属于兼容性变更，不影响你。建议你的服务对未知字段、未知 event 类型做忽略处理，提升前向兼容性。破坏性变更会通过新版本号发布，并提供迁移说明。

Q：history 里为什么没有图片？

为避免请求体过大，历史里只传文本。如需历史中的媒体，请在你侧用 conversationId 关联存储。

Q：系统提示词（system prompt）由谁控制？

AI 大模型：SlashX 把智能体配置的提示词注入到 messages 最前面。
HTTP 服务商 / OpenClaw：提示词在你的服务端，SlashX 不注入。
Make AI Agents：SlashX 通过 Make 的运行配置传入智能体系统提示词和可选追加提示词。

准备好了吗

你的AI应用/智能体，离收费交付只差十分钟

SlashX 帮你填平搭建到交付的鸿沟 —— 自动获得多端聊天前端、管理后台和积分计费。

免费开始使用预约企业演示

PROTOCOLprotocols/response-v1.md

slashx.response.v1

你返回给 SlashX 的格式

slashx.response.v1 字段详解

这是 HTTP 服务商返回给 SlashX 的格式。本文按代码中的协议定义（provider-protocol-v1.ts）逐字段说明。

schemaVersion 固定为 "slashx.response.v1"。

完整示例

一个覆盖所有字段的完整成功响应（含全部可选字段），下面的字段表可逐项对照。真实场景下大部分字段会缺失，这里为演示协议全貌而全放上：

json

{
  "schemaVersion": "slashx.response.v1",
  "runId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "traceId": "9c858901-8a57-4791-81fe-4c455b099bc9",
  "runStatus": "success",
  "progress": 1,
  "messages": [
    {
      "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
      "role": "assistant",
      "status": "success",
      "delta": false,
      "done": true,
      "content": {
        "text": "支持 7 天无理由退货[1]。下面是退货入口：",
        "images": [
          { "url": "https://cdn.example.com/guide.png", "mimeType": "image/png", "fileName": "退货指引.png", "meta": { "width": 800, "height": 600 } }
        ],
        "videos": [
          { "url": "https://cdn.example.com/demo.mp4", "mimeType": "video/mp4", "fileName": "退货演示.mp4" }
        ],
        "audio": [
          { "url": "https://cdn.example.com/tip.mp3", "mimeType": "audio/mpeg", "fileName": "语音提示.mp3" }
        ],
        "attachments": [
          { "url": "https://cdn.example.com/policy.pdf", "mimeType": "application/pdf", "fileName": "退货政策.pdf", "attachmentType": "document" }
        ],
        "citations": [
          { "index": 1, "title": "退货政策", "url": "https://example.com/policy", "snippet": "自签收起 7 日内…", "meta": { "source": "kb" } }
        ],
        "cards": [
          {
            "type": "product",
            "title": "无线降噪耳机",
            "subtitle": "旗舰款 · 现货",
            "imageUrl": "https://cdn.example.com/headphone.png",
            "fields": [
              { "label": "价格", "value": "￥999" },
              { "label": "库存", "value": "充足" }
            ],
            "actions": [
              { "label": "立即购买", "kind": "open_url", "value": "https://example.com/buy/123" }
            ],
            "meta": { "skuId": "123" }
          }
        ],
        "actions": [
          { "label": "申请退货", "kind": "open_url", "value": "https://example.com/refund", "meta": { "track": "refund_btn" } }
        ]
      },
      "meta": {
        "toolName": "order_lookup",
        "modelUsed": "gpt-4o",
        "thinkingDurationMs": 320,
        "finishReason": "stop"
      }
    }
  ],
  "conversationUpdate": { "title": "退货咨询", "modeTag": "after_sales" },
  "usage": {
    "promptTokens": 220,
    "completionTokens": 48,
    "totalTokens": 268,
    "costUsd": 0.0021,
    "modelUsed": "gpt-4o",
    "latencyMs": 1280
  },
  "nextPoll": { "afterMs": 2000, "url": "https://example.com/poll/run-123" },
  "extensions": { "anyCustomKey": "任意自定义数据" }
}

上面把所有字段都列出来了，仅用于展示协议全貌。error 字段未出现在这里——它只在失败响应（runStatus: "error"）中出现，见下方「场景化响应示例 → 业务失败」。

顶层字段

字段	类型	必填	说明	示例 / 取值
`schemaVersion`	string	必填	固定值	`"slashx.response.v1"`（固定）
`runId`	string(uuid)	可选	同步可省略（沿用请求的 runId）	`"f47ac10b-58cc-4372-a567-0e02b2c3d479"`
`traceId`	string(uuid)	可选	追踪 ID	`"9c858901-8a57-4791-81fe-4c455b099bc9"`
`runStatus`	enum	可选	运行状态，默认 `success`	`"pending"` / `"running"` / `"success"` / `"error"` / `"cancelled"`
`progress`	number	可选	进度，范围 0~1	`1`
`messages`	array	可选	助手消息列表，默认 `[]`	见 messages 小节
`conversationUpdate`	object	可选	更新会话标题/模式标签	`{ "title": "退货咨询", "modeTag": "after_sales" }`
`usage`	object	可选	token 用量（按 token 计费必填）	见 usage 小节
`error`	object	可选	错误详情（`runStatus: error` 时填）	见 error 小节
`nextPoll`	object	可选	异步轮询提示（`afterMs` 必填正整数，`url` 可选）	`{ "afterMs": 2000, "url": "https://..." }`
`extensions`	object	可选	扩展字段，默认 `{}`	`{ "anyCustomKey": "任意数据" }`

异步 Operation 响应

当 Operation Contract 声明 taskSupport: "async" 或 "both" 时，服务商可以先返回：

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "running",
  "progress": 0.05,
  "messages": [],
  "nextPoll": {
    "afterMs": 3000,
    "url": "https://provider.example/tasks/task-123"
  },
  "extensions": {
    "externalRunId": "task-123",
    "cancelUrl": "https://provider.example/tasks/task-123"
  }
}

messages（助手消息）

每条消息：

字段	类型	必填	说明	示例 / 取值
`id`	string	必填	消息 ID（建议用请求的 `runId`）	`"f47ac10b-58cc-4372-a567-0e02b2c3d479"`
`role`	enum	可选	消息角色，默认 `assistant`	`"assistant"` / `"thinking"` / `"tool"` / `"system"` / `"error"`
`status`	enum	可选	消息状态，默认 `success`	`"pending"` / `"streaming"` / `"success"` / `"error"` / `"cancelled"`
`delta`	boolean	可选	是否为增量帧，默认 `false`	`true` / `false`
`done`	boolean	可选	是否为最后一帧，默认 `true`	`true` / `false`
`content`	object	必填	消息内容，见下	见 content 小节
`meta`	object	可选	消息元数据，见下	见 meta 小节

content（消息内容）

字段	类型	必填	说明	示例 / 取值
`text`	string	可选	文本，默认空	`"支持 7 天无理由退货"`
`images`	array	可选	图片（元素 `url` 必填）	见 AssistantMedia
`videos`	array	可选	视频，同 AssistantMedia 结构	见 AssistantMedia
`audio`	array	可选	音频，同 AssistantMedia 结构	见 AssistantMedia
`attachments`	array	可选	附件，额外含 `attachmentType`	见 AssistantMedia（+`attachmentType`）
`citations`	array	可选	引用来源，见下	见 citations 小节
`cards`	array	可选	结构化卡片，见下	见 cards 小节
`actions`	array	可选	快捷操作按钮，见下	见 actions 小节

AssistantMedia（助手返回的媒体）

images / videos / audio / attachments 的元素结构：

字段	必填	说明	示例 / 取值
`url`	必填	资源 URL（响应里必填，不能只给 base64）	`"https://cdn.example.com/out.png"`
`mimeType`	可选	MIME 类型，默认 `application/octet-stream`	`"image/png"` / `"video/mp4"` / `"audio/mpeg"`
`fileName`	可选	文件名，默认空	`"结果.png"`
`meta`	可选	附加元数据	`{ "width": 800 }`
`attachmentType`	可选	仅 `attachments` 有，标注附件类型	`"document"` / `"video"` / `"audio"` / `"image"`（也可自定义）

meta（消息元数据）

字段	类型	必填	说明	示例 / 取值
`toolName`	string	可选	工具名（`role: tool` 时用）	`"order_lookup"`
`modelUsed`	string	可选	实际使用的模型	`"gpt-4o"`
`thinkingDurationMs`	number	可选	思考耗时（毫秒，非负整数）	`320`
`finishReason`	string	可选	结束原因	`"stop"` / `"length"` 等

助手返回的媒体里 url 是必填的（请求里的媒体允许 base64，但响应里建议给可访问 URL）。

citations（引用）

字段	类型	必填	说明	示例 / 取值
`index`	number	可选	角标序号（正整数）	`1`
`title`	string	必填	来源标题	`"退货政策"`
`url`	string	可选	来源链接	`"https://example.com/policy"`
`snippet`	string	可选	原文摘录	`"自签收起 7 日内…"`
`meta`	object	可选	附加元数据	`{ "source": "kb" }`

actions（操作按钮）

字段	类型	必填	说明	示例 / 取值
`label`	string	必填	按钮文字	`"申请退货"`
`kind`	enum	必填	按钮类型	`"send_message"` / `"open_url"` / `"copy"` / `"feedback"` / `"custom"`
`value`	string	必填	按钮值（要发送的文本、要打开的 URL 等）	`"https://example.com/refund"`
`meta`	object	可选	附加元数据	`{ "track": "refund_btn" }`

cards（卡片）

字段	类型	必填	说明	示例 / 取值
`type`	string	必填	卡片类型（自由字符串）	`"product"` / `"order"` 等自定义
`title`	string	可选	标题	`"无线降噪耳机"`
`subtitle`	string	可选	副标题	`"旗舰款 · 现货"`
`imageUrl`	string	可选	卡片图	`"https://cdn.example.com/headphone.png"`
`fields`	array	可选	`{ label, value }` 列表	`[{ "label": "价格", "value": "￥999" }]`
`actions`	array	可选	卡片内按钮（结构同上 actions）	见 actions 小节
`meta`	object	可选	附加元数据	`{ "skuId": "123" }`

usage（用量）

字段	类型	必填	说明	示例 / 取值
`promptTokens`	number	可选	输入 token（非负整数）	`220`
`completionTokens`	number	可选	输出 token（按 token 计费时必填，非负整数）	`48`
`totalTokens`	number	可选	总 token（建议返回，非负整数）	`268`
`costUsd`	number	可选	成本（美元，非负）	`0.0021`
`modelUsed`	string	可选	实际使用的模型	`"gpt-4o"`
`latencyMs`	number	可选	耗时（毫秒，非负整数）	`1280`

如果智能体配置了按 token 计费，请务必分别返回 usage.promptTokens（输入）与 usage.completionTokens（输出），SlashX 按输入/输出单价分别精确计费。仅返回 totalTokens 时会按输出单价对全部 token 计费（偏贵）。

error（错误详情）

字段	类型	必填	说明	示例 / 取值
`code`	string	必填	错误码（自定义字符串）	`"ORDER_NOT_FOUND"`
`message`	string	必填	错误信息	`"找不到该订单"`
`userVisible`	boolean	可选	是否展示给用户，默认 `true`	`true` / `false`
`retryable`	boolean	可选	是否可重试，默认 `false`	`true` / `false`

当 runStatus: "error" 或带 error 时，SlashX 会自动退还本次前置扣费。

场景化响应示例

不同业务场景下，建议这样返回。直接照着改即可。

1. 最简纯文本（最常用）

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    { "id": "m-1", "role": "assistant", "content": { "text": "你好，有什么可以帮你？" } }
  ]
}

2. 按 token 计费：带 usage

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    { "id": "m-1", "role": "assistant", "content": { "text": "已为你查询完成。" } }
  ],
  "usage": { "promptTokens": 120, "completionTokens": 30, "totalTokens": 150, "modelUsed": "gpt-4o" }
}

3. 返回图片

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    {
      "id": "m-1",
      "role": "assistant",
      "content": {
        "text": "这是为你生成的图：",
        "images": [
          { "url": "https://cdn.example.com/out.png", "mimeType": "image/png", "fileName": "结果.png" }
        ]
      }
    }
  ]
}

4. 返回文件附件

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    {
      "id": "m-1",
      "role": "assistant",
      "content": {
        "text": "报表已生成，请下载：",
        "attachments": [
          { "url": "https://cdn.example.com/report.xlsx", "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet", "fileName": "月度报表.xlsx", "attachmentType": "document" }
        ]
      }
    }
  ]
}

5. 带引用来源（知识库 / RAG 场景）

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    {
      "id": "m-1",
      "role": "assistant",
      "content": {
        "text": "根据公司规定，年假为 10 天[1]，可跨年使用[2]。",
        "citations": [
          { "index": 1, "title": "员工手册 v3", "url": "https://example.com/handbook#leave", "snippet": "全职员工每年享有 10 天带薪年假…" },
          { "index": 2, "title": "年假管理细则", "url": "https://example.com/leave-policy", "snippet": "未休年假可顺延至次年 3 月…" }
        ]
      }
    }
  ]
}

6. 带快捷操作按钮

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    {
      "id": "m-1",
      "role": "assistant",
      "content": {
        "text": "我能帮你处理订单，想做什么？",
        "actions": [
          { "label": "查询物流", "kind": "send_message", "value": "查一下我的物流" },
          { "label": "申请退款", "kind": "open_url", "value": "https://example.com/refund" },
          { "label": "复制订单号", "kind": "copy", "value": "NO20260610001" }
        ]
      }
    }
  ]
}

7. 带结构化卡片（商品 / 订单展示）

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    {
      "id": "m-1",
      "role": "assistant",
      "content": {
        "text": "为你找到这款商品：",
        "cards": [
          {
            "type": "product",
            "title": "无线降噪耳机",
            "subtitle": "旗舰款 · 现货",
            "imageUrl": "https://cdn.example.com/headphone.png",
            "fields": [
              { "label": "价格", "value": "￥999" },
              { "label": "库存", "value": "充足" }
            ],
            "actions": [
              { "label": "立即购买", "kind": "open_url", "value": "https://example.com/buy/123" }
            ]
          }
        ]
      }
    }
  ]
}

8. 业务失败（会触发自动退款）

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "error",
  "error": {
    "code": "ORDER_NOT_FOUND",
    "message": "找不到该订单，请确认订单号",
    "userVisible": true,
    "retryable": false
  }
}

9. 更新会话标题

首次对话时可顺便给会话设一个标题（展示在用户的会话列表里）。

json

{
  "schemaVersion": "slashx.response.v1",
  "runStatus": "success",
  "messages": [
    { "id": "m-1", "role": "assistant", "content": { "text": "好的，我们来规划你的三亚行程。" } }
  ],
  "conversationUpdate": { "title": "三亚旅行规划" }
}

容错说明

SlashX 对非标准格式有容错：能从 content.text、或顶层的 output/result/message/text/body 等字段提取文本兜底。所以下面这种最简结构也能识别出文本：

json

{ "text": "直接返回纯文本也行" }

但生产环境强烈建议严格用上面的 slashx.response.v1 结构，否则无法使用多媒体、引用、卡片、按 token 计费（需 usage）等能力。