天马行空天马行空 · 能力交付平台
…

接入文档

天马行空能力调用采用「平台客户令牌 → 业务后端直连能力服务」的调用链：浏览器不持有令牌，凭据只在服务端流转，每次调用由平台实时校验与计费。

调用链路

全部公网能力共用同一套平台令牌体系（tmxk-site）：

  • 凭据发放：登录客户门户，在「令牌」页创建平台客户令牌（opaque 随机串，仅显示一次，可随时吊销）；令牌按所购能力 slug 白名单签发；
  • 令牌校验：每次调用由平台实时查库校验（撤销即时生效），能力服务不本地验签；
  • 能力调用：请求头携带 Authorization: Bearer <平台客户令牌> 直连能力服务，服务间链路透传同一令牌；
  • 计费结算：能力服务按任务量向平台申请冻结并在完成后结算，收支明细见门户「账单」。
step 1 · 创建并配置令牌
# 1) 登录客户门户 →「令牌」页创建平台客户令牌
#    勾选所购能力（files / docs / parse …），secret 仅显示一次，请妥善保管
# 2) 存入业务系统后端环境变量（禁止入库、禁止下发浏览器）
TMXK_SITE_PLATFORM_TOKEN=<平台签发的客户令牌>
step 2 · 调用能力
# 携带 Bearer 直连能力服务（示例：提交文档解析任务）
curl -s -X POST https://tmxk-mineru.cspy.site/api/analysis \
  -H "Authorization: Bearer <平台客户令牌>" \
  -H 'Content-Type: application/json' \
  -d '{ "fileUrl": "https://example.com/合同.pdf" }'

能力清单与元数据

每个能力服务暴露 /.well-known/rs-metadata 声明服务名与能力 scope； 能力实时状态与版本见站点「能力总览」（数据来自平台注册中心实例心跳，无需外部信任根）。

# 能力服务的能力声明（公开，无需鉴权）
curl -s https://tmxk-mineru.cspy.site/.well-known/rs-metadata

环境变量建议（业务系统后端）

TMXK_SITE_PLATFORM_TOKEN=<平台签发的客户令牌>

本地二进制能力包

能力包以二进制包/镜像形式向购买客户交付，固定版本在授权范围内永久使用。 能力包不提供公开下载；下载与授权凭证通过线下安全渠道交付（支持邮件/安全网盘，具体以交付约定为准）。

错误与安全

  • 全部调用由平台实时校验令牌与 scope；缺失/无效令牌 401，scope 未授权 403，积分不足 402（INSUFFICIENT_CREDITS）；
  • 令牌撤销即时生效；secret 仅服务端保存，禁止在浏览器端出现；
  • 冻结积分按实际用量结算：失败全额退回，超冻结上限封顶并记录审计。