能力调用

Endpoint

/openapi/v1/?model={model}

model 查询参数选择平台能力，调用方无需提供上游路径或模型标识。平台根据能力的内部配置拼接请求路径；业务输入按该能力约定提交。

model 必须非空且只传一次，重复或空值返回 400，不存在的能力返回 404。兼容旧格式 /openapi/v1/{model}/{path}；只有未传 model 时才从路径解析能力。新格式下路径全部作为业务路径，不再包含能力前缀。

实际输入输出和可用协议由配置的上游能力决定；未配置上游时返回 503。

请求与响应

HTTP 请求必须携带 Authorization: Bearer <Access Key> 头。平台先校验应用身份、状态及能力权限，再转发原始方法、业务查询参数、请求体和内容类型。JSON 请求体不经过平台业务包装；配置了上游模型时，平台注入模型字段，此类请求限 1MB。

上游 HTTP 状态及响应体原样返回；SSE 和分块内容实时转发，不会等完整结果再输出。平台自身鉴权失败返回 { code, msg, data }，上游返回结果不强制采用此格式。

转发前移除 model 查询参数。上游路径和模型标识由平台内部配置；对于配置了上游模型的能力，平台将该模型写入 JSON 请求体，覆盖客户端同名字段，客户端无需传入该字段。转发不携带平台密钥、客户端 Cookie/Authorization 或逐跳头；上游凭证由服务端配置。上游 Set-Cookie 不返回给客户端，响应禁用缓存。不自动重试请求或追随重定向。

服务端统一封装

配置一次域名和 Key，各业务位置通过参数选择能力。示例返回原始 Response，由调用方决定读取 JSON、错误文本还是 SSE 流；不自动重试业务请求：

const createCapabilityClient = ({ baseUrl, accessKey }) => ({
  invoke({ model, path = '', query = {}, ...init }) {
    const url = new URL(`/openapi/v1/${path.replace(/^\/+/, '')}`, baseUrl);
    url.search = new URLSearchParams(query).toString();
    url.searchParams.set('model', model);
    const headers = new Headers(init.headers);
    headers.set('Authorization', 'Bearer ' + accessKey);
    return fetch(url, { ...init, headers });
  },
});

const client = createCapabilityClient({
  baseUrl: gatewayOrigin,
  accessKey: process.env.THINKWHEEL_ACCESS_KEY,
});

const response = await client.invoke({
  model: 'education-ocr',
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(businessInput),
  signal: abortController.signal,
});

if (!response.ok) throw new Error(`调用失败：${response.status}`);
const result = await response.json();

调用批改时只需将 model 改为 composition-correction，并按批改文档传业务数据。

流式读取

统一方法不会缓冲响应。向实际支持流式输出的业务接口发起请求后，可以读取原始数据块：

for await (const chunk of response.body) {
  consumeChunk(chunk);
}

同一个响应体只能读取一次；流式调用不要先调用 response.json()。流式路径或请求体中的 stream 字段以具体上游文档为准，网关不定义统一的业务字段。

HTTP 等待上游响应头超时为 30 秒，空闲超时为 120 秒；有持续数据的流可继续。客户端中断后，网关关闭上游请求。若流已开始后发生上游异常，连接将断开，不会向原始数据流插入错误 JSON。

本地 Demo

在项目根目录运行 pnpm demo:gateway，打开 http://127.0.0.1:4100。可交互验证能力授权、401/403、普通 JSON 和 SSE；平台统一验证应用 Key、状态和能力权限，业务上游来自数据库中的真实配置。能力关联及启停统一在控制台管理。

完整操作及 Java / Node.js 示例见从创建应用到首次调用。

Demo 调用需要先启动 pnpm dev:server-api。Demo 服务端只负责读取应用凭证并通过 HTTP 请求平台，权限校验、上游转发、统计及失败采集统一由 server-api 完成。平台地址默认 http://127.0.0.1:4000，可用 DEMO_PLATFORM_URL 调整。