快速开始

1. 创建应用

在控制台「应用管理」创建应用，填写名称和描述，勾选需要调用的一个或多个能力。暂不勾选时可以创建，但没有能力调用权限。

创建成功后保存完整 Access Key。详情中默认脱敏，可手动查看和复制；仅保存过哈希的历史密钥不能还原。

2. 管理能力权限

通过应用列表「编辑」调整关联能力，也可以在能力卡片点击「关联应用」。下拉列表中的「已绑定」应用无需重复关联。

调用前应用必须处于已启用状态。取消绑定后，下一次请求会返回无权限；停用应用会拒绝该应用所有后续能力调用。

3. 发起请求

使用平台实际部署域名，并确认目标能力已配置业务上游。以下是服务端 JavaScript 示例，业务请求字段以对应能力文档为准：

const response = await fetch(`${gatewayOrigin}/openapi/v1/?model=education-ocr`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer ' + process.env.THINKWHEEL_ACCESS_KEY,
  },
  body: JSON.stringify(businessInput),
});

const result = await response.text();

平台只需要 access_key，不要求额外的 AppSecret 或签名。JSON API 和 SSE 流式响应 的处理方式见 能力调用。

4. 运行本地 Demo

项目根目录执行：

pnpm demo:gateway

打开 http://127.0.0.1:4100，下拉选择已创建应用和已绑定能力，执行 JSON 或 SSE 调用。浏览器不填写、不接收应用 Key；Demo 服务端从当前数据库读取密钥，请求平台完成鉴权和上游转发。

完整流程及 Java / Node.js 标签示例见从创建应用到首次调用。

5. 上线准备

生产使用 HTTPS，密钥保存于业务服务端；不要写入公开前端代码、URL 日志或仓库。校验目标应用的启用状态、能力绑定、上游连通性和实际业务输入输出，按 错误码 处理拒绝与上游异常。

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