接入文档 · 天马行空能力交付平台

调用链路

能力按应用（计费主体）接入，全部能力共用同一套接入体系（tmxk.site）：

应用接入：平台创建应用，签发 client_id + client_secret（哈希入库、仅签发时展示一次）；
换取票据：后端以 client_credentials 换短期 RS256 应用票据（kind=app，含 aid=appId）；票据到期自动续换；
能力调用：请求头携带 Authorization: Bearer <应用票据> 调用站内能力端点（files / analysis / editor / chat…）；
计费结算：平台按能力自报口径两阶段计费——调用前冻结（authorize），完成后结算（report，失败全额解冻）；收支明细见管理台「计费中心」。

step 1 · 创建应用并换取票据

# 1) 平台「应用接入」创建应用 → 获得 client_id（ak_…）与 client_secret（仅展示一次）
# 2) 后端以 key+secret 换取短期应用票据（RS256 JWT，kind=app；禁止把 secret 下发浏览器）
curl -s -X POST https://tmxk.site/api/oauth/token \
  -H 'Content-Type: application/json' \
  -d '{ "grant_type": "client_credentials", "client_id": "<ak_…>", "client_secret": "<…>" }'
# → { "access_token": "<应用票据>", "token_type": "Bearer", "expires_in": …, "expires_at": … }

step 2 · 调用能力

# 携带 Bearer 调用站内能力端点（示例：提交文档解析任务）
curl -s -X POST https://tmxk.site/api/analysis \
  -H "Authorization: Bearer <应用票据>" \
  -H 'Content-Type: application/json' \
  -d '{ "sourceUrl": "https://example.com/合同.pdf" }'

能力清单与元数据

能力清单、scope 与计费说明以代码能力注册表为事实源（各能力模块 catalog.ts 声明）；运行时可调状态见 GET /api/capabilities/status。

# 能力目录（代码注册表派生，公开，无需鉴权）
curl -s https://tmxk.site/api/capabilities/status

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

TMXK_APP_KEY=ak_…
TMXK_APP_SECRET=<仅服务端保存>

错误与安全

票据缺失/无效 401，scope/应用未授权 403，积分不足 402（INSUFFICIENT_CREDITS），计费主体校验失败 409；
应用停用/secret 轮换即时生效；secret 只允许在服务端保存，禁止入库到前端或下发浏览器；
冻结积分按实际用量结算：失败全额退回，超冻结上限封顶并记录审计。