mcpField
U
use-llm-gateway

use-llm-gateway

github.com/xgent-aiDevelopment172 installsUpdated today
Repository

About use-llm-gateway

use-llm-gateway is a skill for integrating an LLM gateway into an app’s existing workflows. It covers authentication, native requests, task recovery, and media handling, while requiring the target environment and gateway version to be verified.

Key features

  1. 01Select credentials and models
  2. 02Send native gateway requests
  3. 03Persist call keys and task links
  4. 04Recover timed-out or uncertain tasks
  5. 05Archive media before acknowledgment
  6. 06Limit automatic retries

Use cases

  1. 01Connect an app workflow to the gateway
  2. 02Resume a task after a timeout
  3. 03Safely handle media generation results

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/xgent-ai/skills --skill use-llm-gateway

After installing, type/use-llm-gatewayin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

agents/
openai.yaml
references/
api.md
recovery.md

Details

From the project README

use-llm-gateway

把模型调用接进调用方已有的业务流程：选对模型与凭证，发送原生请求，保存调用键和任务关联，正确处理未知结果与产物回收。本包面向统一 /v1 版本；源码或本 skill 的存在不证明目标环境已经升级。

先确定调用方上下文

读取当前 App 的 HTTP/SDK 封装、配置、manifest、鉴权与业务 job/run/attempt 模型。复用其语言、客户端和配置约定，不要求克隆门户源码或新建一套任务系统。

先确定实际网关服务根地址、租户、可用凭证、所需能力和目标环境版本。缺部署资料时可先完成可配置的客户端与本地契约测试；真实联调前再索取缺项，不猜生产地址、模型或凭证，也不因新接口404静默回退旧调用面。

当前工作按需读取
签服务令牌、选模型、构造请求、解析成功体references/api.md
幂等、丢回包、超时、任务查询/取消/ACK、计费判定references/recovery.md
从旧媒体、推理、审核或服务调用台账迁移references/recovery.md 的迁移对照

实现调用读取第一份；涉及非流式生成、后台任务、重试或迁移时同时读取第二份。普通文本调用不必加载全部媒体细节。

两种凭证，一张调用面

身份公共调用方式
API Key：xuak_ 或仍有效的 xgw_Authorization: Bearer <key>；按这把 Key 隔离
绑定调用 App 的服务令牌同一 Bearer 头；票为 kind=service 且有非空 azp，按 App 隔离
用户 TDT，包括用户 Token Exchange 产物不能调用公共 /v1，返回401；不能因用户点击了生成就把用户票直接传给网关

用户触发的 App 后端生成仍须先验证本 App 的用户/租户/业务权限，再使用已授权的 API Key 或 App 服务令牌。X-Actor-User-Id 可记录已验证的发起用户，但不授予权限；鉴权失败不自动切换到更宽身份。

GET 使用 llm_gateway.read，生成POST、取消、ACK、封存及DELETE使用 llm_gateway.write。API Key 的网关write资格兼具读；服务令牌按实际scope校验。不要把SA密钥或共享API Key打进前端bundle。

协议分界：/v1/* 返回原生JSON、字节或SSE，失败用真实HTTP状态；GET /api/v1/models 仍是带TDT的管理信封 {ok,data}。公共调用直接使用服务端HTTP/适配的SDK，不经过门户iframe的 callService / postMessage代理。

实施时保留这些事实

  1. 先保存执行意图，再提交。 对需要恢复的非流式调用，在业务attempt中持久化凭证主体、逻辑模型、不可变请求及 Idempotency-Key。同一意图重传保持原键、原内容、标记与策略；新的一次业务执行才用新键。流式调用不能带键。
  2. HTTP成功不等于业务完成。 202是任务受理；语音成功可能直接是音频字节；审核的review/unsupported不是放行。先按状态和Content-Type分派，再解析对应成功体，不能统一取 response.data.data。
  3. 超时后恢复原调用。 保存成功头 X-Gateway-Task-Id、202的id，或错误的 details.taskId。504 TASK_RUNNING后查同一任务，不再POST生成。仅有键时先回读 /v1/calls；没有免费终局证据时不自动换键重做。
  4. 资源归属不随token字符串猜测。 查询、下载、取消和ACK使用同租户、同主体。同App的新服务令牌可续查；另一把API Key或另一App不能读旧资源，不能靠actor、标记或taskId跨主体恢复。
  5. 媒体先归档再ACK。 用返回的 asset_key 取网关自持字节，校验并可靠写入调用方存储后再ACK。/v1/... 资源路径相对网关服务根目录，拼接时保留 /svc/llm-gateway 前缀；不能直接当公开图片地址，也不向供应商地址转发网关Bearer。
  6. 限制自动重试。 尊重 x-should-retry:false；接管SDK对写请求的默认重试，避免HTTP状态触发重复付费。后台查询可有退避与观察期限；期限到达保留可恢复关联，停止本轮等待，不制造新的生成。

验证与交付

按改动覆盖实际行为：所用能力成功与原生错误、用户票拒绝、跨主体拒绝、同键重放/不同请求冲突、丢回包恢复；媒体补充202、504同任务恢复、查询失败重试、终态失败/取消、下载后ACK与410。若接入审核，验证不可用或不支持时不会当作allow。

本地HTTP fixture可验证调用方行为；真实联调只在任务授权的环境和费用范围内进行。没有凭证或目标版本未升级时，明确未验证部分，不把mock成功写成供应商实测，也不为完成接入擅自部署网关、改门户授权或切换旧接口。

交付当前App的代码/配置与实际验证结果，说明仍需的平台安装、scope、模型或版本条件。纯查询时解释接线即可，不强制落文档、执行调用或改基础设施。

契约维护依据

本包按门户调用面统一实现 17104d5e 核对，可整目录导出给其他App。若可访问该版本源码，维护线索是 docs/llm-gateway-service-calls.md、docs/llm-gateway-models-contract.md、docs/内容安全审核接入指引.md 以及 apps/llm-gateway-server/src/{lib/caller.ts,routes/gateway-ext.ts,routes/generation.ts}；这些不是使用本包的运行依赖。目标部署的实际版本和能力需单独确认。

Comments

Markdown supported